@inferencesh/sdk 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- `approveTool` and `rejectTool` resolve the call's interrupt (`POST /interrupts/{id}/resolve`), the same answer as every other pause (a wait, a hook gate, a held turn); they no longer post to `/tools/{id}/invoke|reject`. A call that is not awaiting approval rejects with "Tool call … is not awaiting approval".
+- `resolveInterrupt` (agent actions and `AgentsAPI`) takes an optional `reason`, sent with a deny as `data.reason`.
+
+## [0.31.0] - 2026-10-19
+
+### Added
+- `pendingWait(interrupts)` and `PendingWait`: the wait a run is paused on by its agent's wait tool (`InterruptReasonWait`), with when it ends and the agent's note.
+- Generated types: `InternalToolsConfig.wait`, `AgentTool.approval_timeout` (seconds a call waits for approval before it is refused), `InterruptReasonWait`.
+
 ## [0.30.0] - 2026-10-18
 
 ### Removed

package/dist/agent/actions.js

@@ -5,7 +5,7 @@
  * These are created once per provider instance with access to dispatch.
  */
 import { ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, } from '../types.js';
-import { isChatBusy, isMessageTerminal, isRunInterrupted, isRunWorking } from '../utils.js';
+import { approvalInterrupt, isChatBusy, isMessageTerminal, isRunInterrupted, isRunWorking } from '../utils.js';
 import { StreamableManager } from '../http/streamable.js';
 import { PollManager } from '../http/poll.js';
 import { createLLMDeltaAccumulator } from '../delta.js';
@@ -29,6 +29,23 @@ function isTransient(err) {
 export function createActions(ctx) {
     const dispatchedToolInvocations = new Set();
     const { client, dispatch, getState, getConfig, getChatId, getClientToolHandlers, getStreamManager, setStreamManager, getStreamEnabled, getPollIntervalMs, callbacks } = ctx;
+    /**
+     * The interrupt a call awaiting approval waits on: approving or rejecting
+     * the call resolves it, like every other pause. The chat's pending
+     * interrupts carry it; when they have not caught up with the call yet, the
+     * run's are read from the api.
+     */
+    const approvalInterruptId = async (toolInvocationId) => {
+        const chat = getState().chat;
+        let interrupt = approvalInterrupt(chat?.pending_interrupts, toolInvocationId);
+        const runId = chat?.active_run?.id;
+        if (!interrupt && runId) {
+            interrupt = approvalInterrupt(await api.listRunInterrupts(client, runId), toolInvocationId);
+        }
+        if (!interrupt)
+            throw new Error(`Tool call ${toolInvocationId} is not awaiting approval`);
+        return interrupt.id;
+    };
     let prevChatWasBusy = false;
     // Bumped by every streamChat() and stopStream(). A stream whose generation
     // is no longer current (stopped, reset, switched to another chat) leaves
@@ -453,7 +470,7 @@ export function createActions(ctx) {
         },
         approveTool: async (toolInvocationId) => {
             try {
-                await api.approveTool(client, toolInvocationId);
+                await api.resolveInterrupt(client, await approvalInterruptId(toolInvocationId), 'allow');
             }
             catch (error) {
                 console.error('[AgentSDK] Failed to approve tool:', error);
@@ -466,7 +483,7 @@ export function createActions(ctx) {
         },
         rejectTool: async (toolInvocationId, reason) => {
             try {
-                await api.rejectTool(client, toolInvocationId, reason);
+                await api.resolveInterrupt(client, await approvalInterruptId(toolInvocationId), 'deny', reason);
             }
             catch (error) {
                 console.error('[AgentSDK] Failed to reject tool:', error);

package/dist/agent/api.d.ts

@@ -46,24 +46,6 @@ export declare function submitToolResult(client: AgentClient, toolInvocationId:
     };
     form_data?: Record<string, unknown>;
 }, attachments?: FileRef[]): Promise<void>;
-/**
- * Approve a call awaiting approval; the api then runs it.
- *
- * Needs approvals:write, which only the account holder's own sign-in holds
- * (the web app, or a `belt login` session). An API key, an app's OAuth token
- * or the server proxy is refused with 403 `requires_sign_in`
- * (ErrorCodeRequiresSignIn); the error's message says what to do.
- */
-export declare function approveTool(client: AgentClient, toolInvocationId: string): Promise<void>;
-/**
- * Reject a call awaiting approval, with an optional reason the agent sees.
- *
- * Needs approvals:write, which only the account holder's own sign-in holds
- * (the web app, or a `belt login` session). An API key, an app's OAuth token
- * or the server proxy is refused with 403 `requires_sign_in`
- * (ErrorCodeRequiresSignIn); the error's message says what to do.
- */
-export declare function rejectTool(client: AgentClient, toolInvocationId: string, reason?: string): Promise<void>;
 /**
  * What "always allow" can save for a call awaiting approval, narrowest first.
  * The api computes the options from the call; each one, saved, answers it again.
@@ -94,14 +76,16 @@ export declare function explainTool(client: AgentClient, chatId: string, toolInv
  */
 export declare function updateChatSettings(client: AgentClient, chatId: string, settings: ChatSettingsRequest): Promise<ChatSettingsDTO>;
 /**
- * Allow or deny an interrupt gate on an agent run.
+ * Allow or deny an interrupt on an agent run: a tool call waiting for
+ * approval, a wait, a hook gate or a held turn, all the same way. `reason`,
+ * with deny, goes back to the agent with the refused call.
  *
  * Needs approvals:write, which only the account holder's own sign-in holds
  * (the web app, or a `belt login` session). An API key, an app's OAuth token
  * or the server proxy is refused with 403 `requires_sign_in`
  * (ErrorCodeRequiresSignIn); the error's message says what to do.
  */
-export declare function resolveInterrupt(client: AgentClient, interruptId: string, decision: 'allow' | 'deny'): Promise<InterruptDTO>;
+export declare function resolveInterrupt(client: AgentClient, interruptId: string, decision: 'allow' | 'deny', reason?: string): Promise<InterruptDTO>;
 export declare function listRunInterrupts(client: AgentClient, runId: string): Promise<InterruptDTO[]>;
 export declare function uploadFile(client: AgentClient, file: globalThis.File): Promise<FileRef>;
 export declare function chatStreamRequest(client: AgentClient, chatId: string): StreamRequest;

package/dist/agent/api.js

@@ -151,28 +151,6 @@ export async function submitToolResult(client, toolInvocationId, resultOrAction,
     }
     await client.http.request('post', `/tools/${toolInvocationId}`, { data });
 }
-/**
- * Approve a call awaiting approval; the api then runs it.
- *
- * Needs approvals:write, which only the account holder's own sign-in holds
- * (the web app, or a `belt login` session). An API key, an app's OAuth token
- * or the server proxy is refused with 403 `requires_sign_in`
- * (ErrorCodeRequiresSignIn); the error's message says what to do.
- */
-export async function approveTool(client, toolInvocationId) {
-    await client.http.request('post', `/tools/${toolInvocationId}/invoke`);
-}
-/**
- * Reject a call awaiting approval, with an optional reason the agent sees.
- *
- * Needs approvals:write, which only the account holder's own sign-in holds
- * (the web app, or a `belt login` session). An API key, an app's OAuth token
- * or the server proxy is refused with 403 `requires_sign_in`
- * (ErrorCodeRequiresSignIn); the error's message says what to do.
- */
-export async function rejectTool(client, toolInvocationId, reason) {
-    await client.http.request('post', `/tools/${toolInvocationId}/reject`, { data: { reason } });
-}
 /**
  * What "always allow" can save for a call awaiting approval, narrowest first.
  * The api computes the options from the call; each one, saved, answers it again.
@@ -219,16 +197,18 @@ export async function updateChatSettings(client, chatId, settings) {
 // Interrupt operations
 // =========================================================================
 /**
- * Allow or deny an interrupt gate on an agent run.
+ * Allow or deny an interrupt on an agent run: a tool call waiting for
+ * approval, a wait, a hook gate or a held turn, all the same way. `reason`,
+ * with deny, goes back to the agent with the refused call.
  *
  * Needs approvals:write, which only the account holder's own sign-in holds
  * (the web app, or a `belt login` session). An API key, an app's OAuth token
  * or the server proxy is refused with 403 `requires_sign_in`
  * (ErrorCodeRequiresSignIn); the error's message says what to do.
  */
-export async function resolveInterrupt(client, interruptId, decision) {
+export async function resolveInterrupt(client, interruptId, decision, reason) {
     const resp = await client.http.request('post', `/interrupts/${interruptId}/resolve`, {
-        data: { decision }
+        data: reason ? { decision, data: { reason } } : { decision }
     });
     return resp.data;
 }

package/dist/agent/types.d.ts

@@ -134,7 +134,8 @@ export interface AgentChatActions {
     /** Answer an MCP tool call's input requests (AwaitingInput status with MCPInputState data) */
     submitMCPInput: (toolInvocationId: string, responses: Record<string, ElicitResult>) => Promise<void>;
     /**
-     * Approve a tool (for HIL approval - AwaitingApproval status)
+     * Approve a tool (for HIL approval - AwaitingApproval status). Resolves the
+     * call's interrupt with allow, as resolveInterrupt does for every pause.
      *
      * Needs the account holder's own sign-in (approvals:write): with an API
      * key, an app's token or the server proxy it rejects with 403
@@ -142,7 +143,8 @@ export interface AgentChatActions {
      */
     approveTool: (toolInvocationId: string) => Promise<void>;
     /**
-     * Reject a tool (for HIL approval - AwaitingApproval status)
+     * Reject a tool (for HIL approval - AwaitingApproval status). Resolves the
+     * call's interrupt with deny; `reason` goes back to the agent.
      *
      * Needs the account holder's own sign-in (approvals:write): with an API
      * key, an app's token or the server proxy it rejects with 403

package/dist/api/agents.d.ts

@@ -219,13 +219,15 @@ export declare class AgentsAPI {
         form_data?: Record<string, unknown>;
     }, attachments?: FileRef[]): Promise<void>;
     /**
-     * Resolve an interrupt gate on an agent run.
+     * Resolve an interrupt on an agent run: a tool call waiting for approval, a
+     * wait, a hook gate or a held turn, all the same way. `reason`, with deny,
+     * goes back to the agent with the refused call.
      *
      * Needs approvals:write, which only the account holder's own sign-in holds:
      * with an API key, an app's OAuth token or the server proxy it rejects with
      * 403 `requires_sign_in` (ErrorCodeRequiresSignIn).
      */
-    resolveInterrupt(interruptId: string, decision: 'allow' | 'deny'): Promise<Response<InterruptDTO>>;
+    resolveInterrupt(interruptId: string, decision: 'allow' | 'deny', reason?: string): Promise<Response<InterruptDTO>>;
     /**
      * List pending interrupts for an agent run
      */

package/dist/api/agents.js

@@ -522,15 +522,17 @@ export class AgentsAPI {
         await this.http.request('post', `/tools/${toolInvocationId}`, { data });
     }
     /**
-     * Resolve an interrupt gate on an agent run.
+     * Resolve an interrupt on an agent run: a tool call waiting for approval, a
+     * wait, a hook gate or a held turn, all the same way. `reason`, with deny,
+     * goes back to the agent with the refused call.
      *
      * Needs approvals:write, which only the account holder's own sign-in holds:
      * with an API key, an app's OAuth token or the server proxy it rejects with
      * 403 `requires_sign_in` (ErrorCodeRequiresSignIn).
      */
-    async resolveInterrupt(interruptId, decision) {
+    async resolveInterrupt(interruptId, decision, reason) {
         return this.http.request('post', `/interrupts/${interruptId}/resolve`, {
-            data: { decision }
+            data: reason ? { decision, data: { reason } } : { decision }
         });
     }
     /**

package/dist/index.d.ts

@@ -36,8 +36,8 @@ export type { ClientTool, ClientToolHandler, ClientToolResult } from './tool-bui
 export { lifecycleHook, learningHooks } from './hook-builder.js';
 export type { LifecycleHookBuilder } from './hook-builder.js';
 export { DeltaAccumulator, createLLMDeltaAccumulator, type DeltaEvent, type FieldTags, type FieldTagsRegistry } from './delta.js';
-export { parseStatus, isTerminalStatus, isChatBusy, isAwaitingHuman, isRunTerminal, isRunInterrupted, isRunSettled, isRunWorking, isMessageTerminal, pendingApprovals, heldTurn, } from './utils.js';
-export type { PendingApproval, HeldTurn } from './utils.js';
+export { parseStatus, isTerminalStatus, isChatBusy, isAwaitingHuman, isRunTerminal, isRunInterrupted, isRunSettled, isRunWorking, isMessageTerminal, pendingApprovals, heldTurn, pendingWait, } from './utils.js';
+export type { PendingApproval, HeldTurn, PendingWait } from './utils.js';
 export * from './types.js';
 export type { TaskDTO as Task } from './types.js';
 import { HttpClient, type HttpClientConfig } from './http/client.js';

package/dist/index.js

@@ -38,7 +38,7 @@ export { lifecycleHook, learningHooks } from './hook-builder.js';
 // Delta accumulator for streaming responses
 export { DeltaAccumulator, createLLMDeltaAccumulator } from './delta.js';
 // Status utilities (handle both int and string status values)
-export { parseStatus, isTerminalStatus, isChatBusy, isAwaitingHuman, isRunTerminal, isRunInterrupted, isRunSettled, isRunWorking, isMessageTerminal, pendingApprovals, heldTurn, } from './utils.js';
+export { parseStatus, isTerminalStatus, isChatBusy, isAwaitingHuman, isRunTerminal, isRunInterrupted, isRunSettled, isRunWorking, isMessageTerminal, pendingApprovals, heldTurn, pendingWait, } from './utils.js';
 // Types - includes TaskStatus constants and all DTOs
 export * from './types.js';
 // =============================================================================

package/dist/types.d.ts

@@ -17,6 +17,7 @@ export interface InternalToolsConfig {
     agent?: boolean;
     remote?: boolean;
     knowledge?: boolean;
+    wait?: boolean;
 }
 /**
  * AgentPermissions is what an agent's new chats in its own workspace may do
@@ -43,6 +44,11 @@ export interface AgentTool {
     description: string;
     type: ToolType;
     require_approval?: boolean;
+    /**
+     * ApprovalTimeout is how many seconds a call of this tool waits for its
+     * approval before it is refused. 0 waits until someone answers.
+     */
+    approval_timeout?: number;
     app?: AppToolConfig;
     agent?: AgentToolConfig;
     hook?: HookToolConfig;
@@ -97,6 +103,7 @@ export interface AgentToolDTO {
     description: string;
     type: ToolType;
     require_approval?: boolean;
+    approval_timeout?: number;
     app?: AppToolConfigDTO;
     agent?: AgentToolConfigDTO;
     hook?: HookToolConfigDTO;
@@ -5080,7 +5087,13 @@ export interface TaskLog {
 }
 /**
  * TaskDTO is the full API response for a task.
+ * TaskEgress is what a task's sandbox sent to and received from the
+ * internet through the engine's egress gateway, in bytes.
  */
+export interface TaskEgress {
+    bytes_out: number;
+    bytes_in: number;
+}
 export interface TaskDTO extends BaseModelDTO, PermissionModelDTO {
     graph_id?: string;
     user_public_key: string;
@@ -5114,6 +5127,12 @@ export interface TaskDTO extends BaseModelDTO, PermissionModelDTO {
     events: TaskEvent[];
     logs: TaskLog[];
     usage_events: (UsageEventDTO | undefined)[];
+    /**
+     * Egress is what the task's sandbox moved through the engine's egress
+     * gateway, reported by the engine when the task ended. Absent for a
+     * task that ran without the gateway.
+     */
+    egress?: TaskEgress;
     session_id?: string;
     session_timeout?: number;
 }
@@ -6711,6 +6730,13 @@ export declare const GraphEdgeTypeOutput: GraphEdgeType;
  * allow starts the turn, a deny ends the run.
  */
 export declare const InterruptResourceTurn: InterruptResourceType;
+/**
+ * InterruptReasonWait is a tool call the agent made to wait: the run is
+ * paused until the interrupt's deadline, when its own expiry trigger settles
+ * it (allow), or until a person ends the wait sooner. Its resource is the
+ * wait call (InterruptResourceToolInvocation).
+ */
+export declare const InterruptReasonWait: InterruptReason;
 /**
  * MergeStrategy defines how a delta field should be merged by consumers.
  */
@@ -7841,7 +7867,7 @@ export declare const AgentRunStateRejected: AgentRunState;
  * InterruptReason describes why an agent run is in an interrupted state.
  * Aligns with AG-UI interrupt outcome reasons.
  */
-export type InterruptReason = "tool_approval" | "client_tool" | "widget" | "auth" | "confirmation" | "hook_gate";
+export type InterruptReason = "wait" | "tool_approval" | "client_tool" | "widget" | "auth" | "confirmation" | "hook_gate";
 export declare const InterruptReasonToolApproval: InterruptReason;
 export declare const InterruptReasonClientTool: InterruptReason;
 export declare const InterruptReasonWidget: InterruptReason;

package/dist/types.js

@@ -992,6 +992,13 @@ export const GraphEdgeTypeOutput = "output";
  * allow starts the turn, a deny ends the run.
  */
 export const InterruptResourceTurn = "turn";
+/**
+ * InterruptReasonWait is a tool call the agent made to wait: the run is
+ * paused until the interrupt's deadline, when its own expiry trigger settles
+ * it (allow), or until a person ends the wait sooner. Its resource is the
+ * wait call (InterruptResourceToolInvocation).
+ */
+export const InterruptReasonWait = "wait";
 export const MergeStrategyConcat = "concat";
 export const MergeStrategyReplace = "replace";
 export const MergeStrategyIndexed = "indexed";

package/dist/utils.d.ts

@@ -49,3 +49,16 @@ export type HeldTurn = {
 };
 /** The held turn among a run's pending interrupts, if one is held. */
 export declare function heldTurn(interrupts: InterruptDTO[] | null | undefined): HeldTurn | null;
+/** The interrupt a tool call awaiting approval waits on, among a chat's or a run's pending interrupts. */
+export declare function approvalInterrupt(interrupts: InterruptDTO[] | null | undefined, toolInvocationId: string): InterruptDTO | undefined;
+/** A run paused by its agent's wait tool (InterruptReasonWait): it continues at `until`, or sooner when the person ends the wait ("continue now", allow) or cancels it (deny). */
+export type PendingWait = {
+    interruptId: string;
+    runId: string;
+    /** When the wait ends, RFC3339; null when the api gives no deadline. */
+    until: string | null;
+    /** What the agent said it will do when the wait ends. */
+    note: string;
+};
+/** The wait among a run's pending interrupts, if the run is waiting. */
+export declare function pendingWait(interrupts: InterruptDTO[] | null | undefined): PendingWait | null;

package/dist/utils.js

@@ -2,7 +2,7 @@
  * Status utilities for handling both int and string-based status values.
  * Provides future compatibility when API migrates from int to string status.
  */
-import { InterruptReasonToolApproval, InterruptResourceTurn, InterruptStatusPending } from './types.js';
+import { InterruptReasonToolApproval, InterruptReasonWait, InterruptResourceTurn, InterruptStatusPending } from './types.js';
 import { TaskStatusUnknown, TaskStatusReceived, TaskStatusQueued, TaskStatusDispatched, TaskStatusPreparing, TaskStatusServing, TaskStatusSettingUp, TaskStatusRunning, TaskStatusCancelling, TaskStatusUploading, TaskStatusCompleted, TaskStatusFailed, TaskStatusCancelled, TaskStatusRejected, AgentRunStateWorking, AgentRunStateSubmitted, AgentRunStateInputRequired, AgentRunStateAuthRequired, AgentRunStateCompleted, AgentRunStateFailed, AgentRunStateCanceled, AgentRunStateRejected, ChatMessageStatusReady, ChatMessageStatusFailed, ChatMessageStatusCancelled, ChatStatusBusy, ChatStatusAwaitingInput, } from './types.js';
 /** Map string status names to TaskStatus values (for future string-based API) */
 const STATUS_STRING_MAP = {
@@ -117,11 +117,27 @@ export function pendingApprovals(chat) {
     }
     return out;
 }
+/** The first pending interrupt among a run's that matches. */
+function pendingInterrupt(interrupts, match) {
+    return interrupts?.find(i => i.status === InterruptStatusPending && match(i));
+}
 /** The held turn among a run's pending interrupts, if one is held. */
 export function heldTurn(interrupts) {
-    const interrupt = interrupts?.find(i => i.resource_type === InterruptResourceTurn && i.status === InterruptStatusPending);
+    const interrupt = pendingInterrupt(interrupts, i => i.resource_type === InterruptResourceTurn);
     if (!interrupt)
         return null;
     const { steps } = parseMeta(interrupt);
     return { interruptId: interrupt.id, runId: interrupt.run_id, steps: typeof steps === 'number' ? steps : null };
 }
+/** The interrupt a tool call awaiting approval waits on, among a chat's or a run's pending interrupts. */
+export function approvalInterrupt(interrupts, toolInvocationId) {
+    return pendingInterrupt(interrupts, i => i.reason === InterruptReasonToolApproval && (i.resource_id || parseMeta(i).tool_invocation_id) === toolInvocationId);
+}
+/** The wait among a run's pending interrupts, if the run is waiting. */
+export function pendingWait(interrupts) {
+    const interrupt = pendingInterrupt(interrupts, i => i.reason === InterruptReasonWait);
+    if (!interrupt)
+        return null;
+    const { note } = parseMeta(interrupt);
+    return { interruptId: interrupt.id, runId: interrupt.run_id, until: interrupt.expires_at ?? null, note: typeof note === 'string' ? note : '' };
+}

package/package.json

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