@canonmsg/codex-plugin 0.23.3 → 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/dist/app-server-adapter.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { createInterface } from 'node:readline';
+import { normalizePlanStepStatus, renderPlanSteps } from '@canonmsg/coding-agent-host';
 const DEFAULT_DISCOVERY_REQUEST_TIMEOUT_MS = 5_000;
 export class CodexAppServerAdapter {
     cwd;
@@ -783,23 +784,20 @@ function summarizeItem(item) {
         return 'Searching the web';
     return null;
 }
+/**
+ * Codex's plan update in the shared plan grammar (`renderPlanSteps` in
+ * @canonmsg/coding-agent-host), so a plan card reads the same whichever host
+ * produced it. Codex numbers steps by their position in the plan it sent, so an
+ * entry with no step text is passed through as a blank that keeps its slot
+ * rather than renumbering the steps below it.
+ */
 function renderPlan(params) {
     const explanation = readString(params, 'explanation');
     const plan = Array.isArray(params.plan) ? params.plan : [];
-    const lines = [
-        explanation ? `**Plan**\n${explanation}` : '**Plan**',
-        ...plan.flatMap((entry, index) => {
-            if (!isRecord(entry))
-                return [];
-            const step = readString(entry, 'step');
-            if (!step)
-                return [];
-            const status = readString(entry, 'status') ?? 'pending';
-            const marker = status === 'completed' ? '[x]' : status === 'inProgress' ? '[~]' : '[ ]';
-            return [`${index + 1}. ${marker} ${step}`];
-        }),
-    ];
-    return lines.join('\n');
+    return renderPlanSteps(plan.map((entry) => ({
+        text: (isRecord(entry) ? readString(entry, 'step') : undefined) ?? '',
+        status: normalizePlanStepStatus(isRecord(entry) ? readString(entry, 'status') : undefined),
+    })), { explanation });
 }
 function defaultServerRequestResult(method) {
     if (method.includes('requestApproval'))

package/dist/host.js

@@ -5,7 +5,7 @@ import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
 import { getCodexImagePath, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, } from '@canonmsg/agent-sdk';
-import { captureTurnArtifactSnapshot, collectTurnArtifacts, } from '@canonmsg/coding-agent-host';
+import { buildTrailBlockId, buildUndeliverableFinalNotice, captureTurnArtifactSnapshot, collectTurnArtifacts, IDLE_TIMEOUT_MS, PLAN_BLOCK_TITLE, } from '@canonmsg/coding-agent-host';
 import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, resolveQuestionAllowOther, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, buildCanonInboundFrameV1, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, markLocalRuntimeStopped, normalizeTurnMetadata, parseRuntimeCardV1, RuntimeRequestManager, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, verifyResolvedAgentEnvironment, CanonApiError, loadRuntimeSessionState, sendMessageWithRetry, sendMessageWithRetryChunked, saveRuntimeSessionState, buildBoundedTurnTrail, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
@@ -74,8 +74,12 @@ export function buildCodexLiveSessionConfig(input) {
     };
 }
 const MAX_SESSIONS = 12;
-const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+// IDLE_TIMEOUT_MS (30 minutes) is shared with the other coding-agent hosts.
 const HEARTBEAT_MS = 30_000;
+/** How Codex says it finished the work but Canon would not take the answer. */
+const CODEX_UNDELIVERABLE_FINAL_WORDING = {
+    lead: 'The Codex host completed the turn, but Canon could not deliver the reply',
+};
 const IDLE_CHECK_MS = 60_000;
 const PLAN_REVIEW_TIMEOUT_MS = 10 * 60_000;
 const CODEX_RUNTIME_CAPABILITIES = {
@@ -1591,10 +1595,14 @@ export async function main() {
                     writeTurn(session);
                     stopVisibleWorkSignal(session);
                     upsertTurnBlock(session, {
-                        id: `plan:${session.currentTurnId}`,
+                        // Spelled through the shared helper, and with the same fallback
+                        // the other host uses: a plan arriving before a turn id would
+                        // otherwise mint the literal id `plan:null`, which two such turns
+                        // would share — one margin row for two plans.
+                        id: buildTrailBlockId('plan', session.currentTurnId ?? 'turn'),
                         kind: 'plan',
                         status: 'running',
-                        title: 'Plan',
+                        title: PLAN_BLOCK_TITLE,
                         text: event.text,
                     });
                     writeCodexStreaming(session, event.text, 'streaming');
@@ -1801,7 +1809,10 @@ export async function main() {
             const message = error instanceof ExecutionEnvironmentError
                 ? error.userMessage
                 : error instanceof CanonApiError
-                    ? `The Codex host completed the turn, but Canon could not deliver the reply: ${error.message}`
+                    // Shared with the other coding-agent hosts, which is where the bound
+                    // on the quoted error comes from: an unbounded API error body would
+                    // push this notice over the very limit that rejected the reply.
+                    ? buildUndeliverableFinalNotice({ error, wording: CODEX_UNDELIVERABLE_FINAL_WORDING })
                     : `The Codex host failed during the turn: ${error instanceof Error ? error.message : String(error)}`;
             session.state.lastError = message;
             writeState(session);

package/dist/turn-activity.js

@@ -1,15 +1,12 @@
+import { buildTrailBlockId, normalizeTrailKey } from '@canonmsg/coding-agent-host';
 export function createCommandBlockTracker() {
     return {
         sequence: 0,
         running: [],
     };
 }
-function normalizeOptionalString(value) {
-    const normalized = value?.trim();
-    return normalized ? normalized : undefined;
-}
 function textBlockId(turnId, itemId) {
-    return `message:${turnId ?? 'turn'}:${normalizeOptionalString(itemId) ?? 'latest'}`;
+    return buildTrailBlockId('message', turnId ?? 'turn', normalizeTrailKey(itemId) ?? 'latest');
 }
 function buildLiveText(blocks) {
     return blocks
@@ -54,12 +51,14 @@ export function applyTextSegmentBlock(state, input) {
 function nextCommandBlockId(tracker, turnId, itemId) {
     const stableTurnId = turnId ?? 'turn';
     if (itemId)
-        return `command:${stableTurnId}:${itemId}`;
+        return buildTrailBlockId('command', stableTurnId, itemId);
+    // Older Codex runtimes report no item id, so the per-turn sequence is what
+    // keeps two commands from sharing a row.
     tracker.sequence += 1;
-    return `command:${stableTurnId}:${tracker.sequence}`;
+    return buildTrailBlockId('command', stableTurnId, tracker.sequence);
 }
 export function beginCommandBlock(tracker, input) {
-    const itemId = normalizeOptionalString(input.itemId);
+    const itemId = normalizeTrailKey(input.itemId);
     if (itemId) {
         const existing = tracker.running.find((block) => block.itemId === itemId);
         if (existing)
@@ -74,7 +73,7 @@ export function beginCommandBlock(tracker, input) {
     return blockId;
 }
 export function claimCommandBlock(tracker, input) {
-    const itemId = normalizeOptionalString(input.itemId);
+    const itemId = normalizeTrailKey(input.itemId);
     const command = input.command.trim();
     const matchingIndex = itemId
         ? tracker.running.findIndex((block) => block.itemId === itemId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.23.3",
+  "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.1",
-    "@canonmsg/coding-agent-host": "^0.2.2",
-    "@canonmsg/core": "^8.0.0"
+    "@canonmsg/agent-sdk": "^7.1.3",
+    "@canonmsg/coding-agent-host": "^0.3.1",
+    "@canonmsg/core": "^8.2.0"
   },
   "engines": {
     "node": ">=18.0.0"