@six5536/smllm-wasm 0.5.0 → 0.7.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)
@@ -21,7 +23,7 @@ engine:
 ```js
 import init, { Engine, memoryStorage } from "@six5536/smllm-wasm"; // or from "@six5536/smllm-wasm/bundler"
 
-await init(); // the bundler build needs no init
+await init(); // in a browser or Node.js, while the bundler build needs no init
 const compiled = await (await fetch("machines.json")).json(); // `smllm compile`
 const engine = new Engine(
   compiled,
@@ -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.
 
@@ -59,10 +65,16 @@ host leaves the method out:
 - `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`.
+- `checkJson(schema, value)` checks a `json` param's value against its schema, and returns one
+  message for each error, such as `at /steps: [] has fewer than 1 item`, or none when the value
+  passes. The engine refuses an event whose value has errors. The package has no validator of its
+  own, so give it one of yours, such as Ajv's. Without `checkJson`, the engine takes the value
+  unchecked, and `unsupported()` names each `json` param with a schema.
 - `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.
+- `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 +92,149 @@ 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, invoke }`: where the session is, the events
+  that the model can fire, the events that only the host fires, and the host's work that the
+  state invokes. Each event has its `name`, `description`, and `params`, and a JSON param has its
+  bundled `schema` as an object. Each `invoke` has its `src`, the name of the work, and its
+  `input`, an object of fixed values, if the machine gives one: run the work, then fire its result
+  with `fireAsHost`.
+- `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 if (view.invoke.length > 0) {
+    // The state names its work, so the host finds its code by name, not by the state's.
+    for (const { src, input } of view.invoke) await work[src](session, input);
+  } else {
+    throw new Error(`nothing to do in ${view.location.state}`); // a person's step: wait for them
+  }
+}
+```
+
+`work` maps each `src` to the host's code, which fires the work's result:
+
+```js
+const work = {
+  async runChecks(session) {
+    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/index.d.ts

@@ -1,6 +1,11 @@
-import init, { Engine as Raw, initSync } from "../wasm/web/smllm_wasm.js";
+import load, { Engine as Raw, initSync } from "../wasm/web/smllm_wasm.js";
 import { Engine as Base } from "./wrap.js";
-export default init;
+type Input = Parameters<typeof load>[0];
+/**
+ * Load the engine's WebAssembly once. Without an argument, a browser fetches
+ * the package's file, and Node.js, which can't fetch a `file:` URL, reads it.
+ */
+export default function init(input?: Input): ReturnType<typeof load>;
 export { initSync };
 export type * from "./types.js";
 export { memoryStorage } from "./storage.js";

package/dist/index.js

@@ -1,8 +1,23 @@
 // 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 load, { Engine as Raw, initSync } from "../wasm/web/smllm_wasm.js";
 import { Engine as Base } from "./wrap.js";
-export default init;
+// sokf-implements: WASM-6_AC-2
+/**
+ * Load the engine's WebAssembly once. Without an argument, a browser fetches
+ * the package's file, and Node.js, which can't fetch a `file:` URL, reads it.
+ */
+export default async function init(input) {
+    const node = globalThis.process?.versions?.node;
+    if (input === undefined && node) {
+        // A variable keeps a bundler for the browser from resolving `node:fs`.
+        const fs = "node:fs/promises";
+        const { readFile } = (await import(/* @vite-ignore */ fs));
+        const file = new URL("../wasm/web/smllm_wasm_bg.wasm", import.meta.url);
+        return load({ module_or_path: await readFile(file) });
+    }
+    return load(input);
+}
 export { initSync };
 export { memoryStorage } from "./storage.js";
 /** smllm's engine over compiled machines (`smllm compile` output). */

package/dist/types.d.ts

@@ -53,15 +53,58 @@ 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.
  *   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.
+ * - `checkJson`: the errors of a `json` param's value against its schema, one message each, such as
+ *   `at /steps: [] has fewer than 1 item`, and none when the value passes. Without it, the engine takes
+ *   the value unchecked, and `unsupported()` names each such param.
  * - `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 {
@@ -71,22 +114,30 @@ export interface Host {
     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;
+    checkJson?(schema: Record<string, unknown> | boolean, value: unknown): string[];
     now?(): number;
     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 (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 +150,60 @@ 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[];
+    /** The host's work that the state invokes: run each, and fire its result with `fireAsHost`. */
+    invoke: Invoked[];
+}
+/** One piece of the host's work that a state names with `invoke`: its name, and its fixed input. */
+export interface Invoked {
+    src: string;
+    input?: Record<string, unknown>;
+}
+/** 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;
@@ -6,10 +6,14 @@ export interface RawHost {
     run(kind: string, params: string, env: string, cwd: string): string;
     read(file: string): string | undefined;
     isMatch(pattern: string, value: string): boolean;
+    checksJson(): boolean;
+    checkJson(schema: string, value: string): string;
     now(): number;
     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 +25,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,7 +45,8 @@ 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 (WASM-1). */
@@ -47,15 +57,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

@@ -10,6 +10,10 @@ function adapt(host) {
         run: (kind, params, env, cwd) => host.run ? (host.run(kind, parse(params), parse(env), cwd) ?? "") : `${kind} is not supported`,
         read: (file) => host.read?.(file) ?? undefined,
         isMatch: (pattern, value) => host.isMatch ? host.isMatch(pattern, value) : new RegExp(pattern).test(value),
+        checksJson: () => typeof host.checkJson === "function",
+        // `checksJson` guards the call; an answer that isn't a list of strings,
+        // such as `undefined`, reaches the engine as `null`, which refuses it.
+        checkJson: (schema, value) => JSON.stringify(host.checkJson(parse(schema), parse(value)) ?? null),
         now: () => (host.now ? host.now() : Date.now()),
         random: () => (host.random ? host.random() : crypto.getRandomValues(new Uint32Array(1))[0]),
         history: (machine, id, entry) => {
@@ -18,6 +22,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 +35,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,6 +52,15 @@ 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));
@@ -68,7 +86,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));
     }
@@ -79,16 +97,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.5.0",
+  "version": "0.7.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,6 +7,10 @@
 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).
      */
@@ -18,6 +22,12 @@ export class Engine {
      * 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.
      */
@@ -42,6 +62,11 @@ export class Engine {
      * A user prompt arrived.
      */
     promptSubmitted(key: string): void;
+    /**
+     * 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).
      */
@@ -60,7 +85,8 @@ export class Engine {
      */
     tool(): string;
     /**
-     * Guard and action kinds this host cannot run, as a JSON array.
+     * Guard and action kinds this host cannot run, and the `json` params
+     * whose schema it can't check, as a JSON array.
      */
     unsupported(): string;
     /**