@mcoda/codali 0.1.108 → 0.1.109

package/dist/gateway/LocalGatewayProvider.d.ts

@@ -0,0 +1,46 @@
+import type { Provider, ProviderConfig } from "../providers/ProviderTypes.js";
+import type { CodaliGatewayAgentAssignment } from "./AgentTierResolver.js";
+/**
+ * Builds a `Provider` from a resolved mcoda agent so the gateway can run
+ * in-process from the CLI, without a round trip through mswarm.
+ *
+ * mswarm keeps its own cloud path; both should end up sharing this factory so
+ * local and cloud behaviour cannot drift.
+ */
+export interface LocalProviderOptions {
+    timeoutMs?: number;
+    apiKey?: string;
+}
+/**
+ * mcoda adapter -> Codali provider. Adapters not listed fall through to the
+ * OpenAI-compatible provider, which is the correct default for local runners
+ * (llama.cpp, vLLM, LocalAI) and most hosted endpoints.
+ */
+export declare const providerNameForAdapter: (adapter: string | undefined) => string;
+export declare const createProviderForName: (name: string, config: ProviderConfig) => Provider;
+export declare const resolveMswarmApiKey: () => string | undefined;
+/**
+ * Creates a provider for an assigned agent. The raw inventory entry carries the
+ * transport details (base URL, runner kind, auth mode) that the tier resolver
+ * does not model, so it is read here.
+ */
+export declare const createProviderForAssignment: (assignment: CodaliGatewayAgentAssignment, options?: LocalProviderOptions) => Provider;
+/**
+ * Routes each gateway role to its own provider.
+ *
+ * Codali's whole premise is that a small model does the errands and a large one
+ * writes the answer. A single shared provider would silently collapse that: the
+ * planner and the synthesizer would run on the same model and the cost/quality
+ * split would be lost. So role dispatch is explicit, with a declared fallback
+ * rather than an accidental one.
+ */
+export declare class RoleRoutingProvider implements Provider {
+    private readonly providers;
+    private readonly fallback;
+    private readonly resolveRole;
+    readonly name = "codali-role-router";
+    constructor(providers: Record<string, Provider>, fallback: Provider, resolveRole?: () => string | undefined);
+    providerForRole(role: string | undefined): Provider;
+    generate(request: Parameters<Provider["generate"]>[0]): ReturnType<Provider["generate"]>;
+}
+//# sourceMappingURL=LocalGatewayProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalGatewayProvider.d.ts","sourceRoot":"","sources":["../../src/gateway/LocalGatewayProvider.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AAE3E;;;;;;GAMG;AAEH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAkCD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,GAAG,SAAS,KAAG,MAapE,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAChC,MAAM,MAAM,EACZ,QAAQ,cAAc,KACrB,QAWF,CAAC;AAYF,eAAO,MAAM,mBAAmB,QAAO,MAAM,GAAG,SA4B/C,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,GACtC,YAAY,4BAA4B,EACxC,UAAS,oBAAyB,KACjC,QAoCF,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,YAAW,QAAQ;IAIhD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAL9B,QAAQ,CAAC,IAAI,wBAAwB;gBAGlB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,EACnC,QAAQ,EAAE,QAAQ,EAClB,WAAW,GAAE,MAAM,MAAM,GAAG,SAA2B;IAG1E,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ;IAK7C,QAAQ,CACZ,OAAO,EAAE,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAC3C,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;CAGpC"}

package/dist/gateway/LocalGatewayProvider.js

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { ClaudeCliProvider } from "../providers/ClaudeCliProvider.js";
+import { CodexCliProvider } from "../providers/CodexCliProvider.js";
+import { OllamaRemoteProvider } from "../providers/OllamaRemoteProvider.js";
+import { OpenAiCompatibleProvider } from "../providers/OpenAiCompatibleProvider.js";
+/**
+ * Request timeout for a locally-hosted model.
+ *
+ * The providers default to 60s, which suits a hosted API and not a local one:
+ * qwen3.6 on the self-hosted node takes ~47s for a one-line prompt, so a full
+ * context pack aborted every time and surfaced as "the final model was
+ * unavailable" — a timeout wearing the costume of an outage.
+ */
+const LOCAL_MODEL_TIMEOUT_MS = 600000;
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const readString = (record, keys) => {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+};
+const readBoolean = (record, keys) => {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "boolean")
+            return value;
+    }
+    return undefined;
+};
+/**
+ * mcoda adapter -> Codali provider. Adapters not listed fall through to the
+ * OpenAI-compatible provider, which is the correct default for local runners
+ * (llama.cpp, vLLM, LocalAI) and most hosted endpoints.
+ */
+export const providerNameForAdapter = (adapter) => {
+    switch ((adapter ?? "").toLowerCase()) {
+        case "claude-cli":
+            return "claude-cli";
+        case "codex-cli":
+            return "codex-cli";
+        case "ollama-cli":
+        case "ollama-remote":
+        case "ollama":
+            return "ollama";
+        default:
+            return "openai-compatible";
+    }
+};
+export const createProviderForName = (name, config) => {
+    switch (name) {
+        case "claude-cli":
+            return new ClaudeCliProvider(config);
+        case "codex-cli":
+            return new CodexCliProvider(config);
+        case "ollama":
+            return new OllamaRemoteProvider(config);
+        default:
+            return new OpenAiCompatibleProvider(config);
+    }
+};
+/**
+ * The mswarm API key, used to reach self-hosted agents served through the
+ * mswarm gateway. `mcoda agent list --json` reports `auth.configured: true` but
+ * never discloses the key itself, so it is read from local trusted config.
+ *
+ * Local CLI only. A multi-tenant deployment must receive credentials from its
+ * host rather than reading the operator's files.
+ */
+let cachedMswarmKey;
+export const resolveMswarmApiKey = () => {
+    if (cachedMswarmKey !== undefined)
+        return cachedMswarmKey ?? undefined;
+    const fromEnv = process.env.MSWARM_API_KEY?.trim();
+    if (fromEnv) {
+        cachedMswarmKey = fromEnv;
+        return fromEnv;
+    }
+    const configPath = path.join(homedir(), ".docdex", "config.toml");
+    if (existsSync(configPath)) {
+        try {
+            const raw = readFileSync(configPath, "utf8");
+            // Minimal TOML read: find api_key inside [integrations.mswarm].
+            const section = raw.split(/^\[integrations\.mswarm\]\s*$/m)[1];
+            const match = section?.match(/^\s*api_key\s*=\s*"([^"]+)"/m);
+            if (match?.[1]) {
+                cachedMswarmKey = match[1];
+                return cachedMswarmKey;
+            }
+        }
+        catch {
+            // Unreadable config is not fatal; the provider will fail with a clearer
+            // authentication error than anything we could raise here.
+        }
+    }
+    cachedMswarmKey = null;
+    return undefined;
+};
+const isMswarmEndpoint = (baseUrl) => Boolean(baseUrl && /(^|\/\/)([^/]*\.)?mswarm\.org/i.test(baseUrl));
+/**
+ * Creates a provider for an assigned agent. The raw inventory entry carries the
+ * transport details (base URL, runner kind, auth mode) that the tier resolver
+ * does not model, so it is read here.
+ */
+export const createProviderForAssignment = (assignment, options = {}) => {
+    const raw = isRecord(assignment.candidate.raw) ? assignment.candidate.raw : {};
+    // mcoda nests transport details under `config`; older entries put them at the
+    // top level. Read both, preferring the nested form.
+    const nested = isRecord(raw.config) ? raw.config : {};
+    const adapter = assignment.candidate.adapter ?? readString(raw, ["adapter"]);
+    const providerName = providerNameForAdapter(adapter);
+    const baseUrl = readString(nested, ["baseUrl", "base_url", "apiBaseUrl", "api_base_url"]) ??
+        readString(raw, ["baseUrl", "base_url"]);
+    const apiKey = options.apiKey ??
+        readString(nested, ["apiKey", "api_key"]) ??
+        readString(raw, ["apiKey", "api_key"]) ??
+        (isMswarmEndpoint(baseUrl) ? resolveMswarmApiKey() : undefined);
+    const config = {
+        model: assignment.candidate.model ?? readString(raw, ["defaultModel", "model"]) ?? "",
+        baseUrl,
+        apiKey,
+        timeoutMs: options.timeoutMs ?? LOCAL_MODEL_TIMEOUT_MS,
+        runnerKind: readString(nested, ["runnerKind", "runner_kind"]),
+        authMode: readString(nested, ["authMode", "auth_mode"]),
+        localRunner: isRecord(nested.localRunner)
+            ? nested.localRunner
+            : undefined,
+        supportsTools: assignment.candidate.supportsTools ?? readBoolean(raw, ["supportsTools"]),
+        supportsJsonSchema: assignment.candidate.supportsJsonSchema ?? readBoolean(raw, ["supportsJsonSchema"]),
+        supportsStreaming: assignment.candidate.supportsStreaming ?? readBoolean(raw, ["supportsStreaming"]),
+    };
+    return createProviderForName(providerName, config);
+};
+/**
+ * Routes each gateway role to its own provider.
+ *
+ * Codali's whole premise is that a small model does the errands and a large one
+ * writes the answer. A single shared provider would silently collapse that: the
+ * planner and the synthesizer would run on the same model and the cost/quality
+ * split would be lost. So role dispatch is explicit, with a declared fallback
+ * rather than an accidental one.
+ */
+export class RoleRoutingProvider {
+    constructor(providers, fallback, resolveRole = () => undefined) {
+        this.providers = providers;
+        this.fallback = fallback;
+        this.resolveRole = resolveRole;
+        this.name = "codali-role-router";
+    }
+    providerForRole(role) {
+        if (!role)
+            return this.fallback;
+        return this.providers[role] ?? this.fallback;
+    }
+    async generate(request) {
+        return this.providerForRole(this.resolveRole()).generate(request);
+    }
+}

package/dist/gateway/LocalGatewayTaskRunner.d.ts

@@ -0,0 +1,79 @@
+import type { Provider } from "../providers/ProviderTypes.js";
+import type { ToolRegistry } from "../tools/ToolRegistry.js";
+import type { ToolContext } from "../tools/ToolTypes.js";
+import type { CodaliGatewayWorkerTaskRunInput, CodaliGatewayWorkerTaskRunResult, CodaliGatewayWorkerTaskRunner } from "./GatewayStateMachine.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 declare const MAX_TOOL_CALLS_PER_TASK = 8;
+/** Model calls per task: one to select tools, one to summarize results. */
+export declare const MAX_MODEL_CALLS_PER_TASK = 2;
+export interface LocalGatewayTaskRunnerOptions {
+    provider: Provider;
+    registry: ToolRegistry;
+    toolContext: ToolContext;
+    maxTokens?: number;
+    temperature?: number;
+    /** Observability hook; see `GatewayTracer`. */
+    onEvent?: (event: LocalGatewayTaskRunnerEvent) => void;
+}
+export type LocalGatewayTaskRunnerEvent = {
+    type: "task_start";
+    taskId: string;
+    workerRole: string;
+    allowedTools: string[];
+} | {
+    type: "tool_call";
+    taskId: string;
+    tool: string;
+    args: unknown;
+} | {
+    type: "tool_result";
+    taskId: string;
+    tool: string;
+    ok: boolean;
+    latencyMs: number;
+    errorCode?: string;
+} | {
+    type: "task_end";
+    taskId: string;
+    status: "succeeded" | "failed";
+    toolCallCount: number;
+    modelCallCount: number;
+    durationMs: number;
+};
+export declare class LocalGatewayTaskRunner implements CodaliGatewayWorkerTaskRunner {
+    private readonly options;
+    constructor(options: LocalGatewayTaskRunnerOptions);
+    run(input: CodaliGatewayWorkerTaskRunInput): Promise<CodaliGatewayWorkerTaskRunResult>;
+}
+export declare const createLocalGatewayTaskRunner: (options: LocalGatewayTaskRunnerOptions) => LocalGatewayTaskRunner;
+export declare const isRecordValue: (value: unknown) => value is Record<string, unknown>;
+//# sourceMappingURL=LocalGatewayTaskRunner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalGatewayTaskRunner.d.ts","sourceRoot":"","sources":["../../src/gateway/LocalGatewayTaskRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EAGT,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,KAAK,EAEV,+BAA+B,EAC/B,gCAAgC,EAChC,6BAA6B,EAE9B,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAe1C,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,2BAA2B,KAAK,IAAI,CAAC;CACxD;AAED,MAAM,MAAM,2BAA2B,GACnC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GAClF;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAClE;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AA6DN,qBAAa,sBAAuB,YAAW,6BAA6B;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,6BAA6B;IAE7D,GAAG,CACP,KAAK,EAAE,+BAA+B,GACrC,OAAO,CAAC,gCAAgC,CAAC;CA+S7C;AAED,eAAO,MAAM,4BAA4B,GACvC,SAAS,6BAA6B,KACrC,sBAA6D,CAAC;AAEjE,eAAO,MAAM,aAAa,UArXD,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAqX7B,CAAC"}

package/dist/gateway/LocalGatewayTaskRunner.js

@@ -0,0 +1,354 @@
+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,
+                },
+                output: result.ok
+                    ? 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,14 @@
+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;
+}
+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,eAAO,MAAM,oBAAoB,GAC/B,SAAS,qBAAqB,KAC7B,cAsCF,CAAC"}