;
/**
@@ -345,29 +332,20 @@ function summarizeFilteredLogs(entries: LogEntry[]): {
requests: number;
totalTokens: number;
estimatedCostUsd: number;
+ priorityLowerBound: boolean;
unpricedRequests: number;
unmeteredRequests: number;
} {
let totalTokens = 0;
- let estimatedCostUsd = 0;
- let unpricedRequests = 0;
- let unmeteredRequests = 0;
for (const entry of entries) {
const tokens = displayTokenTotal(entry);
if (tokens !== undefined) totalTokens += tokens;
- if (entry.usageStatus === "unsupported") {
- unmeteredRequests += 1;
- continue;
- }
- const cost = entry.displayMetrics?.cost;
- const total = cost?.kind === "value" ? cost.estimate.cost.total : undefined;
- if (total !== undefined && Number.isFinite(total) && total >= 0) {
- estimatedCostUsd += total;
- continue;
- }
- unpricedRequests += 1;
}
- return { requests: entries.length, totalTokens, estimatedCostUsd, unpricedRequests, unmeteredRequests };
+ return {
+ requests: entries.length,
+ totalTokens,
+ ...summarizeEstimatedCosts(entries),
+ };
}
export default function Logs({ apiBase }: { apiBase: string }) {
@@ -612,7 +590,12 @@ export default function Logs({ apiBase }: { apiBase: string }) {
{t("logs.conversation.totals", {
requests: conversationTotals.requests,
tokens: formatTokens(conversationTotals.totalTokens, localeTag ?? locale),
- cost: formatEstimatedUsdValue(conversationTotals.estimatedCostUsd, localeTag),
+ cost: formatEstimatedUsdValue(
+ conversationTotals.estimatedCostUsd,
+ t,
+ localeTag,
+ conversationTotals.priorityLowerBound,
+ ),
})}
{" "}
@@ -731,7 +714,7 @@ export default function Logs({ apiBase }: { apiBase: string }) {
{formatTokPerSecond(log.displayMetrics?.tokPerSecond, localeTag)}
|
- {formatEstimatedUsd(log.displayMetrics?.cost, localeTag)}
+ {formatEstimatedUsd(log.displayMetrics?.cost, t, localeTag)}
|
@@ -956,11 +939,11 @@ function LogDetailDialog({
{cost?.kind === "value" ? (
<>
- {t("logs.detail.costTotal")}{formatEstimatedUsdValue(cost.estimate.cost.total, localeTag)}
- {t("logs.tokens.input")}{formatEstimatedUsdValue(cost.estimate.cost.input, localeTag)}
- {t("logs.tokens.cacheRead")}{formatEstimatedUsdValue(cost.estimate.cost.cacheRead, localeTag)}
- {t("logs.tokens.cacheWrite")}{formatEstimatedUsdValue(cost.estimate.cost.cacheWrite, localeTag)}
- {t("logs.tokens.output")}{formatEstimatedUsdValue(cost.estimate.cost.output, localeTag)}
+ {t("logs.detail.costTotal")}{formatEstimatedUsdValue(cost.estimate.cost.total, t, localeTag, cost.estimate.priorityLowerBound)}
+ {t("logs.tokens.input")}{formatEstimatedUsdValue(cost.estimate.cost.input, t, localeTag, cost.estimate.priorityLowerBound)}
+ {t("logs.tokens.cacheRead")}{formatEstimatedUsdValue(cost.estimate.cost.cacheRead, t, localeTag, cost.estimate.priorityLowerBound)}
+ {t("logs.tokens.cacheWrite")}{formatEstimatedUsdValue(cost.estimate.cost.cacheWrite, t, localeTag, cost.estimate.priorityLowerBound)}
+ {t("logs.tokens.output")}{formatEstimatedUsdValue(cost.estimate.cost.output, t, localeTag, cost.estimate.priorityLowerBound)}
{cost.estimate.price && (
<>
{t("logs.detail.matchedKey")}
@@ -978,7 +961,7 @@ function LogDetailDialog({
) : (
- {t("logs.detail.costTotal")}{"\u2014"}
+ {t("logs.detail.costTotal")}{t("logs.cost.unavailable")}
{t("logs.detail.unavailableReason")}
{cost?.kind === "unavailable" ? t(metricReasonKey(cost.reason)) : t("logs.detail.reason.usage_missing")}
@@ -1033,7 +1016,7 @@ function LogDetailDialog({
|
{attempt.durationMs}ms |
{formatTokPerSecond(attempt.displayMetrics?.tokPerSecond, localeTag)} |
- {formatEstimatedUsd(attemptCost, localeTag)} |
+ {formatEstimatedUsd(attemptCost, t, localeTag)} |
{reason} |
);
diff --git a/gui/src/pages/logs-cost-format.ts b/gui/src/pages/logs-cost-format.ts
new file mode 100644
index 0000000000..48a0814097
--- /dev/null
+++ b/gui/src/pages/logs-cost-format.ts
@@ -0,0 +1,77 @@
+import type { TFn } from "../i18n/shared";
+
+type EstimatedCostResult = {
+ kind: "value";
+ estimate: { cost: { total: number }; priorityLowerBound?: boolean };
+} | { kind: "unavailable" };
+
+export function formatEstimatedUsdValue(
+ value: number,
+ t: TFn,
+ localeTag?: string,
+ priorityLowerBound = false,
+): string {
+ if (!Number.isFinite(value) || value < 0) return t("logs.cost.unavailable");
+ const amount = new Intl.NumberFormat(localeTag, {
+ style: "currency",
+ currency: "USD",
+ minimumFractionDigits: 4,
+ maximumFractionDigits: 4,
+ }).format(value);
+ return t(priorityLowerBound ? "logs.cost.lowerBound" : "logs.cost.approximate", { amount });
+}
+
+export function formatEstimatedUsd(
+ result: EstimatedCostResult | undefined,
+ t: TFn,
+ localeTag?: string,
+): string {
+ if (!result || result.kind === "unavailable") return t("logs.cost.unavailable");
+ return formatEstimatedUsdValue(
+ result.estimate.cost.total,
+ t,
+ localeTag,
+ result.estimate.priorityLowerBound,
+ );
+}
+
+interface CostSummaryEntry {
+ usageStatus?: string;
+ displayMetrics?: { cost: EstimatedCostResult };
+}
+
+export function summarizeEstimatedCosts(entries: readonly CostSummaryEntry[]): {
+ estimatedCostUsd: number;
+ priorityLowerBound: boolean;
+ unpricedRequests: number;
+ unmeteredRequests: number;
+} {
+ let estimatedCostUsd = 0;
+ let everyPricedEstimateIsLowerBound = true;
+ let pricedEstimates = 0;
+ let unpricedRequests = 0;
+ let unmeteredRequests = 0;
+ for (const entry of entries) {
+ if (entry.usageStatus === "unsupported") {
+ unmeteredRequests += 1;
+ continue;
+ }
+ const cost = entry.displayMetrics?.cost;
+ if (cost?.kind === "value") {
+ const total = cost.estimate.cost.total;
+ if (Number.isFinite(total) && total >= 0) {
+ estimatedCostUsd += total;
+ pricedEstimates += 1;
+ everyPricedEstimateIsLowerBound &&= cost.estimate.priorityLowerBound === true;
+ continue;
+ }
+ }
+ unpricedRequests += 1;
+ }
+ return {
+ estimatedCostUsd,
+ priorityLowerBound: pricedEstimates > 0 && everyPricedEstimateIsLowerBound,
+ unpricedRequests,
+ unmeteredRequests,
+ };
+}
diff --git a/gui/tests/logs-priority-lower-bound.test.ts b/gui/tests/logs-priority-lower-bound.test.ts
new file mode 100644
index 0000000000..877252c07f
--- /dev/null
+++ b/gui/tests/logs-priority-lower-bound.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+import { DICTS } from "../src/i18n/catalogs";
+import { interpolate, type TFn } from "../src/i18n/shared";
+import {
+ formatEstimatedUsd,
+ formatEstimatedUsdValue,
+ summarizeEstimatedCosts,
+} from "../src/pages/logs-cost-format";
+
+function translator(locale: keyof typeof DICTS): TFn {
+ return (key, vars) => interpolate(DICTS[locale][key], vars);
+}
+
+const en = translator("en");
+const de = translator("de");
+
+describe("Logs priority lower-bound formatting", () => {
+ test("prefixes confirmed unpriced priority estimates with the lower-bound marker", () => {
+ expect(formatEstimatedUsdValue(1.6, en, "en-US", true)).toBe("≥$1.6000");
+ });
+
+ test("keeps ordinary standard-price estimates unchanged", () => {
+ expect(formatEstimatedUsdValue(1.6, en, "en-US", false)).toBe("~$1.6000");
+ });
+
+ test("uses locale-aware USD placement and separators", () => {
+ expect(formatEstimatedUsdValue(1.6, de, "de-DE", false)).toBe("ca. 1,6000\u00a0$");
+ });
+});
+
+describe("Logs table cost formatting", () => {
+ test("uses the shared value formatter for lower bounds, ordinary estimates, and unavailable costs", () => {
+ expect(formatEstimatedUsd({
+ kind: "value",
+ estimate: { cost: { total: 1.6 }, priorityLowerBound: true },
+ }, en, "en-US")).toBe("≥$1.6000");
+ expect(formatEstimatedUsd({
+ kind: "value",
+ estimate: { cost: { total: 1.6 } },
+ }, en, "en-US")).toBe("~$1.6000");
+ expect(formatEstimatedUsd({ kind: "unavailable" }, en, "en-US")).toBe("—");
+ expect(formatEstimatedUsdValue(Number.NaN, en, "en-US")).toBe("—");
+ });
+});
+
+describe("Logs conversation cost aggregation", () => {
+ test("does not mark a mixed ordinary and lower-bound total as a lower bound", () => {
+ const summary = summarizeEstimatedCosts([
+ {
+ usageStatus: "reported",
+ displayMetrics: {
+ cost: {
+ kind: "value",
+ estimate: { cost: { total: 1.6 }, priorityLowerBound: true },
+ },
+ },
+ },
+ {
+ usageStatus: "reported",
+ displayMetrics: {
+ cost: {
+ kind: "value",
+ estimate: { cost: { total: 0.4 } },
+ },
+ },
+ },
+ ]);
+
+ expect(summary.estimatedCostUsd).toBe(2);
+ expect(summary.priorityLowerBound).toBe(false);
+ });
+
+ test("marks a total as a lower bound only when every priced estimate is one", () => {
+ const summary = summarizeEstimatedCosts([
+ {
+ usageStatus: "reported",
+ displayMetrics: {
+ cost: {
+ kind: "value",
+ estimate: { cost: { total: 1.6 }, priorityLowerBound: true },
+ },
+ },
+ },
+ {
+ usageStatus: "reported",
+ displayMetrics: {
+ cost: {
+ kind: "value",
+ estimate: { cost: { total: 0.4 }, priorityLowerBound: true },
+ },
+ },
+ },
+ ]);
+
+ expect(summary.estimatedCostUsd).toBe(2);
+ expect(summary.priorityLowerBound).toBe(true);
+ });
+
+ test("does not mark an unpriced-only total as a lower bound", () => {
+ const summary = summarizeEstimatedCosts([
+ {
+ usageStatus: "reported",
+ displayMetrics: { cost: { kind: "unavailable" } },
+ },
+ ]);
+
+ expect(summary.estimatedCostUsd).toBe(0);
+ expect(summary.priorityLowerBound).toBe(false);
+ expect(summary.unpricedRequests).toBe(1);
+ });
+});
diff --git a/package.json b/package.json
index ae0571e503..ecb4a81645 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@bitkyc08/opencodex",
- "version": "2.26.0",
+ "version": "2.27.0",
"description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
"type": "module",
"main": "./bin/package-main.mjs",
diff --git a/src/adapters/anthropic.ts b/src/adapters/anthropic.ts
index fd141ccfb8..e012a78198 100644
--- a/src/adapters/anthropic.ts
+++ b/src/adapters/anthropic.ts
@@ -743,7 +743,7 @@ function toolsToAnthropicFormat(parsed: OcxParsedRequest, toolNames: { toWire: (
? new Set(parsed.options.toolChoice.allowedTools)
: undefined;
const tools = allowed
- ? parsed.context.tools.filter(t => toolAllowedByChoice(t, allowed))
+ ? parsed.context.tools.filter(t => toolAllowedByChoice(t, allowed, parsed.context.tools))
: parsed.context.tools;
if (tools.length === 0) return undefined;
const converted = tools.map(t => ({
diff --git a/src/adapters/base.ts b/src/adapters/base.ts
index bcdd657344..7d3a8be07b 100644
--- a/src/adapters/base.ts
+++ b/src/adapters/base.ts
@@ -39,8 +39,20 @@ export interface ProviderAdapter {
fetchResponse?(request: AdapterRequest, ctx?: AdapterFetchContext): Promise;
- parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator;
- parseResponse?(response: Response, budget: TranslatorBudget): Promise;
+ /**
+ * Parse one upstream response. `tierMetadata` is the same live observer returned on the
+ * corresponding AdapterRequest; adapters that receive a documented tier echo may update it.
+ */
+ parseStream(
+ response: Response,
+ budget: TranslatorBudget,
+ tierMetadata?: AdapterTierMetadata,
+ ): AsyncGenerator;
+ parseResponse?(
+ response: Response,
+ budget: TranslatorBudget,
+ tierMetadata?: AdapterTierMetadata,
+ ): Promise;
runTurn?(
parsed: OcxParsedRequest,
incoming: IncomingMeta,
diff --git a/src/adapters/command-code.ts b/src/adapters/command-code.ts
index 156ba5130a..8f2edbdb55 100644
--- a/src/adapters/command-code.ts
+++ b/src/adapters/command-code.ts
@@ -3,7 +3,7 @@ import { execFile as execFileCallback } from "node:child_process";
import { promisify } from "node:util";
import { opendir } from "node:fs/promises";
import type { AdapterEvent, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTool, OcxUsage } from "../types";
-import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice, toolChoiceAliases } from "../types";
+import { isAllowedToolChoice, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
import type { AdapterFetchContext, AdapterRequest, ProviderAdapter } from "./base";
import type { TranslatorBudget } from "../lib/translator-budget";
import { readBoundedResponseBody } from "../lib/bounded-body";
@@ -157,10 +157,11 @@ function visibleTools(parsed: OcxParsedRequest): OcxTool[] {
const tools = parsed.context.tools ?? [];
if (isAllowedToolChoice(choice)) {
const allowed = new Set(choice.allowedTools);
- return tools.filter(tool => toolAllowedByChoice(tool, allowed));
+ return tools.filter(tool => toolAllowedByChoice(tool, allowed, tools));
}
if (choice && typeof choice !== "string") {
- return tools.filter(tool => toolChoiceAliases(tool).includes(choice.name));
+ const selected = resolveToolChoiceWireName(tools, choice.name);
+ return tools.filter(tool => namespacedToolName(tool.namespace, tool.name) === selected);
}
return tools;
}
diff --git a/src/adapters/cursor/cursor-errors.ts b/src/adapters/cursor/cursor-errors.ts
index 294adc4a7c..f2e13c578c 100644
--- a/src/adapters/cursor/cursor-errors.ts
+++ b/src/adapters/cursor/cursor-errors.ts
@@ -85,6 +85,21 @@ export function isCursorBenignCancelError(value: unknown): boolean {
return false;
}
+/**
+ * True when the turn was torn down by an `AbortSignal` rather than by a transport fault.
+ *
+ * This is deliberately NOT part of `isCursorBenignCancelError`: an abort mid-turn is a real
+ * failure and must still surface. It is only meaningful in combination with a terminal frame
+ * having already been emitted, where it means "the answer landed and then the connection went
+ * away" (#1527).
+ */
+export function isCursorAbortError(value: unknown): boolean {
+ const message = errorMessage(value).toLowerCase();
+ if (message.includes("cursor request was aborted")) return true;
+ const name = (value as { name?: unknown })?.name;
+ return typeof name === "string" && name === "AbortError";
+}
+
/**
* True when Cursor Connect rejected the turn with invalid_argument.
* Seen after stepCompleted on brittle external-model continuations.
diff --git a/src/adapters/cursor/live-transport.ts b/src/adapters/cursor/live-transport.ts
index 3f8ce957a9..5775de025e 100644
--- a/src/adapters/cursor/live-transport.ts
+++ b/src/adapters/cursor/live-transport.ts
@@ -48,7 +48,7 @@ import {
type InteractionResponse,
} from "./gen/agent_pb";
import { debugProviderDiagnostic } from "../../lib/debug";
-import { classifyCursorError, CursorUnexpectedCancelError, isCursorBenignCancelError, safeCursorErrorMessage } from "./cursor-errors";
+import { classifyCursorError, CursorUnexpectedCancelError, isCursorAbortError, isCursorBenignCancelError, safeCursorErrorMessage } from "./cursor-errors";
import { mcpArgsFromToolCall } from "./protobuf-events";
import { OCX_RESPONSES_TOOL_PROVIDER } from "./tool-definitions";
import {
@@ -650,6 +650,18 @@ class LiveCursorTransport implements CursorTransport {
// A CANCEL is benign only on the client-tool suspend path (expectedClose); an
// unexpected server-side NGHTTP2_CANCEL must surface as a real transport error.
if (this.expectedClose && isCursorBenignCancelError(failure)) return;
+ // A teardown error arriving AFTER the turn's terminal frame describes the connection,
+ // not the turn: the answer is committed and every queued message has been yielded.
+ //
+ // Narrow on purpose. A benign cancel after a terminal is already swallowed one layer
+ // up (`cursor.ts:183`), so widening this to every post-terminal error would change
+ // what the adapter sees for genuine faults. What it does cover is the abort case
+ // from #1527: `signal.abort` fires `failAndClear(new Error("Cursor request was
+ // aborted"))`, which is NOT benign (`cursor-errors.ts:74`), so an ordinary completed
+ // turn that is then torn down still surfaced as `turn-failed` with
+ // `expectedClose:false`. Only `cancelCursorRun()` sets `expectedClose`, so a normal
+ // completion never qualified for the branch above.
+ if (this.emittedTerminal && isCursorAbortError(failure)) return;
throw attachPartialUsage(classifyTurnFailure(failure), state);
}
if (done) break;
@@ -659,6 +671,7 @@ class LiveCursorTransport implements CursorTransport {
}
if (failure) {
if (this.expectedClose && isCursorBenignCancelError(failure)) return;
+ if (this.emittedTerminal && isCursorAbortError(failure)) return;
throw attachPartialUsage(classifyTurnFailure(failure), state);
}
}
diff --git a/src/adapters/google.ts b/src/adapters/google.ts
index 9043d1f929..a3be021a76 100644
--- a/src/adapters/google.ts
+++ b/src/adapters/google.ts
@@ -262,7 +262,7 @@ function toolsToGeminiFormat(parsed: OcxParsedRequest): unknown[] | undefined {
? new Set(parsed.options.toolChoice.allowedTools)
: undefined;
const tools = allowed
- ? parsed.context.tools.filter(t => toolAllowedByChoice(t, allowed))
+ ? parsed.context.tools.filter(t => toolAllowedByChoice(t, allowed, parsed.context.tools))
: parsed.context.tools;
if (tools.length === 0) return undefined;
return [{
diff --git a/src/adapters/openai-chat.ts b/src/adapters/openai-chat.ts
index b93222d6ac..c5338d5eaa 100644
--- a/src/adapters/openai-chat.ts
+++ b/src/adapters/openai-chat.ts
@@ -19,6 +19,7 @@ import {
import {
canonicalFastTierMarker,
createAdapterTierMetadata,
+ type AdapterTierMetadata,
} from "../providers/fastwire";
import { openaiChatCompletionsUrl } from "./openai-chat-url";
import { stripResponsesOnlyEncryptedMarker } from "./responses-tool-schema";
@@ -1156,7 +1157,11 @@ function normalizeXaiToolParameters(parameters: unknown): Record key !== "oneOf" && key !== "anyOf" && key !== "type"));
+ const metadata = Object.fromEntries(Object.entries(normalizedRoot).filter(([key]) => key !== "oneOf" && key !== "anyOf" && key !== "type"));
delete metadata.properties;
delete metadata.required;
delete metadata.additionalProperties;
@@ -1180,6 +1185,7 @@ function normalizeXaiToolParameters(parameters: unknown): Record [name, mergeXaiPropertySchemas(values)]),
);
@@ -1196,7 +1202,7 @@ function normalizeXaiToolParameters(parameters: unknown): Record {
@@ -1478,7 +1484,11 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
};
},
- async *parseStream(response: Response, budget: TranslatorBudget): AsyncGenerator {
+ async *parseStream(
+ response: Response,
+ budget: TranslatorBudget,
+ tierMetadata?: AdapterTierMetadata,
+ ): AsyncGenerator {
if (!response.body) {
yield { type: "error", message: "No response body" };
return;
@@ -1547,11 +1557,15 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
try {
parsed = JSON.parse(payload);
} catch {
+ tierMetadata?.markResponseUnparseable();
yield { type: "error", message: "malformed upstream SSE data frame" };
return "terminate";
}
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return "continue";
const chunk = parsed as Record;
+ if (Object.hasOwn(chunk, "service_tier")) {
+ tierMetadata?.observeResponseServiceTier(chunk.service_tier);
+ }
if (chunk.error !== undefined && chunk.error !== null) {
const event = upstreamErrorEvent(chunk.error, pendingUsage);
@@ -1752,8 +1766,26 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
}
},
- async parseResponse(response: Response, budget: TranslatorBudget): Promise {
- const json = await response.json() as Record;
+ async parseResponse(
+ response: Response,
+ budget: TranslatorBudget,
+ tierMetadata?: AdapterTierMetadata,
+ ): Promise {
+ let parsed: unknown;
+ try {
+ parsed = await response.json();
+ } catch (error) {
+ tierMetadata?.markResponseUnparseable();
+ throw error;
+ }
+ if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+ tierMetadata?.markResponseUnparseable();
+ throw new Error("upstream response was not a JSON object");
+ }
+ const json = parsed as Record;
+ if (Object.hasOwn(json, "service_tier")) {
+ tierMetadata?.observeResponseServiceTier(json.service_tier);
+ }
const responseBytes = new TextEncoder().encode(JSON.stringify(json)).byteLength;
budget.chargeRetained(responseBytes, { kind: "retained_collectors" });
try {
diff --git a/src/adapters/tool-catalog-nudge.ts b/src/adapters/tool-catalog-nudge.ts
index 9325125691..626bd93d8d 100644
--- a/src/adapters/tool-catalog-nudge.ts
+++ b/src/adapters/tool-catalog-nudge.ts
@@ -135,7 +135,7 @@ export function buildNonOpenAIToolCatalogNudgeForTools(
toolChoice?: OcxRequestOptions["toolChoice"],
toWireName: (tool: Pick) => string = tool => namespacedToolName(tool.namespace, tool.name),
): string | undefined {
- const visible = tools?.filter(toolChoiceToolPredicate(toolChoice));
+ const visible = tools?.filter(toolChoiceToolPredicate(toolChoice, tools));
const visibleNames = visible?.map(toWireName);
// Decide code mode from the tool OBJECTS, while the `freeform` flag still exists — reducing
// to wire names first throws away the only thing that distinguishes Codex's JavaScript
diff --git a/src/bridge.ts b/src/bridge.ts
index e5621faa80..44745bd75f 100644
--- a/src/bridge.ts
+++ b/src/bridge.ts
@@ -167,7 +167,7 @@ export type ResponsesTerminalStatus = "completed" | "failed" | "incomplete";
export function bridgeToResponsesSSE(
events: AsyncIterable,
modelId: string,
- toolNsMap?: Map,
+ toolNsMap?: Map,
freeformToolNames?: Set,
toolSearchToolNames?: Set,
onCancel?: () => void,
@@ -1050,7 +1050,9 @@ export function bridgeToResponsesSSE(
}
const ns = mapped?.namespace;
const toolSearch = toolSearchToolNames?.has(realName) ?? false;
- const freeform = !toolSearch && (freeformToolNames?.has(realName) ?? false);
+ const freeform = !toolSearch && (mapped
+ ? mapped.freeform === true
+ : (freeformToolNames?.has(realName) ?? false));
const itemId = `${toolSearch ? "tsc" : freeform ? "ctc" : "fc"}_${uuid()}`;
const item = toolSearch
? { type: "tool_search_call", id: itemId, call_id: event.id, execution: "client", arguments: {}, status: "in_progress" }
@@ -1451,7 +1453,7 @@ function buildResponseJSONWithBudget(
modelId: string,
options?: {
hideThinkingSummary?: boolean;
- toolNsMap?: Map;
+ toolNsMap?: Map;
/** Request-visible tool names. When present, an upstream call outside this set fails closed. */
declaredToolNames?: ReadonlySet;
/** Declared parameter schema per tool name; repairs integral-float integer args (#1611). */
@@ -1632,7 +1634,9 @@ function buildResponseJSONWithBudget(
const realName = mapped?.name ?? currentToolCallName;
const ns = mapped?.namespace;
const toolSearch = options?.toolSearchToolNames?.has(realName) ?? false;
- const freeform = !toolSearch && (options?.freeformToolNames?.has(realName) ?? false);
+ const freeform = !toolSearch && (mapped
+ ? mapped.freeform === true
+ : (options?.freeformToolNames?.has(realName) ?? false));
// #1611: same integral-float repair as the streaming path. Keyed by the wire name
// the request declared, which is the pre-namespace-mapping `currentToolCallName`.
const coercedArgs = coerceIntegerToolArguments(
@@ -1796,7 +1800,9 @@ function buildResponseJSONWithBudget(
const mapped = options?.toolNsMap?.get(currentToolCallName);
const realName = mapped?.name ?? currentToolCallName;
const toolSearch = options?.toolSearchToolNames?.has(realName) ?? false;
- const freeform = !toolSearch && (options?.freeformToolNames?.has(realName) ?? false);
+ const freeform = !toolSearch && (mapped
+ ? mapped.freeform === true
+ : (options?.freeformToolNames?.has(realName) ?? false));
if (!freeform && !toolSearch) {
flushToolCall("incomplete");
errorEvent = {
diff --git a/src/cli/doctor.ts b/src/cli/doctor.ts
index 7962c06672..8af24a2693 100644
--- a/src/cli/doctor.ts
+++ b/src/cli/doctor.ts
@@ -25,6 +25,11 @@ import { collectOrcaCodexHomeDiagnostic, resolveCodexHomeDir as resolveCodexHome
import { scanCodexAgentRolesWithTomlModelFallback } from "../codex/subagent-model-fallback";
import { findCodexOnPath, isWindowsInteropDir } from "../codex/shim";
import { countPendingOpencodexHistory } from "../codex/history-provider";
+import {
+ inspectAbandonedResponseStateTemps,
+ reclaimAbandonedResponseStateTemps,
+ type ResponseStateTempRecoveryResult,
+} from "../responses/state";
import {
CodexUserIdentityRefusal,
probeCodexCoordinatorNamespace,
@@ -678,6 +683,57 @@ export async function fetchServiceMemory(
const mb = (bytes: number): string => `${Math.round(bytes / (1024 * 1024))}MB`;
+export const RECLAIM_RESPONSE_TEMPS_FLAG = "--reclaim-response-temps";
+/** Matches the dry run's entry bound so report and reclaim agree on a large backlog. */
+const RESPONSE_TEMP_RECLAIM_MAX_CLEANUPS = 4_096;
+/** Names the subsystem: other components mint temps with the same shape and are not covered. */
+const CLEAN_RESPONSE_TEMP_LINE = " ok No abandoned response-state temp files.";
+
+/**
+ * Render the abandoned-temp section (testable without console capture).
+ *
+ * Report is the DEFAULT and reclaim is opt-in: `doctor` is a diagnostic an operator runs
+ * to understand a machine, so deleting files as a side effect of asking a question is the
+ * wrong default even for cache files.
+ *
+ * Counts come from `eligible`/`eligibleBytes`, never `matched`: `matched` is incremented
+ * before the file-type, age, boot-floor, and liveness gates, so reporting it would tell an
+ * operator that live-pid temps and young temps are "abandoned".
+ */
+export function formatResponseTempLines(
+ result: ResponseStateTempRecoveryResult,
+ reclaimed: boolean,
+): string[] {
+ if (reclaimed) {
+ if (result.removed === 0 && result.failed === 0) return [CLEAN_RESPONSE_TEMP_LINE];
+ const lines = [` ok Reclaimed ${result.removed} abandoned response-state temp file(s), ${mb(result.bytesRemoved)} freed.`];
+ if (result.failed > 0) {
+ // Never "retried automatically": this command exists for the operator whose proxy will
+ // NOT start, and in that state nothing retries anything.
+ lines.push(` !! ${result.failed} file(s) could not be removed (in use or locked). Retried on the next reclaim — automatically while the proxy runs, otherwise re-run this command.`);
+ }
+ // `truncated`, not `eligible > removed + failed`: outside a dry run every eligible entry
+ // is unlinked or failed on the same iteration it is counted, so those two are always
+ // equal and the comparison never fired. An operator with a backlog past the budget was
+ // told the reclaim had finished.
+ if (result.truncated) {
+ lines.push(" !! Cleanup budget reached; files remain. Run the command again to continue.");
+ }
+ return lines;
+ }
+ if (result.eligible === 0) return [CLEAN_RESPONSE_TEMP_LINE];
+ const lines = [
+ ` !! ${result.eligible} abandoned response-state temp file(s), ${mb(result.eligibleBytes)} reclaimable.`,
+ " These are interrupted snapshot writes (continuation cache only) and are safe to remove.",
+ " Reclaim them with: ocx doctor --reclaim-response-temps",
+ ];
+ // The dry run skips the cleanup budget but is still bounded by the entry cap, so a large
+ // enough backlog makes this a floor rather than a total. Say so instead of letting an
+ // operator size the problem from a truncated count.
+ if (result.truncated) lines.push(" Scan stopped at its entry budget; the real total is higher.");
+ return lines;
+}
+
/** Render the doctor "Memory / runtime" section lines (testable without console capture). */
export function formatServiceMemoryLines(report: ServiceMemoryReport): string[] {
const lines: string[] = [];
@@ -805,6 +861,26 @@ export async function runDoctor(args: string[] = []): Promise {
console.log(` ${row.exists ? "ok " : "-- "} ${row.label}: ${row.path}${flags ? ` (${flags})` : ""}`);
}
+ // Runs without the proxy on purpose: the worst accumulation happens when the proxy will
+ // not start, which is exactly when the in-process periodic reclaim never ticks.
+ const reclaimTemps = args.includes(RECLAIM_RESPONSE_TEMPS_FLAG);
+ console.log("\nResponse-state temp files");
+ // A typo must not silently degrade into "nothing to reclaim" — the operator would read the
+ // report as an answer to a question they never actually asked.
+ for (const arg of args) {
+ if (arg !== RECLAIM_RESPONSE_TEMPS_FLAG && /^--reclaim/.test(arg)) {
+ console.log(` !! Unrecognized flag ${arg}; did you mean ${RECLAIM_RESPONSE_TEMPS_FLAG}? Reporting only.`);
+ }
+ }
+ for (const line of formatResponseTempLines(
+ // The reclaim budget matches the report budget: a report bounded by entries and a removal
+ // bounded by a smaller cleanup cap would tell an operator 816 and then silently free 512.
+ reclaimTemps
+ ? reclaimAbandonedResponseStateTemps({ maxCleanups: RESPONSE_TEMP_RECLAIM_MAX_CLEANUPS })
+ : inspectAbandonedResponseStateTemps(),
+ reclaimTemps,
+ )) console.log(line);
+
const orcaHome = collectOrcaCodexHomeDiagnostic();
console.log("\nCodex app home targeting");
console.log(` ${orcaHome.mismatch ? "!! " : "ok "} Effective Codex home: ${orcaHome.effectiveCodexHome}`);
diff --git a/src/cli/help.ts b/src/cli/help.ts
index 19843c2e01..c335c347b5 100644
--- a/src/cli/help.ts
+++ b/src/cli/help.ts
@@ -36,6 +36,8 @@ Usage:
Refresh Codex's model cache from the active catalog
ocx status Check proxy server status
ocx doctor Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
+ ocx doctor --reclaim-response-temps
+ Reclaim abandoned response-state temp files (works without a running proxy)
ocx debug provider/usage/injection/claude on|off|status|reset
ocx login OAuth or API-key provider login
ocx logout Remove a stored OAuth login
diff --git a/src/cli/models.ts b/src/cli/models.ts
index db4f20742d..a20ba18472 100644
--- a/src/cli/models.ts
+++ b/src/cli/models.ts
@@ -5,11 +5,11 @@ import { randomUUID } from "node:crypto";
import { createInterface } from "node:readline/promises";
import { syncModelsToCodex } from "../codex/sync";
import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
-import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort } from "../reasoning-effort";
+import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
import { encodedModelIdCollides, routedSlug, slugEquals } from "../providers/slug-codec";
import { knownModelIdsForProvider } from "../router";
import { findLiveProxy } from "../server/proxy-liveness";
-import type { OcxConfig, OcxCustomModel } from "../types";
+import { modelInList, type OcxConfig, type OcxCustomModel } from "../types";
const ADD_USAGE = "Usage: ocx models add [--display-name ] [--context-window ] [--modalities text,image,audio] [--reasoning-efforts ] [--default-reasoning-effort ]";
const REMOVE_USAGE = "Usage: ocx models remove [--yes]";
@@ -98,15 +98,22 @@ function collectModels(config: OcxConfig, providerFilter?: string): ModelEntry[]
if (seen.has(model)) return;
seen.add(model);
- const noVision = prov.noVisionModels?.includes(model);
- const modalities = inputModalities[model] ?? (noVision ? ["text"] : null);
- const efforts = reasoningEfforts[model] ?? prov.reasoningEfforts ?? null;
+ // Resolve exactly as the runtime does, or this command reports capabilities the
+ // proxy will not honour: `isModelTextOnly` matches noVisionModels with modelInList
+ // and reads modelInputModalities with modelRecordValue, so a `gpt-oss` entry covers
+ // `gpt-oss:120b`. A bare lookup reported that model as unclassified on every field.
+ // noVisionModels is checked first because `isModelTextOnly` returns true on that
+ // match before it ever reads modelInputModalities: a `gpt-oss` noVision entry beats
+ // an exact `gpt-oss:120b` entry that lists "image", and the proxy rejects the image.
+ const noVision = modelInList(prov.noVisionModels, model);
+ const modalities = noVision ? ["text"] : (modelRecordValue(inputModalities, model) ?? null);
+ const efforts = modelRecordValue(reasoningEfforts, model) ?? prov.reasoningEfforts ?? null;
entries.push({
provider: provName,
model,
isDefault,
- contextWindow: contextWindows[model] ?? globalContext,
+ contextWindow: modelRecordValue(contextWindows, model) ?? globalContext,
inputModalities: modalities,
reasoningEfforts: efforts,
});
diff --git a/src/codex/app-server-processes.ts b/src/codex/app-server-processes.ts
index c70c3af5c5..8d51d8efa9 100644
--- a/src/codex/app-server-processes.ts
+++ b/src/codex/app-server-processes.ts
@@ -7,7 +7,7 @@
* Never match broad `*codex*` patterns that hit unrelated tools such as
* `hermes-codex-bridge-mcp`.
*/
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync, type ExecFileException } from "node:child_process";
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { isProcessAlive, waitForExit } from "../lib/process-control";
import {
@@ -98,9 +98,30 @@ export interface CodexAppServerProcessIo {
waitExit?: (pid: number, timeoutMs: number) => boolean;
now?: () => number;
readStartMs?: (pid: number) => number | null;
+ /** Async process-list seam used by the request-path Windows collector. */
+ listSnapshotsAsync?: () => Promise;
+ /** Async batch start-time seam used by the request-path Windows collector. */
+ readStartMsBatchAsync?: (pids: readonly number[]) => Promise>;
catalogMtimeMs?: () => number | null;
}
+function execFileTextAsync(
+ file: string,
+ args: readonly string[],
+ timeoutMs: number,
+): Promise {
+ return new Promise((resolve, reject) => {
+ execFile(file, [...args], {
+ encoding: "utf-8",
+ timeout: timeoutMs,
+ windowsHide: true,
+ }, (error: ExecFileException | null, stdout: string) => {
+ if (error) reject(error);
+ else resolve(stdout);
+ });
+ });
+}
+
/** Split a process command line into argv-like tokens (handles simple quotes). */
export function tokenizeCommandLine(commandLine: string): string[] {
const tokens: string[] = [];
@@ -375,7 +396,7 @@ export function parseWindowsSnapshotOutput(output: string): ProcessSnapshot[] {
return out;
}
-export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => string): ProcessSnapshot[] {
+function windowsSnapshotPowerShellCommand(): string {
// Newlines keep -Command as a real script (space-joined statements need ';').
// Double-quoted format string so `t expands to a real tab.
// Codex candidates only: basename token codex / codex.exe / codex.cmd /
@@ -384,7 +405,7 @@ export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => stri
// path with "opencodex".
const basenameMatch = powerShellSingleQuotedIgnoreCaseMatch(WINDOWS_CODEX_BASENAME_CANDIDATE_RE.source);
const codeModeMatch = powerShellSingleQuotedIgnoreCaseMatch(WINDOWS_CODEX_CODE_MODE_HOST_CANDIDATE_RE.source);
- const psCommand = [
+ return [
"$ErrorActionPreference='SilentlyContinue'",
"$me=[System.Security.Principal.WindowsIdentity]::GetCurrent().Name",
// -ErrorAction Stop plus the outer try is what makes a TOP-LEVEL query failure
@@ -412,9 +433,13 @@ export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => stri
"}",
"} catch { \"__OCX_ENUM_INCOMPLETE__\" }",
].join("\n");
+}
+
+export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => string): ProcessSnapshot[] {
// Top-level exec failure propagates (see listDarwinSnapshots note). The
// executable resolves from the trusted System32 directory (never PATH), and
// windowsHide keeps the enumeration console-less on desktop sessions (#1278).
+ const psCommand = windowsSnapshotPowerShellCommand();
const output = runPowerShell
? runPowerShell(psCommand)
: execFileSync(resolveTrustedWindowsPowerShellExe(), [
@@ -425,6 +450,15 @@ export function listWindowsSnapshots(runPowerShell?: (psCommand: string) => stri
return parseWindowsSnapshotOutput(output);
}
+async function listWindowsSnapshotsAsync(): Promise {
+ const output = await execFileTextAsync(resolveTrustedWindowsPowerShellExe(), [
+ "-NoProfile", "-NoLogo", "-NonInteractive",
+ "-Command",
+ windowsSnapshotPowerShellCommand(),
+ ], 8_000);
+ return parseWindowsSnapshotOutput(output);
+}
+
function defaultListSnapshots(platform: NodeJS.Platform, getuid: () => number | undefined): ProcessSnapshot[] {
if (platform === "win32") return listWindowsSnapshots();
if (platform === "darwin") return listDarwinSnapshots(getuid());
@@ -533,6 +567,41 @@ export function readProcessStartMs(pid: number, platform: NodeJS.Platform = proc
return readLinuxProcStartMs(pid);
}
+function windowsProcessStartPowerShellCommand(pids: readonly number[]): string {
+ const filter = pids.map(pid => `ProcessId=${pid}`).join(" OR ");
+ return `Get-CimInstance Win32_Process -Filter "${filter}" | ForEach-Object { "$($_.ProcessId)\t$($_.CreationDate.ToUniversalTime().ToString("o"))" }`;
+}
+
+function parseWindowsProcessStartTimes(
+ stdout: string,
+ pids: readonly number[],
+): Map {
+ const byPid = new Map();
+ for (const line of stdout.split(/\r?\n/)) {
+ const tab = line.indexOf("\t");
+ if (tab <= 0) continue;
+ const pid = Number(line.slice(0, tab));
+ const parsed = Date.parse(line.slice(tab + 1).trim());
+ if (Number.isSafeInteger(pid) && Number.isFinite(parsed)) byPid.set(pid, parsed);
+ }
+ return new Map(pids.map(pid => [pid, byPid.get(pid) ?? null]));
+}
+
+async function readWindowsProcessStartMsBatchAsync(
+ pids: readonly number[],
+): Promise> {
+ try {
+ const stdout = await execFileTextAsync(resolveTrustedWindowsPowerShellExe(), [
+ "-NoProfile", "-NoLogo", "-NonInteractive",
+ "-Command",
+ windowsProcessStartPowerShellCommand(pids),
+ ], 5_000);
+ return parseWindowsProcessStartTimes(stdout, pids);
+ } catch {
+ return new Map(pids.map(pid => [pid, null]));
+ }
+}
+
/**
* Start times for many pids in ONE platform call where possible, so the
* staleness check does not serialize per-process ps/PowerShell invocations
@@ -568,22 +637,12 @@ export function readProcessStartMsBatch(
}
if (platform === "win32") {
try {
- const filter = pids.map(pid => `ProcessId=${pid}`).join(" OR ");
const stdout = execFileSync(resolveTrustedWindowsPowerShellExe(), [
"-NoProfile", "-NoLogo", "-NonInteractive",
"-Command",
- `Get-CimInstance Win32_Process -Filter "${filter}" | ForEach-Object { "$($_.ProcessId)\t$($_.CreationDate.ToUniversalTime().ToString("o"))" }`,
+ windowsProcessStartPowerShellCommand(pids),
], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5_000, windowsHide: true });
- const byPid = new Map();
- for (const line of stdout.split(/\r?\n/)) {
- const tab = line.indexOf("\t");
- if (tab <= 0) continue;
- const pid = Number(line.slice(0, tab));
- const parsed = Date.parse(line.slice(tab + 1).trim());
- if (Number.isSafeInteger(pid) && Number.isFinite(parsed)) byPid.set(pid, parsed);
- }
- for (const pid of pids) out.set(pid, byPid.get(pid) ?? null);
- return out;
+ return parseWindowsProcessStartTimes(stdout, pids);
} catch {
for (const pid of pids) out.set(pid, null);
return out;
@@ -610,9 +669,65 @@ function defaultCatalogMtimeMs(): number | null {
}
}
+function codexAppServerProcessesFromSnapshots(
+ snapshots: readonly ProcessSnapshot[],
+): CodexAppServerProcess[] {
+ const processes: CodexAppServerProcess[] = [];
+ const seen = new Set();
+ for (const snapshot of snapshots) {
+ if (seen.has(snapshot.pid)) continue;
+ if (!isCodexAppServerCommandLine(snapshot.commandLine, snapshot.executable)) continue;
+ seen.add(snapshot.pid);
+ processes.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
+ }
+ return processes;
+}
+
+function catalogStatusFromProcesses(
+ processes: readonly CodexAppServerProcess[],
+ catalogMtimeMs: number | null,
+ starts: ReadonlyMap,
+): CodexAppServerCatalogStatus {
+ const withStarts = processes.map(proc => ({
+ pid: proc.pid,
+ startedAtMs: starts.get(proc.pid) ?? null,
+ }));
+ if (catalogMtimeMs === null || withStarts.some(proc => proc.startedAtMs === null)) {
+ return { state: "unknown", processes: withStarts, catalogMtimeMs };
+ }
+ // `<=` is deliberate: coarse clocks (ps lstart is second-granularity) can
+ // report equal values when the catalog actually changed after startup.
+ const stale = withStarts.some(proc => proc.startedAtMs! <= catalogMtimeMs);
+ return { state: stale ? "stale" : "fresh", processes: withStarts, catalogMtimeMs };
+}
+
// Short TTL: process listing + stat run once per window even under per-turn
// guidance calls (#857).
let catalogStateCache: { atMs: number; status: CodexAppServerCatalogStatus } | null = null;
+interface RequestCatalogStateIdentity {
+ platform: NodeJS.Platform;
+ listSnapshots?: CodexAppServerProcessIo["listSnapshots"];
+ listSnapshotsAsync?: CodexAppServerProcessIo["listSnapshotsAsync"];
+ readStartMs?: CodexAppServerProcessIo["readStartMs"];
+ readStartMsBatchAsync?: CodexAppServerProcessIo["readStartMsBatchAsync"];
+ catalogMtimeMs?: CodexAppServerProcessIo["catalogMtimeMs"];
+ now?: CodexAppServerProcessIo["now"];
+}
+
+interface RequestCatalogStateFlight {
+ generation: number;
+ identity: RequestCatalogStateIdentity;
+ promise: Promise;
+}
+
+let requestCatalogStateGeneration = 0;
+let requestCatalogStateCache: {
+ generation: number;
+ identity: RequestCatalogStateIdentity;
+ atMs: number;
+ status: CodexAppServerCatalogStatus;
+} | null = null;
+let requestCatalogStateFlight: RequestCatalogStateFlight | null = null;
const CATALOG_STATE_TTL_MS = 5_000;
/**
* `unknown` is a failure to observe, not an observation, so it gets a much shorter
@@ -627,6 +742,19 @@ export function catalogStateTtlMs(state: CodexAppServerCatalogState): number {
return state === "unknown" ? CATALOG_STATE_UNKNOWN_TTL_MS : CATALOG_STATE_TTL_MS;
}
+function sameRequestCatalogStateIdentity(
+ left: RequestCatalogStateIdentity,
+ right: RequestCatalogStateIdentity,
+): boolean {
+ return left.platform === right.platform
+ && left.listSnapshots === right.listSnapshots
+ && left.listSnapshotsAsync === right.listSnapshotsAsync
+ && left.readStartMs === right.readStartMs
+ && left.readStartMsBatchAsync === right.readStartMsBatchAsync
+ && left.catalogMtimeMs === right.catalogMtimeMs
+ && left.now === right.now;
+}
+
/**
* Compare the on-disk catalog mtime against the start time of running Codex
* app-servers (#857): a server that started before the catalog changed keeps
@@ -676,33 +804,17 @@ export function collectCodexAppServerCatalogState(
snapshots = [];
enumerationFailed = true;
}
- const processes: CodexAppServerProcess[] = [];
- const seen = new Set();
- for (const snapshot of snapshots) {
- if (seen.has(snapshot.pid)) continue;
- if (!isCodexAppServerCommandLine(snapshot.commandLine, snapshot.executable)) continue;
- seen.add(snapshot.pid);
- processes.push({ pid: snapshot.pid, commandLine: snapshot.commandLine });
- }
+ const processes = codexAppServerProcessesFromSnapshots(snapshots);
if (processes.length === 0) {
return enumerationFailed
? { state: "unknown", processes: [], catalogMtimeMs: null }
: { state: "not_running", processes: [], catalogMtimeMs: null };
}
const catalogMtimeMs = (io.catalogMtimeMs ?? defaultCatalogMtimeMs)();
- const withStarts = io.readStartMs
- ? processes.map(proc => ({ pid: proc.pid, startedAtMs: io.readStartMs!(proc.pid) }))
- : (() => {
- const batch = readProcessStartMsBatch(processes.map(proc => proc.pid), platform);
- return processes.map(proc => ({ pid: proc.pid, startedAtMs: batch.get(proc.pid) ?? null }));
- })();
- if (catalogMtimeMs === null || withStarts.some(proc => proc.startedAtMs === null)) {
- return { state: "unknown", processes: withStarts, catalogMtimeMs };
- }
- // `<=` is deliberate: coarse clocks (ps lstart is second-granularity) can
- // report equal values when the catalog actually changed after startup.
- const stale = withStarts.some(proc => proc.startedAtMs! <= catalogMtimeMs);
- return { state: stale ? "stale" : "fresh", processes: withStarts, catalogMtimeMs };
+ const starts = io.readStartMs
+ ? new Map(processes.map(proc => [proc.pid, io.readStartMs!(proc.pid)] as const))
+ : readProcessStartMsBatch(processes.map(proc => proc.pid), platform);
+ return catalogStatusFromProcesses(processes, catalogMtimeMs, starts);
};
const status = compute();
if (fullyDefault) {
@@ -711,9 +823,129 @@ export function collectCodexAppServerCatalogState(
return status;
}
-/** Test hook: drop the memoized catalog state. */
+/**
+ * Request-path catalog state collector.
+ *
+ * [Decision Log]
+ * - 목적과 의도: keep Windows CIM discovery from blocking Bun's event loop while v2 guidance is built.
+ * - 기존 구현 및 제약 조건: CLI/service operations still need the synchronous, fail-closed collector; the request path needs only advisory state.
+ * - 검토한 주요 대안: remove stale-catalog guidance, move all process work to workers, or add a Windows-only async boundary.
+ * - 선택한 방식: retain the synchronous API and use async PowerShell plus an identity-scoped in-flight refresh, short cache, and invalidation generation only for Windows requests.
+ * - 다른 대안 대신 이 방식을 선택한 이유: it fixes unrelated `/healthz` starvation without widening the process-matching or restart contract.
+ * - 장점, 단점 및 영향: concurrent turns share one CIM walk, invalidated pre-write results cannot repopulate the cache, and the event loop stays responsive; a cold v2 turn can still await the bounded advisory probe.
+ */
+export async function collectCodexAppServerCatalogStateForRequest(
+ io: CodexAppServerProcessIo = {},
+): Promise {
+ const platform = io.platform ?? process.platform;
+ if (platform !== "win32") return collectCodexAppServerCatalogState(io);
+
+ const now = (io.now ?? Date.now)();
+ const generation = requestCatalogStateGeneration;
+ const identity: RequestCatalogStateIdentity = {
+ platform,
+ listSnapshots: io.listSnapshots,
+ listSnapshotsAsync: io.listSnapshotsAsync,
+ readStartMs: io.readStartMs,
+ readStartMsBatchAsync: io.readStartMsBatchAsync,
+ catalogMtimeMs: io.catalogMtimeMs,
+ now: io.now,
+ };
+ if (requestCatalogStateCache
+ && requestCatalogStateCache.generation === generation
+ && sameRequestCatalogStateIdentity(requestCatalogStateCache.identity, identity)
+ && now - requestCatalogStateCache.atMs < catalogStateTtlMs(requestCatalogStateCache.status.state)) {
+ return requestCatalogStateCache.status;
+ }
+ if (requestCatalogStateFlight
+ && requestCatalogStateFlight.generation === generation
+ && sameRequestCatalogStateIdentity(requestCatalogStateFlight.identity, identity)) {
+ return requestCatalogStateFlight.promise;
+ }
+
+ const refresh = async (): Promise => {
+ let snapshots: ProcessSnapshot[];
+ try {
+ snapshots = io.listSnapshotsAsync
+ ? await io.listSnapshotsAsync()
+ : io.listSnapshots
+ ? io.listSnapshots()
+ : await listWindowsSnapshotsAsync();
+ } catch {
+ return { state: "unknown", processes: [], catalogMtimeMs: null };
+ }
+ const processes = codexAppServerProcessesFromSnapshots(snapshots);
+ if (processes.length === 0) {
+ return { state: "not_running", processes: [], catalogMtimeMs: null };
+ }
+ let catalogMtimeMs: number | null;
+ try {
+ catalogMtimeMs = (io.catalogMtimeMs ?? defaultCatalogMtimeMs)();
+ } catch {
+ catalogMtimeMs = null;
+ }
+ const pids = processes.map(proc => proc.pid);
+ const starts = io.readStartMsBatchAsync
+ ? await io.readStartMsBatchAsync(pids)
+ : io.readStartMs
+ ? new Map(pids.map(pid => [pid, io.readStartMs!(pid)] as const))
+ : await readWindowsProcessStartMsBatchAsync(pids);
+ return catalogStatusFromProcesses(processes, catalogMtimeMs, starts);
+ };
+
+ const pending = refresh().catch(() => ({
+ state: "unknown" as const,
+ processes: [],
+ catalogMtimeMs: null,
+ }));
+ let flight: RequestCatalogStateFlight;
+ const promise = pending.then(status => {
+ // A catalog write can invalidate while slow CIM is still running. The result
+ // describes the PRE-write world, so it must neither repopulate the post-write
+ // cache nor reach the caller.
+ //
+ // Suppressing only the cache write is not enough. The awaiting request still
+ // received `fresh`, and `fresh` is the one state that authorizes positive
+ // guidance (`src/server/responses/collaboration.ts:279-280` returns null for
+ // `stale`/`unknown` but describes the catalog for `fresh`). So the request
+ // would advertise the newly written disk catalog to an app-server whose
+ // in-memory copy the write just made stale — a wrong answer, which is worse
+ // than the slow answer this whole change exists to fix.
+ //
+ // Degrade to `unknown` instead: it is the honest description of what an
+ // invalidated observation knows, and the guidance path already treats it as
+ // "say nothing positive".
+ if (requestCatalogStateGeneration !== generation) {
+ return { state: "unknown" as const, processes: [], catalogMtimeMs: null };
+ }
+ if (requestCatalogStateFlight === flight) {
+ requestCatalogStateCache = {
+ generation,
+ identity,
+ atMs: (io.now ?? Date.now)(),
+ status,
+ };
+ }
+ return status;
+ }).finally(() => {
+ if (requestCatalogStateFlight === flight) requestCatalogStateFlight = null;
+ });
+ flight = { generation, identity, promise };
+ requestCatalogStateFlight = flight;
+ return flight.promise;
+}
+
+/**
+ * Drop memoized catalog state after a relevant catalog/cache write and before
+ * the post-write state read. Advancing the generation prevents an older
+ * in-flight Windows CIM refresh from publishing its pre-write result after the
+ * write has completed.
+ */
export function resetCodexAppServerCatalogStateCache(): void {
catalogStateCache = null;
+ requestCatalogStateGeneration += 1;
+ requestCatalogStateCache = null;
+ requestCatalogStateFlight = null;
}
export interface RestartCodexAppServersResult {
diff --git a/src/codex/auth-context.ts b/src/codex/auth-context.ts
index b74ef0bfa4..1f8b120112 100644
--- a/src/codex/auth-context.ts
+++ b/src/codex/auth-context.ts
@@ -12,7 +12,8 @@ import { ConfigMutationLockError } from "../config";
import { isCodexAccountUsable } from "./account-usability";
import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken, isMainAccountTokenLive } from "./main-account";
-import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+import { isNativeMainTrafficBlocked, nativeMainStartupGateSnapshot } from "./native-profile-startup";
+import type { NativeMainStartupBlockReason } from "./native-profile-startup";
import {
codexQuotaScopeForModel,
getCodexQuotaHealthSnapshot,
@@ -116,12 +117,63 @@ export const CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE =
"OpenCodex local native-main profile maintenance is active; retry this request";
export class CodexMainProfileDrainingError extends Error {
+ /**
+ * Which startup-gate state fenced this request, when one did. Undefined means the
+ * fence came from somewhere other than the startup gate — the turn-drain claim race
+ * throws this same error while the gate reads `ready`, and inventing a reason there
+ * would point the next report at a gate that never closed.
+ *
+ * Captured here rather than at the throw sites because this is the last moment it is
+ * both in scope and still true: every catch site has already lost it, and re-reading
+ * the gate later can observe a recovery that completed in between (#2108).
+ */
+ readonly reason?: NativeMainStartupBlockReason;
+
constructor() {
super(CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
this.name = "CodexMainProfileDrainingError";
+ const gate = nativeMainStartupGateSnapshot();
+ if (gate.status !== "blocked") return;
+ this.reason = gate.reason;
+ reportNativeMainFenceReason(gate.reason);
}
}
+/**
+ * #2108: a reboot could leave this fence closed until `ocx restart`, and the report was
+ * unactionable because the settled reason was never written anywhere. It cannot ride the
+ * message (claude-messages.ts matches that string exactly to keep the fence a 503 rather
+ * than an Anthropic 529) and it cannot ride a header (/api/logs reads only error.message
+ * from the body, and the Claude surface rebuilds its response headers from scratch), so
+ * stdout is the one surface that covers every path this fence fires on.
+ *
+ * Deduped per distinct reason: the original report shows three 503s in eleven seconds and
+ * a real client retries harder than that, so a per-request line would bury the signal.
+ * Only the reason is emitted; the snapshot's homeId is derived from a profile directory.
+ */
+const reportedFenceReasons = new Set();
+
+function reportNativeMainFenceReason(reason: NativeMainStartupBlockReason): void {
+ if (reportedFenceReasons.has(reason)) return;
+ reportedFenceReasons.add(reason);
+ console.warn(
+ `native-main admission is fenced (reason: ${reason}); native model requests return 503 until it clears`,
+ );
+}
+
+/**
+ * Test-only reset for the dedup set above.
+ *
+ * The dedup is process-lifetime module state, so it is order-sensitive across test files
+ * sharing one Bun process: whichever file constructs this error first consumes the one-shot
+ * warn, and a later file asserting on it would see nothing and pass vacuously. Any test that
+ * asserts on the warn must call this first — an `afterEach` in the asserting file is not
+ * enough on its own, because the consuming file may not be the asserting one.
+ */
+export function __resetNativeMainFenceReasonLog(): void {
+ reportedFenceReasons.clear();
+}
+
export function codexMainProfileDrainingResponse(): Response {
const response = formatErrorResponse(503, "server_busy", CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
const headers = new Headers(response.headers);
diff --git a/src/codex/catalog/aggregation.ts b/src/codex/catalog/aggregation.ts
index a4736ab4b0..a605534227 100644
--- a/src/codex/catalog/aggregation.ts
+++ b/src/codex/catalog/aggregation.ts
@@ -183,6 +183,9 @@ export function deriveComboCatalogModel(
? { supportsServiceTier: false }
: {}),
...(members.some(member => member.supportsReasoningSummaries === false) ? { supportsReasoningSummaries: false } : {}),
+ ...(members.every(member => member.codexToolMode === "shell")
+ ? { codexToolMode: "shell" as const }
+ : {}),
};
}
diff --git a/src/codex/catalog/parsing.ts b/src/codex/catalog/parsing.ts
index f42049150e..0d1b2c2aaa 100644
--- a/src/codex/catalog/parsing.ts
+++ b/src/codex/catalog/parsing.ts
@@ -126,6 +126,12 @@ export interface CatalogModel {
/** Whether this exact routed model has a verified OpenAI-compatible service tier. */
supportsServiceTier?: boolean;
supportsReasoningSummaries?: boolean;
+ /**
+ * Codex tool calling mode for this routed model.
+ * "code_mode_only" (default) sets entry.tool_mode = "code_mode_only".
+ * "shell" leaves tool_mode unset so Codex declares top-level shell tools (exec_command).
+ */
+ codexToolMode?: "code_mode_only" | "shell";
/** Normalized upstream capability names retained for management/API consumers (#485 follow-up). */
capabilities?: string[];
/** OpenCodex-only catalog ownership marker; Codex ignores the serialized extension field. */
@@ -423,7 +429,14 @@ export function catalogEntryIsNativeChatGpt(entry: RawEntry): boolean {
export const ROUTED_CODEX_TOOL_MODE = "code_mode_only";
-export function applyRoutedCodexToolMode(entry: RawEntry): RawEntry {
+export function applyRoutedCodexToolMode(
+ entry: RawEntry,
+ toolMode?: "code_mode_only" | "shell" | string,
+): RawEntry {
+ if (toolMode === "shell") {
+ delete entry.tool_mode;
+ return entry;
+ }
entry.tool_mode = ROUTED_CODEX_TOOL_MODE;
return entry;
}
@@ -490,10 +503,14 @@ export function applyMultiAgentMode(
return entries;
}
-export function normalizeRoutedCatalogEntry(entry: RawEntry, parallelToolCalls = false): RawEntry {
+export function normalizeRoutedCatalogEntry(
+ entry: RawEntry,
+ parallelToolCalls = false,
+ toolMode?: "code_mode_only" | "shell" | string,
+): RawEntry {
delete entry.model_messages;
delete entry.tool_mode;
- applyRoutedCodexToolMode(entry);
+ applyRoutedCodexToolMode(entry, toolMode);
delete entry.multi_agent_version;
delete entry.use_responses_lite;
delete entry.supports_websockets;
diff --git a/src/codex/catalog/provider-fetch.ts b/src/codex/catalog/provider-fetch.ts
index 93d36ac8ae..9c3384b4e3 100644
--- a/src/codex/catalog/provider-fetch.ts
+++ b/src/codex/catalog/provider-fetch.ts
@@ -413,6 +413,7 @@ function captureProviderGather(
name,
provider,
registryTransportMatch,
+ configured,
);
const observedAuth = authResolver.kind === "observed"
&& provider.authMode !== "forward"
@@ -676,6 +677,7 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
...(prov.parallelToolCalls === true || (prov.adapter === "openai-chat" && prov.parallelToolCalls !== false)
? { parallelToolCalls: true }
: {}),
+ ...(prov.codexToolMode !== undefined ? { codexToolMode: prov.codexToolMode } : {}),
};
const capped = applyProviderContextCap(hinted.contextWindow, providerCap);
if (providerCap !== undefined && capped !== hinted.contextWindow) {
@@ -1881,6 +1883,11 @@ async function gatherRoutedModelsUncached(
...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
+ ...(cm.codexToolMode !== undefined
+ ? { codexToolMode: cm.codexToolMode }
+ : effectiveProvider?.codexToolMode !== undefined
+ ? { codexToolMode: effectiveProvider.codexToolMode }
+ : {}),
};
// #962: the dedupe below drops the provider-derived row this custom row replaces. Inherit that
// row's provider capability metadata (reasoning ladder, default effort, parallel tool calls,
@@ -1905,6 +1912,7 @@ async function gatherRoutedModelsUncached(
...(base.parallelToolCalls === undefined && replaced.parallelToolCalls !== undefined ? { parallelToolCalls: replaced.parallelToolCalls } : {}),
...(base.supportsVerbosity === undefined && replaced.supportsVerbosity !== undefined ? { supportsVerbosity: replaced.supportsVerbosity } : {}),
...(base.supportsReasoningSummaries === undefined && replaced.supportsReasoningSummaries !== undefined ? { supportsReasoningSummaries: replaced.supportsReasoningSummaries } : {}),
+ ...(base.codexToolMode === undefined && replaced.codexToolMode !== undefined ? { codexToolMode: replaced.codexToolMode } : {}),
...(base.capabilities === undefined && replaced.capabilities !== undefined ? { capabilities: replaced.capabilities } : {}),
} : base;
// Vision-sidecar coverage ONLY: if the custom model is in the enriched provider's
diff --git a/src/codex/catalog/sync.ts b/src/codex/catalog/sync.ts
index 5d833e2c17..1167bacc27 100644
--- a/src/codex/catalog/sync.ts
+++ b/src/codex/catalog/sync.ts
@@ -331,7 +331,9 @@ export function deriveEntry(
// This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
// native tool/search/responses-lite contract while preserving the routed slug and wire id.
if (!codexForwardNativeCapabilityAlias) {
- normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true);
+ normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true, model?.codexToolMode);
+ } else if (model?.codexToolMode !== undefined) {
+ applyRoutedCodexToolMode(e, model.codexToolMode);
}
if (model) applyCatalogMetadata(e, model.provider, model.id, model.contextCap);
applyCatalogModelMetadata(e, model);
@@ -358,8 +360,8 @@ export function deriveEntry(
});
}
// Fallback when no template is available (best-effort; strict parser may need more).
- // All routed fallbacks enable deferred code-mode tool exposure; otherwise the nested catalog
- // expands into `exec.description` and can exceed Cursor's 120 KB serialized tool limit (#1830).
+ // Routed fallbacks default to code-mode tool exposure (or shell mode when codexToolMode === "shell");
+ // otherwise the nested catalog expands into `exec.description` and can exceed Cursor's 120 KB serialized tool limit (#1830).
// Cursor still omits hosted web-search metadata because runTurn bypasses that separate sidecar.
const isCursorFallback = isRouted && model?.provider === "cursor";
const entry: RawEntry = {
@@ -373,7 +375,7 @@ export function deriveEntry(
: {}),
};
if (isRouted) {
- applyRoutedCodexToolMode(entry);
+ applyRoutedCodexToolMode(entry, model?.codexToolMode);
applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExact);
}
else {
diff --git a/src/codex/log-guard/path-safety.ts b/src/codex/log-guard/path-safety.ts
index e1f0ee0736..6dabd1dd7d 100644
--- a/src/codex/log-guard/path-safety.ts
+++ b/src/codex/log-guard/path-safety.ts
@@ -1,5 +1,5 @@
-import { realpathSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { lstatSync, realpathSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
import { samePathIdentity } from "../user-identity";
@@ -35,5 +35,54 @@ export function normalizeTrustedDarwinSystemAlias(path: string): string {
* Arbitrary ancestor symlinks remain refused.
*/
export function sameLogGuardPathIdentity(realPath: string, requestedPath: string): boolean {
- return samePathIdentity(realPath, normalizeTrustedDarwinSystemAlias(requestedPath));
+ const requested = normalizeTrustedDarwinSystemAlias(requestedPath);
+ if (samePathIdentity(realPath, requested)) return true;
+ return sameWindowsCanonicalPath(realPath, requested);
+}
+
+/**
+ * On Windows, is the difference between these two spellings the OS canonicalizing the
+ * request rather than a redirection?
+ *
+ * `realpathSync.native` expands 8.3 short components — the `RUNNER~1` form that appears
+ * throughout `%TEMP%` — so the canonical path and the requested path can disagree as
+ * strings while naming the same file. Reading that as an ancestor-symlink redirection made
+ * every Log Guard mutation refuse with `unsafe_path` on Windows, which is what the CI shards
+ * were reporting.
+ *
+ * The first version of this re-canonicalized the requested path and compared the two
+ * canonical forms. That was wrong, and the Windows shard proved it: the caller already
+ * passes `realpathSync.native(requested)` as `realPath`, so re-resolving the request
+ * produced the same value on BOTH sides and a symlinked database compared equal. The
+ * widening let through exactly what the guard exists to refuse.
+ *
+ * The comparison is therefore link-aware. A short-name expansion rewrites the spelling of
+ * components that are all still directories on the same chain, so it is enough to require
+ * that no component of the request is a link: with none present, any remaining difference
+ * is the OS's own canonical spelling. A symlink or junction anywhere in the chain fails
+ * closed as before.
+ */
+function sameWindowsCanonicalPath(realPath: string, requestedPath: string): boolean {
+ if (process.platform !== "win32") return false;
+ try {
+ if (pathChainContainsLink(requestedPath)) return false;
+ return samePathIdentity(realPath, realpathSync.native(requestedPath));
+ } catch {
+ return false;
+ }
+}
+
+/** Is any component of this path a symlink or junction? Fails closed on an unreadable one. */
+function pathChainContainsLink(path: string): boolean {
+ let current = resolve(path);
+ for (;;) {
+ try {
+ if (lstatSync(current).isSymbolicLink()) return true;
+ } catch {
+ return true;
+ }
+ const parent = dirname(current);
+ if (parent === current) return false;
+ current = parent;
+ }
}
diff --git a/src/codex/native-profile-startup.ts b/src/codex/native-profile-startup.ts
index 0722a077dd..e873579197 100644
--- a/src/codex/native-profile-startup.ts
+++ b/src/codex/native-profile-startup.ts
@@ -15,6 +15,7 @@ import {
import { withNativeMainExclusiveClaim } from "./native-main-claim";
import { scrubNativeMainAuthTempResidues } from "./native-main-auth-temp";
import { NATIVE_STAGE_SWEEP_INTERVAL_MS } from "./native-profile-stage-store";
+import type { NativeCodexOwnership } from "../integrations/native/ownership-preflight";
export type NativeMainStartupGateSnapshot =
| { status: "ready"; homeId: string | null }
@@ -31,6 +32,10 @@ export type NativeMainStartupGateSnapshot =
| "stage-cleanup-required";
};
+/** The settled reason a blocked gate carries, named so consumers can hold one without the union. */
+export type NativeMainStartupBlockReason =
+ Extract["reason"];
+
export interface NativeMainStartupGateDeps {
manager?: NativeProfileManager;
/** Test-only barrier used to prove admission stays closed while startup recovery is pending. */
@@ -306,6 +311,75 @@ export function startNativeMainStartupLifecycle(
};
}
+/**
+ * How many times a service-ownership fence will re-ask before it stops asking (#2108).
+ *
+ * A host that is permanently unaskable must not re-probe on every request forever, and a
+ * host that recovers usually does so within the first few. The budget belongs to the
+ * REASON, not to an individual fence: raising a second fence deliberately does not hand
+ * out a fresh allowance, or a caller looping over fences could spin the probe forever.
+ * It is dropped when the last fence for that reason releases.
+ */
+export const NATIVE_MAIN_OWNERSHIP_RETRY_LIMIT = 5;
+
+/** Reprobe hooks for the fences currently held, keyed by the reason they were raised for. */
+const serviceOwnershipReprobes = new Map();
+
+interface ServiceOwnershipReprobe {
+ readonly probe: () => NativeCodexOwnership;
+ attempts: number;
+ /** The fence that installed this hook; only its own release may drop the entry. */
+ readonly owner: NativeMainStartupLifecycle;
+ /** Releases the fence that installed this hook, exactly once. */
+ readonly spend: () => void;
+}
+
+/** Test-only: the retry budget is module state and would otherwise leak across tests. */
+export function __resetNativeMainOwnershipRetries(): void {
+ for (const entry of serviceOwnershipReprobes.values()) entry.attempts = 0;
+}
+
+/**
+ * Re-ask whether this host is still unownable, and drop the fence if it is not.
+ *
+ * `startServer` takes the ownership verdict once, at boot, and holds it for the process
+ * lifetime. For `foreign-ownership` that is correct — a foreign owner is a fact, and
+ * re-asking would only hand a determined caller a second chance. For `ownership-unknown`
+ * it is wrong: that verdict means the probe could not answer, so waiting cannot help,
+ * which is precisely why the #2108 reporter had to run `ocx restart` after every reboot.
+ *
+ * The re-probe is demand-driven rather than timed: it runs when something asks whether
+ * native-main is fenced, which is usually a request but is also the background token
+ * guardian's warmup. It is capped so a permanently unaskable host cannot spin.
+ *
+ * The probe is synchronous `spawnSync` with a bounded timeout, and this function is on a
+ * request path, so the cap is what keeps a wedged host from paying that cost repeatedly.
+ */
+function reprobeServiceOwnership(reason: NativeMainServiceOwnershipBlockReason): boolean {
+ if (reason !== "ownership-unknown") return false;
+ const entry = serviceOwnershipReprobes.get(reason);
+ if (!entry) return false;
+ if (entry.attempts >= NATIVE_MAIN_OWNERSHIP_RETRY_LIMIT) return false;
+ entry.attempts += 1;
+ let answer: NativeCodexOwnership;
+ try {
+ answer = entry.probe();
+ } catch {
+ // An inspection that throws is not evidence the host became ownable.
+ return false;
+ }
+ if (answer !== "owned") return false;
+ // Release through the fence that installed this hook, and only that one.
+ //
+ // Several servers can hold a fence for the same reason while only one carries a hook, so
+ // clearing the shared refcount here would unblock fences this probe never spoke for.
+ // Decrementing here directly is just as wrong the other way: that fence's own release()
+ // would then pay a second time for one fence, leaving the count short. Delegating to the
+ // fence's idempotent release keeps exactly one payment per fence.
+ entry.spend();
+ return true;
+}
+
function activeServiceOwnershipBlockReason(): NativeMainServiceOwnershipBlockReason | null {
if ((serviceOwnershipRefs.get("foreign-ownership") ?? 0) > 0) return "foreign-ownership";
if ((serviceOwnershipRefs.get("ownership-unknown") ?? 0) > 0) return "ownership-unknown";
@@ -321,10 +395,11 @@ function serviceOwnershipSnapshot(
/** Close native-main admission without resolving or creating any CODEX_HOME artifacts. */
export function blockNativeMainStartupForUnownedServiceHome(
reason: NativeMainServiceOwnershipBlockReason,
+ options?: { reprobe?: () => NativeCodexOwnership },
): NativeMainStartupLifecycle {
serviceOwnershipRefs.set(reason, (serviceOwnershipRefs.get(reason) ?? 0) + 1);
let released = false;
- return {
+ const lifecycle: NativeMainStartupLifecycle = {
homeId: null,
settled: Promise.resolve(serviceOwnershipSnapshot(reason)),
async release() {
@@ -333,8 +408,25 @@ export function blockNativeMainStartupForUnownedServiceHome(
const remaining = Math.max(0, (serviceOwnershipRefs.get(reason) ?? 0) - 1);
if (remaining === 0) serviceOwnershipRefs.delete(reason);
else serviceOwnershipRefs.set(reason, remaining);
+ if (serviceOwnershipReprobes.get(reason)?.owner === lifecycle) {
+ serviceOwnershipReprobes.delete(reason);
+ }
},
};
+ // Do NOT reset an existing budget: keying the reprobe by reason means a caller raising
+ // fences in a loop would otherwise be handed a fresh allowance each time and could spin
+ // the probe forever. But once the holder is gone its entry is removed above, so a LATER
+ // fence installs its own hook — a server started after an earlier probe must not be left
+ // needing `ocx restart`, which is the very symptom this exists to remove.
+ if (options?.reprobe && reason === "ownership-unknown" && !serviceOwnershipReprobes.has(reason)) {
+ serviceOwnershipReprobes.set(reason, {
+ probe: options.reprobe,
+ attempts: 0,
+ owner: lifecycle,
+ spend: () => { void lifecycle.release(); },
+ });
+ }
+ return lifecycle;
}
export function bindNativeMainStartupLifecycle(server: object, lifecycle: NativeMainStartupLifecycle): void {
@@ -349,7 +441,13 @@ export async function releaseNativeMainStartupLifecycle(server: object): Promise
}
export function isNativeMainTrafficBlocked(): boolean {
- return activeServiceOwnershipBlockReason() !== null || snapshot.status === "blocked";
+ const reason = activeServiceOwnershipBlockReason();
+ if (reason !== null && reprobeServiceOwnership(reason)) {
+ // The host became ownable after boot (#2108): the fence lifts here rather than
+ // waiting for the restart the reporter had to perform by hand.
+ return activeServiceOwnershipBlockReason() !== null || snapshot.status === "blocked";
+ }
+ return reason !== null || snapshot.status === "blocked";
}
/**
diff --git a/src/codex/user-identity.ts b/src/codex/user-identity.ts
index 716d06b4cb..05d1a5bc10 100644
--- a/src/codex/user-identity.ts
+++ b/src/codex/user-identity.ts
@@ -39,6 +39,26 @@ const SID_PATTERN = /^S-1-(?:\d+-)+\d+$/i;
*/
const WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_MS = 8_000;
+/**
+ * The same budget, widened for a contended CI runner.
+ *
+ * 8s is a generous ceiling for `powershell.exe -Command` on a real desktop and is not one
+ * on a GitHub Windows runner executing a quarter of this suite: the composed-acceptance
+ * cases fail there with "Windows effective-account lookup timed out" while the child is
+ * still starting. That is runner contention, not a hung lookup, and the budget exists to
+ * bound the latter.
+ *
+ * Gated on `CI` alone. A user's machine keeps the 8s ceiling exactly as before, so the
+ * recoverable-refusal contract this budget protects is unchanged where it matters.
+ */
+const WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_CI_MS = 30_000;
+
+function windowsIdentityLookupTimeoutMs(): number {
+ return process.env.CI === "true"
+ ? WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_CI_MS
+ : WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_MS;
+}
+
/**
* FOLDERID_LocalAppData, and the flag that makes the lookup ignore the caller's
* environment.
@@ -108,7 +128,7 @@ function windowsIdentityPowerShellSpawnOptions(): {
stdin: "ignore",
stdout: "pipe",
stderr: "pipe",
- timeout: WINDOWS_POWERSHELL_LOOKUP_TIMEOUT_MS,
+ timeout: windowsIdentityLookupTimeoutMs(),
windowsHide: true,
};
}
diff --git a/src/config.ts b/src/config.ts
index 4d5547f5fd..60178f3d4f 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -5,6 +5,7 @@ import { homedir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { Database } from "bun:sqlite";
import * as z from "zod/v4";
+import { isValidProviderName, hasOwnProvider } from "./config/provider-name";
import {
bumpConfigGenerationAtPath,
bumpCurrentConfigGeneration,
@@ -74,6 +75,7 @@ import {
getProviderRegistryEntry,
providerMatchesRegistryTransport,
providerModelWireDefault,
+ registryModelServiceTierCapabilityApplies,
} from "./providers/registry";
import { resolveOpenAiVirtualModel } from "./providers/openai-virtual-models";
import { parseDesktopProfile } from "./claude/desktop-profile";
@@ -726,6 +728,11 @@ const providerConfigSchema = z.object({
.optional(),
retryOn429: retryOn429PolicySchema.optional(),
codexAccountMode: z.enum(["pool", "direct"]).optional(),
+ // Validated rather than passed through: this schema ends in `.passthrough()`, so an
+ // undeclared key survives verbatim. A misspelled `codexToolMode` therefore used to be
+ // accepted, persisted, and then silently resolved to the `code_mode_only` default — the
+ // operator asked for shell mode, got code mode, and was told nothing (#2106).
+ codexToolMode: z.enum(["code_mode_only", "shell"]).optional(),
responsesItemIdRepair: z.object({
message: z.array(z.string().min(1)).optional(),
reasoning: z.array(z.string().min(1)).optional(),
@@ -735,19 +742,6 @@ const providerConfigSchema = z.object({
responsesSnapshotRepair: z.boolean().optional(),
}).passthrough();
-const RESERVED_PROVIDER_NAMES = new Set([
- // JavaScript prototype-pollution guards.
- "__proto__",
- "prototype",
- "constructor",
- // System-reserved routing namespace (resolved before provider/account
- // namespaces in routeModelInternal). "combo" is intentionally NOT reserved:
- // a physical provider named `combo` is a supported pattern (combo aliases
- // hosted on the combo provider), and the combo selector only wins when an
- // actual combo id matches.
- "policy",
-]);
-const PROVIDER_NAME_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$/;
const HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
const SENSITIVE_PROVIDER_HEADERS = new Set([
"authorization",
@@ -759,16 +753,7 @@ const SENSITIVE_PROVIDER_HEADERS = new Set([
"x-amz-security-token",
]);
-export function isValidProviderName(name: string): boolean {
- const trimmed = name.trim();
- return trimmed === name
- && PROVIDER_NAME_PATTERN.test(name)
- && !RESERVED_PROVIDER_NAMES.has(name.toLowerCase());
-}
-
-export function hasOwnProvider(providers: Record, name: string): boolean {
- return Object.prototype.hasOwnProperty.call(providers, name);
-}
+export { isValidProviderName, hasOwnProvider } from "./config/provider-name";
export function providerBaseUrlConfigError(baseUrl: string): string | null {
try {
@@ -2159,7 +2144,9 @@ function inheritedFastWireConflictProviderNames(
if (!registry) continue;
const effectiveProviderCapability = provider.supportsServiceTier ?? registry.supportsServiceTier;
const effectiveModelCapabilities = {
- ...(registry.modelSupportsServiceTier ?? {}),
+ ...(registryModelServiceTierCapabilityApplies(registry, provider)
+ ? registry.modelSupportsServiceTier ?? {}
+ : {}),
...(provider.modelSupportsServiceTier ?? {}),
};
if (
diff --git a/src/config/provider-name.ts b/src/config/provider-name.ts
new file mode 100644
index 0000000000..244bd3cc3e
--- /dev/null
+++ b/src/config/provider-name.ts
@@ -0,0 +1,24 @@
+const RESERVED_PROVIDER_NAMES = new Set([
+ // JavaScript prototype-pollution guards.
+ "__proto__",
+ "prototype",
+ "constructor",
+ // System-reserved routing namespace (resolved before provider/account
+ // namespaces in routeModelInternal). "combo" is intentionally NOT reserved:
+ // a physical provider named `combo` is a supported pattern (combo aliases
+ // hosted on the combo provider), and the combo selector only wins when an
+ // actual combo id matches.
+ "policy",
+]);
+const PROVIDER_NAME_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62}[A-Za-z0-9])?$/;
+
+export function isValidProviderName(name: string): boolean {
+ const trimmed = name.trim();
+ return trimmed === name
+ && PROVIDER_NAME_PATTERN.test(name)
+ && !RESERVED_PROVIDER_NAMES.has(name.toLowerCase());
+}
+
+export function hasOwnProvider(providers: Record, name: string): boolean {
+ return Object.prototype.hasOwnProperty.call(providers, name);
+}
diff --git a/src/images/loop.ts b/src/images/loop.ts
index 1699906d94..834bcced93 100644
--- a/src/images/loop.ts
+++ b/src/images/loop.ts
@@ -676,13 +676,20 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise();
+ const toolNsMap = new Map();
const freeform = new Set();
const toolSearch = new Set();
- const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice);
- for (const t of parsed.context.tools ?? []) {
+ const requestedTools = parsed.context.tools ?? [];
+ const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice, requestedTools);
+ for (const t of requestedTools) {
if (!toolAllowed(t)) continue;
- if (t.namespace) toolNsMap.set(namespacedToolName(t.namespace, t.name), { namespace: t.namespace, name: t.name });
+ if (t.namespace) {
+ toolNsMap.set(namespacedToolName(t.namespace, t.name), {
+ namespace: t.namespace,
+ name: t.name,
+ ...(t.freeform ? { freeform: true } : {}),
+ });
+ }
if (t.freeform) freeform.add(t.name);
if (t.toolSearch) toolSearch.add(t.name);
}
diff --git a/src/lib/state-store-registrations.ts b/src/lib/state-store-registrations.ts
index 55bb4f292a..61aad5f7b9 100644
--- a/src/lib/state-store-registrations.ts
+++ b/src/lib/state-store-registrations.ts
@@ -35,7 +35,7 @@ import { listLiveOAuthAccountKeys, reconcileOAuthReauthState } from "../oauth/st
import { reconcileGuardianBackoff } from "../oauth/token-guardian";
import { sweepExpiredApiKeyCooldowns } from "../providers/key-failover";
import { reconcileProviderRequestPacing } from "../providers/request-pacing";
-import { sweepExpiredResponseStates } from "../responses/state";
+import { sweepAbandonedResponseStateTemps, sweepExpiredResponseStates } from "../responses/state";
import { sweepExpiredAntigravityReplay } from "../adapters/google-antigravity-replay";
import { reconcileProviderAccountQuotaRows } from "../providers/quota";
import { reconcileRouterWarningMemos } from "../router";
@@ -84,7 +84,13 @@ export const STATE_STORE_REGISTRATIONS = [
},
{ name: "anthropic-routing-health", sweepExpired: sweepExpiredAnthropicRoutingHealth },
{ name: "xai-refresh-verdicts", sweepExpired: sweepExpiredXaiPermanentFailureVerdicts },
- { name: "responses-continuation", sweepExpired: sweepExpiredResponseStates },
+ {
+ name: "responses-continuation",
+ sweepExpired: sweepExpiredResponseStates,
+ // Disk reclaim rides the liveness tick, not the TTL tick: sweepExpiredOnWrite puts
+ // sweepExpired on hot write paths, where a directory scan does not belong.
+ sweepLiveness: sweepAbandonedResponseStateTemps,
+ },
{ name: "antigravity-replay", sweepExpired: sweepExpiredAntigravityReplay },
{ name: "config-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileConfigWarningMemos(context.generation) },
{ name: "catalog-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileCatalogWarningMemos(context.generation) },
diff --git a/src/providers/antigravity-models.ts b/src/providers/antigravity-models.ts
index bf155b543c..9b9045cb9b 100644
--- a/src/providers/antigravity-models.ts
+++ b/src/providers/antigravity-models.ts
@@ -72,6 +72,12 @@ const ANTIGRAVITY_WIRE_IDS_BY_PICKER_MODEL: Record = Object.en
}, {});
const ANTIGRAVITY_DISCOVERY_EFFORTS = ["low", "medium", "high"] as const;
+type AntigravityDiscoveryEffort = typeof ANTIGRAVITY_DISCOVERY_EFFORTS[number];
+type AntigravityEffortWireModelIds = Partial>;
+
+function isAntigravityDiscoveryEffort(value: string): value is AntigravityDiscoveryEffort {
+ return (ANTIGRAVITY_DISCOVERY_EFFORTS as readonly string[]).includes(value);
+}
function pickerModelIdForDiscoveredWireId(
wireId: string,
@@ -151,6 +157,25 @@ const ANTIGRAVITY_EFFORT_WIRE_MAP: Record> = {
},
};
+function completeDiscoveredEffortWireModelIds(
+ pickerId: string,
+ available: ReadonlyMap>,
+): AntigravityEffortWireModelIds | undefined {
+ const explicitEffortMap = ANTIGRAVITY_EFFORT_WIRE_MAP[pickerId];
+ if (explicitEffortMap && Object.values(explicitEffortMap).every(wireId => available.has(wireId))) {
+ return { ...explicitEffortMap };
+ }
+
+ if (!isKnownAntigravityPickerModelId(pickerId)) return undefined;
+ const suffixEffortMap: AntigravityEffortWireModelIds = {};
+ for (const effort of ANTIGRAVITY_DISCOVERY_EFFORTS) {
+ const wireId = `${pickerId}-${effort}`;
+ if (!available.has(wireId)) return undefined;
+ suffixEffortMap[effort] = wireId;
+ }
+ return suffixEffortMap;
+}
+
// ── Default effort per Gemini base model ──
const ANTIGRAVITY_DEFAULT_EFFORT: Record = {
"gemini-3.1-pro": "high",
@@ -270,6 +295,8 @@ export interface AntigravityAvailableModel {
id: string;
/** CCA model id used by the agent envelope when `id` comes from display metadata. */
wireModelId: string;
+ /** Complete effort-to-wire mapping retained for collapsed discovered tier sets. */
+ effortWireModelIds?: AntigravityEffortWireModelIds;
contextWindow?: number;
inputModalities?: string[];
}
@@ -286,6 +313,7 @@ function antigravityPositiveInteger(value: unknown): number | undefined {
interface DiscoveredWireModelMapping {
readonly models: ReadonlyMap;
+ readonly effortModels: ReadonlyMap;
readonly generation?: { provider: string; cacheGeneration: string };
}
@@ -327,17 +355,21 @@ export function registerAntigravityDiscoveredWireModels(
const key = antigravityBaseUrlKey(baseUrl);
if (!key) return;
const wireModels = new Map();
- for (const model of models) wireModels.set(model.id, model.wireModelId);
+ const effortModels = new Map();
+ for (const model of models) {
+ wireModels.set(model.id, model.wireModelId);
+ if (model.effortWireModelIds) effortModels.set(model.id, { ...model.effortWireModelIds });
+ }
discoveredWireModelsByBaseUrl.set(key, {
models: wireModels,
+ effortModels,
...(generation ? { generation } : {}),
});
}
-function discoveredAntigravityWireModelId(
- modelId: string,
+function discoveredAntigravityMapping(
baseUrl: string | undefined,
-): string | undefined {
+): DiscoveredWireModelMapping | undefined {
const key = antigravityBaseUrlKey(baseUrl);
if (!key) return undefined;
const mapping = discoveredWireModelsByBaseUrl.get(key);
@@ -347,7 +379,35 @@ function discoveredAntigravityWireModelId(
discoveredWireModelsByBaseUrl.delete(key);
return undefined;
}
- return mapping.models.get(modelId);
+ return mapping;
+}
+
+function discoveredAntigravityWireModelId(
+ modelId: string,
+ baseUrl: string | undefined,
+): string | undefined {
+ return discoveredAntigravityMapping(baseUrl)?.models.get(modelId);
+}
+
+function discoveredAntigravityEffortWireModelId(
+ modelId: string,
+ effort: string | undefined,
+ baseUrl: string | undefined,
+): string | undefined {
+ const effortMap = discoveredAntigravityMapping(baseUrl)?.effortModels.get(modelId);
+ if (!effortMap) return undefined;
+
+ const requestedEffort = effort ? resolveAntigravityThinkingLevel(effort) : undefined;
+ if (requestedEffort && isAntigravityDiscoveryEffort(requestedEffort) && effortMap[requestedEffort]) {
+ return effortMap[requestedEffort];
+ }
+
+ const defaultEffort = ANTIGRAVITY_DEFAULT_EFFORT[modelId]
+ ?? ANTIGRAVITY_THINKING_LEVEL_MODELS[modelId];
+ if (defaultEffort && isAntigravityDiscoveryEffort(defaultEffort) && effortMap[defaultEffort]) {
+ return effortMap[defaultEffort];
+ }
+ return Object.values(effortMap)[0];
}
/**
@@ -465,9 +525,11 @@ export function parseAntigravityAvailableModels(
const id = pickerModelIdForDiscoveredWireId(wireId, info, available);
if (seen.has(id)) continue;
seen.add(id);
+ const effortWireModelIds = completeDiscoveredEffortWireModelIds(id, available);
out.push({
id,
wireModelId: wireId,
+ ...(effortWireModelIds ? { effortWireModelIds } : {}),
...(antigravityPositiveInteger(info.maxTokens) ? { contextWindow: antigravityPositiveInteger(info.maxTokens) } : {}),
// Tri-state, deliberately not a ternary: `true` asserts image support,
// `false` asserts against it, and ABSENT is unknown. Collapsing absent into
@@ -522,6 +584,9 @@ export function resolveAntigravityEffortWireModel(
effort?: string,
baseUrl?: string,
): { wireModelId: string; thinkingLevel?: string } {
+ const discoveredEffortWireModelId = discoveredAntigravityEffortWireModelId(modelId, effort, baseUrl);
+ if (discoveredEffortWireModelId) return { wireModelId: discoveredEffortWireModelId };
+
// A collapsed picker row reports ONE representative wire id (whichever tier CCA
// listed first), so live discovery cannot describe a ladder — it can only name a
// single rung. Letting it answer for a base model we already have a ladder for
diff --git a/src/providers/derive.ts b/src/providers/derive.ts
index c5e08065b3..3db91f73df 100644
--- a/src/providers/derive.ts
+++ b/src/providers/derive.ts
@@ -3,6 +3,7 @@ import { cloneFastWire } from "./fastwire";
import {
PROVIDER_REGISTRY,
registryEntryForProviderDestination,
+ registryModelServiceTierCapabilityApplies,
type ProviderRegistryEntry,
} from "./registry";
import {
@@ -377,6 +378,15 @@ function applyServiceTierModelDefaults(
};
}
+function serviceTierModelDefaultsFor(
+ entry: ProviderRegistryEntry | undefined,
+ prov: OcxProviderConfig,
+): Readonly> | undefined {
+ return entry && registryModelServiceTierCapabilityApplies(entry, prov)
+ ? entry.modelSupportsServiceTier
+ : undefined;
+}
+
/**
* Last-resort enrichment for a provider whose NAME matches no registry id.
*
@@ -412,7 +422,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
// which vendor endpoint is this row talking to — and is already restricted to fixed key
// destinations, so a templated or overridable base URL cannot be claimed by it.
enrichReasoningSummariesByDestination(prov);
- applyServiceTierModelDefaults(prov, registryEntryForProviderDestination(prov)?.modelSupportsServiceTier);
+ applyServiceTierModelDefaults(prov, serviceTierModelDefaultsFor(registryEntryForProviderDestination(prov), prov));
return;
}
const explicitDirectReasoning: DirectReasoningEffortOverrides = {
@@ -466,7 +476,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
if (prov.supportsServiceTier === undefined && entry.supportsServiceTier !== undefined) prov.supportsServiceTier = entry.supportsServiceTier;
if (prov.preserveResponsesReasoningContent === undefined && entry.preserveResponsesReasoningContent !== undefined) prov.preserveResponsesReasoningContent = entry.preserveResponsesReasoningContent;
applyReasoningSummaryDefaults(prov, entry.modelSupportsReasoningSummaries);
- applyServiceTierModelDefaults(prov, entry.modelSupportsServiceTier);
+ applyServiceTierModelDefaults(prov, serviceTierModelDefaultsFor(entry, prov));
// Registry-only repair policy (#938): fill only when the runtime provider has
// no explicit policy, and deep-clone so saved/user values never alias the
// registry constant.
diff --git a/src/providers/registry.ts b/src/providers/registry.ts
index c81735ba15..53922e75ad 100644
--- a/src/providers/registry.ts
+++ b/src/providers/registry.ts
@@ -17,6 +17,7 @@ import {
cursorModelReasoningEfforts,
} from "../adapters/cursor/discovery";
import { COMMAND_CODE_MODEL_REASONING_EFFORTS } from "./command-code-efforts";
+import { isCanonicalOpenRouterTarget } from "./openrouter-routing";
export type ProviderAuthKind = "forward" | "oauth" | "key" | "local";
export type MetadataModelIdNormalize = "case-insensitive";
@@ -217,6 +218,11 @@ export interface ProviderRegistryEntry {
supportsServiceTier?: boolean;
/** Registry default for exact model service-tier capability; explicit config keys win. */
modelSupportsServiceTier?: Record;
+ /**
+ * Registry-only destination guard for `modelSupportsServiceTier`. This scopes vendor evidence
+ * without changing provider ownership, routing, authentication, or config validation.
+ */
+ modelServiceTierCapabilityBaseUrlGuard?: (baseUrl: string) => boolean;
/** Registry default for plaintext reasoning replay; see `OcxProviderConfig.preserveResponsesReasoningContent`. Registry-only like `supportsServiceTier`. */
preserveResponsesReasoningContent?: boolean;
/** Registry defaults for per-model Codex reasoning propagation; explicit user keys win during enrichment. */
@@ -1349,7 +1355,33 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
autoToolChoiceOnlyModels: ["kimi-k2.7-code"],
preserveReasoningContentModels: NEURALWATT_REASONING_HISTORY_MODELS,
},
- { id: "openrouter", label: "OpenRouter", adapter: "openai-chat", baseUrl: "https://openrouter.ai/api/v1", authKind: "key", featured: true, dashboardUrl: "https://openrouter.ai/keys", jawcodeBundle: "openrouter", models: ["anthropic/claude-sonnet-5", ...OPENROUTER_GPT56_MODELS], modelContextWindows: { "anthropic/claude-sonnet-5": 1_000_000, ...OPENROUTER_GPT56_CONTEXT_WINDOWS } },
+ {
+ id: "openrouter",
+ label: "OpenRouter",
+ adapter: "openai-chat",
+ baseUrl: "https://openrouter.ai/api/v1",
+ authKind: "key",
+ featured: true,
+ dashboardUrl: "https://openrouter.ai/keys",
+ jawcodeBundle: "openrouter",
+ models: ["anthropic/claude-sonnet-5", ...OPENROUTER_GPT56_MODELS],
+ modelContextWindows: {
+ "anthropic/claude-sonnet-5": 1_000_000,
+ ...OPENROUTER_GPT56_CONTEXT_WINDOWS,
+ },
+ // OpenRouter documents priority support for OpenAI endpoints, but not Anthropic. Keep the
+ // provider unclassified and opt in only the exact OpenAI-backed slugs we ship. These facts
+ // belong only to the canonical destination; a same-named custom gateway is unknown to us.
+ modelServiceTierCapabilityBaseUrlGuard: isCanonicalOpenRouterTarget,
+ modelSupportsServiceTier: {
+ "openai/gpt-5.6-sol": true,
+ "openai/gpt-5.6-terra": true,
+ "openai/gpt-5.6-luna": true,
+ },
+ // Deliberately no OpenRouter route pin: it bills the endpoint actually used and reports the
+ // actual service_tier. B0 confirmation therefore owns downgrade safety. Forcing `only` plus
+ // `allow_fallbacks:false` would turn a graceful priority-capacity fallback into a hard failure.
+ },
{
// Primary sources checked 2026-08-02:
// - docs.cline.bot/getting-started/clinepass publishes this exact catalog and explicitly
@@ -2470,6 +2502,10 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
// The gateway validates the ladder strictly and rejects anything above `high`.
reasoningEfforts: ["low", "medium", "high"],
reasoningEffortMap: { xhigh: "high", max: "high", ultra: "high" },
+ // Live token-plan verification (#1927): the Pro route rejects image input while
+ // mimo-v2.5 accepts it natively. Keep this provider-scoped so a hand-rolled
+ // provider with the same id but another destination does not inherit the claim.
+ noVisionModels: ["mimo-v2.5-pro"],
// A user may already have hand-rolled a provider under this id against a different host;
// without this, routedProviderConfig() would canonicalize their base URL onto ours and send
// their key somewhere they did not choose.
@@ -2555,6 +2591,15 @@ export function getProviderRegistryEntry(id: string): ProviderRegistryEntry | un
return PROVIDER_REGISTRY.find(entry => entry.id === id);
}
+/** Whether this registry row's per-model service-tier evidence applies to one configured target. */
+export function registryModelServiceTierCapabilityApplies(
+ entry: Pick,
+ provider: Pick,
+): boolean {
+ const guard = entry.modelServiceTierCapabilityBaseUrlGuard;
+ return guard === undefined || guard(provider.baseUrl);
+}
+
function normalizedProviderEndpoint(value: string): string {
const trimmed = value.trim();
try {
diff --git a/src/providers/service-tier.ts b/src/providers/service-tier.ts
index a06c42c7b4..278f89394e 100644
--- a/src/providers/service-tier.ts
+++ b/src/providers/service-tier.ts
@@ -4,6 +4,7 @@ import { isCanonicalOpenAiForwardProvider } from "./openai-tiers";
import {
getProviderRegistryEntry,
providerMatchesRegistryTransport,
+ registryModelServiceTierCapabilityApplies,
type InboundWire,
type ModelWireDefault,
} from "./registry";
@@ -57,8 +58,14 @@ function buildFastPolicyAuthority(
providerName: string,
provider: ServiceTierCapabilityProvider,
registryTransportMatch: boolean,
+ capabilityProvider: ServiceTierCapabilityProvider = provider,
): FastPolicyAuthority {
const registry = registryTransportMatch ? getProviderRegistryEntry(providerName) : undefined;
+ const registryModelCapabilities = registry
+ && registryModelServiceTierCapabilityApplies(registry, capabilityProvider)
+ ? registry.modelSupportsServiceTier
+ : undefined;
+ const providerCapability = capabilityProvider.supportsServiceTier ?? registry?.supportsServiceTier;
const authority: FastPolicyAuthority = Object.freeze({
providerAdapter: provider.adapter,
fastWireDeclaration: cloneFastWire(
@@ -72,8 +79,11 @@ function buildFastPolicyAuthority(
provider.apiKeyTransport,
),
capability: Object.freeze({
- ...(provider.supportsServiceTier !== undefined ? { provider: provider.supportsServiceTier } : {}),
- models: Object.freeze({ ...(provider.modelSupportsServiceTier ?? {}) }),
+ ...(providerCapability !== undefined ? { provider: providerCapability } : {}),
+ models: Object.freeze({
+ ...(registryModelCapabilities ?? {}),
+ ...(capabilityProvider.modelSupportsServiceTier ?? {}),
+ }),
...(provider.chatServiceTier !== undefined ? { chatServiceTier: provider.chatServiceTier } : {}),
}),
modelAdapters: Object.freeze({ ...(provider.modelAdapters ?? {}) }),
@@ -87,8 +97,14 @@ export function captureFastPolicyAuthority(
providerName: string,
provider: ServiceTierCapabilityProvider,
registryTransportMatch: boolean,
+ capabilityProvider: ServiceTierCapabilityProvider = provider,
): FastPolicyAuthority {
- const authority = buildFastPolicyAuthority(providerName, provider, registryTransportMatch);
+ const authority = buildFastPolicyAuthority(
+ providerName,
+ provider,
+ registryTransportMatch,
+ capabilityProvider,
+ );
if (Object.isFrozen(provider)) capturedFastPolicyAuthorities.set(provider, authority);
return authority;
}
@@ -106,12 +122,13 @@ export function captureServiceTierAdapterAuthority(
function authorityForProvider(
provider: ServiceTierCapabilityProvider,
providerName?: string,
+ capabilityProvider?: ServiceTierCapabilityProvider,
): FastPolicyAuthority {
// Preserve the legacy no-name short circuit: serviceTierSupportForModel() used the
// provider adapter directly when no provider identity was available, so no configured
// override, hard pin, or registry default may participate on this path in A1.
if (providerName === undefined) {
- const authority = buildFastPolicyAuthority("", provider, false);
+ const authority = buildFastPolicyAuthority("", provider, false, capabilityProvider ?? provider);
return Object.freeze({
...authority,
modelAdapters: Object.freeze({}),
@@ -119,12 +136,17 @@ function authorityForProvider(
registryWireDefaults: Object.freeze({}),
});
}
- const captured = Object.isFrozen(provider)
+ const captured = capabilityProvider === undefined && Object.isFrozen(provider)
? capturedFastPolicyAuthorities.get(provider)
: undefined;
if (captured) return captured;
const registryTransportMatch = providerMatchesRegistryTransport(providerName, provider);
- const authority = buildFastPolicyAuthority(providerName, provider, registryTransportMatch);
+ const authority = buildFastPolicyAuthority(
+ providerName,
+ provider,
+ registryTransportMatch,
+ capabilityProvider ?? provider,
+ );
// Frozen provider snapshots cannot drift, so repeated catalog/runtime projections may safely
// reuse the registry lookup and detached declaration maps. Mutable configs still rebuild.
if (Object.isFrozen(provider)) capturedFastPolicyAuthorities.set(provider, authority);
@@ -137,8 +159,13 @@ export function fastPolicyForModel(
modelId: string,
providerName?: string,
inbound: InboundWire = "responses",
+ capabilityProvider?: ServiceTierCapabilityProvider,
): ResolvedFastPolicy {
- return resolveFastPolicy(authorityForProvider(provider, providerName), modelId, inbound);
+ return resolveFastPolicy(
+ authorityForProvider(provider, providerName, capabilityProvider),
+ modelId,
+ inbound,
+ );
}
/**
diff --git a/src/responses/parser.ts b/src/responses/parser.ts
index 7c2393bd2e..ca9f425f29 100644
--- a/src/responses/parser.ts
+++ b/src/responses/parser.ts
@@ -11,7 +11,7 @@ import type {
OcxToolCall,
OcxReasoningReplayScopeRef,
} from "../types";
-import { namespacedToolName } from "../types";
+import { namespacedToolName, toolChoiceCandidates } from "../types";
import { responsesRequestSchema } from "./schema";
import { providerMetadataFromResponsesFunctionCall } from "./provider-opaque-metadata";
import { lookupReplayThoughtSignature } from "./thought-signature-replay";
@@ -203,7 +203,7 @@ function buildTools(tools: unknown[] | undefined): OcxTool[] | undefined {
const ns = typeof t.name === "string" && !builtinFunctions ? t.name : undefined;
for (const inner of t.tools as unknown[]) {
if (isObj(inner) && inner.type === "function" && typeof inner.name === "string") pushFn(inner, ns);
- else if (builtinFunctions && isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner);
+ else if (isObj(inner) && inner.type === "custom" && typeof inner.name === "string") pushCustom(inner, ns);
}
}
else if (t.type === "custom" && typeof t.name === "string") {
@@ -328,6 +328,35 @@ function attachPendingReasoningToCallOwner(
const REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
+/**
+ * Namespace a custom tool was declared under, by its bare name.
+ *
+ * A `custom_tool_call` echoed back by the client carries only the bare name — the bridge
+ * emits `{"type":"custom_tool_call","name":"exec"}` even when the tool was declared as
+ * `mcp__functions__exec`. Without this lookup the namespace is lost on the return trip,
+ * and the adapters replay history through `namespacedToolName(namespace, name)`, which
+ * then produces a bare `exec` the provider may not have. Ordinary `function_call` items
+ * do not need this: they carry `namespace` on the wire.
+ */
+function customToolNamespaces(tools: unknown): Map {
+ const out = new Map();
+ if (!Array.isArray(tools)) return out;
+ for (const spec of tools) {
+ if (!isObj(spec) || spec.type !== "namespace" || !Array.isArray(spec.tools)) continue;
+ const namespace = typeof spec.name === "string" ? spec.name : undefined;
+ // Codex 0.147 groups ordinary client tools under the reserved `functions` namespace and
+ // buildTools deliberately flattens those without a namespace. Mirror that here, or the
+ // reconstruction would invent a namespace the request never advertised.
+ if (!namespace || namespace === "functions") continue;
+ for (const inner of spec.tools) {
+ if (!isObj(inner) || inner.type !== "custom" || typeof inner.name !== "string") continue;
+ // Ambiguous bare names are already rejected upstream, so first declaration wins.
+ if (!out.has(inner.name)) out.set(inner.name, namespace);
+ }
+ }
+ return out;
+}
+
export function parseRequest(
body: unknown,
parseOptions?: { replayCacheScope?: OcxReasoningReplayScopeRef },
@@ -341,6 +370,9 @@ export function parseRequest(
const data = parsed.data;
const now = Date.now();
const messages: OcxMessage[] = [];
+ // Built before the item loop: a custom_tool_call echoed back in `input` needs the
+ // namespace from the request's own tool catalog to survive the round trip.
+ const customToolNamespacesByName = customToolNamespaces(data.tools);
const systemPrompt: string[] = [];
// Responses reasoning siblings belong to the following assistant, including across call items.
// Keep them off the message list until that assistant arrives; turn boundaries clear the array.
@@ -574,10 +606,15 @@ export function parseRequest(
if (effectiveType === "custom_tool_call") {
const call = item as { id?: string; call_id: string; name: string; input: string };
const remembered = typeof call.call_id === "string" ? replayThoughtSignatureMetadata(call.call_id, replayCacheScope) : undefined;
+ // Reconstruct the namespace the request declared this tool under. The wire item
+ // carries only the bare name, so without this the round trip loses it and adapters
+ // replay the call as an unnamespaced tool the provider may not expose.
+ const customNamespace = customToolNamespacesByName.get(call.name);
const toolCall: OcxToolCall = {
type: "toolCall", id: call.call_id, name: call.name,
arguments: { input: call.input ?? "" },
customWireName: call.name,
+ ...(customNamespace ? { namespace: customNamespace } : {}),
...(remembered ? { providerMetadata: remembered } : {}),
};
assistantHolderWithReasoning().content.push(toolCall);
@@ -691,6 +728,15 @@ export function parseRequest(
const declaredTools = buildTools(data.tools as unknown[] | undefined) ?? [];
const loadedTools = buildTools(loadedToolSpecs) ?? [];
const loadedToolNames = new Set(loadedTools.map(t => namespacedToolName(t.namespace, t.name)));
+ const wireOwners = new Map();
+ for (const tool of [...declaredTools, ...loadedTools]) {
+ const wireName = namespacedToolName(tool.namespace, tool.name);
+ const previous = wireOwners.get(wireName);
+ if (previous && (previous.namespace !== tool.namespace || previous.name !== tool.name || previous.freeform !== tool.freeform || previous.toolSearch !== tool.toolSearch)) {
+ throw new Error(`ambiguous tool catalog: multiple logical tools map to wire name ${wireName}`);
+ }
+ wireOwners.set(wireName, tool);
+ }
const seenTools = new Set();
const mergedTools = [...declaredTools, ...loadedTools]
.filter(t => {
@@ -716,6 +762,14 @@ export function parseRequest(
options.stopSequences = typeof data.stop === "string" ? [data.stop] : data.stop;
}
const tc = mapToolChoice(data.tool_choice);
+ if (tc && typeof tc === "object") {
+ const selectors = "allowedTools" in tc ? tc.allowedTools : [tc.name];
+ for (const selector of selectors) {
+ if (toolChoiceCandidates(mergedTools, selector).length > 1) {
+ throw new Error(`ambiguous tool_choice name: ${selector}`);
+ }
+ }
+ }
if (tc !== undefined) options.toolChoice = tc;
if (data.parallel_tool_calls !== undefined) options.parallelToolCalls = data.parallel_tool_calls;
// Upstream codex-rs converts "ultra" to "max" at the inference boundary (core/src/client.rs
diff --git a/src/responses/state.ts b/src/responses/state.ts
index a08ed1012e..39c83b7022 100644
--- a/src/responses/state.ts
+++ b/src/responses/state.ts
@@ -1,4 +1,5 @@
import { chmodSync, existsSync, lstatSync, mkdirSync, opendirSync, readFileSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { uptime } from "node:os";
import { dirname, join } from "node:path";
import { atomicWriteFileAsync, getConfigDir, resolveWriteTarget } from "../config";
import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../lib/app-owned-memory";
@@ -31,6 +32,17 @@ const SNAPSHOT_FILE_MAX_BYTES = 32 * 1024 * 1024;
const STALE_TEMP_GRACE_MS = 15 * 60 * 1_000;
const STALE_TEMP_MAX_ENTRIES = 4_096;
const STALE_TEMP_MAX_CLEANUPS = 512;
+/** Absorbs `os.uptime()` granularity only. It is deliberately NOT the safety margin:
+ * the unconditional 15-minute grace above is (see the boot floor in the scan loop). */
+const BOOT_FLOOR_SKEW_MS = 60 * 1_000;
+/** Per-tick budget for the periodic reclaim. Smaller than the startup budget because the
+ * periodic pass runs synchronously on the serving process's event loop every 60 s. */
+const PERIODIC_TEMP_MAX_ENTRIES = 512;
+const PERIODIC_TEMP_MAX_CLEANUPS = 64;
+/** Wall-clock ceiling for one periodic scan. An entry cap bounds syscalls, not time: on a
+ * network-mounted config dir each `lstat` can cost 10-20 ms, which would stall in-flight
+ * streams. Reclaim is idempotent, so a truncated tick simply resumes on the next one. */
+const PERIODIC_TEMP_SCAN_DEADLINE_MS = 25;
const RESPONSE_STATE_TEMP_NAME = /^responses-state\.json\.ocx\.(\d+)\.(\d+)\.tmp$/;
const MAX_SNAPSHOT_REWRITE_ATTEMPTS = 4;
@@ -494,19 +506,37 @@ export interface ResponseStateTempRecoveryResult {
removed: number;
failed: number;
bytesRemoved: number;
+ /** Entries that passed EVERY gate and would be reclaimed. In a dry run nothing is
+ * unlinked, so this is the only honest count to show an operator: `matched` is
+ * incremented before the file-type, age, boot-floor, and liveness gates. */
+ eligible: number;
+ /** Total size of the `eligible` entries. */
+ eligibleBytes: number;
+ /** The scan stopped on a budget (entry cap, cleanup cap, or deadline) rather than reaching
+ * the end of the directory, so the counts below describe a prefix of the backlog and not
+ * the backlog. `eligible > removed + failed` cannot express this: outside a dry run every
+ * eligible entry is unlinked or failed on the same iteration, so the two are always equal
+ * and a comparison between them is dead code. */
+ truncated: boolean;
}
interface ResponseStateTempRecoveryIO {
now: () => number;
+ /** Approximate epoch ms of the current boot; see the boot floor in the scan loop. */
+ bootTime: () => number;
list: (dir: string) => Iterable;
inspect: (path: string) => { isFile: boolean; mtimeMs: number; size: number };
isProcessAlive: (pid: number) => boolean;
unlink: (path: string) => void;
}
-type ResponseStateTempRecoveryOptions = Partial & {
+export type ResponseStateTempRecoveryOptions = Partial & {
maxEntries?: number;
maxCleanups?: number;
+ /** Wall-clock ceiling for the scan, or null/undefined for no deadline (startup path). */
+ deadlineMs?: number | null;
+ /** Report only: apply every gate, count what would be reclaimed, unlink nothing. */
+ dryRun?: boolean;
};
function processIsAlive(pid: number): boolean {
@@ -523,6 +553,7 @@ function processIsAlive(pid: number): boolean {
const responseStateTempRecoveryIO: ResponseStateTempRecoveryIO = {
now: Date.now,
+ bootTime: () => Date.now() - uptime() * 1_000,
list: function* list(dir) {
const handle = opendirSync(dir);
try {
@@ -549,26 +580,56 @@ export function recoverStaleResponseStateTemps(
dir = getConfigDir(),
options: ResponseStateTempRecoveryOptions = {},
): ResponseStateTempRecoveryResult {
- const { maxEntries = STALE_TEMP_MAX_ENTRIES, maxCleanups = STALE_TEMP_MAX_CLEANUPS, ...overrides } = options;
+ const {
+ maxEntries = STALE_TEMP_MAX_ENTRIES,
+ maxCleanups = STALE_TEMP_MAX_CLEANUPS,
+ deadlineMs = null,
+ dryRun = false,
+ ...overrides
+ } = options;
const io = { ...responseStateTempRecoveryIO, ...overrides };
const result: ResponseStateTempRecoveryResult = {
matched: 0,
removed: 0,
failed: 0,
bytesRemoved: 0,
+ eligible: 0,
+ eligibleBytes: 0,
+ truncated: false,
};
+ const startedAt = io.now();
+ // One probe per scan, not one per entry. A non-finite or future-dated boot is anomalous, and
+ // clamping it to "now" would be the WORST response: the floor would then retire the liveness
+ // probe for every file older than the skew, which is every file past the grace. Disable it
+ // instead -- an absent floor only costs a missed reclaim, never a wrong one.
+ const rawBoot = io.bootTime();
+ const bootMs = Number.isFinite(rawBoot) && rawBoot <= startedAt ? rawBoot : Number.NEGATIVE_INFINITY;
let names: Iterable;
try { names = io.list(dir); } catch { return result; }
let iterator: Iterator;
try { iterator = names[Symbol.iterator](); } catch { return result; }
let scanned = 0;
+ // Every early exit runs through this. The production `list` is a generator that closes its
+ // directory handle in a `finally`, and a `finally` does NOT run when the consumer simply
+ // stops calling `next()` -- only `return()` resumes the generator to completion. Breaking
+ // out of the loop directly therefore leaked one directory handle per truncated scan, and the
+ // periodic reclaim truncates on purpose (entry cap, cleanup cap, deadline), so on a slow
+ // filesystem that is a leak per tick, forever.
+ const stopScan = (): ResponseStateTempRecoveryResult => {
+ try { iterator.return?.(); } catch { /* closing is best-effort; never fail a reclaim on it */ }
+ return result;
+ };
for (;;) {
let next: IteratorResult;
try { next = iterator.next(); } catch { return result; }
if (next.done) break;
const name = next.value;
scanned += 1;
- if (scanned > maxEntries || result.removed + result.failed >= maxCleanups) break;
+ // A dry run performs no cleanups, so bounding it by the cleanup budget would truncate
+ // the very report an operator uses to size the problem.
+ if (scanned > maxEntries) { result.truncated = true; return stopScan(); }
+ if (!dryRun && result.removed + result.failed >= maxCleanups) { result.truncated = true; return stopScan(); }
+ if (deadlineMs !== null && io.now() - startedAt > deadlineMs) { result.truncated = true; return stopScan(); }
const match = RESPONSE_STATE_TEMP_NAME.exec(name);
if (!match) continue;
result.matched += 1;
@@ -579,13 +640,34 @@ export function recoverStaleResponseStateTemps(
let file: ReturnType;
try { file = io.inspect(path); } catch { continue; }
if (!file.isFile || io.now() - file.mtimeMs < STALE_TEMP_GRACE_MS) continue;
- if (pid === process.pid || io.isProcessAlive(pid)) continue;
+ // Boot floor. After a reboot the original writer's pid is routinely reused, which makes
+ // the liveness skip PERMANENT: the 15-minute grace above is a lower bound and never
+ // expires it, so the file is skipped on every future pass forever. A temp older than
+ // this boot cannot be owned by the pid we would probe, so the probe is vacuous and we
+ // retire it. This does NOT claim the file is provably dead: under a shared-volume
+ // container, suspend-excluding uptime, or a network config dir the computed boot can
+ // land after the real one. The unconditional 15-minute grace above remains the safety
+ // floor, and this process's own temps are never touched.
+ const predatesBoot = file.mtimeMs < bootMs - BOOT_FLOOR_SKEW_MS;
+ if (pid === process.pid) continue;
+ if (!predatesBoot && io.isProcessAlive(pid)) continue;
+
+ result.eligible += 1;
+ result.eligibleBytes += file.size;
+ if (dryRun) continue;
try {
io.unlink(path);
result.removed += 1;
result.bytesRemoved += file.size;
- } catch {
+ } catch (error) {
+ // Another proxy sharing this config dir may have won the race. A file that is already
+ // gone is reclaimed, not a failure -- reporting it as one would surface "in use or
+ // locked" to an operator for a file nobody holds.
+ if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+ result.removed += 1;
+ continue;
+ }
// Locked files remain for a later startup. Do not truncate by path: a same-user
// replacement could turn that fallback into an arbitrary symlink-target write.
result.failed += 1;
@@ -594,6 +676,23 @@ export function recoverStaleResponseStateTemps(
return result;
}
+/**
+ * Literal config dir plus the snapshot's resolved dir. Atomic writes place their temp beside
+ * the RESOLVED target, so a symlinked snapshot (dotfiles-managed config dir) strands temps in
+ * the link's real directory where a scan of the literal dir would never see them. The two
+ * collapse to one when nothing is symlinked.
+ */
+function responseStateSweepDirectories(): Set {
+ const path = snapshotPath();
+ let resolvedDir = dirname(path);
+ try {
+ resolvedDir = dirname(resolveWriteTarget(path));
+ } catch {
+ /* unresolvable link: sweep the literal dir only */
+ }
+ return new Set([dirname(path), resolvedDir]);
+}
+
/**
* Best-effort disk snapshot so previous_response_id chains survive a proxy restart (the
* dominant expansion-miss cause: an in-memory-only store dies with the process, and the next
@@ -898,6 +997,64 @@ export function sweepExpiredResponseStates(at = now()): number {
return removed;
}
+/**
+ * Periodic disk reclaim for abandoned atomic-write temps.
+ *
+ * `ensureLoaded` sweeps once per process, at load, BEFORE that process writes anything:
+ * every `schedulePersist` site is downstream of it. So a process that abandons a temp has
+ * already had its only look, the 15-minute grace hides the temp its predecessor's crash
+ * just produced, and `maxCleanups` caps a single pass below a large backlog. A restart
+ * loop therefore accumulates monotonically. Repeating the reclaim on a timer fixes all
+ * three: the grace expires into a later tick and the per-pass cap becomes a per-tick rate.
+ *
+ * Registered on the sweeper's LIVENESS tick, not the TTL tick: `sweepExpiredOnWrite` puts
+ * `sweepExpired` on hot write paths, and a directory scan does not belong there.
+ */
+export function reclaimAbandonedResponseStateTemps(
+ options: ResponseStateTempRecoveryOptions = {},
+): ResponseStateTempRecoveryResult {
+ const total: ResponseStateTempRecoveryResult = {
+ matched: 0, removed: 0, failed: 0, bytesRemoved: 0, eligible: 0, eligibleBytes: 0, truncated: false,
+ };
+ // The try encloses responseStateSweepDirectories() deliberately: recoverStaleResponseStateTemps
+ // already swallows its own enumeration failures, so a catch around only that call would be
+ // unreachable. snapshotPath()/getConfigDir() are the paths that can genuinely throw.
+ try {
+ for (const dir of responseStateSweepDirectories()) {
+ const result = recoverStaleResponseStateTemps(dir, options);
+ total.matched += result.matched;
+ total.removed += result.removed;
+ total.failed += result.failed;
+ total.bytesRemoved += result.bytesRemoved;
+ total.eligible += result.eligible;
+ total.eligibleBytes += result.eligibleBytes;
+ // Truncation anywhere makes the whole total a prefix.
+ total.truncated ||= result.truncated;
+ }
+ } catch {
+ /* best-effort: disk reclaim must never destabilize the caller */
+ }
+ return total;
+}
+
+/**
+ * Report-only counterpart for `ocx doctor`: applies every selection gate and unlinks
+ * nothing. It runs the SAME predicate as the reclaim, so the report and the subsequent
+ * removal cannot disagree about which files are reclaimable.
+ */
+export function inspectAbandonedResponseStateTemps(): ResponseStateTempRecoveryResult {
+ return reclaimAbandonedResponseStateTemps({ dryRun: true });
+}
+
+/** Sweeper adapter: narrows the reclaim to the `() => number` the liveness tick expects. */
+export function sweepAbandonedResponseStateTemps(): number {
+ return reclaimAbandonedResponseStateTemps({
+ maxEntries: PERIODIC_TEMP_MAX_ENTRIES,
+ maxCleanups: PERIODIC_TEMP_MAX_CLEANUPS,
+ deadlineMs: PERIODIC_TEMP_SCAN_DEADLINE_MS,
+ }).removed;
+}
+
export function responseContinuationRetainedStoreSnapshot(): RetainedStoreSnapshot {
return {
count: states.size,
diff --git a/src/router.ts b/src/router.ts
index 723ff8ca84..297795180e 100644
--- a/src/router.ts
+++ b/src/router.ts
@@ -8,10 +8,15 @@ import {
type ComboPick,
} from "./combos";
import type { NormalizedComboConfig } from "./combos/types";
-import { hasOwnProvider, resolveEnvValue } from "./config";
+import { hasOwnProvider } from "./config/provider-name";
+import { resolveEnvValue } from "./config";
import { assertProviderDestinationAllowed } from "./lib/destination-policy";
import { redactSecretString, redactUrlForLog } from "./lib/redact";
-import { PROVIDER_REGISTRY, providerCodexAccountMode } from "./providers/registry";
+import {
+ PROVIDER_REGISTRY,
+ providerCodexAccountMode,
+ registryModelServiceTierCapabilityApplies,
+} from "./providers/registry";
import { applyDirectReasoningEffortContracts, hasLegacyClinePassReasoningEfforts } from "./providers/derive";
import { cloneFastWire } from "./providers/fastwire";
import {
@@ -296,7 +301,9 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
: mergeRecordFill(registryEntry.modelMaxInputTokens, provider.modelMaxInputTokens);
const modelMaxOutputTokens = mergeRecordFill(registryEntry.modelMaxOutputTokens, provider.modelMaxOutputTokens);
const modelSupportsServiceTier = mergeRecordFill(
- registryEntry.modelSupportsServiceTier,
+ registryModelServiceTierCapabilityApplies(registryEntry, provider)
+ ? registryEntry.modelSupportsServiceTier
+ : undefined,
provider.modelSupportsServiceTier,
);
const noVisionModels = mergeStringArray(registryEntry.noVisionModels, provider.noVisionModels);
diff --git a/src/routing/compatibility/behavior.ts b/src/routing/compatibility/behavior.ts
index fce2ff004d..5abf08f17d 100644
--- a/src/routing/compatibility/behavior.ts
+++ b/src/routing/compatibility/behavior.ts
@@ -1,7 +1,7 @@
import { modelInList } from "../../types";
import type { OcxConfig, OcxProviderConfig } from "../../types";
import { PROVIDER_REGISTRY } from "../../providers/registry";
-import { fastPolicyForModel, serviceTierSupportForModel } from "../../providers/service-tier";
+import { fastPolicyForModel, serviceTierSupportFromPolicy } from "../../providers/service-tier";
import { resolveProviderAuthTransport } from "../../providers/fastwire";
import { localFingerprint } from "../../lab/digest";
import type { LabBehaviorSource, LabBehaviorValues } from "../../lab/live/types";
@@ -103,7 +103,7 @@ export function resolveProductionBehaviorValues(
const project = typeof effective.project === "string" && effective.project ? effective.project : null;
const location = typeof effective.location === "string" && effective.location ? effective.location : null;
const nativeLocalExec = effective.nativeLocalExec === "on" || effective.unsafeAllowNativeLocalExec === true;
- const fastPolicy = fastPolicyForModel(effective, modelId, providerName);
+ const fastPolicy = fastPolicyForModel(effective, modelId, providerName, "responses", provider);
const values: LabBehaviorValues = {
"wire.adapter": behaviorRow("provider_config", adapter),
@@ -122,7 +122,7 @@ export function resolveProductionBehaviorValues(
"responses.stateful": behaviorRow("provider_config", effective.statelessResponses !== true),
"responses.serviceTier": behaviorRow(
"provider_config",
- serviceTierSupportForModel(effective, modelId, providerName) ?? null,
+ serviceTierSupportFromPolicy(fastPolicy) ?? null,
),
"responses.fastWireKind": behaviorRow(
"provider_config",
diff --git a/src/routing/profile.ts b/src/routing/profile.ts
index 17e07d6b04..6c978de94a 100644
--- a/src/routing/profile.ts
+++ b/src/routing/profile.ts
@@ -13,7 +13,7 @@ import type {
} from "../types";
import { codexAccountNamespaceEntries } from "../codex/account-namespaces";
import { listComboIds, resolveComboId } from "../combos";
-import { hasOwnProvider } from "../config";
+import { hasOwnProvider } from "../config/provider-name";
import { MAX_COMPATIBILITY_REQUIRED_SUITES } from "./compatibility/types";
import { POLICY_NAMESPACE } from "./profile-namespace";
diff --git a/src/server/index.ts b/src/server/index.ts
index 8f43b8fdf1..b33e3f1750 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -705,6 +705,11 @@ export function startServer(port?: number, deps: StartServerDeps = {}): Server inspectStartupOwnership(deps).ownership },
)
: {
homeId: null,
diff --git a/src/server/management/shared.ts b/src/server/management/shared.ts
index 77d1f74264..3ebea685e8 100644
--- a/src/server/management/shared.ts
+++ b/src/server/management/shared.ts
@@ -86,7 +86,8 @@ export type CostEstimateReason =
| "usage_estimated"
| "cache_detail_missing"
| "expected_price_overlay"
- | "provider_cost_overlay";
+ | "provider_cost_overlay"
+ | "priority_lower_bound";
export type CostResult =
| { kind: "value"; estimate: NonNullable>; estimateReasons: CostEstimateReason[] }
@@ -143,6 +144,7 @@ export function costResult(entry: MetricSource): CostResult {
? "expected_price_overlay" as const : undefined,
estimate.price?.source === "user" || estimate.attempts?.some(a => a.price.source === "user")
? "provider_cost_overlay" as const : undefined,
+ estimate.priorityLowerBound ? "priority_lower_bound" as const : undefined,
].filter((reason): reason is CostEstimateReason => reason !== undefined);
return { kind: "value", estimate, estimateReasons };
}
diff --git a/src/server/responses/collaboration.ts b/src/server/responses/collaboration.ts
index 37fca4777f..7c671a7de4 100644
--- a/src/server/responses/collaboration.ts
+++ b/src/server/responses/collaboration.ts
@@ -101,22 +101,23 @@ import type { TranslatorBudget } from "../../lib/translator-budget";
export function buildToolBridgeMaps(parsed: OcxParsedRequest, budget?: TranslatorBudget): {
- toolNsMap: Map;
+ toolNsMap: Map;
declaredToolNames: Set;
/** Declared parameter schema per request-visible tool name (#1611 integer repair). */
toolParameterSchemas: Map>;
freeformToolNames: Set;
toolSearchToolNames: Set;
} {
- const toolNsMap = new Map();
+ const toolNsMap = new Map();
const declaredToolNames = new Set();
const toolParameterSchemas = new Map>();
const freeformToolNames = new Set();
const toolSearchToolNames = new Set();
- const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice);
- for (const t of parsed.context.tools ?? []) {
+ const requestedTools = parsed.context.tools ?? [];
+ const toolAllowed = toolChoiceToolPredicate(parsed.options.toolChoice, requestedTools);
+ const authorizedTools = requestedTools.filter(toolAllowed);
+ for (const t of authorizedTools) {
// Upstream output is untrusted: only restore calls for tools the caller authorized.
- if (!toolAllowed(t)) continue;
const wireName = namespacedToolName(t.namespace, t.name);
budget?.chargeRetained(new TextEncoder().encode(wireName).byteLength, { kind: "retained_collectors" });
declaredToolNames.add(wireName);
@@ -125,7 +126,7 @@ export function buildToolBridgeMaps(parsed: OcxParsedRequest, budget?: Translato
if (t.parameters && typeof t.parameters === "object") toolParameterSchemas.set(wireName, t.parameters);
if (t.namespace) {
budget?.chargeRetained(new TextEncoder().encode(JSON.stringify([wireName, t.namespace, t.name])).byteLength, { kind: "retained_collectors" });
- toolNsMap.set(wireName, { namespace: t.namespace, name: t.name });
+ toolNsMap.set(wireName, { namespace: t.namespace, name: t.name, ...(t.freeform ? { freeform: true } : {}) });
}
if (t.freeform) {
budget?.chargeRetained(new TextEncoder().encode(t.name).byteLength, { kind: "retained_collectors" });
@@ -136,6 +137,29 @@ export function buildToolBridgeMaps(parsed: OcxParsedRequest, budget?: Translato
toolSearchToolNames.add(t.name);
}
}
+ // Some routed providers echo a bare tool_choice selector instead of the flattened catalog
+ // name. Accept only selectors the client actually sent and only when the full request catalog
+ // contains one tool with that logical name.
+ const choice = parsed.options.toolChoice;
+ const bareChoiceNames = new Set(
+ choice && typeof choice === "object"
+ ? ("allowedTools" in choice ? choice.allowedTools : [choice.name])
+ : [],
+ );
+ const bareNameCounts = new Map();
+ for (const t of requestedTools) {
+ bareNameCounts.set(t.name, (bareNameCounts.get(t.name) ?? 0) + 1);
+ }
+ for (const t of authorizedTools) {
+ if (!t.namespace || !bareChoiceNames.has(t.name) || bareNameCounts.get(t.name) !== 1 || declaredToolNames.has(t.name)) continue;
+ budget?.chargeRetained(new TextEncoder().encode(t.name).byteLength, { kind: "retained_collectors" });
+ declaredToolNames.add(t.name);
+ budget?.chargeRetained(new TextEncoder().encode(JSON.stringify([t.name, t.namespace, t.name])).byteLength, { kind: "retained_collectors" });
+ toolNsMap.set(t.name, { namespace: t.namespace, name: t.name, ...(t.freeform ? { freeform: true } : {}) });
+ if (t.parameters && typeof t.parameters === "object") {
+ toolParameterSchemas.set(t.name, t.parameters);
+ }
+ }
return { toolNsMap, declaredToolNames, toolParameterSchemas, freeformToolNames, toolSearchToolNames };
}
@@ -197,7 +221,8 @@ export interface MultiAgentGuidanceDeps {
configuredModels: readonly string[],
surface: SpawnAgentSurface,
) => EffectiveSubagentRoster | Promise;
- collectCatalogState?: () => { state: "fresh" | "stale" | "not_running" | "unknown" };
+ collectCatalogState?: () => { state: "fresh" | "stale" | "not_running" | "unknown" }
+ | Promise<{ state: "fresh" | "stale" | "not_running" | "unknown" }>;
}
async function defaultCollectCatalogState(): Promise<{ state: "fresh" | "stale" | "not_running" | "unknown" }> {
@@ -207,8 +232,8 @@ async function defaultCollectCatalogState(): Promise<{ state: "fresh" | "stale"
if (override === "fresh" || override === "stale" || override === "not_running" || override === "unknown") {
return { state: override };
}
- const { collectCodexAppServerCatalogState } = await import("../../codex/app-server-processes");
- return collectCodexAppServerCatalogState();
+ const { collectCodexAppServerCatalogStateForRequest } = await import("../../codex/app-server-processes");
+ return collectCodexAppServerCatalogStateForRequest();
}
diff --git a/src/server/responses/core.ts b/src/server/responses/core.ts
index 8d2906e536..9e2813d0b5 100644
--- a/src/server/responses/core.ts
+++ b/src/server/responses/core.ts
@@ -1238,6 +1238,7 @@ async function applyFinalRouteRequestNormalization(args: {
route.modelId,
route.providerName,
inboundWire,
+ config.providers[route.providerName],
);
const modelServiceTierSupport = serviceTierSupportFromPolicy(fastPolicy);
const callerTier = parsed.options.serviceTier;
@@ -4348,9 +4349,9 @@ async function handleResponsesInner(
const detachContinuationBodyGuard = cancelBodyOnAbort(response.body, upstream.signal);
try {
if (nextParsed.stream) {
- yield* activeAdapter.parseStream(response, translatorBudget);
+ yield* activeAdapter.parseStream(response, translatorBudget, logCtx.activeTierMetadata);
} else if (activeAdapter.parseResponse) {
- yield* await activeAdapter.parseResponse(response, translatorBudget);
+ yield* await activeAdapter.parseResponse(response, translatorBudget, logCtx.activeTierMetadata);
} else {
yield { type: "error", message: "Provider continuation does not support response parsing" };
}
@@ -4380,7 +4381,11 @@ async function handleResponsesInner(
};
if (parsed.stream) {
- const initialEventStream = activeAdapter.parseStream(upstreamResponse, translatorBudget);
+ const initialEventStream = activeAdapter.parseStream(
+ upstreamResponse,
+ translatorBudget,
+ logCtx.activeTierMetadata,
+ );
const eventStream = terminalGuardEnabled
? guardTerminalEventStream({
parsed,
@@ -4448,7 +4453,11 @@ async function handleResponsesInner(
if (activeAdapter.parseResponse) {
let events: AdapterEvent[];
try {
- const initialEvents = await activeAdapter.parseResponse(upstreamResponse, translatorBudget);
+ const initialEvents = await activeAdapter.parseResponse(
+ upstreamResponse,
+ translatorBudget,
+ logCtx.activeTierMetadata,
+ );
let guardedEvents: AdapterEvent[];
if (terminalGuardEnabled) {
guardedEvents = [];
diff --git a/src/server/responses/input-admission.ts b/src/server/responses/input-admission.ts
index 219c3b6f89..a2a06e5b73 100644
--- a/src/server/responses/input-admission.ts
+++ b/src/server/responses/input-admission.ts
@@ -13,6 +13,7 @@
import { nativeOpenAiContextWindow, nativeOpenAiMaxInputTokens, type NativeContextLimitsInput } from "../../codex/catalog/metadata";
import { estimateTokens } from "../../lib/token-estimate";
import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
+import { modelRecordValue } from "../../reasoning-effort";
import type { OcxContentPart, OcxParsedRequest, OcxProviderConfig } from "../../types";
/**
@@ -133,7 +134,11 @@ export function resolveInputCeiling(
// config here so this stays pure: no filesystem, no catalog, no registry scan.
nativeContextCap?: NativeContextLimitsInput,
): number | null {
- const configured = positive(provider.modelContextWindows?.[modelId]) ?? positive(provider.contextWindow);
+ // `modelRecordValue`, not a bare lookup: the catalog resolves these same two maps that
+ // way, so a `gpt-oss` entry covers `gpt-oss:120b`. Reading raw here made the gate fall
+ // back to the provider-wide window and refuse turns the model can plainly hold.
+ const configured = positive(modelRecordValue(provider.modelContextWindows, modelId))
+ ?? positive(provider.contextWindow);
// The canonical `openai` registry entry declares no context fields, so without this the
// gate would be inert on the default Codex route. All three clauses are load-bearing: a
@@ -156,7 +161,7 @@ export function resolveInputCeiling(
const window = canonicalNativeBare ? native : configured;
// modelMaxInputTokens is an input-only cap, so it can only tighten the window.
- const configuredMaxInput = positive(provider.modelMaxInputTokens?.[modelId]);
+ const configuredMaxInput = positive(modelRecordValue(provider.modelMaxInputTokens, modelId));
const limits = [window, configuredMaxInput, nativeMaxInput].filter((v): v is number => v !== null);
return limits.length === 0 ? null : Math.min(...limits);
}
diff --git a/src/service-manager-probe.ts b/src/service-manager-probe.ts
index 8446c78ae5..670e55e4f8 100644
--- a/src/service-manager-probe.ts
+++ b/src/service-manager-probe.ts
@@ -179,6 +179,86 @@ function unitEnvValue(body: string, key: string): string | null {
return null;
}
+/**
+ * Did `systemctl --user` fail because the session bus could not be reached at all?
+ *
+ * These are the shapes reported on #2114 and #1939. The distinction that matters is
+ * "the question never left the machine" versus "systemd answered and said no" — only
+ * the former licenses reading the disk instead.
+ *
+ * **Locale caveat, stated rather than hidden:** systemd localizes these strings, so a
+ * non-English host will not match and keeps the old `unknown`. That is the safe
+ * direction — it fences rather than admits — but it does mean the fix does not reach
+ * every affected user. Forcing `LC_ALL=C` on the probe would remove the caveat and is
+ * the obvious follow-up; it is not done here because it changes every systemctl call
+ * this module makes, not just this branch.
+ */
+function busUnreachable(stderr: string): boolean {
+ const err = stderr.trim();
+ return err.includes("Failed to connect to bus")
+ || err.includes("Failed to connect to user scope bus")
+ || err.includes("Failed to get D-Bus connection")
+ || err.includes("DBUS_SESSION_BUS_ADDRESS")
+ || err.includes("System has not been booted with systemd");
+}
+
+/**
+ * Ownership from the unit file alone, for when the bus cannot answer (#2114).
+ *
+ * A unit file is proof of installation that does not require a running bus, and the homes
+ * it names are what ownership is actually decided on. What the disk cannot tell us is
+ * whether systemd has the unit LOADED, so this reports `registration: "absent"` — the
+ * honest reading of "no running manager has it" — rather than inventing a live state.
+ *
+ * A foreign home therefore still blocks, which is the whole reason this consults the disk
+ * instead of widening the exit code.
+ */
+function systemdUserUnitSearchPaths(home: string): string[] {
+ // systemd's user search path is not one directory. Checking only the canonical one and
+ // calling the rest absent is a fail-open: with the bus down a foreign unit in any other
+ // search dir is invisible, and "no answer" would be read as "no owner".
+ const xdgConfig = process.env.XDG_CONFIG_HOME?.trim();
+ const xdgData = process.env.XDG_DATA_HOME?.trim();
+ const dirs = [
+ xdgConfig ? join(xdgConfig, "systemd", "user") : join(home, ".config", "systemd", "user"),
+ join(home, ".config", "systemd", "user"),
+ xdgData ? join(xdgData, "systemd", "user") : join(home, ".local", "share", "systemd", "user"),
+ join(home, ".local", "share", "systemd", "user"),
+ ];
+ return [...new Set(dirs)].map(dir => join(dir, `${TASK}.service`));
+}
+
+function inspectSystemdOffline(home: string): ServiceManagerInstallation {
+ const candidates = systemdUserUnitSearchPaths(home);
+ const found = candidates.filter(path => artifactPresence(path) === "present");
+ if (candidates.some(path => artifactPresence(path) === "unreadable")) {
+ return unknown("the session bus is unreachable and a systemd unit could not be read");
+ }
+ if (found.length === 0) return { kind: "absent" };
+ if (found.length > 1) {
+ return unknown("the session bus is unreachable and more than one systemd unit file claims this proxy");
+ }
+ const definitionPath = found[0]!;
+ let body: string;
+ try {
+ body = readFileSync(definitionPath, "utf-8");
+ } catch (error) {
+ return unknown(`the session bus is unreachable and the systemd unit could not be read: ${String(error)}`);
+ }
+ return {
+ kind: "present",
+ claims: [{
+ backend: "systemd",
+ definitionPath,
+ homes: {
+ codexHome: unitEnvValue(body, "CODEX_HOME"),
+ opencodexHome: unitEnvValue(body, "OPENCODEX_HOME"),
+ },
+ registration: "absent",
+ }],
+ };
+}
+
function inspectLaunchd(deps: Required>): ServiceManagerInstallation {
const definitionPath = join(deps.home, "Library", "LaunchAgents", `${LABEL}.plist`);
@@ -269,6 +349,15 @@ function inspectSystemd(deps: Required>): Servic
if (shown.status !== 0) {
// A missing unit still exits ZERO and says not-found; a non-zero status means
// the question never reached the bus.
+ //
+ // That is evidence about the BUS, not evidence that a foreign service owns this home
+ // (#2114). Calling it `unknown` fences native-main for the whole process, so a laptop
+ // with no session bus answers every native request with a 503 until `ocx restart`.
+ //
+ // Widening on the exit code alone would fail open, because with the bus down systemctl
+ // cannot see a foreign unit either. So ask the disk, which needs no bus, and fall back
+ // to `unknown` for every other non-zero exit.
+ if (busUnreachable(shown.stderr)) return inspectSystemdOffline(deps.home);
return unknown(`systemctl show exited ${String(shown.status)}: ${shown.stderr.trim()}`);
}
@@ -729,6 +818,16 @@ function walkWinswChain(
const registration = probeWinswRegistration(deps);
if (xml === "absent" && exe === "absent" && registration === "absent") return { kind: "absent" };
+ // A query we could not ask is a question about a service that cannot exist: WinSW is an
+ // optional backend, and with neither its XML nor its exe on disk there is nothing for a
+ // registration to belong to. Fencing here on an `sc.exe` timeout is one of the two
+ // triggers behind #2108, where a scheduler-only install answers 503 until `ocx restart`.
+ //
+ // The disk outranks the unaskable query only when BOTH assets are gone. Either one
+ // present means a real install may be there and the old `unknown` still holds.
+ if (registration === "unknown" && xml === "absent" && exe === "absent") {
+ return { kind: "absent" };
+ }
if (registration === "unknown") {
return unknown("the native WinSW service registration could not be verified");
}
diff --git a/src/service.ts b/src/service.ts
index 8ba2b417b1..a00e616ba1 100644
--- a/src/service.ts
+++ b/src/service.ts
@@ -19,6 +19,7 @@ import { BUN_RUNTIME_PATH_ENV, BUN_RUNTIME_SOURCE_ENV, durableBunRuntime } from
import type { BunRuntimeSource } from "./lib/bun-runtime";
import { isProcessAlive, stopProxy } from "./lib/process-control";
import { serviceApiTokenFilePath } from "./lib/service-secrets";
+import { PROXY_ENV_KEYS } from "./lib/proxy-env";
import { randomUUID } from "node:crypto";
import {
ELEVATION_REQUEST_TIMEOUT_MS,
@@ -389,7 +390,7 @@ function writeServiceApiTokenFile(): string | null {
return path;
}
-export function buildPlist(): string {
+export function buildPlist(proxyEnv: { name: string; value: string }[] = resolvedProxyEnv()): string {
const { bun, bunRuntimeSource, cli } = cliEntry();
const log = logPath();
const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
@@ -404,6 +405,8 @@ export function buildPlist(): string {
codexHome ? ` CODEX_HOME${plistString(codexHome)}` : null,
codexSqliteHome ? ` CODEX_SQLITE_HOME${plistString(codexSqliteHome)}` : null,
opencodexHome ? ` OPENCODEX_HOME${plistString(opencodexHome)}` : null,
+ ...proxyEnv.map(({ name, value }) =>
+ ` ${name}${plistString(value)}`),
].filter((line): line is string => Boolean(line)).join("\n");
const command = buildServiceShellCommand(bun, cli);
return `
@@ -640,6 +643,31 @@ function systemdEnvironmentAssignment(name: string, value: string | undefined):
return `Environment=${systemdQuote(`${name}=${value}`)}`;
}
+/**
+ * Outbound proxy settings the installing shell had, resolved for baking into a service
+ * definition.
+ *
+ * A service manager does not inherit the environment of the shell that installed it, and
+ * `ExecStart=/bin/sh -lc` is dash on Ubuntu/WSL — login dash reads `.profile`, not
+ * `.bashrc`, which is where proxy exports usually live. So a user who needs a proxy to
+ * reach the upstream got a service that dialed direct: the socket was reset, the retry
+ * budget drained, and the request surfaced as `502 Provider unreachable` (#2107). The
+ * same install driven through `ocx codex-shim` worked, because that path spawns with
+ * `{ ...process.env }`.
+ *
+ * Lower-case variants are honored because curl-style tooling sets them and the runtime's
+ * own `applyProxyEnv` already treats both cases as equivalent. Only the canonical
+ * upper-case name is baked, so a definition never carries two spellings of one setting.
+ */
+export function resolvedProxyEnv(env: NodeJS.ProcessEnv = process.env): { name: string; value: string }[] {
+ const resolved: { name: string; value: string }[] = [];
+ for (const key of PROXY_ENV_KEYS) {
+ const value = env[key]?.trim() || env[key.toLowerCase()]?.trim();
+ if (value) resolved.push({ name: key, value });
+ }
+ return resolved;
+}
+
function systemdOutputTarget(value: string): string {
// StandardOutput/StandardError use output specifiers such as append:/path.
// Quoting the full specifier makes systemd reject it as an invalid output target.
@@ -1513,7 +1541,11 @@ function taskXmlRunLevelAcceptable(principal: string): boolean {
return value === "leastprivilege" || value === "highestavailable";
}
-export function buildWindowsServiceScript(entry = cliEntry(), port = resolveServiceListenPort()): string {
+export function buildWindowsServiceScript(
+ entry = cliEntry(),
+ port = resolveServiceListenPort(),
+ proxyEnv: { name: string; value: string }[] = resolvedProxyEnv(),
+): string {
// Provenance rides along with the entry: a second durableBunRuntime() call here could
// resolve differently from the binary the caller actually baked.
const { bun, bunRuntimeSource, cli } = entry;
@@ -1531,6 +1563,7 @@ export function buildWindowsServiceScript(entry = cliEntry(), port = resolveServ
windowsBatchSet("CODEX_HOME", process.env.CODEX_HOME?.trim(), "path"),
windowsBatchSet("CODEX_SQLITE_HOME", currentCodexSqliteHomeAbsolute("windows"), "path"),
windowsBatchSet("OPENCODEX_HOME", process.env.OPENCODEX_HOME?.trim(), "path"),
+ ...proxyEnv.map(({ name, value }) => windowsBatchSet(name, value)),
windowsBatchSet("OCX_API_TOKEN_FILE", serviceApiTokenFilePath(), "path"),
windowsBatchSet("OCX_SERVICE_LOG", serviceLogPath(), "path"),
windowsBatchSet("OCX_BUN", bun, "path"),
@@ -1852,7 +1885,7 @@ function installLaunchd(): void {
// Capture this BEFORE writing: the write below makes the plist exist unconditionally,
// so a post-write existsSync would call every fresh install an "installed" service.
const wasInstalled = existsSync(p);
- writeFileSync(p, buildPlist(), "utf8");
+ writeServiceDefinitionFile(p, buildPlist(), "utf8");
// Best-effort: an absent job is fine here, and a failed unload is caught by the
// load verification below with a better message than a raw unload error.
runLaunchctl(["unload", p]);
@@ -1915,6 +1948,52 @@ function uninstallLaunchd(): void {
if (existsSync(p)) unlinkSync(p);
}
+/**
+ * Write a service definition with owner-only permissions.
+ *
+ * These files carry the outbound proxy environment (#2107), and a proxy URL routinely
+ * carries `user:password`. `writeFileSync` without a mode lands at 0644 under the default
+ * umask, so the credential would be world-readable on a shared host. Every other
+ * secret-bearing write in this file already uses 0600 — the service API token and the
+ * install state — and a service definition holding a proxy credential belongs in the same
+ * class.
+ *
+ * The explicit `chmodSync` is not redundant: `mode` only applies when the file is
+ * created, so an install over a definition left at 0644 by an earlier version would keep
+ * the loose mode.
+ *
+ * On Windows the POSIX bits are advisory, so the ACL is the real boundary — and whether it
+ * may soft-fail depends on what the definition actually contains. A definition carrying a
+ * proxy credential is a secret publication and fails closed like the API token and the
+ * install state do; one carrying only paths and a port is not worth refusing an install
+ * over, since before #2107 these files had no hardening at all and a failure here would
+ * regress a user who has no credential to protect.
+ */
+export function writeServiceDefinitionFile(path: string, content: string, encoding: "utf8" | "utf16le"): void {
+ writeFileSync(path, content, { encoding, mode: 0o600 });
+ try { chmodSync(path, 0o600); } catch { /* superseded by the Windows ACL below */ }
+ if (process.platform === "win32") {
+ hardenSecretPath(path, { required: definitionCarriesCredential(content) });
+ }
+}
+
+/**
+ * Does this service definition embed a credential-bearing proxy URL?
+ *
+ * Only the userinfo form leaks something: `http://user:pass@host` in any of the four proxy
+ * variables. A bare `http://127.0.0.1:7890` is not a secret, and treating it as one would
+ * make an icacls stall fail an install that had nothing to protect.
+ *
+ * The scan is over any URL in the rendered definition rather than over a `KEY=value` shape,
+ * because the three formats render differently — systemd writes `Environment="K=V"`, the
+ * plist writes `KV`, and the Windows wrapper writes
+ * `set "K=V"`. Keying on the assignment syntax silently missed the plist.
+ */
+export function definitionCarriesCredential(content: string): boolean {
+ // A userinfo authority: scheme, then anything that is not a delimiter, then '@'.
+ return /[a-z][a-z0-9+.-]*:\/\/[^\s"'<>/@]+@/i.test(content);
+}
+
// ── Windows (Task Scheduler) ──
/**
* In-place service-asset write that tolerates the transient EBUSY/EPERM/EACCES Windows
@@ -1923,7 +2002,7 @@ function uninstallLaunchd(): void {
function writeServiceAssetWithRetry(path: string, content: string, encoding: "utf8" | "utf16le"): void {
for (let attempt = 0; ; attempt++) {
try {
- writeFileSync(path, content, encoding);
+ writeServiceDefinitionFile(path, content, encoding);
return;
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
@@ -2415,7 +2494,7 @@ function unitPath(): string {
return join(unitDir(), `${TASK}.service`);
}
-export function buildUnit(): string {
+export function buildUnit(proxyEnv: { name: string; value: string }[] = resolvedProxyEnv()): string {
const { bun, bunRuntimeSource, cli } = cliEntry();
const log = logPath();
const path = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
@@ -2430,6 +2509,7 @@ export function buildUnit(): string {
codexHome,
codexSqliteHome,
opencodexHome,
+ ...proxyEnv.map(({ name, value }) => systemdEnvironmentAssignment(name, value)),
].filter((line): line is string => Boolean(line)).join("\n");
return `[Unit]
Description=OpenCodex Proxy Server
@@ -2490,7 +2570,7 @@ function installSystemd(): void {
recordOwnedConfigPath(getConfigDir(), serviceStatePath());
if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
writeServiceApiTokenFile();
- writeFileSync(unitPath(), buildUnit(), "utf8");
+ writeServiceDefinitionFile(unitPath(), buildUnit(), "utf8");
sh("systemctl --user daemon-reload");
sh(`systemctl --user enable ${TASK}`);
sh(`systemctl --user restart ${TASK}`);
diff --git a/src/tray/windows.ts b/src/tray/windows.ts
index 08c7619d7e..cefb61c3ee 100644
--- a/src/tray/windows.ts
+++ b/src/tray/windows.ts
@@ -9,6 +9,7 @@ import type { BunRuntimeSource } from "../lib/bun-runtime";
import { forgetEphemeralSecretPath, hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
import { recordOwnedConfigPath } from "../lib/config-ownership";
import { renameAtomicFile } from "../lib/windows-atomic-replace";
+import { decodeWindowsTextBytes } from "../lib/windows-text";
const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
const RUN_PARENT_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion";
@@ -117,12 +118,31 @@ function registryExe(): string {
return existsSync(candidate) ? candidate : "reg.exe";
}
+/**
+ * Decode `reg.exe` output the way the rest of the product decodes Windows console
+ * output.
+ *
+ * `reg.exe` writes the console ANSI code page when its output is redirected, not
+ * UTF-8. Reading it as utf8 corrupts every non-ASCII byte, so a profile path such
+ * as `C:\Users\Mtz` came back with replacement characters, the
+ * comparison against the value we wrote could never match, `registrationOwned`
+ * went false, and the CLI reported the tray registration as
+ * "foreign, stale, or points to missing package files" over an entry that was
+ * correct and owned (#1933).
+ *
+ * `decodeWindowsTextBytes` already solves this for `schtasks` (#1573). The tray
+ * reader was the site that class fix missed.
+ */
+function decodeRegistryOutput(stdout: Buffer | string): string {
+ const bytes = typeof stdout === "string" ? Buffer.from(stdout, "binary") : stdout;
+ return decodeWindowsTextBytes(bytes).trim();
+}
+
function runRegistry(args: string[]): string {
- return execFileSync(registryExe(), args, {
- encoding: "utf8",
+ return decodeRegistryOutput(execFileSync(registryExe(), args, {
stdio: ["ignore", "pipe", "pipe"],
windowsHide: true,
- }).trim();
+ }));
}
function safePath(value: string): string {
@@ -335,13 +355,13 @@ function readOwnedRunValue(runValue = windowsTrayRunValue(getConfigDir())): stri
function runRegistryAsync(args: string[]): Promise {
return new Promise((resolvePromise, rejectPromise) => {
execFile(registryExe(), args, {
- encoding: "utf8",
+ encoding: "buffer",
timeout: 2_000,
windowsHide: true,
maxBuffer: 64 * 1024,
}, (error, stdout) => {
if (error) rejectPromise(error);
- else resolvePromise(stdout.trim());
+ else resolvePromise(decodeRegistryOutput(stdout));
});
});
}
diff --git a/src/types.ts b/src/types.ts
index 77c88be200..f474695ca7 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,1884 +1,104 @@
-import type { KiroOAuthMetadata } from "./oauth/types";
+// AUTO-SPLIT barrel: src/types.ts re-exports every historical name; bodies live in src/types/*.
+// Values (runtime): tools + wire. Types (erased): request + config + provider + accounts.
+
+export type { OcxTool, OcxToolChoice } from "./types/tools";
+export {
+ namespacedToolName,
+ toolChoiceAliases,
+ toolChoiceCandidates,
+ toolAllowedByChoice,
+ resolveToolChoiceWireName,
+ modelInList,
+ isAllowedToolChoice,
+ toolChoiceToolPredicate,
+} from "./types/tools";
+
+export type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./types/wire";
+export {
+ UPSTREAM_HTTP_VERSION_VALUES,
+ REASONING_SUMMARY_DELIVERY_VALUES,
+ OPENAI_PROVIDER_TIER_VERSION,
+ MODEL_ADAPTER_OVERRIDE_ALLOWED,
+ captureWireAdapterHardPins,
+ isWirePinnedModel,
+ pinnedWireAdapter,
+} from "./types/wire";
+
+export type {
+ OcxReasoningReplayIdentity,
+ OcxReasoningReplayScopeRef,
+ OcxParsedRequest,
+ OcxContext,
+ OcxMessage,
+ OcxUserMessage,
+ OcxAssistantMessage,
+ OcxDeveloperMessage,
+ OcxToolResultMessage,
+ OcxTextContent,
+ OcxImageContent,
+ OcxContentPart,
+ OcxThinkingContent,
+ OcxToolCall,
+ OcxProviderOpaqueToolCallMetadata,
+ OcxAssistantContentPart,
+ OcxRequestOptions,
+ OcxMessagePhase,
+ OcxProviderContinuationState,
+ AdapterEvent,
+ OcxUrlCitation,
+ OcxUsage,
+} from "./types/request";
+
+export type {
+ OcxClaudeCodeConfig,
+ OcxClaudeDesktopFamily,
+ OcxClaudeDesktopAssignment,
+ OcxClaudeDesktopProfile,
+ StorageCleanupPolicy,
+ OcxCustomModel,
+ OcxApiKeyEntry,
+ OcxClientIntegrationsConfig,
+ OcxConfig,
+ OcxAccountPoolRotationStrategy,
+ OcxComboStrategy,
+ OcxComboDefaultEffort,
+ OcxComboTarget,
+ OcxComboConfig,
+ OcxRoutingUnknownEvidenceMode,
+ OcxRoutingProfileCandidate,
+ OcxRoutingProfileRequirements,
+ OcxRoutingProfileOptimize,
+ OcxRoutingUnknownCostCapMode,
+ OcxRoutingProfileLimits,
+ OcxRoutingProfileUnknownEvidence,
+ OcxRoutingProfileCompatibilitySuite,
+ OcxRoutingProfileCompatibility,
+ OcxRoutingProfileConfig,
+ OcxTokenGuardianConfig,
+ OcxImagesConfig,
+ OcxSearchConfig,
+ OcxVisionSidecarConfig,
+ OcxWebSearchSidecarConfig,
+} from "./types/config";
+
+export type {
+ RefreshPolicy,
+ OpenRouterProviderRouting,
+ ResponsesItemIdRepairConfig,
+ RateLimitRetryPolicy,
+ ProviderCostOverlay,
+ RequestPacingRule,
+ ProviderRequestPacingConfig,
+ FastWire,
+ AttemptTierOutcome,
+ TierObservationContext,
+ TierDecision,
+ OcxProviderConfig,
+} from "./types/provider";
+
+export type {
+ CodexAccount,
+ CodexAccountCredentials,
+ CodexAccountCredentialRecord,
+} from "./types/accounts";
-/** Exact provider/credential namespace for process-local reasoning replay. */
-export interface OcxReasoningReplayIdentity {
- providerName: string;
- /** Opaque process-local digest of the exact upstream destination. */
- providerDestinationIdentity: string;
- /**
- * The same destination, digested WITHOUT the process-local random key, so it can key a
- * durable store. Absent when no base URL was resolvable.
- */
- providerDestinationDurableIdentity?: string;
- adapterName: string;
- modelId: string;
- /** Opaque process-local credential identity; never a raw token or API key. */
- credentialIdentity: string;
- /**
- * Salted-HMAC credential identity that survives restarts, for the durable
- * thought-signature store (#1926). Absent when no durable identity could be
- * derived — the durable store then refuses to key the entry (fail closed).
- */
- credentialDurableIdentity?: string;
-}
-
-/**
- * Stable holder shared by parsed-request copies and already-created bridges.
- * Credential/provider rotation replaces `current` atomically without replacing
- * the holder, so late tool-call cache writes see the active physical identity.
- */
-export interface OcxReasoningReplayScopeRef {
- readonly clientThreadId: string;
- current?: Readonly;
-}
-
-export interface OcxParsedRequest {
- modelId: string;
- /** Client-facing model selector retained for Anthropic routes after wire-model normalization. */
- _responseModelId?: string;
- /** Selected OpenAI API virtual-model id retained after it rewrites the upstream wire model. */
- _openAiVirtualSelectedModelId?: string;
- previousResponseId?: string;
- context: OcxContext;
- stream: boolean;
- options: OcxRequestOptions;
- _rawBody?: unknown;
- /**
- * Boundary between replayed history and this turn's newly appended input. Usually the
- * items the proxy restored from local previous_response_id state; also set when the
- * CLIENT already carried that history verbatim and the proxy skipped the prepend.
- */
- _replayPrefixLen?: number;
- /** Parsed-message index before the first conversational item in a continuation's current delta. */
- _continuationConversationMessageIndex?: number;
- /**
- * True when the full history for a previous_response_id request is present in the input —
- * whether the proxy expanded it or the client already sent it. Consumers read this as
- * "this request is self-contained", never as "the proxy mutated it".
- */
- _previousResponseInputExpanded?: boolean;
- /** Provider-private stable Cursor conversation id resolved from the Responses previous_response_id chain. */
- _cursorConversationId?: string;
- /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
- _clientThreadId?: string;
- /** Provider/account/model-bound namespace for process-local raw-reasoning replay. */
- _reasoningReplayScope?: OcxReasoningReplayScopeRef;
- /**
- * Optional authenticated tenant/operator namespace for Cursor thread→conversation derivation.
- * When absent (single-operator local proxy), derivation stays local-scoped.
- */
- _cursorIdentityScope?: string;
- /**
- * True for helper/shadow/compaction turns that must not append into the main Cursor conversation
- * derived from the parent thread id.
- */
- _cursorIsolateConversation?: boolean;
- /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
- _kiroAuthContext?: Pick;
- /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
- _providerContinuation?: OcxProviderContinuationState;
- /**
- * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed
- * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and
- * executes searches via the gpt-5.4-mini sidecar (see src/web-search). Absent when not requested.
- */
- _webSearch?: Record;
- /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */
- _imageGeneration?: { toolNames: Set; originalTool?: Record };
- /**
- * True when Codex requested structured output (`text.format` = json_schema/json_object). The
- * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its
- * answer/"Sources:" text can't bleed into and corrupt the model's schema-constrained output.
- */
- _structuredOutput?: boolean;
- /**
- * True when the input carried `{type:"compaction_trigger"}` — Codex remote compaction v2 asking
- * this turn to produce a `{type:"compaction"}` output item. Routed adapters can't natively;
- * the server runs the model as a summarizer and the bridge emits a synthetic compaction item
- * (see src/responses/compaction.ts).
- */
- _compactionRequest?: boolean;
- /**
- * True when the current request newly introduced a stored compaction summary/marker. Historical
- * markers restored by previous_response_id expansion were already acknowledged and do not reset
- * provider-private continuation caches again on every later turn.
- */
- _contextCompactionBoundary?: boolean;
-}
-
-export interface OcxContext {
- systemPrompt?: string[];
- messages: OcxMessage[];
- tools?: OcxTool[];
-}
-
-export type OcxMessage =
- | OcxUserMessage
- | OcxAssistantMessage
- | OcxDeveloperMessage
- | OcxToolResultMessage;
-
-export interface OcxUserMessage {
- role: "user";
- content: string | OcxContentPart[];
- timestamp: number;
-}
-
-export interface OcxAssistantMessage {
- role: "assistant";
- content: OcxAssistantContentPart[];
- /** Responses message phase, preserved when replaying translated provider output. */
- phase?: OcxMessagePhase;
- model?: string;
- timestamp: number;
- /**
- * Kiro `reasoningContent.redactedContent` for THIS assistant turn — an opaque encrypted blob
- * Kiro replays to preserve model reasoning across turns. Provider-specific and unrenderable, so
- * it rides the message rather than a content part: any other adapter simply ignores it.
- */
- kiroRedactedReasoning?: string;
-}
-
-export interface OcxDeveloperMessage {
- role: "developer";
- content: string | OcxContentPart[];
- timestamp: number;
-}
-
-export interface OcxToolResultMessage {
- role: "toolResult";
- toolCallId: string;
- toolName: string;
- /** MCP namespace from the originating tool call, if any. */
- toolNamespace?: string;
- /** Text, or content parts when a tool (e.g. Codex view_image) returns an image in its output. */
- content: string | OcxContentPart[];
- /** True when the Responses result contained opaque encrypted output Kiro cannot translate. */
- containsEncryptedContent?: boolean;
- isError: boolean;
- timestamp: number;
-}
-
-export interface OcxTextContent {
- type: "text";
- text: string;
-}
-
-export interface OcxImageContent {
- type: "image";
- /** A `data:` URL (base64) or a remote https URL — passed through from Codex verbatim, NEVER inlined as text. */
- imageUrl: string;
- /** Fidelity hint from Codex: "low" | "high" | "auto". */
- detail?: string;
-}
-
-/** A user/developer message content part: text or an image (vision). */
-export type OcxContentPart = OcxTextContent | OcxImageContent;
-
-export interface OcxThinkingContent {
- type: "thinking";
- thinking: string;
- signature?: string;
- itemId?: string;
- /** Raw Anthropic redacted_thinking block payloads to replay verbatim (order preserved). */
- redacted?: string[];
-}
-
-export interface OcxToolCall {
- type: "toolCall";
- id: string;
- name: string;
- arguments: Record;
- customWireName?: string;
- thoughtSignature?: string;
- /**
- * Provider-issued opaque metadata that must survive the whole round trip unchanged
- * (issue #1735). A signed Gemini part is only valid when its signature comes back on the
- * SAME part it was issued for, so this travels with the individual tool call rather than
- * being matched by name/arguments after the fact.
- */
- providerMetadata?: OcxProviderOpaqueToolCallMetadata;
- /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */
- namespace?: string;
-}
-
-/**
- * Opaque, provider-scoped tool-call metadata. Values are never parsed, merged, re-encoded, or
- * synthesized — they are carried verbatim or not at all.
- */
-export interface OcxProviderOpaqueToolCallMetadata {
- google?: {
- thoughtSignature?: string;
- };
-}
-
-export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
-
-export interface OcxTool {
- name: string;
- description: string;
- parameters: Record;
- strict?: boolean;
- /** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
- namespace?: string;
- /** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
- freeform?: boolean;
- /** Client-executed tool discovery (tool_search): the model's call must be relayed as a tool_search_call. */
- toolSearch?: boolean;
- /** Tool definition restored from a prior tool_search output; transports may prioritize it when catalogs are bounded. */
- loadedFromToolSearch?: boolean;
- /** Cursor-only synthetic exact-match edit tool; never inferred from the wire name. */
- cursorStructuredEdit?: true;
- /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
- webSearch?: boolean;
- /** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
- imageGeneration?: boolean;
- /** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
- videoGeneration?: boolean;
-}
-
-/**
- * Wire name a chat model sees for a tool. Namespaced (MCP) tools are flattened to
- * "__" so they survive the chat-completions function-tool format;
- * the proxy maps this back to {namespace, name} on the return trip (Codex routes MCP
- * calls by an explicit `namespace` field, not by parsing the name).
- */
-export function namespacedToolName(namespace: string | undefined, name: string): string {
- return namespace ? `${namespace}__${name}` : name;
-}
-
-export function toolChoiceAliases(tool: Pick): string[] {
- const wireName = namespacedToolName(tool.namespace, tool.name);
- return tool.namespace ? [wireName, `${tool.namespace}.${tool.name}`] : [wireName];
-}
-
-export function toolAllowedByChoice(tool: Pick, allowedTools: ReadonlySet): boolean {
- return toolChoiceAliases(tool).some(name => allowedTools.has(name));
-}
-
-export function resolveToolChoiceWireName(tools: readonly Pick[] | undefined, name: string): string {
- const match = tools?.find(tool => toolChoiceAliases(tool).includes(name));
- return match ? namespacedToolName(match.namespace, match.name) : name;
-}
-
-/**
- * Whether `modelId` is in a per-provider classification list (e.g. `noVisionModels`). Matches the full
- * id, OR — for Ollama-style ids — the family before the ":size" tag, so a `gpt-oss` entry covers
- * `gpt-oss:120b`/`gpt-oss:20b`. Colon-less ids (e.g. `grok-build-0.1`) still match exactly only.
- */
-export function modelInList(list: string[] | undefined, modelId: string): boolean {
- if (!list || list.length === 0) return false;
- if (list.includes(modelId)) return true;
- const colon = modelId.indexOf(":");
- return colon > 0 && list.includes(modelId.slice(0, colon));
-}
-
-export type OcxToolChoice =
- | "auto"
- | "none"
- | "required"
- | { name: string }
- | { allowedTools: string[]; mode: "auto" | "required" };
-
-export function isAllowedToolChoice(value: OcxToolChoice | undefined): value is { allowedTools: string[]; mode: "auto" | "required" } {
- return typeof value === "object" && value !== null && "allowedTools" in value;
-}
-
-/** Compile the request's tool-choice policy into a reusable advertisement/restoration predicate. */
-export function toolChoiceToolPredicate(
- choice: OcxToolChoice | undefined,
-): (tool: Pick) => boolean {
- if (!choice || choice === "auto" || choice === "required") return () => true;
- if (choice === "none") return () => false;
- if (isAllowedToolChoice(choice)) {
- const allowed = new Set(choice.allowedTools);
- return tool => toolAllowedByChoice(tool, allowed);
- }
- return tool => toolChoiceAliases(tool).includes(choice.name);
-}
-
-export interface OcxRequestOptions {
- maxOutputTokens?: number;
- temperature?: number;
- topP?: number;
- stopSequences?: string[];
- toolChoice?: OcxToolChoice;
- parallelToolCalls?: boolean;
- reasoning?: string;
- hideThinkingSummary?: boolean;
- serviceTier?: string;
- /** Final outbound tier action, resolved after the provider/model wire is settled. */
- tierDecision?: TierDecision;
- /** Internal B0 observation inputs; adapters combine these with the wire they actually serialize. */
- tierObservation?: TierObservationContext;
- presencePenalty?: number;
- frequencyPenalty?: number;
- /** Responses prompt-cache affinity key. Passthrough preserves it via _rawBody; routed adapters do not consume it unless their upstream wire supports it. */
- promptCacheKey?: string;
- /**
- * Responses `text.format` (json_schema / json_object), preserved for adapters whose
- * upstream wire has an equivalent. The openai-chat adapter re-nests it as chat
- * `response_format`, the exact inverse of responseFormatToText in src/chat/inbound.ts.
- * The native passthrough ignores it (it forwards `_rawBody.text` verbatim) and Kiro
- * keeps rejecting structured output via `_structuredOutput`.
- */
- textFormat?: {
- type: "json_schema" | "json_object";
- name?: string;
- description?: string;
- schema?: Record;
- strict?: boolean;
- };
-}
-
-export type OcxMessagePhase = "commentary" | "final_answer";
-
-/**
- * Provider-private state that must follow a locally expanded `previous_response_id` chain.
- * Kept out of public Responses output and persisted only in the bounded local continuation cache.
- */
-export interface OcxProviderContinuationState {
- cursor?: {
- conversationId?: string;
- checkpointUsable?: boolean;
- };
- kiro?: {
- conversationId?: string;
- };
- [provider: string]: Record | undefined;
-}
-
-export type AdapterEvent =
- | { type: "heartbeat" }
- | { type: "text_delta"; text: string; phase?: OcxMessagePhase }
- | { type: "thinking_delta"; thinking: string }
- // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and
- // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400.
- | { type: "thinking_signature"; signature: string }
- | { type: "redacted_thinking"; data: string }
- // Kiro reasoning round-trip: the encrypted `redactedContent` blob for the CURRENT assistant turn.
- // Never rendered — it only rides the reasoning item's envelope so the next request can replay it.
- | { type: "kiro_redacted_reasoning"; data: string }
- | { type: "reasoning_raw_delta"; text: string }
- | { type: "tool_call_start"; id: string; name: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata }
- | { type: "tool_call_delta"; arguments: string }
- | { type: "tool_call_end" }
- /** Internal boundary between a guarded first pass and its one-shot continuation. */
- | { type: "assistant_boundary" }
- // Native web-search activity surfaced by the web-search sidecar so Codex renders a "Searched the
- // web" cell. Emitted as a lifecycle PAIR at real wall-clock moments by src/web-search/loop.ts
- // (routed adapters never emit these): `begin` right before the sidecar runs so Codex shows the
- // "Searching the web" spinner, then `end` once it resolves. The bridge maps begin → an
- // output_item.added(in_progress) and end → the matching output_item.done(completed|failed) under
- // the SAME output index, so the activity animates instead of flashing completed instantly.
- | { type: "web_search_call_begin"; id: string }
- | { type: "web_search_call_end"; id: string; queries: string[]; status?: "completed" | "failed"; sources?: OcxUrlCitation[] }
- | {
- type: "done";
- usage?: OcxUsage;
- stopReason?: string;
- endTurn?: boolean;
- providerState?: OcxProviderContinuationState;
- }
- | {
- type: "incomplete";
- reason: string;
- message?: string;
- usage?: OcxUsage;
- retryable?: boolean;
- endTurn?: boolean;
- providerState?: OcxProviderContinuationState;
- }
- // `usage` carries best-effort partial consumption when a turn dies before a clean done
- // (e.g. cursor upstream 502 mid-stream), so failed requests can log real token counts.
- | {
- type: "error";
- message: string;
- usage?: OcxUsage;
- /** Authoritative upstream/proxy status when known; avoids message-based classification. */
- status?: number;
- /** Responses error type and code when the adapter has a structured provider failure. */
- errorType?: string;
- code?: string;
- retryable?: boolean;
- };
-
-/**
- * A web source backing a search answer. Surfaced on the search-end event and rendered by the bridge
- * as a `url_citation` annotation on the following assistant message (the desktop app's Sources chip
- * reads these; the TUI ignores annotations, so this is additive).
- */
-export interface OcxUrlCitation {
- url: string;
- title?: string;
-}
-
-/**
- * Canonical usage convention (devlog/260711_claude_inbound/070):
- * - `inputTokens` is the TOTAL prompt size, INCLUDING cache reads and cache writes
- * (OpenAI Responses convention). Anthropic parse sites normalize into this shape.
- * - `cachedInputTokens` is cache READ tokens only (a subset of `inputTokens`).
- * - `cacheReadInputTokens`/`cacheCreationInputTokens` carry the read/write split when
- * the provider reports both; reads mirror `cachedInputTokens`.
- * - `totalTokens` = inputTokens + outputTokens. Never re-add cache detail on top.
- */
-export interface OcxUsage {
- inputTokens: number;
- outputTokens: number;
- /**
- * Absolute active-context size after the response. Stateful providers can expose this separately
- * from their per-attempt usage. Responses serialization derives the input side from
- * `contextTotalTokens - outputTokens` so output is never added to an absolute checkpoint twice.
- */
- contextTotalTokens?: number;
- totalTokens?: number;
- cachedInputTokens?: number;
- cacheReadInputTokens?: number;
- cacheCreationInputTokens?: number;
- reasoningOutputTokens?: number;
- estimated?: boolean;
-}
-
-/**
- * Claude Code inbound settings (devlog/260711_claude_inbound). Consumed by the
- * /v1/messages surface, the `ocx claude` launcher, and the GUI Claude page.
- */
-export interface OcxClaudeCodeConfig {
- /** Kill switch for the /v1/messages inbound (GUI "Claude ON" toggle). Default: enabled. */
- enabled?: boolean;
- /**
- * Verbatim passthrough of unmapped claude/anthropic models to api.anthropic.com with the
- * caller's own sk-ant-* credential (Claude Code subscription OAuth). Default: enabled.
- */
- nativePassthrough?: boolean;
- /** Upstream for the native passthrough (tests/enterprise gateways). Default: https://api.anthropic.com */
- anthropicBaseUrl?: string;
- /**
- * Native passthrough body inactivity budget in SECONDS — raw upstream-byte silence
- * while a read is pending, NOT total duration (slow-but-alive streams never trip it;
- * devlog 260716_passthrough_followups/010). Default 90. Min 1. Exactly 0 disables;
- * negative/non-finite values fall back to the default.
- */
- bodyStallSec?: number;
- /**
- * Native passthrough cumulative body byte cap (streamed SSE and buffered non-stream
- * alike) — an OOM/occupancy guard, not a correctness limit. Default 67108864 (64 MiB).
- * Exactly 0 disables; negative/non-finite values fall back to the default.
- */
- bodyMaxBytes?: number;
- /** Default model slot injected as ANTHROPIC_MODEL by `ocx claude`. */
- model?: string;
- /** Haiku/small-fast slot injected as ANTHROPIC_DEFAULT_HAIKU_MODEL (+ legacy SMALL_FAST). */
- smallFastModel?: string;
- /** Inbound model id remaps: exact id first, then date-stripped (`-\d{8}$`). */
- modelMap?: Record;
- /**
- * Explicit classifier model for Claude Code Auto Mode safety checks (e.g. "RelayA/claude-opus-5").
- * When unset, bare classifier requests check modelMap, then same-provider affinity from
- * `claudeCode.model`, then compatible Anthropic-adapter providers, and finally fallbacks.
- */
- classifierModel?: string;
- /**
- * Ordered fallback candidates for Claude Code Auto Mode classifier routing when the primary
- * classifier route is not available.
- */
- classifierFallbacks?: string[];
- /**
- * Inject ANTHROPIC_BASE_URL etc. into the macOS user domain via `launchctl setenv`
- * so plain `claude` commands route through the proxy without `ocx claude`. Reverted
- * on stop/shutdown. Default: false (opt-in). macOS only.
- */
- systemEnv?: boolean;
- /**
- * Auth mode for Claude Code inbound requests — a THREE-state intent.
- *
- * "proxy": inject the dummy ANTHROPIC_AUTH_TOKEN so Claude Code routes through the
- * proxy without a real Anthropic key. "subscription": never inject it. UNSET means
- * AUTO: the mode is resolved from detected Claude auth on every launch and every
- * status read (src/claude/auth-mode.ts), so registering a Claude login switches the
- * behaviour with no migration and no stored state.
- *
- * An explicit value always wins over detection and is never rewritten by the auto
- * logic — that is what makes a manual choice stick (devlog 260726_claude_auth_auto).
- */
- authMode?: "proxy" | "subscription";
- /**
- * ISO timestamp of the one-time authMode migration. Before auto existed, choosing
- * "Subscription" DELETED the key, so a pre-upgrade config cannot distinguish an
- * explicit subscription choice from "never chose". Its ABSENCE identifies a
- * pre-upgrade block; the migration writes it once and never re-runs, so a user who
- * later picks Auto (which deletes authMode) is not silently converted back.
- */
- authModeMigratedAt?: string;
- /**
- * Context-window override for Claude Code/Desktop clients (devlog 136 B6):
- * injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS + DISABLE_COMPACT=1 (the official
- * env pair — recognized claude-shaped ids need both). WARNING: DISABLE_COMPACT
- * turns off auto-compaction. Unset = client defaults.
- */
- maxContextTokens?: number;
- /**
- * Opt-in CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 injection. Default OFF: opus-shaped
- * aliases already carry output_config.effort on the wire (devlog 136 실측), and
- * forcing effort on every request can leak reasoning params to non-reasoning routes.
- */
- alwaysEnableEffort?: boolean;
- /**
- * Subagent tier slots (devlog 260712 B2): injected as ANTHROPIC_DEFAULT_*_MODEL so
- * Claude Code's Agent-tool aliases (opus/sonnet/haiku/fable + parent-inherit) route
- * to proxy models. haiku falls back to smallFastModel (one effective value feeds
- * both ANTHROPIC_DEFAULT_HAIKU_MODEL and legacy ANTHROPIC_SMALL_FAST_MODEL).
- */
- tierModels?: { opus?: string; sonnet?: string; haiku?: string; fable?: string };
- /**
- * Auto-context (devlog 260712 020): when not false, routed/native models whose
- * authoritative window is > 200k AND >= the compact window get the [1m] marker
- * (Claude Code then accounts 1M) and CLAUDE_CODE_AUTO_COMPACT_WINDOW is injected
- * so compaction fires at the real budget. 2.1.207 semantics (binary-verified):
- * effective compact window = min(believed window, env) — one global env behaves
- * like a per-model floor. Default: enabled. Inert while maxContextTokens is set
- * (the legacy DISABLE_COMPACT pair takes rule-1 precedence in the CLI).
- */
- autoContext?: boolean;
- /** Compact-window tokens for auto-context. Default 829_800 (AUTO_COMPACT_WINDOW_DEFAULT). */
- autoCompactWindow?: number;
- /**
- * Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
- * 060): Skill-tool results whose skill name matches an entry here are replaced
- * with a short stub in the anthropic->responses translation. Third-party models
- * are not trained on these Anthropic doc bundles, and claude-api alone injects
- * ~136k tokens (GitHub anthropics/claude-code#74473). Native Anthropic
- * passthrough never goes through the translation, so Claude models keep the
- * full content. Default: ["claude-api"]. Empty array = explicitly off.
- */
- blockedSkills?: string[];
- /**
- * Sync the featured subagent roster (config.subagentModels + main model) into
- * ~/.claude/agents/ocx-*.md custom agent definitions at launch (devlog 260712
- * 070) so any routed model is dispatchable as a subagent_type — the Agent
- * tool's model argument is a hard 4-alias enum, but definition frontmatter is
- * free. Only ocx-*.md files are owned/pruned. Default: enabled.
- */
- injectAgents?: boolean;
- /**
- * Optional Claude Code effort pinned in every generated ocx-* subagent
- * definition. Unset inherits the parent session effort.
- */
- subagentEffort?: "low" | "medium" | "high" | "xhigh" | "max";
- /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
- webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
- /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
- visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
- /** Persisted Claude Desktop four-family routing profile. */
- desktopProfile?: OcxClaudeDesktopProfile;
- /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
- desktopAutoApply?: boolean;
- /**
- * When false, omit `native/*` rows from Claude Desktop show/export/apply. Default: enabled.
- * Routing-sidecar alias decoding is unchanged — only the Desktop model list writer.
- */
- desktopNativeModels?: boolean;
-}
-
-export type OcxClaudeDesktopFamily = "opus" | "fable" | "sonnet" | "haiku";
-
-export interface OcxClaudeDesktopAssignment {
- family: OcxClaudeDesktopFamily;
- alias: string;
-}
-
-export interface OcxClaudeDesktopProfile {
- version: 1;
- assignments: Record;
- defaults: Record;
- /** SHA-256 fingerprint of the last successfully applied 3P config content. */
- appliedFingerprint?: string;
- /** ISO timestamp of the last successful apply. */
- appliedAt?: string;
-}
-
-/**
- * Opt-in archived-session auto-cleanup policy (issue #42 Phase 3).
- * Persisted under `OcxConfig.storageCleanupPolicy`. Default `enabled: false`.
- */
-export interface StorageCleanupPolicy {
- /** When false/unset, the engine never mutates. Default false. */
- enabled: boolean;
- /** Run when archived session bytes exceed this threshold. */
- trigger: { archivedBytesOver: number };
- /** Either shrink archives toward a byte floor, or remove the oldest N%. */
- target: { reduceToBytes?: number } | { removeOldestPercent?: number };
- schedule: "startup" | "daily" | "weekly" | "manual";
- /** Default quarantine. Permanent only when explicitly set. */
- mode: "quarantine" | "permanent";
- lastRun?: { at: number; freedBytes: number; removed: number };
- /** Epoch ms when the next scheduled evaluation is due. */
- nextRun?: number;
-}
-
-/** 사용자가 대시보드에서 직접 추가한 커스텀 모델 정의. */
-export interface OcxCustomModel {
- /** 고유 ID (crypto.randomUUID()) */
- id: string;
- /** 프로바이더 키 (기존 providers[name]) */
- provider: string;
- /** Native provider model id; slashes are allowed and encoded for Codex as provider/. */
- modelId: string;
- /** 인간 가독 표시명 (선택, 슬래시 불가) */
- displayName?: string;
- /** 컨텍스트 윈도우 (토큰) */
- contextWindow?: number;
- /** 입력 모달리티 (선택, 기본 ["text"]) */
- inputModalities?: string[];
- /**
- * Reasoning ladder (Codex labels) this custom row explicitly advertises. An empty array
- * hides the effort control; an omitted key leaves the provider-derived ladder in charge.
- */
- reasoningEfforts?: string[];
- /** Default effort label when `reasoningEfforts` is non-empty. */
- defaultReasoningEffort?: string;
- /** 추가 시각 (ISO 8601) */
- addedAt?: string;
-}
-
-/**
- * A generated `ocx_` data-plane key. `key` is the secret itself and never leaves
- * the server except in the one-time POST /api/keys response; every other surface
- * sees only the masked prefix.
- */
-export interface OcxApiKeyEntry {
- id: string;
- name: string;
- key: string;
- createdAt: string;
-}
-
-/**
- * Durable per-client intent. One key today, deliberately.
- *
- * A top-level `codexEnabled` would force every later client to invent an
- * unrelated name and its own helpers; a ten-key union recreated the coupling
- * that failed two audits, because every phase then had to touch every client's
- * write path. A one-key object keeps the extension point without letting this
- * phase claim ownership over a client it does not implement.
- */
-export interface OcxClientIntegrationsConfig {
- /** Durable desired state for native Codex. MISSING MEANS ON. */
- codex?: boolean;
- /** Durable desired state for Grok Build. MISSING MEANS ON. */
- grok?: boolean;
- /** Durable desired state for Claude Desktop. MISSING MEANS ON. */
- "claude-desktop"?: boolean;
-}
-
-export interface OcxConfig {
- port: number;
- /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
- emptyCompletionRetry?: boolean;
- /** Maximum usage-log bytes read for one management snapshot. */
- managementUsageMaxReadBytes?: number;
- providers: Record;
- defaultProvider: string;
- /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
- openaiProviderTierVersion?: 1 | 2;
- /** One-time migration marker for Antigravity's static-catalog defaults. */
- googleAntigravityStaticCatalogVersion?: 1 | 2;
- /** Claude Code inbound + launcher settings. */
- claudeCode?: OcxClaudeCodeConfig;
- /**
- * Per-client durable intent. This phase owns only `codex`; later phases extend
- * one key at a time rather than widening a shared union.
- */
- clientIntegrations?: OcxClientIntegrationsConfig;
- /**
- * Up to 5 Codex-facing catalog ids to feature first. Values may be bare catalog ids,
- * exact account-qualified "/" ids, or routed
- * "/" ids. With account selectors, one bare native choice can expand
- * into a selector-qualified group; Codex still advertises only the first 5 visible rows.
- */
- subagentModels?: string[];
- /**
- * Optional full picker ordering for the Codex model catalog, independent of the
- * 5-slot `subagentModels` spawn_agent cap. DISPLAY-ONLY: it controls the visual order of
- * the Codex model picker for large routed catalogs (10-20+ models) that would otherwise sort
- * arbitrarily and reshuffle on every rebuild. Values are routed `/` catalog
- * slugs (matched by exact slug or `provider/id`); native OpenAI passthrough rows and
- * account-qualified native rows are not reordered (order native rows via `subagentModels`).
- * Listed routed rows appear in array order; rows not listed keep their normal display order.
- * `subagentModels`-featured rows keep their top position. When unset or empty, catalog
- * priority is unchanged. This changes ONLY what the user sees in the picker: the spawn_agent
- * candidate set is derived from each row's natural priority and is provably unaffected, even
- * when every routed row is listed (see opencodex_spawn_priority / effectiveSubagentRoster).
- */
- modelPickerOrder?: string[];
- /**
- * Priority-ordered fallback models for spawned sub-agents. When the requested
- * model is quota-exhausted or recently failed, opencodex rewrites the child
- * turn to the next available entry before routing.
- */
- subagentModelFallback?: string[];
- /**
- * Per-primary-model fallback chains for spawned sub-agents, keyed by the
- * requested primary model id (bare native or "provider/model"). Entries for
- * the matching key are consulted after the requested model and before the
- * global `subagentModelFallback` list.
- *
- * This is the supported home for per-role fallback metadata: storing it as
- * `model_fallback` inside `$CODEX_HOME/agents/*.toml` makes Codex >= 0.146
- * reject the whole role file as an unknown field (#1190).
- */
- subagentModelFallbackByModel?: Record;
- /**
- * TTL (ms) for cached sub-agent model availability probes. Default 60_000.
- */
- subagentModelFallbackPollMs?: number;
- injectionModel?: string;
- /**
- * Opt in to synchronizing the selected injection model into Codex's native
- * sub-agent defaults. Only meaningful while `injectionModel` is set.
- */
- syncCodexSubagentDefaults?: boolean;
- /**
- * Optional reasoning effort the delegation prompt tells the agent to pass in spawn_agent calls
- * (`reasoning_effort` argument). Only meaningful while `injectionModel` is set; validated against
- * the Codex ladder (src/reasoning-effort.ts CODEX_REASONING_LEVELS) at the API boundary.
- */
- injectionEffort?: string;
- /**
- * Explicit sideband websocket base for realtime/live joins, mirroring upstream's
- * `experimental_realtime_ws_base_url`. The value is a ROOT (or a recognized
- * `/realtime`, `/realtime/calls/`, `/live/` endpoint form, which is
- * stripped back to the root); `/v1` is appended during normalization. Intended
- * for local development against a fake realtime server — plaintext `http`/`ws`
- * is accepted only for loopback hosts, and URL userinfo is rejected; both
- * failures close to the canonical `https://api.openai.com/v1`. Configured by
- * editing this file; there is deliberately no management-API or GUI surface.
- */
- experimentalRealtimeWsBaseUrl?: string;
- /**
- * Model ids the user has EXCLUDED from the Grok Build managed block. Absent or empty
- * means "everything visible", which is the historical behaviour — so an existing
- * config keeps the fence it already had.
- *
- * Exclusion list rather than an inclusion list on purpose: a newly added provider
- * model should appear in Grok by default, exactly as it does today. An inclusion list
- * would silently hide every future model behind a switch nobody knew to flip.
- */
- grokExcludedModels?: string[];
- /**
- * When true, OpenAI-routed requests include `service_tier: "priority"` (fast inference).
- * When false, service_tier is stripped so requests use default speed.
- * Undefined = passthrough (don't modify what the client sends).
- */
- fastMode?: boolean;
- /**
- * Windows/macOS SSE passthrough stream shape (#314 mitigation).
- * On Windows, "auto" (default) selects eager relay only on a runtime proven
- * to carry the Bun#32111 fix. On macOS, "auto" always stays on legacy tee and
- * eager relay is explicit-only. "eager-relay" opts into the new relay (and
- * accepts #32111 crash risk on Bun 1.3.14); "legacy-tee" pins the tee path.
- * Persisted in config.json so service users can select the stream shape.
- * See src/lib/bun-stream-caps.ts.
- */
- streamMode?: "auto" | "legacy-tee" | "eager-relay";
- /**
- * Custom override for the injected v2 multi-agent guidance body (the text inside
- * the tags). After guidance is enabled and the v2 surface and
- * catalog-state gates pass, a configured injectionModel is sufficient to render it;
- * otherwise an eligible roster or fallback is required. Placeholders: `{{model}}` -> the
- * effective preferred model for the request (a bare native model is account-qualified
- * only when the request targets an explicit account selector; unresolved or ambiguous
- * bare values become "", while unresolved explicit routed or account-qualified values
- * remain unchanged),
- * `{{effort}}` -> injectionEffort, `{{roster}}` -> the resolved sub-agent roster
- * block ("" when nothing resolves), `{{fallback}}` -> the configured subagent
- * model fallback guidance block ("" when unset).
- */
- injectionPrompt?: string;
- /**
- * Proxy-authored multi-agent developer guidance. Undefined/true = enabled for
- * backward compatibility; false suppresses both v1 and v2 guidance injection.
- */
- multiAgentGuidanceEnabled?: boolean;
- /**
- * Global hard ceiling for the reasoning effort of EVERY proxied turn (main agent AND
- * sub-agents). Ladder value "low".."max"; incoming efforts ranking above it are rewritten
- * in both request shapes before any adapter or clamp. Unset = no cap. codex-rs converts
- * ultra -> max client-side, so e.g. a "high" cap sends ultra/max-tier turns as high.
- */
- effortCap?: string;
- /**
- * Hard ceiling applied ONLY to sub-agent turns — requests carrying codex-rs's spawned-child
- * markers (`x-openai-subagent` header, or `subagent_kind` inside `x-codex-turn-metadata`).
- * Lets the main agent keep its tier while delegated children are capped. When both caps are
- * set, the lower one wins for sub-agents. See src/server/effort-policy.ts.
- */
- subagentEffortCap?: string;
- /**
- * Models hidden from Codex discovery without blocking direct proxy calls. Routed provider ids
- * are excluded from the catalog + /v1/models entirely. Account-qualified native ids hide only
- * their generated selector row and are omitted from raw /v1/models. BARE native GPT ids hide
- * the bare row plus every generated selector row and omit that model family from raw discovery.
- */
- disabledModels?: string[];
- /** 사용자가 대시보드에서 직접 추가한 커스텀 모델 목록. */
- customModels?: OcxCustomModel[];
- /**
- * Internal, versioned evidence for reconciling custom-model deletions with
- * pre-marker Codex catalog rows. Consumers must parse this defensively so a
- * future state written by a newer binary survives older whole-config saves.
- */
- customModelCatalogMigration?: unknown;
- /**
- * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
- * commit messages, skill orchestration) to a user-chosen model. Default intercepted
- * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
- * Opt-in; disabled by default. Matching maintenance/helper requests are forced to low.
- * All requests for configured shadow source models are intercepted unconditionally.
- */
- shadowCallIntercept?: {
- /** When true, requests for known shadow/helper source models are rewritten to the configured model. */
- enabled?: boolean;
- /** Replacement model id (e.g. "gpt-5.5"). */
- model?: string;
- /** Optional override of intercepted source-model prefixes (default: gpt-5.4-mini, gpt-5.6-luna). */
- sourceModels?: string[];
- };
- /**
- * 3-state multi-agent surface override:
- * - "v1": force ALL models to v1 surface (override upstream pins)
- * - "default" | undefined: respect upstream model pins (sol/terra=v2, luna=v1, rest=codex flag)
- * - "v2": force ALL models to v2 surface (override upstream pins)
- */
- multiAgentMode?: "v1" | "default" | "v2";
- /**
- * When `multiAgentMode` is `"v2"`, keep ChatGPT-native catalog rows on v1.
- * Routed parents get v2 tools; Sol/Terra can still spawn Grok/Claude (issue #92).
- */
- keepNativeChatGptOnV1?: boolean;
- /** Experimental, default-off ChatGPT recovery for encrypted V2 routed tasks. */
- agentTaskRecovery?: {
- enabled?: boolean;
- /** ChatGPT model used by the recovery request. Default: gpt-5.6-sol. */
- model?: string;
- /** Recovery request timeout in milliseconds. Default: 45000. */
- timeoutMs?: number;
- /** Maximum in-memory ciphertext-to-assignment entries. Default: 200. */
- cacheEntries?: number;
- };
- /** Provider-level Codex-visible context caps. Values only lower known model context windows. */
- providerContextCaps?: Record;
- /** Global Codex-visible context cap value (tokens). Falls back to DEFAULT_PROVIDER_CONTEXT_CAP. */
- contextCapValue?: number;
- /** Bind hostname. Default "127.0.0.1" (loopback only). Set "0.0.0.0" to expose on all interfaces. */
- hostname?: string;
- /**
- * Optional second listener bound to 127.0.0.1 that admits data-plane requests without a
- * credential (issue #1102).
- *
- * Why a separate listener rather than an exemption on the main one: when `hostname` is a
- * wildcard, every caller needs `x-opencodex-api-key`, but a `codex app-server` spawned
- * directly from the resolved entrypoint never goes through the generated shim and so never
- * inherits the token. Exempting "loopback-looking peers" on the public listener would be
- * unsound — `requestIP()` only proves the last transport hop, and Docker Desktop port
- * forwarding, host-network containers, WSL mirrored networking and tunnels all terminate
- * remote connections locally. Binding a second socket to 127.0.0.1 makes the kernel refuse
- * remote connections outright, so there is no address to judge.
- *
- * The public listener's admission policy is unchanged. This adds an explicit local trust
- * surface: every process on the machine can reach it, spend account quota, and consume paid
- * provider credentials. Off by default; not for multi-tenant hosts.
- *
- * The port is required when enabled and must differ from the proxy port. An OS-assigned port
- * would change across restarts, which would break already-running app-servers holding the
- * previous `base_url` — the exact symptom #1102 reported and we disproved for token rotation.
- */
- unauthenticatedLoopbackListener?:
- | { enabled: false }
- | { enabled: true; port: number };
- /**
- * Outbound HTTP(S) proxy URL for provider requests (e.g. "http://user:pass@proxy:8080", or
- * "${HTTPS_PROXY}"-style env reference). Mirrored into HTTP_PROXY/HTTPS_PROXY at startup when
- * those are unset — Bun's fetch honors them for all outbound calls; localhost is excluded.
- */
- proxy?: string;
- /**
- * Upstream stall timeout (seconds). After this many seconds of no upstream data, emits
- * response.incomplete. Default 300. Min 1.
- */
- stallTimeoutSec?: number;
- /** Connect timeout (ms) for upstream fetch — covers DNS, TCP, TLS, and response header. Default 200000. */
- connectTimeoutMs?: number;
- /** Graceful shutdown drain timeout (ms). Active turns are aborted after this deadline. Default 5000. */
- shutdownTimeoutMs?: number;
- /** Advertise supports_websockets so Codex opens the WS endpoint. Default false; set true to opt in. */
- websockets?: boolean;
- /**
- * Opt-in auto-cleanup policy for archived Codex sessions (issue #42 Phase 3).
- * Default OFF (`enabled` false / unset). Never enabled implicitly.
- * See `src/storage/policy.ts`.
- */
- storageCleanupPolicy?: StorageCleanupPolicy;
- /** Generated API keys for external access to the proxy's /v1/responses endpoint. */
- apiKeys?: OcxApiKeyEntry[];
- /** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */
- codexAutoStart?: boolean;
- /** Restore an installed shim after a stable external Codex update replaces it. Default true. */
- codexShimAutoRestore?: boolean;
- /**
- * Compatibility mode: temporarily rewrite Codex resume-history metadata while the proxy is active
- * so Codex App can show old OpenAI chats and opencodex-created exec chats under its default
- * interactive-source/provider filters. Default true; originals are backed up and restored by
- * `ocx stop` / `ocx restore`. Set false to opt out of history remapping.
- */
- syncResumeHistory?: boolean;
- /** Freshness window (ms) for the per-provider live `/models` cache. Defaults to 5 min. */
- modelCacheTtlMs?: number;
- /** Evictable retained app-state budget in MiB. Default 256; valid 64..4096. */
- appOwnedMemoryBudgetMb?: number;
- /** Anthropic prompt-cache retention: "short" = 5-min ephemeral (default), "long" = 1-hour extended, "none" = disabled. */
- cacheRetention?: "none" | "short" | "long";
- /** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */
- webSearchSidecar?: OcxWebSearchSidecarConfig;
- /** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
- visionSidecar?: OcxVisionSidecarConfig;
- /** /v1/images relay for codex's built-in image_gen tool. */
- images?: OcxImagesConfig;
- /** /v1/alpha/search relay for codex's built-in web search client. */
- search?: OcxSearchConfig;
- /** Codex multi-account pool. */
- codexAccounts?: CodexAccount[];
- /** Account ids administratively excluded from future pool selection until resumed. */
- pausedCodexAccountIds?: string[];
- /**
- * Selection order per account id, higher used earlier; absent = 0. Keyed by id
- * rather than stored on `codexAccounts` rows so the Desktop login (`__main__`),
- * which has no row, can be ordered too. Range -100..100.
- */
- codexAccountPriorities?: Record;
- /**
- * Account id the operator last selected by hand. Suppresses upward priority
- * preemption until that account crosses the auto-switch threshold. Stores the
- * id (not a flag) so a stale pin cannot outlive the selection it described.
- */
- activeCodexAccountPinned?: string;
- /**
- * Public model-selector namespaces bound to one Codex account. Values are stored account ids;
- * `"@main"` selects the Codex Desktop/main auth.json account. Account display aliases
- * are intentionally separate from these selectors.
- */
- codexAccountNamespaces?: Record;
- /**
- * Picker visibility override for account-qualified native models. When omitted, a non-empty
- * selector map remains visible for compatibility with hand-written configurations.
- */
- codexAccountPickerEnabled?: boolean;
- /** Active pool account id for next session. undefined = main (passthrough as-is). */
- activeCodexAccountId?: string;
- /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
- autoSwitchThreshold?: number;
- /** New-session account rotation strategy for the Codex pool. Default quota (today's behaviour). */
- accountPoolStrategy?: OcxAccountPoolRotationStrategy;
- /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
- accountPoolStickyLimit?: number;
- /** Consecutive non-2xx upstream responses before switching future new threads. Default 3. 0 = disabled. */
- upstreamFailoverThreshold?: number;
- /**
- * Opt-in provider-origin circuit threshold for proven pre-connection reachability failures.
- * Default 0 (disabled); range 0..20. The circuit never counts timeouts or HTTP responses.
- */
- upstreamHostCircuitThreshold?: number;
- /**
- * Opt-in Anthropic OAuth account pool (#294). Default OFF.
- * Failover on 429 + sticky affinity; new sessions may pick lowest known 5h usage.
- * Experimental — see docs and GUI warning before enabling.
- */
- anthropicAccountPool?: {
- enabled?: boolean;
- /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
- autoSwitchThreshold?: number;
- /** New-session rotation strategy. Default quota (today's behaviour). */
- strategy?: OcxAccountPoolRotationStrategy;
- /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
- stickyLimit?: number;
- };
- /** Virtual `combo/` models spanning concrete provider/model targets (issue #133). */
- combos?: Record;
- /**
- * Routing policy profiles (Router Intelligence, RI-04+): explicitly requested
- * `policy/` (or configured alias) models select among an explicit
- * candidate allowlist using hard capability requirements and deterministic
- * scoring. Existing model ids are never routed through profiles implicitly.
- */
- routingProfiles?: Record;
- /** Background proactive token refresh ("Token Guardian"). Off by default; see OcxTokenGuardianConfig. */
- tokenGuardian?: OcxTokenGuardianConfig;
- /** Additional exact origins allowed for CORS (e.g. HTTPS or chrome-extension://). Loopback origins are always allowed. */
- corsAllowOrigins?: string[];
-}
-
-export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
-
-export type OcxComboStrategy = "failover" | "round-robin";
-export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
-
-export interface OcxComboTarget {
- provider: string;
- model: string;
- /** Relative SWRR batch weight. Default 1; valid range 1..10000. */
- weight?: number;
-}
-
-export interface OcxComboConfig {
- targets: OcxComboTarget[];
- /** Ordered failover (default) or deterministic smooth weighted round-robin. */
- strategy?: OcxComboStrategy;
- /** Successful requests retained on one RR selection batch. Default 1; range 1..100. */
- stickyLimit?: number;
- /** Used when the client omits reasoning.effort. null/omitted leaves the target default unchanged. */
- defaultEffort?: OcxComboDefaultEffort | null;
- /**
- * Disable image input even when every target supports it.
- * Omitted / `"auto"` keeps automatic capability derivation (default: enabled when
- * the target intersection includes image).
- */
- imageInput?: "auto" | "disabled";
- /**
- * Optional public model name replacing the default `combo/` slug. Bare names
- * without "/" are allowed (e.g. "deepseek-v4-flash") so the combo can answer to a
- * mandated model id; exact-match requests route here before any provider resolution.
- */
- alias?: string;
- /**
- * Explicitly allow a bare OpenAI-native alias (for example `gpt-5.6-sol`) to
- * be represented by this routed combo. Never inferred from `alias`.
- */
- nativeAlias?: boolean;
- /** Display-only label for the public catalog row. Required for native aliases. */
- displayName?: string;
-}
-
-export type OcxRoutingUnknownEvidenceMode = "allow" | "penalize" | "exclude";
-
-export interface OcxRoutingProfileCandidate {
- provider: string;
- model: string;
-}
-
-export interface OcxRoutingProfileRequirements {
- /** Minimum model context window in tokens. */
- minContextWindow?: number;
- /** Minimum remaining quota headroom fraction (0..1). */
- minQuotaHeadroom?: number;
- tools?: boolean;
- imageInput?: boolean;
- structuredOutput?: boolean;
- reasoningEffort?: string;
- serviceTier?: string;
- localOnly?: boolean;
- remoteAllowed?: boolean;
- /** Special encrypted Codex task readability (ChatGPT forward pool). */
- encryptedCodexTasks?: boolean;
-}
-
-export interface OcxRoutingProfileOptimize {
- latency?: number;
- health?: number;
- cost?: number;
- quota?: number;
-}
-
-/**
- * Policy for the hard cost ceiling when a candidate has no finite cost
- * estimate. `"allow"` (default) preserves the documented dry-run contract:
- * the cap only excludes evidence known to exceed it, and the candidate's
- * `cost.capOutcome` is `"unknown-allowed"`. `"exclude"` makes the ceiling
- * fail-closed (`cost-limit-unknown` + `capOutcome: "unknown-excluded"`).
- */
-export type OcxRoutingUnknownCostCapMode = "allow" | "exclude";
-
-export interface OcxRoutingProfileLimits {
- /** Hard per-request estimated-cost ceiling in USD. */
- maxEstimatedCostUsd?: number;
- /**
- * How `maxEstimatedCostUsd` behaves when the estimate is unknown.
- * Defaults to `"allow"` (eligible + `cost.capOutcome: "unknown-allowed"`);
- * opt in to `"exclude"` for a true hard ceiling.
- */
- onUnknownCost?: OcxRoutingUnknownCostCapMode;
-}
-
-export interface OcxRoutingProfileUnknownEvidence {
- capability?: OcxRoutingUnknownEvidenceMode;
- health?: OcxRoutingUnknownEvidenceMode;
- quota?: OcxRoutingUnknownEvidenceMode;
- cost?: OcxRoutingUnknownEvidenceMode;
-}
-
-export interface OcxRoutingProfileCompatibilitySuite {
- suiteId: string;
- evidenceLayer: "protocol_conformance" | "live_route_compatibility";
-}
-
-export interface OcxRoutingProfileCompatibility {
- requiredSuites?: OcxRoutingProfileCompatibilitySuite[];
- minStatus?: "PROBED" | "VERIFIED";
- maxEvidenceAgeMs?: number;
- unknownEvidence?: OcxRoutingUnknownEvidenceMode;
- degradedEvidence?: OcxRoutingUnknownEvidenceMode;
-}
-
-export interface OcxRoutingProfileConfig {
- /**
- * Explicit candidate allowlist (`provider/model` refs). No implicit
- * expansion in v1.
- */
- candidates: OcxRoutingProfileCandidate[];
- /** Optional public model name replacing the default `policy/` slug. */
- alias?: string;
- /** Hard requirements evaluated before scoring. */
- require?: OcxRoutingProfileRequirements;
- /** Optimization weights; normalized deterministically. */
- optimize?: OcxRoutingProfileOptimize;
- limits?: OcxRoutingProfileLimits;
- /** How unknown evidence is handled per dimension. */
- unknownEvidence?: OcxRoutingProfileUnknownEvidence;
- /** Optional Compatibility Lab policy (CL-06). */
- compatibility?: OcxRoutingProfileCompatibility;
-}
-
-/**
- * Per-provider proactive-refresh policy. The guardian only ever touches a provider whose EFFECTIVE
- * policy is "proactive"; "lazy-only" keeps today's on-demand refresh, "disabled" forbids the
- * guardian entirely (used for providers whose ToS actively enforces against non-official-client
- * token traffic, e.g. Anthropic subscription OAuth). See devlog 260703_oauth-multi-account-refresh-and-tos.
- */
-export type RefreshPolicy = "proactive" | "lazy-only" | "disabled";
-
-export interface OcxTokenGuardianConfig {
- /** Global kill-switch. Default false — the guardian does nothing unless explicitly enabled. */
- enabled?: boolean;
- /** Seconds between refresh sweeps. Default 21600 (6h). Min 60. */
- tickSeconds?: number;
- /** Random 0..jitterSeconds added before each sweep to de-synchronize. Default 300. */
- jitterSeconds?: number;
- /** Max concurrent refreshes per sweep. Default 3. Min 1. */
- concurrency?: number;
- /** Extra lead (seconds) beyond one tick when deciding a token is "expiring soon". Default 900. */
- leadSeconds?: number;
- /** First backoff (seconds) after a permanent refresh failure. Default 300. */
- failureBackoffBaseSeconds?: number;
- /** Backoff ceiling (seconds). Default 3600. */
- failureBackoffMaxSeconds?: number;
- /** Optional Codex pool session warmup sweep. Default false to avoid background synthetic traffic. */
- codexWarmupEnabled?: boolean;
- /** Max age before a Codex pool account is revalidated via `/codex/responses`. Default 691200 (8d). */
- codexWarmupMaxAgeSeconds?: number;
- /** Model used for optional Codex pool warmup. Default gpt-5.4-mini. */
- codexWarmupModel?: string;
-}
-
-export interface OcxImagesConfig {
- /** Optional custom API-key provider for /v1/images relays. Built-in OpenAI tiers remain automatic. */
- provider?: string;
- /** Upstream timeout (ms) for one image generation/edit call (bridge xAI + /v1/images relay). Default 60000 for the bridge; relay may use a higher default (300000). */
- timeoutMs?: number;
- /** Master switch for the image bridge. Default false — set true to enable paid xAI Grok Imagine generation. */
- bridgeEnabled?: boolean;
- /** xAI image model id. Default "grok-imagine-image-quality" (see DEFAULT_MODEL in images/plan.ts). */
- bridgeModel?: string;
- /** Max image-generation loop iterations before forced-final. Default 3; clamped to [0, 10]. */
- maxRounds?: number;
- /** Max files retained under artifacts/. Oldest deleted when exceeded. Default 200. */
- artifactsKeepCount?: number;
- /** Master switch for the video bridge. Default false — must be explicitly opted in. */
- videoBridgeEnabled?: boolean;
- /** Model for xAI video generation. Default "grok-imagine-video". */
- videoBridgeModel?: string;
- /** Max video-gen rounds before forced-final. Default 2 (video is slower than image). */
- videoMaxRounds?: number;
- /** Per-video generation timeout (ms) including polling. Default 300000 (5 min). */
- videoTimeoutMs?: number;
-}
-
-export interface OcxSearchConfig {
- /**
- * Total upstream deadline (ms) for one /v1/alpha/search relay. Default 200000. The endpoint
- * is non-streaming JSON (headers arrive only when the search completes), so this is a whole-
- * request budget — deliberately NOT connectTimeoutMs, which is a header-arrival budget.
- */
- timeoutMs?: number;
-}
-
-export interface OcxVisionSidecarConfig {
- /** Master switch. Default: enabled when the selected backend has a usable credential. */
- enabled?: boolean;
- /** Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI. */
- backend?: "openai" | "anthropic";
- /** Vision model that describes images. */
- model?: string;
- /** Max description cache misses admitted in one main-model turn. Zero disables description calls. */
- maxDescriptionsPerTurn?: number;
- /** Sidecar fetch timeout (ms). */
- timeoutMs?: number;
-}
-
-export interface OcxWebSearchSidecarConfig {
- /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
- enabled?: boolean;
- /**
- * Which backend actually runs the server-side search. "openai" replays the hosted web_search via
- * the ChatGPT forward provider (gpt-mini sidecar); "anthropic" runs web_search_20250305 on a Claude
- * model authenticated by the STORED anthropic OAuth credential. Unset resolves to "anthropic" when a
- * usable anthropic OAuth credential exists, else "openai".
- */
- backend?: "openai" | "anthropic";
- /** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
- model?: string;
- /** Reasoning effort for the sidecar — "minimal" (non-thinking) keeps it fast/cheap. */
- reasoning?: string;
- /** Max searches executed per main-model turn (loop guard). */
- maxSearchesPerTurn?: number;
- /** Sidecar fetch timeout (ms). */
- timeoutMs?: number;
- /**
- * Config-file-only deadline (ms) for continuous routed-model response-body raw-byte inactivity
- * during a web-search turn. Default 200000. Must be an integer from 1 through 2147483647.
- */
- routedModelStallTimeoutMs?: number;
- /**
- * Stream the routed model's leading output (text/thinking deltas) live instead of buffering the
- * whole iteration. Live delivery stops at the first tool-call boundary so web_search interception
- * stays atomic. Tradeoff: text the model emits BEFORE deciding to search — which buffered mode
- * silently drops — becomes visible to the client and may partially repeat in the post-search
- * answer. Default: false (buffered, previous behavior).
- */
- streamRoutedModelOutput?: boolean;
-}
-
-export interface OpenRouterProviderRouting {
- /** OpenRouter provider slugs to try first, in priority order. */
- order?: string[];
- /** Restrict routing to these OpenRouter provider slugs. */
- only?: string[];
- /** Whether OpenRouter may use providers outside `order`. Defaults to OpenRouter's policy. */
- allowFallbacks?: boolean;
-}
-
-export interface ResponsesItemIdRepairConfig {
- /** Exact `message` item ids that the proxy should rewrite to request-local canonical ids. */
- message?: string[];
- /** Exact `reasoning` item ids that the proxy should rewrite to request-local canonical ids. */
- reasoning?: string[];
- /** Backfill missing `output_item.done` / terminal snapshot ids from the matching output_index. */
- repairMissingTerminalIds?: boolean;
- /**
- * Treat existing message/reasoning ids without the canonical `msg_`/`rs_` prefix (e.g. bare
- * UUIDs from DeepSeek's Responses route) as invalid and mint canonical replacements (#938).
- * function_call ids and call_id pairing are never rewritten.
- */
- repairInvalidIds?: boolean;
-}
-
-/**
- * Same-target 429 wait-and-retry policy (`providers..retryOn429`). When present and not
- * explicitly disabled, the proxy waits and replays the identical request on the same key before
- * any key failover. All fields optional; the runtime applies defaults (attempts=3,
- * intervalMs=5000, maxIntervalMs=60000, respectRetryAfter=true, enabled=true).
- */
-export interface RateLimitRetryPolicy {
- /** Master switch. The presence of the object also enables the policy (default true). */
- enabled?: boolean;
- /** Extra replay attempts after the first 429 (1..20, default 3). */
- attempts?: number;
- /** Fixed wait between attempts when the upstream sends no usable Retry-After (default 5000). */
- intervalMs?: number;
- /** Cap for any single wait, including an upstream Retry-After (default 60000). */
- maxIntervalMs?: number;
- /** Prefer the upstream Retry-After header when present and parseable (default true). */
- respectRetryAfter?: boolean;
-}
-
-/**
- * User-configured display price for one model (USD per 1M tokens).
- * Mirrors the `Cost4` shape used by the usage cost estimator; structurally
- * compatible so config rows can be lifted directly into price overlays.
- */
-export interface ProviderCostOverlay {
- input: number;
- output: number;
- cacheRead: number;
- cacheWrite: number;
-}
-
-export interface RequestPacingRule {
- /** Evenly spread request starts to this many requests per minute. */
- requestsPerMinute?: number;
- /** Minimum delay between request starts. The slower configured value wins. */
- minIntervalMs?: number;
-}
-
-export interface ProviderRequestPacingConfig extends RequestPacingRule {
- /** False preserves legacy behavior with no client-side waiting. */
- enabled: boolean;
- /** Exact upstream model-id overrides; other models inherit the provider rule. */
- models?: Record;
-}
-
-export interface FastWire {
- kind: "service-tier" | "anthropic-speed";
- /** Canonical tier name to upstream wire spelling. */
- canonicalToWire: Readonly>;
- /** Policy for non-canonical caller-provided tier values. */
- foreignCallerTiers: "verbatim" | "drop";
- /** Anthropic speed headers/betas reserved for the later wire implementation. */
- betas?: readonly string[];
-}
-
-/** Durable per-attempt service-tier fact produced at the adapter serialization boundary. */
-export interface AttemptTierOutcome {
- canonical?: "priority";
- wireKind?: FastWire["kind"] | null;
- wireValue?: string | null;
- fastOutcome: "not-requested" | "applied" | "downgraded" | "unknown";
- fastDowngradeReason?: "route-unsupported" | "wire-unavailable" | "response-declined";
- callerTierDropped?: boolean;
- callerFastSuppressedByConfig?: boolean;
- confirmation: "confirmed" | "assumed" | "downgraded" | "unknown";
- responseServiceTier?: string;
-}
-
-/**
- * Request-local observation inputs captured before the final tier action mutates the parsed view.
- * This is not persisted; the final adapter turns it into AttemptTierOutcome after serialization.
- */
-export interface TierObservationContext {
- capability: boolean | undefined;
- eligibility:
- | "eligible"
- | "capability-unsupported"
- | "unclassified"
- | "wire-unavailable"
- | "pin-unavailable";
- fastWire: FastWire | null;
- demandDecision: "force-fast" | "force-default" | "inherit";
- callerTier?: string;
-}
-
-export type TierDecision =
- | { readonly kind: "forward-caller" }
- | { readonly kind: "drop" }
- | { readonly kind: "set"; readonly value: string };
-
-/**
- * One configured provider entry. `authMode` (default `"key"`) decides whether same-target 429
- * retries are allowed; OAuth/forward credentials and local runtimes are never replayed.
- */
-export interface OcxProviderConfig {
- adapter: string;
- /** Optional outbound request-start pacing shared by this provider and its model overrides. */
- requestPacing?: ProviderRequestPacingConfig;
- /** Cursor MCP compatibility bounds; positive integers when configured. */
- mcpMaxTools?: number;
- mcpMaxSchemaBytes?: number;
- mcpMaxResultBytes?: number;
- /**
- * Per-model wire override, keyed by the upstream native model id (after namespace
- * and combo resolution). A single gateway can front models that speak different
- * wires — Grok needs the Responses API for hosted web_search while a sibling model
- * is fine on chat completions (#404).
- *
- * Only OpenAI-shaped wires may be selected; see MODEL_ADAPTER_OVERRIDE_ALLOWED.
- * Absent or empty means the provider-wide `adapter` applies to everything, exactly
- * as before.
- */
- modelAdapters?: Record;
- /**
- * Fast-wire declaration. `null` explicitly disables adapter-derived defaults;
- * absence derives from the final model adapter.
- */
- fastWire?: FastWire | null;
- baseUrl: string;
- /**
- * Optional relative resource path for key-auth openai-responses requests. Must start with `/`
- * and must not include a URL scheme, query string, or fragment. When omitted, the adapter keeps
- * the legacy `/v1/responses` construction.
- */
- responsesPath?: string;
- /**
- * Command Code protocol version sent as `x-command-code-version` on /alpha/generate requests.
- * The internal endpoint's schema drifts with the CLI version; operators can pin a known-good
- * version here instead of waiting for a code change. Absent uses the adapter's current default.
- */
- commandCodeVersion?: string;
- /**
- * Responses upstream that stores nothing server-side (DeepSeek documents "the API
- * is stateless"). Stateful request parameters are dropped, `store` is pinned false,
- * and orphaned tool results left by a replay miss are repaired rather than
- * forwarded to an upstream that cannot resolve their pair.
- */
- statelessResponses?: boolean;
- /**
- * Responses upstream whose parser requires an unambiguous call batch and its matched
- * result batch to remain contiguous. Hook-injected context that splits the batch is
- * preserved after it, and parallel calls stay together with the reasoning turn that produced them.
- */
- requiresAdjacentResponsesToolResults?: boolean;
- /**
- * Provider fallback for canonical Fast capability over an OpenAI `service_tier` wire.
- * This pure tri-state feeds catalog publication, routing eligibility, compatibility
- * fingerprints, and proxy-owned canonical Fast injection on both Responses and Chat routes.
- * Tri-state: `true` lets fast mode inject/remove the canonical field; `false` strips it and
- * never injects, because an upstream documented as not supporting the parameter
- * must not receive it; absent (`undefined`) leaves the provider unclassified — fast mode never
- * injects or translates, and caller values pass only under the final wire's forwarding permission.
- * On Chat, that CallerTierForward permission is `chatServiceTier`; Responses retains passthrough.
- * An explicit config value always wins over the registry default.
- */
- supportsServiceTier?: boolean;
- /** Exact upstream model ids that override the provider-level service-tier capability. */
- modelSupportsServiceTier?: Record;
- /**
- * Responses upstream whose native contract accepts plaintext reasoning replay
- * (DeepSeek documents reasoning items with plaintext content). When set, the
- * passthrough serializer keeps `reasoning_text` content on replayed reasoning
- * items instead of blanking it the way the ChatGPT backend requires; proxy-minted
- * `ocxr1` envelopes are still stripped because no upstream can decrypt them.
- */
- preserveResponsesReasoningContent?: boolean;
- /**
- * Explicit opt-in for non-registry private-network destinations such as localhost, RFC1918,
- * link-local, or unique-local upstreams. Metadata endpoints remain blocked.
- */
- allowPrivateNetwork?: boolean;
- /**
- * Pin the HTTP version used for upstream provider requests. Bun's fetch negotiates
- * HTTP/2 via TLS ALPN by default; some Cloudflare-fronted SSE endpoints hang on
- * HTTP/2 streaming responses (issue #1668). "http1.1" / "h1" forces HTTP/1.1,
- * "http2" / "h2" forces HTTP/2. Absent or "auto" keeps Bun's default negotiation
- * (current behavior unchanged). Explicit pins require an https: target and fail locally when the
- * pin cannot be honored. Cursor additionally maps an HTTP/1.1 pin onto its RunSSE + BidiAppend
- * compatibility transport.
- */
- upstreamHttpVersion?: UpstreamHttpVersion;
- /**
- * Google only. When `false`, the AI Studio (direct) path sends Gemini Flash ids
- * unchanged to the wire instead of applying the `-tiered` suffix (`gemini-3.7-flash`
- * -> `gemini-3.7-flash-tiered`). Set this to `false` when the configured upstream still
- * serves the bare ids. Absent (default) keeps the rename.
- */
- directGeminiWireRenames?: boolean;
- /** Keep provider settings on disk but exclude it from routing and model/catalog listings. */
- disabled?: boolean;
- /**
- * Codex account-selection mode. Valid ONLY on the canonical built-in `openai` forward provider.
- * "pool" (default) rotates main + added Codex accounts through the affinity/quota/cooldown/
- * failover engine; "direct" pins the caller's main Codex login and never touches pool state.
- */
- codexAccountMode?: CodexAccountMode;
- apiKey?: string;
- /**
- * Key-auth header style for Anthropic-compatible providers.
- * Defaults to the native Anthropic `x-api-key`; gateways may require
- * `Authorization: Bearer ` instead.
- */
- apiKeyTransport?: "x-api-key" | "bearer";
- /**
- * Multi-key pool (API-key twin of OAuth multiauth). `apiKey` always mirrors the ACTIVE
- * entry so routing stays single-key; managed via /api/providers/keys. A legacy bare
- * `apiKey` seeds a one-entry pool on first management touch.
- */
- apiKeyPool?: Array<{ id: string; key: string; label?: string; addedAt?: number }>;
- defaultModel?: string;
- models?: string[];
- /**
- * Fetch the provider's live `/models` endpoint. Defaults to true.
- * Set false when `models` is an intentional allowlist or a provider's live catalog is too large
- * or too flaky for startup/catalog sync.
- */
- liveModels?: boolean;
- /**
- * Per-provider catalog allowlist. When non-empty, ONLY these model ids are emitted to Codex's
- * catalog and `/v1/models` — live discovery still runs, this just narrows what ships (so a proxy
- * exposing thousands of models, or an aggregator like OpenRouter, doesn't bloat the catalog).
- * Empty/undefined = expose all. The admin `/api/models` list is unaffected (it always shows the
- * full set so the user can pick). See devlog issue_052_provider-model-allowlist.
- */
- selectedModels?: string[];
- /** Provider-wide fallback when context metadata is absent; otherwise caps the reported window. */
- contextWindow?: number;
- /** Per-model fallback when context metadata is absent; otherwise caps the reported window. */
- modelContextWindows?: Record;
- /** Model-specific Codex catalog input modalities, e.g. ["text"] or ["text", "image"]. */
- modelInputModalities?: Record;
- /** Model-specific max input token limits. Values cap auto_compact_token_limit. */
- modelMaxInputTokens?: Record;
- /**
- * Provider-wide fallback for chat-completions `max_tokens` when the caller omits
- * Responses `max_output_tokens`. Adapters still let an explicit request win.
- */
- defaultMaxOutputTokens?: number;
- /** Model-specific fallback output token budgets. Exact/model-pattern entries beat the provider default. */
- modelMaxOutputTokens?: Record;
- /**
- * Per-model display prices (USD per 1M tokens) keyed by exact model id —
- * opencode-style per-model pricing in ocx's flat `modelXxx` convention:
- * `{ "deepseek-v4-flash": { "input": 0.14, "output": 0.28, "cacheRead": 0.0028, "cacheWrite": 0 } }`.
- * User-configured prices win over the built-in jawcode/expected catalogs in
- * the Logs `~$` estimate. Display-time estimation only; never billing. An
- * all-zero entry means "not billable here" and falls through to the catalogs.
- */
- modelCosts?: Record;
- headers?: Record;
- /** Default provider-routing preferences for models sent through the canonical OpenRouter API. */
- openRouterRouting?: OpenRouterProviderRouting;
- /** Exact model-id overrides for `openRouterRouting`. Each matching entry replaces the default. */
- modelOpenRouterRouting?: Record;
- /**
- * "key" (default): authenticate upstream with `apiKey`.
- * "forward": relay the caller's incoming auth headers verbatim (OAuth passthrough; gpt only).
- * "oauth": resolve a stored OAuth access token (auto-refreshed) and use it as the Bearer key.
- * Only the openai-responses adapter implements "forward"; openai-chat uses its own key/token.
- * "local": local runtime (Ollama etc.) — no remote key required. Valid only for
- * providers whose registry entry declares authKind "local" (management API enforces).
- */
- authMode?: "key" | "forward" | "oauth" | "local";
- /** Allow an explicitly key/oauth provider to run without a credential (for keyless local proxies). */
- keyOptional?: boolean;
- /**
- * Free-tier pricing flag for UI/catalog (Free badge, Free filter). Not the same as
- * `keyOptional` — free tiers may still require an API key (e.g. NVIDIA NIM free credits).
- */
- freeTier?: boolean;
- /** Optional human note shown in the providers UI (not used for routing). */
- note?: string;
- /** Strip one trailing bracketed suffix from model ids before sending them upstream. */
- modelSuffixBracketStrip?: boolean;
- /**
- * Override the guardian's proactive-refresh policy for this provider. When unset, the provider's
- * built-in risk-tiered default applies (see OAUTH_PROVIDERS in src/oauth/index.ts). Set "proactive"
- * to opt this provider into background refresh; "disabled"/"lazy-only" to forbid/limit it.
- */
- refreshPolicy?: RefreshPolicy;
- /**
- * Provider-wide Codex-visible reasoning tiers for routed models. Use only Codex-supported labels
- * here (`low`, `medium`, `high`, `xhigh`, `max`); translate provider aliases with
- * `reasoningEffortMap` / `modelReasoningEffortMap` below.
- */
- reasoningEfforts?: string[];
- /** Model-specific Codex-visible reasoning tiers. An empty array means “do not expose effort”. */
- modelReasoningEfforts?: Record;
- /** Model-specific default Codex reasoning tier; must also be present in the visible tier list. */
- modelDefaultReasoningEfforts?: Record;
- /**
- * Model-specific Codex reasoning-summary capability. Set false when an OpenAI-compatible
- * Responses backend rejects Codex summary-delivery fields for that model.
- */
- modelSupportsReasoningSummaries?: Record;
- /**
- * Per-model wire value for Responses `stream_options.reasoning_summary_delivery`.
- * Presence also advertises reasoning-summary support for that routed model.
- */
- modelReasoningSummaryDelivery?: Record;
- /**
- * Exact-model hosted tools that win collisions with Codex client tool declarations.
- * Use for non-forward Responses gateways that reserve a hosted tool namespace server-side.
- */
- modelPreferHostedTools?: Record;
- /**
- * Provider-local repair for Responses gateways whose lifecycle snapshots omit canonical
- * fields or closing events (#893). Disabled by default and applied only to client-facing
- * SSE/JSON; raw inspection state remains authoritative.
- */
- responsesSnapshotRepair?: boolean;
- /** Provider-wide mapping from Codex effort labels to upstream `reasoning_effort` values. */
- reasoningEffortMap?: Record;
- /** Model-specific mapping from Codex effort labels to upstream `reasoning_effort` values. */
- modelReasoningEffortMap?: Record>;
- /** OpenAI-compatible gateway reasoning wire shape. Default sends `reasoning_effort`. */
- reasoningWireFormat?: "gateway-object";
- /**
- * Model ids that do NOT support a reasoning/thinking parameter. The openai-chat adapter drops
- * reasoning_effort for these even when Codex selects a reasoning level (e.g. xAI grok-build-0.1).
- */
- noReasoningModels?: string[];
- /** Model ids that reject caller-specified temperature. */
- noTemperatureModels?: string[];
- /** Model ids that reject caller-specified top_p. */
- noTopPModels?: string[];
- /** Model ids that reject caller-specified presence/frequency penalty values. */
- noPenaltyModels?: string[];
- /**
- * Model ids whose Chat Completions endpoint rejects `response_format`.
- * Structured-output translation remains enabled by default; this is a narrow
- * per-model compatibility escape hatch for mixed-capability gateways.
- */
- noStructuredOutputModels?: string[];
- /**
- * Allow multiple tool calls per completion. DEFAULT-ON for openai-chat providers (the
- * buffered stream parser assembles interleaved/fragmented multi-call turns safely);
- * set `false` to force `parallel_tool_calls:false` upstream and drop the catalog's
- * `supports_parallel_tool_calls` bit for that provider. Non-chat adapters advertise
- * only on explicit `true`. See devlog/_plan/260709_parallel_tool_calls.
- */
- parallelToolCalls?: boolean;
- /**
- * Opt-in: when `parallelToolCalls` is `false`, actually send `parallel_tool_calls: false`
- * on the `/chat/completions` wire for this provider. By default an opted-out provider only
- * OMITS the field (strict OpenAI-compatible hosts reject unknown knobs), and the NVIDIA NIM
- * baseUrl is the sole built-in exception that pins the wire bit. Some self-hosted gateways
- * (Kimi/GLM-family, vLLM, etc.) do honor `parallel_tool_calls` and keep emitting concurrent
- * tool calls unless it is present; enable this to pin the bit without hardcoding their URL.
- * No effect unless `parallelToolCalls === false`; ignored by non-`openai-chat` adapters.
- */
- pinParallelToolCallsFalse?: boolean;
- /**
- * Opt-in: extend the no-tool-call terminal continuation guard to this provider's
- * `openai-chat` routed turns. The guard (originally Anthropic-only, see
- * devlog/_fin/260706_previous-response-id-400) issues one bounded internal re-ask when a
- * model announces work but ends the turn without emitting a tool call. Self-hosted
- * OpenAI-compatible gateways (GLM/Kimi-family, etc.) hit the same premature-completion
- * pattern, but the heuristic that decides a "suspicious no-tool stop" was tuned on
- * Anthropic turns, so it stays OFF by default for the many registry providers that share
- * the `openai-chat` adapter. Enable only for a provider whose models are known to stop
- * mid-work; non-`openai-chat` adapters ignore this flag.
- */
- terminalContinuationGuard?: boolean;
- /**
- * Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
- * OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown
- * fields. Default off; only enable for providers that document this parameter.
- */
- promptCacheKey?: boolean;
- /**
- * Opt-in: forward caller `service_tier` values to the upstream `/chat/completions` body.
- * On a classified route it governs foreign values (for example `flex`), not proxy-owned
- * canonical Fast after capability validation. On an unclassified route it governs every caller
- * value, including canonical spellings, because no Fast capability has been validated.
- * OpenAI-specific extension with the same hazard as `promptCacheKey` — strict backends
- * reject unknown fields, and 66 registry providers share the `openai-chat` adapter, so a
- * caller-supplied `service_tier` would otherwise turn working requests into upstream 400s.
- * Exact-model `true` enables canonical Fast capability but does not grant foreign-tier
- * forwarding; provider-level `supportsServiceTier: false` remains a global denial. Default off;
- * only enable for providers that document this parameter on the chat wire.
- */
- chatServiceTier?: boolean;
- /**
- * Provider-local passthrough SSE repair for broken openai-responses gateways that reuse exact
- * placeholder message/reasoning ids or omit the terminal id after a stable added event.
- * Disabled by default; function_call ids and call_id pairing are never rewritten.
- */
- responsesItemIdRepair?: ResponsesItemIdRepairConfig;
- /** Model ids whose tool_choice only accepts `auto` or `none`; forced/named choices are downgraded. */
- autoToolChoiceOnlyModels?: string[];
- /** Model ids that expect prior assistant `reasoning_content` to be preserved in chat history. */
- preserveReasoningContentModels?: string[];
- /**
- * Model ids whose upstream hard-rejects a tool_call continuation missing
- * `reasoning_content` (DeepSeek thinking mode: HTTP 400). When the replay
- * cache misses, the adapter injects a minimal placeholder for these models.
- * Defaults to `preserveReasoningContentModels` when unset; set `[]` to opt
- * out explicitly (e.g. MiniMax, where low effort disables thinking).
- */
- requiresReasoningPlaceholderModels?: string[];
- /**
- * Opt-in same-target 429 retry policy. Codex itself never retries 429 (it retries 5xx only,
- * openai/codex#30471), and single-key pools have no failover, so the proxy waits and replays
- * the identical request on the same key before any failover. Pre-stream only: a 429 arrives
- * before any response bytes are relayed, so the replay is lossless.
- */
- retryOn429?: RateLimitRetryPolicy;
- /**
- * Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
- * thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.
- */
- reasoningSplitModels?: string[];
- /**
- * Model ids whose reasoning is a vendor `thinking: {type}` toggle on the
- * chat-completions wire (MiMo v2.x, GLM 5/5.1 style), NOT an OpenAI `reasoning_effort` ladder.
- * The openai-chat adapter translates the mapped effort into the thinking toggle for these.
- */
- thinkingToggleModels?: string[];
- /**
- * Model ids whose reasoning is a `thinking_budget` integer on the chat-completions wire
- * (Qwen3.x style), NOT an OpenAI `reasoning_effort` ladder. The openai-chat adapter maps the
- * Codex effort to a budget fraction.
- */
- thinkingBudgetModels?: string[];
- /** Anthropic-compatible gateways that need custom tool names escaped on the wire. */
- escapeBuiltinToolNames?: boolean;
- /**
- * Anthropic-compatible gateways (e.g. AgentRouter) that may close the stream before
- * `message_stop`. With this enabled the adapter completes an otherwise-clean EOF only when
- * visible text was received or an open tool call has complete JSON-object arguments; all
- * other EOFs remain truncation errors. Absent = strict default behavior.
- */
- anthropicEofTolerance?: boolean;
- /**
- * Model ids that do NOT accept image inputs. The proxy gives them "eyes" via the vision sidecar:
- * attached images are described by a gpt vision model and replaced with text before the call.
- */
- noVisionModels?: string[];
- /**
- * Google adapter mode. "ai-studio" (default) = Generative Language API + x-goog-api-key.
- * "vertex" = Vertex AI project/location endpoints with GCP ADC (or x-goog-api-key).
- * "cloud-code-assist" = Google Antigravity (Cloud Code Assist) OAuth + CCA envelope.
- */
- googleMode?: "ai-studio" | "vertex" | "cloud-code-assist";
- /** Vertex AI GCP project id (or GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env). */
- project?: string;
- /** Vertex AI location, e.g. "us-central1" or "global" (or GOOGLE_CLOUD_LOCATION env). */
- location?: string;
- /**
- * Cursor adapter only: MCP servers opencodex starts/connects and exposes to the Cursor agent
- * as callable tools. Each entry is spawned (stdio `command`) or connected (`url`) lazily per
- * stream; their tools are advertised to the Cursor server and executed against the live server.
- */
- mcpServers?: Record;
- /**
- * Cursor adapter only: opt-in external executor for computer-use / record-screen. opencodex is
- * headless and cannot control a screen itself; provide commands here only when running on a host
- * that can. With no executor, these tools honestly report "not supported".
- */
- desktopExecutor?: import("./adapters/cursor/native-exec-desktop").DesktopExecutorConfig;
- /**
- * Cursor adapter only: unsafe opt-in escape hatch for Cursor server-driven built-in local
- * read/write/delete/ls/grep/shell/fetch execution. Prefer `nativeLocalExec: "on"` for new
- * configs; this legacy boolean remains a server-local explicit opt-in for existing operators.
- * Defaults to false so remote Cursor messages cannot bypass Codex approval/sandbox semantics.
- * Explicit MCP and desktop executors remain controlled by their own opt-in config.
- */
- unsafeAllowNativeLocalExec?: boolean;
- /**
- * Cursor adapter only: native local exec policy mode (exec-policy.ts).
- * "off" (default) rejects server-driven local exec; "on" always allows it for this
- * provider and should be used only for a trusted local experiment on a host where every
- * data-plane caller is trusted. "codex-sandbox" is accepted for backwards compatibility
- * but is fail-closed like "off": Responses instructions/system/developer text is
- * caller-controlled prose, and opencodex has no trustworthy per-request attestation that it
- * reflects a real Codex sandbox state. The default loopback bind admits ANY local process
- * without auth (including other local users on multi-user machines), and
- * isAllowedRequestOrigin blocks non-loopback browser origins by default but not
- * loopback-origin or origin-less callers.
- */
- nativeLocalExec?: "off" | "codex-sandbox" | "on";
-}
-
-/**
- * Accepted values for the per-provider upstream HTTP-version pin (#1668). Shared by the
- * zod load schema, the management write boundary (POST/PATCH), and the fetch runtime, so
- * a value that one boundary accepts can never be rejected by another.
- */
-export const UPSTREAM_HTTP_VERSION_VALUES = [
- "auto",
- "http1.1",
- "h1",
- "http2",
- "h2",
-] as const;
-
-export type UpstreamHttpVersion = (typeof UPSTREAM_HTTP_VERSION_VALUES)[number];
-
-export const REASONING_SUMMARY_DELIVERY_VALUES = [
- "sequential",
- "sequential_cutoff",
- "concurrent",
- "concurrent_cutoff",
-] as const;
-
-export type ReasoningSummaryDelivery = typeof REASONING_SUMMARY_DELIVERY_VALUES[number];
-
-/** Trusted runtime ownership for Codex-account credentials. Never persisted per provider. */
-export type CodexAccountMode = "direct" | "pool";
-
-export const OPENAI_PROVIDER_TIER_VERSION = 2 as const;
-
-/**
- * Wires that a per-model `modelAdapters` override may select.
- *
- * Deliberately narrow: provider-specific adapters (cursor, kiro, google, ...) carry
- * their own credential and base-URL semantics, so exposing them here would widen the
- * auth boundary rather than pick a wire. Widening this set needs a per-adapter
- * credential threat model first (#404).
- */
-export const MODEL_ADAPTER_OVERRIDE_ALLOWED: ReadonlySet = new Set([
- "openai-chat",
- "openai-responses",
-]);
-
-/**
- * Providers whose listed model ids must be driven over the Anthropic wire even when
- * the provider's configured adapter says otherwise — the upstream only speaks
- * Anthropic for these models.
- */
-const ANTHROPIC_WIRE_MODELS: Record> = {
- "opencode-go": new Set(["minimax-m2.5", "minimax-m2.7", "minimax-m3"]),
-};
-
-function anthropicWireModelsForProvider(providerName: string): ReadonlySet | undefined {
- return Object.hasOwn(ANTHROPIC_WIRE_MODELS, providerName)
- ? ANTHROPIC_WIRE_MODELS[providerName]
- : undefined;
-}
-
-/** Detached provider-local hard-pin table for pure wire-policy resolution. */
-export function captureWireAdapterHardPins(providerName: string): Readonly> {
- const models = anthropicWireModelsForProvider(providerName);
- if (!models) return Object.freeze({});
- return Object.freeze(Object.fromEntries([...models].map(modelId => [modelId, "anthropic"])));
-}
-
-/**
- * True when the upstream speaks exactly one wire for this model, so a configured
- * override must not apply.
- *
- * Deliberately independent of the provider's current adapter: the wire resolver runs
- * more than once per request, and a check phrased as "pin differs from the current
- * adapter" would pass on the first pass and then let the override win on the second.
- */
-export function isWirePinnedModel(providerName: string, modelId: string): boolean {
- return anthropicWireModelsForProvider(providerName)?.has(modelId) ?? false;
-}
-
-/** The wire a pinned model must use, or undefined when the model is not pinned. */
-export function pinnedWireAdapter(providerName: string, modelId: string): string | undefined {
- return isWirePinnedModel(providerName, modelId) ? "anthropic" : undefined;
-}
-
-export interface CodexAccount {
- id: string;
- email: string;
- /** User-owned display label; never participates in routing or identity checks. */
- alias?: string;
- plan?: string;
- /**
- * Provenance of `plan`. WHAM (live quota API) is authoritative; the JWT
- * `chatgpt_plan_type` claim is a fallback that may lag a plan change. A JWT write
- * must never overwrite a WHAM-sourced plan observed for the same credential
- * generation — only a newer generation (token refresh after the WHAM read) may.
- */
- planSource?: "jwt" | "wham";
- /** Credential generation at which `plan`/`planSource` was recorded. */
- planCredentialGeneration?: number;
- chatgptAccountId?: string;
- logLabel?: string;
- isMain: boolean;
-}
-
-export interface CodexAccountCredentials {
- accessToken: string;
- refreshToken: string;
- expiresAt: number;
- chatgptAccountId: string;
-}
-
-export interface CodexAccountCredentialRecord {
- credential?: CodexAccountCredentials;
- generation: number;
- refreshGrantFingerprint?: string;
- deletedAt?: number;
- replacedAt?: number;
- lastCodexValidatedAt?: number;
- lastCodexValidationStatus?: "ok" | "failed";
- lastCodexValidationError?: string;
-}
diff --git a/src/types/accounts.ts b/src/types/accounts.ts
new file mode 100644
index 0000000000..5ff48945c7
--- /dev/null
+++ b/src/types/accounts.ts
@@ -0,0 +1,37 @@
+export interface CodexAccount {
+ id: string;
+ email: string;
+ /** User-owned display label; never participates in routing or identity checks. */
+ alias?: string;
+ plan?: string;
+ /**
+ * Provenance of `plan`. WHAM (live quota API) is authoritative; the JWT
+ * `chatgpt_plan_type` claim is a fallback that may lag a plan change. A JWT write
+ * must never overwrite a WHAM-sourced plan observed for the same credential
+ * generation — only a newer generation (token refresh after the WHAM read) may.
+ */
+ planSource?: "jwt" | "wham";
+ /** Credential generation at which `plan`/`planSource` was recorded. */
+ planCredentialGeneration?: number;
+ chatgptAccountId?: string;
+ logLabel?: string;
+ isMain: boolean;
+}
+
+export interface CodexAccountCredentials {
+ accessToken: string;
+ refreshToken: string;
+ expiresAt: number;
+ chatgptAccountId: string;
+}
+
+export interface CodexAccountCredentialRecord {
+ credential?: CodexAccountCredentials;
+ generation: number;
+ refreshGrantFingerprint?: string;
+ deletedAt?: number;
+ replacedAt?: number;
+ lastCodexValidatedAt?: number;
+ lastCodexValidationStatus?: "ok" | "failed";
+ lastCodexValidationError?: string;
+}
diff --git a/src/types/config.ts b/src/types/config.ts
new file mode 100644
index 0000000000..f00bfbcdd4
--- /dev/null
+++ b/src/types/config.ts
@@ -0,0 +1,818 @@
+import type { OcxProviderConfig } from "./provider";
+import type { CodexAccount } from "./accounts";
+
+/**
+ * Claude Code inbound settings (devlog/260711_claude_inbound). Consumed by the
+ * /v1/messages surface, the `ocx claude` launcher, and the GUI Claude page.
+ */
+export interface OcxClaudeCodeConfig {
+ /** Kill switch for the /v1/messages inbound (GUI "Claude ON" toggle). Default: enabled. */
+ enabled?: boolean;
+ /**
+ * Verbatim passthrough of unmapped claude/anthropic models to api.anthropic.com with the
+ * caller's own sk-ant-* credential (Claude Code subscription OAuth). Default: enabled.
+ */
+ nativePassthrough?: boolean;
+ /** Upstream for the native passthrough (tests/enterprise gateways). Default: https://api.anthropic.com */
+ anthropicBaseUrl?: string;
+ /**
+ * Native passthrough body inactivity budget in SECONDS — raw upstream-byte silence
+ * while a read is pending, NOT total duration (slow-but-alive streams never trip it;
+ * devlog 260716_passthrough_followups/010). Default 90. Min 1. Exactly 0 disables;
+ * negative/non-finite values fall back to the default.
+ */
+ bodyStallSec?: number;
+ /**
+ * Native passthrough cumulative body byte cap (streamed SSE and buffered non-stream
+ * alike) — an OOM/occupancy guard, not a correctness limit. Default 67108864 (64 MiB).
+ * Exactly 0 disables; negative/non-finite values fall back to the default.
+ */
+ bodyMaxBytes?: number;
+ /** Default model slot injected as ANTHROPIC_MODEL by `ocx claude`. */
+ model?: string;
+ /** Haiku/small-fast slot injected as ANTHROPIC_DEFAULT_HAIKU_MODEL (+ legacy SMALL_FAST). */
+ smallFastModel?: string;
+ /** Inbound model id remaps: exact id first, then date-stripped (`-\d{8}$`). */
+ modelMap?: Record;
+ /**
+ * Explicit classifier model for Claude Code Auto Mode safety checks (e.g. "RelayA/claude-opus-5").
+ * When unset, bare classifier requests check modelMap, then same-provider affinity from
+ * `claudeCode.model`, then compatible Anthropic-adapter providers, and finally fallbacks.
+ */
+ classifierModel?: string;
+ /**
+ * Ordered fallback candidates for Claude Code Auto Mode classifier routing when the primary
+ * classifier route is not available.
+ */
+ classifierFallbacks?: string[];
+ /**
+ * Inject ANTHROPIC_BASE_URL etc. into the macOS user domain via `launchctl setenv`
+ * so plain `claude` commands route through the proxy without `ocx claude`. Reverted
+ * on stop/shutdown. Default: false (opt-in). macOS only.
+ */
+ systemEnv?: boolean;
+ /**
+ * Auth mode for Claude Code inbound requests — a THREE-state intent.
+ *
+ * "proxy": inject the dummy ANTHROPIC_AUTH_TOKEN so Claude Code routes through the
+ * proxy without a real Anthropic key. "subscription": never inject it. UNSET means
+ * AUTO: the mode is resolved from detected Claude auth on every launch and every
+ * status read (src/claude/auth-mode.ts), so registering a Claude login switches the
+ * behaviour with no migration and no stored state.
+ *
+ * An explicit value always wins over detection and is never rewritten by the auto
+ * logic — that is what makes a manual choice stick (devlog 260726_claude_auth_auto).
+ */
+ authMode?: "proxy" | "subscription";
+ /**
+ * ISO timestamp of the one-time authMode migration. Before auto existed, choosing
+ * "Subscription" DELETED the key, so a pre-upgrade config cannot distinguish an
+ * explicit subscription choice from "never chose". Its ABSENCE identifies a
+ * pre-upgrade block; the migration writes it once and never re-runs, so a user who
+ * later picks Auto (which deletes authMode) is not silently converted back.
+ */
+ authModeMigratedAt?: string;
+ /**
+ * Context-window override for Claude Code/Desktop clients (devlog 136 B6):
+ * injected as CLAUDE_CODE_MAX_CONTEXT_TOKENS + DISABLE_COMPACT=1 (the official
+ * env pair — recognized claude-shaped ids need both). WARNING: DISABLE_COMPACT
+ * turns off auto-compaction. Unset = client defaults.
+ */
+ maxContextTokens?: number;
+ /**
+ * Opt-in CLAUDE_CODE_ALWAYS_ENABLE_EFFORT=1 injection. Default OFF: opus-shaped
+ * aliases already carry output_config.effort on the wire (devlog 136 실측), and
+ * forcing effort on every request can leak reasoning params to non-reasoning routes.
+ */
+ alwaysEnableEffort?: boolean;
+ /**
+ * Subagent tier slots (devlog 260712 B2): injected as ANTHROPIC_DEFAULT_*_MODEL so
+ * Claude Code's Agent-tool aliases (opus/sonnet/haiku/fable + parent-inherit) route
+ * to proxy models. haiku falls back to smallFastModel (one effective value feeds
+ * both ANTHROPIC_DEFAULT_HAIKU_MODEL and legacy ANTHROPIC_SMALL_FAST_MODEL).
+ */
+ tierModels?: { opus?: string; sonnet?: string; haiku?: string; fable?: string };
+ /**
+ * Auto-context (devlog 260712 020): when not false, routed/native models whose
+ * authoritative window is > 200k AND >= the compact window get the [1m] marker
+ * (Claude Code then accounts 1M) and CLAUDE_CODE_AUTO_COMPACT_WINDOW is injected
+ * so compaction fires at the real budget. 2.1.207 semantics (binary-verified):
+ * effective compact window = min(believed window, env) — one global env behaves
+ * like a per-model floor. Default: enabled. Inert while maxContextTokens is set
+ * (the legacy DISABLE_COMPACT pair takes rule-1 precedence in the CLI).
+ */
+ autoContext?: boolean;
+ /** Compact-window tokens for auto-context. Default 829_800 (AUTO_COMPACT_WINDOW_DEFAULT). */
+ autoCompactWindow?: number;
+ /**
+ * Bundled-skill content elision for ROUTED (non-Anthropic) models (devlog 260712
+ * 060): Skill-tool results whose skill name matches an entry here are replaced
+ * with a short stub in the anthropic->responses translation. Third-party models
+ * are not trained on these Anthropic doc bundles, and claude-api alone injects
+ * ~136k tokens (GitHub anthropics/claude-code#74473). Native Anthropic
+ * passthrough never goes through the translation, so Claude models keep the
+ * full content. Default: ["claude-api"]. Empty array = explicitly off.
+ */
+ blockedSkills?: string[];
+ /**
+ * Sync the featured subagent roster (config.subagentModels + main model) into
+ * ~/.claude/agents/ocx-*.md custom agent definitions at launch (devlog 260712
+ * 070) so any routed model is dispatchable as a subagent_type — the Agent
+ * tool's model argument is a hard 4-alias enum, but definition frontmatter is
+ * free. Only ocx-*.md files are owned/pruned. Default: enabled.
+ */
+ injectAgents?: boolean;
+ /**
+ * Optional Claude Code effort pinned in every generated ocx-* subagent
+ * definition. Unset inherits the parent session effort.
+ */
+ subagentEffort?: "low" | "medium" | "high" | "xhigh" | "max";
+ /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
+ webSearchSidecar?: { backend?: "openai" | "anthropic"; model?: string };
+ /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
+ visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
+ /** Persisted Claude Desktop four-family routing profile. */
+ desktopProfile?: OcxClaudeDesktopProfile;
+ /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
+ desktopAutoApply?: boolean;
+ /**
+ * When false, omit `native/*` rows from Claude Desktop show/export/apply. Default: enabled.
+ * Routing-sidecar alias decoding is unchanged — only the Desktop model list writer.
+ */
+ desktopNativeModels?: boolean;
+}
+
+export type OcxClaudeDesktopFamily = "opus" | "fable" | "sonnet" | "haiku";
+
+export interface OcxClaudeDesktopAssignment {
+ family: OcxClaudeDesktopFamily;
+ alias: string;
+}
+
+export interface OcxClaudeDesktopProfile {
+ version: 1;
+ assignments: Record;
+ defaults: Record;
+ /** SHA-256 fingerprint of the last successfully applied 3P config content. */
+ appliedFingerprint?: string;
+ /** ISO timestamp of the last successful apply. */
+ appliedAt?: string;
+}
+
+/**
+ * Opt-in archived-session auto-cleanup policy (issue #42 Phase 3).
+ * Persisted under `OcxConfig.storageCleanupPolicy`. Default `enabled: false`.
+ */
+export interface StorageCleanupPolicy {
+ /** When false/unset, the engine never mutates. Default false. */
+ enabled: boolean;
+ /** Run when archived session bytes exceed this threshold. */
+ trigger: { archivedBytesOver: number };
+ /** Either shrink archives toward a byte floor, or remove the oldest N%. */
+ target: { reduceToBytes?: number } | { removeOldestPercent?: number };
+ schedule: "startup" | "daily" | "weekly" | "manual";
+ /** Default quarantine. Permanent only when explicitly set. */
+ mode: "quarantine" | "permanent";
+ lastRun?: { at: number; freedBytes: number; removed: number };
+ /** Epoch ms when the next scheduled evaluation is due. */
+ nextRun?: number;
+}
+
+/** 사용자가 대시보드에서 직접 추가한 커스텀 모델 정의. */
+export interface OcxCustomModel {
+ /** 고유 ID (crypto.randomUUID()) */
+ id: string;
+ /** 프로바이더 키 (기존 providers[name]) */
+ provider: string;
+ /** Native provider model id; slashes are allowed and encoded for Codex as provider/. */
+ modelId: string;
+ /** 인간 가독 표시명 (선택, 슬래시 불가) */
+ displayName?: string;
+ /** 컨텍스트 윈도우 (토큰) */
+ contextWindow?: number;
+ /** 입력 모달리티 (선택, 기본 ["text"]) */
+ inputModalities?: string[];
+ /**
+ * Reasoning ladder (Codex labels) this custom row explicitly advertises. An empty array
+ * hides the effort control; an omitted key leaves the provider-derived ladder in charge.
+ */
+ reasoningEfforts?: string[];
+ /** Default effort label when `reasoningEfforts` is non-empty. */
+ defaultReasoningEffort?: string;
+ /**
+ * Codex tool calling mode override for this custom model.
+ * "code_mode_only" (default) sets entry.tool_mode = "code_mode_only".
+ * "shell" leaves tool_mode unset so Codex declares top-level shell tools (exec_command).
+ */
+ codexToolMode?: "code_mode_only" | "shell";
+ /** 추가 시각 (ISO 8601) */
+ addedAt?: string;
+}
+
+/**
+ * A generated `ocx_` data-plane key. `key` is the secret itself and never leaves
+ * the server except in the one-time POST /api/keys response; every other surface
+ * sees only the masked prefix.
+ */
+export interface OcxApiKeyEntry {
+ id: string;
+ name: string;
+ key: string;
+ createdAt: string;
+}
+
+/**
+ * Durable per-client intent. One key today, deliberately.
+ *
+ * A top-level `codexEnabled` would force every later client to invent an
+ * unrelated name and its own helpers; a ten-key union recreated the coupling
+ * that failed two audits, because every phase then had to touch every client's
+ * write path. A one-key object keeps the extension point without letting this
+ * phase claim ownership over a client it does not implement.
+ */
+export interface OcxClientIntegrationsConfig {
+ /** Durable desired state for native Codex. MISSING MEANS ON. */
+ codex?: boolean;
+ /** Durable desired state for Grok Build. MISSING MEANS ON. */
+ grok?: boolean;
+ /** Durable desired state for Claude Desktop. MISSING MEANS ON. */
+ "claude-desktop"?: boolean;
+}
+
+export interface OcxConfig {
+ port: number;
+ /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */
+ emptyCompletionRetry?: boolean;
+ /** Maximum usage-log bytes read for one management snapshot. */
+ managementUsageMaxReadBytes?: number;
+ providers: Record;
+ defaultProvider: string;
+ /** OpenAI provider-contract migration marker (v2 = single `openai` provider with account mode). */
+ openaiProviderTierVersion?: 1 | 2;
+ /** One-time migration marker for Antigravity's static-catalog defaults. */
+ googleAntigravityStaticCatalogVersion?: 1 | 2;
+ /** Claude Code inbound + launcher settings. */
+ claudeCode?: OcxClaudeCodeConfig;
+ /**
+ * Per-client durable intent. This phase owns only `codex`; later phases extend
+ * one key at a time rather than widening a shared union.
+ */
+ clientIntegrations?: OcxClientIntegrationsConfig;
+ /**
+ * Up to 5 Codex-facing catalog ids to feature first. Values may be bare catalog ids,
+ * exact account-qualified "/" ids, or routed
+ * "/" ids. With account selectors, one bare native choice can expand
+ * into a selector-qualified group; Codex still advertises only the first 5 visible rows.
+ */
+ subagentModels?: string[];
+ /**
+ * Optional full picker ordering for the Codex model catalog, independent of the
+ * 5-slot `subagentModels` spawn_agent cap. DISPLAY-ONLY: it controls the visual order of
+ * the Codex model picker for large routed catalogs (10-20+ models) that would otherwise sort
+ * arbitrarily and reshuffle on every rebuild. Values are routed `/` catalog
+ * slugs (matched by exact slug or `provider/id`); native OpenAI passthrough rows and
+ * account-qualified native rows are not reordered (order native rows via `subagentModels`).
+ * Listed routed rows appear in array order; rows not listed keep their normal display order.
+ * `subagentModels`-featured rows keep their top position. When unset or empty, catalog
+ * priority is unchanged. This changes ONLY what the user sees in the picker: the spawn_agent
+ * candidate set is derived from each row's natural priority and is provably unaffected, even
+ * when every routed row is listed (see opencodex_spawn_priority / effectiveSubagentRoster).
+ */
+ modelPickerOrder?: string[];
+ /**
+ * Priority-ordered fallback models for spawned sub-agents. When the requested
+ * model is quota-exhausted or recently failed, opencodex rewrites the child
+ * turn to the next available entry before routing.
+ */
+ subagentModelFallback?: string[];
+ /**
+ * Per-primary-model fallback chains for spawned sub-agents, keyed by the
+ * requested primary model id (bare native or "provider/model"). Entries for
+ * the matching key are consulted after the requested model and before the
+ * global `subagentModelFallback` list.
+ *
+ * This is the supported home for per-role fallback metadata: storing it as
+ * `model_fallback` inside `$CODEX_HOME/agents/*.toml` makes Codex >= 0.146
+ * reject the whole role file as an unknown field (#1190).
+ */
+ subagentModelFallbackByModel?: Record;
+ /**
+ * TTL (ms) for cached sub-agent model availability probes. Default 60_000.
+ */
+ subagentModelFallbackPollMs?: number;
+ injectionModel?: string;
+ /**
+ * Opt in to synchronizing the selected injection model into Codex's native
+ * sub-agent defaults. Only meaningful while `injectionModel` is set.
+ */
+ syncCodexSubagentDefaults?: boolean;
+ /**
+ * Optional reasoning effort the delegation prompt tells the agent to pass in spawn_agent calls
+ * (`reasoning_effort` argument). Only meaningful while `injectionModel` is set; validated against
+ * the Codex ladder (src/reasoning-effort.ts CODEX_REASONING_LEVELS) at the API boundary.
+ */
+ injectionEffort?: string;
+ /**
+ * Explicit sideband websocket base for realtime/live joins, mirroring upstream's
+ * `experimental_realtime_ws_base_url`. The value is a ROOT (or a recognized
+ * `/realtime`, `/realtime/calls/`, `/live/` endpoint form, which is
+ * stripped back to the root); `/v1` is appended during normalization. Intended
+ * for local development against a fake realtime server — plaintext `http`/`ws`
+ * is accepted only for loopback hosts, and URL userinfo is rejected; both
+ * failures close to the canonical `https://api.openai.com/v1`. Configured by
+ * editing this file; there is deliberately no management-API or GUI surface.
+ */
+ experimentalRealtimeWsBaseUrl?: string;
+ /**
+ * Model ids the user has EXCLUDED from the Grok Build managed block. Absent or empty
+ * means "everything visible", which is the historical behaviour — so an existing
+ * config keeps the fence it already had.
+ *
+ * Exclusion list rather than an inclusion list on purpose: a newly added provider
+ * model should appear in Grok by default, exactly as it does today. An inclusion list
+ * would silently hide every future model behind a switch nobody knew to flip.
+ */
+ grokExcludedModels?: string[];
+ /**
+ * When true, OpenAI-routed requests include `service_tier: "priority"` (fast inference).
+ * When false, service_tier is stripped so requests use default speed.
+ * Undefined = passthrough (don't modify what the client sends).
+ */
+ fastMode?: boolean;
+ /**
+ * Windows/macOS SSE passthrough stream shape (#314 mitigation).
+ * On Windows, "auto" (default) selects eager relay only on a runtime proven
+ * to carry the Bun#32111 fix. On macOS, "auto" always stays on legacy tee and
+ * eager relay is explicit-only. "eager-relay" opts into the new relay (and
+ * accepts #32111 crash risk on Bun 1.3.14); "legacy-tee" pins the tee path.
+ * Persisted in config.json so service users can select the stream shape.
+ * See src/lib/bun-stream-caps.ts.
+ */
+ streamMode?: "auto" | "legacy-tee" | "eager-relay";
+ /**
+ * Custom override for the injected v2 multi-agent guidance body (the text inside
+ * the tags). After guidance is enabled and the v2 surface and
+ * catalog-state gates pass, a configured injectionModel is sufficient to render it;
+ * otherwise an eligible roster or fallback is required. Placeholders: `{{model}}` -> the
+ * effective preferred model for the request (a bare native model is account-qualified
+ * only when the request targets an explicit account selector; unresolved or ambiguous
+ * bare values become "", while unresolved explicit routed or account-qualified values
+ * remain unchanged),
+ * `{{effort}}` -> injectionEffort, `{{roster}}` -> the resolved sub-agent roster
+ * block ("" when nothing resolves), `{{fallback}}` -> the configured subagent
+ * model fallback guidance block ("" when unset).
+ */
+ injectionPrompt?: string;
+ /**
+ * Proxy-authored multi-agent developer guidance. Undefined/true = enabled for
+ * backward compatibility; false suppresses both v1 and v2 guidance injection.
+ */
+ multiAgentGuidanceEnabled?: boolean;
+ /**
+ * Global hard ceiling for the reasoning effort of EVERY proxied turn (main agent AND
+ * sub-agents). Ladder value "low".."max"; incoming efforts ranking above it are rewritten
+ * in both request shapes before any adapter or clamp. Unset = no cap. codex-rs converts
+ * ultra -> max client-side, so e.g. a "high" cap sends ultra/max-tier turns as high.
+ */
+ effortCap?: string;
+ /**
+ * Hard ceiling applied ONLY to sub-agent turns — requests carrying codex-rs's spawned-child
+ * markers (`x-openai-subagent` header, or `subagent_kind` inside `x-codex-turn-metadata`).
+ * Lets the main agent keep its tier while delegated children are capped. When both caps are
+ * set, the lower one wins for sub-agents. See src/server/effort-policy.ts.
+ */
+ subagentEffortCap?: string;
+ /**
+ * Models hidden from Codex discovery without blocking direct proxy calls. Routed provider ids
+ * are excluded from the catalog + /v1/models entirely. Account-qualified native ids hide only
+ * their generated selector row and are omitted from raw /v1/models. BARE native GPT ids hide
+ * the bare row plus every generated selector row and omit that model family from raw discovery.
+ */
+ disabledModels?: string[];
+ /** 사용자가 대시보드에서 직접 추가한 커스텀 모델 목록. */
+ customModels?: OcxCustomModel[];
+ /**
+ * Internal, versioned evidence for reconciling custom-model deletions with
+ * pre-marker Codex catalog rows. Consumers must parse this defensively so a
+ * future state written by a newer binary survives older whole-config saves.
+ */
+ customModelCatalogMigration?: unknown;
+ /**
+ * Shadow call intercept: redirect Codex's hard-coded helper calls (title generation,
+ * commit messages, skill orchestration) to a user-chosen model. Default intercepted
+ * source models: gpt-5.4-mini (older clients) and gpt-5.6-luna (Codex 0.145.0+).
+ * Opt-in; disabled by default. Matching maintenance/helper requests are forced to low.
+ * All requests for configured shadow source models are intercepted unconditionally.
+ */
+ shadowCallIntercept?: {
+ /** When true, requests for known shadow/helper source models are rewritten to the configured model. */
+ enabled?: boolean;
+ /** Replacement model id (e.g. "gpt-5.5"). */
+ model?: string;
+ /** Optional override of intercepted source-model prefixes (default: gpt-5.4-mini, gpt-5.6-luna). */
+ sourceModels?: string[];
+ };
+ /**
+ * 3-state multi-agent surface override:
+ * - "v1": force ALL models to v1 surface (override upstream pins)
+ * - "default" | undefined: respect upstream model pins (sol/terra=v2, luna=v1, rest=codex flag)
+ * - "v2": force ALL models to v2 surface (override upstream pins)
+ */
+ multiAgentMode?: "v1" | "default" | "v2";
+ /**
+ * When `multiAgentMode` is `"v2"`, keep ChatGPT-native catalog rows on v1.
+ * Routed parents get v2 tools; Sol/Terra can still spawn Grok/Claude (issue #92).
+ */
+ keepNativeChatGptOnV1?: boolean;
+ /** Experimental, default-off ChatGPT recovery for encrypted V2 routed tasks. */
+ agentTaskRecovery?: {
+ enabled?: boolean;
+ /** ChatGPT model used by the recovery request. Default: gpt-5.6-sol. */
+ model?: string;
+ /** Recovery request timeout in milliseconds. Default: 45000. */
+ timeoutMs?: number;
+ /** Maximum in-memory ciphertext-to-assignment entries. Default: 200. */
+ cacheEntries?: number;
+ };
+ /** Provider-level Codex-visible context caps. Values only lower known model context windows. */
+ providerContextCaps?: Record;
+ /** Global Codex-visible context cap value (tokens). Falls back to DEFAULT_PROVIDER_CONTEXT_CAP. */
+ contextCapValue?: number;
+ /** Bind hostname. Default "127.0.0.1" (loopback only). Set "0.0.0.0" to expose on all interfaces. */
+ hostname?: string;
+ /**
+ * Optional second listener bound to 127.0.0.1 that admits data-plane requests without a
+ * credential (issue #1102).
+ *
+ * Why a separate listener rather than an exemption on the main one: when `hostname` is a
+ * wildcard, every caller needs `x-opencodex-api-key`, but a `codex app-server` spawned
+ * directly from the resolved entrypoint never goes through the generated shim and so never
+ * inherits the token. Exempting "loopback-looking peers" on the public listener would be
+ * unsound — `requestIP()` only proves the last transport hop, and Docker Desktop port
+ * forwarding, host-network containers, WSL mirrored networking and tunnels all terminate
+ * remote connections locally. Binding a second socket to 127.0.0.1 makes the kernel refuse
+ * remote connections outright, so there is no address to judge.
+ *
+ * The public listener's admission policy is unchanged. This adds an explicit local trust
+ * surface: every process on the machine can reach it, spend account quota, and consume paid
+ * provider credentials. Off by default; not for multi-tenant hosts.
+ *
+ * The port is required when enabled and must differ from the proxy port. An OS-assigned port
+ * would change across restarts, which would break already-running app-servers holding the
+ * previous `base_url` — the exact symptom #1102 reported and we disproved for token rotation.
+ */
+ unauthenticatedLoopbackListener?:
+ | { enabled: false }
+ | { enabled: true; port: number };
+ /**
+ * Outbound HTTP(S) proxy URL for provider requests (e.g. "http://user:pass@proxy:8080", or
+ * "${HTTPS_PROXY}"-style env reference). Mirrored into HTTP_PROXY/HTTPS_PROXY at startup when
+ * those are unset — Bun's fetch honors them for all outbound calls; localhost is excluded.
+ */
+ proxy?: string;
+ /**
+ * Upstream stall timeout (seconds). After this many seconds of no upstream data, emits
+ * response.incomplete. Default 300. Min 1.
+ */
+ stallTimeoutSec?: number;
+ /** Connect timeout (ms) for upstream fetch — covers DNS, TCP, TLS, and response header. Default 200000. */
+ connectTimeoutMs?: number;
+ /** Graceful shutdown drain timeout (ms). Active turns are aborted after this deadline. Default 5000. */
+ shutdownTimeoutMs?: number;
+ /** Advertise supports_websockets so Codex opens the WS endpoint. Default false; set true to opt in. */
+ websockets?: boolean;
+ /**
+ * Opt-in auto-cleanup policy for archived Codex sessions (issue #42 Phase 3).
+ * Default OFF (`enabled` false / unset). Never enabled implicitly.
+ * See `src/storage/policy.ts`.
+ */
+ storageCleanupPolicy?: StorageCleanupPolicy;
+ /** Generated API keys for external access to the proxy's /v1/responses endpoint. */
+ apiKeys?: OcxApiKeyEntry[];
+ /** Auto-start/sync the proxy from the Codex shim before launching Codex. Default true. */
+ codexAutoStart?: boolean;
+ /** Restore an installed shim after a stable external Codex update replaces it. Default true. */
+ codexShimAutoRestore?: boolean;
+ /**
+ * Compatibility mode: temporarily rewrite Codex resume-history metadata while the proxy is active
+ * so Codex App can show old OpenAI chats and opencodex-created exec chats under its default
+ * interactive-source/provider filters. Default true; originals are backed up and restored by
+ * `ocx stop` / `ocx restore`. Set false to opt out of history remapping.
+ */
+ syncResumeHistory?: boolean;
+ /** Freshness window (ms) for the per-provider live `/models` cache. Defaults to 5 min. */
+ modelCacheTtlMs?: number;
+ /** Evictable retained app-state budget in MiB. Default 256; valid 64..4096. */
+ appOwnedMemoryBudgetMb?: number;
+ /** Anthropic prompt-cache retention: "short" = 5-min ephemeral (default), "long" = 1-hour extended, "none" = disabled. */
+ cacheRetention?: "none" | "short" | "long";
+ /** Web-search sidecar: route web_search for non-OpenAI models through a gpt-mini via ChatGPT passthrough. */
+ webSearchSidecar?: OcxWebSearchSidecarConfig;
+ /** Vision sidecar: describe images via a gpt vision model so text-only models can "see" them. */
+ visionSidecar?: OcxVisionSidecarConfig;
+ /** /v1/images relay for codex's built-in image_gen tool. */
+ images?: OcxImagesConfig;
+ /** /v1/alpha/search relay for codex's built-in web search client. */
+ search?: OcxSearchConfig;
+ /** Codex multi-account pool. */
+ codexAccounts?: CodexAccount[];
+ /** Account ids administratively excluded from future pool selection until resumed. */
+ pausedCodexAccountIds?: string[];
+ /**
+ * Selection order per account id, higher used earlier; absent = 0. Keyed by id
+ * rather than stored on `codexAccounts` rows so the Desktop login (`__main__`),
+ * which has no row, can be ordered too. Range -100..100.
+ */
+ codexAccountPriorities?: Record;
+ /**
+ * Account id the operator last selected by hand. Suppresses upward priority
+ * preemption until that account crosses the auto-switch threshold. Stores the
+ * id (not a flag) so a stale pin cannot outlive the selection it described.
+ */
+ activeCodexAccountPinned?: string;
+ /**
+ * Public model-selector namespaces bound to one Codex account. Values are stored account ids;
+ * `"@main"` selects the Codex Desktop/main auth.json account. Account display aliases
+ * are intentionally separate from these selectors.
+ */
+ codexAccountNamespaces?: Record;
+ /**
+ * Picker visibility override for account-qualified native models. When omitted, a non-empty
+ * selector map remains visible for compatibility with hand-written configurations.
+ */
+ codexAccountPickerEnabled?: boolean;
+ /** Active pool account id for next session. undefined = main (passthrough as-is). */
+ activeCodexAccountId?: string;
+ /** Auto-switch threshold (0-100). Default 80. 0 = disabled. */
+ autoSwitchThreshold?: number;
+ /** New-session account rotation strategy for the Codex pool. Default quota (today's behaviour). */
+ accountPoolStrategy?: OcxAccountPoolRotationStrategy;
+ /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
+ accountPoolStickyLimit?: number;
+ /** Consecutive non-2xx upstream responses before switching future new threads. Default 3. 0 = disabled. */
+ upstreamFailoverThreshold?: number;
+ /**
+ * Opt-in provider-origin circuit threshold for proven pre-connection reachability failures.
+ * Default 0 (disabled); range 0..20. The circuit never counts timeouts or HTTP responses.
+ */
+ upstreamHostCircuitThreshold?: number;
+ /**
+ * Opt-in Anthropic OAuth account pool (#294). Default OFF.
+ * Failover on 429 + sticky affinity; new sessions may pick lowest known 5h usage.
+ * Experimental — see docs and GUI warning before enabling.
+ */
+ anthropicAccountPool?: {
+ enabled?: boolean;
+ /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
+ autoSwitchThreshold?: number;
+ /** New-session rotation strategy. Default quota (today's behaviour). */
+ strategy?: OcxAccountPoolRotationStrategy;
+ /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
+ stickyLimit?: number;
+ };
+ /** Virtual `combo/` models spanning concrete provider/model targets (issue #133). */
+ combos?: Record;
+ /**
+ * Routing policy profiles (Router Intelligence, RI-04+): explicitly requested
+ * `policy/` (or configured alias) models select among an explicit
+ * candidate allowlist using hard capability requirements and deterministic
+ * scoring. Existing model ids are never routed through profiles implicitly.
+ */
+ routingProfiles?: Record;
+ /** Background proactive token refresh ("Token Guardian"). Off by default; see OcxTokenGuardianConfig. */
+ tokenGuardian?: OcxTokenGuardianConfig;
+ /** Additional exact origins allowed for CORS (e.g. HTTPS or chrome-extension://). Loopback origins are always allowed. */
+ corsAllowOrigins?: string[];
+}
+
+export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
+
+export type OcxComboStrategy = "failover" | "round-robin";
+export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+
+export interface OcxComboTarget {
+ provider: string;
+ model: string;
+ /** Relative SWRR batch weight. Default 1; valid range 1..10000. */
+ weight?: number;
+}
+
+export interface OcxComboConfig {
+ targets: OcxComboTarget[];
+ /** Ordered failover (default) or deterministic smooth weighted round-robin. */
+ strategy?: OcxComboStrategy;
+ /** Successful requests retained on one RR selection batch. Default 1; range 1..100. */
+ stickyLimit?: number;
+ /** Used when the client omits reasoning.effort. null/omitted leaves the target default unchanged. */
+ defaultEffort?: OcxComboDefaultEffort | null;
+ /**
+ * Disable image input even when every target supports it.
+ * Omitted / `"auto"` keeps automatic capability derivation (default: enabled when
+ * the target intersection includes image).
+ */
+ imageInput?: "auto" | "disabled";
+ /**
+ * Optional public model name replacing the default `combo/` slug. Bare names
+ * without "/" are allowed (e.g. "deepseek-v4-flash") so the combo can answer to a
+ * mandated model id; exact-match requests route here before any provider resolution.
+ */
+ alias?: string;
+ /**
+ * Explicitly allow a bare OpenAI-native alias (for example `gpt-5.6-sol`) to
+ * be represented by this routed combo. Never inferred from `alias`.
+ */
+ nativeAlias?: boolean;
+ /** Display-only label for the public catalog row. Required for native aliases. */
+ displayName?: string;
+}
+
+export type OcxRoutingUnknownEvidenceMode = "allow" | "penalize" | "exclude";
+
+export interface OcxRoutingProfileCandidate {
+ provider: string;
+ model: string;
+}
+
+export interface OcxRoutingProfileRequirements {
+ /** Minimum model context window in tokens. */
+ minContextWindow?: number;
+ /** Minimum remaining quota headroom fraction (0..1). */
+ minQuotaHeadroom?: number;
+ tools?: boolean;
+ imageInput?: boolean;
+ structuredOutput?: boolean;
+ reasoningEffort?: string;
+ serviceTier?: string;
+ localOnly?: boolean;
+ remoteAllowed?: boolean;
+ /** Special encrypted Codex task readability (ChatGPT forward pool). */
+ encryptedCodexTasks?: boolean;
+}
+
+export interface OcxRoutingProfileOptimize {
+ latency?: number;
+ health?: number;
+ cost?: number;
+ quota?: number;
+}
+
+/**
+ * Policy for the hard cost ceiling when a candidate has no finite cost
+ * estimate. `"allow"` (default) preserves the documented dry-run contract:
+ * the cap only excludes evidence known to exceed it, and the candidate's
+ * `cost.capOutcome` is `"unknown-allowed"`. `"exclude"` makes the ceiling
+ * fail-closed (`cost-limit-unknown` + `capOutcome: "unknown-excluded"`).
+ */
+export type OcxRoutingUnknownCostCapMode = "allow" | "exclude";
+
+export interface OcxRoutingProfileLimits {
+ /** Hard per-request estimated-cost ceiling in USD. */
+ maxEstimatedCostUsd?: number;
+ /**
+ * How `maxEstimatedCostUsd` behaves when the estimate is unknown.
+ * Defaults to `"allow"` (eligible + `cost.capOutcome: "unknown-allowed"`);
+ * opt in to `"exclude"` for a true hard ceiling.
+ */
+ onUnknownCost?: OcxRoutingUnknownCostCapMode;
+}
+
+export interface OcxRoutingProfileUnknownEvidence {
+ capability?: OcxRoutingUnknownEvidenceMode;
+ health?: OcxRoutingUnknownEvidenceMode;
+ quota?: OcxRoutingUnknownEvidenceMode;
+ cost?: OcxRoutingUnknownEvidenceMode;
+}
+
+export interface OcxRoutingProfileCompatibilitySuite {
+ suiteId: string;
+ evidenceLayer: "protocol_conformance" | "live_route_compatibility";
+}
+
+export interface OcxRoutingProfileCompatibility {
+ requiredSuites?: OcxRoutingProfileCompatibilitySuite[];
+ minStatus?: "PROBED" | "VERIFIED";
+ maxEvidenceAgeMs?: number;
+ unknownEvidence?: OcxRoutingUnknownEvidenceMode;
+ degradedEvidence?: OcxRoutingUnknownEvidenceMode;
+}
+
+export interface OcxRoutingProfileConfig {
+ /**
+ * Explicit candidate allowlist (`provider/model` refs). No implicit
+ * expansion in v1.
+ */
+ candidates: OcxRoutingProfileCandidate[];
+ /** Optional public model name replacing the default `policy/` slug. */
+ alias?: string;
+ /** Hard requirements evaluated before scoring. */
+ require?: OcxRoutingProfileRequirements;
+ /** Optimization weights; normalized deterministically. */
+ optimize?: OcxRoutingProfileOptimize;
+ limits?: OcxRoutingProfileLimits;
+ /** How unknown evidence is handled per dimension. */
+ unknownEvidence?: OcxRoutingProfileUnknownEvidence;
+ /** Optional Compatibility Lab policy (CL-06). */
+ compatibility?: OcxRoutingProfileCompatibility;
+}
+
+
+export interface OcxTokenGuardianConfig {
+ /** Global kill-switch. Default false — the guardian does nothing unless explicitly enabled. */
+ enabled?: boolean;
+ /** Seconds between refresh sweeps. Default 21600 (6h). Min 60. */
+ tickSeconds?: number;
+ /** Random 0..jitterSeconds added before each sweep to de-synchronize. Default 300. */
+ jitterSeconds?: number;
+ /** Max concurrent refreshes per sweep. Default 3. Min 1. */
+ concurrency?: number;
+ /** Extra lead (seconds) beyond one tick when deciding a token is "expiring soon". Default 900. */
+ leadSeconds?: number;
+ /** First backoff (seconds) after a permanent refresh failure. Default 300. */
+ failureBackoffBaseSeconds?: number;
+ /** Backoff ceiling (seconds). Default 3600. */
+ failureBackoffMaxSeconds?: number;
+ /** Optional Codex pool session warmup sweep. Default false to avoid background synthetic traffic. */
+ codexWarmupEnabled?: boolean;
+ /** Max age before a Codex pool account is revalidated via `/codex/responses`. Default 691200 (8d). */
+ codexWarmupMaxAgeSeconds?: number;
+ /** Model used for optional Codex pool warmup. Default gpt-5.4-mini. */
+ codexWarmupModel?: string;
+}
+
+export interface OcxImagesConfig {
+ /** Optional custom API-key provider for /v1/images relays. Built-in OpenAI tiers remain automatic. */
+ provider?: string;
+ /** Upstream timeout (ms) for one image generation/edit call (bridge xAI + /v1/images relay). Default 60000 for the bridge; relay may use a higher default (300000). */
+ timeoutMs?: number;
+ /** Master switch for the image bridge. Default false — set true to enable paid xAI Grok Imagine generation. */
+ bridgeEnabled?: boolean;
+ /** xAI image model id. Default "grok-imagine-image-quality" (see DEFAULT_MODEL in images/plan.ts). */
+ bridgeModel?: string;
+ /** Max image-generation loop iterations before forced-final. Default 3; clamped to [0, 10]. */
+ maxRounds?: number;
+ /** Max files retained under artifacts/. Oldest deleted when exceeded. Default 200. */
+ artifactsKeepCount?: number;
+ /** Master switch for the video bridge. Default false — must be explicitly opted in. */
+ videoBridgeEnabled?: boolean;
+ /** Model for xAI video generation. Default "grok-imagine-video". */
+ videoBridgeModel?: string;
+ /** Max video-gen rounds before forced-final. Default 2 (video is slower than image). */
+ videoMaxRounds?: number;
+ /** Per-video generation timeout (ms) including polling. Default 300000 (5 min). */
+ videoTimeoutMs?: number;
+}
+
+export interface OcxSearchConfig {
+ /**
+ * Total upstream deadline (ms) for one /v1/alpha/search relay. Default 200000. The endpoint
+ * is non-streaming JSON (headers arrive only when the search completes), so this is a whole-
+ * request budget — deliberately NOT connectTimeoutMs, which is a header-arrival budget.
+ */
+ timeoutMs?: number;
+}
+
+export interface OcxVisionSidecarConfig {
+ /** Master switch. Default: enabled when the selected backend has a usable credential. */
+ enabled?: boolean;
+ /** Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI. */
+ backend?: "openai" | "anthropic";
+ /** Vision model that describes images. */
+ model?: string;
+ /** Max description cache misses admitted in one main-model turn. Zero disables description calls. */
+ maxDescriptionsPerTurn?: number;
+ /** Sidecar fetch timeout (ms). */
+ timeoutMs?: number;
+}
+
+export interface OcxWebSearchSidecarConfig {
+ /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
+ enabled?: boolean;
+ /**
+ * Which backend actually runs the server-side search. "openai" replays the hosted web_search via
+ * the ChatGPT forward provider (gpt-mini sidecar); "anthropic" runs web_search_20250305 on a Claude
+ * model authenticated by the STORED anthropic OAuth credential. Unset resolves to "anthropic" when a
+ * usable anthropic OAuth credential exists, else "openai".
+ */
+ backend?: "openai" | "anthropic";
+ /** Sidecar model that runs the real server-side web_search (must be a native ChatGPT model). */
+ model?: string;
+ /** Reasoning effort for the sidecar — "minimal" (non-thinking) keeps it fast/cheap. */
+ reasoning?: string;
+ /** Max searches executed per main-model turn (loop guard). */
+ maxSearchesPerTurn?: number;
+ /** Sidecar fetch timeout (ms). */
+ timeoutMs?: number;
+ /**
+ * Config-file-only deadline (ms) for continuous routed-model response-body raw-byte inactivity
+ * during a web-search turn. Default 200000. Must be an integer from 1 through 2147483647.
+ */
+ routedModelStallTimeoutMs?: number;
+ /**
+ * Stream the routed model's leading output (text/thinking deltas) live instead of buffering the
+ * whole iteration. Live delivery stops at the first tool-call boundary so web_search interception
+ * stays atomic. Tradeoff: text the model emits BEFORE deciding to search — which buffered mode
+ * silently drops — becomes visible to the client and may partially repeat in the post-search
+ * answer. Default: false (buffered, previous behavior).
+ */
+ streamRoutedModelOutput?: boolean;
+}
diff --git a/src/types/provider.ts b/src/types/provider.ts
new file mode 100644
index 0000000000..72fbc10033
--- /dev/null
+++ b/src/types/provider.ts
@@ -0,0 +1,521 @@
+import type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./wire";
+
+/**
+ * Per-provider proactive-refresh policy. The guardian only ever touches a provider whose EFFECTIVE
+ * policy is "proactive"; "lazy-only" keeps today's on-demand refresh, "disabled" forbids the
+ * guardian entirely (used for providers whose ToS actively enforces against non-official-client
+ * token traffic, e.g. Anthropic subscription OAuth). See devlog 260703_oauth-multi-account-refresh-and-tos.
+ */
+export type RefreshPolicy = "proactive" | "lazy-only" | "disabled";
+
+export interface OpenRouterProviderRouting {
+ /** OpenRouter provider slugs to try first, in priority order. */
+ order?: string[];
+ /** Restrict routing to these OpenRouter provider slugs. */
+ only?: string[];
+ /** Whether OpenRouter may use providers outside `order`. Defaults to OpenRouter's policy. */
+ allowFallbacks?: boolean;
+}
+
+export interface ResponsesItemIdRepairConfig {
+ /** Exact `message` item ids that the proxy should rewrite to request-local canonical ids. */
+ message?: string[];
+ /** Exact `reasoning` item ids that the proxy should rewrite to request-local canonical ids. */
+ reasoning?: string[];
+ /** Backfill missing `output_item.done` / terminal snapshot ids from the matching output_index. */
+ repairMissingTerminalIds?: boolean;
+ /**
+ * Treat existing message/reasoning ids without the canonical `msg_`/`rs_` prefix (e.g. bare
+ * UUIDs from DeepSeek's Responses route) as invalid and mint canonical replacements (#938).
+ * function_call ids and call_id pairing are never rewritten.
+ */
+ repairInvalidIds?: boolean;
+}
+
+/**
+ * Same-target 429 wait-and-retry policy (`providers..retryOn429`). When present and not
+ * explicitly disabled, the proxy waits and replays the identical request on the same key before
+ * any key failover. All fields optional; the runtime applies defaults (attempts=3,
+ * intervalMs=5000, maxIntervalMs=60000, respectRetryAfter=true, enabled=true).
+ */
+export interface RateLimitRetryPolicy {
+ /** Master switch. The presence of the object also enables the policy (default true). */
+ enabled?: boolean;
+ /** Extra replay attempts after the first 429 (1..20, default 3). */
+ attempts?: number;
+ /** Fixed wait between attempts when the upstream sends no usable Retry-After (default 5000). */
+ intervalMs?: number;
+ /** Cap for any single wait, including an upstream Retry-After (default 60000). */
+ maxIntervalMs?: number;
+ /** Prefer the upstream Retry-After header when present and parseable (default true). */
+ respectRetryAfter?: boolean;
+}
+
+/**
+ * User-configured display price for one model (USD per 1M tokens).
+ * Mirrors the `Cost4` shape used by the usage cost estimator; structurally
+ * compatible so config rows can be lifted directly into price overlays.
+ */
+export interface ProviderCostOverlay {
+ input: number;
+ output: number;
+ cacheRead: number;
+ cacheWrite: number;
+}
+
+export interface RequestPacingRule {
+ /** Evenly spread request starts to this many requests per minute. */
+ requestsPerMinute?: number;
+ /** Minimum delay between request starts. The slower configured value wins. */
+ minIntervalMs?: number;
+}
+
+export interface ProviderRequestPacingConfig extends RequestPacingRule {
+ /** False preserves legacy behavior with no client-side waiting. */
+ enabled: boolean;
+ /** Exact upstream model-id overrides; other models inherit the provider rule. */
+ models?: Record;
+}
+
+export interface FastWire {
+ kind: "service-tier" | "anthropic-speed";
+ /** Canonical tier name to upstream wire spelling. */
+ canonicalToWire: Readonly>;
+ /** Policy for non-canonical caller-provided tier values. */
+ foreignCallerTiers: "verbatim" | "drop";
+ /** Anthropic speed headers/betas reserved for the later wire implementation. */
+ betas?: readonly string[];
+}
+
+/** Durable per-attempt service-tier fact produced at the adapter serialization boundary. */
+export interface AttemptTierOutcome {
+ canonical?: "priority";
+ wireKind?: FastWire["kind"] | null;
+ wireValue?: string | null;
+ fastOutcome: "not-requested" | "applied" | "downgraded" | "unknown";
+ fastDowngradeReason?: "route-unsupported" | "wire-unavailable" | "response-declined";
+ callerTierDropped?: boolean;
+ callerFastSuppressedByConfig?: boolean;
+ confirmation: "confirmed" | "assumed" | "downgraded" | "unknown";
+ responseServiceTier?: string;
+}
+
+/**
+ * Request-local observation inputs captured before the final tier action mutates the parsed view.
+ * This is not persisted; the final adapter turns it into AttemptTierOutcome after serialization.
+ */
+export interface TierObservationContext {
+ capability: boolean | undefined;
+ eligibility:
+ | "eligible"
+ | "capability-unsupported"
+ | "unclassified"
+ | "wire-unavailable"
+ | "pin-unavailable";
+ fastWire: FastWire | null;
+ demandDecision: "force-fast" | "force-default" | "inherit";
+ callerTier?: string;
+}
+
+export type TierDecision =
+ | { readonly kind: "forward-caller" }
+ | { readonly kind: "drop" }
+ | { readonly kind: "set"; readonly value: string };
+
+/**
+ * One configured provider entry. `authMode` (default `"key"`) decides whether same-target 429
+ * retries are allowed; OAuth/forward credentials and local runtimes are never replayed.
+ */
+export interface OcxProviderConfig {
+ adapter: string;
+ /**
+ * Codex tool calling mode for routed models.
+ * "code_mode_only" (default) sets entry.tool_mode = "code_mode_only" (unified exec helper tool).
+ * "shell" leaves tool_mode unset so Codex declares top-level shell tools (exec_command).
+ */
+ codexToolMode?: "code_mode_only" | "shell";
+ /** Optional outbound request-start pacing shared by this provider and its model overrides. */
+ requestPacing?: ProviderRequestPacingConfig;
+ /** Cursor MCP compatibility bounds; positive integers when configured. */
+ mcpMaxTools?: number;
+ mcpMaxSchemaBytes?: number;
+ mcpMaxResultBytes?: number;
+ /**
+ * Per-model wire override, keyed by the upstream native model id (after namespace
+ * and combo resolution). A single gateway can front models that speak different
+ * wires — Grok needs the Responses API for hosted web_search while a sibling model
+ * is fine on chat completions (#404).
+ *
+ * Only OpenAI-shaped wires may be selected; see MODEL_ADAPTER_OVERRIDE_ALLOWED.
+ * Absent or empty means the provider-wide `adapter` applies to everything, exactly
+ * as before.
+ */
+ modelAdapters?: Record;
+ /**
+ * Fast-wire declaration. `null` explicitly disables adapter-derived defaults;
+ * absence derives from the final model adapter.
+ */
+ fastWire?: FastWire | null;
+ baseUrl: string;
+ /**
+ * Optional relative resource path for key-auth openai-responses requests. Must start with `/`
+ * and must not include a URL scheme, query string, or fragment. When omitted, the adapter keeps
+ * the legacy `/v1/responses` construction.
+ */
+ responsesPath?: string;
+ /**
+ * Command Code protocol version sent as `x-command-code-version` on /alpha/generate requests.
+ * The internal endpoint's schema drifts with the CLI version; operators can pin a known-good
+ * version here instead of waiting for a code change. Absent uses the adapter's current default.
+ */
+ commandCodeVersion?: string;
+ /**
+ * Responses upstream that stores nothing server-side (DeepSeek documents "the API
+ * is stateless"). Stateful request parameters are dropped, `store` is pinned false,
+ * and orphaned tool results left by a replay miss are repaired rather than
+ * forwarded to an upstream that cannot resolve their pair.
+ */
+ statelessResponses?: boolean;
+ /**
+ * Responses upstream whose parser requires an unambiguous call batch and its matched
+ * result batch to remain contiguous. Hook-injected context that splits the batch is
+ * preserved after it, and parallel calls stay together with the reasoning turn that produced them.
+ */
+ requiresAdjacentResponsesToolResults?: boolean;
+ /**
+ * Provider fallback for canonical Fast capability over an OpenAI `service_tier` wire.
+ * This pure tri-state feeds catalog publication, routing eligibility, compatibility
+ * fingerprints, and proxy-owned canonical Fast injection on both Responses and Chat routes.
+ * Tri-state: `true` lets fast mode inject/remove the canonical field; `false` strips it and
+ * never injects, because an upstream documented as not supporting the parameter
+ * must not receive it; absent (`undefined`) leaves the provider unclassified — fast mode never
+ * injects or translates, and caller values pass only under the final wire's forwarding permission.
+ * On Chat, that CallerTierForward permission is `chatServiceTier`; Responses retains passthrough.
+ * An explicit config value always wins over the registry default.
+ */
+ supportsServiceTier?: boolean;
+ /** Exact upstream model ids that override the provider-level service-tier capability. */
+ modelSupportsServiceTier?: Record;
+ /**
+ * Responses upstream whose native contract accepts plaintext reasoning replay
+ * (DeepSeek documents reasoning items with plaintext content). When set, the
+ * passthrough serializer keeps `reasoning_text` content on replayed reasoning
+ * items instead of blanking it the way the ChatGPT backend requires; proxy-minted
+ * `ocxr1` envelopes are still stripped because no upstream can decrypt them.
+ */
+ preserveResponsesReasoningContent?: boolean;
+ /**
+ * Explicit opt-in for non-registry private-network destinations such as localhost, RFC1918,
+ * link-local, or unique-local upstreams. Metadata endpoints remain blocked.
+ */
+ allowPrivateNetwork?: boolean;
+ /**
+ * Pin the HTTP version used for upstream provider requests. Bun's fetch negotiates
+ * HTTP/2 via TLS ALPN by default; some Cloudflare-fronted SSE endpoints hang on
+ * HTTP/2 streaming responses (issue #1668). "http1.1" / "h1" forces HTTP/1.1,
+ * "http2" / "h2" forces HTTP/2. Absent or "auto" keeps Bun's default negotiation
+ * (current behavior unchanged). Only meaningful for https: base URLs.
+ */
+ upstreamHttpVersion?: UpstreamHttpVersion;
+ /**
+ * Google only. When `false`, the AI Studio (direct) path sends Gemini Flash ids
+ * unchanged to the wire instead of applying the `-tiered` suffix (`gemini-3.7-flash`
+ * -> `gemini-3.7-flash-tiered`). Set this to `false` when the configured upstream still
+ * serves the bare ids. Absent (default) keeps the rename.
+ */
+ directGeminiWireRenames?: boolean;
+ /** Keep provider settings on disk but exclude it from routing and model/catalog listings. */
+ disabled?: boolean;
+ /**
+ * Codex account-selection mode. Valid ONLY on the canonical built-in `openai` forward provider.
+ * "pool" (default) rotates main + added Codex accounts through the affinity/quota/cooldown/
+ * failover engine; "direct" pins the caller's main Codex login and never touches pool state.
+ */
+ codexAccountMode?: CodexAccountMode;
+ apiKey?: string;
+ /**
+ * Key-auth header style for Anthropic-compatible providers.
+ * Defaults to the native Anthropic `x-api-key`; gateways may require
+ * `Authorization: Bearer ` instead.
+ */
+ apiKeyTransport?: "x-api-key" | "bearer";
+ /**
+ * Multi-key pool (API-key twin of OAuth multiauth). `apiKey` always mirrors the ACTIVE
+ * entry so routing stays single-key; managed via /api/providers/keys. A legacy bare
+ * `apiKey` seeds a one-entry pool on first management touch.
+ */
+ apiKeyPool?: Array<{ id: string; key: string; label?: string; addedAt?: number }>;
+ defaultModel?: string;
+ models?: string[];
+ /**
+ * Fetch the provider's live `/models` endpoint. Defaults to true.
+ * Set false when `models` is an intentional allowlist or a provider's live catalog is too large
+ * or too flaky for startup/catalog sync.
+ */
+ liveModels?: boolean;
+ /**
+ * Per-provider catalog allowlist. When non-empty, ONLY these model ids are emitted to Codex's
+ * catalog and `/v1/models` — live discovery still runs, this just narrows what ships (so a proxy
+ * exposing thousands of models, or an aggregator like OpenRouter, doesn't bloat the catalog).
+ * Empty/undefined = expose all. The admin `/api/models` list is unaffected (it always shows the
+ * full set so the user can pick). See devlog issue_052_provider-model-allowlist.
+ */
+ selectedModels?: string[];
+ /** Provider-wide fallback when context metadata is absent; otherwise caps the reported window. */
+ contextWindow?: number;
+ /** Per-model fallback when context metadata is absent; otherwise caps the reported window. */
+ modelContextWindows?: Record;
+ /** Model-specific Codex catalog input modalities, e.g. ["text"] or ["text", "image"]. */
+ modelInputModalities?: Record;
+ /** Model-specific max input token limits. Values cap auto_compact_token_limit. */
+ modelMaxInputTokens?: Record;
+ /**
+ * Provider-wide fallback for chat-completions `max_tokens` when the caller omits
+ * Responses `max_output_tokens`. Adapters still let an explicit request win.
+ */
+ defaultMaxOutputTokens?: number;
+ /** Model-specific fallback output token budgets. Exact/model-pattern entries beat the provider default. */
+ modelMaxOutputTokens?: Record;
+ /**
+ * Per-model display prices (USD per 1M tokens) keyed by exact model id —
+ * opencode-style per-model pricing in ocx's flat `modelXxx` convention:
+ * `{ "deepseek-v4-flash": { "input": 0.14, "output": 0.28, "cacheRead": 0.0028, "cacheWrite": 0 } }`.
+ * User-configured prices win over the built-in jawcode/expected catalogs in
+ * the Logs `~$` estimate. Display-time estimation only; never billing. An
+ * all-zero entry means "not billable here" and falls through to the catalogs.
+ */
+ modelCosts?: Record;
+ headers?: Record;
+ /** Default provider-routing preferences for models sent through the canonical OpenRouter API. */
+ openRouterRouting?: OpenRouterProviderRouting;
+ /** Exact model-id overrides for `openRouterRouting`. Each matching entry replaces the default. */
+ modelOpenRouterRouting?: Record;
+ /**
+ * "key" (default): authenticate upstream with `apiKey`.
+ * "forward": relay the caller's incoming auth headers verbatim (OAuth passthrough; gpt only).
+ * "oauth": resolve a stored OAuth access token (auto-refreshed) and use it as the Bearer key.
+ * Only the openai-responses adapter implements "forward"; openai-chat uses its own key/token.
+ * "local": local runtime (Ollama etc.) — no remote key required. Valid only for
+ * providers whose registry entry declares authKind "local" (management API enforces).
+ */
+ authMode?: "key" | "forward" | "oauth" | "local";
+ /** Allow an explicitly key/oauth provider to run without a credential (for keyless local proxies). */
+ keyOptional?: boolean;
+ /**
+ * Free-tier pricing flag for UI/catalog (Free badge, Free filter). Not the same as
+ * `keyOptional` — free tiers may still require an API key (e.g. NVIDIA NIM free credits).
+ */
+ freeTier?: boolean;
+ /** Optional human note shown in the providers UI (not used for routing). */
+ note?: string;
+ /** Strip one trailing bracketed suffix from model ids before sending them upstream. */
+ modelSuffixBracketStrip?: boolean;
+ /**
+ * Override the guardian's proactive-refresh policy for this provider. When unset, the provider's
+ * built-in risk-tiered default applies (see OAUTH_PROVIDERS in src/oauth/index.ts). Set "proactive"
+ * to opt this provider into background refresh; "disabled"/"lazy-only" to forbid/limit it.
+ */
+ refreshPolicy?: RefreshPolicy;
+ /**
+ * Provider-wide Codex-visible reasoning tiers for routed models. Use only Codex-supported labels
+ * here (`low`, `medium`, `high`, `xhigh`, `max`); translate provider aliases with
+ * `reasoningEffortMap` / `modelReasoningEffortMap` below.
+ */
+ reasoningEfforts?: string[];
+ /** Model-specific Codex-visible reasoning tiers. An empty array means “do not expose effort”. */
+ modelReasoningEfforts?: Record;
+ /** Model-specific default Codex reasoning tier; must also be present in the visible tier list. */
+ modelDefaultReasoningEfforts?: Record;
+ /**
+ * Model-specific Codex reasoning-summary capability. Set false when an OpenAI-compatible
+ * Responses backend rejects Codex summary-delivery fields for that model.
+ */
+ modelSupportsReasoningSummaries?: Record;
+ /**
+ * Per-model wire value for Responses `stream_options.reasoning_summary_delivery`.
+ * Presence also advertises reasoning-summary support for that routed model.
+ */
+ modelReasoningSummaryDelivery?: Record;
+ /**
+ * Exact-model hosted tools that win collisions with Codex client tool declarations.
+ * Use for non-forward Responses gateways that reserve a hosted tool namespace server-side.
+ */
+ modelPreferHostedTools?: Record;
+ /**
+ * Provider-local repair for Responses gateways whose lifecycle snapshots omit canonical
+ * fields or closing events (#893). Disabled by default and applied only to client-facing
+ * SSE/JSON; raw inspection state remains authoritative.
+ */
+ responsesSnapshotRepair?: boolean;
+ /** Provider-wide mapping from Codex effort labels to upstream `reasoning_effort` values. */
+ reasoningEffortMap?: Record;
+ /** Model-specific mapping from Codex effort labels to upstream `reasoning_effort` values. */
+ modelReasoningEffortMap?: Record>;
+ /** OpenAI-compatible gateway reasoning wire shape. Default sends `reasoning_effort`. */
+ reasoningWireFormat?: "gateway-object";
+ /**
+ * Model ids that do NOT support a reasoning/thinking parameter. The openai-chat adapter drops
+ * reasoning_effort for these even when Codex selects a reasoning level (e.g. xAI grok-build-0.1).
+ */
+ noReasoningModels?: string[];
+ /** Model ids that reject caller-specified temperature. */
+ noTemperatureModels?: string[];
+ /** Model ids that reject caller-specified top_p. */
+ noTopPModels?: string[];
+ /** Model ids that reject caller-specified presence/frequency penalty values. */
+ noPenaltyModels?: string[];
+ /**
+ * Model ids whose Chat Completions endpoint rejects `response_format`.
+ * Structured-output translation remains enabled by default; this is a narrow
+ * per-model compatibility escape hatch for mixed-capability gateways.
+ */
+ noStructuredOutputModels?: string[];
+ /**
+ * Allow multiple tool calls per completion. DEFAULT-ON for openai-chat providers (the
+ * buffered stream parser assembles interleaved/fragmented multi-call turns safely);
+ * set `false` to force `parallel_tool_calls:false` upstream and drop the catalog's
+ * `supports_parallel_tool_calls` bit for that provider. Non-chat adapters advertise
+ * only on explicit `true`. See devlog/_plan/260709_parallel_tool_calls.
+ */
+ parallelToolCalls?: boolean;
+ /**
+ * Opt-in: when `parallelToolCalls` is `false`, actually send `parallel_tool_calls: false`
+ * on the `/chat/completions` wire for this provider. By default an opted-out provider only
+ * OMITS the field (strict OpenAI-compatible hosts reject unknown knobs), and the NVIDIA NIM
+ * baseUrl is the sole built-in exception that pins the wire bit. Some self-hosted gateways
+ * (Kimi/GLM-family, vLLM, etc.) do honor `parallel_tool_calls` and keep emitting concurrent
+ * tool calls unless it is present; enable this to pin the bit without hardcoding their URL.
+ * No effect unless `parallelToolCalls === false`; ignored by non-`openai-chat` adapters.
+ */
+ pinParallelToolCallsFalse?: boolean;
+ /**
+ * Opt-in: extend the no-tool-call terminal continuation guard to this provider's
+ * `openai-chat` routed turns. The guard (originally Anthropic-only, see
+ * devlog/_fin/260706_previous-response-id-400) issues one bounded internal re-ask when a
+ * model announces work but ends the turn without emitting a tool call. Self-hosted
+ * OpenAI-compatible gateways (GLM/Kimi-family, etc.) hit the same premature-completion
+ * pattern, but the heuristic that decides a "suspicious no-tool stop" was tuned on
+ * Anthropic turns, so it stays OFF by default for the many registry providers that share
+ * the `openai-chat` adapter. Enable only for a provider whose models are known to stop
+ * mid-work; non-`openai-chat` adapters ignore this flag.
+ */
+ terminalContinuationGuard?: boolean;
+ /**
+ * Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
+ * OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown
+ * fields. Default off; only enable for providers that document this parameter.
+ */
+ promptCacheKey?: boolean;
+ /**
+ * Opt-in: forward caller `service_tier` values to the upstream `/chat/completions` body.
+ * On a classified route it governs foreign values (for example `flex`), not proxy-owned
+ * canonical Fast after capability validation. On an unclassified route it governs every caller
+ * value, including canonical spellings, because no Fast capability has been validated.
+ * OpenAI-specific extension with the same hazard as `promptCacheKey` — strict backends
+ * reject unknown fields, and 66 registry providers share the `openai-chat` adapter, so a
+ * caller-supplied `service_tier` would otherwise turn working requests into upstream 400s.
+ * Exact-model `true` enables canonical Fast capability but does not grant foreign-tier
+ * forwarding; provider-level `supportsServiceTier: false` remains a global denial. Default off;
+ * only enable for providers that document this parameter on the chat wire.
+ */
+ chatServiceTier?: boolean;
+ /**
+ * Provider-local passthrough SSE repair for broken openai-responses gateways that reuse exact
+ * placeholder message/reasoning ids or omit the terminal id after a stable added event.
+ * Disabled by default; function_call ids and call_id pairing are never rewritten.
+ */
+ responsesItemIdRepair?: ResponsesItemIdRepairConfig;
+ /** Model ids whose tool_choice only accepts `auto` or `none`; forced/named choices are downgraded. */
+ autoToolChoiceOnlyModels?: string[];
+ /** Model ids that expect prior assistant `reasoning_content` to be preserved in chat history. */
+ preserveReasoningContentModels?: string[];
+ /**
+ * Model ids whose upstream hard-rejects a tool_call continuation missing
+ * `reasoning_content` (DeepSeek thinking mode: HTTP 400). When the replay
+ * cache misses, the adapter injects a minimal placeholder for these models.
+ * Defaults to `preserveReasoningContentModels` when unset; set `[]` to opt
+ * out explicitly (e.g. MiniMax, where low effort disables thinking).
+ */
+ requiresReasoningPlaceholderModels?: string[];
+ /**
+ * Opt-in same-target 429 retry policy. Codex itself never retries 429 (it retries 5xx only,
+ * openai/codex#30471), and single-key pools have no failover, so the proxy waits and replays
+ * the identical request on the same key before any failover. Pre-stream only: a 429 arrives
+ * before any response bytes are relayed, so the replay is lossless.
+ */
+ retryOn429?: RateLimitRetryPolicy;
+ /**
+ * Model ids whose OpenAI-compatible chat endpoint accepts `reasoning_split: true` and returns
+ * thinking separately in `reasoning_content` / `reasoning_details` instead of visible content.
+ */
+ reasoningSplitModels?: string[];
+ /**
+ * Model ids whose reasoning is a vendor `thinking: {type}` toggle on the
+ * chat-completions wire (MiMo v2.x, GLM 5/5.1 style), NOT an OpenAI `reasoning_effort` ladder.
+ * The openai-chat adapter translates the mapped effort into the thinking toggle for these.
+ */
+ thinkingToggleModels?: string[];
+ /**
+ * Model ids whose reasoning is a `thinking_budget` integer on the chat-completions wire
+ * (Qwen3.x style), NOT an OpenAI `reasoning_effort` ladder. The openai-chat adapter maps the
+ * Codex effort to a budget fraction.
+ */
+ thinkingBudgetModels?: string[];
+ /** Anthropic-compatible gateways that need custom tool names escaped on the wire. */
+ escapeBuiltinToolNames?: boolean;
+ /**
+ * Anthropic-compatible gateways (e.g. AgentRouter) that may close the stream before
+ * `message_stop`. With this enabled the adapter completes an otherwise-clean EOF only when
+ * visible text was received or an open tool call has complete JSON-object arguments; all
+ * other EOFs remain truncation errors. Absent = strict default behavior.
+ */
+ anthropicEofTolerance?: boolean;
+ /**
+ * Model ids that do NOT accept image inputs. The proxy gives them "eyes" via the vision sidecar:
+ * attached images are described by a gpt vision model and replaced with text before the call.
+ */
+ noVisionModels?: string[];
+ /**
+ * Google adapter mode. "ai-studio" (default) = Generative Language API + x-goog-api-key.
+ * "vertex" = Vertex AI project/location endpoints with GCP ADC (or x-goog-api-key).
+ * "cloud-code-assist" = Google Antigravity (Cloud Code Assist) OAuth + CCA envelope.
+ */
+ googleMode?: "ai-studio" | "vertex" | "cloud-code-assist";
+ /** Vertex AI GCP project id (or GOOGLE_CLOUD_PROJECT / GCLOUD_PROJECT env). */
+ project?: string;
+ /** Vertex AI location, e.g. "us-central1" or "global" (or GOOGLE_CLOUD_LOCATION env). */
+ location?: string;
+ /**
+ * Cursor adapter only: MCP servers opencodex starts/connects and exposes to the Cursor agent
+ * as callable tools. Each entry is spawned (stdio `command`) or connected (`url`) lazily per
+ * stream; their tools are advertised to the Cursor server and executed against the live server.
+ */
+ mcpServers?: Record;
+ /**
+ * Cursor adapter only: opt-in external executor for computer-use / record-screen. opencodex is
+ * headless and cannot control a screen itself; provide commands here only when running on a host
+ * that can. With no executor, these tools honestly report "not supported".
+ */
+ desktopExecutor?: import("../adapters/cursor/native-exec-desktop").DesktopExecutorConfig;
+ /**
+ * Cursor adapter only: unsafe opt-in escape hatch for Cursor server-driven built-in local
+ * read/write/delete/ls/grep/shell/fetch execution. Prefer `nativeLocalExec: "on"` for new
+ * configs; this legacy boolean remains a server-local explicit opt-in for existing operators.
+ * Defaults to false so remote Cursor messages cannot bypass Codex approval/sandbox semantics.
+ * Explicit MCP and desktop executors remain controlled by their own opt-in config.
+ */
+ unsafeAllowNativeLocalExec?: boolean;
+ /**
+ * Cursor adapter only: native local exec policy mode (exec-policy.ts).
+ * "off" (default) rejects server-driven local exec; "on" always allows it for this
+ * provider and should be used only for a trusted local experiment on a host where every
+ * data-plane caller is trusted. "codex-sandbox" is accepted for backwards compatibility
+ * but is fail-closed like "off": Responses instructions/system/developer text is
+ * caller-controlled prose, and opencodex has no trustworthy per-request attestation that it
+ * reflects a real Codex sandbox state. The default loopback bind admits ANY local process
+ * without auth (including other local users on multi-user machines), and
+ * isAllowedRequestOrigin blocks non-loopback browser origins by default but not
+ * loopback-origin or origin-less callers.
+ */
+ nativeLocalExec?: "off" | "codex-sandbox" | "on";
+}
diff --git a/src/types/request.ts b/src/types/request.ts
new file mode 100644
index 0000000000..c01d6d3614
--- /dev/null
+++ b/src/types/request.ts
@@ -0,0 +1,358 @@
+import type { KiroOAuthMetadata } from "../oauth/types";
+import type { OcxTool, OcxToolChoice } from "./tools";
+import type { TierDecision, TierObservationContext } from "./provider";
+
+/** Exact provider/credential namespace for process-local reasoning replay. */
+export interface OcxReasoningReplayIdentity {
+ providerName: string;
+ /** Opaque process-local digest of the exact upstream destination. */
+ providerDestinationIdentity: string;
+ /**
+ * The same destination, digested WITHOUT the process-local random key, so it can key a
+ * durable store. Absent when no base URL was resolvable.
+ */
+ providerDestinationDurableIdentity?: string;
+ adapterName: string;
+ modelId: string;
+ /** Opaque process-local credential identity; never a raw token or API key. */
+ credentialIdentity: string;
+ /**
+ * Salted-HMAC credential identity that survives restarts, for the durable
+ * thought-signature store (#1926). Absent when no durable identity could be
+ * derived — the durable store then refuses to key the entry (fail closed).
+ */
+ credentialDurableIdentity?: string;
+}
+
+/**
+ * Stable holder shared by parsed-request copies and already-created bridges.
+ * Credential/provider rotation replaces `current` atomically without replacing
+ * the holder, so late tool-call cache writes see the active physical identity.
+ */
+export interface OcxReasoningReplayScopeRef {
+ readonly clientThreadId: string;
+ current?: Readonly;
+}
+
+export interface OcxParsedRequest {
+ modelId: string;
+ /** Client-facing model selector retained for Anthropic routes after wire-model normalization. */
+ _responseModelId?: string;
+ /** Selected OpenAI API virtual-model id retained after it rewrites the upstream wire model. */
+ _openAiVirtualSelectedModelId?: string;
+ previousResponseId?: string;
+ context: OcxContext;
+ stream: boolean;
+ options: OcxRequestOptions;
+ _rawBody?: unknown;
+ /**
+ * Boundary between replayed history and this turn's newly appended input. Usually the
+ * items the proxy restored from local previous_response_id state; also set when the
+ * CLIENT already carried that history verbatim and the proxy skipped the prepend.
+ */
+ _replayPrefixLen?: number;
+ /** Parsed-message index before the first conversational item in a continuation's current delta. */
+ _continuationConversationMessageIndex?: number;
+ /**
+ * True when the full history for a previous_response_id request is present in the input —
+ * whether the proxy expanded it or the client already sent it. Consumers read this as
+ * "this request is self-contained", never as "the proxy mutated it".
+ */
+ _previousResponseInputExpanded?: boolean;
+ /** Provider-private stable Cursor conversation id resolved from the Responses previous_response_id chain. */
+ _cursorConversationId?: string;
+ /** Stable upstream client thread identity, used only to derive provider-scoped continuation ids. */
+ _clientThreadId?: string;
+ /** Provider/account/model-bound namespace for process-local raw-reasoning replay. */
+ _reasoningReplayScope?: OcxReasoningReplayScopeRef;
+ /**
+ * Optional authenticated tenant/operator namespace for Cursor thread→conversation derivation.
+ * When absent (single-operator local proxy), derivation stays local-scoped.
+ */
+ _cursorIdentityScope?: string;
+ /**
+ * True for helper/shadow/compaction turns that must not append into the main Cursor conversation
+ * derived from the parent thread id.
+ */
+ _cursorIsolateConversation?: boolean;
+ /** Account-scoped, non-secret Kiro request metadata selected with the OAuth access token. */
+ _kiroAuthContext?: Pick;
+ /** Provider-private continuation metadata resolved from the Responses previous_response_id chain. */
+ _providerContinuation?: OcxProviderContinuationState;
+ /**
+ * The hosted `{type:"web_search", ...}` tool config, stashed when Codex enables web search. Routed
+ * (non-OpenAI) providers can't run it server-side, so the proxy re-exposes it as a function tool and
+ * executes searches via the gpt-5.4-mini sidecar (see src/web-search). Absent when not requested.
+ */
+ _webSearch?: Record;
+ /** Hosted image_generation tool config stashed for the image bridge sidecar (see src/images). */
+ _imageGeneration?: { toolNames: Set; originalTool?: Record };
+ /**
+ * True when Codex requested structured output (`text.format` = json_schema/json_object). The
+ * web-search tool_result is then rendered as compact JSON instead of markdown prose, so its
+ * answer/"Sources:" text can't bleed into and corrupt the model's schema-constrained output.
+ */
+ _structuredOutput?: boolean;
+ /**
+ * True when the input carried `{type:"compaction_trigger"}` — Codex remote compaction v2 asking
+ * this turn to produce a `{type:"compaction"}` output item. Routed adapters can't natively;
+ * the server runs the model as a summarizer and the bridge emits a synthetic compaction item
+ * (see src/responses/compaction.ts).
+ */
+ _compactionRequest?: boolean;
+ /**
+ * True when the current request newly introduced a stored compaction summary/marker. Historical
+ * markers restored by previous_response_id expansion were already acknowledged and do not reset
+ * provider-private continuation caches again on every later turn.
+ */
+ _contextCompactionBoundary?: boolean;
+}
+
+export interface OcxContext {
+ systemPrompt?: string[];
+ messages: OcxMessage[];
+ tools?: OcxTool[];
+}
+
+export type OcxMessage =
+ | OcxUserMessage
+ | OcxAssistantMessage
+ | OcxDeveloperMessage
+ | OcxToolResultMessage;
+
+export interface OcxUserMessage {
+ role: "user";
+ content: string | OcxContentPart[];
+ timestamp: number;
+}
+
+export interface OcxAssistantMessage {
+ role: "assistant";
+ content: OcxAssistantContentPart[];
+ /** Responses message phase, preserved when replaying translated provider output. */
+ phase?: OcxMessagePhase;
+ model?: string;
+ timestamp: number;
+ /**
+ * Kiro `reasoningContent.redactedContent` for THIS assistant turn — an opaque encrypted blob
+ * Kiro replays to preserve model reasoning across turns. Provider-specific and unrenderable, so
+ * it rides the message rather than a content part: any other adapter simply ignores it.
+ */
+ kiroRedactedReasoning?: string;
+}
+
+export interface OcxDeveloperMessage {
+ role: "developer";
+ content: string | OcxContentPart[];
+ timestamp: number;
+}
+
+export interface OcxToolResultMessage {
+ role: "toolResult";
+ toolCallId: string;
+ toolName: string;
+ /** MCP namespace from the originating tool call, if any. */
+ toolNamespace?: string;
+ /** Text, or content parts when a tool (e.g. Codex view_image) returns an image in its output. */
+ content: string | OcxContentPart[];
+ /** True when the Responses result contained opaque encrypted output Kiro cannot translate. */
+ containsEncryptedContent?: boolean;
+ isError: boolean;
+ timestamp: number;
+}
+
+export interface OcxTextContent {
+ type: "text";
+ text: string;
+}
+
+export interface OcxImageContent {
+ type: "image";
+ /** A `data:` URL (base64) or a remote https URL — passed through from Codex verbatim, NEVER inlined as text. */
+ imageUrl: string;
+ /** Fidelity hint from Codex: "low" | "high" | "auto". */
+ detail?: string;
+}
+
+/** A user/developer message content part: text or an image (vision). */
+export type OcxContentPart = OcxTextContent | OcxImageContent;
+
+export interface OcxThinkingContent {
+ type: "thinking";
+ thinking: string;
+ signature?: string;
+ itemId?: string;
+ /** Raw Anthropic redacted_thinking block payloads to replay verbatim (order preserved). */
+ redacted?: string[];
+}
+
+export interface OcxToolCall {
+ type: "toolCall";
+ id: string;
+ name: string;
+ arguments: Record;
+ customWireName?: string;
+ thoughtSignature?: string;
+ /**
+ * Provider-issued opaque metadata that must survive the whole round trip unchanged
+ * (issue #1735). A signed Gemini part is only valid when its signature comes back on the
+ * SAME part it was issued for, so this travels with the individual tool call rather than
+ * being matched by name/arguments after the fact.
+ */
+ providerMetadata?: OcxProviderOpaqueToolCallMetadata;
+ /** MCP namespace (e.g. "mcp__context7") when this call targets a namespaced tool. */
+ namespace?: string;
+}
+
+/**
+ * Opaque, provider-scoped tool-call metadata. Values are never parsed, merged, re-encoded, or
+ * synthesized — they are carried verbatim or not at all.
+ */
+export interface OcxProviderOpaqueToolCallMetadata {
+ google?: {
+ thoughtSignature?: string;
+ };
+}
+
+export type OcxAssistantContentPart = OcxTextContent | OcxThinkingContent | OcxToolCall;
+export interface OcxRequestOptions {
+ maxOutputTokens?: number;
+ temperature?: number;
+ topP?: number;
+ stopSequences?: string[];
+ toolChoice?: OcxToolChoice;
+ parallelToolCalls?: boolean;
+ reasoning?: string;
+ hideThinkingSummary?: boolean;
+ serviceTier?: string;
+ /** Final outbound tier action, resolved after the provider/model wire is settled. */
+ tierDecision?: TierDecision;
+ /** Internal B0 observation inputs; adapters combine these with the wire they actually serialize. */
+ tierObservation?: TierObservationContext;
+ presencePenalty?: number;
+ frequencyPenalty?: number;
+ /** Responses prompt-cache affinity key. Passthrough preserves it via _rawBody; routed adapters do not consume it unless their upstream wire supports it. */
+ promptCacheKey?: string;
+ /**
+ * Responses `text.format` (json_schema / json_object), preserved for adapters whose
+ * upstream wire has an equivalent. The openai-chat adapter re-nests it as chat
+ * `response_format`, the exact inverse of responseFormatToText in src/chat/inbound.ts.
+ * The native passthrough ignores it (it forwards `_rawBody.text` verbatim) and Kiro
+ * keeps rejecting structured output via `_structuredOutput`.
+ */
+ textFormat?: {
+ type: "json_schema" | "json_object";
+ name?: string;
+ description?: string;
+ schema?: Record;
+ strict?: boolean;
+ };
+}
+
+export type OcxMessagePhase = "commentary" | "final_answer";
+
+/**
+ * Provider-private state that must follow a locally expanded `previous_response_id` chain.
+ * Kept out of public Responses output and persisted only in the bounded local continuation cache.
+ */
+export interface OcxProviderContinuationState {
+ cursor?: {
+ conversationId?: string;
+ checkpointUsable?: boolean;
+ };
+ kiro?: {
+ conversationId?: string;
+ };
+ [provider: string]: Record | undefined;
+}
+
+export type AdapterEvent =
+ | { type: "heartbeat" }
+ | { type: "text_delta"; text: string; phase?: OcxMessagePhase }
+ | { type: "thinking_delta"; thinking: string }
+ // Anthropic extended-thinking round-trip: signature_delta for the current thinking block, and
+ // opaque redacted_thinking blocks. Both must be replayed verbatim or tool-use turns 400.
+ | { type: "thinking_signature"; signature: string }
+ | { type: "redacted_thinking"; data: string }
+ // Kiro reasoning round-trip: the encrypted `redactedContent` blob for the CURRENT assistant turn.
+ // Never rendered — it only rides the reasoning item's envelope so the next request can replay it.
+ | { type: "kiro_redacted_reasoning"; data: string }
+ | { type: "reasoning_raw_delta"; text: string }
+ | { type: "tool_call_start"; id: string; name: string; providerMetadata?: OcxProviderOpaqueToolCallMetadata }
+ | { type: "tool_call_delta"; arguments: string }
+ | { type: "tool_call_end" }
+ /** Internal boundary between a guarded first pass and its one-shot continuation. */
+ | { type: "assistant_boundary" }
+ // Native web-search activity surfaced by the web-search sidecar so Codex renders a "Searched the
+ // web" cell. Emitted as a lifecycle PAIR at real wall-clock moments by src/web-search/loop.ts
+ // (routed adapters never emit these): `begin` right before the sidecar runs so Codex shows the
+ // "Searching the web" spinner, then `end` once it resolves. The bridge maps begin → an
+ // output_item.added(in_progress) and end → the matching output_item.done(completed|failed) under
+ // the SAME output index, so the activity animates instead of flashing completed instantly.
+ | { type: "web_search_call_begin"; id: string }
+ | { type: "web_search_call_end"; id: string; queries: string[]; status?: "completed" | "failed"; sources?: OcxUrlCitation[] }
+ | {
+ type: "done";
+ usage?: OcxUsage;
+ stopReason?: string;
+ endTurn?: boolean;
+ providerState?: OcxProviderContinuationState;
+ }
+ | {
+ type: "incomplete";
+ reason: string;
+ message?: string;
+ usage?: OcxUsage;
+ retryable?: boolean;
+ endTurn?: boolean;
+ providerState?: OcxProviderContinuationState;
+ }
+ // `usage` carries best-effort partial consumption when a turn dies before a clean done
+ // (e.g. cursor upstream 502 mid-stream), so failed requests can log real token counts.
+ | {
+ type: "error";
+ message: string;
+ usage?: OcxUsage;
+ /** Authoritative upstream/proxy status when known; avoids message-based classification. */
+ status?: number;
+ /** Responses error type and code when the adapter has a structured provider failure. */
+ errorType?: string;
+ code?: string;
+ retryable?: boolean;
+ };
+
+/**
+ * A web source backing a search answer. Surfaced on the search-end event and rendered by the bridge
+ * as a `url_citation` annotation on the following assistant message (the desktop app's Sources chip
+ * reads these; the TUI ignores annotations, so this is additive).
+ */
+export interface OcxUrlCitation {
+ url: string;
+ title?: string;
+}
+
+/**
+ * Canonical usage convention (devlog/260711_claude_inbound/070):
+ * - `inputTokens` is the TOTAL prompt size, INCLUDING cache reads and cache writes
+ * (OpenAI Responses convention). Anthropic parse sites normalize into this shape.
+ * - `cachedInputTokens` is cache READ tokens only (a subset of `inputTokens`).
+ * - `cacheReadInputTokens`/`cacheCreationInputTokens` carry the read/write split when
+ * the provider reports both; reads mirror `cachedInputTokens`.
+ * - `totalTokens` = inputTokens + outputTokens. Never re-add cache detail on top.
+ */
+export interface OcxUsage {
+ inputTokens: number;
+ outputTokens: number;
+ /**
+ * Absolute active-context size after the response. Stateful providers can expose this separately
+ * from their per-attempt usage. Responses serialization derives the input side from
+ * `contextTotalTokens - outputTokens` so output is never added to an absolute checkpoint twice.
+ */
+ contextTotalTokens?: number;
+ totalTokens?: number;
+ cachedInputTokens?: number;
+ cacheReadInputTokens?: number;
+ cacheCreationInputTokens?: number;
+ reasoningOutputTokens?: number;
+ estimated?: boolean;
+}
diff --git a/src/types/tools.ts b/src/types/tools.ts
new file mode 100644
index 0000000000..9e3dc37fd0
--- /dev/null
+++ b/src/types/tools.ts
@@ -0,0 +1,131 @@
+export interface OcxTool {
+ name: string;
+ description: string;
+ parameters: Record;
+ strict?: boolean;
+ /** MCP namespace (e.g. "mcp__context7") for tools flattened out of a Responses "namespace" tool. */
+ namespace?: string;
+ /** Freeform/custom tool (e.g. apply_patch): the model's call must be relayed as a custom_tool_call. */
+ freeform?: boolean;
+ /** Client-executed tool discovery (tool_search): the model's call must be relayed as a tool_search_call. */
+ toolSearch?: boolean;
+ /** Tool definition restored from a prior tool_search output; transports may prioritize it when catalogs are bounded. */
+ loadedFromToolSearch?: boolean;
+ /** Cursor-only synthetic exact-match edit tool; never inferred from the wire name. */
+ cursorStructuredEdit?: true;
+ /** Synthetic web_search tool: the model's call is executed by the gpt-5.4-mini sidecar, not relayed to Codex. */
+ webSearch?: boolean;
+ /** Synthetic image_gen tool: the model's call is executed by the xAI image bridge sidecar, not relayed to Codex. */
+ imageGeneration?: boolean;
+ /** Synthetic video_gen tool: executed by the xAI video bridge sidecar. */
+ videoGeneration?: boolean;
+}
+
+/**
+ * Wire name a chat model sees for a tool. Namespaced (MCP) tools are flattened to
+ * "