@bitkyc08/opencodex 2.86.0 → 2.87.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

@@ -20,6 +20,7 @@ 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";
@@ -39,6 +40,7 @@ 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 +243,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") {
@@ -286,6 +292,7 @@ class LoopError extends Error {
  */
 export interface ImageBridgeDeps {
   parsed: OcxParsedRequest;
+  clientToolCatalogRestriction?: ClientToolCatalogRestriction;
   adapter: ProviderAdapter;
   incomingMeta: IncomingMeta;
   plan?: ImageBridgePlan;
@@ -319,6 +326,12 @@ export interface ImageBridgeDeps {
   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 +366,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 +392,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 => {
@@ -569,6 +588,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);
         }
@@ -709,6 +729,10 @@ 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" };
@@ -772,6 +796,8 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           signal,
           inactivityTimeoutMs: stallTimeoutMs,
           translatorBudget,
+          // A pass that fails was still billed; the error terminal below reports it with the hidden passes.
+          onErrorUsage: usage => { hiddenUsage = addUsage(hiddenUsage, usage); },
         })) {
           if (event.type === "heartbeat") yield event;
           else {
@@ -863,13 +889,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 +911,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 +1086,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 +1095,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 } : {}),
+              ...(usage ? { usage } : {}),
             };
           }
           return;
@@ -1079,13 +1115,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 +1131,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];
+}

package/src/lib/errors.ts

@@ -650,10 +650,22 @@ export function adapterFailureFromMessage(message: string): { httpStatus: number
   return { httpStatus, error };
 }
 
+/** A declared client refusal: retrying the identical request cannot change the verdict. */
+const CLIENT_ERROR_STATUS: Record<string, 400 | 401 | 403 | 404> = {
+  invalid_request_error: 400,
+  authentication_error: 401,
+  permission_error: 403,
+  not_found_error: 404,
+};
+
 /** Narrow structured classes carried through a synthesized bare-error terminal. */
 export function recognizedUpstreamError(error: { type?: unknown; code?: unknown }):
-  { type: string; code: string; httpStatus: 429 | 503 } | undefined {
+  { type: string; code: string; httpStatus: 400 | 401 | 403 | 404 | 429 | 503 } | undefined {
   const code = typeof error.code === "string" ? error.code : undefined;
+  const clientClass = code ?? (typeof error.type === "string" ? error.type : undefined);
+  if (clientClass !== undefined && Object.hasOwn(CLIENT_ERROR_STATUS, clientClass)) {
+    return { type: clientClass, code: clientClass, httpStatus: CLIENT_ERROR_STATUS[clientClass] };
+  }
   // An explicit unknown code must not gain a recognized class from its type or copy.
   if (code !== undefined && !["rate_limit_exceeded", "rate_limit_error", "server_is_overloaded", "overloaded_error"].includes(code)) return undefined;
   if (code === "rate_limit_exceeded" || code === "rate_limit_error"
@@ -680,8 +692,13 @@ export function httpStatusFromTerminalError(error: {
   if (isCyberPolicyCode(error.code) || (error.message ? isCyberPolicyMessage(error.message) : false)) {
     return 400;
   }
+  const message = error.message ?? "";
   const recognized = recognizedUpstreamError(error);
-  if (recognized) return recognized.httpStatus;
+  // Client-closed messages often arrive as invalid_request_error after classifyError, so a
+  // recognized 400 yields to the client-closed check below; every other class keeps its order.
+  if (recognized && !(recognized.httpStatus === 400 && message && isClientClosedMessage(message))) {
+    return recognized.httpStatus;
+  }
   if (error.type === "rate_limit_error" || error.code === "rate_limit_exceeded") return 429;
   if (error.type === "authentication_error" || error.code === "invalid_api_key") return 401;
   if (
@@ -693,7 +710,6 @@ export function httpStatusFromTerminalError(error: {
   if (error.type === "server_error" && error.code === "server_is_overloaded") return 503;
   // Client-closed messages often arrive as invalid_request_error after classifyError; check message
   // before treating every invalid_request_error as HTTP 400.
-  const message = error.message ?? "";
   if (message && isClientClosedMessage(message)) return 499;
   if (error.type === "invalid_request_error") return 400;
   if (error.type === "proxy_error") return 500;

package/src/lib/gcp-adc.ts

@@ -2,6 +2,10 @@
  * Application Default Credentials (ADC) resolution for Vertex AI.
  *
  * Direct WebCrypto + REST implementation (no `google-auth-library`). Sources, in priority order:
+ *   0. A `gcp-sa:<account>` reference (the provider's active key resolving to one) → the Service
+ *      Account / authorized_user JSON stored in the OS credential store under that account
+ *      (`keychain:<account>` secret, written by the key-store save path when the user pastes a
+ *      credential JSON directly into the API-key slot). See resolveGcpCredentialMarker.
  *   1. `GOOGLE_APPLICATION_CREDENTIALS` env → file with `type: "service_account"` (RS256 JWT
  *      exchange) or `type: "authorized_user"` (refresh-token exchange).
  *   2. gcloud user ADC (`CLOUDSDK_CONFIG`, else `%APPDATA%\gcloud` on Windows, else
@@ -18,6 +22,8 @@ import { Buffer } from "node:buffer";
 import * as os from "node:os";
 import * as path from "node:path";
 import { readFileSync, existsSync, statSync } from "node:fs";
+import { GCP_CREDENTIAL_MARKER_PREFIX, providerKeychainEntry } from "../providers/api-key-resolve";
+export { isGcpCredentialMaterial } from "./gcp-credential-input";
 import {
   captureConfigGeneration,
   sweepExpiredOnWrite,
@@ -36,6 +42,50 @@ const TOKEN_TIMEOUT_MS = 15_000;
 const TOKEN_ATTEMPTS = 3;
 const TOKEN_RETRY_BASE_MS = 300;
 
+/**
+ * Reference prefix stored in `provider.apiKey` (and `apiKeyPool` entries) when the user pastes a
+ * GCP credential JSON directly into an API-key slot. The secret JSON lives in the OS credential
+ * store under the same service the `keychain:` references use; only the marker is persisted to
+ * `config.json`. The leaf reference prefix also identifies already-stored material for migration.
+ */
+export { GCP_CREDENTIAL_MARKER_PREFIX } from "../providers/api-key-resolve";
+
+/** Extract a marker account; malformed explicit markers never opt into host ADC. */
+export function gcpCredentialMarkerAccount(value: string | undefined): string | undefined {
+  if (typeof value !== "string" || !value.startsWith(GCP_CREDENTIAL_MARKER_PREFIX)) return undefined;
+  const account = value.slice(GCP_CREDENTIAL_MARKER_PREFIX.length);
+  if (!account.trim()) throw new Error("GCP credential marker requires a non-empty account");
+  return account;
+}
+
+/**
+ * Whether a pasted API-key value is in fact a GCP credential JSON. Used by the save path to
+ * divert JSON material out of the literal-key flow before it reaches `config.json`. Deliberately
+ * strict: only a `type` field with a known ADC credential type counts, so a user's literal API
+ * key that happens to start with `{` is never eaten.
+ */
+export function parseGcpCredentialJson(value: string): AdcFileCredentials | undefined {
+  const trimmed = (value ?? "").trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+    if (parsed?.type === "service_account") {
+      if (typeof parsed.client_email !== "string" || !parsed.client_email.trim()) return undefined;
+      if (typeof parsed.private_key !== "string" || !parsed.private_key.trim()) return undefined;
+      return parsed as unknown as AdcFileCredentials;
+    }
+    if (parsed?.type === "authorized_user") {
+      if (typeof parsed.client_id !== "string" || !parsed.client_id.trim()) return undefined;
+      if (typeof parsed.client_secret !== "string" || !parsed.client_secret.trim()) return undefined;
+      if (typeof parsed.refresh_token !== "string" || !parsed.refresh_token.trim()) return undefined;
+      return parsed as unknown as AdcFileCredentials;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 interface CachedToken {
   token: string;
   expiresAtMs: number;
@@ -81,7 +131,10 @@ export function sweepExpiredGcpAdcTokens(now = Date.now()): number {
 
 export function reconcileGcpAdcTokens(context: GenerationContext): number {
   if (context.generation <= lastReconciledGeneration) return 0;
-  const currentSource = currentAdcSourceKey();
+  // The periodic sweep registration has no request context, so no marker is active here: markers
+  // travel per-request via getVertexAccessToken(options.markerAccount), and a marker-token cache
+  // entry whose account no longer resolves is simply pruned by this sweep when it expires.
+  const currentSource = currentAdcSourceKey(undefined);
   let removed = 0;
   for (const source of tokenCache.keys()) {
     if (source === currentSource) continue;
@@ -131,7 +184,29 @@ function readJsonFile<T>(filePath: string): T | undefined {
   return JSON.parse(readFileSync(filePath, "utf8")) as T;
 }
 
-function loadAdcCredentials(): { source: string; creds: AdcFileCredentials } | undefined {
+/**
+ * Read the credential JSON for a `gcp-sa:<account>` marker from the OS credential store. Uses the
+ * same service name and the same injectable entry factory as the `keychain:` API-key references
+ * (api-key-resolve.providerKeychainEntry), so one probe surface and one test seam cover both.
+ * Mirrors `readKeychain`'s fail-closed policy: an unreadable entry yields no credential (the
+ * caller surfaces the failure instead of silently falling through to the next ADC source).
+ */
+function readMarkerCredential(account: string): AdcFileCredentials | undefined {
+  try {
+    const raw = providerKeychainEntry(account).getPassword();
+    if (typeof raw !== "string" || !raw.trim()) return undefined;
+    return parseGcpCredentialJson(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function loadAdcCredentials(markerAccount: string | undefined): { source: string; creds: AdcFileCredentials } | undefined {
+  if (markerAccount) {
+    const creds = readMarkerCredential(markerAccount);
+    if (!creds) throw new Error("GCP credential marker is set but its credential could not be read from the OS credential store");
+    return { source: `marker:${markerAccount}`, creds };
+  }
   const gacPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
   if (gacPath) {
     const creds = readJsonFile<AdcFileCredentials>(gacPath);
@@ -148,9 +223,10 @@ function loadAdcCredentials(): { source: string; creds: AdcFileCredentials } | u
  * The cache key for the source the NEXT resolve would use, computed cheaply (no network). Lets the
  * cache return a token only when it still matches the active credential source, so an in-process
  * change to GOOGLE_APPLICATION_CREDENTIALS (or the user ADC file) does not keep serving a stale
- * token from a different source. Falls back to "metadata" when no file/env ADC is present.
+ * token from a different source. Falls back to "metadata" when no marker/file/env ADC is present.
  */
-function currentAdcSourceKey(): string {
+function currentAdcSourceKey(markerAccount: string | undefined): string {
+  if (markerAccount) return `marker:${markerAccount}`;
   const gacPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
   if (gacPath) return fileSourceTag("gac", gacPath);
   const userPath = userAdcPath();
@@ -279,8 +355,8 @@ async function fetchMetadataToken(signal: AbortSignal | undefined, fetchImpl: Fe
   }
 }
 
-async function resolveAccessTokenUncached(signal: AbortSignal | undefined, fetchImpl: FetchImpl): Promise<{ source: string; token: TokenResponse }> {
-  const adc = loadAdcCredentials();
+async function resolveAccessTokenUncached(markerAccount: string | undefined, signal: AbortSignal | undefined, fetchImpl: FetchImpl): Promise<{ source: string; token: TokenResponse }> {
+  const adc = loadAdcCredentials(markerAccount);
   if (adc) {
     const token = adc.creds.type === "service_account"
       ? await exchangeJwtForToken(adc.creds, signal, fetchImpl)
@@ -295,14 +371,25 @@ async function resolveAccessTokenUncached(signal: AbortSignal | undefined, fetch
 }
 
 /** Returns a Bearer access token for the `Authorization` header on Vertex AI calls (cached + refreshed). */
-export async function getVertexAccessToken(options?: { signal?: AbortSignal; fetch?: FetchImpl }): Promise<string> {
+export async function getVertexAccessToken(options?: { signal?: AbortSignal; fetch?: FetchImpl; markerAccount?: string }): Promise<string> {
+  // The marker travels as an argument, never as process-global state: a module-level "active
+  // marker" written by the router would race across concurrent requests for different providers
+  // and could resolve one provider's Vertex call with another provider's service account. The
+  // adapter passes `gcpCredentialMarkerAccount(provider.apiKey)` per request instead.
+  const markerAccount = options?.markerAccount;
   const fetchImpl = options?.fetch ?? globalThis.fetch.bind(globalThis);
   const skew = getRefreshSkewMs();
   const now = Date.now();
 
   // Only serve a cached token that matches the source the next resolve would actually use; prune
   // expired or now-stale (different-source) entries so a credential-source change is honored.
-  const expectedSource = currentAdcSourceKey();
+  const expectedSource = currentAdcSourceKey(markerAccount);
+  // A cached bearer token is usable only while the explicitly selected store entry remains
+  // readable. Removal or a locked store must fail closed before the cache can return it.
+  if (markerAccount && !readMarkerCredential(markerAccount)) {
+    tokenCache.delete(expectedSource);
+    throw new Error("GCP credential marker is set but its credential could not be read from the OS credential store");
+  }
   const writerGeneration = captureConfigGeneration();
   for (const [source, cached] of tokenCache) {
     if (source === expectedSource && cached.expiresAtMs - skew > now) return cached.token;
@@ -317,7 +404,7 @@ export async function getVertexAccessToken(options?: { signal?: AbortSignal; fet
 
   const promise = (async () => {
     try {
-      const { source, token } = await resolveAccessTokenUncached(options?.signal, fetchImpl);
+      const { source, token } = await resolveAccessTokenUncached(markerAccount, options?.signal, fetchImpl);
       const expiresAtMs = Date.now() + Math.max(0, token.expires_in * 1000);
       if (writerGeneration >= lastReconciledGeneration || liveSources.has(source)) {
         tokenCache.set(source, { token: token.access_token, expiresAtMs });