botmancers 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -3,7 +3,113 @@
 All notable changes to the `botmancers` npm package. It uses
 [Semantic Versioning](https://semver.org): while the package is `0.x`, a
 minor version may change the CLI or configuration. The MCP tool contract is
-versioned separately, as `botmancers.mcp.v1`.
+versioned separately: `botmancers.mcp.v1` (frozen) and `botmancers.mcp.v2`.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-10-19
+
+### Added
+
+- `botmancers.mcp.v2` (additive): `botmancers_message_agent`,
+  `botmancers_pin_session`, `botmancers_send_to_pin`, `botmancers_get_pin`,
+  and `botmancers_detach_pin` for registered-Agent messaging and exact-session
+  pins; `home` and `actions` on session items, `messaging` on Agent items,
+  and a `recovery` hint on errors. Every existing tool is unchanged.
+  The five new tools are marked `botmancers/optional`: the bridge still
+  starts against a Botmancers that serves the earlier v2 surface without them.
+- The collaboration skill teaches registered-Agent addressing, pinned
+  sessions, and the three session actions: Ask from this context, Resume
+  work here, and Hand off to….
+- Native session providers behind a `SessionProvider` boundary: Botmancers
+  discovers and resumes sessions created by Claude Code, Codex, Cursor
+  (Agent CLI or SDK), and Muse Code, and imports them as native sessions.
+- Sessions show reported token usage and cost.
+
+### Changed
+
+- Agent Deck is now an optional launch profile at registration, not a
+  requirement.
+- The default ports are now UI 3333 and MCP 3332. Update any configuration
+  or bookmarks that use the old ports, or set the ports explicitly.
+- `npm run release:publish` no longer needs `--otp`; npm's browser login
+  works.
+
+## [0.4.2] - 2026-10-17
+
+### Changed
+
+- Releases are published once, straight to `latest`, by the maintainer
+  (`npm run release:publish`). The `canary` dist-tag, the CI publish, npm
+  trusted publishing, and the bootstrap token are gone;
+  `release-botmancers.yml` now only runs the release check on the tag. The
+  package contents are unchanged from 0.4.1.
+- 0.4.1 was tagged but never published, so 0.4.2 carries its contents
+  (below) and the 0.4.0 contents.
+
+## [0.4.1] - 2026-10-17
+
+Not published; see 0.4.2.
+
+### Fixed
+
+- 0.4.0 was never published: its release check failed on the Linux release
+  runner. `npm test` passed a directory to `node --test`, which Node 24 treats
+  as a module path; it now passes a glob. The clean-install smoke signalled
+  `npx`, which on npm 11.19 does not forward `SIGTERM` to the bridge; it now
+  signals the process group and checks that the bridge port closes.
+- `release:check` shows the failing test and smoke output, drains stdout
+  before exiting, and writes its `--out` transcript as it goes.
+
+### Changed
+
+- A `ci-botmancers` workflow runs the same release check on pull requests that
+  touch the app or the package, so release failures show up before a tag.
+- 0.4.1 carries everything 0.4.0 would have shipped (below).
+
+## [0.4.0] - 2026-10-17
+
+Not published; see 0.4.1.
+
+### Added
+
+- The Botmancers app bundled in the package adds the durable Agent session
+  catalog and Sessions UI, session-targeted Ask and Continue exchanges with
+  inline exchange cards, and an Agent Exchanges ledger.
+- Service grants let the owner give another Agent narrow, audited access to
+  sessions, conversations, and exchanges (`docs/service-grants.md`). Grants
+  are re-checked at read time, and an unregistered Agent invalidates the
+  document.
+
+- `botmancers setup --client codex|cursor|claude [--remove]`: connects the
+  client to the local MCP bridge and installs the optional
+  `botmancers-collaboration` Agent Skill (shipped in `skills/`). An
+  ownership record in `config/clients/<client>.json` (versions and SHA-256
+  hashes, no token) lets re-runs, upgrades, and rollbacks refresh only
+  unmodified Botmancers files. Edited or foreign files are never overwritten
+  (exit 12), a missing client writes nothing (exit 11), and a failed write is
+  rolled back. Plain `botmancers setup` refreshes the clients already set up.
+  `botmancers doctor` reports each client as connected, missing, stale, or
+  conflicted, with the repair command.
+
+- MCP contract `botmancers.mcp.v2`: `botmancers_capabilities`,
+  `botmancers_list_agents`, `botmancers_list_sessions`,
+  `botmancers_list_conversations`, `botmancers_send_to_session`,
+  `botmancers_create_exchange`, `botmancers_get_exchange`, and
+  `botmancers_list_exchanges`, plus a v2 (`agent_id`) path of
+  `botmancers_get_conversation`, over the owner's service grants. The bundled
+  schema is `schemas/botmancers.mcp.v2.tools.json`; every v2 call is forwarded
+  unchanged. `GET /healthz` adds `contracts`. Library exports add
+  `MCP_CONTRACT_V1`, `MCP_CONTRACTS`, `TOOL_SCHEMA_V1_URL`, and
+  `toolContractOf`.
+
+### Changed
+
+- `MCP_CONTRACT` and `/healthz` `contract` are now `botmancers.mcp.v2`;
+  `tools/list` returns the v1 tools unchanged, then the v2 tools.
+- Startup preflight refuses (exit 4) a Botmancers that lacks any bundled v1 or
+  v2 tool, or the v2 path of `botmancers_get_conversation`, and names what is
+  missing. It still sends only `initialize` and `tools/list`.
 
 ## [0.3.0] - 2026-10-16
 

package/README.md

@@ -7,22 +7,53 @@ result. Examples of such agents are Cursor's Grok Bot or any other MCP client.
 No source checkout or separately started app is needed.
 
 - `botmancers setup` / `botmancers start` run the **full product**: the UI and
-  core engine on `http://127.0.0.1:43123` and the MCP bridge on
-  `http://127.0.0.1:43124/mcp`, under one supervisor.
+  core engine on `http://127.0.0.1:3333` and the MCP bridge on
+  `http://127.0.0.1:3332/mcp`, under one supervisor.
 - Bare `botmancers` (or `botmancers mcp`) runs **only the bridge** in front of
   a Botmancers app you run yourself, exactly as in 0.1.0, so existing MCP
   configurations keep working.
 
-The tool contract is `botmancers.mcp.v1`, and its JSON schema ships in this
-package at `schemas/botmancers.mcp.v1.tools.json`.
+The tool contract is `botmancers.mcp.v2`, which serves every
+`botmancers.mcp.v1` tool unchanged and adds granted access to Agents,
+sessions, conversations, and exchanges. Its JSON schema ships in this
+package at `schemas/botmancers.mcp.v2.tools.json`, next to the frozen
+`schemas/botmancers.mcp.v1.tools.json`; both are byte-identical to the
+captures in the Botmancers repository
+([`docs/contracts`](../../docs/contracts/mcp-bridge-v2.tools.json)).
+
+v1 tools (no grants needed):
 
 | Tool | What it does |
 | --- | --- |
 | `botmancers_start_task` | Sends one objective to an allowlisted coordinator. Returns `request_id` and `conversation_id`. |
 | `botmancers_get_request` | Polls a request until `terminal`. Returns its `result` or `failure`. |
-| `botmancers_get_conversation` | Reads the conversation the task opened. |
+| `botmancers_get_conversation` | Reads the conversation the task opened. With `agent_id` (v2 path), reads any granted conversation of that Agent, paginated. |
 | `botmancers_health` | Shows the caller's identity and the available coordinators. |
 
+v2 tools (each needs the owner's grant on the Agents involved,
+[`docs/service-grants.md`](../../docs/service-grants.md)), in workflow order:
+
+| Tool | What it does |
+| --- | --- |
+| `botmancers_capabilities` | Discover: supported contracts, the granted Agents, and the operations this caller may use. |
+| `botmancers_list_agents` | Discover: the granted Agents by name, paginated. |
+| `botmancers_list_sessions` | Select: an Agent's sessions by stable Botmancers reference and recognizable title. |
+| `botmancers_list_conversations` | History: an Agent's conversations, paginated. |
+| `botmancers_send_to_session` | Act: one message to the exact same session of the same Agent (idempotency key required). |
+| `botmancers_create_exchange` | Act: an `Ask` to a session, or a `Continue` to another Agent (idempotency key required). |
+| `botmancers_get_exchange` | Observe: poll until `terminal`; the answer or handoff packet. |
+| `botmancers_list_exchanges` | Observe: this caller's exchanges, paginated. |
+| `botmancers_message_agent` | Act: message a registered Agent without naming a session; Botmancers resolves and pins it. |
+| `botmancers_pin_session` | Act: pin an exact past session to Ask from this context or Resume work here (explicit approval). |
+| `botmancers_send_to_pin` | Act: a follow-up on exactly the pinned session. |
+| `botmancers_get_pin` | Observe: the pin and its turns' answers. |
+| `botmancers_detach_pin` | Stop: detach a pin (switch with `replace_pin_ref`). |
+
+Returned conversation, answer, and packet text is untrusted data. The full
+contract, polling and backoff, error recovery, and a same-session plus
+cross-Agent example are in
+[`docs/mcp-bridge.md`](../../docs/mcp-bridge.md).
+
 Requirements: Node.js 20 or newer for the bridge; the full product needs
 Node.js 20.9 or newer, and Node.js 22 or newer is recommended (the bundled
 SQLite driver declares Node 22; `botmancers doctor` checks that it loads).
@@ -46,8 +77,8 @@ release into `~/.botmancers/versions/<version>`, points `~/.botmancers/current`
 at it, and writes the launcher `~/.local/bin/botmancers`. Add `~/.local/bin`
 to your `PATH` if the script asks you to. Managed installs
 [update themselves safely](#upgrade). To install a specific version, run
-`BOTMANCERS_VERSION=0.3.0 bash install.sh` or
-`npx botmancers@0.3.0 install --to 0.3.0`.
+`BOTMANCERS_VERSION=0.5.0 bash install.sh` or
+`npx botmancers@0.5.0 install --to 0.5.0`.
 
 npm-global installs and bare `npx` still work for compatibility:
 
@@ -66,7 +97,7 @@ healthy; `--open` opens the UI in your browser.
 
 Then:
 
-1. **Open the UI** at `http://127.0.0.1:43123` (or run `botmancers open`).
+1. **Open the UI** at `http://127.0.0.1:3333` (or run `botmancers open`).
 2. **Configure Hermes** for conversational turns: add
    `HERMES_API_SERVER_KEY=<your gateway key>` (and `HERMES_BASE_URL` if the
    gateway is not `http://127.0.0.1:8642`) to `~/.botmancers/config/core.env`,
@@ -74,26 +105,30 @@ Then:
 3. **Configure Agent Deck** for coding-agent runs: install Agent Deck so
    `agent-deck` is on `PATH` and its server runs on `http://127.0.0.1:1111`,
    and add `AGENT_DECK_RUN_TOKEN=<token issued by Agent Deck>` to `core.env`.
-4. **Connect an MCP client** to `http://127.0.0.1:43124/mcp` with
+4. **Connect an MCP client** to `http://127.0.0.1:3332/mcp` with
    `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`, taking the token from
-   `~/.botmancers/config/bridge.env`. To let `botmancers_start_task` reach a
-   coordinator, list its Agent name in `core.env` as
-   `BOTMANCERS_MCP_COORDINATORS=Tank` and restart.
+   `~/.botmancers/config/bridge.env`. For Codex, Cursor, or Claude Code,
+   `botmancers setup --client codex|cursor|claude` does this for you and adds
+   the optional collaboration skill
+   ([Client setup and the collaboration skill](#client-setup-and-the-collaboration-skill)).
+   To let `botmancers_start_task` reach a coordinator, list its Agent name in
+   `core.env` as `BOTMANCERS_MCP_COORDINATORS=Tank` and restart.
 5. **Check everything** with `botmancers doctor`.
 
 For anything long-running, use the managed install, or a pinned global
-release rather than `npx`: `npm install -g botmancers@0.3.0`, then run
+release rather than `npx`: `npm install -g botmancers@0.5.0`, then run
 `botmancers setup` and `botmancers start --daemon`.
 
 ### Product commands
 
 | Command | What it does | Exit codes |
 | --- | --- | --- |
-| `botmancers setup` | Creates `BOTMANCERS_HOME` and its credentials; re-running keeps them and re-tightens permissions. | `0`; `9` home not writable |
+| `botmancers setup` | Creates `BOTMANCERS_HOME` and its credentials; re-running keeps them and re-tightens permissions, and refreshes the clients set up with `--client`. | `0`; `9` home not writable |
+| `botmancers setup --client codex\|cursor\|claude [--remove]` | Connects that MCP client to the bridge and installs the optional collaboration skill, or removes both. Files you edited are never overwritten. See [Client setup](#client-setup-and-the-collaboration-skill). | `0`; `2` usage or unsupported client; `11` client not installed; `12` conflicting files (nothing written) |
 | `botmancers start [--daemon] [--open]` | Starts the UI/core and the bridge. Without `--daemon` it stays in the foreground until Ctrl-C. Starting a healthy product again changes nothing. | `0` running; `1` a previous start is degraded; `6` a port is in use; `7` the core or bridge failed (both are stopped); `8` packaged app incomplete; `9` home not writable; `10` not set up |
 | `botmancers stop` | Stops the supervisor, the core, and the bridge. Safe to repeat. | `0`; `1` a process would not stop |
 | `botmancers status` | Reports `healthy`, `degraded`, or `stopped`, with the install kind, launcher, the CLI, current, and pending versions, the versions the live core and bridge report, both endpoints, process ids, and the restart action. | `0` healthy; `1` degraded; `3` stopped |
-| `botmancers doctor` | Checks the install kind, the launcher and `PATH` shadowing, the updater, Node, the packaged app, the home and its permissions, the credentials, the SQLite driver, ports, Hermes, and Agent Deck. Hermes and Agent Deck are optional and only warn. | `0` ok; `1` a check failed |
+| `botmancers doctor` | Checks the install kind, the launcher and `PATH` shadowing, the updater, Node, the packaged app, the home and its permissions, the credentials, the SQLite driver, ports, Hermes, Agent Deck, and the MCP clients set up with `--client`. Hermes, Agent Deck, and clients are optional and only warn. | `0` ok; `1` a check failed |
 | `botmancers open` | Opens the UI in a browser (`BOTMANCERS_BROWSER` overrides the command). | `0`; `1` no browser; `3` not running |
 | `botmancers mcp [options]` | Runs only the bridge; identical to bare `botmancers`. | see [bridge exit codes](#startup-checks-and-exit-codes) |
 | `botmancers install [--to VERSION] [--migrate-cli] [--purge-global]` | Managed install or rollback: downloads the release into `~/.botmancers/versions/VERSION`, verifies it, makes it current, and writes the launcher. `--purge-global` also runs `npm uninstall -g botmancers`; nothing else uninstalls it. | `0`; `1` download or verification failed; `2` usage |
@@ -121,6 +156,7 @@ Everything the product writes lives under `BOTMANCERS_HOME` (default
 | --- | --- |
 | `config/core.env` | Core engine configuration: the bridge's service-token digest and anything you add (Hermes, Agent Deck, coordinators). Variables exported in your shell take precedence. |
 | `config/bridge.env` | The bridge's service token and MCP token. Keep private. |
+| `config/clients/<client>.json` | What `setup --client` manages in that client: the version, and the SHA-256 of each skill file and of the MCP entry it wrote. No token. |
 | `data/` | The SQLite database and its WAL. |
 | `files/`, `skills/` | File artifacts and local Agent skills. |
 | `logs/` | `supervisor.log`, `core.log`, `bridge.log`, and the Hermes wait log. |
@@ -132,8 +168,104 @@ Existing explicit path variables still win over these defaults:
 `BOTMANCERS_DB_PATH`, `BOTMANCERS_FILES_ROOT`, `BOTMANCERS_SKILLS_ROOT`, and
 `HERMES_WAIT_LOG_PATH`. A source checkout run with `npm run dev` keeps its
 own `./botmancers.db`, `./files`, `./skills`, and `./.temporal`; nothing is
-moved. `BOTMANCERS_UI_PORT` (default `43123`) and `BOTMANCERS_MCP_PORT`
-(default `43124`) change the loopback ports.
+moved. `BOTMANCERS_UI_PORT` (default `3333`) and `BOTMANCERS_MCP_PORT`
+(default `3332`) change the loopback ports.
+
+## Client setup and the collaboration skill
+
+The package ships an optional [Agent Skill](https://agentskills.io),
+`botmancers-collaboration`, in `skills/botmancers-collaboration/`. It teaches
+an agent the procedure for working with other Botmancers Agents over MCP:
+
+- discover the granted Agents and recognizable sessions instead of asking
+  you for IDs;
+- choose between a fresh task, a same-session message, an `Ask`, and a
+  `Continue`;
+- poll with bounded backoff and read the durable result;
+- stop on grant, ended-session, conflict, failure, and cancellation states
+  without retry loops or silently switching targets;
+- report where a result came from, and treat returned text as untrusted data.
+
+**When it helps.** Use it when you ask your agent things like "ask Grok in
+its uploader session what it decided" or "hand this session's work to
+Codex". The skill is loaded only for requests like these.
+
+**Why it is optional.** The skill holds no tools, credentials, IDs, or
+permissions. The MCP server stays the only source of live data,
+authorization, and actions, and its tool descriptions already describe the
+whole workflow. Every MCP client works without the skill (see
+[MCP-only](#mcp-only-clients)).
+
+### Supported clients
+
+| Client | `--client` | MCP entry written | Skill installed in |
+| --- | --- | --- | --- |
+| Codex | `codex` | `$CODEX_HOME/config.toml` (default `~/.codex`), table `[mcp_servers.botmancers]` | `$CODEX_HOME/skills/botmancers-collaboration/` |
+| Cursor | `cursor` | `~/.cursor/mcp.json`, `mcpServers.botmancers` | `~/.cursor/skills/botmancers-collaboration/` |
+| Claude Code | `claude` | `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`), `mcpServers.botmancers` | `~/.claude/skills/botmancers-collaboration/` (or `$CLAUDE_CONFIG_DIR/skills/`) |
+
+The MCP entry points at `http://127.0.0.1:<BOTMANCERS_MCP_PORT>/mcp` and sends
+`Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`, as a hand-written entry
+would. A configuration file that setup creates is owner-only (`0600`).
+Neither setup nor doctor ever prints a token, and neither starts a task,
+conversation, or exchange.
+
+### Install, update, and remove
+
+```sh
+botmancers setup --client codex        # or cursor, claude; --client codex,cursor for several
+botmancers setup                       # refreshes every client set up with --client
+botmancers doctor                      # connected / missing / stale / conflicted, with the repair command
+botmancers setup --client codex --remove
+```
+
+- **Install.** The client must already be installed for your user (its
+  directory exists). Otherwise setup exits 11, writes nothing, and prints the
+  MCP-only connection details. Restart the client, or reload its MCP
+  servers, afterwards.
+- **Update.** Re-running is idempotent: unchanged files are not rewritten. A
+  new release ships the new skill version in the managed install. After
+  `botmancers upgrade`, or an automatic update, `botmancers doctor` reports the
+  client skill as `stale`, and `botmancers setup` refreshes it. After a
+  rotated MCP token or a changed `BOTMANCERS_MCP_PORT`, doctor reports the
+  MCP entry `stale` for the same repair. A rollback (`botmancers install
+  --to VERSION`) followed by `botmancers setup` puts that release's skill
+  back.
+- **Remove.** `--remove` deletes the skill files and the MCP entry that are
+  still exactly as Botmancers wrote them, and the ownership record. Anything
+  you edited is kept and listed.
+
+### Managed-file ownership
+
+Setup records each file and MCP entry it writes, with its SHA-256, in
+`config/clients/<client>.json` under `BOTMANCERS_HOME`. It replaces only a file
+or entry that still has the recorded hash, or that already has the wanted
+content. Your own MCP servers, other keys in the configuration file, and
+other skills are never touched. If the skill directory holds a file you
+edited, or the configuration already has a `botmancers` server that setup
+did not write, setup changes nothing for that client, exits 12, and lists
+what conflicts. To hand it back to Botmancers, keep a copy of your
+version, remove the listed files or entry, and re-run setup. If a write
+fails part way, setup restores every file it had already changed for that
+client. Credentials in `config/` are never rewritten by `--client`.
+
+### MCP-only clients
+
+Any other MCP client needs no setup and no skill. Connect it to the URL and
+header that `botmancers setup` prints:
+
+```text
+URL     http://127.0.0.1:3332/mcp
+Header  Authorization: Bearer <BOTMANCERS_MCP_TOKEN from ~/.botmancers/config/bridge.env>
+```
+
+Then follow the tool descriptions in workflow order: `botmancers_capabilities`,
+`botmancers_list_agents`, `botmancers_list_sessions`, an action, and
+`botmancers_get_exchange` until `terminal`
+([`docs/mcp-bridge.md`](../../docs/mcp-bridge.md)). A client that supports
+Agent Skills but is not listed above can also load the skill directly: copy
+`skills/botmancers-collaboration/` from this package into that client's skills
+directory. Setup does not manage that copy.
 
 ## Bridge only
 
@@ -162,14 +294,14 @@ newer and a running Botmancers app.
 3. **Start the bridge:**
 
    ```sh
-   BOTMANCERS_URL=http://127.0.0.1:43123 npx botmancers
+   BOTMANCERS_URL=http://127.0.0.1:3333 npx botmancers
    ```
 
    It prints
-   `botmancers <version>: MCP bridge listening on http://127.0.0.1:43124/mcp ...`
+   `botmancers <version>: MCP bridge listening on http://127.0.0.1:3332/mcp ...`
    and keeps running until you press Ctrl-C.
 
-4. **Connect an MCP client** to `http://127.0.0.1:43124/mcp` with the header
+4. **Connect an MCP client** to `http://127.0.0.1:3332/mcp` with the header
    `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`. Then call
    `botmancers_health`. It should return `status: "ok"` and each coordinator
    with `available: true`.
@@ -177,18 +309,18 @@ newer and a running Botmancers app.
 To pin an exact release, which is recommended for anything long-running:
 
 ```sh
-BOTMANCERS_URL=http://127.0.0.1:43123 npx botmancers@0.3.0
+BOTMANCERS_URL=http://127.0.0.1:3333 npx botmancers@0.5.0
 ```
 
 ## Bridge configuration
 
 | Variable | Flag | Required | Default | Meaning |
 | --- | --- | --- | --- | --- |
-| `BOTMANCERS_URL` | `--botmancers-url` | yes | none | Base URL of the Botmancers app, for example `http://127.0.0.1:43123`. Must be `http://` or `https://`, with no credentials, query, or fragment. The bridge calls `<url>/api/v0/mcp`. |
+| `BOTMANCERS_URL` | `--botmancers-url` | yes | none | Base URL of the Botmancers app, for example `http://127.0.0.1:3333`. Must be `http://` or `https://`, with no credentials, query, or fragment. The bridge calls `<url>/api/v0/mcp`. |
 | `BOTMANCERS_SERVICE_TOKEN` | none (environment only) | yes | none | Bearer token the bridge sends to Botmancers. Its SHA-256 digest must be listed in the app's `BOTMANCERS_SERVICE_TOKENS`. |
 | `BOTMANCERS_MCP_TOKEN` | none (environment only) | yes | none | Bearer token MCP clients must send to the bridge. At least 16 characters, and must differ from the service token. |
 | `BOTMANCERS_MCP_HOST` | `--host` | no | `127.0.0.1` | Address to bind. |
-| `BOTMANCERS_MCP_PORT` | `--port` | no | `43124` | Port to bind. `0` picks a free port. |
+| `BOTMANCERS_MCP_PORT` | `--port` | no | `3332` | Port to bind. `0` picks a free port. |
 
 Flags override environment variables. Secrets are accepted only from the
 environment, because command-line flags are visible to every local user in
@@ -204,23 +336,33 @@ installed version.
   `2025-03-26`. Every request needs `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`.
   `GET` and `DELETE` return 405 because the bridge opens no SSE stream and
   issues no session. Bodies over 256 KiB are refused with 413.
-- `GET /healthz` returns `{"status":"ok","contract":"botmancers.mcp.v1","version":"<version>"}`.
+- `GET /healthz` returns `{"status":"ok","contract":"botmancers.mcp.v2","contracts":["botmancers.mcp.v1","botmancers.mcp.v2"],"version":"<version>"}`.
   It needs no authentication and does not call Botmancers. Use the
   `botmancers_health` tool to check the end-to-end path.
 
 ### Startup checks and exit codes
 
-Before listening, the bridge validates its configuration. It then sends
-Botmancers an MCP `initialize` with the service token. That call writes
-nothing and does not count against the rate limit. No error message contains
-a token.
+Before listening, the bridge validates its configuration. It then runs a
+compatibility preflight: an MCP `initialize` and a `tools/list` with the
+service token, never a tool call, so it writes nothing and does not count
+against the rate limit. Botmancers must offer every bundled tool: all of
+`botmancers.mcp.v1`, all of `botmancers.mcp.v2`, and the v2 `agent_id` path of
+`botmancers_get_conversation`. Otherwise the bridge exits 4 naming exactly
+what is missing, for example `it serves only botmancers.mcp.v1; this bridge
+needs botmancers.mcp.v2 (missing botmancers_capabilities, ...)` or `missing
+botmancers.mcp.v2 tools: botmancers_send_to_session`. Upgrade that Botmancers,
+or pin a bridge release that predates v2. No error message contains a token.
+
+Every v1 and v2 `tools/call` is forwarded to Botmancers unchanged, and its
+result returned unchanged; Botmancers validates the arguments and applies
+the grants.
 
 | Exit | Meaning | What to do |
 | --- | --- | --- |
 | `0` | Stopped by SIGINT or SIGTERM. | Nothing. |
 | `2` | Configuration error: a missing or invalid variable or flag. Every problem is listed. | Fix the listed settings. |
 | `3` | Cannot listen, for example because the port is already in use. | Stop the other process, or choose another `--port`. |
-| `4` | Botmancers is unreachable, or `BOTMANCERS_URL` is not a Botmancers MCP endpoint (the server is not named `botmancers` or lacks a `botmancers.mcp.v1` tool). | Start the app, or fix the URL. |
+| `4` | Botmancers is unreachable, or `BOTMANCERS_URL` is not a compatible Botmancers MCP endpoint (the server is not named `botmancers`, or lacks a `botmancers.mcp.v1` or `botmancers.mcp.v2` tool). | Start or upgrade the app, or fix the URL. |
 | `5` | Botmancers rejected the service token, or the app has no service tokens configured. | Check `BOTMANCERS_SERVICE_TOKEN` against the app's `BOTMANCERS_SERVICE_TOKENS`. |
 
 If Botmancers becomes unavailable after startup, tool calls return a JSON-RPC
@@ -317,7 +459,7 @@ time. After that, npx may reuse its cached copy. To move deliberately, name
 the version:
 
 ```sh
-npx botmancers@0.3.0 --version
+npx botmancers@0.5.0 --version
 ```
 
 For a global full product, stop it, upgrade, and start it again. Your state
@@ -337,8 +479,9 @@ npm install -g botmancers@latest    # global
 ```
 
 Check the [changelog](CHANGELOG.md) before upgrading across a minor version
-while the package is `0.x`. The tool contract version, `botmancers.mcp.v1`,
-changes only with a major contract revision.
+while the package is `0.x`. The tool contract is versioned separately: the
+bundled `botmancers.mcp.v2` keeps `botmancers.mcp.v1` frozen, changes within v2
+are additive, and a breaking change is a new contract version.
 
 ## Uninstall
 
@@ -352,6 +495,9 @@ npm cache clean --force         # optional: drops npx's cached copy
 rm -rf ~/.botmancers/versions ~/.botmancers/current ~/.botmancers/update-state.json ~/.local/bin/botmancers   # managed install
 ```
 
+Before deleting the home, remove the client connections:
+`botmancers setup --client codex --remove` (and `cursor`, `claude`).
+
 For the full product, delete `~/.botmancers` (or your `BOTMANCERS_HOME`)
 only if you also want to delete its database, files, and credentials.
 

package/app/.next/BUILD_ID

@@ -1 +1 @@
-u4r8RPgEfpxk-DGXeKV6g
+gh3shm8hnVqXLr75rmvsL

package/app/.next/app-path-routes-manifest.json

@@ -4,6 +4,9 @@
   "/api/agent-deck/decks/route": "/api/agent-deck/decks",
   "/api/agent-deck/settings/route": "/api/agent-deck/settings",
   "/api/bots/[id]/config/route": "/api/bots/[id]/config",
+  "/api/bots/[id]/sessions/[ref]/pins/route": "/api/bots/[id]/sessions/[ref]/pins",
+  "/api/bots/[id]/sessions/[ref]/route": "/api/bots/[id]/sessions/[ref]",
+  "/api/bots/[id]/sessions/route": "/api/bots/[id]/sessions",
   "/api/bots/[id]/skill/route": "/api/bots/[id]/skill",
   "/api/bots/availability/route": "/api/bots/availability",
   "/api/bots/delete-preview/route": "/api/bots/delete-preview",
@@ -19,6 +22,9 @@
   "/api/conversations/[id]/route": "/api/conversations/[id]",
   "/api/conversations/[id]/stop/route": "/api/conversations/[id]/stop",
   "/api/conversations/route": "/api/conversations",
+  "/api/exchanges/[id]/cancel/route": "/api/exchanges/[id]/cancel",
+  "/api/exchanges/[id]/route": "/api/exchanges/[id]",
+  "/api/exchanges/route": "/api/exchanges",
   "/api/files/[name]/route": "/api/files/[name]",
   "/api/groups/route": "/api/groups",
   "/api/health/route": "/api/health",
@@ -27,14 +33,34 @@
   "/api/marketplace-handoff/status/route": "/api/marketplace-handoff/status",
   "/api/mcp/route": "/api/mcp",
   "/api/messages/[id]/between/route": "/api/messages/[id]/between",
+  "/api/runtime-connections/route": "/api/runtime-connections",
+  "/api/service-grants/route": "/api/service-grants",
+  "/api/v0/agents/[agentId]/conversations/[conversationId]/route": "/api/v0/agents/[agentId]/conversations/[conversationId]",
+  "/api/v0/agents/[agentId]/conversations/route": "/api/v0/agents/[agentId]/conversations",
   "/api/v0/agents/[agentId]/messages/route": "/api/v0/agents/[agentId]/messages",
+  "/api/v0/agents/[agentId]/pins/route": "/api/v0/agents/[agentId]/pins",
+  "/api/v0/agents/[agentId]/route": "/api/v0/agents/[agentId]",
+  "/api/v0/agents/[agentId]/sessions/[ref]/route": "/api/v0/agents/[agentId]/sessions/[ref]",
+  "/api/v0/agents/[agentId]/sessions/route": "/api/v0/agents/[agentId]/sessions",
+  "/api/v0/agents/route": "/api/v0/agents",
+  "/api/v0/capabilities/route": "/api/v0/capabilities",
   "/api/v0/conversations/[id]/route": "/api/v0/conversations/[id]",
+  "/api/v0/exchanges/[id]/cancel/route": "/api/v0/exchanges/[id]/cancel",
+  "/api/v0/exchanges/[id]/route": "/api/v0/exchanges/[id]",
+  "/api/v0/exchanges/route": "/api/v0/exchanges",
   "/api/v0/mcp/route": "/api/v0/mcp",
+  "/api/v0/pins/[pinRef]/detach/route": "/api/v0/pins/[pinRef]/detach",
+  "/api/v0/pins/[pinRef]/messages/route": "/api/v0/pins/[pinRef]/messages",
+  "/api/v0/pins/[pinRef]/route": "/api/v0/pins/[pinRef]",
   "/api/v0/requests/[id]/route": "/api/v0/requests/[id]",
+  "/api/v0/sessions/[ref]/messages/route": "/api/v0/sessions/[ref]/messages",
+  "/api/v0/sessions/[ref]/pins/route": "/api/v0/sessions/[ref]/pins",
   "/api/wake-grants/[id]/revoke/route": "/api/wake-grants/[id]/revoke",
   "/api/wakes/[id]/decision/route": "/api/wakes/[id]/decision",
   "/api/wakes/[id]/retry/route": "/api/wakes/[id]/retry",
   "/bots/[id]/config/page": "/bots/[id]/config",
+  "/exchanges/page": "/exchanges",
   "/page": "/",
-  "/settings/page": "/settings"
+  "/settings/page": "/settings",
+  "/threads/[id]/page": "/threads/[id]"
 }

package/app/.next/build-manifest.json

@@ -7,9 +7,9 @@
     "static/chunks/0cz1d0mv5g_q7.js"
   ],
   "lowPriorityFiles": [
-    "static/u4r8RPgEfpxk-DGXeKV6g/_buildManifest.js",
-    "static/u4r8RPgEfpxk-DGXeKV6g/_ssgManifest.js",
-    "static/u4r8RPgEfpxk-DGXeKV6g/_clientMiddlewareManifest.js"
+    "static/gh3shm8hnVqXLr75rmvsL/_buildManifest.js",
+    "static/gh3shm8hnVqXLr75rmvsL/_ssgManifest.js",
+    "static/gh3shm8hnVqXLr75rmvsL/_clientMiddlewareManifest.js"
   ],
   "rootMainFiles": [
     "static/chunks/3s6nzrbk-8mnv.js",

package/app/.next/prerender-manifest.json

@@ -5,7 +5,7 @@
       "routeType": "page",
       "response": "complete",
       "compute": "static",
-      "htmlSize": 8434,
+      "htmlSize": 8785,
       "experimentalBypassFor": [
         {
           "type": "header",
@@ -86,11 +86,39 @@
         "x-next-revalidate-tag-token"
       ]
     },
+    "/exchanges": {
+      "routeType": "page",
+      "response": "complete",
+      "compute": "static",
+      "htmlSize": 9850,
+      "experimentalBypassFor": [
+        {
+          "type": "header",
+          "key": "next-action"
+        },
+        {
+          "type": "header",
+          "key": "content-type",
+          "value": "multipart/form-data;.*"
+        }
+      ],
+      "initialRevalidateSeconds": false,
+      "srcRoute": "/exchanges",
+      "dataRoute": "/exchanges.rsc",
+      "allowHeader": [
+        "host",
+        "x-matched-path",
+        "x-prerender-revalidate",
+        "x-prerender-revalidate-if-generated",
+        "x-next-revalidated-tags",
+        "x-next-revalidate-tag-token"
+      ]
+    },
     "/settings": {
       "routeType": "page",
       "response": "complete",
       "compute": "static",
-      "htmlSize": 8802,
+      "htmlSize": 9038,
       "experimentalBypassFor": [
         {
           "type": "header",
@@ -118,8 +146,8 @@
   "dynamicRoutes": {},
   "notFoundRoutes": [],
   "preview": {
-    "previewModeId": "2dafcdf4ba176137ac2fed825477055c",
-    "previewModeSigningKey": "e7e86d5fa0a1417836f6f550b33f2c1a209a012ed7fdc48058a2739a537bb02e",
-    "previewModeEncryptionKey": "fbc5f85fcf768d76d55e8363de7bb023ee40b8dac5219ad09afa91db80b775a5"
+    "previewModeId": "6c55e1ba527fcb83f7b80eee1c24bc4c",
+    "previewModeSigningKey": "bd7a056fdf6b23a83b52e2bf319cf8c2d1b695b40f239a5b8bf795df2d06b1b3",
+    "previewModeEncryptionKey": "ef09c30a78d1197e9dc468ecb1145834b8f330cdb0c6b3b1b3b71c8a13b782fe"
   }
 }

package/app/.next/required-server-files.json

@@ -2,8 +2,8 @@
   "version": 1,
   "config": {
     "env": {
-      "BOTMANCERS_BUILD_VERSION": "0.3.0",
-      "BOTMANCERS_BUILD_COMMIT": "a08e532e759845e03310017398ab584ebc9d5b9e"
+      "BOTMANCERS_BUILD_VERSION": "0.5.0",
+      "BOTMANCERS_BUILD_COMMIT": "47984e52c3b4b718ad944d03532e9b80efc95529"
     },
     "webpack": null,
     "typescript": {