@inferencesh/sdk 0.6.51 → 0.6.53

package/dist/index.d.ts

@@ -5,9 +5,10 @@ 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 } from './api/agents';
+export { AgentsAPI, Agent, type AgentOptions, type SendMessageOptions, type AgentRunOptions, type AgentDelta } from './api/agents';
 export { SessionsAPI } from './api/sessions';
 export { AppsAPI } from './api/apps';
 export { ChatsAPI } from './api/chats';
@@ -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';
@@ -32,8 +37,12 @@ export { parseStatus, isTerminalStatus, isChatBusy, pendingApprovals } from './u
 export type { PendingApproval } from './utils';
 export * from './types';
 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';
@@ -107,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?: {
@@ -119,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 });
+        }
+    }
+}