@inferencesh/sdk 0.4.8 → 0.4.13

package/dist/client.d.ts

@@ -1,16 +1,13 @@
 import { ApiAppRunRequest, TaskDTO as Task, File, ChatDTO, ChatMessageDTO, AgentConfig } from './types';
 import { EventSource } from 'eventsource';
-/**
- * Ad-hoc agent configuration - extends AgentConfig with core_app_ref required
- * Uses Partial to make fields optional for ad-hoc usage
- */
-export type AdHocAgentConfig = Partial<AgentConfig> & {
-    /** Core LLM app ref: namespace/name@shortid (required for ad-hoc agents) */
-    core_app_ref: string;
-};
+/** Options for creating an agent */
+export interface AgentOptions {
+    /** Optional name for the adhoc agent (used for deduplication and display) */
+    name?: string;
+}
 export interface SendMessageOptions {
-    /** File attachments (Blob or base64 data URI) */
-    files?: (Blob | string)[];
+    /** File attachments - Blob (will be uploaded) or FileDTO (already uploaded, has uri) */
+    files?: (Blob | File)[];
     /** Callback for message updates */
     onMessage?: (message: ChatMessageDTO) => void;
     /** Callback for chat updates */
@@ -137,11 +134,17 @@ export declare class Inference {
      *   tools: [...]
      * })
      *
+     * // Ad-hoc agent with name for grouping
+     * const agent = client.agent(
+     *   { core_app_ref: 'infsh/claude-sonnet-4@xyz789' },
+     *   { name: 'My Assistant' }
+     * )
+     *
      * // Send messages
      * const response = await agent.sendMessage('Hello!')
      * ```
      */
-    agent(config: string | AdHocAgentConfig): Agent;
+    agent(config: string | AgentConfig, options?: AgentOptions): Agent;
 }
 /**
  * Agent for chat interactions
@@ -151,15 +154,19 @@ export declare class Inference {
 export declare class Agent {
     private readonly client;
     private readonly config;
+    private readonly agentName;
     private chatId;
     private stream;
     private dispatchedToolCalls;
     /** @internal */
-    constructor(client: Inference, config: string | AdHocAgentConfig);
+    constructor(client: Inference, config: string | AgentConfig, options?: AgentOptions);
     /** Get current chat ID */
     get currentChatId(): string | null;
     /** Send a message to the agent */
-    sendMessage(text: string, options?: SendMessageOptions): Promise<ChatMessageDTO>;
+    sendMessage(text: string, options?: SendMessageOptions): Promise<{
+        userMessage: ChatMessageDTO;
+        assistantMessage: ChatMessageDTO;
+    }>;
     /** Get chat by ID */
     getChat(chatId?: string): Promise<ChatDTO | null>;
     /** Stop the current chat generation */
@@ -180,6 +187,24 @@ export declare class Agent {
     disconnect(): void;
     /** Reset the agent (start fresh chat) */
     reset(): void;
+    /**
+     * Start streaming for the current chat.
+     * Call this after sendMessage to receive real-time updates.
+     * This is useful when you want to manage streaming separately from sendMessage.
+     *
+     * @example
+     * ```typescript
+     * // Send message without waiting for streaming
+     * const { userMessage, assistantMessage } = await agent.sendMessage('hello');
+     *
+     * // Start streaming separately
+     * agent.startStreaming({
+     *   onMessage: (msg) => console.log(msg.content),
+     *   onChat: (chat) => console.log(chat.status),
+     * });
+     * ```
+     */
+    startStreaming(options?: Omit<SendMessageOptions, 'files'>): void;
     /** Stream events until chat becomes idle */
     private streamUntilIdle;
 }

package/dist/client.js

@@ -109,14 +109,24 @@ class Inference {
     _createEventSource(endpoint) {
         const targetUrl = new URL(`${this.baseUrl}${endpoint}`);
         const isProxyMode = !!this.proxyUrl;
-        const fetchUrl = isProxyMode ? this.proxyUrl : targetUrl.toString();
+        // For proxy mode: Browser EventSource can't send custom headers,
+        // so append target URL as query param instead
+        let fetchUrl;
+        if (isProxyMode) {
+            const proxyUrlWithQuery = new URL(this.proxyUrl, window?.location?.origin || 'http://localhost');
+            proxyUrlWithQuery.searchParams.set('__inf_target', targetUrl.toString());
+            fetchUrl = proxyUrlWithQuery.toString();
+        }
+        else {
+            fetchUrl = targetUrl.toString();
+        }
         return new eventsource_1.EventSource(fetchUrl, {
             fetch: (input, init) => {
                 const headers = {
                     ...init?.headers,
                 };
                 if (isProxyMode) {
-                    // Proxy mode: send target URL as header
+                    // Proxy mode: also send target URL as header (for non-browser clients)
                     headers["x-inf-target-url"] = targetUrl.toString();
                 }
                 else {
@@ -246,10 +256,21 @@ class Inference {
                     }
                 },
                 onPartialData: (data, fields) => {
-                    // Call onPartialUpdate if provided
-                    if (onPartialUpdate) {
-                        const stripped = this._stripTask(data);
-                        onPartialUpdate(stripped, fields);
+                    // Strip and send partial update if callback provided
+                    const stripped = this._stripTask(data);
+                    onPartialUpdate?.(stripped, fields);
+                    // Also check for status changes in partial updates
+                    if (data.status === types_1.TaskStatusCompleted) {
+                        streamManager.stop();
+                        resolve(stripped);
+                    }
+                    else if (data.status === types_1.TaskStatusFailed) {
+                        streamManager.stop();
+                        reject(new Error(data.error || "task failed"));
+                    }
+                    else if (data.status === types_1.TaskStatusCancelled) {
+                        streamManager.stop();
+                        reject(new Error("task cancelled"));
                     }
                 },
                 onError: (error) => {
@@ -346,12 +367,18 @@ class Inference {
      *   tools: [...]
      * })
      *
+     * // Ad-hoc agent with name for grouping
+     * const agent = client.agent(
+     *   { core_app_ref: 'infsh/claude-sonnet-4@xyz789' },
+     *   { name: 'My Assistant' }
+     * )
+     *
      * // Send messages
      * const response = await agent.sendMessage('Hello!')
      * ```
      */
-    agent(config) {
-        return new Agent(this, config);
+    agent(config, options) {
+        return new Agent(this, config, options);
     }
 }
 exports.Inference = Inference;
@@ -365,12 +392,13 @@ exports.Inference = Inference;
  */
 class Agent {
     /** @internal */
-    constructor(client, config) {
+    constructor(client, config, options) {
         this.chatId = null;
         this.stream = null;
         this.dispatchedToolCalls = new Set();
         this.client = client;
         this.config = config;
+        this.agentName = options?.name;
     }
     /** Get current chat ID */
     get currentChatId() {
@@ -379,40 +407,69 @@ class Agent {
     /** Send a message to the agent */
     async sendMessage(text, options = {}) {
         const isTemplate = typeof this.config === 'string';
-        // Upload files if provided
+        const hasCallbacks = !!(options.onMessage || options.onChat || options.onToolCall);
+        // Process files - either already uploaded (FileDTO with uri) or needs upload (Blob)
         let imageUri;
         let fileUris;
         if (options.files && options.files.length > 0) {
-            const uploadedFiles = await Promise.all(options.files.map(f => this.client.uploadFile(f)));
-            const images = uploadedFiles.filter(f => f.content_type?.startsWith('image/'));
-            const others = uploadedFiles.filter(f => !f.content_type?.startsWith('image/'));
+            // Separate files that need uploading from those already uploaded
+            const toUpload = [];
+            const alreadyUploaded = [];
+            for (const file of options.files) {
+                // FileDTO has a uri property, Blob does not
+                if ('uri' in file && typeof file.uri === 'string') {
+                    alreadyUploaded.push(file);
+                }
+                else {
+                    toUpload.push(file);
+                }
+            }
+            // Upload any Blobs that need uploading
+            const uploadedFiles = toUpload.length > 0
+                ? await Promise.all(toUpload.map((blob) => this.client.uploadFile(blob)))
+                : [];
+            // Combine all files (already uploaded + newly uploaded)
+            const allFiles = [...alreadyUploaded, ...uploadedFiles];
+            // Separate images from other files
+            const images = allFiles.filter((f) => f.content_type?.startsWith('image/'));
+            const others = allFiles.filter((f) => !f.content_type?.startsWith('image/'));
             if (images.length > 0)
                 imageUri = images[0].uri;
             if (others.length > 0)
-                fileUris = others.map(f => f.uri);
+                fileUris = others.map((f) => f.uri);
         }
         const body = isTemplate
             ? {
                 chat_id: this.chatId,
-                agent_ref: this.config,
+                agent: this.config,
                 input: { text, image: imageUri, files: fileUris, role: 'user', context: [], system_prompt: '', context_size: 0 },
             }
             : {
                 chat_id: this.chatId,
                 agent_config: this.config,
+                agent_name: this.agentName,
                 input: { text, image: imageUri, files: fileUris, role: 'user', context: [], system_prompt: '', context_size: 0 },
             };
+        // For existing chats with callbacks: Start streaming BEFORE POST so we don't miss updates
+        let streamPromise = null;
+        if (this.chatId && hasCallbacks) {
+            streamPromise = this.streamUntilIdle(options);
+        }
+        // Make the POST request
         const response = await this.client._request('post', '/agents/run', { data: body });
-        // Start streaming for new chats or continue existing stream
+        // For new chats: Set chatId and start streaming immediately after POST
         const isNewChat = !this.chatId && response.assistant_message.chat_id;
         if (isNewChat) {
             this.chatId = response.assistant_message.chat_id;
+            if (hasCallbacks) {
+                streamPromise = this.streamUntilIdle(options);
+            }
         }
-        // Wait for streaming to complete if callbacks are provided
-        if (options.onMessage || options.onChat || options.onToolCall) {
-            await this.streamUntilIdle(options);
+        // Wait for streaming to complete
+        if (streamPromise) {
+            await streamPromise;
         }
-        return response.assistant_message;
+        return { userMessage: response.user_message, assistantMessage: response.assistant_message };
     }
     /** Get chat by ID */
     async getChat(chatId) {
@@ -450,6 +507,28 @@ class Agent {
         this.chatId = null;
         this.dispatchedToolCalls.clear();
     }
+    /**
+     * Start streaming for the current chat.
+     * Call this after sendMessage to receive real-time updates.
+     * This is useful when you want to manage streaming separately from sendMessage.
+     *
+     * @example
+     * ```typescript
+     * // Send message without waiting for streaming
+     * const { userMessage, assistantMessage } = await agent.sendMessage('hello');
+     *
+     * // Start streaming separately
+     * agent.startStreaming({
+     *   onMessage: (msg) => console.log(msg.content),
+     *   onChat: (chat) => console.log(chat.status),
+     * });
+     * ```
+     */
+    startStreaming(options = {}) {
+        if (!this.chatId)
+            return;
+        this.streamUntilIdle(options);
+    }
     /** Stream events until chat becomes idle */
     streamUntilIdle(options) {
         if (!this.chatId)
@@ -461,6 +540,7 @@ class Agent {
                 createEventSource: async () => this.client._createEventSource(`/chats/${this.chatId}/stream`),
                 autoReconnect: true,
             });
+            // Listen for Chat object updates (status changes)
             this.stream.addEventListener('chats', (chat) => {
                 options.onChat?.(chat);
                 // Resolve when chat becomes idle (generation complete)
@@ -468,6 +548,7 @@ class Agent {
                     resolve();
                 }
             });
+            // Listen for ChatMessage updates
             this.stream.addEventListener('chat_messages', (message) => {
                 options.onMessage?.(message);
                 if (message.tool_invocations && options.onToolCall) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Inference, inference, InferenceConfig, RunOptions, UploadFileOptions, Agent, AdHocAgentConfig, SendMessageOptions, } from './client';
+export { Inference, inference, InferenceConfig, RunOptions, UploadFileOptions, Agent, AgentOptions, SendMessageOptions, } from './client';
 export { tool, appTool, agentTool, webhookTool, internalTools, string, number, integer, boolean, enumOf, object, array, optional } from './tool-builder';
 export { StreamManager, PartialDataWrapper } from './stream';
 export { InferenceError, RequirementsNotMetException } from './errors';

package/dist/proxy/express.d.ts

@@ -1,37 +1,30 @@
 /**
- * Express.js proxy handler for Inference.sh API
+ * @inferencesh/sdk/proxy/express - Express.js Proxy Handler
  *
  * @example
  * ```typescript
  * import express from "express";
- * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
+ * import { createHandler, PROXY_ROUTE } from "@inferencesh/sdk/proxy/express";
  *
  * const app = express();
  * app.use(express.json());
- * app.all(inferenceProxy.route, inferenceProxy.handler);
+ * app.all(PROXY_ROUTE, createHandler());
  * ```
  */
 import type { RequestHandler } from "express";
-/**
- * The default proxy route path.
- */
+/** 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;
+}
 /**
- * Express middleware handler for the Inference.sh proxy.
+ * Creates an Express middleware handler for the Inference.sh proxy.
  *
  * Requires `express.json()` middleware to be applied before this handler.
- *
- * @example
- * ```typescript
- * import express from "express";
- * import cors from "cors";
- * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
- *
- * const app = express();
- * app.use(express.json());
- *
- * // If clients are external, enable CORS
- * app.all(inferenceProxy.route, cors(), inferenceProxy.handler);
- * ```
  */
-export declare const handler: RequestHandler;
+export declare function createHandler(options?: ExpressProxyOptions): RequestHandler;
+/** @deprecated Use createHandler() */
+export declare const handler: RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;

package/dist/proxy/express.js

@@ -1,84 +1,71 @@
 "use strict";
 /**
- * Express.js proxy handler for Inference.sh API
+ * @inferencesh/sdk/proxy/express - Express.js Proxy Handler
  *
  * @example
  * ```typescript
  * import express from "express";
- * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
+ * import { createHandler, PROXY_ROUTE } from "@inferencesh/sdk/proxy/express";
  *
  * const app = express();
  * app.use(express.json());
- * app.all(inferenceProxy.route, inferenceProxy.handler);
+ * app.all(PROXY_ROUTE, createHandler());
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handler = exports.route = void 0;
+exports.handler = exports.route = exports.PROXY_ROUTE = void 0;
+exports.createHandler = createHandler;
 const index_1 = require("./index");
+/** Default proxy route path */
+exports.PROXY_ROUTE = index_1.PROXY_PATH;
+/** @deprecated Use PROXY_ROUTE */
+exports.route = exports.PROXY_ROUTE;
 /**
- * The default proxy route path.
- */
-exports.route = index_1.DEFAULT_PROXY_ROUTE;
-/**
- * Express middleware handler for the Inference.sh proxy.
+ * Creates an Express middleware handler for the Inference.sh proxy.
  *
  * Requires `express.json()` middleware to be applied before this handler.
- *
- * @example
- * ```typescript
- * import express from "express";
- * import cors from "cors";
- * import * as inferenceProxy from "@inferencesh/sdk/proxy/express";
- *
- * const app = express();
- * app.use(express.json());
- *
- * // If clients are external, enable CORS
- * app.all(inferenceProxy.route, cors(), inferenceProxy.handler);
- * ```
  */
-const handler = async (req, res, _next) => {
-    const responseHeaders = {};
-    return (0, index_1.handleRequest)({
-        id: "express",
-        method: req.method,
-        getRequestBody: async () => JSON.stringify(req.body),
-        getHeaders: () => req.headers,
-        getHeader: (name) => req.headers[name],
-        sendHeader: (name, value) => {
-            responseHeaders[name] = value;
-            res.setHeader(name, value);
-        },
-        respondWith: (status, data) => {
-            return res.status(status).json(data);
-        },
-        sendResponse: async (response) => {
-            // Copy status
-            res.status(response.status);
-            // Handle streaming responses
-            const contentType = response.headers.get("content-type");
-            if (contentType?.includes("text/event-stream") ||
-                contentType?.includes("application/octet-stream")) {
-                // Stream the response
-                if (response.body) {
-                    const reader = response.body.getReader();
-                    while (true) {
-                        const { done, value } = await reader.read();
-                        if (done)
-                            break;
-                        res.write(value);
+function createHandler(options) {
+    return async (req, res, _next) => {
+        return (0, index_1.processProxyRequest)({
+            framework: "express",
+            method: req.method,
+            body: async () => JSON.stringify(req.body),
+            headers: () => req.headers,
+            header: (name) => req.headers[name],
+            query: (name) => {
+                const v = req.query[name];
+                return typeof v === "string" ? v : undefined;
+            },
+            setHeader: (name, value) => res.setHeader(name, value),
+            error: (status, data) => res.status(status).json(data),
+            respond: async (response) => {
+                res.status(response.status);
+                // Handle streaming responses
+                const contentType = response.headers.get("content-type");
+                if (contentType?.includes("text/event-stream") ||
+                    contentType?.includes("application/octet-stream")) {
+                    if (response.body) {
+                        const reader = response.body.getReader();
+                        while (true) {
+                            const { done, value } = await reader.read();
+                            if (done)
+                                break;
+                            res.write(value);
+                        }
                     }
+                    res.end();
+                    return res;
+                }
+                // Handle JSON responses
+                if (contentType?.includes("application/json")) {
+                    return res.json(await response.json());
                 }
-                res.end();
-                return res;
-            }
-            // Handle JSON responses
-            if (contentType?.includes("application/json")) {
-                return res.json(await response.json());
-            }
-            // Handle text responses
-            return res.send(await response.text());
-        },
-    });
-};
-exports.handler = handler;
+                // Handle text responses
+                return res.send(await response.text());
+            },
+        }, options);
+    };
+}
+/** @deprecated Use createHandler() */
+exports.handler = createHandler();

package/dist/proxy/hono.d.ts

@@ -1,59 +1,27 @@
 /**
- * Hono proxy handler for Inference.sh API
+ * @inferencesh/sdk/proxy/hono - Hono Framework Proxy Handler
  *
- * Lightweight handler for Hono framework, ideal for edge/serverless deployments.
+ * Lightweight handler for Hono, ideal for edge/serverless deployments.
  *
  * @example
  * ```typescript
  * import { Hono } from "hono";
- * import { createRouteHandler } from "@inferencesh/sdk/proxy/hono";
+ * import { createHandler } from "@inferencesh/sdk/proxy/hono";
  *
  * const app = new Hono();
- * const proxyHandler = createRouteHandler();
- *
- * app.all("/api/inference/proxy", proxyHandler);
+ * app.all("/api/inference/proxy", createHandler());
  * ```
  */
 import type { Context } from "hono";
 export interface HonoProxyOptions {
-    /**
-     * Custom function to resolve the API key.
-     * Defaults to reading from INFERENCE_API_KEY environment variable.
-     */
+    /** Custom function to resolve the API key */
     resolveApiKey?: () => Promise<string | undefined>;
 }
-type RouteHandler = (context: Context) => Promise<Response>;
+type HonoHandler = (context: Context) => Promise<Response>;
 /**
- * Creates a Hono route handler that proxies requests to the Inference.sh API.
- *
- * This is a drop-in handler for Hono applications that keeps API keys safe
- * by running on your server.
- *
- * @param options - Proxy options
- * @returns A Hono route handler function
- *
- * @example
- * ```typescript
- * import { Hono } from "hono";
- * import { createRouteHandler } from "@inferencesh/sdk/proxy/hono";
- *
- * const app = new Hono();
- * const proxyHandler = createRouteHandler();
- *
- * app.all("/api/inference/proxy", proxyHandler);
- *
- * export default app;
- * ```
- *
- * @example Custom API key resolver
- * ```typescript
- * const proxyHandler = createRouteHandler({
- *   resolveApiKey: async () => {
- *     // Load from a secrets manager
- *     return await getSecretFromVault("INFERENCE_API_KEY");
- *   },
- * });
- * ```
+ * Creates a Hono route handler for the Inference.sh proxy.
  */
-export declare function createRouteHandler({ resolveApiKey, }?: HonoProxyOptions): RouteHandler;
+export declare function createHandler({ resolveApiKey, }?: HonoProxyOptions): HonoHandler;
+/** @deprecated Use createHandler */
+export declare const createRouteHandler: typeof createHandler;
 export {};