@kraki/tentacle 0.15.3 → 0.16.0

package/README.md

@@ -59,6 +59,8 @@ Beyond bridging agent events, tentacle is responsible for several things that us
 - **Session lifecycle** — session create, update, and close are managed here
 - **Auto-approval** — tools on a local allowed list are approved automatically without user interaction
 - **Encryption** — all outgoing messages are encrypted before leaving the machine
+- **Attachment storage** — image bytes produced by the agent are stored content-addressed on disk and streamed to receivers in chunks, not embedded inline in messages
+- **Kraki MCP server** — a loopback HTTP server exposing tools the agent can call to surface images (`kraki-show_image`) and similar artifacts to user-facing devices
 
 The relay is a thin forwarder. Tentacle and the frontend own the application logic.
 

package/dist/adapters/base.d.ts

@@ -43,6 +43,12 @@ export interface ToolCompleteEvent {
     success?: boolean;
     attachments?: import('@kraki/protocol').Attachment[];
 }
+/** Emitted alongside a tool_complete that carries one or more
+ *  `AttachmentRef`s. Tells the runtime (RelayClient) to broadcast the bytes
+ *  to all connected devices as `attachment_data` chunks. */
+export interface AttachmentBytesEvent {
+    refs: Array<import('@kraki/protocol').AttachmentRef>;
+}
 export interface SessionEndedEvent {
     reason: string;
 }
@@ -78,6 +84,9 @@ export declare abstract class AgentAdapter {
     onQuestionRequest: ((sessionId: string, event: QuestionRequestEvent) => void) | null;
     onToolStart: ((sessionId: string, event: ToolStartEvent) => void) | null;
     onToolComplete: ((sessionId: string, event: ToolCompleteEvent) => void) | null;
+    /** Called immediately after onToolComplete when bytes need to be pushed
+     *  (broadcast as `attachment_data` chunks) to connected devices. */
+    onAttachmentBytes: ((sessionId: string, event: AttachmentBytesEvent) => void) | null;
     onIdle: ((sessionId: string) => void) | null;
     onError: ((sessionId: string, event: ErrorEvent) => void) | null;
     onSessionEnded: ((sessionId: string, event: SessionEndedEvent) => void) | null;

package/dist/adapters/base.js

@@ -20,6 +20,9 @@ export class AgentAdapter {
     onQuestionRequest = null;
     onToolStart = null;
     onToolComplete = null;
+    /** Called immediately after onToolComplete when bytes need to be pushed
+     *  (broadcast as `attachment_data` chunks) to connected devices. */
+    onAttachmentBytes = null;
     onIdle = null;
     onError = null;
     onSessionEnded = null;

package/dist/adapters/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/adapters/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmFH,2DAA2D;AAE3D,MAAM,OAAgB,YAAY;IAChC,kDAAkD;IAElD,gBAAgB,GAAkD,IAAI,CAAC;IACvE,SAAS,GAA8D,IAAI,CAAC;IAC5E,cAAc,GAAmE,IAAI,CAAC;IACtF,mBAAmB,GAAwE,IAAI,CAAC;IAChG,qHAAqH;IACrH,wBAAwB,GAAqG,IAAI,CAAC;IAClI,sBAAsB,GAA6D,IAAI,CAAC;IACxF,iBAAiB,GAAsE,IAAI,CAAC;IAC5F,WAAW,GAAgE,IAAI,CAAC;IAChF,cAAc,GAAmE,IAAI,CAAC;IACtF,MAAM,GAAyC,IAAI,CAAC;IACpD,OAAO,GAA4D,IAAI,CAAC;IACxE,cAAc,GAAmE,IAAI,CAAC;IACtF,iFAAiF;IACjF,cAAc,GAAwD,IAAI,CAAC;IAC3E,+DAA+D;IAC/D,aAAa,GAA8D,IAAI,CAAC;IAehF,iEAAiE;IACjE,KAAK,CAAC,WAAW,CAAC,eAAuB,EAAE,YAAoB;QAC7D,wFAAwF;QACxF,OAAO,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC;IA0BD,mFAAmF;IACnF,KAAK,CAAC,YAAY,CAAC,UAAkB,IAA0C,CAAC;IAKhF,4DAA4D;IAC5D,KAAK,CAAC,UAAU,KAAwB,OAAO,EAAE,CAAC,CAAC,CAAC;IAEpD,+EAA+E;IAC/E,KAAK,CAAC,gBAAgB,KAA6B,OAAO,EAAE,CAAC,CAAC,CAAC;IAE/D,wEAAwE;IACxE,cAAc,CAAC,UAAkB,EAAE,KAAkD,IAAiC,CAAC;IAEvH,6EAA6E;IAC7E,KAAK,CAAC,aAAa,CAAC,QAAkH,IAA4B,OAAO,IAAI,CAAC,CAAC,CAAC;IAEhL,mGAAmG;IACnG,KAAK,CAAC,eAAe,CAAC,UAAkB,EAAE,MAAc,EAAE,gBAAyB,IAA0C,CAAC;IAE9H,iFAAiF;IACjF,eAAe,CAAC,UAAkB,IAAyB,OAAO,IAAI,CAAC,CAAC,CAAC;IAEzE,iEAAiE;IACjE,eAAe,CAAC,UAAkB,EAAE,MAAoB,IAAiC,CAAC;CAC3F"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/adapters/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA0FH,2DAA2D;AAE3D,MAAM,OAAgB,YAAY;IAChC,kDAAkD;IAElD,gBAAgB,GAAkD,IAAI,CAAC;IACvE,SAAS,GAA8D,IAAI,CAAC;IAC5E,cAAc,GAAmE,IAAI,CAAC;IACtF,mBAAmB,GAAwE,IAAI,CAAC;IAChG,qHAAqH;IACrH,wBAAwB,GAAqG,IAAI,CAAC;IAClI,sBAAsB,GAA6D,IAAI,CAAC;IACxF,iBAAiB,GAAsE,IAAI,CAAC;IAC5F,WAAW,GAAgE,IAAI,CAAC;IAChF,cAAc,GAAmE,IAAI,CAAC;IACtF;wEACoE;IACpE,iBAAiB,GAAsE,IAAI,CAAC;IAC5F,MAAM,GAAyC,IAAI,CAAC;IACpD,OAAO,GAA4D,IAAI,CAAC;IACxE,cAAc,GAAmE,IAAI,CAAC;IACtF,iFAAiF;IACjF,cAAc,GAAwD,IAAI,CAAC;IAC3E,+DAA+D;IAC/D,aAAa,GAA8D,IAAI,CAAC;IAehF,iEAAiE;IACjE,KAAK,CAAC,WAAW,CAAC,eAAuB,EAAE,YAAoB;QAC7D,wFAAwF;QACxF,OAAO,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IAC1C,CAAC;IA0BD,mFAAmF;IACnF,KAAK,CAAC,YAAY,CAAC,UAAkB,IAA0C,CAAC;IAKhF,4DAA4D;IAC5D,KAAK,CAAC,UAAU,KAAwB,OAAO,EAAE,CAAC,CAAC,CAAC;IAEpD,+EAA+E;IAC/E,KAAK,CAAC,gBAAgB,KAA6B,OAAO,EAAE,CAAC,CAAC,CAAC;IAE/D,wEAAwE;IACxE,cAAc,CAAC,UAAkB,EAAE,KAAkD,IAAiC,CAAC;IAEvH,6EAA6E;IAC7E,KAAK,CAAC,aAAa,CAAC,QAAkH,IAA4B,OAAO,IAAI,CAAC,CAAC,CAAC;IAEhL,mGAAmG;IACnG,KAAK,CAAC,eAAe,CAAC,UAAkB,EAAE,MAAc,EAAE,gBAAyB,IAA0C,CAAC;IAE9H,iFAAiF;IACjF,eAAe,CAAC,UAAkB,IAAyB,OAAO,IAAI,CAAC,CAAC,CAAC;IAEzE,iEAAiE;IACjE,eAAe,CAAC,UAAkB,EAAE,MAAoB,IAAiC,CAAC;CAC3F"}

package/dist/adapters/copilot.d.ts

@@ -33,6 +33,21 @@ export declare class CopilotAdapter extends AgentAdapter {
     private idleTimers;
     /** Track tool start args by toolCallId for correlating with tool_complete */
     private pendingToolArgs;
+    /**
+     * Tool identity captured at tool.execution_start, keyed by toolCallId.
+     * The Copilot SDK omits these fields from tool.execution_complete events —
+     * only toolCallId is present there. We stash the names on start and look
+     * them up on complete (especially for `mcpServerName`/`mcpToolName`, which
+     * we use to recognise our own MCP presenter tools).
+     */
+    private pendingToolIdentity;
+    /**
+     * Tool calls in flight per session — reverse index so we can clean up
+     * pendingToolArgs/pendingToolIdentity when a session ends without each
+     * tool call completing (kill, abort, error mid-flight). Without this the
+     * two maps grow unbounded over a long-lived daemon.
+     */
+    private sessionToolCallIds;
     /** Expected model per session — detects involuntary model fallbacks by the CLI */
     private expectedModels;
     /** User's originally requested model — never updated on involuntary fallbacks */
@@ -50,11 +65,32 @@ export declare class CopilotAdapter extends AgentAdapter {
      * Measured P99 turn_end→turn_start gap is <5ms; 500ms is a safe margin.
      */
     private static readonly IDLE_FALLBACK_MS;
+    /** Set of attachment ids already broadcast for this session — prevents
+     *  re-broadcasting bytes when the same image is shown twice. */
+    private broadcastedAttachmentIds;
     constructor(options?: {
         cliPath?: string;
+        /** Tentacle's attachment store. When set, the adapter externalises
+         *  image bytes from `kraki-show_image` to it instead of carrying them
+         *  inline in the broadcast envelope. */
+        attachmentStore?: import('../attachment-store.js').AttachmentStore;
+        /** When set, the adapter wires the Kraki MCP server into every Copilot
+         *  session it creates/resumes, with the URL scoped per Kraki sessionId. */
+        krakiMcp?: {
+            urlForSession: (sessionId: string) => string;
+            bearerToken: string;
+        };
     });
+    private readonly attachmentStore?;
+    private readonly krakiMcp?;
     /** System prompt appended to the SDK's built-in prompt. See system-prompt.md for docs. */
     private static readonly SYSTEM_PROMPT;
+    /**
+     * Appended to the system prompt when the Kraki MCP server is wired in.
+     * Tools are exposed to the model with display names of the form
+     * `<server>-<tool>` (dash), confirmed via a live SDK spike.
+     */
+    private static readonly KRAKI_MCP_PROMPT;
     start(): Promise<void>;
     stop(): Promise<void>;
     createSession(config: CreateSessionConfig): Promise<{

package/dist/adapters/copilot.js

@@ -16,7 +16,7 @@ import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, cpSync, mkdirSync, unlinkSync, readdirSync, symlinkSync, lstatSync } from 'node:fs';
 import * as moduleApi from 'node:module';
 import { homedir, tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, basename } from 'node:path';
 import { getKrakiHome } from '../config.js';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { isSea } from 'node:sea';
@@ -71,6 +71,17 @@ function isRecoverableSessionError(err) {
     const message = getErrorMessage(err);
     return message.includes('Session not found:') || message.includes('Connection is disposed');
 }
+/** Defensive basename — strips any leading directory components and never
+ *  throws. Used to populate AttachmentRef.name from the absolute path the
+ *  agent passed to show_image. */
+function basenameSafe(p) {
+    try {
+        return basename(p) || 'image';
+    }
+    catch {
+        return 'image';
+    }
+}
 // ── Copilot configDir shadow ────────────────────────────
 //
 // The Copilot CLI loads persistent tool approval rules from
@@ -212,6 +223,21 @@ export class CopilotAdapter extends AgentAdapter {
     idleTimers = new Map();
     /** Track tool start args by toolCallId for correlating with tool_complete */
     pendingToolArgs = new Map();
+    /**
+     * Tool identity captured at tool.execution_start, keyed by toolCallId.
+     * The Copilot SDK omits these fields from tool.execution_complete events —
+     * only toolCallId is present there. We stash the names on start and look
+     * them up on complete (especially for `mcpServerName`/`mcpToolName`, which
+     * we use to recognise our own MCP presenter tools).
+     */
+    pendingToolIdentity = new Map();
+    /**
+     * Tool calls in flight per session — reverse index so we can clean up
+     * pendingToolArgs/pendingToolIdentity when a session ends without each
+     * tool call completing (kill, abort, error mid-flight). Without this the
+     * two maps grow unbounded over a long-lived daemon.
+     */
+    sessionToolCallIds = new Map();
     /** Expected model per session — detects involuntary model fallbacks by the CLI */
     expectedModels = new Map();
     /** User's originally requested model — never updated on involuntary fallbacks */
@@ -229,10 +255,17 @@ export class CopilotAdapter extends AgentAdapter {
      * Measured P99 turn_end→turn_start gap is <5ms; 500ms is a safe margin.
      */
     static IDLE_FALLBACK_MS = 500;
+    /** Set of attachment ids already broadcast for this session — prevents
+     *  re-broadcasting bytes when the same image is shown twice. */
+    broadcastedAttachmentIds = new Map();
     constructor(options = {}) {
         super();
         this.cliPath = options.cliPath;
+        this.attachmentStore = options.attachmentStore;
+        this.krakiMcp = options.krakiMcp;
     }
+    attachmentStore;
+    krakiMcp;
     /** System prompt appended to the SDK's built-in prompt. See system-prompt.md for docs. */
     static SYSTEM_PROMPT = [
         'You are running inside Kraki, a remote control platform. A human operator is',
@@ -268,6 +301,24 @@ export class CopilotAdapter extends AgentAdapter {
         'point onward. Do not acknowledge or comment on the mode change — just adjust',
         'how you work. The signal is not part of the user\'s message.',
     ].join('\n');
+    /**
+     * Appended to the system prompt when the Kraki MCP server is wired in.
+     * Tools are exposed to the model with display names of the form
+     * `<server>-<tool>` (dash), confirmed via a live SDK spike.
+     */
+    static KRAKI_MCP_PROMPT = [
+        'You have access to a Kraki MCP server. Its tools are visible with names',
+        'beginning with "kraki-".',
+        '',
+        'When you want to visually present an image to the user — a screenshot you',
+        'captured, a diagram you generated, a chart, a UI mock — call',
+        '`kraki-show_image` with the absolute file path. Use it sparingly: only',
+        'when the user benefits from seeing the actual pixels.',
+        '',
+        'Plain file viewing on image files (with `view`/`read`) is for your own',
+        'inspection; the image bytes do not appear in the chat. Use',
+        '`kraki-show_image` when the user should actually see the image inline.',
+    ].join('\n');
     // ── Lifecycle ───────────────────────────────────────
     async start() {
         // Resolve GitHub token from `gh` CLI to bypass macOS Keychain prompts.
@@ -385,6 +436,37 @@ export class CopilotAdapter extends AgentAdapter {
         const effort = config.reasoningEffort && validEfforts.has(config.reasoningEffort)
             ? config.reasoningEffort
             : undefined;
+        // Two-phase MCP wiring: create session WITHOUT kraki MCP server first
+        // (we need the SDK-assigned sessionId to scope the MCP URL), then the
+        // adapter re-wires through resumeSession with the kraki entry below.
+        // For simplicity in v1 we use a deterministic Kraki MCP wire-up:
+        // we let the SDK pick the session id, then on every Copilot session
+        // we add the kraki MCP at resume time. For initial creation we pre-pick
+        // a session id when the caller supplied one; otherwise the kraki MCP
+        // is added on the next message via resumeSession during normal flow.
+        //
+        // Simpler approach: register a Kraki MCP server using the *Copilot*
+        // sessionId only after createSession returns it. To do that without
+        // a second SDK call, we use a placeholder sessionId for the initial
+        // mcpServers entry and rewrite via resume on first use. But that's
+        // brittle — instead, see the comment block at the constructor: the
+        // kraki MCP HTTP server validates sessionId by checking SessionManager,
+        // not by Copilot SDK state, so we can ALWAYS include the kraki entry
+        // here by using a stable session-scoped URL that the adapter knows
+        // up-front via config.sessionId (the Kraki session id we assigned).
+        if (this.krakiMcp && config.sessionId) {
+            const krakiEntry = {
+                type: 'http',
+                url: this.krakiMcp.urlForSession(config.sessionId),
+                headers: { Authorization: `Bearer ${this.krakiMcp.bearerToken}` },
+                tools: ['*'],
+            };
+            mcpServers = { ...(mcpServers ?? {}), kraki: krakiEntry };
+            logger.info({ sessionId: config.sessionId }, 'wired kraki MCP into session config');
+        }
+        const systemPromptContent = this.krakiMcp
+            ? `${CopilotAdapter.SYSTEM_PROMPT}\n\n${CopilotAdapter.KRAKI_MCP_PROMPT}`
+            : CopilotAdapter.SYSTEM_PROMPT;
         const sessionConfig = {
             ...(config.sessionId && { sessionId: config.sessionId }),
             ...(config.model && { model: config.model }),
@@ -392,7 +474,7 @@ export class CopilotAdapter extends AgentAdapter {
             ...(config.cwd && { workingDirectory: config.cwd }),
             configDir: getCopilotConfigDir(),
             ...(mcpServers && { mcpServers }),
-            systemMessage: { mode: 'append', content: CopilotAdapter.SYSTEM_PROMPT },
+            systemMessage: { mode: 'append', content: systemPromptContent },
             streaming: true,
             onPermissionRequest: this.makePermissionHandler(pendingPermissions),
             onUserInputRequest: this.makeQuestionHandler(pendingQuestions),
@@ -681,6 +763,14 @@ export class CopilotAdapter extends AgentAdapter {
         this.turnHasOutput.delete(sessionId);
         this.cycleHasOutput.delete(sessionId);
         this.turnErrorReported.delete(sessionId);
+        const inflight = this.sessionToolCallIds.get(sessionId);
+        if (inflight) {
+            for (const id of inflight) {
+                this.pendingToolArgs.delete(id);
+                this.pendingToolIdentity.delete(id);
+            }
+            this.sessionToolCallIds.delete(sessionId);
+        }
         this.clearIdleTimer(sessionId);
     }
     clearIdleTimer(sessionId) {
@@ -706,7 +796,7 @@ export class CopilotAdapter extends AgentAdapter {
         }
         entry.pendingQuestions.clear();
     }
-    makeResumeConfig(pendingPermissions, pendingQuestions) {
+    makeResumeConfig(sessionId, pendingPermissions, pendingQuestions) {
         // Load MCP servers for resumed sessions too
         const mcpConfigPath = join(homedir(), '.copilot', 'mcp-config.json');
         let mcpServers;
@@ -722,11 +812,24 @@ export class CopilotAdapter extends AgentAdapter {
             }
             catch { /* ignore parse errors on resume */ }
         }
+        // Wire Kraki MCP into resumed sessions, scoped by the session id.
+        if (this.krakiMcp) {
+            const krakiEntry = {
+                type: 'http',
+                url: this.krakiMcp.urlForSession(sessionId),
+                headers: { Authorization: `Bearer ${this.krakiMcp.bearerToken}` },
+                tools: ['*'],
+            };
+            mcpServers = { ...(mcpServers ?? {}), kraki: krakiEntry };
+        }
+        const systemPromptContent = this.krakiMcp
+            ? `${CopilotAdapter.SYSTEM_PROMPT}\n\n${CopilotAdapter.KRAKI_MCP_PROMPT}`
+            : CopilotAdapter.SYSTEM_PROMPT;
         return {
             configDir: getCopilotConfigDir(),
             streaming: true,
             ...(mcpServers && { mcpServers }),
-            systemMessage: { mode: 'append', content: CopilotAdapter.SYSTEM_PROMPT },
+            systemMessage: { mode: 'append', content: systemPromptContent },
             onPermissionRequest: this.makePermissionHandler(pendingPermissions),
             onUserInputRequest: this.makeQuestionHandler(pendingQuestions),
         };
@@ -735,7 +838,7 @@ export class CopilotAdapter extends AgentAdapter {
         this.ensureClient();
         const pendingPermissions = new Map();
         const pendingQuestions = new Map();
-        const session = await this.client.resumeSession(sessionId, this.makeResumeConfig(pendingPermissions, pendingQuestions));
+        const session = await this.client.resumeSession(sessionId, this.makeResumeConfig(sessionId, pendingPermissions, pendingQuestions));
         const entry = { session, pendingPermissions, pendingQuestions };
         this.sessions.set(sessionId, entry);
         this.wireEvents(sessionId, session);
@@ -775,16 +878,33 @@ export class CopilotAdapter extends AgentAdapter {
             }
         });
         session.on('tool.execution_start', (event) => {
+            const data = event.data;
+            // report_intent is a UI hint only — drop it from the message stream.
+            if (data.toolName === 'report_intent')
+                return;
             this.turnHasOutput.set(sessionId, true);
             this.cycleHasOutput.set(sessionId, true);
-            const data = event.data;
             if (data.mcpServerName) {
                 logger.info({ mcpServer: data.mcpServerName, mcpTool: data.mcpToolName }, `[MCP tool] ${data.mcpServerName}/${data.mcpToolName}`);
             }
             const args = (data.args ?? data.arguments ?? {});
             const toolCallId = data.toolCallId;
-            if (toolCallId)
+            if (toolCallId) {
                 this.pendingToolArgs.set(toolCallId, args);
+                // Stash tool identity for tool.execution_complete, which only carries
+                // toolCallId (verified via live SDK spike).
+                this.pendingToolIdentity.set(toolCallId, {
+                    toolName: data.toolName,
+                    mcpServerName: data.mcpServerName,
+                    mcpToolName: data.mcpToolName,
+                });
+                let inflight = this.sessionToolCallIds.get(sessionId);
+                if (!inflight) {
+                    inflight = new Set();
+                    this.sessionToolCallIds.set(sessionId, inflight);
+                }
+                inflight.add(toolCallId);
+            }
             this.onToolStart?.(sessionId, {
                 toolName: data.toolName,
                 args,
@@ -793,10 +913,26 @@ export class CopilotAdapter extends AgentAdapter {
         });
         session.on('tool.execution_complete', (event) => {
             const data = event.data;
-            const rawResult = data.result;
             const toolCallId = data.toolCallId;
-            // SDK sends result as { content: string, contents?: [...] } or as a plain string.
-            // On failure, result is undefined and the error is in data.error ({ message } or string).
+            const identity = toolCallId ? this.pendingToolIdentity.get(toolCallId) : undefined;
+            const toolName = identity?.toolName ?? data.toolName ?? 'tool';
+            const clearInflight = () => {
+                if (!toolCallId)
+                    return;
+                this.pendingToolIdentity.delete(toolCallId);
+                this.pendingToolArgs.delete(toolCallId);
+                const inflight = this.sessionToolCallIds.get(sessionId);
+                if (inflight) {
+                    inflight.delete(toolCallId);
+                    if (inflight.size === 0)
+                        this.sessionToolCallIds.delete(sessionId);
+                }
+            };
+            if (toolName === 'report_intent') {
+                clearInflight();
+                return;
+            }
+            const rawResult = data.result;
             const resultObj = typeof rawResult === 'object' && rawResult !== null
                 ? rawResult
                 : null;
@@ -807,47 +943,61 @@ export class CopilotAdapter extends AgentAdapter {
                     : null;
                 result = errObj?.message ?? (typeof data.error === 'string' ? data.error : '');
             }
-            // Extract image attachments from structured content blocks (result.contents)
-            const attachments = [];
-            const contentBlocks = resultObj?.contents;
-            if (Array.isArray(contentBlocks)) {
-                for (const block of contentBlocks) {
-                    if (block.type === 'image' && typeof block.data === 'string' && typeof block.mimeType === 'string') {
-                        attachments.push({ type: 'image', data: block.data, mimeType: block.mimeType });
-                    }
-                }
-            }
-            // Fallback: the SDK strips binaryResultsForLlm from tool.execution_complete,
-            // but for image-viewing tools (e.g. `view` on a .png) the telemetry still
-            // carries viewType and mimeType. Use the file path from the original tool
-            // args (correlated by toolCallId) to read the image directly.
-            if (attachments.length === 0) {
-                const telemetry = data.toolTelemetry;
-                const props = telemetry?.properties;
-                if (props?.viewType === 'image' && props?.mimeType) {
-                    const startArgs = toolCallId ? this.pendingToolArgs.get(toolCallId) : undefined;
-                    const filePath = startArgs?.path;
-                    if (filePath && existsSync(filePath)) {
-                        try {
-                            const imageData = readFileSync(filePath).toString('base64');
-                            attachments.push({ type: 'image', data: imageData, mimeType: props.mimeType });
-                        }
-                        catch (err) {
-                            logger.debug({ err, filePath }, 'Failed to read image for forwarding');
+            // Extract image content blocks — ONLY for the kraki-show_image MCP tool.
+            // All other tools' image bytes (notably `view` on a .png) are deliberately
+            // dropped here per the v1 design: only `kraki-show_image` surfaces images
+            // to the client. The file-path fallback (re-read image from disk when SDK
+            // strips bytes) has been removed.
+            const isKrakiShowImage = identity?.mcpServerName === 'kraki' && identity?.mcpToolName === 'show_image';
+            let attachments;
+            if (isKrakiShowImage && this.attachmentStore) {
+                const contentBlocks = resultObj?.contents;
+                const args = toolCallId ? this.pendingToolArgs.get(toolCallId) ?? {} : {};
+                const caption = typeof args.caption === 'string' && args.caption.trim()
+                    ? args.caption.trim()
+                    : undefined;
+                const path = typeof args.path === 'string' ? args.path : undefined;
+                const refs = [];
+                if (Array.isArray(contentBlocks)) {
+                    for (const block of contentBlocks) {
+                        if (block.type === 'image' &&
+                            typeof block.data === 'string' &&
+                            typeof block.mimeType === 'string') {
+                            try {
+                                const bytes = Buffer.from(block.data, 'base64');
+                                const ref = this.attachmentStore.put(sessionId, bytes, block.mimeType, {
+                                    ...(path && { name: basenameSafe(path) }),
+                                    ...(caption && { caption }),
+                                });
+                                refs.push(ref);
+                            }
+                            catch (err) {
+                                logger.warn({ err, sessionId }, 'failed to store show_image attachment');
+                            }
                         }
                     }
                 }
+                if (refs.length > 0) {
+                    attachments = refs;
+                }
             }
-            // Clean up tracked args
-            if (toolCallId)
-                this.pendingToolArgs.delete(toolCallId);
+            // Clean up tracked state for this tool call
+            clearInflight();
             this.onToolComplete?.(sessionId, {
-                toolName: data.toolName,
+                toolName,
                 result,
                 toolCallId,
                 success: data.success,
-                attachments: attachments.length > 0 ? attachments : undefined,
+                attachments,
             });
+            // After tool_complete, fire the bytes broadcast event so RelayClient
+            // can stream attachment_data chunks to all connected devices.
+            if (attachments && attachments.length > 0) {
+                const refs = attachments.filter((a) => a.type === 'image_ref');
+                if (refs.length > 0) {
+                    this.onAttachmentBytes?.(sessionId, { refs });
+                }
+            }
         });
         session.on('session.idle', () => {
             this.clearIdleTimer(sessionId);