@canonmsg/claude-code-plugin 0.8.0 → 0.9.1

package/dist/host-runtime.d.ts

@@ -28,9 +28,6 @@ export interface HostInboundParticipantContext {
 type HostInboundMessage = {
     text?: string | null;
     contentType?: CanonMessage['contentType'] | null;
-    audioUrl?: string | null;
-    audioDurationMs?: number | null;
-    imageUrl?: string | null;
     attachments?: CanonMessage['attachments'];
     senderType?: CanonMessage['senderType'];
     mentions?: string[] | null;
@@ -49,7 +46,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,46 @@ 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 ?? [];
+    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 rendered = [...placeholders, body].filter(Boolean).join('\n');
+    return rendered || '[Empty message]';
+}
+function describeAttachment(attachment, materialized) {
+    if (attachment.kind === 'image') {
+        return '[Image attached]';
     }
-    else if (message.contentType === 'image' && message.imageUrl) {
-        content = content
-            ? `[Image: ${message.imageUrl}]\n${content}`
-            : `[Image: ${message.imageUrl}]`;
+    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,9 +24,11 @@ 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';
+import { createStreamingBuffer } from './streaming-buffer.js';
 let workingDir = process.cwd();
 let workspaceOptions = [];
 let runtimeModels = [];
@@ -50,6 +52,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 +115,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) {
@@ -270,31 +300,33 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         sdkSessionId: resumeSessionId || null,
         pendingReply: null,
     };
+    const streamingBuffer = createStreamingBuffer({
+        throttleMs: STREAMING_THROTTLE_MS,
+        getText: () => session.streamingText,
+        setText: (text) => {
+            session.streamingText = text;
+        },
+        getTimer: () => session.streamingTimer,
+        setTimer: (timer) => {
+            session.streamingTimer = timer;
+        },
+        onWrite: (text) => {
+            rtdbWrite(`/streaming/${conversationId}/${agentId}`, {
+                text,
+                status: 'streaming',
+                updatedAt: { '.sv': 'timestamp' },
+            }).catch(() => { });
+        },
+    });
     // ── Per-session streaming helpers ──
     function flushStreaming() {
-        if (!session.streamingText)
-            return;
-        rtdbWrite(`/streaming/${conversationId}/${agentId}`, {
-            text: session.streamingText,
-            status: 'streaming',
-            updatedAt: { '.sv': 'timestamp' },
-        }).catch(() => { });
+        streamingBuffer.flush();
     }
     function onStreamDelta(text) {
-        session.streamingText += text;
-        if (!session.streamingTimer) {
-            session.streamingTimer = setTimeout(() => {
-                session.streamingTimer = null;
-                flushStreaming();
-            }, STREAMING_THROTTLE_MS);
-        }
+        streamingBuffer.append(text);
     }
     function clearStreaming() {
-        if (session.streamingTimer) {
-            clearTimeout(session.streamingTimer);
-            session.streamingTimer = null;
-        }
-        session.streamingText = '';
+        streamingBuffer.clear();
         rtdbWrite(`/streaming/${conversationId}/${agentId}`, null).catch(() => { });
     }
     function clearIdleResetTimer() {
@@ -338,8 +370,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         session.pendingFinalDeliveryText = finalText;
         session.state.state = 'running';
         session.turnState = 'streaming';
-        session.streamingText = finalText;
-        flushStreaming();
+        streamingBuffer.replace(finalText);
         writeState();
         writeTurn();
         client.setTyping(conversationId, true, 'typing').catch(() => { });
@@ -612,6 +643,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 +706,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 +731,7 @@ async function main() {
             defaultPermissionMode: 'default',
             availableModels: runtimeModels,
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     catch {
@@ -702,6 +739,7 @@ async function main() {
             defaultWorkspaceId: workspaceOptions[0]?.id,
             defaultPermissionMode: 'default',
             availableWorkspaces: buildPublicWorkspaceOptions(workspaceOptions),
+            availableExecutionModes: hostAvailableExecutionModes,
         };
     }
     try {
@@ -747,6 +785,8 @@ async function main() {
         }
         if (session.streamingTimer)
             clearTimeout(session.streamingTimer);
+        session.streamingText = '';
+        rtdbWrite(`/streaming/${conversationId}/${agentId}`, null).catch(() => { });
         if (session.idleResetTimer) {
             clearTimeout(session.idleResetTimer);
             session.idleResetTimer = null;
@@ -755,7 +795,6 @@ async function main() {
             clearTimeout(session.finalDeliveryTimer);
             session.finalDeliveryTimer = null;
         }
-        rtdbWrite(`/streaming/${conversationId}/${agentId}`, null).catch(() => { });
         clearSessionState(conversationId, agentId).catch(() => { });
         clearTurnState(conversationId, agentId).catch(() => { });
         client.setTyping(conversationId, false).catch(() => { });
@@ -794,12 +833,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 +866,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 +907,21 @@ 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 ?? [],
+                            }, { 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/dist/server.js

@@ -32,36 +32,31 @@ function getPrimaryAttachment(message) {
     const attachment = message.attachments?.[0];
     if (attachment?.url)
         return attachment;
-    if (message.audioUrl) {
-        return {
-            kind: 'audio',
-            url: message.audioUrl,
-            durationMs: message.audioDurationMs,
-        };
-    }
-    if (message.imageUrl) {
-        return {
-            kind: 'image',
-            url: message.imageUrl,
-        };
-    }
     return null;
 }
 function renderInboundContent(message) {
-    let content = message.text || '';
+    const content = message.text || '';
     const attachment = getPrimaryAttachment(message);
+    // MCP channel mode does not yet materialize media into local files. Surface
+    // a placeholder that tells the model media *was* attached without inlining a
+    // Firebase Storage URL: the model cannot fetch it, and reasoning about a
+    // URL-as-string leads to hallucinated image descriptions. The `attachment_*`
+    // fields on the structured `meta` sidechannel still carry the URL for UI /
+    // telemetry consumers.
+    let placeholder = null;
     if (attachment?.kind === 'audio') {
         const duration = attachment.durationMs ? ` (${Math.round(attachment.durationMs / 1000)}s)` : '';
-        return content
-            ? `[Voice message${duration}: ${attachment.url}]\n${content}`
-            : `[Voice message${duration}: ${attachment.url}]`;
+        placeholder = `[Voice message${duration} — ask sender to resend if you need the audio]`;
     }
-    if (attachment?.kind === 'image') {
-        return content ? `[Image: ${attachment.url}]\n${content}` : `[Image: ${attachment.url}]`;
+    else if (attachment?.kind === 'image') {
+        placeholder = '[Image attached — not yet materialized into this session; ask sender to describe if needed]';
     }
-    if (attachment?.kind === 'file') {
+    else if (attachment?.kind === 'file') {
         const label = attachment.fileName || 'File';
-        return content ? `[File: ${label} ${attachment.url}]\n${content}` : `[File: ${label} ${attachment.url}]`;
+        placeholder = `[File: ${label} — not yet materialized into this session]`;
+    }
+    if (placeholder) {
+        return content ? `${placeholder}\n${content}` : placeholder;
     }
     return content;
 }
@@ -486,10 +481,6 @@ async function handleInboundMessage(payload) {
         }
     }
     const primaryAttachment = getPrimaryAttachment(m);
-    if (m.imageUrl)
-        meta.image_url = m.imageUrl;
-    if (m.audioUrl)
-        meta.audio_url = m.audioUrl;
     if (primaryAttachment?.url) {
         meta.attachment_kind = primaryAttachment.kind;
         meta.attachment_url = primaryAttachment.url;

package/dist/streaming-buffer.d.ts

@@ -0,0 +1,16 @@
+export interface StreamingBufferOptions {
+    throttleMs: number;
+    getText: () => string;
+    setText: (text: string) => void;
+    getTimer: () => ReturnType<typeof setTimeout> | null;
+    setTimer: (timer: ReturnType<typeof setTimeout> | null) => void;
+    onWrite: (text: string) => void;
+    schedule?: typeof setTimeout;
+    cancel?: typeof clearTimeout;
+}
+export declare function createStreamingBuffer(options: StreamingBufferOptions): {
+    append(delta: string): void;
+    flush: () => void;
+    clear(): void;
+    replace(text: string): void;
+};

package/dist/streaming-buffer.js

@@ -0,0 +1,52 @@
+export function createStreamingBuffer(options) {
+    const schedule = options.schedule ?? setTimeout;
+    const cancel = options.cancel ?? clearTimeout;
+    const flush = () => {
+        const timer = options.getTimer();
+        if (timer) {
+            cancel(timer);
+            options.setTimer(null);
+        }
+        const text = options.getText();
+        if (text) {
+            options.onWrite(text);
+        }
+    };
+    return {
+        append(delta) {
+            if (!delta)
+                return;
+            options.setText(`${options.getText()}${delta}`);
+            if (options.getTimer())
+                return;
+            const timer = schedule(() => {
+                options.setTimer(null);
+                const text = options.getText();
+                if (text) {
+                    options.onWrite(text);
+                }
+            }, options.throttleMs);
+            options.setTimer(timer);
+        },
+        flush,
+        clear() {
+            const timer = options.getTimer();
+            if (timer) {
+                cancel(timer);
+                options.setTimer(null);
+            }
+            options.setText('');
+        },
+        replace(text) {
+            const timer = options.getTimer();
+            if (timer) {
+                cancel(timer);
+                options.setTimer(null);
+            }
+            options.setText(text);
+            if (text) {
+                options.onWrite(text);
+            }
+        },
+    };
+}

package/package.json

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