# The coder plugin demo, and the shape it recommends

2026-08-24. Branch `coder-plugin-demo`. This is the one-off working demo

ahead of the plugin walking skeleton (#26): a WASM plugin loads into

`openagents coder`, its digest is verified before load, and a live model

calls it as a tool in the chat. The contract it follows is

`OpenAgentsInc/openagents.com` docs

`2026-08-24-triage-and-plugin-model-assessment.md` sections 4.2–4.4.

## What was built

- `plugins/word-stats/` — a guest plugin in dependency-free Rust, compiled

  to `wasm32-unknown-unknown` (rustc 1.94.1), with the 52 KB artifact and

  its SHA-256 checked in beside the source so the demo runs without a Rust

  toolchain. It computes text statistics: bytes, chars, words, lines,

  longest word, most frequent word. Pure computation — the module imports

  nothing.

- `plugins/word-stats/manifest.json` — identity (name, version, author),

  the artifact path and `sha256:` digest pin, the ABI export names, typed

  input and output JSON Schemas, capability declarations (empty mounts,

  empty hosts, a 2000 ms timeout, a memory figure), and reserved

  `price_msats` / `license` fields per the assessment.

- `packages/openagents-cli/src/coder-plugins.ts` — the host. Plain

  `WebAssembly` API, no new dependencies. Load: parse and validate the

  manifest, refuse non-empty capability declarations, read the artifact,

  compare SHA-256 to the pin, compile, refuse any module whose import list

  is not empty, require the declared exports. Invoke: one

  `node:worker_threads` worker per call, terminated at the manifest's

  timeout. Every failure is a typed refusal `{code, reason}` returned as a

  value, never thrown.

- `/plugin load <manifest>` in both the interface and `--plain`. A loaded

  plugin materializes one session-scoped `CoderTool`: the manifest's name

  is the tool name, its description is the tool description (suffixed

  "experimental, session-only, sandboxed"), its input schema is the tool

  parameters, and `run` marshals the JSON arguments to a packet and the

  output packet back to text.

- `scripts/plugin-demo.mjs` — the happy path and all three refusal paths

  from the shell, and `test/coder-plugins.test.ts` — nine tests including a

  `--plain` transcript driven through `CoderSession` by a scripted source.

Proved live: `printf '/plugin load ../../plugins/word-stats/manifest.json\n

<prompt>\n' | node dist/main.js coder --plain` — the thread model called

`word_stats`, the call and its `→ ok` rendered in the transcript, and the

reply was built from the plugin's output.

## ABI and memory mechanics

The packet contract is `handle_packet(bytes) -> bytes`, and bytes cross the

boundary through guest linear memory:

1. The host calls the guest's exported allocator `packet_alloc(len) -> ptr`

   and writes the input packet — the UTF-8 JSON encoding of the tool

   arguments — into guest memory at `ptr`.

2. The host calls `handle_packet(ptr, len)`. The guest allocates its output

   inside its own memory and returns one `u64` packing the location:

   `(out_ptr << 32) | out_len`. (WASM `i64` returns surface as `BigInt` in

   Node; the worker unpacks with shifts.)

3. The host re-reads `memory.buffer` after the call — the guest may have

   grown memory, which detaches earlier views — bounds-checks

   `out_ptr + out_len`, and copies the output packet out.

The output buffer is deliberately leaked by the guest: the instance lives

for exactly one call, so a `packet_free` export would be ceremony. That

choice is coupled to one-worker-per-invocation, which also buys the two

properties the contract cares about: the timeout is enforceable (a WASM

call is synchronous and cannot be preempted in-process, so the host

terminates the worker), and no state survives between calls.

Refusals are typed on both sides. The host refuses with a closed code set

(`manifest_invalid`, `digest_mismatch`, `capabilities_unsupported`,

`imports_declared`, `exports_missing`, `not_wasm`, `timeout`, `trap`,

`bad_packet`); the guest returns `{"refusal": {code, reason}}` as its

output packet. Both reach the model as text it can act on.

## What the skeleton (#26) should keep

- **The manifest as the whole declaration.** Digest pin checked before

  compile; import list checked before instantiate; capabilities are

  declared-and-enforced or refused, never ignored. The demo's

  `capabilities_unsupported` refusal for any non-empty mounts/hosts is the

  right default until host imports exist.

- **Refusals as values.** `LoadedPlugin | PluginRefusal` and

  `Uint8Array | PluginRefusal` compose; exceptions do not. The tool layer

  turning a refusal into one sentence is what let the live model handle the

  demo gracefully.

- **Termination as the timeout mechanism.** Whatever engine the skeleton

  adopts, the bound must survive a guest that never returns. Worker

  isolation (or engine epochs/fuel) is load-bearing; an in-process `await`

  with a timer is not enforcement.

- **The tool-materialization seam.** `pluginTool(loaded): CoderTool` is

  exactly the `CoderTool` shape the session already declares, so plugins,

  skills, shell, and delegate all ride one declaration path and the

  `/plugin load` wiring is ~20 lines in `cli.ts`. Tier-3 session loading

  per assessment 4.4 falls out of this for free.

- **Session-scoped registration with replace-by-name**, so iterating on a

  plugin re-declares rather than duplicates.

## What the skeleton should replace

- **The hand-rolled guest.** The demo guest parses JSON with a scanner

  because it ships dependency-free. The skeleton's owned Rust PDK should

  own the ABI: serde for packets, a `Refusal` enum, a `#[plugin_fn]`-style

  macro over `packet_alloc`/`handle_packet`, and the pack/unpack of the

  return word. Guest authors should never see a pointer.

- **The raw `WebAssembly` host, behind the engine abstraction.** The

  bare API has no fuel metering, no memory ceiling at instantiation (the

  manifest's `memory_max_mib` is declared but unenforced here), and no

  WASI. The issue's engine-abstraction constraint is right: keep the

  demo's *contract* (load → verify → instantiate → invoke-with-bound →

  bytes-or-refusal) as the interface and let wasmtime/Extism-derived code

  implement it. The worker-per-call model can stay as the Node fallback

  engine.

- **Per-call worker spawn, eventually.** ~10–30 ms per invocation is fine

  for a demo; a pooled worker holding a compiled `WebAssembly.Module`

  (modules are transferable) is the obvious next step if plugins get hot.

- **Schema validation.** The manifest carries typed input/output schemas

  and the demo forwards the input schema to the model but validates

  neither side. The skeleton should validate both (Effect Schema in the

  CLI per the assessment), and reject non-conforming output packets as a

  host-side `bad_packet`.

- **No receipt.** The contract wants a `tool.ran` thread event carrying

  the digest per invocation. The demo's tool run is visible in the

  transcript but writes no durable event; the skeleton must, since the

  economy lane projects over those records.

- **`/plugin` surface.** Only `load` exists. `list`, `unload`, the

  digest-pinned local catalog, and the `capability` discovery tool

  (tiers 1–2 of assessment 4.4) are all skeleton scope.

## Open questions

- **WASI.** The demo proves pure compute needs none. The pilot (foreign

  session resume) needs read-only mounts, which means WASI preview 1

  filesystem imports or Extism-style host functions — the first real host

  import surface, and the first ask-once approval per assessment 4.4.

- **Fuel/CPU metering.** Wall-clock termination bounds time but not spend;

  fuel or epoch interruption needs an engine (wasmtime) the plain Node API

  does not expose. Decide whether the Node host ever needs it or whether

  wall-clock is the Node engine's honest ceiling.

- **Memory ceiling.** Enforceable today by instantiating with a

  host-provided bounded `WebAssembly.Memory` only if the guest imports its

  memory; rustc's default is to export it. The PDK could flip guests to

  imported memory, or the engine abstraction owns the limit.

- **Effect integration.** The host is promise-based to match `CoderTool`.

  Whether the skeleton wraps it as an Effect service with typed errors

  (per the workspace's Effect conventions) or stays at the tool seam is a

  skeleton decision; nothing in the demo blocks either.

- **Packet encoding.** JSON-in-JSON (arguments → UTF-8 JSON packet) is

  legible and matches the manifest schemas, but binary payloads (the

  session-resume pilot moves transcripts) may want a length-prefixed or

  CBOR packet kind — the manifest's `abi.kind: "packet-v0"` field exists

  so this can version.

- **Where guest crates live.** `plugins/word-stats` is a standalone crate

  (`[workspace]` empty table) so the monorepo's cargo workspace does not

  build it. The skeleton should decide whether guests join the workspace,

  get a `plugins/` workspace of their own, or live out-of-repo entirely

  once the registry exists.

#!/usr/bin/env node

/**

 * The plugin walking demo, end to end, from the shell:

 * manifest -> digest verified -> pure-compute check -> invoke -> result,

 * then the refusal paths: a guest refusal, a tampered digest, and a timeout.

 *

 * Run from packages/openagents-cli after a build:

 *

 *     pnpm build && node scripts/plugin-demo.mjs

 *

 * To see it inside the chat instead, load it as a session tool:

 *

 *     printf '/plugin load ../../plugins/word-stats/manifest.json\n<prompt>\n' \

 *       | node dist/main.js coder --plain

 */

import { copyFileSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";

import { tmpdir } from "node:os";

import { dirname, join, resolve } from "node:path";

import { fileURLToPath } from "node:url";

const here = dirname(fileURLToPath(import.meta.url));

const dist = resolve(here, "../dist/coder-plugins.js");

let host;

try {

  host = await import(dist);

} catch {

  console.error("Build first: pnpm build (this demo runs against dist/).");

  process.exit(1);

}

const { describeLoad, invokePlugin, isRefusal, loadPluginFromManifest, pluginTool } = host;

const manifestPath = resolve(here, "../../../plugins/word-stats/manifest.json");

const say = (label, text) => console.log(`\n== ${label}\n${text}`);

// 1. Load: manifest read, digest verified, imports proven empty.

const plugin = loadPluginFromManifest(manifestPath);

if (isRefusal(plugin)) {

  console.error(describeLoad(plugin));

  process.exit(1);

}

say("load", describeLoad(plugin));

// 2. Invoke through the tool the manifest materializes, as the model would.

const tool = pluginTool(plugin);

const text = "the quick brown fox jumps over the lazy dog";

say(

  `tool run: ${tool.name}({ text: "${text}" })`,

  await tool.run({ text }, new AbortController().signal),

);

// 3. The guest's own typed refusal, passed through as the output packet.

const bad = await invokePlugin(plugin, new TextEncoder().encode('{"wrong": true}'));

say("guest refusal", isRefusal(bad) ? describeLoad(bad) : new TextDecoder().decode(bad));

// 4. A tampered artifact does not load.

const dir = mkdtempSync(join(tmpdir(), "plugin-demo-"));

const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));

copyFileSync(

  resolve(dirname(manifestPath), manifest.artifact.path),

  join(dir, manifest.artifact.path),

);

manifest.artifact.digest = `sha256:${"0".repeat(64)}`;

writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest));

say("tampered digest", describeLoad(loadPluginFromManifest(join(dir, "manifest.json"))));

// 5. A guest that never returns is terminated at the bound.

const spin = new TextEncoder().encode(JSON.stringify({ text: "x", spin: true }));

const started = Date.now();

const timedOut = await invokePlugin(plugin, spin, { timeoutMs: 500 });

say(

  `runaway guest (${String(Date.now() - started)}ms)`,

  isRefusal(timedOut) ? `refused (${timedOut.code}): ${timedOut.reason}` : "unexpectedly answered",

);

} from "./coder-ollama.js";

import { openThread, ThreadUnavailable, type ThreadReplySource } from "./coder-thread.js";

import { delegateTool, openagentsTool, shellTool, skillTool } from "./coder-tools.js";

import {

  describeLoad,

  isRefusal,

  loadPluginFromManifest,

  pluginTool,

  type LoadedPlugin,

} from "./coder-plugins.js";

import { spawnSync } from "node:child_process";

import { resolve as resolvePath } from "node:path";

import { rebuild, RELOAD_EXIT_CODE, sourceCheckout } from "./coder-reload.js";

import { loadSkillSelection, standingContext } from "./coder-skills.js";

  // than guess.

  const laneFor = (choice: string) => {

    const harness = /^devin(:.+)?$/.test(choice)

      ? new DevinHarness(

          choice.startsWith("devin:") ? { permissionMode: choice.slice(6) } : {},

        )

      ? new DevinHarness(choice.startsWith("devin:") ? { permissionMode: choice.slice(6) } : {})

      : new OpencodeHarness({

          model: choice,

          ...(command === undefined ? {} : { command }),

      // neither.

      const named = Option.getOrUndefined(model);

      const localModel =

        named === undefined && !offline ? yield* Effect.promise(() => discoverOllamaModel()) : undefined;

        named === undefined && !offline

          ? yield* Effect.promise(() => discoverOllamaModel())

          : undefined;

      const wantsOllama = named === undefined ? localModel !== undefined : isOllamaModelFlag(named);

      const askedFor =

      // An Ollama session reads the credential too, though it opens no thread of

      // its own. The parent answers locally; children still spend a server

      // grant, so a local session delegates exactly as a thread session does.

      const stored =

        offline

          ? Option.none()

          : yield* findToken(endpoint.origin).pipe(

              Effect.catchTag("OpenAgentsCli.CredentialPersistenceUnavailable", () =>

                Effect.succeed(Option.none()),

              ),

            );

      const stored = offline

        ? Option.none()

        : yield* findToken(endpoint.origin).pipe(

            Effect.catchTag("OpenAgentsCli.CredentialPersistenceUnavailable", () =>

              Effect.succeed(Option.none()),

            ),

          );

      const thread =

        Option.isSome(stored) && !wantsOllama

      // Children get their own thread on their own model. The conversation

      // stays on the model it opened with, and a fan-out spends a budget the

      // reader's next question does not share.

      const childThread =

        Option.isSome(stored)

          ? yield* Effect.promise(() =>

              openChildThread({

                origin: endpoint.origin,

                token: Redacted.value(stored.value.token),

                objective: `delegated children of openagents coder in ${workspace.repository}`,

              }),

            )

          : undefined;

      const childThread = Option.isSome(stored)

        ? yield* Effect.promise(() =>

            openChildThread({

              origin: endpoint.origin,

              token: Redacted.value(stored.value.token),

              objective: `delegated children of openagents coder in ${workspace.repository}`,

            }),

          )

        : undefined;

      const childGrant = childThread?.kind === "opened" ? childThread.thread.childGrant : undefined;

      // Re-declared rather than declared once: switching a skill off in

      // `/skills` has to change what the next turn carries, and the tool

      // holding the catalog is the thing that changes.

      // Session-scoped WASM plugins, loaded with `/plugin load <manifest>`.

      // Experimental: the demo ahead of the plugin walking skeleton. A loaded

      // plugin materializes one tool for the rest of this session and nothing

      // outlives the process.

      const plugins: LoadedPlugin[] = [];

      const declareTools = () => {

        const active = skills.active();

        const tools = [

          ...(active.length === 0 ? [] : [skillTool(active)]),

          openagentsTool(),

          ...(setup === undefined ? [] : [delegateTool(setup.delegation)]),

          ...plugins.map((plugin) => pluginTool(plugin)),

        ];

        source.useTools?.(tools);

      };

      declareTools();

      const loadPlugin = (manifestPath: string): string => {

        const outcome = loadPluginFromManifest(resolvePath(process.cwd(), manifestPath));

        if (!isRefusal(outcome)) {

          // Reloading a name replaces it: a demo iterates on one plugin, and

          // two tools with one name would be a declaration the model cannot

          // tell apart.

          const at = plugins.findIndex((held) => held.manifest.name === outcome.manifest.name);

          if (at >= 0) plugins.splice(at, 1);

          plugins.push(outcome);

          declareTools();

        }

        return describeLoad(outcome);

      };

      // Delegation is off rather than quietly running children on the

      // conversation's model, so the refusal that turned it off is what the

      // reader sees.

                stdout: process.stdout,

                skills,

                onSkillsChanged: declareTools,

                loadPlugin,

              })

            : await runCoderPlain(session, {

                stdin: process.stdin,

                stdout: process.stdout,

                prompt: oneShot,

                skills,

                loadPlugin,

              });

        } finally {

          // An account holds eight open threads at once. A terminal that closed

  readonly prompt?: string | undefined;

  /** The workspace's skills, so `/skills` can report them. */

  readonly skills?: SkillSelection | undefined;

  /**

   * Load a WASM plugin from a manifest path and say what happened.

   *

   * Experimental, for `/plugin load <manifest>`. The caller owns the plugin

   * registry and the tool re-declaration.

   */

  readonly loadPlugin?: ((manifestPath: string) => string) | undefined;

}

export async function runCoderPlain(

          : `\n${all

              .map(

                (skill) =>

                  `${options.skills?.isOn(skill.name) ?? true ? "[on] " : "[off]"} ${skill.name}`,

                  `${(options.skills?.isOn(skill.name) ?? true) ? "[on] " : "[off]"} ${skill.name}`,

              )

              .join("\n")}\nRun the interactive session to switch one.\n`,

      );

      return;

    }

    // The same command as in the interface: it changes what the next turn

    // carries, so it is not sent to the model. Experimental.

    const pluginLoad = /^\/plugin\s+load\s+(.+)$/.exec(line.trim());

    if (pluginLoad !== null || /^\/plugin\b/.test(line.trim())) {

      const path = pluginLoad?.[1]?.trim();

      stdout.write(

        `\n${

          path === undefined || path.length === 0

            ? "Usage: /plugin load <path-to-manifest.json>. Experimental: loads a WASM plugin as a session tool."

            : options.loadPlugin === undefined

              ? "This session cannot load plugins."

              : options.loadPlugin(path)

        }\n`,

      );

      return;

    }

    written = 0;

    stdout.write(`\ncoder> `);

    await session.submit(line);

/**

 * The demo WASM plugin host for `openagents coder`.

 *

 * This is the one-off walking demo ahead of the plugin walking skeleton

 * (OpenAgentsInc/openagents#26): load a manifest, verify the artifact digest,

 * instantiate a pure-compute WASM module, call `handle_packet(bytes) -> bytes`

 * under a timeout, and surface the whole thing to the model as a session

 * tool. `docs/plugins/2026-08-24-coder-plugin-demo-shape.md` records what the

 * real skeleton keeps and what it replaces.

 *

 * The contract, in miniature:

 *

 * - **Manifest first.** Identity, artifact digest, typed input and output

 *   schemas, and capability declarations. Absence of a capability means

 *   denial; this demo host accepts only the empty declaration — no mounts,

 *   no hosts — because it implements no host imports at all.

 * - **Digest before load.** The artifact's SHA-256 is compared to the

 *   manifest's pin before the module is compiled. A mismatch is a refusal,

 *   not a warning.

 * - **Pure compute only.** The module's import list must be empty. A module

 *   that asks for imports is refused by inspection, before instantiation, so

 *   the sandbox is a property of what was loaded rather than a hope about

 *   what it does.

 * - **Timeout by termination.** A WASM call is synchronous and cannot be

 *   preempted in-process, so every invocation runs in a `worker_threads`

 *   worker the host terminates when the manifest's bound expires. A runaway

 *   guest costs its own worker and nothing else.

 * - **Typed refusals both ways.** The host refuses with `{code, reason}`;

 *   the guest returns `{"refusal": {...}}` inside its output packet. Both

 *   read as text to the model, which can act on a refusal and cannot act on

 *   a turn that died.

 */

import { createHash } from "node:crypto";

import { readFileSync } from "node:fs";

import { dirname, resolve } from "node:path";

import { Worker } from "node:worker_threads";

import type { CoderTool } from "./coder-tools.js";

/** Why the host would not do what was asked. Never thrown; always returned. */

export interface PluginRefusal {

  readonly code:

    | "manifest_unreadable"

    | "manifest_invalid"

    | "artifact_unreadable"

    | "digest_mismatch"

    | "capabilities_unsupported"

    | "imports_declared"

    | "exports_missing"

    | "not_wasm"

    | "timeout"

    | "trap"

    | "bad_packet";

  readonly reason: string;

}

export const isRefusal = (value: unknown): value is PluginRefusal =>

  typeof value === "object" &&

  value !== null &&

  typeof (value as PluginRefusal).code === "string" &&

  typeof (value as PluginRefusal).reason === "string";

/** The manifest fields this host reads. The file may carry more. */

export interface PluginManifest {

  readonly name: string;

  readonly version: string;

  readonly description: string;

  readonly artifact: { readonly path: string; readonly digest: string };

  readonly abi: { readonly entry: string; readonly alloc: string };

  readonly interface: {

    readonly input: Record<string, unknown>;

    readonly output: Record<string, unknown>;

  };

  readonly capabilities: {

    readonly mounts: ReadonlyArray<unknown>;

    readonly hosts: ReadonlyArray<unknown>;

    readonly timeout_ms: number;

  };

}

/** A plugin that passed every check and is ready to invoke. */

export interface LoadedPlugin {

  readonly manifest: PluginManifest;

  /** The artifact bytes, held so an invocation cannot race a file rewrite. */

  readonly wasm: Uint8Array;

  /** The verified digest, `sha256:<hex>`, for receipts and notices. */

  readonly digest: string;

}

/** Ceiling on the manifest's own timeout, so a manifest cannot ask for an hour. */

const TIMEOUT_CEILING_MS = 30_000;

/** How much plugin output the model is shown. */

const PLUGIN_OUTPUT_LIMIT = 16_000;

const refuse = (code: PluginRefusal["code"], reason: string): PluginRefusal => ({ code, reason });

/**

 * Load a plugin from its manifest: parse, validate, verify the digest, and

 * prove by inspection that the module is pure compute with the declared ABI.

 *

 * Everything that can be checked before the first invocation is checked here,

 * so `/plugin load` either says exactly what is wrong or hands back a plugin

 * whose next failure can only be about the packet.

 */

export function loadPluginFromManifest(manifestPath: string): LoadedPlugin | PluginRefusal {

  let raw: string;

  try {

    raw = readFileSync(manifestPath, "utf8");

  } catch (cause) {

    return refuse("manifest_unreadable", cause instanceof Error ? cause.message : String(cause));

  }

  let parsed: unknown;

  try {

    parsed = JSON.parse(raw);

  } catch {

    return refuse("manifest_invalid", `${manifestPath} is not JSON`);

  }

  const manifest = validateManifest(parsed);

  if (isRefusal(manifest)) return manifest;

  // This host implements no imports, so the only capability set it can

  // enforce is the empty one. Declared-but-denied, never declared-and-ignored.

  if (manifest.capabilities.mounts.length > 0 || manifest.capabilities.hosts.length > 0) {

    return refuse(

      "capabilities_unsupported",

      "this host runs pure computation only: the manifest declares mounts or hosts, " +

        "and there are no host imports to grant them through",

    );

  }

  let wasm: Uint8Array<ArrayBuffer>;

  const artifactPath = resolve(dirname(manifestPath), manifest.artifact.path);

  try {

    // Copied out of the Buffer pool so the bytes sit on their own

    // ArrayBuffer, which both the compiler and the worker transfer want.

    wasm = Uint8Array.from(readFileSync(artifactPath));

  } catch (cause) {

    return refuse("artifact_unreadable", cause instanceof Error ? cause.message : String(cause));

  }

  const digest = `sha256:${createHash("sha256").update(wasm).digest("hex")}`;

  if (digest !== manifest.artifact.digest) {

    return refuse(

      "digest_mismatch",

      `the manifest pins ${manifest.artifact.digest} but ${manifest.artifact.path} is ${digest}; ` +

        "the artifact is not the one the manifest describes, so it does not load",

    );

  }

  let module: WebAssembly.Module;

  try {

    module = new WebAssembly.Module(wasm);

  } catch (cause) {

    return refuse("not_wasm", cause instanceof Error ? cause.message : String(cause));

  }

  const imports = WebAssembly.Module.imports(module);

  if (imports.length > 0) {

    const named = imports.map((entry) => `${entry.module}.${entry.name}`).join(", ");

    return refuse(

      "imports_declared",

      `the module asks for host imports (${named}); this host instantiates with none`,

    );

  }

  const exports = new Set(WebAssembly.Module.exports(module).map((entry) => entry.name));

  for (const name of [manifest.abi.entry, manifest.abi.alloc, "memory"]) {

    if (!exports.has(name)) {

      return refuse("exports_missing", `the module does not export \`${name}\``);

    }

  }

  return { manifest, wasm, digest };

}

function validateManifest(value: unknown): PluginManifest | PluginRefusal {

  const bad = (what: string): PluginRefusal =>

    refuse("manifest_invalid", `the manifest is missing or mistypes ${what}`);

  if (typeof value !== "object" || value === null) return bad("the top-level object");

  const record = value as Record<string, unknown>;

  const name = record["name"];

  if (typeof name !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(name)) {

    return bad("`name` (lowercase identifier, it becomes the tool name)");

  }

  const version = record["version"];

  if (typeof version !== "string" || version.length === 0) return bad("`version`");

  const description = record["description"];

  if (typeof description !== "string" || description.length === 0) return bad("`description`");

  const artifact = record["artifact"] as Record<string, unknown> | undefined;

  if (

    typeof artifact !== "object" ||

    artifact === null ||

    typeof artifact["path"] !== "string" ||

    typeof artifact["digest"] !== "string" ||

    !artifact["digest"].startsWith("sha256:")

  ) {

    return bad("`artifact` (`path` and a `sha256:` `digest`)");

  }

  const abi = record["abi"] as Record<string, unknown> | undefined;

  if (

    typeof abi !== "object" ||

    abi === null ||

    typeof abi["entry"] !== "string" ||

    typeof abi["alloc"] !== "string"

  ) {

    return bad("`abi` (`entry` and `alloc` export names)");

  }

  const iface = record["interface"] as Record<string, unknown> | undefined;

  if (

    typeof iface !== "object" ||

    iface === null ||

    typeof iface["input"] !== "object" ||

    iface["input"] === null ||

    typeof iface["output"] !== "object" ||

    iface["output"] === null

  ) {

    return bad("`interface` (`input` and `output` JSON schemas)");

  }

  const capabilities = record["capabilities"] as Record<string, unknown> | undefined;

  if (

    typeof capabilities !== "object" ||

    capabilities === null ||

    !Array.isArray(capabilities["mounts"]) ||

    !Array.isArray(capabilities["hosts"]) ||

    typeof capabilities["timeout_ms"] !== "number" ||

    capabilities["timeout_ms"] <= 0

  ) {

    return bad("`capabilities` (`mounts`, `hosts`, positive `timeout_ms`)");

  }

  return {

    name,

    version,

    description,

    artifact: { path: artifact["path"], digest: artifact["digest"] },

    abi: { entry: abi["entry"], alloc: abi["alloc"] },

    interface: {

      input: iface["input"] as Record<string, unknown>,

      output: iface["output"] as Record<string, unknown>,

    },

    capabilities: {

      mounts: capabilities["mounts"],

      hosts: capabilities["hosts"],

      timeout_ms: Math.min(capabilities["timeout_ms"], TIMEOUT_CEILING_MS),

    },

  };

}

/**

 * The invocation worker, as source.

 *

 * A string rather than a file because the worker is part of this module's

 * contract, and a path into `dist/` breaks the moment tests run from source.

 * The worker instantiates the already-verified bytes with an empty import

 * object, copies the packet in through the guest's allocator, calls the entry,

 * and posts the output packet back. Anything the guest does wrong — a trap, an

 * out-of-range packet — comes back as a message, and anything it does forever

 * is ended by the host's timer terminating the whole worker.

 */

const INVOKE_WORKER = `

const { parentPort, workerData } = require("node:worker_threads");

(async () => {

  const { wasm, input, entry, alloc } = workerData;

  try {

    const { instance } = await WebAssembly.instantiate(wasm, {});

    const call = instance.exports[entry];

    const reserve = instance.exports[alloc];

    const memory = instance.exports.memory;

    const ptr = reserve(input.length);

    new Uint8Array(memory.buffer).set(input, ptr);

    const packed = call(ptr, input.length);

    const outPtr = Number(BigInt(packed) >> 32n);

    const outLen = Number(BigInt(packed) & 0xffffffffn);

    // Re-read the buffer: the call may have grown memory, detaching the old view.

    const view = new Uint8Array(memory.buffer);

    if (outPtr + outLen > view.length) {

      parentPort.postMessage({ trap: "the output packet points outside guest memory" });

      return;

    }

    parentPort.postMessage({ output: view.slice(outPtr, outPtr + outLen) });

  } catch (cause) {

    parentPort.postMessage({ trap: cause instanceof Error ? cause.message : String(cause) });

  }

})();

`;

/**

 * Call the plugin once: packet bytes in, packet bytes out, or a refusal.

 *

 * One worker per invocation. That costs a few milliseconds of instantiation

 * and buys the two properties the contract cares about: the timeout is

 * enforceable against a guest that never returns, and no state survives from

 * one call to the next, so every invocation runs on memory the previous one

 * cannot have corrupted.

 */

export function invokePlugin(

  plugin: LoadedPlugin,

  input: Uint8Array,

  options?: { readonly timeoutMs?: number | undefined },

): Promise<Uint8Array | PluginRefusal> {

  const timeoutMs = options?.timeoutMs ?? plugin.manifest.capabilities.timeout_ms;

  return new Promise((settle) => {

    const worker = new Worker(INVOKE_WORKER, {

      eval: true,

      workerData: {

        wasm: plugin.wasm,

        input,

        entry: plugin.manifest.abi.entry,

        alloc: plugin.manifest.abi.alloc,

      },

    });

    let done = false;

    const finish = (outcome: Uint8Array | PluginRefusal) => {

      if (done) return;

      done = true;

      clearTimeout(timer);

      void worker.terminate();

      settle(outcome);

    };

    const timer = setTimeout(() => {

      finish(

        refuse(

          "timeout",

          `the plugin did not answer within ${String(timeoutMs)}ms, the bound its manifest declares, ` +

            "and its worker was terminated",

        ),

      );

    }, timeoutMs);

    worker.on("message", (message: { output?: Uint8Array; trap?: string }) => {

      if (message.output !== undefined) finish(new Uint8Array(message.output));

      else finish(refuse("trap", message.trap ?? "the plugin trapped without a message"));

    });

    worker.on("error", (cause) => {

      finish(refuse("trap", cause.message));

    });

    worker.on("exit", (code) => {

      if (!done && code !== 0)

        finish(refuse("trap", `the plugin worker exited with code ${String(code)}`));

    });

  });

}

/**

 * The tool a loaded plugin materializes for the session.

 *

 * The manifest is the whole declaration: its name is the tool name, its

 * description is what the model reads, its input schema is the parameters.

 * `run` is the marshalling layer — arguments to a JSON packet, packet to the

 * plugin, output packet back as text — and every host refusal is a sentence

 * the model can act on rather than an exception the turn dies of.

 */

export function pluginTool(plugin: LoadedPlugin): CoderTool {

  const { manifest } = plugin;

  return {

    name: manifest.name,

    description:

      `${manifest.description}\n\n` +

      `Experimental WASM plugin \`${manifest.name}\` v${manifest.version}, loaded for this ` +

      `session only (${plugin.digest.slice(0, 19)}…). It runs sandboxed pure computation: no ` +

      "file, network, or environment access. The result is a JSON object with either `ok` or " +

      "`refusal`.",

    parameters: manifest.interface.input,

    run: async (args) => {

      const packet = new TextEncoder().encode(JSON.stringify(args));

      const outcome = await invokePlugin(plugin, packet);

      if (isRefusal(outcome)) {

        return `The plugin refused (${outcome.code}): ${outcome.reason}`;

      }

      let text: string;

      try {

        text = new TextDecoder("utf-8", { fatal: true }).decode(outcome);

      } catch {

        return `The plugin refused (bad_packet): the output packet is not UTF-8 (${String(outcome.length)} bytes)`;

      }

      return text.length <= PLUGIN_OUTPUT_LIMIT

        ? text

        : `${text.slice(0, PLUGIN_OUTPUT_LIMIT)}\n…[truncated]`;

    },

  };

}

/** What `/plugin load` reports, for a notice or a plain line. */

export function describeLoad(outcome: LoadedPlugin | PluginRefusal): string {

  if (isRefusal(outcome)) {

    return `Plugin not loaded (${outcome.code}): ${outcome.reason}`;

  }

  const { manifest } = outcome;

  return (

    `Loaded plugin \`${manifest.name}\` v${manifest.version} — digest verified ` +

    `(${outcome.digest.slice(0, 19)}…, ${String(outcome.wasm.length)} bytes, pure compute, ` +

    `${String(manifest.capabilities.timeout_ms)}ms bound). The \`${manifest.name}\` tool is ` +

    "declared to the model for this session. Experimental."

  );

}

  readonly skills?: SkillSelection | undefined;

  /** Re-declare the tools after a skill is switched. */

  readonly onSkillsChanged?: (() => void) | undefined;

  /**

   * Load a WASM plugin from a manifest path and say what happened.

   *

   * Experimental, for `/plugin load <manifest>`. The caller owns the plugin

   * registry and the tool re-declaration; this interface only relays the path

   * and shows the sentence that comes back.

   */

  readonly loadPlugin?: ((manifestPath: string) => string) | undefined;

  readonly stdin: NodeJS.ReadStream;

  readonly stdout: NodeJS.WriteStream;

}

        // row in hand: eight descriptions at once is the wall of text the

        // catalog exists to avoid.

        if (focused) {

          rows.push(...wrapStyled(skill.description, Math.max(20, width - 8), DIM).map(

            (line) => `        ${line}`,

          ));

          rows.push(

            ...wrapStyled(skill.description, Math.max(20, width - 8), DIM).map(

              (line) => `        ${line}`,

            ),

          );

        }

      }

        rows.push(

          `${DIM}${"─".repeat(Math.max(0, width))}${RESET}`,

          hints(

            [

              { text: "↑↓ move" },

              { text: "space toggles" },

              { text: "esc returns" },

            ],

            [{ text: "↑↓ move" }, { text: "space toggles" }, { text: "esc returns" }],

            "",

            width,

          ),

        paint(rows, rows.length, 1);

        return;

      }

      const transcriptHeight = Math.max(

        1,

        height - STATUS_ROWS - COMPOSER_ROWS - SPACER_ROWS - 1,

      );

      const transcriptHeight = Math.max(1, height - STATUS_ROWS - COMPOSER_ROWS - SPACER_ROWS - 1);

      const fleet = fleetLines(snapshot, width);

      // The fleet takes its rows from the transcript, not from the chrome: the

        return;

      }

      // `/plugin load` changes what the next turn carries, like `/skills`, so

      // it is not something to say to the model. Experimental.

      const pluginLoad = /^\/plugin\s+load\s+(.+)$/.exec(prompt.trim());

      if (pluginLoad !== null || /^\/plugin\b/.test(prompt.trim())) {

        const path = pluginLoad?.[1]?.trim();

        session.notice(

          path === undefined || path.length === 0

            ? "Usage: /plugin load <path-to-manifest.json>. Experimental: loads a WASM plugin " +

                "as a session tool."

            : options.loadPlugin === undefined

              ? "This session cannot load plugins."

              : options.loadPlugin(path),

        );

        render();

        return;

      }

      if (prompt.trimStart().startsWith("/delegate")) {

        void session.submit(prompt);

        render();

/**

 * The plugin demo, proved end to end against the checked-in artifact:

 * manifest read, digest verified, module inspected, packet in, packet out,

 * refusals typed, timeout enforced by termination, and the whole path

 * surfaced through a coder session as a tool call in the transcript.

 */

import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";

import { tmpdir } from "node:os";

import { fileURLToPath } from "node:url";

import { join } from "node:path";

import { PassThrough } from "node:stream";

import { describe, expect, it } from "vitest";

import {

  describeLoad,

  invokePlugin,

  isRefusal,

  loadPluginFromManifest,

  pluginTool,

  type LoadedPlugin,

} from "../src/coder-plugins.js";

import { CoderSession, type ReplyChunk, type ReplySource } from "../src/coder-session.js";

import { runCoderPlain } from "../src/coder-plain.js";

import type { CoderTool } from "../src/coder-tools.js";

const MANIFEST = fileURLToPath(

  new URL("../../../plugins/word-stats/manifest.json", import.meta.url),

);

const loadFixture = (): LoadedPlugin => {

  const outcome = loadPluginFromManifest(MANIFEST);

  if (isRefusal(outcome)) throw new Error(`${outcome.code}: ${outcome.reason}`);

  return outcome;

};

describe("loadPluginFromManifest", () => {

  it("loads the checked-in demo plugin and verifies its digest", () => {

    const plugin = loadFixture();

    expect(plugin.manifest.name).toBe("word_stats");

    expect(plugin.digest).toBe(plugin.manifest.artifact.digest);

    expect(describeLoad(plugin)).toContain("digest verified");

  });

  it("refuses an artifact whose digest does not match the manifest's pin", () => {

    const dir = mkdtempSync(join(tmpdir(), "plugin-digest-"));

    const manifest = JSON.parse(readFileSync(MANIFEST, "utf8")) as {

      artifact: { digest: string; path: string };

    };

    manifest.artifact.digest = `sha256:${"0".repeat(64)}`;

    writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest));

    writeFileSync(

      join(dir, manifest.artifact.path),

      readFileSync(

        fileURLToPath(new URL("../../../plugins/word-stats/word_stats.wasm", import.meta.url)),

      ),

    );

    const outcome = loadPluginFromManifest(join(dir, "manifest.json"));

    expect(isRefusal(outcome) && outcome.code).toBe("digest_mismatch");

  });

  it("refuses a manifest that declares mounts or hosts", () => {

    const dir = mkdtempSync(join(tmpdir(), "plugin-caps-"));

    const manifest = JSON.parse(readFileSync(MANIFEST, "utf8")) as {

      capabilities: { hosts: unknown[] };

    };

    manifest.capabilities.hosts = ["api.example.com"];

    writeFileSync(join(dir, "manifest.json"), JSON.stringify(manifest));

    const outcome = loadPluginFromManifest(join(dir, "manifest.json"));

    expect(isRefusal(outcome) && outcome.code).toBe("capabilities_unsupported");

  });

});

describe("invokePlugin", () => {

  it("answers a packet with the statistics the guest computed", async () => {

    const plugin = loadFixture();

    const packet = new TextEncoder().encode(