@bitkyc08/opencodex 2.25.0 → 2.26.0

package/src/adapters/openai-responses.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { IncomingMeta, ProviderAdapter } from "./base";
-import { namespacedToolName, type AdapterEvent, type OcxParsedRequest, type OcxProviderConfig, type OcxUsage } from "../types";
+import { namespacedToolName, type AdapterEvent, type OcxParsedRequest, type OcxProviderConfig, type OcxUsage, type TierDecision } from "../types";
 import { catalogModelSupportsReasoningSummaries } from "../codex/catalog";
 import { COMPACT_PROMPT, decodeCompactionSummary, SUMMARY_PREFIX } from "../responses/compaction";
 import { collectResponsesToolGroups } from "../responses/tool-groups";
@@ -12,6 +12,9 @@ import { modelRecordValue } from "../reasoning-effort";
 import type { TranslatorBudget } from "../lib/translator-budget";
 import { rewriteRoutedCustomToolsForUpstream } from "../responses/custom-tool-compat";
 import { openaiResponsesUrl } from "./openai-responses-url";
+import {
+  createAdapterTierMetadata,
+} from "../providers/fastwire";
 
 // Headers relayed verbatim from the caller in OAuth-passthrough ("forward") mode.
 // Exported so the web-search sidecar reuses the exact same forwarded-auth set for its ChatGPT call.
@@ -572,6 +575,15 @@ function toolOutputText(output: unknown): string {
  * expansion misses (proxy restart, unrecorded prior turn), previous_response_id is stripped
  * (the ChatGPT backend rejects it), so the delta may carry items that reference now-absent
  * prior items and 400 upstream:
+ * - `function_call`/`local_shell_call`/`custom_tool_call` without their paired output item
+ *   ("No tool output found for tool call <call_id>"). A stateless upstream cannot resolve
+ *   the pair from its own storage, so a placeholder output is synthesized to keep the
+ *   turn continuable without pretending the result was real. Synthetic outputs are
+ *   emitted after the complete parallel call batch, in call order alongside any real
+ *   outputs, so the adjacency normalizer can still recognize the batch as one
+ *   reasoning-bearing assistant turn (#1477). Gated on
+ *   `synthesizeMissingCallOutputs` (stateless AND non-forward wires); forward replay keeps
+ *   fail-closed behavior.
  * - `function_call_output`/`custom_tool_call_output` without their paired call item
  *   ("No tool call found for function call output with call_id ..."). Converted to user
  *   messages so the result text survives. `function_call_output` also pairs with
@@ -608,26 +620,38 @@ function backfillWebSearchQueries(body: unknown): unknown {
   return changed ? { ...body, input } : body;
 }
 
-function repairOrphanedInputItems(body: unknown, dropReasoning: boolean): unknown {
+function repairOrphanedInputItems(body: unknown, dropReasoning: boolean, synthesizeMissingCallOutputs = false): unknown {
   if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
   const input = body.input;
 
   const functionCallIds = new Set<string>();
   const customCallIds = new Set<string>();
+  const functionOutputIds = new Set<string>();
+  const customOutputIds = new Set<string>();
   for (const item of input) {
     if (!isPlainObject(item) || typeof item.call_id !== "string") continue;
     if (item.type === "function_call" || item.type === "local_shell_call") functionCallIds.add(item.call_id);
     else if (item.type === "custom_tool_call") customCallIds.add(item.call_id);
+    else if (item.type === "function_call_output") functionOutputIds.add(item.call_id);
+    else if (item.type === "custom_tool_call_output") customOutputIds.add(item.call_id);
   }
 
   let changed = false;
   const repaired: unknown[] = [];
+  const syntheticKeys = new Set<string>();
+  const pendingSyntheticOutputs: unknown[] = [];
+  const flushPendingSyntheticOutputs = (): void => {
+    if (pendingSyntheticOutputs.length === 0) return;
+    repaired.push(...pendingSyntheticOutputs);
+    pendingSyntheticOutputs.length = 0;
+  };
   for (const item of input) {
-    if (!isPlainObject(item)) { repaired.push(item); continue; }
+    if (!isPlainObject(item)) { flushPendingSyntheticOutputs(); repaired.push(item); continue; }
     if (dropReasoning && item.type === "reasoning") { changed = true; continue; }
     const isFnOutput = item.type === "function_call_output";
     const isCustomOutput = item.type === "custom_tool_call_output";
     if (isFnOutput || isCustomOutput) {
+      flushPendingSyntheticOutputs();
       const callId = typeof item.call_id === "string" ? item.call_id : "";
       const paired = isFnOutput ? functionCallIds.has(callId) : customCallIds.has(callId);
       if (!paired) {
@@ -640,10 +664,83 @@ function repairOrphanedInputItems(body: unknown, dropReasoning: boolean): unknow
         continue;
       }
     }
+    const isFnCall = item.type === "function_call" || item.type === "local_shell_call";
+    const isCustomCall = item.type === "custom_tool_call";
+    if (isFnCall || isCustomCall) {
+      repaired.push(item);
+      if (synthesizeMissingCallOutputs) {
+        const callId = typeof item.call_id === "string" ? item.call_id : "";
+        const hasOutput = isFnCall ? functionOutputIds.has(callId) : customOutputIds.has(callId);
+        if (!hasOutput && callId) {
+          changed = true;
+          const name = typeof item.name === "string" && item.name.length > 0 ? item.name : callId;
+          const text = `[ocx] no tool result was recorded for "${name}"; execution status unknown — do not treat this as success, failure, or user-provided input.`;
+          syntheticKeys.add(`${isFnCall ? "function" : "custom"}:${callId}`);
+          pendingSyntheticOutputs.push(isFnCall
+            ? { type: "function_call_output", call_id: callId, output: text }
+            : { type: "custom_tool_call_output", call_id: callId, output: text });
+        }
+      }
+      continue;
+    }
+    flushPendingSyntheticOutputs();
     repaired.push(item);
   }
+  flushPendingSyntheticOutputs();
+
+  const callKeyOf = (item: unknown): string | null => {
+    if (!isPlainObject(item) || typeof item.call_id !== "string") return null;
+    if (item.type === "function_call" || item.type === "local_shell_call") return `function:${item.call_id}`;
+    if (item.type === "custom_tool_call") return `custom:${item.call_id}`;
+    return null;
+  };
+  const outputKeyOf = (item: unknown): string | null => {
+    if (!isPlainObject(item) || typeof item.call_id !== "string") return null;
+    if (item.type === "function_call_output") return `function:${item.call_id}`;
+    if (item.type === "custom_tool_call_output") return `custom:${item.call_id}`;
+    return null;
+  };
+  const reorderBatchOutputs = (items: unknown[]): unknown[] => {
+    const ordered: unknown[] = [];
+    let index = 0;
+    while (index < items.length) {
+      const key = callKeyOf(items[index]);
+      if (key === null) { ordered.push(items[index]); index += 1; continue; }
+      const batch: unknown[] = [];
+      const batchKeys: string[] = [];
+      let cursor = index;
+      while (cursor < items.length) {
+        const nextKey = callKeyOf(items[cursor]);
+        if (nextKey === null) break;
+        batch.push(items[cursor]);
+        batchKeys.push(nextKey);
+        cursor += 1;
+      }
+      const hasSynthetic = batchKeys.some(batchKey => syntheticKeys.has(batchKey));
+      if (!hasSynthetic) {
+        ordered.push(...batch);
+        index = cursor;
+        continue;
+      }
+      const remainder: unknown[] = [];
+      const batchOutputs: Array<{ key: string; item: unknown }> = [];
+      for (let probe = cursor; probe < items.length; probe += 1) {
+        const outputKey = outputKeyOf(items[probe]);
+        if (outputKey !== null && batchKeys.includes(outputKey)) {
+          batchOutputs.push({ key: outputKey, item: items[probe] });
+        } else {
+          remainder.push(items[probe]);
+        }
+      }
+      batchOutputs.sort((left, right) => batchKeys.indexOf(left.key) - batchKeys.indexOf(right.key));
+      ordered.push(...batch, ...batchOutputs.map(output => output.item));
+      ordered.push(...reorderBatchOutputs(remainder));
+      return ordered;
+    }
+    return ordered;
+  };
 
-  return changed ? { ...body, input: repaired } : body;
+  return changed ? { ...body, input: reorderBatchOutputs(repaired) } : body;
 }
 
 /**
@@ -764,6 +861,15 @@ function stripPreviousResponseId(body: unknown, strip: boolean): unknown {
   return rest;
 }
 
+/** Apply the settled tier only to a fresh outbound object; `_rawBody` remains caller-owned. */
+function applyTierDecisionToResponsesBody(body: unknown, decision: TierDecision | undefined): unknown {
+  if (!decision || decision.kind === "forward-caller" || !isPlainObject(body)) return body;
+  const next: Record<string, unknown> = { ...body };
+  if (decision.kind === "set") next.service_tier = decision.value;
+  else delete next.service_tier;
+  return next;
+}
+
 /**
  * Drop request parameters a stateless Responses upstream cannot implement, and pin
  * `store` false.
@@ -778,8 +884,8 @@ function stripPreviousResponseId(body: unknown, strip: boolean): unknown {
  * `prompt` is a reference to a server-stored prompt template — the most stateful
  * field in the accepted schema.
  *
- * `service_tier` is deliberately NOT dropped: the server writes it for fast mode
- * (`responses/core.ts`), and silently deleting a configured knob inside an adapter is
+ * `service_tier` is deliberately NOT dropped: the final TierDecision is applied to a
+ * detached outbound body before this sanitizer chain, and silently deleting a configured knob is
  * worse than forwarding a parameter the upstream ignores.
  *
  * MUST run before the composed sanitize chain below: `stripItemIdsWhenUnstored` keys
@@ -1367,6 +1473,9 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         parsed._rawBody,
         forward || parsed._previousResponseInputExpanded === true,
       );
+      // stripPreviousResponseId() intentionally returns its input on a no-op. Detach before the
+      // tier write so a force-fast/default decision can never mutate parsed._rawBody.
+      outBody = applyTierDecisionToResponsesBody(outBody, parsed.options?.tierDecision);
       const stateless = provider.statelessResponses === true;
       if (stateless) outBody = stripStatefulResponsesParams(outBody);
       // A replay miss can leave a function_call_output whose paired function_call sat
@@ -1375,7 +1484,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       // backend gets — dropping previous_response_id is not much use if the body that
       // reaches the wire is unparseable.
       if (forward || stateless) {
-        outBody = repairOrphanedInputItems(outBody, unexpandedMiss);
+        outBody = repairOrphanedInputItems(outBody, unexpandedMiss, stateless && !forward);
       }
       if (provider.requiresAdjacentResponsesToolResults === true) {
         outBody = normalizeResponsesToolResultAdjacency(outBody);
@@ -1414,11 +1523,21 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         convertedRoutedCustomToolNames = rewritten.names;
       }
       const sanitizedBody = normalizeToolSchemas(stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody), { preserveRawReasoningContent: provider.preserveResponsesReasoningContent === true })))))));
-      const body = JSON.stringify(stripDisabledReasoningSummaries(
+      const finalBody = stripDisabledReasoningSummaries(
         normalizeConfiguredReasoningSummaryDelivery(sanitizedBody, provider, parsed.modelId),
         provider,
         parsed.modelId,
-      ));
+      );
+      const actualServiceTier = isPlainObject(finalBody) && typeof finalBody.service_tier === "string"
+        ? finalBody.service_tier
+        : null;
+      const tierLog = createAdapterTierMetadata(
+        parsed.options?.tierObservation,
+        parsed.options?.tierDecision,
+        actualServiceTier === null ? null : "service-tier",
+        actualServiceTier,
+      );
+      const body = JSON.stringify(finalBody);
       const releaseBodyObservation = translatorBudget.observeExternallyCapped(
         "passthrough_serialization",
         new TextEncoder().encode(body).byteLength,
@@ -1430,6 +1549,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         body,
         releaseBodyObservation,
         ...(convertedRoutedCustomToolNames ? { convertedRoutedCustomToolNames } : {}),
+        ...(tierLog ? { tierLog } : {}),
       };
     },
 

package/src/adapters/registry.ts

@@ -10,6 +10,7 @@ import { createMimoFreeAdapter } from "./mimo-free";
 import { createOpenAIChatAdapter } from "./openai-chat";
 import { createResponsesPassthroughAdapter } from "./openai-responses";
 import type { OcxProviderConfig } from "../types";
+import { createAdapterTierMetadata } from "../providers/fastwire";
 
 export type AdapterCacheRetention = "none" | "short" | "long";
 
@@ -142,5 +143,33 @@ export function createRegisteredAdapter(
 ): ProviderAdapter {
   const definition = getAdapterDefinition(provider.adapter);
   if (!definition) throw new Error(`Unknown adapter: ${provider.adapter}`);
-  return definition.create(provider, context);
+  const adapter = definition.create(provider, context);
+  const buildRequest = adapter.buildRequest.bind(adapter);
+  adapter.buildRequest = (parsed, incoming) => {
+    const attachTierMetadata = (request: Awaited<ReturnType<ProviderAdapter["buildRequest"]>>) => {
+      // OpenAI-family adapters report the exact emitted field themselves. Other adapters
+      // still report an exact absence at this serialization boundary, which makes a routed
+      // Fast downgrade observable without asking core to infer an outbound body shape.
+      request.tierLog ??= createAdapterTierMetadata(
+        parsed.options.tierObservation,
+        parsed.options.tierDecision,
+        null,
+        null,
+      );
+      return request;
+    };
+    const request = buildRequest(parsed, incoming);
+    return request instanceof Promise
+      ? request.then(attachTierMetadata)
+      : attachTierMetadata(request);
+  };
+  if (adapter.runTurn && !adapter.tierLogForRunTurn) {
+    adapter.tierLogForRunTurn = parsed => createAdapterTierMetadata(
+      parsed.options.tierObservation,
+      parsed.options.tierDecision,
+      null,
+      null,
+    );
+  }
+  return adapter;
 }

package/src/bridge.ts

@@ -15,6 +15,7 @@ import { rememberReasoningForCall } from "./responses/reasoning-replay-cache";
 import {
   rememberAndSerializeExtraContent,
   rememberExtraContentForReplay,
+  awaitThoughtSignatureDurability,
 } from "./responses/thought-signature-replay";
 import { resolveStallTimeoutSec } from "./stall-timeout";
 import { usageDisplayTotalTokens } from "./usage/totals";
@@ -198,6 +199,16 @@ export function bridgeToResponsesSSE(
     declaredToolNames?: ReadonlySet<string>;
     /** Declared parameter schema per tool name; repairs integral-float integer args (#1611). */
     toolParameterSchemas?: ReadonlyMap<string, Record<string, unknown>>;
+    /**
+     * Wire keep-alive shape. Codex-rs parses at the EVENT level (timeout(idle_timeout,
+     * stream.next()) over an eventsource_stream), so an SSE comment line dispatches no event
+     * and does NOT re-arm its idle timer — the keep-alive must be a typed frame the parser
+     * ignores via its catch-all (110 RCA, 30_patch-direction.md). grok-build's strict
+     * async-openai fork is the opposite: it dies on the unknown `response.heartbeat`
+     * variant but, being eventsource-based at the byte level, its idle handling tolerates
+     * comment lines. Default stays the typed frame; the grok surface opts into comments.
+     */
+    heartbeatStyle?: "typed" | "comment";
     translatorBudget?: TranslatorBudget;
     /**
      * Conversation identity for the reasoning replay cache (issue #950).
@@ -326,10 +337,13 @@ export function bridgeToResponsesSSE(
     clearOwnedWatchdog();
   };
   // RC3 keep-alive: Codex's idle timer is timeout(idle_timeout, stream.next()) over an
-  // eventsource_stream; ANY received event re-arms it, while an unknown type is ignored
-  // (responses.rs `_ => Ok(None)`). Emit a parser-ignored `response.heartbeat` whenever the
-  // *wire* has been silent, even if invisible adapter heartbeats are still flowing (web-search
-  // buffering + raw-byte progress). Upstream activity only resets the stall watchdog.
+  // eventsource_stream, which parses at the EVENT level — a comment-only frame dispatches no
+  // event, so it does NOT re-arm the timer (110 RCA). The default keep-alive is therefore a
+  // typed `response.heartbeat` frame the codex-rs parser ignores via `_ => Ok(None)`. The
+  // grok surface (strict async-openai decoder that dies on unknown variants) opts into SSE
+  // comment lines instead via options.heartbeatStyle. Emit whenever the *wire* has been
+  // silent, even if invisible adapter heartbeats are still flowing (web-search buffering +
+  // raw-byte progress). Upstream activity only resets the stall watchdog.
   let upstreamActivity = false;
   let wireActivity = false;
   let beat: unknown;
@@ -396,7 +410,9 @@ export function bridgeToResponsesSSE(
         ...(endTurn !== undefined ? { end_turn: endTurn } : {}),
       });
 
-      const heartbeatFrame = encoder.encode('event: response.heartbeat\ndata: {"type":"response.heartbeat"}\n\n');
+      const heartbeatFrame = options?.heartbeatStyle === "comment"
+        ? encoder.encode(': opencodex heartbeat\n\n')
+        : encoder.encode('event: response.heartbeat\ndata: {"type":"response.heartbeat"}\n\n');
       let stallTicks = 0;
       const stallSec = resolveStallTimeoutSec(options?.stallTimeoutSec);
       const maxStallTicks = Math.ceil((stallSec * 1000) / heartbeatMs);
@@ -576,9 +592,16 @@ export function bridgeToResponsesSSE(
       const closeCurrentRawReasoning = () => {
         if (!currentRawReasoning) return;
         rawReasoningForNextToolCall = currentRawReasoning.text;
+        emit("response.reasoning_summary_text.done", {
+          item_id: currentRawReasoning.itemId, output_index: currentRawReasoning.outputIndex, summary_index: 0, text: currentRawReasoning.text,
+        });
+        emit("response.reasoning_summary_part.done", {
+          item_id: currentRawReasoning.itemId, output_index: currentRawReasoning.outputIndex, summary_index: 0,
+          part: { type: "summary_text", text: currentRawReasoning.text },
+        });
         const item = {
-          type: "reasoning", id: currentRawReasoning.itemId, summary: [],
-          content: [{ type: "reasoning_text", text: currentRawReasoning.text }],
+          type: "reasoning", id: currentRawReasoning.itemId,
+          summary: [{ type: "summary_text", text: currentRawReasoning.text }],
         };
         emit("response.output_item.done", { output_index: currentRawReasoning.outputIndex, item });
         retainFinishedItem(item as OutputItem, currentRawReasoning.textBytes, "reasoning");
@@ -977,8 +1000,12 @@ export function bridgeToResponsesSSE(
               if (currentToolCall) closeCurrentToolCall();
               if (!currentRawReasoning) {
                 const itemId = `rs_${uuid()}`;
-                const item = { type: "reasoning", id: itemId, summary: [] as never[], content: [] as { type: string; text: string }[] };
+                const item = { type: "reasoning", id: itemId, summary: [] as { type: string; text: string }[] };
                 emit("response.output_item.added", { output_index: outputIndex, item });
+                emit("response.reasoning_summary_part.added", {
+                  item_id: itemId, output_index: outputIndex, summary_index: 0,
+                  part: { type: "summary_text", text: "" },
+                });
                 currentRawReasoning = { itemId, outputIndex, text: "", textBytes: 0 };
               }
               ({ value: currentRawReasoning.text, bytes: currentRawReasoning.textBytes } = appendString(
@@ -987,9 +1014,9 @@ export function bridgeToResponsesSSE(
                 event.text,
                 "reasoning",
               ));
-              emit("response.reasoning_text.delta", {
+              emit("response.reasoning_summary_text.delta", {
                 item_id: currentRawReasoning.itemId, output_index: currentRawReasoning.outputIndex,
-                content_index: 0, delta: event.text,
+                summary_index: 0, delta: event.text,
               });
               break;
             }
@@ -1176,6 +1203,9 @@ export function bridgeToResponsesSSE(
               if (truncationReasonFor(event.stopReason)) {
                 // Upstream stopped before a normal completion. Surface as incomplete so the
                 // client can distinguish a truncated/filtered turn from a finished one.
+                // #1926 gap 2: bound the window in which a handed-out thought signature is
+                // not yet durable before the turn becomes externally terminal.
+                await awaitThoughtSignatureDurability();
                 const response = {
                   ...responseSnapshot("incomplete", finishedItems, event.endTurn),
                   usage: responsesUsage(event.usage),
@@ -1190,6 +1220,7 @@ export function bridgeToResponsesSSE(
                 emit("response.incomplete", { response });
                 reportTerminal("incomplete");
               } else {
+                await awaitThoughtSignatureDurability();
                 const response = { ...responseSnapshot("completed", finishedItems, event.endTurn), usage: responsesUsage(event.usage) };
                 options?.onCompletedResponse?.(response, event.providerState);
                 options?.onUsage?.(event.usage);
@@ -1210,6 +1241,7 @@ export function bridgeToResponsesSSE(
               if (currentWebSearch) closeCurrentWebSearch("failed", []);
               flushHiddenReasoningEnvelope();
               options?.onUsage?.(event.usage);
+              await awaitThoughtSignatureDurability();
               emit("response.incomplete", {
                 response: {
                   ...responseSnapshot("incomplete", finishedItems, event.endTurn),
@@ -1238,6 +1270,7 @@ export function bridgeToResponsesSSE(
               if (currentWebSearch) closeCurrentWebSearch("failed", []);
               const failure = adapterFailureFromEvent(event);
               if (event.usage) options?.onUsage?.(event.usage);
+              await awaitThoughtSignatureDurability();
               emit("response.failed", {
                 response: {
                   ...responseSnapshot("failed", finishedItems),
@@ -1299,6 +1332,7 @@ export function bridgeToResponsesSSE(
         if (currentToolCall) failCurrentToolCall();
         if (currentWebSearch) closeCurrentWebSearch("failed", []);
         options?.onUsage?.(undefined);
+        await awaitThoughtSignatureDurability();
         emit("response.incomplete", {
           response: {
             ...responseSnapshot("incomplete", finishedItems),
@@ -1339,6 +1373,10 @@ export function bridgeToResponsesSSE(
             flushHiddenRawReasoning();
             if (currentToolCall) failCurrentToolCall();
             if (currentWebSearch) closeCurrentWebSearch("failed", []);
+            // #1926 gap 2 residual: this beat callback is synchronous, so the durability
+            // barrier is not awaited on the stall-timeout kill path. The in-memory store is
+            // already updated; only a crash between here and the queued write loses it,
+            // which is the pre-#1926 status quo for an already-abnormal termination.
             emit("response.incomplete", {
               response: {
                 ...responseSnapshot("incomplete", finishedItems),
@@ -1582,8 +1620,8 @@ function buildResponseJSONWithBudget(
       return;
     }
     pushOutput({
-      type: "reasoning", id: `rs_${uuid()}`, summary: [],
-      content: [{ type: "reasoning_text", text: currentRawReasoning }],
+      type: "reasoning", id: `rs_${uuid()}`,
+      summary: [{ type: "summary_text", text: currentRawReasoning }],
     }, currentRawReasoningBytes, "reasoning");
     currentRawReasoning = "";
     currentRawReasoningBytes = 0;

package/src/chat/inbound.ts

@@ -299,6 +299,7 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
   if (raw.stop !== undefined) body.stop = raw.stop;
   if (typeof raw.user === "string") body.user = raw.user;
   if (typeof raw.parallel_tool_calls === "boolean") body.parallel_tool_calls = raw.parallel_tool_calls;
+  if (typeof raw.service_tier === "string") body.service_tier = raw.service_tier;
   if (typeof raw.prompt_cache_key === "string") body.prompt_cache_key = raw.prompt_cache_key;
   if (raw.metadata !== undefined) body.metadata = raw.metadata;
 

package/src/claude/agents-inject.ts

@@ -11,9 +11,10 @@
  * Ownership contract: this module only creates/overwrites/deletes files matching
  * `ocx-*.md` inside the agents dir. User-authored agents are never touched.
  */
-import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { OcxConfig } from "../types";
+import { renameAtomicFile } from "../lib/windows-atomic-replace";
 import { claudeCodeAlias, claudeCodeNativeAlias } from "./alias";
 import { AUTO_CONTEXT_OFF, shouldMarkOneMillion, stripOneMillionMarker, withOneMillionMarker } from "./context-windows";
 import { claudeConfigDir } from "./gateway-cache";
@@ -235,7 +236,7 @@ export function syncClaudeAgentDefs(defs: readonly ClaudeAgentDef[], configDir =
       } catch { /* does not exist: ours to create */ }
       const tmp = `${target}.tmp-${process.pid}`;
       writeFileSync(tmp, renderAgentDef(def), { encoding: "utf8", mode: 0o644 });
-      renameSync(tmp, target);
+      renameAtomicFile(tmp, target, undefined, "claude-agents");
       written.push(def.file);
     }
     return written;

package/src/cli/dispatch.ts

@@ -204,10 +204,20 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   sync: async deps => {
     const restartCodex = deps.args.slice(1).includes("--restart-codex");
-    const synced = await syncModelsToCodex((await deps.findLiveProxy())?.port);
+    const synced = await syncModelsToCodex(
+      (await deps.findLiveProxy())?.port,
+      undefined,
+      undefined,
+      undefined,
+      { catalogEvenWhenNotInjected: true },
+    );
     let code = 0;
     if (synced.status === "skipped") {
       console.log("Codex integration is OFF; sync skipped and no Codex files changed.");
+    } else if (synced.status === "catalog-only") {
+      // Explicit sync with the integration OFF still refreshes the catalog/cache
+      // for side profiles that consume the proxy without injection.
+      console.log(synced.message ?? "Codex integration is OFF; catalog refreshed, Codex config untouched.");
     } else if (!synced.ok) {
       code = 1;
       console.error("Codex sync did not complete. Fix the reported Codex config issue and retry.");
@@ -227,19 +237,18 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   "sync-cache": async deps => {
     const restartCodex = deps.args.slice(1).includes("--restart-codex");
-    if (!shouldSyncCodexOnStart(deps.loadConfig())) {
-      console.log("Codex integration is OFF; cache sync skipped and no Codex files changed.");
-      return 0;
-    }
     const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
     const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
     const { getCodexHome } = await import("../codex/paths");
     const owningCodexHome = getCodexHome();
+    const desiredDisabled = !shouldSyncCodexOnStart(deps.loadConfig());
     const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
-      invalidateCodexModelsCacheWithPermit(permit, owningCodexHome));
+      invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
     if (invalidated.kind === "completed" && invalidated.value) {
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+    } else if (desiredDisabled) {
+      console.log("Codex integration is OFF; cache sync skipped (no catalog or cache write).");
     }
     return 0;
   },
@@ -502,6 +511,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { cmdMmx } = await import("./minimax");
     return await cmdMmx(deps.args.slice(1));
   },
+  zcode: async deps => {
+    const { handleZcodeCommand } = await import("./integrations");
+    return await handleZcodeCommand(deps.args.slice(1));
+  },
   help: async () => {
     printUsage();
     return 0;

package/src/cli/help.ts

@@ -58,7 +58,7 @@ Usage:
   ocx memory [--json]         Alias of ocx observe memory
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
-  ocx export --client <id>    Print a client config wired to the running proxy (8 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (10 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, and updates
@@ -69,6 +69,7 @@ Usage:
   ocx opencode [args...]      Launch opencode wired to the proxy (runtime provider config)
   ocx mcode [args...]         Launch MiniMax Code through its managed provider
   ocx mmx text <sub> [args]   Launch MiniMax CLI text through the proxy
+  ocx zcode [sub]             Connect ZCode to the proxy (managed provider)
   ocx help [command]          Show help
   ocx --version | -v          Print version
 

package/src/cli/integrations.ts

@@ -223,3 +223,38 @@ export async function handleClientIntegrationCommand(
 }
 
 export const INTEGRATION_USAGE = { claude: CLAUDE_USAGE, grok: GROK_USAGE, client: CLIENT_USAGE };
+
+const ZCODE_USAGE = `Usage:
+  ocx zcode [status] [--json]
+  ocx zcode <enable|disable> [--json]
+  ocx zcode history [--json]
+  ocx zcode restore --op <opId> [--confirm-drift] [--json]`;
+
+/**
+ * Thin alias over the client-integration surface for ZCode (Z.ai's desktop
+ * client). ZCode is a GUI app with no launch surface to wrap, so unlike
+ * `ocx mcode` there is no exec step: connecting the managed provider block is
+ * the whole integration, and every safety property (ownership, snapshots,
+ * journal, drift refusal) stays behind the shared management API. ZCode reads
+ * its config at startup, so enable/disable print a restart reminder.
+ */
+export async function handleZcodeCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const args = [...argv];
+  // Find the first non-flag token so `ocx zcode --json enable` still enables.
+  const verbIndex = args.findIndex(arg => !arg.startsWith("-"));
+  const action = (verbIndex === -1 ? "status" : args[verbIndex]).toLowerCase();
+  const known = ["status", "show", "list", "enable", "disable", "history", "journal", "restore"];
+  if (!known.includes(action)) {
+    console.error(`unknown zcode command ${action}`);
+    console.error(ZCODE_USAGE);
+    return 2;
+  }
+  const rest = verbIndex === -1 ? args : [...args.slice(0, verbIndex), ...args.slice(verbIndex + 1)];
+  // `restore` addresses an operation id, not a client, so nothing is injected.
+  const forwarded = action === "restore" ? [action, ...rest] : [action, ...rest, "--client", "zcode"];
+  const code = await handleClientIntegrationCommand(forwarded, deps);
+  if (code === 0 && (action === "enable" || action === "disable")) {
+    console.error("Restart ZCode to pick up the provider change.");
+  }
+  return code;
+}

package/src/cli/minimax.ts

@@ -190,12 +190,18 @@ export function startMmxTextBridge(
         ? null
         : clearableDeadline(options.headerTimeoutMs, req.signal);
       try {
-        return await fetch(new Request(target, {
+        const upstreamRequest = new Request(target, {
           method: "POST",
           headers,
           body: req.body,
           signal: headerDeadline?.signal ?? req.signal,
-        }));
+        });
+        return await fetch(upstreamRequest, {
+          // Override HTTP(S)_PROXY with the loopback listener itself. Bun sends
+          // the HTTP proxy-form request directly to this exact origin, so the
+          // hop cannot leave the machine even when the parent has proxy vars.
+          proxy: { url: upstreamOrigin },
+        });
       } catch {
         return Response.json({
           type: "error",

package/src/cli/registry.ts

@@ -216,8 +216,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "api-key", usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "export",
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",
@@ -302,6 +302,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "The wrapper isolates ~/.mmx credentials and refuses --api-key/--base-url overrides.",
     ],
   },
+  {
+    name: "zcode",
+    usage: "ocx zcode [status|enable|disable|history|restore] [--json]",
+    summary: "Connect ZCode (Z.ai desktop client) to the proxy via its managed provider.",
+    details: [
+      "Alias of ocx integration client <sub> --client zcode.",
+      "enable writes the managed provider.opencodex block into ~/.zcode/v2/config.json; disable removes only that block.",
+      "ZCode reads its config at startup — restart ZCode after enable/disable.",
+      "Select OpenCodex Proxy/<provider>/<model> from ZCode's model picker.",
+    ],
+  },
   {
     name: "restart",
     usage: "ocx restart",