repositories / smith
smith
There are many coding harnesses - but this one is fast
owned by admin
smith-harness/src/wasm/lifecycle.rs
Raw//! Optional sandbox decisions and generation-local failure isolation (SMH-SPEC-PLUG0001).
use super::{
PluginInstance, PluginRegistry, Result, composition::CompositionGrants, kernel::Watchdog,
plugin_fault,
};
use smith::lifecycle::{
ACTION_ITEMS_MAX, Boundary, ContextEdit, ContextReplacement, DiagnosticCode, HANDLER_ITEMS_MAX,
HANDLER_NAME_BYTES_MAX, LifecycleAction as Action, LifecycleBatch, LifecycleDiagnostic,
LifecycleEvent, ToolAvailability,
};
use smith::tool::CancelHandle;
use std::time::{Duration, Instant};
#[allow(missing_docs, reason = "generated lifecycle component bindings")]
mod bindings {
wasmtime::component::bindgen!({ path: "../wit", inline: "package smith:lifecycle-host; world lifecycle-host { export smith:plugin/lifecycle@0.1.0; }" });
}
use bindings::exports::smith::plugin::lifecycle as guest;
pub(super) struct Handler {
declaration: guest::HandlerDeclaration,
disabled: bool,
}
impl PluginInstance {
fn call_lifecycle(
&mut self,
name: &str,
event: &LifecycleEvent,
cancel: &CancelHandle,
fuel: &mut u64,
deadline: Instant,
effects: Option<&mut smith_core::tools::ToolEffectContext<'_>>,
) -> Result<Vec<guest::Action>> {
let watchdog = Watchdog::boundary(self.store.engine().clone(), cancel.clone(), deadline)?;
self.store
.set_fuel(*fuel)
.map_err(|_| plugin_fault("lifecycle fuel unavailable"))?;
let handle = cancel.clone();
self.store.set_epoch_deadline(1);
self.store.epoch_deadline_callback(move |_| {
if handle.is_cancelled() || Instant::now() >= deadline {
return Err(wasmtime::Error::msg("lifecycle interrupted"));
}
Ok(wasmtime::UpdateDeadline::Continue(1))
});
let enabled = self.store.data().effects_enabled;
let has_effects = effects.is_some();
let _attachment = match effects {
Some(effects) => Some(super::attach_workspace_effects(&self.store, effects)?),
None => None,
};
self.store.data_mut().effects_enabled = has_effects;
self.store.data_mut().lifecycle_deadline = Some(deadline);
// Redaction values remain host-only; opaque handles from a prior model call
// confer no credential authority on a lifecycle handler.
let caller_secrets = std::mem::take(&mut self.store.data_mut().resolved_secret_refs);
let result = (|| {
let bindings = bindings::LifecycleHost::new(&mut self.store, &self.raw)
.map_err(|_| plugin_fault("lifecycle export disappeared"))?;
bindings
.smith_plugin_lifecycle()
.call_handle(
&mut self.store,
name,
guest::Event {
root_entry_id: identity(event.root_entry_id.as_u128()),
boundary: boundary(event.boundary),
round_index: event.round_index,
last_stop: stop_reason(event.last_stop),
continuation_eligible: event.continuation_eligible,
},
)
.map_err(|_| plugin_fault("lifecycle handler trapped"))?
.map_err(|_| plugin_fault("lifecycle handler returned failure"))
})();
self.store.data_mut().resolved_secret_refs = caller_secrets;
self.store.data_mut().effects_enabled = enabled;
self.store.data_mut().lifecycle_deadline = None;
self.store.data_mut().lifecycle_allocation_bytes = 0;
*fuel = self.store.get_fuel().unwrap_or(0);
self.store.set_epoch_deadline(u64::MAX / 2);
drop(watchdog);
result
}
pub(super) fn declare_lifecycle(&mut self) -> Result<Vec<Handler>> {
if self
.raw
.get_export_index(&mut self.store, None, "smith:plugin/lifecycle@0.1.0")
.is_none()
{
return Ok(Vec::new());
}
let bindings = bindings::LifecycleHost::new(&mut self.store, &self.raw)
.map_err(|_| plugin_fault("invalid lifecycle export"))?;
super::refill_fuel(&mut self.store)?;
let declarations = bindings
.smith_plugin_lifecycle()
.call_declare_handlers(&mut self.store)
.map_err(|_| plugin_fault("lifecycle declaration failed"))?;
if declarations.len() > HANDLER_ITEMS_MAX {
return Err(plugin_fault("lifecycle handler count exceeds 32"));
}
for (index, declaration) in declarations.iter().enumerate() {
if declaration.boundary == guest::Boundary::Settled && declaration.required_decision {
return Err(plugin_fault(
"settled notification cannot require a decision",
));
}
if declaration.name.is_empty()
|| declaration.name.len() > HANDLER_NAME_BYTES_MAX
|| !declaration
.name
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'-' || byte == b'_')
|| declarations[..index]
.iter()
.any(|prior| prior.name == declaration.name)
{
return Err(plugin_fault(
"lifecycle handler identity invalid or duplicated",
));
}
}
Ok(declarations
.into_iter()
.map(|declaration| Handler {
declaration,
disabled: false,
})
.collect())
}
}
const fn boundary(value: Boundary) -> guest::Boundary {
match value {
Boundary::TurnComplete => guest::Boundary::TurnComplete,
Boundary::PreSettlement => guest::Boundary::PreSettlement,
Boundary::Settled => guest::Boundary::Settled,
}
}
const fn stop_reason(value: smith::StopReason) -> guest::StopReason {
match value {
smith::StopReason::EndTurn => guest::StopReason::EndTurn,
smith::StopReason::ToolUse => guest::StopReason::ToolUse,
smith::StopReason::Limit => guest::StopReason::Limit,
smith::StopReason::Abort => guest::StopReason::Abort,
smith::StopReason::StopSequence => guest::StopReason::StopSequence,
smith::StopReason::Refusal => guest::StopReason::Refusal,
smith::StopReason::ContentFilter => guest::StopReason::ContentFilter,
}
}
const fn identity(value: u128) -> (u64, u64) {
let bytes = value.to_le_bytes();
let (halves, _) = bytes.as_chunks::<8>();
(u64::from_le_bytes(halves[0]), u64::from_le_bytes(halves[1]))
}
fn number((low, high): (u64, u64)) -> u128 {
u128::from(low) | (u128::from(high) << 64)
}
fn convert(action: guest::Action) -> Action {
match action {
guest::Action::Cancel => Action::Cancel,
guest::Action::EnsureContinuation => Action::EnsureContinuation,
guest::Action::SetModel(value) => Action::SetModel(value),
guest::Action::SetProvider(value) => Action::SetProvider(value),
guest::Action::SetPrompt(value) => Action::SetPrompt(value),
guest::Action::IncludeUsage(value) => Action::IncludeUsage(value),
guest::Action::SetToolPolicy(changes) => Action::SetToolPolicy(
changes
.into_iter()
.map(|change| {
(
change.name,
match change.availability {
guest::Availability::Advertised => ToolAvailability::Advertised,
guest::Availability::Hidden => ToolAvailability::Hidden,
guest::Availability::Disabled => ToolAvailability::Disabled,
},
)
})
.collect(),
),
guest::Action::EditContext(edits) => Action::EditContext(
edits
.into_iter()
.map(|edit| ContextEdit {
target: smith::EntryId::from_u128(number(edit.target)),
replacement: edit.replacement.map(|replacement| match replacement {
guest::Replacement::Text(value) => ContextReplacement::Text(value),
guest::Replacement::AssistantText(value) => {
ContextReplacement::AssistantText(value)
}
guest::Replacement::ToolResultOutput((call_id, output)) => {
ContextReplacement::ToolResultOutput {
call_id: smith::ToolCallId::from_u128(number(call_id)),
output,
}
}
}),
})
.collect(),
),
}
}
impl PluginRegistry {
pub(super) fn has_lifecycle_handlers(&self, event_boundary: Boundary) -> bool {
self.generations.iter().any(|generation| {
generation.lifecycle_handlers.iter().any(|handler| {
!handler.disabled && handler.declaration.boundary == boundary(event_boundary)
})
})
}
pub(super) fn lifecycle(
&mut self,
event: &LifecycleEvent,
cancel: &CancelHandle,
grants: &CompositionGrants,
) -> Result<LifecycleBatch> {
self.lifecycle_effects(event, cancel, grants, None, &[], None)
}
#[expect(
clippy::too_many_lines,
reason = "one ordered boundary owns cumulative budgets and failure-isolated staged actions"
)]
pub(super) fn lifecycle_effects(
&mut self,
event: &LifecycleEvent,
cancel: &CancelHandle,
grants: &CompositionGrants,
mut effects: Option<&mut smith_core::tools::ToolEffectContext<'_>>,
redaction_values: &[String],
deadline: Option<Instant>,
) -> Result<LifecycleBatch> {
let mut batch = LifecycleBatch::default();
if !self.has_lifecycle_handlers(event.boundary) {
return Ok(batch);
}
let allocation = smith_alloc::AllocationGroup::current()
.map_or_else(smith_alloc::AllocationGroup::new, Ok)
.map_err(|_| plugin_fault("lifecycle allocation observer unavailable"))?;
let _allocation = allocation.enter();
let limits = grants.limits();
let deadline = deadline
.unwrap_or_else(|| Instant::now() + Duration::from_nanos(limits.timeout_nanoseconds));
let mut fuel = limits.fuel;
let mut memory_bytes = 0usize;
let mut table_elements = 0usize;
let mut conversion_bytes = 0usize;
let mut output_bytes = 0usize;
let mut calls = 0u16;
for generation in &mut self.generations {
let mut charged = false;
for handler in &mut generation.lifecycle_handlers {
if handler.disabled || handler.declaration.boundary != boundary(event.boundary) {
continue;
}
if cancel.is_cancelled() {
return Err(smith::SmithError::Cancelled);
}
let instance = &mut generation.instance;
if !charged {
memory_bytes = memory_bytes.saturating_add(instance.store.data().memory_bytes);
table_elements =
table_elements.saturating_add(instance.store.data().table_elements);
charged = true;
}
calls = calls.saturating_add(1);
conversion_bytes =
conversion_bytes.saturating_add(super::composition::LIFT_BYTES_MAX);
batch.allocated_bytes = allocation
.allocated()
.map_err(|_| plugin_fault("lifecycle allocation observation failed"))?
.bytes;
let mut budget_exceeded = batch.allocated_bytes > limits.allocation_bytes
|| fuel == 0
|| Instant::now() >= deadline
|| memory_bytes > limits.memory_bytes
|| table_elements > limits.table_elements
|| calls > limits.calls
|| conversion_bytes > limits.conversion_bytes
|| output_bytes > limits.output_bytes;
if let Some(effects) = effects.as_deref_mut() {
effects.begin_lifecycle_invocation(
event,
&handler.declaration.name,
smith_core::tools::ToolComponentProvenance {
source_id: generation.manifest.id().into(),
manifest_sha256: generation.manifest_sha256.clone(),
component_sha256: generation.component_sha256.clone(),
},
)?;
}
batch.allocated_bytes = allocation
.allocated()
.map_err(|_| plugin_fault("lifecycle admission allocation observation failed"))?
.bytes;
budget_exceeded |=
batch.allocated_bytes > limits.allocation_bytes || Instant::now() >= deadline;
instance.store.data_mut().lifecycle_allocation_bytes = limits.allocation_bytes;
let result = if budget_exceeded {
Err(plugin_fault("shared lifecycle boundary budget exhausted"))
} else {
let secret_count = instance.store.data().secret_values.len();
instance
.store
.data_mut()
.secret_values
.extend_from_slice(redaction_values);
let result = instance.call_lifecycle(
&handler.declaration.name,
event,
cancel,
&mut fuel,
deadline,
effects.as_deref_mut(),
);
instance
.store
.data_mut()
.secret_values
.truncate(secret_count);
budget_exceeded |= fuel == 0 || Instant::now() >= deadline;
result
};
let requests_cancel = event.boundary != Boundary::Settled
&& result.as_ref().is_ok_and(|actions| {
actions
.iter()
.any(|action| matches!(action, guest::Action::Cancel))
});
let result = result.and_then(|actions| {
if actions.len() > ACTION_ITEMS_MAX {
return Err(plugin_fault("lifecycle action count exceeded"));
}
let actions: Vec<_> = actions.into_iter().map(convert).collect();
smith::lifecycle::validate_action_bounds(&actions)?;
let bytes = serde_json::to_vec(&actions)
.map_err(|_| plugin_fault("lifecycle output conversion failed"))?
.len();
output_bytes = output_bytes.saturating_add(bytes);
budget_exceeded |= output_bytes > limits.output_bytes;
if budget_exceeded || batch.actions.len() + actions.len() > ACTION_ITEMS_MAX {
return Err(plugin_fault("shared lifecycle output budget exhausted"));
}
Ok(actions)
});
batch.allocated_bytes = allocation
.allocated()
.map_err(|_| plugin_fault("lifecycle allocation observation failed"))?
.bytes;
// Allocation is soft within a host call, enforced at the next boundary.
// Exhausted handlers cannot publish actions or enter another guest.
budget_exceeded |= batch.allocated_bytes > limits.allocation_bytes;
if let Some(effects) = effects.as_deref_mut() {
let output = match &result {
Ok(actions) => serde_json::to_string(actions)
.map_err(|_| plugin_fault("lifecycle outcome encoding failed"))?,
Err(_) => "handler-failed".into(),
};
effects
.finish_lifecycle_invocation(result.is_ok() && !budget_exceeded, &output)?;
}
batch.allocated_bytes = allocation
.allocated()
.map_err(|_| plugin_fault("lifecycle cleanup allocation observation failed"))?
.bytes;
budget_exceeded |= batch.allocated_bytes > limits.allocation_bytes;
if cancel.is_cancelled() {
return Err(smith::SmithError::Cancelled);
}
if requests_cancel && !budget_exceeded {
cancel.cancel();
}
match result {
Ok(actions)
if !budget_exceeded
&& event.boundary == Boundary::Settled
&& !actions.is_empty() =>
{
batch.diagnostics.push(LifecycleDiagnostic {
component: generation.manifest.id().into(),
handler: handler.declaration.name.clone(),
code: DiagnosticCode::BatchRejected,
});
}
Ok(actions) if !budget_exceeded => {
batch.required_decision |= handler.declaration.required_decision;
batch.actions.extend(actions);
}
_ => {
handler.disabled = true;
batch.diagnostics.push(LifecycleDiagnostic {
component: generation.manifest.id().into(),
handler: handler.declaration.name.clone(),
code: if handler.declaration.required_decision {
DiagnosticCode::RequiredDecisionFailed
} else if budget_exceeded {
DiagnosticCode::BudgetExceeded
} else {
DiagnosticCode::HandlerFailed
},
});
if handler.declaration.required_decision {
batch.actions.clear();
batch.required_failure = true;
return Ok(batch);
}
}
}
if cancel.is_cancelled() {
return Err(smith::SmithError::Cancelled);
}
}
}
Ok(batch)
}
}
#[cfg(test)]
mod tests {
//! SMH-SPEC-PLUG0001: actual cumulative fuel and host allocation observations.
use super::super::{PluginEngine, PluginGeneration, PluginManifest};
use super::*;
fn generation(engine: &PluginEngine, artifact: &std::path::Path, id: &str) -> PluginGeneration {
let manifest = PluginManifest::parse(&format!(
"id \"{id}\"\nversion \"0.1.0\"\nworld \"0.1.0\"\nartifact \"fixture.wasm\"\n"
))
.unwrap();
PluginGeneration::load(engine, manifest, artifact, &[]).unwrap()
}
fn event() -> LifecycleEvent {
LifecycleEvent {
root_entry_id: smith::EntryId::from_u128(1),
boundary: Boundary::TurnComplete,
round_index: 0,
last_stop: smith::StopReason::EndTurn,
continuation_eligible: true,
}
}
#[test]
fn second_component_receives_only_unspent_fuel_and_host_allocations_are_actual() {
let directory = std::env::temp_dir().join(format!(
"smith-lifecycle-shared-fuel-{}",
std::process::id()
));
std::fs::create_dir_all(&directory).unwrap();
let source = include_str!("../../tests/fixtures/lifecycle.rs")
.replace("path: \"wit\"", "path: \"WIT_PATH\"");
let artifact = super::super::nested_tests::fixture_component_source(&directory, &source);
let engine = PluginEngine::new().unwrap();
let grants = CompositionGrants::default();
let mut registry = PluginRegistry::new();
registry
.publish_all(vec![generation(&engine, &artifact, "example:first")])
.unwrap();
let first = registry
.lifecycle(&event(), &CancelHandle::new(), &grants)
.unwrap();
assert_eq!(first.actions, vec![Action::EnsureContinuation]);
let spent =
grants.limits().fuel - registry.generations[0].instance.store.get_fuel().unwrap();
assert!(spent > 0);
registry
.publish_all(vec![
generation(&engine, &artifact, "example:first"),
generation(&engine, &artifact, "example:second"),
])
.unwrap();
let limits = CompositionGrants::default()
.with_execution_limits(spent * 2 - 1, Duration::from_secs(30))
.unwrap();
let batch = registry
.lifecycle(&event(), &CancelHandle::new(), &limits)
.unwrap();
assert_eq!(batch.actions, vec![Action::EnsureContinuation]);
assert_eq!(batch.diagnostics.len(), 1);
assert_eq!(batch.diagnostics[0].component, "example:second");
assert_eq!(batch.diagnostics[0].code, DiagnosticCode::BudgetExceeded);
registry
.publish_all(vec![generation(&engine, &artifact, "example:first")])
.unwrap();
let limits = CompositionGrants::default()
.with_host_allocation_limit(1)
.unwrap();
let batch = registry
.lifecycle(&event(), &CancelHandle::new(), &limits)
.unwrap();
assert!(batch.allocated_bytes > 1);
assert!(batch.actions.is_empty());
assert_eq!(batch.diagnostics[0].code, DiagnosticCode::BudgetExceeded);
std::fs::remove_dir_all(directory).unwrap();
}
}