skillscript-runtime 0.23.1 → 0.25.0

package/dist/runtime.d.ts

@@ -2,6 +2,7 @@ import type { ParsedSkill } from "./parser.js";
 import type { DeliveryReceipt, WakeReceipt } from "./connectors/agent.js";
 import type { Registry } from "./connectors/registry.js";
 import type { TraceConfig, TraceStore } from "./trace.js";
+import type { SecretProvider } from "./secrets.js";
 /**
  * Runtime executor. Pure mechanical execution: walks the parsed skill
  * tree, dispatches each op to its handler, threads variable state.
@@ -143,6 +144,14 @@ export interface ExecuteContext {
      */
     _currentSkillName?: string;
     _currentSkillEventType?: string | null;
+    /**
+     * v0.25.0 — the running skill's declared `# Requires: secret.NAME` set.
+     * Stashed by execute() so the sink resolver can enforce declare-before-spend
+     * at RUNTIME, not just at lint: a `{{secret.X}}` whose X isn't declared is
+     * refused even when the marker was built dynamically (e.g. `{{secret.${VAR}}}`
+     * resolved by substituteRuntime), which lint can't see statically. Internal.
+     */
+    _currentSkillSecretRequires?: string[];
     /** Skill identity for trace records. Optional — falls back to parsed.name + version inference. */
     skillVersion?: string;
     /**
@@ -167,6 +176,17 @@ export interface ExecuteContext {
      * Undefined → TraceBuilder mints fresh (existing v1 behavior).
      */
     preMintedTraceId?: string;
+    /**
+     * v0.25.0 — resolver for `{{secret.NAME}}` markers. Wired at every
+     * ExecuteContext build site (bootstrap / scheduler / mcp-server). When a
+     * skill places a marker in a sink op (shell / `$`) the runtime resolves it
+     * here, AT the sink, and injects the value use-only — never binding,
+     * emitting, or tracing it. Undefined → markers are unresolvable: a sink op
+     * carrying one throws (fail-closed) so a misconfigured runtime can't send a
+     * literal `{{secret.X}}` to a credential-expecting sink. The env-backed
+     * provider ships today; a vault provider swaps in here with no other change.
+     */
+    secretProvider?: SecretProvider;
 }
 /**
  * Structured op-error record in `result.errors[]`. Per ERD §8: each entry

package/dist/runtime.d.ts.map

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

package/dist/runtime.js

@@ -12,6 +12,7 @@ import { isSecuredMode } from "./approval.js";
 import { classifyMutation, authorizationGranted, buildAuthorizationSuggestion, } from "./mutation-gate.js";
 import { TraceBuilder, shouldTraceFire } from "./trace.js";
 import { describeValueShape, isShapeWorthRecording } from "./observed-shape.js";
+import { expandSecretMarkers, expandSecretMarkersInList, hasSecretMarker, extractSecretRefs } from "./secrets.js";
 /**
  * v0.18.5 — address-routing predicate per Perry's design call (thread
  * `c453afa2`). The presence of `@session` on the agent_id encodes
@@ -148,7 +149,7 @@ export async function execute(parsed, initialVars, order, ctx) {
     // v0.9.6 — stash skill identity onto ctx so deep-stack op handlers
     // (notify()) can read for DeliveryMeta without threading `parsed`
     // through every call hop. Internal convention; do not set from outside.
-    ctx = { ...ctx, _currentSkillName: skillName, _currentSkillEventType: parsed.eventType };
+    ctx = { ...ctx, _currentSkillName: skillName, _currentSkillEventType: parsed.eventType, _currentSkillSecretRequires: parsed.secretRequires };
     const traceBuilder = shouldTraceFire(ctx.trace, triggerId, skillName)
         ? new TraceBuilder(skillName, ctx.skillVersion ?? "unknown", triggerCtx, { agent_id: ctx.agentId }, ctx.preMintedTraceId)
         : null;
@@ -472,6 +473,77 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
     if (isEffectfulOpKind(op.kind) && isSecuredMode() && ctx.effectsAuthorized !== true) {
         throw new SecuredModeEffectError(op.kind, targetName);
     }
+    // v0.25.0 — sink-side secret resolution. Expand `{{secret.NAME}}` markers
+    // AFTER ${VAR} substitution, immediately before the value reaches the sink
+    // (spawn argv / connector arg). Resolved values are use-only: they never
+    // bind to a var, emit, or trace. Fail-closed: a marker with no provider
+    // wired throws rather than sending a literal `{{secret.X}}` to a sink. Only
+    // the sink handlers (shell / `$`) call these; lint keeps markers out of
+    // every other op. (No-op when the text has no marker, so call freely.)
+    const requireSecretProvider = () => {
+        if (ctx.secretProvider === undefined) {
+            throw new OpError(`\`${op.kind}\` op references a secret ({{secret.…}}) but this runtime has no secret provider wired.`, op.kind, "Run via the dashboard/serve runtime (it wires the env secret provider) and provision SKILLSCRIPT_SECRET_<NAME> in the operator's .env.", targetName);
+        }
+        return ctx.secretProvider;
+    };
+    // Runtime declare-before-spend enforcement. A marker can be built dynamically
+    // (`{{secret.${VAR}}}` → substituteRuntime makes `{{secret.FLAG}}`), which the
+    // static lint can't see — so the runtime independently refuses any secret name
+    // not in the skill's `# Requires: secret.NAME` set. Fail-closed; keeps the
+    // approver-visible declaration an enforced contract, not just a lint hint.
+    const enforceDeclared = (text) => {
+        const declared = ctx._currentSkillSecretRequires ?? [];
+        for (const name of extractSecretRefs(text)) {
+            if (!declared.includes(name)) {
+                throw new OpError(`\`${op.kind}\` op references secret '${name}' which is not declared in the skill's \`# Requires:\`.`, op.kind, `Add \`# Requires: secret.${name}\` to the frontmatter. Secrets must be declared up-front so an approver can see which credentials the skill reaches (dynamically-named markers are refused for the same reason).`, targetName);
+            }
+        }
+    };
+    // Per-op set of resolved secret VALUES. Populated as markers resolve; used by
+    // redactSecrets() to scrub a value from any error/fallback-reason that gets
+    // recorded or rethrown (Perry Bug B fix #2 — belt-and-suspenders: a secret
+    // value must never appear anywhere but the live sink call, even if a sink or
+    // connector echoes it in a thrown error). The shared invariant: outside the
+    // successful spawn, everything renders the marker, never the value.
+    const injectedSecretValues = [];
+    const collectSecret = (_name, value) => {
+        if (value !== "")
+            injectedSecretValues.push(value);
+    };
+    const redactSecrets = (text) => {
+        let out = text;
+        for (const v of injectedSecretValues) {
+            if (v !== "")
+                out = out.split(v).join("{{secret.REDACTED}}");
+        }
+        return out;
+    };
+    // Scrub resolved secret values from a thrown error's message/remediation in
+    // place (preserves the error class + `instanceof` checks). No-op when no
+    // secret resolved for this op (so pre-resolution errors — e.g. the binary
+    // allowlist gate — pass through untouched).
+    const redactErr = (err) => {
+        if (injectedSecretValues.length === 0 || !(err instanceof Error))
+            return err;
+        err.message = redactSecrets(err.message);
+        const withRem = err;
+        if (typeof withRem.remediation === "string")
+            withRem.remediation = redactSecrets(withRem.remediation);
+        return err;
+    };
+    const resolveSecretsAtSink = async (text) => {
+        if (!hasSecretMarker(text))
+            return text;
+        enforceDeclared(text);
+        return expandSecretMarkers(text, requireSecretProvider(), { skillName: ctx._currentSkillName }, collectSecret);
+    };
+    const resolveSecretsAtSinkList = async (items) => {
+        if (!items.some(hasSecretMarker))
+            return items;
+        for (const item of items)
+            enforceDeclared(item);
+        return expandSecretMarkersInList(items, requireSecretProvider(), { skillName: ctx._currentSkillName }, collectSecret);
+    };
     switch (op.kind) {
         case "$set": {
             // v0.5.0 item 3 — `$set X = "...$(REF)..."` now resolves $(REF) at
@@ -575,21 +647,30 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                         lastValue: placeholder,
                     };
                 }
-                const [bin, ...args] = substArgv;
                 let stdoutArgv;
                 try {
-                    // v0.18.8 binary-scope gate. argv[0] IS the binary by construction;
-                    // the allowlist applies identically to argv mode and command= mode.
-                    if (!isBinaryAllowed(bin, ctx.shellAllowlist)) {
-                        throw new ShellBinaryNotAllowedError(bin, ctx.shellAllowlist, targetName);
+                    // v0.18.8 binary-scope gate. argv[0] IS the binary by construction.
+                    // v0.25.0 — gate the binary BEFORE resolving secrets, so a refused
+                    // op never resolves the credential and never lands it in the error
+                    // message (which is built from the binary token). The binary itself
+                    // is never a secret.
+                    const bin0 = substArgv[0];
+                    if (!isBinaryAllowed(bin0, ctx.shellAllowlist)) {
+                        throw new ShellBinaryNotAllowedError(bin0, ctx.shellAllowlist, targetName);
                     }
+                    // Resolve `{{secret.NAME}}` markers per-element AFTER the gate so a
+                    // secret value with spaces/quotes stays one argv element (the argv
+                    // form never re-tokenizes). Use-only: spliced straight into spawn,
+                    // never bound or traced.
+                    const resolvedArgv = await resolveSecretsAtSinkList(substArgv);
+                    const [bin, ...args] = resolvedArgv;
                     stdoutArgv = await execShellCommand(bin, args, shellTimeoutMs);
                 }
                 catch (err) {
                     if (shellFallback !== undefined) {
-                        return recordShellFallback(shellFallback, `shell argv failed: ${messageOf(err)}`);
+                        return recordShellFallback(shellFallback, redactSecrets(`shell argv failed: ${messageOf(err)}`));
                     }
-                    throw err;
+                    throw redactErr(err);
                 }
                 // Empty-stdout fallback (matches $-op trailer empty-result semantic).
                 if (shellFallback !== undefined && stdoutArgv.trim() === "") {
@@ -637,28 +718,41 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                     if (!isBinaryAllowed("bash", ctx.shellAllowlist)) {
                         throw new ShellBinaryNotAllowedError("bash", ctx.shellAllowlist, targetName);
                     }
-                    stdout = await execShellCommand("bash", ["-c", body], shellTimeoutMs);
+                    // v0.25.0 — resolve markers into the bash script. NOTE: the
+                    // resolved value lands in the `bash -c <script>` argv, which is
+                    // process-list visible (the documented argv/`ps` leak window);
+                    // vault-era sink-aware injection closes it. Unsafe shell is
+                    // already operator-gated, so a secret here is a deliberate choice.
+                    const resolvedUnsafeBody = await resolveSecretsAtSink(body);
+                    stdout = await execShellCommand("bash", ["-c", resolvedUnsafeBody], shellTimeoutMs);
                 }
                 else {
                     const tokens = tokenizeShellArgs(body);
                     if (tokens.length === 0) {
                         throw new OpError(`Empty \`shell(...)\` op body in target '${targetName}'.`, "shell", "Provide a non-empty `command=\"...\"` kwarg.", targetName);
                     }
-                    const [bin, ...args] = tokens;
-                    // v0.18.8 — binary-scope gate. Safe-path grammar guarantees
-                    // one binary + no metacharacters, so the first token IS the
-                    // binary. Default-deny when allowlist unset (BREAKING).
-                    if (!isBinaryAllowed(bin, ctx.shellAllowlist)) {
-                        throw new ShellBinaryNotAllowedError(bin, ctx.shellAllowlist, targetName);
+                    // v0.18.8 — binary-scope gate. Safe-path grammar guarantees one
+                    // binary + no metacharacters, so the first token IS the binary.
+                    // Default-deny when allowlist unset (BREAKING). v0.25.0 — gate
+                    // BEFORE resolving secrets so a refused op never resolves the
+                    // credential and the error message (built from the binary token)
+                    // carries the marker, never the value. The binary is never a secret.
+                    if (!isBinaryAllowed(tokens[0], ctx.shellAllowlist)) {
+                        throw new ShellBinaryNotAllowedError(tokens[0], ctx.shellAllowlist, targetName);
                     }
+                    // Resolve `{{secret.NAME}}` markers AFTER tokenization + gate so a
+                    // secret value with spaces/quotes stays one argv element and never
+                    // reaches a shell for re-splitting. Use-only.
+                    const resolvedTokens = await resolveSecretsAtSinkList(tokens);
+                    const [bin, ...args] = resolvedTokens;
                     stdout = await execShellCommand(bin, args, shellTimeoutMs);
                 }
             }
             catch (err) {
                 if (shellFallback !== undefined) {
-                    return recordShellFallback(shellFallback, `shell failed: ${messageOf(err)}`);
+                    return recordShellFallback(shellFallback, redactSecrets(`shell failed: ${messageOf(err)}`));
                 }
-                throw err;
+                throw redactErr(err);
             }
             // Empty-stdout fallback (matches $-op trailer empty-result semantic).
             if (shellFallback !== undefined && stdout.trim() === "") {
@@ -1002,13 +1096,26 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
             // fallback present, ditto.
             const dollarFallback = op.fallback !== undefined ? coerceLiteralValue(op.fallback) : undefined;
             try {
+                // v0.25.0 — resolve `{{secret.NAME}}` markers in string-valued args
+                // just before the real connector dispatch (use-only). The built-in
+                // execute_skill / json_parse intercepts ran earlier and never reach
+                // here, so a secret value can't leak into a child skill's scope or a
+                // parsed/bound var — it exists only for this one dispatch call.
+                let dispatchArgs = args;
+                if (Object.values(args).some((v) => typeof v === "string" && hasSecretMarker(v))) {
+                    dispatchArgs = { ...args };
+                    for (const [k, v] of Object.entries(args)) {
+                        if (typeof v === "string")
+                            dispatchArgs[k] = await resolveSecretsAtSink(v);
+                    }
+                }
                 if (ctx.registry.hasMcpConnector(connectorName)) {
                     const connector = ctx.registry.getMcpConnector(connectorName);
-                    rawResult = await dispatchWithTimeout(() => connector.call(toolName, args, ctx.agentId !== undefined ? { agentId: ctx.agentId } : undefined), timeoutMs, "$");
+                    rawResult = await dispatchWithTimeout(() => connector.call(toolName, dispatchArgs, ctx.agentId !== undefined ? { agentId: ctx.agentId } : undefined), timeoutMs, "$");
                     dispatched = true;
                 }
                 else if (op.mcpConnector === undefined && ctx.toolDispatch) {
-                    rawResult = await dispatchWithTimeout(() => ctx.toolDispatch(toolName, args), timeoutMs, "$");
+                    rawResult = await dispatchWithTimeout(() => ctx.toolDispatch(toolName, dispatchArgs), timeoutMs, "$");
                     dispatched = true;
                 }
                 else {
@@ -1034,11 +1141,13 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                         target: targetName,
                         opKind: "$",
                         value: dollarFallback,
-                        reason: `$ ${connectorLabel}${toolName} failed: ${messageOf(err)}`,
+                        // v0.25.0 — a connector may echo a resolved secret arg in its
+                        // error; scrub it before this reason lands in the trace.
+                        reason: redactSecrets(`$ ${connectorLabel}${toolName} failed: ${messageOf(err)}`),
                     });
                     return { lastBoundVar: op.outputVar ?? flatKey, lastValue: dollarFallback };
                 }
-                throw err;
+                throw redactErr(err);
             }
             // c580de5: surface inner-tool `isError: true` as an op error. Otherwise
             // the error text gets bound silently to the output var and the skill
@@ -1048,7 +1157,9 @@ async function execOpInner(op, vars, emissions, fallbacks, ctx, targetName, skil
                 typeof rawResult === "object" &&
                 rawResult.isError === true) {
                 const innerText = extractToolErrorText(rawResult);
-                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);
+                throw new OpError(
+                // v0.25.0 — the connector's error text may echo a resolved secret arg.
+                redactSecrets(`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);
             // v0.23.0 — observed output-shape capture. For a qualified `$ conn.tool`
@@ -1550,9 +1661,21 @@ export function substituteRuntime(text, vars) {
     // through (the silent-blank case Perry hit with `gh pr list` writing
     // nothing to stdout). Now: same semantic across both fallback surfaces.
     return text.replace(
+    // v0.25.0 (Perry red-team `d8a5ad0a` Bug A, fix #1): a `{{secret...}}`
+    // marker is OPAQUE to var-substitution. Group 1 captures any double-brace
+    // secret marker (incl. a dynamically-shaped interior like `{{secret.${NM}}}`)
+    // and the callback returns it verbatim, so `${VAR}` substitution can NEVER
+    // reach inside a marker to build a secret name at runtime. The secret name
+    // therefore stays exactly as authored — a compile-time literal — which the
+    // sink resolver + lint then validate against `# Requires`. `[^}]*` (not
+    // `[^{}]*`) is deliberate so the interior `${...}` is consumed here, not by
+    // the var-ref alternative below.
     // v0.7.0: alternation accepts both `$(REF|chain)` (legacy) and `${REF|chain}`
-    // (canonical). Capture groups 1+2 = paren form, 3+4 = brace form.
-    /\$(?:\(([^|)\s]+)\s*((?:\|\s*[A-Za-z_]\w*(?:\s*:\s*"[^"]*")?\s*)*)\)|\{([^|}\s]+)\s*((?:\|\s*[A-Za-z_]\w*(?:\s*:\s*"[^"]*")?\s*)*)\})/g, (_match, ref1, fc1, ref2, fc2) => {
+    // (canonical). Capture groups 2+3 = paren form, 4+5 = brace form.
+    /(\{\{\s*secret\.[^}]*\}\})|\$(?:\(([^|)\s]+)\s*((?:\|\s*[A-Za-z_]\w*(?:\s*:\s*"[^"]*")?\s*)*)\)|\{([^|}\s]+)\s*((?:\|\s*[A-Za-z_]\w*(?:\s*:\s*"[^"]*")?\s*)*)\})/g, (_match, secretMarker, ref1, fc1, ref2, fc2) => {
+        // Opaque passthrough — never resolve inside a secret marker.
+        if (secretMarker !== undefined)
+            return secretMarker;
         const ref = (ref1 ?? ref2);
         const filterChain = fc1 ?? fc2 ?? "";
         let value = resolveRef(ref, vars);