cookbook-bridge 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,156 @@
+# Cookbook Bridge
+
+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**.
+
+```
+someone assigns your Claude a task  →  it lands on the board (open)
+        the Bridge (this) polls, sees it, wakes `claude -p "…"` headlessly
+        Claude — MCP-connected to Cookbook — does the work, writes what it
+        learned to the team memory, and calls complete_task itself
+        the Bridge verifies it's done and reports what the run cost (tokens)
+```
+
+The Bridge never does the work itself: it **wakes the right agent and verifies**.
+Plain, readable JavaScript — Node built-ins only, no dependencies, no telemetry.
+Trust model: your Cookbook's `/security` page.
+
+## Quick start (2 minutes)
+
+```bash
+npx cookbook-bridge 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 doctor    # preflight: checks every prerequisite, with exact fixes
+npx cookbook-bridge           # run it (leave it running)
+```
+
+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.
+
+<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
+```
+
+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>`.
+
+</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.
+
+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
+connected to Cookbook over MCP — that's how it completes tasks. Run `doctor`; it tells
+you exactly which parts are ready and how to fix the rest.
+
+## Commands
+
+| 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) |
+
+## Self-updating
+
+**The Bridge follows the app.** At startup and every 6 hours it compares its own files
+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.
+
+## Agents (config.json)
+
+```json
+"agents": [
+  { "name": "Claude", "match": ["claude"], "enabled": true,
+    "command": ["claude", "-p", "{prompt}", "--allowedTools", "mcp__cookbook__*", "--output-format", "json"] },
+  { "name": "Gemini", "match": ["gemini"], "enabled": true,
+    "command": ["agy", "-p", "{prompt}", "--sandbox", "--print-timeout", "3600s"] },
+  { "name": "Codex", "match": ["codex", "chatgpt"], "enabled": false, "runner": "app-server",
+    "command": ["/Applications/Codex.app/Contents/Resources/codex"] }
+]
+```
+
+- `match`: which task assignees this agent handles (substring match — a task assigned
+  to "Claude" wakes the agent whose match includes "claude").
+- **Claude with `--output-format json`** lets the Bridge report what each run cost
+  (tokens / $-equivalent) back to the board — `text` works too, you just lose the detail.
+- **`--allowedTools` prefix matters**: 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 — `doctor` checks it.
+- **Codex (ChatGPT)** runs through `codex app-server` (its headless `exec` can't call
+  MCP tools); see `_setup` in `config.example.json` for the 3-step enable.
+- `"default"`: which agent takes tasks assigned to **any**.
+
+## What rides into (and out of) every run
+
+- **Team memory in**: the Bridge injects the workspace's relevant decisions/gotchas
+  into the prompt, so your agent starts with what the team already knows.
+- **Knowledge out**: agents are instructed to `remember` durable learnings — work
+  produces shared memory as exhaust.
+- **Cost out**: after a verified completion the Bridge reports tokens/duration, so the
+  board shows what each delegation cost, on whose quota.
+
+## Volunteering (off by default)
+
+An agent with `"volunteer": true` + a `"capabilities"` line watches tasks posted as
+**open goals** (🎯 on the board) and may claim ones it judges itself capable of — 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. Nothing volunteers unless
+you opt an agent in, and only tasks explicitly posted as goals are ever eligible.
+`"volunteering": false` kills it globally.
+
+## Safety rails (on by default)
+
+- **Billing protection**: vendor API keys (`ANTHROPIC_API_KEY` etc.) are hidden from
+  agent processes, so a task can never silently bill your API account instead of your
+  subscription. Opt out with `"allowApiKeyBilling": true`.
+- **Vulnerable-version gate**: gemini-cli below 0.39.1 (the CVSS-10.0 RCE fix) is refused; agy below 1.1.1 (headless MCP) is refused.
+- **Who can use your agents**: `"acceptFrom": "anyone"` (default) or a list of member
+  names (e.g. `["dp", "pierre"]`); per-agent overrides supported. Plus the per-person
+  **allow / ask / off** delegation policy you manage in Cookbook (Account → Agents) —
+  "ask" parks a teammate's task in your approvals inbox before anything runs.
+
+## How completion + attribution works
+
+The agent completes the task through **its own** Cookbook connection, so work is
+attributed to the agent (via you). The Bridge's token only reads the board, claims
+volunteered goals, verifies completion, and reports usage. If an agent runs but doesn't
+finish, the Bridge retries up to `maxAttempts`, then leaves the task open — with the
+likely cause in the log (login missing, MCP not connected, tool blocked).
+
+## Honest limits
+
+- **Local only** — tasks run while your machine and the Bridge are up.
+- **Subscription terms** — automating consumer CLIs in a loop can hit usage limits and
+  sits near vendor policy lines; fine at team scale, don't point it at a firehose.
+- **Headless flake** — one-shot agents occasionally wobble; `maxAttempts` + leave-open
+  + the failure-cause log exist for exactly that.