@canonmsg/codex-plugin 0.6.5 → 0.7.0

package/README.md

@@ -37,7 +37,7 @@ You do not need a git repo for host mode. The plugin passes `--skip-git-repo-che
 
 ## Current limitation
 
-The stable `codex exec --json` surface exposes completed assistant messages and tool activity, but not token-by-token text deltas. v1 therefore reports live status and publishes the final reply when the turn completes, instead of true token streaming.
+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 message snapshots without claiming true token streaming.
 
 ## Working directory
 
@@ -45,12 +45,22 @@ The stable `codex exec --json` surface exposes completed assistant messages and
 canon-codex --cwd /path/to/project
 ```
 
+Advertise multiple project choices to the Canon app:
+
+```bash
+canon-codex --cwd ~/dev --workspace ~/dev/canon --workspace ~/dev/yumyumv2
+```
+
+`--cwd` is the default workspace. Each `--workspace` value appears as a selectable workspace during session creation. Worktree mode creates a per-conversation git worktree under `~/.canon/conversation-worktrees`; shared-workspace mode runs directly in the selected directory.
+
 Useful flags:
 
 ```bash
 canon-codex --cwd /path/to/project --model gpt-5.4 --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.
+
 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`.
 
 Local smoke test:

package/dist/host-runtime.d.ts

@@ -37,6 +37,12 @@ interface HostWorkspaceResolverOption {
     id: string;
     cwd: string;
 }
+export declare const HOST_ADMISSION_ACTION_CAPABILITIES: Readonly<{
+    canStartDirectConversation: false;
+    canSendContactRequest: false;
+    canApprovePendingContactRequests: false;
+    canRejectPendingContactRequests: false;
+}>;
 export declare function buildCanonHostPrompt(input: {
     hostLabel: string;
     content: string;
@@ -81,12 +87,33 @@ export declare function buildHydratedInboundContext(input: {
     hydratedFromPage: boolean;
 };
 export declare function publishHostAgentRuntime(agentId: string, clientType: AgentClientType, runtime: AgentRuntime): Promise<void>;
-export declare function readHostSessionConfig<TExtra extends string = never>(raw: unknown, extraStringFields?: readonly TExtra[]): (SessionWorkspaceConfig & Partial<Record<TExtra, string>>) | null;
+export declare function publishHostSessionSnapshots(input: {
+    conversationIds: string[];
+    agentId: string;
+    clientType: AgentClientType;
+    runtime: AgentRuntime;
+    workspaceOptions: HostWorkspaceResolverOption[];
+    defaultCwd: string;
+    liveSessionConfigByConversation?: ReadonlyMap<string, {
+        model?: string;
+        permissionMode?: string;
+        effort?: string;
+        runtimeControlValues?: Record<string, string>;
+        workspaceId?: string;
+        executionMode?: SessionWorkspaceConfig['executionMode'];
+        executionBranch?: string | null;
+    }>;
+}): Promise<void>;
+export declare function readHostSessionConfig<TExtra extends string = never>(raw: unknown, extraStringFields?: readonly TExtra[]): (SessionWorkspaceConfig & Partial<Record<TExtra, string>> & {
+    runtimeControlValues?: Record<string, string>;
+}) | null;
 export declare function loadHostSessionConfig<TExtra extends string = never>(input: {
     conversationId: string;
     agentId: string;
     extraStringFields?: readonly TExtra[];
-}): Promise<(SessionWorkspaceConfig & Partial<Record<TExtra, string>>) | null>;
+}): Promise<(SessionWorkspaceConfig & Partial<Record<TExtra, string>> & {
+    runtimeControlValues?: Record<string, string>;
+}) | null>;
 export declare function resolveHostWorkspaceCwd(input: {
     workspaceOptions: HostWorkspaceResolverOption[];
     config: {

package/dist/host-runtime.js

@@ -11,7 +11,13 @@
  * behavior here, update that copy too and adjust the shared golden
  * fixture test (`packages/codex-plugin/src/host-runtime.test.ts`).
  */
-import { buildBehaviorPolicyLines, buildParticipationHistorySnapshot, buildWorkSessionsPromptLines, mergeWorkSessionContexts, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, rtdbRead, rtdbWrite, } from '@canonmsg/core';
+import { buildAgentSessionSnapshot, buildConversationWorktreeSpec, buildBehaviorPolicyLines, buildParticipationHistorySnapshot, buildWorkSessionsPromptLines, mergeWorkSessionContexts, normalizeOptionalString, patchAgentSessionSnapshot, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, rtdbRead, rtdbWrite, } from '@canonmsg/core';
+export const HOST_ADMISSION_ACTION_CAPABILITIES = Object.freeze({
+    canStartDirectConversation: false,
+    canSendContactRequest: false,
+    canApprovePendingContactRequests: false,
+    canRejectPendingContactRequests: false,
+});
 export function buildCanonHostPrompt(input) {
     const resolvedWorkSessions = mergeWorkSessionContexts(input.workSession, input.workSessions);
     return [
@@ -69,7 +75,21 @@ function describeContactCard(card) {
     if (card.about)
         parts.push(`about: ${card.about}`);
     const identity = `📇 Contact card: "${card.displayName}" (${parts.join(' · ')}).`;
-    const hint = `This card is informational only in host mode. Canon does not currently expose a host-side tool here for starting a new direct conversation or sending a contact request to userId ${card.userId}.`;
+    const missingCapabilities = [
+        !HOST_ADMISSION_ACTION_CAPABILITIES.canStartDirectConversation
+            ? 'start a direct conversation'
+            : null,
+        !HOST_ADMISSION_ACTION_CAPABILITIES.canSendContactRequest
+            ? 'send a contact request'
+            : null,
+        !HOST_ADMISSION_ACTION_CAPABILITIES.canApprovePendingContactRequests
+            ? 'approve pending requests'
+            : null,
+        !HOST_ADMISSION_ACTION_CAPABILITIES.canRejectPendingContactRequests
+            ? 'reject pending requests'
+            : null,
+    ].filter(Boolean).join(', ');
+    const hint = `This host can inspect the card, but Canon admission actions are missing here. Missing capabilities: ${missingCapabilities}. Use another Canon surface for userId ${card.userId}.`;
     return `${identity}\n${hint}`;
 }
 function describeAttachment(attachment, materialized) {
@@ -116,6 +136,70 @@ export async function publishHostAgentRuntime(agentId, clientType, runtime) {
         updatedAt: { '.sv': 'timestamp' },
     });
 }
+export async function publishHostSessionSnapshots(input) {
+    if (input.conversationIds.length === 0) {
+        return;
+    }
+    await Promise.all(input.conversationIds.map(async (conversationId) => {
+        const persistedConfig = await loadHostSessionConfig({
+            conversationId,
+            agentId: input.agentId,
+            extraStringFields: ['permissionMode'],
+        });
+        const liveConfig = input.liveSessionConfigByConversation?.get(conversationId) ?? null;
+        const mergedConfig = {
+            ...(persistedConfig ?? {}),
+            ...(liveConfig ?? {}),
+        };
+        const snapshot = buildAgentSessionSnapshot({
+            conversationId,
+            agentId: input.agentId,
+            runtime: {
+                ...input.runtime,
+                clientType: input.clientType,
+                hostMode: true,
+            },
+            sessionConfig: {
+                ...(mergedConfig.model ? { model: mergedConfig.model } : {}),
+                ...(mergedConfig.permissionMode ? { permissionMode: mergedConfig.permissionMode } : {}),
+                ...(mergedConfig.effort ? { effort: mergedConfig.effort } : {}),
+                ...(mergedConfig.runtimeControlValues
+                    ? { runtimeControlValues: mergedConfig.runtimeControlValues }
+                    : {}),
+                ...(mergedConfig.workspaceId ? { workspaceId: mergedConfig.workspaceId } : {}),
+                ...(mergedConfig.executionMode ? { executionMode: mergedConfig.executionMode } : {}),
+            },
+            lastHeartbeatAt: undefined,
+        });
+        let executionBranch = liveConfig?.executionBranch ?? null;
+        if (!executionBranch && snapshot.executionMode === 'worktree' && snapshot.workspaceId) {
+            const workspace = input.workspaceOptions.find((option) => option.id === snapshot.workspaceId);
+            if (workspace) {
+                executionBranch = buildConversationWorktreeSpec({
+                    agentId: input.agentId,
+                    conversationId,
+                    workspaceCwd: workspace.cwd,
+                }).branch;
+            }
+        }
+        return patchAgentSessionSnapshot(conversationId, input.agentId, {
+            clientType: input.clientType,
+            hostMode: true,
+            model: snapshot.model ?? null,
+            permissionMode: snapshot.permissionMode ?? null,
+            effort: snapshot.effort ?? null,
+            runtimeControlValues: snapshot.runtimeControlValues ?? null,
+            workspaceId: snapshot.workspaceId ?? null,
+            executionMode: snapshot.executionMode ?? null,
+            executionBranch,
+            modelOptions: snapshot.modelOptions,
+            permissionModeOptions: snapshot.permissionModeOptions,
+            workspaceOptions: snapshot.workspaceOptions,
+            availableExecutionModes: snapshot.availableExecutionModes,
+            lastHeartbeatAt: { '.sv': 'timestamp' },
+        });
+    }));
+}
 export function readHostSessionConfig(raw, extraStringFields = []) {
     const baseConfig = readSessionWorkspaceConfig(raw);
     if (!raw || typeof raw !== 'object') {
@@ -126,9 +210,16 @@ export function readHostSessionConfig(raw, extraStringFields = []) {
         const value = normalizeOptionalString(data[field]);
         return value ? [[field, value]] : [];
     }));
+    const runtimeControlValues = Object.fromEntries(Object.entries(data.runtimeControlValues && typeof data.runtimeControlValues === 'object'
+        ? data.runtimeControlValues
+        : {}).flatMap(([key, value]) => {
+        const normalizedValue = normalizeOptionalString(value);
+        return normalizedValue ? [[key, normalizedValue]] : [];
+    }));
     return {
         ...(baseConfig ?? {}),
         ...extraConfig,
+        ...(Object.keys(runtimeControlValues).length > 0 ? { runtimeControlValues } : {}),
     };
 }
 export async function loadHostSessionConfig(input) {

package/dist/host.js

@@ -3,8 +3,8 @@ import { setDefaultResultOrder } from 'node:dns';
 import { randomUUID } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import { getCodexImagePath, materializeMessageMedia, } from '@canonmsg/agent-sdk';
-import { buildConfiguredWorkspaceOptions, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfile, initRTDBAuth, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseLock, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, writeSessionState, writeTurnState, } from '@canonmsg/core';
-import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
+import { buildConfiguredWorkspaceOptions, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfile, initRTDBAuth, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseLock, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, writeRuntimeInfo, shouldTriggerAgentTurn, writeSessionState, writeTurnState, } from '@canonmsg/core';
+import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
 import { clearStoredThreadId, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
@@ -23,6 +23,61 @@ const CODEX_RUNTIME_CAPABILITIES = {
 };
 let workingDir = process.cwd();
 let workspaceOptions = [];
+function buildCodexRuntimeDescriptor(input) {
+    return {
+        coreControls: [
+            {
+                id: 'model',
+                label: 'Model',
+                options: input.models,
+                defaultValue: input.models[0]?.value ?? null,
+                availability: 'setup_and_live',
+                liveBehavior: 'next_turn',
+                selectionPolicy: 'inherit',
+            },
+            {
+                id: 'workspace',
+                label: 'Workspace',
+                options: input.workspaces.map((workspace) => ({
+                    value: workspace.id,
+                    label: workspace.label,
+                })),
+                defaultValue: input.workspaces[0]?.id ?? null,
+                availability: 'setup',
+                liveBehavior: 'none',
+                selectionPolicy: 'inherit',
+            },
+            {
+                id: 'executionMode',
+                label: 'Execution mode',
+                options: input.executionModes.map((mode) => ({
+                    value: mode,
+                    label: mode === 'worktree' ? 'Isolated worktree' : 'Use shared workspace',
+                    description: mode === 'worktree'
+                        ? 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected workspace is a git repo.'
+                        : 'Runs directly in the selected workspace. Canon records usage, but does not create a separate checkout.',
+                })),
+                defaultValue: null,
+                availability: 'setup',
+                liveBehavior: 'none',
+                selectionPolicy: 'required_explicit',
+            },
+        ],
+        runtimeControls: [
+            {
+                id: 'permissionMode',
+                label: 'Execution policy',
+                options: input.permissionModes,
+                defaultValue: input.defaultPermissionMode ?? null,
+                availability: 'setup',
+                liveBehavior: 'none',
+                selectionPolicy: 'inherit',
+            },
+        ],
+        supportsInterrupt: true,
+        streamingTextMode: 'snapshot',
+    };
+}
 function normalizeRuntimeTurnState(value) {
     const normalizedTurn = normalizeTurnState(value);
     if (normalizedTurn) {
@@ -62,6 +117,14 @@ function resolveWorkspaceCwd(config) {
         defaultCwd: workingDir,
     });
 }
+function resolveExecutionFallbackReason(environment) {
+    if (!environment?.reason || environment.mode !== 'locked') {
+        return null;
+    }
+    return environment.reason === 'Sharing the base workspace (locked mode)'
+        ? null
+        : environment.reason;
+}
 function buildCanonPrompt(input) {
     return buildCanonHostPrompt({
         hostLabel: 'Codex',
@@ -138,10 +201,27 @@ export async function main() {
     const sessions = new Map();
     const pendingSessionCreations = new Map();
     const conversationCache = new Map();
+    const knownConversationIds = new Set();
+    let lastKnownConversationRefreshAt = 0;
     const { getConversationMeta } = createConversationMetadataLoader({
         client,
         conversationCache,
     });
+    function resolveWorkspaceIdForBaseCwd(baseCwd) {
+        return workspaceOptions.find((option) => option.cwd === baseCwd)?.id;
+    }
+    async function refreshKnownConversationIds(force = false) {
+        if (!force && Date.now() - lastKnownConversationRefreshAt < HEARTBEAT_MS) {
+            return;
+        }
+        const conversations = await client.getConversations();
+        knownConversationIds.clear();
+        for (const conversation of conversations) {
+            knownConversationIds.add(conversation.id);
+            conversationCache.set(conversation.id, conversation);
+        }
+        lastKnownConversationRefreshAt = Date.now();
+    }
     async function loadSenderRuntimeState(conversationId, senderId) {
         try {
             const [turnState, sessionState] = await Promise.all([
@@ -177,6 +257,7 @@ export async function main() {
             cwd: session.cwd,
             executionMode: session.environment.mode,
             ...(session.environment.branch ? { executionBranch: session.environment.branch } : {}),
+            ...(session.environment.worktreePath ? { worktreePath: session.environment.worktreePath } : {}),
             hostMode: true,
             clientType: 'codex',
             state: session.state.state,
@@ -236,6 +317,7 @@ export async function main() {
         }
     }
     async function getOrCreateSession(conversationId) {
+        knownConversationIds.add(conversationId);
         const existing = sessions.get(conversationId);
         if (existing && !existing.closed) {
             existing.lastActivity = Date.now();
@@ -335,6 +417,7 @@ export async function main() {
         void runNextTurn(session);
     }
     async function enqueueInboundMessage(input) {
+        knownConversationIds.add(input.conversationId);
         let materialized = [];
         if (input.message.id) {
             try {
@@ -551,13 +634,88 @@ export async function main() {
         ...(codexPermissionEnvelope.defaultPermissionMode
             ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
             : {}),
+        runtimeDescriptor: buildCodexRuntimeDescriptor({
+            models: [],
+            workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            executionModes: hostAvailableExecutionModes,
+            permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
+            defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
+        }),
     };
     const publishRuntimeHeartbeat = async () => {
         if (!streamConnected)
             return;
+        await refreshKnownConversationIds().catch((error) => {
+            console.error('[canon-codex] Failed to refresh known conversations:', error);
+        });
         await publishAgentRuntime(agentId, runtimeDescriptor).catch((error) => {
             console.error('[canon-codex] Failed to publish agent runtime:', error);
         });
+        await publishHostSessionSnapshots({
+            conversationIds: Array.from(knownConversationIds),
+            agentId,
+            clientType: 'codex',
+            runtime: runtimeDescriptor,
+            workspaceOptions,
+            defaultCwd: workingDir,
+            liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
+                const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
+                return [
+                    session.conversationId,
+                    {
+                        ...(session.state.model ? { model: session.state.model } : {}),
+                        ...(workspaceId ? { workspaceId } : {}),
+                        executionMode: session.environment.mode,
+                        executionBranch: session.environment.branch ?? null,
+                    },
+                ];
+            })),
+        }).catch((error) => {
+            console.error('[canon-codex] Failed to publish session snapshots:', error);
+        });
+        await Promise.all(Array.from(knownConversationIds).map(async (conversationId) => {
+            const session = sessions.get(conversationId);
+            const workspaceId = session
+                ? resolveWorkspaceIdForBaseCwd(session.environment.baseCwd)
+                : runtimeDescriptor.defaultWorkspaceId;
+            const workspace = workspaceOptions.find((option) => option.id === workspaceId) ?? null;
+            const payload = {
+                descriptor: runtimeDescriptor.runtimeDescriptor ?? buildCodexRuntimeDescriptor({
+                    models: runtimeDescriptor.availableModels ?? [],
+                    workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                    executionModes: hostAvailableExecutionModes,
+                    permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
+                    defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
+                }),
+                surfaceMode: 'host',
+                statusItems: [
+                    {
+                        id: 'transport',
+                        label: 'Transport',
+                        value: 'exec --json',
+                    },
+                    {
+                        id: 'streaming',
+                        label: 'Live output',
+                        value: 'Thinking, tools, and completed-message previews',
+                    },
+                ],
+                execution: {
+                    resolvedWorkspaceLabel: workspace?.label ?? workspaceId ?? null,
+                    resolvedCwd: session?.cwd ?? workspace?.cwd ?? workingDir,
+                    executionMode: session?.environment.mode ?? null,
+                    executionBranch: session?.environment.branch ?? null,
+                    worktreePath: session?.environment.worktreePath ?? null,
+                    fallbackReason: resolveExecutionFallbackReason(session?.environment),
+                },
+                notes: [
+                    'This Codex host uses the current exec --json transport, so Canon can show thinking, tool activity, and completed assistant-message previews, but not token-by-token text deltas.',
+                ],
+            };
+            await writeRuntimeInfo(conversationId, agentId, payload);
+        })).catch((error) => {
+            console.error('[canon-codex] Failed to publish runtime info:', error);
+        });
     };
     const stream = new CanonStream({
         apiKey,
@@ -599,6 +757,13 @@ export async function main() {
             ...(codexPermissionEnvelope.defaultPermissionMode
                 ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
                 : {}),
+            runtimeDescriptor: buildCodexRuntimeDescriptor({
+                models: [],
+                workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                executionModes: hostAvailableExecutionModes,
+                permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
+                defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
+            }),
         };
     }
     catch {
@@ -610,11 +775,21 @@ export async function main() {
             ...(codexPermissionEnvelope.defaultPermissionMode
                 ? { defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode }
                 : {}),
+            runtimeDescriptor: buildCodexRuntimeDescriptor({
+                models: [],
+                workspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                executionModes: hostAvailableExecutionModes,
+                permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
+                defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
+            }),
         };
     }
     try {
         const conversations = await client.getConversations();
+        lastKnownConversationRefreshAt = Date.now();
         for (const conversation of conversations) {
+            knownConversationIds.add(conversation.id);
+            conversationCache.set(conversation.id, conversation);
             clearStreaming(conversation.id);
             clearSessionState(conversation.id, agentId).catch(() => { });
             clearTurnState(conversation.id, agentId).catch(() => { });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "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": "^0.8.2",
-    "@canonmsg/core": "^0.7.4"
+    "@canonmsg/agent-sdk": "^0.9.0",
+    "@canonmsg/core": "^0.8.0"
   },
   "engines": {
     "node": ">=18.0.0"