//! The provider-independent agent loop (`SMH-SPEC-SPEC0001`, Tools and //! Compaction cost and secrets). //! //! One runtime drives every interface mode: it sends provider-neutral //! requests, streams normalized events, executes tool calls through the //! recorded [`ToolSession`] boundary, and settles //! turns with ordered, paired durable events. Vendor details stop at the //! [`StreamFn`](smith::provider::StreamFn) it consumes. use crate::metadata::{ CompactionMetadata, ProviderToolCallIdentityMetadata, encode as encode_metadata, }; use crate::session::{ COMPACTION_KIND, EntryContent, EntryContentRef, PROVIDER_DISPATCH_PROVENANCE_KIND, PROVIDER_HTTP_KIND, PROVIDER_TOOL_CALL_IDENTITIES_KIND, }; use crate::tools::ToolSession; use smith::error::{Result, SmithError}; use smith::id::ToolCallId; use smith::message::{ContentBlock, Message, Role}; use smith::provider::{ProviderRequest, StreamFn}; use smith::stream::{StopReason, StreamEvent, Usage}; use smith::structured::{AccessError, ToolArguments}; use smith::tool::CancelHandle; use std::collections::VecDeque; /// Observable agent lifecycle event, in emission order. #[derive(Clone, Debug, PartialEq, Eq)] pub enum AgentEvent { /// A turn started for this input. TurnStarted { /// The user input that began the turn. input: String, }, /// A normalized provider event surfaced during the turn. Streamed { /// The provider event after secret redaction. event: StreamEvent, }, /// A tool call began executing. ToolStarted { /// Tool name. name: String, /// Paired call identifier. call_id: ToolCallId, }, /// A tool call finished. ToolFinished { /// Tool name. name: String, /// Paired call identifier. call_id: ToolCallId, /// Whether the recorded effect succeeded. ok: bool, /// Durable best-known host mutation outcome. mutation_state: smith::error::MutationState, }, /// The turn settled; no further events follow for it. TurnSettled { /// Why the turn ended. reason: StopReason, /// Accumulated usage across the turn's provider requests. cost: Option, }, } /// How queued input resumes: immediately between provider requests, or once /// the current turn settles. #[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)] pub enum Delivery { /// Delivered before the next provider request. BetweenRequests, /// Delivered after the current turn settles. AfterTurn, } /// Queued steering or follow-up input. #[derive(Clone, Debug, PartialEq, Eq)] pub struct QueuedInput { /// Text to deliver as a user message. pub text: String, /// When the input may be delivered. pub delivery: Delivery, } /// The agent runtime. pub struct Agent { stream: StreamFn, tools: ToolSession, model: String, prompt: Option, continuation_round_limit: u32, cancel: CancelHandle, queue: VecDeque, /// Secret placeholder prefix used by [`SecretProxy`]-masked content. secrets: SecretProxy, /// Redacted provider effect records spooled by the transport. provider_records: Option, } /// Replacement and masking of registered secrets. /// /// Context and provider requests keep `{{secret:name}}` placeholders. /// Placeholders are restored only for authorized local effects; their inputs, /// outputs, events, and errors are masked before recording or exposure. #[derive(Clone, Default)] pub struct SecretProxy { registered: Vec<(String, String)>, } impl SecretProxy { /// An empty proxy. #[must_use] pub fn new() -> Self { Self::default() } /// Register or replace a secret under a name. pub fn register(&mut self, name: impl Into, value: impl Into) { let name = name.into(); let value = value.into(); if let Some((_, registered)) = self .registered .iter_mut() .find(|(registered, _)| registered == &name) { *registered = value; } else { self.registered.push((name, value)); } // At each position the longest matching value wins, including when // a shorter complete value is also a prefix of a longer registration. self.registered .sort_by_key(|entry| std::cmp::Reverse(entry.1.len())); } fn placeholder(name: &str) -> String { format!("{{{{secret:{name}}}}}") } /// Restore placeholders immediately before an authorized local effect. #[must_use] pub fn unmask(&self, text: &str) -> String { let mut out = text.to_string(); for (name, value) in &self.registered { let placeholder = Self::placeholder(name); if out.contains(&placeholder) { out = out.replace(&placeholder, value); } } out } /// Replace registered values with placeholders before content crosses a /// persistence, provider, event, or diagnostic boundary. #[must_use] pub fn mask(&self, text: &str) -> String { let mut out = text.to_string(); self.mask_in_place(&mut out); out } /// [`SecretProxy::mask`] without a copy when `text` holds no secret. fn mask_in_place(&self, text: &mut String) { if !self .registered .iter() .any(|(_, value)| !value.is_empty() && text.contains(value)) { return; } let mut masked = String::new(); let mut rest = text.as_str(); while !rest.is_empty() { if let Some((name, value)) = self .registered .iter() .find(|(_, value)| !value.is_empty() && rest.starts_with(value)) { masked.push_str(&Self::placeholder(name)); rest = &rest[value.len()..]; } else if let Some(character) = rest.chars().next() { masked.push(character); rest = &rest[character.len_utf8()..]; } } *text = masked; } /// Mask a decoded `message` in place; texts without a secret are not /// copied. fn mask_message(&self, message: &mut Message) -> Result<()> { if self.registered.is_empty() { return Ok(()); } for block in &mut message.blocks { match block { ContentBlock::Text(text) | ContentBlock::Thinking(text) => self.mask_in_place(text), ContentBlock::ToolUse { name, input, .. } => { self.mask_in_place(name); *input = self.mask_arguments(input)?; } ContentBlock::ToolResult { output, .. } => self.mask_in_place(output), } } Ok(()) } fn mask_arguments(&self, value: &ToolArguments) -> Result { value .transform_strings(&|text| self.mask(text), 64) .map_err(structured_error) } fn unmask_arguments(&self, value: &ToolArguments) -> Result { value .transform_strings(&|text| self.unmask(text), 64) .map_err(structured_error) } fn mask_event(&self, event: &mut StreamEvent) -> Result<()> { match event { StreamEvent::ToolUse { name, input, .. } => { self.mask_in_place(name); *input = self.mask_arguments(input)?; } StreamEvent::ToolResult { output, .. } => self.mask_in_place(output), StreamEvent::Error { error } => self.mask_in_place(error), _ => {} } Ok(()) } /// Mask registered values while retaining the original error classification. #[must_use] pub fn mask_error(&self, error: SmithError) -> SmithError { match error { SmithError::Session { code, message } => SmithError::Session { code, message: self.mask(&message), }, SmithError::Storage { code, operation, path, message, publication, } => SmithError::Storage { code, operation, path, message: self.mask(&message), publication, }, SmithError::Provider { fault } => SmithError::Provider { fault: match fault { smith::error::ProviderFault::Transient { message } => { smith::error::ProviderFault::Transient { message: self.mask(&message), } } smith::error::ProviderFault::Invalid { field, message } => { smith::error::ProviderFault::Invalid { field, message: self.mask(&message), } } smith::error::ProviderFault::Authentication { message } => { smith::error::ProviderFault::Authentication { message: self.mask(&message), } } smith::error::ProviderFault::Overloaded { message } => { smith::error::ProviderFault::Overloaded { message: self.mask(&message), } } smith::error::ProviderFault::Protocol { message } => { smith::error::ProviderFault::Protocol { message: self.mask(&message), } } smith::error::ProviderFault::Plugin { message } => { smith::error::ProviderFault::Plugin { message: self.mask(&message), } } other => other, }, }, SmithError::Tool { code, message } => SmithError::Tool { code, message: self.mask(&message), }, SmithError::RecordFailed { tool, mutation_state, message, } => SmithError::RecordFailed { tool, mutation_state, message: self.mask(&message), }, SmithError::Config { field, message } => SmithError::Config { field, message: self.mask(&message), }, other => other, } } } fn structured_error(error: AccessError) -> SmithError { SmithError::Session { code: smith::error::SessionCode::EntryDecode, message: error.to_string(), } } /// Result of one settled turn. #[derive(Clone, Debug, PartialEq, Eq)] pub struct TurnOutcome { /// Final assistant text, or the observed text prefix after an abort. pub text: String, /// Why the turn ended. pub reason: StopReason, /// Sum of known usage observations; `None` means none were available. /// Partial totals remain useful when `cost_complete` is false. pub cost: Option, /// Whether every dispatched provider round supplied usage. pub cost_complete: bool, /// Events emitted during the turn. pub events: Vec, } fn aborted_outcome( mut events: Vec, cost: Option<&Usage>, cost_complete: bool, ) -> TurnOutcome { events.retain(|event| !matches!(event, AgentEvent::TurnSettled { .. })); let text = events .iter() .filter_map(|event| match event { AgentEvent::Streamed { event: StreamEvent::TextDelta { delta, .. }, } => Some(delta.as_str()), _ => None, }) .collect(); events.push(AgentEvent::TurnSettled { reason: StopReason::Abort, cost: cost.copied(), }); TurnOutcome { text, reason: StopReason::Abort, cost: cost.copied(), cost_complete: cost_complete && cost.is_some(), events, } } /// One unresolved suffix. Arrival order fixes deterministic global flushing. struct PendingDelta { message_id: smith::id::MessageId, thinking: bool, suffix: String, } /// Pending lookahead belongs to one provider call, not session history. /// Only the unresolved suffix of its own message field delays a delta. #[derive(Default)] pub struct StreamRedactor { pending: Vec, } impl StreamRedactor { /// Bound independently ambiguous message fields and all retained suffix bytes. const PENDING_LANES_LIMIT: usize = 4096; const PENDING_BYTES_LIMIT: usize = 1024 * 1024; /// Redact one event, retaining only its own unresolved secret prefix. /// /// # Errors /// Returns a protocol fault when retained lookahead exceeds its bound. pub fn push( &mut self, mut event: StreamEvent, secrets: &SecretProxy, ) -> Result> { let Some((message_id, thinking, delta)) = (match &event { StreamEvent::TextDelta { message_id, delta } => Some((*message_id, false, delta)), StreamEvent::ThinkingDelta { message_id, delta } => Some((*message_id, true, delta)), StreamEvent::ToolUse { message_id, .. } | StreamEvent::ToolResult { message_id, .. } => { let mut output = self.flush_message(*message_id, secrets)?; secrets.mask_event(&mut event)?; output.push(event); return Ok(output); } StreamEvent::Stop { .. } | StreamEvent::Error { .. } => { let mut output = self.drain(secrets, true)?; secrets.mask_event(&mut event)?; output.push(event); return Ok(output); } }) else { unreachable!("every stream event variant is handled") }; let lane = self .pending .iter() .position(|lane| lane.message_id == message_id && lane.thinking == thinking); let lane = if let Some(index) = lane { &mut self.pending[index] } else { if self.pending.len() == Self::PENDING_LANES_LIMIT { return Err(lookahead_limit_error()); } self.pending.push(PendingDelta { message_id, thinking, suffix: String::new(), }); let last = self.pending.len() - 1; &mut self.pending[last] }; lane.suffix.push_str(delta); self.redact_lane(message_id, thinking, secrets, false) } fn redact_lane( &mut self, message_id: smith::id::MessageId, thinking: bool, secrets: &SecretProxy, finished: bool, ) -> Result> { let index = self .pending .iter() .position(|lane| lane.message_id == message_id && lane.thinking == thinking); let Some(index) = index else { return Ok(Vec::new()); }; let mut output = String::new(); let empty = { let lane = &mut self.pending[index]; while !lane.suffix.is_empty() { let ambiguous = !finished && secrets.registered.iter().any(|(_, value)| { !value.is_empty() && value.len() > lane.suffix.len() && value.starts_with(&lane.suffix) }); if ambiguous { break; } if let Some((name, value)) = secrets .registered .iter() .find(|(_, value)| !value.is_empty() && lane.suffix.starts_with(value)) { output.push_str(&SecretProxy::placeholder(name)); lane.suffix.drain(..value.len()); } else if let Some(character) = lane.suffix.chars().next() { output.push(character); lane.suffix.drain(..character.len_utf8()); } } lane.suffix.is_empty() }; if self .pending .iter() .map(|lane| lane.suffix.len()) .sum::() > Self::PENDING_BYTES_LIMIT { return Err(lookahead_limit_error()); } if empty { self.pending.remove(index); } let event = if thinking { StreamEvent::thinking_delta(message_id, output) } else { StreamEvent::text_delta(message_id, output) }; Ok((!matches!(&event, StreamEvent::TextDelta { delta, .. } | StreamEvent::ThinkingDelta { delta, .. } if delta.is_empty())) .then_some(event) .into_iter() .collect()) } fn flush_message( &mut self, message_id: smith::id::MessageId, secrets: &SecretProxy, ) -> Result> { let fields: Vec<_> = self .pending .iter() .filter(|lane| lane.message_id == message_id) .map(|lane| (lane.message_id, lane.thinking)) .collect(); let mut output = Vec::new(); for (message_id, thinking) in fields { output.extend(self.redact_lane(message_id, thinking, secrets, true)?); } Ok(output) } /// Flush pending fields in arrival order at a message or stream boundary. /// /// # Errors /// Returns a protocol fault when retained lookahead exceeds its bound. pub fn drain(&mut self, secrets: &SecretProxy, finished: bool) -> Result> { let fields: Vec<_> = self .pending .iter() .map(|lane| (lane.message_id, lane.thinking)) .collect(); let mut output = Vec::new(); for (message_id, thinking) in fields { output.extend(self.redact_lane(message_id, thinking, secrets, finished)?); } Ok(output) } } fn lookahead_limit_error() -> SmithError { SmithError::Provider { fault: smith::error::ProviderFault::Protocol { message: "secret redaction lookahead limit exceeded".into(), }, } } /// A compaction summary; incomplete summaries are never persisted. #[derive(Clone, Debug, PartialEq, Eq)] pub struct CompactionSummary { /// Summary text. pub text: String, /// Whether the summarizer considers the summary complete. pub complete: bool, } /// One consumed provider round. struct Round { /// Accumulated assistant text. text: String, /// Complete tool uses, in emission order. tools: Vec<(ToolCallId, String, ToolArguments, String)>, /// Terminal stop with usage, when the round ended cleanly. terminal: Option<(StopReason, Option)>, } impl Agent { /// An agent over a stream function and a recorded tool session. #[must_use] pub fn new(stream: StreamFn, tools: ToolSession, model: impl Into) -> Self { Self::with_provider_records(stream, tools, model, None) } /// An agent whose provider rounds drain redacted effect records into /// the session after each round. #[must_use] pub fn with_provider_records( stream: StreamFn, tools: ToolSession, model: impl Into, records: Option, ) -> Self { let cancel = tools.cancel_handle(); Self { stream, tools, model: model.into(), prompt: None, continuation_round_limit: 64, cancel, queue: VecDeque::new(), secrets: SecretProxy::new(), provider_records: records, } } /// A handle that aborts the running turn. #[must_use] pub fn cancel_handle(&self) -> CancelHandle { self.cancel.clone() } /// Replace a settled turn's cancellation handle. /// /// Call only between turns. The returned handle controls the next turn's /// provider requests and local tool effects. pub fn renew_cancel_handle(&mut self) -> CancelHandle { let cancel = CancelHandle::new(); self.cancel = cancel.clone(); self.tools.set_cancel_handle(cancel.clone()); cancel } /// Mutable access to the secret proxy before turns run. pub const fn secrets_mut(&mut self) -> &mut SecretProxy { &mut self.secrets } /// The live session, for inspection and persistence by the caller. #[must_use] pub const fn session(&self) -> &crate::session::Session { &self.tools.session } /// Queue steering or follow-up input. /// /// Queued input is delivered only between provider requests, never /// mid-request, so an injected message can never split a tool call from /// its result. pub fn queue(&mut self, input: QueuedInput) { self.queue.push_back(input); } /// Persist a compaction boundary and reject incomplete summaries. /// /// # Errors /// /// Returns a [`SmithError::Session`] fault when `summary` is incomplete; /// nothing is persisted in that case. pub fn compact(&mut self, summary: &CompactionSummary) -> Result { if !summary.complete { return Err(SmithError::Session { code: smith::error::SessionCode::CompactionIncomplete, message: "refusing to persist a summary known to be incomplete".to_string(), }); } let detail = encode_metadata(&CompactionMetadata { summary: self.secrets.mask(&summary.text), complete: Some(true), })?; let entry = self.tools.record(&EntryContent::Meta { kind: COMPACTION_KIND.to_string(), detail, })?; Ok(entry.id) } /// Run one user turn to settlement. /// /// # Errors /// /// Returns [`SmithError::Cancelled`] when aborted, or the first /// provider, tool, or recording failure; durable state stays consistent /// with what was recorded before the failure. pub fn run_turn(&mut self, input: impl Into) -> Result { let input = input.into(); let masked_input = self.secrets.mask(&input); let mut events = vec![AgentEvent::TurnStarted { input: masked_input.clone(), }]; let root_entry_id = self.record_user_message(&masked_input)?; let mut outcome = self.drive_settled( root_entry_id, &mut events, false, &mut None, &mut true, &mut |_| {}, &mut |_| Ok(()), )?; outcome.events.push(AgentEvent::TurnSettled { reason: outcome.reason, cost: outcome.cost, }); Ok(outcome) } /// Consume queued after-turn input as follow-up turns. /// /// # Errors /// /// Same as [`Agent::run_turn`]. pub fn run_queued(&mut self) -> Result> { let mut outcomes = Vec::new(); while let Some(input) = self.queue.pop_front() { outcomes.push(self.run_turn(input.text)?); } Ok(outcomes) } /// Execute already recorded root input through the shared agent loop. /// Tool capability requires the session worker's atomic completion boundary. /// The caller must durably claim before calling; terminal output crosses /// the supplied persistence boundary once, as one settlement command. /// /// # Errors /// Provider failures settle explicitly if persistence remains certain. /// Recording failures leave claimed work blocked for recovery. pub fn run_admitted( &mut self, submission_id: smith::id::EntryId, mut persist: impl FnMut(crate::frame::Frame) -> Result<()>, ) -> Result { self.run_admitted_controlled( submission_id, |command| persist(command).map(|()| crate::control::SettlementDisposition::Committed), &mut |_| {}, ) } /// Execute admitted input with typed cancellation-versus-settlement serialization. /// A pre-commit rejection never adopts the rejected assistant message. /// Masked progress is observed live, without acknowledging settlement. /// /// # Errors /// Returns an abort outcome only after durable acknowledgement; faults remain errors. pub fn run_admitted_controlled( &mut self, submission_id: smith::id::EntryId, persist: impl FnMut(crate::frame::Frame) -> Result, observe: &mut dyn FnMut(&StreamEvent), ) -> Result { self.run_admitted_phased(submission_id, persist, observe, &mut |_| Ok(())) } /// Execute admitted input with acknowledged executor phase transitions. /// The notification transition precedes every terminal guest and effect. /// /// # Errors /// Same durable failure contract as [`Self::run_admitted_controlled`]. pub fn run_admitted_phased( &mut self, submission_id: smith::id::EntryId, mut persist: impl FnMut(crate::frame::Frame) -> Result, observe: &mut dyn FnMut(&StreamEvent), phase: &mut dyn FnMut(crate::control::ExecutionPhase) -> Result<()>, ) -> Result { use crate::control::SettlementDisposition; let input = self.admitted_input()?; let mut events = vec![AgentEvent::TurnStarted { input }]; let mut cost = None; let mut cost_complete = true; match self.drive_settled( submission_id, &mut events, true, &mut cost, &mut cost_complete, observe, phase, ) { Ok(mut outcome) => { let message = Message::with_text(Role::Assistant, &outcome.text); let mut cancelled_before_commit = false; let committed = self .tools .session .append_with(EntryContentRef::Message(&message), |entry, bytes| { let disposition = persist(crate::frame::Frame::Settlement { submission_id, reason: Some(outcome.reason), output: Some(crate::session::EntryFrame { id: entry.id, parent: entry.parent, timestamp_ms: entry.timestamp_ms, kind: entry.kind, content: bytes.to_vec(), }), })?; if disposition == SettlementDisposition::CancelBeforeCommit { cancelled_before_commit = true; return Err(SmithError::Cancelled); } Ok(()) }) .map(|_| ()); if cancelled_before_commit { let result = persist(crate::frame::Frame::Settlement { submission_id, reason: Some(StopReason::Abort), output: None, }); self.require_settlement(result)?; return Ok(aborted_outcome( outcome.events, cost.as_ref(), cost_complete, )); } committed.inspect_err(|_| self.tools.poison_recording())?; outcome.events.push(AgentEvent::TurnSettled { reason: outcome.reason, cost: outcome.cost, }); Ok(outcome) } Err(error) => { if !self.tools.recording_failed() { let reason = matches!(error, SmithError::Cancelled).then_some(StopReason::Abort); let mut committed = persist(crate::frame::Frame::Settlement { submission_id, reason, output: None, }); if matches!(committed, Ok(SettlementDisposition::CancelBeforeCommit)) { committed = persist(crate::frame::Frame::Settlement { submission_id, reason: Some(StopReason::Abort), output: None, }); } self.require_settlement(committed)?; } if matches!(error, SmithError::Cancelled) && !self.tools.recording_failed() { Ok(aborted_outcome(events, cost.as_ref(), cost_complete)) } else { Err(error) } } } } fn admitted_input(&self) -> Result { { let session = &self.tools.session; let mut input = None; for entry in session.active_branch().entries().iter().rev() { match session.content(entry)? { EntryContent::Message(message) if message.role == Role::User => { input = Some( message .blocks .iter() .filter_map(|block| match block { ContentBlock::Text(text) => Some(text.as_str()), _ => None, }) .collect::(), ); break; } _ => {} } } input } .ok_or_else(|| SmithError::Session { code: smith::error::SessionCode::EntryNotFound, message: "admitted execution has no recorded user input".into(), }) } fn require_settlement( &mut self, result: Result, ) -> Result<()> { if matches!(result, Ok(crate::control::SettlementDisposition::Committed)) { return Ok(()); } self.tools.poison_recording(); result?; Err(SmithError::Session { code: smith::error::SessionCode::SessionIncompleteContext, message: "abort settlement was not durably committed".into(), }) } #[expect( clippy::too_many_arguments, reason = "one joined execution shares progress, phase, usage and event sinks without heap ownership" )] fn drive_settled( &mut self, root_entry_id: smith::id::EntryId, events: &mut Vec, admitted: bool, cost: &mut Option, cost_complete: &mut bool, observe: &mut dyn FnMut(&StreamEvent), phase: &mut dyn FnMut(crate::control::ExecutionPhase) -> Result<()>, ) -> Result { let mut terminal = smith::lifecycle::LifecycleEvent { root_entry_id, boundary: smith::lifecycle::Boundary::Settled, round_index: 0, last_stop: StopReason::Abort, continuation_eligible: false, }; let outcome = self.drive( &mut terminal, events, admitted, cost, cost_complete, observe, ); // Uncertain recording cannot authorize another guest or effect; retain // the original failure and its already-applied mutation evidence. if let Err(error) = self.tools.ensure_recording() { return outcome.and(Err(error)); } terminal.boundary = smith::lifecycle::Boundary::Settled; terminal.continuation_eligible = false; if matches!(outcome, Err(SmithError::Cancelled)) { terminal.last_stop = StopReason::Abort; } phase(crate::control::ExecutionPhase::Notifying)?; self.lifecycle_boundary(&terminal)?; outcome } #[expect( clippy::too_many_lines, reason = "provider stream, durable tool pairing, and settlement form one ordered state machine" )] fn drive( &mut self, terminal_event: &mut smith::lifecycle::LifecycleEvent, events: &mut Vec, admitted: bool, cost: &mut Option, cost_complete: &mut bool, observe: &mut dyn FnMut(&StreamEvent), ) -> Result { let mut round_index = 0u32; loop { self.tools.ensure_recording()?; self.check_cancelled()?; self.deliver_between_request_queue()?; self.tools.begin_provider_round()?; let atomic_tools = self.tools.has_completion_boundary(); if admitted && atomic_tools { self.tools.record_admitted_loadout_provenance()?; } let mut request = self.build_request()?; if admitted && !atomic_tools { request.tools = std::sync::Arc::from([]); } let stream = (self.stream)(request, self.cancel.clone()); self.drain_provider_records()?; let previously_complete = *cost_complete; *cost_complete = false; let round = self.consume(stream, events, observe); let records = self.drain_provider_records(); // Drain first, then preserve the stream's fault as the // user-visible cause when both boundaries failed. let round = round?; records?; let Round { text, tools: pending_tools, terminal, } = round; let Some((reason, usage)) = terminal else { return Err(SmithError::Provider { fault: smith::error::ProviderFault::Incomplete, }); }; *cost_complete = previously_complete && usage.is_some(); if let Some(usage) = usage { let total = cost.get_or_insert_with(Usage::new); total.input_tokens += usage.input_tokens; total.output_tokens += usage.output_tokens; total.input_cache_hit_tokens += usage.input_cache_hit_tokens; total.input_cache_write_tokens += usage.input_cache_write_tokens; } // The assistant message carries its text and every tool use it // issued, so the provider sees the same pairing the session // recorded. let masked_text = self.secrets.mask(&text); if admitted && !atomic_tools && (!pending_tools.is_empty() || reason == StopReason::ToolUse) { return Err(SmithError::Provider { fault: smith::error::ProviderFault::Protocol { message: "admitted text execution does not support tool use".into(), }, }); } if !admitted || !pending_tools.is_empty() { self.record_assistant_round(&masked_text, &pending_tools)?; } let text_only_round = pending_tools.is_empty(); let mut tool_results = Vec::new(); for (call_id, name, tool_input, _) in pending_tools { let recorded_name = self.secrets.mask(&name); let recorded_input = self.secrets.mask_arguments(&tool_input)?; let effect_input = self.secrets.unmask_arguments(&recorded_input)?; events.push(AgentEvent::ToolStarted { name: recorded_name.clone(), call_id, }); let secrets = &self.secrets; let outcome = self .tools .invoke_local( call_id, &recorded_name, &recorded_input, &effect_input, |text| secrets.mask(text), ) .map_err(|error| self.secrets.mask_error(error))?; events.push(AgentEvent::ToolFinished { name: recorded_name, call_id, ok: outcome.ok, mutation_state: outcome.mutation_state, }); if !atomic_tools { tool_results.push(ContentBlock::tool_result( call_id, outcome.ok, self.secrets.mask(&outcome.output), )); } } // Tool results return as one Tool-role message, paired and // ordered exactly as the calls were issued. self.record_tool_results(tool_results)?; self.check_cancelled()?; self.tools.end_provider_round(); let eligible = matches!(reason, StopReason::EndTurn | StopReason::ToolUse); let event = smith::lifecycle::LifecycleEvent { root_entry_id: terminal_event.root_entry_id, boundary: smith::lifecycle::Boundary::TurnComplete, round_index, last_stop: reason, continuation_eligible: eligible, }; *terminal_event = event; let mut continuation = self.lifecycle_boundary(&event)?; let queued = self .queue .front() .is_some_and(|input| input.delivery == Delivery::BetweenRequests); if reason != StopReason::ToolUse && !queued && !continuation { continuation = self.lifecycle_boundary(&smith::lifecycle::LifecycleEvent { boundary: smith::lifecycle::Boundary::PreSettlement, ..event })?; } self.check_cancelled()?; if eligible && (reason == StopReason::ToolUse || queued || continuation) { if admitted && text_only_round { self.record_assistant_round(&masked_text, &[])?; } round_index = round_index .checked_add(1) .ok_or_else(|| crate::context::invalid("provider round index overflow"))?; if round_index >= self.continuation_round_limit { return Err(crate::context::invalid( "provider request round limit exceeded", )); } continue; } return Ok(TurnOutcome { text: masked_text, reason, cost: *cost, cost_complete: *cost_complete, events: std::mem::take(events), }); } } /// Set a positive provider-round ceiling for handler-requested continuation. /// /// # Errors /// Rejects zero; no run may have an unbounded request loop. pub fn set_continuation_round_limit(&mut self, rounds: u32) -> Result<()> { if rounds == 0 { return Err(crate::context::invalid( "continuation round limit must be positive", )); } self.continuation_round_limit = rounds; Ok(()) } #[expect( clippy::too_many_lines, reason = "one atomic lifecycle action batch validates before publishing any non-cancel action" )] fn lifecycle_boundary(&mut self, event: &smith::lifecycle::LifecycleEvent) -> Result { use smith::lifecycle::{DiagnosticCode, LifecycleAction as A, LifecycleDiagnostic}; let mut batch = self .tools .lifecycle(event, &|text| self.secrets.mask(text))?; let notification = event.boundary == smith::lifecycle::Boundary::Settled; if !notification { self.check_cancelled()?; } for action in &mut batch.actions { match action { A::Cancel if !notification => self.cancel.cancel(), A::SetPrompt(text) | A::SetModel(text) | A::SetProvider(text) => { *text = self.secrets.mask(text); } A::EditContext(edits) => { for edit in edits { if let Some(replacement) = &mut edit.replacement { let (smith::lifecycle::ContextReplacement::Text(text) | smith::lifecycle::ContextReplacement::AssistantText(text) | smith::lifecycle::ContextReplacement::ToolResultOutput { output: text, .. }) = replacement; *text = self.secrets.mask(text); } } } A::SetToolPolicy(changes) => { for (name, _) in changes { *name = self.secrets.mask(name); } } _ => {} } } for diagnostic in &mut batch.diagnostics { diagnostic.component = self.secrets.mask(&diagnostic.component); diagnostic.handler = self.secrets.mask(&diagnostic.handler); } let mut edits = Vec::new(); let validation = (|| { smith::lifecycle::validate_actions(&batch.actions)?; self.tools.validate_lifecycle(&batch.actions, &self.model)?; for action in &batch.actions { if let A::EditContext(changes) = action { for edit in changes { if !edits.contains(edit) { edits.push(edit.clone()); } } } } if !edits.is_empty() { self.tools.session.validate_context_edits(&edits)?; } if event.boundary == smith::lifecycle::Boundary::Settled && !batch.actions.is_empty() { return Err(crate::context::invalid( "settled notification cannot return actions", )); } Ok(()) })(); if validation.is_err() { batch.actions.clear(); batch.diagnostics.push(LifecycleDiagnostic { component: String::new(), handler: String::new(), code: DiagnosticCode::BatchRejected, }); batch.required_failure |= batch.required_decision; } if batch.required_failure { batch.actions.clear(); } if !batch.actions.is_empty() || !batch.diagnostics.is_empty() || batch.allocated_bytes != 0 { let detail = encode_metadata(&(event, &batch))?; self.tools.record(&EntryContent::Meta { kind: "lifecycle_decision".into(), detail, })?; } if notification { return Ok(false); } self.check_cancelled()?; if batch.required_failure { return Err(crate::context::invalid( "required lifecycle decision failed", )); } if validation.is_err() { return Ok(false); } // All validation precedes persistence. Context acknowledgement precedes // infallible resident publication; no configuration file is written. if !edits.is_empty() { self.tools.edit_context(&edits)?; } self.tools.commit_lifecycle(&batch.actions); let mut continuation = false; for action in batch.actions { match action { A::EnsureContinuation => continuation = event.continuation_eligible, A::SetPrompt(prompt) => self.prompt = Some(prompt), A::SetModel(model) => self.model = model, _ => {} } } Ok(continuation) } fn record_tool_results(&mut self, results: Vec) -> Result<()> { if results.is_empty() { return Ok(()); } let mut message = Message::new(Role::Tool); message.blocks = results; self.record_message(message) } /// Poll one provider stream to its single terminal outcome. fn consume( &self, stream: smith::provider::ProviderStream, events: &mut Vec, observe: &mut dyn FnMut(&StreamEvent), ) -> Result { let mut round = Round { text: String::new(), tools: Vec::new(), terminal: None, }; let mut redactor = StreamRedactor::default(); let mut failure = None; for item in futures::executor::block_on_stream(stream) { // A genuine provider fault is not changed into cancellation merely // because cancellation was requested concurrently. let event = match item { Ok(event) => event, Err(error) => { failure = Some(self.secrets.mask_error(error)); break; } }; if let StreamEvent::Error { error } = &event { failure = Some(SmithError::Provider { fault: smith::error::ProviderFault::Protocol { message: self.secrets.mask(error), }, }); break; } if let StreamEvent::Stop { reason, usage } = event { round.terminal = Some((reason, usage)); break; } if let Err(error) = self.check_cancelled() { failure = Some(error); break; } match &event { StreamEvent::TextDelta { delta, .. } => round.text.push_str(delta), StreamEvent::ThinkingDelta { .. } | StreamEvent::ToolResult { .. } => {} StreamEvent::ToolUse { name, input, call_id, provider_call_id, .. } => round.tools.push(( *call_id, name.clone(), input.clone(), provider_call_id.clone(), )), StreamEvent::Stop { .. } => { unreachable!("terminal outcomes stop before event handling") } StreamEvent::Error { .. } => unreachable!("errors return before event handling"), } for event in redactor.push(event, &self.secrets)? { observe(&event); events.push(AgentEvent::Streamed { event }); } } for event in redactor.drain(&self.secrets, true)? { observe(&event); events.push(AgentEvent::Streamed { event }); } if let Some(error) = failure { return Err(error); } Ok(round) } /// Decode the provider context into this request: the active branch's /// messages since the compaction boundary. This is the one per-request /// reader of entry content. fn build_request(&self) -> Result { let session = &self.tools.session; let mut messages = session.map_projected_messages(|message| self.secrets.mask_message(message))?; if let Some(prompt) = &self.prompt { messages.retain(|message| message.role != Role::System); messages.insert(0, Message::with_text(Role::System, prompt)); } let mut request = ProviderRequest::new(self.model.clone(), messages); request.tools = self.tools.advertised_tools(); request.provider_call_ids = session.provider_call_ids()?; Ok(request) } fn record_assistant_round( &mut self, text: &str, pending_tools: &[(ToolCallId, String, ToolArguments, String)], ) -> Result<()> { if text.is_empty() && pending_tools.is_empty() { return Ok(()); } let mut message = Message::new(Role::Assistant); if !text.is_empty() { message.add_block(ContentBlock::text(text)); } for (index, (call_id, name, tool_input, _)) in pending_tools.iter().enumerate() { if pending_tools[..index] .iter() .any(|(prior, _, _, _)| prior == call_id) { return Err(SmithError::Session { code: smith::error::SessionCode::SessionIncompleteContext, message: "provider response repeats a Smith tool-call identity".to_string(), }); } message.add_block(ContentBlock::tool_use( self.secrets.mask(name), self.secrets.mask_arguments(tool_input)?, *call_id, )); } self.record_message(message)?; for (call_id, _, _, provider_call_id) in pending_tools { let detail = encode_metadata(&ProviderToolCallIdentityMetadata { call_id: *call_id, provider_call_id: provider_call_id.clone(), })?; self.tools.record(EntryContentRef::Meta { kind: PROVIDER_TOOL_CALL_IDENTITIES_KIND, detail: &detail, })?; } Ok(()) } fn record_user_message(&mut self, text: &str) -> Result { self.tools .record(&EntryContent::Message(Message::with_text(Role::User, text))) .map(|entry| entry.id) } fn record_message(&mut self, message: Message) -> Result<()> { self.tools.record(&EntryContent::Message(message))?; Ok(()) } /// Drain spooled provider effect records into the session as metadata /// entries; every round's records land before its assistant message. fn drain_provider_records(&mut self) -> Result<()> { let Some(drain) = &self.provider_records else { return Ok(()); }; // Records are drained in bulk before any session entry is built. let drained: Vec = drain.try_iter().collect(); for request in drained { let result = (|| { if let Some(provenance) = request.provenance() { let detail = encode_metadata(provenance)?; self.tools.record(&EntryContent::Meta { kind: PROVIDER_DISPATCH_PROVENANCE_KIND.to_string(), detail, })?; } let detail = encode_metadata(request.record())?; self.tools.record(&EntryContent::Meta { kind: PROVIDER_HTTP_KIND.to_string(), detail, })?; Ok(()) })(); request.acknowledge(result.clone()); result?; } Ok(()) } fn deliver_between_request_queue(&mut self) -> Result<()> { loop { let next = self .queue .front() .is_some_and(|input| input.delivery == Delivery::BetweenRequests); if !next { return Ok(()); } let input = self.queue.pop_front(); if let Some(input) = input { self.record_user_message(&self.secrets.mask(&input.text))?; } } } fn check_cancelled(&self) -> Result<()> { if self.cancel.is_cancelled() { return Err(SmithError::Cancelled); } Ok(()) } } #[cfg(test)] #[expect( clippy::unwrap_used, reason = "agent tests assert on scripted mock streams" )] mod tests { use super::*; use crate::session::EntryKind; use crate::session::Session; use crate::store::{SessionReader, open_session}; use futures::StreamExt; use smith::config::Config; use smith::message::{ContentBlock, Role}; use smith::stream::StopReason; /// Mock stream that records the requests it saw. fn recording( responses: Vec>, ) -> ( StreamFn, std::sync::Arc>>, ) { let seen = std::sync::Arc::new(std::sync::Mutex::new(Vec::new())); let responses = std::sync::Arc::new(std::sync::Mutex::new(responses)); let seen_for_stream = std::sync::Arc::clone(&seen); let stream: StreamFn = std::sync::Arc::new(move |request, _cancel| { let index = seen_for_stream.lock().unwrap().len(); seen_for_stream.lock().unwrap().push(request); let response = responses.lock().unwrap()[index].clone(); futures::stream::iter(response.into_iter().map(Ok)).boxed() }); (stream, seen) } /// Every decoded entry content, rendered for secret checks. fn decoded(session: &Session) -> String { let contents: Vec = session .active_branch() .entries() .iter() .map(|entry| session.content(entry).unwrap()) .collect(); format!("{contents:?}") } fn temp_tools(tag: &str) -> ToolSession { let dir = std::env::temp_dir().join(format!("smith_agent_{tag}_{}", std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); ToolSession::new(&dir) } fn tool_use_turn_response() -> Vec { vec![ StreamEvent::text_delta(smith::id::MessageId::new(), "Writing the file."), StreamEvent::tool_use( smith::id::MessageId::new(), "write", ToolArguments::from_serializable( &serde_json::json!({"path": "note.txt", "content": "hi"}), ) .unwrap(), smith::id::ToolCallId::new(), ), StreamEvent::stop(StopReason::ToolUse, Some(Usage::new())), ] } fn final_response() -> Vec { vec![ StreamEvent::text_delta(smith::id::MessageId::new(), "Done."), StreamEvent::stop(StopReason::EndTurn, Some(Usage::new())), ] } fn redacted_chunks(secrets: &SecretProxy, chunks: &[String]) -> String { let message = smith::id::MessageId::new(); let mut redactor = StreamRedactor::default(); let mut output = String::new(); for chunk in chunks { for event in redactor .push(StreamEvent::text_delta(message, chunk), secrets) .unwrap() { if let StreamEvent::TextDelta { delta, .. } = event { output.push_str(&delta); } } } for event in redactor.drain(secrets, true).unwrap() { if let StreamEvent::TextDelta { delta, .. } = event { output.push_str(&delta); } } output } #[test] fn redaction_lookahead_is_lane_isolated_and_bounded() { #[cfg(target_arch = "x86_64")] assert_eq!(std::mem::size_of::(), 24); #[cfg(target_arch = "x86_64")] assert_eq!(std::mem::size_of::(), 96); let mut secrets = SecretProxy::new(); secrets.register("key", "secret"); let mut redactor = StreamRedactor::default(); let blocked = smith::id::MessageId::new(); assert!( redactor .push(StreamEvent::text_delta(blocked, "sec"), &secrets) .unwrap() .is_empty() ); let safe = smith::id::MessageId::new(); for _ in 0..StreamRedactor::PENDING_LANES_LIMIT + 1 { assert_eq!( redactor .push(StreamEvent::thinking_delta(safe, "x"), &secrets) .unwrap(), vec![StreamEvent::thinking_delta(safe, "x")] ); } for _ in 1..StreamRedactor::PENDING_LANES_LIMIT { assert!( redactor .push( StreamEvent::text_delta(smith::id::MessageId::new(), "sec"), &secrets ) .unwrap() .is_empty() ); } assert!( redactor .push( StreamEvent::text_delta(smith::id::MessageId::new(), "sec"), &secrets ) .is_err() ); assert_eq!( StreamRedactor::default() .push( StreamEvent::tool_use( blocked, "x".repeat(StreamRedactor::PENDING_BYTES_LIMIT + 1), ToolArguments::empty_object(), smith::id::ToolCallId::new(), ), &secrets ) .unwrap() .len(), 1 ); } #[test] fn incremental_redaction_masks_all_boundaries_overlaps_and_unicode() { let mut secrets = SecretProxy::new(); secrets.register("short", "abc"); secrets.register("long", "abcd"); secrets.register("unicode", "🔒é密"); for text in [ "before abcd abc after", "🔒é密abcd🔒é密", "abcabc", "ab", "abcde", ] { for split in text .char_indices() .map(|(index, _)| index) .chain(std::iter::once(text.len())) { let chunks = [text[..split].to_owned(), text[split..].to_owned()]; assert_eq!( redacted_chunks(&secrets, &chunks), secrets.mask(text), "split {split} of {text}" ); } let chars: Vec = text .chars() .map(|character| character.to_string()) .collect(); assert_eq!(redacted_chunks(&secrets, &chars), secrets.mask(text)); } } proptest::proptest! { #[test] fn incremental_redaction_is_independent_of_chunk_boundaries(chunks in proptest::collection::vec("[abcé密🔒 ]{0,16}", 0..24)) { let mut secrets = SecretProxy::new(); secrets.register("short", "abc"); secrets.register("long", "abcé"); secrets.register("unicode", "🔒密"); proptest::prop_assert_eq!(redacted_chunks(&secrets, &chunks), secrets.mask(&chunks.concat())); } } #[test] fn incremental_redaction_preserves_interleaved_field_order_without_cross_message_matching() { let mut secrets = SecretProxy::new(); secrets.register("key", "secret"); let first = smith::id::MessageId::new(); let second = smith::id::MessageId::new(); let mut redactor = StreamRedactor::default(); assert!( redactor .push(StreamEvent::text_delta(first, "sec"), &secrets) .unwrap() .is_empty() ); assert_eq!( redactor .push(StreamEvent::thinking_delta(second, "other"), &secrets) .unwrap(), vec![StreamEvent::thinking_delta(second, "other")] ); assert_eq!( redactor .push(StreamEvent::text_delta(first, "ret!"), &secrets) .unwrap(), vec![StreamEvent::text_delta(first, "{{secret:key}}!")] ); assert!( redactor .push(StreamEvent::text_delta(first, "sec"), &secrets) .unwrap() .is_empty() ); assert_eq!( redactor .push(StreamEvent::text_delta(second, "ret"), &secrets) .unwrap(), vec![StreamEvent::text_delta(second, "ret")] ); assert_eq!( redactor.drain(&secrets, true).unwrap(), vec![StreamEvent::text_delta(first, "sec")] ); } #[test] fn observed_progress_is_redacted_before_callback_session_and_outcome() { let text = "safe prefix 🔒é密 abcd end"; for split in text.char_indices().map(|(index, _)| index) { let message = smith::id::MessageId::new(); let (stream, _) = recording(vec![vec![ StreamEvent::text_delta(message, &text[..split]), StreamEvent::text_delta(message, &text[split..]), StreamEvent::stop(StopReason::EndTurn, None), ]]); let mut agent = Agent::new(stream, temp_tools("observed-secrets"), "mock"); agent.secrets.register("unicode", "🔒é密"); agent.secrets.register("overlap", "abc"); agent.secrets.register("long", "abcd"); agent.record_user_message("input").unwrap(); let mut observed = Vec::new(); let outcome = agent .run_admitted_controlled( smith::id::EntryId::new(), |_| Ok(crate::control::SettlementDisposition::Committed), &mut |event| observed.push(event.clone()), ) .unwrap(); let rendered = format!("{observed:?} {outcome:?} {}", decoded(agent.session())); assert!(!rendered.contains("🔒é密")); assert!(!rendered.contains("abcd")); let published: String = observed .iter() .filter_map(|event| match event { StreamEvent::TextDelta { delta, .. } => Some(delta.as_str()), _ => None, }) .collect(); assert_eq!(published, agent.secrets.mask(text)); assert_eq!(outcome.text, published); } } #[test] fn cancellation_never_hides_a_provider_error_or_failed_abort_settlement() { let fault = SmithError::Provider { fault: smith::error::ProviderFault::Protocol { message: "genuine failure".into(), }, }; let failure = fault.clone(); let stream: StreamFn = std::sync::Arc::new(move |_, cancel| { let failure = failure.clone(); futures::stream::iter(vec![Ok(StreamEvent::text_delta( smith::id::MessageId::new(), "observed", ))]) .chain(futures::stream::once(async move { cancel.cancel(); Err(failure) })) .boxed() }); let mut agent = Agent::new(stream, temp_tools("failure-precedence"), "mock"); agent.record_user_message("input").unwrap(); let mut commands = Vec::new(); let result = agent.run_admitted_controlled( smith::id::EntryId::new(), |command| { commands.push(command); Ok(if commands.len() == 1 { crate::control::SettlementDisposition::CancelBeforeCommit } else { crate::control::SettlementDisposition::Committed }) }, &mut |_| {}, ); assert_eq!(result.unwrap_err(), fault); assert!(matches!( commands.as_slice(), [ crate::frame::Frame::Settlement { reason: None, .. }, crate::frame::Frame::Settlement { reason: Some(StopReason::Abort), .. } ] )); for reject in [false, true] { let (stream, _) = recording(vec![]); let mut agent = Agent::new(stream, temp_tools("abort-settlement-failure"), "mock"); agent.record_user_message("input").unwrap(); agent.cancel_handle().cancel(); let result = agent.run_admitted_controlled( smith::id::EntryId::new(), |_| { if reject { Ok(crate::control::SettlementDisposition::CancelBeforeCommit) } else { Err(SmithError::Session { code: smith::error::SessionCode::SessionCorrupt, message: "settlement failed".into(), }) } }, &mut |_| {}, ); assert!(result.is_err()); assert!(agent.tools.recording_failed()); } } #[test] fn unknown_provider_usage_is_not_zero() { let (stream, _) = recording(vec![vec![StreamEvent::stop(StopReason::EndTurn, None)]]); let mut agent = Agent::new(stream, temp_tools("unknown-usage"), "mock"); let outcome = agent.run_turn("input").unwrap(); assert_eq!(outcome.cost, None); assert!(!outcome.cost_complete); assert!(matches!( outcome.events.last(), Some(AgentEvent::TurnSettled { cost: None, .. }) )); } #[test] fn admitted_abort_retains_observed_text_and_completed_usage() { fn usage( input_tokens: u64, output_tokens: u64, input_cache_hit_tokens: u64, input_cache_write_tokens: u64, ) -> Usage { Usage { input_tokens, output_tokens, input_cache_hit_tokens, input_cache_write_tokens, } } // Cancellation on the next dispatch pins completed-round accounting // independently of the binary test's committed file effect. let calls = std::sync::atomic::AtomicUsize::new(0); let stream: StreamFn = std::sync::Arc::new(move |_, _| { let response = if calls.fetch_add(1, std::sync::atomic::Ordering::SeqCst) == 0 { vec![ Ok(StreamEvent::text_delta( smith::id::MessageId::new(), "committed prefix", )), Ok(StreamEvent::stop( StopReason::ToolUse, Some(usage(23, 29, 0, 0)), )), ] } else { vec![Err(SmithError::Cancelled)] }; futures::stream::iter(response).boxed() }); let mut agent = Agent::new(stream, temp_tools("partial-observations"), "mock"); // Atomic completion capability permits provider tool rounds. agent.tools.set_dispatcher(Box::new(CancelAfterFirstWrite { cancel: agent.cancel_handle(), calls: 0, })); agent.tools = agent .tools .with_completion_boundary(smith::id::EntryId::new(), |_| unreachable!()); agent.record_user_message("input").unwrap(); let outcome = agent .run_admitted(smith::id::EntryId::new(), |_| Ok(())) .unwrap(); assert_eq!(outcome.reason, StopReason::Abort); assert_eq!(outcome.text, "committed prefix"); assert_eq!(outcome.cost, Some(usage(23, 29, 0, 0))); assert!(!outcome.cost_complete); } #[test] fn admitted_turn_starts_with_redacted_input_without_recording_it_twice() { let (stream, _) = recording(vec![final_response()]); let mut agent = Agent::new(stream, temp_tools("admitted-lifecycle"), "mock"); agent.secrets.register("api", "secret-value"); let input = agent.secrets.mask("question secret-value"); agent.record_user_message(&input).unwrap(); let id = smith::id::EntryId::new(); let outcome = agent.run_admitted(id, |_| Ok(())).unwrap(); assert!(matches!( outcome.events.first(), Some(AgentEvent::TurnStarted { input }) if input == "question {{secret:api}}" )); assert_eq!( agent .session() .active_branch() .entries() .iter() .filter(|entry| matches!( agent.session().content(entry).unwrap(), EntryContent::Message(message) if message.role == Role::User )) .count(), 1 ); } #[test] fn late_cancel_rejection_never_adopts_unstored_assistant_or_poisons_certain_state() { use crate::control::SettlementDisposition; let (stream, _) = recording(vec![final_response()]); let mut agent = Agent::new(stream, temp_tools("late-cancel"), "mock"); agent.record_user_message("input").unwrap(); let id = smith::id::EntryId::new(); let mut commands = Vec::new(); let result = agent.run_admitted_controlled( id, |command| { let disposition = if commands.is_empty() { SettlementDisposition::CancelBeforeCommit } else { assert_eq!( command, crate::frame::Frame::Settlement { submission_id: id, reason: Some(StopReason::Abort), output: None, } ); SettlementDisposition::Committed }; commands.push(command); Ok(disposition) }, &mut |_| {}, ); let outcome = result.unwrap(); assert_eq!(outcome.reason, StopReason::Abort); assert_eq!(outcome.text, "Done."); assert_eq!( outcome .events .iter() .filter(|event| matches!(event, AgentEvent::TurnSettled { .. })) .count(), 1 ); assert_eq!(commands.len(), 2); assert_eq!(agent.session().active_branch().entries().len(), 1); assert!(!agent.tools.recording_failed()); } #[test] fn admitted_cancellation_commits_abort_without_dispatch_or_duplicate_input() { let (stream, seen) = recording(vec![]); let tools = temp_tools("admitted-cancel"); tools.cancel_handle().cancel(); let mut agent = Agent::new(stream, tools, "mock"); agent.record_user_message("admitted input").unwrap(); let id = smith::id::EntryId::new(); let mut commits = 0; let result = agent.run_admitted(id, |frame| { assert_eq!( frame, crate::frame::Frame::Settlement { submission_id: id, reason: Some(StopReason::Abort), output: None } ); commits += 1; Ok(()) }); let outcome = result.unwrap(); assert_eq!(outcome.reason, StopReason::Abort); assert_eq!(outcome.cost, None); assert!(!outcome.cost_complete); assert_eq!(commits, 1); assert!(seen.lock().unwrap().is_empty()); assert_eq!(agent.session().active_branch().entries().len(), 1); } struct CancelAfterFirstWrite { cancel: smith::tool::CancelHandle, calls: usize, } impl crate::tools::ToolDispatcher for CancelAfterFirstWrite { fn begin_provider_round(&mut self) -> Result { crate::tools::test_tool_snapshot() } fn invoke( &mut self, name: &str, input: &ToolArguments, effects: &mut crate::tools::ToolEffectContext<'_>, ) -> Result { assert_eq!(name, "write"); self.calls += 1; let output = effects.invoke(name, input)?; self.cancel.cancel(); Ok(output) } } #[test] fn admitted_cancellation_after_first_effect_keeps_commit_and_blocks_second_effect() { let first = smith::id::ToolCallId::new(); let second = smith::id::ToolCallId::new(); let response = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), "write", ToolArguments::from_serializable( &serde_json::json!({"path":"first.txt","content":"applied"}), ) .unwrap(), first, ), StreamEvent::tool_use( smith::id::MessageId::new(), "write", ToolArguments::from_serializable( &serde_json::json!({"path":"second.txt","content":"forbidden"}), ) .unwrap(), second, ), StreamEvent::stop(StopReason::ToolUse, Some(Usage::new())), ]; let (stream, seen) = recording(vec![response]); let dir = std::env::temp_dir().join(format!("smith_admitted_effects_{}", std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); let mut tools = ToolSession::new(&dir); let cancel = tools.cancel_handle(); tools.set_dispatcher(Box::new(CancelAfterFirstWrite { cancel, calls: 0 })); let root = tools .session .append(crate::session::EntryContentRef::Message( &Message::with_text(Role::User, "write two files"), )) .unwrap() .id; let commits = std::sync::Arc::new(std::sync::Mutex::new(Vec::new())); let committed = std::sync::Arc::clone(&commits); tools = tools.with_completion_boundary(root, move |frame| { committed.lock().unwrap().push(frame); Ok(()) }); let mut agent = Agent::new(stream, tools, "mock"); let settlements = std::sync::Arc::new(std::sync::Mutex::new(Vec::new())); let settled = std::sync::Arc::clone(&settlements); let outcome = agent .run_admitted(root, move |frame| { settled.lock().unwrap().push(frame); Ok(()) }) .unwrap(); assert_eq!(outcome.reason, StopReason::Abort); assert!(matches!( settlements.lock().unwrap().as_slice(), [crate::frame::Frame::Settlement { reason: Some(StopReason::Abort), output: None, .. }] )); assert_eq!( std::fs::read_to_string(dir.join("first.txt")).unwrap(), "applied" ); assert!(!dir.join("second.txt").exists()); assert_eq!(seen.lock().unwrap().len(), 1); let frames = commits.lock().unwrap(); assert_eq!(frames.len(), 3); assert!(matches!( frames[0], crate::frame::Frame::NestedCommit { .. } )); let outer: Vec<_> = frames .iter() .filter_map(|frame| { if let crate::frame::Frame::Commit { checkpoint, entries, } = frame { Some((checkpoint, entries)) } else { None } }) .collect(); assert_eq!(outer.len(), 2); assert_eq!(outer[0].0.call_id, first); assert_eq!(outer[1].0.call_id, second); for ((_, entries), expected) in outer.iter().zip([ smith::error::MutationState::Applied, smith::error::MutationState::NotApplied, ]) { let crate::session::EntryContent::Meta { detail, .. } = crate::session::EntryContent::decode(&entries[1].content).unwrap() else { panic!("mutation evidence"); }; assert_eq!( detail .deserialize_as::() .unwrap() .mutation_state, expected ); } std::fs::remove_dir_all(dir).unwrap(); } struct CatchNestedRecordingFailure; impl crate::tools::ToolDispatcher for CatchNestedRecordingFailure { fn begin_provider_round(&mut self) -> Result { crate::tools::test_tool_snapshot() } fn invoke( &mut self, name: &str, input: &ToolArguments, effects: &mut crate::tools::ToolEffectContext<'_>, ) -> Result { let _caught = effects.invoke(name, input); let second = ToolArguments::from_serializable( &serde_json::json!({"path":"second.txt","content":"forbidden"}), ) .unwrap(); let _caught = effects.invoke_redacted("write", &second, str::to_string); Ok("guest caught both host errors".into()) } } #[test] fn nested_completion_uncertainty_blocks_followup_provider_even_when_guest_catches_error() { let response = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), "write", ToolArguments::from_serializable( &serde_json::json!({"path":"first.txt","content":"applied"}), ) .unwrap(), smith::id::ToolCallId::new(), ), StreamEvent::stop(StopReason::ToolUse, Some(Usage::new())), ]; let (stream, seen) = recording(vec![response, final_response()]); let dir = std::env::temp_dir().join(format!( "smith-nested-provider-{}", smith::id::SessionId::new() )); std::fs::create_dir(&dir).unwrap(); let mut tools = ToolSession::new(&dir); tools.set_dispatcher(Box::new(CatchNestedRecordingFailure)); let root = tools .session .append(crate::session::EntryContentRef::Message( &Message::with_text(Role::User, "write"), )) .unwrap() .id; let tools = tools.with_completion_boundary(root, |frame| { assert!(matches!(frame, crate::frame::Frame::NestedCommit { .. })); Err(SmithError::Cancelled) }); let mut agent = Agent::new(stream, tools, "mock"); let error = agent .run_admitted(root, |_| { panic!("uncertain nested effect must not settle root") }) .unwrap_err(); assert!(matches!( error, SmithError::RecordFailed { mutation_state: smith::error::MutationState::Applied, .. } )); assert_eq!(seen.lock().unwrap().len(), 1); assert_eq!( std::fs::read_to_string(dir.join("first.txt")).unwrap(), "applied" ); assert!(!dir.join("second.txt").exists()); assert!( agent .run_admitted(root, |_| panic!("no settlement after uncertainty")) .is_err() ); assert_eq!(seen.lock().unwrap().len(), 1); std::fs::remove_dir_all(dir).unwrap(); } #[test] fn payload_chunk_ack_failure_blocks_next_effect_provider_and_settlement() { for phase in [ crate::frame::NestedPayloadPhase::Input, crate::frame::NestedPayloadPhase::Output, ] { let input_phase = phase == crate::frame::NestedPayloadPhase::Input; let content = "line\n".repeat(16 * 1024); let name = if input_phase { "write" } else { "read" }; let arguments = if input_phase { serde_json::json!({"path":"first.txt", "content":content}) } else { serde_json::json!({"path":"first.txt", "max_bytes":content.len()}) }; let response = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), name, ToolArguments::from_serializable(&arguments).unwrap(), smith::id::ToolCallId::new(), ), StreamEvent::stop(StopReason::ToolUse, Some(Usage::new())), ]; let (stream, seen) = recording(vec![response, final_response()]); let dir = std::env::temp_dir().join(format!( "smith-payload-provider-{}", smith::id::SessionId::new() )); std::fs::create_dir(&dir).unwrap(); if !input_phase { std::fs::write(dir.join("first.txt"), &content).unwrap(); } let mut tools = ToolSession::new(&dir); tools.set_dispatcher(Box::new(CatchNestedRecordingFailure)); let root = tools .session .append(crate::session::EntryContentRef::Message( &Message::with_text(Role::User, "invoke"), )) .unwrap() .id; let tools = tools.with_completion_boundary(root, move |frame| { let crate::frame::Frame::NestedPayload { chunk } = frame else { panic!("chunk failure must block completion and outer success") }; assert_eq!(chunk.phase, phase); Err(SmithError::Cancelled) }); let mut agent = Agent::new(stream, tools, "mock"); assert!( agent .run_admitted(root, |_| panic!("no settlement after chunk uncertainty")) .is_err() ); assert_eq!(seen.lock().unwrap().len(), 1); assert_eq!(dir.join("first.txt").exists(), !input_phase); assert!(!dir.join("second.txt").exists()); assert!( agent .run_admitted(root, |_| panic!("no retry settlement")) .is_err() ); assert_eq!(seen.lock().unwrap().len(), 1); std::fs::remove_dir_all(dir).unwrap(); } } #[test] fn uncertain_terminal_persistence_blocks_future_dispatch_and_output() { let (stream, seen) = recording(vec![final_response(), final_response()]); let mut agent = Agent::new(stream, temp_tools("settlement-poison"), "mock"); agent.record_user_message("admitted input").unwrap(); let id = smith::id::EntryId::new(); let result = agent.run_admitted(id, |_| Err(SmithError::Cancelled)); assert!(result.is_err()); assert_eq!(agent.session().active_branch().entries().len(), 1); assert!( agent .run_admitted(id, |_| panic!("uncertain persistence must not settle")) .is_err() ); assert_eq!(seen.lock().unwrap().len(), 1); } #[test] fn secret_registration_handles_rotation_and_overlapping_values() { let mut secrets = SecretProxy::new(); secrets.register("short", "token"); secrets.register("long", "token-suffix"); assert_eq!(secrets.mask("token-suffix"), "{{secret:long}}"); secrets.register("long", "replacement"); assert_eq!(secrets.unmask("{{secret:long}}"), "replacement"); assert_eq!(secrets.mask("replacement"), "{{secret:long}}"); } #[test] fn mock_provider_completes_a_tool_using_turn_with_paired_durable_events() { let (stream, _seen) = recording(vec![tool_use_turn_response(), final_response()]); let tools = temp_tools("turn"); let mut agent = Agent::new(stream, tools, "mock-smith"); let outcome = agent.run_turn("write hi to note.txt").unwrap(); assert_eq!(outcome.reason, StopReason::EndTurn); assert_eq!(outcome.text, "Done."); // Durable order: user, assistant, call, result, mutation completion, assistant. let kinds: Vec<&str> = agent .session() .active_branch() .entries() .iter() .map(|entry| match entry.kind { EntryKind::Message { role, .. } => match role { Role::User => "user", Role::Assistant => "assistant", Role::Tool => "tool", Role::System => "system", }, EntryKind::ToolCall { .. } => "call", EntryKind::ToolResult { .. } => "result", EntryKind::Meta { .. } => "meta", }) .collect(); assert_eq!( kinds, vec![ "user", "assistant", "meta", "call", "result", "meta", "tool", "assistant" ] ); // The tool effect happened. assert_eq!( std::fs::read_to_string( std::env::temp_dir() .join(format!("smith_agent_turn_{}", std::process::id())) .join("note.txt") ) .unwrap_or_default(), "hi" ); // Tool lifecycle events bracket the recorded pair. let names: Vec<&str> = outcome .events .iter() .filter_map(|event| match event { AgentEvent::ToolStarted { name, .. } | AgentEvent::ToolFinished { name, .. } => { Some(name.as_str()) } _ => None, }) .collect(); assert_eq!(names, vec!["write", "write"]); } #[test] fn executed_tool_failure_returns_to_provider_and_turn_continues() { let call_id = smith::id::ToolCallId::new(); let failed_read = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), "read", ToolArguments::from_serializable(&serde_json::json!({"path": "missing.txt"})) .unwrap(), call_id, ), StreamEvent::stop(StopReason::ToolUse, None), ]; let (stream, seen) = recording(vec![failed_read, final_response()]); let tools = temp_tools("tool_failure"); let mut agent = Agent::new(stream, tools, "mock-smith"); let outcome = agent.run_turn("read the missing file").unwrap(); assert_eq!(outcome.reason, StopReason::EndTurn); assert!(outcome.events.iter().any(|event| matches!( event, AgentEvent::ToolFinished { call_id: finished, ok: false, .. } if *finished == call_id ))); { let requests = seen.lock().unwrap(); assert_eq!(requests.len(), 2); assert!(requests[1].messages.iter().any(|message| { message.blocks.iter().any(|block| { matches!( block, ContentBlock::ToolResult { call_id: result, ok: false, output, } if *result == call_id && output.contains("READ_ERROR") ) }) })); drop(requests); } let durable_ids: Vec = agent .session() .active_branch() .entries() .iter() .filter_map(|entry| match entry.kind { EntryKind::ToolCall { call_id } | EntryKind::ToolResult { call_id, .. } => { Some(call_id) } _ => None, }) .collect(); assert_eq!(durable_ids, vec![call_id, call_id]); } #[test] fn steering_is_delivered_between_requests_and_never_splits_pairs() { let third: Vec = vec![StreamEvent::stop(StopReason::EndTurn, None)]; let (stream, seen) = recording(vec![tool_use_turn_response(), final_response(), third]); let tools = temp_tools("steering"); let mut agent = Agent::new(stream, tools, "mock-smith"); agent.queue(QueuedInput { text: "also uppercase it".to_string(), delivery: Delivery::BetweenRequests, }); agent.run_turn("write hi").unwrap(); // Second request already carries the steering message: user, tool // exchange, steering. The recorded pair stays adjacent. let second = { let requests = seen.lock().unwrap(); requests[1].clone() }; assert_eq!(second.messages.len(), 4); assert!( second.messages.iter().any(|message| matches!( message.blocks.first(), Some(ContentBlock::Text(text)) if text.contains("uppercase") )), "steering message missing from {second:?}" ); let kinds: Vec<&str> = agent .session() .active_branch() .entries() .iter() .map(|entry| match entry.kind { EntryKind::ToolCall { .. } => "call", EntryKind::ToolResult { .. } => "result", _ => "other", }) .collect(); let pair_position = kinds .windows(2) .position(|window| window == ["call", "result"]) .unwrap(); // Steering was recorded after the pair, never inside it. assert!(pair_position + 2 <= kinds.len()); } #[test] fn turn_cost_sums_the_usage_of_every_round() { let usage = |input, output, hit, write| Usage { input_tokens: input, output_tokens: output, input_cache_hit_tokens: hit, input_cache_write_tokens: write, }; let mut tool_round = tool_use_turn_response(); tool_round.pop(); tool_round.push(StreamEvent::stop( StopReason::ToolUse, Some(usage(3, 5, 7, 11)), )); let final_round = vec![StreamEvent::stop( StopReason::EndTurn, Some(usage(2, 4, 6, 8)), )]; let (stream, _seen) = recording(vec![tool_round, final_round]); let mut agent = Agent::new(stream, temp_tools("cost"), "mock-smith"); let outcome = agent.run_turn("write hi").unwrap(); assert_eq!(outcome.cost, Some(usage(5, 9, 13, 19))); assert!(matches!( outcome.events.last(), Some(AgentEvent::TurnSettled { cost, .. }) if *cost == outcome.cost )); } #[test] fn queued_input_is_delivered_in_order_within_a_deadline() { let (stream, seen) = recording(vec![final_response(), final_response()]); let mut agent = Agent::new(stream, temp_tools("queued"), "mock-smith"); agent.queue(QueuedInput { text: "steer".to_string(), delivery: Delivery::BetweenRequests, }); agent.queue(QueuedInput { text: "follow up".to_string(), delivery: Delivery::AfterTurn, }); // The agent runs off the test thread so a delivery loop that never // settles fails the deadline instead of hanging the test. let (done, settled) = std::sync::mpsc::channel(); std::thread::spawn(move || { let texts = |outcomes: Vec| -> Vec { outcomes.into_iter().map(|outcome| outcome.text).collect() }; let first = agent.run_turn("start").map(|outcome| texts(vec![outcome])); let _ = done.send((first, agent.run_queued().map(texts))); }); let (first, queued) = settled .recv_timeout(std::time::Duration::from_secs(10)) .expect("queued input settled within the deadline"); assert_eq!(first.unwrap(), vec!["Done."]); assert_eq!(queued.unwrap(), vec!["Done."]); let user_texts: Vec> = seen .lock() .unwrap() .iter() .map(|request| { request .messages .iter() .filter(|message| message.role == Role::User) .filter_map(|message| match message.blocks.first() { Some(ContentBlock::Text(text)) => Some(text.clone()), _ => None, }) .collect() }) .collect(); assert_eq!( user_texts, vec![vec!["start", "steer"], vec!["start", "steer", "follow up"]] ); } #[test] fn cancellation_aborts_without_partial_durable_claims() { let (stream, _seen) = recording(vec![tool_use_turn_response()]); let tools = temp_tools("cancel"); let mut agent = Agent::new(stream, tools, "mock-smith"); let cancel = agent.cancel_handle(); cancel.cancel(); let error = agent.run_turn("hello").unwrap_err(); assert_eq!(error.code(), "CANCELLED"); // Only the user message was recorded; no assistant claims exist. assert_eq!(agent.session().active_branch().entries().len(), 1); } #[test] fn request_build_rejects_a_message_record_holding_other_content() { let mut forged = crate::session::EntryFrame::new( None, &EntryContent::ToolResult { ok: true, output: "not a message".to_string(), call_id: ToolCallId::new(), }, ) .unwrap(); forged.kind = EntryKind::Message { id: smith::id::MessageId::new(), role: Role::User, }; let (stream, seen) = recording(vec![final_response()]); let mut tools = temp_tools("kind_mismatch"); tools.session = Session::from_frames(&[crate::frame::Frame::Known { entry: forged }]).unwrap(); let mut agent = Agent::new(stream, tools, "mock-smith"); let error = agent.run_turn("hello").unwrap_err(); assert_eq!(error.code(), "ENTRY_KIND_MISMATCH"); assert!(seen.lock().unwrap().is_empty()); } #[test] fn cancelled_tool_is_paired_before_the_next_turn() { let call_id = smith::id::ToolCallId::new(); let signal = crate::process_signal::ProcessSignal::new(); let running_tool = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), "bash", ToolArguments::from_serializable(&serde_json::json!({"command": format!("{}; sleep 30", signal.raise()), "timeout_ms": 30_000})).unwrap(), call_id, ), StreamEvent::stop(StopReason::ToolUse, None), ]; let (stream, seen) = recording(vec![running_tool, final_response()]); let tools = temp_tools("cancelled_pair"); let mut agent = Agent::new(stream, tools, "mock-smith"); let cancel = agent.cancel_handle(); // synchronize: cancel once the tool's command reports it runs, never after a guessed delay. let canceller = std::thread::spawn(move || { let mut socket = signal.wait(); cancel.cancel(); crate::process_signal::closed(&mut socket) }); let error = agent.run_turn("start the command").unwrap_err(); assert!(canceller.join().unwrap(), "tool command kept running"); assert_eq!(error.code(), "CANCELLED"); agent.renew_cancel_handle(); agent.run_turn("continue").unwrap(); let requests = seen.lock().unwrap(); let restarted = &requests[1]; let uses = restarted .messages .iter() .flat_map(|message| &message.blocks) .filter(|block| matches!(block, ContentBlock::ToolUse { call_id: id, .. } if *id == call_id)) .count(); let results = restarted .messages .iter() .flat_map(|message| &message.blocks) .filter(|block| matches!(block, ContentBlock::ToolResult { call_id: id, ok: false, .. } if *id == call_id)) .count(); assert_eq!((uses, results), (1, 1)); drop(requests); } #[test] fn nested_secret_values_and_keys_are_masked_and_restored() { let mut proxy = SecretProxy::new(); proxy.register("token", "s3cr3t-value"); let input = ToolArguments::from_serializable(&serde_json::json!({ "s3cr3t-value": ["prefix s3cr3t-value suffix", {"leaf": "s3cr3t-value"}], "scalars": [null, true, -1, u64::MAX, -0.0] })) .unwrap(); let masked = proxy.mask_arguments(&input).unwrap(); assert_eq!( serde_json::to_value(&masked).unwrap(), serde_json::json!({ "{{secret:token}}": ["prefix {{secret:token}} suffix", {"leaf": "{{secret:token}}"}], "scalars": [null, true, -1, u64::MAX, -0.0] }) ); assert!( !serde_json::to_string(&masked) .unwrap() .contains("s3cr3t-value") ); assert_eq!(proxy.unmask_arguments(&masked).unwrap(), input); } #[test] fn secrets_cross_only_the_authorized_local_effect_boundary() { let call_id = smith::id::ToolCallId::new(); let tool_response = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), "write", ToolArguments::from_serializable(&serde_json::json!({ "path": "secret.txt", "content": "{{secret:api_key}}", })) .unwrap(), call_id, ), StreamEvent::stop(StopReason::ToolUse, Some(Usage::new())), ]; let echo_id = smith::id::MessageId::new(); let secret_echo = vec![ StreamEvent::text_delta(echo_id, "s3cr3t-"), StreamEvent::text_delta(echo_id, "value"), StreamEvent::stop(StopReason::EndTurn, Some(Usage::new())), ]; let (stream, seen) = recording(vec![tool_response, secret_echo]); let tools = temp_tools("secrets"); let secret_path = tools.working_dir().join("secret.txt"); let mut agent = Agent::new(stream, tools, "mock-smith"); agent.secrets_mut().register("api_key", "s3cr3t-value"); let outcome = agent.run_turn("use {{secret:api_key}} locally").unwrap(); let requests = seen.lock().unwrap(); let dispatched = format!("{requests:?}"); assert!(!dispatched.contains("s3cr3t-value")); drop(requests); let recorded = decoded(agent.session()); assert!(recorded.contains("{{secret:api_key}}")); assert!(!recorded.contains("s3cr3t-value")); assert_eq!( std::fs::read_to_string(secret_path).unwrap(), "s3cr3t-value" ); let surfaced: String = outcome .events .iter() .filter_map(|event| match event { AgentEvent::Streamed { event: StreamEvent::TextDelta { delta, .. }, } => Some(delta.as_str()), _ => None, }) .collect(); assert!(!surfaced.contains("s3cr3t-value")); assert!(surfaced.contains("{{secret:api_key}}")); } #[test] fn secrets_registered_later_are_masked_in_earlier_recorded_context() { let (stream, seen) = recording(vec![final_response(), final_response()]); let mut agent = Agent::new(stream, temp_tools("late_secret"), "mock-smith"); agent.run_turn("my key is s3cr3t-value").unwrap(); agent.secrets_mut().register("api_key", "s3cr3t-value"); agent.run_turn("again").unwrap(); let requests = seen.lock().unwrap(); let resent = format!("{:?}", requests[1].messages); drop(requests); assert!(resent.contains("my key is {{secret:api_key}}"), "{resent}"); assert!(!resent.contains("s3cr3t-value"), "{resent}"); } #[test] fn secret_bearing_tool_output_stays_out_of_persisted_session() { let dir = std::env::temp_dir().join(format!("smith_agent_secret_output_{}", std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); let path = dir.join("session.smh"); let opened = open_session(&path, Config::default_valid()).unwrap(); let tools = ToolSession::with_session(&dir, opened.session, opened.writer); let response = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), "bash", ToolArguments::from_serializable( &serde_json::json!({"command": "printf '{{secret:api_key}}'"}), ) .unwrap(), smith::id::ToolCallId::new(), ), StreamEvent::stop(StopReason::ToolUse, None), ]; let (stream, seen) = recording(vec![response, final_response()]); let mut agent = Agent::new(stream, tools, "mock-smith"); agent.secrets_mut().register("api_key", "s3cr3t-value"); let outcome = agent.run_turn("run it locally").unwrap(); assert!(!format!("{outcome:?}").contains("s3cr3t-value")); assert!(!format!("{:?}", *seen.lock().unwrap()).contains("s3cr3t-value")); drop(agent); assert!( !std::fs::read(&path) .unwrap() .windows("s3cr3t-value".len()) .any(|window| window == b"s3cr3t-value") ); let reopened = open_session(&path, Config::default_valid()).unwrap(); let restored = decoded(&reopened.session); assert!(restored.contains("{{secret:api_key}}")); assert!(!restored.contains("s3cr3t-value")); let _ = std::fs::remove_dir_all(&dir); } #[test] fn secret_bearing_tool_errors_are_recorded_and_returned_redacted() { let response = vec![ StreamEvent::tool_use( smith::id::MessageId::new(), "bash", ToolArguments::from_serializable(&serde_json::json!({ "command": "printf '{{secret:api_key}}' >&2; exit 7", })) .unwrap(), smith::id::ToolCallId::new(), ), StreamEvent::stop(StopReason::ToolUse, None), ]; let (stream, seen) = recording(vec![response, final_response()]); let tools = temp_tools("secret_error"); let mut agent = Agent::new(stream, tools, "mock-smith"); agent.secrets_mut().register("api_key", "s3cr3t-value"); let outcome = agent.run_turn("run it locally").unwrap(); assert!(!format!("{outcome:?}").contains("s3cr3t-value")); { let requests = seen.lock().unwrap(); let tool_error = requests[1] .messages .iter() .flat_map(|message| &message.blocks) .find_map(|block| match block { ContentBlock::ToolResult { ok: false, output, .. } => Some(output), _ => None, }) .unwrap(); assert!(tool_error.contains("{{secret:api_key}}")); assert!(!tool_error.contains("s3cr3t-value")); drop(requests); } let recorded = decoded(agent.session()); assert!(recorded.contains("{{secret:api_key}}")); assert!(!recorded.contains("s3cr3t-value")); } #[test] fn compaction_rejects_incomplete_summaries_and_resets_context() { let (stream, seen) = recording(vec![final_response(), final_response()]); let tools = temp_tools("compaction"); let mut agent = Agent::new(stream, tools, "mock-smith"); agent.run_turn("first").unwrap(); let error = agent .compact(&CompactionSummary { text: "partial".to_string(), complete: false, }) .unwrap_err(); assert_eq!(error.code(), "COMPACTION_INCOMPLETE"); agent .compact(&CompactionSummary { text: "summary of first".to_string(), complete: true, }) .unwrap(); // Requests after compaction start from the boundary. agent.run_turn("second").unwrap(); let last = { let requests = seen.lock().unwrap(); requests.last().cloned() }; assert!(last.is_some_and(|request| request.messages.len() <= 2)); } #[test] fn live_compaction_drops_pre_summary_entries() { let dir = std::env::temp_dir().join(format!( "smith_agent_live_compaction_{}", std::process::id() )); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); let path = dir.join("session.smh"); let config = Config::default_valid(); let opened = open_session(&path, config.clone()).unwrap(); let tools = ToolSession::with_session(&dir, opened.session, opened.writer); let (stream, _seen) = recording(vec![final_response()]); let mut agent = Agent::new(stream, tools, "mock-smith"); agent.run_turn("first").unwrap(); let boundary = agent .compact(&CompactionSummary { text: "summary of first".to_string(), complete: true, }) .unwrap(); assert_eq!(agent.session().active_branch().entries().len(), 1); let mut durable = Vec::new(); SessionReader::open(&path) .unwrap() .replay_at(boundary, config.frame_bytes_max, |entry| { durable.push(entry.id); Ok(()) }) .unwrap(); assert_eq!( durable.len(), 3, "durable history keeps the summary ancestry" ); drop(agent); let _ = std::fs::remove_dir_all(&dir); } #[test] fn durable_turn_survives_reload_with_same_identity() { let dir = std::env::temp_dir().join(format!("smith_agent_durable_{}", std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); let path = dir.join("session.smh"); let config = Config::default_valid(); let opened = open_session(&path, config).unwrap(); let tools = ToolSession::with_session(&dir, opened.session, opened.writer); let (stream, _seen) = recording(vec![final_response()]); let mut agent = Agent::new(stream, tools, "mock-smith"); agent.run_turn("persisted").unwrap(); let session_id = agent.session().id(); drop(agent); let reopened = open_session(&path, Config::default_valid()).unwrap(); assert_eq!(reopened.session.id(), session_id); assert_eq!(reopened.session.active_branch().entries().len(), 2); let _ = std::fs::remove_dir_all(&dir); } } /// Secret masking laws (`SMH-SPEC-SPEC0001`, Compaction, cost, and secrets). /// /// Secret values use `[A-Z0-9]`, possibly empty, names `[a-z]`, and filler text never holds /// `{`: no value can match inside a placeholder and no input holds one, the /// precondition under which masking is reversible. #[cfg(test)] mod properties { use super::SecretProxy; use proptest::collection::vec; use proptest::prelude::*; /// Registered secrets and a text interleaving filler with their values. fn secrets_and_text() -> impl Strategy, String)> { vec(("[a-z]{1,6}", "[A-Z0-9]{0,8}"), 1..5).prop_flat_map(|secrets| { let count = secrets.len(); let pieces = vec(("[^{]{0,12}", proptest::option::of(0..count)), 0..6); (Just(secrets), pieces).prop_map(|(secrets, pieces)| { let mut text = String::new(); for (filler, secret) in pieces { text.push_str(&filler); if let Some(index) = secret { text.push_str(&secrets[index].1); } } (secrets, text) }) }) } fn proxy(secrets: &[(String, String)]) -> SecretProxy { let mut proxy = SecretProxy::new(); for (name, value) in secrets { proxy.register(name.clone(), value.clone()); } proxy } proptest! { #[test] fn unmask_restores_masked_text((secrets, text) in secrets_and_text()) { let proxy = proxy(&secrets); prop_assert_eq!(proxy.unmask(&proxy.mask(&text)), text); } #[test] fn masked_text_holds_no_registered_value((secrets, text) in secrets_and_text()) { let masked = proxy(&secrets).mask(&text); // A later registration under the same name replaces the value. let registered: std::collections::HashMap<&str, &str> = secrets .iter() .map(|(name, value)| (name.as_str(), value.as_str())) .collect(); for value in registered.values().filter(|value| !value.is_empty()) { prop_assert!(!masked.contains(value), "{value} survived in {masked}"); } } } }