@voicelayer/sdk 0.1.10 → 0.1.11

package/README.md

@@ -44,7 +44,23 @@ That's what this SDK does. One declaration:
 
 ```ts
 import { defineAgent, defineProcess } from '@voicelayer/sdk';
-import { salesforce } from '@voicelayer/connector-salesforce';
+
+// A connector is any object with this shape — write one for whatever system
+// you already use. Its methods land on `ctx.connectors.<name>`.
+const crm = {
+  __connector: true as const,
+  name: 'crm',
+  api: {
+    createClaim: async (data: Record<string, unknown>) => {
+      const res = await fetch('https://your-crm.example.com/claims', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(data),
+      });
+      return (await res.json()) as { id: string };
+    },
+  },
+};
 
 export default await defineAgent({
   name: 'fnol',
@@ -62,7 +78,7 @@ export default await defineAgent({
     },
     completeWhen: 'all-required-captured',
     onComplete: async (data, ctx) => {
-      const claim = await ctx.connectors.salesforce.createClaim(data);
+      const claim = await ctx.connectors.crm.createClaim(data);
       await ctx.say(`Your claim number is ${claim.id}. You will receive a text shortly.`);
     },
   }),
@@ -87,10 +103,8 @@ export default await defineAgent({
     piiFields: ['ssn', 'dob'],
   },
 
-  // 5. Connectors — auto-wired tools, available to the LLM and in ctx.
-  connectors: {
-    salesforce: salesforce({ objects: ['Claim', 'Account'] }),
-  },
+  // 5. Connectors — available on ctx, and as LLM tools when `expose: true`.
+  connectors: { crm },
 
   // 6. Compliance — opt-in posture, defaults are safe.
   compliance: ['tcpa'],
@@ -131,10 +145,13 @@ defineAgent({
     if (text.includes('refund')) ctx.metadata.flagged = true;
   },
   async onFieldCaptured(field, value, ctx) {
-    if (field === 'claimNumber') await ctx.connectors.salesforce.lookup(value);
+    if (field === 'claimNumber') await ctx.connectors.crm.lookup(value);
   },
   async onCallEnd(outcome, ctx) {
-    await ctx.connectors.slack.send(`#claims`, `Call ${ctx.call.id} ended: ${outcome.reason}`);
+    await fetch('https://your-api.example.com/call-ended', {
+      method: 'POST',
+      body: JSON.stringify({ callId: ctx.call.id, reason: outcome.reason }),
+    });
   },
 });
 ```
@@ -148,7 +165,7 @@ defineAgent({
     // You own the entire conversation loop.
     await ctx.say('Hi! What is your policy number?');
     const policy = await ctx.ask();
-    const account = await ctx.connectors.salesforce.lookupPolicy(policy);
+    const account = await ctx.connectors.crm.lookupPolicy(policy);
     // ... do whatever ...
   },
 });
@@ -240,50 +257,53 @@ export default await defineAgent({
 
 Works with OpenAI, Azure, Together, Groq, vLLM, or a [LiteLLM](https://docs.litellm.ai) proxy in front of anything. The URL is `https`-only and SSRF-guarded; under the hood it reuses the proven LiveKit OpenAI client.
 
-**3. A private endpoint (tunnel)** — keep your brain behind your firewall. Run the one-container `vl-brain` daemon — it dials *out* to us (no inbound ports) and LiteLLM is baked in to normalize any provider. The connector then shows up as a voice agent in the dashboard (its LLM is your brain; STT/TTS still swappable) — test it in the Playground, attach a number. No SDK code required. See the [`vl-brain` daemon guide](../../apps/connector-daemon/README.md).
+**3. A private endpoint (tunnel)** — keep your brain behind your firewall. Run the one-container `vl-brain` daemon — it dials *out* to us (no inbound ports) and LiteLLM is baked in to normalize any provider. The connector then shows up as a voice agent in the dashboard (its LLM is your brain; STT/TTS still swappable) — test it in the Playground, attach a number. No SDK code required. See the [`vl-brain` daemon guide](https://vlayers.ai/docs/brain-connectors).
 
 ---
 
 ## Connectors
 
-Connectors are **typed integrations** with external systems. They show up on `ctx.connectors` and (optionally) as LLM tools.
+Connectors are **typed integrations** with external systems. They show up on `ctx.connectors` and, when `expose: true`, every method also becomes an LLM-callable tool automatically.
+
+There is no connector registry to install from — a connector is a plain object, so you write one against whatever API you already have:
 
 ```ts
-import { salesforce, twilio, slack, zendesk, webhook } from '@voicelayer/connectors';
+import { defineAgent, type ConnectorInstance } from '@voicelayer/sdk';
+
+const crm = {
+  __connector: true as const,
+  name: 'crm',
+  // With `expose: true`, the LLM can call `crm_lookupPolicy` on its own.
+  expose: true,
+  api: {
+    lookupPolicy: async ({ policyNumber }: { policyNumber: string }) => {
+      const res = await fetch(`https://your-crm.example.com/policies/${policyNumber}`, {
+        headers: { authorization: `Bearer ${process.env.CRM_TOKEN}` },
+      });
+      return res.json();
+    },
+  },
+} satisfies ConnectorInstance;
 
 defineAgent({
   // ...
-  connectors: {
-    crm:    salesforce({ objects: ['Claim'] }),
-    sms:    twilio(),
-    alerts: slack({ channel: '#claims' }),
-    custom: webhook({ url: 'https://your-api.example.com/voicelayer' }),
-  },
+  connectors: { crm },
 });
 ```
 
-Available connectors: `salesforce`, `twilio`, `slack`, `zendesk`, `webhook`, `epic` (HIPAA-scoped), `servicenow`. More on the roadmap.
+Each method receives `(args, ctx)`, so you can reach call state from inside a connector. When a `ToolRouter` is active, exposed connector methods are dispatched through Action Guard and audited like any other tool.
 
 ---
 
-## Testing locally
+## Running locally
 
-```ts
-import { testAgent } from '@voicelayer/sdk/testing';
-import agent from './agent.js';
-
-test('captures all required fields', async () => {
-  const result = await testAgent(agent)
-    .say('I was in a wreck yesterday with my Honda Civic, no injuries.')
-    .say('Claim number is AB-12345678.')
-    .end();
-
-  expect(result.process.complete).toBe(true);
-  expect(result.process.data.vehiclesInvolved).toEqual(['Honda Civic']);
-});
+```bash
+node --import tsx agent.ts dev
 ```
 
-No LiveKit, no audio, no API keys. Pure unit-test speed.
+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.
+
+> 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.
 
 ---
 
@@ -329,6 +349,7 @@ At `1.0` we'll commit to semver and a stable public surface. Until then, expect
 
 ## Reference
 
-- API: [`docs/API.md`](../../docs/API.md)
-- Architecture (what's underneath): [`docs/architecture.md`](../../docs/architecture.md)
-- Migration from 0.x → 0.next: [`CHANGELOG.md`](./CHANGELOG.md)
+- [SDK documentation](https://vlayers.ai/docs/sdk)
+- [Dashboard, flow builder, and brain connectors](https://vlayers.ai/docs)
+- [Pricing](https://vlayers.ai/pricing) — $0.05/min flat, providers billed at cost
+- [github.com/vlayers](https://github.com/vlayers)

package/dist/index.js

@@ -1669,6 +1669,212 @@ var init_connection = __esm({
     });
   }
 });
+var E164, RoomPrefix, RecordingPrefix, Cidr, TelephonySettings, ProfileSource, EffectiveCallProfile;
+var init_telephony = __esm({
+  "../contracts/src/telephony.ts"() {
+    E164 = z.string().regex(/^\+[1-9]\d{6,14}$/, "must be E.164 (+15551234567)");
+    RoomPrefix = z.string().regex(/^[a-z0-9][a-z0-9-]{0,30}[a-z0-9-]?$/, "lowercase letters, digits, dashes; max 32");
+    RecordingPrefix = z.string().min(1).max(128).refine((v) => !v.startsWith("/") && !v.includes(".."), "relative key prefix only");
+    Cidr = z.string().regex(/^\d{1,3}(\.\d{1,3}){3}\/\d{1,2}$/, "must be IPv4 CIDR (a.b.c.d/nn)");
+    TelephonySettings = z.object({
+      outboundTrunkId: z.string().min(1).max(128).nullable().default(null),
+      defaultFromE164: E164.nullable().default(null),
+      roomPrefix: RoomPrefix.nullable().default(null),
+      sipAllowedCidrs: z.array(Cidr).max(32).nullable().default(null),
+      recordingPrefix: RecordingPrefix.nullable().default(null),
+      strictByok: z.boolean().default(false)
+    });
+    z.object({
+      outboundTrunkId: z.string().min(1).max(128).nullable().optional(),
+      defaultFromE164: E164.nullable().optional(),
+      roomPrefix: RoomPrefix.nullable().optional(),
+      sipAllowedCidrs: z.array(Cidr).max(32).nullable().optional(),
+      recordingPrefix: RecordingPrefix.nullable().optional(),
+      strictByok: z.boolean().optional()
+    }).refine((v) => Object.keys(v).length > 0, { message: "nothing to update" });
+    ProfileSource = z.enum(["org", "platform", "none"]);
+    EffectiveCallProfile = z.object({
+      projectId: z.string(),
+      outboundTrunkId: z.string().nullable(),
+      defaultFromE164: z.string().nullable(),
+      roomPrefix: z.string(),
+      sipAllowedCidrs: z.array(z.string()),
+      recordingPrefix: z.string(),
+      strictByok: z.boolean(),
+      sources: z.object({
+        outboundTrunkId: ProfileSource,
+        defaultFromE164: ProfileSource,
+        roomPrefix: ProfileSource,
+        sipAllowedCidrs: ProfileSource,
+        recordingPrefix: ProfileSource
+      })
+    });
+    z.object({
+      settings: TelephonySettings,
+      profile: EffectiveCallProfile
+    });
+  }
+});
+var SHORTENER_HOSTS, PLACEHOLDER_HOSTS, PublicUrl, A2pBusinessType, A2pBusinessInfo, A2pOptInType, A2pUseCase, A2pMessagingProfile, A2pState;
+var init_a2p = __esm({
+  "../contracts/src/a2p.ts"() {
+    SHORTENER_HOSTS = [
+      "bit.ly",
+      "tinyurl.com",
+      "t.co",
+      "goo.gl",
+      "ow.ly",
+      "is.gd",
+      "buff.ly",
+      "rebrand.ly",
+      "cutt.ly",
+      "shorturl.at",
+      "tiny.cc"
+    ];
+    PLACEHOLDER_HOSTS = ["acme.com", "example.com", "example.org", "test.com", "localhost"];
+    PublicUrl = z.string().url().refine((v) => v.startsWith("https://"), "must be https").refine((v) => {
+      try {
+        const host = new URL(v).hostname.toLowerCase().replace(/^www\./, "");
+        return !SHORTENER_HOSTS.includes(host);
+      } catch {
+        return false;
+      }
+    }, "public URL shorteners are rejected by carriers \u2014 use your own domain").refine((v) => {
+      try {
+        const host = new URL(v).hostname.toLowerCase().replace(/^www\./, "");
+        return !PLACEHOLDER_HOSTS.some((p) => host === p || host.endsWith(`.${p}`));
+      } catch {
+        return false;
+      }
+    }, "placeholder domain \u2014 reviewers will follow this link and reject the campaign");
+    A2pBusinessType = z.enum([
+      "Sole Proprietorship",
+      "Partnership",
+      "Corporation",
+      "Co-operative",
+      "Limited Liability Corporation",
+      "Non-profit Corporation"
+    ]);
+    A2pBusinessInfo = z.object({
+      legalName: z.string().trim().min(2).max(200),
+      /** EIN (US) or equivalent registration number. */
+      registrationNumber: z.string().trim().min(4).max(50),
+      businessType: A2pBusinessType,
+      /** Publicly reachable production site — not staging, not a 404. */
+      website: PublicUrl,
+      industry: z.string().trim().min(2).max(60),
+      address: z.object({
+        street: z.string().trim().min(2).max(200),
+        city: z.string().trim().min(1).max(100),
+        region: z.string().trim().min(1).max(100),
+        postalCode: z.string().trim().min(2).max(20),
+        isoCountry: z.string().trim().length(2)
+      }),
+      authorizedRep: z.object({
+        firstName: z.string().trim().min(1).max(100),
+        lastName: z.string().trim().min(1).max(100),
+        email: z.string().trim().email(),
+        phone: z.string().trim().regex(/^\+[1-9]\d{6,14}$/, "must be E.164"),
+        jobTitle: z.string().trim().min(2).max(100)
+      })
+    });
+    A2pOptInType = z.enum(["WEB_FORM", "PAPER_FORM", "VERBAL", "VIA_TEXT", "MOBILE_QR_CODE"]);
+    A2pUseCase = z.enum([
+      "MIXED",
+      "CUSTOMER_CARE",
+      "MARKETING",
+      "ACCOUNT_NOTIFICATION",
+      "2FA",
+      "DELIVERY_NOTIFICATION",
+      "HIGHER_EDUCATION",
+      "POLLING_VOTING",
+      "PUBLIC_SERVICE_ANNOUNCEMENT",
+      "LOW_VOLUME"
+    ]);
+    A2pMessagingProfile = z.object({
+      useCase: A2pUseCase,
+      /** Specific, not generic. "We send texts" gets rejected; describe the actual
+       *  messages and when they are sent. */
+      description: z.string().trim().min(40).max(4096),
+      /**
+       * The single most-rejected field. Must describe HOW people opt in, state the
+       * message frequency, include the "message and data rates may apply"
+       * disclosure, and link to publicly reachable evidence. Twilio's API bounds it
+       * to 40–2049 characters.
+       */
+      messageFlow: z.string().trim().min(40).max(2049),
+      optInType: A2pOptInType,
+      /** Publicly accessible screenshots/pages showing the opt-in. Reviewers open
+       *  these; anything behind a login fails. */
+      optInEvidenceUrls: z.array(PublicUrl).min(1).max(5),
+      /** Real messages the customer will send. Must reflect the declared use case
+       *  and carry opt-out language. */
+      messageSamples: z.array(z.string().trim().min(10).max(1024)).min(2).max(5),
+      privacyPolicyUrl: PublicUrl,
+      termsAndConditionsUrl: PublicUrl,
+      hasEmbeddedLinks: z.boolean().default(false),
+      hasEmbeddedPhone: z.boolean().default(false)
+    });
+    z.object({
+      business: A2pBusinessInfo,
+      messaging: A2pMessagingProfile,
+      /** Register against Twilio's mock endpoints — exercises the full pipeline
+       *  with no fees and no real carrier submission. Used in CI and staging. */
+      mock: z.boolean().default(false)
+    }).superRefine((v, ctx) => {
+      const flow = v.messaging.messageFlow.toLowerCase();
+      if (!/(msg|message)\s*(&|and)\s*data rates/.test(flow)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["messaging", "messageFlow"],
+          message: 'must include a "Message and data rates may apply" disclosure \u2014 carriers reject without it'
+        });
+      }
+      if (!/\d/.test(flow) || !/(msg|message|text)/.test(flow)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["messaging", "messageFlow"],
+          message: 'must state message frequency, e.g. "Up to 4 msgs/month"'
+        });
+      }
+      const hasOptOut = v.messaging.messageSamples.some((s) => /stop/i.test(s));
+      if (!hasOptOut) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["messaging", "messageSamples"],
+          message: 'at least one sample must include opt-out language (e.g. "Reply STOP to opt out")'
+        });
+      }
+    });
+    A2pState = z.enum([
+      "none",
+      "profile_pending",
+      "profile_approved",
+      "profile_failed",
+      "brand_pending",
+      "brand_approved",
+      "brand_failed",
+      "campaign_pending",
+      "messaging_ready",
+      "campaign_failed"
+    ]);
+    z.object({
+      state: A2pState,
+      customerProfileSid: z.string().nullable(),
+      trustProductSid: z.string().nullable(),
+      brandSid: z.string().nullable(),
+      messagingServiceSid: z.string().nullable(),
+      campaignSid: z.string().nullable(),
+      mock: z.boolean(),
+      /** Carrier/Twilio rejection details, surfaced verbatim so the customer can
+       *  fix the specific field rather than guess. */
+      failures: z.array(z.object({ code: z.number().nullable(), field: z.string().nullable(), message: z.string() })).default([]),
+      /** Plain-language next step for the dashboard. */
+      nextAction: z.string().nullable(),
+      updatedAt: z.string().nullable()
+    });
+  }
+});
 var ConnectorMode, ConnectorStatus, ConnectorNormalize;
 var init_connector = __esm({
   "../contracts/src/connector.ts"() {
@@ -2307,6 +2513,8 @@ var init_src = __esm({
     init_call_recording();
     init_outbound();
     init_connection();
+    init_telephony();
+    init_a2p();
     init_connector();
     init_connector_stream();
     init_flow_compile();
@@ -7605,12 +7813,12 @@ function definitionFor(opts) {
 }
 async function runTextTranscript(opts) {
   const replies = [];
-  const trace7 = [];
+  const trace8 = [];
   const processRt = opts.processRt ?? createProcessRuntime(definitionFor(opts));
   const session = runTextSession({
     program: opts.program,
     onAgentText: (t) => void replies.push(t),
-    onTrace: (e) => void trace7.push(e),
+    onTrace: (e) => void trace8.push(e),
     ...processRt ? { processRt } : {},
     ...opts.generate ? { generate: opts.generate } : {},
     ...opts.call ? { call: opts.call } : {},
@@ -7619,7 +7827,7 @@ async function runTextTranscript(opts) {
   for (const m of opts.messages) session.sendUserMessage(m);
   session.end();
   const outcome = await session.result;
-  return { replies, outcome, trace: trace7 };
+  return { replies, outcome, trace: trace8 };
 }
 function ensureLkLogger() {
   if (loggerOptions() === void 0) {
@@ -7652,9 +7860,15 @@ async function runAgentTextTranscript(opts) {
   return { replies };
 }
 var DEFAULT_OTLP_ENDPOINT = "https://otel.vlayers.ai/v1/otlp";
+var DEFAULT_METRIC_EXPORT_INTERVAL_MS = 15e3;
 var started = false;
 var sdk = null;
 var loggerProvider = null;
+var metricReader = null;
+function metricExportIntervalMs() {
+  const raw = Number(process.env.OTEL_METRIC_EXPORT_INTERVAL);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_METRIC_EXPORT_INTERVAL_MS;
+}
 function start(opts) {
   if (started)
     return;
@@ -7679,21 +7893,23 @@ function start(opts) {
     processors: [new BatchLogRecordProcessor(new OTLPLogExporter())]
   });
   logs.setGlobalLoggerProvider(loggerProvider);
+  metricReader = new PeriodicExportingMetricReader({
+    exportIntervalMillis: metricExportIntervalMs(),
+    // DELTA temporality: each export carries only the increment since the
+    // previous one. The read side (apps/api openobserve-repository) totals a
+    // metric with SUM(value) over the query window, which is correct only for
+    // deltas. The OTLP exporter defaults to CUMULATIVE — it re-reports the
+    // running total every export, so SUM double-counts every call that lives
+    // longer than one export interval (inflating LLM/TTS/STT usage + cost).
+    // Setting DELTA makes the existing SUM reads correct without touching them.
+    exporter: new OTLPMetricExporter({
+      temporalityPreference: AggregationTemporalityPreference.DELTA
+    })
+  });
   sdk = new NodeSDK({
     resource,
     traceExporter: new OTLPTraceExporter(),
-    metricReader: new PeriodicExportingMetricReader({
-      // DELTA temporality: each 60s export carries only the increment since the
-      // previous one. The read side (apps/api openobserve-repository) totals a
-      // metric with SUM(value) over the query window, which is correct only for
-      // deltas. The OTLP exporter defaults to CUMULATIVE — it re-reports the
-      // running total every export, so SUM double-counts every call that lives
-      // longer than one export interval (inflating LLM/TTS/STT usage + cost).
-      // Setting DELTA makes the existing SUM reads correct without touching them.
-      exporter: new OTLPMetricExporter({
-        temporalityPreference: AggregationTemporalityPreference.DELTA
-      })
-    }),
+    metricReader,
     instrumentations: [
       getNodeAutoInstrumentations({
         // fs instrumentation is extremely noisy and rarely useful for app traces.
@@ -7712,6 +7928,19 @@ function start(opts) {
   process.once("SIGTERM", () => void shutdown().then(() => process.exit(0)));
   process.once("SIGINT", () => void shutdown().then(() => process.exit(0)));
 }
+async function flushTelemetry() {
+  const flushes = [];
+  if (metricReader)
+    flushes.push(metricReader.forceFlush());
+  if (loggerProvider)
+    flushes.push(loggerProvider.forceFlush());
+  const proxied = trace.getTracerProvider();
+  const tracerProvider = proxied.getDelegate?.() ?? proxied;
+  if (typeof tracerProvider.forceFlush === "function") {
+    flushes.push(tracerProvider.forceFlush());
+  }
+  await Promise.allSettled(flushes);
+}
 function getLogger(name) {
   return logs.getLogger(name);
 }
@@ -7783,6 +8012,12 @@ function getCurrentCallContext() {
 }
 var METER_NAME = "voicelayer";
 var METER_VERSION = "0.1.0";
+var USAGE_METRIC_NAMES = {
+  llmInputTokens: "vl.llm.input_tokens",
+  llmOutputTokens: "vl.llm.output_tokens",
+  ttsChars: "vl.tts.chars",
+  sttSeconds: "vl.stt.seconds"
+};
 function meter() {
   return metrics.getMeter(METER_NAME, METER_VERSION);
 }
@@ -7803,25 +8038,25 @@ var _llmOutputTokens = null;
 var _ttsChars = null;
 var _sttSeconds = null;
 function llmInputTokens() {
-  return _llmInputTokens ??= meter().createCounter("vl.llm.input_tokens", {
+  return _llmInputTokens ??= meter().createCounter(USAGE_METRIC_NAMES.llmInputTokens, {
     description: "Input tokens consumed by an LLM call",
     unit: "{tokens}"
   });
 }
 function llmOutputTokens() {
-  return _llmOutputTokens ??= meter().createCounter("vl.llm.output_tokens", {
+  return _llmOutputTokens ??= meter().createCounter(USAGE_METRIC_NAMES.llmOutputTokens, {
     description: "Output tokens produced by an LLM call",
     unit: "{tokens}"
   });
 }
 function ttsChars() {
-  return _ttsChars ??= meter().createCounter("vl.tts.chars", {
+  return _ttsChars ??= meter().createCounter(USAGE_METRIC_NAMES.ttsChars, {
     description: "Characters synthesized by TTS",
     unit: "{chars}"
   });
 }
 function sttSeconds() {
-  return _sttSeconds ??= meter().createCounter("vl.stt.seconds", {
+  return _sttSeconds ??= meter().createCounter(USAGE_METRIC_NAMES.sttSeconds, {
     description: "Audio seconds transcribed by STT",
     unit: "s"
   });
@@ -11024,7 +11259,7 @@ async function quiesce(deps) {
 async function executeHandoff(args, config, deps) {
   const briefing = args.briefing ?? await buildBriefing(config, deps) ?? `Handoff to ${args.to}`;
   const mode = args.mode ?? config?.mode ?? "warm";
-  const sipOps = deps.sipOps ?? buildDefaultSipOps();
+  const sipOps = deps.sipOps ?? buildDefaultSipOps(deps.outboundTrunkId, ownDidFor(deps.call));
   const notify = deps.notify ?? (() => {
   });
   if (mode === "warm" && sipOps && sipOps.canConference) {
@@ -11102,14 +11337,19 @@ async function buildBriefing(config, deps, args) {
     return void 0;
   }
 }
-function buildDefaultSipOps() {
+function ownDidFor(call) {
+  const direction = typeof call.metadata["direction"] === "string" ? call.metadata["direction"] : "inbound";
+  const candidate = direction === "outbound" ? call.callerId : call.to;
+  return candidate && /^\+[1-9]\d{6,14}$/.test(candidate) ? candidate : void 0;
+}
+function buildDefaultSipOps(trunkOverride, fromNumber) {
   const url = process.env["LIVEKIT_URL"];
   const key = process.env["LIVEKIT_API_KEY"];
   const secret = process.env["LIVEKIT_API_SECRET"];
   if (!url || !key || !secret) return null;
   const host = url.startsWith("wss://") ? `https://${url.slice("wss://".length)}` : url.startsWith("ws://") ? `http://${url.slice("ws://".length)}` : url;
   const client = new SipClient(host, key, secret);
-  const trunkId = process.env["LIVEKIT_SIP_OUTBOUND_TRUNK_ID"];
+  const trunkId = trunkOverride ?? process.env["LIVEKIT_SIP_OUTBOUND_TRUNK_ID"];
   return {
     canConference: Boolean(trunkId),
     async refer(roomName, callerIdentity, target) {
@@ -11121,7 +11361,8 @@ function buildDefaultSipOps() {
       await client.createSipParticipant(trunkId, target.replace(/^tel:/, ""), roomName, {
         participantIdentity: identity,
         playDialtone: false,
-        waitUntilAnswered: true
+        waitUntilAnswered: true,
+        ...fromNumber ? { fromNumber } : {}
       });
       return { identity };
     }
@@ -11909,6 +12150,64 @@ var UsageAccumulator = class {
     };
   }
 };
+function registerTelemetryFlush(job, flush = flushTelemetry) {
+  const ctx = job;
+  if (typeof ctx?.addShutdownCallback !== "function") return;
+  ctx.addShutdownCallback(async () => {
+    try {
+      await flush();
+    } catch (err) {
+      console.warn("[agent] telemetry flush failed", err);
+    }
+  });
+}
+function attachEndpointingProbe(session, events, ctx, deps) {
+  const base = {
+    projectId: ctx.projectId,
+    callId: ctx.callId,
+    ...ctx.campaignId ? { campaignId: ctx.campaignId } : {}
+  };
+  const now = deps.now ?? Date.now;
+  let armed = false;
+  let speechEndAt = null;
+  let finalTranscriptAt = null;
+  const resetTurn = () => {
+    speechEndAt = null;
+    finalTranscriptAt = null;
+  };
+  const tryEmit = () => {
+    if (!armed || speechEndAt == null || finalTranscriptAt == null) return;
+    const delayMs = finalTranscriptAt - speechEndAt;
+    armed = false;
+    resetTurn();
+    if (!(delayMs > 0)) return;
+    recordEouLatency({
+      ...base,
+      endOfUtteranceDelayMs: delayMs,
+      transcriptionDelayMs: delayMs
+    });
+    recordTurnLatencySpan({ ...base, stage: "endpointing", latencyMs: delayMs });
+    recordTurnLatencySpan({ ...base, stage: "stt", latencyMs: delayMs });
+  };
+  deps.vad.onSpeechEnd((sample) => {
+    if (!armed) return;
+    speechEndAt = sample.speechEndAt;
+    tryEmit();
+  });
+  session.on(events.userStateChanged, (event) => {
+    const e = event;
+    if (e?.newState === "speaking") {
+      armed = true;
+      resetTurn();
+    }
+  });
+  session.on(events.userInputTranscribed, (event) => {
+    const e = event;
+    if (!armed || !e?.isFinal) return;
+    finalTranscriptAt = typeof e.createdAt === "number" ? e.createdAt : now();
+    tryEmit();
+  });
+}
 function attachMetricsBridge(session, eventName, ctx) {
   session.on(eventName, (event) => {
     try {
@@ -12024,6 +12323,51 @@ function dispatch(metrics2, ctx) {
     }
   }
 }
+
+// src/runtime/vad-tap.ts
+function tapVad(vad, opts) {
+  const listeners = /* @__PURE__ */ new Set();
+  const now = opts.now ?? Date.now;
+  const target = vad;
+  if (!target || typeof target.stream !== "function") {
+    return { onSpeechEnd: () => () => {
+    } };
+  }
+  const originalStream = target.stream.bind(target);
+  target.stream = () => {
+    const stream = originalStream();
+    const originalNext = stream.next.bind(stream);
+    stream.next = async () => {
+      const result = await originalNext();
+      try {
+        const event = result.value;
+        if (!result.done && event && event.type === opts.endOfSpeechType) {
+          const silenceMs = numberOr(event.silenceDuration, 0);
+          const inferenceMs = numberOr(event.inferenceDuration, 0);
+          const sample = {
+            speechEndAt: now() - silenceMs - inferenceMs,
+            silenceMs,
+            inferenceMs
+          };
+          for (const listener of [...listeners]) listener(sample);
+        }
+      } catch (err) {
+        console.warn("[agent] vad tap failed", err);
+      }
+      return result;
+    };
+    return stream;
+  };
+  return {
+    onSpeechEnd(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+function numberOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
 function resolveAgentModulePath(moduleUrl) {
   if (moduleUrl.startsWith("file://")) {
     return fileURLToPath(moduleUrl);
@@ -12179,6 +12523,82 @@ function actionSpecToAction(spec) {
   return void 0;
 }
 
+// src/worker-identity.ts
+async function exchangeWorkerToken(input) {
+  const apiUrl = process.env["VOICELAYER_API_URL"];
+  const internalToken = process.env["INTERNAL_SERVICE_TOKEN"];
+  if (!apiUrl || !internalToken) return null;
+  try {
+    const res = await (input.fetchImpl ?? fetch)(
+      `${apiUrl.replace(/\/+$/, "")}/v1/internal/worker-token`,
+      {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-internal-token": internalToken
+        },
+        body: JSON.stringify({
+          projectId: input.projectId,
+          ...input.callId ? { callId: input.callId } : {}
+        })
+      }
+    );
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.token === "string" && body.token.length > 0 ? body.token : null;
+  } catch {
+    return null;
+  }
+}
+async function fetchCallProfile(projectId, fetchImpl) {
+  const apiUrl = process.env["VOICELAYER_API_URL"];
+  const internalToken = process.env["INTERNAL_SERVICE_TOKEN"];
+  if (!apiUrl || !internalToken) return null;
+  try {
+    const res = await (fetchImpl ?? fetch)(
+      `${apiUrl.replace(/\/+$/, "")}/v1/internal/call-profile/${encodeURIComponent(projectId)}`,
+      { headers: { "x-internal-token": internalToken } }
+    );
+    if (!res.ok) return null;
+    const body = await res.json();
+    if (!body.profile) return null;
+    return {
+      outboundTrunkId: typeof body.profile.outboundTrunkId === "string" ? body.profile.outboundTrunkId : null,
+      strictByok: body.profile.strictByok === true
+    };
+  } catch {
+    return null;
+  }
+}
+async function resolveWorkerClient(md, fetchImpl) {
+  const projectId = typeof md["projectId"] === "string" ? md["projectId"] : void 0;
+  const callId = typeof md["callId"] === "string" ? md["callId"] : void 0;
+  if (projectId) {
+    const token = await exchangeWorkerToken({
+      projectId,
+      ...callId ? { callId } : {},
+      ...{}
+    });
+    if (token) {
+      try {
+        return createClient({ apiKey: token });
+      } catch {
+      }
+    } else if (process.env["INTERNAL_SERVICE_TOKEN"] && process.env["VOICELAYER_API_URL"]) {
+      console.warn("[sdk.worker-identity] worker-token exchange failed; falling back to env key", {
+        projectId
+      });
+    }
+  }
+  const apiKey = process.env["VOICELAYER_API_KEY"];
+  if (!apiKey) return null;
+  try {
+    return createClient({ apiKey });
+  } catch {
+    return null;
+  }
+}
+
 // src/runtime/prompt-compose.ts
 function composeSystemPrompt(prompt, routingInstructions) {
   const routing = routingInstructions?.trim();
@@ -12703,26 +13123,34 @@ var Agent = class {
     const projectId = typeof md["projectId"] === "string" ? md["projectId"] : void 0;
     const agentId = typeof md["agentId"] === "string" ? md["agentId"] : void 0;
     const room = job.room.name ?? void 0;
-    return withCallContext(
-      {
-        kind: "agent.call",
-        source: this.config.name,
-        callId,
-        ...projectId ? { projectId } : {},
-        ...agentId ? { agentId } : {},
-        ...room ? { room } : {}
-      },
-      () => this.runCallSpan(job)
-    );
+    registerTelemetryFlush(job);
+    try {
+      return await withCallContext(
+        {
+          kind: "agent.call",
+          source: this.config.name,
+          callId,
+          ...projectId ? { projectId } : {},
+          ...agentId ? { agentId } : {},
+          ...room ? { room } : {}
+        },
+        () => this.runCallSpan(job)
+      );
+    } finally {
+      await flushTelemetry().catch(() => {
+      });
+    }
   }
   async runCallSpan(job) {
-    const { AutoSubscribe, voice: voice3 } = await import('@livekit/agents');
+    const { AutoSubscribe, voice: voice3, VADEventType } = await import('@livekit/agents');
     const Events = voice3.AgentSessionEventTypes;
     await job.connect(void 0, AutoSubscribe.SUBSCRIBE_ALL);
     const participant = await job.waitForParticipant();
     const callInfo = buildCallInfo(job, participant);
-    const sdkClient = tryCreateClient();
     const dispatchMdEarly = parseJobMetadata(job.job?.metadata);
+    const sdkClient = await resolveWorkerClient(dispatchMdEarly);
+    const earlyProjectId = stringValue(dispatchMdEarly["projectId"]);
+    const workerCallProfile = earlyProjectId ? await fetchCallProfile(earlyProjectId) : null;
     let effectiveConfig = this.config;
     let graphMode = false;
     let graphProgram;
@@ -12881,6 +13309,7 @@ var Agent = class {
       callInfo,
       job.proc.userData.vad
     );
+    const vadTap = tapVad(pipeline.vad, { endOfSpeechType: VADEventType.END_OF_SPEECH });
     const usingRealtime = pipeline.realtime != null;
     let runtimeLlm = usingRealtime ? pipeline.realtime : pipeline.llm;
     if (this.config.puppetMode) {
@@ -13174,7 +13603,8 @@ ${callIntent}`
       },
       getProcessData: () => processRt.getData(),
       transcript,
-      notify: (kind, payload) => emitOpEvent(kind, payload)
+      notify: (kind, payload) => emitOpEvent(kind, payload),
+      ...workerCallProfile?.outboundTrunkId ? { outboundTrunkId: workerCallProfile.outboundTrunkId } : {}
     });
     const triggersRt = createTriggersRuntime(effectiveConfig.triggers, handoffRt);
     const audioExperience = new AudioExperiencePrimitive();
@@ -13518,12 +13948,26 @@ ${callIntent}`
       console.error("[agent] session error", e.error);
       if (e.fatalTransport) endCallController.noteEngineClosed();
     });
-    attachMetricsBridge(session, Events.MetricsCollected, {
+    const metricsCtx = {
       projectId: callProjectId,
       callId: callSync.callId,
-      ...callCampaignId ? { campaignId: callCampaignId } : {},
+      ...callCampaignId ? { campaignId: callCampaignId } : {}
+    };
+    attachMetricsBridge(session, Events.MetricsCollected, {
+      ...metricsCtx,
       usage: usageAccumulator
     });
+    if (graphMode) {
+      attachEndpointingProbe(
+        session,
+        {
+          userStateChanged: Events.UserStateChanged,
+          userInputTranscribed: Events.UserInputTranscribed
+        },
+        metricsCtx,
+        { vad: vadTap }
+      );
+    }
     adapter.on("state", (e) => {
       console.log("[agent] state", {
         from: e.rawOldState,
@@ -13926,15 +14370,6 @@ function builtinToolCapabilities() {
   }
   return [...caps];
 }
-function tryCreateClient() {
-  const apiKey = process.env["VOICELAYER_API_KEY"];
-  if (!apiKey) return null;
-  try {
-    return createClient({ apiKey });
-  } catch {
-    return null;
-  }
-}
 function buildFormStreamWatcher(processRt) {
   const apiBaseUrl = process.env["VOICELAYER_API_URL"];
   if (!apiBaseUrl) {

package/dist/runtime/text-session.js

@@ -1627,6 +1627,212 @@ var init_connection = __esm({
     });
   }
 });
+var E164, RoomPrefix, RecordingPrefix, Cidr, TelephonySettings, ProfileSource, EffectiveCallProfile;
+var init_telephony = __esm({
+  "../contracts/src/telephony.ts"() {
+    E164 = z.string().regex(/^\+[1-9]\d{6,14}$/, "must be E.164 (+15551234567)");
+    RoomPrefix = z.string().regex(/^[a-z0-9][a-z0-9-]{0,30}[a-z0-9-]?$/, "lowercase letters, digits, dashes; max 32");
+    RecordingPrefix = z.string().min(1).max(128).refine((v) => !v.startsWith("/") && !v.includes(".."), "relative key prefix only");
+    Cidr = z.string().regex(/^\d{1,3}(\.\d{1,3}){3}\/\d{1,2}$/, "must be IPv4 CIDR (a.b.c.d/nn)");
+    TelephonySettings = z.object({
+      outboundTrunkId: z.string().min(1).max(128).nullable().default(null),
+      defaultFromE164: E164.nullable().default(null),
+      roomPrefix: RoomPrefix.nullable().default(null),
+      sipAllowedCidrs: z.array(Cidr).max(32).nullable().default(null),
+      recordingPrefix: RecordingPrefix.nullable().default(null),
+      strictByok: z.boolean().default(false)
+    });
+    z.object({
+      outboundTrunkId: z.string().min(1).max(128).nullable().optional(),
+      defaultFromE164: E164.nullable().optional(),
+      roomPrefix: RoomPrefix.nullable().optional(),
+      sipAllowedCidrs: z.array(Cidr).max(32).nullable().optional(),
+      recordingPrefix: RecordingPrefix.nullable().optional(),
+      strictByok: z.boolean().optional()
+    }).refine((v) => Object.keys(v).length > 0, { message: "nothing to update" });
+    ProfileSource = z.enum(["org", "platform", "none"]);
+    EffectiveCallProfile = z.object({
+      projectId: z.string(),
+      outboundTrunkId: z.string().nullable(),
+      defaultFromE164: z.string().nullable(),
+      roomPrefix: z.string(),
+      sipAllowedCidrs: z.array(z.string()),
+      recordingPrefix: z.string(),
+      strictByok: z.boolean(),
+      sources: z.object({
+        outboundTrunkId: ProfileSource,
+        defaultFromE164: ProfileSource,
+        roomPrefix: ProfileSource,
+        sipAllowedCidrs: ProfileSource,
+        recordingPrefix: ProfileSource
+      })
+    });
+    z.object({
+      settings: TelephonySettings,
+      profile: EffectiveCallProfile
+    });
+  }
+});
+var SHORTENER_HOSTS, PLACEHOLDER_HOSTS, PublicUrl, A2pBusinessType, A2pBusinessInfo, A2pOptInType, A2pUseCase, A2pMessagingProfile, A2pState;
+var init_a2p = __esm({
+  "../contracts/src/a2p.ts"() {
+    SHORTENER_HOSTS = [
+      "bit.ly",
+      "tinyurl.com",
+      "t.co",
+      "goo.gl",
+      "ow.ly",
+      "is.gd",
+      "buff.ly",
+      "rebrand.ly",
+      "cutt.ly",
+      "shorturl.at",
+      "tiny.cc"
+    ];
+    PLACEHOLDER_HOSTS = ["acme.com", "example.com", "example.org", "test.com", "localhost"];
+    PublicUrl = z.string().url().refine((v) => v.startsWith("https://"), "must be https").refine((v) => {
+      try {
+        const host = new URL(v).hostname.toLowerCase().replace(/^www\./, "");
+        return !SHORTENER_HOSTS.includes(host);
+      } catch {
+        return false;
+      }
+    }, "public URL shorteners are rejected by carriers \u2014 use your own domain").refine((v) => {
+      try {
+        const host = new URL(v).hostname.toLowerCase().replace(/^www\./, "");
+        return !PLACEHOLDER_HOSTS.some((p) => host === p || host.endsWith(`.${p}`));
+      } catch {
+        return false;
+      }
+    }, "placeholder domain \u2014 reviewers will follow this link and reject the campaign");
+    A2pBusinessType = z.enum([
+      "Sole Proprietorship",
+      "Partnership",
+      "Corporation",
+      "Co-operative",
+      "Limited Liability Corporation",
+      "Non-profit Corporation"
+    ]);
+    A2pBusinessInfo = z.object({
+      legalName: z.string().trim().min(2).max(200),
+      /** EIN (US) or equivalent registration number. */
+      registrationNumber: z.string().trim().min(4).max(50),
+      businessType: A2pBusinessType,
+      /** Publicly reachable production site — not staging, not a 404. */
+      website: PublicUrl,
+      industry: z.string().trim().min(2).max(60),
+      address: z.object({
+        street: z.string().trim().min(2).max(200),
+        city: z.string().trim().min(1).max(100),
+        region: z.string().trim().min(1).max(100),
+        postalCode: z.string().trim().min(2).max(20),
+        isoCountry: z.string().trim().length(2)
+      }),
+      authorizedRep: z.object({
+        firstName: z.string().trim().min(1).max(100),
+        lastName: z.string().trim().min(1).max(100),
+        email: z.string().trim().email(),
+        phone: z.string().trim().regex(/^\+[1-9]\d{6,14}$/, "must be E.164"),
+        jobTitle: z.string().trim().min(2).max(100)
+      })
+    });
+    A2pOptInType = z.enum(["WEB_FORM", "PAPER_FORM", "VERBAL", "VIA_TEXT", "MOBILE_QR_CODE"]);
+    A2pUseCase = z.enum([
+      "MIXED",
+      "CUSTOMER_CARE",
+      "MARKETING",
+      "ACCOUNT_NOTIFICATION",
+      "2FA",
+      "DELIVERY_NOTIFICATION",
+      "HIGHER_EDUCATION",
+      "POLLING_VOTING",
+      "PUBLIC_SERVICE_ANNOUNCEMENT",
+      "LOW_VOLUME"
+    ]);
+    A2pMessagingProfile = z.object({
+      useCase: A2pUseCase,
+      /** Specific, not generic. "We send texts" gets rejected; describe the actual
+       *  messages and when they are sent. */
+      description: z.string().trim().min(40).max(4096),
+      /**
+       * The single most-rejected field. Must describe HOW people opt in, state the
+       * message frequency, include the "message and data rates may apply"
+       * disclosure, and link to publicly reachable evidence. Twilio's API bounds it
+       * to 40–2049 characters.
+       */
+      messageFlow: z.string().trim().min(40).max(2049),
+      optInType: A2pOptInType,
+      /** Publicly accessible screenshots/pages showing the opt-in. Reviewers open
+       *  these; anything behind a login fails. */
+      optInEvidenceUrls: z.array(PublicUrl).min(1).max(5),
+      /** Real messages the customer will send. Must reflect the declared use case
+       *  and carry opt-out language. */
+      messageSamples: z.array(z.string().trim().min(10).max(1024)).min(2).max(5),
+      privacyPolicyUrl: PublicUrl,
+      termsAndConditionsUrl: PublicUrl,
+      hasEmbeddedLinks: z.boolean().default(false),
+      hasEmbeddedPhone: z.boolean().default(false)
+    });
+    z.object({
+      business: A2pBusinessInfo,
+      messaging: A2pMessagingProfile,
+      /** Register against Twilio's mock endpoints — exercises the full pipeline
+       *  with no fees and no real carrier submission. Used in CI and staging. */
+      mock: z.boolean().default(false)
+    }).superRefine((v, ctx) => {
+      const flow = v.messaging.messageFlow.toLowerCase();
+      if (!/(msg|message)\s*(&|and)\s*data rates/.test(flow)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["messaging", "messageFlow"],
+          message: 'must include a "Message and data rates may apply" disclosure \u2014 carriers reject without it'
+        });
+      }
+      if (!/\d/.test(flow) || !/(msg|message|text)/.test(flow)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["messaging", "messageFlow"],
+          message: 'must state message frequency, e.g. "Up to 4 msgs/month"'
+        });
+      }
+      const hasOptOut = v.messaging.messageSamples.some((s) => /stop/i.test(s));
+      if (!hasOptOut) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["messaging", "messageSamples"],
+          message: 'at least one sample must include opt-out language (e.g. "Reply STOP to opt out")'
+        });
+      }
+    });
+    A2pState = z.enum([
+      "none",
+      "profile_pending",
+      "profile_approved",
+      "profile_failed",
+      "brand_pending",
+      "brand_approved",
+      "brand_failed",
+      "campaign_pending",
+      "messaging_ready",
+      "campaign_failed"
+    ]);
+    z.object({
+      state: A2pState,
+      customerProfileSid: z.string().nullable(),
+      trustProductSid: z.string().nullable(),
+      brandSid: z.string().nullable(),
+      messagingServiceSid: z.string().nullable(),
+      campaignSid: z.string().nullable(),
+      mock: z.boolean(),
+      /** Carrier/Twilio rejection details, surfaced verbatim so the customer can
+       *  fix the specific field rather than guess. */
+      failures: z.array(z.object({ code: z.number().nullable(), field: z.string().nullable(), message: z.string() })).default([]),
+      /** Plain-language next step for the dashboard. */
+      nextAction: z.string().nullable(),
+      updatedAt: z.string().nullable()
+    });
+  }
+});
 var ConnectorMode, ConnectorStatus, ConnectorNormalize;
 var init_connector = __esm({
   "../contracts/src/connector.ts"() {
@@ -1931,6 +2137,8 @@ var init_src = __esm({
     init_call_recording();
     init_outbound();
     init_connection();
+    init_telephony();
+    init_a2p();
     init_connector();
     init_connector_stream();
     init_flow_compile();

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@voicelayer/sdk",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Official SDK for VoiceLayer — define, run, and orchestrate voice AI agents on the VoiceLayer control plane.",
   "license": "Apache-2.0",
   "author": "VoiceLayer",
-  "homepage": "https://github.com/paradox1612/voicelayer/tree/main/packages/sdk#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/paradox1612/voicelayer.git",
-    "directory": "packages/sdk"
-  },
+  "homepage": "https://vlayers.ai/docs/sdk",
   "bugs": {
-    "url": "https://github.com/paradox1612/voicelayer/issues"
+    "email": "customer@vlayers.ai"
   },
   "keywords": [
     "voicelayer",
@@ -81,14 +76,14 @@
     "vitest": "^4.1.5",
     "@voicelayer/contracts": "0.1.0",
     "@voicelayer/observability": "0.1.0",
-    "@voicelayer/primitive-audio-experience": "0.1.0",
     "@voicelayer/primitive-audio-routing": "0.1.0",
-    "@voicelayer/primitive-security": "0.1.0",
     "@voicelayer/primitive-process-schema": "0.1.0",
-    "@voicelayer/agents-plugin-deepgram": "1.0.0",
-    "@voicelayer/agents-plugin-livekit": "1.0.0",
-    "@voicelayer/agents-plugin-openai": "1.0.0",
-    "@voicelayer/agents-plugin-silero": "1.0.0"
+    "@voicelayer/agents-plugin-livekit": "1.0.1",
+    "@voicelayer/primitive-security": "0.1.0",
+    "@voicelayer/agents-plugin-openai": "1.0.1",
+    "@voicelayer/agents-plugin-silero": "1.0.1",
+    "@voicelayer/primitive-audio-experience": "0.1.0",
+    "@voicelayer/agents-plugin-deepgram": "1.0.1"
   },
   "scripts": {
     "typecheck": "tsc -b --pretty false",