@zenalexa/unicli 0.213.1 → 0.213.3

package/dist/engine/harden.js

@@ -0,0 +1,327 @@
+/**
+ * Input hardening — agents hallucinate differently from humans. A typo
+ * like `../../../.ssh` is near-impossible for a person but routine for an
+ * LLM confusing path segments. This module validates the resolved ArgBag
+ * against the schema the adapter *declares*, not regex heuristics on arg
+ * names (v0.213.3: D5 locked — no fallback to `looksLike*`).
+ *
+ * Dispatch order for each string arg:
+ *   1. Always-on: ASCII control-char check (below 0x20, except \t\n\r)
+ *   2. `format: "uri"` (+ the other draft-2020-12 standard formats)
+ *      → ajv format-assertion — fails closed
+ *   3. `x-unicli-kind: "path"`        → validatePathArg (traversal + NUL + sandbox)
+ *   4. `x-unicli-kind: "adapter-ref"` → `<site>/<command>` regex
+ *   5. `x-unicli-kind: "selector"`    → reject `<script` or unescaped backtick
+ *   6. `x-unicli-kind: "shell-safe"`  → reject `$` `` ` `` `;` `|` `&` `>`
+ *   7. `x-unicli-kind: "id"`          → reject URL punctuation (`?` `#`) and
+ *                                        percent-escapes; IDs are bare tokens
+ *   8. If a kind check fails, `x-unicli-accepts` lists secondary kinds
+ *      that can salvage the value (dual-accept fallback).
+ *   9. No format / kind declared → freeform; only the control-char gate
+ *      applies (codemod in Phase 4 migrates YAML adapters; unannotated
+ *      args stay permissive until then).
+ *
+ * Violations throw `InputHardeningError` with a directional suggestion
+ * that completes the self-repair contract (Banach convergence principle).
+ *
+ * NOTE: kept the `InputHardeningError` class and its `{argName, suggestion}`
+ * fields intact — MCP/ACP surfaces depend on them for `structuredContent`.
+ */
+import { isAbsolute, resolve as resolvePath, relative, sep } from "node:path";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+export class InputHardeningError extends Error {
+    argName;
+    suggestion;
+    constructor(message, argName, suggestion) {
+        super(message);
+        this.argName = argName;
+        this.suggestion = suggestion;
+        this.name = "InputHardeningError";
+    }
+}
+/** Does the value contain an ASCII control char we never want to see? */
+function hasControlChars(value) {
+    // Allow \t (0x09), \n (0x0A), \r (0x0D); reject anything else <0x20 or DEL (0x7F).
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if ((c < 0x20 && c !== 0x09 && c !== 0x0a && c !== 0x0d) || c === 0x7f) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Sandbox a path to the current working directory. Absolute paths outside
+ * CWD / home-dir, or any path that escapes CWD via `..`, are rejected.
+ * Explicit home-dir paths (starting with `~`) are allowed after expansion.
+ */
+function validatePathArg(name, value) {
+    if (value.includes("\0")) {
+        throw new InputHardeningError(`path arg "${name}" contains NUL byte`, name, "remove NUL bytes and retry; NUL is never valid in filesystem paths");
+    }
+    // Expand ~ manually; node doesn't do it for us.
+    let expanded = value;
+    if (expanded.startsWith("~")) {
+        expanded =
+            (process.env.HOME ?? process.env.USERPROFILE ?? "") + expanded.slice(1);
+    }
+    const cwd = process.cwd();
+    // Always run through resolvePath so mixed `/` and `\` separators normalize
+    // to the platform's canonical form before any prefix comparison. Without
+    // this, a Windows caller passing `${USERPROFILE}/file.txt` (the literal
+    // shape Node emits when interpolating $HOME on win32) leaves a mid-path `/`
+    // that the normalized `homeDir + sep` ("\\") prefix-match cannot see.
+    const abs = resolvePath(cwd, expanded);
+    const rel = relative(cwd, abs);
+    // Rejected if the relative path starts with `..` AND also isn't within
+    // the user's home directory (agents often legitimately target ~/.unicli).
+    // Use strict boundary match (dir === base || startsWith(base + sep)) so
+    // `$HOME=/Users/foo` does NOT match `/Users/foobar/...` — raw `startsWith`
+    // would allow a prefix-collision escape on shared machines.
+    const homeRaw = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    const homeDir = homeRaw ? resolvePath(homeRaw) : "";
+    const withinHome = Boolean(homeDir && (abs === homeDir || abs.startsWith(homeDir + sep)));
+    const withinCwd = !rel.startsWith("..") && !isAbsolute(rel);
+    if (!withinCwd && !withinHome) {
+        throw new InputHardeningError(`path arg "${name}" escapes CWD and is not inside $HOME: "${value}"`, name, `pass a path inside ${cwd} or inside $HOME (${homeDir})`);
+    }
+}
+/** `<site>/<command>` token (alphanumeric + _ - on each side). */
+function validateAdapterRefArg(name, value) {
+    if (!/^[a-z0-9_-]+\/[a-z0-9_-]+$/.test(value)) {
+        throw new InputHardeningError(`adapter-ref arg "${name}" must match "<site>/<command>": "${value}"`, name, "pass the adapter reference as `<site>/<command>` (lowercase alphanumerics, `_`, `-`)");
+    }
+}
+/** CSS/XPath-ish selector — reject the two punctuations agents use to smuggle code. */
+function validateSelectorArg(name, value) {
+    if (/<script/i.test(value)) {
+        throw new InputHardeningError(`selector arg "${name}" contains "<script" — likely XSS payload: "${value}"`, name, "pass a bare CSS or XPath selector; never include HTML tags");
+    }
+    // Reject any backtick — `querySelector` does not need them and they are
+    // the classic JS template-literal escape.
+    if (/`/.test(value)) {
+        throw new InputHardeningError(`selector arg "${name}" contains backtick — selectors never need them: "${value}"`, name, "remove backticks; use single or double quotes in attribute selectors");
+    }
+}
+/**
+ * Resource id token — reject anything that is a URL fragment rather than a
+ * bare identifier. Agents frequently paste a full URL into an `id` slot; the
+ * adapter then either double-encodes it or 404s. We reject `?`/`#` (query or
+ * fragment) and `%XX` (already URL-encoded). Adapters that legitimately accept
+ * both a bare id AND a URL declare `x-unicli-accepts: [url]` so the URL
+ * salvage path kicks in.
+ */
+function validateIdArg(name, value) {
+    if (/[?#]/.test(value)) {
+        throw new InputHardeningError(`id arg "${name}" contains URL punctuation (? or #): "${value}"`, name, "strip query string/fragment — resource ids are bare tokens, not URLs");
+    }
+    if (/%[0-9a-fA-F]{2}/.test(value)) {
+        throw new InputHardeningError(`id arg "${name}" contains URL-encoded characters (%XX): "${value}"`, name, "strip query string/fragment — resource ids are bare tokens, not URLs");
+    }
+    // A full URL ("https://…") is not a bare id. Adapters that legitimately
+    // accept both a token and a URL declare `x-unicli-accepts: [url]`; the
+    // caller's try/catch salvage path picks that up without widening this
+    // validator's contract.
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+        throw new InputHardeningError(`id arg "${name}" looks like a URL ("${value}") but kind is "id"`, name, "strip query string/fragment — resource ids are bare tokens, not URLs");
+    }
+}
+/** Shell-safe string — reject the injection chars a subprocess arg would expand. */
+function validateShellSafeArg(name, value) {
+    // The order of chars in the regex is irrelevant — we reject any occurrence.
+    // Keep `>` even though stdout redirection requires adjacent space; an
+    // agent that wrote `>` in a shell-safe arg has already misunderstood it.
+    if (/[$`;|&>]/.test(value)) {
+        throw new InputHardeningError(`shell-safe arg "${name}" contains shell metacharacter ($ \` ; | & >): "${value}"`, name, "pass only literal values; the adapter will construct any subprocess args safely");
+    }
+}
+/** Warn (non-throwing) when a URL arg looks double-encoded. */
+function warnDoubleEncoded(name, value) {
+    // Look for %25 followed by two hex — that's `%` itself being encoded twice.
+    if (/%25[0-9a-fA-F]{2}/.test(value)) {
+        return `arg "${name}" looks double-URL-encoded (contains %25XX). Pass a single-encoded or raw URL.`;
+    }
+    return undefined;
+}
+/** Treat URL fallback as "succeeds if it parses as an http(s) URL". */
+function tryAcceptUrl(value) {
+    try {
+        const u = new URL(value);
+        return u.protocol === "http:" || u.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Treat ID fallback as "succeeds if it has no URL punctuation and no percent-escapes". */
+function tryAcceptId(value) {
+    return !/[?#]/.test(value) && !/%[0-9a-fA-F]{2}/.test(value);
+}
+let cachedFormatValidators;
+/**
+ * Lazy-init ajv with the draft-2020-12 format-assertion vocabulary and
+ * build one compiled validator per standard format. Ajv treats `format` as
+ * an annotation by default — opting into `meta/format-assertion` is what
+ * makes it fail-closed (spec §7.3).
+ *
+ * Module-level so that per-arg validation is O(1) once the first call has
+ * primed the cache. The cost is bounded (7 validators total).
+ */
+function getFormatValidators() {
+    if (cachedFormatValidators)
+        return cachedFormatValidators;
+    // Normalise CJS/ESM interop: Node wraps `module.exports = class` as a
+    // default-keyed namespace when imported into an ESM file.
+    const AjvCtor = (Ajv2020.default ??
+        Ajv2020);
+    const addFormatsFn = (addFormats
+        .default ?? addFormats);
+    // `validateFormats: true` with `mode: "full"` makes `format:` a hard
+    // precondition rather than a silent annotation (JSON Schema draft-2020-12
+    // format-assertion semantics, §7.3).
+    const ajv = new AjvCtor({
+        strict: true,
+        allErrors: false,
+        validateFormats: true,
+    });
+    addFormatsFn(ajv, { mode: "full" });
+    const formats = [
+        "uri",
+        "uuid",
+        "date-time",
+        "email",
+        "hostname",
+        "ipv4",
+        "ipv6",
+        "regex",
+    ];
+    const map = new Map();
+    for (const f of formats) {
+        const schema = {
+            $schema: "https://json-schema.org/draft/2020-12/schema",
+            type: "string",
+            format: f,
+        };
+        map.set(f, ajv.compile(schema));
+    }
+    cachedFormatValidators = map;
+    return map;
+}
+function validateFormatArg(name, value, format) {
+    const validator = getFormatValidators().get(format);
+    if (!validator)
+        return;
+    const ok = validator(value);
+    if (ok)
+        return;
+    const detail = validator.errors?.[0]?.message ?? `does not match format "${format}"`;
+    throw new InputHardeningError(`arg "${name}" ${detail}: "${value}"`, name, `pass a value matching JSON Schema format "${format}"`);
+}
+function validateKind(name, value, kind) {
+    switch (kind) {
+        case "path":
+            validatePathArg(name, value);
+            return;
+        case "adapter-ref":
+            validateAdapterRefArg(name, value);
+            return;
+        case "selector":
+            validateSelectorArg(name, value);
+            return;
+        case "shell-safe":
+            validateShellSafeArg(name, value);
+            return;
+        case "id":
+            validateIdArg(name, value);
+            return;
+    }
+}
+/**
+ * Validate the resolved ArgBag against the adapter schema. Returns any
+ * non-fatal warnings (double-encoded URLs, etc.); throws InputHardeningError
+ * for anything unsafe.
+ *
+ * `argByName` is the Map already built by the invocation kernel. Callers
+ * that hold the raw `AdapterArg[]` can pass it directly — the function
+ * tolerates either shape via an internal normalisation.
+ */
+export function hardenArgs(args, schemaOrMap) {
+    const warnings = [];
+    const byName = schemaOrMap instanceof Map
+        ? schemaOrMap
+        : new Map(schemaOrMap.map((a) => [a.name, a]));
+    for (const [name, raw] of Object.entries(args)) {
+        if (typeof raw !== "string")
+            continue;
+        const value = raw;
+        // Always-on control-char gate — applies regardless of kind declaration.
+        if (hasControlChars(value)) {
+            throw new InputHardeningError(`arg "${name}" contains control characters (ASCII <0x20 or 0x7F)`, name, "remove control characters; only \\t \\n \\r are allowed in string args");
+        }
+        const declared = byName.get(name);
+        if (!declared)
+            continue; // unknown field — left freeform until codemod
+        // Standard-vocab format check (fails closed).
+        if (declared.format) {
+            try {
+                validateFormatArg(name, value, declared.format);
+            }
+            catch (err) {
+                if (!(err instanceof InputHardeningError))
+                    throw err;
+                // If the format is `uri` and dual-accept lists `id`, allow a bare
+                // token to pass; otherwise rethrow.
+                const accepts = declared["x-unicli-accepts"] ?? [];
+                if (declared.format === "uri" && accepts.includes("id")) {
+                    if (tryAcceptId(value)) {
+                        // primary failed but secondary passed
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+                else {
+                    throw err;
+                }
+            }
+            // Double-URL-encoding warning applies even on success.
+            if (declared.format === "uri") {
+                const w = warnDoubleEncoded(name, value);
+                if (w)
+                    warnings.push(w);
+            }
+            continue;
+        }
+        // Bespoke kind dispatch.
+        const kind = declared["x-unicli-kind"];
+        if (kind) {
+            try {
+                validateKind(name, value, kind);
+            }
+            catch (err) {
+                if (!(err instanceof InputHardeningError))
+                    throw err;
+                const accepts = declared["x-unicli-accepts"] ?? [];
+                let salvaged = false;
+                for (const alt of accepts) {
+                    if (alt === "url" && tryAcceptUrl(value)) {
+                        salvaged = true;
+                        break;
+                    }
+                    if (alt === "id" && tryAcceptId(value)) {
+                        salvaged = true;
+                        break;
+                    }
+                }
+                if (!salvaged)
+                    throw err;
+            }
+            continue;
+        }
+        // Missing kind declaration = freeform. Codemod (Phase 4) will
+        // annotate the remaining 1324/1355 args.
+    }
+    return { warnings };
+}
+//# sourceMappingURL=harden.js.map

package/dist/engine/harden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harden.js","sourceRoot":"","sources":["../../src/engine/harden.ts"],"names":[],"mappings":"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"}

package/dist/engine/invoke.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Invocation Kernel — backward-compat re-export surface.
+ *
+ * v0.213.3 R2 split this file into `src/engine/kernel/{types,ulid,compile,execute}.ts`
+ * so each concern owns its own 100-220 LOC module. This file exists solely
+ * to keep the historic `src/engine/invoke.js` import path stable for any
+ * external callers (tests, third-party scripts, downstream plugins).
+ *
+ * New code should import from `./kernel/{types,ulid,compile,execute}.js`
+ * directly; the re-export is a compatibility shim, not a recommended path.
+ */
+export type { Invocation, CompiledCommand, InvocationResult, AjvValidateFn, } from "./kernel/types.js";
+export { newULID, _resetULIDForTests } from "./kernel/ulid.js";
+export { compileAll, getCompiled, compileCommand, _resetCompiledCacheForTests, } from "./kernel/compile.js";
+export { buildInvocation, execute, KernelLookupError, } from "./kernel/execute.js";
+//# sourceMappingURL=invoke.d.ts.map

package/dist/engine/invoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.d.ts","sourceRoot":"","sources":["../../src/engine/invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE/D,OAAO,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,eAAe,EACf,OAAO,EACP,iBAAiB,GAClB,MAAM,qBAAqB,CAAC"}

package/dist/engine/invoke.js

@@ -0,0 +1,15 @@
+/**
+ * Invocation Kernel — backward-compat re-export surface.
+ *
+ * v0.213.3 R2 split this file into `src/engine/kernel/{types,ulid,compile,execute}.ts`
+ * so each concern owns its own 100-220 LOC module. This file exists solely
+ * to keep the historic `src/engine/invoke.js` import path stable for any
+ * external callers (tests, third-party scripts, downstream plugins).
+ *
+ * New code should import from `./kernel/{types,ulid,compile,execute}.js`
+ * directly; the re-export is a compatibility shim, not a recommended path.
+ */
+export { newULID, _resetULIDForTests } from "./kernel/ulid.js";
+export { compileAll, getCompiled, compileCommand, _resetCompiledCacheForTests, } from "./kernel/compile.js";
+export { buildInvocation, execute, KernelLookupError, } from "./kernel/execute.js";
+//# sourceMappingURL=invoke.js.map

package/dist/engine/invoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.js","sourceRoot":"","sources":["../../src/engine/invoke.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE/D,OAAO,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,eAAe,EACf,OAAO,EACP,iBAAiB,GAClB,MAAM,qBAAqB,CAAC"}

package/dist/engine/kernel/compile.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Compile step — converts adapter manifests into immutable `CompiledCommand`
+ * entries keyed by `${site}.${cmd}`. Called once at loader boot; every
+ * subsequent invocation looks up O(1).
+ *
+ * Built on ajv 2020-12 strict mode + format-assertion so adapter schemas
+ * fail closed. `x-unicli` extension keywords are stripped before handing to
+ * ajv (strict mode rejects unknowns) but preserved in the introspection
+ * schema returned to describe.ts / MCP tools/list.
+ */
+import type { AdapterCommand, AdapterManifest } from "../../types.js";
+import type { CompiledCommand } from "./types.js";
+/**
+ * Compile one `AdapterCommand` into an immutable `CompiledCommand`. Called
+ * once per command per process; the validator is reused on every call.
+ */
+export declare function compileCommand(cmd: AdapterCommand): CompiledCommand;
+/**
+ * Eagerly compile every (adapter, command) in the registry. Intended to be
+ * called once at the tail of `loadAllAdapters()`; subsequent CLI / MCP /
+ * ACP calls look up by `${site}.${cmd}` in O(1).
+ */
+export declare function compileAll(registry: AdapterManifest[]): Map<string, CompiledCommand>;
+/** Expose the cache read-only for introspection (tests, describe.ts). */
+export declare function getCompiled(site: string, cmd: string): CompiledCommand | undefined;
+/** Internal — used by execute() for lazy cache fill on isolated unit tests. */
+export declare function setCompiled(key: string, compiled: CompiledCommand): void;
+/** Test hook — clear the cache between independent test files. */
+export declare function _resetCompiledCacheForTests(): void;
+//# sourceMappingURL=compile.d.ts.map

package/dist/engine/kernel/compile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/engine/kernel/compile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAEV,cAAc,EACd,eAAe,EAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,YAAY,CAAC;AAmGjE;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,eAAe,CAiCnE;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,eAAe,EAAE,GAC1B,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAQ9B;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,eAAe,GAAG,SAAS,CAE7B;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAExE;AAED,kEAAkE;AAClE,wBAAgB,2BAA2B,IAAI,IAAI,CAElD"}

package/dist/engine/kernel/compile.js

@@ -0,0 +1,167 @@
+/**
+ * Compile step — converts adapter manifests into immutable `CompiledCommand`
+ * entries keyed by `${site}.${cmd}`. Called once at loader boot; every
+ * subsequent invocation looks up O(1).
+ *
+ * Built on ajv 2020-12 strict mode + format-assertion so adapter schemas
+ * fail closed. `x-unicli` extension keywords are stripped before handing to
+ * ajv (strict mode rejects unknowns) but preserved in the introspection
+ * schema returned to describe.ts / MCP tools/list.
+ */
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+let ajvSingleton;
+function getAjv() {
+    if (ajvSingleton)
+        return ajvSingleton;
+    const Ctor = (Ajv2020.default ??
+        Ajv2020);
+    const addFormatsFn = (addFormats
+        .default ?? addFormats);
+    ajvSingleton = new Ctor({
+        strict: true,
+        allErrors: false,
+        validateFormats: true,
+    });
+    addFormatsFn(ajvSingleton, { mode: "full" });
+    return ajvSingleton;
+}
+/** Map adapter-arg type tokens to JSON Schema `type` strings. */
+function jsonSchemaType(t) {
+    switch (t) {
+        case "int":
+            return "integer";
+        case "float":
+            return "number";
+        case "bool":
+            return "boolean";
+        default:
+            return "string";
+    }
+}
+function buildJsonSchema(args) {
+    const properties = {};
+    const required = [];
+    for (const a of args) {
+        const prop = { type: jsonSchemaType(a.type) };
+        if (a.description)
+            prop.description = a.description;
+        if (a.default !== undefined)
+            prop.default = a.default;
+        if (a.choices && a.choices.length > 0)
+            prop.enum = a.choices;
+        if (a.format)
+            prop.format = a.format;
+        // x-unicli-kind / x-unicli-accepts are non-standard extension keywords;
+        // Ajv is strict about unknown keywords, so we pass them through as
+        // annotations under a nested `x-unicli` bag that Ajv's schema cloner
+        // strips before compilation.
+        const ext = {};
+        if (a["x-unicli-kind"])
+            ext.kind = a["x-unicli-kind"];
+        if (a["x-unicli-accepts"])
+            ext.accepts = a["x-unicli-accepts"];
+        if (Object.keys(ext).length > 0)
+            prop["x-unicli"] = ext;
+        properties[a.name] = prop;
+        if (a.required)
+            required.push(a.name);
+    }
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        type: "object",
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+function buildExample(args) {
+    const example = {};
+    for (const a of args) {
+        if (a.default !== undefined) {
+            example[a.name] = a.default;
+        }
+        else if (a.choices && a.choices.length > 0) {
+            example[a.name] = a.choices[0];
+        }
+        else {
+            switch (a.type) {
+                case "int":
+                    example[a.name] = 10;
+                    break;
+                case "float":
+                    example[a.name] = 0.5;
+                    break;
+                case "bool":
+                    example[a.name] = false;
+                    break;
+                default:
+                    example[a.name] = `<${a.name}>`;
+            }
+        }
+    }
+    return example;
+}
+/**
+ * Compile one `AdapterCommand` into an immutable `CompiledCommand`. Called
+ * once per command per process; the validator is reused on every call.
+ */
+export function compileCommand(cmd) {
+    const args = cmd.adapterArgs ?? [];
+    const jsonSchema = buildJsonSchema(args);
+    const ajv = getAjv();
+    // Strip `x-unicli` from the schema passed to Ajv — Ajv's strict mode
+    // rejects unknown keywords, but the original `jsonSchema` (kept for
+    // introspection) preserves them. Clone + prune.
+    const ajvSchema = JSON.parse(JSON.stringify(jsonSchema));
+    const props = ajvSchema.properties;
+    for (const key of Object.keys(props)) {
+        if ("x-unicli" in props[key])
+            delete props[key]["x-unicli"];
+    }
+    const validator = ajv.compile(ajvSchema);
+    const argByName = new Map(args.map((a) => [a.name, a]));
+    return {
+        jsonSchema,
+        example: buildExample(args),
+        channels: ["shell", "file", "stdin"],
+        argByName,
+        validate: (input) => {
+            const ok = validator(input);
+            if (ok)
+                return { ok: true };
+            return {
+                ok: false,
+                errors: validator.errors ?? [],
+            };
+        },
+    };
+}
+const compiledCache = new Map();
+/**
+ * Eagerly compile every (adapter, command) in the registry. Intended to be
+ * called once at the tail of `loadAllAdapters()`; subsequent CLI / MCP /
+ * ACP calls look up by `${site}.${cmd}` in O(1).
+ */
+export function compileAll(registry) {
+    compiledCache.clear();
+    for (const adapter of registry) {
+        for (const [cmdName, cmd] of Object.entries(adapter.commands)) {
+            compiledCache.set(`${adapter.name}.${cmdName}`, compileCommand(cmd));
+        }
+    }
+    return compiledCache;
+}
+/** Expose the cache read-only for introspection (tests, describe.ts). */
+export function getCompiled(site, cmd) {
+    return compiledCache.get(`${site}.${cmd}`);
+}
+/** Internal — used by execute() for lazy cache fill on isolated unit tests. */
+export function setCompiled(key, compiled) {
+    compiledCache.set(key, compiled);
+}
+/** Test hook — clear the cache between independent test files. */
+export function _resetCompiledCacheForTests() {
+    compiledCache.clear();
+}
+//# sourceMappingURL=compile.js.map

package/dist/engine/kernel/compile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compile.js","sourceRoot":"","sources":["../../../src/engine/kernel/compile.ts"],"names":[],"mappings":"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"}

package/dist/engine/kernel/execute.d.ts

@@ -0,0 +1,35 @@
+/**
+ * execute() — the bag-to-envelope pipeline every surface shares.
+ *
+ * Flow per invocation:
+ *   1. ajv validate(bag.args)              → fail-closed USAGE_ERROR on reject
+ *   2. hardenArgs(bag.args, argByName)     → schema-driven hardening
+ *   3. runPipeline() / command.func()      → actual work
+ *   4. build success envelope with live next_actions (runtime, not templated)
+ *
+ * Callers (CLI/MCP/ACP) format the returned `InvocationResult` for their
+ * transport; they do not rebuild envelopes.
+ */
+import type { ResolvedArgs } from "../args.js";
+import type { Invocation, InvocationResult } from "./types.js";
+/**
+ * Raised when execute() is called for a (site, cmd) pair that was not seen
+ * by `compileAll()` at loader boot. Signals a wiring bug (the loader forgot
+ * to prime the cache), not a user error.
+ */
+export declare class KernelLookupError extends Error {
+    constructor(key: string);
+}
+/**
+ * Look up an adapter + command pair and return an Invocation ready for
+ * execute(). Returns `null` if either the site or command is unknown —
+ * callers can emit their own "unknown command" envelope.
+ */
+export declare function buildInvocation(surface: Invocation["surface"], site: string, cmd: string, bag: ResolvedArgs): Invocation | null;
+/**
+ * Run a validated, hardened invocation end-to-end. Failure paths never
+ * throw — every error surfaces as `{ exitCode, error }` on the returned
+ * result so transport code can do uniform error handling.
+ */
+export declare function execute(inv: Invocation): Promise<InvocationResult>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/engine/kernel/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../../src/engine/kernel/execute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAgBH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG/D;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,GAAG,EAAE,MAAM;CAOxB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,GAChB,UAAU,GAAG,IAAI,CAWnB;AAED;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsLxE"}