@canonmsg/claude-code-plugin 0.8.0 → 0.9.0

package/dist/host-runtime.d.ts

@@ -49,7 +49,27 @@ 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 and other
+ * binary attachments are referenced by short placeholders — their actual
+ * bytes are delivered to the host as native vision/media inputs (Anthropic
+ * image blocks, Codex `-i` file args). 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 blocks carry the
+ * bytes 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,57 @@ 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 and other
+ * binary attachments are referenced by short placeholders — their actual
+ * bytes are delivered to the host as native vision/media inputs (Anthropic
+ * image blocks, Codex `-i` file args). 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 blocks carry the
+ * bytes 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

@@ -24,7 +24,8 @@ setDefaultResultOrder('ipv4first');
 import { parseArgs } from 'node:util';
 import { randomUUID } from 'node:crypto';
 import { query } from '@anthropic-ai/claude-agent-sdk';
-import { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildPublicWorkspaceOptions, isEnabledFlag, CanonClient, CanonStream, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, rtdbRead, rtdbWrite, writeSessionState, clearSessionState, writeTurnState, releaseConversationEnvironment, } from '@canonmsg/core';
+import { isAnthropicImageAttachment, materializeMessageMedia, toAnthropicImageBlock, } from '@canonmsg/agent-sdk';
+import { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, CanonClient, CanonStream, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, rtdbRead, rtdbWrite, writeSessionState, clearSessionState, writeTurnState, releaseConversationEnvironment, } from '@canonmsg/core';
 import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 let workingDir = process.cwd();
@@ -50,6 +51,14 @@ async function loadSessionConfig(conversationId, agentId) {
         permissionMode: config?.permissionMode,
     };
 }
+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,
@@ -105,8 +114,28 @@ function buildCanonPrompt(input) {
         ...input,
     });
 }
-function renderInboundContent(message) {
-    return renderCanonHostInboundContent(message);
+function renderInboundContent(message, materialized) {
+    return renderCanonHostInboundContent(message, materialized);
+}
+/**
+ * Build the multimodal `content` payload handed to the Claude Code SDK.
+ *
+ * Images are delivered as native Anthropic `image` blocks (base64) so the
+ * vision model sees pixels, not a text reference to a URL. Non-image
+ * attachments (audio, files) are referenced by their local path inside the
+ * text prompt — see `renderCanonHostInboundContent` — so the agent can
+ * Read them on demand.
+ */
+async function buildCanonUserContent(input) {
+    const imageAttachments = input.materialized.filter(isAnthropicImageAttachment);
+    if (imageAttachments.length === 0) {
+        return input.promptText;
+    }
+    const imageBlocks = await Promise.all(imageAttachments.map((attachment) => toAnthropicImageBlock(attachment)));
+    return [
+        { type: 'text', text: input.promptText },
+        ...imageBlocks,
+    ];
 }
 // ── Session factory ─────────────────────────────────────────────────
 function createSession(conversationId, environment, agentId, client, onSessionEnd, onRuntimeDescriptorUpdate, config, resumeSessionId) {
@@ -612,6 +641,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                 defaultPermissionMode: 'default',
                 availableModels: modelList,
                 availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+                availableExecutionModes: config.availableExecutionModes,
             });
             writeSessionState(conversationId, agentId, {
                 ...session.state,
@@ -674,10 +704,14 @@ async function main() {
         console.error(`[canon-host] Authenticated as ${agentId}`);
     }
     let streamConnected = false;
+    const hostAvailableExecutionModes = allowWorktrees
+        ? [...EXECUTION_ENVIRONMENT_MODES]
+        : ['locked'];
     let runtimeDescriptor = {
         defaultWorkspaceId: workspaceOptions[0]?.id,
         defaultPermissionMode: 'default',
         availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+        availableExecutionModes: hostAvailableExecutionModes,
     };
     const publishRuntimeHeartbeat = async () => {
         if (!streamConnected)
@@ -695,6 +729,7 @@ async function main() {
             defaultPermissionMode: 'default',
             availableModels: runtimeModels,
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     catch {
@@ -702,6 +737,7 @@ async function main() {
             defaultWorkspaceId: workspaceOptions[0]?.id,
             defaultPermissionMode: 'default',
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     try {
@@ -794,12 +830,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 resumeKey = buildConversationEnvironmentKey(conversationId, environment.baseCwd);
@@ -823,6 +863,7 @@ async function main() {
                     model: config?.model ?? runtimeModels[0]?.value,
                     permissionMode: config?.permissionMode ?? 'default',
                     availableModels: runtimeModels,
+                    availableExecutionModes: hostAvailableExecutionModes,
                 }, resumeId);
                 sessions.set(conversationId, session);
                 return session;
@@ -863,9 +904,24 @@ async function main() {
                     }
                 }
                 const sender = m.senderName || m.senderId;
-                const content = renderInboundContent(m);
                 const isOwner = m.isOwner ?? (ownerId != null && m.senderId === ownerId);
                 void (async () => {
+                    let materialized = [];
+                    if (m.id) {
+                        try {
+                            materialized = await materializeMessageMedia({
+                                id: m.id,
+                                attachments: m.attachments,
+                                imageUrl: m.imageUrl ?? null,
+                                audioUrl: m.audioUrl ?? null,
+                                audioDurationMs: m.audioDurationMs ?? null,
+                            }, { agentId, conversationId: convoId });
+                        }
+                        catch (error) {
+                            console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to materialize media:`, error instanceof Error ? error.message : error);
+                        }
+                    }
+                    const content = renderInboundContent(m, materialized);
                     const hydrated = await loadHydratedInboundContext({
                         conversationId: convoId,
                         message: m,
@@ -899,18 +955,20 @@ async function main() {
                     const turnMetadata = normalizeTurnMetadata(m.metadata);
                     const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
                     const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
+                    const promptText = buildCanonPrompt({
+                        content,
+                        conversationId: convoId,
+                        participantContext,
+                        behavior,
+                        workSession: m.workSession,
+                        workSessions,
+                    });
+                    const messageContent = await buildCanonUserContent({ promptText, materialized });
                     session.enqueueInbound({
                         type: 'user',
                         message: {
                             role: 'user',
-                            content: buildCanonPrompt({
-                                content,
-                                conversationId: convoId,
-                                participantContext,
-                                behavior,
-                                workSession: m.workSession,
-                                workSessions,
-                            }),
+                            content: messageContent,
                         },
                         parent_tool_use_id: null,
                     }, deliveryIntent, m.id ?? null, shouldMarkAccepted);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/server.js",
@@ -23,6 +23,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.101",
+    "@canonmsg/agent-sdk": "^0.8.0",
     "@canonmsg/core": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.12.0"
   },