@mcoda/codali 0.1.108 → 0.1.110

package/dist/gateway/Finalizer.d.ts

@@ -0,0 +1,50 @@
+import type { CodaliContextPack, CodaliGatewayRequest } from "./CodaliGatewayTypes.js";
+import type { CodaliGatewayStoredArtifact } from "./CodaliGatewayStore.js";
+import type { CodaliArtifactRef } from "./CodaliGatewayTypes.js";
+/**
+ * The finishing step every run passes through.
+ *
+ * Skipping the large synthesizer for a simple factual lookup is sensible;
+ * skipping *normalization* is not. Without one consistent finisher each tool
+ * shapes its own output, citations quietly disappear, units go unlabelled, and
+ * raw tool error strings leak to end users. So there is no path from a tool
+ * result to a caller that does not come through here.
+ *
+ * Three modes:
+ *
+ *   - `deterministic` — one clean, well-attributed result. Formatted in code,
+ *     no model call. This is what makes a simple lookup cheap.
+ *   - `synthesizer`   — multiple, conflicting, or unstructured sources. Needs
+ *     the large model to reconcile them.
+ *   - `artifact`      — media. The artifact is the answer; prose only frames it.
+ */
+export type FinalizerMode = "deterministic" | "synthesizer" | "artifact";
+export interface FinalizerDecision {
+    mode: FinalizerMode;
+    reason: string;
+}
+export interface FinalizerDecisionInput {
+    request: CodaliGatewayRequest;
+    contextPack: CodaliContextPack;
+    artifacts: readonly CodaliArtifactRef[];
+    /**
+     * Set when the router judged this a direct lookup — a question whose answer
+     * *is* the retrieved fact, rather than something that must be reasoned from
+     * it. Required for the deterministic path.
+     */
+    directLookup?: boolean;
+}
+export declare const decideFinalizerMode: (input: FinalizerDecisionInput) => FinalizerDecision;
+/**
+ * Formats a single fact without a model call. Deliberately conservative: it
+ * restates the claim and attributes it. It never paraphrases, because
+ * paraphrasing without a model is how meaning gets lost.
+ */
+export declare const formatDeterministicAnswer: (contextPack: CodaliContextPack) => string;
+/**
+ * Frames artifacts as the answer. The artifact reference carries the payload;
+ * this is only the surrounding text.
+ */
+export declare const formatArtifactAnswer: (artifacts: readonly CodaliArtifactRef[], existingAnswer?: string) => string;
+export declare const artifactRefsFromStored: (artifacts: readonly CodaliGatewayStoredArtifact[]) => CodaliArtifactRef[];
+//# sourceMappingURL=Finalizer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Finalizer.d.ts","sourceRoot":"","sources":["../../src/gateway/Finalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,aAAa,GAAG,UAAU,CAAC;AAEzE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAQD,eAAO,MAAM,mBAAmB,GAC9B,OAAO,sBAAsB,KAC5B,iBAqCF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GAAI,aAAa,iBAAiB,KAAG,MAM1E,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAC/B,WAAW,SAAS,iBAAiB,EAAE,EACvC,iBAAiB,MAAM,KACtB,MAUF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,WAAW,SAAS,2BAA2B,EAAE,KAChD,iBAAiB,EAaf,CAAC"}

package/dist/gateway/Finalizer.js

@@ -0,0 +1,79 @@
+/**
+ * A single high-confidence fact from one source, with nothing contradicting it
+ * and nothing known to be missing, does not need a large model to restate it.
+ */
+const DETERMINISTIC_MIN_CONFIDENCE = 0.85;
+export const decideFinalizerMode = (input) => {
+    if (input.artifacts.length > 0) {
+        return { mode: "artifact", reason: "run produced artifacts" };
+    }
+    // An explicit response schema means the caller wants structured output that
+    // a deterministic formatter cannot invent. Always synthesize.
+    if (input.request.response?.schema) {
+        return { mode: "synthesizer", reason: "caller supplied a response schema" };
+    }
+    // The deterministic formatter restates a retrieved claim; it cannot reason.
+    // "One high-confidence fact exists" is not sufficient grounds to use it —
+    // the question "why is X failing?" may rest on a single solid fact and still
+    // need real synthesis. So the router must have judged this a direct lookup.
+    if (!input.directLookup) {
+        return { mode: "synthesizer", reason: "not a direct lookup" };
+    }
+    const facts = input.contextPack.decisionFacts;
+    if (facts.length !== 1) {
+        return {
+            mode: "synthesizer",
+            reason: facts.length === 0 ? "no decision facts" : "multiple decision facts",
+        };
+    }
+    if (input.contextPack.contradictions.length > 0) {
+        return { mode: "synthesizer", reason: "contradictory evidence" };
+    }
+    if (input.contextPack.missingInformation.length > 0) {
+        return { mode: "synthesizer", reason: "known missing information" };
+    }
+    if ((facts[0]?.confidence ?? 0) < DETERMINISTIC_MIN_CONFIDENCE) {
+        return { mode: "synthesizer", reason: "single fact below confidence threshold" };
+    }
+    return { mode: "deterministic", reason: "single high-confidence fact" };
+};
+/**
+ * Formats a single fact without a model call. Deliberately conservative: it
+ * restates the claim and attributes it. It never paraphrases, because
+ * paraphrasing without a model is how meaning gets lost.
+ */
+export const formatDeterministicAnswer = (contextPack) => {
+    const fact = contextPack.decisionFacts[0];
+    if (!fact)
+        return "";
+    const attribution = fact.sourceTitle ?? fact.sourceUri ?? fact.sourceId;
+    const claim = fact.summary?.trim() || fact.claim.trim();
+    return attribution ? `${claim}\n\nSource: ${attribution} [${fact.id}]` : claim;
+};
+/**
+ * Frames artifacts as the answer. The artifact reference carries the payload;
+ * this is only the surrounding text.
+ */
+export const formatArtifactAnswer = (artifacts, existingAnswer) => {
+    const framed = existingAnswer?.trim();
+    const lines = artifacts.map((artifact) => {
+        const location = artifact.path ?? artifact.uri ?? artifact.id;
+        return `- ${artifact.type}: ${location}`;
+    });
+    const header = artifacts.length === 1 ? "Generated artifact:" : "Generated artifacts:";
+    return [framed, framed ? "" : undefined, header, ...lines]
+        .filter((line) => line !== undefined)
+        .join("\n");
+};
+export const artifactRefsFromStored = (artifacts) => artifacts.map((artifact) => ({
+    id: artifact.id,
+    type: artifact.type,
+    uri: artifact.uri,
+    path: artifact.path,
+    model: artifact.model,
+    taskId: artifact.taskId,
+    mimeType: typeof artifact.metadata?.mimeType === "string"
+        ? artifact.metadata.mimeType
+        : undefined,
+    metadata: artifact.metadata,
+}));

package/dist/gateway/GatewayPlanner.d.ts

@@ -5,6 +5,10 @@ export interface CodaliGatewayPlannerToolDescriptor {
     name: string;
     description?: string;
     inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    /** Capability group used for two-level tool exposure. See ToolExposure.ts. */
+    capability?: string;
+    readOnly?: boolean;
 }
 export interface GatewayPlannerInput {
     request: CodaliGatewayRequest;
@@ -58,6 +62,15 @@ export declare const CODALI_GATEWAY_CLASSIFIER_SCHEMA: {
         readonly directAnswerCandidate: {
             readonly type: "string";
         };
+        readonly capabilities: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly needsClarification: {
+            readonly type: "string";
+        };
         readonly rationale: {
             readonly type: "string";
         };

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

@@ -1 +1 @@
-{"version":3,"file":"GatewayPlanner.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayPlanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,KAAK,EACV,6BAA6B,EAC7B,0BAA0B,EAC1B,oBAAoB,EAEpB,4BAA4B,EAE7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,4BAA4B,CAAC;AAGpC,MAAM,WAAW,kCAAkC;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,kCAAkC,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,wBAAwB,CAAC;IAC5C,UAAU,EAAE,6BAA6B,CAAC;IAC1C,OAAO,EAAE,0BAA0B,CAAC;IACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,4BAA4B,EAAE,CAAC;gBAErC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,4BAA4B,EAAE;CAMnF;AAED,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuBnC,CAAC;AAEX,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+ChC,CAAC;AAoVX,eAAO,MAAM,oCAAoC,GAC/C,OAAO,mBAAmB,KACzB,eAAe,EAyBjB,CAAC;AAEF,eAAO,MAAM,iCAAiC,GAC5C,OAAO,mBAAmB,EAC1B,YAAY,6BAA6B,KACxC,eAAe,EAsCjB,CAAC;AA0VF,qBAAa,oBAAoB;IAI7B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAGxB,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,2BAAgC;IAKtD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC;QAClD,UAAU,EAAE,6BAA6B,CAAC;QAC1C,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IAiBI,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,2BAA2B,CAAC;YAkD9D,iBAAiB;CAgDhC;AAED,eAAO,MAAM,0BAA0B,GACrC,UAAU,QAAQ,EAClB,UAAU,2BAA2B,KACpC,oBAAmE,CAAC"}
+{"version":3,"file":"GatewayPlanner.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayPlanner.ts"],"names":[],"mappings":"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"}

package/dist/gateway/GatewayPlanner.js

@@ -1,6 +1,8 @@
 import { validateCodaliGatewayPlannerOutput, } from "./CodaliGatewaySchemas.js";
 import { compileCodaliGatewayPolicy, } from "./GatewayPolicyCompiler.js";
 import { CODALI_GATEWAY_SECURITY_PROMPT_HARDENING } from "./GatewaySecurityPolicy.js";
+import { renderCapabilityLines, renderToolLines } from "./ToolExposure.js";
+import { buildTemporalContext, renderTemporalContext } from "./TemporalContext.js";
 export class CodaliGatewayPlannerError extends Error {
     constructor(code, message, issues) {
         super(`${code}: ${message}`);
@@ -28,6 +30,8 @@ export const CODALI_GATEWAY_CLASSIFIER_SCHEMA = {
         needsAppTools: { type: "boolean" },
         needsImageWorker: { type: "boolean" },
         directAnswerCandidate: { type: "string" },
+        capabilities: { type: "array", items: { type: "string" } },
+        needsClarification: { type: "string" },
         rationale: { type: "string" },
         confidence: { enum: ["high", "medium", "low"] },
         metadata: { type: "object" },
@@ -360,23 +364,56 @@ const validateClassifierOutput = (value, input, policyCompilation) => {
             needsImageWorker: booleans.needsImageWorker ?? false,
             directAnswerCandidate: readString(record, "directAnswerCandidate") ??
                 readString(record, "direct_answer_candidate"),
+            capabilities: readCapabilities(record),
+            needsClarification: (() => {
+                const asked = readString(record, "needsClarification") ??
+                    readString(record, "needs_clarification");
+                const originalQuery = input?.request.query ?? "";
+                return asked && isRealClarification(asked, originalQuery) ? asked : undefined;
+            })(),
             rationale: readString(record, "rationale"),
             confidence,
             metadata: isRecord(record.metadata) ? record.metadata : undefined,
         },
     };
 };
-const describeTool = (name, descriptors) => {
-    const descriptor = descriptors?.[name];
-    if (!descriptor) {
-        return `${name}: read-only allowed tool`;
-    }
-    if (typeof descriptor === "string") {
-        return `${name}: ${descriptor}`;
-    }
-    return `${name}: ${descriptor.description ?? "read-only allowed tool"}`;
-};
 const allowedToolNames = (compilation) => [...compilation.effectiveAllowedTools].sort();
+/**
+ * Capability names the classifier selected for stage-2 tool expansion. Absent
+ * or unparseable means "no narrowing", which expands everything - a wrong
+ * selection must degrade to a bigger prompt, never to a blind planner.
+ */
+/**
+ * A clarifying question must add something. A small model asked "set
+ * needsClarification if the request is ambiguous" will sometimes echo the
+ * question back, which stops the run and tells the user nothing — worse than
+ * attempting an answer. Restatements are therefore discarded.
+ */
+const normalizeForCompare = (value) => value.toLowerCase().replace(/[^a-z0-9 ]+/g, " ").replace(/\s+/g, " ").trim();
+const isRealClarification = (question, query) => {
+    const asked = normalizeForCompare(question);
+    const original = normalizeForCompare(query);
+    if (!asked)
+        return false;
+    if (asked === original)
+        return false;
+    // A near-restatement: nothing in it that was not already in the question.
+    if (original.includes(asked) || asked.includes(original))
+        return false;
+    const originalWords = new Set(original.split(" "));
+    const novel = asked.split(" ").filter((word) => word.length > 2 && !originalWords.has(word));
+    return novel.length > 0;
+};
+const readCapabilities = (record) => {
+    const raw = record.capabilities ?? record.capability_groups ?? record.capabilityGroups;
+    if (!Array.isArray(raw))
+        return undefined;
+    const values = raw
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return values.length > 0 ? values : undefined;
+};
 export const buildCodaliGatewayClassifierMessages = (input) => {
     const policy = input.policyCompilation ?? compileCodaliGatewayPolicy({ request: input.request });
     const tools = allowedToolNames(policy);
@@ -394,8 +431,12 @@ export const buildCodaliGatewayClassifierMessages = (input) => {
         `Product: ${input.request.product?.name ?? "generic"}`,
         `Tenant scoped: ${input.request.tenant?.id || input.request.tenant?.slug ? "yes" : "unknown"}`,
         `Image worker allowed: ${input.request.policy.allowImageWorker === true ? "yes" : "no"}`,
-        `Available tools: ${tools.length > 0 ? tools.join(", ") : "none"}`,
+        ...renderTemporalContext(buildTemporalContext(input.request.query)),
+        "Available capabilities:",
+        renderCapabilityLines(tools, input.toolDescriptions),
         "Decide these booleans: needsPrivateData, needsFreshData, needsDocdex, needsAppTools, needsImageWorker.",
+        "If the request is genuinely ambiguous — an unidentifiable person, project, or scope — set needsClarification to the single question that would resolve it. Never guess an identity.",
+        "List in `capabilities` only the capability names above that this query actually needs; the planner will then see the full tool schemas for just those.",
         "If a direct answer is possible without private/runtime tools, include directAnswerCandidate.",
     ].join("\n");
     return [
@@ -406,9 +447,10 @@ export const buildCodaliGatewayClassifierMessages = (input) => {
 export const buildCodaliGatewayPlannerMessages = (input, classifier) => {
     const policy = input.policyCompilation ?? compileCodaliGatewayPolicy({ request: input.request });
     const tools = allowedToolNames(policy);
-    const toolLines = tools.length > 0
-        ? tools.map((tool) => `- ${describeTool(tool, input.toolDescriptions)}`).join("\n")
-        : "- none";
+    // Stage 2 of two-level exposure: expand full schemas, but only for the
+    // capabilities the classifier selected.
+    const exposure = renderToolLines(tools, input.toolDescriptions, classifier.capabilities);
+    const toolLines = exposure.text;
     const workerRoles = [
         "direct_answer",
         "rag_worker",
@@ -431,11 +473,15 @@ export const buildCodaliGatewayPlannerMessages = (input, classifier) => {
         `Query: ${input.request.query}`,
         `Classifier: ${JSON.stringify(classifier)}`,
         `Policy limits: maxIterations=${input.request.policy.maxIterations}, maxToolCalls=${policy.security.limits.maxToolCalls}, maxModelCalls=${policy.security.limits.maxModelCalls}, maxEvidenceItems=${policy.security.limits.maxEvidenceItems}, maxImageArtifacts=${policy.security.limits.maxImageArtifacts}`,
+        ...renderTemporalContext(buildTemporalContext(input.request.query)),
         `Worker roles available: ${workerRoles}`,
-        "Allowed tools:",
+        "Allowed tools (name, purpose, and argument shape). Use these names exactly:",
         toolLines,
+        exposure.truncated
+            ? `(Tool list truncated to ${exposure.expandedTools.length}; narrow the capabilities if the needed tool is absent.)`
+            : "",
         "Output planner JSON with queryType, subquestions, workerTasks, expectedEvidenceCount, maxIterations, requiresFinalLargeModel, and metadata.",
-    ].join("\n");
+    ].filter(Boolean).join("\n");
     return [
         { role: "system", content: system },
         { role: "user", content: user },
@@ -742,6 +788,25 @@ export class CodaliGatewayPlanner {
             throw new CodaliGatewayPlannerError("GATEWAY_POLICY_COMPILE_FAILED", "Cannot plan with invalid gateway policy.");
         }
         const classifierResult = await this.classify({ ...input, policyCompilation });
+        // A request the classifier could not disambiguate has nothing to plan.
+        // Skipping the planner stage saves a model call and, more importantly,
+        // avoids producing a plan built on a guessed identity.
+        if (classifierResult.classifier.needsClarification?.trim()) {
+            return {
+                policyCompilation,
+                classifier: classifierResult.classifier,
+                planner: {
+                    queryType: classifierResult.classifier.queryType,
+                    subquestions: [],
+                    workerTasks: [],
+                },
+                warnings: [...classifierResult.warnings, "planner_skipped:needs_clarification"],
+                classifierRepairAttempts: classifierResult.repairAttempts,
+                plannerRepairAttempts: 0,
+                classifierRawContent: classifierResult.rawContent,
+                plannerRawContent: "",
+            };
+        }
         const plannerMessages = buildCodaliGatewayPlannerMessages({ ...input, policyCompilation }, classifierResult.classifier);
         const plannerResult = await this.generateValidated("planner", plannerMessages, PLANNER_RESPONSE_FORMAT, (value) => {
             const validation = validateCodaliGatewayPlannerOutput(normalizePlannerOutput(value, { ...input, policyCompilation }, classifierResult.classifier, policyCompilation));

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

@@ -1 +1 @@
-{"version":3,"file":"GatewayStateMachine.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayStateMachine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GatewayStateMachine.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayStateMachine.ts"],"names":[],"mappings":"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"}

package/dist/gateway/GatewayStateMachine.js

@@ -1,6 +1,7 @@
 import { createInMemoryCodaliGatewayStore, } from "./CodaliGatewayStore.js";
 import { compileCodaliGatewayPolicy, } from "./GatewayPolicyCompiler.js";
 import { normalizeCodaliEvidence } from "./EvidenceNormalizer.js";
+import { buildTemporalContext, renderTemporalContext } from "./TemporalContext.js";
 import { validateCodaliGatewayVerifierOutput } from "./CodaliGatewaySchemas.js";
 import { CODALI_GATEWAY_SECURITY_PROMPT_HARDENING } from "./GatewaySecurityPolicy.js";
 import { dispatchAppToolGateway, AppToolGatewayDispatchError, } from "./AppToolGatewayDispatcher.js";
@@ -122,6 +123,11 @@ export const buildCodaliGatewayWorkerPrompt = (input) => [
     CODALI_GATEWAY_SECURITY_PROMPT_HARDENING.tenantScope,
     "Return structured evidence, source references, tool telemetry, and any errors.",
     `User query: ${input.request.query}`,
+    // The worker is what actually forms tool arguments, so it needs the resolved
+    // window. Without it a model invents dates — observed producing 2023 and
+    // 2024 ranges for "the last two weeks" in 2026 — and the tool call is
+    // syntactically fine but silently answers a different question.
+    ...renderTemporalContext(buildTemporalContext(input.request.query)),
     `Task id: ${input.task.id}`,
     `Worker role: ${input.task.workerRole}`,
     `Objective: ${input.task.objective}`,

package/dist/gateway/GatewayTracer.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Minimal run tracing.
+ *
+ * This ships with the first executable version rather than being deferred to a
+ * later observability phase. Tool-selection and iteration failures are the two
+ * things most likely to go wrong in an orchestrator, and both are close to
+ * undiagnosable without a record of what was chosen and why. Full trace replay
+ * can wait; knowing which model ran, which tools it picked, and why the run
+ * stopped cannot.
+ *
+ * Arguments are sanitized before they are recorded, because tool arguments
+ * routinely carry tokens and paths that must not reach a log.
+ */
+export interface GatewayTraceRecord {
+    runId?: string;
+    query: string;
+    startedAt: string;
+    roleBindings: Record<string, string>;
+    capabilities?: string[];
+    plannedTasks: Array<{
+        id: string;
+        role: string;
+        objective: string;
+        tools: string[];
+    }>;
+    toolCalls: Array<{
+        taskId: string;
+        tool: string;
+        args: unknown;
+        ok?: boolean;
+        latencyMs?: number;
+        errorCode?: string;
+    }>;
+    rounds: number;
+    finalizerMode?: string;
+    completionReason?: string;
+    status?: string;
+    durationMs?: number;
+    warnings: string[];
+}
+export declare const redactSecretValues: (value: string) => string;
+/**
+ * Redacts sensitive-looking values and truncates long ones. Applied to every
+ * argument before it is recorded or printed.
+ */
+export declare const sanitizeArgs: (value: unknown, depth?: number) => unknown;
+export interface GatewayTracerOptions {
+    /** Print progress to stderr as the run proceeds. */
+    verbose?: boolean;
+    write?: (line: string) => void;
+}
+export declare class GatewayTracer {
+    private readonly options;
+    private readonly record;
+    private readonly startedMs;
+    constructor(query: string, options?: GatewayTracerOptions);
+    private emit;
+    setRunId(runId: string): void;
+    setRoleBindings(bindings: Record<string, string | undefined>): void;
+    recordPlan(input: {
+        capabilities?: string[];
+        tasks: Array<{
+            id: string;
+            workerRole: string;
+            objective: string;
+            toolsAllowed?: string[];
+        }>;
+    }): void;
+    recordToolCall(input: {
+        taskId: string;
+        tool: string;
+        args: unknown;
+    }): void;
+    recordToolResult(input: {
+        taskId: string;
+        tool: string;
+        ok: boolean;
+        latencyMs: number;
+        errorCode?: string;
+    }): void;
+    recordRound(round: number): void;
+    addWarning(warning: string): void;
+    finish(input: {
+        status: string;
+        finalizerMode?: string;
+        completionReason?: string;
+        warnings?: string[];
+    }): GatewayTraceRecord;
+    snapshot(): GatewayTraceRecord;
+    /** Human-readable summary printed by `codali ask --trace`. */
+    render(): string;
+}
+//# sourceMappingURL=GatewayTracer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GatewayTracer.d.ts","sourceRoot":"","sources":["../../src/gateway/GatewayTracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACtF,SAAS,EAAE,KAAK,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,OAAO,CAAC;QACd,EAAE,CAAC,EAAE,OAAO,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AA0BD,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAMlD,CAAC;AAIF;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,EAAE,cAAS,KAAG,OAuBxD,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,qBAAa,aAAa;IAIG,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,KAAK,EAAE,MAAM,EAAmB,OAAO,GAAE,oBAAyB;IAY9E,OAAO,CAAC,IAAI;IAKZ,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B,eAAe,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,IAAI;IAUnE,UAAU,CAAC,KAAK,EAAE;QAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,KAAK,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;KAC9F,GAAG,IAAI;IAqBR,cAAc,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IAS5E,gBAAgB,CAAC,KAAK,EAAE;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,OAAO,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI;IAiBR,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKhC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC,MAAM,CAAC,KAAK,EAAE;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,GAAG,kBAAkB;IActB,QAAQ,IAAI,kBAAkB;IAI9B,8DAA8D;IAC9D,MAAM,IAAI,MAAM;CAsDjB"}