@canonmsg/codex-plugin 0.10.0 → 0.11.1

package/README.md

@@ -22,7 +22,9 @@ canon-codex --cwd /path/to/project
 
 Registration saves a Canon profile in `~/.canon/agents.json`, the same shared profile store used by the Claude Code integration and supported by the OpenClaw plugin.
 
-If the terminal closes or the machine restarts, the agent goes offline until you start the host again. Install `@canonmsg/local-agents` and run `canon-necromance` to list every recorded local agent from newest to oldest, then revive one in the foreground:
+`canon-codex` is the local agent process. Keep that terminal open while you want Canon to reach the agent. Closing it, logging out, rebooting, or sleeping long enough to stop the process takes the local agent offline until you revive it.
+
+Install `@canonmsg/local-agents` and run `canon-necromance` to list every recorded local agent from newest to oldest, then revive one in the foreground:
 
 ```bash
 npm install -g @canonmsg/local-agents
@@ -30,7 +32,9 @@ canon-necromance
 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`. Keep the revived terminal open; closing it takes this local agent offline.
+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`.
+
+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.
 

package/dist/host.js

@@ -4,7 +4,7 @@ import { randomUUID } from 'node:crypto';
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
 import { getCodexImagePath, materializeMessageMedia, } from '@canonmsg/agent-sdk';
-import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, createConversationMetadataLoader, createRuntimeStatePublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, loadRuntimeSessionState, markLocalRuntimeStopped, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, createConversationMetadataLoader, createRuntimeStatePublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, loadRuntimeSessionState, markLocalRuntimeStopped, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
 import { clearStoredThreadId, buildCodexThreadPolicyFingerprint, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
@@ -38,7 +38,10 @@ EXAMPLES
   canon-codex --cwd ~/dev/canon
   canon-codex --cwd ~/dev/canon --workspace-root ~/dev --full-auto
 
-Keep this terminal open while you want Canon to reach the agent.`;
+Keep this terminal open while you want Canon to reach the agent. Closing it,
+logging out, rebooting, or sleeping long enough to stop the process takes the
+local agent offline until you revive it. Docs:
+https://canonmail.com/agents/integrations`;
 const MAX_SESSIONS = 12;
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 const HEARTBEAT_MS = 30_000;
@@ -55,6 +58,23 @@ let workspaceOptions = [];
 let workspaceRoots = [];
 let workspaceRootMetadata = [];
 function buildCodexRuntimeDescriptor(input) {
+    const commands = [
+        {
+            id: 'runtime-status',
+            label: 'Runtime status',
+            description: 'Open Codex runtime details.',
+            primitive: 'runtime.status',
+            aliases: ['status'],
+            category: 'details',
+            placements: ['composer_slash', 'command_palette'],
+            availability: ['always'],
+            dispatch: { kind: 'open_details', target: 'status' },
+        },
+        {
+            ...RUNTIME_NEW_SESSION_ACTION,
+            primitive: 'session.new',
+        },
+    ];
     const descriptor = buildFirstPartyCodingRuntimeDescriptor({
         clientType: 'codex',
         models: input.models,
@@ -64,6 +84,7 @@ function buildCodexRuntimeDescriptor(input) {
         permissionModes: input.permissionModes,
         defaultPermissionMode: input.defaultPermissionMode,
         streamingTextMode: 'snapshot',
+        commands,
         actions: [
             RUNTIME_STOP_ACTION,
             RUNTIME_STOP_AND_DROP_ACTION,
@@ -244,10 +265,12 @@ export async function main() {
     initRTDBAuth(client);
     let agentId;
     let ownerId = null;
+    let ownerName = null;
     try {
         const ctx = await client.getAgentMe();
         agentId = ctx.agentId;
         ownerId = ctx.ownerId;
+        ownerName = ctx.ownerName;
         console.error(`[canon-codex] Connected as ${ctx.displayName || agentId}`);
     }
     catch {
@@ -297,6 +320,8 @@ export async function main() {
     const pendingSessionCreations = new Map();
     const conversationCache = new Map();
     const knownConversationIds = new Set();
+    const promptedGroupContextConversationIds = new Set();
+    const pendingMembershipChanges = new Map();
     let lastKnownConversationRefreshAt = 0;
     const { getConversationMeta } = createConversationMetadataLoader({
         client,
@@ -317,6 +342,45 @@ export async function main() {
         }
         lastKnownConversationRefreshAt = Date.now();
     }
+    function handleConversationUpdated(payload) {
+        const rawMemberIds = payload.changes.memberIds;
+        if (!Array.isArray(rawMemberIds))
+            return;
+        const memberIds = rawMemberIds.filter((id) => typeof id === 'string');
+        const cached = conversationCache.get(payload.conversationId);
+        const membershipChange = payload.membershipChange
+            ?? (cached ? diffCanonMemberIds(cached.memberIds, memberIds) : null);
+        if (cached) {
+            conversationCache.set(payload.conversationId, {
+                ...cached,
+                memberIds,
+            });
+        }
+        if (membershipChange) {
+            pendingMembershipChanges.set(payload.conversationId, membershipChange);
+        }
+        if (!memberIds.includes(agentId)) {
+            knownConversationIds.delete(payload.conversationId);
+            conversationCache.delete(payload.conversationId);
+        }
+    }
+    function getGroupContextMode(conversationId, conversation) {
+        if (conversation?.type !== 'group')
+            return undefined;
+        if (pendingMembershipChanges.has(conversationId))
+            return 'membership_change';
+        if (!promptedGroupContextConversationIds.has(conversationId))
+            return 'initial';
+        return undefined;
+    }
+    function markGroupContextModeUsed(conversationId, mode) {
+        if (!mode)
+            return;
+        promptedGroupContextConversationIds.add(conversationId);
+        if (mode === 'membership_change') {
+            pendingMembershipChanges.delete(conversationId);
+        }
+    }
     async function loadSenderRuntimeState(conversationId, senderId) {
         try {
             return normalizeRuntimeTurnState(await rtdbRead(`/turn-state/${conversationId}/${senderId}`));
@@ -336,9 +400,15 @@ export async function main() {
             agentId,
             conversation,
             page,
+            activeSelfContextId: input.activeSelfContextId,
+            selfContexts: input.selfContexts,
             message: input.message,
             senderName: input.senderName,
             isOwner: input.isOwner,
+            ownerId,
+            ownerName,
+            membershipChange: pendingMembershipChanges.get(input.conversationId) ?? null,
+            groupContextMode: getGroupContextMode(input.conversationId, conversation),
         });
     }
     function writeState(session) {
@@ -604,14 +674,13 @@ export async function main() {
             message: input.message,
             senderName: input.senderName,
             isOwner: input.isOwner,
+            activeSelfContextId: input.activeSelfContextId,
+            selfContexts: input.selfContexts,
             hydratedPage: input.hydratedPage,
         });
         const behavior = input.behavior ?? hydrated.behavior;
-        const selfContexts = hydrated.hydratedFromPage
-            ? hydrated.selfContexts
-            : Array.isArray(input.selfContexts)
-                ? input.selfContexts
-                : hydrated.selfContexts;
+        const activeSelfContextId = hydrated.activeSelfContextId;
+        const selfContexts = hydrated.selfContexts;
         const participantContext = hydrated.participantContext;
         const autoReply = decideAutoReply(participantContext, behavior);
         if (!autoReply.allow) {
@@ -619,6 +688,7 @@ export async function main() {
             return;
         }
         console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Message from ${input.senderName}: "${content.slice(0, 80)}" (${autoReply.reason})`);
+        markGroupContextModeUsed(input.conversationId, participantContext.groupContextMode);
         let session;
         try {
             session = await getOrCreateSession(input.conversationId);
@@ -628,7 +698,7 @@ export async function main() {
             const userMessage = error instanceof ExecutionEnvironmentError ? error.userMessage : message;
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to create session: ${message}`);
             await client.sendMessage(input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
-                ...(selfContexts[0]?.id ? { selfContextId: selfContexts[0].id } : {}),
+                ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                 metadata: {
                     turnSemantics: 'turn_complete',
                     turnComplete: true,
@@ -638,7 +708,7 @@ export async function main() {
             return;
         }
         const turnMetadata = normalizeTurnMetadata(input.message.metadata);
-        session.activeSelfContextId = selfContexts[0]?.id ?? null;
+        session.activeSelfContextId = activeSelfContextId;
         const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
         const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
         const prompt = buildCanonPrompt({
@@ -1000,6 +1070,7 @@ export async function main() {
                     senderName: message.senderName || message.senderId,
                     isOwner: message.isOwner ?? (ownerId != null && message.senderId === ownerId),
                     behavior: payload.behavior,
+                    activeSelfContextId: payload.activeSelfContextId,
                     selfContexts: payload.selfContexts,
                 });
                 if (message.id) {
@@ -1010,6 +1081,9 @@ export async function main() {
                     });
                 }
             },
+            onConversationUpdated: (payload) => {
+                handleConversationUpdated(payload);
+            },
             onConnected: () => {
                 streamConnected = true;
                 void publishRuntimeHeartbeat();
@@ -1104,7 +1178,7 @@ export async function main() {
                 await enqueueInboundMessage({
                     conversationId: conversation.id,
                     message: latestMessage,
-                    senderName: latestMessage.senderId,
+                    senderName: latestMessage.senderName || latestMessage.senderId,
                     isOwner: ownerId != null && latestMessage.senderId === ownerId,
                     behavior: latestPage.behavior,
                     selfContexts: latestPage.selfContexts,

package/dist/inbound-policy.d.ts

@@ -1,4 +1,4 @@
-import { type CanonConversation, type ResolvedAgentBehaviorPolicy } from '@canonmsg/core';
+import { type CanonGroupContext, type CanonGroupContextMode, type CanonConversation, type ResolvedAgentBehaviorPolicy } from '@canonmsg/core';
 export interface InboundParticipantContext {
     conversationType: CanonConversation['type'] | 'unknown';
     memberCount: number | null;
@@ -6,6 +6,8 @@ export interface InboundParticipantContext {
     senderName: string;
     isOwner: boolean;
     mentionedAgent: boolean;
+    groupContext?: CanonGroupContext;
+    groupContextMode?: CanonGroupContextMode;
     recentSenderTypes: Array<'human' | 'ai_agent'>;
     recentHumanCount: number;
     recentAgentCount: number;

package/dist/inbound-policy.js

@@ -1,4 +1,4 @@
-import { evaluateParticipationPolicy, resolveAgentBehaviorPolicy, } from '@canonmsg/core';
+import { buildCompactGroupContextLines, evaluateParticipationPolicy, resolveAgentBehaviorPolicy, } from '@canonmsg/core';
 function formatRecentSenders(senderTypes) {
     if (senderTypes.length === 0)
         return 'none';
@@ -18,6 +18,9 @@ export function buildInboundContextLines(context) {
         `Latest sender name: ${context.senderName}`,
         `Latest sender type: ${context.senderType}`,
         `Conversation type: ${conversationTypeLabel}`,
+        ...(context.groupContext && context.groupContextMode
+            ? buildCompactGroupContextLines(context.groupContext, context.groupContextMode)
+            : []),
         `Directly addressed to this agent: ${context.mentionedAgent ? 'yes' : 'no'}`,
         `Recent sender pattern: ${formatRecentSenders(context.recentSenderTypes)}`,
         `Recent human messages: ${context.recentHumanCount}`,

package/dist/register.js

@@ -97,7 +97,9 @@ export async function main() {
             console.log(`Approved! Agent: ${result.agentName} (${result.agentId})`);
             console.log(`Saved as profile "${profileName}" in ~/.canon/agents.json`);
             console.log('Start it with: CANON_AGENT=' + profileName + ' canon-codex --cwd /path/to/project');
-            console.log('Keep that terminal open. Closing it takes this local agent offline.');
+            console.log('Keep that terminal open while you want Canon to reach the agent.');
+            console.log('Closing it, logging out, rebooting, or sleeping long enough to stop the process takes this local agent offline until you revive it.');
+            console.log('Docs: https://canonmail.com/agents/integrations');
             break;
         }
         case 'rejected':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -29,8 +29,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@canonmsg/agent-sdk": "^1.2.0",
-    "@canonmsg/core": "^0.16.0"
+    "@canonmsg/agent-sdk": "^1.3.1",
+    "@canonmsg/core": "^0.17.2"
   },
   "engines": {
     "node": ">=18.0.0"