Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-core/src/agent.rs

Raw
//! 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<Usage>,
    },
}

/// 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<String>,
    continuation_round_limit: u32,
    cancel: CancelHandle,
    queue: VecDeque<QueuedInput>,
    /// Secret placeholder prefix used by [`SecretProxy`]-masked content.
    secrets: SecretProxy,
    /// Redacted provider effect records spooled by the transport.
    provider_records: Option<smith::provider::RecordDrain>,
}

/// 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<String>, value: impl Into<String>) {
        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<ToolArguments> {
        value
            .transform_strings(&|text| self.mask(text), 64)
            .map_err(structured_error)
    }

    fn unmask_arguments(&self, value: &ToolArguments) -> Result<ToolArguments> {
        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<Usage>,
    /// Whether every dispatched provider round supplied usage.
    pub cost_complete: bool,
    /// Events emitted during the turn.
    pub events: Vec<AgentEvent>,
}

fn aborted_outcome(
    mut events: Vec<AgentEvent>,
    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<PendingDelta>,
}

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<Vec<StreamEvent>> {
        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<Vec<StreamEvent>> {
        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::<usize>()
            > 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<Vec<StreamEvent>> {
        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<Vec<StreamEvent>> {
        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<Usage>)>,
}

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<String>) -> 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<String>,
        records: Option<smith::provider::RecordDrain>,
    ) -> 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<smith::id::EntryId> {
        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<String>) -> Result<TurnOutcome> {
        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<Vec<TurnOutcome>> {
        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<TurnOutcome> {
        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<crate::control::SettlementDisposition>,
        observe: &mut dyn FnMut(&StreamEvent),
    ) -> Result<TurnOutcome> {
        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<crate::control::SettlementDisposition>,
        observe: &mut dyn FnMut(&StreamEvent),
        phase: &mut dyn FnMut(crate::control::ExecutionPhase) -> Result<()>,
    ) -> Result<TurnOutcome> {
        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<String> {
        {
            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::<String>(),
                        );
                        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<crate::control::SettlementDisposition>,
    ) -> 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<AgentEvent>,
        admitted: bool,
        cost: &mut Option<Usage>,
        cost_complete: &mut bool,
        observe: &mut dyn FnMut(&StreamEvent),
        phase: &mut dyn FnMut(crate::control::ExecutionPhase) -> Result<()>,
    ) -> Result<TurnOutcome> {
        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<AgentEvent>,
        admitted: bool,
        cost: &mut Option<Usage>,
        cost_complete: &mut bool,
        observe: &mut dyn FnMut(&StreamEvent),
    ) -> Result<TurnOutcome> {
        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<bool> {
        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<ContentBlock>) -> 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<AgentEvent>,
        observe: &mut dyn FnMut(&StreamEvent),
    ) -> Result<Round> {
        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<ProviderRequest> {
        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<smith::id::EntryId> {
        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<smith::provider::ProviderRecordRequest> = 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<Vec<StreamEvent>>,
    ) -> (
        StreamFn,
        std::sync::Arc<std::sync::Mutex<Vec<ProviderRequest>>>,
    ) {
        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<EntryContent> = 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<StreamEvent> {
        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<StreamEvent> {
        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::<StreamRedactor>(), 24);
        #[cfg(target_arch = "x86_64")]
        assert_eq!(std::mem::size_of::<TurnOutcome>(), 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<String> = 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::ToolDispatcherSnapshot> {
            crate::tools::test_tool_snapshot()
        }

        fn invoke(
            &mut self,
            name: &str,
            input: &ToolArguments,
            effects: &mut crate::tools::ToolEffectContext<'_>,
        ) -> Result<String> {
            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::<crate::metadata::ToolMutationMetadata>()
                    .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::ToolDispatcherSnapshot> {
            crate::tools::test_tool_snapshot()
        }

        fn invoke(
            &mut self,
            name: &str,
            input: &ToolArguments,
            effects: &mut crate::tools::ToolEffectContext<'_>,
        ) -> Result<String> {
            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<ToolCallId> = 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<StreamEvent> = 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<TurnOutcome>| -> Vec<String> {
                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<Vec<String>> = 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<Value = (Vec<(String, String)>, 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}");
            }
        }
    }
}