Luigit
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();
    }
}