@sweny-ai/core 0.1.101 → 0.1.103

package/dist/browser.d.ts

@@ -13,11 +13,12 @@
  *   - `buildWorkflow` / `refineWorkflow` — depend on the Claude interface.
  *   - Testing helpers — `MockClaude`, `createFileSkill` use `node:fs`.
  */
-export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, } from "./types.js";
+export type { Skill, SkillCategory, Tool, ToolContext, ConfigField, JSONSchema, Workflow, Node, Edge, NodeResult, ToolCall, ExecutionEvent, Observer, Claude, Logger, Evaluator, EvaluatorRule, EvalResult, EvaluatorKind, NodeRequires, NodeRetry, OutputMatch, NodeSources, EvalPolicy, RequiresOnFail, McpTransport, WorkflowType, SkillHarnessKey, } from "./types.js";
 export { consoleLogger } from "./types.js";
+export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
 export { github, linear, slack, sentry, datadog, notification, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 export type { SkillValidationResult } from "./skills/index.js";
-export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema } from "./schema.js";
+export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
 export type { WorkflowError } from "./schema.js";
 export { workflowToFlow, flowToWorkflow, applyExecutionEvent, exportAsTypescript, getSkillCatalog } from "./studio.js";
 export type { FlowNode, SkillNodeData, FlowEdge } from "./studio.js";

package/dist/browser.js

@@ -14,9 +14,14 @@
  *   - Testing helpers — `MockClaude`, `createFileSkill` use `node:fs`.
  */
 export { consoleLogger } from "./types.js";
+// Runtime enum constants + skill-id helpers. Pure data / regex / pure
+// function from types.ts, which is already proven browser-safe (schema.ts
+// imports it). A Studio dropdown rendering evaluator kinds, or validating a
+// skill id, needs these without hardcoding the members.
+export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, MCP_TRANSPORTS, SKILL_CATEGORIES, SKILL_HARNESSES, SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, } from "./types.js";
 // Skills (browser-safe — no filesystem access, no `process.env` reads)
 export { github, linear, slack, sentry, datadog, notification, builtinSkills, createSkillMap, allSkills, isSkillConfigured, configuredBuiltinSkills, validateWorkflowSkills, } from "./skills/index.js";
 // Schema & validation
-export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema } from "./schema.js";
+export { workflowZ, nodeZ, edgeZ, skillZ, parseWorkflow, validateWorkflow, workflowJsonSchema, skillJsonSchema, } from "./schema.js";
 // Studio adapter
 export { workflowToFlow, flowToWorkflow, applyExecutionEvent, exportAsTypescript, getSkillCatalog } from "./studio.js";

package/dist/claude.d.ts

@@ -9,6 +9,43 @@
  * is to use headless Claude Code — never the raw Anthropic API.
  */
 import type { Claude, Tool, ToolContext, NodeResult, JSONSchema, Logger, McpServerConfig } from "./types.js";
+/** How sweny resolves which credentials reach the Claude Code subprocess. */
+export type SwenyAuthMode = "auto" | "api-key" | "oauth";
+export interface ResolveAuthEnvOpts {
+    /** Explicit override; when absent, read from `env.SWENY_AUTH`. Test seam. */
+    mode?: SwenyAuthMode;
+    /** Logger for the debug line + invalid-value warning. */
+    logger?: Pick<Logger, "debug" | "warn">;
+}
+/**
+ * Decide which auth credentials survive into the Claude Code subprocess env.
+ *
+ * sweny does not select the winning credential (the spawned agent and any
+ * on-disk `~/.claude/.credentials.json` do that). This function only controls
+ * what is *present* in the env we hand the agent.
+ *
+ * Modes (`SWENY_AUTH`, default `auto`):
+ *  - `auto`    — today's protective behavior: when an OAuth token is present,
+ *                strip `ANTHROPIC_API_KEY` so a stray `.env` key cannot
+ *                silently bill a metered API account. `ANTHROPIC_AUTH_TOKEN`
+ *                (a bearer token, not a console key) is never touched.
+ *  - `api-key` — user explicitly authenticates a gateway with a key/bearer:
+ *                preserve both even when an OAuth token is also present.
+ *  - `oauth`   — user explicitly wants subscription/OAuth: strip both
+ *                `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` so a leftover
+ *                credential cannot win at the agent. Fails closed.
+ *
+ * Base-URL presence is deliberately NOT a signal here: pass-through proxies
+ * (corporate egress, observability) set `ANTHROPIC_BASE_URL` while still
+ * billing the real key, so inferring "use the key" from a base URL would
+ * re-introduce a surprise-billing path. Intent must be explicit.
+ *
+ * An unrecognized `SWENY_AUTH` value falls back to `auto` with a warning
+ * (never throws — an env typo must not crash a CI run).
+ *
+ * Pure: returns a copy, never mutates the input.
+ */
+export declare function resolveAuthEnv(env: Record<string, string>, opts?: ResolveAuthEnvOpts): Record<string, string>;
 export interface ClaudeClientOptions {
     /** Model override */
     model?: string;
@@ -23,6 +60,20 @@ export interface ClaudeClientOptions {
     /** External MCP servers (GitHub, Linear, Sentry, etc.) — merged with core skill tools */
     mcpServers?: Record<string, McpServerConfig>;
 }
+/**
+ * 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 ClaudeClient implements Claude {
     private model;
     private maxTurns;
@@ -32,9 +83,8 @@ export declare class ClaudeClient implements Claude {
     private mcpServers;
     constructor(opts?: ClaudeClientOptions);
     /**
-     * Build env for the Claude Code subprocess.
-     * OAuth token takes priority over API key to prevent .env files from
-     * overriding the user's subscription-based auth.
+     * Build env for the Claude Code subprocess. Snapshots process.env (dropping
+     * nullish values) and applies auth precedence via {@link resolveAuthEnv}.
      */
     private buildEnv;
     run(opts: {
@@ -45,6 +95,11 @@ export declare class ClaudeClient implements Claude {
         onProgress?: (message: string) => void;
         maxTurns?: number;
         disallowedTools?: string[];
+        model?: string;
+        /** Abort the query after this many ms. Default: no timeout (back-compat). */
+        timeoutMs?: number;
+        /** Caller-supplied abort signal. Aborting it interrupts the query. */
+        signal?: AbortSignal;
     }): Promise<NodeResult>;
     evaluate(opts: {
         question: string;
@@ -53,11 +108,19 @@ export declare class ClaudeClient implements Claude {
             id: string;
             description: string;
         }[];
+        /** Abort the query after this many ms. Default: no timeout (back-compat). */
+        timeoutMs?: number;
+        /** Caller-supplied abort signal. Aborting it interrupts the query. */
+        signal?: AbortSignal;
     }): Promise<string>;
     ask(opts: {
         instruction: string;
         context: Record<string, unknown>;
         model?: string;
+        /** Abort the query after this many ms. Default: no timeout (back-compat). */
+        timeoutMs?: number;
+        /** Caller-supplied abort signal. Aborting it interrupts the query. */
+        signal?: AbortSignal;
     }): Promise<string>;
 }
 /**

package/dist/claude.js

@@ -12,6 +12,131 @@ import { query, createSdkMcpServer, tool as sdkTool } from "@anthropic-ai/claude
 import { z } from "zod";
 import { consoleLogger } from "./types.js";
 const SYSTEM_PROMPT = `You are a step in an automated workflow. Execute the instruction precisely using the tools available to you. Be thorough but concise. When you're done, summarize your findings and results.`;
+/**
+ * Decide which auth credentials survive into the Claude Code subprocess env.
+ *
+ * sweny does not select the winning credential (the spawned agent and any
+ * on-disk `~/.claude/.credentials.json` do that). This function only controls
+ * what is *present* in the env we hand the agent.
+ *
+ * Modes (`SWENY_AUTH`, default `auto`):
+ *  - `auto`    — today's protective behavior: when an OAuth token is present,
+ *                strip `ANTHROPIC_API_KEY` so a stray `.env` key cannot
+ *                silently bill a metered API account. `ANTHROPIC_AUTH_TOKEN`
+ *                (a bearer token, not a console key) is never touched.
+ *  - `api-key` — user explicitly authenticates a gateway with a key/bearer:
+ *                preserve both even when an OAuth token is also present.
+ *  - `oauth`   — user explicitly wants subscription/OAuth: strip both
+ *                `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` so a leftover
+ *                credential cannot win at the agent. Fails closed.
+ *
+ * Base-URL presence is deliberately NOT a signal here: pass-through proxies
+ * (corporate egress, observability) set `ANTHROPIC_BASE_URL` while still
+ * billing the real key, so inferring "use the key" from a base URL would
+ * re-introduce a surprise-billing path. Intent must be explicit.
+ *
+ * An unrecognized `SWENY_AUTH` value falls back to `auto` with a warning
+ * (never throws — an env typo must not crash a CI run).
+ *
+ * Pure: returns a copy, never mutates the input.
+ */
+export function resolveAuthEnv(env, opts = {}) {
+    const out = { ...env };
+    const raw = opts.mode ?? env.SWENY_AUTH;
+    let mode = "auto";
+    if (raw === "auto" || raw === "api-key" || raw === "oauth") {
+        mode = raw;
+    }
+    else if (raw) {
+        // truthy but unrecognized — empty string falls through silently to auto
+        opts.logger?.warn?.(`SWENY_AUTH="${raw}" is not one of auto|api-key|oauth; falling back to auto`);
+    }
+    // Truthy checks throughout: action.yml sets these to "" when an input is
+    // omitted, and empty string must read as unset.
+    const hasOauth = !!out.CLAUDE_CODE_OAUTH_TOKEN;
+    if (mode === "oauth") {
+        delete out.ANTHROPIC_API_KEY;
+        delete out.ANTHROPIC_AUTH_TOKEN;
+    }
+    else if (mode === "api-key") {
+        // preserve key + bearer; do not strip even if an OAuth token is present
+    }
+    else {
+        // auto — byte-for-byte the historical behavior
+        if (hasOauth) {
+            delete out.ANTHROPIC_API_KEY;
+        }
+    }
+    // Mode only, never credential values.
+    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.
+ * Swallows errors: the stream may already be done, and interrupt is only
+ * supported in streaming-input mode.
+ */
+async function interruptStream(stream) {
+    if (!stream || typeof stream.interrupt !== "function")
+        return;
+    try {
+        await stream.interrupt();
+    }
+    catch {
+        /* already finished or not interruptible — nothing to clean up */
+    }
+}
 export class ClaudeClient {
     model;
     maxTurns;
@@ -28,19 +153,16 @@ export class ClaudeClient {
         this.mcpServers = opts.mcpServers ?? {};
     }
     /**
-     * Build env for the Claude Code subprocess.
-     * OAuth token takes priority over API key to prevent .env files from
-     * overriding the user's subscription-based auth.
+     * Build env for the Claude Code subprocess. Snapshots process.env (dropping
+     * nullish values) and applies auth precedence via {@link resolveAuthEnv}.
      */
     buildEnv() {
         const env = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] != null));
-        if (env.CLAUDE_CODE_OAUTH_TOKEN) {
-            delete env.ANTHROPIC_API_KEY;
-        }
-        return env;
+        return resolveAuthEnv(env, { logger: this.logger });
     }
     async run(opts) {
-        const { instruction, context, tools, outputSchema, onProgress, maxTurns, disallowedTools } = opts;
+        const { instruction, context, tools, outputSchema, onProgress, maxTurns, disallowedTools, model, timeoutMs, signal, } = opts;
+        const effectiveModel = model ?? this.model;
         // Tool-call accounting (Fix #1).
         //
         // Stream-driven recording, correlated by tool_use_id:
@@ -80,11 +202,16 @@ export class ClaudeClient {
             .join("\n\n");
         const env = this.buildEnv();
         let response = "";
+        // Timeout / abort wiring (back-compat: only armed when requested).
+        // A single AbortController drives both an optional caller signal and an
+        // optional timeout timer. The SDK aborts the subprocess when this fires.
+        const abort = makeAbort(timeoutMs, signal);
+        let stream;
         try {
             const allMcpServers = { ...this.mcpServers };
             if (sdkTools.length > 0)
                 allMcpServers["sweny-core"] = mcpServer;
-            const stream = query({
+            stream = query({
                 prompt,
                 options: {
                     maxTurns: maxTurns ?? this.maxTurns,
@@ -94,7 +221,8 @@ export class ClaudeClient {
                     permissionMode: "bypassPermissions",
                     allowDangerouslySkipPermissions: true,
                     stderr: (data) => this.logger.debug(`[claude-code] ${data}`),
-                    ...(this.model ? { model: this.model } : {}),
+                    ...(abort ? { abortController: abort.controller } : {}),
+                    ...(effectiveModel ? { model: effectiveModel } : {}),
                     ...(Object.keys(allMcpServers).length > 0 ? { mcpServers: allMcpServers } : {}),
                     ...(disallowedTools && disallowedTools.length > 0 ? { disallowedTools } : {}),
                 },
@@ -200,6 +328,11 @@ export class ClaudeClient {
             }
         }
         catch (err) {
+            if (abort?.reason() === "timeout") {
+                const msg = `Claude query timed out after ${timeoutMs}ms`;
+                this.logger.error(msg);
+                return { status: "failed", data: { error: msg }, toolCalls };
+            }
             this.logger.error(`Claude Code query failed: ${err.message}`);
             return {
                 status: "failed",
@@ -207,19 +340,29 @@ export class ClaudeClient {
                 toolCalls,
             };
         }
+        finally {
+            // Interrupt the subprocess on any exit (early return, throw, or normal
+            // completion) so a wedged agent does not leak, and clear the timer so
+            // it cannot fire after we are done.
+            abort?.clear();
+            await interruptStream(stream);
+        }
         return {
             status: "success",
-            data: { summary: response, ...tryParseJSON(response) },
+            data: { summary: response, ...tryParseJSON(response, outputSchema, this.logger) },
             toolCalls,
         };
     }
     async evaluate(opts) {
-        const { question, context, choices } = opts;
+        const { question, context, choices, timeoutMs, signal } = opts;
         const prompt = buildEvaluatePrompt(question, context, choices);
         const env = this.buildEnv();
         let response = "";
+        const abort = makeAbort(timeoutMs, signal);
+        let sdkFailed = false;
+        let stream;
         try {
-            const stream = query({
+            stream = query({
                 prompt,
                 options: {
                     maxTurns: 1,
@@ -228,6 +371,7 @@ export class ClaudeClient {
                     permissionMode: "bypassPermissions",
                     allowDangerouslySkipPermissions: true,
                     stderr: (data) => this.logger.debug(`[claude-code] ${data}`),
+                    ...(abort ? { abortController: abort.controller } : {}),
                     ...(this.model ? { model: this.model } : {}),
                 },
             });
@@ -237,13 +381,35 @@ export class ClaudeClient {
                     if (resultMsg.subtype === "success" && "result" in resultMsg) {
                         response = resultMsg.result;
                     }
+                    else {
+                        // Distinguish an SDK-level failure from a genuinely ambiguous
+                        // model answer. Without this, both fall through to validIds[0]
+                        // and log the same "Could not parse route choice" warning, so an
+                        // operator cannot tell them apart. Short-circuit below so the
+                        // ambiguous-answer warning never fires on top of this one.
+                        sdkFailed = true;
+                        this.logger.warn(`claude.evaluate: SDK returned non-success subtype "${resultMsg.subtype}" — falling back to first choice.`);
+                    }
                 }
             }
         }
         catch (err) {
-            this.logger.warn(`Evaluate query failed: ${err.message}. Falling back to first choice.`);
+            if (abort?.reason() === "timeout") {
+                this.logger.warn(`Evaluate query timed out after ${timeoutMs}ms. Falling back to first choice.`);
+            }
+            else {
+                this.logger.warn(`Evaluate query failed: ${err.message}. Falling back to first choice.`);
+            }
             return choices[0].id;
         }
+        finally {
+            abort?.clear();
+            await interruptStream(stream);
+        }
+        // An SDK-level failure already logged a distinct message; do not also emit
+        // the ambiguous-answer warning, which would misattribute the cause.
+        if (sdkFailed)
+            return choices[0].id;
         const text = response.trim().replace(/^["']|["']$/g, "");
         const validIds = choices.map((c) => c.id);
         // Exact match
@@ -258,7 +424,7 @@ export class ClaudeClient {
         return validIds[0];
     }
     async ask(opts) {
-        const { instruction, context, model } = opts;
+        const { instruction, context, model, timeoutMs, signal } = opts;
         const prompt = [
             instruction,
             Object.keys(context).length > 0 ? `\nContext:\n\`\`\`json\n${JSON.stringify(context, null, 2)}\n\`\`\`` : "",
@@ -268,8 +434,10 @@ export class ClaudeClient {
         const env = this.buildEnv();
         let response = "";
         const effectiveModel = model ?? this.model;
+        const abort = makeAbort(timeoutMs, signal);
+        let stream;
         try {
-            const stream = query({
+            stream = query({
                 prompt,
                 options: {
                     maxTurns: 1,
@@ -278,6 +446,7 @@ export class ClaudeClient {
                     permissionMode: "bypassPermissions",
                     allowDangerouslySkipPermissions: true,
                     stderr: (data) => this.logger.debug(`[claude-code] ${data}`),
+                    ...(abort ? { abortController: abort.controller } : {}),
                     ...(effectiveModel ? { model: effectiveModel } : {}),
                 },
             });
@@ -294,9 +463,18 @@ export class ClaudeClient {
             }
         }
         catch (err) {
-            this.logger.warn(`Ask query failed: ${err.message}`);
+            if (abort?.reason() === "timeout") {
+                this.logger.warn(`Ask query timed out after ${timeoutMs}ms — returning empty string`);
+            }
+            else {
+                this.logger.warn(`Ask query failed: ${err.message}`);
+            }
             return "";
         }
+        finally {
+            abort?.clear();
+            await interruptStream(stream);
+        }
         return response.trim();
     }
 }
@@ -372,18 +550,37 @@ export function buildEvaluatePrompt(question, context, choices) {
         `1. Read each choice's condition literally and match against the structured fields in the context (e.g. status, counts, enum values, boolean flags).`,
         `2. Ignore prose narrative fields ("summary", free-form rationale, conversational commentary). They are not the contract.`,
         `3. When a field's value contradicts what a prose field claims, trust the field's value.`,
+        `4. A field whose value is explicitly null means the source node DECLARED that field but did NOT emit a value. Treat null as "unknown" and do NOT match it against any specific value (do not match "is 0", "is N", "is true", "is false", or "is undefined" against a null field). Prefer a default/fallback edge when the field needed for a decision is null.`,
         `\nRespond with ONLY the choice ID, nothing else.`,
     ].join("\n");
 }
 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];
-    // Only objects and arrays are unambiguous to parse. Strings, numbers,
-    // booleans, and null would all corrupt or discard information.
     if (first !== "{" && first !== "[")
         return content;
     try {
@@ -393,6 +590,34 @@ export function parseToolResultContent(content) {
         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
@@ -493,24 +718,38 @@ function stripMcpPrefix(name) {
  * Extract a JSON object from Claude's text response.
  *
  * Strategy (in order):
- * 1. ```json code block``` — most reliable, Claude often wraps JSON this way
+ * 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) {
+function tryParseJSON(text, outputSchema, logger) {
     if (!text)
         return {};
-    // 1. Code block
-    const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
-    if (codeBlockMatch) {
+    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(codeBlockMatch[1].trim());
+            const parsed = JSON.parse(fences[i][1].trim());
             if (typeof parsed === "object" && parsed !== null)
-                return parsed;
+                return finalize(parsed);
         }
         catch {
-            /* try next strategy */
+            /* try the next-earlier fence, then fall through to brace scan */
         }
     }
     // 2. Last brace-delimited block (scan backwards for matching braces)
@@ -526,7 +765,7 @@ function tryParseJSON(text) {
                 try {
                     const parsed = JSON.parse(text.slice(i, lastBrace + 1));
                     if (typeof parsed === "object" && parsed !== null)
-                        return parsed;
+                        return finalize(parsed);
                 }
                 catch {
                     /* try next strategy */
@@ -539,10 +778,77 @@ function tryParseJSON(text) {
     try {
         const parsed = JSON.parse(text.trim());
         if (typeof parsed === "object" && parsed !== null)
-            return parsed;
+            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
+    }
+}