supafone-labs 0.4.10 → 0.4.13

package/src/index.ts

@@ -93,6 +93,64 @@ export interface WhisperOptions {
   temperature?: number;
 }
 
+export type SecondMindDirectiveKind = "empathy" | "tactical" | "guardrail" | "mixed";
+
+export interface DirectiveTextControl {
+  enabled?: boolean;
+  instructions?: string;
+  maxChars?: number;
+  max_chars?: number;
+}
+
+export interface DirectiveListControl {
+  enabled?: boolean;
+  instructions?: string;
+  maxItems?: number;
+  max_items?: number;
+  itemMaxChars?: number;
+  item_max_chars?: number;
+}
+
+/** Serializable controls for each field generated by SecondMind. */
+export interface DirectiveContract {
+  empathyDirective?: DirectiveTextControl;
+  empathy_directive?: DirectiveTextControl;
+  tacticalDirective?: DirectiveTextControl;
+  tactical_directive?: DirectiveTextControl;
+  surfaceFacts?: DirectiveListControl;
+  surface_facts?: DirectiveListControl;
+  guardrails?: DirectiveListControl;
+  languageMode?: "caller" | "model" | "fixed";
+  language_mode?: "caller" | "model" | "fixed";
+  fixedLanguage?: string;
+  fixed_language?: string;
+  allowedKinds?: SecondMindDirectiveKind[];
+  allowed_kinds?: SecondMindDirectiveKind[];
+  confidenceThreshold?: number;
+  confidence_threshold?: number;
+  operatorGuardrails?: string[];
+  operator_guardrails?: string[];
+}
+
+export interface SecondMindDirective {
+  empathy_directive: string;
+  tactical_directive: string;
+  surface_facts: string[];
+  guardrails: string[];
+  language: string;
+  confidence: number;
+  kind: SecondMindDirectiveKind;
+}
+
+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>;
+}
+
 export interface Balance {
   plan: string;
   seconds_remaining: number;
@@ -144,14 +202,32 @@ export interface LabsCallStage {
   key?: string;
   id?: string;
   name: string;
+  /** Plain-English job description used by the hosted call-plan generator. */
+  description?: string;
   goal?: string;
   instructions?: string;
   exitCriteria?: string[];
   exit_criteria?: string[];
   tools?: string[];
+  temperature?: number;
+  nextStages?: string[];
+  next_stages?: string[];
   metadata?: Record<string, unknown>;
 }
 
+export type LabsStageGeneration = "oracle" | "template" | "off";
+
+export interface LabsCallPlan {
+  version: "supafone_call_plan_v1" | string;
+  summary: string;
+  base_system_prompt: string;
+  call_stages: LabsCallStage[];
+  generated_by: "supafone_hosted_haiku" | "deterministic_template" | "deterministic_fallback" | "developer" | string;
+  model: string;
+  fallback: boolean;
+  warnings?: string[];
+}
+
 export interface LabsVoiceSelection {
   provider?: string;
   voiceId?: string;
@@ -159,6 +235,115 @@ export interface LabsVoiceSelection {
   model?: string;
 }
 
+export type LabsVoiceGender = "female" | "male" | "neutral";
+
+export interface LabsVoiceLanguage {
+  code: string;
+  locale: string;
+  name: string;
+  native_name: string;
+  aliases?: string[];
+  routing_supported?: boolean;
+}
+
+export interface LabsVoiceLanguageSupport {
+  provider: string;
+  model?: string | null;
+  known: boolean;
+  language_codes: string[];
+  /** Number of language codes Supafone can enumerate from provider docs. */
+  enumerated_language_count: number;
+  generally_available_language_codes: string[];
+  experimental_language_codes: string[];
+  documented_language_count: number;
+  documented_language_count_is_minimum: boolean;
+  support_tier: string;
+  cross_lingual: boolean | null;
+  documentation_url?: string | null;
+  verified_at: string;
+  native_language_codes: string[];
+  ultravox_routing_language_codes: string[];
+  primary_language_support_tier: "generally_available" | "experimental" | "unknown";
+}
+
+export interface LabsVoiceProviderTraits {
+  countries: string[];
+  accents: string[];
+  age_groups: string[];
+  categories: string[];
+  use_cases: string[];
+  descriptors: string[];
+  native_locales: string[];
+  created_at?: string | number | null;
+  is_public?: boolean | null;
+  is_owner?: boolean | null;
+}
+
+export interface LabsVoiceCatalogItem {
+  /** Stable runtime reference, including provider prefix when required. */
+  id: string;
+  voice_id: string;
+  /** Human-readable provider display name. */
+  provider: string;
+  /** Canonical SDK/runtime provider key. */
+  provider_key: string;
+  /** Runtime adapter used to place the voice on an Ultravox call. */
+  runtime_provider_key: string;
+  /** Actual TTS engine behind the voice (can differ for Ultravox built-ins). */
+  synthesis_provider_key: string;
+  /** Raw identifier used by the provider API. */
+  provider_voice_id: string;
+  name: string;
+  label: string;
+  description: string;
+  style: string;
+  model?: string | null;
+  language: string;
+  language_code: string;
+  language_locale: string;
+  language_name: string;
+  native_language_name: string;
+  languages: LabsVoiceLanguage[];
+  native_language_codes: string[];
+  model_language_codes: string[];
+  runtime_supported_language_codes: string[];
+  routing_supported: boolean;
+  language_support: LabsVoiceLanguageSupport;
+  gender: LabsVoiceGender;
+  accent: string;
+  age: string;
+  provider_traits: LabsVoiceProviderTraits;
+  voice_types: string[];
+  primary_voice_type: string;
+  tags: string[];
+  /** Sanitized provider-native fields retained for forward-compatible filtering. */
+  provider_metadata: Record<string, unknown>;
+  provider_metadata_fields: string[];
+  preview_url?: string | null;
+  preview_available: boolean;
+  source: string;
+  ownership?: string | null;
+  configured: boolean;
+  recommended: boolean;
+  premium?: boolean;
+  is_custom: boolean;
+  runtime: { provider: string; voice_id: string; model?: string };
+  [extra: string]: unknown;
+}
+
+export interface LabsVoicePreference {
+  description: string;
+  language?: string;
+  provider?: string;
+  gender?: LabsVoiceGender;
+  voiceType?: string;
+  voice_type?: string;
+  model?: string;
+  configuredOnly?: boolean;
+  configured_only?: boolean;
+  premium?: boolean;
+}
+
 export interface LabsProviderKeys {
   /** Agent runtime/platform providers. */
   ultravox?: string;
@@ -481,6 +666,8 @@ export interface CreateLabsAgentRequest {
   agentStyle?: LabsAgentStyle;
   agent_style?: LabsAgentStyle;
   name: string;
+  /** Plain-language job description used by the hosted call-plan generator. */
+  description?: string;
   assistantName?: string;
   assistant_name?: string;
   businessName?: string;
@@ -500,18 +687,30 @@ export interface CreateLabsAgentRequest {
   preset_key?: string;
   runtimeMode?: LabsRuntimeMode;
   runtime_mode?: LabsRuntimeMode;
-  /** Default true. When true, the SDK creates sensible call stages from prompt metadata. */
-  callStages?: boolean | LabsCallStage[];
-  call_stages?: boolean | LabsCallStage[];
+  /** Defaults to Supafone's hosted planner; model credentials remain server-side. */
+  callStages?: boolean | LabsStageGeneration | LabsCallStage[];
+  call_stages?: boolean | LabsStageGeneration | LabsCallStage[];
   stages?: LabsCallStage[];
   autoCallStages?: boolean;
   auto_call_stages?: boolean;
+  stageGeneration?: LabsStageGeneration;
+  stage_generation?: LabsStageGeneration;
+  stageCount?: number;
+  stage_count?: number;
+  stageDetail?: "compact" | "standard" | "detailed";
+  stage_detail?: "compact" | "standard" | "detailed";
   goal?: string;
   greeting?: string;
   systemPrompt?: string;
   system_prompt?: string;
+  /** Fixed language for the full call. Does not enable mid-call switching. */
   language?: string;
+  preferredLanguage?: string;
+  preferred_language?: string;
   voice?: LabsVoiceSelection;
+  /** Resolve a real current catalog voice from this plain-language preference. */
+  voicePreference?: LabsVoicePreference;
+  voice_preference?: LabsVoicePreference;
   providerKeys?: LabsProviderKeys;
   provider_keys?: LabsProviderKeys;
   byok?: LabsProviderKeys | LabsByokConfig;
@@ -578,21 +777,125 @@ export interface LabsToolListResponse {
 
 export interface LabsVoiceListOptions {
   provider?: string;
+  search?: string;
+  /** Native/accent language advertised for the individual voice. */
+  language?: string;
+  /** Language that the provider model and Ultravox can both run live. */
+  compatibleLanguage?: string;
+  compatible_language?: string;
+  gender?: LabsVoiceGender;
+  voiceType?: string;
+  voice_type?: string;
+  model?: string;
+  runtimeProvider?: string;
+  runtime_provider?: string;
+  configuredOnly?: boolean;
+  configured_only?: boolean;
+  cursor?: number;
+  limit?: number;
+  agencyId?: string;
+  agency_id?: string;
 }
 
 export interface LabsVoiceListResponse {
-  voices: Array<Record<string, unknown>>;
+  account_id?: string;
+  voices: LabsVoiceCatalogItem[];
   total: number;
-  providers: Array<Record<string, unknown>>;
+  cursor?: number;
+  next_cursor?: number | null;
+  providers: Array<{
+    id: string;
+    label: string;
+    configured: boolean;
+    voice_count: number;
+    error?: string | null;
+  }>;
   provider_accounts?: Record<string, unknown>;
   errors?: Record<string, string>;
+  catalog?: {
+    dynamic: boolean;
+    source: string;
+    normalization_schema_version: number;
+    cache_ttl_seconds: number;
+    capabilities_url?: string;
+  };
+}
+
+export interface LabsVoiceModelCapability {
+  provider: string;
+  model?: string | null;
+  known: boolean;
+  language_codes: string[];
+  enumerated_language_count: number;
+  generally_available_language_codes: string[];
+  experimental_language_codes: string[];
+  documented_language_count: number;
+  documented_language_count_is_minimum: boolean;
+  support_tier: string;
+  cross_lingual: boolean | null;
+  documentation_url?: string | null;
+  verified_at: string;
+  ultravox_routing_language_codes: string[];
+  ultravox_routing_language_count: number;
+}
+
+export interface LabsVoiceProviderCapability {
+  provider: string;
+  label: string;
+  ultravox_integration: "native" | "named_external" | string;
+  default_model?: string | null;
+  models: LabsVoiceModelCapability[];
+}
+
+export interface LabsVoiceCapabilitiesResponse {
+  runtime: "ultravox" | string;
+  runtime_spoken_languages: LabsVoiceLanguage[];
+  runtime_spoken_language_count: number;
+  providers: LabsVoiceProviderCapability[];
+  selection_rule: Record<string, string>;
+  normalization_schema_version: number;
+}
+
+export interface LabsVoiceRecommendOptions extends LabsVoicePreference {
+  limit?: number;
+  agencyId?: string;
+  agency_id?: string;
+}
+
+export interface LabsVoiceRecommendation {
+  voice: LabsVoiceCatalogItem;
+  score: number;
+  reasons: string[];
+}
+
+export interface LabsVoiceRecommendResponse {
+  account_id?: string;
+  description: string;
+  matches: LabsVoiceRecommendation[];
+  total_considered: number;
+}
+
+export interface LabsVoicePreview {
+  content: ArrayBuffer;
+  mediaType: string;
+}
+
+export interface LabsRuntimeResponse {
+  account_id: string;
+  provider: "ultravox" | string;
+  managed: boolean;
+  byok_connected: boolean;
+  base_url?: string;
+  updated_at?: string;
 }
 
 export interface LabsCallListOptions {
   agencyId?: string;
+  agency_id?: string;
   agentKey?: string;
   agent_key?: string;
   limit?: number;
+  offset?: number;
 }
 
 export interface LabsCallArtifact {
@@ -603,7 +906,11 @@ export interface LabsCallArtifact {
   started_at?: string;
   duration_seconds?: number;
   recording_url?: string;
+  recording_download_url?: string;
+  recording_archived?: boolean;
   transcript_url?: string;
+  watcher_events?: LabsDeveloperActivityEvent[];
+  watcher_event_count?: number;
   [extra: string]: unknown;
 }
 
@@ -632,6 +939,40 @@ export interface LabsTranscriptListResponse {
   [extra: string]: unknown;
 }
 
+export interface LabsDeveloperActivityEvent {
+  id: string;
+  account_id: string;
+  event_type: string;
+  resource_type: string;
+  resource_id: string;
+  source?: string;
+  detail?: Record<string, unknown>;
+  created_at: string;
+  [extra: string]: unknown;
+}
+
+export interface LabsActivityListOptions {
+  accountId?: string;
+  account_id?: string;
+  agencyId?: string;
+  agency_id?: string;
+  eventType?: string;
+  event_type?: string;
+  resourceType?: string;
+  resource_type?: string;
+  resourceId?: string;
+  resource_id?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface LabsActivityListResponse {
+  events: LabsDeveloperActivityEvent[];
+  count: number;
+  next_offset?: number | null;
+  account_id?: string;
+}
+
 export interface LabsPhoneNumberSearchOptions {
   agencyId?: string;
   agency_id?: string;
@@ -718,6 +1059,8 @@ export interface LabsPhoneNumberProvisionRequest {
   numberPool?: string;
   number_pool?: string;
   premium?: boolean;
+  billingCheckoutSessionId?: string;
+  billing_checkout_session_id?: string;
   style?: LabsAgentStyle;
   agentStyle?: LabsAgentStyle;
   agent_style?: LabsAgentStyle;
@@ -779,7 +1122,7 @@ export interface CreateLabsAgentWithNumberRequest extends CreateLabsAgentRequest
 }
 
 export interface CreateLabsAgentWithNumberResponse extends CreateLabsAgentResponse {
-  number?: LabsPhoneNumberProvisionResponse;
+  number?: LabsPhoneNumberProvisionResponse | LabsBillingCheckoutResponse;
 }
 
 export interface LabsAgentResponse {
@@ -805,6 +1148,7 @@ export interface CreateLabsAgentResponse {
     snippet?: string;
     [extra: string]: unknown;
   };
+  call_plan?: LabsCallPlan;
   [extra: string]: unknown;
 }
 
@@ -1094,6 +1438,140 @@ const COACH_SYSTEM =
   "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 " +
+  "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 " +
+  "(empathy, tactical, guardrail, or mixed). Be silent with low confidence when evidence is weak.";
+
+interface NormalizedDirectiveContract {
+  empathy_directive: Required<Pick<DirectiveTextControl, "enabled" | "instructions">> & { max_chars: number };
+  tactical_directive: Required<Pick<DirectiveTextControl, "enabled" | "instructions">> & { max_chars: number };
+  surface_facts: Required<Pick<DirectiveListControl, "enabled" | "instructions">> & {
+    max_items: number;
+    item_max_chars: number;
+  };
+  guardrails: Required<Pick<DirectiveListControl, "enabled" | "instructions">> & {
+    max_items: number;
+    item_max_chars: number;
+  };
+  language_mode: "caller" | "model" | "fixed";
+  fixed_language: string;
+  allowed_kinds: SecondMindDirectiveKind[];
+  confidence_threshold: number;
+  operator_guardrails: string[];
+}
+
+function boundedInteger(value: unknown, fallback: number, minimum: number, maximum: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed)
+    ? Math.max(minimum, Math.min(maximum, Math.trunc(parsed)))
+    : fallback;
+}
+
+function textControl(input: DirectiveTextControl | undefined): NormalizedDirectiveContract["empathy_directive"] {
+  return {
+    enabled: input?.enabled ?? true,
+    instructions: String(input?.instructions ?? "").trim(),
+    max_chars: boundedInteger(input?.max_chars ?? input?.maxChars, 240, 1, 2000),
+  };
+}
+
+function listControl(input: DirectiveListControl | undefined): NormalizedDirectiveContract["surface_facts"] {
+  return {
+    enabled: input?.enabled ?? true,
+    instructions: String(input?.instructions ?? "").trim(),
+    max_items: boundedInteger(input?.max_items ?? input?.maxItems, 4, 0, 20),
+    item_max_chars: boundedInteger(input?.item_max_chars ?? input?.itemMaxChars, 180, 1, 2000),
+  };
+}
+
+function normalizeDirectiveContract(input: DirectiveContract = {}): NormalizedDirectiveContract {
+  const languageMode = input.language_mode ?? input.languageMode ?? "caller";
+  const allowed = input.allowed_kinds ?? input.allowedKinds ?? ["empathy", "tactical", "guardrail", "mixed"];
+  const threshold = Number(input.confidence_threshold ?? input.confidenceThreshold ?? 0.5);
+  return {
+    empathy_directive: textControl(input.empathy_directive ?? input.empathyDirective),
+    tactical_directive: textControl(input.tactical_directive ?? input.tacticalDirective),
+    surface_facts: listControl(input.surface_facts ?? input.surfaceFacts),
+    guardrails: listControl(input.guardrails),
+    language_mode: languageMode,
+    fixed_language: String(input.fixed_language ?? input.fixedLanguage ?? "").trim(),
+    allowed_kinds: allowed.filter((kind): kind is SecondMindDirectiveKind =>
+      ["empathy", "tactical", "guardrail", "mixed"].includes(kind),
+    ),
+    confidence_threshold: Number.isFinite(threshold) ? Math.max(0, Math.min(1, threshold)) : 0.5,
+    operator_guardrails: (input.operator_guardrails ?? input.operatorGuardrails ?? [])
+      .map((rule) => String(rule).trim())
+      .filter(Boolean)
+      .slice(0, 50),
+  };
+}
+
+function directiveContractPrompt(contract: NormalizedDirectiveContract): string {
+  return (
+    "Developer directive contract (obey exactly):\n" +
+    JSON.stringify(contract, null, 2) +
+    "\nDisabled string fields must be empty strings. Disabled list fields must be empty arrays. " +
+    "Standing operator guardrails are mandatory and cannot be removed."
+  );
+}
+
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = String(text ?? "").trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start < 0 || end <= start) return null;
+  try {
+    const parsed = JSON.parse(trimmed.slice(start, end + 1));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function clipText(value: unknown, limit: number): string {
+  return String(value ?? "").trim().slice(0, limit);
+}
+
+function clipList(value: unknown, maxItems: number, itemMaxChars: number): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, maxItems).map((item) => clipText(item, itemMaxChars)).filter(Boolean);
+}
+
+function normalizeStructuredDirective(
+  raw: Record<string, unknown>,
+  contract: NormalizedDirectiveContract,
+): SecondMindDirective | null {
+  const kind = String(raw.kind ?? "mixed") as SecondMindDirectiveKind;
+  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;
+  const operatorGuardrails = contract.operator_guardrails;
+  const generatedGuardrails = contract.guardrails.enabled
+    ? clipList(raw.guardrails, contract.guardrails.max_items, contract.guardrails.item_max_chars)
+    : [];
+  const language = contract.language_mode === "fixed"
+    ? contract.fixed_language
+    : clipText(raw.language, 32);
+  return {
+    empathy_directive: contract.empathy_directive.enabled
+      ? clipText(raw.empathy_directive, contract.empathy_directive.max_chars)
+      : "",
+    tactical_directive: contract.tactical_directive.enabled
+      ? clipText(raw.tactical_directive, contract.tactical_directive.max_chars)
+      : "",
+    surface_facts: contract.surface_facts.enabled
+      ? clipList(raw.surface_facts, contract.surface_facts.max_items, contract.surface_facts.item_max_chars)
+      : [],
+    guardrails: [...new Set([...generatedGuardrails, ...operatorGuardrails])],
+    language,
+    confidence: contract.allowed_kinds.includes(kind) ? confidence : 0,
+    kind,
+  };
+}
+
 export class SupafoneLabs {
   readonly baseUrl: string;
   readonly supafoneApiBaseUrl: string;
@@ -1153,6 +1631,15 @@ export class SupafoneLabs {
     this.campaigns = new CampaignsNamespace(this);
   }
 
+  /** Build a complete hosted plan with the same Supafone key used to create agents. */
+  generateCallStages(input: CreateLabsAgentRequest & { description?: string }): Promise<LabsCallPlan> {
+    return this.labs.agents.plan(input);
+  }
+
+  generate_call_stages(input: CreateLabsAgentRequest & { description?: string }): Promise<LabsCallPlan> {
+    return this.generateCallStages(input);
+  }
+
   /** True once login() (or a passed sessionToken) is in effect. */
   get isLoggedIn(): boolean {
     return !!this.sessionToken;
@@ -1215,6 +1702,31 @@ export class SupafoneLabs {
     }
   }
 
+  /** @internal Authenticated binary request to the Supafone app API. */
+  async requestSupafoneBinary(path: string): Promise<LabsVoicePreview> {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await fetch(this.supafoneApiBaseUrl + path, {
+        method: "GET",
+        signal: ctrl.signal,
+        headers: { Authorization: `Bearer ${this.supafoneApiKey}` },
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        const parsed = text ? safeJson(text) : {};
+        const detail = (parsed as { detail?: string })?.detail ?? text ?? `HTTP ${res.status}`;
+        throw new SupafoneLabsError(`GET ${path}: ${detail}`, res.status, parsed);
+      }
+      return {
+        content: await res.arrayBuffer(),
+        mediaType: res.headers.get("content-type") || "application/octet-stream",
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   /**
    * Exchange the account email/password for a product-API JWT (the same login
    * as app.supafone.ai). Called lazily by campaigns/calls — call directly only
@@ -1426,6 +1938,52 @@ export class SupafoneLabs {
     return out.text.trim();
   }
 
+  /**
+   * Structured SecondMind 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> {
+    const contract = normalizeDirectiveContract(
+      opts.directive_contract ?? opts.directiveContract ?? {},
+    );
+    const operatorRules = [opts.guardrails, ...contract.operator_guardrails]
+      .map((rule) => String(rule ?? "").trim())
+      .filter(Boolean);
+    const system = [
+      STRUCTURED_COACH_SYSTEM,
+      directiveContractPrompt(contract),
+      operatorRules.length ? `Operator rules:\n${operatorRules.join("\n")}` : "",
+    ].filter(Boolean).join("\n\n");
+    const out = await this.oracle({
+      model: opts.model,
+      maxTokens: opts.maxTokens ?? 320,
+      ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+      messages: [
+        { role: "system", content: system },
+        { role: "user", content: transcript },
+      ],
+    });
+    const parsed = parseJsonObject(out.text);
+    let directive = parsed ? normalizeStructuredDirective(parsed, contract) : null;
+    if (directive && opts.transform) {
+      directive = await opts.transform(directive);
+    }
+    if (!directive || directive.confidence < contract.confidence_threshold) return null;
+    return directive;
+  }
+
+  /** Alias that reads naturally in applications building their own watcher loop. */
+  directive(
+    transcript: string,
+    opts: StructuredWhisperOptions = {},
+  ): Promise<SecondMindDirective | null> {
+    return this.whisperStructured(transcript, opts);
+  }
+
   /** Hosted TTS — returns raw audio bytes (WAV/PCM per voice). */
   async tts(text: string, voice = "supafone-labs-calm-en"): Promise<Uint8Array> {
     const ctrl = new AbortController();
@@ -2088,23 +2646,31 @@ class CampaignsNamespace {
 
 class LabsNamespace {
   readonly agents: LabsAgentsNamespace;
+  readonly billing: LabsBillingNamespace;
   readonly presets: LabsPresetsNamespace;
   readonly tools: LabsToolsNamespace;
   readonly voices: LabsVoicesNamespace;
+  readonly runtime: LabsRuntimeNamespace;
   readonly phoneNumbers: LabsPhoneNumbersNamespace;
   readonly telephony: LabsTelephonyNamespace;
   readonly calls: LabsCallsNamespace;
+  readonly activity: LabsActivityNamespace;
+  readonly plans: LabsPlansNamespace;
   readonly recordings: LabsRecordingsNamespace;
   readonly transcripts: LabsTranscriptsNamespace;
 
   constructor(private sm: SupafoneLabs) {
     this.agents = new LabsAgentsNamespace(sm);
+    this.billing = new LabsBillingNamespace(sm);
     this.presets = new LabsPresetsNamespace(sm);
     this.tools = new LabsToolsNamespace(sm);
     this.voices = new LabsVoicesNamespace(sm);
+    this.runtime = new LabsRuntimeNamespace(sm);
     this.phoneNumbers = new LabsPhoneNumbersNamespace(sm);
     this.telephony = new LabsTelephonyNamespace(sm);
     this.calls = new LabsCallsNamespace(sm);
+    this.activity = new LabsActivityNamespace(sm);
+    this.plans = new LabsPlansNamespace(sm);
     this.recordings = new LabsRecordingsNamespace(sm);
     this.transcripts = new LabsTranscriptsNamespace(sm);
   }
@@ -2115,6 +2681,73 @@ class LabsNamespace {
   }
 }
 
+export type LabsBillingCheckoutKind = "plan" | "credits" | "number_addon";
+
+export interface LabsBillingCheckoutInput {
+  kind?: LabsBillingCheckoutKind;
+  planKey?: "developer" | "growth" | "scale" | string;
+  plan_key?: string;
+  numberStrategy?: "dedicated" | "premium" | string;
+  number_strategy?: string;
+  phoneNumber?: string;
+  phone_number?: string;
+  quantity?: number;
+  successUrl?: string;
+  success_url?: string;
+  cancelUrl?: string;
+  cancel_url?: string;
+}
+
+export interface LabsBillingCheckoutResponse {
+  status: "requires_payment" | "pending" | "paid" | string;
+  checkout_session_id: string;
+  checkout_url?: string;
+  kind: LabsBillingCheckoutKind | string;
+  plan_key?: string | null;
+  number_strategy?: string | null;
+  phone_number?: string | null;
+  stripe_subscription_id?: string | null;
+  ready_to_provision?: boolean;
+  next_step?: string;
+}
+
+class LabsBillingNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  /** Start hosted Stripe Checkout. MCP callers should render checkout_url as a link. */
+  checkout(input: LabsBillingCheckoutInput = {}): Promise<LabsBillingCheckoutResponse> {
+    return this.sm.request("POST", "/v1/billing/checkout", compact({
+      kind: input.kind ?? "plan",
+      plan_key: input.plan_key ?? input.planKey,
+      number_strategy: input.number_strategy ?? input.numberStrategy,
+      phone_number: input.phone_number ?? input.phoneNumber,
+      quantity: input.quantity,
+      success_url: input.success_url ?? input.successUrl,
+      cancel_url: input.cancel_url ?? input.cancelUrl,
+    }));
+  }
+
+  status(checkoutSessionId: string): Promise<LabsBillingCheckoutResponse> {
+    if (!checkoutSessionId?.trim()) throw new SupafoneLabsError("checkoutSessionId is required");
+    return this.sm.request(
+      "GET",
+      `/v1/billing/checkout/${encodeURIComponent(checkoutSessionId)}`,
+    );
+  }
+
+  portal(): Promise<{ url: string }> {
+    return this.sm.request("POST", "/v1/billing/portal", {});
+  }
+
+  createCheckout(input: LabsBillingCheckoutInput = {}): Promise<LabsBillingCheckoutResponse> {
+    return this.checkout(input);
+  }
+
+  getCheckout(checkoutSessionId: string): Promise<LabsBillingCheckoutResponse> {
+    return this.status(checkoutSessionId);
+  }
+}
+
 class LabsAgentsNamespace {
   constructor(private sm: SupafoneLabs) {}
 
@@ -2127,6 +2760,19 @@ class LabsAgentsNamespace {
     );
   }
 
+  /** Preview the exact validated call-plan contract the Supafone runtime executes. */
+  plan(input: CreateLabsAgentRequest & { description?: string }): Promise<LabsCallPlan> {
+    return this.sm.requestSupafoneApi<LabsCallPlan>(
+      "POST",
+      "/api/v1/labs/agent-plans",
+      stagePlanPayload(input),
+    );
+  }
+
+  generateCallStages(input: CreateLabsAgentRequest & { description?: string }): Promise<LabsCallPlan> {
+    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. */
@@ -2266,13 +2912,140 @@ class LabsToolsNamespace {
 class LabsVoicesNamespace {
   constructor(private sm: SupafoneLabs) {}
 
-  /** Supafone-managed Cartesia voices. Other TTS engines remain explicit BYOK choices. */
+  /** Live normalized catalog from every connected/managed TTS provider. */
   list(opts: LabsVoiceListOptions = {}): Promise<LabsVoiceListResponse> {
     const q = new URLSearchParams();
     if (opts.provider) q.set("provider", opts.provider);
+    if (opts.search) q.set("search", opts.search);
+    if (opts.language) q.set("language", opts.language);
+    const compatibleLanguage = opts.compatible_language ?? opts.compatibleLanguage;
+    if (compatibleLanguage) q.set("compatible_language", compatibleLanguage);
+    if (opts.gender) q.set("gender", opts.gender);
+    const voiceType = opts.voice_type ?? opts.voiceType;
+    if (voiceType) q.set("voice_type", voiceType);
+    if (opts.model) q.set("model", opts.model);
+    const runtimeProvider = opts.runtime_provider ?? opts.runtimeProvider;
+    if (runtimeProvider) q.set("runtime_provider", runtimeProvider);
+    const configuredOnly = opts.configured_only ?? opts.configuredOnly;
+    if (configuredOnly !== undefined) q.set("configured_only", String(configuredOnly));
+    if (opts.cursor !== undefined) q.set("cursor", String(opts.cursor));
+    if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+    const agencyId = opts.agency_id ?? opts.agencyId;
+    if (agencyId) q.set("agency_id", agencyId);
     const suffix = q.toString() ? `?${q}` : "";
     return this.sm.requestSupafoneApi<LabsVoiceListResponse>("GET", `/api/v1/labs/voices${suffix}`);
   }
+
+  /** Provider/model language limits and their Ultravox-compatible intersection. */
+  capabilities(): Promise<LabsVoiceCapabilitiesResponse> {
+    return this.sm.requestSupafoneApi<LabsVoiceCapabilitiesResponse>(
+      "GET",
+      "/api/v1/labs/voices/capabilities",
+    );
+  }
+
+  /** Page through the complete normalized catalog. */
+  async listAll(
+    opts: Omit<LabsVoiceListOptions, "cursor" | "limit"> & { pageSize?: number; maxPages?: number } = {},
+  ): Promise<LabsVoiceListResponse> {
+    const pageSize = Math.max(1, Math.min(opts.pageSize ?? 250, 250));
+    const maxPages = Math.max(1, opts.maxPages ?? 100);
+    let cursor: number | null = 0;
+    let pages = 0;
+    let first: LabsVoiceListResponse | undefined;
+    const voices: LabsVoiceCatalogItem[] = [];
+    const seen = new Set<number>();
+    while (cursor !== null && pages < maxPages) {
+      if (seen.has(cursor)) throw new SupafoneLabsError("Voice catalog returned a repeated cursor");
+      seen.add(cursor);
+      const page = await this.list({ ...opts, cursor, limit: pageSize });
+      first ??= page;
+      voices.push(...page.voices);
+      cursor = page.next_cursor ?? null;
+      pages += 1;
+    }
+    if (cursor !== null) {
+      throw new SupafoneLabsError(`Voice catalog exceeded maxPages=${maxPages}`);
+    }
+    return {
+      ...(first ?? { total: 0, providers: [] }),
+      voices,
+      total: first?.total ?? voices.length,
+      cursor: 0,
+      next_cursor: null,
+    };
+  }
+
+  /** Rank real current voices from a plain-language description. */
+  recommend(opts: LabsVoiceRecommendOptions): Promise<LabsVoiceRecommendResponse> {
+    if (!opts.description?.trim()) {
+      throw new SupafoneLabsError("description is required — describe the voice you want");
+    }
+    return this.sm.requestSupafoneApi<LabsVoiceRecommendResponse>(
+      "POST",
+      "/api/v1/labs/voices/recommend",
+      compact({
+        agency_id: opts.agency_id ?? opts.agencyId,
+        description: opts.description.trim(),
+        language: opts.language,
+        provider: opts.provider,
+        gender: opts.gender,
+        voice_type: opts.voice_type ?? opts.voiceType,
+        model: opts.model,
+        configured_only: opts.configured_only ?? opts.configuredOnly,
+        premium: opts.premium,
+        limit: opts.limit,
+      }),
+    );
+  }
+
+  /** Download an authenticated voice preview. */
+  preview(voiceId: string, opts: { agencyId?: string; agency_id?: string } = {}): Promise<LabsVoicePreview> {
+    if (!voiceId.trim()) throw new SupafoneLabsError("voiceId is required");
+    const q = new URLSearchParams({ voice: voiceId.trim() });
+    const agencyId = opts.agency_id ?? opts.agencyId;
+    if (agencyId) q.set("agency_id", agencyId);
+    return this.sm.requestSupafoneBinary(`/api/v1/labs/voices/preview?${q}`);
+  }
+
+  /** Convert a catalog row into the exact Agent Factory voice field. */
+  selection(voice: LabsVoiceCatalogItem): LabsVoiceSelection {
+    if (!voice?.id) throw new SupafoneLabsError("A catalog voice with id is required");
+    return compact({
+      provider: voice.provider_key || voice.source,
+      voiceId: voice.id,
+      model: voice.model || undefined,
+    }) as LabsVoiceSelection;
+  }
+}
+
+class LabsRuntimeNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  get(opts: { agencyId?: string; agency_id?: string } = {}): Promise<LabsRuntimeResponse> {
+    const q = new URLSearchParams();
+    const agencyId = opts.agency_id ?? opts.agencyId;
+    if (agencyId) q.set("agency_id", agencyId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi<LabsRuntimeResponse>("GET", `/api/v1/labs/runtime${suffix}`);
+  }
+
+  configure(input: {
+    agencyId?: string;
+    agency_id?: string;
+    provider?: "ultravox" | string;
+    credentials?: { apiKey?: string; api_key?: string; baseUrl?: string; base_url?: string };
+  }): Promise<LabsRuntimeResponse> {
+    const credentials = input.credentials ?? {};
+    return this.sm.requestSupafoneApi<LabsRuntimeResponse>("PUT", "/api/v1/labs/runtime", compact({
+      agency_id: input.agency_id ?? input.agencyId,
+      provider: input.provider ?? "ultravox",
+      credentials: compact({
+        api_key: credentials.api_key ?? credentials.apiKey,
+        base_url: credentials.base_url ?? credentials.baseUrl,
+      }),
+    }));
+  }
 }
 
 class LabsCallsNamespace {
@@ -2284,11 +3057,53 @@ class LabsCallsNamespace {
     return this.sm.requestSupafoneApi<LabsCallListResponse>("GET", `/api/v1/labs/calls${suffix}`);
   }
 
-  get(callId: string, opts: { agencyId?: string } = {}): Promise<Record<string, unknown>> {
+  get(callId: string, opts: { agencyId?: string; agency_id?: string } = {}): Promise<{ call: LabsCallArtifact }> {
     const q = new URLSearchParams();
-    if (opts.agencyId) q.set("agency_id", opts.agencyId);
+    const agencyId = opts.agency_id ?? opts.agencyId;
+    if (agencyId) q.set("agency_id", agencyId);
     const suffix = q.toString() ? `?${q}` : "";
-    return this.sm.requestSupafoneApi("GET", `/api/v1/labs/calls/${encodeURIComponent(callId)}${suffix}`);
+    return this.sm.requestSupafoneApi<{ call: LabsCallArtifact }>("GET", `/api/v1/labs/calls/${encodeURIComponent(callId)}${suffix}`);
+  }
+
+  delete(callId: string, opts: { agencyId?: string; agency_id?: string } = {}): Promise<Record<string, unknown>> {
+    const q = new URLSearchParams();
+    const agencyId = opts.agency_id ?? opts.agencyId;
+    if (agencyId) q.set("agency_id", agencyId);
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi("DELETE", `/api/v1/labs/calls/${encodeURIComponent(callId)}${suffix}`);
+  }
+}
+
+class LabsActivityNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  list(opts: LabsActivityListOptions = {}): Promise<LabsActivityListResponse> {
+    const q = new URLSearchParams();
+    const accountId = opts.account_id ?? opts.accountId ?? opts.agency_id ?? opts.agencyId;
+    if (accountId) q.set("account_id", accountId);
+    const eventType = opts.event_type ?? opts.eventType;
+    if (eventType) q.set("event_type", eventType);
+    const resourceType = opts.resource_type ?? opts.resourceType;
+    if (resourceType) q.set("resource_type", resourceType);
+    const resourceId = opts.resource_id ?? opts.resourceId;
+    if (resourceId) q.set("resource_id", resourceId);
+    if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+    if (opts.offset !== undefined) q.set("offset", String(opts.offset));
+    const suffix = q.toString() ? `?${q}` : "";
+    return this.sm.requestSupafoneApi<LabsActivityListResponse>("GET", `/api/v1/labs/activity${suffix}`);
+  }
+}
+
+class LabsPlansNamespace {
+  constructor(private sm: SupafoneLabs) {}
+
+  list(opts: Omit<LabsActivityListOptions, "eventType" | "event_type" | "resourceType" | "resource_type"> = {}): Promise<LabsActivityListResponse> {
+    const activity = new LabsActivityNamespace(this.sm);
+    return activity.list({
+      ...opts,
+      eventType: "studio.plan.created",
+      resourceType: "studio_plan",
+    });
   }
 }
 
@@ -2362,13 +3177,32 @@ class LabsPhoneNumbersNamespace {
     );
   }
 
-  /** Buy a Supafone-managed number. Developers do not need a Twilio account. */
-  buy(input: LabsPhoneNumberProvisionRequest): Promise<LabsPhoneNumberProvisionResponse> {
+  /**
+   * Buy a managed number. Paid strategies return a hosted Checkout link first;
+   * call again with billingCheckoutSessionId after Checkout reports paid.
+   */
+  buy(
+    input: LabsPhoneNumberProvisionRequest,
+  ): Promise<LabsPhoneNumberProvisionResponse | LabsBillingCheckoutResponse> {
+    const strategy = input.number_strategy ?? input.numberStrategy ?? (input.premium ? "premium" : "default_pool");
+    const checkoutSessionId = input.billing_checkout_session_id ?? input.billingCheckoutSessionId;
+    if ((strategy === "dedicated" || strategy === "premium") && !checkoutSessionId) {
+      const phoneNumber = input.phone_number ?? input.phoneNumber;
+      if (!phoneNumber) {
+        return Promise.reject(new SupafoneLabsError("phoneNumber is required before starting number Checkout"));
+      }
+      return this.sm.labs.billing.checkout({
+        kind: "number_addon",
+        numberStrategy: strategy,
+        phoneNumber,
+      });
+    }
     return this.sm.requestSupafoneApi<LabsPhoneNumberProvisionResponse>(
       "POST",
       "/api/v1/labs/phone-numbers",
       phoneNumberProvisionPayload({
         ...input,
+        numberStrategy: strategy,
         telephony: input.telephony ?? { mode: "supafone_managed", provider: "supafone" },
       }),
     );
@@ -2423,7 +3257,9 @@ class LabsPhoneNumbersNamespace {
    * Search if needed, buy the first matching Supafone-managed number, and assign
    * it to the supplied agent. This is the zero-Twilio-account happy path.
    */
-  async buyAndAssign(input: LabsPhoneNumberBuyAndAssignRequest): Promise<LabsPhoneNumberProvisionResponse> {
+  async buyAndAssign(
+    input: LabsPhoneNumberBuyAndAssignRequest,
+  ): Promise<LabsPhoneNumberProvisionResponse | LabsBillingCheckoutResponse> {
     let phoneNumber = input.phoneNumber ?? input.phone_number ?? "";
     if (!phoneNumber) {
       const found = await this.search({
@@ -2631,12 +3467,14 @@ class OptimizerNamespace {
 }
 
 function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown> {
+  const fixedLanguage = input.preferred_language ?? input.preferredLanguage ?? input.language;
   return compact({
     agency_id: input.agency_id ?? input.agencyId,
     agent_key: input.agent_key ?? input.agentKey,
     agent_type: input.agent_type ?? input.agentType,
     style: input.agent_style ?? input.agentStyle ?? input.style,
     name: input.name,
+    description: input.description,
     assistant_name: input.assistant_name ?? input.assistantName,
     business_name: input.business_name ?? input.businessName,
     industry: input.industry,
@@ -2649,11 +3487,18 @@ function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown
     preset_key: input.preset_key ?? input.presetKey,
     runtime_mode: input.runtime_mode ?? input.runtimeMode,
     call_stages: callStagesPayload(input),
+    stage_generation: input.stage_generation ?? input.stageGeneration,
+    stage_count: input.stage_count ?? input.stageCount,
+    stage_detail: input.stage_detail ?? input.stageDetail,
     goal: input.goal,
     greeting: input.greeting,
     system_prompt: input.system_prompt ?? input.systemPrompt,
-    language: input.language,
+    language: fixedLanguage,
     voice: input.voice ? voicePayload(input.voice) : undefined,
+    voice_preference: voicePreferencePayload(
+      input.voice_preference ?? input.voicePreference,
+      fixedLanguage,
+    ),
     provider_keys: input.provider_keys ?? (input.providerKeys ? providerKeysPayload(input.providerKeys) : undefined),
     byok: input.byok ? byokPayload(input.byok) : undefined,
     telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
@@ -2673,10 +3518,12 @@ function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown
 
 function hostedListQuery(opts: LabsCallListOptions): URLSearchParams {
   const q = new URLSearchParams();
-  if (opts.agencyId) q.set("agency_id", opts.agencyId);
+  const agencyId = opts.agency_id ?? opts.agencyId;
+  if (agencyId) q.set("agency_id", agencyId);
   const agentKey = opts.agent_key ?? opts.agentKey;
   if (agentKey) q.set("agent_key", agentKey);
   if (opts.limit !== undefined) q.set("limit", String(opts.limit));
+  if (opts.offset !== undefined) q.set("offset", String(opts.offset));
   return q;
 }
 
@@ -2752,6 +3599,7 @@ function phoneNumberProvisionPayload(input: LabsPhoneNumberProvisionRequest): Re
     number_strategy: input.number_strategy ?? input.numberStrategy,
     number_pool: input.number_pool ?? input.numberPool,
     premium: input.premium,
+    billing_checkout_session_id: input.billing_checkout_session_id ?? input.billingCheckoutSessionId,
     style: input.agent_style ?? input.agentStyle ?? input.style,
     direction: input.direction,
     telephony: input.telephony ? telephonyPayload(input.telephony) : undefined,
@@ -2786,12 +3634,39 @@ function phoneNumberReleasePayload(input: LabsPhoneNumberReleaseRequest): Record
   });
 }
 
-function callStagesPayload(input: CreateLabsAgentRequest): Record<string, unknown>[] | undefined {
+function callStagesPayload(
+  input: CreateLabsAgentRequest,
+): Record<string, unknown>[] | LabsStageGeneration | false | undefined {
   const explicit = input.call_stages ?? input.callStages ?? input.stages;
   const auto = input.auto_call_stages ?? input.autoCallStages;
   if (Array.isArray(explicit)) return explicit.map(callStagePayload);
-  if (explicit === false || auto === false) return undefined;
-  return generateCallStages(input).map(callStagePayload);
+  if (explicit === false || auto === false) return false;
+  if (explicit === "oracle" || explicit === "template" || explicit === "off") return explicit;
+  // Omitted means the private Supafone API generates and compiles the plan.
+  return undefined;
+}
+
+function stagePlanPayload(
+  input: CreateLabsAgentRequest & { description?: string },
+): Record<string, unknown> {
+  return compact({
+    agency_id: input.agency_id ?? input.agencyId,
+    description: input.description,
+    name: input.name,
+    assistant_name: input.assistant_name ?? input.assistantName,
+    business_name: input.business_name ?? input.businessName,
+    industry: input.industry,
+    direction: input.direction ?? input.agent_style ?? input.agentStyle ?? input.style,
+    goal: input.goal,
+    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,
+    stage_generation: input.stage_generation ?? input.stageGeneration,
+    stage_count: input.stage_count ?? input.stageCount,
+    stage_detail: input.stage_detail ?? input.stageDetail,
+  });
 }
 
 function callStagePayload(input: LabsCallStage): Record<string, unknown> {
@@ -2802,11 +3677,15 @@ function callStagePayload(input: LabsCallStage): Record<string, unknown> {
     instructions: input.instructions,
     exit_criteria: input.exit_criteria ?? input.exitCriteria,
     tools: input.tools,
+    temperature: input.temperature,
+    next_stages: input.next_stages ?? input.nextStages,
     metadata: input.metadata,
   });
 }
 
 export function generateCallStages(input: CreateLabsAgentRequest): LabsCallStage[] {
+  // Offline compatibility template. New code should use
+  // client.generateCallStages(...) for the hosted, executable plan.
   const direction = String(input.direction ?? input.agent_style ?? input.agentStyle ?? input.style ?? "inbound").toLowerCase();
   const haystack = [
     input.name,
@@ -2882,6 +3761,23 @@ function voicePayload(input: LabsVoiceSelection): Record<string, unknown> {
   });
 }
 
+function voicePreferencePayload(
+  input?: LabsVoicePreference,
+  defaultLanguage?: string,
+): Record<string, unknown> | undefined {
+  if (!input) return undefined;
+  return compact({
+    description: input.description,
+    language: input.language ?? defaultLanguage,
+    provider: input.provider,
+    gender: input.gender,
+    voice_type: input.voice_type ?? input.voiceType,
+    model: input.model,
+    configured_only: input.configured_only ?? input.configuredOnly,
+    premium: input.premium,
+  });
+}
+
 function providerKeysPayload(input: LabsProviderKeys): Record<string, unknown> {
   return compact({
     ultravox: input.ultravox,