@inferencesh/sdk 0.6.7 → 0.6.10

package/CHANGELOG.md

@@ -7,6 +7,34 @@ 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`)
+- `ToolParamType*` constants for JSON Schema tool parameter types (distinct from `ToolCallType`)
+
+## [0.6.7] - 2026-05-19
+
+### Added
+
+- `client.sessions` API: `get`, `list`, `keepalive`, and `end` for session lifecycle management
+- Session error types: `SessionNotFoundError`, `SessionExpiredError`, `SessionEndedError`
+- Agent chat: `sendMessage` file attachments (upload `Blob` or reuse uploaded file `uri`)
+- Agent lifecycle: `stopChat()`, `reset()`, and `agent.run()` for structured output via polling
+- Task streaming: `onPartialUpdate` callback for partial NDJSON stream payloads
+- Client config: `stream` and `pollIntervalMs` for global streaming vs status polling
+
+### Changed
+
+- README documents ad-hoc agent field names (`core_app`, `system_prompt`) and tool builder API
+- Polling mode: `run()` rejects if full task fetch fails after a status transition
+
 ## [0.1.1] - 2024-11-30
 
 ### Added
@@ -42,6 +70,9 @@ 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.1.0...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

@@ -90,18 +90,43 @@ console.log('Status:', task.status);
 
 ### Real-time Status Updates
 
+By default, the client streams task progress over NDJSON (`/tasks/{id}/stream`) and invokes `onUpdate` as the task changes. Use `onPartialUpdate` when you only need specific fields from a partial stream payload:
+
 ```typescript
-const result = await client.tasks.run(
+const result = await client.run(
   { app: 'my-app', input: { prompt: 'hello' } },
   {
     onUpdate: (update) => {
       console.log('Status:', update.status);
       console.log('Progress:', update.logs);
-    }
+    },
+    onPartialUpdate: (update, fields) => {
+      console.log('Changed fields:', fields, update.status);
+    },
   }
 );
 ```
 
+### Streaming vs Polling
+
+SSE/NDJSON streaming is the default. For edge runtimes that cannot keep long-lived connections open (Convex actions, Cloudflare Workers, etc.), disable streaming and use lightweight status polling instead:
+
+```typescript
+const client = inference({
+  apiKey: 'your-api-key',
+  stream: false,           // poll /tasks/{id}/status instead of streaming
+  pollIntervalMs: 2000,    // default: 2000
+});
+
+// Per-call override
+const result = await client.run(
+  { app: 'my-app', input: { prompt: 'hello' } },
+  { stream: false, onUpdate: (u) => console.log(u.status) }
+);
+```
+
+In polling mode, the SDK checks `/tasks/{id}/status` and fetches the full task when the status changes. If that fetch fails after a status transition, `run()` rejects with the underlying error.
+
 ### Batch Processing
 
 ```typescript
@@ -196,6 +221,58 @@ const result = await client.tasks.run({
 - Maximum timeout: 3600 seconds (1 hour)
 - Each successful call resets the idle timer
 
+#### Session management API
+
+Manage sessions directly without running a task:
+
+```typescript
+// Inspect a session
+const info = await client.sessions.get(sessionId);
+console.log(info.status, info.expires_at, info.call_count);
+
+// List active sessions
+const sessions = await client.sessions.list();
+
+// Extend idle timeout without a task call (sliding window)
+await client.sessions.keepalive(sessionId);
+
+// Release the worker immediately
+await client.sessions.end(sessionId);
+```
+
+#### Session errors
+
+```typescript
+import {
+  SessionNotFoundError,
+  SessionExpiredError,
+  SessionEndedError,
+} from '@inferencesh/sdk';
+
+try {
+  await client.tasks.run({
+    app: 'my-stateful-app',
+    input: { prompt: 'hello' },
+    session: sessionId,
+  });
+} catch (error) {
+  if (
+    error instanceof SessionNotFoundError ||
+    error instanceof SessionExpiredError ||
+    error instanceof SessionEndedError
+  ) {
+    // Start a new session and retry
+    const result = await client.tasks.run({
+      app: 'my-stateful-app',
+      input: { prompt: 'hello' },
+      session: 'new',
+    });
+  } else {
+    throw error;
+  }
+}
+```
+
 For complete session documentation including error handling, best practices, and advanced patterns, see the [Sessions Developer Guide](https://inference.sh/docs/extend/sessions).
 
 ## Agent Chat
@@ -240,27 +317,111 @@ import { inference, tool, string } from '@inferencesh/sdk';
 
 const client = inference({ apiKey: 'your-api-key' });
 
-// Create ad-hoc agent
+// Create ad-hoc agent (config uses API field names: core_app, system_prompt)
+const weatherTool = tool('get_weather')
+  .describe('Get current weather')
+  .param('city', string('City name'))
+  .build();
+
 const agent = client.agents.create({
-  coreApp: 'infsh/claude-sonnet-4@abc123',  // LLM to use
-  systemPrompt: 'You are a helpful assistant.',
-  tools: [
-    tool('get_weather')
-      .description('Get current weather')
-      .params({ city: string('City name') })
-      .handler(async (args) => {
-        // Your tool logic here
-        return JSON.stringify({ temp: 72, conditions: 'sunny' });
-      })
-      .build()
-  ]
+  core_app: { ref: 'infsh/claude-sonnet-4@abc123' },
+  system_prompt: 'You are a helpful assistant.',
+  tools: [weatherTool], // only schemas are sent to the API; handlers stay client-side
 });
 
 await agent.sendMessage('What is the weather in Paris?', {
   onMessage: (msg) => console.log(msg),
   onToolCall: async (call) => {
-    // Tool handlers are auto-executed if defined
-  }
+    const result = await runMyClientTool(call.name, call.args);
+    await agent.submitToolResult(call.id, result);
+  },
+});
+```
+
+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:
+
+```typescript
+const uploaded = await client.files.upload(imageBlob, {
+  filename: 'photo.png',
+  contentType: 'image/png',
+});
+
+await agent.sendMessage('Describe this image', {
+  files: [imageBlob, uploaded], // Blob uploads; FileDTO reuses uri
+  onMessage: (msg) => console.log(msg),
 });
 ```
 
@@ -283,21 +444,23 @@ const agent = client.agents.create({
   internal_tools: { finish: true },
 });
 
-const response = await agent.sendMessage('Analyze: Great product!');
+const output = await agent.run('Analyze: Great product!');
 ```
 
+`agent.run()` sends a message with polling (no SSE), waits until the chat is idle, and returns `chat.output` (parsed finish-tool result, or `null` if none).
+
 ### Agent Methods
 
 | Method | Description |
 |--------|-------------|
-| `sendMessage(text, options?)` | Send a message to the agent |
-| `getChat(chatId?)` | Get chat history |
-| `stopChat(chatId?)` | Stop current generation |
-| `submitToolResult(toolId, resultOrAction)` | Submit result for a client tool (string or {action, form_data}) |
-| `streamMessages(chatId?, options?)` | Stream message updates |
-| `streamChat(chatId?, options?)` | Stream chat updates |
-| `disconnect()` | Clean up streams |
-| `reset()` | Start a new conversation |
+| `sendMessage(text, options?)` | Send a message; streams or polls until idle when callbacks or `stream: false` |
+| `run(text, options?)` | Send and return structured `chat.output` (always uses polling) |
+| `getChat(chatId?)` | Get the current or specified chat (`chat_messages` on the returned chat) |
+| `stopChat()` | Stop generation for the current chat (no-op if no active chat) |
+| `submitToolResult(toolId, resultOrAction)` | Submit result for a client tool (string or `{action, form_data}`) |
+| `startStreaming(options?)` | Manually attach to `/chats/{id}/stream` for the current chat |
+| `disconnect()` | Stop active stream/poll connections |
+| `reset()` | Disconnect and clear chat state so the next message starts a new chat |
 
 ## API Reference
 
@@ -309,6 +472,9 @@ Creates a new inference client.
 |-----------|------|----------|-------------|
 | `config.apiKey` | `string` | Yes | Your inference.sh API key |
 | `config.baseUrl` | `string` | No | Custom API URL (default: `https://api.inference.sh`) |
+| `config.stream` | `boolean` | No | Use NDJSON streaming (`true`, default) or status polling (`false`) |
+| `config.pollIntervalMs` | `number` | No | Poll interval when `stream: false` (default: `2000`) |
+| `config.proxyUrl` | `string` | No | Proxy base URL for frontend apps (keeps API keys server-side) |
 
 ### `client.tasks.run(params, options?)`
 
@@ -331,10 +497,11 @@ Runs a task on inference.sh.
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `wait` | `boolean` | `true` | Wait for task completion |
-| `onUpdate` | `function` | - | Callback for status updates |
-| `autoReconnect` | `boolean` | `true` | Auto-reconnect on connection loss |
-| `maxReconnects` | `number` | `5` | Max reconnection attempts |
-| `reconnectDelayMs` | `number` | `1000` | Delay between reconnects (ms) |
+| `stream` | `boolean` | client default | Use NDJSON streaming or status polling |
+| `pollIntervalMs` | `number` | client default | Poll interval when `stream: false` |
+| `onUpdate` | `function` | - | Callback for task updates (full fetch on status change when polling) |
+| `onPartialUpdate` | `function` | - | Callback for partial NDJSON stream updates `(task, fields)` |
+| `maxReconnects` | `number` | `5` | Max poll retries when `stream: false` |
 
 ### `client.tasks.get(taskId)`
 
@@ -357,9 +524,11 @@ Uploads a file to inference.sh.
 | `options.contentType` | `string` | MIME type |
 | `options.public` | `boolean` | Make file publicly accessible |
 
-### `client.agents.create(templateOrConfig)`
+### `client.agents.create(templateOrConfig)` / `client.agent(...)`
 
-Creates an agent instance from a template or ad-hoc configuration.
+Creates an agent instance from a template or ad-hoc configuration. `client.agent(...)` is an alias for `client.agents.create(...)`.
+
+**`sendMessage` options:** `onMessage`, `onChat`, `onToolCall`, `files`, `stream`, `pollIntervalMs`. Client tools with status `awaiting_input` are dispatched once per invocation ID via `onToolCall`.
 
 **Template mode:**
 ```typescript
@@ -369,12 +538,21 @@ const agent = client.agents.create('namespace/name@version');
 **Ad-hoc mode:**
 ```typescript
 const agent = client.agents.create({
-  coreApp: 'infsh/claude-sonnet-4@abc123',
-  systemPrompt: 'You are helpful.',
-  tools: [...]
+  core_app: { ref: 'infsh/claude-sonnet-4@abc123' },
+  system_prompt: 'You are helpful.',
+  tools: [...],
 });
 ```
 
+### `client.sessions`
+
+| Method | HTTP | Description |
+|--------|------|-------------|
+| `get(sessionId)` | `GET /sessions/{id}` | Session metadata (`status`, `expires_at`, `call_count`, …) |
+| `list()` | `GET /sessions` | All sessions (empty array if none) |
+| `keepalive(sessionId)` | `POST /sessions/{id}/keepalive` | Reset idle expiration |
+| `end(sessionId)` | `DELETE /sessions/{id}` | End session and release worker |
+
 ## Task Status Constants
 
 ```typescript
@@ -391,12 +569,103 @@ if (task.status === TaskStatusCompleted) {
 }
 ```
 
+## Integration Constants
+
+`IntegrationDTO` fields (`provider`, `type`, `auth`, `status`) use typed string unions exported as constants:
+
+```typescript
+import type { IntegrationDTO } from '@inferencesh/sdk';
+import {
+  IntegrationProviderGoogle,
+  IntegrationAuthTypeOAuth,
+  IntegrationStatusConnected,
+  IntegrationStatusDisconnected,
+  IntegrationStatusExpired,
+  IntegrationStatusError,
+  isRequirementsNotMetException,
+} from '@inferencesh/sdk';
+
+function isGoogleConnected(integration: IntegrationDTO): boolean {
+  return (
+    integration.provider === IntegrationProviderGoogle &&
+    integration.status === IntegrationStatusConnected
+  );
+}
+
+// HTTP 412 when an app requires a missing secret, integration, or scope
+try {
+  await client.run({ app: 'my-app', input: {} });
+} catch (error) {
+  if (isRequirementsNotMetException(error)) {
+    for (const req of error.errors) {
+      if (req.type === 'integration' && req.action?.provider === IntegrationProviderGoogle) {
+        // User must connect Google — see https://inference.sh/docs/extend/integrations
+      }
+    }
+  }
+}
+```
+
+| Constant group | Values |
+|----------------|--------|
+| `IntegrationProvider*` | `google`, `slack`, `notion`, `github`, `x`, `microsoft`, `salesforce`, `discord`, `gcp`, `mcp`, `reddit` |
+| `IntegrationAuthType*` | `service_account`, `oauth`, `api_key`, `wif`, `mcp` |
+| `IntegrationStatus*` | `connected`, `disconnected`, `expired`, `error` |
+
+## Instance Status Constants
+
+Use when working with engine instance APIs (`InstanceDTO.status`):
+
+```typescript
+import {
+  InstanceStatusCreating,
+  InstanceStatusPendingProvider,
+  InstanceStatusPending,
+  InstanceStatusActive,
+  InstanceStatusError,
+  InstanceStatusDeleting,
+  InstanceStatusDeleted,
+} from '@inferencesh/sdk';
+```
+
+## Tool Parameter Types
+
+When building `AgentTool` schemas manually (outside the tool builder), use `ToolParamType*` for JSON Schema `type` fields:
+
+```typescript
+import {
+  ToolParamTypeObject,
+  ToolParamTypeString,
+  ToolParamTypeInteger,
+  ToolParamTypeNumber,
+  ToolParamTypeBoolean,
+  ToolParamTypeArray,
+  ToolParamTypeNull,
+} from '@inferencesh/sdk';
+
+const schema = {
+  type: ToolParamTypeObject,
+  properties: {
+    city: { type: ToolParamTypeString, description: 'City name' },
+  },
+  required: ['city'],
+};
+```
+
+The fluent tool builder (`string()`, `number()`, `object()`, …) infers these types automatically.
+
 ## TypeScript Support
 
 This SDK is written in TypeScript and includes full type definitions. All types are exported:
 
 ```typescript
-import type { Task, ApiTaskRequest, RunOptions } from '@inferencesh/sdk';
+import type {
+  Task,
+  ApiAppRunRequest,
+  RunOptions,
+  IntegrationDTO,
+  AgentTool,
+} from '@inferencesh/sdk';
 ```
 
 ## Requirements

package/dist/agent/actions.test.d.ts

@@ -0,0 +1 @@
+export {};