@canonmsg/codex-plugin 0.5.0 → 0.6.0

package/dist/adapter.d.ts

@@ -63,7 +63,7 @@ export declare class CodexConversationAdapter {
     setModel(model: string | null): void;
     isRunning(): boolean;
     interrupt(): Promise<void>;
-    runTurn(prompt: string, onEvent: (event: CodexEvent) => void, onLog?: (line: string) => void): Promise<CodexTurnResult>;
+    runTurn(prompt: string, onEvent: (event: CodexEvent) => void, onLog?: (line: string) => void, imagePaths?: readonly string[]): Promise<CodexTurnResult>;
     private buildArgs;
     private clearActiveProcess;
 }

package/dist/adapter.js

@@ -47,11 +47,11 @@ export class CodexConversationAdapter {
                 this.child.kill('SIGKILL');
         }, 5_000);
     }
-    async runTurn(prompt, onEvent, onLog) {
+    async runTurn(prompt, onEvent, onLog, imagePaths = []) {
         if (this.child) {
             throw new Error('A Codex turn is already in progress for this conversation');
         }
-        const args = this.buildArgs(prompt);
+        const args = this.buildArgs(prompt, imagePaths);
         const child = spawn(this.codexBin, args, {
             cwd: this.cwd,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -141,7 +141,7 @@ export class CodexConversationAdapter {
             });
         });
     }
-    buildArgs(prompt) {
+    buildArgs(prompt, imagePaths = []) {
         if (this.threadId) {
             const args = ['exec', 'resume', '--json', '--skip-git-repo-check'];
             if (this.model) {
@@ -159,6 +159,9 @@ export class CodexConversationAdapter {
             if (this.bypassApprovalsAndSandbox) {
                 args.push('--dangerously-bypass-approvals-and-sandbox');
             }
+            for (const imagePath of imagePaths) {
+                args.push('-i', imagePath);
+            }
             args.push(this.threadId, prompt);
             return args;
         }
@@ -190,6 +193,9 @@ export class CodexConversationAdapter {
         if (execMode.bypassApprovalsAndSandbox) {
             args.push('--dangerously-bypass-approvals-and-sandbox');
         }
+        for (const imagePath of imagePaths) {
+            args.push('-i', imagePath);
+        }
         args.push(prompt);
         return args;
     }

package/dist/host-runtime.d.ts

@@ -49,7 +49,26 @@ export declare function buildCanonHostPrompt(input: {
     workSessions?: MessageCreatedPayload['workSessions'];
     buildInboundContextLines: (context: HostInboundParticipantContext) => string[];
 }): string;
-export declare function renderCanonHostInboundContent(message: HostInboundMessage): string;
+/**
+ * Render the **text portion** of an inbound Canon message. Images are
+ * referenced by short placeholders — their actual bytes are delivered to the
+ * host as native vision/media inputs (Codex `-i <file>`, Anthropic image
+ * blocks). URLs are intentionally *not* inlined, since the harness never
+ * needs to refetch and earlier `[Image: <url>]` inlining caused vision
+ * models to see a string about an image instead of the image itself.
+ *
+ * `materialized` may be passed so non-image attachments can reference a
+ * local path the agent can Read. Without it we fall back to an unadorned
+ * placeholder; the vision path still works because image args carry the
+ * file path directly.
+ */
+export declare function renderCanonHostInboundContent(message: HostInboundMessage, materialized?: ReadonlyArray<{
+    kind: 'image' | 'audio' | 'file';
+    path: string;
+    fileName?: string;
+    durationMs?: number;
+    index: number;
+}>): string;
 export declare function buildHydratedInboundContext(input: {
     agentId: string;
     conversation: CanonConversation | null;

package/dist/host-runtime.js

@@ -32,38 +32,56 @@ export function buildCanonHostPrompt(input) {
         input.content,
     ].join('\n');
 }
-export function renderCanonHostInboundContent(message) {
-    let content = message.text || '';
-    const attachment = message.attachments?.[0];
-    if (attachment?.kind === 'audio' && attachment.url) {
-        const duration = attachment.durationMs ? ` (${Math.round(attachment.durationMs / 1000)}s)` : '';
-        content = content
-            ? `[Voice message${duration}: ${attachment.url}]\n${content}`
-            : `[Voice message${duration}: ${attachment.url}]`;
-    }
-    else if (attachment?.kind === 'image' && attachment.url) {
-        content = content
-            ? `[Image: ${attachment.url}]\n${content}`
-            : `[Image: ${attachment.url}]`;
-    }
-    else if (attachment?.kind === 'file' && attachment.url) {
-        const label = attachment.fileName || 'File';
-        content = content
-            ? `[File: ${label} ${attachment.url}]\n${content}`
-            : `[File: ${label} ${attachment.url}]`;
+/**
+ * Render the **text portion** of an inbound Canon message. Images are
+ * referenced by short placeholders — their actual bytes are delivered to the
+ * host as native vision/media inputs (Codex `-i <file>`, Anthropic image
+ * blocks). URLs are intentionally *not* inlined, since the harness never
+ * needs to refetch and earlier `[Image: <url>]` inlining caused vision
+ * models to see a string about an image instead of the image itself.
+ *
+ * `materialized` may be passed so non-image attachments can reference a
+ * local path the agent can Read. Without it we fall back to an unadorned
+ * placeholder; the vision path still works because image args carry the
+ * file path directly.
+ */
+export function renderCanonHostInboundContent(message, materialized) {
+    const body = message.text || '';
+    const placeholders = [];
+    const attachments = message.attachments ?? [];
+    if (attachments.length > 0) {
+        for (let i = 0; i < attachments.length; i += 1) {
+            const att = attachments[i];
+            const mat = materialized?.find((m) => m.index === i) ?? null;
+            placeholders.push(describeAttachment(att, mat));
+        }
     }
     else if (message.contentType === 'audio' && message.audioUrl) {
-        const duration = message.audioDurationMs ? ` (${Math.round(message.audioDurationMs / 1000)}s)` : '';
-        content = content
-            ? `[Voice message${duration}: ${message.audioUrl}]\n${content}`
-            : `[Voice message${duration}: ${message.audioUrl}]`;
+        const duration = message.audioDurationMs
+            ? ` (${Math.round(message.audioDurationMs / 1000)}s)`
+            : '';
+        placeholders.push(`[Voice message${duration}]`);
     }
     else if (message.contentType === 'image' && message.imageUrl) {
-        content = content
-            ? `[Image: ${message.imageUrl}]\n${content}`
-            : `[Image: ${message.imageUrl}]`;
+        placeholders.push('[Image attached]');
+    }
+    const rendered = [...placeholders, body].filter(Boolean).join('\n');
+    return rendered || '[Empty message]';
+}
+function describeAttachment(attachment, materialized) {
+    if (attachment.kind === 'image') {
+        return '[Image attached]';
+    }
+    if (attachment.kind === 'audio') {
+        const durationMs = materialized?.durationMs ?? attachment.durationMs;
+        const duration = durationMs ? ` (${Math.round(durationMs / 1000)}s)` : '';
+        const ref = materialized?.path ? ` ${materialized.path}` : '';
+        return `[Voice message${duration}${ref}]`;
     }
-    return content || '[Empty message]';
+    // file
+    const label = materialized?.fileName ?? attachment.fileName ?? 'File';
+    const ref = materialized?.path ? ` ${materialized.path}` : '';
+    return `[File: ${label}${ref}]`;
 }
 export function buildHydratedInboundContext(input) {
     const history = buildParticipationHistorySnapshot(input.page?.messages ?? [], input.agentId);

package/dist/host.js

@@ -3,7 +3,8 @@ import { setDefaultResultOrder } from 'node:dns';
 setDefaultResultOrder('ipv4first');
 import { randomUUID } from 'node:crypto';
 import { parseArgs } from 'node:util';
-import { buildConfiguredWorkspaceOptions, buildPublicWorkspaceOptions, ExecutionEnvironmentError, isEnabledFlag, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfile, initRTDBAuth, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseLock, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, writeSessionState, writeTurnState, } from '@canonmsg/core';
+import { getCodexImagePath, materializeMessageMedia, } from '@canonmsg/agent-sdk';
+import { buildConfiguredWorkspaceOptions, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, ExecutionEnvironmentError, isEnabledFlag, CanonClient, CanonStream, clearSessionState, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, getActiveProfile, initRTDBAuth, normalizeTurnMetadata, normalizeTurnState, prepareConversationEnvironment, releaseLock, releaseConversationEnvironment, resolveCanonAgent, rtdbRead, rtdbWrite, shouldTriggerAgentTurn, writeSessionState, writeTurnState, } from '@canonmsg/core';
 import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { CodexConversationAdapter, } from './adapter.js';
@@ -43,6 +44,14 @@ async function publishAgentRuntime(agentId, runtime) {
 async function loadSessionConfig(conversationId, agentId) {
     return loadHostSessionConfig({ conversationId, agentId });
 }
+const SESSION_EXECUTION_MODE_REQUIRED = 'Session execution mode required; please select a mode before starting the session.';
+function requireSessionExecutionMode(config) {
+    const mode = config?.executionMode;
+    if (!mode) {
+        throw new ExecutionEnvironmentError(SESSION_EXECUTION_MODE_REQUIRED, SESSION_EXECUTION_MODE_REQUIRED);
+    }
+    return mode;
+}
 function resolveWorkspaceCwd(config) {
     return resolveHostWorkspaceCwd({
         workspaceOptions,
@@ -57,8 +66,8 @@ function buildCanonPrompt(input) {
         ...input,
     });
 }
-function renderInboundContent(message) {
-    return renderCanonHostInboundContent(message);
+function renderInboundContent(message, materialized) {
+    return renderCanonHostInboundContent(message, materialized);
 }
 function summarizeCommand(command) {
     const trimmed = command.trim();
@@ -241,12 +250,16 @@ async function main() {
         }
         const creation = (async () => {
             const config = await loadSessionConfig(conversationId, agentId);
+            const sessionExecutionMode = requireSessionExecutionMode(config);
+            if (sessionExecutionMode === 'worktree' && !allowWorktrees) {
+                throw new ExecutionEnvironmentError('This host does not allow worktree sessions (launched without --enable-worktrees).', 'This Canon host was started without worktree isolation enabled. Choose "Lock the workspace" or restart the host with --enable-worktrees.');
+            }
             const workspaceCwd = resolveWorkspaceCwd(config);
             const environment = prepareConversationEnvironment({
                 agentId,
                 conversationId,
                 workspaceCwd,
-                allowWorktrees,
+                allowWorktrees: sessionExecutionMode === 'worktree',
             });
             try {
                 const sessionCwd = environment.cwd;
@@ -303,8 +316,8 @@ async function main() {
             pendingSessionCreations.delete(conversationId);
         }
     }
-    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false) {
-        const nextPrompt = { prompt, intent, sourceMessageId, markAccepted };
+    function enqueuePrompt(session, prompt, intent = 'queue', toFront = false, sourceMessageId, markAccepted = false, imagePaths = []) {
+        const nextPrompt = { prompt, intent, sourceMessageId, markAccepted, imagePaths };
         if (toFront) {
             session.queue.unshift(nextPrompt);
         }
@@ -316,7 +329,25 @@ async function main() {
         void runNextTurn(session);
     }
     async function enqueueInboundMessage(input) {
-        const content = renderInboundContent(input.message);
+        let materialized = [];
+        if (input.message.id) {
+            try {
+                materialized = await materializeMessageMedia({
+                    id: input.message.id,
+                    attachments: input.message.attachments,
+                    imageUrl: input.message.imageUrl ?? null,
+                    audioUrl: input.message.audioUrl ?? null,
+                    audioDurationMs: input.message.audioDurationMs ?? null,
+                }, { agentId, conversationId: input.conversationId });
+            }
+            catch (error) {
+                console.error(`[canon-codex] [${input.conversationId.slice(0, 8)}] Failed to materialize media:`, error instanceof Error ? error.message : error);
+            }
+        }
+        const imagePaths = materialized
+            .map((attachment) => getCodexImagePath(attachment))
+            .filter((path) => path !== null);
+        const content = renderInboundContent(input.message, materialized);
         const hydrated = await loadHydratedInboundContext({
             conversationId: input.conversationId,
             message: input.message,
@@ -360,14 +391,14 @@ async function main() {
             workSessions,
         });
         if (session.running && deliveryIntent === 'interrupt') {
-            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted);
+            enqueuePrompt(session, prompt, deliveryIntent, true, input.message.id, shouldMarkAccepted, imagePaths);
             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);
+        enqueuePrompt(session, prompt, deliveryIntent, false, input.message.id, shouldMarkAccepted, imagePaths);
     }
     async function runNextTurn(session) {
         if (session.running || session.closed)
@@ -393,6 +424,7 @@ async function main() {
             updatedAt: { '.sv': 'timestamp' },
         }).catch(() => { });
         try {
+            const turnImagePaths = nextTurn.imagePaths ?? [];
             const result = await session.adapter.runTurn(nextTurn.prompt, (event) => {
                 session.lastActivity = Date.now();
                 if (event.type === 'thread.started') {
@@ -426,7 +458,7 @@ async function main() {
                 }
             }, (line) => {
                 console.error(`[canon-codex] [${session.conversationId.slice(0, 8)}] ${line}`);
-            });
+            }, turnImagePaths);
             if (result.threadId) {
                 saveStoredThreadId(agentId, session.conversationId, session.cwd, result.threadId);
             }
@@ -503,10 +535,14 @@ async function main() {
     }
     let controlStopped = false;
     let streamConnected = false;
+    const hostAvailableExecutionModes = allowWorktrees
+        ? [...EXECUTION_ENVIRONMENT_MODES]
+        : ['locked'];
     let runtimeDescriptor = {
         defaultWorkspaceId: workspaceOptions[0]?.id,
         ...(typeof args.model === 'string' ? { defaultModel: args.model } : {}),
         availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+        availableExecutionModes: hostAvailableExecutionModes,
     };
     const publishRuntimeHeartbeat = async () => {
         if (!streamConnected)
@@ -550,12 +586,14 @@ async function main() {
             defaultWorkspaceId: workspaceOptions[0]?.id,
             ...(typeof args.model === 'string' ? { defaultModel: args.model } : {}),
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     catch {
         runtimeDescriptor = {
             defaultWorkspaceId: workspaceOptions[0]?.id,
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/codex-plugin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Canon host integration for Codex CLI",
   "type": "module",
   "main": "dist/host.js",
@@ -22,6 +22,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
+    "@canonmsg/agent-sdk": "^0.8.0",
     "@canonmsg/core": "^0.7.0"
   },
   "engines": {