codemax-cli 0.0.0-stage → 0.1.3

package/src/engines/codex.ts

@@ -0,0 +1,330 @@
+import type { AgentId } from "../adapters/types.ts";
+import type { Engine, EngineEvent, EngineInfo, EngineSessionRef, EngineStartOptions, PermissionRequest, StopReason, ToolStatus } from "./types.ts";
+import { agentEnv } from "./env.ts";
+import { platformArgv } from "../core/spawn.ts";
+import { classifyError } from "./errors.ts";
+
+export interface CodexEngineOptions {
+  /** Command for the app server. Default: codex app-server. */
+  cmd?: string[];
+  /** Tests inject a transport instead of spawning. */
+  transport?: { send(line: string): void; onLine(cb: (line: string) => void): void; close(): Promise<void> };
+}
+
+/**
+ * Codex engine over the native `codex app-server` JSON-RPC protocol (the one
+ * Codex's own IDE extension uses). Works with ChatGPT-plan login. Approvals
+ * arrive as server→client requests and are answered through
+ * `answerPermission`.
+ */
+export class CodexEngine implements Engine {
+  readonly agent: AgentId = "codex";
+  info: EngineInfo | null = null;
+  session: EngineSessionRef | null = null;
+  private listeners = new Set<(e: EngineEvent) => void>();
+  private proc: Bun.Subprocess | null = null;
+  private transport: NonNullable<CodexEngineOptions["transport"]> | null = null;
+  private nextId = 1;
+  private pending = new Map<number, { resolve: (v: any) => void; reject: (e: Error) => void }>();
+  private pendingApprovals = new Map<string, { rpcId: number | string; method: string }>();
+  private permSeq = 0;
+  private turn: { resolve: (r: StopReason) => void; id?: string } | null = null;
+  private threadId: string | null = null;
+  private cwd = "";
+  private model: string | undefined;
+  private lastTotals = { inputTokens: 0, cachedInputTokens: 0, cacheWriteInputTokens: 0, outputTokens: 0 };
+
+  constructor(private opts: CodexEngineOptions = {}) {}
+
+  onEvent(listener: (e: EngineEvent) => void) {
+    this.listeners.add(listener);
+    return () => void this.listeners.delete(listener);
+  }
+
+  private emit(e: EngineEvent) {
+    for (const l of this.listeners) l(e);
+  }
+
+  async start(o: EngineStartOptions): Promise<EngineInfo> {
+    this.cwd = o.cwd;
+    this.transport = this.opts.transport ?? this.spawn(o.cwd);
+    this.transport.onLine((line) => this.onLine(line));
+    const init = await this.request("initialize", { clientInfo: { name: "codemax", version: "0.3.0" }, capabilities: {} });
+    this.notify("initialized", {});
+
+    let thread: any;
+    if (o.resume) {
+      try {
+        thread = (await this.request("thread/resume", { threadId: o.resume.id, cwd: o.cwd, approvalPolicy: "on-request" })).thread;
+      } catch (e: any) {
+        this.emit({ type: "log", level: "warn", message: `resume failed (${e?.message ?? e}); starting a new thread` });
+      }
+    }
+    if (!thread) thread = (await this.request("thread/start", { cwd: o.cwd, approvalPolicy: "on-request" })).thread;
+    this.threadId = thread.id;
+    this.model = thread.model ?? undefined;
+    this.session = { agent: "codex", id: thread.id, cwd: o.cwd, startedAt: Date.now(), lastUsedAt: Date.now() };
+    const account: any = await this.request("account/read", {}).catch(() => null);
+    this.info = {
+      agent: "codex",
+      name: "Codex",
+      version: String(init?.userAgent ?? "").match(/\/(\d+\.\d+\.\d+)/)?.[1],
+      modes: [
+        { id: "on-request", name: "ask before risky actions" },
+        { id: "never", name: "full auto (no approvals)" },
+      ],
+      currentMode: "on-request",
+      models: [...new Set([this.model, "gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5"].filter(Boolean))].map((id) => ({ id: id!, name: id! })),
+      currentModel: this.model,
+      plan: account?.account?.planType ? `chatgpt ${account.account.planType}` : undefined,
+    };
+    this.emit({ type: "session", ref: this.session });
+    return this.info;
+  }
+
+  private spawn(cwd: string) {
+    const proc = Bun.spawn(platformArgv(this.opts.cmd ?? ["codex", "app-server"]), { cwd, env: agentEnv(), stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+    this.proc = proc;
+    void (async () => {
+      for await (const chunk of proc.stderr as ReadableStream<Uint8Array>) {
+        const s = new TextDecoder().decode(chunk).trim();
+        if (s && !/rmcp::transport|models_manager/.test(s)) this.emit({ type: "log", level: "info", message: s.slice(0, 500) });
+      }
+    })();
+    void proc.exited.then((code) => {
+      if (this.transport) this.emit({ type: "error", kind: "crashed", message: `codex app-server exited with code ${code}` });
+      if (this.turn) this.turn.resolve("error");
+    });
+    const sink: { cb: ((line: string) => void) | null } = { cb: null };
+    void (async () => {
+      let buf = "";
+      for await (const chunk of proc.stdout as ReadableStream<Uint8Array>) {
+        buf += new TextDecoder().decode(chunk);
+        let i: number;
+        while ((i = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, i);
+          buf = buf.slice(i + 1);
+          if (line.trim()) sink.cb?.(line);
+        }
+      }
+    })();
+    return {
+      send: (line: string) => {
+        (proc.stdin as any).write(line + "\n");
+        (proc.stdin as any).flush?.();
+      },
+      onLine: (f: (line: string) => void) => void (sink.cb = f),
+      close: async () => {
+        try {
+          proc.kill();
+        } catch {
+          /* gone */
+        }
+        await Promise.race([proc.exited, Bun.sleep(1500)]);
+      },
+    };
+  }
+
+  private request(method: string, params: unknown): Promise<any> {
+    return new Promise((resolve, reject) => {
+      const id = this.nextId++;
+      this.pending.set(id, { resolve, reject });
+      this.transport!.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+    });
+  }
+
+  private notify(method: string, params: unknown) {
+    this.transport!.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+  }
+
+  private onLine(line: string) {
+    let m: any;
+    try {
+      m = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (m.id !== undefined && m.method === undefined) {
+      const p = this.pending.get(m.id);
+      if (!p) return;
+      this.pending.delete(m.id);
+      if (m.error) p.reject(Object.assign(new Error(m.error.message ?? JSON.stringify(m.error)), { data: m.error }));
+      else p.resolve(m.result);
+      return;
+    }
+    if (m.id !== undefined && m.method) return this.onServerRequest(m);
+    if (m.method) this.onNotification(m.method, m.params ?? {});
+  }
+
+  private onServerRequest(m: any) {
+    const method: string = m.method;
+    if (/requestApproval|Approval/.test(method)) {
+      const id = `perm-${++this.permSeq}`;
+      this.pendingApprovals.set(id, { rpcId: m.id, method });
+      const p = m.params ?? {};
+      const what = method.includes("commandExecution") ? "Run command" : method.includes("fileChange") ? "Edit files" : method.replace(/^item\//, "").replace(/\/requestApproval$/, "");
+      const detail = p.command ? (Array.isArray(p.command) ? p.command.join(" ") : String(p.command)) : p.reason ?? (p.changes ? JSON.stringify(p.changes).slice(0, 1500) : undefined);
+      const request: PermissionRequest = {
+        id,
+        toolCallId: p.itemId,
+        kind: method.includes("commandExecution") ? "execute" : method.includes("fileChange") ? "edit" : "other",
+        title: what,
+        detail,
+        options: [
+          { id: "accept", label: "Allow once", kind: "allow_once" },
+          { id: "acceptForSession", label: "Allow for this session", kind: "allow_always" },
+          { id: "decline", label: "Deny", kind: "reject_once" },
+        ],
+      };
+      this.emit({ type: "permission_request", request });
+      return;
+    }
+    // Unknown server request: decline politely so the agent does not hang.
+    this.transport!.send(JSON.stringify({ jsonrpc: "2.0", id: m.id, error: { code: -32601, message: `codemax does not handle ${method}` } }));
+  }
+
+  private onNotification(method: string, p: any) {
+    switch (method) {
+      case "item/agentMessage/delta":
+        this.emit({ type: "text_delta", text: p.delta ?? "" });
+        break;
+      case "item/reasoning/delta":
+      case "item/reasoning/summaryDelta":
+      case "item/reasoning/textDelta":
+        this.emit({ type: "thought_delta", text: p.delta ?? "" });
+        break;
+      case "item/started":
+      case "item/completed":
+      case "item/updated": {
+        const it = p.item ?? {};
+        if (it.type === "agentMessage" || it.type === "userMessage" || it.type === "reasoning") break;
+        const status: ToolStatus = method === "item/started" ? "in_progress" : it.status === "failed" || it.status === "declined" ? "failed" : method === "item/completed" ? "completed" : "in_progress";
+        const title = it.type === "commandExecution" ? `$ ${Array.isArray(it.command) ? it.command.join(" ") : it.command ?? ""}` : it.type === "fileChange" ? `edit ${(it.changes ?? []).map((c: any) => c.path).join(", ")}` : it.type === "mcpToolCall" ? `${it.server}/${it.tool}` : it.type ?? "tool";
+        const detail = it.aggregatedOutput ? String(it.aggregatedOutput).slice(-800) : undefined;
+        const files = it.type === "fileChange" ? (it.changes ?? []).map((c: any) => c.path).filter(Boolean) : undefined;
+        const input = it.type === "commandExecution" ? { command: Array.isArray(it.command) ? it.command.join(" ") : it.command, cwd: it.cwd } : it.type === "mcpToolCall" ? it.arguments : undefined;
+        const changeDiffs = it.type === "fileChange" ? (it.changes ?? []).map((c: any) => c.diff ?? c.unified_diff ?? "").filter(Boolean).join("\n") : "";
+        const output = it.aggregatedOutput ? String(it.aggregatedOutput) : changeDiffs || undefined;
+        if (method === "item/started") this.emit({ type: "tool_call", id: it.id, title, kind: it.type, status, detail, input, files });
+        else this.emit({ type: "tool_update", id: it.id, status, title, detail, input, files, output });
+        break;
+      }
+      case "item/commandExecution/outputDelta":
+        this.emit({ type: "tool_update", id: p.itemId, detail: p.delta });
+        break;
+      case "turn/plan/updated":
+      case "item/plan/updated":
+        this.emit({ type: "plan", entries: (p.plan ?? p.entries ?? []).map((e: any) => ({ content: e.step ?? e.content, status: e.status })) });
+        break;
+      case "thread/tokenUsage/updated":
+      case "turn/tokenUsage/updated": {
+        const rl = p.rateLimits ?? p.tokenUsage?.rateLimits;
+        const used = rl?.primary?.usedPercent ?? rl?.primary?.used_percent;
+        const t = p.tokenUsage?.total;
+        if (t) {
+          // Totals are cumulative for the thread; emit the delta. Codex's inputTokens include cached ones.
+          const d = {
+            inputTokens: Math.max(0, (t.inputTokens ?? 0) - this.lastTotals.inputTokens),
+            cachedInputTokens: Math.max(0, (t.cachedInputTokens ?? 0) - this.lastTotals.cachedInputTokens),
+            cacheWriteInputTokens: Math.max(0, (t.cacheWriteInputTokens ?? 0) - this.lastTotals.cacheWriteInputTokens),
+            outputTokens: Math.max(0, (t.outputTokens ?? 0) - this.lastTotals.outputTokens),
+          };
+          this.lastTotals = { inputTokens: t.inputTokens ?? 0, cachedInputTokens: t.cachedInputTokens ?? 0, cacheWriteInputTokens: t.cacheWriteInputTokens ?? 0, outputTokens: t.outputTokens ?? 0 };
+          if (d.inputTokens || d.outputTokens) {
+            this.emit({
+              type: "usage",
+              inputTokens: Math.max(0, d.inputTokens - d.cachedInputTokens),
+              cacheReadTokens: d.cachedInputTokens,
+              cacheWriteTokens: d.cacheWriteInputTokens,
+              outputTokens: d.outputTokens,
+              model: this.model,
+              usedPercent: typeof used === "number" ? used : undefined,
+              contextSize: p.tokenUsage?.modelContextWindow,
+            });
+          }
+        } else if (typeof used === "number") this.emit({ type: "usage", usedPercent: used });
+        break;
+      }
+      case "turn/completed": {
+        const status = p.turn?.status;
+        const err = p.turn?.error;
+        if (err) this.emit({ type: "error", kind: classify(JSON.stringify(err)), message: err.message ?? JSON.stringify(err) });
+        const reason: StopReason = status === "completed" ? "end_turn" : status === "interrupted" || status === "cancelled" ? "cancelled" : err ? "error" : "other";
+        this.finishTurn(reason);
+        break;
+      }
+      case "turn/error":
+      case "error": {
+        const msg = p.error?.message ?? p.message ?? JSON.stringify(p);
+        this.emit({ type: "error", kind: classify(msg), message: msg });
+        break;
+      }
+      case "serverRequest/resolved": {
+        for (const [id, a] of this.pendingApprovals) if (String(a.rpcId) === String(p.requestId)) this.pendingApprovals.delete(id);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  private finishTurn(reason: StopReason) {
+    const t = this.turn;
+    this.turn = null;
+    if (this.session) this.session.lastUsedAt = Date.now();
+    this.emit({ type: "turn_end", stopReason: reason });
+    t?.resolve(reason);
+  }
+
+  async prompt(text: string): Promise<StopReason> {
+    if (!this.transport || !this.threadId) throw new Error("engine not started");
+    const done = new Promise<StopReason>((resolve) => (this.turn = { resolve }));
+    try {
+      const approvalPolicy = this.info?.currentMode === "never" ? "never" : "on-request";
+      const res = await this.request("turn/start", { threadId: this.threadId, cwd: this.cwd, input: [{ type: "text", text }], model: this.model, approvalPolicy });
+      if (this.turn) this.turn.id = res?.turn?.id;
+    } catch (e: any) {
+      const msg = `${e?.message ?? e} ${JSON.stringify(e?.data ?? "")}`.trim();
+      this.emit({ type: "error", kind: classify(msg), message: msg });
+      this.finishTurn("error");
+    }
+    return done;
+  }
+
+  answerPermission(requestId: string, optionId: string) {
+    const a = this.pendingApprovals.get(requestId);
+    if (!a) return;
+    this.pendingApprovals.delete(requestId);
+    this.transport!.send(JSON.stringify({ jsonrpc: "2.0", id: a.rpcId, result: { decision: optionId } }));
+  }
+
+  async cancel() {
+    if (!this.transport || !this.threadId || !this.turn) return;
+    for (const [id] of this.pendingApprovals) this.answerPermission(id, "cancel");
+    await this.request("turn/interrupt", { threadId: this.threadId, turnId: this.turn.id }).catch(() => {});
+  }
+
+  async setMode(modeId: string) {
+    // Applied on the next turn via approvalPolicy; kept for parity with ACP modes.
+    if (this.info) this.info.currentMode = modeId;
+    this.emit({ type: "mode", modeId });
+  }
+
+  /** Codex takes the model per turn; it applies from the next prompt. */
+  async setModel(modelId: string) {
+    this.model = modelId;
+    if (this.info) this.info.currentModel = modelId;
+  }
+
+  async close() {
+    const t = this.transport;
+    this.transport = null;
+    for (const [id] of this.pendingApprovals) this.answerPermission(id, "cancel");
+    if (this.turn) this.finishTurn("cancelled");
+    await t?.close();
+  }
+}
+
+function classify(msg: string) {
+  return classifyError(msg);
+}

package/src/engines/env.ts

@@ -0,0 +1,17 @@
+/**
+ * Environment for agent subprocesses. Subscriptions only: vendor API keys are
+ * removed so each agent uses its login. Nested-session markers from a parent
+ * Claude Code / Codex session are removed too. CLAUDE_CODE_EXECUTABLE is kept
+ * on purpose: the Claude ACP adapter uses it to run the user's own `claude`.
+ */
+const STRIP = /^(ANTHROPIC_API_KEY|ANTHROPIC_AUTH_TOKEN|OPENAI_API_KEY|CURSOR_API_KEY|XAI_API_KEY|GROK_API_KEY|GEMINI_API_KEY|GOOGLE_API_KEY|CLAUDECODE|CLAUDE_PID|CLAUDE_EFFORT|CODEX_SANDBOX|CODEX_THREAD_ID)$|^CLAUDE_CODE_(?!EXECUTABLE$)/;
+
+export function agentEnv(extra: Record<string, string> = {}): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) if (v !== undefined && !STRIP.test(k)) env[k] = v;
+  return { ...env, ...extra };
+}
+
+export function strippedKeys(): string[] {
+  return Object.keys(process.env).filter((k) => /API_KEY|AUTH_TOKEN/.test(k) && STRIP.test(k));
+}

package/src/engines/errors.ts

@@ -0,0 +1,47 @@
+import type { ErrorKind } from "./types.ts";
+
+/**
+ * Wording agents use when a subscription runs out. Claude Code says "You've hit
+ * your session limit · resets 3pm" or "Claude AI usage limit reached"; Codex
+ * "You've hit your usage limit"; Grok "free-usage-exhausted" / 429.
+ */
+const QUOTA = /usage limit|session limit|weekly limit|daily limit|monthly limit|hit your limit|limit reached|limit · resets|out of (credits|quota)|quota|rate.?limit|too many requests|\b429\b|insufficient|usage[-_ ]exhausted|credits? (exhausted|depleted)/i;
+const AUTH = /\bauth|login|unauthori[sz]ed|\b401\b|not logged in/i;
+
+/** The human part of an agent error: drops "Internal error" and unwraps {"details": "..."} / {"message": "..."}. */
+export function cleanError(text: string): string {
+  const m = text.match(/"(?:details|message)"\s*:\s*"((?:[^"\\]|\\.)+)"/);
+  const inner = m ? m[1]!.replace(/\\"/g, '"') : text;
+  return inner.replace(/^\s*(internal error|error)[:\s]*/i, "").trim() || text.trim();
+}
+
+export function classifyError(text: string): ErrorKind {
+  if (QUOTA.test(text)) return "quota";
+  if (AUTH.test(text)) return "auth";
+  return "protocol";
+}
+
+/**
+ * A whole reply that is only a limit notice (some agents end the turn normally
+ * and put the notice in the message instead of raising an error).
+ */
+export function isLimitNotice(reply: string): boolean {
+  const t = reply.trim();
+  return t.length > 0 && t.length < 400 && /^(you've|you have) (hit|reached) your (session|usage|weekly|daily|monthly)? ?limit|^claude ai usage limit reached|^(session|usage|weekly) limit (reached|hit)/i.test(t);
+}
+
+/** "resets 3pm", "resets 6:30 pm", "resets at 15:00" → next such time, as epoch ms. */
+export function parseResetTime(text: string, now = new Date()): number | undefined {
+  const m = text.match(/resets?(?: at)? (\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i);
+  if (!m) return undefined;
+  let h = Number(m[1]);
+  const min = Number(m[2] ?? 0);
+  const ap = m[3]?.toLowerCase();
+  if (ap === "pm" && h < 12) h += 12;
+  if (ap === "am" && h === 12) h = 0;
+  if (h > 23 || min > 59) return undefined;
+  const d = new Date(now);
+  d.setHours(h, min, 0, 0);
+  if (d.getTime() <= now.getTime()) d.setDate(d.getDate() + 1);
+  return d.getTime();
+}

package/src/engines/index.ts

@@ -0,0 +1,154 @@
+import { basename, dirname, join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import type { AgentId } from "../adapters/types.ts";
+import type { Engine, EngineFactory } from "./types.ts";
+import { AcpEngine, type UsageSample } from "./acp.ts";
+import { CodexEngine } from "./codex.ts";
+import { ClaudeUsageTail } from "../transcripts/claude-usage.ts";
+
+/** Grok writes ~/.grok/sessions/<encoded cwd>/<session>/usage.json with per-turn totals. */
+function grokUsageTail(cwd: string, sessionId: string): { read(): UsageSample[] } {
+  const path = join(homedir(), ".grok", "sessions", encodeURIComponent(cwd), sessionId, "usage.json");
+  let seen = 0;
+  return {
+    read() {
+      if (!existsSync(path)) return [];
+      let j: any;
+      try {
+        j = JSON.parse(readFileSync(path, "utf8"));
+      } catch {
+        return [];
+      }
+      const turns: any[] = j.turns ?? [];
+      const fresh = turns.slice(seen);
+      seen = turns.length;
+      return fresh.map((t) => ({
+        model: t.primaryModelId ?? j.session?.primaryModelId,
+        input: Math.max(0, (t.inputTokens ?? 0) - (t.cachedReadTokens ?? 0)),
+        cacheRead: t.cachedReadTokens ?? 0,
+        cacheWrite: t.cacheCreationTokens ?? 0,
+        output: t.outputTokens ?? 0,
+        costUsd: typeof t.costUsdTicks === "number" ? t.costUsdTicks / 1e10 : undefined,
+      }));
+    },
+  };
+}
+
+const CLAUDE_ADAPTER_PKG = "@agentclientprotocol/claude-agent-acp@0.93.0";
+
+/**
+ * Command for the Claude ACP adapter (it runs the user's own `claude`).
+ * From a source checkout it is in node_modules; from the compiled binary it is
+ * fetched once by bunx and cached.
+ */
+function claudeAdapterCmd(): string[] | null {
+  const runningOnBun = basename(process.execPath).toLowerCase().startsWith("bun");
+  if (process.platform !== "win32") {
+    const candidates = [
+      join(import.meta.dir, "..", "..", "node_modules", ".bin", "claude-agent-acp"),
+      join(process.cwd(), "node_modules", ".bin", "claude-agent-acp"),
+    ];
+    for (const c of candidates) if (existsSync(c)) return [c];
+  }
+  // The installed package's own entry, run with this Bun: works where .bin shims
+  // do not (Windows) and when no `bun` is on PATH (installed through npm).
+  if (runningOnBun) {
+    try {
+      const pkgJson = Bun.resolveSync("@agentclientprotocol/claude-agent-acp/package.json", import.meta.dir);
+      const bin = JSON.parse(readFileSync(pkgJson, "utf8")).bin;
+      const entry = typeof bin === "string" ? bin : bin?.["claude-agent-acp"];
+      if (entry && existsSync(join(dirname(pkgJson), entry))) return [process.execPath, join(dirname(pkgJson), entry)];
+    } catch {
+      /* not installed next to codemax */
+    }
+  }
+  const onPath = Bun.which("claude-agent-acp");
+  if (onPath) return [onPath];
+  const bun = Bun.which("bun") ?? (runningOnBun ? process.execPath : null);
+  const bunx = Bun.which("bunx") ? [Bun.which("bunx")!] : bun ? [bun, "x"] : null;
+  return bunx ? [...bunx, CLAUDE_ADAPTER_PKG] : null;
+}
+
+const factories: EngineFactory[] = [
+  {
+    agent: "claude",
+    available: async () => !!Bun.which("claude") && !!claudeAdapterCmd(),
+    create: () =>
+      new AcpEngine({
+        agent: "claude",
+        name: "Claude Code",
+        cmd: claudeAdapterCmd()!,
+        env: { CLAUDE_CODE_EXECUTABLE: Bun.which("claude")! },
+        usageTail: (s) => new ClaudeUsageTail(s.cwd, s.id),
+      }),
+  },
+  {
+    agent: "codex",
+    available: async () => !!Bun.which("codex"),
+    create: () => new CodexEngine(),
+  },
+  {
+    agent: "opencode",
+    available: async () => !!Bun.which("opencode"),
+    // OpenCode's defaults allow edits and shell without asking. Over ACP it honours an inline
+    // config, so codemax makes it ask for anything that changes state; reads stay silent.
+    create: () =>
+      new AcpEngine({
+        agent: "opencode",
+        name: "OpenCode",
+        cmd: ["opencode", "acp"],
+        env: { OPENCODE_CONFIG_CONTENT: JSON.stringify({ permission: { "*": "ask", read: "allow", glob: "allow", grep: "allow", list: "allow", todowrite: "allow", todoread: "allow", webfetch: "ask" } }) },
+      }),
+  },
+  {
+    agent: "grok",
+    available: async () => !!Bun.which("grok"),
+    // Grok takes its permission mode from the user's Claude Code settings; see grokPermissionNote().
+    create: () => new AcpEngine({ agent: "grok", name: "Grok", cmd: ["grok", "agent", "stdio"], permissionPrompts: !grokPermissionNote(), usageTail: (s) => grokUsageTail(s.cwd, s.id) }),
+  },
+  {
+    agent: "cursor",
+    available: async () => !!Bun.which("cursor-agent"),
+    // `cursor-agent acp` (Cursor Agent 2026.10+) asks before shell commands and edits, and
+    // exposes its modes (agent / plan / ask) and models as ACP config options.
+    create: () => new AcpEngine({ agent: "cursor", name: "Cursor Agent", cmd: ["cursor-agent", "acp"] }),
+  },
+  {
+    agent: "gemini",
+    available: async () => !!Bun.which("gemini"),
+    create: () => new AcpEngine({ agent: "gemini", name: "Gemini CLI", cmd: ["gemini", "--experimental-acp"] }),
+  },
+];
+
+/**
+ * Grok applies Claude Code's settings files as its permission source (seen in
+ * `grok inspect`). With `permissions.defaultMode: "auto"` there it rarely asks.
+ * Returns a note for the user when that is the case, else null.
+ */
+export function grokPermissionNote(): string | null {
+  for (const f of [join(homedir(), ".claude", "settings.local.json"), join(homedir(), ".claude", "settings.json")]) {
+    try {
+      const mode = JSON.parse(readFileSync(f, "utf8"))?.permissions?.defaultMode;
+      if (mode && mode !== "default") return `Grok follows your Claude Code settings (${f}): defaultMode is "${mode}", so it will act without asking. Set it to "default" there to get prompts.`;
+    } catch {
+      /* missing or unreadable */
+    }
+  }
+  return null;
+}
+
+/** Agents whose protocol never asks before acting on this machine; shown as a warning in the menu. */
+export const NO_PERMISSION_PROMPTS: ReadonlySet<AgentId> = new Set(grokPermissionNote() ? ["grok"] : []);
+
+export const engineFactories: Partial<Record<AgentId, EngineFactory>> = Object.fromEntries(factories.map((f) => [f.agent, f]));
+
+export function hasEngine(agent: AgentId): boolean {
+  return !!engineFactories[agent];
+}
+
+export function createEngine(agent: AgentId): Engine {
+  const f = engineFactories[agent];
+  if (!f) throw new Error(`no protocol engine for ${agent}`);
+  return f.create();
+}

package/src/engines/types.ts

@@ -0,0 +1,131 @@
+import type { AgentId } from "../adapters/types.ts";
+
+/** One normalized stream that every protocol (ACP, Codex app-server, …) is mapped onto. */
+export type EngineEvent =
+  /** `messageId` changes between separate agent messages (e.g. before and after a tool call). */
+  | { type: "text_delta"; text: string; messageId?: string }
+  | { type: "thought_delta"; text: string; messageId?: string }
+  /**
+   * `detail` is a short display string. `input` (the tool's raw arguments), `output`
+   * (its full text result) and `files` are carried uncut for the journal, which caps them.
+   */
+  | { type: "tool_call"; id: string; title: string; kind?: string; status: ToolStatus; detail?: string; input?: unknown; output?: string; files?: string[] }
+  | { type: "tool_update"; id: string; status?: ToolStatus; title?: string; detail?: string; input?: unknown; output?: string; files?: string[] }
+  | { type: "permission_request"; request: PermissionRequest }
+  | { type: "plan"; entries: { content: string; status: string; priority?: string }[] }
+  | { type: "mode"; modeId: string }
+  | { type: "commands"; commands: { name: string; description?: string }[] }
+  | {
+      type: "usage";
+      /** Incremental token counts for the work just done (never cumulative). */
+      inputTokens?: number;
+      outputTokens?: number;
+      cacheReadTokens?: number;
+      cacheWriteTokens?: number;
+      model?: string;
+      /** Incremental cost the agent itself reported, in USD. */
+      costUsd?: number;
+      /** Rate-limit window consumption, when the agent exposes it. */
+      usedPercent?: number;
+      /** Context window fill, when reported (tokens used / size). */
+      contextUsed?: number;
+      contextSize?: number;
+    }
+  | { type: "session"; ref: EngineSessionRef }
+  | { type: "turn_end"; stopReason: StopReason }
+  | { type: "error"; kind: ErrorKind; message: string }
+  | { type: "log"; level: "info" | "warn" | "error"; message: string };
+
+export type ToolStatus = "pending" | "in_progress" | "completed" | "failed";
+export type StopReason = "end_turn" | "max_tokens" | "cancelled" | "refusal" | "error" | "other";
+export type ErrorKind = "quota" | "auth" | "protocol" | "crashed" | "other";
+
+export interface PermissionOption {
+  id: string;
+  label: string;
+  /** allow_once | allow_always | reject_once | reject_always */
+  kind: string;
+}
+
+export interface PermissionRequest {
+  id: string;
+  toolCallId?: string;
+  /** ACP tool kind when known: read | edit | delete | move | search | execute | think | fetch | other */
+  kind?: string;
+  title: string;
+  detail?: string;
+  options: PermissionOption[];
+}
+
+export interface EngineSessionRef {
+  agent: AgentId;
+  /** Vendor session / thread id, used to resume. */
+  id: string;
+  cwd: string;
+  startedAt: number;
+  lastUsedAt: number;
+}
+
+export interface EngineMode {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+export interface EngineStartOptions {
+  cwd: string;
+  /** Resume a previous session instead of starting a new one. */
+  resume?: EngineSessionRef;
+}
+
+export interface EngineInfo {
+  agent: AgentId;
+  name: string;
+  version?: string;
+  modes: EngineMode[];
+  currentMode?: string;
+  models?: { id: string; name: string }[];
+  currentModel?: string;
+  /** Subscription plan name when the agent reports one (e.g. "chatgpt pro"). */
+  plan?: string;
+  /** Other settings the agent exposes as selects, e.g. Grok's reasoning effort. */
+  options?: EngineOption[];
+}
+
+export interface EngineOption {
+  id: string;
+  name: string;
+  /** ACP category, e.g. "thought_level" for reasoning effort. */
+  category?: string;
+  current?: string;
+  values: { value: string; name: string; description?: string }[];
+}
+
+/**
+ * A running agent process spoken to over a protocol. One engine = one agent
+ * session. Events arrive through `onEvent`; permission requests must be
+ * answered with `answerPermission` or the agent stays blocked.
+ */
+export interface Engine {
+  readonly agent: AgentId;
+  readonly info: EngineInfo | null;
+  readonly session: EngineSessionRef | null;
+  onEvent(listener: (e: EngineEvent) => void): () => void;
+  start(opts: EngineStartOptions): Promise<EngineInfo>;
+  /** Send one user turn. Resolves when the turn ends (turn_end has been emitted). */
+  prompt(text: string): Promise<StopReason>;
+  answerPermission(requestId: string, optionId: string): void;
+  cancel(): Promise<void>;
+  setMode?(modeId: string): Promise<void>;
+  setModel?(modelId: string): Promise<void>;
+  /** Change one of `info.options` (e.g. reasoning effort). */
+  setOption?(optionId: string, value: string): Promise<void>;
+  close(): Promise<void>;
+}
+
+export interface EngineFactory {
+  agent: AgentId;
+  /** True when the binary (or adapter) this engine needs is available. */
+  available(): Promise<boolean>;
+  create(): Engine;
+}