@modelprofile.com/mcp-crossharness 5.0.0

package/ts/classes.connection.codex.ts

@@ -0,0 +1,1120 @@
+import * as plugins from './plugins.js';
+import * as helpers from './helpers.js';
+import { commitinfo } from './00_commitinfo_data.js';
+import type * as interfaces from './interfaces.js';
+
+const appServerVersion = '0.146.0';
+const maxSocketMessageBytes = 4 * 1024 * 1024;
+const maxSocketBufferedBytes = 4 * 1024 * 1024;
+const maxTurnTextChars = 1024 * 1024;
+const maxTurnDeltaChunks = 4096;
+const maxEarlyNotifications = 100;
+const maxQueuedSends = 100;
+const maxQueuedSendsPerThread = 10;
+
+interface ICodexThread {
+  id: string;
+  cwd: string;
+  updatedAt: number;
+  turns: unknown[];
+  preview?: string;
+  name?: string | null;
+  modelProvider?: string;
+  status?: unknown;
+}
+
+interface ICodexNotification {
+  method: string;
+  params: Record<string, unknown>;
+}
+
+interface IPendingRequest {
+  resolve: (valueArg: unknown) => void;
+  reject: (errorArg: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+  signal?: AbortSignal;
+  abortHandler?: () => void;
+}
+
+interface IPendingTurn {
+  threadId: string;
+  turnId?: string;
+  agentText: string;
+  deltaChunks: string[];
+  deltaChars: number;
+  earlyNotifications: Map<string, ICodexNotification[]>;
+  earlyNotificationCount: number;
+  earlyNotificationChars: number;
+  timeoutError?: Error;
+  interruptAcknowledged?: boolean;
+  terminalObserved?: boolean;
+  terminalTimer?: ReturnType<typeof setTimeout>;
+  resolve: (valueArg: interfaces.ISendResult) => void;
+  reject: (errorArg: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+interface IThreadQueueEntry {
+  deadline: number;
+  timeoutSeconds: number;
+  task: () => Promise<interfaces.ISendResult>;
+  resolve: (valueArg: interfaces.ISendResult) => void;
+  reject: (errorArg: Error) => void;
+  timer?: ReturnType<typeof setTimeout>;
+  signal?: AbortSignal;
+  abortHandler?: () => void;
+}
+
+export class CodexConnection implements interfaces.IHarnessConnection {
+  public readonly harness = 'codex' as const;
+  public state: interfaces.TConnectionState = 'connecting';
+  private connectedAt = new Date().toISOString();
+  private serverVersion: string | undefined;
+  private socket: InstanceType<typeof plugins.WsWebSocket> | undefined;
+  private requestCounter = 0;
+  private pendingRequests = new Map<number, IPendingRequest>();
+  private pendingTurns = new Set<IPendingTurn>();
+  private threadQueues = new Map<string, IThreadQueueEntry[]>();
+  private activeThreads = new Set<string>();
+  private queuedSends = 0;
+  private queuedSendsByThread = new Map<string, number>();
+  private connectStarted = false;
+
+  constructor(
+    public readonly connectionId: string,
+    public readonly serverUrl: string,
+    public readonly directory: string,
+    private onClosing?: () => void,
+    private onClosed?: () => void,
+  ) {}
+
+  public async connect(): Promise<void> {
+    if (this.connectStarted) {
+      throw new Error(`Codex connection ${this.connectionId} has already been started`);
+    }
+    this.connectStarted = true;
+    const headers: Record<string, string> = {};
+    const token = process.env.CODEX_REMOTE_TOKEN;
+    if (token) headers.authorization = `Bearer ${token}`;
+    const socket = new plugins.WsWebSocket(this.serverUrl, {
+      perMessageDeflate: false,
+      headers,
+      followRedirects: false,
+      maxPayload: maxSocketMessageBytes,
+    });
+    this.socket = socket;
+    socket.on('message', (data) => this.handleMessage(data.toString()));
+    socket.on('error', (error) => this.handleSocketFailure(error));
+    socket.on('close', () => this.handleSocketClose());
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = () => {
+        clearTimeout(timer);
+        socket.off('open', handleOpen);
+        socket.off('error', handleError);
+        socket.off('close', handleClose);
+      };
+      const handleOpen = () => {
+        cleanup();
+        resolve();
+      };
+      const handleError = (errorArg: Error) => {
+        cleanup();
+        reject(errorArg);
+      };
+      const handleClose = () => {
+        cleanup();
+        reject(new Error('Codex server WebSocket closed during handshake'));
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        socket.terminate();
+        reject(new Error('Codex server WebSocket handshake timed out'));
+      }, 5000);
+      socket.once('open', handleOpen);
+      socket.once('error', handleError);
+      socket.once('close', handleClose);
+    });
+    try {
+      const initialized = await this.request(
+        'initialize',
+        {
+          clientInfo: {
+            name: 'mcp-crossharness',
+            title: 'mcp-crossharness',
+            version: commitinfo.version,
+          },
+          capabilities: {
+            experimentalApi: false,
+            requestAttestation: false,
+          },
+        },
+        5000,
+        true,
+      );
+      if (!helpers.isRecord(initialized) || typeof initialized.userAgent !== 'string') {
+        throw new Error(
+          `Codex server returned an invalid initialize response (expected app-server ${appServerVersion})`,
+        );
+      }
+      this.serverVersion = initialized.userAgent.match(/\/(\d+\.\d+\.\d+[^\s]*)/)?.[1];
+      if (this.state !== 'connecting' || socket.readyState !== plugins.WsWebSocket.OPEN) {
+        throw new Error('Codex server connection closed during initialization');
+      }
+      this.sendNotification('initialized');
+      this.state = 'connected';
+    } catch (error) {
+      socket.terminate();
+      throw error;
+    }
+  }
+
+  public getInfo(): interfaces.IConnectionInfo {
+    return {
+      connectionId: this.connectionId,
+      harness: this.harness,
+      serverUrl: this.serverUrl,
+      directory: this.directory,
+      state: this.state,
+      connectedAt: this.connectedAt,
+      serverVersion: this.serverVersion,
+    };
+  }
+
+  public async getStatus(): Promise<interfaces.IConnectionStatus> {
+    if (this.state !== 'connected') {
+      return { ...this.getInfo(), healthy: false, detail: `connection is ${this.state}` };
+    }
+    try {
+      const response = await this.request('thread/loaded/list', {}, 5000);
+      const healthy = helpers.isRecord(response) && Array.isArray(response.data);
+      return {
+        ...this.getInfo(),
+        healthy,
+        detail: healthy ? 'Codex app-server answered thread/loaded/list' : 'invalid health response',
+      };
+    } catch (error) {
+      return { ...this.getInfo(), healthy: false, detail: helpers.errorMessage(error) };
+    }
+  }
+
+  public async listChats(limitArg: number): Promise<interfaces.IChatSummary[]> {
+    const payload = await this.request('thread/list', {
+      limit: limitArg,
+      sortKey: 'updated_at',
+      sortDirection: 'desc',
+      archived: false,
+      cwd: this.directory,
+    });
+    if (!helpers.isRecord(payload) || !Array.isArray(payload.data)) {
+      throw new Error('Codex server returned an invalid thread list');
+    }
+    return payload.data.map((entry) => {
+      const thread = this.parseThread(entry);
+      this.assertThreadIdentity(thread, thread.id);
+      return {
+        harness: this.harness,
+        chatId: thread.id,
+        title: thread.name ?? thread.preview ?? '(untitled)',
+        directory: thread.cwd,
+        updatedAt: new Date(thread.updatedAt * 1000).toISOString(),
+        isActive: helpers.isRecord(thread.status) && thread.status.type === 'active',
+        meta: thread.modelProvider ? { modelProvider: thread.modelProvider } : undefined,
+      };
+    });
+  }
+
+  public async readChat(
+    chatIdArg: string,
+    limitArg: number,
+    maxCharsArg: number,
+  ): Promise<interfaces.IChatTranscript> {
+    this.assertChatId(chatIdArg);
+    const thread = await this.readThread(chatIdArg, true);
+    const messages: interfaces.IChatMessage[] = [];
+    for (const turn of thread.turns) {
+      if (!helpers.isRecord(turn) || !Array.isArray(turn.items)) continue;
+      for (const item of turn.items) {
+        if (!helpers.isRecord(item) || typeof item.type !== 'string') continue;
+        if (item.type === 'userMessage' && Array.isArray(item.content)) {
+          const text = item.content
+            .filter((content) => helpers.isRecord(content) && content.type === 'text')
+            .map((content) => String((content as Record<string, unknown>).text ?? ''))
+            .join('\n')
+            .trim();
+          if (text) messages.push({ role: 'user', text: helpers.truncateText(text, maxCharsArg) });
+        } else if (item.type === 'agentMessage' && typeof item.text === 'string') {
+          messages.push({ role: 'assistant', text: helpers.truncateText(item.text, maxCharsArg) });
+        }
+      }
+    }
+    const limited = messages.slice(-limitArg);
+    return {
+      harness: this.harness,
+      chatId: chatIdArg,
+      title: thread.name ?? thread.preview ?? '(untitled)',
+      directory: thread.cwd,
+      totalMessages: messages.length,
+      messages: limited,
+    };
+  }
+
+  public async sendMessage(
+    chatIdArg: string,
+    messageArg: string,
+    timeoutSecondsArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<interfaces.ISendResult> {
+    this.assertChatId(chatIdArg);
+    if (messageArg.length > maxTurnTextChars) {
+      throw new Error('Codex message exceeds the 1 MiB character limit');
+    }
+    const threadQueueSize = this.queuedSendsByThread.get(chatIdArg) ?? 0;
+    if (this.queuedSends >= maxQueuedSends || threadQueueSize >= maxQueuedSendsPerThread) {
+      throw new Error('Codex send queue is full');
+    }
+    this.queuedSends++;
+    this.queuedSendsByThread.set(chatIdArg, threadQueueSize + 1);
+    const deadline = Date.now() + timeoutSecondsArg * 1000;
+    try {
+      return await this.enqueueThreadSend(
+        chatIdArg,
+        deadline,
+        timeoutSecondsArg,
+        signalArg,
+        () =>
+          this.sendMessageInner(
+            chatIdArg,
+            messageArg,
+            deadline,
+            timeoutSecondsArg,
+            signalArg,
+          ),
+      );
+    } finally {
+      this.queuedSends--;
+      const remainingForThread = (this.queuedSendsByThread.get(chatIdArg) ?? 1) - 1;
+      if (remainingForThread > 0) this.queuedSendsByThread.set(chatIdArg, remainingForThread);
+      else this.queuedSendsByThread.delete(chatIdArg);
+    }
+  }
+
+  private async sendMessageInner(
+    chatIdArg: string,
+    messageArg: string,
+    deadlineArg: number,
+    timeoutSecondsArg: number,
+    signalArg?: AbortSignal,
+  ): Promise<interfaces.ISendResult> {
+    await this.readThread(
+      chatIdArg,
+      false,
+      this.remainingSendMs(deadlineArg, timeoutSecondsArg),
+      signalArg,
+    );
+    const resumed = await this.request(
+      'thread/resume',
+      { threadId: chatIdArg },
+      this.remainingSendMs(deadlineArg, timeoutSecondsArg),
+      false,
+      signalArg,
+    );
+    if (
+      !helpers.isRecord(resumed) ||
+      !helpers.isRecord(resumed.thread) ||
+      typeof resumed.cwd !== 'string'
+    ) {
+      throw new Error('Codex server returned an invalid thread/resume response');
+    }
+    const resumedThread = this.parseThread(resumed.thread);
+    this.assertThreadIdentity(resumedThread, chatIdArg);
+    if (resumed.cwd !== this.directory) {
+      throw new Error(`Codex thread ${chatIdArg} resumed outside the connection directory`);
+    }
+    const turnTimeoutMs = this.remainingSendMs(deadlineArg, timeoutSecondsArg);
+    if (signalArg?.aborted) throw this.abortError(signalArg.reason);
+
+    return new Promise<interfaces.ISendResult>((resolve, reject) => {
+      const turn: IPendingTurn = {
+        threadId: chatIdArg,
+        agentText: '',
+        deltaChunks: [],
+        deltaChars: 0,
+        earlyNotifications: new Map(),
+        earlyNotificationCount: 0,
+        earlyNotificationChars: 0,
+        resolve,
+        reject,
+        timer: setTimeout(
+          () => void this.timeoutTurn(turn, timeoutSecondsArg),
+          turnTimeoutMs,
+        ),
+      };
+      this.pendingTurns.add(turn);
+      void this.request(
+        'turn/start',
+        {
+          threadId: chatIdArg,
+          clientUserMessageId: plugins.crypto.randomUUID(),
+          input: [{ type: 'text', text: messageArg, text_elements: [] }],
+          cwd: this.directory,
+        },
+        turnTimeoutMs,
+      )
+        .then((result) => {
+          if (!this.pendingTurns.has(turn)) return;
+          let turnId: string;
+          try {
+            turnId = this.extractTurnId(result);
+          } catch (error) {
+            this.failUncertainTurnStart(turn, error);
+            return;
+          }
+          this.bindTurnId(turn, turnId);
+        })
+        .catch((error) => this.failUncertainTurnStart(turn, error));
+    });
+  }
+
+  private enqueueThreadSend(
+    threadIdArg: string,
+    deadlineArg: number,
+    timeoutSecondsArg: number,
+    signalArg: AbortSignal | undefined,
+    taskArg: () => Promise<interfaces.ISendResult>,
+  ): Promise<interfaces.ISendResult> {
+    return new Promise((resolve, reject) => {
+      const entry: IThreadQueueEntry = {
+        deadline: deadlineArg,
+        timeoutSeconds: timeoutSecondsArg,
+        task: taskArg,
+        resolve,
+        reject,
+        signal: signalArg,
+      };
+      if (signalArg?.aborted) {
+        reject(this.abortError(signalArg.reason));
+        return;
+      }
+      const queue = this.threadQueues.get(threadIdArg) ?? [];
+      queue.push(entry);
+      this.threadQueues.set(threadIdArg, queue);
+      entry.timer = setTimeout(
+        () => this.timeoutQueuedSend(threadIdArg, entry),
+        Math.max(0, deadlineArg - Date.now()),
+      );
+      if (signalArg) {
+        entry.abortHandler = () => this.cancelThreadSend(threadIdArg, entry);
+        signalArg.addEventListener('abort', entry.abortHandler, { once: true });
+      }
+      this.drainThreadQueue(threadIdArg);
+    });
+  }
+
+  public async close(reasonArg = 'connection disconnected'): Promise<void> {
+    if (this.state === 'closed') return;
+    if (this.state !== 'closing') {
+      this.state = 'closing';
+      this.rejectAll(new Error(reasonArg));
+      this.onClosing?.();
+      this.onClosing = undefined;
+    }
+    await this.closeSocket();
+    this.finishClosed();
+  }
+
+  private async readThread(
+    chatIdArg: string,
+    includeTurnsArg: boolean,
+    timeoutMsArg = 30000,
+    signalArg?: AbortSignal,
+  ): Promise<ICodexThread> {
+    const payload = await this.request('thread/read', {
+      threadId: chatIdArg,
+      includeTurns: includeTurnsArg,
+    }, timeoutMsArg, false, signalArg);
+    if (!helpers.isRecord(payload) || !helpers.isRecord(payload.thread)) {
+      throw new Error('Codex server returned an invalid thread');
+    }
+    const thread = this.parseThread(payload.thread);
+    this.assertThreadIdentity(thread, chatIdArg);
+    return thread;
+  }
+
+  private parseThread(valueArg: unknown): ICodexThread {
+    if (
+      !helpers.isRecord(valueArg) ||
+      typeof valueArg.id !== 'string' ||
+      typeof valueArg.cwd !== 'string' ||
+      typeof valueArg.updatedAt !== 'number' ||
+      !Array.isArray(valueArg.turns)
+    ) {
+      throw new Error('Codex server returned an invalid thread');
+    }
+    return {
+      id: valueArg.id,
+      cwd: valueArg.cwd,
+      updatedAt: valueArg.updatedAt,
+      turns: valueArg.turns,
+      preview: typeof valueArg.preview === 'string' ? valueArg.preview : undefined,
+      name: typeof valueArg.name === 'string' || valueArg.name === null ? valueArg.name : undefined,
+      modelProvider:
+        typeof valueArg.modelProvider === 'string' ? valueArg.modelProvider : undefined,
+      status: valueArg.status,
+    };
+  }
+
+  private assertThreadIdentity(threadArg: ICodexThread, chatIdArg: string): void {
+    if (threadArg.id !== chatIdArg) {
+      throw new Error(`Codex server returned a different thread for ${chatIdArg}`);
+    }
+    if (threadArg.cwd !== this.directory) {
+      throw new Error(`Codex thread ${chatIdArg} is outside the connection directory`);
+    }
+  }
+
+  private request(
+    methodArg: string,
+    paramsArg: unknown,
+    timeoutMsArg = 30000,
+    allowConnectingArg = false,
+    signalArg?: AbortSignal,
+  ): Promise<unknown> {
+    if (!allowConnectingArg && this.state !== 'connected') {
+      return Promise.reject(new Error(`Codex connection ${this.connectionId} is ${this.state}`));
+    }
+    const socket = this.socket;
+    if (!socket || socket.readyState !== plugins.WsWebSocket.OPEN) {
+      return Promise.reject(new Error('Codex server WebSocket is not open'));
+    }
+    if (this.pendingRequests.size >= 256) {
+      return Promise.reject(new Error('Codex connection has too many active requests'));
+    }
+    if (signalArg?.aborted) return Promise.reject(this.abortError(signalArg.reason));
+    return new Promise((resolve, reject) => {
+      const id = ++this.requestCounter;
+      const timer = setTimeout(() => {
+        const pending = this.pendingRequests.get(id);
+        if (!pending) return;
+        this.pendingRequests.delete(id);
+        this.clearPendingRequestResources(pending);
+        reject(new Error(`Codex request timed out: ${methodArg}`));
+      }, timeoutMsArg);
+      const pending: IPendingRequest = { resolve, reject, timer, signal: signalArg };
+      if (signalArg) {
+        pending.abortHandler = () => {
+          if (!this.pendingRequests.delete(id)) return;
+          this.clearPendingRequestResources(pending);
+          reject(this.abortError(signalArg.reason));
+        };
+        signalArg.addEventListener('abort', pending.abortHandler, { once: true });
+      }
+      this.pendingRequests.set(id, pending);
+      const failSend = (errorArg: Error) => {
+        const current = this.pendingRequests.get(id);
+        if (!current) return;
+        this.pendingRequests.delete(id);
+        this.clearPendingRequestResources(current);
+        current.reject(errorArg);
+      };
+      try {
+        this.sendFrame({ id, method: methodArg, params: paramsArg });
+      } catch (error) {
+        failSend(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+
+  private sendNotification(methodArg: string, paramsArg?: unknown): void {
+    this.sendFrame(
+      paramsArg === undefined
+        ? { method: methodArg }
+        : { method: methodArg, params: paramsArg },
+    );
+  }
+
+  private sendFrame(frameArg: Record<string, unknown>): void {
+    const socket = this.socket;
+    const payload = JSON.stringify(frameArg);
+    const payloadBytes = Buffer.byteLength(payload, 'utf8');
+    if (!socket || socket.readyState !== plugins.WsWebSocket.OPEN) {
+      const error = new Error('Codex server WebSocket is not open');
+      this.handleSocketFailure(error);
+      throw error;
+    }
+    if (socket.bufferedAmount + payloadBytes > maxSocketBufferedBytes) {
+      const error = new Error('Codex WebSocket send buffer exceeded the 4 MiB limit');
+      this.handleSocketFailure(error);
+      throw error;
+    }
+    try {
+      socket.send(payload, (error) => {
+        if (error) this.handleSocketFailure(error);
+      });
+    } catch (error) {
+      const sendError = error instanceof Error ? error : new Error(String(error));
+      this.handleSocketFailure(sendError);
+      throw sendError;
+    }
+  }
+
+  private handleMessage(rawArg: string): void {
+    const message = helpers.parseJson(rawArg);
+    if (!helpers.isRecord(message)) return;
+    if (message.id !== undefined && typeof message.method === 'string') {
+      this.respondToServerRequest(message);
+      return;
+    }
+    if (typeof message.id === 'number' && this.pendingRequests.has(message.id)) {
+      const pending = this.pendingRequests.get(message.id)!;
+      this.pendingRequests.delete(message.id);
+      this.clearPendingRequestResources(pending);
+      if (message.error !== undefined) {
+        pending.reject(
+          new Error(
+            `Codex server rejected request: ${JSON.stringify(message.error).slice(0, 4000)}`,
+          ),
+        );
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+    if (typeof message.method === 'string') {
+      if (!helpers.isRecord(message.params)) {
+        if (message.method === 'turn/completed') {
+          this.handleSocketFailure(new Error('Codex returned malformed turn/completed params'));
+        }
+        return;
+      }
+      this.handleNotification(message.method, message.params);
+    }
+  }
+
+  private handleNotification(methodArg: string, paramsArg: Record<string, unknown>): void {
+    if (methodArg === 'turn/completed') {
+      if (
+        !helpers.isRecord(paramsArg.turn) ||
+        typeof paramsArg.turn.id !== 'string' ||
+        (paramsArg.turnId !== undefined && paramsArg.turnId !== paramsArg.turn.id)
+      ) {
+        this.handleSocketFailure(new Error('Codex returned malformed turn/completed identity'));
+        return;
+      }
+    }
+    const threadId = typeof paramsArg.threadId === 'string' ? paramsArg.threadId : undefined;
+    const turnId =
+      typeof paramsArg.turnId === 'string'
+        ? paramsArg.turnId
+        : helpers.isRecord(paramsArg.turn) && typeof paramsArg.turn.id === 'string'
+          ? paramsArg.turn.id
+          : undefined;
+    if (!threadId || !turnId) {
+      if (methodArg === 'turn/completed') {
+        this.handleSocketFailure(new Error('Codex returned malformed turn/completed identity'));
+      }
+      return;
+    }
+    const turn = [...this.pendingTurns].find(
+      (candidate) => candidate.threadId === threadId && candidate.turnId === turnId,
+    );
+    if (!turn) {
+      const unbound = [...this.pendingTurns].filter(
+        (candidate) => candidate.threadId === threadId && !candidate.turnId,
+      );
+      if (unbound.length === 1) this.bufferEarlyNotification(unbound[0], turnId, methodArg, paramsArg);
+      return;
+    }
+    this.handleTurnNotification(turn, methodArg, paramsArg);
+  }
+
+  private handleTurnNotification(
+    turnArg: IPendingTurn,
+    methodArg: string,
+    paramsArg: Record<string, unknown>,
+  ): void {
+    if (methodArg === 'turn/completed' && !helpers.isRecord(paramsArg.turn)) {
+      this.handleSocketFailure(new Error('Codex returned malformed turn/completed payload'));
+      return;
+    }
+    if (methodArg === 'item/agentMessage/delta' && typeof paramsArg.delta === 'string') {
+      this.appendTurnDelta(turnArg, paramsArg.delta);
+    } else if (methodArg === 'item/completed' && helpers.isRecord(paramsArg.item)) {
+      if (paramsArg.item.type === 'agentMessage' && typeof paramsArg.item.text === 'string') {
+        if (paramsArg.item.text.length > maxTurnTextChars) {
+          this.handleSocketFailure(new Error('Codex turn output exceeded the response limit'));
+          return;
+        }
+        turnArg.agentText = paramsArg.item.text;
+      }
+    } else if (methodArg === 'turn/completed' && helpers.isRecord(paramsArg.turn)) {
+      const status = paramsArg.turn.status;
+      if (turnArg.timeoutError) {
+        if (status !== 'completed' && status !== 'interrupted' && status !== 'failed') {
+          this.handleSocketFailure(
+            new Error('Codex returned a non-terminal status in turn/completed'),
+          );
+          return;
+        }
+        turnArg.terminalObserved = true;
+        this.rejectTimedOutTurnIfSafe(turnArg);
+        return;
+      }
+      if (status === 'completed') {
+        this.completeTurn(turnArg);
+      } else if (status === 'interrupted' || status === 'failed') {
+        const turnError = helpers.isRecord(paramsArg.turn.error)
+          ? String(paramsArg.turn.error.message ?? status)
+          : String(status);
+        this.failTurn(turnArg, new Error(`Codex turn ${status}: ${turnError}`));
+      } else {
+        this.handleSocketFailure(
+          new Error('Codex returned a non-terminal status in turn/completed'),
+        );
+      }
+    }
+  }
+
+  private bindTurnId(turnArg: IPendingTurn, turnIdArg: string): void {
+    if (!this.pendingTurns.has(turnArg)) return;
+    if (turnArg.turnId && turnArg.turnId !== turnIdArg) {
+      this.failTurn(turnArg, new Error('Codex turn identity changed during dispatch'));
+      return;
+    }
+    const collision = [...this.pendingTurns].find(
+      (candidate) => candidate !== turnArg && candidate.turnId === turnIdArg,
+    );
+    if (collision) {
+      this.handleSocketFailure(new Error('Codex reused a turn id across concurrent sends'));
+      return;
+    }
+    turnArg.turnId = turnIdArg;
+    const buffered = turnArg.earlyNotifications.get(turnIdArg) ?? [];
+    turnArg.earlyNotifications.clear();
+    turnArg.earlyNotificationCount = 0;
+    turnArg.earlyNotificationChars = 0;
+    for (const notification of buffered) {
+      if (!this.pendingTurns.has(turnArg)) break;
+      this.handleTurnNotification(turnArg, notification.method, notification.params);
+    }
+  }
+
+  private extractTurnId(valueArg: unknown): string {
+    if (!helpers.isRecord(valueArg) || !helpers.isRecord(valueArg.turn) || typeof valueArg.turn.id !== 'string') {
+      throw new Error('Codex server returned an invalid turn/start response');
+    }
+    return valueArg.turn.id;
+  }
+
+  private completeTurn(turnArg: IPendingTurn): void {
+    if (!this.settleTurn(turnArg)) return;
+    const reply = (turnArg.agentText || turnArg.deltaChunks.join('')).trim();
+    if (!reply) {
+      turnArg.reject(new Error('Codex turn completed without assistant text'));
+      return;
+    }
+    turnArg.resolve({
+      harness: this.harness,
+      chatId: turnArg.threadId,
+      reply,
+      via: `ws:${this.serverUrl}`,
+    });
+  }
+
+  private failTurn(turnArg: IPendingTurn, errorArg: unknown): void {
+    if (!this.settleTurn(turnArg)) return;
+    turnArg.reject(errorArg instanceof Error ? errorArg : new Error(String(errorArg)));
+  }
+
+  private async timeoutTurn(turnArg: IPendingTurn, timeoutSecondsArg: number): Promise<void> {
+    if (!this.pendingTurns.has(turnArg) || turnArg.timeoutError) return;
+    const timeoutError = new Error(
+      `Codex turn timed out after ${timeoutSecondsArg}s; Crossharness did not retry`,
+    );
+    turnArg.timeoutError = timeoutError;
+    const turnId = turnArg.turnId;
+    if (!turnId) {
+      const fatalError = new Error(
+        `${timeoutError.message}; no turn id was available to interrupt safely, so the connection was closed`,
+      );
+      this.handleSocketFailure(fatalError);
+      return;
+    }
+    try {
+      await this.request('turn/interrupt', { threadId: turnArg.threadId, turnId }, 3000);
+      if (!this.pendingTurns.has(turnArg)) return;
+      turnArg.interruptAcknowledged = true;
+      if (turnArg.terminalObserved) {
+        this.rejectTimedOutTurnIfSafe(turnArg);
+        return;
+      }
+      turnArg.terminalTimer = setTimeout(() => {
+        if (!this.pendingTurns.has(turnArg)) return;
+        this.handleSocketFailure(
+          new Error(
+            `${timeoutError.message}; the interrupted turn did not report terminal completion, so the connection was closed`,
+          ),
+        );
+      }, 3000);
+      turnArg.terminalTimer.unref();
+    } catch (error) {
+      const fatalError = new Error(
+        `${timeoutError.message}; turn/interrupt was not acknowledged, so the connection was closed: ${helpers.errorMessage(error)}`,
+        { cause: error },
+      );
+      this.handleSocketFailure(fatalError);
+    }
+  }
+
+  private async cancelActiveTurn(turnArg: IPendingTurn, errorArg: Error): Promise<void> {
+    if (!this.pendingTurns.has(turnArg) || turnArg.timeoutError) return;
+    turnArg.timeoutError = errorArg;
+    const turnId = turnArg.turnId;
+    if (!turnId) {
+      this.handleSocketFailure(
+        new Error(
+          `${errorArg.message}; no turn id was available to interrupt safely, so the connection was closed`,
+        ),
+      );
+      return;
+    }
+    try {
+      await this.request('turn/interrupt', { threadId: turnArg.threadId, turnId }, 3000);
+      if (!this.pendingTurns.has(turnArg)) return;
+      turnArg.interruptAcknowledged = true;
+      if (turnArg.terminalObserved) {
+        this.rejectTimedOutTurnIfSafe(turnArg);
+        return;
+      }
+      turnArg.terminalTimer = setTimeout(() => {
+        if (!this.pendingTurns.has(turnArg)) return;
+        this.handleSocketFailure(
+          new Error(
+            `${errorArg.message}; the interrupted turn did not report terminal completion, so the connection was closed`,
+          ),
+        );
+      }, 3000);
+      turnArg.terminalTimer.unref();
+    } catch (error) {
+      this.handleSocketFailure(
+        new Error(
+          `${errorArg.message}; turn/interrupt was not acknowledged, so the connection was closed: ${helpers.errorMessage(error)}`,
+          { cause: error },
+        ),
+      );
+    }
+  }
+
+  private timeoutQueuedSend(threadIdArg: string, entryArg: IThreadQueueEntry): void {
+    if (this.activeThreads.has(threadIdArg)) {
+      const queue = this.threadQueues.get(threadIdArg);
+      if (queue?.[0] === entryArg) return;
+    }
+    const queue = this.threadQueues.get(threadIdArg);
+    if (!queue) return;
+    const index = queue.indexOf(entryArg);
+    if (index < 0) return;
+    queue.splice(index, 1);
+    this.clearQueueEntryResources(entryArg);
+    entryArg.reject(
+      new Error(
+        `Codex send timed out after ${entryArg.timeoutSeconds}s while queued; no message was delivered`,
+      ),
+    );
+    if (queue.length === 0 && !this.activeThreads.has(threadIdArg)) {
+      this.threadQueues.delete(threadIdArg);
+    }
+  }
+
+  private cancelThreadSend(threadIdArg: string, entryArg: IThreadQueueEntry): void {
+    const queue = this.threadQueues.get(threadIdArg);
+    if (!queue) return;
+    const index = queue.indexOf(entryArg);
+    if (index < 0) return;
+    if (index === 0 && this.activeThreads.has(threadIdArg)) {
+      const turn = [...this.pendingTurns].find((candidate) => candidate.threadId === threadIdArg);
+      if (turn) void this.cancelActiveTurn(turn, this.abortError(entryArg.signal?.reason));
+      return;
+    }
+    queue.splice(index, 1);
+    this.clearQueueEntryResources(entryArg);
+    entryArg.reject(this.abortError(entryArg.signal?.reason));
+    if (queue.length === 0 && !this.activeThreads.has(threadIdArg)) {
+      this.threadQueues.delete(threadIdArg);
+    }
+  }
+
+  private drainThreadQueue(threadIdArg: string): void {
+    if (this.activeThreads.has(threadIdArg)) return;
+    const queue = this.threadQueues.get(threadIdArg);
+    const entry = queue?.[0];
+    if (!queue || !entry) {
+      this.threadQueues.delete(threadIdArg);
+      return;
+    }
+    if (entry.deadline <= Date.now()) {
+      this.timeoutQueuedSend(threadIdArg, entry);
+      this.drainThreadQueue(threadIdArg);
+      return;
+    }
+    this.activeThreads.add(threadIdArg);
+    if (entry.timer) clearTimeout(entry.timer);
+    void entry.task().then(entry.resolve, entry.reject).finally(() => {
+      this.clearQueueEntryResources(entry);
+      this.activeThreads.delete(threadIdArg);
+      const currentQueue = this.threadQueues.get(threadIdArg);
+      if (currentQueue?.[0] === entry) currentQueue.shift();
+      if (currentQueue?.length === 0) this.threadQueues.delete(threadIdArg);
+      this.drainThreadQueue(threadIdArg);
+    });
+  }
+
+  private appendTurnDelta(turnArg: IPendingTurn, deltaArg: string): void {
+    if (turnArg.deltaChunks.length >= maxTurnDeltaChunks) {
+      this.handleSocketFailure(new Error('Codex turn output exceeded the delta chunk limit'));
+      return;
+    }
+    if (turnArg.deltaChars + deltaArg.length > maxTurnTextChars) {
+      this.handleSocketFailure(new Error('Codex turn output exceeded the response limit'));
+      return;
+    }
+    turnArg.deltaChunks.push(deltaArg);
+    turnArg.deltaChars += deltaArg.length;
+  }
+
+  private remainingSendMs(deadlineArg: number, timeoutSecondsArg: number): number {
+    const remainingMs = deadlineArg - Date.now();
+    if (remainingMs <= 0) {
+      throw new Error(
+        `Codex send timed out after ${timeoutSecondsArg}s before turn/start; no message was delivered`,
+      );
+    }
+    return remainingMs;
+  }
+
+  private clearQueueEntryResources(entryArg: IThreadQueueEntry): void {
+    if (entryArg.timer) clearTimeout(entryArg.timer);
+    if (entryArg.abortHandler) {
+      entryArg.signal?.removeEventListener('abort', entryArg.abortHandler);
+    }
+  }
+
+  private clearPendingRequestResources(pendingArg: IPendingRequest): void {
+    clearTimeout(pendingArg.timer);
+    if (pendingArg.abortHandler) {
+      pendingArg.signal?.removeEventListener('abort', pendingArg.abortHandler);
+    }
+  }
+
+  private abortError(reasonArg: unknown): Error {
+    return reasonArg instanceof Error ? reasonArg : new Error('operation cancelled');
+  }
+
+  private assertChatId(chatIdArg: string): void {
+    if (!chatIdArg || chatIdArg.length > 1024) {
+      throw new Error('Codex chatId must contain 1-1024 characters');
+    }
+  }
+
+  private bufferEarlyNotification(
+    turnArg: IPendingTurn,
+    turnIdArg: string,
+    methodArg: string,
+    paramsArg: Record<string, unknown>,
+  ): void {
+    const notification = this.normalizeEarlyNotification(methodArg, paramsArg);
+    if (!notification) return;
+    turnArg.earlyNotificationCount++;
+    if (turnArg.earlyNotificationCount > maxEarlyNotifications) {
+      this.handleSocketFailure(
+        new Error('Codex sent too many turn notifications before acknowledging turn/start'),
+      );
+      return;
+    }
+    const notificationChars = JSON.stringify(notification).length;
+    turnArg.earlyNotificationChars += notificationChars;
+    if (turnArg.earlyNotificationChars > maxTurnTextChars) {
+      this.handleSocketFailure(
+        new Error('Codex buffered turn notifications exceeded the response limit'),
+      );
+      return;
+    }
+    const notifications = turnArg.earlyNotifications.get(turnIdArg) ?? [];
+    notifications.push(notification);
+    turnArg.earlyNotifications.set(turnIdArg, notifications);
+  }
+
+  private normalizeEarlyNotification(
+    methodArg: string,
+    paramsArg: Record<string, unknown>,
+  ): ICodexNotification | undefined {
+    if (methodArg === 'item/agentMessage/delta' && typeof paramsArg.delta === 'string') {
+      return { method: methodArg, params: { delta: paramsArg.delta } };
+    }
+    if (methodArg === 'item/completed' && helpers.isRecord(paramsArg.item)) {
+      const item = paramsArg.item;
+      if (item.type === 'agentMessage' && typeof item.text === 'string') {
+        return { method: methodArg, params: { item: { type: item.type, text: item.text } } };
+      }
+      return undefined;
+    }
+    if (methodArg === 'turn/completed' && helpers.isRecord(paramsArg.turn)) {
+      const turn = paramsArg.turn;
+      return {
+        method: methodArg,
+        params: {
+          turn: {
+            status: turn.status,
+            error: helpers.isRecord(turn.error) ? { message: turn.error.message } : turn.error,
+          },
+        },
+      };
+    }
+    return undefined;
+  }
+
+  private failUncertainTurnStart(turnArg: IPendingTurn, errorArg: unknown): void {
+    if (!this.pendingTurns.has(turnArg)) return;
+    const fatalError = new Error(
+      `Codex turn/start outcome is uncertain, so the connection was closed: ${helpers.errorMessage(errorArg)}`,
+      { cause: errorArg },
+    );
+    this.handleSocketFailure(fatalError);
+  }
+
+  private rejectTimedOutTurnIfSafe(turnArg: IPendingTurn): void {
+    const error = turnArg.timeoutError;
+    if (
+      !error ||
+      !turnArg.interruptAcknowledged ||
+      !turnArg.terminalObserved ||
+      !this.settleTurn(turnArg)
+    ) {
+      return;
+    }
+    turnArg.reject(error);
+  }
+
+  private settleTurn(turnArg: IPendingTurn): boolean {
+    if (!this.pendingTurns.delete(turnArg)) return false;
+    clearTimeout(turnArg.timer);
+    if (turnArg.terminalTimer) clearTimeout(turnArg.terminalTimer);
+    turnArg.earlyNotifications.clear();
+    return true;
+  }
+
+  private respondToServerRequest(messageArg: Record<string, unknown>): void {
+    const method = String(messageArg.method);
+    let result: unknown;
+    switch (method) {
+      case 'item/commandExecution/requestApproval':
+      case 'item/fileChange/requestApproval':
+        result = { decision: 'decline' };
+        break;
+      case 'item/tool/requestUserInput':
+        result = { answers: {} };
+        break;
+      case 'mcpServer/elicitation/request':
+        result = { action: 'decline', content: null, _meta: null };
+        break;
+      case 'item/permissions/requestApproval':
+        result = { permissions: {}, scope: 'turn' };
+        break;
+      case 'applyPatchApproval':
+      case 'execCommandApproval':
+        result = { decision: 'abort' };
+        break;
+      default:
+        try {
+          this.sendFrame({
+            id: messageArg.id,
+            error: { code: -32601, message: `Crossharness does not implement ${method}` },
+          });
+        } catch {}
+        return;
+    }
+    try {
+      this.sendFrame({ id: messageArg.id, result });
+    } catch {}
+  }
+
+  private handleSocketFailure(errorArg: Error): void {
+    if (this.state === 'closed') return;
+    if (this.state !== 'closing') {
+      this.state = 'closing';
+      this.rejectAll(errorArg);
+      this.onClosing?.();
+      this.onClosing = undefined;
+    }
+    const socket = this.socket;
+    if (socket && socket.readyState !== plugins.WsWebSocket.CLOSED) {
+      socket.terminate();
+    } else {
+      this.finishClosed();
+    }
+  }
+
+  private handleSocketClose(): void {
+    if (this.state !== 'closing' && this.state !== 'closed') {
+      this.state = 'closing';
+      this.rejectAll(new Error('Codex server connection closed'));
+      this.onClosing?.();
+      this.onClosing = undefined;
+    }
+    this.finishClosed();
+  }
+
+  private finishClosed(): void {
+    if (this.state === 'closed') return;
+    this.state = 'closed';
+    this.onClosed?.();
+    this.onClosing = undefined;
+    this.onClosed = undefined;
+  }
+
+  private rejectAll(errorArg: Error): void {
+    for (const pending of this.pendingRequests.values()) {
+      this.clearPendingRequestResources(pending);
+      pending.reject(errorArg);
+    }
+    this.pendingRequests.clear();
+    for (const turn of [...this.pendingTurns]) this.failTurn(turn, errorArg);
+    for (const [threadId, queue] of this.threadQueues) {
+      const activeOffset = this.activeThreads.has(threadId) ? 1 : 0;
+      for (const entry of queue.slice(activeOffset)) {
+        this.clearQueueEntryResources(entry);
+        entry.reject(errorArg);
+      }
+    }
+    this.threadQueues.clear();
+  }
+
+  private async closeSocket(): Promise<void> {
+    const socket = this.socket;
+    if (!socket || socket.readyState === plugins.WsWebSocket.CLOSED) return;
+    await new Promise<void>((resolve) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        socket.off('close', finish);
+        resolve();
+      };
+      const timer = setTimeout(() => {
+        socket.terminate();
+        finish();
+      }, 1000);
+      socket.once('close', finish);
+      try {
+        if (socket.readyState === plugins.WsWebSocket.CONNECTING) {
+          socket.terminate();
+        } else {
+          socket.close();
+        }
+      } catch {
+        socket.terminate();
+        finish();
+      }
+    });
+  }
+}