@six5536/smllm-wasm 0.0.0 → 0.4.1

package/README.md

@@ -1,3 +1,138 @@
-# @six5536/smllm-wasm
+# smllm-wasm
 
-This version only reserves the name. smllm publishes its real versions from https://github.com/six5536/smllm.
+`@six5536/smllm-wasm` is smllm's engine, `smllm-core`, compiled to WebAssembly. It is for a host
+that runs state machines in its own process, such as a browser, a worker, a serverless function,
+or Node. The large language model (LLM) can run anywhere. The API is typed: it takes objects and returns
+objects, and the package includes TypeScript declarations.
+
+This README helps you run the engine in your own host. It shows a first example, then describes
+the host methods, storage, the Node helpers, and when to use the WebAssembly engine instead of the
+CLI.
+
+- [Host](#host)
+- [Storage](#storage)
+- [Run in Node](#run-in-node)
+- [WebAssembly or CLI](#webassembly-or-cli)
+- [Licence](#licence)
+
+This example loads compiled machines, starts a session, and passes the model's tool calls to the
+engine:
+
+```js
+import init, { Engine, memoryStorage } from "@six5536/smllm-wasm"; // or from "@six5536/smllm-wasm/bundler"
+
+await init(); // the bundler build needs no init
+const compiled = await (await fetch("machines.json")).json(); // `smllm compile`
+const engine = new Engine(
+  compiled,
+  {
+    // Every host method is optional; supports / check / run add host guard and
+    // action kinds (`command`), none by default.
+  },
+  memoryStorage(), // or your own Storage (see Storage); optional
+);
+const { session, text } = engine.bind("web");
+// Give the model the same `smllm` tool the MCP server offers, and pass its
+// calls through: a malformed call comes back as an answer, never a throw.
+const tool = engine.tool(); // { name, description, inputSchema }
+const reply = engine.callTool({ session, event: "enter", params: { stateMachine: "dev" } });
+// When the model tries to stop (`stopHookActive`: it is already continuing
+// because of an earlier block):
+const stop = engine.stop(session, stopHookActive);
+// stop.decision "block": hold the model, show it stop.text (the events list);
+// "runaway": let it stop, show stop.text to the user; "allow": let it stop.
+```
+
+The `examples/wasm` folder of the [smllm repository](https://github.com/six5536/smllm) holds a
+whole agent loop, in TypeScript.
+
+## Host
+
+A host can supply these methods. Each one is optional, and the engine uses its default when the
+host leaves the method out:
+
+- `supports(kind)` says which guard and action kinds the host runs. By default, it supports none.
+- `check(kind, params, env, cwd)` checks a guard of a supported kind.
+- `run(kind, params, env, cwd)` runs an action of a supported kind. It returns nothing on
+  success, and the detail of the failure otherwise. A command's `params.cwd` is relative to the
+  compiled config file.
+- `read(file)` reads a prompt file. `smllm compile` inlines prompt files, so a host rarely needs
+  this method.
+- `isMatch(pattern, value)` matches a pattern. By default, it uses `new RegExp`.
+- `now()` returns the time. By default, it uses `Date.now`.
+- `random()` returns a random number. By default, it uses `crypto.getRandomValues`.
+- `history(machine, id, entry)` and `put(kind, key, record)` receive writes. By default, the
+  engine drops them.
+
+A host method that throws is a host failure: a failed guard or action, or a rejected pattern. The
+reply text shows the failure, and the engine stays usable.
+
+## Storage
+
+The engine works in memory and writes through to storage. It passes each session, binding, and
+instance to `put` when it saves them, and each history entry to `history`. Persistence therefore
+costs only what changed, never a snapshot for each call.
+
+A `Storage` is `{ load(), put(kind, key, record), history(machine, id, entry) }`. The engine
+takes a `Storage` as the constructor's third argument, loads it once, and then hands it every
+write.
+`memoryStorage()` keeps the state in memory. In a browser, you can write a `Storage` over
+IndexedDB, or one that sends the records to a server. `exportState()` and `importState(state)`
+move the whole state at once, for backups and moves.
+
+## Run in Node
+
+`@six5536/smllm-wasm/node` provides a host and a storage for Node:
+
+```js
+import { nodeFileStorage, nodeHost } from "@six5536/smllm-wasm/node";
+
+const engine = new Engine(
+  compiled,
+  nodeHost({ configDir: "/path/to/the/compiled/config/folder" }),
+  nodeFileStorage("/path/to/state"),
+);
+```
+
+`nodeHost` runs `command` guards and actions as the smllm CLI does:
+
+- It runs a string `run` through the shell, and a list without one.
+- It sets the `SMLLM_*` environment variables.
+- It applies a timeout, 60 seconds by default, and the timeout also kills the processes that the
+  command started.
+- On a failure, it reports the last 400 characters of output.
+
+`nodeFileStorage` keeps one file for each record, written atomically, and keeps history as JSON Lines (JSONL).
+Only one process can own a storage folder.
+
+## WebAssembly or CLI
+
+The following table gives the median time for each call. The project's benchmark measured the
+times in a Linux container with a local disk. Each column heading gives the size of the store as the
+number of paused instances and the number of completed instances.
+
+| Path | Call | 0 / 0 | 100 / 1000 | 1000 / 1000 |
+| ---- | ---- | ---: | ---: | ---: |
+| wasm, in-process | `fire` enter / pause | 0.06 ms | 0.02 / 0.03 ms | 0.02 / 0.03 ms |
+| wasm, in-process | view, stop | 0.02 ms | 0.006 ms | 0.006 ms |
+| CLI, `smllm mcp` (one process, over stdio) | tool call | 0.2–0.4 ms | 0.1–0.6 ms | 0.1–2.3 ms |
+| CLI, a process per call | `smllm fire`, `statusline` | 1.4–1.7 ms | 1.2–1.8 ms | 1.3–4.4 ms |
+
+Use the WebAssembly engine in these cases:
+
+- In a browser, a worker, or a serverless function, where there is no binary and no shell.
+- For a model that answers in milliseconds.
+- For guards and actions written in JavaScript.
+- For storage of your own.
+
+Use the CLI, from the `@six5536/smllm` npm package, when a Node app needs the CLI's behaviour as
+it is. For tool calls, run `smllm mcp`. The CLI shares files between processes with locking, and
+provides the status line, `smllm instance list`, and the Claude Code hooks.
+
+The string API underneath, which takes and returns JSON text, is in `@six5536/smllm-wasm/raw` and
+`@six5536/smllm-wasm/raw/bundler`.
+
+## Licence
+
+smllm-wasm is licensed under the MIT licence. Its source is in the
+[smllm repository](https://github.com/six5536/smllm).

package/dist/bundler.d.ts

@@ -0,0 +1,8 @@
+import { Engine as Raw } from "../wasm/bundler/smllm_wasm.js";
+import { Engine as Base } from "./wrap.js";
+export type * from "./types.js";
+export { memoryStorage } from "./storage.js";
+/** smllm's engine over compiled machines (`smllm compile` output). */
+export declare class Engine extends Base {
+    protected static Raw: typeof Raw;
+}

package/dist/bundler.js

@@ -0,0 +1,9 @@
+// smllm-wasm for bundlers: the wasm loads on import. The string API is
+// `smllm-wasm/raw/bundler`.
+import { Engine as Raw } from "../wasm/bundler/smllm_wasm.js";
+import { Engine as Base } from "./wrap.js";
+export { memoryStorage } from "./storage.js";
+/** smllm's engine over compiled machines (`smllm compile` output). */
+export class Engine extends Base {
+    static Raw = Raw;
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import init, { Engine as Raw, initSync } from "../wasm/web/smllm_wasm.js";
+import { Engine as Base } from "./wrap.js";
+export default init;
+export { initSync };
+export type * from "./types.js";
+export { memoryStorage } from "./storage.js";
+/** smllm's engine over compiled machines (`smllm compile` output). */
+export declare class Engine extends Base {
+    protected static Raw: typeof Raw;
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+// smllm-wasm for browsers and Node (the web build): call `init()` (or
+// `initSync`) once, then use `Engine`. The string API is `smllm-wasm/raw`.
+import init, { Engine as Raw, initSync } from "../wasm/web/smllm_wasm.js";
+import { Engine as Base } from "./wrap.js";
+export default init;
+export { initSync };
+export { memoryStorage } from "./storage.js";
+/** smllm's engine over compiled machines (`smllm compile` output). */
+export class Engine extends Base {
+    static Raw = Raw;
+}

package/dist/node/host.d.ts

@@ -0,0 +1,12 @@
+import type { Host } from "../types.js";
+/** `timeoutSecs` default (DEC-5), as the CLI's. */
+export declare const DEFAULT_TIMEOUT_SECS = 60;
+/**
+ * A host that runs `command` guards and actions. `configDir` is the folder
+ * of the compiled config: a command's `cwd` is relative to it (D8-22).
+ * Spread it into your host: `new Engine(compiled, { ...nodeHost({ configDir }), ... })`.
+ */
+export declare function nodeHost(options: {
+    configDir: string;
+    timeoutSecs?: number;
+}): Host;

package/dist/node/host.js

@@ -0,0 +1,106 @@
+// The Node command host (HOST-15): `command` guards
+// and actions run as the CLI runs them (DEC-4..DEC-7). Host methods are
+// synchronous, so commands run with `spawnSync`. On unix the command is
+// started detached, as the leader of its own process group, and a timeout
+// kills that whole group, so what the command started dies with it; its
+// output goes to a file, not a pipe, so a process it leaves running cannot
+// hold the call open. On Windows the command's own process is killed, as the
+// CLI does.
+// @zen-component: HOST-JsPackage
+import { spawnSync } from "node:child_process";
+import { closeSync, mkdtempSync, openSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+/** `timeoutSecs` default (DEC-5), as the CLI's. */
+export const DEFAULT_TIMEOUT_SECS = 60;
+const TAIL_CHARS = 400;
+/** The last `TAIL_CHARS` characters of `text`, on one line (as the CLI's). */
+function tail(text) {
+    const chars = [...text.trim()];
+    const cut = chars.length > TAIL_CHARS;
+    const s = chars.slice(-TAIL_CHARS).join("").split(/\s+/).filter(Boolean).join(" ");
+    return cut ? `…${s}` : s;
+}
+/** A command's failure text, `""` when it passed. */
+function runCommand(params, env, sessionCwd, configDir, timeoutSecs) {
+    const run = params.run;
+    let argv;
+    if (typeof run === "string") {
+        argv = process.platform === "win32" ? ["cmd", "/C", run] : ["sh", "-c", run];
+    }
+    else if (Array.isArray(run) && run.length > 0 && run.every((a) => typeof a === "string")) {
+        argv = run;
+    }
+    else {
+        return "no run param";
+    }
+    // `params.cwd` is relative to the compiled config (D8-22); else the
+    // session's working directory, when there is one.
+    const cwd = typeof params.cwd === "string" ? resolve(configDir, params.cwd) : sessionCwd || undefined;
+    const secs = typeof params.timeoutSecs === "number" ? params.timeoutSecs : timeoutSecs;
+    const unix = process.platform !== "win32";
+    const dir = mkdtempSync(join(tmpdir(), "smllm-command-"));
+    const out = join(dir, "out");
+    const fd = openSync(out, "w");
+    try {
+        // `detached` is honoured by spawnSync as by spawn, though its typings
+        // omit it; the test that a timed-out grandchild dies guards this.
+        const options = {
+            cwd,
+            env: { ...process.env, ...env },
+            stdio: ["ignore", fd, fd],
+            timeout: secs * 1000,
+            killSignal: "SIGKILL",
+            // Its own session and process group (spawnSync honours it as spawn
+            // does), so a timeout can kill what it started too.
+            detached: unix,
+            windowsVerbatimArguments: argv[0] === "cmd",
+            windowsHide: true,
+        };
+        const r = spawnSync(argv[0], argv.slice(1), options);
+        const timedOut = r.error?.code === "ETIMEDOUT";
+        if (timedOut) {
+            if (unix && r.pid) {
+                // The leader is gone; the rest of its group goes too. A group id is
+                // not reused while members remain.
+                try {
+                    process.kill(-r.pid, "SIGKILL");
+                }
+                catch {
+                    // Nothing left in the group.
+                }
+            }
+            return `timed out after ${secs}s`;
+        }
+        if (r.error) {
+            return `could not start: ${r.error.message}`;
+        }
+        return failure(r.status, r.status === 0 ? "" : readFileSync(out, "utf8"));
+    }
+    finally {
+        closeSync(fd);
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+function failure(status, output) {
+    if (status === 0) {
+        return "";
+    }
+    const code = status === null ? "killed by a signal" : `exited ${status}`;
+    const t = tail(output);
+    return t ? `${code}: ${t}` : code;
+}
+/**
+ * A host that runs `command` guards and actions. `configDir` is the folder
+ * of the compiled config: a command's `cwd` is relative to it (D8-22).
+ * Spread it into your host: `new Engine(compiled, { ...nodeHost({ configDir }), ... })`.
+ */
+export function nodeHost(options) {
+    const { configDir, timeoutSecs = DEFAULT_TIMEOUT_SECS } = options;
+    const exec = (kind, params, env, cwd) => kind === "command" ? runCommand(params, env, cwd, configDir, timeoutSecs) : `${kind} is not supported`;
+    return {
+        supports: (kind) => kind === "command",
+        check: (kind, params, env, cwd) => exec(kind, params, env, cwd) === "",
+        run: (kind, params, env, cwd) => exec(kind, params, env, cwd),
+    };
+}

package/dist/node/index.d.ts

@@ -0,0 +1,2 @@
+export { fileName, nodeFileStorage } from "./storage.js";
+export { DEFAULT_TIMEOUT_SECS, nodeHost } from "./host.js";

package/dist/node/index.js

@@ -0,0 +1,4 @@
+// smllm-wasm for Node hosts: file storage and the command host.
+// Import the engine itself from `smllm-wasm`.
+export { fileName, nodeFileStorage } from "./storage.js";
+export { DEFAULT_TIMEOUT_SECS, nodeHost } from "./host.js";

package/dist/node/storage.d.ts

@@ -0,0 +1,9 @@
+import type { Storage } from "../types.js";
+/**
+ * A file name for `key`: `[a-z0-9-]` kept, every other byte %-escaped (upper
+ * case too, so a case-insensitive file system cannot merge two keys), cut
+ * with an FNV-1a hash when long.
+ */
+export declare function fileName(key: string): string;
+/** Storage in `dir`: `sessions/`, `bindings/`, `instances/` and `history/`. */
+export declare function nodeFileStorage(dir: string): Storage;

package/dist/node/storage.js

@@ -0,0 +1,75 @@
+// Node file storage (HOST-14): a file per record, written
+// atomically (temp file, then rename), and history as JSONL, one line per
+// entry in the CLI's format. One process owns a folder: several processes
+// sharing state should use the CLI, whose store locks.
+// @zen-component: HOST-JsPackage
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const SHELF = {
+    session: "sessions",
+    binding: "bindings",
+    instance: "instances",
+};
+/** Longest file name before `.json`; longer ones are cut and end in a hash. */
+const MAX_NAME = 120;
+/**
+ * A file name for `key`: `[a-z0-9-]` kept, every other byte %-escaped (upper
+ * case too, so a case-insensitive file system cannot merge two keys), cut
+ * with an FNV-1a hash when long.
+ */
+export function fileName(key) {
+    let name = "";
+    for (const b of new TextEncoder().encode(key)) {
+        const c = String.fromCharCode(b);
+        name += /[a-z0-9-]/.test(c) ? c : `%${b.toString(16).padStart(2, "0")}`;
+    }
+    if (name.length > MAX_NAME) {
+        let h = 0xcbf29ce484222325n;
+        for (const b of new TextEncoder().encode(key)) {
+            h = ((h ^ BigInt(b)) * 0x100000001b3n) & 0xffffffffffffffffn;
+        }
+        name = `${name.slice(0, MAX_NAME - 17)}~${h.toString(16).padStart(16, "0")}`;
+    }
+    return name;
+}
+let written = 0;
+/** Write `text` to `path` whole or not at all. */
+function writeAtomic(path, text) {
+    const temp = `${path}.${process.pid}.${written++}.tmp`;
+    writeFileSync(temp, text);
+    renameSync(temp, path);
+}
+/** Storage in `dir`: `sessions/`, `bindings/`, `instances/` and `history/`. */
+export function nodeFileStorage(dir) {
+    return {
+        load() {
+            const state = { sessions: {}, bindings: {}, instances: {} };
+            let any = false;
+            for (const shelf of Object.values(SHELF)) {
+                let names;
+                try {
+                    names = readdirSync(join(dir, shelf)).filter((n) => n.endsWith(".json"));
+                }
+                catch {
+                    continue;
+                }
+                for (const n of names) {
+                    const { key, record } = JSON.parse(readFileSync(join(dir, shelf, n), "utf8"));
+                    state[shelf][key] = record;
+                    any = true;
+                }
+            }
+            return any ? state : undefined;
+        },
+        put(kind, key, record) {
+            const shelf = join(dir, SHELF[kind]);
+            mkdirSync(shelf, { recursive: true });
+            writeAtomic(join(shelf, `${fileName(key)}.json`), JSON.stringify({ key, record }));
+        },
+        history(machine, id, entry) {
+            const folder = join(dir, "history", fileName(machine));
+            mkdirSync(folder, { recursive: true });
+            appendFileSync(join(folder, `${fileName(id)}.jsonl`), `${JSON.stringify(entry)}\n`);
+        },
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,5 @@
+import type { HistoryEntry, Storage } from "./types.js";
+/** A storage that keeps everything in memory. `history` holds the log by `machine/id`. */
+export declare function memoryStorage(): Storage & {
+    readonly log: Map<string, HistoryEntry[]>;
+};

package/dist/storage.js

@@ -0,0 +1,26 @@
+// In-memory storage (HOST-14): what `nodeFileStorage` does with files,
+// without them; for tests, examples and hosts that persist elsewhere.
+// @zen-component: HOST-JsPackage
+/** A storage that keeps everything in memory. `history` holds the log by `machine/id`. */
+export function memoryStorage() {
+    const state = { sessions: {}, bindings: {}, instances: {} };
+    const log = new Map();
+    let empty = true;
+    const shelf = {
+        session: state.sessions,
+        binding: state.bindings,
+        instance: state.instances,
+    };
+    return {
+        load: () => (empty ? undefined : structuredClone(state)),
+        put(kind, key, record) {
+            shelf[kind][key] = record;
+            empty = false;
+        },
+        history(machine, id, entry) {
+            const key = `${machine}/${id}`;
+            log.set(key, [...(log.get(key) ?? []), entry]);
+        },
+        log,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+/** Where a session is after a call; all `null` in idle. */
+export interface Location {
+    machine: string | null;
+    state: string | null;
+    instance: string | null;
+    ref: string | null;
+}
+/** The answer to a call: the `<smllm>` text for the agent, and where the session is. */
+export interface Reply {
+    /** `false` when the event was rejected or the instance moved. */
+    ok: boolean;
+    session: string;
+    location: Location;
+    text: string;
+}
+/** The stop hook's decision (TURN-4..6). */
+export type StopDecision = {
+    decision: "allow";
+}
+/** `block`: hold the agent and show it `text`; `runaway`: let it stop, show `text` to the user. */
+ | {
+    decision: "block" | "runaway";
+    text: string;
+};
+export interface InstanceStatus {
+    machine: string;
+    kind: string;
+    id: string;
+    ref: string | null;
+    label: string;
+    status: "active" | "interrupted" | "paused" | "completed";
+}
+/** Where a session is, as data (the `smllm statusline --json` object). */
+export interface SessionStatus {
+    session: string;
+    idle: boolean;
+    machine: string | null;
+    state: string | null;
+    visit: number | null;
+    yielded: boolean;
+    instance: InstanceStatus | null;
+    interrupted: InstanceStatus | null;
+    paused: number;
+}
+/** One history entry, handed to `Host.history` as it happens. */
+export interface HistoryEntry {
+    /** Unix ms. */
+    at: number;
+    session: string;
+    event: string;
+    from: string | null;
+    to: string | null;
+    params: Record<string, string>;
+    trace: string[];
+}
+/**
+ * What the engine needs from its host. Every method is optional:
+ * - `supports`, `check`, `run`: host guard/action kinds (`command`); none by default.
+ *   A command's `params.cwd` is relative to the compiled config file (`nodeHost`'s `configDir`).
+ * - `read`: prompt files (`smllm compile` inlines them, so rarely needed).
+ * - `isMatch`: `new RegExp(pattern).test(value)` by default.
+ * - `now`, `random`: `Date.now()` and `crypto.getRandomValues` by default.
+ * - `history`: each history entry as it happens; dropped by default.
+ * - `put`: each session, binding and instance as it is saved (write-through storage); dropped by default.
+ * A method that throws is a host failure the engine reports, never a broken engine.
+ */
+export interface Host {
+    supports?(kind: string): boolean;
+    check?(kind: string, params: Record<string, unknown>, env: Record<string, string>, cwd: string): boolean;
+    /** Nothing (or `""`) on success, else the failure detail. */
+    run?(kind: string, params: Record<string, unknown>, env: Record<string, string>, cwd: string): string | void;
+    read?(file: string): string | undefined;
+    isMatch?(pattern: string, value: string): boolean;
+    now?(): number;
+    random?(): number;
+    history?(machine: string, id: string, entry: HistoryEntry): void;
+    put?(kind: RecordKind, key: string, record: unknown): void;
+}
+/** What `put` hands on: a session (key: its key), a binding (`harness/hostSession`, record: the session key) or an instance (`machine/id`). */
+export type RecordKind = "session" | "binding" | "instance";
+/**
+ * Where an engine's state lives (HOST-14): `load` once, into `importState`;
+ * then each saved record through `put` and each history entry through
+ * `history`, as they happen, so persisting costs what changed.
+ */
+export interface Storage {
+    load(): State | undefined;
+    put(kind: RecordKind, key: string, record: unknown): void;
+    history(machine: string, id: string, entry: HistoryEntry): void;
+}
+/** The agent-facing `smllm` tool: the same definition the MCP server offers. */
+export interface Tool {
+    name: string;
+    description: string;
+    /** JSON Schema of `ToolArgs`. */
+    inputSchema: Record<string, unknown>;
+}
+/** The agent's tool arguments. */
+export interface ToolArgs {
+    session?: string;
+    event?: string;
+    params?: Record<string, string>;
+}
+/** Sessions, bindings and instances by key, as `exportState` returns them and `importState` takes them. */
+export interface State {
+    sessions: Record<string, unknown>;
+    bindings: Record<string, string>;
+    instances: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Types of the typed smllm-wasm API, shared by the web and bundler entry
+// points. They mirror what
+// smllm-core serializes.
+export {};

package/dist/wrap.d.ts

@@ -0,0 +1,64 @@
+import type { Host, RecordKind, Reply, SessionStatus, State, Storage, StopDecision, Tool, ToolArgs } from "./types.js";
+/** The host the wasm calls: strings in, strings out, every method there. */
+export interface RawHost {
+    supports(kind: string): boolean;
+    check(kind: string, params: string, env: string, cwd: string): boolean;
+    run(kind: string, params: string, env: string, cwd: string): string;
+    read(file: string): string | undefined;
+    isMatch(pattern: string, value: string): boolean;
+    now(): number;
+    random(): number;
+    history(machine: string, id: string, entry: string): void;
+    put(kind: RecordKind, key: string, record: string): void;
+}
+/** A build's wasm-bindgen `Engine`: JSON text in and out. */
+export interface RawEngine {
+    tool(): string;
+    callTool(args: string): string;
+    unsupported(): string;
+    bind(harness: string, hostSession: string | null | undefined, cwd: string): string;
+    view(key: string): string;
+    events(key: string): string;
+    status(key: string): string;
+    fire(key: string | null | undefined, event: string, params: string): string;
+    stop(key: string, stopHookActive: boolean): string;
+    promptSubmitted(key: string): void;
+    exportState(): string;
+    importState(state: string): void;
+    free(): void;
+}
+/** A build's wasm-bindgen `Engine` class. */
+export type RawClass = new (compiled: string, host: RawHost) => RawEngine;
+/** smllm's engine over compiled machines (`smllm compile` output). */
+export declare class Engine {
+    #private;
+    /** The build's raw `Engine`: set by the entry module's subclass. */
+    protected static Raw: RawClass;
+    /**
+     * `storage`, when given, is loaded now and then receives every saved
+     * record and history entry (its `put` and `history` go before `host`'s).
+     */
+    constructor(compiled: string | object, host?: Host, storage?: Storage);
+    /** The agent-facing tool, to hand to an LLM's tool list (HOST-13). */
+    tool(): Tool;
+    /** Answer a tool call as the MCP server does; a malformed call is `ok: false`, never a throw. */
+    callTool(args?: ToolArgs): Reply;
+    /** Guard and action kinds the machines use that this host cannot run. */
+    unsupported(): string[];
+    /** Bind a harness session (reused when `hostSession` is already bound). */
+    bind(harness: string, hostSession?: string, cwd?: string): Reply;
+    /** Where the session is; changes nothing. */
+    view(key: string): Reply;
+    /** The events list of the session's state. */
+    events(key: string): Reply;
+    status(key: string): SessionStatus;
+    /** Fire an event; with no key, only `enter` (it starts a session). */
+    fire(key: string | undefined, event: string, params?: Record<string, string>): Reply;
+    stop(key: string, stopHookActive?: boolean): StopDecision;
+    promptSubmitted(key: string): void;
+    exportState(): State;
+    importState(state: State | string): void;
+    /** Free the wasm memory now, rather than when collected. */
+    free(): void;
+    [Symbol.dispose](): void;
+}