supafone-labs 0.5.2 → 0.5.3

package/README.md

@@ -104,13 +104,13 @@ Supafone Labs has two main features:
 
 - **Agent Factory**: create the complete hosted agent with managed provider
   defaults and one Supafone API key.
-- **Self-healing watcher**: enable `labs.enabled` to attach the Supafone Labs
-  second mind to a hosted or BYOK agent.
+- **Supafone Supervisor**: attach live guidance, call scoring, and QA to a
+  hosted or BYOK agent.
 
 The daily developer workflow is documented in
 [Developer Workflows](../gitbook/developer-workflows.md): one normalized live
 voice catalog, fixed BCP-47 language selection, automatic voice compatibility
-filtering, structured SecondMind directives, and the same configuration model
+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.
 
@@ -166,10 +166,9 @@ 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!,
-  // voiceWatcher is on by default (also accepts voice_watcher; deprecated: labs).
-  // Every provisioned agent runs under the Voice Watcher framework (live
-  // supervision + QA + call scoring). Set false for a raw agent.
-  voiceWatcher: true,
+  // Supafone Supervisor is on by default for live guidance, QA, and scoring.
+  // Set false only when you intentionally need an unsupervised agent.
+  supervisor: true,
   // Defaults to https://api.supafone.ai. Override for staging/local tests.
   // supafoneApiBaseUrl: "http://localhost:8000",
 });

package/dist/cjs/index.d.ts

@@ -3,7 +3,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 Pro watcher. It also
+ * tools, recordings, transcripts, widgets, and Supafone Supervisor. It also
  * includes the Labs cloud sidecar oracle, hosted TTS/STT, live multilingual
  * transcription, telemetry, agent builder, and objective-driven optimizer.
  *
@@ -53,15 +53,13 @@ export interface SupafoneLabsOptions {
      * fall back to the plain zero-billed report.
      */
     postCallAnalysis?: boolean;
-    /**
-     * Run provisioned agents under Supafone's Voice Watcher framework — live
-     * supervision, QA, and call scoring (default true). Set false for a raw
-     * agent with no watcher. `voice_watcher` (snake) and the deprecated `labs`
-     * are accepted aliases, resolved voiceWatcher > voice_watcher > labs > true.
-     */
+    /** Enable Supafone Supervisor live guidance, QA, and scoring (default true). */
+    supervisor?: boolean;
+    /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
+    /** @deprecated Use supervisor. */
     voice_watcher?: boolean;
-    /** @deprecated alias for voiceWatcher. */
+    /** @deprecated Use supervisor. */
     labs?: boolean;
 }
 export interface ChatMessage {
@@ -87,7 +85,9 @@ export interface WhisperOptions {
     maxTokens?: number;
     temperature?: number;
 }
-export type SecondMindDirectiveKind = "empathy" | "tactical" | "guardrail" | "mixed";
+export type SupervisorDirectiveKind = "empathy" | "tactical" | "guardrail" | "mixed";
+/** @deprecated Use SupervisorDirectiveKind. */
+export type SecondMindDirectiveKind = SupervisorDirectiveKind;
 export interface DirectiveTextControl {
     enabled?: boolean;
     instructions?: string;
@@ -102,7 +102,7 @@ export interface DirectiveListControl {
     itemMaxChars?: number;
     item_max_chars?: number;
 }
-/** Serializable controls for each field generated by SecondMind. */
+/** Serializable controls for each field generated by Supafone Supervisor. */
 export interface DirectiveContract {
     empathyDirective?: DirectiveTextControl;
     empathy_directive?: DirectiveTextControl;
@@ -115,27 +115,29 @@ export interface DirectiveContract {
     language_mode?: "caller" | "model" | "fixed";
     fixedLanguage?: string;
     fixed_language?: string;
-    allowedKinds?: SecondMindDirectiveKind[];
-    allowed_kinds?: SecondMindDirectiveKind[];
+    allowedKinds?: SupervisorDirectiveKind[];
+    allowed_kinds?: SupervisorDirectiveKind[];
     confidenceThreshold?: number;
     confidence_threshold?: number;
     operatorGuardrails?: string[];
     operator_guardrails?: string[];
 }
-export interface SecondMindDirective {
+export interface SupervisorDirective {
     empathy_directive: string;
     tactical_directive: string;
     surface_facts: string[];
     guardrails: string[];
     language: string;
     confidence: number;
-    kind: SecondMindDirectiveKind;
+    kind: SupervisorDirectiveKind;
 }
+/** @deprecated Use SupervisorDirective. */
+export type SecondMindDirective = SupervisorDirective;
 export interface StructuredWhisperOptions extends WhisperOptions {
     directiveContract?: DirectiveContract;
     directive_contract?: DirectiveContract;
     /** Local final say: revise or suppress the generated directive before use. */
-    transform?: (directive: SecondMindDirective) => SecondMindDirective | null | Promise<SecondMindDirective | null>;
+    transform?: (directive: SupervisorDirective) => SupervisorDirective | null | Promise<SupervisorDirective | null>;
 }
 export interface Balance {
     plan: string;
@@ -579,9 +581,12 @@ export interface LabsArtifactsConfig {
     retention_days?: number;
     metadata?: Record<string, unknown>;
 }
-export interface LabsWatcherConfig {
+export interface LabsSupervisorConfig {
     enabled?: boolean;
+    supervisor?: boolean;
+    /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
+    /** @deprecated Use supervisor. */
     voice_watcher?: boolean;
     apiKey?: string;
     api_key?: string;
@@ -596,6 +601,8 @@ export interface LabsWatcherConfig {
     provider_keys?: Record<string, unknown>;
     label?: string;
 }
+/** @deprecated Use LabsSupervisorConfig. */
+export type LabsWatcherConfig = LabsSupervisorConfig;
 export interface LabsUltravoxRuntime {
     model?: string;
     temperature?: number;
@@ -810,9 +817,12 @@ export interface CreateLabsAgentRequest {
     artifacts?: LabsArtifactsConfig;
     compliance?: Record<string, unknown>;
     tools?: LabsToolsConfig;
-    labs?: LabsWatcherConfig;
+    labs?: LabsSupervisorConfig;
     ultravox?: LabsUltravoxRuntime;
+    supervisor?: boolean;
+    /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
+    /** @deprecated Use supervisor. */
     voice_watcher?: boolean;
     voiceWatcherModel?: string;
     voice_watcher_model?: string;
@@ -1518,7 +1528,9 @@ export declare class SupafoneLabs {
     private readonly supafoneApiKey;
     private readonly timeoutMs;
     private readonly postCallAnalysis;
-    /** Client default for the Voice Watcher framework (supervision + QA + scoring). */
+    /** Client default for Supafone Supervisor (live guidance + QA + scoring). */
+    readonly supervisor: boolean;
+    /** @deprecated Use supervisor. */
     readonly voiceWatcher: boolean;
     private sessionToken?;
     private accountToken?;
@@ -1623,13 +1635,13 @@ export declare class SupafoneLabs {
      */
     whisper(transcript: string, opts?: WhisperOptions): Promise<string>;
     /**
-     * Structured SecondMind guidance with developer-controlled field policy.
+     * Structured Supafone Supervisor guidance with developer-controlled field policy.
      * Returns null when JSON is invalid, evidence misses the confidence gate,
      * the generated kind is disallowed, or the local transform suppresses it.
      */
-    whisperStructured(transcript: string, opts?: StructuredWhisperOptions): Promise<SecondMindDirective | null>;
+    whisperStructured(transcript: string, opts?: StructuredWhisperOptions): Promise<SupervisorDirective | null>;
     /** Alias that reads naturally in applications building their own watcher loop. */
-    directive(transcript: string, opts?: StructuredWhisperOptions): Promise<SecondMindDirective | null>;
+    directive(transcript: string, opts?: StructuredWhisperOptions): Promise<SupervisorDirective | null>;
     /** Hosted TTS — returns raw audio bytes (WAV/PCM per voice). */
     tts(text: string, voice?: string): Promise<Uint8Array>;
     /** Convenience alias for voice preview UI/buttons. */
@@ -2052,10 +2064,9 @@ declare class LabsAgentsNamespace {
     generateCallStages(input: CreateLabsAgentRequest & {
         description?: string;
     }): Promise<LabsCallPlan>;
-    /** Default the agent onto the client's Voice Watcher setting (live supervision
-     * + QA + scoring) unless the caller set it explicitly; mirror into
-     * labs.voice_watcher when a labs block exists. Never overwrites a caller value. */
-    private withVoiceWatcher;
+    /** Default the agent onto the client's Supafone Supervisor setting unless the
+     * caller set it explicitly. Legacy wire fields remain unchanged. */
+    private withSupervisor;
     /** Create an inbound receptionist/intake agent. No Twilio account is required. */
     createInbound(input: CreateLabsAgentRequest): Promise<CreateLabsAgentResponse>;
     /** Create an outbound sales/speed-to-lead/campaign agent. No Twilio account is required. */

package/dist/cjs/index.js

@@ -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 Pro watcher. It also
+ * tools, recordings, transcripts, widgets, and Supafone Supervisor. It also
  * includes the Labs cloud sidecar oracle, hosted TTS/STT, live multilingual
  * transcription, telemetry, agent builder, and objective-driven optimizer.
  *
@@ -159,11 +159,11 @@ class SupafoneLabsError extends Error {
 exports.SupafoneLabsError = SupafoneLabsError;
 const DEFAULT_BASE = "https://api.labs.supafone.ai";
 const DEFAULT_SUPAFONE_API_BASE = "https://api.supafone.ai";
-const COACH_SYSTEM = "You are the coaching core of a second mind for a live voice agent. Read the " +
+const COACH_SYSTEM = "You are the coaching core of a supervisor for a live voice agent. Read the " +
     "conversation and return ONE short, silent directive the agent reads but never " +
     "speaks aloud — a correction or nudge, phrased imperatively. If nothing needs " +
     "correcting, return an empty string.";
-const STRUCTURED_COACH_SYSTEM = "You are the coaching core of a second mind for a live voice agent. Read the " +
+const STRUCTURED_COACH_SYSTEM = "You are the coaching core of a supervisor for a live voice agent. Read the " +
     "conversation and return ONLY one JSON object with exactly these keys: " +
     "empathy_directive (string), tactical_directive (string), surface_facts (string[]), " +
     "guardrails (string[]), language (short code), confidence (0-1), and kind " +
@@ -273,7 +273,9 @@ class SupafoneLabs {
     supafoneApiKey;
     timeoutMs;
     postCallAnalysis;
-    /** Client default for the Voice Watcher framework (supervision + QA + scoring). */
+    /** Client default for Supafone Supervisor (live guidance + QA + scoring). */
+    supervisor;
+    /** @deprecated Use supervisor. */
     voiceWatcher;
     sessionToken;
     accountToken;
@@ -298,8 +300,9 @@ class SupafoneLabs {
         this.appUrl = (opts.appUrl ?? "https://app.supafone.ai").replace(/\/$/, "");
         this.timeoutMs = opts.timeoutMs ?? 30_000;
         this.postCallAnalysis = opts.postCallAnalysis ?? false;
-        // Precedence: explicit voiceWatcher > voice_watcher (snake) > labs (deprecated) > true.
-        this.voiceWatcher = opts.voiceWatcher ?? opts.voice_watcher ?? opts.labs ?? true;
+        // Precedence: supervisor > legacy aliases > true.
+        this.supervisor = opts.supervisor ?? opts.voiceWatcher ?? opts.voice_watcher ?? opts.labs ?? true;
+        this.voiceWatcher = this.supervisor;
         this.sessionToken = opts.sessionToken;
         this.accountToken = opts.accountToken;
         this.accountEmail = opts.accountEmail;
@@ -628,7 +631,7 @@ class SupafoneLabs {
         return out.text.trim();
     }
     /**
-     * Structured SecondMind guidance with developer-controlled field policy.
+     * Structured Supafone Supervisor guidance with developer-controlled field policy.
      * Returns null when JSON is invalid, evidence misses the confidence gate,
      * the generated kind is disallowed, or the local transform suppresses it.
      */
@@ -1174,7 +1177,7 @@ class LabsAgentsNamespace {
     }
     /** Spawn a durable hosted Supafone agent backed by Ultravox and Supafone-managed providers. */
     create(input) {
-        return this.sm.requestSupafoneApi("POST", "/api/v1/labs/agents", labsAgentPayload(this.withVoiceWatcher(input)));
+        return this.sm.requestSupafoneApi("POST", "/api/v1/labs/agents", labsAgentPayload(this.withSupervisor(input)));
     }
     /** Preview the exact validated call-plan contract the Supafone runtime executes. */
     plan(input) {
@@ -1183,17 +1186,16 @@ class LabsAgentsNamespace {
     generateCallStages(input) {
         return this.plan(input);
     }
-    /** Default the agent onto the client's Voice Watcher setting (live supervision
-     * + QA + scoring) unless the caller set it explicitly; mirror into
-     * labs.voice_watcher when a labs block exists. Never overwrites a caller value. */
-    withVoiceWatcher(input) {
+    /** Default the agent onto the client's Supafone Supervisor setting unless the
+     * caller set it explicitly. Legacy wire fields remain unchanged. */
+    withSupervisor(input) {
         const out = { ...input };
-        if (out.voice_watcher === undefined && out.voiceWatcher === undefined) {
-            out.voice_watcher = this.sm.voiceWatcher;
+        if (out.supervisor === undefined && out.voice_watcher === undefined && out.voiceWatcher === undefined) {
+            out.supervisor = this.sm.supervisor;
         }
         const labs = out.labs;
-        if (labs && labs.voice_watcher === undefined && labs.voiceWatcher === undefined) {
-            out.labs = { ...labs, voice_watcher: this.sm.voiceWatcher };
+        if (labs && labs.supervisor === undefined && labs.voice_watcher === undefined && labs.voiceWatcher === undefined) {
+            out.labs = { ...labs, supervisor: this.sm.supervisor };
         }
         return out;
     }
@@ -2014,7 +2016,7 @@ function labsAgentPayload(input) {
         tools: input.tools ? toolsPayload(input.tools) : undefined,
         labs: input.labs ? labsPayload(input.labs) : undefined,
         ultravox: input.ultravox ? ultravoxPayload(input.ultravox) : undefined,
-        voice_watcher: input.voice_watcher ?? input.voiceWatcher,
+        voice_watcher: input.supervisor ?? input.voice_watcher ?? input.voiceWatcher,
         voice_watcher_model: input.voice_watcher_model ?? input.voiceWatcherModel,
         metadata: labsAgentMetadataPayload(input),
     });
@@ -2415,7 +2417,7 @@ function artifactsPayload(input) {
 function labsPayload(input) {
     return compact({
         enabled: input.enabled,
-        voice_watcher: input.voice_watcher ?? input.voiceWatcher,
+        voice_watcher: input.supervisor ?? input.voice_watcher ?? input.voiceWatcher,
         api_key: input.api_key ?? input.apiKey,
         model: input.model,
         mode: input.mode,

package/dist/index.d.ts

@@ -3,7 +3,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 Pro watcher. It also
+ * tools, recordings, transcripts, widgets, and Supafone Supervisor. It also
  * includes the Labs cloud sidecar oracle, hosted TTS/STT, live multilingual
  * transcription, telemetry, agent builder, and objective-driven optimizer.
  *
@@ -53,15 +53,13 @@ export interface SupafoneLabsOptions {
      * fall back to the plain zero-billed report.
      */
     postCallAnalysis?: boolean;
-    /**
-     * Run provisioned agents under Supafone's Voice Watcher framework — live
-     * supervision, QA, and call scoring (default true). Set false for a raw
-     * agent with no watcher. `voice_watcher` (snake) and the deprecated `labs`
-     * are accepted aliases, resolved voiceWatcher > voice_watcher > labs > true.
-     */
+    /** Enable Supafone Supervisor live guidance, QA, and scoring (default true). */
+    supervisor?: boolean;
+    /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
+    /** @deprecated Use supervisor. */
     voice_watcher?: boolean;
-    /** @deprecated alias for voiceWatcher. */
+    /** @deprecated Use supervisor. */
     labs?: boolean;
 }
 export interface ChatMessage {
@@ -87,7 +85,9 @@ export interface WhisperOptions {
     maxTokens?: number;
     temperature?: number;
 }
-export type SecondMindDirectiveKind = "empathy" | "tactical" | "guardrail" | "mixed";
+export type SupervisorDirectiveKind = "empathy" | "tactical" | "guardrail" | "mixed";
+/** @deprecated Use SupervisorDirectiveKind. */
+export type SecondMindDirectiveKind = SupervisorDirectiveKind;
 export interface DirectiveTextControl {
     enabled?: boolean;
     instructions?: string;
@@ -102,7 +102,7 @@ export interface DirectiveListControl {
     itemMaxChars?: number;
     item_max_chars?: number;
 }
-/** Serializable controls for each field generated by SecondMind. */
+/** Serializable controls for each field generated by Supafone Supervisor. */
 export interface DirectiveContract {
     empathyDirective?: DirectiveTextControl;
     empathy_directive?: DirectiveTextControl;
@@ -115,27 +115,29 @@ export interface DirectiveContract {
     language_mode?: "caller" | "model" | "fixed";
     fixedLanguage?: string;
     fixed_language?: string;
-    allowedKinds?: SecondMindDirectiveKind[];
-    allowed_kinds?: SecondMindDirectiveKind[];
+    allowedKinds?: SupervisorDirectiveKind[];
+    allowed_kinds?: SupervisorDirectiveKind[];
     confidenceThreshold?: number;
     confidence_threshold?: number;
     operatorGuardrails?: string[];
     operator_guardrails?: string[];
 }
-export interface SecondMindDirective {
+export interface SupervisorDirective {
     empathy_directive: string;
     tactical_directive: string;
     surface_facts: string[];
     guardrails: string[];
     language: string;
     confidence: number;
-    kind: SecondMindDirectiveKind;
+    kind: SupervisorDirectiveKind;
 }
+/** @deprecated Use SupervisorDirective. */
+export type SecondMindDirective = SupervisorDirective;
 export interface StructuredWhisperOptions extends WhisperOptions {
     directiveContract?: DirectiveContract;
     directive_contract?: DirectiveContract;
     /** Local final say: revise or suppress the generated directive before use. */
-    transform?: (directive: SecondMindDirective) => SecondMindDirective | null | Promise<SecondMindDirective | null>;
+    transform?: (directive: SupervisorDirective) => SupervisorDirective | null | Promise<SupervisorDirective | null>;
 }
 export interface Balance {
     plan: string;
@@ -579,9 +581,12 @@ export interface LabsArtifactsConfig {
     retention_days?: number;
     metadata?: Record<string, unknown>;
 }
-export interface LabsWatcherConfig {
+export interface LabsSupervisorConfig {
     enabled?: boolean;
+    supervisor?: boolean;
+    /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
+    /** @deprecated Use supervisor. */
     voice_watcher?: boolean;
     apiKey?: string;
     api_key?: string;
@@ -596,6 +601,8 @@ export interface LabsWatcherConfig {
     provider_keys?: Record<string, unknown>;
     label?: string;
 }
+/** @deprecated Use LabsSupervisorConfig. */
+export type LabsWatcherConfig = LabsSupervisorConfig;
 export interface LabsUltravoxRuntime {
     model?: string;
     temperature?: number;
@@ -810,9 +817,12 @@ export interface CreateLabsAgentRequest {
     artifacts?: LabsArtifactsConfig;
     compliance?: Record<string, unknown>;
     tools?: LabsToolsConfig;
-    labs?: LabsWatcherConfig;
+    labs?: LabsSupervisorConfig;
     ultravox?: LabsUltravoxRuntime;
+    supervisor?: boolean;
+    /** @deprecated Use supervisor. */
     voiceWatcher?: boolean;
+    /** @deprecated Use supervisor. */
     voice_watcher?: boolean;
     voiceWatcherModel?: string;
     voice_watcher_model?: string;
@@ -1518,7 +1528,9 @@ export declare class SupafoneLabs {
     private readonly supafoneApiKey;
     private readonly timeoutMs;
     private readonly postCallAnalysis;
-    /** Client default for the Voice Watcher framework (supervision + QA + scoring). */
+    /** Client default for Supafone Supervisor (live guidance + QA + scoring). */
+    readonly supervisor: boolean;
+    /** @deprecated Use supervisor. */
     readonly voiceWatcher: boolean;
     private sessionToken?;
     private accountToken?;
@@ -1623,13 +1635,13 @@ export declare class SupafoneLabs {
      */
     whisper(transcript: string, opts?: WhisperOptions): Promise<string>;
     /**
-     * Structured SecondMind guidance with developer-controlled field policy.
+     * Structured Supafone Supervisor guidance with developer-controlled field policy.
      * Returns null when JSON is invalid, evidence misses the confidence gate,
      * the generated kind is disallowed, or the local transform suppresses it.
      */
-    whisperStructured(transcript: string, opts?: StructuredWhisperOptions): Promise<SecondMindDirective | null>;
+    whisperStructured(transcript: string, opts?: StructuredWhisperOptions): Promise<SupervisorDirective | null>;
     /** Alias that reads naturally in applications building their own watcher loop. */
-    directive(transcript: string, opts?: StructuredWhisperOptions): Promise<SecondMindDirective | null>;
+    directive(transcript: string, opts?: StructuredWhisperOptions): Promise<SupervisorDirective | null>;
     /** Hosted TTS — returns raw audio bytes (WAV/PCM per voice). */
     tts(text: string, voice?: string): Promise<Uint8Array>;
     /** Convenience alias for voice preview UI/buttons. */
@@ -2052,10 +2064,9 @@ declare class LabsAgentsNamespace {
     generateCallStages(input: CreateLabsAgentRequest & {
         description?: string;
     }): Promise<LabsCallPlan>;
-    /** Default the agent onto the client's Voice Watcher setting (live supervision
-     * + QA + scoring) unless the caller set it explicitly; mirror into
-     * labs.voice_watcher when a labs block exists. Never overwrites a caller value. */
-    private withVoiceWatcher;
+    /** Default the agent onto the client's Supafone Supervisor setting unless the
+     * caller set it explicitly. Legacy wire fields remain unchanged. */
+    private withSupervisor;
     /** Create an inbound receptionist/intake agent. No Twilio account is required. */
     createInbound(input: CreateLabsAgentRequest): Promise<CreateLabsAgentResponse>;
     /** Create an outbound sales/speed-to-lead/campaign agent. No Twilio account is required. */