@dinoxx/dinox-cli 2.7.0 → 2.8.1

package/dist/commands/gateway/index.js

@@ -291,7 +291,7 @@ export const gatewayCommandGroup = {
         },
         {
             name: 'mcp',
-            description: 'Serve read-only Dinox knowledge tools over stdio MCP (started by gateway agents)',
+            description: 'Serve Dinox tools over stdio MCP: read-only knowledge tools and send_file (started by gateway agents)',
             schema: {
                 path: 'gateway.mcp',
                 risk: 'read',

package/dist/commands/storage/repo/remote.d.ts

@@ -28,5 +28,5 @@ export declare function defaultUploadBytes(input: {
 }): Promise<UploadObjectResult>;
 type SharpFactory = typeof import('sharp');
 export declare function loadSharp(): Promise<SharpFactory>;
-export declare function generateThumbnailBuffer(sharp: SharpFactory, localPath: string): Promise<Buffer>;
+export declare function generateThumbnailBuffer(sharp: SharpFactory, input: string | Buffer): Promise<Buffer>;
 export {};

package/dist/commands/storage/repo/remote.js

@@ -124,8 +124,8 @@ export async function loadSharp() {
         });
     }
 }
-export async function generateThumbnailBuffer(sharp, localPath) {
-    return sharp(localPath)
+export async function generateThumbnailBuffer(sharp, input) {
+    return sharp(input)
         .resize({ width: 400, withoutEnlargement: true })
         .webp({ quality: 50 })
         .toBuffer();

package/dist/daemon/server.js

@@ -1,6 +1,7 @@
 import crypto from 'node:crypto';
 import { createServer } from 'http';
 import { chmodSync, existsSync } from 'node:fs';
+import path from 'node:path';
 import { DAEMON_SERVICE_ENV } from './supervisor.js';
 import { writeDaemonLogLine } from './log.js';
 import { loadConfig } from '../config/store.js';
@@ -183,6 +184,21 @@ export class DaemonServer {
                     }
                     return { id: req.id, ok: true, result: { gateways: await this.gateways.reload() } };
                 }
+                case 'gateway.sendFile': {
+                    if (!this.gateways) {
+                        throw new DinoxError('Gateways need a signed-in daemon', { code: 'AUTH_REQUIRED' });
+                    }
+                    const { token, path: filePath, name } = (params ?? {});
+                    if (typeof token !== 'string' || !token || typeof filePath !== 'string' || !path.isAbsolute(filePath)) {
+                        throw new DinoxError('gateway.sendFile needs a session token and an absolute path', { code: 'USAGE_ERROR' });
+                    }
+                    const sent = await this.gateways.sendFile(token, {
+                        kind: 'path',
+                        path: filePath,
+                        ...(typeof name === 'string' && name.trim() ? { name: name.trim() } : {}),
+                    });
+                    return { id: req.id, ok: true, result: sent };
+                }
                 case 'thread.messages': {
                     if (!this.userId) {
                         throw new DinoxError('Reading conversations needs a signed-in daemon', { code: 'AUTH_REQUIRED' });

package/dist/gateway/adapters/acp.d.ts

@@ -1,6 +1,9 @@
-import { type McpServer, type SessionConfigOption, type ToolKind } from '@agentclientprotocol/sdk';
-import type { GatewayAdapter, GatewayAdapterInfo, GatewayConfigOption, GatewayDefinition, GatewayTurnInput, GatewayTurnResult } from '../types.js';
+import { type ContentBlock, type McpServer, type SessionConfigOption, type ToolKind } from '@agentclientprotocol/sdk';
+import type { GatewayAdapter, GatewayAdapterInfo, GatewayConfigOption, GatewayDefinition, GatewayFileSource, GatewaySentFile, GatewayTurnInput, GatewayTurnResult } from '../types.js';
 type Logger = (message: string, details?: Record<string, unknown>) => void;
+export declare function withoutTransportNotice(text: string): string;
+/** A file in an agent message (an image, or a resource it attached), as something to send the user. */
+export declare function fileFromContent(content: ContentBlock): GatewayFileSource | null;
 /** Select options only; boolean toggles have no use in the app yet. */
 export declare function normalizeConfigOptions(options: SessionConfigOption[] | null | undefined): GatewayConfigOption[];
 export declare function isReadOnlyToolKind(kind: ToolKind | null | undefined): boolean;
@@ -14,7 +17,10 @@ export declare class AcpGatewayAdapter implements GatewayAdapter {
     /** Live: settings changed from the app (approval, Dinox tools) apply to the next request. */
     private readonly gateway;
     private readonly log;
-    /** MCP servers offered to sessions as they are created or loaded, e.g. the Dinox knowledge tools. */
+    /**
+     * MCP servers offered to sessions as they are created or loaded, e.g. the
+     * Dinox tools; `sessionToken` lets their `send_file` reach this session.
+     */
     private readonly mcpServers;
     readonly kind: "acp";
     private process;
@@ -22,15 +28,25 @@ export declare class AcpGatewayAdapter implements GatewayAdapter {
     private readonly turns;
     /** The latest settings any session reported: the agent-wide choices the app lists. */
     private catalog;
+    /** Token each session's Dinox tools were started with → that session, for routing `send_file`. */
+    private readonly sessionTokens;
     constructor(
     /** Live: settings changed from the app (approval, Dinox tools) apply to the next request. */
     gateway: GatewayDefinition, log?: Logger, 
-    /** MCP servers offered to sessions as they are created or loaded, e.g. the Dinox knowledge tools. */
-    mcpServers?: () => McpServer[]);
+    /**
+     * MCP servers offered to sessions as they are created or loaded, e.g. the
+     * Dinox tools; `sessionToken` lets their `send_file` reach this session.
+     */
+    mcpServers?: (sessionToken: string) => McpServer[]);
     info(): GatewayAdapterInfo;
     runTurn(input: GatewayTurnInput): Promise<GatewayTurnResult>;
+    sendFile(token: string, file: GatewayFileSource): Promise<GatewaySentFile> | null;
     describeConfig(): Promise<GatewayConfigOption[]>;
     dispose(): Promise<void>;
+    /** Codex leaves generated images on disk; send the ones this turn made when it sent nothing itself. */
+    private sendGeneratedImages;
+    /** Reports a file the agent put in its message to the user, without failing the turn. */
+    private sendContentFile;
     /** Continues the session (loading it in `cwd` when this process has not seen it) or starts one there. */
     private resolveSession;
     /**

package/dist/gateway/adapters/acp.js

@@ -1,9 +1,13 @@
 import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { Readable, Writable } from 'node:stream';
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from '@agentclientprotocol/sdk';
 import { generateId } from '../../utils/id.js';
 import { getPackageVersion } from '../../utils/version.js';
+import { codexGeneratedImagesDir, codexImagesSince } from './codexImages.js';
+import { agentLaunch } from '../spawnAgent.js';
 const TOOL_STATUS = {
     pending: 'pending',
     in_progress: 'running',
@@ -17,6 +21,30 @@ const STOP_REASON = {
     refusal: 'refusal',
     cancelled: 'cancelled',
 };
+/** Codex reports its transport falling back as message text; it is not part of the answer. */
+const TRANSPORT_NOTICE = /^Warning: Falling back from WebSockets to HTTPS transport\.[^\n]*(\n+|$)/;
+export function withoutTransportNotice(text) {
+    return text.replace(TRANSPORT_NOTICE, '');
+}
+/** A file in an agent message (an image, or a resource it attached), as something to send the user. */
+export function fileFromContent(content) {
+    switch (content.type) {
+        case 'image':
+            return content.data ? { kind: 'data', data: content.data, mediaType: content.mimeType } : null;
+        case 'resource_link':
+            return content.uri.startsWith('file://')
+                ? { kind: 'path', path: fileURLToPath(content.uri), name: content.name }
+                : null;
+        case 'resource': {
+            const resource = content.resource;
+            if (!('blob' in resource))
+                return null;
+            return { kind: 'data', data: resource.blob, mediaType: resource.mimeType ?? 'application/octet-stream' };
+        }
+        default:
+            return null;
+    }
+}
 function toolContentText(content) {
     const text = (content ?? [])
         .map((item) => (item.type === 'content' && item.content.type === 'text' ? item.content.text : ''))
@@ -82,10 +110,15 @@ export class AcpGatewayAdapter {
     turns = new Map();
     /** The latest settings any session reported: the agent-wide choices the app lists. */
     catalog = null;
+    /** Token each session's Dinox tools were started with → that session, for routing `send_file`. */
+    sessionTokens = new Map();
     constructor(
     /** Live: settings changed from the app (approval, Dinox tools) apply to the next request. */
     gateway, log = () => { }, 
-    /** MCP servers offered to sessions as they are created or loaded, e.g. the Dinox knowledge tools. */
+    /**
+     * MCP servers offered to sessions as they are created or loaded, e.g. the
+     * Dinox tools; `sessionToken` lets their `send_file` reach this session.
+     */
     mcpServers = () => []) {
         this.gateway = gateway;
         this.log = log;
@@ -99,7 +132,9 @@ export class AcpGatewayAdapter {
         const agent = await this.ensureProcess();
         const { sessionId, created } = await this.resolveSession(agent, input.sessionId, input.cwd);
         await this.applyConfig(agent, sessionId, input.config);
-        this.turns.set(sessionId, { onEvent: input.onEvent, awaitApproval: input.awaitApproval });
+        const turn = { onEvent: input.onEvent, awaitApproval: input.awaitApproval, sendFile: input.sendFile, sent: 0 };
+        this.turns.set(sessionId, turn);
+        const startedAt = Date.now();
         const onAbort = () => {
             void agent.connection.cancel({ sessionId }).catch(() => undefined);
         };
@@ -111,6 +146,8 @@ export class AcpGatewayAdapter {
                 prompt.push({ type: 'resource_link', uri: resource.uri, name: resource.name, mimeType: resource.mediaType ?? null });
             }
             const response = await agent.connection.prompt({ sessionId, prompt });
+            if (turn.sent === 0)
+                await this.sendGeneratedImages(turn, sessionId, startedAt);
             return { sessionId, stopReason: STOP_REASON[response.stopReason] ?? 'end_turn' };
         }
         catch (error) {
@@ -123,6 +160,16 @@ export class AcpGatewayAdapter {
             this.turns.delete(sessionId);
         }
     }
+    sendFile(token, file) {
+        const sessionId = this.sessionTokens.get(token);
+        if (!sessionId)
+            return null;
+        const turn = this.turns.get(sessionId);
+        if (!turn)
+            return Promise.reject(new Error('Files can only be sent while answering the user'));
+        turn.sent += 1;
+        return turn.sendFile(file);
+    }
     async describeConfig() {
         if (this.catalog)
             return this.catalog;
@@ -146,6 +193,25 @@ export class AcpGatewayAdapter {
             return;
         agent.child.stdin.end();
         agent.child.kill('SIGTERM');
+        this.sessionTokens.clear();
+    }
+    /** Codex leaves generated images on disk; send the ones this turn made when it sent nothing itself. */
+    async sendGeneratedImages(turn, sessionId, startedAt) {
+        const dir = codexGeneratedImagesDir(sessionId, { ...process.env, ...(this.gateway.env ?? {}) });
+        if (!dir)
+            return;
+        for (const file of await codexImagesSince(dir, startedAt)) {
+            turn.sent += 1;
+            await turn.sendFile({ kind: 'path', path: file }).catch((error) => this.log('sending a generated image failed', { error: String(error) }));
+        }
+    }
+    /** Reports a file the agent put in its message to the user, without failing the turn. */
+    sendContentFile(turn, content) {
+        const file = fileFromContent(content);
+        if (!file)
+            return;
+        turn.sent += 1;
+        void turn.sendFile(file).catch((error) => this.log('sending a file from the agent message failed', { error: String(error) }));
     }
     /** Continues the session (loading it in `cwd` when this process has not seen it) or starts one there. */
     async resolveSession(agent, sessionId, cwd) {
@@ -154,7 +220,9 @@ export class AcpGatewayAdapter {
         if (sessionId && agent.init.agentCapabilities?.loadSession) {
             try {
                 // No turn is registered yet, so the history the agent replays is ignored.
-                const loaded = await agent.connection.loadSession({ sessionId, cwd, mcpServers: this.mcpServers() });
+                const token = crypto.randomBytes(18).toString('base64url');
+                const loaded = await agent.connection.loadSession({ sessionId, cwd, mcpServers: this.mcpServers(token) });
+                this.sessionTokens.set(token, sessionId);
                 agent.liveSessions.add(sessionId);
                 this.rememberConfig(agent, sessionId, loaded.configOptions);
                 return { sessionId, created: false };
@@ -163,7 +231,9 @@ export class AcpGatewayAdapter {
                 this.log('session/load failed; starting a new session', { sessionId, error: String(error) });
             }
         }
-        const created = await agent.connection.newSession({ cwd, mcpServers: this.mcpServers() });
+        const token = crypto.randomBytes(18).toString('base64url');
+        const created = await agent.connection.newSession({ cwd, mcpServers: this.mcpServers(token) });
+        this.sessionTokens.set(token, created.sessionId);
         agent.liveSessions.add(created.sessionId);
         this.rememberConfig(agent, created.sessionId, created.configOptions);
         return { sessionId: created.sessionId, created: true };
@@ -209,21 +279,24 @@ export class AcpGatewayAdapter {
         const command = this.gateway.command;
         if (!command)
             throw new Error(`Gateway ${this.gateway.name} has no ACP command`);
-        const child = spawn(command, this.gateway.args ?? [], {
+        const launch = agentLaunch(command, this.gateway.args ?? [], {
             cwd: this.gateway.cwd ?? os.homedir(),
             env: { ...process.env, ...(this.gateway.env ?? {}) },
             stdio: ['pipe', 'pipe', 'pipe'],
             // The daemon runs without a visible console on Windows; keep agents that way.
             windowsHide: true,
         });
+        const child = spawn(launch.command, launch.args, launch.options);
         child.stderr.on('data', (chunk) => this.log('agent stderr', { text: chunk.toString('utf8').slice(0, 2000) }));
         const exited = new Promise((_, reject) => {
             child.once('error', reject);
             child.once('exit', (code, signal) => reject(new Error(`agent exited (code ${code}, signal ${signal})`)));
         });
         child.once('exit', () => {
-            if (this.process?.child === child)
+            if (this.process?.child === child) {
                 this.process = null;
+                this.sessionTokens.clear();
+            }
         });
         const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
         const connection = new ClientSideConnection(() => ({
@@ -255,8 +328,14 @@ export class AcpGatewayAdapter {
             return;
         switch (update.sessionUpdate) {
             case 'agent_message_chunk':
-                if (update.content.type === 'text')
-                    turn.onEvent({ type: 'text-delta', text: update.content.text });
+                if (update.content.type === 'text') {
+                    const text = withoutTransportNotice(update.content.text);
+                    if (text)
+                        turn.onEvent({ type: 'text-delta', text });
+                }
+                else {
+                    this.sendContentFile(turn, update.content);
+                }
                 break;
             case 'agent_thought_chunk':
                 if (update.content.type === 'text')

package/dist/gateway/adapters/codexImages.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_FALLBACK_IMAGES = 4;
+export declare function codexGeneratedImagesDir(sessionId: string, env: Record<string, string | undefined>): string | null;
+/** Images written to the session's folder since `sinceMs`, oldest first. */
+export declare function codexImagesSince(dir: string, sinceMs: number): Promise<string[]>;

package/dist/gateway/adapters/codexImages.js

@@ -0,0 +1,34 @@
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Codex saves the images it generates to `$CODEX_HOME/generated_images/<session>/`
+ * and only tells the model where they are, so a turn that produced images but
+ * never sent them would leave the user with nothing. The newest ones are sent instead.
+ */
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif']);
+export const MAX_FALLBACK_IMAGES = 4;
+export function codexGeneratedImagesDir(sessionId, env) {
+    // The session id names a folder; refuse anything that could leave it.
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(sessionId))
+        return null;
+    const codexHome = env.CODEX_HOME?.trim() || path.join(os.homedir(), '.codex');
+    return path.join(codexHome, 'generated_images', sessionId);
+}
+/** Images written to the session's folder since `sinceMs`, oldest first. */
+export async function codexImagesSince(dir, sinceMs) {
+    const entries = await fsp.readdir(dir, { withFileTypes: true }).catch(() => []);
+    const images = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !IMAGE_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+            continue;
+        const file = path.join(dir, entry.name);
+        const stats = await fsp.stat(file).catch(() => null);
+        if (stats && stats.mtimeMs >= sinceMs)
+            images.push({ file, mtimeMs: stats.mtimeMs });
+    }
+    return images
+        .sort((a, b) => a.mtimeMs - b.mtimeMs)
+        .slice(-MAX_FALLBACK_IMAGES)
+        .map((image) => image.file);
+}

package/dist/gateway/adapters/index.d.ts

@@ -1,9 +1,12 @@
 import type { McpServer } from '@agentclientprotocol/sdk';
 import type { GatewayAdapter, GatewayDefinition } from '../types.js';
 /**
- * The Dinox knowledge tools as a stdio MCP server: this same CLI, run as
+ * The Dinox tools as a stdio MCP server: this same CLI, run as
  * `dino gateway mcp`, reading through the daemon. DINOX_* variables are passed
  * on so the child finds the same config, data dir and daemon socket.
  */
-export declare function dinoxMcpServerConfig(): McpServer | null;
+export declare function dinoxMcpServerConfig(options: {
+    sessionToken: string;
+    knowledgeTools: boolean;
+}): McpServer | null;
 export declare function createGatewayAdapter(gateway: GatewayDefinition, log: (message: string, details?: Record<string, unknown>) => void): GatewayAdapter;

package/dist/gateway/adapters/index.js

@@ -1,30 +1,39 @@
+import { GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from '../mcpEnv.js';
 import { AcpGatewayAdapter } from './acp.js';
 import { EchoGatewayAdapter } from './echo.js';
 /**
- * The Dinox knowledge tools as a stdio MCP server: this same CLI, run as
+ * The Dinox tools as a stdio MCP server: this same CLI, run as
  * `dino gateway mcp`, reading through the daemon. DINOX_* variables are passed
  * on so the child finds the same config, data dir and daemon socket.
  */
-export function dinoxMcpServerConfig() {
+export function dinoxMcpServerConfig(options) {
     const entrypoint = process.argv[1];
     if (!entrypoint)
         return null;
+    const inherited = Object.entries(process.env).filter((entry) => entry[0].startsWith('DINOX_') &&
+        entry[0] !== GATEWAY_SESSION_TOKEN_ENV &&
+        entry[0] !== GATEWAY_KNOWLEDGE_TOOLS_ENV &&
+        typeof entry[1] === 'string');
     return {
         name: 'dinox',
         command: process.execPath,
         args: [...process.execArgv, entrypoint, 'gateway', 'mcp'],
-        env: Object.entries(process.env)
-            .filter((entry) => entry[0].startsWith('DINOX_') && typeof entry[1] === 'string')
-            .map(([name, value]) => ({ name, value })),
+        env: [
+            ...inherited,
+            [GATEWAY_SESSION_TOKEN_ENV, options.sessionToken],
+            [GATEWAY_KNOWLEDGE_TOOLS_ENV, options.knowledgeTools ? '1' : '0'],
+        ].map(([name, value]) => ({ name, value })),
     };
 }
 export function createGatewayAdapter(gateway, log) {
     switch (gateway.kind) {
-        case 'acp': {
-            const dinoxTools = dinoxMcpServerConfig();
-            // Read per session, so turning the Dinox tools off applies to the next new conversation.
-            return new AcpGatewayAdapter(gateway, log, () => (gateway.dinoxTools !== false && dinoxTools ? [dinoxTools] : []));
-        }
+        case 'acp':
+            // Read per session, so turning the knowledge tools off applies to the next new conversation.
+            // `send_file` stays offered either way: it is how the agent hands the user a file.
+            return new AcpGatewayAdapter(gateway, log, (sessionToken) => {
+                const tools = dinoxMcpServerConfig({ sessionToken, knowledgeTools: gateway.dinoxTools !== false });
+                return tools ? [tools] : [];
+            });
         case 'echo':
             return new EchoGatewayAdapter();
     }

package/dist/gateway/assistantProjection.d.ts

@@ -1,6 +1,7 @@
 import type { ChatUIMessage } from '../vendor/electron/shared/external-types.js';
 import type { RemoteToolApprovalPrompt } from '../vendor/electron/shared/remote-device-agent.js';
-import type { GatewayEvent } from './types.js';
+import type { GatewayEvent, GatewaySentFile } from './types.js';
+export declare function compactToolValue(value: unknown, depth?: number): unknown;
 export declare class AssistantProjection {
     private readonly base;
     private readonly parts;
@@ -10,11 +11,14 @@ export declare class AssistantProjection {
     constructor(base: ChatUIMessage);
     get revision(): number;
     apply(event: GatewayEvent): void;
+    /** A file sent to the user, shown where the agent sent it (the app renders images inline). */
+    addFile(file: GatewaySentFile): void;
     /** Closes streaming parts; called once when the turn ends. */
     finish(): void;
     snapshot(): ChatUIMessage;
     private appendText;
     private ensureTool;
+    private closeTextSegment;
     private findToolByApproval;
     private applyTool;
 }

package/dist/gateway/assistantProjection.js

@@ -8,6 +8,27 @@ const APPROVAL_TTL_MS = 30 * 60 * 1000;
 const MAX_PENDING_APPROVALS = 32;
 const PREVIEW_MAX_CHARS = 1500;
 const SENSITIVE_KEY = /password|token|secret|api[-_ ]?key|authorization|cookie|credential|private[-_ ]?key/i;
+/** Tool input/output is shown as a preview; whole files (e.g. a generated image as base64) would overflow every event. */
+const TOOL_STRING_MAX_CHARS = 4000;
+const TOOL_VALUE_MAX_ITEMS = 64;
+const TOOL_VALUE_MAX_DEPTH = 6;
+export function compactToolValue(value, depth = 0) {
+    if (typeof value === 'string') {
+        if (value.startsWith('data:') && value.length > 256) {
+            return `[${value.slice(5, value.indexOf(';') > 0 ? value.indexOf(';') : 32)} data, ${value.length} chars]`;
+        }
+        return value.length > TOOL_STRING_MAX_CHARS ? `${value.slice(0, TOOL_STRING_MAX_CHARS)}… (${value.length} chars)` : value;
+    }
+    if (!value || typeof value !== 'object')
+        return value;
+    if (depth >= TOOL_VALUE_MAX_DEPTH)
+        return '[…]';
+    if (Array.isArray(value))
+        return value.slice(0, TOOL_VALUE_MAX_ITEMS).map((item) => compactToolValue(item, depth + 1));
+    return Object.fromEntries(Object.entries(value)
+        .slice(0, TOOL_VALUE_MAX_ITEMS)
+        .map(([key, item]) => [key, compactToolValue(item, depth + 1)]));
+}
 export class AssistantProjection {
     base;
     parts = [];
@@ -43,7 +64,7 @@ export class AssistantProjection {
                 part.state = 'approval-requested';
                 part.approval = { id: event.approvalId };
                 if (event.input !== undefined)
-                    part.input = event.input;
+                    part.input = compactToolValue(event.input);
                 break;
             }
             case 'approval-resolved': {
@@ -59,6 +80,18 @@ export class AssistantProjection {
         }
         this.revisionCounter += 1;
     }
+    /** A file sent to the user, shown where the agent sent it (the app renders images inline). */
+    addFile(file) {
+        this.closeTextSegment();
+        this.parts.push({
+            type: 'file',
+            mediaType: file.mediaType,
+            url: file.url,
+            filename: file.name,
+            providerMetadata: { dinox: { resourceId: file.resourceId } },
+        });
+        this.revisionCounter += 1;
+    }
     /** Closes streaming parts; called once when the turn ends. */
     finish() {
         for (const part of this.parts) {
@@ -93,13 +126,16 @@ export class AssistantProjection {
         if (index !== undefined)
             return this.parts[index];
         // A tool call closes the text segment before it.
-        const last = this.parts.at(-1);
-        if (last && (last.type === 'text' || last.type === 'reasoning'))
-            last.state = 'done';
+        this.closeTextSegment();
         const part = { type: 'dynamic-tool', toolCallId, toolName, state: 'input-streaming', input: undefined };
         this.toolIndex.set(toolCallId, this.parts.push(part) - 1);
         return part;
     }
+    closeTextSegment() {
+        const last = this.parts.at(-1);
+        if (last && (last.type === 'text' || last.type === 'reasoning'))
+            last.state = 'done';
+    }
     findToolByApproval(approvalId) {
         return this.parts.find((part) => part.type === 'dynamic-tool' && part.approval?.id === approvalId);
     }
@@ -108,26 +144,27 @@ export class AssistantProjection {
         if (event.title)
             part.toolName = event.title;
         if (event.input !== undefined)
-            part.input = event.input;
+            part.input = compactToolValue(event.input);
+        const output = event.output === undefined ? undefined : compactToolValue(event.output);
         switch (event.status) {
             case 'completed':
                 part.state = 'output-available';
-                part.output = event.output ?? part.output ?? null;
+                part.output = output ?? part.output ?? null;
                 break;
             case 'failed':
                 part.state = 'output-error';
-                part.errorText = typeof event.output === 'string' ? event.output : 'Tool failed';
+                part.errorText = typeof output === 'string' ? output : 'Tool failed';
                 break;
             case 'pending':
             case 'running':
                 if (part.state !== 'approval-requested')
                     part.state = 'input-available';
-                if (event.output !== undefined)
-                    part.output = event.output;
+                if (output !== undefined)
+                    part.output = output;
                 break;
             default:
-                if (event.output !== undefined)
-                    part.output = event.output;
+                if (output !== undefined)
+                    part.output = output;
         }
     }
 }

package/dist/gateway/detect.js

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION } from '@agentclientprotocol/sdk';
+import { agentLaunch } from './spawnAgent.js';
 import { getPackageVersion } from '../utils/version.js';
 /**
  * Known agents that speak ACP over stdio. Each lists launch variants in order;
@@ -70,7 +71,10 @@ export async function findExecutable(name, envPath = process.env.PATH ?? '') {
 }
 /** Starts the agent, runs `initialize`, and stops it. Never leaves the process running. */
 export async function probeAcpAgent(command, args, timeoutMs = PROBE_TIMEOUT_MS) {
-    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'ignore'], env: process.env, windowsHide: true });
+    const launch = agentLaunch(command, args, { stdio: ['pipe', 'pipe', 'ignore'], env: process.env, windowsHide: true });
+    const child = spawn(launch.command, launch.args, launch.options);
+    if (!child.stdin || !child.stdout)
+        throw new Error('ACP probe stdio was not piped');
     let timer;
     try {
         const exited = new Promise((_, reject) => {
@@ -97,7 +101,7 @@ export async function probeAcpAgent(command, args, timeoutMs = PROBE_TIMEOUT_MS)
     }
     finally {
         clearTimeout(timer);
-        child.stdin.destroy();
+        child.stdin?.destroy();
         child.kill('SIGTERM');
     }
 }

package/dist/gateway/deviceHost.d.ts

@@ -1,7 +1,7 @@
 import { wsconnect } from '@nats-io/nats-core';
 import type { AbstractPowerSyncDatabase } from '@powersync/common';
 import type { GatewaySettingsPatch } from './config.js';
-import type { GatewayAdapter, GatewayDefinition } from './types.js';
+import type { GatewayAdapter, GatewayDefinition, GatewayFileSource, GatewaySentFile } from './types.js';
 export declare const DEFAULT_NATS_CREDENTIALS_URL = "https://aisdk.chatgo.pro/api/nats/credentials";
 type Logger = (message: string, details?: Record<string, unknown>) => void;
 export type DeviceHostState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'error';
@@ -59,6 +59,8 @@ export declare class GatewayDeviceHost {
     /** Latest event per run while offline; the snapshot model makes older ones redundant. */
     private readonly pendingEvents;
     constructor(deps: DeviceHostDeps);
+    /** A `send_file` from the Dinox tools of one of this gateway's sessions; `null` when the token is another's. */
+    sendFile(token: string, file: GatewayFileSource): Promise<GatewaySentFile> | null;
     start(): void;
     stop(): Promise<void>;
     status(): DeviceHostStatus;

package/dist/gateway/deviceHost.js

@@ -7,6 +7,7 @@ import { isAgentConfigQuery, isAgentFoldersQuery, isAgentSettingsQuery, isCancel
 import { GatewayRunExecutor, MAX_QUEUED_TURNS, QueueFullError } from './runExecutor.js';
 import { RunStreamPublisher } from './streamPublisher.js';
 import { findRun, readRecentSessionFolders, resolveTrustedResource, TERMINAL_RUN_STATUSES, threadExists, } from './threadStore.js';
+import { uploadToOfficialStorage } from './fileUpload.js';
 import { agentHomeFolder, ensureAgentHomeFolder, existingWorkspaceFolders, listWorkspaceFolders, resolveWorkspaceFolder, WorkspaceFolderError, } from './workspaceFolders.js';
 export const DEFAULT_NATS_CREDENTIALS_URL = 'https://aisdk.chatgo.pro/api/nats/credentials';
 const CREDENTIALS_TIMEOUT_MS = 10_000;
@@ -68,8 +69,13 @@ export class GatewayDeviceHost {
             adapter: deps.adapter,
             log: deps.log,
             keepAwake: deps.keepAwake,
+            uploadFile: (file) => uploadToOfficialStorage({ db: deps.db, userId: deps.userId, authorization: deps.authorization, fetchImpl: deps.fetchImpl }, file),
         });
     }
+    /** A `send_file` from the Dinox tools of one of this gateway's sessions; `null` when the token is another's. */
+    sendFile(token, file) {
+        return this.deps.adapter.sendFile?.(token, file) ?? null;
+    }
     start() {
         this.stopped = false;
         void this.connect();

package/dist/gateway/fileUpload.d.ts

@@ -0,0 +1,12 @@
+import type { AbstractPowerSyncDatabase } from '@powersync/common';
+import type { GatewayFileSource, GatewaySentFile } from './types.js';
+export declare const MAX_SENT_FILE_BYTES: number;
+export type OfficialUploadDeps = {
+    db: AbstractPowerSyncDatabase;
+    userId: string;
+    authorization: string;
+    fetchImpl?: typeof fetch;
+    /** Overrides the API host (tests). */
+    apiBaseUrl?: string;
+};
+export declare function uploadToOfficialStorage(deps: OfficialUploadDeps, source: GatewayFileSource): Promise<GatewaySentFile>;

package/dist/gateway/fileUpload.js

@@ -0,0 +1,154 @@
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { getTableColumns } from '../commands/storage/repo/configs.js';
+import { generateThumbnailBuffer, loadSharp } from '../commands/storage/repo/remote.js';
+import { OFFICIAL_STORAGE_PROVIDER } from '../commands/storage/repo/shared.js';
+import { buildObjectId, generateThumbnailKey, guessContentType } from '../commands/storage/repo/targets.js';
+import { POWERSYNC_DEFAULT_UPLOAD_BASE_URL } from '../config/serviceEndpoints.js';
+import { toAuthorizationHeaderValue } from '../utils/authToken.js';
+import { generateId } from '../utils/id.js';
+/**
+ * Files an agent hands to the user leave this computer through the official
+ * Dinox storage, the way the app uploads attachments: the API signs a PUT URL,
+ * the bytes go straight to OSS, and a `c_resource` row (synced by PowerSync)
+ * records them. The message only carries the public URL, never the bytes.
+ */
+const OFFICIAL_DOMAIN = 'https://dinoai.oss-accelerate.aliyuncs.com';
+const OFFICIAL_ENDPOINT = 'https://oss-accelerate.aliyuncs.com';
+const OFFICIAL_BUCKET = 'dinoai';
+const CODE_OK = '000000';
+const SIGN_TIMEOUT_MS = 20_000;
+const PUT_TIMEOUT_MS = 120_000;
+export const MAX_SENT_FILE_BYTES = 50 * 1024 * 1024;
+const EXTENSION_BY_MEDIA_TYPE = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/svg+xml': 'svg',
+    'application/pdf': 'pdf',
+    'text/plain': 'txt',
+    'text/markdown': 'md',
+};
+function categoryFor(mediaType) {
+    if (mediaType.startsWith('image/'))
+        return 'images';
+    if (mediaType.startsWith('video/'))
+        return 'videos';
+    if (mediaType.startsWith('audio/'))
+        return 'audios';
+    return 'files';
+}
+async function readSource(source) {
+    if (source.kind === 'data') {
+        const bytes = Buffer.from(source.data, 'base64');
+        const extension = EXTENSION_BY_MEDIA_TYPE[source.mediaType];
+        const name = source.name?.trim() || `file${extension ? `.${extension}` : ''}`;
+        if (bytes.byteLength > MAX_SENT_FILE_BYTES)
+            throw new Error(`${name} is larger than 50 MB`);
+        return { bytes, name, mediaType: source.mediaType };
+    }
+    const stats = await fsp.stat(source.path).catch(() => null);
+    if (!stats?.isFile())
+        throw new Error(`Not a file: ${source.path}`);
+    if (stats.size > MAX_SENT_FILE_BYTES)
+        throw new Error(`${path.basename(source.path)} is larger than 50 MB`);
+    return {
+        bytes: await fsp.readFile(source.path),
+        name: source.name?.trim() || path.basename(source.path),
+        mediaType: guessContentType(source.path),
+    };
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    return fetchImpl(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+}
+/** A presigned PUT URL for `key` from the Dinox API. */
+async function signPut(deps, key, contentType) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const response = await fetchWithTimeout(fetchImpl, `${deps.apiBaseUrl ?? POWERSYNC_DEFAULT_UPLOAD_BASE_URL}/oss/generatePreSignedUrl`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            accept: 'application/json',
+            Authorization: toAuthorizationHeaderValue(deps.authorization),
+        },
+        body: JSON.stringify({ objectId: key, contentType }),
+    }, SIGN_TIMEOUT_MS);
+    const body = (await response.json().catch(() => null));
+    const url = body?.data?.url;
+    if (!response.ok || body?.code !== CODE_OK || typeof url !== 'string' || !url) {
+        throw new Error(`Signing the upload failed (${response.status}${body?.msg ? `: ${String(body.msg)}` : ''})`);
+    }
+    return url;
+}
+async function putObject(deps, key, bytes, contentType) {
+    const signedUrl = await signPut(deps, key, contentType);
+    const response = await fetchWithTimeout(deps.fetchImpl ?? fetch, signedUrl, { method: 'PUT', headers: { 'Content-Type': contentType }, body: new Uint8Array(bytes) }, PUT_TIMEOUT_MS);
+    if (!response.ok)
+        throw new Error(`Uploading failed (${response.status})`);
+    return response.headers.get('etag');
+}
+/** The thumbnail the app shows in lists; optional, so a missing image library never fails the upload. */
+async function uploadThumbnail(deps, key, bytes) {
+    try {
+        const sharp = await loadSharp();
+        const thumbnail = await generateThumbnailBuffer(sharp, bytes);
+        const thumbnailKey = generateThumbnailKey(key);
+        await putObject(deps, thumbnailKey, thumbnail, 'image/webp');
+        return `${OFFICIAL_DOMAIN}/${thumbnailKey}`;
+    }
+    catch {
+        return null;
+    }
+}
+async function insertResource(db, values) {
+    // Only the columns this schema version has, like `dino storage upload`.
+    const columns = await getTableColumns(db, 'c_resource');
+    const entries = Object.entries(values).filter(([column]) => columns.has(column));
+    await db.execute(`INSERT INTO c_resource (${entries.map(([column]) => column).join(', ')}) VALUES (${entries.map(() => '?').join(', ')})`, entries.map(([, value]) => value));
+}
+export async function uploadToOfficialStorage(deps, source) {
+    const { bytes, name, mediaType } = await readSource(source);
+    const category = categoryFor(mediaType);
+    const extension = path.extname(name) || (EXTENSION_BY_MEDIA_TYPE[mediaType] ? `.${EXTENSION_BY_MEDIA_TYPE[mediaType]}` : '');
+    const key = buildObjectId(deps.userId, category, `file${extension}`);
+    const etag = await putObject(deps, key, bytes, mediaType);
+    const url = `${OFFICIAL_DOMAIN}/${key}`;
+    const thumbnailUrl = category === 'images' && mediaType !== 'image/svg+xml' ? await uploadThumbnail(deps, key, bytes) : null;
+    const id = generateId();
+    const now = new Date().toISOString();
+    // Same row the app writes for an official upload (the thumbnail URL lives in `checksum`).
+    await insertResource(deps.db, {
+        id,
+        user_id: deps.userId,
+        name,
+        mime_type: mediaType,
+        size_bytes: bytes.byteLength,
+        storage_config_id: null,
+        storage_key: key,
+        storage_url: url,
+        storage_provider: OFFICIAL_STORAGE_PROVIDER,
+        bucket: OFFICIAL_BUCKET,
+        is_public: 0,
+        created_at: now,
+        updated_at: now,
+        is_del: 0,
+        status: 'uploaded',
+        uploaded_at: now,
+        etag: etag ?? '',
+        checksum: thumbnailUrl ?? '',
+        category,
+        width: 0,
+        height: 0,
+        duration: 0,
+        endpoint: OFFICIAL_ENDPOINT,
+        domain: OFFICIAL_DOMAIN,
+        extra_data: '{}',
+        deleted_at: null,
+        content_sha256: crypto.createHash('sha256').update(bytes).digest('hex'),
+        content_md: null,
+        summary: null,
+    });
+    return { resourceId: id, url, name, mediaType, sizeBytes: bytes.byteLength };
+}

package/dist/gateway/mcpEnv.d.ts

@@ -0,0 +1,5 @@
+/** Environment the gateway starts `dino gateway mcp` with, for each agent session. */
+/** Names the session whose turn a `send_file` belongs to. */
+export declare const GATEWAY_SESSION_TOKEN_ENV = "DINOX_GATEWAY_SESSION_TOKEN";
+/** `0` offers only `send_file`: the owner turned the knowledge tools off. */
+export declare const GATEWAY_KNOWLEDGE_TOOLS_ENV = "DINOX_GATEWAY_KNOWLEDGE_TOOLS";

package/dist/gateway/mcpEnv.js

@@ -0,0 +1,5 @@
+/** Environment the gateway starts `dino gateway mcp` with, for each agent session. */
+/** Names the session whose turn a `send_file` belongs to. */
+export const GATEWAY_SESSION_TOKEN_ENV = 'DINOX_GATEWAY_SESSION_TOKEN';
+/** `0` offers only `send_file`: the owner turned the knowledge tools off. */
+export const GATEWAY_KNOWLEDGE_TOOLS_ENV = 'DINOX_GATEWAY_KNOWLEDGE_TOOLS';

package/dist/gateway/mcpServer.d.ts

@@ -1,4 +1,14 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export type DaemonCall = (method: string, params?: unknown) => Promise<unknown>;
-export declare function createDinoxMcpServer(call?: DaemonCall): McpServer;
+export type DaemonCall = (method: string, params?: unknown, options?: {
+    timeoutMs?: number;
+}) => Promise<unknown>;
+export type DinoxMcpOptions = {
+    /** Offer the knowledge tools (notes, todos, conversations); default true. */
+    knowledgeTools?: boolean;
+    /** The session `send_file` belongs to; absent, `send_file` is not offered. */
+    sessionToken?: string;
+    /** Resolves relative `send_file` paths; default the process directory. */
+    cwd?: string;
+};
+export declare function createDinoxMcpServer(call?: DaemonCall, options?: DinoxMcpOptions): McpServer;
 export declare function serveDinoxMcpOverStdio(): Promise<void>;

package/dist/gateway/mcpServer.js

@@ -1,25 +1,57 @@
+import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { sendDaemonRequest } from '../daemon/client.js';
+import { GATEWAY_KNOWLEDGE_TOOLS_ENV, GATEWAY_SESSION_TOKEN_ENV } from './mcpEnv.js';
 import { READ_CONVERSATION_MAX_LIMIT } from './conversationContext.js';
 import { getPackageVersion } from '../utils/version.js';
 /**
- * Dinox knowledge tools for gateway agents, served over stdio MCP. The agent
- * launches this as a child process (`dino gateway mcp`); every read goes
- * through the daemon, which owns the database. Read-only by design: writes
- * from a third-party agent would bypass the app's approval flow.
+ * Dinox tools for gateway agents, served over stdio MCP. The agent launches
+ * this as a child process (`dino gateway mcp`); every call goes through the
+ * daemon, which owns the database. The knowledge tools are read-only by
+ * design: writes from a third-party agent would bypass the app's approval
+ * flow. `send_file` only adds a file to the reply the agent is writing.
  */
 const MAX_NOTE_CHARS = 20_000;
 const MAX_RESULTS = 50;
+/** Uploading a large file can take a while; the daemon's default request timeout is 10s. */
+const SEND_FILE_TIMEOUT_MS = 150_000;
 function text(value) {
     return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
 }
 function failure(error) {
     return { ...text(`Dinox is unavailable: ${error instanceof Error ? error.message : String(error)}`), isError: true };
 }
-export function createDinoxMcpServer(call = (method, params) => sendDaemonRequest(method, params)) {
+export function createDinoxMcpServer(call = (method, params, options) => sendDaemonRequest(method, params, options), options = {}) {
     const server = new McpServer({ name: 'dinox', version: getPackageVersion() });
+    if (options.sessionToken)
+        registerSendFile(server, call, options.sessionToken, options.cwd ?? process.cwd());
+    if (options.knowledgeTools !== false)
+        registerKnowledgeTools(server, call);
+    return server;
+}
+function registerSendFile(server, call, sessionToken, cwd) {
+    server.registerTool('send_file', {
+        description: 'Show the user a file from this computer (an image you generated, a document, a chart, ...). The user talks to ' +
+            'you from the Dinox app and cannot open files on this computer, so a path alone is useless to them: call this ' +
+            'for every file they should see, then answer as usual. Images appear in the reply; other files as attachments. ' +
+            'Up to 50 MB per file.',
+        inputSchema: {
+            path: z.string().describe('Absolute path of the file (relative paths resolve from your working directory)'),
+            name: z.string().optional().describe('File name to show; defaults to the file name in the path'),
+        },
+    }, async ({ path: filePath, name }) => {
+        try {
+            const sent = (await call('gateway.sendFile', { token: sessionToken, path: path.resolve(cwd, filePath), ...(name ? { name } : {}) }, { timeoutMs: SEND_FILE_TIMEOUT_MS }));
+            return text({ sent: true, name: sent.name, mediaType: sent.mediaType });
+        }
+        catch (error) {
+            return { ...text(`Sending the file failed: ${error instanceof Error ? error.message : String(error)}`), isError: true };
+        }
+    });
+}
+function registerKnowledgeTools(server, call) {
     server.registerTool('search_notes', {
         description: "Search the user's Dinox notes by keyword. Returns id, title, summary, tags and folders; use read_note for full content.",
         inputSchema: {
@@ -129,10 +161,12 @@ export function createDinoxMcpServer(call = (method, params) => sendDaemonReques
             return failure(error);
         }
     });
-    return server;
 }
 export async function serveDinoxMcpOverStdio() {
-    const server = createDinoxMcpServer();
+    const server = createDinoxMcpServer(undefined, {
+        knowledgeTools: process.env[GATEWAY_KNOWLEDGE_TOOLS_ENV] !== '0',
+        sessionToken: process.env[GATEWAY_SESSION_TOKEN_ENV]?.trim() || undefined,
+    });
     await server.connect(new StdioServerTransport());
     await new Promise((resolve) => process.stdin.once('close', resolve));
 }

package/dist/gateway/runExecutor.d.ts

@@ -1,9 +1,11 @@
 import type { AbstractPowerSyncDatabase } from '@powersync/common';
 import type { RemoteDeviceRunRequest, RemoteDeviceToolApprovalAckCode } from '../vendor/electron/shared/remote-device-agent.js';
 import type { RunSnapshot } from './streamPublisher.js';
-import type { GatewayAdapter, GatewayDefinition } from './types.js';
+import type { GatewayAdapter, GatewayDefinition, GatewayFileSource, GatewaySentFile } from './types.js';
 /** Turns waiting behind a thread's active one; more are refused as `busy`. */
 export declare const MAX_QUEUED_TURNS = 10;
+/** Files one reply may carry, like the attachments of one message. */
+export declare const MAX_SENT_FILES_PER_TURN = 16;
 /** How long a turn waits for the client's latest messages to sync to this machine. */
 export declare const CLIENT_TAIL_SYNC_TIMEOUT_MS = 5000;
 type Logger = (message: string, details?: Record<string, unknown>) => void;
@@ -21,9 +23,15 @@ export type RunExecutorDeps = {
     clientTailSyncTimeoutMs?: number;
     /** Keeps the computer awake while a turn runs; returns the release. */
     keepAwake?: () => () => void;
+    /** Uploads a file the agent sends to the user; absent, sending files fails. */
+    uploadFile?: (file: GatewayFileSource) => Promise<GatewaySentFile>;
 };
 /** The user's instructions for the agent, as the start of a new session. */
 export declare function agentInstructionsPreamble(instructions: string): string | undefined;
+/** How the user sees this conversation, so the agent hands over files instead of printing their paths. */
+export declare const SESSION_DELIVERY_NOTE: string;
+/** What a new session starts with: how replies reach the user, then the user's instructions. */
+export declare function sessionPreamble(instructions: string): string;
 /**
  * Runs accepted turns on one gateway. A thread has at most one active run;
  * turns sent meanwhile wait in a per-thread FIFO and, when it ends, run

package/dist/gateway/runExecutor.js

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import { AssistantProjection, projectPendingApprovals, toTranscriptMessage } from './assistantProjection.js';
 import { CONTEXT_MESSAGE_LIMIT, withConversationContext } from './conversationContext.js';
-import { commitRunTerminal, enqueueRun, finishMergedRun, startQueuedRuns, withdrawQueuedRun, readAgentInstructions, readCurrentTopic, readSessionBinding, readTranscriptPage, resolveTrustedResource, updateRunSnapshot, waitForMessage, withGatewaySession, writeSessionBinding, } from './threadStore.js';
+import { commitRunTerminal, enqueueRun, finishMergedRun, startQueuedRuns, TERMINAL_RUN_STATUSES, withdrawQueuedRun, readAgentInstructions, readCurrentTopic, readSessionBinding, readTranscriptPage, resolveTrustedResource, updateRunSnapshot, waitForMessage, withGatewaySession, writeSessionBinding, } from './threadStore.js';
 import { readAgentConfig } from './protocol.js';
 const SNAPSHOT_PERSIST_INTERVAL_MS = 1_000;
 /** Turns waiting behind a thread's active one; more are refused as `busy`. */
@@ -9,6 +9,8 @@ export const MAX_QUEUED_TURNS = 10;
 const APPROVAL_TIMEOUT_MS = 30 * 60 * 1000;
 /** The agent's instructions travel with a new session's first prompt; longer ones are cut. */
 const MAX_INSTRUCTIONS_CHARS = 8_000;
+/** Files one reply may carry, like the attachments of one message. */
+export const MAX_SENT_FILES_PER_TURN = 16;
 /** How long a turn waits for the client's latest messages to sync to this machine. */
 export const CLIENT_TAIL_SYNC_TIMEOUT_MS = 5_000;
 /** Client tails that never synced, so later turns of their thread do not wait for them again. */
@@ -40,6 +42,17 @@ export function agentInstructionsPreamble(instructions) {
         '</dinox_agent_instructions>',
     ].join('\n');
 }
+/** How the user sees this conversation, so the agent hands over files instead of printing their paths. */
+export const SESSION_DELIVERY_NOTE = [
+    '<dinox_delivery>',
+    'The user reads your replies in the Dinox app, usually on another device, and cannot open files on this computer.',
+    'To show them a file you made or found (an image, a document, a chart, ...), call the Dinox send_file tool with its path.',
+    '</dinox_delivery>',
+].join('\n');
+/** What a new session starts with: how replies reach the user, then the user's instructions. */
+export function sessionPreamble(instructions) {
+    return [SESSION_DELIVERY_NOTE, agentInstructionsPreamble(instructions)].filter(Boolean).join('\n\n');
+}
 function withErrorText(message, error) {
     return { ...message, metadata: { ...(message.metadata ?? {}), error } };
 }
@@ -261,6 +274,30 @@ export class GatewayRunExecutor {
             return decision;
         };
         const awaitApproval = registerApproval;
+        // Uploads still running when the agent ends its turn finish before the reply is committed.
+        const uploads = new Set();
+        let filesSent = 0;
+        const sendFile = (file) => {
+            const upload = this.deps.uploadFile;
+            if (!upload)
+                return Promise.reject(new Error('Sending files is not available on this computer'));
+            if (filesSent >= MAX_SENT_FILES_PER_TURN) {
+                return Promise.reject(new Error(`At most ${MAX_SENT_FILES_PER_TURN} files can be sent in one reply`));
+            }
+            filesSent += 1;
+            const pending = upload(file).then((sent) => {
+                projection.addFile(sent);
+                // Once the turn has ended, the terminal snapshot carries the file.
+                if (!TERMINAL_RUN_STATUSES.has(status))
+                    publish(true);
+                return sent;
+            });
+            uploads.add(pending);
+            void pending
+                .catch((error) => log('send file failed', { runId: active.runId, error: String(error) }))
+                .finally(() => uploads.delete(pending));
+            return pending;
+        };
         let errorText = null;
         let nextBinding = null;
         try {
@@ -286,12 +323,13 @@ export class GatewayRunExecutor {
             const result = await adapter.runTurn({
                 sessionId: continued?.sessionId ?? null,
                 cwd,
-                sessionPreamble: agentInstructionsPreamble(instructions),
+                sessionPreamble: this.deps.uploadFile ? sessionPreamble(instructions) : agentInstructionsPreamble(instructions),
                 prompt: withConversationContext(prompt, context, { canReadConversation: gateway.dinoxTools !== false }),
                 resources,
                 signal: active.controller.signal,
                 config: agentConfig,
                 awaitApproval,
+                sendFile,
                 onEvent: (event) => {
                     projection.apply(event);
                     if (event.type === 'approval-request') {
@@ -301,6 +339,8 @@ export class GatewayRunExecutor {
                     publish(event.type === 'approval-request' || event.type === 'approval-resolved');
                 },
             });
+            // Files still uploading belong to this reply: the turn ends once they are in it.
+            await Promise.allSettled([...uploads]);
             nextBinding = {
                 sessionId: result.sessionId,
                 topicId,
@@ -326,6 +366,7 @@ export class GatewayRunExecutor {
             for (const approval of active.approvals.values())
                 clearTimeout(approval.timer);
         }
+        await Promise.allSettled([...uploads]);
         projection.finish();
         const assistant = errorText ? withErrorText(projection.snapshot(), errorText) : projection.snapshot();
         try {

package/dist/gateway/service.d.ts

@@ -1,5 +1,6 @@
 import type { AbstractPowerSyncDatabase } from '@powersync/common';
 import { type DeviceHostStatus } from './deviceHost.js';
+import type { GatewayFileSource, GatewaySentFile } from './types.js';
 type Logger = (message: string, details?: Record<string, unknown>) => void;
 export type GatewayServiceDeps = {
     db: AbstractPowerSyncDatabase;
@@ -25,6 +26,8 @@ export declare class GatewayService {
     /** Saves a change made in the app, applies it to the running gateway and syncs the robot row. */
     private updateSettings;
     private robotRegistration;
+    /** Routes a `send_file` from an agent's Dinox tools to the turn of the session that started them. */
+    sendFile(token: string, file: GatewayFileSource): Promise<GatewaySentFile>;
     status(): DeviceHostStatus[];
 }
 export {};

package/dist/gateway/service.js

@@ -105,6 +105,15 @@ export class GatewayService {
             },
         };
     }
+    /** Routes a `send_file` from an agent's Dinox tools to the turn of the session that started them. */
+    sendFile(token, file) {
+        for (const host of this.hosts) {
+            const sent = host.sendFile(token, file);
+            if (sent)
+                return sent;
+        }
+        return Promise.reject(new Error('This conversation is no longer running on this computer'));
+    }
     status() {
         return this.hosts.map((host) => host.status());
     }

package/dist/gateway/spawnAgent.d.ts

@@ -0,0 +1,12 @@
+import type { SpawnOptions } from 'node:child_process';
+export type AgentLaunch = {
+    command: string;
+    args: readonly string[];
+    options: SpawnOptions;
+};
+/**
+ * Node's `spawn` cannot execute a Windows `.cmd` / `.bat` directly: CreateProcess
+ * returns EINVAL. npm global shims are those files (`claude-agent-acp.CMD`).
+ * Launch them through `cmd.exe /d /s /c`, with the same argument array everywhere else.
+ */
+export declare function agentLaunch(command: string, args: readonly string[], options: SpawnOptions, platform?: NodeJS.Platform): AgentLaunch;

package/dist/gateway/spawnAgent.js

@@ -0,0 +1,32 @@
+const WINDOWS_BATCH = /\.(?:cmd|bat)$/i;
+/** Characters cmd.exe would interpret if a batch path or argument reached the shell unquoted. */
+const CMD_METACHARACTERS = /[\0\r\n"&|<>^%]/;
+/**
+ * Node's `spawn` cannot execute a Windows `.cmd` / `.bat` directly: CreateProcess
+ * returns EINVAL. npm global shims are those files (`claude-agent-acp.CMD`).
+ * Launch them through `cmd.exe /d /s /c`, with the same argument array everywhere else.
+ */
+export function agentLaunch(command, args, options, platform = process.platform) {
+    if (platform !== 'win32' || !WINDOWS_BATCH.test(command)) {
+        return { command, args, options };
+    }
+    for (const part of [command, ...args]) {
+        if (CMD_METACHARACTERS.test(part)) {
+            throw new Error(`Cannot launch a Windows batch file containing shell metacharacters (${part})`);
+        }
+    }
+    const inner = [quoteCmdArg(command), ...args.map(quoteCmdArg)].join(' ');
+    return {
+        command: process.env.ComSpec || 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${inner}"`],
+        options: { ...options, windowsVerbatimArguments: true },
+    };
+}
+/** Quote one argv token for CommandLineToArgvW. Tokens without spaces stay bare. */
+function quoteCmdArg(value) {
+    if (value.length === 0)
+        return '""';
+    if (!/[\s"]/.test(value))
+        return value;
+    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, '$1$1')}"`;
+}

package/dist/gateway/types.d.ts

@@ -93,6 +93,25 @@ export type GatewayConfigOption = {
         group: string | null;
     }>;
 };
+/** A file the agent hands to the user: a local path, or bytes it sent inline (base64). */
+export type GatewayFileSource = {
+    kind: 'path';
+    path: string;
+    name?: string;
+} | {
+    kind: 'data';
+    data: string;
+    mediaType: string;
+    name?: string;
+};
+/** A file uploaded for the user, as it appears in the reply. */
+export type GatewaySentFile = {
+    resourceId: string;
+    url: string;
+    name: string;
+    mediaType: string;
+    sizeBytes: number;
+};
 export type GatewayStopReason = 'end_turn' | 'cancelled' | 'max_tokens' | 'refusal' | 'error';
 export type GatewayTurnInput = {
     /** Agent session to continue; absent starts a new one. */
@@ -114,6 +133,8 @@ export type GatewayTurnInput = {
     onEvent: (event: GatewayEvent) => void;
     /** Resolves with the user's decision for an `approval-request` event. */
     awaitApproval: (approvalId: string) => Promise<boolean>;
+    /** Uploads a file for the user and adds it to the reply. */
+    sendFile: (file: GatewayFileSource) => Promise<GatewaySentFile>;
 };
 export type GatewayTurnResult = {
     sessionId: string;
@@ -132,5 +153,11 @@ export interface GatewayAdapter {
     runTurn(input: GatewayTurnInput): Promise<GatewayTurnResult>;
     /** The agent's session settings (models, modes); absent when it has none. */
     describeConfig?(): Promise<GatewayConfigOption[]>;
+    /**
+     * A `send_file` call from the Dinox tools of one of this adapter's sessions,
+     * named by the token the session's tools were started with; `null` when the
+     * token is not this adapter's.
+     */
+    sendFile?(token: string, file: GatewayFileSource): Promise<GatewaySentFile> | null;
     dispose(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dinoxx/dinox-cli",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "description": "Dinox CLI",
   "main": "dist/dinox.js",
   "scripts": {