Skip to main content

pixie_pi/compat/
claude.rs

1//! Claude Code `stream-json` envelope shapes + the pixie→Claude event mapper.
2//!
3//! Each line of Claude's `stream-json` output is a JSON object externally
4//! tagged by `type`. Pixie (and other `claude` integrations) drive a turn by
5//! reading NDJSON lines off stdout until a `result` line ends the turn. This
6//! module maps pixie-pi's [`AgentEvent`]s onto those four envelope types:
7//!
8//! | Claude line  | Emitted from                                             |
9//! |--------------|----------------------------------------------------------|
10//! | `system`     | once at process start ([`system_init`]; not an event)    |
11//! | `assistant`  | [`AgentEvent::MessageEnd`] of an assistant message       |
12//! | `user`       | [`AgentEvent::MessageEnd`] of a tool-result message      |
13//! | `result`     | [`AgentEvent::AgentEnd`] (exactly one per turn)          |
14//!
15//! [`AgentEvent`]: crate::agent::context::AgentEvent
16//! [`AgentEvent::MessageEnd`]: crate::agent::context::AgentEvent::MessageEnd
17//! [`AgentEvent::AgentEnd`]: crate::agent::context::AgentEvent::AgentEnd
18
19use serde::Serialize;
20use serde_json::{json, Map, Value};
21
22use crate::agent::context::AgentEvent;
23use crate::ai::types::{
24    AssistantMessage, ContentBlock, Message, StopReason, ToolResultContent, ToolResultMessage,
25    Usage,
26};
27
28/// Per-process / per-turn state the mapper accumulates as events flow through
29/// [`map_events`]. The immutable fields (`session_id`, `model`, …) describe the
30/// run; the rest are updated in place so the final `result` line can report
31/// totals (usage, cost, turn count, duration, …).
32#[derive(Debug, Clone)]
33pub struct MapCtx {
34    /// Stable id for this session (echoed in every line). Usually the
35    /// `--session-id` value, else a freshly generated id.
36    pub session_id: String,
37    /// Model id driving the run (e.g. `claude-sonnet-4-6`).
38    pub model: String,
39    /// Working directory, surfaced in the `system.init` line.
40    pub cwd: String,
41    /// Permission mode string (e.g. `bypassPermissions`).
42    pub permission_mode: String,
43
44    // --- mutable accumulators (advanced by map_events) ---
45    usage: Usage,
46    num_turns: usize,
47    final_text: String,
48    last_stop_reason: Option<String>,
49    error: Option<String>,
50    /// Wall-clock duration of the turn, set by the driver from
51    /// [`std::time::Instant`] right before the `result` line is mapped.
52    pub duration_ms: u64,
53}
54
55impl MapCtx {
56    /// Construct a context with zeroed accumulators.
57    pub fn new(
58        session_id: impl Into<String>,
59        model: impl Into<String>,
60        cwd: impl Into<String>,
61        permission_mode: impl Into<String>,
62    ) -> Self {
63        Self {
64            session_id: session_id.into(),
65            model: model.into(),
66            cwd: cwd.into(),
67            permission_mode: permission_mode.into(),
68            usage: Usage::default(),
69            num_turns: 0,
70            final_text: String::new(),
71            last_stop_reason: None,
72            error: None,
73            duration_ms: 0,
74        }
75    }
76
77    /// Stamp the turn duration (called by the driver on `AgentEnd`).
78    pub fn set_duration_ms(&mut self, ms: u64) {
79        self.duration_ms = ms;
80    }
81}
82
83/// One NDJSON line of Claude's `stream-json` output.
84///
85/// Serialized with an internal `type` tag so each variant renders as
86/// `{"type":"<variant>", …}`.
87#[derive(Debug, Clone, Serialize)]
88#[serde(tag = "type")]
89pub enum ClaudeLine {
90    /// `system` init line — emitted once at process start (not from an event).
91    #[serde(rename = "system")]
92    System {
93        subtype: String,
94        #[serde(skip_serializing_if = "Option::is_none")]
95        cwd: Option<String>,
96        session_id: String,
97        model: String,
98        #[serde(rename = "permissionMode", skip_serializing_if = "Option::is_none")]
99        permission_mode: Option<String>,
100        tools: Vec<String>,
101        /// `mcpServers` map (empty — pixie-pi has no MCP server surface yet).
102        #[serde(rename = "mcpServers", skip_serializing_if = "Option::is_none")]
103        mcp_servers: Option<Value>,
104        version: String,
105    },
106    /// `assistant` line carrying a full assistant message.
107    #[serde(rename = "assistant")]
108    Assistant {
109        message: Value,
110        session_id: String,
111    },
112    /// `user` line carrying tool results back to the model's view.
113    #[serde(rename = "user")]
114    User {
115        message: Value,
116        session_id: String,
117    },
118    /// `result` line — the turn terminator (exactly one per turn).
119    #[serde(rename = "result")]
120    Result {
121        subtype: String,
122        is_error: bool,
123        result: String,
124        session_id: String,
125        #[serde(rename = "total_cost_usd")]
126        total_cost_usd: f64,
127        duration_ms: u64,
128        num_turns: u64,
129        model: String,
130        #[serde(skip_serializing_if = "Option::is_none")]
131        stop_reason: Option<String>,
132        /// Token totals with Claude's snake_case keys.
133        usage: Value,
134        /// Per-model token totals with Claude's camelCase keys.
135        #[serde(rename = "modelUsage")]
136        model_usage: Value,
137    },
138}
139
140impl ClaudeLine {
141    /// Build a `system` init line from the run context + active tool names.
142    fn system(ctx: &MapCtx, tools: Vec<String>) -> Self {
143        ClaudeLine::System {
144            subtype: "init".to_string(),
145            cwd: Some(ctx.cwd.clone()),
146            session_id: ctx.session_id.clone(),
147            model: ctx.model.clone(),
148            permission_mode: Some(ctx.permission_mode.clone()),
149            tools,
150            mcp_servers: Some(json!({})),
151            version: env!("CARGO_PKG_VERSION").to_string(),
152        }
153    }
154
155    /// Build an `assistant` line from a pixie assistant message.
156    fn assistant(a: &AssistantMessage, ctx: &MapCtx) -> Self {
157        let content: Vec<Value> = a.content.iter().map(map_content_block).collect();
158        let message = json!({
159            "id": a.response_id.clone().unwrap_or_else(|| "msg_0".to_string()),
160            "type": "message",
161            "role": "assistant",
162            "model": if a.model.is_empty() { ctx.model.clone() } else { a.model.clone() },
163            "content": content,
164            "stop_reason": map_stop_reason(a.stop_reason).unwrap_or("end_turn"),
165            "stop_sequence": Value::Null,
166            "usage": usage_tokens(&a.usage),
167        });
168        ClaudeLine::Assistant {
169            message,
170            session_id: ctx.session_id.clone(),
171        }
172    }
173
174    /// Build a `user` line carrying a single tool result.
175    fn user_tool_result(t: &ToolResultMessage, ctx: &MapCtx) -> Self {
176        let text: String = t
177            .content
178            .iter()
179            .filter_map(|c| match c {
180                ToolResultContent::Text { text } => Some(text.as_str()),
181                _ => None,
182            })
183            .collect::<Vec<_>>()
184            .join("\n");
185        let block = json!({
186            "type": "tool_result",
187            "tool_use_id": t.tool_call_id,
188            "content": text,
189            "is_error": t.is_error,
190        });
191        ClaudeLine::User {
192            message: json!({ "role": "user", "content": [block] }),
193            session_id: ctx.session_id.clone(),
194        }
195    }
196
197    /// Build the turn-terminating `result` line from accumulated context.
198    fn result(ctx: &MapCtx) -> Self {
199        let is_error = ctx.error.is_some();
200        let result_text = ctx
201            .error
202            .clone()
203            .unwrap_or_else(|| ctx.final_text.clone());
204        let model_usage = per_model_usage(&ctx.model, &ctx.usage);
205        ClaudeLine::Result {
206            subtype: if is_error {
207                "error".to_string()
208            } else {
209                "success".to_string()
210            },
211            is_error,
212            result: result_text,
213            session_id: ctx.session_id.clone(),
214            total_cost_usd: ctx.usage.cost.total,
215            duration_ms: ctx.duration_ms,
216            num_turns: ctx.num_turns as u64,
217            model: ctx.model.clone(),
218            stop_reason: ctx.last_stop_reason.clone(),
219            usage: usage_tokens(&ctx.usage),
220            model_usage,
221        }
222    }
223}
224
225/// Map one pixie [`AgentEvent`] to zero or more Claude [`ClaudeLine`]s, advancing
226/// `ctx` in place (accumulating usage, turn count, final text, …).
227///
228/// Returns lines in emission order; the caller flushes each as NDJSON. Most
229/// events produce no line — only assistant/tool-result message ends and the
230/// agent-end boundary do.
231pub fn map_events(ev: &AgentEvent, ctx: &mut MapCtx) -> Vec<ClaudeLine> {
232    let mut out = Vec::new();
233    match ev {
234        // Per-turn usage arrives as its own event (after the assistant message
235        // end); fold it into the running total for the final `result` line.
236        AgentEvent::Usage(u) => ctx.usage.add(u),
237
238        AgentEvent::MessageEnd(msg) => match msg {
239            Message::Assistant(a) => {
240                ctx.num_turns += 1;
241                if let Some(err) = &a.error_message {
242                    ctx.error = Some(err.clone());
243                }
244                ctx.last_stop_reason = map_stop_reason(a.stop_reason).map(str::to_string);
245                let text = a.text_content();
246                if !text.is_empty() {
247                    ctx.final_text = text;
248                }
249                out.push(ClaudeLine::assistant(a, ctx));
250            }
251            Message::ToolResult(t) => out.push(ClaudeLine::user_tool_result(t, ctx)),
252            // The user's own prompt is not echoed — real claude doesn't emit a
253            // `user` line for it, and doing so would read as a tool_result.
254            Message::User(_) => {}
255        },
256
257        // A fatal loop failure is folded into the single `result` terminator
258        // below (is_error=true) so the turn still ends with exactly one line.
259        AgentEvent::Error(msg) => ctx.error = Some(msg.clone()),
260
261        AgentEvent::AgentEnd { messages } => {
262            // Recover a final text if no assistant turn produced one.
263            if ctx.final_text.is_empty() {
264                if let Some(text) = messages.iter().rev().find_map(|m| match m {
265                    Message::Assistant(a) => {
266                        let t = a.text_content();
267                        if t.is_empty() {
268                            None
269                        } else {
270                            Some(t)
271                        }
272                    }
273                    _ => None,
274                }) {
275                    ctx.final_text = text;
276                }
277            }
278            out.push(ClaudeLine::result(ctx));
279        }
280
281        _ => {}
282    }
283    out
284}
285
286/// Build the one-time `system` init line (emitted at process start, before any
287/// event). `tools` is the list of active tool names.
288pub fn system_init(ctx: &MapCtx, tools: Vec<String>) -> ClaudeLine {
289    ClaudeLine::system(ctx, tools)
290}
291
292/// Serialize a [`ClaudeLine`] to a single NDJSON line (no trailing newline).
293pub fn to_ndjson(line: &ClaudeLine) -> String {
294    serde_json::to_string(line).unwrap_or_default()
295}
296
297// ---------------------------------------------------------------------------
298// shape mappers
299// ---------------------------------------------------------------------------
300
301/// Map a pixie assistant content block onto Claude's block shapes:
302/// - `Text`            → `{type:"text",text}`
303/// - `Thinking`        → `{type:"thinking",thinking}` (signature/redacted dropped)
304/// - `ToolCall`        → `{type:"tool_use",id,name,input}` (pixie's `arguments`
305///   becomes Claude's `input`)
306fn map_content_block(b: &ContentBlock) -> Value {
307    match b {
308        ContentBlock::Text { text } => json!({ "type": "text", "text": text }),
309        ContentBlock::Thinking { thinking, .. } => {
310            json!({ "type": "thinking", "thinking": thinking })
311        }
312        ContentBlock::ToolCall {
313            id,
314            name,
315            arguments,
316        } => json!({
317            "type": "tool_use",
318            "id": id,
319            "name": name,
320            "input": arguments,
321        }),
322    }
323}
324
325/// Map pixie's stop reason onto Claude's.
326fn map_stop_reason(r: StopReason) -> Option<&'static str> {
327    Some(match r {
328        StopReason::Stop => "end_turn",
329        StopReason::Length => "max_tokens",
330        StopReason::ToolUse => "tool_use",
331        // Provider/stream failures don't have a dedicated Claude stop reason;
332        // surface them via the `result` line's `is_error` instead.
333        StopReason::Error | StopReason::Aborted => "end_turn",
334    })
335}
336
337/// Claude usage object with snake_case token keys. pixie's `cache_write` maps
338/// to Anthropic's `cache_creation`.
339fn usage_tokens(u: &Usage) -> Value {
340    json!({
341        "input_tokens": u.input,
342        "output_tokens": u.output,
343        "cache_creation_input_tokens": u.cache_write,
344        "cache_read_input_tokens": u.cache_read,
345    })
346}
347
348/// Claude `modelUsage` map (camelCase keys) for the result line.
349fn per_model_usage(model: &str, u: &Usage) -> Value {
350    let mut m = Map::new();
351    m.insert(
352        model.to_string(),
353        json!({
354            "inputTokens": u.input,
355            "outputTokens": u.output,
356            "cacheReadInputTokens": u.cache_read,
357            "cacheCreationInputTokens": u.cache_write,
358        }),
359    );
360    Value::Object(m)
361}
362
363#[cfg(test)]
364mod tests {
365    use super::*;
366    use crate::ai::types::{AssistantMessage, ContentBlock, Message, ToolResultContent,
367        ToolResultMessage, Usage};
368
369    fn ctx() -> MapCtx {
370        MapCtx::new("sess-1", "claude-sonnet-4-6", "/tmp/proj", "bypassPermissions")
371    }
372
373    fn assistant_text(text: &str, usage: Usage) -> AssistantMessage {
374        let mut a = AssistantMessage::empty();
375        a.content.push(ContentBlock::Text {
376            text: text.to_string(),
377        });
378        a.usage = usage;
379        a
380    }
381
382    #[test]
383    fn system_init_has_init_subtype_and_model() {
384        let line = system_init(&ctx(), vec!["read".into(), "bash".into()]);
385        let v: Value = serde_json::from_str(&to_ndjson(&line)).unwrap();
386        assert_eq!(v["type"], "system");
387        assert_eq!(v["subtype"], "init");
388        assert_eq!(v["model"], "claude-sonnet-4-6");
389        assert_eq!(v["session_id"], "sess-1");
390        assert_eq!(v["permissionMode"], "bypassPermissions");
391        assert_eq!(v["cwd"], "/tmp/proj");
392        assert_eq!(v["tools"][0], "read");
393    }
394
395    #[test]
396    fn assistant_message_end_emits_assistant_line_with_text_block() {
397        let mut c = ctx();
398        let a = assistant_text("Hello", Usage::default());
399        let lines = map_events(
400            &AgentEvent::MessageEnd(Message::Assistant(a)),
401            &mut c,
402        );
403        assert_eq!(lines.len(), 1);
404        let v: Value = serde_json::from_str(&to_ndjson(&lines[0])).unwrap();
405        assert_eq!(v["type"], "assistant");
406        assert_eq!(v["session_id"], "sess-1");
407        assert_eq!(v["message"]["role"], "assistant");
408        assert_eq!(v["message"]["content"][0]["type"], "text");
409        assert_eq!(v["message"]["content"][0]["text"], "Hello");
410    }
411
412    #[test]
413    fn tool_call_block_is_tool_use_with_input_not_arguments() {
414        let mut c = ctx();
415        let mut a = AssistantMessage::empty();
416        a.content.push(ContentBlock::ToolCall {
417            id: "tu_1".into(),
418            name: "read".into(),
419            arguments: json!({ "path": "/a" }),
420        });
421        let lines = map_events(&AgentEvent::MessageEnd(Message::Assistant(a)), &mut c);
422        let block = serde_json::from_str::<Value>(&to_ndjson(&lines[0])).unwrap()["message"]
423            ["content"][0]
424            .clone();
425        assert_eq!(block["type"], "tool_use");
426        assert_eq!(block["id"], "tu_1");
427        assert_eq!(block["name"], "read");
428        // pixie's `arguments` is remapped to Claude's `input`.
429        assert_eq!(block["input"]["path"], "/a");
430        assert!(block.get("arguments").is_none());
431    }
432
433    #[test]
434    fn tool_result_message_end_emits_user_line_with_tool_result_block() {
435        let mut c = ctx();
436        let t = ToolResultMessage {
437            tool_call_id: "tu_1".into(),
438            tool_name: "read".into(),
439            content: vec![ToolResultContent::text("file body")],
440            is_error: false,
441            timestamp: 0,
442        };
443        let lines = map_events(&AgentEvent::MessageEnd(Message::ToolResult(t)), &mut c);
444        assert_eq!(lines.len(), 1);
445        let v: Value = serde_json::from_str(&to_ndjson(&lines[0])).unwrap();
446        assert_eq!(v["type"], "user");
447        assert_eq!(v["message"]["role"], "user");
448        assert_eq!(v["message"]["content"][0]["type"], "tool_result");
449        assert_eq!(v["message"]["content"][0]["tool_use_id"], "tu_1");
450        assert_eq!(v["message"]["content"][0]["content"], "file body");
451        assert_eq!(v["message"]["content"][0]["is_error"], false);
452    }
453
454    #[test]
455    fn user_prompt_is_not_echoed_as_a_user_line() {
456        let mut c = ctx();
457        let prompt = Message::User(crate::ai::types::UserMessage::text("ignored prompt"));
458        let lines = map_events(&AgentEvent::MessageEnd(prompt), &mut c);
459        assert!(lines.is_empty(), "injected user prompt must not be echoed");
460    }
461
462    #[test]
463    fn usage_event_accumulates_into_context_and_emits_no_line() {
464        let mut c = ctx();
465        let a = assistant_text("Hi", Usage::default());
466        map_events(&AgentEvent::MessageEnd(Message::Assistant(a)), &mut c);
467        // The assistant message's own usage is in its line; the aggregate Usage
468        // event folds into the context for the result line.
469        let lines = map_events(
470            &AgentEvent::Usage(Usage {
471                input: 100,
472                output: 40,
473                cache_read: 5,
474                cache_write: 2,
475                ..Usage::default()
476            }),
477            &mut c,
478        );
479        assert!(lines.is_empty());
480    }
481
482    #[test]
483    fn agent_end_emits_exactly_one_result_line_with_totals() {
484        let mut c = ctx();
485        let a = assistant_text("final answer", Usage::default());
486        map_events(&AgentEvent::MessageEnd(Message::Assistant(a)), &mut c);
487        map_events(
488            &AgentEvent::Usage(Usage {
489                input: 100,
490                output: 40,
491                cache_read: 5,
492                cache_write: 2,
493                cost: crate::ai::types::Cost {
494                    total: 0.0123,
495                    ..Default::default()
496                },
497                ..Usage::default()
498            }),
499            &mut c,
500        );
501        c.set_duration_ms(1500);
502
503        let lines = map_events(
504            &AgentEvent::AgentEnd {
505                messages: Vec::new(),
506            },
507            &mut c,
508        );
509        assert_eq!(lines.len(), 1, "AgentEnd ⇒ exactly one result line");
510        let v: Value = serde_json::from_str(&to_ndjson(&lines[0])).unwrap();
511        assert_eq!(v["type"], "result");
512        assert_eq!(v["subtype"], "success");
513        assert_eq!(v["is_error"], false);
514        assert_eq!(v["result"], "final answer");
515        assert_eq!(v["num_turns"], 1);
516        assert_eq!(v["duration_ms"], 1500);
517        assert_eq!(v["total_cost_usd"], 0.0123);
518        assert_eq!(v["usage"]["input_tokens"], 100);
519        assert_eq!(v["usage"]["output_tokens"], 40);
520        // cache_write (2) surfaces as Anthropic's cache_creation.
521        assert_eq!(v["usage"]["cache_creation_input_tokens"], 2);
522        assert_eq!(v["usage"]["cache_read_input_tokens"], 5);
523        // modelUsage mirrors the same totals under the model key, camelCase.
524        assert_eq!(v["modelUsage"]["claude-sonnet-4-6"]["inputTokens"], 100);
525        assert_eq!(v["modelUsage"]["claude-sonnet-4-6"]["outputTokens"], 40);
526    }
527
528    #[test]
529    fn full_tool_use_turn_sequences_assistant_user_result() {
530        // assistant(tool_use) → user(tool_result) → assistant(text) → result
531        let mut c = ctx();
532
533        let mut a1 = AssistantMessage::empty();
534        a1.stop_reason = StopReason::ToolUse;
535        a1.content.push(ContentBlock::ToolCall {
536            id: "tu_1".into(),
537            name: "read".into(),
538            arguments: json!({ "path": "/a" }),
539        });
540        let l1 = map_events(&AgentEvent::MessageEnd(Message::Assistant(a1)), &mut c);
541
542        let t = ToolResultMessage {
543            tool_call_id: "tu_1".into(),
544            tool_name: "read".into(),
545            content: vec![ToolResultContent::text("ok")],
546            is_error: false,
547            timestamp: 0,
548        };
549        let l2 = map_events(&AgentEvent::MessageEnd(Message::ToolResult(t)), &mut c);
550
551        let mut a2 = AssistantMessage::empty();
552        a2.content.push(ContentBlock::Text {
553            text: "done".into(),
554        });
555        let l3 = map_events(&AgentEvent::MessageEnd(Message::Assistant(a2)), &mut c);
556
557        let l4 = map_events(
558            &AgentEvent::AgentEnd {
559                messages: Vec::new(),
560            },
561            &mut c,
562        );
563
564        let line_of = |ls: Vec<ClaudeLine>| {
565            serde_json::from_str::<Value>(&to_ndjson(&ls[0])).unwrap()["type"]
566                .clone()
567        };
568        assert_eq!(line_of(l1), "assistant");
569        assert_eq!(line_of(l2), "user");
570        assert_eq!(line_of(l3), "assistant");
571        assert_eq!(line_of(l4), "result");
572        assert_eq!(c.num_turns, 2, "two assistant turns in a tool-use run");
573    }
574
575    #[test]
576    fn fatal_error_surfaces_in_result_line_as_error() {
577        let mut c = ctx();
578        let a = assistant_text("partial", Usage::default());
579        map_events(&AgentEvent::MessageEnd(Message::Assistant(a)), &mut c);
580        map_events(&AgentEvent::Error("boom".into()), &mut c);
581        let lines = map_events(
582            &AgentEvent::AgentEnd {
583                messages: Vec::new(),
584            },
585            &mut c,
586        );
587        let v: Value = serde_json::from_str(&to_ndjson(&lines[0])).unwrap();
588        assert_eq!(v["type"], "result");
589        assert_eq!(v["is_error"], true);
590        assert_eq!(v["subtype"], "error");
591        assert_eq!(v["result"], "boom", "error message becomes the result text");
592    }
593
594    #[test]
595    fn to_ndjson_round_trips_through_serde() {
596        let line = system_init(&ctx(), Vec::new());
597        let s = to_ndjson(&line);
598        assert!(!s.contains('\n'), "a line has no embedded newline");
599        let v: Value = serde_json::from_str(&s).unwrap();
600        assert_eq!(v["type"], "system");
601    }
602}