cookbook-bridge 0.1.10 → 0.1.12

package/README.md

@@ -2,6 +2,19 @@
 
 ## Changelog
 
+**0.1.12** (2026-09-02)
+- Kimi Code is the fourth agent: `connect` finds `kimi`, mints a "Kimi" token and writes `~/.kimi-code/mcp.json` (owner-only, other servers kept). Runs use `kimi -p ... --output-format stream-json`; the board gets live text and the work log, resume by session id, and a duration-only receipt (kimi reports no token counts).
+- A headless kimi run approves every tool and has no `--allowedTools` flag, so the Bridge turns the config's `--allowedTools` into a per-run agent file (`--agent-file`, a 0600 temp file) whose tools allowlist is exactly that list. `doctor` fails a Kimi agent that has no `--allowedTools`.
+- Billing protection also hides `KIMI_API_KEY`, `MOONSHOT_API_KEY` and `KIMI_MODEL_API_KEY`.
+- `doctor` gained Kimi rows: version, login (config.toml providers or OAuth credentials), the MCP file, and the two flags a headless run needs.
+
+**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.
@@ -18,7 +31,7 @@
 - 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**,
+Runs your **own AI agents** (Claude Code, Codex, Gemini, Kimi Code) 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**.
 
@@ -37,66 +50,84 @@ 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, kimi, 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
+installed and logged in (`claude`, `agy` — the Antigravity CLI for Gemini — `kimi`, 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
 
+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
 
@@ -104,8 +135,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)
 
@@ -115,6 +149,8 @@ and works even from a broken install.
     "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": "Kimi", "match": ["kimi"], "enabled": true,
+    "command": ["kimi", "-p", "{prompt}", "--allowedTools", "mcp__cookbook__*", "--output-format", "stream-json"] },
   { "name": "Codex", "match": ["codex", "chatgpt"], "enabled": false, "runner": "app-server",
     "command": ["/Applications/Codex.app/Contents/Resources/codex"] }
 ]
@@ -130,6 +166,13 @@ and works even from a broken install.
   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.
+- **Kimi Code** runs `kimi -p` with `--output-format stream-json` (live text, work log,
+  session resume; no token counts, so the receipt is duration only). Its headless mode
+  approves every tool and has no `--allowedTools` flag, so the Bridge turns that value
+  into a per-run agent file (`--agent-file`) whose `tools:` allowlist is exactly the
+  list. Keep it on the command; `doctor` fails a Kimi agent without it. `connect`
+  writes `~/.kimi-code/mcp.json` (kimi has no `mcp add`). Kimi does not stream its
+  thinking, so a long think looks like silence to `livenessTimeoutSeconds`.
 - `"default"`: which agent takes tasks assigned to **any**.
 
 ## What rides into (and out of) every run
@@ -152,9 +195,11 @@ you opt an agent in, and only tasks explicitly posted as goals are ever eligible
 
 ## 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`.
+- **Billing protection**: vendor API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+  `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `KIMI_API_KEY`, `MOONSHOT_API_KEY`,
+  `KIMI_MODEL_API_KEY`) 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