@canonmsg/codex-plugin 0.11.12 → 0.13.0

package/dist/host.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { setDefaultResultOrder } from 'node:dns';
 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, buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, 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, buildRuntimeCardOutcome, buildPlanApprovalRequest, buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, 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, parseRuntimeCardV1, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, saveRuntimeSessionState, buildBoundedTurnTrail, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
+import { CodexAppServerAdapter } from './app-server-adapter.js';
+import { mapCanonApprovalResultToCodexDecision, mapCodexAppServerApprovalRequest, } from './app-server-approval.js';
 import { clearStoredThreadId, buildCodexThreadPolicyFingerprint, loadStoredThreadId, saveStoredThreadId, } from './session-store.js';
 import { deriveCodexPermissionEnvelope, mapCanonPermissionToCodex, } from './permission-mode.js';
 import { detectCodexCliVersion } from './codex-cli-version.js';
@@ -64,6 +67,19 @@ let workspaceRoots = [];
 let workspaceRootMetadata = [];
 function buildCodexRuntimeDescriptor(input) {
     const commands = [
+        ...(input.supportsPlanMode
+            ? [{
+                    id: 'plan',
+                    label: 'Plan first',
+                    description: 'Ask Codex to plan before implementing. Text after /plan becomes the planning prompt.',
+                    aliases: ['plan'],
+                    category: 'plan',
+                    placements: ['composer_slash', 'command_palette'],
+                    availability: ['always'],
+                    trailingTextBehavior: 'send_as_prompt',
+                    dispatch: { kind: 'text_passthrough', template: '/plan {argument}' },
+                }]
+            : []),
         {
             id: 'runtime-status',
             label: 'Runtime status',
@@ -79,6 +95,8 @@ function buildCodexRuntimeDescriptor(input) {
             ...RUNTIME_NEW_SESSION_ACTION,
             primitive: 'session.new',
         },
+        RUNTIME_STOP_ACTION,
+        RUNTIME_STOP_AND_DROP_ACTION,
     ];
     const descriptor = buildFirstPartyCodingRuntimeDescriptor({
         clientType: 'codex',
@@ -91,11 +109,21 @@ function buildCodexRuntimeDescriptor(input) {
         presentation: input.presentation,
         streamingTextMode: 'snapshot',
         commands,
-        actions: [
-            RUNTIME_STOP_ACTION,
-            RUNTIME_STOP_AND_DROP_ACTION,
-            RUNTIME_NEW_SESSION_ACTION,
-        ],
+        ...(input.supportsRichCards
+            ? {
+                runtimeCards: {
+                    rich: {
+                        schema: 'canon.card.v1',
+                        lifecycle: 'blocking_requires_action',
+                        responder: 'agent_owner',
+                        result: 'action_or_values',
+                        maxTimeoutMs: 30 * 60_000,
+                        blockKinds: ['summary', 'metricGrid', 'chart', 'table', 'list', 'callout', 'actions'],
+                        native: true,
+                    },
+                },
+            }
+            : {}),
     });
     if (input.models.length > 0) {
         return descriptor;
@@ -119,18 +147,6 @@ function buildCodexModelOptions(model) {
         ? [{ value: model.trim(), label: modelOptionLabel(model.trim()) }]
         : [];
 }
-function normalizeRuntimeTurnState(value) {
-    const normalizedTurn = normalizeTurnState(value);
-    if (normalizedTurn) {
-        return {
-            state: normalizedTurn.state,
-            ...(normalizedTurn.openedAt !== undefined ? { openedAt: normalizedTurn.openedAt } : {}),
-            ...(normalizedTurn.updatedAt !== undefined ? { updatedAt: normalizedTurn.updatedAt } : {}),
-            ...(normalizedTurn.turnUpdatedAt !== undefined ? { turnUpdatedAt: normalizedTurn.turnUpdatedAt } : {}),
-        };
-    }
-    return null;
-}
 async function publishAgentRuntime(agentId, runtime) {
     await publishHostAgentRuntime(agentId, 'codex', runtime);
 }
@@ -249,6 +265,78 @@ function stringArgs(value) {
         ? value.filter((item) => typeof item === 'string' && item.trim().length > 0)
         : undefined;
 }
+function supportsCodexAppServer(codexBin) {
+    if (process.env.CANON_CODEX_TRANSPORT === 'exec')
+        return false;
+    if (process.env.CANON_CODEX_TRANSPORT === 'app-server')
+        return true;
+    const result = spawnSync(codexBin, ['app-server', '--help'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return result.status === 0;
+}
+function parsePlanCommand(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith('/plan'))
+        return { planMode: false, content };
+    const rest = trimmed.replace(/^\/plan(?:\s+)?/i, '').trim();
+    return {
+        planMode: true,
+        content: rest || 'Please inspect the request and propose a plan before making changes.',
+    };
+}
+function mapCodexQuestions(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const questions = value.slice(0, 12).flatMap((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            return [];
+        const record = entry;
+        const id = typeof record.id === 'string' && record.id.trim() ? record.id.trim().slice(0, 120) : null;
+        const question = typeof record.question === 'string' && record.question.trim()
+            ? record.question.trim().slice(0, 1000)
+            : null;
+        if (!id || !/^[A-Za-z0-9_.:-]{1,120}$/.test(id) || !question)
+            return [];
+        const header = typeof record.header === 'string' && record.header.trim()
+            ? record.header.trim().slice(0, 120)
+            : undefined;
+        const rawOptions = Array.isArray(record.options) ? record.options : [];
+        const choices = rawOptions.slice(0, 12).flatMap((option) => {
+            if (!option || typeof option !== 'object' || Array.isArray(option))
+                return [];
+            const optionRecord = option;
+            const label = typeof optionRecord.label === 'string' && optionRecord.label.trim()
+                ? optionRecord.label.trim().slice(0, 120)
+                : null;
+            if (!label)
+                return [];
+            const description = typeof optionRecord.description === 'string' && optionRecord.description.trim()
+                ? optionRecord.description.trim().slice(0, 300)
+                : undefined;
+            return [{ label, value: label, ...(description ? { description } : {}) }];
+        });
+        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 } : {}),
+                ...(record.isSecret === true ? { isSecret: true } : {}),
+                ...(record.multiSelect === true ? { multiSelect: true } : {}),
+            }];
+    });
+    return questions.length > 0 ? questions : undefined;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
 export async function main() {
     setDefaultResultOrder('ipv4first');
     const { values: args } = parseArgs({
@@ -290,12 +378,14 @@ export async function main() {
     }
     const codexBin = typeof args['codex-bin'] === 'string' ? args['codex-bin'] : 'codex';
     const codexCliStatus = detectCodexCliVersion(codexBin);
+    const useAppServer = supportsCodexAppServer(codexBin);
     if (codexCliStatus.version) {
         console.error(`[canon-codex] Detected Codex CLI ${codexCliStatus.version} (${codexBin})`);
     }
     else {
         console.error(`[canon-codex] Could not detect Codex CLI version for ${codexBin}: ${codexCliStatus.error ?? 'unknown result'}`);
     }
+    console.error(`[canon-codex] Codex transport: ${useAppServer ? 'app-server' : 'exec --json'}`);
     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);
@@ -418,14 +508,6 @@ export async function main() {
             pendingMembershipChanges.delete(conversationId);
         }
     }
-    async function loadSenderRuntimeState(conversationId, senderId) {
-        try {
-            return normalizeRuntimeTurnState(await rtdbRead(`/turn-state/${conversationId}/${senderId}`));
-        }
-        catch {
-            return null;
-        }
-    }
     async function loadHydratedInboundContext(input) {
         const [conversation, page] = await Promise.all([
             getConversationMeta(input.conversationId),
@@ -523,6 +605,61 @@ export async function main() {
     function clearStreaming(conversationId) {
         runtimeState.clearStreaming(conversationId).catch(() => { });
     }
+    function writeCodexStreaming(session, text, status) {
+        if (text !== null) {
+            session.turnLiveText = text;
+        }
+        else if (status !== 'thinking' && session.turnLiveText === 'Thinking…') {
+            session.turnLiveText = '';
+        }
+        runtimeState.writeStreaming(session.conversationId, {
+            text: session.turnLiveText,
+            status,
+            messageId: session.currentTurnId ?? undefined,
+            turnId: session.currentTurnId,
+            blocks: session.turnBlocks,
+        }).catch(() => { });
+    }
+    function upsertTurnBlock(session, block) {
+        const now = Date.now();
+        const index = session.turnBlocks.findIndex((existing) => existing.id === block.id);
+        const existing = index >= 0 ? session.turnBlocks[index] : null;
+        const next = {
+            ...(existing ?? {
+                sequence: session.turnBlocks.length + 1,
+                createdAt: now,
+            }),
+            ...block,
+            turnId: session.currentTurnId ?? block.id,
+            updatedAt: now,
+        };
+        session.turnBlocks = index >= 0
+            ? [
+                ...session.turnBlocks.slice(0, index),
+                next,
+                ...session.turnBlocks.slice(index + 1),
+            ]
+            : [...session.turnBlocks, next];
+    }
+    function completeTurnBlock(session, id, summary) {
+        const existing = session.turnBlocks.find((block) => block.id === id);
+        if (!existing)
+            return;
+        upsertTurnBlock(session, {
+            id,
+            kind: existing.kind,
+            status: 'completed',
+            title: existing.title,
+            text: existing.text,
+            summary: summary ?? existing.summary,
+        });
+    }
+    function buildFinalTurnTrail(session) {
+        return buildBoundedTurnTrail(session.turnBlocks.map((block) => ({
+            ...block,
+            turnId: session.currentTurnId ?? block.turnId,
+        })));
+    }
     async function handoffFinalMessage(conversationId) {
         await sleep(FINAL_MESSAGE_HANDOFF_MS);
         clearStreaming(conversationId);
@@ -555,6 +692,9 @@ export async function main() {
             return;
         session.closed = true;
         stopVisibleWorkSignal(session);
+        if ('close' in session.adapter && typeof session.adapter.close === 'function') {
+            session.adapter.close();
+        }
         releaseConversationEnvironment(session.environment);
         clearStreaming(conversationId);
         runtimeState.clearSessionState(conversationId).catch(() => { });
@@ -638,11 +778,20 @@ export async function main() {
                     throw new ExecutionEnvironmentError(modelGuard, modelGuard);
                 }
                 const storedThreadId = loadStoredThreadId(runtimeId, agentId, conversationId, environment.baseCwd, environment.mode, policy.fingerprint);
-                const session = {
-                    conversationId,
-                    cwd: sessionCwd,
-                    environment,
-                    adapter: new CodexConversationAdapter({
+                const adapter = useAppServer
+                    ? new CodexAppServerAdapter({
+                        cwd: sessionCwd,
+                        threadId: storedThreadId,
+                        codexBin,
+                        model: policy.model ?? null,
+                        sandbox: policy.sandbox,
+                        approvalPolicy: policy.approvalPolicy,
+                        addDirs: args['add-dir'] ?? [],
+                        configOverrides: args.config ?? [],
+                        fullAuto: policy.fullAuto,
+                        bypassApprovalsAndSandbox: policy.bypassApprovalsAndSandbox,
+                    })
+                    : new CodexConversationAdapter({
                         cwd: sessionCwd,
                         threadId: storedThreadId,
                         codexBin,
@@ -654,7 +803,12 @@ export async function main() {
                         configOverrides: args.config ?? [],
                         fullAuto: policy.fullAuto,
                         bypassApprovalsAndSandbox: policy.bypassApprovalsAndSandbox,
-                    }),
+                    });
+                const session = {
+                    conversationId,
+                    cwd: sessionCwd,
+                    environment,
+                    adapter,
                     queue: [],
                     running: false,
                     state: {
@@ -673,6 +827,8 @@ export async function main() {
                     lastActivity: Date.now(),
                     typingKeepaliveTimer: null,
                     closed: false,
+                    turnLiveText: '',
+                    turnBlocks: [],
                 };
                 sessions.set(conversationId, session);
                 await Promise.all([
@@ -697,8 +853,8 @@ export async function main() {
             pendingSessionCreations.delete(conversationId);
         }
     }
-    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false, imagePaths = [], mediaAddDirs = []) {
-        const nextPrompt = { prompt, intent, sourceMessageId, markAccepted, imagePaths, mediaAddDirs };
+    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false, imagePaths = [], mediaAddDirs = [], planMode = false) {
+        const nextPrompt = { prompt, intent, sourceMessageId, markAccepted, imagePaths, mediaAddDirs, planMode };
         if (toFront) {
             session.queue.unshift(nextPrompt);
         }
@@ -709,8 +865,276 @@ export async function main() {
         writeTurn(session);
         void runNextTurn(session);
     }
+    async function waitForRuntimeInputResponse(input) {
+        while (Date.now() < input.expiresAt) {
+            const response = await client.consumeRuntimeInputResponse({
+                conversationId: input.conversationId,
+                inputId: input.inputId,
+            }).catch(() => null);
+            if (response?.status === 'submitted') {
+                return { status: 'submitted', value: response.value, answers: response.answers };
+            }
+            if (response?.status === 'cancelled' || response?.status === 'timeout') {
+                return { status: response.status };
+            }
+            await sleep(1_000);
+        }
+        const response = await client.consumeRuntimeInputResponse({
+            conversationId: input.conversationId,
+            inputId: input.inputId,
+        }).catch(() => null);
+        if (response?.status === 'submitted') {
+            return { status: 'submitted', value: response.value, answers: response.answers };
+        }
+        return { status: 'timeout' };
+    }
+    async function waitForRuntimeApprovalResponse(input) {
+        while (Date.now() < input.expiresAt) {
+            const response = await client.consumeRuntimeApprovalResponse({
+                conversationId: input.conversationId,
+                approvalId: input.approvalId,
+            }).catch(() => null);
+            if (response?.status === 'allow') {
+                return { decision: 'allow', sessionRule: response.sessionRule };
+            }
+            if (response?.status === 'deny' || response?.status === 'timeout') {
+                return { decision: 'deny' };
+            }
+            await sleep(1_000);
+        }
+        await client.consumeRuntimeApprovalResponse({
+            conversationId: input.conversationId,
+            approvalId: input.approvalId,
+        }).catch(() => null);
+        return { decision: 'deny' };
+    }
+    async function waitForRuntimeCardResponse(input) {
+        while (Date.now() < input.expiresAt) {
+            const response = await client.consumeRuntimeCardResponse({
+                conversationId: input.conversationId,
+                cardId: input.cardId,
+            }).catch(() => null);
+            if (response?.status === 'submitted') {
+                return {
+                    status: 'submitted',
+                    ...(response.actionId ? { actionId: response.actionId } : {}),
+                    ...(response.values ? { values: response.values } : {}),
+                };
+            }
+            if (response?.status === 'cancelled' || response?.status === 'timeout') {
+                return { status: response.status };
+            }
+            await sleep(1_000);
+        }
+        const response = await client.consumeRuntimeCardResponse({
+            conversationId: input.conversationId,
+            cardId: input.cardId,
+        }).catch(() => null);
+        if (response?.status === 'submitted') {
+            return {
+                status: 'submitted',
+                ...(response.actionId ? { actionId: response.actionId } : {}),
+                ...(response.values ? { values: response.values } : {}),
+            };
+        }
+        return { status: 'timeout' };
+    }
+    function runtimeCardRequestPayload(method, params) {
+        if (method !== 'item/runtimeCard/request'
+            && method !== 'runtimeCard/request') {
+            return null;
+        }
+        const input = isRecord(params.input) ? params.input : null;
+        const args = isRecord(params.arguments) ? params.arguments : null;
+        return params.card ?? params.cardDocument ?? input?.card ?? args?.card ?? null;
+    }
+    async function handleCodexServerRequest(session, request) {
+        const requestId = String(request.id);
+        const params = request.params;
+        const expiresAt = Date.now() + 30 * 60_000;
+        const runtimeCardPayload = runtimeCardRequestPayload(request.method, params);
+        if (runtimeCardPayload) {
+            const card = parseRuntimeCardV1(runtimeCardPayload);
+            if (!card) {
+                return { status: 'cancelled', error: 'Invalid canon.card.v1 card' };
+            }
+            const cardId = readString(params, 'cardId')
+                ?? readString(params, 'itemId')
+                ?? card.cardId
+                ?? requestId;
+            let requestCreated = false;
+            let requestResolved = false;
+            try {
+                await client.createRuntimeCardRequest({
+                    conversationId: session.conversationId,
+                    cardId,
+                    card: { ...card, cardId },
+                    expiresAt,
+                    // Omit responseUserId so the backend targets a reachable member (the
+                    // owner if present, else the sole other member) — the owner is often
+                    // not a member of agent-to-user DMs.
+                    native: {
+                        runtime: 'codex',
+                        method: request.method,
+                        requestId,
+                        turnId: readString(params, 'turnId') ?? session.currentTurnId ?? undefined,
+                        handles: {
+                            itemId: readString(params, 'itemId') ?? '',
+                            threadId: readString(params, 'threadId') ?? '',
+                        },
+                    },
+                    turnId: session.currentTurnId ?? undefined,
+                });
+                requestCreated = true;
+                session.turnState = 'waiting_input';
+                markTurnProgress(session);
+                upsertTurnBlock(session, {
+                    id: `card:${cardId}`,
+                    kind: 'input',
+                    status: 'pending',
+                    title: card.title,
+                    summary: card.template ?? 'runtime card',
+                });
+                writeTurn(session);
+                stopVisibleWorkSignal(session);
+                writeCodexStreaming(session, null, 'waiting_input');
+                const response = await waitForRuntimeCardResponse({
+                    conversationId: session.conversationId,
+                    cardId,
+                    expiresAt,
+                });
+                requestResolved = true;
+                const outcome = buildRuntimeCardOutcome(cardId, response.status, { reason: response.status });
+                await client.sendMessage(session.conversationId, outcome.text, {
+                    metadata: {
+                        ...outcome.metadata,
+                        turnId: session.currentTurnId ?? undefined,
+                        turnSemantics: 'control',
+                        replyBehavior: 'suppress_auto_reply',
+                    },
+                });
+                completeTurnBlock(session, `card:${cardId}`, `Card ${response.status}`);
+                if (session.turnState === 'waiting_input') {
+                    session.turnState = 'thinking';
+                    markTurnProgress(session);
+                    writeTurn(session);
+                    startVisibleWorkSignal(session);
+                    writeCodexStreaming(session, null, 'thinking');
+                }
+                return response;
+            }
+            catch (error) {
+                if (requestCreated && !requestResolved) {
+                    await client.consumeRuntimeCardResponse({
+                        conversationId: session.conversationId,
+                        cardId,
+                        cancel: true,
+                    }).catch(() => null);
+                    const outcome = buildRuntimeCardOutcome(cardId, 'cancelled', { reason: 'interrupted' });
+                    await client.sendMessage(session.conversationId, outcome.text, {
+                        metadata: {
+                            ...outcome.metadata,
+                            turnId: session.currentTurnId ?? undefined,
+                            turnSemantics: 'control',
+                            replyBehavior: 'suppress_auto_reply',
+                        },
+                    }).catch(() => null);
+                }
+                throw error;
+            }
+        }
+        if (request.method === 'item/tool/requestUserInput') {
+            const paramsInput = isRecord(params.input) ? params.input : null;
+            const paramsArguments = isRecord(params.arguments) ? params.arguments : null;
+            const questions = mapCodexQuestions(params.questions ?? paramsInput?.questions ?? paramsArguments?.questions);
+            const inputId = readString(params, 'itemId') ?? requestId;
+            await client.createRuntimeInputRequest({
+                conversationId: session.conversationId,
+                inputId,
+                kind: 'clarify',
+                expiresAt,
+                responseUserId: ownerId ?? undefined,
+                title: 'Codex needs input',
+                prompt: questions?.length
+                    ? 'Codex needs your input to continue.'
+                    : 'Codex needs input.',
+                ...(questions ? { questions } : {}),
+                sensitive: Boolean(questions?.some((question) => question.isSecret)),
+                native: {
+                    runtime: 'codex',
+                    method: request.method,
+                    requestId,
+                    turnId: readString(params, 'turnId') ?? session.currentTurnId ?? undefined,
+                    handles: {
+                        itemId: readString(params, 'itemId') ?? '',
+                        threadId: readString(params, 'threadId') ?? '',
+                    },
+                },
+                turnId: session.currentTurnId ?? undefined,
+            });
+            const response = await waitForRuntimeInputResponse({
+                conversationId: session.conversationId,
+                inputId,
+                expiresAt,
+            });
+            return { answers: response.status === 'submitted' ? response.answers ?? {} : {} };
+        }
+        const mappedApproval = mapCodexAppServerApprovalRequest({
+            method: request.method,
+            params,
+        });
+        if (mappedApproval) {
+            const approvalId = readString(params, 'approvalId') ?? readString(params, 'itemId') ?? requestId;
+            await client.createRuntimeApprovalRequest({
+                conversationId: session.conversationId,
+                approvalId,
+                toolName: mappedApproval.toolName,
+                toolSummary: mappedApproval.toolSummary,
+                category: mappedApproval.category,
+                risk: mappedApproval.risk,
+                riskLevel: mappedApproval.riskLevel,
+                native: {
+                    ...mappedApproval.native,
+                    requestId,
+                    method: request.method,
+                },
+                details: mappedApproval.details,
+                responseUserId: ownerId ?? undefined,
+                allowSessionRule: true,
+                expiresAt,
+                turnId: session.currentTurnId ?? undefined,
+            });
+            const response = await waitForRuntimeApprovalResponse({
+                conversationId: session.conversationId,
+                approvalId,
+                expiresAt,
+            });
+            if (request.method === 'item/permissions/requestApproval') {
+                return response.decision === 'allow'
+                    ? { permissions: isRecord(params.permissions) ? params.permissions : {}, scope: response.sessionRule ? 'session' : 'turn' }
+                    : { permissions: {}, scope: 'turn' };
+            }
+            return mapCanonApprovalResultToCodexDecision({
+                decision: response.decision,
+                ...(response.sessionRule ? { sessionRule: response.sessionRule } : {}),
+            });
+        }
+        return {};
+    }
     async function enqueueInboundMessage(input) {
         knownConversationIds.add(input.conversationId);
+        if (isRecord(input.message.metadata)
+            && input.message.metadata.type === 'plan_approval_reply'
+            && typeof input.message.metadata.decision === 'string') {
+            const session = await getOrCreateSession(input.conversationId);
+            const feedback = readString(input.message.metadata, 'feedback');
+            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}` : ''}`;
+            enqueuePrompt(session, prompt, 'queue', false, input.message.id, false, [], [], decision !== 'approve');
+            return;
+        }
         let materialized = [];
         if (input.message.id) {
             try {
@@ -723,7 +1147,11 @@ export async function main() {
                 console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to materialize media:`, error instanceof Error ? error.message : error);
             }
         }
-        const content = renderInboundContent(input.message, materialized);
+        const renderedContent = renderInboundContent(input.message, materialized);
+        const planCommand = useAppServer
+            ? parsePlanCommand(renderedContent)
+            : { planMode: false, content: renderedContent };
+        const content = planCommand.content;
         const hydrated = await loadHydratedInboundContext({
             conversationId: input.conversationId,
             message: input.message,
@@ -773,7 +1201,6 @@ export async function main() {
                 ...(activeSelfContextId ? { selfContextId: activeSelfContextId } : {}),
                 metadata: {
                     turnSemantics: 'turn_complete',
-                    turnComplete: true,
                     replyBehavior: 'suppress_auto_reply',
                 },
             }).catch(() => { });
@@ -789,14 +1216,14 @@ export async function main() {
             replyContext,
         });
         if (session.running && deliveryIntent === 'interrupt') {
-            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs);
+            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode);
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Interrupting current turn for explicit human send-now`);
             await session.adapter.interrupt().catch(() => { });
             clearStreaming(input.conversationId);
             client.setTyping(input.conversationId, false).catch(() => { });
             return;
         }
-        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs);
+        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode);
     }
     async function runNextTurn(session) {
         if (session.running || session.closed)
@@ -808,6 +1235,8 @@ export async function main() {
         session.state.lastError = undefined;
         session.state.state = 'running';
         session.currentTurnId = randomUUID();
+        session.turnLiveText = '';
+        session.turnBlocks = [];
         session.currentTurnOpenedAt = Date.now();
         session.currentTurnUpdatedAt = session.currentTurnOpenedAt;
         session.lastAcceptedIntent = nextTurn.intent;
@@ -817,12 +1246,7 @@ export async function main() {
         writeState(session);
         writeTurn(session);
         startVisibleWorkSignal(session);
-        runtimeState.writeStreaming(session.conversationId, {
-            text: 'Thinking…',
-            status: 'thinking',
-            messageId: session.currentTurnId ?? undefined,
-            turnId: session.currentTurnId,
-        }).catch(() => { });
+        writeCodexStreaming(session, 'Thinking…', 'thinking');
         try {
             const modelGuard = buildCodexModelGuardMessage(session.state.model, codexCliStatus);
             if (modelGuard) {
@@ -846,12 +1270,31 @@ export async function main() {
                     writeTurn(session);
                     stopVisibleWorkSignal(session);
                     client.setTyping(session.conversationId, false).catch(() => { });
-                    runtimeState.writeStreaming(session.conversationId, {
+                    writeCodexStreaming(session, event.text, 'streaming');
+                    return;
+                }
+                if (event.type === 'plan.updated') {
+                    session.turnState = 'streaming';
+                    markTurnProgress(session);
+                    writeTurn(session);
+                    stopVisibleWorkSignal(session);
+                    client.setTyping(session.conversationId, false).catch(() => { });
+                    upsertTurnBlock(session, {
+                        id: `plan:${session.currentTurnId}`,
+                        kind: 'plan',
+                        status: 'running',
+                        title: 'Plan',
                         text: event.text,
-                        status: 'streaming',
-                        messageId: session.currentTurnId ?? undefined,
-                        turnId: session.currentTurnId,
-                    }).catch(() => { });
+                    });
+                    writeCodexStreaming(session, event.text, 'streaming');
+                    return;
+                }
+                if (event.type === 'waiting') {
+                    session.turnState = 'waiting_input';
+                    markTurnProgress(session);
+                    writeTurn(session);
+                    stopVisibleWorkSignal(session);
+                    writeCodexStreaming(session, null, 'waiting_input');
                     return;
                 }
                 if (event.type === 'command.started') {
@@ -859,20 +1302,24 @@ export async function main() {
                     markTurnProgress(session);
                     writeTurn(session);
                     startVisibleWorkSignal(session);
-                    runtimeState.writeStreaming(session.conversationId, {
-                        text: summarizeCommand(event.command),
-                        status: 'tool',
-                        messageId: session.currentTurnId ?? undefined,
-                        turnId: session.currentTurnId,
-                    }).catch(() => { });
+                    upsertTurnBlock(session, {
+                        id: `command:${session.currentTurnId}`,
+                        kind: 'tool',
+                        status: 'running',
+                        title: summarizeCommand(event.command),
+                        summary: 'Command running',
+                    });
+                    writeCodexStreaming(session, null, 'tool');
                     return;
                 }
                 if (event.type === 'command.completed') {
+                    completeTurnBlock(session, `command:${session.currentTurnId}`, 'Command completed');
                     if (session.turnState === 'tool') {
                         session.turnState = 'thinking';
                         markTurnProgress(session);
                         writeTurn(session);
                         startVisibleWorkSignal(session);
+                        writeCodexStreaming(session, null, 'thinking');
                     }
                     return;
                 }
@@ -887,7 +1334,10 @@ export async function main() {
                 clearStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, session.environment.mode);
                 session.adapter.clearThreadId();
             };
-            const runTurnOnce = () => session.adapter.runTurn(nextTurn.prompt, handleCodexEvent, logCodexLine, turnImagePaths, turnMediaAddDirs);
+            const runTurnOnce = () => session.adapter.runTurn(nextTurn.prompt, handleCodexEvent, logCodexLine, turnImagePaths, turnMediaAddDirs, {
+                planMode: nextTurn.planMode,
+                onServerRequest: (request) => handleCodexServerRequest(session, request),
+            });
             let result = await runTurnOnce();
             if (!result.interrupted
                 && !result.finalMessage
@@ -901,10 +1351,28 @@ export async function main() {
             if (result.threadId && !session.resetRequested) {
                 saveStoredThreadId(runtimeId, agentId, session.conversationId, session.environment.baseCwd, result.threadId, session.environment.mode, session.policyFingerprint);
             }
-            if (!result.interrupted && result.finalMessage) {
+            if (!result.interrupted && result.finalMessage && nextTurn.planMode) {
+                const planApproval = buildPlanApprovalRequest(session.currentTurnId ?? randomUUID(), 'Plan ready for review.', {
+                    responseUserId: ownerId ?? undefined,
+                    title: 'Codex Plan',
+                    body: result.finalMessage,
+                });
+                await client.sendMessage(session.conversationId, planApproval.text, {
+                    metadata: {
+                        ...planApproval.metadata,
+                        turnId: session.currentTurnId,
+                        turnSemantics: 'control',
+                        replyBehavior: 'suppress_auto_reply',
+                    },
+                });
+                await handoffFinalMessage(session.conversationId);
+                console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Sent plan approval card`);
+            }
+            else if (!result.interrupted && result.finalMessage) {
                 if (isRecoverableCodexThreadError(result.errorText)) {
                     clearStoredThread();
                 }
+                const turnTrail = buildFinalTurnTrail(session);
                 await client.sendMessage(session.conversationId, result.finalMessage, {
                     ...(session.activeSelfContextId
                         ? { selfContextId: session.activeSelfContextId }
@@ -912,8 +1380,8 @@ export async function main() {
                     metadata: {
                         turnId: session.currentTurnId,
                         turnSemantics: 'turn_complete',
-                        turnComplete: true,
                         deliveryIntent: session.lastAcceptedIntent ?? undefined,
+                        ...(turnTrail.length > 0 ? { turnTrail } : {}),
                     },
                 });
                 await handoffFinalMessage(session.conversationId);
@@ -926,6 +1394,7 @@ export async function main() {
                 if (result.errorText) {
                     console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Turn exited ${result.exitCode}: ${result.errorText}`);
                 }
+                const turnTrail = buildFinalTurnTrail(session);
                 await client.sendMessage(session.conversationId, userVisibleError, {
                     ...(session.activeSelfContextId
                         ? { selfContextId: session.activeSelfContextId }
@@ -933,8 +1402,8 @@ export async function main() {
                     metadata: {
                         turnId: session.currentTurnId,
                         turnSemantics: 'turn_complete',
-                        turnComplete: true,
                         deliveryIntent: session.lastAcceptedIntent ?? undefined,
+                        ...(turnTrail.length > 0 ? { turnTrail } : {}),
                     },
                 });
                 await handoffFinalMessage(session.conversationId);
@@ -964,7 +1433,6 @@ export async function main() {
                 metadata: {
                     turnId: session.currentTurnId,
                     turnSemantics: 'turn_complete',
-                    turnComplete: true,
                     deliveryIntent: session.lastAcceptedIntent ?? undefined,
                 },
             }).catch(() => { });
@@ -1024,6 +1492,8 @@ export async function main() {
             permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
             defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
             presentation: runtimePresentation,
+            supportsPlanMode: useAppServer,
+            supportsRichCards: useAppServer,
         }),
     };
     async function baselineControlSignal(conversationId) {
@@ -1108,12 +1578,14 @@ export async function main() {
                         {
                             id: 'transport',
                             label: 'Transport',
-                            value: 'exec --json',
+                            value: useAppServer ? 'app-server' : 'exec --json',
                         },
                         {
                             id: 'streaming',
                             label: 'Live output',
-                            value: 'Thinking, tools, and completed-message previews',
+                            value: useAppServer
+                                ? 'Plans, questions, approvals, tools, and message deltas'
+                                : 'Thinking, tools, and completed-message previews',
                         },
                         {
                             id: 'codex-cli',
@@ -1124,8 +1596,8 @@ export async function main() {
                         {
                             id: 'nativeActions',
                             label: 'Native actions',
-                            value: 'Limited until app-server transport',
-                            tone: 'warning',
+                            value: useAppServer ? 'Enabled' : 'Limited until app-server transport',
+                            ...(useAppServer ? {} : { tone: 'warning' }),
                         },
                     ],
                     execution: {
@@ -1139,8 +1611,9 @@ export async function main() {
                         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.',
-                        'Codex review, compact/rollback, live plan/diff/reasoning updates, PTY command execution, plugin/app/MCP inventory, and structured approvals require the future app-server transport.',
+                        useAppServer
+                            ? 'This Codex host uses the app-server transport, so Canon can route native plan mode, runtime questions, approvals, and live turn updates.'
+                            : 'This Codex host uses the current exec --json transport, so Canon can show thinking, tool activity, and completed assistant-message previews, but not native plan questions or structured approvals.',
                     ],
                 };
                 await runtimeState.writeRuntimeInfo(conversationId, payload);
@@ -1215,6 +1688,8 @@ export async function main() {
                 permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
                 defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
                 presentation: runtimePresentation,
+                supportsPlanMode: useAppServer,
+                supportsRichCards: useAppServer,
             }),
         };
     }
@@ -1235,6 +1710,8 @@ export async function main() {
                 permissionModes: [...codexPermissionEnvelope.availablePermissionModes],
                 defaultPermissionMode: codexPermissionEnvelope.defaultPermissionMode,
                 presentation: runtimePresentation,
+                supportsPlanMode: useAppServer,
+                supportsRichCards: useAppServer,
             }),
         };
     }
@@ -1264,13 +1741,9 @@ export async function main() {
                 ? inboundMessages.slice(cursorIndex + 1)
                 : inboundMessages.slice(-1);
             for (const latestMessage of messagesToRecover) {
-                const senderTurnState = latestMessage.senderType === 'ai_agent'
-                    ? await loadSenderRuntimeState(conversation.id, latestMessage.senderId)
-                    : null;
                 const triggerDecision = shouldTriggerAgentTurn({
                     senderType: latestMessage.senderType ?? 'human',
                     metadata: latestMessage.metadata,
-                    senderTurnState,
                 });
                 if (!triggerDecision.allow) {
                     console.error(`[canon-codex] [${conversation.id.slice(0, 8)}] Skipping startup recovery for suppressed message (${triggerDecision.reason})`);