work-ally 0.2.0-alpha.1

package/bridge/src/runtime-client-turn-read.ts

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { logInfo } from './logger.ts';
+import { normalizeThreadStatus } from './runtime-client-protocol.ts';
+import type { RuntimeThreadStatus, RuntimeTurnResult } from './types.ts';
+
+interface TurnReadDeps {
+  request(method: string, params: unknown): Promise<any>;
+  cacheThreadStatus(threadId: string, status: RuntimeThreadStatus | null | undefined): RuntimeThreadStatus | null;
+  buildReplyFromThreadItems(items: Array<any>): string;
+}
+
+interface TerminalReplyDeps {
+  readPersistedFinalReply(turnId: string): string | null;
+}
+
+function collectRolloutFiles(root: string): string[] {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const files: string[] = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+      if (entry.isFile() && entry.name.startsWith('rollout-') && entry.name.endsWith('.jsonl')) {
+        files.push(fullPath);
+      }
+    }
+  }
+  return files.sort((left, right) => fs.statSync(right).mtimeMs - fs.statSync(left).mtimeMs);
+}
+
+export function readPersistedFinalReplyFromCodexHome(codexHome: string | null, turnId: string): string | null {
+  if (!codexHome) {
+    return null;
+  }
+  const sessionsDir = path.join(codexHome, 'sessions');
+  const files = collectRolloutFiles(sessionsDir);
+  for (const file of files) {
+    let content = '';
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    if (!content.includes(turnId) || !content.includes('task_complete')) {
+      continue;
+    }
+    const lines = content.split(/\r?\n/);
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+      const line = lines[index];
+      if (!line || !line.includes(turnId) || !line.includes('task_complete')) {
+        continue;
+      }
+      try {
+        const record = JSON.parse(line);
+        const payload = record?.payload;
+        if (payload?.type !== 'task_complete' || payload?.turn_id !== turnId) {
+          continue;
+        }
+        const text = typeof payload.last_agent_message === 'string' ? payload.last_agent_message.trim() : '';
+        if (text) {
+          return text;
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+export async function enrichTerminalReply(
+  deps: TerminalReplyDeps,
+  result: RuntimeTurnResult,
+): Promise<RuntimeTurnResult> {
+  if (result.status !== 'completed' || String(result.reply || '').trim()) {
+    return result;
+  }
+  const persisted = deps.readPersistedFinalReply(result.turnId);
+  if (!persisted) {
+    return result;
+  }
+  logInfo('runtime', 'turn_reply_restored_from_task_complete', {
+    threadId: result.threadId,
+    turnId: result.turnId,
+    replyLength: persisted.length,
+  });
+  return {
+    ...result,
+    reply: persisted,
+  };
+}
+
+export function normalizeTurnError(error: unknown): string | null {
+  if (typeof error === 'string') {
+    return error;
+  }
+  if (error && typeof error === 'object' && typeof (error as { message?: unknown }).message === 'string') {
+    return String((error as { message?: string }).message);
+  }
+  return null;
+}
+
+export function buildTurnResultFromObject(
+  buildReplyFromThreadItems: (items: Array<any>) => string,
+  turn: any,
+  fallbackThreadId?: string | null,
+  fallbackTurnId?: string | null,
+): RuntimeTurnResult | null {
+  const turnId = typeof turn?.id === 'string' ? turn.id : (fallbackTurnId || null);
+  if (!turnId) {
+    return null;
+  }
+  return {
+    threadId: typeof turn?.threadId === 'string' ? turn.threadId : (fallbackThreadId || ''),
+    turnId,
+    status: typeof turn?.status === 'string' ? turn.status : 'completed',
+    reply: buildReplyFromThreadItems(Array.isArray(turn?.items) ? turn.items : []),
+    error: normalizeTurnError(turn?.error),
+  };
+}
+
+export function mergeTerminalTurnResult(
+  preferred: RuntimeTurnResult | null,
+  observed: RuntimeTurnResult,
+): RuntimeTurnResult {
+  if (!preferred) {
+    return observed;
+  }
+  return {
+    threadId: preferred.threadId || observed.threadId,
+    turnId: preferred.turnId || observed.turnId,
+    status: preferred.status || observed.status,
+    reply: preferred.reply || observed.reply,
+    error: preferred.error || observed.error || null,
+  };
+}
+
+export async function readTurnSnapshot(
+  deps: Pick<TurnReadDeps, 'request' | 'cacheThreadStatus'>,
+  threadId: string,
+  turnId: string,
+): Promise<{ threadId: string; threadStatus: RuntimeThreadStatus | null; turn: any | null }> {
+  const result = await deps.request('thread/read', { threadId, includeTurns: true });
+  const resolvedThreadId = result?.thread?.id || threadId;
+  const status = deps.cacheThreadStatus(resolvedThreadId, normalizeThreadStatus(result?.thread?.status));
+  if (resolvedThreadId !== threadId && status) {
+    deps.cacheThreadStatus(threadId, status);
+  }
+  const turns = Array.isArray(result?.thread?.turns) ? result.thread.turns : [];
+  const turn = turns.find((item: any) => item?.id === turnId) || null;
+  return {
+    threadId: resolvedThreadId,
+    threadStatus: status,
+    turn,
+  };
+}
+
+export async function readTurnResult(
+  deps: TurnReadDeps & TerminalReplyDeps,
+  threadId: string,
+  turnId: string,
+): Promise<RuntimeTurnResult | null> {
+  const snapshot = await readTurnSnapshot(deps, threadId, turnId);
+  if (!snapshot.turn || typeof snapshot.turn.status !== 'string') {
+    return null;
+  }
+  return enrichTerminalReply(deps, {
+    threadId: snapshot.threadId,
+    turnId,
+    status: snapshot.turn.status,
+    reply: deps.buildReplyFromThreadItems(Array.isArray(snapshot.turn.items) ? snapshot.turn.items : []),
+    error: typeof snapshot.turn.error?.message === 'string' ? snapshot.turn.error.message : null,
+  });
+}

package/bridge/src/runtime-client-turn-state.ts

@@ -0,0 +1,105 @@
+import type { RuntimeTurnState } from './runtime-client-agent-messages.ts';
+import { logWarn } from './logger.ts';
+import type { RuntimeProgressMeta, RuntimeThreadStatus, RuntimeTurnResult } from './types.ts';
+
+function finalizeTurnState(
+  turnStates: Map<string, RuntimeTurnState>,
+  turnId: string,
+): RuntimeTurnState | null {
+  const turn = turnStates.get(turnId) || null;
+  if (!turn) {
+    return null;
+  }
+  turnStates.delete(turnId);
+  return turn;
+}
+
+export async function safeEmitRuntimeTurnProgress(
+  turnStates: Map<string, RuntimeTurnState>,
+  turnId: string,
+  text: string,
+  meta?: RuntimeProgressMeta,
+): Promise<void> {
+  const turn = turnStates.get(turnId);
+  if (!turn?.onProgress) {
+    return;
+  }
+  try {
+    await turn.onProgress(text, meta);
+  } catch (error) {
+    logWarn('runtime', 'progress_handler_failed', {
+      turnId,
+      progressKind: meta?.kind || null,
+      progressPhase: meta?.phase || null,
+      itemId: meta?.itemId || null,
+      error: error instanceof Error ? (error.stack || error.message) : String(error),
+    });
+  }
+}
+
+export function resolveRuntimeTurnResult(
+  turnStates: Map<string, RuntimeTurnState>,
+  cacheThreadStatus: (threadId: string, status: RuntimeThreadStatus | null | undefined) => RuntimeThreadStatus | null,
+  turnId: string,
+  result: RuntimeTurnResult,
+): boolean {
+  const turn = finalizeTurnState(turnStates, turnId);
+  if (!turn) {
+    return false;
+  }
+  cacheThreadStatus(result.threadId || turn.threadId, { type: 'idle', activeFlags: [] });
+  turn.resolve({
+    threadId: result.threadId || turn.threadId,
+    turnId: result.turnId || turnId,
+    status: result.status,
+    reply: result.reply,
+    error: result.error || null,
+  });
+  return true;
+}
+
+export function rejectRuntimeTurnResult(
+  turnStates: Map<string, RuntimeTurnState>,
+  turnId: string,
+  error: Error,
+): boolean {
+  const turn = finalizeTurnState(turnStates, turnId);
+  if (!turn) {
+    return false;
+  }
+  turn.reject(error);
+  return true;
+}
+
+export function rejectAllRuntimeTurns(
+  turnStates: Map<string, RuntimeTurnState>,
+  error: Error,
+): void {
+  for (const [turnId, turn] of turnStates.entries()) {
+    turn.reject(error);
+    turnStates.delete(turnId);
+  }
+}
+
+export function emitContextCompactionTurnProgress(
+  turnStates: Map<string, RuntimeTurnState>,
+  emitProgress: (turnId: string, text: string, meta?: RuntimeProgressMeta) => Promise<void>,
+  turnId: string,
+  itemId: string,
+): void {
+  const turn = turnStates.get(turnId);
+  if (!turn || !turn.onProgress) {
+    return;
+  }
+  const dedupeKey = `${turn.threadId}:${turnId}:${itemId}`;
+  if (turn.emittedContextCompactionKeys.has(dedupeKey)) {
+    return;
+  }
+  turn.emittedContextCompactionKeys.add(dedupeKey);
+  void emitProgress(turnId, 'Codex 正在压缩当前会话上下文。', {
+    kind: 'context_compaction',
+    phase: null,
+    turnId,
+    itemId,
+  });
+}

package/bridge/src/runtime-client.ts

@@ -0,0 +1,344 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import type { RuntimeTurnState } from './runtime-client-agent-messages.ts';
+import { handleRuntimeRpcMessage, type PendingRuntimeRequest } from './runtime-client-message-dispatch.ts';
+import { createRunTurnEventBridge, startRuntimeTurn } from './runtime-client-run-turn.ts';
+import { pollTurnFinalState } from './runtime-client-turn-poll.ts';
+import { rejectAllPendingRequests, sendRuntimeRequest } from './runtime-client-request-ops.ts';
+import { emitContextCompactionTurnProgress, rejectAllRuntimeTurns, rejectRuntimeTurnResult, resolveRuntimeTurnResult, safeEmitRuntimeTurnProgress } from './runtime-client-turn-state.ts';
+import { RuntimeClientTransport } from './runtime-client-transport.ts';
+import { cacheThreadStatusFor, cachedThreadStatusFor, interruptTurnRequest, readPersistedFinalReply, readThreadRequest, readThreadStatusRequest, recoverTurnResultRequest, resolveApprovalRequest, resolveElicitationRequest, resolveUserInputRequest, resumeThreadRequest, startThreadRequest, steerTurnRequest } from './runtime-client-thread-ops.ts';
+import { logInfo } from './logger.ts';
+import type {
+  ApprovalDecision,
+  ConnectionLifecycleEvent,
+  RuntimeProgressMeta,
+  RuntimeThreadStatus,
+  RuntimeTurnResult,
+  ServerRequestResolvedEvent,
+} from './types.ts';
+import {
+  normalizeRuntimeError,
+  runtimeErrorMessage,
+  type ApprovalPolicy,
+  type JsonRpcMessage,
+  type RunTurnOptions,
+  type ThreadOptions,
+} from './runtime-client-protocol.ts';
+
+const CONNECT_TIMEOUT_MS = Number(process.env.WORK_ALLY_CODEX_CONNECT_TIMEOUT_MS || '5000');
+const DISCONNECT_TIMEOUT_MS = 1000;
+const RECONNECT_BASE_DELAY_MS = Number(process.env.WORK_ALLY_RUNTIME_RECONNECT_BASE_MS || '2000');
+const RECONNECT_MAX_DELAY_MS = Number(process.env.WORK_ALLY_RUNTIME_RECONNECT_MAX_MS || '30000');
+const RECOVERABLE_RUNTIME_ERROR_RE = /runtime (?:stdio|transport) is not connected|runtime child process exited|runtime connect timed out|not materialized yet|includeTurns is unavailable before first user message/i;
+const TURN_IDLE_RECONCILE_DELAY_MS = Number(process.env.WORK_ALLY_TURN_IDLE_RECONCILE_DELAY_MS || '500');
+const TURN_FINAL_POLL_MS = Number(process.env.WORK_ALLY_TURN_FINAL_POLL_MS || '250');
+const TURN_RESULT_RECOVERY_TIMEOUT_MS = Number(process.env.WORK_ALLY_TURN_RESULT_RECOVERY_TIMEOUT_MS || '60000');
+
+interface CodexRuntimeClientOptions {
+  codexHome?: string | null;
+  codexBin?: string | null;
+  spawnImpl?: typeof spawn;
+}
+
+export class CodexRuntimeClient {
+  private readonly codexHome: string | null;
+  private readonly codexBin: string;
+  private readonly spawnImpl: typeof spawn;
+  private readonly transport: RuntimeClientTransport;
+  private nextId = 1;
+  private readonly pending = new Map<string | number, PendingRuntimeRequest>();
+  private readonly turnStates = new Map<string, RuntimeTurnState>();
+  private readonly emitter = new EventEmitter();
+  private readonly threadStatusCache = new Map<string, RuntimeThreadStatus>();
+
+  constructor(options: CodexRuntimeClientOptions = {}) {
+    this.codexHome = options.codexHome ? path.resolve(options.codexHome) : null;
+    this.codexBin = (options.codexBin || process.env.WORK_ALLY_CODEX_BIN || 'codex').trim() || 'codex';
+    this.spawnImpl = options.spawnImpl || spawn;
+    this.transport = new RuntimeClientTransport({
+      codexHome: this.codexHome,
+      codexBin: this.codexBin,
+      spawnImpl: this.spawnImpl,
+      connectTimeoutMs: CONNECT_TIMEOUT_MS,
+      disconnectTimeoutMs: DISCONNECT_TIMEOUT_MS,
+      reconnectBaseDelayMs: RECONNECT_BASE_DELAY_MS,
+      reconnectMaxDelayMs: RECONNECT_MAX_DELAY_MS,
+      initialize: () => this.initialize(),
+      onMessage: (line) => this.onMessage(line),
+      rejectAllPending: (error) => this.rejectAllPending(error),
+      rejectAllTurns: (error) => this.rejectAllTurns(error),
+      activeTurnCount: () => this.turnStates.size,
+      emitConnectionEvent: (event) => this.emitConnectionEvent(event),
+    });
+  }
+
+  private emitConnectionEvent(event: ConnectionLifecycleEvent): void {
+    this.emitter.emit('connectionLifecycle', event);
+  }
+
+  onConnectionEvent(listener: (event: ConnectionLifecycleEvent) => void): void {
+    this.emitter.on('connectionLifecycle', listener);
+  }
+
+  offConnectionEvent(listener: (event: ConnectionLifecycleEvent) => void): void {
+    this.emitter.off('connectionLifecycle', listener);
+  }
+
+  onServerRequestResolved(listener: (event: ServerRequestResolvedEvent) => void): void {
+    this.emitter.on('serverRequestResolved', listener);
+  }
+
+  offServerRequestResolved(listener: (event: ServerRequestResolvedEvent) => void): void {
+    this.emitter.off('serverRequestResolved', listener);
+  }
+
+  private scheduleReconnect(reason: string): void {
+    this.transport.scheduleReconnect(reason, () => this.connect());
+  }
+
+
+  private handleTransportClosed(reason: string): void {
+    this.transport.handleTransportClosed(reason, (message) => this.scheduleReconnect(message));
+  }
+
+  private isRecoverableRuntimeError(error: unknown): boolean {
+    return RECOVERABLE_RUNTIME_ERROR_RE.test(runtimeErrorMessage(error));
+  }
+
+  private sendRaw(payload: unknown): void {
+    this.transport.sendRaw(payload);
+  }
+
+  private rejectAllPending(error: Error): void {
+    rejectAllPendingRequests(this.pending, error);
+  }
+
+  private resolveTurnResult(turnId: string, result: RuntimeTurnResult): boolean {
+    return resolveRuntimeTurnResult(this.turnStates, (threadId, status) => this.cacheThreadStatus(threadId, status), turnId, result);
+  }
+
+  private rejectTurnResult(turnId: string, error: Error): boolean {
+    return rejectRuntimeTurnResult(this.turnStates, turnId, error);
+  }
+
+  private startTurnFinalPoll(threadId: string, turnId: string): void {
+    const pollMs = Math.max(50, TURN_FINAL_POLL_MS);
+    void pollTurnFinalState({
+      turnStates: this.turnStates,
+      request: (method, params) => this.request(method, params),
+      cacheThreadStatus: (currentThreadId, status) => this.cacheThreadStatus(currentThreadId, status),
+      readPersistedFinalReply: (currentTurnId) => this.readPersistedFinalReply(currentTurnId),
+      resolveTurnResult: (currentTurnId, result) => this.resolveTurnResult(currentTurnId, result),
+      rejectTurnResult: (currentTurnId, error) => this.rejectTurnResult(currentTurnId, error),
+      isRecoverableRuntimeError: (error) => this.isRecoverableRuntimeError(error),
+      safeEmitTurnProgress: (currentTurnId, text, meta) => this.safeEmitTurnProgress(currentTurnId, text, meta),
+    }, threadId, turnId, {
+      pollMs,
+      transportTimeoutMs: Math.max(pollMs, TURN_RESULT_RECOVERY_TIMEOUT_MS),
+      idleReconcileMs: Math.max(pollMs * 2, TURN_IDLE_RECONCILE_DELAY_MS),
+      idleAwaitingAuthoritativeResultTimeoutMs: Math.max(Math.max(pollMs * 2, TURN_IDLE_RECONCILE_DELAY_MS), TURN_RESULT_RECOVERY_TIMEOUT_MS),
+    });
+  }
+
+  private async safeEmitTurnProgress(turnId: string, text: string, meta?: RuntimeProgressMeta): Promise<void> {
+    return safeEmitRuntimeTurnProgress(this.turnStates, turnId, text, meta);
+  }
+
+  private rejectAllTurns(error: Error): void {
+    rejectAllRuntimeTurns(this.turnStates, error);
+  }
+
+  private async request(method: string, params: unknown): Promise<any> {
+    return sendRuntimeRequest({
+      connect: () => this.connect(),
+      createId: () => `req_${this.nextId++}`,
+      pending: this.pending,
+      sendRaw: (payload) => this.sendRaw(payload),
+    }, method, params);
+  }
+
+  private async initialize(): Promise<void> {
+    await this.request('initialize', {
+      clientInfo: { name: 'work-ally-bridge', version: '0.1.0' },
+      capabilities: { experimentalApi: true },
+    });
+  }
+
+
+  private cacheThreadStatus(threadId: string, status: RuntimeThreadStatus | null | undefined): RuntimeThreadStatus | null {
+    return cacheThreadStatusFor(this.threadStatusCache, threadId, status);
+  }
+
+  private cachedThreadStatus(threadId: string): RuntimeThreadStatus | null {
+    return cachedThreadStatusFor(this.threadStatusCache, threadId);
+  }
+
+  private emitContextCompactionProgress(turnId: string, itemId: string): void {
+    emitContextCompactionTurnProgress(
+      this.turnStates,
+      (currentTurnId, text, meta) => this.safeEmitTurnProgress(currentTurnId, text, meta),
+      turnId,
+      itemId,
+    );
+  }
+
+  readPersistedFinalReply(turnId: string): string | null {
+    return readPersistedFinalReply(this.codexHome, turnId);
+  }
+
+  async connect(): Promise<void> {
+    return this.transport.connect();
+  }
+
+  async disconnect(): Promise<void> {
+    return this.transport.disconnect();
+  }
+
+  private onMessage(data: unknown): void {
+    const text = typeof data === 'string' ? data : Buffer.from(data as ArrayBuffer).toString('utf8');
+    const msg = JSON.parse(text) as JsonRpcMessage;
+    handleRuntimeRpcMessage(msg, {
+      pending: this.pending,
+      turnStates: this.turnStates,
+      cacheThreadStatus: (threadId, status) => this.cacheThreadStatus(threadId, status),
+      emitServerRequestResolved: (event) => this.emitter.emit('serverRequestResolved', event),
+      emitServerRequest: (message) => this.emitter.emit('serverRequest', message),
+      emitContextCompactionProgress: (turnId, itemId) => this.emitContextCompactionProgress(turnId, itemId),
+      resolveTurnResult: (turnId, result) => this.resolveTurnResult(turnId, result),
+    });
+  }
+
+  async healthcheck(): Promise<boolean> {
+    try {
+      await this.connect();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async startThread(cwd: string, options: ThreadOptions = {}): Promise<{ id: string }> {
+    return startThreadRequest({
+      request: (method, params) => this.request(method, params),
+      cacheThreadStatus: (threadId, status) => this.cacheThreadStatus(threadId, status),
+    }, cwd, options);
+  }
+
+  async resumeThread(threadId: string, cwd: string, options: ThreadOptions = {}): Promise<{ id: string }> {
+    return resumeThreadRequest({
+      request: (method, params) => this.request(method, params),
+      cacheThreadStatus: (resolvedThreadId, status) => this.cacheThreadStatus(resolvedThreadId, status),
+      startThread: (nextCwd, nextOptions = {}) => this.startThread(nextCwd, nextOptions),
+    }, threadId, cwd, options);
+  }
+
+  async readThread(threadId: string, includeTurns = false): Promise<{ id: string; status: RuntimeThreadStatus | null }> {
+    const result = await readThreadRequest({
+      request: (method, params) => this.request(method, params),
+      cacheThreadStatus: (resolvedThreadId, status) => this.cacheThreadStatus(resolvedThreadId, status),
+    }, threadId, includeTurns);
+    return { id: result.id, status: result.status };
+  }
+
+  async readThreadWithTurns(threadId: string): Promise<{ id: string; status: RuntimeThreadStatus | null; turns: any[] }> {
+    const result = await readThreadRequest({
+      request: (method, params) => this.request(method, params),
+      cacheThreadStatus: (resolvedThreadId, status) => this.cacheThreadStatus(resolvedThreadId, status),
+    }, threadId, true);
+    return {
+      id: result.id,
+      status: result.status,
+      turns: Array.isArray(result.turns) ? result.turns : [],
+    };
+  }
+
+  async readThreadStatus(threadId: string): Promise<RuntimeThreadStatus | null> {
+    return readThreadStatusRequest({
+      request: (method, params) => this.request(method, params),
+      cacheThreadStatus: (resolvedThreadId, status) => this.cacheThreadStatus(resolvedThreadId, status),
+      cachedThreadStatus: (currentThreadId) => this.cachedThreadStatus(currentThreadId),
+    }, threadId);
+  }
+
+  async interruptTurn(threadId: string, turnId: string): Promise<void> {
+    await interruptTurnRequest((method, params) => this.request(method, params), threadId, turnId);
+  }
+
+  async steerTurn(threadId: string, turnId: string, prompt: string): Promise<void> {
+    await steerTurnRequest({
+      connect: () => this.connect(),
+      request: (method, params) => this.request(method, params),
+      isRecoverableRuntimeError: (error) => this.isRecoverableRuntimeError(error),
+      scheduleReconnect: (reason) => this.scheduleReconnect(reason),
+    }, threadId, turnId, prompt);
+  }
+
+  async recoverTurnResult(
+    threadId: string,
+    turnId: string,
+    options: { timeoutMs?: number; pollMs?: number } = {},
+  ): Promise<RuntimeTurnResult | null> {
+    return recoverTurnResultRequest({
+      request: (method, params) => this.request(method, params),
+      cacheThreadStatus: (resolvedThreadId, status) => this.cacheThreadStatus(resolvedThreadId, status),
+      readPersistedFinalReply: (currentTurnId) => this.readPersistedFinalReply(currentTurnId),
+    }, threadId, turnId, options);
+  }
+
+  async resolveApproval(requestId: string | number, decision: ApprovalDecision): Promise<void> {
+    resolveApprovalRequest((payload) => this.sendRaw(payload), requestId, decision);
+  }
+
+  async resolveUserInput(
+    requestId: string | number,
+    response: { answers: Record<string, { answers: string[] }> },
+  ): Promise<void> {
+    resolveUserInputRequest((payload) => this.sendRaw(payload), requestId, response);
+  }
+
+  async resolveElicitation(
+    requestId: string | number,
+    response: { action: 'accept' | 'decline' | 'cancel'; content: unknown | null },
+  ): Promise<void> {
+    resolveElicitationRequest((payload) => this.sendRaw(payload), requestId, response);
+  }
+
+  async runTurn(options: RunTurnOptions): Promise<RuntimeTurnResult> {
+    await this.connect();
+
+    let activeTurnId: string | null = null;
+
+    const { progressHandler, serverRequestHandler } = createRunTurnEventBridge({
+      safeEmitTurnProgress: (turnId, progressText, meta) => this.safeEmitTurnProgress(turnId, progressText, meta),
+      resolveApproval: (requestId, decision) => this.resolveApproval(requestId, decision),
+      resolveUserInput: (requestId, response) => this.resolveUserInput(requestId, response),
+      resolveElicitation: (requestId, response) => this.resolveElicitation(requestId, response),
+    }, options, {
+      getActiveTurnId: () => activeTurnId,
+    });
+    this.emitter.on('progress', progressHandler);
+    this.emitter.on('serverRequest', serverRequestHandler);
+    try {
+      const { turnId, turnPromise } = await startRuntimeTurn({
+        request: (method, params) => this.request(method, params),
+        cacheThreadStatus: (threadId, status) => this.cacheThreadStatus(threadId, status),
+        turnStates: this.turnStates,
+        startTurnFinalPoll: (threadId, startedTurnId) => this.startTurnFinalPoll(threadId, startedTurnId),
+        rejectTurnResult: (turnId, error) => this.rejectTurnResult(turnId, error),
+      }, options);
+      activeTurnId = turnId;
+      return await turnPromise;
+    } catch (error) {
+      if (this.isRecoverableRuntimeError(error)) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.scheduleReconnect(message);
+      }
+      throw error;
+    } finally {
+      this.emitter.off('progress', progressHandler);
+      this.emitter.off('serverRequest', serverRequestHandler);
+    }
+  }
+}