skillscript-runtime 0.2.10 → 0.3.0

package/dist/lint.js

@@ -9,6 +9,7 @@ export async function lint(source, options) {
         skillStore: options?.skillStore,
         hasSkillStore: options?.skillStore !== undefined,
         callSite: options?.callSite ?? "api",
+        enableUnsafeShell: options?.enableUnsafeShell,
     };
     const findings = [];
     for (const rule of RULES) {
@@ -41,6 +42,7 @@ export function lintSync(source, options) {
         skillStore: options?.skillStore,
         hasSkillStore: options?.skillStore !== undefined,
         callSite: options?.callSite ?? "api",
+        enableUnsafeShell: options?.enableUnsafeShell,
     };
     const findings = [];
     for (const rule of RULES) {
@@ -364,20 +366,21 @@ const UNKNOWN_SKILL_REFERENCE = {
         const findings = [];
         const seen = new Set();
         for (const [targetName, target] of ctx.parsed.targets) {
-            for (const refName of collectAmpRefsFromOps(target.ops)) {
-                if (seen.has(refName))
+            for (const ref of collectAmpRefsFromOps(target.ops)) {
+                const key = `${ref.via}:${ref.name}`;
+                if (seen.has(key))
                     continue;
-                seen.add(refName);
+                seen.add(key);
                 try {
-                    await ctx.skillStore.metadata(refName);
+                    await ctx.skillStore.metadata(ref.name);
                 }
                 catch {
                     findings.push({
                         rule: "unknown-skill-reference",
                         severity: "error",
-                        message: `Skill '${targetName}' references skill '${refName}' via \`&\`, but the SkillStore has no skill by that name.`,
+                        message: `Skill '${targetName}' references skill '${ref.name}' via \`${ref.via}\`, but the SkillStore has no skill by that name.`,
                         block: targetName,
-                        extras: { referenced_skill: refName },
+                        extras: { referenced_skill: ref.name, via: ref.via },
                     });
                 }
             }
@@ -385,6 +388,70 @@ const UNKNOWN_SKILL_REFERENCE = {
         return findings;
     },
 };
+// v0.2.12 Bug 26. Tier-2 warning when a `>` retrieval op carries kwargs
+// outside the documented set. Cold author wrote `since=1h` (hallucinated
+// time-window predicate) and the kwarg passed silently. The documented
+// kwarg set is mode/query/limit/connector/fallback plus filter shapes
+// the connector advertises via staticCapabilities (out of band here).
+const KNOWN_RETRIEVAL_KWARGS = new Set(["mode", "query", "limit", "connector", "fallback"]);
+const UNKNOWN_RETRIEVAL_ARG = {
+    id: "unknown-retrieval-arg",
+    severity: "warning",
+    description: "A `>` retrieval op carries a kwarg outside the documented set (mode/query/limit/connector/fallback).",
+    remediation: "Remove the kwarg, or check it against your MemoryStore connector's documentation — extras pass through to the connector but unrecognized ones often indicate hallucinated syntax.",
+    check: (ctx) => {
+        const findings = [];
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== ">")
+                    return;
+                const extras = op.retrievalParams?.extra ?? {};
+                for (const k of Object.keys(extras)) {
+                    if (KNOWN_RETRIEVAL_KWARGS.has(k))
+                        continue;
+                    findings.push({
+                        rule: "unknown-retrieval-arg",
+                        severity: "warning",
+                        message: `\`>\` op in target '${targetName}' carries unknown kwarg '${k}'. Documented kwargs: ${Array.from(KNOWN_RETRIEVAL_KWARGS).join(", ")}. If '${k}' is a connector-specific filter, confirm it against the connector's docs.`,
+                        block: targetName,
+                        extras: { unknown_kwarg: k },
+                    });
+                }
+            });
+        }
+        return findings;
+    },
+};
+// v0.2.12 Bug 17. `# Templates:` refs were not lint-validated despite
+// `# OnError:` having compile-time validation (since v0.2.10). Tier-1
+// because a missing template fails delivery at runtime.
+const UNKNOWN_TEMPLATE_REFERENCE = {
+    id: "unknown-template-reference",
+    severity: "error",
+    description: "`# Templates: <name>` references a skill that's not present in the configured SkillStore.",
+    remediation: "Check the template name spelling, or store the missing template skill before referencing it. Templates resolve at delivery time; missing ones fail the agent delivery.",
+    check: async (ctx) => {
+        if (ctx.skillStore === undefined)
+            return [];
+        if (ctx.parsed.templates.length === 0)
+            return [];
+        const findings = [];
+        for (const name of ctx.parsed.templates) {
+            try {
+                await ctx.skillStore.metadata(name);
+            }
+            catch {
+                findings.push({
+                    rule: "unknown-template-reference",
+                    severity: "error",
+                    message: `Skill references template '${name}' via \`# Templates:\`, but the SkillStore has no skill by that name.`,
+                    extras: { referenced_skill: name },
+                });
+            }
+        }
+        return findings;
+    },
+};
 const DISABLED_SKILL_REFERENCE = {
     id: "disabled-skill-reference",
     severity: "error",
@@ -396,19 +463,19 @@ const DISABLED_SKILL_REFERENCE = {
         const findings = [];
         const checked = new Set();
         for (const [targetName, target] of ctx.parsed.targets) {
-            for (const refName of collectAmpRefsFromOps(target.ops)) {
-                if (checked.has(refName))
+            for (const ref of collectAmpRefsFromOps(target.ops)) {
+                if (checked.has(ref.name))
                     continue;
-                checked.add(refName);
+                checked.add(ref.name);
                 try {
-                    const meta = await ctx.skillStore.metadata(refName);
+                    const meta = await ctx.skillStore.metadata(ref.name);
                     if (meta.status === "Disabled") {
                         findings.push({
                             rule: "disabled-skill-reference",
                             severity: "error",
-                            message: `Skill '${targetName}' references '${refName}' which is disabled.`,
+                            message: `Skill '${targetName}' references '${ref.name}' via \`${ref.via}\` which is disabled.`,
                             block: targetName,
-                            extras: { referenced_skill: refName, target_status: meta.status },
+                            extras: { referenced_skill: ref.name, via: ref.via, target_status: meta.status },
                         });
                     }
                 }
@@ -627,6 +694,19 @@ const UNSAFE_SHELL_AMBIGUOUS_SUBST = {
                     const trimmed = inner.trim();
                     if (/^[A-Za-z_]\w*$/.test(trimmed) && declared.has(trimmed))
                         continue;
+                    // v0.2.11 Bug 4: dotted refs (EVENT.fired_at_unix, MEMORY.x,
+                    // <target>.output) are runtime ambient/output families — same
+                    // dotted-passthrough heuristic as `undeclared-var`. The
+                    // unsafe-shell warning was telling cold authors to rewrite
+                    // `$(EVENT.fired_at_unix)` as `$$(EVENT.fired_at_unix)` (bash
+                    // command-sub), which would just try to execute "EVENT...".
+                    if (trimmed.includes("."))
+                        continue;
+                    // v0.2.11 Bug 4: bare ambient refs (NOW, USER, ERROR_CONTEXT,
+                    // SESSION_CONTEXT, TRIGGER_TYPE, TRIGGER_PAYLOAD) also pass —
+                    // runtime injects them, author doesn't declare.
+                    if (AMBIENT_VARS.includes(trimmed))
+                        continue;
                     if (reported.has(inner))
                         continue;
                     reported.add(inner);
@@ -665,8 +745,55 @@ const UNSAFE_SHELL_OP = {
         return findings;
     },
 };
-/** Tool-name patterns that strongly suggest mutating operations. Conservative — false positives are tolerable for warnings; false negatives are dangerous. */
-const MUTATING_TOOL_PATTERN = /^(?:write_|update_|delete_|remove_|set_|create_|insert_|put_|patch_|destroy_).*/;
+/**
+ * v0.2.11 Bug 5. Tier-1 escalation of the unsafe-shell signal — only
+ * fires when the caller passed `enableUnsafeShell: false` explicitly.
+ * Without that knowledge (the field is undefined), this rule stays
+ * silent and the tier-2 `unsafe-shell-op` warning is the only signal.
+ *
+ * When the runtime is known-disabled, every `@ unsafe` op is a guaranteed
+ * runtime refusal (`UnsafeShellDisabledError`). Surfacing that at compile
+ * time instead of letting the skill compile clean and then fail at first
+ * fire avoids the "compiles clean but won't run" gap Perry's harness
+ * surfaced (memory `b6176e02`).
+ */
+const UNSAFE_SHELL_DISABLED = {
+    id: "unsafe-shell-disabled",
+    severity: "error",
+    description: "Skill uses `@ unsafe`, but the runtime was configured with `enableUnsafeShell: false`. The op will refuse at first fire.",
+    remediation: "Either set `enableUnsafeShell: true` on the runtime (after reviewing the shell content), or refactor the `@ unsafe` op to use the structured `@ <binary> <args>` form (sandboxed, no bash).",
+    check: (ctx) => {
+        if (ctx.enableUnsafeShell !== false)
+            return [];
+        const findings = [];
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind === "@" && op.policy === "unsafe") {
+                    findings.push({
+                        rule: "unsafe-shell-disabled",
+                        severity: "error",
+                        message: `\`@ unsafe\` op in target '${targetName}' would refuse at runtime: \`enableUnsafeShell\` is false. Command: '${op.body.slice(0, 60)}${op.body.length > 60 ? "..." : ""}'`,
+                        block: targetName,
+                    });
+                }
+            });
+        }
+        return findings;
+    },
+};
+/**
+ * Tool-name patterns that strongly suggest mutating operations.
+ * Conservative — false positives are tolerable for warnings; false
+ * negatives are dangerous.
+ *
+ * v0.2.11 Bug 6: extended with archive_/prune_/deploy_/expire_/
+ * consolidate_/purge_/reset_/rotate_/move_/rename_/drop_/truncate_/
+ * upsert_/overwrite_/clear_/wipe_/finalize_ — Perry's wild-and-crazy
+ * harness surfaced a cluster of mutating tools that the original
+ * write/update/delete/etc. set didn't catch (`archive_old_threads`,
+ * `prune_threads`, `deploy_release`, `dangerous-cleanup`'s `expire_*`).
+ */
+const MUTATING_TOOL_PATTERN = /^(?:write_|update_|delete_|remove_|set_|create_|insert_|put_|patch_|destroy_|archive_|prune_|deploy_|expire_|consolidate_|purge_|reset_|rotate_|move_|rename_|drop_|truncate_|upsert_|overwrite_|clear_|wipe_|finalize_).*/;
 const UNCONFIRMED_MUTATION = {
     id: "unconfirmed-mutation",
     severity: "warning",
@@ -756,19 +883,19 @@ const REFERENCE_TO_DISABLED_SKILL = {
         const findings = [];
         const checked = new Set();
         for (const [targetName, target] of ctx.parsed.targets) {
-            for (const refName of collectAmpRefsFromOps(target.ops)) {
-                if (checked.has(refName))
+            for (const ref of collectAmpRefsFromOps(target.ops)) {
+                if (checked.has(ref.name))
                     continue;
-                checked.add(refName);
+                checked.add(ref.name);
                 try {
-                    const meta = await ctx.skillStore.metadata(refName);
+                    const meta = await ctx.skillStore.metadata(ref.name);
                     if (meta.status === "Disabled") {
                         findings.push({
                             rule: "reference-to-disabled-skill",
                             severity: "warning",
-                            message: `Target '${targetName}' references '${refName}' which is disabled.`,
+                            message: `Target '${targetName}' references '${ref.name}' via \`${ref.via}\` which is disabled.`,
                             block: targetName,
-                            extras: { referenced_skill: refName },
+                            extras: { referenced_skill: ref.name, via: ref.via },
                         });
                     }
                 }
@@ -857,6 +984,193 @@ const UNUSED_AUGMENTING_HEADER = {
         return findings;
     },
 };
+function isAncestorScope(initPath, appendPath) {
+    if (initPath.length >= appendPath.length)
+        return false;
+    for (let i = 0; i < initPath.length; i++) {
+        if (initPath[i].id !== appendPath[i].id)
+            return false;
+    }
+    return true;
+}
+function isSameScope(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i].id !== b[i].id)
+            return false;
+    return true;
+}
+function pathContainsForeach(p) {
+    for (const n of p)
+        if (n.kind === "foreach")
+            return true;
+    return false;
+}
+function walkOpsWithScope(ops, visit, nextScopeId, path = []) {
+    for (const op of ops) {
+        visit(op, path);
+        if (op.foreachBody !== undefined) {
+            const child = { id: nextScopeId.n++, kind: "foreach" };
+            walkOpsWithScope(op.foreachBody, visit, nextScopeId, [...path, child]);
+        }
+        if (op.ifBranches !== undefined) {
+            for (const b of op.ifBranches) {
+                const child = { id: nextScopeId.n++, kind: "if-branch" };
+                walkOpsWithScope(b.body, visit, nextScopeId, [...path, child]);
+            }
+        }
+        if (op.ifElseBody !== undefined) {
+            const child = { id: nextScopeId.n++, kind: "if-else" };
+            walkOpsWithScope(op.ifElseBody, visit, nextScopeId, [...path, child]);
+        }
+    }
+}
+function isStaticListLiteral(raw) {
+    const t = raw.trim();
+    return t.startsWith("[") && t.endsWith("]");
+}
+const UNINITIALIZED_APPEND = {
+    id: "uninitialized-append",
+    severity: "error",
+    description: "`$append VAR ...` where VAR isn't initialized in any enclosing scope (target body, # Vars: declaration, or shallower foreach/if block).",
+    remediation: "Add `$set VAR = []` before the `$append` (in the target body, not inside the foreach), or declare in `# Vars: VAR=[]`. If you meant a different variable, check the spelling against your declarations.",
+    check: (ctx) => {
+        const declaredGlobal = new Set();
+        for (const v of ctx.parsed.vars)
+            declaredGlobal.add(v.name);
+        for (const r of ctx.parsed.requires)
+            declaredGlobal.add(r.target);
+        const findings = [];
+        for (const [targetName, target] of ctx.parsed.targets) {
+            const inits = new Map();
+            const sc1 = { n: 1 };
+            walkOpsWithScope(target.ops, (op, path) => {
+                if (op.kind === "$set" && op.setName !== undefined) {
+                    const arr = inits.get(op.setName) ?? [];
+                    arr.push([...path]);
+                    inits.set(op.setName, arr);
+                }
+            }, sc1);
+            const sc2 = { n: 1 };
+            walkOpsWithScope(target.ops, (op, path) => {
+                if (op.kind !== "$append" || op.setName === undefined)
+                    return;
+                const varName = op.setName;
+                if (declaredGlobal.has(varName))
+                    return;
+                const initPaths = inits.get(varName) ?? [];
+                const hasAncestor = initPaths.some((ip) => isAncestorScope(ip, path));
+                const hasSame = initPaths.some((ip) => isSameScope(ip, path));
+                // Same-scope counts as "visible" for resolution purposes — the
+                // init runs before the append in the same block (foreach iteration,
+                // straight target body, etc.). Whether it's the RIGHT shape for an
+                // accumulator is `foreach-local-accumulator-target`'s job.
+                const isVisible = hasAncestor || hasSame;
+                const hasOther = initPaths.some((ip) => !isAncestorScope(ip, path) && !isSameScope(ip, path));
+                if (initPaths.length === 0) {
+                    findings.push({
+                        rule: "uninitialized-append",
+                        severity: "error",
+                        message: `\`$append ${varName} ...\` in target '${targetName}': ${varName} is not initialized. Add \`$set ${varName} = []\` before the \`$append\` (or declare in \`# Vars: ${varName}=[]\`). If you meant a different variable, check the spelling against your declarations.`,
+                        block: targetName,
+                        extras: { var_name: varName },
+                    });
+                }
+                else if (!isVisible && hasOther) {
+                    // init exists in a sibling/inner scope, not visible at the append site.
+                    findings.push({
+                        rule: "uninitialized-append",
+                        severity: "error",
+                        message: `\`$append ${varName} ...\` in target '${targetName}': ${varName}'s \`$set\` initialization is in a sibling or inner block, not visible at this append site. Move the init to the target body (or a common enclosing scope) before the \`$append\`.`,
+                        block: targetName,
+                        extras: { var_name: varName },
+                    });
+                }
+            }, sc2);
+        }
+        return findings;
+    },
+};
+const FOREACH_LOCAL_ACCUMULATOR_TARGET = {
+    id: "foreach-local-accumulator-target",
+    severity: "error",
+    description: "`$append VAR ...` where VAR's `$set VAR = []` initialization is in the SAME scope (typically same foreach body). Each iteration resets VAR; the accumulator silently loses all but the last iteration's append.",
+    remediation: "Move `$set VAR = []` outside the foreach (to the target body), so the append mutates a single outer-scope list that persists across iterations.",
+    check: (ctx) => {
+        const findings = [];
+        for (const [targetName, target] of ctx.parsed.targets) {
+            const inits = new Map();
+            const sc1 = { n: 1 };
+            walkOpsWithScope(target.ops, (op, path) => {
+                if (op.kind === "$set" && op.setName !== undefined) {
+                    const arr = inits.get(op.setName) ?? [];
+                    arr.push([...path]);
+                    inits.set(op.setName, arr);
+                }
+            }, sc1);
+            const sc2 = { n: 1 };
+            walkOpsWithScope(target.ops, (op, path) => {
+                if (op.kind !== "$append" || op.setName === undefined)
+                    return;
+                const initPaths = inits.get(op.setName) ?? [];
+                const hasAncestor = initPaths.some((ip) => isAncestorScope(ip, path));
+                const hasSame = initPaths.some((ip) => isSameScope(ip, path));
+                // Only fires when the SAME scope is inside a foreach. Same scope at
+                // target-body level (both ops at depth 0) is fine — that's just
+                // sequential init + append, no iteration to lose data across.
+                if (!hasAncestor && hasSame && pathContainsForeach(path)) {
+                    findings.push({
+                        rule: "foreach-local-accumulator-target",
+                        severity: "error",
+                        message: `\`$append ${op.setName} ...\` in target '${targetName}': \`$set ${op.setName} = []\` is in the same scope as the append (typically the same foreach body). Each iteration resets ${op.setName}, silently losing all but the last iteration's data. Move the \`$set ${op.setName} = []\` to the target body, before the foreach.`,
+                        block: targetName,
+                        extras: { var_name: op.setName },
+                    });
+                }
+            }, sc2);
+        }
+        return findings;
+    },
+};
+const APPEND_TO_NON_LIST = {
+    id: "append-to-non-list",
+    severity: "error",
+    description: "`$append VAR ...` where VAR's static initialization is a non-list value. $append v0.3.0 is list-only.",
+    remediation: "Initialize VAR with a list literal (`$set VAR = []` or `# Vars: VAR=[]`). String concat and map-shaped accumulation are out of scope for v0.3.0.",
+    check: (ctx) => {
+        const staticInits = new Map();
+        for (const v of ctx.parsed.vars) {
+            if (v.default !== undefined)
+                staticInits.set(v.name, v.default);
+        }
+        const findings = [];
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind === "$set" && op.setName !== undefined && op.setValue !== undefined && !/\$\(/.test(op.setValue)) {
+                    staticInits.set(op.setName, op.setValue);
+                }
+            });
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$append" || op.setName === undefined)
+                    return;
+                const init = staticInits.get(op.setName);
+                if (init === undefined)
+                    return;
+                if (!isStaticListLiteral(init)) {
+                    findings.push({
+                        rule: "append-to-non-list",
+                        severity: "error",
+                        message: `\`$append ${op.setName} ...\` in target '${targetName}': ${op.setName} is initialized to a non-list value (\`${init.slice(0, 40)}${init.length > 40 ? "..." : ""}\`). $append v0.3.0 requires a list-typed target.`,
+                        block: targetName,
+                        extras: { var_name: op.setName, init_value: init },
+                    });
+                }
+            });
+        }
+        return findings;
+    },
+};
 const RULES = [
     // Tier-1 (error)
     PARSE_ERROR,
@@ -872,6 +1186,11 @@ const RULES = [
     INDENTATION,
     RESERVED_KEYWORD,
     UNKNOWN_SKILL_REFERENCE,
+    UNKNOWN_TEMPLATE_REFERENCE,
+    UNKNOWN_RETRIEVAL_ARG,
+    UNINITIALIZED_APPEND,
+    FOREACH_LOCAL_ACCUMULATOR_TARGET,
+    APPEND_TO_NON_LIST,
     DISABLED_SKILL_REFERENCE,
     CREDENTIAL_IN_ARGS,
     STATUS_DISABLED,
@@ -882,6 +1201,7 @@ const RULES = [
     DEPRECATED_QUESTION,
     UNSAFE_SHELL_AMBIGUOUS_SUBST,
     UNSAFE_SHELL_OP,
+    UNSAFE_SHELL_DISABLED,
     UNCONFIRMED_MUTATION,
     MODEL_CONTENTION,
     DRAFT_WITH_TRIGGER,
@@ -911,10 +1231,27 @@ function walkOps(ops, visit) {
     }
 }
 function collectAmpRefsFromOps(ops) {
-    const out = new Set();
+    const out = [];
+    const seen = new Set();
+    const emit = (name, via) => {
+        const key = `${via}:${name}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ name, via });
+    };
     walkOps(ops, (op) => {
         if (op.kind === "&" && op.ampParams !== undefined)
-            out.add(op.ampParams.skillName);
+            emit(op.ampParams.skillName, "&");
+        // v0.2.11 Bug 7: $ execute_skill is also a composition primitive.
+        if (op.kind === "$" && /^execute_skill\b/.test(op.body)) {
+            const m = /\bskill_name\s*=\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z_][\w-]*))/.exec(op.body);
+            if (m !== null) {
+                const name = m[1] ?? m[2] ?? m[3];
+                if (name !== undefined && name !== "")
+                    emit(name, "$ execute_skill");
+            }
+        }
     });
     return out;
 }