skillscript-runtime 0.15.7 → 0.16.0

package/dist/runtime.js

@@ -6,7 +6,7 @@ import { validateQualifiedDispatch } from "./dispatch-validate.js";
 import { spawn } from "node:child_process";
 import { readFile as fsReadFile, writeFile as fsWriteFile, mkdir as fsMkdir } from "node:fs/promises";
 import { dirname as pathDirname } from "node:path";
-import { OpError, ConnectorNotFoundError, OpTimeoutError, InteractiveOpInAutonomousModeError, UnsafeShellDisabledError, UnresolvedVariableError, TypeMismatchError, MissingSkillReferenceError, UnconfirmedMutationError, messageOf, } from "./errors.js";
+import { OpError, ConnectorNotFoundError, OpTimeoutError, UnsafeShellDisabledError, UnresolvedVariableError, TypeMismatchError, MissingSkillReferenceError, UnconfirmedMutationError, messageOf, } from "./errors.js";
 import { classifyMutation, authorizationGranted, buildAuthorizationSuggestion, } from "./mutation-gate.js";
 import { TraceBuilder, shouldTraceFire } from "./trace.js";
 /**
@@ -112,12 +112,11 @@ export async function execute(parsed, initialVars, order, ctx) {
             continue;
         let targetLastBound = null;
         let targetLastValue = undefined;
-        // v0.14.1 — fresh mutation-auth state per target. `skillAutonomous`
-        // is set from the parsed header; `sawConfirm` resets so a `??` in
-        // target T1 doesn't authorize mutations in T2 (correct scope).
+        // Fresh mutation-auth state per target. `skillAutonomous` is set from
+        // the parsed header. v0.16.0 retired the `sawConfirm` path with the
+        // `ask` op removal.
         const authState = {
             skillAutonomous: parsed.autonomous === true,
-            sawConfirm: false,
         };
         try {
             const r = await execOps(target.ops, vars, emissions, fallbacks, ctx, targetName, parsed.timeout, absoluteTimeoutMs, traceBuilder, authState);
@@ -276,15 +275,11 @@ async function execOps(ops, vars, emissions, fallbacks, ctx, targetName, skillTi
     let lastBoundVar = null;
     let lastValue = undefined;
     for (const op of ops) {
-        // v0.14.1 Layer A — load-bearing mutation gate. Flip `sawConfirm` for the
-        // current op iteration in lint-parity order (`??` flips before its own
-        // gate check) so a `??` op's own classification path stays consistent
-        // with lint. Non-mutation `??` skips the throw branch naturally.
-        if (op.kind === "??")
-            authState.sawConfirm = true;
+        // v0.16.0 — `ask` removed; mutation gate now relies solely on `approved=`
+        // per-op kwarg + `# Autonomous: true` skill flag (sawConfirm path retired).
         const mutKind = classifyMutation(op);
         if (mutKind !== null && !authorizationGranted(op, authState)) {
-            throw new UnconfirmedMutationError(mutKind.kind, mutKind.detail, ["# Autonomous: true header", "preceding ?? / ask() in same target", "approved=\"reason\" per-op kwarg"], buildAuthorizationSuggestion(mutKind), op.kind, targetName);
+            throw new UnconfirmedMutationError(mutKind.kind, mutKind.detail, ["# Autonomous: true header", "approved=\"reason\" per-op kwarg"], buildAuthorizationSuggestion(mutKind), op.kind, targetName);
         }
         const r = await execOp(op, vars, emissions, fallbacks, ctx, targetName, skillTimeoutSec, absoluteTimeoutMs, traceBuilder, authState);
         if (r.lastBoundVar !== null) {
@@ -327,16 +322,13 @@ async function execOp(op, vars, emissions, fallbacks, ctx, targetName, skillTime
         }
     }
 }
-/** Extract the connector instance name for $/~/> ops; undefined for others. */
+/** Extract the connector instance name for `$` ops; undefined for others. */
 function extractOpConnector(op) {
-    switch (op.kind) {
-        case "$": return op.mcpConnector ?? "primary";
-        case "~": return op.localModelParams?.model ?? "default";
-        case ">": return op.retrievalParams?.connector ?? "primary";
-        default: return undefined;
-    }
+    if (op.kind === "$")
+        return op.mcpConnector ?? "primary";
+    return undefined;
 }
-async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skillTimeoutSec, absoluteTimeoutMs, traceBuilder, authState = { skillAutonomous: false, sawConfirm: false }) {
+async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skillTimeoutSec, absoluteTimeoutMs, traceBuilder, authState = { skillAutonomous: false }) {
     switch (op.kind) {
         case "$set": {
             // v0.5.0 item 3 — `$set X = "...$(REF)..."` now resolves $(REF) at
@@ -392,12 +384,12 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             emissions.push(`Reason: ${body}`);
             return { lastBoundVar: null, lastValue: undefined };
         }
-        case "!": {
+        case "emit": {
             const body = substituteRuntime(op.body, vars);
             emissions.push(body);
             return { lastBoundVar: null, lastValue: undefined };
         }
-        case "@": {
+        case "shell": {
             const body = op.policy === "unsafe"
                 ? substituteRuntimeUnsafe(op.body, vars)
                 : substituteRuntime(op.body, vars);
@@ -405,8 +397,6 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             if (ctx.mechanical === true) {
                 const label = op.policy === "unsafe" ? "Would run unsafe shell" : "Would run shell";
                 emissions.push(`${label}: ${body} (mechanical: true preview).`);
-                // Bind a placeholder so downstream `$(VAR)` substitutions resolve.
-                // Matches the convention used by `$`/`~`/`>` mechanical-mode binding.
                 const flatKey = `${targetName}.output`;
                 const placeholder = `[mechanical: would run ${body.slice(0, 40)}${body.length > 40 ? "..." : ""}]`;
                 vars.set(flatKey, placeholder);
@@ -427,7 +417,7 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             else {
                 const tokens = tokenizeShellArgs(body);
                 if (tokens.length === 0) {
-                    throw new OpError(`Empty \`@\` op body in target '${targetName}'.`, "@", "Provide a shell command body, e.g., `@ echo hello`.", targetName);
+                    throw new OpError(`Empty \`shell(...)\` op body in target '${targetName}'.`, "shell", "Provide a non-empty `command=\"...\"` kwarg.", targetName);
                 }
                 const [bin, ...args] = tokens;
                 stdout = await execShellCommand(bin, args, shellTimeoutMs);
@@ -441,41 +431,14 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                 lastValue: stdout,
             };
         }
-        case "??": {
-            const promptStr = substituteRuntime(op.body, vars);
-            if (ctx.askUser === undefined) {
-                // Autonomous mode — no interactive surface wired. Per decision 6 +
-                // §6 dispatcher routing, `??` fails fast so dependent targets don't
-                // silently fall through.
-                throw new InteractiveOpInAutonomousModeError(promptStr, targetName);
-            }
-            const response = await ctx.askUser(promptStr);
-            const outName = op.outputVar;
-            if (outName !== undefined)
-                vars.set(outName, response);
-            // Decline semantics (per Section 2 Ops + §13 Open Q #2 resolution):
-            // bind the response AND short-circuit downstream via soft op-error
-            // routed through else: / # OnError:. Closes the silent-fall-through
-            // security bug pattern (subsequent `apply:` running on a "no").
-            if (isDeclineResponse(response)) {
-                throw new OpError(`User declined at \`??\` prompt: '${promptStr}' (response: '${response}'). Dependent targets short-circuited.`, "??", "If decline should not short-circuit, handle the response in an `else:` branch or `# OnError:` fallback.", targetName);
-            }
-            return {
-                lastBoundVar: outName ?? null,
-                lastValue: response,
-            };
-        }
-        case "&": {
-            // v0.3.1: deferred-resolution path. `&` ops that reached runtime
-            // are either (a) forward-references that compile couldn't inline
-            // because the target wasn't yet stored, or (b) the rare "raw AST
-            // bypassed compile()" case. Try to resolve through a SkillStore on
-            // the context if one is wired; otherwise throw MissingSkillReferenceError
-            // with the structured fields so `# OnError:` can catch.
+        case "inline": {
+            // Deferred-resolution path. `inline` ops that reached runtime are
+            // either (a) forward-references that compile couldn't inline because
+            // the target wasn't yet stored, or (b) the rare "raw AST bypassed
+            // compile()" case. Surface as MissingSkillReferenceError so `# OnError:`
+            // can catch.
             const skillName = op.ampParams?.skillName ?? "(unknown)";
-            // No store wired = can't resolve. Surface as MissingSkillReferenceError
-            // for consistency (same shape as runtime resolve-and-miss path).
-            throw new MissingSkillReferenceError(skillName, "&", "&", targetName);
+            throw new MissingSkillReferenceError(skillName, "inline", "inline", targetName);
         }
         case "file_read": {
             // v0.7.0 — runtime-intrinsic file read. Substitutes `${VAR}` /
@@ -647,6 +610,18 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             const toolName = m[1];
             const argsStr = m[2] ?? "";
             const args = parseToolArgs(argsStr);
+            // v0.16.0 — op-level `timeout=N` kwarg reserved for `$` dispatch (parity
+            // with legacy `~` `timeoutSeconds`). Pop from args before forwarding so
+            // connectors don't see a kwarg they didn't declare. Accepts int literal
+            // or `$(VAR)` / `${VAR}` ref string; resolveOpTimeoutMs coerces refs.
+            const rawTimeoutKwarg = args["timeout"];
+            let perOpTimeoutSec;
+            if (typeof rawTimeoutKwarg === "number")
+                perOpTimeoutSec = rawTimeoutKwarg;
+            else if (typeof rawTimeoutKwarg === "string" && rawTimeoutKwarg !== "")
+                perOpTimeoutSec = rawTimeoutKwarg;
+            if (rawTimeoutKwarg !== undefined)
+                delete args["timeout"];
             const connectorLabel = op.mcpConnector !== undefined ? `${op.mcpConnector}.` : "";
             const flatKey = `${targetName}.output`;
             // Mechanical preview, registry-routed, test escape hatch, no-dispatcher.
@@ -703,19 +678,23 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                     vars.set(op.outputVar, parsed);
                 return { lastBoundVar: op.outputVar ?? flatKey, lastValue: parsed };
             }
-            // v0.7.2 — bare-form name-match dispatch resolution. When `$ <name> ...`
-            // is bare (no dotted prefix) AND `<name>` matches a registered
-            // connector name, route to that connector directly. This makes the
-            // canonical `$ llm prompt="..."` and `$ data_read mode=... query=...
-            // limit=N` paths work in default deployments where the bridges are
-            // auto-wired as `llm` + `memory` (rather than as `primary`). If
-            // `<name>` isn't a registered connector, fall back to the legacy
-            // `primary` lookup — preserves backward-compat for skills that wrote
-            // `$ <tool>` expecting routing through the primary MCP connector.
-            let connectorName = op.mcpConnector ?? "primary";
-            if (op.mcpConnector === undefined && ctx.registry.hasMcpConnector(toolName)) {
+            // Bare-form name-match dispatch: when `$ <name> ...` is bare (no dotted
+            // prefix), `<name>` must match a registered connector name. This makes
+            // typed-contract patterns (`$ llm prompt=...`, `$ data_read mode=...`)
+            // dispatch cleanly to the auto-wired bridge connectors. v0.16.0 dropped
+            // the legacy "primary" fallback — substrate-specific MCP tools require
+            // named form `$ <connector>.<tool>` and fail clearly if bare-form is
+            // used with no matching connector.
+            let connectorName;
+            if (op.mcpConnector !== undefined) {
+                connectorName = op.mcpConnector;
+            }
+            else if (ctx.registry.hasMcpConnector(toolName)) {
                 connectorName = toolName;
             }
+            else {
+                connectorName = toolName; // will fail through to ConnectorNotFoundError below
+            }
             // v0.4.1 — defense-in-depth allowlist check. Lint catches this at
             // compile time via `disallowed-tool`; this runtime check is the
             // backstop for compiled artifacts run against a different runtime
@@ -740,7 +719,7 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             }
             let rawResult;
             let dispatched = false;
-            const timeoutMs = resolveOpTimeoutMs(undefined, skillTimeoutSec, absoluteTimeoutMs, vars);
+            const timeoutMs = resolveOpTimeoutMs(perOpTimeoutSec, skillTimeoutSec, absoluteTimeoutMs, vars);
             // Op-level fallback (per language reference §9, extended to `$` for
             // cold-agent corpus consistency). On dispatch throw, bind the
             // fallback value to the output var; on missing connector with
@@ -796,121 +775,34 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                 throw new OpError(`tool ${connectorLabel}${toolName} returned isError: ${innerText}`, "$", "The tool itself failed; inspect the inner error text. Add `(fallback: ...)` to the op for graceful failure.", targetName);
             }
             const bindValue = unwrapToolResult(rawResult);
-            vars.set(flatKey, bindValue);
+            // v0.16.0 — fallback-on-empty parity with legacy `~`/`>` semantics
+            // (LocalModel empty-trimmed-response + Retrieval empty-array both bind
+            // fallback). Without this, the doc-vs-code mismatch at parser.ts:84-91
+            // (which claims `$` fallback fires "on throw or empty result") would
+            // persist. Empty = "" after trim, OR [], OR null/undefined.
+            let finalValue = bindValue;
+            if (dollarFallback !== undefined) {
+                const isEmptyString = typeof bindValue === "string" && bindValue.trim() === "";
+                const isEmptyArray = Array.isArray(bindValue) && bindValue.length === 0;
+                const isNullish = bindValue === null || bindValue === undefined;
+                if (isEmptyString || isEmptyArray || isNullish) {
+                    finalValue = dollarFallback;
+                    fallbacks.push({
+                        target: targetName,
+                        opKind: "$",
+                        value: dollarFallback,
+                        reason: `$ ${connectorLabel}${toolName} returned empty result`,
+                    });
+                }
+            }
+            vars.set(flatKey, finalValue);
             if (op.outputVar !== undefined)
-                vars.set(op.outputVar, bindValue);
+                vars.set(op.outputVar, finalValue);
             return {
                 lastBoundVar: op.outputVar ?? flatKey,
-                lastValue: bindValue,
+                lastValue: finalValue,
             };
         }
-        case ">": {
-            const p = op.retrievalParams;
-            const querySub = substituteRuntime(p.query, vars);
-            const extraSub = {};
-            for (const [k, v] of Object.entries(p.extra)) {
-                extraSub[k] = substituteRuntime(v, vars);
-            }
-            if (ctx.mechanical === true) {
-                // Bind a 1-element array of placeholders so foreach M in $(RESULTS)
-                // iterates once with a dotted-accessible M (matches common author
-                // patterns like `$(M.id)`, `$(M.summary)`). Authors expecting empty
-                // result sets test the empty case in unit tests, not mechanical mode.
-                const mechanicalValue = p.fallback !== undefined
-                    ? p.fallback
-                    : [makeMechanicalPlaceholder(`${op.outputVar}[0]`)];
-                emissions.push(`Would query DataStore \`${p.connector}\` with mode=${p.mode}, ` +
-                    `query="${querySub}", limit=${p.limit} (mechanical: true preview). ` +
-                    `Binding $(${op.outputVar}) = placeholder result set.`);
-                vars.set(op.outputVar, mechanicalValue);
-                return { lastBoundVar: op.outputVar, lastValue: mechanicalValue };
-            }
-            const store = ctx.registry.getDataStore(p.connector);
-            const limitResolved = resolveIntParam(p.limit, vars, "limit");
-            const filters = {
-                query: querySub,
-                mode: p.mode,
-                limit: limitResolved,
-                ...extraSub,
-            };
-            const retrievalTimeoutMs = resolveOpTimeoutMs(undefined, skillTimeoutSec, absoluteTimeoutMs, vars);
-            // Op-level fallback (per language reference §9): on throw OR empty
-            // result, bind the fallback value and continue. Without a fallback,
-            // throws propagate to `else:` / `# OnError:` / target error.
-            // coerceLiteralValue parses array-shaped literals (`[]`, `[a, b]`)
-            // into actual arrays so downstream `foreach M in $(VAR)` iterates
-            // correctly on the empty/sentinel case.
-            const coercedFallback = p.fallback !== undefined ? coerceLiteralValue(p.fallback) : undefined;
-            let results;
-            try {
-                results = await dispatchWithTimeout(() => store.query(filters), retrievalTimeoutMs, ">");
-                if (coercedFallback !== undefined && Array.isArray(results) && results.length === 0) {
-                    results = coercedFallback;
-                }
-            }
-            catch (err) {
-                if (coercedFallback !== undefined) {
-                    results = coercedFallback;
-                }
-                else {
-                    throw err;
-                }
-            }
-            vars.set(op.outputVar, results);
-            return { lastBoundVar: op.outputVar, lastValue: results };
-        }
-        case "~": {
-            const p = op.localModelParams;
-            const promptSub = substituteRuntime(p.prompt, vars);
-            if (ctx.mechanical === true) {
-                const modelName = p.model ?? "default";
-                // v0.2.12 Bug 23: bind a Proxy placeholder (same shape as the `$`/`>`
-                // mechanical handlers) so dotted field access — `$(HI.outputs.text)`,
-                // `$(HI.choices.0.message.content)` — resolves to deeper placeholders
-                // instead of erroring with UnresolvedVariableError. Pre-fix the `~` op
-                // bound a flat string, which broke field access in mechanical mode.
-                const placeholder = makeMechanicalPlaceholder(op.outputVar ?? `${modelName}.output`);
-                emissions.push(`Would invoke LocalModel \`${modelName}\` with prompt='${promptSub}' ` +
-                    `(mechanical: true preview). Binding $(${op.outputVar}) = ${stringifyValue(placeholder)}`);
-                vars.set(op.outputVar, placeholder);
-                return { lastBoundVar: op.outputVar, lastValue: placeholder };
-            }
-            let model;
-            try {
-                model = ctx.registry.getLocalModel(p.model);
-            }
-            catch (err) {
-                if (p.fallback !== undefined) {
-                    vars.set(op.outputVar, p.fallback);
-                    return { lastBoundVar: op.outputVar, lastValue: p.fallback };
-                }
-                throw err;
-            }
-            const runOpts = {};
-            if (p.maxTokens !== undefined) {
-                runOpts.maxTokens = resolveIntParam(p.maxTokens, vars, "maxTokens");
-            }
-            const tildeTimeoutMs = resolveOpTimeoutMs(p.timeoutSeconds, skillTimeoutSec, absoluteTimeoutMs, vars);
-            // Op-level fallback (per language reference §9): on throw OR empty
-            // (trimmed) response, bind the fallback value.
-            let response;
-            try {
-                response = await dispatchWithTimeout(() => model.run(promptSub, runOpts), tildeTimeoutMs, "~");
-                if (p.fallback !== undefined && response.trim() === "") {
-                    response = p.fallback;
-                }
-            }
-            catch (err) {
-                if (p.fallback !== undefined) {
-                    response = p.fallback;
-                }
-                else {
-                    throw err;
-                }
-            }
-            vars.set(op.outputVar, response);
-            return { lastBoundVar: op.outputVar, lastValue: response };
-        }
         case "foreach": {
             const listVal = resolveListExpr(op.foreachList, vars);
             const iterName = op.foreachIter;
@@ -1086,17 +978,17 @@ async function execShellCommand(bin, args, timeoutMs) {
         child.stderr?.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
         child.on("error", (err) => {
             clearTimeout(timer);
-            reject(new OpError(`Failed to spawn '${bin}': ${err.message}`, "@", "Verify the binary is on PATH and executable. Check for typos in the `@` op body."));
+            reject(new OpError(`Failed to spawn '${bin}': ${err.message}`, "shell", "Verify the binary is on PATH and executable. Check for typos in the `shell(command=...)` body."));
         });
         child.on("close", (code) => {
             clearTimeout(timer);
             if (killed) {
-                reject(new OpTimeoutError(timeoutMs, "@"));
+                reject(new OpTimeoutError(timeoutMs, "shell"));
                 return;
             }
             if (code !== 0) {
                 const trimmed = stderr.trim();
-                reject(new OpError(`Shell command '${bin}' exited with code ${code}${trimmed ? `: ${trimmed.slice(0, 200)}` : ""}.`, "@", "Inspect the stderr output. Add `(fallback: ...)` to the `@` op for graceful failure on non-zero exit."));
+                reject(new OpError(`Shell command '${bin}' exited with code ${code}${trimmed ? `: ${trimmed.slice(0, 200)}` : ""}.`, "shell", "Inspect the stderr output. Add `(fallback: ...)` to the `shell(...)` op for graceful failure on non-zero exit."));
                 return;
             }
             // Strip trailing newline — convention for shell command output.
@@ -1104,10 +996,6 @@ async function execShellCommand(bin, args, timeoutMs) {
         });
     });
 }
-function isDeclineResponse(raw) {
-    const t = raw.trim().toLowerCase();
-    return t === "" || t === "no" || t === "n" || t === "false" || t === "0";
-}
 /**
  * Resolve an integer parameter that may be a literal number or a string
  * containing a `$(VAR)` ref. Substitutes any refs then parseInts. Throws