@modelprofile.com/mcp-crossharness 5.1.0 → 5.2.0

package/ts/classes.codexappserverclient.ts

@@ -0,0 +1,331 @@
+import * as plugins from './plugins.js';
+import * as helpers from './helpers.js';
+
+export type TCodexAppServerRequestId = string | number;
+
+export interface ICodexAppServerNotification {
+  method: string;
+  params: Record<string, unknown>;
+}
+
+export interface ICodexAppServerRequest extends ICodexAppServerNotification {
+  id: TCodexAppServerRequestId;
+  signal: AbortSignal;
+}
+
+export type TCodexAppServerTransport =
+  | { type: 'websocket'; url: string; token?: string }
+  | { type: 'stdio'; readable: plugins.stream.Readable; writable: plugins.stream.Writable };
+
+export interface ICodexAppServerClientOptions {
+  transport: TCodexAppServerTransport;
+  clientInfo: { name: string; title: string; version: string };
+  experimentalApi?: boolean;
+  /** Defaults to 4 MiB; consumers of paginated native histories may opt into up to 64 MiB. */
+  maxMessageBytes?: number;
+  onNotification?: (notificationArg: ICodexAppServerNotification) => void;
+  /** Replies use respond()/rejectRequest(); IDs are valid only on this connection. */
+  onServerRequest?: (requestArg: ICodexAppServerRequest) => void;
+  onClose?: (errorArg: Error) => void;
+}
+
+interface IPendingRequest {
+  resolve: (valueArg: unknown) => void;
+  reject: (errorArg: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+  signal?: AbortSignal;
+  abortHandler?: () => void;
+}
+
+/** A request failure is not evidence that a dispatched mutation did not execute. */
+export class CodexAppServerRequestError extends Error {
+  constructor(
+    messageArg: string,
+    public readonly dispatched: boolean,
+    public readonly code?: number,
+    optionsArg?: ErrorOptions,
+  ) {
+    super(messageArg, optionsArg);
+    this.name = 'CodexAppServerRequestError';
+  }
+}
+
+/** Connection-scoped app-server protocol client. Process and approval policy belong to the caller. */
+export class CodexAppServerClient {
+  public state: 'connecting' | 'connected' | 'closed' = 'connecting';
+  public serverVersion?: string;
+  private socket?: InstanceType<typeof plugins.WsWebSocket>;
+  private started = false;
+  private requestCounter = 0;
+  private readonly pendingRequests = new Map<number, IPendingRequest>();
+  private readonly serverRequests = new Map<TCodexAppServerRequestId, AbortController>();
+  private readonly maxMessageBytes: number;
+  private inputBuffer = Buffer.alloc(0);
+  private readonly maxBufferedBytes = 4 * 1024 * 1024;
+
+  constructor(private readonly options: ICodexAppServerClientOptions) {
+    this.maxMessageBytes = options.maxMessageBytes ?? 4 * 1024 * 1024;
+    if (!Number.isSafeInteger(this.maxMessageBytes)
+      || this.maxMessageBytes < 1024 || this.maxMessageBytes > 64 * 1024 * 1024) {
+      throw new Error('Codex maxMessageBytes must be between 1 KiB and 64 MiB');
+    }
+    if (options.transport.type === 'websocket') {
+      const url = new URL(options.transport.url);
+      if (!['ws:', 'wss:'].includes(url.protocol) || url.username || url.password || url.hash) {
+        throw new Error('Codex app-server requires an explicit ws/wss URL without credentials or fragment');
+      }
+    }
+  }
+
+  public async connect(): Promise<void> {
+    if (this.started || this.state === 'closed') throw new Error('Codex client has already been started');
+    this.started = true;
+    try {
+      const transport = this.options.transport;
+      if (transport.type === 'websocket') {
+        const socket = new plugins.WsWebSocket(transport.url, {
+          perMessageDeflate: false,
+          followRedirects: false,
+          maxPayload: this.maxMessageBytes,
+          headers: transport.token ? { authorization: `Bearer ${transport.token}` } : {},
+        });
+        this.socket = socket;
+        socket.on('message', (data) => this.receive(data.toString()));
+        socket.on('error', this.handleError);
+        socket.on('close', this.handleEnd);
+        await new Promise<void>((resolve, reject) => {
+          const cleanup = () => {
+            clearTimeout(timer);
+            socket.off('open', opened);
+            socket.off('error', failed);
+            socket.off('close', closed);
+          };
+          const opened = () => { cleanup(); resolve(); };
+          const failed = (errorArg: Error) => { cleanup(); reject(errorArg); };
+          const closed = () => failed(new Error('Codex server WebSocket closed during handshake'));
+          const timer = setTimeout(() => failed(new Error('Codex server WebSocket handshake timed out')), 5000);
+          socket.once('open', opened);
+          socket.once('error', failed);
+          socket.once('close', closed);
+        });
+      } else {
+        if (transport.readable.destroyed || transport.writable.destroyed || transport.writable.writableEnded) {
+          throw new Error('Codex app-server streams are closed');
+        }
+        transport.readable.on('data', this.handleData);
+        transport.readable.on('error', this.handleError);
+        transport.readable.on('end', this.handleEnd);
+        transport.readable.on('close', this.handleEnd);
+        transport.writable.on('error', this.handleError);
+        transport.writable.on('close', this.handleEnd);
+      }
+      const initialized = await this.sendRequest('initialize', {
+        clientInfo: this.options.clientInfo,
+        capabilities: { experimentalApi: this.options.experimentalApi ?? false, requestAttestation: false },
+      }, 5000, undefined, true);
+      if (!helpers.isRecord(initialized) || typeof initialized.userAgent !== 'string') {
+        throw new Error('Codex server returned an invalid initialize response');
+      }
+      this.serverVersion = initialized.userAgent.match(/\/(\d+\.\d+\.\d+[^\s]*)/)?.[1];
+      this.sendFrame({ method: 'initialized' });
+      this.assertOpen();
+      this.state = 'connected';
+    } catch (error) {
+      this.close(helpers.errorMessage(error));
+      throw error;
+    }
+  }
+
+  public request(
+    methodArg: string,
+    paramsArg: unknown,
+    timeoutMsArg = 30000,
+    signalArg?: AbortSignal,
+  ): Promise<unknown> {
+    return this.sendRequest(methodArg, paramsArg, timeoutMsArg, signalArg);
+  }
+
+  private sendRequest(
+    methodArg: string,
+    paramsArg: unknown,
+    timeoutMsArg: number,
+    signalArg?: AbortSignal,
+    allowInitializingArg = false,
+  ): Promise<unknown> {
+    if ((!allowInitializingArg && this.state !== 'connected') || this.state === 'closed') {
+      return Promise.reject(new CodexAppServerRequestError('Codex client is not connected', false));
+    }
+    if (this.pendingRequests.size >= 256) {
+      return Promise.reject(new CodexAppServerRequestError('Codex connection has too many active requests', false));
+    }
+    if (!Number.isFinite(timeoutMsArg) || timeoutMsArg <= 0 || timeoutMsArg > 2_147_483_647) {
+      return Promise.reject(new CodexAppServerRequestError('Codex request timeout is invalid', false));
+    }
+    if (signalArg?.aborted) return Promise.reject(this.cancellationError(signalArg, false));
+    return new Promise((resolve, reject) => {
+      const id = ++this.requestCounter;
+      const timer = setTimeout(() => this.rejectPending(id,
+        new CodexAppServerRequestError(`Codex request timed out: ${methodArg}`, true)), timeoutMsArg);
+      const pending: IPendingRequest = { resolve, reject, timer, signal: signalArg };
+      if (signalArg) {
+        pending.abortHandler = () => this.rejectPending(id, this.cancellationError(signalArg, true));
+        signalArg.addEventListener('abort', pending.abortHandler, { once: true });
+      }
+      this.pendingRequests.set(id, pending);
+      try {
+        this.sendFrame({ id, method: methodArg, params: paramsArg });
+      } catch (error) {
+        this.rejectPending(id, new CodexAppServerRequestError(helpers.errorMessage(error), false, undefined, { cause: error }));
+      }
+    });
+  }
+
+  public respond(idArg: TCodexAppServerRequestId, resultArg: unknown): boolean {
+    if (!this.finishServerRequest(idArg) || this.state === 'closed') return false;
+    this.sendFrame({ id: idArg, result: resultArg });
+    return true;
+  }
+
+  public rejectRequest(idArg: TCodexAppServerRequestId, codeArg: number, messageArg: string): boolean {
+    if (!this.finishServerRequest(idArg) || this.state === 'closed') return false;
+    this.sendFrame({ id: idArg, error: { code: codeArg, message: messageArg } });
+    return true;
+  }
+
+  public close(reasonArg = 'Codex server connection closed'): void {
+    if (this.state === 'closed') return;
+    this.state = 'closed';
+    const error = new CodexAppServerRequestError(reasonArg, true);
+    for (const id of this.pendingRequests.keys()) this.rejectPending(id, error);
+    for (const id of this.serverRequests.keys()) this.finishServerRequest(id);
+    this.inputBuffer = Buffer.alloc(0);
+    const transport = this.options.transport;
+    if (transport.type === 'websocket') {
+      if (this.socket && this.socket.readyState !== plugins.WsWebSocket.CLOSED) this.socket.terminate();
+    } else {
+      transport.readable.off('data', this.handleData);
+      transport.readable.off('end', this.handleEnd);
+      transport.readable.off('close', this.handleEnd);
+      transport.writable.off('close', this.handleEnd);
+      // End only these caller-supplied streams; the caller owns the subprocess.
+      transport.writable.end();
+      transport.readable.destroy();
+    }
+    this.options.onClose?.(error);
+  }
+
+  private readonly handleError = (errorArg: Error): void => { this.close(errorArg.message); };
+  private readonly handleEnd = (): void => { this.close('Codex server connection closed'); };
+  private readonly handleData = (dataArg: Buffer | string): void => {
+    const data = Buffer.isBuffer(dataArg) ? dataArg : Buffer.from(dataArg);
+    let offset = 0;
+    while (offset < data.length && this.state !== 'closed') {
+      const newline = data.indexOf(10, offset);
+      const end = newline < 0 ? data.length : newline;
+      if (this.inputBuffer.length + end - offset > this.maxMessageBytes) {
+        this.close('Codex app-server frame exceeded the response limit');
+        return;
+      }
+      this.inputBuffer = Buffer.concat([this.inputBuffer, data.subarray(offset, end)]);
+      if (newline < 0) break;
+      const raw = this.inputBuffer.toString('utf8');
+      this.inputBuffer = Buffer.alloc(0);
+      if (raw.trim()) this.receive(raw);
+      offset = newline + 1;
+    }
+  };
+
+  private sendFrame(frameArg: Record<string, unknown>): void {
+    const payload = JSON.stringify(frameArg);
+    const payloadBytes = Buffer.byteLength(payload, 'utf8');
+    const transport = this.options.transport;
+    const buffered = transport.type === 'websocket'
+      ? this.socket?.bufferedAmount ?? 0 : transport.writable.writableLength;
+    if (this.state === 'closed') throw new Error('Codex server connection is closed');
+    if (buffered + payloadBytes + 1 > this.maxBufferedBytes) {
+      const error = new Error('Codex send buffer exceeded the 4 MiB limit');
+      this.close(error.message);
+      throw error;
+    }
+    if (transport.type === 'websocket') {
+      if (!this.socket || this.socket.readyState !== plugins.WsWebSocket.OPEN) {
+        throw new Error('Codex server WebSocket is not open');
+      }
+      this.socket.send(payload, (error) => { if (error) this.handleError(error); });
+    } else {
+      if (transport.writable.destroyed || transport.writable.writableEnded) throw new Error('Codex server input is closed');
+      transport.writable.write(`${payload}\n`, (error) => { if (error) this.handleError(error); });
+    }
+  }
+
+  private receive(rawArg: string): void {
+    if (this.state === 'closed') return;
+    try {
+      const message: unknown = JSON.parse(rawArg);
+      if (!helpers.isRecord(message)) throw new Error('Codex server returned a malformed frame');
+      if (typeof message.method === 'string') {
+        const params = message.params ?? {};
+        if (!helpers.isRecord(params)) throw new Error(`Codex returned malformed ${message.method} params`);
+        if (message.id !== undefined) {
+          if ((typeof message.id !== 'string' && typeof message.id !== 'number')
+            || this.serverRequests.has(message.id) || this.serverRequests.size >= 256) {
+            throw new Error('Codex server request identity or capacity is invalid');
+          }
+          const controller = new AbortController();
+          this.serverRequests.set(message.id, controller);
+          if (this.options.onServerRequest) this.options.onServerRequest({ id: message.id, method: message.method, params, signal: controller.signal });
+          else this.rejectRequest(message.id, -32601, `Client does not implement ${message.method}`);
+        } else {
+          if (message.method === 'serverRequest/resolved'
+            && (typeof params.requestId === 'number' || typeof params.requestId === 'string')) {
+            this.finishServerRequest(params.requestId);
+          }
+          this.options.onNotification?.({ method: message.method, params });
+        }
+        return;
+      }
+      if (typeof message.id !== 'number') return;
+      const pending = this.takePending(message.id);
+      if (!pending) return;
+      if (message.error !== undefined) {
+        const code = helpers.isRecord(message.error) && typeof message.error.code === 'number' ? message.error.code : undefined;
+        pending.reject(new CodexAppServerRequestError(
+          `Codex server rejected request: ${JSON.stringify(message.error).slice(0, 4000)}`, true, code));
+      } else pending.resolve(message.result);
+    } catch (error) {
+      this.close(helpers.errorMessage(error));
+    }
+  }
+
+  private takePending(idArg: number): IPendingRequest | undefined {
+    const pending = this.pendingRequests.get(idArg);
+    if (!pending) return undefined;
+    this.pendingRequests.delete(idArg);
+    clearTimeout(pending.timer);
+    if (pending.abortHandler) pending.signal?.removeEventListener('abort', pending.abortHandler);
+    return pending;
+  }
+
+  private rejectPending(idArg: number, errorArg: Error): void {
+    this.takePending(idArg)?.reject(errorArg);
+  }
+
+  private finishServerRequest(idArg: TCodexAppServerRequestId): boolean {
+    const controller = this.serverRequests.get(idArg);
+    if (!controller) return false;
+    this.serverRequests.delete(idArg);
+    controller.abort();
+    return true;
+  }
+
+  private assertOpen(): void {
+    if (this.state === 'closed') throw new Error('Codex server connection is closed');
+  }
+
+  private cancellationError(signalArg: AbortSignal, dispatchedArg: boolean): CodexAppServerRequestError {
+    return new CodexAppServerRequestError(
+      signalArg.reason instanceof Error ? signalArg.reason.message : 'operation cancelled',
+      dispatchedArg, undefined, { cause: signalArg.reason },
+    );
+  }
+}