@inferencesh/sdk 0.21.0 → 0.22.0

package/dist/http/loopback.js

@@ -0,0 +1,18 @@
+/**
+ * Loopback hosts, where plain http never leaves the machine (local dev):
+ * `localhost`, any `*.localhost`, `[::1]` and 127.0.0.0/8. This is the one
+ * copy of the rule; the proxy, the app and common-js all ask it.
+ */
+export function isLoopbackHost(hostname) {
+    const h = hostname.toLowerCase();
+    return h === 'localhost'
+        || h.endsWith('.localhost')
+        || h === '[::1]'
+        || /^127(\.\d{1,3}){3}$/.test(h);
+}
+/** Whether `url` is https, or plain http to a loopback host. */
+export function isHttpsOrLoopback(url) {
+    if (url.protocol === 'https:')
+        return true;
+    return url.protocol === 'http:' && isLoopbackHost(url.hostname);
+}

package/dist/http/stream-until-terminal.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Follow a resource's NDJSON stream until the resource reaches a terminal
+ * state.
+ *
+ * StreamableManager never reconnects, and a stream can close cleanly before
+ * the resource is done (load balancer idle timeout, API deploy). A wait built
+ * on it must not hang then. This helper owns that contract for every
+ * "stream until done" wait: when the stream ends early it fetches the
+ * resource once (`reconcile`) and settles with what that shows, or rejects
+ * when the resource is still not terminal. sdk-py's `wait_for_completion`
+ * does the same final GET.
+ */
+import { type StreamableManagerOptions, type StreamRequest } from './streamable';
+/** Settles a stream-until-terminal wait. Calls after the first are ignored. */
+export interface TerminalSettler<R> {
+    resolve(value: R): void;
+    reject(error: Error): void;
+}
+/** The stream to follow and how to tell when its resource is done. */
+export type StreamUntilTerminalSpec<T> = Pick<StreamableManagerOptions<T>, 'body' | 'onData' | 'onPartialData' | 'onStart' | 'onDelta'> & {
+    /** Sends the stream request, e.g. `(init) => http.fetch(endpoint, init)`. */
+    request: StreamRequest;
+    /** Typed event listeners ({"event": name, "data": ...} messages). */
+    events?: Record<string, (data: any, fields?: string[]) => void>;
+    /**
+     * Called once when the stream ends cleanly before the wait settled. Fetch
+     * the resource and settle if it is terminal; returning without settling
+     * rejects the wait with `closedMessage`.
+     */
+    reconcile: () => Promise<void>;
+    /** Rejection message when the stream closed and the resource is still not terminal. */
+    closedMessage: string;
+    /**
+     * Called when the wait ends because `stop()` was called. Without it `done`
+     * stays pending.
+     */
+    onStopped?: () => void;
+    /**
+     * Keep the stream open after the wait settled so its listeners go on
+     * seeing updates (default false: settling stops the stream).
+     */
+    keepOpen?: boolean;
+};
+export interface StreamUntilTerminal<R> {
+    /** Settles when the resource is terminal, the stream fails, or it closed early and the resource is not terminal. */
+    done: Promise<R>;
+    /** Ends the stream on purpose; see `onStopped`. */
+    stop(): void;
+}
+/**
+ * `build` receives the settler and returns the stream spec; its handlers call
+ * `settle.resolve`/`settle.reject` once the resource is terminal. Settling
+ * stops the stream unless the spec says `keepOpen`.
+ */
+export declare function streamUntilTerminal<T, R>(build: (settle: TerminalSettler<R>) => StreamUntilTerminalSpec<T>): StreamUntilTerminal<R>;

package/dist/http/stream-until-terminal.js

@@ -0,0 +1,88 @@
+/**
+ * Follow a resource's NDJSON stream until the resource reaches a terminal
+ * state.
+ *
+ * StreamableManager never reconnects, and a stream can close cleanly before
+ * the resource is done (load balancer idle timeout, API deploy). A wait built
+ * on it must not hang then. This helper owns that contract for every
+ * "stream until done" wait: when the stream ends early it fetches the
+ * resource once (`reconcile`) and settles with what that shows, or rejects
+ * when the resource is still not terminal. sdk-py's `wait_for_completion`
+ * does the same final GET.
+ */
+import { StreamableManager } from './streamable';
+/**
+ * `build` receives the settler and returns the stream spec; its handlers call
+ * `settle.resolve`/`settle.reject` once the resource is terminal. Settling
+ * stops the stream unless the spec says `keepOpen`.
+ */
+export function streamUntilTerminal(build) {
+    let settled = false;
+    let stopped = false;
+    let manager;
+    const done = new Promise((resolve, reject) => {
+        const settle = {
+            resolve: (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (!keepOpen)
+                    manager?.stop();
+                resolve(value);
+            },
+            reject: (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (!keepOpen)
+                    manager?.stop();
+                reject(error);
+            },
+        };
+        const { events, reconcile, closedMessage, onStopped, keepOpen, ...managerOptions } = build(settle);
+        let streamError = null;
+        manager = new StreamableManager({
+            ...managerOptions,
+            onError: (error) => {
+                streamError = error;
+            },
+            onEnd: () => {
+                if (settled)
+                    return;
+                if (stopped) {
+                    onStopped?.();
+                    return;
+                }
+                if (streamError) {
+                    settle.reject(streamError);
+                    return;
+                }
+                // Closed cleanly before the resource was terminal: ask the API once.
+                const closed = (cause) => {
+                    if (stopped && !settled) {
+                        onStopped?.();
+                        return;
+                    }
+                    const error = new Error(closedMessage);
+                    if (cause !== undefined)
+                        error.cause = cause;
+                    settle.reject(error);
+                };
+                reconcile().then(() => closed(), closed);
+            },
+        });
+        for (const [name, listener] of Object.entries(events ?? {})) {
+            manager.addEventListener(name, listener);
+        }
+    });
+    manager.start();
+    return {
+        done,
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            manager.stop();
+        },
+    };
+}

package/dist/http/stream.d.ts

@@ -24,6 +24,7 @@ export declare class StreamManager<T> {
     private initialConnectionAttempts;
     private consecutiveErrors;
     private isConnected;
+    private hasEverConnected;
     private isStopped;
     private eventListeners;
     constructor(options: StreamManagerOptions<T>);

package/dist/http/stream.js

@@ -17,6 +17,7 @@ export class StreamManager {
         this.initialConnectionAttempts = 0;
         this.consecutiveErrors = 0;
         this.isConnected = false;
+        this.hasEverConnected = false;
         this.isStopped = false;
         this.eventListeners = new Map();
         this.options = {
@@ -53,6 +54,8 @@ export class StreamManager {
         source.addEventListener(eventName, (e) => {
             if (this.isStopped)
                 return;
+            // A delivered event proves the connection works, same as onmessage.
+            this.consecutiveErrors = 0;
             try {
                 const parsed = JSON.parse(e.data);
                 const listeners = this.eventListeners.get(eventName);
@@ -114,15 +117,15 @@ export class StreamManager {
         if (!this.options.autoReconnect || this.isStopped)
             return false;
         const maxReconnects = this.options.maxReconnects ?? 5;
-        if (!this.isConnected && this.initialConnectionAttempts >= maxReconnects) {
+        if (!this.hasEverConnected && this.initialConnectionAttempts >= maxReconnects) {
             return false;
         }
-        if (this.isConnected && this.consecutiveErrors >= maxReconnects) {
+        if (this.hasEverConnected && this.consecutiveErrors >= maxReconnects) {
             return false;
         }
         this.reconnectTimeout = setTimeout(() => {
             if (!this.isStopped) {
-                if (!this.isConnected) {
+                if (!this.hasEverConnected) {
                     this.initialConnectionAttempts++;
                 }
                 this.consecutiveErrors++;
@@ -142,6 +145,7 @@ export class StreamManager {
                 return;
             this.eventSource = source;
             this.isConnected = true;
+            this.hasEverConnected = true;
             this.options.onStart?.();
             // Set up typed event listeners (for events with `event: eventName` header)
             this.setupAllEventListeners(source);

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import type { Response } from './http/response';
 export { StreamManager, type StreamManagerOptions, type PartialDataWrapper } from './http/stream';
 export { StreamableManager, type StreamableManagerOptions, type StreamableSource, type StreamRequest, type StreamRequestInit, type StreamableMessage, streamable, streamableRaw } from './http/streamable';
 export { PollManager, type PollManagerOptions } from './http/poll';
+export { isLoopbackHost, isHttpsOrLoopback } from './http/loopback';
 export { InferenceError, RequirementsNotMetException, SessionError, SessionNotFoundError, SessionExpiredError, SessionEndedError, WorkerLostError, isRequirementsNotMetException, isInferenceError, isSessionError, } from './http/errors';
 export { TasksAPI, type RunOptions, type WatchOptions, type TaskWatch } from './api/tasks';
 export { SocketsAPI, type SocketTarget, type OpenSocketOptions } from './api/sockets';
@@ -17,6 +18,7 @@ export { FlowRunsAPI } from './api/flow-runs';
 export { EnginesAPI } from './api/engines';
 export { KnowledgeAPI, SkillsAPI } from './api/knowledge';
 export { ArtifactsAPI } from './api/artifacts';
+export type { AgentUpdateBody, AppPatchBody, AppUpdateBody, ChatUpdateBody, EngineUpdateBody, FlowUpdateBody, FlowPatchBody, FlowViewportBody, ProjectWriteBody, KnowledgeUpdateBody, TeamUpdateBody, MCPServerUpdateBody, } from './api/write-bodies';
 export { TeamsAPI } from './api/teams';
 export { SecretsAPI } from './api/secrets';
 export { ApiKeysAPI } from './api/api-keys';

package/dist/index.js

@@ -3,6 +3,7 @@ export { HttpClient, createHttpClient } from './http/client';
 export { StreamManager } from './http/stream';
 export { StreamableManager, streamable, streamableRaw } from './http/streamable';
 export { PollManager } from './http/poll';
+export { isLoopbackHost, isHttpsOrLoopback } from './http/loopback';
 export { InferenceError, RequirementsNotMetException, SessionError, SessionNotFoundError, SessionExpiredError, SessionEndedError, WorkerLostError, 
 // Type guards (use these instead of instanceof for reliability)
 isRequirementsNotMetException, isInferenceError, isSessionError, } from './http/errors';

package/dist/proxy/endpoints.json

@@ -0,0 +1,156 @@
+{
+    "$comment": "Generated by `make proxy-endpoints` from the route table (internal/api/proxy_endpoints_test.go). Do not edit.",
+    "preset": "run-only",
+    "endpoints": [
+        {
+            "method": "POST",
+            "path": "/apps/run",
+            "purpose": "run an app",
+            "scopes": [
+                "apps:execute",
+                "apps:read",
+                "conversations:read"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/files",
+            "purpose": "upload a file input of a run or message",
+            "scopes": [
+                "files:write"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/tasks/{id}",
+            "purpose": "read a task",
+            "scopes": [
+                "apps:read"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/tasks/{id}/status",
+            "purpose": "poll a task",
+            "scopes": [
+                "apps:read"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/tasks/{id}/stream",
+            "purpose": "stream a task",
+            "scopes": [
+                "apps:read",
+                "conversations:read",
+                "flows:read"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/tasks/{id}/cancel",
+            "purpose": "cancel a task",
+            "scopes": [
+                "apps:execute"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/agents/run",
+            "purpose": "send a message to an agent",
+            "scopes": [
+                "agents:execute",
+                "conversations:read"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/chats",
+            "purpose": "start a chat with an agent",
+            "scopes": [
+                "conversations:write"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/chats/{id}/messages",
+            "purpose": "send a message in a chat",
+            "scopes": [
+                "agents:execute"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/chats/{id}/agent",
+            "purpose": "hand a chat to another agent",
+            "scopes": [
+                "conversations:write"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/agents/{namespace}/{name}",
+            "purpose": "read an agent's info",
+            "scopes": [
+                "agents:read"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/chats/{id}",
+            "purpose": "read a chat",
+            "scopes": [
+                "conversations:read"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/chats/{id}/status",
+            "purpose": "poll a chat",
+            "scopes": [
+                "conversations:read"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/chats/{id}/messages",
+            "purpose": "read a chat's messages",
+            "scopes": [
+                "conversations:read"
+            ]
+        },
+        {
+            "method": "GET",
+            "path": "/chats/{id}/stream",
+            "purpose": "stream a chat",
+            "scopes": [
+                "conversations:read"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/chats/{id}/stop",
+            "purpose": "stop a chat",
+            "scopes": [
+                "conversations:write"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/chats/messages/{messageId}/cancel",
+            "purpose": "cancel a message",
+            "scopes": [
+                "conversations:read",
+                "conversations:write"
+            ]
+        },
+        {
+            "method": "POST",
+            "path": "/tools/{toolId}",
+            "purpose": "answer a client tool call",
+            "scopes": [
+                "conversations:write"
+            ]
+        }
+    ]
+}

package/dist/proxy/express.d.ts

@@ -8,18 +8,17 @@
  *
  * const app = express();
  * app.use(express.json());
- * app.all(PROXY_ROUTE, createHandler());
+ * app.all(PROXY_ROUTE, createHandler({ allowedEndpoints: ["my-team/*"] }));
  * ```
  */
-import type { RequestHandler } from "express";
+import type { Request, RequestHandler } from "express";
+import { type ProxyOptions } from "./index";
 /** Default proxy route path */
 export declare const PROXY_ROUTE = "/api/inference/proxy";
 /** @deprecated Use PROXY_ROUTE */
 export declare const route = "/api/inference/proxy";
-export interface ExpressProxyOptions {
-    /** Custom API key (overrides INFERENCE_API_KEY env var) */
-    apiKey?: string;
-}
+/** Proxy options; `isAuthenticated` receives the Express request. */
+export type ExpressProxyOptions = ProxyOptions<Request>;
 /**
  * Creates an Express middleware handler for the Inference.sh proxy.
  *

package/dist/proxy/express.js

@@ -8,7 +8,7 @@
  *
  * const app = express();
  * app.use(express.json());
- * app.all(PROXY_ROUTE, createHandler());
+ * app.all(PROXY_ROUTE, createHandler({ allowedEndpoints: ["my-team/*"] }));
  * ```
  */
 import { PROXY_PATH, processProxyRequest, } from "./index";
@@ -23,8 +23,19 @@ export const route = PROXY_ROUTE;
  */
 export function createHandler(options) {
     return async (req, res, _next) => {
+        // The client hung up before the response finished: stop the upstream
+        // request too. Chat and task streams never end on their own, so
+        // without this the proxy keeps reading them for nobody and the open
+        // upstream connection keeps the server process alive.
+        const upstream = new AbortController();
+        res.on("close", () => {
+            if (!res.writableFinished)
+                upstream.abort();
+        });
         return processProxyRequest({
             framework: "express",
+            signal: upstream.signal,
+            request: req,
             method: req.method,
             body: async () => JSON.stringify(req.body),
             headers: () => req.headers,
@@ -61,7 +72,12 @@ export function createHandler(options) {
                 // Handle text responses
                 return res.send(await response.text());
             },
-        }, options);
+        }, options).catch((error) => {
+            // Aborted because the client left; there is nobody to answer.
+            if (upstream.signal.aborted)
+                return res;
+            throw error;
+        });
     };
 }
 /** @deprecated Use createHandler() */

package/dist/proxy/hono.d.ts

@@ -9,11 +9,13 @@
  * import { createHandler } from "@inferencesh/sdk/proxy/hono";
  *
  * const app = new Hono();
- * app.all("/api/inference/proxy", createHandler());
+ * app.all("/api/inference/proxy", createHandler({ allowedEndpoints: ["my-team/*"] }));
  * ```
  */
 import type { Context } from "hono";
-export interface HonoProxyOptions {
+import { type ProxyOptions } from "./index";
+/** Proxy options; `isAuthenticated` receives the Context. */
+export interface HonoProxyOptions extends ProxyOptions<Context> {
     /** Custom function to resolve the API key */
     resolveApiKey?: () => Promise<string | undefined>;
 }
@@ -21,7 +23,7 @@ type HonoHandler = (context: Context) => Promise<Response>;
 /**
  * Creates a Hono route handler for the Inference.sh proxy.
  */
-export declare function createHandler({ resolveApiKey, }?: HonoProxyOptions): HonoHandler;
+export declare function createHandler({ resolveApiKey, ...options }?: HonoProxyOptions): HonoHandler;
 /** @deprecated Use createHandler */
 export declare const createRouteHandler: typeof createHandler;
 export {};

package/dist/proxy/hono.js

@@ -9,19 +9,20 @@
  * import { createHandler } from "@inferencesh/sdk/proxy/hono";
  *
  * const app = new Hono();
- * app.all("/api/inference/proxy", createHandler());
+ * app.all("/api/inference/proxy", createHandler({ allowedEndpoints: ["my-team/*"] }));
  * ```
  */
 import { processProxyRequest, getEnvApiKey, passthrough, headersToRecord, } from "./index";
 /**
  * Creates a Hono route handler for the Inference.sh proxy.
  */
-export function createHandler({ resolveApiKey = getEnvApiKey, } = {}) {
+export function createHandler({ resolveApiKey = getEnvApiKey, ...options } = {}) {
     return async (context) => {
         const responseHeaders = new Headers();
         const url = new URL(context.req.url);
         return processProxyRequest({
             framework: "hono",
+            request: context,
             method: context.req.method,
             body: async () => {
                 try {
@@ -44,7 +45,7 @@ export function createHandler({ resolveApiKey = getEnvApiKey, } = {}) {
             }),
             respond: passthrough,
             apiKey: resolveApiKey,
-        });
+        }, options);
     };
 }
 /** @deprecated Use createHandler */