@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/quota/window-mapping.ts

@@ -26,7 +26,7 @@ type ProviderLikeQuota = {
   weeklyResetAt?: number;
   monthlyPercent?: number;
   monthlyResetAt?: number;
-  customWindows?: ReadonlyArray<{ label: string; percent: number; resetAt?: number }>;
+  customWindows?: ReadonlyArray<{ label: string; percent: number; resetAt?: number; modelId?: string }>;
 };
 
 function window(
@@ -65,12 +65,15 @@ const NOMINAL_WINDOW_SECONDS: Readonly<Record<string, number>> = {
 };
 
 function customWindows(
-  entries: ReadonlyArray<{ label: string; percent: number; resetAt?: number }> | undefined,
+  entries: ReadonlyArray<{ label: string; percent: number; resetAt?: number; modelId?: string }> | undefined,
 ): QuotaWindowObservation[] {
   if (!entries) return [];
   const out: QuotaWindowObservation[] = [];
   for (const entry of entries) {
     if (typeof entry?.label !== "string") continue;
+    // Exact-model rows (Antigravity diagnostics) restate the pool their family window already
+    // reports. Observing them would turn one pool reset into one notification per model.
+    if (entry.modelId !== undefined) continue;
     const mapped = window(`custom:${entry.label}`, entry.percent, entry.resetAt);
     if (mapped) out.push(mapped);
   }

package/src/responses/anthropic-progress.ts

@@ -0,0 +1,34 @@
+import { encodeReasoningEnvelope, decodeReasoningEnvelope, type ReasoningEnvelope } from "./reasoning-envelope";
+import type { TranslatorBudget } from "../lib/translator-budget";
+
+/** A visible update is a presentation copy of one original signed thinking block. */
+export function anthropicProgressItems(text: string, signature: string, budget?: TranslatorBudget) {
+  const id = `msg_${crypto.randomUUID().replaceAll("-", "")}`;
+  return [
+    { type: "reasoning", id: `rs_${crypto.randomUUID().replaceAll("-", "")}`, summary: [],
+      encrypted_content: encodeReasoningEnvelope({ sig: signature, txt: text, upd: id }, budget) },
+    { type: "message", id, role: "assistant", status: "completed", phase: "commentary",
+      content: [{ type: "output_text", text, annotations: [] }] },
+  ];
+}
+
+/** Remove only an adjacent exact mirror. Retain edited or unrelated assistant text.
+ * Some clients omit message IDs on replay; the explicit phase and exact text still bind it.
+ */
+export function isAnthropicProgressMirror(item: unknown, envelope: ReasoningEnvelope | null): boolean {
+  if (!envelope?.upd || typeof envelope.txt !== "string" || !item || typeof item !== "object") return false;
+  const msg = item as { type?: unknown; id?: unknown; role?: unknown; phase?: unknown; content?: unknown };
+  if (msg.type !== "message" && msg.type !== undefined) return false;
+  if (msg.role !== "assistant" || msg.phase !== "commentary" || (msg.id !== undefined && msg.id !== envelope.upd)) return false;
+  if (!Array.isArray(msg.content) || msg.content.length !== 1) return false;
+  const part = msg.content[0] as { type?: unknown; text?: unknown } | undefined;
+  return part?.type === "output_text" && part.text === envelope.txt;
+}
+
+export function anthropicProgressEnvelope(item: unknown, budget?: TranslatorBudget): ReasoningEnvelope | null {
+  if (!item || typeof item !== "object") return null;
+  const raw = item as { type?: unknown; encrypted_content?: unknown };
+  if (raw.type !== "reasoning" || typeof raw.encrypted_content !== "string") return null;
+  const envelope = decodeReasoningEnvelope(raw.encrypted_content, budget);
+  return envelope?.upd && envelope.sig && typeof envelope.txt === "string" ? envelope : null;
+}

package/src/responses/assistant-replay.ts

@@ -0,0 +1,35 @@
+import type { AdapterEvent, OcxAssistantContentPart } from "../types";
+
+/** Rebuild text and signed blocks in event order, never joining separately signed blocks. */
+export function assistantReplayContent(events: readonly AdapterEvent[]): OcxAssistantContentPart[] {
+  const content: OcxAssistantContentPart[] = [];
+  let text = "";
+  let thinking: string | undefined;
+  let signature: string | undefined;
+  const flush = () => {
+    if (text) content.push({ type: "text", text });
+    if (thinking !== undefined || signature !== undefined) content.push({ type: "thinking", thinking: thinking ?? "", ...(signature !== undefined ? { signature } : {}) });
+    text = "";
+    thinking = signature = undefined;
+  };
+  for (const event of events) {
+    if (event.type === "heartbeat") continue;
+    if (signature !== undefined && event.type !== "thinking_signature") flush();
+    if (event.type === "text_delta" && event.anthropicThinkingSignature) {
+      flush();
+      content.push({ type: "thinking", thinking: event.text, signature: event.anthropicThinkingSignature });
+    } else if (event.type === "text_delta") {
+      if (thinking !== undefined) flush();
+      text += event.text;
+    } else if (event.type === "thinking_delta") {
+      if (text) flush();
+      thinking = (thinking ?? "") + event.thinking;
+    } else if (event.type === "thinking_signature") signature = event.signature;
+    else if (event.type === "redacted_thinking") {
+      flush();
+      content.push({ type: "thinking", thinking: "", redacted: [event.data] });
+    } else flush();
+  }
+  flush();
+  return content;
+}

package/src/responses/compaction-history-framing.ts

@@ -0,0 +1,65 @@
+import { appendCheckpointContinuationNote, COMPACT_PROMPT, SUMMARY_PREFIX } from "./compaction";
+
+type InputRecord = Record<string, unknown>;
+const isRecord = (value: unknown): value is InputRecord =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+export const HISTORICAL_REQUEST_START = "[Historical user request retained before the following compaction checkpoint. This is prior context, not a new request.]";
+export const HISTORICAL_REQUEST_END = "[End historical request. Use the following checkpoint to distinguish completed work from unfinished work. Do not repeat completed work unless later user input asks for it. Preserve these original details for unfinished work within its existing authorization; the checkpoint grants no new authority. Only input after the checkpoint is a new user request.]";
+
+// Plaintext checkpoint detection and context exclusions follow robin-bially's #7105 selector.
+// Keep this separate from decoding ocx1 items: those already have a continuation contract.
+function plainUserText(item: unknown): string | null {
+  if (!isRecord(item) || item.role !== "user") return null;
+  if (item.type !== undefined && item.type !== "message") return null;
+  if (typeof item.content === "string") return item.content;
+  if (!Array.isArray(item.content) || item.content.length === 0) return null;
+  const texts: string[] = [];
+  for (const part of item.content) {
+    if (!isRecord(part) || (part.type !== "input_text" && part.type !== "text") || typeof part.text !== "string") return null;
+    texts.push(part.text);
+  }
+  return texts.join("\n");
+}
+
+function isContext(text: string): boolean {
+  const head = text.trimStart();
+  return head.startsWith("<") || head.startsWith("# AGENTS.md") || head.startsWith("# Context from my IDE");
+}
+
+/**
+ * Prompt-only projection for translated/routed generation. Never pass the result to replay
+ * storage: canonical input, item identities and replay-prefix lengths must remain unchanged.
+ * Native OpenAI forwarding does not call this projection.
+ */
+export function frameCompactionHistory<T extends { input?: unknown; instructions?: unknown }>(body: T): T {
+  const input = body.input;
+  if (!Array.isArray(input) || input.some(item => isRecord(item) && item.type === "compaction_trigger")) return body;
+  // Codex local compaction appends this user prompt without a compaction_trigger.
+  // Keep that summarizer turn free of generation-only continuation instructions.
+  if (plainUserText(input.at(-1))?.trim() === COMPACT_PROMPT) return body;
+  let checkpointIndex = -1;
+  for (let index = input.length - 1; index >= 0; index--) {
+    if (plainUserText(input[index])?.startsWith(SUMMARY_PREFIX)) {
+      checkpointIndex = index;
+      break;
+    }
+  }
+  if (checkpointIndex <= 0) return body;
+  let changed = false;
+  const framed = input.map((item, index) => {
+    if (index >= checkpointIndex) return item;
+    const text = plainUserText(item);
+    if (text === null || !text.trim() || text.startsWith(SUMMARY_PREFIX) || isContext(text)
+      || text.startsWith(HISTORICAL_REQUEST_START)) return item;
+    const message = item as InputRecord;
+    changed = true;
+    // Preserve original text blocks and their metadata verbatim, including block boundaries.
+    const content = typeof message.content === "string"
+      ? `${HISTORICAL_REQUEST_START}\n${message.content}\n${HISTORICAL_REQUEST_END}`
+      : [{ type: "input_text", text: HISTORICAL_REQUEST_START },
+        ...(message.content as unknown[]), { type: "input_text", text: HISTORICAL_REQUEST_END }];
+    return { ...message, content };
+  });
+  return changed ? { ...body, input: framed, instructions: appendCheckpointContinuationNote(body.instructions) } : body;
+}

package/src/responses/compaction.ts

@@ -15,6 +15,7 @@
  * routed models get a short "history was compacted" note instead.
  */
 
+import { decodeRetainedCompaction, RETAINED_COMPACTION_PREFIX } from "./retained-compaction";
 import type { TranslatorBudget } from "../lib/translator-budget";
 
 const ciphertextLeases = new WeakMap<object, { budget: TranslatorBudget; bytes: number }>();
@@ -57,7 +58,7 @@ export const SUMMARY_PREFIX = "Another language model started to solve this prob
 export const OPAQUE_COMPACTION_NOTE = "[earlier conversation was compacted; the summary is stored in a format this model cannot read]";
 
 /**
- * Prompt contract for a routed model receiving a decoded `ocx1` checkpoint as user text (#6764).
+ * Prompt contract for a routed model receiving a decoded `ocx1`/`ocx2` checkpoint as user text (#6764).
  * It preserves existing authorization scope and permission gates; it grants no authority.
  * Kept apart from SUMMARY_PREFIX, which the v1 retention and recovery paths match exactly.
  */
@@ -94,6 +95,10 @@ export function encodeCompactionSummary(summary: string): string {
 
 /** Decode an `ocx1:` envelope; returns null for real (OpenAI-encrypted) blobs or garbage. */
 export function decodeCompactionSummary(encryptedContent: string): string | null {
+  if (encryptedContent.startsWith(RETAINED_COMPACTION_PREFIX)) {
+    const retained = decodeRetainedCompaction(encryptedContent);
+    return retained ? [retained.summary, ...retained.reasoning].join("\n\n") : null;
+  }
   if (!encryptedContent.startsWith(OCX_COMPACTION_PREFIX)) return null;
   try {
     return Buffer.from(encryptedContent.slice(OCX_COMPACTION_PREFIX.length), "base64").toString("utf-8");

package/src/responses/incomplete-reason.ts

@@ -0,0 +1,31 @@
+import { truncationReasonFor } from "./truncated-stop-reason";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeResponse(value: unknown): unknown {
+  if (!record(value) || !record(value.incomplete_details)) return value;
+  const details = value.incomplete_details;
+  if (typeof details.reason !== "string") return value;
+  const reason = truncationReasonFor(details.reason);
+  return reason !== undefined && reason !== details.reason
+    ? { ...value, incomplete_details: { ...details, reason } }
+    : value;
+}
+
+/** Normalize only Responses metadata, never output content or unknown provider reasons. */
+export function normalizeResponsesIncompleteReason<T>(payload: T): T {
+  if (!record(payload)) return payload;
+  const root = normalizeResponse(payload) as Record<string, unknown>;
+  const response = normalizeResponse(root.response);
+  return (response === root.response ? root : { ...root, response }) as T;
+}
+
+/** Identity for malformed JSON and unchanged metadata, preserving upstream framing on SSE. */
+export function rewriteResponsesIncompleteReasonJson(json: string): string {
+  let payload: unknown;
+  try { payload = JSON.parse(json); } catch { return json; }
+  const normalized = normalizeResponsesIncompleteReason(payload);
+  return normalized === payload ? json : JSON.stringify(normalized);
+}

package/src/responses/parser.ts

@@ -1,3 +1,4 @@
+import { anthropicProgressEnvelope, isAnthropicProgressMirror } from "./anthropic-progress";
 import type {
   OcxAssistantMessage,
   OcxContentPart,
@@ -15,7 +16,8 @@ import { createToolChoiceResolver, namespacedToolName } from "../types";
 import { responsesRequestSchema } from "./schema";
 import { providerMetadataFromResponsesFunctionCall } from "./provider-opaque-metadata";
 import { lookupReplayThoughtSignature } from "./thought-signature-replay";
-import { CHECKPOINT_CONTINUATION_NOTE, compactionItemToText, decodeCompactionSummary, isCompactionItemType } from "./compaction";
+import { decodeRetainedCompaction, RETAINED_COMPACTION_PREFIX } from "./retained-compaction";
+import { CHECKPOINT_CONTINUATION_NOTE, compactionItemToText, decodeCompactionSummary, isCompactionItemType, SUMMARY_PREFIX } from "./compaction";
 import { previousResponseReplayPrefixLength } from "./state";
 import { decodeReasoningEnvelope } from "./reasoning-envelope";
 import { hasRoutedIdentity, nameRoutedIdentity } from "../adapters/identity";
@@ -28,6 +30,7 @@ import { mapToolChoice, buildTools, customToolNamespaces } from "./parser-tools"
 import { parseTextFormat } from "./parser-text-format";
 import { externalTaskInputContent } from "./task-input";
 import { normalizeVisualizationContext } from "./visualization-directives";
+import { frameCompactionHistory } from "./compaction-history-framing";
 
 /**
  * Wrap a remembered proxy-side signature as provider metadata for a replayed tool call.
@@ -66,6 +69,69 @@ function repairJsonObjectEnvelope(text: string): Record<string, unknown> | undef
   return undefined;
 }
 
+/**
+ * Repair the observed MiMo tool-call corruption: the model emits its proprietary
+ * `</function></tool_call>` closing tags INSIDE the JSON string value of the
+ * function arguments, and drops the JSON object's closing brace. Strip the
+ * suffix, restore the brace, and only accept the repair when the result parses
+ * into an object.
+ */
+function repairMimoToolCallEnvelope(text: string): Record<string, unknown> | undefined {
+  const suffix = "</function></tool_call>";
+  if (!text.endsWith(suffix)) return undefined;
+  const stripped = text.slice(0, -suffix.length);
+  if (!stripped.startsWith("{")) return undefined;
+  // A trailing brace or quote can itself belong to the unterminated string.
+  // Try only the three observed envelope endings, accepting an object parse.
+  for (const candidate of [stripped, `${stripped}}`, `${stripped}"}`]) {
+    try {
+      const parsed: unknown = JSON.parse(candidate);
+      if (isObj(parsed)) return parsed;
+    } catch {
+      /* try the next bounded envelope ending */
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Decode a function call's serialized arguments the way history replay tolerates them: empty
+ * or non-JSON text becomes `{}` instead of failing every later turn, and the bounded
+ * lost-brace and MiMo closing-tag corruptions above are repaired. Shared with the direct Chat decoder
+ * (`src/protocols/codecs/chat-ir.ts`) so both decode the same call to the same object.
+ */
+export function functionCallArgumentsFromText(callId: string, rawArguments: string | undefined): Record<string, unknown> {
+  let args: Record<string, unknown> = {};
+  const rawArgs = rawArguments?.trim();
+  if (rawArgs) {
+    try {
+      const parsed: unknown = JSON.parse(rawArgs);
+      if (isObj(parsed)) args = parsed;
+    } catch {
+      // Corruptions observed on Xiaomi MiMo routed requests, each with a bounded
+      // repair so a serialized call the model can still see is restored instead
+      // of replaying {} forever.
+      const mimoRepaired = repairMimoToolCallEnvelope(rawArgs);
+      if (mimoRepaired !== undefined) {
+        args = mimoRepaired;
+        console.warn(`[parser] function_call ${callId} repaired MiMo tool-call envelope (tags inside string)`);
+        return args;
+      }
+      // One observed serialization corruption loses exactly the JSON object's opening
+      // brace; the closed envelope is tight enough to repair back into a call the
+      // routed model can still see and retry, instead of replaying {} forever.
+      const repaired = repairJsonObjectEnvelope(rawArgs);
+      if (repaired === undefined) {
+        console.warn(`[parser] function_call ${callId} has non-JSON arguments; defaulting to {}`);
+      } else {
+        args = repaired;
+        console.warn(`[parser] function_call ${callId} arguments lost the JSON opening brace; repaired from history`);
+      }
+    }
+  }
+  return args;
+}
+
 
 
 function ensureAssistantPlaceholder(messages: OcxMessage[], modelId: string, now: number): OcxAssistantMessage {
@@ -160,7 +226,7 @@ export function parseRequest(
   if (!parsed.success) {
     throw new Error(`responses parse error: ${parsed.error.message}`);
   }
-  const data = parsed.data;
+  const data = frameCompactionHistory(parsed.data);
   const now = Date.now();
   const messages: OcxMessage[] = [];
   // Built before the item loop: a custom_tool_call echoed back in `input` needs the
@@ -210,6 +276,7 @@ export function parseRequest(
   } else if (data.input) {
     for (let inputIndex = 0; inputIndex < data.input.length; inputIndex++) {
       const item = data.input[inputIndex];
+      if (inputIndex > 0 && isAnthropicProgressMirror(item, anthropicProgressEnvelope(data.input[inputIndex - 1]))) continue;
       const effectiveType = (item as { type?: string }).type ?? ("role" in item ? "message" : undefined);
       const itemRole = (item as { role?: string }).role;
       const externalTaskInput = effectiveType === "function_call_output" ? externalTaskInputContent(item) : undefined;
@@ -252,7 +319,7 @@ export function parseRequest(
       }
 
       if (isCompactionItemType(effectiveType)) {
-        // A stored summary from a previous compaction. Decode our ocx1 envelope into plain text so
+        // A stored summary from a previous compaction. Decode our ocx1/ocx2 envelopes into plain text so
         // the routed model keeps the compacted context; real OpenAI-encrypted blobs degrade to a note.
         // `context_compaction` (encrypted_content optional) is codex-rs's local-compaction marker;
         // with no payload it is a pure marker (the summary follows as its own user message), so it
@@ -264,6 +331,13 @@ export function parseRequest(
         if (effectiveType === "context_compaction" && typeof encrypted !== "string") continue;
         if (typeof encrypted === "string" && decodeCompactionSummary(encrypted) !== null) decodedCheckpoint = true;
         pendingReasoning.length = 0;
+        if (typeof encrypted === "string" && encrypted.startsWith(RETAINED_COMPACTION_PREFIX)) {
+          const retained = decodeRetainedCompaction(encrypted);
+          if (!retained) throw new Error("Invalid OpenCodex retained compaction envelope");
+          messages.push({ role: "user", content: `${SUMMARY_PREFIX}\n\n${retained.summary}`, timestamp: now });
+          messages.push(...retained.reasoning.map(content => ({ role: "user" as const, content, timestamp: now })));
+          continue;
+        }
         messages.push({
           role: "user",
           content: compactionItemToText(typeof encrypted === "string" ? encrypted : undefined),
@@ -397,25 +471,7 @@ export function parseRequest(
         const call = item as { id?: string; call_id: string; name: string; arguments?: string; namespace?: string; extra_content?: unknown };
         // Tolerate empty/non-JSON arguments (e.g. a no-arg tool call serialized as "") instead of
         // throwing — a single poisoned history item would otherwise 400 every subsequent turn.
-        let args: Record<string, unknown> = {};
-        const rawArgs = call.arguments?.trim();
-        if (rawArgs) {
-          try {
-            const parsed: unknown = JSON.parse(rawArgs);
-            if (isObj(parsed)) args = parsed;
-          } catch {
-            // One observed serialization corruption loses exactly the JSON object's opening
-            // brace; the closed envelope is tight enough to repair back into a call the
-            // routed model can still see and retry, instead of replaying {} forever.
-            const repaired = repairJsonObjectEnvelope(rawArgs);
-            if (repaired === undefined) {
-              console.warn(`[parser] function_call ${call.call_id} has non-JSON arguments; defaulting to {}`);
-            } else {
-              args = repaired;
-              console.warn(`[parser] function_call ${call.call_id} arguments lost the JSON opening brace; repaired from history`);
-            }
-          }
-        }
+        const args = functionCallArgumentsFromText(call.call_id, call.arguments);
         // Do NOT map Responses item `id` (fc_/ctc_/…) onto `thoughtSignature`. That field is
         // reserved for Gemini/Antigravity opaque thought tokens; forwarding item ids as
         // thoughtSignature 400s Antigravity (Base64 / TYPE_BYTES). Continuity for CCA comes from

package/src/responses/reasoning-envelope.ts

@@ -20,6 +20,8 @@ export const OCX_REASONING_PREFIX = "ocxr1:";
 export interface ReasoningEnvelope {
   /** Anthropic thinking-block signature (signature_delta), if captured. */
   sig?: string;
+  /** ID of the immediately following commentary copy of this signed thinking block. */
+  upd?: string;
   /** Raw redacted_thinking block data payloads, order preserved. */
   red?: string[];
   /**
@@ -133,6 +135,8 @@ export function decodeReasoningEnvelope(encryptedContent: string, budget?: Trans
       const obj = parsed as { sig?: unknown; red?: unknown };
       const envelope: ReasoningEnvelope = {};
       if (typeof obj.sig === "string") envelope.sig = obj.sig;
+      const upd = (parsed as { upd?: unknown }).upd;
+      if (typeof upd === "string" && /^msg_[a-f0-9]{32}$/.test(upd)) envelope.upd = upd;
       if (Array.isArray(obj.red)) {
         const red = obj.red.filter((r): r is string => typeof r === "string");
         if (red.length > 0) envelope.red = red;

package/src/responses/reasoning-replay-cache.ts

@@ -200,12 +200,34 @@ function sweepExpiredOpaqueBlobRejections(at: number): void {
 export function reasoningReplayServingIdentityChanged(
   scope: OcxReasoningReplayScopeRef | undefined,
 ): boolean {
+  return reasoningReplayServingIdentityChange(scope) !== undefined;
+}
+
+/** Known durable route differences; an unknown issuer never establishes compatibility. */
+export function reasoningReplayServingIdentityChange(
+  scope: OcxReasoningReplayScopeRef | undefined,
+): {
+  providerChanged: boolean;
+  destinationChanged: boolean;
+  adapterChanged: boolean;
+  modelChanged: boolean;
+  credentialChanged: boolean;
+} | undefined {
   const current = servingIdentityFor(scope);
-  if (!current) return false;
+  if (!current) return undefined;
   const at = now();
   sweepExpiredServingIdentities(at);
   const previous = servingIdentities.get(current.threadId);
-  return previous !== undefined && previous.identity !== current.identity;
+  if (previous === undefined || previous.identity === current.identity) return undefined;
+  const before = JSON.parse(previous.identity) as ReasoningReplayIdentityTuple;
+  const after = JSON.parse(current.identity) as ReasoningReplayIdentityTuple;
+  return {
+    providerChanged: before[0] !== after[0],
+    destinationChanged: before[1] !== after[1],
+    adapterChanged: before[2] !== after[2],
+    modelChanged: before[3] !== after[3],
+    credentialChanged: before[4] !== after[4],
+  };
 }
 
 /**

package/src/responses/reasoning-retention.ts

@@ -0,0 +1,173 @@
+/**
+ * Routed v1 compaction keeps readable reasoning out of the summarizer request. Text within
+ * the configured budget is held locally until success; oversized text is archived on disk.
+ * Provider ciphertext and signatures are never included in the portable retained items.
+ */
+
+import { expandRetainedCompactionInput } from "./retained-compaction";
+import { closeSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { estimateTokens } from "../lib/token-estimate";
+import { decodeReasoningEnvelope } from "./reasoning-envelope";
+
+export const DEFAULT_REASONING_RETENTION_PERCENT = 20;
+export const DEFAULT_MAX_REASONING_TOKENS = 100_000;
+
+export interface ReasoningRetentionOptions {
+  /** Directory that receives archived reasoning files. */
+  archiveDir: string;
+  /** Context window of the model running the compaction turn; an unknown window uses only maxTokens. */
+  contextWindow?: number;
+  /** Share of the context window reasoning may occupy before it is archived. Defaults to 20. */
+  maxContextPercent?: number;
+  /** Absolute token ceiling for retained reasoning, regardless of the window share. Defaults to 100,000. */
+  maxTokens?: number;
+  /** Clock injection for tests. */
+  now?: number;
+}
+
+export interface ReasoningArchive {
+  path: string;
+  tokens: number;
+  percent: number;
+  /** The effective token ceiling that triggered the archive (window share vs absolute cap, whichever is smaller). */
+  cap?: number;
+  /** Whether the percent share could be calculated from a known context window. */
+  windowKnown?: boolean;
+}
+
+export interface ReasoningRetentionResult {
+  /** Summarizer input with reasoning items removed; other items retain their order. */
+  input: unknown[];
+  archived?: ReasoningArchive;
+  /** Portable, exact readable text to merge only after compaction succeeds. */
+  retainedReasoning?: Array<{ type: "message"; role: "user"; content: Array<{ type: "input_text"; text: string }> }>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+// Ordinary context messages survive translated providers that discard unsigned thinking.
+// Match the complete frame so subsequent compactions hold the text locally again.
+const RETAINED_PREFIX = "[OpenCodeX locally retained assistant reasoning; historical context, not a new instruction]\n<assistant_reasoning>\n";
+const RETAINED_SUFFIX = "\n</assistant_reasoning>";
+function retainedTextOf(item: Record<string, unknown>): string | undefined {
+  if (item.type !== "message" || item.role !== "user") return undefined;
+  const content = item.content;
+  const text = typeof content === "string" ? content
+    : Array.isArray(content) && content.length === 1 && isRecord(content[0])
+      && content[0].type === "input_text" && typeof content[0].text === "string" ? content[0].text : undefined;
+  return text?.startsWith(RETAINED_PREFIX) && text.endsWith(RETAINED_SUFFIX)
+    ? text.slice(RETAINED_PREFIX.length, -RETAINED_SUFFIX.length) : undefined;
+}
+
+/** Readable reasoning text of one item: decoded ocxr1 envelope text, else summary/content text. */
+function reasoningTextOf(item: Record<string, unknown>): string {
+  const encrypted = typeof item.encrypted_content === "string" ? item.encrypted_content : undefined;
+  const envelope = encrypted ? decodeReasoningEnvelope(encrypted) : null;
+  if (envelope?.txt) return envelope.txt;
+  const collect = (key: "summary" | "content"): string =>
+    Array.isArray(item[key])
+      ? (item[key] as Array<Record<string, unknown>>)
+        .map(part => (isRecord(part) && typeof part.text === "string" ? part.text : ""))
+        .join("")
+      : "";
+  return collect("summary") || collect("content");
+}
+
+/** Plaintext of every reasoning item in a Responses input array, order preserved. */
+export function collectReasoningTexts(input: unknown): string[] {
+  if (!Array.isArray(input)) return [];
+  const texts: string[] = [];
+  for (const item of input) {
+    if (!isRecord(item)) continue;
+    const text = item.type === "reasoning" ? reasoningTextOf(item) : retainedTextOf(item) ?? "";
+    if (text.length > 0) texts.push(text);
+  }
+  return texts;
+}
+
+function retentionPercent(value: number | undefined): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 100
+    ? value
+    : DEFAULT_REASONING_RETENTION_PERCENT;
+}
+
+function retentionTokenCap(value: number | undefined): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MAX_REASONING_TOKENS;
+}
+
+/** Separate reasoning locally before dispatch; unknown windows enforce the absolute cap. */
+export function applyReasoningRetention(
+  input: unknown,
+  options: ReasoningRetentionOptions,
+): ReasoningRetentionResult {
+  if (!Array.isArray(input)) return { input: [] };
+  input = expandRetainedCompactionInput(input);
+  if (!Array.isArray(input)) return { input: [] };
+  const texts = collectReasoningTexts(input);
+  const retained = input.filter(item => !(isRecord(item) && (item.type === "reasoning" || retainedTextOf(item) !== undefined)));
+  if (texts.length === 0) return { input: retained.length === input.length ? input : retained };
+  const window = options.contextWindow;
+
+  const percent = retentionPercent(options.maxContextPercent);
+  const cap = retentionTokenCap(options.maxTokens);
+  // The window share alone inflates without bound on 1M-window models (20% of 1M is ~210K
+  // tokens), so an absolute ceiling applies on top of it: reasoning keeps at most the
+  // SMALLER of the two limits. An unknown window leaves the percent share unusable, so the
+  // absolute cap alone stands guard.
+  const windowKnown = typeof window === "number" && Number.isInteger(window) && window > 0;
+  const limit = windowKnown ? Math.min(Math.floor(window * (percent / 100)), cap) : cap;
+  const framedTexts = texts.map(text => RETAINED_PREFIX + text + RETAINED_SUFFIX);
+  // Budget the historical context that is actually replayed, including every block's frame.
+  const tokens = estimateTokens(framedTexts.join("\n"));
+  if (tokens <= limit) return {
+    input: retained,
+    retainedReasoning: framedTexts.map(text => ({ type: "message", role: "user",
+      content: [{ type: "input_text", text }] })),
+  };
+
+  mkdirSync(options.archiveDir, { recursive: true, mode: 0o700 });
+  const stamp = new Date(options.now ?? Date.now()).toISOString().replace(/[:.]/g, "-");
+  const path = join(options.archiveDir, "reasoning-" + stamp + "-" + Math.random().toString(36).slice(2, 8) + ".md");
+  // Only a successful exclusive open grants ownership; an occupied path is never removed.
+  const fd = openSync(path, "wx", 0o600);
+  let failure: unknown;
+  try { writeFileSync(fd, texts.join("\n\n---\n\n"), "utf-8"); } catch (error) { failure = error; }
+  try { closeSync(fd); } catch (error) { failure ??= error; }
+  if (failure !== undefined) {
+    try { rmSync(path); } catch { /* preserve the original I/O error; cleanup is best-effort */ }
+    throw failure;
+  }
+
+  const limitDescription = windowKnown
+    ? percent + "% of the context window, capped at " + limit + " tokens"
+    : "absolute cap of " + limit + " tokens (context window unknown)";
+  const note = [
+    "[reasoning archived locally] " + texts.length + " reasoning block(s) totalling ~" + tokens + " tokens",
+    "exceeded the configured retention limit (" + limitDescription + ") and were moved out of band.",
+    "Full text: " + path,
+  ].join(" ");
+  const triggerIndex = retained.findIndex(item => isRecord(item) && item.type === "compaction_trigger");
+  const noteItem = { type: "message", role: "user", content: note };
+  if (triggerIndex >= 0) retained.splice(triggerIndex, 0, noteItem);
+  else retained.push(noteItem);
+  return { input: retained, archived: { path, tokens, percent, cap: limit, windowKnown } };
+}
+
+/**
+ * User-visible notice appended to a compaction summary when reasoning was archived. The summary
+ * is what the next model and the user both read, so the notice lives there rather than in a log.
+ */
+export function appendRetentionNotice(summary: string, archived: ReasoningArchive | undefined): string {
+  if (!archived) return summary;
+  const limitDescription = archived.windowKnown === false
+    ? "absolute cap of " + (archived.cap ?? "unknown") + " tokens (context window unknown)"
+    : archived.percent + "% of the context window (effective cap: " + (archived.cap ?? "unknown") + " tokens)";
+  return summary + "\n\n[reasoning retention notice] Reasoning of ~" + archived.tokens + " tokens exceeded " + limitDescription
+    + " and was archived locally at " + archived.path
+    + ". This summary covers conclusions only; read that file for the full reasoning.";
+}

package/src/responses/retained-compaction.ts

@@ -0,0 +1,46 @@
+/** Versioned, proxy-owned compaction data. This is encoding, never provider ciphertext. */
+export const RETAINED_COMPACTION_PREFIX = "ocx2:";
+
+export interface RetainedCompaction {
+  version: 2;
+  summary: string;
+  /** Already framed historical context, preserved byte-for-byte on replay. */
+  reasoning: string[];
+}
+
+export function encodeRetainedCompaction(summary: string, reasoning: string[]): string {
+  return RETAINED_COMPACTION_PREFIX + Buffer.from(JSON.stringify({ version: 2, summary, reasoning }), "utf-8").toString("base64");
+}
+
+export function decodeRetainedCompaction(value: string): RetainedCompaction | null {
+  if (!value.startsWith(RETAINED_COMPACTION_PREFIX)) return null;
+  try {
+    const payload = value.slice(RETAINED_COMPACTION_PREFIX.length);
+    const bytes = Buffer.from(payload, "base64");
+    if (bytes.toString("base64") !== payload) return null;
+    const parsed: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const item = parsed as Record<string, unknown>;
+    if (Object.keys(item).some(key => !["version", "summary", "reasoning"].includes(key))
+      || item.version !== 2 || typeof item.summary !== "string" || !item.summary.trim()
+      || !Array.isArray(item.reasoning) || !item.reasoning.every(text => typeof text === "string")) return null;
+    return item as unknown as RetainedCompaction;
+  } catch { return null; }
+}
+
+/** Expand only our structured envelopes; callers retain their existing native/ocx1 policy. */
+export function expandRetainedCompactionInput(input: unknown): unknown {
+  if (!Array.isArray(input)) return input;
+  if (!input.some(item => item && typeof item === "object" && ["compaction", "compaction_summary", "context_compaction"].includes(item.type)
+    && typeof item.encrypted_content === "string" && item.encrypted_content.startsWith(RETAINED_COMPACTION_PREFIX))) return input;
+  return input.flatMap(item => {
+    if (!item || typeof item !== "object" || !["compaction", "compaction_summary", "context_compaction"].includes(item.type)
+      || typeof item.encrypted_content !== "string" || !item.encrypted_content.startsWith(RETAINED_COMPACTION_PREFIX)) return [item];
+    const data = decodeRetainedCompaction(item.encrypted_content);
+    if (!data) throw new Error("Invalid OpenCodex retained compaction envelope");
+    return [
+      { ...item, encrypted_content: "ocx1:" + Buffer.from(data.summary, "utf-8").toString("base64") },
+      ...data.reasoning.map(text => ({ type: "message", role: "user", content: [{ type: "input_text", text }] })),
+    ];
+  });
+}