@inferencesh/sdk 0.6.30 → 0.6.47

package/README.md

@@ -409,6 +409,41 @@ const agent = client.agents.create({
 
 `callTool` is an alias for `httpTool`. Run `npx tsx examples/tool-builder.ts` for more schema examples (no API key required).
 
+### Lifecycle hooks
+
+Use `lifecycleHook()` to attach hooks to agent events. Hooks can call a webhook or delegate to another agent as a task:
+
+```typescript
+import { inference, lifecycleHook, HookEventTurnStart, HookEventToolCall } from '@inferencesh/sdk';
+
+const client = inference({ apiKey: 'your-api-key' });
+
+const agent = client.agents.create({
+  core_app: { ref: 'openrouter/claude-sonnet-4@abc' },
+  hooks: [
+    lifecycleHook(HookEventTurnStart)
+      .webhook('https://example.com/on-turn')
+      .timeout(10)
+      .build(),
+    lifecycleHook(HookEventToolCall)
+      .task('my-org/approval-agent')
+      .async(true)
+      .build(),
+  ],
+});
+```
+
+### Queued messages
+
+`sendMessage` automatically queues when the agent is busy processing a previous message. Queued messages appear with a `queued` status until the agent picks them up.
+
+To cancel a queued message before it is processed, use `cancelMessage` on the React provider or `chats.cancelMessage` on the API client:
+
+```typescript
+// Via the API client
+await client.chats.cancelMessage(messageId);
+```
+
 ### File attachments
 
 Pass files in `sendMessage` options. `Blob` values are uploaded first; objects with a `uri` (already uploaded via `client.files.upload`) are attached as-is:

package/dist/agent/actions.js

@@ -4,10 +4,11 @@
  * Action creators that handle side effects (API calls, streaming).
  * These are created once per provider instance with access to dispatch.
  */
-import { ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, } from '../types';
+import { AgentRunStateWorking, AgentRunStateSubmitted, AgentRunStateInputRequired, ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, } from '../types';
 import { isChatBusy } from '../utils';
 import { StreamableManager } from '../http/streamable';
 import { PollManager } from '../http/poll';
+import { createLLMDeltaAccumulator } from '../delta';
 import { isAdHocConfig, extractClientToolHandlers } from './types';
 import * as api from './api';
 // =============================================================================
@@ -15,7 +16,7 @@ import * as api from './api';
 // =============================================================================
 export function createActions(ctx) {
     const dispatchedToolInvocations = new Set();
-    const { client, dispatch, getConfig, getChatId, getClientToolHandlers, getStreamManager, setStreamManager, getStreamEnabled, getPollIntervalMs, callbacks } = ctx;
+    const { client, dispatch, getState, getConfig, getChatId, getClientToolHandlers, getStreamManager, setStreamManager, getStreamEnabled, getPollIntervalMs, callbacks } = ctx;
     let prevChatWasBusy = false;
     const checkTurnEnd = (chat) => {
         const busy = isChatBusy(chat);
@@ -34,13 +35,13 @@ export function createActions(ctx) {
             checkTurnEnd(chat);
         }
     };
-    const updateMessage = (message) => {
+    const updateMessage = (message, fields) => {
         const chatId = getChatId();
         // TODO: remove startsWith once the provider normalizes chatId to full ID after first fetchChat
         // Support short ID matching (URL short IDs are prefixes of full IDs)
         if (chatId && message.chat_id && message.chat_id !== chatId && !message.chat_id.startsWith(chatId))
             return;
-        dispatch({ type: 'UPDATE_MESSAGE', payload: message });
+        dispatch({ type: 'UPDATE_MESSAGE', payload: message, partial: fields ? true : undefined });
         // Dispatch client tool handlers when ready (in_progress or awaiting_input for backwards compat)
         const clientToolHandlers = getClientToolHandlers();
         if (message.tool_invocations && chatId && clientToolHandlers.size > 0) {
@@ -88,7 +89,7 @@ export function createActions(ctx) {
         dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'connecting' });
         callbacks.onStatusChange?.('connecting');
         try {
-            // Fetch initial chat
+            // Fetch initial chat (fetchChat loads messages separately since Chat.Get no longer preloads them)
             const chat = await api.fetchChat(client, id);
             if (chat) {
                 setChat(chat);
@@ -139,15 +140,25 @@ export function createActions(ctx) {
             }
         });
         // Listen for ChatMessage updates
-        manager.addEventListener('chat_messages', (message) => {
-            updateMessage(message);
+        manager.addEventListener('chat_messages', (message, fields) => {
+            updateMessage(message, fields);
         });
         // Listen for AgentRun updates (state transitions, output)
         manager.addEventListener('agent_runs', (run) => {
             dispatch({ type: 'UPDATE_ACTIVE_RUN', payload: run });
-            const asChat = { active_run: run };
-            callbacks.onStatusChange?.(isChatBusy(asChat) ? 'streaming' : 'idle');
-            checkTurnEnd(asChat);
+            const isRunActive = run.state === AgentRunStateWorking || run.state === AgentRunStateSubmitted || run.state === AgentRunStateInputRequired;
+            callbacks.onStatusChange?.(isRunActive ? 'streaming' : 'idle');
+            const currentChat = getState().chat;
+            if (currentChat)
+                checkTurnEnd({ ...currentChat, active_run: run });
+        });
+        // Listen for LLM delta events (token-by-token streaming)
+        const deltaAccum = createLLMDeltaAccumulator();
+        manager.addEventListener('delta', (evt) => {
+            if (evt && evt.delta) {
+                deltaAccum.apply(evt.delta);
+                dispatch({ type: 'DELTA_TOKEN', payload: deltaAccum.toOutput() });
+            }
         });
         setStreamManager(manager);
         manager.start();
@@ -156,13 +167,16 @@ export function createActions(ctx) {
     const pollChat = (id) => {
         let prevStatus = null;
         const manager = new PollManager({
-            pollFunction: () => client.http.request('get', `/chats/${id}/status`),
+            pollFunction: async () => {
+                const resp = await client.http.request('get', `/chats/${id}/status`);
+                return resp.data;
+            },
             intervalMs: getPollIntervalMs(),
             onData: async (statusData) => {
                 if (statusData.status === prevStatus)
                     return;
                 prevStatus = statusData.status;
-                // Status changed — fetch full chat
+                // Status changed — fetch chat (fetchChat loads messages)
                 try {
                     const chat = await api.fetchChat(client, id);
                     if (chat) {
@@ -229,7 +243,10 @@ export function createActions(ctx) {
             try {
                 const result = await api.sendMessage(client, agentConfig, chatId, trimmedText, files);
                 if (result) {
-                    const { chatId: newChatId } = result;
+                    const { chatId: newChatId, userMessage } = result;
+                    // Add user message from POST response immediately
+                    if (userMessage)
+                        dispatch({ type: 'UPDATE_MESSAGE', payload: userMessage });
                     // Start streaming if not already connected
                     const streamManager = getStreamManager();
                     if (newChatId && !streamManager) {
@@ -330,6 +347,48 @@ export function createActions(ctx) {
                 throw error;
             }
         },
+        cancelMessage: async (messageId) => {
+            try {
+                await api.cancelMessage(client, messageId);
+            }
+            catch (error) {
+                console.error('[AgentSDK] Failed to cancel message:', error);
+                const err = error instanceof Error ? error : new Error('Failed to cancel message');
+                dispatch({ type: 'SET_ERROR', payload: err.message });
+                callbacks.onError?.(err);
+                throw error;
+            }
+        },
+        resolveInterrupt: async (interruptId, decision) => {
+            try {
+                await api.resolveInterrupt(client, interruptId, decision);
+            }
+            catch (error) {
+                console.error('[AgentSDK] Failed to resolve interrupt:', error);
+                const err = error instanceof Error ? error : new Error('Failed to resolve interrupt');
+                dispatch({ type: 'SET_CONNECTION_STATUS', payload: 'error' });
+                dispatch({ type: 'SET_ERROR', payload: err.message });
+                callbacks.onError?.(err);
+                throw error;
+            }
+        },
+        loadOlderMessages: async () => {
+            const chatId = getChatId();
+            const cursor = getState().messageCursor;
+            if (!chatId || !cursor)
+                return false;
+            const page = await api.fetchMessagesPage(client, chatId, { cursor });
+            if (page.items.length > 0) {
+                dispatch({
+                    type: 'PREPEND_MESSAGES',
+                    payload: { messages: page.items, cursor: page.next_cursor, hasMore: page.has_next },
+                });
+            }
+            return page.has_next;
+        },
+        get hasOlderMessages() {
+            return getState().hasOlderMessages ?? false;
+        },
     };
     const internalActions = {
         streamChat,

package/dist/agent/api.d.ts

@@ -1,50 +1,42 @@
 /**
  * Agent Chat API
  *
- * API functions for agent chat operations.
- * Uses the client passed in from the provider.
- */
-import type { ChatDTO, ChatMessageDTO } from '../types';
-import type { AdHocAgentConfig, TemplateAgentConfig, AgentOptions, AgentClient, FileRef } from './types';
-/**
- * File input that can be either a File to upload or an already-uploaded file
- */
-export type FileInput = globalThis.File | FileRef;
-/**
- * Send a message using ad-hoc agent config
- */
-export declare function sendAdHocMessage(client: AgentClient, config: AdHocAgentConfig, chatId: string | null, text: string, attachments?: FileRef[]): Promise<{
-    chatId: string;
-    userMessage: ChatMessageDTO;
-    assistantMessage: ChatMessageDTO;
-} | null>;
-/**
- * Send a message using template agent config
+ * Two paths by user intent:
+ * - New conversation:  POST /chats (create chat with agent) → POST /chats/{id}/messages
+ * - Existing chat:     POST /chats/{id}/messages
+ *
+ * /agents/run stays for A2A/programmatic use.
  */
-export declare function sendTemplateMessage(client: AgentClient, config: TemplateAgentConfig, chatId: string | null, text: string, attachments?: FileRef[]): Promise<{
+import type { ChatDTO, ChatMessageDTO, InterruptDTO } from '../types';
+import type { AgentOptions, AgentClient, AgentInfo, FileRef } from './types';
+export interface SendResult {
     chatId: string;
     userMessage: ChatMessageDTO;
-    assistantMessage: ChatMessageDTO;
-} | null>;
+}
 /**
- * Send a message (unified interface)
+ * File input that can be either a File to upload or an already-uploaded file
  */
-export declare function sendMessage(client: AgentClient, config: AgentOptions, chatId: string | null, text: string, files?: FileInput[]): Promise<{
-    chatId: string;
-    userMessage: ChatMessageDTO;
-    assistantMessage: ChatMessageDTO;
-} | null>;
+export type FileInput = globalThis.File | FileRef;
 /**
- * Fetch a chat by ID
- */
+ * Send a message — creates chat if needed, then sends message
+ */
+export declare function sendMessage(client: AgentClient, config: AgentOptions, chatId: string | null, text: string, files?: FileInput[]): Promise<SendResult | null>;
+export declare function fetchAgentInfo(client: AgentClient, agentRef: string): Promise<AgentInfo | null>;
+export interface FetchMessagesOptions {
+    limit?: number;
+    cursor?: string;
+}
+export interface FetchMessagesResult {
+    items: ChatMessageDTO[];
+    next_cursor: string;
+    has_next: boolean;
+}
+export declare function fetchMessages(client: AgentClient, chatId: string, options?: FetchMessagesOptions): Promise<ChatMessageDTO[]>;
+export declare function fetchMessagesPage(client: AgentClient, chatId: string, options?: FetchMessagesOptions): Promise<FetchMessagesResult>;
 export declare function fetchChat(client: AgentClient, chatId: string): Promise<ChatDTO | null>;
-/**
- * Stop a chat
- */
 export declare function stopChat(client: AgentClient, chatId: string): Promise<void>;
-/**
- * Submit a tool result (for client tools/widgets/awaiting input)
- */
+export declare function cancelMessage(client: AgentClient, messageId: string): Promise<void>;
+export declare function setAgent(client: AgentClient, chatId: string, agentRef: string): Promise<ChatDTO>;
 export declare function submitToolResult(client: AgentClient, toolInvocationId: string, resultOrAction: string | {
     action: {
         type: string;
@@ -52,25 +44,12 @@ export declare function submitToolResult(client: AgentClient, toolInvocationId:
     };
     form_data?: Record<string, unknown>;
 }): Promise<void>;
-/**
- * Approve a tool (for HIL approval)
- */
 export declare function approveTool(client: AgentClient, toolInvocationId: string): Promise<void>;
-/**
- * Reject a tool (for HIL approval)
- */
 export declare function rejectTool(client: AgentClient, toolInvocationId: string, reason?: string): Promise<void>;
-/**
- * Always allow a tool for this chat
- */
 export declare function alwaysAllowTool(client: AgentClient, chatId: string, toolInvocationId: string, toolName: string): Promise<void>;
-/**
- * Upload a file and return the uploaded file reference
- */
+export declare function resolveInterrupt(client: AgentClient, interruptId: string, decision: 'allow' | 'deny'): Promise<InterruptDTO>;
+export declare function listRunInterrupts(client: AgentClient, runId: string): Promise<InterruptDTO[]>;
 export declare function uploadFile(client: AgentClient, file: globalThis.File): Promise<FileRef>;
-/**
- * Get streamable config for chat streaming (NDJSON)
- */
 export declare function getChatStreamConfig(client: AgentClient, chatId: string): {
     url: string;
     headers: Record<string, string>;

package/dist/agent/api.js

@@ -1,136 +1,126 @@
 /**
  * Agent Chat API
  *
- * API functions for agent chat operations.
- * Uses the client passed in from the provider.
- */
-import { isAdHocConfig, extractToolSchemas } from './types';
-/**
- * Check if input is an already-uploaded file
+ * Two paths by user intent:
+ * - New conversation:  POST /chats (create chat with agent) → POST /chats/{id}/messages
+ * - Existing chat:     POST /chats/{id}/messages
+ *
+ * /agents/run stays for A2A/programmatic use.
  */
+import { isAdHocConfig } from './types';
 function isFileRef(input) {
     return 'uri' in input && typeof input.uri === 'string';
 }
 /**
- * Send a message using ad-hoc agent config
+ * Process file inputs — upload raw files, pass through already-uploaded FileRefs
  */
-export async function sendAdHocMessage(client, config, chatId, text, attachments) {
-    // Extract just the schemas from tools (handlers are stripped out)
-    const toolSchemas = config.tools ? extractToolSchemas(config.tools) : undefined;
-    const request = {
-        chat_id: chatId ?? undefined,
-        agent_config: {
-            ...config,
-            system_prompt: config.system_prompt ?? '',
-            tools: toolSchemas
-        },
-        agent_name: config.name,
-        input: {
-            text,
-            attachments,
-            context_size: 0,
-            system_prompt: '',
-            context: [],
-            role: 'user',
-        },
-    };
-    const response = await client.http.request('post', '/agents/run', { data: request });
-    if (response) {
-        const { user_message, assistant_message } = response;
-        if (user_message && assistant_message) {
-            return {
-                chatId: assistant_message.chat_id,
-                userMessage: user_message,
-                assistantMessage: assistant_message,
-            };
+async function processFiles(client, files) {
+    if (!files || files.length === 0)
+        return undefined;
+    const results = await Promise.all(files.map(async (file) => {
+        if (isFileRef(file))
+            return file;
+        try {
+            return await client.files.upload(file);
         }
-    }
-    return null;
+        catch (error) {
+            console.error('[AgentSDK] Failed to upload file:', error);
+            return null;
+        }
+    }));
+    const refs = results.filter((r) => r !== null);
+    return refs.length > 0 ? refs : undefined;
 }
 /**
- * Send a message using template agent config
+ * Create a new chat with an agent — POST /chats
  */
-export async function sendTemplateMessage(client, config, chatId, text, attachments) {
-    const request = {
-        chat_id: chatId ?? undefined,
-        // Only include agent if it's not empty (for existing chats, backend uses chat's agent)
-        agent: config.agent || undefined,
-        // Agent-level context (version_id, app_id, ...). Omit when empty so we don't
-        // send a bare {} for agents that declare no context.
-        context: config.context && Object.keys(config.context).length > 0 ? config.context : undefined,
-        input: {
-            text,
-            attachments,
-            context_size: 0,
-            system_prompt: '',
-            context: [],
-            role: 'user',
-        },
+async function createChat(client, config) {
+    const agentRef = isAdHocConfig(config) ? config.core_app.ref : config.agent;
+    const context = !isAdHocConfig(config) ? config.context : undefined;
+    const resp = await client.http.request('post', '/chats', {
+        data: { agent: agentRef, context },
+    });
+    return resp.data;
+}
+/**
+ * Send a message in a chat — POST /chats/{id}/messages
+ */
+async function sendChatMessage(client, chatId, text) {
+    const resp = await client.http.request('post', `/chats/${chatId}/messages`, {
+        data: { message: text },
+    });
+    return {
+        chatId,
+        userMessage: resp.data,
     };
-    const response = await client.http.request('post', '/agents/run', { data: request });
-    if (response) {
-        const { user_message, assistant_message } = response;
-        if (user_message && assistant_message) {
-            return {
-                chatId: assistant_message.chat_id,
-                userMessage: user_message,
-                assistantMessage: assistant_message,
-            };
-        }
-    }
-    return null;
 }
 /**
- * Send a message (unified interface)
+ * Send a message — creates chat if needed, then sends message
  */
 export async function sendMessage(client, config, chatId, text, files) {
-    // Process files - upload if needed, collect as FileRef attachments
-    let attachments;
-    if (files && files.length > 0) {
-        attachments = [];
-        for (const file of files) {
-            // Check if already uploaded (FileRef)
-            if (isFileRef(file)) {
-                attachments.push(file);
-                continue;
-            }
-            // Upload the file
-            try {
-                const result = await client.files.upload(file);
-                if (result) {
-                    attachments.push(result);
-                }
-            }
-            catch (error) {
-                console.error('[AgentSDK] Failed to upload file:', error);
-            }
-        }
-        if (attachments.length === 0) {
-            attachments = undefined;
-        }
+    await processFiles(client, files);
+    // Existing chat — just send the message
+    if (chatId) {
+        return sendChatMessage(client, chatId, text);
+    }
+    // New chat — create it, then send the first message
+    const chat = await createChat(client, config);
+    return sendChatMessage(client, chat.id, text);
+}
+// =========================================================================
+// Agent info
+// =========================================================================
+export async function fetchAgentInfo(client, agentRef) {
+    try {
+        const resp = await client.http.request('get', `/agents/${agentRef}`);
+        const version = resp.data?.version;
+        return {
+            description: version?.description,
+            example_prompts: version?.example_prompts,
+        };
     }
-    if (isAdHocConfig(config)) {
-        return sendAdHocMessage(client, config, chatId, text, attachments);
+    catch {
+        return null;
+    }
+}
+export async function fetchMessages(client, chatId, options) {
+    const result = await fetchMessagesPage(client, chatId, options);
+    return result.items;
+}
+export async function fetchMessagesPage(client, chatId, options) {
+    try {
+        const params = {};
+        if (options?.limit !== undefined)
+            params.limit = options.limit;
+        if (options?.cursor)
+            params.cursor = options.cursor;
+        const resp = await client.http.request('get', `/chats/${chatId}/messages`, { params });
+        return resp.data || { items: [], next_cursor: '', has_next: false };
     }
-    else {
-        return sendTemplateMessage(client, config, chatId, text, attachments);
+    catch (error) {
+        console.error('[AgentSDK] Failed to fetch messages:', error);
+        return { items: [], next_cursor: '', has_next: false };
     }
 }
-/**
- * Fetch a chat by ID
- */
 export async function fetchChat(client, chatId) {
     try {
-        return await client.http.request('get', `/chats/${chatId}`);
+        const resp = await client.http.request('get', `/chats/${chatId}`);
+        const chat = resp.data;
+        // Chat.Get no longer preloads messages — fetch them separately and attach
+        if (chat && (!chat.chat_messages || chat.chat_messages.length === 0)) {
+            const page = await fetchMessagesPage(client, chatId);
+            chat.chat_messages = page.items;
+            // Store pagination info on the chat for the reducer to pick up
+            chat._messageCursor = page.next_cursor;
+            chat._hasOlderMessages = page.has_next;
+        }
+        return chat;
     }
     catch (error) {
         console.error('[AgentSDK] Failed to fetch chat:', error);
     }
     return null;
 }
-/**
- * Stop a chat
- */
 export async function stopChat(client, chatId) {
     try {
         await client.http.request('post', `/chats/${chatId}/stop`);
@@ -139,67 +129,52 @@ export async function stopChat(client, chatId) {
         console.error('[AgentSDK] Failed to stop chat:', error);
     }
 }
-/**
- * Submit a tool result (for client tools/widgets/awaiting input)
- */
+export async function cancelMessage(client, messageId) {
+    await client.http.request('post', `/chats/messages/${messageId}/cancel`);
+}
+export async function setAgent(client, chatId, agentRef) {
+    const resp = await client.http.request('post', `/chats/${chatId}/agent`, {
+        data: { agent: agentRef },
+    });
+    return resp.data;
+}
+// =========================================================================
+// Tool operations
+// =========================================================================
 export async function submitToolResult(client, toolInvocationId, resultOrAction) {
-    try {
-        const data = typeof resultOrAction === 'string' ? { result: resultOrAction } : resultOrAction;
-        await client.http.request('post', `/tools/${toolInvocationId}`, { data });
-    }
-    catch (error) {
-        console.error('[AgentSDK] Failed to submit tool result:', error);
-        throw error;
-    }
+    const data = typeof resultOrAction === 'string' ? { result: resultOrAction } : resultOrAction;
+    await client.http.request('post', `/tools/${toolInvocationId}`, { data });
 }
-/**
- * Approve a tool (for HIL approval)
- */
 export async function approveTool(client, toolInvocationId) {
-    try {
-        await client.http.request('post', `/tools/${toolInvocationId}/invoke`);
-    }
-    catch (error) {
-        console.error('[AgentSDK] Failed to approve tool:', error);
-        throw error;
-    }
+    await client.http.request('post', `/tools/${toolInvocationId}/invoke`);
 }
-/**
- * Reject a tool (for HIL approval)
- */
 export async function rejectTool(client, toolInvocationId, reason) {
-    try {
-        await client.http.request('post', `/tools/${toolInvocationId}/reject`, { data: { reason } });
-    }
-    catch (error) {
-        console.error('[AgentSDK] Failed to reject tool:', error);
-        throw error;
-    }
+    await client.http.request('post', `/tools/${toolInvocationId}/reject`, { data: { reason } });
 }
-/**
- * Always allow a tool for this chat
- */
 export async function alwaysAllowTool(client, chatId, toolInvocationId, toolName) {
-    try {
-        await client.http.request('post', `/chats/${chatId}/tools/${toolInvocationId}/always-allow`, {
-            data: { tool_name: toolName }
-        });
-    }
-    catch (error) {
-        console.error('[AgentSDK] Failed to always-allow tool:', error);
-        throw error;
-    }
+    await client.http.request('post', `/chats/${chatId}/tools/${toolInvocationId}/always-allow`, {
+        data: { tool_name: toolName }
+    });
 }
-/**
- * Upload a file and return the uploaded file reference
- */
+// =========================================================================
+// Interrupt operations
+// =========================================================================
+export async function resolveInterrupt(client, interruptId, decision) {
+    const resp = await client.http.request('post', `/interrupts/${interruptId}/resolve`, {
+        data: { decision }
+    });
+    return resp.data;
+}
+export async function listRunInterrupts(client, runId) {
+    const resp = await client.http.request('get', `/agent-runs/${runId}/interrupts`);
+    return resp.data;
+}
+// =========================================================================
+// File & stream operations
+// =========================================================================
 export async function uploadFile(client, file) {
-    const result = await client.files.upload(file);
-    return result;
+    return client.files.upload(file);
 }
-/**
- * Get streamable config for chat streaming (NDJSON)
- */
 export function getChatStreamConfig(client, chatId) {
     return client.http.getStreamableConfig(`/chats/${chatId}/stream`);
 }