supafone-labs 0.4.12 → 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;
@@ -177,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;
@@ -536,8 +703,14 @@ export interface CreateLabsAgentRequest {
   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;
@@ -605,17 +778,106 @@ 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 {
@@ -629,9 +891,11 @@ export interface LabsRuntimeResponse {
 
 export interface LabsCallListOptions {
   agencyId?: string;
+  agency_id?: string;
   agentKey?: string;
   agent_key?: string;
   limit?: number;
+  offset?: number;
 }
 
 export interface LabsCallArtifact {
@@ -642,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;
 }
 
@@ -671,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;
@@ -1136,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;
@@ -1266,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
@@ -1477,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();
@@ -2147,6 +2654,8 @@ class LabsNamespace {
   readonly phoneNumbers: LabsPhoneNumbersNamespace;
   readonly telephony: LabsTelephonyNamespace;
   readonly calls: LabsCallsNamespace;
+  readonly activity: LabsActivityNamespace;
+  readonly plans: LabsPlansNamespace;
   readonly recordings: LabsRecordingsNamespace;
   readonly transcripts: LabsTranscriptsNamespace;
 
@@ -2160,6 +2669,8 @@ class LabsNamespace {
     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);
   }
@@ -2401,17 +2912,111 @@ 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 {
@@ -2452,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<{ 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("GET", `/api/v1/labs/calls/${encodeURIComponent(callId)}${suffix}`);
+    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",
+    });
   }
 }
 
@@ -2820,6 +3467,7 @@ 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,
@@ -2845,8 +3493,12 @@ function labsAgentPayload(input: CreateLabsAgentRequest): Record<string, unknown
     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,
@@ -2866,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;
 }
 
@@ -3107,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,