@bitkyc08/opencodex 2.84.0 → 2.86.0

package/src/adapters/cursor/protobuf-events.ts

@@ -2,6 +2,7 @@ import type { OcxUsage } from "../../types";
 import type { AgentServerMessage, McpArgs, ToolCall } from "./gen/agent_pb";
 import { decodeCursorArgsMap } from "./arg-codec";
 import { normalizeArgKeys } from "./arg-normalize";
+import { canonicalCursorFreeformArgs } from "./freeform-args";
 import {
   CODEX_APPLY_PATCH_TOOL,
   CURSOR_MULTI_EDIT_TOOL,
@@ -334,9 +335,20 @@ function toolSchemaForWireName(state: CursorProtobufEventState, toolName: string
   return resolveShellBridgeAliasKey(toolName, alias => state.toolSchemas!.get(alias));
 }
 
-function decodeMcpArgsNormalized(args: McpArgs | undefined, state: CursorProtobufEventState): string {
-  const decoded = decodeCursorArgsMap(args?.args);
+function isFreeformCall(state: CursorProtobufEventState, responsesName: string | undefined): boolean {
+  return responsesName !== undefined && state.freeformToolNames?.has(responsesName) === true;
+}
+
+function decodeMcpArgsNormalized(
+  args: McpArgs | undefined,
+  state: CursorProtobufEventState,
+  openResponsesName?: string,
+): string {
   const toolName = mcpWireNameFromArgs(args);
+  const responsesName = toolName
+    ? responsesToolNameFromCursorWire(toolName, state.cursorToolNameMap)
+    : openResponsesName;
+  const decoded = decodeCursorArgsMap(args?.args, { preserveStrings: isFreeformCall(state, responsesName) });
   const schema = toolSchemaForWireName(state, toolName);
   if (schema) return JSON.stringify(normalizeArgKeys(decoded, schema));
   return JSON.stringify(decoded);
@@ -381,8 +393,13 @@ function normalizeJsonText(text: string, toolName: string | undefined, state: Cu
  * preserved verbatim so the bridge can reject malformed or truncated JSON instead of silently
  * converting it to `{}`. A genuinely empty buffer remains the no-argument case.
  */
-function resolveCompletedArgs(buffered: string, args: McpArgs | undefined, state: CursorProtobufEventState): string {
-  if (hasMcpArgBytes(args)) return decodeMcpArgsNormalized(args, state);
+function resolveCompletedArgs(
+  buffered: string,
+  args: McpArgs | undefined,
+  state: CursorProtobufEventState,
+  openResponsesName?: string,
+): string {
+  if (hasMcpArgBytes(args)) return decodeMcpArgsNormalized(args, state, openResponsesName);
   const name = mcpWireNameFromArgs(args);
   if (isCompleteJson(buffered)) return normalizeJsonText(buffered, name, state);
   return buffered;
@@ -1092,7 +1109,7 @@ export function mapSyntheticMcpExecToToolEvents(
     const out: CursorServerMessage[] = [...recordToolCall(options.state, callId, cursorWireName)];
     if (out.some(event => event.type === "error")) return out;
     const open = options.state.openToolCalls.get(callId);
-    const finalArgs = resolveCompletedArgs(open?.args ?? "", args, options.state);
+    const finalArgs = resolveCompletedArgs(open?.args ?? "", args, options.state, open?.name);
     out.push(...commitToolCall(options.state, callId, finalArgs));
     return out;
   }
@@ -1167,23 +1184,16 @@ function discardBufferedTextToolCalls(state: CursorProtobufEventState): void {
  * recorded in `openToolCalls`. Because each completion emits a whole non-interleaved unit, the bridge
  * (which tracks a single current tool call) serializes parallel Cursor calls correctly.
  */
-function cursorFreeformWrapperValid(args: string): boolean {
-  try {
-    const parsed = JSON.parse(args) as unknown;
-    return !!parsed
-      && typeof parsed === "object"
-      && !Array.isArray(parsed)
-      && typeof (parsed as Record<string, unknown>).input === "string";
-  } catch {
-    return false;
-  }
+/** True when the args already carry a body this call can commit, canonical or repairable (#7049). */
+function cursorFreeformArgsCommittable(args: string, toolName: string): boolean {
+  return canonicalCursorFreeformArgs(args, toolName).ok;
 }
 
-function dropInvalidFreeformCall(state: CursorProtobufEventState, callId: string, toolName: string): CursorServerMessage[] {
+function dropInvalidFreeformCall(state: CursorProtobufEventState, callId: string, toolName: string, reason: string): CursorServerMessage[] {
   state.openToolCalls.delete(callId);
   state.translatorBudget?.closeCall(callId);
   state.completedToolCalls.add(callId);
-  return [{ type: "error", message: `${toolName} call had invalid freeform arguments; expected {input:string}` }];
+  return [{ type: "error", message: `${toolName} call had invalid freeform arguments; expected {input:string} (${reason})` }];
 }
 
 function dropShellBridgeCall(state: CursorProtobufEventState, callId: string, toolName: string): CursorServerMessage[] {
@@ -1202,11 +1212,14 @@ function dropStructuredEditCall(state: CursorProtobufEventState, callId: string,
   return [{ type: "text", text: `\n${toolName} call was not converted to apply_patch: ${reason}` }];
 }
 
-function commitToolCall(state: CursorProtobufEventState, callId: string, finalArgs: string): CursorServerMessage[] {
+function commitToolCall(state: CursorProtobufEventState, callId: string, committedArgs: string): CursorServerMessage[] {
   const open = state.openToolCalls.get(callId);
   if (!open) return [];
-  if (state.freeformToolNames?.has(open.name) && !cursorFreeformWrapperValid(finalArgs)) {
-    return dropInvalidFreeformCall(state, callId, open.name);
+  let finalArgs = committedArgs;
+  if (isFreeformCall(state, open.name)) {
+    const freeform = canonicalCursorFreeformArgs(finalArgs, open.name);
+    if (!freeform.ok) return dropInvalidFreeformCall(state, callId, open.name, freeform.reason);
+    finalArgs = freeform.args;
   }
   const schema = toolSchemaForWireName(state, open.name);
   if (!cursorShellBridgeArgsValid(finalArgs, open.name, schema)) {
@@ -1386,7 +1399,7 @@ export function mapCursorProtobufServerMessage(
         && (
           (name !== undefined && openBeforeStart.args.length === 0)
           || (state.freeformToolNames?.has(openBeforeStart.name) === true
-            && !cursorFreeformWrapperValid(openBeforeStart.args)
+            && !cursorFreeformArgsCommittable(openBeforeStart.args, openBeforeStart.name)
           )
         )
       ) {
@@ -1410,13 +1423,13 @@ export function mapCursorProtobufServerMessage(
       if (
         !openBeforeStart && open && !hasMcpArgBytes(args)
         && state.freeformToolNames?.has(open.name) === true
-        && !cursorFreeformWrapperValid(open.args)
+        && !cursorFreeformArgsCommittable(open.args, open.name)
       ) {
         open.awaitingNativeArgs = true;
         return [];
       }
       if (open) {
-        const finalArgs = resolveCompletedArgs(open.args, args, state);
+        const finalArgs = resolveCompletedArgs(open.args, args, state, open.name);
         out.push(...commitToolCall(state, update.value.callId, finalArgs));
       }
       return out;

package/src/adapters/google-antigravity-wire.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { OcxContentPart, OcxParsedRequest } from "../types";
-import { antigravityUserAgent } from "./client-fingerprint";
+import { antigravityCliUserAgent, antigravityUserAgent } from "./client-fingerprint";
 
 /**
  * Antigravity request User-Agent. Mirrors the real Antigravity IDE UA
@@ -11,6 +11,27 @@ import { antigravityUserAgent } from "./client-fingerprint";
  */
 export const ANTIGRAVITY_REQUEST_UA = antigravityUserAgent();
 
+/**
+ * Antigravity CLI User-Agent. CCA serves Gemini 4 Argon only to the CLI client family, and it
+ * 404s other agent models (`gemini-3.7-flash-tiered`, `gemini-3.1-pro-low`) under it, so the
+ * choice is per wire model: see `antigravityUserAgentForWireModel`.
+ */
+export const ANTIGRAVITY_CLI_REQUEST_UA = antigravityCliUserAgent();
+
+/**
+ * Model discovery (`:fetchAvailableModels`) uses the CLI UA so Argon's wire ids are listed;
+ * under the IDE UA they are absent.
+ */
+export const ANTIGRAVITY_DISCOVERY_UA = ANTIGRAVITY_CLI_REQUEST_UA;
+
+/** Wire ids CCA serves only to the CLI client family (verified 2026-10-14). */
+const ANTIGRAVITY_CLI_ONLY_WIRE_MODEL = /^gemini-4-argon(?:-(?:low|medium|high))?$/;
+
+/** The User-Agent an Antigravity inference request for `wireModelId` must carry. */
+export function antigravityUserAgentForWireModel(wireModelId: string): string {
+  return ANTIGRAVITY_CLI_ONLY_WIRE_MODEL.test(wireModelId) ? ANTIGRAVITY_CLI_REQUEST_UA : ANTIGRAVITY_REQUEST_UA;
+}
+
 /**
  * Whether a stored `OcxToolCall.thoughtSignature` is a REAL upstream Gemini signature versus a
  * foreign id that must not be forwarded to Gemini/Antigravity.

package/src/adapters/google.ts

@@ -21,7 +21,7 @@ import { getVertexAccessToken } from "../lib/gcp-adc";
 import { fetchAntigravityWithRetry, fetchVertexWithRetry } from "./google-http";
 import { safeAntigravityHttpErrorMessage, safeVertexHttpErrorMessage } from "./google-errors";
 import { isVertexTruncatedTurn, vertexTruncationErrorEvent } from "./google-truncation";
-import { ANTIGRAVITY_REQUEST_UA, antigravitySessionAnchor, antigravitySessionId, isLikelyRealThoughtSignature, sanitizeAntigravityClaudeSignatures } from "./google-antigravity-wire";
+import { antigravitySessionAnchor, antigravityUserAgentForWireModel, antigravitySessionId, isLikelyRealThoughtSignature, sanitizeAntigravityClaudeSignatures } from "./google-antigravity-wire";
 import { summarizeGoogleWireShape } from "./google-wire-shape";
 import { compileGoogleWireBody } from "./google-wire-compiler";
 import type { GoogleToolSchemaLossReport, GoogleToolSchemaProfile } from "./google-tool-schema";
@@ -1155,7 +1155,7 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
           requestId: `agent-${crypto.randomUUID()}`,
           request,
         };
-        headers["User-Agent"] = ANTIGRAVITY_REQUEST_UA;
+        headers["User-Agent"] = antigravityUserAgentForWireModel(wireModelId);
         headers["Authorization"] = `Bearer ${token}`;
         return { url, method: "POST", headers, body: JSON.stringify(envelope) };
       }

package/src/adapters/openai-chat/response-events.ts

@@ -1,6 +1,7 @@
 import { diagnoseInvalidToolCalls, isRecord, type InvalidToolCallDiagnostic } from "./tool-call-validation";
 import { TranslatorBudgetExceededError, type TranslatorBudget } from "../../lib/translator-budget";
-import type { AdapterEvent, OcxUsage } from "../../types";
+import type { AdapterEvent, OcxProviderConfig, OcxUsage } from "../../types";
+import { createInlineThinkContentSplitter } from "../inline-think-tags";
 
 export function stopReasonFor(finishReason: unknown): "max_tokens" | "content_filter" | undefined {
   return finishReason === "length"
@@ -18,6 +19,63 @@ export function reasoningTextFrom(record: Record<string, unknown>): string | und
       : undefined;
 }
 
+type ChatContentEvent = Extract<AdapterEvent, { type: "text_delta" | "reasoning_raw_delta" | "error" }>;
+
+/** Mistral can mix typed blocks and strings in one response. Other destinations keep their parser. */
+export function chatContentEvents(content: unknown, baseUrl: string, usage?: OcxUsage, buffered = false): ChatContentEvent[] {
+  if (typeof content === "string") return content.length > 0 || buffered ? [{ type: "text_delta", text: content }] : [];
+  if (!Array.isArray(content)) return [];
+  let host: string;
+  try { host = new URL(baseUrl).hostname; } catch { return []; }
+  if (host !== "api.mistral.ai") return [];
+  const invalid = (): ChatContentEvent[] => [{
+    type: "error", status: 502, errorType: "upstream_error",
+    message: "unsupported Mistral content block", ...(usage ? { usage } : {}),
+  }];
+  const events: ChatContentEvent[] = [];
+  for (const block of content) {
+    if (!isRecord(block)) return invalid();
+    if (block.type === "text" && typeof block.text === "string") {
+      if (block.text.length > 0 || buffered) events.push({ type: "text_delta", text: block.text });
+    } else if (block.type === "thinking" && Array.isArray(block.thinking)) {
+      for (const inner of block.thinking) {
+        if (!isRecord(inner) || inner.type !== "text" || typeof inner.text !== "string") return invalid();
+        if (inner.text.length > 0) events.push({ type: "reasoning_raw_delta", text: inner.text });
+      }
+    } else return invalid();
+  }
+  return events;
+}
+
+/** Keep adjacent text together; typed reasoning flushes and resets inline-tag parsing. */
+export function createChatContentSplitter(provider: OcxProviderConfig, modelId: string | undefined, budget: TranslatorBudget) {
+  let splitter = createInlineThinkContentSplitter(provider.inlineThinkTagModels, modelId, budget);
+  return {
+    feed(event: ChatContentEvent): AdapterEvent[] {
+      if (event.type === "error") return [event];
+      if (event.type === "text_delta") return splitter.feed(event.text);
+      const pending = splitter.flush();
+      splitter.dispose();
+      splitter = createInlineThinkContentSplitter(provider.inlineThinkTagModels, modelId, budget);
+      return [...pending, event];
+    },
+    flush: () => splitter.flush(),
+    dispose: () => splitter.dispose(),
+  };
+}
+
+/** Split a buffered answer with the same typed-reasoning boundaries as a stream. */
+export function splitChatContentEvents(content: unknown, provider: OcxProviderConfig, modelId: string | undefined, budget: TranslatorBudget, usage?: OcxUsage): AdapterEvent[] {
+  const events = chatContentEvents(content, provider.baseUrl, usage, true);
+  if (events.some(event => event.type === "error")) return events;
+  const splitter = createChatContentSplitter(provider, modelId, budget);
+  try {
+    return [...events.flatMap(event => splitter.feed(event)), ...splitter.flush()];
+  } finally {
+    splitter.dispose();
+  }
+}
+
 export interface ReasoningDetailSegment {
   key: string;
   text: string;

package/src/adapters/openai-chat.ts

@@ -5,7 +5,6 @@ import { applyExplicitChatReasoningWirePolicy } from "./openai-chat/reasoning-wi
 import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "./base";
 import type { AdapterEvent, OcxParsedRequest, OcxProviderConfig, OcxUsage } from "../types";
 import { modelInList } from "../types";
-import { createInlineThinkContentSplitter, splitInlineThinkContent } from "./inline-think-tags";
 import { mapReasoningEffort } from "../reasoning-effort";
 import { debugProviderDiagnostic } from "../lib/debug";
 import { sseFieldValue } from "../lib/sse-decoder";
@@ -28,6 +27,7 @@ import {
   type InvalidToolCallDiagnostic,
 } from "./openai-chat/tool-call-validation";
 import {
+  chatContentEvents, createChatContentSplitter, splitChatContentEvents,
   createReasoningDetailSnapshotTracker,
   invalidChoicesEvent,
   invalidToolCallsEvent,
@@ -368,7 +368,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       const reasoningDetailsOptIn = modelInList(provider.reasoningDetailsModels, lastRequestedModelId ?? "");
       // A gateway with no server-side reasoning parser leaves thinking inline in `content` as
       // <think> blocks, which would otherwise render as the answer. Passthrough unless opted in.
-      const inlineThink = createInlineThinkContentSplitter(provider.inlineThinkTagModels, lastRequestedModelId, budget);
+      const inlineThink = createChatContentSplitter(provider, lastRequestedModelId, budget);
       const emitContent = function* (events: AdapterEvent[]): Generator<AdapterEvent> {
         for (const event of events) {
           // Any other event keeps its place behind held text instead of overtaking it.
@@ -444,8 +444,9 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
             const reasoningText = reasoningTextFrom(delta);
             if (reasoningText !== undefined) yield* toolCallContent.hold({ type: "reasoning_raw_delta", text: reasoningText });
           }
-          if (typeof delta.content === "string" && delta.content.length > 0) {
-            yield* emitContent(inlineThink.feed(delta.content));
+          for (const event of chatContentEvents(delta.content, provider.baseUrl, pendingUsage)) {
+            if (event.type === "error") return yield* terminateWithError(event);
+            yield* emitContent(inlineThink.feed(event));
           }
 
           const rawToolCalls = delta.tool_calls;
@@ -767,7 +768,9 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
         }
         if (reasoningText !== undefined) events.push({ type: "reasoning_raw_delta", text: reasoningText });
         const contentStart = events.length;
-        if (typeof msg.content === "string") events.push(...splitInlineThinkContent(provider.inlineThinkTagModels, lastRequestedModelId, budget, msg.content));
+        const contentEvents = splitChatContentEvents(msg.content, provider, lastRequestedModelId, budget, usage);
+        if (contentEvents.some(event => event.type === "error")) return contentEvents;
+        events.push(...contentEvents);
         const contentEnd = events.length;
         const answerText = events.slice(contentStart).map(event => (event.type === "text_delta" ? event.text : "")).join("");
         // Each call holds the delta event it emitted, so the batch repair sets its arguments later.

package/src/adapters/qoder/adapter.ts

@@ -4,12 +4,50 @@ import type { AdapterRequest, ProviderAdapter } from "../base";
 import { mapReasoningEffort } from "../../reasoning-effort";
 import { buildSystemPrompt, MAX_TOOL_BLOCK_STARTS } from "../coding-agent/protocol";
 import { buildCodingAgentToolCatalog, CodingAgentToolCatalogError } from "../coding-agent/tool-catalog";
-import { baseScopedEnv, runCodingAgentTurn, type CodingAgentDeps, type CodingAgentToolBridgeInput } from "../coding-agent/turn";
+import { baseScopedEnv, runCodingAgentTurn, type CodingAgentDeps, type CodingAgentToolBridgeInput, type CodingAgentFailure } from "../coding-agent/turn";
 import { QODER_PROFILES, resolveQoderProfile, type QoderProfile } from "./profiles";
 import { QoderScaffoldFilter, QODER_SCAFFOLD_ERROR_CODE, qoderScaffoldErrorMessage } from "./scaffold-guard";
 
 export type QoderAdapterDeps = CodingAgentDeps;
 
+function classifyQoderFailure(failure: CodingAgentFailure): Extract<AdapterEvent, { type: "error" }> {
+  const { error, profile } = failure;
+  const auth = (): typeof error => ({
+    ...error, status: 401, errorType: "authentication_error", code: "invalid_api_key",
+    retryable: false, apiKeyRecovery: true,
+  });
+  if (failure.source === "process-exit") {
+    return failure.exitCode === 41 || (failure.exitCode === 1
+      && failure.stderr.includes("QoderAuthError")
+      && !!profile.tokenEnv && failure.stderr.includes(profile.tokenEnv)
+      && /token (?:that )?was rejected/i.test(failure.stderr))
+      ? auth() : error;
+  }
+  const code = failure.frame.error_code;
+  if (code === 105) return auth();
+  if (code === 114) return {
+    ...error, status: 403, errorType: "permission_error", code: "permission_denied", retryable: false,
+  };
+  if (typeof code === "number" && [110, 113, 115, 116, 117, 118, 119, 122].includes(code)) {
+    return {
+      ...error, status: 429, errorType: "insufficient_quota", code: "insufficient_quota", retryable: false,
+      ...(code === 110 || code === 118 ? { apiKeyRecovery: true as const } : {}),
+    };
+  }
+  if (typeof code === "number") return error;
+  if (/daily usage limit|credit usage limit/i.test(error.message)) {
+    const isAccountDaily = /^You've reached your daily usage limit for Chat\b/i.test(error.message.trim())
+      && !/\b(?:team|model|shared)\b/i.test(error.message);
+    return {
+      ...error, status: 429, errorType: "insufficient_quota", code: "insufficient_quota",
+      retryable: false,
+      ...(isAccountDaily ? { apiKeyRecovery: true as const } : {}),
+    };
+  }
+  if (/\binvalid (?:personal access )?token\b|\btoken (?:was |that was )?rejected\b|\bqoder authentication rejected\b/i.test(error.message)) return auth();
+  return error;
+}
+
 const QODER_MCP_SERVER_NAME = "opencodex";
 const QODER_MCP_SERVER_PATH = fileURLToPath(new URL("../coding-agent/mcp-server.ts", import.meta.url));
 
@@ -164,6 +202,7 @@ export function createQoderAdapter(provider: OcxProviderConfig, deps: QoderAdapt
       const system = buildSystemPrompt(parsed);
       await runCodingAgentTurn({
           profiles: QODER_PROFILES,
+          classifyFailure: classifyQoderFailure,
           provider,
           parsed,
           incoming,

package/src/advisor/consult.ts

@@ -0,0 +1,220 @@
+/**
+ * Execute ONE advisor consultation through the proxy's own /v1/chat/completions on loopback.
+ *
+ * Same execution shape as the vision sidecar's routed describe (src/vision/routed-describe.ts):
+ * the loopback call re-enters the normal data plane, so model resolution, provider auth, effort
+ * mapping and usage accounting are the ROUTING AUTHORITY's job — the advisor never builds its own
+ * router and never touches provider credentials. Any model string the router accepts works here:
+ * a bare native model, an explicit "provider/model", or an account-qualified native model.
+ *
+ * Recursion fence: the request carries `x-opencodex-advisor-internal` set to this process's
+ * capability. The Chat surface checks that value before its bridge rebuilds headers and carries
+ * the fact into handleResponses as `advisorInternal`. A marked request never plans an advisor
+ * consultation (depth cap 1 — the same structure as the vision describe fence). The capability
+ * is not a literal and is not forwarded upstream.
+ *
+ * Failure contract: never throws. A failed consultation returns `ok: false` plus a redacted,
+ * bounded error string; the worker keeps going (fail-open) either with an explicit
+ * unavailable context or with nothing, depending on the trigger.
+ */
+import type { OcxConfig } from "../types";
+import { localAdmissionToken, localInferenceDestination } from "../lib/local-destinations";
+import { signalWithTimeout, cancelBodyOnAbort } from "../lib/abort";
+import { redactSecretString } from "../lib/redact";
+import { sidecarEnter } from "../lib/sidecar-tracker";
+import {
+  ADVISOR_INTERNAL_CAPABILITY_HEADER,
+  internalCallCapability,
+} from "../lib/local-internal-call-capability";
+import { configuredPort } from "../server/auth-cors";
+import { ADVISOR_SYSTEM_INSTRUCTION, buildAdvisorUserPrompt, type AdvisorContextInput } from "./context";
+
+/**
+ * The header the advisor presents on its own loopback request. Its VALUE is this process's
+ * internal-call capability — never a literal, and never trusted from an inbound caller.
+ */
+export { ADVISOR_INTERNAL_CAPABILITY_HEADER as ADVISOR_INTERNAL_HEADER } from "../lib/local-internal-call-capability";
+
+/** Bound the loopback JSON response; advice is prose, not data dumps. */
+const MAX_ADVISOR_RESPONSE_BYTES = 4 * 1024 * 1024;
+/** Advice length cap handed to the worker. */
+const MAX_ADVICE_CHARS = 16_000;
+
+export interface AdvisorConsultationResult {
+  ok: boolean;
+  /** Advisor prose when ok; empty string otherwise. */
+  advice: string;
+  advisorModel: string;
+  /** True when the caller aborted the request — not a provider failure (no cooldown). */
+  cancelled?: boolean;
+  /** Redacted, bounded failure description when not ok. */
+  error?: string;
+  /** Loopback round-trip duration (ms), for logs. */
+  durationMs: number;
+  /** Token usage reported by the chat completion, when the adapter surfaced it. */
+  usage?: { inputTokens?: number; outputTokens?: number; totalTokens?: number };
+}
+
+export function advisorDestinationOrigin(
+  config: Pick<OcxConfig, "port" | "hostname" | "unauthenticatedLoopbackListener">,
+): string {
+  // Same port resolution rule as the vision sidecar: config.port can be 0 (ephemeral bind, tests)
+  // or stale after a live port override, so prefer the recorded actual bind port when present.
+  const port = config.port && config.port > 0
+    ? config.port
+    : Number(configuredPort()) || 10_100;
+  return localInferenceDestination(config, port).origin;
+}
+
+function extractContent(payload: unknown): string | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const choices = (payload as { choices?: unknown }).choices;
+  if (!Array.isArray(choices) || choices.length === 0) return undefined;
+  const message = (choices[0] as { message?: unknown })?.message;
+  if (!message || typeof message !== "object") return undefined;
+  const content = (message as { content?: unknown }).content;
+  if (typeof content === "string" && content.trim().length > 0) return content;
+  if (Array.isArray(content)) {
+    const joined = content
+      .map(part => (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string"
+        ? (part as { text: string }).text
+        : ""))
+      .join("");
+    if (joined.trim().length > 0) return joined;
+  }
+  return undefined;
+}
+
+function extractUsage(payload: unknown): AdvisorConsultationResult["usage"] {
+  if (!payload || typeof payload !== "object") return undefined;
+  const usage = (payload as { usage?: unknown }).usage;
+  if (!usage || typeof usage !== "object") return undefined;
+  const num = (value: unknown): number | undefined => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  const inputTokens = num((usage as { prompt_tokens?: unknown }).prompt_tokens);
+  const outputTokens = num((usage as { completion_tokens?: unknown }).completion_tokens);
+  const totalTokens = num((usage as { total_tokens?: unknown }).total_tokens);
+  if (inputTokens === undefined && outputTokens === undefined && totalTokens === undefined) return undefined;
+  return { ...(inputTokens !== undefined ? { inputTokens } : {}), ...(outputTokens !== undefined ? { outputTokens } : {}), ...(totalTokens !== undefined ? { totalTokens } : {}) };
+}
+
+/**
+ * Base URL seam for tests; production always self-fetches the resolved local destination.
+ * The advisor is an internal caller: no credential material rides the override path in tests.
+ */
+export function advisorBaseUrl(
+  config: Pick<OcxConfig, "port" | "hostname" | "unauthenticatedLoopbackListener">,
+): string {
+  return advisorDestinationOrigin(config);
+}
+
+export async function consultAdvisor(
+  input: AdvisorContextInput,
+  config: Pick<OcxConfig, "port" | "hostname" | "apiKeys" | "unauthenticatedLoopbackListener">,
+  effort: string,
+  timeoutMs: number,
+  abortSignal?: AbortSignal,
+  baseUrlOverride?: string,
+): Promise<AdvisorConsultationResult> {
+  const t0 = Date.now();
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    [ADVISOR_INTERNAL_CAPABILITY_HEADER]: internalCallCapability(),
+  };
+  // Admission ladder identical to the vision sidecar: env token || service token file || first
+  // configured API key, sent as `x-opencodex-api-key` — never Authorization. Loopback binds that
+  // require no token simply omit it.
+  const admission = localAdmissionToken(config);
+  if (admission) headers["x-opencodex-api-key"] = admission;
+
+  const requestBody = {
+    model: input.advisorModel,
+    stream: false,
+    reasoning_effort: effort,
+    messages: [
+      { role: "system", content: ADVISOR_SYSTEM_INSTRUCTION },
+      { role: "user", content: buildAdvisorUserPrompt(input) },
+    ],
+  };
+
+  const linkedSignal = signalWithTimeout(timeoutMs, abortSignal);
+  const sidecarExit = sidecarEnter("advisor");
+  if (abortSignal?.aborted) {
+    sidecarExit();
+    linkedSignal.cleanup();
+    return { ok: false, cancelled: true, advice: "", advisorModel: input.advisorModel, error: "advisor cancelled before dispatch", durationMs: Date.now() - t0 };
+  }
+  try {
+    const res = await fetch(`${baseUrlOverride ?? advisorBaseUrl(config)}/v1/chat/completions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(requestBody),
+      signal: linkedSignal.signal,
+      redirect: "manual",
+    });
+    const detachBodyGuard = cancelBodyOnAbort(res.body, linkedSignal.signal);
+    try {
+      // Bounded read: count bytes per chunk and cancel the reader the moment the bound is
+      // exceeded, instead of materializing the full body before the length check.
+      let raw = "";
+      let totalBytes = 0;
+      const reader = res.body?.getReader();
+      if (reader) {
+        const decoder = new TextDecoder();
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          totalBytes += value.byteLength;
+          if (totalBytes > MAX_ADVISOR_RESPONSE_BYTES) {
+            try { await reader.cancel(); } catch { /* body already closing */ }
+            return { ok: false, advice: "", advisorModel: input.advisorModel, error: "advisor response exceeded byte bound", durationMs: Date.now() - t0 };
+          }
+          raw += decoder.decode(value, { stream: true });
+        }
+        raw += decoder.decode();
+      }
+      const durationMs = Date.now() - t0;
+      if (!res.ok) {
+        // Status only. Upstream bodies can echo the consultation prompt; they are not logged
+        // and not handed to the worker. display-safe body text is intentionally not copied here.
+        return {
+          ok: false, advice: "", advisorModel: input.advisorModel,
+          error: `advisor HTTP ${res.status}`,
+          durationMs,
+        };
+      }
+      let payload: unknown;
+      try { payload = JSON.parse(raw); } catch {
+        return { ok: false, advice: "", advisorModel: input.advisorModel, error: "advisor returned non-JSON", durationMs };
+      }
+      const content = extractContent(payload);
+      if (!content) {
+        return { ok: false, advice: "", advisorModel: input.advisorModel, error: "advisor returned no text", durationMs };
+      }
+      return {
+        ok: true,
+        advice: content.length > MAX_ADVICE_CHARS ? `${content.slice(0, MAX_ADVICE_CHARS)}… [truncated]` : content,
+        advisorModel: input.advisorModel,
+        durationMs,
+        ...(extractUsage(payload) ? { usage: extractUsage(payload) } : {}),
+      };
+    } finally {
+      detachBodyGuard();
+    }
+  } catch (e) {
+    const durationMs = Date.now() - t0;
+    // Client cancellation is not a provider failure: the caller aborted (linked signal), so the
+    // task must stay eligible for a later attempt rather than entering a failure cooldown.
+    if (abortSignal?.aborted) {
+      return { ok: false, cancelled: true, advice: "", advisorModel: input.advisorModel, error: "advisor cancelled by the caller", durationMs };
+    }
+    const kind = e instanceof Error && e.name === "TimeoutError" ? "timeout" : "connect_error";
+    return {
+      ok: false, advice: "", advisorModel: input.advisorModel,
+      error: `advisor ${kind}: ${redactSecretString(e instanceof Error ? e.message : String(e))}`,
+      durationMs,
+    };
+  } finally {
+    sidecarExit();
+    linkedSignal.cleanup();
+  }
+}