@inferencesh/sdk 0.6.8 → 0.6.12

package/CHANGELOG.md

@@ -7,8 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.8] - 2026-05-20
+
 ### Added
 
+- README tool builder section: `httpTool`/`callTool` auth, `mcpTool`, and builder comparison table
+- `examples/tool-builder.ts` demonstrates HTTP and MCP tool schemas
+
 - Typed SDK constants for integrations: `IntegrationProvider*`, `IntegrationAuthType*`, `IntegrationStatus*`
 - `IntegrationDTO` fields (`provider`, `type`, `auth`, `status`) now use those typed aliases
 - Additional `InstanceStatus*` constants (`creating`, `pending_provider`, `error`, `deleting`)
@@ -65,7 +70,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Configurable reconnection behavior
 - Comprehensive error handling
 
-[Unreleased]: https://github.com/inference-sh/sdk-js/compare/v0.6.7...HEAD
+[Unreleased]: https://github.com/inference-sh/sdk-js/compare/v0.6.8...HEAD
+[0.6.8]: https://github.com/inference-sh/sdk-js/compare/v0.6.7...v0.6.8
 [0.6.7]: https://github.com/inference-sh/sdk-js/compare/v0.6.6...v0.6.7
 [0.1.1]: https://github.com/inference-sh/sdk-js/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/inference-sh/sdk-js/releases/tag/v0.1.0

package/README.md

@@ -7,7 +7,7 @@
 
 official javascript/typescript sdk for [inference.sh](https://inference.sh) — the ai agent runtime for serverless ai inference.
 
-run ai models, build ai agents, and deploy generative ai applications with a simple api. access 250+ models including flux, stable diffusion, llms (claude, gpt, gemini), video generation (veo, seedance), and more.
+run ai models, build ai agents, and deploy generative ai applications with a simple api. access models including flux, stable diffusion, llms (claude, gpt, gemini), video generation (veo, seedance), and more.
 
 ## Installation
 
@@ -340,6 +340,75 @@ await agent.sendMessage('What is the weather in Paris?', {
 
 For multi-turn chats, the SDK opens the chat stream before sending the next message so updates are not missed. Use `stopChat()` to cancel in-flight generation (`POST /chats/{id}/stop`), and `reset()` to clear the current chat and start fresh.
 
+### Tool builder
+
+Use the fluent builders to define `AgentTool` schemas. Client tools (`tool`) run in your app via `onToolCall`; server-side tools run on inference.sh.
+
+| Builder | Runs on | Description |
+|---------|---------|-------------|
+| `tool(name)` | Client | Local handler; only the schema is sent to the API |
+| `appTool(name, appRef)` | Server | Invoke another inference app |
+| `agentTool(name, agentRef)` | Server | Delegate to a sub-agent |
+| `httpTool(name, url)` / `callTool(name, url)` | Server | HTTP request with credential injection (preferred over `webhookTool`) |
+| `webhookTool(name, url)` | Server | Unsigned webhook (legacy; use `httpTool` for new tools) |
+| `mcpTool(name, integrationId, toolName)` | Server | Call a tool on a connected MCP integration |
+| `internalTools()` | Server | Built-in plan, memory, and widget tools |
+
+```typescript
+import {
+  inference,
+  tool,
+  appTool,
+  httpTool,
+  mcpTool,
+  internalTools,
+  string,
+  IntegrationProviderGoogle,
+} from '@inferencesh/sdk';
+
+const clientTool = tool('get_weather')
+  .describe('Get current weather')
+  .param('city', string('City name'))
+  .build();
+
+// HTTP tool with OAuth integration credentials (injected server-side)
+const gmailSend = httpTool('gmail_send', 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send')
+  .describe('Send an email via Gmail')
+  .method('POST')
+  .auth({ integration: IntegrationProviderGoogle, integrationId: 'your-integration-id' })
+  .build();
+
+// API key or bearer auth
+const fetchData = httpTool('fetch', 'https://api.example.com/data')
+  .method('GET')
+  .auth({ apiKey: 'YOUR_KEY', header: 'X-API-Key' }) // default header: X-API-Key
+  .header('Accept', 'application/json')
+  .build();
+
+const bearerFetch = httpTool('bearer_fetch', 'https://api.example.com')
+  .auth({ bearer: 'YOUR_TOKEN' })
+  .build();
+
+const imageGen = appTool('generate_image', 'infsh/flux-schnell@abc123')
+  .param('prompt', string('Image description'))
+  .requireApproval()
+  .build();
+
+const mcpSearch = mcpTool('notion_search', 'your-mcp-integration-id', 'search')
+  .describe('Search Notion pages')
+  .param('query', string('Search query'))
+  .build();
+
+const agent = client.agents.create({
+  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
+  system_prompt: 'You are helpful.',
+  tools: [clientTool, gmailSend, imageGen, mcpSearch],
+  internal_tools: internalTools().memory().build(),
+});
+```
+
+`callTool` is an alias for `httpTool`. Run `npx tsx examples/tool-builder.ts` for more schema examples (no API key required).
+
 ### 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,7 +4,7 @@
  * Action creators that handle side effects (API calls, streaming).
  * These are created once per provider instance with access to dispatch.
  */
-import { ToolInvocationStatusAwaitingInput, ToolTypeClient, ChatStatusBusy, } from '../types';
+import { ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ToolTypeClient, ChatStatusBusy, } from '../types';
 import { StreamableManager } from '../http/streamable';
 import { PollManager } from '../http/poll';
 import { isAdHocConfig, extractClientToolHandlers } from './types';
@@ -35,12 +35,12 @@ export function createActions(ctx) {
         if (chatId && message.chat_id !== chatId && !message.chat_id.startsWith(chatId))
             return;
         dispatch({ type: 'UPDATE_MESSAGE', payload: message });
-        // Check for client tool invocations that need execution
+        // 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) {
             for (const invocation of message.tool_invocations) {
                 if (invocation.type === ToolTypeClient &&
-                    invocation.status === ToolInvocationStatusAwaitingInput) {
+                    (invocation.status === ToolInvocationStatusInProgress || invocation.status === ToolInvocationStatusAwaitingInput)) {
                     // Skip if already dispatched
                     if (dispatchedToolInvocations.has(invocation.id)) {
                         continue;

package/dist/agent/actions.test.js

@@ -91,6 +91,9 @@ describe('createActions', () => {
             assistantMessage: makeMessage(),
         });
         mockAgentApi.submitToolResult.mockResolvedValue(undefined);
+        mockAgentApi.approveTool.mockResolvedValue(undefined);
+        mockAgentApi.rejectTool.mockResolvedValue(undefined);
+        mockAgentApi.alwaysAllowTool.mockResolvedValue(undefined);
     });
     describe('updateMessage (via stream listeners)', () => {
         it('should ignore messages for a different chat when IDs do not prefix-match', async () => {
@@ -388,6 +391,12 @@ describe('createActions', () => {
             publicActions.stopGeneration();
             expect(mockAgentApi.stopChat).toHaveBeenCalledWith(ctx.client, 'chat-short');
         });
+        it('stopGeneration should no-op when there is no chatId', () => {
+            const { ctx } = createTestContext({ getChatId: () => null });
+            const { publicActions } = createActions(ctx);
+            publicActions.stopGeneration();
+            expect(mockAgentApi.stopChat).not.toHaveBeenCalled();
+        });
         it('submitToolResult should set error state when API fails', async () => {
             mockAgentApi.submitToolResult.mockRejectedValueOnce(new Error('submit failed'));
             const onError = jest.fn();
@@ -400,5 +409,85 @@ describe('createActions', () => {
             });
             expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: 'submit failed' }));
         });
+        it('clearError should reset error and connection status to idle', () => {
+            const { ctx, dispatch } = createTestContext();
+            const { publicActions } = createActions(ctx);
+            publicActions.clearError();
+            expect(dispatch).toHaveBeenCalledWith({
+                type: 'SET_ERROR',
+                payload: undefined,
+            });
+            expect(dispatch).toHaveBeenCalledWith({
+                type: 'SET_CONNECTION_STATUS',
+                payload: 'idle',
+            });
+        });
+    });
+    describe('HIL tool actions', () => {
+        it('approveTool should delegate to the API', async () => {
+            const { ctx } = createTestContext();
+            const { publicActions } = createActions(ctx);
+            await publicActions.approveTool('inv-approve');
+            expect(mockAgentApi.approveTool).toHaveBeenCalledWith(ctx.client, 'inv-approve');
+        });
+        it('rejectTool should pass an optional reason', async () => {
+            const { ctx } = createTestContext();
+            const { publicActions } = createActions(ctx);
+            await publicActions.rejectTool('inv-reject', 'unsafe');
+            expect(mockAgentApi.rejectTool).toHaveBeenCalledWith(ctx.client, 'inv-reject', 'unsafe');
+        });
+        it('alwaysAllowTool should no-op without a chatId', async () => {
+            const { ctx } = createTestContext({ getChatId: () => null });
+            const { publicActions } = createActions(ctx);
+            await publicActions.alwaysAllowTool('inv-allow', 'my_tool');
+            expect(mockAgentApi.alwaysAllowTool).not.toHaveBeenCalled();
+        });
+        it('alwaysAllowTool should call API when chatId exists', async () => {
+            const { ctx } = createTestContext({ getChatId: () => 'chat-short' });
+            const { publicActions } = createActions(ctx);
+            await publicActions.alwaysAllowTool('inv-allow', 'my_tool');
+            expect(mockAgentApi.alwaysAllowTool).toHaveBeenCalledWith(ctx.client, 'chat-short', 'inv-allow', 'my_tool');
+        });
+        it('approveTool should set error state when API fails', async () => {
+            mockAgentApi.approveTool.mockRejectedValueOnce(new Error('approve failed'));
+            const onError = jest.fn();
+            const { ctx, dispatch } = createTestContext({ callbacks: { onError } });
+            const { publicActions } = createActions(ctx);
+            await expect(publicActions.approveTool('inv-1')).rejects.toThrow('approve failed');
+            expect(dispatch).toHaveBeenCalledWith({
+                type: 'SET_CONNECTION_STATUS',
+                payload: 'error',
+            });
+            expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: 'approve failed' }));
+        });
+    });
+    describe('setChatId', () => {
+        it('should no-op when the chat id is unchanged', async () => {
+            const { ctx } = createTestContext({ getChatId: () => 'chat-short' });
+            const { internalActions } = createActions(ctx);
+            internalActions.setChatId('chat-short');
+            await Promise.resolve();
+            expect(StreamableManager).not.toHaveBeenCalled();
+        });
+        it('should reset and stop stream when chat id is cleared', async () => {
+            const { ctx, dispatch } = createTestContext();
+            const { internalActions } = createActions(ctx);
+            internalActions.streamChat('chat-full-id-123');
+            await Promise.resolve();
+            internalActions.setChatId(null);
+            expect(streamInstances[0].stop).toHaveBeenCalled();
+            expect(dispatch).toHaveBeenCalledWith({ type: 'RESET' });
+        });
+        it('should start streaming when switching to a new chat id', async () => {
+            const { ctx, dispatch } = createTestContext({ getChatId: () => null });
+            const { internalActions } = createActions(ctx);
+            internalActions.setChatId('chat-new');
+            await Promise.resolve();
+            expect(dispatch).toHaveBeenCalledWith({
+                type: 'SET_CHAT_ID',
+                payload: 'chat-new',
+            });
+            expect(StreamableManager).toHaveBeenCalled();
+        });
     });
 });

package/dist/agent/api.test.js

@@ -1,6 +1,6 @@
 import { HttpClient } from '../http/client';
 import { FilesAPI } from '../api/files';
-import { sendAdHocMessage, sendTemplateMessage, sendMessage, submitToolResult, getChatStreamConfig, } from './api';
+import { sendAdHocMessage, sendTemplateMessage, sendMessage, submitToolResult, approveTool, rejectTool, alwaysAllowTool, fetchChat, stopChat, getChatStreamConfig, } from './api';
 import { ToolTypeClient } from '../types';
 const mockFetch = jest.fn();
 global.fetch = mockFetch;
@@ -30,8 +30,13 @@ describe('agent/api', () => {
         jest.clearAllMocks();
     });
     describe('sendAdHocMessage', () => {
+        it('should return null when the API response omits messages', async () => {
+            mockJsonResponse({});
+            const result = await sendAdHocMessage(makeClient(), adHocConfig, null, 'hello');
+            expect(result).toBeNull();
+        });
         it('should strip client tool handlers from the agents/run request body', async () => {
-            mockJsonResponse({ success: true, data: runResponse });
+            mockJsonResponse(runResponse);
             const handler = jest.fn().mockReturnValue('ok');
             await sendAdHocMessage(makeClient(), {
                 ...adHocConfig,
@@ -58,8 +63,15 @@ describe('agent/api', () => {
         });
     });
     describe('sendTemplateMessage', () => {
+        it('should return null when assistant_message is missing', async () => {
+            mockJsonResponse({
+                user_message: { id: 'u1', chat_id: 'chat-1', role: 'user' },
+            });
+            const result = await sendTemplateMessage(makeClient(), { agent: 'agent-1' }, null, 'hello');
+            expect(result).toBeNull();
+        });
         it('should omit empty agent field for existing chats', async () => {
-            mockJsonResponse({ success: true, data: runResponse });
+            mockJsonResponse(runResponse);
             await sendTemplateMessage(makeClient(), { agent: '' }, 'chat-existing', 'hi');
             const [, init] = mockFetch.mock.calls[0];
             const body = JSON.parse(String(init.body));
@@ -69,7 +81,7 @@ describe('agent/api', () => {
     });
     describe('sendMessage', () => {
         it('should pass FileRef attachments without uploading', async () => {
-            mockJsonResponse({ success: true, data: runResponse });
+            mockJsonResponse(runResponse);
             const fileRef = {
                 id: 'f1',
                 uri: 'inf://files/abc',
@@ -82,6 +94,19 @@ describe('agent/api', () => {
             const body = JSON.parse(String(init.body));
             expect(body.input.attachments).toEqual([fileRef]);
         });
+        it('should omit attachments when every file upload fails', async () => {
+            const client = makeClient();
+            const uploadSpy = jest
+                .spyOn(client.files, 'upload')
+                .mockRejectedValue(new Error('upload failed'));
+            mockJsonResponse(runResponse);
+            const file = new File(['data'], 'doc.txt', { type: 'text/plain' });
+            await sendMessage(client, adHocConfig, null, 'with file', [file]);
+            const [, init] = mockFetch.mock.calls[0];
+            const body = JSON.parse(String(init.body));
+            expect(body.input.attachments).toBeUndefined();
+            uploadSpy.mockRestore();
+        });
         it('should upload File inputs before sending', async () => {
             const fileRecord = {
                 id: 'file-1',
@@ -90,9 +115,9 @@ describe('agent/api', () => {
                 upload_url: 'https://upload.example/put',
                 content_type: 'text/plain',
             };
-            mockJsonResponse({ success: true, data: [fileRecord] });
+            mockJsonResponse([fileRecord]);
             mockFetch.mockResolvedValueOnce({ ok: true, status: 200 });
-            mockJsonResponse({ success: true, data: runResponse });
+            mockJsonResponse(runResponse);
             const file = new File(['hello'], 'hello.txt', { type: 'text/plain' });
             await sendMessage(makeClient(), adHocConfig, null, 'with file', [file]);
             expect(mockFetch).toHaveBeenCalledTimes(3);
@@ -103,14 +128,14 @@ describe('agent/api', () => {
     });
     describe('submitToolResult', () => {
         it('should wrap string results in { result }', async () => {
-            mockJsonResponse({ success: true, data: null });
+            mockJsonResponse(null);
             await submitToolResult(makeClient(), 'inv-1', 'done');
             const [url, init] = mockFetch.mock.calls[0];
             expect(url).toContain('/tools/inv-1');
             expect(JSON.parse(String(init.body))).toEqual({ result: 'done' });
         });
         it('should pass structured action objects through unchanged', async () => {
-            mockJsonResponse({ success: true, data: null });
+            mockJsonResponse(null);
             const payload = {
                 action: { type: 'approve', payload: { ok: true } },
             };
@@ -119,6 +144,59 @@ describe('agent/api', () => {
             expect(JSON.parse(String(init.body))).toEqual(payload);
         });
     });
+    describe('fetchChat', () => {
+        it('should return chat data on success', async () => {
+            const chat = { id: 'chat-1', status: 'idle' };
+            mockJsonResponse(chat);
+            const result = await fetchChat(makeClient(), 'chat-1');
+            expect(result).toEqual(chat);
+        });
+        it('should return null and not throw when the request fails', async () => {
+            mockFetch.mockRejectedValueOnce(new Error('network error'));
+            const result = await fetchChat(makeClient(), 'chat-1');
+            expect(result).toBeNull();
+        });
+    });
+    describe('stopChat', () => {
+        it('should POST to /chats/{id}/stop', async () => {
+            mockJsonResponse(null);
+            await stopChat(makeClient(), 'chat-1');
+            const [url, init] = mockFetch.mock.calls[0];
+            expect(url).toContain('/chats/chat-1/stop');
+            expect(init.method).toBe('POST');
+        });
+        it('should swallow errors without throwing', async () => {
+            mockFetch.mockRejectedValueOnce(new Error('stop failed'));
+            await expect(stopChat(makeClient(), 'chat-1')).resolves.toBeUndefined();
+        });
+    });
+    describe('HIL tool approval', () => {
+        it('approveTool should POST to /tools/{id}/invoke', async () => {
+            mockJsonResponse(null);
+            await approveTool(makeClient(), 'inv-approve');
+            const [url, init] = mockFetch.mock.calls[0];
+            expect(url).toContain('/tools/inv-approve/invoke');
+            expect(init.method).toBe('POST');
+        });
+        it('rejectTool should POST reason to /tools/{id}/reject', async () => {
+            mockJsonResponse(null);
+            await rejectTool(makeClient(), 'inv-reject', 'not safe');
+            const [url, init] = mockFetch.mock.calls[0];
+            expect(url).toContain('/tools/inv-reject/reject');
+            expect(JSON.parse(String(init.body))).toEqual({ reason: 'not safe' });
+        });
+        it('alwaysAllowTool should POST tool_name to the chat tools endpoint', async () => {
+            mockJsonResponse(null);
+            await alwaysAllowTool(makeClient(), 'chat-1', 'inv-allow', 'browser_tool');
+            const [url, init] = mockFetch.mock.calls[0];
+            expect(url).toContain('/chats/chat-1/tools/inv-allow/always-allow');
+            expect(JSON.parse(String(init.body))).toEqual({ tool_name: 'browser_tool' });
+        });
+        it('should rethrow when approveTool request fails', async () => {
+            mockFetch.mockRejectedValueOnce(new Error('approve failed'));
+            await expect(approveTool(makeClient(), 'inv-1')).rejects.toThrow('approve failed');
+        });
+    });
     describe('getChatStreamConfig', () => {
         it('should delegate to HttpClient.getStreamableConfig for the chat stream path', () => {
             const client = makeClient();

package/dist/api/agents.d.ts

@@ -144,10 +144,20 @@ export declare class AgentsAPI {
      * Get a specific agent version
      */
     getVersion(agentId: string, versionId: string): Promise<AgentVersionDTO>;
+    /**
+     * Get an agent by namespace/name (e.g., "inference/my-agent")
+     */
+    getByName(namespace: string, name: string): Promise<AgentDTO>;
     /**
      * Get internal tools for the agent
      */
     getInternalTools(): Promise<InternalToolDefinition[]>;
+    /**
+     * Get A2A protocol agent card for an agent.
+     * Returns raw JSON (not wrapped in {data:...}) for direct upload to GCP Producer Portal.
+     * Spec: https://a2a-protocol.org/latest/specification/
+     */
+    getA2ACard(agentId: string): Promise<Record<string, unknown>>;
     /**
      * Create an agent instance for chat interactions
      */

package/dist/api/agents.js

@@ -1,6 +1,6 @@
 import { StreamableManager } from '../http/streamable';
 import { PollManager } from '../http/poll';
-import { ToolTypeClient, ToolInvocationStatusAwaitingInput, ChatStatusBusy, } from '../types';
+import { ToolTypeClient, ToolInvocationStatusAwaitingInput, ToolInvocationStatusInProgress, ChatStatusBusy, } from '../types';
 /**
  * Agent for chat interactions
  *
@@ -166,7 +166,7 @@ export class Agent {
                     for (const inv of message.tool_invocations) {
                         if (this.dispatchedToolCalls.has(inv.id))
                             continue;
-                        if (inv.type === ToolTypeClient && inv.status === ToolInvocationStatusAwaitingInput) {
+                        if (inv.type === ToolTypeClient && (inv.status === ToolInvocationStatusInProgress || inv.status === ToolInvocationStatusAwaitingInput)) {
                             this.dispatchedToolCalls.add(inv.id);
                             options.onToolCall({
                                 id: inv.id,
@@ -222,7 +222,7 @@ export class Agent {
                                 for (const inv of message.tool_invocations) {
                                     if (this.dispatchedToolCalls.has(inv.id))
                                         continue;
-                                    if (inv.type === ToolTypeClient && inv.status === ToolInvocationStatusAwaitingInput) {
+                                    if (inv.type === ToolTypeClient && (inv.status === ToolInvocationStatusInProgress || inv.status === ToolInvocationStatusAwaitingInput)) {
                                         this.dispatchedToolCalls.add(inv.id);
                                         options.onToolCall({
                                             id: inv.id,
@@ -319,12 +319,26 @@ export class AgentsAPI {
     async getVersion(agentId, versionId) {
         return this.http.request('get', `/agents/${agentId}/versions/${versionId}`);
     }
+    /**
+     * Get an agent by namespace/name (e.g., "inference/my-agent")
+     */
+    async getByName(namespace, name) {
+        return this.http.request('get', `/agents/${namespace}/${name}`);
+    }
     /**
      * Get internal tools for the agent
      */
     async getInternalTools() {
         return this.http.request('get', '/agents/internal-tools');
     }
+    /**
+     * Get A2A protocol agent card for an agent.
+     * Returns raw JSON (not wrapped in {data:...}) for direct upload to GCP Producer Portal.
+     * Spec: https://a2a-protocol.org/latest/specification/
+     */
+    async getA2ACard(agentId) {
+        return this.http.request('get', `/agents/${agentId}/card`);
+    }
     // ==========================================================================
     // Agent Runtime (chat interactions)
     // ==========================================================================