@voicelayer/sdk 0.1.10 → 0.2.0

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/brain/index.d.ts

@@ -0,0 +1,283 @@
+import { Redis } from 'ioredis';
+import { z } from 'zod';
+
+/** Frames a daemon sends up to the relay. */
+declare const ConnectorUpFrame: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"hello">;
+    token: z.ZodString;
+    replicaId: z.ZodString;
+    version: z.ZodString;
+    caps: z.ZodObject<{
+        streaming: z.ZodBoolean;
+        tools: z.ZodBoolean;
+        litellm: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        tools: boolean;
+        streaming: boolean;
+        litellm: boolean;
+    }, {
+        tools: boolean;
+        streaming: boolean;
+        litellm: boolean;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    kind: "hello";
+    version: string;
+    token: string;
+    replicaId: string;
+    caps: {
+        tools: boolean;
+        streaming: boolean;
+        litellm: boolean;
+    };
+}, {
+    kind: "hello";
+    version: string;
+    token: string;
+    replicaId: string;
+    caps: {
+        tools: boolean;
+        streaming: boolean;
+        litellm: boolean;
+    };
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"pong">;
+    ts: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    kind: "pong";
+    ts: number;
+}, {
+    kind: "pong";
+    ts: number;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"brain.delta">;
+    streamId: z.ZodString;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "brain.delta";
+    content: string;
+    streamId: string;
+}, {
+    kind: "brain.delta";
+    content: string;
+    streamId: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"brain.done">;
+    streamId: z.ZodString;
+    finishReason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "brain.done";
+    streamId: string;
+    finishReason: string;
+}, {
+    kind: "brain.done";
+    streamId: string;
+    finishReason: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"brain.error">;
+    streamId: z.ZodString;
+    code: z.ZodEnum<["upstream_timeout", "upstream_error", "bad_response", "normalize_failed", "unreachable"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "brain.error";
+    code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
+    message: string;
+    streamId: string;
+}, {
+    kind: "brain.error";
+    code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
+    message: string;
+    streamId: string;
+}>]>;
+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. */
+declare function chatContextToMessages(chatCtx: unknown): BrainMessage[];
+/** The most recent user utterance, or '' if none. */
+declare function lastUserText(messages: readonly BrainMessage[]): string;
+
+interface ConnectorLLMOptions {
+    readonly model?: string;
+    readonly temperature?: number;
+    readonly callId?: string;
+    readonly projectId?: string;
+    /** Spoken instead of dead air when the brain errors before any reply. */
+    readonly fallbackText?: string;
+}
+/** One ChatChunk in the shape AgentSession consumes (subset of LK's ChatChunk). */
+interface ConnectorChatChunk {
+    readonly id: string;
+    readonly delta: {
+        readonly role: 'assistant';
+        readonly content: string;
+    };
+}
+/**
+ * Stream a brain reply as ChatChunks. On error before any content is emitted,
+ * falls back to `fallbackText` if provided; otherwise rethrows. Errors after
+ * partial output stop the stream (the partial is already spoken).
+ */
+declare function chatChunkStream(transport: BrainTransport, messages: ReturnType<typeof chatContextToMessages>, options: ConnectorLLMOptions, signal: AbortSignal): AsyncGenerator<ConnectorChatChunk>;
+/**
+ * Build a ConnectorLLM instance for the pipeline's `llm` slot. The returned
+ * object's chat() yields the brain reply and exposes close() for barge-in.
+ */
+declare function createConnectorLLM(transport: BrainTransport, options?: ConnectorLLMOptions): Promise<unknown>;
+
+interface ConnectorChatModelOptions {
+    readonly model?: string;
+}
+interface ChatModelInput {
+    readonly messages: readonly {
+        readonly role: 'system' | 'user' | 'assistant';
+        readonly content: string;
+    }[];
+    readonly json?: boolean;
+    readonly temperature?: number;
+    readonly model?: string;
+}
+declare class ConnectorChatModel {
+    private readonly transport;
+    private readonly options;
+    constructor(transport: BrainTransport, options?: ConnectorChatModelOptions);
+    /** `signal` cancels the brain request (the tunnel sends `brain.cancel`); a deadline is the caller's to set. */
+    complete(input: ChatModelInput, signal?: AbortSignal): Promise<string>;
+}
+
+declare class BrainConfigError extends Error {
+    constructor(message: string);
+}
+/** Resolve a hostname to a list of IP strings. Injectable for tests. */
+type HostLookup = (host: string) => Promise<readonly string[]>;
+interface AssertUrlOptions {
+    /** Hostnames that bypass IP checks (explicit per-connector allowlist). */
+    readonly allowHosts?: readonly string[];
+    /** Override DNS resolution (tests). */
+    readonly lookup?: HostLookup;
+}
+/** True if `ip` is a literal address we must refuse. */
+declare function isDisallowedIp(ip: string): boolean;
+/**
+ * Validate a brain URL for direct egress. Throws BrainConfigError on any
+ * violation; returns the parsed URL when safe.
+ */
+declare function assertPublicHttpsUrl(raw: string, opts?: AssertUrlOptions): Promise<URL>;
+
+interface HttpBrainTransportOptions {
+    readonly baseUrl: string;
+    readonly apiKey?: string;
+    readonly defaultModel?: string;
+    /** Hostnames that bypass the IP checks (tests, an allow-listed private brain). */
+    readonly allowHosts?: readonly string[];
+    /** Test seams. */
+    readonly fetchImpl?: typeof fetch;
+    readonly lookup?: HostLookup;
+}
+declare function httpBrainTransport(opts: HttpBrainTransportOptions): BrainTransport;
+
+declare class BrainRequestError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+
+interface BrainPubSub {
+    publish(channel: string, message: string): Promise<void>;
+    /** Subscribe to a channel; returns an unsubscribe handle. */
+    subscribe(channel: string, handler: (raw: string) => void): Promise<() => Promise<void>>;
+}
+interface TunnelBrainTransportOptions {
+    readonly connectorId: string;
+    readonly pubsub: BrainPubSub;
+    /** Fail the turn if the daemon sends nothing within this window. Default 20s. */
+    readonly firstChunkTimeoutMs?: number;
+}
+declare function tunnelBrainTransport(options: TunnelBrainTransportOptions): BrainTransport;
+
+declare class RedisBrainPubSub implements BrainPubSub {
+    private readonly sub;
+    private readonly pub;
+    private readonly listeners;
+    constructor(sub: Redis, pub: Redis);
+    publish(channel: string, message: string): Promise<void>;
+    subscribe(channel: string, handler: (raw: string) => void): Promise<() => Promise<void>>;
+    close(): Promise<void>;
+}
+declare function buildRedisBrainPubSub(redisUrl: string | undefined): RedisBrainPubSub | null;
+
+interface SseDelta {
+    readonly content?: string;
+    readonly finishReason?: string;
+}
+declare function parseChatCompletionSse(source: AsyncIterable<Uint8Array> | ReadableStream<Uint8Array>): AsyncGenerator<SseDelta>;
+
+interface BrainEndpointConfig {
+    /** Base URL of the OpenAI-compatible endpoint, e.g. http://localhost:4000/v1. */
+    readonly brainUrl: string;
+    readonly apiKey?: string;
+    readonly defaultModel?: string;
+    /** Injectable for tests; defaults to global fetch. */
+    readonly fetchImpl?: typeof fetch;
+    /** Refuse redirects (direct egress from VoiceLayer's own servers — the SSRF rule). Default: follow (the daemon). */
+    readonly refuseRedirects?: boolean;
+}
+interface IncomingBrainRequest {
+    readonly streamId: string;
+    readonly model?: string;
+    readonly temperature?: number;
+    readonly messages: ReadonlyArray<{
+        role: 'system' | 'user' | 'assistant';
+        content: string;
+    }>;
+}
+/** 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 };