botmancers 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+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`.
+
+## [0.3.0] - 2026-10-16
+
+### Added
+
+- Managed install, following the Agent Deck / Agent Dealer contract:
+  `curl -fsSL https://raw.githubusercontent.com/not-so-fat/botmancers/main/scripts/install.sh | bash`
+  or `botmancers install [--to VERSION] [--migrate-cli] [--purge-global]`
+  installs the exact npm release into `~/.botmancers/versions/<version>`,
+  checks its sha512 integrity and contents, atomically points
+  `~/.botmancers/current` at it, and writes the stable launcher
+  `~/.local/bin/botmancers`. Existing data, configuration, logs, and workdirs
+  are not touched.
+- Safe automatic updates for managed installs, on by default: at most one
+  background npm `latest` check per 24 hours, a verified download next to the
+  running release, and activation only at the next `botmancers start` once no
+  Botmancers process from the home is live. `status`, `open`, `doctor`, the
+  bridge, and a running product never switch releases.
+  `BOTMANCERS_DISABLE_AUTOUPDATER=1` turns all of it off. Explicit installs,
+  upgrades, and rollbacks wait for a background download (`update.lock`), and
+  a start's stopped check, any release switch, and the supervisor's claim on
+  the home are serialized (`run/start.lock`). A release is made current only
+  when every module its CLI loads and this platform's better-sqlite3 binary
+  are present.
+- `botmancers upgrade [--check] [--to VERSION] [--yes]`: managed installs
+  download, verify, and activate (or stage while the product runs).
+  npm-global installs keep the prompted `npm install -g botmancers@<version>`.
+  npx, project-local, and source-checkout copies report how to upgrade and
+  never change themselves.
+- Rollback with `botmancers install --to <older>`. The newer version is then
+  not reinstated automatically. Activation keeps the active release and the
+  two newest other complete releases, and removes incomplete trees.
+- `status` and `doctor` report the install kind, launcher, `PATH` shadowing,
+  the CLI, current, and pending versions, the versions the live core and
+  bridge report, and the restart action.
+
+### Fixed
+
+- After a release switch beneath a running product, the newer CLI reports the
+  old core and bridge versions as degraded instead of treating the old bridge
+  as not running (NOT-279 class). It can still stop that product. The run
+  record now stores the CLI path the product was started from.
+
+## [0.2.0] - 2026-10-16
+
+### Added
+
+- The full Botmancers product in the package: the production Next.js UI, API
+  routes, and core engine (standalone server under `app/`, with every
+  platform's SQLite prebuild) next to the MCP bridge.
+- `botmancers setup`: creates `BOTMANCERS_HOME` (default `~/.botmancers`)
+  owner-only and generates the bridge-to-core service token (the engine
+  stores only its digest) and the inbound MCP token; prints the Hermes and
+  Agent Deck steps without writing their credentials.
+- `botmancers start [--daemon] [--open]`, `stop`, `status`, `doctor`, and
+  `open`: one supervisor runs the UI/core on `127.0.0.1:43123` and the bridge
+  on `127.0.0.1:43124`, with one health model (healthy / degraded /
+  stopped), idempotent start, stale run-metadata repair, and deterministic
+  exit codes.
+- `botmancers mcp`, the explicit bridge-only command.
+- Core `GET /api/health` reporting the running release version.
+
+### Changed
+
+- Installed-product state (database, files, skills, logs, configuration, run
+  metadata) lives under `BOTMANCERS_HOME` regardless of the launch directory.
+  Explicit `BOTMANCERS_DB_PATH`, `BOTMANCERS_FILES_ROOT`,
+  `BOTMANCERS_SKILLS_ROOT` (new), and `HERMES_WAIT_LOG_PATH` still win; a
+  source checkout without `BOTMANCERS_HOME` keeps its cwd-relative files.
+- Bare `botmancers` is unchanged (bridge only, same flags, environment, and
+  exit codes); `--help` now also points to the product commands.
+
+## [0.1.0] - 2026-10-15
+
+### Added
+
+- `botmancers` CLI (`npx botmancers`), a standalone Streamable HTTP MCP bridge
+  that forwards the `botmancers.mcp.v1` tools to a Botmancers app's
+  `/api/v0/mcp` endpoint.
+- Configuration through `BOTMANCERS_URL`, `BOTMANCERS_SERVICE_TOKEN`,
+  `BOTMANCERS_MCP_TOKEN`, `BOTMANCERS_MCP_HOST`, and `BOTMANCERS_MCP_PORT`,
+  with `--botmancers-url`, `--host`, and `--port` flags. The bridge binds
+  loopback by default.
+- A startup preflight against Botmancers. Configuration, listen,
+  reachability, and credential failures each have their own exit code, and
+  their messages are redacted.
+- `GET /healthz` liveness endpoint.
+- The versioned tool schema at `schemas/botmancers.mcp.v1.tools.json`, and a
+  library export (`createBridge`, `parseCli`, and related functions).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuke Muraoka
+
+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

@@ -1,3 +1,379 @@
-# Temporary Holding Version
+# botmancers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Botmancers in one npm package: the web UI, the API and durable core engine,
+and the authenticated [MCP](https://modelcontextprotocol.io) bridge that lets
+an external agent hand a task to a Botmancers coordinator Agent and poll the
+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.
+- 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`.
+
+| 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_health` | Shows the caller's identity and the available coordinators. |
+
+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).
+The full product is supported on macOS and Linux (x64 and arm64); the
+bundled SQLite driver also ships Windows binaries, but the supervisor is
+untested there.
+
+## Quick start: the full product
+
+The recommended install is the **managed install**. It needs Node.js and
+npm, and no global npm package or source checkout:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/not-so-fat/botmancers/main/scripts/install.sh | bash
+botmancers setup
+botmancers start --daemon --open
+```
+
+The script runs `npx botmancers@latest install`. That command installs the
+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`.
+
+npm-global installs and bare `npx` still work for compatibility:
+
+```sh
+npx botmancers setup
+npx botmancers start --daemon --open
+```
+
+`setup` creates `~/.botmancers` (owner-only) and generates two local
+credentials: the service token the bridge uses to call the core engine (the
+engine stores only its SHA-256 digest) and the MCP token your MCP clients
+send to the bridge. It never writes Hermes, Agent Deck, or coding-agent
+credentials; it prints where to add them. `start --daemon` launches the UI,
+API, core engine, and bridge in the background and returns once both are
+healthy; `--open` opens the UI in your browser.
+
+Then:
+
+1. **Open the UI** at `http://127.0.0.1:43123` (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`,
+   then `botmancers stop && botmancers start --daemon`.
+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
+   `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.
+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
+`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 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 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 |
+| `botmancers upgrade [--check] [--to VERSION] [--yes]` | Updates this install. See [Upgrade](#upgrade). | `0`; `1` failed, or this kind of install cannot update itself; `2` usage |
+
+`healthy` means the supervisor and both processes are alive, the core's
+`GET /api/health` and the bridge's `GET /healthz` report the installed
+version, and an authenticated bridge call reaches the core. Anything else
+that is running is `degraded` and never reported healthy: one process down,
+a version mismatch, or a start that has not finished. Run metadata whose
+processes are gone is removed automatically. Each process is recorded with
+its start time, and a recorded process id is only signalled when both its
+start time and its command line still match, so a recycled PID (even another
+Next.js server) is never touched. When identity cannot be verified (no `ps`,
+or metadata from an older release) nothing is signalled and the metadata is
+kept; the same holds if a process survives `stop`, so `status` keeps
+reporting it and `stop` can be retried.
+
+### Where state lives
+
+Everything the product writes lives under `BOTMANCERS_HOME` (default
+`~/.botmancers`), whatever directory you start it from:
+
+| Path | Contents |
+| --- | --- |
+| `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. |
+| `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. |
+| `run/product.json` | Run metadata of the supervised product. |
+| `versions/`, `current`, `update-state.json` | Managed install only: the release trees, the link to the active one, and updater metadata. |
+
+The home and `config/` are created `0700` and the credential files `0600`.
+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.
+
+## Bridge only
+
+Use bare `botmancers` (or `botmancers mcp`) when you run the Botmancers app
+yourself, for example from a source checkout. Requirements: Node.js 20 or
+newer and a running Botmancers app.
+
+1. **Create two tokens.** The service token authenticates the bridge to
+   Botmancers. The MCP token authenticates MCP clients to the bridge.
+
+   ```sh
+   export BOTMANCERS_SERVICE_TOKEN=$(openssl rand -hex 32)
+   export BOTMANCERS_MCP_TOKEN=$(openssl rand -hex 32)
+   printf %s "$BOTMANCERS_SERVICE_TOKEN" | shasum -a 256   # -> <hex>, for the next step
+   ```
+
+2. **Configure the Botmancers app**, in the environment of its `npm start`.
+   Store only the token's digest there, and allowlist the coordinators the
+   bridge may use:
+
+   ```sh
+   BOTMANCERS_SERVICE_TOKENS="mcp-bridge=sha256:<hex>"
+   BOTMANCERS_MCP_COORDINATORS="Tank"
+   ```
+
+3. **Start the bridge:**
+
+   ```sh
+   BOTMANCERS_URL=http://127.0.0.1:43123 npx botmancers
+   ```
+
+   It prints
+   `botmancers <version>: MCP bridge listening on http://127.0.0.1:43124/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
+   `Authorization: Bearer <BOTMANCERS_MCP_TOKEN>`. Then call
+   `botmancers_health`. It should return `status: "ok"` and each coordinator
+   with `available: true`.
+
+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
+```
+
+## 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_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. |
+
+Flags override environment variables. Secrets are accepted only from the
+environment, because command-line flags are visible to every local user in
+the process list. `--service-token` and `--mcp-token` are refused.
+
+`botmancers --help` lists the options. `botmancers --version` prints the
+installed version.
+
+### Endpoints
+
+- `POST /mcp` is MCP Streamable HTTP. It is stateless and answers with
+  `application/json`, using protocol versions `2025-11-25`, `2025-06-18`, and
+  `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>"}`.
+  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.
+
+| 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. |
+| `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
+error (`-32603`) whose `data.code` is `botmancers_unreachable`,
+`botmancers_unauthorized`, or a similar code. The bridge keeps running. When
+Botmancers rate-limits a tool call, the bridge answers 429 and passes on
+`Retry-After`.
+
+## Network exposure
+
+- **Loopback by default.** The bridge binds `127.0.0.1`. While it is bound to
+  loopback, it refuses any request whose `Host` is not a loopback name, and
+  any `Origin` other than its own. This guards against DNS rebinding. The
+  bridge does not support CORS, so browser pages cannot call it.
+- **Remote MCP consumers.** A hosted agent such as Grok Bot cannot reach your
+  loopback address. Put the bridge behind an HTTPS endpoint that you control,
+  such as a TLS-terminating reverse proxy or tunnel, or reach it over a
+  private network such as a VPN or tailnet. Do not expose it as plain HTTP on
+  the public internet: the MCP token would travel in cleartext. If you bind a
+  non-loopback address (`--host 0.0.0.0`), the bridge prints a warning. Keep
+  the proxy or network in front of it.
+- **Botmancers itself** should stay on loopback, with the bridge on the same
+  machine. `botmancers start` binds both the UI/core and the bridge to
+  `127.0.0.1` only. If `BOTMANCERS_URL` points to another host over plain `http://`,
+  the bridge warns that the service token is sent unencrypted. Use `https://`
+  in that case.
+- Rotate a token by changing it and restarting the bridge. For the service
+  token, also update its digest in the app's `BOTMANCERS_SERVICE_TOKENS`.
+
+## Upgrade
+
+### Managed install (automatic)
+
+A managed install checks npm's `latest` tag at most once every 24 hours, in a
+background process, so no command waits on the network. A newer release is
+downloaded next to the running one under a temporary name, checked against
+the registry's sha512 integrity and for a complete package, and then
+recorded as **pending**. The running product is not stopped or changed.
+`botmancers status` shows the versions the live core and bridge report, the
+pending version, and the restart command:
+
+```
+  versions    cli 0.3.0, current 0.3.0, pending 0.3.1 (staged, not running)
+  running     core 0.3.0, bridge 0.3.0 (started by 0.3.0)
+  restart     botmancers stop && botmancers start --daemon   (activates 0.3.1)
+```
+
+The pending release becomes current only when `botmancers start` has checked
+that no Botmancers process from this home is still running. `status`,
+`open`, `doctor`, the bridge, and a running product never switch it. If the
+product is still running, `start` leaves it alone and prints the restart
+command. Restart once to activate the pending release:
+
+```sh
+botmancers stop && botmancers start --daemon
+```
+
+Set `BOTMANCERS_DISABLE_AUTOUPDATER=1` to turn off the automatic checks,
+downloads, and activation completely. `botmancers upgrade` still works when
+it is set.
+
+Explicit commands:
+
+```sh
+botmancers upgrade --check          # installed, latest, and pending versions; changes nothing
+botmancers upgrade                  # download, verify, and activate latest
+botmancers upgrade --to 0.3.0       # a specific version
+botmancers install --to 0.3.0       # roll back (no download if it is still installed)
+```
+
+If the product is running, `upgrade` downloads the release and marks it
+pending. It does not switch versions underneath the running product. After a
+rollback, the newer version is not reinstalled automatically. A later
+`botmancers upgrade` moves forward again. The active release and the two most
+recent other complete releases are kept, and older or incomplete release
+trees are removed when a release is activated. Install, upgrade, rollback,
+and pruning change only `versions/`, `current`, `update-state.json`, and the
+launcher. They never touch your data, configuration, logs, or workdirs.
+
+If `botmancers doctor` reports that another `botmancers` (for example an
+npm-global copy) shadows `~/.local/bin/botmancers` on `PATH`, put
+`~/.local/bin` first, or run `botmancers install --purge-global` to remove
+the global copy.
+
+### npm-global, npx, and project-local installs
+
+These never update themselves automatically. `botmancers upgrade` on an
+npm-global install asks before it runs `npm install -g botmancers@<version>`
+(`--yes` skips the question). On any other kind of install, it explains how
+to upgrade and changes nothing.
+
+`npx botmancers` resolves the newest release on the `latest` tag the first
+time. After that, npx may reuse its cached copy. To move deliberately, name
+the version:
+
+```sh
+npx botmancers@0.3.0 --version
+```
+
+For a global full product, stop it, upgrade, and start it again. Your state
+in `BOTMANCERS_HOME` is kept:
+
+```sh
+botmancers stop
+npm install -g botmancers@latest
+botmancers start --daemon
+```
+
+To upgrade a project-local or global install:
+
+```sh
+npm install botmancers@latest       # project-local
+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.
+
+## Uninstall
+
+Stop the product with `botmancers stop` (or the bridge with Ctrl-C or
+SIGTERM), then remove the package:
+
+```sh
+npm uninstall botmancers        # project-local
+npm uninstall -g botmancers     # global
+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
+```
+
+For the full product, delete `~/.botmancers` (or your `BOTMANCERS_HOME`)
+only if you also want to delete its database, files, and credentials.
+
+For the bridge only, remove its entry from the app's
+`BOTMANCERS_SERVICE_TOKENS` so its token stops working. The bridge stores no
+files of its own.
+
+## Library use
+
+The package also exports the bridge for embedding:
+
+```js
+import { createBridge, parseCli } from 'botmancers';
+
+const command = parseCli([], process.env);
+if (command.kind === 'serve') {
+  const bridge = createBridge({ config: command.config });
+  await bridge.upstream.preflight();
+  const address = await bridge.listen();
+}
+```
+
+## License
+
+MIT

package/app/.next/BUILD_ID

@@ -0,0 +1 @@
+u4r8RPgEfpxk-DGXeKV6g

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

@@ -0,0 +1,40 @@
+{
+  "/_global-error/page": "/_global-error",
+  "/_not-found/page": "/_not-found",
+  "/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]/skill/route": "/api/bots/[id]/skill",
+  "/api/bots/availability/route": "/api/bots/availability",
+  "/api/bots/delete-preview/route": "/api/bots/delete-preview",
+  "/api/bots/import/route": "/api/bots/import",
+  "/api/bots/manage/route": "/api/bots/manage",
+  "/api/bots/name-migrations/route": "/api/bots/name-migrations",
+  "/api/bots/route": "/api/bots",
+  "/api/conversations/[id]/approve/route": "/api/conversations/[id]/approve",
+  "/api/conversations/[id]/deny/route": "/api/conversations/[id]/deny",
+  "/api/conversations/[id]/draft/route": "/api/conversations/[id]/draft",
+  "/api/conversations/[id]/messages/[messageId]/stop/route": "/api/conversations/[id]/messages/[messageId]/stop",
+  "/api/conversations/[id]/messages/route": "/api/conversations/[id]/messages",
+  "/api/conversations/[id]/route": "/api/conversations/[id]",
+  "/api/conversations/[id]/stop/route": "/api/conversations/[id]/stop",
+  "/api/conversations/route": "/api/conversations",
+  "/api/files/[name]/route": "/api/files/[name]",
+  "/api/groups/route": "/api/groups",
+  "/api/health/route": "/api/health",
+  "/api/import-capabilities/route": "/api/import-capabilities",
+  "/api/marketplace-handoff/route": "/api/marketplace-handoff",
+  "/api/marketplace-handoff/status/route": "/api/marketplace-handoff/status",
+  "/api/mcp/route": "/api/mcp",
+  "/api/messages/[id]/between/route": "/api/messages/[id]/between",
+  "/api/v0/agents/[agentId]/messages/route": "/api/v0/agents/[agentId]/messages",
+  "/api/v0/conversations/[id]/route": "/api/v0/conversations/[id]",
+  "/api/v0/mcp/route": "/api/v0/mcp",
+  "/api/v0/requests/[id]/route": "/api/v0/requests/[id]",
+  "/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",
+  "/page": "/",
+  "/settings/page": "/settings"
+}

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

@@ -0,0 +1,24 @@
+{
+  "pages": {
+    "/_app": []
+  },
+  "devFiles": [],
+  "polyfillFiles": [
+    "static/chunks/0cz1d0mv5g_q7.js"
+  ],
+  "lowPriorityFiles": [
+    "static/u4r8RPgEfpxk-DGXeKV6g/_buildManifest.js",
+    "static/u4r8RPgEfpxk-DGXeKV6g/_ssgManifest.js",
+    "static/u4r8RPgEfpxk-DGXeKV6g/_clientMiddlewareManifest.js"
+  ],
+  "rootMainFiles": [
+    "static/chunks/3s6nzrbk-8mnv.js",
+    "static/chunks/19mx3mg6lkumu.js",
+    "static/chunks/3g4px251sg85e.js",
+    "static/chunks/2z-e6jheq0ftu.js",
+    "static/chunks/turbopack-03rfayxv7ep_b.js"
+  ],
+  "rootMainFilesTree": {},
+  "pagesChunkGroupBootstrapParams": {},
+  "chunkLoadingGlobal": "TURBOPACK"
+}

package/app/.next/node_modules/better-sqlite3-90e2652d1716b047/index.js

@@ -0,0 +1 @@
+module.exports = require("better-sqlite3");

package/app/.next/node_modules/better-sqlite3-90e2652d1716b047/package.json

@@ -0,0 +1 @@
+{"name":"better-sqlite3-90e2652d1716b047","private":true,"main":"index.js"}

package/app/.next/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}