@bitkyc08/opencodex 2.89.0 → 2.91.0

package/src/adapters/openai-responses/opengateway-input.ts

@@ -0,0 +1,139 @@
+import { isPlainObject } from "./internal";
+import { normalizeResponsesToolResultAdjacency } from "./tool-output-recovery";
+
+export class OpenGatewayInputCompatibilityError extends Error {
+  constructor() {
+    super("OpenGateway cannot preserve this tool result; use text or valid input_image parts with a call_id.");
+    this.name = "OpenGatewayInputCompatibilityError";
+  }
+}
+
+const TOOL_ROUND_TYPES = new Set([
+  "function_call",
+  "function_call_output",
+  "custom_tool_call",
+  "custom_tool_call_output",
+  "local_shell_call",
+  "local_shell_call_output",
+]);
+
+function normalizeImageDetail(part: unknown): unknown {
+  return isPlainObject(part) && part.type === "input_image" && part.detail === "original"
+    ? { ...part, detail: "high" }
+    : part;
+}
+
+function isToolRound(item: unknown): boolean {
+  return isPlainObject(item) && typeof item.type === "string" && TOOL_ROUND_TYPES.has(item.type);
+}
+
+function pairedCallId(item: Record<string, unknown>): string | undefined {
+  return typeof item.call_id === "string" && item.call_id.length > 0 ? item.call_id : undefined;
+}
+
+type ProjectedInput = { readonly changed: boolean; readonly input: unknown[] };
+
+function projectOpenGatewayInput(input: readonly unknown[]): ProjectedInput {
+  let changed = false;
+  const projected: unknown[] = [];
+  const pendingImages: unknown[] = [];
+  const flushImages = (): void => {
+    if (pendingImages.length === 0) return;
+    projected.push(...pendingImages);
+    pendingImages.length = 0;
+  };
+  for (const item of input) {
+    if (!isToolRound(item)) flushImages();
+    if (!isPlainObject(item)) {
+      projected.push(item);
+      continue;
+    }
+    if (item.type === "function_call_output" && Array.isArray(item.output)) {
+      const callId = pairedCallId(item);
+      const content: Record<string, unknown>[] = [];
+      const text: string[] = [];
+      let supported = callId !== undefined;
+      let hasImage = false;
+      if (supported) {
+        for (const part of item.output) {
+          if (!isPlainObject(part)) {
+            supported = false;
+            break;
+          }
+          switch (part.type) {
+            case "text":
+            case "input_text":
+            case "output_text":
+              if (typeof part.text !== "string") {
+                supported = false;
+                break;
+              }
+              text.push(part.text);
+              content.push({ type: "input_text", text: part.text });
+              break;
+            case "input_image":
+              if (!((typeof part.image_url === "string" && part.image_url.length > 0)
+                || (typeof part.file_id === "string" && part.file_id.length > 0))
+                || (part.image_url !== undefined && typeof part.image_url !== "string")
+                || (part.file_id !== undefined && typeof part.file_id !== "string")
+                || (part.detail !== undefined && (typeof part.detail !== "string"
+                  || !["auto", "low", "high", "original"].includes(part.detail)))) {
+                supported = false;
+                break;
+              }
+              content.push({ ...part, ...(part.detail === "original" ? { detail: "high" } : {}) });
+              hasImage = true;
+              break;
+            default:
+              supported = false;
+          }
+          if (!supported) break;
+        }
+      }
+      if (supported && callId !== undefined) {
+        changed = true;
+        const marker = `[tool output for ${callId}]`;
+        projected.push({
+          ...item,
+          output: text.length > 0 ? text.join("\n") : hasImage ? marker : "",
+        });
+        if (hasImage) {
+          pendingImages.push({
+            type: "message",
+            role: "user",
+            content: [{ type: "input_text", text: marker }, ...content],
+          });
+        }
+        continue;
+      }
+      throw new OpenGatewayInputCompatibilityError();
+    }
+    if (Array.isArray(item.content)) {
+      const originalContent = item.content;
+      const content = originalContent.map(normalizeImageDetail);
+      if (content.some((part, index) => part !== originalContent[index])) {
+        changed = true;
+        projected.push({ ...item, content });
+        continue;
+      }
+    }
+    projected.push(item);
+  }
+  flushImages();
+  return { changed, input: projected };
+}
+
+/** OpenGateway requires string tool results and auto/low/high image detail. */
+export function normalizeOpenGatewayResponsesInput(body: unknown, url: string): unknown {
+  // Same exact-URL boundary as completion recovery; a query-routed variant is a different destination.
+  if (url !== "https://apis.opengateway.ai/v1/responses" || !isPlainObject(body) || !Array.isArray(body.input)) return body;
+
+  const direct = projectOpenGatewayInput(body.input);
+  if (!direct.changed) return body;
+  const aligned = normalizeResponsesToolResultAdjacency(body);
+  if (!isPlainObject(aligned) || !Array.isArray(aligned.input) || aligned === body) {
+    return { ...body, input: direct.input };
+  }
+  const paired = projectOpenGatewayInput(aligned.input);
+  return { ...aligned, input: paired.changed ? paired.input : direct.input };
+}

package/src/adapters/openai-responses/passthrough.ts

@@ -40,7 +40,7 @@ import {
   emittedFastWire,
 } from "../../providers/fastwire";
 import { dropResponsesReasoningInputItems, mapRoutedResponsesReasoningEffort, normalizeConfiguredReasoningSummaryDelivery, sanitizeReasoningInputContent, stripDisabledReasoningSummaries, stripDisabledVerbosity, stripNoneReasoningSummary, stripUnsupportedReasoningSummaryDelivery } from "./reasoning";
-import { scrubOcxCompactionItems, stripCanonicalOnlyToolFields, stripCanonicalOnlyTopLevelFields, stripInternalChatMessageMetadataPassthrough, stripInvalidItemIds, stripItemIdsWhenUnstored, stripProviderInputItemMetadata, stripRejectedSamplingParams } from "./request-strips";
+import { scrubOcxCompactionItems, stripCanonicalOnlyInputItems, stripCanonicalOnlyToolFields, stripCanonicalOnlyTopLevelFields, stripInternalChatMessageMetadataPassthrough, stripInvalidItemIds, stripItemIdsWhenUnstored, stripProviderInputItemMetadata, stripRejectedSamplingParams } from "./request-strips";
 import { notePlaintextReasoningDropped } from "./plaintext-reasoning-notice";
 import { stripCanonicalForwardPromptCacheOptions, stripDeprecatedPromptCacheRetention } from "./prompt-cache";
 import { isPlainObject } from "./internal";
@@ -55,6 +55,7 @@ import { observeOutbound } from "../../usage/cache-diagnostic";
 import { normalizeMuseToolChoice } from "./muse-tool-choice";
 import { declaresHostedWebSearch, projectHostedSearchHistory, renderCompactionSearchHistoryItems } from "./compaction-search-history";
 import { stripKimiEmptyAssistantMessages } from "./empty-assistant";
+import { normalizeOpenGatewayResponsesInput } from "./opengateway-input";
 
 /**
  * Identifies DeepSeek's strict Responses replay contract: tool-bearing continuations need
@@ -334,6 +335,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         if (!isOpenAiOperatedResponsesDestination(provider)) {
           if (parsed._compactionRequest !== true && isPlainObject(outBody)) outBody = frameCompactionHistory(outBody);
           outBody = stripCanonicalOnlyTopLevelFields(outBody);
+          outBody = stripCanonicalOnlyInputItems(outBody);
         }
         outBody = promoteClientLoadedTools(outBody);
       }
@@ -508,11 +510,13 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
           || !declaresHostedWebSearch(finalBody))) {
         finalBody = projectHostedSearchHistory(finalBody);
       }
+      finalBody = normalizeOpenGatewayResponsesInput(finalBody, url);
       observeOutbound(parsed._rawBody, finalBody, headers);
       if (!isCanonicalOpenAiForwardProvider(provider)) {
         validateFinalCustomToolCompatibility(finalBody, provider.supportsResponsesCustomTools);
       }
-      const body = JSON.stringify(applyGithubCopilotContextTier(finalBody, provider, parsed.modelId, incoming.providerName));
+      const wireBody = applyGithubCopilotContextTier(finalBody, provider, parsed.modelId, incoming.providerName);
+      const body = JSON.stringify(wireBody);
       const releaseBodyObservation = translatorBudget.observeExternallyCapped(
         "passthrough_serialization",
         Buffer.byteLength(body, "utf8"),
@@ -522,6 +526,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         method: "POST",
         headers,
         body,
+        ...(isPlainObject(wireBody) && typeof wireBody.model === "string" ? { outboundModelId: wireBody.model } : {}),
         releaseBodyObservation,
         ...(convertedRoutedCustomToolNames ? { convertedRoutedCustomToolNames } : {}),
         ...(routedCustomToolRepairNames ? { routedCustomToolRepairNames } : {}),

package/src/adapters/openai-responses/request-strips.ts

@@ -187,6 +187,38 @@ export function stripCanonicalOnlyTopLevelFields(body: unknown): unknown {
   return next;
 }
 
+/**
+ * OpenAI-private input item TYPES, the item-level sibling of the two tables above.
+ *
+ * Each one is a positional control the OpenAI Responses backend interprets where it sits in
+ * history, never a turn of the conversation, so dropping it leaves every message, call and output
+ * in place. Codex gates sending one on its own `is_openai` provider check, which loopback
+ * injection always satisfies, so a gateway this proxy does not operate can still receive one and
+ * reject the whole body as an unknown item type.
+ *
+ * Same rule as the top-level table: only types a client is OBSERVED to send.
+ */
+const CANONICAL_ONLY_INPUT_ITEM_TYPES: ReadonlySet<string> = new Set([
+  // Codex 0.164 `ResponseItem::ConfigurationUpdate` ({type, reasoning: {effort}}): a durable
+  // reasoning-effort change recorded at its position in history. codex-rs sends it only for a
+  // catalog row with `supports_reasoning_effort_updates`, and keeps it in saved history after a
+  // model switch. Mapping the effort onto another provider is out of scope (#6895).
+  "configuration_update",
+]);
+
+/**
+ * Remove OpenAI-private input items. The caller decides the boundary, exactly as for
+ * {@link stripCanonicalOnlyTopLevelFields}; the canonical and OpenAI-operated destinations keep
+ * the items verbatim and in order. Returns the input unchanged when none is present.
+ */
+export function stripCanonicalOnlyInputItems(body: unknown): unknown {
+  if (!isPlainObject(body) || !Array.isArray(body.input)) return body;
+  const isPrivate = (item: unknown): boolean => isPlainObject(item)
+    && typeof item.type === "string" && CANONICAL_ONLY_INPUT_ITEM_TYPES.has(item.type);
+  if (!body.input.some(isPrivate)) return body;
+  return { ...body, input: body.input.filter(item => !isPrivate(item)) };
+}
+
 /**
  * Sampling fields a model on the provider's `noStopModels` / `noPenaltyModels` list rejects on
  * every wire. Claude inbound translates `stop_sequences` into a Responses `stop`

package/src/adapters/openai-responses/transport.ts

@@ -3,6 +3,7 @@ import type { OcxProviderConfig } from "../../types";
 import { CODEX_RESPONSES_LITE_HEADER } from "../../codex/forward-transport-headers";
 import { CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "../../providers/openai-tiers-destination";
 import { normalizeForwardedClientHeaderName } from "../../lib/provider-client-headers";
+import { AGENT_ASSERTION_HEADER } from "../../lib/authorization-scheme";
 import { openaiResponsesUrl } from "../openai-responses-url";
 
 // Caller credentials are forwarded only to the canonical Codex destination, never by capability.
@@ -23,6 +24,18 @@ export function copyResponsesClientMetadata(target: Headers, incoming: Headers,
   }
 }
 
+/**
+ * Strip trailing slashes with a linear scan rather than a regex.
+ *
+ * `/\/+$/` retries candidate end positions when a long slash run is not at the end of the
+ * string; the scan walks each character once and produces the same result on every input.
+ */
+function stripTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+  return end === value.length ? value : value.slice(0, end);
+}
+
 /** Shared Responses URL/auth/header construction; capabilities never grant auth authority. */
 export function buildResponsesTransport(provider: OcxProviderConfig, incoming: Pick<IncomingMeta, "headers">): {
   url: string; headers: Record<string, string>;
@@ -31,7 +44,7 @@ export function buildResponsesTransport(provider: OcxProviderConfig, incoming: P
   let url: string;
   if (provider.authMode === "forward") {
     const mayForwardCallerCredentials = isCanonicalOpenAiForwardProvider(provider);
-    const baseUrl = mayForwardCallerCredentials ? CODEX_FORWARD_BASE_URL : provider.baseUrl.replace(/\/+$/, "");
+    const baseUrl = mayForwardCallerCredentials ? CODEX_FORWARD_BASE_URL : stripTrailingSlashes(provider.baseUrl);
     url = `${baseUrl}/responses`;
     if (provider.headers) Object.assign(headers, provider.headers);
     const runtimeProvider = provider as {
@@ -57,6 +70,11 @@ export function buildResponsesTransport(provider: OcxProviderConfig, incoming: P
     if (override && mayForwardCallerCredentials) {
       headers.authorization = `Bearer ${override.accessToken}`;
       headers["chatgpt-account-id"] = override.chatgptAccountId;
+    } else if (mayForwardCallerCredentials) {
+      // dual_header runtime assertion: first-party Direct only, beside the caller's own Bearer.
+      // A pool override above never carries it, and non-canonical transports never see it.
+      const assertion = incoming.headers.get(AGENT_ASSERTION_HEADER);
+      if (assertion) headers[AGENT_ASSERTION_HEADER] = assertion;
     }
   } else {
     url = provider.responsesPath === undefined

package/src/chat/inbound.ts

@@ -6,6 +6,7 @@
  * responsesRequestSchema so routing/OAuth/pool/sidecars are inherited unchanged.
  */
 import { chatImageUrlFromPart } from "./image-parts";
+import { signedReasoningInputItems } from "./reasoning-details";
 import { untranslatedChatInputMedia, untranslatedInputMediaMessage } from "../responses/input-media";
 
 export class ChatCompletionsRequestError extends Error {}
@@ -439,7 +440,16 @@ function resolveReasoningSummary(raw: Rec): string | undefined {
  * Translate an OpenAI Chat Completions request body into a /v1/responses request body.
  * Throws ChatCompletionsRequestError (-> 400) on malformed input.
  */
-export function chatCompletionsToResponsesBody(raw: unknown): Rec {
+export interface ChatResponsesProjectionOptions {
+  /**
+   * The route is one first-party Anthropic destination that cannot change credential domain, so
+   * signed thinking a client returns in `reasoning_details` may be replayed to it (#7429).
+   * Every other route keeps the plaintext projection.
+   */
+  acceptAnthropicReasoningSignatures?: boolean;
+}
+
+export function chatCompletionsToResponsesBody(raw: unknown, options: ChatResponsesProjectionOptions = {}): Rec {
   assertChatCompletionsRoutingBody(raw);
   // Only the translated path reaches this function. Native Chat can retain its
   // provider-specific file/audio blocks; projecting them here would discard them.
@@ -510,7 +520,13 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
         // is no attachment point on the message itself, and the parser buffers a
         // reasoning item and prepends it to the NEXT assistant message. Emitting it
         // here keeps that adjacency intact.
-        const reasoningText = assistantReasoningText(msg);
+        const signedReasoning = options.acceptAnthropicReasoningSignatures === true
+          ? signedReasoningInputItems(msg.reasoning_details)
+          : undefined;
+        const reasoningText = signedReasoning ? undefined : assistantReasoningText(msg);
+        // Signed entries carry their own text, so `reasoning_content` (the same text) is not
+        // projected a second time beside them.
+        if (signedReasoning) input.push(...signedReasoning);
         if (reasoningText !== undefined) {
           // `summary` is required on a reasoning input item by the OpenAI Responses API, and our
           // own responsesRequestSchema marks it optional, so a summary-less item validated locally
@@ -525,6 +541,8 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
             content: [{ type: "reasoning_text", text: reasoningText }],
           });
         }
+        // An Opus progress update also sits in `content`. The wire has no marker that tells it
+        // from answer text, so the content is replayed as sent, as it was before #7429.
         const blocks = assistantContentToBlocks(msg.content);
         if (blocks.length > 0) input.push({ type: "message", role: "assistant", content: blocks });
         if (msg.tool_calls !== undefined) {

package/src/chat/outbound.ts

@@ -23,6 +23,7 @@ import {
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { createSseBlockBuffer, sseDataPayload } from "../server/sse-payload-rewrite";
+import { reasoningDetailEntriesForItem } from "./reasoning-details";
 
 function isRec(v: unknown): v is Rec {
   return !!v && typeof v === "object" && !Array.isArray(v);
@@ -149,7 +150,7 @@ export function chunkBase(id: string, model: string, created: number): Rec {
   };
 }
 
-function appendedUtf8Bytes(previous: string, previousBytes: number, fragment: string): number {
+export function appendedUtf8Bytes(previous: string, previousBytes: number, fragment: string): number {
   let nextBytes = previousBytes + Buffer.byteLength(fragment);
   const previousLast = previous.charCodeAt(previous.length - 1);
   const fragmentFirst = fragment.charCodeAt(0);
@@ -511,6 +512,17 @@ export function responsesSseToChatCompletionsSse(
         frame.choices = [{ index: 0, delta: { reasoning_content: text }, finish_reason: null }];
         emit(frame);
       };
+      // #7429: provider-issued thinking state, one complete frame per finished reasoning item.
+      let nextReasoningDetailIndex = 0;
+      const emitReasoningDetails = (item: Rec) => {
+        const entries = reasoningDetailEntriesForItem(item, nextReasoningDetailIndex, translatorBudget);
+        if (entries.length === 0) return;
+        nextReasoningDetailIndex += entries.length;
+        ensureRole();
+        const frame = chunkBase(id, model, created);
+        frame.choices = [{ index: 0, delta: { reasoning_details: entries }, finish_reason: null }];
+        emit(frame);
+      };
       const resolveFinalArguments = (candidate: unknown, streamed: string) => {
         if (typeof candidate !== "string") return streamed;
         // Some compatible providers send an empty final snapshot. Do not let that erase
@@ -717,6 +729,7 @@ export function responsesSseToChatCompletionsSse(
               && refusalItems.has(data.output_index)) {
               refusalItem(data.output_index, data, "item_id");
             }
+            if (item.type === "reasoning") emitReasoningDetails(item);
             if (item.type === "function_call") {
               sawToolUse = true;
               const callId = typeof item.call_id === "string" ? item.call_id : "";
@@ -872,6 +885,7 @@ export function responsesJsonToChatCompletion(json: unknown, model: string, tran
   let contentBytes = 0;
   let reasoningBytes = 0;
   const toolCalls: Rec[] = [];
+  const reasoningDetails: Rec[] = [];
   const append = (previous: string, previousBytes: number, fragment: string): { text: string; bytes: number } => {
     if (!fragment) return { text: previous, bytes: previousBytes };
     const scope = { kind: "retained_collectors" as const };
@@ -902,6 +916,11 @@ export function responsesJsonToChatCompletion(json: unknown, model: string, tran
         }
       }
     } else if (raw.type === "reasoning") {
+      const entries = reasoningDetailEntriesForItem(raw, reasoningDetails.length, translatorBudget);
+      if (entries.length > 0) {
+        translatorBudget?.chargeRetained(Buffer.byteLength(JSON.stringify(entries)), { kind: "retained_collectors" });
+        reasoningDetails.push(...entries);
+      }
       if (Array.isArray(raw.summary)) {
         for (const part of raw.summary) {
           if (isRec(part) && part.type === "summary_text" && typeof part.text === "string") {
@@ -948,6 +967,7 @@ export function responsesJsonToChatCompletion(json: unknown, model: string, tran
     refusal,
   };
   if (reasoning) message.reasoning_content = reasoning;
+  if (reasoningDetails.length > 0) message.reasoning_details = reasoningDetails;
   if (toolCalls.length > 0) message.tool_calls = toolCalls;
 
   return {
@@ -981,7 +1001,8 @@ export async function collectChatCompletion(
   let content = "";
   let refusal: string | null = null;
   let reasoning = "";
-  const retainedBytes = { content: 0, refusal: 0, reasoning: 0 };
+  const reasoningDetails: Rec[] = [];
+  const retainedBytes = { content: 0, refusal: 0, reasoning: 0, reasoningDetails: 0 };
   const toolCalls = new Map<number, { id: string; name: string; arguments: string; argumentBytes: number }>();
   // Per-call budget scopes (2 MiB/call enforced by the budget): the map key is the
   // wire index, which is stable across deltas and present before the call id.
@@ -1005,8 +1026,8 @@ export async function collectChatCompletion(
     }
   };
   const releaseCollectors = () => {
-    translatorBudget.releaseRetained(retainedBytes.content + retainedBytes.refusal + retainedBytes.reasoning,
-      { kind: "retained_collectors" });
+    translatorBudget.releaseRetained(retainedBytes.content + retainedBytes.refusal + retainedBytes.reasoning
+      + retainedBytes.reasoningDetails, { kind: "retained_collectors" });
   };
   try {
     // Share native relay framing, while retaining the collector's existing admission
@@ -1055,6 +1076,16 @@ export async function collectChatCompletion(
           refusal = appendRetained("refusal", refusal ?? "", delta.refusal);
         }
         if (typeof delta.reasoning_content === "string") reasoning = appendRetained("reasoning", reasoning, delta.reasoning_content);
+        // Each entry arrives complete in one frame (#7429), so the fold is a concatenation.
+        if (Array.isArray(delta.reasoning_details)) {
+          for (const entry of delta.reasoning_details) {
+            if (!isRec(entry)) continue;
+            const entryBytes = Buffer.byteLength(JSON.stringify(entry));
+            translatorBudget.chargeRetained(entryBytes, { kind: "retained_collectors" });
+            retainedBytes.reasoningDetails += entryBytes;
+            reasoningDetails.push(entry);
+          }
+        }
         if (Array.isArray(delta.tool_calls)) {
           for (const tc of delta.tool_calls) {
             if (!isRec(tc)) continue;
@@ -1121,6 +1152,7 @@ export async function collectChatCompletion(
     refusal,
   };
   if (reasoning) message.reasoning_content = reasoning;
+  if (reasoningDetails.length > 0) message.reasoning_details = reasoningDetails;
   if (toolCalls.size > 0) {
     // Final owner transfer is itself a charging operation: if it overflows,
     // release every copy already charged in this loop and close every scope

package/src/chat/reasoning-details.ts

@@ -0,0 +1,137 @@
+/**
+ * Anthropic thinking state on the Chat Completions wire, as OpenRouter-style `reasoning_details`
+ * (#7429).
+ *
+ * Chat has no slot for a thinking block's signature, so a Chat client echoing `reasoning_content`
+ * gave Claude back unsigned text, which the Anthropic adapter must drop: every tool step lost its
+ * reasoning. The carrier is the one OpenRouter documents for Claude and Hermes and pi already round
+ * trip: an ordered array on the assistant message, `{type: "reasoning.text", text, signature}`
+ * for a signed thinking block and `{type: "reasoning.encrypted", data}` for a redacted one.
+ *
+ * Outbound, the entries are built from the signature and redacted payloads the provider issued,
+ * never from anything this proxy computes. A signature that signs text the client never saw
+ * (hidden thinking) is withheld, because pairing it with the visible text would attest to content
+ * Anthropic did not sign. Inbound, the entries are read only for a single-destination first-party
+ * Anthropic route (the caller decides that), only when every entry is well formed, and become the
+ * same `ocxr1` envelope the Responses wire already uses; anything else falls back to plaintext.
+ */
+import {
+  decodeReasoningEnvelope,
+  encodeReasoningEnvelope,
+  isLikelyRealAnthropicThinkingSignature,
+  type ReasoningEnvelope,
+} from "../responses/reasoning-envelope";
+import type { TranslatorBudget } from "../lib/translator-budget";
+
+type Rec = Record<string, unknown>;
+
+function isRec(value: unknown): value is Rec {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** OpenRouter's `format` for Anthropic thinking entries. */
+export const ANTHROPIC_REASONING_DETAIL_FORMAT = "anthropic-claude-v1";
+
+/** One closed reasoning item, as either outbound path sees it. */
+export interface ReasoningDetailSource {
+  /** The thinking text the client was shown for this item. */
+  text: string;
+  signature?: string;
+  redacted?: readonly string[];
+  /** The signature covers thinking text the client was not shown. */
+  hidden?: boolean;
+}
+
+/**
+ * The `reasoning_details` entries for one reasoning item, numbered from `firstIndex`. Redacted
+ * blocks come first: that is the order the adapter replays them in. Empty when the item carries no
+ * provider-issued state a Chat client can return.
+ */
+export function reasoningDetailEntries(source: ReasoningDetailSource, firstIndex: number): Rec[] {
+  const entries: Rec[] = [];
+  for (const data of source.redacted ?? []) {
+    if (typeof data !== "string" || data.length === 0) continue;
+    entries.push({
+      type: "reasoning.encrypted",
+      data,
+      format: ANTHROPIC_REASONING_DETAIL_FORMAT,
+      index: firstIndex + entries.length,
+    });
+  }
+  if (source.hidden !== true && isLikelyRealAnthropicThinkingSignature(source.signature)) {
+    entries.push({
+      type: "reasoning.text",
+      text: source.text,
+      signature: source.signature,
+      format: ANTHROPIC_REASONING_DETAIL_FORMAT,
+      index: firstIndex + entries.length,
+    });
+  }
+  return entries;
+}
+
+/** The visible text of a Responses reasoning item, read the way the parser reads it. */
+export function responsesReasoningItemText(item: Rec): string {
+  const pick = (parts: unknown, type: string): string => Array.isArray(parts)
+    ? parts.filter((part): part is Rec => isRec(part) && part.type === type && typeof part.text === "string")
+      .map(part => part.text as string).join("")
+    : "";
+  return pick(item.summary, "summary_text") || pick(item.content, "reasoning_text");
+}
+
+/**
+ * The entries for a finished Responses reasoning item from the internal bridge. Its `ocxr1`
+ * envelope holds what the provider issued. `txt` alone means the signed text was hidden; `txt`
+ * with `upd` is an Opus progress update, whose signed text the client received as `content`.
+ */
+export function reasoningDetailEntriesForItem(item: Rec, firstIndex: number, budget?: TranslatorBudget): Rec[] {
+  if (typeof item.encrypted_content !== "string") return [];
+  const envelope = decodeReasoningEnvelope(item.encrypted_content, budget);
+  if (!envelope || (!envelope.sig && !envelope.red)) return [];
+  const progress = envelope.upd !== undefined && typeof envelope.txt === "string";
+  return reasoningDetailEntries({
+    text: progress ? envelope.txt! : responsesReasoningItemText(item),
+    ...(envelope.sig ? { signature: envelope.sig } : {}),
+    ...(envelope.red ? { redacted: envelope.red } : {}),
+    hidden: !progress && envelope.txt !== undefined,
+  }, firstIndex);
+}
+
+function reasoningInputItem(text: string, envelope: ReasoningEnvelope): Rec {
+  return {
+    type: "reasoning",
+    summary: text ? [{ type: "summary_text", text }] : [],
+    ...(text ? { content: [{ type: "reasoning_text", text }] } : {}),
+    encrypted_content: encodeReasoningEnvelope(envelope),
+  };
+}
+
+/**
+ * Responses reasoning input items carrying the signatures a client returned in
+ * `reasoning_details`, or `undefined` when the array is absent, empty or holds anything this
+ * carrier did not issue — an unsigned or malformed signature, a summary entry, another provider's
+ * encrypted format. Undefined means the caller keeps its plaintext projection unchanged.
+ */
+export function signedReasoningInputItems(details: unknown): Rec[] | undefined {
+  if (!Array.isArray(details) || details.length === 0) return undefined;
+  const items: Rec[] = [];
+  let redacted: string[] = [];
+  for (const raw of details) {
+    if (!isRec(raw)) return undefined;
+    if (raw.type === "reasoning.encrypted") {
+      if (raw.format !== ANTHROPIC_REASONING_DETAIL_FORMAT || typeof raw.data !== "string" || raw.data.length === 0) {
+        return undefined;
+      }
+      redacted.push(raw.data);
+      continue;
+    }
+    if (raw.type !== "reasoning.text") return undefined;
+    if (raw.format !== undefined && raw.format !== ANTHROPIC_REASONING_DETAIL_FORMAT) return undefined;
+    const signature = typeof raw.signature === "string" ? raw.signature : undefined;
+    if (typeof raw.text !== "string" || !isLikelyRealAnthropicThinkingSignature(signature)) return undefined;
+    items.push(reasoningInputItem(raw.text, { sig: signature, ...(redacted.length > 0 ? { red: redacted } : {}) }));
+    redacted = [];
+  }
+  if (redacted.length > 0) items.push(reasoningInputItem("", { red: redacted }));
+  return items;
+}

package/src/claude/desktop-3p-library.ts

@@ -1,4 +1,4 @@
-import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, type BigIntStats } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, type BigIntStats } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { claudeDesktopConfigLibraryDir, resolveConfigLibraryDir } from "./desktop-3p-paths";
@@ -44,6 +44,20 @@ export interface Desktop3pMetadata {
 
 export const DESKTOP_PICKER_ENTRY_NAME = "opencodex-picker";
 
+export const MAX_DESKTOP_PROFILE_FILE_BYTES = 4 * 1024 * 1024;
+
+export function assertDesktopLibraryTextSize(text: string): void {
+  if (Buffer.byteLength(text, "utf8") > MAX_DESKTOP_PROFILE_FILE_BYTES) {
+    throw new Error("desktop_config_too_large");
+  }
+}
+
+export function serializeDesktopLibraryJson(value: unknown): string {
+  const text = JSON.stringify(value, null, 2) + "\n";
+  assertDesktopLibraryTextSize(text);
+  return text;
+}
+
 /** A path that no longer names the observed file was swapped; a same-path failure keeps its own errno. */
 function pathStillNamesExpectedFile(path: string, expected: BigIntStats): boolean {
   try {
@@ -54,7 +68,13 @@ function pathStillNamesExpectedFile(path: string, expected: BigIntStats): boolea
 }
 
 /** Read regular config files only; a path swap must not turn an observation into a FIFO wait. */
-export function readDesktopLibraryBytes(path: string): Buffer {
+export function readDesktopLibraryBytes(
+  path: string,
+  maxBytes: number = MAX_DESKTOP_PROFILE_FILE_BYTES,
+): Buffer {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > MAX_DESKTOP_PROFILE_FILE_BYTES) {
+    throw new RangeError("invalid Desktop library read limit");
+  }
   const expected = lstatSync(path, { bigint: true });
   if (!expected.isFile()) throw new Error("desktop_config_not_regular");
   // POSIX open of a FIFO can itself block, before fstat is possible. Windows has no POSIX
@@ -73,7 +93,27 @@ export function readDesktopLibraryBytes(path: string): Buffer {
     const opened = fstatSync(fd, { bigint: true });
     if (!opened.isFile() || opened.dev !== expected.dev || opened.ino !== expected.ino
       || opened.ctimeNs !== expected.ctimeNs) throw new Error("desktop_config_not_regular");
-    return readFileSync(fd);
+    if (opened.size > BigInt(maxBytes)) throw new Error("desktop_config_too_large");
+    // Allocate for the observed size plus one sentinel byte, not the full cap: callers scan many
+    // small profiles, and the cap would zero-fill megabytes per read. A file that fills the
+    // buffer grew after validation — keep reading within the bound so it classifies as
+    // desktop_config_too_large rather than silently truncating.
+    let bytes = Buffer.alloc(Number(opened.size) + 1);
+    let length = 0;
+    for (;;) {
+      const count = readSync(fd, bytes, length, Math.min(64 * 1024, bytes.length - length), null);
+      if (count === 0) break;
+      length += count;
+      if (length > maxBytes) throw new Error("desktop_config_too_large");
+      if (length === bytes.length && bytes.length <= maxBytes) {
+        const grown = Buffer.alloc(Math.min(maxBytes + 1, bytes.length * 2));
+        bytes.copy(grown, 0, 0, length);
+        bytes = grown;
+      }
+    }
+    if (length > maxBytes) throw new Error("desktop_config_too_large");
+    if (!pathStillNamesExpectedFile(path, opened)) throw new Error("desktop_config_not_regular");
+    return bytes.subarray(0, length);
   } finally {
     closeSync(fd);
   }