@meistrari/tela-sdk-js 2.13.0 → 2.13.2

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` runs agents through the Tela gateway (`run` → `POST /agent/:id/run`). Streaming, timeline, cancellation, and model updates are delegated to [`@meistrari/agent-sdk`](https://www.npmjs.com/package/@meistrari/agent-sdk). The SDK adds the Tela-specific bits: addressing agents by **`agentId`**, flattening a per-variable `inputs` map into the wire `inputSchema` array, uploading `TelaFile` inputs to the vault, and mapping your Tela credentials onto the agent-sdk auth strategy.
+
+> **Transport:** `run` posts to the Tela gateway and is authenticated by your SDK credentials. The delegated streaming/timeline/cancel calls use an agent-sdk client against `/v4/sessions`; 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.
+const started = await tela.agents.run({
+    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:
+`run` returns `{ success, sessionId }` — execution is async, so 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,74 @@ 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** — `inputs` is a map keyed by variable name. Each value is a single entry or an array of entries; an entry can be a `TelaFile` (uploaded to the vault automatically), a ready `vault://` reference, or a text entry — each optionally carrying `metadata`. The SDK flattens this into the wire `inputSchema` array, tagging every entry with its variable name.
 
 ```typescript
-await agent.execute({
-    prompt: 'Review this contract',
+await tela.agents.run({
+    agentId,
+    message: 'Review this contract against the references',
     inputs: {
-        document: tela.createFile(buffer, { name: 'contract.pdf', mimeType: 'application/pdf' }),
-        focus: 'liability clauses',
+        // a TelaFile — uploaded to the vault for you
+        contract: tela.createFile(buffer, { name: 'contract.pdf', mimeType: 'application/pdf' }),
+        // multiple entries for one variable; ready vault refs with metadata
+        references: [
+            { vaultRef: 'vault://...', filename: 'reference.txt', metadata: 'prior version' },
+        ],
+        // a text input
+        notes: { type: 'text', content: 'Focus on the indemnity clauses.' },
     },
-    attachments: [{ vaultRef: 'vault://...', filename: 'reference.txt' }],
-}).result
+    environmentVariables: { LOCALE: 'en-US' },
+})
 ```
 
-**Multi-turn** — continue the same session with another instruction:
+**Multi-turn** — continue an existing session by passing its `sessionId` alongside the `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.run({ agentId, sessionId, message: 'Now implement step 1' })
 ```
 
-**Cancel / recover** an in-flight or failed run:
+**Webhooks** — register session lifecycle callbacks by passing `webhooks` to `run`. The gateway forwards the webhook config to the agent execution service unchanged. Passing `webhooks` on a continuation replaces the session's registration; omitting it keeps the existing registration.
 
 ```typescript
-await execution.cancel() // aborts the stream and cancels server-side
-await execution.recover() // resume a failed/terminal session
+await tela.agents.run({
+    agentId,
+    message: 'Summarize the latest tickets',
+    webhooks: [{
+        url: 'https://example.com/hooks/agent-session',
+        events: ['session.completed', 'session.failed', 'session.cancelled'],
+        secret: 'whsec_a-long-random-string',
+    }],
+})
 ```
 
-**Resume / inspect** a session by id — useful for resumable workflows, dashboards, and background jobs:
+Webhook URLs must be HTTPS and publicly reachable. Up to five webhooks can be registered per session. Use `verifyWebhookSignature` to verify signed deliveries.
+
+**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`, `AgentRunWebhooks`, `SessionWebhookConfig`, …), `verifyWebhookSignature`, and `parseSessionStream` are re-exported from `@meistrari/tela-sdk-js` — the agent-sdk is the single source of truth for the session/streaming/webhook contract.
+
+**Migration note** — replace `tela.agents.executeAgent(...)` with `tela.agents.run(...)`. `agentId` is now required, `inputs` is keyed by variable name instead of a flat array, and `webhooks` moves unchanged onto `run`. The Tela gateway run path does not support agent-sdk `recover` requests; start or continue a session with `message` instead.
+
+```typescript
+await tela.agents.run({
+    agentId,
+    message,
+    inputs: {
+        document: tela.createFile(file, { name: 'document.pdf' }),
+    },
+    webhooks,
+})
+```
 
 ## Migration Guide from v1.x to v2