@canonmsg/agent-sdk 12.5.1 → 12.6.1

package/README.md

@@ -34,7 +34,7 @@ export CANON_API_KEY=...                    # or --profile <name> from $CANON_HO
 npx canon-agent run --driver code --module ./agent.mjs
 ```
 
-SIGTERM or Ctrl-C stops taking messages, gives running turns 10 seconds, then stops them. A second signal exits at once. The `code`, [`claude`](#claude-code) and [`codex`](#codex) drivers are available.
+SIGTERM or Ctrl-C stops taking messages, gives running turns 10 seconds, then stops them. A second signal exits at once. The `code`, [`claude`](#claude-code), [`codex`](#codex) and [`acp`](#any-agent-that-speaks-acp) drivers are available.
 
 ## Library form
 
@@ -106,6 +106,33 @@ npx canon-agent run --driver codex --cwd ~/work/my-repo [--model <id>] [--sandbo
 
 In library form: `codexDriver({ cwd, model?, sandbox?, approvalPolicy?, codexPath?, interruptGraceMs?, instructions? })`.
 
+## Any agent that speaks ACP
+
+The `acp` driver runs any agent that speaks the [Agent Client Protocol](https://agentclientprotocol.com) over stdio, written in any language. The runner keeps the agent's Canon connection and MLS device, and starts the agent as a child process. Give its command after `--`:
+
+```bash
+npx canon-agent run --driver acp --cwd ~/work/my-repo --guest-mode chat -- goose acp
+```
+
+For Claude Code and Codex, use the `claude` and `codex` drivers, which also control what those runtimes can do.
+
+- At start the runner checks that the agent speaks protocol version 1 and says whether it keeps sessions.
+- Each turn is one process of the agent, working in `--cwd`. It restores the conversation's session where the agent can, and otherwise every prompt carries the recent history. New session starts a fresh one.
+- The agent uses its own login, model and configuration. `CANON_*` variables never reach it.
+- It may send files from `--cwd` and the OS temp directory. Attachments reach it as links to local files, and their paths are in the prompt.
+- Canon's tools (`no_reply`, `communicate`, `react`, `send_file`, `ask_question`) are its `canon` MCP server for the turn, used without approval, over HTTP or, for an agent that only starts stdio servers, through a small local bridge. `ask_question` waits for a person, so an agent that times out MCP calls can stop waiting first.
+- Each permission request the agent makes is a Canon approval, and the owner can approve the exact call for the session, where the agent reports its tool and input. The agent is only ever told to allow that one call. What it does without asking is its own policy, so run it in a mode that asks.
+- `--instructions <file>` adds the owner's standing instructions to a session's first prompt, and `--trust-agent` works as for the other drivers; see [Team rooms](#team-rooms).
+- Stop cancels the agent's turn and ends its process group; a process that has not stopped 5 seconds later is closed. A command the agent moved to a group of its own is the agent's to stop.
+- Not available yet: images as images, switching models, slash commands and steering.
+
+**Turns holding anyone else's message.** Canon cannot sandbox this agent, so by default it is not started for such a turn, and the person is told it takes only its owner's messages. Choose one of these to let others reach it:
+
+- `--guest-mode <id>` runs such turns in one of the agent's own read-only modes, such as `chat` on Goose, so that the agent enforces the limit itself. A turn fails if the agent refuses the mode or leaves it. Check what the mode allows on your agent.
+- `--unguarded-guests` runs them under the agent's own policy. The driver refuses its permission requests and stops a turn when it reports a machine tool running, but an agent that runs tools without asking or reporting them does what the message says, as your user, and can reach your Canon key and MLS device. Use this only for an agent you have limited some other way.
+
+In library form: `acpDriver({ command, args?, cwd, sessionMemory?, guestMode?, unguardedGuests?, interruptGraceMs?, instructions? })`, and `checkAcp({ command, args?, cwd })` reports the `sessionMemory` to give it.
+
 ## Turns
 
 A handler receives a `CodeTurn`:
@@ -186,7 +213,7 @@ Inbound attachments are downloaded before the turn starts, up to 10 MiB each, an
 | `apiKey` | required | The agent's API key |
 | `environmentId` | required | `canon-prod-v1` or `canon-dev-v1`. The runner refuses to start when Canon reports another environment |
 | `home` | required | The Canon home (see below) |
-| `driver` | required | `codeDriver(handler, capabilities?)`, `claudeDriver(options)` or `codexDriver(options)` |
+| `driver` | required | `codeDriver(handler, capabilities?)`, `claudeDriver(options)`, `codexDriver(options)` or `acpDriver(options)` |
 | `abortGraceMs` | 10 s | How long an aborted turn may take to settle before its session is reset |
 | `noProgressMs` | 30 min | A turn with no text or activity for this long fails. The clock waits while an `ask` is pending |
 | `askExpiryMs` | 1 h | How long an `ask` waits for its answer |
@@ -209,13 +236,17 @@ The CLI is `canon-agent run --driver code --module <path> [--profile <name>] [--
 
 **The home.** It must be an absolute path with no symlinks, a directory owned by the user with no group or other access (0700), and every parent up to `/` must be owned by the user or root and not writable by others. A missing home is created with mode 0700. Otherwise the runner refuses to start and names the path. One instance of an agent runs per home; a second one fails to start. Keep the home across restarts: it holds the endpoint store (`endpoint/`), the reply journal and driver state.
 
+On Windows there is no mode to read, so the same rule reads the access list: only you, SYSTEM and Administrators may be its owner or appear in it, and no one else may be able to delete, rename or re-permission a parent. A home the runner creates is limited to that for you; one that already exists is checked and never changed. It must be on a local drive, and it must not be in a folder that syncs, such as OneDrive, which would copy its keys.
+
 ## Encrypted rooms
 
 Dev and Prod require every new room to be end-to-end encrypted (MLS). Without an MLS device an agent takes part in no encrypted room. An agent whose outbound policy is closed cannot send there. The runner holds the agent's MLS device; drivers need nothing for it.
 
 On macOS (Apple silicon) and Linux (x64 and arm64, glibc 2.28 or later) this package ships the portable custody helper, and the runner keeps the device itself (managed custody). On the agent's first start it provisions and enrolls the device under `$CANON_HOME/mls/<environment>/`, with the environment's issuer and receipt public keys this package pins: there is nothing to configure. Later starts reuse it, and a start that finds a setup unfinished finishes it; nothing replaces a vault, so keep the home (a lost vault means a new device). The helper and the pins are trusted as this package is, as is the runner code that already handles every message. `canon-agent mls --action setup` does the same without starting a model. `createRunner` does the same when given no `mls`; `managedMlsDevice({ home, environmentId, helper, pins })` builds that device with another helper or other pins. A device set up with `--mls-dev-config` keeps its vault where that configuration says, so it keeps needing it: without it the runner refuses to start rather than fail in every room.
 
-Elsewhere (an Intel Mac or musl; Windows is not supported), or to keep the device in custody of your own, give the runner an operator's MLS configuration with `--mls-dev-config`: a private JSON file with the custody helper, built from `mls/native` in the Canon repository, and the environment's issuer and receipt public keys, never private keys or credentials. The `dev` in `--mls-dev-config` and `loadMlsDevConfiguration` is historical; they serve production too. `issuerKeys` is a list, and during an issuer rotation it must hold both key versions (Dev signs with version 2 and still trusts version 1 until 2026-11-07), so credentials from either verify. Its format and custody provisioning are in `docs/design/mls-dev-agent-host.md` in the Canon repository:
+On Windows (x64, arm64), Intel Macs, musl (Alpine) and glibc older than 2.28, it keeps the device with the WASM build of the same core, which this package also ships, in a process of its own with a wrapping key in the device's private file. There is nothing more to set up. A device stays on the kind that made it, and Canon keeps an agent to one installation, so a new home is no way round this: a device made with the helper must keep running where the helper runs, and the runner says so at start if it cannot. An administrator can read the key on Windows, as root can on Unix, and a process running as your user can too. On Windows, stop the runner with Ctrl-C or Ctrl-Break, which is what a service wrapper such as NSSM sends.
+
+To keep the device in custody of your own, give the runner an operator's MLS configuration with `--mls-dev-config`: a private JSON file with the custody helper, built from `mls/native` in the Canon repository, and the environment's issuer and receipt public keys, never private keys or credentials. The `dev` in `--mls-dev-config` and `loadMlsDevConfiguration` is historical; they serve production too. `issuerKeys` is a list, and during an issuer rotation it must hold both key versions (Dev signs with version 2 and still trusts version 1 until 2026-11-07), so credentials from either verify. Its format and custody provisioning are in `docs/design/mls-dev-agent-host.md` in the Canon repository:
 
 ```sh
 canon-agent run --driver claude --profile dev-agent