@canonmsg/codex-plugin 0.25.1 → 0.26.1

package/README.md

@@ -60,6 +60,33 @@ You do not need a git repo for host mode. Any readable working directory is vali
 - Quiet group turns: in groups the host shows the thinking indicator and the
   answer only; direct chats keep the live preview and margin activity
 
+### Service-agent mode
+
+Long-running customer agents can use the same Canon host without exposing its
+coding controls:
+
+```bash
+canon-codex \
+  --cwd /srv/agent-workspace \
+  --service-agent \
+  --no-native-vision
+```
+
+`--service-agent` removes the coding-oriented dynamic tools and exposes only
+`codex_app.canon_runtime_control` plus `codex_app.no_reply`. Runtime control is
+bound by the host to the active Canon conversation and authenticated human; the
+model cannot select another user, conversation, or responder. It can display a
+card with `send_card`, wait for an action card with `request_card`, or ask one
+standalone question with `request_input`.
+
+Authorized conversation members may use a service agent even when they do not
+own its Canon identity. Normal coding-host sessions keep their existing
+owner-only execution boundary.
+
+`--no-native-vision` keeps inbound attachment paths in the prompt while
+suppressing Codex's native image input. This lets a service agent use its
+purpose-built OCR tool as the only image-recognition path.
+
 ## Transports
 
 The host picks a transport at startup and logs the choice as

package/dist/app-server-adapter.js

@@ -382,11 +382,26 @@ export class CodexAppServerAdapter {
     }
     async handleServerRequest(request) {
         try {
+            const params = isRecord(request.params) ? request.params : {};
+            // Detached child threads may use the ordinary coding-thread bridge, but
+            // Canon conversation controls belong only to the foreground human turn.
+            // A fork can inherit dynamic-tool declarations, so enforce this again at
+            // dispatch instead of relying only on the child thread's advertised list.
+            if (isForegroundCanonToolCall(params) && !this.isCurrentThreadNotification(params)) {
+                this.write({
+                    id: request.id,
+                    error: {
+                        code: -32001,
+                        message: 'Server request does not belong to the active Canon turn',
+                    },
+                });
+                return;
+            }
             const result = this.currentRequestHandler
                 ? await this.currentRequestHandler({
                     id: request.id,
                     method: request.method,
-                    params: isRecord(request.params) ? request.params : {},
+                    params,
                 })
                 : defaultServerRequestResult(request.method);
             this.write({ id: request.id, result });
@@ -616,6 +631,15 @@ export class CodexAppServerAdapter {
         this.child.stdin.write(`${JSON.stringify(message)}\n`);
     }
 }
+function isForegroundCanonToolCall(params) {
+    const rawTool = readString(params, 'tool');
+    if (!rawTool)
+        return false;
+    const tool = rawTool.startsWith('codex_app.')
+        ? rawTool.slice('codex_app.'.length)
+        : rawTool;
+    return tool === 'canon_runtime_control' || tool === 'no_reply';
+}
 function parseJson(line) {
     try {
         const parsed = JSON.parse(line);

package/dist/codex-app-tools.d.ts

@@ -43,6 +43,7 @@ type DynamicToolCallResponse = {
  * the host's turn, not to the app-server bridge.
  */
 export declare const CODEX_NO_REPLY_TOOL_NAME = "no_reply";
+export declare const CANON_RUNTIME_CONTROL_TOOL_NAME = "canon_runtime_control";
 /**
  * What the model actually sees for the tool above, for prompt text that names
  * it (the group posture cue). Only meaningful on the app-server transport —
@@ -50,10 +51,28 @@ export declare const CODEX_NO_REPLY_TOOL_NAME = "no_reply";
  */
 export declare const CODEX_NO_REPLY_MODEL_TOOL_NAME = "codex_app.no_reply";
 export declare const CODEX_APP_DYNAMIC_TOOLS: ReadonlyArray<DynamicToolSpec>;
+/** The complete model-visible surface for non-coding service agents. */
+export declare const CODEX_SERVICE_AGENT_DYNAMIC_TOOLS: ReadonlyArray<DynamicToolSpec>;
+/**
+ * Tools exposed to detached Codex threads created through the bridge. Canon
+ * conversation controls belong only to the foreground turn that received the
+ * human message; a child thread has neither that turn nor its responder.
+ */
+export declare const CODEX_DETACHED_THREAD_DYNAMIC_TOOLS: ReadonlyArray<DynamicToolSpec>;
 export declare function isCodexAppToolCall(params: Record<string, unknown>): boolean;
 export declare function deniedCodexAppToolResult(reason: string): DynamicToolCallResponse;
+export declare function successfulCodexAppToolResult(payload: unknown): DynamicToolCallResponse;
 /** True when this dynamic-tool call is the deliberate-silence verb. */
 export declare function isCodexNoReplyToolCall(params: CodexAppToolCallParams): boolean;
+export declare function isCanonRuntimeControlToolCall(params: CodexAppToolCallParams): boolean;
+export declare function isCodexServiceAgentToolCall(params: CodexAppToolCallParams): boolean;
+export interface CanonRuntimeControlRequest {
+    action: 'send_card' | 'request_card' | 'request_input';
+    card?: unknown;
+    prompt?: string;
+    placeholder?: string;
+}
+export declare function parseCanonRuntimeControlRequest(params: CodexAppToolCallParams): CanonRuntimeControlRequest | null;
 /** Private rationale, when the model supplied one. Logged, never rendered. */
 export declare function readCodexNoReplyReason(params: CodexAppToolCallParams): string | undefined;
 /**

package/dist/codex-app-tools.js

@@ -89,12 +89,51 @@ function tool(name, description, inputSchema, deferLoading = true) {
  * the host's turn, not to the app-server bridge.
  */
 export const CODEX_NO_REPLY_TOOL_NAME = 'no_reply';
+export const CANON_RUNTIME_CONTROL_TOOL_NAME = 'canon_runtime_control';
 /**
  * What the model actually sees for the tool above, for prompt text that names
  * it (the group posture cue). Only meaningful on the app-server transport —
  * the `exec --json` transport registers no dynamic tools.
  */
 export const CODEX_NO_REPLY_MODEL_TOOL_NAME = `codex_app.${CODEX_NO_REPLY_TOOL_NAME}`;
+const CANON_RUNTIME_CONTROL_TOOL = tool(CANON_RUNTIME_CONTROL_TOOL_NAME, 'Interact with the current Canon conversation. Send a display card, request one card response, '
+    + 'or ask one short question. Canon binds the current conversation and authenticated responder; '
+    + 'never ask for or invent routing ids.', {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        action: {
+            type: 'string',
+            enum: ['send_card', 'request_card', 'request_input'],
+        },
+        card: {
+            type: 'object',
+            description: 'A canon.card.v1 document. Use request_card when it contains actions.',
+        },
+        prompt: {
+            type: 'string',
+            description: 'A short question for request_input.',
+        },
+        placeholder: {
+            type: 'string',
+            description: 'Optional example or formatting hint for request_input.',
+        },
+    },
+    required: ['action'],
+}, false);
+const CODEX_NO_REPLY_TOOL = tool(CODEX_NO_REPLY_TOOL_NAME, 'End your turn without posting anything to the conversation. Use it in group '
+    + 'chats when you have nothing to add — no message is created, so no other '
+    + 'member or agent is triggered. Optional private reason (logged, never '
+    + 'shown). After calling this, produce no further text.', {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        reason: {
+            type: 'string',
+            description: 'Never rendered; logged only.',
+        },
+    },
+}, false);
 export const CODEX_APP_DYNAMIC_TOOLS = [
     tool('automation_update', 'Create, update, view, or delete Codex app automations. Canon exposes the name for compatibility, but does not manage Desktop automations.', {
         type: 'object',
@@ -205,24 +244,23 @@ export const CODEX_APP_DYNAMIC_TOOLS = [
         },
         required: ['threadId', 'title'],
     }),
+    CANON_RUNTIME_CONTROL_TOOL,
     // Canon's `no_reply` verb, projected into the only model-visible tool surface
-    // the Codex transport gives us. It is answered by the Canon host itself (see
-    // `handleCodexServerRequest`), never by `handleCodexAppToolCall` — the host
-    // owns the turn this call is about.
-    tool(CODEX_NO_REPLY_TOOL_NAME, 'End your turn without posting anything to the conversation. Use it in group '
-        + 'chats when you have nothing to add — no message is created, so no other '
-        + 'member or agent is triggered. Optional private reason (logged, never '
-        + 'shown). After calling this, produce no further text.', {
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-            reason: {
-                type: 'string',
-                description: 'Never rendered; logged only.',
-            },
-        },
-    }, false),
+    // the Codex transport gives us. It is answered by the Canon host itself.
+    CODEX_NO_REPLY_TOOL,
+];
+/** The complete model-visible surface for non-coding service agents. */
+export const CODEX_SERVICE_AGENT_DYNAMIC_TOOLS = [
+    CANON_RUNTIME_CONTROL_TOOL,
+    CODEX_NO_REPLY_TOOL,
 ];
+/**
+ * Tools exposed to detached Codex threads created through the bridge. Canon
+ * conversation controls belong only to the foreground turn that received the
+ * human message; a child thread has neither that turn nor its responder.
+ */
+export const CODEX_DETACHED_THREAD_DYNAMIC_TOOLS = CODEX_APP_DYNAMIC_TOOLS.filter((entry) => (entry.name !== CANON_RUNTIME_CONTROL_TOOL_NAME
+    && entry.name !== CODEX_NO_REPLY_TOOL_NAME));
 const CODEX_APP_TOOL_NAMES = new Set(CODEX_APP_DYNAMIC_TOOLS.map((entry) => String(entry.name)));
 const UNSUPPORTED_TOOLS = new Map([
     ['automation_update', 'Canon does not manage Codex Desktop automations.'],
@@ -246,10 +284,38 @@ export function isCodexAppToolCall(params) {
 export function deniedCodexAppToolResult(reason) {
     return toolResult(false, { error: reason });
 }
+export function successfulCodexAppToolResult(payload) {
+    return toolResult(true, payload);
+}
 /** True when this dynamic-tool call is the deliberate-silence verb. */
 export function isCodexNoReplyToolCall(params) {
     return normalizeToolName(params.tool) === CODEX_NO_REPLY_TOOL_NAME;
 }
+export function isCanonRuntimeControlToolCall(params) {
+    return normalizeToolName(params.tool) === CANON_RUNTIME_CONTROL_TOOL_NAME;
+}
+export function isCodexServiceAgentToolCall(params) {
+    const toolName = normalizeToolName(params.tool);
+    return toolName === CANON_RUNTIME_CONTROL_TOOL_NAME || toolName === CODEX_NO_REPLY_TOOL_NAME;
+}
+export function parseCanonRuntimeControlRequest(params) {
+    if (!isCanonRuntimeControlToolCall(params))
+        return null;
+    const args = parseToolArguments(params.arguments);
+    const allowedKeys = new Set(['action', 'card', 'prompt', 'placeholder']);
+    if (Object.keys(args).some((key) => !allowedKeys.has(key)))
+        return null;
+    const action = readString(args, 'action');
+    if (action !== 'send_card' && action !== 'request_card' && action !== 'request_input') {
+        return null;
+    }
+    return {
+        action,
+        ...(args.card !== undefined ? { card: args.card } : {}),
+        ...(readString(args, 'prompt') ? { prompt: readString(args, 'prompt') } : {}),
+        ...(readString(args, 'placeholder') ? { placeholder: readString(args, 'placeholder') } : {}),
+    };
+}
 /** Private rationale, when the model supplied one. Logged, never rendered. */
 export function readCodexNoReplyReason(params) {
     const args = parseToolArguments(params.arguments);
@@ -314,6 +380,12 @@ export async function handleCodexAppToolCall(runtime, params) {
             error: 'no_reply is answered by the Canon host, not the app-tool bridge.',
         });
     }
+    if (toolName === CANON_RUNTIME_CONTROL_TOOL_NAME) {
+        return toolResult(false, {
+            tool: toolName,
+            error: 'canon_runtime_control is answered by the Canon host, not the app-tool bridge.',
+        });
+    }
     const unsupportedReason = UNSUPPORTED_TOOLS.get(toolName);
     if (unsupportedReason) {
         return toolResult(false, { tool: toolName, error: unsupportedReason });
@@ -366,7 +438,7 @@ async function createThread(runtime, args) {
     const started = await runtime.adapter.requestAppServer('thread/start', {
         cwd,
         ...(readString(args, 'model') ?? runtime.model ? { model: readString(args, 'model') ?? runtime.model } : {}),
-        dynamicTools: CODEX_APP_DYNAMIC_TOOLS,
+        dynamicTools: CODEX_DETACHED_THREAD_DYNAMIC_TOOLS,
         experimentalRawEvents: false,
         persistExtendedHistory: true,
     });

package/dist/host.d.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { type TurnArtifactRoutingDecision, type TurnArtifactRoutingMode } from '@canonmsg/coding-agent-host';
-import { type CanonRuntimeCommandDescriptor, type CanonRuntimeDescriptor, type CanonRuntimePresentationPolicy, type ExecutionEnvironmentMode, type WorkspaceOption, type CanonWorkspaceRootMetadata, type RuntimeStreamingPayload, type TurnLifecycleState, type TurnOutputBlock, type TurnVerbosity, type TurnVerbosityConfig } from '@canonmsg/core';
+import { type CanonRuntimeCommandDescriptor, type CanonRuntimeDescriptor, type CanonRuntimePresentationPolicy, type ExecutionEnvironmentMode, type PreparedExecutionEnvironment, type WorkspaceOption, type CanonWorkspaceRootMetadata, type RuntimeStreamingPayload, type TurnLifecycleState, type TurnOutputBlock, type TurnVerbosity, type TurnVerbosityConfig } from '@canonmsg/core';
+import { type CodexSandboxMode } from './adapter.js';
 import { type CodexSkillMetadata } from './app-server-adapter.js';
+import { deriveCodexPermissionEnvelope } from './permission-mode.js';
 import { type CodexControlOption } from './model-catalog.js';
 interface HostSessionState {
     lastError?: string;
@@ -68,6 +70,31 @@ export declare function getCodexRequestingUserId(message: {
     senderId: string;
     senderType?: 'human' | 'ai_agent';
 }): string | null;
+export declare function resolveSessionExecutionMode(config: {
+    executionMode?: ExecutionEnvironmentMode;
+} | null | undefined, serviceAgentMode?: boolean): ExecutionEnvironmentMode;
+export declare function resolveWorkspaceCwd(config: {
+    workspaceId?: string;
+    retiredWorkspaceConfig?: boolean;
+} | null, serviceAgentMode?: boolean): string;
+interface CodexEffectiveRuntimePolicy {
+    model?: string;
+    permissionMode?: string;
+    sandbox: CodexSandboxMode | null;
+    fullAuto: boolean;
+    bypassApprovalsAndSandbox: boolean;
+    fingerprint: string;
+}
+export declare function resolveCodexEffectiveRuntimePolicy(input: {
+    args: Record<string, unknown>;
+    config: {
+        model?: string;
+        permissionMode?: string;
+    } | null | undefined;
+    permissionEnvelope: ReturnType<typeof deriveCodexPermissionEnvelope>;
+    environment: Pick<PreparedExecutionEnvironment, 'baseCwd' | 'mode'>;
+    serviceAgentMode?: boolean;
+}): CodexEffectiveRuntimePolicy;
 /**
  * `--turn-verbosity` beats `CANON_TURN_VERBOSITY`; `null` means "unset, use the
  * per-conversation-type default".
@@ -137,6 +164,7 @@ export declare function planCodexStreamingWrite(input: {
  * same decision at its `text_delta` handler.
  */
 export declare function shouldStopTypingDotsOnStreamedText(turnVerbosity: TurnVerbosity): boolean;
+export declare function selectCodexNativeImagePaths(imagePaths: readonly string[], nativeVisionEnabled: boolean): string[];
 /**
  * Whether this turn may post the media it generated in the workspace.
  *

package/dist/host.js

@@ -6,10 +6,11 @@ import { dirname } from 'node:path';
 import { parseArgs } from 'node:util';
 import { getCodexImagePath, materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, } from '@canonmsg/agent-sdk';
 import { buildTrailBlockId, buildUndeliverableFinalNotice, captureTurnArtifactSnapshot, createTurnArtifactRouter, IDLE_TIMEOUT_MS, PLAN_BLOCK_TITLE, resolveTurnArtifactRouting, collectMissedInboundMessages, STARTUP_RECOVERY_MAX_MESSAGES, STARTUP_RECOVERY_PAGE_SIZE, } from '@canonmsg/coding-agent-host';
-import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, resolveQuestionAllowOther, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, buildCanonInboundFrameV1, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, decideAutoReply, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, markLocalRuntimeStopped, normalizeTurnMetadata, parseRuntimeCardV1, parseTurnVerbosityConfig, RuntimeRequestManager, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, verifyResolvedAgentEnvironment, CanonApiError, loadRuntimeSessionState, sendMessageWithRetry, sendMessageWithRetryChunked, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, isSilentTurnSuppressed, resolveSilentTurnDelivery, resolveTurnVerbosity, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, resolveQuestionAllowOther, buildCanonTurnContextV2, buildConfiguredWorkspaceOptionsWithRoots, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, diffCanonMemberIds, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, buildRuntimePresentationPolicy, buildCanonInboundFrameV1, DEFAULT_FIRST_PARTY_RUNTIME_PRESENTATION, createConversationMetadataLoader, createRuntimeStatePublisher, createTypingStatusPublisher, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfileLock, decideAutoReply, initRTDBAuth, buildLocalRuntimeId, heartbeatLocalRuntimeEntry, markLocalRuntimeStopped, normalizeTurnMetadata, parseTurnVerbosityConfig, RuntimeRequestManager, prepareConversationEnvironment, loadHostSessionConfig, releaseConversationEnvironment, resolveCanonAgent, verifyResolvedAgentEnvironment, CanonApiError, loadRuntimeSessionState, sendMessageWithRetry, sendMessageWithRetryChunked, saveRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, renderCodingHostInboundPrompt, resolveHostWorkspaceCwd, isSilentTurnSuppressed, resolveSilentTurnDelivery, resolveTurnVerbosity, shouldTriggerAgentTurn, upsertLocalRuntimeEntry, } from '@canonmsg/core';
+import { validateCard } from '@canonmsg/rich-cards';
 import { CodexConversationAdapter, } from './adapter.js';
 import { CodexAppServerAdapter, } from './app-server-adapter.js';
-import { CODEX_APP_DYNAMIC_TOOLS, CODEX_NO_REPLY_MODEL_TOOL_NAME, answerCodexNoReply, classifyCodexAppToolRequest, deniedCodexAppToolResult, handleCodexAppToolCall, isCodexAppToolCall, readCodexNoReplyReason, } from './codex-app-tools.js';
+import { CODEX_APP_DYNAMIC_TOOLS, CODEX_NO_REPLY_MODEL_TOOL_NAME, CODEX_SERVICE_AGENT_DYNAMIC_TOOLS, answerCodexNoReply, classifyCodexAppToolRequest, deniedCodexAppToolResult, handleCodexAppToolCall, isCanonRuntimeControlToolCall, isCodexAppToolCall, isCodexServiceAgentToolCall, parseCanonRuntimeControlRequest, readCodexNoReplyReason, successfulCodexAppToolResult, } from './codex-app-tools.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';
@@ -42,6 +43,8 @@ COMMON FLAGS
                                       How much of a turn's middle readers see.
                                       Default (auto): verbose in direct chats,
                                       quiet in groups. Env: CANON_TURN_VERBOSITY
+  --service-agent                     Expose Canon conversation tools, not coding tools
+  --no-native-vision                  Keep attachment paths but omit native image input
   --help, -h                           Show this help
   --version, -V                        Show package version
 
@@ -259,15 +262,17 @@ async function loadSessionConfig(conversationId, agentId, rtdb) {
         extraStringFields: CODEX_SESSION_CONFIG_FIELDS,
     });
 }
-function resolveSessionExecutionMode(config) {
+export function resolveSessionExecutionMode(config, serviceAgentMode = false) {
+    if (serviceAgentMode)
+        return 'locked';
     if (config?.executionMode)
         return config.executionMode;
     throw new ExecutionEnvironmentError('Session config is missing an execution mode.', 'Choose Isolated worktree or Use shared project before starting this coding session.');
 }
-function resolveWorkspaceCwd(config) {
+export function resolveWorkspaceCwd(config, serviceAgentMode = false) {
     return resolveHostWorkspaceCwd({
         workspaceOptions,
-        config,
+        config: serviceAgentMode ? null : config,
         defaultCwd: workingDir,
     });
 }
@@ -286,9 +291,11 @@ function stringArg(args, key) {
 function boolArg(args, key) {
     return args[key] === true;
 }
-function resolveCodexEffectiveRuntimePolicy(input) {
+export function resolveCodexEffectiveRuntimePolicy(input) {
     const model = input.config?.model ?? stringArg(input.args, 'model');
-    const permissionMode = input.config?.permissionMode ?? input.permissionEnvelope.defaultPermissionMode;
+    const permissionMode = input.serviceAgentMode
+        ? input.permissionEnvelope.defaultPermissionMode
+        : input.config?.permissionMode ?? input.permissionEnvelope.defaultPermissionMode;
     if (permissionMode
         && !input.permissionEnvelope.availablePermissionModes.some((option) => option.value === permissionMode)) {
         throw new ExecutionEnvironmentError(`Permission mode "${permissionMode}" is not supported by this Codex host.`, 'This Canon host was started with stricter approval settings. Choose one of the advertised permission modes or restart the host with more permissive flags.');
@@ -538,6 +545,9 @@ export function planCodexStreamingWrite(input) {
 export function shouldStopTypingDotsOnStreamedText(turnVerbosity) {
     return turnVerbosity !== 'quiet';
 }
+export function selectCodexNativeImagePaths(imagePaths, nativeVisionEnabled) {
+    return nativeVisionEnabled ? [...imagePaths] : [];
+}
 /**
  * Whether this turn may post the media it generated in the workspace.
  *
@@ -585,6 +595,8 @@ export async function main() {
             'show-runtime-detail': { type: 'string', multiple: true },
             'hide-runtime-detail': { type: 'string', multiple: true },
             'turn-verbosity': { type: 'string' },
+            'service-agent': { type: 'boolean' },
+            'no-native-vision': { type: 'boolean' },
             'full-auto': { type: 'boolean' },
             'dangerously-bypass-approvals-and-sandbox': { type: 'boolean' },
         },
@@ -600,6 +612,11 @@ export async function main() {
         env: process.env.CANON_TURN_VERBOSITY,
         onWarning: (message) => console.error(`[canon-codex] ${message}`),
     });
+    const serviceAgentMode = args['service-agent'] === true;
+    const nativeVisionEnabled = args['no-native-vision'] !== true;
+    const codexDynamicTools = serviceAgentMode
+        ? CODEX_SERVICE_AGENT_DYNAMIC_TOOLS
+        : CODEX_APP_DYNAMIC_TOOLS;
     workingDir = (typeof args.cwd === 'string' ? args.cwd : null) || process.cwd();
     const workspaceDiscovery = buildConfiguredWorkspaceOptionsWithRoots({
         primaryCwd: workingDir,
@@ -1116,6 +1133,8 @@ export async function main() {
         if (!session)
             return;
         session.closed = true;
+        session.currentTurnAbortController?.abort(new Error('Codex session closed'));
+        session.currentTurnAbortController = null;
         stopVisibleWorkSignal(session);
         if ('close' in session.adapter && typeof session.adapter.close === 'function') {
             session.adapter.close();
@@ -1139,6 +1158,7 @@ export async function main() {
         session.activeSelfContextId = null;
         session.state.lastError = undefined;
         if (session.running) {
+            session.currentTurnAbortController?.abort(new Error('Codex session reset'));
             await session.adapter.interrupt();
             session.turnState = 'interrupted';
         }
@@ -1186,8 +1206,8 @@ export async function main() {
         }
         const creation = (async () => {
             const config = await loadSessionConfig(conversationId, agentId, rtdb);
-            const sessionExecutionMode = resolveSessionExecutionMode(config);
-            const workspaceCwd = resolveWorkspaceCwd(config);
+            const sessionExecutionMode = resolveSessionExecutionMode(config, serviceAgentMode);
+            const workspaceCwd = resolveWorkspaceCwd(config, serviceAgentMode);
             const environment = prepareConversationEnvironment({
                 agentId,
                 conversationId,
@@ -1201,6 +1221,7 @@ export async function main() {
                     config,
                     permissionEnvelope: codexPermissionEnvelope,
                     environment,
+                    serviceAgentMode,
                 });
                 const modelGuard = buildCodexModelGuardMessage(policy.model, codexCliStatus);
                 if (modelGuard) {
@@ -1226,7 +1247,7 @@ export async function main() {
                         configOverrides: args.config ?? [],
                         fullAuto: policy.fullAuto,
                         bypassApprovalsAndSandbox: policy.bypassApprovalsAndSandbox,
-                        dynamicTools: CODEX_APP_DYNAMIC_TOOLS,
+                        dynamicTools: codexDynamicTools,
                     })
                     : new CodexConversationAdapter({
                         cwd: sessionCwd,
@@ -1259,6 +1280,7 @@ export async function main() {
                     currentTurnOpenedAt: null,
                     currentTurnUpdatedAt: null,
                     currentTurnCanUseCodexAppTools: false,
+                    currentTurnAbortController: null,
                     // Corrected by the first turn that runs; a session with no turn
                     // publishes nothing anyway, and quiet is never an accident.
                     turnVerbosity: 'verbose',
@@ -1333,7 +1355,10 @@ export async function main() {
         // No `turnVerbosity`: this prompt continues the same conversation, so it
         // keeps whatever the session last resolved rather than reverting to the
         // default.
-        enqueuePrompt(session, prompt, 'queue', false, result.receiptId ?? null, false, [], [], result.status !== 'approve', { requestingUserId: responseUserId });
+        enqueuePrompt(session, prompt, 'queue', false, result.receiptId ?? null, false, [], [], result.status !== 'approve', {
+            canUseCodexAppTools: serviceAgentMode || responseUserId === ownerId,
+            requestingUserId: responseUserId,
+        });
     }
     function resolveArtifactRoutingMode(participantContext) {
         return participantContext.conversationType === 'direct' && participantContext.isOwner
@@ -1349,7 +1374,7 @@ export async function main() {
     function resolveCodexTurnModes(participantContext, message) {
         return {
             artifactRoutingMode: resolveArtifactRoutingMode(participantContext),
-            canUseCodexAppTools: participantContext.isOwner,
+            canUseCodexAppTools: participantContext.isOwner || serviceAgentMode,
             turnVerbosity: resolveTurnVerbosity({
                 configured: configuredTurnVerbosity,
                 conversationType: participantContext.conversationType,
@@ -1371,6 +1396,9 @@ export async function main() {
         const params = request.params;
         const expiresAt = Date.now() + 30 * 60_000;
         if (request.method === 'item/tool/call' && isCodexAppToolCall(params)) {
+            if (serviceAgentMode && !isCodexServiceAgentToolCall(params)) {
+                return deniedCodexAppToolResult('This service agent exposes only Canon conversation tools.');
+            }
             // The admission order — no_reply above the owner gate — is pinned by
             // `classifyCodexAppToolRequest`'s tests, not by the shape of this block.
             const disposition = classifyCodexAppToolRequest({
@@ -1393,6 +1421,102 @@ export async function main() {
             if (disposition === 'denied-non-owner') {
                 return deniedCodexAppToolResult('Only the Canon owner can use codex_app tools.');
             }
+            if (isCanonRuntimeControlToolCall(params)) {
+                const command = parseCanonRuntimeControlRequest(params);
+                if (!command) {
+                    return deniedCodexAppToolResult('Invalid canon_runtime_control arguments.');
+                }
+                if (command.action === 'request_input') {
+                    if (!command.prompt) {
+                        return deniedCodexAppToolResult('request_input requires prompt.');
+                    }
+                    const responseRouting = buildCodexTurnResponseRouting({ requestingUserId, ownerId });
+                    const inputId = `codex_input_${randomUUID()}`;
+                    const question = command.placeholder
+                        ? `${command.prompt}\n\nFormat hint: ${command.placeholder}`
+                        : command.prompt;
+                    const response = await runtimeRequests.request('input', session.conversationId, {
+                        kind: 'clarify',
+                        title: 'Input requested',
+                        prompt: command.prompt,
+                        questions: [{ id: 'response', header: 'Response', question, allowOther: true }],
+                        ...(responseRouting.responseUserId
+                            ? { responseUserId: responseRouting.responseUserId }
+                            : {}),
+                        turnId: session.currentTurnId ?? undefined,
+                    }, {
+                        requestId: inputId,
+                        expiresAt,
+                        signal: session.currentTurnAbortController?.signal,
+                        onCreated: () => {
+                            session.turnState = 'waiting_input';
+                            markTurnProgress(session);
+                            stopVisibleWorkSignal(session);
+                            writeTurn(session);
+                            writeCodexStreaming(session, null, 'waiting_input');
+                        },
+                    });
+                    resumeTurnFromWaiting(session);
+                    return successfulCodexAppToolResult(response);
+                }
+                const validation = validateCard(command.card);
+                if (!validation.ok || !validation.card) {
+                    return deniedCodexAppToolResult(`Invalid canon.card.v1 card: ${validation.errors.join('; ')}`);
+                }
+                const card = validation.card;
+                const interactive = card.blocks.some((block) => block.kind === 'actions');
+                if (command.action === 'send_card') {
+                    if (interactive) {
+                        return deniedCodexAppToolResult('send_card cannot contain actions; use request_card.');
+                    }
+                    const cardId = card.cardId ?? `codex_card_${randomUUID()}`;
+                    const created = await client.createRuntimeCardRequest({
+                        conversationId: session.conversationId,
+                        card: { ...card, cardId },
+                        cardId,
+                        expiresAt,
+                        turnId: session.currentTurnId ?? undefined,
+                    });
+                    return successfulCodexAppToolResult({
+                        status: 'sent',
+                        cardId: created.cardId,
+                        messageId: created.messageId,
+                    });
+                }
+                if (!interactive) {
+                    return deniedCodexAppToolResult('request_card requires an actions block; use send_card.');
+                }
+                const cardId = card.cardId ?? `codex_card_${randomUUID()}`;
+                const responseRouting = buildCodexTurnResponseRouting({ requestingUserId, ownerId });
+                const response = await runtimeRequests.request('card', session.conversationId, {
+                    card,
+                    turnId: session.currentTurnId ?? undefined,
+                    ...(responseRouting.responseUserId
+                        ? { responseUserId: responseRouting.responseUserId }
+                        : {}),
+                }, {
+                    requestId: cardId,
+                    expiresAt,
+                    signal: session.currentTurnAbortController?.signal,
+                    onCreated: () => {
+                        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');
+                    },
+                });
+                completeTurnBlock(session, `card:${cardId}`, `Card ${response.status}`);
+                resumeTurnFromWaiting(session);
+                return successfulCodexAppToolResult(response);
+            }
             // `disposition` already ruled on the transport (it is checked first, so a
             // wrong transport never reaches the branches above). This repeats the
             // test only to narrow the adapter type for the bridge call.
@@ -1410,9 +1534,13 @@ export async function main() {
         }
         const runtimeCardPayload = runtimeCardRequestPayload(request.method, params);
         if (runtimeCardPayload) {
-            const card = parseRuntimeCardV1(runtimeCardPayload);
-            if (!card) {
-                return { status: 'cancelled', error: 'Invalid canon.card.v1 card' };
+            const validation = validateCard(runtimeCardPayload);
+            const card = validation.card;
+            if (!validation.ok || !card) {
+                return {
+                    status: 'cancelled',
+                    error: `Invalid canon.card.v1 card: ${validation.errors.join('; ')}`,
+                };
             }
             const cardId = readString(params, 'cardId')
                 ?? readString(params, 'itemId')
@@ -1443,6 +1571,7 @@ export async function main() {
                 }, {
                     requestId: cardId,
                     expiresAt,
+                    signal: session.currentTurnAbortController?.signal,
                     onCreated: () => {
                         requestCreated = true;
                         session.turnState = 'waiting_input';
@@ -1464,8 +1593,14 @@ export async function main() {
                         status: 'submitted',
                         ...(cardResult.actionId ? { actionId: cardResult.actionId } : {}),
                         ...(cardResult.values ? { values: cardResult.values } : {}),
+                        ...(cardResult.respondedBy ? { respondedBy: cardResult.respondedBy } : {}),
                     }
-                    : { status: cardResult.status };
+                    : {
+                        status: cardResult.status,
+                        ...('respondedBy' in cardResult && cardResult.respondedBy
+                            ? { respondedBy: cardResult.respondedBy }
+                            : {}),
+                    };
                 requestResolved = true;
                 const outcome = buildRuntimeCardOutcome(cardId, response.status, { reason: response.status });
                 await sendMessageWithRetry(client, session.conversationId, outcome.text, {
@@ -1535,7 +1670,11 @@ export async function main() {
                     },
                 },
                 turnId: session.currentTurnId ?? undefined,
-            }, { requestId: inputId, expiresAt });
+            }, {
+                requestId: inputId,
+                expiresAt,
+                signal: session.currentTurnAbortController?.signal,
+            });
             resumeTurnFromWaiting(session);
             return { answers: response.status === 'submitted' ? response.answers ?? {} : {} };
         }
@@ -1554,7 +1693,11 @@ export async function main() {
                     ? { responseUserId: responseRouting.responseUserId }
                     : {}),
                 allowSessionRule: responseRouting.allowSessionRule,
-            }, { requestId: approvalId, expiresAt });
+            }, {
+                requestId: approvalId,
+                expiresAt,
+                signal: session.currentTurnAbortController?.signal,
+            });
             resumeTurnFromWaiting(session);
             if (request.method === 'item/permissions/requestApproval') {
                 return response.decision === 'allow'
@@ -1595,7 +1738,7 @@ export async function main() {
                     ? `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', {
-                canUseCodexAppTools: input.isOwner,
+                canUseCodexAppTools: input.isOwner || serviceAgentMode,
                 requestingUserId: getCodexRequestingUserId(input.message),
             });
             return;
@@ -1642,9 +1785,10 @@ export async function main() {
         });
         const replyContext = replyMedia.replyContext;
         const promptMaterialized = [...replyMedia.materialized, ...materialized];
-        const imagePaths = promptMaterialized
+        const discoveredImagePaths = promptMaterialized
             .map((attachment) => getCodexImagePath(attachment))
             .filter((path) => path !== null);
+        const imagePaths = selectCodexNativeImagePaths(discoveredImagePaths, nativeVisionEnabled);
         const mediaAddDirs = uniqueStrings(promptMaterialized.map((attachment) => dirname(attachment.path)));
         const participantContext = hydrated.participantContext;
         const autoReply = input.turnDispatch?.kind === 'run_turn'
@@ -1698,6 +1842,7 @@ export async function main() {
         if (session.running && deliveryIntent === 'interrupt') {
             enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths, mediaAddDirs, planCommand.planMode, resolveCodexTurnModes(participantContext, input.message));
             console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Interrupting current turn for explicit human send-now`);
+            session.currentTurnAbortController?.abort(new Error('Codex turn interrupted by a newer message'));
             await session.adapter.interrupt().catch(() => { });
             clearStreaming(input.conversationId);
             typingSignals.clear(input.conversationId).catch(() => { });
@@ -1734,6 +1879,7 @@ export async function main() {
         session.currentTurnOpenedAt = Date.now();
         session.currentTurnUpdatedAt = session.currentTurnOpenedAt;
         session.currentTurnCanUseCodexAppTools = nextTurn.canUseCodexAppTools === true;
+        session.currentTurnAbortController = new AbortController();
         // A continuation prompt (a plan-review result) carries none, and keeps the
         // conversation's last answer rather than silently reverting to verbose.
         session.turnVerbosity = nextTurn.turnVerbosity ?? session.turnVerbosity;
@@ -2135,6 +2281,8 @@ export async function main() {
             console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] Turn failed:`, error);
         }
         finally {
+            session.currentTurnAbortController?.abort(new Error('Codex turn ended'));
+            session.currentTurnAbortController = null;
             persistInboundRecoveryCursor(session.conversationId, nextTurn.sourceMessageId);
             if (session.pendingDroppedRecoveryCursor) {
                 persistInboundRecoveryCursor(session.conversationId, session.pendingDroppedRecoveryCursor);
@@ -2184,10 +2332,10 @@ export async function main() {
         }
     }
     let streamConnected = false;
-    const hostAvailableExecutionModes = [
-        ...EXECUTION_ENVIRONMENT_MODES,
-    ];
-    const codexPermissionEnvelope = deriveCodexPermissionEnvelope(args);
+    const hostAvailableExecutionModes = serviceAgentMode
+        ? ['locked']
+        : [...EXECUTION_ENVIRONMENT_MODES];
+    const codexPermissionEnvelope = deriveCodexPermissionEnvelope(serviceAgentMode ? { sandbox: 'read-only' } : args);
     const configuredCodexEffort = readCodexConfiguredEffort(args.config ?? []);
     let codexModels = [];
     let codexModelOptions = buildCodexModelOptions(codexModels, args.model);
@@ -2345,6 +2493,7 @@ export async function main() {
             rememberDroppedRecoveryCursor(session, droppedPrompts);
         }
         if (session.running) {
+            session.currentTurnAbortController?.abort(new Error(`Codex turn interrupted by ${type}`));
             await session.adapter.interrupt();
         }
         session.turnState = 'interrupted';
@@ -2666,6 +2815,9 @@ export async function main() {
         controlPoller.stop();
         clearInterval(heartbeat);
         clearInterval(idleCheck);
+        for (const session of sessions.values()) {
+            session.currentTurnAbortController?.abort(new Error('Codex host shutting down'));
+        }
         runtimeRequests.dispose();
         stream.stop();
         await runtimeState.clearAgentRuntime().catch(() => { });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.25.1",
+  "version": "0.26.1",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "scripts"
   ],
   "scripts": {
-    "prepare:workspace-deps": "node ../../scripts/run-workspace-prep.mjs ../core ../agent-sdk ../coding-agent-host",
+    "prepare:workspace-deps": "node ../../scripts/run-workspace-prep.mjs ../core ../agent-sdk ../coding-agent-host ../rich-cards",
     "build": "npm run prepare:workspace-deps && node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "npm run prepare:workspace-deps && tsc --watch",
     "smoke": "node scripts/smoke-test.mjs",
@@ -31,7 +31,8 @@
   "dependencies": {
     "@canonmsg/agent-sdk": "^8.3.0",
     "@canonmsg/coding-agent-host": "^0.5.0",
-    "@canonmsg/core": "^10.2.0"
+    "@canonmsg/core": "^10.3.1",
+    "@canonmsg/rich-cards": "^0.10.0"
   },
   "engines": {
     "node": ">=18.0.0"