@bitkyc08/opencodex 2.6.26-preview.20260705 → 2.6.28-preview.20260707

package/src/providers/api-keys.ts

@@ -0,0 +1,121 @@
+/**
+ * Multi-key pool for key-auth providers (the API-key twin of OAuth multiauth).
+ *
+ * `provider.apiKey` stays the single source of truth for routing — it always mirrors the
+ * ACTIVE pool entry, so the router/adapters never learn about the pool. The pool itself
+ * lives in `provider.apiKeyPool` in config.json (same file that already holds apiKey).
+ * A provider with a legacy bare `apiKey` is seeded into a one-entry pool on first touch.
+ */
+import { createHash } from "node:crypto";
+import { saveConfig } from "../config";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+
+export interface ProviderApiKeyInfo {
+  id: string;
+  label?: string;
+  /** First/last 4 chars only; env references (`${VAR}`) are shown verbatim (not secrets). */
+  masked: string;
+  active: boolean;
+  addedAt?: number;
+}
+
+function isEnvReference(value: string): boolean {
+  return /^\$\{?\w+\}?$/.test(value);
+}
+
+export function maskApiKey(value: string): string {
+  if (isEnvReference(value)) return value;
+  if (value.length <= 8) return "****";
+  return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+
+/** Content-derived id: re-adding the same key upserts instead of duplicating. */
+function keyId(key: string): string {
+  return createHash("sha256").update(key).digest("hex").slice(0, 8);
+}
+
+/** True for providers whose upstream auth is a configured API key (not oauth/forward). */
+export function isKeyAuthProvider(provider: OcxProviderConfig): boolean {
+  return provider.authMode !== "oauth" && provider.authMode !== "forward";
+}
+
+/** Seed the pool from a legacy bare `apiKey`, and keep `apiKey` mirrored to the active entry. */
+function ensurePool(provider: OcxProviderConfig): NonNullable<OcxProviderConfig["apiKeyPool"]> {
+  if (!provider.apiKeyPool) provider.apiKeyPool = [];
+  if (provider.apiKeyPool.length === 0 && provider.apiKey) {
+    provider.apiKeyPool.push({ id: keyId(provider.apiKey), key: provider.apiKey });
+  }
+  return provider.apiKeyPool;
+}
+
+function activeEntryId(provider: OcxProviderConfig): string | null {
+  const pool = provider.apiKeyPool ?? [];
+  if (pool.length === 0) return null;
+  return (pool.find(e => e.key === provider.apiKey) ?? pool[0]!).id;
+}
+
+export function listProviderApiKeys(config: OcxConfig, name: string): { activeId: string | null; keys: ProviderApiKeyInfo[] } {
+  const provider = config.providers[name];
+  if (!provider || !isKeyAuthProvider(provider)) return { activeId: null, keys: [] };
+  const pool = ensurePool(provider);
+  const activeId = activeEntryId(provider);
+  return {
+    activeId,
+    keys: pool.map(entry => ({
+      id: entry.id,
+      ...(entry.label ? { label: entry.label } : {}),
+      masked: maskApiKey(entry.key),
+      active: entry.id === activeId,
+      ...(entry.addedAt !== undefined ? { addedAt: entry.addedAt } : {}),
+    })),
+  };
+}
+
+/** Add (or upsert) a key and make it ACTIVE. Persists config. */
+export function addProviderApiKey(config: OcxConfig, name: string, key: string, label?: string): { id: string } | { error: string } {
+  const provider = config.providers[name];
+  if (!provider || !isKeyAuthProvider(provider)) return { error: "provider does not use API-key auth" };
+  const trimmed = key.trim();
+  if (!trimmed) return { error: "key is required" };
+  if (/[\r\n]/.test(trimmed)) return { error: "key must not include line breaks" };
+  const pool = ensurePool(provider);
+  const id = keyId(trimmed);
+  const existing = pool.find(e => e.id === id);
+  if (existing) {
+    if (label?.trim()) existing.label = label.trim();
+  } else {
+    pool.push({ id, key: trimmed, ...(label?.trim() ? { label: label.trim() } : {}), addedAt: Date.now() });
+  }
+  provider.apiKey = trimmed;
+  saveConfig(config);
+  return { id };
+}
+
+/** Switch the ACTIVE key (mirrors into `provider.apiKey`). Persists config. */
+export function setActiveProviderApiKey(config: OcxConfig, name: string, id: string): boolean {
+  const provider = config.providers[name];
+  if (!provider || !isKeyAuthProvider(provider)) return false;
+  const entry = ensurePool(provider).find(e => e.id === id);
+  if (!entry) return false;
+  provider.apiKey = entry.key;
+  saveConfig(config);
+  return true;
+}
+
+/** Remove one key; removing the active one promotes the first remaining. Persists config. */
+export function removeProviderApiKey(config: OcxConfig, name: string, id: string): boolean {
+  const provider = config.providers[name];
+  if (!provider || !isKeyAuthProvider(provider)) return false;
+  const pool = ensurePool(provider);
+  const entry = pool.find(e => e.id === id);
+  if (!entry) return false;
+  provider.apiKeyPool = pool.filter(e => e.id !== id);
+  if (provider.apiKey === entry.key) {
+    const next = provider.apiKeyPool[0];
+    if (next) provider.apiKey = next.key;
+    else delete provider.apiKey;
+  }
+  if (provider.apiKeyPool.length === 0) delete provider.apiKeyPool;
+  saveConfig(config);
+  return true;
+}

package/src/{provider-context-cap.ts → providers/context-cap.ts}

@@ -1,4 +1,4 @@
-import type { OcxConfig } from "./types";
+import type { OcxConfig } from "../types";
 
 export const DEFAULT_PROVIDER_CONTEXT_CAP = 350_000;
 

package/src/providers/derive.ts

@@ -82,6 +82,7 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.noPenaltyModels ? { noPenaltyModels: [...entry.noPenaltyModels] } : {}),
     ...(entry.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...entry.autoToolChoiceOnlyModels] } : {}),
     ...(entry.preserveReasoningContentModels ? { preserveReasoningContentModels: [...entry.preserveReasoningContentModels] } : {}),
+    ...(entry.thinkingToggleModels ? { thinkingToggleModels: [...entry.thinkingToggleModels] } : {}),
     ...(entry.escapeBuiltinToolNames !== undefined ? { escapeBuiltinToolNames: entry.escapeBuiltinToolNames } : {}),
     ...(entry.googleMode ? { googleMode: entry.googleMode } : {}),
     ...(entry.project ? { project: entry.project } : {}),
@@ -178,6 +179,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (!prov.noPenaltyModels && seed.noPenaltyModels) prov.noPenaltyModels = [...seed.noPenaltyModels];
   if (!prov.autoToolChoiceOnlyModels && seed.autoToolChoiceOnlyModels) prov.autoToolChoiceOnlyModels = [...seed.autoToolChoiceOnlyModels];
   if (!prov.preserveReasoningContentModels && seed.preserveReasoningContentModels) prov.preserveReasoningContentModels = [...seed.preserveReasoningContentModels];
+  if (!prov.thinkingToggleModels && seed.thinkingToggleModels) prov.thinkingToggleModels = [...seed.thinkingToggleModels];
   if (prov.escapeBuiltinToolNames === undefined && seed.escapeBuiltinToolNames !== undefined) prov.escapeBuiltinToolNames = seed.escapeBuiltinToolNames;
 }
 

package/src/providers/key-failover.ts

@@ -0,0 +1,145 @@
+/**
+ * Multi-key 429 failover for non-OpenAI providers.
+ *
+ * When a provider's upstream returns 429, this module picks the next available key
+ * from `apiKeyPool`, puts the exhausted key into cooldown (respecting Retry-After),
+ * and returns a fresh provider config with the swapped key. If all keys are in
+ * cooldown, returns null so the caller surfaces the 429 to the client.
+ *
+ * Modelled after src/codex/routing.ts cooldown logic but scoped to plain API-key pools.
+ */
+import { saveConfig } from "../config";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+
+// ---- cooldown state (in-memory, same as codex/routing.ts) ----
+
+interface KeyCooldown {
+  cooldownUntil: number;
+}
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 10 * 60_000; // cap at 10 min for api-key rotation
+
+/** Map<`${providerName}\0${keyId}`, KeyCooldown> */
+const keyCooldowns = new Map<string, KeyCooldown>();
+
+function cooldownKey(providerName: string, keyId: string): string {
+  return `${providerName}\0${keyId}`;
+}
+
+function parseRetryAfterMs(value: string | null | undefined, now = Date.now()): number | undefined {
+  const text = value?.trim();
+  if (!text) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const seconds = Number(text);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
+    }
+  }
+  const timestamp = Date.parse(text);
+  if (!Number.isFinite(timestamp)) return undefined;
+  const delay = timestamp - now;
+  return delay > 0 ? Math.min(delay, MAX_COOLDOWN_MS) : undefined;
+}
+
+function isKeyInCooldown(providerName: string, keyId: string, now = Date.now()): boolean {
+  const entry = keyCooldowns.get(cooldownKey(providerName, keyId));
+  if (!entry) return false;
+  if (entry.cooldownUntil <= now) {
+    keyCooldowns.delete(cooldownKey(providerName, keyId));
+    return false;
+  }
+  return true;
+}
+
+// ---- public API ----
+
+/**
+ * Check whether a provider has multiple keys available for failover.
+ * Returns true only for key-auth providers with 2+ pool entries.
+ */
+export function hasKeyPoolFailover(provider: OcxProviderConfig): boolean {
+  if (provider.authMode === "oauth" || provider.authMode === "forward") return false;
+  return (provider.apiKeyPool?.length ?? 0) >= 2;
+}
+
+/**
+ * Record a 429 for the current key and attempt to switch to the next available one.
+ *
+ * @returns A new OcxProviderConfig with the swapped key (and mutated config on disk),
+ *          or `null` when no alternative key is available (all in cooldown or pool < 2).
+ */
+export function rotateKeyOn429(
+  config: OcxConfig,
+  providerName: string,
+  retryAfterHeader: string | null | undefined,
+  now = Date.now(),
+  attemptedKey?: string,
+): OcxProviderConfig | null {
+  const provider = config.providers[providerName];
+  if (!provider) return null;
+  if (provider.authMode === "oauth" || provider.authMode === "forward") return null;
+
+  const pool = provider.apiKeyPool;
+  if (!pool || pool.length < 2) return null;
+
+  // Cool the key that ACTUALLY failed. Under concurrent 429s another request may already have
+  // rotated provider.apiKey — cooling the live key would punish an innocent replacement and can
+  // exhaust a 2-key pool from a single bad key. CAS semantics: callers pass the key they used.
+  const failedKey = attemptedKey ?? provider.apiKey;
+  const currentEntry = pool.find(e => e.key === failedKey);
+  if (currentEntry) {
+    const cooldownMs = parseRetryAfterMs(retryAfterHeader, now) ?? DEFAULT_COOLDOWN_MS;
+    keyCooldowns.set(cooldownKey(providerName, currentEntry.id), {
+      cooldownUntil: now + cooldownMs,
+    });
+  }
+
+  // Lost the race: someone already rotated away from the failed key. If the live key is healthy,
+  // retry with it as-is instead of rotating a second time.
+  if (attemptedKey !== undefined && provider.apiKey !== attemptedKey) {
+    const liveEntry = pool.find(e => e.key === provider.apiKey);
+    if (liveEntry && !isKeyInCooldown(providerName, liveEntry.id, now)) {
+      return { ...provider };
+    }
+  }
+
+  // Pick the next key that is NOT in cooldown
+  const currentIndex = currentEntry ? pool.indexOf(currentEntry) : -1;
+  for (let i = 1; i < pool.length; i++) {
+    const candidate = pool[(currentIndex + i) % pool.length]!;
+    if (!isKeyInCooldown(providerName, candidate.id, now)) {
+      // Swap active key
+      provider.apiKey = candidate.key;
+      saveConfig(config);
+      console.warn(
+        // Log ids only — labels are user-supplied free text and could carry secret material.
+        `[key-failover] ${providerName}: 429 on key ${currentEntry?.id ?? "?"}; rotating to key ${candidate.id}`,
+      );
+      return { ...provider };
+    }
+  }
+
+  // All keys in cooldown
+  console.warn(`[key-failover] ${providerName}: all ${pool.length} keys in cooldown; returning 429 to client`);
+  return null;
+}
+
+/** Clear cooldown state for a provider (e.g. after manual key management). */
+export function clearKeyCooldowns(providerName?: string): void {
+  if (!providerName) {
+    keyCooldowns.clear();
+    return;
+  }
+  const prefix = `${providerName}\0`;
+  for (const key of keyCooldowns.keys()) {
+    if (key.startsWith(prefix)) keyCooldowns.delete(key);
+  }
+}
+
+/** Visible-for-testing: get the cooldown-until timestamp for a key. */
+export function getKeyCooldownUntil(providerName: string, keyId: string, now = Date.now()): number | null {
+  const entry = keyCooldowns.get(cooldownKey(providerName, keyId));
+  if (!entry) return null;
+  return entry.cooldownUntil > now ? entry.cooldownUntil : null;
+}

package/src/{provider-label.ts → providers/label.ts}

@@ -1,4 +1,4 @@
-import { CODEX_ACCOUNT_LOG_LABEL_RE } from "./codex-account-label";
+import { CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
 
 function canonicalUsageProviderLabel(provider: string): string {
   return provider === "chatgpt" ? "openai" : provider;

package/src/{provider-quota.ts → providers/quota.ts}

@@ -1,10 +1,10 @@
-import { listCodexAuthAccounts } from "./codex-auth-api";
-import { MAIN_CODEX_ACCOUNT_ID } from "./codex-main-account";
-import { getValidAccessToken } from "./oauth";
-import { getCredential } from "./oauth/store";
-import { antigravityUserAgent } from "./adapters/client-fingerprint";
-import { getProviderRegistryEntry } from "./providers/registry";
-import type { OcxConfig, OcxProviderConfig } from "./types";
+import { listCodexAuthAccounts } from "../codex/auth-api";
+import { MAIN_CODEX_ACCOUNT_ID } from "../codex/main-account";
+import { getValidAccessToken } from "../oauth";
+import { getCredential } from "../oauth/store";
+import { antigravityUserAgent } from "../adapters/client-fingerprint";
+import { getProviderRegistryEntry } from "./registry";
+import type { OcxConfig, OcxProviderConfig } from "../types";
 
 const CACHE_TTL_MS = 5 * 60_000;
 const REQUEST_TIMEOUT_MS = 8_000;
@@ -43,6 +43,11 @@ export interface ProviderQuotaResponse {
 
 let cache: { key: string; ts: number; response: ProviderQuotaResponse } | null = null;
 
+/** Invalidate the report cache (e.g. after switching a provider's active account). */
+export function clearProviderQuotaCache(): void {
+  cache = null;
+}
+
 function cacheKey(config: OcxConfig): string {
   const providers = Object.entries(config.providers)
     .map(([name, provider]) => `${name}:${provider.authMode ?? "key"}:${provider.disabled === true ? "off" : "on"}:${provider.baseUrl}`)

package/src/providers/registry.ts

@@ -39,6 +39,7 @@ export interface ProviderRegistryEntry {
   noPenaltyModels?: string[];
   autoToolChoiceOnlyModels?: string[];
   preserveReasoningContentModels?: string[];
+  thinkingToggleModels?: string[];
   escapeBuiltinToolNames?: boolean;
   oauthId?: string;
   jawcodeBundle?: string;
@@ -55,13 +56,18 @@ export type ProviderConfigSeed = Pick<
   | "liveModels" | "contextWindow" | "modelContextWindows" | "modelInputModalities"
   | "reasoningEfforts" | "modelReasoningEfforts" | "reasoningEffortMap" | "modelReasoningEffortMap"
   | "noVisionModels" | "noReasoningModels" | "noTemperatureModels" | "noTopPModels" | "noPenaltyModels"
-  | "autoToolChoiceOnlyModels" | "preserveReasoningContentModels" | "escapeBuiltinToolNames"
+  | "autoToolChoiceOnlyModels" | "preserveReasoningContentModels" | "thinkingToggleModels" | "escapeBuiltinToolNames"
   | "googleMode" | "project" | "location"
 >;
 
 
 const OLLAMA_REASONING_MAP: Record<string, string> = { xhigh: "max" };
 
+// Shared between the OAuth (Claude account) and API-key Anthropic entries so both expose the
+// same static model seed.
+const ANTHROPIC_MODELS = ["claude-sonnet-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"];
+const ANTHROPIC_MODEL_CONTEXT_WINDOWS: Record<string, number> = { "claude-sonnet-5": 1_000_000 };
+
 const ZAI_GLM_52_MODELS = ["glm-5.2", "glm-5.2[1m]"];
 const ZAI_GLM_52_REASONING_EFFORTS = ["low", "medium", "high", "xhigh"];
 const ZAI_GLM_52_REASONING_MAP: Record<string, string> = {
@@ -73,6 +79,26 @@ const ZAI_GLM_52_REASONING_MAP: Record<string, string> = {
   xhigh: "max",
   max: "max",
 };
+
+/**
+ * Vendor thinking-toggle models (MiMo v2.x, GLM 5/5.1 on Zen Go): the wire knob is
+ * `thinking: {type: enabled|disabled}` — a binary. Advertise a two-step Codex ladder
+ * (low = thinking off, high = thinking on) and map efforts onto the toggle. Zen Go
+ * pass-through probed live 2026-07-07 (glm-5.2 toggle verified; mimo/minimax accept shape).
+ */
+const THINKING_TOGGLE_EFFORTS = ["low", "high"];
+const THINKING_TOGGLE_MAP: Record<string, string> = {
+  none: "disabled",
+  minimal: "disabled",
+  low: "disabled",
+  medium: "enabled",
+  high: "enabled",
+  xhigh: "enabled",
+  max: "enabled",
+};
+const OPENCODE_GO_THINKING_TOGGLE_MODELS = [
+  "mimo-v2.5", "mimo-v2.5-pro", "mimo-v2-omni", "mimo-v2-pro", "glm-5", "glm-5.1",
+];
 const DEEPSEEK_THINKING_MODELS = ["deepseek-v4-pro", "deepseek-v4-flash"];
 const DEEPSEEK_THINKING_EFFORTS = ["high", "xhigh"];
 const DEEPSEEK_THINKING_REASONING_MAP: Record<string, string> = {
@@ -148,6 +174,11 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     modelContextWindows: cursorModelContextWindows(CURSOR_STATIC_MODELS),
     modelInputModalities: cursorModelInputModalities(CURSOR_STATIC_MODELS),
     modelReasoningEfforts: cursorModelReasoningEfforts(CURSOR_STATIC_MODELS),
+    // Cursor's wire protocol never forwards image parts (request-builder emits an unsupported-
+    // content marker), so the vision sidecar covers ALL cursor models regardless of what the
+    // upstream model could natively do. Live-discovered models outside the static list fall back
+    // to the same marker until they appear here.
+    noVisionModels: cursorModelIds(CURSOR_STATIC_MODELS),
   },
   {
     id: "xai",
@@ -174,8 +205,24 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     oauthId: "anthropic",
     jawcodeBundle: "anthropic",
     note: "Log in with your Claude account",
-    models: ["claude-sonnet-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6", "claude-sonnet-4-6", "claude-haiku-4-5"],
-    modelContextWindows: { "claude-sonnet-5": 1_000_000 },
+    models: [...ANTHROPIC_MODELS],
+    modelContextWindows: { ...ANTHROPIC_MODEL_CONTEXT_WINDOWS },
+    defaultModel: "claude-sonnet-4-6",
+  },
+  {
+    id: "anthropic-apikey",
+    label: "Anthropic (API key)",
+    adapter: "anthropic",
+    baseUrl: "https://api.anthropic.com",
+    authKind: "key",
+    featured: true,
+    dashboardUrl: "https://console.anthropic.com/settings/keys",
+    jawcodeBundle: "anthropic",
+    extraMetadataAliases: ["anthropic-key"],
+    note: "Direct Anthropic API billing — no Claude subscription",
+    models: [...ANTHROPIC_MODELS],
+    liveModels: true,
+    modelContextWindows: { ...ANTHROPIC_MODEL_CONTEXT_WINDOWS },
     defaultModel: "claude-sonnet-4-6",
   },
   {
@@ -251,9 +298,24 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
       "glm-5.2": ZAI_GLM_52_REASONING_EFFORTS,
       "kimi-k2.7-code": [],
       "kimi-k2.7-code-highspeed": [],
+      ...Object.fromEntries(OPENCODE_GO_THINKING_TOGGLE_MODELS.map(id => [id, THINKING_TOGGLE_EFFORTS])),
     },
-    modelReasoningEffortMap: { "glm-5.2": ZAI_GLM_52_REASONING_MAP },
+    modelReasoningEffortMap: {
+      "glm-5.2": ZAI_GLM_52_REASONING_MAP,
+      ...Object.fromEntries(OPENCODE_GO_THINKING_TOGGLE_MODELS.map(id => [id, THINKING_TOGGLE_MAP])),
+    },
+    thinkingToggleModels: OPENCODE_GO_THINKING_TOGGLE_MODELS,
     noReasoningModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed"],
+    // Text-only Zen Go models (jawcode metadata) — the vision sidecar describes images for
+    // every model listed here (and the catalog advertises image input on their behalf).
+    // Kimi K2.7 Code accepts text+image+video: do NOT list it here.
+    noVisionModels: [
+      "glm-5.2", "glm-5", "glm-5.1",
+      "deepseek-v4-flash", "deepseek-v4-pro",
+      "mimo-v2-pro", "mimo-v2.5-pro",
+      "minimax-m2.5", "minimax-m2.7",
+      "qwen3.7-max",
+    ],
     noTemperatureModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed"],
     noTopPModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed"],
     noPenaltyModels: ["kimi-k2.7-code", "kimi-k2.7-code-highspeed"],

package/src/responses/compaction.ts

@@ -0,0 +1,117 @@
+/**
+ * Remote compaction v2 support for ROUTED providers.
+ *
+ * Codex decides "this provider supports remote compaction" by provider name (built-in `OpenAI`),
+ * and Design B points that provider at this proxy — so Codex sends remote compaction v2 requests
+ * for EVERY routed model. The request is a normal /responses call whose input ends with
+ * `{"type":"compaction_trigger"}`; codex-rs `collect_compaction_output` then requires the stream
+ * to carry EXACTLY ONE `{"type":"compaction","encrypted_content":...}` output item
+ * (compact_remote_v2.rs) or it fatals with "expected exactly one compaction output item".
+ *
+ * Routed models cannot produce OpenAI's encrypted blob, so the proxy runs the model as a plain
+ * summarizer and wraps the summary text in a transparent envelope: `ocx1:` + base64(utf8 summary).
+ * Codex stores the item and replays it in later input; the parser decodes our envelope back into
+ * plain text for routed models. Real OpenAI-encrypted blobs (no `ocx1:` prefix) are opaque —
+ * routed models get a short "history was compacted" note instead.
+ */
+
+export const OCX_COMPACTION_PREFIX = "ocx1:";
+
+/** Mirrors codex-rs core/templates/compact/prompt.md (the local-compaction instruction). */
+export const COMPACT_PROMPT = `You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
+
+Include:
+- Current progress and key decisions made
+- Important context, constraints, or user preferences
+- What remains to be done (clear next steps)
+- Any critical data, examples, or references needed to continue
+
+Be concise, structured, and focused on helping the next LLM seamlessly continue the work.`;
+
+/** Mirrors codex-rs core/templates/compact/summary_prefix.md (framing for a replayed summary). */
+export const SUMMARY_PREFIX = "Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis:";
+
+export const OPAQUE_COMPACTION_NOTE = "[earlier conversation was compacted; the summary is stored in a format this model cannot read]";
+
+export function encodeCompactionSummary(summary: string): string {
+  return OCX_COMPACTION_PREFIX + Buffer.from(summary, "utf-8").toString("base64");
+}
+
+/** Decode an `ocx1:` envelope; returns null for real (OpenAI-encrypted) blobs or garbage. */
+export function decodeCompactionSummary(encryptedContent: string): string | null {
+  if (!encryptedContent.startsWith(OCX_COMPACTION_PREFIX)) return null;
+  try {
+    return Buffer.from(encryptedContent.slice(OCX_COMPACTION_PREFIX.length), "base64").toString("utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Render a replayed compaction item as plain user-visible text for a routed model. */
+export function compactionItemToText(encryptedContent: string | undefined): string {
+  const decoded = typeof encryptedContent === "string" ? decodeCompactionSummary(encryptedContent) : null;
+  return decoded ? `${SUMMARY_PREFIX}\n\n${decoded}` : OPAQUE_COMPACTION_NOTE;
+}
+
+/**
+ * Remote compaction v1 (`POST /responses/compact`, unary) — codex-rs installs the returned
+ * `{"output":[ResponseItem...]}` as the REPLACEMENT history (compact_remote.rs
+ * process_compacted_history). Mirror codex-rs local `build_compacted_history`: recent real user
+ * messages within a token budget, then one user message `SUMMARY_PREFIX\n<summary>`. Plain user
+ * message items parse as real user messages on the codex side (event_mapping parse_user_message);
+ * contextual wrappers are filtered there, and v2-style `compaction` items are NOT expected here.
+ */
+
+/** codex-rs compact.rs COMPACT_USER_MESSAGE_MAX_TOKENS = 20k tokens (~4 chars/token). */
+const COMPACT_V1_RETAINED_CHAR_BUDGET = 20_000 * 4;
+
+/** Extract plain-text user messages from a Responses `input` array (for v1 compact retention). */
+export function extractCompactUserMessages(input: unknown): string[] {
+  if (!Array.isArray(input)) return [];
+  const out: string[] = [];
+  for (const item of input) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const rec = item as { type?: string; role?: string; content?: unknown };
+    if (rec.type !== undefined && rec.type !== "message") continue;
+    if (rec.role !== "user") continue;
+    let text = "";
+    if (typeof rec.content === "string") text = rec.content;
+    else if (Array.isArray(rec.content)) {
+      text = rec.content
+        .map(b => {
+          if (!b || typeof b !== "object") return "";
+          const block = b as { type?: string; text?: string };
+          return (block.type === "input_text" || block.type === "text") && typeof block.text === "string" ? block.text : "";
+        })
+        .join("");
+    }
+    if (text.trim().length > 0) out.push(text);
+  }
+  return out;
+}
+
+function compactUserMessageItem(text: string): Record<string, unknown> {
+  return { type: "message", role: "user", content: [{ type: "input_text", text }] };
+}
+
+/** Build the v1 compact `output` array: retained recent user messages + the summary message. */
+export function buildCompactV1Output(userMessages: string[], summary: string): Record<string, unknown>[] {
+  const selected: string[] = [];
+  let remaining = COMPACT_V1_RETAINED_CHAR_BUDGET;
+  for (let i = userMessages.length - 1; i >= 0 && remaining > 0; i--) {
+    const msg = userMessages[i];
+    if (msg.length <= remaining) {
+      selected.push(msg);
+      remaining -= msg.length;
+    } else {
+      // Budget partially covers this older message: keep its tail (most recent context) and stop.
+      selected.push(msg.slice(msg.length - remaining));
+      break;
+    }
+  }
+  selected.reverse();
+  // codex-rs compact.rs uses "{SUMMARY_PREFIX}\n{summary}" (single newline) and detects stored
+  // summaries by that exact prefix — keep the same shape.
+  const summaryText = summary.trim().length > 0 ? `${SUMMARY_PREFIX}\n${summary}` : "(no summary available)";
+  return [...selected.map(compactUserMessageItem), compactUserMessageItem(summaryText)];
+}