@voicelayer/sdk 0.6.3 → 0.7.0

package/dist/brain/index.js

@@ -1209,11 +1209,10 @@ var AgentConfig = z.object({
   projectId: z.string().min(1),
   // Human-readable label. No `agentType` enum on purpose.
   name: z.string().min(1).max(128),
-  // Soft override of the worker's baked-in prompt. Absent → call_start
-  // uses the SDK worker's predefined prompt (the source of truth for
-  // pre-defined agents like FNOL). Present → it overrides the worker's
-  // prompt at call_start as a snapshot decision; mid-call edits are not
-  // honoured. Per-call override at call_start time is also allowed.
+  // The agent's persona (the Behaviour page). For a FLOW agent the PUBLISHED value is the flow persona on every
+  // transport (flowPersonaOf — voice boot and text replies alike; absent → DEFAULT_FLOW_PERSONA), read at call start as
+  // a snapshot decision; mid-call edits are not honoured (burn-down G-46). A coded SDK agent's prompt is its code: this
+  // field doesn't reach it. A call plan may still override the prompt per call.
   systemPrompt: z.string().max(64e3).optional(),
   // Routing/decision layer (Voiceflow "Instructions"): plain-language guidance the
   // agent reads to decide WHEN to do things (vs systemPrompt = WHO it is). Injected
@@ -2004,7 +2003,134 @@ z.object({
   toolCalls: z.array(ToolCallAudit),
   mcpInteractions: z.array(McpInteractionAudit)
 });
-var WEBHOOK_EVENT_TYPES = ["call.started", "call.ended", "recording.ready"];
+var BUDGET_SCOPE_KINDS = ["workspace", "agent", "api_key", "channel"];
+var BudgetScopeKind = z.enum(BUDGET_SCOPE_KINDS);
+var CREATABLE_BUDGET_SCOPE_KINDS = ["workspace", "api_key", "channel"];
+var BUDGET_CHANNELS = ["voice", "sms", "email", "chat", "discord"];
+z.enum(BUDGET_CHANNELS);
+var BudgetScope = z.object({
+  kind: BudgetScopeKind,
+  // null for the workspace; the API key's id, or the channel name.
+  id: z.string().min(1).nullable()
+});
+var BudgetPeriodKind = z.enum(["day", "month", "billing_period"]);
+var BudgetEnforcement = z.enum(["soft", "hard"]);
+var BudgetInbound = z.enum(["refuse", "answer"]);
+var BudgetOwner = z.enum(["customer", "operator"]);
+var DEFAULT_BUDGET_THRESHOLDS = [50, 80, 100];
+var BUDGET_MAX_USD = 1e6;
+var Thresholds = z.array(z.number().int().min(1).max(100)).max(5).refine((t) => new Set(t).size === t.length, "thresholds must be distinct").transform((t) => [...t].sort((a, b) => a - b));
+var IANA_NAME = /^[A-Za-z]+(?:\/[A-Za-z0-9_+-]+)+$/;
+var SUPPORTED_ZONES = null;
+function supportedZones() {
+  if (!SUPPORTED_ZONES) {
+    const intl = Intl;
+    SUPPORTED_ZONES = new Set(intl.supportedValuesOf?.("timeZone") ?? []);
+  }
+  return SUPPORTED_ZONES;
+}
+function isIanaTimezone(tz) {
+  if (tz === "UTC" || supportedZones().has(tz)) return true;
+  if (!IANA_NAME.test(tz)) return false;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+var Timezone = z.string().min(1).max(64).refine(isIanaTimezone, "use an IANA time zone name, like America/New_York or UTC");
+var BudgetPeriodStatus = z.object({
+  periodStart: z.string(),
+  // When the budget resets.
+  periodEnd: z.string(),
+  // Charged usage this period.
+  settledUsd: z.string(),
+  // Reserved for calls in progress.
+  inProgressUsd: z.string(),
+  // settled + in progress — what the budget compares with its amount.
+  spentUsd: z.string(),
+  // spent ÷ amount, as a whole percent (may pass 100: calls in progress finish).
+  percent: z.number().int().min(0),
+  // A hard budget at its limit: new actions in its scope are refused until periodEnd.
+  reached: z.boolean()
+});
+var Budget = z.object({
+  id: z.string(),
+  scope: BudgetScope,
+  period: BudgetPeriodKind,
+  timezone: z.string(),
+  amountUsd: z.string(),
+  enforcement: BudgetEnforcement,
+  thresholds: z.array(z.number().int()),
+  notifyEmail: z.boolean(),
+  notifyWebhook: z.boolean(),
+  // Operator budgets are VoiceLayer's own safety limits: shown to the customer, read-only.
+  owner: BudgetOwner,
+  inbound: BudgetInbound,
+  createdAt: z.string(),
+  current: BudgetPeriodStatus
+});
+z.object({ budgets: z.array(Budget) });
+z.object({
+  scope: z.object({ kind: z.enum(CREATABLE_BUDGET_SCOPE_KINDS), id: z.string().min(1).max(200).nullable().optional() }),
+  period: BudgetPeriodKind,
+  timezone: Timezone.default("UTC"),
+  amountUsd: z.number().positive().max(BUDGET_MAX_USD),
+  enforcement: BudgetEnforcement,
+  thresholds: Thresholds.default([...DEFAULT_BUDGET_THRESHOLDS]),
+  notifyEmail: z.boolean().default(true),
+  notifyWebhook: z.boolean().default(true),
+  // Hard budgets only; a customer budget refuses incoming calls unless told to answer them (MON-9).
+  inbound: BudgetInbound.default("refuse")
+}).superRefine((b, ctx) => {
+  const id = b.scope.id ?? null;
+  if (b.scope.kind === "workspace" && id !== null) ctx.addIssue({ code: "custom", path: ["scope", "id"], message: "a workspace budget names no scope id" });
+  if (b.scope.kind !== "workspace" && id === null) ctx.addIssue({ code: "custom", path: ["scope", "id"], message: "name the API key or channel" });
+  if (b.scope.kind === "channel" && id !== null && !BUDGET_CHANNELS.includes(id)) {
+    ctx.addIssue({ code: "custom", path: ["scope", "id"], message: `channel is one of ${BUDGET_CHANNELS.join(", ")}` });
+  }
+});
+z.object({
+  amountUsd: z.number().positive().max(BUDGET_MAX_USD),
+  enforcement: BudgetEnforcement,
+  thresholds: Thresholds,
+  notifyEmail: z.boolean(),
+  notifyWebhook: z.boolean(),
+  inbound: BudgetInbound
+}).partial().refine((b) => Object.keys(b).length > 0, "nothing to change");
+var BudgetRefusalDetail = z.object({
+  budgetId: z.string(),
+  scope: BudgetScope,
+  period: BudgetPeriodKind,
+  resetsAt: z.string()
+});
+var BillingNoticeKind = z.enum([
+  "balance_empty",
+  "credit_limit_reached",
+  "auto_topup_off",
+  "wallet_frozen",
+  "invoice_issued",
+  "invoice_overdue",
+  "workspace_paused",
+  "workspace_restored",
+  "budget_threshold",
+  "budget_reached"
+]);
+var BillingNotice = z.object({
+  id: z.string(),
+  kind: BillingNoticeKind,
+  // The same words as the email's subject and first paragraph.
+  title: z.string(),
+  body: z.string(),
+  // The budget a budget notice is about.
+  budgetId: z.string().nullable(),
+  createdAt: z.string()
+});
+z.object({ notices: z.array(BillingNotice) });
+
+// ../contracts/src/webhook-events.ts
+var WEBHOOK_EVENT_TYPES = ["call.started", "call.ended", "recording.ready", "billing.budget_threshold", "billing.budget_reached"];
 z.enum(WEBHOOK_EVENT_TYPES);
 var CallWebhookDirection = z.enum(["inbound", "outbound", "web"]);
 var CallWebhookOutcome = z.enum(["completed", "dropped", "failed", "no_answer", "other"]);
@@ -2063,6 +2189,19 @@ z.object({
   recordingUrl: z.string().url(),
   status: z.enum(["starting", "active", "completed", "failed", "aborted"])
 });
+z.object({
+  budgetId: z.string(),
+  scope: BudgetScope,
+  period: BudgetPeriodKind,
+  periodStart: z.string().datetime({ offset: true }),
+  periodEnd: z.string().datetime({ offset: true }),
+  amountUsd: z.string(),
+  spentUsd: z.string(),
+  inProgressUsd: z.string(),
+  // The threshold passed (budget_reached: 100).
+  thresholdPct: z.number().int().min(1).max(100),
+  enforcement: BudgetEnforcement
+});
 var PhoneNumberStatus = z.enum([
   "pending",
   "active",
@@ -2125,6 +2264,10 @@ z.object({
   })
 });
 
+// ../contracts/src/flow-ask-lines.ts
+BigInt("0xcbf29ce484222325");
+BigInt("0x100000001b3");
+
 // ../contracts/src/dispatch-metadata.ts
 var IDENTITY_DISPATCH_METADATA_KEYS = [
   "projectId",
@@ -3511,14 +3654,18 @@ var WalletRefusalCode = z.enum([
   // still answered. Paying the invoice restores the workspace.
   "account_suspended",
   // The action's reservation already closed (e.g. a call ended or expired) — it cannot be re-admitted.
-  "hold_closed"
+  "hold_closed",
+  // A hard budget (docs/specs/monetization LLD §8a) would be passed: new actions in its scope wait for its reset.
+  "budget_exceeded"
 ]);
 z.object({
   error: WalletRefusalCode,
   code: WalletRefusalCode,
   availableUsd: z.string(),
   needUsd: z.string(),
-  message: z.string()
+  message: z.string(),
+  // budget_exceeded only: which budget, and when it resets.
+  budget: BudgetRefusalDetail.optional()
 });
 var WalletMode = z.enum(["prepaid", "invoiced"]);
 z.object({
@@ -3559,7 +3706,7 @@ var WalletInvoice = z.object({
   payUrl: z.string().nullable()
 });
 z.object({ invoices: z.array(WalletInvoice) });
-var WalletEntryKind = z.enum(["grant", "topup", "usage", "refund", "refund_reversal", "dispute", "dispute_reinstated", "adjustment", "invoice_payment"]);
+var WalletEntryKind = z.enum(["grant", "topup", "usage", "usage_correction", "refund", "refund_reversal", "dispute", "dispute_reinstated", "adjustment", "invoice_payment"]);
 var WalletEntry = z.object({
   id: z.string(),
   kind: WalletEntryKind,
@@ -3596,6 +3743,76 @@ z.object({
   tts: PipelineSlotKey.optional(),
   realtime: PipelineSlotKey.optional()
 });
+var METERING_SCHEMA_VERSION = 2;
+var METER_IDS = [
+  // A model's prompt tokens as the provider counts them (cached ones included); `cached_input_tokens` is the cached
+  // subset and `reasoning_tokens` the reasoning subset of `output_tokens`. Rating prices the totals until it prices the
+  // subsets on their own (monetization MON-14).
+  "llm.input_tokens",
+  "llm.cached_input_tokens",
+  "llm.output_tokens",
+  "llm.reasoning_tokens",
+  "embedding.input_tokens",
+  "realtime.audio_input_tokens",
+  "realtime.audio_output_tokens",
+  "realtime.text_input_tokens",
+  "realtime.cached_input_tokens",
+  "realtime.text_output_tokens",
+  "stt.billed_seconds",
+  "tts.characters",
+  "call.connected_seconds",
+  "telephony.carrier_seconds",
+  "media.participant_seconds",
+  "media.sip_seconds",
+  "recording.seconds",
+  "storage.byte_days",
+  "message.segments",
+  "email.messages",
+  // One per billable text action — a text turn, or a single model action the API takes for a workspace (a QA review,
+  // an evaluation, a planner call, a knowledge ingest): the per-message fee's basis.
+  "text.turns",
+  // Informational: number rental is a recurring fee on charge_cycles (🔒 B-21).
+  "number.held_days",
+  "provider_fee.micros"
+];
+var MeterId = z.enum(METER_IDS);
+var KEY_OWNERS = ["platform", "workspace_key", "workspace_plan", "workspace_brain", "self_hosted"];
+z.enum(KEY_OWNERS);
+var READING_SOURCES = ["server_observed", "platform_wire", "platform_estimate", "customer_report"];
+z.enum(READING_SOURCES);
+var SUBJECT_KINDS = ["call", "turn", "job", "message", "email", "number"];
+var SubjectKind = z.enum(SUBJECT_KINDS);
+var MeteringSubject = z.object({ kind: SubjectKind, id: z.string().min(1).max(200) });
+var DimValue = z.string().max(200).nullable();
+var IdentityDims = z.record(z.string(), DimValue);
+var Attributes = z.object({
+  served_model: z.string().max(200).nullable(),
+  channel: z.string().max(64).nullable(),
+  direction: z.string().max(32).nullable(),
+  leg_kind: z.string().max(64).nullable(),
+  country: z.string().max(8).nullable(),
+  worker_owner: z.enum(["platform", "self_hosted", "unknown"]).nullable()
+});
+var SERIES_PATTERN = /^(req|ws|srv):[A-Za-z0-9._:-]{1,60}$/;
+var SeriesName = z.string().max(64).regex(SERIES_PATTERN);
+var Quantity = z.string().regex(/^\d{1,14}(\.\d{1,6})?$/);
+var MeterReadingInput = z.object({
+  schemaVersion: z.literal(METERING_SCHEMA_VERSION),
+  subject: MeteringSubject,
+  meter: MeterId,
+  identity: IdentityDims,
+  series: SeriesName,
+  quantity: Quantity,
+  final: z.boolean(),
+  void: z.literal(true).optional(),
+  // The pre-send input estimate of a request that may never answer (LLD §4.1). A client never names a source: the
+  // server derives it from the principal (§4.4), and this flag is the one thing only the producer knows. Honoured
+  // only from the call's own worker token; it ranks below the request's wire count, which supersedes it.
+  estimate: z.literal(true).optional(),
+  occurredAt: z.string().datetime({ offset: true }),
+  attributes: Attributes.partial().optional()
+}).strict();
+z.object({ readings: z.array(MeterReadingInput).min(1).max(200) }).strict();
 
 // src/brain/transport-tunnel.ts
 var AsyncQueue = class {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AgentEnvironment, P as ProcessSchemaDTO, R as ReadinessProbe, a as AgentLifecycleEvent, b as AgentDTO, c as AgentEventEmitter, T as ToolDefinition, d as AgentConfig$1, e as ProcessField, M as ModelConfig, C as ConnectorInstance, f as ProviderFactory, S as STTProvider, g as TTSProvider, L as LLMProvider, h as RealtimeProvider, i as TurnDetectorProvider, V as VADProvider, j as ProcessDefinition, k as TriggerDefinition, H as HandoffConfig, l as MemoryConfig, m as SpeechConfig, n as ToolExecutor, o as AgentContext, p as ToolRunInfo, q as HostLookup } from './text-session-B928dhkB.js';
-export { r as AgentEventListener, s as AgentTurnEvent, t as AudioProfile, u as AudioSurface, v as CallInfo, w as CallOutcomeSummary, x as ChannelKind, y as CompletionStrategy, z as ComplianceTag, B as ConsultationPolicy, D as DtmfEvent, E as DtmfHandler, F as EndCallControllerHandle, G as EndCallInfo, I as EndCallOutcome, J as EndCallPolicy, K as EndCallTrigger, N as EndpointingConfig, O as FakeSessionAdapter, Q as FloorControlConfig, U as InboundOptions, W as InferProcessData, X as InterruptionConfig, Y as LK_AGENT_STATE_MAP, Z as MemoryHandle, _ as MemoryScope, $ as MetricsEvent, a0 as NON_BUSY_STATES, a1 as Participant, a2 as ParticipantId, a3 as ParticipantKind, a4 as ParticipantSet, a5 as ParticipantsConfig, a6 as ProcessBackendAck, a7 as ProcessFieldType, a8 as ProcessSnapshot, a9 as ReadinessReport, aa as ReadinessResult, ab as RespondOptions, ac as Room, ad as RouteEntry, ae as RoutingRule, af as RoutingSnapshot, ag as RunTextSessionOptions, ah as RunTextTranscriptOptions, ai as SayOptions, aj as SecurityConfig, ak as SendDtmfOptions, al as SessionAdapter, am as SessionCapabilities, an as SessionErrorEvent, ao as SessionEvent, ap as SessionEventMap, aq as SessionFactory, ar as SessionFactoryInput, as as SessionOutbound, at as SessionState, au as ShorthandPrimitive, av as SpeechResult, aw as SpeechTarget, ax as StateChangeEvent, ay as TextSession, az as TextTranscriptResult, aA as ToolInputShape, aB as TriggerAction, aC as TriggerCondition, aD as TtsVoiceConfig, aE as TurnEvent, aF as Unsubscribe, aG as UserInputEvent, aH as UserStateEvent, aI as UserTurn, aJ as VoiceLayerAuthError, aK as VoiceLayerError, aL as VoiceLayerHttpError, aM as VoiceLayerNetworkError, aN as VoiceLayerValidationError, aO as applySpeechTurnHandling, aP as asyncProbe, aQ as defineProcess, aR as dtmfCodeToDigit, aS as dtmfDigitToCode, aT as duck, aU as envProbe, aV as mute, aW as normalizeState, a2 as participantId, aX as passthrough, aY as runProbes, aZ as runTextSession, a_ as runTextTranscript, a$ as transform, b0 as urlProbe } from './text-session-B928dhkB.js';
+import { A as AgentEnvironment, P as ProcessSchemaDTO, R as ReadinessProbe, a as AgentLifecycleEvent, b as AgentDTO, c as AgentEventEmitter, T as ToolDefinition, d as AgentConfig$1, e as ProcessField, M as ModelConfig, C as ConnectorInstance, f as ProviderFactory, S as STTProvider, g as TTSProvider, L as LLMProvider, h as RealtimeProvider, i as TurnDetectorProvider, V as VADProvider, j as ProcessDefinition, k as TriggerDefinition, H as HandoffConfig, l as MemoryConfig, m as SpeechConfig, n as ToolExecutor, o as AgentContext, p as ToolRunInfo, q as HostLookup } from './text-session-BI5A-gxI.js';
+export { r as AgentEventListener, s as AgentTurnEvent, t as AudioProfile, u as AudioSurface, v as CallInfo, w as CallOutcomeSummary, x as ChannelKind, y as CompletionStrategy, z as ComplianceTag, B as ConsultationPolicy, D as DtmfEvent, E as DtmfHandler, F as EndCallControllerHandle, G as EndCallInfo, I as EndCallOutcome, J as EndCallPolicy, K as EndCallTrigger, N as EndpointingConfig, O as FakeSessionAdapter, Q as FloorControlConfig, U as InboundOptions, W as InferProcessData, X as InterruptionConfig, Y as LK_AGENT_STATE_MAP, Z as MemoryHandle, _ as MemoryScope, $ as MetricsEvent, a0 as NON_BUSY_STATES, a1 as Participant, a2 as ParticipantId, a3 as ParticipantKind, a4 as ParticipantSet, a5 as ParticipantsConfig, a6 as ProcessBackendAck, a7 as ProcessFieldType, a8 as ProcessSnapshot, a9 as ReadinessReport, aa as ReadinessResult, ab as RespondOptions, ac as Room, ad as RouteEntry, ae as RoutingRule, af as RoutingSnapshot, ag as RunTextSessionOptions, ah as RunTextTranscriptOptions, ai as SayOptions, aj as SecurityConfig, ak as SendDtmfOptions, al as SessionAdapter, am as SessionCapabilities, an as SessionErrorEvent, ao as SessionEvent, ap as SessionEventMap, aq as SessionFactory, ar as SessionFactoryInput, as as SessionOutbound, at as SessionState, au as ShorthandPrimitive, av as SpeechResult, aw as SpeechTarget, ax as StateChangeEvent, ay as TextSession, az as TextTranscriptResult, aA as ToolInputShape, aB as TriggerAction, aC as TriggerCondition, aD as TtsVoiceConfig, aE as TurnEvent, aF as Unsubscribe, aG as UserInputEvent, aH as UserStateEvent, aI as UserTurn, aJ as VoiceLayerAuthError, aK as VoiceLayerError, aL as VoiceLayerHttpError, aM as VoiceLayerNetworkError, aN as VoiceLayerValidationError, aO as applySpeechTurnHandling, aP as asyncProbe, aQ as defineProcess, aR as dtmfCodeToDigit, aS as dtmfDigitToCode, aT as duck, aU as envProbe, aV as mute, aW as normalizeState, a2 as participantId, aX as passthrough, aY as runProbes, aZ as runTextSession, a_ as runTextTranscript, a$ as transform, b0 as urlProbe } from './text-session-BI5A-gxI.js';
 import { z, ZodType } from 'zod';
 import { O as OnQuery, B as BrainTransport } from './types-KqrAfY85.js';
 export { a as BrainCallMetadata, b as BrainCapabilities, c as BrainChunk, d as BrainMessage, e as BrainRequest, f as OnQueryContext, g as OnQueryResult } from './types-KqrAfY85.js';
@@ -2831,6 +2831,9 @@ declare function defineAgent<TProcess extends Record<string, ProcessField> = Rec
  * via the same per-job override path that plans use. The STT/LLM/TTS pipeline
  * is shared infrastructure set here; the flow supplies prompt/process/triggers.
  *
+ * `basePrompt` is the prompt of the pool's NON-flow agents (brain connectors, a call plan's base). A flow agent runs on
+ * its own persona — its published Behaviour prompt, else the shared default — on voice and text alike (burn-down G-46).
+ *
  *   export default await defineFlowRuntime({ models: {...} }).start(import.meta.url);
  */
 declare function defineFlowRuntime(opts: {
@@ -3038,6 +3041,8 @@ interface CompiledAgentParts {
  * triggers (rails), and the handoff destination. Pure.
  */
 declare function processSchemaToAgentParts(schema: ProcessSchemaDTO, opts?: {
+    /** The flow persona the voice boot resolved (resolveFlowPersona: the published Behaviour prompt, else the default, +
+     *  the spoken cue). Absent ⇒ DEFAULT_FLOW_PERSONA alone. */
     readonly basePrompt?: string;
     readonly graphNodeIds?: ReadonlySet<string>;
     /**