---
id: SMH-PLAN-PLUG0001
type: plan
title: "Sandboxed Plugin Harness"
spec: SMH-SPEC-SPEC0001
status: approved
depends_on: []
research: [SMH-RESEARCH-WASM0001]
---

# Sandboxed Plugin Harness

## Outcome

Provider and OAuth plugins run as unprivileged wasm components over core primitives.
The host owns one typed effect surface; built-ins and user plugins share it with no privileged path.

## Scope

Host primitives extraction, the minimal wasm plugin system, plugin scaffolding, and plugin tooling.
Provider and OAuth plugin delivery lives in the provider-plugins plan.

## Behaviors

Ordered by delivery value.

1. **Typed HTTP effect**: provider network runs through one host-owned typed HTTP client with bounded bodies, cancellation, and durable recorded effects; `smith-ai` transport consumes it before any plugin exists.
2. **Core shrink**: vendor wire decoders, vendor catalogs, and conformance fixtures leave the core path; `smith-ai` keeps auth, mux, and model types.
3. **Wasm host**: wasmtime engine with deterministic settings, fuel and memory ceilings, artifact validation against the pinned world, and no ambient WASI.
4. **Trust and discovery**: project packages stay undiscovered until trust resolves; manifests declare artifact, world version, and capabilities; grants resolve at trust or install time.
5. **Transactional load**: load, validate, instantiate, and register one component atomically; failure leaves no registrations.
6. **Capability effects**: guests reach host effects only through granted imports — HTTP via net-scope, credential exchange via secret-proxy, logging; ungranted imports fail instantiation.
7. **Registration surface**: plugins register provider streams, credential sources, and model contributions; the host pulls stream chunks by explicit request.
8. **Generations and reload**: one complete generation publishes atomically; provider rounds pin one generation; reload keeps session continuity.
9. **Scaffolding**: a workspace-pinned WIT copy is the single contract; `plugins/` members bind with raw `wit-bindgen` and build components under the same gates; dev-links load fresh artifacts from the target directory; no smith-authored SDK ships before 1.0.
10. **Embedded built-ins**: release binaries embed system plugin artifacts and load them through the same loader, sandbox, and effect grants as user plugins.
11. **Tooling**: `smith plugin init|build|check|dev|test` scaffold, produce artifacts, lint worlds and grants, hot-swap via dev-links, and run hosted tests with mocked capabilities.

## Behavior structure

```mermaid
flowchart LR
  P1["Typed HTTP effect"] --> P2["Core shrink"]
  P2 --> H["Wasm host"]
  H --> T["Trust + discovery"]
  T --> L["Transactional load"]
  L --> E["Capability effects"]
  E --> R["Registration surface"]
  R --> G["Generations + reload"]
  G --> S["Scaffolding"]
  S --> B["Embedded built-ins"]
  B --> X["Tooling"]
  X --> PROV["Provider plugins plan"]
```

## Interfaces

- `smith-harness::http`: typed HTTP effect with durable records.
- `smith-harness::wasm`: engine, validation, instantiation, capabilities, ceilings.
- `smith-harness::trust`, `smith-harness::plugins`: discovery, binding, registration, reload.
- `smith-plugin-sdk`: pinned WIT, guest types, effect wrappers.
- `plugins/*`: system plugin crates.
- `smith:plugin` WIT world: the only plugin path to host effects.

## Verification

- Provider network calls through the typed effect are replay-visible and cancellable.
- Ambient WASI imports fail validation; ungranted capability imports fail instantiation with a named grant.
- Failed load or reload leaves no registrations; reload preserves session continuity.
- One generation serves a provider round end to end.
- `plugins/` members pass the same fmt, clippy, test, and arch gates as core crates.
- Raw `wit-bindgen` guests build and load with no smith-authored SDK in the tree.
- `cargo x dev` loads a freshly built component through a dev-link without manual steps.
- Embedded built-in artifacts pass the same validation as installed plugins.
- Repeated runs of one artifact with recorded host inputs produce identical outputs.

## Stop conditions

- An effect can begin before durable intent publication.
- The engine cannot enforce deterministic settings without unacceptable latency.
- A built-in requires an effect absent from the public world.
- Trust must execute or enumerate project code before deciding trust.