@mcoda/codali 0.1.108 → 0.1.110

package/dist/gateway/LocalGatewayTaskRunner.js

@@ -0,0 +1,361 @@
+import { truncateToolResult } from "../tools/TruncateResult.js";
+import { CODALI_GATEWAY_SECURITY_PROMPT_HARDENING } from "./GatewaySecurityPolicy.js";
+/**
+ * Bounded worker-task runner.
+ *
+ * ## Why this exists
+ *
+ * Codali previously executed every gateway worker task by handing it to the
+ * full `CodaliRuntime` agent loop (see `createGatewayTaskRunner` in
+ * `packages/mswarm/src/codali-executor.ts`). That nested one open-ended loop
+ * inside another: the gateway decided how many *rounds* to run, while the
+ * runtime independently decided how many *steps* to take inside each task.
+ * Neither could bound the other, so a single request could fan out
+ * unpredictably and a runaway task was near-impossible to attribute.
+ *
+ * This runner removes the inner loop. Exactly one component - the gateway state
+ * machine - owns iteration. A task here is a single bounded pass:
+ *
+ *   1. ask the model what it needs (one model call)
+ *   2. execute the tool calls it asked for, in parallel where independent
+ *   3. ask the model to turn the results into the task output (one model call)
+ *
+ * There is no step 4 and no "decide whether to keep going". If the evidence is
+ * insufficient, that is the verifier's judgement to make, and the gateway will
+ * schedule another round against `maxIterations`. A worker never extends its
+ * own budget.
+ *
+ * The upper bound on work per task is therefore fixed and knowable:
+ * 2 model calls and `min(remainingToolCalls, MAX_TOOL_CALLS_PER_TASK)` tool
+ * calls.
+ */
+/** Hard ceiling on tool calls in a single task, independent of run budget. */
+export const MAX_TOOL_CALLS_PER_TASK = 8;
+/** Model calls per task: one to select tools, one to summarize results. */
+export const MAX_MODEL_CALLS_PER_TASK = 2;
+const DEFAULT_TASK_TIMEOUT_MS = 60000;
+const DEFAULT_MAX_TOKENS = 1200;
+const DEFAULT_TEMPERATURE = 0;
+/**
+ * Tool output beyond this is truncated before it reaches the model.
+ *
+ * Connector list endpoints are the pressure here: a GitHub `list_commits` for a
+ * fortnight of activity runs well past the old 8k cap, and the model then
+ * summarized only the commits that survived — accurately, but incompletely.
+ */
+const MAX_TOOL_OUTPUT_CHARS = 24000;
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const truncate = (value, limit = MAX_TOOL_OUTPUT_CHARS) => value.length > limit
+    ? `${value.slice(0, limit)}\n\n[TRUNCATED: ${value.length - limit} more characters were cut. This result is INCOMPLETE — say so explicitly in your summary and do not present it as the full set.]`
+    : value;
+const positiveInteger = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : fallback;
+const nonNegativeInteger = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : fallback;
+const errorMessageFor = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Tool definitions offered to the worker model, narrowed to what the planner
+ * allowed for this task. A tool absent from `allowedTools` is not merely
+ * discouraged - the model never sees it.
+ */
+const toolDefinitionsFor = (registry, allowedTools) => registry.catalog(allowedTools).map((descriptor) => ({
+    name: descriptor.name,
+    description: descriptor.description,
+    inputSchema: descriptor.inputSchema,
+}));
+const buildTaskMessages = (input, hasTools) => {
+    const system = [
+        "You are a Codali gateway worker.",
+        "Gather evidence for one bounded sub-task. Do not answer the user's overall question.",
+        hasTools
+            ? "Call the tools you need in a single batch. You get exactly one opportunity to call tools, so request everything you need at once."
+            : "No tools are available. Answer from the task description alone or state what is missing.",
+        "Report only what the tool results actually support. Never invent file paths, identifiers, figures, or quotations.",
+        "If the results are insufficient, say so plainly instead of guessing; another round may be scheduled.",
+        CODALI_GATEWAY_SECURITY_PROMPT_HARDENING.toolOutputBoundary,
+        CODALI_GATEWAY_SECURITY_PROMPT_HARDENING.policyImmutability,
+        CODALI_GATEWAY_SECURITY_PROMPT_HARDENING.tenantScope,
+    ].join("\n");
+    return [
+        { role: "system", content: system },
+        { role: "user", content: input.prompt },
+    ];
+};
+export class LocalGatewayTaskRunner {
+    constructor(options) {
+        this.options = options;
+    }
+    async run(input) {
+        const startedMs = Date.now();
+        const taskId = input.task.id;
+        const deadlineMs = startedMs + positiveInteger(input.timeoutMs, DEFAULT_TASK_TIMEOUT_MS);
+        const allowedTools = input.allowedTools ?? [];
+        const toolBudget = Math.min(nonNegativeInteger(input.remainingToolCalls, 0), MAX_TOOL_CALLS_PER_TASK);
+        const modelBudget = Math.min(nonNegativeInteger(input.remainingModelCalls, MAX_MODEL_CALLS_PER_TASK), MAX_MODEL_CALLS_PER_TASK);
+        const toolCalls = [];
+        const modelCalls = [];
+        this.options.onEvent?.({
+            type: "task_start",
+            taskId,
+            workerRole: input.task.workerRole,
+            allowedTools: [...allowedTools],
+        });
+        const finish = (result) => {
+            this.options.onEvent?.({
+                type: "task_end",
+                taskId,
+                status: result.status,
+                toolCallCount: toolCalls.length,
+                modelCallCount: modelCalls.length,
+                durationMs: Date.now() - startedMs,
+            });
+            return { ...result, toolCalls, modelCalls };
+        };
+        if (modelBudget <= 0) {
+            return finish({
+                status: "failed",
+                errorCode: "GATEWAY_MODEL_BUDGET_EXCEEDED",
+                errorMessage: "No model calls remain for this worker task.",
+            });
+        }
+        const offerTools = toolBudget > 0 && allowedTools.length > 0;
+        const toolDefinitions = offerTools
+            ? toolDefinitionsFor(this.options.registry, allowedTools)
+            : [];
+        const messages = buildTaskMessages(input, toolDefinitions.length > 0);
+        // ---- Pass 1: ask the model what it needs -----------------------------
+        let selection;
+        const selectionStartedMs = Date.now();
+        try {
+            selection = await this.options.provider.generate({
+                messages,
+                tools: toolDefinitions.length > 0 ? toolDefinitions : undefined,
+                toolChoice: toolDefinitions.length > 0 ? "auto" : "none",
+                maxTokens: positiveInteger(this.options.maxTokens, DEFAULT_MAX_TOKENS),
+                temperature: this.options.temperature ?? DEFAULT_TEMPERATURE,
+            });
+        }
+        catch (error) {
+            modelCalls.push({
+                role: "worker",
+                status: "failed",
+                latencyMs: Date.now() - selectionStartedMs,
+                provider: this.options.provider.name,
+                errorCode: "GATEWAY_WORKER_MODEL_FAILED",
+                errorMessage: errorMessageFor(error),
+            });
+            return finish({
+                status: "failed",
+                errorCode: "GATEWAY_WORKER_MODEL_FAILED",
+                errorMessage: errorMessageFor(error),
+            });
+        }
+        modelCalls.push({
+            role: "worker",
+            status: "success",
+            latencyMs: Date.now() - selectionStartedMs,
+            provider: this.options.provider.name,
+            output: selection.message.content,
+            metadata: {
+                pass: "tool_selection",
+                requestedToolCalls: selection.toolCalls?.length ?? 0,
+                usage: selection.usage,
+            },
+        });
+        const requested = (selection.toolCalls ?? []).slice(0, toolBudget);
+        const droppedForBudget = (selection.toolCalls ?? []).length - requested.length;
+        // No tools requested: the first answer is the task output. One model call,
+        // and we return rather than looping to look for more work.
+        if (requested.length === 0) {
+            const output = selection.message.content.trim();
+            return finish({
+                status: "succeeded",
+                output,
+                metadata: {
+                    pass: "direct",
+                    modelCallCount: modelCalls.length,
+                    toolCallCount: 0,
+                    ...(droppedForBudget > 0 ? { droppedToolCalls: droppedForBudget } : {}),
+                },
+            });
+        }
+        // ---- Execute the batch ------------------------------------------------
+        // Independent read-only calls run in parallel. Ordering between them is not
+        // meaningful; each is validated against the registry schema before running.
+        const executions = await Promise.all(requested.map(async (call) => {
+            if (Date.now() > deadlineMs) {
+                return {
+                    call,
+                    record: {
+                        tool: call.name,
+                        status: "failed",
+                        latencyMs: 0,
+                        args: call.args,
+                        errorCode: "tool_timeout",
+                        errorMessage: "Task deadline elapsed before the tool was invoked.",
+                    },
+                    output: "Tool skipped: task deadline elapsed.",
+                };
+            }
+            this.options.onEvent?.({ type: "tool_call", taskId, tool: call.name, args: call.args });
+            const toolStartedMs = Date.now();
+            if (!allowedTools.includes(call.name)) {
+                // The model named a tool outside the planner's allowance. Refuse it
+                // and tell the model, rather than silently widening the policy.
+                const latencyMs = Date.now() - toolStartedMs;
+                this.options.onEvent?.({
+                    type: "tool_result",
+                    taskId,
+                    tool: call.name,
+                    ok: false,
+                    latencyMs,
+                    errorCode: "tool_permission_denied",
+                });
+                return {
+                    call,
+                    record: {
+                        tool: call.name,
+                        status: "failed",
+                        latencyMs,
+                        args: call.args,
+                        errorCode: "tool_permission_denied",
+                        errorMessage: `Tool ${call.name} is not allowed for this task.`,
+                    },
+                    output: `Tool ${call.name} is not allowed for this task.`,
+                };
+            }
+            const result = await this.options.registry.execute(call.name, call.args, this.options.toolContext);
+            const latencyMs = Date.now() - toolStartedMs;
+            this.options.onEvent?.({
+                type: "tool_result",
+                taskId,
+                tool: call.name,
+                ok: result.ok,
+                latencyMs,
+                errorCode: result.error?.code,
+            });
+            return {
+                call,
+                record: {
+                    tool: call.name,
+                    status: result.ok ? "success" : "failed",
+                    latencyMs,
+                    args: call.args,
+                    result: result.ok ? (result.data ?? result.output) : undefined,
+                    errorCode: result.error?.code,
+                    errorMessage: result.error?.message,
+                },
+                // Structural where the tool returned data: a 258 KB web-research
+                // payload cut at a character count is unparseable, and the model
+                // then reports it found nothing. Applied here so it covers docdex
+                // and built-in tools too, not just the connectors.
+                output: result.ok
+                    ? (result.data !== undefined
+                        ? truncateToolResult(result.data, result.output, MAX_TOOL_OUTPUT_CHARS).text
+                        : truncate(result.output))
+                    : `Tool failed (${result.error?.code ?? "unknown"}): ${result.error?.message ?? ""}`,
+            };
+        }));
+        for (const execution of executions) {
+            toolCalls.push(execution.record);
+        }
+        const succeededCount = executions.filter((execution) => execution.record.status === "success").length;
+        // Every tool failed: report the failure rather than asking the model to
+        // narrate an empty result set, which is where fabrication starts.
+        if (succeededCount === 0) {
+            const first = executions[0]?.record;
+            return finish({
+                status: "failed",
+                errorCode: first?.errorCode ?? "GATEWAY_WORKER_TOOLS_FAILED",
+                errorMessage: first?.errorMessage ?? "All tool calls for this worker task failed.",
+                metadata: { pass: "tools_failed", toolCallCount: toolCalls.length },
+            });
+        }
+        if (modelCalls.length >= modelBudget) {
+            // No budget left to summarize. Return the raw tool outputs as the task
+            // output; the finalizer, not the user, is what sees this.
+            return finish({
+                status: "succeeded",
+                output: executions.map((execution) => `${execution.call.name}: ${execution.output}`).join("\n\n"),
+                metadata: {
+                    pass: "unsummarized",
+                    reason: "model_budget_exhausted",
+                    toolCallCount: toolCalls.length,
+                },
+            });
+        }
+        // ---- Pass 2: turn the results into the task output --------------------
+        const resultMessages = [
+            ...messages,
+            {
+                role: "assistant",
+                content: selection.message.content ||
+                    `Requested tools: ${requested.map((call) => call.name).join(", ")}`,
+            },
+            {
+                role: "user",
+                content: [
+                    "Tool results:",
+                    ...executions.map((execution) => `--- ${execution.call.name} ---\n${execution.output}`),
+                    "",
+                    "Summarize what these results establish for this sub-task.",
+                    "If any result is marked TRUNCATED, state that the data is incomplete and roughly what is missing. Never present a truncated list as complete.",
+                    "Attribute each statement to the tool that produced it.",
+                    "State explicitly what remains unknown. Do not speculate beyond the results.",
+                ].join("\n"),
+            },
+        ];
+        const summaryStartedMs = Date.now();
+        try {
+            const summary = await this.options.provider.generate({
+                messages: resultMessages,
+                toolChoice: "none",
+                maxTokens: positiveInteger(this.options.maxTokens, DEFAULT_MAX_TOKENS),
+                temperature: this.options.temperature ?? DEFAULT_TEMPERATURE,
+            });
+            modelCalls.push({
+                role: "worker",
+                status: "success",
+                latencyMs: Date.now() - summaryStartedMs,
+                provider: this.options.provider.name,
+                output: summary.message.content,
+                metadata: { pass: "summary", usage: summary.usage },
+            });
+            return finish({
+                status: "succeeded",
+                output: summary.message.content.trim(),
+                metadata: {
+                    pass: "tools_summarized",
+                    toolCallCount: toolCalls.length,
+                    succeededToolCalls: succeededCount,
+                    ...(droppedForBudget > 0 ? { droppedToolCalls: droppedForBudget } : {}),
+                },
+            });
+        }
+        catch (error) {
+            modelCalls.push({
+                role: "worker",
+                status: "failed",
+                latencyMs: Date.now() - summaryStartedMs,
+                provider: this.options.provider.name,
+                errorCode: "GATEWAY_WORKER_SUMMARY_FAILED",
+                errorMessage: errorMessageFor(error),
+            });
+            // Summarization failed but the evidence is real. Return it unsummarized
+            // rather than discarding a successful tool batch.
+            return finish({
+                status: "succeeded",
+                output: executions.map((execution) => `${execution.call.name}: ${execution.output}`).join("\n\n"),
+                metadata: {
+                    pass: "unsummarized",
+                    reason: "summary_failed",
+                    toolCallCount: toolCalls.length,
+                },
+            });
+        }
+    }
+}
+export const createLocalGatewayTaskRunner = (options) => new LocalGatewayTaskRunner(options);
+export const isRecordValue = isRecord;

package/dist/gateway/RelevanceJudge.d.ts

@@ -0,0 +1,25 @@
+import type { Provider } from "../providers/ProviderTypes.js";
+import type { RelevanceJudge } from "../tools/docdex/DocdexTools.js";
+/**
+ * Reduces a result payload to a short list of titles. The judge needs to know
+ * *what* was found, not the contents — sending snippets would cost more than
+ * the web call being avoided.
+ */
+export declare const summarizeResultTitles: (results: unknown) => string[];
+export interface RelevanceJudgeOptions {
+    provider: Provider;
+    maxTokens?: number;
+}
+/**
+ * Whether any result title shares a distinctive word with the question.
+ *
+ * A cheap pre-check that exists because the judge was answering obvious cases
+ * wrongly and expensively: asked whether `LocalGatewayTaskRunner.ts` could
+ * answer "what does LocalGatewayTaskRunner do", a small model said no, which
+ * forced a 45-second web search for a local class. Lexical overlap settles
+ * that case without a model call, leaving the judge for genuinely ambiguous
+ * results — which is where it earns its keep.
+ */
+export declare const titlesShareTermsWithQuery: (query: string, titles: readonly string[]) => boolean;
+export declare const createRelevanceJudge: (options: RelevanceJudgeOptions) => RelevanceJudge;
+//# sourceMappingURL=RelevanceJudge.d.ts.map

package/dist/gateway/RelevanceJudge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RelevanceJudge.d.ts","sourceRoot":"","sources":["../../src/gateway/RelevanceJudge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAyBrE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,OAAO,KAAG,MAAM,EAqB9D,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAeD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,GACpC,OAAO,MAAM,EACb,QAAQ,SAAS,MAAM,EAAE,KACxB,OAWF,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,qBAAqB,KAC7B,cAyCF,CAAC"}

package/dist/gateway/RelevanceJudge.js

@@ -0,0 +1,124 @@
+/**
+ * Decides whether local search results actually answer the question.
+ *
+ * The alternative approaches are both worse:
+ *
+ * - **Score thresholds** do not discriminate. Measured against this repository,
+ *   "GDP of France 2025" scores 29.07 while "gateway planner class" scores
+ *   14.35 — the irrelevant query scores higher, because a test fixture contains
+ *   the phrase. Any threshold would be arbitrary and frequently wrong.
+ * - **Keyword rules** ("if the query mentions GDP or news, go to the web") are
+ *   precisely the hardcoding this project rules out: they work for the examples
+ *   someone thought of and fail on the next question.
+ *
+ * A model reading the titles is generic and costs one short call. It is asked
+ * for a single token so a small local model can answer it quickly.
+ */
+const MAX_TITLES = 8;
+const MAX_TITLE_CHARS = 90;
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+/**
+ * Reduces a result payload to a short list of titles. The judge needs to know
+ * *what* was found, not the contents — sending snippets would cost more than
+ * the web call being avoided.
+ */
+export const summarizeResultTitles = (results) => {
+    if (!isRecord(results))
+        return [];
+    const hits = ["hits", "results", "matches"]
+        .map((key) => results[key])
+        .find((value) => Array.isArray(value) && value.length > 0);
+    if (!hits)
+        return [];
+    const titles = [];
+    for (const hit of hits.slice(0, MAX_TITLES)) {
+        if (!isRecord(hit))
+            continue;
+        const title = (typeof hit.rel_path === "string" && hit.rel_path) ||
+            (typeof hit.relPath === "string" && hit.relPath) ||
+            (typeof hit.path === "string" && hit.path) ||
+            (typeof hit.title === "string" && hit.title) ||
+            (typeof hit.url === "string" && hit.url) ||
+            (typeof hit.doc_id === "string" && hit.doc_id) ||
+            "";
+        if (title)
+            titles.push(String(title).slice(0, MAX_TITLE_CHARS));
+    }
+    return titles;
+};
+/**
+ * Words too common to signal relevance on their own.
+ *
+ * Not a keyword rule about any subject — just the connectives that appear in
+ * every question and would otherwise match any file path.
+ */
+const STOPWORDS = new Set([
+    "what", "which", "where", "when", "does", "did", "the", "and", "for", "with",
+    "from", "that", "this", "how", "why", "who", "are", "was", "were", "its",
+    "class", "file", "code", "show", "list", "find", "tell", "give", "about",
+    "purpose", "exists", "existence", "summary", "summarize", "explain",
+]);
+/**
+ * Whether any result title shares a distinctive word with the question.
+ *
+ * A cheap pre-check that exists because the judge was answering obvious cases
+ * wrongly and expensively: asked whether `LocalGatewayTaskRunner.ts` could
+ * answer "what does LocalGatewayTaskRunner do", a small model said no, which
+ * forced a 45-second web search for a local class. Lexical overlap settles
+ * that case without a model call, leaving the judge for genuinely ambiguous
+ * results — which is where it earns its keep.
+ */
+export const titlesShareTermsWithQuery = (query, titles) => {
+    const terms = query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((word) => word.length > 3 && !STOPWORDS.has(word));
+    if (terms.length === 0)
+        return false;
+    // Split titles the same way so `LocalGatewayTaskRunner.ts` matches
+    // `localgatewaytaskrunner` from the question.
+    const haystack = titles.join(" ").toLowerCase().replace(/[^a-z0-9]+/g, " ");
+    return terms.some((term) => haystack.includes(term));
+};
+export const createRelevanceJudge = (options) => async ({ query, results }) => {
+    const titles = summarizeResultTitles(results);
+    // Nothing to judge; the caller's presence check already decided.
+    if (titles.length === 0)
+        return true;
+    // An obvious match needs no model call, and no chance of getting it wrong.
+    if (titlesShareTermsWithQuery(query, titles))
+        return true;
+    const response = await options.provider.generate({
+        messages: [
+            {
+                role: "system",
+                content: [
+                    "You decide whether local search results are relevant to a question.",
+                    "You are shown only the titles or file paths that were found.",
+                    "Answer with exactly one word: YES if these look like they could answer the question, NO if they are about something else.",
+                    "A repository file that merely happens to mention a word from the question is NO.",
+                ].join("\n"),
+            },
+            {
+                role: "user",
+                content: [
+                    `Question: ${query}`,
+                    "",
+                    "Results found locally:",
+                    ...titles.map((title) => `- ${title}`),
+                    "",
+                    "Could these answer the question? Reply YES or NO.",
+                ].join("\n"),
+            },
+        ],
+        toolChoice: "none",
+        maxTokens: options.maxTokens ?? 5,
+        temperature: 0,
+    });
+    const verdict = response.message.content.trim().toUpperCase();
+    // Default to keeping the local result when the answer is unreadable: a
+    // needless web call is a worse failure than a slightly weak local hit.
+    if (verdict.startsWith("NO"))
+        return false;
+    return true;
+};

package/dist/gateway/ResponseSchema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Enforcement for `CodaliGatewayRequest.response.schema`.
+ *
+ * The field has been part of the request contract for a while but was never
+ * validated — only `response.format === "json"` was read, so a caller could ask
+ * for a schema and receive anything at all. That pushes parsing and correction
+ * logic into every consuming product, which is precisely the duplication Codali
+ * exists to remove.
+ *
+ * Validation reuses the same structural rules as tool-argument validation so a
+ * schema behaves identically whether it describes a tool input or a response.
+ */
+export interface ResponseSchemaViolation {
+    path: string;
+    message: string;
+}
+export interface ResponseSchemaValidation {
+    ok: boolean;
+    value?: unknown;
+    violations: ResponseSchemaViolation[];
+}
+/**
+ * Extracts a JSON value from a model response. Models routinely wrap JSON in
+ * prose or a fenced block even when told not to, and rejecting those outright
+ * would burn a repair attempt on a formatting quirk rather than a real
+ * structural failure.
+ */
+export declare const extractJsonPayload: (content: string) => unknown;
+export declare const validateResponseAgainstSchema: (content: string, schema: Record<string, unknown> | undefined) => ResponseSchemaValidation;
+/** Human-readable violation list, used to prompt one repair attempt. */
+export declare const describeViolations: (violations: ResponseSchemaViolation[]) => string;
+//# sourceMappingURL=ResponseSchema.d.ts.map

package/dist/gateway/ResponseSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResponseSchema.d.ts","sourceRoot":"","sources":["../../src/gateway/ResponseSchema.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,uBAAuB,EAAE,CAAC;CACvC;AAwED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,OAuBpD,CAAC;AAUF,eAAO,MAAM,6BAA6B,GACxC,SAAS,MAAM,EACf,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAC1C,wBAmBF,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,GAAI,YAAY,uBAAuB,EAAE,KAAG,MACY,CAAC"}

package/dist/gateway/ResponseSchema.js

@@ -0,0 +1,120 @@
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const typeOf = (value) => {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (typeof value === "number")
+        return Number.isInteger(value) ? "integer" : "number";
+    return typeof value;
+};
+const typeMatches = (value, expected) => {
+    const actual = typeOf(value);
+    if (expected === actual)
+        return true;
+    // An integer satisfies "number"; a whole float satisfies "integer".
+    if (expected === "number" && actual === "integer")
+        return true;
+    if (expected === "integer" && actual === "number")
+        return Number.isInteger(value);
+    return false;
+};
+const validateAgainst = (value, schema, path, violations) => {
+    const expectedTypes = schema.type
+        ? (Array.isArray(schema.type) ? schema.type : [schema.type])
+        : undefined;
+    if (expectedTypes && !expectedTypes.some((type) => typeMatches(value, type))) {
+        violations.push({
+            path,
+            message: `expected ${expectedTypes.join(" or ")}, received ${typeOf(value)}`,
+        });
+        return;
+    }
+    if (schema.enum && !schema.enum.some((entry) => entry === value)) {
+        violations.push({
+            path,
+            message: `value is not one of ${JSON.stringify(schema.enum)}`,
+        });
+        return;
+    }
+    if (Array.isArray(value) && schema.items) {
+        value.forEach((entry, index) => {
+            validateAgainst(entry, schema.items, `${path}[${index}]`, violations);
+        });
+        return;
+    }
+    if (isRecord(value)) {
+        for (const key of schema.required ?? []) {
+            if (!(key in value)) {
+                violations.push({ path: `${path}.${key}`, message: "required property is missing" });
+            }
+        }
+        const properties = schema.properties ?? {};
+        for (const [key, entry] of Object.entries(value)) {
+            const child = properties[key];
+            if (child) {
+                validateAgainst(entry, child, `${path}.${key}`, violations);
+            }
+            else if (schema.additionalProperties === false) {
+                violations.push({ path: `${path}.${key}`, message: "unexpected property" });
+            }
+        }
+    }
+};
+/**
+ * Extracts a JSON value from a model response. Models routinely wrap JSON in
+ * prose or a fenced block even when told not to, and rejecting those outright
+ * would burn a repair attempt on a formatting quirk rather than a real
+ * structural failure.
+ */
+export const extractJsonPayload = (content) => {
+    const trimmed = content.trim();
+    if (!trimmed)
+        return undefined;
+    const direct = tryParse(trimmed);
+    if (direct !== undefined)
+        return direct;
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fenced?.[1]) {
+        const parsed = tryParse(fenced[1].trim());
+        if (parsed !== undefined)
+            return parsed;
+    }
+    const firstBrace = trimmed.search(/[[{]/);
+    if (firstBrace >= 0) {
+        const lastBrace = Math.max(trimmed.lastIndexOf("}"), trimmed.lastIndexOf("]"));
+        if (lastBrace > firstBrace) {
+            const parsed = tryParse(trimmed.slice(firstBrace, lastBrace + 1));
+            if (parsed !== undefined)
+                return parsed;
+        }
+    }
+    return undefined;
+};
+const tryParse = (value) => {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+};
+export const validateResponseAgainstSchema = (content, schema) => {
+    if (!schema) {
+        return { ok: true, value: content, violations: [] };
+    }
+    const payload = extractJsonPayload(content);
+    if (payload === undefined) {
+        return {
+            ok: false,
+            violations: [{ path: "$", message: "response was not parseable as JSON" }],
+        };
+    }
+    const violations = [];
+    validateAgainst(payload, schema, "$", violations);
+    return violations.length === 0
+        ? { ok: true, value: payload, violations: [] }
+        : { ok: false, value: payload, violations };
+};
+/** Human-readable violation list, used to prompt one repair attempt. */
+export const describeViolations = (violations) => violations.map((violation) => `- ${violation.path}: ${violation.message}`).join("\n");