@canonmsg/codex-plugin 0.14.1 → 0.18.1

package/dist/host.js

@@ -4,8 +4,8 @@ import { randomUUID } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
-import { getCodexImagePath, materializeMessageMedia, materializeReplyContextMedia, } from '@canonmsg/agent-sdk';
-import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildPlanApprovalRequest, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, 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, loadRuntimeSessionState, markLocalRuntimeStopped, normalizeTurnMetadata, parseRuntimeCardV1, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, CanonApiError, sendMessageWithRetry, sendMessageWithRetryChunked, shouldTriggerAgentTurn, saveRuntimeSessionState, buildBoundedTurnTrail, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCanonTurnBriefPrompt, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { getCodexImagePath, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, } from '@canonmsg/agent-sdk';
+import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildPlanApprovalRequest, resolveQuestionAllowOther, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, 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, loadRuntimeSessionState, markLocalRuntimeStopped, normalizeTurnMetadata, parseRuntimeCardV1, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, CanonApiError, sendMessageWithRetry, sendMessageWithRetryChunked, shouldTriggerAgentTurn, saveRuntimeSessionState, buildBoundedTurnTrail, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCanonTurnBriefPrompt, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
 import { CodexAppServerAdapter } from './app-server-adapter.js';
@@ -15,7 +15,10 @@ import { deriveCodexPermissionEnvelope, mapCanonPermissionToCodex, } from './per
 import { detectCodexCliVersion } from './codex-cli-version.js';
 import { buildCodexModelGuardMessage, formatCodexTurnFailure, isRecoverableCodexThreadError, } from './error-format.js';
 import { startCodexStreamInBackground } from './host-lifecycle.js';
+import { createCodexControlPoller } from './control-channel.js';
+import { buildOutboxContextLine, ensureOutboxDir, flushOutbox, resolveOutboxDir, } from './outbox.js';
 import { runCli } from './cli-entry.js';
+import { collectMissedInboundMessages, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from './startup-recovery.js';
 import { beginCommandBlock, claimCommandBlock, createCommandBlockTracker, } from './turn-activity.js';
 const HELP = `canon-codex — run a local Codex agent host for Canon
 
@@ -54,9 +57,6 @@ const MAX_SESSIONS = 12;
 const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 const HEARTBEAT_MS = 30_000;
 const IDLE_CHECK_MS = 60_000;
-const CONTROL_POLL_MS = 2_000;
-const IDLE_CONTROL_POLL_MS = 10_000;
-const CONTROL_POLL_JITTER_MS = 1_000;
 const CODEX_RUNTIME_CAPABILITIES = {
     ...DEFAULT_RUNTIME_CAPABILITIES,
     supportsInterrupt: true,
@@ -64,14 +64,18 @@ const CODEX_RUNTIME_CAPABILITIES = {
     supportsQueue: true,
     supportsNonFinalPermanentMessages: false,
 };
-function controlPollDelayMs(hasActiveWork) {
-    const base = hasActiveWork ? CONTROL_POLL_MS : IDLE_CONTROL_POLL_MS;
-    return base + Math.floor(Math.random() * CONTROL_POLL_JITTER_MS);
-}
 let workingDir = process.cwd();
 let workspaceOptions = [];
 let workspaceRoots = [];
 let workspaceRootMetadata = [];
+/** GPT reasoning-effort levels, applied next turn via model_reasoning_effort. */
+const CODEX_EFFORT_OPTIONS = [
+    { value: 'minimal', label: 'Minimal' },
+    { value: 'low', label: 'Low' },
+    { value: 'medium', label: 'Medium' },
+    { value: 'high', label: 'High' },
+];
+const CODEX_EFFORT_VALUES = new Set(CODEX_EFFORT_OPTIONS.map((option) => option.value));
 function buildCodexRuntimeDescriptor(input) {
     const commands = [
         {
@@ -100,6 +104,11 @@ function buildCodexRuntimeDescriptor(input) {
         executionModes: input.executionModes,
         permissionModes: input.permissionModes,
         defaultPermissionMode: input.defaultPermissionMode,
+        permissionModeLabel: 'Execution policy',
+        modelLiveBehavior: 'next_turn',
+        effortOptions: [...CODEX_EFFORT_OPTIONS],
+        defaultEffort: 'medium',
+        effortLiveBehavior: 'next_turn',
         presentation: input.presentation,
         streamingTextMode: 'snapshot',
         ...(input.supportsPlanMode
@@ -172,7 +181,7 @@ async function loadSessionConfig(conversationId, agentId) {
     return loadHostSessionConfig({
         conversationId,
         agentId,
-        extraStringFields: ['permissionMode'],
+        extraStringFields: ['permissionMode', 'effort'],
     });
 }
 function resolveSessionExecutionMode(config) {
@@ -247,6 +256,7 @@ function buildCanonPrompt(input) {
         activeSelfContextId: input.activeSelfContextId,
         provenance: input.provenance,
         replyContext: input.replyContext,
+        sessionContextLines: input.sessionContextLines,
         message: input.message,
     }));
 }
@@ -339,15 +349,21 @@ function mapCodexQuestions(value) {
             const description = typeof optionRecord.description === 'string' && optionRecord.description.trim()
                 ? optionRecord.description.trim().slice(0, 300)
                 : undefined;
-            return [{ label, value: label, ...(description ? { description } : {}) }];
+            const preview = typeof optionRecord.preview === 'string' && optionRecord.preview.trim()
+                ? optionRecord.preview.trim().slice(0, 4000)
+                : undefined;
+            return [{ label, value: label, ...(description ? { description } : {}), ...(preview ? { preview } : {}) }];
         });
         return [{
                 id,
                 question,
                 ...(header ? { header } : {}),
                 ...(choices.length > 0 ? { choices } : {}),
-                ...(choices.length > 0 && record.allowOther !== false ? { allowOther: true } : {}),
-                ...(record.allowOther === true || record.isOther === true ? { allowOther: true } : {}),
+                // Shared automatic-"Other" convention (Mac-app parity): on for choice
+                // questions unless the agent explicitly opts out.
+                ...(resolveQuestionAllowOther(choices.length > 0, record.allowOther ?? record.isOther)
+                    ? { allowOther: true }
+                    : {}),
                 ...(record.isSecret === true ? { isSecret: true } : {}),
                 ...(record.multiSelect === true ? { multiSelect: true } : {}),
             }];
@@ -413,7 +429,7 @@ export async function main() {
     const { apiKey, agentId: profileAgentId, agentName: profileAgentName, profile, baseUrl, lockHandle, } = resolveCanonAgent({ logPrefix: '[canon-codex]', expectedClientType: 'codex' });
     console.error(`[canon-codex] Starting${profile ? ` (profile: ${profile})` : ''} in ${workingDir}`);
     const client = new CanonClient(apiKey, baseUrl);
-    initRTDBAuth(client);
+    const rtdb = initRTDBAuth(client);
     const typingSignals = createTypingStatusPublisher({
         setTyping: (conversationId, typing, status) => status
             ? client.setTyping(conversationId, typing, status)
@@ -585,6 +601,7 @@ export async function main() {
             hostMode: true,
             clientType: 'codex',
             isActive: true,
+            ...(session.state.contextUsage ? { contextUsage: session.state.contextUsage } : {}),
         }).catch(() => { });
     }
     function writeTurn(session) {
@@ -810,12 +827,16 @@ export async function main() {
                     throw new ExecutionEnvironmentError(modelGuard, modelGuard);
                 }
                 const storedThreadId = loadStoredThreadId(runtimeId, agentId, conversationId, environment.baseCwd, environment.mode, policy.fingerprint);
+                const initialEffort = config?.effort && CODEX_EFFORT_VALUES.has(config.effort)
+                    ? config.effort
+                    : null;
                 const adapter = useAppServer
                     ? new CodexAppServerAdapter({
                         cwd: sessionCwd,
                         threadId: storedThreadId,
                         codexBin,
                         model: policy.model ?? null,
+                        reasoningEffort: initialEffort,
                         sandbox: policy.sandbox,
                         approvalPolicy: policy.approvalPolicy,
                         addDirs: args['add-dir'] ?? [],
@@ -828,6 +849,7 @@ export async function main() {
                         threadId: storedThreadId,
                         codexBin,
                         model: policy.model ?? null,
+                        reasoningEffort: initialEffort,
                         sandbox: policy.sandbox,
                         approvalPolicy: policy.approvalPolicy,
                         codexProfile: typeof args['codex-profile'] === 'string' ? args['codex-profile'] : null,
@@ -864,10 +886,8 @@ export async function main() {
                     turnCommandBlocks: createCommandBlockTracker(),
                 };
                 sessions.set(conversationId, session);
-                await Promise.all([
-                    baselineControlSignal(conversationId),
-                    baselineSessionControl(conversationId),
-                ]);
+                await controlPoller.baseline([conversationId]);
+                ensureOutboxDir(sessionCwd).catch((error) => console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Failed to create media outbox:`, error));
                 console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Environment → ${environment.mode} (${sessionCwd})`);
                 writeState(session);
                 writeTurn(session);
@@ -1134,6 +1154,7 @@ export async function main() {
                     method: request.method,
                 },
                 details: mappedApproval.details,
+                ...(mappedApproval.diff ? { diff: mappedApproval.diff } : {}),
                 responseUserId: ownerId ?? undefined,
                 allowSessionRule: true,
                 expiresAt,
@@ -1170,7 +1191,9 @@ export async function main() {
             const decision = input.message.metadata.decision;
             const prompt = decision === 'approve'
                 ? 'The plan was approved. Implement the approved plan now.'
-                : `Please revise the plan.${feedback ? `\n\nRevision feedback:\n${feedback}` : ''}`;
+                : decision === 'reject'
+                    ? `The plan was declined — keep planning and wait for guidance before implementing.${feedback ? `\n\nNotes:\n${feedback}` : ''}`
+                    : `Please revise the plan.${feedback ? `\n\nRevision feedback:\n${feedback}` : ''}`;
             enqueuePrompt(session, prompt, 'queue', false, input.message.id, false, [], [], decision !== 'approve');
             return;
         }
@@ -1264,6 +1287,7 @@ export async function main() {
             activeSelfContextId,
             provenance: hydrated.provenance,
             replyContext,
+            sessionContextLines: [buildOutboxContextLine(session.cwd)],
             message: input.message,
         });
         if (session.running && deliveryIntent === 'interrupt') {
@@ -1276,6 +1300,45 @@ export async function main() {
         }
         enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode);
     }
+    /**
+     * Turn-end media outbox flush (see ./outbox.ts for the convention). Never
+     * throws: upload failures are logged and the files stay in place for a
+     * later turn.
+     */
+    async function flushSessionOutbox(session) {
+        const logPrefix = `[canon-codex] [${session.conversationId.slice(0, 8)}]`;
+        try {
+            const result = await flushOutbox({
+                outboxDir: resolveOutboxDir(session.cwd),
+                send: (file) => sendMediaFileMessage(client, session.conversationId, file.path, '', {
+                    ...(session.activeSelfContextId ? { selfContextId: session.activeSelfContextId } : {}),
+                    metadata: {
+                        ...(session.currentTurnId ? { turnId: session.currentTurnId } : {}),
+                        // Media is permanent conversation content (promoted like a final
+                        // reply) but must never re-trigger other agents — the host's own
+                        // final text message stays the only turn-complete trigger.
+                        turnSemantics: 'turn_complete',
+                        replyBehavior: 'suppress_auto_reply',
+                    },
+                }),
+            });
+            for (const entry of result.sent) {
+                console.error(`${logPrefix} Sent outbox file ${entry.file.fileName} (${entry.messageId})`
+                    + (entry.removeFailed ? ' — removal failed; it may resend next turn' : ''));
+            }
+            for (const failure of result.failed) {
+                console.error(`${logPrefix} Outbox upload failed for ${failure.file.fileName}; left in place: ${failure.error}`);
+            }
+            for (const skipped of result.skipped) {
+                if (skipped.reason === 'too-large' || skipped.reason === 'file-cap') {
+                    console.error(`${logPrefix} Outbox skipped ${skipped.fileName} (${skipped.reason}); left in place`);
+                }
+            }
+        }
+        catch (error) {
+            console.error(`${logPrefix} Outbox flush failed:`, error instanceof Error ? error.message : error);
+        }
+    }
     async function runNextTurn(session) {
         if (session.running || session.closed)
             return;
@@ -1384,6 +1447,15 @@ export async function main() {
                     return;
                 }
                 if (event.type === 'turn.completed') {
+                    // Codex reports per-turn token usage but no context window, so the
+                    // meter publishes tokens only (input + cached covers the full
+                    // prompt context of the completed turn).
+                    const totalTokens = (event.usage?.input_tokens ?? 0)
+                        + (event.usage?.cached_input_tokens ?? 0)
+                        + (event.usage?.output_tokens ?? 0);
+                    if (totalTokens > 0) {
+                        session.state.contextUsage = { totalTokens };
+                    }
                     writeState(session);
                 }
             };
@@ -1411,6 +1483,11 @@ export async function main() {
             if (result.threadId && !session.resetRequested) {
                 saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, result.threadId, session.environment.mode, session.policyFingerprint);
             }
+            // Turn-end outbox flush — media lands before the final text reply.
+            // Interrupted turns keep their files for the next completed turn.
+            if (!result.interrupted) {
+                await flushSessionOutbox(session);
+            }
             if (!result.interrupted && result.finalMessage && nextTurn.planMode) {
                 const planApproval = buildPlanApprovalRequest(session.currentTurnId ?? randomUUID(), 'Plan ready for review.', {
                     responseUserId: ownerId ?? undefined,
@@ -1526,9 +1603,6 @@ export async function main() {
             }
         }
     }
-    let controlStopped = false;
-    const lastSeenControl = new Map();
-    const lastSeenSignal = new Map();
     let streamConnected = false;
     const hostAvailableExecutionModes = [
         ...EXECUTION_ENVIRONMENT_MODES,
@@ -1562,28 +1636,87 @@ export async function main() {
             supportsRichCards: useAppServer,
         }),
     };
-    async function baselineControlSignal(conversationId) {
-        if (lastSeenSignal.has(conversationId))
-            return;
-        const raw = await rtdbRead(`/control/${conversationId}/${agentId}/signal`).catch(() => null);
-        if (!raw || typeof raw !== 'object')
+    function applySessionControl(conversationId, control) {
+        const session = sessions.get(conversationId);
+        if (!session || session.closed)
             return;
-        const timestamp = Number(raw.updatedAt ?? 0);
-        if (timestamp > 0) {
-            lastSeenSignal.set(conversationId, timestamp);
+        if (control.model && control.model !== session.state.model) {
+            const modelGuard = buildCodexModelGuardMessage(control.model, codexCliStatus);
+            if (modelGuard) {
+                session.state.lastError = modelGuard;
+                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${modelGuard}`);
+                writeState(session);
+                // The poller consumes the node; skip effort handling for this pass,
+                // matching the legacy loop.
+                return;
+            }
+            session.adapter.setModel(control.model);
+            session.state.model = control.model;
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Model set for next turn -> ${control.model}`);
+            writeState(session);
+        }
+        if (control.permissionMode) {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] approval mode is session-creation-only; ignoring mid-session change request (${control.permissionMode})`);
+        }
+        if (control.effort) {
+            if (CODEX_EFFORT_VALUES.has(control.effort)) {
+                session.adapter.setReasoningEffort(control.effort);
+                session.state.effort = control.effort;
+                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Reasoning effort set for next turn -> ${control.effort}`);
+                writeState(session);
+            }
+            else {
+                console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Ignoring unknown effort level (${control.effort})`);
+            }
         }
     }
-    async function baselineSessionControl(conversationId) {
-        if (lastSeenControl.has(conversationId))
+    async function handleControlSignal(event) {
+        const { conversationId, type } = event;
+        const session = sessions.get(conversationId);
+        // No live session: dedupe already advanced, but the node stays in place,
+        // matching the legacy loop.
+        if (!session || session.closed)
+            return { consume: false };
+        if (type === 'new_session') {
+            console.error(`[canon-codex] [${conversationId.slice(0, 8)}] new_session signal`);
+            await resetRuntimeSession(session);
             return;
-        const raw = await rtdbRead(`/control/${conversationId}/${agentId}/session`).catch(() => null);
-        if (!raw || typeof raw !== 'object')
+        }
+        if (!session.running && (type !== 'stop_and_drop' || session.queue.length === 0)) {
+            // Nothing to interrupt or drop — just consume the signal.
             return;
-        const timestamp = Number(raw.updatedAt ?? 0);
-        if (timestamp > 0) {
-            lastSeenControl.set(conversationId, timestamp);
         }
+        console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${type} signal`);
+        if (type === 'stop_and_drop') {
+            const droppedPrompts = session.queue.splice(0);
+            await markQueuedPromptsRejected(conversationId, droppedPrompts);
+        }
+        if (session.running) {
+            await session.adapter.interrupt();
+        }
+        session.turnState = 'interrupted';
+        writeTurn(session);
+        clearStreaming(conversationId);
+        typingSignals.clear(conversationId).catch(() => { });
     }
+    const controlPoller = createCodexControlPoller({
+        rtdb,
+        agentId,
+        conversationIds: () => sessions.keys(),
+        hasActiveWork: () => [...sessions.values()].some((session) => !session.closed
+            && (session.running || session.queue.length > 0 || session.turnState === 'waiting_input')),
+        onSessionControl: ({ conversationId, control }) => {
+            applySessionControl(conversationId, control);
+        },
+        onSignal: handleControlSignal,
+        onError: (error) => {
+            // The legacy loop ignored transient RTDB failures; keep read/consume
+            // errors quiet but surface handler failures.
+            if (error.scope !== 'handler')
+                return;
+            console.error(`[canon-codex] [${(error.conversationId ?? 'unknown').slice(0, 8)}] Control ${error.key ?? 'poll'} handler failed:`, error.error instanceof Error ? error.error.message : error.error);
+        },
+    });
     let publishRuntimeDetailsInFlight = false;
     const publishRuntimeHeartbeat = async () => {
         heartbeatLocalRuntimeEntry(runtimeId, {
@@ -1640,6 +1773,12 @@ export async function main() {
                 const payload = {
                     descriptor,
                     surfaceMode: 'host',
+                    // The exec --json transport cannot block on approvals — without a
+                    // strip-level warning a user can believe they have an approval
+                    // gate they do not have.
+                    ...(useAppServer
+                        ? {}
+                        : { warning: "Approvals can't block on this Codex CLI — update Codex to enable the app-server transport and approval gates." }),
                     statusItems: [
                         {
                             id: 'transport',
@@ -1665,6 +1804,11 @@ export async function main() {
                             value: useAppServer ? 'Enabled' : 'Limited until app-server transport',
                             ...(useAppServer ? {} : { tone: 'warning' }),
                         },
+                        {
+                            id: 'mediaOut',
+                            label: 'Media out',
+                            value: 'Turn-end outbox',
+                        },
                     ],
                     execution: {
                         resolvedWorkspaceLabel: workspace?.label ?? workspaceId ?? null,
@@ -1801,17 +1945,19 @@ export async function main() {
                 conversationId: conversation.id,
                 baseCwd: workingDir,
             })?.lastInboundMessageId;
-            const latestPage = await client.getMessagesPage(conversation.id, 25);
-            const inboundMessages = latestPage.messages
-                .filter((message) => message.senderId !== agentId)
-                .sort((a, b) => String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? '')));
-            const cursorIndex = cursor
-                ? inboundMessages.findIndex((message) => message.id === cursor)
-                : -1;
-            const messagesToRecover = cursorIndex >= 0
-                ? inboundMessages.slice(cursorIndex + 1)
-                : inboundMessages.slice(-1);
-            for (const latestMessage of messagesToRecover) {
+            const recovery = await collectMissedInboundMessages({
+                fetchPage: (before) => client.getMessagesPage(conversation.id, STARTUP_RECOVERY_PAGE_SIZE, before),
+                cursor,
+                agentId,
+            });
+            const latestPage = recovery.newestPage;
+            if (recovery.mode === 'truncated-window') {
+                console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Startup recovery cursor not found within ${STARTUP_RECOVERY_MAX_MESSAGES} messages; recovering truncated window`);
+            }
+            if (recovery.messages.length > 1) {
+                console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Recovered ${recovery.messages.length} missed messages in ${conversation.id}`);
+            }
+            for (const latestMessage of recovery.messages) {
                 const triggerDecision = shouldTriggerAgentTurn({
                     senderType: latestMessage.senderType ?? 'human',
                     metadata: latestMessage.metadata,
@@ -1846,89 +1992,7 @@ export async function main() {
     startCodexStreamInBackground(stream, (error) => {
         console.error('[canon-codex] SSE start error:', error instanceof Error ? error.message : error);
     });
-    const pollControl = async () => {
-        while (!controlStopped) {
-            const hadActiveWork = [...sessions.values()].some((session) => !session.closed
-                && (session.running || session.queue.length > 0 || session.turnState === 'waiting_input'));
-            for (const conversationId of [...sessions.keys()]) {
-                try {
-                    const controlRaw = await rtdbRead(`/control/${conversationId}/${agentId}/session`);
-                    if (controlRaw && typeof controlRaw === 'object') {
-                        const control = controlRaw;
-                        const timestamp = control.updatedAt ?? 0;
-                        if (timestamp > (lastSeenControl.get(conversationId) ?? 0)) {
-                            lastSeenControl.set(conversationId, timestamp);
-                            const session = sessions.get(conversationId);
-                            if (session && !session.closed) {
-                                if (control.model && control.model !== session.state.model) {
-                                    const modelGuard = buildCodexModelGuardMessage(control.model, codexCliStatus);
-                                    if (modelGuard) {
-                                        session.state.lastError = modelGuard;
-                                        console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${modelGuard}`);
-                                        writeState(session);
-                                        await rtdbWrite(`/control/${conversationId}/${agentId}/session`, null).catch(() => { });
-                                        continue;
-                                    }
-                                    session.adapter.setModel(control.model);
-                                    session.state.model = control.model;
-                                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] Model set for next turn -> ${control.model}`);
-                                    writeState(session);
-                                }
-                                if (control.permissionMode) {
-                                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] approval mode is session-creation-only; ignoring mid-session change request (${control.permissionMode})`);
-                                }
-                                if (control.effort) {
-                                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] effort control is not mapped yet (${control.effort})`);
-                                }
-                            }
-                            await rtdbWrite(`/control/${conversationId}/${agentId}/session`, null).catch(() => { });
-                        }
-                    }
-                    const raw = await rtdbRead(`/control/${conversationId}/${agentId}/signal`);
-                    if (!raw || typeof raw !== 'object')
-                        continue;
-                    const signal = raw;
-                    const timestamp = signal.updatedAt ?? 0;
-                    if ((signal.type !== 'interrupt' && signal.type !== 'stop_and_drop' && signal.type !== 'new_session')
-                        || timestamp <= (lastSeenSignal.get(conversationId) ?? 0)) {
-                        continue;
-                    }
-                    lastSeenSignal.set(conversationId, timestamp);
-                    const session = sessions.get(conversationId);
-                    if (!session || session.closed)
-                        continue;
-                    if (signal.type === 'new_session') {
-                        console.error(`[canon-codex] [${conversationId.slice(0, 8)}] new_session signal`);
-                        await resetRuntimeSession(session);
-                        await rtdbWrite(`/control/${conversationId}/${agentId}/signal`, null).catch(() => { });
-                        continue;
-                    }
-                    if (!session.running && (signal.type !== 'stop_and_drop' || session.queue.length === 0)) {
-                        await rtdbWrite(`/control/${conversationId}/${agentId}/signal`, null).catch(() => { });
-                        continue;
-                    }
-                    console.error(`[canon-codex] [${conversationId.slice(0, 8)}] ${signal.type} signal`);
-                    if (signal.type === 'stop_and_drop') {
-                        const droppedPrompts = session.queue.splice(0);
-                        await markQueuedPromptsRejected(conversationId, droppedPrompts);
-                    }
-                    if (session.running) {
-                        await session.adapter.interrupt();
-                    }
-                    session.turnState = 'interrupted';
-                    writeTurn(session);
-                    clearStreaming(conversationId);
-                    typingSignals.clear(conversationId).catch(() => { });
-                    await rtdbWrite(`/control/${conversationId}/${agentId}/signal`, null).catch(() => { });
-                }
-                catch {
-                    // Ignore transient RTDB failures.
-                }
-            }
-            await new Promise((resolve) => setTimeout(resolve, controlPollDelayMs(hadActiveWork)));
-        }
-    };
-    void pollControl();
+    controlPoller.start();
     const heartbeat = setInterval(() => {
         for (const session of sessions.values()) {
             writeState(session);
@@ -1952,7 +2016,7 @@ export async function main() {
     }, IDLE_CHECK_MS);
     const shutdown = async () => {
         console.error('[canon-codex] Shutting down...');
-        controlStopped = true;
+        controlPoller.stop();
         clearInterval(heartbeat);
         clearInterval(idleCheck);
         stream.stop();

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { main as hostMain } from './host.js';
 export { main as registerMain } from './register.js';
 export { main as setupMain } from './setup.js';
-export { mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
+export { extractCodexApprovalDiff, mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
 export type { CanonCodexApprovalRequest, CodexAppServerApprovalMethod, CodexApprovalDecision, CodexNativeApprovalRequest, } from './app-server-approval.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { main as hostMain } from './host.js';
 export { main as registerMain } from './register.js';
 export { main as setupMain } from './setup.js';
-export { mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
+export { extractCodexApprovalDiff, mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';

package/dist/outbox.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Turn-end media outbox for Canon coding hosts.
+ *
+ * The host advertises a per-conversation outbox directory inside the session
+ * working directory (`<cwd>/.canon/outbox/`). When the runtime wants a file
+ * (screenshot, plot, artifact) delivered to the Canon conversation it writes
+ * the file there — an explicit channel, never inferred from reply prose. At
+ * turn end the host scans the outbox, uploads each regular file as a Canon
+ * media attachment, and removes files that were delivered. Failed uploads
+ * stay in place for a later turn; subdirectories, symlinks, and dotfiles are
+ * ignored.
+ *
+ * This module is intentionally identical in packages/claude-code-plugin and
+ * packages/codex-plugin — keep both copies in sync (future consolidation
+ * candidate).
+ */
+export declare const OUTBOX_MAX_FILES_PER_TURN = 8;
+export declare const OUTBOX_MAX_FILE_BYTES: number;
+export interface OutboxFile {
+    path: string;
+    fileName: string;
+    sizeBytes: number;
+}
+export type OutboxSkipReason = 'not-regular-file' | 'hidden' | 'too-large' | 'file-cap';
+export interface OutboxScanResult {
+    /** Regular files eligible for upload this turn, ordered by file name. */
+    files: OutboxFile[];
+    skipped: Array<{
+        fileName: string;
+        reason: OutboxSkipReason;
+    }>;
+}
+export interface OutboxFlushResult {
+    sent: Array<{
+        file: OutboxFile;
+        messageId: string;
+        removeFailed?: true;
+    }>;
+    failed: Array<{
+        file: OutboxFile;
+        error: string;
+    }>;
+    skipped: OutboxScanResult['skipped'];
+}
+export declare function resolveOutboxDir(sessionCwd: string): string;
+/**
+ * Create the outbox directory for a session and drop a `.gitignore` into the
+ * host-managed `.canon/` dir (only when absent) so outbox state never shows
+ * up as untracked dirt inside project checkouts or conversation worktrees.
+ */
+export declare function ensureOutboxDir(sessionCwd: string): Promise<string>;
+/**
+ * The one terse paragraph injected into the runtime's Canon context so the
+ * agent knows the outbox exists. Hosts may append their own extra sentence
+ * (e.g. an immediate-send tool) but must not paraphrase the convention.
+ */
+export declare function buildOutboxContextLine(sessionCwd: string): string;
+/**
+ * Discover the outbox files eligible for upload this turn. A missing outbox
+ * directory is an empty result. Entries are ordered by file name so multi-file
+ * turns deliver deterministically; everything past the per-turn cap (or over
+ * the size cap) is left in place and reported as skipped.
+ */
+export declare function scanOutbox(outboxDir: string, options?: {
+    maxFiles?: number;
+    maxFileBytes?: number;
+}): Promise<OutboxScanResult>;
+/**
+ * Upload-and-consume pass over the outbox. Each eligible file is handed to
+ * `send`; on success the file is removed (consumed), on failure it is left in
+ * place for a later turn. A failed removal after a successful send is still
+ * reported as sent (flagged `removeFailed`) so callers can warn about a
+ * potential duplicate next turn instead of re-reporting a delivery failure.
+ */
+export declare function flushOutbox(input: {
+    outboxDir: string;
+    send: (file: OutboxFile) => Promise<{
+        messageId: string;
+    }>;
+    maxFiles?: number;
+    maxFileBytes?: number;
+    remove?: (path: string) => Promise<void>;
+}): Promise<OutboxFlushResult>;