supafone-labs 0.5.2 → 0.5.4

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 {
@@ -574,8 +578,60 @@ export interface LabsToolsConfig {
   voicemail?: boolean;
   emergencyEscalation?: boolean;
   emergency_escalation?: boolean;
-  customTools?: Array<Record<string, unknown>>;
-  custom_tools?: Array<Record<string, unknown>>;
+  /** Makes the native DTMF tool available for bounded phone-tree navigation. */
+  ivrNavigation?: boolean;
+  ivr_navigation?: boolean;
+  /** Executable customer-owned HTTPS tools, proxied by Supafone at call time. */
+  customTools?: LabsCustomToolDefinition[];
+  custom_tools?: LabsCustomToolDefinition[];
+}
+
+export type LabsCustomToolParameterType = "string" | "number" | "integer" | "boolean";
+
+export interface LabsCustomToolParameter {
+  name: string;
+  description?: string;
+  type?: LabsCustomToolParameterType;
+  required?: boolean;
+}
+
+export interface LabsCustomToolDefinition {
+  /** Stable id returned by Supafone. Omit it when creating a tool. */
+  id?: string;
+  /** Lowercase model tool name, such as lookup_order. */
+  name: string;
+  description?: string;
+  /** HTTPS endpoint called by Supafone's guarded server-side proxy. */
+  url: string;
+  /** Optional secret header name. Defaults to Authorization: Bearer <apiKey>. */
+  header?: string;
+  apiKey?: string;
+  api_key?: string;
+  /** Set false on update to remove a previously stored secret. */
+  apiKeySet?: boolean;
+  api_key_set?: boolean;
+  params?: LabsCustomToolParameter[];
+  parameters?: LabsCustomToolParameter[];
+  /** Optional call-stage keys where this tool is available. Empty means every stage. */
+  stages?: string[];
+  allowedStages?: string[];
+  allowed_stages?: string[];
+}
+
+export interface LabsEmailConfig {
+  enabled?: boolean;
+  fromEmail?: string;
+  from_email?: string;
+  smtpHost?: string;
+  smtp_host?: string;
+  smtpPort?: number;
+  smtp_port?: number;
+  smtpUser?: string;
+  smtp_user?: string;
+  /** Encrypted by Supafone and never returned. */
+  smtpPassword?: string;
+  smtp_password?: string;
+  smtp_pass?: string;
 }
 
 export interface LabsRecordingConfig {
@@ -618,9 +674,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 +695,9 @@ export interface LabsWatcherConfig {
   label?: string;
 }
 
+/** @deprecated Use LabsSupervisorConfig. */
+export type LabsWatcherConfig = LabsSupervisorConfig;
+
 export interface LabsUltravoxRuntime {
   model?: string;
   temperature?: number;
@@ -948,9 +1010,14 @@ export interface CreateLabsAgentRequest {
   artifacts?: LabsArtifactsConfig;
   compliance?: Record<string, unknown>;
   tools?: LabsToolsConfig;
-  labs?: LabsWatcherConfig;
+  /** Optional per-agent SMTP sender used by the callable send_email tool. */
+  email?: LabsEmailConfig;
+  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 +1789,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 +1814,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 +1854,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 +1899,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 +1936,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 +1967,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 +2329,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 +2370,7 @@ export class SupafoneLabs {
   directive(
     transcript: string,
     opts: StructuredWhisperOptions = {},
-  ): Promise<SecondMindDirective | null> {
+  ): Promise<SupervisorDirective | null> {
     return this.whisperStructured(transcript, opts);
   }
 
@@ -3097,7 +3167,7 @@ class LabsAgentsNamespace {
     return this.sm.requestSupafoneApi<CreateLabsAgentResponse>(
       "POST",
       "/api/v1/labs/agents",
-      labsAgentPayload(this.withVoiceWatcher(input)),
+      labsAgentPayload(this.withSupervisor(input)),
     );
   }
 
@@ -3114,17 +3184,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;
   }
@@ -4099,9 +4168,10 @@ function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown
     artifacts: input.artifacts ? artifactsPayload(input.artifacts) : undefined,
     compliance: input.compliance,
     tools: input.tools ? toolsPayload(input.tools) : undefined,
+    email: input.email ? emailPayload(input.email) : 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),
   });
@@ -4490,10 +4560,22 @@ function toolsPayload(input: LabsToolsConfig): Record<string, unknown> {
     existing_client_lookup: input.existing_client_lookup ?? input.existingClientLookup,
     voicemail: input.voicemail,
     emergency_escalation: input.emergency_escalation ?? input.emergencyEscalation,
+    ivr_navigation: input.ivr_navigation ?? input.ivrNavigation,
     custom_tools: input.custom_tools ?? input.customTools,
   });
 }
 
+function emailPayload(input: LabsEmailConfig): Record<string, unknown> {
+  return compact({
+    enabled: input.enabled,
+    from_email: input.from_email ?? input.fromEmail,
+    smtp_host: input.smtp_host ?? input.smtpHost,
+    smtp_port: input.smtp_port ?? input.smtpPort,
+    smtp_user: input.smtp_user ?? input.smtpUser,
+    smtp_pass: input.smtp_pass ?? input.smtp_password ?? input.smtpPassword,
+  });
+}
+
 function recordingPayload(input: LabsRecordingConfig): Record<string, unknown> {
   return compact({
     enabled: input.enabled,
@@ -4533,10 +4615,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,