//! 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> { 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> { 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 { 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, ) -> Result { 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(); } }