supafone-labs 0.5.4 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@ Use this package to create hosted Supafone agents from code: inbound
 receptionists, outbound sales agents, web agents, Supafone-managed phone
 numbers, built-in stages, tools, recordings, transcripts, widgets, and Supafone
 Pro watcher. It also includes the [Supafone Labs cloud](https://labs.supafone.ai)
-sidecar oracle, hosted TTS/STT, live multilingual transcription, the builder,
+Supervisor, hosted TTS/STT, live multilingual transcription, the builder,
 and the adversarial QA suite.
 
 Dependency-free. Works in Node 18+ and the browser (native `fetch` / `WebSocket`).
@@ -21,7 +21,7 @@ The SDK talks to two related APIs:
 
 | Environment variable | Key shape | Used for |
 | --- | --- | --- |
-| `SUPAFONE_LABS_API_KEY` | `sl_live_...` | Labs cloud oracle, hosted TTS/STT, logs, usage, QA, optimizer |
+| `SUPAFONE_LABS_API_KEY` | `sl_live_...` | Labs Cloud Supervisor, hosted TTS/STT, logs, usage, QA, optimizer |
 | `SUPAFONE_API_KEY` | `sf_live_...` | Hosted Supafone agents on `/api/v1/labs/*` |
 
 If you only use hosted-agent methods, `SUPAFONE_API_KEY` is enough. If you use
@@ -114,6 +114,12 @@ filtering, structured Supervisor directives, and the same configuration model
 across TypeScript and Python. Fixed language selection does not enable
 mid-call language or voice switching.
 
+The canonical packet separates interpersonal guidance, the next operational
+move, observed evidence, policy/tool-truth boundaries, language, confidence,
+and guidance kind. See
+[Programmable Supervisor Directives](../gitbook/programmable-supervisor-directives.md)
+for the human-supervisor mapping and field controls.
+
 Agent Factory can opt into managed live language and matching-voice routing
 with one field. It remains absent and disabled for existing agents:
 
@@ -407,7 +413,7 @@ const { analysis } = await supafone.reportCall({
 ```
 
 The enriched report is filed server-side (feeding `optimizer.improve()` and
-`/v1/optimizer/objective/stats`); billed one oracle call per analyzed call.
+`/v1/optimizer/objective/stats`); billed one Supervisor inference per analyzed call.
 Reports without a transcript — or any analysis failure — fall back to the
 plain zero-billed report. You can also classify explicitly with
 `supafone.classifyCall({ transcript, agent })`.
@@ -539,11 +545,12 @@ and `const { Supafone } = require("supafone-labs")` both work, with full types.
 | `labs.agents.syncKnowledge/detachWebsiteKnowledge/reindexKnowledge` | Managed website corpus lifecycle using `agent.id` |
 | `labs.agents.uploadKnowledgeDocument/deleteKnowledgeDocument/chatKnowledge` | Account-isolated document and grounded-query methods |
 | `labs.phoneNumbers.search/buy/assign/list/buyAndAssign` | `/api/v1/labs/phone-numbers*` |
+| `labs.phoneNumbers.pool/connectPool` | Safe shared developer-number snapshot and scoped realtime stream |
 | `labs.billing.checkout/status/portal` | Stripe-hosted Checkout, payment polling, and Customer Portal |
 | `labs.telephony.get/configure/useSupafoneManaged` | `/api/v1/labs/telephony` |
 | `labs.presets.list()` · `labs.tools.list()` · `labs.voices.list()` | Supafone hosted-agent discovery |
-| `whisper(transcript, opts?)` | convenience over the oracle |
-| `oracle({ messages, model?, ... })` | `POST /v1/oracle/complete` |
+| `whisper(transcript, opts?)` | Convenience over Supervisor completion and directive extraction |
+| `completeWithSupervisor({ messages, model?, ... })` | `POST /v1/supervisor/complete` |
 | `tts(text, voice?)` | `POST /v1/tts` |
 | `stt(audio, opts?)` | `POST /v1/stt` |
 | `liveTranscribe(opts?)` | `WS /v1/stt/live` |
@@ -553,7 +560,19 @@ and `const { Supafone } = require("supafone-labs")` both work, with full types.
 | `qa.run/generate/suite/history` | `/v1/qa/*` |
 | `optimizer.improve/standing` | `/v1/optimizer/*` |
 
-Get a key (5 free minutes, no card): <https://labs.supafone.ai/get-key.html>
+Get a key (five account-wide managed-runtime minutes, no card):
+<https://labs.supafone.ai/get-key.html>
+
+That allowance is shared by every key, agent, WebRTC tab, PSTN call, SDK, CLI,
+and MCP client linked to the account. Managed calls reserve time atomically
+before provider startup; settlement refunds unused held seconds. HTTP 402
+responses expose `detail.code=managed_minutes_exhausted` and a
+`checkout_endpoint`. Create Checkout with `labs.billing.checkout()`, open the
+returned `checkout_url`, poll `labs.billing.status()`, and retry after payment.
+
+The older `oracle()` method and `POST /v1/oracle/complete` route remain only as
+deprecated compatibility aliases. New integrations should use
+`completeWithSupervisor()` and `POST /v1/supervisor/complete`.
 
 For `dedicated` or `premium`, `labs.phoneNumbers.buy()` first returns a public
 `checkout_url`. Open it, poll `labs.billing.status()`, then call `buy()` again

package/dist/cjs/index.d.ts

@@ -4,7 +4,7 @@
  * 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 the Labs cloud sidecar oracle, hosted TTS/STT, live multilingual
+ * 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.
@@ -49,7 +49,7 @@ export interface SupafoneLabsOptions {
      * (or structured messages) first classifies the finished call against the
      * agent's objective — generating labels (achieved/missed, per-criterion
      * verdicts, failure reasons) — and files the enriched report server-side.
-     * Billed one oracle call per analyzed call; reports without a transcript
+     * Billed one Supervisor inference per analyzed call; reports without a transcript
      * fall back to the plain zero-billed report.
      */
     postCallAnalysis?: boolean;
@@ -66,18 +66,22 @@ export interface ChatMessage {
     role: "system" | "user" | "assistant";
     content: string;
 }
-export interface OracleRequest {
+export interface SupervisorRequest {
     messages: ChatMessage[];
-    /** Any claude-* / gpt-* / grok-* id, or the alias "supafone-labs-oracle". */
+    /** Any supported managed/BYOK model id, or the alias "supafone-supervisor". */
     model?: string;
     maxTokens?: number;
     temperature?: number;
 }
-export interface OracleResult {
+export interface SupervisorResult {
     text: string;
     model: string;
     usage?: Record<string, number>;
 }
+/** @deprecated Use SupervisorRequest. */
+export type OracleRequest = SupervisorRequest;
+/** @deprecated Use SupervisorResult. */
+export type OracleResult = SupervisorResult;
 export interface WhisperOptions {
     model?: string;
     /** Extra operator rules folded into the coaching system prompt. */
@@ -195,7 +199,7 @@ export interface LabsCallStage {
     next_stages?: string[];
     metadata?: Record<string, unknown>;
 }
-export type LabsStageGeneration = "oracle" | "template" | "off";
+export type LabsStageGeneration = "managed" | "template" | "off" | "oracle";
 export interface LabsCallPlan {
     version: "supafone_call_plan_v1" | string;
     summary: string;
@@ -440,6 +444,8 @@ export interface LabsProviderByokConfig {
     provider?: string;
     apiKey?: string;
     api_key?: string;
+    apiKeyConfigured?: boolean;
+    api_key_configured?: boolean;
     credentials?: Record<string, unknown>;
     settings?: Record<string, unknown>;
     model?: string;
@@ -629,15 +635,29 @@ export interface LabsArtifactsConfig {
     retention_days?: number;
     metadata?: Record<string, unknown>;
 }
+export type LabsSupervisorProvider = "anthropic" | "claude" | "openai" | "gemini" | "google" | "openrouter" | "groq" | "cerebras";
+export interface LabsByokSupervisorConfig {
+    enabled?: boolean;
+    mode?: "managed" | "supafone_managed" | "byok";
+    provider?: LabsSupervisorProvider;
+    model?: string;
+    apiKey?: string;
+    api_key?: string;
+    apiKeyConfigured?: boolean;
+    api_key_configured?: boolean;
+}
 export interface LabsSupervisorConfig {
     enabled?: boolean;
-    supervisor?: boolean;
+    supervisor?: boolean | LabsByokSupervisorConfig;
     /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
     /** @deprecated Use supervisor. */
     voice_watcher?: boolean;
     apiKey?: string;
     api_key?: string;
+    apiKeyConfigured?: boolean;
+    api_key_configured?: boolean;
+    provider?: LabsSupervisorProvider;
     model?: string;
     mode?: "supafone_managed" | "byok" | string;
     managedInfrastructure?: boolean;
@@ -869,7 +889,7 @@ export interface CreateLabsAgentRequest {
     email?: LabsEmailConfig;
     labs?: LabsSupervisorConfig;
     ultravox?: LabsUltravoxRuntime;
-    supervisor?: boolean;
+    supervisor?: boolean | LabsByokSupervisorConfig;
     /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
     /** @deprecated Use supervisor. */
@@ -1192,6 +1212,44 @@ export interface LabsPhoneNumberListResponse {
     numbers: LabsPhoneNumberRecord[];
     telephony?: Record<string, unknown>;
 }
+export type LabsSharedPhonePoolStatus = "available" | "in_use" | "cooldown" | "reserved" | "unavailable";
+export interface LabsSharedPhonePoolNumber {
+    id: string;
+    pool_id: string;
+    pool_name: string;
+    phone_number: string;
+    display_name: string;
+    provider: string;
+    status: LabsSharedPhonePoolStatus;
+    status_color: "green" | "red";
+    available: boolean;
+    reason: string;
+    health: string;
+    capabilities: string[];
+    cooldown_until?: string | null;
+    updated_at: string;
+}
+export interface LabsSharedPhonePoolSnapshot {
+    version: "developer_phone_pool_v1" | string;
+    revision: string;
+    counts: {
+        total: number;
+        available: number;
+        in_use: number;
+        unavailable: number;
+    };
+    numbers: LabsSharedPhonePoolNumber[];
+    stream?: {
+        url: string;
+        token: string;
+        expires_in_seconds: number;
+        protocol: "developer_phone_pool_v1" | string;
+    };
+}
+export interface LabsPhonePoolStreamOptions {
+    /** Inject a WebSocket implementation for Node versions without a global WebSocket. */
+    WebSocketImpl?: typeof WebSocket;
+}
 export interface LabsPhoneNumberProvisionRequest {
     agencyId?: string;
     agency_id?: string;
@@ -1414,6 +1472,8 @@ export interface BuilderChatResult {
     emotion?: string;
     language?: string;
     intent?: string;
+    supervisor_ms?: number;
+    /** @deprecated Use supervisor_ms. */
     oracle_ms?: number;
     standing_version?: number;
 }
@@ -1455,7 +1515,9 @@ export interface QASuiteResult {
         passed: number;
         avg_ssr_score: number;
         ssr_histogram: Record<SSRLabel, number>;
-        oracle_calls_billed: number;
+        supervisor_inferences_billed?: number;
+        /** @deprecated Legacy server field. */
+        oracle_calls_billed?: number;
     };
 }
 export interface QAResult {
@@ -1484,7 +1546,9 @@ export interface QAResult {
         passed_supervised: number;
         passed_unsupervised: number;
         avg_lift: number;
-        oracle_calls_billed: number;
+        supervisor_inferences_billed?: number;
+        /** @deprecated Legacy server field. */
+        oracle_calls_billed?: number;
     };
 }
 export type TesterScenario = "price_probe" | "false_booking" | "language_switch" | "distressed";
@@ -1677,8 +1741,10 @@ export declare class SupafoneLabs {
         industry?: string;
         apply?: boolean;
     }): Promise<GenerateIntakeResult>;
-    /** Raw oracle completion — full control over messages and model. */
-    oracle(req: OracleRequest): Promise<OracleResult>;
+    /** Raw Supervisor completion with either Supafone-managed or BYOK inference. */
+    completeWithSupervisor(req: SupervisorRequest): Promise<SupervisorResult>;
+    /** @deprecated Use completeWithSupervisor(). */
+    oracle(req: SupervisorRequest): Promise<SupervisorResult>;
     /**
      * The one-liner: hand it the running transcript, get back a silent directive
      * (empty string when the agent is doing fine).
@@ -1709,7 +1775,7 @@ export declare class SupafoneLabs {
     liveTranscribe(opts?: LiveTranscribeOptions): LiveTranscription;
     /** Remaining prepaid balance. */
     balance(): Promise<Balance>;
-    /** Today's usage against your plan caps (oracle/tts/stt/…). */
+    /** Today's usage across Supervisor, TTS, STT, and managed runtime meters. */
     usage(): Promise<UsageToday>;
     /** The auditable whisper/billing log. */
     logs(limit?: number): Promise<{
@@ -1732,7 +1798,7 @@ export declare class SupafoneLabs {
      *
      * With `postCallAnalysis: true` on the client and a transcript (or
      * messages) present, the call is automatically classified first: the
-     * oracle labels it against the agent's objective (achieved/missed,
+     * Supervisor labels it against the agent's objective (achieved/missed,
      * per-criterion verdicts, failure reasons) and files the enriched report
      * server-side. The generated labels come back on `analysis`. Analysis is
      * best-effort — on any failure the plain zero-billed report still lands.
@@ -1743,10 +1809,10 @@ export declare class SupafoneLabs {
      * objective and get labels back — achieved/missed, per-criterion verdicts,
      * failure reasons, and the blended objective value. Files an enriched call
      * report server-side (feeding optimizer.improve() and objective stats).
-     * Billed one oracle call.
+     * Billed one Supervisor inference.
      */
     classifyCall(input: ClassifyCallInput): Promise<CallClassification>;
-    /** Available oracle model ids (live vendor catalog). */
+    /** Available managed and BYOK Supervisor model ids. */
     models(): Promise<string[]>;
     /** Available TTS voice ids. */
     voices(): Promise<string[]>;
@@ -2065,6 +2131,10 @@ declare class LabsNamespace {
 }
 export type LabsBillingCheckoutKind = "plan" | "credits" | "number_addon";
 export interface LabsBillingCheckoutInput {
+    /** Current prepaid managed-minute package SKU. */
+    sku?: string;
+    packageSku?: string;
+    package_sku?: string;
     kind?: LabsBillingCheckoutKind;
     planKey?: "developer" | "growth" | "scale" | string;
     plan_key?: string;
@@ -2079,10 +2149,16 @@ export interface LabsBillingCheckoutInput {
     cancel_url?: string;
 }
 export interface LabsBillingCheckoutResponse {
-    status: "requires_payment" | "pending" | "paid" | string;
-    checkout_session_id: string;
+    status?: "requires_payment" | "pending" | "paid" | string;
+    checkout_session_id?: string;
     checkout_url?: string;
-    kind: LabsBillingCheckoutKind | string;
+    /** Canonical minute-top-up Checkout URL. */
+    url?: string;
+    kind?: LabsBillingCheckoutKind | string;
+    sku?: string;
+    minutes?: number;
+    amount_cents?: number;
+    purchase_id?: string;
     plan_key?: string | null;
     number_strategy?: string | null;
     phone_number?: string | null;
@@ -2095,6 +2171,8 @@ declare class LabsBillingNamespace {
     constructor(sm: SupafoneLabs);
     /** Start hosted Stripe Checkout. MCP callers should render checkout_url as a link. */
     checkout(input?: LabsBillingCheckoutInput): Promise<LabsBillingCheckoutResponse>;
+    /** Start Stripe Checkout for one prepaid managed-minute package. */
+    topUp(sku?: string): Promise<LabsBillingCheckoutResponse>;
     status(checkoutSessionId: string): Promise<LabsBillingCheckoutResponse>;
     portal(): Promise<{
         url: string;
@@ -2267,6 +2345,16 @@ declare class LabsPhoneNumbersNamespace {
     constructor(sm: SupafoneLabs);
     /** List numbers already owned by this Supafone account. */
     list(opts?: LabsPhoneNumberListOptions): Promise<LabsPhoneNumberListResponse>;
+    /**
+     * Read the explicitly enrolled shared developer-number pool. This inventory
+     * never infers customer or merely-unassigned numbers into the response.
+     */
+    pool(): Promise<LabsSharedPhonePoolSnapshot>;
+    /**
+     * Connect to realtime pool state using a short-lived pool-only token. The
+     * Supafone API key is never placed in the WebSocket URL.
+     */
+    connectPool(opts?: LabsPhonePoolStreamOptions): Promise<WebSocket>;
     /** Search Supafone-managed inventory. This uses Supafone's master telephony account. */
     search(opts?: LabsPhoneNumberSearchOptions): Promise<LabsPhoneNumberSearchResponse>;
     /**