@voicelayer/sdk 0.4.2 → 0.5.1

package/README.md

@@ -333,6 +333,33 @@ 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
 
 `.start()` also registers a second LiveKit name, `<name>::text`, beside the voice one. A text message dispatched to it

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

@@ -434,6 +434,8 @@ var FlowNodeType = z.enum([
   "ask",
   "confirm",
   "tool",
+  // Send an email through the workspace's email (metered, wallet-gated; From on a verified domain) — burn-down G-22.
+  "email",
   "decision",
   "handoff",
   "end",
@@ -599,7 +601,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 +623,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 +642,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 +662,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({
@@ -1382,6 +1397,56 @@ z.object({
   ok: z.literal(true),
   scopesPurged: z.array(MemoryScope)
 });
+var EMAIL_RE = /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/;
+function isEmailAddress(value) {
+  return EMAIL_RE.test(value) && value.length <= 254;
+}
+var EMAIL_SUBJECT_MAX = 200;
+var EMAIL_TEXT_MAX = 5e4;
+var EMAIL_HTML_MAX = 2e5;
+var address = z.string().max(254).refine(isEmailAddress, { message: "must be an email address" });
+z.object({
+  to: address,
+  subject: z.string().min(1).max(EMAIL_SUBJECT_MAX),
+  text: z.string().min(1).max(EMAIL_TEXT_MAX),
+  html: z.string().min(1).max(EMAIL_HTML_MAX).optional(),
+  // An address on one of the workspace's verified sending domains; omitted → the platform sender.
+  from: address.optional(),
+  // The display name shown beside `from` (or beside the platform sender's address).
+  fromName: z.string().trim().min(1).max(64).refine((v) => !/[\r\n<>"]/.test(v), { message: 'must not contain line breaks, <, > or "' }).optional(),
+  // Where a reply goes — any address; it needs no verification.
+  replyTo: address.optional(),
+  // The conversation (a call, a text conversation) the email belongs to — a conversation sends at most 3 emails.
+  conversationId: z.string().min(1).max(128).optional()
+});
+var DOMAIN_RE = /^(?=.{4,253}$)(?!-)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+function normalizeDomain(input) {
+  return input.trim().toLowerCase().replace(/^[a-z]+:\/\//, "").replace(/\/.*$/, "").replace(/\.$/, "");
+}
+function isDomainName(value) {
+  return DOMAIN_RE.test(value);
+}
+z.object({
+  domain: z.string().max(253).transform(normalizeDomain).refine(isDomainName, { message: "must be a domain like example.com" })
+});
+var EmailDomainStatus = z.enum(["pending", "verified", "failed"]);
+var EmailDnsRecord = z.object({
+  type: z.enum(["CNAME", "TXT"]),
+  name: z.string(),
+  value: z.string(),
+  // dkim: proves the domain (required); dmarc: recommended, only when the domain has no DMARC record yet.
+  purpose: z.enum(["dkim", "dmarc"]),
+  required: z.boolean()
+});
+z.object({
+  id: z.string(),
+  domain: z.string(),
+  status: EmailDomainStatus,
+  records: z.array(EmailDnsRecord),
+  createdAt: z.string().datetime(),
+  lastCheckedAt: z.string().datetime().nullable(),
+  verifiedAt: z.string().datetime().nullable()
+});
 z.object({
   systemPrompt: z.string().max(64e3),
   routingInstructions: z.string().max(32e3).nullable(),
@@ -1878,6 +1943,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),
@@ -1970,6 +2072,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(),
@@ -2055,7 +2176,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({
@@ -2356,7 +2481,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}`)
 );