@sweny-ai/core 0.1.141 → 0.1.143

package/dist/harness/abort.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Timeout + caller-signal wiring shared by every adapter. No agent SDK imports.
+ */
+/**
+ * Wire an optional timeout + caller signal onto a single AbortController.
+ *
+ * Returns undefined when neither a timeout nor a signal is supplied so the
+ * default code path (no abortController, no timer) is byte-for-byte unchanged.
+ *
+ * `reason()` reports whether the abort came from the timeout timer or an
+ * external signal, so callers can log a distinct timeout message.
+ */
+export declare function makeAbort(timeoutMs?: number, signal?: AbortSignal): {
+    controller: AbortController;
+    clear: () => void;
+    reason: () => "timeout" | "signal" | undefined;
+} | undefined;

package/dist/harness/abort.js

@@ -0,0 +1,53 @@
+/**
+ * Timeout + caller-signal wiring shared by every adapter. No agent SDK imports.
+ */
+/**
+ * Wire an optional timeout + caller signal onto a single AbortController.
+ *
+ * Returns undefined when neither a timeout nor a signal is supplied so the
+ * default code path (no abortController, no timer) is byte-for-byte unchanged.
+ *
+ * `reason()` reports whether the abort came from the timeout timer or an
+ * external signal, so callers can log a distinct timeout message.
+ */
+export function makeAbort(timeoutMs, signal) {
+    if (!timeoutMs && !signal)
+        return undefined;
+    const controller = new AbortController();
+    let reason;
+    let timer;
+    const onSignalAbort = () => {
+        if (controller.signal.aborted)
+            return;
+        reason = "signal";
+        controller.abort();
+    };
+    if (signal) {
+        if (signal.aborted) {
+            reason = "signal";
+            controller.abort();
+        }
+        else {
+            signal.addEventListener("abort", onSignalAbort, { once: true });
+        }
+    }
+    if (timeoutMs && timeoutMs > 0 && !controller.signal.aborted) {
+        timer = setTimeout(() => {
+            if (controller.signal.aborted)
+                return;
+            reason = "timeout";
+            controller.abort();
+        }, timeoutMs);
+        // Don't keep the event loop alive just for the abort timer.
+        timer?.unref?.();
+    }
+    return {
+        controller,
+        reason: () => reason,
+        clear: () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onSignalAbort);
+        },
+    };
+}

package/dist/harness/agents.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The agent ids `--agent` / `coding-agent-provider` accept. Each one has an
+ * adapter and a green contract suite; anything else is refused, so sweny never
+ * runs one agent under another's name. No runtime imports (the CLI config and
+ * the harness factory share it).
+ */
+export declare const SUPPORTED_AGENTS: readonly ["claude", "codex"];
+export type SupportedAgent = (typeof SUPPORTED_AGENTS)[number];
+export declare function isSupportedAgent(id: string): id is SupportedAgent;
+/** The error for an agent id with no adapter. */
+export declare function unsupportedAgentError(id: string): string;

package/dist/harness/agents.js

@@ -0,0 +1,15 @@
+/**
+ * The agent ids `--agent` / `coding-agent-provider` accept. Each one has an
+ * adapter and a green contract suite; anything else is refused, so sweny never
+ * runs one agent under another's name. No runtime imports (the CLI config and
+ * the harness factory share it).
+ */
+export const SUPPORTED_AGENTS = ["claude", "codex"];
+export function isSupportedAgent(id) {
+    return SUPPORTED_AGENTS.includes(id);
+}
+/** The error for an agent id with no adapter. */
+export function unsupportedAgentError(id) {
+    return (`Unsupported coding agent "${id}": supported agents are "claude" (headless Claude Code) ` +
+        `and "codex" (Codex CLI). Remove --agent / coding-agent-provider or set it to one of them.`);
+}

package/dist/harness/capabilities.d.ts

@@ -5,3 +5,26 @@
 import type { HarnessCapabilities } from "./types.js";
 /** Claude Code enforces every sweny opinion natively, so `policyGate` never degrades or refuses it. */
 export declare const CLAUDE_CODE_CAPABILITIES: HarnessCapabilities;
+/**
+ * Codex (`codex exec --json`), declared from the openai/codex source at
+ * rust-v0.159.2 and probed by the contract suite against the scripted fake:
+ * - structuredOutput native: `--output-schema <file>` (exec/src/cli.rs).
+ * - toolTrace full: `item.*` events for command_execution, file_change,
+ *   mcp_tool_call and web_search, each with an id and a status
+ *   (exec/src/exec_events.rs).
+ * - builtinDeny shell-only, plus net and subagent: `features.shell_tool=false`
+ *   removes every shell tool (core/src/tools/spec_plan.rs add_shell_tools),
+ *   `web_search="disabled"` removes web search, and `features.multi_agent=false`
+ *   with `agents.enabled=false` removes subagents. apply_patch has no switch,
+ *   so write and edit cannot be denied as classes.
+ * - mcp exclusive native: `--ignore-user-config` drops `$CODEX_HOME/config.toml`,
+ *   and project `.codex/config.toml` layers stay disabled for a project that
+ *   is not trusted in that ignored file (config/src/loader/mod.rs).
+ * - sandbox fs only: `--sandbox read-only|workspace-write`. Network is one
+ *   on/off switch (`sandbox_workspace_write.network_access`), not a host list.
+ * - readOnly native: `--sandbox read-only` plus the shell, web search and
+ *   subagent switches above.
+ * - turnLimit watchdog: codex exec has no turn limit; sweny counts tool calls.
+ * - usage tokens only: `turn.completed.usage`; Codex reports no cost.
+ */
+export declare const CODEX_CAPABILITIES: HarnessCapabilities;

package/dist/harness/capabilities.js

@@ -15,3 +15,38 @@ export const CLAUDE_CODE_CAPABILITIES = {
     cancel: "signal",
     resume: false,
 };
+/**
+ * Codex (`codex exec --json`), declared from the openai/codex source at
+ * rust-v0.159.2 and probed by the contract suite against the scripted fake:
+ * - structuredOutput native: `--output-schema <file>` (exec/src/cli.rs).
+ * - toolTrace full: `item.*` events for command_execution, file_change,
+ *   mcp_tool_call and web_search, each with an id and a status
+ *   (exec/src/exec_events.rs).
+ * - builtinDeny shell-only, plus net and subagent: `features.shell_tool=false`
+ *   removes every shell tool (core/src/tools/spec_plan.rs add_shell_tools),
+ *   `web_search="disabled"` removes web search, and `features.multi_agent=false`
+ *   with `agents.enabled=false` removes subagents. apply_patch has no switch,
+ *   so write and edit cannot be denied as classes.
+ * - mcp exclusive native: `--ignore-user-config` drops `$CODEX_HOME/config.toml`,
+ *   and project `.codex/config.toml` layers stay disabled for a project that
+ *   is not trusted in that ignored file (config/src/loader/mod.rs).
+ * - sandbox fs only: `--sandbox read-only|workspace-write`. Network is one
+ *   on/off switch (`sandbox_workspace_write.network_access`), not a host list.
+ * - readOnly native: `--sandbox read-only` plus the shell, web search and
+ *   subagent switches above.
+ * - turnLimit watchdog: codex exec has no turn limit; sweny counts tool calls.
+ * - usage tokens only: `turn.completed.usage`; Codex reports no cost.
+ */
+export const CODEX_CAPABILITIES = {
+    structuredOutput: "native",
+    toolTrace: "full",
+    builtinDeny: "shell-only",
+    denyClasses: ["shell", "net", "subagent"],
+    mcp: { inject: true, exclusive: "native" },
+    sandbox: { fs: true, network: false },
+    readOnly: "native",
+    turnLimit: "watchdog",
+    usage: { tokens: true, costUsd: false, live: false },
+    cancel: "kill",
+    resume: false,
+};

package/dist/harness/claude-code.d.ts

@@ -10,10 +10,13 @@
  */
 import type { Claude, Tool, ToolContext, Logger, McpServerConfig } from "../types.js";
 import { type SandboxMode } from "../agent-env.js";
-import type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessInfo, HarnessRunRequest, HarnessRunResult } from "./types.js";
+import type { AgentHarness, HarnessCapabilities, HarnessCompleteRequest, HarnessInfo, HarnessRunRequest, HarnessRunResult, ToolClass } from "./types.js";
 import { CLAUDE_CODE_CAPABILITIES } from "./capabilities.js";
 import { buildEvaluatePrompt } from "./prompts.js";
+import { parseToolResultContent, summarizeToolError } from "./parse.js";
+import { makeAbort } from "./abort.js";
 export { buildEvaluatePrompt, CLAUDE_CODE_CAPABILITIES };
+export { parseToolResultContent, summarizeToolError, makeAbort };
 /**
  * Built-in tools disallowed for the route-evaluation (`evaluate`) and
  * reflection/judge (`ask`) calls.
@@ -34,6 +37,11 @@ export declare const CLASSIFICATION_DISALLOWED_TOOLS: readonly ["Bash", "Write",
  * Read, Grep, Glob and WebSearch stay available for analysis.
  */
 export declare const READ_ONLY_DISALLOWED_TOOLS: readonly ["Bash", "Write", "Edit", "MultiEdit", "NotebookEdit", "Task", "Agent", "WebFetch"];
+/**
+ * Claude Code built-in tool names per portable tool class. A node's
+ * `tools.deny` classes compile to these names on `disallowedTools`.
+ */
+export declare const CLAUDE_TOOLS_BY_CLASS: Readonly<Record<ToolClass, readonly string[]>>;
 /** How sweny resolves which credentials reach the Claude Code subprocess. */
 export type SwenyAuthMode = "auto" | "api-key" | "oauth";
 export interface ResolveAuthEnvOpts {
@@ -120,20 +128,6 @@ export interface ClaudeCodeHarnessOptions {
         args: string[];
     };
 }
-/**
- * Wire an optional timeout + caller signal onto a single AbortController.
- *
- * Returns undefined when neither a timeout nor a signal is supplied so the
- * default code path (no abortController, no timer) is byte-for-byte unchanged.
- *
- * `reason()` reports whether the abort came from the timeout timer or an
- * external signal, so callers can log a distinct timeout message.
- */
-export declare function makeAbort(timeoutMs?: number, signal?: AbortSignal): {
-    controller: AbortController;
-    clear: () => void;
-    reason: () => "timeout" | "signal" | undefined;
-} | undefined;
 export declare class ClaudeCodeHarness implements Claude, AgentHarness {
     readonly id: "claude-code";
     readonly capabilities: HarnessCapabilities;
@@ -227,28 +221,3 @@ export type ClaudeClient = ClaudeCodeHarness;
  * @internal Exported for the tool bridge parity test (#414).
  */
 export declare function coreToolToSdkTool(coreTool: Tool, defaultCtx: ToolContext): import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<Record<string, import("zod").ZodType<any, import("zod").ZodTypeDef, any>>>;
-/**
- * Best-effort recovery of typed output from a tool_result's `content`.
- *
- * The MCP protocol sends tool results as string content. Our in-process
- * wrapper JSON-stringifies structured output before returning; external
- * MCP servers generally do the same for JSON payloads. If the string
- * looks like a JSON object or array and parses, return the parsed value
- * so verify's output-path walks work against typed data.
- *
- * Raw strings are preserved verbatim. JSON-primitive strings (e.g. the
- * literal four characters `"42"`) are intentionally NOT parsed - we
- * cannot distinguish a tool that returned the number 42 (wrapper sends
- * `"42"`) from a tool that returned the string "42" (wrapper also sends
- * `"42"`). Preserving the string is safer than guessing.
- */
-export declare function parseToolResultContent(content: unknown): unknown;
-/**
- * Produce a short, single-line description of a tool-error payload suitable
- * for the CI log stream. The full parsed value stays on the ToolCall for
- * verify and downstream tooling - this is only for inline observability.
- *
- * Collapses newlines, trims whitespace, and caps to 300 chars so a huge
- * API response body doesn't flood the log.
- */
-export declare function summarizeToolError(parsed: unknown): string;

package/dist/harness/claude-code.js

@@ -12,13 +12,15 @@ import { query, createSdkMcpServer, tool as sdkTool } from "@anthropic-ai/claude
 import { createRequire } from "node:module";
 import { consoleLogger } from "../types.js";
 import { reportWithheldEnv, parseList, resolveEnvScope, scopeAgentEnv, resolveAgentSandbox, } from "../agent-env.js";
-import { fenceUntrustedJson } from "../untrusted.js";
 import { policyGate } from "./policy.js";
 import { CLAUDE_CODE_CAPABILITIES } from "./capabilities.js";
-import { ask as coreAsk, evaluate as coreEvaluate, buildEvaluatePrompt } from "./prompts.js";
+import { ask as coreAsk, evaluate as coreEvaluate, buildEvaluatePrompt, buildNodePrompt } from "./prompts.js";
 import { jsonSchemaToZodShape, toolErrorToMcpResult, toolOutputToMcpResult } from "./tool-bridge/protocol.js";
 import { startToolBridge } from "./tool-bridge/server.js";
+import { parseToolResultContent, summarizeToolError, tryParseJSON } from "./parse.js";
+import { makeAbort } from "./abort.js";
 export { buildEvaluatePrompt, CLAUDE_CODE_CAPABILITIES };
+export { parseToolResultContent, summarizeToolError, makeAbort };
 let cachedSdkVersion;
 /** Version of the Claude Agent SDK this adapter drives; "unknown" when it cannot be read. */
 function claudeSdkVersion() {
@@ -72,6 +74,17 @@ export const READ_ONLY_DISALLOWED_TOOLS = [
     "Agent",
     "WebFetch",
 ];
+/**
+ * Claude Code built-in tool names per portable tool class. A node's
+ * `tools.deny` classes compile to these names on `disallowedTools`.
+ */
+export const CLAUDE_TOOLS_BY_CLASS = {
+    shell: ["Bash"],
+    write: ["Write", "NotebookEdit"],
+    edit: ["Edit", "MultiEdit"],
+    net: ["WebFetch", "WebSearch"],
+    subagent: ["Task", "Agent"],
+};
 /**
  * Decide which auth credentials survive into the Claude Code subprocess env.
  *
@@ -131,56 +144,6 @@ export function resolveAuthEnv(env, opts = {}) {
     opts.logger?.debug?.(`[sweny] auth mode: ${mode}`);
     return out;
 }
-/**
- * Wire an optional timeout + caller signal onto a single AbortController.
- *
- * Returns undefined when neither a timeout nor a signal is supplied so the
- * default code path (no abortController, no timer) is byte-for-byte unchanged.
- *
- * `reason()` reports whether the abort came from the timeout timer or an
- * external signal, so callers can log a distinct timeout message.
- */
-export function makeAbort(timeoutMs, signal) {
-    if (!timeoutMs && !signal)
-        return undefined;
-    const controller = new AbortController();
-    let reason;
-    let timer;
-    const onSignalAbort = () => {
-        if (controller.signal.aborted)
-            return;
-        reason = "signal";
-        controller.abort();
-    };
-    if (signal) {
-        if (signal.aborted) {
-            reason = "signal";
-            controller.abort();
-        }
-        else {
-            signal.addEventListener("abort", onSignalAbort, { once: true });
-        }
-    }
-    if (timeoutMs && timeoutMs > 0 && !controller.signal.aborted) {
-        timer = setTimeout(() => {
-            if (controller.signal.aborted)
-                return;
-            reason = "timeout";
-            controller.abort();
-        }, timeoutMs);
-        // Don't keep the event loop alive just for the abort timer.
-        timer?.unref?.();
-    }
-    return {
-        controller,
-        reason: () => reason,
-        clear: () => {
-            if (timer)
-                clearTimeout(timer);
-            signal?.removeEventListener("abort", onSignalAbort);
-        },
-    };
-}
 /**
  * Best-effort interrupt of an SDK query stream. Called from `finally` so an
  * early return / timeout / throw does not leak the underlying subprocess.
@@ -297,13 +260,16 @@ export class ClaudeCodeHarness {
     async run(req) {
         const policy = req.policy ?? {
             readOnly: !!req.readOnly,
-            deny: [],
+            deny: req.deny ?? [],
             nativeDeny: req.disallowedTools,
             egress: req.agentAccess?.domains ?? [],
             strict: false,
         };
         const gate = policyGate(this.capabilities, policy);
-        const result = await this.runQuery(req);
+        // Portable deny classes (`tools.deny: [write]`) compile to Claude Code tool names.
+        const classNames = policy.deny.flatMap((c) => CLAUDE_TOOLS_BY_CLASS[c] ?? []);
+        const disallowedTools = classNames.length > 0 ? [...new Set([...(req.disallowedTools ?? []), ...classNames])] : req.disallowedTools;
+        const result = await this.runQuery({ ...req, disallowedTools });
         return { ...result, harness: this.info(), degraded: gate.degraded };
     }
     async runQuery(opts) {
@@ -371,15 +337,7 @@ export class ClaudeCodeHarness {
         let bridge;
         // Build prompt. Context (workflow input such as issues/alerts, plus prior
         // node outputs) is fenced as untrusted data (#360).
-        const prompt = [
-            `## Instruction\n\n${instruction}`,
-            `## Context\n\n${fenceUntrustedJson(context, "context")}`,
-            outputSchema
-                ? `## Required Output\n\nYou MUST end with a JSON object matching this schema:\n\`\`\`json\n${JSON.stringify(outputSchema, null, 2)}\n\`\`\``
-                : "",
-        ]
-            .filter(Boolean)
-            .join("\n\n");
+        const prompt = buildNodePrompt(instruction, context, outputSchema);
         const env = this.buildEnv(agentAccess?.envVars);
         let response = "";
         // CC-08: when the SDK populates typed structured output (because we passed
@@ -749,112 +707,6 @@ export function coreToolToSdkTool(coreTool, defaultCtx) {
         }
     });
 }
-/**
- * Best-effort recovery of typed output from a tool_result's `content`.
- *
- * The MCP protocol sends tool results as string content. Our in-process
- * wrapper JSON-stringifies structured output before returning; external
- * MCP servers generally do the same for JSON payloads. If the string
- * looks like a JSON object or array and parses, return the parsed value
- * so verify's output-path walks work against typed data.
- *
- * Raw strings are preserved verbatim. JSON-primitive strings (e.g. the
- * literal four characters `"42"`) are intentionally NOT parsed - we
- * cannot distinguish a tool that returned the number 42 (wrapper sends
- * `"42"`) from a tool that returned the string "42" (wrapper also sends
- * `"42"`). Preserving the string is safer than guessing.
- */
-export function parseToolResultContent(content) {
-    // The Anthropic tool_result `content` field can be a block array
-    // (e.g. [{type:"text",text:"..."}, ...]) rather than a string. When it is,
-    // concatenate the text of every {type:"text"} block (recursing through any
-    // nested content), then run the same object/array JSON-parse logic on the
-    // joined string. This keeps `call.output` the actual payload instead of the
-    // raw wrapper array that eval/route logic would otherwise have to walk.
-    if (Array.isArray(content)) {
-        const text = collectBlockText(content);
-        return parseJsonObjectOrArray(text);
-    }
-    if (typeof content !== "string")
-        return content;
-    return parseJsonObjectOrArray(content);
-}
-/**
- * Parse a string only when it is an unambiguous JSON object or array.
- *
- * Strings, numbers, booleans, and null would all corrupt or discard
- * information (we cannot distinguish the literal text `"42"` from the number
- * 42), so non-object/array inputs are preserved verbatim.
- */
-function parseJsonObjectOrArray(content) {
-    const trimmed = content.trim();
-    if (trimmed.length === 0)
-        return content;
-    const first = trimmed[0];
-    if (first !== "{" && first !== "[")
-        return content;
-    try {
-        return JSON.parse(trimmed);
-    }
-    catch {
-        return content;
-    }
-}
-/**
- * Concatenate the text of an array of content blocks. Handles {type:"text"}
- * blocks and recurses into any nested `content` array so deeply-wrapped tool
- * results still flatten to their underlying text.
- */
-function collectBlockText(blocks) {
-    const parts = [];
-    for (const block of blocks) {
-        if (typeof block === "string") {
-            parts.push(block);
-            continue;
-        }
-        if (!block || typeof block !== "object")
-            continue;
-        const b = block;
-        if (b.type === "text" && typeof b.text === "string") {
-            parts.push(b.text);
-        }
-        else if (Array.isArray(b.content)) {
-            parts.push(collectBlockText(b.content));
-        }
-        else if (typeof b.text === "string") {
-            // Some producers omit an explicit type but still carry text.
-            parts.push(b.text);
-        }
-    }
-    return parts.join("");
-}
-/**
- * Produce a short, single-line description of a tool-error payload suitable
- * for the CI log stream. The full parsed value stays on the ToolCall for
- * verify and downstream tooling - this is only for inline observability.
- *
- * Collapses newlines, trims whitespace, and caps to 300 chars so a huge
- * API response body doesn't flood the log.
- */
-export function summarizeToolError(parsed) {
-    let raw;
-    if (typeof parsed === "string") {
-        raw = parsed;
-    }
-    else if (parsed && typeof parsed === "object") {
-        try {
-            raw = JSON.stringify(parsed);
-        }
-        catch {
-            raw = String(parsed);
-        }
-    }
-    else {
-        raw = String(parsed);
-    }
-    const collapsed = raw.replace(/\s+/g, " ").trim();
-    return collapsed.length > 300 ? collapsed.slice(0, 297) + "..." : collapsed;
-}
 /** Strip MCP server prefix: "mcp__server__tool" → "tool" */
 function stripMcpPrefix(name) {
     const parts = name.split("__");
@@ -862,142 +714,3 @@ function stripMcpPrefix(name) {
         return parts.slice(2).join("__");
     return name;
 }
-// ─── JSON extraction ────────────────────────────────────────────
-/**
- * Extract a JSON object from Claude's text response.
- *
- * Strategy (in order):
- * 1. LAST ```json code block``` - models put their real final answer last, so
- *    a prompt-injected fake fenced block placed earlier must not win.
- * 2. Last brace-delimited `{...}` block - handles inline JSON at end of text
- * 3. Full text parse - for responses that are pure JSON
- * 4. Empty object - safe fallback
- *
- * When `outputSchema` is supplied, the parsed object is checked against it.
- * A mismatch is logged (warning) rather than silently accepted, so a
- * non-conforming model answer is at least attributable.
- */
-function tryParseJSON(text, outputSchema, logger) {
-    if (!text)
-        return {};
-    const finalize = (parsed) => {
-        if (outputSchema) {
-            const problems = schemaMismatches(parsed, outputSchema);
-            if (problems.length > 0) {
-                logger?.warn?.(`Claude output did not conform to outputSchema: ${problems.join("; ")}`);
-            }
-        }
-        return parsed;
-    };
-    // 1. Code block - scan ALL fenced blocks, prefer the LAST that parses.
-    const fences = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/g)];
-    for (let i = fences.length - 1; i >= 0; i--) {
-        try {
-            const parsed = JSON.parse(fences[i][1].trim());
-            if (typeof parsed === "object" && parsed !== null)
-                return finalize(parsed);
-        }
-        catch {
-            /* try the next-earlier fence, then fall through to brace scan */
-        }
-    }
-    // 2. Last brace-delimited block (scan backwards for matching braces)
-    const lastBrace = text.lastIndexOf("}");
-    if (lastBrace !== -1) {
-        let depth = 0;
-        for (let i = lastBrace; i >= 0; i--) {
-            if (text[i] === "}")
-                depth++;
-            else if (text[i] === "{")
-                depth--;
-            if (depth === 0) {
-                try {
-                    const parsed = JSON.parse(text.slice(i, lastBrace + 1));
-                    if (typeof parsed === "object" && parsed !== null)
-                        return finalize(parsed);
-                }
-                catch {
-                    /* try next strategy */
-                }
-                break;
-            }
-        }
-    }
-    // 3. Full text parse
-    try {
-        const parsed = JSON.parse(text.trim());
-        if (typeof parsed === "object" && parsed !== null)
-            return finalize(parsed);
-    }
-    catch {
-        /* fall through */
-    }
-    return {};
-}
-/**
- * Lightweight structural check of a parsed object against a JSON Schema.
- *
- * Deliberately shallow: it verifies `required` keys are present and that the
- * top-level `type` and each declared property `type` match. It does NOT do
- * full JSON Schema validation (no `$ref`, `oneOf`, formats, nested arrays).
- * The contract here is "flag an obviously non-conforming object" so a mismatch
- * is logged rather than silently accepted; it is not a validation gate.
- *
- * Returns a list of human-readable problems; empty means no detected mismatch.
- */
-function schemaMismatches(value, schema) {
-    const problems = [];
-    const s = schema;
-    if (s.type === "object" || s.properties || s.required) {
-        if (typeof value !== "object" || value === null || Array.isArray(value)) {
-            return [`expected an object, got ${Array.isArray(value) ? "array" : typeof value}`];
-        }
-        const obj = value;
-        const required = Array.isArray(s.required) ? s.required : [];
-        for (const key of required) {
-            if (!(key in obj) || obj[key] === undefined) {
-                problems.push(`missing required property "${key}"`);
-            }
-        }
-        const props = s.properties ?? {};
-        for (const [key, propSchema] of Object.entries(props)) {
-            if (!(key in obj) || obj[key] === undefined || obj[key] === null)
-                continue;
-            const expected = propSchema?.type;
-            if (typeof expected === "string" && !jsonTypeMatches(obj[key], expected)) {
-                problems.push(`property "${key}" expected ${expected}, got ${jsonTypeOf(obj[key])}`);
-            }
-        }
-    }
-    else if (typeof s.type === "string" && !jsonTypeMatches(value, s.type)) {
-        problems.push(`expected ${s.type}, got ${jsonTypeOf(value)}`);
-    }
-    return problems;
-}
-function jsonTypeOf(value) {
-    if (value === null)
-        return "null";
-    if (Array.isArray(value))
-        return "array";
-    return typeof value;
-}
-function jsonTypeMatches(value, expected) {
-    switch (expected) {
-        case "object":
-            return typeof value === "object" && value !== null && !Array.isArray(value);
-        case "array":
-            return Array.isArray(value);
-        case "string":
-            return typeof value === "string";
-        case "number":
-            return typeof value === "number";
-        case "integer":
-            return typeof value === "number" && Number.isInteger(value);
-        case "boolean":
-            return typeof value === "boolean";
-        case "null":
-            return value === null;
-        default:
-            return true; // unknown/unsupported type keyword - don't flag
-    }
-}