@meistrari/agent-sdk 0.3.0 → 0.4.0

package/README.md

@@ -93,6 +93,83 @@ Multi-turn lifecycle rules:
 - Treat `completed`, `failed`, and `cancelled` as non-normal follow-up states in SDK consumers.
 - The SDK v4 path does not use the legacy `/v3/sessions/{sessionId}/continue` endpoint.
 
+### Cancel a running session
+
+```ts
+const cancellation = await client.cancelSession(sessionId)
+
+if (cancellation.success)
+    console.log(cancellation.message) // 'Message cancelled'
+else
+    console.error(cancellation.error)
+```
+
+`cancelSession` aborts the active turn (the model stops generating, ending token spend)
+and restores the session to a continuable state: `waiting_messages` for multi-turn
+sessions, `cancelled` for single-shot runs. A session that is not currently `running`
+rejects with a `FetchError` (HTTP 409); branch on it with `isFetchError`.
+
+### Register session webhooks
+
+Pass `webhooks` to `executeAgent` to receive lifecycle callbacks instead of polling.
+Each entry takes an HTTPS `url`, an optional `events` filter, and an optional HMAC
+`secret`:
+
+```ts
+import type { SessionWebhookEventPayload } from '@meistrari/agent-sdk'
+
+const { success, sessionId } = await client.executeAgent({
+    organizationName: 'acme',
+    repository: 'support-bot',
+    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',
+    }],
+})
+```
+
+Webhook semantics (full contract in [`docs/webhooks.md`](../../docs/webhooks.md)):
+
+- Available on the v4 execute path only; up to **5 webhooks** per session.
+- URLs must be HTTPS; localhost, `.local`/`.internal`, and private/loopback IP hosts are rejected.
+- `events` defaults to **all `session.*` events** (`started`, `completed`, `failed`,
+  `cancelled`, `waiting_messages`); `subagent.started`/`subagent.completed` must be opted into.
+- Passing `webhooks` on a continuation **replaces** the registered set; omitting it keeps
+  the existing registration.
+- Deliveries are **at-least-once** with retries — make handlers idempotent.
+- The payload (`SessionWebhookEventPayload`) is lightweight metadata: `eventType`,
+  `sessionId`, `runId`, `status`, `error`, `usage`, `subagent`, `deliveryId`. Fetch content
+  with `streamSession` or `fetchTimeline`.
+
+When a `secret` is configured, verify the `x-tela-agent-webhook-signature` header with the bundled
+helper (Web Crypto, works in Node/Bun/edge runtimes):
+
+```ts
+import { verifyWebhookSignature } from '@meistrari/agent-sdk'
+
+app.post('/hooks/agent-session', async (req) => {
+    const rawBody = await req.text()
+    const valid = await verifyWebhookSignature(
+        rawBody,
+        req.headers.get('x-tela-agent-webhook-signature'),
+        process.env.WEBHOOK_SECRET!,
+    )
+    if (!valid)
+        return new Response('invalid signature', { status: 401 })
+
+    const event = JSON.parse(rawBody) as SessionWebhookEventPayload
+    // ...
+    return new Response('ok')
+})
+```
+
+For [Trigger.dev wait-for-token](../../docs/trigger-dev-wait-token.md) flows, pass the
+token's callback URL as a webhook filtered to terminal events — no `secret` needed (auth
+is embedded in the token URL), and the waiting task resumes with the payload as the token
+output.
+
 ### Update an agent model
 
 ```ts
@@ -102,7 +179,12 @@ const update = await client.updateAgentModel({
     commitMessage: 'Switch support bot model',
 })
 
-console.log(update.commitHash)
+if (update.success) {
+    console.log(update.commitHash)
+}
+else {
+    console.error(update.error)
+}
 ```
 
 `updateAgentModel` writes `agent.config.json` on the main branch and lets agent-api
@@ -142,7 +224,8 @@ This package mirrors `@meistrari/vault-sdk` and is published as `UNLICENSED`.
 
 ## Scope
 
-Focused on sandbox execution and the public v4 consumer paths: `executeAgent`,
-`streamSession`, `updateAgentModel`, `fetchTimeline`, and `resolveReference`. Agent CRUD,
-legacy polling, and the internal sandbox timeline callback are intentionally out of
-scope.
+Focused on sandbox execution and the public v4 consumer paths: `executeAgent` (including
+session webhook registration), `streamSession`, `cancelSession`, `updateAgentModel`,
+`fetchTimeline`, `resolveReference`, and webhook signature verification via
+`verifyWebhookSignature`. Agent CRUD, legacy polling, and the internal sandbox timeline
+callback are intentionally out of scope.

package/dist/index.cjs

@@ -231,6 +231,14 @@ function agentClient(config) {
     });
     return schemas.sessionTimelineResponseSchema.parse(await response.json());
   }
+  async function cancelSession(sessionId) {
+    const parsedSessionId = schemas.sessionTimelineIdSchema.parse(sessionId);
+    const response = await request({
+      method: "POST",
+      path: `/v4/sessions/${encodeURIComponent(parsedSessionId)}/cancel`
+    });
+    return schemas.cancelSessionResponseSchema.parse(await response.json());
+  }
   async function streamSession(sessionId, options) {
     const response = await request({
       method: "GET",
@@ -267,7 +275,49 @@ function agentClient(config) {
       return JSON.parse(await vaultFile.content.text());
     return vaultFile.content.arrayBuffer();
   }
-  return { executeAgent, updateAgentModel, fetchTimeline, streamSession, resolveReference };
+  return { executeAgent, updateAgentModel, fetchTimeline, cancelSession, streamSession, resolveReference };
+}
+
+const SIGNATURE_PREFIX = "sha256=";
+function toBytes(rawBody) {
+  if (typeof rawBody === "string") {
+    return new TextEncoder().encode(rawBody);
+  }
+  const copy = new Uint8Array(rawBody.byteLength);
+  copy.set(rawBody);
+  return copy;
+}
+function toHex(buffer) {
+  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqualStrings(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let index = 0; index < a.length; index++) {
+    mismatch |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return mismatch === 0;
+}
+async function verifyWebhookSignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader || !signatureHeader.startsWith(SIGNATURE_PREFIX) || !secret) {
+    return false;
+  }
+  try {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const digest = await crypto.subtle.sign("HMAC", key, toBytes(rawBody));
+    const expected = `${SIGNATURE_PREFIX}${toHex(digest)}`;
+    return timingSafeEqualStrings(signatureHeader, expected);
+  } catch {
+    return false;
+  }
 }
 
 exports.APIKeyAuthStrategy = APIKeyAuthStrategy;
@@ -278,3 +328,4 @@ exports.agentClient = agentClient;
 exports.isFetchError = isFetchError;
 exports.isNetworkError = isNetworkError;
 exports.parseSessionStream = parseSessionStream;
+exports.verifyWebhookSignature = verifyWebhookSignature;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { E as ExecuteAgentRequest, a as ExecuteAgentResponse, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, S as SessionTimelineResponse, c as SessionStreamEvent } from './shared/agent-sdk.4ad2c746.cjs';
-export { A as AgentInput, d as SessionStatus, T as TimelineEvent, e as TimelineMetrics, f as TimelinePrompt, g as TimelineRunTurnMetrics, h as TimelineSpan, i as TimelineToolResult } from './shared/agent-sdk.4ad2c746.cjs';
+import { E as ExecuteAgentRequest, a as ExecuteAgentResponse, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, S as SessionTimelineResponse, C as CancelSessionResponse, c as SessionStreamEvent } from './shared/agent-sdk.dc5630ec.cjs';
+export { A as AgentInput, d as SessionStatus, e as SessionWebhookConfig, f as SessionWebhookEventPayload, g as SessionWebhookEventType, h as SessionWebhookSubagent, i as SessionWebhookUsage, T as TimelineEvent, j as TimelineMetrics, k as TimelinePrompt, l as TimelineRunTurnMetrics, m as TimelineSpan, n as TimelineToolResult } from './shared/agent-sdk.dc5630ec.cjs';
 import 'zod';
 
 interface AuthStrategy {
@@ -38,6 +38,7 @@ declare function agentClient(config: AgentClientConfig): {
     executeAgent: (input: ExecuteAgentRequest) => Promise<ExecuteAgentResponse>;
     updateAgentModel: (input: UpdateAgentModelRequest) => Promise<UpdateAgentModelResponse>;
     fetchTimeline: (sessionId: string, options?: FetchTimelineOptions) => Promise<SessionTimelineResponse>;
+    cancelSession: (sessionId: string) => Promise<CancelSessionResponse>;
     streamSession: (sessionId: string, options?: StreamSessionOptions) => Promise<AsyncIterable<SessionStreamEvent>>;
     resolveReference: {
         (reference: string, options?: {
@@ -78,5 +79,7 @@ declare function isNetworkError(error: unknown): error is NetworkError;
 
 declare function parseSessionStream(stream: ReadableStream<Uint8Array>): AsyncIterable<SessionStreamEvent>;
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, FetchError, NetworkError, SessionStreamEvent, SessionTimelineResponse, UpdateAgentModelRequest, UpdateAgentModelResponse, agentClient, isFetchError, isNetworkError, parseSessionStream };
+declare function verifyWebhookSignature(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+
+export { APIKeyAuthStrategy, CancelSessionResponse, DataTokenAuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, FetchError, NetworkError, SessionStreamEvent, SessionTimelineResponse, UpdateAgentModelRequest, UpdateAgentModelResponse, agentClient, isFetchError, isNetworkError, parseSessionStream, verifyWebhookSignature };
 export type { AgentClient, AgentClientConfig, AgentRequestError, AuthStrategy, FetchTimelineOptions, ResolveReferenceAs, ResolveReferenceOptions, StreamSessionOptions };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { E as ExecuteAgentRequest, a as ExecuteAgentResponse, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, S as SessionTimelineResponse, c as SessionStreamEvent } from './shared/agent-sdk.4ad2c746.mjs';
-export { A as AgentInput, d as SessionStatus, T as TimelineEvent, e as TimelineMetrics, f as TimelinePrompt, g as TimelineRunTurnMetrics, h as TimelineSpan, i as TimelineToolResult } from './shared/agent-sdk.4ad2c746.mjs';
+import { E as ExecuteAgentRequest, a as ExecuteAgentResponse, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, S as SessionTimelineResponse, C as CancelSessionResponse, c as SessionStreamEvent } from './shared/agent-sdk.dc5630ec.mjs';
+export { A as AgentInput, d as SessionStatus, e as SessionWebhookConfig, f as SessionWebhookEventPayload, g as SessionWebhookEventType, h as SessionWebhookSubagent, i as SessionWebhookUsage, T as TimelineEvent, j as TimelineMetrics, k as TimelinePrompt, l as TimelineRunTurnMetrics, m as TimelineSpan, n as TimelineToolResult } from './shared/agent-sdk.dc5630ec.mjs';
 import 'zod';
 
 interface AuthStrategy {
@@ -38,6 +38,7 @@ declare function agentClient(config: AgentClientConfig): {
     executeAgent: (input: ExecuteAgentRequest) => Promise<ExecuteAgentResponse>;
     updateAgentModel: (input: UpdateAgentModelRequest) => Promise<UpdateAgentModelResponse>;
     fetchTimeline: (sessionId: string, options?: FetchTimelineOptions) => Promise<SessionTimelineResponse>;
+    cancelSession: (sessionId: string) => Promise<CancelSessionResponse>;
     streamSession: (sessionId: string, options?: StreamSessionOptions) => Promise<AsyncIterable<SessionStreamEvent>>;
     resolveReference: {
         (reference: string, options?: {
@@ -78,5 +79,7 @@ declare function isNetworkError(error: unknown): error is NetworkError;
 
 declare function parseSessionStream(stream: ReadableStream<Uint8Array>): AsyncIterable<SessionStreamEvent>;
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, FetchError, NetworkError, SessionStreamEvent, SessionTimelineResponse, UpdateAgentModelRequest, UpdateAgentModelResponse, agentClient, isFetchError, isNetworkError, parseSessionStream };
+declare function verifyWebhookSignature(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+
+export { APIKeyAuthStrategy, CancelSessionResponse, DataTokenAuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, FetchError, NetworkError, SessionStreamEvent, SessionTimelineResponse, UpdateAgentModelRequest, UpdateAgentModelResponse, agentClient, isFetchError, isNetworkError, parseSessionStream, verifyWebhookSignature };
 export type { AgentClient, AgentClientConfig, AgentRequestError, AuthStrategy, FetchTimelineOptions, ResolveReferenceAs, ResolveReferenceOptions, StreamSessionOptions };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as ExecuteAgentRequest, a as ExecuteAgentResponse, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, S as SessionTimelineResponse, c as SessionStreamEvent } from './shared/agent-sdk.4ad2c746.js';
-export { A as AgentInput, d as SessionStatus, T as TimelineEvent, e as TimelineMetrics, f as TimelinePrompt, g as TimelineRunTurnMetrics, h as TimelineSpan, i as TimelineToolResult } from './shared/agent-sdk.4ad2c746.js';
+import { E as ExecuteAgentRequest, a as ExecuteAgentResponse, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, S as SessionTimelineResponse, C as CancelSessionResponse, c as SessionStreamEvent } from './shared/agent-sdk.dc5630ec.js';
+export { A as AgentInput, d as SessionStatus, e as SessionWebhookConfig, f as SessionWebhookEventPayload, g as SessionWebhookEventType, h as SessionWebhookSubagent, i as SessionWebhookUsage, T as TimelineEvent, j as TimelineMetrics, k as TimelinePrompt, l as TimelineRunTurnMetrics, m as TimelineSpan, n as TimelineToolResult } from './shared/agent-sdk.dc5630ec.js';
 import 'zod';
 
 interface AuthStrategy {
@@ -38,6 +38,7 @@ declare function agentClient(config: AgentClientConfig): {
     executeAgent: (input: ExecuteAgentRequest) => Promise<ExecuteAgentResponse>;
     updateAgentModel: (input: UpdateAgentModelRequest) => Promise<UpdateAgentModelResponse>;
     fetchTimeline: (sessionId: string, options?: FetchTimelineOptions) => Promise<SessionTimelineResponse>;
+    cancelSession: (sessionId: string) => Promise<CancelSessionResponse>;
     streamSession: (sessionId: string, options?: StreamSessionOptions) => Promise<AsyncIterable<SessionStreamEvent>>;
     resolveReference: {
         (reference: string, options?: {
@@ -78,5 +79,7 @@ declare function isNetworkError(error: unknown): error is NetworkError;
 
 declare function parseSessionStream(stream: ReadableStream<Uint8Array>): AsyncIterable<SessionStreamEvent>;
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, FetchError, NetworkError, SessionStreamEvent, SessionTimelineResponse, UpdateAgentModelRequest, UpdateAgentModelResponse, agentClient, isFetchError, isNetworkError, parseSessionStream };
+declare function verifyWebhookSignature(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+
+export { APIKeyAuthStrategy, CancelSessionResponse, DataTokenAuthStrategy, ExecuteAgentRequest, ExecuteAgentResponse, FetchError, NetworkError, SessionStreamEvent, SessionTimelineResponse, UpdateAgentModelRequest, UpdateAgentModelResponse, agentClient, isFetchError, isNetworkError, parseSessionStream, verifyWebhookSignature };
 export type { AgentClient, AgentClientConfig, AgentRequestError, AuthStrategy, FetchTimelineOptions, ResolveReferenceAs, ResolveReferenceOptions, StreamSessionOptions };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { VaultFile } from '@meistrari/vault-sdk';
-import { SESSION_STREAM_EVENT_KINDS, sessionStreamEventSchema, executeAgentRequestSchema, executeAgentResponseSchema, updateAgentModelRequestSchema, updateAgentModelResponseSchema, sessionTimelineIdSchema, sessionTimelineResponseSchema } from './schemas.mjs';
+import { SESSION_STREAM_EVENT_KINDS, sessionStreamEventSchema, executeAgentRequestSchema, executeAgentResponseSchema, updateAgentModelRequestSchema, updateAgentModelResponseSchema, sessionTimelineIdSchema, sessionTimelineResponseSchema, cancelSessionResponseSchema } from './schemas.mjs';
 import 'zod';
 
 var __defProp$1 = Object.defineProperty;
@@ -229,6 +229,14 @@ function agentClient(config) {
     });
     return sessionTimelineResponseSchema.parse(await response.json());
   }
+  async function cancelSession(sessionId) {
+    const parsedSessionId = sessionTimelineIdSchema.parse(sessionId);
+    const response = await request({
+      method: "POST",
+      path: `/v4/sessions/${encodeURIComponent(parsedSessionId)}/cancel`
+    });
+    return cancelSessionResponseSchema.parse(await response.json());
+  }
   async function streamSession(sessionId, options) {
     const response = await request({
       method: "GET",
@@ -265,7 +273,49 @@ function agentClient(config) {
       return JSON.parse(await vaultFile.content.text());
     return vaultFile.content.arrayBuffer();
   }
-  return { executeAgent, updateAgentModel, fetchTimeline, streamSession, resolveReference };
+  return { executeAgent, updateAgentModel, fetchTimeline, cancelSession, streamSession, resolveReference };
+}
+
+const SIGNATURE_PREFIX = "sha256=";
+function toBytes(rawBody) {
+  if (typeof rawBody === "string") {
+    return new TextEncoder().encode(rawBody);
+  }
+  const copy = new Uint8Array(rawBody.byteLength);
+  copy.set(rawBody);
+  return copy;
+}
+function toHex(buffer) {
+  return Array.from(new Uint8Array(buffer), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function timingSafeEqualStrings(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let index = 0; index < a.length; index++) {
+    mismatch |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return mismatch === 0;
+}
+async function verifyWebhookSignature(rawBody, signatureHeader, secret) {
+  if (!signatureHeader || !signatureHeader.startsWith(SIGNATURE_PREFIX) || !secret) {
+    return false;
+  }
+  try {
+    const key = await crypto.subtle.importKey(
+      "raw",
+      new TextEncoder().encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const digest = await crypto.subtle.sign("HMAC", key, toBytes(rawBody));
+    const expected = `${SIGNATURE_PREFIX}${toHex(digest)}`;
+    return timingSafeEqualStrings(signatureHeader, expected);
+  } catch {
+    return false;
+  }
 }
 
-export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, NetworkError, agentClient, isFetchError, isNetworkError, parseSessionStream };
+export { APIKeyAuthStrategy, DataTokenAuthStrategy, FetchError, NetworkError, agentClient, isFetchError, isNetworkError, parseSessionStream, verifyWebhookSignature };

package/dist/schemas.cjs

@@ -430,6 +430,7 @@ const nativeAnthropicModelIds = [
   "claude-sonnet-4-5",
   "claude-sonnet-4-6",
   "claude-haiku-4-5",
+  "claude-fable-5",
   "claude-opus-4-6",
   "claude-opus-4-7",
   "claude-opus-4-8"
@@ -442,6 +443,118 @@ const modelSchema = zod.z.enum([
   ...openrouterModelIds
 ]);
 
+const sessionWebhookEventTypeSchema = zod.z.enum([
+  "session.started",
+  "session.completed",
+  "session.failed",
+  "session.cancelled",
+  "session.waiting_messages",
+  "subagent.started",
+  "subagent.completed"
+]);
+const SESSION_WEBHOOK_DEFAULT_EVENTS = [
+  "session.started",
+  "session.completed",
+  "session.failed",
+  "session.cancelled",
+  "session.waiting_messages"
+];
+const BLOCKED_HOSTNAME_SUFFIXES = [".localhost", ".local", ".internal"];
+const BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "metadata.google.internal"]);
+function isPrivateIpv4(hostname) {
+  const match = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!match) {
+    return false;
+  }
+  const octets = match.slice(1).map(Number);
+  if (octets.some((octet) => octet > 255)) {
+    return true;
+  }
+  const a = octets[0] ?? 0;
+  const b = octets[1] ?? 0;
+  return a === 0 || a === 10 || a === 127 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168;
+}
+function isPrivateIpv6(hostname) {
+  const normalized = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  if (!normalized.includes(":")) {
+    return false;
+  }
+  return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb") || normalized.startsWith("::ffff:");
+}
+function isBlockedWebhookHostname(hostname) {
+  const normalized = hostname.toLowerCase();
+  if (BLOCKED_HOSTNAMES.has(normalized)) {
+    return true;
+  }
+  if (BLOCKED_HOSTNAME_SUFFIXES.some((suffix) => normalized.endsWith(suffix))) {
+    return true;
+  }
+  return isPrivateIpv4(normalized) || isPrivateIpv6(normalized);
+}
+function validateWebhookUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return "Webhook URL is invalid";
+  }
+  if (parsed.protocol !== "https:") {
+    return "Webhook URLs must use https";
+  }
+  if (isBlockedWebhookHostname(parsed.hostname)) {
+    return "Webhook URL host is not allowed";
+  }
+  return null;
+}
+const sessionWebhookConfigSchema = zod.z.object({
+  url: zod.z.string().max(2048).superRefine((value, ctx) => {
+    const error = validateWebhookUrl(value);
+    if (error) {
+      ctx.addIssue({ code: "custom", message: error });
+    }
+  }).describe("HTTPS endpoint that receives lifecycle event POSTs (e.g. a Trigger.dev wait-token URL)"),
+  events: zod.z.array(sessionWebhookEventTypeSchema).min(1).optional().describe("Event filter; defaults to all session.* events (subagent.* events must be opted into)"),
+  secret: zod.z.string().min(8).max(256).optional().describe("Optional HMAC-SHA256 signing secret used for the x-tela-agent-webhook-signature header")
+}).strict();
+const sessionWebhooksSchema = zod.z.array(sessionWebhookConfigSchema).max(5).describe("Webhook endpoints notified about session lifecycle and subagent events");
+const sessionWebhookUsageSchema = zod.z.object({
+  inputTokens: zod.z.number().int().nonnegative().optional(),
+  outputTokens: zod.z.number().int().nonnegative().optional(),
+  cacheReadInputTokens: zod.z.number().int().nonnegative().optional(),
+  cacheCreationInputTokens: zod.z.number().int().nonnegative().optional(),
+  totalCostUsd: zod.z.number().nullable().optional(),
+  durationMs: zod.z.number().int().nonnegative().optional(),
+  numTurns: zod.z.number().int().nonnegative().optional()
+}).strict();
+const sessionWebhookSubagentSchema = zod.z.object({
+  callId: zod.z.string().min(1).max(256),
+  subagentType: zod.z.string().max(256).optional(),
+  status: zod.z.enum(["success", "failed"]).optional(),
+  durationMs: zod.z.number().int().nonnegative().optional()
+}).strict();
+const sessionWebhookEventPayloadSchema = zod.z.object({
+  eventType: sessionWebhookEventTypeSchema,
+  sessionId: zod.z.string(),
+  workspaceId: zod.z.string().optional(),
+  runId: zod.z.string().optional(),
+  status: zod.z.string(),
+  error: zod.z.string().optional(),
+  usage: sessionWebhookUsageSchema.optional(),
+  subagent: sessionWebhookSubagentSchema.optional(),
+  timestamp: zod.z.string(),
+  apiVersion: zod.z.literal("v4"),
+  deliveryId: zod.z.string()
+});
+const sessionAgentEventSchema = zod.z.object({
+  type: zod.z.enum(["subagent.started", "subagent.completed"]),
+  callId: zod.z.string().min(1).max(256),
+  subagentType: zod.z.string().max(256).optional(),
+  status: zod.z.enum(["success", "failed"]).optional(),
+  durationMs: zod.z.number().int().nonnegative().optional(),
+  timestamp: zod.z.number().int().nonnegative()
+}).strict();
+const sessionAgentEventsSchema = zod.z.array(sessionAgentEventSchema).max(20);
+
 const vaultReferenceSchema = zod.z.string().regex(/^vault:\/\/\S+$/, "vaultRef must start with vault:// and cannot contain whitespace");
 const agentInputSchema = zod.z.object({
   vaultRef: vaultReferenceSchema,
@@ -456,7 +569,8 @@ const executeAgentRequestSchema = zod.z.object({
   message: zod.z.string().min(1).max(8e5).optional(),
   inputs: zod.z.array(agentInputSchema).optional(),
   environmentVariables: zod.z.record(zod.z.string(), zod.z.string()).optional(),
-  recover: zod.z.boolean().optional()
+  recover: zod.z.boolean().optional(),
+  webhooks: sessionWebhooksSchema.optional()
 }).strict().superRefine((data, ctx) => {
   if (!data.sessionId) {
     if (!data.organizationName) {
@@ -495,15 +609,15 @@ const updateAgentModelRequestSchema = zod.z.object({
 }).strict();
 const updateAgentModelSuccessResponseSchema = zod.z.object({
   success: zod.z.literal(true).describe("Whether the model update succeeded"),
-  organizationName: zod.z.string().optional().describe("Resolved Forgejo organization name"),
-  repository: zod.z.string().optional().describe("Forgejo repository name"),
-  branch: zod.z.string().optional().describe("Branch written to"),
-  commitHash: zod.z.string().optional().describe("Commit hash after update"),
-  model: modelSchema.optional().describe("Configured model after update"),
-  providerTemplate: zod.z.string().optional().describe("Provider template selected from the model prefix"),
-  templateSynced: zod.z.boolean().optional().describe("Whether managed template files were synchronized"),
-  files: zod.z.array(zod.z.string()).optional().describe("Files written by the update"),
-  deletedFiles: zod.z.array(zod.z.string()).optional().describe("Files deleted by the update")
+  organizationName: zod.z.string().describe("Resolved Forgejo organization name"),
+  repository: zod.z.string().describe("Forgejo repository name"),
+  branch: zod.z.string().describe("Branch written to"),
+  commitHash: zod.z.string().describe("Commit hash after update"),
+  model: modelSchema.describe("Configured model after update"),
+  providerTemplate: zod.z.string().describe("Provider template selected from the model prefix"),
+  templateSynced: zod.z.boolean().describe("Whether managed template files were synchronized"),
+  files: zod.z.array(zod.z.string()).describe("Files written by the update"),
+  deletedFiles: zod.z.array(zod.z.string()).describe("Files deleted by the update")
 });
 const updateAgentModelErrorResponseSchema = zod.z.object({
   success: zod.z.literal(false).describe("Whether the model update succeeded"),
@@ -637,22 +751,37 @@ const sessionStreamEventSchema = zod.z.discriminatedUnion("kind", [
   sessionErrorEventSchema
 ]);
 const SESSION_STREAM_EVENT_KINDS = /* @__PURE__ */ new Set(["status", "steps", "result", "timeline-finalize", "error"]);
+const cancelSessionResponseSchema = zod.z.discriminatedUnion("success", [
+  zod.z.object({ success: zod.z.literal(true), message: zod.z.string() }),
+  zod.z.object({ success: zod.z.literal(false), error: zod.z.string() })
+]);
 
 exports.SESSION_STREAM_EVENT_KINDS = SESSION_STREAM_EVENT_KINDS;
+exports.SESSION_WEBHOOK_DEFAULT_EVENTS = SESSION_WEBHOOK_DEFAULT_EVENTS;
 exports.agentInputSchema = agentInputSchema;
+exports.cancelSessionResponseSchema = cancelSessionResponseSchema;
 exports.executeAgentErrorResponseSchema = executeAgentErrorResponseSchema;
 exports.executeAgentRequestSchema = executeAgentRequestSchema;
 exports.executeAgentResponseSchema = executeAgentResponseSchema;
 exports.executeAgentSuccessResponseSchema = executeAgentSuccessResponseSchema;
+exports.isBlockedWebhookHostname = isBlockedWebhookHostname;
 exports.modelSchema = modelSchema;
 exports.nativeAnthropicModelIds = nativeAnthropicModelIds;
 exports.nativeModelSchema = nativeModelSchema;
 exports.openrouterModelCatalog = openrouterModelCatalog;
 exports.openrouterModelIds = openrouterModelIds;
+exports.sessionAgentEventSchema = sessionAgentEventSchema;
+exports.sessionAgentEventsSchema = sessionAgentEventsSchema;
 exports.sessionStatusSchema = sessionStatusSchema;
 exports.sessionStreamEventSchema = sessionStreamEventSchema;
 exports.sessionTimelineIdSchema = sessionTimelineIdSchema;
 exports.sessionTimelineResponseSchema = sessionTimelineResponseSchema;
+exports.sessionWebhookConfigSchema = sessionWebhookConfigSchema;
+exports.sessionWebhookEventPayloadSchema = sessionWebhookEventPayloadSchema;
+exports.sessionWebhookEventTypeSchema = sessionWebhookEventTypeSchema;
+exports.sessionWebhookSubagentSchema = sessionWebhookSubagentSchema;
+exports.sessionWebhookUsageSchema = sessionWebhookUsageSchema;
+exports.sessionWebhooksSchema = sessionWebhooksSchema;
 exports.timelineEventSchema = timelineEventSchema;
 exports.timelineMetricsSchema = timelineMetricsSchema;
 exports.timelinePromptSchema = timelinePromptSchema;
@@ -663,3 +792,4 @@ exports.updateAgentModelErrorResponseSchema = updateAgentModelErrorResponseSchem
 exports.updateAgentModelRequestSchema = updateAgentModelRequestSchema;
 exports.updateAgentModelResponseSchema = updateAgentModelResponseSchema;
 exports.updateAgentModelSuccessResponseSchema = updateAgentModelSuccessResponseSchema;
+exports.validateWebhookUrl = validateWebhookUrl;

package/dist/schemas.d.cts

@@ -1,13 +1,14 @@
-export { A as AgentInput, E as ExecuteAgentRequest, a as ExecuteAgentResponse, D as SESSION_STREAM_EVENT_KINDS, d as SessionStatus, c as SessionStreamEvent, S as SessionTimelineResponse, T as TimelineEvent, e as TimelineMetrics, f as TimelinePrompt, g as TimelineRunTurnMetrics, h as TimelineSpan, i as TimelineToolResult, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, j as agentInputSchema, m as executeAgentErrorResponseSchema, k as executeAgentRequestSchema, n as executeAgentResponseSchema, l as executeAgentSuccessResponseSchema, s as sessionStatusSchema, C as sessionStreamEventSchema, r as sessionTimelineIdSchema, B as sessionTimelineResponseSchema, y as timelineEventSchema, t as timelineMetricsSchema, v as timelinePromptSchema, x as timelineRunTurnMetricsSchema, z as timelineSpanSchema, w as timelineToolResultSchema, p as updateAgentModelErrorResponseSchema, u as updateAgentModelRequestSchema, q as updateAgentModelResponseSchema, o as updateAgentModelSuccessResponseSchema } from './shared/agent-sdk.4ad2c746.cjs';
+export { A as AgentInput, C as CancelSessionResponse, E as ExecuteAgentRequest, a as ExecuteAgentResponse, K as SESSION_STREAM_EVENT_KINDS, N as SESSION_WEBHOOK_DEFAULT_EVENTS, Z as SessionAgentEvent, d as SessionStatus, c as SessionStreamEvent, S as SessionTimelineResponse, e as SessionWebhookConfig, f as SessionWebhookEventPayload, g as SessionWebhookEventType, h as SessionWebhookSubagent, i as SessionWebhookUsage, T as TimelineEvent, j as TimelineMetrics, k as TimelinePrompt, l as TimelineRunTurnMetrics, m as TimelineSpan, n as TimelineToolResult, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, o as agentInputSchema, L as cancelSessionResponseSchema, r as executeAgentErrorResponseSchema, p as executeAgentRequestSchema, s as executeAgentResponseSchema, q as executeAgentSuccessResponseSchema, O as isBlockedWebhookHostname, Y as sessionAgentEventSchema, _ as sessionAgentEventsSchema, x as sessionStatusSchema, J as sessionStreamEventSchema, y as sessionTimelineIdSchema, I as sessionTimelineResponseSchema, Q as sessionWebhookConfigSchema, X as sessionWebhookEventPayloadSchema, M as sessionWebhookEventTypeSchema, W as sessionWebhookSubagentSchema, V as sessionWebhookUsageSchema, R as sessionWebhooksSchema, G as timelineEventSchema, z as timelineMetricsSchema, B as timelinePromptSchema, F as timelineRunTurnMetricsSchema, H as timelineSpanSchema, D as timelineToolResultSchema, v as updateAgentModelErrorResponseSchema, u as updateAgentModelRequestSchema, w as updateAgentModelResponseSchema, t as updateAgentModelSuccessResponseSchema, P as validateWebhookUrl } from './shared/agent-sdk.dc5630ec.cjs';
 import { z } from 'zod';
 
-declare const nativeAnthropicModelIds: readonly ["claude-sonnet-4-5", "claude-sonnet-4-6", "claude-haiku-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"];
+declare const nativeAnthropicModelIds: readonly ["claude-sonnet-4-5", "claude-sonnet-4-6", "claude-haiku-4-5", "claude-fable-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"];
 type NativeAnthropicModelId = typeof nativeAnthropicModelIds[number];
 type V3Provider = 'anthropic' | 'vertex-ai' | 'openrouter' | 'bedrock' | 'tela-claude-agent-gateway';
 declare const nativeModelSchema: z.ZodEnum<{
     "claude-sonnet-4-5": "claude-sonnet-4-5";
     "claude-sonnet-4-6": "claude-sonnet-4-6";
     "claude-haiku-4-5": "claude-haiku-4-5";
+    "claude-fable-5": "claude-fable-5";
     "claude-opus-4-6": "claude-opus-4-6";
     "claude-opus-4-7": "claude-opus-4-7";
     "claude-opus-4-8": "claude-opus-4-8";

package/dist/schemas.d.mts

@@ -1,13 +1,14 @@
-export { A as AgentInput, E as ExecuteAgentRequest, a as ExecuteAgentResponse, D as SESSION_STREAM_EVENT_KINDS, d as SessionStatus, c as SessionStreamEvent, S as SessionTimelineResponse, T as TimelineEvent, e as TimelineMetrics, f as TimelinePrompt, g as TimelineRunTurnMetrics, h as TimelineSpan, i as TimelineToolResult, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, j as agentInputSchema, m as executeAgentErrorResponseSchema, k as executeAgentRequestSchema, n as executeAgentResponseSchema, l as executeAgentSuccessResponseSchema, s as sessionStatusSchema, C as sessionStreamEventSchema, r as sessionTimelineIdSchema, B as sessionTimelineResponseSchema, y as timelineEventSchema, t as timelineMetricsSchema, v as timelinePromptSchema, x as timelineRunTurnMetricsSchema, z as timelineSpanSchema, w as timelineToolResultSchema, p as updateAgentModelErrorResponseSchema, u as updateAgentModelRequestSchema, q as updateAgentModelResponseSchema, o as updateAgentModelSuccessResponseSchema } from './shared/agent-sdk.4ad2c746.mjs';
+export { A as AgentInput, C as CancelSessionResponse, E as ExecuteAgentRequest, a as ExecuteAgentResponse, K as SESSION_STREAM_EVENT_KINDS, N as SESSION_WEBHOOK_DEFAULT_EVENTS, Z as SessionAgentEvent, d as SessionStatus, c as SessionStreamEvent, S as SessionTimelineResponse, e as SessionWebhookConfig, f as SessionWebhookEventPayload, g as SessionWebhookEventType, h as SessionWebhookSubagent, i as SessionWebhookUsage, T as TimelineEvent, j as TimelineMetrics, k as TimelinePrompt, l as TimelineRunTurnMetrics, m as TimelineSpan, n as TimelineToolResult, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, o as agentInputSchema, L as cancelSessionResponseSchema, r as executeAgentErrorResponseSchema, p as executeAgentRequestSchema, s as executeAgentResponseSchema, q as executeAgentSuccessResponseSchema, O as isBlockedWebhookHostname, Y as sessionAgentEventSchema, _ as sessionAgentEventsSchema, x as sessionStatusSchema, J as sessionStreamEventSchema, y as sessionTimelineIdSchema, I as sessionTimelineResponseSchema, Q as sessionWebhookConfigSchema, X as sessionWebhookEventPayloadSchema, M as sessionWebhookEventTypeSchema, W as sessionWebhookSubagentSchema, V as sessionWebhookUsageSchema, R as sessionWebhooksSchema, G as timelineEventSchema, z as timelineMetricsSchema, B as timelinePromptSchema, F as timelineRunTurnMetricsSchema, H as timelineSpanSchema, D as timelineToolResultSchema, v as updateAgentModelErrorResponseSchema, u as updateAgentModelRequestSchema, w as updateAgentModelResponseSchema, t as updateAgentModelSuccessResponseSchema, P as validateWebhookUrl } from './shared/agent-sdk.dc5630ec.mjs';
 import { z } from 'zod';
 
-declare const nativeAnthropicModelIds: readonly ["claude-sonnet-4-5", "claude-sonnet-4-6", "claude-haiku-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"];
+declare const nativeAnthropicModelIds: readonly ["claude-sonnet-4-5", "claude-sonnet-4-6", "claude-haiku-4-5", "claude-fable-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"];
 type NativeAnthropicModelId = typeof nativeAnthropicModelIds[number];
 type V3Provider = 'anthropic' | 'vertex-ai' | 'openrouter' | 'bedrock' | 'tela-claude-agent-gateway';
 declare const nativeModelSchema: z.ZodEnum<{
     "claude-sonnet-4-5": "claude-sonnet-4-5";
     "claude-sonnet-4-6": "claude-sonnet-4-6";
     "claude-haiku-4-5": "claude-haiku-4-5";
+    "claude-fable-5": "claude-fable-5";
     "claude-opus-4-6": "claude-opus-4-6";
     "claude-opus-4-7": "claude-opus-4-7";
     "claude-opus-4-8": "claude-opus-4-8";

package/dist/schemas.d.ts

@@ -1,13 +1,14 @@
-export { A as AgentInput, E as ExecuteAgentRequest, a as ExecuteAgentResponse, D as SESSION_STREAM_EVENT_KINDS, d as SessionStatus, c as SessionStreamEvent, S as SessionTimelineResponse, T as TimelineEvent, e as TimelineMetrics, f as TimelinePrompt, g as TimelineRunTurnMetrics, h as TimelineSpan, i as TimelineToolResult, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, j as agentInputSchema, m as executeAgentErrorResponseSchema, k as executeAgentRequestSchema, n as executeAgentResponseSchema, l as executeAgentSuccessResponseSchema, s as sessionStatusSchema, C as sessionStreamEventSchema, r as sessionTimelineIdSchema, B as sessionTimelineResponseSchema, y as timelineEventSchema, t as timelineMetricsSchema, v as timelinePromptSchema, x as timelineRunTurnMetricsSchema, z as timelineSpanSchema, w as timelineToolResultSchema, p as updateAgentModelErrorResponseSchema, u as updateAgentModelRequestSchema, q as updateAgentModelResponseSchema, o as updateAgentModelSuccessResponseSchema } from './shared/agent-sdk.4ad2c746.js';
+export { A as AgentInput, C as CancelSessionResponse, E as ExecuteAgentRequest, a as ExecuteAgentResponse, K as SESSION_STREAM_EVENT_KINDS, N as SESSION_WEBHOOK_DEFAULT_EVENTS, Z as SessionAgentEvent, d as SessionStatus, c as SessionStreamEvent, S as SessionTimelineResponse, e as SessionWebhookConfig, f as SessionWebhookEventPayload, g as SessionWebhookEventType, h as SessionWebhookSubagent, i as SessionWebhookUsage, T as TimelineEvent, j as TimelineMetrics, k as TimelinePrompt, l as TimelineRunTurnMetrics, m as TimelineSpan, n as TimelineToolResult, U as UpdateAgentModelRequest, b as UpdateAgentModelResponse, o as agentInputSchema, L as cancelSessionResponseSchema, r as executeAgentErrorResponseSchema, p as executeAgentRequestSchema, s as executeAgentResponseSchema, q as executeAgentSuccessResponseSchema, O as isBlockedWebhookHostname, Y as sessionAgentEventSchema, _ as sessionAgentEventsSchema, x as sessionStatusSchema, J as sessionStreamEventSchema, y as sessionTimelineIdSchema, I as sessionTimelineResponseSchema, Q as sessionWebhookConfigSchema, X as sessionWebhookEventPayloadSchema, M as sessionWebhookEventTypeSchema, W as sessionWebhookSubagentSchema, V as sessionWebhookUsageSchema, R as sessionWebhooksSchema, G as timelineEventSchema, z as timelineMetricsSchema, B as timelinePromptSchema, F as timelineRunTurnMetricsSchema, H as timelineSpanSchema, D as timelineToolResultSchema, v as updateAgentModelErrorResponseSchema, u as updateAgentModelRequestSchema, w as updateAgentModelResponseSchema, t as updateAgentModelSuccessResponseSchema, P as validateWebhookUrl } from './shared/agent-sdk.dc5630ec.js';
 import { z } from 'zod';
 
-declare const nativeAnthropicModelIds: readonly ["claude-sonnet-4-5", "claude-sonnet-4-6", "claude-haiku-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"];
+declare const nativeAnthropicModelIds: readonly ["claude-sonnet-4-5", "claude-sonnet-4-6", "claude-haiku-4-5", "claude-fable-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"];
 type NativeAnthropicModelId = typeof nativeAnthropicModelIds[number];
 type V3Provider = 'anthropic' | 'vertex-ai' | 'openrouter' | 'bedrock' | 'tela-claude-agent-gateway';
 declare const nativeModelSchema: z.ZodEnum<{
     "claude-sonnet-4-5": "claude-sonnet-4-5";
     "claude-sonnet-4-6": "claude-sonnet-4-6";
     "claude-haiku-4-5": "claude-haiku-4-5";
+    "claude-fable-5": "claude-fable-5";
     "claude-opus-4-6": "claude-opus-4-6";
     "claude-opus-4-7": "claude-opus-4-7";
     "claude-opus-4-8": "claude-opus-4-8";