@canonmsg/codex-plugin 0.23.4 → 0.23.5

package/README.md

@@ -14,6 +14,7 @@ npm install -g @canonmsg/codex-plugin
 codex login status
 
 # Register (approve in Canon when prompted)
+export CANON_ENVIRONMENT_ID=canon-prod-v1
 canon-codex-register --name "My Codex" --description "My local coding agent" --phone "+15551234567"
 
 # Run inside a project and keep the host process running
@@ -39,30 +40,51 @@ canon-necromance revive my-codex
 
 Do not run registration again unless Canon tells you the saved API key is invalid. If you registered multiple profiles, relaunch the same one with `CANON_AGENT=<profile> canon-codex --cwd /path/to/project`.
 
+`canon-codex-setup` reprints these steps and the optional flags at any time.
+
 Public docs: <https://canonmail.com/agents/integrations>. Coding-host concepts: <https://canonmail.com/agents/coding-agents>.
 
-You do not need a git repo for host mode. The plugin passes `--skip-git-repo-check` to Codex, so any readable working directory is valid.
+You do not need a git repo for host mode. Any readable working directory is valid.
 
-## What v1 supports
+## What the host supports
 
 - Canon messages routed into Codex turns
-- One Codex thread per Canon conversation
-- Resume by thread ID across turns
+- One Codex thread per Canon conversation, resumed by thread ID across turns
+- Queued input while a turn is running
 - RTDB session state and activity heartbeat
 - Interrupt by terminating the active Codex turn
 - Tool/running status surfaced while Codex is working
+- Reasoning-effort selection, resolved against what the active model accepts
+
+## Transports
+
+The host picks a transport at startup and logs the choice as
+`Codex transport: app-server` or `Codex transport: exec --json`.
 
-## Current limitation
+`codex app-server` is preferred and is selected when `codex app-server --help`
+succeeds. On it Canon additionally routes native plan mode and plan review,
+compact, rich cards, blocking approval gates, runtime questions, live message
+deltas, and model/effort discovery from the runtime.
 
-The stable `codex exec --json` surface exposes thinking state, tool activity, and completed assistant-message previews, but not token-by-token text deltas. v1 therefore publishes live progress and assistant-message snapshots without claiming true token streaming.
+`codex exec --json` is the fallback for older Codex CLIs. It reports thinking
+state, tool activity, and completed assistant-message previews, but not
+token-by-token deltas, and it cannot block on approvals — Canon labels the
+session with that warning rather than implying a gate it does not have. Without
+discovery it also offers no model picker and a fixed effort list.
 
-Current Canon control truth for Codex host mode:
+Set `CANON_CODEX_TRANSPORT=exec` or `CANON_CODEX_TRANSPORT=app-server` to skip
+the probe when it misfires.
 
-- model is live-visible, but current changes apply on the next turn rather than mid-turn
+Canon control truth for Codex host mode:
+
+- model is live-visible, but changes apply on the next turn rather than mid-turn
+- reasoning effort is live-editable and also applies on the next turn; the option list comes from the active model
 - workspace selection is setup-only
 - execution mode selection is setup-only
-- the current `Execution policy`/permission choice is setup-only
-- advanced Codex-only controls such as effort, sandbox policy, approval reviewer, or apps/plugins inventory are not exposed on the current transport unless the runtime can actually report them
+- the `Execution policy`/permission choice is session-creation-only; mid-session change requests are ignored and the applied value is re-published
+
+The runtime descriptor the host publishes is the authoritative capability list;
+what Canon renders always comes from it, not from this file.
 
 ## Working directory
 
@@ -85,14 +107,23 @@ Worktree mode is project isolation, not an operating-system sandbox. The Codex C
 Useful flags:
 
 ```bash
-canon-codex --cwd /path/to/project --model gpt-5.5 --full-auto
+canon-codex --cwd /path/to/project --model <model-id> --full-auto
 ```
 
-Codex also supports `--add-dir /extra/path` for additional writable directories passed through to `codex exec`. Canon does not yet render those extra directories as workspace choices.
+Canon hardcodes no model IDs: on the app-server transport the picker is built
+from what the local Codex runtime reports, and `--model` pins the default. A
+model your installed Codex CLI does not know fails early with an upgrade
+message.
 
-`gpt-5.5` requires a recent local Codex CLI. Older CLIs fail early with an upgrade message; upgrade Codex or choose a model supported by your installed CLI.
+`--add-dir /extra/path` adds a writable directory: the exec transport passes it
+through to `codex exec`, the app-server transport adds it to the thread's
+writable roots. Canon does not render those extra directories as workspace
+choices.
 
-Recent Codex CLI releases no longer accept `--ask-for-approval` with `codex exec`. If you previously launched Canon with `--sandbox workspace-write --ask-for-approval never`, switch to `--full-auto`.
+`--ask-for-approval` is rejected by Canon itself — the host exits with an error
+pointing at `--full-auto`, `--sandbox`, or Canon permission modes. If you
+previously launched with `--sandbox workspace-write --ask-for-approval never`,
+switch to `--full-auto`.
 
 Do not start Canon with `--sandbox danger-full-access` as an unlabeled default. Use `--dangerously-bypass-approvals-and-sandbox` only when you intentionally want Canon to advertise the owner-only Bypass policy.
 
@@ -125,7 +156,7 @@ canon-codex --cwd /path/to/project --codex-bin /absolute/path/to/codex
 If Canon rejects authenticated requests with `401 Invalid API key`, the stored Canon profile needs a fresh key. Reconnect the same profile to overwrite `~/.canon/agents.json`, then restart or revive the host:
 
 ```bash
-canon-codex-register --name "My Codex" --description "My local coding agent" --phone "+15551234567" --profile my-codex
+CANON_ENVIRONMENT_ID=canon-prod-v1 canon-codex-register --name "My Codex" --description "My local coding agent" --phone "+15551234567" --profile my-codex
 ```
 
 If Codex reports API-key quota errors while another local tool on the same machine uses OpenAI API keys, check Codex's own stored login state:
@@ -147,10 +178,13 @@ Restart `canon-codex` after changing the Codex login state.
 ## Multiple agents
 
 ```bash
+export CANON_ENVIRONMENT_ID=canon-prod-v1
 canon-codex-register --name "Frontend" --description "React work" --phone "+1..." --profile frontend
 CANON_AGENT=frontend canon-codex --cwd ~/projects/frontend
 ```
 
+With more than one registered profile, `CANON_AGENT` is required — the host refuses to guess and lists the available profiles instead.
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.23.4",
+  "version": "0.23.5",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -29,9 +29,9 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^7.1.2",
-    "@canonmsg/coding-agent-host": "^0.3.0",
-    "@canonmsg/core": "^8.1.0"
+    "@canonmsg/agent-sdk": "^7.1.3",
+    "@canonmsg/coding-agent-host": "^0.3.1",
+    "@canonmsg/core": "^8.2.0"
   },
   "engines": {
     "node": ">=18.0.0"