@meistrari/tela-sdk-js 2.13.0 → 2.13.1

package/README.md

@@ -718,27 +718,35 @@ This is particularly useful when reading task input files: `tela.tasks.getInputF
 
 ### Agents API
 
-The Agents API runs **agents** — an agent is a configured project (with its own instructions and skills) that executes a prompt asynchronously, streaming its steps until it produces a result. Agents run through the standard Tela API, so no extra configuration is needed: authentication and the vault are shared. Agents are identified by their **agentId**.
+`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, then get a handle by id (mirrors `tela.canvas.get`)
+// Discover agents (Tela gateway)
 const agents = await tela.agents.list()
-const agent = await tela.agents.get(agents[0].id)
 
-// Run the published agent and await the final result
-const result = await agent.execute({
-    prompt: 'Summarize the latest tickets',
-}).result
+// 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)
 
-console.log(result.content)
+const { sessionId } = started
 ```
 
-`execute()` runs the **published** version by default (pass `{ draft: true }` to run the current draft). It returns a promise-like handle — consume **either** `.result` **or** `.stream` (they share one underlying stream). Stream the session's events as they happen:
+`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 agent.execute({ prompt: 'Investigate the failing build' }).stream) {
+for await (const event of await tela.agents.streamSession(sessionId)) {
     switch (event.kind) {
         case 'status':
             console.log('status:', event.status)
@@ -753,59 +761,66 @@ for await (const event of agent.execute({ prompt: 'Investigate the failing build
             throw new Error(event.error)
     }
 }
-```
 
-Or subscribe to lifecycle events and read state:
-
-```typescript
-const execution = await agent.execute({ prompt: 'Refactor the auth module' })
-execution.on('status', status => console.log(status))
-execution.on('step', steps => console.log(steps))
-execution.on('result', result => console.log(result))
-execution.on('error', err => console.error(err))
-
-await execution.result
-console.log(execution.sessionId, execution.status)
+// Timeline metrics (duration, token/cost) and cancellation, by session id:
+const timeline = await tela.agents.fetchTimeline(sessionId)
+await tela.agents.cancelSession(sessionId)
 ```
 
-**Inputs & attachments** — provide values for the agent's declared inputs (keyed by name) plus ad-hoc file attachments:
+**Inputs** — pass file inputs as `TelaFile`s (uploaded to the vault automatically) or ready `vault://` references:
 
 ```typescript
-await agent.execute({
-    prompt: 'Review this contract',
-    inputs: {
-        document: tela.createFile(buffer, { name: 'contract.pdf', mimeType: 'application/pdf' }),
-        focus: 'liability clauses',
-    },
-    attachments: [{ vaultRef: 'vault://...', filename: 'reference.txt' }],
-}).result
+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** — continue the same session with another instruction:
+**Multi-turn / recover** — continue or recover an existing session by `sessionId` (omit `agentId`):
 
 ```typescript
-const execution = await agent.execute({ prompt: 'Draft a migration plan' })
-await execution.result
-await execution.continue({ prompt: 'Now implement step 1' }).result
+await tela.agents.executeAgent({ sessionId, message: 'Now implement step 1' }) // continue
+await tela.agents.executeAgent({ sessionId, recover: true }) // recover a failed/terminal session
 ```
 
-**Cancel / recover** an in-flight or failed run:
+**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
-await execution.cancel() // aborts the stream and cancels server-side
-await execution.recover() // resume a failed/terminal session
+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
 ```
 
-**Resume / inspect** a session by id — useful for resumable workflows, dashboards, and background jobs:
+**Model updates** — set an agent's model by id:
 
 ```typescript
-const execution = await tela.agents.getSession('session-uuid') // resumable: .stream / .result / .cancel / .recover
-const timeline = await tela.agents.getTimeline('session-uuid') // duration + token/cost metrics
-await tela.agents.cancel('session-uuid')
-await tela.agents.endSession('session-uuid')
+await tela.agents.updateAgentModel({ agentId, model: 'claude-opus-4-8', commitMessage: 'bump model' })
 ```
 
-`TelaFile` inputs and attachments are uploaded to the vault automatically. `execute()` defaults the prompt to `"Execute"` for input-driven agents, and `.result` resolves on `completed` **or** `waiting_messages` (check `.status` and `.continue()` from a paused turn).
+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