@wlv-zedd/dsh-chatgpt-web 1.0.0

package/src/native-passthrough.ts

@@ -0,0 +1,261 @@
+import { readJsonRequestBody } from "./http-body";
+import {
+  BRIDGE_COMPACTION_PREFIX,
+  SUMMARY_PREFIX,
+  decodeCompactionSummary,
+} from "./responses/compaction";
+import { BRIDGE_REASONING_PREFIX } from "./responses/reasoning-envelope";
+
+const CODEX_BACKEND = "https://chatgpt.com/backend-api/codex";
+const FIRST_PARTY_CODEX_ORIGINATORS = new Set([
+  "codex_cli_rs",
+  "codex-tui",
+  "codex_vscode",
+  "codex_atlas",
+  "codex_chatgpt_desktop",
+]);
+const HOP_BY_HOP_HEADERS = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+  "host",
+]);
+
+export type NativeFetch = (request: Request) => Promise<Response>;
+export type NativeCodexEndpoint = "models" | "responses" | "responses/compact" | "alpha/search";
+
+type JsonObject = Record<string, unknown>;
+type BridgeCompactionItem = JsonObject & { type: "compaction"; encrypted_content: string };
+
+function firstPartyCodexOriginator(value: string): boolean {
+  return FIRST_PARTY_CODEX_ORIGINATORS.has(value)
+    || /^Codex [A-Za-z0-9][A-Za-z0-9._ -]{0,63}$/.test(value);
+}
+
+/**
+ * Current Codex clients identify themselves as `<originator>/<cargo semver> (...)`. The models
+ * backend requires the release-only `major.minor.patch` value even when the client is an alpha.
+ * Derive it only from the documented first-party Codex prefix; an arbitrary browser or proxy
+ * User-Agent is not evidence of a Codex version and leaves the original request untouched.
+ */
+export function codexClientVersionFromUserAgent(userAgent: string | null): string | undefined {
+  if (!userAgent) return undefined;
+  const separator = userAgent.indexOf("/");
+  if (separator < 1) return undefined;
+  const originator = userAgent.slice(0, separator);
+  if (!firstPartyCodexOriginator(originator)) return undefined;
+  const version = /^(\d{1,6})\.(\d{1,6})\.(\d{1,6})(?:[-+][0-9A-Za-z.-]+)?(?:\s|$)/
+    .exec(userAgent.slice(separator + 1));
+  return version ? `${version[1]}.${version[2]}.${version[3]}` : undefined;
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isBridgeReasoningItem(value: unknown): value is JsonObject {
+  if (!isObject(value) || value.type !== "reasoning") return false;
+  const encrypted = value.encrypted_content;
+  if (typeof encrypted === "string" && encrypted.startsWith(BRIDGE_REASONING_PREFIX)) return true;
+  return typeof value.id === "string"
+    && /^rs_[0-9a-f]{32}$/i.test(value.id)
+    && (encrypted === undefined || encrypted === null)
+    && (Array.isArray(value.summary) || Array.isArray(value.content));
+}
+
+function isBridgeCompactionItem(value: unknown): value is BridgeCompactionItem {
+  return isObject(value)
+    && value.type === "compaction"
+    && typeof value.encrypted_content === "string"
+    && value.encrypted_content.startsWith(BRIDGE_COMPACTION_PREFIX);
+}
+
+/**
+ * Response item ids are scoped to the backend that created them. A ChatGPT Web response is
+ * generated locally, so replaying its `rs_*` id after switching back to native Codex makes the
+ * official backend try to load an item it has never stored. The same boundary applies to local
+ * `ocx1:` compaction checkpoints: preserve their decoded summary as a normal input message rather
+ * than asking the official backend to decrypt a bridge-owned envelope. Once either artifact proves
+ * that the history crossed providers, send the complete item content without provider-local ids.
+ */
+export function scrubBridgeArtifactsForNative(value: unknown): { value: unknown; changed: boolean } {
+  if (!isObject(value)
+    || !Array.isArray(value.input)
+    || !value.input.some(item => isBridgeReasoningItem(item) || isBridgeCompactionItem(item))) {
+    return { value, changed: false };
+  }
+
+  const input = value.input.flatMap(item => {
+    if (!isObject(item)) return [item];
+    const clean = { ...item };
+    delete clean.id;
+    if (isBridgeCompactionItem(clean)) {
+      const summary = decodeCompactionSummary(clean.encrypted_content);
+      if (summary === null) throw new Error("Invalid ChatGPT Web compaction checkpoint");
+      return [{
+        type: "message",
+        role: "user",
+        content: [{ type: "input_text", text: `${SUMMARY_PREFIX}\n\n${summary}` }],
+      }];
+    }
+    if (clean.type !== "reasoning") return [clean];
+
+    if (typeof clean.encrypted_content === "string"
+      && clean.encrypted_content.startsWith(BRIDGE_REASONING_PREFIX)) {
+      delete clean.encrypted_content;
+    } else if (clean.encrypted_content === null) {
+      delete clean.encrypted_content;
+    }
+
+    const hasSummary = Array.isArray(clean.summary) && clean.summary.length > 0;
+    const hasContent = Array.isArray(clean.content) && clean.content.length > 0;
+    const hasNativeEncryptedContent = typeof clean.encrypted_content === "string";
+    return hasSummary || hasContent || hasNativeEncryptedContent ? [clean] : [];
+  });
+  const clean: JsonObject = { ...value, input };
+  delete clean.previous_response_id;
+  return { value: clean, changed: true };
+}
+
+function endToEndHeaders(source: Headers): Headers {
+  const headers = new Headers();
+  for (const [name, value] of source) {
+    if (!HOP_BY_HOP_HEADERS.has(name.toLowerCase())) headers.append(name, value);
+  }
+  headers.delete("content-length");
+  return headers;
+}
+
+/** Terminator every Responses SSE stream ends with; nothing after it carries meaning. */
+const SSE_TERMINATOR = "data: [DONE]";
+
+/**
+ * ChatGPT's backend routinely resets the native Codex connection instead of closing it cleanly,
+ * which Bun surfaces as ECONNRESET while reading the body. Passed through untouched that reaches
+ * Codex as a truncated HTTP body and the opaque "error decoding response body".
+ *
+ * A reset that arrives after the stream already delivered `data: [DONE]` is an unclean TCP close on
+ * a turn that finished: every byte the protocol defines has been forwarded, so the stream is closed
+ * normally rather than failed. A reset before that genuinely truncated the turn and is still raised,
+ * because inventing a terminal event there would tell Codex a turn ended when it did not.
+ */
+function withUncleanCloseTolerance(
+  body: ReadableStream<Uint8Array>,
+  isEventStream: boolean,
+  onUncleanClose?: (bytes: number) => void,
+): ReadableStream<Uint8Array> {
+  if (!isEventStream) return body;
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let lineBuffer = "";
+  let completed = false;
+  let bytes = 0;
+  const inspectLines = (text: string): void => {
+    lineBuffer += text;
+    let newline = lineBuffer.indexOf("\n");
+    while (newline >= 0) {
+      const line = lineBuffer.slice(0, newline).replace(/\r$/, "");
+      lineBuffer = lineBuffer.slice(newline + 1);
+      if (line === SSE_TERMINATOR) completed = true;
+      newline = lineBuffer.indexOf("\n");
+    }
+  };
+  const inspectTrailingLine = (): void => {
+    // A reset can arrive before the final line separator. Treat only an exact unterminated
+    // terminator line as complete; text embedded in a JSON data payload must not qualify.
+    if (lineBuffer.replace(/\r$/, "") === SSE_TERMINATOR) completed = true;
+  };
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const chunk = await reader.read();
+        if (chunk.done) {
+          inspectLines(decoder.decode());
+          inspectTrailingLine();
+          controller.close();
+          return;
+        }
+        bytes += chunk.value.byteLength;
+        inspectLines(decoder.decode(chunk.value, { stream: true }));
+        controller.enqueue(chunk.value);
+      } catch (error) {
+        inspectTrailingLine();
+        if (!completed) {
+          controller.error(error);
+          return;
+        }
+        onUncleanClose?.(bytes);
+        controller.close();
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+}
+
+export async function forwardNativeCodexRequest(
+  request: Request,
+  endpoint: NativeCodexEndpoint,
+  fetchUpstream: NativeFetch = fetch,
+  decodedBody?: unknown,
+): Promise<Response> {
+  const authorization = request.headers.get("authorization") ?? "";
+  if (!authorization.startsWith("Bearer ") || authorization.length <= "Bearer ".length) {
+    throw new Error("Native Codex passthrough requires the incoming Bearer authorization");
+  }
+
+  const incomingUrl = new URL(request.url);
+  if (endpoint === "models" && !incomingUrl.searchParams.has("client_version")) {
+    const clientVersion = codexClientVersionFromUserAgent(request.headers.get("user-agent"));
+    if (clientVersion) incomingUrl.searchParams.set("client_version", clientVersion);
+  }
+  const headers = endToEndHeaders(request.headers);
+  if (endpoint === "models") headers.delete("if-none-match");
+  const method = endpoint === "models" ? "GET" : "POST";
+  let body: BodyInit | undefined;
+  if (method === "POST") {
+    const parseRequest = decodedBody === undefined ? request.clone() : undefined;
+    const originalBody = await request.arrayBuffer();
+    const scrubbed = scrubBridgeArtifactsForNative(
+      decodedBody === undefined ? await readJsonRequestBody(parseRequest!) : decodedBody,
+    );
+    if (scrubbed.changed) {
+      headers.delete("content-encoding");
+      body = JSON.stringify(scrubbed.value);
+    } else {
+      body = originalBody;
+    }
+  }
+  const upstreamRequest = new Request(`${CODEX_BACKEND}/${endpoint}${incomingUrl.search}`, {
+    method,
+    headers,
+    ...(body ? { body } : {}),
+    signal: request.signal,
+  });
+  const upstream = await fetchUpstream(upstreamRequest);
+  const responseHeaders = endToEndHeaders(upstream.headers);
+  const isEventStream = (upstream.headers.get("content-type") ?? "")
+    .toLowerCase()
+    .includes("text/event-stream");
+  return new Response(
+    upstream.body
+      ? withUncleanCloseTolerance(upstream.body, isEventStream, bytes => {
+        console.warn(
+          `[codex-chatgpt-web] native_upstream_unclean_close endpoint=${endpoint} bytes=${bytes}`
+          + " (turn had already completed; closing the client stream normally)",
+        );
+      })
+      : upstream.body,
+    {
+      status: upstream.status,
+      statusText: upstream.statusText,
+      headers: responseHeaders,
+    },
+  );
+}

package/src/plugin.ts

@@ -0,0 +1,191 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export interface CordisContext {
+  effect?: (cb: () => void | Promise<void> | (() => void) | (() => Promise<void>)) => void;
+  logger?: (name: string) => {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+  };
+}
+
+export const name = "dsh-chatgpt-web";
+export const inject = [];
+
+export interface ChatGPTWebPluginConfig {
+  /** Host to bind or check for health (default: 127.0.0.1). */
+  host?: string;
+  /** Port the sidecar listens on (default: 17841). */
+  port?: number;
+  /** Automatically start the sidecar daemon if not running (default: true). */
+  autoStart?: boolean;
+  /** Maximum milliseconds to wait for the sidecar to report ready (default: 30000). */
+  readyTimeoutMs?: number;
+  /** Explicit path to the bun executable (optional). */
+  bunPath?: string;
+}
+
+import { pathToFileURL } from "node:url";
+
+const ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function resolveLauncher(customBunPath?: string): { cmd: string; args: string[] } {
+  const libCliPath = resolve(ROOT_DIR, "lib", "cli.js");
+  if (existsSync(libCliPath)) {
+    return {
+      cmd: process.execPath,
+      args: [libCliPath, "serve"],
+    };
+  }
+
+  // Development fallback: check for bun or tsx
+  if (customBunPath && existsSync(customBunPath)) {
+    return { cmd: customBunPath, args: ["run", "src/cli.ts", "serve"] };
+  }
+
+  const winBun = join(homedir(), ".bun", "bin", "bun.exe");
+  if (existsSync(winBun)) {
+    return { cmd: winBun, args: ["run", "src/cli.ts", "serve"] };
+  }
+
+  const tsxPath = resolve(ROOT_DIR, "../deepseek-harness/node_modules/tsx/dist/esm/index.mjs");
+  if (existsSync(tsxPath)) {
+    return {
+      cmd: process.execPath,
+      args: ["--import", pathToFileURL(tsxPath).href, "src/cli.ts", "serve"],
+    };
+  }
+
+  return { cmd: process.execPath, args: ["src/cli.ts", "serve"] };
+}
+
+async function isSidecarHealthy(host: string, port: number): Promise<boolean> {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1500);
+    const res = await fetch(`http://${host}:${port}/healthz`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timer);
+    if (!res.ok) return false;
+    const body = (await res.json()) as { status?: string };
+    return body.status === "ok";
+  } catch {
+    return false;
+  }
+}
+
+export function apply(ctx: CordisContext, config: ChatGPTWebPluginConfig = {}): void {
+  const host = config.host || "127.0.0.1";
+  const port = config.port || 17841;
+  const autoStart = config.autoStart !== false;
+  const readyTimeoutMs = config.readyTimeoutMs || 30_000;
+  const logger = typeof ctx.logger === "function" ? ctx.logger("chatgpt-web") : console;
+
+  let spawnedProcess: ChildProcess | undefined;
+
+  const startDaemon = async () => {
+    const alreadyHealthy = await isSidecarHealthy(host, port);
+    if (alreadyHealthy) {
+      logger.info(`[dsh-chatgpt-web] Sidecar already running and healthy at http://${host}:${port}/v1`);
+      return;
+    }
+
+    if (!autoStart) {
+      logger.warn(`[dsh-chatgpt-web] Sidecar is offline and autoStart is false. Start it manually with 'bun run src/cli.ts serve'`);
+      return;
+    }
+
+    const launcher = resolveLauncher(config.bunPath);
+    logger.info(`[dsh-chatgpt-web] Starting dsh-chatgpt-web daemon via ${launcher.cmd} at http://${host}:${port}/v1...`);
+
+    const child = spawn(launcher.cmd, launcher.args, {
+      cwd: ROOT_DIR,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true,
+      env: {
+        ...process.env,
+      },
+    });
+
+    spawnedProcess = child;
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      const text = chunk.toString().trim();
+      if (text && typeof logger.debug === "function") logger.debug(`[sidecar] ${text}`);
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      const text = chunk.toString().trim();
+      if (text && typeof logger.debug === "function") logger.debug(`[sidecar:err] ${text}`);
+    });
+
+    child.on("error", (err) => {
+      logger.error(`[dsh-chatgpt-web] Failed to launch sidecar process: ${err.message}`);
+    });
+
+    child.on("exit", (code, signal) => {
+      if (code !== 0 && code !== null) {
+        logger.warn(`[dsh-chatgpt-web] Sidecar process exited with code ${code} (signal: ${signal})`);
+      }
+      spawnedProcess = undefined;
+    });
+
+    // Wait for healthcheck
+    const deadline = Date.now() + readyTimeoutMs;
+    while (Date.now() < deadline) {
+      if (await isSidecarHealthy(host, port)) {
+        logger.info(`[dsh-chatgpt-web] Sidecar ready and accepting turns at http://${host}:${port}/v1`);
+        return;
+      }
+      await new Promise((r) => setTimeout(r, 500));
+    }
+
+    logger.error(`[dsh-chatgpt-web] Sidecar did not become healthy within ${readyTimeoutMs}ms`);
+  };
+
+  const stopDaemon = async () => {
+    if (!spawnedProcess) return;
+
+    logger.info("[dsh-chatgpt-web] Stopping sidecar daemon...");
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 2000);
+      await fetch(`http://${host}:${port}/admin/shutdown`, {
+        method: "POST",
+        signal: controller.signal,
+      }).catch(() => {});
+      clearTimeout(timer);
+    } catch {
+      // ignore
+    }
+
+    if (spawnedProcess && !spawnedProcess.killed) {
+      spawnedProcess.kill("SIGTERM");
+    }
+    spawnedProcess = undefined;
+  };
+
+  if (typeof ctx.effect === "function") {
+    ctx.effect(() => {
+      void startDaemon();
+      return () => {
+        void stopDaemon();
+      };
+    });
+  } else {
+    void startDaemon();
+    process.once("beforeExit", () => void stopDaemon());
+  }
+}
+
+export default {
+  name,
+  inject,
+  apply,
+};

package/src/process.ts

@@ -0,0 +1,45 @@
+import { spawnSync, type SpawnSyncOptions } from "node:child_process";
+
+export interface CommandResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+export function processRunning(
+  pid: unknown,
+  probe: (pid: number, signal: 0) => void = process.kill,
+): boolean {
+  if (!Number.isInteger(pid) || (pid as number) < 1) return false;
+  try {
+    probe(pid as number, 0);
+    return true;
+  } catch (error) {
+    // Windows and hardened Unix environments can deny signalling an existing process. EPERM is
+    // existence evidence, not proof that the launcher/browser/tunnel owner disappeared.
+    return (error as NodeJS.ErrnoException)?.code === "EPERM";
+  }
+}
+
+export function runCommand(command: string, args: string[], options: SpawnSyncOptions = {}): CommandResult {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    stdio: "pipe",
+    ...options,
+  });
+  if (result.error) throw result.error;
+  return {
+    status: result.status ?? 1,
+    stdout: typeof result.stdout === "string" ? result.stdout : result.stdout?.toString("utf8") ?? "",
+    stderr: typeof result.stderr === "string" ? result.stderr : result.stderr?.toString("utf8") ?? "",
+  };
+}
+
+export function runChecked(command: string, args: string[], options: SpawnSyncOptions = {}): CommandResult {
+  const result = runCommand(command, args, options);
+  if (result.status !== 0) {
+    const detail = result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`;
+    throw new Error(`${command} ${args.join(" ")} failed: ${detail}`);
+  }
+  return result;
+}

package/src/responses/compaction.ts

@@ -0,0 +1,199 @@
+/**
+ * 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 BRIDGE_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]";
+
+/** Codex v1 uses one newline after the prefix; the transparent v2 replay uses two. */
+export function isReadableCompactionSummaryText(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith(`${SUMMARY_PREFIX}\n`);
+}
+
+export function encodeCompactionSummary(summary: string): string {
+  return BRIDGE_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(BRIDGE_COMPACTION_PREFIX)) return null;
+  try {
+    return Buffer.from(encryptedContent.slice(BRIDGE_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;
+
+type CompactMessageItem = Record<string, unknown>;
+
+interface CompactContentBlock extends Record<string, unknown> {
+  type?: string;
+  text?: string;
+  image_url?: string;
+}
+
+/**
+ * Codex can persist unavailable historical images as a one-pixel PNG. Replaying that sentinel as
+ * a real attachment produces an opaque black tile in ChatGPT and consumes one attachment slot,
+ * but carries no visual information. Treat every 1x1 PNG data URL as non-semantic transport state.
+ */
+export function isOnePixelPngDataUrl(value: unknown): value is string {
+  if (typeof value !== "string" || !value.startsWith("data:image/png;base64,")) return false;
+  try {
+    const png = Buffer.from(value.slice("data:image/png;base64,".length), "base64");
+    return png.length >= 24
+      && png.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+      && png.readUInt32BE(16) === 1
+      && png.readUInt32BE(20) === 1;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract original user message items from a Responses `input` array.
+ *
+ * Keeping the original item metadata matters: Codex uses it after `/responses/compact` to
+ * distinguish real user turns from contextual user-role wrappers. Images remain structured
+ * `input_image` blocks so the browser adapter can upload them as attachments; their data URL is
+ * never copied into the textual ChatGPT transport envelope.
+ */
+export function extractCompactUserMessages(input: unknown): CompactMessageItem[] {
+  if (!Array.isArray(input)) return [];
+  const out: CompactMessageItem[] = [];
+  for (const item of input) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+    const rec = item as CompactMessageItem & { type?: string; role?: string; content?: unknown };
+    if (rec.type !== undefined && rec.type !== "message") continue;
+    if (rec.role !== "user") continue;
+    if (isReadableCompactionSummaryText(
+      compactContentBlocks(rec).filter(textBlock).map(block => block.text).join(""),
+    )) continue;
+    out.push(structuredClone(rec));
+  }
+  return out;
+}
+
+function compactUserMessageItem(text: string): CompactMessageItem {
+  return { type: "message", role: "user", content: [{ type: "input_text", text }] };
+}
+
+function compactContentBlocks(item: CompactMessageItem): CompactContentBlock[] {
+  if (typeof item.content === "string") {
+    return [{ type: "input_text", text: item.content }];
+  }
+  if (!Array.isArray(item.content)) return [];
+  return item.content
+    .filter((block): block is CompactContentBlock => Boolean(block && typeof block === "object" && !Array.isArray(block)))
+    .map(block => structuredClone(block));
+}
+
+function textBlock(block: CompactContentBlock): boolean {
+  return (block.type === "input_text" || block.type === "text") && typeof block.text === "string";
+}
+
+function imageBlock(block: CompactContentBlock): boolean {
+  return block.type === "input_image"
+    && typeof block.image_url === "string"
+    && !isOnePixelPngDataUrl(block.image_url);
+}
+
+/**
+ * Build the v1 compact replacement history.
+ *
+ * Text follows Codex's 20k-token retained-user-message budget. Image history is independently
+ * bounded to ChatGPT's ten-attachment limit, newest first. This prevents an old image corpus from
+ * immediately refilling Codex's context window after a successful compact while still preserving
+ * the visual context the browser model can actually receive.
+ */
+export function buildCompactV1Output(
+  userMessages: CompactMessageItem[],
+  summary: string,
+  maxImages = 10,
+): CompactMessageItem[] {
+  const selected: CompactMessageItem[] = [];
+  let remaining = COMPACT_V1_RETAINED_CHAR_BUDGET;
+  let retainedImages = 0;
+  for (let i = userMessages.length - 1; i >= 0 && (remaining > 0 || retainedImages < maxImages); i--) {
+    const message = structuredClone(userMessages[i]!);
+    const blocks = compactContentBlocks(message);
+    const retainedReversed: CompactContentBlock[] = [];
+    for (let blockIndex = blocks.length - 1; blockIndex >= 0; blockIndex -= 1) {
+      const block = blocks[blockIndex]!;
+      if (imageBlock(block)) {
+        if (retainedImages < maxImages) {
+          retainedImages += 1;
+          retainedReversed.push(block);
+        }
+        continue;
+      }
+      if (!textBlock(block) || remaining === 0) continue;
+      const text = block.text!;
+      if (text.length <= remaining) {
+        remaining -= text.length;
+        retainedReversed.push({ ...block, type: "input_text", text });
+      } else {
+        retainedReversed.push({ ...block, type: "input_text", text: text.slice(text.length - remaining) });
+        remaining = 0;
+      }
+    }
+    const content = retainedReversed.reverse();
+    if (content.length > 0) {
+      message.type = "message";
+      message.role = "user";
+      message.content = content;
+      selected.push(message);
+    }
+  }
+  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, compactUserMessageItem(summaryText)];
+}