@six5536/smllm-wasm 0.6.0 → 0.7.0

package/README.md

@@ -23,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,
@@ -65,6 +65,11 @@ 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
@@ -157,9 +162,12 @@ model that the host calls through the Messages API with no tools. The host shows
 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.
+- `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`.
@@ -194,12 +202,25 @@ for (;;) {
       }
       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

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

@@ -96,6 +96,9 @@ export interface AuditEntry {
  *   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.
@@ -111,6 +114,7 @@ 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;
@@ -183,6 +187,13 @@ 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 = {

package/dist/wrap.d.ts

@@ -6,6 +6,8 @@ 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;

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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@six5536/smllm-wasm",
-  "version": "0.6.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

@@ -85,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;
     /**

package/wasm/bundler/smllm_wasm_bg.js

@@ -484,7 +484,8 @@ export class Engine {
         }
     }
     /**
-     * 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.
      * @returns {string}
      */
     unsupported() {
@@ -540,7 +541,7 @@ export function __wbg_Error_30c8987f7c2ed4e2(arg0, arg1) {
     const ret = Error(getStringFromWasm0(arg0, arg1));
     return addHeapObject(ret);
 }
-export function __wbg_String_a5249499d8036ec9(arg0, arg1) {
+export function __wbg_String_cecff35e2c01b558(arg0, arg1) {
     const ret = String(getObject(arg1));
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
     const len1 = WASM_VECTOR_LEN;
@@ -550,50 +551,61 @@ export function __wbg_String_a5249499d8036ec9(arg0, arg1) {
 export function __wbg___wbindgen_throw_41e9ee4f547fc59a(arg0, arg1) {
     throw new Error(getStringFromWasm0(arg0, arg1));
 }
-export function __wbg_audit_85f5bb21263e0644() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+export function __wbg_audit_74e1db6cf5830646() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
     getObject(arg0).audit(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4));
 }, arguments); }
-export function __wbg_check_e9ea28c77bd41729() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) {
+export function __wbg_checkJson_c347a4633ef4d106() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5) {
+    const ret = getObject(arg1).checkJson(getStringFromWasm0(arg2, arg3), getStringFromWasm0(arg4, arg5));
+    const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+    const len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+}, arguments); }
+export function __wbg_check_74d9bb5986e4c1a9() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) {
     const ret = getObject(arg0).check(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4), getStringFromWasm0(arg5, arg6), getStringFromWasm0(arg7, arg8));
     return ret;
 }, arguments); }
-export function __wbg_history_ba99161437b60e0e() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
+export function __wbg_checksJson_071fcacbc23698af() { return handleError(function (arg0) {
+    const ret = getObject(arg0).checksJson();
+    return ret;
+}, arguments); }
+export function __wbg_history_9012f84a8f46c83e() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
     getObject(arg0).history(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4), getStringFromWasm0(arg5, arg6));
 }, arguments); }
-export function __wbg_isMatch_57a619cdd9087ba8() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+export function __wbg_isMatch_b1e6bbf6ef4ec3ce() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
     const ret = getObject(arg0).isMatch(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4));
     return ret;
 }, arguments); }
-export function __wbg_now_1a669daa685d184d() { return handleError(function (arg0) {
+export function __wbg_now_0d9ea04a799ba8a3() { return handleError(function (arg0) {
     const ret = getObject(arg0).now();
     return ret;
 }, arguments); }
-export function __wbg_put_8270908aa8f03c2a() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
+export function __wbg_put_ba72b914046f9b1a() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
     getObject(arg0).put(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4), getStringFromWasm0(arg5, arg6));
 }, arguments); }
-export function __wbg_random_a2849827a284f2d5() { return handleError(function (arg0) {
+export function __wbg_random_ec8c8b37b8f3fa25() { return handleError(function (arg0) {
     const ret = getObject(arg0).random();
     return ret;
 }, arguments); }
-export function __wbg_read_e79d6ea23600ac6f() { return handleError(function (arg0, arg1, arg2, arg3) {
+export function __wbg_read_cf7e62e7d878815d() { return handleError(function (arg0, arg1, arg2, arg3) {
     const ret = getObject(arg1).read(getStringFromWasm0(arg2, arg3));
     var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
     var len1 = WASM_VECTOR_LEN;
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }, arguments); }
-export function __wbg_run_e1681363901db5c8() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) {
+export function __wbg_run_2af5a6bf612a4f65() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) {
     const ret = getObject(arg1).run(getStringFromWasm0(arg2, arg3), getStringFromWasm0(arg4, arg5), getStringFromWasm0(arg6, arg7), getStringFromWasm0(arg8, arg9));
     const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
     const len1 = WASM_VECTOR_LEN;
     getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
     getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
 }, arguments); }
-export function __wbg_supports_5e904725127552cf() { return handleError(function (arg0, arg1, arg2) {
+export function __wbg_supports_0949a8c83c0fdd6d() { return handleError(function (arg0, arg1, arg2) {
     const ret = getObject(arg0).supports(getStringFromWasm0(arg1, arg2));
     return ret;
 }, arguments); }
-export function __wbg_wantsAudit_27e6b386da9d3696() { return handleError(function (arg0) {
+export function __wbg_wantsAudit_0cc52731beef3c65() { return handleError(function (arg0) {
     const ret = getObject(arg0).wantsAudit();
     return ret;
 }, arguments); }

package/wasm/web/smllm_wasm.d.ts

@@ -85,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;
     /**

package/wasm/web/smllm_wasm.js

@@ -486,7 +486,8 @@ export class Engine {
         }
     }
     /**
-     * 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.
      * @returns {string}
      */
     unsupported() {
@@ -545,7 +546,7 @@ function __wbg_get_imports() {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
         },
-        __wbg_String_a5249499d8036ec9: function(arg0, arg1) {
+        __wbg_String_cecff35e2c01b558: function(arg0, arg1) {
             const ret = String(getObject(arg1));
             const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len1 = WASM_VECTOR_LEN;
@@ -555,50 +556,61 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_41e9ee4f547fc59a: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_audit_85f5bb21263e0644: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+        __wbg_audit_74e1db6cf5830646: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
             getObject(arg0).audit(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4));
         }, arguments); },
-        __wbg_check_e9ea28c77bd41729: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) {
+        __wbg_checkJson_c347a4633ef4d106: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5) {
+            const ret = getObject(arg1).checkJson(getStringFromWasm0(arg2, arg3), getStringFromWasm0(arg4, arg5));
+            const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len1 = WASM_VECTOR_LEN;
+            getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+            getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+        }, arguments); },
+        __wbg_check_74d9bb5986e4c1a9: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8) {
             const ret = getObject(arg0).check(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4), getStringFromWasm0(arg5, arg6), getStringFromWasm0(arg7, arg8));
             return ret;
         }, arguments); },
-        __wbg_history_ba99161437b60e0e: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
+        __wbg_checksJson_071fcacbc23698af: function() { return handleError(function (arg0) {
+            const ret = getObject(arg0).checksJson();
+            return ret;
+        }, arguments); },
+        __wbg_history_9012f84a8f46c83e: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
             getObject(arg0).history(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4), getStringFromWasm0(arg5, arg6));
         }, arguments); },
-        __wbg_isMatch_57a619cdd9087ba8: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
+        __wbg_isMatch_b1e6bbf6ef4ec3ce: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4) {
             const ret = getObject(arg0).isMatch(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4));
             return ret;
         }, arguments); },
-        __wbg_now_1a669daa685d184d: function() { return handleError(function (arg0) {
+        __wbg_now_0d9ea04a799ba8a3: function() { return handleError(function (arg0) {
             const ret = getObject(arg0).now();
             return ret;
         }, arguments); },
-        __wbg_put_8270908aa8f03c2a: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
+        __wbg_put_ba72b914046f9b1a: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6) {
             getObject(arg0).put(getStringFromWasm0(arg1, arg2), getStringFromWasm0(arg3, arg4), getStringFromWasm0(arg5, arg6));
         }, arguments); },
-        __wbg_random_a2849827a284f2d5: function() { return handleError(function (arg0) {
+        __wbg_random_ec8c8b37b8f3fa25: function() { return handleError(function (arg0) {
             const ret = getObject(arg0).random();
             return ret;
         }, arguments); },
-        __wbg_read_e79d6ea23600ac6f: function() { return handleError(function (arg0, arg1, arg2, arg3) {
+        __wbg_read_cf7e62e7d878815d: function() { return handleError(function (arg0, arg1, arg2, arg3) {
             const ret = getObject(arg1).read(getStringFromWasm0(arg2, arg3));
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             var len1 = WASM_VECTOR_LEN;
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         }, arguments); },
-        __wbg_run_e1681363901db5c8: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) {
+        __wbg_run_2af5a6bf612a4f65: function() { return handleError(function (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9) {
             const ret = getObject(arg1).run(getStringFromWasm0(arg2, arg3), getStringFromWasm0(arg4, arg5), getStringFromWasm0(arg6, arg7), getStringFromWasm0(arg8, arg9));
             const ptr1 = passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len1 = WASM_VECTOR_LEN;
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         }, arguments); },
-        __wbg_supports_5e904725127552cf: function() { return handleError(function (arg0, arg1, arg2) {
+        __wbg_supports_0949a8c83c0fdd6d: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = getObject(arg0).supports(getStringFromWasm0(arg1, arg2));
             return ret;
         }, arguments); },
-        __wbg_wantsAudit_27e6b386da9d3696: function() { return handleError(function (arg0) {
+        __wbg_wantsAudit_0cc52731beef3c65: function() { return handleError(function (arg0) {
             const ret = getObject(arg0).wantsAudit();
             return ret;
         }, arguments); },