@absolutejs/voice 0.0.22-beta.521 → 0.0.22-beta.523

package/dist/index.d.ts

@@ -71,6 +71,8 @@ export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, crea
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool, } from "./agent";
 export { createPersonaVoiceCaller, createScriptedVoiceCaller, renderVoiceSimulationTranscript, runVoiceConversationSimulation, } from "./conversationSimulator";
 export type { RunVoiceConversationSimulationInput, VoiceConversationSimulationEndedReason, VoiceConversationSimulationResult, VoicePersonaCallerCompletion, VoiceScriptedCallerStep, VoiceSimulatedSpeaker, VoiceSimulatedTurn, VoiceSimulatorCaller, VoiceSimulatorCallerModel, VoiceSimulatorCallerReply, } from "./conversationSimulator";
+export { createVoiceMCPToolset } from "./mcpToolset";
+export type { CreateVoiceMCPToolsetOptions, MCPClientLike, MCPToolCallResult, MCPToolContentBlock, MCPToolDefinition, VoiceMCPToolResult, } from "./mcpToolset";
 export { createAIVoiceModel } from "./aiVoiceModel";
 export type { CreateAIVoiceModelOptions } from "./aiVoiceModel";
 export { createVoiceAIJudgeCompletion, createVoiceLLMJudge, } from "./llmJudge";
@@ -79,6 +81,10 @@ export { DEFAULT_VOICE_REDACTION_PATTERNS, createVoiceTranscriptRedactor, redact
 export type { CreateVoiceTranscriptRedactorOptions, VoiceRedactionPattern, VoiceTranscriptRedactor, } from "./redaction";
 export { deriveVoiceRecordingRedactionRanges, redactVoiceRecording, } from "./recordingRedaction";
 export type { DeriveVoiceRecordingRedactionRangesInput, RedactVoiceRecordingInput, RedactVoiceRecordingResult, VoiceRecordingRedactionRange, } from "./recordingRedaction";
+export { buildVoiceVariableAnalytics } from "./variableAnalytics";
+export type { BuildVoiceVariableAnalyticsInput, VoiceAnalyticsCall, VoiceAnalyticsVariableValue, VoiceVariableAnalyticsReport, VoiceVariableBreakdown, VoiceVariableValueStats, } from "./variableAnalytics";
+export { VOICE_ZERO_DATA_RETENTION_REDACTION_MARKER, createVoiceZeroDataRetentionPolicy, isVoiceZeroDataRetentionActive, scrubVoiceTraceForZeroDataRetention, scrubVoiceTurnForZeroDataRetention, shouldRetainVoiceRecording, shouldRetainVoiceTranscript, } from "./zeroDataRetention";
+export type { CreateVoiceZeroDataRetentionPolicyOptions, VoiceZeroDataRetentionMode, VoiceZeroDataRetentionPolicy, VoiceZeroDataRetentionRetainFlags, } from "./zeroDataRetention";
 export { DEFAULT_VOICE_PRICE_BOOK, createVoiceCostAccountant, } from "./costAccounting";
 export type { CreateVoiceCostAccountantOptions, VoiceCostAccountant, VoiceCostBreakdown, VoiceCostLLMRecord, VoiceCostSTTRecord, VoiceCostTTSRecord, VoiceCostTelephonyRecord, VoicePriceBook, VoiceProviderRates, } from "./costAccounting";
 export { describeVoiceAssistantMode, resolveVoiceAssistantMode, } from "./assistantMode";

package/dist/index.js

@@ -35415,6 +35415,52 @@ Respond with only your spoken line. When your goal is met or you want to hang up
     persona: options.persona
   };
 };
+// src/mcpToolset.ts
+var flattenContent = (result) => {
+  const blocks = result.content ?? [];
+  const text = blocks.filter((block) => block.type === "text" && typeof block.text === "string").map((block) => block.text).join(`
+`).trim();
+  if (text.length > 0)
+    return text;
+  if (result.structuredContent !== undefined) {
+    return JSON.stringify(result.structuredContent);
+  }
+  return "";
+};
+var createVoiceMCPToolset = async (options) => {
+  const prefix = options.namePrefix ?? "";
+  const allowed = options.allowedTools ? new Set(options.allowedTools) : undefined;
+  const blocked = options.blockedTools ? new Set(options.blockedTools) : undefined;
+  const listed = await Promise.resolve(options.client.listTools());
+  const tools = [];
+  for (const definition of listed.tools) {
+    if (allowed && !allowed.has(definition.name))
+      continue;
+    if (blocked && blocked.has(definition.name))
+      continue;
+    const exposedName = `${prefix}${definition.name}`;
+    tools.push(createVoiceAgentTool({
+      ...definition.description !== undefined ? { description: definition.description } : {},
+      execute: async ({ args }) => {
+        const raw = await Promise.resolve(options.client.callTool({
+          arguments: args,
+          name: definition.name
+        }));
+        const result = {
+          isError: raw.isError === true,
+          raw,
+          text: flattenContent(raw),
+          ...raw.structuredContent !== undefined ? { structuredContent: raw.structuredContent } : {}
+        };
+        return result;
+      },
+      name: exposedName,
+      ...definition.inputSchema !== undefined ? { parameters: definition.inputSchema } : {},
+      resultToMessage: options.resultToMessage ?? ((result) => result.isError ? `Tool error: ${result.text || "unknown error"}` : result.text || "(no output)")
+    }));
+  }
+  return tools;
+};
 // src/aiVoiceModel.ts
 var toProviderMessages = (messages) => {
   const out = [];
@@ -35748,6 +35794,134 @@ var redactVoiceRecording = (input) => {
     redactedCount: ranges.length
   };
 };
+// src/variableAnalytics.ts
+var stringifyValue = (value) => {
+  if (value === null || value === undefined)
+    return "(none)";
+  return String(value);
+};
+var mean = (values) => values.length === 0 ? null : values.reduce((sum, value) => sum + value, 0) / values.length;
+var successRateFor = (calls, successOutcomes) => {
+  const flagged = calls.filter((call) => call.success !== undefined || call.outcome !== undefined);
+  if (flagged.length === 0)
+    return null;
+  const successes = flagged.filter((call) => call.success !== undefined ? call.success : call.outcome !== undefined && successOutcomes.has(call.outcome.toLowerCase())).length;
+  return successes / flagged.length;
+};
+var buildVoiceVariableAnalytics = (input) => {
+  const successOutcomes = new Set((input.successOutcomes ?? ["won", "resolved", "qualified", "completed", "booked"]).map((outcome) => outcome.toLowerCase()));
+  const totalCalls = input.calls.length;
+  const overall = {
+    avgCostUsd: mean(input.calls.map((call) => call.costUsd).filter((cost) => typeof cost === "number")),
+    avgDurationSeconds: mean(input.calls.map((call) => call.durationSeconds).filter((duration) => typeof duration === "number")),
+    successRate: successRateFor(input.calls, successOutcomes)
+  };
+  const byVariable = {};
+  for (const variable of input.variables) {
+    const groups = new Map;
+    let missingCount = 0;
+    for (const call of input.calls) {
+      const raw = call.variables[variable];
+      if (raw === undefined || raw === null) {
+        missingCount += 1;
+        continue;
+      }
+      const key = stringifyValue(raw);
+      const bucket = groups.get(key) ?? [];
+      bucket.push(call);
+      groups.set(key, bucket);
+    }
+    let values = [];
+    for (const [value, calls] of groups) {
+      const outcomes = {};
+      for (const call of calls) {
+        if (call.outcome) {
+          outcomes[call.outcome] = (outcomes[call.outcome] ?? 0) + 1;
+        }
+      }
+      values.push({
+        avgCostUsd: mean(calls.map((call) => call.costUsd).filter((cost) => typeof cost === "number")),
+        avgDurationSeconds: mean(calls.map((call) => call.durationSeconds).filter((d) => typeof d === "number")),
+        count: calls.length,
+        outcomes,
+        share: totalCalls === 0 ? 0 : calls.length / totalCalls,
+        successRate: successRateFor(calls, successOutcomes),
+        value
+      });
+    }
+    values.sort((left, right) => right.count - left.count);
+    if (input.topValuesPerVariable !== undefined) {
+      values = values.slice(0, input.topValuesPerVariable);
+    }
+    byVariable[variable] = {
+      distinctValues: groups.size,
+      missingCount,
+      values,
+      variable
+    };
+  }
+  return { byVariable, overall, totalCalls };
+};
+// src/zeroDataRetention.ts
+var RETAIN_ALL = {
+  assistantText: true,
+  metadata: true,
+  recordings: true,
+  traceText: true,
+  transcriptText: true
+};
+var RETAIN_NONE = {
+  assistantText: false,
+  metadata: false,
+  recordings: false,
+  traceText: false,
+  transcriptText: false
+};
+var REDACTED = "[redacted:zdr]";
+var createVoiceZeroDataRetentionPolicy = (options = {}) => {
+  const mode = options.mode ?? "off";
+  const base = mode === "strict" ? RETAIN_NONE : mode === "off" ? RETAIN_ALL : RETAIN_ALL;
+  return {
+    mode,
+    retain: { ...base, ...options.retain ?? {} }
+  };
+};
+var isVoiceZeroDataRetentionActive = (policy) => policy.mode !== "off" && Object.values(policy.retain).some((retain) => retain === false);
+var shouldRetainVoiceRecording = (policy) => policy.retain.recordings;
+var shouldRetainVoiceTranscript = (policy) => policy.retain.transcriptText;
+var scrubVoiceTurnForZeroDataRetention = (turn, policy) => {
+  if (!isVoiceZeroDataRetentionActive(policy))
+    return turn;
+  const scrubbed = {
+    ...turn,
+    text: policy.retain.transcriptText ? turn.text : REDACTED,
+    transcripts: policy.retain.transcriptText ? turn.transcripts : turn.transcripts.map((transcript) => ({
+      ...transcript,
+      text: REDACTED
+    }))
+  };
+  if (!policy.retain.assistantText && scrubbed.assistantText !== undefined) {
+    scrubbed.assistantText = REDACTED;
+  }
+  if (!policy.retain.metadata) {
+    delete scrubbed.attachments;
+  }
+  return scrubbed;
+};
+var scrubVoiceTraceForZeroDataRetention = (event, policy) => {
+  if (!isVoiceZeroDataRetentionActive(policy) || policy.retain.traceText) {
+    return event;
+  }
+  const payload = event.payload;
+  if (!payload || typeof payload !== "object")
+    return event;
+  const scrubbedPayload = {};
+  for (const [key, value] of Object.entries(payload)) {
+    scrubbedPayload[key] = typeof value === "string" ? REDACTED : value;
+  }
+  return { ...event, payload: scrubbedPayload };
+};
+var VOICE_ZERO_DATA_RETENTION_REDACTION_MARKER = REDACTED;
 // src/costAccounting.ts
 var DEFAULT_VOICE_PRICE_BOOK = {
   "anthropic:claude-opus-4-5": {
@@ -51867,8 +52041,12 @@ export {
   signVoiceTwilioWebhook,
   signVoicePlivoWebhook,
   shouldRetryCampaignAttempt,
+  shouldRetainVoiceTranscript,
+  shouldRetainVoiceRecording,
   shapeTelephonyAssistantText,
   selectVoiceTraceEventsForPrune,
+  scrubVoiceTurnForZeroDataRetention,
+  scrubVoiceTraceForZeroDataRetention,
   scoreVoiceNoShowRisk,
   saveVoiceIncidentBundleArtifact,
   runVoiceToolContractSuite,
@@ -52070,6 +52248,7 @@ export {
   listVoiceProviderDecisionTraces,
   listVoiceOpsTasks,
   isWithinCampaignWindow,
+  isVoiceZeroDataRetentionActive,
   isVoiceOpsTaskOverdue,
   isPhoneOnDNC,
   interleaveStereoPcm,
@@ -52156,6 +52335,7 @@ export {
   decodeTwilioMulawBase64,
   deadLetterVoiceOpsTask,
   createVoiceZeroRetentionPolicy,
+  createVoiceZeroDataRetentionPolicy,
   createVoiceZendeskTicketUpdateSink,
   createVoiceZendeskTicketSyncSinks,
   createVoiceZendeskTicketSink,
@@ -52389,6 +52569,7 @@ export {
   createVoiceMemoryAuditEventStore,
   createVoiceMemoryAssistantMemoryStore,
   createVoiceMediaPipelineRoutes,
+  createVoiceMCPToolset,
   createVoiceLiveOpsRoutes,
   createVoiceLiveOpsController,
   createVoiceLiveMonitorRoutes,
@@ -52564,6 +52745,7 @@ export {
   collectVoiceDTMFInput,
   collectVoiceCampaignTemplateVariables,
   claimVoiceOpsTask,
+  buildVoiceVariableAnalytics,
   buildVoiceTraceReplay,
   buildVoiceTraceDeliveryReport,
   buildVoiceTelephonyWebhookSecurityReport,
@@ -52713,6 +52895,7 @@ export {
   appendVoiceIOProviderRouterTraceEvent,
   aggregateVoiceTurnLatencySpans,
   acknowledgeVoiceMonitorIssue,
+  VOICE_ZERO_DATA_RETENTION_REDACTION_MARKER,
   VOICE_WEBHOOK_TIMESTAMP_HEADER,
   VOICE_WEBHOOK_SIGNATURE_HEADER,
   VOICE_TCPA_DEFAULT_WINDOW,

package/dist/mcpToolset.d.ts

@@ -0,0 +1,58 @@
+import { type VoiceAgentTool } from "./agent";
+import type { VoiceSessionRecord } from "./types";
+/**
+ * Minimal structural shapes from the Model Context Protocol. Any MCP client
+ * (`@modelcontextprotocol/sdk` over stdio / SSE / streamable-HTTP, or a custom
+ * transport) that exposes `listTools` + `callTool` satisfies this — voice does
+ * not bundle an MCP SDK.
+ */
+export type MCPToolDefinition = {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+};
+export type MCPToolContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export type MCPToolCallResult = {
+    content?: MCPToolContentBlock[];
+    structuredContent?: unknown;
+    isError?: boolean;
+};
+export type MCPClientLike = {
+    listTools: () => Promise<{
+        tools: MCPToolDefinition[];
+    }> | {
+        tools: MCPToolDefinition[];
+    };
+    callTool: (input: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }) => Promise<MCPToolCallResult> | MCPToolCallResult;
+};
+export type VoiceMCPToolResult = {
+    text: string;
+    structuredContent?: unknown;
+    isError: boolean;
+    raw: MCPToolCallResult;
+};
+export type CreateVoiceMCPToolsetOptions = {
+    client: MCPClientLike;
+    /** Prefix applied to every exposed tool name (e.g. "mcp_"). */
+    namePrefix?: string;
+    /** Only expose tools whose (unprefixed) name is in this allow-list. */
+    allowedTools?: ReadonlyArray<string>;
+    /** Drop tools whose (unprefixed) name is in this block-list. */
+    blockedTools?: ReadonlyArray<string>;
+    /** Override how an MCP result is flattened to the assistant-visible string. */
+    resultToMessage?: (result: VoiceMCPToolResult) => string;
+};
+/**
+ * Bridges the tools exposed by an MCP server into `VoiceAgentTool`s. Call once
+ * at setup; the returned array spreads straight into `createVoiceAgent({ tools })`.
+ */
+export declare const createVoiceMCPToolset: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord>(options: CreateVoiceMCPToolsetOptions) => Promise<VoiceAgentTool<TContext, TSession, Record<string, unknown>, VoiceMCPToolResult>[]>;

package/dist/variableAnalytics.d.ts

@@ -0,0 +1,47 @@
+export type VoiceAnalyticsVariableValue = string | number | boolean | null;
+export type VoiceAnalyticsCall = {
+    sessionId: string;
+    variables: Record<string, VoiceAnalyticsVariableValue>;
+    durationSeconds?: number;
+    costUsd?: number;
+    outcome?: string;
+    success?: boolean;
+    at?: number;
+};
+export type VoiceVariableValueStats = {
+    value: string;
+    count: number;
+    share: number;
+    successRate: number | null;
+    avgDurationSeconds: number | null;
+    avgCostUsd: number | null;
+    outcomes: Record<string, number>;
+};
+export type VoiceVariableBreakdown = {
+    variable: string;
+    distinctValues: number;
+    missingCount: number;
+    values: VoiceVariableValueStats[];
+};
+export type VoiceVariableAnalyticsReport = {
+    totalCalls: number;
+    overall: {
+        successRate: number | null;
+        avgDurationSeconds: number | null;
+        avgCostUsd: number | null;
+    };
+    byVariable: Record<string, VoiceVariableBreakdown>;
+};
+export type BuildVoiceVariableAnalyticsInput = {
+    calls: ReadonlyArray<VoiceAnalyticsCall>;
+    /** Variable keys to break analytics down by. */
+    variables: ReadonlyArray<string>;
+    /**
+     * Treat these outcome strings as successes when a call has no explicit
+     * `success` flag. Case-insensitive.
+     */
+    successOutcomes?: ReadonlyArray<string>;
+    /** Cap the values returned per variable (highest count first). */
+    topValuesPerVariable?: number;
+};
+export declare const buildVoiceVariableAnalytics: (input: BuildVoiceVariableAnalyticsInput) => VoiceVariableAnalyticsReport;

package/dist/zeroDataRetention.d.ts

@@ -0,0 +1,41 @@
+import type { VoiceTraceEvent } from "./trace";
+import type { VoiceTurnRecord } from "./types";
+export type VoiceZeroDataRetentionMode = "off" | "strict" | "custom";
+export type VoiceZeroDataRetentionRetainFlags = {
+    /** Persist committed/partial transcript text. */
+    transcriptText: boolean;
+    /** Persist assistant response text. */
+    assistantText: boolean;
+    /** Persist recorded audio artifacts. */
+    recordings: boolean;
+    /** Persist free-text payloads on trace events. */
+    traceText: boolean;
+    /** Persist arbitrary session/turn metadata. */
+    metadata: boolean;
+};
+export type VoiceZeroDataRetentionPolicy = {
+    mode: VoiceZeroDataRetentionMode;
+    retain: VoiceZeroDataRetentionRetainFlags;
+};
+export type CreateVoiceZeroDataRetentionPolicyOptions = {
+    mode?: VoiceZeroDataRetentionMode;
+    /** Per-flag overrides; only meaningful with mode "custom" (or to relax "strict"). */
+    retain?: Partial<VoiceZeroDataRetentionRetainFlags>;
+};
+export declare const createVoiceZeroDataRetentionPolicy: (options?: CreateVoiceZeroDataRetentionPolicyOptions) => VoiceZeroDataRetentionPolicy;
+export declare const isVoiceZeroDataRetentionActive: (policy: VoiceZeroDataRetentionPolicy) => boolean;
+export declare const shouldRetainVoiceRecording: (policy: VoiceZeroDataRetentionPolicy) => boolean;
+export declare const shouldRetainVoiceTranscript: (policy: VoiceZeroDataRetentionPolicy) => boolean;
+/**
+ * Returns a scrubbed copy of a turn record honoring the ZDR policy. Structural
+ * fields (ids, timestamps, transcript count, citation ids) are preserved;
+ * content fields are replaced with a redaction marker or dropped.
+ */
+export declare const scrubVoiceTurnForZeroDataRetention: <TResult = unknown>(turn: VoiceTurnRecord<TResult>, policy: VoiceZeroDataRetentionPolicy) => VoiceTurnRecord<TResult>;
+/**
+ * Returns a scrubbed copy of a trace event honoring the ZDR policy. Drops or
+ * masks free-text payload fields while keeping the event type, ids, and
+ * timestamps so observability/lifecycle accounting still works.
+ */
+export declare const scrubVoiceTraceForZeroDataRetention: (event: VoiceTraceEvent, policy: VoiceZeroDataRetentionPolicy) => VoiceTraceEvent;
+export declare const VOICE_ZERO_DATA_RETENTION_REDACTION_MARKER = "[redacted:zdr]";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.521",
+  "version": "0.0.22-beta.523",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",