@runuai/host 0.1.0

package/lib/agents/proc.ts

@@ -0,0 +1,172 @@
+/**
+ * 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.
+ */
+
+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;
+}
+
+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;
+
+export class LineProcess {
+  private readonly child: ChildProcess;
+  private stdoutBuf = "";
+  private stderrBuf = "";
+  private readonly lineHandlers = new Set<LineHandler>();
+  private readonly exitHandlers = new Set<ExitHandler>();
+  private closed = false;
+  private readonly debug: string | null;
+
+  constructor(opts: LineProcessOptions) {
+    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));
+
+    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()}`);
+    });
+
+    this.child.on("exit", (code) => this.finish(code));
+    this.child.on("error", (err) => {
+      if (this.debug) this.log(`spawn error: ${err.message}`);
+      this.finish(null);
+    });
+  }
+
+  private log(msg: string): void {
+    console.error(`[uai-agent ${this.debug}] ${msg}`);
+  }
+
+  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);
+  }
+
+  /** 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;
+      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 read loop.
+        }
+      }
+    }
+  }
+
+  /** Subscribe to complete stdout lines. */
+  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);
+  }
+
+  /** 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`);
+  }
+
+  /** Last few KB of stderr — surfaced in error events. */
+  get stderrTail(): string {
+    return this.stderrBuf;
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  /** Terminate the process. Idempotent. */
+  async close(): Promise<void> {
+    if (this.closed) {
+      // Already exited — nothing to kill.
+      return;
+    }
+    try {
+      this.child.stdin?.end();
+    } catch {
+      // stdin may already be gone.
+    }
+    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[] = [],
+): { command: string; args: string[] } {
+  const envArgs: string[] = [];
+  for (const name of passEnv) {
+    if (process.env[name]) envArgs.push("-e", name);
+  }
+  return {
+    command: "docker",
+    args: ["exec", "-i", ...envArgs, containerName, cli, ...cliArgs],
+  };
+}

package/lib/agents/registry.ts

@@ -0,0 +1,109 @@
+/**
+ * Agent adapter registry (ADR-021).
+ *
+ * A small module-level registry so adding an agent kind is mechanical and
+ * needs no uai-core change: an adapter module calls `register()` at load,
+ * declaring its `kind`, display `label`, the models it can drive, an
+ * optional `defaultModel`, and a `create()` that builds an `AgentSession`.
+ *
+ * The host derives two things from the registry:
+ *   - `factoryFor(kind)` — used by the real agent factory to construct a
+ *     session for a roster entry by its `kind`.
+ *   - `capabilities()` — the `agentKinds` slice of the `host.capabilities`
+ *     frame, computed straight from the registered adapters.
+ *
+ * Registration is side-effect-on-import: importing `./claude` and `./codex`
+ * runs their `register()` calls (see `factory.ts`, which imports them).
+ */
+
+import type { AgentSessionFactory } from "./types";
+
+/** A registered agent adapter — metadata plus the session factory. */
+export interface RegisteredAdapter {
+  /** Host-advertised agent kind ("claude" | "codex" | "gemini" | …). */
+  kind: string;
+  /** Display name for the cloud picker. */
+  label: string;
+  /** Models this adapter can drive (CLI `--model` / `-c model=` values). */
+  supportedModels(): string[];
+  /** Preferred model when the user doesn't pick one. */
+  defaultModel?: string;
+  /** Reasoning levels this adapter can drive (CLI effort values). */
+  supportedEfforts(): string[];
+  /** Preferred effort when the user doesn't pick one. */
+  defaultEffort?: string;
+  /** Builds an AgentSession for a roster entry of this kind. */
+  create: AgentSessionFactory["create"];
+}
+
+/** One entry of the `host.capabilities` frame's `agentKinds`. */
+export interface AgentKindCapability {
+  kind: string;
+  label: string;
+  supportedModels: string[];
+  defaultModel?: string;
+  supportedEfforts: string[];
+  defaultEffort?: string;
+}
+
+const adapters = new Map<string, RegisteredAdapter>();
+
+/** Listeners fired after any registry mutation (manual re-advertise hook). */
+const changeListeners = new Set<() => void>();
+
+/**
+ * Register (or replace) an adapter for a kind. Called at module load by the
+ * adapter modules. Replacing is allowed so a later import wins deterministically.
+ */
+export function register(adapter: RegisteredAdapter): void {
+  adapters.set(adapter.kind, adapter);
+  for (const listener of changeListeners) listener();
+}
+
+/** Every registered adapter, in insertion order. */
+export function list(): RegisteredAdapter[] {
+  return [...adapters.values()];
+}
+
+/** The session factory for a kind, or undefined if no adapter is registered. */
+export function factoryFor(kind: string): AgentSessionFactory | undefined {
+  const adapter = adapters.get(kind);
+  return adapter ? { create: adapter.create } : undefined;
+}
+
+/**
+ * The `agentKinds` capability slice, derived from the registered adapters.
+ * Each adapter's `supportedModels()` / `supportedEfforts()` is evaluated here.
+ */
+export function capabilities(): AgentKindCapability[] {
+  return list().map((adapter) => {
+    const out: AgentKindCapability = {
+      kind: adapter.kind,
+      label: adapter.label,
+      supportedModels: adapter.supportedModels(),
+      supportedEfforts: adapter.supportedEfforts(),
+    };
+    if (adapter.defaultModel !== undefined) {
+      out.defaultModel = adapter.defaultModel;
+    }
+    if (adapter.defaultEffort !== undefined) {
+      out.defaultEffort = adapter.defaultEffort;
+    }
+    return out;
+  });
+}
+
+/**
+ * Subscribe to registry changes (adapter added/replaced). Returns an
+ * unsubscribe. Used to re-send the capability frame on change.
+ */
+export function onChange(listener: () => void): () => void {
+  changeListeners.add(listener);
+  return () => changeListeners.delete(listener);
+}
+
+/** Test/maintenance hook: drop all adapters and listeners. */
+export function reset(): void {
+  adapters.clear();
+  changeListeners.clear();
+}

package/lib/agents/types.ts

@@ -0,0 +1,133 @@
+/**
+ * The agent abstraction.
+ *
+ * uai drives Claude Code and Codex in their structured modes (see
+ * docs/interaction-model.md). Both — plus a mock for testing — implement
+ * the same `AgentSession` interface, so the orchestrator and chat UI
+ * never branch on which CLI is behind a given agent.
+ *
+ * An "agent" is a roster entry on a project, not a hardcoded
+ * Claude/Codex pair. A project can run one agent or several; each has a
+ * stable `id` used for addressing (`@<id>`).
+ */
+
+import { z } from "zod";
+
+/** The host-advertised adapter kind ("claude" | "codex" | "gemini" | …). */
+export const AgentKind = z
+  .string()
+  .min(1)
+  .regex(/^[a-z0-9][a-z0-9_-]*$/, "kind must be lowercase letters, digits, _ or -");
+export type AgentKind = z.infer<typeof AgentKind>;
+
+/** A task agent (ADR-021/ADR-022) — materialised onto a task.
+ *
+ *  `id` must be URL-safe (letters, digits, `_`, `-`) because it is the
+ *  `@<id>` mention token. `kind` selects the adapter; `model` is passed
+ *  through to the CLI. There is no `role` field. `initialPrompt` (if set)
+ *  drives this agent's first turn at container-ready. */
+export const RosterAgent = z.object({
+  id: z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z0-9_-]+$/, "id must be url-safe: letters, digits, _ or -"),
+  label: z.string().min(1), // display name
+  kind: AgentKind,
+  model: z.string().min(1).optional(),
+  effort: z.string().min(1).optional(), // CLI reasoning level, passed through
+  defaultPrompt: z.string().optional(), // persona
+  initialPrompt: z.string().optional(), // first-turn instructions, this task only
+});
+export type RosterAgent = z.infer<typeof RosterAgent>;
+
+/** A task's agents — distinct ids so a mention routes unambiguously. May be
+ *  empty (a scratchpad task with no crew). */
+export const Roster = z
+  .array(RosterAgent)
+  .refine((agents) => new Set(agents.map((a) => a.id)).size === agents.length, {
+    message: "agent ids must be unique within a roster",
+  });
+export type Roster = z.infer<typeof Roster>;
+
+/**
+ * Parse a task's `agents` JSON into a validated Roster. Falls back to an
+ * empty roster if malformed.
+ */
+export function parseRoster(raw: string): Roster {
+  try {
+    const parsed = Roster.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : [];
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Events an agent session emits as it works. The orchestrator persists
+// these to `uai_messages` and streams them to the browser.
+// ---------------------------------------------------------------------------
+
+export type AgentEvent =
+  /** A chunk of streaming assistant text. Appended to the in-progress message. */
+  | { type: "message_delta"; text: string }
+  /** The assistant message finished. `text` is the full final text. */
+  | { type: "message_complete"; text: string }
+  /** The agent invoked a tool / ran a command. Rendered as a card. */
+  | { type: "tool_call"; id: string; title: string; detail: string }
+  /** The agent needs approval before proceeding. */
+  | { type: "permission_request"; id: string; title: string; detail: string }
+  /** The agent addressed another agent — uai routes this as a peer message. */
+  | { type: "peer_message"; toAgentId: string; text: string }
+  /** The turn (one request → response cycle) is done; agent is idle. */
+  | { type: "turn_complete" }
+  /** A recoverable error surfaced by the agent. */
+  | { type: "error"; message: string }
+  /** The underlying process exited. */
+  | { type: "exit"; code: number };
+
+export type AgentEventHandler = (event: AgentEvent) => void;
+
+/**
+ * A live session with one agent. Implementations: ClaudeSession
+ * (stream-json), CodexSession (codex app-server), MockAgentSession.
+ */
+export interface AgentSession {
+  /** The roster id this session is for. */
+  readonly agentId: string;
+  /** Which agent kind backs it ("claude" | "codex" | …). */
+  readonly kind: AgentKind;
+
+  /** Send a user (or routed peer) message into the agent. */
+  send(text: string): Promise<void>;
+
+  /** Interrupt the agent's current turn (ESC). Idempotent / safe when idle. */
+  interrupt(): Promise<void>;
+
+  /** Resolve a pending permission request. */
+  resolvePermission(
+    requestId: string,
+    decision: "accept" | "decline",
+  ): Promise<void>;
+
+  /** Subscribe to events. Returns an unsubscribe function. */
+  onEvent(handler: AgentEventHandler): () => void;
+
+  /** Tear the session down. Idempotent. */
+  close(): Promise<void>;
+}
+
+/**
+ * Constructs an AgentSession for a roster entry. The orchestrator is
+ * handed one of these; swapping mock ⇄ real adapters is changing the
+ * factory, nothing else.
+ */
+export interface AgentSessionFactory {
+  create(args: {
+    taskId: string;
+    agent: RosterAgent;
+    /** Container the task runs in (real adapters `docker exec` into it). */
+    containerName: string;
+    /** Initial briefing — project.defaultPrompt — sent on session start. */
+    systemPreamble: string;
+  }): Promise<AgentSession>;
+}

package/lib/attachments.ts

@@ -0,0 +1,46 @@
+/**
+ * Chat attachments live on the host, inside the task workspace (ADR-015: the
+ * cloud stores no blobs). They land under `<workspace>/.uai/attachments/` —
+ * inside the workspace so the container (mounted at `/workspace`) reads them
+ * directly, and under `.uai/` so they sit outside the per-project worktrees and
+ * never get committed. The cloud relays bytes in/out; it never persists them.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+
+import { taskWorkspaceDir } from "./env";
+
+/** Host directory holding a task's attachments. */
+export function attachmentsDir(taskId: string): string {
+  return resolve(taskWorkspaceDir(taskId), ".uai", "attachments");
+}
+
+/** The path an in-container agent reads (workspace is mounted at /workspace). */
+export function containerAttachmentPath(filename: string): string {
+  return `/workspace/.uai/attachments/${basename(filename)}`;
+}
+
+/** Resolve + harden a filename to a path inside the task's attachments dir. */
+function safePath(taskId: string, filename: string): string {
+  const dir = attachmentsDir(taskId);
+  const full = resolve(dir, basename(filename));
+  if (full !== dir && !full.startsWith(dir + "/")) {
+    throw new Error("invalid attachment filename");
+  }
+  return full;
+}
+
+export function writeAttachment(
+  taskId: string,
+  filename: string,
+  bytes: Buffer,
+): void {
+  mkdirSync(attachmentsDir(taskId), { recursive: true });
+  writeFileSync(safePath(taskId, filename), bytes);
+}
+
+export function readAttachment(taskId: string, filename: string): Buffer | null {
+  const full = safePath(taskId, filename);
+  return existsSync(full) ? readFileSync(full) : null;
+}

package/lib/cloud-state.ts

@@ -0,0 +1,56 @@
+/**
+ * In-memory cloud (WSS bridge) connection state for the local UI (ADR-028).
+ *
+ * The bridge client in `src/main.ts` is the single writer; the local
+ * `/api/cloud` handler is a reader. Module-level singleton — there is exactly
+ * one bridge connection per host process. Never persisted.
+ */
+
+export type CloudConnectionState =
+  | "connected"
+  | "reconnecting"
+  | "disconnected";
+
+export interface CloudState {
+  state: CloudConnectionState;
+  /** Epoch ms of the last successful connect, or null if never connected. */
+  lastConnectedAt: number | null;
+  /** Count of reconnect attempts since process start. */
+  reconnectCount: number;
+  /** Most recent connection error message, or null. */
+  lastError: string | null;
+}
+
+const state: CloudState = {
+  state: "disconnected",
+  lastConnectedAt: null,
+  reconnectCount: 0,
+  lastError: null,
+};
+
+/** Snapshot for `/api/cloud`. */
+export function getCloudState(): CloudState {
+  return { ...state };
+}
+
+export function markConnected(): void {
+  state.state = "connected";
+  state.lastConnectedAt = Date.now();
+}
+
+/** The socket dropped and we will retry. Increments the reconnect counter. */
+export function markReconnecting(error?: string | null): void {
+  state.state = "reconnecting";
+  state.reconnectCount += 1;
+  if (error !== undefined) state.lastError = error;
+}
+
+/** Stopped for good (shutdown or fatal auth failure) — no retry. */
+export function markDisconnected(error?: string | null): void {
+  state.state = "disconnected";
+  if (error !== undefined) state.lastError = error;
+}
+
+export function markCloudError(message: string): void {
+  state.lastError = message;
+}