@runuai/host 0.9.14 → 0.9.43

package/lib/agents/proc.ts

@@ -1,125 +1,139 @@
-/**
- * LineProcess — a child process whose stdout is consumed as
- * newline-delimited text (one JSON value per line).
- *
- * Both real agent adapters (ClaudeSession, CodexSession) drive a CLI
- * running *inside the task container* (ADR-010) via
- * `docker exec -i task-<id>-app-1 <cli> …`. That CLI speaks
- * newline-delimited JSON over stdio — Claude's stream-json, Codex's
- * JSON-RPC. This class owns the mechanics shared by both: spawn,
- * line-buffer stdout, capture stderr, write lines to stdin, tear down.
- *
- * It is deliberately protocol-agnostic — it knows nothing about
- * stream-json or JSON-RPC. The adapters layer that on top.
- */
+/** Provider-backed process adapters shared by the agent protocols. */
 
-import { spawn, type ChildProcess } from "node:child_process";
-
-export interface LineProcessOptions {
-  /** Executable — almost always "docker". */
-  command: string;
-  /** Args — e.g. ["exec", "-i", "task-…-app-1", "claude", …]. */
-  args: string[];
-  /**
-   * When set *and* `UAI_DEBUG_AGENTS` is truthy in the environment,
-   * spawn / raw stdio / exit are logged to the server console with
-   * this label — the way to see what an agent CLI is actually doing.
-   */
-  debugLabel?: string;
-}
+import { EventEmitter } from "node:events";
+
+import type {
+  TaskEnvironmentAgentSessionSurface,
+  TaskEnvironmentProcess,
+  TaskEnvironmentSessionRequest,
+} from "../task-environment/types";
 
 export type LineHandler = (line: string) => void;
 export type ExitHandler = (code: number | null) => void;
 
 /** How much trailing stderr to retain for error reporting. */
 const STDERR_CAP = 8 * 1024;
+/** Maximum unread stdout+stderr retained by a provider for an agent process. */
+export const AGENT_SESSION_OUTPUT_BUFFER_BYTES = 1024 * 1024;
 
-export class LineProcess {
-  private readonly child: ChildProcess;
+/**
+ * Line-oriented adapter over the provider-neutral environment
+ * stream. Startup may be asynchronous, so writes are serialized behind the
+ * provider's spawn promise without exposing a container command to callers.
+ */
+export class EnvironmentLineProcess {
+  private readonly processPromise: Promise<TaskEnvironmentProcess>;
+  private process: TaskEnvironmentProcess | null = null;
   private stdoutBuf = "";
   private stderrBuf = "";
   private readonly lineHandlers = new Set<LineHandler>();
   private readonly exitHandlers = new Set<ExitHandler>();
+  private inputChain: Promise<void> = Promise.resolve();
   private closed = false;
+  private finished = false;
+  private exitCode: number | null = null;
   private readonly debug: string | null;
 
-  constructor(opts: LineProcessOptions) {
+  constructor(opts: {
+    environment: TaskEnvironmentAgentSessionSurface;
+    request: TaskEnvironmentSessionRequest;
+    debugLabel?: string;
+  }) {
     this.debug =
       opts.debugLabel && process.env.UAI_DEBUG_AGENTS ? opts.debugLabel : null;
-    if (this.debug) {
-      this.log(`spawn: ${opts.command} ${opts.args.join(" ")}`);
-    }
-
-    this.child = spawn(opts.command, opts.args, {
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-
-    this.child.stdout?.setEncoding("utf8");
-    this.child.stdout?.on("data", (chunk: string) => this.onStdout(chunk));
+    if (this.debug) this.log(`spawn: ${opts.request.argv.join(" ")}`);
+    this.processPromise = opts.environment.spawnSession(opts.request);
+    void this.consume();
+  }
 
-    this.child.stderr?.setEncoding("utf8");
-    this.child.stderr?.on("data", (chunk: string) => {
-      // Keep only the tail — stderr can be noisy, we want the last words.
-      this.stderrBuf = (this.stderrBuf + chunk).slice(-STDERR_CAP);
-      if (this.debug) this.log(`stderr: ${chunk.trimEnd()}`);
-    });
+  private log(message: string): void {
+    console.error(`[uai-agent ${this.debug}] ${message}`);
+  }
 
-    this.child.on("exit", (code) => this.finish(code));
-    this.child.on("error", (err) => {
-      if (this.debug) this.log(`spawn error: ${err.message}`);
+  private async consume(): Promise<void> {
+    try {
+      const process = await this.processPromise;
+      this.process = process;
+      const stdout = this.consumeStdout(process.stdout);
+      const stderr = this.consumeStderr(process.stderr);
+      const exit = await process.completion;
+      await Promise.allSettled([stdout, stderr]);
+      this.finish(exit.exitCode);
+    } catch (error) {
+      this.stderrBuf = (
+        this.stderrBuf +
+        (error instanceof Error ? error.message : String(error))
+      ).slice(-STDERR_CAP);
       this.finish(null);
-    });
+    }
   }
 
-  private log(msg: string): void {
-    console.error(`[uai-agent ${this.debug}] ${msg}`);
+  private async consumeStdout(stream: AsyncIterable<Uint8Array>): Promise<void> {
+    for await (const chunk of stream) this.onStdout(Buffer.from(chunk).toString("utf8"));
   }
 
-  private finish(code: number | null): void {
-    if (this.closed) return;
-    this.closed = true;
-    if (this.debug) this.log(`exit: code ${code}`);
-    for (const h of this.exitHandlers) h(code);
+  private async consumeStderr(stream: AsyncIterable<Uint8Array>): Promise<void> {
+    for await (const chunk of stream) {
+      const text = Buffer.from(chunk).toString("utf8");
+      this.stderrBuf = (this.stderrBuf + text).slice(-STDERR_CAP);
+      if (this.debug) this.log(`stderr: ${text.trimEnd()}`);
+    }
   }
 
-  /** Split the rolling buffer on newlines; emit each complete line. */
   private onStdout(chunk: string): void {
     this.stdoutBuf += chunk;
-    let nl: number;
-    while ((nl = this.stdoutBuf.indexOf("\n")) >= 0) {
-      const line = this.stdoutBuf.slice(0, nl).trim();
-      this.stdoutBuf = this.stdoutBuf.slice(nl + 1);
-      if (line.length === 0) continue;
+    let newline: number;
+    while ((newline = this.stdoutBuf.indexOf("\n")) >= 0) {
+      const line = this.stdoutBuf.slice(0, newline).trim();
+      this.stdoutBuf = this.stdoutBuf.slice(newline + 1);
+      if (!line) continue;
       if (this.debug) this.log(`<- ${line.slice(0, 1000)}`);
-      for (const h of this.lineHandlers) {
+      for (const handler of this.lineHandlers) {
         try {
-          h(line);
+          handler(line);
         } catch {
-          // A broken handler must not wedge the read loop.
+          // A broken protocol handler must not wedge stream consumption.
         }
       }
     }
   }
 
-  /** Subscribe to complete stdout lines. */
+  private finish(code: number | null): void {
+    if (this.finished) return;
+    this.finished = true;
+    this.closed = true;
+    this.exitCode = code;
+    if (this.debug) this.log(`exit: code ${code}`);
+    for (const handler of this.exitHandlers) handler(code);
+  }
+
   onLine(handler: LineHandler): void {
     this.lineHandlers.add(handler);
   }
 
-  /** Subscribe to process exit. `code` is null on spawn error. */
   onExit(handler: ExitHandler): void {
     this.exitHandlers.add(handler);
+    if (this.finished) queueMicrotask(() => handler(this.exitCode));
   }
 
-  /** Serialise `value` as JSON and write it as one newline-delimited line. */
   writeLine(value: unknown): void {
     if (this.closed) return;
     const json = JSON.stringify(value);
     if (this.debug) this.log(`-> ${json.slice(0, 1000)}`);
-    this.child.stdin?.write(`${json}\n`);
+    this.inputChain = this.inputChain
+      .then(async () => {
+        const process = await this.processPromise;
+        await process.write(Buffer.from(`${json}\n`));
+      })
+      .catch((error: unknown) => {
+        this.stderrBuf = (
+          this.stderrBuf +
+          (error instanceof Error ? error.message : String(error))
+        ).slice(-STDERR_CAP);
+        this.finish(null);
+      });
   }
 
-  /** Last few KB of stderr — surfaced in error events. */
   get stderrTail(): string {
     return this.stderrBuf;
   }
@@ -128,54 +142,75 @@ export class LineProcess {
     return this.closed;
   }
 
-  /** Terminate the process. Idempotent. */
   async close(): Promise<void> {
-    if (this.closed) {
-      // Already exited — nothing to kill.
-      return;
-    }
+    if (this.closed) return;
     try {
-      this.child.stdin?.end();
+      const process = this.process ?? (await this.processPromise);
+      await process.closeInput().catch(() => {});
+      await process.terminate("SIGTERM").catch(() => {});
     } catch {
-      // stdin may already be gone.
+      // Startup already failed; consume() owns the terminal notification.
     }
-    this.child.kill("SIGTERM");
   }
 }
 
-/**
- * Build the `docker exec` argv that runs `cli …cliArgs` inside a task
- * container. `-i` keeps stdin open for the bidirectional session.
- */
-export function dockerExecArgs(
-  containerName: string,
-  cli: string,
-  cliArgs: string[],
-  /**
-   * Env var names to forward from the host-agent process into the
-   * `docker exec` (as `-e NAME`, value taken from the host-agent's own
-   * environment). Used to pass host-resident AI credentials — e.g.
-   * `CLAUDE_CODE_OAUTH_TOKEN` for headless Claude subscription auth — into
-   * the container without baking them into the image or sending them to the
-   * cloud (ADR-015). Only vars actually set on the host are forwarded.
-   */
-  passEnv: string[] = [],
-  /**
-   * Explicit per-exec env values (`-e NAME=value`) — used for per-agent values
-   * that don't live in the host's own env, e.g. the agent's task-scoped
-   * `UAI_TASK_TOKEN` (ADR-048). Values are argv, never a shell string.
-   */
-  explicitEnv: Record<string, string> = {},
-): { command: string; args: string[] } {
-  const envArgs: string[] = [];
-  for (const name of passEnv) {
-    if (process.env[name]) envArgs.push("-e", name);
-  }
-  for (const [name, value] of Object.entries(explicitEnv)) {
-    envArgs.push("-e", `${name}=${value}`);
+/** Minimal ChildProcess-shaped view retained by the one-shot adapters. */
+export interface AgentEnvironmentProcess {
+  readonly stdout: EventEmitter;
+  readonly stderr: EventEmitter;
+  on(event: "exit", listener: (code: number | null) => void): this;
+  on(event: "error", listener: (error: Error) => void): this;
+  kill(signal?: "SIGTERM" | "SIGKILL"): boolean;
+}
+
+/** Bridge a provider stream into the event shape used by one-shot adapters. */
+export function spawnEnvironmentProcess(
+  environment: TaskEnvironmentAgentSessionSurface,
+  request: TaskEnvironmentSessionRequest,
+): AgentEnvironmentProcess {
+  class EnvironmentProcess extends EventEmitter implements AgentEnvironmentProcess {
+    readonly stdout = new EventEmitter();
+    readonly stderr = new EventEmitter();
+    private process: TaskEnvironmentProcess | null = null;
+    private readonly processPromise: Promise<TaskEnvironmentProcess>;
+
+    constructor() {
+      super();
+      this.processPromise = environment.spawnSession(request);
+      void this.consume();
+    }
+
+    private async consume(): Promise<void> {
+      try {
+        const process = await this.processPromise;
+        this.process = process;
+        const stdout = pumpEnvironmentStream(process.stdout, this.stdout);
+        const stderr = pumpEnvironmentStream(process.stderr, this.stderr);
+        const exit = await process.completion;
+        await Promise.allSettled([stdout, stderr]);
+        this.emit("exit", exit.exitCode);
+      } catch (error) {
+        this.emit(
+          "error",
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    }
+
+    kill(signal: "SIGTERM" | "SIGKILL" = "SIGTERM"): boolean {
+      const process = this.process;
+      if (process) void process.terminate(signal).catch(() => {});
+      else void this.processPromise.then((pending) => pending.terminate(signal)).catch(() => {});
+      return true;
+    }
   }
-  return {
-    command: "docker",
-    args: ["exec", "-i", ...envArgs, containerName, cli, ...cliArgs],
-  };
+
+  return new EnvironmentProcess();
+}
+
+async function pumpEnvironmentStream(
+  stream: AsyncIterable<Uint8Array>,
+  target: EventEmitter,
+): Promise<void> {
+  for await (const chunk of stream) target.emit("data", Buffer.from(chunk));
 }

package/lib/agents/transport.ts

@@ -2,7 +2,7 @@
  * Agent transport selection (ADR-061). Adapters call createAgentTransport()
  * where they used to build a LineProcess directly; it returns either:
  *
- *  - legacy pipes (`docker exec -i <cli>`, LineProcess) when
+ *  - provider-owned interactive pipes when
  *    UAI_DURABLE_SESSIONS=0, or
  *  - the durable path: an in-container runner owning the CLI, driven through
  *    inbox/outbox files on the workspace mount (DurableProcess).
@@ -17,9 +17,8 @@
  * via its inbox first.
  *
  * The runner script is COPIED into each session dir (not bind-mounted):
- * every existing container already sees the workspace at its identical host
- * path, so durable sessions work for containers created before this
- * feature, and each spawn ships the runner version matching this host.
+ * the task environment sees the workspace at its provider path, so each
+ * durable spawn ships the runner version matching this host.
  */
 
 import {
@@ -37,8 +36,15 @@ import { and, eq } from "drizzle-orm";
 
 import { getDb, schema } from "../db";
 import { taskWorkspaceDir } from "../env";
+import { requireContainerRuntimeOperational } from "../runtime-guard";
+import type { TaskEnvironmentAgentSessionSurface } from "../task-environment/types";
 import { DurableProcess, runnerScriptPath } from "./durable-proc";
-import { LineProcess, dockerExecArgs, type ExitHandler, type LineHandler } from "./proc";
+import {
+  AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+  EnvironmentLineProcess,
+  type ExitHandler,
+  type LineHandler,
+} from "./proc";
 
 /** The shared surface adapters program against (LineProcess's shape). */
 export interface LineTransport {
@@ -53,13 +59,13 @@ export interface LineTransport {
 export interface AgentTransportOptions {
   taskId: string;
   agentId: string;
-  containerName: string;
-  /** CLI + args exactly as they'd follow `docker exec -i <container>`. */
+  environment: TaskEnvironmentAgentSessionSurface;
+  /** CLI + literal argv as observed inside the task environment. */
   cli: string;
   cliArgs: string[];
-  /** Env names forwarded from the host's own env (`-e NAME`). */
+  /** Env names forwarded from the host's own environment. */
   passEnv?: string[];
-  /** Explicit per-exec env values (`-e NAME=value`). */
+  /** Explicit per-session environment values. */
   explicitEnv?: Record<string, string>;
   /**
    * Whether a live runner from a previous host process may be attached to.
@@ -100,16 +106,13 @@ function durableEnabled(): boolean {
 }
 
 export function createAgentTransport(opts: AgentTransportOptions): LineTransport {
+  // Session creation can happen after channel/task lifecycle queues drain, well
+  // after the command-level runtime preflight. Recheck at the actual attach or
+  // spawn boundary so a cached ready verdict cannot launch container work.
+  requireContainerRuntimeOperational();
   if (!durableEnabled()) {
     clearCurrentSession(opts.taskId, opts.agentId);
-    const { command, args } = dockerExecArgs(
-      opts.containerName,
-      opts.cli,
-      opts.cliArgs,
-      opts.passEnv ?? [],
-      opts.explicitEnv ?? {},
-    );
-    return new LineProcess({ command, args, debugLabel: opts.debugLabel });
+    return directEnvironmentTransport(opts);
   }
 
   const db = getDb();
@@ -154,6 +157,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
     opts.allowAttach &&
     row &&
     row.status === "running" &&
+    row.containerName === opts.environment.durableIdentity &&
     (row.attachCompatibilityKey ?? null) ===
       (opts.attachCompatibilityKey ?? null) &&
     heartbeatFresh(row.sessionDir)
@@ -188,13 +192,21 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
     ".uai",
     "sessions",
     opts.agentId,
-    String(Date.now()),
+    `${String(Date.now())}-${process.pid}`,
   );
   mkdirSync(sessionDir, { recursive: true });
   // Ship this host's runner with the session: works in containers created
   // before this feature (the workspace is mounted at its host path) and
   // never skews against the host version.
   const runnerInSession = join(sessionDir, "runner.mjs");
+  const environmentSessionDir = join(
+    opts.environment.descriptor.workspacePath,
+    ".uai",
+    "sessions",
+    opts.agentId,
+    basename(sessionDir),
+  );
+  const runnerInEnvironment = join(environmentSessionDir, "runner.mjs");
   try {
     copyFileSync(runnerScriptPath(), runnerInSession);
   } catch (err) {
@@ -205,22 +217,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
       `[transport] runner unavailable (${err instanceof Error ? err.message : err}) — falling back to direct pipes for ${opts.agentId}`,
     );
     clearCurrentSession(opts.taskId, opts.agentId);
-    const { command, args } = dockerExecArgs(
-      opts.containerName,
-      opts.cli,
-      opts.cliArgs,
-      opts.passEnv ?? [],
-      opts.explicitEnv ?? {},
-    );
-    return new LineProcess({ command, args, debugLabel: opts.debugLabel });
-  }
-
-  const envArgs: string[] = [];
-  for (const name of opts.passEnv ?? []) {
-    if (process.env[name]) envArgs.push("-e", name);
-  }
-  for (const [name, value] of Object.entries(opts.explicitEnv ?? {})) {
-    envArgs.push("-e", `${name}=${value}`);
+    return directEnvironmentTransport(opts);
   }
 
   const proc = new DurableProcess({
@@ -228,20 +225,22 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
     onOffsetAdvance: persistOffset,
     onCloseRequested: markClosed,
     debugLabel: opts.debugLabel,
-    spawnCommand: {
-      command: "docker",
-      args: [
-        "exec",
-        "-d",
-        ...envArgs,
-        opts.containerName,
-        "node",
-        runnerInSession, // identical path in-container (workspace self-mount)
-        sessionDir,
-        "--",
-        opts.cli,
-        ...opts.cliArgs,
-      ],
+    launch: async () => {
+      const result = await opts.environment.launchDetachedSession({
+        argv: [
+          "node",
+          runnerInEnvironment,
+          environmentSessionDir,
+          "--",
+          opts.cli,
+          ...opts.cliArgs,
+        ],
+        inheritEnv: opts.passEnv ?? [],
+        env: opts.explicitEnv ?? {},
+        launchTimeoutMs: 30_000,
+        maxOutputBytes: 256 * 1024,
+      });
+      return { exitCode: result.exitCode, stderr: result.stderr };
     },
   });
 
@@ -251,7 +250,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
       taskId: opts.taskId,
       agentId: opts.agentId,
       sessionDir,
-      containerName: opts.containerName,
+      containerName: opts.environment.durableIdentity,
       kind: opts.kind,
       attachCompatibilityKey: opts.attachCompatibilityKey ?? null,
       outboxOffset: 0,
@@ -263,7 +262,7 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
       target: [schema.hostAgentSessions.taskId, schema.hostAgentSessions.agentId],
       set: {
         sessionDir,
-        containerName: opts.containerName,
+        containerName: opts.environment.durableIdentity,
         kind: opts.kind,
         attachCompatibilityKey: opts.attachCompatibilityKey ?? null,
         outboxOffset: 0,
@@ -278,6 +277,19 @@ export function createAgentTransport(opts: AgentTransportOptions): LineTransport
   return claimTail(tailKey, proc);
 }
 
+function directEnvironmentTransport(opts: AgentTransportOptions): LineTransport {
+  return new EnvironmentLineProcess({
+    environment: opts.environment,
+    request: {
+      argv: [opts.cli, ...opts.cliArgs],
+      inheritEnv: opts.passEnv ?? [],
+      env: opts.explicitEnv ?? {},
+      maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+    },
+    debugLabel: opts.debugLabel,
+  });
+}
+
 /**
  * Make the opaque generation directory discoverable from inside the task.
  * The relative link resolves on both sides of the workspace bind mount. The

package/lib/agents/types.ts

@@ -13,6 +13,8 @@
 
 import { z } from "zod";
 
+import type { TaskEnvironmentAgentSessionSurface } from "../task-environment/types";
+
 /** The host-advertised adapter kind ("claude" | "codex" | "gemini" | …). */
 export const AgentKind = z
   .string()
@@ -168,8 +170,8 @@ export interface AgentSessionFactory {
   create(args: {
     taskId: string;
     agent: RosterAgent;
-    /** Container the task runs in (real adapters `docker exec` into it). */
-    containerName: string;
+    /** Provider-owned process/session surface for this task environment. */
+    environment: TaskEnvironmentAgentSessionSurface;
     /** Initial briefing — project.defaultPrompt — sent on session start. */
     systemPreamble: string;
     /** Host-derived restricted execution policy (ADR-083). Never supplied by
@@ -179,8 +181,8 @@ export interface AgentSessionFactory {
      *  supplies a new key so restart recovery replaces, rather than attaches,
      *  a process launched with incompatible argv/preamble/tooling. */
     attachCompatibilityKey?: string;
-    /** ADR-048: extra per-agent env for the `docker exec` (e.g. this agent's
-     *  own UAI_TASK_TOKEN so its `uai` CLI carries only its own permissions). */
+    /** ADR-048: extra per-agent process environment (e.g. this agent's own
+     *  UAI_TASK_TOKEN so its `uai` CLI carries only its own permissions). */
     agentEnv?: Record<string, string>;
   }): Promise<AgentSession>;
 }