@voicelayer/sdk 0.1.11 → 0.3.0

package/README.md

@@ -328,6 +328,14 @@ export DEEPGRAM_API_KEY=...
 node agent.ts start
 ```
 
+### Texts
+
+The same worker answers texts — SMS replies, Discord, your website's chat widget, the dashboard playground. `.start()`
+registers a second LiveKit name, `<name>::text`, beside the voice one; each message is dispatched to it and runs as
+your agent: its tools, security, connectors and model, with the conversation so far. Over text `ctx.call.callerId` is
+the sender, `ctx.call.metadata.mode` is `'text'`, and call-only methods (`handoff`, `endCall`, `ask`, DTMF) throw. In
+production the text registration's health server listens on `VL_TEXT_TURN_PORT` (default 8082).
+
 ---
 
 ## What's *not* in this SDK

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, {
+    code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
+    message: string;
+    kind: "brain.error";
+    streamId: string;
+}, {
+    code: "upstream_timeout" | "upstream_error" | "bad_response" | "normalize_failed" | "unreachable";
+    message: string;
+    kind: "brain.error";
+    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 };