agent-control-plane 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {

package/tools/bin/render-architecture-infographics.sh

@@ -1,110 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-SOURCE_HTML="${ROOT_DIR}/tools/architecture/architecture-infographics.html"
-OUTPUT_DIR="${ROOT_DIR}/assets/architecture"
-PDF_OUT="${OUTPUT_DIR}/agent-control-plane-architecture.pdf"
-OVERVIEW_OUT="${OUTPUT_DIR}/overview-infographic.png"
-RUNTIME_OUT="${OUTPUT_DIR}/runtime-loop-infographic.png"
-LIFECYCLE_OUT="${OUTPUT_DIR}/worker-lifecycle-infographic.png"
-STATE_OUT="${OUTPUT_DIR}/state-dashboard-infographic.png"
-
-require_bin() {
-  local name="$1"
-  if ! command -v "$name" >/dev/null 2>&1; then
-    echo "missing required dependency: $name" >&2
-    exit 1
-  fi
-}
-
-require_bin python3
-require_bin playwright
-
-PLAYWRIGHT_CLI="$(command -v playwright)"
-PLAYWRIGHT_PACKAGE_ROOT="$(
-  python3 - "$PLAYWRIGHT_CLI" <<'PY'
-import os
-import sys
-
-print(os.path.dirname(os.path.realpath(sys.argv[1])))
-PY
-)"
-
-mkdir -p "${OUTPUT_DIR}"
-tmpdir="$(mktemp -d)"
-
-cleanup() {
-  rm -rf "${tmpdir}"
-}
-trap cleanup EXIT
-
-cat >"${tmpdir}/render-architecture.js" <<'EOF'
-const fs = require("fs");
-const path = require("path");
-const { chromium } = require(process.env.PLAYWRIGHT_PACKAGE_ROOT);
-
-async function screenshotSection(page, selector, filename) {
-  const element = await page.$(selector);
-  if (!element) {
-    throw new Error(`missing section for selector: ${selector}`);
-  }
-  await element.screenshot({ path: filename });
-}
-
-(async () => {
-  const sourceHtml = process.env.ACP_ARCH_SOURCE_HTML;
-  const pdfOut = process.env.ACP_ARCH_PDF_OUT;
-  const overviewOut = process.env.ACP_ARCH_OVERVIEW_OUT;
-  const runtimeOut = process.env.ACP_ARCH_RUNTIME_OUT;
-  const lifecycleOut = process.env.ACP_ARCH_LIFECYCLE_OUT;
-  const stateOut = process.env.ACP_ARCH_STATE_OUT;
-
-  const browser = await chromium.launch({ headless: true });
-  const page = await browser.newPage({
-    viewport: { width: 1664, height: 964 },
-    deviceScaleFactor: 1,
-    colorScheme: "light",
-  });
-
-  await page.goto(`file://${sourceHtml}`, { waitUntil: "load" });
-  await page.waitForTimeout(400);
-
-  await screenshotSection(page, "#overview-page", overviewOut);
-  await screenshotSection(page, "#runtime-loop-page", runtimeOut);
-  await screenshotSection(page, "#worker-lifecycle-page", lifecycleOut);
-  await screenshotSection(page, "#state-dashboard-page", stateOut);
-
-  await page.pdf({
-    path: pdfOut,
-    printBackground: true,
-    preferCSSPageSize: true,
-    margin: {
-      top: "0in",
-      right: "0in",
-      bottom: "0in",
-      left: "0in",
-    },
-  });
-
-  await browser.close();
-})().catch((error) => {
-  console.error(error);
-  process.exit(1);
-});
-EOF
-
-PLAYWRIGHT_PACKAGE_ROOT="${PLAYWRIGHT_PACKAGE_ROOT}" \
-ACP_ARCH_SOURCE_HTML="${SOURCE_HTML}" \
-ACP_ARCH_PDF_OUT="${PDF_OUT}" \
-ACP_ARCH_OVERVIEW_OUT="${OVERVIEW_OUT}" \
-ACP_ARCH_RUNTIME_OUT="${RUNTIME_OUT}" \
-ACP_ARCH_LIFECYCLE_OUT="${LIFECYCLE_OUT}" \
-ACP_ARCH_STATE_OUT="${STATE_OUT}" \
-node "${tmpdir}/render-architecture.js"
-
-echo "ARCHITECTURE_PDF=${PDF_OUT}"
-echo "ARCHITECTURE_OVERVIEW_PNG=${OVERVIEW_OUT}"
-echo "ARCHITECTURE_RUNTIME_PNG=${RUNTIME_OUT}"
-echo "ARCHITECTURE_LIFECYCLE_PNG=${LIFECYCLE_OUT}"
-echo "ARCHITECTURE_STATE_PNG=${STATE_OUT}"

package/tools/bin/render-dashboard-demo-media.sh

@@ -1,333 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-OUTPUT_DIR="${ROOT_DIR}/assets/readme"
-PNG_OUT="${OUTPUT_DIR}/dashboard-demo.png"
-GIF_OUT="${OUTPUT_DIR}/dashboard-demo.gif"
-
-require_bin() {
-  local name="$1"
-  if ! command -v "$name" >/dev/null 2>&1; then
-    echo "missing required dependency: $name" >&2
-    exit 1
-  fi
-}
-
-require_bin python3
-require_bin ffmpeg
-require_bin playwright
-require_bin curl
-
-PLAYWRIGHT_CLI="$(command -v playwright)"
-PLAYWRIGHT_PACKAGE_ROOT="$(
-  python3 - "$PLAYWRIGHT_CLI" <<'PY'
-import os
-import sys
-
-print(os.path.dirname(os.path.realpath(sys.argv[1])))
-PY
-)"
-
-tmpdir="$(mktemp -d)"
-server_pid=""
-controller_pid=""
-port="$(
-  python3 - <<'PY'
-import socket
-
-sock = socket.socket()
-sock.bind(("127.0.0.1", 0))
-print(sock.getsockname()[1])
-sock.close()
-PY
-)"
-
-cleanup() {
-  if [[ -n "${server_pid}" ]]; then
-    kill "${server_pid}" >/dev/null 2>&1 || true
-    wait "${server_pid}" 2>/dev/null || true
-  fi
-  if [[ -n "${controller_pid}" ]]; then
-    kill "${controller_pid}" >/dev/null 2>&1 || true
-    wait "${controller_pid}" 2>/dev/null || true
-  fi
-  rm -rf "${tmpdir}"
-}
-trap cleanup EXIT
-
-profile_registry_root="${tmpdir}/profiles"
-profile_dir="${profile_registry_root}/demo-retail"
-runs_root="${tmpdir}/runtime/demo-retail/runs"
-state_root="${tmpdir}/runtime/demo-retail/state"
-frames_dir="${tmpdir}/frames"
-mkdir -p \
-  "${profile_dir}" \
-  "${runs_root}/demo-issue-14" \
-  "${runs_root}/demo-issue-17" \
-  "${runs_root}/demo-issue-21" \
-  "${state_root}/resident-workers/issues/14" \
-  "${state_root}/resident-workers/issues/issue-lane-recurring-general-openclaw-safe" \
-  "${state_root}/retries/providers" \
-  "${state_root}/scheduled-issues" \
-  "${state_root}/resident-workers/issue-queue/pending" \
-  "${frames_dir}" \
-  "${OUTPUT_DIR}"
-
-sleep 600 &
-controller_pid="$!"
-
-cat >"${profile_dir}/control-plane.yaml" <<EOF
-schema_version: "1"
-id: "demo-retail"
-repo:
-  slug: "example/retail-agent-demo"
-  root: "${tmpdir}/repo"
-  default_branch: "main"
-runtime:
-  orchestrator_agent_root: "${tmpdir}/runtime/demo-retail"
-  worktree_root: "${tmpdir}/worktrees"
-  agent_repo_root: "${tmpdir}/repo"
-  runs_root: "${runs_root}"
-  state_root: "${state_root}"
-  history_root: "${tmpdir}/runtime/demo-retail/history"
-  retained_repo_root: "${tmpdir}/repo"
-  vscode_workspace_file: "${tmpdir}/demo-retail.code-workspace"
-session_naming:
-  issue_prefix: "demo-issue-"
-  pr_prefix: "demo-pr-"
-execution:
-  coding_worker: "openclaw"
-  openclaw:
-    model: "openrouter/sonic"
-    thinking: "adaptive"
-    timeout_seconds: 900
-EOF
-
-cat >"${runs_root}/demo-issue-14/run.env" <<'EOF'
-TASK_KIND=issue
-TASK_ID=14
-SESSION=demo-issue-14
-MODE=safe
-STARTED_AT=2026-03-27T15:00:00Z
-CODING_WORKER=openclaw
-WORKTREE=/tmp/demo-worktree-14
-BRANCH=agent/demo/issue-14
-RESIDENT_WORKER_KEY=issue-lane-recurring-general-openclaw-safe
-OPENCLAW_MODEL=openrouter/sonic
-EOF
-
-cat >"${runs_root}/demo-issue-14/runner.env" <<'EOF'
-RUNNER_STATE=succeeded
-THREAD_ID=thread-demo-14
-LAST_EXIT_CODE=0
-UPDATED_AT=2026-03-27T15:04:00Z
-EOF
-
-cat >"${runs_root}/demo-issue-14/result.env" <<'EOF'
-OUTCOME=implemented
-ACTION=host-publish-issue-pr
-EOF
-
-cat >"${runs_root}/demo-issue-17/run.env" <<'EOF'
-TASK_KIND=issue
-TASK_ID=17
-SESSION=demo-issue-17
-MODE=safe
-STARTED_AT=2026-03-27T15:05:00Z
-CODING_WORKER=openclaw
-WORKTREE=/tmp/demo-worktree-17
-BRANCH=agent/demo/issue-17
-OPENCLAW_MODEL=openrouter/sonic
-EOF
-
-cat >"${runs_root}/demo-issue-17/runner.env" <<'EOF'
-RUNNER_STATE=succeeded
-THREAD_ID=thread-demo-17
-LAST_EXIT_CODE=0
-UPDATED_AT=2026-03-27T15:08:00Z
-EOF
-
-cat >"${runs_root}/demo-issue-17/result.env" <<'EOF'
-OUTCOME=reported
-ACTION=host-comment-scheduled-report
-EOF
-
-cat >"${runs_root}/demo-issue-21/run.env" <<'EOF'
-TASK_KIND=issue
-TASK_ID=21
-SESSION=demo-issue-21
-MODE=safe
-STARTED_AT=2026-03-27T15:10:00Z
-CODING_WORKER=openclaw
-WORKTREE=/tmp/demo-worktree-21
-BRANCH=agent/demo/issue-21
-OPENCLAW_MODEL=openrouter/sonic
-EOF
-
-cat >"${runs_root}/demo-issue-21/runner.env" <<'EOF'
-RUNNER_STATE=succeeded
-THREAD_ID=thread-demo-21
-LAST_EXIT_CODE=0
-UPDATED_AT=2026-03-27T15:12:00Z
-EOF
-
-cat >"${runs_root}/demo-issue-21/result.env" <<'EOF'
-OUTCOME=blocked
-ACTION=host-comment-blocked
-FAILURE_REASON=provider-quota-limit
-EOF
-
-cat >"${state_root}/resident-workers/issues/14/controller.env" <<EOF
-ISSUE_ID=14
-SESSION=demo-issue-14
-CONTROLLER_PID=${controller_pid}
-CONTROLLER_MODE=safe
-CONTROLLER_LOOP_COUNT=4
-CONTROLLER_STATE=waiting-provider
-CONTROLLER_REASON=provider-cooldown
-ACTIVE_RESIDENT_WORKER_KEY=issue-lane-recurring-general-openclaw-safe
-ACTIVE_RESIDENT_LANE_KIND=recurring
-ACTIVE_RESIDENT_LANE_VALUE=general
-ACTIVE_PROVIDER_BACKEND=openclaw
-ACTIVE_PROVIDER_MODEL=openrouter/sonic
-PROVIDER_SWITCH_COUNT=1
-PROVIDER_FAILOVER_COUNT=1
-PROVIDER_WAIT_COUNT=2
-PROVIDER_WAIT_TOTAL_SECONDS=45
-PROVIDER_LAST_WAIT_SECONDS=21
-UPDATED_AT=2026-03-27T15:13:00Z
-EOF
-
-cat >"${state_root}/resident-workers/issues/issue-lane-recurring-general-openclaw-safe/metadata.env" <<'EOF'
-RESIDENT_WORKER_KIND=issue
-RESIDENT_WORKER_SCOPE=lane
-RESIDENT_WORKER_KEY=issue-lane-recurring-general-openclaw-safe
-ISSUE_ID=14
-CODING_WORKER=openclaw
-TASK_COUNT=9
-LAST_STATUS=running
-LAST_STARTED_AT=2026-03-27T15:00:00Z
-LAST_RUN_SESSION=demo-issue-14
-LAST_OUTCOME=implemented
-LAST_ACTION=host-publish-issue-pr
-EOF
-
-cat >"${state_root}/retries/providers/openclaw-openrouter-sonic.env" <<'EOF'
-ATTEMPTS=2
-NEXT_ATTEMPT_EPOCH=4102444800
-NEXT_ATTEMPT_AT=2100-01-01T00:00:00Z
-LAST_REASON=provider-quota-limit
-UPDATED_AT=2026-03-27T15:14:00Z
-EOF
-
-cat >"${state_root}/scheduled-issues/17.env" <<'EOF'
-INTERVAL_SECONDS=1800
-LAST_STARTED_AT=2026-03-27T15:05:00Z
-NEXT_DUE_AT=2026-03-27T15:35:00Z
-UPDATED_AT=2026-03-27T15:05:00Z
-EOF
-
-cat >"${state_root}/scheduled-issues/44.env" <<'EOF'
-INTERVAL_SECONDS=3600
-LAST_STARTED_AT=2026-03-27T14:30:00Z
-NEXT_DUE_AT=2026-03-27T15:30:00Z
-UPDATED_AT=2026-03-27T14:30:00Z
-EOF
-
-cat >"${state_root}/resident-workers/issue-queue/pending/issue-27.env" <<'EOF'
-ISSUE_ID=27
-SESSION=demo-issue-27
-UPDATED_AT=2026-03-27T15:14:00Z
-EOF
-
-cat >"${state_root}/resident-workers/issue-queue/pending/issue-28.env" <<'EOF'
-ISSUE_ID=28
-SESSION=demo-issue-28
-UPDATED_AT=2026-03-27T15:15:00Z
-EOF
-
-ACP_PROFILE_REGISTRY_ROOT="${profile_registry_root}" \
-  python3 "${ROOT_DIR}/tools/dashboard/server.py" \
-  --host 127.0.0.1 \
-  --port "${port}" \
-  >"${tmpdir}/server.log" 2>&1 &
-server_pid="$!"
-
-dashboard_url="http://127.0.0.1:${port}"
-
-for _ in $(seq 1 40); do
-  if curl -sf "${dashboard_url}/api/snapshot.json" >/dev/null 2>&1; then
-    break
-  fi
-  sleep 0.25
-done
-
-if ! curl -sf "${dashboard_url}/api/snapshot.json" >/dev/null 2>&1; then
-  cat "${tmpdir}/server.log" >&2
-  echo "failed to start dashboard demo server" >&2
-  exit 1
-fi
-
-cat >"${tmpdir}/capture-demo.js" <<'EOF'
-const fs = require("fs");
-const path = require("path");
-const { chromium } = require(process.env.PLAYWRIGHT_PACKAGE_ROOT);
-
-async function captureFrame(page, target, filename) {
-  await page.evaluate((top) => window.scrollTo({ top, behavior: "instant" }), target);
-  await page.waitForTimeout(350);
-  await page.screenshot({ path: filename });
-}
-
-(async () => {
-  const pngOut = process.env.ACP_PNG_OUT;
-  const framesDir = process.env.ACP_FRAMES_DIR;
-  const url = process.env.ACP_DEMO_URL;
-
-  fs.mkdirSync(path.dirname(pngOut), { recursive: true });
-  fs.mkdirSync(framesDir, { recursive: true });
-
-  const browser = await chromium.launch({ headless: true });
-  const page = await browser.newPage({
-    viewport: { width: 1440, height: 1080 },
-    deviceScaleFactor: 1,
-    colorScheme: "light",
-  });
-
-  await page.goto(url, { waitUntil: "networkidle" });
-  await page.waitForTimeout(800);
-  await page.screenshot({ path: pngOut, fullPage: true });
-
-  await captureFrame(page, 0, path.join(framesDir, "frame-00.png"));
-  await page.click("#refresh-button");
-  await page.waitForTimeout(500);
-  await captureFrame(page, 0, path.join(framesDir, "frame-01.png"));
-  await captureFrame(page, 900, path.join(framesDir, "frame-02.png"));
-  await captureFrame(page, 1700, path.join(framesDir, "frame-03.png"));
-  await captureFrame(page, 0, path.join(framesDir, "frame-04.png"));
-
-  await browser.close();
-})().catch((error) => {
-  console.error(error);
-  process.exit(1);
-});
-EOF
-
-PLAYWRIGHT_PACKAGE_ROOT="${PLAYWRIGHT_PACKAGE_ROOT}" \
-ACP_DEMO_URL="${dashboard_url}" \
-ACP_PNG_OUT="${PNG_OUT}" \
-ACP_FRAMES_DIR="${frames_dir}" \
-node "${tmpdir}/capture-demo.js"
-
-ffmpeg \
-  -y \
-  -framerate 1.25 \
-  -i "${frames_dir}/frame-%02d.png" \
-  -vf "fps=10,scale=1200:-1:flags=lanczos,split[s0][s1];[s0]palettegen=stats_mode=diff[p];[s1][p]paletteuse=dither=bayer" \
-  "${GIF_OUT}" \
-  >/dev/null 2>&1
-
-echo "DASHBOARD_DEMO_URL=${dashboard_url}"
-echo "PNG_OUT=${PNG_OUT}"
-echo "GIF_OUT=${GIF_OUT}"

package/tools/vendor/codex-quota/README.md

@@ -1,451 +0,0 @@
-# codex-quota
-
-Multi-account manager for OpenAI Codex CLI and OpenCode. Add, switch, list, and remove accounts with OAuth browser authentication. Seamlessly switch between both tools with shared credentials.
-
-Zero dependencies - uses Node.js built-ins only.
-
-## Installation
-
-```bash
-npm install -g codex-quota
-```
-
-Or with bun:
-
-```bash
-bun add -g codex-quota
-```
-
-After installation, both `codex-quota` and `cq` commands are available.
-
-## Quick Start
-
-```bash
-# Add a new account (opens browser for OAuth)
-codex-quota codex add personal
-
-# Add a Claude credential (interactive)
-codex-quota claude add work
-
-# Check quota for all accounts
-codex-quota
-
-# Switch active Codex account
-codex-quota codex switch personal
-
-# Switch Claude credentials
-codex-quota claude switch work
-
-# Sync activeLabel to CLI auth files
-codex-quota codex sync
-codex-quota claude sync
-
-# Preview sync without writing files
-codex-quota codex sync --dry-run
-codex-quota claude sync --dry-run
-
-# List accounts
-codex-quota codex list
-codex-quota claude list
-
-# Remove an account
-codex-quota codex remove old-account
-codex-quota claude remove old-account
-```
-
-## Commands
-
-Run `codex-quota` with no namespace to check combined Codex + Claude usage.
-
-### codex quota
-
-Check usage quota for Codex accounts.
-
-```bash
-codex-quota codex quota            # All Codex accounts
-codex-quota codex quota personal   # Specific account
-codex-quota codex quota --json     # JSON output
-```
-
-### claude quota
-
-Check usage quota for Claude accounts.
-
-```bash
-codex-quota claude quota           # All Claude accounts
-codex-quota claude quota work      # Specific credential
-codex-quota claude quota --json    # JSON output
-```
-
-### codex add
-
-Add a new Codex account via OAuth browser authentication.
-
-```bash
-codex-quota codex add                # Label derived from email
-codex-quota codex add work           # With explicit label
-codex-quota codex add --no-browser   # Print URL (for SSH/headless)
-```
-
-### claude add
-
-Add a Claude credential interactively.
-
-```bash
-codex-quota claude add               # Prompt for label + credentials
-codex-quota claude add work          # With explicit label
-codex-quota claude add work --json   # JSON output
-```
-
-### codex switch
-
-Switch the active account for Codex CLI, OpenCode, and pi.
-
-```bash
-codex-quota codex switch personal
-```
-
-When you run `codex switch`:
-
-1. **Codex CLI** - Updates `~/.codex/auth.json` with the selected account tokens
-2. **OpenCode** - If `~/.local/share/opencode/auth.json` exists, updates the `openai` provider entry
-3. **pi** - If `~/.pi/agent/auth.json` exists, updates the `openai-codex` provider entry
-
-It also updates `activeLabel` in `~/.codex-accounts.json` when available.
-
-### claude switch
-
-Switch Claude Code, OpenCode, and pi to a stored Claude credential.
-
-```bash
-codex-quota claude switch work
-```
-
-This updates `activeLabel` in `~/.claude-accounts.json` when available. OAuth-based
-credentials are required to update CLI auth files.
-
-### codex list
-
-List all Codex accounts from all sources with status indicators.
-
-```bash
-codex-quota codex list
-codex-quota codex list --json
-```
-
-Output shows:
-- `*` = active account (from `activeLabel`)
-- `~` = CLI auth account when it diverges from `activeLabel`
-- Email, plan type, token expiry
-- Source file for each account
-
-If CLI auth diverges from the tracked `activeLabel`, `list` and `quota` print a warning and
-suggest `codex-quota codex sync` to realign.
-
-### claude list
-
-List Claude credentials from `CLAUDE_ACCOUNTS` or `~/.claude-accounts.json`.
-
-```bash
-codex-quota claude list
-codex-quota claude list --json
-```
-
-Output shows:
-- `*` = active account (from `activeLabel`)
-- Source file for each credential
-
-For OAuth-based accounts, `list` and `quota` warn when stored tokens diverge from the
-`activeLabel` account. Session-key-only accounts are skipped.
-
-### codex remove
-
-Remove a Codex account from storage.
-
-```bash
-codex-quota codex remove old-account
-```
-
-Note: Accounts from `CODEX_ACCOUNTS` env var cannot be removed via CLI.
-
-### claude remove
-
-Remove a Claude credential from storage.
-
-```bash
-codex-quota claude remove old-account
-```
-
-Note: Accounts from `CLAUDE_ACCOUNTS` env var cannot be removed via CLI.
-
-### codex sync
-
-Sync the `activeLabel` Codex account to CLI auth files.
-
-```bash
-codex-quota codex sync
-codex-quota codex sync --dry-run
-codex-quota codex sync --json
-```
-
-This updates:
-1. `~/.codex/auth.json`
-2. `~/.local/share/opencode/auth.json` (if it exists)
-3. `~/.pi/agent/auth.json` (if it exists)
-
-### claude sync
-
-Sync the `activeLabel` Claude account to CLI auth files.
-
-```bash
-codex-quota claude sync
-codex-quota claude sync --dry-run
-codex-quota claude sync --json
-```
-
-Only OAuth-based Claude accounts can be synced. Session-key-only accounts are skipped with
-a warning.
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--json` | Output in JSON format |
-| `--dry-run` | Preview sync without writing files |
-| `--no-browser` | Print auth URL instead of opening browser |
-| `--no-color` | Disable colored output |
-| `--version, -v` | Show version number |
-| `--help, -h` | Show help |
-
-## Account Sources
-
-Accounts are loaded from these locations (in order). Read/write indicates whether the CLI
-reads from or writes to each path.
-
-| Source | Purpose | Read | Write |
-|--------|---------|------|-------|
-| `CODEX_ACCOUNTS` env var | JSON array of accounts | Yes | No |
-| `~/.codex-accounts.json` | Primary multi-account file (shared with OpenCode) | Yes | Yes (`add`, `remove`) |
-| `~/.opencode/openai-codex-auth-accounts.json` | OpenCode accounts | Yes | No |
-| `~/.codex/auth.json` | Codex CLI single-account (label `codex-cli`) | Yes | Yes (`switch`) |
-| `~/.local/share/opencode/auth.json` | OpenCode auth file (`openai` provider) | No | Yes (`switch` if it exists) |
-| `~/.pi/agent/auth.json` | pi auth file (`openai-codex` provider) | No | Yes (`switch` if it exists) |
-
-New accounts added via `codex-quota codex add` are saved to `~/.codex-accounts.json`, which is
-shared with OpenCode.
-
-Claude sources (in order):
-
-| Source | Purpose | Read | Write |
-|--------|---------|------|-------|
-| `CLAUDE_ACCOUNTS` env var | JSON array of credentials | Yes | No |
-| `~/.claude-accounts.json` | Claude multi-account file | Yes | Yes (`add`, `remove`) |
-| `~/.claude/.credentials.json` | Claude Code credentials | Yes | Yes (`switch`, `sync`) |
-| `~/.local/share/opencode/auth.json` | OpenCode auth file (`anthropic` provider) | No | Yes (`switch`, `sync` if it exists) |
-| `~/.pi/agent/auth.json` | pi auth file (`anthropic` provider) | No | Yes (`switch`, `sync` if it exists) |
-
-## Multi-Account JSON Schema
-
-File: `~/.codex-accounts.json`
-
-```json
-{
-  "schemaVersion": 1,
-  "activeLabel": "personal",
-  "accounts": [
-    {
-      "label": "personal",
-      "accountId": "chatgpt-account-uuid",
-      "access": "access-token",
-      "refresh": "refresh-token",
-      "idToken": "id-token-or-null",
-      "expires": 1234567890000
-    }
-  ]
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `schemaVersion` | number | Schema version marker (root field) |
-| `activeLabel` | string\|null | Active account label (root field) |
-| `label` | string | Unique identifier for the account |
-| `accountId` | string | ChatGPT account UUID |
-| `access` | string | OAuth access token |
-| `refresh` | string | OAuth refresh token |
-| `idToken` | string\|null | OAuth ID token (optional, for email extraction) |
-| `expires` | number | Token expiry timestamp in milliseconds |
-
-Root-level fields are preserved on write; unknown root fields are kept intact.
-
-Claude multi-account files (`~/.claude-accounts.json`) use the same root fields
-(`schemaVersion`, `activeLabel`) and store account entries that include a
-Claude OAuth token and refresh metadata.
-
-## OAuth Flow
-
-The `codex add` command uses OAuth 2.0 with PKCE for secure browser authentication:
-
-1. Generates PKCE code verifier and challenge
-2. Starts local callback server on `http://127.0.0.1:1455`
-3. Opens browser to OpenAI authorization page
-4. User authenticates in browser
-5. Callback server receives authorization code
-6. Exchanges code for tokens using PKCE verifier
-7. Saves tokens to `~/.codex-accounts.json`
-
-### Headless/SSH Mode
-
-In SSH sessions or headless environments (detected via `SSH_CLIENT`, `SSH_TTY`, or missing `DISPLAY`), the auth URL is printed instead of opening a browser:
-
-```bash
-codex-quota codex add --no-browser
-# Prints: Open this URL in your browser: https://auth.openai.com/authorize?...
-```
-
-Copy the URL to a browser on another machine, complete authentication, and the callback will be received by the local server.
-
-## Troubleshooting
-
-### Port 1455 in use
-
-```
-Error: Port 1455 is in use. Close other codex-quota instances and retry.
-```
-
-Another process is using port 1455. Check for:
-- Other `codex-quota codex add` commands running
-- OpenCode or Codex CLI auth processes
-
-Find and kill the process:
-```bash
-lsof -i :1455
-kill <pid>
-```
-
-### SSH/Headless authentication
-
-If browser doesn't open in SSH session:
-
-1. Use `--no-browser` flag: `codex-quota codex add --no-browser`
-2. Copy the printed URL to a browser on another machine
-3. Complete authentication in browser
-4. The callback is received by the server running over SSH
-
-### Token refresh failures
-
-If token refresh fails:
-```
-Error: Failed to refresh token. Re-authenticate with 'codex-quota codex add'.
-```
-
-The refresh token may have expired. Add the account again:
-```bash
-codex-quota codex remove expired-account
-codex-quota codex add new-label
-```
-
-### Environment variable accounts
-
-Accounts from `CODEX_ACCOUNTS` env var cannot be removed via CLI:
-```
-Error: Cannot remove account from CODEX_ACCOUNTS env var. Modify the env var directly.
-```
-
-Edit your shell configuration to remove the account from the env var.
-
-## JSON Output
-
-All commands support `--json` for scripting:
-
-```bash
-# Quota (combined)
-codex-quota --json
-# {"codex":[{"label":"personal","email":"user@example.com","usage":{...}}],"claude":[...]}
-
-# List (Codex)
-codex-quota codex list --json
-# {"accounts":[{"label":"personal","isActive":true,"email":"...","source":"..."}]}
-
-# Add (Codex, success)
-codex-quota codex add work --json
-# {"success":true,"label":"work","email":"user@example.com","accountId":"...","source":"~/.codex-accounts.json"}
-
-# Switch (Codex)
-codex-quota codex switch personal --json
-# {"success":true,"label":"personal","email":"...","authPath":"~/.codex/auth.json"}
-
-# Sync (Codex)
-codex-quota codex sync --json
-# {"success":true,"activeLabel":"work","updated":["~/.codex/auth.json",...],"skipped":[...]}
-
-# Errors include structured data
-codex-quota codex switch nonexistent --json
-# {"success":false,"error":"Account not found","availableLabels":["personal","work"]}
-```
-
-## Claude Code Usage (Optional)
-
-Use the `claude` namespace to check Claude usage alongside OpenAI quotas:
-
-```bash
-codex-quota claude quota
-```
-
-If multiple Claude accounts are configured, each account is fetched and displayed separately.
-
-To add a Claude credential interactively:
-
-```bash
-codex-quota claude add
-```
-
-This uses OAuth credentials to call:
-- `https://api.anthropic.com/api/oauth/usage`
-
-Authentication sources (in order):
-1. `CLAUDE_ACCOUNTS` env var (JSON array or `{ accounts: [...] }`)
-2. `~/.claude-accounts.json` (multi-account format with `oauthToken`)
-3. `~/.claude/.credentials.json` OAuth `accessToken`
-
-Multi-account format (Claude):
-```json
-{
-  "accounts": [
-    {
-      "label": "personal",
-      "oauthToken": "claude-ai-access-token",
-      "orgId": "org_uuid_optional"
-    }
-  ]
-}
-```
-
-Notes:
-- `label` plus `oauthToken` is required.
-- `orgId` is optional.
-
-Environment overrides:
-- `CLAUDE_ACCOUNTS` to supply multi-account JSON directly
-- `CLAUDE_CREDENTIALS_PATH` to point to a different credentials file
-
-Codex overrides:
-- `CODEX_ACCOUNTS` to supply multi-account JSON directly (read-only)
-- `CODEX_AUTH_PATH` to point to a different Codex CLI auth file
-- `XDG_DATA_HOME` to relocate OpenCode auth paths
-- `PI_AUTH_PATH` to point to a different pi auth file
-
-Notes:
-- Claude usage in the bundled public package is OAuth-only.
-
-## Releasing
-
-- Run `bun test` and `bun run preflight` before publishing.
-- Bump version with `bun pm version patch|minor|major`.
-- Dry-run the package with `bun run release:pack`.
-- Publish with `bun run release:publish` (local publish, no provenance).
-- Ensure the git working tree is clean.
-
-## License
-
-MIT