feat: add token budget circuit breaker and session log to agent loop (#245)

**Key Changes:**

- Introduced token budget circuit breaker to halt agent loop when
cumulative input/output token limits are exceeded
- Added append-only JSONL session log for crash recovery and debugging
- Enhanced context compaction with proactive and reactive trimming and
semantic recap
- Exposed new configuration options for budget, logging, and prompt
cache through environment variables

**Added:**

- Token budget enforcement (`BudgetConfig`) that ends loops with
`BudgetExceeded` reason when input, output, or total token budgets are
reached; configurable via env vars
- Append-only JSONL session log (`SessionLog` and `SessionLogConfig`)
that records all conversation events, tool results, usage stats, and
outcomes for each agent loop in a crash-tolerant manner
- Proactive context compaction logic, including semantic recap of
trimmed messages, with configurability for compaction cadence and
thresholds
- New public exports for session logging and budget configs in agent
loop modules and library root

**Changed:**

- Agent loop runner now checks token budgets each iteration and exits
early if limits are exceeded
- Context compaction upgraded to support both proactive
(threshold-based) and reactive (hard ceiling) trimming, with detailed
logging and semantic recaps of dropped content
- Anthropic provider now attaches prompt-cache breakpoints to
system/tool blocks when enabled, improving cache hit rates and
efficiency
- Configuration loading for agent loop now layers environment variable
overrides on top of defaults for agent, context, budget, and session log
settings
- All agent loop terminal paths (success, error, budget, assistance) now
consistently log outcomes to the session log if enabled

**Removed:**

- Previous static context trimming that lacked proactive compaction and
semantic recaps
- Unused or redundant context compaction code paths in favor of unified
`maybe_compact` and semantic recap mechanism

Author: l50

Cargo.lock

@@ -145,6 +145,9 @@ impl BlueCallbackHandler {
                 format!("Sub-agent hit max steps ({} steps)", outcome.steps)
             }
             ares_llm::LoopEndReason::MaxTokens => "Sub-agent hit max tokens".to_string(),
+            ares_llm::LoopEndReason::BudgetExceeded { reason } => {
+                format!("Sub-agent budget exceeded: {reason}")
+            }
             ares_llm::LoopEndReason::Error(e) => format!("Sub-agent error: {e}"),
         };
 

ares-cli/src/orchestrator/blue/callbacks.rs

@@ -425,6 +425,9 @@ fn process_outcome(outcome: &AgentLoopOutcome, investigation_id: &str) -> Invest
         LoopEndReason::MaxTokens => InvestigationOutcome::Failed {
             error: format!("Investigation {investigation_id} hit max tokens"),
         },
+        LoopEndReason::BudgetExceeded { reason } => InvestigationOutcome::Failed {
+            error: format!("Investigation {investigation_id} budget exceeded: {reason}"),
+        },
         LoopEndReason::Error(err) => InvestigationOutcome::Failed { error: err.clone() },
     }
 }

ares-cli/src/orchestrator/blue/investigation.rs

@@ -399,6 +399,28 @@ impl Dispatcher {
                                 agent_name: Some(tt.clone()),
                             }
                         }
+                        LoopEndReason::BudgetExceeded { reason } => {
+                            let mut result_json = json!({
+                                "steps": outcome.steps,
+                                "tool_calls": outcome.tool_calls_dispatched,
+                            });
+                            if let Some(disc) = merged_discoveries {
+                                result_json["discoveries"] = disc;
+                            }
+                            if !tool_outputs_json.is_empty() {
+                                result_json["tool_outputs"] =
+                                    Value::Array(tool_outputs_json.clone());
+                            }
+                            TaskResult {
+                                task_id: tid.clone(),
+                                success: false,
+                                result: Some(result_json),
+                                error: Some(format!("Budget exceeded: {reason}")),
+                                completed_at: Some(Utc::now()),
+                                worker_pod: Some("rust-llm-runner".into()),
+                                agent_name: Some(tt.clone()),
+                            }
+                        }
                         LoopEndReason::Error(err) => TaskResult {
                             task_id: tid.clone(),
                             success: false,

ares-cli/src/orchestrator/dispatcher/submission.rs

@@ -45,11 +45,10 @@ impl LlmTaskRunner {
         temperature: Option<f32>,
         technique_priorities: Vec<(String, i32)>,
     ) -> Self {
-        let config = AgentLoopConfig {
-            model: model_name,
-            temperature,
-            ..AgentLoopConfig::default()
-        };
+        // Layer env-var overrides (ARES_AGENT_*, ARES_CONTEXT_*, ARES_BUDGET_*,
+        // ARES_SESSION_LOG_*) on top of compiled defaults so operators can
+        // tune the loop without a code change.
+        let config = AgentLoopConfig::from_env(model_name, temperature);
         Self {
             provider,
             dispatcher,
@@ -287,6 +286,13 @@ fn log_outcome(task_id: &str, outcome: &AgentLoopOutcome) {
                 "LLM agent hit max tokens"
             );
         }
+        LoopEndReason::BudgetExceeded { reason } => {
+            warn!(
+                task_id = task_id,
+                steps = outcome.steps,
+                "LLM agent budget circuit breaker tripped: {reason}"
+            );
+        }
         LoopEndReason::Error(err) => {
             warn!(
                 task_id = task_id,

ares-cli/src/orchestrator/llm_runner.rs

@@ -282,6 +282,12 @@ async fn execute_blue_task(
             "Hit max tokens".into(),
             agent_name,
         ),
+        LoopEndReason::BudgetExceeded { reason } => BlueTaskResult::failure(
+            &task.task_id,
+            &task.investigation_id,
+            format!("Budget exceeded: {reason}"),
+            agent_name,
+        ),
         LoopEndReason::Error(err) => {
             error!(task_id = %task.task_id, err = %err, "Blue task error");
             BlueTaskResult::failure(

ares-cli/src/worker/blue_task_loop.rs

@@ -27,3 +27,4 @@ blue = []
 tokio = { workspace = true }
 serde_json = { workspace = true }
 async-trait = "0.1"
+tempfile = "3"

ares-llm/Cargo.toml

@@ -164,6 +164,7 @@ async fn main() -> Result<()> {
         retry: RetryConfig::default(),
         context: ContextConfig::default(),
         max_tool_calls_per_name: 10,
+        ..AgentLoopConfig::default()
     };
 
     let outcome = run_agent_loop(