@cat-factory/executor-harness 1.31.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @cat-factory/executor-harness
+
+The payload that runs **inside** a per-run Cloudflare Container (or a
+[self-hosted runner](../../docs/runner-pool-integration.md)) to perform real
+repo work with the [Pi coding agent](https://github.com/earendil-works/pi).
+
+It is a thin TypeScript wrapper — a `node:http` server on `:8080` — that the
+Worker drives over a small **job protocol**. Jobs run **asynchronously**: a `POST`
+accepts the job and returns immediately with a `jobId`; the driver then polls
+`GET /jobs/{id}` for live progress and the terminal result.
+
+## Table of contents
+
+- [Job protocol](#job-protocol)
+- [What a job does](#what-a-job-does)
+- [No secrets in the image](#no-secrets-in-the-image)
+- [Layout](#layout)
+- [Runner lifecycle knobs](#runner-lifecycle-knobs)
+- [Build / test](#build--test)
+
+## Job protocol
+
+| Method & path     | Purpose                                                                                                                |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `GET /health`     | Liveness — `{ "status": "ok" }`.                                                                                       |
+| `POST /run`       | Start (or re-attach to) an **implementation** job (`coder` / `mocker` / `playwright`). Returns `202 { jobId, state }`. |
+| `POST /bootstrap` | Start a **repo-bootstrap** job (adapt a reference architecture → force-push a new repo).                               |
+| `POST /blueprint` | Start a **blueprint** job (decompose a repo → write the in-repo `blueprints/` map, commit on a branch).                |
+| `GET /jobs/{id}`  | Poll any job; returns the **job view** (`state`, optional `progress {completed,inProgress,total}`, `result`, `error`). |
+
+All jobs run in a generic `JobRegistry` (`src/runner.ts`) keyed by `jobId`, so a
+replayed `POST` **re-attaches** to the running job rather than starting a
+duplicate (the durable driver's retries/replays are safe). Pi's todo-tool counts
+are surfaced as `progress` while a job runs. The exact request/response shapes
+cat-factory sends are documented in
+[`docs/runner-pool-integration.md`](../../docs/runner-pool-integration.md).
+
+## What a job does
+
+The implementation job (`POST /run`) is the canonical sequence:
+
+1. **clone** the target repo (shallow) with a short-lived GitHub installation token,
+2. write the composed system prompt (role + the block's best-practice fragments)
+   to Pi's **global** context file `~/.pi/agent/AGENTS.md` (outside the checkout,
+   so it never lands in a commit and never clobbers a repo's own `AGENTS.md` —
+   Pi reads and concatenates both), and point Pi at the Worker's LLM proxy via
+   `~/.pi/agent/models.json` (provider `proxy`, `api: openai-completions`),
+3. **run Pi** non-interactively (`pi -p --mode json --model proxy/<model> --approve`),
+4. **commit, push** a branch and **open a PR**, returning `{ prUrl, branch, summary }`.
+
+Bootstrap differs at the ends — it may start from an empty dir, and **resets
+history to one commit and force-pushes** the default branch instead of opening a
+PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
+
+## No secrets in the image
+
+The image (built from the `Dockerfile`, base `node:26-trixie-slim`) contains
+only `git` + the Pi CLI + this compiled wrapper — **no API keys, no GitHub
+credentials**. Per job, the Worker passes a short-lived GitHub token and a
+signed, model-locked LLM-proxy **session token** in the request body. Pi reaches
+models only through the Worker proxy, which injects the real provider key (qwen /
+Kimi / DeepSeek) and meters spend. The provider key never enters the container.
+
+## Layout
+
+| File               | Responsibility                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------- |
+| `src/server.ts`    | HTTP entry point; routes `/health`, `/run`, `/bootstrap`, `/blueprint`, `/jobs/{id}`.                   |
+| `src/runner.ts`    | `JobRegistry` — async job lifecycle, idempotent on `jobId`, progress tracking.                          |
+| `src/job.ts`       | Request types + validators for the job specs.                                                           |
+| `src/pi.ts`        | Pi provider config, non-interactive run, JSON-line event + todo-progress parsing, global `AGENTS.md` guidance. |
+| `src/git.ts`       | clone / branch / commit / push + GitHub PR creation; bootstrap history reset + force-push.              |
+| `src/bootstrap.ts` | The `/bootstrap` handler (clone-or-empty → adapt → reinit + force-push).                                |
+| `src/blueprint.ts` | The `/blueprint` handler (decompose → render `blueprints/` → commit on branch).                         |
+| `src/embed.ts`     | Bundled assets/templates written into the workspace.                                                    |
+| `src/logger.ts`    | Structured logging.                                                                                     |
+
+## Runner lifecycle knobs
+
+Read from the environment inside the container (also honoured by a self-hosted
+runner):
+
+| Env var               | Default         | Effect                                                      |
+| --------------------- | --------------- | ----------------------------------------------------------- |
+| `PORT`                | `8080`          | HTTP port the harness listens on.                           |
+| `JOB_MAX_DURATION_MS` | `3600000` (60m) | Hard ceiling on a job's wall-clock time; force-fails after. |
+| `JOB_INACTIVITY_MS`   | `600000` (10m)  | Kills a hung agent that produces no output for this long.   |
+
+## Build / test
+
+```sh
+pnpm --filter @cat-factory/executor-harness build      # tsc → dist/
+pnpm --filter @cat-factory/executor-harness test       # unit tests
+docker build -f Dockerfile .                              # the container image
+```
+
+The build context is just this package, so its `tsconfig.json` is intentionally
+self-contained.
+
+## Published image (GHCR + Docker Hub)
+
+This package is not published to npm; instead its **Docker image** is published
+publicly, multi-arch (`linux/amd64` + `linux/arm64`), to **both GHCR and Docker
+Hub** so anyone can pull it without building from source:
+
+```
+ghcr.io/<owner>/cat-factory-executor:<version>
+docker.io/<org>/cat-factory-executor:<version>
+```
+
+Each is tagged with the package `version`, the commit `sha-…`, and `latest`.
+
+**CI** does this automatically:
+[`.github/workflows/docker-publish.yml`](../../../.github/workflows/docker-publish.yml)
+republishes on every push to `main` that touches image content (`src/**`,
+`Dockerfile`, `tsconfig.json`, `package.json`). Docker Hub is gated on the
+`DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN` repo secrets; without them it publishes
+to GHCR only.
+
+**Manually** (on demand, or to publish from a fork under your own namespaces):
+
+```sh
+# Log in first (one per registry you target):
+echo "$GHCR_TOKEN" | docker login ghcr.io -u <github-user> --password-stdin
+echo "$DOCKERHUB_TOKEN" | docker login -u <dockerhub-user> --password-stdin
+
+pnpm --filter @cat-factory/executor-harness run image:publish
+```
+
+The script ([`scripts/publish-image.sh`](./scripts/publish-image.sh)) builds the
+multi-arch image once and pushes it to the selected registries. Override defaults
+via env vars (`REGISTRIES`, `GHCR_OWNER`, `DOCKERHUB_ORG`, `TAG`, `PUSH_LATEST`,
+`PLATFORMS`, `EXTRA_CA`) — see the header of the script. Example: GHCR only —
+`REGISTRIES=ghcr pnpm --filter @cat-factory/executor-harness run image:publish`.
+
+A backend deployment references the image from `wrangler.toml`
+(`[[containers]] image = "ghcr.io/<owner>/cat-factory-executor:<version>"` — see
+[`deploy/backend`](../../../deploy/backend)); a self-hosted runner pool pulls the
+same image (see [`docs/runner-pool-integration.md`](../../docs/runner-pool-integration.md)).
+The worker library's own test/dev `wrangler.toml` still references this
+`Dockerfile` by local path so the acceptance suite can build it. Because the
+version is the image tag, **bump this package via a changeset whenever you change
+image content** (see [`CONTRIBUTING.md`](../../../CONTRIBUTING.md)).

package/dist/agent-runner.js

@@ -0,0 +1,389 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { killChildProcess } from './process.js';
+import { redact, secretsToRedact } from './redact.js';
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Drive one CLI subprocess to completion, streaming LF-framed JSONL from stdout
+ * through `onEvent`. Mirrors `runPi`'s lifecycle: prompt over stdin (out-of-band,
+ * never argv), `onActivity` on every chunk, abort kills the child, and the close
+ * handler resolves/rejects. The caller's `onEvent` accumulates the outcome.
+ *
+ * `prompt` is fed over stdin: for Claude Code that is just the task prompt (the
+ * system prompt rides `--append-system-prompt`); for Codex — which has no
+ * system-prompt flag — the caller prepends the composed system prompt to it so
+ * the role + best-practice context is not lost.
+ */
+function streamCli(command, args, prompt, opts, env, secrets, onEvent) {
+    return new Promise((resolve, reject) => {
+        if (opts.signal?.aborted) {
+            reject(new Error(`${command} aborted before start`));
+            return;
+        }
+        const child = spawn(command, args, {
+            cwd: opts.cwd,
+            env: { ...process.env, ...env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        child.stdin.on('error', () => { });
+        child.stdin.end(prompt);
+        let stderr = '';
+        let aborted = false;
+        let lineBuffer = '';
+        const killChild = () => killChildProcess(child);
+        const processLine = (line) => {
+            if (!line.startsWith('{'))
+                return;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            try {
+                onEvent(event);
+            }
+            catch {
+                // A faulty observer must never break the run.
+            }
+        };
+        const consumeStdout = (text) => {
+            lineBuffer += text;
+            let nl = lineBuffer.indexOf('\n');
+            while (nl !== -1) {
+                const line = lineBuffer.slice(0, nl).trim();
+                lineBuffer = lineBuffer.slice(nl + 1);
+                nl = lineBuffer.indexOf('\n');
+                processLine(line);
+            }
+        };
+        const onAbort = () => {
+            aborted = true;
+            killChild();
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        child.stdout.on('data', (chunk) => {
+            opts.onActivity?.();
+            consumeStdout(chunk.toString());
+        });
+        child.stderr.on('data', (chunk) => {
+            opts.onActivity?.();
+            stderr += chunk.toString();
+            if (stderr.length > 8_000)
+                stderr = stderr.slice(-8_000);
+        });
+        child.on('error', (err) => {
+            opts.signal?.removeEventListener('abort', onAbort);
+            reject(err);
+        });
+        child.on('close', (code) => {
+            opts.signal?.removeEventListener('abort', onAbort);
+            if (lineBuffer.trim())
+                processLine(lineBuffer.trim());
+            const stderrTail = redact(stderr, secrets).slice(-700);
+            if (aborted) {
+                reject(new Error('agent run aborted by watchdog'));
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(`${command} exited with code ${code}: ${stderrTail}`));
+                return;
+            }
+            resolve({ stderrTail });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Claude Code
+// ---------------------------------------------------------------------------
+/**
+ * Run the Claude Code CLI headlessly against `opts.cwd`, authenticated with the
+ * leased subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN), talking direct to
+ * api.anthropic.com. Streams `--output-format stream-json`, mapping the
+ * `TodoWrite` tool calls onto subtask progress and the terminal `result` event
+ * onto the summary + usage.
+ */
+export async function runClaudeCode(opts) {
+    const stats = { toolCalls: 0, assistantChars: 0 };
+    let summary = '';
+    let usage;
+    const onEvent = (event) => {
+        const type = event.type;
+        if (type === 'assistant' && isObject(event.message)) {
+            const content = event.message.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (!isObject(block))
+                        continue;
+                    if (block.type === 'text' && typeof block.text === 'string') {
+                        stats.assistantChars += block.text.length;
+                    }
+                    if (block.type === 'tool_use') {
+                        stats.toolCalls += 1;
+                        if (block.name === 'TodoWrite' && opts.onProgress) {
+                            const progress = todosToProgress(block.input?.todos);
+                            if (progress)
+                                opts.onProgress(progress);
+                        }
+                    }
+                }
+            }
+        }
+        else if (type === 'result') {
+            if (typeof event.result === 'string')
+                summary = event.result;
+            usage = claudeUsage(event.usage) ?? usage;
+        }
+    };
+    // Native (ambient) mode: run the developer's installed `claude` with its OWN login —
+    // no isolated config home, no injected credential, no onboarding pre-seed. Otherwise,
+    // Claude Code persists user config/credentials under its config dir; point that at an
+    // isolated, per-run temp dir OUTSIDE the cloned checkout (`opts.cwd`). Otherwise the
+    // agents that finish with `git add -A` (blueprint/requirements/bootstrap) could stage a
+    // stray `.claude/` directory — and any cached credential in it — into the pushed branch.
+    // Mirrors the Codex CODEX_HOME isolation below; removed in `finally`.
+    if (!opts.ambientAuth && !opts.subscriptionToken) {
+        throw new Error('claude-code harness requires a subscription token (or ambientAuth)');
+    }
+    const configHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-claude-'));
+    // The config dir is brand-new every run, so Claude Code would otherwise treat this
+    // as a first launch and BLOCK on the interactive onboarding / "trust this folder" /
+    // bypass-permissions acknowledgement prompts — which never get answered headlessly,
+    // hanging the job until the watchdog kills it. Pre-seed the config that marks those
+    // as already accepted so `-p` starts straight into the run. Best-effort: written
+    // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
+    // (Ambient mode skips this — the developer's own config is already onboarded.)
+    if (configHome) {
+        await writeFile(join(configHome, '.claude.json'), JSON.stringify({
+            hasCompletedOnboarding: true,
+            bypassPermissionsModeAccepted: true,
+            hasTrustDialogAccepted: true,
+        }), { mode: 0o600 }).catch(() => { });
+    }
+    // Anthropic itself authenticates with the subscription OAuth token; a
+    // non-Anthropic Claude-Code vendor (GLM via Z.ai, Kimi via Moonshot, DeepSeek)
+    // points Claude Code at its Anthropic-compatible endpoint with an auth-token key.
+    // Ambient mode injects neither — the CLI uses the developer's logged-in `~/.claude`.
+    const env = opts.ambientAuth
+        ? {}
+        : {
+            CLAUDE_CONFIG_DIR: configHome,
+            ...(opts.subscriptionBaseUrl
+                ? {
+                    ANTHROPIC_BASE_URL: opts.subscriptionBaseUrl,
+                    ANTHROPIC_AUTH_TOKEN: opts.subscriptionToken,
+                }
+                : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken }),
+        };
+    try {
+        const { stderrTail } = await streamCli('claude', [
+            '-p',
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            // The per-run container IS the sandbox, and the run is fully headless (no one
+            // to approve a tool call) — so bypass permissions entirely. `acceptEdits`
+            // would auto-accept file edits but still gate Bash, which in `-p` mode is then
+            // denied, leaving the agent unable to run builds/tests/git to verify its work.
+            '--permission-mode',
+            'bypassPermissions',
+            '--model',
+            opts.model,
+            '--append-system-prompt',
+            opts.systemPrompt,
+        ], opts.userPrompt, opts, env, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        return { summary, stats, stderrTail, ...(usage ? { usage } : {}) };
+    }
+    finally {
+        // Never leave the config dir (and any cached credential) on disk past the run.
+        if (configHome)
+            await rm(configHome, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/** Map Claude Code's `TodoWrite` todos array onto subtask counts. */
+function todosToProgress(todos) {
+    if (!Array.isArray(todos))
+        return undefined;
+    const items = todos.filter(isObject).map((t) => ({
+        label: typeof t.content === 'string' ? t.content : String(t.content ?? ''),
+        status: normalizeStatus(t.status),
+    }));
+    const completed = items.filter((i) => i.status === 'completed').length;
+    const inProgress = items.filter((i) => i.status === 'in_progress').length;
+    return { completed, inProgress, total: items.length, items };
+}
+function normalizeStatus(status) {
+    if (status === 'completed')
+        return 'completed';
+    if (status === 'in_progress')
+        return 'in_progress';
+    return 'pending';
+}
+function claudeUsage(raw) {
+    if (!isObject(raw))
+        return undefined;
+    // Count every input bucket Anthropic bills: fresh input plus BOTH cache reads and
+    // cache writes (cache_creation_input_tokens), which are real consumed tokens — and
+    // are the dominant share on a long agent run. Omitting them under-weights a token's
+    // true load in the usage-aware rotation window.
+    const input = numberOf(raw.input_tokens) +
+        numberOf(raw.cache_read_input_tokens) +
+        numberOf(raw.cache_creation_input_tokens);
+    const output = numberOf(raw.output_tokens);
+    if (input === 0 && output === 0)
+        return undefined;
+    return { inputTokens: input, outputTokens: output };
+}
+// ---------------------------------------------------------------------------
+// Codex
+// ---------------------------------------------------------------------------
+/**
+ * Run the Codex CLI headlessly against `opts.cwd`, authenticated with the leased
+ * ChatGPT `auth.json` bundle written to an isolated CODEX_HOME, talking direct to
+ * the ChatGPT backend. Streams `codex exec --json`, mapping plan/todo updates onto
+ * subtask progress and the running cumulative token usage onto the outcome.
+ */
+export async function runCodex(opts) {
+    const stats = { toolCalls: 0, assistantChars: 0 };
+    let summary = '';
+    let usage;
+    // Codex reads its credentials from $CODEX_HOME/auth.json with file-backed
+    // storage. CRITICAL: this home must live OUTSIDE the cloned checkout (`opts.cwd`)
+    // — the blueprint/requirements/conflict-resolver handlers finish with
+    // `git add -A` + push, which would otherwise stage and publish the decrypted
+    // subscription `auth.json` (access + refresh tokens) to the PR branch. An
+    // isolated, per-run temp dir keeps the credential out of the working tree and is
+    // removed in `finally`.
+    //
+    // KNOWN LIMITATION: Codex refreshes its OAuth access token in-place by rewriting
+    // this `auth.json` mid-run. Because the home is a per-run temp dir wiped in
+    // `finally`, that refreshed credential is discarded and never written back to the
+    // pool — there is no write-back path. The stored bundle keeps working as long as
+    // its refresh token stays valid (ChatGPT refresh tokens are long-lived and reused,
+    // not rotated per refresh today), so each run re-refreshes from the same stored
+    // copy; if OpenAI ever rotates refresh tokens on use, a pooled Codex token would
+    // eventually need to be re-connected by the user. Claude OAuth tokens (from
+    // `claude setup-token`) are long-lived and unaffected.
+    // Native (ambient) mode: run the developer's installed `codex` with its OWN login —
+    // no isolated CODEX_HOME, no injected auth.json. Otherwise write the leased credential
+    // to a per-run temp home kept OUTSIDE the checkout (and removed in `finally`).
+    if (!opts.ambientAuth && !opts.subscriptionToken) {
+        throw new Error('codex harness requires a subscription token (or ambientAuth)');
+    }
+    const codexHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-codex-'));
+    if (codexHome) {
+        await writeFile(join(codexHome, 'auth.json'), opts.subscriptionToken, { mode: 0o600 });
+        await writeFile(join(codexHome, 'config.toml'), 'cli_auth_credentials_store = "file"\n', 'utf8');
+    }
+    const onEvent = (event) => {
+        const type = typeof event.type === 'string' ? event.type : '';
+        if (type.includes('agent_message') || type === 'item.completed') {
+            const text = extractText(event);
+            if (text) {
+                stats.assistantChars += text.length;
+                summary = text;
+            }
+        }
+        if (type.includes('tool') || type.includes('command') || type.includes('exec')) {
+            stats.toolCalls += 1;
+        }
+        const progress = codexPlanProgress(event);
+        if (progress && opts.onProgress)
+            opts.onProgress(progress);
+        const turnUsage = codexUsage(event);
+        if (turnUsage)
+            usage = turnUsage;
+    };
+    // Codex has no system-prompt flag, so fold the composed role + best-practice
+    // context into the prompt itself (Claude Code instead rides --append-system-prompt).
+    const prompt = opts.systemPrompt
+        ? `${opts.systemPrompt}\n\n---\n\n${opts.userPrompt}`
+        : opts.userPrompt;
+    try {
+        const { stderrTail } = await streamCli('codex', [
+            'exec',
+            '--json',
+            '--skip-git-repo-check',
+            // The per-run container IS the sandbox; let Codex write files and reach the
+            // vendor unrestricted, with no approval prompts (the run is headless).
+            '--dangerously-bypass-approvals-and-sandbox',
+            '--model',
+            opts.model,
+            '-',
+        ], prompt, opts, codexHome ? { CODEX_HOME: codexHome } : {}, opts.subscriptionToken ? secretsToRedact(opts.subscriptionToken) : [], onEvent);
+        return { summary, stats, stderrTail, ...(usage ? { usage } : {}) };
+    }
+    finally {
+        // Never leave the decrypted credential on disk past the run.
+        if (codexHome)
+            await rm(codexHome, { recursive: true, force: true }).catch(() => { });
+    }
+}
+/** Best-effort: pull a textual message out of a Codex event. */
+function extractText(event) {
+    if (typeof event.message === 'string')
+        return event.message;
+    if (typeof event.text === 'string')
+        return event.text;
+    if (isObject(event.item)) {
+        const item = event.item;
+        if (typeof item.text === 'string')
+            return item.text;
+        if (typeof item.message === 'string')
+            return item.message;
+    }
+    return undefined;
+}
+/** Best-effort: map a Codex `update_plan`/plan event onto subtask counts. */
+function codexPlanProgress(event) {
+    const plan = (isObject(event.plan) ? event.plan : undefined) ??
+        (isObject(event.item) && Array.isArray(event.item.plan)
+            ? { steps: event.item.plan }
+            : undefined);
+    const steps = isObject(plan) ? plan.steps : Array.isArray(event.steps) ? event.steps : undefined;
+    if (!Array.isArray(steps))
+        return undefined;
+    const items = steps.filter(isObject).map((s) => ({
+        label: typeof s.step === 'string' ? s.step : String(s.step ?? s.content ?? ''),
+        status: normalizeStatus(s.status),
+    }));
+    if (items.length === 0)
+        return undefined;
+    const completed = items.filter((i) => i.status === 'completed').length;
+    const inProgress = items.filter((i) => i.status === 'in_progress').length;
+    return { completed, inProgress, total: items.length, items };
+}
+/**
+ * Best-effort: pull token usage out of a Codex usage event. Codex `exec --json`
+ * reports a running CUMULATIVE total on `token_count` events under
+ * `info.total_token_usage` (it also carries the per-turn `last_token_usage`); older /
+ * other shapes put it on `usage` / `info.usage` directly. We read the cumulative
+ * total when present so the caller can simply overwrite (not sum) — summing
+ * cumulative totals across events would multiply-count. Checked most-likely first.
+ */
+function codexUsage(event) {
+    const info = isObject(event.info) ? event.info : undefined;
+    const raw = (info && isObject(info.total_token_usage) ? info.total_token_usage : undefined) ??
+        (isObject(event.total_token_usage) ? event.total_token_usage : undefined) ??
+        (isObject(event.usage) ? event.usage : undefined) ??
+        (info && isObject(info.usage) ? info.usage : undefined);
+    if (!isObject(raw))
+        return undefined;
+    const input = numberOf(raw.input_tokens) + numberOf(raw.cached_input_tokens);
+    const output = numberOf(raw.output_tokens);
+    if (input === 0 && output === 0)
+        return undefined;
+    return { inputTokens: input, outputTokens: output };
+}
+function numberOf(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+/** Dispatch to the configured subscription harness runner. */
+export function runSubscriptionHarness(harness, opts) {
+    return harness === 'claude-code' ? runClaudeCode(opts) : runCodex(opts);
+}