@skaile/forge-agent-runtime 0.0.0-stage → 1.0.0

package/dist/index.mjs

@@ -0,0 +1,881 @@
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import net from 'node:net';
+import { join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createConsola } from 'consola';
+import { createColors } from 'picocolors';
+import { AgentClient } from '@skaile/workspaces/sdk/client';
+import { WebSocketClientTransport } from '@skaile/workspaces/sdk/transport/ws/client';
+import { registryCredentialEnv } from '@skaile/forge-settings/server';
+import { mkdir, appendFile, readFile } from 'node:fs/promises';
+import { SessionDispatcher } from '@skaile/workspaces/sdk/session';
+
+const pc = createColors(true);
+const consolaWithFancy = createConsola;
+const log = consolaWithFancy({
+  fancy: false,
+  defaults: { tag: pc.bold(pc.cyan("agent-process")) }
+});
+const BASE_PORT = 9100;
+let nextPort = BASE_PORT;
+async function isPortFree(port) {
+  return new Promise((resolve2) => {
+    const server = net.createServer();
+    server.once("error", () => resolve2(false));
+    server.once("listening", () => {
+      server.close(() => resolve2(true));
+    });
+    server.listen(port);
+  });
+}
+async function allocatePort() {
+  for (let i = 0; i < 100; i++) {
+    const port = nextPort++;
+    if (nextPort > BASE_PORT + 500) nextPort = BASE_PORT;
+    if (await isPortFree(port)) return port;
+  }
+  throw new Error("Could not find a free port for skaile serve");
+}
+function dialHost(host) {
+  if (!host) return "127.0.0.1";
+  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function resolveSkaileCmd() {
+  try {
+    return fileURLToPath(import.meta.resolve("@skaile/workspaces/cli"));
+  } catch {
+  }
+  try {
+    const entryDir = fileURLToPath(new URL(".", import.meta.url));
+    const cliSubpath = join("node_modules", "@skaile", "workspaces", "dist", "cli", "index.js");
+    let dir = entryDir;
+    for (let i = 0; i < 8; i++) {
+      const candidate = join(dir, cliSubpath);
+      if (existsSync(candidate)) return candidate;
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+  }
+  return "skaile";
+}
+function resolveBunCmd() {
+  const exec = basename(process.execPath).toLowerCase();
+  if (exec === "bun" || exec === "bun.exe") return process.execPath;
+  return "bun";
+}
+function resolveCliInterpreter(jsEntry) {
+  try {
+    const firstLine = readFileSync(jsEntry, "utf8").split("\n", 1)[0] ?? "";
+    if (/\bbun\b/.test(firstLine)) return resolveBunCmd();
+  } catch {
+  }
+  return process.execPath;
+}
+class ProcessManagerClientTransport {
+  constructor(manager, id) {
+    this.manager = manager;
+    this.id = id;
+  }
+  get connected() {
+    return this.manager.isConnected(this.id);
+  }
+  async connect() {
+  }
+  async disconnect() {
+    await this.manager.shutdown(this.id);
+  }
+  send(command) {
+    this.manager.sendCommand(this.id, command);
+  }
+  onMessage(handler) {
+    this.manager.on(`event:${this.id}`, handler);
+    return () => this.manager.off(`event:${this.id}`, handler);
+  }
+  onDisconnect(_handler) {
+    return () => {
+    };
+  }
+}
+class AgentProcessManager extends EventEmitter {
+  processes = /* @__PURE__ */ new Map();
+  constructor() {
+    super();
+    this.setMaxListeners(100);
+    const cleanup = () => {
+      for (const [id] of this.processes) {
+        try {
+          this.shutdownSync(id);
+        } catch {
+        }
+      }
+    };
+    process.on("exit", cleanup);
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+  }
+  /**
+   * Spawn a `skaile serve` subprocess and connect via WebSocket transport.
+   * Resolves when the subprocess is ready and transport is connected.
+   */
+  async create(id, config) {
+    log.info(
+      `[${id}] Creating session \u2014 harness=${config.harness ?? "omp"} model=${config.model ?? "(registry default)"}`
+    );
+    log.debug(`[${id}]   projectDir=${config.projectDir}`);
+    if (this.processes.has(id)) {
+      log.info(`[${id}] Shutting down existing process`);
+      await this.shutdown(id);
+    }
+    if (config.systemPrompt) {
+      const skaileDir = join(config.projectDir, ".skaile");
+      if (!existsSync(skaileDir)) mkdirSync(skaileDir, { recursive: true });
+      const systemPromptFile = join(skaileDir, "system-prompt.md");
+      writeFileSync(systemPromptFile, config.systemPrompt);
+      log.debug(`[${id}] Wrote system prompt (${config.systemPrompt.length} chars)`);
+    }
+    const credentials = config.registry ? registryCredentialEnv(config.registry, { env: config.credentialEnv }) : { env: {}, deliveries: [] };
+    for (const delivery of credentials.deliveries) {
+      if (delivery.names.length > 0) {
+        log.debug(`[${id}]   ${delivery.providerId} credential from ${delivery.source}`);
+      } else if (delivery.error) {
+        log.warn(`[${id}]   ${delivery.providerId} credential not delivered: ${delivery.error}`);
+      }
+    }
+    const env = {
+      ...config.credentialEnv ?? process.env,
+      ...credentials.env,
+      ...config.env ?? {}
+    };
+    if (config.sshKeyPath) {
+      env.GIT_SSH_COMMAND = `ssh -i ${config.sshKeyPath} -o StrictHostKeyChecking=no`;
+    }
+    if (config.harnessSessionId) {
+      env.SKAILE_RESUME_SESSION_ID = config.harnessSessionId;
+      log.debug(`[${id}]   SKAILE_RESUME_SESSION_ID=${config.harnessSessionId}`);
+    }
+    if (config.wsAuthToken) env.SKAILE_WS_AUTH_TOKEN = config.wsAuthToken;
+    const skaileCmd = resolveSkaileCmd();
+    const interpreter = skaileCmd.endsWith(".js") ? resolveCliInterpreter(skaileCmd) : null;
+    const MAX_PORT_ATTEMPTS = 3;
+    let managed;
+    let transport;
+    let port = 0;
+    for (let attempt = 1; attempt <= MAX_PORT_ATTEMPTS; attempt++) {
+      port = await allocatePort();
+      log.debug(`[${id}] Allocated port ${port} (attempt ${attempt}/${MAX_PORT_ATTEMPTS})`);
+      const args = ["serve", "--project-dir", config.projectDir, "--port", String(port)];
+      if (config.host) args.push("--host", config.host);
+      if (config.harness) args.push("--harness", config.harness);
+      if (config.model) args.push("--model", config.model);
+      if (config.providers && config.providers.length > 0)
+        args.push("--providers", config.providers.join(","));
+      log.debug(
+        `[${id}] Spawning: ${interpreter ? `${interpreter} ${skaileCmd}` : skaileCmd} ${args.join(" ")}`
+      );
+      const child = interpreter ? spawn(interpreter, [skaileCmd, ...args], { env, stdio: ["pipe", "pipe", "pipe"] }) : spawn(skaileCmd, args, { env, stdio: ["pipe", "pipe", "pipe"] });
+      transport = new WebSocketClientTransport({
+        url: `ws://${dialHost(config.host)}:${port}`,
+        ...config.wsAuthToken ? { auth: config.wsAuthToken } : {},
+        reconnect: { maxAttempts: 3, baseMs: 1e3, maxMs: 1e4 },
+        onLog: (line) => log.debug(`[${id}] ${line}`)
+      });
+      managed = {
+        child,
+        port,
+        transport,
+        config,
+        status: "starting",
+        stderrBuffer: []
+      };
+      this.processes.set(id, managed);
+      child.stdout?.on("data", (chunk) => {
+        for (const line of chunk.toString().split("\n")) {
+          const trimmed = line.trim();
+          if (trimmed && !trimmed.includes("listening on port")) {
+            log.info(`[${id}] [stdout] ${trimmed}`);
+          }
+        }
+      });
+      child.stderr?.on("data", (chunk) => {
+        const line = chunk.toString().trim();
+        if (line) {
+          managed.stderrBuffer.push(line);
+          if (managed.stderrBuffer.length > 30) managed.stderrBuffer.shift();
+          log.warn(`[${id}] [stderr] ${line}`);
+        }
+      });
+      log.debug(`[${id}] Waiting for subprocess ready signal...`);
+      try {
+        await this.waitForReady(id, managed, 2e4);
+      } catch (err) {
+        const portConflict = managed.stderrBuffer.some((l) => l.includes("EADDRINUSE"));
+        try {
+          if (managed.child.exitCode === null) managed.child.kill("SIGKILL");
+        } catch {
+        }
+        this.processes.delete(id);
+        if (portConflict && attempt < MAX_PORT_ATTEMPTS) {
+          log.warn(`[${id}] Port ${port} already in use \u2014 retrying on a fresh port`);
+          continue;
+        }
+        throw err;
+      }
+      log.info(`[${id}] Subprocess ready on port ${port}`);
+      managed.child.on("exit", (code, signal) => {
+        const prev = managed.status;
+        managed.status = "stopped";
+        if (prev !== "stopped") {
+          log.warn(`[${id}] Process exited unexpectedly (code=${code}, signal=${signal})`);
+          const stderr = managed.stderrBuffer.slice(-5).join("\n");
+          if (stderr) log.debug(`[${id}] Last stderr: ${stderr}`);
+          this.emit(`error:${id}`, {
+            type: "error",
+            error: `Agent process exited (code=${code}, signal=${signal})${stderr ? `: ${stderr}` : ""}`
+          });
+        } else {
+          log.debug(`[${id}] Process exited cleanly (code=${code})`);
+        }
+        this.processes.delete(id);
+      });
+      break;
+    }
+    await transport.connect();
+    managed.status = "connected";
+    log.info(`[${id}] WebSocket connected`);
+    managed.unsubMessage = transport.onMessage((event) => {
+      if (event.type === "error") {
+        log.warn(`[${id}] \u2190 error: ${event.message}`);
+      } else {
+        log.info(`[${id}] \u2190 ${event.type}`);
+      }
+      this.emit(`event:${id}`, event);
+    });
+    managed.unsubDisconnect = transport.onDisconnect(() => {
+      if (managed.status === "connected") {
+        log.warn(`[${id}] WebSocket disconnected unexpectedly`);
+        managed.status = "disconnected";
+      }
+    });
+  }
+  /**
+   * Send a prompt to the agent subprocess.
+   */
+  async prompt(id, message) {
+    log.info(`[${id}] Sending prompt (${message.length} chars)`);
+    const managed = this.processes.get(id);
+    if (!managed?.transport.connected) {
+      throw new Error(`No active connection for session ${id}`);
+    }
+    managed.transport.send({ type: "prompt", prompt: message });
+  }
+  /**
+   * Cancel the current agent operation.
+   */
+  async cancel(id) {
+    log.info(`[${id}] Cancelling`);
+    const managed = this.processes.get(id);
+    if (managed?.transport.connected) {
+      managed.transport.send({ type: "cancel" });
+    }
+  }
+  /**
+   * Gracefully shut down a subprocess.
+   */
+  async shutdown(id) {
+    const managed = this.processes.get(id);
+    if (!managed) return;
+    log.info(`[${id}] Shutting down (port ${managed.port})`);
+    managed.status = "stopped";
+    managed.unsubMessage?.();
+    managed.unsubDisconnect?.();
+    await managed.transport.disconnect();
+    if (managed.child.exitCode === null) {
+      managed.child.kill("SIGTERM");
+      await new Promise((resolve2) => {
+        const timeout = setTimeout(() => {
+          try {
+            managed.child.kill("SIGKILL");
+          } catch {
+          }
+          resolve2();
+        }, 5e3);
+        managed.child.on("exit", () => {
+          clearTimeout(timeout);
+          resolve2();
+        });
+      });
+    }
+    this.processes.delete(id);
+  }
+  /**
+   * Check if a subprocess is connected and ready.
+   */
+  isConnected(id) {
+    const managed = this.processes.get(id);
+    return managed?.status === "connected" && managed.transport.connected;
+  }
+  /**
+   * Check if a session exists (regardless of connection state).
+   */
+  has(id) {
+    return this.processes.has(id);
+  }
+  /**
+   * Send any AgentCommand to the managed process.
+   * Used internally by ProcessManagerClientTransport.
+   */
+  sendCommand(id, command) {
+    const managed = this.processes.get(id);
+    if (!managed?.transport.connected) {
+      throw new Error(`No active connection for session ${id}`);
+    }
+    managed.transport.send(command);
+  }
+  /**
+   * Create an AgentClient for a managed session.
+   * Uses ProcessManagerClientTransport so there is no second subscription
+   * on the underlying WebSocket transport. Disposing the client will
+   * gracefully shut down the subprocess via manager.shutdown().
+   *
+   * Throws if the session does not exist. The session must be connected
+   * (isConnected() === true) before any commands can be sent.
+   */
+  createAgentClient(id) {
+    if (!this.processes.has(id)) {
+      throw new Error(`No managed session '${id}'`);
+    }
+    return new AgentClient(new ProcessManagerClientTransport(this, id));
+  }
+  // ── Internal ────────────────────────────────────────────────────────
+  shutdownSync(id) {
+    const managed = this.processes.get(id);
+    if (!managed) return;
+    managed.status = "stopped";
+    managed.unsubMessage?.();
+    managed.unsubDisconnect?.();
+    try {
+      managed.transport.disconnect();
+    } catch {
+    }
+    try {
+      managed.child.kill("SIGTERM");
+    } catch {
+    }
+    this.processes.delete(id);
+  }
+  waitForReady(id, managed, timeoutMs) {
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new Error(
+            `skaile serve did not become ready within ${timeoutMs}ms. stderr: ${managed.stderrBuffer.slice(-3).join(" | ")}`
+          )
+        );
+      }, timeoutMs);
+      const onData = (chunk) => {
+        const text = chunk.toString();
+        if (text.includes("listening on port")) {
+          clearTimeout(timer);
+          managed.child.stdout?.off("data", onData);
+          resolve2();
+        }
+      };
+      managed.child.stdout?.on("data", onData);
+      managed.child.on("exit", (code) => {
+        clearTimeout(timer);
+        managed.child.stdout?.off("data", onData);
+        reject(
+          new Error(
+            `skaile serve exited during startup (code=${code}). stderr: ${managed.stderrBuffer.join(" | ")}`
+          )
+        );
+      });
+    });
+  }
+}
+
+class ProcessManagerAdapter {
+  processManager = new AgentProcessManager();
+  emitter = new EventEmitter();
+  processKey = null;
+  status = "disconnected";
+  constructor() {
+    this.emitter.setMaxListeners(20);
+  }
+  async connect(config) {
+    this.processKey = config.projectDir;
+    await this.processManager.create(this.processKey, {
+      projectDir: config.projectDir,
+      harness: config.harness,
+      registry: config.registry,
+      providers: config.providers,
+      credentialEnv: config.credentialEnv,
+      model: config.model,
+      env: config.env,
+      systemPrompt: config.systemPrompt,
+      maxTurns: config.maxTurns,
+      agentDir: config.agentDir,
+      harnessSessionId: config.harnessSessionId,
+      host: config.host,
+      wsAuthToken: config.wsAuthToken
+    });
+    this.status = "idle";
+    this.processManager.on(`event:${this.processKey}`, (event) => {
+      this._pushEvent(event);
+      if (event.type === "status") {
+        const phase = event.phase;
+        if (phase === "thinking" || phase === "working") {
+          this.status = "running";
+        } else if (phase === "idle") {
+          this.status = "idle";
+        }
+      }
+      if (event.type === "finished" || event.type === "turn_end" || event.type === "agent_end") {
+        this.status = "idle";
+      }
+      if (event.type === "message_start" && event.message?.role === "assistant") {
+        this.status = "running";
+      }
+      if (event.type === "error") {
+        this.status = "error";
+      }
+    });
+    this.processManager.on(`error:${this.processKey}`, (err) => {
+      this.status = "error";
+      this._pushEvent({
+        type: "error",
+        error: err.error || String(err)
+      });
+    });
+  }
+  async sendCommand(command) {
+    if (!this.processKey || !this.processManager.isConnected(this.processKey)) {
+      throw new Error("ProcessManagerAdapter: not connected \u2014 call connect() first");
+    }
+    this.processManager.sendCommand(this.processKey, command);
+  }
+  async *listen() {
+    const queue = [];
+    let resolve = null;
+    let done = false;
+    const onEvent = (event) => {
+      queue.push(event);
+      resolve?.();
+      resolve = null;
+    };
+    const onDone = () => {
+      done = true;
+      resolve?.();
+      resolve = null;
+    };
+    this.emitter.on("_event", onEvent);
+    this.emitter.on("_done", onDone);
+    try {
+      while (true) {
+        while (queue.length > 0) {
+          yield queue.shift();
+        }
+        if (done) break;
+        await new Promise((res) => {
+          resolve = res;
+          if (queue.length > 0 || done) {
+            res();
+            resolve = null;
+          }
+        });
+      }
+    } finally {
+      this.emitter.off("_event", onEvent);
+      this.emitter.off("_done", onDone);
+    }
+  }
+  async abort() {
+    if (this.processKey && this.processManager.isConnected(this.processKey)) {
+      this.processManager.sendCommand(this.processKey, { type: "cancel" });
+      this.status = "idle";
+    }
+  }
+  isConnected() {
+    return !!this.processKey && this.processManager.isConnected(this.processKey);
+  }
+  getStatus() {
+    return this.status;
+  }
+  async disconnect() {
+    this.emitter.emit("_done");
+    if (this.processKey) {
+      await this.processManager.shutdown(this.processKey).catch(() => {
+      });
+      this.processKey = null;
+    }
+    this.status = "disconnected";
+  }
+  /**
+   * Internal: push an event into the async iterable queue.
+   * Exposed with underscore prefix for test injection.
+   */
+  _pushEvent(event) {
+    this.emitter.emit("_event", event);
+  }
+  /**
+   * Set a custom process key (used by apps that namespace keys as 'userId:slug:mode').
+   * Must be called before `connect()`.
+   */
+  setProcessKey(key) {
+    this.processKey = key;
+  }
+  /**
+   * Access the underlying AgentProcessManager for advanced use cases
+   * (e.g. createAgentClient() needed by SessionDispatcher construction).
+   */
+  getProcessManager() {
+    return this.processManager;
+  }
+}
+
+const registry = /* @__PURE__ */ new Map();
+registry.set("omp", () => new ProcessManagerAdapter());
+registry.set("claude-sdk", () => new ProcessManagerAdapter());
+function createAdapterForHarness(harness) {
+  const factory = registry.get(harness) ?? registry.get("omp");
+  return factory();
+}
+function registerHarness(name, factory) {
+  registry.set(name, factory);
+}
+function listRegisteredHarnesses() {
+  return Array.from(registry.keys());
+}
+
+class EventEmitterSubscriberTransport {
+  emitter = new EventEmitter();
+  /**
+   * Push an event to all listeners registered for this subscriber ID.
+   *
+   * Part of the `SubscriberTransport` interface — called by `SessionDispatcher`
+   * when the agent emits an event.
+   *
+   * @param subscriberId - ID of the subscriber connection to notify.
+   * @param event - Agent event to broadcast.
+   */
+  send(subscriberId, event) {
+    this.emitter.emit(subscriberId, event);
+  }
+  /**
+   * Remove all listeners for a subscriber ID.
+   *
+   * Part of the `SubscriberTransport` interface — called by `SessionDispatcher`
+   * when a subscriber disconnects or the session ends.
+   *
+   * @param subscriberId - ID of the subscriber whose listeners should be cleared.
+   */
+  remove(subscriberId) {
+    this.emitter.removeAllListeners(subscriberId);
+  }
+  /**
+   * Register a per-connection event handler and return an unsubscribe function.
+   *
+   * Not part of the `SubscriberTransport` interface — used directly by SSE route handlers.
+   *
+   * @param subscriberId - Unique identifier for this SSE connection.
+   * @param handler - Called for each agent event broadcast to this subscriber.
+   * @returns Cleanup function — call when the SSE connection closes.
+   */
+  listen(subscriberId, handler) {
+    this.emitter.on(subscriberId, handler);
+    return () => this.emitter.off(subscriberId, handler);
+  }
+}
+
+class JsonlMessageStore {
+  /**
+   * @param dir - Directory where per-session `.jsonl` files are stored.
+   *   The directory is created on first write if it does not exist.
+   */
+  constructor(dir) {
+    this.dir = dir;
+  }
+  /** Tail of this instance's serialised append chain; never rejects. */
+  tail = Promise.resolve();
+  filePath(sessionId) {
+    return join(this.dir, `${sessionId}.jsonl`);
+  }
+  /**
+   * Append a message to the session's JSONL file.
+   *
+   * Creates the file (and parent directory) if absent.
+   *
+   * Appends are chained on a per-instance tail promise, so overlapping calls are
+   * written in the order they were issued rather than racing each other's
+   * open/write/close. A failed write is neutralised for the chain but still
+   * rejected to its own caller, so one bad append does not poison the ones after it.
+   *
+   * @param message - Message to persist. `message.sessionId` determines the target file.
+   */
+  async append(message) {
+    const mine = this.tail.then(async () => {
+      await mkdir(this.dir, { recursive: true });
+      await appendFile(this.filePath(message.sessionId), `${JSON.stringify(message)}
+`);
+    });
+    this.tail = mine.catch(() => {
+    });
+    return mine;
+  }
+  /**
+   * Read messages for a session with optional pagination.
+   *
+   * Reads the full file on every call — acceptable for forge's short-lived sessions.
+   *
+   * @param sessionId - Session whose messages to retrieve.
+   * @param opts.before - Return only messages with `seq` less than this value.
+   * @param opts.limit - Return at most this many messages (tail semantics — most recent).
+   * @returns Ordered array of messages (oldest first within the result window).
+   */
+  async getMessages(sessionId, opts) {
+    let content;
+    try {
+      content = await readFile(this.filePath(sessionId), "utf-8");
+    } catch {
+      return [];
+    }
+    const parsed = [];
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        parsed.push(JSON.parse(line));
+      } catch {
+      }
+    }
+    let messages = parsed;
+    if (opts?.before !== void 0) {
+      messages = messages.filter((m) => m.seq < opts.before);
+    }
+    if (opts?.limit !== void 0) {
+      messages = messages.slice(-opts.limit);
+    }
+    return messages;
+  }
+  /**
+   * Return the sequence number of the most recent message in the session.
+   *
+   * Reads the whole JSONL file and takes its last non-empty line — see the
+   * class note on why re-reading is acceptable here.
+   *
+   * @param sessionId - Session to inspect.
+   * @returns `seq` of the last appended message, or `0` if the session has no
+   *   messages (or its last line is unreadable).
+   */
+  async getLatestSeq(sessionId) {
+    let content;
+    try {
+      content = await readFile(this.filePath(sessionId), "utf-8");
+    } catch {
+      return 0;
+    }
+    const lines = content.split("\n").filter((l) => l.trim());
+    if (lines.length === 0) return 0;
+    const lastLine = lines[lines.length - 1];
+    try {
+      const last = JSON.parse(lastLine ?? "");
+      return last.seq ?? 0;
+    } catch {
+      return 0;
+    }
+  }
+}
+
+class BaseAgentManager extends EventEmitter {
+  processManager = new AgentProcessManager();
+  constructor() {
+    super();
+    this.setMaxListeners(50);
+  }
+  // ── Core session creation ─────────────────────────────────────────────
+  /**
+   * Create a new ManagedSession: spawn subprocess, wire dispatcher, register event handler.
+   *
+   * This is the canonical "extract" from the `_createSession` methods in each app.
+   * The event handler below is the common core — apps extend via `onEvent()`.
+   *
+   * @param sessionId - The UUID for this session (resolved by the app).
+   */
+  async createManagedSession(sessionId) {
+    const config = await this.buildAdapterConfig(sessionId);
+    const processKey = this.buildProcessKey(sessionId);
+    await this.processManager.create(processKey, {
+      projectDir: config.projectDir,
+      harness: config.harness,
+      registry: config.registry,
+      providers: config.providers,
+      credentialEnv: config.credentialEnv,
+      model: config.model,
+      env: config.env,
+      systemPrompt: config.systemPrompt,
+      maxTurns: config.maxTurns,
+      agentDir: config.agentDir,
+      harnessSessionId: config.harnessSessionId,
+      host: config.host,
+      wsAuthToken: config.wsAuthToken
+    });
+    const messageStore = new JsonlMessageStore(this.getMessagesDir(sessionId));
+    const subscriberTransport = new EventEmitterSubscriberTransport();
+    const client = this.processManager.createAgentClient(processKey);
+    const session = {
+      sessionId,
+      dispatcher: new SessionDispatcher({
+        sessionId,
+        client,
+        store: messageStore,
+        transport: subscriberTransport
+      }),
+      subscriberTransport,
+      isStreaming: false,
+      error: null
+    };
+    await session.dispatcher.init();
+    const eventHandler = async (event) => {
+      if (event.type === "status") {
+        const phase = event.phase;
+        if (phase === "thinking" || phase === "working") {
+          session.isStreaming = true;
+        } else if (phase === "idle") {
+          session.isStreaming = false;
+        }
+      }
+      if (event.type === "finished" || event.type === "turn_end" || event.type === "agent_end") {
+        session.isStreaming = false;
+      }
+      if (event.type === "message_start" && event.message?.role === "assistant") {
+        session.isStreaming = true;
+      }
+      if (event.type === "error") {
+        session.error = event.error || event.message || String(event);
+        session.isStreaming = false;
+      }
+      const suppress = await this.onEvent(event, session, processKey);
+      if (suppress) return;
+      this.emit("event", event);
+    };
+    this.processManager.on(`event:${processKey}`, eventHandler);
+    session.removeEventHandler = () => this.processManager.off(`event:${processKey}`, eventHandler);
+    this.processManager.on(`error:${processKey}`, (err) => {
+      session.error = err.error || String(err);
+      session.isStreaming = false;
+      this.emit("event", {
+        type: "error",
+        error: session.error
+      });
+    });
+    await this.onSessionCreated(session);
+    return session;
+  }
+  /**
+   * App-specific event hook. Called for every agent event after common
+   * streaming/error tracking but before SSE fan-out.
+   *
+   * Return `true` to suppress the default `this.emit('event', event)` call.
+   * Default implementation: no-op, returns false.
+   *
+   * @example Override in forge-workspace to handle `capability_invoked`
+   * @example Override in forge-assistant to trigger consolidation on `finished`
+   */
+  async onEvent(_event, _session, _processKey) {
+    return false;
+  }
+  // ── Session teardown helpers ──────────────────────────────────────────
+  /**
+   * Tear down a session: unregister event handler, disconnect dispatcher.
+   */
+  teardownSession(session) {
+    session.removeEventHandler?.();
+    session.dispatcher.disconnect().catch(() => {
+    });
+  }
+  // ── Observable state helpers ──────────────────────────────────────────
+  /**
+   * Whether the given session is currently streaming.
+   * Returns false if the session does not exist.
+   * Override in subclasses that cache their session.
+   */
+  isSessionStreaming(_sessionId) {
+    return false;
+  }
+  /**
+   * Last error for the given session, or null.
+   * Override in subclasses that cache their session.
+   */
+  getSessionError(_sessionId) {
+    return null;
+  }
+}
+
+class FanoutSubscriberTransport {
+  emitter = new EventEmitter();
+  FANOUT_CHANNEL = "__fanout__";
+  constructor(maxListeners = 200) {
+    this.emitter.setMaxListeners(maxListeners);
+  }
+  /**
+   * Called by SessionDispatcher. Broadcasts to ALL subscribers (ignores subscriberId).
+   */
+  send(_subscriberId, event) {
+    this.emitter.emit(this.FANOUT_CHANNEL, event);
+  }
+  /**
+   * Called by SessionDispatcher on disconnect. No-op for fanout — subscribers
+   * manage their own cleanup via the unsubscribe function returned by subscribe().
+   */
+  remove(_subscriberId) {
+  }
+  /**
+   * Internal: register a handler for all broadcasted events.
+   * Returns an unsubscribe function.
+   */
+  _listen(handler) {
+    this.emitter.on(this.FANOUT_CHANNEL, handler);
+    return () => this.emitter.off(this.FANOUT_CHANNEL, handler);
+  }
+  /**
+   * Current count of listeners on the fanout channel.
+   */
+  get listenerCount() {
+    return this.emitter.listenerCount(this.FANOUT_CHANNEL);
+  }
+}
+class FanoutTransport {
+  /**
+   * The inner transport passed to SessionDispatcher.
+   * SessionDispatcher calls transport.send(subscriberId, event) for each
+   * registered subscriber. FanoutTransport overrides send() to broadcast
+   * to ALL connected subscribers, ignoring the subscriberId argument.
+   */
+  transport;
+  constructor() {
+    this.transport = new FanoutSubscriberTransport();
+  }
+  /**
+   * Register a new SSE connection.
+   *
+   * @param connectionId - Unique identifier for this browser connection (e.g. randomUUID()).
+   *   Used only for diagnostics — the fanout ignores it for routing.
+   * @param handler - Called for each agent event broadcast to all subscribers.
+   * @returns Unsubscribe function — call when the SSE connection closes.
+   */
+  subscribe(_connectionId, handler) {
+    return this.transport._listen(handler);
+  }
+  /**
+   * Returns the current count of active subscribers.
+   * Useful for diagnostics and health checks.
+   */
+  get subscriberCount() {
+    return this.transport.listenerCount;
+  }
+}
+
+export { AgentProcessManager, BaseAgentManager, EventEmitterSubscriberTransport, FanoutTransport, JsonlMessageStore, ProcessManagerAdapter, createAdapterForHarness, listRegisteredHarnesses, registerHarness };