@runuai/host 0.1.0

package/lib/agents/claude.ts

@@ -0,0 +1,343 @@
+/**
+ * ClaudeSession — a real AgentSession backed by the Claude Code CLI in
+ * stream-json mode, run inside the task container (ADR-010).
+ *
+ *   docker exec -i task-<id>-app-1 \
+ *     claude --print --input-format stream-json --output-format stream-json \
+ *            --verbose --no-session-persistence
+ *
+ * The CLI is a persistent bidirectional process: uai writes one JSON
+ * line per user turn to stdin and reads a stream of JSON event lines
+ * from stdout. Same binary, same subscription auth as the TUI — not the
+ * paid API (docs/interaction-model.md).
+ *
+ * Protocol mapping lives in the pure `mapClaudeLine` function so it can
+ * be unit-tested against fixture lines without spawning anything.
+ *
+ * ⚠️ VERIFY-ON-MAC: the exact stream-json envelope — especially the
+ * permission/control-request shape — must be checked against the
+ * installed `claude` build. The mapping is isolated here precisely so
+ * those fixups stay in one place.
+ */
+
+import { newId } from "../ulid";
+import { dockerExecArgs, LineProcess } from "./proc";
+import { register } from "./registry";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  RosterAgent,
+} from "./types";
+
+// Published Claude model aliases the CLI accepts via `--model`. The CLI
+// resolves these aliases to the current dated snapshots, so this list is
+// stable across point releases. UPDATE WHEN MODELS CHANGE (new family or a
+// retired alias). Order is display order in the cloud picker.
+const CLAUDE_MODELS = ["opus", "sonnet", "haiku"];
+
+// Opus ("opus" alias = Opus 4.8) is the default: the strongest coding model
+// for the interactive loop. Update alongside CLAUDE_MODELS.
+const CLAUDE_DEFAULT_MODEL = "opus";
+
+// Reasoning levels passed through via `claude --effort <level>`. Taken from
+// the CLI's `--help`: `--effort <level>` accepts (low, medium, high, xhigh,
+// max). UPDATE WHEN THE CLI CHANGES its effort levels.
+const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+
+// High is the default reasoning level. Update alongside CLAUDE_EFFORTS.
+const CLAUDE_DEFAULT_EFFORT = "high";
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping — stream-json line → AgentEvent[].
+// ---------------------------------------------------------------------------
+
+/** Narrow an unknown to a plain object. */
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+/**
+ * Map one stream-json stdout line to zero or more AgentEvents.
+ *
+ * Contract:
+ *   - `stream_event` content_block_delta(text) → `message_delta`
+ *   - `assistant` message tool_use blocks      → `tool_call`
+ *   - `result`                                 → `message_complete` + `turn_complete`
+ *   - control/permission request               → `permission_request`
+ *   - anything else                            → []  (ignored)
+ *
+ * A malformed line yields []. The mapper is intentionally total and
+ * side-effect free.
+ */
+export function mapClaudeLine(raw: string): AgentEvent[] {
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!isObj(json)) return [];
+
+  const type = json.type;
+
+  // --- streaming text deltas --------------------------------------------
+  if (type === "stream_event" && isObj(json.event)) {
+    const event = json.event;
+    if (
+      event.type === "content_block_delta" &&
+      isObj(event.delta) &&
+      event.delta.type === "text_delta" &&
+      typeof event.delta.text === "string"
+    ) {
+      return [{ type: "message_delta", text: event.delta.text }];
+    }
+    return [];
+  }
+
+  // --- full assistant message: harvest tool calls -----------------------
+  if (type === "assistant" && isObj(json.message)) {
+    const content = json.message.content;
+    if (!Array.isArray(content)) return [];
+    const out: AgentEvent[] = [];
+    for (const block of content) {
+      if (isObj(block) && block.type === "tool_use") {
+        const name = typeof block.name === "string" ? block.name : "tool";
+        out.push({
+          type: "tool_call",
+          id: typeof block.id === "string" ? block.id : newId(),
+          title: name,
+          detail: safeStringify(block.input),
+        });
+      }
+    }
+    return out;
+  }
+
+  // --- turn result ------------------------------------------------------
+  if (type === "result") {
+    const text = typeof json.result === "string" ? json.result : "";
+    if (json.is_error === true) {
+      return [
+        { type: "error", message: text || "claude returned an error" },
+        { type: "turn_complete" },
+      ];
+    }
+    return [
+      { type: "message_complete", text },
+      { type: "turn_complete" },
+    ];
+  }
+
+  // --- permission / control request -------------------------------------
+  // ⚠️ VERIFY-ON-MAC: confirm this envelope against the real CLI.
+  if (type === "control_request" && isObj(json.request)) {
+    const req = json.request;
+    if (req.subtype === "can_use_tool") {
+      return [
+        {
+          type: "permission_request",
+          id: typeof json.request_id === "string" ? json.request_id : newId(),
+          title:
+            typeof req.tool_name === "string"
+              ? `Allow ${req.tool_name}?`
+              : "Permission requested",
+          detail: safeStringify(req.input),
+        },
+      ];
+    }
+    return [];
+  }
+
+  return [];
+}
+
+function safeStringify(v: unknown): string {
+  if (v === undefined) return "";
+  if (typeof v === "string") return v;
+  try {
+    return JSON.stringify(v, null, 2);
+  } catch {
+    return String(v);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The session.
+// ---------------------------------------------------------------------------
+
+const CLAUDE_ARGS = [
+  "--print",
+  "--input-format",
+  "stream-json",
+  "--output-format",
+  "stream-json",
+  "--verbose",
+  // uai owns durable chat persistence. Claude Code's JSON transcript
+  // files are an implementation detail and can contain redacted
+  // thinking blocks. Replaying those from disk has caused Anthropic API
+  // 400s when a later turn sees a changed thinking block, so keep each
+  // managed stream-json process in-memory only.
+  "--no-session-persistence",
+  // Full tool access, no per-call prompts. Safe here precisely because
+  // a uai task runs in a throwaway, isolated container operating on a
+  // disposable worktree (ADR-001 / ADR-010) — the container *is* the
+  // sandbox. Without this, stream-json has no interactive approver and
+  // every Write/Bash silently self-denies.
+  "--dangerously-skip-permissions",
+];
+
+export class ClaudeSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "claude";
+
+  private readonly proc: LineProcess;
+  private readonly handlers = new Set<AgentEventHandler>();
+  private closed = false;
+
+  constructor(args: {
+    agent: RosterAgent;
+    containerName: string;
+    systemPreamble: string;
+  }) {
+    this.agentId = args.agent.id;
+
+    // The uai channel briefing (how to @-mention, the agent roster, the
+    // project's defaultPrompt) is passed as a real system prompt via
+    // `--append-system-prompt`, so it applies to every turn — not
+    // smuggled into the first user message.
+    const cliArgs = [...CLAUDE_ARGS];
+    if (process.env.UAI_CLAUDE_INCLUDE_PARTIAL_MESSAGES === "1") {
+      cliArgs.push("--include-partial-messages");
+    }
+    // The agent's model (when set) selects which Claude model the CLI
+    // drives. Without it the CLI uses the account default.
+    if (args.agent.model) {
+      cliArgs.push("--model", args.agent.model);
+    }
+    // The agent's effort (when set) selects the CLI reasoning level. Without
+    // it the CLI uses its own default.
+    if (args.agent.effort) {
+      cliArgs.push("--effort", args.agent.effort);
+    }
+    if (args.systemPreamble.trim().length > 0) {
+      cliArgs.push("--append-system-prompt", args.systemPreamble);
+    }
+    // Forward host-resident Claude auth into the headless exec. Headless
+    // `--print` does NOT use the interactive subscription/keychain path, so
+    // 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",
+      cliArgs,
+      ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+    );
+    this.proc = new LineProcess({
+      command,
+      args: argv,
+      debugLabel: `claude:${this.agentId}`,
+    });
+    this.proc.onLine((line) => {
+      for (const event of mapClaudeLine(line)) this.emit(event);
+    });
+    this.proc.onExit((code) => {
+      if (this.closed) return;
+      const tail = this.proc.stderrTail.trim();
+      // Surface an error event when:
+      //   - the process exited non-zero, OR
+      //   - it exited 0 but stderr says "Claude configuration file not
+      //     found". That message means Claude silently bailed because
+      //     its config was unlinked (Docker Desktop macOS atomic-write
+      //     race). The orchestrator handles this by repairing the
+      //     config and respawning, but only if it sees the error event.
+      const configMissing =
+        /Claude configuration file not found/i.test(tail);
+      if (code !== 0 || configMissing) {
+        this.emit({
+          type: "error",
+          message:
+            `claude process exited (${code ?? "spawn failed"})` +
+            (tail
+              ? `:\n${tail}`
+              : " — no stderr. Is the claude CLI installed in the task container, and is the container running?"),
+        });
+      }
+      this.closed = true;
+      this.emit({ type: "exit", code: code ?? -1 });
+    });
+  }
+
+  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;
+    this.proc.writeLine({
+      type: "user",
+      message: { role: "user", content: text },
+    });
+  }
+
+  async interrupt(): Promise<void> {
+    if (this.closed) return;
+    // Claude Code's stream-json control channel: an `interrupt` control-request
+    // stops the in-flight turn (the SDK's ESC). Safe to send when idle — the
+    // CLI acks with a control_response we don't need to track.
+    // ⚠️ VERIFY-ON-MAC: confirm the control-request `interrupt` envelope.
+    this.proc.writeLine({
+      type: "control_request",
+      request_id: newId(),
+      request: { subtype: "interrupt" },
+    });
+  }
+
+  async resolvePermission(
+    requestId: string,
+    decision: "accept" | "decline",
+  ): Promise<void> {
+    if (this.closed) return;
+    // ⚠️ VERIFY-ON-MAC: confirm the control-response envelope.
+    this.proc.writeLine({
+      type: "control_response",
+      request_id: requestId,
+      response: {
+        subtype: "can_use_tool",
+        behavior: decision === "accept" ? "allow" : "deny",
+      },
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      await this.proc.close();
+      return;
+    }
+    this.closed = true;
+    await this.proc.close();
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+// Register the Claude adapter at module load (ADR-021). The `--model`
+// pass-through above means `model` flows from the roster entry to the CLI.
+register({
+  kind: "claude",
+  label: "Claude",
+  supportedModels: () => [...CLAUDE_MODELS],
+  defaultModel: CLAUDE_DEFAULT_MODEL,
+  supportedEfforts: () => [...CLAUDE_EFFORTS],
+  defaultEffort: CLAUDE_DEFAULT_EFFORT,
+  create: async ({ agent, containerName, systemPreamble }) =>
+    new ClaudeSession({ agent, containerName, systemPreamble }),
+});