@six5536/smllm-wasm 0.4.1 → 0.6.0

package/README.md

@@ -6,11 +6,13 @@ or Node. The large language model (LLM) can run anywhere. The API is typed: it t
 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.
+the host methods, storage, the events that only the host fires, machines that the host drives for
+a model without tools, the Node helpers, and when to use the WebAssembly engine instead of the CLI.
 
 - [Host](#host)
 - [Storage](#storage)
+- [Host-only events](#host-only-events)
+- [Host-driven machines](#host-driven-machines)
 - [Run in Node](#run-in-node)
 - [WebAssembly or CLI](#webassembly-or-cli)
 - [Licence](#licence)
@@ -43,6 +45,10 @@ const stop = engine.stop(session, stopHookActive);
 // "runaway": let it stop, show stop.text to the user; "allow": let it stop.
 ```
 
+A param takes a string. A param that the machine declares with `type: json` takes any JSON value,
+in `callTool`, `fire`, and `fireAsHost`, and the host receives its compact JSON text. A JSON string stays a string, even when its text spells an object. The events list shows
+the param as a JSON value, with its JSON Schema.
+
 The `examples/wasm` folder of the [smllm repository](https://github.com/six5536/smllm) holds a
 whole agent loop, in TypeScript.
 
@@ -63,6 +69,7 @@ host leaves the method out:
 - `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.
+- `wantsAudit()` and `audit(entry, reply)` keep an audit, as the following section describes.
 
 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.
@@ -80,6 +87,133 @@ write.
 IndexedDB, or one that sends the records to a server. `exportState()` and `importState(state)`
 move the whole state at once, for backups and moves.
 
+## Audit
+
+An audit records every call that drove a session, accepted or refused: `bind`, `callTool`,
+`events`, `fire`, `fireAsHost`, and `stop`. `view`, `status`, and `promptSubmitted` record
+nothing. To keep an audit, give the storage or the host `wantsAudit()`, which returns true, and
+`audit(entry, reply)`, which receives each `AuditEntry` and the text of the call's reply:
+
+```ts
+const storage = {
+  ...memoryStorage(),
+  wantsAudit: () => true,
+  audit(entry: AuditEntry, reply: string) {
+    console.log(entry.source, entry.call, entry.event, entry.outcome, entry.reason);
+  },
+};
+```
+
+An entry holds the time, the session, the source (`agent`, or `host` for `fireAsHost`), the call,
+the instance with its states before and after, the params, the names of the events that the reply
+offered, the outcome with the reason for a refusal, and for a call that created the session its
+binding. Keep what you need of the reply's text. A hash names its algorithm, as `sha256:` and the
+hex of the SHA-256 of the text's UTF-8 bytes, which is the default that the `smllm` CLI uses.
+
+## Host-only events
+
+A host-only event is an event that only the host fires, such as the result of checks that the host
+runs outside the machine. A machine marks it with `source: host` in `meta.events`:
+
+```yaml
+meta:
+  smllm: 1
+  events:
+    checksPassed: { source: host }
+    checksFailed: { source: host }
+states:
+  WORK:
+    on: { submit: CHECKING }
+  CHECKING:
+    on: { checksPassed: DONE, checksFailed: WORK }
+  DONE: { type: final }
+```
+
+The agent never sees a host-only event: the events lists of the tool's replies, of `view`, of
+`events`, and of `stop` leave it out. `fire` and `callTool` refuse it with an error that names it
+as an event that only the host fires. The host fires it with `fireAsHost`, which takes the same
+arguments as `fire` and fires any event that the state offers:
+
+```js
+engine.callTool({ session, event: "submit" }); // the agent: WORK → CHECKING
+const passed = await runChecks(); // your own checks, which can be async
+engine.fireAsHost(session, passed ? "checksPassed" : "checksFailed");
+```
+
+Fire an event that the agent chose with `fire` or `callTool`, never with `fireAsHost`, because
+`fireAsHost` would then take a host-only event from the agent. Keep `fireAsHost` for the host's
+own events.
+
+`source: host` is a security boundary only when the host drives a model without tools. An agent
+that runs under a harness, such as Claude Code, usually has a shell, and there the marker
+prevents mistakes rather than an attack. A harness has no host to fire the events, so the smllm
+CLI refuses to start an instance of such a machine, and `smllm validate` notes that the machine
+needs a host to drive it.
+
+## Host-driven machines
+
+A host can drive a machine for a model that has no tools and only answers in text, such as a
+model that the host calls through the Messages API with no tools. The host shows the model the
+state, reads its answer as one event, runs its own checks, and fires the results. Four methods
+serve it, and none of them changes anything:
+
+- `hostView(key)` returns `{ location, model, host }`: where the session is, the events that the
+  model can fire, and the events that only the host fires. Each event has its `name`,
+  `description`, and `params`, and a JSON param has its bundled `schema` as an object.
+- `stateText(key, { schemas })` returns the state's text for the model: its instructions, the
+  model's events with their params, and a request to answer with one event as JSON. Each JSON
+  param shows its schema, unless `schemas` is `false`.
+- `answerSchema(key)` returns a JSON Schema of a valid answer, as an object, for a model that can
+  constrain its output, such as the Claude API's structured outputs.
+- `checkAnswer(key, text)` reads the model's answer, a bare JSON object or one fenced block with
+  nothing outside it. It returns `{ ok: true, event, params }`, whose params are plain
+  JavaScript values ready for `fire`, or `{ ok: false, error }`, whose error the host sends back
+  to the model as it stands. Every malformed answer gets the same error.
+
+This loop runs a machine from start to end. The machine is an extractor builder for bank
+statements, which is in the `examples/extractor` folder of the smllm repository. The model
+answers with an extractor, a JSON value with a schema, or asks for more pages. The host checks
+the extractor and fires `checks_passed` or `checks_failed`, and the machine gives up after five
+attempts:
+
+```js
+const engine = new Engine(compiled, {}, memoryStorage());
+// A keyless `enter` creates the session and starts the machine in one call.
+const { session } = engine.fire(undefined, "enter", { stateMachine: "extractor-build" });
+for (;;) {
+  const view = engine.hostView(session);
+  if (view.location.machine === null) break; // a final state: the session is idle again
+  if (view.model.length > 0) {
+    let prompt = `${engine.stateText(session)}\n${statement}`;
+    for (;;) {
+      const answer = engine.checkAnswer(session, await askModel(prompt)); // your adapter
+      if (answer.ok) {
+        engine.fire(session, answer.event, answer.params); // the model chose the event
+        if (answer.event === "extractor") extractor = answer.params.json;
+        break;
+      }
+      prompt = answer.error; // the refusal, as it stands; count it as an attempt
+    }
+  } else {
+    const errors = await runChecks(extractor); // your checks, which can be async
+    if (errors.length === 0) engine.fireAsHost(session, "checks_passed");
+    else engine.fireAsHost(session, "checks_failed", { errors: errors.join("\n") });
+  }
+}
+```
+
+The model is never offered a built-in event, such as `yield`, `pause`, or `unmatched`, or a
+host-only event, because those belong to whoever drives the session, which here is the host. The
+host fires them as it needs them. An outcome that the model can choose, such as "I can't do this"
+or "ask the user", is an event that the machine declares.
+
+One machine can mix the model's steps, the host's deterministic steps, and a person's steps. A
+state that offers the model events is a step of the model. A state whose events are all the
+host's is a step of the host, such as `CHECKING`, or a person's step, such as an approval for
+which the host fires the person's decision. A state that offers both lists is a step of the model
+that the host can interrupt: the extractor builder's `READ` offers the host `timed_out`, which the
+host fires when the model takes too long.
+
 ## Run in Node
 
 `@six5536/smllm-wasm/node` provides a host and a storage for Node:

package/dist/node/host.d.ts

@@ -1,5 +1,5 @@
 import type { Host } from "../types.js";
-/** `timeoutSecs` default (DEC-5), as the CLI's. */
+/** `timeoutSecs` default (CLI-11), as the CLI's. */
 export declare const DEFAULT_TIMEOUT_SECS = 60;
 /**
  * A host that runs `command` guards and actions. `configDir` is the folder

package/dist/node/host.js

@@ -1,17 +1,16 @@
-// The Node command host (HOST-15): `command` guards
-// and actions run as the CLI runs them (DEC-4..DEC-7). Host methods are
+// The Node command host (WASM-3): `command` guards
+// and actions run as the CLI runs them (CLI-11..CLI-11). 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. */
+/** `timeoutSecs` default (CLI-11), 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). */
@@ -22,6 +21,7 @@ function tail(text) {
     return cut ? `…${s}` : s;
 }
 /** A command's failure text, `""` when it passed. */
+// sokf-implements: WASM-3_AC-1
 function runCommand(params, env, sessionCwd, configDir, timeoutSecs) {
     const run = params.run;
     let argv;

package/dist/node/storage.js

@@ -1,8 +1,7 @@
-// Node file storage (HOST-14): a file per record, written
+// Node file storage (WASM-2): 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 = {

package/dist/storage.js

@@ -1,6 +1,5 @@
-// In-memory storage (HOST-14): what `nodeFileStorage` does with files,
+// In-memory storage (WASM-2): 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: {} };

package/dist/types.d.ts

@@ -13,7 +13,7 @@ export interface Reply {
     location: Location;
     text: string;
 }
-/** The stop hook's decision (TURN-4..6). */
+/** The stop hook's decision (AGT-8..6). */
 export type StopDecision = {
     decision: "allow";
 }
@@ -53,6 +53,43 @@ export interface HistoryEntry {
     params: Record<string, string>;
     trace: string[];
 }
+/**
+ * One audit entry: a call that drove a session, accepted or refused, handed
+ * to `audit` with the text of its reply when the host or the storage wants
+ * an audit.
+ */
+export interface AuditEntry {
+    /** Unix ms. */
+    at: number;
+    session: string;
+    /** `host` for `fireAsHost`, else `agent`. */
+    source: "agent" | "host";
+    /** `view` is a tool call with no event. */
+    call: "bind" | "view" | "menu" | "fire" | "stop";
+    event: string | null;
+    machine: string | null;
+    instance: string | null;
+    /** The instance's state before the call. */
+    from: string | null;
+    /** The state where the session is after the call. */
+    to: string | null;
+    /** Each param as its text, a JSON value as its compact JSON. */
+    params: Record<string, string>;
+    /** The names of the events that the reply offered. */
+    offered: string[];
+    /** `accepted` or `refused`; for `stop`, the decision. */
+    outcome: "accepted" | "refused" | "allow" | "block" | "runaway";
+    /** Why the engine refused the call. */
+    reason: string | null;
+    trace: string[];
+    /** The binding of the session that the call created. */
+    binding: {
+        harness: string;
+        hostSession: string | null;
+        cwd: string;
+        configs: string[];
+    } | null;
+}
 /**
  * What the engine needs from its host. Every method is optional:
  * - `supports`, `check`, `run`: host guard/action kinds (`command`); none by default.
@@ -62,6 +99,9 @@ export interface HistoryEntry {
  * - `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.
+ * - `wantsAudit`, `audit`: whether to keep an audit, false by default, and each audit entry with the
+ *   text of its reply. The host keeps what it likes of the text, such as `sha256:` and the hex of the
+ *   SHA-256 of its UTF-8 bytes, the default that `smllm` uses.
  * A method that throws is a host failure the engine reports, never a broken engine.
  */
 export interface Host {
@@ -75,18 +115,25 @@ export interface Host {
     random?(): number;
     history?(machine: string, id: string, entry: HistoryEntry): void;
     put?(kind: RecordKind, key: string, record: unknown): void;
+    wantsAudit?(): boolean;
+    audit?(entry: AuditEntry, reply: string): 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`;
+ * Where an engine's state lives (WASM-2): `load` once, into `importState`;
  * then each saved record through `put` and each history entry through
- * `history`, as they happen, so persisting costs what changed.
+ * `history`, as they happen, so persisting costs what changed; and, when
+ * `wantsAudit` returns true, each audit entry through `audit`.
  */
 export interface Storage {
     load(): State | undefined;
     put(kind: RecordKind, key: string, record: unknown): void;
     history(machine: string, id: string, entry: HistoryEntry): void;
+    /** Whether the storage keeps an audit; false when absent. */
+    wantsAudit?(): boolean;
+    /** Each audit entry, with the text of the call's reply. */
+    audit?(entry: AuditEntry, reply: string): void;
 }
 /** The agent-facing `smllm` tool: the same definition the MCP server offers. */
 export interface Tool {
@@ -99,8 +146,53 @@ export interface Tool {
 export interface ToolArgs {
     session?: string;
     event?: string;
-    params?: Record<string, string>;
+    /** A string for each param, or any JSON value for a param that the events list shows as a JSON value. */
+    params?: Record<string, unknown>;
 }
+/** How `stateText` renders the state. */
+export interface StateTextOptions {
+    /** Show each JSON param's schema; `true` by default. */
+    schemas?: boolean;
+}
+/** A param of an offered event. */
+export interface OfferedParam {
+    name: string;
+    required: boolean;
+    /** `json`: the param takes any JSON value. */
+    type: "string" | "json";
+    /** The allowed values; empty when any string is allowed. */
+    enum: string[];
+    pattern: string | null;
+    description: string | null;
+    /** A JSON param's JSON Schema, bundled, or `null`. */
+    schema: Record<string, unknown> | boolean | null;
+}
+/** An event that the state offers. */
+export interface Offered {
+    name: string;
+    description: string | null;
+    params: OfferedParam[];
+}
+/**
+ * The state as a host that drives the machine sees it: the events that the
+ * model can answer with, and the events that only the host fires (with
+ * `fireAsHost`). Neither list holds the built-in events, which the host
+ * fires as it needs them.
+ */
+export interface HostView {
+    location: Location;
+    model: Offered[];
+    host: Offered[];
+}
+/** A model's answer, checked: the event and its params, ready for `fire`, or the refusal to send back to the model. */
+export type CheckedAnswer = {
+    ok: true;
+    event: string;
+    params: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
 /** Sessions, bindings and instances by key, as `exportState` returns them and `importState` takes them. */
 export interface State {
     sessions: Record<string, unknown>;

package/dist/wrap.d.ts

@@ -1,4 +1,4 @@
-import type { Host, RecordKind, Reply, SessionStatus, State, Storage, StopDecision, Tool, ToolArgs } from "./types.js";
+import type { CheckedAnswer, Host, HostView, RecordKind, Reply, SessionStatus, State, StateTextOptions, 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;
@@ -10,6 +10,8 @@ export interface RawHost {
     random(): number;
     history(machine: string, id: string, entry: string): void;
     put(kind: RecordKind, key: string, record: string): void;
+    wantsAudit(): boolean;
+    audit(entry: string, reply: string): void;
 }
 /** A build's wasm-bindgen `Engine`: JSON text in and out. */
 export interface RawEngine {
@@ -21,8 +23,13 @@ export interface RawEngine {
     events(key: string): string;
     status(key: string): string;
     fire(key: string | null | undefined, event: string, params: string): string;
+    fireAsHost(key: string | null | undefined, event: string, params: string): string;
     stop(key: string, stopHookActive: boolean): string;
     promptSubmitted(key: string): void;
+    stateText(key: string, schemas: boolean): string;
+    answerSchema(key: string): string;
+    checkAnswer(key: string, text: string): string;
+    hostView(key: string): string;
     exportState(): string;
     importState(state: string): void;
     free(): void;
@@ -36,10 +43,11 @@ export declare class Engine {
     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).
+     * record and history entry, and each audit entry when it wants an audit
+     * (its `put`, `history` and `audit` 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). */
+    /** The agent-facing tool, to hand to an LLM's tool list (WASM-1). */
     tool(): Tool;
     /** Answer a tool call as the MCP server does; a malformed call is `ok: false`, never a throw. */
     callTool(args?: ToolArgs): Reply;
@@ -47,15 +55,41 @@ export declare class Engine {
     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. */
+    /** Where the session is; changes nothing and records no audit entry. A look of the agent's is `callTool` with no event. */
     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;
+    /**
+     * Fire an event for the agent; with no key, only `enter` (it starts a
+     * session). An event that the machine marks with `source: host` is
+     * refused: fire it with `fireAsHost`. Fire an event that the agent chose
+     * here, never with `fireAsHost`. A param takes a string, or any JSON
+     * value when the events list shows it as a JSON value.
+     */
+    fire(key: string | undefined, event: string, params?: Record<string, unknown>): Reply;
+    /**
+     * Fire an event as the host: as `fire`, and also an event that the machine
+     * marks with `source: host`, such as the result of the host's own checks.
+     */
+    fireAsHost(key: string | undefined, event: string, params?: Record<string, unknown>): Reply;
     stop(key: string, stopHookActive?: boolean): StopDecision;
     promptSubmitted(key: string): void;
+    /**
+     * The state's text for a model without tools: its instructions, the
+     * events that the model can answer with, and how to answer. Each JSON
+     * param shows its schema unless `schemas` is `false`.
+     */
+    stateText(key: string, options?: StateTextOptions): string;
+    /** The JSON Schema of a valid answer: a `oneOf` with one branch for each event of the model. */
+    answerSchema(key: string): Record<string, unknown>;
+    /**
+     * Check the model's text answer: the event and its params, ready for
+     * `fire`, or a refusal to send back to the model. It fires nothing.
+     */
+    checkAnswer(key: string, text: string): CheckedAnswer;
+    /** The state's offered events in two lists: the model's, and the host's own. */
+    hostView(key: string): HostView;
     exportState(): State;
     importState(state: State | string): void;
     /** Free the wasm memory now, rather than when collected. */

package/dist/wrap.js

@@ -18,6 +18,10 @@ function adapt(host) {
         put: (kind, key, record) => {
             host.put?.(kind, key, parse(record));
         },
+        wantsAudit: () => Boolean(host.wantsAudit?.()),
+        audit: (entry, reply) => {
+            host.audit?.(parse(entry), reply);
+        },
     };
 }
 /** smllm's engine over compiled machines (`smllm compile` output). */
@@ -27,7 +31,8 @@ export class Engine {
     #raw;
     /**
      * `storage`, when given, is loaded now and then receives every saved
-     * record and history entry (its `put` and `history` go before `host`'s).
+     * record and history entry, and each audit entry when it wants an audit
+     * (its `put`, `history` and `audit` go before `host`'s).
      */
     constructor(compiled, host = {}, storage) {
         const json = typeof compiled === "string" ? compiled : JSON.stringify(compiled);
@@ -43,15 +48,25 @@ export class Engine {
                     storage.history(machine, id, entry);
                     host.history?.(machine, id, entry);
                 },
+                wantsAudit: () => Boolean(storage.wantsAudit?.() || host.wantsAudit?.()),
+                audit: (entry, reply) => {
+                    if (storage.wantsAudit?.()) {
+                        storage.audit?.(entry, reply);
+                    }
+                    if (host.wantsAudit?.()) {
+                        host.audit?.(entry, reply);
+                    }
+                },
             }
             : host;
         this.#raw = new Raw(json, adapt(all));
+        // sokf-implements: WASM-2_AC-2
         const saved = storage?.load();
         if (saved) {
             this.importState(saved);
         }
     }
-    /** The agent-facing tool, to hand to an LLM's tool list (HOST-13). */
+    /** The agent-facing tool, to hand to an LLM's tool list (WASM-1). */
     tool() {
         return parse(this.#raw.tool());
     }
@@ -67,7 +82,7 @@ export class Engine {
     bind(harness, hostSession, cwd = "") {
         return parse(this.#raw.bind(harness, hostSession, cwd));
     }
-    /** Where the session is; changes nothing. */
+    /** Where the session is; changes nothing and records no audit entry. A look of the agent's is `callTool` with no event. */
     view(key) {
         return parse(this.#raw.view(key));
     }
@@ -78,16 +93,52 @@ export class Engine {
     status(key) {
         return parse(this.#raw.status(key));
     }
-    /** Fire an event; with no key, only `enter` (it starts a session). */
+    /**
+     * Fire an event for the agent; with no key, only `enter` (it starts a
+     * session). An event that the machine marks with `source: host` is
+     * refused: fire it with `fireAsHost`. Fire an event that the agent chose
+     * here, never with `fireAsHost`. A param takes a string, or any JSON
+     * value when the events list shows it as a JSON value.
+     */
     fire(key, event, params = {}) {
         return parse(this.#raw.fire(key, event, JSON.stringify(params)));
     }
+    /**
+     * Fire an event as the host: as `fire`, and also an event that the machine
+     * marks with `source: host`, such as the result of the host's own checks.
+     */
+    fireAsHost(key, event, params = {}) {
+        return parse(this.#raw.fireAsHost(key, event, JSON.stringify(params)));
+    }
     stop(key, stopHookActive = false) {
         return parse(this.#raw.stop(key, stopHookActive));
     }
     promptSubmitted(key) {
         this.#raw.promptSubmitted(key);
     }
+    /**
+     * The state's text for a model without tools: its instructions, the
+     * events that the model can answer with, and how to answer. Each JSON
+     * param shows its schema unless `schemas` is `false`.
+     */
+    stateText(key, options = {}) {
+        return this.#raw.stateText(key, options.schemas ?? true);
+    }
+    /** The JSON Schema of a valid answer: a `oneOf` with one branch for each event of the model. */
+    answerSchema(key) {
+        return parse(this.#raw.answerSchema(key));
+    }
+    /**
+     * Check the model's text answer: the event and its params, ready for
+     * `fire`, or a refusal to send back to the model. It fires nothing.
+     */
+    checkAnswer(key, text) {
+        return parse(this.#raw.checkAnswer(key, text));
+    }
+    /** The state's offered events in two lists: the model's, and the host's own. */
+    hostView(key) {
+        return parse(this.#raw.hostView(key));
+    }
     exportState() {
         return parse(this.#raw.exportState());
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@six5536/smllm-wasm",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "smllm's engine as WebAssembly: run smllm state machines that drive an LLM agent, in a browser or Node.",
   "homepage": "https://github.com/six5536/smllm#readme",
   "repository": {

package/wasm/bundler/smllm_wasm.d.ts

@@ -7,17 +7,27 @@
 export class Engine {
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * The JSON Schema of a valid answer, as JSON (ENG-8).
+     */
+    answerSchema(key: string): string;
     /**
      * Bind a session; returns the reply JSON (its `session` is the key).
      */
     bind(harness: string, host_session: string | null | undefined, cwd: string): string;
     /**
      * A tool call: the agent's arguments as JSON, answered as the MCP
-     * server answers them (HOST-13). A malformed call or an engine error is
+     * server answers them (WASM-1). A malformed call or an engine error is
      * a reply with `ok: false` and `error: …`, never a throw: the agent
      * sees its mistake as the tool's answer.
      */
     callTool(args: string): string;
+    /**
+     * A model's answer checked (ENG-9), as JSON: `{"ok": true, "event",
+     * "params"}`, whose params are JSON values ready for `fire`, or
+     * `{"ok": false, "error"}`.
+     */
+    checkAnswer(key: string, text: string): string;
     /**
      * The events list.
      */
@@ -27,9 +37,19 @@ export class Engine {
      */
     exportState(): string;
     /**
-     * Fire an event; `params` is a JSON object of strings.
+     * Fire an event as the host, host-only events included (ENG-6).
+     */
+    fireAsHost(key: string | null | undefined, event: string, params: string): string;
+    /**
+     * Fire an event for the agent; `params` is a JSON object, of strings
+     * except for a JSON param's value.
      */
     fire(key: string | null | undefined, event: string, params: string): string;
+    /**
+     * The state's offered events in two lists, the model's and the
+     * host's, with where the session is, as JSON (ENG-10).
+     */
+    hostView(key: string): string;
     /**
      * Replace the store from [`Engine::export_state`] JSON.
      */
@@ -43,11 +63,16 @@ export class Engine {
      */
     promptSubmitted(key: string): void;
     /**
-     * Where the session is, as the `smllm statusline --json` object (STL-8).
+     * The state's text for a model without tools; `schemas` shows each
+     * JSON param's schema (ENG-7).
+     */
+    stateText(key: string, schemas: boolean): string;
+    /**
+     * Where the session is, as the `smllm statusline --json` object (ENG-3).
      */
     status(key: string): string;
     /**
-     * The stop decision as JSON (TURN-4..6): `{"decision": "allow"}` = may
+     * The stop decision as JSON (AGT-8..6): `{"decision": "allow"}` = may
      * stop; `{"decision": "block", "text"}` = hold the agent with the events
      * list; `{"decision": "runaway", "text"}` = let it stop, showing the
      * list to the user (the harness was already continuing because of a
@@ -56,7 +81,7 @@ export class Engine {
     stop(key: string, stop_hook_active: boolean): string;
     /**
      * The agent-facing tool, as JSON `{name, description, inputSchema}`:
-     * the core's definition, as the MCP server offers it (HOST-13).
+     * the core's definition, as the MCP server offers it (WASM-1).
      */
     tool(): string;
     /**