@juspay/neurolink 12.17.1 → 12.17.2

package/dist/proxy/proxyAnalysis.js

@@ -355,6 +355,8 @@ function accountEntry(accounts, account, accountType) {
     return created;
 }
 function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByRequest, accounts) {
+    let clientFinals = 0;
+    let internalFinals = 0;
     let success = 0;
     let errors = 0;
     let finalRateLimits = 0;
@@ -376,37 +378,49 @@ function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByR
     const errorTypes = {};
     const errorCodes = {};
     for (const [requestId, request] of finalRequests) {
-        const failed = request.status >= 400 ||
-            !!request.errorType ||
-            terminalStreamErrors.has(requestId);
-        if (failed) {
-            errors += 1;
+        if (request.accountingScope === "internal") {
+            internalFinals++;
         }
         else {
-            success += 1;
-        }
-        finalRateLimits += request.status === 429 ? 1 : 0;
-        const accountStats = accountEntry(accounts, request.account, request.accountType);
-        accountStats.finalRequests += 1;
-        accountStats.finalErrors += failed ? 1 : 0;
-        if (failed) {
-            increment(errorTypes, terminalStreamErrors.has(requestId)
-                ? "stream_error"
-                : (request.errorType ?? `http_${request.status}`));
-            if (request.errorCode) {
-                increment(errorCodes, request.errorCode);
+            clientFinals++;
+            const failed = request.status >= 400 ||
+                !!request.errorType ||
+                terminalStreamErrors.has(requestId);
+            if (failed) {
+                errors += 1;
+            }
+            else {
+                success += 1;
+            }
+            finalRateLimits += request.status === 429 ? 1 : 0;
+            const accountStats = accountEntry(accounts, request.account, request.accountType);
+            accountStats.finalRequests += 1;
+            accountStats.finalErrors += failed ? 1 : 0;
+            if (failed) {
+                increment(errorTypes, terminalStreamErrors.has(requestId)
+                    ? "stream_error"
+                    : (request.errorType ?? `http_${request.status}`));
+                if (request.errorCode) {
+                    increment(errorCodes, request.errorCode);
+                }
+            }
+            if (request.durationMs !== null && request.durationMs >= 0) {
+                finalRequestLatency.push(request.durationMs);
+            }
+            const requestAttempts = attemptsByRequest.get(requestId);
+            recoveredAfterRetry += !failed && requestAttempts?.hadError ? 1 : 0;
+            if (requestAttempts?.count === 1 &&
+                requestAttempts.durationCount === 1 &&
+                request.durationMs !== null &&
+                Number.isFinite(requestAttempts.totalDurationMs)) {
+                singleAttemptDelta.push(request.durationMs - requestAttempts.totalDurationMs);
             }
         }
-        if (request.durationMs !== null && request.durationMs >= 0) {
-            finalRequestLatency.push(request.durationMs);
-        }
-        const requestAttempts = attemptsByRequest.get(requestId);
-        recoveredAfterRetry += !failed && requestAttempts?.hadError ? 1 : 0;
-        if (requestAttempts?.count === 1 &&
-            requestAttempts.durationCount === 1 &&
-            request.durationMs !== null &&
-            Number.isFinite(requestAttempts.totalDurationMs)) {
-            singleAttemptDelta.push(request.durationMs - requestAttempts.totalDurationMs);
+        // Only the designated owner contributes provider usage. Client bridge
+        // records retain outcome/latency while their linked child owns token cost.
+        if (request.usageOwnerRequestId &&
+            request.usageOwnerRequestId !== requestId) {
+            continue;
         }
         if (request.inputTokens !== null ||
             request.outputTokens !== null ||
@@ -455,7 +469,8 @@ function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByR
     }
     return {
         requestTotals: {
-            completed: finalRequests.size,
+            completed: clientFinals,
+            internalCompleted: internalFinals,
             success,
             errors,
             finalRateLimits,
@@ -587,6 +602,7 @@ export async function analyzeProxyLogs(options) {
     let malformedLines = 0;
     let unsupportedLifecycleLines = 0;
     const accepted = new Set();
+    const internalRequests = new Set();
     const auxiliaryRequests = new Set();
     const headers = new Set();
     const firstChunks = new Set();
@@ -630,6 +646,9 @@ export async function analyzeProxyLogs(options) {
             if (timestamp === null || !requestId) {
                 return;
             }
+            if (record.accountingScope === "internal") {
+                internalRequests.add(requestId);
+            }
             const event = stringValue(record.event);
             if (record.schemaVersion !== 1 ||
                 !event ||
@@ -749,15 +768,6 @@ export async function analyzeProxyLogs(options) {
                 if (elapsed !== null && elapsed >= 0) {
                     terminalLatencyByRequest.set(requestId, elapsed);
                 }
-                increment(terminalOutcomes, stringValue(record.terminalOutcome) ?? "unknown");
-                const errorType = stringValue(record.errorType);
-                const errorCode = stringValue(record.errorCode);
-                if (errorType) {
-                    increment(lifecycleErrorTypes, errorType);
-                }
-                if (errorCode) {
-                    increment(lifecycleErrorCodes, errorCode);
-                }
             }
         }, () => {
             malformedLines += 1;
@@ -785,11 +795,8 @@ export async function analyzeProxyLogs(options) {
     // Contradictory copies are not reliable latency samples. Keep their data
     // quality count, but do not choose one timing arbitrarily.
     const verifiedLatencies = (values) => [...values]
-        .filter(([id]) => !conflictedRequests.has(id))
+        .filter(([id]) => !conflictedRequests.has(id) && !internalRequests.has(id))
         .map(([, ms]) => ms);
-    const headersLatency = verifiedLatencies(headersLatencyByRequest);
-    const firstChunkLatency = verifiedLatencies(firstChunkLatencyByRequest);
-    const terminalLatency = verifiedLatencies(terminalLatencyByRequest);
     let lifecycleSequenceGaps = 0;
     let lifecycleSequenceDuplicates = 0;
     for (const [processId, allValues] of sequences) {
@@ -972,7 +979,15 @@ export async function analyzeProxyLogs(options) {
             else {
                 absentRoutingDecisions += 1;
             }
+            if (record.accountingScope === "internal") {
+                internalRequests.add(requestId);
+            }
             const parsed = {
+                accountingScope: internalRequests.has(requestId)
+                    ? "internal"
+                    : "client",
+                parentRequestId: stringValue(record.parentRequestId) ?? undefined,
+                usageOwnerRequestId: stringValue(record.usageOwnerRequestId) ?? undefined,
                 firstUsefulOutputMs: finiteNumber(record.firstUsefulOutputMs),
                 timestamp: new Date(timestamp).toISOString(),
                 status,
@@ -1057,7 +1072,17 @@ export async function analyzeProxyLogs(options) {
             !(recorded === "bodyless" && resolved === "completed")) {
             finalOutcomeConflicts += 1;
         }
-        increment(terminalOutcomes, resolved);
+        if (!internalRequests.has(requestId)) {
+            increment(terminalOutcomes, resolved);
+            const errorType = stringValue(record.errorType);
+            const errorCode = stringValue(record.errorCode);
+            if (errorType) {
+                increment(lifecycleErrorTypes, errorType);
+            }
+            if (errorCode) {
+                increment(lifecycleErrorCodes, errorCode);
+            }
+        }
     }
     let capturesIndexed = 0;
     let truncatedCaptures = 0;
@@ -1210,14 +1235,18 @@ export async function analyzeProxyLogs(options) {
                     },
                 ];
             }),
-            accepted: accepted.size,
-            auxiliaryRequests: [...accepted].filter((id) => auxiliaryRequests.has(id))
+            accepted: [...accepted].filter((id) => !internalRequests.has(id)).length,
+            internalAccepted: [...accepted].filter((id) => internalRequests.has(id))
+                .length,
+            auxiliaryRequests: [...accepted].filter((id) => auxiliaryRequests.has(id) && !internalRequests.has(id)).length,
+            headers: [...headers].filter((id) => !internalRequests.has(id)).length,
+            firstChunks: [...firstChunks].filter((id) => !internalRequests.has(id))
                 .length,
-            headers: headers.size,
-            firstChunks: firstChunks.size,
-            terminal: terminal.size,
-            unsettled: [...accepted].filter((requestId) => !terminal.has(requestId))
+            terminal: [...terminal].filter((id) => !internalRequests.has(id)).length,
+            internalTerminal: [...terminal].filter((id) => internalRequests.has(id))
                 .length,
+            internalUnsettled: [...accepted].filter((id) => internalRequests.has(id) && !terminal.has(id)).length,
+            unsettled: [...accepted].filter((requestId) => !internalRequests.has(requestId) && !terminal.has(requestId)).length,
             terminalOutcomes,
             errorTypes: lifecycleErrorTypes,
             errorCodes: lifecycleErrorCodes,
@@ -1237,12 +1266,13 @@ export async function analyzeProxyLogs(options) {
             unclassified: unclassifiedRateLimits,
         },
         latencyMs: {
-            headers: summarizeLatency(headersLatency),
-            firstChunk: summarizeLatency(firstChunkLatency),
-            firstUsefulOutput: summarizeLatency([...finalRequests.values()].flatMap((record) => record.firstUsefulOutputMs === null
+            headers: summarizeLatency(verifiedLatencies(headersLatencyByRequest)),
+            firstChunk: summarizeLatency(verifiedLatencies(firstChunkLatencyByRequest)),
+            firstUsefulOutput: summarizeLatency([...finalRequests.values()].flatMap((record) => record.accountingScope === "internal" ||
+                record.firstUsefulOutputMs === null
                 ? []
                 : [record.firstUsefulOutputMs])),
-            terminal: summarizeLatency(terminalLatency),
+            terminal: summarizeLatency(verifiedLatencies(terminalLatencyByRequest)),
             finalRequest: summarizeLatency(finalSummary.finalRequestLatency),
             attempt: summarizeLatency(attemptLatency),
             singleAttemptDelta: summarizeLatency(finalSummary.singleAttemptDelta),

package/dist/proxy/proxyClientCancellation.d.ts

@@ -0,0 +1,7 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** Node's fetch Request does not always abort when a completed upload's peer
+ * disconnects before response headers. Observe the response socket as well. */
+export declare function bindProxyClientCancellation(request: Request, bindings: {
+    incoming?: IncomingMessage;
+    outgoing?: ServerResponse;
+} | undefined, controller: AbortController): () => void;

package/dist/proxy/proxyClientCancellation.js

@@ -0,0 +1,23 @@
+/** Node's fetch Request does not always abort when a completed upload's peer
+ * disconnects before response headers. Observe the response socket as well. */
+export function bindProxyClientCancellation(request, bindings, controller) {
+    const abort = () => controller.abort(new DOMException("Client disconnected", "AbortError"));
+    const close = () => {
+        if (!bindings?.outgoing?.writableFinished) {
+            abort();
+        }
+    };
+    request.signal.addEventListener("abort", abort, { once: true });
+    bindings?.incoming?.once("aborted", abort);
+    bindings?.outgoing?.once("close", close);
+    if (request.signal.aborted ||
+        bindings?.incoming?.aborted ||
+        bindings?.outgoing?.destroyed) {
+        abort();
+    }
+    return () => {
+        request.signal.removeEventListener("abort", abort);
+        bindings?.incoming?.removeListener("aborted", abort);
+        bindings?.outgoing?.removeListener("close", close);
+    };
+}

package/dist/proxy/proxyContextPreflight.d.ts

@@ -0,0 +1,25 @@
+import type { ProxyContextPolicy, ProxyContextEvidence, ProxyPreparedContext } from "../types/index.js";
+/** Local refusal before spending a provider request; never silently truncates. */
+export declare class ProxyContextPreflightError extends Error {
+    readonly code: string;
+    readonly evidence?: ProxyContextEvidence | undefined;
+    readonly status = 400;
+    readonly retryable = false;
+    constructor(code: string, message: string, evidence?: ProxyContextEvidence | undefined);
+}
+/** An invalid configured budget must not silently disable protection. */
+export declare function parseProxyContextPolicy(raw: string | undefined): ProxyContextPolicy;
+export declare function getProxyContextPolicy(): ProxyContextPolicy;
+/**
+ * Preserve history, instructions and tool-call pairs. Tool reduction is explicit
+ * opt-in; discovered/configured context limits never use a guessed model default.
+ */
+export declare function prepareProxyRequestContext<T extends object>(args: {
+    provider: string;
+    model: string;
+    body: T;
+    /** Original protocol body before an adapter flattens historical tool calls. */
+    toolReferenceBody?: unknown;
+    maxOutputTokens?: number;
+    policy?: ProxyContextPolicy;
+}): ProxyPreparedContext<T>;

package/dist/proxy/proxyContextPreflight.js

@@ -0,0 +1,337 @@
+import { getRuntimeContextWindow, getRuntimeOutputCeiling, } from "../constants/contextWindows.js";
+import { estimateTokens, IMAGE_TOKEN_ESTIMATE, } from "../utils/tokenEstimation.js";
+/** Local refusal before spending a provider request; never silently truncates. */
+export class ProxyContextPreflightError extends Error {
+    code;
+    evidence;
+    status = 400;
+    retryable = false;
+    constructor(code, message, evidence) {
+        super(message);
+        this.code = code;
+        this.evidence = evidence;
+        this.name = "ProxyContextPreflightError";
+    }
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function positive(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+/** An invalid configured budget must not silently disable protection. */
+export function parseProxyContextPolicy(raw) {
+    if (!raw?.trim()) {
+        return {};
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new ProxyContextPreflightError("invalid_context_policy", "NEUROLINK_PROXY_CONTEXT_POLICY must contain a JSON object");
+    }
+    if (!record(value)) {
+        throw new ProxyContextPreflightError("invalid_context_policy", "Proxy context policy must be an object");
+    }
+    for (const key of Object.keys(value)) {
+        if (![
+            "maxInputTokens",
+            "outputReserveTokens",
+            "enforceDiscoveredLimits",
+            "toolAllowlist",
+            "models",
+        ].includes(key)) {
+            throw new ProxyContextPreflightError("invalid_context_policy", `Unknown context policy field: ${key}`);
+        }
+    }
+    for (const key of ["maxInputTokens", "outputReserveTokens"]) {
+        if (value[key] !== undefined && !positive(value[key])) {
+            throw new ProxyContextPreflightError("invalid_context_policy", `${key} must be a positive safe integer`);
+        }
+    }
+    if (value.enforceDiscoveredLimits !== undefined &&
+        typeof value.enforceDiscoveredLimits !== "boolean") {
+        throw new ProxyContextPreflightError("invalid_context_policy", "enforceDiscoveredLimits must be boolean");
+    }
+    if (value.toolAllowlist !== undefined &&
+        (!Array.isArray(value.toolAllowlist) ||
+            value.toolAllowlist.length > 4096 ||
+            !value.toolAllowlist.every((name) => typeof name === "string" && name.length > 0 && name.length <= 256))) {
+        throw new ProxyContextPreflightError("invalid_context_policy", "toolAllowlist must be a bounded array of tool names");
+    }
+    if (value.models !== undefined) {
+        if (!record(value.models) || Object.keys(value.models).length > 1024) {
+            throw new ProxyContextPreflightError("invalid_context_policy", "models must be a bounded map of provider/model limits");
+        }
+        for (const [key, limit] of Object.entries(value.models)) {
+            if (!key.includes("/") ||
+                !record(limit) ||
+                !positive(limit.contextWindow) ||
+                (limit.maxOutputTokens !== undefined &&
+                    !positive(limit.maxOutputTokens)) ||
+                Object.keys(limit).some((k) => !["contextWindow", "maxOutputTokens"].includes(k))) {
+                throw new ProxyContextPreflightError("invalid_context_policy", "Each model needs an explicit provider/model key and positive contextWindow/output limit");
+            }
+        }
+    }
+    return value;
+}
+let lastPolicyText;
+let lastPolicy;
+export function getProxyContextPolicy() {
+    const raw = process.env.NEUROLINK_PROXY_CONTEXT_POLICY;
+    if (!lastPolicy || raw !== lastPolicyText) {
+        lastPolicy = parseProxyContextPolicy(raw);
+        lastPolicyText = raw;
+    }
+    return lastPolicy;
+}
+/** Collect referenced tools so selection never strands a historical call/result. */
+function referencedTools(value, names, seen = new WeakSet(), depth = 0) {
+    if (!value || typeof value !== "object" || depth > 128 || seen.has(value)) {
+        return;
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            referencedTools(item, names, seen, depth + 1);
+        }
+        return;
+    }
+    const item = value;
+    if (["tool_use", "function_call", "tool_call", "function"].includes(String(item.type))) {
+        const name = item.name ?? item.toolName;
+        if (typeof name === "string") {
+            names.add(name);
+        }
+        if (record(item.function) && typeof item.function.name === "string") {
+            names.add(item.function.name);
+        }
+    }
+    if (typeof item.toolName === "string") {
+        names.add(item.toolName);
+    }
+    if (record(item.functionCall) && typeof item.functionCall.name === "string") {
+        names.add(item.functionCall.name);
+    }
+    for (const [key, child] of Object.entries(item)) {
+        if (key !== "tools") {
+            referencedTools(child, names, seen, depth + 1);
+        }
+    }
+}
+function toolName(tool) {
+    if (!record(tool)) {
+        return undefined;
+    }
+    if (typeof tool.name === "string") {
+        return tool.name;
+    }
+    return record(tool.function) && typeof tool.function.name === "string"
+        ? tool.function.name
+        : undefined;
+}
+function toolCount(value) {
+    return Array.isArray(value)
+        ? value.length
+        : record(value)
+            ? Object.keys(value).length
+            : 0;
+}
+/** Estimate without copying binary payloads or building another giant JSON string. */
+function estimateValue(value, provider, state, seen = new WeakSet(), depth = 0) {
+    if (typeof value === "string") {
+        return estimateTokens(value, provider) + 1;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return 1;
+    }
+    if (!value || typeof value !== "object") {
+        return 0;
+    }
+    if (depth > 128) {
+        throw new ProxyContextPreflightError("context_structure_too_deep", "Request context nesting exceeds the supported limit");
+    }
+    if (seen.has(value)) {
+        return 0;
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.reduce((sum, item) => sum + estimateValue(item, provider, state, seen, depth + 1) + 4, 0);
+        }
+        const item = value;
+        if (value instanceof Uint8Array || value instanceof ArrayBuffer) {
+            state.multimodal = true;
+            return IMAGE_TOKEN_ESTIMATE;
+        }
+        if (typeof item.text === "string" && Array.isArray(item.images)) {
+            state.multimodal = item.images.length > 0 || state.multimodal;
+            return (estimateTokens(item.text, provider) +
+                item.images.length * IMAGE_TOKEN_ESTIMATE);
+        }
+        if ([
+            "input_image",
+            "image",
+            "image_url",
+            "input_audio",
+            "audio",
+            "file",
+            "input_file",
+            "document",
+        ].includes(String(item.type)) ||
+            item.inlineData !== undefined ||
+            item.fileData !== undefined) {
+            state.multimodal = true;
+            return IMAGE_TOKEN_ESTIMATE;
+        }
+        return Object.entries(item).reduce((sum, [key, child]) => sum +
+            estimateTokens(key, provider) +
+            estimateValue(child, provider, state, seen, depth + 1), 0);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/**
+ * Preserve history, instructions and tool-call pairs. Tool reduction is explicit
+ * opt-in; discovered/configured context limits never use a guessed model default.
+ */
+export function prepareProxyRequestContext(args) {
+    const policy = args.policy ?? getProxyContextPolicy();
+    const original = args.body;
+    let body = args.body;
+    const tools = original.tools;
+    if (policy.toolAllowlist) {
+        const keep = new Set(policy.toolAllowlist);
+        referencedTools(original, keep);
+        referencedTools(args.toolReferenceBody, keep);
+        const choice = original.tool_choice;
+        if (record(choice)) {
+            if (typeof choice.name === "string") {
+                keep.add(choice.name);
+            }
+            if (record(choice.function) && typeof choice.function.name === "string") {
+                keep.add(choice.function.name);
+            }
+        }
+        const selected = Array.isArray(tools)
+            ? tools.filter((tool) => {
+                const name = toolName(tool);
+                return name === undefined || keep.has(name);
+            })
+            : record(tools)
+                ? Object.fromEntries(Object.entries(tools).filter(([name]) => keep.has(name)))
+                : tools;
+        body = {
+            ...args.body,
+            tools: selected,
+            ...(Array.isArray(original.toolFilter)
+                ? {
+                    toolFilter: original.toolFilter.filter((name) => typeof name !== "string" || keep.has(name)),
+                }
+                : {}),
+        };
+    }
+    const wire = body;
+    const state = { multimodal: false };
+    const provider = args.provider === "codex" ? "openai" : args.provider;
+    const toolsTokensEstimate = estimateValue(wire.tools, provider, state);
+    const instructionsTokensEstimate = [
+        wire.instructions,
+        wire.system,
+        wire.systemPrompt,
+        wire.systemInstruction,
+    ].reduce((sum, value) => sum + estimateValue(value, provider, state), 0);
+    const schemaTokensEstimate = [
+        wire.response_format,
+        wire.output_config,
+        wire.structuredOutput,
+        wire.schema,
+        record(wire.text) ? wire.text.format : undefined,
+        record(wire.generationConfig)
+            ? wire.generationConfig.responseSchema
+            : undefined,
+        record(wire.generationConfig)
+            ? wire.generationConfig.responseJsonSchema
+            : undefined,
+    ].reduce((sum, value) => sum + estimateValue(value, provider, state), 0);
+    const inputTokensEstimate = 24 +
+        schemaTokensEstimate +
+        toolsTokensEstimate +
+        instructionsTokensEstimate +
+        [
+            wire.messages,
+            wire.input,
+            wire.contents,
+            wire.conversationMessages,
+            wire.prompt,
+        ].reduce((sum, value) => sum + estimateValue(value, provider, state), 0);
+    const configured = policy.models?.[`${args.provider}/${args.model}`];
+    const discovered = getRuntimeContextWindow(args.provider, args.model);
+    const contextWindow = configured?.contextWindow ?? discovered;
+    const outputCeiling = configured?.maxOutputTokens ??
+        getRuntimeOutputCeiling(args.provider, args.model);
+    const requestedOutput = args.maxOutputTokens ??
+        wire.max_tokens ??
+        wire.max_output_tokens ??
+        wire.maxTokens ??
+        (record(wire.generationConfig)
+            ? wire.generationConfig.maxOutputTokens
+            : undefined);
+    if (requestedOutput !== undefined && !positive(requestedOutput)) {
+        throw new ProxyContextPreflightError("invalid_output_budget", "Requested output tokens must be a positive safe integer");
+    }
+    // Codex rejects max_output_tokens; its model-owned ceiling, not Claude's
+    // requested max_tokens, must be reserved when bridging to that transport.
+    const outputTokensReserve = args.provider === "codex"
+        ? (outputCeiling ?? policy.outputReserveTokens ?? 32768)
+        : positive(requestedOutput)
+            ? requestedOutput
+            : (outputCeiling ?? policy.outputReserveTokens ?? 32768);
+    const evidence = {
+        provider: args.provider,
+        model: args.model,
+        inputTokensEstimate,
+        toolsTokensEstimate,
+        instructionsTokensEstimate,
+        schemaTokensEstimate,
+        outputTokensReserve,
+        reasoningIncludedInOutputReserve: true,
+        ...(contextWindow ? { contextWindow } : {}),
+        contextLimitSource: configured
+            ? "configured"
+            : discovered
+                ? "discovered"
+                : "unknown",
+        tokenCountSource: "estimated",
+        multimodalEstimate: state.multimodal,
+        originalToolCount: toolCount(tools),
+        retainedToolCount: toolCount(wire.tools),
+        historyModified: false,
+    };
+    if (policy.maxInputTokens !== undefined &&
+        inputTokensEstimate > policy.maxInputTokens) {
+        throw new ProxyContextPreflightError("proxy_input_budget_exceeded", "Estimated input exceeds the configured proxy token budget; reduce context or tools before retrying", evidence);
+    }
+    if (outputCeiling !== undefined &&
+        positive(requestedOutput) &&
+        args.provider !== "codex" &&
+        requestedOutput > outputCeiling) {
+        throw new ProxyContextPreflightError("proxy_output_budget_exceeded", "Requested output exceeds the serving model's known output limit", evidence);
+    }
+    if (contextWindow !== undefined &&
+        policy.enforceDiscoveredLimits !== false &&
+        !state.multimodal &&
+        inputTokensEstimate + outputTokensReserve > contextWindow) {
+        throw new ProxyContextPreflightError("proxy_context_window_exceeded", "Estimated input plus output/reasoning reserve exceeds the serving model context window; no history was truncated", evidence);
+    }
+    return {
+        body,
+        inputTokensEstimate,
+        outputTokensReserve,
+        totalTokensReservation: inputTokensEstimate + outputTokensReserve,
+        evidence,
+    };
+}

package/dist/proxy/proxyFailureDetails.d.ts

@@ -0,0 +1,19 @@
+/** Shared provider terminal codes across native and SDK transports. */
+export declare function classifyProxyFailureCode(code: string | undefined): {
+    status: number;
+    retryable: boolean;
+} | {
+    status: undefined;
+    retryable: boolean;
+} | {
+    status: number | undefined;
+    retryable: undefined;
+};
+/** Read explicit SDK/API failure evidence without guessing from free-form text.
+ * Bounded traversal covers common error/cause/data and JSON response envelopes. */
+export declare function getProxyUpstreamFailure(error: unknown): {
+    status: number;
+    code: string | undefined;
+    retryable: boolean | undefined;
+    message: string | undefined;
+} | undefined;