@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/grok/sync.ts

@@ -18,7 +18,7 @@ export interface GrokSyncDeps {
 }
 
 async function defaultFetchAllModels(config: OcxConfig): Promise<CatalogModel[]> {
-  const { fetchAllModels } = await import("../server/management-api");
+  const { fetchAllModels } = await import("../server/management/shared");
   return fetchAllModels(config);
 }
 

package/src/images/loop.ts

@@ -1,3 +1,5 @@
+import type { createAnthropicThinkingRecovery } from "../server/responses/anthropic-thinking-recovery";
+import { bindAnthropicRejectionResponse } from "../adapters/anthropic-rejection-memo";
 /**
  * Media bridge agentic loop — supports both image and video generation sidecars.
  *
@@ -20,9 +22,10 @@ import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
 import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaque-metadata";
 import type { AttemptRecoveryKind } from "../usage/log";
 import { bridgeToResponsesSSE } from "../bridge";
+import { isTerminalRefusalIncomplete } from "../bridge/terminal-refusal";
 import { clearableDeadline, idleDeadline } from "../lib/abort";
 import { readBoundedResponseBody } from "../lib/bounded-body";
-import { applyUpstreamRecoveryInit, fetchWithResetRetry, prepareSameTarget429Wait } from "../lib/upstream-retry";
+import { applyUpstreamRecoveryInit, fetchWithResetRetry, prepareSameTarget429Wait, isNonReplayableResponse, SendBudgetExhaustedError } from "../lib/upstream-retry";
 import { rateLimitRetryDelayMs } from "../providers/key-failover";
 import { releaseProviderRequestSlot, sendTrackingRequestSlot, type ProviderRequestSlot } from "../providers/request-pacing";
 import {
@@ -32,13 +35,14 @@ import {
   TRANSLATOR_MAX_TURN_BYTES,
   TranslatorBudgetExceededError,
 } from "../lib/translator-budget";
-import { parseStreamWithProgress, RoutedModelInactivityError, WebSearchStreamProtocolError } from "../web-search/progress-stream";
+import { parseStreamWithProgress, RoutedModelInactivityError, WebSearchStreamProtocolError, WebSearchAdapterEventError } from "../web-search/progress-stream";
 import { fulfillImageCall } from "./fulfill";
 import { parseVideoCallArgs, pollVideoWithHeartbeats, buildVideoResult, createVideoBudget } from "./fulfill-video";
 import { submitVideoJob } from "./xai-video-client";
 import { downloadVideoToArtifact, createImageBudget, pruneArtifacts } from "./artifacts";
 import { IMAGE_GEN_TOOL_NAME, VIDEO_GEN_TOOL_NAME } from "./synthetic-tool";
 import type { ImageBridgePlan, VideoBridgePlan } from "./types";
+import { guardEmptyToolCatalogStream, type ClientToolCatalogRestriction } from "../lib/empty-tool-catalog";
 
 const SSE_HEADERS = {
   "Content-Type": "text/event-stream",
@@ -241,7 +245,11 @@ function extractIterationThinking(events: AdapterEvent[]): OcxThinkingContent[]
   };
 
   for (const e of events) {
-    if (e.type === "thinking_delta") {
+    if (e.type === "text_delta" && e.anthropicThinkingSignature) {
+      flushVisible();
+      flushRaw();
+      parts.push({ type: "thinking", thinking: e.text, signature: e.anthropicThinkingSignature });
+    } else if (e.type === "thinking_delta") {
       flushRaw();
       thinking += e.thinking;
     } else if (e.type === "reasoning_raw_delta") {
@@ -264,17 +272,18 @@ function extractIterationThinking(events: AdapterEvent[]): OcxThinkingContent[]
   return parts;
 }
 
-function jsonError(status: number, message: string): Response {
-  return new Response(JSON.stringify({ error: { message, type: "upstream_error", code: null } }), {
+function jsonError(status: number, message: string, event?: Extract<AdapterEvent, { type: "error" }>): Response {
+  return new Response(JSON.stringify({ error: { message, type: event?.errorType ?? "upstream_error", code: event?.code ?? null,
+    ...(event?.retryable === false ? { retryable: false } : {}) } }), {
     status,
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...(event?.retryable === false ? { "x-should-retry": "false" } : {}) },
   });
 }
 
 /** Hard provider/parse failure inside an iteration. The eager first iteration converts it to a
  *  non-2xx jsonError; later (already-streaming) iterations surface it as an in-stream error event. */
 class LoopError extends Error {
-  constructor(readonly status: number, message: string) {
+  constructor(readonly status: number, message: string, readonly event?: Extract<AdapterEvent, { type: "error" }>) {
     super(message);
     this.name = "LoopError";
   }
@@ -285,7 +294,9 @@ class LoopError extends Error {
  * metadata, and the optional image/video bridge plans.
  */
 export interface ImageBridgeDeps {
+  thinkingRecovery?: ReturnType<typeof createAnthropicThinkingRecovery>;
   parsed: OcxParsedRequest;
+  clientToolCatalogRestriction?: ClientToolCatalogRestriction;
   adapter: ProviderAdapter;
   incomingMeta: IncomingMeta;
   plan?: ImageBridgePlan;
@@ -314,11 +325,17 @@ export interface ImageBridgeDeps {
   /** Provider-specific fetch (e.g. xAI transport wrapper). Falls back to global fetch. */
   fetchImpl?: typeof globalThis.fetch;
   /** Bind physical dispatch to this iteration's built request; pacing remains owned by the loop. */
-  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest, adapter: ProviderAdapter) => typeof globalThis.fetch;
+  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest, adapter: ProviderAdapter, recovery?: AttemptRecoveryKind) => typeof globalThis.fetch;
   /** Reserve the routed provider's next request-start slot before each adapter dispatch. */
   waitForRequestSlot?: (signal?: AbortSignal) => Promise<ProviderRequestSlot | void>;
   /** Raw adapter usage at the terminal event, pre wire-normalization (see bridgeToResponsesSSE onUsage). */
   onUsage?: (usage: OcxUsage | undefined) => void;
+  /**
+   * After an `on429` rotation, offered the usage of the hidden iterations the left credential
+   * served. Returning true means it was billed to that credential's attempt, so `onUsage` will not
+   * report it again; the client terminal still includes it.
+   */
+  onRotatedUsage?: (usage: OcxUsage) => boolean;
   /**
    * Optional 429 failover for the routed (non-xAI) model. Return a rebuilt adapter for the
    * rotated credential, or null when the pool is exhausted. Async hooks support OAuth refresh;
@@ -353,6 +370,8 @@ export interface ImageBridgeDeps {
   onCompletedResponse?: (response: Record<string, unknown>, providerState?: OcxProviderContinuationState) => void;
   /** WebSocket Responses path only — leave response id empty for protocol compatibility. */
   forceEmptyResponseId?: boolean;
+  /** Responses inbound only: deliver a non-retryable upstream refusal as `response.failed`. */
+  terminalRefusalAsFailed?: boolean;
 }
 
 /**
@@ -377,6 +396,10 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
   let paidImageCalls = 0;
   let paidVideoCalls = 0;
   let hiddenUsage: OcxUsage | undefined;
+  // Hidden usage already billed through onRotatedUsage: still on the client terminal, not in
+  // ledgerUsage, which is what onUsage reports once a rotation has moved some.
+  let rotatedUsage: OcxUsage | undefined;
+  let ledgerUsage: OcxUsage | undefined;
   let activeProducers = 0;
 
   const addUsage = (a: OcxUsage | undefined, b: OcxUsage | undefined): OcxUsage | undefined => {
@@ -445,6 +468,8 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
   interface IterationResponse {
     response: Response;
     responseAdapter: ProviderAdapter;
+    parsed?: OcxParsedRequest;
+    retryThinking?: () => Promise<IterationResponse>;
     /** runTurn events are already bounded; consume them without replaying or charging twice. */
     collectedEvents?: AdapterEvent[];
   }
@@ -569,6 +594,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       // runTurn adapters signal errors via {type:"error"} events, not HTTP status codes.
       const errorEvent = events.find(e => e.type === "error");
       if (errorEvent && errorEvent.type === "error") {
+        hiddenUsage = addUsage(hiddenUsage, errorEvent.usage);
         if (errorEvent.code === "translation_buffer_limit") {
           throw new TranslatorBudgetExceededError("retained_collectors", TRANSLATOR_MAX_TURN_BYTES);
         }
@@ -614,7 +640,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           cachedRequest = request;
           cachedAdapter = requestAdapter;
         }
-        const requestFetch = deps.fetchForRequest?.(request, iterParsed, requestAdapter) ?? fetchImpl;
+        const requestFetch = deps.fetchForRequest?.(request, iterParsed, requestAdapter, recovery) ?? fetchImpl;
         let response: Response;
         try {
           if (requestAdapter.fetchResponse) {
@@ -665,7 +691,8 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         } finally {
           request.releaseBodyObservation?.();
         }
-        return { response, responseAdapter: requestAdapter };
+        bindAnthropicRejectionResponse(request, response);
+        return { response, responseAdapter: requestAdapter, parsed: iterParsed };
       };
 
       let prepared = await fetchOnce(adapter);
@@ -709,15 +736,28 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         const rotated = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers,
           iterParsed, prepared.response);
         if (!rotated) break;
+        if (hiddenUsage && deps.onRotatedUsage?.(hiddenUsage)) {
+          rotatedUsage = addUsage(rotatedUsage, hiddenUsage);
+          hiddenUsage = undefined;
+        }
         try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
         adapter = rotated.adapter;
         yield { type: "heartbeat" };
         prepared = await fetchOnce(adapter, rotated.recoveryKind);
       }
 
+      if (await deps.thinkingRecovery?.prepareHttp(prepared.response, prepared.responseAdapter.name, iterParsed)) {
+        try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* closed */ }
+        cachedRequest = undefined;
+        prepared = await fetchOnce(adapter, "opaque-blob-rejection");
+      }
       // Final headers have arrived. Clear only the deadline timer before ANY body read.
       headerDeadline.clear();
       if (!prepared.response.ok) {
+        if (deps.thinkingRecovery && prepared.responseAdapter.name === "anthropic") {
+          const event = await deps.thinkingRecovery.projectHttpFailure(prepared.response, signal);
+          throw new LoopError(event.status ?? prepared.response.status, event.message, event);
+        }
         let body: Awaited<ReturnType<typeof readBoundedResponseBody>>;
         try {
           body = await readBoundedResponseBody(prepared.response, { signal });
@@ -738,9 +778,21 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         const suffix = formatted ? `: ${formatted.slice(0, 400)}` : "";
         throw new LoopError(prepared.response.status, `Provider error ${prepared.response.status}${suffix}`);
       }
-      return prepared;
+      return { ...prepared, retryThinking: async () => {
+        cachedRequest = undefined;
+        headerDeadline = clearableDeadline(connectTimeoutMs, signal);
+        try { return await fetchOnce(adapter, "opaque-blob-rejection"); }
+        catch (error) {
+          if (signal.aborted) throw new LoopError(499, "client closed request during image-bridge");
+          if (headerDeadline.didExpire()) throw new LoopError(504,
+            `Provider response-header timeout after ${connectTimeoutMs}ms during image-bridge`);
+          throw error;
+        } finally { headerDeadline.clear(); deps.onIterationEnd?.(); }
+      } };
     } catch (error) {
       if (isTranslatorBudgetExceededError(error)) throw error;
+      if (error instanceof SendBudgetExhaustedError) throw new LoopError(429, error.message,
+        { type: "error", status: 429, errorType: "rate_limit_error", code: error.code, message: error.message, retryable: false });
       if (headerDeadline.didExpire()) {
         throw new LoopError(504, `Provider response-header timeout after ${connectTimeoutMs}ms during image-bridge`);
       }
@@ -767,12 +819,31 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
     const iterationBudget = prepared.collectedEvents ? undefined : createIterationEventBudget();
     try {
       if (iterationBudget) {
-        const parse = prepared.responseAdapter.parseStream.bind(prepared.responseAdapter);
-        for await (const event of parseStreamWithProgress(prepared.response, parse, {
-          signal,
-          inactivityTimeoutMs: stallTimeoutMs,
-          translatorBudget,
-        })) {
+        const parse = async function* (current: IterationResponse): AsyncGenerator<AdapterEvent> {
+          if (!current.response.ok && deps.thinkingRecovery) {
+            yield await deps.thinkingRecovery.projectHttpFailure(current.response, signal);
+            return;
+          }
+          try {
+            yield* parseStreamWithProgress(current.response, current.responseAdapter.parseStream.bind(current.responseAdapter), {
+              signal, inactivityTimeoutMs: stallTimeoutMs, translatorBudget,
+              preserveAdapterError: deps.thinkingRecovery !== undefined,
+              onErrorUsage: usage => { hiddenUsage = addUsage(hiddenUsage, usage); },
+            });
+          } catch (error) {
+            if (!(error instanceof WebSearchAdapterEventError)) throw error;
+            if (!error.replaySafe) yield { type: "heartbeat", replayUnsafe: true };
+            yield isNonReplayableResponse(current.response)
+              ? { ...error.event, message: "Provider stream error: upstream diagnostic withheld for a non-replayable failure", retryable: false }
+              : error.event;
+          }
+        };
+        const source = deps.thinkingRecovery && prepared.retryThinking
+          ? deps.thinkingRecovery.wrap(parse(prepared), async function* () {
+              yield* parse(await prepared.retryThinking!());
+            }, () => prepared.responseAdapter.name, !isNonReplayableResponse(prepared.response), prepared.response, prepared.parsed)
+          : parse(prepared);
+        for await (const event of source) {
           if (event.type === "heartbeat") yield event;
           else {
             iterationBudget.retain(event);
@@ -786,6 +857,9 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         throw error;
       }
       if (signal.aborted) throw new LoopError(499, "client closed request during image-bridge");
+      if (error instanceof LoopError) throw error;
+      if (error instanceof SendBudgetExhaustedError) throw new LoopError(429, error.message,
+        { type: "error", status: 429, errorType: "rate_limit_error", code: error.code, message: error.message, retryable: false });
       if (error instanceof RoutedModelInactivityError) throw new LoopError(504, error.message);
       if (error instanceof WebSearchStreamProtocolError) throw new LoopError(502, error.message);
       throw new LoopError(502, `Provider stream error: ${error instanceof Error ? error.message : String(error)}`);
@@ -803,8 +877,9 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       if (terminal.code === "translation_buffer_limit") {
         throw new TranslatorBudgetExceededError("retained_collectors", TRANSLATOR_MAX_TURN_BYTES);
       }
-      throw new LoopError(502, terminal.message);
+      throw new LoopError(terminal.status ?? 502, terminal.message, terminal);
     }
+    deps.thinkingRecovery?.observeIteration(events);
     return scanEventsForImageCall(events, mediaToolNames);
   };
 
@@ -819,7 +894,9 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       firstPrepared = await prepareIterationDrained(maxRounds <= 0);
     } catch (e) {
       if (abortSignal) abortSignal.removeEventListener("abort", linkAbort);
-      if (e instanceof LoopError) return jsonError(e.status, e.message);
+      if (e instanceof LoopError) return jsonError(e.status, e.message, e.event);
+      if (e instanceof SendBudgetExhaustedError) return jsonError(429, e.message,
+        { type: "error", status: 429, errorType: "rate_limit_error", code: e.code, message: e.message, retryable: false });
       throw e;
     }
   }
@@ -863,13 +940,17 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           // Loop (fulfill + re-ask) ONLY when the model's actionable output is purely image_gen. A
           // real tool call means this turn is terminal for Codex — finalize so those calls reach
           // Codex. forceFinal also finalizes.
-          const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall && !forceFinal;
+          // A refused iteration also finalizes: fulfilling its media call would re-ask the model
+          // with the refused context (#7148).
+          const shouldLoop = split.calls.length > 0 && !split.hasRealToolCall && !forceFinal
+            && !split.passthrough.some(isTerminalRefusalIncomplete);
           if (!shouldLoop) {
-            if (hiddenUsage) {
+            if (hiddenUsage || rotatedUsage) {
               for (let i = split.passthrough.length - 1; i >= 0; i--) {
                 const e = split.passthrough[i];
                 if (e?.type === "done" || e?.type === "incomplete") {
-                  split.passthrough[i] = { ...e, usage: addUsage(hiddenUsage, e.usage) };
+                  ledgerUsage = addUsage(hiddenUsage, e.usage);
+                  split.passthrough[i] = { ...e, usage: addUsage(rotatedUsage, ledgerUsage) };
                   break;
                 }
               }
@@ -881,6 +962,10 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           // Discarded iteration still contributed tokens — accumulate for the final onUsage.
           takeUsageFrom(split.passthrough);
 
+          for (const event of split.passthrough) {
+            if (event.type === "text_delta" && event.anthropicThinkingSignature) yield event;
+          }
+
           // Fulfill each image/video call, then inject ONE assistant turn (thinking once + all tool
           // calls) so Anthropic extended-thinking continuations stay valid across parallel calls.
           const iterationThinking = extractIterationThinking(split.passthrough);
@@ -1052,6 +1137,8 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
             });
           }
         } catch (e) {
+          ledgerUsage = hiddenUsage;
+          const usage = addUsage(rotatedUsage, hiddenUsage);
           if (isTranslatorBudgetExceededError(e)) {
             yield {
               type: "error",
@@ -1059,14 +1146,14 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
               errorType: "upstream_error",
               code: e.code,
               message: "upstream translation buffer exceeded the safe limit",
-              ...(hiddenUsage ? { usage: hiddenUsage } : {}),
+              ...(usage ? { usage } : {}),
             };
           } else {
             yield {
               type: "error",
               message: e instanceof LoopError ? e.message : (e instanceof Error ? e.message : String(e)),
-              ...(e instanceof LoopError ? { status: e.status } : {}),
-              ...(hiddenUsage ? { usage: hiddenUsage } : {}),
+              ...(e instanceof LoopError ? { status: e.status, ...(e.event ?? {}) } : {}),
+              ...(usage ? { usage } : {}),
             };
           }
           return;
@@ -1079,13 +1166,15 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
   }
 
   const sse = bridgeToResponsesSSE(
-    produce(), parsed._responseModelId ?? parsed.modelId, toolNsMap, freeform, toolSearch, () => {
+    guardEmptyToolCatalogStream(produce(), deps.clientToolCatalogRestriction, translatorBudget), parsed._responseModelId ?? parsed.modelId, toolNsMap, freeform, toolSearch, () => {
       internalAbort.abort("client closed responses stream");
     }, 2_000,
     {
       translatorBudget,
       replayCacheScope: parsed._reasoningReplayScope,
+      ...(deps.clientToolCatalogRestriction ? { ...deps.clientToolCatalogRestriction, enforceDeclaredToolNames: false } : {}),
       ...(deps.forceEmptyResponseId ? { responseId: "" } : {}),
+      ...(deps.terminalRefusalAsFailed ? { terminalRefusalAsFailed: true } : {}),
       hideThinkingSummary: parsed.options.hideThinkingSummary,
       hideRawReasoning: parsed.options.hideRawReasoning,
       stallTimeoutSec: deps.stallTimeoutSec,
@@ -1093,7 +1182,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       ...(deps.onUsage ? {
         // Terminal done/incomplete already includes hiddenUsage (merged above). Do not
         // add it again here or request logs double-count multi-iteration image turns.
-        onUsage: (usage: OcxUsage | undefined) => deps.onUsage?.(usage),
+        onUsage: (usage: OcxUsage | undefined) => deps.onUsage?.(rotatedUsage ? ledgerUsage : usage),
       } : {}),
       ...(deps.onCompletedResponse ? { onCompletedResponse: deps.onCompletedResponse } : {}),
     },

package/src/integrations/catalog-refresh.ts

@@ -12,7 +12,7 @@ import {
 /** Refresh only previously connected clients; a refused file never blocks its peers. */
 export async function refreshOwnedCatalogIntegrations(
   input: Omit<OwnedIntegrationRefreshInput, "clientId">,
-  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo", "qoder"],
+  clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo", "qoder", "gentle-shell"],
   options: { refreshOnly?: boolean; admit?: () => boolean } = {},
 ): Promise<OwnedIntegrationRefreshOutcome[]> {
   // Client files are shared with the live proxy a sibling instance runs beside; their entries

package/src/integrations/mutation-plan.ts

@@ -134,6 +134,7 @@ const CLIENT_MANAGED_PATHS = {
   qoder: [["providers", OPENCODE_PROVIDER_ID], ["modelConfigs", "customModels", DYNAMIC_SEGMENT]],
   opencode: [["provider", OPENCODE_PROVIDER_ID], ["providers", OPENCODE_PROVIDER_ID]],
   pi: [["providers", OPENCODE_PROVIDER_ID]],
+  "gentle-shell": [["providers", OPENCODE_PROVIDER_ID]],
   omp: [["providers", OPENCODE_PROVIDER_ID]],
   hermes: [["providers", OPENCODE_PROVIDER_ID]],
   openclaw: [["models", "providers", OPENCODE_PROVIDER_ID]],

package/src/integrations/registry.ts

@@ -9,6 +9,7 @@
  * Design of record: devlog/_fin/260802_client_toggle_api/021 §1.
  */
 import { homedir } from "node:os";
+import { gentleShellPaths } from "../clients/gentle-shell-path";
 import { assertDroidSettingsUnambiguous } from "./droid-settings";
 import { readPath } from "./merge";
 import type { OwnershipRecord } from "./ownership";
@@ -505,6 +506,13 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
       return { configPath: droidConfigPath(env, home), detectDir };
     },
   },
+  "gentle-shell": {
+    id: "gentle-shell",
+    configPath: (env, home, io) => gentleShellPaths(env, home, io).configPath,
+    detectDir: (env, home, io) => gentleShellPaths(env, home, io).detectDir,
+    resolvePaths: (env, home, _context, io) => gentleShellPaths(env, home, io),
+    unresolvedPathHint: (_env, home = homedir()) => join(home, ".gentle-shell", "agent", "models.json"),
+  },
 };
 
 export const INTEGRATION_CLIENT_IDS: readonly IntegrationClientId[] =

package/src/lib/codex-restart-contract.ts

@@ -36,6 +36,10 @@ export interface CodexAppServerStateResponse {
  * The desktop half of a restart. Scalar-only for the same reason as the rest of this
  * contract: pid lists and a closed-vocabulary reason, never a command line or an OS
  * error message, both of which routinely embed a path or a username.
+ *
+ * `reason: "picker_current"` means the shell was deliberately left running because it
+ * launched after the current catalog was written, so only the app-servers restarted and
+ * the operator's unsaved client state was kept (#4761).
  */
 export interface CodexDesktopRestartSummary {
   attempted: boolean;
@@ -43,8 +47,17 @@ export interface CodexDesktopRestartSummary {
   surviving: number[];
   relaunch: "started" | "skipped";
   reason?: string;
+  /**
+   * Why the desktop was or was not restarted: `stale` (the shell predates the bound
+   * catalog, or this request rebound it) and `unknown` (the evidence was unreadable) both
+   * take the full restart. Absent on a proxy older than #4761.
+   */
+  pickerState?: CodexDesktopPickerState;
 }
 
+export type CodexDesktopPickerState = "current" | "stale" | "unknown" | "not_running";
+const DESKTOP_PICKER_STATES: readonly string[] = ["current", "stale", "unknown", "not_running"];
+
 /** POST response. All four arrays are pid lists — never command lines. */
 export interface CodexRestartResponse {
   success: boolean;
@@ -130,6 +143,8 @@ export function isCodexRestartResponse(value: unknown): value is CodexRestartRes
     if (!isPidList(d.stopped) || !isPidList(d.surviving)) return false;
     if (d.relaunch !== "started" && d.relaunch !== "skipped") return false;
     if (d.reason !== undefined && typeof d.reason !== "string") return false;
+    if (d.pickerState !== undefined
+      && (typeof d.pickerState !== "string" || !DESKTOP_PICKER_STATES.includes(d.pickerState))) return false;
     // A started relaunch cannot have left anything behind: the ladder refuses to
     // relaunch beside a survivor precisely so a second shell never appears.
     if (d.relaunch === "started" && (d.surviving as number[]).length > 0) return false;

package/src/lib/desktop-upstream-tunnel.ts

@@ -1,10 +1,10 @@
-import { connect as tcpConnect, isIP, type Socket } from "node:net";
-import { checkServerIdentity, connect as tlsConnect, type TLSSocket } from "node:tls";
+import { connect as tcpConnect, type Socket } from "node:net";
+import { connect as tlsConnect, type TLSSocket } from "node:tls";
 import { desktopProxyFor } from "./desktop-proxy-route";
-import { socks5Credentials, socks5Handshake } from "./socks5-handshake";
+import { dialTunnel, type OpaqueProxyRoute } from "./opaque-proxy-tunnel";
 
-// Shares the SOCKS exchange extracted by lcxhh521 in PR #5947 (efdccdbfac3f).
-// Lifecycle here additionally bounds the entire dial and handles close/abort/header limits.
+// The shared opaque dialer owns proxy framing; this caller owns fixed-target
+// TLS and bounds the entire connection, including the target TLS handshake.
 export interface DesktopTunnelOptions {
   proxy?: string | false;
   signal?: AbortSignal;
@@ -15,37 +15,6 @@ export interface DesktopTunnelOptions {
   proxyCa?: string;
 }
 const fail = () => new Error("desktop_upstream_connection_failed");
-class HandshakeReader {
-  private buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
-  private failure: Error | null = null;
-  private waiting: { ready: () => boolean; resolve: () => void; reject: (error: Error) => void } | null = null;
-  private onData = (chunk: Buffer) => {
-    if (this.buffer.length + chunk.length > 65536) { this.onFailure(); return; }
-    this.buffer = Buffer.concat([this.buffer, chunk]);
-    if (this.waiting?.ready()) { const current = this.waiting; this.waiting = null; current.resolve(); }
-  };
-  private onFailure = () => { this.failure = fail(); const current = this.waiting; this.waiting = null; current?.reject(this.failure); };
-  constructor(private socket: Socket, private signal: AbortSignal) {
-    socket.on("data", this.onData); socket.once("error", this.onFailure); socket.once("end", this.onFailure); socket.once("close", this.onFailure);
-    signal.addEventListener("abort", this.onFailure, { once: true }); if (signal.aborted) this.onFailure(); socket.resume();
-  }
-  write(bytes: Uint8Array | string): void { if (this.failure) throw this.failure; this.socket.write(bytes); }
-  private async until(ready: () => boolean): Promise<void> {
-    if (this.failure) throw this.failure;
-    if (ready()) return;
-    if (this.waiting) throw fail();
-    await new Promise<void>((resolve, reject) => { this.waiting = { ready, resolve, reject }; });
-  }
-  private take(length: number): Buffer { const out = this.buffer.subarray(0, length); this.buffer = this.buffer.subarray(length); return out; }
-  async readExact(length: number): Promise<Buffer> { await this.until(() => this.buffer.length >= length); return this.take(length); }
-  async readHead(): Promise<string> { await this.until(() => this.buffer.indexOf("\r\n\r\n") >= 0); return this.take(this.buffer.indexOf("\r\n\r\n") + 4).toString("latin1"); }
-  dispose(): void {
-    this.socket.pause(); this.socket.removeListener("data", this.onData); this.socket.removeListener("error", this.onFailure);
-    this.socket.removeListener("end", this.onFailure); this.socket.removeListener("close", this.onFailure);
-    this.signal.removeEventListener("abort", this.onFailure);
-    if (this.buffer.length) this.socket.unshift(this.buffer); this.buffer = Buffer.alloc(0); this.onFailure();
-  }
-}
 function waitConnected(socket: Socket, event: "connect" | "secureConnect", signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     const dispose = () => { socket.off(event, done); socket.off("error", failure); socket.off("close", failure); signal.removeEventListener("abort", failure); };
@@ -76,25 +45,21 @@ export async function dialDesktopUpstream(options: DesktopTunnelOptions = {}): P
       const url = new URL(proxy), protocol = url.protocol;
       if (!["http:", "https:", "socks5:", "socks5h:"].includes(protocol) || !url.hostname || url.search || url.hash || url.pathname !== "" && url.pathname !== "/") throw fail();
       const host = url.hostname.replace(/^\[|\]$/g, ""), port = Number(url.port) || (protocol === "https:" ? 443 : protocol.startsWith("socks") ? 1080 : 80);
-      raw = own(tcpConnect({ host, port })); await waitConnected(raw, "connect", signal);
-      if (protocol === "https:") {
-        raw = own(tlsConnect({ socket: raw, servername: isIP(host) ? undefined : host, ca: options.proxyCa,
-          rejectUnauthorized: true, checkServerIdentity: (_name, certificate) => checkServerIdentity(host, certificate), ALPNProtocols: ["http/1.1"] }));
-        await waitConnected(raw, "secureConnect", signal);
-      }
-      const reader = new HandshakeReader(raw, signal);
-      try {
-        if (protocol.startsWith("socks")) await socks5Handshake(reader, target, socks5Credentials(url));
-        else {
-          const authority = `${target.host}:${target.port}`;
-          const lines = [`CONNECT ${authority} HTTP/1.1`, `Host: ${authority}`];
-          if (url.username || url.password) lines.push(`Proxy-Authorization: Basic ${Buffer.from(`${decodeURIComponent(url.username)}:${decodeURIComponent(url.password)}`).toString("base64")}`);
-          reader.write(lines.join("\r\n") + "\r\n\r\n");
-          if (!/^HTTP\/1\.[01] 2\d\d(?: |\r)/.test(await reader.readHead())) throw fail();
-        }
-      } finally { reader.dispose(); }
+      const credentials = url.username || url.password
+        ? { username: decodeURIComponent(url.username), password: decodeURIComponent(url.password) }
+        : {};
+      const endpoint = { host, port, ...credentials };
+      const route: OpaqueProxyRoute = protocol === "https:"
+        ? { ...endpoint, kind: "https", proxyCa: options.proxyCa }
+        : { ...endpoint, kind: protocol.slice(0, -1) as "http" | "socks5" | "socks5h" };
+      const authority = `${target.host.includes(":") ? `[${target.host}]` : target.host}:${target.port}`;
+      // The route resolver remains authoritative; a failed proxy never becomes DIRECT.
+      raw = own(await dialTunnel(authority, route, { signal, timeoutMs: timeout, maxHeaderBytes: 65536 }));
     }
     if (signal.aborted || raw.destroyed) throw fail();
+    // This consumer historically closes its writable side after peer EOF. The
+    // shared opaque transport preserves half-closes for callers that need them.
+    raw.allowHalfOpen = false;
     const secured = own(tlsConnect({ socket: raw, servername: "chatgpt.com", ca: options.ca, rejectUnauthorized: true, ALPNProtocols: ["http/1.1"] }));
     // The CONNECT reader paused its stream before handing buffered bytes back. Bun's
     // TLS-over-TLS path needs the outer TLS stream explicitly resumed for the new handshake.

package/src/lib/empty-tool-catalog.ts

@@ -0,0 +1,62 @@
+import { normalizeDeclaredToolName, type AdapterEvent } from "../types";
+import { UNDECLARED_TOOL_CALL_ERROR_CODE } from "./errors";
+import { releaseTranslatedEvent, type TranslatorBudget } from "./translator-budget";
+import { releaseCompactionCiphertextLease } from "../responses/compaction";
+
+/** Snapshot of current-turn declarations when an explicit empty catalog activates enforcement. */
+export interface ClientToolCatalogRestriction {
+  declaredToolNames: ReadonlySet<string>;
+  bareCustomToolNames: ReadonlySet<string>;
+}
+
+export function emptyToolCatalogRefusal(
+  event: AdapterEvent,
+  catalog: ClientToolCatalogRestriction | undefined,
+): Extract<AdapterEvent, { type: "error" }> | undefined {
+  if (!catalog) return;
+  if (event.type === "tool_call_start") {
+    const name = normalizeDeclaredToolName(event.name, catalog.declaredToolNames, undefined, catalog.bareCustomToolNames);
+    if (catalog.declaredToolNames.has(name)) return;
+  } else if (catalog.declaredToolNames.size !== 0
+    || (event.type !== "tool_call_delta" && event.type !== "tool_call_end")) return;
+  return {
+    type: "error", status: 502, errorType: "upstream_error", code: UNDECLARED_TOOL_CALL_ERROR_CODE,
+    message: "routed provider emitted a client tool call outside the current request's explicit tool catalog",
+  };
+}
+
+/** Runs after hosted tool loops, before client delivery and continuation-state folding. */
+export async function* guardEmptyToolCatalogStream(
+  events: AsyncIterable<AdapterEvent>,
+  catalog: ClientToolCatalogRestriction | undefined,
+  budget: TranslatorBudget,
+): AsyncGenerator<AdapterEvent> {
+  for await (const event of events) {
+    const refusal = emptyToolCatalogRefusal(event, catalog);
+    if (refusal) {
+      releaseTranslatedEvent(event, budget);
+      releaseCompactionCiphertextLease(event, budget);
+    }
+    yield refusal ?? event;
+    if (refusal) return;
+  }
+}
+
+export function guardEmptyToolCatalogEvents(
+  events: AdapterEvent[],
+  catalog: ClientToolCatalogRestriction | undefined,
+  budget: TranslatorBudget,
+): AdapterEvent[] {
+  if (!catalog) return events;
+  const index = events.findIndex(event => emptyToolCatalogRefusal(event, catalog) !== undefined);
+  if (index < 0) return events;
+  const refusal = emptyToolCatalogRefusal(events[index]!, catalog)!;
+  for (const event of events.slice(index)) {
+    if ((event.type === "done" || event.type === "incomplete" || event.type === "error") && event.usage) {
+      refusal.usage = event.usage;
+    }
+    releaseTranslatedEvent(event, budget);
+    releaseCompactionCiphertextLease(event, budget);
+  }
+  return [...events.slice(0, index), refusal];
+}