@absolutejs/voice 0.0.22-beta.475 → 0.0.22-beta.477

package/dist/aiVoiceModel.d.ts

@@ -0,0 +1,10 @@
+import type { AIProviderConfig } from "@absolutejs/ai";
+import type { VoiceAgentModel } from "./agent";
+import type { VoiceSessionRecord } from "./types";
+export type CreateAIVoiceModelOptions = {
+    model: string;
+    provider: AIProviderConfig;
+    signal?: AbortSignal;
+    systemPrompt?: string;
+};
+export declare const createAIVoiceModel: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: CreateAIVoiceModelOptions) => VoiceAgentModel<TContext, TSession, TResult>;

package/dist/fileStore.d.ts

@@ -7,6 +7,7 @@ import { type StoredVoiceTraceEvent, type VoiceTraceSinkDeliveryRecord, type Voi
 import type { StoredVoiceIntegrationEvent, StoredVoiceExternalObjectMap, StoredVoiceOpsTask, VoiceExternalObjectMap, VoiceExternalObjectMapStore, VoiceIntegrationEvent, VoiceIntegrationEventStore, VoiceOpsTask, VoiceOpsTaskStore } from "./ops";
 import type { StoredVoiceCallReviewArtifact, VoiceCallReviewArtifact, VoiceCallReviewStore } from "./testing/review";
 import type { VoiceSessionRecord, VoiceSessionStore } from "./types";
+import type { VoiceRecordingStore } from "./recordingStore";
 export type VoiceFileStoreOptions = {
     directory: string;
     pretty?: boolean;
@@ -50,3 +51,4 @@ export declare const createStoredVoiceIntegrationEvent: <TEvent extends Omit<Voi
 export declare const createStoredVoiceExternalObjectMap: <TMapping extends Omit<VoiceExternalObjectMap, "id" | "createdAt" | "updatedAt"> = Omit<VoiceExternalObjectMap, "id" | "createdAt" | "updatedAt">>(mapping: TMapping & {
     at?: number;
 }) => VoiceExternalObjectMap;
+export declare const createVoiceFileRecordingStore: (options: VoiceFileStoreOptions) => VoiceRecordingStore;

package/dist/index.d.ts

@@ -69,6 +69,8 @@ export { assertVoiceSimulationSuiteEvidence, createVoiceSimulationSuiteRoutes, e
 export { createVoiceWorkflowContract, createVoiceWorkflowContractHandler, createVoiceWorkflowContractPreset, createVoiceWorkflowScenario, recordVoiceWorkflowContractTrace, validateVoiceWorkflowRouteResult, } from "./workflowContract";
 export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, createVoiceSessionReplayJSONHandler, createVoiceSessionReplayRoutes, createVoiceSessionsHTMLHandler, createVoiceSessionsJSONHandler, renderVoiceSessionsHTML, summarizeVoiceProviderFallbackRecovery, summarizeVoiceSessions, summarizeVoiceSessionReplay, } from "./sessionReplay";
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool, } from "./agent";
+export { createAIVoiceModel } from "./aiVoiceModel";
+export type { CreateAIVoiceModelOptions } from "./aiVoiceModel";
 export { createVoiceRAGTool } from "./ragTool";
 export type { VoiceRAGCollectionLike, VoiceRAGQueryResult, VoiceRAGSearchInput, VoiceRAGToolArgs, VoiceRAGToolOptions, VoiceRAGToolResult, } from "./ragTool";
 export { createVoiceApiRequestTool, createVoiceDTMFTool, createVoiceEndCallTool, createVoiceTransferCallTool, createVoiceVoicemailDetectionTool, } from "./agentTools";
@@ -85,7 +87,9 @@ export { createVoiceTurnQualityHTMLHandler, createVoiceTurnQualityJSONHandler, c
 export { assertVoiceOutcomeContractEvidence, createVoiceOutcomeContractHTMLHandler, createVoiceOutcomeContractJSONHandler, createVoiceOutcomeContractRoutes, evaluateVoiceOutcomeContractEvidence, renderVoiceOutcomeContractHTML, runVoiceOutcomeContractSuite, } from "./outcomeContract";
 export { applyVoiceTelephonyOutcome, assertVoiceTelephonyWebhookNormalizationEvidence, createMemoryVoiceTelephonyWebhookIdempotencyStore, createVoiceTelephonyOutcomePolicy, createVoiceTelephonyWebhookHandler, createVoiceTelephonyWebhookRoutes, evaluateVoiceTelephonyWebhookNormalizationEvidence, parseVoiceTelephonyWebhookEvent, resolveVoiceTelephonyOutcome, signVoiceTwilioWebhook, verifyVoiceTwilioWebhookSignature, voiceTelephonyOutcomeToRouteResult, } from "./telephonyOutcome";
 export { assertVoicePhoneCallControlEvidence, assertVoicePhoneAssistantEvidence, createVoicePhoneAgent, evaluateVoicePhoneCallControlEvidence, evaluateVoicePhoneAssistantEvidence, } from "./phoneAgent";
-export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileIncidentBundleStore, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileAuditEventStore, createVoiceFileAuditSinkDeliveryStore, createVoiceFileCampaignStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore, } from "./fileStore";
+export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileIncidentBundleStore, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileAuditEventStore, createVoiceFileAuditSinkDeliveryStore, createVoiceFileCampaignStore, createVoiceFileIntegrationEventStore, createVoiceFileRecordingStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore, } from "./fileStore";
+export { computePcmDurationMs, createVoiceMemoryRecordingStore, encodePcmAsWav, } from "./recordingStore";
+export type { StoredVoiceRecordingArtifact, VoiceRecordingArtifact, VoiceRecordingChannel, VoiceRecordingStore, } from "./recordingStore";
 export { createVoiceAssistantMemoryHandle, createVoiceAssistantMemoryRecord, createVoiceMemoryAssistantMemoryStore, resolveVoiceAssistantMemoryNamespace, } from "./assistantMemory";
 export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, createVoiceProviderOrchestrationProfile, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter, } from "./modelAdapters";
 export { createOpenAIVoiceTTS } from "./openaiTTS";

package/dist/index.js

@@ -3369,6 +3369,77 @@ var buildTurnText = (transcripts, partialText, options = {}) => {
   return selectPreferredTranscriptText(finalText, nextPartial);
 };
 
+// src/types.ts
+var ttsAdapterSessionCanCancel = (session) => typeof session.cancel === "function";
+
+// src/recordingStore.ts
+var writeUint32LE = (view, offset, value) => {
+  view.setUint32(offset, value, true);
+};
+var writeUint16LE = (view, offset, value) => {
+  view.setUint16(offset, value, true);
+};
+var writeAscii = (view, offset, value) => {
+  for (let index = 0;index < value.length; index += 1) {
+    view.setUint8(offset + index, value.charCodeAt(index));
+  }
+};
+var encodePcmAsWav = (pcm, format) => {
+  if (format.container !== "raw" || format.encoding !== "pcm_s16le") {
+    throw new Error(`encodePcmAsWav only supports raw pcm_s16le input (got container=${format.container}, encoding=${format.encoding})`);
+  }
+  const channels = format.channels;
+  const sampleRate = format.sampleRateHz;
+  const bitsPerSample = 16;
+  const byteRate = sampleRate * channels * bitsPerSample / 8;
+  const blockAlign = channels * bitsPerSample / 8;
+  const dataSize = pcm.byteLength;
+  const buffer = new ArrayBuffer(44 + dataSize);
+  const view = new DataView(buffer);
+  writeAscii(view, 0, "RIFF");
+  writeUint32LE(view, 4, 36 + dataSize);
+  writeAscii(view, 8, "WAVE");
+  writeAscii(view, 12, "fmt ");
+  writeUint32LE(view, 16, 16);
+  writeUint16LE(view, 20, 1);
+  writeUint16LE(view, 22, channels);
+  writeUint32LE(view, 24, sampleRate);
+  writeUint32LE(view, 28, byteRate);
+  writeUint16LE(view, 32, blockAlign);
+  writeUint16LE(view, 34, bitsPerSample);
+  writeAscii(view, 36, "data");
+  writeUint32LE(view, 40, dataSize);
+  const output = new Uint8Array(buffer);
+  output.set(pcm, 44);
+  return output;
+};
+var computePcmDurationMs = (pcmByteLength, format) => {
+  if (format.container !== "raw" || format.encoding !== "pcm_s16le") {
+    return 0;
+  }
+  const bytesPerSecond = format.sampleRateHz * format.channels * 2;
+  if (bytesPerSecond === 0) {
+    return 0;
+  }
+  return Math.round(pcmByteLength / bytesPerSecond * 1000);
+};
+var createVoiceMemoryRecordingStore = () => {
+  const records = new Map;
+  const key = (sessionId, channel) => `${sessionId}::${channel}`;
+  return {
+    get: async (sessionId, channel) => records.get(key(sessionId, channel)),
+    list: async (sessionId) => Array.from(records.values()).filter((record) => record.sessionId === sessionId),
+    put: async (artifact) => {
+      const stored = {
+        ...artifact,
+        recordingUrl: `memory://recording/${artifact.sessionId}/${artifact.channel}.wav`
+      };
+      records.set(key(artifact.sessionId, artifact.channel), stored);
+      return stored;
+    }
+  };
+};
+
 // src/session.ts
 var DEFAULT_RECONNECT_TIMEOUT = 30000;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 10;
@@ -3611,6 +3682,39 @@ var createVoiceSession = (options) => {
   const currentTurnAudio = [];
   let fallbackAttemptsForCurrentTurn = 0;
   let fallbackReplayAudioMsForCurrentTurn = 0;
+  const recordingConfig = options.recording;
+  const recordingChannels = new Set(recordingConfig?.channels ?? ["assistant", "user"]);
+  const recordingMaxBytes = recordingConfig?.maxBytesPerChannel ?? 50 * 1024 * 1024;
+  const recordingBuffers = {
+    assistant: [],
+    user: []
+  };
+  const recordingByteTotals = {
+    assistant: 0,
+    user: 0
+  };
+  const recordingFormats = {};
+  let recordingPersisted = false;
+  const captureRecordingChunk = (channel, bytes, format) => {
+    if (!recordingConfig || recordingPersisted) {
+      return;
+    }
+    if (!recordingChannels.has(channel)) {
+      return;
+    }
+    if (format.container !== "raw" || format.encoding !== "pcm_s16le") {
+      return;
+    }
+    const currentTotal = recordingByteTotals[channel];
+    if (currentTotal >= recordingMaxBytes) {
+      return;
+    }
+    const remaining = recordingMaxBytes - currentTotal;
+    const slice = bytes.byteLength <= remaining ? bytes : bytes.subarray(0, remaining);
+    recordingBuffers[channel].push(new Uint8Array(slice));
+    recordingByteTotals[channel] += slice.byteLength;
+    recordingFormats[channel] = format;
+  };
   const pruneTurnAudio = () => {
     const replayWindowMs = sttFallback?.replayWindowMs ?? DEFAULT_FALLBACK_REPLAY_MS;
     const cutoffAt = Date.now() - replayWindowMs;
@@ -3789,8 +3893,83 @@ var createVoiceSession = (options) => {
       });
     }
   };
+  const persistRecordings = async () => {
+    if (!recordingConfig || recordingPersisted) {
+      return;
+    }
+    recordingPersisted = true;
+    const channels = ["assistant", "user"];
+    for (const channel of channels) {
+      if (!recordingChannels.has(channel)) {
+        continue;
+      }
+      const chunks = recordingBuffers[channel];
+      const format = recordingFormats[channel];
+      if (chunks.length === 0 || !format) {
+        continue;
+      }
+      const totalBytes = recordingByteTotals[channel];
+      const merged = new Uint8Array(totalBytes);
+      let offset = 0;
+      for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      try {
+        const stored = await recordingConfig.store.put({
+          audioBytes: merged,
+          capturedAt: Date.now(),
+          channel,
+          durationMs: computePcmDurationMs(totalBytes, format),
+          format,
+          sessionId: options.id
+        });
+        await appendTrace({
+          payload: {
+            channel,
+            durationMs: stored.durationMs,
+            recordingUrl: stored.recordingUrl,
+            sessionId: options.id,
+            sizeBytes: merged.byteLength
+          },
+          type: "recording.ready"
+        });
+      } catch (error) {
+        logger.warn("voice recording persist failed", {
+          channel,
+          error: toError(error).message,
+          sessionId: options.id
+        });
+      } finally {
+        recordingBuffers[channel] = [];
+        recordingByteTotals[channel] = 0;
+      }
+    }
+  };
+  const cancelActiveTTS = async (reason) => {
+    const activeSession = ttsSession;
+    const cancelledTurnId = activeTTSTurnId;
+    if (!activeSession || cancelledTurnId === undefined) {
+      return;
+    }
+    activeTTSTurnId = undefined;
+    if (!ttsAdapterSessionCanCancel(activeSession)) {
+      return;
+    }
+    try {
+      await activeSession.cancel(reason);
+    } catch (error) {
+      logger.warn("voice tts adapter cancel failed", {
+        error: toError(error).message,
+        reason,
+        sessionId: options.id,
+        turnId: cancelledTurnId
+      });
+    }
+  };
   const sendAssistantAudio = async (chunk, input) => {
     const normalizedChunk = chunk instanceof Uint8Array ? new Uint8Array(chunk) : chunk instanceof ArrayBuffer ? new Uint8Array(chunk.slice(0)) : new Uint8Array(chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength));
+    captureRecordingChunk("assistant", normalizedChunk, input.format);
     await send({
       chunkBase64: encodeBase64(normalizedChunk),
       format: input.format,
@@ -3887,6 +4066,7 @@ var createVoiceSession = (options) => {
     });
     await closeTTSSession("failed");
     await closeAdapter("failed");
+    await persistRecordings();
     speechDetected = false;
     rewindFallbackTurnAudio();
     await options.route.onError?.({
@@ -3955,6 +4135,7 @@ var createVoiceSession = (options) => {
     });
     await closeTTSSession("complete");
     await closeAdapter("complete");
+    await persistRecordings();
     speechDetected = false;
     rewindFallbackTurnAudio();
     if (disposition === "transferred" && input.target) {
@@ -5096,7 +5277,14 @@ var createVoiceSession = (options) => {
     if (shouldStoreAudio) {
       pushTurnAudio(conditionedAudio);
     }
+    if (recordingConfig?.userInputFormat) {
+      const userBytes = conditionedAudio instanceof Uint8Array ? conditionedAudio : conditionedAudio instanceof ArrayBuffer ? new Uint8Array(conditionedAudio) : new Uint8Array(conditionedAudio.buffer, conditionedAudio.byteOffset, conditionedAudio.byteLength);
+      captureRecordingChunk("user", userBytes, recordingConfig.userInputFormat);
+    }
     if (audioLevel >= turnDetection.speechThreshold) {
+      if (!speechDetected && activeTTSTurnId !== undefined) {
+        cancelActiveTTS("barge-in");
+      }
       speechDetected = true;
       clearSilenceTimer();
     } else if (speechDetected) {
@@ -5129,6 +5317,7 @@ var createVoiceSession = (options) => {
         clearSilenceTimer();
         await closeTTSSession(reason);
         await closeAdapter(reason);
+        await persistRecordings();
         await Promise.resolve(socket.close(1000, reason));
         if (session.call?.endedAt && session.call.disposition === "closed") {
           await appendTrace({
@@ -34559,6 +34748,76 @@ var createVoiceWorkflowContractHandler = (input) => {
     return result;
   };
 };
+// src/aiVoiceModel.ts
+var toProviderMessages = (messages) => {
+  const out = [];
+  for (const message of messages) {
+    if (message.role === "tool") {
+      out.push({
+        content: [
+          {
+            content: message.content,
+            tool_use_id: message.toolCallId ?? message.name ?? "",
+            type: "tool_result"
+          }
+        ],
+        role: "user"
+      });
+      continue;
+    }
+    if (message.role === "system") {
+      out.push({ content: message.content, role: "user" });
+      continue;
+    }
+    out.push({ content: message.content, role: message.role });
+  }
+  return out;
+};
+var toProviderTools = (tools) => {
+  if (tools.length === 0) {
+    return;
+  }
+  return tools.map((tool) => ({
+    description: tool.description ?? "",
+    input_schema: tool.parameters ?? {
+      properties: {},
+      type: "object"
+    },
+    name: tool.name
+  }));
+};
+var createAIVoiceModel = (options) => ({
+  generate: async (input) => {
+    const systemPrompt = input.system ?? options.systemPrompt;
+    const stream = options.provider.stream({
+      messages: toProviderMessages(input.messages),
+      model: options.model,
+      signal: options.signal,
+      systemPrompt,
+      tools: toProviderTools(input.tools)
+    });
+    let assistantText = "";
+    const toolCalls = [];
+    for await (const chunk of stream) {
+      if (chunk.type === "text") {
+        assistantText += chunk.content;
+      } else if (chunk.type === "tool_use") {
+        toolCalls.push({
+          args: chunk.input ?? {},
+          id: chunk.id,
+          name: chunk.name
+        });
+      }
+    }
+    const output = {
+      assistantText
+    };
+    if (toolCalls.length > 0) {
+      output.toolCalls = toolCalls;
+    }
+    return output;
+  }
+});
 // src/ragTool.ts
 var DEFAULT_TOOL_NAME = "searchKnowledgeBase";
 var DEFAULT_DESCRIPTION = "Search the knowledge base and return short grounded citations. Use this whenever the caller asks a question that may be answered by indexed reference material.";
@@ -37004,6 +37263,66 @@ var createStoredVoiceExternalObjectMap = (mapping) => createVoiceExternalObjectM
   sourceId: mapping.sourceId,
   sourceType: mapping.sourceType
 });
+var recordingFileName = (sessionId, channel) => `${encodeURIComponent(sessionId)}_${channel}.wav`;
+var recordingMetadataFileName = (sessionId, channel) => `${encodeURIComponent(sessionId)}_${channel}.json`;
+var createVoiceFileRecordingStore = (options) => {
+  const ensureDir = async () => {
+    await mkdir4(options.directory, { recursive: true });
+  };
+  const put = async (artifact) => {
+    await ensureDir();
+    const wavPath = join3(options.directory, recordingFileName(artifact.sessionId, artifact.channel));
+    const metadataPath = join3(options.directory, recordingMetadataFileName(artifact.sessionId, artifact.channel));
+    const wav = encodePcmAsWav(artifact.audioBytes, artifact.format);
+    await writeFile(wavPath, wav);
+    const recordingUrl = `file://${wavPath}`;
+    const metadata = {
+      capturedAt: artifact.capturedAt,
+      channel: artifact.channel,
+      durationMs: artifact.durationMs,
+      format: artifact.format,
+      recordingUrl,
+      sessionId: artifact.sessionId
+    };
+    await writeFile(metadataPath, options.pretty ? JSON.stringify(metadata, null, 2) : JSON.stringify(metadata));
+    return {
+      ...artifact,
+      recordingUrl
+    };
+  };
+  const readMetadata = async (sessionId, channel) => {
+    const metadataPath = join3(options.directory, recordingMetadataFileName(sessionId, channel));
+    const wavPath = join3(options.directory, recordingFileName(sessionId, channel));
+    try {
+      const [metaText, wavBytes] = await Promise.all([
+        readFile2(metadataPath, "utf8"),
+        readFile2(wavPath)
+      ]);
+      const meta = JSON.parse(metaText);
+      return {
+        audioBytes: new Uint8Array(wavBytes.buffer, wavBytes.byteOffset, wavBytes.byteLength),
+        capturedAt: meta.capturedAt,
+        channel: meta.channel,
+        durationMs: meta.durationMs,
+        format: meta.format,
+        recordingUrl: meta.recordingUrl,
+        sessionId: meta.sessionId
+      };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+  };
+  const get = (sessionId, channel) => readMetadata(sessionId, channel);
+  const list = async (sessionId) => {
+    const channels = ["assistant", "user"];
+    const records = await Promise.all(channels.map((channel) => readMetadata(sessionId, channel)));
+    return records.filter((record) => record !== undefined);
+  };
+  return { get, list, put };
+};
 // src/modelAdapters.ts
 var isVoiceProviderRoutingPolicyPreset = (value) => value === "balanced" || value === "cost-cap" || value === "cost-first" || value === "latency-first" || value === "quality-first";
 var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
@@ -44991,6 +45310,7 @@ export {
   verifyVoiceOpsWebhookSignature,
   validateVoiceWorkflowRouteResult,
   validateVoiceObservabilityExportRecord,
+  ttsAdapterSessionCanCancel,
   transcodeTwilioInboundPayloadToPCM16,
   transcodePCMToTwilioOutboundPayload,
   summarizeVoiceTurnQuality,
@@ -45263,6 +45583,7 @@ export {
   evaluateVoiceBrowserCallProfileEvidence,
   evaluateVoiceAgentSquadContractEvidence,
   encodeTwilioMulawBase64,
+  encodePcmAsWav,
   deliverVoiceTraceEventsToSinks,
   deliverVoiceObservabilityExport,
   deliverVoiceMonitorIssueNotifications,
@@ -45476,6 +45797,7 @@ export {
   createVoiceMemoryTraceSinkDeliveryStore,
   createVoiceMemoryTraceEventStore,
   createVoiceMemoryStore,
+  createVoiceMemoryRecordingStore,
   createVoiceMemoryObservabilityExportDeliveryReceiptStore,
   createVoiceMemoryMonitorNotifierDeliveryReceiptStore,
   createVoiceMemoryMonitorIssueStore,
@@ -45522,6 +45844,7 @@ export {
   createVoiceFileScenarioFixtureStore,
   createVoiceFileRuntimeStorage,
   createVoiceFileReviewStore,
+  createVoiceFileRecordingStore,
   createVoiceFileObservabilityExportDeliveryReceiptStore,
   createVoiceFileIntegrationEventStore,
   createVoiceFileIncidentBundleStore,
@@ -45614,7 +45937,9 @@ export {
   createDomainPhraseHints,
   createDomainLexicon,
   createAnthropicVoiceAssistantModel,
+  createAIVoiceModel,
   conditionAudioChunk,
+  computePcmDurationMs,
   completeVoiceOpsTask,
   compareVoiceEvalBaseline,
   claimVoiceOpsTask,

package/dist/recordingStore.d.ts

@@ -0,0 +1,21 @@
+import type { AudioFormat } from "./types";
+export type VoiceRecordingChannel = "assistant" | "user";
+export type VoiceRecordingArtifact = {
+    audioBytes: Uint8Array;
+    capturedAt: number;
+    channel: VoiceRecordingChannel;
+    durationMs: number;
+    format: AudioFormat;
+    sessionId: string;
+};
+export type StoredVoiceRecordingArtifact = VoiceRecordingArtifact & {
+    recordingUrl?: string;
+};
+export type VoiceRecordingStore = {
+    get: (sessionId: string, channel: VoiceRecordingChannel) => Promise<StoredVoiceRecordingArtifact | undefined>;
+    list: (sessionId: string) => Promise<StoredVoiceRecordingArtifact[]>;
+    put: (artifact: VoiceRecordingArtifact) => Promise<StoredVoiceRecordingArtifact>;
+};
+export declare const encodePcmAsWav: (pcm: Uint8Array, format: AudioFormat) => Uint8Array;
+export declare const computePcmDurationMs: (pcmByteLength: number, format: AudioFormat) => number;
+export declare const createVoiceMemoryRecordingStore: () => VoiceRecordingStore;

package/dist/testing/index.js

@@ -5337,6 +5337,77 @@ var resolveLogger = (logger) => ({
   ...logger
 });
 
+// src/types.ts
+var ttsAdapterSessionCanCancel = (session) => typeof session.cancel === "function";
+
+// src/recordingStore.ts
+var writeUint32LE = (view, offset, value) => {
+  view.setUint32(offset, value, true);
+};
+var writeUint16LE = (view, offset, value) => {
+  view.setUint16(offset, value, true);
+};
+var writeAscii = (view, offset, value) => {
+  for (let index = 0;index < value.length; index += 1) {
+    view.setUint8(offset + index, value.charCodeAt(index));
+  }
+};
+var encodePcmAsWav = (pcm, format) => {
+  if (format.container !== "raw" || format.encoding !== "pcm_s16le") {
+    throw new Error(`encodePcmAsWav only supports raw pcm_s16le input (got container=${format.container}, encoding=${format.encoding})`);
+  }
+  const channels = format.channels;
+  const sampleRate = format.sampleRateHz;
+  const bitsPerSample = 16;
+  const byteRate = sampleRate * channels * bitsPerSample / 8;
+  const blockAlign = channels * bitsPerSample / 8;
+  const dataSize = pcm.byteLength;
+  const buffer = new ArrayBuffer(44 + dataSize);
+  const view = new DataView(buffer);
+  writeAscii(view, 0, "RIFF");
+  writeUint32LE(view, 4, 36 + dataSize);
+  writeAscii(view, 8, "WAVE");
+  writeAscii(view, 12, "fmt ");
+  writeUint32LE(view, 16, 16);
+  writeUint16LE(view, 20, 1);
+  writeUint16LE(view, 22, channels);
+  writeUint32LE(view, 24, sampleRate);
+  writeUint32LE(view, 28, byteRate);
+  writeUint16LE(view, 32, blockAlign);
+  writeUint16LE(view, 34, bitsPerSample);
+  writeAscii(view, 36, "data");
+  writeUint32LE(view, 40, dataSize);
+  const output = new Uint8Array(buffer);
+  output.set(pcm, 44);
+  return output;
+};
+var computePcmDurationMs = (pcmByteLength, format) => {
+  if (format.container !== "raw" || format.encoding !== "pcm_s16le") {
+    return 0;
+  }
+  const bytesPerSecond = format.sampleRateHz * format.channels * 2;
+  if (bytesPerSecond === 0) {
+    return 0;
+  }
+  return Math.round(pcmByteLength / bytesPerSecond * 1000);
+};
+var createVoiceMemoryRecordingStore = () => {
+  const records = new Map;
+  const key = (sessionId, channel) => `${sessionId}::${channel}`;
+  return {
+    get: async (sessionId, channel) => records.get(key(sessionId, channel)),
+    list: async (sessionId) => Array.from(records.values()).filter((record) => record.sessionId === sessionId),
+    put: async (artifact) => {
+      const stored = {
+        ...artifact,
+        recordingUrl: `memory://recording/${artifact.sessionId}/${artifact.channel}.wav`
+      };
+      records.set(key(artifact.sessionId, artifact.channel), stored);
+      return stored;
+    }
+  };
+};
+
 // src/session.ts
 var DEFAULT_RECONNECT_TIMEOUT = 30000;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS2 = 10;
@@ -5579,6 +5650,39 @@ var createVoiceSession = (options) => {
   const currentTurnAudio = [];
   let fallbackAttemptsForCurrentTurn = 0;
   let fallbackReplayAudioMsForCurrentTurn = 0;
+  const recordingConfig = options.recording;
+  const recordingChannels = new Set(recordingConfig?.channels ?? ["assistant", "user"]);
+  const recordingMaxBytes = recordingConfig?.maxBytesPerChannel ?? 50 * 1024 * 1024;
+  const recordingBuffers = {
+    assistant: [],
+    user: []
+  };
+  const recordingByteTotals = {
+    assistant: 0,
+    user: 0
+  };
+  const recordingFormats = {};
+  let recordingPersisted = false;
+  const captureRecordingChunk = (channel, bytes, format) => {
+    if (!recordingConfig || recordingPersisted) {
+      return;
+    }
+    if (!recordingChannels.has(channel)) {
+      return;
+    }
+    if (format.container !== "raw" || format.encoding !== "pcm_s16le") {
+      return;
+    }
+    const currentTotal = recordingByteTotals[channel];
+    if (currentTotal >= recordingMaxBytes) {
+      return;
+    }
+    const remaining = recordingMaxBytes - currentTotal;
+    const slice = bytes.byteLength <= remaining ? bytes : bytes.subarray(0, remaining);
+    recordingBuffers[channel].push(new Uint8Array(slice));
+    recordingByteTotals[channel] += slice.byteLength;
+    recordingFormats[channel] = format;
+  };
   const pruneTurnAudio = () => {
     const replayWindowMs = sttFallback?.replayWindowMs ?? DEFAULT_FALLBACK_REPLAY_MS;
     const cutoffAt = Date.now() - replayWindowMs;
@@ -5757,8 +5861,83 @@ var createVoiceSession = (options) => {
       });
     }
   };
+  const persistRecordings = async () => {
+    if (!recordingConfig || recordingPersisted) {
+      return;
+    }
+    recordingPersisted = true;
+    const channels = ["assistant", "user"];
+    for (const channel of channels) {
+      if (!recordingChannels.has(channel)) {
+        continue;
+      }
+      const chunks = recordingBuffers[channel];
+      const format = recordingFormats[channel];
+      if (chunks.length === 0 || !format) {
+        continue;
+      }
+      const totalBytes = recordingByteTotals[channel];
+      const merged = new Uint8Array(totalBytes);
+      let offset = 0;
+      for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      try {
+        const stored = await recordingConfig.store.put({
+          audioBytes: merged,
+          capturedAt: Date.now(),
+          channel,
+          durationMs: computePcmDurationMs(totalBytes, format),
+          format,
+          sessionId: options.id
+        });
+        await appendTrace({
+          payload: {
+            channel,
+            durationMs: stored.durationMs,
+            recordingUrl: stored.recordingUrl,
+            sessionId: options.id,
+            sizeBytes: merged.byteLength
+          },
+          type: "recording.ready"
+        });
+      } catch (error) {
+        logger.warn("voice recording persist failed", {
+          channel,
+          error: toError(error).message,
+          sessionId: options.id
+        });
+      } finally {
+        recordingBuffers[channel] = [];
+        recordingByteTotals[channel] = 0;
+      }
+    }
+  };
+  const cancelActiveTTS = async (reason) => {
+    const activeSession = ttsSession;
+    const cancelledTurnId = activeTTSTurnId;
+    if (!activeSession || cancelledTurnId === undefined) {
+      return;
+    }
+    activeTTSTurnId = undefined;
+    if (!ttsAdapterSessionCanCancel(activeSession)) {
+      return;
+    }
+    try {
+      await activeSession.cancel(reason);
+    } catch (error) {
+      logger.warn("voice tts adapter cancel failed", {
+        error: toError(error).message,
+        reason,
+        sessionId: options.id,
+        turnId: cancelledTurnId
+      });
+    }
+  };
   const sendAssistantAudio = async (chunk, input) => {
     const normalizedChunk = chunk instanceof Uint8Array ? new Uint8Array(chunk) : chunk instanceof ArrayBuffer ? new Uint8Array(chunk.slice(0)) : new Uint8Array(chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength));
+    captureRecordingChunk("assistant", normalizedChunk, input.format);
     await send({
       chunkBase64: encodeBase64(normalizedChunk),
       format: input.format,
@@ -5855,6 +6034,7 @@ var createVoiceSession = (options) => {
     });
     await closeTTSSession("failed");
     await closeAdapter("failed");
+    await persistRecordings();
     speechDetected = false;
     rewindFallbackTurnAudio();
     await options.route.onError?.({
@@ -5923,6 +6103,7 @@ var createVoiceSession = (options) => {
     });
     await closeTTSSession("complete");
     await closeAdapter("complete");
+    await persistRecordings();
     speechDetected = false;
     rewindFallbackTurnAudio();
     if (disposition === "transferred" && input.target) {
@@ -7064,7 +7245,14 @@ var createVoiceSession = (options) => {
     if (shouldStoreAudio) {
       pushTurnAudio(conditionedAudio);
     }
+    if (recordingConfig?.userInputFormat) {
+      const userBytes = conditionedAudio instanceof Uint8Array ? conditionedAudio : conditionedAudio instanceof ArrayBuffer ? new Uint8Array(conditionedAudio) : new Uint8Array(conditionedAudio.buffer, conditionedAudio.byteOffset, conditionedAudio.byteLength);
+      captureRecordingChunk("user", userBytes, recordingConfig.userInputFormat);
+    }
     if (audioLevel >= turnDetection.speechThreshold) {
+      if (!speechDetected && activeTTSTurnId !== undefined) {
+        cancelActiveTTS("barge-in");
+      }
       speechDetected = true;
       clearSilenceTimer();
     } else if (speechDetected) {
@@ -7097,6 +7285,7 @@ var createVoiceSession = (options) => {
         clearSilenceTimer();
         await closeTTSSession(reason);
         await closeAdapter(reason);
+        await persistRecordings();
         await Promise.resolve(socket.close(1000, reason));
         if (session.call?.endedAt && session.call.disposition === "closed") {
           await appendTrace({
@@ -13154,8 +13343,9 @@ var runTTSAdapterFixture = async (adapter, fixture, options = {}) => {
     sessionId: `tts-benchmark:${fixture.id}`,
     ...openOptions ?? {}
   });
+  const sessionOn = session.on;
   const unsubscribers = [
-    session.on("audio", ({ chunk, format, receivedAt }) => {
+    sessionOn("audio", ({ chunk, format, receivedAt }) => {
       const normalizedChunk = chunk instanceof Uint8Array ? chunk : chunk instanceof ArrayBuffer ? new Uint8Array(chunk) : new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
       audioChunkCount += 1;
       totalAudioBytes += normalizedChunk.byteLength;
@@ -13175,10 +13365,10 @@ var runTTSAdapterFixture = async (adapter, fixture, options = {}) => {
         }, options.interruptAfterFirstAudioMs);
       }
     }),
-    session.on("error", () => {
+    sessionOn("error", () => {
       errorCount += 1;
     }),
-    session.on("close", () => {
+    sessionOn("close", () => {
       closeCount += 1;
       closed = true;
       closedAt = Date.now();

package/dist/trace.d.ts

@@ -1,5 +1,5 @@
 import type { S3Client, S3Options } from "bun";
-export type VoiceTraceEventType = "assistant.guardrail" | "assistant.memory" | "assistant.run" | "agent.context" | "agent.handoff" | "agent.model" | "agent.result" | "agent.tool" | "call.handoff" | "call.lifecycle" | "client.barge_in" | "client.browser_media" | "client.live_latency" | "client.reconnect" | "client.telephony_media" | "operator.action" | "provider.decision" | "session.error" | "turn.assistant" | "turn.committed" | "turn.cost" | "turn_latency.stage" | "turn.transcript" | "workflow.contract";
+export type VoiceTraceEventType = "assistant.guardrail" | "assistant.memory" | "assistant.run" | "agent.context" | "agent.handoff" | "agent.model" | "agent.result" | "agent.tool" | "call.handoff" | "call.lifecycle" | "client.barge_in" | "client.browser_media" | "client.live_latency" | "client.reconnect" | "client.telephony_media" | "operator.action" | "provider.decision" | "recording.ready" | "session.error" | "turn.assistant" | "turn.committed" | "turn.cost" | "turn_latency.stage" | "turn.transcript" | "workflow.contract";
 export type VoiceTraceEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = {
     at: number;
     id?: string;

package/dist/types.d.ts

@@ -166,8 +166,12 @@ export type TTSSessionEventMap = {
 export type TTSAdapterSession = {
     on: <K extends keyof TTSSessionEventMap>(event: K, handler: (payload: TTSSessionEventMap[K]) => void | Promise<void>) => () => void;
     send: (text: string) => Promise<void>;
+    cancel?: (reason?: string) => Promise<void>;
     close: (reason?: string) => Promise<void>;
 };
+export declare const ttsAdapterSessionCanCancel: (session: TTSAdapterSession) => session is TTSAdapterSession & {
+    cancel: (reason?: string) => Promise<void>;
+};
 export type TTSAdapterOpenOptions = {
     sessionId: string;
     lexicon?: VoiceLexiconEntry[];
@@ -697,6 +701,12 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
     profileSwitchGuard?: VoicePluginProfileSwitchGuardConfig<TContext, TSession, TResult>;
     trace?: VoiceTraceEventStore;
 } & VoiceRouteConfig<TContext, TSession, TResult>;
+export type VoiceSessionRecordingConfig = {
+    channels?: ReadonlyArray<"assistant" | "user">;
+    maxBytesPerChannel?: number;
+    store: import("./recordingStore").VoiceRecordingStore;
+    userInputFormat?: AudioFormat;
+};
 export type CreateVoiceSessionOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     costTelemetry?: VoiceCostTelemetryConfig<TContext, TSession, TResult>;
     id: string;
@@ -711,6 +721,7 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     sttFallback?: VoiceResolvedSTTFallbackConfig;
     store: VoiceSessionStore<TSession>;
     trace?: VoiceTraceEventStore;
+    recording?: VoiceSessionRecordingConfig;
     reconnect: Required<VoiceReconnectConfig>;
     phraseHints?: VoicePhraseHint[];
     sessionMetadata?: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.475",
+  "version": "0.0.22-beta.477",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",
@@ -160,7 +160,7 @@
     "bench:stt": "bun run ./scripts/benchmark-stt.ts all",
     "bench:assemblyai:sessions": "bun run ./scripts/benchmark-session.ts assemblyai",
     "bench:openai:sessions": "bun run ./scripts/benchmark-session.ts openai",
-    "build": "bun run ./scripts/build-htmx-bootstrap-asset.ts && rm -rf dist && bun build ./src/index.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts ./src/testing/index.ts --outdir dist --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute --external @absolutejs/media && bun build ./src/client/htmxBootstrap.ts --outdir dist/client --target browser --format esm && tsc --emitDeclarationOnly --project tsconfig.json",
+    "build": "bun run ./scripts/build-htmx-bootstrap-asset.ts && rm -rf dist && bun build ./src/index.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts ./src/testing/index.ts --outdir dist --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute --external @absolutejs/ai --external @absolutejs/media && bun build ./src/client/htmxBootstrap.ts --outdir dist/client --target browser --format esm && tsc --emitDeclarationOnly --project tsconfig.json",
     "format": "prettier --write \"./**/*.{js,jsx,ts,tsx,json,md}\"",
     "lint": "eslint ./src",
     "release": "bun run format && bun run build && bun publish",
@@ -229,12 +229,16 @@
   },
   "peerDependencies": {
     "@absolutejs/absolute": ">=0.19.0-beta.646",
+    "@absolutejs/ai": ">=0.0.5",
     "@angular/core": ">=21.0.0",
     "elysia": ">=1.4.18",
     "react": ">=19.0.0",
     "vue": ">=3.5.0"
   },
   "peerDependenciesMeta": {
+    "@absolutejs/ai": {
+      "optional": true
+    },
     "@angular/core": {
       "optional": true
     },
@@ -250,6 +254,7 @@
   },
   "devDependencies": {
     "@absolutejs/absolute": "0.19.0-beta.646",
+    "@absolutejs/ai": "0.0.5",
     "@angular/core": "^21.0.0",
     "@types/bun": "1.3.9",
     "@types/react": "19.2.0",