pub mod governor;
pub mod handlers;
pub mod port_file;
pub mod router;
pub mod server;
pub use governor::RequestGovernor;
pub use server::spawn_sidecar;
use parking_lot::{Mutex, RwLock};
use std::collections::HashMap;
use std::path::PathBuf;
use std::sync::Arc;
use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
use serde::Serialize;
pub struct SidecarHandle {
pub port: u16,
pub shutdown_tx: tokio::sync::oneshot::Sender<()>,
pub server_join: tokio::task::JoinHandle<()>,
pub token_stats: Arc<TokenStats>,
}
impl SidecarHandle {
pub async fn shutdown_and_join(self) {
let _ = self.shutdown_tx.send(());
let _ = self.server_join.await;
}
}
#[derive(Debug, Clone, Serialize)]
pub struct StatsSnapshot {
pub read_fires: usize,
pub read_saved_tokens: u64,
pub edit_fires: usize,
pub edit_saved_tokens: u64,
pub write_fires: usize,
pub grep_fires: usize,
pub grep_saved_tokens: u64,
}
pub struct TokenStats {
pub read_fires: AtomicUsize,
pub read_saved_tokens: AtomicU64,
pub edit_fires: AtomicUsize,
pub edit_saved_tokens: AtomicU64,
pub write_fires: AtomicUsize,
pub grep_fires: AtomicUsize,
pub grep_saved_tokens: AtomicU64,
pub tool_calls: Mutex<HashMap<String, usize>>,
pub tool_token_details: Mutex<HashMap<String, (u64, u64)>>,
pub total_tokens_served: AtomicU64,
pub total_tokens_naive: AtomicU64,
}
impl TokenStats {
pub fn new() -> Arc<Self> {
Arc::new(Self {
read_fires: AtomicUsize::new(0),
read_saved_tokens: AtomicU64::new(0),
edit_fires: AtomicUsize::new(0),
edit_saved_tokens: AtomicU64::new(0),
write_fires: AtomicUsize::new(0),
grep_fires: AtomicUsize::new(0),
grep_saved_tokens: AtomicU64::new(0),
tool_calls: Mutex::new(HashMap::new()),
tool_token_details: Mutex::new(HashMap::new()),
total_tokens_served: AtomicU64::new(0),
total_tokens_naive: AtomicU64::new(0),
})
}
pub fn record_read(&self, file_bytes: u64, output_bytes: u64) {
self.read_fires.fetch_add(1, Ordering::Relaxed);
let saved = crate::protocol::format::saved_tokens_vs_competent_manual(
output_bytes as usize,
file_bytes as usize,
);
self.read_saved_tokens.fetch_add(saved, Ordering::Relaxed);
}
pub fn record_edit(&self, file_bytes: u64, output_bytes: u64) {
self.edit_fires.fetch_add(1, Ordering::Relaxed);
let saved = crate::protocol::format::saved_tokens_vs_competent_manual(
output_bytes as usize,
file_bytes as usize,
);
self.edit_saved_tokens.fetch_add(saved, Ordering::Relaxed);
}
pub fn record_write(&self) {
self.write_fires.fetch_add(1, Ordering::Relaxed);
}
pub fn record_grep(&self, _file_bytes: u64, output_bytes: u64) {
self.grep_fires.fetch_add(1, Ordering::Relaxed);
let baseline_chars =
crate::protocol::format::estimate_listing_baseline_chars(output_bytes as usize)
.max(output_bytes as usize);
let saved = crate::protocol::format::saved_tokens_vs_competent_manual(
output_bytes as usize,
baseline_chars,
);
self.grep_saved_tokens.fetch_add(saved, Ordering::Relaxed);
}
pub fn record_tool_call(&self, name: &str) {
let mut map = self.tool_calls.lock();
*map.entry(name.to_string()).or_insert(0) += 1;
}
pub fn record_tool_tokens(&self, tool_name: &str, tokens_served: u64, tokens_saved: u64) {
let mut map = self.tool_token_details.lock();
let entry = map.entry(tool_name.to_string()).or_insert((0, 0));
entry.0 += tokens_served;
entry.1 += tokens_saved;
self.total_tokens_served
.fetch_add(tokens_served, Ordering::Relaxed);
self.total_tokens_naive
.fetch_add(tokens_served + tokens_saved, Ordering::Relaxed);
}
pub fn tool_token_details(&self) -> Vec<(String, u64, u64)> {
let map = self.tool_token_details.lock();
let mut details: Vec<(String, u64, u64)> = map
.iter()
.map(|(k, (served, saved))| (k.clone(), *served, *saved))
.collect();
details.sort_by(|a, b| b.2.cmp(&a.2).then_with(|| a.0.cmp(&b.0)));
details
}
pub fn tool_call_counts(&self) -> Vec<(String, usize)> {
let map = self.tool_calls.lock();
let mut counts: Vec<(String, usize)> = map.iter().map(|(k, v)| (k.clone(), *v)).collect();
counts.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0)));
counts
}
pub fn summary(&self) -> StatsSnapshot {
StatsSnapshot {
read_fires: self.read_fires.load(Ordering::Relaxed),
read_saved_tokens: self.read_saved_tokens.load(Ordering::Relaxed),
edit_fires: self.edit_fires.load(Ordering::Relaxed),
edit_saved_tokens: self.edit_saved_tokens.load(Ordering::Relaxed),
write_fires: self.write_fires.load(Ordering::Relaxed),
grep_fires: self.grep_fires.load(Ordering::Relaxed),
grep_saved_tokens: self.grep_saved_tokens.load(Ordering::Relaxed),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SymbolSnapshot {
pub name: String,
pub kind: String,
pub line_range: (u32, u32),
pub byte_range: (u32, u32),
}
pub type SymbolSnapshotCache = HashMap<String, Vec<SymbolSnapshot>>;
#[derive(Clone)]
pub struct SidecarState {
pub index: crate::live_index::index_lifecycle::activation::ProjectRuntimeHandle,
pub token_stats: Arc<TokenStats>,
pub repo_root: Option<PathBuf>,
pub symbol_cache: Arc<RwLock<SymbolSnapshotCache>>,
}
pub fn build_with_budget(items: &[String], max_bytes: u64) -> (String, usize) {
crate::index_lifecycle::guidance::read_context::build_with_budget(items, max_bytes)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_token_stats_new_all_zeros() {
let stats = TokenStats::new();
let snap = stats.summary();
assert_eq!(snap.read_fires, 0);
assert_eq!(snap.read_saved_tokens, 0);
assert_eq!(snap.edit_fires, 0);
assert_eq!(snap.edit_saved_tokens, 0);
assert_eq!(snap.write_fires, 0);
assert_eq!(snap.grep_fires, 0);
assert_eq!(snap.grep_saved_tokens, 0);
}
#[test]
fn test_token_stats_record_read() {
let stats = TokenStats::new();
stats.record_read(1000, 200);
let snap = stats.summary();
assert_eq!(snap.read_fires, 1);
assert_eq!(snap.read_saved_tokens, 200);
}
#[test]
fn test_token_stats_record_edit() {
let stats = TokenStats::new();
stats.record_edit(800, 300);
let snap = stats.summary();
assert_eq!(snap.edit_fires, 1);
assert_eq!(snap.edit_saved_tokens, 125);
}
#[test]
fn test_token_stats_record_write_no_savings() {
let stats = TokenStats::new();
stats.record_write();
let snap = stats.summary();
assert_eq!(snap.write_fires, 1);
}
#[test]
fn test_token_stats_record_grep() {
let stats = TokenStats::new();
stats.record_grep(2000, 100);
let snap = stats.summary();
assert_eq!(snap.grep_fires, 1);
let expected = crate::protocol::format::saved_tokens_vs_competent_manual(
100,
crate::protocol::format::estimate_listing_baseline_chars(100),
);
assert_eq!(snap.grep_saved_tokens, expected);
}
#[test]
fn test_token_stats_records_tool_calls() {
let stats = TokenStats::new();
stats.record_tool_call("search_text");
stats.record_tool_call("search_text");
stats.record_tool_call("get_file_context");
let counts = stats.tool_call_counts();
assert_eq!(counts[0], ("search_text".to_string(), 2));
assert_eq!(counts[1], ("get_file_context".to_string(), 1));
assert_eq!(counts.len(), 2);
}
#[test]
fn test_token_stats_saturating_sub_no_underflow() {
let stats = TokenStats::new();
stats.record_read(100, 500);
let snap = stats.summary();
assert_eq!(
snap.read_saved_tokens, 0,
"saturating_sub prevents underflow"
);
}
#[test]
fn test_token_stats_accumulates_multiple_fires() {
let stats = TokenStats::new();
stats.record_read(1000, 200);
stats.record_read(800, 400);
let snap = stats.summary();
assert_eq!(snap.read_fires, 2);
assert_eq!(snap.read_saved_tokens, 300);
}
#[test]
fn test_build_with_budget_no_truncation_when_fits() {
let items: Vec<String> = vec![
"line1".to_string(),
"line2".to_string(),
"line3".to_string(),
];
let (text, remaining) = build_with_budget(&items, 1000);
assert_eq!(text, "line1\nline2\nline3");
assert_eq!(remaining, 0, "no truncation when all items fit");
}
#[test]
fn test_build_with_budget_truncates_at_logical_boundary() {
let items: Vec<String> = vec![
"line1".to_string(),
"line2".to_string(),
"line3".to_string(),
];
let (text, remaining) = build_with_budget(&items, 12);
assert!(text.contains("line1"), "line1 should be included");
assert!(text.contains("line2"), "line2 should be included");
assert!(text.contains("truncated"), "should have truncation suffix");
assert_eq!(remaining, 1, "1 item was truncated");
}
#[test]
fn test_build_with_budget_zero_means_unlimited() {
let items: Vec<String> = vec!["a".to_string(), "b".to_string(), "c".to_string()];
let (text, remaining) = build_with_budget(&items, 0);
assert_eq!(text, "a\nb\nc");
assert_eq!(remaining, 0);
}
#[test]
fn test_build_with_budget_empty_items() {
let items: Vec<String> = vec![];
let (text, remaining) = build_with_budget(&items, 100);
assert_eq!(text, "");
assert_eq!(remaining, 0);
}
#[test]
fn test_build_with_budget_truncation_suffix_format() {
let items: Vec<String> = vec![
"line1".to_string(),
"line2".to_string(),
"line3".to_string(),
"line4".to_string(),
];
let (text, remaining) = build_with_budget(&items, 12);
assert!(
text.ends_with(
"[truncated] Truncated at ~3 tokens. 2 additional output line(s) not shown."
),
"suffix should use canonical truncation marker and mention 2 remaining items, got: {text}"
);
assert_eq!(remaining, 2);
}
#[test]
fn test_sidecar_state_constructs() {
use crate::live_index::store::{CircuitBreakerState, LiveIndex};
use parking_lot::RwLock;
use std::collections::HashMap;
use std::sync::Arc;
use std::time::{Duration, Instant, SystemTime};
let index = crate::live_index::SharedIndexHandle::shared(LiveIndex {
files: HashMap::new(),
loaded_at: Instant::now(),
loaded_at_system: SystemTime::now(),
load_duration: Duration::ZERO,
cb_state: CircuitBreakerState::new(0.20),
is_empty: true,
load_source: crate::live_index::store::IndexLoadSource::EmptyBootstrap,
snapshot_verify_state: crate::live_index::store::SnapshotVerifyState::NotNeeded,
reverse_index: HashMap::new(),
files_by_basename: HashMap::new(),
files_by_dir_component: HashMap::new(),
trigram_index: crate::live_index::trigram::TrigramIndex::new(),
gitignore: None,
manifest_entries: Vec::new(),
coupling_store: None,
local_empty_reason: std::sync::Arc::new(parking_lot::RwLock::new(None)),
indexed_root: None,
});
let state = SidecarState {
index: crate::live_index::index_lifecycle::activation::ProjectRuntimeHandle::bind(
index,
),
token_stats: TokenStats::new(),
repo_root: None,
symbol_cache: Arc::new(RwLock::new(HashMap::new())),
};
let _cloned = state.clone();
}
}