@humwick/runner 0.0.0-stage → 0.130.0

package/src/adapters/codex-agent-message-capture.ts

@@ -0,0 +1,189 @@
+type EmitAgentMessage = (body: string) => void;
+type ResponseEntry = { itemId?: string; body: string };
+type CompleteItemOptions = { includeInResponse?: boolean; phase?: unknown };
+
+const MAX_CAPTURED_RESPONSE_CHARS = 16_000;
+// `\s` is defined as exactly the character set String#trim strips, so this tests
+// `text.trim() !== ""` without allocating the trimmed copy. It is NOT free — matching forces a
+// flatten of the accumulated buffer's rope — so it must stay off the per-delta hot path and is
+// only used where the pre-#2504 whitespace guard actually changed the outcome.
+const NON_WHITESPACE = /\S/;
+const TRUNCATION_MARKER_PREFIX = "[truncated:";
+
+export class CodexAgentMessageCapture {
+  private segments: ResponseEntry[][] = [];
+  private currentSegment: ResponseEntry[] = [];
+  private readonly buffers = new Map<string, string>();
+  private readonly flushedLengths = new Map<string, number>();
+  private readonly responseRecordedLengths = new Map<string, number>();
+
+  reset(): void {
+    this.segments = [];
+    this.currentSegment = [];
+    this.buffers.clear();
+    this.flushedLengths.clear();
+    this.responseRecordedLengths.clear();
+  }
+
+  appendDelta(itemId: string | undefined, delta: string): void {
+    if (!itemId || !delta) return;
+    this.buffers.set(itemId, `${this.buffers.get(itemId) ?? ""}${delta}`);
+  }
+
+  completeItem(itemId: string | undefined, text: string | undefined, emit: EmitAgentMessage, options: CompleteItemOptions = {}): void {
+    const fullText = text ?? (itemId ? this.buffers.get(itemId) : undefined);
+    this.flushText(itemId, fullText, emit);
+    if (options.includeInResponse === false || options.phase === "commentary") {
+      this.forgetResponseItem(itemId);
+    } else {
+      this.recordResponseText(itemId, fullText);
+    }
+    if (!itemId) return;
+    this.buffers.delete(itemId);
+    this.flushedLengths.delete(itemId);
+  }
+
+  closeSegment(emit: EmitAgentMessage): void {
+    this.flushPending(emit);
+    if (!this.currentSegment.length) return;
+    this.segments.push(this.currentSegment);
+    this.currentSegment = [];
+  }
+
+  // Deterministic turn-final response: prefer the trailing structured report span, not a generic
+  // post-handoff coda. The original #1079/#1086 trailing-run rule correctly kept early narration
+  // out, but it over-trimmed Codex turns shaped "summary -> workspace ready -> Landed..." and made
+  // report-up deliver only the coda (#1136). We still drop leading narration; we just let structured
+  // report markers beat a terse final status line.
+  finish(emit: EmitAgentMessage): string | undefined {
+    this.closeSegment(emit);
+    const trailingSegment = selectFinalResponseSegments(this.segments);
+    this.segments = [];
+    const text = trailingSegment ? trailingSegment.map(segmentBody).join("\n\n").trim() : undefined;
+    return truncateCapturedResponse(text);
+  }
+
+  private flushPending(emit: EmitAgentMessage): void {
+    // #2504 hot path: EVERY reasoning/plan delta calls closeSegment -> flushPending, so this runs
+    // thousands of times per turn. Bail before the defensive entry-array copy when there is no
+    // open agentMessage buffer (the common case) — that snapshot exists only so `emit` re-entering
+    // and mutating `buffers` cannot disturb the iteration, and there is nothing to iterate here.
+    if (!this.buffers.size) return;
+    for (const [itemId, text] of [...this.buffers.entries()]) {
+      this.flushText(itemId, text, emit);
+      this.recordResponseText(itemId, text);
+    }
+  }
+
+  private flushText(itemId: string | undefined, text: string | undefined, emit: EmitAgentMessage): void {
+    if (!text) return;
+    const offset = itemId ? (this.flushedLengths.get(itemId) ?? 0) : 0;
+    // #2504: `text` is the WHOLE accumulated item buffer and this is re-entered on every
+    // reasoning/plan delta. `.length` is O(1) on a rope, `.slice()`/`.trim()` are not — they
+    // flatten and copy the entire buffer. Skip both when nothing new has arrived, which is the
+    // overwhelmingly common case. Equivalent to the old code: slicing at/past the end yields ""
+    // and an empty body returned without emitting; the only other effect was rewinding the offset
+    // on a shorter (non-extension) text, preserved below.
+    if (itemId && text.length <= offset) {
+      if (text.length < offset) this.flushedLengths.set(itemId, text.length);
+      return;
+    }
+    const chunk = text.slice(offset);
+    if (itemId) this.flushedLengths.set(itemId, text.length);
+    const body = chunk.trim();
+    if (!body) return;
+    emit(body);
+  }
+
+  // #2504 root cause. This used to open with `const body = text.trim()` — a full flatten+copy of
+  // the entire accumulated agentMessage buffer — before branching, and on the itemId path `body`
+  // was then DEAD: that branch computes its own incremental `chunk` and pushes that. Because every
+  // reasoning/plan delta re-enters here via closeSegment -> flushPending with the same growing
+  // buffer, the copy ran per delta over the whole buffer: O(N^2) transient-string churn that
+  // fragmented the runner's allocator into multi-GB RSS bun never returned. Work here is now
+  // bounded by the number of NEW characters, and is O(1) when nothing new arrived.
+  private recordResponseText(itemId: string | undefined, text: string | undefined): void {
+    if (!text) return;
+    if (itemId) {
+      const offset = this.responseRecordedLengths.get(itemId) ?? 0;
+      // THE hot path — every reasoning/plan delta lands here with an unchanged buffer. `.length`
+      // is O(1); the pre-fix full-buffer trim was not, and its outcome was always "record
+      // nothing" anyway (slicing at the end yields an empty chunk, and rewriting the offset to
+      // the value it already holds is a no-op).
+      if (text.length === offset) return;
+      if (text.length < offset) {
+        // The item's text got SHORTER than what we recorded — a buffer re-opened by fresh deltas
+        // after completeItem, which clears `buffers` but deliberately keeps this offset. Nothing
+        // can be recorded from it; the pre-fix code only rewound the offset, and only for
+        // non-blank text.
+        if (NON_WHITESPACE.test(text)) this.responseRecordedLengths.set(itemId, text.length);
+        return;
+      }
+      // Only the NEW tail is examined. `slice` on the accumulated buffer is rope-aware in JSC and
+      // stays proportional to the tail; a regex probe over `text` would NOT be — it forces a full
+      // flatten of the rope on every delta, which is the very cost this fix exists to remove.
+      const chunk = text.slice(offset).trim();
+      // The pre-fix guard was `if (!text.trim()) return` — skip the offset advance while the item
+      // is still ENTIRELY whitespace. A non-blank chunk already proves the text is non-blank (the
+      // chunk is a substring of it), so the whole-text probe below is only reached for an all-blank
+      // tail, and then it stops at the buffer's first real character.
+      if (!chunk && !NON_WHITESPACE.test(text)) return;
+      this.responseRecordedLengths.set(itemId, text.length);
+      if (!chunk) return;
+      this.currentSegment.push({ itemId, body: chunk });
+      return;
+    }
+    const body = text.trim();
+    if (!body) return;
+    this.currentSegment.push({ body });
+  }
+
+  private forgetResponseItem(itemId: string | undefined): void {
+    if (!itemId) return;
+    this.responseRecordedLengths.delete(itemId);
+    this.currentSegment = this.currentSegment.filter((entry) => entry.itemId !== itemId);
+    this.segments = this.segments
+      .map((segment) => segment.filter((entry) => entry.itemId !== itemId))
+      .filter((segment) => segment.length > 0);
+  }
+}
+
+function segmentBody(segment: ResponseEntry[]): string {
+  return segment.map((entry) => entry.body).join("\n\n").trim();
+}
+
+function selectFinalResponseSegments(segments: ResponseEntry[][]): ResponseEntry[][] | undefined {
+  const bodies = segments.map(segmentBody).filter(Boolean);
+  if (!bodies.length) return undefined;
+  let end = bodies.length - 1;
+  while (end > 0 && isGenericFinalCoda(bodies[end]!) && bodies.slice(0, end).some(isSubstantiveReportSegment)) end--;
+  const firstReport = bodies.slice(0, end + 1).findIndex(isReportBoundarySegment);
+  if (firstReport >= 0) return segments.slice(firstReport, end + 1);
+  for (let i = end; i >= 0; i--) {
+    if (isSubstantiveReportSegment(bodies[i]!)) return [segments[i]!];
+  }
+  return [segments[end]!];
+}
+
+const REPORT_BOUNDARY = /(^|\n)(#{1,6}\s|\*\*(summary|what changed|rca|fix|tests?|gates?|verification|risk)\b|(?:summary|what changed|rca|fix|tests?|gates?|verification|risk):)/i;
+const REPORT_STRUCTURE = /(^|\n)\s*[-*]\s+\S|`[^`]+`|\b(typecheck|bun test|tests? pass(?:ed)?|gates? green|rca|verified|implemented)\b/i;
+const GENERIC_FINAL_CODA = /^(?:done|landed(?: on main)?|committed|merged|ready|no further action|nothing further|all set)\b|(?:\bno further action needed\b|\bnothing further needed\b)$/i;
+
+function isReportBoundarySegment(body: string): boolean {
+  return REPORT_BOUNDARY.test(body.trim());
+}
+
+function isSubstantiveReportSegment(body: string): boolean {
+  const trimmed = body.trim();
+  return !isGenericFinalCoda(trimmed) && (trimmed.length >= 120 || isReportBoundarySegment(trimmed) || REPORT_STRUCTURE.test(trimmed));
+}
+
+function isGenericFinalCoda(body: string): boolean {
+  const trimmed = body.trim();
+  return trimmed.length <= 180 && GENERIC_FINAL_CODA.test(trimmed) && !isReportBoundarySegment(trimmed);
+}
+
+function truncateCapturedResponse(text: string | undefined): string | undefined {
+  if (!text || text.length <= MAX_CAPTURED_RESPONSE_CHARS) return text;
+  return `${text.slice(0, MAX_CAPTURED_RESPONSE_CHARS).trimEnd()}\n\n${TRUNCATION_MARKER_PREFIX} showing first ${MAX_CAPTURED_RESPONSE_CHARS} of ${text.length} chars]`;
+}

package/src/adapters/codex-app-server.ts

@@ -0,0 +1,70 @@
+import { errMessage } from "@humwick/sdk";
+import type { SpawnArgs } from "../adapter";
+import { CodexAppClient } from "./codex-client";
+
+const STARTUP_TIMEOUT_MS = 60_000;
+const STDERR_TAIL_CHARS = 8_192;
+
+/** Connect only after our child announces its bound socket, not after a guessed delay (#3225). */
+export async function spawnCodexAppServer(args: SpawnArgs, signal?: AbortSignal) {
+  signal?.throwIfAborted();
+  const appServerUrl = args.env.CODEX_APP_SERVER_URL!;
+  const appServer = Bun.spawn([args.command, ...args.args], {
+    cwd: args.cwd, env: args.env, stdin: "ignore", stdout: "inherit", stderr: "pipe",
+  });
+  const client = new CodexAppClient(appServerUrl);
+  const listening = Promise.withResolvers<void>();
+  const stderrReader = appServer.stderr.getReader();
+  let stderrTail = "";
+  let announced = false;
+  const stderrDone = (async () => {
+    const decoder = new TextDecoder();
+    try {
+      while (true) {
+        const { done, value: chunk } = await stderrReader.read();
+        if (done) return;
+        process.stderr.write(chunk);
+        stderrTail = (stderrTail + decoder.decode(chunk, { stream: true })).slice(-STDERR_TAIL_CHARS);
+        if (announced) continue;
+        const match = /^\s*listening on:\s*(ws:\/\/\S+)[\r\n]/m.exec(stderrTail);
+        if (!match) continue;
+        announced = true;
+        if (new URL(match[1]!).href !== new URL(appServerUrl).href) {
+          listening.reject(new Error(`Codex app-server listened on ${match[1]} instead of ${appServerUrl}`));
+        } else {
+          listening.resolve();
+        }
+      }
+    } finally {
+      stderrReader.releaseLock();
+    }
+  })();
+  // Keep draining after startup so the child cannot block on a full stderr pipe.
+  void stderrDone.catch((error) => listening.reject(error));
+  const exited = appServer.exited.then(async (code) => {
+    await stderrDone;
+    throw new Error(`Codex app-server exited during startup (code ${code}, signal ${appServer.signalCode ?? "none"})`);
+  });
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new Error(`Codex app-server startup timed out after ${STARTUP_TIMEOUT_MS}ms`)), STARTUP_TIMEOUT_MS);
+  const startupSignal = signal ? AbortSignal.any([signal, deadline.signal]) : deadline.signal;
+  const aborted = Promise.withResolvers<never>();
+  const onAbort = () => aborted.reject(startupSignal.reason);
+  startupSignal.addEventListener("abort", onAbort, { once: true });
+  if (startupSignal.aborted) onAbort();
+  try {
+    await Promise.race([listening.promise, exited, aborted.promise]);
+    await Promise.race([client.connect(), exited, aborted.promise]);
+    return { appServer, appServerUrl, client };
+  } catch (error) {
+    client.close();
+    appServer.kill("SIGKILL");
+    await appServer.exited;
+    await stderrReader.cancel().catch(() => {});
+    await stderrDone.catch(() => {});
+    throw new Error(`${errMessage(error)}; endpoint ${appServerUrl}; app-server stderr: ${stderrTail.trim() || "(empty)"}`);
+  } finally {
+    clearTimeout(timer);
+    startupSignal.removeEventListener("abort", onAbort);
+  }
+}

package/src/adapters/codex-client.ts

@@ -0,0 +1,362 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+type JsonRpcId = number | string;
+
+type JsonRpcRequest = {
+  id: JsonRpcId;
+  method: string;
+  params?: unknown;
+};
+
+type JsonRpcResponse = {
+  id: JsonRpcId;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+type JsonRpcNotification = {
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type ThreadStatus =
+  | { type: "notLoaded" }
+  | { type: "idle" }
+  | { type: "systemError" }
+  | { type: "active"; activeFlags: string[] };
+
+type TurnStatus = "completed" | "interrupted" | "failed" | "inProgress";
+
+interface Turn {
+  id: string;
+  status: TurnStatus;
+  startedAt: number | null;
+  completedAt: number | null;
+}
+
+export interface Thread {
+  id: string;
+  cwd: string;
+  status: ThreadStatus;
+  updatedAt: number;
+  preview: string;
+  turns?: Turn[];
+}
+
+export type ClientEvent =
+  | { type: "notification"; message: JsonRpcNotification }
+  | { type: "server-request"; message: JsonRpcRequest }
+  | { type: "response"; message: JsonRpcResponse };
+
+interface TurnStartResponse {
+  turn: Turn;
+}
+
+interface ThreadStartResponse {
+  thread: Thread;
+}
+
+interface ThreadResumeResponse {
+  thread: Thread;
+}
+
+interface ThreadReadResponse {
+  thread: Thread;
+}
+
+interface ThreadListResponse {
+  data: Thread[];
+  nextCursor: string | null;
+}
+
+interface ThreadLoadedListResponse {
+  data: string[];
+  nextCursor: string | null;
+}
+
+interface AccountRateLimitsResponse {
+  rateLimits?: unknown;
+  rate_limits?: unknown;
+}
+
+export const CODEX_APP_CLIENT_EVENT_CAP = 5_000;
+
+// #2504: the frame ring is diagnostic-only (getEvents()), but a COUNT cap alone bounds nothing —
+// a single app-server frame can carry a whole file diff or a large tool payload, so 5,000 frames
+// is an unbounded number of bytes. Cap the retained frame text too and evict oldest-first. The
+// budget is charged in raw frame characters; the parsed objects retained alongside them cost a
+// multiple of that, so keep the ceiling modest. The newest frame is always retained even if it
+// alone exceeds the budget, so an oversized frame can never empty the ring or spin the evictor.
+export const CODEX_APP_CLIENT_EVENT_BYTE_CAP = 4_000_000;
+
+/**
+ * #2539 Phase A — a JSON-RPC error response from the app-server, kept STRUCTURED. The client
+ * used to flatten every error into `"<message> (<code>)"`, which forced callers to classify
+ * rejections by message substring and made the turn/steer fallbacks (not-steerable vs
+ * stale-turn vs transport) indistinguishable from real faults. The message keeps the old
+ * `"<message> (<code>)"` shape so existing diagnostics and message-matching keep working.
+ */
+export class CodexRpcError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+  constructor(code: number, message: string, data?: unknown) {
+    super(`${message} (${code})`);
+    this.name = "CodexRpcError";
+    this.code = code;
+    this.data = data;
+  }
+}
+
+// #1339: every JSON-RPC method the app-server exposes acknowledges promptly — turn/start
+// returns the created turn immediately (turn progress/completion arrive later as separate
+// notifications), compact/start acks and reports completion via thread/compacted, etc. So a
+// request whose response never arrives (a half-open socket, a lost frame, an app-server that
+// wedged mid-handling) is always a fault, never normal latency. Without a ceiling, request()
+// would hang forever; because deliver() awaits turnStart under the runner's single-flight
+// `delivering` latch, one hung request permanently wedges the whole input pump — the agent
+// looks "unresponsive": input is accepted but no turn ever starts and nothing new drains.
+// Reject after this ceiling so the hang surfaces (logged delivery failure) and the pump
+// recovers by re-queuing. Generous vs. the sub-second normal ack, so no false timeouts.
+export const CODEX_APP_CLIENT_REQUEST_TIMEOUT_MS = 30_000;
+
+export class CodexAppClient {
+  private ws!: WebSocket;
+  private nextId = 1;
+  private pending = new Map<JsonRpcId, { resolve: (value: any) => void; reject: (err: unknown) => void }>();
+  // Each retained frame carries the raw character count it was charged, so eviction never has to
+  // re-measure — re-serializing frames inside record() would be its own per-frame leak.
+  private events: { event: ClientEvent; size: number }[] = [];
+  private eventBytes = 0;
+  private listeners = new Set<(event: ClientEvent) => void>();
+  private connected = false;
+  private connectionListeners = new Set<(connected: boolean) => void>();
+
+  constructor(
+    private readonly url: string,
+    private readonly log: (msg: string) => void = () => {},
+    private readonly requestTimeoutMs: number = CODEX_APP_CLIENT_REQUEST_TIMEOUT_MS,
+  ) {}
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+    await new Promise<void>((resolve, reject) => {
+      const ws = new WebSocket(this.url);
+      this.ws = ws;
+
+      ws.onopen = () => {
+        this.connected = true;
+        this.emitConnection(true);
+        resolve();
+      };
+      ws.onerror = (event) => reject(new Error(`websocket error: ${String((event as ErrorEvent).message || "unknown")}`));
+      ws.onclose = (event) => {
+        this.connected = false;
+        this.emitConnection(false);
+        const err = new Error(`websocket closed code=${event.code} reason=${event.reason || "(none)"}`);
+        for (const pending of this.pending.values()) pending.reject(err);
+        this.pending.clear();
+      };
+      ws.onmessage = (event) => this.handleMessage(String(event.data));
+    });
+  }
+
+  close(): void {
+    if (!this.ws) return;
+    this.ws.close();
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  async initialize(): Promise<unknown> {
+    return this.request("initialize", {
+      clientInfo: {
+        name: "agent-relay-runner-codex",
+        title: "Agent Relay Codex Runner",
+        version: "0.1.0",
+      },
+      capabilities: {
+        experimentalApi: true,
+      },
+    });
+  }
+
+  onEvent(listener: (event: ClientEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  onConnectionChange(listener: (connected: boolean) => void): () => void {
+    this.connectionListeners.add(listener);
+    return () => this.connectionListeners.delete(listener);
+  }
+
+  getEvents(): ClientEvent[] {
+    return this.events.map((frame) => frame.event);
+  }
+
+  async settle(ms = 150): Promise<void> {
+    await delay(ms);
+  }
+
+  async threadStart(params: Record<string, unknown>): Promise<ThreadStartResponse> {
+    return this.request<ThreadStartResponse>("thread/start", params);
+  }
+
+  async skillsSetExtraRoots(extraRoots: string[]): Promise<Record<string, never>> {
+    return this.request<Record<string, never>>("skills/extraRoots/set", { extraRoots });
+  }
+
+  async threadResume(params: Record<string, unknown>): Promise<ThreadResumeResponse> {
+    return this.request<ThreadResumeResponse>("thread/resume", params);
+  }
+
+  async threadRead(threadId: string, includeTurns = false): Promise<ThreadReadResponse> {
+    return this.request<ThreadReadResponse>("thread/read", { threadId, includeTurns });
+  }
+
+  async threadList(params: Record<string, unknown>): Promise<ThreadListResponse> {
+    return this.request<ThreadListResponse>("thread/list", params);
+  }
+
+  async threadLoadedList(limit = 20): Promise<ThreadLoadedListResponse> {
+    return this.request<ThreadLoadedListResponse>("thread/loaded/list", { limit });
+  }
+
+  async threadCompactStart(threadId: string): Promise<Record<string, never>> {
+    return this.request<Record<string, never>>("thread/compact/start", { threadId });
+  }
+
+  async turnStart(threadId: string, text: string): Promise<TurnStartResponse> {
+    return this.request<TurnStartResponse>("turn/start", {
+      threadId,
+      input: [{ type: "text", text }],
+    });
+  }
+
+  async turnSteer(threadId: string, turnId: string, text: string, clientUserMessageId?: string): Promise<{ turnId: string }> {
+    return this.request<{ turnId: string }>("turn/steer", {
+      threadId,
+      expectedTurnId: turnId,
+      input: [{ type: "text", text }],
+      // #2539 Phase A — stable acceptance-correlation id (echoed back as the userMessage
+      // item's clientId). Absent keeps the legacy wire shape.
+      ...(clientUserMessageId ? { clientUserMessageId } : {}),
+    });
+  }
+
+  async turnInterrupt(threadId: string, turnId: string): Promise<Record<string, never>> {
+    return this.request<Record<string, never>>("turn/interrupt", { threadId, turnId });
+  }
+
+  async accountRateLimitsRead(): Promise<AccountRateLimitsResponse> {
+    return this.request<AccountRateLimitsResponse>("account/rateLimits/read");
+  }
+
+  respondToServerRequest(id: JsonRpcId, result: unknown): void {
+    if (!this.connected) {
+      throw new Error("websocket not connected");
+    }
+    this.ws.send(JSON.stringify({ id, result }));
+  }
+
+  rejectServerRequest(id: JsonRpcId, code: number, message: string, data?: unknown): void {
+    if (!this.connected) {
+      throw new Error("websocket not connected");
+    }
+    this.ws.send(JSON.stringify({ id, error: { code, message, ...(data !== undefined ? { data } : {}) } }));
+  }
+
+  private async request<T = unknown>(method: string, params?: unknown): Promise<T> {
+    if (!this.connected) {
+      throw new Error("websocket not connected");
+    }
+    const id = this.nextId++;
+    const payload: JsonRpcRequest = { id, method, params };
+    const promise = new Promise<T>((resolve, reject) => {
+      // #1339: cap the wait so a response that never arrives can't hang forever. The timer
+      // is armed here and cleared by settle() the moment the matching frame lands (or the
+      // socket closes and onclose rejects every pending). unref so a pending request never
+      // by itself keeps the process alive.
+      const timer = setTimeout(() => {
+        if (!this.pending.has(id)) return;
+        this.pending.delete(id);
+        this.log(`request timed out after ${this.requestTimeoutMs}ms: ${method} (id=${id})`);
+        reject(new Error(`codex request timed out after ${this.requestTimeoutMs}ms: ${method}`));
+      }, this.requestTimeoutMs);
+      (timer as { unref?: () => void }).unref?.();
+      const settle = (fn: (value: any) => void) => (value: unknown) => {
+        clearTimeout(timer);
+        fn(value);
+      };
+      this.pending.set(id, { resolve: settle(resolve), reject: settle(reject) });
+    });
+    this.ws.send(JSON.stringify(payload));
+    return promise;
+  }
+
+  private handleMessage(raw: string): void {
+    // The frame comes from an external process over a WebSocket; a partial or
+    // malformed frame must not throw out of onmessage and drop the connection.
+    let parsed: JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+    try {
+      parsed = JSON.parse(raw) as JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+    } catch {
+      this.log(`dropped malformed frame (${raw.length} bytes)`);
+      return;
+    }
+
+    if ("id" in parsed && ("result" in parsed || "error" in parsed)) {
+      const pending = this.pending.get(parsed.id);
+      if (pending) {
+        this.pending.delete(parsed.id);
+        if (parsed.error) {
+          // #2539 Phase A — reject with the STRUCTURED error (code + data preserved) so the
+          // adapter can classify turn/steer rejections; the message keeps the legacy shape.
+          pending.reject(new CodexRpcError(parsed.error.code, parsed.error.message, parsed.error.data));
+        } else {
+          pending.resolve(parsed.result);
+        }
+      }
+      this.record({ type: "response", message: parsed }, raw.length);
+      return;
+    }
+
+    if ("id" in parsed && "method" in parsed) {
+      this.log(`server-request ${parsed.method}`);
+      this.record({ type: "server-request", message: parsed }, raw.length);
+      return;
+    }
+
+    if ("method" in parsed) {
+      this.record({ type: "notification", message: parsed }, raw.length);
+    }
+  }
+
+  private record(event: ClientEvent, size: number): void {
+    this.events.push({ event, size });
+    this.eventBytes += size;
+    // Decide how many oldest frames both ceilings require dropping, then drop them in ONE splice —
+    // this runs on every received frame, so a second shift of a 5,000-entry array would itself be
+    // the kind of steady per-frame churn #2504 is about.
+    let drop = Math.max(0, this.events.length - CODEX_APP_CLIENT_EVENT_CAP);
+    let bytes = this.eventBytes;
+    for (let i = 0; i < drop; i++) bytes -= this.events[i]!.size;
+    // `drop < length - 1` retains the newest frame however large it is, so an oversized frame can
+    // neither empty the ring nor spin this loop.
+    while (bytes > CODEX_APP_CLIENT_EVENT_BYTE_CAP && drop < this.events.length - 1) {
+      bytes -= this.events[drop]!.size;
+      drop++;
+    }
+    if (drop) {
+      this.events.splice(0, drop);
+      this.eventBytes = bytes;
+    }
+    for (const listener of this.listeners) listener(event);
+  }
+
+  private emitConnection(connected: boolean): void {
+    for (const listener of this.connectionListeners) listener(connected);
+  }
+}