skillscript-runtime 0.22.1 → 0.23.1

package/dist/lint.js

@@ -24,6 +24,7 @@ export async function lint(source, options) {
         bareArrayReturnTools: options?.bareArrayReturnTools ?? [],
         shellAllowlist: options?.shellAllowlist,
         mcpConnectorStaticTools: collectMcpConnectorStaticToolsFromRegistry(options?.registry),
+        mcpConnectorToolSchemas: options?.mcpConnectorToolSchemas ?? (await collectMcpConnectorToolSchemasFromRegistry(options?.registry)),
     };
     const findings = [];
     for (const rule of RULES) {
@@ -67,6 +68,9 @@ export function lintSync(source, options) {
         bareArrayReturnTools: options?.bareArrayReturnTools ?? [],
         shellAllowlist: options?.shellAllowlist,
         mcpConnectorStaticTools: collectMcpConnectorStaticToolsFromRegistry(options?.registry),
+        // lintSync can't warm schemas (describeTools is async); honor an explicit
+        // injection (tests) but otherwise leave empty → connector-arg rules degrade.
+        mcpConnectorToolSchemas: options?.mcpConnectorToolSchemas ?? new Map(),
     };
     const findings = [];
     for (const rule of RULES) {
@@ -1021,6 +1025,16 @@ const UNVERIFIED_QUALIFIED_TOOL = {
                 if (m === null)
                     return;
                 const toolName = m[1];
+                // v0.23.1 — if the connector's warmed `describeTools` schema verifies
+                // THIS tool (the same source the tier-2 connector-arg rules consume),
+                // the surface IS known — the "can't validate statically" advisory is
+                // stale and contradicts tier-2 ("you passed an unknown arg" + "I can't
+                // see this tool" on the same op). Skip it. Tier-3 still fires when
+                // neither a static nor a warmed dynamic surface verifies the tool
+                // (truly-opaque connector: describeTools absent/unreachable, or a
+                // misspelled tool name not in the fetched surface).
+                if (ctx.mcpConnectorToolSchemas.get(ref)?.has(toolName))
+                    return;
                 const key = `${targetName}:${ref}:${toolName}`;
                 if (reported.has(key))
                     return;
@@ -1037,6 +1051,124 @@ const UNVERIFIED_QUALIFIED_TOOL = {
         return findings;
     },
 };
+// v0.23.0 — connector-aware input lint. For a qualified `$ ref.tool arg=...`
+// op where the connector's warmed inputSchema is available (ctx.
+// mcpConnectorToolSchemas), validate the arg NAMES against the schema. Catches
+// the typo class (`$ ddg.search querry=...`) statically — today it compiles
+// clean and fails only at runtime because MCP connector args are unvalidated.
+//
+// SCOPE (phase 1): qualified `$ connector.tool` form only (bare `$ tool`
+// resolves its owning connector at dispatch and is deferred). Reads only the
+// pre-warmed cache — no I/O here; the async lint() entry point warms it.
+//
+// GRACEFUL DEGRADE: no cache entry / no inputSchema / open schema
+// (additionalProperties: true) → skip. Schema-less or unreachable connectors
+// behave exactly as before (no false positives).
+function connectorArgLintInfo(ctx, op) {
+    if (op.kind !== "$" || op.mcpConnector === undefined)
+        return null;
+    const byTool = ctx.mcpConnectorToolSchemas.get(op.mcpConnector);
+    if (byTool === undefined)
+        return null;
+    const m = /^([A-Za-z_][\w:-]*)\s*([\s\S]*)$/.exec(op.body);
+    if (m === null)
+        return null;
+    const toolName = m[1];
+    const descriptor = byTool.get(toolName);
+    if (descriptor === undefined || descriptor.inputSchema === undefined)
+        return null;
+    const argNames = [];
+    for (const tok of tokenizeKeywordArgs(m[2] ?? "")) {
+        const eq = tok.indexOf("=");
+        if (eq === -1)
+            continue;
+        const k = tok.slice(0, eq).trim();
+        // `timeout` is a runtime-reserved per-op kwarg, popped before the connector
+        // sees args — never part of the tool's own schema.
+        if (k !== "" && k !== "timeout")
+            argNames.push(k);
+    }
+    return { connector: op.mcpConnector, toolName, argNames, inputSchema: descriptor.inputSchema };
+}
+const UNKNOWN_CONNECTOR_ARG = {
+    id: "unknown-connector-arg",
+    severity: "warning",
+    description: "A qualified `$ ref.tool arg=...` op passes an argument name the connector tool's inputSchema doesn't declare.",
+    remediation: "Use an argument the tool declares (see `runtime_capabilities` for the connector tool's schema), or remove the unrecognized one. If the tool genuinely accepts it, the upstream inputSchema may be incomplete — verify before relying on it.",
+    check: (ctx) => {
+        if (ctx.mcpConnectorToolSchemas.size === 0)
+            return [];
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                const info = connectorArgLintInfo(ctx, op);
+                if (info === null)
+                    return;
+                const props = info.inputSchema.properties;
+                if (props === null || typeof props !== "object")
+                    return; // can't enumerate the valid set
+                if (info.inputSchema.additionalProperties === true)
+                    return; // open schema
+                const valid = new Set(Object.keys(props));
+                for (const arg of info.argNames) {
+                    if (valid.has(arg))
+                        continue;
+                    const key = `${targetName}:${info.connector}:${info.toolName}:${arg}`;
+                    if (reported.has(key))
+                        continue;
+                    reported.add(key);
+                    findings.push({
+                        rule: "unknown-connector-arg",
+                        severity: "warning",
+                        message: `\`$ ${info.connector}.${info.toolName}\` in target '${targetName}' passes arg '${arg}', which isn't in the tool's input schema. Declared args: ${[...valid].join(", ") || "(none)"}.`,
+                        block: targetName,
+                        extras: { connector: info.connector, tool: info.toolName, arg, declared_args: [...valid] },
+                    });
+                }
+            });
+        }
+        return findings;
+    },
+};
+const MISSING_REQUIRED_CONNECTOR_ARG = {
+    id: "missing-required-connector-arg",
+    severity: "warning",
+    description: "A qualified `$ ref.tool` op omits an argument the connector tool's inputSchema marks required.",
+    remediation: "Supply the required argument(s). See `runtime_capabilities` for the tool's schema (its `required` list).",
+    check: (ctx) => {
+        if (ctx.mcpConnectorToolSchemas.size === 0)
+            return [];
+        const findings = [];
+        const reported = new Set();
+        for (const [targetName, target] of ctx.parsed.targets) {
+            walkOps(target.ops, (op) => {
+                const info = connectorArgLintInfo(ctx, op);
+                if (info === null)
+                    return;
+                const requiredRaw = info.inputSchema.required;
+                if (!Array.isArray(requiredRaw))
+                    return;
+                const provided = new Set(info.argNames);
+                const missing = requiredRaw.filter((r) => typeof r === "string" && !provided.has(r));
+                if (missing.length === 0)
+                    return;
+                const key = `${targetName}:${info.connector}:${info.toolName}:${missing.join(",")}`;
+                if (reported.has(key))
+                    return;
+                reported.add(key);
+                findings.push({
+                    rule: "missing-required-connector-arg",
+                    severity: "warning",
+                    message: `\`$ ${info.connector}.${info.toolName}\` in target '${targetName}' is missing required arg(s): ${missing.join(", ")}.`,
+                    block: targetName,
+                    extras: { connector: info.connector, tool: info.toolName, missing },
+                });
+            });
+        }
+        return findings;
+    },
+};
 // v0.5.0 item 5 — bare `$ TOOL` op (no connector prefix) when no
 // `primary` connector is wired. Runtime now throws ConnectorNotFoundError
 // instead of silent-stub (was: emitted "Would call tool X" + bound null,
@@ -3271,6 +3403,8 @@ const RULES = [
     DISALLOWED_TOOL,
     UNKNOWN_TOOL_ON_CONNECTOR,
     UNVERIFIED_QUALIFIED_TOOL,
+    UNKNOWN_CONNECTOR_ARG,
+    MISSING_REQUIRED_CONNECTOR_ARG,
     UNINITIALIZED_APPEND,
     FOREACH_LOCAL_ACCUMULATOR_TARGET,
     APPEND_TO_NON_LIST,
@@ -3544,6 +3678,49 @@ function collectMcpConnectorStaticToolsFromRegistry(registry) {
     }
     return out;
 }
+/**
+ * v0.23.0 — warm + collect per-connector tool schemas for connector-aware
+ * input lint. For each wired MCP connector exposing `describeTools()`, calls it
+ * (which ensure-warms a read-only `tools/list` when cold — protocol
+ * introspection, NOT a tool dispatch, so no effect boundary is crossed) under a
+ * short timeout. Best-effort + graceful: a connector with no `describeTools()`,
+ * an unreachable upstream, or a timeout simply contributes no schema, and the
+ * arg rules stay silent for it (no false positives). Async — only reachable via
+ * the async `lint()` entry point.
+ */
+const CONNECTOR_SCHEMA_WARM_TIMEOUT_MS = 2000;
+async function collectMcpConnectorToolSchemasFromRegistry(registry) {
+    const out = new Map();
+    if (registry === undefined)
+        return out;
+    await Promise.all(registry.listMcpConnectors().map(async (e) => {
+        const instance = e.instance;
+        if (typeof instance.describeTools !== "function")
+            return;
+        try {
+            const descriptors = await Promise.race([
+                instance.describeTools(),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("describeTools timeout")), CONNECTOR_SCHEMA_WARM_TIMEOUT_MS)),
+            ]);
+            // Respect the operator's per-connector `allowed_tools` gate: don't
+            // surface (or validate against) tools the operator gated off — a
+            // disallowed `$ conn.tool` is the `disallowed-tool` rule's job, not
+            // ours. undefined allowlist = allow-all.
+            const allowed = e.allowedTools;
+            const byTool = new Map();
+            for (const d of descriptors) {
+                if (allowed !== undefined && !allowed.includes(d.name))
+                    continue;
+                byTool.set(d.name, d);
+            }
+            out.set(e.name, byTool);
+        }
+        catch {
+            // Unreachable / timeout / no schema — degrade arg-agnostic for this connector.
+        }
+    }));
+    return out;
+}
 function buildFeatureSet(classes) {
     const provided = new Set();
     for (const Ctor of classes) {