@runuai/host 0.1.0

package/lib/agents/codex.ts

@@ -0,0 +1,522 @@
+/**
+ * CodexSession — a real AgentSession backed by `codex app-server`, run
+ * inside the task container (ADR-010):
+ *
+ *   docker exec -i task-<id>-app-1 codex app-server
+ *
+ * JSON-RPC 2.0 over stdio, newline-delimited. The protocol below is
+ * verified against `codex app-server generate-json-schema` (the
+ * generated schema, not guesswork).
+ *
+ * Lifecycle:
+ *   initialize        (request)      → server result
+ *   initialized       (notification) → sent by us
+ *   thread/start      (request)      → result `{ thread: { id, … } }`
+ *   turn/start        (request)      → output streams as notifications;
+ *                                      the response itself is ignored
+ *
+ * Streaming notifications consumed (`mapCodexNotification`):
+ *   item/agentMessage/delta        → message_delta
+ *   item/completed (agentMessage)  → message_complete
+ *   item/completed (tool item)     → tool_call
+ *   turn/completed                 → turn_complete (+ error if failed)
+ *   error                          → error
+ *
+ * The thread runs with `approvalPolicy: "never"` and
+ * `sandbox: "danger-full-access"` — the task container is the isolation
+ * boundary (ADR-011), and codex's bubblewrap sandbox can't create user
+ * namespaces inside it anyway.
+ */
+
+import { newId } from "../ulid";
+import { dockerExecArgs, LineProcess } from "./proc";
+import { register } from "./registry";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  RosterAgent,
+} from "./types";
+
+// Codex model slugs accepted via `-c model=<slug>`. Hardcoded: Codex has no
+// machine-readable "list models" command — the canonical list is the
+// interactive `codex` model picker (and `codex -m <slug>` / config.toml).
+// Sourced from that picker; UPDATE WHEN MODELS CHANGE. Order = display order
+// in the cloud picker. Legacy models remain reachable via config.toml.
+const CODEX_MODELS = [
+  "gpt-5.5",
+  "gpt-5.4",
+  "gpt-5.4-mini",
+  "gpt-5.3-codex",
+  "gpt-5.3-codex-spark",
+  "gpt-5.2",
+];
+
+// gpt-5.5 is Codex's current frontier coding model. Update alongside
+// CODEX_MODELS. When an agent's model is null the adapter omits the override
+// entirely and Codex uses the user's own configured default.
+const CODEX_DEFAULT_MODEL = "gpt-5.5";
+
+// Reasoning levels set via `-c model_reasoning_effort=<level>`. "xhigh" is the
+// picker's "Extra high". UPDATE WHEN CODEX CHANGES its reasoning levels.
+const CODEX_EFFORTS = ["low", "medium", "high", "xhigh"];
+
+// medium is Codex's default reasoning level. Update alongside CODEX_EFFORTS.
+const CODEX_DEFAULT_EFFORT = "medium";
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping — JSON-RPC notification → AgentEvent[].
+// ---------------------------------------------------------------------------
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function str(v: unknown, fallback = ""): string {
+  return typeof v === "string" ? v : fallback;
+}
+
+/** `item/completed` item types rendered as tool-call cards. */
+const TOOL_ITEM_TYPES = new Set([
+  "commandExecution",
+  "fileChange",
+  "mcpToolCall",
+  "dynamicToolCall",
+  "webSearch",
+]);
+
+/**
+ * Map one Codex JSON-RPC *notification* (method + params) to AgentEvents.
+ * Pure and total — an unrecognised method yields [].
+ */
+export function mapCodexNotification(
+  method: string,
+  params: unknown,
+): AgentEvent[] {
+  const p = isObj(params) ? params : {};
+
+  if (method === "item/agentMessage/delta") {
+    const text = str(p.delta);
+    return text ? [{ type: "message_delta", text }] : [];
+  }
+
+  if (method === "item/completed" && isObj(p.item)) {
+    const item = p.item;
+    const itemType = str(item.type);
+    if (itemType === "agentMessage") {
+      return [{ type: "message_complete", text: str(item.text) }];
+    }
+    if (TOOL_ITEM_TYPES.has(itemType)) {
+      return [
+        {
+          type: "tool_call",
+          id: str(item.id) || newId(),
+          title: codexToolTitle(itemType, item),
+          detail: codexToolDetail(item),
+        },
+      ];
+    }
+    return [];
+  }
+
+  if (method === "turn/completed") {
+    const turn = isObj(p.turn) ? p.turn : {};
+    if (turn.status === "failed" && isObj(turn.error)) {
+      return [
+        { type: "error", message: str(turn.error.message, "codex turn failed") },
+        { type: "turn_complete" },
+      ];
+    }
+    return [{ type: "turn_complete" }];
+  }
+
+  if (method === "error") {
+    const message = isObj(p.error)
+      ? str(p.error.message, "codex error")
+      : "codex error";
+    return [{ type: "error", message }];
+  }
+
+  return [];
+}
+
+function codexToolTitle(
+  itemType: string,
+  item: Record<string, unknown>,
+): string {
+  if (itemType === "commandExecution") {
+    const c = item.command;
+    const cmd = Array.isArray(c)
+      ? c.map((x) => String(x)).join(" ")
+      : str(c, "command");
+    return `$ ${cmd}`;
+  }
+  if (itemType === "fileChange") {
+    const n = Array.isArray(item.changes) ? item.changes.length : 0;
+    return `Edit ${n} file${n === 1 ? "" : "s"}`;
+  }
+  if (itemType === "mcpToolCall") {
+    return `MCP ${str(item.server)}/${str(item.tool)}`;
+  }
+  if (itemType === "dynamicToolCall") return `Tool ${str(item.tool)}`;
+  if (itemType === "webSearch") return `Search ${str(item.query)}`;
+  return itemType;
+}
+
+function codexToolDetail(item: Record<string, unknown>): string {
+  for (const key of ["aggregatedOutput", "result", "query"]) {
+    const v = item[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  try {
+    return JSON.stringify(item, null, 2);
+  } catch {
+    return "";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC framing.
+// ---------------------------------------------------------------------------
+
+/** Server→client requests we recognise as approval prompts. */
+const APPROVAL_METHODS = new Set([
+  "item/commandExecution/requestApproval",
+  "item/fileChange/requestApproval",
+  "item/permissions/requestApproval",
+  "applyPatchApproval",
+  "execCommandApproval",
+]);
+
+/** Bounds the handshake so a wrong-shape protocol surfaces as an error
+ *  rather than an endless "thinking…". `turn/start` is exempt — turns
+ *  can legitimately run for minutes. */
+const RPC_TIMEOUT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// The session.
+// ---------------------------------------------------------------------------
+
+export class CodexSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "codex";
+
+  private readonly proc: LineProcess;
+  private readonly handlers = new Set<AgentEventHandler>();
+  private readonly systemPreamble: string;
+  private closed = false;
+  private handshakeOk = false;
+
+  private nextRpcId = 1;
+  private readonly pending = new Map<
+    number,
+    { resolve: (v: unknown) => void; reject: (e: Error) => void }
+  >();
+  /** permission_request id → the JSON-RPC request id to answer with. */
+  private readonly approvals = new Map<string, number | string>();
+
+  private threadId: string | null = null;
+  private readonly ready: Promise<void>;
+
+  constructor(args: {
+    agent: RosterAgent;
+    containerName: string;
+    systemPreamble: string;
+  }) {
+    this.agentId = args.agent.id;
+    this.systemPreamble = args.systemPreamble;
+
+    // The agent's model / effort (when set) are selected via config overrides
+    // (`-c model=<model>`, `-c model_reasoning_effort=<effort>`) on the
+    // app-server process (ADR-021). All `-c` overrides go BEFORE the
+    // `app-server` subcommand. Without them codex uses its configured defaults.
+    const codexArgs: string[] = [];
+    if (args.agent.model) {
+      codexArgs.push("-c", `model=${args.agent.model}`);
+    }
+    if (args.agent.effort) {
+      codexArgs.push("-c", `model_reasoning_effort=${args.agent.effort}`);
+    }
+    codexArgs.push("app-server");
+    const { command, args: argv } = dockerExecArgs(
+      args.containerName,
+      "codex",
+      codexArgs,
+    );
+    this.proc = new LineProcess({
+      command,
+      args: argv,
+      debugLabel: `codex:${this.agentId}`,
+    });
+    this.proc.onLine((line) => this.onLine(line));
+    this.proc.onExit((code) => {
+      if (this.closed) return;
+      if (code !== 0) {
+        const tail = this.proc.stderrTail.trim();
+        this.emit({
+          type: "error",
+          message:
+            `codex process exited (${code ?? "spawn failed"})` +
+            (tail
+              ? `:\n${tail}`
+              : " — is the codex CLI installed in the task container, and is the container running?"),
+        });
+      }
+      this.closed = true;
+      for (const waiter of this.pending.values()) {
+        waiter.reject(new Error("codex process exited"));
+      }
+      this.pending.clear();
+      this.emit({ type: "exit", code: code ?? -1 });
+    });
+
+    this.ready = this.handshake().catch((err: unknown) => {
+      this.emit({
+        type: "error",
+        message: `codex handshake failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      });
+    });
+  }
+
+  // -- JSON-RPC plumbing ----------------------------------------------------
+
+  private onLine(line: string): void {
+    let msg: unknown;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (!isObj(msg)) return;
+
+    const hasId = "id" in msg && (typeof msg.id === "number" || typeof msg.id === "string");
+
+    // Response to one of our requests (id, no method).
+    if (hasId && !("method" in msg)) {
+      const id = typeof msg.id === "number" ? msg.id : -1;
+      const waiter = this.pending.get(id);
+      if (waiter) {
+        this.pending.delete(id);
+        if (isObj(msg.error)) {
+          waiter.reject(new Error(str(msg.error.message, "rpc error")));
+        } else {
+          waiter.resolve(msg.result);
+        }
+      }
+      return;
+    }
+
+    // Server→client request (id + method).
+    if (hasId && "method" in msg) {
+      this.onServerRequest(
+        msg.id as number | string,
+        str(msg.method),
+        msg.params,
+      );
+      return;
+    }
+
+    // Notification (method, no id).
+    if ("method" in msg) {
+      const method = str(msg.method);
+      // The thread id arrives on `thread/started`; also captured from
+      // the `thread/start` response in handshake().
+      if (method === "thread/started" && isObj(msg.params)) {
+        const thread = msg.params.thread;
+        if (isObj(thread) && typeof thread.id === "string") {
+          this.threadId = thread.id;
+        }
+      }
+      for (const ev of mapCodexNotification(method, msg.params)) {
+        this.emit(ev);
+      }
+    }
+  }
+
+  private onServerRequest(
+    id: number | string,
+    method: string,
+    params: unknown,
+  ): void {
+    if (APPROVAL_METHODS.has(method)) {
+      const permId = newId();
+      this.approvals.set(permId, id);
+      const p = isObj(params) ? params : {};
+      this.emit({
+        type: "permission_request",
+        id: permId,
+        title: method.includes("fileChange")
+          ? "Allow file changes?"
+          : `Allow: ${str(p.command, method)}`,
+        detail: codexToolDetail(p),
+      });
+      return;
+    }
+    // Anything else (tool calls, elicitation, token refresh) — we can't
+    // service it; reply with an error so codex doesn't block waiting.
+    this.respondError(id, `uai does not handle "${method}"`);
+  }
+
+  /** Send a JSON-RPC request, resolving with its result; rejects after
+   *  RPC_TIMEOUT_MS. For short calls (initialize, thread/start). */
+  private request(method: string, params: unknown): Promise<unknown> {
+    const id = this.nextRpcId++;
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.pending.delete(id)) {
+          reject(
+            new Error(
+              `codex did not answer "${method}" within ${
+                RPC_TIMEOUT_MS / 1000
+              }s`,
+            ),
+          );
+        }
+      }, RPC_TIMEOUT_MS);
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(timer);
+          resolve(v);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      });
+      this.proc.writeLine({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+
+  /** Send a JSON-RPC request without awaiting it — for `turn/start`,
+   *  whose output streams as notifications and whose response can take
+   *  minutes. The eventual response is ignored (no pending waiter). */
+  private fireRequest(method: string, params: unknown): void {
+    this.proc.writeLine({
+      jsonrpc: "2.0",
+      id: this.nextRpcId++,
+      method,
+      params,
+    });
+  }
+
+  private notify(method: string, params: unknown): void {
+    this.proc.writeLine({ jsonrpc: "2.0", method, params });
+  }
+
+  private respond(id: number | string, result: unknown): void {
+    this.proc.writeLine({ jsonrpc: "2.0", id, result });
+  }
+
+  private respondError(id: number | string, message: string): void {
+    this.proc.writeLine({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32601, message },
+    });
+  }
+
+  private async handshake(): Promise<void> {
+    await this.request("initialize", {
+      clientInfo: { name: "uai", version: "0.2" },
+    });
+    this.notify("initialized", {});
+    // The uai channel briefing (how to @-mention, the roster, the
+    // project's defaultPrompt) goes in as developer instructions so it
+    // applies to every turn on the thread.
+    const threadParams: Record<string, unknown> = {
+      approvalPolicy: "never",
+      sandbox: "danger-full-access",
+    };
+    if (this.systemPreamble.trim().length > 0) {
+      threadParams.developerInstructions = this.systemPreamble;
+    }
+    const result = await this.request("thread/start", threadParams);
+    if (isObj(result) && isObj(result.thread)) {
+      this.threadId = str(result.thread.id) || this.threadId;
+    }
+    this.handshakeOk = true;
+  }
+
+  // -- AgentSession ---------------------------------------------------------
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed && event.type !== "exit") return;
+    for (const h of this.handlers) h(event);
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    await this.ready;
+    if (this.closed) return;
+    if (!this.handshakeOk || !this.threadId) {
+      this.emit({
+        type: "error",
+        message:
+          "codex is unavailable — the app-server handshake did not complete.",
+      });
+      return;
+    }
+
+    this.fireRequest("turn/start", {
+      threadId: this.threadId,
+      input: [{ type: "text", text }],
+    });
+  }
+
+  async interrupt(): Promise<void> {
+    if (this.closed || !this.threadId) return;
+    // Cancel the thread's in-flight turn (codex's ESC). The app-server ends the
+    // current turn and emits a `turn/completed`. No-op when nothing is running.
+    // ⚠️ VERIFY-ON-MAC: confirm the codex interrupt method/params.
+    this.fireRequest("turn/interrupt", { threadId: this.threadId });
+  }
+
+  async resolvePermission(
+    requestId: string,
+    decision: "accept" | "decline",
+  ): Promise<void> {
+    if (this.closed) return;
+    const rpcId = this.approvals.get(requestId);
+    if (rpcId === undefined) return;
+    this.approvals.delete(requestId);
+    this.respond(rpcId, {
+      decision: decision === "accept" ? "accept" : "decline",
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      await this.proc.close();
+      return;
+    }
+    this.closed = true;
+    for (const waiter of this.pending.values()) {
+      waiter.reject(new Error("session closed"));
+    }
+    this.pending.clear();
+    await this.proc.close();
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+// Register the Codex adapter at module load (ADR-021). The `-c model=` config
+// override above means `model` flows from the roster entry to the app-server.
+register({
+  kind: "codex",
+  label: "Codex",
+  supportedModels: () => [...CODEX_MODELS],
+  defaultModel: CODEX_DEFAULT_MODEL,
+  supportedEfforts: () => [...CODEX_EFFORTS],
+  defaultEffort: CODEX_DEFAULT_EFFORT,
+  create: async ({ agent, containerName, systemPreamble }) =>
+    new CodexSession({ agent, containerName, systemPreamble }),
+});

package/lib/agents/factory.ts

@@ -0,0 +1,34 @@
+/**
+ * realAgentFactory — builds a real AgentSession per roster agent, resolving
+ * the adapter from the plug-in registry by `agent.kind` (ADR-021).
+ *
+ * Importing this module pulls in `./claude` and `./codex` purely for their
+ * side effect: each calls `register()` at load, populating the registry.
+ * Adding a kind is then "drop a module + import it for its side effect" — no
+ * change here. Unknown kinds fail loudly so a typo in a roster surfaces as an
+ * error rather than silently falling back to the wrong CLI.
+ *
+ * Both adapters run their CLI inside the task container via `docker exec`
+ * (ADR-010); the agent's `model` (if set) is passed through. Swapping mock ⇄
+ * real is changing which factory the orchestrator is constructed with — see
+ * `getOrchestrator`.
+ */
+
+// Side-effect imports: register the built-in adapters with the registry.
+import "./claude";
+import "./codex";
+
+import { factoryFor } from "./registry";
+import type { AgentSession, AgentSessionFactory } from "./types";
+
+export const realAgentFactory: AgentSessionFactory = {
+  create: async (args): Promise<AgentSession> => {
+    const factory = factoryFor(args.agent.kind);
+    if (!factory) {
+      throw new Error(
+        `no agent adapter registered for kind "${args.agent.kind}"`,
+      );
+    }
+    return factory.create(args);
+  },
+};

package/lib/agents/mock.ts

@@ -0,0 +1,133 @@
+/**
+ * MockAgentSession — a fake AgentSession for building and testing the
+ * chat pipeline without Docker or a real CLI.
+ *
+ * On send(), it streams a few `message_delta` chunks, sometimes a
+ * `tool_call` card, then `message_complete` + `turn_complete`. Enough
+ * shape that the orchestrator, SSE stream, and chat UI can all be
+ * exercised end to end. The real ClaudeSession / CodexSession adapters
+ * replace this behind the identical interface.
+ */
+
+import { newId } from "../ulid";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  AgentSessionFactory,
+  RosterAgent,
+} from "./types";
+
+/** Tunable so tests can run instantly while dev feels lifelike. */
+const DELTA_INTERVAL_MS = Number(process.env.UAI_MOCK_DELTA_MS ?? 60);
+
+export class MockAgentSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind;
+
+  private readonly handlers = new Set<AgentEventHandler>();
+  private readonly timers = new Set<ReturnType<typeof setTimeout>>();
+  private closed = false;
+  private turn = 0;
+
+  constructor(args: { agent: RosterAgent; systemPreamble: string }) {
+    this.agentId = args.agent.id;
+    this.kind = args.agent.kind;
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed) return;
+    for (const h of this.handlers) h(event);
+  }
+
+  /** schedule(fn, ms) — like setTimeout but cleaned up on close(). */
+  private schedule(fn: () => void, ms: number): void {
+    const t = setTimeout(() => {
+      this.timers.delete(t);
+      if (!this.closed) fn();
+    }, ms);
+    this.timers.add(t);
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    this.turn += 1;
+
+    // Compose a canned reply that echoes a little of the input so the
+    // feed visibly reflects what was sent.
+    const trimmed = text.trim().replace(/\s+/g, " ");
+    const echo = trimmed.length > 60 ? `${trimmed.slice(0, 57)}…` : trimmed;
+    const reply =
+      `[mock ${this.agentId}] received: "${echo}". ` +
+      `This is turn ${this.turn}. Wiring up the real ${this.kind} ` +
+      `adapter is the next step — until then I just echo.`;
+
+    const words = reply.split(" ");
+    let cursor = 0;
+    let assembled = "";
+
+    // Stream the reply word-by-word.
+    const streamNext = (): void => {
+      if (cursor >= words.length) {
+        this.emit({ type: "message_complete", text: assembled });
+        // Halfway through the conversation, fake a tool call so the
+        // card rendering path gets exercised.
+        if (this.turn === 1) {
+          this.schedule(() => {
+            this.emit({
+              type: "tool_call",
+              id: newId(),
+              title: "Read",
+              detail: "README.md (mock)",
+            });
+            this.schedule(() => this.emit({ type: "turn_complete" }), 200);
+          }, 150);
+        } else {
+          this.emit({ type: "turn_complete" });
+        }
+        return;
+      }
+      const chunk = (cursor === 0 ? "" : " ") + words[cursor];
+      assembled += chunk;
+      cursor += 1;
+      this.emit({ type: "message_delta", text: chunk });
+      this.schedule(streamNext, DELTA_INTERVAL_MS);
+    };
+
+    // Small initial "thinking" delay before the first token.
+    this.schedule(streamNext, DELTA_INTERVAL_MS * 2);
+  }
+
+  async interrupt(): Promise<void> {
+    if (this.closed) return;
+    // Stop any in-flight streaming and end the turn — the mock's ESC.
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    this.emit({ type: "turn_complete" });
+  }
+
+  async resolvePermission(): Promise<void> {
+    // The mock never raises permission requests, so nothing to resolve.
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+/** Factory that hands back MockAgentSessions. */
+export const mockAgentFactory: AgentSessionFactory = {
+  create: async ({ agent, systemPreamble }) =>
+    new MockAgentSession({ agent, systemPreamble }),
+};