Skip to main content

pixie_pi/
session.rs

1//! Agent session: holds the live transcript, model, tools, and credentials,
2//! drives the agent loop, and persists the transcript as JSONL.
3
4use std::path::{Path, PathBuf};
5use std::sync::Arc;
6
7use serde_json::Value;
8use tokio_util::sync::CancellationToken;
9
10use crate::agent::agent_loop::{agent_loop, AgentEventStream, AgentLoopConfig};
11use crate::agent::context::AgentContext;
12use crate::agent::tool::{AgentTool, ExecutionMode, ToolGate, allow_all_gate};
13use crate::ai::anthropic::{stream_simple, LlmContext, SimpleStreamOptions};
14use crate::ai::stream::{AssistantMessageEvent, AssistantStream};
15use crate::ai::types::{Message, Model, ThinkingLevel, Usage, UserBlock, UserMessage};
16use futures::StreamExt;
17
18/// Rough characters-per-token estimate for budgeting/compaction.
19const CHARS_PER_TOKEN: usize = 4;
20
21pub struct AgentSession {
22    pub cwd: PathBuf,
23    pub messages: Vec<Message>,
24    pub system_prompt: String,
25    pub model: Model,
26    pub thinking: ThinkingLevel,
27    pub tools: Vec<Arc<dyn AgentTool>>,
28    pub client: reqwest::Client,
29    pub gate: Arc<dyn ToolGate>,
30    pub api_key: Option<String>,
31    pub auth_token: Option<String>,
32    pub session_file: Option<PathBuf>,
33    pub total_usage: Usage,
34    /// Override the model's default output-token cap, if set.
35    pub max_tokens: Option<usize>,
36    /// Attach Anthropic prompt-caching markers. Default true (`--no-cache` flips it).
37    pub cache_control: bool,
38    /// Override the model used for background compaction summaries. `None`
39    /// (default) resolves via [`Self::default_compact_model`] — the cheapest
40    /// tier (haiku), or `PIXIE_PI_COMPACT_MODEL`. Pinned per-session in tests.
41    pub compact_model: Option<Model>,
42}
43
44impl AgentSession {
45    /// Construct a session from its core parts, with sensible defaults for
46    /// token caps, caching, the allow-all gate, and an empty transcript.
47    pub fn new(
48        cwd: PathBuf,
49        system_prompt: String,
50        model: Model,
51        thinking: ThinkingLevel,
52        tools: Vec<Arc<dyn AgentTool>>,
53        client: reqwest::Client,
54    ) -> Self {
55        Self {
56            cwd,
57            messages: Vec::new(),
58            system_prompt,
59            model,
60            thinking,
61            tools,
62            client,
63            gate: default_gate(),
64            api_key: None,
65            auth_token: None,
66            session_file: None,
67            total_usage: Usage::default(),
68            max_tokens: None,
69            cache_control: true,
70            compact_model: None,
71        }
72    }
73
74    /// Build the streaming options for the current model + thinking level.
75    pub fn stream_options(&self) -> SimpleStreamOptions {
76        SimpleStreamOptions {
77            api_key: self.api_key.clone(),
78            auth_token: self.auth_token.clone(),
79            max_tokens: self.max_tokens,
80            temperature: None,
81            reasoning: if self.model.reasoning {
82                Some(self.thinking)
83            } else {
84                None
85            },
86            thinking_budget_tokens: None,
87            cache_control: self.cache_control,
88            timeout_ms: None,
89        }
90    }
91
92    /// Start an agent run for the given prompt messages.
93    pub fn run(&self, prompts: Vec<Message>, cancel: CancellationToken) -> AgentEventStream {
94        let ctx = AgentContext {
95            system_prompt: self.system_prompt.clone(),
96            messages: self.messages.clone(),
97            tools: self.tools.clone(),
98        };
99        let config = AgentLoopConfig {
100            client: self.client.clone(),
101            model: self.model.clone(),
102            options: self.stream_options(),
103            tool_execution: ExecutionMode::Parallel,
104            gate: Some(self.gate.clone()),
105        };
106        agent_loop(ctx, config, prompts, cancel)
107    }
108
109    /// Estimated token count of the current transcript.
110    pub fn estimated_tokens(&self) -> usize {
111        estimate_tokens(&self.messages)
112    }
113
114    /// Token-budget fraction used (0.0–1.0+).
115    pub fn context_usage(&self) -> f64 {
116        self.estimated_tokens() as f64 / self.model.context_window.max(1) as f64
117    }
118
119    /// Compaction budget: ~80% of the context window.
120    fn compaction_budget(&self) -> usize {
121        (self.model.context_window as f64 * 0.8) as usize
122    }
123
124    /// Resolve the model for background compaction summaries (model tiering):
125    /// a per-session override, then the `PIXIE_PI_COMPACT_MODEL` env var, then the
126    /// cheapest tier (haiku) for cost, finally the session's main model. Using a
127    /// cheap tier for summaries keeps long sessions inexpensive regardless of
128    /// the (possibly opus-tier) main model.
129    fn default_compact_model(&self) -> Model {
130        let registry = crate::ai::builtin_models();
131        if let Ok(pattern) = std::env::var("PIXIE_PI_COMPACT_MODEL") {
132            let pattern = pattern.trim();
133            if !pattern.is_empty() {
134                if let Some(m) = crate::ai::resolve_model(&registry, pattern) {
135                    return m;
136                }
137            }
138        }
139        registry
140            .iter()
141            .find(|m| m.id.contains("haiku"))
142            .cloned()
143            .unwrap_or_else(|| self.model.clone())
144    }
145
146    /// True when the transcript exceeds the compaction budget.
147    pub fn should_compact(&self) -> bool {
148        self.estimated_tokens() > self.compaction_budget()
149    }
150
151    /// Index of the first message to KEEP after compaction. We only cut at a
152    /// plain user-message boundary, so the remaining transcript still starts
153    /// with a user turn and no tool_use ↔ tool_result pair is severed — keeping
154    /// it valid for the Anthropic API. Returns 0 when nothing need be dropped.
155    fn compaction_cut(&self) -> usize {
156        let budget = self.compaction_budget();
157        let mut cut = 0;
158        loop {
159            let remaining = &self.messages[cut..];
160            if remaining.len() <= 4 || estimate_tokens(remaining) <= budget {
161                break;
162            }
163            // Next user boundary within `remaining` (skip index 0 — cutting there
164            // would drop everything). `rel` is relative to `remaining[1..]`.
165            match remaining[1..]
166                .iter()
167                .position(|m| matches!(m, Message::User(_)))
168            {
169                Some(rel) => cut += rel + 1,
170                None => break, // No safe boundary; stop rather than corrupt.
171            }
172        }
173        cut
174    }
175
176    /// Summarize a dropped prefix of the transcript via the model. Returns
177    /// `None` on any failure (or empty result) so the caller always has a clean
178    /// fallback. Uses a short, no-thinking, no-cache, time-boxed request — a
179    /// summary must never hang or bankrupt the turn it runs in.
180    async fn summarize(&self, messages: &[Message]) -> Option<String> {
181        if messages.is_empty() {
182            return None;
183        }
184        let transcript = transcript_for_summary(messages);
185        if transcript.trim().is_empty() {
186            return None;
187        }
188        let prompt = format!(
189            "You are compacting a coding-agent conversation to save context. Summarize everything \
190             below, preserving: the user's original goal and constraints; key decisions and their \
191             rationale; every file read or modified and what was done to it; important findings, \
192             errors, and their resolution; and any open problems or planned next steps. Be concise \
193             and factual — this summary replaces the earlier messages, so include anything the \
194             agent still needs to continue. No preamble or commentary.\n\n--- BEGIN TRANSCRIPT ---\n\
195             {transcript}\n--- END TRANSCRIPT ---"
196        );
197        let user = vec![Message::User(UserMessage::text(prompt))];
198        let tools: Vec<crate::ai::types::ToolSchema> = Vec::new();
199        let llm = LlmContext {
200            system_prompt: Some("You compact agent conversation transcripts."),
201            messages: &user,
202            tools: &tools,
203        };
204        let options = SimpleStreamOptions {
205            api_key: self.api_key.clone(),
206            auth_token: self.auth_token.clone(),
207            max_tokens: Some(1024),
208            temperature: None,
209            reasoning: None,
210            thinking_budget_tokens: None,
211            cache_control: false,
212            timeout_ms: Some(60_000),
213        };
214        // Use the (cheap) compaction-tier model for the summary, not the main
215        // model — see default_compact_model.
216        let model = self
217            .compact_model
218            .clone()
219            .unwrap_or_else(|| self.default_compact_model());
220        let stream = stream_simple(&self.client, &model, &llm, &options, CancellationToken::new());
221        collect_assistant_text(stream).await
222    }
223
224    /// Compaction: summarize the oldest messages (cut at a user boundary) and
225    /// replace them with the summary, keeping the recent tail. Falls back to a
226    /// plain "messages dropped" note if the model is unavailable or fails, so
227    /// compaction always reduces the transcript and never hard-fails. Returns
228    /// the number of messages dropped.
229    pub async fn compact(&mut self) -> usize {
230        let cut = self.compaction_cut();
231        if cut == 0 {
232            return 0;
233        }
234        let dropped: Vec<Message> = self.messages[..cut].to_vec();
235        let summary = self.summarize(&dropped).await;
236        self.apply_compaction(cut, summary);
237        cut
238    }
239
240    /// Pure apply-step: drop `[0..cut)`, then fold `summary` (or a fallback
241    /// note) into the new first user message so roles stay valid (two
242    /// consecutive user roles are rejected by the API).
243    fn apply_compaction(&mut self, cut: usize, summary: Option<String>) {
244        let prefix = match summary {
245            Some(ref s) => format!(
246                "[Compaction summary — earlier messages were summarized to save context. Treat this \
247                 as background; do not re-read these files just to verify it.]\n\n{s}"
248            ),
249            None => "[context compacted: earlier messages were dropped to stay within the token budget]"
250                .into(),
251        };
252        self.messages.drain(0..cut);
253        match self.messages.first_mut() {
254            Some(Message::User(u)) => u.content.insert(0, UserBlock::text(prefix)),
255            _ => self.messages.insert(0, Message::User(UserMessage::text(prefix))),
256        }
257    }
258
259    /// Persist the transcript to the session JSONL file (if any).
260    pub fn save(&self) -> std::io::Result<()> {
261        let Some(path) = &self.session_file else {
262            return Ok(());
263        };
264        if let Some(parent) = path.parent() {
265            std::fs::create_dir_all(parent)?;
266        }
267        let mut out = String::new();
268        for msg in &self.messages {
269            let line = serde_json::to_string(msg).unwrap_or_default();
270            out.push_str(&line);
271            out.push('\n');
272        }
273        std::fs::write(path, out)
274    }
275
276    /// Load a transcript from a JSONL session file.
277    pub fn load(path: &Path) -> std::io::Result<Vec<Message>> {
278        let content = std::fs::read_to_string(path)?;
279        let mut messages = Vec::new();
280        for line in content.lines() {
281            if line.trim().is_empty() {
282                continue;
283            }
284            match serde_json::from_str::<Message>(line) {
285                Ok(m) => messages.push(m),
286                Err(_) => continue,
287            }
288        }
289        Ok(messages)
290    }
291
292    /// Accumulate usage from a turn into the session total.
293    pub fn add_usage(&mut self, usage: &Usage) {
294        self.total_usage.add(usage);
295    }
296
297    pub fn tool_names(&self) -> Vec<String> {
298        self.tools.iter().map(|t| t.name().to_string()).collect()
299    }
300}
301
302/// Builder with sensible defaults.
303pub fn default_gate() -> Arc<dyn ToolGate> {
304    allow_all_gate()
305}
306
307/// Sentinel used to attach a compacted-note marker; exposed for tests.
308pub fn compact_marker() -> Value {
309    Value::String("compacted".into())
310}
311
312/// Rough token estimate for a slice of messages (~4 chars/token). Extracted from
313/// the old `estimated_tokens` so `compaction_cut` can budget an arbitrary tail.
314fn estimate_tokens(messages: &[Message]) -> usize {
315    let chars: usize = messages
316        .iter()
317        .map(|m| match m {
318            Message::User(u) => u.text_content().len(),
319            Message::Assistant(a) => a.text_content().len(),
320            Message::ToolResult(t) => t
321                .content
322                .iter()
323                .filter_map(|c| match c {
324                    crate::ai::types::ToolResultContent::Text { text } => Some(text.len()),
325                    _ => None,
326                })
327                .sum::<usize>(),
328        })
329        .sum();
330    chars / CHARS_PER_TOKEN
331}
332
333/// Render a transcript slice to plain text for the summarizer: user/assistant
334/// text plus tool calls and their results, so the summary captures what was
335/// actually done — not just prose.
336fn transcript_for_summary(messages: &[Message]) -> String {
337    use crate::ai::types::{ContentBlock, ToolResultContent};
338    let mut out = String::new();
339    for m in messages {
340        match m {
341            Message::User(u) => {
342                out.push_str("User: ");
343                out.push_str(&u.text_content());
344                out.push('\n');
345            }
346            Message::Assistant(a) => {
347                let text = a.text_content();
348                if !text.trim().is_empty() {
349                    out.push_str("Assistant: ");
350                    out.push_str(&text);
351                    out.push('\n');
352                }
353                for block in &a.content {
354                    if let ContentBlock::ToolCall { name, arguments, .. } = block {
355                        out.push_str(&format!(
356                            "  [Assistant calls tool {name} with: {arguments}]\n"
357                        ));
358                    }
359                }
360            }
361            Message::ToolResult(t) => {
362                let text = t
363                    .content
364                    .iter()
365                    .filter_map(|c| match c {
366                        ToolResultContent::Text { text } => Some(text.as_str()),
367                        _ => None,
368                    })
369                    .collect::<Vec<_>>()
370                    .join("\n");
371                let tag = if t.is_error { "ERROR result" } else { "result" };
372                out.push_str(&format!("  [Tool {tag} for {}: {text}]\n", t.tool_name));
373            }
374        }
375    }
376    out
377}
378
379/// Drain a provider stream to its final assistant message and return its text.
380/// Used by the one-shot compaction summary call (no tool loop, no streaming UI).
381async fn collect_assistant_text(mut stream: AssistantStream) -> Option<String> {
382    let mut final_msg: Option<crate::ai::types::AssistantMessage> = None;
383    while let Some(ev) = stream.next().await {
384        match ev {
385            AssistantMessageEvent::Done { message, .. }
386            | AssistantMessageEvent::Error { message, .. } => final_msg = Some(message),
387            _ => {}
388        }
389    }
390    let msg = final_msg?;
391    if msg.error_message.is_some() {
392        return None;
393    }
394    let text = msg.text_content();
395    if text.trim().is_empty() {
396        None
397    } else {
398        Some(text)
399    }
400}
401
402#[cfg(test)]
403mod tests {
404    use super::*;
405    use crate::ai::types::{AssistantMessage, Message, UserMessage};
406
407    fn session_with(messages: Vec<Message>) -> AgentSession {
408        let mut model = crate::ai::builtin_models()[0].clone();
409        model.context_window = 1; // tiny so compaction always wants to drop
410        let session = AgentSession::new(
411            std::path::PathBuf::from("."),
412            "sys".into(),
413            model,
414            crate::ai::ThinkingLevel::Off,
415            vec![],
416            reqwest::Client::new(),
417        );
418        AgentSession {
419            messages,
420            ..session
421        }
422    }
423
424    #[test]
425    fn default_compact_model_uses_the_cheapest_tier() {
426        // With no per-session override and (normally) no PIXIE_PI_COMPACT_MODEL env var,
427        // the summary model should default to the cheapest tier (haiku).
428        let model = crate::ai::builtin_models()[0].clone();
429        let session = AgentSession::new(
430            std::path::PathBuf::from("."),
431            "sys".into(),
432            model,
433            crate::ai::ThinkingLevel::Off,
434            vec![],
435            reqwest::Client::new(),
436        );
437        let cm = session.default_compact_model();
438        assert!(cm.id.contains("haiku"), "default compact model should be haiku: {}", cm.id);
439    }
440
441    #[test]
442    fn compaction_cut_drops_oldest_exchange_at_user_boundary() {
443        // Three exchanges: U A U A U A. With a tiny context window the cut must
444        // drop at least the first exchange and land on a user boundary, leaving
445        // a valid alternating transcript.
446        let msgs = vec![
447            Message::User(UserMessage::text("first prompt")),
448            Message::Assistant(AssistantMessage::empty()),
449            Message::User(UserMessage::text("second prompt")),
450            Message::Assistant(AssistantMessage::empty()),
451            Message::User(UserMessage::text("third prompt")),
452            Message::Assistant(AssistantMessage::empty()),
453        ];
454        let s = session_with(msgs);
455        let cut = s.compaction_cut();
456        assert!(cut >= 2, "should cut at least the first exchange, got {cut}");
457        let remaining = &s.messages[cut..];
458        assert!(matches!(remaining.first(), Some(Message::User(_))), "starts with user");
459        assert!(matches!(remaining.get(1), Some(Message::Assistant(_))), "alternates");
460    }
461
462    #[test]
463    fn compaction_cut_refuses_to_sever_tool_chain() {
464        // One user prompt then an assistant/tool chain with no later user
465        // boundary — the cut must be 0 (stop) rather than orphan a tool result.
466        use crate::ai::types::ToolResultMessage;
467        let msgs = vec![
468            Message::User(UserMessage::text("only prompt")),
469            Message::Assistant(AssistantMessage::empty()),
470            Message::ToolResult(ToolResultMessage {
471                tool_call_id: "t1".into(),
472                tool_name: "read".into(),
473                content: vec![crate::ai::types::ToolResultContent::text("x")],
474                is_error: false,
475                timestamp: 0,
476            }),
477            Message::Assistant(AssistantMessage::empty()),
478            Message::ToolResult(ToolResultMessage {
479                tool_call_id: "t2".into(),
480                tool_name: "read".into(),
481                content: vec![crate::ai::types::ToolResultContent::text("y")],
482                is_error: false,
483                timestamp: 0,
484            }),
485        ];
486        let s = session_with(msgs.clone());
487        assert_eq!(s.compaction_cut(), 0, "no safe user boundary → no cut");
488        assert_eq!(s.messages.len(), msgs.len(), "nothing dropped");
489    }
490
491    #[test]
492    fn apply_compaction_folds_summary_ahead_of_kept_user_text() {
493        // Drop the first 2 messages; the summary must be folded into the (now
494        // first) kept user message, ahead of that message's original text, and
495        // the transcript must still start with a user turn.
496        let msgs = vec![
497            Message::User(UserMessage::text("old prompt")),
498            Message::Assistant(AssistantMessage::empty()),
499            Message::User(UserMessage::text("kept prompt")),
500            Message::Assistant(AssistantMessage::empty()),
501        ];
502        let mut s = session_with(msgs);
503        s.apply_compaction(2, Some("The user wanted to refactor parse().".into()));
504        assert_eq!(s.messages.len(), 2, "dropped 2, kept 2");
505        match &s.messages[0] {
506            Message::User(u) => {
507                let t = u.text_content();
508                assert!(t.contains("Compaction summary"), "summary header present: {t}");
509                assert!(
510                    t.contains("The user wanted to refactor parse()."),
511                    "summary body present: {t}"
512                );
513                assert!(t.contains("kept prompt"), "original user text preserved: {t}");
514                // Summary must come BEFORE the original text so the model reads it first.
515                assert!(t.find("Compaction summary").unwrap() < t.find("kept prompt").unwrap());
516            }
517            _ => panic!("must start with a user message"),
518        }
519    }
520
521    #[test]
522    fn apply_compaction_falls_back_to_note_without_summary() {
523        // No summary (model unavailable/failed) → a plain "dropped" note, and the
524        // transcript still starts with a user message.
525        let msgs = vec![
526            Message::User(UserMessage::text("old")),
527            Message::Assistant(AssistantMessage::empty()),
528            Message::User(UserMessage::text("kept")),
529            Message::Assistant(AssistantMessage::empty()),
530        ];
531        let mut s = session_with(msgs);
532        s.apply_compaction(2, None);
533        assert_eq!(s.messages.len(), 2);
534        assert!(matches!(s.messages.first(), Some(Message::User(_))));
535        match &s.messages[0] {
536            Message::User(u) => assert!(u.text_content().contains("dropped")),
537            _ => unreachable!(),
538        }
539    }
540
541    #[tokio::test]
542    async fn compact_async_falls_back_when_model_unreachable() {
543        // Exercises the real async compact() path end-to-end: summarize() opens a
544        // stream, collect_assistant_text drains it, and on failure apply_compaction
545        // falls back. The model points at an unreachable host so the summary call
546        // fails fast (connection refused) — this proves the orchestration and the
547        // graceful fallback WITHOUT depending on (or spending) a real API call.
548        let mut model = crate::ai::builtin_models()[0].clone();
549        model.context_window = 1; // tiny → always wants to compact
550        let mut session = AgentSession::new(
551            std::path::PathBuf::from("."),
552            "sys".into(),
553            model,
554            crate::ai::ThinkingLevel::Off,
555            vec![],
556            reqwest::Client::new(),
557        );
558        // Pin the compaction-tier model to an unreachable host so summarize()
559        // fails fast and compaction falls back to the plain drop (rather than
560        // hitting a real endpoint).
561        let mut unreachable = crate::ai::builtin_models()[0].clone();
562        unreachable.base_url = "http://127.0.0.1:1".into();
563        session.compact_model = Some(unreachable);
564        session.messages = vec![
565            Message::User(UserMessage::text("first")),
566            Message::Assistant(AssistantMessage::empty()),
567            Message::User(UserMessage::text("second")),
568            Message::Assistant(AssistantMessage::empty()),
569            Message::User(UserMessage::text("third")),
570            Message::Assistant(AssistantMessage::empty()),
571        ];
572        let dropped = session.compact().await;
573        assert!(dropped >= 2, "should drop at least one exchange");
574        assert!(matches!(session.messages.first(), Some(Message::User(_))));
575        let text = match &session.messages[0] {
576            Message::User(u) => u.text_content(),
577            _ => unreachable!(),
578        };
579        assert!(
580            text.contains("dropped"),
581            "must fall back to the drop-note when the model is unreachable: {text}"
582        );
583    }
584}