@voicelayer/sdk 0.4.1 → 0.5.0

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,55 @@ 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`.
+
+### Outbound HTTP from your agent
+
+`httpTool`, a flow's tool steps and schema tools, and a process's completion `backendAck` all go through the SDK's
+outbound guard. They use http(s) only, and any private, loopback, link-local or cloud-metadata address is refused, both
+after DNS and on every redirect (at most 5 hops). The connection goes only to the address that was checked, a request
+times out (a `backendAck` waits at most 10 s), and responses are capped at 2 MiB.
+
+If your self-hosted worker has to call a service on your own network, opt in per tool or per ACK:
+
+```ts
+httpTool({ name: 'inventory', description: '…', input: { sku: 'string' }, url: 'http://inventory.internal/{sku}', allowPrivateNetwork: true });
+defineProcess({ collect: { … }, backendAck: { url: 'http://localhost:4000/ack', allowPrivateNetwork: true } });
+```
+
+`allowPrivateNetwork` only lifts the private-address refusal. The request is still http(s), still pinned to the checked
+address and still never follows a redirect blindly.
+
+On `httpTool` you set it in your own code, so it takes effect directly. On a `backendAck`, or on a tool in a stored
+flow or process schema, it takes effect only when the worker's operator also sets **`VL_ALLOW_PRIVATE_NETWORK=1`** in
+the worker's environment, because an author's flag alone shouldn't open your network. VoiceLayer-hosted workers (those
+holding `INTERNAL_SERVICE_TOKEN`) and the VoiceLayer API's text engine never honour it, whatever the environment says.
+Their tool steps run through the platform's server-side guard, which has no such switch.
+
+```bash
+export VL_ALLOW_PRIVATE_NETWORK=1   # self-hosted only: honour authors' allowPrivateNetwork on schema tools / backendAck
+```
+
 ### 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

@@ -1,3 +1,5 @@
+import { O as OnQuery, B as BrainTransport, d as BrainMessage } from '../types-KqrAfY85.js';
+export { a as BrainCallMetadata, b as BrainCapabilities, c as BrainChunk, e as BrainRequest, f as OnQueryContext, g as OnQueryResult } from '../types-KqrAfY85.js';
 import { Redis } from 'ioredis';
 import { z } from 'zod';
 
@@ -91,52 +93,6 @@ declare const ConnectorUpFrame: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
 }>]>;
 type ConnectorUpFrame = z.infer<typeof ConnectorUpFrame>;
 
-interface BrainMessage {
-    readonly role: 'system' | 'user' | 'assistant';
-    readonly content: string;
-}
-interface BrainCallMetadata {
-    readonly channel: 'voice' | 'text';
-    readonly callId?: string;
-    readonly projectId?: string;
-}
-interface BrainRequest {
-    readonly messages: readonly BrainMessage[];
-    /** Upstream model id / alias. Omitted → the brain's own default. */
-    readonly model?: string;
-    readonly temperature?: number;
-    readonly metadata: BrainCallMetadata;
-}
-/** One streamed piece of the brain's reply. */
-interface BrainChunk {
-    readonly content?: string;
-}
-interface BrainCapabilities {
-    readonly reachable: boolean;
-    readonly streaming: boolean;
-}
-interface BrainTransport {
-    readonly kind: 'callback' | 'http' | 'tunnel';
-    /** Stream the reply token-by-token (the voice path: first sentence → TTS ASAP). */
-    stream(req: BrainRequest, signal: AbortSignal): AsyncIterable<BrainChunk>;
-    /** Non-streaming convenience (the text path). */
-    complete(req: BrainRequest, signal: AbortSignal): Promise<string>;
-}
-/** Context handed to a customer's in-process `onQuery` brain. */
-interface OnQueryContext {
-    /** Full conversation so far (system + prior turns + latest user message). */
-    readonly messages: readonly BrainMessage[];
-    /** Aborts when the caller barges in / the turn is cancelled. */
-    readonly signal: AbortSignal;
-}
-type OnQueryResult = string | AsyncIterable<string>;
-/**
- * Bring-your-own brain, in-process. Receives the latest user utterance (and the
- * full history via `ctx.messages`) and returns the reply — either a string or an
- * async-iterable of string pieces for token streaming.
- */
-type OnQuery = (text: string, ctx: OnQueryContext) => OnQueryResult | Promise<OnQueryResult>;
-
 declare function callbackTransport(onQuery: OnQuery): BrainTransport;
 
 /** Convert a LK ChatContext (or any `{items}` shape) into BrainMessages. */
@@ -280,4 +236,4 @@ interface IncomingBrainRequest {
 /** Run one brain.request and yield the reply frames. Never throws. */
 declare function runBrainRequest(req: IncomingBrainRequest, cfg: BrainEndpointConfig, signal: AbortSignal): AsyncGenerator<ConnectorUpFrame>;
 
-export { type AssertUrlOptions, type BrainCallMetadata, type BrainCapabilities, type BrainChunk, BrainConfigError, type BrainEndpointConfig, type BrainMessage, type BrainPubSub, type BrainRequest, BrainRequestError, type BrainTransport, type ConnectorChatChunk, ConnectorChatModel, type ConnectorChatModelOptions, type ConnectorLLMOptions, type HostLookup, type HttpBrainTransportOptions, type IncomingBrainRequest, type OnQuery, type OnQueryContext, type OnQueryResult, RedisBrainPubSub, type SseDelta, type TunnelBrainTransportOptions, assertPublicHttpsUrl, buildRedisBrainPubSub, callbackTransport, chatChunkStream, chatContextToMessages, createConnectorLLM, httpBrainTransport, isDisallowedIp, lastUserText, parseChatCompletionSse, runBrainRequest, tunnelBrainTransport };
+export { type AssertUrlOptions, BrainConfigError, type BrainEndpointConfig, BrainMessage, type BrainPubSub, BrainRequestError, BrainTransport, type ConnectorChatChunk, ConnectorChatModel, type ConnectorChatModelOptions, type ConnectorLLMOptions, type HostLookup, type HttpBrainTransportOptions, type IncomingBrainRequest, OnQuery, RedisBrainPubSub, type SseDelta, type TunnelBrainTransportOptions, assertPublicHttpsUrl, buildRedisBrainPubSub, callbackTransport, chatChunkStream, chatContextToMessages, createConnectorLLM, httpBrainTransport, isDisallowedIp, lastUserText, parseChatCompletionSse, runBrainRequest, tunnelBrainTransport };

package/dist/brain/index.js

@@ -599,7 +599,10 @@ var ProcessFieldDTO = z.object({
   min: z.number().optional(),
   max: z.number().optional(),
   enum: z.array(z.string()).max(64).optional(),
-  ask: z.string().max(512).optional()
+  ask: z.string().max(512).optional(),
+  /** false ⇒ written by the agent itself (a tool's output, an assignment), never said by the caller — the runtime
+   *  doesn't extract it from their words. Absent ⇒ the caller may say it. */
+  fromCaller: z.boolean().optional()
 });
 var ProcessTriggerDTO = z.object({
   name: z.string().min(1).max(64),
@@ -618,7 +621,12 @@ var ProcessToolDTO = z.object({
   method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
   headers: z.record(z.string().max(1024)).optional(),
   auth: z.enum(["none", "connection"]),
-  connectionRef: z.string().max(128).optional()
+  connectionRef: z.string().max(128).optional(),
+  /**
+   * Self-hosted workers only: allow a private / loopback address (a localhost service of your own). A platform
+   * worker (it holds the internal service token) never honours it.
+   */
+  allowPrivateNetwork: z.boolean().optional()
 });
 var ProcessSchemaDTO = z.object({
   id: z.string().min(1).max(64),
@@ -632,7 +640,9 @@ var ProcessSchemaDTO = z.object({
     requiredFields: z.array(z.string()).max(64),
     backendAck: z.object({
       url: z.string().url(),
-      timeoutMs: z.number().int().positive()
+      timeoutMs: z.number().int().positive(),
+      // self-hosted workers only (see ProcessToolDTO.allowPrivateNetwork); a platform worker never honours it
+      allowPrivateNetwork: z.boolean().optional()
     }).optional()
   }),
   // Deterministic rails compiled from trigger/handoff/end nodes.
@@ -650,6 +660,9 @@ var ProcessSchemaDTO = z.object({
   }).optional(),
   // Tool capabilities compiled from tool nodes (maps to AgentConfig.tools).
   tools: z.array(ProcessToolDTO).max(32).optional(),
+  // The agent's human name, sealed at deploy (G-31): what a caller hears for {{ agent_name }} and what the dashboard
+  // shows. Distinct from the agent's dispatch name (a slug). Absent on schemas deployed before it.
+  displayName: z.string().min(1).max(128).optional(),
   // Voice turn-taking compiled from the flow's speech capability node (maps to
   // AgentConfig.speech → applySpeechTurnHandling). Absent = platform defaults.
   speech: z.object({
@@ -1782,6 +1795,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",
@@ -1843,6 +1891,43 @@ z.object({
     perCallMaxCumulativeMs: z.number().int().min(1e3).default(3e5)
   })
 });
+
+// ../contracts/src/dispatch-metadata.ts
+var IDENTITY_DISPATCH_METADATA_KEYS = [
+  "projectId",
+  "agentId",
+  "sessionId",
+  "callId",
+  "phoneNumberId",
+  "bindingId",
+  "apiKeyId",
+  "tenantId",
+  // the SecurityPrimitive's identity for the call
+  "moduleId",
+  "toNumber",
+  // fromNumber / toNumber / callerId: a warm transfer's caller ID (sdk handoff.ts ownDidFor)
+  "fromNumber",
+  "callerId"
+];
+var RESERVED_DISPATCH_METADATA_KEYS = [
+  ...IDENTITY_DISPATCH_METADATA_KEYS,
+  "route",
+  "direction",
+  "carrier",
+  "source",
+  "mode",
+  // mode + turnId would make a call's job run as a text turn
+  "turnId",
+  // set by the platform from its own inputs (the call's directive, the project's recording notice, AMD) — a caller's
+  // copy in a metadata bag would speak a line, skip a disclosure or change answering-machine handling
+  "initialDirective",
+  "recordingAnnouncement",
+  "amd"
+];
+new Set(RESERVED_DISPATCH_METADATA_KEYS);
+new Set(IDENTITY_DISPATCH_METADATA_KEYS);
+
+// ../contracts/src/flow-validate.ts
 var FlowIssueSeverity = z.enum(["error", "warning"]);
 var FlowIssue = z.object({
   code: z.string().max(64),
@@ -1935,6 +2020,25 @@ z.object({
   amd: OutboundAmdMode.optional()
 });
 var ConnectionAuthType = z.enum(["oauth2", "api_key", "bearer", "basic", "none"]);
+var TRANSPORT_OWNED_HEADERS = /* @__PURE__ */ new Set([
+  "host",
+  "content-length",
+  "transfer-encoding",
+  "connection",
+  "keep-alive",
+  "upgrade",
+  "te",
+  "trailer",
+  "expect",
+  // the transport advertises only what it can decode
+  "accept-encoding"
+]);
+function isTransportOwnedHeader(name) {
+  const n = name.trim().toLowerCase();
+  return TRANSPORT_OWNED_HEADERS.has(n) || n.startsWith("proxy-");
+}
+var PLATFORM_OWNED_HEADERS = { has: (n) => n === "content-type" || isTransportOwnedHeader(n) };
+z.string().trim().regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/, "a header name: letters, digits and - only, up to 64").refine((n) => !PLATFORM_OWNED_HEADERS.has(n.toLowerCase()), "the platform sets this header itself");
 var ConnectionStatus = z.enum(["active", "revoked", "error"]);
 z.object({
   v: z.number().int(),
@@ -2020,7 +2124,11 @@ z.object({
   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 PLATFORM_ROOM_NAMESPACES = ["text-", "vl-", "call-out-"];
+var RoomPrefix = z.string().regex(/^[a-z0-9][a-z0-9-]{0,30}[a-z0-9-]?$/, "lowercase letters, digits, dashes; max 32").refine(
+  (v) => !PLATFORM_ROOM_NAMESPACES.some((ns) => v.startsWith(ns)),
+  `must not start with a platform room namespace (${PLATFORM_ROOM_NAMESPACES.join(", ")})`
+);
 var RecordingPrefix = z.string().min(1).max(128).refine((v) => !v.startsWith("/") && !v.includes(".."), "relative key prefix only");
 var Cidr = z.string().regex(/^\d{1,3}(\.\d{1,3}){3}\/\d{1,2}$/, "must be IPv4 CIDR (a.b.c.d/nn)");
 var TelephonySettings = z.object({
@@ -2321,7 +2429,7 @@ z.discriminatedUnion("kind", [
   BrainRequestFrame,
   BrainCancelFrame
 ]);
-var FLOW_BOOT_FAILURES = ["schema_fetch_failed", "no_process_schema", "missing_agent_id", "no_api_key"];
+var FLOW_BOOT_FAILURES = ["schema_fetch_failed", "no_process_schema", "missing_agent_id", "no_api_key", "worker_identity_refused"];
 z.enum(
   FLOW_BOOT_FAILURES.map((cause) => `flow_boot:${cause}`)
 );