@voicelayer/sdk 0.4.0 → 0.4.2

package/README.md

@@ -32,7 +32,9 @@ export default await defineAgent({
 node --import tsx agent.ts dev
 ```
 
-Call your LiveKit number. The agent answers. That's it. STT, LLM, TTS, VAD, turn detection — defaults are picked for you. Swap them later with one config line.
+The worker runs on **your** LiveKit project. Call a number you have connected to that project (a LiveKit SIP trunk plus a dispatch rule for the agent name `hello`), or join a room from LiveKit's Agents Playground, and the agent answers. STT, LLM, TTS, VAD, turn detection — defaults are picked for you. Swap them later with one config line.
+
+> **What a self-hosted worker can and can't do today.** A number bought or imported in VoiceLayer can't reach a worker you run on your own LiveKit project: VoiceLayer numbers answer with **hosted flow agents** (built in the dashboard's flow builder) and **brain-connector agents** (your own LLM behind a VoiceLayer-hosted voice pipeline — see [Bring your own LLM](#bring-your-own-llm)). Your worker still registers with VoiceLayer, so it shows up in the dashboard with its calls and transcripts.
 
 ---
 
@@ -301,7 +303,7 @@ Each method receives `(args, ctx)`, so you can reach call state from inside a co
 node --import tsx agent.ts dev
 ```
 
-This boots the worker against your LiveKit project and registers the agent with the VoiceLayer control plane, so you can call your number and iterate on the same file you will deploy. Set the environment variables listed under [Production](#production) first.
+This boots the worker against your LiveKit project and registers the agent with the VoiceLayer control plane, so you can call a number connected to your LiveKit project and iterate on the same file you will deploy. Set the environment variables listed under [Production](#production) first.
 
 > A headless harness for asserting on process capture without audio is not part of the public API yet. Today, iterate by calling the agent, or drive the flow from the Playground in the dashboard.
 
@@ -320,21 +322,28 @@ export LIVEKIT_URL=...
 export LIVEKIT_API_KEY=...
 export LIVEKIT_API_SECRET=...
 
-# Provider keys for the models your agent uses (or set them per project in the
-# VoiceLayer dashboard's connections, resolved at call time):
+# Required. Provider keys for the models your agent uses. Your worker reads
+# them from its own environment — provider keys saved in the VoiceLayer
+# dashboard's Connections are NOT handed to a worker you run yourself.
 export OPENAI_API_KEY=...
 export DEEPGRAM_API_KEY=...
 
 node agent.ts start
 ```
 
+Agent names starting `voicelayer-` (and the names of VoiceLayer's own workers) are reserved; registering one is refused with `422 agent_name_reserved`.
+
 ### Texts
 
-The same worker answers texts — SMS replies, Discord, your website's chat widget, the dashboard playground. `.start()`
-registers a second LiveKit name, `<name>::text`, beside the voice one; each message is dispatched to it and runs as
-your agent: its tools, security, connectors and model, with the conversation so far. Over text `ctx.call.callerId` is
-the sender, `ctx.call.metadata.mode` is `'text'`, and call-only methods (`handoff`, `endCall`, `ask`, DTMF) throw. In
-production the text registration's health server listens on `VL_TEXT_TURN_PORT` (default 8082).
+`.start()` also registers a second LiveKit name, `<name>::text`, beside the voice one. A text message dispatched to it
+runs as your agent: its tools, security, connectors and model, with the conversation so far. Over text
+`ctx.call.callerId` is the sender, `ctx.call.metadata.mode` is `'text'`, and call-only methods (`handoff`, `endCall`,
+`ask`, DTMF) throw. In production the text registration's health server listens on `VL_TEXT_TURN_PORT` (default 8082).
+
+> **Today** VoiceLayer dispatches text turns (SMS replies, Discord, the website chat widget, the dashboard playground)
+> through its own LiveKit project, so they reach VoiceLayer-hosted workers only. A worker on your own LiveKit project
+> doesn't receive them yet — the turn answers `agent_offline`. For texts on a VoiceLayer number, use a hosted flow
+> agent or a brain-connector agent.
 
 ---
 

package/dist/brain/index.d.ts

@@ -79,14 +79,14 @@ declare const ConnectorUpFrame: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
     code: z.ZodEnum<["upstream_timeout", "upstream_error", "bad_response", "normalize_failed", "unreachable"]>;
     message: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    kind: "brain.error";
     code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
     message: string;
-    kind: "brain.error";
     streamId: string;
 }, {
+    kind: "brain.error";
     code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
     message: string;
-    kind: "brain.error";
     streamId: string;
 }>]>;
 type ConnectorUpFrame = z.infer<typeof ConnectorUpFrame>;

package/dist/brain/index.js

@@ -622,9 +622,11 @@ var ProcessToolDTO = z.object({
 });
 var ProcessSchemaDTO = z.object({
   id: z.string().min(1).max(64),
-  // System-prompt fragments compiled from say/confirm nodes. The SDK bridge
-  // composes these into the agent's prompt.
-  prompts: z.array(z.object({ id: z.string().min(1).max(128), text: z.string().max(2e3) })).max(64).optional(),
+  // System-prompt fragments compiled from say/confirm/llm nodes. The SDK bridge
+  // composes these into the agent's prompt. An AI step's instructions are a
+  // system prompt in their own right, so the cap is generous (2,000 refused real
+  // flows — G-27); publish checks it (validateFlowGraph → compiledSchemaIssues).
+  prompts: z.array(z.object({ id: z.string().min(1).max(128), text: z.string().max(16e3) })).max(64).optional(),
   fields: z.array(ProcessFieldDTO).max(64),
   completionGate: z.object({
     requiredFields: z.array(z.string()).max(64),
@@ -1780,6 +1782,41 @@ z.object({
   toolCalls: z.array(ToolCallAudit),
   mcpInteractions: z.array(McpInteractionAudit)
 });
+var WEBHOOK_EVENT_TYPES = ["call.started", "call.ended", "recording.ready"];
+z.enum(WEBHOOK_EVENT_TYPES);
+var CallWebhookDirection = z.enum(["inbound", "outbound", "web"]);
+var CallWebhookOutcome = z.enum(["completed", "dropped", "failed", "no_answer", "other"]);
+var CallWebhookAttributes = z.record(z.union([z.string(), z.number(), z.boolean()]));
+var Party = z.string().min(1).nullable();
+z.object({
+  callId: z.string().uuid(),
+  startedAt: z.string().datetime(),
+  agentId: z.string().nullable(),
+  phoneNumberId: z.string().nullable(),
+  callerE164: Party,
+  toE164: Party,
+  // Null when it can't be told yet: an inbound phone call and a web session look alike until the caller joins. When
+  // set, it is the same value `call.ended` carries; `call.ended` always has one.
+  direction: CallWebhookDirection.nullable()
+});
+z.object({
+  callId: z.string().uuid(),
+  durationMs: z.number().int().min(0),
+  endedAt: z.string().datetime(),
+  endReason: z.string(),
+  agentId: z.string().nullable(),
+  phoneNumberId: z.string().nullable(),
+  callerE164: Party,
+  toE164: Party,
+  direction: CallWebhookDirection,
+  outcome: CallWebhookOutcome,
+  attributes: CallWebhookAttributes
+});
+z.object({
+  callId: z.string().uuid(),
+  recordingUrl: z.string().url(),
+  status: z.enum(["starting", "active", "completed", "failed", "aborted"])
+});
 var PhoneNumberStatus = z.enum([
   "pending",
   "active",
@@ -1984,6 +2021,39 @@ byokProviders().map((p) => ({
   keyPlaceholder: p.keyPlaceholder ?? "",
   supportsBaseUrl: p.supportsBaseUrl
 }));
+z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  /** The vault `provider` the resulting connection is stored under. */
+  vaultProvider: z.string().min(1),
+  category: z.enum(["model", "tool"])
+});
+z.object({
+  authorizeUrl: z.string().url()
+});
+z.object({
+  state: z.string().min(1).max(512),
+  code: z.string().min(1).max(4096)
+});
+z.object({
+  providerId: z.string().min(1),
+  /** The provider's display name ("ChatGPT"). */
+  providerLabel: z.string().min(1),
+  /** What the connection is for — which group the dashboard files it under. */
+  category: z.enum(["model", "tool"]),
+  /** The account's stable id at the provider (OIDC `sub`); reconnecting the same account updates the same row. */
+  subject: z.string().min(1).nullable(),
+  email: z.string().nullable(),
+  displayName: z.string().nullable(),
+  scopes: z.array(z.string()),
+  /**
+   * The workspace user who signed in. A person's model plan (category 'model') serves only them — never teammates or
+   * API keys. Absent on rows connected before it was recorded.
+   */
+  connectedBy: z.string().nullable().optional(),
+  /** Set when a refresh was refused (e.g. `invalid_grant`): the owner must connect again. */
+  reauthRequired: z.boolean().optional()
+});
 var E164 = z.string().regex(/^\+[1-9]\d{6,14}$/, "must be E.164 (+15551234567)");
 var RoomPrefix = z.string().regex(/^[a-z0-9][a-z0-9-]{0,30}[a-z0-9-]?$/, "lowercase letters, digits, dashes; max 32");
 var RecordingPrefix = z.string().min(1).max(128).refine((v) => !v.startsWith("/") && !v.includes(".."), "relative key prefix only");
@@ -2286,6 +2356,10 @@ z.discriminatedUnion("kind", [
   BrainRequestFrame,
   BrainCancelFrame
 ]);
+var FLOW_BOOT_FAILURES = ["schema_fetch_failed", "no_process_schema", "missing_agent_id", "no_api_key"];
+z.enum(
+  FLOW_BOOT_FAILURES.map((cause) => `flow_boot:${cause}`)
+);
 var EnvironmentSpec = z.enum(["draft", "live"]);
 z.object({
   agentName: z.string().min(1),