@canonmsg/claude-code-plugin 0.28.1 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.28.1",
+  "version": "0.29.1",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/index.js",
@@ -31,11 +31,11 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.220",
-    "@canonmsg/agent-sdk": "^7.1.1",
-    "@canonmsg/agent-tools": "^0.3.1",
-    "@canonmsg/coding-agent-host": "^0.2.2",
-    "@canonmsg/core": "^8.0.0",
-    "@canonmsg/rich-cards": "^0.8.5",
+    "@canonmsg/agent-sdk": "^7.1.3",
+    "@canonmsg/agent-tools": "^0.3.2",
+    "@canonmsg/coding-agent-host": "^0.3.1",
+    "@canonmsg/core": "^8.2.0",
+    "@canonmsg/rich-cards": "^0.8.6",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "engines": {

package/skills/configure/SKILL.md

@@ -1,50 +1,59 @@
 ---
 name: canon-configure
-description: Configure an existing Canon agent API key
+description: Use an existing Canon agent API key with Claude Code
 user-invocable: true
 allowed-tools:
   - Read
   - Write
 ---
 
-# Configure Canon API Key
+# Use an existing Canon API key
 
-Add an existing Canon agent API key as a named profile.
+Point Claude Code at a Canon agent key the user already has.
+
+## Hard rule
+
+Never write or edit `~/.canon/agents.json`. A stored profile must carry the agent
+identity **and** a complete environment-bound endpoint set (`agentId`,
+`environmentId`, `baseUrl`, `streamUrl`, `rtdbUrl`, `firebaseApiKey`), and every
+entry is validated in one pass on load — a single hand-written entry makes the
+whole file unloadable for every Canon host on that machine. Only the register
+CLI writes profiles.
 
 ## Steps
 
 1. Ask the user for:
-   - **API key** — must start with `agk_live_`
-   - **Profile name** — a short identifier (e.g., "my-agent", "reviewer")
-   - **Agent name** (optional) — display name for reference
-
-2. Validate the API key format — it must start with `agk_live_` and be non-empty.
+   - **API key** — starts with `agk_live_`
+   - **Canon environment** — `canon-prod-v1` for production, `canon-dev-v1` for dev
 
-3. Read the existing profiles from `~/.canon/agents.json` (create if missing).
+2. Give them the launch command for the key. Nothing is stored; the key lives in
+   the environment of the process they start:
 
-4. Add/update the profile:
-   ```json
-   {
-     "<profile>": {
-       "apiKey": "<key>",
-       "agentId": "",
-       "agentName": "<name or 'Unknown'>",
-       "registeredAt": "<current ISO date>"
-     }
-   }
+   ```bash
+   CANON_API_KEY=<key> CANON_ENVIRONMENT_ID=<environment> canon-claude --cwd /path/to/project
    ```
 
-5. Write the updated profiles to `~/.canon/agents.json`.
+   `CANON_ENVIRONMENT_ID` is required with a raw key — without it the host exits
+   before connecting. Sessions started this way are shown as
+   manual/non-revivable by `canon-necromance`, because no secret-bearing state is
+   persisted.
 
-6. Tell the user: **"API key saved as profile '<profile>'. Restart Claude Code to connect."**
+3. If the user wants a stored, revivable profile instead, run `/canon-register`.
+   Registration is the only path that writes `~/.canon/agents.json`; re-running it
+   with an existing `--profile` name refreshes that profile's credential in place.
+
+4. Once a profile exists, it can be pinned for channel mode in `.mcp.json`:
 
-   If they have multiple agents and want to pin one, add to `.mcp.json`:
    ```json
    {
      "mcpServers": {
        "canon-channel": {
+         "command": "canon-channel-server",
          "env": { "CANON_AGENT": "<profile>" }
        }
      }
    }
    ```
+
+   `CANON_AGENT` is required as soon as more than one profile exists — the host
+   refuses to guess between them.

package/skills/register/SKILL.md

@@ -18,7 +18,7 @@ Register a new Canon agent so it can send and receive messages. Each agent is sa
    - **Agent name** — The display name for the agent in Canon
    - **Description** — What the agent does (shown to users in Canon)
    - **Owner phone number** — The Canon account owner's phone number in E.164 format (e.g., +15551234567)
-   - **Canon environment** — The trust-domain ID supplied by Canon (production defaults to `canon-prod-v1`)
+   - **Canon environment** — The trust-domain ID supplied by Canon (`canon-prod-v1` for production, `canon-dev-v1` for dev). There is no CLI default; the command fails without it.
    - **Profile name** (optional) — A short identifier for this agent (e.g., "reviewer", "notifier"). Defaults to a sanitized version of the agent name.
 
 2. Run the registration CLI:
@@ -26,18 +26,23 @@ Register a new Canon agent so it can send and receive messages. Each agent is sa
    canon-register --environment "<environment>" --name "<name>" --description "<description>" --phone "<phone>" --profile "<profile>"
    ```
 
+   `CANON_ENVIRONMENT_ID=<environment>` in the environment is equivalent to `--environment`.
+
 3. Tell the user: **"Open your Canon app and approve the agent registration request. Waiting for approval..."**
 
    The CLI will poll automatically for up to 5 minutes.
 
 4. On approval, the CLI saves the agent to `~/.canon/agents.json` automatically.
 
-5. Tell the user: **"Agent registered! Run `canon-claude` to start. Or specify a project: `canon-claude --cwd /path/to/project`"**
+5. Tell the user: **"Agent registered! Start it with `CANON_AGENT=<profile> canon-claude`. Or specify a project: `CANON_AGENT=<profile> canon-claude --cwd /path/to/project`"**
+
+   `CANON_AGENT` is required once more than one profile exists — the host refuses to guess between them.
 
 ## Error handling
 
 - If the registration fails, show the error and ask the user to retry.
 - If status returns `"rejected"`, tell the user the registration was rejected by the owner.
 - If polling times out after 5 minutes, tell the user to try again later.
-- If the phone number format is wrong (must start with `+`, 8-16 digits), ask the user to re-enter it.
+- If the server returns `Invalid phone number format`, the number could not be parsed as a real number; ask the user to re-enter it in full E.164 form (`+<country code><number>`).
+- If the server returns `Owner phone number not found on platform`, the number is valid but no Canon account uses it; ask the user for the phone number of their Canon account.
 - If environment verification fails, do not retry against another URL. Confirm the environment ID and endpoint set with the user.