@inferencesh/sdk 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-12
+
+### Added
+
+- Generated types follow the API: device authorization records the starting device and proximity (`DeviceAuthCodeInfo.device` with `client`, `client_version`, `proximity`, `scopes`), `DeviceAuthStatusSlowDown` and the poll `interval`, the `code_confirmation_required` and `invalid_scope` error codes, and `cached_tokens` / `cache_write_tokens` on LLM usage and text meta items.
+
+## [0.24.0] - 2026-10-11
+
+### 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

package/dist/agent/actions.js

@@ -16,6 +16,15 @@ 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;
@@ -24,6 +33,28 @@ export function createActions(ctx) {
     // 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) {
@@ -63,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`,
                         }));
@@ -73,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)
                         }));
                     });
@@ -381,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

@@ -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

@@ -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/index.d.ts

@@ -46,6 +46,6 @@
 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, } from './types.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/types.d.ts

@@ -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

@@ -2,7 +2,7 @@ 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 } from '../types.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;
@@ -108,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: {
@@ -116,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;
     /**
@@ -205,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: {
@@ -213,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.
      *

package/dist/api/agents.js

@@ -172,11 +172,17 @@ export class Agent {
         await this.http.request('post', `/chats/${this.chatId}/stop`);
     }
     /**
-     * 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.
      */
-    async submitToolResult(toolInvocationId, resultOrAction) {
+    async submitToolResult(toolInvocationId, resultOrAction, attachments) {
         const result = typeof resultOrAction === 'string' ? resultOrAction : JSON.stringify(resultOrAction);
-        await this.http.request('post', `/tools/${toolInvocationId}`, { data: { result } });
+        const data = { result };
+        if (attachments && attachments.length > 0) {
+            data.attachments = attachments;
+        }
+        await this.http.request('post', `/tools/${toolInvocationId}`, { data });
     }
     /** Stop streaming/polling and cleanup */
     disconnect() {
@@ -496,11 +502,17 @@ export class AgentsAPI {
         return new Agent(this.http, this.files, config, options);
     }
     /**
-     * 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.
      */
-    async submitToolResult(toolInvocationId, resultOrAction) {
+    async submitToolResult(toolInvocationId, resultOrAction, attachments) {
         const result = typeof resultOrAction === 'string' ? resultOrAction : JSON.stringify(resultOrAction);
-        await this.http.request('post', `/tools/${toolInvocationId}`, { data: { result } });
+        const data = { result };
+        if (attachments && attachments.length > 0) {
+            data.attachments = attachments;
+        }
+        await this.http.request('post', `/tools/${toolInvocationId}`, { data });
     }
     /**
      * Resolve an interrupt gate on an agent run.

package/dist/types.d.ts

@@ -502,10 +502,17 @@ export interface CreateAgentMessageResponse {
     assistant_message?: ChatMessageDTO;
 }
 /**
- * ToolResultRequest represents a tool result submission
+ * ToolResultRequest is the body of POST /tools/{id}: a client's result for a
+ * tool call it ran.
  */
 export interface ToolResultRequest {
     result: string;
+    /**
+     * Attachments are files uploaded with POST /files, as in MessageInput.
+     * The tool message carries them; images reach the model as image input
+     * when it accepts images.
+     */
+    attachments?: FileRef[];
 }
 /**
  * PartialFile is the clean DTO version (no gorm tags).
@@ -638,6 +645,12 @@ export interface DeviceAuthPollResponse {
      * credential comes with it.
      */
     admin_until?: string;
+    /**
+     * Interval is the polling interval in seconds the device is now held
+     * to, set with status slow_down (RFC 8628 3.5: each one raises it by
+     * five seconds).
+     */
+    interval?: number;
 }
 /**
  * AdminElevateRequest is the body of POST /device/auth/elevate: a platform
@@ -2794,7 +2807,7 @@ export interface DecideEntitlementRequestRequest {
  * and APIError.Code on the legacy envelope. Clients branch on these, so a
  * code is a named const here, where it generates into models and the SDKs.
  */
-export type ErrorCode = "invalid_request" | "validation_error" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "name_conflict" | "already_exists" | "not_configured" | "method_not_allowed" | "rate_limited" | "internal_error" | "team_role_required" | "blocked_by_usage_policy" | "last_owner" | "account_deactivated" | "account_banned" | "person_required" | "otp_required" | "requires_sign_in" | "insufficient_scope" | "impersonation_reason_required" | "mcp_auth_expired" | "admin_session_required" | "admin_scopes_not_approved" | "cli_session_required" | "admin_required" | "same_admin_required" | "browser_session_required" | "invalid_ttl" | "admin_authenticator_required" | "limit_exceeded" | "feature_not_available" | "entitlement_unavailable" | "payment_required" | "payment_method_required" | "form_closed" | "already_submitted" | "already_claimed" | "already_entitled" | "request_open" | "invalid_code" | "already_processed" | "expired" | "app_retired" | "app_maintenance" | "invalid_transition" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED" | "SESSION_ENDED" | "WORKER_LEASED" | "APP_MISMATCH" | "VERSION_MISMATCH" | "agents_disabled" | "remote_offline" | "remote_timeout" | "harness_not_drivable" | "harness_too_old";
+export type ErrorCode = "invalid_request" | "validation_error" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "name_conflict" | "already_exists" | "not_configured" | "method_not_allowed" | "rate_limited" | "internal_error" | "team_role_required" | "blocked_by_usage_policy" | "last_owner" | "account_deactivated" | "account_banned" | "person_required" | "otp_required" | "requires_sign_in" | "insufficient_scope" | "invalid_scope" | "impersonation_reason_required" | "mcp_auth_expired" | "admin_session_required" | "admin_scopes_not_approved" | "cli_session_required" | "admin_required" | "same_admin_required" | "browser_session_required" | "invalid_ttl" | "admin_authenticator_required" | "limit_exceeded" | "feature_not_available" | "entitlement_unavailable" | "payment_required" | "payment_method_required" | "form_closed" | "already_submitted" | "already_claimed" | "already_entitled" | "request_open" | "invalid_code" | "already_processed" | "expired" | "code_confirmation_required" | "app_retired" | "app_maintenance" | "invalid_transition" | "SESSION_NOT_FOUND" | "SESSION_EXPIRED" | "SESSION_ENDED" | "WORKER_LEASED" | "APP_MISMATCH" | "VERSION_MISMATCH" | "agents_disabled" | "remote_offline" | "remote_timeout" | "harness_not_drivable" | "harness_too_old";
 export declare const ErrorCodeInvalidRequest: ErrorCode;
 export declare const ErrorCodeValidationError: ErrorCode;
 export declare const ErrorCodeUnauthorized: ErrorCode;
@@ -2853,6 +2866,12 @@ export declare const ErrorCodeRequiresSignIn: ErrorCode;
  * narrowed login granted less). The detail names the scope.
  */
 export declare const ErrorCodeInsufficientScope: ErrorCode;
+/**
+ * ErrorCodeInvalidScope (400): a grant request (an OAuth authorization,
+ * a device sign-in's approval) named only scopes this server does not
+ * know. The detail names them.
+ */
+export declare const ErrorCodeInvalidScope: ErrorCode;
 /**
  * ErrorCodeImpersonationReasonRequired (403): a platform admin named a
  * team they are not a member of without a live impersonation grant.
@@ -2931,6 +2950,11 @@ export declare const ErrorCodeRequestOpen: ErrorCode;
 export declare const ErrorCodeInvalidCode: ErrorCode;
 export declare const ErrorCodeAlreadyProcessed: ErrorCode;
 export declare const ErrorCodeExpired: ErrorCode;
+/**
+ * A device sign-in started away from the approver is approved only
+ * with the code typed from the device (400).
+ */
+export declare const ErrorCodeCodeConfirmationRequired: ErrorCode;
 /**
  * Run-time refusals. AppRetired (410): the app no longer runs.
  * AppMaintenance (503, Retry-After): the owner paused it; the message is
@@ -5015,6 +5039,12 @@ export interface ToolInvocationDTO extends BaseModelDTO, PermissionModelDTO {
 export interface MetaItem {
     type: MetaItemType;
     tokens?: number;
+    /**
+     * CachedTokens and CacheWriteTokens are the parts of Tokens (on an input
+     * text item) read from and written to the provider's prompt cache.
+     */
+    cached_tokens?: number;
+    cache_write_tokens?: number;
     width?: number;
     height?: number;
     resolution_mp?: number;
@@ -5640,6 +5670,16 @@ export interface DecisionVisionInput extends DecisionInput {
      */
     images?: string[];
 }
+/**
+ * DecisionVideoInput is the input of a decision model that also watches
+ * videos: a DecisionVisionInput plus the videos the questions are about.
+ */
+export interface DecisionVideoInput extends DecisionVisionInput {
+    /**
+     * Videos are file URIs. Every question sees them, after the images.
+     */
+    videos?: string[];
+}
 /**
  * DecisionChoiceAnswer is the answer to a choice question.
  */
@@ -6271,11 +6311,16 @@ export declare const OpIsNull: FilterOperator;
 export declare const OpIsNotNull: FilterOperator;
 export declare const OpIsEmpty: FilterOperator;
 export declare const OpIsNotEmpty: FilterOperator;
-export type DeviceAuthStatus = "pending" | "approved" | "expired" | "denied" | "valid" | "invalid" | "loading";
+export type DeviceAuthStatus = "pending" | "approved" | "expired" | "denied" | "slow_down" | "valid" | "invalid" | "loading";
 export declare const DeviceAuthStatusPending: DeviceAuthStatus;
 export declare const DeviceAuthStatusApproved: DeviceAuthStatus;
 export declare const DeviceAuthStatusExpired: DeviceAuthStatus;
 export declare const DeviceAuthStatusDenied: DeviceAuthStatus;
+/**
+ * DeviceAuthStatusSlowDown: still pending, and the device polled sooner
+ * than its interval, which is now five seconds longer (RFC 8628 3.5).
+ */
+export declare const DeviceAuthStatusSlowDown: DeviceAuthStatus;
 export declare const DeviceAuthStatusValid: DeviceAuthStatus;
 export declare const DeviceAuthStatusInvalid: DeviceAuthStatus;
 export declare const DeviceAuthStatusLoading: DeviceAuthStatus;
@@ -7293,7 +7338,17 @@ export interface LLMUsage {
     stop_reason: string;
     time_to_first_token: number;
     tokens_per_second: number;
+    /**
+     * PromptTokens counts every input token, cached ones included
+     * (OpenAI, xAI and OpenRouter count them this way).
+     */
     prompt_tokens: number;
+    /**
+     * CachedTokens is how many of PromptTokens were read from the provider's
+     * prompt cache; CacheWriteTokens how many were written to it.
+     */
+    cached_tokens: number;
+    cache_write_tokens: number;
     completion_tokens: number;
     total_tokens: number;
     reasoning_tokens: number;

package/dist/types.js

@@ -434,6 +434,12 @@ export const ErrorCodeRequiresSignIn = "requires_sign_in";
  * narrowed login granted less). The detail names the scope.
  */
 export const ErrorCodeInsufficientScope = "insufficient_scope";
+/**
+ * ErrorCodeInvalidScope (400): a grant request (an OAuth authorization,
+ * a device sign-in's approval) named only scopes this server does not
+ * know. The detail names them.
+ */
+export const ErrorCodeInvalidScope = "invalid_scope";
 /**
  * ErrorCodeImpersonationReasonRequired (403): a platform admin named a
  * team they are not a member of without a live impersonation grant.
@@ -512,6 +518,11 @@ export const ErrorCodeRequestOpen = "request_open";
 export const ErrorCodeInvalidCode = "invalid_code";
 export const ErrorCodeAlreadyProcessed = "already_processed";
 export const ErrorCodeExpired = "expired";
+/**
+ * A device sign-in started away from the approver is approved only
+ * with the code typed from the device (400).
+ */
+export const ErrorCodeCodeConfirmationRequired = "code_confirmation_required";
 /**
  * Run-time refusals. AppRetired (410): the app no longer runs.
  * AppMaintenance (503, Retry-After): the owner paused it; the message is
@@ -1054,6 +1065,11 @@ export const DeviceAuthStatusPending = "pending";
 export const DeviceAuthStatusApproved = "approved";
 export const DeviceAuthStatusExpired = "expired";
 export const DeviceAuthStatusDenied = "denied";
+/**
+ * DeviceAuthStatusSlowDown: still pending, and the device polled sooner
+ * than its interval, which is now five seconds longer (RFC 8628 3.5).
+ */
+export const DeviceAuthStatusSlowDown = "slow_down";
 export const DeviceAuthStatusValid = "valid";
 export const DeviceAuthStatusInvalid = "invalid";
 export const DeviceAuthStatusLoading = "loading";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/sdk",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Official JavaScript/TypeScript SDK for inference.sh - Run AI models with a simple API",
   "type": "module",
   "main": "dist/index.js",