cookbook-bridge 0.1.0

package/codex-runner.mjs

@@ -0,0 +1,241 @@
+/**
+ * Codex runner — drives OpenAI's Codex CLI autonomously with FULL Cookbook MCP.
+ *
+ * Why app-server: `codex exec` auto-cancels every MCP tool call in headless mode
+ * (OpenAI bug #16685 — closed stdin reads as "user declined"). The app-server
+ * JSON-RPC interface answers approvals explicitly, so tools work.
+ *
+ * v2 (chat lane, 2026-08-21): the server is now PERSISTENT — one process, one
+ * handshake, reused across turns — and Cookbook threads map to Codex threads, so
+ * a follow-up turn CONTINUES the same Codex conversation (claude-resume parity).
+ * Agent-message deltas stream out via onProgress as live_text. Codex Perplexity
+ * lane: boot once, then every turn is model time.
+ *
+ * SECURITY UNCHANGED from v1 (audit 2026-07-03): elicitations/input requests are
+ * accepted (that's what lets MCP tools run), but exec/patch APPROVALS are always
+ * DECLINED — with approvalPolicy "never" those only arrive as requests to escalate
+ * beyond the sandbox, and the sandbox is the boundary only if we never approve
+ * leaving it.
+ *
+ * Node built-ins only.
+ */
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+import { spawn } from "node:child_process";
+
+const IDLE_MS = 15 * 60_000;
+const LIVE_TEXT_CAP = 1800;
+
+let server = null; // one persistent app-server per Bridge
+const codexThreads = new Map(); // cookbook threadKey -> codex threadId
+
+/** Does a live Codex conversation exist for this Cookbook thread? (Prompt shaping:
+ *  resumed follow-ups skip the cold baton.) */
+export function hasCodexThread(threadKey) {
+  return !!(server && !server.dead && codexThreads.has(threadKey));
+}
+
+export function killCodexServer() {
+  if (server) {
+    server.kill();
+    server = null;
+  }
+  codexThreads.clear();
+}
+
+/** Reap the server after idleness (call from the Bridge's janitor tick). */
+export function reapCodexServer(log) {
+  if (server && !server.dead && !server.turn && Date.now() - server.lastUsedAt > IDLE_MS) {
+    log?.("  ↳ codex app-server reaped (idle)");
+    killCodexServer();
+  }
+}
+
+class CodexServer {
+  constructor(agent, env, log) {
+    const codexBin = (agent.command && agent.command[0]) || "codex";
+    const codexHome = agent.codexHome || path.join(os.homedir(), ".codex-bridge");
+    this.cwd = path.join(os.tmpdir(), "codex-bridge-work");
+    try { fs.mkdirSync(this.cwd, { recursive: true }); } catch { /* best effort */ }
+    this.agent = agent;
+    this.log = log;
+    this.dead = false;
+    this.turn = null; // the single in-flight turn's handlers
+    this.queue = Promise.resolve(); // turns serialize on this chain
+    this.nextId = 10;
+    this.pending = new Map(); // request id -> {resolve, reject}
+    this.lastUsedAt = Date.now();
+    this.buf = "";
+    this.child = spawn(codexBin, ["app-server"], { env: { ...env, CODEX_HOME: codexHome }, stdio: ["pipe", "pipe", "pipe"] });
+    this.child.stderr.on("data", () => {});
+    this.child.on("error", (e) => this.#die(new Error(`could not launch \`${codexBin} app-server\`: ${e.message}`)));
+    this.child.on("close", () => this.#die(new Error("codex app-server exited")));
+    this.child.stdout.on("data", (d) => this.#onData(String(d)));
+    // Handshake once for the process lifetime.
+    this.ready = this.request("initialize", {
+      clientInfo: { name: "cookbook-bridge", title: "Cookbook Bridge", version: "0.2.0" },
+      capabilities: { experimentalApi: true, mcpServerOpenaiFormElicitation: true },
+    }).then(() => { this.notify("initialized"); });
+  }
+
+  #die(err) {
+    if (this.dead) return;
+    this.dead = true;
+    for (const [, p] of this.pending) p.reject(err);
+    this.pending.clear();
+    const t = this.turn;
+    this.turn = null;
+    if (t) t.reject(err);
+  }
+
+  kill() {
+    this.dead = true;
+    try { this.child.kill("SIGTERM"); } catch { /* gone */ }
+    setTimeout(() => { try { this.child.kill("SIGKILL"); } catch { /* gone */ } }, 3000);
+  }
+
+  send(o) {
+    try { this.child.stdin.write(JSON.stringify(o) + "\n"); } catch { /* closed */ }
+  }
+
+  request(method, params) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.send({ id, method, params });
+    });
+  }
+
+  notify(method, params) {
+    this.send(params === undefined ? { method } : { method, params });
+  }
+
+  #onData(chunk) {
+    this.buf += chunk;
+    let i;
+    while ((i = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, i);
+      this.buf = this.buf.slice(i + 1);
+      if (!line.trim()) continue;
+      let m;
+      try { m = JSON.parse(line); } catch { continue; }
+      const meth = m.method || "";
+
+      // Server→client REQUESTS (id + method): tool elicitations accepted, sandbox
+      // escalation approvals DECLINED — see header; semantics identical to v1.
+      if (m.id !== undefined && meth) {
+        if (/elicitation\/request$/.test(meth)) this.send({ id: m.id, result: { action: "accept" } });
+        else if (/requestUserInput$/.test(meth)) this.send({ id: m.id, result: { answers: [{ value: "accept" }] } });
+        else if (/requestApproval$|Approval$/.test(meth)) this.send({ id: m.id, result: "decline" });
+        continue;
+      }
+
+      // RESPONSES to our requests.
+      if (m.id !== undefined && (m.result !== undefined || m.error)) {
+        const p = this.pending.get(m.id);
+        if (p) {
+          this.pending.delete(m.id);
+          if (m.error) p.reject(new Error(`codex app-server error: ${m.error.message || JSON.stringify(m.error).slice(0, 200)}`));
+          else p.resolve(m.result);
+        }
+        continue;
+      }
+
+      // NOTIFICATIONS — routed to the single in-flight turn.
+      const t = this.turn;
+      if (!t) continue;
+      t.lastActivityAt = Date.now();
+      if (meth === "item/agentMessage/delta" && m.params && m.params.delta) {
+        t.text += m.params.delta;
+        t.emit();
+      }
+      if (m.params) {
+        const u = m.params.usage ?? m.params.tokenUsage ?? m.params.token_usage ?? (m.params.turn && m.params.turn.usage);
+        if (u && typeof u === "object") t.usage = u;
+      }
+      if (meth === "turn/completed" || meth === "turn/failed") {
+        const status = (m.params && m.params.turn && m.params.turn.status) || meth;
+        this.turn = null;
+        this.lastUsedAt = Date.now();
+        clearInterval(t.watchdog);
+        t.resolve({ status, out: t.text.trim(), usage: t.usage });
+      }
+    }
+  }
+
+  /** Run one turn (serialized). threadKey maps to a persistent Codex thread —
+   *  reused when known, created otherwise. */
+  runTurn({ threadKey, prompt, timeoutSeconds, onProgress, cwd }) {
+    const exec = async () => {
+      if (this.dead) throw new Error("codex app-server is dead");
+      await this.ready;
+      let threadId = codexThreads.get(threadKey);
+      if (!threadId) {
+        // Per-THREAD cwd: local-access threads live in the mapped folder (the
+        // workspace-write sandbox is the wall); jailed threads use the tmp dir.
+        const r = await this.request("thread/start", {
+          cwd: cwd || this.cwd,
+          sandbox: this.agent.sandbox || "workspace-write",
+          approvalPolicy: "never",
+        });
+        threadId = r && r.thread && r.thread.id;
+        if (!threadId) throw new Error("codex app-server: thread/start returned no thread id");
+        codexThreads.set(threadKey, threadId);
+      } else {
+        this.log?.(`  ↳ continuing the codex conversation (thread reuse)`);
+      }
+      return await new Promise((resolve, reject) => {
+        const startedAt = Date.now();
+        const t = {
+          resolve, reject,
+          text: "", usage: null,
+          lastEmit: 0, lastActivityAt: startedAt,
+          emit: () => {
+            if (!onProgress || Date.now() - t.lastEmit < 1200) return;
+            t.lastEmit = Date.now();
+            const tail = t.text.length > LIVE_TEXT_CAP ? "…" + t.text.slice(-LIVE_TEXT_CAP) : t.text;
+            try { onProgress({ input_tokens: 0, output_tokens: 0, runner: this.agent.name, ...(tail ? { live_text: tail } : {}) }); } catch { /* best-effort */ }
+          },
+          watchdog: setInterval(() => {
+            if (Date.now() - startedAt < timeoutSeconds * 1000) return;
+            clearInterval(t.watchdog);
+            if (this.turn === t) this.turn = null;
+            reject(new Error(`timed out after ${timeoutSeconds}s`));
+          }, 5000),
+        };
+        this.turn = t;
+        this.request("turn/start", {
+          threadId,
+          input: [{ type: "text", text: prompt, text_elements: [] }],
+        }).catch((e) => {
+          clearInterval(t.watchdog);
+          if (this.turn === t) this.turn = null;
+          reject(e);
+        });
+      });
+    };
+    // Serialize turns; a failed turn must not break the chain for the next one.
+    const run = this.queue.then(exec, exec);
+    this.queue = run.catch(() => {});
+    return run;
+  }
+}
+
+/**
+ * Run a Codex turn against the persistent server (booted on first use, kept warm).
+ * Signature kept close to v1's runCodexTask; extra opts carry the thread key and
+ * the live-progress sink. Falls back to a fresh server if the old one died.
+ */
+export function runCodexTask(agent, prompt, timeoutSeconds, token, baseEnv, onProgress, opts = {}) {
+  const env = { ...(baseEnv ?? process.env) };
+  if (token) env.COOKBOOK_CODEX_TOKEN = token;
+  if (!server || server.dead) server = new CodexServer(agent, env, opts.log);
+  return server.runTurn({
+    threadKey: opts.threadKey ?? `oneshot::${Date.now()}`,
+    prompt,
+    timeoutSeconds,
+    onProgress,
+    cwd: agent.cwd,
+  });
+}

package/config.example.json

@@ -0,0 +1,83 @@
+{
+  "cookbookUrl": "https://cookbook.team",
+  "token": "PASTE_YOUR_COOKBOOK_TOKEN_HERE",
+  "pollSeconds": 15,
+  "maxAttempts": 2,
+  "taskTimeoutSeconds": 3600,
+  "_timeouts": "taskTimeoutSeconds is the ABSOLUTE ceiling per run (cost backstop). livenessTimeoutSeconds kills a STALLED run \u2014 no output for this many seconds (streaming runs only). Healthy long work runs to the ceiling; silence dies fast.",
+  "livenessTimeoutSeconds": 300,
+  "_concurrency": "How many task runs may be in flight at once. Runs launch in parallel up to this cap; the atomic pre-claim keeps every task single-runner.",
+  "maxConcurrentRuns": 2,
+  "_billing": "Agents run on the CLI subscriptions you already pay for. The Bridge hides ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY from agent processes so a task can never silently bill your API account instead. Set allowApiKeyBilling to true ONLY if you explicitly want API-key billing.",
+  "allowApiKeyBilling": false,
+  "_volunteering": "STIGMERGY (off by default): an agent with volunteer:true watches tasks posted as open GOALS (to:'goal' on the board) and may claim ones matching its capabilities \u2014 decided by one cheap call to the agent's own CLI, gated by your delegation policy (ask parks it in your approvals inbox), claimed atomically, capped per poll. Flip volunteering:false to kill it globally without touching agents.",
+  "volunteering": true,
+  "_autoUpdate": "The Bridge follows the app: it checks the deploy's file manifest at startup + every 6h, and self-updates (hash-verified, originals kept in bridge.backup/, your config/token never touched) then restarts itself. Set false to pin your version and update manually with `node bridge.mjs update`.",
+  "autoUpdate": true,
+  "default": "Gemini",
+  "_acceptFrom": "Who may auto-run tasks on this Bridge: \"anyone\", or a list of EXACT member names or profile ids (case-insensitive, no partial matching \u2014 consent never guesses).",
+  "acceptFrom": "anyone",
+  "agents": [
+    {
+      "name": "Gemini",
+      "match": [
+        "gemini",
+        "antigravity",
+        "agy"
+      ],
+      "enabled": true,
+      "command": [
+        "agy",
+        "-p",
+        "{prompt}",
+        "--sandbox",
+        "--print-timeout",
+        "3600s"
+      ],
+      "_setup": "Gemini runs via the Antigravity CLI (agy) \u2014 the old `gemini` CLI stopped serving individual accounts June 18 2026. Requires agy >= 1.1.1 (first version whose headless -p can call MCP tools; the Bridge refuses older). Auth: run `agy` once interactively and sign in with Google. MCP: `node bridge/bridge.mjs connect-agents` writes ~/.gemini/config/mcp_config.json (agy has no `mcp add`). --sandbox keeps terminal restrictions on \u2014 Cookbook work flows through MCP tools, not the shell. Keep --print-timeout >= taskTimeoutSeconds (ceiling) so agy doesn't cut off before the Bridge's own timeout.",
+      "_usage": "agy emits no token/usage JSON \u2014 the board shows wall-clock duration for its runs (no token count)."
+    },
+    {
+      "name": "Claude",
+      "match": [
+        "claude"
+      ],
+      "enabled": true,
+      "volunteer": false,
+      "capabilities": "TypeScript/Next.js, Supabase, research & writing. Avoid: iOS/Swift, design.",
+      "command": [
+        "claude",
+        "-p",
+        "{prompt}",
+        "--allowedTools",
+        "mcp__cookbook__*",
+        "--output-format",
+        "json"
+      ],
+      "_allowedTools": "The prefix matches HOW your Claude is connected to Cookbook: a CLI-added server (claude mcp add ... cookbook ...) exposes mcp__cookbook__*; the claude.ai/desktop CONNECTOR exposes mcp__claude_ai_Cookbook__*. If tasks run but never complete, this mismatch is the usual cause \u2014 `node bridge.mjs doctor` checks it.",
+      "_output": "json output lets the Bridge report what each task cost (tokens/$) back to the board \u2014 text works too, you just lose the usage report"
+    },
+    {
+      "name": "Codex",
+      "match": [
+        "codex",
+        "chatgpt"
+      ],
+      "enabled": false,
+      "runner": "app-server",
+      "command": [
+        "/Applications/ChatGPT.app/Contents/Resources/codex"
+      ],
+      "_binary": "Codex merged into the ChatGPT desktop app (July 2026) \u2014 older installs had /Applications/Codex.app/Contents/Resources/codex. If doctor says 'binary not found', check both paths.",
+      "sandbox": "workspace-write",
+      "_setup": "Codex (ChatGPT) via codex app-server \u2014 its headless `exec` can't call MCP tools (OpenAI #16685), so the Bridge drives the app-server protocol and auto-approves tool elicitations (bridge/codex-runner.mjs). To enable: (1) make a clean CODEX_HOME at ~/.codex-bridge with config.toml [mcp_servers.cookbook] (url=<cookbookUrl>/api/mcp, bearer_token_env_var=COOKBOOK_CODEX_TOKEN) and a copy of ~/.codex/auth.json so it uses your ChatGPT login; (2) add a Cookbook token here as \"token\" (separate from the Bridge token, so Codex's work is attributed to Codex); (3) optionally set \"codexHome\" if not ~/.codex-bridge; (4) set enabled:true."
+    }
+  ],
+  "persistentThreads": true,
+  "localWorkspaces": {
+    "<workspace-id>": {
+      "cwd": "/absolute/path/to/project",
+      "allowedTools": null
+    }
+  }
+}

package/connectors.mjs

@@ -0,0 +1,157 @@
+/**
+ * CONNECTOR SYNC — connect a tool once, every one of your agents has it.
+ *
+ * Today MCP connectors are configured per vendor, in three places, in three
+ * different shapes:
+ *
+ *   Claude   ~/.claude.json                     mcpServers{}  (+ per-project blocks)
+ *   Codex    ~/.codex/config.toml               [mcp_servers.NAME] TOML sections
+ *   Gemini   ~/.gemini/config/mcp_config.json   mcpServers{} but `serverUrl` not `url`
+ *
+ * So a tool you wired into Claude is invisible to Codex, and drift is silent — one
+ * vendor keeps pointing at a stale URL for months. This module reads all three,
+ * normalizes them to one shape, and can write missing connectors back so every
+ * vendor agrees. That is the Cookbook thesis at the tool layer: your agents are
+ * interchangeable workers, so their capabilities should be yours, not the vendor's.
+ *
+ * Safety: every write makes a timestamped .bak first; secrets are never printed
+ * (values are carried across as-is, shown as ••••). Node built-ins only.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const HOME = os.homedir();
+export const VENDORS = {
+  claude: { label: "Claude", file: path.join(HOME, ".claude.json") },
+  codex: { label: "Codex", file: path.join(process.env.CODEX_HOME || path.join(HOME, ".codex"), "config.toml") },
+  gemini: { label: "Gemini", file: path.join(HOME, ".gemini", "config", "mcp_config.json") },
+};
+
+/** Normalized connector: { name, kind: 'stdio'|'http', command, args, env, url, headers } */
+function normalize(name, raw) {
+  const url = raw.url || raw.serverUrl || raw.httpUrl;
+  if (url) return { name, kind: "http", url, headers: raw.headers || {} };
+  return { name, kind: "stdio", command: raw.command, args: raw.args || [], env: raw.env || {} };
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+/** Read one vendor's connectors → Map(name → normalized). */
+export function readVendor(vendor) {
+  const out = new Map();
+  const { file } = VENDORS[vendor];
+  if (vendor === "claude") {
+    const j = readJson(file);
+    if (!j) return out;
+    for (const [n, raw] of Object.entries(j.mcpServers || {})) out.set(n, normalize(n, raw));
+    return out;
+  }
+  if (vendor === "gemini") {
+    const j = readJson(file);
+    if (!j) return out;
+    for (const [n, raw] of Object.entries(j.mcpServers || {})) out.set(n, normalize(n, raw));
+    return out;
+  }
+  // codex: TOML. We only need the [mcp_servers.NAME] sections and their scalars.
+  let text = "";
+  try { text = fs.readFileSync(file, "utf8"); } catch { return out; }
+  const re = /^\[mcp_servers\.([A-Za-z0-9_\-]+)\]([\s\S]*?)(?=^\[|\Z)/gm;
+  let m;
+  while ((m = re.exec(text))) {
+    const [, name, body] = m;
+    const get = (k) => {
+      const hit = body.match(new RegExp(`^${k}\\s*=\\s*"([^"]*)"`, "m"));
+      return hit ? hit[1] : undefined;
+    };
+    const argsLine = body.match(/^args\s*=\s*\[([^\]]*)\]/m);
+    const args = argsLine ? argsLine[1].split(",").map((s) => s.trim().replace(/^"|"$/g, "")).filter(Boolean) : [];
+    out.set(name, get("url")
+      ? { name, kind: "http", url: get("url"), headers: {} }
+      : { name, kind: "stdio", command: get("command"), args, env: {} });
+  }
+  return out;
+}
+
+/** One row per connector, with per-vendor presence and drift detection. */
+export function survey() {
+  const byVendor = Object.fromEntries(Object.keys(VENDORS).map((v) => [v, readVendor(v)]));
+  const names = [...new Set(Object.values(byVendor).flatMap((m) => [...m.keys()]))].sort();
+  return names.map((name) => {
+    const present = {};
+    const targets = new Set();
+    for (const v of Object.keys(VENDORS)) {
+      const c = byVendor[v].get(name);
+      present[v] = !!c;
+      if (c) targets.add(c.kind === "http" ? c.url : `${c.command} ${c.args.join(" ")}`.trim());
+    }
+    return { name, present, drift: targets.size > 1, targets: [...targets], byVendor };
+  });
+}
+
+function backup(file) {
+  try {
+    if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.bak-${Date.now()}`);
+  } catch { /* best effort */ }
+}
+
+/** Write a connector into a vendor's config (idempotent: replaces same-named). */
+export function writeConnector(vendor, conn) {
+  const { file } = VENDORS[vendor];
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  backup(file);
+
+  if (vendor === "claude" || vendor === "gemini") {
+    const j = readJson(file) || {};
+    j.mcpServers = j.mcpServers || {};
+    j.mcpServers[conn.name] = conn.kind === "http"
+      // Claude takes `url`; Gemini takes `serverUrl`. Same connector, different key.
+      ? (vendor === "gemini"
+          ? { serverUrl: conn.url, ...(Object.keys(conn.headers).length ? { headers: conn.headers } : {}) }
+          : { type: "http", url: conn.url, ...(Object.keys(conn.headers).length ? { headers: conn.headers } : {}) })
+      : { command: conn.command, args: conn.args, ...(Object.keys(conn.env).length ? { env: conn.env } : {}) };
+    fs.writeFileSync(file, JSON.stringify(j, null, 2));
+    return;
+  }
+
+  // codex TOML: drop any existing section for this name, then append a fresh one.
+  let text = "";
+  try { text = fs.readFileSync(file, "utf8"); } catch { /* new file */ }
+  text = text.replace(new RegExp(`^\\[mcp_servers\\.${conn.name}\\][\\s\\S]*?(?=^\\[|\\Z)`, "gm"), "");
+  const lines = [`\n[mcp_servers.${conn.name}]`];
+  if (conn.kind === "http") {
+    lines.push(`url = "${conn.url}"`);
+  } else {
+    lines.push(`command = "${conn.command}"`);
+    lines.push(`args = [${conn.args.map((a) => `"${a}"`).join(", ")}]`);
+    if (Object.keys(conn.env).length) {
+      lines.push(`\n[mcp_servers.${conn.name}.env]`);
+      for (const [k, v] of Object.entries(conn.env)) lines.push(`${k} = "${v}"`);
+    }
+  }
+  fs.writeFileSync(file, text.replace(/\n{3,}$/, "\n") + lines.join("\n") + "\n");
+}
+
+/** Make every vendor agree. `only` limits to named connectors; source picks whose
+ *  definition wins when a connector exists in several places (default: claude). */
+export function sync({ only = null, source = "claude", dryRun = false } = {}) {
+  const rows = survey();
+  const actions = [];
+  for (const row of rows) {
+    if (only && !only.includes(row.name)) continue;
+    const defs = row.byVendor;
+    const winner = defs[source]?.get(row.name)
+      || defs.claude.get(row.name) || defs.codex.get(row.name) || defs.gemini.get(row.name);
+    if (!winner) continue;
+    for (const v of Object.keys(VENDORS)) {
+      const existing = defs[v].get(row.name);
+      const same = existing && JSON.stringify(existing) === JSON.stringify({ ...existing, ...winner });
+      if (existing && same) continue;
+      actions.push({ vendor: v, name: row.name, action: existing ? "update" : "add", conn: winner });
+    }
+  }
+  if (!dryRun) for (const a of actions) writeConnector(a.vendor, a.conn);
+  return actions;
+}