supafone-labs 0.6.3 → 0.7.0

package/README.md

@@ -52,47 +52,36 @@ silent directive, and the exact primitive for each, is in
 
 ## Supported frameworks
 
-Silent injection feeds the live agent hidden guidance it acts on but never
-speaks. Two mechanisms cover every supported framework:
-
-- **Mode A — native silent event:** speech-to-speech models take a vendor event
-  that adds context without triggering speech.
-- **Mode B — own the LLM:** for STT→LLM→TTS pipelines, Supafone plugs in as the
-  LLM and splices a `system`/`developer` message into the prompt.
-
-**Possible — 10 frameworks**, each with a real injection door:
-
-| Framework | Mode | Exact primitive |
-| --- | :--: | --- |
-| Ultravox | A | `send_data_message` (`urgency:"later"`) — **live/proven today** |
-| OpenAI Realtime | A | `conversation.item.create` (role `system`, no `response.create`) |
-| Grok (xAI) | A | OpenAI-Realtime-compatible item inject |
-| Gemini Live | A | `clientContent` (`turnComplete:false`, role `user`) |
-| ElevenLabs | A | `contextual_update` |
-| Inworld | A | OpenAI-Realtime-compatible item inject |
-| Vapi | A+B | `add-message` (`triggerResponseEnabled:false`) or custom-LLM splice |
-| Retell | B | `system` message into the custom-LLM turn |
-| Deepgram | A+B | `UpdatePrompt`, or own the `think` LLM |
-| LiveKit | B | inject into `chat_ctx` in-process |
-
-**Impossible — Bland:** its live-call API is stop/listen/transfer only, with no
-mid-call inject channel and no custom-LLM. Observe and score it, but you cannot
-whisper to it live — a permanent vendor limitation, not a Supafone gap.
-**Cartesia** (a TTS voice) and **Pipecat** (a DIY framework you own end to end)
-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 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.)*
+Supervisor delivers approved guidance through the control surface exposed by
+the selected adapter. The standalone SDK and hosted Agent Factory have separate
+capability contracts:
+
+- **Native control adapters:** Supafone/Ultravox, OpenAI Realtime, Grok,
+  Vapi, ElevenLabs Agents, Deepgram Voice Agent and Inworld Realtime.
+  For example, Ultravox uses a deferred data message; Grok uses
+  `response.create.instructions`, with `response.created` followed by
+  `response.done` as protocol acknowledgement.
+- **Developer-owned conversation context:** Retell custom LLM, LiveKit Agents
+  and Pipecat apply guidance inside the loop the integrator controls.
+- **Observation-only by default:** Gemini Developer Live and Bland emit no
+  hidden instruction through the default standalone adapter. Ordinary Gemini
+  `clientContent` is conversation history, not privileged system control.
+  Cartesia Line needs an explicit custom-event hook in the target agent.
+
+Hosted Agent Factory supports coaching across Ultravox, OpenAI, Gemini, Grok
+and Hydra through its managed call paths. Native calls use `check_guidance`
+tool results; Hydra's live observations are model-reported because it supplies
+no native transcript stream. This does not change the standalone adapter's
+capabilities or prove that a model followed the guidance.
+
+See the [framework matrix](../gitbook/framework-support.md) and
+[provider contracts](../docs/providers.md) for delivery and acceptance details.
+Live validation requires configured provider access; local contract tests do
+not certify a production call.
 
 ## One S2S interface, five providers
 
-Version 0.6.3 exports `SupafoneS2S`, the shared parent of `UltravoxS2S`,
+Since version 0.6.3, the SDK 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.
@@ -130,7 +119,8 @@ agent and does not implicitly switch providers. The same constructors and
 | 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
+All five speaking families use the shared generated/custom stage plan, Manager
+and specialist consultations. The phone
 paths are Supafone-managed numbers, BYO Twilio, Telnyx, Plivo, and SIP through
 LiveKit. Carrier provisioning and credentials still determine call readiness.
 
@@ -140,12 +130,23 @@ 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
+mid-session persona/voice. Supafone supplies the frozen call plan 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.
+support opt-in recording, public widgets, configured carrier controls and
+allowed-model handoff. A handoff opens a replacement session; a carrier transfer
+acknowledgement does not mean a human answered. Hydra has no live transcript
+stream; optional post-call transcription needs a recording and server Deepgram
+credentials. Ultravox retains compatible external TTS and its profile router.
+All five hosted speaking families support optional Supervisor coaching. Native
+models receive guidance through `check_guidance`; Hydra supplies explicitly
+labeled model-reported context rather than transcripts.
 See the [unified S2S guide](https://labs.supafone.ai/docs/unified-s2s/) and
 [capability matrix](https://labs.supafone.ai/docs/realtime-agent-factory/).
+See [Shared runtime, Manager and teams](https://labs.supafone.ai/docs/shared-agent-runtime/)
+for `manager`, `agentTeam`, structured stage requirements, `recording` and
+`runtimeRouting`. Both SDKs preserve explicit empty stage-tool and edge arrays.
+
 ## Spawn a hosted Supafone agent
 
 Use the same package to create finished Supafone agents from code. This hits the
@@ -229,7 +230,7 @@ import { Supafone } from "supafone-labs";
 const supafone = new Supafone({
   apiKey: process.env.SUPAFONE_LABS_API_KEY || process.env.SUPAFONE_API_KEY!,
   supafoneApiKey: process.env.SUPAFONE_API_KEY!,
-  // Supafone Supervisor is on by default for live guidance, QA, and scoring.
+  // Requests Supervisor by default; its model credentials must also be configured.
   // Set false only when you intentionally need an unsupervised agent.
   supervisor: true,
   // Defaults to https://api.supafone.ai. Override for staging/local tests.
@@ -257,11 +258,7 @@ const inbound = await supafone.labs.agents.createInboundWithNumber({
   },
   recording: {
     enabled: true,
-    recordAudio: true,
-    consentRequired: true,
-    announcement: "This call may be recorded for quality and training.",
-    retentionDays: 30,
-    redactPii: true,
+    transcribe: true,
   },
   transcription: {
     enabled: true,
@@ -384,37 +381,40 @@ agent; fetches it back; verifies `runtime.telephony.mode` is `supafone_managed`
 and the runtime is managed (`runtime.managed === true`, no developer Ultravox key
 required); and prints the returned widget snippet.
 
-## Hosted voices
+## Hosted voices: Ultravox + custom TTS
 
-Select a current provider voice from plain-language intent:
+The managed Ultravox option remains part of the shared S2S offering. Its
+conversation runtime and compatible TTS voice are separate choices:
 
 ```ts
-const matches = await supafone.labs.voices.recommend({
-  description: "calm Spanish customer-support voice",
-  language: "es-MX",
-  configuredOnly: true,
-});
+import { UltravoxS2S } from "supafone-labs";
 
-const voice = matches.matches[0].voice;
-await supafone.labs.agents.createInbound({
+const catalog = await supafone.labs.voices.list({ provider: "cartesia" });
+console.log(catalog.voices);
+
+await new UltravoxS2S(supafone).create({
   name: "Spanish support",
-  voice: supafone.labs.voices.selection(voice),
+  voice: { provider: "cartesia", voiceId: process.env.CARTESIA_VOICE_ID! },
 });
 ```
 
-The hosted catalog refreshes Ultravox, Cartesia, ElevenLabs, and Inworld and
-normalizes names, languages, gender, accent, voice type, model limits, and the
-Ultravox-compatible language intersection. Full reference:
-[Dynamic Voice Catalog and Selection](../gitbook/voice-catalog-and-selection.md).
-
-Labs Cloud also exposes direct hosted TTS and STT:
-
-```ts
-const wav = await supafone.tts("You're all set — talk soon!", "supafone-labs-calm-en");
-// wav: Uint8Array
-
-const text = await supafone.stt(audioBytes, { language: "en" });
-```
+Use a real, configured catalog voice. Compatible Ultravox, Cartesia, ElevenLabs,
+and Inworld voices can supply the managed agent's speech. Native OpenAI,
+Gemini, Grok, and Hydra use their own model voices; external TTS is not a
+universal override. Deepgram is preview-only in the current hosted Ultravox
+integration. Custom TTS backends are for developer-owned synthesis unless a
+hosted runtime bridge explicitly supports them.
+
+The published SDK 0.7.0 exposes `labs.voices.list`, `listAll`, `capabilities`,
+`recommend`, `preview`, and `selection`. Use `listAll` for automatic catalog
+pagination, then pass `selection(voice)` into managed agent creation. These
+helpers query the hosted voice catalog; they do not enable external TTS on
+native OpenAI, Gemini, Grok, or Hydra sessions.
+See [voice-output choices](https://labs.supafone.ai/docs/voice-output-modes/) and
+[the voice catalog](https://labs.supafone.ai/docs/voice-catalog-and-selection/).
+
+Labs Cloud's standalone `tts` and `stt` methods remain separate synthesis and
+transcription tools; using them does not change a saved agent's speaking model.
 
 ## Live multilingual transcription
 

package/dist/cjs/index.d.ts

@@ -199,8 +199,74 @@ export interface LabsCallStage {
     temperature?: number;
     nextStages?: string[];
     next_stages?: string[];
+    /** Server-enforced exit gates, independent of conversational exit criteria. */
+    requirements?: LabsStageRequirements;
+    role?: string;
+    specialistId?: string;
+    specialist_id?: string;
     metadata?: Record<string, unknown>;
 }
+export interface LabsStageRequirements {
+    requiredFields?: string[];
+    required_fields?: string[];
+    successfulTools?: string[];
+    successful_tools?: string[];
+}
+export interface LabsManagerConfig {
+    enabled?: boolean;
+    /** Reuse the existing encrypted Supervisor profile, or use managed reasoning. */
+    reasoning?: "managed" | "supervisor";
+    model?: "supafone-manager" | "supafone-manager-pro";
+    maxTasks?: number;
+    max_tasks?: number;
+    maxParallel?: number;
+    max_parallel?: number;
+    timeoutSeconds?: number;
+    timeout_seconds?: number;
+}
+export interface LabsSpecialist {
+    id: string;
+    role?: string;
+    label?: string;
+    description?: string;
+    instructions?: string;
+    enabled?: boolean;
+    stageKeys?: string[];
+    stage_keys?: string[];
+    tools?: string[];
+}
+export interface LabsAgentTeam {
+    enabled?: boolean;
+    routingMode?: "auto" | "sequential";
+    routing_mode?: "auto" | "sequential";
+    fallbackMemberId?: string;
+    fallback_member_id?: string;
+    members?: LabsSpecialist[];
+    routingRules?: Array<{
+        intent: string;
+        member_id: string;
+        priority?: string;
+        action?: string;
+    }>;
+    routing_rules?: Array<{
+        intent: string;
+        member_id: string;
+        priority?: string;
+        action?: string;
+    }>;
+}
+export interface LabsRuntimeRoutingConfig {
+    enabled?: boolean;
+    allowedModels?: LabsRealtimeSelection[];
+    allowed_models?: LabsRealtimeSelection[];
+    /** Server-supported range is 1–3 handoffs per call. */
+    maxHandoffs?: number;
+    max_handoffs?: number;
+    recoverOnDisconnect?: boolean;
+    recover_on_disconnect?: boolean;
+    allowedLanguages?: string[];
+    allowed_languages?: string[];
+}
 export type LabsStageGeneration = "managed" | "template" | "off" | "oracle";
 export interface LabsCallPlan {
     version: "supafone_call_plan_v1" | string;
@@ -646,6 +712,8 @@ export interface LabsEmailConfig {
 }
 export interface LabsRecordingConfig {
     enabled?: boolean;
+    /** Request post-call transcription of the recording where configured. */
+    transcribe?: boolean;
     recordAudio?: boolean;
     record_audio?: boolean;
     consentRequired?: boolean;
@@ -885,6 +953,17 @@ export interface CreateLabsAgentRequest {
     presetKey?: string;
     preset_key?: string;
     realtime?: LabsRealtimeSelection;
+    manager?: boolean | LabsManagerConfig;
+    agentTeam?: LabsAgentTeam;
+    agent_team?: LabsAgentTeam;
+    runtimeRouting?: LabsRuntimeRoutingConfig;
+    runtime_routing?: LabsRuntimeRoutingConfig;
+    captureFields?: string[];
+    capture_fields?: string[];
+    timezone?: string;
+    businessTimezone?: string;
+    timeAwareness?: boolean;
+    time_awareness?: boolean;
     runtimeMode?: LabsRuntimeMode;
     runtime_mode?: LabsRuntimeMode;
     /** Defaults to Supafone's hosted planner; model credentials remain server-side. */
@@ -927,7 +1006,7 @@ export interface CreateLabsAgentRequest {
     customSip?: LabsCustomSipConfig;
     custom_sip?: LabsCustomSipConfig;
     sip?: LabsCustomSipConfig;
-    recording?: LabsRecordingConfig;
+    recording?: boolean | LabsRecordingConfig;
     transcription?: LabsTranscriptionConfig;
     artifacts?: LabsArtifactsConfig;
     compliance?: Record<string, unknown>;

package/dist/cjs/index.js

@@ -2015,6 +2015,40 @@ function outboundCallModeRequiredCapabilities(payload) {
         required.push("observability");
     return required;
 }
+function managerPayload(input) {
+    if (typeof input !== "object" || input === null)
+        return input;
+    return compact({
+        enabled: input.enabled, reasoning: input.reasoning, model: input.model,
+        max_tasks: input.max_tasks ?? input.maxTasks,
+        max_parallel: input.max_parallel ?? input.maxParallel,
+        timeout_seconds: input.timeout_seconds ?? input.timeoutSeconds,
+    });
+}
+function agentTeamPayload(input) {
+    if (!input)
+        return undefined;
+    return compact({
+        enabled: input.enabled, routing_mode: input.routing_mode ?? input.routingMode,
+        fallback_member_id: input.fallback_member_id ?? input.fallbackMemberId,
+        routing_rules: input.routing_rules ?? input.routingRules,
+        members: input.members?.map((member) => compact({
+            id: member.id, role: member.role, label: member.label, description: member.description,
+            instructions: member.instructions, enabled: member.enabled, tools: member.tools,
+            stage_keys: member.stage_keys ?? member.stageKeys,
+        })),
+    });
+}
+function runtimeRoutingPayload(input) {
+    if (!input)
+        return undefined;
+    return compact({
+        enabled: input.enabled, allowed_models: input.allowed_models ?? input.allowedModels,
+        max_handoffs: input.max_handoffs ?? input.maxHandoffs,
+        recover_on_disconnect: input.recover_on_disconnect ?? input.recoverOnDisconnect,
+        allowed_languages: input.allowed_languages ?? input.allowedLanguages,
+    });
+}
 function labsAgentMetadataPayload(input) {
     const metadata = { ...(input.metadata ?? {}) };
     const mode = input.outboundCallMode ?? input.outbound_call_mode;
@@ -2056,6 +2090,12 @@ function labsAgentPayload(input) {
         preset_key: input.preset_key ?? input.presetKey,
         runtime_mode: input.runtime_mode ?? input.runtimeMode,
         realtime: input.realtime,
+        manager: managerPayload(input.manager),
+        agent_team: agentTeamPayload(input.agent_team ?? input.agentTeam),
+        runtime_routing: runtimeRoutingPayload(input.runtime_routing ?? input.runtimeRouting),
+        capture_fields: input.capture_fields ?? input.captureFields,
+        timezone: input.timezone ?? input.businessTimezone,
+        time_awareness: input.time_awareness ?? input.timeAwareness,
         call_stages: callStagesPayload(input),
         stage_generation: input.stage_generation ?? input.stageGeneration,
         stage_count: input.stage_count ?? input.stageCount,
@@ -2073,7 +2113,7 @@ function labsAgentPayload(input) {
         byok: input.byok ? byokPayload(input.byok) : undefined,
         telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
         custom_sip: customSipPayload(input.custom_sip ?? input.customSip ?? input.sip),
-        recording: input.recording ? recordingPayload(input.recording) : undefined,
+        recording: input.recording !== undefined ? recordingPayload(input.recording) : undefined,
         transcription: input.transcription ? transcriptionPayload(input.transcription) : undefined,
         artifacts: input.artifacts ? artifactsPayload(input.artifacts) : undefined,
         compliance: input.compliance,
@@ -2217,9 +2257,6 @@ function callStagesPayload(input) {
         return explicit;
     if (explicit === "oracle")
         return "managed";
-    // The S2S backend owns its validated intake → booking → confirmation flow.
-    if (input.realtime)
-        return undefined;
     // Omitted means the private Supafone API generates and compiles the plan.
     return undefined;
 }
@@ -2236,8 +2273,7 @@ function stagePlanPayload(input) {
         system_prompt: input.system_prompt ?? input.systemPrompt,
         tools: input.tools ? toolsPayload(input.tools) : undefined,
         call_stages: Array.isArray(input.call_stages ?? input.callStages ?? input.stages)
-            ? (input.call_stages ?? input.callStages ?? input.stages)
-            : undefined,
+            ? callStagesPayload(input) : undefined,
         stage_generation: input.stage_generation ?? input.stageGeneration,
         stage_count: input.stage_count ?? input.stageCount,
         stage_detail: input.stage_detail ?? input.stageDetail,
@@ -2253,6 +2289,12 @@ function callStagePayload(input) {
         tools: input.tools,
         temperature: input.temperature,
         next_stages: input.next_stages ?? input.nextStages,
+        requirements: input.requirements ? compact({
+            required_fields: input.requirements.required_fields ?? input.requirements.requiredFields,
+            successful_tools: input.requirements.successful_tools ?? input.requirements.successfulTools,
+        }) : undefined,
+        role: input.role,
+        specialist_id: input.specialist_id ?? input.specialistId,
         metadata: input.metadata,
     });
 }
@@ -2471,8 +2513,11 @@ function emailPayload(input) {
     });
 }
 function recordingPayload(input) {
+    if (typeof input === "boolean")
+        return input;
     return compact({
         enabled: input.enabled,
+        transcribe: input.transcribe,
         record_audio: input.record_audio ?? input.recordAudio,
         consent_required: input.consent_required ?? input.consentRequired,
         announcement: input.announcement,

package/dist/index.d.ts

@@ -199,8 +199,74 @@ export interface LabsCallStage {
     temperature?: number;
     nextStages?: string[];
     next_stages?: string[];
+    /** Server-enforced exit gates, independent of conversational exit criteria. */
+    requirements?: LabsStageRequirements;
+    role?: string;
+    specialistId?: string;
+    specialist_id?: string;
     metadata?: Record<string, unknown>;
 }
+export interface LabsStageRequirements {
+    requiredFields?: string[];
+    required_fields?: string[];
+    successfulTools?: string[];
+    successful_tools?: string[];
+}
+export interface LabsManagerConfig {
+    enabled?: boolean;
+    /** Reuse the existing encrypted Supervisor profile, or use managed reasoning. */
+    reasoning?: "managed" | "supervisor";
+    model?: "supafone-manager" | "supafone-manager-pro";
+    maxTasks?: number;
+    max_tasks?: number;
+    maxParallel?: number;
+    max_parallel?: number;
+    timeoutSeconds?: number;
+    timeout_seconds?: number;
+}
+export interface LabsSpecialist {
+    id: string;
+    role?: string;
+    label?: string;
+    description?: string;
+    instructions?: string;
+    enabled?: boolean;
+    stageKeys?: string[];
+    stage_keys?: string[];
+    tools?: string[];
+}
+export interface LabsAgentTeam {
+    enabled?: boolean;
+    routingMode?: "auto" | "sequential";
+    routing_mode?: "auto" | "sequential";
+    fallbackMemberId?: string;
+    fallback_member_id?: string;
+    members?: LabsSpecialist[];
+    routingRules?: Array<{
+        intent: string;
+        member_id: string;
+        priority?: string;
+        action?: string;
+    }>;
+    routing_rules?: Array<{
+        intent: string;
+        member_id: string;
+        priority?: string;
+        action?: string;
+    }>;
+}
+export interface LabsRuntimeRoutingConfig {
+    enabled?: boolean;
+    allowedModels?: LabsRealtimeSelection[];
+    allowed_models?: LabsRealtimeSelection[];
+    /** Server-supported range is 1–3 handoffs per call. */
+    maxHandoffs?: number;
+    max_handoffs?: number;
+    recoverOnDisconnect?: boolean;
+    recover_on_disconnect?: boolean;
+    allowedLanguages?: string[];
+    allowed_languages?: string[];
+}
 export type LabsStageGeneration = "managed" | "template" | "off" | "oracle";
 export interface LabsCallPlan {
     version: "supafone_call_plan_v1" | string;
@@ -646,6 +712,8 @@ export interface LabsEmailConfig {
 }
 export interface LabsRecordingConfig {
     enabled?: boolean;
+    /** Request post-call transcription of the recording where configured. */
+    transcribe?: boolean;
     recordAudio?: boolean;
     record_audio?: boolean;
     consentRequired?: boolean;
@@ -885,6 +953,17 @@ export interface CreateLabsAgentRequest {
     presetKey?: string;
     preset_key?: string;
     realtime?: LabsRealtimeSelection;
+    manager?: boolean | LabsManagerConfig;
+    agentTeam?: LabsAgentTeam;
+    agent_team?: LabsAgentTeam;
+    runtimeRouting?: LabsRuntimeRoutingConfig;
+    runtime_routing?: LabsRuntimeRoutingConfig;
+    captureFields?: string[];
+    capture_fields?: string[];
+    timezone?: string;
+    businessTimezone?: string;
+    timeAwareness?: boolean;
+    time_awareness?: boolean;
     runtimeMode?: LabsRuntimeMode;
     runtime_mode?: LabsRuntimeMode;
     /** Defaults to Supafone's hosted planner; model credentials remain server-side. */
@@ -927,7 +1006,7 @@ export interface CreateLabsAgentRequest {
     customSip?: LabsCustomSipConfig;
     custom_sip?: LabsCustomSipConfig;
     sip?: LabsCustomSipConfig;
-    recording?: LabsRecordingConfig;
+    recording?: boolean | LabsRecordingConfig;
     transcription?: LabsTranscriptionConfig;
     artifacts?: LabsArtifactsConfig;
     compliance?: Record<string, unknown>;