@inferencesh/sdk 0.22.1 → 0.24.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Client tools can return files. A `ClientToolHandlerFn` may return `{ result: string; attachments?: FileRef[] }` (new `ClientToolResult` type) besides a string; the files are uploaded first with POST /files (`client.files.upload`, the chat's `uploadFile`) and sent as `attachments` with the result. Images reach the model as image input when it supports images. `submitToolResult` (agent api, `Agent`, `AgentsAPI`, the React chat actions) takes optional `attachments`, sent only when non-empty. `ToolResultRequest.attachments` is added by hand to the generated types until the next `make types` picks it up from the API. String returns work as before.
+
+## [0.23.0] - 2026-10-11
+
+### Changed
+
+- Generated types follow the API: `MessageInput` (what an agent run takes), `ContextField.in_prompt`, `ApiAgentRunRequest` takes `agent_id`/`agent_version_id` and no `channel_context`; `CreateAgentMessageRequest` is gone. Per-function `credentials` and annotations on `AppFunction`, and `DeployWarning` on `AppVersionDTO` (INF-1053). `ScopesResponse.account_groups`. Agent events for subagent ids, context, limits and account.
+- Dev dependency lockfile refreshed for security advisories (handlebars, devalue, sharp). Nothing shipped in the package changes.
+
+### Deprecated
+
+- `SendMessageOptions.channel_context`. The API no longer reads a channel context from an agent run request; a chat's routing comes from the server's own channel receivers. The option is still accepted and is not sent. Chats still return `channel_context`.
+
+### Added
+
+- `StreamableManager` reconnects on opt-in: `reconnect: true | { maxAttempts, baseDelayMs, maxDelayMs, idleTimeoutMs }` (defaults 10, 1000, 30000, 30000). A failed stream is retried with jittered exponential backoff; any line received, heartbeats included, resets the failure count; a stream silent for `idleTimeoutMs` is reconnected; in a browser, `online` or the tab becoming visible retries at once. A 4xx other than 408/429 is not retried. `onRetry(error, attempt, delayMs)` reports each scheduled retry; `onReconnect(attempt)` runs after a retry connects and before the new stream is read, so the caller can fetch what it missed. With `reconnect`, `onError` fires only when the manager gives up. `StreamReconnectOptions` is exported. Without the option nothing changes.
+
+### Fixed
+
+- The React chat (`AgentChatProvider`) no longer stays busy after a network blip mid-turn (Chromium `ERR_NETWORK_CHANGED`, "Stream error: TypeError: network error"). The chat stream reconnects; each reconnect refetches the chat and its messages, so a turn that finished while disconnected ends and `onTurnEnd` fires. `connectionStatus` is `'connecting'` while it waits to retry and `'error'` (with `error` set) once it gives up. Whenever the stream ends on its own and the chat is still busy, the chat is polled until idle. A stop, reset or chat switch during a pending retry leaves the new state alone.
+- `Agent.sendMessage`/`startStreaming` and `tasks.run`/`watch` in streaming mode survive a network error: the stream reconnects and refetches the chat (with its messages) or the task, so the wait settles when it finished meanwhile. A 4xx refusal still rejects at once; other errors reject once the stream stops retrying.
+
+- The package loads in plain Node (no bundler). 0.22.1's dist used extensionless relative imports, so `import("@inferencesh/sdk")` and every subpath except `proxy` and `internal/upload` failed with ERR_MODULE_NOT_FOUND. The build now uses NodeNext resolution with `.js` import specifiers, and `@inferencesh/sdk/proxy/nextjs` imports `next/server.js`. `require()` of every subpath works on Node >=22.12. CI and publish load each export of the packed tarball (`pnpm run check:exports`).
+
 ## [0.22.1] - 2026-10-10
 
 ### Fixed

package/dist/agent/actions.d.ts

@@ -4,6 +4,6 @@
  * Action creators that handle side effects (API calls, streaming).
  * These are created once per provider instance with access to dispatch.
  */
-import type { ActionsContext, ActionsResult } from './types';
+import type { ActionsContext, ActionsResult } from './types.js';
 export declare function createActions(ctx: ActionsContext): ActionsResult;
-export declare function getClientToolHandlers(config: import('./types').AgentOptions | null): Map<string, import('./types').ClientToolHandlerFn>;
+export declare function getClientToolHandlers(config: import('./types.js').AgentOptions | null): Map<string, import('./types.js').ClientToolHandlerFn>;

package/dist/agent/actions.js

@@ -4,22 +4,57 @@
  * Action creators that handle side effects (API calls, streaming).
  * These are created once per provider instance with access to dispatch.
  */
-import { ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, } from '../types';
-import { isChatBusy, isMessageTerminal, isRunInterrupted, isRunWorking } from '../utils';
-import { StreamableManager } from '../http/streamable';
-import { PollManager } from '../http/poll';
-import { createLLMDeltaAccumulator } from '../delta';
-import { isAdHocConfig, extractClientToolHandlers } from './types';
-import * as api from './api';
-import { buildMCPInputResult } from './mcp-input';
-import { isInferenceError } from '../http/errors';
+import { ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, } from '../types.js';
+import { isChatBusy, isMessageTerminal, isRunInterrupted, isRunWorking } from '../utils.js';
+import { StreamableManager } from '../http/streamable.js';
+import { PollManager } from '../http/poll.js';
+import { createLLMDeltaAccumulator } from '../delta.js';
+import { isAdHocConfig, extractClientToolHandlers } from './types.js';
+import * as api from './api.js';
+import { buildMCPInputResult } from './mcp-input.js';
+import { isInferenceError } from '../http/errors.js';
 // =============================================================================
 // Action Creators
 // =============================================================================
+/** Up to about ten minutes of backoff (1s doubling to 30s, jittered) before a tool result is given up. */
+const TOOL_RESULT_MAX_ATTEMPTS = 25;
+/** A failure a retry can get past: no response at all, a 5xx, a 408 or a 429. */
+function isTransient(err) {
+    const status = err?.statusCode;
+    if (typeof status !== 'number')
+        return true;
+    return status >= 500 || status === 408 || status === 429;
+}
 export function createActions(ctx) {
     const dispatchedToolInvocations = new Set();
     const { client, dispatch, getState, getConfig, getChatId, getClientToolHandlers, getStreamManager, setStreamManager, getStreamEnabled, getPollIntervalMs, callbacks } = ctx;
     let prevChatWasBusy = false;
+    // Bumped by every streamChat() and stopStream(). A stream whose generation
+    // is no longer current (stopped, reset, switched to another chat) leaves
+    // state alone, including work it started before that.
+    let streamGeneration = 0;
+    // A client tool's result is the only way its turn continues: the server
+    // waits on it. A result lost to a network drop left the turn stuck on
+    // "running" for good, so it is sent again until it lands or is refused.
+    const deliverToolResult = async (invocationId, result, attachments) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                if (attachments?.length)
+                    await api.submitToolResult(client, invocationId, result, attachments);
+                else
+                    await api.submitToolResult(client, invocationId, result);
+                return;
+            }
+            catch (err) {
+                if (!isTransient(err) || attempt >= TOOL_RESULT_MAX_ATTEMPTS) {
+                    console.error(`[AgentSDK] Failed to submit tool result for ${invocationId}:`, err);
+                    return;
+                }
+                const step = Math.min(30000, 1000 * 2 ** (attempt - 1));
+                await new Promise((r) => setTimeout(r, step / 2 + Math.random() * (step / 2)));
+            }
+        }
+    };
     const checkTurnEnd = (chat) => {
         const busy = isChatBusy(chat);
         if (prevChatWasBusy && !busy) {
@@ -59,7 +94,7 @@ export function createActions(ctx) {
                     const handler = clientToolHandlers.get(functionName);
                     if (!handler) {
                         console.warn(`[AgentSDK] No handler for client tool: ${functionName}`);
-                        api.submitToolResult(client, invocation.id, JSON.stringify({
+                        deliverToolResult(invocation.id, JSON.stringify({
                             status: 'not_available',
                             message: `Client tool "${functionName}" is not available in this environment`,
                         }));
@@ -69,12 +104,12 @@ export function createActions(ctx) {
                     // Use Promise.resolve to handle both sync and async handlers
                     const args = invocation.function?.arguments || {};
                     Promise.resolve(handler(args))
-                        .then((result) => {
-                        api.submitToolResult(client, invocation.id, result);
-                    })
+                        .then((output) => typeof output === 'string'
+                        ? deliverToolResult(invocation.id, output)
+                        : deliverToolResult(invocation.id, output.result, output.attachments))
                         .catch((error) => {
                         console.error(`[AgentSDK] Client tool ${functionName} error:`, error);
-                        api.submitToolResult(client, invocation.id, JSON.stringify({
+                        return deliverToolResult(invocation.id, JSON.stringify({
                             error: String(error)
                         }));
                     });
@@ -83,6 +118,7 @@ export function createActions(ctx) {
         }
     };
     const streamChat = async (id) => {
+        const generation = ++streamGeneration;
         const existingManager = getStreamManager();
         if (existingManager) {
             existingManager.stop();
@@ -93,6 +129,9 @@ export function createActions(ctx) {
         try {
             // Fetch initial chat (fetchChat loads messages separately since Chat.Get no longer preloads them)
             const chat = await api.fetchChat(client, id);
+            // Stopped or switched to another chat while fetching.
+            if (generation !== streamGeneration)
+                return;
             if (chat) {
                 setChat(chat);
             }
@@ -108,11 +147,53 @@ export function createActions(ctx) {
             pollChat(id);
             return;
         }
+        // Token-by-token streaming state, one accumulator per message being
+        // streamed. Deltas name their message (DeltaEvent.resource_id), so state
+        // never leaks between messages the way a single shared accumulator allowed.
+        const deltaAccums = new Map();
+        const isCurrent = () => generation === streamGeneration;
+        let failed = false;
+        // The API does not replay what the stream missed: the chat as fetched is
+        // the source of truth. Messages are merged, so older pages stay loaded.
+        const resync = async () => {
+            const chat = await api.fetchChat(client, id);
+            if (!chat || !isCurrent())
+                return null;
+            for (const message of chat.chat_messages ?? []) {
+                updateMessage(message);
+            }
+            dispatch({ type: 'UPDATE_CHAT', payload: chat });
+            callbacks.onStatusChange?.(isChatBusy(chat) ? 'streaming' : 'idle');
+            checkTurnEnd(chat);
+            return chat;
+        };
         // Single unified stream with TypedEvents (both Chat and ChatMessage events)
         const manager = new StreamableManager({
             request: api.chatStreamRequest(client, id),
+            reconnect: true,
+            onRetry: (error, attempt, delayMs) => {
+                console.warn(`[AgentSDK] Stream error, reconnecting in ${delayMs}ms (attempt ${attempt}):`, error);
+                if (!isCurrent())
+                    return;
+                dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'connecting' });
+                callbacks.onStatusChange?.('connecting');
+            },
+            onReconnect: async () => {
+                // Partial text from before the drop is replaced by the fetched messages.
+                deltaAccums.clear();
+                if (!isCurrent())
+                    return;
+                dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'streaming' });
+                await resync();
+            },
             onError: (error) => {
+                // The manager gave up: a refusal, or every retry failed.
                 console.warn('[AgentSDK] Stream error:', error);
+                if (!isCurrent())
+                    return;
+                failed = true;
+                dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'error' });
+                dispatch({ type: 'SET_ERROR', payload: error.message });
                 callbacks.onError?.(error);
             },
             onStart: () => {
@@ -120,14 +201,28 @@ export function createActions(ctx) {
                 callbacks.onStatusChange?.('streaming');
             },
             onEnd: () => {
-                // Only reset if this is an unexpected stop (stream died, max reconnects exhausted).
-                // If stopStream() was called intentionally, it clears the manager ref first,
-                // so getStreamManager() will be undefined and we skip the duplicate dispatch.
-                if (getStreamManager()) {
-                    setStreamManager(undefined);
+                // An intentional stop or a newer stream skips all of this.
+                if (!isCurrent() || getStreamManager() !== manager)
+                    return;
+                // The stream ended cleanly or gave up. Release the ref now, so a
+                // sendMessage meanwhile opens a new stream (and makes this one stale).
+                setStreamManager(undefined);
+                // A turn still running would leave the UI busy with nothing to end
+                // it: read the chat, and poll it until idle if it is still busy.
+                resync()
+                    .catch(() => null)
+                    .then((chat) => {
+                    if (!isCurrent() || getStreamManager())
+                        return;
+                    if (chat ? isChatBusy(chat) : isChatBusy(getState().chat)) {
+                        pollChat(id, { untilIdle: true });
+                        return;
+                    }
+                    if (failed)
+                        return; // keep the 'error' status
                     dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'idle' });
                     callbacks.onStatusChange?.('idle');
-                }
+                });
             },
         });
         // Listen for Chat object updates (status changes only — don't replace messages)
@@ -138,10 +233,6 @@ export function createActions(ctx) {
                 checkTurnEnd(chatData);
             }
         });
-        // Token-by-token streaming state, one accumulator per message being
-        // streamed. Deltas name their message (DeltaEvent.resource_id), so state
-        // never leaks between messages the way a single shared accumulator allowed.
-        const deltaAccums = new Map();
         // Listen for ChatMessage updates
         manager.addEventListener('chat_messages', (message, fields) => {
             // A message that has reached a terminal state will receive no further
@@ -182,8 +273,12 @@ export function createActions(ctx) {
         setStreamManager(manager);
         manager.start();
     };
-    /** Poll-based alternative to streaming for restricted environments */
-    const pollChat = (id) => {
+    /**
+     * Poll-based alternative to streaming for restricted environments. With
+     * `untilIdle` (the fallback when a stream gave up mid-turn) polling stops
+     * once the chat is idle; the next sendMessage streams again.
+     */
+    const pollChat = (id, { untilIdle = false } = {}) => {
         let prevStatus = null;
         const manager = new PollManager({
             pollFunction: async () => {
@@ -205,6 +300,13 @@ export function createActions(ctx) {
                                 updateMessage(message);
                             }
                         }
+                        if (untilIdle && !isChatBusy(chat) && getStreamManager() === manager) {
+                            // Clear the ref first so onStop is a no-op.
+                            setStreamManager(undefined);
+                            manager.stop();
+                            dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'idle' });
+                            callbacks.onStatusChange?.('idle');
+                        }
                     }
                 }
                 catch (err) {
@@ -232,6 +334,7 @@ export function createActions(ctx) {
         manager.start();
     };
     const stopStream = () => {
+        streamGeneration++;
         const manager = getStreamManager();
         // Clear ref first so onStop callback (from manager.stop) is a no-op
         setStreamManager(undefined);
@@ -309,9 +412,9 @@ export function createActions(ctx) {
             dispatch({ type: 'SET_ERROR', payload: undefined });
             dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'idle' });
         },
-        submitToolResult: async (toolInvocationId, result) => {
+        submitToolResult: async (toolInvocationId, result, attachments) => {
             try {
-                await api.submitToolResult(client, toolInvocationId, result);
+                await api.submitToolResult(client, toolInvocationId, result, attachments);
             }
             catch (error) {
                 console.error('[AgentSDK] Failed to submit tool result:', error);

package/dist/agent/api.d.ts

@@ -7,9 +7,9 @@
  *
  * /agents/run stays for A2A/programmatic use.
  */
-import type { AlwaysAllowOptionsDTO, AlwaysAllowResultDTO, ChatAgentDTO, ChatDTO, ChatMessageDTO, ChatSettingsDTO, ChatSettingsRequest, InterruptDTO, ToolExplanationDTO } from '../types';
-import type { AgentOptions, AgentClient, AgentInfo, FileRef } from './types';
-import type { StreamRequest } from '../http/streamable';
+import type { AlwaysAllowOptionsDTO, AlwaysAllowResultDTO, ChatAgentDTO, ChatDTO, ChatMessageDTO, ChatSettingsDTO, ChatSettingsRequest, InterruptDTO, ToolExplanationDTO } from '../types.js';
+import type { AgentOptions, AgentClient, AgentInfo, FileRef } from './types.js';
+import type { StreamRequest } from '../http/streamable.js';
 export interface SendResult {
     chatId: string;
     userMessage: ChatMessageDTO;
@@ -45,7 +45,7 @@ export declare function submitToolResult(client: AgentClient, toolInvocationId:
         payload?: Record<string, unknown>;
     };
     form_data?: Record<string, unknown>;
-}): Promise<void>;
+}, attachments?: FileRef[]): Promise<void>;
 /**
  * Approve a call awaiting approval; the api then runs it.
  *

package/dist/agent/api.js

@@ -7,7 +7,7 @@
  *
  * /agents/run stays for A2A/programmatic use.
  */
-import { isAdHocConfig } from './types';
+import { isAdHocConfig } from './types.js';
 function isFileRef(input) {
     return 'uri' in input && typeof input.uri === 'string';
 }
@@ -144,8 +144,11 @@ export async function setAgent(client, chatId, agentRef) {
 // =========================================================================
 // Tool operations
 // =========================================================================
-export async function submitToolResult(client, toolInvocationId, resultOrAction) {
-    const data = typeof resultOrAction === 'string' ? { result: resultOrAction } : resultOrAction;
+export async function submitToolResult(client, toolInvocationId, resultOrAction, attachments) {
+    const data = typeof resultOrAction === 'string' ? { result: resultOrAction } : { ...resultOrAction };
+    if (attachments && attachments.length > 0) {
+        data.attachments = attachments;
+    }
     await client.http.request('post', `/tools/${toolInvocationId}`, { data });
 }
 /**

package/dist/agent/context.d.ts

@@ -3,7 +3,7 @@
  *
  * React Context for sharing chat state and actions.
  */
-import type { AgentChatState, AgentChatActions, AgentClient } from './types';
+import type { AgentChatState, AgentChatActions, AgentClient } from './types.js';
 /**
  * Context value combining state, actions, and client
  */

package/dist/agent/hooks.d.ts

@@ -3,8 +3,8 @@
  *
  * React hooks for accessing chat state and actions.
  */
-import type { AgentChatState, AgentChatActions, AgentClient } from './types';
-import type { ChatMessageDTO } from '../types';
+import type { AgentChatState, AgentChatActions, AgentClient } from './types.js';
+import type { ChatMessageDTO } from '../types.js';
 /**
  * Hook to access chat state
  *

package/dist/agent/hooks.js

@@ -4,7 +4,7 @@
  * React hooks for accessing chat state and actions.
  */
 import { useContext } from 'react';
-import { AgentChatContext } from './context';
+import { AgentChatContext } from './context.js';
 /**
  * Hook to access chat state
  *

package/dist/agent/index.d.ts

@@ -43,9 +43,9 @@
  * }
  * ```
  */
-export { AgentChatProvider } from './provider';
-export { useAgentChat, useAgentActions, useAgentClient, useAgentChatContext, useMessage, } from './hooks';
-export { AgentChatContext, type AgentChatContextValue } from './context';
-export type { AgentClient, FileRef, AdHocAgentConfig, TemplateAgentConfig, AgentOptions, AgentChatState, AgentChatActions, AlwaysAllowChoice, ChatStatus, AgentChatProviderProps, ClientTool, ClientToolHandlerFn, } from './types';
-export { isAdHocConfig, isTemplateConfig, isClientTool, extractToolSchemas, extractClientToolHandlers, } from './types';
-export { MCPMethodElicitationCreate, parseMCPInputState, elicitParams, isURLElicitation, buildMCPInputResult, type MCPInputState, type ElicitRequestParams, type ElicitRequestedSchema, type ElicitPropertySchema, } from './mcp-input';
+export { AgentChatProvider } from './provider.js';
+export { useAgentChat, useAgentActions, useAgentClient, useAgentChatContext, useMessage, } from './hooks.js';
+export { AgentChatContext, type AgentChatContextValue } from './context.js';
+export type { AgentClient, FileRef, AdHocAgentConfig, TemplateAgentConfig, AgentOptions, AgentChatState, AgentChatActions, AlwaysAllowChoice, ChatStatus, AgentChatProviderProps, ClientTool, ClientToolHandlerFn, ClientToolResult, } from './types.js';
+export { isAdHocConfig, isTemplateConfig, isClientTool, extractToolSchemas, extractClientToolHandlers, } from './types.js';
+export { MCPMethodElicitationCreate, parseMCPInputState, elicitParams, isURLElicitation, buildMCPInputResult, type MCPInputState, type ElicitRequestParams, type ElicitRequestedSchema, type ElicitPropertySchema, } from './mcp-input.js';

package/dist/agent/index.js

@@ -44,12 +44,12 @@
  * ```
  */
 // Provider
-export { AgentChatProvider } from './provider';
+export { AgentChatProvider } from './provider.js';
 // Hooks
-export { useAgentChat, useAgentActions, useAgentClient, useAgentChatContext, useMessage, } from './hooks';
+export { useAgentChat, useAgentActions, useAgentClient, useAgentChatContext, useMessage, } from './hooks.js';
 // Context (for advanced use cases)
-export { AgentChatContext } from './context';
+export { AgentChatContext } from './context.js';
 // Type guards and helpers
-export { isAdHocConfig, isTemplateConfig, isClientTool, extractToolSchemas, extractClientToolHandlers, } from './types';
+export { isAdHocConfig, isTemplateConfig, isClientTool, extractToolSchemas, extractClientToolHandlers, } from './types.js';
 // MCP input requests
-export { MCPMethodElicitationCreate, parseMCPInputState, elicitParams, isURLElicitation, buildMCPInputResult, } from './mcp-input';
+export { MCPMethodElicitationCreate, parseMCPInputState, elicitParams, isURLElicitation, buildMCPInputResult, } from './mcp-input.js';

package/dist/agent/mcp-input.d.ts

@@ -7,7 +7,7 @@
  * key, and submits them with `submitMCPInput`; the runtime then re-sends the
  * tool call with those responses.
  */
-import type { ElicitResult, InputRequest } from '../types';
+import type { ElicitResult, InputRequest } from '../types.js';
 export declare const MCPMethodElicitationCreate = "elicitation/create";
 /** Stored in ToolInvocationDTO.data while an MCP tool call waits for the user. */
 export interface MCPInputState {

package/dist/agent/provider.d.ts

@@ -5,7 +5,7 @@
  * Uses React useReducer + Context pattern.
  */
 import React from 'react';
-import type { AgentChatProviderProps } from './types';
+import type { AgentChatProviderProps } from './types.js';
 /**
  * AgentChatProvider - Provides chat state and actions to children
  *

package/dist/agent/provider.js

@@ -6,11 +6,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * Uses React useReducer + Context pattern.
  */
 import { useReducer, useRef, useEffect, useMemo } from 'react';
-import { AgentChatContext } from './context';
-import { chatReducer, initialState } from './reducer';
-import { createActions, getClientToolHandlers } from './actions';
-import { fetchAgentInfo } from './api';
-import { isTemplateConfig } from './types';
+import { AgentChatContext } from './context.js';
+import { chatReducer, initialState } from './reducer.js';
+import { createActions, getClientToolHandlers } from './actions.js';
+import { fetchAgentInfo } from './api.js';
+import { isTemplateConfig } from './types.js';
 function mergeHandlers(base, extra) {
     if (!extra || extra.size === 0)
         return base;

package/dist/agent/reducer.d.ts

@@ -3,6 +3,6 @@
  *
  * Pure reducer for managing agent chat state.
  */
-import type { AgentChatState, ChatAction } from './types';
+import type { AgentChatState, ChatAction } from './types.js';
 export declare const initialState: AgentChatState;
 export declare function chatReducer(state: AgentChatState, action: ChatAction): AgentChatState;

package/dist/agent/reducer.js

@@ -3,8 +3,8 @@
  *
  * Pure reducer for managing agent chat state.
  */
-import { ChatStatusBusy, ChatStatusAwaitingInput, ChatStatusIdle } from '../types';
-import { isRunInterrupted, isRunWorking } from '../utils';
+import { ChatStatusBusy, ChatStatusAwaitingInput, ChatStatusIdle } from '../types.js';
+import { isRunInterrupted, isRunWorking } from '../utils.js';
 function deriveChatStatus(run) {
     if (!run)
         return ChatStatusIdle;

package/dist/agent/types.d.ts

@@ -4,11 +4,11 @@
  * Public types for the Agent chat module.
  */
 import type { Dispatch } from 'react';
-import type { AgentRunDTO, AgentVersionDTO, AlwaysAllowOptionsDTO, AlwaysAllowResultDTO, ToolExplanationDTO, ChatAgentDTO, ChatDTO, ChatMessageDTO, ChatSettingsDTO, ChatSettingsRequest, AgentTool, AgentConfigInput as GeneratedAgentConfig, CoreAppConfigInput as CoreAppConfig, FileRef, ElicitResult } from '../types';
-import type { HttpClient } from '../http/client';
-import type { StreamableManager } from '../http/streamable';
-import type { PollManager } from '../http/poll';
-export type { FileRef } from '../types';
+import type { AgentRunDTO, AgentVersionDTO, AlwaysAllowOptionsDTO, AlwaysAllowResultDTO, ToolExplanationDTO, ChatAgentDTO, ChatDTO, ChatMessageDTO, ChatSettingsDTO, ChatSettingsRequest, AgentTool, AgentConfigInput as GeneratedAgentConfig, CoreAppConfigInput as CoreAppConfig, FileRef, ElicitResult } from '../types.js';
+import type { HttpClient } from '../http/client.js';
+import type { StreamableManager } from '../http/streamable.js';
+import type { PollManager } from '../http/poll.js';
+export type { FileRef } from '../types.js';
 /** The "always allow" option to save: a key from getAlwaysAllowOptions. */
 export interface AlwaysAllowChoice {
     option?: string;
@@ -129,7 +129,7 @@ export interface AgentChatActions {
     /** Clear the current error */
     clearError: () => void;
     /** Submit a tool result (for widgets/awaiting input) - usually called automatically by SDK */
-    submitToolResult: (toolInvocationId: string, result: string) => Promise<void>;
+    submitToolResult: (toolInvocationId: string, result: string, attachments?: FileRef[]) => Promise<void>;
     /** Answer an MCP tool call's input requests (AwaitingInput status with MCPInputState data) */
     submitMCPInput: (toolInvocationId: string, responses: Record<string, ElicitResult>) => Promise<void>;
     /**
@@ -221,10 +221,23 @@ export interface AgentChatProviderProps {
     /** Children */
     children: React.ReactNode;
 }
+/**
+ * What a client tool handler returns: the result text, or the text plus files.
+ *
+ * `attachments` are files already uploaded with POST /files (for example with
+ * `client.files.upload(dataUrlOrBlob)` or the chat's `uploadFile`), passed as
+ * `FileRef`s, the same as message attachments. An image attachment reaches the
+ * model as image input when the model supports images; other files are listed
+ * on the tool message.
+ */
+export type ClientToolResult = string | {
+    result: string;
+    attachments?: FileRef[];
+};
 /**
  * Client tool handler function - takes args and returns a result (sync or async)
  */
-export type ClientToolHandlerFn = (args: Record<string, unknown>) => Promise<string> | string;
+export type ClientToolHandlerFn = (args: Record<string, unknown>) => Promise<ClientToolResult> | ClientToolResult;
 /**
  * Client tool definition - combines schema with handler
  */

package/dist/api/agents.d.ts

@@ -1,8 +1,8 @@
-import { HttpClient } from '../http/client';
-import type { Response } from '../http/response';
-import type { AgentUpdateBody } from './write-bodies';
-import { FilesAPI } from './files';
-import { ChatDTO, ChatMessageDTO, ChannelContext, LLMDelta, LLMOutput, AgentConfigInput as AgentConfig, AgentDTO, AgentVersionDTO, CreateAgentRequest, FileDTO as File, InterruptDTO, CursorListRequest, CursorListResponse } from '../types';
+import { HttpClient } from '../http/client.js';
+import type { Response } from '../http/response.js';
+import type { AgentUpdateBody } from './write-bodies.js';
+import { FilesAPI } from './files.js';
+import { ChannelContext, ChatDTO, ChatMessageDTO, LLMDelta, LLMOutput, AgentConfigInput as AgentConfig, AgentDTO, AgentVersionDTO, CreateAgentRequest, FileDTO as File, InterruptDTO, CursorListRequest, CursorListResponse, FileRef } from '../types.js';
 /** Internal tool definition returned by getInternalTools */
 export interface InternalToolDefinition {
     id: string;
@@ -67,11 +67,9 @@ export interface SendMessageOptions {
      */
     signal?: AbortSignal;
     /**
-     * The channel this message came through (slack, telegram, a wearable...):
-     * `channel_type` plus whatever `channel_metadata` the integration needs to
-     * route the reply (thread ids, chat ids). Sent as `channel_context` on the
-     * message; the API records it on the chat the first time it sees it, so
-     * later turns in that chat inherit the routing.
+     * @deprecated The API no longer reads a channel context from an agent run;
+     * a chat's routing comes from the server's own channel receivers. Accepted
+     * for compatibility and not sent.
      */
     channel_context?: ChannelContext;
 }
@@ -110,7 +108,9 @@ export declare class Agent {
     /** Stop the current chat generation */
     stopChat(): Promise<void>;
     /**
-     * Submit a tool result
+     * Submit a tool result. `attachments` are files uploaded with POST /files
+     * (`files.upload`) that the tool returns; images reach the model as image
+     * input when it supports images.
      */
     submitToolResult(toolInvocationId: string, resultOrAction: string | {
         action: {
@@ -118,7 +118,7 @@ export declare class Agent {
             payload?: Record<string, unknown>;
         };
         form_data?: Record<string, unknown>;
-    }): Promise<void>;
+    }, attachments?: FileRef[]): Promise<void>;
     /** Stop streaming/polling and cleanup */
     disconnect(): void;
     /**
@@ -207,7 +207,9 @@ export declare class AgentsAPI {
      */
     create(config: string | AgentConfig, options?: AgentOptions): Agent;
     /**
-     * Submit a tool result
+     * Submit a tool result. `attachments` are files uploaded with POST /files
+     * (`files.upload`) that the tool returns; images reach the model as image
+     * input when it supports images.
      */
     submitToolResult(toolInvocationId: string, resultOrAction: string | {
         action: {
@@ -215,7 +217,7 @@ export declare class AgentsAPI {
             payload?: Record<string, unknown>;
         };
         form_data?: Record<string, unknown>;
-    }): Promise<void>;
+    }, attachments?: FileRef[]): Promise<void>;
     /**
      * Resolve an interrupt gate on an agent run.
      *