2588 lines
116 KiB
Rust
2588 lines
116 KiB
Rust
//! The stream-json dialect: CLI lines in, common [`Event`]s out.
|
|
//!
|
|
//! Split from the driver beside it because the two change for unrelated
|
|
//! reasons. This half moves when the CLI's wire format does, which is what the
|
|
//! tests at the bottom pin by replaying recorded lines; the driver half moves
|
|
//! when spawning, resuming or shutting down changes.
|
|
//!
|
|
//! The one side effect here is saving images a tool result carries into the
|
|
//! session directory; everything else is pure, which is what makes the mapping
|
|
//! testable without a process.
|
|
|
|
use std::collections::{HashMap, HashSet};
|
|
use std::path::{Path, PathBuf};
|
|
use std::sync::{Arc, Mutex};
|
|
|
|
use serde_json::{Value, json};
|
|
|
|
use super::super::driver::{Event, QuestionOption, SessionStatus, context_tokens, patch_start};
|
|
use super::super::subagent::Subagents;
|
|
|
|
/// Whether this line is the CLI opening a fresh model call.
|
|
///
|
|
/// `message_start` begins one assistant message, and the CLI sends the previous
|
|
/// call's tool results back before opening the next -- so this is the first
|
|
/// moment at which anything written since the last one can have been read.
|
|
/// Nothing earlier will do: the deltas and `tool_use` of a message *already in
|
|
/// flight* keep arriving after a steer is written, and none of them saw it.
|
|
///
|
|
/// Only present because the driver passes `--include-partial-messages`, which
|
|
/// is why the caller keeps a fallback that does not depend on it.
|
|
pub(super) fn starts_a_model_call(message: &Value) -> bool {
|
|
message.get("type").and_then(Value::as_str) == Some("stream_event")
|
|
&& message["event"].get("type").and_then(Value::as_str) == Some("message_start")
|
|
}
|
|
|
|
/// What answering a question produced.
|
|
pub(super) enum AnswerOutcome {
|
|
/// Send this control_response line to the CLI.
|
|
Respond(Value),
|
|
/// Part of a multi-question request; more answers still needed.
|
|
Pending,
|
|
Unknown,
|
|
}
|
|
|
|
/// A setting a control request asked for, held until the CLI says whether it
|
|
/// took. The CLI answers `set_model` with a bare success -- no value -- so the
|
|
/// only way to report what was accepted is to remember what was asked.
|
|
/// `set_permission_mode` does echo its mode back.
|
|
pub(super) enum Setting {
|
|
Model(String),
|
|
PermissionMode(String),
|
|
}
|
|
|
|
/// A `can_use_tool` request we've surfaced to the phone and not yet answered.
|
|
/// For plain permissions there is one implicit question (Allow/Deny); for
|
|
/// AskUserQuestion, one per entry in `questions`.
|
|
struct PendingRequest {
|
|
request_id: String,
|
|
input: Value,
|
|
/// Question text per sub-question, in order -- the keys the answers map
|
|
/// uses. Empty for a plain permission request.
|
|
questions: Vec<String>,
|
|
answers: HashMap<String, String>,
|
|
}
|
|
|
|
/// Translation state: stream-json lines in, common events out.
|
|
pub(super) struct Translator {
|
|
pub(super) session_id: Option<String>,
|
|
pending: HashMap<String, PendingRequest>,
|
|
/// Settings asked for and not yet answered, by request id. Its path out is
|
|
/// the response: every entry is removed when one arrives, whether it
|
|
/// succeeded or failed.
|
|
asked: HashMap<String, Setting>,
|
|
/// Whether this side asked the turn to stop.
|
|
///
|
|
/// The CLI reports an interrupted turn the same way it reports one that
|
|
/// broke -- a `result` with `is_error` set -- so the line cannot tell them
|
|
/// apart, and somebody who pressed Stop was shown "the turn ended with an
|
|
/// error". What separates them is that *we* asked.
|
|
///
|
|
/// Its path out is that result, so a genuine failure in a later turn is
|
|
/// still reported.
|
|
interrupting: bool,
|
|
/// The input side of the newest assistant message, waiting for the `result`
|
|
/// that ends the turn to carry it out.
|
|
///
|
|
/// Read from the assistant message rather than the result's own usage,
|
|
/// which is the whole turn added up: measured on 2026-08-30 against 2.1.237,
|
|
/// a two-message turn reported `cache_read_input_tokens` of 40,211, being
|
|
/// 14,259 and 25,952 -- the same conversation counted twice. The model held
|
|
/// 26,131. A turn with ten tool calls would overstate it tenfold.
|
|
///
|
|
/// Its path out is that result, so a turn whose messages carried no usage
|
|
/// reports none rather than repeating the previous turn's.
|
|
context: Option<u64>,
|
|
session_dir: PathBuf,
|
|
/// This session's subagents, shared with every child translator below --
|
|
/// see `SUBAGENTS.md`. One registry per session, so a subagent started
|
|
/// through this translator or any of its children lands in the same
|
|
/// place a route reads it back from.
|
|
subagents: Arc<Subagents>,
|
|
/// One translator per subagent id, holding *its* streaming and
|
|
/// tool-tracking state -- separate from the parent's because tool ids
|
|
/// are unique but a `stream_event`'s content-block index is not, and
|
|
/// parallel subagents interleave their deltas on one stdout.
|
|
children: HashMap<String, Arc<Mutex<Translator>>>,
|
|
/// Whether the last `rate_limit_event` said the account is refused, so
|
|
/// that only the change into that state is reported -- see
|
|
/// [`Translator::translate_rate_limit`].
|
|
rate_limited: bool,
|
|
/// Which Task call each task belongs to: the CLI's `task_id` against the
|
|
/// `tool_use_id` this side names a subagent by.
|
|
///
|
|
/// Needed because the line that says a task ended comes in two shapes and
|
|
/// only one of them carries the tool id -- see [`Translator::translate_task`].
|
|
tasks: HashMap<String, String>,
|
|
/// The backgrounded tasks this translator has seen start and not seen
|
|
/// finish, by `tool_use_id`.
|
|
///
|
|
/// Half of the answer to "does this session still have work outstanding",
|
|
/// which is the difference between `Idle` and [`SessionStatus::Waiting`].
|
|
/// The other half is `Subagents::any_open`, and both are needed: this one
|
|
/// covers a backgrounded *command*, which has no subagent behind it at
|
|
/// all, and the registry covers a subagent launched before this
|
|
/// translator existed, which is every one of them after a backend
|
|
/// restart adopts a running session.
|
|
open_tasks: HashSet<String>,
|
|
/// File-edit calls whose successful boilerplate result should not be drawn below their diff.
|
|
/// Each leaves here with its `tool_result`; a failure keeps its text because that is the part a
|
|
/// reader needs to act on.
|
|
patches: HashSet<String>,
|
|
/// Whether a turn is open, judged from this translator's own output: the
|
|
/// events that [`super::proves_a_turn`] accepts open one, and the status
|
|
/// that ends a turn closes it.
|
|
///
|
|
/// The same rule the driver uses to announce `Running`, read from the same
|
|
/// side of the translation, because two rules for "is a turn running"
|
|
/// would disagree the first time either moved. What it decides here is
|
|
/// narrow: whether a task reporting back means the session has gone idle,
|
|
/// or is merely one of several things happening inside a turn.
|
|
in_turn: bool,
|
|
}
|
|
|
|
impl Translator {
|
|
pub(super) fn new(session_dir: PathBuf, subagents: Arc<Subagents>) -> Self {
|
|
Self {
|
|
session_id: None,
|
|
pending: HashMap::new(),
|
|
asked: HashMap::new(),
|
|
interrupting: false,
|
|
context: None,
|
|
session_dir,
|
|
subagents,
|
|
children: HashMap::new(),
|
|
rate_limited: false,
|
|
tasks: HashMap::new(),
|
|
open_tasks: HashSet::new(),
|
|
patches: HashSet::new(),
|
|
in_turn: false,
|
|
}
|
|
}
|
|
|
|
/// Remembers what a control request was for, so its answer can say so.
|
|
/// Called before the request goes out: the reader thread is already running
|
|
/// and a fast CLI can answer before this side gets back to it.
|
|
pub(super) fn expect_setting(&mut self, request_id: String, setting: Setting) {
|
|
self.asked.insert(request_id, setting);
|
|
}
|
|
|
|
/// Says that the turn about to end was stopped on purpose. Called before
|
|
/// the request goes out, for the reason [`Translator::expect_setting`]
|
|
/// gives.
|
|
pub(super) fn expect_interrupt(&mut self) {
|
|
self.interrupting = true;
|
|
}
|
|
pub(super) fn translate(&mut self, message: &Value) -> Vec<Event> {
|
|
// Events from subagents (Task tool internals) carry a
|
|
// parent_tool_use_id; the transcript shows the Task tool's own
|
|
// start/end instead of every nested step. Routed into that
|
|
// subagent's own transcript rather than dropped -- see
|
|
// `SUBAGENTS.md`.
|
|
if let Some(parent_id) = message.get("parent_tool_use_id").and_then(Value::as_str) {
|
|
return self.translate_child(parent_id, message);
|
|
}
|
|
self.dispatch(message)
|
|
}
|
|
|
|
/// A line belonging to a subagent rather than to this translator's own
|
|
/// session. Always returns nothing to the *caller*: everything it
|
|
/// produces goes into the subagent's own transcript instead.
|
|
fn translate_child(&mut self, id: &str, message: &Value) -> Vec<Event> {
|
|
match self.subagents.get(id) {
|
|
Some(subagent) if !subagent.is_open() => {
|
|
// Not stale: the Task tool runs in the background by
|
|
// default, so a finished subagent can still be sent another
|
|
// message later (SendMessage) and start working again. A
|
|
// line arriving after `finish` means exactly that, not a
|
|
// conversation that is over -- see `SUBAGENTS.md`.
|
|
self.subagents.reopen(id);
|
|
}
|
|
Some(_) => {}
|
|
None => {
|
|
// Nobody has heard of this id yet: the Task call itself
|
|
// either has not been seen or never will be. Started here
|
|
// with the best title available -- the tool name of this
|
|
// first line -- since SUBAGENTS.md's real title only
|
|
// arrives with the Task call.
|
|
self.subagents.start(id, &fallback_title(message), None);
|
|
}
|
|
}
|
|
let child = self
|
|
.children
|
|
.entry(id.to_string())
|
|
.or_insert_with(|| {
|
|
Arc::new(Mutex::new(Translator::new(
|
|
self.session_dir.clone(),
|
|
Arc::clone(&self.subagents),
|
|
)))
|
|
})
|
|
.clone();
|
|
let events = child.lock().unwrap().dispatch(message);
|
|
// A limit the account hit while this subagent was working. It belongs
|
|
// in the subagent's transcript, which is where it happened -- and it
|
|
// also has to reach the session, which is the only thing auto-resume
|
|
// can schedule against: a background subagent can run on long after
|
|
// its parent's own turn ended, so "the main agent was idle when the
|
|
// limit hit" is the ordinary case rather than an edge of one, and
|
|
// swallowing it here left that session waiting for a person for ever.
|
|
let mut hoisted = Vec::new();
|
|
for event in events {
|
|
// The subagent's own vocabulary is Running/Exited/Unknown, never
|
|
// Idle or Waiting -- a background Task is either working or it has
|
|
// ended, never merely "between turns" the way a session is.
|
|
// Dropped here rather than never produced, so a `result` line's
|
|
// own end-of-turn status (dispatch's ordinary one, for a subagent
|
|
// dialect that ever sends one) is caught the same way a
|
|
// `message_delta` would be.
|
|
if closes_a_turn(&event) {
|
|
continue;
|
|
}
|
|
if matches!(event, Event::LimitReached { .. }) {
|
|
hoisted.push(event.clone());
|
|
}
|
|
self.subagents.record(id, event);
|
|
}
|
|
// What actually ends a subagent's turn: not the parent's
|
|
// `tool_result`, which for a background Task arrives at launch
|
|
// ("Async agent launched...") long before the work is done -- see
|
|
// `SUBAGENTS.md`.
|
|
if ends_a_turn(message) {
|
|
self.subagents.finish(id);
|
|
}
|
|
hoisted
|
|
}
|
|
|
|
/// One line of this translator's own session, with [`Translator::in_turn`]
|
|
/// kept up to date from what came out of it.
|
|
///
|
|
/// Here rather than in each arm because it has to hold for every line
|
|
/// there is: the set of events that prove a turn is running is
|
|
/// [`super::proves_a_turn`]'s, and no arm should have to remember it.
|
|
fn dispatch(&mut self, message: &Value) -> Vec<Event> {
|
|
let events = self.translate_line(message);
|
|
if events.iter().any(closes_a_turn) {
|
|
self.in_turn = false;
|
|
} else if events.iter().any(super::proves_a_turn) {
|
|
self.in_turn = true;
|
|
}
|
|
events
|
|
}
|
|
|
|
fn translate_line(&mut self, message: &Value) -> Vec<Event> {
|
|
match message.get("type").and_then(Value::as_str) {
|
|
Some("system") => self.translate_system(message),
|
|
// The CLI's own announcement that `/clear` took effect, sent just
|
|
// before the fresh `init` carrying the new session_id. Measured
|
|
// against 2.1.237: this used to watch for the id being *replaced*,
|
|
// which is the same event seen through a side effect. The
|
|
// announcement lands before the new init rather than after it.
|
|
Some("conversation_reset") => vec![Event::Cleared],
|
|
Some("rate_limit_event") => self.translate_rate_limit(message),
|
|
Some("stream_event") => self.translate_stream_event(&message["event"]),
|
|
Some("assistant") => self.translate_assistant(&message["message"]),
|
|
Some("user") => self.translate_user(message),
|
|
Some("control_request") => self.translate_control_request(message),
|
|
Some("control_response") => {
|
|
let response = &message["response"];
|
|
// Answered either way, so the request stops being pending
|
|
// either way -- a rejected setting that stayed here would be
|
|
// applied by the next request that reused its id.
|
|
let asked = response
|
|
.get("request_id")
|
|
.and_then(Value::as_str)
|
|
.and_then(|id| self.asked.remove(id));
|
|
if response.get("subtype").and_then(Value::as_str) == Some("error") {
|
|
let error = response
|
|
.get("error")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or("unknown");
|
|
return vec![Event::Error {
|
|
message: format!("claude rejected a request: {error}"),
|
|
}];
|
|
}
|
|
// Success, so the setting this request asked for is now the
|
|
// session's, and this is the only place that says so: the
|
|
// response carries no value of its own for a model.
|
|
match asked {
|
|
Some(Setting::Model(model)) => vec![Event::Settings {
|
|
model: Some(model),
|
|
permission_mode: None,
|
|
}],
|
|
Some(Setting::PermissionMode(mode)) => vec![Event::Settings {
|
|
model: None,
|
|
// The CLI echoes this one, and its answer wins: `auto`
|
|
// and `manual` are names it accepts on the way in and
|
|
// reports back under another name, so repeating the
|
|
// request would show a mode the session is not in.
|
|
permission_mode: Some(
|
|
response["response"]["mode"]
|
|
.as_str()
|
|
.map(str::to_string)
|
|
.unwrap_or(mode),
|
|
),
|
|
}],
|
|
None => Vec::new(),
|
|
}
|
|
}
|
|
Some("result") => {
|
|
let usage = &message["usage"];
|
|
let tokens = usage
|
|
.get("input_tokens")
|
|
.and_then(Value::as_u64)
|
|
.unwrap_or(0)
|
|
+ usage
|
|
.get("output_tokens")
|
|
.and_then(Value::as_u64)
|
|
.unwrap_or(0);
|
|
let mut events = Vec::new();
|
|
// A turn another agent started, which is only knowable here.
|
|
//
|
|
// Measured against 2.1.237 (2026-08-31) by sending a real
|
|
// cross-session message to a real stream-json session: the CLI
|
|
// emits no `user` record for it and nothing in the
|
|
// partial-message stream mentions it. The whole of it arrives as
|
|
// an `origin` object on the turn's `result`, in the same shape
|
|
// the session file records -- so this is `import::peer_message`
|
|
// reading a different record.
|
|
//
|
|
// The cost is the position: the note lands after the reply it
|
|
// caused, because at no earlier point does the CLI say why the
|
|
// turn started. Taken deliberately over a second reader tailing
|
|
// the CLI's own session file, which is two sources of truth for
|
|
// one conversation and a poll per live session.
|
|
//
|
|
// Only peer-caused turns carry it: four ordinary results over a
|
|
// real session's stdout had no `origin` between them.
|
|
if let Some(peer) = crate::session::import::peer_message(message) {
|
|
events.push(peer);
|
|
}
|
|
// Whichever way this result went, the interrupt it may have
|
|
// been answering is now spent.
|
|
let asked_to_stop = std::mem::take(&mut self.interrupting);
|
|
if !asked_to_stop
|
|
&& message
|
|
.get("is_error")
|
|
.and_then(Value::as_bool)
|
|
.unwrap_or(false)
|
|
{
|
|
let said = message.get("result").and_then(Value::as_str);
|
|
events.push(match said.and_then(usage_limit) {
|
|
Some(resets_at) => Event::LimitReached { resets_at },
|
|
None => Event::Error {
|
|
message: said.unwrap_or("the turn ended with an error").to_string(),
|
|
},
|
|
});
|
|
}
|
|
let context = self.context.take();
|
|
if tokens > 0 {
|
|
events.push(Event::UsageDelta { tokens, context });
|
|
}
|
|
// Idle means "waiting for a person", and a session with a
|
|
// backgrounded subagent or command still running is not doing
|
|
// that -- it is waiting for itself, and will speak again with
|
|
// nobody having typed anything. Reported as what it is, so
|
|
// that nothing tells the reader the work has finished.
|
|
events.push(Event::Status {
|
|
state: if self.work_outstanding() {
|
|
SessionStatus::Waiting
|
|
} else {
|
|
SessionStatus::Idle
|
|
},
|
|
});
|
|
events
|
|
}
|
|
_ => Vec::new(),
|
|
}
|
|
}
|
|
|
|
/// The CLI's own notices: which session this is, and what it is doing that
|
|
/// is not a turn.
|
|
///
|
|
/// Compaction is the whole of that second kind, and it is announced rather
|
|
/// than inferred. Measured against 2.1.237 (2026-08-29) by driving a session
|
|
/// through `/compact`, one produces in order:
|
|
///
|
|
/// - `{"subtype":"status","status":"compacting"}` -- the start;
|
|
/// - `{"subtype":"status","status":null,"compact_result":"success"}`, or
|
|
/// `"failed"` with a `compact_error` -- the end;
|
|
/// - a fresh `init` carrying the same `session_id`;
|
|
/// - `{"subtype":"compact_boundary","compact_metadata":{…}}` with the token
|
|
/// counts, and only when it succeeded;
|
|
/// - the turn's ordinary `result`, which returns it to idle.
|
|
///
|
|
/// The keys are snake_case here and camelCase in the CLI's own transcript
|
|
/// file, which records the same events -- so reading the shape off that
|
|
/// file, the obvious place to look, gets every field name wrong and
|
|
/// silently yields a compaction with no numbers in it.
|
|
fn translate_system(&mut self, message: &Value) -> Vec<Event> {
|
|
match message.get("subtype").and_then(Value::as_str) {
|
|
Some("init") => {
|
|
if let Some(id) = message.get("session_id").and_then(Value::as_str) {
|
|
self.session_id = Some(id.to_string());
|
|
}
|
|
// The CLI's own account of what it is set to, and the only one
|
|
// that resolves an alias: a session launched with
|
|
// `--model haiku` reports `claude-haiku-4-5-20251001` here. It
|
|
// arrives again after a compaction, which is free.
|
|
vec![Event::Settings {
|
|
model: message
|
|
.get("model")
|
|
.and_then(Value::as_str)
|
|
.map(str::to_string),
|
|
permission_mode: message
|
|
.get("permissionMode")
|
|
.and_then(Value::as_str)
|
|
.map(str::to_string),
|
|
}]
|
|
}
|
|
Some("status") => self.translate_status(message),
|
|
Some("task_started" | "task_progress" | "task_updated" | "task_notification") => {
|
|
self.translate_task(message)
|
|
}
|
|
Some("compact_boundary") => {
|
|
let meta = &message["compact_metadata"];
|
|
vec![Event::Compacted {
|
|
pre_tokens: meta.get("pre_tokens").and_then(Value::as_u64),
|
|
post_tokens: meta.get("post_tokens").and_then(Value::as_u64),
|
|
trigger: meta
|
|
.get("trigger")
|
|
.and_then(Value::as_str)
|
|
.map(str::to_string),
|
|
}]
|
|
}
|
|
_ => Vec::new(),
|
|
}
|
|
}
|
|
|
|
/// A `system/status` line: the CLI entering or leaving a state that is not
|
|
/// a turn.
|
|
///
|
|
/// The CLI saying where the account stands with its rate limits, which it
|
|
/// sends unasked during a turn.
|
|
///
|
|
/// A second detector for the one thing auto-resume depends on, beside the
|
|
/// failed `result` [`usage_limit`] reads. That one is the CLI's error
|
|
/// sentence and is the only thing this server watched; if a version ever
|
|
/// stops the turn without it -- or blocks before starting one -- nothing
|
|
/// is scheduled and a session switched to auto-resume simply never comes
|
|
/// back, with nothing on screen or in the log saying why. This line says
|
|
/// it outright.
|
|
///
|
|
/// Measured against 2.1.237 on 2026-09-06: `rate_limit_info` carries
|
|
/// `status`, `resetsAt` (epoch seconds), `rateLimitType`, and on newer
|
|
/// lines a `unifiedWindows` map of utilizations. Only `allowed` has been
|
|
/// observed here, so anything that is *not* an `allowed…` word is taken
|
|
/// as refused rather than assumed harmless -- the state left out of an
|
|
/// enumeration is the one that costs, and being wrong that way is one
|
|
/// extra question to the usage meter, which is what decides whether
|
|
/// anything is actually sent. An unrecognised word is logged, so the next
|
|
/// one to appear is a fact rather than a guess.
|
|
///
|
|
/// Only the *change* into being refused is reported: these arrive
|
|
/// repeatedly, and a `LimitReached` per line would be a transcript full
|
|
/// of them.
|
|
fn translate_rate_limit(&mut self, message: &Value) -> Vec<Event> {
|
|
let info = &message["rate_limit_info"];
|
|
let status = info.get("status").and_then(Value::as_str);
|
|
let refused = !matches!(status, None | Some("allowed"))
|
|
&& !status.is_some_and(|status| status.starts_with("allowed"));
|
|
if refused && !status.is_some_and(is_known_refusal) {
|
|
tracing::warn!(
|
|
"unrecognised rate limit status {status:?}, read as out of quota -- see translate_rate_limit"
|
|
);
|
|
}
|
|
let was = std::mem::replace(&mut self.rate_limited, refused);
|
|
if !refused || was {
|
|
return Vec::new();
|
|
}
|
|
vec![Event::LimitReached {
|
|
resets_at: info.get("resetsAt").and_then(Value::as_f64),
|
|
}]
|
|
}
|
|
|
|
/// The CLI's own account of a subagent's life, and **the only thing that
|
|
/// ends one**.
|
|
///
|
|
/// Measured against 2.1.237 on 2026-09-06 by running a session that
|
|
/// launched one Task agent and reading its stdout. A task produces, in
|
|
/// order and all as top-level `system` lines with no `parent_tool_use_id`:
|
|
///
|
|
/// - `task_started` -- `task_id`, `tool_use_id`, `description`,
|
|
/// `subagent_type`, `is_backgrounded`, `prompt`;
|
|
/// - `task_progress` -- `last_tool_name` and usage, repeatedly;
|
|
/// - `task_updated` -- `{patch: {status, end_time}}`, carrying the
|
|
/// `task_id` but **not** the tool id;
|
|
/// - `task_notification` -- `tool_use_id`, `status`, and `summary`: the
|
|
/// agent's own report, which is also what the parent's `tool_result`
|
|
/// for the Task call is given.
|
|
///
|
|
/// What that run also showed is why this exists: **the child lines carry
|
|
/// no `stream_event` at all.** A subagent's own output arrives as whole
|
|
/// `user`/`assistant` lines whose `stop_reason` is `null`, and no `result`
|
|
/// line is ever sent for one -- so [`ends_a_turn`], which watches for a
|
|
/// raw `message_delta` saying `end_turn`, cannot fire for a subagent in
|
|
/// this version, and every subagent stayed `Running` until its session's
|
|
/// process exited. The task lines are the CLI saying it outright, for a
|
|
/// backgrounded agent and a synchronous one alike, which is what the
|
|
/// parent's `tool_result` could not do.
|
|
///
|
|
/// The summary is recorded as the subagent's own closing text because it
|
|
/// is the one thing it says that never reaches its transcript otherwise:
|
|
/// the run above ended the child lines at its last `tool_result`, so
|
|
/// without this a finished subagent reads as stopping mid-tool.
|
|
fn translate_task(&mut self, message: &Value) -> Vec<Event> {
|
|
let task_id = message.get("task_id").and_then(Value::as_str);
|
|
let tool_use_id = message.get("tool_use_id").and_then(Value::as_str);
|
|
if let (Some(task), Some(tool)) = (task_id, tool_use_id) {
|
|
self.tasks.insert(task.to_string(), tool.to_string());
|
|
}
|
|
// The tool call this line is about, from the line itself or from
|
|
// whichever earlier line did carry it.
|
|
let about = tool_use_id
|
|
.map(str::to_string)
|
|
.or_else(|| task_id.and_then(|task| self.tasks.get(task).cloned()));
|
|
match message.get("subtype").and_then(Value::as_str) {
|
|
Some("task_notification") => self.task_ended(
|
|
about,
|
|
message.get("status").and_then(Value::as_str),
|
|
text_field(message, "summary"),
|
|
),
|
|
Some("task_updated") => {
|
|
let status = message
|
|
.get("patch")
|
|
.and_then(|patch| patch.get("status"))
|
|
.and_then(Value::as_str);
|
|
// `completed` deliberately does nothing here: the
|
|
// `task_notification` a completed task is always followed by
|
|
// is what carries its summary, and ending it on this earlier
|
|
// line would put that summary after the ending. Every other
|
|
// way a task can stop is taken at face value -- a task that
|
|
// failed or was cancelled has not been observed here, and the
|
|
// failure to avoid is the one this whole function exists for:
|
|
// a subagent that nothing ever finishes.
|
|
if status == Some("completed") {
|
|
return Vec::new();
|
|
}
|
|
self.task_ended(about, status, None)
|
|
}
|
|
Some("task_started") => {
|
|
// What makes the session `Waiting` when its turn ends. The
|
|
// subagent itself is created by the Task `tool_use` in the
|
|
// parent's own message, which arrives first and carries the
|
|
// title this side shows.
|
|
if let Some(about) = about {
|
|
self.open_tasks.insert(about);
|
|
}
|
|
Vec::new()
|
|
}
|
|
// `task_progress`: the mapping above is the whole of what it is
|
|
// for.
|
|
_ => Vec::new(),
|
|
}
|
|
}
|
|
|
|
/// Whether the session has work of its own still running: the difference
|
|
/// between `Idle` and [`SessionStatus::Waiting`].
|
|
///
|
|
/// Two sources because neither covers the other. `open_tasks` holds what
|
|
/// this translator watched start, which is the only thing that knows
|
|
/// about a backgrounded *command* -- it has no subagent. The registry
|
|
/// holds what is on disk, which is the only thing that knows about a
|
|
/// subagent that started before this translator did.
|
|
///
|
|
/// `session_running` is true by construction: this is only ever asked
|
|
/// while translating a line the session's process just wrote.
|
|
fn work_outstanding(&self) -> bool {
|
|
!self.open_tasks.is_empty() || self.subagents.any_open(true)
|
|
}
|
|
|
|
/// A task reporting back, from whichever of the two lines got here first.
|
|
///
|
|
/// Handled once. The two shapes can both arrive for one task, and what
|
|
/// says which of them is the first is that it finds the task still open.
|
|
///
|
|
/// **Nothing about it reaches the parent's transcript**, deliberately.
|
|
/// The summary is the subagent's own closing words and goes into the
|
|
/// subagent's own transcript, which is the only place it belongs; a row
|
|
/// per finished task in the session's transcript is a screen of dividers
|
|
/// about work the reader was not asking after, and the session did not
|
|
/// receive a message it could act on. What *does* reach the parent is a
|
|
/// message a subagent genuinely sends it, which arrives by the peer
|
|
/// path. The only thing produced here is the status: a session with
|
|
/// nothing outstanding any more has stopped being
|
|
/// [`SessionStatus::Waiting`].
|
|
fn task_ended(
|
|
&mut self,
|
|
about: Option<String>,
|
|
status: Option<&str>,
|
|
summary: Option<String>,
|
|
) -> Vec<Event> {
|
|
if !ended(status) {
|
|
return Vec::new();
|
|
}
|
|
let Some(about) = about else {
|
|
return Vec::new();
|
|
};
|
|
// Reported once. The two lifecycle shapes can both arrive for one
|
|
// task, and whichever gets here first is the one that finds it open.
|
|
//
|
|
// The registry is asked as well as this translator's own set, and
|
|
// that is what makes an adopted session work: a subagent launched
|
|
// before a backend restart has no entry here, because its
|
|
// `task_started` is behind the offset its session's stdout is read
|
|
// from. `finish` below closes it either way, so a second line for the
|
|
// same task still finds nothing.
|
|
if !self.open_tasks.remove(&about) && !self.subagents.is_open(&about) {
|
|
return Vec::new();
|
|
}
|
|
let mut events = Vec::new();
|
|
// Where the report goes, and the two cases are not the same place.
|
|
//
|
|
// A subagent has a transcript of its own, and its closing words are
|
|
// that transcript's last line -- see `SUBAGENTS.md`. A backgrounded
|
|
// *command* has none: its own tool card is the only record of it
|
|
// anywhere, and until this arrives that card is still showing the
|
|
// launch result, which says the command is running. It stopped being
|
|
// true at this line, so the card is brought up to date rather than
|
|
// left making a claim nothing will ever correct.
|
|
if self.subagents.get(&about).is_some() {
|
|
if let Some(summary) = summary {
|
|
self.subagents
|
|
.record(&about, Event::AssistantText { delta: summary });
|
|
}
|
|
} else {
|
|
events.push(Event::ToolUpdate {
|
|
id: about.clone(),
|
|
// A task that stopped without a word still has to say so: the
|
|
// states with no summary are exactly the ones that went
|
|
// wrong, and they are the ones a stale "running in
|
|
// background" reads worst on.
|
|
output: summary
|
|
.unwrap_or_else(|| format!("this background command {}", status_word(status))),
|
|
});
|
|
}
|
|
self.subagents.finish(&about);
|
|
// The last outstanding task, with the session's own turn already
|
|
// over: it has stopped being `Waiting` and nothing else will say so.
|
|
// Inside a turn there is nothing to announce -- the turn's own
|
|
// `result` will decide between the two statuses when it lands.
|
|
if !self.work_outstanding() && !self.in_turn {
|
|
events.push(Event::Status {
|
|
state: SessionStatus::Idle,
|
|
});
|
|
}
|
|
events
|
|
}
|
|
|
|
/// A null `status` is the leaving edge, and it carries how the thing went.
|
|
/// The turn it happened inside is still going when it ends -- the `result`
|
|
/// has not arrived -- so leaving says `Running`. A state this build does
|
|
/// not recognise is left alone rather than mapped onto the nearest one.
|
|
fn translate_status(&self, message: &Value) -> Vec<Event> {
|
|
// A mode change the CLI has made, announced a moment after it answers
|
|
// the request. Measured on 2.1.237:
|
|
// `{"subtype":"status","status":null,"permissionMode":"plan"}`, which
|
|
// is a leaving edge carrying no compaction result -- so it is checked
|
|
// before the compaction reading below.
|
|
if let Some(mode) = message.get("permissionMode").and_then(Value::as_str) {
|
|
return vec![Event::Settings {
|
|
model: None,
|
|
permission_mode: Some(mode.to_string()),
|
|
}];
|
|
}
|
|
if let Some(status) = message.get("status").and_then(Value::as_str) {
|
|
return match status {
|
|
"compacting" => vec![Event::Status {
|
|
state: SessionStatus::Compacting,
|
|
}],
|
|
_ => Vec::new(),
|
|
};
|
|
}
|
|
let Some(result) = message.get("compact_result").and_then(Value::as_str) else {
|
|
return Vec::new();
|
|
};
|
|
let mut events = Vec::new();
|
|
if result != "success" {
|
|
// The CLI's own sentence, because it is specific enough to act on:
|
|
// "Not enough messages to compact." is a complete answer.
|
|
events.push(Event::Error {
|
|
message: match message.get("compact_error").and_then(Value::as_str) {
|
|
Some(why) => format!("compaction failed: {why}"),
|
|
None => format!("compaction {result}"),
|
|
},
|
|
});
|
|
}
|
|
events.push(Event::Status {
|
|
state: SessionStatus::Running,
|
|
});
|
|
events
|
|
}
|
|
|
|
/// Raw API streaming: only text deltas become events. Consolidated blocks
|
|
/// arriving later re-carry the same text, so those are skipped in
|
|
/// `translate_assistant` -- one source per fact.
|
|
fn translate_stream_event(&mut self, event: &Value) -> Vec<Event> {
|
|
if event.get("type").and_then(Value::as_str) == Some("content_block_delta")
|
|
&& let Some(delta) = event["delta"].get("text")
|
|
&& event["delta"].get("type").and_then(Value::as_str) == Some("text_delta")
|
|
&& let Some(text) = delta.as_str()
|
|
{
|
|
return vec![Event::AssistantText {
|
|
delta: text.to_string(),
|
|
}];
|
|
}
|
|
Vec::new()
|
|
}
|
|
|
|
fn translate_assistant(&mut self, message: &Value) -> Vec<Event> {
|
|
if let Some(usage) = message.get("usage") {
|
|
let field = |name: &str| usage.get(name).and_then(Value::as_u64).unwrap_or(0);
|
|
self.context = Some(context_tokens(
|
|
field("input_tokens"),
|
|
field("cache_creation_input_tokens"),
|
|
field("cache_read_input_tokens"),
|
|
));
|
|
}
|
|
let Some(content) = message.get("content").and_then(Value::as_array) else {
|
|
return Vec::new();
|
|
};
|
|
content
|
|
.iter()
|
|
.filter(|block| block.get("type").and_then(Value::as_str) == Some("tool_use"))
|
|
.map(|block| {
|
|
let id = block
|
|
.get("id")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or_default()
|
|
.to_string();
|
|
let tool = block
|
|
.get("name")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or_default()
|
|
.to_string();
|
|
let input = block.get("input").cloned().unwrap_or(Value::Null);
|
|
// A subagent this call is about to start -- see
|
|
// `SUBAGENTS.md`'s lifecycle #1. The parent's own transcript
|
|
// still shows only the Task call itself, below.
|
|
if tool == "Task" || tool == "Agent" {
|
|
self.start_subagent_from_task(&id, &input);
|
|
}
|
|
if tool == "Edit" {
|
|
self.patches.insert(id.clone());
|
|
patch_start(id, replacement_diff(&input))
|
|
} else {
|
|
Event::ToolStart { id, tool, input }
|
|
}
|
|
})
|
|
.collect()
|
|
}
|
|
|
|
/// Starts the subagent a Task call names, with the title and prompt
|
|
/// SUBAGENTS.md describes: the call's `description`, then
|
|
/// `(<subagent_type>)` when one is given, falling back to the tool's own
|
|
/// name when there is no description to build one from.
|
|
fn start_subagent_from_task(&self, id: &str, input: &Value) {
|
|
let description = text_field(input, "description");
|
|
let subagent_type = text_field(input, "subagent_type");
|
|
let prompt = input.get("prompt").and_then(Value::as_str);
|
|
let title = match (description, subagent_type) {
|
|
(Some(description), Some(subagent_type)) => {
|
|
format!("{description} ({subagent_type})")
|
|
}
|
|
(Some(description), None) => description,
|
|
(None, _) => "Task".to_string(),
|
|
};
|
|
self.subagents.start(id, &title, prompt);
|
|
}
|
|
|
|
fn translate_control_request(&mut self, message: &Value) -> Vec<Event> {
|
|
let request = &message["request"];
|
|
if request.get("subtype").and_then(Value::as_str) != Some("can_use_tool") {
|
|
return Vec::new();
|
|
}
|
|
let request_id = message
|
|
.get("request_id")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or_default()
|
|
.to_string();
|
|
let tool_name = request
|
|
.get("tool_name")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or("a tool");
|
|
let input = request.get("input").cloned().unwrap_or(Value::Null);
|
|
// Measured, not matched: the request names the call it is about, so the
|
|
// phone never has to guess which tool row a permission belongs to.
|
|
let about = request
|
|
.get("tool_use_id")
|
|
.and_then(Value::as_str)
|
|
.map(String::from);
|
|
|
|
let mut events = Vec::new();
|
|
let mut questions = Vec::new();
|
|
if tool_name == "AskUserQuestion" {
|
|
for (i, question) in input
|
|
.get("questions")
|
|
.and_then(Value::as_array)
|
|
.into_iter()
|
|
.flatten()
|
|
.enumerate()
|
|
{
|
|
let text = question
|
|
.get("question")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or("(question)")
|
|
.to_string();
|
|
// Everything the reader decides on, carried in the event. The
|
|
// alternative -- and what this was -- is the phone reaching into
|
|
// the tool call's input for the parts the event dropped, which
|
|
// puts this dialect's schema where no other dialect can reach it.
|
|
let options = question
|
|
.get("options")
|
|
.and_then(Value::as_array)
|
|
.into_iter()
|
|
.flatten()
|
|
.filter_map(|option| {
|
|
Some(QuestionOption {
|
|
label: option.get("label").and_then(Value::as_str)?.to_string(),
|
|
description: text_field(option, "description"),
|
|
preview: text_field(option, "preview"),
|
|
})
|
|
})
|
|
.collect();
|
|
events.push(Event::Question {
|
|
id: format!("{request_id}#{i}"),
|
|
prompt: text.clone(),
|
|
header: text_field(question, "header"),
|
|
options,
|
|
multi_select: question
|
|
.get("multiSelect")
|
|
.and_then(Value::as_bool)
|
|
.unwrap_or(false),
|
|
// The call that is asking, so all of this draws as one
|
|
// thing. It used to be `None` on the grounds that a question
|
|
// the model asked is not permission for a call -- true, and
|
|
// beside the point: the reader was shown the AskUserQuestion
|
|
// call *and* its questions as two separate cards.
|
|
about: about.clone(),
|
|
});
|
|
questions.push(text);
|
|
}
|
|
} else {
|
|
let summary = serde_json::to_string_pretty(&input).unwrap_or_default();
|
|
let summary: String = summary.chars().take(600).collect();
|
|
events.push(Event::Question {
|
|
id: request_id.clone(),
|
|
prompt: format!("Allow {tool_name}?\n{summary}"),
|
|
// No header: the question is about the call it names, and the
|
|
// phone draws it on that call's own row.
|
|
header: None,
|
|
options: vec![
|
|
QuestionOption::plain("Allow"),
|
|
QuestionOption::plain("Deny"),
|
|
],
|
|
multi_select: false,
|
|
about: about.clone(),
|
|
});
|
|
}
|
|
self.pending.insert(
|
|
request_id.clone(),
|
|
PendingRequest {
|
|
request_id,
|
|
input,
|
|
questions,
|
|
answers: HashMap::new(),
|
|
},
|
|
);
|
|
events.push(Event::Status {
|
|
state: SessionStatus::AwaitingInput,
|
|
});
|
|
events
|
|
}
|
|
|
|
/// Applies one answer from the phone. Question ids are the control request
|
|
/// id, suffixed `#i` for AskUserQuestion sub-questions.
|
|
pub(super) fn answer(&mut self, question_id: &str, answers: &[String]) -> AnswerOutcome {
|
|
// Where this dialect's shape is put on: the CLI's `answers` map is
|
|
// string-valued whatever the question, so several choices become one
|
|
// line here rather than everything upstream pretending a question can
|
|
// only ever have one answer.
|
|
let answer = answers.join(", ");
|
|
let answer = answer.as_str();
|
|
let (request_id, sub) = match question_id.split_once('#') {
|
|
Some((request_id, index)) => (request_id, index.parse::<usize>().ok()),
|
|
None => (question_id, None),
|
|
};
|
|
let Some(pending) = self.pending.get_mut(request_id) else {
|
|
return AnswerOutcome::Unknown;
|
|
};
|
|
|
|
let response = if let Some(index) = sub {
|
|
let Some(question) = pending.questions.get(index) else {
|
|
return AnswerOutcome::Unknown;
|
|
};
|
|
pending.answers.insert(question.clone(), answer.to_string());
|
|
if pending.answers.len() < pending.questions.len() {
|
|
return AnswerOutcome::Pending;
|
|
}
|
|
let mut updated = pending.input.clone();
|
|
updated["answers"] = serde_json::to_value(&pending.answers).expect("string map");
|
|
json!({"behavior": "allow", "updatedInput": updated})
|
|
} else if answer.eq_ignore_ascii_case("deny") {
|
|
json!({"behavior": "deny", "message": "The user denied this from the phone."})
|
|
} else {
|
|
json!({"behavior": "allow", "updatedInput": pending.input})
|
|
};
|
|
|
|
let request_id = pending.request_id.clone();
|
|
self.pending.remove(&request_id);
|
|
AnswerOutcome::Respond(json!({
|
|
"type": "control_response",
|
|
"response": {"subtype": "success", "request_id": request_id, "response": response},
|
|
}))
|
|
}
|
|
|
|
/// `user` messages: tool results become ToolEnd, with any image parts saved
|
|
/// into the session dir and referenced by an Image event. Replayed and
|
|
/// synthetic user text is skipped -- the manager already recorded the
|
|
/// user's side.
|
|
fn translate_user(&mut self, message: &Value) -> Vec<Event> {
|
|
// Only tool results are here. The CLI never echoes a person's own
|
|
// message back on stdout -- measured, because the obvious way to learn
|
|
// that a queued message had been taken was to watch for it coming back
|
|
// -- so the driver reports that itself, at the line it writes.
|
|
let Some(content) = message["message"].get("content").and_then(Value::as_array) else {
|
|
return Vec::new();
|
|
};
|
|
let mut events = Vec::new();
|
|
for block in content {
|
|
if block.get("type").and_then(Value::as_str) != Some("tool_result") {
|
|
continue;
|
|
}
|
|
let mut texts = Vec::new();
|
|
// Held until the call's id is in hand a few lines below: an image is
|
|
// drawn under the call that produced it, so it has to carry that id.
|
|
let mut images = Vec::new();
|
|
match block.get("content") {
|
|
Some(Value::String(text)) => texts.push(text.clone()),
|
|
Some(Value::Array(parts)) => {
|
|
for part in parts {
|
|
match part.get("type").and_then(Value::as_str) {
|
|
Some("text") => {
|
|
if let Some(text) = part.get("text").and_then(Value::as_str) {
|
|
texts.push(text.to_string());
|
|
}
|
|
}
|
|
Some("image") => {
|
|
if let Some(name) = save_image(&self.session_dir, part) {
|
|
images.push(name);
|
|
}
|
|
}
|
|
_ => {}
|
|
}
|
|
}
|
|
}
|
|
_ => {}
|
|
}
|
|
let about = block
|
|
.get("tool_use_id")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or_default()
|
|
.to_string();
|
|
let patch = self.patches.remove(&about);
|
|
if patch && block.get("is_error").and_then(Value::as_bool) != Some(true) {
|
|
texts.clear();
|
|
}
|
|
for image in images {
|
|
events.push(Event::Image {
|
|
image,
|
|
about: Some(about.clone()),
|
|
});
|
|
}
|
|
events.push(Event::ToolEnd {
|
|
id: about.clone(),
|
|
output: texts.join("\n"),
|
|
});
|
|
// Deliberately does *not* finish a subagent `about` might name:
|
|
// the Task tool runs in the background by default, so this
|
|
// `tool_result` -- "Async agent launched..." -- arrives at
|
|
// launch, long before the subagent's own work is done. What
|
|
// ends it is its own turn ending, handled in `translate_child`.
|
|
}
|
|
events
|
|
}
|
|
}
|
|
|
|
fn replacement_diff(input: &Value) -> String {
|
|
let path = input
|
|
.get("file_path")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or("file");
|
|
let old = input
|
|
.get("old_string")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or_default();
|
|
let new = input
|
|
.get("new_string")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or_default();
|
|
format!(
|
|
"--- {path}\n+++ {path}\n@@\n{}{}",
|
|
prefixed_lines('-', old),
|
|
prefixed_lines('+', new)
|
|
)
|
|
}
|
|
|
|
fn prefixed_lines(prefix: char, text: &str) -> String {
|
|
text.split_inclusive('\n')
|
|
.map(|line| {
|
|
if line.ends_with('\n') {
|
|
format!("{prefix}{line}")
|
|
} else {
|
|
format!("{prefix}{line}\n")
|
|
}
|
|
})
|
|
.collect()
|
|
}
|
|
|
|
/// The title to start a subagent under when its own first line arrives
|
|
/// before (or without) its Task call ever being seen: the tool name of that
|
|
/// first line, which is the only thing known about it yet. `"subagent"` for
|
|
/// a line this cannot even find a tool name in, such as one that opens with
|
|
/// something other than a tool call.
|
|
fn fallback_title(message: &Value) -> String {
|
|
message["message"]["content"]
|
|
.as_array()
|
|
.into_iter()
|
|
.flatten()
|
|
.find(|block| block.get("type").and_then(Value::as_str) == Some("tool_use"))
|
|
.and_then(|block| block.get("name"))
|
|
.and_then(Value::as_str)
|
|
.unwrap_or("subagent")
|
|
.to_string()
|
|
}
|
|
|
|
/// Whether this line is a subagent's *own* turn ending -- the only thing
|
|
/// that does, per `SUBAGENTS.md`: not the parent's `tool_result`, which for
|
|
/// a background Task arrives at launch rather than at completion.
|
|
///
|
|
/// Checked on the raw line rather than on what `dispatch` returns, so this
|
|
/// never has to touch the shared `translate_stream_event`/`dispatch` code a
|
|
/// top-level session's own turn-ending also goes through -- a subagent's
|
|
/// idea of "ended" must not change when a real session's does.
|
|
///
|
|
/// `message_delta` is the raw API's own signal, carrying the stop reason:
|
|
/// `end_turn` is genuinely done, `tool_use` means the model is about to call
|
|
/// one and there is more coming. A `result` line is the CLI's own shape for
|
|
/// a top-level turn.
|
|
///
|
|
/// **Neither has been observed on a subagent's lines in 2.1.237** -- see
|
|
/// [`Translator::translate_task`], which is what actually ends one, and which
|
|
/// exists because relying on this alone left every subagent running for ever.
|
|
/// Kept because it costs nothing and a dialect that does send either would be
|
|
/// saying exactly what it means; it must never be the only detector again.
|
|
/// The words `rate_limit_info.status` has been seen or documented to use for
|
|
/// "no". Only used to decide whether to *log* an unfamiliar one: an unknown
|
|
/// status is treated as a refusal either way, since a limit missed is a
|
|
/// session that never comes back.
|
|
fn is_known_refusal(status: &str) -> bool {
|
|
matches!(status, "rejected" | "blocked" | "exceeded" | "limited")
|
|
}
|
|
|
|
/// Whether this event is the end of a turn: the two statuses a turn can
|
|
/// finish in, and no others.
|
|
///
|
|
/// A sibling of [`super::proves_a_turn`] and deliberately shaped like it --
|
|
/// see [`Translator::in_turn`]. `Exited` is not here: a process that has gone
|
|
/// ends the session rather than the turn, and nothing after it can start one.
|
|
fn closes_a_turn(event: &Event) -> bool {
|
|
matches!(
|
|
event,
|
|
Event::Status {
|
|
state: SessionStatus::Idle | SessionStatus::Waiting
|
|
}
|
|
)
|
|
}
|
|
|
|
/// A task's ending in a word, for a card that has to say what became of it.
|
|
///
|
|
/// `ended` has already said this is an ending, so the fallback is not "still
|
|
/// going" -- it is the honest answer for an ending this build has no word for,
|
|
/// which is that nobody here knows which it was.
|
|
fn status_word(status: Option<&str>) -> &str {
|
|
status.unwrap_or("ended, and this build cannot say how")
|
|
}
|
|
|
|
/// Whether a task status word means the task is over.
|
|
///
|
|
/// Written as "not one of the words that mean it is still going" rather than
|
|
/// as a list of endings, because the two are not symmetric here: a status
|
|
/// this build has never seen is far more likely to be a new way of finishing
|
|
/// than a new way of continuing, and guessing wrong in that direction leaves
|
|
/// a subagent reading `running` for ever with nothing able to correct it.
|
|
/// Nothing at all is *not* an ending: a line that said no status said nothing.
|
|
fn ended(status: Option<&str>) -> bool {
|
|
!matches!(
|
|
status,
|
|
None | Some("running" | "in_progress" | "pending" | "queued" | "started")
|
|
)
|
|
}
|
|
|
|
fn ends_a_turn(message: &Value) -> bool {
|
|
match message.get("type").and_then(Value::as_str) {
|
|
Some("stream_event") => {
|
|
let event = &message["event"];
|
|
event.get("type").and_then(Value::as_str) == Some("message_delta")
|
|
&& event["delta"].get("stop_reason").and_then(Value::as_str) == Some("end_turn")
|
|
}
|
|
Some("result") => true,
|
|
_ => false,
|
|
}
|
|
}
|
|
|
|
/// Whether a failed turn failed because the account is out of quota, and when
|
|
/// the CLI said the limit lifts.
|
|
///
|
|
/// The wording is the CLI's: a turn stopped by the limit ends with `is_error`
|
|
/// and a result of `Claude AI usage limit reached|1788546972`, the reset being
|
|
/// epoch seconds after a pipe. Matched on the sentence rather than on a code
|
|
/// because the CLI sends none, so this is deliberately loose about everything
|
|
/// but the four words.
|
|
///
|
|
/// The two `None`s mean different things and both are real. The outer one is
|
|
/// "some other failure". The inner one is "the limit is reached and the CLI did
|
|
/// not say until when" -- which is not a reason to invent a time: `crate::resume`
|
|
/// asks the usage endpoint before sending anything, and that answer is the one
|
|
/// that decides.
|
|
///
|
|
/// Milliseconds are accepted as well as seconds and told apart by magnitude,
|
|
/// since a wrong guess would schedule a resume tens of thousands of years out
|
|
/// and look exactly like auto-resume being broken.
|
|
fn usage_limit(result: &str) -> Option<Option<f64>> {
|
|
if !result.to_ascii_lowercase().contains("usage limit reached") {
|
|
return None;
|
|
}
|
|
let stamp = result
|
|
.rsplit('|')
|
|
.next()
|
|
.and_then(|tail| tail.trim().parse::<f64>().ok())
|
|
.filter(|stamp| *stamp > 0.0)
|
|
.map(|stamp| if stamp > 1e11 { stamp / 1000.0 } else { stamp });
|
|
Some(stamp)
|
|
}
|
|
|
|
/// A string field that is there and not empty, or `None`. The CLI omits these
|
|
/// rather than sending them empty, but a caller that sends `""` means the same
|
|
/// thing and should not produce a description that draws as a blank line.
|
|
fn text_field(value: &Value, name: &str) -> Option<String> {
|
|
value
|
|
.get(name)
|
|
.and_then(Value::as_str)
|
|
.filter(|text| !text.trim().is_empty())
|
|
.map(str::to_string)
|
|
}
|
|
|
|
/// Decodes one base64 image block into `files/` and returns its ref.
|
|
///
|
|
/// A free function rather than a method because the import replay needs exactly
|
|
/// this too: a session's history carries the same image blocks as its live
|
|
/// output. Two copies would be two naming schemes for one directory.
|
|
pub(in crate::session) fn save_image(session_dir: &Path, part: &Value) -> Option<String> {
|
|
let source = part.get("source")?;
|
|
let data = source.get("data")?.as_str()?;
|
|
use base64::Engine;
|
|
let bytes = base64::engine::general_purpose::STANDARD
|
|
.decode(data)
|
|
.ok()?;
|
|
// Screenshots are the overwhelming case and they are PNG; an unrecognized type is more likely
|
|
// a dialect change than a JPEG. `store_image` owns that fallback.
|
|
let media_type = source
|
|
.get("media_type")
|
|
.and_then(Value::as_str)
|
|
.unwrap_or("image/png");
|
|
super::super::driver::store_image(session_dir, media_type, &bytes)
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
/// What a phone sends back: everything chosen, even when that is one.
|
|
fn chose(answer: &str) -> Vec<String> {
|
|
vec![answer.to_string()]
|
|
}
|
|
|
|
fn labels(options: &[QuestionOption]) -> Vec<&str> {
|
|
options.iter().map(|option| option.label.as_str()).collect()
|
|
}
|
|
|
|
fn translate_lines(translator: &mut Translator, lines: &[&str]) -> Vec<Event> {
|
|
lines
|
|
.iter()
|
|
.flat_map(|line| translator.translate(&serde_json::from_str(line).expect("json")))
|
|
.collect()
|
|
}
|
|
|
|
/// A fresh, empty subagent registry over the same temp dir a test's
|
|
/// translator writes into -- every test here is about the parent's own
|
|
/// events, so what a registry does with a subagent is `subagent.rs`'s
|
|
/// tests to make, not these.
|
|
fn test_subagents(dir: &tempfile::TempDir) -> Arc<Subagents> {
|
|
Arc::new(Subagents::new(dir.path().to_path_buf()))
|
|
}
|
|
|
|
#[test]
|
|
fn captures_the_resume_token_and_the_settings_from_init() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"init","cwd":"/x","session_id":"5ecf21da-d53f","tools":[],"model":"claude-haiku-4-5-20251001","permissionMode":"acceptEdits"}"#,
|
|
],
|
|
);
|
|
assert_eq!(translator.session_id.as_deref(), Some("5ecf21da-d53f"));
|
|
// The resolved model, which is the point: a session launched with
|
|
// `--model haiku` is reported by its full name here.
|
|
assert_eq!(
|
|
events,
|
|
vec![Event::Settings {
|
|
model: Some("claude-haiku-4-5-20251001".to_string()),
|
|
permission_mode: Some("acceptEdits".to_string()),
|
|
}]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_setting_is_reported_when_the_cli_accepts_it_and_not_before() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
|
|
// What `set_model` does: remember, send, and say nothing yet.
|
|
translator.expect_setting("req-a".to_string(), Setting::Model("sonnet".to_string()));
|
|
translator.expect_setting(
|
|
"req-b".to_string(),
|
|
Setting::PermissionMode("plan".to_string()),
|
|
);
|
|
|
|
// Success carries no model of its own -- measured on 2.1.237 -- so what
|
|
// was asked for is the only answer available.
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_response","response":{"subtype":"success","request_id":"req-a"}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![Event::Settings {
|
|
model: Some("sonnet".to_string()),
|
|
permission_mode: None,
|
|
}]
|
|
);
|
|
|
|
// A mode the CLI answers with a value of its own is taken from that
|
|
// value: `auto` on the way in is `default` coming back.
|
|
translator.expect_setting(
|
|
"req-c".to_string(),
|
|
Setting::PermissionMode("auto".to_string()),
|
|
);
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_response","response":{"subtype":"success","request_id":"req-c","response":{"mode":"default"}}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![Event::Settings {
|
|
model: None,
|
|
permission_mode: Some("default".to_string()),
|
|
}]
|
|
);
|
|
|
|
// A refusal changes nothing, and says why rather than claiming a
|
|
// setting that was rejected.
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_response","response":{"subtype":"error","request_id":"req-b","error":"unknown mode"}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![Event::Error {
|
|
message: "claude rejected a request: unknown mode".to_string()
|
|
}]
|
|
);
|
|
|
|
// And neither request is still waiting: a second answer to either id
|
|
// reports nothing at all.
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_response","response":{"subtype":"success","request_id":"req-a"}}"#,
|
|
r#"{"type":"control_response","response":{"subtype":"success","request_id":"req-b"}}"#,
|
|
],
|
|
);
|
|
assert!(events.is_empty(), "{events:?}");
|
|
}
|
|
|
|
#[test]
|
|
fn a_mode_the_cli_announces_is_taken_from_the_announcement() {
|
|
// The line it sends just after answering `set_permission_mode`, which is
|
|
// also how a mode changed from the terminal arrives.
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"status","status":null,"permissionMode":"plan","session_id":"s"}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![Event::Settings {
|
|
model: None,
|
|
permission_mode: Some("plan".to_string()),
|
|
}]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn streams_text_deltas_and_skips_the_consolidated_copy() {
|
|
// Real lines (trimmed) from the 2.1.237 probe.
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"stream_event","event":{"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"Done."}},"session_id":"s","parent_tool_use_id":null}"#,
|
|
r#"{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Done."}]},"parent_tool_use_id":null,"session_id":"s"}"#,
|
|
r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"hmm"}},"session_id":"s","parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![Event::AssistantText {
|
|
delta: "Done.".to_string()
|
|
}]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn tool_use_and_result_become_tool_events() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_01","name":"Bash","input":{"command":"echo probe-ok"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"user","message":{"role":"user","content":[{"tool_use_id":"toolu_01","type":"tool_result","content":"probe-ok","is_error":false}]},"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![
|
|
Event::ToolStart {
|
|
id: "toolu_01".to_string(),
|
|
tool: "Bash".to_string(),
|
|
input: serde_json::json!({"command": "echo probe-ok"}),
|
|
},
|
|
Event::ToolEnd {
|
|
id: "toolu_01".to_string(),
|
|
output: "probe-ok".to_string()
|
|
},
|
|
]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn an_edit_becomes_a_patch_and_drops_only_its_success_boilerplate() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"edit-1","name":"Edit","input":{"file_path":"src/main.rs","old_string":"old","new_string":"new"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"user","message":{"role":"user","content":[{"tool_use_id":"edit-1","type":"tool_result","content":"The file src/main.rs has been updated successfully.","is_error":false}]},"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![
|
|
patch_start(
|
|
"edit-1".to_string(),
|
|
"--- src/main.rs\n+++ src/main.rs\n@@\n-old\n+new\n".to_string()
|
|
),
|
|
Event::ToolEnd {
|
|
id: "edit-1".to_string(),
|
|
output: String::new()
|
|
}
|
|
]
|
|
);
|
|
|
|
let failed = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"edit-2","name":"Edit","input":{"file_path":"src/main.rs","old_string":"missing","new_string":"new"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"user","message":{"role":"user","content":[{"tool_use_id":"edit-2","type":"tool_result","content":"old_string was not found","is_error":true}]},"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
assert!(matches!(
|
|
&failed[1],
|
|
Event::ToolEnd { output, .. } if output == "old_string was not found"
|
|
));
|
|
}
|
|
|
|
#[test]
|
|
fn subagent_events_are_not_duplicated_into_the_transcript() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_02","name":"Bash","input":{}}]},"parent_tool_use_id":"toolu_parent"}"#,
|
|
],
|
|
);
|
|
assert!(events.is_empty());
|
|
}
|
|
|
|
/// A child line does not just vanish from the parent -- it lands in its
|
|
/// own subagent's transcript, with that transcript's own sequence
|
|
/// numbers, starting at 1 like any other.
|
|
#[test]
|
|
fn a_child_line_lands_in_its_own_subagents_transcript() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_c1","name":"Bash","input":{"command":"echo hi"}}]},"parent_tool_use_id":"toolu_parent"}"#,
|
|
],
|
|
);
|
|
let subagent = subagents.get("toolu_parent").expect("subagent started");
|
|
let lines = crate::session::transcript::read_after(&subagent.transcript_path(), 0)
|
|
.expect("read subagent transcript");
|
|
assert_eq!(lines[0].seq, 1);
|
|
assert_eq!(
|
|
lines[0].event,
|
|
Event::Status {
|
|
state: SessionStatus::Running
|
|
}
|
|
);
|
|
assert!(
|
|
lines.iter().any(
|
|
|entry| matches!(&entry.event, Event::ToolStart { tool, .. } if tool == "Bash")
|
|
)
|
|
);
|
|
}
|
|
|
|
/// The title and prompt shown for a subagent come from the Task call
|
|
/// that started it, not from anything guessed at its first line.
|
|
#[test]
|
|
fn the_subagent_takes_its_title_and_prompt_from_the_task_call() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_task","name":"Task","input":{"description":"Investigate the bug","prompt":"Find why X fails","subagent_type":"general-purpose"}}]},"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
let rows = subagents.list(true);
|
|
assert_eq!(rows.len(), 1);
|
|
assert_eq!(rows[0].title, "Investigate the bug (general-purpose)");
|
|
let subagent = subagents.get(&rows[0].id).expect("subagent");
|
|
let lines = crate::session::transcript::read_after(&subagent.transcript_path(), 0)
|
|
.expect("read subagent transcript");
|
|
assert!(lines.iter().any(
|
|
|entry| matches!(&entry.event, Event::UserMessage { text, .. } if text == "Find why X fails")
|
|
));
|
|
}
|
|
|
|
/// The parent's `tool_result` for the Task id is what ends the
|
|
/// subagent -- SUBAGENTS.md's lifecycle #3 -- and nothing else does.
|
|
#[test]
|
|
fn the_parents_tool_result_does_not_finish_the_subagent() {
|
|
// The Task tool runs in the background by default: this
|
|
// `tool_result` is "Async agent launched...", arriving the moment
|
|
// the subagent *starts*, while it goes on working for however long
|
|
// its own turn takes. Finishing it here was the bug -- a running
|
|
// background agent read as "finished" with its transcript truncated
|
|
// at launch.
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_task2","name":"Task","input":{"description":"helper"}}]},"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
let subagent = subagents.get("toolu_task2").expect("subagent started");
|
|
assert!(subagent.is_open());
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_task2","content":"Async agent launched","is_error":false}]},"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
assert!(subagent.is_open());
|
|
}
|
|
|
|
/// The end of a turn is not the end of the work when the session
|
|
/// backgrounded something, and `Idle` says it is. Everything that reads a
|
|
/// status hangs off this: the phone's word for the row, whether a
|
|
/// "finished" notification goes out, and what auto-resume is looking at.
|
|
#[test]
|
|
fn a_turn_that_ends_with_a_task_still_running_is_waiting_rather_than_idle() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
let result = r#"{"type":"result","subtype":"success","is_error":false,"usage":{}}"#;
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_bg","name":"Task","input":{"description":"the Dev Updater agent"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"system","subtype":"task_started","task_id":"t1","tool_use_id":"toolu_bg","is_backgrounded":true}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
translate_lines(&mut translator, &[result]).last(),
|
|
Some(&Event::Status {
|
|
state: SessionStatus::Waiting
|
|
})
|
|
);
|
|
|
|
// The task reports back: the message the session received, and only
|
|
// now the session is genuinely waiting for a person.
|
|
assert_eq!(
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_notification","task_id":"t1","tool_use_id":"toolu_bg","status":"completed","summary":"pushed as c41c36f"}"#,
|
|
],
|
|
),
|
|
vec![Event::Status {
|
|
state: SessionStatus::Idle
|
|
}]
|
|
);
|
|
|
|
// Reported once. The two lifecycle shapes can both arrive for one
|
|
// task, and a second row for it would be a message that never came.
|
|
assert!(
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_updated","task_id":"t1","patch":{"status":"failed"}}"#,
|
|
],
|
|
)
|
|
.is_empty()
|
|
);
|
|
|
|
// And with nothing outstanding, the next turn ends idle as before.
|
|
assert_eq!(
|
|
translate_lines(&mut translator, &[result]).last(),
|
|
Some(&Event::Status {
|
|
state: SessionStatus::Idle
|
|
})
|
|
);
|
|
}
|
|
|
|
/// A backgrounded command is a task with no subagent behind it, so there is
|
|
/// no second transcript for its report to live in -- its own tool card is
|
|
/// the only record of it anywhere, and until the notification arrives that
|
|
/// card is still showing the launch result saying it is running.
|
|
#[test]
|
|
fn a_backgrounded_command_reports_into_the_card_that_launched_it() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_started","task_id":"bg1","tool_use_id":"toolu_sh","is_backgrounded":true}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_notification","task_id":"bg1","tool_use_id":"toolu_sh","status":"completed","summary":"Background command \"run the tests\" completed (exit code 0)"}"#,
|
|
],
|
|
),
|
|
vec![
|
|
Event::ToolUpdate {
|
|
id: "toolu_sh".into(),
|
|
output: r#"Background command "run the tests" completed (exit code 0)"#.into(),
|
|
},
|
|
Event::Status {
|
|
state: SessionStatus::Idle
|
|
},
|
|
]
|
|
);
|
|
assert!(
|
|
subagents.get("toolu_sh").is_none(),
|
|
"a command is not a subagent and must not become one"
|
|
);
|
|
}
|
|
|
|
/// The states with no summary are exactly the ones that went wrong, and a
|
|
/// card left saying "running in background" is the worst thing to leave on
|
|
/// screen for them.
|
|
#[test]
|
|
fn a_backgrounded_command_that_failed_says_so_rather_than_saying_nothing() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), subagents);
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_started","task_id":"bg2","tool_use_id":"toolu_sh2","is_backgrounded":true}"#,
|
|
],
|
|
);
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_updated","task_id":"bg2","patch":{"status":"failed"}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events.first(),
|
|
Some(&Event::ToolUpdate {
|
|
id: "toolu_sh2".into(),
|
|
output: "this background command failed".into(),
|
|
})
|
|
);
|
|
}
|
|
|
|
/// The case a backend restart produces, which is every subagent a session
|
|
/// has when the server is updated under it. Adoption picks the session's
|
|
/// stdout back up from a recorded offset, so the `task_started` lines for
|
|
/// anything already running are behind it and this translator never sees
|
|
/// them: it starts empty, and asking only itself would report the session
|
|
/// idle with a subagent plainly still working.
|
|
#[test]
|
|
fn a_subagent_that_started_before_this_translator_still_counts_as_outstanding() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
// Started by somebody else, exactly as a previous run of the server
|
|
// would have left it on disk.
|
|
subagents.start("toolu_old", "the Dev Updater agent", None);
|
|
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
let result = r#"{"type":"result","subtype":"success","is_error":false,"usage":{}}"#;
|
|
assert_eq!(
|
|
translate_lines(&mut translator, &[result]).last(),
|
|
Some(&Event::Status {
|
|
state: SessionStatus::Waiting
|
|
}),
|
|
"the registry knows about it even though this translator does not"
|
|
);
|
|
|
|
// And its ending is reported, though nothing here saw it begin.
|
|
assert_eq!(
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_notification","task_id":"old","tool_use_id":"toolu_old","status":"completed","summary":"pushed"}"#,
|
|
],
|
|
),
|
|
vec![Event::Status {
|
|
state: SessionStatus::Idle
|
|
}]
|
|
);
|
|
// Once: `finish` closed it, so the second shape finds nothing.
|
|
assert!(
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_updated","task_id":"old","patch":{"status":"failed"}}"#,
|
|
],
|
|
)
|
|
.is_empty()
|
|
);
|
|
}
|
|
|
|
/// A task ending *inside* a turn says nothing about the session's status:
|
|
/// the turn is still running, and its own `result` decides. Without the
|
|
/// `in_turn` guard this reported the session idle in the middle of one,
|
|
/// which releases the message queue and tells every phone the work is
|
|
/// over.
|
|
#[test]
|
|
fn a_task_ending_during_a_turn_does_not_report_the_session_idle() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_fg","name":"Task","input":{"description":"a helper"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"system","subtype":"task_started","task_id":"t2","tool_use_id":"toolu_fg","is_backgrounded":false}"#,
|
|
r#"{"type":"stream_event","event":{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"still going"}},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"system","subtype":"task_notification","task_id":"t2","tool_use_id":"toolu_fg","status":"completed","summary":"done"}"#,
|
|
],
|
|
);
|
|
assert!(
|
|
!events.iter().any(closes_a_turn),
|
|
"the turn has not ended: {events:?}"
|
|
);
|
|
// The helper's summary went where it belongs and nowhere else.
|
|
let subagent = subagents.get("toolu_fg").expect("subagent started");
|
|
let lines =
|
|
crate::session::transcript::read_after(&subagent.transcript_path(), 0).expect("read");
|
|
assert!(
|
|
lines.iter().any(|entry| matches!(
|
|
&entry.event,
|
|
Event::AssistantText { delta } if delta == "done"
|
|
)),
|
|
"{lines:?}"
|
|
);
|
|
}
|
|
|
|
/// A background subagent can still be working long after its parent's own
|
|
/// turn ended, so the account running out while one is mid-flight is the
|
|
/// ordinary shape of the problem rather than an edge of it. The limit
|
|
/// belongs in the subagent's transcript *and* has to reach the session,
|
|
/// which is the only thing `crate::resume` can schedule against.
|
|
#[test]
|
|
fn a_limit_a_subagent_hits_reaches_the_session_as_well_as_the_subagent() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_lim","name":"Task","input":{"description":"a helper"}}]},"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
let hit = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"error","is_error":true,"result":"Claude usage limit reached|1788726600","usage":{},"parent_tool_use_id":"toolu_lim"}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
hit,
|
|
vec![Event::LimitReached {
|
|
resets_at: Some(1788726600.0)
|
|
}],
|
|
"the session has to hear about it, or nothing resumes"
|
|
);
|
|
let subagent = subagents.get("toolu_lim").expect("subagent started");
|
|
let lines =
|
|
crate::session::transcript::read_after(&subagent.transcript_path(), 0).expect("read");
|
|
assert!(
|
|
lines
|
|
.iter()
|
|
.any(|entry| matches!(entry.event, Event::LimitReached { .. })),
|
|
"and so does the transcript it happened in: {lines:?}"
|
|
);
|
|
}
|
|
|
|
/// The second limit detector, on the shape the CLI actually sends. The
|
|
/// `allowed` line is copied from a real 2.1.237 run on 2026-09-06; the
|
|
/// refused one is the same line with the status changed, which is the
|
|
/// part that has not been observed and is why an unknown word counts as
|
|
/// refused.
|
|
#[test]
|
|
fn a_rate_limit_event_that_is_not_allowed_reports_the_limit_once() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), subagents);
|
|
let allowed = r#"{"type":"rate_limit_event","rate_limit_info":{"status":"allowed","resetsAt":1788726600,"rateLimitType":"five_hour"}}"#;
|
|
let refused = r#"{"type":"rate_limit_event","rate_limit_info":{"status":"rejected","resetsAt":1788726600,"rateLimitType":"five_hour"}}"#;
|
|
assert!(translate_lines(&mut translator, &[allowed]).is_empty());
|
|
assert_eq!(
|
|
translate_lines(&mut translator, &[refused]),
|
|
vec![Event::LimitReached {
|
|
resets_at: Some(1788726600.0)
|
|
}]
|
|
);
|
|
// Repeats say nothing: these arrive throughout a turn, and the
|
|
// schedule was made by the first one.
|
|
assert!(translate_lines(&mut translator, &[refused]).is_empty());
|
|
// Allowed again, then refused again, is a new limit and is reported.
|
|
assert!(translate_lines(&mut translator, &[allowed]).is_empty());
|
|
assert_eq!(
|
|
translate_lines(&mut translator, &[refused]),
|
|
vec![Event::LimitReached {
|
|
resets_at: Some(1788726600.0)
|
|
}]
|
|
);
|
|
}
|
|
|
|
/// What ends a subagent in the CLI as it actually behaves: its task's
|
|
/// own lifecycle lines. The shapes here are copied from a real 2.1.237
|
|
/// run on 2026-09-06 -- see [`Translator::translate_task`] -- including
|
|
/// the detail that killed the previous rule, that a subagent's own lines
|
|
/// stop at its last `tool_result` and never say `end_turn`.
|
|
#[test]
|
|
fn a_tasks_own_completion_finishes_the_subagent_and_records_its_report() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_task9","name":"Task","input":{"description":"echo something","prompt":"say hello"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"system","subtype":"task_started","task_id":"a7c5","tool_use_id":"toolu_task9","is_backgrounded":false}"#,
|
|
r#"{"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_bash","name":"Bash","input":{"command":"echo hello"}}],"stop_reason":null},"parent_tool_use_id":"toolu_task9"}"#,
|
|
r#"{"type":"system","subtype":"task_progress","task_id":"a7c5","tool_use_id":"toolu_task9","last_tool_name":"Bash"}"#,
|
|
],
|
|
);
|
|
let subagent = subagents.get("toolu_task9").expect("subagent started");
|
|
assert!(subagent.is_open(), "still working");
|
|
|
|
// The completed update carries no tool id and no summary, and is
|
|
// deliberately not the end: the notification behind it is.
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_updated","task_id":"a7c5","patch":{"status":"completed","end_time":1788715207655}}"#,
|
|
],
|
|
);
|
|
assert!(subagent.is_open(), "waiting for the report");
|
|
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_notification","task_id":"a7c5","tool_use_id":"toolu_task9","status":"completed","summary":"it said hello"}"#,
|
|
],
|
|
);
|
|
assert!(!subagent.is_open());
|
|
let lines =
|
|
crate::session::transcript::read_after(&subagent.transcript_path(), 0).expect("read");
|
|
// The report, then the ending, in that order.
|
|
let tail: Vec<&Event> = lines
|
|
.iter()
|
|
.rev()
|
|
.take(2)
|
|
.map(|entry| &entry.event)
|
|
.collect();
|
|
assert!(
|
|
matches!(
|
|
tail[0],
|
|
Event::Status {
|
|
state: SessionStatus::Exited
|
|
}
|
|
),
|
|
"{tail:?}"
|
|
);
|
|
assert!(
|
|
matches!(tail[1], Event::AssistantText { delta } if delta == "it said hello"),
|
|
"{tail:?}"
|
|
);
|
|
}
|
|
|
|
/// A task that stops any other way still ends its subagent, from the one
|
|
/// line that carries it -- the update, which names the task rather than
|
|
/// the tool call, so the mapping from `task_started` is what finds it.
|
|
#[test]
|
|
fn a_task_that_did_not_complete_is_ended_by_its_update() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_task8","name":"Task","input":{"description":"doomed"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"system","subtype":"task_started","task_id":"b1f2","tool_use_id":"toolu_task8","is_backgrounded":true}"#,
|
|
],
|
|
);
|
|
let subagent = subagents.get("toolu_task8").expect("subagent started");
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"task_updated","task_id":"b1f2","patch":{"status":"failed"}}"#,
|
|
],
|
|
);
|
|
assert!(!subagent.is_open());
|
|
}
|
|
|
|
/// What actually ends a subagent: the raw API's own `message_delta`
|
|
/// saying its turn stopped with `end_turn`. Never written into the
|
|
/// subagent's own transcript as `Idle` -- its vocabulary has no such
|
|
/// state.
|
|
#[test]
|
|
fn the_subagents_own_end_turn_finishes_it() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_task3","name":"Task","input":{"description":"helper"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"stream_event","event":{"type":"message_delta","delta":{"stop_reason":"end_turn"}},"parent_tool_use_id":"toolu_task3"}"#,
|
|
],
|
|
);
|
|
let subagent = subagents.get("toolu_task3").expect("subagent started");
|
|
assert!(!subagent.is_open());
|
|
let lines = crate::session::transcript::read_after(&subagent.transcript_path(), 0)
|
|
.expect("read subagent transcript");
|
|
assert!(
|
|
!lines
|
|
.iter()
|
|
.any(|entry| matches!(&entry.event, Event::Status { state } if *state == SessionStatus::Idle)),
|
|
"a subagent's transcript must never carry Idle: {lines:?}"
|
|
);
|
|
assert_eq!(
|
|
lines.last().unwrap().event,
|
|
Event::Status {
|
|
state: SessionStatus::Exited
|
|
}
|
|
);
|
|
}
|
|
|
|
/// `stop_reason: "tool_use"` is the model about to call a tool, with
|
|
/// more of the turn still coming -- not an end.
|
|
#[test]
|
|
fn a_stop_reason_of_tool_use_does_not_finish_the_subagent() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_task4","name":"Task","input":{"description":"helper"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"stream_event","event":{"type":"message_delta","delta":{"stop_reason":"tool_use"}},"parent_tool_use_id":"toolu_task4"}"#,
|
|
],
|
|
);
|
|
assert!(
|
|
subagents
|
|
.get("toolu_task4")
|
|
.expect("subagent started")
|
|
.is_open()
|
|
);
|
|
}
|
|
|
|
/// A background Task can be sent another message long after its first
|
|
/// turn ended -- a further child line for it reopens rather than being
|
|
/// dropped, and the same transcript and child translator carry on.
|
|
#[test]
|
|
fn a_line_after_finish_reopens_the_subagent_rather_than_being_dropped() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_task5","name":"Task","input":{"description":"helper"}}]},"parent_tool_use_id":null}"#,
|
|
r#"{"type":"stream_event","event":{"type":"message_delta","delta":{"stop_reason":"end_turn"}},"parent_tool_use_id":"toolu_task5"}"#,
|
|
],
|
|
);
|
|
let subagent = subagents.get("toolu_task5").expect("subagent started");
|
|
assert!(!subagent.is_open());
|
|
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_more","name":"Bash","input":{}}]},"parent_tool_use_id":"toolu_task5"}"#,
|
|
],
|
|
);
|
|
assert!(subagent.is_open());
|
|
let lines = crate::session::transcript::read_after(&subagent.transcript_path(), 0)
|
|
.expect("read subagent transcript");
|
|
// Running, [prompt], Exited, Running (reopened), then the new line's
|
|
// own ToolStart -- the same transcript throughout, not a new one.
|
|
assert!(
|
|
lines.iter().any(
|
|
|entry| matches!(&entry.event, Event::ToolStart { tool, .. } if tool == "Bash")
|
|
)
|
|
);
|
|
assert_eq!(
|
|
lines
|
|
.iter()
|
|
.filter(|entry| matches!(
|
|
&entry.event,
|
|
Event::Status {
|
|
state: SessionStatus::Running
|
|
}
|
|
))
|
|
.count(),
|
|
2,
|
|
"expected one Running at creation and one at the reopen: {lines:?}"
|
|
);
|
|
}
|
|
|
|
/// Two subagents running at once keep two separate transcripts: tool ids
|
|
/// are unique but a `stream_event`'s content-block index is not, so
|
|
/// sharing translation state between them would cross their streams.
|
|
#[test]
|
|
fn two_parallel_subagents_keep_separate_transcripts() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let subagents = test_subagents(&dir);
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), Arc::clone(&subagents));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_a","name":"Bash","input":{}}]},"parent_tool_use_id":"toolu_task_a"}"#,
|
|
r#"{"type":"assistant","message":{"content":[{"type":"tool_use","id":"toolu_b","name":"Read","input":{}}]},"parent_tool_use_id":"toolu_task_b"}"#,
|
|
],
|
|
);
|
|
let a = subagents.get("toolu_task_a").expect("subagent a");
|
|
let b = subagents.get("toolu_task_b").expect("subagent b");
|
|
let a_events = crate::session::transcript::read_after(&a.transcript_path(), 0)
|
|
.expect("read a's transcript");
|
|
let b_events = crate::session::transcript::read_after(&b.transcript_path(), 0)
|
|
.expect("read b's transcript");
|
|
assert!(
|
|
a_events.iter().any(
|
|
|entry| matches!(&entry.event, Event::ToolStart { tool, .. } if tool == "Bash")
|
|
)
|
|
);
|
|
assert!(
|
|
b_events.iter().any(
|
|
|entry| matches!(&entry.event, Event::ToolStart { tool, .. } if tool == "Read")
|
|
)
|
|
);
|
|
assert!(
|
|
!a_events.iter().any(
|
|
|entry| matches!(&entry.event, Event::ToolStart { tool, .. } if tool == "Read")
|
|
)
|
|
);
|
|
assert!(
|
|
!b_events.iter().any(
|
|
|entry| matches!(&entry.event, Event::ToolStart { tool, .. } if tool == "Bash")
|
|
)
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_permission_request_becomes_an_allow_deny_question() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_request","request_id":"req-1","request":{"subtype":"can_use_tool","tool_name":"Bash","input":{"command":"rm -rf /tmp/x"},"tool_use_id":"toolu_03"}}"#,
|
|
],
|
|
);
|
|
let Event::Question {
|
|
id,
|
|
prompt,
|
|
options,
|
|
about,
|
|
..
|
|
} = &events[0]
|
|
else {
|
|
panic!("expected a question, got {events:?}");
|
|
};
|
|
assert_eq!(id, "req-1");
|
|
// The call being asked about, so the phone draws the ask on that tool's
|
|
// row instead of as a second card repeating its input.
|
|
assert_eq!(about.as_deref(), Some("toolu_03"));
|
|
assert!(prompt.contains("Bash") && prompt.contains("rm -rf /tmp/x"));
|
|
assert_eq!(labels(options), ["Allow", "Deny"]);
|
|
assert_eq!(
|
|
events[1],
|
|
Event::Status {
|
|
state: SessionStatus::AwaitingInput
|
|
}
|
|
);
|
|
|
|
// Allowing echoes the input back; the request is then gone.
|
|
let AnswerOutcome::Respond(response) = translator.answer("req-1", &chose("Allow")) else {
|
|
panic!("expected a control response");
|
|
};
|
|
assert_eq!(response["response"]["request_id"], "req-1");
|
|
assert_eq!(response["response"]["response"]["behavior"], "allow");
|
|
assert_eq!(
|
|
response["response"]["response"]["updatedInput"]["command"],
|
|
"rm -rf /tmp/x"
|
|
);
|
|
assert!(matches!(
|
|
translator.answer("req-1", &chose("Allow")),
|
|
AnswerOutcome::Unknown
|
|
));
|
|
}
|
|
|
|
#[test]
|
|
fn denying_a_permission_sends_deny() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_request","request_id":"req-2","request":{"subtype":"can_use_tool","tool_name":"Write","input":{"file_path":"/etc/passwd"}}}"#,
|
|
],
|
|
);
|
|
let AnswerOutcome::Respond(response) = translator.answer("req-2", &chose("Deny")) else {
|
|
panic!("expected a control response");
|
|
};
|
|
assert_eq!(response["response"]["response"]["behavior"], "deny");
|
|
}
|
|
|
|
#[test]
|
|
fn ask_user_question_rides_the_same_flow_with_answers_keyed_by_question() {
|
|
// The real 2.1.237 shape, verified live: answers go back inside
|
|
// updatedInput, keyed by the question text.
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_request","request_id":"req-3","request":{"subtype":"can_use_tool","tool_name":"AskUserQuestion","input":{"questions":[{"question":"Which color?","header":"Color","options":[{"label":"Red"},{"label":"Blue"}],"multiSelect":false},{"question":"Which size?","header":"Size","options":[{"label":"S"},{"label":"L"}],"multiSelect":false}]},"tool_use_id":"toolu_04","requires_user_interaction":true}}"#,
|
|
],
|
|
);
|
|
let questions: Vec<_> = events
|
|
.iter()
|
|
.filter_map(|event| match event {
|
|
Event::Question {
|
|
id,
|
|
prompt,
|
|
options,
|
|
multi_select,
|
|
..
|
|
} => Some((id.clone(), prompt.clone(), options.clone(), *multi_select)),
|
|
_ => None,
|
|
})
|
|
.collect();
|
|
assert_eq!(questions.len(), 2);
|
|
assert_eq!(questions[0].0, "req-3#0");
|
|
// Both belong to the call that asked, so a phone draws them on it.
|
|
assert!(events.iter().all(|event| match event {
|
|
Event::Question { about, .. } => about.as_deref() == Some("toolu_04"),
|
|
_ => true,
|
|
}));
|
|
assert_eq!(questions[0].1, "Which color?");
|
|
assert_eq!(labels(&questions[0].2), ["Red", "Blue"]);
|
|
|
|
// First answer alone isn't enough; the response goes out when the
|
|
// last sub-question is answered, with all answers aboard.
|
|
assert!(matches!(
|
|
translator.answer("req-3#0", &chose("Blue")),
|
|
AnswerOutcome::Pending
|
|
));
|
|
let AnswerOutcome::Respond(response) = translator.answer("req-3#1", &chose("L")) else {
|
|
panic!("expected a control response");
|
|
};
|
|
let updated = &response["response"]["response"]["updatedInput"];
|
|
assert_eq!(updated["answers"]["Which color?"], "Blue");
|
|
assert_eq!(updated["answers"]["Which size?"], "L");
|
|
assert_eq!(updated["questions"][0]["question"], "Which color?");
|
|
}
|
|
|
|
#[test]
|
|
fn a_question_carries_what_it_takes_to_answer_it() {
|
|
// Descriptions and previews are what the reader decides on, and a
|
|
// multi-select is how many answers the question takes. All of it travels
|
|
// in the event: a phone that had to read this dialect's tool input to
|
|
// find them would be the only place that knew how.
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"control_request","request_id":"req-9","request":{"subtype":"can_use_tool","tool_name":"AskUserQuestion","input":{"questions":[{"question":"Which to collapse?","header":"Collapsed","multiSelect":true,"options":[{"label":"Tool calls","description":"A run becomes one card."},{"label":"Peer messages","description":"From other agents.","preview":"from: dev-updater\\npull before you touch it"}]}]},"tool_use_id":"toolu_09"}}"#,
|
|
],
|
|
);
|
|
let Event::Question {
|
|
header,
|
|
options,
|
|
multi_select,
|
|
..
|
|
} = &events[0]
|
|
else {
|
|
panic!("expected a question, got {events:?}");
|
|
};
|
|
assert_eq!(header.as_deref(), Some("Collapsed"));
|
|
assert!(multi_select);
|
|
assert_eq!(
|
|
options[0].description.as_deref(),
|
|
Some("A run becomes one card.")
|
|
);
|
|
assert!(options[0].preview.is_none());
|
|
assert!(
|
|
options[1]
|
|
.preview
|
|
.as_deref()
|
|
.unwrap()
|
|
.contains("dev-updater")
|
|
);
|
|
|
|
// Two choices, one answer: the joining is this dialect's shape, done
|
|
// where it is spoken. The CLI's answers map holds strings.
|
|
let AnswerOutcome::Respond(response) = translator.answer(
|
|
"req-9#0",
|
|
&["Tool calls".to_string(), "Peer messages".to_string()],
|
|
) else {
|
|
panic!("expected a control response");
|
|
};
|
|
assert_eq!(
|
|
response["response"]["response"]["updatedInput"]["answers"]["Which to collapse?"],
|
|
"Tool calls, Peer messages"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn images_in_tool_results_are_saved_and_referenced() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
// A 1x1 PNG, the smallest real payload worth round-tripping.
|
|
let png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
|
|
let line = format!(
|
|
r#"{{"type":"user","message":{{"role":"user","content":[{{"type":"tool_result","tool_use_id":"toolu_05","content":[{{"type":"text","text":"took a screenshot"}},{{"type":"image","source":{{"type":"base64","media_type":"image/png","data":"{png}"}}}}]}}]}},"parent_tool_use_id":null}}"#
|
|
);
|
|
let events = translator.translate(&serde_json::from_str(&line).expect("json"));
|
|
|
|
let Event::Image { image, about } = &events[0] else {
|
|
panic!("expected an image event, got {events:?}");
|
|
};
|
|
assert!(image.ends_with(".png"));
|
|
// Named as belonging to the call that produced it, so a phone draws it
|
|
// under that row rather than beside it.
|
|
assert_eq!(about.as_deref(), Some("toolu_05"));
|
|
let saved = dir.path().join("files").join(image);
|
|
assert!(saved.is_file(), "image not saved at {}", saved.display());
|
|
assert_eq!(
|
|
events[1],
|
|
Event::ToolEnd {
|
|
id: "toolu_05".to_string(),
|
|
output: "took a screenshot".to_string(),
|
|
}
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_turn_result_reports_usage_and_returns_to_idle() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"success","is_error":false,"num_turns":2,"stop_reason":"end_turn","session_id":"s","total_cost_usd":0.0149,"usage":{"input_tokens":18,"output_tokens":164}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![
|
|
Event::UsageDelta {
|
|
tokens: 182,
|
|
context: None
|
|
},
|
|
Event::Status {
|
|
state: SessionStatus::Idle
|
|
},
|
|
]
|
|
);
|
|
}
|
|
|
|
/// A turn another agent started says so, on the record that carries it.
|
|
///
|
|
/// The line is the real shape, taken from a real cross-session message sent
|
|
/// to a real stream-json session on 2.1.237 (2026-08-31) -- including the
|
|
/// `from` socket path, which is deliberately *not* what a reader is shown:
|
|
/// the sending session's `name` is what they recognise it by. The `body` is
|
|
/// the message as written; the content the model is given wraps the same
|
|
/// text in a preamble written for the model rather than for a person.
|
|
///
|
|
/// The note comes before the usage and the idle, so it sits as close to the
|
|
/// turn it explains as the wire allows.
|
|
#[test]
|
|
fn a_turn_started_by_another_agent_records_who_and_what() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"success","is_error":false,"session_id":"s","usage":{"input_tokens":2,"output_tokens":5},"origin":{"kind":"peer","from":"uds:/run/user/1000/cc-socks/137108.sock","verifiedPeerPid":137108,"msg_id":"1e729740","name":"ai-app-2-fb","fromMode":"prompting","body":"Reply with just the word ACK."}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![
|
|
Event::PeerMessage {
|
|
from: "ai-app-2-fb".to_string(),
|
|
text: "Reply with just the word ACK.".to_string(),
|
|
// Stamped by the pump, which is the only place that knows
|
|
// what seq the turn started at.
|
|
turn_start: None,
|
|
},
|
|
Event::UsageDelta {
|
|
tokens: 7,
|
|
context: None
|
|
},
|
|
Event::Status {
|
|
state: SessionStatus::Idle
|
|
},
|
|
]
|
|
);
|
|
}
|
|
|
|
/// And an ordinary turn does not, which is the half that decides whether
|
|
/// the check above is a check or a rubber stamp. Measured over a real
|
|
/// session's stdout: four results, no `origin` between them.
|
|
#[test]
|
|
fn an_ordinary_turn_carries_no_peer_note() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"success","is_error":false,"session_id":"s","usage":{"input_tokens":2,"output_tokens":5}}"#,
|
|
],
|
|
);
|
|
assert!(
|
|
!events
|
|
.iter()
|
|
.any(|event| matches!(event, Event::PeerMessage { .. })),
|
|
"a turn nobody else started must not be attributed to anyone: {events:?}"
|
|
);
|
|
}
|
|
|
|
/// The context is the last assistant message's, not the result's.
|
|
///
|
|
/// Real figures from a two-message haiku turn on 2.1.237, captured
|
|
/// 2026-08-30. The result adds the turn up -- its `cache_read_input_tokens`
|
|
/// of 40,211 is 14,259 and 25,952, the same conversation counted twice -- so
|
|
/// reading the context off it would report a size the model never held, by
|
|
/// more the more tool calls a turn makes.
|
|
#[test]
|
|
fn the_context_is_what_the_last_message_held_not_the_turn_added_up() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"assistant","message":{"content":[],"usage":{"input_tokens":9,"cache_creation_input_tokens":11693,"cache_read_input_tokens":14259,"output_tokens":3}}}"#,
|
|
r#"{"type":"assistant","message":{"content":[],"usage":{"input_tokens":8,"cache_creation_input_tokens":171,"cache_read_input_tokens":25952,"output_tokens":2}}}"#,
|
|
r#"{"type":"result","subtype":"success","is_error":false,"session_id":"s","usage":{"input_tokens":17,"cache_creation_input_tokens":11864,"cache_read_input_tokens":40211,"output_tokens":156}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events.first(),
|
|
Some(&Event::UsageDelta {
|
|
tokens: 173,
|
|
context: Some(26_131),
|
|
})
|
|
);
|
|
|
|
// Taken by that result, so a following turn whose messages carry no
|
|
// usage reports none rather than repeating this one's.
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"success","is_error":false,"session_id":"s","usage":{"input_tokens":4,"output_tokens":9}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events.first(),
|
|
Some(&Event::UsageDelta {
|
|
tokens: 13,
|
|
context: None,
|
|
})
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_compaction_reports_its_start_and_what_it_recovered() {
|
|
// Real lines (trimmed) from a 2.1.237 session driven through `/compact`.
|
|
// Note the snake_case keys -- the CLI's transcript file writes the same
|
|
// records in camelCase.
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"status","status":"compacting","session_id":"s","uuid":"u1"}"#,
|
|
r#"{"type":"system","subtype":"status","status":null,"compact_result":"success","session_id":"s","uuid":"u2"}"#,
|
|
r#"{"type":"system","subtype":"compact_boundary","session_id":"s","uuid":"u3","compact_metadata":{"trigger":"manual","pre_tokens":28719,"post_tokens":1125,"duration_ms":17130}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![
|
|
Event::Status {
|
|
state: SessionStatus::Compacting
|
|
},
|
|
Event::Status {
|
|
state: SessionStatus::Running
|
|
},
|
|
Event::Compacted {
|
|
pre_tokens: Some(28719),
|
|
post_tokens: Some(1125),
|
|
trigger: Some("manual".to_string()),
|
|
},
|
|
]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_failed_compaction_says_why_and_leaves_the_turn_running() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"status","status":"compacting","session_id":"s","uuid":"u1"}"#,
|
|
r#"{"type":"system","subtype":"status","status":null,"compact_result":"failed","compact_error":"Not enough messages to compact.","session_id":"s","uuid":"u2"}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![
|
|
Event::Status {
|
|
state: SessionStatus::Compacting
|
|
},
|
|
Event::Error {
|
|
message: "compaction failed: Not enough messages to compact.".to_string()
|
|
},
|
|
Event::Status {
|
|
state: SessionStatus::Running
|
|
},
|
|
]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_boundary_without_counts_says_so_rather_than_inventing_them() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"system","subtype":"compact_boundary","session_id":"s","compact_metadata":{"trigger":"auto"}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events,
|
|
vec![Event::Compacted {
|
|
pre_tokens: None,
|
|
post_tokens: None,
|
|
trigger: Some("auto".to_string()),
|
|
}]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn an_error_result_surfaces_the_message() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"error_during_execution","is_error":true,"result":"something broke","usage":{}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events[0],
|
|
Event::Error {
|
|
message: "something broke".to_string()
|
|
}
|
|
);
|
|
assert_eq!(
|
|
*events.last().unwrap(),
|
|
Event::Status {
|
|
state: SessionStatus::Idle
|
|
}
|
|
);
|
|
}
|
|
|
|
/// Running out of quota is a state, not a failure of the work.
|
|
///
|
|
/// The naive reading -- an error result like any other -- is what shipped
|
|
/// before this: the transcript said "Claude AI usage limit reached|…" in
|
|
/// red, which is neither readable nor actionable, and nothing above the
|
|
/// driver could tell it apart from a broken tool call.
|
|
#[test]
|
|
fn a_turn_stopped_by_the_usage_limit_says_so_and_carries_the_reset() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"error_during_execution","is_error":true,"result":"Claude AI usage limit reached|1788546972","usage":{}}"#,
|
|
],
|
|
);
|
|
assert_eq!(
|
|
events[0],
|
|
Event::LimitReached {
|
|
resets_at: Some(1_788_546_972.0)
|
|
}
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_limit_the_cli_gave_no_reset_for_is_reported_without_one() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"result","subtype":"error_during_execution","is_error":true,"result":"Claude AI usage limit reached","usage":{}}"#,
|
|
],
|
|
);
|
|
// Not a time this side invented: the meter is asked before anything is
|
|
// sent, and a made-up reset would only decide when to ask.
|
|
assert_eq!(events[0], Event::LimitReached { resets_at: None });
|
|
}
|
|
|
|
#[test]
|
|
fn a_reset_in_milliseconds_is_not_read_as_the_year_58000() {
|
|
assert_eq!(
|
|
usage_limit("Claude AI usage limit reached|1788546972000"),
|
|
Some(Some(1_788_546_972.0))
|
|
);
|
|
// And anything that is not the limit stays an ordinary failure.
|
|
assert_eq!(usage_limit("something broke"), None);
|
|
}
|
|
|
|
/// Pressing Stop is not a failure, and the CLI cannot tell you which it was.
|
|
///
|
|
/// An interrupted turn arrives as exactly the same shape a broken one does,
|
|
/// so somebody who pressed the button was shown "the turn ended with an
|
|
/// error". What separates the two is that this side asked. The second half
|
|
/// of this test is the one that matters, because the naive fix -- never
|
|
/// reporting an error result -- passes the first half and silences every
|
|
/// genuine failure afterwards.
|
|
#[test]
|
|
fn a_turn_stopped_on_purpose_is_not_an_error() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let stopped_result = r#"{"type":"result","subtype":"error_during_execution","is_error":true,"result":"Interrupted by user","usage":{}}"#;
|
|
|
|
translator.expect_interrupt();
|
|
let events = translate_lines(&mut translator, &[stopped_result]);
|
|
assert!(
|
|
!events
|
|
.iter()
|
|
.any(|event| matches!(event, Event::Error { .. })),
|
|
"a stop the driver asked for was reported as a failure: {events:?}"
|
|
);
|
|
assert_eq!(
|
|
*events.last().unwrap(),
|
|
Event::Status {
|
|
state: SessionStatus::Idle
|
|
},
|
|
"an interrupted turn still has to end the turn"
|
|
);
|
|
|
|
// The interrupt is spent, so the next failure is a failure again.
|
|
let later = translate_lines(&mut translator, &[stopped_result]);
|
|
assert!(
|
|
later
|
|
.iter()
|
|
.any(|event| matches!(event, Event::Error { .. })),
|
|
"a later failure was swallowed by an interrupt that had already been answered"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn replayed_and_synthetic_user_text_is_skipped() {
|
|
let dir = tempfile::tempdir().expect("tempdir");
|
|
let mut translator = Translator::new(dir.path().to_path_buf(), test_subagents(&dir));
|
|
let events = translate_lines(
|
|
&mut translator,
|
|
&[
|
|
r#"{"type":"user","message":{"role":"user","content":[{"type":"text","text":"hi"}]},"isReplay":true,"parent_tool_use_id":null}"#,
|
|
r#"{"type":"user","message":{"role":"user","content":[{"type":"text","text":"[continue]"}]},"isSynthetic":true,"parent_tool_use_id":null}"#,
|
|
],
|
|
);
|
|
assert!(events.is_empty());
|
|
}
|
|
}
|