TypeScript

When an AI agent reaches an action that needs sign-off, it opens an interrupt - a request for a human decision. A teammate handles it in the inbox, and your code continues with the outcome. In between, a session streams the agent's conversation to Live View so operators can watch it as it happens. @vigilator/sdk is the official TypeScript SDK for both:

Installation

bun add @vigilator/sdk

Quick Start

import { Client } from "@vigilator/sdk";

const client = new Client({ apiKey: "your-api-key" });

const interrupt = await client.createInterrupt({
  title: "Send onboarding email",
  description: "The agent wants to email a new customer.",
  externalId: "run_42", // your own correlation id, e.g. the agent run
  actionRequests: [
    {
      name: "send_email",
      args: { to: "customer@example.com" },
      allowedDecisions: ["approve", "edit", "reject"],
    },
  ],
});

const result = await client.getInterrupt(interrupt.id);
if (result.answered) {
  for (const request of result.actionRequests) {
    console.log(request.name, request.decision, request.decidedByName);
  }
}

Prefer to start from a working agent? The examples wire this SDK into LangGraph.js and Mastra, with polling and webhook drivers.

Acting on decisions

Each decided action request tells you what the reviewer chose and everything you need to act on it:

Every decision also carries decidedByName and decidedAt, so your agent can log who made the call and when. The Decision object exported by the SDK holds the four values, so request.decision === Decision.edit and request.decision === "edit" are the same check.

Client behaviour

The client retries requests that fail with 429/502/503/504 or a connection error - 5 attempts with exponential backoff by default, honouring Retry-After, tunable via the constructor. Each attempt is subject to the timeout (5 seconds by default). There is nothing to close when you are done: the client holds no connection pool of its own.

Input that breaks the API contract - an empty session name, an empty message batch, more than 200 messages - throws a ValidationError before any request is sent.

Live View sessions

Interrupts capture the moments an agent stops to ask; a session covers everything in between. Register one when a run starts, stream the conversation as it progresses, and end it when the run completes - operators watch the transcript grow in Live View and can step in when something looks off. Sessions are standalone: they are not linked to interrupts, so you can monitor agents that never raise one.

const session = await client.startSession("billing-agent", {
  externalId: "thread_42",
  messages: [{ type: "human", content: "Refund order #42" }],
});

await client.appendSessionMessages(session.id, [
  {
    type: "ai",
    content: "Looking up order #42.",
    name: "billing-agent",
    toolCalls: [{ id: "call_1", name: "lookup_order", args: { id: "42" } }],
  },
  {
    type: "tool",
    content: '{"id": "42", "total": 129.0, "refundable": true}',
    name: "lookup_order",
    toolCallId: "call_1",
    toolStatus: "success",
  },
  { type: "ai", content: "Refund issued.", name: "billing-agent" },
]);

await client.endSession(session.id);

A session that goes quiet for longer than your organisation's session timeout is ended automatically, so a crashed agent never lingers in the queue. If your run may pause for long stretches - waiting on an interrupt, say - end the session before the pause and start a new one afterwards, or make sure the timeout in Integrations → Live View covers it.

Message format

Message mirrors LangChain's message types, with the field names in camelCase so a LangChain BaseMessage maps onto it one-to-one.

Send tool results as tool messages, not as ai messages with the JSON in content. The dashboard treats a tool message as evidence rather than speech: Live View folds it behind the chip of the call it answers with a tick or cross, and the inbox shows it monospaced under a Tool result badge. A tool message without a toolCallId, or a human / ai message carrying one, is rejected with a ValidationError before it is sent.

Session state

Each call returns the session as the API sees it:

Monitored time counts towards your organisation's agent hours, recorded when each session ends. Once a free organisation's monthly allowance is spent, startSession throws UsageLimitError until it resets.

Handling webhooks

Vigilator signs webhook deliveries (Svix / Standard Webhooks). WebhookHandler verifies the signature, parses the payload into a typed event, and dispatches it to registered callbacks. Create an endpoint in the dashboard under your organisation's integrations, copy its signing secret, and register callbacks for the events you care about:

import { WebhookHandler } from "@vigilator/sdk";

export const webhooks = new WebhookHandler({ secret: "whsec_..." }); // the endpoint's signing secret

webhooks.on("interrupt.answered", async (event) => {
  for (const request of event.data.actionRequests) {
    // act on approve / edit / reject / respond
  }
});

The callback's event parameter is typed from the event name you subscribe to, so event.data.actionRequests autocompletes. The handler is framework-agnostic - pass the raw request body and the request headers from any web framework:

import { WebhookVerificationError } from "@vigilator/sdk";
import { webhooks } from "@/lib/vigilator";

export async function POST(request: Request) {
  try {
    await webhooks.handle(await request.text(), request.headers);
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(null, { status: 401 });
    }
    throw error;
  }
  return new Response(null, { status: 204 });
}

Events

Every event shares the same envelope: type, timestamp (the moment the lifecycle edge happened, not the delivery time) and data, with the payload keys in camelCase exactly as documented. Event types newer than the installed SDK parse into UnknownEvent instead of throwing, so handlers keep working across SDK versions - and on accepts any event name, so you can subscribe to a newer type before upgrading.

The session events are how Live View talks back to your agent. SessionEndedEvent carries a reason ("agent", "timeout", "manual" or "limit" - also available on SessionEndReason), so you can tell a run that finished on its own from one a watcher disconnected, one that timed out, or one closed because the organisation's monitored hours ran out. SessionActionEvent carries the action name a watcher pressed - a custom action you defined - and triggeredBy, the member who pressed it; what the action means is up to your agent:

import { SessionEndReason } from "@vigilator/sdk";

webhooks.on("session.action", (event) => {
  if (event.data.action === "pause") {
    pauseRun(event.data.externalId); // your correlation id from startSession
  }
});

webhooks.on("session.ended", (event) => {
  if (event.data.reason === SessionEndReason.manual) {
    stopRun(event.data.externalId); // a watcher pulled the plug
  }
});

Return a 2xx quickly and offload slow work - failed deliveries are retried on a backoff schedule. Callbacks are awaited one after another, and an error thrown by one propagates out of handle. For local testing and delivery tooling, see the webhooks guide.

API Reference

Client

new Client(options: ClientOptions)

Every method returns a promise of the API's response and throws on failure.

createInterrupt(params)

Creates an interrupt and returns it as an Interrupt.

getInterrupt(interruptId)

Fetches a single interrupt by id as an Interrupt, including any decisions taken on its action requests.

startSession(name, options?)

Starts a live session and returns it as a Session.

appendSessionMessages(sessionId, messages)

Appends messages to a running session and returns it as a Session.

endSession(sessionId)

Ends a session and returns it as a Session. Ending an already-ended session is a no-op that returns the current state, so the call is safe to retry.

WebhookHandler

new WebhookHandler(options: WebhookHandlerOptions)

All three verification methods are async and take the raw body (a string, Uint8Array or ArrayBuffer) and the request headers (a Headers instance or a plain object, as Node, Express and Fastify hand them to you; names are matched case-insensitively).

on(eventType, callback)

Registers a callback for one event type and returns a function that removes it again. Callbacks receive the typed event and may be async. Unknown types are allowed, so callbacks can target event types newer than the installed SDK.

handle(body, headers)

Verifies a delivery, parses it, invokes the callbacks registered for its type (awaited one after another, in registration order), and resolves with the typed event.

constructEvent(body, headers)

Verifies a delivery and resolves with the typed event without dispatching - use this if you prefer routing events yourself.

verify(body, headers)

Verifies the signature only, without parsing the body.

All three reject with WebhookVerificationError on missing or malformed Svix headers, a timestamp outside the tolerance window, a signature mismatch, or a verified body that is not valid JSON.

Errors

All SDK errors extend VigilatorError, so a single instanceof check covers the whole SDK:

UsageLimitError through NotFoundError extend APIError, so error instanceof APIError catches them all.