@xmanrui/dsh-im 0.7.0 → 0.7.2

package/src/channels/shared/harness-client.mjs

@@ -0,0 +1,858 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+
+import { adoptRegisteredWorkspaceSession } from './harness-session-binding.mjs';
+
+// Every channel plugin runs in the same Host process. Sharing ownership by
+// Harness origin prevents two channel-specific clients bound to one Session
+// from claiming or cancelling each other's interactions.
+const interactionRegistries = new Map();
+
+function interactionRegistry(origin) {
+  let registry = interactionRegistries.get(origin);
+  if (!registry) {
+    registry = { ownerships: new Map(), claims: new Map(), nextOrder: 0 };
+    interactionRegistries.set(origin, registry);
+  }
+  return registry;
+}
+
+function workspacePaths(value) {
+  if (!Array.isArray(value?.items)) return [];
+  return value.items.flatMap((item) => (
+    typeof item?.path === 'string' && isAbsolute(item.path) ? [item.path] : []
+  ));
+}
+
+function workspaceFromList(workspacePath, workspaceList) {
+  if (!Array.isArray(workspaceList?.items)
+    || !Array.isArray(workspaceList?.archivedSessionIds)) {
+    throw new Error('Harness returned an invalid response for workspace.list');
+  }
+
+  const workspace = workspaceList.items.find((item) => item?.path === workspacePath);
+  if (!workspace) return null;
+  if (!Array.isArray(workspace.sessionIds)
+    || workspace.sessionIds.some((sessionId) => typeof sessionId !== 'string')) {
+    throw new Error('Harness returned invalid session IDs for workspace.list');
+  }
+  return workspace;
+}
+
+function workspaceSessions(workspace, archivedSessionIds, sessionList) {
+  if (!Array.isArray(sessionList?.items)) {
+    throw new Error('Harness returned an invalid response for session.list');
+  }
+
+  const archived = new Set(archivedSessionIds);
+  const summaries = new Map(sessionList.items.flatMap((item) => (
+    typeof item?.sessionId === 'string' ? [[item.sessionId, item]] : []
+  )));
+  return {
+    workspace: workspace.path,
+    sessions: workspace.sessionIds.map((sessionId) => {
+      const summary = summaries.get(sessionId);
+      const title = summary?.projections?.values?.title;
+      return {
+        sessionId,
+        title: typeof title === 'string' ? title : null,
+        archived: archived.has(sessionId),
+        blank: summary?.blank === true,
+        origin: summary?.origin === 'subagent' ? 'subagent' : null,
+        summaryAvailable: summary !== undefined,
+      };
+    }),
+  };
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+function assistantMessageText(event) {
+  return (event?.data?.message?.content ?? [])
+    .filter((part) => part.type === 'text' && typeof part.text === 'string')
+    .map((part) => part.text)
+    .join('\n')
+    .trim();
+}
+
+function consumeInteractionOwnership(ownership, entries) {
+  const ordered = [...entries]
+    .map((entry) => entry?.event ?? entry)
+    .filter(Boolean)
+    .sort((left, right) => (left.seq ?? -1) - (right.seq ?? -1));
+
+  for (const event of ordered) {
+    const seq = event.seq ?? -1;
+    if (seq <= ownership.lastSeq) continue;
+    ownership.lastSeq = seq;
+
+    if (event.type === 'turn/start') {
+      const turn = event.data?.turn ?? null;
+      if (ownership.active && turn !== ownership.turn) ownership.active = false;
+      if (ownership.turn !== null && turn !== ownership.turn) ownership.completed = true;
+      ownership.openTurn = turn;
+      continue;
+    }
+    if (event.type === 'user/message' && event.data?.source?.rpcId === ownership.promptRpcId) {
+      ownership.active = true;
+      ownership.started = true;
+      ownership.completed = false;
+      ownership.turn = event.data?.turn ?? ownership.openTurn;
+      continue;
+    }
+    if (event.type === 'turn/end' && event.data?.turn === ownership.turn) {
+      ownership.active = false;
+      ownership.completed = true;
+      continue;
+    }
+    let toolCall = null;
+    if (event.type === 'tool/call'
+      && ownership.active
+      && event.data?.turn === ownership.turn
+      && typeof event.data?.callId === 'string'
+      && event.data.callId) {
+      toolCall = {
+        callId: event.data.callId,
+        name: event.data?.name,
+        arguments: event.data?.arguments,
+      };
+    } else if (event.type === 'tool/code-dispatch-start'
+      && ownership.active
+      && typeof event.data?.subCallId === 'string'
+      && event.data.subCallId) {
+      let argumentsText;
+      try {
+        argumentsText = JSON.stringify(event.data?.arguments);
+      } catch {
+        argumentsText = undefined;
+      }
+      toolCall = {
+        callId: event.data.subCallId,
+        name: event.data?.name,
+        arguments: argumentsText,
+      };
+    }
+    if (toolCall) ownership.toolCalls.set(toolCall.callId, Object.freeze(toolCall));
+  }
+}
+
+export class HarnessReplyTracker {
+  #promptRpcId;
+  #lastSeq;
+  #openTurn = null;
+  #targetTurn = null;
+  #stepText = new Map();
+  #latestText = '';
+  #finished = false;
+  #reason = null;
+
+  constructor({ promptRpcId, afterSeq = -1 }) {
+    this.#promptRpcId = promptRpcId;
+    this.#lastSeq = afterSeq;
+  }
+
+  get finished() {
+    return this.#finished;
+  }
+
+  get answer() {
+    return this.#latestText.trim();
+  }
+
+  get reason() {
+    return this.#reason;
+  }
+
+  get tracking() {
+    return this.#targetTurn !== null && !this.#finished;
+  }
+
+  get turn() {
+    return this.#targetTurn;
+  }
+
+  consume(entries) {
+    let update = null;
+    const ordered = [...entries]
+      .map((entry) => entry?.event ?? entry)
+      .filter(Boolean)
+      .sort((left, right) => (left.seq ?? -1) - (right.seq ?? -1));
+
+    for (const event of ordered) {
+      const seq = event.seq ?? -1;
+      if (seq <= this.#lastSeq) continue;
+      this.#lastSeq = seq;
+
+      if (event.type === 'turn/start') this.#openTurn = event.data?.turn ?? null;
+
+      if (event.type === 'user/message' && event.data?.source?.rpcId === this.#promptRpcId) {
+        this.#targetTurn = this.#openTurn;
+        continue;
+      }
+      if (this.#targetTurn === null) continue;
+
+      if (event.type === 'turn/end') {
+        if (event.data?.turn !== this.#targetTurn) continue;
+        this.#finished = true;
+        this.#reason = event.data?.reason ?? null;
+        this.#openTurn = null;
+        continue;
+      }
+      if (event.data?.turn !== this.#targetTurn) continue;
+
+      if (event.type === 'assistant/chunk' && event.data?.chunk?.type === 'text-delta') {
+        const step = event.data?.step ?? 0;
+        const index = event.data.chunk.index ?? 0;
+        const key = `${step}:${index}`;
+        this.#stepText.set(key, (this.#stepText.get(key) ?? '') + event.data.chunk.text);
+        const prefix = `${step}:`;
+        const text = [...this.#stepText.entries()]
+          .filter(([partKey]) => partKey.startsWith(prefix))
+          .sort(([left], [right]) => Number(left.split(':')[1]) - Number(right.split(':')[1]))
+          .map(([, part]) => part)
+          .join('\n')
+          .trim();
+        if (text && text !== this.#latestText) {
+          this.#latestText = text;
+          update = { type: 'text', text };
+        }
+        continue;
+      }
+
+      if (event.type === 'assistant/message') {
+        const text = assistantMessageText(event);
+        if (text && text !== this.#latestText) {
+          this.#latestText = text;
+          update = { type: 'text', text };
+        }
+        continue;
+      }
+
+      if (event.type === 'tool/call') {
+        update = { type: 'tool', name: event.data?.name ?? '工具' };
+      } else if (event.type === 'tool/result') {
+        update = { type: 'status', text: '正在整理结果…' };
+      }
+    }
+    return update;
+  }
+}
+
+export class HarnessRpcError extends Error {
+  constructor(method, error) {
+    super(`${method}: ${error?.message ?? 'unknown Harness RPC error'}`);
+    this.name = 'HarnessRpcError';
+    this.method = method;
+    this.code = error?.code ?? 'internal';
+    this.details = error?.details ?? {};
+  }
+}
+
+export class HarnessInteractionError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'HarnessInteractionError';
+    this.code = code;
+  }
+}
+
+export class HarnessClient {
+  #baseUrl;
+  #workspace;
+  #agentPreset;
+  #autostart;
+  #dshBin;
+  #fetch;
+  #createWebSocket;
+  #interactionReconnectDelayMs;
+  #rpcIdPrefix;
+  #logPrefix;
+  #managedProcess = null;
+  #interactionRegistry;
+  #interactionOwnerships;
+  #interactionClaims;
+
+  constructor({
+    baseUrl,
+    workspace,
+    agentPreset = 'standard',
+    autostart = false,
+    dshBin = 'dsh',
+    fetchImpl = fetch,
+    createWebSocket = (url) => new WebSocket(url),
+    interactionReconnectDelayMs = 500,
+    rpcIdPrefix = 'im',
+    logPrefix = 'dsh-im',
+  }) {
+    if (typeof createWebSocket !== 'function') {
+      throw new TypeError('createWebSocket must be a function');
+    }
+    if (!Number.isFinite(interactionReconnectDelayMs) || interactionReconnectDelayMs < 0) {
+      throw new TypeError('interactionReconnectDelayMs must be a non-negative number');
+    }
+    if (typeof rpcIdPrefix !== 'string' || !rpcIdPrefix.trim()) {
+      throw new TypeError('rpcIdPrefix must be a non-empty string');
+    }
+    if (typeof logPrefix !== 'string' || !logPrefix.trim()) {
+      throw new TypeError('logPrefix must be a non-empty string');
+    }
+    this.#baseUrl = new URL(baseUrl);
+    this.#workspace = workspace;
+    this.#agentPreset = agentPreset;
+    this.#autostart = autostart;
+    this.#dshBin = dshBin;
+    this.#fetch = fetchImpl;
+    this.#createWebSocket = createWebSocket;
+    this.#interactionReconnectDelayMs = interactionReconnectDelayMs;
+    this.#rpcIdPrefix = rpcIdPrefix.trim();
+    this.#logPrefix = logPrefix.trim();
+    this.#interactionRegistry = interactionRegistry(this.#baseUrl.origin);
+    this.#interactionOwnerships = this.#interactionRegistry.ownerships;
+    this.#interactionClaims = this.#interactionRegistry.claims;
+  }
+
+  async rpc(method, payload = {}, timeoutMs = 30_000, options = {}) {
+    const rpcId = options.rpcId ?? `${this.#rpcIdPrefix}-${randomUUID()}`;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = options.signal
+      ? AbortSignal.any([options.signal, timeoutSignal])
+      : timeoutSignal;
+    const response = await this.#fetch(new URL(`/api/${method}`, this.#baseUrl), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ type: 'client-request', rpcId, method, payload }),
+      signal,
+    });
+    if (!response.ok) throw new Error(`Harness transport ${method} failed: HTTP ${response.status}`);
+    const body = await response.json();
+    if (body?.type !== 'server-response' || body?.rpcId !== rpcId) {
+      throw new Error(`Harness returned an invalid response for ${method}`);
+    }
+    if (!body.result?.ok) throw new HarnessRpcError(method, body.result?.error);
+    return body.result.value;
+  }
+
+  async health(options = {}) {
+    await this.rpc('host.describe', {}, 5_000, options);
+    return true;
+  }
+
+  async ensureRunning(options = {}) {
+    try {
+      return await this.health(options);
+    } catch (firstError) {
+      if (!this.#autostart) throw firstError;
+    }
+
+    if (!this.#managedProcess || this.#managedProcess.exitCode !== null) {
+      const port = this.#baseUrl.port || (this.#baseUrl.protocol === 'https:' ? '443' : '80');
+      this.#managedProcess = spawn(this.#dshBin, [
+        'web', '--host', this.#baseUrl.hostname, '--port', port,
+      ], {
+        cwd: this.#workspace,
+        env: process.env,
+        stdio: ['ignore', 'inherit', 'inherit'],
+      });
+      this.#managedProcess.on('error', (error) => {
+        console.error(`[${this.#logPrefix}] failed to start Harness:`, error.message);
+      });
+    }
+
+    const deadline = Date.now() + 60_000;
+    let lastError;
+    while (Date.now() < deadline) {
+      await sleep(1_000, options.signal);
+      try {
+        return await this.health(options);
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw new Error(`Harness did not become ready: ${lastError?.message ?? 'timeout'}`);
+  }
+
+  async listWorkspaces(options = {}) {
+    await this.ensureRunning(options);
+    return workspacePaths(await this.rpc('workspace.list', {}, 30_000, options));
+  }
+
+  async listWorkspaceSessions(workspacePath, options = {}) {
+    await this.ensureRunning(options);
+    const workspaceList = await this.rpc('workspace.list', {}, 30_000, options);
+    const workspace = workspaceFromList(workspacePath, workspaceList);
+    if (!workspace) return { workspace: workspacePath, sessions: [] };
+    const sessionList = await this.rpc('session.list', {}, 30_000, options);
+    return workspaceSessions(workspace, workspaceList.archivedSessionIds, sessionList);
+  }
+
+  async adoptWorkspaceSession(value, options = {}) {
+    return adoptRegisteredWorkspaceSession(this, value, options);
+  }
+
+  async workspaceId(options = {}) {
+    const { workspace = this.#workspace, ...rpcOptions } = options;
+    const { items } = await this.rpc('workspace.list', {}, 30_000, rpcOptions);
+    const existing = items.find((item) => item.path === workspace);
+    if (existing) return existing.workspaceId;
+    const created = await this.rpc('workspace.create', { path: workspace }, 30_000, rpcOptions);
+    return created.workspace.workspaceId;
+  }
+
+  async createSession(options = {}) {
+    await this.ensureRunning(options);
+    const workspaceId = await this.workspaceId(options);
+    const created = await this.rpc('session.create', {
+      workspaceId,
+      agentPreset: this.#agentPreset,
+    }, 30_000, options);
+    return created.sessionId;
+  }
+
+  async sessionExists(sessionId, options = {}) {
+    try {
+      await this.rpc('session.history', { sessionId, maxMessages: 1 }, 30_000, options);
+      return true;
+    } catch (error) {
+      if (error instanceof HarnessRpcError && error.code === 'session-not-found') return false;
+      throw error;
+    }
+  }
+
+  async respondInteraction(rpcId, result, options = {}) {
+    if (typeof rpcId !== 'string' || !rpcId) throw new TypeError('rpcId is required');
+    if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+      throw new TypeError('A Harness RPC result is required');
+    }
+    const timeoutSignal = AbortSignal.timeout(options.timeoutMs ?? 30_000);
+    const signal = options.signal
+      ? AbortSignal.any([options.signal, timeoutSignal])
+      : timeoutSignal;
+    const response = await this.#fetch(new URL('/api/respond', this.#baseUrl), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ type: 'client-response', rpcId, result }),
+      signal,
+    });
+    if (!response.ok) {
+      throw new Error(`Harness transport respond failed: HTTP ${response.status}`);
+    }
+    const receipt = await response.json();
+    if (receipt?.accepted === true) return receipt;
+    if (receipt?.accepted !== false
+      || (receipt.reason !== 'bad-response' && receipt.reason !== 'not-pending')) {
+      throw new Error('Harness returned an invalid interaction response receipt');
+    }
+    const reason = receipt.reason;
+    throw new HarnessInteractionError(
+      `interaction-${reason}`,
+      `Harness interaction response was rejected (${reason})`,
+    );
+  }
+
+  async watchInteractions(sessionId, {
+    signal,
+    onInteraction,
+    onResolved,
+    onOpen,
+    ownership,
+  } = {}) {
+    if (typeof sessionId !== 'string' || !sessionId) throw new TypeError('sessionId is required');
+    if (!signal || typeof signal.addEventListener !== 'function') {
+      throw new TypeError('watchInteractions requires an AbortSignal');
+    }
+    if (onInteraction !== undefined && typeof onInteraction !== 'function') {
+      throw new TypeError('onInteraction must be a function');
+    }
+    if (onResolved !== undefined && typeof onResolved !== 'function') {
+      throw new TypeError('onResolved must be a function');
+    }
+    if (onOpen !== undefined && typeof onOpen !== 'function') {
+      throw new TypeError('onOpen must be a function');
+    }
+
+    while (!signal.aborted) {
+      try {
+        await this.#watchInteractionSocket(sessionId, {
+          signal,
+          onInteraction,
+          onResolved,
+          onOpen,
+          ownership,
+        });
+      } catch (error) {
+        if (signal.aborted) return;
+        console.warn(`[${this.#logPrefix}] Harness interaction stream disconnected:`, error.message);
+      }
+      if (signal.aborted) return;
+      try {
+        await sleep(this.#interactionReconnectDelayMs, signal);
+      } catch {
+        if (signal.aborted) return;
+        throw new Error('Harness interaction reconnect wait failed');
+      }
+    }
+  }
+
+  #registerInteractionOwnership(sessionId, ownership) {
+    const owners = this.#interactionOwnerships.get(sessionId) ?? new Set();
+    ownership.order = this.#interactionRegistry.nextOrder;
+    this.#interactionRegistry.nextOrder += 1;
+    owners.add(ownership);
+    this.#interactionOwnerships.set(sessionId, owners);
+  }
+
+  #unregisterInteractionOwnership(sessionId, ownership) {
+    const owners = this.#interactionOwnerships.get(sessionId);
+    owners?.delete(ownership);
+    if (owners?.size === 0) this.#interactionOwnerships.delete(sessionId);
+    for (const [key, claim] of this.#interactionClaims) {
+      if (claim.ownership === ownership) this.#interactionClaims.delete(key);
+    }
+  }
+
+  #consumeInteractionOwnerships(sessionId, entries) {
+    for (const ownership of this.#interactionOwnerships.get(sessionId) ?? []) {
+      consumeInteractionOwnership(ownership, entries);
+    }
+  }
+
+  async #refreshInteractionOwnerships(sessionId, signal) {
+    const history = await this.rpc(
+      'session.history',
+      { sessionId, maxMessages: 50 },
+      30_000,
+      { signal },
+    );
+    this.#consumeInteractionOwnerships(sessionId, history.events ?? []);
+  }
+
+  #interactionOwner(sessionId, claimKey, kind) {
+    const claim = this.#interactionClaims.get(claimKey);
+    if (claim && this.#interactionOwnerships.get(sessionId)?.has(claim.ownership)) return claim;
+
+    const owners = [...(this.#interactionOwnerships.get(sessionId) ?? [])];
+    const active = owners
+      .filter((ownership) => ownership.active)
+      .sort((left, right) => left.order - right.order);
+    if (active.length > 0) return { ownership: active[0], recovered: false };
+
+    // A newly attached IM conversation may encounter a question left by
+    // an earlier runtime before its queued prompt starts. Let the oldest such
+    // ask adopt that replay so the Session can recover instead of deadlocking.
+    // Approval adopters receive recovered=true and must reject it without ever
+    // presenting it as approvable; the original actor/route cannot be proven
+    // after a runtime restart.
+    const ownership = owners
+      .filter((ownership) => !ownership.started && !ownership.completed)
+      .sort((left, right) => left.order - right.order)[0] ?? null;
+    return ownership ? { ownership, recovered: true } : null;
+  }
+
+  async ask(sessionId, text, options = {}) {
+    if (typeof options === 'number') options = { timeoutMs: options };
+    const timeoutMs = options.timeoutMs ?? 600_000;
+    const signal = options.signal;
+    const onUpdate = typeof options.onUpdate === 'function' ? options.onUpdate : null;
+    const onInteraction = typeof options.onInteraction === 'function'
+      ? options.onInteraction
+      : undefined;
+    const onInteractionResolved = typeof options.onInteractionResolved === 'function'
+      ? options.onInteractionResolved
+      : undefined;
+    await this.ensureRunning({ signal });
+    const before = await this.rpc(
+      'session.history',
+      { sessionId, maxMessages: 1 },
+      30_000,
+      { signal },
+    );
+    const baselineSeq = Math.max(-1, ...(before.events ?? []).map(({ event }) => event.seq ?? -1));
+    const promptRpcId = `${this.#rpcIdPrefix}-${randomUUID()}`;
+    const tracker = new HarnessReplyTracker({ promptRpcId, afterSeq: baselineSeq });
+    const interactionController = onInteraction || onInteractionResolved
+      ? new AbortController()
+      : null;
+    const interactionSignal = interactionController
+      ? (signal
+          ? AbortSignal.any([signal, interactionController.signal])
+          : interactionController.signal)
+      : null;
+    // The mux is host-global. A prompt RPC becomes the owner only when its
+    // durable user/message starts a turn, so two chats bound to one Session
+    // cannot answer each other's questions or approvals.
+    const ownership = interactionController
+      ? {
+          promptRpcId,
+          active: false,
+          started: false,
+          completed: false,
+          turn: null,
+          openTurn: null,
+          lastSeq: baselineSeq,
+          reconnect: null,
+          order: -1,
+          toolCalls: new Map(),
+        }
+      : null;
+    let interactionTask = null;
+
+    if (ownership) this.#registerInteractionOwnership(sessionId, ownership);
+
+    try {
+      if (interactionSignal) {
+        let markOpen;
+        const opened = new Promise((resolve) => { markOpen = resolve; });
+        interactionTask = this.watchInteractions(sessionId, {
+          signal: interactionSignal,
+          onInteraction,
+          onResolved: onInteractionResolved,
+          onOpen: markOpen,
+          ownership,
+        });
+        void interactionTask.catch(() => undefined);
+        await Promise.race([
+          opened,
+          sleep(30_000, interactionSignal).then(() => {
+            throw new Error('Harness interaction stream did not open within 30 seconds');
+          }),
+        ]);
+      }
+
+      await this.rpc('session.prompt', {
+        sessionId,
+        mode: 'queue',
+        content: [{ type: 'text', text }],
+        clientTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+      }, 30_000, { rpcId: promptRpcId, signal });
+
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() < deadline) {
+        await sleep(300, signal);
+        const history = await this.rpc(
+          'session.history',
+          { sessionId, maxMessages: 50 },
+          30_000,
+          { signal },
+        );
+        const wasActive = ownership?.active === true;
+        if (ownership) {
+          this.#consumeInteractionOwnerships(sessionId, history.events ?? []);
+          if (!wasActive && ownership.active) ownership.reconnect?.();
+        }
+        const update = tracker.consume(history.events ?? []);
+        if (update && onUpdate) {
+          try {
+            await onUpdate(update);
+          } catch (error) {
+            console.warn(`[${this.#logPrefix}] ignored a progress update failure:`, error.message);
+          }
+        }
+        if (!tracker.finished) continue;
+        if (tracker.answer) return tracker.answer;
+        throw new Error(
+          `Harness turn ended without a text reply${tracker.reason ? ` (${JSON.stringify(tracker.reason)})` : ''}`,
+        );
+      }
+      throw new Error(`Harness reply timed out after ${Math.round(timeoutMs / 1_000)} seconds`);
+    } finally {
+      interactionController?.abort(new DOMException('Harness turn finished', 'AbortError'));
+      if (interactionTask) await interactionTask.catch(() => undefined);
+      if (ownership) this.#unregisterInteractionOwnership(sessionId, ownership);
+    }
+  }
+
+  #watchInteractionSocket(sessionId, {
+    signal,
+    onInteraction,
+    onResolved,
+    onOpen,
+    ownership,
+  }) {
+    const url = new URL('/api/events.mux', this.#baseUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+
+    return new Promise((resolve, reject) => {
+      let socket;
+      try {
+        socket = this.#createWebSocket(url.toString());
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      let opened = false;
+      let settled = false;
+      let callbackFailure = null;
+      let callbackTail = Promise.resolve();
+      let ownershipReady = ownership === undefined || ownership === null;
+      const bufferedEnvelopes = [];
+      const finish = (error) => {
+        if (settled) return;
+        settled = true;
+        socket.removeEventListener('open', handleOpen);
+        socket.removeEventListener('message', handleMessage);
+        socket.removeEventListener('close', handleClose);
+        socket.removeEventListener('error', handleError);
+        signal.removeEventListener('abort', handleAbort);
+        if (ownership?.reconnect === close) ownership.reconnect = null;
+        void callbackTail.then(() => {
+          const failure = error ?? callbackFailure;
+          if (failure) reject(failure);
+          else resolve();
+        }, reject);
+      };
+      const close = () => {
+        try {
+          if (socket.readyState === 0 || socket.readyState === 1) socket.close();
+        } catch {
+          // Cleanup must still settle the watcher if a WebSocket rejects close while connecting.
+        }
+      };
+      const handleOpen = () => {
+        opened = true;
+        if (ownership) ownership.reconnect = close;
+        try {
+          onOpen?.();
+        } catch (error) {
+          console.warn(`[${this.#logPrefix}] ignored an interaction open callback failure:`, error.message);
+        }
+        if (ownership) {
+          void this.#refreshInteractionOwnerships(sessionId, signal).then(() => {
+            if (settled) return;
+            ownershipReady = true;
+            for (const envelope of bufferedEnvelopes.splice(0)) processEnvelope(envelope);
+          }).catch((error) => {
+            callbackFailure ??= error;
+            close();
+            finish(error);
+          });
+        }
+      };
+      const dispatch = (callback, value) => {
+        if (!callback) return;
+        callbackTail = callbackTail
+          .then(() => callback(value))
+          .catch((error) => {
+            callbackFailure ??= error;
+            close();
+            finish(callbackFailure);
+          });
+      };
+      const processEnvelope = (envelope) => {
+        const payload = envelope.payload;
+        if (ownership && payload.type === 'session/event') {
+          this.#consumeInteractionOwnerships(sessionId, [payload.event]);
+          return;
+        }
+        if (payload.type === 'question/requested' || payload.type === 'approval/requested') {
+          const kind = payload.type === 'question/requested' ? 'question' : 'approval';
+          const interactionId = kind === 'question' ? envelope.rpcId : payload.approvalId;
+          const claimKey = `${kind}:${interactionId}`;
+          if (ownership) {
+            const claim = this.#interactionOwner(sessionId, claimKey, kind);
+            if (claim?.ownership !== ownership) return;
+            this.#interactionClaims.set(claimKey, claim);
+          }
+          const toolCall = kind === 'approval' && ownership && typeof payload.callId === 'string'
+            ? this.#interactionClaims.get(claimKey)?.ownership.toolCalls.get(payload.callId)
+            : undefined;
+          dispatch(onInteraction, Object.freeze({
+            kind,
+            interactionId,
+            rpcId: envelope.rpcId,
+            sessionId,
+            payload,
+            recovered: ownership
+              ? this.#interactionClaims.get(claimKey)?.recovered === true
+              : false,
+            ...(toolCall ? { toolCall } : {}),
+            reconnect: close,
+            respond: (result, options = {}) => this.respondInteraction(
+              envelope.rpcId,
+              result,
+              { ...options, signal: options.signal ?? signal },
+            ),
+          }));
+          return;
+        }
+        if (payload.type === 'question/resolved' || payload.type === 'approval/resolved') {
+          const kind = payload.type === 'question/resolved' ? 'question' : 'approval';
+          const interactionId = kind === 'question'
+            ? payload.questionRpcId
+            : payload.approvalId;
+          const claimKey = `${kind}:${interactionId}`;
+          if (ownership) {
+            const claim = this.#interactionClaims.get(claimKey);
+            if (claim?.ownership !== ownership) return;
+            this.#interactionClaims.delete(claimKey);
+          }
+          dispatch(onResolved, Object.freeze({
+            kind,
+            interactionId,
+            sessionId,
+            outcome: payload.outcome,
+            payload,
+          }));
+        }
+      };
+      const handleMessage = (event) => {
+        try {
+          if (typeof event.data !== 'string') throw new Error('binary WebSocket frame');
+          const envelope = JSON.parse(event.data);
+          const payload = envelope?.payload;
+          if (envelope?.type !== 'server-request'
+            || typeof envelope.rpcId !== 'string'
+            || !payload || typeof payload !== 'object'
+            || envelope.method !== payload.type) {
+            throw new Error('invalid server-request envelope');
+          }
+          if (payload.sessionId !== sessionId) return;
+          if (!ownershipReady) bufferedEnvelopes.push(envelope);
+          else processEnvelope(envelope);
+        } catch (error) {
+          console.warn(`[${this.#logPrefix}] ignored a malformed Harness interaction frame:`, error.message);
+        }
+      };
+      const handleClose = () => finish(opened ? null : new Error(
+        'Harness interaction WebSocket closed before opening',
+      ));
+      const handleError = () => {
+        finish(new Error(opened
+          ? 'Harness interaction WebSocket failed'
+          : 'Harness interaction WebSocket failed before opening'));
+        close();
+      };
+      const handleAbort = () => {
+        close();
+        finish();
+      };
+
+      socket.addEventListener('open', handleOpen);
+      socket.addEventListener('message', handleMessage);
+      socket.addEventListener('close', handleClose, { once: true });
+      socket.addEventListener('error', handleError, { once: true });
+      signal.addEventListener('abort', handleAbort, { once: true });
+      if (signal.aborted) handleAbort();
+    });
+  }
+
+  stopManagedProcess() {
+    if (this.#managedProcess?.exitCode === null) this.#managedProcess.kill('SIGTERM');
+  }
+}