skillscript-runtime 0.16.3 → 0.16.5

package/dist/lint.js

@@ -4,6 +4,9 @@ import { KNOWN_FILTERS } from "./filters.js";
 // ─── lint() entry point ────────────────────────────────────────────────────
 export async function lint(source, options) {
     const parsed = parse(source);
+    const localModelInfo = options?.localModelAliases !== undefined
+        ? { aliases: options.localModelAliases, modelsAvailable: options.localModelsAvailable ?? [] }
+        : await collectLocalModelInfoFromRegistry(options?.registry);
     const ctx = {
         parsed,
         source,
@@ -16,6 +19,8 @@ export async function lint(source, options) {
         connectorConfigErrors: options?.connectorConfigErrors ?? [],
         mcpConnectorAllowedTools: options?.mcpConnectorAllowedTools ?? collectMcpConnectorAllowedToolsFromRegistry(options?.registry),
         agentConnectorNames: options?.agentConnectorNames ?? collectAgentConnectorNamesFromRegistry(options?.registry),
+        localModelAliases: localModelInfo?.aliases,
+        localModelsAvailable: localModelInfo?.modelsAvailable,
         mcpConnectorStaticTools: collectMcpConnectorStaticToolsFromRegistry(options?.registry),
     };
     const findings = [];
@@ -55,6 +60,8 @@ export function lintSync(source, options) {
         connectorConfigErrors: options?.connectorConfigErrors ?? [],
         mcpConnectorAllowedTools: options?.mcpConnectorAllowedTools ?? collectMcpConnectorAllowedToolsFromRegistry(options?.registry),
         agentConnectorNames: options?.agentConnectorNames ?? collectAgentConnectorNamesFromRegistry(options?.registry),
+        localModelAliases: options?.localModelAliases ?? collectLocalModelAliasesFromRegistry(options?.registry),
+        localModelsAvailable: options?.localModelsAvailable,
         mcpConnectorStaticTools: collectMcpConnectorStaticToolsFromRegistry(options?.registry),
     };
     const findings = [];
@@ -468,6 +475,203 @@ const UNKNOWN_CONNECTOR = {
         return findings;
     },
 };
+// v0.16.4 — `$ llm prompt="..." model="X"` where X matches neither any
+// registered LocalModel alias name NOR any `models_available` entry from
+// any registered LocalModel's `manifest()` payload. Tier-2 warning.
+//
+// Closes the documented-but-unenforced surface from v0.16.2 (the `model=`
+// kwarg shipped working at runtime but a typo like `model="qwen2.5"` —
+// intending the upstream Ollama tag `qwen2.5:7b` or the alias `qwen` —
+// would silently fall through to the default model). With v0.16.3
+// putting `manifest()` in `runtime_capabilities`, the lint now has
+// substrate-aware source of truth: both alias names AND each registered
+// LocalModel's underlying model surface participate in the typo-catch.
+//
+// Silent unless context carries the data — `lint()` without a `registry`
+// or explicit `localModelAliases` cannot validate. Variable-substituted
+// values (`model="${TAG}"`) are skipped — the literal isn't a model
+// identifier at compile time.
+const UNKNOWN_LLM_MODEL = {
+    id: "unknown-llm-model",
+    severity: "warning",
+    description: "A `$ llm` op carries `model=\"X\"` where X is neither a registered LocalModel alias nor a model in any registered LocalModel's `models_available` manifest field.",
+    remediation: "Check the model name against the runtime's registered LocalModels — `runtime_capabilities()` lists every alias plus each instance's `manifest.models_available`. Either fix the typo, register the model under a runtime alias (e.g., `registry.registerLocalModel(\"<alias>\", <instance>)`), or wrap the value in a substitution if it's resolved at runtime.",
+    check: (ctx) => {
+        if (ctx.localModelAliases === undefined)
+            return [];
+        const known = new Set(ctx.localModelAliases);
+        if (ctx.localModelsAvailable !== undefined) {
+            for (const m of ctx.localModelsAvailable)
+                known.add(m);
+        }
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$")
+                    return;
+                // Bare-form `$ llm ...` puts `llm` as the first token of op.body
+                // with op.mcpConnector === undefined. Named-form `$ llm.run ...`
+                // would set op.mcpConnector === "llm" — match either.
+                const tokens = tokenizeKeywordArgs(op.body);
+                const head = tokens[0];
+                const isLlmDispatch = op.mcpConnector === "llm" || (head === "llm" && op.mcpConnector === undefined);
+                if (!isLlmDispatch)
+                    return;
+                for (const tok of tokens) {
+                    const eq = tok.indexOf("=");
+                    if (eq === -1)
+                        continue;
+                    const key = tok.slice(0, eq).trim();
+                    if (key !== "model")
+                        continue;
+                    let value = tok.slice(eq + 1).trim();
+                    // Strip outer quotes if present.
+                    if ((value.startsWith('"') && value.endsWith('"')) ||
+                        (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.slice(1, -1);
+                    }
+                    if (value === "")
+                        continue;
+                    // Substitutions — `${TAG}` / `$(TAG)` — are runtime-resolved.
+                    if (value.includes("$(") || value.includes("${"))
+                        continue;
+                    if (known.has(value))
+                        continue;
+                    const dedupKey = `${targetName}:${value}`;
+                    if (reported.has(dedupKey))
+                        continue;
+                    reported.add(dedupKey);
+                    const knownDescr = known.size === 0
+                        ? "(no LocalModels registered)"
+                        : [...known].sort().join(", ");
+                    findings.push({
+                        rule: "unknown-llm-model",
+                        severity: "warning",
+                        message: `\`$ llm model="${value}"\` in target '${targetName}': '${value}' matches no registered LocalModel alias and no \`models_available\` entry from any registered LocalModel. Known: ${knownDescr}.`,
+                        block: targetName,
+                        extras: { referenced_model: value },
+                    });
+                }
+            });
+        }
+        return findings;
+    },
+};
+// v0.16.5 — `$ llm` op with a kwarg outside the canonical closed set.
+// Catches authors leaking provider-API kwargs (e.g., `temperature=0.7`)
+// which the LocalModelMcpConnector bridge silently drops — LocalModel.run()
+// only consumes `{maxTokens, model}`. Tier-2 warning.
+//
+// Sibling to `unknown-llm-model` (v0.16.4) — same shape, different axis.
+// The `model=` axis validates a value against registered substrate state;
+// this rule validates a kwarg KEY against the documented closed surface.
+//
+// Per memory `9254a648`. Closed set lives in `LLM_KWARG_SURFACE`.
+const LLM_KWARG_SURFACE = new Set([
+    "prompt",
+    "maxTokens",
+    "model",
+    "timeout",
+    "approved",
+    "fallback",
+]);
+const UNKNOWN_LLM_ARG = {
+    id: "unknown-llm-arg",
+    severity: "warning",
+    description: "A `$ llm` op carries a kwarg outside the canonical surface (`prompt`/`maxTokens`/`model`/`timeout`/`approved`/`fallback`). Provider-API kwargs (e.g., `temperature=`) silently dropped by the bridge.",
+    remediation: "Drop the kwarg, or substitute the canonical equivalent. The closed surface is documented under `$ llm` in the language reference. If your substrate accepts additional kwargs, configure them at the LocalModel adapter layer (e.g., construct an OpenAILocalModel with `defaultTemperature: 0.7`) — kwargs from the skill body must match the substrate-neutral contract.",
+    check: (ctx) => {
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$")
+                    return;
+                const tokens = tokenizeKeywordArgs(op.body);
+                const head = tokens[0];
+                const isLlmDispatch = op.mcpConnector === "llm" || (head === "llm" && op.mcpConnector === undefined);
+                if (!isLlmDispatch)
+                    return;
+                for (const tok of tokens) {
+                    const eq = tok.indexOf("=");
+                    if (eq === -1)
+                        continue;
+                    const key = tok.slice(0, eq).trim();
+                    if (LLM_KWARG_SURFACE.has(key))
+                        continue;
+                    const dedupKey = `${targetName}:${key}`;
+                    if (reported.has(dedupKey))
+                        continue;
+                    reported.add(dedupKey);
+                    findings.push({
+                        rule: "unknown-llm-arg",
+                        severity: "warning",
+                        message: `\`$ llm\` in target '${targetName}' carries unknown kwarg '${key}'. Canonical surface: ${[...LLM_KWARG_SURFACE].sort().join(", ")}.`,
+                        block: targetName,
+                        extras: { kwarg: key },
+                    });
+                }
+            });
+        }
+        return findings;
+    },
+};
+// v0.16.5 — `$ data_read` op with a kwarg outside the canonical closed
+// set. Replaces the deleted `unknown-retrieval-arg` rule which targeted
+// the v0.7.0-removed `>` symbol op surface. Same shape as `unknown-llm-arg`.
+// Per memory `9254a648`.
+const DATA_READ_KWARG_SURFACE = new Set([
+    "mode",
+    "query",
+    "limit",
+    "connector",
+    "fallback",
+    "domain_tags",
+    "filters",
+    "min_confidence",
+]);
+const UNKNOWN_DATA_READ_ARG = {
+    id: "unknown-data-read-arg",
+    severity: "warning",
+    description: "A `$ data_read` op carries a kwarg outside the canonical surface (`mode`/`query`/`limit`/`connector`/`fallback`/`domain_tags`/`filters`/`min_confidence`).",
+    remediation: "Drop the kwarg, or substitute the canonical equivalent. The closed surface is documented under `$ data_read` in the language reference. Substrate-specific filters belong inside the `filters={...}` object literal, not as top-level kwargs.",
+    check: (ctx) => {
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                if (op.kind !== "$")
+                    return;
+                const tokens = tokenizeKeywordArgs(op.body);
+                const head = tokens[0];
+                const isDataReadDispatch = op.mcpConnector === "data_read" || (head === "data_read" && op.mcpConnector === undefined);
+                if (!isDataReadDispatch)
+                    return;
+                for (const tok of tokens) {
+                    const eq = tok.indexOf("=");
+                    if (eq === -1)
+                        continue;
+                    const key = tok.slice(0, eq).trim();
+                    if (DATA_READ_KWARG_SURFACE.has(key))
+                        continue;
+                    const dedupKey = `${targetName}:${key}`;
+                    if (reported.has(dedupKey))
+                        continue;
+                    reported.add(dedupKey);
+                    findings.push({
+                        rule: "unknown-data-read-arg",
+                        severity: "warning",
+                        message: `\`$ data_read\` in target '${targetName}' carries unknown kwarg '${key}'. Canonical surface: ${[...DATA_READ_KWARG_SURFACE].sort().join(", ")}.`,
+                        block: targetName,
+                        extras: { kwarg: key },
+                    });
+                }
+            });
+        }
+        return findings;
+    },
+};
 // v0.4.1 — `$ name.tool` where `name` is configured with an
 // `allowed_tools` list that doesn't include `tool`. Tier-1 lint error
 // at compile time. Closes the "minion-safe by default" framing from
@@ -2362,6 +2566,9 @@ const RULES = [
     TRANSCRIPT_FOOTGUN,
     SET_JSON_LITERAL_ADVISORY,
     SKILL_NAME_COLLISION,
+    UNKNOWN_LLM_MODEL,
+    UNKNOWN_LLM_ARG,
+    UNKNOWN_DATA_READ_ARG,
     // v0.9.2 — promoted from tier-3 info to tier-1 error (P0.9 in c9c667d2)
     NO_DEFAULT_TARGET,
     COLON_KWARG_SYNTAX,
@@ -2533,6 +2740,43 @@ function collectAgentConnectorNamesFromRegistry(registry) {
     // registry.ts) — empty array means "no real AgentConnector wired."
     return registry.listAgentConnectors().map((e) => e.name);
 }
+function collectLocalModelAliasesFromRegistry(registry) {
+    if (registry === undefined)
+        return undefined;
+    return registry.listLocalModels().map((e) => e.name);
+}
+// v0.16.4 — async sibling to collectLocalModelAliasesFromRegistry: probes each
+// registered LocalModel's `manifest()` to harvest `models_available`. Used by
+// the async `lint()` entry point so `unknown-llm-model` can validate against
+// both registry aliases AND the underlying substrate's model surface (sharpened
+// by Perry's `bfd776a9` audit insight — with manifest in capabilities, the lint
+// has substrate-aware source of truth, not just alias names).
+//
+// Per-instance try/catch — a throwing `manifest()` (e.g., substrate unreachable
+// at lint time) silently degrades to alias-only validation rather than failing
+// the lint. Adopters whose LocalModel `manifest()` omits `models_available`
+// (the contract permits absence) also gracefully fall through.
+async function collectLocalModelInfoFromRegistry(registry) {
+    if (registry === undefined)
+        return undefined;
+    const entries = registry.listLocalModels();
+    const aliases = entries.map((e) => e.name);
+    const available = new Set();
+    for (const entry of entries) {
+        try {
+            const m = await entry.instance.manifest();
+            const inner = m.manifest;
+            if (Array.isArray(inner.models_available)) {
+                for (const tag of inner.models_available)
+                    available.add(tag);
+            }
+        }
+        catch {
+            // Probe failure — degrade to alias-only for this instance.
+        }
+    }
+    return { aliases, modelsAvailable: [...available] };
+}
 function collectMcpConnectorAllowedToolsFromRegistry(registry) {
     const out = new Map();
     if (registry === undefined)