@pat-lewczuk/cezar 0.1.3 → 0.1.5

package/README.md

@@ -2,13 +2,15 @@
 
 # cezar ⚡
 
-**A local cockpit for running and tracking AI coding-agent tasks in your repo.**
+**Parallel coding agents orchestrator** — a local cockpit for running and
+tracking AI coding-agent tasks in your repo.
 
-Type a task, pick a workflow, watch the agent work live — steps, tool calls,
-tokens, diffs — in a browser cockpit that runs entirely on your machine.
-Your `claude` login, your `gh`, your files. No accounts, no database, no cloud.
+Type a task, pick a workflow and an agent — **Claude Code, Codex or OpenCode,
+or a mix of them per step** — and watch it work live: steps, tool calls,
+tokens, diffs, in a browser cockpit that runs entirely on your machine.
+Your CLI logins, your `gh`, your files. No accounts, no database, no cloud.
 
-[What it solves](#what-it-solves) · [Who it's for](#who-its-for) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Core concepts](#core-concepts) · [Cockpit tour](#cockpit-tour)
+[A look inside](#a-look-inside) · [What it solves](#what-it-solves) · [Who it's for](#who-its-for) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Core concepts](#core-concepts) · [Cockpit tour](#cockpit-tour) · [Agent backends](#coding-agent-backends)
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
 ![Node 20+](https://img.shields.io/badge/Node-20%2B-339933)
@@ -29,6 +31,18 @@ That's the whole setup. If your `claude` CLI is logged in (Pro/Max) and `gh` is
 authenticated, there is nothing else to configure. State lives in `.ai/cezar/`
 inside your repo — plain JSON, NDJSON and Markdown you can `cat` and fix by hand.
 
+## A look inside
+
+Click any thumbnail for the full-size screenshot.
+
+| Watch a run live | The review gate | Parallel variants |
+|:--:|:--:|:--:|
+| [![A running task streaming agent text, tool calls and screenshots live](docs/screenshots/live-run.png)](docs/screenshots/live-run.png) | [![A finished run parked at the review gate — read the diff, send notes back, open the PR, or accept](docs/screenshots/review-gate.png)](docs/screenshots/review-gate.png) | [![Two competing variants of the same task compared side by side — pick the winner](docs/screenshots/variants-compare.png)](docs/screenshots/variants-compare.png) |
+| *Every step, tool call, token and screenshot — streamed as it happens.* | *Nothing auto-merges: inspect the diff, send notes into the same session, or push a draft PR.* | *Run a task ×2/×3 in isolated worktrees, compare the diffs, keep one.* |
+| **Plan before you run** | **Workflow builder** | **GitHub, one click away** |
+| [![The Plan overlay — an AI-drafted chain of steps you approve before anything runs](docs/screenshots/plan-chain.png)](docs/screenshots/plan-chain.png) | [![The workflow builder — drag skills into an ordered chain of agent steps and shell checks](docs/screenshots/workflow-builder.png)](docs/screenshots/workflow-builder.png) | [![The GitHub tab — hand an open issue to the agent with a workflow and skills](docs/screenshots/github-issues.png)](docs/screenshots/github-issues.png) |
+| *Press **Plan first** and review the proposed chain — trim, reorder, then start.* | *Stitch skills and shell checks into a reusable YAML chain, no code.* | *Open issues and PRs via your `gh` — run the agent straight on an issue.* |
+
 ---
 
 ## What it solves
@@ -51,6 +65,10 @@ locally under *your* subscription, and a cockpit shows you exactly what it's doi
 - **Losing a session when it fails.** Every run records its `claude` session id.
   Take it over interactively in one click (`claude --resume <id>`), or continue it
   in-process from the cockpit.
+- **Locked into one agent vendor.** Most tools wed you to a single CLI. cezar
+  drives **Claude Code, Codex and OpenCode** through one runner seam — set a
+  default, pick a backend per task, or mix them inside one workflow (implement
+  with one agent, review with another). See [Agent backends](#coding-agent-backends).
 - **Setup tax.** No wizard, no env vars, no schema. Skills are Markdown, workflows
   are short YAML, and everything degrades: no `gh` → works without PRs, no network
   → local skills still load, no `.ai/skills` → the bare prompt still runs.
@@ -73,8 +91,10 @@ locally under *your* subscription, and a cockpit shows you exactly what it's doi
 
 ## Quick start
 
-**Prerequisites:** Node 20+, the [`claude` CLI](https://github.com/anthropics/claude-code)
-logged in (Pro/Max subscription), and — optionally — `git` and the `gh` CLI.
+**Prerequisites:** Node 20+, at least one logged-in agent CLI — the
+[`claude` CLI](https://github.com/anthropics/claude-code) (Pro/Max subscription),
+the [`codex` CLI](https://github.com/openai/codex), or
+[OpenCode](https://opencode.ai) — and, optionally, `git` and the `gh` CLI.
 
 ```bash
 cd your-repo
@@ -91,8 +111,8 @@ npx cezar-cli init                                            # scaffold .ai/cez
 ```
 
 Both the `cezar` and `cez` commands are installed, so once it's on your PATH you
-can run either. No API key is ever used — cezar shells out to your logged-in
-`claude` CLI.
+can run either. No API key is ever used — cezar shells out to whichever agent
+CLIs you are already logged into, `claude` by default.
 
 > **Just kicking the tires?** Set `CEZ_DRY_RUN=1` to run against a bundled mock
 > instead of the real CLI — the whole cockpit works with no `claude` login, so
@@ -103,8 +123,9 @@ can run either. No API key is ever used — cezar shells out to your logged-in
 ## How it works
 
 You describe a task. cezar runs it as a **workflow** — an ordered list of agent
-steps and shell checks — shelling out to your `claude` CLI in headless
-stream-json mode. Each task gets its own git worktree; the cockpit streams every
+steps and shell checks — shelling out to your locally installed agent CLI
+(Claude Code by default; Codex and OpenCode are drop-in alternatives, per task
+or per step). Each task gets its own git worktree; the cockpit streams every
 event live and parks the run at a review gate when there's a diff to inspect.
 
 ```
@@ -117,15 +138,15 @@ event live and parks the run at a review gate when there's a diff to inspect.
         │
         ▼
    ┌──────────────────────────────┐     ┌───────────────────────────────┐
-   │  git worktree per task       │     │  claude CLI  (your login)     │
-   │  (isolated branch, parallel) │◄───►│  stream-json · default-deny   │
-   └──────────────────────────────┘     │  tools · acceptEdits in-repo  │
+   │  git worktree per task       │     │  agent CLI  (your login)      │
+   │  (isolated branch, parallel) │◄───►│  claude · codex · opencode    │
+   └──────────────────────────────┘     │  default-deny · acceptEdits   │
         │                                 └───────────────────────────────┘
         │  agent text · tool calls · tool results · tokens · cost
         ▼
    ┌─────────────┐   SSE (replay + live)   ┌──────────────────────────┐
    │ .ai/cezar/  │ ──────────────────────► │  cockpit  localhost:4321 │
-   │ JSON·NDJSON │                         │  Runs · Repo · GitHub ·  │
+   │ JSON·NDJSON │                         │  Tasks · Git · GitHub ·  │
    │ ·Markdown   │                         │  Skills · Workflows      │
    └─────────────┘                         └──────────────────────────┘
                                                   │
@@ -155,8 +176,8 @@ Three words, no jargon — **task**, **skill**, **chain**:
   shape *how* the agent reasons without touching code.
 - **Chains (workflows)** stitch steps into a pipeline: agent steps plus shell
   checks, with bounded `onFail` retry loops. Write the YAML yourself, build one by
-  drag-ordering skills in the **Workflows** tab, or press **Plan** and let the AI
-  draft a chain for your task that you review, trim and start. The built-in
+  drag-ordering skills in the **Workflows** tab, or press **Plan first** and let the
+  AI draft a chain for your task that you review, trim and start. The built-in
   `quick-task` (one agent step) works with zero setup.
 
 Two moves that make the cockpit worth the browser tab:
@@ -172,19 +193,22 @@ Two moves that make the cockpit worth the browser tab:
 
 ## Cockpit tour
 
-Six tabs, one browser window, all live over Server-Sent Events:
+Seven views, one browser window, all live over Server-Sent Events:
 
-| Tab | What's in it |
+| View | What's in it |
 |---|---|
-| **Runs** | Every task with its status, live event stream (agent text · tool calls · tool results · pasted/generated screenshots), tokens and cost. Continue, cancel, open in terminal (`claude --resume`), review the diff, or push a draft PR. |
+| **Tasks** | Every task with its status, live event stream (agent text · tool calls · tool results · pasted/generated screenshots), tokens and cost. Continue, cancel, open in terminal (`claude --resume`), review the diff, or push a draft PR. |
 | **Inbox** | Follow-ups an agent left behind (`todos.json`) — one click turns a suggestion into the next task, pre-wired to its suggested skill. |
-| **Repo** | Branch, working-tree status, diff vs HEAD, recent commits (click one for its inline patch + GitHub link), and the configurable base branch that worktrees fork from and PRs target. |
-| **GitHub** | Open issues and PRs of the repo's origin, read through your logged-in `gh`. Drag an issue onto the task box to prefill the prompt. |
+| **Git** | Branch, working-tree status, diff vs HEAD, recent commits (click one for its inline patch + GitHub link), and the configurable base branch that worktrees fork from and PRs target. |
+| **GitHub** | Open issues and PRs of the repo's origin, read through your logged-in `gh`. Hand an issue straight to the agent — pick a workflow and skills, one click runs it. |
 | **Skills** | Local skills plus the team skills repo, with a rendered body + prompt preview. Refresh pulls the latest from the remote. |
 | **Workflows** | Build a chain by drag-ordering skills, save it as portable YAML, import/export, or delete. Built-ins always come back. |
+| **Settings** | Appearance (dark/light theme, accent, density), agent backends, notifications, and the skills catalog. |
 
-The whole GUI is dependency-free vanilla JS with no build step, a dark/light
-theme toggle, and bookmarklets that launch a task straight from a GitHub page.
+The cockpit is a React app served pre-built from the package — `npx cezar-cli`
+still means no build step and no dev server on your machine — with a dark/light
+theme, a ⌘K command palette, and bookmarklets that launch a task straight from
+a GitHub page.
 
 ---
 
@@ -201,6 +225,7 @@ steps:
     prompt: "{{task}}"
     skill: project-conventions   # optional — from .ai/skills or .ai/cezar/skills
     # model: opus                # optional per-step model override
+    # runner: codex              # optional per-step backend: claude · codex · opencode
     # allowedTools: [Read, Edit, Write, Grep, Glob, Bash]
   - id: verify
     name: Verify
@@ -226,11 +251,13 @@ skills: [reproduce, root-cause, implement, self-review]
 
 ## How it runs agents
 
-cezar shells out to your locally installed, logged-in `claude` CLI in headless
-`stream-json` mode — **your subscription, no API key**. Tool access is
-default-deny via `--allowedTools`, and edits are auto-accepted
-(`--permission-mode acceptEdits`) inside the task's worktree. Nothing runs on a
-server you don't own.
+cezar shells out to your locally installed, logged-in agent CLI —
+**your subscription, no API key**. With the default Claude Code backend that
+means headless `stream-json` mode, tool access default-deny via
+`--allowedTools`, and edits auto-accepted (`--permission-mode acceptEdits`)
+inside the task's worktree. Codex and OpenCode are driven through their own
+native protocols — see [Coding agent backends](#coding-agent-backends).
+Nothing runs on a server you don't own.
 
 Useful environment variables:
 
@@ -238,10 +265,62 @@ Useful environment variables:
 |---|---|
 | `CEZ_DRY_RUN=1` | Use the bundled mock instead of the real `claude` CLI — the entire cockpit works offline, for demos and development. |
 | `CEZ_CLAUDE_BIN=/path/to/claude` | Override which `claude` binary is used. |
+| `CEZ_CODEX_BIN=/path/to/codex` | Override which `codex` binary is used. |
+| `CEZ_OPENCODE_BIN=/path/to/opencode` | Override which `opencode` binary is used. |
 | `GITHUB_TOKEN` | Fallback for GitHub reads/PRs when `gh` isn't authenticated. |
 
 ---
 
+## Coding agent backends
+
+cezar is not married to one vendor. Every agent step runs through a single
+`AgentRunner` seam with three built-in backends:
+
+| Backend | CLI | How cezar drives it |
+|---|---|---|
+| **Claude Code** (default) | [`claude`](https://github.com/anthropics/claude-code) | Headless `stream-json` mode. |
+| **Codex** | [`codex`](https://github.com/openai/codex) | `codex app-server` — JSON-RPC over stdio, the same transport the Codex IDE extensions use. |
+| **OpenCode** | [`opencode`](https://opencode.ai) | `opencode serve` — a local HTTP server with an SSE event stream. |
+
+On startup cezar probes which CLIs are installed and the cockpit only offers
+the backends it found — install any one of the three and you're operational.
+
+**Pick a backend at three levels** (most specific wins):
+
+1. **Config default** — `"defaultRunner": "codex"` in `.ai/cezar/config.json`.
+2. **Per task** — the backend picker next to the task box in the cockpit.
+3. **Per workflow step** — `runner:` on any step in the YAML.
+
+Per-step overrides are what make **mixed-agent strategies** a one-liner:
+implement with one agent, review with another, and let a shell check referee:
+
+```yaml
+name: implement-and-cross-review
+steps:
+  - id: implement
+    name: Implement
+    prompt: "{{task}}"
+    runner: codex                # one vendor writes the code…
+  - id: review
+    name: Cross-review
+    prompt: "Review the diff produced for: {{task}}. Fix real issues only."
+    runner: claude               # …another one reviews it
+  - id: verify
+    name: Verify
+    command: "npm test"
+    onFail: { retry: implement, max: 2 }
+```
+
+Parallel variants (×2/×3) of one task share that task's backend — mixing
+happens per task and per step, not inside a variant group.
+
+The seam is deliberately small: a backend is one class implementing the
+`AgentRunner` interface (`src/core/agent-runner.ts`) that turns a prompt into
+a stream of normalized events. Other CLIs — pi, aider, whatever ships next —
+can slot in the same way.
+
+---
+
 ## Configuration (optional)
 
 Zero config is the default — everything below is opt-in via
@@ -252,8 +331,9 @@ never blocks startup):
 {
   "skillsRepos": [{ "repo": "open-mercato/skills", "ref": "main" }], // team skills; [] disables
   "maxParallel": 2,          // how many tasks may run at once (non-git dirs always run 1)
-  "plannerModel": "sonnet",  // model the Plan button uses to draft chains
-  "baseBranch": "develop"    // branch worktrees fork from + PRs target (also settable in the Repo tab)
+  "defaultRunner": "claude", // agent backend: "claude" (default) · "codex" · "opencode"
+  "plannerModel": "sonnet",  // model the "Plan first" button uses to draft chains
+  "baseBranch": "develop"    // branch worktrees fork from + PRs target (also settable in the Git tab)
 }
 ```
 
@@ -266,15 +346,22 @@ git-ignored automatically; your workflows and skills stay committable.
 
 ```bash
 npm install
-npm run dev          # tsx src/index.ts — the cockpit, live-reloaded
-npm run build        # tsc → dist/
-npm run typecheck    # tsc --noEmit
+npm run dev          # server (API :4321) + Vite dev server, opens the cockpit in the browser
+npm run dev:server   # tsx src/index.ts — the API server alone
+npm run dev:web      # Vite dev server alone (proxies /api to :4321)
+npm run build        # tsc → dist/, vite build → web/dist/, then the pack gate
+npm run typecheck    # server + web (tsc --noEmit)
+npm test             # vitest — server + cockpit unit suites
+npm run test:unit    # node:test — fast core-module tests
+npm run test:package # pack/install and exercise the built CLI
+npm run test:e2e     # real-browser cockpit suite (agent-browser)
 ```
 
 The stack is deliberately small: **TypeScript** (strict, ESM), **Hono** + SSE for
-the server, **Zod** at every boundary, **YAML** for workflows, and **vanilla JS**
-for the GUI (no framework, no bundler). Every module is meant to be read in one
-sitting.
+the server, **Zod** at every boundary, **YAML** for workflows, and a **React 19 +
+Vite + Tailwind v4 + shadcn/ui** cockpit shipped pre-built in `web/dist/` — the
+published package carries the built app, so `npx` users never run a bundler.
+Every module is meant to be read in one sitting.
 
 ---
 

package/dist/config.d.ts

@@ -32,6 +32,13 @@ declare const configSchema: z.ZodObject<{
     }>, "many">>;
     /** How many tasks may run at once (spec 006). Non-git dirs always run 1. */
     maxParallel: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Per-task memory ceiling in MiB (whole process tree). When a running task's
+     * RSS crosses this the engine pauses it with a warning and lets the queue
+     * advance (#memory-guard). 0 / unset = no limit. `.catch(undefined)` keeps
+     * the key additive-safe: a bad value degrades to "no limit".
+     */
+    memoryLimitMb: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
     /**
      * Which agent backend a task uses unless overridden per task (GUI) or per
      * step (workflow). The GUI only offers runners actually installed; this is
@@ -45,6 +52,35 @@ declare const configSchema: z.ZodObject<{
      * Unset = the branch currently checked out. Settable from the Repo tab.
      */
     baseBranch: z.ZodOptional<z.ZodString>;
+    /**
+     * Default extra system prompt applied to every run's agent steps (claude:
+     * `--append-system-prompt`; codex/opencode: prepended to the opening user
+     * message — the AgentRunSpec seam handles the per-backend delivery).
+     * Settings is the single edit place; `POST /api/runs` can override it per
+     * run (`systemPrompt`). `.catch(undefined)` keeps the key additive-safe: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    systemPrompt: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    /**
+     * Per-runner default model preset (Settings → Agents, redesign R6 1.5): the
+     * model id the composer preselects for that runner. Missing = auto (the
+     * runner decides). A capability (`model`), never a vendor config format.
+     * `.catch(undefined)` keeps the key additive-safe like `systemPrompt`: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    defaultModels: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        claude: z.ZodOptional<z.ZodString>;
+        codex: z.ZodOptional<z.ZodString>;
+        opencode: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        claude?: string | undefined;
+        codex?: string | undefined;
+        opencode?: string | undefined;
+    }, {
+        claude?: string | undefined;
+        codex?: string | undefined;
+        opencode?: string | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     skillsRepos: {
         repo: string;
@@ -53,16 +89,26 @@ declare const configSchema: z.ZodObject<{
     maxParallel: number;
     defaultRunner: "claude" | "codex" | "opencode";
     plannerModel: string;
+    memoryLimitMb?: number | undefined;
     baseBranch?: string | undefined;
+    systemPrompt?: string | undefined;
+    defaultModels?: {
+        claude?: string | undefined;
+        codex?: string | undefined;
+        opencode?: string | undefined;
+    } | undefined;
 }, {
     skillsRepos?: {
         repo: string;
         ref?: string | undefined;
     }[] | undefined;
     maxParallel?: number | undefined;
+    memoryLimitMb?: unknown;
     defaultRunner?: "claude" | "codex" | "opencode" | undefined;
     plannerModel?: string | undefined;
     baseBranch?: string | undefined;
+    systemPrompt?: unknown;
+    defaultModels?: unknown;
 }>;
 export type CezConfig = z.infer<typeof configSchema>;
 /** Read `.ai/cezar/config.json` on demand — never cached, never throws. */

package/dist/config.js

@@ -19,6 +19,13 @@ const configSchema = z.object({
     skillsRepos: z.array(skillsRepoSchema).default(DEFAULT_SKILLS_REPOS),
     /** How many tasks may run at once (spec 006). Non-git dirs always run 1. */
     maxParallel: z.number().int().min(1).max(16).default(2),
+    /**
+     * Per-task memory ceiling in MiB (whole process tree). When a running task's
+     * RSS crosses this the engine pauses it with a warning and lets the queue
+     * advance (#memory-guard). 0 / unset = no limit. `.catch(undefined)` keeps
+     * the key additive-safe: a bad value degrades to "no limit".
+     */
+    memoryLimitMb: z.number().int().min(0).max(1_048_576).optional().catch(undefined),
     /**
      * Which agent backend a task uses unless overridden per task (GUI) or per
      * step (workflow). The GUI only offers runners actually installed; this is
@@ -32,6 +39,30 @@ const configSchema = z.object({
      * Unset = the branch currently checked out. Settable from the Repo tab.
      */
     baseBranch: z.string().trim().min(1).optional(),
+    /**
+     * Default extra system prompt applied to every run's agent steps (claude:
+     * `--append-system-prompt`; codex/opencode: prepended to the opening user
+     * message — the AgentRunSpec seam handles the per-backend delivery).
+     * Settings is the single edit place; `POST /api/runs` can override it per
+     * run (`systemPrompt`). `.catch(undefined)` keeps the key additive-safe: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    systemPrompt: z.string().trim().min(1).max(20_000).optional().catch(undefined),
+    /**
+     * Per-runner default model preset (Settings → Agents, redesign R6 1.5): the
+     * model id the composer preselects for that runner. Missing = auto (the
+     * runner decides). A capability (`model`), never a vendor config format.
+     * `.catch(undefined)` keeps the key additive-safe like `systemPrompt`: a
+     * bad value degrades to unset without discarding the rest of the config.
+     */
+    defaultModels: z
+        .object({
+        claude: z.string().trim().min(1).max(200).optional(),
+        codex: z.string().trim().min(1).max(200).optional(),
+        opencode: z.string().trim().min(1).max(200).optional(),
+    })
+        .optional()
+        .catch(undefined),
 });
 /** Read `.ai/cezar/config.json` on demand — never cached, never throws. */
 export async function loadConfig(repoRoot) {

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,gFAAgF;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;CACvC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAuB;IACtD,EAAE,IAAI,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,EAAE;CAC7C,CAAC;AAEF,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC;IACpE,4EAA4E;IAC5E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACvD;;;;OAIG;IACH,aAAa,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACxE,2EAA2E;IAC3E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACjD;;;OAGG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CAChD,CAAC,CAAC;AAIH,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,IAAI,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,wDAAwD;IAC1D,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/core/agent-runner.d.ts

@@ -10,6 +10,7 @@
  *  - `codex`    — `codex app-server`, JSON-RPC 2.0 (JSONL) over stdin/stdout;
  *  - `opencode` — `opencode serve`, HTTP + SSE.
  */
+import type { UiEvent } from './ui-events.js';
 /** `claude-cli` is the legacy id kept so old run records still parse. */
 export type AgentBackend = 'claude' | 'codex' | 'opencode' | 'claude-cli';
 /** The user-selectable runners (what config/GUI expose). */
@@ -47,6 +48,13 @@ export interface AgentRunSpec {
      */
     resume?: boolean;
 }
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export declare function prependSystemPrompt(systemPrompt: string | undefined, userPrompt: string): string;
 /** One content block of a user message — mirrors the Anthropic wire format
  *  so it can be written to the claude CLI's stdin verbatim. */
 export type ContentBlock = {
@@ -123,6 +131,10 @@ export interface SessionOptions {
      *  behavior, used for non-interactive workflow steps). Interactive
      *  sessions omit this and control `end()` themselves. */
     autoEndAfterFirstTurn?: boolean;
+    /** Protocol-v2 channel: receives the normalized `UiEvent` stream emitted
+     *  ALONGSIDE the v1 `AgentEvent`s (additive — v1 keeps flowing unchanged).
+     *  RunManager consumption lands in R2 step 2.1. */
+    onUiEvent?: (event: UiEvent) => void;
 }
 /**
  * A live agent session over one spawned backend process. The process stays
@@ -133,6 +145,10 @@ export interface SessionOptions {
 export interface AgentSession {
     /** Resolves when the backend process exits — the session is fully over. */
     result: Promise<AgentRunResult>;
+    /** OS pid of the spawned backend process — the root of the run's process
+     *  tree (agents spawn Bash children under it). Absent when the spawn
+     *  failed before a pid existed. Feeds live resource telemetry (#348). */
+    readonly pid?: number;
     /** Write a user message into the live session. False when it is closed. */
     sendMessage(content: ContentBlock[]): boolean;
     /** Graceful close: end input, then a SIGTERM→SIGKILL watchdog. */

package/dist/core/agent-runner.js

@@ -11,4 +11,13 @@
  *  - `opencode` — `opencode serve`, HTTP + SSE.
  */
 export const RUNNER_IDS = ['claude', 'codex', 'opencode'];
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export function prependSystemPrompt(systemPrompt, userPrompt) {
+    return systemPrompt ? `${systemPrompt}\n\n---\n\n${userPrompt}` : userPrompt;
+}
 //# sourceMappingURL=agent-runner.js.map

package/dist/core/agent-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC"}
+{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAmC/E;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAgC,EAAE,UAAkB;IACtF,OAAO,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,cAAc,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAC/E,CAAC"}

package/dist/core/claude-cli-runner.d.ts

@@ -38,6 +38,12 @@ export declare class ClaudeCliRunner implements AgentRunner {
     interrupt(): Promise<void>;
     startSession(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void, opts?: SessionOptions): AgentSession;
 }
+/**
+ * Build the headless argv. `--input-format stream-json` reads user messages
+ * from stdin; `--output-format stream-json --verbose` gives per-event NDJSON;
+ * `--permission-mode acceptEdits` lets edits through without a TTY prompt.
+ */
+export declare function buildClaudeArgs(spec: AgentRunSpec): string[];
 /**
  * Map `allowedTools` onto claude's `--allowedTools` syntax. `Bash` with a
  * `bashAllowlist` becomes one `Bash(<prefix>:*)` entry per allowed prefix;

package/dist/core/claude-cli-runner.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { costWeightedTokens } from './usage.js';
 import { readNdjson } from './ndjson.js';
+import { claudeTurnStarted, createClaudeUiState, mapClaudeMessage, stringifyToolResultContent, toolResultImageBlocks, } from './claude-ui-mapper.js';
 /** Default wall-clock cap for a single run before SIGTERM → SIGKILL.
  *  Interactive sessions pass `timeoutMs: 0` to disable it entirely. */
 export const DEFAULT_RUN_TIMEOUT_MS = 30 * 60_000;
@@ -57,6 +58,24 @@ export class ClaudeCliRunner {
         let autoEndTimer;
         let eofTermTimer;
         let eofKillTimer;
+        // Protocol v2 emission — additive alongside v1 (`onEvent` keeps flowing
+        // byte-identical); the channel is `opts.onUiEvent` (RunManager wiring
+        // lands in R2 step 2.1). The mapper never throws, but a defect in it
+        // must still never disturb the v1 stream — hence the belt-and-braces try.
+        let uiState = createClaudeUiState({ fallbackSessionId: spec.sessionId });
+        const emitUi = (map) => {
+            try {
+                const mapped = map(uiState);
+                uiState = mapped.state;
+                if (opts.onUiEvent) {
+                    for (const event of mapped.events)
+                        opts.onUiEvent(event);
+                }
+            }
+            catch {
+                // v2 mapping is best-effort; v1 consumers stay unaffected.
+            }
+        };
         const sendMessage = (content) => {
             if (!stdinOpen)
                 return false;
@@ -72,6 +91,8 @@ export class ClaudeCliRunner {
             });
             try {
                 child.stdin.write(`${line}\n`);
+                // Each user message written to stdin begins a turn (§7.1).
+                emitUi(claudeTurnStarted);
                 return true;
             }
             catch (err) {
@@ -151,6 +172,7 @@ export class ClaudeCliRunner {
                         onEvent?.({ type: 'note', message: `claude: skipped unparseable stream line: ${truncate(line)}` });
                         continue;
                     }
+                    emitUi((state) => mapClaudeMessage(msg, state));
                     let delta = 0;
                     try {
                         delta = handleClaudeMessage(msg, { toolCalls, textChunks, onEvent });
@@ -224,6 +246,7 @@ export class ClaudeCliRunner {
             sendMessage,
             end,
             interrupt,
+            pid: child.pid,
             get open() {
                 return stdinOpen;
             },
@@ -237,7 +260,7 @@ export class ClaudeCliRunner {
  * from stdin; `--output-format stream-json --verbose` gives per-event NDJSON;
  * `--permission-mode acceptEdits` lets edits through without a TTY prompt.
  */
-function buildClaudeArgs(spec) {
+export function buildClaudeArgs(spec) {
     const args = [
         '--input-format',
         'stream-json',
@@ -325,12 +348,12 @@ function handleClaudeMessage(msg, ctx) {
                 ctx.onEvent?.({
                     type: 'tool-result',
                     toolCallId: b.tool_use_id,
-                    result: stringifyContent(b.content),
+                    result: stringifyToolResultContent(b.content),
                     isError: b.is_error === true,
                 });
                 // Screenshots and other images inside the result get their own
                 // events — the text path above renders them as a placeholder.
-                for (const img of imageBlocks(b.content)) {
+                for (const img of toolResultImageBlocks(b.content)) {
                     ctx.onEvent?.({ type: 'image', mediaType: img.media_type, data: img.data });
                 }
             }
@@ -355,46 +378,7 @@ function handleClaudeMessage(msg, ctx) {
     // system/init and anything else: nothing actionable.
     return 0;
 }
-function stringifyContent(content) {
-    if (typeof content === 'string')
-        return content;
-    if (Array.isArray(content)) {
-        return content
-            .map((c) => {
-            const b = c;
-            if (b.type === 'text' && typeof b.text === 'string')
-                return b.text;
-            if (b.type === 'image')
-                return '[screenshot]'; // emitted as its own image event
-            try {
-                return JSON.stringify(b);
-            }
-            catch {
-                return String(b);
-            }
-        })
-            .join('\n');
-    }
-    try {
-        return JSON.stringify(content);
-    }
-    catch {
-        return String(content);
-    }
-}
-/** base64 image blocks inside a tool_result's content, if any. */
-function imageBlocks(content) {
-    if (!Array.isArray(content))
-        return [];
-    const out = [];
-    for (const c of content) {
-        const b = c;
-        if (b.type === 'image' && b.source?.type === 'base64' && b.source.media_type && b.source.data) {
-            out.push({ media_type: b.source.media_type, data: b.source.data });
-        }
-    }
-    return out;
-}
+// stringify/image helpers moved to claude-ui-mapper.ts (shared by v1 and v2).
 // ---- subprocess plumbing --------------------------------------------------
 function waitForExit(child) {
     if (child.exitCode != null)