@inferencesh/sdk 0.6.52 → 0.6.54

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

package/dist/api/agents.d.ts

@@ -57,6 +57,14 @@ export interface SendMessageOptions {
     stream?: boolean;
     /** Polling interval in ms when stream is false. Overrides client default. */
     pollIntervalMs?: number;
+    /**
+     * Stops waiting for the turn. Aborting rejects sendMessage with
+     * `signal.reason` and closes the stream or poller; the agent keeps running
+     * server-side (use stopChat() to cancel it). A turn parked on a tool
+     * approval or an authorization counts as still running, so a client that
+     * cannot resolve those is the typical caller.
+     */
+    signal?: AbortSignal;
 }
 export interface AgentRunOptions extends Omit<SendMessageOptions, 'stream'> {
     /** Polling interval in ms (default: 2000) */
@@ -86,6 +94,8 @@ export declare class Agent {
         userMessage: ChatMessageDTO;
         assistantMessage: ChatMessageDTO;
     }>;
+    /** Resolves with `wait`, or rejects with `signal.reason` and stops the stream/poller. */
+    private abortable;
     /** Get chat by ID */
     getChat(chatId?: string): Promise<ChatDTO | null>;
     /** Stop the current chat generation */

package/dist/api/agents.js

@@ -59,6 +59,8 @@ export class Agent {
     /** Send a message to the agent */
     async sendMessage(text, options = {}) {
         this.dispatchedToolCalls.clear();
+        if (options.signal?.aborted)
+            throw options.signal.reason;
         const isTemplate = typeof this.config === 'string';
         const hasCallbacks = !!(options.onMessage || options.onChat || options.onToolCall || options.onDelta);
         // Process files - either already uploaded (FileDTO with uri) or needs upload (Blob)
@@ -132,10 +134,25 @@ export class Agent {
         }
         // Wait for completion
         if (waitPromise) {
-            await waitPromise;
+            await this.abortable(waitPromise, options.signal);
         }
         return { userMessage: response.user_message, assistantMessage: response.assistant_message };
     }
+    /** Resolves with `wait`, or rejects with `signal.reason` and stops the stream/poller. */
+    abortable(wait, signal) {
+        if (!signal)
+            return wait;
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                this.disconnect();
+                reject(signal.reason);
+            };
+            if (signal.aborted)
+                return onAbort();
+            signal.addEventListener('abort', onAbort, { once: true });
+            wait.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+        });
+    }
     /** Get chat by ID */
     async getChat(chatId) {
         const id = chatId || this.chatId;

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

package/dist/index.d.ts

@@ -5,7 +5,8 @@ export { StreamManager, type StreamManagerOptions, type PartialDataWrapper } fro
 export { StreamableManager, type StreamableManagerOptions, type StreamableMessage, streamable, streamableRaw } from './http/streamable';
 export { PollManager, type PollManagerOptions } from './http/poll';
 export { InferenceError, RequirementsNotMetException, SessionError, SessionNotFoundError, SessionExpiredError, SessionEndedError, WorkerLostError, isRequirementsNotMetException, isInferenceError, isSessionError, } from './http/errors';
-export { TasksAPI, type RunOptions } from './api/tasks';
+export { TasksAPI, type RunOptions, type WatchOptions, type TaskWatch } from './api/tasks';
+export { SocketsAPI, type SocketTarget, type OpenSocketOptions } from './api/sockets';
 export { FilesAPI, type UploadFileOptions } from './api/files';
 export { AgentsAPI, Agent, type AgentOptions, type SendMessageOptions, type AgentRunOptions, type AgentDelta } from './api/agents';
 export { SessionsAPI } from './api/sessions';
@@ -23,6 +24,10 @@ export { IntegrationsAPI } from './api/integrations';
 export { SearchAPI } from './api/search';
 export { ProjectsAPI } from './api/projects';
 export { MCPServersAPI } from './api/mcp-servers';
+export { LiveSession } from './live/session';
+export type { LiveState, LiveEnd, LiveHandlers, LiveSessionOptions, WebSocketLike, WebSocketConstructor } from './live/session';
+export { STREAM_FORMAT, isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveField, alternativeLabel, } from './live/schema';
+export type { JsonSchema, MediaType, PCMFormat, LiveField } from './live/schema';
 export { tool, appTool, agentTool, webhookTool, httpTool, callTool, mcpTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional, } from './tool-builder';
 export type { ClientTool, ClientToolHandler } from './tool-builder';
 export { lifecycleHook } from './hook-builder';
@@ -35,6 +40,9 @@ export type { TaskDTO as Task } from './types';
 export type { CredentialDTO as IntegrationDTO, CredentialConfigDTO as IntegrationConfigDTO, CredentialConnectRequest as IntegrationConnectRequest, CredentialConnectResponse as IntegrationConnectResponse, CredentialCompleteOAuthRequest as IntegrationCompleteOAuthRequest, CredentialRequirement as IntegrationRequirement, CredentialStatus as IntegrationStatus, CredentialScope as IntegrationScope, CredentialGrant as IntegrationGrant, CredentialType as IntegrationAuthType, CredentialProvider as IntegrationProvider, } from './types';
 import { HttpClient, type HttpClientConfig } from './http/client';
 import { TasksAPI, RunOptions } from './api/tasks';
+import { SocketsAPI } from './api/sockets';
+import { LiveSession, type LiveHandlers } from './live/session';
+import type { OpenSocketOptions } from './api/sockets';
 import { FilesAPI, UploadFileOptions } from './api/files';
 import { AgentsAPI, Agent, AgentOptions } from './api/agents';
 import { SessionsAPI } from './api/sessions';
@@ -108,6 +116,7 @@ export declare class Inference {
     readonly search: SearchAPI;
     readonly projects: ProjectsAPI;
     readonly mcpServers: MCPServersAPI;
+    readonly sockets: SocketsAPI;
     constructor(config: InferenceConfig | HttpClientConfig);
     /** @internal */
     _request<T>(method: 'get' | 'post' | 'put' | 'delete', endpoint: string, options?: {
@@ -120,6 +129,24 @@ export declare class Inference {
      * Run a task on inference.sh
      */
     run(params: ApiAppRunRequest, options?: RunOptions): Promise<Task>;
+    /**
+     * Start a stream function and open its socket. The task runs until the
+     * session is closed (or the app returns); `session.ended` settles then.
+     *
+     * @example
+     * ```typescript
+     * const { session } = await client.live({ app: 'infsh/voice-loop', function: 'stream', input: { effect: 'robot' } }, {
+     *   onBinary: (pcm) => speaker.write(pcm),
+     *   onPatch: (patch) => console.log(patch),
+     * });
+     * session.sendBinary(micFrame);
+     * session.close();
+     * ```
+     */
+    live(params: ApiAppRunRequest, handlers?: LiveHandlers, options?: OpenSocketOptions): Promise<{
+        task: Task;
+        session: LiveSession;
+    }>;
     /**
      * Upload a file
      */

package/dist/index.js

@@ -8,6 +8,7 @@ export { InferenceError, RequirementsNotMetException, SessionError, SessionNotFo
 isRequirementsNotMetException, isInferenceError, isSessionError, } from './http/errors';
 // API modules
 export { TasksAPI } from './api/tasks';
+export { SocketsAPI } from './api/sockets';
 export { FilesAPI } from './api/files';
 export { AgentsAPI, Agent } from './api/agents';
 export { SessionsAPI } from './api/sessions';
@@ -25,6 +26,9 @@ export { IntegrationsAPI } from './api/integrations';
 export { SearchAPI } from './api/search';
 export { ProjectsAPI } from './api/projects';
 export { MCPServersAPI } from './api/mcp-servers';
+// Live: the socket of a stream task and the live fields of its schemas
+export { LiveSession } from './live/session';
+export { STREAM_FORMAT, isLiveField, parseMediaType, pcmFormat, splitLiveSchema, binaryLiveField, alternativeLabel, } from './live/schema';
 // Tool Builder (fluent API)
 export { tool, appTool, agentTool, webhookTool, httpTool, callTool, mcpTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional, } from './tool-builder';
 // Hook Builder (fluent API)
@@ -40,6 +44,7 @@ export * from './types';
 // =============================================================================
 import { HttpClient } from './http/client';
 import { TasksAPI } from './api/tasks';
+import { SocketsAPI } from './api/sockets';
 import { FilesAPI } from './api/files';
 import { AgentsAPI } from './api/agents';
 import { SessionsAPI } from './api/sessions';
@@ -100,6 +105,7 @@ export class Inference {
         this.search = new SearchAPI(this.http);
         this.projects = new ProjectsAPI(this.http);
         this.mcpServers = new MCPServersAPI(this.http);
+        this.sockets = new SocketsAPI(this.http, this.tasks);
     }
     // Legacy methods for backward compatibility
     /** @internal */
@@ -117,6 +123,25 @@ export class Inference {
         const processedInput = await this.files.processInput(params.input);
         return this.tasks.run(params, processedInput, options);
     }
+    /**
+     * Start a stream function and open its socket. The task runs until the
+     * session is closed (or the app returns); `session.ended` settles then.
+     *
+     * @example
+     * ```typescript
+     * const { session } = await client.live({ app: 'infsh/voice-loop', function: 'stream', input: { effect: 'robot' } }, {
+     *   onBinary: (pcm) => speaker.write(pcm),
+     *   onPatch: (patch) => console.log(patch),
+     * });
+     * session.sendBinary(micFrame);
+     * session.close();
+     * ```
+     */
+    async live(params, handlers = {}, options = {}) {
+        const task = await this.run(params, { wait: false });
+        const session = await this.sockets.open(task, handlers, options);
+        return { task, session };
+    }
     /**
      * Upload a file
      */

package/dist/live/schema.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Live fields of a stream function.
+ *
+ * A stream function's input and output schemas are ordinary JSON Schemas in
+ * which some properties are live: `{"type": "array", "format": "stream",
+ * "items": ...}`. Their values travel over the task's socket while it runs,
+ * instead of in the request body or the final output. `format: "stream"` is
+ * the sibling of `format: "file"`: the same media, live instead of by
+ * reference.
+ *
+ * On the wire a binary frame is one item of the schema's binary live field
+ * (there is at most one per direction), and a JSON text frame is a partial
+ * object keyed by property name: an item of a live field, or a new value for
+ * an ordinary one.
+ *
+ * The helpers are generic over the schema type so a caller with a richer
+ * JSON Schema type keeps it.
+ */
+export declare const STREAM_FORMAT = "stream";
+/** The part of JSON Schema these helpers read. */
+export interface JsonSchema {
+    $ref?: string;
+    $defs?: Record<string, JsonSchema>;
+    type?: string | string[];
+    format?: string;
+    title?: string;
+    description?: string;
+    contentMediaType?: string;
+    const?: unknown;
+    items?: JsonSchema | JsonSchema[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    anyOf?: JsonSchema[];
+    oneOf?: JsonSchema[];
+}
+export declare function isLiveField(schema: JsonSchema | undefined | null): boolean;
+export interface MediaType {
+    /** e.g. "audio/pcm" */
+    type: string;
+    /** e.g. {format: "s16le", rate: "16000", channels: "1"} */
+    params: Record<string, string>;
+}
+export declare function parseMediaType(value: string | undefined): MediaType | null;
+export interface PCMFormat {
+    sampleRate: number;
+    channels: number;
+}
+/** The PCM format of a media type, or null when it is not 16-bit PCM audio. */
+export declare function pcmFormat(media: MediaType | null): PCMFormat | null;
+export interface LiveField<S extends JsonSchema = JsonSchema> {
+    key: string;
+    title: string;
+    description?: string;
+    /** Items are binary frames. */
+    binary: boolean;
+    /** Set when binary. */
+    media: MediaType | null;
+    /**
+     * What one item can be, references resolved: the alternatives of an anyOf,
+     * or the single item schema. Empty for a binary field.
+     */
+    alternatives: S[];
+}
+/**
+ * Splits a function schema into what a form renders (the ordinary
+ * properties) and what the socket carries (the live ones).
+ */
+export declare function splitLiveSchema<S extends JsonSchema>(schema: S | undefined | null): {
+    ordinary: S | null;
+    live: LiveField<S>[];
+};
+/** The schema's one binary live field. A binary frame carries no field name. */
+export declare function binaryLiveField<S extends JsonSchema>(live: LiveField<S>[]): LiveField<S> | null;
+/** A label for one alternative of a JSON live field: its `type` const, else its title. */
+export declare function alternativeLabel(schema: JsonSchema, index: number): string;

package/dist/live/schema.js

@@ -0,0 +1,108 @@
+/**
+ * Live fields of a stream function.
+ *
+ * A stream function's input and output schemas are ordinary JSON Schemas in
+ * which some properties are live: `{"type": "array", "format": "stream",
+ * "items": ...}`. Their values travel over the task's socket while it runs,
+ * instead of in the request body or the final output. `format: "stream"` is
+ * the sibling of `format: "file"`: the same media, live instead of by
+ * reference.
+ *
+ * On the wire a binary frame is one item of the schema's binary live field
+ * (there is at most one per direction), and a JSON text frame is a partial
+ * object keyed by property name: an item of a live field, or a new value for
+ * an ordinary one.
+ *
+ * The helpers are generic over the schema type so a caller with a richer
+ * JSON Schema type keeps it.
+ */
+export const STREAM_FORMAT = 'stream';
+export function isLiveField(schema) {
+    return !!schema && schema.format === STREAM_FORMAT;
+}
+export function parseMediaType(value) {
+    if (!value)
+        return null;
+    const [type, ...rest] = value.split(';').map((part) => part.trim());
+    if (!type)
+        return null;
+    const params = {};
+    for (const part of rest) {
+        const eq = part.indexOf('=');
+        if (eq > 0)
+            params[part.slice(0, eq).trim().toLowerCase()] = part.slice(eq + 1).trim();
+    }
+    return { type: type.toLowerCase(), params };
+}
+/** The PCM format of a media type, or null when it is not 16-bit PCM audio. */
+export function pcmFormat(media) {
+    if (!media || media.type !== 'audio/pcm')
+        return null;
+    if (media.params.format && media.params.format !== 's16le')
+        return null;
+    const sampleRate = Number(media.params.rate ?? 16000);
+    const channels = Number(media.params.channels ?? 1);
+    if (!Number.isFinite(sampleRate) || sampleRate <= 0 || !Number.isFinite(channels) || channels <= 0)
+        return null;
+    return { sampleRate, channels };
+}
+/** Resolves a `#/$defs/` reference against the root, recursively. */
+function deref(schema, root) {
+    if (!schema.$ref || !root.$defs)
+        return schema;
+    const name = schema.$ref.replace('#/$defs/', '');
+    const target = root.$defs[name];
+    if (!target)
+        return schema;
+    // The reference's own fields (title, description) win over the target's.
+    return { ...deref(target, root), ...schema };
+}
+function itemAlternatives(items, root) {
+    const resolved = deref(items, root);
+    const options = (resolved.anyOf ?? resolved.oneOf);
+    if (options?.length)
+        return options.map((option) => deref(option, root));
+    return [resolved];
+}
+/**
+ * Splits a function schema into what a form renders (the ordinary
+ * properties) and what the socket carries (the live ones).
+ */
+export function splitLiveSchema(schema) {
+    if (!schema?.properties)
+        return { ordinary: schema ?? null, live: [] };
+    const ordinary = {};
+    const live = [];
+    for (const [key, property] of Object.entries(schema.properties)) {
+        if (!isLiveField(property)) {
+            ordinary[key] = property;
+            continue;
+        }
+        const items = ((Array.isArray(property.items) ? property.items[0] : property.items) ?? {});
+        const resolvedItems = deref(items, schema);
+        const binary = resolvedItems.format === 'binary';
+        live.push({
+            key,
+            title: property.title ?? key,
+            description: property.description,
+            binary,
+            media: binary ? parseMediaType(resolvedItems.contentMediaType) : null,
+            alternatives: binary ? [] : itemAlternatives(items, schema),
+        });
+    }
+    return {
+        ordinary: { ...schema, properties: ordinary, required: schema.required?.filter((key) => key in ordinary) },
+        live,
+    };
+}
+/** The schema's one binary live field. A binary frame carries no field name. */
+export function binaryLiveField(live) {
+    return live.find((field) => field.binary) ?? null;
+}
+/** A label for one alternative of a JSON live field: its `type` const, else its title. */
+export function alternativeLabel(schema, index) {
+    const tag = schema.properties?.type?.const;
+    if (typeof tag === 'string')
+        return tag;
+    return schema.title ?? `option ${index + 1}`;
+}

package/dist/live/session.d.ts

@@ -0,0 +1,100 @@
+/**
+ * One end of a stream task's socket, as the caller holds it.
+ *
+ * The task's run response carries where to dial and a short-lived credential
+ * (SocketAccess). The relay pairs this connection with the worker's. Until the
+ * app's first frame arrives nobody may be on the other end yet (the worker can
+ * still be pulling an image), so the session is `waiting`, not `live`.
+ *
+ * Frames follow the function's schemas (see ./schema): a binary frame is one
+ * item of the binary live field, a text frame is a JSON object keyed by field
+ * name.
+ */
+import type { SocketAccess } from '../types';
+export type LiveState = 'connecting' | 'waiting' | 'live' | 'ended';
+export interface LiveEnd {
+    /** The WebSocket close code, or 1006 when the session ended without one. */
+    code: number;
+    reason: string;
+    /** The caller asked for it. */
+    byCaller: boolean;
+    /** The task ended before the app connected, so the session gave up waiting. */
+    taskEnded: boolean;
+}
+export interface LiveHandlers {
+    onState?: (state: LiveState, end?: LiveEnd) => void;
+    /** An item of the output's binary live field. */
+    onBinary?: (data: ArrayBuffer) => void;
+    /** A partial output object keyed by field name. */
+    onPatch?: (patch: Record<string, unknown>) => void;
+}
+/**
+ * Follows the task the socket belongs to. `done` settles when the task ends
+ * (rejected when it failed or was cancelled); `stop` ends the watch early and
+ * leaves `done` pending.
+ */
+export interface TaskWatch {
+    done: Promise<unknown>;
+    stop(): void;
+}
+/** The part of the WebSocket API the session uses; browsers, Node 22+ and `ws` all provide it. */
+export interface WebSocketLike {
+    binaryType: string;
+    readyState: number;
+    onopen: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    send(data: string | ArrayBuffer | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+}
+export type WebSocketConstructor = new (url: string) => WebSocketLike;
+export interface LiveSessionOptions {
+    access: SocketAccess;
+    handlers?: LiveHandlers;
+    /** Issues a fresh credential (POST /sockets/{id}/access) for a redial. */
+    renew?: () => Promise<SocketAccess>;
+    /**
+     * Ends the session when the task ends before the app connected. Without it
+     * a task that fails before its worker dials leaves the caller waiting on
+     * the relay until the pair timeout.
+     */
+    task?: TaskWatch;
+    /** The WebSocket to dial with; defaults to the runtime's global one. */
+    webSocket?: WebSocketConstructor;
+}
+export declare class LiveSession {
+    private ws;
+    private current;
+    private closedByCaller;
+    private redials;
+    private access;
+    private readonly handlers;
+    private readonly renew;
+    private readonly task;
+    private readonly WebSocket;
+    private resolveEnded;
+    /** Settles when the session has ended, however it ended. */
+    readonly ended: Promise<LiveEnd>;
+    constructor(options: LiveSessionOptions);
+    get state(): LiveState;
+    get isOpen(): boolean;
+    /** Dials the relay. The session reports its progress through onState. */
+    connect(): void;
+    private watched;
+    private watchTask;
+    private redial;
+    private setState;
+    private end;
+    private closeSocket;
+    /** One item of the input's binary live field. */
+    sendBinary(data: ArrayBuffer | ArrayBufferView): void;
+    /** A partial input object keyed by field name. */
+    sendPatch(patch: Record<string, unknown>): void;
+    /** Ends the stream; the function returns and the task completes. */
+    close(): void;
+}

package/dist/live/session.js

@@ -0,0 +1,139 @@
+const WS_OPEN = 1;
+// 1012: the relay is restarting and closed an end that still waited for its
+// peer. 1013: the peer did not come in time. Both mean "dial again" while the
+// task is alive, and neither means anything once frames have flowed.
+const REDIAL_CODES = new Set([1012, 1013]);
+const MAX_REDIALS = 5;
+function globalWebSocket() {
+    const ctor = globalThis.WebSocket;
+    if (!ctor) {
+        throw new Error('no WebSocket in this runtime: pass one (e.g. from the "ws" package) as webSocket');
+    }
+    return ctor;
+}
+export class LiveSession {
+    constructor(options) {
+        this.ws = null;
+        this.current = 'connecting';
+        this.closedByCaller = false;
+        this.redials = 0;
+        this.watched = false;
+        this.access = options.access;
+        this.handlers = options.handlers ?? {};
+        this.renew = options.renew;
+        this.task = options.task;
+        this.WebSocket = options.webSocket ?? globalWebSocket();
+        this.ended = new Promise((resolve) => {
+            this.resolveEnded = resolve;
+        });
+    }
+    get state() {
+        return this.current;
+    }
+    get isOpen() {
+        return this.ws?.readyState === WS_OPEN;
+    }
+    /** Dials the relay. The session reports its progress through onState. */
+    connect() {
+        this.setState('connecting');
+        this.watchTask();
+        // A browser cannot set headers on a WebSocket, so the credential rides in
+        // the query, as the relay documents.
+        const ws = new this.WebSocket(`${this.access.url}?access_token=${encodeURIComponent(this.access.token)}`);
+        ws.binaryType = 'arraybuffer';
+        this.ws = ws;
+        ws.onopen = () => this.setState('waiting');
+        ws.onmessage = (event) => {
+            if (this.current !== 'live') {
+                this.setState('live');
+                this.task?.stop(); // the app is there; the task's fate now shows on the socket
+            }
+            if (typeof event.data === 'string') {
+                let patch;
+                try {
+                    patch = JSON.parse(event.data);
+                }
+                catch {
+                    patch = { text: event.data };
+                }
+                if (patch && typeof patch === 'object' && !Array.isArray(patch)) {
+                    this.handlers.onPatch?.(patch);
+                }
+            }
+            else {
+                this.handlers.onBinary?.(event.data);
+            }
+        };
+        ws.onclose = (event) => {
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            const waiting = this.current !== 'live';
+            if (!this.closedByCaller && waiting && REDIAL_CODES.has(event.code) && this.redials < MAX_REDIALS) {
+                this.redials += 1;
+                void this.redial();
+                return;
+            }
+            this.end({ code: event.code, reason: event.reason, byCaller: this.closedByCaller, taskEnded: false });
+        };
+    }
+    watchTask() {
+        if (!this.task || this.watched)
+            return;
+        this.watched = true;
+        const endedBeforeLive = (reason) => {
+            if (this.current === 'ended' || this.current === 'live')
+                return;
+            this.closeSocket(1000, 'task ended');
+            this.end({ code: 1000, reason, byCaller: false, taskEnded: true });
+        };
+        this.task.done.then(() => endedBeforeLive('the task ended before the app connected'), (err) => endedBeforeLive(err instanceof Error ? err.message : String(err)));
+    }
+    async redial() {
+        try {
+            if (this.renew)
+                this.access = await this.renew();
+            if (this.current !== 'ended' && !this.closedByCaller)
+                this.connect();
+        }
+        catch (err) {
+            this.end({ code: 1006, reason: err instanceof Error ? err.message : 'could not redial', byCaller: false, taskEnded: false });
+        }
+    }
+    setState(state, end) {
+        this.current = state;
+        this.handlers.onState?.(state, end);
+    }
+    end(end) {
+        if (this.current === 'ended')
+            return;
+        this.task?.stop();
+        this.setState('ended', end);
+        this.resolveEnded(end);
+    }
+    closeSocket(code, reason) {
+        const ws = this.ws;
+        this.ws = null; // its onclose must not end the session a second time
+        ws?.close(code, reason);
+    }
+    /** One item of the input's binary live field. */
+    sendBinary(data) {
+        if (this.isOpen)
+            this.ws.send(data);
+    }
+    /** A partial input object keyed by field name. */
+    sendPatch(patch) {
+        if (this.isOpen)
+            this.ws.send(JSON.stringify(patch));
+    }
+    /** Ends the stream; the function returns and the task completes. */
+    close() {
+        this.closedByCaller = true;
+        if (this.ws) {
+            this.ws.close(1000, 'done'); // onclose ends the session
+        }
+        else {
+            this.end({ code: 1000, reason: 'done', byCaller: true, taskEnded: false });
+        }
+    }
+}

package/dist/types.d.ts

@@ -1618,6 +1618,11 @@ export interface ChatDTO extends BaseModelDTO, PermissionModelDTO {
     context?: {
         [key: string]: string;
     };
+    /**
+     * ChannelContext names the channel this chat came through (slack, a
+     * wearable's tag, ...). Unset for chats started in the app or the SDK.
+     */
+    channel_context?: ChannelContext;
     agent_id?: string;
     agent?: AgentDTO;
     agent_version_id?: string;
@@ -4704,6 +4709,7 @@ export declare const NotificationTypePaymentFailed: NotificationType;
 export declare const NotificationTypeUsageSummary: NotificationType;
 export declare const NotificationTypeSpendingLimit: NotificationType;
 export declare const NotificationTypeInvoice: NotificationType;
+export declare const NotificationTypeCreditNote: NotificationType;
 export declare const NotificationTypeSubscriptionCreated: NotificationType;
 export declare const NotificationTypeSubscriptionCredit: NotificationType;
 export declare const NotificationTypeSubscriptionCanceled: NotificationType;

package/dist/types.js

@@ -859,6 +859,7 @@ export const NotificationTypePaymentFailed = "payment_failed";
 export const NotificationTypeUsageSummary = "usage_summary";
 export const NotificationTypeSpendingLimit = "spending_limit";
 export const NotificationTypeInvoice = "invoice";
+export const NotificationTypeCreditNote = "credit_note";
 export const NotificationTypeSubscriptionCreated = "subscription_created";
 export const NotificationTypeSubscriptionCredit = "subscription_credit";
 export const NotificationTypeSubscriptionCanceled = "subscription_canceled";

package/package.json

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