@meistrari/tela-sdk-js 2.12.0 → 2.13.1

package/README.md

@@ -19,6 +19,7 @@ The Tela SDK for JavaScript provides a simple and powerful way to interact with
   - [File Handling](#file-handling)
   - [Tasks API](#tasks-api)
   - [Vault API](#vault-api)
+  - [Agents API](#agents-api)
 - [Migration Guide from v1.x to v2](#migration-guide-from-v1x-to-v2)
   - [Breaking Changes](#breaking-changes)
   - [Migration Checklist](#migration-checklist)
@@ -715,6 +716,112 @@ const stream = await tela.vault.stream('vault://abc-123')
 
 This is particularly useful when reading task input files: `tela.tasks.getInputFiles(id)` returns the file references, and `tela.vault.download(file.url)` downloads them in one call.
 
+### Agents API
+
+`tela.agents` is a thin **pass-through wrapper** around [`@meistrari/agent-sdk`](https://www.npmjs.com/package/@meistrari/agent-sdk). Execution, streaming, timeline, cancellation, and model updates are delegated straight to the agent-sdk client; the SDK adds only the Tela-specific bits: addressing agents by **`agentId`** (resolved to the underlying `organizationName`/`repository`), uploading `TelaFile` inputs to the vault, and mapping your Tela credentials onto the agent-sdk auth strategy. Method names and shapes mirror the agent-sdk contract.
+
+> **Transport:** the wrapper builds an agent-sdk client that calls the `/v4/agents` and `/v4/sessions` endpoints. It defaults to your `baseURL`; set `agentBaseURL` when the v4 agent service lives at a different host:
+>
+> ```typescript
+> const tela = new TelaSDK({ apiKey: 'your-api-key', agentBaseURL: 'https://agents.example.com' })
+> ```
+
+```typescript
+const tela = new TelaSDK({ apiKey: 'your-api-key' })
+
+// Discover agents (Tela gateway)
+const agents = await tela.agents.list()
+
+// Start a session by agentId — resolved to org/repo under the hood.
+const started = await tela.agents.executeAgent({
+    agentId: agents[0].id,
+    message: 'Summarize the latest tickets',
+})
+if (!started.success)
+    throw new Error(started.error)
+
+const { sessionId } = started
+```
+
+`executeAgent` returns the agent-sdk `ExecuteAgentResponse` (`{ success: true, sessionId } | { success: false, error }`). Stream the session's events by id:
+
+```typescript
+for await (const event of await tela.agents.streamSession(sessionId)) {
+    switch (event.kind) {
+        case 'status':
+            console.log('status:', event.status)
+            break
+        case 'steps':
+            console.log('steps:', event.steps)
+            break
+        case 'result':
+            console.log('result:', event.result)
+            break
+        case 'error':
+            throw new Error(event.error)
+    }
+}
+
+// Timeline metrics (duration, token/cost) and cancellation, by session id:
+const timeline = await tela.agents.fetchTimeline(sessionId)
+await tela.agents.cancelSession(sessionId)
+```
+
+**Inputs** — pass file inputs as `TelaFile`s (uploaded to the vault automatically) or ready `vault://` references:
+
+```typescript
+await tela.agents.executeAgent({
+    agentId,
+    message: 'Review this contract',
+    inputs: [
+        tela.createFile(buffer, { name: 'contract.pdf', mimeType: 'application/pdf' }),
+        { vaultRef: 'vault://...', filename: 'reference.txt' },
+    ],
+})
+```
+
+**Multi-turn / recover** — continue or recover an existing session by `sessionId` (omit `agentId`):
+
+```typescript
+await tela.agents.executeAgent({ sessionId, message: 'Now implement step 1' }) // continue
+await tela.agents.executeAgent({ sessionId, recover: true }) // recover a failed/terminal session
+```
+
+**Webhooks** — register up to 5 HTTPS endpoints to receive session lifecycle callbacks instead of (or alongside) streaming. Passing `webhooks` on a continuation **replaces** the set.
+
+```typescript
+import { verifyWebhookSignature } from '@meistrari/tela-sdk-js'
+import type { SessionWebhookEventPayload } from '@meistrari/tela-sdk-js'
+
+await tela.agents.executeAgent({
+    agentId,
+    message: 'Audit the README for typos',
+    webhooks: [{
+        url: 'https://example.com/hooks/agent',
+        events: ['session.completed', 'session.failed'], // defaults to all session.* events
+        secret: 'whsec_…', // optional HMAC-SHA256 signing secret
+    }],
+})
+
+// On your endpoint, verify the signature before trusting the payload:
+const valid = await verifyWebhookSignature(
+    rawBody,
+    req.headers.get('x-tela-agent-webhook-signature'),
+    process.env.WEBHOOK_SECRET!,
+)
+if (!valid)
+    return res.status(401).end()
+const event = JSON.parse(rawBody) as SessionWebhookEventPayload
+```
+
+**Model updates** — set an agent's model by id:
+
+```typescript
+await tela.agents.updateAgentModel({ agentId, model: 'claude-opus-4-8', commitMessage: 'bump model' })
+```
+
+The contract types (`SessionStreamEvent`, `SessionTimelineResponse`, `SessionWebhookConfig`, …), `verifyWebhookSignature`, and `parseSessionStream` are re-exported from `@meistrari/tela-sdk-js` — the agent-sdk is the single source of truth.
+
 ## Migration Guide from v1.x to v2
 
 Version 2.0 of the Tela SDK introduces significant improvements to type safety, schema validation, and API design. This guide will help you migrate your code from v1.x to v2.