@inferencesh/sdk 0.6.51 → 0.6.53

package/README.md

@@ -176,6 +176,32 @@ const task = await client.tasks.run(
 await client.tasks.cancel(task.id);
 ```
 
+### Stream Functions (Live Sockets)
+
+A stream function keeps a socket open with its caller for the life of the task: frames go both ways until the caller closes or the app returns. `client.live` starts the task and dials its socket; the run response carries where to dial (`task.socket`).
+
+```typescript
+const { task, session } = await client.live(
+  { app: 'infsh/voice-loop', function: 'stream', input: { effect: 'robot' } },
+  {
+    onState: (state) => console.log(state), // connecting → waiting → live → ended
+    onBinary: (pcm) => speaker.write(new Int16Array(pcm)),
+    onPatch: (patch) => console.log(patch), // e.g. { frames: 120 }
+  }
+);
+
+session.sendBinary(micFrame);          // one item of the input's binary live field
+session.sendPatch({ effect: 'echo' }); // change an ordinary input while it runs
+session.close();                       // the function returns and the task completes
+await session.ended;
+```
+
+The session is `waiting` until the app's first frame (a cold start can take a minute) and gives up if the task ends before then. It dials again with a fresh credential when the relay restarts under it. `client.sockets.open(taskOrId, handlers)` reconnects to a running task's socket, e.g. after a page reload.
+
+What a function's socket carries is in its schemas: a live field is `{"type": "array", "format": "stream", "items": ...}`. `splitLiveSchema(schema)` separates the ordinary fields (the request body) from the live ones, and `pcmFormat(field.media)` reads the sample rate of a PCM audio field.
+
+On Node 18–21 there is no global `WebSocket`: pass one from the `ws` package as `{ webSocket: WebSocket }`.
+
 ### Sessions (Stateful Execution)
 
 Sessions allow you to maintain state across multiple task invocations. The worker stays warm between calls, preserving loaded models and in-memory state.
@@ -363,7 +389,7 @@ import {
   mcpTool,
   internalTools,
   string,
-  IntegrationProviderGoogle,
+  CredentialProviderGoogle,
 } from '@inferencesh/sdk';
 
 const clientTool = tool('get_weather')
@@ -375,7 +401,7 @@ const clientTool = tool('get_weather')
 const gmailSend = httpTool('gmail_send', 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send')
   .describe('Send an email via Gmail')
   .method('POST')
-  .auth({ integration: IntegrationProviderGoogle, integrationId: 'your-integration-id' })
+  .auth({ integration: CredentialProviderGoogle, integrationId: 'your-integration-id' })
   .build();
 
 // API key or bearer auth
@@ -588,6 +614,18 @@ const agent = client.agents.create({
 | `keepalive(sessionId)` | `POST /sessions/{id}/keepalive` | Reset idle expiration |
 | `end(sessionId)` | `DELETE /sessions/{id}` | End session and release worker |
 
+### `client.sockets`
+
+| Method | HTTP | Description |
+|--------|------|-------------|
+| `open(taskOrId, handlers?, options?)` | — | Dial a stream task's socket; returns a `LiveSession` |
+| `get(socketId)` | `GET /sockets/{id}` | The socket and what is known of its life |
+| `forTask(taskId)` | `POST /sockets/list` | The task's socket, or null |
+| `access(socketId)` | `POST /sockets/{id}/access` | A fresh credential for the caller's end |
+| `delete(socketId)` | `DELETE /sockets/{id}` | Delete the record |
+
+`client.live(params, handlers?, options?)` is `tasks.run(params, { wait: false })` followed by `sockets.open`.
+
 ## Task Status Constants
 
 ```typescript
@@ -606,24 +644,24 @@ if (task.status === TaskStatusCompleted) {
 
 ## Integration Constants
 
-`IntegrationDTO` fields (`provider`, `type`, `auth`, `status`) use typed string unions exported as constants:
+`CredentialDTO` fields (`provider`, `type`, `auth`, `status`) use typed string unions exported as constants:
 
 ```typescript
-import type { IntegrationDTO } from '@inferencesh/sdk';
+import type { CredentialDTO } from '@inferencesh/sdk';
 import {
-  IntegrationProviderGoogle,
-  IntegrationAuthTypeOAuth,
-  IntegrationStatusConnected,
-  IntegrationStatusDisconnected,
-  IntegrationStatusExpired,
-  IntegrationStatusError,
+  CredentialProviderGoogle,
+  CredentialTypeOAuth,
+  CredentialStatusConnected,
+  CredentialStatusDisconnected,
+  CredentialStatusExpired,
+  CredentialStatusError,
   isRequirementsNotMetException,
 } from '@inferencesh/sdk';
 
-function isGoogleConnected(integration: IntegrationDTO): boolean {
+function isGoogleConnected(integration: CredentialDTO): boolean {
   return (
-    integration.provider === IntegrationProviderGoogle &&
-    integration.status === IntegrationStatusConnected
+    integration.provider === CredentialProviderGoogle &&
+    integration.status === CredentialStatusConnected
   );
 }
 
@@ -633,7 +671,7 @@ try {
 } catch (error) {
   if (isRequirementsNotMetException(error)) {
     for (const req of error.errors) {
-      if (req.type === 'integration' && req.action?.provider === IntegrationProviderGoogle) {
+      if (req.type === 'integration' && req.action?.provider === CredentialProviderGoogle) {
         // User must connect Google — see https://inference.sh/docs/extend/integrations
       }
     }
@@ -643,9 +681,9 @@ try {
 
 | Constant group | Values |
 |----------------|--------|
-| `IntegrationProvider*` | `google`, `slack`, `notion`, `github`, `x`, `microsoft`, `salesforce`, `discord`, `gcp`, `mcp`, `reddit` |
-| `IntegrationAuthType*` | `service_account`, `oauth`, `api_key`, `wif`, `mcp` |
-| `IntegrationStatus*` | `connected`, `disconnected`, `expired`, `error` |
+| `CredentialProvider*` | `google`, `slack`, `notion`, `github`, `x`, `microsoft`, `salesforce`, `discord`, `gcp`, `mcp`, `reddit` |
+| `CredentialType*` | `service_account`, `oauth`, `api_key`, `wif`, `mcp` |
+| `CredentialStatus*` | `connected`, `disconnected`, `expired`, `error` |
 
 ## Instance Status Constants
 
@@ -698,7 +736,7 @@ import type {
   Task,
   ApiAppRunRequest,
   RunOptions,
-  IntegrationDTO,
+  CredentialDTO,
   AgentTool,
 } from '@inferencesh/sdk';
 ```

package/dist/agent/actions.js

@@ -4,7 +4,7 @@
  * Action creators that handle side effects (API calls, streaming).
  * These are created once per provider instance with access to dispatch.
  */
-import { AgentRunStateWorking, AgentRunStateSubmitted, AgentRunStateInputRequired, ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, } from '../types';
+import { AgentRunStateWorking, AgentRunStateSubmitted, AgentRunStateInputRequired, ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, ChatMessageStatusReady, ChatMessageStatusFailed, ChatMessageStatusCancelled, } from '../types';
 import { isChatBusy } from '../utils';
 import { StreamableManager } from '../http/streamable';
 import { PollManager } from '../http/poll';
@@ -139,17 +139,19 @@ export function createActions(ctx) {
                 checkTurnEnd(chatData);
             }
         });
-        // Token-by-token streaming state, reset at every assistant-message boundary.
-        const deltaAccum = createLLMDeltaAccumulator();
+        // 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 new assistant message starts a new accumulation. The accumulator is
-            // cumulative and shared across the whole connection, so without this the
-            // next message's deltas merge into the previous message's state — and
-            // because concat with "" is a no-op, a turn that is only tool calls
-            // would render the previous message's text as its own.
-            if (message.role === 'assistant' && !getState().messages.some(m => m.id === message.id)) {
-                deltaAccum.reset();
+            // A message that has reached a terminal state will receive no further
+            // deltas, so its accumulator is done. This bounds the map by the number
+            // of messages streaming at once rather than by chat length.
+            if (message.status === ChatMessageStatusReady
+                || message.status === ChatMessageStatusFailed
+                || message.status === ChatMessageStatusCancelled) {
+                deltaAccums.delete(message.id);
             }
             updateMessage(message, fields);
         });
@@ -163,10 +165,23 @@ export function createActions(ctx) {
                 checkTurnEnd({ ...currentChat, active_run: run });
         });
         manager.addEventListener('delta', (evt) => {
-            if (evt && evt.delta) {
-                deltaAccum.apply(evt.delta);
-                dispatch({ type: 'DELTA_TOKEN', payload: deltaAccum.toOutput() });
+            if (!evt || !evt.delta)
+                return;
+            // On a chat stream every task is created with an execution edge, so a
+            // delta with no resource id means something is wrong upstream — a missing
+            // or ambiguous edge, or a failed lookup. Guessing a target there would
+            // reintroduce exactly the misattribution this field exists to end, so
+            // drop it: the text still lands when the message itself arrives.
+            const messageId = evt.resource_id;
+            if (!messageId)
+                return;
+            let accum = deltaAccums.get(messageId);
+            if (!accum) {
+                accum = createLLMDeltaAccumulator();
+                deltaAccums.set(messageId, accum);
             }
+            accum.apply(evt.delta);
+            dispatch({ type: 'DELTA_TOKEN', payload: { messageId, output: accum.toOutput() } });
         });
         setStreamManager(manager);
         manager.start();

package/dist/agent/reducer.js

@@ -85,16 +85,19 @@ export function chatReducer(state, action) {
                 messages: [...state.messages, action.payload].sort((a, b) => a.order - b.order),
             };
         case 'DELTA_TOKEN': {
-            const output = action.payload;
+            const { messageId, output } = action.payload;
             const msgs = state.messages;
-            const lastAssistant = [...msgs].reverse().find(m => m.role === 'assistant');
-            if (!lastAssistant)
+            // Apply to the message the delta names — never to a guessed one. A
+            // message we have not received yet (or an unnamed delta) is dropped
+            // rather than misattributed; the text still arrives with the message.
+            const target = msgs.find(m => m.id === messageId);
+            if (!target)
                 return state;
-            const textBlock = lastAssistant.content?.find(c => c.type === 'text');
+            const textBlock = target.content?.find(c => c.type === 'text');
             const newContent = textBlock
-                ? lastAssistant.content.map(c => c.type === 'text' ? { ...c, text: output.response } : c)
-                : [{ type: 'text', text: output.response }, ...lastAssistant.content];
-            const newMessages = msgs.map(m => m.id === lastAssistant.id ? { ...lastAssistant, content: newContent } : m);
+                ? target.content.map(c => c.type === 'text' ? { ...c, text: output.response } : c)
+                : [{ type: 'text', text: output.response }, ...target.content];
+            const newMessages = msgs.map(m => m.id === target.id ? { ...target, content: newContent } : m);
             return { ...state, messages: newMessages };
         }
         case 'SET_CONNECTION_STATUS':

package/dist/agent/types.d.ts

@@ -220,7 +220,10 @@ export type ChatAction = {
     payload: ChatMessageDTO;
 } | {
     type: 'DELTA_TOKEN';
-    payload: Record<string, any>;
+    payload: {
+        messageId: string;
+        output: Record<string, any>;
+    };
 } | {
     type: 'SET_CONNECTION_STATUS';
     payload: ChatStatus;

package/dist/api/agents.d.ts

@@ -1,7 +1,7 @@
 import { HttpClient } from '../http/client';
 import type { Response } from '../http/response';
 import { FilesAPI } from './files';
-import { ChatDTO, ChatMessageDTO, AgentConfigInput as AgentConfig, AgentDTO, AgentVersionDTO, CreateAgentRequest, FileDTO as File, InterruptDTO, CursorListRequest, CursorListResponse } from '../types';
+import { ChatDTO, ChatMessageDTO, LLMDelta, LLMOutput, AgentConfigInput as AgentConfig, AgentDTO, AgentVersionDTO, CreateAgentRequest, FileDTO as File, InterruptDTO, CursorListRequest, CursorListResponse } from '../types';
 /** Internal tool definition returned by getInternalTools */
 export interface InternalToolDefinition {
     id: string;
@@ -20,6 +20,20 @@ export interface AgentOptions {
     /** Per-chat context variables — resolved in call tool URL templates ({{context.X}}) */
     context?: Record<string, string>;
 }
+/**
+ * One streamed token batch for a message, with everything received for that
+ * message so far. `output.response` is the assistant text as it grows.
+ */
+export interface AgentDelta {
+    /** The chat message the tokens belong to (normally this turn's assistant message) */
+    messageId: string;
+    /** This batch alone */
+    delta: LLMDelta;
+    /** All batches for the message merged, in the shape of the message's final output */
+    output: LLMOutput;
+    /** Producer sequence number, monotonically increasing per message */
+    seq: number;
+}
 export interface SendMessageOptions {
     /** File attachments - Blob (will be uploaded) or FileDTO (already uploaded, has uri) */
     files?: (Blob | File)[];
@@ -27,6 +41,12 @@ export interface SendMessageOptions {
     onMessage?: (message: ChatMessageDTO) => void;
     /** Callback for chat updates */
     onChat?: (chat: ChatDTO) => void;
+    /**
+     * Callback for token-by-token output while the assistant message is being
+     * generated. Streaming mode only: with `stream: false` there are no deltas
+     * and the message arrives whole through onMessage.
+     */
+    onDelta?: (delta: AgentDelta) => void;
     /** Callback when a client tool needs execution */
     onToolCall?: (invocation: {
         id: string;

package/dist/api/agents.js

@@ -1,5 +1,6 @@
 import { StreamableManager } from '../http/streamable';
 import { PollManager } from '../http/poll';
+import { createLLMDeltaAccumulator } from '../delta';
 import { ChatMessageStatusCancelled, ChatMessageStatusFailed, ChatMessageStatusReady, ToolTypeClient, ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, } from '../types';
 import { isChatBusy } from '../utils';
 const terminalMessageStatuses = new Set([ChatMessageStatusReady, ChatMessageStatusFailed, ChatMessageStatusCancelled]);
@@ -59,7 +60,7 @@ export class Agent {
     async sendMessage(text, options = {}) {
         this.dispatchedToolCalls.clear();
         const isTemplate = typeof this.config === 'string';
-        const hasCallbacks = !!(options.onMessage || options.onChat || options.onToolCall);
+        const hasCallbacks = !!(options.onMessage || options.onChat || options.onToolCall || options.onDelta);
         // Process files - either already uploaded (FileDTO with uri) or needs upload (Blob)
         let imageUris;
         let fileUris;
@@ -227,7 +228,30 @@ export class Agent {
                 else
                     idlePending = false;
             });
+            // One accumulator per message being streamed, keyed by the message id
+            // the delta names, so a tool-call-only turn never shows the previous
+            // message's text. Same attribution rule as the React hooks.
+            const deltaAccums = new Map();
+            this.stream.addEventListener('delta', (evt) => {
+                if (!options.onDelta || !evt?.delta || !evt.resource_id)
+                    return;
+                let accum = deltaAccums.get(evt.resource_id);
+                if (!accum) {
+                    accum = createLLMDeltaAccumulator();
+                    deltaAccums.set(evt.resource_id, accum);
+                }
+                accum.apply(evt.delta);
+                options.onDelta({
+                    messageId: evt.resource_id,
+                    delta: evt.delta,
+                    output: accum.toOutput(),
+                    seq: evt.seq,
+                });
+            });
             this.stream.addEventListener('chat_messages', (message) => {
+                // A terminal message receives no further deltas.
+                if (terminalMessageStatuses.has(message.status))
+                    deltaAccums.delete(message.id);
                 gate.observeMessage(message);
                 options.onMessage?.(message);
                 if (idlePending && gate.settled)

package/dist/api/integrations.d.ts

@@ -1,6 +1,6 @@
 import { HttpClient } from '../http/client';
 import type { Response } from '../http/response';
-import { IntegrationDTO, IntegrationConfigDTO, IntegrationConnectRequest, IntegrationConnectResponse, CursorListRequest, CursorListResponse } from '../types';
+import { CredentialDTO, CredentialConfigDTO, CredentialConnectRequest, CredentialConnectResponse, CursorListRequest, CursorListResponse } from '../types';
 /**
  * Integrations API
  */
@@ -10,15 +10,15 @@ export declare class IntegrationsAPI {
     /**
      * List integrations with cursor-based pagination
      */
-    list(params?: Partial<CursorListRequest>): Promise<Response<CursorListResponse<IntegrationDTO>>>;
+    list(params?: Partial<CursorListRequest>): Promise<Response<CursorListResponse<CredentialDTO>>>;
     /**
      * Get available integrations
      */
-    listAvailable(): Promise<Response<IntegrationConfigDTO[]>>;
+    listAvailable(): Promise<Response<CredentialConfigDTO[]>>;
     /**
      * Get integration configs
      */
-    getConfigs(): Promise<Response<IntegrationConfigDTO[]>>;
+    getConfigs(): Promise<Response<CredentialConfigDTO[]>>;
     /**
      * Get capabilities
      */
@@ -30,11 +30,11 @@ export declare class IntegrationsAPI {
     /**
      * Connect an integration
      */
-    connect(data: IntegrationConnectRequest): Promise<Response<IntegrationConnectResponse>>;
+    connect(data: CredentialConnectRequest): Promise<Response<CredentialConnectResponse>>;
     /**
      * Get an integration by provider key
      */
-    get(provider: string): Promise<Response<IntegrationDTO>>;
+    get(provider: string): Promise<Response<CredentialDTO>>;
     /**
      * Disconnect an integration
      */

package/dist/api/sockets.d.ts

@@ -0,0 +1,44 @@
+import { HttpClient } from '../http/client';
+import type { Response } from '../http/response';
+import { LiveSession, type LiveHandlers, type WebSocketConstructor } from '../live/session';
+import { CursorListRequest, CursorListResponse, SocketAccess, SocketDTO, TaskDTO as Task } from '../types';
+import type { TasksAPI } from './tasks';
+/** What identifies the socket to open: the run response (which carries the access), a task, or a task id. */
+export type SocketTarget = (Pick<Task, 'id' | 'status'> & {
+    socket?: SocketAccess;
+}) | string;
+export interface OpenSocketOptions {
+    /**
+     * Follow the task while waiting for the app, and end the session if the
+     * task ends first (default: true). Off, a task that fails before its
+     * worker dials leaves the session waiting until the relay's pair timeout.
+     */
+    watchTask?: boolean;
+    /** The WebSocket to dial with; defaults to the runtime's global one. */
+    webSocket?: WebSocketConstructor;
+}
+/**
+ * Sockets API: the duplex connection of a stream task.
+ *
+ * A stream function keeps a socket open with its caller for the life of the
+ * task. The run response carries the caller's end (`task.socket`); `open`
+ * dials it and gives back a LiveSession.
+ */
+export declare class SocketsAPI {
+    private readonly http;
+    private readonly tasks;
+    constructor(http: HttpClient, tasks: TasksAPI);
+    get(id: string): Promise<Response<SocketDTO>>;
+    list(params?: Partial<CursorListRequest>): Promise<Response<CursorListResponse<SocketDTO>>>;
+    /** The task's socket, or null when it has none (not a stream function). */
+    forTask(taskId: string): Promise<SocketDTO | null>;
+    /** A fresh credential for the caller's end, e.g. after a reload or to redial. */
+    access(id: string): Promise<Response<SocketAccess>>;
+    delete(id: string): Promise<Response<void>>;
+    /**
+     * Dials the caller's end of a stream task's socket. The session is
+     * `waiting` until the app's first frame, then `live`; see LiveSession.
+     */
+    open(target: SocketTarget, handlers?: LiveHandlers, options?: OpenSocketOptions): Promise<LiveSession>;
+}
+export declare function createSocketsAPI(http: HttpClient, tasks: TasksAPI): SocketsAPI;

package/dist/api/sockets.js

@@ -0,0 +1,61 @@
+import { LiveSession } from '../live/session';
+import { OpEqual } from '../types';
+/**
+ * Sockets API: the duplex connection of a stream task.
+ *
+ * A stream function keeps a socket open with its caller for the life of the
+ * task. The run response carries the caller's end (`task.socket`); `open`
+ * dials it and gives back a LiveSession.
+ */
+export class SocketsAPI {
+    constructor(http, tasks) {
+        this.http = http;
+        this.tasks = tasks;
+    }
+    async get(id) {
+        return this.http.request('get', `/sockets/${id}`);
+    }
+    async list(params) {
+        return this.http.request('post', '/sockets/list', { data: params });
+    }
+    /** The task's socket, or null when it has none (not a stream function). */
+    async forTask(taskId) {
+        const res = await this.list({ limit: 1, filters: [{ field: 'task_id', operator: OpEqual, value: taskId }] });
+        return res.data?.items?.[0] ?? null;
+    }
+    /** A fresh credential for the caller's end, e.g. after a reload or to redial. */
+    async access(id) {
+        return this.http.request('post', `/sockets/${id}/access`);
+    }
+    async delete(id) {
+        return this.http.request('delete', `/sockets/${id}`);
+    }
+    /**
+     * Dials the caller's end of a stream task's socket. The session is
+     * `waiting` until the app's first frame, then `live`; see LiveSession.
+     */
+    async open(target, handlers = {}, options = {}) {
+        const task = typeof target === 'string' ? (await this.tasks.get(target)).data : target;
+        let access = typeof target === 'string' ? undefined : target.socket;
+        let socketId = access?.id;
+        if (!access) {
+            const socket = await this.forTask(task.id);
+            if (!socket)
+                throw new Error(`task ${task.id} has no socket: is it a stream function?`);
+            socketId = socket.id;
+            access = (await this.access(socket.id)).data;
+        }
+        const session = new LiveSession({
+            access,
+            handlers,
+            renew: async () => (await this.access(socketId)).data,
+            task: options.watchTask === false ? undefined : this.tasks.watch(task),
+            webSocket: options.webSocket,
+        });
+        session.connect();
+        return session;
+    }
+}
+export function createSocketsAPI(http, tasks) {
+    return new SocketsAPI(http, tasks);
+}

package/dist/api/tasks.d.ts

@@ -1,13 +1,12 @@
 import { HttpClient } from '../http/client';
 import type { Response } from '../http/response';
 import { TaskDTO as Task, TaskLogsDTO, TaskTimingsDTO, ApiAppRunRequest, CursorListRequest, CursorListResponse } from '../types';
-export interface RunOptions {
+/** How to follow a task while it runs; see TasksAPI.watch. */
+export interface WatchOptions {
     /** Callback for real-time status updates */
     onUpdate?: (update: Task) => void;
     /** Callback for partial updates with list of changed fields */
     onPartialUpdate?: (update: Task, fields: string[]) => void;
-    /** Wait for task completion (default: true) */
-    wait?: boolean;
     /** Maximum retry attempts when using polling mode (stream: false). Default: 5 */
     maxReconnects?: number;
     /** Use SSE streaming (true) or polling (false). Overrides client default. */
@@ -17,6 +16,15 @@ export interface RunOptions {
     /** Callback for streaming delta events (token-by-token updates) */
     onDelta?: (delta: Record<string, any>, seq: number) => void;
 }
+export interface RunOptions extends WatchOptions {
+    /** Wait for task completion (default: true) */
+    wait?: boolean;
+}
+/** A task being followed: `done` settles when it ends, `stop` ends the watch early. */
+export interface TaskWatch {
+    done: Promise<Task>;
+    stop(): void;
+}
 /**
  * Tasks API
  */
@@ -55,8 +63,15 @@ export declare class TasksAPI {
      * Run a task and optionally wait for completion
      */
     run(params: ApiAppRunRequest, processedInput: unknown, options?: RunOptions): Promise<Task>;
+    /**
+     * Follows a task until it ends. `done` resolves with the task when it
+     * completes and rejects when it fails or is cancelled; `stop` ends the
+     * watch early and leaves `done` pending.
+     */
+    watch(task: Pick<Task, 'id' | 'status'>, options?: WatchOptions): TaskWatch;
+    private watchStream;
     /** Poll GET /tasks/{id}/status until terminal, full-fetch on status change. */
-    private pollUntilTerminal;
+    private watchPoll;
     /**
      * Update task visibility
      */

package/dist/api/tasks.js

@@ -69,7 +69,7 @@ export class TasksAPI {
      * Run a task and optionally wait for completion
      */
     async run(params, processedInput, options = {}) {
-        const { onUpdate, onPartialUpdate, onDelta, wait = true, } = options;
+        const { wait = true } = options;
         const resp = await this.http.request('post', '/apps/run', {
             data: {
                 ...params,
@@ -81,16 +81,39 @@ export class TasksAPI {
         if (!wait) {
             return stripTask(task);
         }
+        return this.watch(task, options).done;
+    }
+    /**
+     * Follows a task until it ends. `done` resolves with the task when it
+     * completes and rejects when it fails or is cancelled; `stop` ends the
+     * watch early and leaves `done` pending.
+     */
+    watch(task, options = {}) {
         const useStream = options.stream ?? this.http.getStreamDefault();
-        if (!useStream) {
-            return this.pollUntilTerminal(task, options);
-        }
-        // Wait for completion with optional updates via NDJSON streaming
+        return useStream ? this.watchStream(task, options) : this.watchPoll(task, options);
+    }
+    watchStream(task, options) {
+        const { onUpdate, onPartialUpdate, onDelta } = options;
         // Accumulate state across partial updates to preserve fields like session_id
         let accumulatedTask = { ...task };
         const { url, headers, credentials } = this.http.getStreamableConfig(`/tasks/${task.id}/stream`);
-        return new Promise((resolve, reject) => {
-            const streamManager = new StreamableManager({
+        let streamManager;
+        const done = new Promise((resolve, reject) => {
+            const settle = (data, stripped) => {
+                if (parseStatus(data.status) === TaskStatusCompleted) {
+                    streamManager.stop();
+                    resolve(stripped);
+                }
+                else if (parseStatus(data.status) === TaskStatusFailed) {
+                    streamManager.stop();
+                    reject(new Error(data.error || 'task failed'));
+                }
+                else if (parseStatus(data.status) === TaskStatusCancelled) {
+                    streamManager.stop();
+                    reject(new Error('task cancelled'));
+                }
+            };
+            streamManager = new StreamableManager({
                 url,
                 headers,
                 credentials,
@@ -100,36 +123,14 @@ export class TasksAPI {
                     accumulatedTask = { ...accumulatedTask, ...data };
                     const stripped = stripTask(accumulatedTask);
                     onUpdate?.(stripped);
-                    if (parseStatus(data.status) === TaskStatusCompleted) {
-                        streamManager.stop();
-                        resolve(stripped);
-                    }
-                    else if (parseStatus(data.status) === TaskStatusFailed) {
-                        streamManager.stop();
-                        reject(new Error(data.error || 'task failed'));
-                    }
-                    else if (parseStatus(data.status) === TaskStatusCancelled) {
-                        streamManager.stop();
-                        reject(new Error('task cancelled'));
-                    }
+                    settle(data, stripped);
                 },
                 onPartialData: (data, fields) => {
                     // Merge partial update, preserving fields not in this update
                     accumulatedTask = { ...accumulatedTask, ...data };
                     const stripped = stripTask(accumulatedTask);
                     onPartialUpdate?.(stripped, fields);
-                    if (parseStatus(data.status) === TaskStatusCompleted) {
-                        streamManager.stop();
-                        resolve(stripped);
-                    }
-                    else if (parseStatus(data.status) === TaskStatusFailed) {
-                        streamManager.stop();
-                        reject(new Error(data.error || 'task failed'));
-                    }
-                    else if (parseStatus(data.status) === TaskStatusCancelled) {
-                        streamManager.stop();
-                        reject(new Error('task cancelled'));
-                    }
+                    settle(data, stripped);
                 },
                 onError: (error) => {
                     reject(error);
@@ -138,14 +139,16 @@ export class TasksAPI {
             });
             streamManager.start();
         });
+        return { done, stop: () => streamManager.stop() };
     }
     /** Poll GET /tasks/{id}/status until terminal, full-fetch on status change. */
-    pollUntilTerminal(task, options) {
+    watchPoll(task, options) {
         const { onUpdate, maxReconnects = 5 } = options;
         const intervalMs = options.pollIntervalMs ?? this.http.getPollIntervalMs();
         let prevStatus = task.status;
-        return new Promise((resolve, reject) => {
-            const poller = new PollManager({
+        let poller;
+        const done = new Promise((resolve, reject) => {
+            poller = new PollManager({
                 pollFunction: async () => {
                     const resp = await this.http.request('get', `/tasks/${task.id}/status`);
                     return resp.data;
@@ -187,6 +190,7 @@ export class TasksAPI {
             });
             poller.start();
         });
+        return { done, stop: () => poller.stop() };
     }
     /**
      * Update task visibility