@inferencesh/sdk 0.1.3 → 0.2.1

package/dist/client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.inference = exports.Inference = void 0;
+exports.Agent = exports.Inference = void 0;
+exports.inference = inference;
 const types_1 = require("./types");
 const stream_1 = require("./stream");
 const eventsource_1 = require("eventsource");
@@ -22,7 +23,8 @@ class Inference {
         this.apiKey = config.apiKey;
         this.baseUrl = config.baseUrl || "https://api.inference.sh";
     }
-    async request(method, endpoint, options = {}) {
+    /** @internal */
+    async _request(method, endpoint, options = {}) {
         const url = new URL(`${this.baseUrl}${endpoint}`);
         if (options.params) {
             Object.entries(options.params).forEach(([key, value]) => {
@@ -84,7 +86,8 @@ class Inference {
         }
         return apiResponse.data;
     }
-    createEventSource(endpoint) {
+    /** @internal */
+    _createEventSource(endpoint) {
         const url = new URL(`${this.baseUrl}${endpoint}`);
         return new eventsource_1.EventSource(url.toString(), {
             fetch: (input, init) => fetch(input, {
@@ -147,26 +150,37 @@ class Inference {
      * @param options - Run options for waiting, updates, and reconnection
      * @returns The completed task result
      *
+     * App reference format: `namespace/name@shortid` (version is required)
+     *
+     * The short ID ensures your code always runs the same version,
+     * protecting against breaking changes from app updates.
+     *
      * @example
      * ```typescript
-     * // Simple usage - wait for result
-     * const result = await client.run({ app: 'my-app', input: { prompt: 'hello' } });
+     * // Run a specific version (required)
+     * const result = await client.run({
+     *   app: 'okaris/flux@abc1',  // version @abc1 is pinned
+     *   input: { prompt: 'hello' }
+     * });
      *
      * // With status updates
      * const result = await client.run(
-     *   { app: 'my-app', input: { prompt: 'hello' } },
+     *   { app: 'okaris/flux@abc1', input: { prompt: 'hello' } },
      *   { onUpdate: (update) => console.log(update.status) }
      * );
      *
      * // Fire and forget
-     * const task = await client.run({ app: 'my-app', input: {} }, { wait: false });
+     * const task = await client.run(
+     *   { app: 'okaris/flux@abc1', input: {} },
+     *   { wait: false }
+     * );
      * ```
      */
     async run(params, options = {}) {
         const { onUpdate, onPartialUpdate, wait = true, autoReconnect = true, maxReconnects = 5, reconnectDelayMs = 1000, } = options;
         // Process input data and upload any files
         const processedInput = await this.processInputData(params.input);
-        const task = await this.request("post", "/run", {
+        const task = await this._request("post", "/apps/run", {
             data: {
                 ...params,
                 input: processedInput
@@ -179,7 +193,7 @@ class Inference {
         // Wait for completion with optional updates
         return new Promise((resolve, reject) => {
             const streamManager = new stream_1.StreamManager({
-                createEventSource: async () => this.createEventSource(`/tasks/${task.id}/stream`),
+                createEventSource: async () => this._createEventSource(`/tasks/${task.id}/stream`),
                 autoReconnect,
                 maxReconnects,
                 reconnectDelayMs,
@@ -224,7 +238,7 @@ class Inference {
             path: options.path,
             size: data instanceof Blob ? data.size : undefined,
         };
-        const response = await this.request("post", "/files", {
+        const response = await this._request("post", "/files", {
             data: {
                 files: [fileRequest]
             }
@@ -281,11 +295,178 @@ class Inference {
        * @param taskId - The ID of the task to cancel
        */
     async cancel(taskId) {
-        return this.request("post", `/tasks/${taskId}/cancel`);
+        return this._request("post", `/tasks/${taskId}/cancel`);
+    }
+    /**
+     * Create an agent for chat interactions
+     *
+     * @param config - Either a template reference string (namespace/name@version) or ad-hoc config
+     * @returns An Agent instance for chat operations
+     *
+     * @example
+     * ```typescript
+     * // Template agent
+     * const agent = client.agent('okaris/assistant@abc123')
+     *
+     * // Ad-hoc agent
+     * const agent = client.agent({
+     *   core_app_ref: 'infsh/claude-sonnet-4@xyz789',
+     *   system_prompt: 'You are a helpful assistant',
+     *   tools: [...]
+     * })
+     *
+     * // Send messages
+     * const response = await agent.sendMessage('Hello!')
+     * ```
+     */
+    agent(config) {
+        return new Agent(this, config);
     }
 }
 exports.Inference = Inference;
+// =============================================================================
+// Agent Class
+// =============================================================================
 /**
- * @deprecated Use `Inference` instead. Will be removed in v1.0.0
+ * Agent for chat interactions
+ *
+ * Created via `client.agent()` - do not instantiate directly.
  */
-exports.inference = Inference;
+class Agent {
+    /** @internal */
+    constructor(client, config) {
+        this.chatId = null;
+        this.stream = null;
+        this.dispatchedToolCalls = new Set();
+        this.client = client;
+        this.config = config;
+    }
+    /** Get current chat ID */
+    get currentChatId() {
+        return this.chatId;
+    }
+    /** Send a message to the agent */
+    async sendMessage(text, options = {}) {
+        const isTemplate = typeof this.config === 'string';
+        // Upload files if provided
+        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/'));
+            if (images.length > 0)
+                imageUri = images[0].uri;
+            if (others.length > 0)
+                fileUris = others.map(f => f.uri);
+        }
+        const body = isTemplate
+            ? {
+                chat_id: this.chatId,
+                agent_ref: this.config,
+                input: { text, image: imageUri, files: fileUris, role: 'user', context: [], system_prompt: '', context_size: 0 },
+            }
+            : {
+                chat_id: this.chatId,
+                agent_config: this.config,
+                input: { text, image: imageUri, files: fileUris, role: 'user', context: [], system_prompt: '', context_size: 0 },
+            };
+        const response = await this.client._request('post', '/agents/run', { data: body });
+        // Start streaming for new chats or continue existing stream
+        const isNewChat = !this.chatId && response.assistant_message.chat_id;
+        if (isNewChat) {
+            this.chatId = response.assistant_message.chat_id;
+        }
+        // Wait for streaming to complete if callbacks are provided
+        if (options.onMessage || options.onChat || options.onToolCall) {
+            await this.streamUntilIdle(options);
+        }
+        return response.assistant_message;
+    }
+    /** Get chat by ID */
+    async getChat(chatId) {
+        const id = chatId || this.chatId;
+        if (!id)
+            return null;
+        return this.client._request('get', `/chats/${id}`);
+    }
+    /** Stop the current chat generation */
+    async stopChat() {
+        if (!this.chatId)
+            return;
+        await this.client._request('post', `/chats/${this.chatId}/stop`);
+    }
+    /**
+     * Submit a tool result
+     * @param toolInvocationId - The tool invocation ID
+     * @param resultOrAction - Either a raw result string, or an object with action and optional form_data (will be JSON-serialized)
+     */
+    async submitToolResult(toolInvocationId, resultOrAction) {
+        // Serialize widget actions to JSON string
+        const result = typeof resultOrAction === 'string'
+            ? resultOrAction
+            : JSON.stringify(resultOrAction);
+        await this.client._request('post', `/tools/${toolInvocationId}`, { data: { result } });
+    }
+    /** Stop streaming and cleanup */
+    disconnect() {
+        this.stream?.stop();
+        this.stream = null;
+    }
+    /** Reset the agent (start fresh chat) */
+    reset() {
+        this.disconnect();
+        this.chatId = null;
+        this.dispatchedToolCalls.clear();
+    }
+    /** Stream events until chat becomes idle */
+    streamUntilIdle(options) {
+        if (!this.chatId)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            // Stop any existing stream
+            this.stream?.stop();
+            this.stream = new stream_1.StreamManager({
+                createEventSource: async () => this.client._createEventSource(`/chats/${this.chatId}/stream`),
+                autoReconnect: true,
+            });
+            this.stream.addEventListener('chats', (chat) => {
+                options.onChat?.(chat);
+                // Resolve when chat becomes idle (generation complete)
+                if (chat.status === 'idle') {
+                    resolve();
+                }
+            });
+            this.stream.addEventListener('chat_messages', (message) => {
+                options.onMessage?.(message);
+                if (message.tool_invocations && options.onToolCall) {
+                    for (const inv of message.tool_invocations) {
+                        // Skip if already dispatched
+                        if (this.dispatchedToolCalls.has(inv.id))
+                            continue;
+                        if (inv.type === types_1.ToolTypeClient && inv.status === types_1.ToolInvocationStatusAwaitingInput) {
+                            this.dispatchedToolCalls.add(inv.id);
+                            options.onToolCall({
+                                id: inv.id,
+                                name: inv.function?.name || '',
+                                args: inv.function?.arguments || {},
+                            });
+                        }
+                    }
+                }
+            });
+            this.stream.connect();
+        });
+    }
+}
+exports.Agent = Agent;
+/**
+ * Factory function for creating an Inference client (lowercase for branding)
+ * @example
+ * ```typescript
+ * const client = inference({ apiKey: 'your-api-key' });
+ * ```
+ */
+function inference(config) {
+    return new Inference(config);
+}

package/dist/client.test.js

@@ -155,12 +155,12 @@ describe('Inference', () => {
             expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('/tasks/task-123/cancel'), expect.objectContaining({ method: 'POST' }));
         });
     });
-    describe('backward compatibility', () => {
-        it('should export lowercase inference as alias', () => {
-            expect(client_1.inference).toBe(client_1.Inference);
+    describe('lowercase factory', () => {
+        it('should export lowercase inference factory', () => {
+            expect(typeof client_1.inference).toBe('function');
         });
-        it('should work with lowercase inference', () => {
-            const client = new client_1.inference({ apiKey: 'test-api-key' });
+        it('should work with lowercase inference factory', () => {
+            const client = (0, client_1.inference)({ apiKey: 'test-api-key' });
             expect(client).toBeInstanceOf(client_1.Inference);
         });
     });

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-export { Inference, inference, InferenceConfig, RunOptions, UploadFileOptions } from './client';
+export { Inference, inference, InferenceConfig, RunOptions, UploadFileOptions, Agent, AdHocAgentConfig, SendMessageOptions, } from './client';
+export { AgentConfig, AdHocAgentOptions, TemplateAgentOptions, AgentOptions, } from './agent';
+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';
 export * from './types';

package/dist/index.js

@@ -14,11 +14,27 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RequirementsNotMetException = exports.InferenceError = exports.StreamManager = exports.inference = exports.Inference = void 0;
-// Main client export
+exports.RequirementsNotMetException = exports.InferenceError = exports.StreamManager = exports.optional = exports.array = exports.object = exports.enumOf = exports.boolean = exports.integer = exports.number = exports.string = exports.internalTools = exports.webhookTool = exports.agentTool = exports.appTool = exports.tool = exports.Agent = exports.inference = exports.Inference = void 0;
+// Main client export (includes Agent)
 var client_1 = require("./client");
 Object.defineProperty(exports, "Inference", { enumerable: true, get: function () { return client_1.Inference; } });
 Object.defineProperty(exports, "inference", { enumerable: true, get: function () { return client_1.inference; } });
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return client_1.Agent; } });
+// Tool Builder (fluent API)
+var tool_builder_1 = require("./tool-builder");
+Object.defineProperty(exports, "tool", { enumerable: true, get: function () { return tool_builder_1.tool; } });
+Object.defineProperty(exports, "appTool", { enumerable: true, get: function () { return tool_builder_1.appTool; } });
+Object.defineProperty(exports, "agentTool", { enumerable: true, get: function () { return tool_builder_1.agentTool; } });
+Object.defineProperty(exports, "webhookTool", { enumerable: true, get: function () { return tool_builder_1.webhookTool; } });
+Object.defineProperty(exports, "internalTools", { enumerable: true, get: function () { return tool_builder_1.internalTools; } });
+Object.defineProperty(exports, "string", { enumerable: true, get: function () { return tool_builder_1.string; } });
+Object.defineProperty(exports, "number", { enumerable: true, get: function () { return tool_builder_1.number; } });
+Object.defineProperty(exports, "integer", { enumerable: true, get: function () { return tool_builder_1.integer; } });
+Object.defineProperty(exports, "boolean", { enumerable: true, get: function () { return tool_builder_1.boolean; } });
+Object.defineProperty(exports, "enumOf", { enumerable: true, get: function () { return tool_builder_1.enumOf; } });
+Object.defineProperty(exports, "object", { enumerable: true, get: function () { return tool_builder_1.object; } });
+Object.defineProperty(exports, "array", { enumerable: true, get: function () { return tool_builder_1.array; } });
+Object.defineProperty(exports, "optional", { enumerable: true, get: function () { return tool_builder_1.optional; } });
 // Stream utilities
 var stream_1 = require("./stream");
 Object.defineProperty(exports, "StreamManager", { enumerable: true, get: function () { return stream_1.StreamManager; } });

package/dist/stream.d.ts

@@ -24,7 +24,15 @@ export declare class StreamManager<T> {
     private initialConnectionAttempts;
     private isConnected;
     private isStopped;
+    private eventListeners;
     constructor(options: StreamManagerOptions<T>);
+    /**
+     * Add a listener for typed SSE events (e.g., 'chats', 'chat_messages')
+     * Used when server sends events with `event: eventName` header
+     */
+    addEventListener<E = unknown>(eventName: string, callback: (data: E) => void): () => void;
+    private setupEventListener;
+    private setupAllEventListeners;
     private clearTimeouts;
     private closeEventSource;
     private cleanup;

package/dist/stream.js

@@ -20,6 +20,7 @@ class StreamManager {
         this.initialConnectionAttempts = 0;
         this.isConnected = false;
         this.isStopped = false;
+        this.eventListeners = new Map();
         this.options = {
             autoReconnect: true,
             maxReconnects: 5,
@@ -27,6 +28,51 @@ class StreamManager {
             ...options,
         };
     }
+    /**
+     * Add a listener for typed SSE events (e.g., 'chats', 'chat_messages')
+     * Used when server sends events with `event: eventName` header
+     */
+    addEventListener(eventName, callback) {
+        const listeners = this.eventListeners.get(eventName) || new Set();
+        listeners.add(callback);
+        this.eventListeners.set(eventName, listeners);
+        // If already connected, set up the listener on the existing EventSource
+        if (this.eventSource) {
+            this.setupEventListener(this.eventSource, eventName);
+        }
+        // Return cleanup function
+        return () => {
+            const listeners = this.eventListeners.get(eventName);
+            if (listeners) {
+                listeners.delete(callback);
+                if (listeners.size === 0) {
+                    this.eventListeners.delete(eventName);
+                }
+            }
+        };
+    }
+    setupEventListener(source, eventName) {
+        source.addEventListener(eventName, (e) => {
+            if (this.isStopped)
+                return;
+            try {
+                const data = JSON.parse(e.data);
+                const listeners = this.eventListeners.get(eventName);
+                if (listeners?.size) {
+                    listeners.forEach(callback => callback(data));
+                }
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error('Invalid JSON');
+                this.options.onError?.(error);
+            }
+        });
+    }
+    setupAllEventListeners(source) {
+        this.eventListeners.forEach((_, eventName) => {
+            this.setupEventListener(source, eventName);
+        });
+    }
     clearTimeouts() {
         if (this.reconnectTimeout) {
             clearTimeout(this.reconnectTimeout);
@@ -93,6 +139,8 @@ class StreamManager {
             this.eventSource = source;
             this.isConnected = true;
             this.options.onStart?.();
+            // Set up typed event listeners (for events with `event: eventName` header)
+            this.setupAllEventListeners(source);
             source.onmessage = (e) => {
                 if (this.isStopped)
                     return;

package/dist/tool-builder.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Tool Builder - Fluent API for defining agent tools
+ */
+import { AgentTool, InternalToolsConfig } from './types';
+type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array';
+interface ParamSchema {
+    type: JsonSchemaType;
+    description?: string;
+    optional?: boolean;
+    enum?: string[];
+    properties?: Record<string, ParamSchema>;
+    items?: ParamSchema;
+}
+export declare const string: (description?: string) => ParamSchema;
+export declare const number: (description?: string) => ParamSchema;
+export declare const integer: (description?: string) => ParamSchema;
+export declare const boolean: (description?: string) => ParamSchema;
+export declare const enumOf: (values: string[], description?: string) => ParamSchema;
+export declare const object: (properties: Record<string, ParamSchema>, description?: string) => ParamSchema;
+export declare const array: (items: ParamSchema, description?: string) => ParamSchema;
+export declare const optional: <T extends ParamSchema>(schema: T) => T & {
+    optional: true;
+};
+declare class ToolBuilder {
+    protected name: string;
+    protected desc: string;
+    protected displayName?: string;
+    protected params: Record<string, ParamSchema>;
+    protected approval: boolean;
+    constructor(name: string);
+    describe(description: string): this;
+    display(name: string): this;
+    param(name: string, schema: ParamSchema): this;
+    requireApproval(): this;
+}
+declare class ClientToolBuilder extends ToolBuilder {
+    build(): AgentTool;
+}
+declare class AppToolBuilder extends ToolBuilder {
+    private appRef;
+    constructor(name: string, appRef: string);
+    build(): AgentTool;
+}
+declare class AgentToolBuilder extends ToolBuilder {
+    private agentRef;
+    constructor(name: string, agentRef: string);
+    build(): AgentTool;
+}
+declare class WebhookToolBuilder extends ToolBuilder {
+    private url;
+    private secretKey?;
+    constructor(name: string, url: string);
+    secret(key: string): this;
+    build(): AgentTool;
+}
+/** Create a client tool (executed by SDK consumer) */
+export declare const tool: (name: string) => ClientToolBuilder;
+/** Create an app tool (runs another inference app) */
+export declare const appTool: (name: string, appRef: string) => AppToolBuilder;
+/** Create an agent tool (delegates to sub-agent) */
+export declare const agentTool: (name: string, agentRef: string) => AgentToolBuilder;
+/** Create a webhook tool (calls external URL) */
+export declare const webhookTool: (name: string, url: string) => WebhookToolBuilder;
+declare class InternalToolsBuilder {
+    private config;
+    /** Enable plan tools (Create, Update, Load) */
+    plan(enabled?: boolean): this;
+    /** Enable memory tools (Set, Get, GetAll) */
+    memory(enabled?: boolean): this;
+    /** Enable widget tools (UI, HTML) - top-level only */
+    widget(enabled?: boolean): this;
+    /** Enable finish tool - sub-agents only */
+    finish(enabled?: boolean): this;
+    /** Enable all internal tools */
+    all(): this;
+    /** Disable all internal tools */
+    none(): this;
+    build(): InternalToolsConfig;
+}
+/** Create internal tools configuration */
+export declare const internalTools: () => InternalToolsBuilder;
+export {};