Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
37.0 KB
Raw Blame
/**
 * The server's handle on session capture (the session uploader, the
 * project archive and the turn observers, see capture-host.ts). By default
 * the capture runs on a worker thread (capture-worker.ts): the main event
 * loop, which serves the app (in the desktop app, the Electron main process),
 * only posts calls and answers the worker's requests for the gateway broker
 * and external egress. Opening or switching sessions never waits on a scan,
 * a snapshot or an archive. If the worker cannot start (a runtime without
 * worker support for this module, or OMNIRUSH_CAPTURE_WORKER=0) the same host
 * runs in-process; a worker that dies after starting is replaced, again and
 * again with a growing pause, and the calls made meanwhile wait for it.
 */
import type { ApprovalMode } from "./approval-mode.js";
import { Worker } from "node:worker_threads";
import { lstat } from "node:fs/promises";
import { resolve } from "node:path";
import { START_GATE_MS } from "./session-archive/capture-v2.js";
import { LATE_WRITES_CAP_MS } from "./session-archive/late-writes.js";
import type { FilesUsedStatus } from "./session-archive/index.js";
import type { BoxCaptureInfo } from "./box/service.js";
import type { CommandEventType } from "./command-events.js";

import { CaptureHost, type CaptureDiagnostics, type CaptureHostOptions, type EngineReplacement, type EngineTarget, type LateWritesGate, type PromptRecord } from "./capture-host.js";
import {
  invokeCapture,
  serializeResponse,
  transferables,
  type CaptureCall,
  type CaptureWorkerInit,
  type FromWorker,
  type HostRequest,
  type RequestChannel,
  type RequestResult,
  type ToWorker,
} from "./capture-protocol.js";
import { externalFetch } from "./server-fetch.js";
import { isUploadableWebUrl, MAX_UPLOAD_COMPRESSED_BYTES, sessionUploaderEnabled, type UploadWebVisit } from "./session-uploader.js";

/** A prompt body larger than this is not traced, so it is not copied to the worker either. */
const MAX_TRACED_REQUEST_BYTES = 4 * 1024 * 1024;
/** Shutdown waits this long for the last traces and end snapshots before the worker is terminated. */
const STOP_TIMEOUT_MS = 20_000;
/** Shutdown waits this long to learn whether the account is still there (for the final project archives), else packs none. */
const ACCOUNT_CHECK_TIMEOUT_MS = 1_000;
/** The pause before a new worker: `baseMs` doubled per consecutive exit, at most `maxMs`; `stableMs` up and ready starts over. */
type RestartBackoff = { baseMs: number; maxMs: number; stableMs?: number };
/** A worker that exits unexpectedly is replaced after 1 s, then 2 s, 4 s, ... at most 60 s. */
const RESTART_BACKOFF: RestartBackoff = { baseMs: 1_000, maxMs: 60_000 };
/** A worker that stayed up and ready this long starts the backoff over. */
const RESTART_STABLE_MS = 5 * 60_000;
/** Calls waiting for a worker to start; past this the oldest one nobody waits on is dropped. */
const MAX_QUEUED_CALLS = 20_000;
const SESSION_ID_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/;
/** Chats whose engine is remembered for a restarted worker. */
const MAX_OBSERVED_TARGETS = 256;

export type CaptureServiceOptions = Omit<CaptureHostOptions, "onSessionClosed"> & {
  /** Run capture on a worker thread; default on unless OMNIRUSH_CAPTURE_WORKER is 0, false, no or off. */
  worker?: boolean;
  /** How long shutdown waits for the capture to stop; STOP_TIMEOUT_MS unless a test lowers it. */
  stopTimeoutMs?: number;
  /** RESTART_BACKOFF and RESTART_STABLE_MS unless a test lowers them. */
  restartBackoffMs?: RestartBackoff;
  /** Told each time the mode changes. */
  onModeChange?: (mode: CaptureMode) => void;
};

/**
 * Where capture runs: "restarting" between a worker's exit and the next
 * one's start, and "down" only once stopped. While "starting" or
 * "restarting", calls wait for the worker.
 */
export type CaptureMode = "starting" | "worker" | "local" | "restarting" | "down";

export type CaptureService = {
  /** A Claude chat: its uploads name Claude Code (`version`) as the harness. */
  markClaude(sessionId: string, version: string): void;
  /** A chat pinned to another provider's model: its uploads keep the engine's identity. */
  markNotClaude(sessionId: string): void;
  /** The session uploader has an account to upload to (the sign-in gate's question). */
  readonly uploadEnabled: boolean;
  /** Where capture runs right now. */
  mode(): CaptureMode;
  /** The mode, when it began, and how many times a worker was replaced (the app's status). */
  status(): { mode: CaptureMode; since: Date; restarts: number };
  /** Whether the session uploader is tracking this session (started and not finished). */
  hasSession(sessionId: string): boolean;
  /** `turnsBefore`: the turns a reopened chat already had (its turn numbers carry on from them). */
  startSession(sessionId: string, workspaceId: string, root: string, turnsBefore?: number): void;
  /** The chat's prompts run in its project's Linux sandbox (box/service.ts), or no longer (null); before startSession. */
  boxSession(sessionId: string, box: BoxCaptureInfo | null): void;
  /** A tracked chat's capture policy once settled; null when it is not tracked or not settled. */
  sessionPolicy(sessionId: string): Promise<string | null>;
  /** The capture policy the server's binding keeps for the chat: its uploads follow it. */
  pinPolicy(sessionId: string, policy: string): void;
  /** Strict sessions: hold the chat's uploads until its binding is confirmed (kept on disk); `seq` orders the calls. */
  holdUploads(sessionId: string, state: "pending" | "refused" | "confirmed", seq: number): void;
  /** The app's permission mode, named in the setup record of the sessions started after it; before startSession. */
  permissionMode(mode: ApprovalMode | null): void;
  recordTrace(sessionId: string, type: string, data?: unknown): void;
  flushTrace(sessionId: string, finalTrace?: unknown): void;
  finishSession(sessionId: string, finalTrace?: unknown): void;
  /** The "engine.request" event of a captured request (its body parsed off the main thread), plus a prompt's attachments. */
  recordPrompt(sessionId: string, prompt: Omit<PromptRecord, "body"> & { body: ArrayBuffer | undefined }): void;
  captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"): void;
  /** A prompt steered the running turn: its "turn.steer" event (turn-steer.ts steerRecord). */
  steerTurn(sessionId: string, steer: Record<string, unknown>): void;
  /** An undo / redo / review / fix the person ran: its additive event (command-events.ts). */
  recordCommand(sessionId: string, type: CommandEventType, data: Record<string, unknown>): void;
  /** The engine took a steer: its turn is followed (if no observer follows it already). */
  followSteer(sessionId: string, target: EngineTarget): void;
  /** Whether the visit is recorded (a tracked session and an uploadable URL). */
  recordWebVisit(sessionId: string, visit: UploadWebVisit): boolean;
  archiveSessionStarted(sessionId: string, root: string, target: EngineTarget): void;
  /**
   * Resolves once the turn before's background processes finished writing
   * (with `lateWrites`, when that turn ended: LATE_WRITES_CAP_MS after its
   * end at most), capture v2's project archive took the session-start
   * manifest (hash and stat only) and a new session's start snapshot read the
   * folder (call startSession first; both START_GATE_MS at most); the prompt goes to
   * the engine after it. Never rejects.
   */
  archiveStartGate(sessionId: string, root: string, lateWrites?: LateWritesGate | null): Promise<void>;
  observeSession(sessionId: string, target: EngineTarget): void;
  /** An engine was closed and another took over its sessions: turn observers reading it move there. */
  engineReplaced(closedBaseUrl: string, replacement: EngineReplacement): void;
  sessionDeleted(sessionId: string): void;
  signOut(): Promise<void>;
  /**
   * Stops capture. `archiveFinals` (default true) says whether the account is
   * still connected, so that the project archive packs its final archives;
   * a user sign-out clears the account before it restarts the server.
   */
  stop(options?: { archiveFinals?: boolean | Promise<boolean> }): Promise<void>;
  /** Every queued capture, upload and archive step settled (tests, profiling). */
  idle(): Promise<void>;
  diagnostics(): Promise<CaptureDiagnostics | null>;
  /** Files used, for the app's one-time notice (null: capture is not running). */
  filesUsedStatus(): Promise<FilesUsedStatus | null>;
  /** Uploads and project archives queued now (null: capture is not running). */
  pendingUploads(): Promise<PendingUploads | null>;
  /** Before a sign-out: sends what is queued for at most `budgetMs`; the rest stays queued for the account. */
  flushPending(budgetMs: number): Promise<{ before: number; after: number } | null>;
};

export type PendingUploads = { uploads: number; archives: number };

/** How much longer than the start gate's own cap the main thread waits for the worker's answer. */
const START_GATE_SLACK_MS = 1_000;

export function captureWorkerEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
  return !["0", "false", "no", "off"].includes((env.OMNIRUSH_CAPTURE_WORKER ?? "").trim().toLowerCase());
}

function workerUrl(): URL {
  // Tests and development run the TypeScript sources; builds run the compiled modules.
  return new URL(import.meta.url.endsWith(".ts") ? "./capture-worker.ts" : "./capture-worker.js", import.meta.url);
}

function errorSummary(error: unknown): string {
  return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
}

type QueuedCall = { call: CaptureCall; transfer: ArrayBuffer[] };

class CaptureClient implements CaptureService {
  readonly uploadEnabled: boolean;
  private current: CaptureMode = "starting";
  private since = new Date();
  private worker: Worker | null = null;
  private local: CaptureHost | null = null;
  private queue: QueuedCall[] = [];
  private callSeq = 0;
  /** Calls waiting for the worker's reply. */
  private readonly replies = new Map<number, (value: unknown) => void>();
  /** The worker's requests being served on this thread. */
  private readonly served = new Map<number, { controller: AbortController; channel: RequestChannel }>();
  /** Sessions the worker's session uploader tracks: true while live, false once finishing. */
  private readonly sessions = new Map<string, boolean>();
  private restarts = 0;
  /** Exits since a worker last stayed up RESTART_STABLE_MS: the next pause doubles with each. */
  private attempt = 0;
  private readyAt = 0;
  private restartTimer: ReturnType<typeof setTimeout> | null = null;
  /** Only the first start falls back to capturing in-process; later failures start new workers. */
  private canRunLocally = true;
  private overflowing = false;
  /** The engine each recently observed chat's requests went to: a restarted worker settles their open turns there. */
  private readonly observedTargets = new Map<string, EngineTarget>();
  private stopping: Promise<void> | null = null;

  constructor(private readonly options: CaptureServiceOptions) {
    this.uploadEnabled = sessionUploaderEnabled({
      upload: Boolean(options.sessionUploader.upload || options.sessionUploader.uploadFile),
      gatewayUrl: options.sessionUploader.gatewayUrl,
      accessToken: options.sessionUploader.accessToken,
    });
    if (options.worker ?? captureWorkerEnabled()) this.spawn();
    else this.runLocally(null);
  }

  mode(): CaptureMode {
    return this.current;
  }

  status(): { mode: CaptureMode; since: Date; restarts: number } {
    return { mode: this.current, since: this.since, restarts: this.restarts };
  }

  private setMode(mode: CaptureMode): void {
    if (mode === this.current) return;
    this.current = mode;
    this.since = new Date();
    this.options.onModeChange?.(mode);
  }

  hasSession(sessionId: string): boolean {
    if (this.local) return this.local.sessionUploader.hasSession(sessionId);
    return this.sessions.get(sessionId) === true;
  }

  startSession(sessionId: string, workspaceId: string, root: string, turnsBefore = 0): void {
    if (this.uploadEnabled && SESSION_ID_PATTERN.test(sessionId) && !this.sessions.has(sessionId)) this.sessions.set(sessionId, true);
    this.send({ kind: "call", id: null, method: "startSession", args: [sessionId, workspaceId, root, turnsBefore] });
  }

  async sessionPolicy(sessionId: string): Promise<string | null> {
    const value = await this.query({ kind: "call", id: null, method: "sessionPolicy", args: [sessionId] }).catch(() => null);
    return typeof value === "string" ? value : null;
  }

  pinPolicy(sessionId: string, policy: string): void {
    this.send({ kind: "call", id: null, method: "pinPolicy", args: [sessionId, policy] });
  }

  holdUploads(sessionId: string, state: "pending" | "refused" | "confirmed", seq: number): void {
    // Awaited: a full start-up queue never drops it (it drops calls nobody waits on first).
    void this.query({ kind: "call", id: null, method: "holdUploads", args: [sessionId, state, seq] }).catch(() => null);
  }

  markClaude(sessionId: string, version: string): void {
    this.send({ kind: "call", id: null, method: "markClaude", args: [sessionId, version] });
  }

  markNotClaude(sessionId: string): void {
    this.send({ kind: "call", id: null, method: "markNotClaude", args: [sessionId] });
  }

  boxSession(sessionId: string, box: BoxCaptureInfo | null): void {
    this.send({ kind: "call", id: null, method: "boxSession", args: [sessionId, box] });
  }

  permissionMode(mode: ApprovalMode | null): void {
    this.send({ kind: "call", id: null, method: "permissionMode", args: [mode] });
  }

  recordTrace(sessionId: string, type: string, data?: unknown): void {
    this.send({ kind: "call", id: null, method: "recordTrace", args: data === undefined ? [sessionId, type] : [sessionId, type, data] });
  }

  flushTrace(sessionId: string, finalTrace?: unknown): void {
    this.send({ kind: "call", id: null, method: "flushTrace", args: finalTrace === undefined ? [sessionId] : [sessionId, finalTrace] });
  }

  finishSession(sessionId: string, finalTrace?: unknown): void {
    if (this.sessions.get(sessionId) === true) this.sessions.set(sessionId, false);
    this.send({ kind: "call", id: null, method: "finishSession", args: finalTrace === undefined ? [sessionId] : [sessionId, finalTrace] });
  }

  recordPrompt(sessionId: string, prompt: Omit<PromptRecord, "body"> & { body: ArrayBuffer | undefined }): void {
    // The body is still forwarded to the engine: the worker gets its own copy, moved rather than cloned.
    const body = prompt.body && prompt.body.byteLength > 0 && prompt.body.byteLength <= MAX_TRACED_REQUEST_BYTES ? new Uint8Array(prompt.body.slice(0)) : null;
    this.send({ kind: "call", id: null, method: "recordPrompt", args: [sessionId, { ...prompt, body }] }, body ? [body.buffer] : []);
  }

  captureSnapshot(sessionId: string, trigger: "prompt" | "turn_completed", outcome?: "aborted"): void {
    this.send({ kind: "call", id: null, method: "captureSnapshot", args: outcome ? [sessionId, trigger, outcome] : [sessionId, trigger] });
  }

  steerTurn(sessionId: string, steer: Record<string, unknown>): void {
    this.send({ kind: "call", id: null, method: "steerTurn", args: [sessionId, steer] });
  }

  recordCommand(sessionId: string, type: CommandEventType, data: Record<string, unknown>): void {
    this.send({ kind: "call", id: null, method: "recordCommand", args: [sessionId, type, data] });
  }

  followSteer(sessionId: string, target: EngineTarget): void {
    this.observedTargets.delete(sessionId);
    this.observedTargets.set(sessionId, target);
    if (this.observedTargets.size > MAX_OBSERVED_TARGETS) this.observedTargets.delete(this.observedTargets.keys().next().value as string);
    this.send({ kind: "call", id: null, method: "followSteer", args: [sessionId, target] });
  }

  recordWebVisit(sessionId: string, visit: UploadWebVisit): boolean {
    if (this.local) return this.local.recordWebVisit(sessionId, visit);
    if (!this.hasSession(sessionId) || typeof visit.url !== "string" || !isUploadableWebUrl(visit.url)) return false;
    this.send({ kind: "call", id: null, method: "recordWebVisit", args: [sessionId, visit] });
    return true;
  }

  archiveSessionStarted(sessionId: string, root: string, target: EngineTarget): void {
    this.send({ kind: "call", id: null, method: "archiveSessionStarted", args: [sessionId, root, target] });
  }

  async archiveStartGate(sessionId: string, root: string, lateWrites?: LateWritesGate | null): Promise<void> {
    // The worker answers within the gate's cap (plus the late-writes cap); a busy or stuck worker never holds a prompt longer.
    let timer: ReturnType<typeof setTimeout> | undefined;
    await Promise.race([
      this.query({ kind: "call", id: null, method: "archiveStartGate", args: lateWrites ? [sessionId, root, lateWrites] : [sessionId, root] }).catch(() => undefined),
      new Promise<void>((resolvePromise) => {
        timer = setTimeout(resolvePromise, START_GATE_MS + START_GATE_SLACK_MS + (lateWrites ? LATE_WRITES_CAP_MS : 0));
        timer.unref?.();
      }),
    ]);
    clearTimeout(timer);
  }

  observeSession(sessionId: string, target: EngineTarget): void {
    this.observedTargets.delete(sessionId);
    this.observedTargets.set(sessionId, target);
    if (this.observedTargets.size > MAX_OBSERVED_TARGETS) this.observedTargets.delete(this.observedTargets.keys().next().value as string);
    this.send({ kind: "call", id: null, method: "observeSession", args: [sessionId, target] });
  }

  engineReplaced(closedBaseUrl: string, replacement: EngineReplacement): void {
    this.send({ kind: "call", id: null, method: "engineReplaced", args: [closedBaseUrl, replacement] });
  }

  sessionDeleted(sessionId: string): void {
    if (this.sessions.get(sessionId) === true) this.sessions.set(sessionId, false);
    this.send({ kind: "call", id: null, method: "sessionDeleted", args: [sessionId] });
  }

  async signOut(): Promise<void> {
    await this.query({ kind: "call", id: null, method: "signOut", args: [] });
  }

  async idle(): Promise<void> {
    await this.query({ kind: "call", id: null, method: "idle", args: [] });
  }

  async diagnostics(): Promise<CaptureDiagnostics | null> {
    const value = await this.query({ kind: "call", id: null, method: "diagnostics", args: [] });
    return isDiagnostics(value) ? value : null;
  }

  async filesUsedStatus(): Promise<FilesUsedStatus | null> {
    return filesUsedStatusOf(await this.query({ kind: "call", id: null, method: "filesUsedStatus", args: [] }));
  }

  async pendingUploads(): Promise<PendingUploads | null> {
    const value = await this.query({ kind: "call", id: null, method: "pendingUploads", args: [] });
    return countsOf(value, ["uploads", "archives"]) as PendingUploads | null;
  }

  async flushPending(budgetMs: number): Promise<{ before: number; after: number } | null> {
    const value = await this.query({ kind: "call", id: null, method: "flushPending", args: [budgetMs] });
    return countsOf(value, ["before", "after"]) as { before: number; after: number } | null;
  }

  stop(options: { archiveFinals?: boolean | Promise<boolean> } = {}): Promise<void> {
    this.stopping ??= this.shutdown(options.archiveFinals ?? true);
    return this.stopping;
  }

  private async shutdown(archiveFinals: boolean | Promise<boolean>): Promise<void> {
    // First, and synchronously: archive uploads this thread makes for the worker are aborted now.
    for (const { controller, channel } of this.served.values()) if (channel === "archive") controller.abort();
    // Between workers: the next one starts now, so the queued calls and the stop reach it.
    if (this.restartTimer) {
      clearTimeout(this.restartTimer);
      this.spawn();
    }
    const finals = await withinTimeout(archiveFinals, ACCOUNT_CHECK_TIMEOUT_MS);
    const done = this.dispatch({ kind: "call", id: null, method: "stop", args: [{ archiveFinals: finals }] }, [], true);
    const timeoutMs = this.options.stopTimeoutMs ?? STOP_TIMEOUT_MS;
    let timer: ReturnType<typeof setTimeout> | undefined;
    const timedOut = new Promise<true>((resolvePromise) => {
      timer = setTimeout(() => {
        this.options.log("warn", this.local
          ? "OmniRush capture did not stop in time; its uploads in flight are aborted"
          : "OmniRush capture did not stop in time; the capture worker is terminated", { timeoutMs });
        resolvePromise(true);
      }, timeoutMs);
      timer.unref?.();
    });
    const late = await Promise.race([done.then(() => false), timedOut]);
    clearTimeout(timer);
    // In-process there is no worker to terminate: its uploads end here instead (spooled for the next start).
    if (late) this.local?.sessionUploader.abortUploads();
    const worker = this.worker;
    this.worker = null;
    this.setMode("down");
    if (worker) await worker.terminate().catch(() => undefined);
    // Also aborts the requests this thread was still serving for the worker.
    this.settleOutstanding();
  }

  // --- calls ------------------------------------------------------------------

  private send(call: CaptureCall, transfer: ArrayBuffer[] = []): void {
    if (this.stopping) return;
    void this.dispatch(call, transfer, false);
  }

  private query(call: CaptureCall): Promise<unknown> {
    if (this.stopping) return Promise.resolve(null);
    return this.dispatch(call, [], true);
  }

  /** Runs or posts one call; resolves with its result when `awaited`, else at once. */
  private dispatch(call: CaptureCall, transfer: ArrayBuffer[], awaited: boolean): Promise<unknown> {
    if (this.local) {
      try {
        return Promise.resolve(invokeCapture(this.local, call)).catch(() => null);
      } catch (error) {
        this.options.log("warn", "OmniRush capture call failed", { method: call.method, error: errorSummary(error) });
        return Promise.resolve(null);
      }
    }
    if (this.current === "down") return Promise.resolve(null);
    let reply: Promise<unknown> = Promise.resolve(null);
    if (awaited) {
      const id = ++this.callSeq;
      call.id = id;
      reply = new Promise((resolvePromise) => this.replies.set(id, resolvePromise));
    }
    if (this.current === "worker" && this.worker) this.post(this.worker, call, transfer);
    else this.enqueue({ call, transfer });
    return reply;
  }

  /** Queues a call for the next worker; a full queue drops its oldest call nobody waits on (an awaited one only if all are). */
  private enqueue(queued: QueuedCall): void {
    if (this.queue.length >= MAX_QUEUED_CALLS) {
      const [dropped] = this.queue.splice(Math.max(0, this.queue.findIndex((item) => item.call.id === null)), 1);
      if (dropped && dropped.call.id !== null) {
        this.replies.get(dropped.call.id)?.(null);
        this.replies.delete(dropped.call.id);
      }
      if (!this.overflowing) {
        this.overflowing = true;
        this.options.log("warn", "OmniRush capture calls are queued past the limit while the capture worker starts; the oldest are dropped", { limit: MAX_QUEUED_CALLS });
      }
    }
    this.queue.push(queued);
  }

  /** Hands the queued calls over (the worker is ready, or the host runs in-process). */
  private takeQueue(): QueuedCall[] {
    const queued = this.queue;
    this.queue = [];
    this.overflowing = false;
    return queued;
  }

  /** Posts a call; one whose arguments cannot be cloned is dropped with a warn line, never thrown into the request. */
  private post(worker: Worker, call: CaptureCall, transfer: ArrayBuffer[]): void {
    try {
      worker.postMessage(call satisfies ToWorker, transfer);
    } catch (error) {
      this.options.log("warn", "OmniRush capture call could not be sent to the capture worker", { method: call.method, error: errorSummary(error) });
      if (call.id === null) return;
      const resolvePromise = this.replies.get(call.id);
      this.replies.delete(call.id);
      resolvePromise?.(null);
    }
  }

  // --- the worker -----------------------------------------------------------------

  private workerInit(): CaptureWorkerInit {
    const { sessionUploader, archive } = this.options;
    return {
      stateDir: this.options.stateDir,
      appVersion: this.options.appVersion,
      engineVersion: this.options.engineVersion,
      accountId: Boolean(this.options.accountId),
      sessionIntegrity: Boolean(this.options.sessionIntegrity),
      // Always: the chats this thread saw observed are known here even without a resolver.
      engineTarget: true,
      ...(this.options.installLog ? { installLog: this.options.installLog } : {}),
      ...(this.options.boxInstallLog ? { boxInstallLog: this.options.boxInstallLog } : {}),
      sessionUploader: {
        upload: Boolean(sessionUploader.upload),
        uploadFile: Boolean(sessionUploader.uploadFile),
        capabilities: Boolean(sessionUploader.capabilities),
        refreshAccessToken: Boolean(sessionUploader.refreshAccessToken),
        ...(sessionUploader.gatewayUrl !== undefined ? { gatewayUrl: sessionUploader.gatewayUrl } : {}),
        ...(sessionUploader.accessToken !== undefined ? { accessToken: sessionUploader.accessToken } : {}),
      },
      archive: {
        enabled: archive.enabled,
        excludedDirs: archive.excludedDirs,
        folderGate: archive.folderGate,
        request: Boolean(archive.request),
        refreshAccessToken: Boolean(archive.refreshAccessToken),
        ...(archive.gatewayUrl !== undefined ? { gatewayUrl: archive.gatewayUrl } : {}),
        ...(archive.accessToken !== undefined ? { accessToken: archive.accessToken } : {}),
        ...(archive.baseIdleMs !== undefined ? { baseIdleMs: archive.baseIdleMs } : {}),
        ...(archive.baseMaxDeferMs !== undefined ? { baseMaxDeferMs: archive.baseMaxDeferMs } : {}),
      },
    };
  }

  private spawn(): void {
    this.restartTimer = null;
    this.setMode("starting");
    let worker: Worker;
    try {
      worker = new Worker(workerUrl(), { workerData: this.workerInit() });
    } catch (error) {
      if (this.canRunLocally) this.runLocally(error);
      else this.scheduleRestart("OmniRush capture worker could not start; starting a new one", { error: errorSummary(error) });
      return;
    }
    // The server's listener keeps the process alive; the worker never holds it open on its own.
    worker.unref();
    this.worker = worker;
    worker.on("message", (message: FromWorker) => this.onMessage(worker, message));
    worker.on("error", (error: unknown) => {
      if (worker === this.worker) this.options.log("warn", "OmniRush capture worker failed", { error: errorSummary(error) });
    });
    worker.on("exit", (code: number) => this.onExit(worker, code));
  }

  private onMessage(worker: Worker, message: FromWorker): void {
    if (worker !== this.worker) return;
    switch (message.kind) {
      case "ready": {
        this.setMode("worker");
        this.readyAt = Date.now();
        this.canRunLocally = false;
        for (const { call, transfer } of this.takeQueue()) this.post(worker, call, transfer);
        return;
      }
      case "log":
        this.options.log(message.level, message.message, message.attributes);
        return;
      case "closed":
        if (this.sessions.get(message.sessionId) === false) this.sessions.delete(message.sessionId);
        return;
      case "reply": {
        const resolvePromise = this.replies.get(message.id);
        this.replies.delete(message.id);
        resolvePromise?.(message.ok ? message.value : null);
        return;
      }
      case "abort":
        this.served.get(message.id)?.controller.abort();
        return;
      case "request":
        void this.serve(worker, message.id, message.channel, message.request);
        return;
    }
  }

  private onExit(worker: Worker, code: number): void {
    if (worker !== this.worker) return;
    this.worker = null;
    this.settleOutstanding();
    if (this.stopping) return;
    if (this.current === "starting" && this.canRunLocally) {
      this.runLocally(new Error(`the capture worker exited with code ${code} before it was ready`));
      return;
    }
    // Its sessions are gone with it; each resumes on its next prompt.
    this.sessions.clear();
    this.scheduleRestart("OmniRush capture worker exited; starting a new one", { code });
  }

  /** Starts a new worker after the backoff's pause; calls made meanwhile are queued for it. */
  private scheduleRestart(message: string, attributes: Record<string, unknown>): void {
    const { baseMs, maxMs, stableMs = RESTART_STABLE_MS } = this.options.restartBackoffMs ?? RESTART_BACKOFF;
    if (this.readyAt && Date.now() - this.readyAt >= stableMs) this.attempt = 0;
    this.readyAt = 0;
    const delayMs = Math.min(baseMs * 2 ** this.attempt, maxMs);
    this.attempt += 1;
    this.restarts += 1;
    this.setMode("restarting");
    this.options.log("warn", message, { ...attributes, attempt: this.attempt, delayMs });
    this.restartTimer = setTimeout(() => this.spawn(), delayMs);
    this.restartTimer.unref?.();
  }

  /**
   * The worker is gone: every caller waiting on it gets an empty result, and
   * every request this thread still serves for it (a session upload that
   * outlasted the stop, an archive or egress fetch) is aborted, so none runs
   * on for up to its own deadline with no one left to take the answer.
   */
  private settleOutstanding(): void {
    for (const resolvePromise of this.replies.values()) resolvePromise(null);
    this.replies.clear();
    for (const { controller } of this.served.values()) controller.abort(new DOMException("The capture worker has stopped", "AbortError"));
    this.served.clear();
  }

  /** No worker: the host runs on this thread, starting with the calls queued so far. */
  private runLocally(reason: unknown): void {
    if (reason !== null) {
      this.options.log("warn", "OmniRush capture worker could not start; capturing in-process", { error: errorSummary(reason) });
    }
    const { worker: _worker, stopTimeoutMs: _stopTimeoutMs, restartBackoffMs: _backoff, onModeChange: _onModeChange, ...hostOptions } = this.options;
    this.canRunLocally = false;
    try {
      this.local = new CaptureHost(hostOptions);
    } catch (error) {
      // Only reached after a worker failed the same way: new workers are tried, with the queued calls kept for them.
      if (reason === null) throw error;
      this.scheduleRestart("OmniRush capture could not start in-process either; starting a new capture worker", { error: errorSummary(error) });
      return;
    }
    this.setMode("local");
    for (const { call } of this.takeQueue()) {
      const id = call.id;
      let value: unknown = null;
      try {
        value = invokeCapture(this.local, call);
      } catch (error) {
        this.options.log("warn", "OmniRush capture call failed", { method: call.method, error: errorSummary(error) });
      }
      if (id === null) continue;
      const resolvePromise = this.replies.get(id);
      this.replies.delete(id);
      Promise.resolve(value).then((settled) => resolvePromise?.(settled), () => resolvePromise?.(null));
    }
  }

  // --- the worker's requests ------------------------------------------------------------

  private async serve(worker: Worker, id: number, channel: RequestChannel, request: HostRequest): Promise<void> {
    const controller = new AbortController();
    // Shutting down: archive uploads were aborted, and none starts again.
    if (this.stopping && channel === "archive") controller.abort();
    this.served.set(id, { controller, channel });
    let result: RequestResult;
    try {
      if (controller.signal.aborted) throw new DOMException("The server is stopping", "AbortError");
      result = await this.perform(channel, request, controller.signal, id);
    } catch (error) {
      result = { kind: "result", id, ok: false, error: error instanceof Error ? error.message : String(error), name: error instanceof Error ? error.name : "Error" };
    } finally {
      this.served.delete(id);
    }
    if (worker !== this.worker) return;
    worker.postMessage(result satisfies ToWorker, result.ok ? transferables(result.response) : []);
  }

  private async perform(channel: RequestChannel, request: HostRequest, signal: AbortSignal, id: number): Promise<RequestResult> {
    const { sessionUploader, archive } = this.options;
    switch (request.type) {
      case "upload": {
        if (!sessionUploader.upload) throw new Error("no session upload hook");
        return { kind: "result", id, ok: true, response: await serializeResponse(await sessionUploader.upload(request.sessionId, request.body, signal, request.options)) };
      }
      case "uploadFile": {
        if (!sessionUploader.uploadFile) throw new Error("no session file upload hook");
        const root = resolve(this.options.stateDir);
        const path = resolve(request.path);
        if (!path.startsWith(`${root}${process.platform === "win32" ? "\\" : "/"}`)) throw new Error("capture file is outside the state directory");
        const file = await lstat(path);
        if (!file.isFile() || file.size !== request.size || file.size > MAX_UPLOAD_COMPRESSED_BYTES) {
          throw new Error("capture file descriptor is invalid");
        }
        return {
          kind: "result",
          id,
          ok: true,
          response: await serializeResponse(await sessionUploader.uploadFile(request.sessionId, path, request.size, signal, request.options)),
        };
      }
      case "capabilities": {
        if (!sessionUploader.capabilities) throw new Error("no session capability hook");
        return { kind: "result", id, ok: true, response: null, value: await sessionUploader.capabilities() };
      }
      case "sessionIntegrity": {
        if (!this.options.sessionIntegrity) throw new Error("no integrity hook");
        return { kind: "result", id, ok: true, response: await serializeResponse(await this.options.sessionIntegrity(request.sessionId, {
          ...(request.summary ? { summary: true } : {}),
          ...(request.turns !== undefined ? { turns: request.turns } : {}),
        })) };
      }
      case "engineTarget":
        // A chat this server saw go to an engine (a restarted worker's), else the workspace's engine.
        return {
          kind: "result",
          id,
          ok: true,
          response: null,
          target: this.observedTargets.get(request.sessionId) ?? (this.options.engineTarget ? await this.options.engineTarget(request.sessionId, request.workspaceId) : null),
        };
      case "accountId":
        return { kind: "result", id, ok: true, response: null, account: this.options.accountId ? await this.options.accountId() : null };
      case "refreshAccessToken": {
        const refresh = channel === "archive" ? archive.refreshAccessToken : sessionUploader.refreshAccessToken;
        return { kind: "result", id, ok: true, response: null, token: refresh ? await refresh() : null };
      }
      case "archiveRequest": {
        if (!archive.request) throw new Error("no archive request hook");
        const response = await archive.request(request.path, {
          method: request.method,
          ...(request.body !== undefined ? { body: request.body } : {}),
          ...(request.refresh === false ? { refresh: false as const } : {}),
          signal,
        });
        return { kind: "result", id, ok: true, response: await serializeResponse(response) };
      }
      case "fetch": {
        const egress = (channel === "archive" ? archive.fetch : sessionUploader.fetch) ?? externalFetch;
        const response = await egress(request.url, {
          method: request.method,
          headers: request.headers,
          ...(request.body !== undefined ? { body: request.body } : {}),
          signal,
        });
        return { kind: "result", id, ok: true, response: await serializeResponse(response) };
      }
    }
  }
}

/** The answer if it comes within `ms`, else false (as for a failed check). */
async function withinTimeout(answer: boolean | Promise<boolean>, ms: number): Promise<boolean> {
  if (typeof answer === "boolean") return answer;
  let timer: ReturnType<typeof setTimeout> | undefined;
  const late = new Promise<boolean>((resolvePromise) => {
    timer = setTimeout(() => resolvePromise(false), ms);
    timer.unref?.();
  });
  try {
    return await Promise.race([answer.catch(() => false), late]);
  } finally {
    clearTimeout(timer);
  }
}

/** `value` when it is an object with a non-negative integer at each of `keys`, else null. */
function countsOf(value: unknown, keys: readonly string[]): Record<string, number> | null {
  if (!value || typeof value !== "object") return null;
  const out: Record<string, number> = {};
  for (const key of keys) {
    const count = Reflect.get(value, key);
    if (!Number.isSafeInteger(count) || count < 0) return null;
    out[key] = count;
  }
  return out;
}

function filesUsedStatusOf(value: unknown): FilesUsedStatus | null {
  if (typeof value !== "object" || value === null) return null;
  const record = value as Record<string, unknown>;
  const flag = (item: unknown) => (typeof item === "boolean" ? item : null);
  return { active: flag(record.active), available: flag(record.available), consentText: typeof record.consentText === "string" ? record.consentText : null };
}

function isDiagnostics(value: unknown): value is CaptureDiagnostics {
  return typeof value === "object" && value !== null && "metrics" in value && "cache" in value;
}

export function startCaptureService(options: CaptureServiceOptions): CaptureService {
  return new CaptureClient(options);
}