cookbook-bridge 0.1.8 → 0.1.11

package/README.md

@@ -1,5 +1,30 @@
 # Cookbook Bridge
 
+## Changelog
+
+**0.1.11** (2026-09-02)
+- The Bridge has a home: `~/.cookbook/config.json` (file 0600, folder 0700) for every command. `bridge.state.json`, `local.json` and `bridge.log` sit next to it. Before, the config lived next to `bridge.mjs`, so every `npx cookbook-bridge@latest` landed in a fresh cache folder and lost it. A config found next to `bridge.mjs` is copied to the home once (the old file stays) and the move is announced in one line. `--config <path>` and `COOKBOOK_CONFIG` still win.
+- `connect` runs the Bridge right after the approval (pass `--no-run` to stop at "connected"). With no agent CLI found it prints the doctor instead.
+- Every hint is a command that works where you are: `npx cookbook-bridge@latest <cmd>` from an npm install, `node bridge/bridge.mjs <cmd>` from a tarball.
+- `doctor` gained rows for the config home (path, exists, mode), other Bridge processes on this machine (pids and config paths), Bridge Local (does the port answer), and whether the local files are behind the app deploy, with the same update line the running Bridge prints. `connect` prints that line too.
+- Visiting agents can read `~/.cookbook/bridge.state.json` as a projection; `~/.cookbook/local.json` is never readable, like the desktop app's copy.
+
+**0.1.10** (2026-09-02)
+- Works on every Node from 18 up. Before, on Node older than 22.18 every command exited silently, doing nothing.
+- The npm package and the desktop app now ship every runtime file (realtime, sessions, synthesis, the approval relay, the hook reporter). Install-time crashes on import are gone, and a test now fails the build if a file is left out.
+- Prompts reach Claude on stdin, never on the command line. On Windows a prompt is never routed through a `.cmd` shim and cmd.exe; the Bridge runs the shim's node script directly or refuses with the fix.
+- Ctrl-C now hands running tasks back to the board the same way a SIGTERM does.
+- When Claude reports its plan window is full, the Bridge waits for the reset instead of burning retries; that attempt is not counted.
+- Team connectors that run a command (stdio) are no longer installed automatically. They wait for `cookbook-bridge connectors approve <name>`; `connectors pending` lists them. URL connectors sync as before.
+- Connector sync never rewrites a `~/.claude.json` it cannot parse, handles the last TOML section correctly, and escapes TOML strings.
+- Bearer tokens no longer appear on agent command lines (`--mcp-config` is a private temp file now).
+- A first `connect` writes a config shaped to the CLIs on your machine (default agent Claude when present, no placeholder entries).
+- Workspace summaries run with no tools and without vendor API keys.
+- Captions, image descriptions and answers now run on your subscription too, through the same lane as summaries. An image job downloads the picture into a private temp folder, gives Claude read access to that one file only, and deletes the folder when the run ends. Synthesis jobs that arrive while another is running now wait their turn instead of being dropped.
+- Live output and results are redacted on this machine before they leave it; `~/.gemini/config/mcp_config.json` is written owner-only.
+- Set `COOKBOOK_NO_BROWSER=1` to stop `login`/`connect` from opening a browser (the URL is still printed).
+
+
 Runs your **own AI agents** (Claude Code, Codex, Gemini) on **your own subscriptions**,
 against your Cookbook workspaces — so tasks on the board get done by your agents
 automatically, on your machine, with **no API credits**.
@@ -19,49 +44,49 @@ Trust model: your Cookbook's `/security` page.
 ## Quick start (2 minutes)
 
 ```bash
-npx cookbook-bridge@latest connect   # one-time: ONE approval connects the Bridge AND every
-                                     # installed agent CLI (claude, codex, agy, openclaw),
-                                     # each with its own attributed token
+npx cookbook-bridge@latest connect   # ONE approval connects the Bridge AND every installed
+                                     # agent CLI (claude, codex, agy, openclaw), each with its
+                                     # own attributed token, then RUNS the Bridge. Leave it open.
+```
+
+That is the whole setup. Later:
+
+```bash
+npx cookbook-bridge@latest           # run it again (config is remembered in ~/.cookbook)
 npx cookbook-bridge@latest doctor    # preflight: checks every prerequisite, with exact fixes
-npx cookbook-bridge@latest           # run it (leave it running)
 ```
 
 Always `@latest`: bare `npx cookbook-bridge` happily runs a weeks-old cached copy
-that predates subcommands you need (`host` shipped in 0.1.1).
+that predates subcommands you need (`host` shipped in 0.1.1). Your config is not in
+that cache, so `@latest` never loses it.
 
 Node 18+. No dependencies, nothing to configure by hand: `connect` writes
-`config.json` for you and never prints or stores a secret you have to copy.
+`~/.cookbook/config.json` for you and never prints or stores a secret you have to copy.
+Pass `--no-run` to stop at "connected" without starting the Bridge.
 
 <details>
 <summary>Prefer no package manager? Download the tarball instead.</summary>
 
 ```bash
 curl -fsSL https://cookbook.team/api/bridge/download | tar xz
-node bridge/bridge.mjs connect
+node bridge/bridge.mjs connect       # same flow: one approval, then it runs
 ```
 
-The commands below are written for this layout (`node bridge/bridge.mjs <command>`);
-with the npm install, every one of them is `npx cookbook-bridge <command>`.
+From a tarball every command is `node bridge/bridge.mjs <command>` (run it from the
+folder you unpacked, the one that contains `bridge/`); with the npm install it is
+`npx cookbook-bridge@latest <command>`. The Bridge knows which layout it runs from and
+prints the right one in every hint. The config lives in `~/.cookbook` either way.
 
 </details>
 
-```bash
-# from the folder you unpacked (it contains bridge/)
-node bridge/bridge.mjs connect-agents  # one-time: ONE approval connects the Bridge
-                                       # AND every installed agent CLI (claude, agy, codex)
-                                       # to Cookbook, each with its own attributed token
-node bridge/bridge.mjs doctor          # preflight: checks EVERY prerequisite, prints
-                                       # the exact fix for anything that's missing
-node bridge/bridge.mjs                 # run it (leave it running)
-```
-
-No hand-pasting tokens: `connect-agents` is the intended path (device flow, like a TV
-app; the code expires in ~10 minutes — just re-run it if it lapses). One browser click
-authorizes the Bridge **and** mints a named token per detected agent CLI — the name is
-the attribution label ("Claude · via you") — then configures each CLI via its own
-`mcp add`. Prefer just the Bridge? `login` does the device flow without touching your
-CLIs. Fully manual: copy `config.example.json` → `config.json` and paste a token from
-your Cookbook **Account → Tokens** page.
+No hand-pasting tokens: `connect` is the intended path (device flow, like a TV app; the
+code expires in ~10 minutes, just re-run it if it lapses). One browser click authorizes
+the Bridge **and** mints a named token per detected agent CLI (the name is the
+attribution label, "Claude · via you"), then configures each CLI via its own `mcp add`.
+`connect-agents` is the same command under its original name. Prefer just the Bridge?
+`login` does the device flow without touching your CLIs. Fully manual: copy
+`config.example.json` to `~/.cookbook/config.json` and paste a token from your Cookbook
+**Account → Tokens** page.
 
 Requires **Node 18+** (built-in `fetch`, no npm install) and at least one agent CLI
 installed and logged in (`claude`, `agy` — the Antigravity CLI for Gemini — or the Codex app). Each agent must also be
@@ -70,15 +95,33 @@ you exactly which parts are ready and how to fix the rest.
 
 ## Commands
 
+Written as `npx cookbook-bridge@latest <command>`; from a tarball, `node bridge/bridge.mjs <command>`.
+
 | Command | What it does |
 |---|---|
-| `node bridge.mjs` | Run the Bridge (uses `config.json` next to it; or pass a path) |
-| `node bridge.mjs connect-agents` | One approval connects the Bridge + every installed agent CLI (attributed tokens) |
-| `node bridge.mjs login` | Device-flow auth for the Bridge only, writes your config |
-| `node bridge.mjs doctor` | Preflight every prerequisite with exact fixes |
-| `node bridge.mjs status` | Liveness + agent readiness |
-| `node bridge.mjs update` | Update the Bridge to match the app (see Self-updating) |
-| `cookbook-bridge host` | Open the door: let an agent someone else runs help you set this machine up, inside a grant you approve. `--off` closes it. |
+| (none) | Run the Bridge (uses `~/.cookbook/config.json`; or pass a path) |
+| `connect` | One approval connects the Bridge + every installed agent CLI (attributed tokens), then runs the Bridge. `--no-run` stops at connected. `connect-agents` is the same command. |
+| `login` | Device-flow auth for the Bridge only, writes your config |
+| `doctor` | Preflight every prerequisite with exact fixes: config home, token, agents, other Bridge processes, Bridge Local, and whether the files are behind the app |
+| `status` | Liveness + agent readiness |
+| `update` | Update the Bridge to match the app (see Self-updating) |
+| `host` | Open the door: let an agent someone else runs help you set this machine up, inside a grant you approve. `--off` closes it. |
+| `connectors` | Survey MCP connectors across Claude, Codex and Gemini; `sync` gives every agent the same tools; `approve <name>` installs a team stdio connector |
+
+## Where things live (the config home)
+
+Every command resolves the config the same way, first match wins:
+
+1. `--config <path>` (or, for the run command, a positional path)
+2. `COOKBOOK_CONFIG` in the environment
+3. `~/.cookbook/config.json` (folder 0700, file 0600)
+4. A `config.json` next to `bridge.mjs`, only when 3 does not exist yet. It is copied to
+   the home once, the old file is left in place, and one line says where the config
+   now lives (pre-0.1.11 installs kept it next to the code).
+
+`bridge.state.json` (attempt counters), `local.json` (the Bridge Local loopback port and
+token) and `bridge.log` sit in the same folder as whichever config is in use. The desktop
+app passes its own `--config` path and keeps its files in its data folder.
 
 ## Self-updating
 
@@ -86,8 +129,11 @@ you exactly which parts are ready and how to fix the rest.
 to the deploy's manifest (`/api/bridge/manifest`) and — with `"autoUpdate": true`, the
 default — replaces them (every file hash-verified first, originals kept in
 a per-version `bridge.backup/<deploy>/` dir, your `config.json` and token never touched) and restarts itself.
-Set `"autoUpdate": false` to pin your version; `node bridge.mjs update` updates manually
-and works even from a broken install.
+Set `"autoUpdate": false` to pin your version; `node bridge/bridge.mjs update` updates
+manually and works even from a broken install. An npm install is updated by npm: re-run
+`npx cookbook-bridge@latest`, and your config in `~/.cookbook` comes along untouched.
+`doctor` and `connect` run the same comparison and print the same update line when the
+local files are behind.
 
 ## Agents (config.json)
 

package/approve-mcp.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * THE PERMISSION RELAY (0086) — Claude Code's --permission-prompt-tool server.
+ *
+ * In an ask-mode folder, Claude Code pre-approves only reads; any other tool call
+ * makes the CLI ask THIS process (a one-tool MCP server over stdio, spawned by
+ * the CLI itself). We redact the request ON the machine, POST it to Cookbook as
+ * a pending approval, poll for the owner's click, and answer the CLI with
+ * {"behavior":"allow"|"deny"}. No decision in 4.5 minutes = deny — the fail-safe
+ * direction, matching the row's 5-minute server expiry.
+ *
+ * Standalone on purpose: newline-delimited JSON-RPC, zero dependencies beyond
+ * the redaction corpus it shares with everything else that leaves this machine.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { redact } from "./hands.mjs";
+
+const URL_BASE = String(process.env.CBK_URL ?? "").replace(/\/$/, "");
+const TOKEN = process.env.CBK_TOKEN ?? "";
+const WORKSPACE = process.env.CBK_WORKSPACE ?? "";
+const TASK = process.env.CBK_TASK ?? "";
+const FOLDER = process.env.CBK_FOLDER ?? "";
+const AGENT = process.env.CBK_AGENT ?? "Claude";
+const POLL_MS = 2000;
+const WAIT_MS = 4.5 * 60_000;
+
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+
+/** One line a human can judge: the command for Bash, the path for edits. */
+export function summarize(toolName, input) {
+  try {
+    const i = input && typeof input === "object" ? input : {};
+    const core = toolName === "Bash" ? String(i.command ?? "")
+      : (i.file_path ?? i.notebook_path ?? i.path ?? i.url ?? JSON.stringify(i));
+    return redact(String(core)).slice(0, 500);
+  } catch {
+    return "";
+  }
+}
+
+/** The CLI contract: a JSON string in the tool result's text content. */
+export function verdictPayload(status) {
+  if (status === "allowed") return { behavior: "allow", updatedInput: undefined };
+  return { behavior: "deny", message: status === "expired" ? "Timed out waiting for approval in Cookbook (5 minutes). Ask again if still needed." : "Denied by the owner in Cookbook." };
+}
+
+async function decide(toolName, input) {
+  if (!URL_BASE || !TOKEN || !WORKSPACE) return { behavior: "deny", message: "Approval relay is not configured." };
+  const res = await fetch(`${URL_BASE}/api/bridge/approvals`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${TOKEN}` },
+    body: JSON.stringify({
+      workspace_id: WORKSPACE,
+      task_id: TASK || undefined,
+      folder: FOLDER || undefined,
+      agent: AGENT,
+      tool_name: String(toolName ?? "tool").slice(0, 60),
+      input_summary: summarize(toolName, input),
+    }),
+  });
+  if (res.status === 403) return { behavior: "deny", message: "The drive layer isn't enabled for this account." };
+  if (!res.ok) return { behavior: "deny", message: `Approval relay error (${res.status}).` };
+  const { id } = await res.json();
+  const until = Date.now() + WAIT_MS;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, POLL_MS));
+    try {
+      const poll = await fetch(`${URL_BASE}/api/bridge/approvals/${id}`, { headers: { Authorization: `Bearer ${TOKEN}` } });
+      if (!poll.ok) continue;
+      const { status } = await poll.json();
+      if (status && status !== "pending") return verdictPayload(status);
+    } catch { /* transient; keep polling */ }
+  }
+  return verdictPayload("expired");
+}
+
+// ── minimal MCP stdio server: initialize, tools/list, tools/call(approve) ────
+const TOOL = {
+  name: "approve",
+  description: "Ask the owner in Cookbook whether this tool call may run.",
+  inputSchema: { type: "object", properties: { tool_name: { type: "string" }, input: { type: "object" }, tool_use_id: { type: "string" } } },
+};
+
+// Start the server ONLY when run as the entry script — importers (tests) get the
+// pure exports without a live stdin listener holding their process open.
+// `import.meta.main` is undefined before Node 22.18 / 24.2; without the argv[1]
+// fallback the relay never started on older Nodes and every ask-mode call was denied.
+const IS_MAIN = import.meta.main === true
+  || (import.meta.main !== false && !!process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url));
+let buf = "";
+if (IS_MAIN) {
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); } catch { continue; }
+    void handle(msg);
+  }
+});
+}
+
+async function handle(msg) {
+  const { id, method, params } = msg ?? {};
+  if (method === "initialize") {
+    return send({ jsonrpc: "2.0", id, result: { protocolVersion: params?.protocolVersion ?? "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "cbapprove", version: "1" } } });
+  }
+  if (method === "tools/list") return send({ jsonrpc: "2.0", id, result: { tools: [TOOL] } });
+  if (method === "tools/call" && params?.name === "approve") {
+    const a = params.arguments ?? {};
+    let verdict;
+    try { verdict = await decide(a.tool_name, a.input); } catch (e) { verdict = { behavior: "deny", message: `Relay failed: ${e.message}` }; }
+    return send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(verdict) }] } });
+  }
+  if (id !== undefined && method) return send({ jsonrpc: "2.0", id, error: { code: -32601, message: `unknown method ${method}` } });
+}