//! Tool registry, validation, built-in file effects, and the durable //! outcome boundary between successful effects and recorded session frames. //! //! (`SMH-SPEC-SPEC0001`, Tools). mod lifecycle; use crate::metadata::{ToolMutationMetadata, encode as encode_metadata}; use crate::session::{ Entry, EntryContentRef, PLUGIN_HTTP_KIND, PLUGIN_LOG_KIND, Session, TOOL_MUTATION_KIND, }; use crate::store::SessionWriter; pub use crate::workspace::WorkspaceRoot; use serde::{Deserialize, Serialize}; use smith::config::Config; use smith::error::{MutationState, Result, SmithError}; use smith::id::ToolCallId; #[cfg(test)] use smith::structured::ToolSchema; use smith::structured::{Kind, SchemaError, StructuredData, StructuredValue, ToolArguments}; use smith::tool::{CancelHandle, ToolMetadata}; use std::collections::HashMap; use std::fs; use std::io::{BufRead, BufReader, Read, Write}; use std::path::{Path, PathBuf}; use std::sync::Arc; use std::sync::atomic::{AtomicUsize, Ordering}; use std::time::{Duration, Instant}; #[cfg(test)] mod commit_tests; #[cfg(test)] mod nested_tests; const HARD_OUTPUT_CAP: usize = 256 * 1024; const DEFAULT_OUTPUT_CAP: usize = 64 * 1024; const LIST_ENTRIES_MAX: usize = 1000; const IGNORE_LINES_MAX: usize = 1000; const IGNORE_LINE_BYTES_MAX: usize = 8 * 1024; const GREP_MATCHES_MAX: usize = 200; const GREP_LINE_BYTES_MAX: usize = DEFAULT_OUTPUT_CAP; const EDIT_FILE_BYTES_MAX: usize = 8 * 1024 * 1024; /// Read one LF-delimited line without materializing more than `bytes_max` bytes. fn read_line_bounded( reader: &mut impl BufRead, line: &mut Vec, bytes_max: usize, ) -> std::io::Result { #[expect( clippy::disallowed_methods, reason = "Take caps one line before overflow is reported" )] let bytes_read = reader .take((bytes_max + 1) as u64) .read_until(b'\n', line)?; if bytes_read == 0 { return Ok(false); } let line_ended = line.ends_with(b"\n") || reader.fill_buf()?.is_empty(); if line.len() > bytes_max || !line_ended { return Err(std::io::Error::new( std::io::ErrorKind::InvalidData, format!("line exceeds {bytes_max} bytes"), )); } Ok(true) } /// Registry of available tools. #[derive(Clone, Debug, Default)] pub struct ToolRegistry { /// Tools by name. tools: HashMap, /// Name-ordered snapshot handed to every provider request; rebuilt on /// registration, shared afterwards. snapshot: Arc<[ToolMetadata]>, } impl ToolRegistry { /// An empty registry. #[must_use] pub fn new() -> Self { Self::default() } /// Register or replace a tool definition. pub fn register(&mut self, meta: ToolMetadata) { self.tools.insert(meta.name.clone(), meta); let mut ordered: Vec = self.tools.values().cloned().collect(); ordered.sort_by(|left, right| left.name.cmp(&right.name)); self.snapshot = ordered.into(); } /// The registered tool, when present. #[must_use] pub fn get(&self, name: &str) -> Option<&ToolMetadata> { self.tools.get(name) } /// The name-ordered tool definitions, for provider requests. #[must_use] pub fn snapshot(&self) -> Arc<[ToolMetadata]> { Arc::clone(&self.snapshot) } } #[cfg(test)] pub(crate) fn test_tool_registry() -> ToolRegistry { let mut registry = ToolRegistry::new(); for (name, description, schema) in [ ( "read", "Read a bounded line window from a file.", ToolSchema::object( &[ ("path", "string"), ("offset", "integer"), ("limit", "integer"), ("max_bytes", "integer"), ], &["path"], ), ), ( "write", "Atomically replace a file, creating parents.", ToolSchema::object( &[("path", "string"), ("content", "string")], &["path", "content"], ), ), ( "edit", "Apply one exact, unambiguous replacement.", ToolSchema::object( &[ ("path", "string"), ("old_string", "string"), ("new_string", "string"), ], &["path", "old_string", "new_string"], ), ), ( "ls", "List a directory deterministically.", ToolSchema::object(&[("path", "string")], &[]), ), ( "find", "Find directory entries matching a substring.", ToolSchema::object(&[("path", "string"), ("pattern", "string")], &["pattern"]), ), ( "grep", "Return bounded matching lines from a file.", ToolSchema::object( &[("path", "string"), ("query", "string")], &["path", "query"], ), ), ( "bash", "Run a bounded cancellable shell command with host filesystem and network access.", ToolSchema::object( &[("command", "string"), ("timeout_ms", "integer")], &["command"], ), ), ] { registry.register(ToolMetadata::new(name, description).with_schema(schema)); } registry } type PersistEntry = dyn FnMut(&Entry, &[u8]) -> Result<()> + Send; type PersistCompletion = dyn FnMut(crate::frame::Frame) -> Result<()> + Send; struct CompletionBoundary { submission_id: smith::id::EntryId, persist: Box, } /// Immutable identity of one component that contributed advertised tools. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct ToolComponentProvenance { /// Stable package or built-in source identity. pub source_id: String, /// SHA-256 of the exact manifest source. pub manifest_sha256: String, /// SHA-256 of the exact component artifact. pub component_sha256: String, } /// Exact tool definition paired with its pinned component generation. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct ToolLoadoutTool { /// Definition advertised to the provider. pub definition: ToolMetadata, /// Index into [`ToolLoadoutProvenance::components`]. pub component_index: u16, } /// Bounded immutable dispatcher snapshot for one provider request. #[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct ToolLoadoutProvenance { /// Hash-pinned component generations owning this snapshot. pub components: Vec, /// Exact advertised definitions and their owner generation. pub tools: Vec, } impl ToolLoadoutProvenance { /// Construct an empty snapshot. #[must_use] pub const fn empty() -> Self { Self { components: Vec::new(), tools: Vec::new(), } } } /// Shared host-owned availability, pinned with one request. pub use smith::lifecycle::ToolAvailability as ToolPolicyState; /// Definitions and provenance pinned together for one provider request. #[derive(Clone, Debug, Default, PartialEq, Eq)] pub struct ToolDispatcherSnapshot { /// Definitions advertised to the provider. pub tools: Vec, /// Every registered definition eligible for host-owned policy resolution. /// /// This can include active hidden tools; provider requests receive only `tools`. pub registered_tools: Vec, /// Host-resolved authority for every registered identity. pub policy: Vec<(String, ToolPolicyState)>, /// Durable identity paired exactly with `tools`. pub provenance: ToolLoadoutProvenance, } /// Dispatches a validated tool call through a host-owned extension. pub trait ToolDispatcher: Send { /// Publish one immutable tool-definition snapshot before a provider request. /// /// Implementations retain the matching handlers until /// [`ToolDispatcher::end_provider_round`] so definitions and execution /// cannot cross a plugin generation boundary. /// /// # Errors /// /// Returns a loading or registration error before the provider request. fn begin_provider_round(&mut self) -> Result { Ok(ToolDispatcherSnapshot::default()) } /// Release handlers pinned by [`ToolDispatcher::begin_provider_round`]. fn end_provider_round(&mut self) {} /// Whether this dispatcher subscribes to a lifecycle boundary. /// /// Empty dispatchers default to no subscriptions, avoiding cleanup scopes. /// Implementations overriding lifecycle dispatch must declare their membership. fn has_lifecycle_handlers(&self, _boundary: smith::lifecycle::Boundary) -> bool { false } /// Invoke sandbox lifecycle handlers without model-tool attribution or effects. /// /// # Errors /// Returns uncatchable host recording or cancellation failure. fn lifecycle( &mut self, _event: &smith::lifecycle::LifecycleEvent, _cancel: &CancelHandle, ) -> Result { Ok(smith::lifecycle::LifecycleBatch::default()) } /// Dispatch lifecycle handlers through an exclusive durable root context. /// /// # Errors /// Recording uncertainty is terminal, even if a handler catches an import error. fn lifecycle_effects( &mut self, event: &smith::lifecycle::LifecycleEvent, effects: &mut ToolEffectContext<'_>, ) -> Result { self.lifecycle(event, &effects.cancel_handle()) } /// Validate runtime choices against host authority before any publication. /// /// # Errors /// Rejects unavailable choices or unsupported changes. fn validate_lifecycle( &self, actions: &[smith::lifecycle::LifecycleAction], model: &str, ) -> Result<()> { for action in actions { if !matches!( action, smith::lifecycle::LifecycleAction::Cancel | smith::lifecycle::LifecycleAction::EnsureContinuation | smith::lifecycle::LifecycleAction::EditContext(_) | smith::lifecycle::LifecycleAction::SetPrompt(_) ) && !matches!(action, smith::lifecycle::LifecycleAction::SetModel(selected) if selected == model) { return Err(tool_error( smith::error::ToolCode::Validation, "runtime lifecycle choice unavailable", )); } } Ok(()) } /// Publish previously validated runtime choices, without fallible I/O. fn commit_lifecycle(&mut self, _actions: &[smith::lifecycle::LifecycleAction]) {} /// Dispatch `name` and validated `input` through its single-operation grant. /// /// # Errors /// /// Returns the extension or granted-effect failure. fn invoke( &mut self, name: &str, input: &ToolArguments, effects: &mut ToolEffectContext<'_>, ) -> Result; } /// Durable origin of one host invocation, without model-message fabrication. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum InvocationCause { /// Real provider-issued model tool call. ModelTool(ToolCallId), /// Host-issued lifecycle invocation intent. Lifecycle(smith::id::EntryId), } /// One dispatcher call's non-escalating primitive-effect grant. /// /// Host imports validate capability grants before selecting primitives. /// Hosts may compose synchronous children through exclusive reborrows, never /// another outer call or concurrent mutable contexts. pub struct ToolEffectContext<'a> { session: &'a mut ToolSession, operation: &'a str, scope: Option<&'a mut EffectScope<'a>>, workspace: Option, workspace_only: bool, next_index: u16, active: bool, mutation_state: MutationState, } #[derive(Clone, Copy)] struct EffectIdentity { id: smith::id::EntryId, index: u16, causal: Option, } struct ChildInvocation { identity: EffectIdentity, operation: String, } /// Terminal host boundary shared by an outer invocation and all its children. /// These failures are never model-recoverable tool outcomes. #[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)] pub enum InvocationStop { /// A host import observed cancellation before parent resumption. Cancelled, /// The root absolute deadline elapsed. Deadline, /// Cumulative execution fuel was exhausted. Fuel, /// Participating linear memory exceeded its ceiling. Memory, /// Participating table elements exceeded their ceiling. Table, /// Cumulative host allocations exceeded their ceiling. HostAllocation, /// A canonical ABI conversion exceeded its allowance. Conversion, /// Cumulative diagnostic entries or bytes exceeded their ceiling. Log, /// Cumulative intermediate or terminal output exceeded its ceiling. Output, /// A sandbox authority boundary was violated. Sandbox, } /// Actual cumulative allocation observation at a bounded host boundary. /// This is requested allocation traffic, not live memory or RSS. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct InvocationAllocationReport { /// Soft production threshold in requested bytes. pub threshold_bytes: u64, /// Actual cumulative bytes at the latest boundary, including bounded cleanup. pub actual_bytes: u64, /// Requested bytes spent on outer terminal recording after guest settlement. pub cleanup_bytes: u64, /// Actual requested bytes above the threshold, never clamped into compliance. pub excess_bytes: u64, /// Successful allocations and reallocations observed. pub allocations: u64, /// Actual bytes at the first observed crossing, before terminal cleanup. pub stopped_bytes: Option, } /// Host-owned allocation observer retained through bounded terminal recording. /// Core owns only this synchronous interface, never an allocator dependency. pub trait InvocationAllocationObserver { /// Snapshot actual cumulative requested bytes across the owned operation. /// /// # Errors /// Returns an observation failure rather than reporting untrustworthy counters. fn report(&self) -> Result; } struct EffectScope<'a> { cause: Option, lifecycle_root: Option, redact: &'a dyn Fn(&str) -> String, component: Option, pending: Option, children: Vec, stop: Option, allocation: Option, allocation_observer: Option>, } impl<'a> EffectScope<'a> { fn new(call_id: ToolCallId, redact: &'a dyn Fn(&str) -> String) -> Self { Self { cause: Some(InvocationCause::ModelTool(call_id)), lifecycle_root: None, redact, component: None, pending: None, children: Vec::new(), stop: None, allocation: None, allocation_observer: None, } } } struct WorkspaceScope<'context, 'session> { context: &'context mut ToolEffectContext<'session>, previous: Option, workspace_only: bool, } impl Drop for WorkspaceScope<'_, '_> { fn drop(&mut self) { self.context.workspace = self.previous.take(); self.context.workspace_only = self.workspace_only; } } impl<'a> ToolEffectContext<'a> { /// Restrict primitive effects to `operation` for one native host call. /// /// This is for hosts that invoke a component directly rather than through /// [`ToolSession::invoke`]. The caller still owns the outer durable record. #[must_use] pub const fn for_operation(session: &'a mut ToolSession, operation: &'a str) -> Self { Self { session, operation, scope: None, workspace: None, workspace_only: false, next_index: 0, active: false, mutation_state: MutationState::NotApplied, } } /// Whether this invocation requires one atomic completion boundary. #[must_use] pub const fn requires_atomic_completion(&self) -> bool { self.session.completion.is_some() } /// Confine guest filesystem effects to a held workspace descriptor. pub fn set_workspace_root(&mut self, workspace: WorkspaceRoot) { self.workspace = Some(workspace); } /// Hold this invocation's workspace descriptor before entering a granted guest. /// /// # Errors /// Returns the workspace open failure before any guest effect dispatch. pub fn confine_workspace(&mut self) -> Result<()> { if self.workspace.is_none() { self.workspace = Some(WorkspaceRoot::open(self.working_dir())?); } Ok(()) } /// Run synchronously under a descendant of the currently held descriptor. /// Primitive authority is filesystem-only; ambient process authority cannot follow. /// Parent authority restores on return, error, or unwinding. /// /// # Errors /// Rejects an absent root or any path that escapes the held directory. pub fn with_workspace_subdirectory( &mut self, path: &str, run: impl FnOnce(&mut Self) -> Result, ) -> Result { let workspace = self .workspace .as_ref() .ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "workspace delegation requires a held root", ) })? .narrow(path)?; let previous = self.workspace.replace(workspace); let workspace_only = std::mem::replace(&mut self.workspace_only, true); let scope = WorkspaceScope { context: self, previous, workspace_only, }; run(scope.context) } /// Cancellation handle inherited from this outer durable effect. #[must_use] pub fn cancel_handle(&self) -> CancelHandle { self.session.cancel_handle() } /// Latch the first terminal host failure for this entire invocation subtree. /// Cancels subsequent effects even if a guest catches an import error. pub fn stop(&mut self, reason: InvocationStop) { if let Some(scope) = &mut self.scope { scope.stop.get_or_insert(reason); } if !self.is_lifecycle() { self.session.cancel.cancel(); } } /// First terminal host failure, independent of guest return values. #[must_use] pub fn stop_reason(&self) -> Option { self.scope.as_ref().and_then(|scope| scope.stop) } /// Retain a host observer through outer completion recording. /// Unscoped native callers retain the returned observer themselves. pub fn hold_allocation_observer( &mut self, observer: Box, ) -> Option> { if let Some(scope) = &mut self.scope { scope.allocation_observer = Some(observer); None } else { Some(observer) } } /// Record actual cumulative allocation traffic without reserving or rejecting malloc. pub fn report_allocation(&mut self, threshold_bytes: u64, actual_bytes: u64, allocations: u64) { if let Some(scope) = &mut self.scope { let stopped_bytes = scope .allocation .and_then(|report| report.stopped_bytes) .or_else(|| (actual_bytes > threshold_bytes).then_some(actual_bytes)); scope.allocation = Some(InvocationAllocationReport { threshold_bytes, actual_bytes, cleanup_bytes: 0, excess_bytes: actual_bytes.saturating_sub(threshold_bytes), allocations, stopped_bytes, }); } } /// Latest actual allocation observation for this root invocation. #[must_use] pub fn allocation_report(&self) -> Option { self.scope.as_ref().and_then(|scope| scope.allocation) } /// Immutable workspace directory associated with this call. #[must_use] pub fn working_dir(&self) -> &Path { self.session.working_dir() } /// Durable parent tool-call identity, when this context came from a tool dispatch. #[must_use] pub fn call_id(&self) -> Option { match self.cause()? { InvocationCause::ModelTool(call_id) => Some(call_id), InvocationCause::Lifecycle(_) => None, } } /// Pin actual component source and generation before guest entry. pub fn set_component_provenance(&mut self, component: ToolComponentProvenance) { if let Some(scope) = &mut self.scope { scope.component = Some(component); } } /// Current host-issued child invocation, or the outer tool boundary. #[must_use] pub fn invocation_id(&self) -> Option { self.scope .as_ref()? .children .last() .map(|child| child.identity.id) } /// Run a host-selected child synchronously with an exclusive reborrow. /// /// The host validates authority before entry. Guests supply neither caller IDs /// nor completion claims. The closure may recursively reborrow this context; /// it must not retain it in another store while the parent is suspended. /// Invocation records are nonmutating; primitive records own mutation evidence. /// /// # Errors /// Bounds and cancellation reject before intent. Persistence uncertainty is /// terminal even if the caller catches the returned error. pub fn with_child( &mut self, operation: &str, input: &str, component: Option, run: impl FnOnce(&mut Self) -> Result, ) -> Result { let previous_component = self .scope .as_mut() .and_then(|scope| std::mem::replace(&mut scope.component, component)); let result = self.run_child(operation, input, run); if let Some(scope) = &mut self.scope { scope.component = previous_component; } result } fn run_child( &mut self, operation: &str, input: &str, run: impl FnOnce(&mut Self) -> Result, ) -> Result { self.begin_nested_record(operation, input, true, true)?; let scope = self.scope.as_mut().ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "child requires admitted outer call", ) })?; let identity = scope.pending.take().ok_or_else(|| { tool_error(smith::error::ToolCode::Validation, "child requires intent") })?; scope.children.push(ChildInvocation { identity, operation: operation.to_owned(), }); self.active = false; let result = run(self); // An incomplete primitive must remain unknown, never be completed as a child. if self.active || self.session.recording_failed { return self.settle_invocation(result); } let scope = self.scope.as_mut().ok_or_else(|| { tool_error(smith::error::ToolCode::Validation, "child requires scope") })?; scope.children.pop(); scope.pending = Some(identity); self.active = true; let result = self.check_stop(result); let output = match &result { Ok(output) => output.as_str(), Err(error) => &error.to_string(), }; self.finish_nested_record(result.is_ok(), MutationState::NotApplied, output, true)?; result } /// Admit one bounded primitive effect under the current invocation before dispatch. /// /// # Errors /// Rejects unresolved effects, exhausted bounds, cancellation, or persistence failure. pub fn begin_nested(&mut self, operation: &str, input: &str) -> Result<()> { self.begin_nested_record(operation, input, true, false) } /// Record canonical evidence already redacted by its host mechanism. /// Does not text-redact wire schema, numbers, or binary hex a second time. /// /// # Errors /// Same admission and durability failures as [`Self::begin_nested`]. pub fn begin_nested_redacted(&mut self, operation: &str, input: &str) -> Result<()> { self.begin_nested_record(operation, input, false, false) } #[expect( clippy::too_many_lines, reason = "one admission boundary selects typed model or lifecycle ownership before persistence" )] fn begin_nested_record( &mut self, operation: &str, input: &str, redact: bool, invocation: bool, ) -> Result<()> { use crate::metadata::{ NESTED_EFFECT_BYTES_MAX, NESTED_EFFECTS_MAX, NESTED_PAYLOAD_BYTES_MAX, NestedEffectIntent, NestedPayload, NestedPayloadRef, }; if self.is_lifecycle() { if invocation { return Err(tool_error( smith::error::ToolCode::Validation, "lifecycle composition unavailable", )); } return self.begin_lifecycle_effect(operation, input, redact); } self.session.ensure_recording()?; if self.next_index >= NESTED_EFFECTS_MAX { self.stop(InvocationStop::HostAllocation); return Err(tool_error( smith::error::ToolCode::Validation, "nested effect count budget exhausted", )); } if operation.is_empty() || operation.len() > 128 || self.active || input.len() > NESTED_PAYLOAD_BYTES_MAX { return Err(tool_error( smith::error::ToolCode::Validation, "nested effect count, depth, or input byte bound exceeded", )); } if self.session.cancel.is_cancelled() { return Err(SmithError::Cancelled); } if let Some(scope) = &mut self.scope && invocation && scope.children.capacity() == 0 { scope .children .try_reserve_exact(usize::from(crate::metadata::NESTED_EFFECTS_MAX)) .map_err(|_| { tool_error( smith::error::ToolCode::Validation, "child stack allocation failed", ) })?; } let scope = self.scope.as_ref().ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "nested effect requires an outer call", ) })?; let root = self.submission_id()?; let input = if redact { (scope.redact)(input) } else { input.to_owned() }; if input.len() > NESTED_PAYLOAD_BYTES_MAX { return Err(tool_error( smith::error::ToolCode::Validation, "redacted nested input exceeds byte bound", )); } let effect_id = smith::id::EntryId::new(); let mut identity = EffectIdentity { id: effect_id, index: self.next_index, causal: (invocation || !scope.children.is_empty()).then_some( crate::metadata::NestedCausality { effect_id, parent: scope.children.last().map(|child| child.identity.id), invocation, }, ), }; let detail = crate::metadata::encode_nested( NestedEffectIntent { submission_id: root, call_id: match scope.cause { Some(InvocationCause::ModelTool(call_id)) => call_id, Some(InvocationCause::Lifecycle(_)) | None => { return Err(tool_error( smith::error::ToolCode::Validation, "model-only primitive unavailable to lifecycle", )); } }, index: self.next_index, operation, component: scope.component.as_ref(), input: if input.len() <= NESTED_EFFECT_BYTES_MAX { NestedPayload::Inline(&input) } else { NestedPayload::Chunks(NestedPayloadRef { payload_bytes: u32::try_from(input.len()).map_err(|_| { tool_error( smith::error::ToolCode::Validation, "nested payload length overflow", ) })?, }) }, }, identity.causal.as_ref(), )?; self.persist_intent(&input, &detail, &mut identity)?; if let Some(scope) = &mut self.scope { scope.pending = Some(identity); } self.next_index += 1; self.active = true; Ok(()) } fn persist_intent( &mut self, input: &str, detail: &StructuredData, identity: &mut EffectIdentity, ) -> Result<()> { use crate::metadata::{NESTED_EFFECT_BYTES_MAX, NESTED_INTENT_KIND}; if identity.causal.is_none() && input.len() <= NESTED_EFFECT_BYTES_MAX { identity.id = self .session .record(EntryContentRef::Meta { kind: NESTED_INTENT_KIND, detail, })? .id; } else { let mut entry = crate::session::EntryFrame::from_content( self.session.session.selected_id().as_ref(), &EntryContentRef::Meta { kind: NESTED_INTENT_KIND, detail, }, )?; entry.id = identity.id; let persisted = (|| { if input.len() > NESTED_EFFECT_BYTES_MAX { self.persist_payload(input, crate::frame::NestedPayloadPhase::Input, identity)?; } let boundary = self.session.completion.as_mut().ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "nested intent requires root", ) })?; self.session .session .append_effect_with(entry, false, &mut boundary.persist) })(); if let Err(error) = persisted { self.session.recording_failed = true; self.session.cancel.cancel(); return Err(error); } } Ok(()) } /// Atomically persist nested completion and root progress before guest resumption. /// /// # Errors /// Any uncertainty poisons this session, including when a guest catches the error. pub fn finish_nested(&mut self, ok: bool, mutation: MutationState, output: &str) -> Result<()> { self.finish_nested_record(ok, mutation, output, true) } /// Complete with canonical evidence already redacted by its host mechanism. /// Binary hex and fixed wire schema remain exact, without text substitution. /// /// # Errors /// Same poisoning and acknowledgement contract as [`Self::finish_nested`]. pub fn finish_nested_redacted( &mut self, ok: bool, mutation: MutationState, output: &str, ) -> Result<()> { self.finish_nested_record(ok, mutation, output, false) } #[expect( clippy::too_many_lines, reason = "one completion boundary preserves model and lifecycle poisoning semantics" )] fn finish_nested_record( &mut self, ok: bool, mutation: MutationState, output: &str, redact: bool, ) -> Result<()> { use crate::metadata::{ NESTED_COMPLETION_KIND, NESTED_EFFECT_BYTES_MAX, NESTED_PAYLOAD_BYTES_MAX, NestedEffectCompletion, NestedPayload, NestedPayloadRef, }; if self.is_lifecycle() { return self.finish_lifecycle_effect(ok, mutation, output, redact); } self.mutation_state = aggregate_mutation(self.mutation_state, mutation); let completion = (|| { self.session.ensure_recording()?; if !self.active || output.len() > NESTED_PAYLOAD_BYTES_MAX { return Err(tool_error( smith::error::ToolCode::Validation, "nested completion missing intent or exceeds byte bound", )); } let scope = self.scope.as_ref().ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "nested completion requires outer call", ) })?; let identity = scope.pending.ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "completion requires pending identity", ) })?; let output = if redact { (scope.redact)(output) } else { output.to_owned() }; if output.len() > NESTED_PAYLOAD_BYTES_MAX { return Err(tool_error( smith::error::ToolCode::Validation, "redacted nested output exceeds byte bound", )); } let root = self.submission_id()?; let detail = crate::metadata::encode_nested( NestedEffectCompletion { submission_id: root, call_id: match scope.cause { Some(InvocationCause::ModelTool(call_id)) => call_id, Some(InvocationCause::Lifecycle(_)) | None => { return Err(tool_error( smith::error::ToolCode::Validation, "model-only primitive unavailable to lifecycle", )); } }, index: identity.index, ok, mutation_state: mutation, output: if output.len() <= NESTED_EFFECT_BYTES_MAX { NestedPayload::Inline(&output) } else { NestedPayload::Chunks(NestedPayloadRef { payload_bytes: u32::try_from(output.len()).map_err(|_| { tool_error( smith::error::ToolCode::Validation, "nested payload length overflow", ) })?, }) }, }, identity.causal.as_ref(), )?; if output.len() > NESTED_EFFECT_BYTES_MAX { self.persist_payload(&output, crate::frame::NestedPayloadPhase::Output, &identity)?; } let boundary = self.session.completion.as_mut().ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "nested completion requires root", ) })?; let entry = crate::session::EntryFrame::from_content( self.session.session.selected_id().as_ref(), &EntryContentRef::Meta { kind: NESTED_COMPLETION_KIND, detail: &detail, }, )?; self.session .session .append_nested_with(entry, &mut boundary.persist) })(); if let Err(error) = completion { self.session.recording_failed = true; self.session.cancel.cancel(); return Err(SmithError::RecordFailed { tool: self.operation.to_string(), mutation_state: self.mutation_state, message: error.to_string(), }); } self.active = false; if let Some(scope) = &mut self.scope { scope.pending = None; } Ok(()) } fn submission_id(&self) -> Result { self.session .completion .as_ref() .map(|boundary| boundary.submission_id) .ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "nested effect requires admitted work", ) }) } fn persist_payload( &mut self, value: &str, phase: crate::frame::NestedPayloadPhase, identity: &EffectIdentity, ) -> Result<()> { let call = self.call_id().ok_or_else(|| { tool_error(smith::error::ToolCode::Validation, "payload requires call") })?; let boundary = self.session.completion.as_mut().ok_or_else(|| { tool_error(smith::error::ToolCode::Validation, "payload requires root") })?; for (ordinal, bytes) in value .as_bytes() .chunks(crate::metadata::NESTED_CHUNK_BYTES_MAX) .enumerate() { let chunk = crate::frame::NestedPayloadChunk { submission_id: boundary.submission_id, call_id: call, effect_id: identity.id, index: identity.index, phase, ordinal: u16::try_from(ordinal).map_err(|_| { tool_error( smith::error::ToolCode::Validation, "payload chunk count overflow", ) })?, bytes: bytes.to_vec(), }; (boundary.persist)(crate::frame::Frame::NestedPayload { chunk: Box::new(chunk), })?; } Ok(()) } fn settle_invocation(&mut self, effect: Result) -> Result { if (self.active || self .scope .as_ref() .is_some_and(|scope| !scope.children.is_empty())) && !self.session.recording_failed { self.session.recording_failed = true; self.session.cancel.cancel(); self.mutation_state = aggregate_mutation(self.mutation_state, MutationState::Unknown); } if self.session.recording_failed { if matches!(&effect, Err(SmithError::RecordFailed { .. })) { return effect; } return Err(SmithError::RecordFailed { tool: self.operation.to_string(), mutation_state: self.mutation_state, message: "nested persistence uncertainty stopped invocation".into(), }); } self.check_stop(effect) } fn check_stop(&self, effect: Result) -> Result { if self.stop_reason() == Some(InvocationStop::Cancelled) { return Err(SmithError::Cancelled); } if let Some(reason) = self.stop_reason() { return Err(tool_error( smith::error::ToolCode::Validation, format!( "terminal host invocation stop: {reason:?}; allocation={:?}", self.allocation_report() ), )); } effect } /// Persist legacy redacted HTTP metadata through this call's session writer. /// Admitted imports use [`Self::begin_nested`] and [`Self::finish_nested`] /// with full bounded request and response evidence. /// /// # Errors /// /// Returns recording failure before the associated transport may execute. pub fn record_plugin_http( &mut self, record: &smith::http::PluginHttpEffectRecord, ) -> Result<()> { if self.requires_atomic_completion() || self.is_lifecycle() { return Err(tool_error( smith::error::ToolCode::Validation, "admitted HTTP requires full nested request and response evidence", )); } if let smith::http::PluginHttpEffectRecord::Outcome { outcome, .. } = record { let mutation = if *outcome == smith::http::PluginHttpEffectOutcome::Completed { MutationState::Applied } else { MutationState::Unknown }; self.mutation_state = aggregate_mutation(self.mutation_state, mutation); } self.record_plugin_metadata(PLUGIN_HTTP_KIND, record) } /// Persist one redacted plugin diagnostic through this call's session writer. /// /// # Errors /// /// Returns the session recording failure. pub fn record_plugin_log(&mut self, record: &smith::http::PluginLogRecord) -> Result<()> { if self.is_lifecycle() { return Err(tool_error( smith::error::ToolCode::Validation, "lifecycle log primitive unavailable", )); } if !self.requires_atomic_completion() { return self.record_plugin_metadata(PLUGIN_LOG_KIND, record); } let input = serde_json::to_string(record) .map_err(|error| tool_error(smith::error::ToolCode::Validation, error.to_string()))?; self.begin_nested("log", &input)?; self.finish_nested(true, MutationState::NotApplied, "recorded") } fn record_plugin_metadata( &mut self, kind: &'static str, record: &T, ) -> Result<()> { let detail = encode_metadata(record)?; self.session.record(EntryContentRef::Meta { kind, detail: &detail, })?; Ok(()) } /// Execute the granted primitive operation. /// /// # Errors /// /// Returns an authorization error before effects when `name` differs from /// the operation delegated by the outer call. pub fn invoke(&mut self, name: &str, input: &ToolArguments) -> Result { let operation = self .scope .as_ref() .and_then(|scope| scope.children.last()) .map_or(self.operation, |child| child.operation.as_str()); if name != operation { return Err(tool_error( smith::error::ToolCode::Validation, format!( "operation '{name}' exceeds delegated operation '{}'", self.operation ), )); } self.invoke_redacted(name, input, str::to_string) } /// Execute a grant-checked host primitive with scoped registered-secret redaction. /// /// # Errors /// Returns primitive or durability failure; no subsequent effect follows uncertainty. pub fn invoke_redacted( &mut self, name: &str, input: &ToolArguments, redact: impl Fn(&str) -> String, ) -> Result { self.session.ensure_recording()?; if self.is_lifecycle() { return Err(tool_error( smith::error::ToolCode::Validation, "model-only primitive unavailable to lifecycle", )); } if self.workspace_only && !matches!(name, "read" | "write" | "edit" | "ls" | "find" | "grep") { return Err(tool_error( smith::error::ToolCode::Validation, "non-filesystem primitive exceeds delegated workspace authority", )); } if self.requires_atomic_completion() { let text = serde_json::to_string(input).map_err(|error| { tool_error(smith::error::ToolCode::Validation, error.to_string()) })?; self.begin_nested(name, &redact(&text))?; } else if name != self.operation { return Err(tool_error( smith::error::ToolCode::Validation, "primitive exceeds delegated operation", )); } let effect = self .session .invoke_primitive_effect(name, input, self.workspace.as_ref()); let mutation = mutation_state(name, &effect); if self.requires_atomic_completion() { let output = match &effect { Ok(text) => redact(text), Err(error) => redact(&error.to_string()), }; self.finish_nested(effect.is_ok(), mutation, &output)?; } else { self.mutation_state = aggregate_mutation(self.mutation_state, mutation); } effect } } enum Persistence { None, Direct(SessionWriter), Worker(Box), } /// Bundles the registry, the live session, and durable persistence so a /// successful mutation cannot be reported while recording failed. pub struct ToolSession { registry: ToolRegistry, /// Live session state; entries are appended as they are recorded. pub session: Session, persistence: Persistence, completion: Option, /// All file effects resolve relative to this directory. working_dir: PathBuf, config: Config, cancel: CancelHandle, /// What `read` and `write` last observed per file, used to reject edits /// whose input describes an older version of the file. observed: HashMap, /// Completion persistence failed; no further host effects may begin. recording_failed: bool, dispatcher: Option>, dynamic_tool_names: Vec, advertised_tools: Arc<[ToolMetadata]>, request_policy: Option>, loadout_provenance: Option, #[cfg(test)] test_effect_control: TestEffectControl, } /// Cheap identity of a file version: size plus modification time. #[derive(Clone, Copy, PartialEq, Eq, Debug)] struct FileVersion { len: u64, modified_ms: i64, } impl FileVersion { #[cfg(target_os = "linux")] const fn from_workspace((len, modified_ms): (u64, i64)) -> Self { Self { len, modified_ms } } fn of(path: &Path) -> Option { let meta = fs::metadata(path).ok()?; let modified_ms = meta .modified() .ok()? .duration_since(std::time::UNIX_EPOCH) .ok()? .as_millis(); Some(Self { len: meta.len(), modified_ms: i64::try_from(modified_ms).unwrap_or(i64::MAX), }) } } impl ToolSession { /// A tool session with no published tools and no persistence. pub fn new(working_dir: impl Into) -> Self { Self { registry: { #[cfg(test)] { test_tool_registry() } #[cfg(not(test))] { ToolRegistry::new() } }, session: Session::new(), persistence: Persistence::None, completion: None, working_dir: working_dir.into(), config: Config::default_valid(), cancel: CancelHandle::new(), observed: HashMap::new(), recording_failed: false, dispatcher: None, dynamic_tool_names: Vec::new(), advertised_tools: Arc::from([]), request_policy: None, loadout_provenance: None, #[cfg(test)] test_effect_control: TestEffectControl::default(), } } /// Use `config` for effect timeouts and frame limits. #[must_use] pub fn with_config(mut self, config: Config) -> Self { self.config = config; self } pub(crate) fn ensure_recording(&self) -> Result<()> { if self.recording_failed { return Err(SmithError::Session { code: smith::error::SessionCode::SessionIncompleteContext, message: "recording persistence is uncertain; reopen before further effects".into(), }); } Ok(()) } pub(crate) const fn poison_recording(&mut self) { self.recording_failed = true; } pub(crate) const fn recording_failed(&self) -> bool { self.recording_failed } /// Every registered definition, including active hidden tools. #[must_use] pub fn registered_tools(&self) -> Arc<[ToolMetadata]> { self.registry.snapshot() } /// Definitions advertised by the current immutable provider round. #[must_use] pub fn advertised_tools(&self) -> Arc<[ToolMetadata]> { Arc::clone(&self.advertised_tools) } /// Immutable workspace directory for this session. #[must_use] pub fn working_dir(&self) -> &Path { &self.working_dir } /// A handle that aborts in-flight and subsequent effects of this session. #[must_use] pub fn cancel_handle(&self) -> CancelHandle { self.cancel.clone() } pub(crate) fn set_cancel_handle(&mut self, cancel: CancelHandle) { self.cancel = cancel; } #[cfg(test)] const fn cancel_at_checkpoint(&mut self, checkpoint: EffectCheckpoint) { self.test_effect_control.cancel_at = Some(checkpoint); } #[cfg(test)] const fn timeout_at_checkpoint(&mut self, checkpoint: EffectCheckpoint) { self.test_effect_control.timeout_at = Some(checkpoint); } /// Continue an existing session, appending every recorded entry to its /// durable writer. pub fn with_session( working_dir: impl Into, session: Session, writer: SessionWriter, ) -> Self { Self { session, persistence: Persistence::Direct(writer), ..Self::new(working_dir) } } /// Keep persistence on an external storage worker. #[must_use] pub fn with_persist( working_dir: impl Into, session: Session, persist: impl FnMut(&Entry, &[u8]) -> Result<()> + Send + 'static, ) -> Self { Self { session, persistence: Persistence::Worker(Box::new(persist)), ..Self::new(working_dir) } } /// Register or replace a tool definition. pub fn register(&mut self, meta: ToolMetadata) { self.registry.register(meta); } /// Bind admitted work to its session worker's atomic completion command. /// No result or conversation message is published before durable acknowledgement. #[must_use] pub fn with_completion_boundary( mut self, submission_id: smith::id::EntryId, persist: impl FnMut(crate::frame::Frame) -> Result<()> + Send + 'static, ) -> Self { self.completion = Some(CompletionBoundary { submission_id, persist: Box::new(persist), }); self } pub(crate) const fn has_completion_boundary(&self) -> bool { self.completion.is_some() } /// Route validated calls through `dispatcher` instead of native effects. pub fn set_dispatcher(&mut self, dispatcher: Box) { self.dispatcher = Some(dispatcher); } /// Pin extension definitions and handlers for one provider request and its /// complete tool-result batch. /// /// # Errors /// /// Returns before provider dispatch when extension publication fails. pub fn begin_provider_round(&mut self) -> Result<()> { let Some(mut dispatcher) = self.dispatcher.take() else { return Ok(()); }; let tools = dispatcher.begin_provider_round(); self.dispatcher = Some(dispatcher); let mut snapshot = tools?; snapshot .tools .sort_by(|left, right| left.name.cmp(&right.name)); snapshot .provenance .tools .sort_by(|left, right| left.definition.name.cmp(&right.definition.name)); if snapshot.tools.len() != snapshot.provenance.tools.len() || snapshot .tools .iter() .zip(&snapshot.provenance.tools) .any(|(tool, provenance)| tool != &provenance.definition) { return Err(tool_error( smith::error::ToolCode::Validation, "dispatcher tool definitions do not match provenance", )); } self.request_policy = Some(snapshot.policy.into_boxed_slice()); self.loadout_provenance = Some(snapshot.provenance); if !snapshot.tools.is_empty() || !self.advertised_tools.is_empty() { self.advertised_tools = Arc::from(snapshot.tools); } for name in self.dynamic_tool_names.drain(..) { self.registry.tools.remove(&name); } for tool in snapshot.registered_tools { self.dynamic_tool_names.push(tool.name.clone()); self.registry.register(tool); } Ok(()) } pub(crate) fn lifecycle( &mut self, event: &smith::lifecycle::LifecycleEvent, redact: &dyn Fn(&str) -> String, ) -> Result { self.ensure_recording()?; let Some(mut dispatcher) = self.dispatcher.take() else { return Ok(smith::lifecycle::LifecycleBatch::default()); }; if !dispatcher.has_lifecycle_handlers(event.boundary) { self.dispatcher = Some(dispatcher); return Ok(smith::lifecycle::LifecycleBatch::default()); } // Root cancellation stops provider work, not bounded terminal cleanup. // Keep the original handle bound to durable control throughout notification. let root_cancel = if event.boundary == smith::lifecycle::Boundary::Settled { Some(std::mem::replace(&mut self.cancel, CancelHandle::new())) } else { None }; if self.completion.is_none() && matches!(self.persistence, Persistence::None) { let result = dispatcher.lifecycle(event, &self.cancel); self.dispatcher = Some(dispatcher); if let Some(root_cancel) = root_cancel { self.cancel = root_cancel; } return result; } let mut scope = EffectScope { cause: None, lifecycle_root: Some(event.root_entry_id), redact, component: None, pending: None, children: Vec::new(), stop: None, allocation: None, allocation_observer: None, }; let mut effects = ToolEffectContext { session: self, operation: "lifecycle", scope: Some(&mut scope), workspace: None, workspace_only: false, next_index: 0, active: false, mutation_state: MutationState::NotApplied, }; let result = dispatcher.lifecycle_effects(event, &mut effects); let recording = effects.session.ensure_recording(); effects.session.dispatcher = Some(dispatcher); if let Some(root_cancel) = root_cancel { effects.session.cancel = root_cancel; } let batch = result?; recording?; Ok(batch) } pub(crate) fn validate_lifecycle( &self, actions: &[smith::lifecycle::LifecycleAction], model: &str, ) -> Result<()> { if let Some(dispatcher) = &self.dispatcher { dispatcher.validate_lifecycle(actions, model)?; } Ok(()) } pub(crate) fn commit_lifecycle(&mut self, actions: &[smith::lifecycle::LifecycleAction]) { if let Some(dispatcher) = &mut self.dispatcher { dispatcher.commit_lifecycle(actions); } } /// Persist the exact pinned dispatcher snapshot before an admitted provider request. /// /// # Errors /// /// Returns a recording error before provider dispatch. pub(crate) fn record_admitted_loadout_provenance(&mut self) -> Result<()> { let provenance = self.loadout_provenance.as_ref().ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "admitted provider request requires a dispatcher loadout snapshot", ) })?; let advertised = &self.advertised_tools; if advertised.len() != provenance.tools.len() || advertised .iter() .zip(&provenance.tools) .any(|(tool, provenance)| tool != &provenance.definition) { return Err(tool_error( smith::error::ToolCode::Validation, "advertised tools do not match dispatcher provenance", )); } let detail = crate::metadata::encode(provenance)?; self.record(EntryContentRef::Meta { kind: crate::session::TOOL_LOADOUT_PROVENANCE_KIND, detail: &detail, }) .map(|_| ()) } /// Release handlers pinned for the completed provider request and tool batch. pub fn end_provider_round(&mut self) { self.request_policy = None; if !self.advertised_tools.is_empty() { self.advertised_tools = Arc::from([]); } if let Some(dispatcher) = &mut self.dispatcher { dispatcher.end_provider_round(); } } /// Validate arguments against the registered schema (required fields and /// declared property types) before any effect can run. /// /// # Errors /// /// Returns [`SmithError::Tool`] for unknown tools, non-object input, /// missing required fields, or mismatched field types. pub fn validate<'a, Input: StructuredValue<'a>>(&self, name: &str, input: Input) -> Result<()> { let meta = self .advertised_tools .iter() .find(|tool| tool.name == name) .or_else(|| self.registry.get(name)) .ok_or_else(|| { tool_error( smith::error::ToolCode::ToolNotRegistered, format!("tool '{name}' not registered"), ) })?; meta.input_schema.validate(input).map_err(|error| { let (code, message) = match error { SchemaError::InputNotObject => ( smith::error::ToolCode::InvalidInput, format!("input for tool '{name}' must be a JSON object"), ), SchemaError::MissingField(field) => ( smith::error::ToolCode::Validation, format!("missing required field '{field}' for tool '{name}'"), ), SchemaError::FieldType { field, expected } => ( smith::error::ToolCode::Validation, format!("field '{field}' for tool '{name}' must be of type {expected}"), ), SchemaError::Access(error) => { (smith::error::ToolCode::Validation, error.to_string()) } }; tool_error(code, message) }) } /// Validate, execute, and durably record one trusted host tool call. /// Hidden tools remain active here; model calls use the request-pinned path. /// /// Recording order is call entry, effect, result entry, so a recorded /// call always precedes the effect it describes. A cancelled session /// refuses to start an effect. If the effect runs but its result cannot /// be recorded, the error states whether host state was already mutated, /// instead of presenting an unrecorded success. /// /// # Errors /// /// Returns [`SmithError::Cancelled`] when the session was cancelled, /// [`SmithError::RecordFailed`] when a completed effect could not be /// recorded, or the effect's own error. pub fn invoke(&mut self, name: &str, input: &ToolArguments) -> Result { self.invoke_recorded( ToolCallId::new(), name, input, input, str::to_string, EffectFailure::ReturnError, ) } /// Execute a model call under its originating request pin while recording /// only its redacted representation. /// /// `recorded_input` crosses persistence and provider boundaries; /// `effect_input` exists only for the duration of the authorized local /// effect. `redact_output` is applied before either the outcome or its /// durable result can escape that boundary. Executed tool failures become /// recorded outcomes so the model can observe and recover from them. pub(crate) fn invoke_local( &mut self, call_id: ToolCallId, name: &str, recorded_input: &ToolArguments, effect_input: &ToolArguments, redact_output: impl Fn(&str) -> String, ) -> Result { self.authorize_model_call(name)?; self.invoke_recorded( call_id, name, recorded_input, effect_input, redact_output, EffectFailure::ReturnOutcome, ) } fn authorize_model_call(&self, name: &str) -> Result<()> { if self.dispatcher.is_none() { return Ok(()); } if self.request_policy.is_none() { return Err(tool_error( smith::error::ToolCode::ToolNotAdvertised, format!("tool '{name}' has no originating request pin; start a new provider round"), )); } self.authorize_active_call(name)?; if !self.advertised_tools.iter().any(|tool| tool.name == name) { return Err(tool_error( smith::error::ToolCode::ToolNotAdvertised, format!( "tool '{name}' was not advertised by the originating request; request its qualified definition in a later round" ), )); } Ok(()) } fn authorize_active_call(&self, name: &str) -> Result<()> { if self.dispatcher.is_none() { return Ok(()); } let Some(policy) = &self.request_policy else { return Ok(()); }; let state = policy .iter() .find(|(identity, _)| identity == name) .map(|(_, state)| *state); match state { Some(ToolPolicyState::Advertised | ToolPolicyState::Hidden) => Ok(()), Some(ToolPolicyState::Disabled) => Err(tool_error( smith::error::ToolCode::ToolDisabled, format!( "tool '{name}' is disabled by host policy; enable its qualified identity before retrying" ), )), None => Err(tool_error( smith::error::ToolCode::ToolNotRegistered, format!( "tool '{name}' has no pinned registered identity; select an exact qualified tool advertised by this request" ), )), } } fn validate_admitted_call(&self, call_id: ToolCallId) -> Result<()> { use crate::session::EntryKind; let Some(boundary) = &self.completion else { return Ok(()); }; let entries = self.session.active_branch().entries(); if call_id.as_u128() == 0 || boundary.submission_id.as_u128() == 0 || !entries.iter().any(|entry| { entry.id == boundary.submission_id && matches!( entry.kind, EntryKind::Message { role: smith::message::Role::User, .. } ) }) || entries.iter().any(|entry| { matches!(entry.kind, EntryKind::ToolCall { call_id: prior } if prior == call_id) }) { return Err(tool_error( smith::error::ToolCode::Validation, "admitted tool call requires its root and a fresh nonzero effect identity", )); } Ok(()) } #[expect( clippy::too_many_lines, reason = "one outer completion retains the allocation observer through dispatch, durable recording and terminal reporting" )] fn invoke_recorded( &mut self, call_id: ToolCallId, name: &str, recorded_input: &ToolArguments, effect_input: &ToolArguments, redact_output: impl Fn(&str) -> String, failure: EffectFailure, ) -> Result { self.authorize_active_call(name)?; self.validate_admitted_call(call_id)?; if self.completion.is_some() && self.dispatcher.is_none() { return Err(tool_error( smith::error::ToolCode::Validation, "admitted tool call requires a component dispatcher", )); } self.validate(name, recorded_input.view())?; if self.recording_failed { return Err(SmithError::RecordFailed { tool: name.to_string(), mutation_state: MutationState::Unknown, message: "a prior completion recording failure stopped further effects".to_string(), }); } if self.cancel.is_cancelled() && failure == EffectFailure::ReturnError { return Err(SmithError::Cancelled); } self.record(EntryContentRef::ToolCall { name, input: recorded_input, call_id, })?; let mut primitive_evidence = None; let mut allocation_observer = None; let mut allocation_report = None; let mut invocation_stop = None; let effect = if self.cancel.is_cancelled() { Err(SmithError::Cancelled) } else if let Some(mut dispatcher) = self.dispatcher.take() { let mut scope = EffectScope::new(call_id, &redact_output); let mut effects = ToolEffectContext { session: self, operation: name, scope: Some(&mut scope), workspace: None, workspace_only: false, next_index: 0, active: false, mutation_state: MutationState::NotApplied, }; let effect = dispatcher.invoke(name, effect_input, &mut effects); let effect = effects.settle_invocation(effect); primitive_evidence = Some((effects.mutation_state, effects.stop_reason().is_some())); effects.session.dispatcher = Some(dispatcher); allocation_report = effects.allocation_report(); invocation_stop = effects.stop_reason(); if let Some(scope) = &mut effects.scope { allocation_observer = scope.allocation_observer.take(); } effect } else { self.invoke_primitive_effect(name, effect_input, None) }; let mut terminal = primitive_evidence.is_some_and(|(_, stopped)| stopped) || matches!(&effect, Err(SmithError::RecordFailed { .. })); let mut effect = effect; let mut ok = effect.is_ok(); let mutation_state = primitive_evidence .map_or_else(|| mutation_state(name, &effect), |(mutation, _)| mutation); let mut output = match &effect { Ok(text) => redact_output(text), Err(error) => redact_output(&error.to_string()), }; let detail = mutation_detail(call_id, mutation_state)?; // A known exhausted observation must not publish a successful completion. // Later recording allocations may still cross the soft threshold. if let Some(observer) = &allocation_observer && !self.recording_failed { let total = observer.report()?; if total.actual_bytes > total.threshold_bytes && invocation_stop.is_none() { invocation_stop = Some(InvocationStop::HostAllocation); self.cancel.cancel(); terminal = true; ok = false; let error = tool_error( smith::error::ToolCode::Validation, format!("terminal host invocation stop: HostAllocation; allocation={total:?}"), ); output = redact_output(&error.to_string()); effect = Err(error); } } let mut completion = || -> Result<()> { self.ensure_recording()?; if self.completion.is_some() { return self.record_completion(call_id, ok, &output, &detail); } self.record(EntryContentRef::ToolResult { ok, output: &output, call_id, })?; self.record(EntryContentRef::Meta { kind: TOOL_MUTATION_KIND, detail: &detail, })?; Ok(()) }; if let Err(error) = completion() { self.recording_failed = true; self.cancel.cancel(); let primary = match &effect { Err(primary @ SmithError::RecordFailed { .. }) => primary, _ => &error, }; return Err(SmithError::RecordFailed { tool: name.to_string(), mutation_state, message: format!( "{primary}; allocation={:?}", allocation_observer .as_ref() .and_then(|observer| observer.report().ok()) .or(allocation_report) ), }); } let mut outcome = ToolOutcome { call_id, name: name.to_string(), ok, output, timestamp_ms: now_ms(), mutation_state, allocation: None, }; if let Some(observer) = &allocation_observer { let mut total = observer.report()?; total.stopped_bytes = allocation_report .and_then(|report| report.stopped_bytes) .or_else(|| { (total.actual_bytes > total.threshold_bytes).then_some(total.actual_bytes) }); total.cleanup_bytes = total .actual_bytes .saturating_sub(allocation_report.map_or(0, |report| report.actual_bytes)); allocation_report = Some(total); if total.actual_bytes > total.threshold_bytes && invocation_stop.is_none_or(|reason| reason == InvocationStop::HostAllocation) { self.cancel.cancel(); let stop = crate::metadata::InvocationTerminalStop { submission_id: self .completion .as_ref() .map(|boundary| boundary.submission_id), call_id, reason: InvocationStop::HostAllocation, allocation: total, }; // No exact self-measuring fixpoint: the report precedes its own // bounded encoding and acknowledgement, without erasing success. let recorded = crate::metadata::encode(&stop).and_then(|detail| { self.record(EntryContentRef::Meta { kind: crate::metadata::INVOCATION_TERMINAL_STOP_KIND, detail: &detail, }) .map(|_| ()) }); if let Err(error) = recorded { self.recording_failed = true; return Err(SmithError::RecordFailed { tool: name.to_string(), mutation_state, message: format!("{error}; allocation={total:?}"), }); } return Err(tool_error( smith::error::ToolCode::Validation, format!("terminal host invocation stop: HostAllocation; allocation={total:?}"), )); } } outcome.allocation = allocation_report; match effect { Ok(_) => Ok(outcome), Err(_) if failure == EffectFailure::ReturnOutcome && !terminal => Ok(outcome), Err(error) => Err(error), } } fn record_completion( &mut self, call_id: ToolCallId, ok: bool, output: &str, detail: &StructuredData, ) -> Result<()> { use crate::session::EntryFrame; let result = EntryFrame::from_content( self.session.selected_id().as_ref(), &EntryContentRef::ToolResult { call_id, ok, output, }, )?; let evidence = EntryFrame::from_content( Some(&result.id), &EntryContentRef::Meta { kind: TOOL_MUTATION_KIND, detail, }, )?; let mut message = smith::message::Message::new(smith::message::Role::Tool); message.add_block(smith::message::ContentBlock::tool_result( call_id, ok, output, )); let conversation = EntryFrame::from_content(Some(&evidence.id), &EntryContentRef::Message(&message))?; let boundary = self.completion.as_mut().ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "missing atomic completion boundary", ) })?; let frame = crate::frame::Frame::Commit { checkpoint: crate::frame::ToolCompletionCheckpoint { submission_id: boundary.submission_id, call_id, }, entries: Box::new([result, evidence, conversation]), }; self.session .append_commit_with(frame, &mut boundary.persist) } /// Execute a primitive effect while an outer dispatcher call owns its /// durable call/result lifecycle. /// /// The caller must hold a [`ToolEffectContext`], which restricts it to the /// outer call's operation and prevents recursive dispatch. fn invoke_primitive_effect( &mut self, name: &str, input: &ToolArguments, workspace: Option<&WorkspaceRoot>, ) -> std::result::Result { execute_effect( name, input, &self.working_dir, &self.config, &self.cancel, &mut self.observed, workspace, #[cfg(test)] self.test_effect_control, ) } /// Append an atomic model-visible edit through this session's durable writer. /// Validation happens before persistence; failure never publishes projection. /// /// # Errors /// Rejects read-only/unpersisted sessions, invalid batches or uncertain recording. pub fn edit_context( &mut self, edits: &[crate::context::ContextEdit], ) -> Result { self.ensure_recording()?; if matches!(self.persistence, Persistence::None) { return Err(crate::context::invalid( "context edits require writable durable session authority", )); } let persistence = &mut self.persistence; let frame_bytes_max = self.config.frame_bytes_max; let mut persistence_started = false; let result = self.session.edit_context_with(edits, |entry, content| { crate::frame::validate_entry_size(content, frame_bytes_max)?; persistence_started = true; match persistence { Persistence::None => Err(crate::context::invalid( "context edits require writable durable session authority", )), Persistence::Direct(writer) => writer.append_entry(entry, content), Persistence::Worker(persist) => persist(entry, content), } }); if persistence_started && result.is_err() { self.recording_failed = true; } result } /// Append `content` after the selected entry and durably record it /// first; a failed write leaves the session unchanged. pub(crate) fn record<'a>(&mut self, content: impl Into>) -> Result { self.ensure_recording()?; let frame_bytes_max = self.config.frame_bytes_max; let persistence = &mut self.persistence; let mut persistence_started = false; let entry = self .session .append_with(content, |entry, bytes| { crate::frame::validate_entry_size(bytes, frame_bytes_max)?; persistence_started = true; match persistence { Persistence::None => Ok(()), Persistence::Direct(writer) => writer.append_entry(entry, bytes), Persistence::Worker(persist) => persist(entry, bytes), } }) .copied(); let entry = match entry { Ok(entry) => entry, Err(error) => { if persistence_started { self.recording_failed = true; } return Err(error); } }; if entry.is_compaction() { self.session.retain_compacted_context()?; } Ok(entry) } } #[derive(Clone, Copy, PartialEq, Eq)] enum EffectFailure { ReturnError, ReturnOutcome, } /// A recorded tool outcome returned to the caller. #[derive(Clone, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)] pub struct ToolOutcome { /// Actual composition allocation traffic, including terminal recording. #[serde(default, skip_serializing_if = "Option::is_none")] pub allocation: Option, /// Tool call ID. pub call_id: ToolCallId, /// Tool name. pub name: String, /// Whether the effect succeeded. pub ok: bool, /// Recorded output or error message. pub output: String, /// Timestamp of outcome. pub timestamp_ms: i64, /// Durable best-known host mutation outcome. pub mutation_state: MutationState, } const fn aggregate_mutation(prior: MutationState, next: MutationState) -> MutationState { match (prior, next) { (MutationState::Applied, _) | (_, MutationState::Applied) => MutationState::Applied, (MutationState::Unknown, _) | (_, MutationState::Unknown) => MutationState::Unknown, _ => MutationState::NotApplied, } } fn mutation_detail(call_id: ToolCallId, mutation_state: MutationState) -> Result { encode_metadata(&ToolMutationMetadata::new(call_id, mutation_state)) } fn tool_error(code: smith::error::ToolCode, message: impl Into) -> SmithError { SmithError::Tool { code, message: message.into(), } } fn io_tool_error(code: smith::error::ToolCode) -> impl Fn(std::io::Error) -> SmithError { move |e| tool_error(code, e.to_string()) } fn input_string<'a>(input: &'a ToolArguments, key: &str) -> Result> { let Some(value) = input.view().field(key).map_err(structured_tool_error)? else { return Ok(None); }; match value.kind().map_err(structured_tool_error)? { Kind::String(value) => Ok(Some(value)), _ => Ok(None), } } fn input_unsigned(input: &ToolArguments, key: &str) -> Result> { let Some(value) = input.view().field(key).map_err(structured_tool_error)? else { return Ok(None); }; match value.kind().map_err(structured_tool_error)? { Kind::Unsigned(value) => Ok(Some(value)), _ => Ok(None), } } fn structured_tool_error(error: smith::structured::AccessError) -> SmithError { tool_error(smith::error::ToolCode::Validation, error.to_string()) } fn resolve_path(input_path: &str, working_dir: &Path) -> PathBuf { let p = Path::new(input_path); if p.is_absolute() { p.to_path_buf() } else { working_dir.join(p) } } /// Execute a built-in file effect. All outputs are bounded and deterministic; /// filesystem errors are surfaced, never converted to empty success. /// Infer only what effect-boundary evidence proves. /// /// A shell's exit status says nothing about arbitrary commands it may have /// executed, so every spawned shell is `Unknown`; only spawn failure proves /// `NotApplied`. File publication and parent creation provide direct evidence. fn mutation_state(name: &str, effect: &std::result::Result) -> MutationState { match name { "bash" => match effect { Err( SmithError::Cancelled | SmithError::Tool { code: smith::error::ToolCode::BashSpawn, .. }, ) => MutationState::NotApplied, _ => MutationState::Unknown, }, "write" | "edit" => match effect { Ok(_) => MutationState::Applied, Err(SmithError::Tool { code, .. }) if matches!(code.as_str(), "CANCELLED_APPLIED" | "TOOL_TIMEOUT_APPLIED") => { MutationState::Applied } Err(SmithError::Cancelled) => MutationState::NotApplied, Err(_) => MutationState::Unknown, }, _ => MutationState::NotApplied, } } /// Cooperative checkpoints placed at bounded filesystem work boundaries. #[derive(Clone, Copy, PartialEq, Eq)] enum EffectCheckpoint { Start, TraversalEntry, ReadChunk, GrepLine, EditReadChunk, WriteChunk, ParentCreated, BeforePublish, AfterPublish, } #[cfg(test)] #[derive(Clone, Copy, Default)] struct TestEffectControl { cancel_at: Option, timeout_at: Option, } /// Cooperative cancellation and deadline checks around filesystem chunks. /// /// Standard filesystem calls can block without a portable interruption API. /// Smith therefore checks before and after bounded reads and writes, and /// immediately before publication. A cancellation observed after `rename` /// reports that the mutation was already applied; it never claims rollback. struct EffectControl<'a> { cancel: &'a CancelHandle, deadline: Instant, #[cfg(test)] test_control: TestEffectControl, } impl<'a> EffectControl<'a> { fn new( cancel: &'a CancelHandle, timeout_ms: u64, #[cfg(test)] test_control: TestEffectControl, ) -> Self { Self { cancel, deadline: Instant::now() + Duration::from_millis(timeout_ms), #[cfg(test)] test_control, } } fn checkpoint(&self, _checkpoint: EffectCheckpoint, mutation_applied: bool) -> Result<()> { #[cfg(test)] if self.test_control.cancel_at == Some(_checkpoint) { self.cancel.cancel(); } #[cfg(test)] if self.test_control.timeout_at == Some(_checkpoint) { return Err(Self::timeout_error(mutation_applied)); } if self.cancel.is_cancelled() { return Err(if mutation_applied { tool_error( smith::error::ToolCode::CancelledApplied, "cancellation arrived after the file mutation was applied", ) } else { SmithError::Cancelled }); } if Instant::now() >= self.deadline { return Err(Self::timeout_error(mutation_applied)); } Ok(()) } fn timeout_error(mutation_applied: bool) -> SmithError { tool_error( if mutation_applied { smith::error::ToolCode::BashTimeoutApplied } else { smith::error::ToolCode::ToolTimeout }, if mutation_applied { "tool deadline elapsed after the file mutation was applied" } else { "tool deadline elapsed before the effect completed" }, ) } } #[cfg_attr( test, expect( clippy::too_many_arguments, reason = "the shared primitive boundary receives test-only fault injection" ) )] fn execute_effect( name: &str, input: &ToolArguments, working_dir: &Path, config: &Config, cancel: &CancelHandle, observed: &mut HashMap, workspace: Option<&WorkspaceRoot>, #[cfg(test)] test_effect_control: TestEffectControl, ) -> std::result::Result { let control = EffectControl::new( cancel, config.tool_timeout_ms, #[cfg(test)] test_effect_control, ); control.checkpoint(EffectCheckpoint::Start, false)?; let path_str = input_string(input, "path")?.unwrap_or_default(); if let Some(workspace) = workspace && matches!(name, "read" | "write" | "edit" | "ls" | "find" | "grep") { return execute_workspace_effect( name, input, path_str, observed, config, &control, workspace, ); } match name { "bash" => run_bash(input, working_dir, config.tool_timeout_ms, cancel), "read" => read_effect( input, resolve_path(path_str, working_dir), observed, &control, ), "write" => write_effect( input, resolve_path(path_str, working_dir), observed, &control, ), "edit" => edit_effect( input, resolve_path(path_str, working_dir), observed, &control, ), "ls" => { let dir = directory_or(path_str, working_dir); if !dir.is_dir() { return Err(tool_error( smith::error::ToolCode::LsError, format!("{} is not a directory", dir.display()), )); } let names = walk_relative( &dir, Some(1), config, &control, smith::error::ToolCode::LsError, )?; Ok(bounded_join(names, LIST_ENTRIES_MAX)) } "find" => { let pattern = input_string(input, "pattern")?.unwrap_or_default(); let root = directory_or(path_str, working_dir); if !root.is_dir() { return Err(tool_error( smith::error::ToolCode::FindError, format!("{} is not a directory", root.display()), )); } let names = walk_relative( &root, None, config, &control, smith::error::ToolCode::FindError, )? .into_iter() .filter(|name| pattern.is_empty() || name.contains(pattern)) .collect(); Ok(bounded_join(names, LIST_ENTRIES_MAX)) } "grep" => { let query = input_string(input, "query")?.unwrap_or_default(); let target = directory_or(path_str, working_dir); if target.is_dir() { grep_tree(&target, query, config, &control) } else { grep_bounded(&target, query, &control) } } _ => Err(tool_error( smith::error::ToolCode::ToolNotImplemented, format!("tool '{name}' has no built-in effect"), )), } } /// Execute a guest filesystem effect through a held workspace descriptor. #[cfg(target_os = "linux")] fn execute_workspace_effect( name: &str, input: &ToolArguments, path: &str, observed: &mut HashMap, config: &Config, control: &EffectControl<'_>, workspace: &WorkspaceRoot, ) -> std::result::Result { match name { "read" => workspace_read(input, path, observed, control, workspace), "write" => workspace_write(input, path, observed, control, workspace), "edit" => workspace_edit(input, path, observed, control, workspace), "ls" => { let entries = workspace_walk( workspace, path, Some(1), config, control, smith::error::ToolCode::LsError, )?; Ok(bounded_join(entries, LIST_ENTRIES_MAX)) } "find" => { let pattern = input_string(input, "pattern")?.unwrap_or_default(); let entries = workspace_walk( workspace, path, None, config, control, smith::error::ToolCode::FindError, )? .into_iter() .filter(|entry| pattern.is_empty() || entry.contains(pattern)) .collect(); Ok(bounded_join(entries, LIST_ENTRIES_MAX)) } "grep" => { let query = input_string(input, "query")?.unwrap_or_default(); if workspace.is_directory(path) { workspace_grep_tree(workspace, path, query, config, control) } else { workspace_grep_file(workspace, path, query, control) } } _ => unreachable!("workspace dispatch includes only filesystem tools"), } } #[cfg(not(target_os = "linux"))] fn execute_workspace_effect( _name: &str, _input: &ToolArguments, _path: &str, _observed: &mut HashMap, _config: &Config, _control: &EffectControl<'_>, _workspace: &WorkspaceRoot, ) -> std::result::Result { Err(tool_error( smith::error::ToolCode::Validation, "workspace filesystem effects require Linux descriptor confinement", )) } #[cfg(target_os = "linux")] fn workspace_read( input: &ToolArguments, path: &str, observed: &mut HashMap, control: &EffectControl<'_>, workspace: &WorkspaceRoot, ) -> std::result::Result { let count = |key| { input_unsigned(input, key) .map(|value| value.map(|value| usize::try_from(value).unwrap_or(usize::MAX))) }; let file = workspace .open_file(path) .map_err(io_tool_error(smith::error::ToolCode::ReadError))?; let text = read_bounded_file( file, count("offset")?.unwrap_or(0), count("limit")?.unwrap_or(usize::MAX), count("max_bytes")?.map_or(DEFAULT_OUTPUT_CAP, |bytes| bytes.min(HARD_OUTPUT_CAP)), control, )?; workspace_remember(path, observed, workspace); Ok(text) } #[cfg(target_os = "linux")] fn workspace_write( input: &ToolArguments, path: &str, observed: &mut HashMap, control: &EffectControl<'_>, workspace: &WorkspaceRoot, ) -> std::result::Result { let content = input_string(input, "content")?.ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "write requires string 'content'", ) })?; workspace_write_atomic(workspace, path, content.as_bytes(), control)?; workspace_remember(path, observed, workspace); Ok(format!("written {} bytes", content.len())) } #[cfg(target_os = "linux")] fn workspace_edit( input: &ToolArguments, path: &str, observed: &mut HashMap, control: &EffectControl<'_>, workspace: &WorkspaceRoot, ) -> std::result::Result { let observed_path = PathBuf::from(path); if let Some(seen) = observed.get(&observed_path) && workspace .version(path) .ok() .map(FileVersion::from_workspace) != Some(*seen) { return Err(tool_error( smith::error::ToolCode::StaleInput, format!("{path} changed since it was last read; read it again before editing"), )); } let old = input_string(input, "old_string")?.unwrap_or_default(); let new = input_string(input, "new_string")?.unwrap_or_default(); let file = workspace .open_file(path) .map_err(io_tool_error(smith::error::ToolCode::EditReadError))?; let bytes = read_edit_input_file(file, control)?; let content = String::from_utf8(bytes).map_err(|_| { tool_error( smith::error::ToolCode::EditNotUtf8, "edit supports UTF-8 files only", ) })?; let count = content.matches(old).count(); if count == 0 { return Err(tool_error( smith::error::ToolCode::EditNotFound, "old_string not found; file unchanged", )); } if count > 1 { return Err(tool_error( smith::error::ToolCode::EditAmbiguous, format!("old_string matches {count} locations; file unchanged"), )); } let updated = content.replacen(old, new, 1); workspace_write_atomic(workspace, path, updated.as_bytes(), control)?; workspace_remember(path, observed, workspace); Ok("edited".to_string()) } #[cfg(target_os = "linux")] fn workspace_remember( path: &str, observed: &mut HashMap, workspace: &WorkspaceRoot, ) { if let Ok(version) = workspace.version(path) { observed.insert(PathBuf::from(path), FileVersion::from_workspace(version)); } } #[cfg(target_os = "linux")] fn workspace_write_atomic( workspace: &WorkspaceRoot, path: &str, content: &[u8], control: &EffectControl<'_>, ) -> std::result::Result<(), SmithError> { control.checkpoint(EffectCheckpoint::WriteChunk, false)?; workspace .write_atomic( path, |parent_created| control.checkpoint(EffectCheckpoint::ParentCreated, parent_created), |file| { for chunk in content.chunks(64 * 1024) { control .checkpoint(EffectCheckpoint::WriteChunk, false) .map_err(std::io::Error::other)?; file.write_all(chunk)?; control .checkpoint(EffectCheckpoint::WriteChunk, false) .map_err(std::io::Error::other)?; } control .checkpoint(EffectCheckpoint::BeforePublish, false) .map_err(std::io::Error::other) }, ) .map_err(|error| match error { crate::workspace::AtomicWriteError::Checkpoint(error) => error, crate::workspace::AtomicWriteError::Io(error) => { io_tool_error(smith::error::ToolCode::WriteError)(error) } })?; control.checkpoint(EffectCheckpoint::AfterPublish, true) } #[cfg(target_os = "linux")] fn workspace_walk( workspace: &WorkspaceRoot, root: &str, depth_max: Option, config: &Config, control: &EffectControl<'_>, code: smith::error::ToolCode, ) -> std::result::Result, SmithError> { if !workspace.is_directory(root) { return Err(tool_error(code, format!("{root} is not a directory"))); } let mut entries = Vec::with_capacity(LIST_ENTRIES_MAX); let mut ignores = Vec::new(); workspace_walk_directory( workspace, root, "", depth_max, config, control, code, &mut ignores, &mut entries, )?; Ok(entries) } #[cfg(target_os = "linux")] #[expect( clippy::too_many_arguments, reason = "recursive traversal carries its bounded caller state without allocation" )] fn workspace_walk_directory( workspace: &WorkspaceRoot, root: &str, relative: &str, depth_max: Option, config: &Config, control: &EffectControl<'_>, code: smith::error::ToolCode, ignores: &mut Vec, entries: &mut Vec, ) -> std::result::Result<(), SmithError> { let path = workspace_path(root, relative); if config.respect_ignore_files { ignores.push(workspace_ignore_directory( workspace, root, relative, control, code, )?); } let result = (|| { for name in workspace .list_directory(&path, LIST_ENTRIES_MAX, || { control.checkpoint(EffectCheckpoint::TraversalEntry, false) }) .map_err(|error| match error { crate::workspace::DirectoryReadError::Checkpoint(error) => error, crate::workspace::DirectoryReadError::Io(error) => io_tool_error(code)(error), crate::workspace::DirectoryReadError::Limit => { tool_error(code, format!("directory entries exceed {LIST_ENTRIES_MAX}")) } })? { if !config.include_hidden && name.starts_with('.') { continue; } let child = if relative.is_empty() { name } else { format!("{relative}/{name}") }; let child_path = workspace_path(root, &child); let directory = workspace.is_directory(&child_path); if config.respect_ignore_files && workspace_ignored(ignores, root, &child, directory) { continue; } if entries.len() == LIST_ENTRIES_MAX { return Err(tool_error( code, format!("directory entries exceed {LIST_ENTRIES_MAX}"), )); } entries.push(child.clone()); let depth = child.matches('/').count() + 1; if directory && depth_max.is_none_or(|maximum| depth < maximum) { workspace_walk_directory( workspace, root, &child, depth_max, config, control, code, ignores, entries, )?; } } Ok(()) })(); if config.respect_ignore_files { let _ignore = ignores.pop(); } result } #[cfg(target_os = "linux")] fn workspace_path(root: &str, relative: &str) -> String { if relative.is_empty() { root.to_string() } else if root.is_empty() { relative.to_string() } else { format!("{root}/{relative}") } } #[cfg(target_os = "linux")] fn workspace_ignore_directory( workspace: &WorkspaceRoot, root: &str, relative: &str, control: &EffectControl<'_>, code: smith::error::ToolCode, ) -> std::result::Result { let directory = workspace_path(root, relative); let virtual_directory = PathBuf::from(&directory); let mut rules = Vec::with_capacity(3 * IGNORE_LINES_MAX); for name in [".git/info/exclude", ".gitignore", ".ignore"] { let path = workspace_path(&directory, name); let file = match workspace.open_file(&path) { Ok(file) => file, Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue, Err(error) => return Err(io_tool_error(code)(error)), }; let mut reader = BufReader::with_capacity(IGNORE_LINE_BYTES_MAX, file); let mut line = Vec::new(); for _ in 0..IGNORE_LINES_MAX { control.checkpoint(EffectCheckpoint::TraversalEntry, false)?; line.clear(); if !read_line_bounded(&mut reader, &mut line, IGNORE_LINE_BYTES_MAX) .map_err(io_tool_error(code))? { break; } rules.push(( virtual_directory.join(".gitignore"), String::from_utf8_lossy(&line).into_owned(), )); } line.clear(); if read_line_bounded(&mut reader, &mut line, IGNORE_LINE_BYTES_MAX) .map_err(io_tool_error(code))? { return Err(tool_error( code, format!("ignore file {path} exceeds {IGNORE_LINES_MAX} lines"), )); } } crate::filters::DirectoryIgnore::compile(&virtual_directory, rules) .map_err(|error| tool_error(code, format!("invalid ignore rule: {error}"))) } #[cfg(target_os = "linux")] fn workspace_ignored( ignores: &[crate::filters::DirectoryIgnore], root: &str, relative: &str, directory: bool, ) -> bool { let path = PathBuf::from(workspace_path(root, relative)); for ignore in ignores.iter().rev() { match ignore.matches(&path, directory) { crate::filters::IgnoreMatch::Ignore => return true, crate::filters::IgnoreMatch::Whitelist => return false, crate::filters::IgnoreMatch::None => {} } } false } #[cfg(target_os = "linux")] fn workspace_grep_tree( workspace: &WorkspaceRoot, root: &str, query: &str, config: &Config, control: &EffectControl<'_>, ) -> std::result::Result { let entries = workspace_walk( workspace, root, None, config, control, smith::error::ToolCode::GrepError, )?; let mut matches = Vec::new(); let mut total_bytes = 0usize; for relative in entries { let path = if root.is_empty() { relative.clone() } else { format!("{root}/{relative}") }; if workspace.is_directory(&path) { continue; } let Ok(lines) = workspace_grep_lines(workspace, &path, query, control) else { continue; }; for (line_number, text) in lines { if matches.len() >= GREP_MATCHES_MAX || total_bytes + relative.len() + text.len() + 32 > DEFAULT_OUTPUT_CAP { matches.push("".to_string()); return Ok(matches.join("\n")); } let rendered = format!("{relative}:{line_number}:{text}"); total_bytes += rendered.len(); matches.push(rendered); } } Ok(matches.join("\n")) } #[cfg(target_os = "linux")] fn workspace_grep_file( workspace: &WorkspaceRoot, path: &str, query: &str, control: &EffectControl<'_>, ) -> std::result::Result { Ok(bounded_join( workspace_grep_lines(workspace, path, query, control)? .into_iter() .map(|(_, text)| text) .collect(), GREP_MATCHES_MAX, )) } #[cfg(target_os = "linux")] fn workspace_grep_lines( workspace: &WorkspaceRoot, path: &str, query: &str, control: &EffectControl<'_>, ) -> std::result::Result, SmithError> { let file = workspace .open_file(path) .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?; let mut reader = BufReader::with_capacity(64 * 1024, file); let mut lines = Vec::new(); let mut line = Vec::new(); let mut line_number = 0usize; let mut output_bytes = 0usize; loop { control.checkpoint(EffectCheckpoint::GrepLine, false)?; line.clear(); if !read_line_bounded(&mut reader, &mut line, GREP_LINE_BYTES_MAX) .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))? { break; } line_number += 1; if line.contains(&0) { break; } let text = String::from_utf8_lossy(&line).trim_end().to_string(); if text.contains(query) { if output_bytes + text.len() > DEFAULT_OUTPUT_CAP { break; } output_bytes += text.len(); lines.push((line_number, text)); if lines.len() >= GREP_MATCHES_MAX { break; } } } Ok(lines) } /// Read a bounded window and remember the version that was shown. fn read_effect( input: &ToolArguments, path: PathBuf, observed: &mut HashMap, control: &EffectControl<'_>, ) -> std::result::Result { let count = |key: &str| { input_unsigned(input, key) .map(|value| value.map(|value| usize::try_from(value).unwrap_or(usize::MAX))) }; let text = read_bounded( &path, count("offset")?.unwrap_or(0), count("limit")?.unwrap_or(usize::MAX), count("max_bytes")?.map_or(DEFAULT_OUTPUT_CAP, |bytes| bytes.min(HARD_OUTPUT_CAP)), control, )?; remember(path, observed); Ok(text) } /// Replace a file atomically and remember the version just written. fn write_effect( input: &ToolArguments, path: PathBuf, observed: &mut HashMap, control: &EffectControl<'_>, ) -> std::result::Result { let content = input_string(input, "content")?.ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "write requires string 'content'", ) })?; write_atomic(&path, content.as_bytes(), control)?; remember(path, observed); Ok(format!("written {} bytes", content.len())) } /// Apply an exact replacement, refusing input that describes an older /// version of the file. /// /// An edit describes a file the caller has seen. If the file moved on since /// then, applying the replacement would silently discard the newer content. fn edit_effect( input: &ToolArguments, path: PathBuf, observed: &mut HashMap, control: &EffectControl<'_>, ) -> std::result::Result { let old = input_string(input, "old_string")?.unwrap_or_default(); let new = input_string(input, "new_string")?.unwrap_or_default(); if let Some(seen) = observed.get(&path) && FileVersion::of(&path) != Some(*seen) { return Err(tool_error( smith::error::ToolCode::StaleInput, format!( "{} changed since it was last read; read it again before editing", path.display() ), )); } let result = edit_exact(&path, old, new, control)?; remember(path, observed); Ok(result) } /// Record the current version of `path` as the one the caller has seen. fn remember(path: PathBuf, observed: &mut HashMap) { if let Some(version) = FileVersion::of(&path) { observed.insert(path, version); } } /// The requested path, or the invocation directory when none was given. fn directory_or(path_str: &str, working_dir: &Path) -> PathBuf { if path_str.is_empty() { working_dir.to_path_buf() } else { resolve_path(path_str, working_dir) } } /// Ignore-aware, deterministic walk of `root`. /// /// Traversal order is sorted by path, and configured ignore files and hidden /// entries are honored, so identical trees always produce identical results. fn walker(root: &Path, depth_max: Option, config: &Config) -> crate::filters::Walker { crate::filters::Walker::new( root, depth_max, config.include_hidden, config.respect_ignore_files, ) } /// Paths under `root`, relative to it, bounded and cancellable. fn walk_relative( root: &Path, depth_max: Option, config: &Config, control: &EffectControl<'_>, code: smith::error::ToolCode, ) -> std::result::Result, SmithError> { let mut names = Vec::new(); for found in walker(root, depth_max, config) { control.checkpoint(EffectCheckpoint::TraversalEntry, false)?; let found = found.map_err(|error| tool_error(code, error))?; if found.depth() == 0 { continue; } names.push( found .path() .strip_prefix(root) .unwrap_or_else(|_| found.path()) .to_string_lossy() .into_owned(), ); if names.len() >= LIST_ENTRIES_MAX { break; } } Ok(names) } /// Search every non-ignored file under `root` for `query`. /// /// Matches are reported as `relative/path:line:text`, bounded by match count /// and total output, and unreadable or binary files are skipped rather than /// failing the whole search. fn grep_tree( root: &Path, query: &str, config: &Config, control: &EffectControl<'_>, ) -> std::result::Result { let mut matches: Vec = Vec::new(); let mut total_bytes = 0usize; for found in walker(root, None, config) { control.checkpoint(EffectCheckpoint::TraversalEntry, false)?; let found = found.map_err(|error| tool_error(smith::error::ToolCode::GrepError, error))?; if !found.is_file() { continue; } let relative = found .path() .strip_prefix(root) .unwrap_or_else(|_| found.path()) .to_string_lossy() .into_owned(); let Ok(file) = fs::File::open(found.path()) else { continue; }; let mut reader = BufReader::with_capacity(64 * 1024, file); let mut line = Vec::new(); let mut line_no = 0usize; loop { control.checkpoint(EffectCheckpoint::GrepLine, false)?; line.clear(); if !matches!( read_line_bounded(&mut reader, &mut line, GREP_LINE_BYTES_MAX), Ok(true) ) { break; } control.checkpoint(EffectCheckpoint::GrepLine, false)?; if line.contains(&0) { break; // binary content } line_no += 1; let text = String::from_utf8_lossy(&line).trim_end().to_string(); if !text.contains(query) { continue; } let rendered = format!("{relative}:{line_no}:{text}"); if matches.len() >= GREP_MATCHES_MAX || total_bytes + rendered.len() > DEFAULT_OUTPUT_CAP { matches.push("".to_string()); return Ok(matches.join("\n")); } total_bytes += rendered.len(); matches.push(rendered); } } Ok(matches.join("\n")) } /// Run one bounded, cancellable shell command in the invocation directory. fn run_bash( input: &ToolArguments, working_dir: &Path, timeout_ms: u64, cancel: &CancelHandle, ) -> std::result::Result { let command = input_string(input, "command")?.ok_or_else(|| { tool_error( smith::error::ToolCode::Validation, "bash requires string 'command'", ) })?; let requested = input_unsigned(input, "timeout_ms")?.unwrap_or(timeout_ms); let result = crate::bash::execute( command, working_dir.to_str(), requested.min(timeout_ms), DEFAULT_OUTPUT_CAP, cancel, )?; if result.cancelled { return Err(tool_error( smith::error::ToolCode::CancelledUnknown, "shell was cancelled after spawning; mutation state is unknown", )); } let mut output = result.stdout; if !result.stderr.is_empty() { if !output.is_empty() { output.push('\n'); } output.push_str("[stderr] "); output.push_str(&result.stderr); } if result.timed_out { return Err(tool_error( smith::error::ToolCode::BashTimeout, format!("timed out after {requested} ms: {output}"), )); } match result.exit_code { Some(0) => Ok(output), Some(code) => Err(tool_error( smith::error::ToolCode::BashExit, format!("exit {code}: {output}"), )), None => Err(tool_error( smith::error::ToolCode::BashKilled, format!("terminated without exit status: {output}"), )), } } /// Read a bounded line window without materializing the whole file. fn read_bounded( path: &Path, offset: usize, limit: usize, bytes_max: usize, control: &EffectControl<'_>, ) -> std::result::Result { control.checkpoint(EffectCheckpoint::ReadChunk, false)?; let file = fs::File::open(path).map_err(io_tool_error(smith::error::ToolCode::ReadError))?; read_bounded_file(file, offset, limit, bytes_max, control) } /// Read one bounded file descriptor window without reopening its path. fn read_bounded_file( file: fs::File, offset: usize, limit: usize, bytes_max: usize, control: &EffectControl<'_>, ) -> std::result::Result { control.checkpoint(EffectCheckpoint::ReadChunk, false)?; let mut reader = BufReader::with_capacity(64 * 1024, file); // Binary sniff on the first bytes. let sniff = reader .fill_buf() .map_err(io_tool_error(smith::error::ToolCode::ReadError))?; control.checkpoint(EffectCheckpoint::ReadChunk, false)?; if sniff[..sniff.len().min(8192)].contains(&0) { return Err(tool_error( smith::error::ToolCode::BinaryContent, "file contains NUL bytes; binary content is unsupported", )); } let mut out = String::new(); let mut buffer: Vec = Vec::with_capacity(8 * 1024); let mut line_no = 0usize; let mut bytes_out = 0usize; loop { control.checkpoint(EffectCheckpoint::ReadChunk, false)?; buffer.clear(); #[expect( clippy::disallowed_methods, reason = "Take caps one read-tool line before truncation is reported" )] let bytes_read = (&mut reader) .take((DEFAULT_OUTPUT_CAP + 1) as u64) .read_until(b'\n', &mut buffer) .map_err(io_tool_error(smith::error::ToolCode::ReadError))?; let line_ended = buffer.ends_with(b"\n") || reader .fill_buf() .map_err(io_tool_error(smith::error::ToolCode::ReadError))? .is_empty(); if bytes_read == 0 || buffer.len() > DEFAULT_OUTPUT_CAP || !line_ended { break; } control.checkpoint(EffectCheckpoint::ReadChunk, false)?; line_no += 1; if line_no <= offset { continue; } let emit = if limit == usize::MAX { true } else { (line_no - offset) <= limit }; if !emit { break; } if bytes_out + buffer.len() > bytes_max { break; // keep fitting prefix only } bytes_out += buffer.len(); out.push_str(&String::from_utf8_lossy(&buffer)); if bytes_out >= bytes_max { break; } } Ok(out) } /// Atomically replace `path` with `content`: temp file in the same /// directory, synced, then renamed over the destination. fn write_atomic( path: &Path, content: &[u8], control: &EffectControl<'_>, ) -> std::result::Result<(), SmithError> { control.checkpoint(EffectCheckpoint::WriteChunk, false)?; let parent = path.parent().filter(|p| !p.as_os_str().is_empty()); if let Some(parent) = parent { let parent_existed = parent.is_dir(); fs::create_dir_all(parent).map_err(io_tool_error(smith::error::ToolCode::WriteMkdir))?; control.checkpoint(EffectCheckpoint::ParentCreated, !parent_existed)?; control.checkpoint(EffectCheckpoint::WriteChunk, !parent_existed)?; } let temporary = temp_sibling(path); let write = || -> std::result::Result<(), SmithError> { let mut file = fs::File::create(&temporary) .map_err(io_tool_error(smith::error::ToolCode::WriteError))?; control.checkpoint(EffectCheckpoint::WriteChunk, false)?; for chunk in content.chunks(64 * 1024) { control.checkpoint(EffectCheckpoint::WriteChunk, false)?; file.write_all(chunk) .map_err(io_tool_error(smith::error::ToolCode::WriteError))?; control.checkpoint(EffectCheckpoint::WriteChunk, false)?; } control.checkpoint(EffectCheckpoint::WriteChunk, false)?; file.sync_all() .map_err(io_tool_error(smith::error::ToolCode::WriteError))?; control.checkpoint(EffectCheckpoint::BeforePublish, false) }; if let Err(error) = write() { // Preserve the write failure; temporary-file removal is best-effort cleanup. let _cleanup_result: std::io::Result<()> = fs::remove_file(&temporary); return Err(error); } control.checkpoint(EffectCheckpoint::BeforePublish, false)?; fs::rename(&temporary, path).map_err(|error| { // Preserve the publish failure; temporary-file removal is best-effort cleanup. let _cleanup_result: std::io::Result<()> = fs::remove_file(&temporary); io_tool_error(smith::error::ToolCode::WritePublish)(error) })?; control.checkpoint(EffectCheckpoint::AfterPublish, true) } /// A hidden sibling path used for atomic publication. fn temp_sibling(path: &Path) -> PathBuf { static COUNTER: AtomicUsize = AtomicUsize::new(0); let n = COUNTER.fetch_add(1, Ordering::Relaxed); let name = path.file_name().map_or_else( || "file".to_string(), |name| name.to_string_lossy().into_owned(), ); path.with_file_name(format!(".{name}.tmp-{}-{n}", std::process::id())) } /// Apply exactly one unambiguous replacement, publishing atomically. fn edit_exact( path: &Path, old: &str, new: &str, control: &EffectControl<'_>, ) -> std::result::Result { let meta = fs::metadata(path).map_err(io_tool_error(smith::error::ToolCode::EditReadError))?; if meta.len() > u64::try_from(EDIT_FILE_BYTES_MAX).unwrap_or(u64::MAX) { return Err(tool_error( smith::error::ToolCode::FileTooLarge, "edit input exceeds the file size limit", )); } let bytes = read_edit_input(path, meta.len(), control)?; let content = String::from_utf8(bytes).map_err(|_| { tool_error( smith::error::ToolCode::EditNotUtf8, "edit supports UTF-8 files only", ) })?; let count = content.matches(old).count(); if count == 0 { return Err(tool_error( smith::error::ToolCode::EditNotFound, "old_string not found; file unchanged", )); } if count > 1 { return Err(tool_error( smith::error::ToolCode::EditAmbiguous, format!("old_string matches {count} locations; file unchanged"), )); } let updated = content.replacen(old, new, 1); write_atomic(path, updated.as_bytes(), control)?; Ok("edited".to_string()) } /// Read edit input in bounded chunks so cancellation stays live between reads. fn read_edit_input( path: &Path, expected_len: u64, control: &EffectControl<'_>, ) -> std::result::Result, SmithError> { let file = fs::File::open(path).map_err(io_tool_error(smith::error::ToolCode::EditReadError))?; let capacity = usize::try_from(expected_len).unwrap_or(EDIT_FILE_BYTES_MAX); read_edit_input_file_with_capacity(file, capacity, control) } /// Read one edit target without reopening its descriptor-confined path. fn read_edit_input_file( file: fs::File, control: &EffectControl<'_>, ) -> std::result::Result, SmithError> { read_edit_input_file_with_capacity(file, EDIT_FILE_BYTES_MAX, control) } fn read_edit_input_file_with_capacity( mut file: fs::File, capacity: usize, control: &EffectControl<'_>, ) -> std::result::Result, SmithError> { control.checkpoint(EffectCheckpoint::EditReadChunk, false)?; let mut bytes = Vec::with_capacity(capacity); let mut chunk = [0_u8; 16 * 1024]; loop { control.checkpoint(EffectCheckpoint::EditReadChunk, false)?; let read = file .read(&mut chunk) .map_err(io_tool_error(smith::error::ToolCode::EditReadError))?; control.checkpoint(EffectCheckpoint::EditReadChunk, false)?; if read == 0 { break; } if bytes.len() + read > EDIT_FILE_BYTES_MAX { return Err(tool_error( smith::error::ToolCode::FileTooLarge, "edit input exceeds the file size limit", )); } bytes.extend_from_slice(&chunk[..read]); } Ok(bytes) } /// Deterministic, bounded listing output. fn bounded_join(mut names: Vec, cap: usize) -> String { names.truncate(cap); let mut out = names.join("\n"); let max = DEFAULT_OUTPUT_CAP; if out.len() > max { out.truncate(max); out.push_str("\n"); } out } /// Stream matching lines with bounded memory and result count. fn grep_bounded( path: &Path, query: &str, control: &EffectControl<'_>, ) -> std::result::Result { let file = fs::File::open(path).map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?; grep_bounded_file(file, query, control) } /// Search one already-open file descriptor. fn grep_bounded_file( file: fs::File, query: &str, control: &EffectControl<'_>, ) -> std::result::Result { control.checkpoint(EffectCheckpoint::GrepLine, false)?; let mut reader = BufReader::with_capacity(64 * 1024, file); let mut matches: Vec = Vec::new(); let mut total_bytes = 0usize; loop { control.checkpoint(EffectCheckpoint::GrepLine, false)?; let mut line = Vec::new(); #[expect( clippy::disallowed_methods, reason = "Take caps one grep line before overflow is reported" )] let bytes_read = (&mut reader) .take((GREP_LINE_BYTES_MAX + 1) as u64) .read_until(b'\n', &mut line) .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?; if bytes_read == 0 { break; } let line_ended = line.ends_with(b"\n") || reader .fill_buf() .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))? .is_empty(); if line.len() > GREP_LINE_BYTES_MAX || !line_ended { matches.push("".to_string()); break; } if line.ends_with(b"\n") { line.pop(); } if line.last() == Some(&b'\r') { line.pop(); } control.checkpoint(EffectCheckpoint::GrepLine, false)?; let line = String::from_utf8(line).map_err(|error| { io_tool_error(smith::error::ToolCode::GrepReadError)(std::io::Error::new( std::io::ErrorKind::InvalidData, error, )) })?; if line.contains(query) { if matches.len() >= GREP_MATCHES_MAX || total_bytes + line.len() > DEFAULT_OUTPUT_CAP { matches.push("".to_string()); break; } total_bytes += line.len(); matches.push(line); } } Ok(matches.join("\n")) } /// Wall-clock milliseconds since the Unix epoch, saturating on overflow. fn now_ms() -> i64 { std::time::SystemTime::now() .duration_since(std::time::UNIX_EPOCH) .map_or(0, |elapsed| { i64::try_from(elapsed.as_millis()).unwrap_or(i64::MAX) }) } #[cfg(test)] pub(crate) fn test_tool_snapshot() -> Result { let tools = crate::tools::test_tool_registry().snapshot().to_vec(); let components = vec![crate::tools::ToolComponentProvenance { source_id: "test-component".into(), manifest_sha256: "0".repeat(64), component_sha256: "1".repeat(64), }]; let provenance = crate::tools::ToolLoadoutProvenance { components, tools: tools .iter() .cloned() .map(|definition| crate::tools::ToolLoadoutTool { definition, component_index: 0, }) .collect(), }; Ok(crate::tools::ToolDispatcherSnapshot { policy: tools .iter() .map(|tool| (tool.name.clone(), crate::tools::ToolPolicyState::Advertised)) .collect(), registered_tools: tools.clone(), tools, provenance, }) } #[cfg(test)] #[expect( clippy::unwrap_used, clippy::panic, reason = "tests may panic on invariant violations" )] mod tests { #[test] fn empty_lifecycle_dispatcher_adds_no_boundary_allocations() { struct Empty; impl super::ToolDispatcher for Empty { fn invoke( &mut self, _: &str, _: &smith::ToolArguments, _: &mut super::ToolEffectContext<'_>, ) -> smith::Result { unreachable!() } } let mut tools = super::ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(Empty)); let event = smith::lifecycle::LifecycleEvent { root_entry_id: smith::id::EntryId::new(), boundary: smith::lifecycle::Boundary::Settled, round_index: 0, last_stop: smith::stream::StopReason::EndTurn, continuation_eligible: false, }; let (result, cost) = smith_alloc::measure(smith_alloc::Scope::Session, || { tools.lifecycle(&event, &str::to_owned) }); result.unwrap(); assert_eq!(cost.allocations, 0); } use super::*; macro_rules! test_args { ($($value:tt)*) => { ToolArguments::from_serializable(&serde_json::json!($($value)*)).unwrap() }; } use crate::process_signal::{ProcessSignal, closed}; use crate::session::EntryContent; use crate::session::EntryKind; use std::path::PathBuf; use std::sync::mpsc; use std::thread; fn workdir(tag: &str) -> PathBuf { let dir = std::env::temp_dir().join(format!("smith_tools_{}_{}", tag, std::process::id())); let _ = std::fs::remove_dir_all(&dir); std::fs::create_dir_all(&dir).unwrap(); dir } #[cfg(target_os = "linux")] struct ConfinedDispatcher { workspace: WorkspaceRoot, } #[cfg(target_os = "linux")] impl ToolDispatcher for ConfinedDispatcher { fn invoke( &mut self, name: &str, input: &ToolArguments, effects: &mut ToolEffectContext<'_>, ) -> Result { effects.set_workspace_root(self.workspace.clone()); effects.invoke(name, input) } } #[cfg(target_os = "linux")] fn confined_session(dir: &Path) -> ToolSession { let mut session = ToolSession::new(dir); session.set_dispatcher(Box::new(ConfinedDispatcher { workspace: WorkspaceRoot::open(dir).unwrap(), })); session } struct SequentialWrites; impl ToolDispatcher for SequentialWrites { fn invoke( &mut self, _: &str, input: &ToolArguments, effects: &mut ToolEffectContext<'_>, ) -> Result { effects.invoke("write", input)?; effects.invoke( "write", &test_args!({"path":"second.txt","content":"second"}), ) } } struct PolicyDispatcher(ToolPolicyState); impl ToolDispatcher for PolicyDispatcher { fn begin_provider_round(&mut self) -> Result { let mut snapshot = test_tool_snapshot()?; snapshot .policy .iter_mut() .for_each(|(_, state)| *state = self.0); if self.0 != ToolPolicyState::Advertised { snapshot.tools.clear(); snapshot.provenance.tools.clear(); } Ok(snapshot) } fn invoke( &mut self, _: &str, _: &ToolArguments, _: &mut ToolEffectContext<'_>, ) -> Result { Ok("host-called".into()) } } #[test] fn admitted_hidden_inventory_does_not_invalidate_advertised_provenance() { let mut tools = ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Hidden))); tools.begin_provider_round().unwrap(); tools.record_admitted_loadout_provenance().unwrap(); assert!(tools.advertised_tools().is_empty()); assert!(!tools.registered_tools().is_empty()); } #[test] fn model_cannot_invoke_registered_but_unadvertised_tool() { let mut tools = ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Hidden))); tools.begin_provider_round().unwrap(); let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap(); let error = tools .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string) .unwrap_err(); assert!( matches!( error, SmithError::Tool { code: smith::error::ToolCode::ToolNotAdvertised, .. } ), "{error}" ); assert!(tools.session.active_branch().entries().is_empty()); } #[test] fn hidden_active_tool_remains_available_to_trusted_host_invocation() { let mut tools = ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Hidden))); tools.begin_provider_round().unwrap(); let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap(); let outcome = tools.invoke("read", &input).unwrap(); assert_eq!(outcome.output, "host-called"); assert!(outcome.ok); assert!(tools.advertised_tools().is_empty()); } #[test] fn disabled_tool_rejects_every_caller_before_handler_or_ledger() { let mut tools = ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Disabled))); tools.begin_provider_round().unwrap(); let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap(); for error in [ tools.invoke("read", &input).unwrap_err(), tools .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string) .unwrap_err(), ] { assert!( matches!( error, SmithError::Tool { code: smith::error::ToolCode::ToolDisabled, .. } ), "{error}" ); } assert!(tools.session.active_branch().entries().is_empty()); } #[test] fn model_cannot_reuse_a_released_request_pin() { let mut tools = ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Advertised))); tools.begin_provider_round().unwrap(); tools.end_provider_round(); let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap(); let error = tools .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string) .unwrap_err(); assert!( matches!( error, SmithError::Tool { code: smith::error::ToolCode::ToolNotAdvertised, .. } ), "{error}" ); assert!(tools.session.active_branch().entries().is_empty()); } #[test] fn model_arguments_use_originating_schema_not_later_registration() { let mut tools = ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Advertised))); tools.begin_provider_round().unwrap(); let mut replacement = tools.registry.get("read").unwrap().clone(); replacement.input_schema = smith::structured::ToolSchema::empty_object(); tools.register(replacement); let input = ToolArguments::from_json("{}").unwrap(); let error = tools .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string) .unwrap_err(); assert!( matches!( error, SmithError::Tool { code: smith::error::ToolCode::Validation, .. } ), "{error}" ); assert!(tools.session.active_branch().entries().is_empty()); } #[test] fn advertised_authorization_allocates_nothing() { let mut tools = ToolSession::new(std::env::temp_dir()); tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Advertised))); tools.begin_provider_round().unwrap(); let (result, cost) = smith_alloc::measure(smith_alloc::Scope::KernelCall, || { tools.authorize_model_call("read") }); result.unwrap(); assert_eq!(cost.allocations, 0); assert_eq!(std::mem::size_of::(), 1); #[cfg(target_pointer_width = "64")] assert_eq!(std::mem::size_of::<(String, ToolPolicyState)>(), 32); } #[test] fn admitted_sequential_writes_have_independent_durable_intents() { let dir = workdir("nested_writes"); let mut tools = ToolSession::new(&dir); let root = tools .session .append(&EntryContent::Message(smith::message::Message::with_text( smith::message::Role::User, "write twice", ))) .unwrap() .id; tools.set_dispatcher(Box::new(SequentialWrites)); let mut tools = tools.with_completion_boundary(root, |_| Ok(())); let outcome = tools .invoke("write", &test_args!({"path":"first.txt","content":"first"})) .unwrap(); assert!(outcome.ok, "{}", outcome.output); assert_eq!( std::fs::read_to_string(dir.join("second.txt")).unwrap(), "second" ); let intents = tools.session.active_branch().entries().iter().filter(|entry| { matches!(tools.session.content(entry).unwrap(), EntryContent::Meta { kind, .. } if kind == "nested-effect-intent") }).count(); assert_eq!(intents, 2); std::fs::remove_dir_all(dir).unwrap(); } #[test] fn listing_and_searching_respect_ignore_rules_and_hidden_entries() { let dir = workdir("ignore_rules"); std::fs::write(dir.join(".gitignore"), "ignored.txt\n").unwrap(); std::fs::write(dir.join("keep.txt"), "needle here\n").unwrap(); std::fs::write(dir.join("ignored.txt"), "needle here\n").unwrap(); std::fs::write(dir.join(".hidden.txt"), "needle here\n").unwrap(); std::fs::create_dir_all(dir.join("nested")).unwrap(); std::fs::write(dir.join("nested/deep.txt"), "needle deep\n").unwrap(); let mut ts = ToolSession::new(&dir); // find walks recursively and drops ignored and hidden paths. let found = ts .invoke("find", &test_args!({"pattern": ""})) .unwrap() .output; assert_eq!(found, "keep.txt\nnested\nnested/deep.txt"); // ls stays one level deep, with the same filtering. let listed = ts.invoke("ls", &test_args!({})).unwrap().output; assert_eq!(listed, "keep.txt\nnested"); // grep searches the tree and locates each match. let hits = ts .invoke("grep", &test_args!({"path": "", "query": "needle"})) .unwrap() .output; assert_eq!( hits, "keep.txt:1:needle here\nnested/deep.txt:1:needle deep" ); // Configuration decides: without ignore rules, everything shows up. let mut config = Config::default_valid(); config.respect_ignore_files = false; config.include_hidden = true; let mut permissive = ToolSession::new(&dir).with_config(config); let found = permissive .invoke("find", &test_args!({"pattern": ".txt"})) .unwrap() .output; assert_eq!(found, ".hidden.txt\nignored.txt\nkeep.txt\nnested/deep.txt"); let hits = permissive .invoke("grep", &test_args!({"path": "", "query": "needle here"})) .unwrap() .output; assert_eq!( hits, ".hidden.txt:1:needle here\nignored.txt:1:needle here\nkeep.txt:1:needle here" ); } #[cfg(target_os = "linux")] #[test] fn confined_walk_preserves_gitignore_ignore_negation_and_grep() { let dir = workdir("confined_ignore"); std::fs::write(dir.join(".gitignore"), "*.log\n/only-root.txt\n").unwrap(); std::fs::create_dir_all(dir.join(".git/info")).unwrap(); std::fs::write(dir.join(".git/info/exclude"), "excluded.txt\n").unwrap(); std::fs::create_dir_all(dir.join("nested")).unwrap(); std::fs::write(dir.join("nested/.ignore"), "!keep.log\n").unwrap(); std::fs::write(dir.join("drop.log"), "needle root\n").unwrap(); std::fs::write(dir.join("excluded.txt"), "needle excluded\n").unwrap(); std::fs::write(dir.join("only-root.txt"), "needle root-only\n").unwrap(); std::fs::write(dir.join("nested/drop.log"), "needle drop\n").unwrap(); std::fs::write(dir.join("nested/keep.log"), "needle keep\n").unwrap(); std::fs::write(dir.join("nested/only-root.txt"), "needle nested-only\n").unwrap(); let mut session = confined_session(&dir); assert_eq!( session .invoke("find", &test_args!({"pattern": ".log"})) .unwrap() .output, "nested/keep.log" ); assert_eq!( session .invoke("find", &test_args!({"pattern": "only-root.txt"})) .unwrap() .output, "nested/only-root.txt" ); assert_eq!( session .invoke("grep", &test_args!({"path": "", "query": "needle"})) .unwrap() .output, "nested/keep.log:1:needle keep\nnested/only-root.txt:1:needle nested-only" ); } #[cfg(target_os = "linux")] #[test] fn confined_grep_output_cap_preserves_rendered_matches_and_truncation() { let dir = workdir("confined_grep_cap"); let text = format!("needle-{}", "x".repeat(400)); let input = (1..=GREP_MATCHES_MAX) .map(|_| format!("{text}\n")) .collect::(); std::fs::write(dir.join("matches.txt"), input).unwrap(); let output = confined_session(&dir) .invoke("grep", &test_args!({"path": "", "query": "needle"})) .unwrap() .output; let expected = (1..=155) .map(|line_number| format!("matches.txt:{line_number}:{text}")) .chain(std::iter::once("".to_string())) .collect::>() .join("\n"); assert_eq!(output, expected); std::fs::remove_dir_all(dir).unwrap(); } #[cfg(target_os = "linux")] #[test] fn confined_directory_limit_is_exact_and_cancellable_during_read() { let dir = workdir("confined_directory_limit"); for index in 0..LIST_ENTRIES_MAX { std::fs::write(dir.join(format!("{index:04}")), "").unwrap(); } let mut session = confined_session(&dir); assert_eq!( session .invoke("ls", &test_args!({})) .unwrap() .output .lines() .count(), LIST_ENTRIES_MAX ); std::fs::write(dir.join("1000"), "").unwrap(); let error = confined_session(&dir) .invoke("ls", &test_args!({})) .unwrap_err(); assert_eq!(error.code(), "LS_ERROR"); assert!(error.to_string().contains("directory entries exceed 1000")); let mut session = confined_session(&dir); session.cancel_at_checkpoint(EffectCheckpoint::TraversalEntry); let error = session.invoke("ls", &test_args!({})).unwrap_err(); assert_eq!(error.code(), "CANCELLED"); } #[cfg(target_os = "linux")] #[test] fn confined_parent_creation_cancellation_and_timeout_record_applied() { for (tag, code, configure) in [ ( "confined_parent_cancellation", "CANCELLED_APPLIED", ToolSession::cancel_at_checkpoint as fn(&mut ToolSession, EffectCheckpoint), ), ( "confined_parent_timeout", "TOOL_TIMEOUT_APPLIED", ToolSession::timeout_at_checkpoint as fn(&mut ToolSession, EffectCheckpoint), ), ] { let dir = workdir(tag); let mut session = confined_session(&dir); configure(&mut session, EffectCheckpoint::ParentCreated); let error = session .invoke( "write", &test_args!({"path": "a/b/target.txt", "content": "new"}), ) .unwrap_err(); assert_eq!(error.code(), code); assert!(dir.join("a/b").is_dir()); assert!(!dir.join("a/b/target.txt").exists()); let entry = session.session.active_branch().entries().last().unwrap(); assert!(matches!( session.session.content(entry).unwrap(), EntryContent::Meta { detail, .. } if serde_json::to_value(&detail).unwrap()["mutation_state"] == "applied" )); } } #[test] fn edit_rejects_input_that_describes_an_older_version_of_the_file() { let dir = workdir("stale_edit"); let target = dir.join("doc.txt"); std::fs::write(&target, "alpha one\n").unwrap(); let mut ts = ToolSession::new(&dir); ts.invoke("read", &test_args!({"path": "doc.txt"})).unwrap(); // Somebody else rewrites the file after the read; same length, so only the mtime tells. std::fs::write(&target, "alpha two\n").unwrap(); // inject: pin the rewrite's mtime past the read instead of sleeping for a clock tick. let later = std::fs::metadata(&target).unwrap().modified().unwrap() + std::time::Duration::from_secs(60); std::fs::File::options() .write(true) .open(&target) .unwrap() .set_modified(later) .unwrap(); let error = ts .invoke( "edit", &test_args!({"path": "doc.txt", "old_string": "alpha", "new_string": "beta"}), ) .unwrap_err(); assert_eq!(error.code(), "STALE_INPUT"); assert_eq!(std::fs::read_to_string(&target).unwrap(), "alpha two\n"); // Re-reading refreshes the observed version and unblocks the edit. ts.invoke("read", &test_args!({"path": "doc.txt"})).unwrap(); ts.invoke( "edit", &test_args!({"path": "doc.txt", "old_string": "alpha", "new_string": "beta"}), ) .unwrap(); assert_eq!(std::fs::read_to_string(&target).unwrap(), "beta two\n"); } #[test] fn bash_effect_runs_in_the_workdir_and_is_recorded() { let dir = workdir("bash_effect"); let mut ts = ToolSession::new(&dir); let outcome = ts .invoke( "bash", &test_args!({"command": "printf hi > made.txt; printf done"}), ) .unwrap(); assert!(outcome.ok); assert_eq!(outcome.mutation_state, MutationState::Unknown); assert_eq!(outcome.output, "done"); assert_eq!(std::fs::read_to_string(dir.join("made.txt")).unwrap(), "hi"); // A recorded call always precedes its result. let kinds: Vec<&str> = ts .session .active_branch() .entries() .iter() .map(|e| match e.kind { EntryKind::ToolCall { .. } => "call", EntryKind::ToolResult { .. } => "result", _ => "other", }) .collect(); assert_eq!(kinds, vec!["call", "result", "other"]); assert_eq!( ts.session.mutation_state(outcome.call_id).unwrap(), MutationState::Unknown ); } #[test] fn cancelled_shell_after_write_records_unknown_mutation_state() { let dir = workdir("bash_cancelled_mutation"); let signal = ProcessSignal::new(); let command = format!("printf made > made.txt; {}; sleep 30", signal.raise()); let mut ts = ToolSession::new(&dir); let cancel = ts.cancel_handle(); let (done, finished) = mpsc::channel(); thread::spawn(move || { let error = ts .invoke( "bash", &test_args!({"command": command, "timeout_ms": 30_000}), ) .unwrap_err(); done.send((error, ts)).unwrap(); }); let mut socket = signal.wait(); cancel.cancel(); assert!(closed(&mut socket), "cancelled shell kept running"); let (error, ts) = finished.recv_timeout(Duration::from_secs(10)).unwrap(); assert_eq!(error.code(), "CANCELLED_UNKNOWN"); assert_eq!( std::fs::read_to_string(dir.join("made.txt")).unwrap(), "made" ); let entry = ts.session.active_branch().entries().last().unwrap(); let EntryContent::Meta { detail, .. } = ts.session.content(entry).unwrap() else { unreachable!() }; let call_id = serde_json::from_value(serde_json::to_value(&detail).unwrap()["call_id"].clone()) .unwrap(); assert_eq!( ts.session.mutation_state(call_id).unwrap(), MutationState::Unknown ); } #[test] fn failing_and_timing_out_commands_report_explicitly() { let dir = workdir("bash_failures"); let mut ts = ToolSession::new(&dir); let error = ts .invoke("bash", &test_args!({"command": "exit 3"})) .unwrap_err(); assert_eq!(error.code(), "BASH_EXIT"); let error = ts .invoke( "bash", &test_args!({"command": "sleep 5", "timeout_ms": 150}), ) .unwrap_err(); assert_eq!(error.code(), "BASH_TIMEOUT"); // Both failures stay durable evidence, recorded as failed results. let failed = ts .session .active_branch() .entries() .iter() .filter(|e| matches!(e.kind, EntryKind::ToolResult { ok: false, .. })) .count(); assert_eq!(failed, 2); } #[test] fn cancellation_stops_effects_before_they_start() { let dir = workdir("cancel_effects"); let mut ts = ToolSession::new(&dir); let cancel = ts.cancel_handle(); cancel.cancel(); let error = ts .invoke("write", &test_args!({"path": "never.txt", "content": "x"})) .unwrap_err(); assert_eq!(error.code(), "CANCELLED"); assert!(!dir.join("never.txt").exists()); // A refused call records nothing. assert!(ts.session.active_branch().entries().is_empty()); } #[test] fn cancelling_a_running_command_aborts_it() { let dir = workdir("cancel_running"); let mut ts = ToolSession::new(&dir); let cancel = ts.cancel_handle(); let signal = crate::process_signal::ProcessSignal::new(); let command = format!("{}; sleep 30", signal.raise()); let running = std::thread::spawn(move || { ts.invoke( "bash", &test_args!({"command": command, "timeout_ms": 30_000}), ) }); // synchronize: cancel once the command reports it runs, never after a guessed delay. let mut socket = signal.wait(); cancel.cancel(); // Before the join: a survivor would hold the pipes and stall it. assert!( crate::process_signal::closed(&mut socket), "command kept running" ); let error = running.join().unwrap().unwrap_err(); assert_eq!(error.code(), "CANCELLED_UNKNOWN"); } #[test] fn unrecordable_result_after_a_mutation_reports_the_mutation() { let dir = workdir("record_failed"); let session_path = dir.join("session.smh"); let mut cfg = Config::default_valid(); cfg.frame_bytes_max = 1024; let opened = crate::store::open_session(&session_path, cfg.clone()).unwrap(); let mut ts = ToolSession::with_session(&dir, opened.session, opened.writer).with_config(cfg); // The call entry fits, the 5 KiB result does not: a shell may have // mutated, but successful exit alone cannot prove it. let error = ts .invoke( "bash", &test_args!({"command": "printf made > actual.txt; printf 'x%.0s' $(seq 5000)"}), ) .unwrap_err(); assert_eq!(error.code(), "RECORD_FAILED"); assert!(matches!( error, SmithError::RecordFailed { mutation_state: MutationState::Unknown, .. } )); assert_eq!( std::fs::read_to_string(dir.join("actual.txt")).unwrap(), "made" ); let later = ts .invoke( "write", &test_args!({"path": "must-not-run.txt", "content": "x"}), ) .unwrap_err(); assert!(matches!( later, SmithError::RecordFailed { mutation_state: MutationState::Unknown, .. } )); assert!(!dir.join("must-not-run.txt").exists()); // Only the durably recorded call is part of the live session. let kinds: Vec = ts .session .active_branch() .entries() .iter() .map(|e| e.kind) .collect(); assert!(matches!(kinds.as_slice(), [EntryKind::ToolCall { .. }])); } #[test] fn write_requires_string_content_and_leaves_existing_file_untouched() { let dir = workdir("write_schema"); let target = dir.join("data.txt"); std::fs::write(&target, "original").unwrap(); let mut ts = ToolSession::new(&dir); let error = ts .invoke("write", &test_args!({"path": "data.txt"})) .unwrap_err(); assert_eq!(error.code(), "VALIDATION"); assert_eq!(std::fs::read_to_string(&target).unwrap(), "original"); let error = ts .invoke("write", &test_args!({"path": "data.txt", "content": 42})) .unwrap_err(); assert_eq!(error.code(), "VALIDATION"); assert_eq!(std::fs::read_to_string(&target).unwrap(), "original"); let _ = std::fs::remove_dir_all(&dir); } #[test] fn write_creates_missing_parents_and_leaves_no_temp_files() { let dir = workdir("write_parents"); let mut ts = ToolSession::new(&dir); ts.invoke( "write", &test_args!({"path": "a/b/c.txt", "content": "deep"}), ) .unwrap(); assert_eq!( std::fs::read_to_string(dir.join("a/b/c.txt")).unwrap(), "deep" ); let leftovers: Vec<_> = std::fs::read_dir(&dir) .unwrap() .filter_map(std::result::Result::ok) .flat_map(|e| { std::fs::read_dir(e.path()) .unwrap() .filter_map(std::result::Result::ok) .map(|x| x.file_name().to_string_lossy().into_owned()) .collect::>() }) .filter(|n| n.contains(".tmp-")) .collect(); assert!( leftovers.is_empty(), "temp files left behind: {leftovers:?}" ); let _ = std::fs::remove_dir_all(&dir); } #[test] fn edit_rejects_ambiguous_and_missing_matches_without_changes() { let dir = workdir("edit_amb"); let target = dir.join("f.txt"); std::fs::write(&target, "a a").unwrap(); let mut ts = ToolSession::new(&dir); let error = ts .invoke( "edit", &test_args!({"path": "f.txt", "old_string": "a", "new_string": "b"}), ) .unwrap_err(); assert_eq!(error.code(), "EDIT_AMBIGUOUS"); assert_eq!(std::fs::read_to_string(&target).unwrap(), "a a"); let error = ts .invoke( "edit", &test_args!({"path": "f.txt", "old_string": "NOT_PRESENT", "new_string": "b"}), ) .unwrap_err(); assert_eq!(error.code(), "EDIT_NOT_FOUND"); assert_eq!(std::fs::read_to_string(&target).unwrap(), "a a"); // Unambiguous edit succeeds. ts.invoke( "edit", &test_args!({"path": "f.txt", "old_string": "a a", "new_string": "b"}), ) .unwrap(); assert_eq!(std::fs::read_to_string(&target).unwrap(), "b"); let _ = std::fs::remove_dir_all(&dir); } #[test] fn read_supports_line_windows_byte_caps_and_binary_detection() { let dir = workdir("read_caps"); let mut body = String::new(); for i in 0..100 { use std::fmt::Write as _; let _ = writeln!(body, "line-{i}"); } std::fs::write(dir.join("lines.txt"), &body).unwrap(); let mut ts = ToolSession::new(&dir); let out = ts .invoke( "read", &test_args!({"path": "lines.txt", "offset": 2, "limit": 3}), ) .unwrap(); assert_eq!(out.output, "line-2\nline-3\nline-4\n"); let capped = ts .invoke("read", &test_args!({"path": "lines.txt", "max_bytes": 20})) .unwrap(); assert!(capped.output.len() <= 20); std::fs::write(dir.join("bin.dat"), [0x62, 0x00, 0x62]).unwrap(); let error = ts .invoke("read", &test_args!({"path": "bin.dat"})) .unwrap_err(); assert_eq!(error.code(), "BINARY_CONTENT"); let _ = std::fs::remove_dir_all(&dir); } #[test] fn ls_and_find_are_sorted_and_surface_errors() { let dir = workdir("ls_find"); for name in ["zeta", "alpha", "mid"] { std::fs::write(dir.join(name), "").unwrap(); } let mut ts = ToolSession::new(&dir); let out = ts.invoke("ls", &test_args!({})).unwrap(); assert_eq!(out.output, "alpha\nmid\nzeta"); let found = ts.invoke("find", &test_args!({"pattern": "a"})).unwrap(); assert_eq!(found.output, "alpha\nzeta"); let error = ts .invoke("find", &test_args!({"path": "missing-dir", "pattern": "x"})) .unwrap_err(); assert_eq!(error.code(), "FIND_ERROR"); let _ = std::fs::remove_dir_all(&dir); } #[test] fn grep_returns_bounded_matches() { let dir = workdir("grep"); std::fs::write( dir.join("log.txt"), "hit one\nmiss\nhit two\nmiss\nhit three\n", ) .unwrap(); let mut ts = ToolSession::new(&dir); let out = ts .invoke("grep", &test_args!({"path": "log.txt", "query": "hit"})) .unwrap(); assert_eq!(out.output, "hit one\nhit two\nhit three"); let _ = std::fs::remove_dir_all(&dir); } #[test] fn unregistered_tools_and_non_object_input_are_rejected() { let dir = workdir("registry"); let mut ts = ToolSession::new(&dir); let error = ts.invoke("rm", &test_args!({})).unwrap_err(); assert_eq!(error.code(), "TOOL_NOT_REGISTERED"); let error = ts.invoke("read", &test_args!("not-an-object")).unwrap_err(); assert_eq!(error.code(), "INVALID_INPUT"); let _ = std::fs::remove_dir_all(&dir); } fn assert_recorded_failure(ts: &ToolSession) { let entries = ts.session.active_branch().entries(); assert!(matches!( entries.iter().rev().nth(1).map(|entry| entry.kind), Some(EntryKind::ToolResult { ok: false, .. }) )); assert!(matches!( entries.last().map(|entry| entry.kind), Some(EntryKind::Meta { .. }) )); } fn cancel_at( dir: &Path, checkpoint: EffectCheckpoint, name: &str, input: serde_json::Value, ) -> (SmithError, ToolSession) { let mut ts = ToolSession::new(dir); ts.cancel_at_checkpoint(checkpoint); let error = ts .invoke(name, &ToolArguments::from_serializable(&input).unwrap()) .unwrap_err(); (error, ts) } fn timeout_at( dir: &Path, checkpoint: EffectCheckpoint, name: &str, input: serde_json::Value, ) -> (SmithError, ToolSession) { let mut ts = ToolSession::new(dir); ts.timeout_at_checkpoint(checkpoint); let error = ts .invoke(name, &ToolArguments::from_serializable(&input).unwrap()) .unwrap_err(); (error, ts) } #[test] fn cancellation_stops_file_effects_at_cooperative_boundaries() { let dir = workdir("file_cancellation"); std::fs::write(dir.join("source.txt"), "needle\nold\n").unwrap(); std::fs::create_dir_all(dir.join("nested")).unwrap(); std::fs::write(dir.join("nested/child.txt"), "needle\n").unwrap(); for (checkpoint, name, input) in [ ( EffectCheckpoint::ReadChunk, "read", serde_json::json!({"path": "source.txt"}), ), ( EffectCheckpoint::GrepLine, "grep", serde_json::json!({"path": "source.txt", "query": "needle"}), ), ( EffectCheckpoint::EditReadChunk, "edit", serde_json::json!({"path": "source.txt", "old_string": "old", "new_string": "new"}), ), ( EffectCheckpoint::TraversalEntry, "find", serde_json::json!({"pattern": "child"}), ), ( EffectCheckpoint::TraversalEntry, "grep", serde_json::json!({"path": "", "query": "needle"}), ), ] { let (error, ts) = cancel_at(&dir, checkpoint, name, input); assert_eq!(error.code(), "CANCELLED"); assert_recorded_failure(&ts); } assert_eq!( std::fs::read_to_string(dir.join("source.txt")).unwrap(), "needle\nold\n" ); } #[test] fn configured_timeout_stops_file_effects_at_cooperative_boundaries() { let dir = workdir("file_timeout_boundaries"); std::fs::write(dir.join("source.txt"), "needle\nold\n").unwrap(); std::fs::create_dir_all(dir.join("nested")).unwrap(); std::fs::write(dir.join("nested/child.txt"), "needle\n").unwrap(); for (checkpoint, name, input) in [ ( EffectCheckpoint::ReadChunk, "read", serde_json::json!({"path": "source.txt"}), ), ( EffectCheckpoint::GrepLine, "grep", serde_json::json!({"path": "source.txt", "query": "needle"}), ), ( EffectCheckpoint::EditReadChunk, "edit", serde_json::json!({"path": "source.txt", "old_string": "old", "new_string": "new"}), ), ( EffectCheckpoint::WriteChunk, "write", serde_json::json!({"path": "new.txt", "content": "new"}), ), ( EffectCheckpoint::TraversalEntry, "ls", serde_json::json!({}), ), ] { let (error, ts) = timeout_at(&dir, checkpoint, name, input); assert_eq!(error.code(), "TOOL_TIMEOUT"); assert_recorded_failure(&ts); } assert_eq!( std::fs::read_to_string(dir.join("source.txt")).unwrap(), "needle\nold\n" ); } #[test] fn cancellation_after_parent_creation_records_applied_directory_mutation() { let dir = workdir("write_parent_cancellation"); let (error, ts) = cancel_at( &dir, EffectCheckpoint::ParentCreated, "write", serde_json::json!({"path": "a/b/target.txt", "content": "new"}), ); assert_eq!(error.code(), "CANCELLED_APPLIED"); assert!(dir.join("a/b").is_dir()); assert!(!dir.join("a/b/target.txt").exists()); assert!(matches!( ts.session.content(ts.session.active_branch().entries().last().unwrap()).unwrap(), EntryContent::Meta { kind, detail } if kind == "tool-mutation" && serde_json::to_value(&detail).unwrap()["mutation_state"] == "applied" )); } #[test] fn deadline_after_parent_creation_records_applied_directory_mutation() { let dir = workdir("write_parent_deadline"); let (error, ts) = timeout_at( &dir, EffectCheckpoint::ParentCreated, "write", serde_json::json!({"path": "a/b/target.txt", "content": "new"}), ); assert_eq!(error.code(), "TOOL_TIMEOUT_APPLIED"); assert!(dir.join("a/b").is_dir()); assert!(!dir.join("a/b/target.txt").exists()); let entry = ts.session.active_branch().entries().last().unwrap(); assert!(matches!( ts.session.content(entry).unwrap(), EntryContent::Meta { detail, .. } if serde_json::to_value(&detail).unwrap()["mutation_state"] == "applied" )); } #[test] fn cancellation_before_or_after_atomic_publication_reports_truthfully() { let dir = workdir("write_commit_cancellation"); let target = dir.join("target.txt"); std::fs::write(&target, "old").unwrap(); let (error, ts) = cancel_at( &dir, EffectCheckpoint::BeforePublish, "write", serde_json::json!({"path": "target.txt", "content": "new"}), ); assert_eq!(error.code(), "CANCELLED"); assert_eq!(std::fs::read_to_string(&target).unwrap(), "old"); assert_recorded_failure(&ts); let (error, ts) = cancel_at( &dir, EffectCheckpoint::AfterPublish, "write", serde_json::json!({"path": "target.txt", "content": "new"}), ); assert_eq!(error.code(), "CANCELLED_APPLIED"); assert_eq!(std::fs::read_to_string(&target).unwrap(), "new"); assert_recorded_failure(&ts); } #[test] fn unrecordable_post_publication_cancellation_reports_applied_mutation() { let dir = workdir("record_applied_cancellation"); let target = dir.join("target.txt"); std::fs::write(&target, "old").unwrap(); let mut writes = 0usize; let mut ts = ToolSession::with_persist(&dir, Session::new(), move |_, _| { writes += 1; if writes == 1 { Ok(()) } else { Err(tool_error( smith::error::ToolCode::TestRecord, "result persistence rejected", )) } }); ts.cancel_at_checkpoint(EffectCheckpoint::AfterPublish); let error = ts .invoke( "write", &test_args!({"path": "target.txt", "content": "new"}), ) .unwrap_err(); assert!(matches!( error, SmithError::RecordFailed { mutation_state: MutationState::Applied, .. } )); assert_eq!(std::fs::read_to_string(&target).unwrap(), "new"); } #[test] fn configured_deadline_stops_every_file_effect_before_it_starts() { let dir = workdir("file_deadline"); std::fs::write(dir.join("source.txt"), "needle\nold\n").unwrap(); std::fs::create_dir_all(dir.join("nested")).unwrap(); std::fs::write(dir.join("nested/child.txt"), "needle\n").unwrap(); let mut config = Config::default_valid(); // Inject an already elapsed effect budget; no wall-clock wait. config.tool_timeout_ms = 0; let mut ts = ToolSession::new(&dir).with_config(config); for (name, input) in [ ("read", serde_json::json!({"path": "source.txt"})), ( "grep", serde_json::json!({"path": "source.txt", "query": "needle"}), ), ("grep", serde_json::json!({"path": "", "query": "needle"})), ("ls", serde_json::json!({})), ("find", serde_json::json!({"pattern": "child"})), ( "write", serde_json::json!({"path": "source.txt", "content": "new"}), ), ( "edit", serde_json::json!({"path": "source.txt", "old_string": "old", "new_string": "new"}), ), ] { let error = ts .invoke(name, &ToolArguments::from_serializable(&input).unwrap()) .unwrap_err(); assert_eq!(error.code(), "TOOL_TIMEOUT"); } assert_eq!( std::fs::read_to_string(dir.join("source.txt")).unwrap(), "needle\nold\n" ); assert_eq!( ts.session .active_branch() .entries() .iter() .filter(|entry| matches!(entry.kind, EntryKind::ToolResult { ok: false, .. })) .count(), 7 ); } #[test] fn plugin_http_intent_uses_the_active_tool_session_writer() { let dir = workdir("plugin_http_record"); let mut tools = ToolSession::new(&dir); let mut effects = ToolEffectContext::for_operation(&mut tools, "fixture"); effects .record_plugin_http(&smith::http::PluginHttpEffectRecord::Intent { plugin_id: "example:fixture".to_string(), call_id: ToolCallId::from_u128(7), origin: "https://api.example.test".to_string(), method: smith::http::HttpMethod::Post, headers: vec![smith::http::HttpHeader { name: "Authorization".to_string(), value: "".to_string(), }] .into(), request_bytes: 0, timeout_ms: 1, response_bytes_max: 1, }) .unwrap(); let entry = &tools.session.active_branch().entries()[0]; match tools.session.content(entry).unwrap() { EntryContent::Meta { kind, .. } => assert_eq!(kind, PLUGIN_HTTP_KIND), other => panic!("unexpected {other:?}"), } let _ = std::fs::remove_dir_all(&dir); } #[test] fn failed_effects_are_recorded_as_failures() { let dir = workdir("record_fail"); let mut ts = ToolSession::new(&dir); let res = ts.invoke("read", &test_args!({"path": "nope.txt"})); assert!(res.is_err()); // Call, failed result, and typed mutation completion are recorded. assert_eq!(ts.session.active_branch().entries().len(), 3); let last = &ts.session.active_branch().entries()[1]; match ts.session.content(last).unwrap() { EntryContent::ToolResult { ok, output, .. } => { assert!(!ok); assert!(output.contains("READ_ERROR")); } other => panic!("unexpected {other:?}"), } let _ = std::fs::remove_dir_all(&dir); } }