@runuai/host 0.4.3 → 0.6.0

package/db/migrations/0009_host_agent_sessions.sql

@@ -0,0 +1,15 @@
+-- ADR-061: durable agent sessions. One row per (task, agent) tracking the
+-- live in-container runner and how far the host has consumed its outbox —
+-- the byte offset is what makes a host restart resume instead of respawn.
+CREATE TABLE `host_agent_sessions` (
+	`task_id` text NOT NULL,
+	`agent_id` text NOT NULL,
+	`session_dir` text NOT NULL,
+	`container_name` text NOT NULL,
+	`kind` text NOT NULL,
+	`outbox_offset` integer DEFAULT 0 NOT NULL,
+	`status` text DEFAULT 'running' NOT NULL,
+	`created_at` integer NOT NULL,
+	`updated_at` integer NOT NULL,
+	PRIMARY KEY(`task_id`, `agent_id`)
+);

package/db/migrations/meta/_journal.json

@@ -64,6 +64,13 @@
       "when": 1779900009000,
       "tag": "0008_host_mcp_connections",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1779900010000,
+      "tag": "0009_host_agent_sessions",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -121,6 +121,39 @@ export type NewHostProjectEnv = typeof hostProjectEnv.$inferInsert;
 // is sealed with the host master key in single-column `ct.nonce` base64 form
 // (same packing as host_project_env). The cloud only ever holds the non-secret
 // metadata; acks never echo secrets back.
+// ---------------------------------------------------------------------------
+// host_agent_sessions — ADR-061 durable agent sessions. One row per
+// (task, agent): where the live in-container runner's session dir is and how
+// far the host has consumed its outbox. The byte offset is what turns a host
+// restart into "resume tailing" instead of "kill and respawn"; attachability
+// itself is judged live off the runner's heartbeat file, not this row.
+// ---------------------------------------------------------------------------
+
+export const hostAgentSessions = sqliteTable(
+  "host_agent_sessions",
+  {
+    taskId: text("task_id").notNull(),
+    agentId: text("agent_id").notNull(),
+    // Host-side absolute path of the session dir (on the workspace mount,
+    // identical in-container — task-up bind-mounts the workspace at its own
+    // host path).
+    sessionDir: text("session_dir").notNull(),
+    containerName: text("container_name").notNull(),
+    kind: text("kind").notNull(), // "claude" | "codex" | ...
+    outboxOffset: integer("outbox_offset", { mode: "number" })
+      .notNull()
+      .default(0),
+    status: text("status").notNull().default("running"), // running|closed
+    createdAt: integer("created_at", { mode: "number" }).notNull(),
+    updatedAt: integer("updated_at", { mode: "number" }).notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.taskId, t.agentId] }),
+  }),
+);
+
+export type HostAgentSession = typeof hostAgentSessions.$inferSelect;
+
 export const mcpConnections = sqliteTable("host_mcp_connections", {
   id: text("id").primaryKey(), // cloud uai_mcp_connections id
   userId: text("user_id").notNull(),

package/lib/agents/claude.ts

@@ -21,7 +21,7 @@
  */
 
 import { newId } from "../ulid";
-import { dockerExecArgs, LineProcess } from "./proc";
+import { createAgentTransport, type LineTransport } from "./transport";
 import { register } from "./registry";
 import type {
   AgentEvent,
@@ -187,17 +187,28 @@ const CLAUDE_ARGS = [
   // sandbox. Without this, stream-json has no interactive approver and
   // every Write/Bash silently self-denies.
   "--dangerously-skip-permissions",
+  // MCP servers come from the uai-managed file, EXPLICITLY (ADR-057/061).
+  // Discovered project .mcp.json servers sit behind a per-server approval
+  // that headless --print can never answer ("⏸ Pending approval"), which
+  // silently loaded a stale subset. --mcp-config bypasses the approval
+  // gate; --strict-mcp-config keeps stray host-copied user configs out.
+  // setupMcpTaskConfig always writes this file (empty when no connections)
+  // before sessions spawn.
+  "--mcp-config",
+  "/workspace/.mcp.json",
+  "--strict-mcp-config",
 ];
 
 export class ClaudeSession implements AgentSession {
   readonly agentId: string;
   readonly kind: AgentKind = "claude";
 
-  private readonly proc: LineProcess;
+  private readonly proc: LineTransport;
   private readonly handlers = new Set<AgentEventHandler>();
   private closed = false;
 
   constructor(args: {
+    taskId: string;
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
@@ -231,16 +242,20 @@ export class ClaudeSession implements AgentSession {
     // it needs CLAUDE_CODE_OAUTH_TOKEN (from `claude setup-token`) or an
     // API key. These live in the host-agent's env (never the cloud, ADR-015);
     // only ones actually set are forwarded.
-    const { command, args: argv } = dockerExecArgs(
-      args.containerName,
-      "claude",
+    // ADR-061: durable by default — the CLI is owned by an in-container
+    // runner and survives host restarts (attach resumes it); legacy pipes
+    // behind UAI_DURABLE_SESSIONS=0. Claude is host-side stateless, so a
+    // live runner can be re-attached (allowAttach).
+    this.proc = createAgentTransport({
+      taskId: args.taskId,
+      agentId: this.agentId,
+      containerName: args.containerName,
+      cli: "claude",
       cliArgs,
-      ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
-      args.agentEnv ?? {},
-    );
-    this.proc = new LineProcess({
-      command,
-      args: argv,
+      passEnv: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+      explicitEnv: args.agentEnv ?? {},
+      allowAttach: true,
+      kind: "claude",
       debugLabel: `claude:${this.agentId}`,
     });
     this.proc.onLine((line) => {
@@ -349,6 +364,6 @@ register({
         process.env.ANTHROPIC_API_KEY ||
         process.env.ANTHROPIC_AUTH_TOKEN,
     ),
-  create: async ({ agent, containerName, systemPreamble, agentEnv }) =>
-    new ClaudeSession({ agent, containerName, systemPreamble, agentEnv }),
+  create: async ({ taskId, agent, containerName, systemPreamble, agentEnv }) =>
+    new ClaudeSession({ taskId, agent, containerName, systemPreamble, agentEnv }),
 });

package/lib/agents/codex.ts

@@ -33,7 +33,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { newId } from "../ulid";
-import { dockerExecArgs, LineProcess } from "./proc";
+import { createAgentTransport, type LineTransport } from "./transport";
 import { register } from "./registry";
 import type {
   AgentEvent,
@@ -213,7 +213,7 @@ export class CodexSession implements AgentSession {
   readonly agentId: string;
   readonly kind: AgentKind = "codex";
 
-  private readonly proc: LineProcess;
+  private readonly proc: LineTransport;
   private readonly handlers = new Set<AgentEventHandler>();
   private readonly systemPreamble: string;
   private closed = false;
@@ -231,6 +231,7 @@ export class CodexSession implements AgentSession {
   private readonly ready: Promise<void>;
 
   constructor(args: {
+    taskId: string;
     agent: RosterAgent;
     containerName: string;
     systemPreamble: string;
@@ -251,16 +252,22 @@ export class CodexSession implements AgentSession {
       codexArgs.push("-c", `model_reasoning_effort=${args.agent.effort}`);
     }
     codexArgs.push("app-server");
-    const { command, args: argv } = dockerExecArgs(
-      args.containerName,
-      "codex",
-      codexArgs,
-      [],
-      args.agentEnv ?? {},
-    );
-    this.proc = new LineProcess({
-      command,
-      args: argv,
+    // ADR-061: the CLI is owned by an in-container runner (durable across
+    // host restarts); legacy pipes behind UAI_DURABLE_SESSIONS=0. Codex
+    // re-handshakes per host process (initialize + thread/start live in this
+    // object), so a leftover runner is never attached — allowAttach:false
+    // stops it and spawns fresh. Its final output before the stop still
+    // reaches the cloud via the outbox.
+    this.proc = createAgentTransport({
+      taskId: args.taskId,
+      agentId: this.agentId,
+      containerName: args.containerName,
+      cli: "codex",
+      cliArgs: codexArgs,
+      passEnv: [],
+      explicitEnv: args.agentEnv ?? {},
+      allowAttach: false,
+      kind: "codex",
       debugLabel: `codex:${this.agentId}`,
     });
     this.proc.onLine((line) => this.onLine(line));
@@ -538,6 +545,6 @@ register({
     existsSync(
       join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".codex", "auth.json"),
     ),
-  create: async ({ agent, containerName, systemPreamble, agentEnv }) =>
-    new CodexSession({ agent, containerName, systemPreamble, agentEnv }),
+  create: async ({ taskId, agent, containerName, systemPreamble, agentEnv }) =>
+    new CodexSession({ taskId, agent, containerName, systemPreamble, agentEnv }),
 });

package/lib/agents/durable-proc.ts

@@ -0,0 +1,306 @@
+/**
+ * DurableProcess (ADR-061) — LineProcess's durable twin. Instead of holding
+ * the agent CLI's pipes, it talks to the in-container runner
+ * (runner/runner.mjs) through two append-only JSONL files on the
+ * task-workspace bind mount:
+ *
+ *   writeLine()  → append to <sessionDir>/inbox.jsonl
+ *   onLine()     ← poll-tail <sessionDir>/outbox.jsonl from a byte offset
+ *
+ * The CLI's lifetime is decoupled from this object: dropping it (host
+ * restart) leaves the runner and CLI running; `attach()` with the persisted
+ * outbox offset resumes exactly where consumption stopped. `close()` is the
+ * real teardown — it sends the runner a stop control.
+ *
+ * Exit is observed via the runner's `{"__uai":"exit"}` meta line, with a
+ * stale-heartbeat check as the backstop for a killed container. Meta lines
+ * never reach onLine handlers — adapters see the same protocol stream
+ * LineProcess gave them.
+ */
+
+import { spawn } from "node:child_process";
+import {
+  closeSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  promises as fsp,
+  readSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExitHandler, LineHandler } from "./proc";
+
+const POLL_MS = 75;
+/** Runner beats every 5 s; 25 s of silence without an exit meta = dead. */
+const HEARTBEAT_STALE_MS = 25_000;
+/** After close(), how long to wait for the exit meta before giving up. */
+const CLOSE_GRACE_MS = 8_000;
+
+/** Host-side absolute path of the bundled in-container runner script. */
+export function runnerScriptPath(): string {
+  return fileURLToPath(new URL("../../runner/runner.mjs", import.meta.url));
+}
+
+export interface DurableProcessOptions {
+  /** Session dir as seen FROM THE HOST (on the workspace bind mount). */
+  hostSessionDir: string;
+  /**
+   * Command that launches the runner (e.g. `docker exec -d … node
+   * /opt/uai/runner.mjs <containerSessionDir> -- claude …`). Omit to ATTACH
+   * to a runner that is already alive (boot reconciliation).
+   */
+  spawnCommand?: { command: string; args: string[] };
+  /** Resume consumption from this outbox byte offset (attach path). */
+  initialOutboxOffset?: number;
+  /** Called after each poll batch whose lines were delivered — persist this
+   *  offset so a host restart resumes here instead of replaying. */
+  onOffsetAdvance?: (offset: number) => void;
+  /** Called the moment close() is requested (before the runner has actually
+   *  died) — lets the owner mark the session unattachable immediately, so a
+   *  re-create during the teardown grace window spawns fresh instead of
+   *  attaching to a dying runner. */
+  onCloseRequested?: () => void;
+  /** Mirrors LineProcess: log raw traffic when UAI_DEBUG_AGENTS is set. */
+  debugLabel?: string;
+}
+
+interface RunnerMeta {
+  __uai: string;
+  code?: number | null;
+  stderrTail?: string;
+}
+
+export class DurableProcess {
+  private readonly dir: string;
+  private readonly outboxPath: string;
+  private readonly inboxPath: string;
+  private readonly heartbeatPath: string;
+
+  private readonly lineHandlers = new Set<LineHandler>();
+  private readonly exitHandlers = new Set<ExitHandler>();
+
+  private offset: number;
+  private lineBuf = "";
+  private stderrBuf = "";
+  private closed = false;
+  private detached = false;
+  private sawSpawnMeta = false;
+  private readonly startedAt = Date.now();
+  private poller: ReturnType<typeof setInterval> | null = null;
+  private closeTimer: ReturnType<typeof setTimeout> | null = null;
+  private inboxChain: Promise<void> = Promise.resolve();
+  private readonly onOffsetAdvance: ((offset: number) => void) | null;
+  private readonly onCloseRequested: (() => void) | null;
+  private readonly debug: string | null;
+
+  constructor(opts: DurableProcessOptions) {
+    this.dir = opts.hostSessionDir;
+    this.outboxPath = join(this.dir, "outbox.jsonl");
+    this.inboxPath = join(this.dir, "inbox.jsonl");
+    this.heartbeatPath = join(this.dir, "heartbeat");
+    this.offset = opts.initialOutboxOffset ?? 0;
+    this.onOffsetAdvance = opts.onOffsetAdvance ?? null;
+    this.onCloseRequested = opts.onCloseRequested ?? null;
+    this.debug =
+      opts.debugLabel && process.env.UAI_DEBUG_AGENTS ? opts.debugLabel : null;
+
+    mkdirSync(this.dir, { recursive: true });
+
+    if (opts.spawnCommand) {
+      if (this.debug) {
+        this.log(
+          `spawn: ${opts.spawnCommand.command} ${opts.spawnCommand.args.join(" ")}`,
+        );
+      }
+      const child = spawn(opts.spawnCommand.command, opts.spawnCommand.args, {
+        stdio: ["ignore", "ignore", "pipe"],
+      });
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (chunk: string) => {
+        this.stderrBuf = (this.stderrBuf + chunk).slice(-8192);
+      });
+      // `docker exec -d` exits 0 immediately on success; non-zero means the
+      // runner never started (bad container, bad mount) — fail loudly now.
+      child.on("exit", (code) => {
+        if (code !== null && code !== 0) this.finish(null);
+      });
+      child.on("error", () => this.finish(null));
+      child.unref();
+    } else {
+      this.sawSpawnMeta = true; // attach: the runner pre-exists
+    }
+
+    this.poller = setInterval(() => this.poll(), POLL_MS);
+  }
+
+  private log(msg: string): void {
+    console.error(`[uai-agent ${this.debug}] ${msg}`);
+  }
+
+  // ---- outbox tail ---------------------------------------------------------
+
+  private poll(): void {
+    if (this.closed || this.detached) return;
+    let fd: number;
+    try {
+      fd = openSync(this.outboxPath, "r");
+    } catch {
+      this.checkLiveness();
+      return; // outbox not created yet
+    }
+    const before = this.offset;
+    try {
+      const size = fstatSync(fd).size;
+      while (this.offset < size) {
+        const len = Math.min(size - this.offset, 256 * 1024);
+        const buf = Buffer.alloc(len);
+        const read = readSync(fd, buf, 0, len, this.offset);
+        if (read <= 0) break;
+        this.offset += read;
+        this.lineBuf += buf.toString("utf8", 0, read);
+        this.drainLines();
+      }
+    } finally {
+      closeSync(fd);
+    }
+    if (this.offset !== before && this.onOffsetAdvance && !this.closed) {
+      try {
+        this.onOffsetAdvance(this.offset);
+      } catch {
+        // Persistence hiccup — the next batch retries with a larger offset.
+      }
+    }
+    this.checkLiveness();
+  }
+
+  private drainLines(): void {
+    let nl: number;
+    while ((nl = this.lineBuf.indexOf("\n")) >= 0) {
+      const line = this.lineBuf.slice(0, nl).trim();
+      this.lineBuf = this.lineBuf.slice(nl + 1);
+      if (line.length === 0) continue;
+      if (line.startsWith('{"__uai"')) {
+        this.handleMeta(line);
+        continue;
+      }
+      if (this.debug) this.log(`<- ${line.slice(0, 1000)}`);
+      for (const h of this.lineHandlers) {
+        try {
+          h(line);
+        } catch {
+          // A broken handler must not wedge the tail loop.
+        }
+      }
+    }
+  }
+
+  private handleMeta(line: string): void {
+    let meta: RunnerMeta;
+    try {
+      meta = JSON.parse(line) as RunnerMeta;
+    } catch {
+      return;
+    }
+    if (meta.__uai === "spawn") {
+      this.sawSpawnMeta = true;
+    } else if (meta.__uai === "exit") {
+      if (typeof meta.stderrTail === "string" && meta.stderrTail) {
+        this.stderrBuf = meta.stderrTail.slice(-8192);
+      }
+      if (this.debug) this.log(`exit meta: code ${meta.code ?? null}`);
+      this.finish(typeof meta.code === "number" ? meta.code : null);
+    }
+  }
+
+  /** Backstop: no exit meta, but the runner stopped beating → it's gone. */
+  private checkLiveness(): void {
+    const path = this.sawSpawnMeta ? this.heartbeatPath : null;
+    if (!path) {
+      // Runner never wrote anything; give the spawn a grace window.
+      if (Date.now() - this.startedAt > HEARTBEAT_STALE_MS) this.finish(null);
+      return;
+    }
+    try {
+      const age = Date.now() - statSync(path).mtimeMs;
+      if (age > HEARTBEAT_STALE_MS) this.finish(null);
+    } catch {
+      if (Date.now() - this.startedAt > HEARTBEAT_STALE_MS) this.finish(null);
+    }
+  }
+
+  private finish(code: number | null): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.poller) clearInterval(this.poller);
+    if (this.closeTimer) clearTimeout(this.closeTimer);
+    for (const h of this.exitHandlers) h(code);
+  }
+
+  // ---- LineProcess-compatible surface ---------------------------------------
+
+  onLine(handler: LineHandler): void {
+    this.lineHandlers.add(handler);
+  }
+
+  onExit(handler: ExitHandler): void {
+    this.exitHandlers.add(handler);
+  }
+
+  /** Serialise `value` as one JSONL line appended to the runner's inbox. */
+  writeLine(value: unknown): void {
+    if (this.closed || this.detached) return;
+    const json = JSON.stringify(value);
+    if (this.debug) this.log(`-> ${json.slice(0, 1000)}`);
+    // Chain appends so concurrent writes can't interleave bytes.
+    this.inboxChain = this.inboxChain
+      .then(() => fsp.appendFile(this.inboxPath, `${json}\n`))
+      .catch(() => {
+        // Disk error — liveness checks will surface a dead session.
+      });
+  }
+
+  get stderrTail(): string {
+    return this.stderrBuf;
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  /** Consumed-outbox byte offset — persist this to survive host restarts. */
+  get outboxOffset(): number {
+    return this.offset;
+  }
+
+  /**
+   * Stop consuming WITHOUT touching the runner — the host-restart path in
+   * miniature (a replaced consumer, a shutting-down host). The CLI lives on;
+   * a later attach() resumes from the persisted offset.
+   */
+  detach(): void {
+    if (this.detached || this.closed) return;
+    this.detached = true;
+    if (this.poller) clearInterval(this.poller);
+    if (this.closeTimer) clearTimeout(this.closeTimer);
+  }
+
+  /** Real teardown: ask the runner to stop its CLI, then observe the exit. */
+  async close(): Promise<void> {
+    if (this.closed || this.detached) return;
+    try {
+      this.onCloseRequested?.();
+    } catch {
+      // Bookkeeping only — never blocks the teardown itself.
+    }
+    try {
+      await this.inboxChain;
+      await fsp.appendFile(this.inboxPath, '{"__uai":"stop"}\n');
+    } catch {
+      // Inbox unwritable — fall through to the grace timer.
+    }
+    this.closeTimer = setTimeout(() => this.finish(null), CLOSE_GRACE_MS);
+  }
+}