repositories / smith
smith
There are many coding harnesses - but this one is fast
owned by admin
smith-core/src/tools.rs
Raw//! 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<u8>,
bytes_max: usize,
) -> std::io::Result<bool> {
#[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<String, ToolMetadata>,
/// 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<ToolMetadata> = 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<PersistCompletion>,
}
/// 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<ToolComponentProvenance>,
/// Exact advertised definitions and their owner generation.
pub tools: Vec<ToolLoadoutTool>,
}
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<ToolMetadata>,
/// Every registered definition eligible for host-owned policy resolution.
///
/// This can include active hidden tools; provider requests receive only `tools`.
pub registered_tools: Vec<ToolMetadata>,
/// 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<ToolDispatcherSnapshot> {
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<smith::lifecycle::LifecycleBatch> {
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<smith::lifecycle::LifecycleBatch> {
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<String>;
}
/// 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<WorkspaceRoot>,
workspace_only: bool,
next_index: u16,
active: bool,
mutation_state: MutationState,
}
#[derive(Clone, Copy)]
struct EffectIdentity {
id: smith::id::EntryId,
index: u16,
causal: Option<crate::metadata::NestedCausality>,
}
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<u64>,
}
/// 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<InvocationAllocationReport>;
}
struct EffectScope<'a> {
cause: Option<InvocationCause>,
lifecycle_root: Option<smith::id::EntryId>,
redact: &'a dyn Fn(&str) -> String,
component: Option<ToolComponentProvenance>,
pending: Option<EffectIdentity>,
children: Vec<ChildInvocation>,
stop: Option<InvocationStop>,
allocation: Option<InvocationAllocationReport>,
allocation_observer: Option<Box<dyn InvocationAllocationObserver>>,
}
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<WorkspaceRoot>,
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<String>,
) -> Result<String> {
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<InvocationStop> {
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<dyn InvocationAllocationObserver>,
) -> Option<Box<dyn InvocationAllocationObserver>> {
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<InvocationAllocationReport> {
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<ToolCallId> {
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<smith::id::EntryId> {
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<ToolComponentProvenance>,
run: impl FnOnce(&mut Self) -> Result<String>,
) -> Result<String> {
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<String>,
) -> Result<String> {
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<smith::id::EntryId> {
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<String>) -> Result<String> {
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<String>) -> Result<String> {
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<T: serde::Serialize>(
&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<String> {
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<String> {
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<PersistEntry>),
}
/// 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<CompletionBoundary>,
/// 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<PathBuf, FileVersion>,
/// Completion persistence failed; no further host effects may begin.
recording_failed: bool,
dispatcher: Option<Box<dyn ToolDispatcher>>,
dynamic_tool_names: Vec<String>,
advertised_tools: Arc<[ToolMetadata]>,
request_policy: Option<Box<[(String, ToolPolicyState)]>>,
loadout_provenance: Option<ToolLoadoutProvenance>,
#[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<Self> {
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<PathBuf>) -> 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<PathBuf>,
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<PathBuf>,
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<dyn ToolDispatcher>) {
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<smith::lifecycle::LifecycleBatch> {
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<ToolOutcome> {
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<ToolOutcome> {
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<ToolOutcome> {
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<String, SmithError> {
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<smith::id::EntryId> {
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<EntryContentRef<'a>>) -> Result<Entry> {
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<InvocationAllocationReport>,
/// 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<StructuredData> {
encode_metadata(&ToolMutationMetadata::new(call_id, mutation_state))
}
fn tool_error(code: smith::error::ToolCode, message: impl Into<String>) -> 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<Option<&'a str>> {
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<Option<u64>> {
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<String, SmithError>) -> 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<EffectCheckpoint>,
timeout_at: Option<EffectCheckpoint>,
}
/// 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<PathBuf, FileVersion>,
workspace: Option<&WorkspaceRoot>,
#[cfg(test)] test_effect_control: TestEffectControl,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
config: &Config,
control: &EffectControl<'_>,
workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
_config: &Config,
_control: &EffectControl<'_>,
_workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
control: &EffectControl<'_>,
workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
control: &EffectControl<'_>,
workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
control: &EffectControl<'_>,
workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
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<usize>,
config: &Config,
control: &EffectControl<'_>,
code: smith::error::ToolCode,
) -> std::result::Result<Vec<String>, 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<usize>,
config: &Config,
control: &EffectControl<'_>,
code: smith::error::ToolCode,
ignores: &mut Vec<crate::filters::DirectoryIgnore>,
entries: &mut Vec<String>,
) -> 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<crate::filters::DirectoryIgnore, SmithError> {
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<String, SmithError> {
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("<truncated>".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<String, SmithError> {
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<Vec<(usize, String)>, 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<PathBuf, FileVersion>,
control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>,
control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
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<PathBuf, FileVersion>) {
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<usize>, 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<usize>,
config: &Config,
control: &EffectControl<'_>,
code: smith::error::ToolCode,
) -> std::result::Result<Vec<String>, 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<String, SmithError> {
let mut matches: Vec<String> = 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("<truncated>".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<String, SmithError> {
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<String, SmithError> {
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<String, SmithError> {
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<u8> = 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<String, SmithError> {
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<Vec<u8>, 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<Vec<u8>, 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<Vec<u8>, 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<String>, 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<truncated>");
}
out
}
/// Stream matching lines with bounded memory and result count.
fn grep_bounded(
path: &Path,
query: &str,
control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
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<String, SmithError> {
control.checkpoint(EffectCheckpoint::GrepLine, false)?;
let mut reader = BufReader::with_capacity(64 * 1024, file);
let mut matches: Vec<String> = 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("<truncated>".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("<truncated>".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<crate::tools::ToolDispatcherSnapshot> {
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<String> {
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<String> {
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<String> {
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<ToolDispatcherSnapshot> {
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<String> {
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::<ToolPolicyState>(), 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::<String>();
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("<truncated>".to_string()))
.collect::<Vec<_>>()
.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<EntryKind> = 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::<Vec<_>>()
})
.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: "<redacted>".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);
}
}