@wardby/cli 0.6.0 → 0.8.0

package/dist/providers/coding-proxy/proxy.js

@@ -1,8 +1,12 @@
-import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { shippedCatalog } from "../llm/catalog.js";
 import { SHIPPED_CATALOG_VERSION } from "../llm/catalog-shipped.js";
 import { deriveRegistryToken } from "../../coding/registry/token.js";
-import { AnthropicSseUsageTracker, actualCostUsd, estimateReservationUsd, fingerprintRequest, parseAnthropicAuthoritativeUsage, parseAuthoritativeUsage, pricingSnapshot, safeUpstreamErrorCode, terminalUsageFromSseFrame, } from "./metering.js";
+import { capabilityHash } from "./capability-hash.js";
+import { CLAUDE_MCP_TOOL_PREFIX } from "../../coding/mcp-token.js";
+import { AnthropicSseUsageTracker, actualCostUsd, fingerprintRequest, parseAnthropicAuthoritativeUsage, parseAuthoritativeUsage, pricingSnapshot, safeUpstreamErrorCode, terminalUsageFromSseFrame, } from "./metering.js";
+import { conversationKey, estimateHold } from "./hold.js";
+import { estimateInterrupted, previousInput } from "./interrupted.js";
 import { createPinnedProxyFetch } from "./secure-fetch.js";
 export const PROXY_MAX_BODY_BYTES = 8 * 1024 * 1024;
 export const PROXY_MAX_OUTPUT_TOKENS = 1_000_000;
@@ -46,20 +50,19 @@ export class CodingProxyError extends Error {
         this.code = code;
     }
 }
-export function capabilityHash(capability) {
-    return createHash("sha256").update(capability).digest("base64url");
-}
+export { capabilityHash };
 // OpenAI Responses allowlist. Everything a request may carry is listed here;
 // anything else is refused before a credential is resolved. It mirrors what the
 // pinned Codex CLI (src/coding-worker/package.json) actually sends, recorded in
 // fixtures/codex-<version>-responses-requests.json. Only client-side tools
-// (function, custom, and namespaces of them) are allowed: a hosted tool (web
-// search, remote MCP, code interpreter, image generation, file search, ...), a
-// remote image or file, a stored prompt, or a previous response would make
-// OpenAI fetch or run something outside the worker's egress policy and outside
-// the token-metered budget. Tool names vary by model and Codex version, so they
-// are checked for shape, not against a fixed list: a client-side tool the model
-// calls is executed by the worker itself, which the container boundary governs.
+// (function, custom, namespaces of them, and the client-executed tool_search)
+// are allowed: a hosted tool (web search, remote MCP, code interpreter, image
+// generation, file search, ...), a remote image or file, a stored prompt, or a
+// previous response would make OpenAI fetch or run something outside the
+// worker's egress policy and outside the token-metered budget. Tool names vary
+// by model and Codex version, so they are checked for shape, not against a
+// fixed list: a client-side tool the model calls is executed by the worker
+// itself, which the container boundary governs.
 const OPENAI_REQUEST_KEYS = new Set([
     "model",
     "instructions",
@@ -149,13 +152,32 @@ function openAiToolName(value, code = "invalid_openai_request") {
     if (typeof value !== "string" || !OPENAI_TOOL_NAME.test(value))
         throw new CodingProxyError(400, code);
 }
-function validateOpenAiFunctionTool(tool) {
-    openAiOnlyKeys(tool, ["type", "name", "description", "strict", "parameters"], "invalid_openai_tool");
+function validateOpenAiFunctionTool(tool, inSearchOutput) {
+    openAiOnlyKeys(tool, inSearchOutput
+        ? ["type", "name", "description", "strict", "defer_loading", "parameters"]
+        : ["type", "name", "description", "strict", "parameters"], "invalid_openai_tool");
     openAiToolName(tool.name, "invalid_openai_tool");
     openAiOptional(tool.description, (value) => openAiString(value, MAX_TOOL_TEXT_BYTES, "invalid_openai_tool"));
     if (tool.strict !== undefined && typeof tool.strict !== "boolean") {
         throw new CodingProxyError(400, "invalid_openai_tool");
     }
+    // Codex marks the tools a tool_search_output loads with defer_loading: true,
+    // and sends it nowhere else. It only delays when the model sees the
+    // definition, which is checked in full.
+    if (tool.defer_loading !== undefined && tool.defer_loading !== true) {
+        throw new CodingProxyError(400, "invalid_openai_tool");
+    }
+    openAiOptional(tool.parameters, (value) => openAiRecord(value, "invalid_openai_tool"));
+}
+// The tool_search tool Codex sends for models whose metadata asks for it. Only
+// client execution: Codex runs the search over its own deferred tools and
+// returns them in a tool_search_output item. A server-executed search would
+// have OpenAI run it.
+function validateOpenAiToolSearchTool(tool) {
+    openAiOnlyKeys(tool, ["type", "execution", "description", "parameters"], "invalid_openai_tool");
+    if (tool.execution !== "client")
+        throw new CodingProxyError(400, "openai_tool_not_allowed:tool_search");
+    openAiOptional(tool.description, (value) => openAiString(value, MAX_TOOL_TEXT_BYTES, "invalid_openai_tool"));
     openAiOptional(tool.parameters, (value) => openAiRecord(value, "invalid_openai_tool"));
 }
 function validateOpenAiCustomTool(tool) {
@@ -173,30 +195,57 @@ function validateOpenAiCustomTool(tool) {
     }
     openAiString(format.definition, MAX_TOOL_TEXT_BYTES, "invalid_openai_tool");
 }
-function validateOpenAiTools(value, count, nested = false) {
+// Every tool list (the request's tools, each additional_tools item, each
+// tool_search_output item) is capped at MAX_OPENAI_TOOLS entries on its own.
+// Across the request, `distinct` holds the `namespace/name` of each callable
+// tool and is capped too. Codex replays every earlier tool_search_output on
+// each turn, so a long run repeats the same definitions many times: each copy
+// is still validated, but only a tool not seen before adds to the shared cap.
+function validateOpenAiTools(value, distinct, { toolSearch = false, inSearchOutput = false, namespace, listed = { value: 0 }, } = {}) {
     if (!Array.isArray(value))
         throw new CodingProxyError(400, "invalid_openai_tool");
+    const callable = (name) => {
+        distinct.add(`${namespace ?? ""}/${name}`);
+        if (distinct.size > MAX_OPENAI_TOOLS)
+            throw new CodingProxyError(400, "invalid_openai_tool");
+    };
     for (const candidate of value) {
-        if (++count.value > MAX_OPENAI_TOOLS)
+        if (++listed.value > MAX_OPENAI_TOOLS)
             throw new CodingProxyError(400, "invalid_openai_tool");
         const tool = openAiRecord(candidate, "invalid_openai_tool");
         if (tool.type === "function") {
-            validateOpenAiFunctionTool(tool);
+            validateOpenAiFunctionTool(tool, inSearchOutput);
+            callable(tool.name);
         }
         else if (tool.type === "custom") {
             validateOpenAiCustomTool(tool);
+            callable(tool.name);
         }
-        else if (tool.type === "namespace" && !nested) {
+        else if (tool.type === "namespace" && namespace === undefined) {
             openAiOnlyKeys(tool, ["type", "name", "description", "tools"], "invalid_openai_tool");
             openAiToolName(tool.name, "invalid_openai_tool");
             openAiOptional(tool.description, (value) => openAiString(value, MAX_TOOL_TEXT_BYTES, "invalid_openai_tool"));
-            validateOpenAiTools(tool.tools, count, true);
+            validateOpenAiTools(tool.tools, distinct, { inSearchOutput, namespace: tool.name, listed });
+        }
+        else if (tool.type === "tool_search" && toolSearch) {
+            validateOpenAiToolSearchTool(tool);
+            callable("tool_search");
         }
         else {
             throw new CodingProxyError(400, openAiCode("openai_tool_not_allowed", tool.type));
         }
     }
 }
+// The arguments the model gave the client-side tool_search, as its parameters
+// in the captures declare them: a query and an optional result limit.
+function validateOpenAiToolSearchArguments(value) {
+    const args = openAiRecord(value);
+    openAiOnlyKeys(args, ["query", "limit"]);
+    openAiString(args.query, MAX_TOOL_TEXT_BYTES);
+    if (args.limit !== undefined && !(Number.isSafeInteger(args.limit) && args.limit > 0)) {
+        throw new CodingProxyError(400, "invalid_openai_request");
+    }
+}
 function validateOpenAiContentPart(value, allowed) {
     const part = openAiRecord(value);
     if (typeof part.type !== "string" || !allowed.has(part.type)) {
@@ -239,7 +288,7 @@ function validateOpenAiTextParts(value, type) {
         openAiString(part.text, PROXY_MAX_BODY_BYTES);
     }
 }
-function validateOpenAiInputItem(value, toolCount) {
+function validateOpenAiInputItem(value, distinctTools) {
     const item = openAiRecord(value);
     switch (item.type) {
         case undefined:
@@ -298,12 +347,32 @@ function validateOpenAiInputItem(value, toolCount) {
             openAiOptional(item.recipient, (value) => openAiString(value, MAX_OPENAI_ID_LENGTH));
             validateOpenAiContent(item.content, OPENAI_AGENT_MESSAGE_PARTS, false);
             return;
+        case "tool_search_call":
+            openAiOnlyKeys(item, ["type", "id", "call_id", "status", "execution", "arguments"]);
+            openAiOptional(item.id, openAiId);
+            openAiId(item.call_id);
+            openAiOptional(item.status, (value) => openAiString(value, 64));
+            if (item.execution !== "client")
+                throw new CodingProxyError(400, openAiCode("openai_input_not_allowed", item.type));
+            validateOpenAiToolSearchArguments(item.arguments);
+            return;
+        case "tool_search_output":
+            // The tools the client-side search loaded: each one passes the same checks
+            // as a top-level tool, so this cannot bring in a shape the proxy refuses.
+            openAiOnlyKeys(item, ["type", "id", "call_id", "status", "execution", "tools"]);
+            openAiOptional(item.id, openAiId);
+            openAiId(item.call_id);
+            openAiOptional(item.status, (value) => openAiString(value, 64));
+            if (item.execution !== "client")
+                throw new CodingProxyError(400, openAiCode("openai_input_not_allowed", item.type));
+            validateOpenAiTools(item.tools, distinctTools, { inSearchOutput: true });
+            return;
         case "additional_tools":
             openAiOnlyKeys(item, ["type", "id", "role", "tools"]);
             openAiOptional(item.id, openAiId);
             if (item.role !== undefined && item.role !== "developer")
                 throw new CodingProxyError(400, "invalid_openai_request");
-            validateOpenAiTools(item.tools, toolCount);
+            validateOpenAiTools(item.tools, distinctTools);
             return;
         default:
             throw new CodingProxyError(400, openAiCode("openai_input_not_allowed", item.type));
@@ -370,9 +439,9 @@ function validateOpenAiBody(body) {
         throw new CodingProxyError(400, "invalid_openai_request");
     }
     openAiOptional(body.instructions, (value) => openAiString(value, PROXY_MAX_BODY_BYTES));
-    const toolCount = { value: 0 };
+    const distinctTools = new Set();
     if (body.tools !== undefined)
-        validateOpenAiTools(body.tools, toolCount);
+        validateOpenAiTools(body.tools, distinctTools, { toolSearch: true });
     if (body.tool_choice !== undefined) {
         if (typeof body.tool_choice !== "string" || !OPENAI_TOOL_CHOICES.has(body.tool_choice)) {
             throw new CodingProxyError(400, "openai_tool_choice_not_allowed");
@@ -399,7 +468,7 @@ function validateOpenAiBody(body) {
         throw new CodingProxyError(400, "invalid_openai_request");
     }
     for (const item of body.input)
-        validateOpenAiInputItem(item, toolCount);
+        validateOpenAiInputItem(item, distinctTools);
 }
 function parseOpenAiRequest(rawBody) {
     if (Buffer.byteLength(rawBody) > PROXY_MAX_BODY_BYTES)
@@ -514,15 +583,33 @@ function validateStructuredOutputTool(value) {
     if (tool.cache_control !== undefined)
         validateCacheControl(tool.cache_control);
 }
-function validateApprovedTool(value) {
+/**
+ * One of the run's pinned MCP tools, as Claude Code advertises it: a plain client tool named
+ * `mcp__wardby_mcp__<exposed name>` (fixtures/claude-code-2.1.286-mcp-requests.json). Only the name
+ * is checked against the pins; the gateway checks the call itself again.
+ */
+function validateMcpTool(tool) {
+    onlyKeys(tool, ["name", "description", "input_schema", "cache_control", "type"]);
+    if ((tool.description !== undefined &&
+        (typeof tool.description !== "string" || tool.description.length > MAX_TOOL_TEXT_BYTES)) ||
+        (tool.type !== undefined && tool.type !== "custom")) {
+        throw new CodingProxyError(400, "tools_not_allowed");
+    }
+    record(tool.input_schema, "tools_not_allowed");
+    if (tool.cache_control !== undefined)
+        validateCacheControl(tool.cache_control);
+}
+function validateApprovedTool(value, mcpTools) {
     const tool = record(value, "tools_not_allowed");
     if (tool.name === WARDBY_COMMAND_TOOL)
         return validateCommandTool(tool);
     if (tool.name === STRUCTURED_OUTPUT_TOOL)
         return validateStructuredOutputTool(tool);
+    if (typeof tool.name === "string" && mcpTools.has(tool.name))
+        return validateMcpTool(tool);
     throw new CodingProxyError(400, "tools_not_allowed");
 }
-function validateToolUseBlock(value) {
+function validateToolUseBlock(value, mcpTools) {
     onlyKeys(value, ["type", "id", "name", "input"]);
     if (typeof value.id !== "string" || value.id.length < 1 || value.id.length > 512) {
         throw new CodingProxyError(400, "unsupported_anthropic_feature");
@@ -531,6 +618,9 @@ function validateToolUseBlock(value) {
         return validateCommandInput(value.input);
     if (value.name === STRUCTURED_OUTPUT_TOOL)
         return void record(value.input, "unsupported_anthropic_feature");
+    if (typeof value.name === "string" && mcpTools.has(value.name)) {
+        return void record(value.input, "unsupported_anthropic_feature");
+    }
     throw new CodingProxyError(400, "unsupported_anthropic_feature");
 }
 function validateToolResultBlock(value) {
@@ -557,7 +647,7 @@ function validateThinkingBlock(value) {
         throw new CodingProxyError(400, "unsupported_anthropic_feature");
     }
 }
-function validateMessageBlocks(value, role) {
+function validateMessageBlocks(value, role, mcpTools) {
     if (!Array.isArray(value) || value.length > 10_000)
         throw new CodingProxyError(400, "invalid_anthropic_request");
     for (const candidate of value) {
@@ -566,7 +656,7 @@ function validateMessageBlocks(value, role) {
             validateTextBlock(block);
         }
         else if (block.type === "tool_use" && role === "assistant") {
-            validateToolUseBlock(block);
+            validateToolUseBlock(block, mcpTools);
         }
         else if (block.type === "tool_result" && role === "user") {
             validateToolResultBlock(block);
@@ -622,7 +712,7 @@ function validateEffortConfig(value, { thinkingMode, efforts }, betas) {
         throw new CodingProxyError(400, "unsupported_anthropic_feature");
     }
 }
-function parseAnthropicRequest(rawBody, betaHeader, shape) {
+function parseAnthropicRequest(rawBody, betaHeader, shape, mcpTools) {
     const beta = parseAnthropicBeta(betaHeader);
     if (Buffer.byteLength(rawBody) > PROXY_MAX_BODY_BYTES)
         throw new CodingProxyError(413, "payload_too_large");
@@ -686,18 +776,20 @@ function parseAnthropicRequest(rawBody, betaHeader, shape) {
                 continue;
             }
         }
-        validateMessageBlocks(message.content, message.role);
+        validateMessageBlocks(message.content, message.role, mcpTools);
     }
     if (body.tools !== undefined) {
-        if (!Array.isArray(body.tools) || body.tools.length > 2)
+        // run_command and StructuredOutput, plus one per pinned MCP tool.
+        if (!Array.isArray(body.tools) || body.tools.length > 2 + mcpTools.size) {
             throw new CodingProxyError(400, "tools_not_allowed");
+        }
         const names = new Set();
         for (const tool of body.tools) {
             const definition = record(tool, "tools_not_allowed");
             if (typeof definition.name !== "string" || names.has(definition.name))
                 throw new CodingProxyError(400, "tools_not_allowed");
             names.add(definition.name);
-            validateApprovedTool(definition);
+            validateApprovedTool(definition, mcpTools);
         }
     }
     if (body.metadata !== undefined) {
@@ -758,13 +850,17 @@ function parseAnthropicRequest(rawBody, betaHeader, shape) {
         anthropicBeta: beta.header,
     };
 }
-function parseRequest(protocol, rawBody, anthropicBeta, shape) {
+/** The Claude tool names of a session's pinned MCP tools; empty for a session without pins. */
+function claudeMcpToolNames(pins) {
+    return new Set((pins ?? []).map((pin) => `${CLAUDE_MCP_TOOL_PREFIX}${pin.exposedName}`));
+}
+function parseRequest(protocol, rawBody, anthropicBeta, shape, mcpTools) {
     if (protocol !== "anthropic-messages" && anthropicBeta !== undefined) {
         throw new CodingProxyError(400, "invalid_anthropic_beta");
     }
     try {
         return protocol === "anthropic-messages"
-            ? parseAnthropicRequest(rawBody, anthropicBeta, shape)
+            ? parseAnthropicRequest(rawBody, anthropicBeta, shape, mcpTools)
             : parseOpenAiRequest(rawBody);
     }
     catch (error) {
@@ -818,8 +914,10 @@ export class CodingProxy {
     getPricing;
     priceVersion;
     activeRequests = new Map();
+    onModelRequest;
     constructor(options) {
         this.ledger = options.ledger;
+        this.onModelRequest = options.onModelRequest;
         this.credentials = options.credentials;
         this.upstreamUrls = {
             "openai-responses": options.upstreamUrl ?? "https://api.openai.com/v1/responses",
@@ -870,6 +968,11 @@ export class CodingProxy {
             throw new Error("invalid_proxy_deadline");
         if (!input.credentialRef || input.credentialRef.length > 200)
             throw new Error("invalid_proxy_credential_reference");
+        // Both or neither: pins without a token could never be called, a token without pins lists nothing.
+        const mcp = input.mcpTools !== undefined || input.mcpTokenHash !== undefined;
+        if (mcp && (!input.mcpTools || input.mcpTools.length === 0 || !input.mcpTokenHash)) {
+            throw new Error("invalid_proxy_mcp_tools");
+        }
         const capability = `rrp_${randomBytes(32).toString("base64url")}`;
         const id = randomUUID();
         const registryTokenHash = capabilityHash(deriveRegistryToken(capability));
@@ -884,6 +987,7 @@ export class CodingProxy {
             budgetUsd: input.budgetUsd,
             registryTokenHash,
             terms: input.terms,
+            ...(mcp ? { mcpTools: input.mcpTools, mcpTokenHash: input.mcpTokenHash } : {}),
         });
         this.audit({ type: "session.created", runId: input.runId });
         return {
@@ -905,12 +1009,19 @@ export class CodingProxy {
     budgetExhausted(sessionId) {
         return this.ledger.budgetExhausted(sessionId);
     }
+    /** The numbers behind this session's first budget refusal, if any. */
+    budgetRefusal(sessionId) {
+        return this.ledger.budgetRefusal(sessionId);
+    }
     /** The code of the first upstream failure relayed for this session's run, if any. */
     upstreamFailure(sessionId) {
         return this.ledger.upstreamFailure(sessionId);
     }
     async execute(input, sink) {
         const session = await this.authenticate(input.bearer);
+        // The run's agent exists from its first model request on (both protocols arrive here).
+        if (this.onModelRequest)
+            await this.onModelRequest(session.runId).catch(() => undefined);
         if (session.protocol !== input.protocol) {
             this.audit({ type: "request.rejected", runId: session.runId, reason: "protocol_mismatch" });
             throw new CodingProxyError(403, "protocol_mismatch");
@@ -923,7 +1034,7 @@ export class CodingProxy {
         };
         let parsed;
         try {
-            parsed = parseRequest(input.protocol, input.rawBody, input.anthropicBeta, shape);
+            parsed = parseRequest(input.protocol, input.rawBody, input.anthropicBeta, shape, claudeMcpToolNames(session.mcpTools));
         }
         catch (error) {
             // The session is already authenticated and no credential has been
@@ -948,7 +1059,32 @@ export class CodingProxy {
         }
         const requestKey = safeRequestKey(input.requestKey, parsed.fingerprint);
         const snapshot = pricingSnapshot(terms.version, terms.pricing);
-        const reservationUsd = estimateReservationUsd(Buffer.byteLength(parsed.encoded), parsed.maxOutputTokens, snapshot);
+        const bodyBytes = Buffer.byteLength(parsed.encoded);
+        const conversation = conversationKey(session.protocol, parsed.body);
+        // A failed lookup holds the ceiling: never a reason to fail the request.
+        const previous = conversation ? await this.ledger.previousReply(session.id, conversation).catch(() => null) : null;
+        const holdNow = this.now();
+        const hold = estimateHold({
+            protocol: session.protocol,
+            model: parsed.model,
+            bodyBytes,
+            maxOutputTokens: parsed.maxOutputTokens,
+            pricing: snapshot,
+            previous,
+            now: holdNow,
+        });
+        // An interrupted reply's input, from the same previous reply and clock as the hold.
+        const previousPrompt = previousInput({ model: parsed.model, bodyBytes, previous, pricing: snapshot, now: holdNow });
+        const reservationUsd = hold.holdUsd;
+        const holdAudit = {
+            reservationUsd,
+            ceilingUsd: hold.ceilingUsd,
+            reservationBasis: hold.basis,
+            ...(hold.fallback ? { holdFallback: hold.fallback } : {}),
+            ...(hold.cachedTokens !== undefined
+                ? { holdCachedTokens: hold.cachedTokens, holdUncachedTokens: hold.uncachedTokens }
+                : {}),
+        };
         const reservation = await this.ledger.reserve({
             id: randomUUID(),
             sessionId: session.id,
@@ -956,6 +1092,10 @@ export class CodingProxy {
             requestFingerprint: parsed.fingerprint,
             model: parsed.model,
             reservationUsd,
+            requestBytes: bodyBytes,
+            ceilingUsd: hold.ceilingUsd,
+            reservationBasis: hold.basis,
+            conversationKey: conversation,
             pricing: snapshot,
             now: this.now(),
         });
@@ -969,7 +1109,12 @@ export class CodingProxy {
                 runId: session.runId,
                 model: parsed.model,
                 reason: "budget_exhausted",
-                reservationUsd,
+                ...holdAudit,
+                budgetUsd: reservation.details.budgetUsd,
+                spentUsd: reservation.details.spentUsd,
+                heldReservedUsd: reservation.details.heldReservedUsd,
+                heldUncertainUsd: reservation.details.heldUncertainUsd,
+                turn: reservation.details.turn,
             });
             throw new CodingProxyError(429, "wardby_budget_exhausted");
         }
@@ -982,7 +1127,7 @@ export class CodingProxy {
             runId: session.runId,
             requestId: request.id,
             model: request.model,
-            reservationUsd,
+            ...holdAudit,
         });
         let key;
         try {
@@ -1010,6 +1155,13 @@ export class CodingProxy {
         const deadlineTimer = setTimeout(() => controller.abort(), remainingMs);
         deadlineTimer.unref();
         this.trackActive(session.id, controller);
+        const progress = {
+            maxOutputTokens: parsed.maxOutputTokens,
+            stream: parsed.stream,
+            bodyBytes,
+            ...(previousPrompt ? { previousInput: previousPrompt } : {}),
+            relayedOutputBytes: 0,
+        };
         const cleanupActive = () => {
             clearTimeout(deadlineTimer);
             const active = this.activeRequests.get(session.id);
@@ -1042,10 +1194,11 @@ export class CodingProxy {
                 redirect: "error",
                 signal: controller.signal,
             });
+            progress.responseStarted = true;
         }
         catch {
             cleanupActive();
-            await this.markUncertain(session, request, undefined, controller.signal.aborted ? "upstream_aborted" : "upstream_transport");
+            await this.markUncertain(session, request, undefined, controller.signal.aborted ? "upstream_aborted" : "upstream_transport", {}, progress);
             throw new CodingProxyError(502, controller.signal.aborted ? "upstream_aborted" : "upstream_transport_error");
         }
         if (!upstream.ok) {
@@ -1068,12 +1221,12 @@ export class CodingProxy {
         }
         try {
             if (parsed.stream)
-                await this.forwardStream(session, request, upstream, sink);
+                await this.forwardStream(session, request, upstream, sink, progress);
             else
                 await this.forwardJson(session, request, upstream, sink);
         }
         catch (error) {
-            await this.markUncertain(session, request, upstream.status, failureReason(error), responseHeadersOf(upstream));
+            await this.markUncertain(session, request, upstream.status, failureReason(error), responseHeadersOf(upstream), progress);
             sink.destroy();
             throw error instanceof CodingProxyError ? error : new CodingProxyError(502, "invalid_upstream_response");
         }
@@ -1117,6 +1270,7 @@ export class CodingProxy {
     async complete(session, request, usage, upstreamStatus) {
         const costUsd = actualCostUsd(usage, request.pricing);
         await this.ledger.complete(request.id, usage, costUsd, upstreamStatus);
+        const overshootUsd = costUsd - request.reservationUsd;
         this.audit({
             type: "response.completed",
             runId: session.runId,
@@ -1124,13 +1278,17 @@ export class CodingProxy {
             model: request.model,
             status: upstreamStatus,
             costUsd,
+            reservationUsd: request.reservationUsd,
+            ...(overshootUsd > Number.EPSILON ? { reason: "reservation_exceeded", overshootUsd } : {}),
             inputTokens: usage.inputTokens,
             outputTokens: usage.outputTokens,
             cachedInputTokens: usage.cachedInputTokens,
             cacheWriteTokens: usage.cacheWriteTokens,
             reasoningTokens: usage.reasoningTokens,
         });
-        if (costUsd > request.reservationUsd + Number.EPSILON) {
+        // A cached hold may be exceeded when the cache misses (settled, audited above); the ceiling may not.
+        const ceilingUsd = request.ceilingUsd ?? request.reservationUsd;
+        if (costUsd > ceilingUsd + Number.EPSILON) {
             await this.ledger.cancelSession(session.id);
             throw new CodingProxyError(502, "reservation_invariant_violated");
         }
@@ -1156,7 +1314,7 @@ export class CodingProxy {
         await safeWrite(sink, bytes, { value: true });
         sink.end();
     }
-    async forwardStream(session, request, upstream, sink) {
+    async forwardStream(session, request, upstream, sink, progress) {
         if (!upstream.body)
             throw new Error("missing_upstream_body");
         sink.start(upstream.status, { "content-type": "text/event-stream", "cache-control": "no-store" });
@@ -1166,7 +1324,7 @@ export class CodingProxy {
         let receivedBytes = 0;
         let completed = false;
         let failedWithoutUsage = false;
-        const anthropicUsage = session.protocol === "anthropic-messages" ? new AnthropicSseUsageTracker() : undefined;
+        const anthropicUsage = session.protocol === "anthropic-messages" ? (progress.anthropic = new AnthropicSseUsageTracker()) : undefined;
         const body = upstream.body;
         for await (const chunk of body) {
             receivedBytes += chunk.byteLength;
@@ -1181,6 +1339,7 @@ export class CodingProxy {
                 buffer = buffer.slice(boundary + 2);
                 const terminal = anthropicUsage ? anthropicUsage.consume(frame) : terminalUsageFromSseFrame(frame);
                 if (!terminal.terminal) {
+                    progress.relayedOutputBytes += relayedTextBytes(frame, session.protocol);
                     await safeWrite(sink, Buffer.from(`${frame}\n\n`), connected);
                     continue;
                 }
@@ -1191,7 +1350,7 @@ export class CodingProxy {
                     // client sees the real error instead of a cut connection; the reservation stays held.
                     await this.recordUpstreamFailure(session, terminal.failure);
                     if (!completed) {
-                        await this.markUncertain(session, request, upstream.status, `upstream_failed:${terminal.failure}`, responseHeadersOf(upstream));
+                        await this.markUncertain(session, request, upstream.status, `upstream_failed:${terminal.failure}`, responseHeadersOf(upstream), progress);
                     }
                     failedWithoutUsage = true;
                     await safeWrite(sink, Buffer.from(`${frame}\n\n`), connected);
@@ -1214,9 +1373,102 @@ export class CodingProxy {
     async recordUpstreamFailure(session, code) {
         await this.ledger.recordUpstreamFailure(session.id, code).catch(() => undefined);
     }
-    async markUncertain(session, request, status, reason, headers = {}) {
-        await this.ledger.markUncertain(request.id, status);
-        this.audit({ type: "request.uncertain", runId: session.runId, requestId: request.id, status, reason, ...headers });
+    async markUncertain(session, request, status, reason, headers, progress) {
+        if (progress.marked)
+            return;
+        progress.marked = true;
+        let estimate = await this.estimateInterrupted(session, request, progress);
+        if (estimate) {
+            try {
+                await this.ledger.markUncertain(request.id, status, estimate);
+            }
+            catch {
+                // Settling at the estimate failed: mark it uncertain without one, so it keeps its full hold.
+                estimate = undefined;
+            }
+        }
+        if (!estimate)
+            await this.ledger.markUncertain(request.id, status);
+        this.audit({
+            type: "request.uncertain",
+            runId: session.runId,
+            requestId: request.id,
+            status,
+            reason,
+            ...(estimate ? { estimatedCostUsd: estimate.costUsd } : {}),
+            ...headers,
+        });
+    }
+    /**
+     * The best known cost of a request that broke before its final usage (interrupted.ts), or
+     * undefined when none can be made: the request then keeps its full hold. Never throws.
+     */
+    async estimateInterrupted(session, request, progress) {
+        try {
+            const hints = await this.ledger.settlementHints(session.id, request.model);
+            const estimate = estimateInterrupted({
+                ...progress.anthropic?.partial(),
+                beforeResponse: progress.stream && !progress.responseStarted,
+                relayedOutputBytes: progress.relayedOutputBytes,
+                ...hints,
+                ...(progress.previousInput ? { previous: progress.previousInput } : {}),
+                bodyBytes: progress.bodyBytes,
+                reservationUsd: request.reservationUsd,
+                maxOutputTokens: progress.maxOutputTokens,
+                ceilingUsd: request.ceilingUsd ?? request.reservationUsd,
+            }, request.pricing);
+            return Number.isFinite(estimate.costUsd) ? estimate : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** OpenAI Responses events whose string `delta` is generated output: text, tool input, reasoning. */
+const OPENAI_OUTPUT_DELTAS = new Set([
+    "response.output_text.delta",
+    "response.refusal.delta",
+    "response.function_call_arguments.delta",
+    "response.custom_tool_call_input.delta",
+    "response.reasoning_text.delta",
+    "response.reasoning_summary_text.delta",
+]);
+/** The generated-output field of each Anthropic content_block_delta type (signatures are not output). */
+const ANTHROPIC_OUTPUT_DELTAS = {
+    text_delta: "text",
+    input_json_delta: "partial_json",
+    thinking_delta: "thinking",
+};
+/**
+ * UTF-8 bytes of generated output in a relayed SSE frame: text, tool-call input and thinking or
+ * reasoning deltas, which are most of a coding agent's output.
+ */
+function relayedTextBytes(frame, protocol) {
+    if (!frame.includes(protocol === "anthropic-messages" ? "content_block_delta" : ".delta"))
+        return 0;
+    try {
+        const data = frame
+            .split("\n")
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).trimStart())
+            .join("\n");
+        const value = JSON.parse(data);
+        if (!value || typeof value.type !== "string")
+            return 0;
+        if (protocol === "openai-responses") {
+            return OPENAI_OUTPUT_DELTAS.has(value.type) && typeof value.delta === "string"
+                ? Buffer.byteLength(value.delta)
+                : 0;
+        }
+        if (value.type !== "content_block_delta")
+            return 0;
+        const delta = value.delta;
+        const field = typeof delta?.type === "string" ? ANTHROPIC_OUTPUT_DELTAS[delta.type] : undefined;
+        const text = field ? delta?.[field] : undefined;
+        return typeof text === "string" ? Buffer.byteLength(text) : 0;
+    }
+    catch {
+        return 0;
     }
 }
 /** The safe error code in a rejected upstream's JSON body, or undefined when it names none or cannot be read. */