rowboat/apps/x/CODE_MODE_ENGINES_PLAN.md

# Code Mode — Managed Engine Provisioning Plan

Branch: `feat/code-mode-managed-engines` (off `dev` @ `8ce24ebb`)

## 1. Problem & Goal

Code mode runs two coding agents — **Claude Code** and **Codex** — by spawning their
ACP adapters, which in turn spawn a heavy **native engine binary** (~205 MB claude,
~194 MB codex). We need code mode to work in **packaged releases with ~99% reliability
for both agents**, without shipping a ~400 MB installer.

### Current state (HEAD = revert of #614)
- Packaged builds **do not stage** the ACP adapters, and `forge.config.cjs`
  `ignore: /^\/node_modules\//` strips them. At runtime `agents.ts` resolves the
  adapter via `require.resolve(...)` then spawns it — which **throws
  `Cannot find module '@agentclientprotocol/...'`**.
- **Net: packaged code mode is broken in every release.** It only works in `dev`
  because pnpm symlinks exist. There is no 400 MB bloat today — but no function either.

### Why the two prior approaches are insufficient
- **Bundle engines (A):** +~400 MB per installer (one claude + one codex native binary
  per OS/arch). Works offline, but installer is huge.
- **Drive from user's local install (B)** — what #614 settled on and was reverted:
  requires the user to have **both** CLIs installed **and** logged in, correct version,
  on the right PATH. Depends on the user's machine → **structurally cannot hit 99%**
  (version skew, GUI-launch PATH stripping, missing installs). This is why #614 was
  reverted.

## 2. Chosen Architecture — Managed Engine Provisioning (validated against Conductor)

Split the problem into **engine** vs **auth**, treat them differently — exactly what
Conductor (conductor.build) does:

1. **Engine = owned by the app.** We provision **version-pinned** engine binaries into
   **app-support** (`~/.rowboat/engines/<agent>/<version>/`), download-on-demand on first
   use, sha256-verified, symlink/path-pinned. Not the user's global npm, not their PATH.
   → no version skew, no PATH quirks → this is what delivers the 99%.
2. **Auth = reused from the user.** The engines read existing credentials
   (`~/.claude` API key / Pro / Max, `~/.codex` auth.json). No second login. `status.ts`
   already inspects these.

### Empirical proof from Conductor on this machine
- DMG is **123 MB** — far smaller than the ~400 MB of engines → engines are **not** in
  the installer; they're downloaded after install.
- Layout observed at `~/Library/Application Support/com.conductor.app/`:
  ```
  agent-binaries/claude/2.1.170/claude   (222 MB, single Mach-O arm64)
  agent-binaries/codex/0.138.0/codex     (205 MB, single Mach-O arm64)
  bin/claude -> agent-binaries/claude/2.1.170/claude   (symlink to active version)
  bin/codex  -> agent-binaries/codex/0.138.0/codex
  agent-binaries/.meta/claude-2.1.170.json  = {sha256, size, downloaded_at_unix_ms, ...}
  ```
- So: versioned dirs + stable symlink + sha256 `.meta` ledger + download. We mirror this.

## 3. Concrete facts that make this clean (verified)

### Adapters honor an external engine via env var (no code change in adapters needed)
- **Claude** — `@agentclientprotocol/claude-agent-acp@0.39.0`,
  `dist/acp-agent.js:39`: `if (process.env.CLAUDE_CODE_EXECUTABLE) return it;`
  and line 1552 `pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE ?? ...`.
  If unset and no bundled native dep → it throws "set CLAUDE_CODE_EXECUTABLE".
- **Codex** — `@agentclientprotocol/codex-acp@0.0.44`,
  `dist/index.js:20900`: `const codexPath = process.env["CODEX_PATH"] ?? "codex";`
  → `spawn(codexPath, ["app-server"])`.
- **Implication:** provisioning + setting these two env vars is the *entire* engine story.

### Our engine packages are already single self-contained binaries
- `@anthropic-ai/claude-agent-sdk-darwin-arm64@0.3.156` → contains one `claude`
  executable (+ LICENSE/README).
- `@openai/codex@0.128.0-darwin-arm64` → `vendor/<target>/codex/codex` native binary
  **plus a bundled `rg` (ripgrep) at `vendor/<target>/path/rg`** — see Risk R1.

### Pinned versions + platform package names (read from the installed adapter trees)
- **Claude:** adapter `claude-agent-acp@0.39.0` → engine `@anthropic-ai/claude-agent-sdk@0.3.156`.
  Platform optional deps `@anthropic-ai/claude-agent-sdk-<platform>@0.3.156`:
  `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`,
  `linux-arm64-musl`, `win32-x64`, `win32-arm64`.
- **Codex:** adapter `codex-acp@0.0.44` → `@openai/codex@^0.128.0` (pnpm-**patched**, see R2).
  Platform deps aliased `@openai/codex-<platform>` → `npm:@openai/codex@0.128.0-<platform>`:
  `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `win32-x64`, `win32-arm64`.

## 4. Distribution source — npm platform packages, adapter-pinned (DECIDED)

We fetch the **per-platform engine packages from the npm registry at the exact versions
our ACP adapters depend on**, extract the native binary, and provision it into
`~/.rowboat/engines/...`. No self-host, no curl installer, no fallback.

- **Tarball URL:** `https://registry.npmjs.org/<pkg>/-/<file>-<version>.tgz`
  - claude: `@anthropic-ai/claude-agent-sdk-<platform>@0.3.156` → extract the `claude` binary.
  - codex:  `@openai/codex@0.128.0-<platform>` → extract `vendor/<target>/codex/codex`
            **and keep `vendor/<target>/path/rg`** (see R1).
- **Why adapter-pinned npm (not curl installer, not release bucket, not self-host):**
  - The binary is the **exact version our adapter was built/tested against** → ACP
    handshake guaranteed → the key to ~99% reliability.
  - npm registry is highly available, immutable per-version, and the packument provides
    `dist.integrity` (sha512) + `dist.shasum` (sha1) → integrity verification with **zero
    infra**.
  - The official `curl | bash` installer is for end-users: it installs globally to
    `~/.local/bin` and **auto-updates in the background** — exactly what we must avoid. We
    want an isolated, pinned, app-managed copy that never moves under the adapter.
    (Conductor likewise fetches the raw binary rather than running the installer.)
- **Versions are read from our lockfile at build time** and embedded in
  `engine-manifest.json`, so the manifest can never drift from the adapters we ship.

### Reference: how this relates to Conductor / official installers
- Conductor self-hosts the same kind of native binaries on `storage.conductor.build`
  (raw/`.gz`/`.zst` + `{url,gzipUrl,zstdUrl,sha256}` manifest), pairing the adapters with
  recent **standalone CLI** versions (claude 2.1.x, codex 0.138). That proves recent
  versions work — but we deliberately pin to the **adapter's own** engine version for
  determinism.
- Official Claude releases also publish a GPG-signed `manifest.json` (SHA256/platform) at
  `downloads.claude.ai/claude-code-releases/<ver>/`. We don't use it now (npm is simpler
  and adapter-matched), but it's the upgrade path if we ever want the latest CLI line.
- If we later want control/availability/compression, we can mirror these npm tarballs to
  our own bucket — **runtime stays identical, only manifest URLs change.**

### Locked decisions
- **Source: npm platform packages, adapter-pinned versions (user).**
- **No self-host (user).**
- **Always provision; no fallback** to a user's pre-installed `claude`/`codex` (user).
  Reverted path B is fully retired.
- **Codex pnpm patch — IRRELEVANT (user):** it targets the JS launcher; we point
  `CODEX_PATH` at the native binary, so it does not apply. (Risk R2 removed.)

## 5. Design

### 5.1 Build-time: generate an engine manifest + stage adapter JS

**(a) Engine manifest (`engine-manifest.json`, embedded in the app).**
A build script reads the installed adapter dependency trees and emits, per agent:
```jsonc
{
  "claude": {
    "version": "0.3.156",
    "platforms": {
      "darwin-arm64": { "pkg": "@anthropic-ai/claude-agent-sdk-darwin-arm64",
                        "tarball": "https://registry.npmjs.org/.../-/...-0.3.156.tgz",
                        "integrity": "sha512-...",
                        "binRelPath": "claude" },
      "...": {}
    }
  },
  "codex": {
    "version": "0.128.0",
    "platforms": {
      "darwin-arm64": { "pkg": "@openai/codex-darwin-arm64",
                        "tarball": "https://registry.npmjs.org/...",
                        "integrity": "sha512-...",
                        "binRelPath": "vendor/aarch64-apple-darwin/codex/codex",
                        "extraPaths": ["vendor/aarch64-apple-darwin/path/rg"] }
    }
  }
}
```
- Versions + tarball URLs + integrity are pulled from the lockfile / npm packument so the
  manifest is always in sync with the adapters we ship. (Generating it at build time
  sidesteps hardcoding fragile package names.)
- `binRelPath` / `extraPaths` capture where the executable (and codex's `rg`) live inside
  each tarball.

**(b) Stage the ACP adapter JS into the package (the part of #614 we KEEP).**
The adapters themselves (tiny, ~15 MB total incl. their non-native JS deps) must exist on
disk in packaged builds so `agents.ts` can resolve + spawn them. In `forge.config.cjs`
`generateAssets`, stage the two adapters and their **non-native** production dependency
closure into `.package/acp/node_modules` (npm-style nested layout), and **exempt
`.package` from the `node_modules` ignore rule**. We **drop** #614's native-engine staging
entirely — engines come from provisioning, not the bundle.

### 5.2 Runtime: engine provisioner (new module in `packages/core`)

New file: `packages/core/src/code-mode/acp/engine-provisioner.ts`.

```
ensureEngine(agent): Promise<{ executablePath: string }>
  1. Read manifest entry for (agent, currentPlatform). Error clearly if unsupported.
  2. dir = ~/.rowboat/engines/<agent>/<version>/
  3. If dir exists AND .meta/<agent>-<version>.json sha256 matches → return binPath.
  4. Else acquire a cross-process lock (avoid double download), then:
     a. Download tarball to a temp file, streaming, with progress events.
     b. Verify integrity (sha512/sha256 from manifest).
     c. Extract into a temp dir, then atomic rename into <version>/ (tar gzip).
     d. chmod +x the binary (and codex's rg) on unix.
     e. Write .meta/<agent>-<version>.json {sha256, size, downloaded_at_unix_ms}.
  5. Return absolute path to the engine executable (binRelPath joined to dir).
```
- **Progress + cancellation** surfaced over IPC for the first-run "Downloading engine…" UI.
- **Offline / failure** → typed error with a clear, actionable message (not a hang).
- **Resumability / atomicity:** download to temp, verify, then rename; never leave a
  half-extracted version dir that passes the existence check.

### 5.3 Wire provisioning into launch

In `agents.ts` `getAgentLaunchSpec()` (currently sets only `CLAUDE_CODE_EXECUTABLE`):
- Make it (or its caller in `client.ts` / `manager.ts`) `await ensureEngine(agent)` first,
  then set:
  - claude → `env.CLAUDE_CODE_EXECUTABLE = <provisioned claude>`
  - codex  → `env.CODEX_PATH = <provisioned codex>` (and ensure its `rg` sibling resolves;
    keep the vendor dir layout intact so codex finds `../path/rg`).
- Keep `ELECTRON_RUN_AS_NODE=1` for the adapter spawn (unchanged).
- The provisioner replaces both the bundled-engine dependency *and* the reverted
  "resolve user's local install" path. (Optionally: if a healthy provisioned engine is
  absent but a compatible local install exists, we *may* fall back to it — but the default
  and reliable path is the provisioned engine. Decide in review; default = provisioned only.)

### 5.4 Status & UX (`status.ts` + renderer)
- `checkCodeModeAgentStatus()` becomes: engine = provisioned? (instead of "installed on
  PATH?"); auth = existing credentials present? (unchanged logic).
- First-run flow: user picks agent → if engine missing, show "Downloading <agent> engine
  (~200 MB), one time…" with progress; on completion, proceed. Subsequent uses: instant.
- Clear error states: download failed / offline / unsupported platform / auth missing.

## 6. File-by-file change plan

| File | Change |
|---|---|
| `apps/main/forge.config.cjs` | Stage adapter JS closure into `.package/acp/node_modules`; exempt `.package` from node_modules ignore; generate + copy `engine-manifest.json`. (No native engines staged.) |
| `apps/main/scripts/gen-engine-manifest.mjs` *(new)* | Build-time: read lockfile/packuments → emit `engine-manifest.json` (versions, tarball URLs, integrity, bin paths). |
| `packages/core/src/code-mode/acp/engine-provisioner.ts` *(new)* | `ensureEngine()` — download, verify, extract, lock, progress, `.meta` ledger. |
| `packages/core/src/code-mode/acp/agents.ts` | Resolve adapter from staged `.package/acp` first (fallback to node_modules in dev); `await ensureEngine`; set `CLAUDE_CODE_EXECUTABLE`/`CODEX_PATH` to provisioned binaries. |
| `packages/core/src/code-mode/acp/client.ts` / `manager.ts` | Await provisioning before spawn; surface provisioning progress/errors; keep startup deadline. |
| `packages/core/src/code-mode/status.ts` | Engine status = provisioned (not PATH); keep auth checks. |
| `apps/main/src/ipc.ts` + preload + renderer | IPC for provisioning progress + first-run download UI + error states. |
| CI (optional) | Smoke: packaged app boots each adapter, provisions a (small fake) engine, sets env var, answers ACP `initialize`; offline → clear error not a hang. |

## 7. Edge cases & risks

- **R1 — Codex needs `rg`.** The codex platform package bundles ripgrep at
  `vendor/<target>/path/rg`. We must extract/keep the vendor layout so codex finds it
  (don't extract the bare binary). Verify codex `app-server` boots from the provisioned dir.
- **R2 — Codex pnpm patch. RESOLVED (irrelevant).** The patch targets the JS launcher; we
  point `CODEX_PATH` at the native binary, so it does not apply.
- **R3 — Platform/arch matrix.** Manifest must cover darwin x64/arm64, linux x64/arm64
  (+musl for claude), win32 x64/arm64. Windows engine is `claude.exe`/`codex.exe`.
- **R4 — Integrity & supply chain.** Always verify the manifest integrity hash before
  chmod/exec. Treat a hash mismatch as a hard failure.
- **R5 — Disk + upgrades.** Versioned dirs accumulate. Add a cleanup that keeps only the
  active pinned version per agent.
- **R6 — First-run network.** Required once per agent; cached forever after. Must be a
  clear, cancellable UX, never a silent hang (reuse the #614 startup-deadline lesson).
- **R7 — code signing / Gatekeeper (macOS).** Downloaded native binaries aren't covered by
  our app's signature. Verify they run under Gatekeeper (they're already
  signed/notarized by Anthropic/OpenAI; quarantine attr may need clearing). Conductor runs
  them fine from app-support — confirm we do too.
- **R8 — `engine-manifest` staleness.** Manifest must regenerate whenever the adapter/engine
  versions change; tie generation into the build so it can't drift.

## 8. Phasing

1. **P1 — Packaging fix (unblocks dev→packaged parity):** stage adapter JS into `.package`,
   resolver checks staged path first. Verify packaged code mode can at least *spawn* the
   adapter. (Independent of provisioning; the part of #614 worth keeping.)
2. **P2 — Provisioner (core):** `ensureEngine()` + manifest + wire env vars. Verify both
   engines provision + boot from `~/.rowboat/engines` on macOS arm64.
3. **P3 — UX + status:** first-run download UI, status panel, error states.
4. **P4 — Cross-platform + CI smoke:** matrix manifest, mac/linux/win smoke.
5. **P5 — Polish:** version cleanup, cancellation, offline messaging, optional local-install
   fallback.

## 9. Decisions & remaining questions

### Resolved (locked)
1. **Source = npm platform packages, adapter-pinned versions** (not self-host, not curl
   installer, not release bucket).
2. **Always provision; no local-install fallback.**
3. **Codex pnpm patch irrelevant.**

### Still open (can decide during implementation)
- **Provision timing:** on first code-mode *use* (lazy) vs first app launch (eager,
  background download). Plan assumes **lazy + cached**.
- **Version-dir cleanup:** keep only the active pinned version per agent (R5).
- **Verify R1** (codex `rg`) and **R7** (Gatekeeper on downloaded macOS binaries) during P2.