supafone-labs 0.6.1 → 0.6.3

package/README.md

@@ -82,13 +82,70 @@ whisper to it live — a permanent vendor limitation, not a Supafone gap.
 are not conversational agents, so there is nothing to inject into.
 
 Injection is *possible* for all 10, but managed delivery is wired end-to-end
-**only for Ultravox today**; the other nine are supported via their native
-primitive with managed delivery rolling out / BYO. A live test against any vendor
+**only for the legacy managed Supervisor delivery path**; the other nine are
+supported via their native primitive with managed delivery rolling out / BYO.
+Native realtime Agent Factory delivery is a separate first-class path. A live test against any vendor
 needs that vendor's key — free/trial tiers exist for all except OpenAI Realtime
 (paid, no free tier). Full matrix:
 [gitbook/framework-support.md](../gitbook/framework-support.md). *(The npm
 package-page copy updates on the next release.)*
 
+## One S2S interface, five providers
+
+Version 0.6.3 exports `SupafoneS2S`, the shared parent of `UltravoxS2S`,
+`OpenAIS2S`, `GeminiS2S`, `GrokS2S`, and `HydraS2S`. These classes use
+Supafone's hosted Agent Factory. Supafone handles the audio adapter, tools,
+stages, and supported phone transport behind one API.
+
+```ts
+import { Supafone, HydraS2S, OpenAIS2S, UltravoxS2S } from "supafone-labs";
+
+const client = new Supafone({ apiKey: process.env.SUPAFONE_API_KEY! });
+const hydra = new HydraS2S(client, { model: "hydra-v1.1", voice: "maya" });
+const created = await hydra.create({
+  name: "Intake", goal: "Collect the caller's details and book a consultation",
+  telephony: { mode: "supafone_managed", provider: "supafone" },
+});
+const agentKey = created.agent.agent_key!;
+await hydra.testCall(agentKey);
+
+// Switch the same agent for its next call, preserving its assigned number.
+await new OpenAIS2S(client, { model: "gpt-realtime-2.1", voice: "marin" }).apply(agentKey);
+// Return to the existing default Ultravox runtime.
+await new UltravoxS2S(client).apply(agentKey);
+```
+
+`apply` saves a selection for subsequent calls. `testCall` previews the saved
+agent and does not implicitly switch providers. The same constructors and
+`create`, `apply`, and `test_call` methods are available in Python.
+
+| Provider family | Selection | Default voice |
+| --- | --- | --- |
+| Ultravox | Default hosted runtime (`realtime: null` resets it) | Agent voice settings |
+| OpenAI | `gpt-realtime-2.1` | `marin` |
+| OpenAI | `gpt-live-1` | `marin` |
+| Google | `gemini-3.1-flash-live-preview` | `Puck` |
+| xAI | `grok-voice-latest` | `eve` |
+| Smallest AI | `hydra-v1.1` | `maya` |
+| Smallest AI | `hydra-v1.0` | `sterling` |
+
+The existing `realtime: { provider, model, voice }` API remains supported.
+Native models use the fixed intake → booking → confirmation flow. The phone
+paths are Supafone-managed numbers, BYO Twilio, Telnyx, Plivo, and SIP through
+LiveKit. Carrier provisioning and credentials still determine call readiness.
+
+Supafone's configured server-side provider keys are used by default. An
+existing encrypted account key takes priority; customers do not need to add a
+provider key when Supafone has one configured. Missing keys produce an
+unavailable preview instead of a live provider call.
+
+Hydra supports English audio and tools, without transcript events or mutable
+mid-session persona/voice. Supafone supplies its fixed stages at session start
+and advances the stage using tool results. Hydra 1.1 uses 16 kHz input / 24 kHz
+output; 1.0 uses 16 kHz / 48 kHz and a different voice roster. Native sessions
+do not claim Ultravox's recording, Supervisor, transfer, or agent-team parity.
+See the [unified S2S guide](https://labs.supafone.ai/docs/unified-s2s/) and
+[capability matrix](https://labs.supafone.ai/docs/realtime-agent-factory/).
 ## Spawn a hosted Supafone agent
 
 Use the same package to create finished Supafone agents from code. This hits the

package/dist/cjs/index.d.ts

@@ -1,3 +1,5 @@
+export { SupafoneS2S, UltravoxS2S, OpenAIS2S, GeminiS2S, GrokS2S, HydraS2S } from "./s2s.js";
+export type { S2SProviderName, S2SModelOptions, S2SOptions } from "./s2s.js";
 /**
  * Supafone Labs — the agent framework behind Supafone.
  *
@@ -353,7 +355,7 @@ export interface LabsVoicePreference {
 }
 /** Direct speech-to-speech configuration for browser previews and carrier phone calls. */
 export interface LabsRealtimeSelection {
-    provider: "openai" | "google" | "xai";
+    provider: "openai" | "google" | "xai" | "smallest";
     model?: string;
     voice?: string;
 }
@@ -369,10 +371,21 @@ export interface LabsBrowserTestSession {
         provider: string;
         transport: "ultravox" | "supafone_realtime";
         join_url?: string | null;
-        websocket_url?: string;
-        token?: string;
+        websocket_url?: string | null;
+        token?: string | null;
         input_sample_rate?: number;
         output_sample_rate?: number;
+        capabilities?: {
+            stages?: boolean;
+            tools?: boolean;
+            transcripts?: boolean;
+            recording?: boolean;
+            supervisor?: boolean;
+            transfer?: boolean;
+            mutable_instructions?: boolean;
+            stage_update_mode?: string;
+            languages?: string[];
+        };
     };
 }
 export interface LabsProviderKeys {
@@ -449,6 +462,9 @@ export interface LabsProviderKeys {
     xai?: string;
     xaiApiKey?: string;
     xai_api_key?: string;
+    smallest?: string;
+    smallestApiKey?: string;
+    smallest_api_key?: string;
     [extra: string]: unknown;
 }
 export interface LabsCustomSipConfig {
@@ -959,7 +975,10 @@ export interface LabsAgentReadiness {
     checks?: Array<Record<string, unknown>>;
     [extra: string]: unknown;
 }
-export type UpdateLabsAgentRequest = Partial<CreateLabsAgentRequest>;
+export type UpdateLabsAgentRequest = Omit<Partial<CreateLabsAgentRequest>, "realtime"> & {
+    /** Select another native model, or null to return to the default Ultravox runtime. */
+    realtime?: LabsRealtimeSelection | null;
+};
 export interface LabsAgentLifecycleResponse {
     success?: boolean;
     agent?: LabsAgentResponse;
@@ -2214,7 +2233,7 @@ declare class LabsBillingNamespace {
 declare class LabsAgentsNamespace {
     private sm;
     constructor(sm: SupafoneLabs);
-    /** Spawn a durable hosted Supafone agent backed by Ultravox and Supafone-managed providers. */
+    /** Create a hosted Supafone agent with the default Ultravox runtime or a selected native S2S model. */
     create(input: CreateLabsAgentRequest): Promise<CreateLabsAgentResponse>;
     /** Preview the exact validated call-plan contract the Supafone runtime executes. */
     plan(input: CreateLabsAgentRequest & {

package/dist/cjs/index.js

@@ -1,30 +1,16 @@
 "use strict";
-/**
- * Supafone Labs — the agent framework behind Supafone.
- *
- * A dependency-free TypeScript client for creating hosted Supafone agents
- * through the Supafone API, including managed phone numbers, voices, stages,
- * tools, recordings, transcripts, widgets, and Supafone Supervisor. It also
- * includes Supafone Supervisor, hosted TTS/STT, live multilingual
- * transcription, telemetry, agent builder, and objective-driven optimizer.
- *
- * Works in Node 18+ (native fetch/WebSocket) and the browser.
- *
- *   npm i supafone-labs
- *
- *   import { Supafone } from "supafone-labs";
- *   const supafone = new Supafone({ apiKey: process.env.SUPAFONE_API_KEY! });
- *   const agent = await supafone.labs.agents.createInboundWithNumber({
- *     agentKey: "northline-intake",
- *     name: "Northline intake",
- *     number: { search: { areaCode: "415" } },
- *   });
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Supafone = exports.SupafoneLabs = exports.SupafoneLabsError = exports.OUTBOUND_CALL_MODE_PROVIDER_MATRIX = exports.OUTBOUND_CALL_MODE_DEFAULTS = exports.OUTBOUND_CALL_MODE_BOUNDS = void 0;
+exports.Supafone = exports.SupafoneLabs = exports.SupafoneLabsError = exports.OUTBOUND_CALL_MODE_PROVIDER_MATRIX = exports.OUTBOUND_CALL_MODE_DEFAULTS = exports.OUTBOUND_CALL_MODE_BOUNDS = exports.HydraS2S = exports.GrokS2S = exports.GeminiS2S = exports.OpenAIS2S = exports.UltravoxS2S = exports.SupafoneS2S = void 0;
 exports.outboundCallModeProviderProfile = outboundCallModeProviderProfile;
 exports.outboundCallModeReadiness = outboundCallModeReadiness;
 exports.generateCallStages = generateCallStages;
+var s2s_js_1 = require("./s2s.js");
+Object.defineProperty(exports, "SupafoneS2S", { enumerable: true, get: function () { return s2s_js_1.SupafoneS2S; } });
+Object.defineProperty(exports, "UltravoxS2S", { enumerable: true, get: function () { return s2s_js_1.UltravoxS2S; } });
+Object.defineProperty(exports, "OpenAIS2S", { enumerable: true, get: function () { return s2s_js_1.OpenAIS2S; } });
+Object.defineProperty(exports, "GeminiS2S", { enumerable: true, get: function () { return s2s_js_1.GeminiS2S; } });
+Object.defineProperty(exports, "GrokS2S", { enumerable: true, get: function () { return s2s_js_1.GrokS2S; } });
+Object.defineProperty(exports, "HydraS2S", { enumerable: true, get: function () { return s2s_js_1.HydraS2S; } });
 exports.OUTBOUND_CALL_MODE_BOUNDS = {
     maxDurationSeconds: { default: 180, min: 30, max: 900 },
     maxKeypresses: { default: 12, min: 1, max: 64 },
@@ -1202,7 +1188,7 @@ class LabsAgentsNamespace {
     constructor(sm) {
         this.sm = sm;
     }
-    /** Spawn a durable hosted Supafone agent backed by Ultravox and Supafone-managed providers. */
+    /** Create a hosted Supafone agent with the default Ultravox runtime or a selected native S2S model. */
     create(input) {
         return this.sm.requestSupafoneApi("POST", "/api/v1/labs/agents", labsAgentPayload(this.withSupervisor(input)));
     }
@@ -2037,7 +2023,10 @@ function labsAgentMetadataPayload(input) {
     return Object.keys(metadata).length ? metadata : undefined;
 }
 function labsAgentUpdatePayload(input) {
-    return labsAgentPayload(input);
+    const payload = labsAgentPayload(input);
+    if (input.realtime === null)
+        payload.realtime = null;
+    return payload;
 }
 function campaignSettingsPayload(settings, mode) {
     const payload = { ...(settings ?? {}) };
@@ -2405,6 +2394,8 @@ function providerKeysPayload(input) {
         openai_api_key: input.openai_api_key ?? input.openaiApiKey,
         xai: input.xai,
         xai_api_key: input.xai_api_key ?? input.xaiApiKey,
+        smallest: input.smallest,
+        smallest_api_key: input.smallest_api_key ?? input.smallestApiKey,
     });
 }
 function byokPayload(input) {

package/dist/cjs/s2s.d.ts

@@ -0,0 +1,41 @@
+import type { CreateLabsAgentRequest, GetLabsAgentOptions, LabsRealtimeSelection, SupafoneLabs } from "./index.js";
+export type S2SProviderName = "ultravox" | "openai" | "google" | "xai" | "smallest";
+export interface S2SModelOptions {
+    model?: string;
+    voice?: string;
+}
+export interface S2SOptions extends S2SModelOptions {
+    provider?: S2SProviderName;
+}
+/** Shared parent for Supafone-hosted S2S agents. Vendor keys stay on the server. */
+export declare class SupafoneS2S {
+    protected readonly client: SupafoneLabs;
+    readonly provider: S2SProviderName;
+    private readonly selection;
+    constructor(client: SupafoneLabs, options?: S2SOptions);
+    /** A fresh wire selection; null explicitly restores the default Ultravox runtime. */
+    get realtime(): LabsRealtimeSelection | null;
+    /** Create through the normal hosted agent factory with this provider. */
+    create(input: Omit<CreateLabsAgentRequest, "realtime">): Promise<import("./index.js").CreateLabsAgentResponse>;
+    /** Change the saved selection for subsequent calls, preserving the agent and number. */
+    apply(agentKey: string, options?: GetLabsAgentOptions): Promise<import("./index.js").LabsAgentLifecycleResponse>;
+    /** Preview the saved agent. Call apply first when switching providers. */
+    testCall(agentKey: string, options?: GetLabsAgentOptions): Promise<import("./index.js").LabsBrowserTestSession>;
+    private checkAgentKey;
+}
+export declare class UltravoxS2S extends SupafoneS2S {
+    constructor(client: SupafoneLabs);
+}
+export declare class OpenAIS2S extends SupafoneS2S {
+    constructor(client: SupafoneLabs, options?: S2SModelOptions);
+}
+export declare class GeminiS2S extends SupafoneS2S {
+    constructor(client: SupafoneLabs, options?: S2SModelOptions);
+}
+export declare class GrokS2S extends SupafoneS2S {
+    constructor(client: SupafoneLabs, options?: S2SModelOptions);
+}
+/** Smallest AI Hydra: full-duplex audio, without transcript events. */
+export declare class HydraS2S extends SupafoneS2S {
+    constructor(client: SupafoneLabs, options?: S2SModelOptions);
+}

package/dist/cjs/s2s.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HydraS2S = exports.GrokS2S = exports.GeminiS2S = exports.OpenAIS2S = exports.UltravoxS2S = exports.SupafoneS2S = void 0;
+/** Shared parent for Supafone-hosted S2S agents. Vendor keys stay on the server. */
+class SupafoneS2S {
+    client;
+    provider;
+    selection;
+    constructor(client, options = {}) {
+        this.client = client;
+        const provider = options.provider ?? "ultravox";
+        if (!["ultravox", "openai", "google", "xai", "smallest"].includes(provider)) {
+            throw new Error("Unsupported Supafone S2S provider");
+        }
+        if (provider === "ultravox" && (options.model !== undefined || options.voice !== undefined)) {
+            throw new Error("Configure Ultravox voices through the agent's voice settings");
+        }
+        for (const field of ["model", "voice"]) {
+            const value = options[field];
+            if (value !== undefined && (typeof value !== "string" || !value.trim())) {
+                throw new Error(`${field} must be a non-empty string`);
+            }
+        }
+        this.provider = provider;
+        this.selection = provider === "ultravox" ? null : {
+            provider,
+            ...(options.model !== undefined ? { model: options.model.trim() } : {}),
+            ...(options.voice !== undefined ? { voice: options.voice.trim() } : {}),
+        };
+    }
+    /** A fresh wire selection; null explicitly restores the default Ultravox runtime. */
+    get realtime() {
+        return this.selection ? { ...this.selection } : null;
+    }
+    /** Create through the normal hosted agent factory with this provider. */
+    create(input) {
+        if ("realtime" in input) {
+            throw new Error("Set provider/model/voice on the S2S adapter, not create({realtime: ...})");
+        }
+        return this.client.labs.agents.create({
+            ...input,
+            ...(this.realtime ? { realtime: this.realtime } : {}),
+        });
+    }
+    /** Change the saved selection for subsequent calls, preserving the agent and number. */
+    apply(agentKey, options = {}) {
+        this.checkAgentKey(agentKey);
+        return this.client.labs.agents.update(agentKey, { realtime: this.realtime }, options);
+    }
+    /** Preview the saved agent. Call apply first when switching providers. */
+    testCall(agentKey, options = {}) {
+        this.checkAgentKey(agentKey);
+        return this.client.labs.agents.testCall(agentKey, options);
+    }
+    checkAgentKey(agentKey) {
+        if (typeof agentKey !== "string" || !agentKey.trim())
+            throw new Error("agentKey is required");
+    }
+}
+exports.SupafoneS2S = SupafoneS2S;
+class UltravoxS2S extends SupafoneS2S {
+    constructor(client) { super(client, { provider: "ultravox" }); }
+}
+exports.UltravoxS2S = UltravoxS2S;
+class OpenAIS2S extends SupafoneS2S {
+    constructor(client, options = {}) {
+        super(client, { ...options, provider: "openai" });
+    }
+}
+exports.OpenAIS2S = OpenAIS2S;
+class GeminiS2S extends SupafoneS2S {
+    constructor(client, options = {}) {
+        super(client, { ...options, provider: "google" });
+    }
+}
+exports.GeminiS2S = GeminiS2S;
+class GrokS2S extends SupafoneS2S {
+    constructor(client, options = {}) {
+        super(client, { ...options, provider: "xai" });
+    }
+}
+exports.GrokS2S = GrokS2S;
+/** Smallest AI Hydra: full-duplex audio, without transcript events. */
+class HydraS2S extends SupafoneS2S {
+    constructor(client, options = {}) {
+        super(client, { ...options, provider: "smallest" });
+    }
+}
+exports.HydraS2S = HydraS2S;

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { SupafoneS2S, UltravoxS2S, OpenAIS2S, GeminiS2S, GrokS2S, HydraS2S } from "./s2s.js";
+export type { S2SProviderName, S2SModelOptions, S2SOptions } from "./s2s.js";
 /**
  * Supafone Labs — the agent framework behind Supafone.
  *
@@ -353,7 +355,7 @@ export interface LabsVoicePreference {
 }
 /** Direct speech-to-speech configuration for browser previews and carrier phone calls. */
 export interface LabsRealtimeSelection {
-    provider: "openai" | "google" | "xai";
+    provider: "openai" | "google" | "xai" | "smallest";
     model?: string;
     voice?: string;
 }
@@ -369,10 +371,21 @@ export interface LabsBrowserTestSession {
         provider: string;
         transport: "ultravox" | "supafone_realtime";
         join_url?: string | null;
-        websocket_url?: string;
-        token?: string;
+        websocket_url?: string | null;
+        token?: string | null;
         input_sample_rate?: number;
         output_sample_rate?: number;
+        capabilities?: {
+            stages?: boolean;
+            tools?: boolean;
+            transcripts?: boolean;
+            recording?: boolean;
+            supervisor?: boolean;
+            transfer?: boolean;
+            mutable_instructions?: boolean;
+            stage_update_mode?: string;
+            languages?: string[];
+        };
     };
 }
 export interface LabsProviderKeys {
@@ -449,6 +462,9 @@ export interface LabsProviderKeys {
     xai?: string;
     xaiApiKey?: string;
     xai_api_key?: string;
+    smallest?: string;
+    smallestApiKey?: string;
+    smallest_api_key?: string;
     [extra: string]: unknown;
 }
 export interface LabsCustomSipConfig {
@@ -959,7 +975,10 @@ export interface LabsAgentReadiness {
     checks?: Array<Record<string, unknown>>;
     [extra: string]: unknown;
 }
-export type UpdateLabsAgentRequest = Partial<CreateLabsAgentRequest>;
+export type UpdateLabsAgentRequest = Omit<Partial<CreateLabsAgentRequest>, "realtime"> & {
+    /** Select another native model, or null to return to the default Ultravox runtime. */
+    realtime?: LabsRealtimeSelection | null;
+};
 export interface LabsAgentLifecycleResponse {
     success?: boolean;
     agent?: LabsAgentResponse;
@@ -2214,7 +2233,7 @@ declare class LabsBillingNamespace {
 declare class LabsAgentsNamespace {
     private sm;
     constructor(sm: SupafoneLabs);
-    /** Spawn a durable hosted Supafone agent backed by Ultravox and Supafone-managed providers. */
+    /** Create a hosted Supafone agent with the default Ultravox runtime or a selected native S2S model. */
     create(input: CreateLabsAgentRequest): Promise<CreateLabsAgentResponse>;
     /** Preview the exact validated call-plan contract the Supafone runtime executes. */
     plan(input: CreateLabsAgentRequest & {