supafone-labs 0.5.2 → 0.5.3

package/src/index.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.
  *
@@ -54,15 +54,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;
 }
 
@@ -93,7 +91,10 @@ export interface WhisperOptions {
   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;
@@ -111,7 +112,7 @@ export interface DirectiveListControl {
   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;
@@ -124,31 +125,34 @@ 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>;
+    directive: SupervisorDirective,
+  ) => SupervisorDirective | null | Promise<SupervisorDirective | null>;
 }
 
 export interface Balance {
@@ -618,9 +622,12 @@ export interface LabsArtifactsConfig {
   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;
@@ -636,6 +643,9 @@ export interface LabsWatcherConfig {
   label?: string;
 }
 
+/** @deprecated Use LabsSupervisorConfig. */
+export type LabsWatcherConfig = LabsSupervisorConfig;
+
 export interface LabsUltravoxRuntime {
   model?: string;
   temperature?: number;
@@ -948,9 +958,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;
@@ -1722,13 +1735,13 @@ 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 " +
+  "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 " +
+  "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 " +
@@ -1747,7 +1760,7 @@ interface NormalizedDirectiveContract {
   };
   language_mode: "caller" | "model" | "fixed";
   fixed_language: string;
-  allowed_kinds: SecondMindDirectiveKind[];
+  allowed_kinds: SupervisorDirectiveKind[];
   confidence_threshold: number;
   operator_guardrails: string[];
 }
@@ -1787,7 +1800,7 @@ function normalizeDirectiveContract(input: DirectiveContract = {}): NormalizedDi
     guardrails: listControl(input.guardrails),
     language_mode: languageMode,
     fixed_language: String(input.fixed_language ?? input.fixedLanguage ?? "").trim(),
-    allowed_kinds: allowed.filter((kind): kind is SecondMindDirectiveKind =>
+    allowed_kinds: allowed.filter((kind): kind is SupervisorDirectiveKind =>
       ["empathy", "tactical", "guardrail", "mixed"].includes(kind),
     ),
     confidence_threshold: Number.isFinite(threshold) ? Math.max(0, Math.min(1, threshold)) : 0.5,
@@ -1832,8 +1845,8 @@ function clipList(value: unknown, maxItems: number, itemMaxChars: number): strin
 function normalizeStructuredDirective(
   raw: Record<string, unknown>,
   contract: NormalizedDirectiveContract,
-): SecondMindDirective | null {
-  const kind = String(raw.kind ?? "mixed") as SecondMindDirectiveKind;
+): SupervisorDirective | null {
+  const kind = String(raw.kind ?? "mixed") as SupervisorDirectiveKind;
   if (!["empathy", "tactical", "guardrail", "mixed"].includes(kind)) return null;
   const parsedConfidence = Number(raw.confidence ?? 0);
   const confidence = Number.isFinite(parsedConfidence) ? Math.max(0, Math.min(1, parsedConfidence)) : 0;
@@ -1869,7 +1882,9 @@ export class SupafoneLabs {
   private readonly supafoneApiKey: string;
   private readonly timeoutMs: number;
   private readonly postCallAnalysis: boolean;
-  /** 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?: string;
   private accountToken?: string;
@@ -1898,8 +1913,9 @@ export 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;
@@ -2259,14 +2275,14 @@ export class SupafoneLabs {
   }
 
   /**
-   * 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.
    */
   async whisperStructured(
     transcript: string,
     opts: StructuredWhisperOptions = {},
-  ): Promise<SecondMindDirective | null> {
+  ): Promise<SupervisorDirective | null> {
     const contract = normalizeDirectiveContract(
       opts.directive_contract ?? opts.directiveContract ?? {},
     );
@@ -2300,7 +2316,7 @@ export class SupafoneLabs {
   directive(
     transcript: string,
     opts: StructuredWhisperOptions = {},
-  ): Promise<SecondMindDirective | null> {
+  ): Promise<SupervisorDirective | null> {
     return this.whisperStructured(transcript, opts);
   }
 
@@ -3097,7 +3113,7 @@ class LabsAgentsNamespace {
     return this.sm.requestSupafoneApi<CreateLabsAgentResponse>(
       "POST",
       "/api/v1/labs/agents",
-      labsAgentPayload(this.withVoiceWatcher(input)),
+      labsAgentPayload(this.withSupervisor(input)),
     );
   }
 
@@ -3114,17 +3130,16 @@ class LabsAgentsNamespace {
     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. */
-  private withVoiceWatcher(input: CreateLabsAgentRequest): CreateLabsAgentRequest {
+  /** Default the agent onto the client's Supafone Supervisor setting unless the
+   * caller set it explicitly. Legacy wire fields remain unchanged. */
+  private withSupervisor(input: CreateLabsAgentRequest): CreateLabsAgentRequest {
     const out: CreateLabsAgentRequest = { ...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;
   }
@@ -4101,7 +4116,7 @@ function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown
     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),
   });
@@ -4533,10 +4548,10 @@ function artifactsPayload(input: LabsArtifactsConfig): Record<string, unknown> {
   });
 }
 
-function labsPayload(input: LabsWatcherConfig): Record<string, unknown> {
+function labsPayload(input: LabsSupervisorConfig): Record<string, unknown> {
   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,