@absolutejs/voice 0.0.22-beta.62 → 0.0.22-beta.620

package/dist/core/auditSinks.d.ts

@@ -0,0 +1,151 @@
+import type { S3Client, S3Options } from "bun";
+import type { StoredVoiceAuditEvent, VoiceAuditEventStore, VoiceAuditEventType } from "./audit";
+import type { VoiceIdempotencyStore, VoiceRedisTaskLeaseCoordinator } from "./queue";
+import type { VoiceTraceRedactionConfig } from "./trace";
+export type VoiceAuditSinkDeliveryStatus = "delivered" | "failed" | "skipped";
+export type VoiceAuditSinkDeliveryQueueStatus = VoiceAuditSinkDeliveryStatus | "pending";
+export type VoiceAuditSinkDeliveryResult = {
+    attempts: number;
+    deliveredAt?: number;
+    deliveredTo?: string;
+    error?: string;
+    eventCount: number;
+    responseBody?: unknown;
+    status: VoiceAuditSinkDeliveryStatus;
+};
+export type VoiceAuditSink = {
+    deliver: (input: {
+        events: StoredVoiceAuditEvent[];
+    }) => Promise<VoiceAuditSinkDeliveryResult> | VoiceAuditSinkDeliveryResult;
+    eventTypes?: VoiceAuditEventType[];
+    id: string;
+    kind?: string;
+};
+export type VoiceAuditSinkFanoutResult = {
+    deliveredAt: number;
+    eventCount: number;
+    sinkDeliveries: Record<string, VoiceAuditSinkDeliveryResult>;
+    status: VoiceAuditSinkDeliveryStatus;
+};
+export type VoiceAuditSinkDeliveryRecord = {
+    createdAt: number;
+    deliveredAt?: number;
+    deliveryAttempts?: number;
+    deliveryError?: string;
+    deliveryStatus: VoiceAuditSinkDeliveryQueueStatus;
+    events: StoredVoiceAuditEvent[];
+    id: string;
+    sinkDeliveries?: Record<string, VoiceAuditSinkDeliveryResult>;
+    updatedAt: number;
+};
+export type VoiceAuditSinkDeliveryStore<TDelivery extends VoiceAuditSinkDeliveryRecord = VoiceAuditSinkDeliveryRecord> = {
+    get: (id: string) => Promise<TDelivery | undefined> | TDelivery | undefined;
+    list: () => Promise<TDelivery[]> | TDelivery[];
+    remove: (id: string) => Promise<void> | void;
+    set: (id: string, delivery: TDelivery) => Promise<void> | void;
+};
+export type VoiceAuditHTTPSinkOptions<TBody extends Record<string, unknown> = Record<string, unknown>> = {
+    backoffMs?: number;
+    body?: (input: {
+        events: StoredVoiceAuditEvent[];
+    }) => Promise<TBody> | TBody;
+    eventTypes?: VoiceAuditEventType[];
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    id: string;
+    kind?: string;
+    method?: "POST" | "PUT" | "PATCH";
+    retries?: number;
+    signingSecret?: string;
+    timeoutMs?: number;
+    url: string;
+};
+export type VoiceS3AuditSinkFile = {
+    write: (data: string, options?: BlobPropertyBag) => Promise<number> | number;
+};
+export type VoiceS3AuditSinkClient = Pick<S3Client, "file">;
+export type VoiceAuditS3SinkOptions<TBody extends Record<string, unknown> = Record<string, unknown>> = S3Options & {
+    body?: (input: {
+        events: StoredVoiceAuditEvent[];
+        key: string;
+    }) => Promise<TBody> | TBody;
+    client?: VoiceS3AuditSinkClient;
+    contentType?: string;
+    eventTypes?: VoiceAuditEventType[];
+    id: string;
+    keyPrefix?: string;
+    kind?: string;
+};
+export type VoiceAuditSinkStoreOptions<TEvent extends StoredVoiceAuditEvent = StoredVoiceAuditEvent> = {
+    awaitDelivery?: boolean;
+    deliveryQueue?: VoiceAuditSinkDeliveryStore;
+    onDelivery?: (result: VoiceAuditSinkFanoutResult) => Promise<void> | void;
+    onError?: (error: unknown) => Promise<void> | void;
+    redact?: VoiceTraceRedactionConfig;
+    sinks: VoiceAuditSink[];
+    store: VoiceAuditEventStore<TEvent>;
+};
+export type VoiceAuditSinkDeliveryWorkerOptions<TDelivery extends VoiceAuditSinkDeliveryRecord = VoiceAuditSinkDeliveryRecord> = {
+    deadLetters?: VoiceAuditSinkDeliveryStore<TDelivery>;
+    deliveries: VoiceAuditSinkDeliveryStore<TDelivery>;
+    idempotency?: VoiceIdempotencyStore;
+    idempotencyTtlSeconds?: number;
+    leaseMs?: number;
+    leases: VoiceRedisTaskLeaseCoordinator;
+    maxFailures?: number;
+    onDeadLetter?: (delivery: TDelivery) => Promise<void> | void;
+    redact?: VoiceTraceRedactionConfig;
+    sinks: VoiceAuditSink[];
+    statuses?: VoiceAuditSinkDeliveryQueueStatus[];
+    workerId: string;
+};
+export type VoiceAuditSinkDeliveryWorkerResult = {
+    alreadyProcessed: number;
+    attempted: number;
+    deadLettered: number;
+    delivered: number;
+    failed: number;
+    skipped: number;
+};
+export type VoiceAuditSinkDeliveryWorkerLoopOptions<TDelivery extends VoiceAuditSinkDeliveryRecord = VoiceAuditSinkDeliveryRecord> = {
+    onError?: (error: unknown) => Promise<void> | void;
+    pollIntervalMs?: number;
+    worker: ReturnType<typeof createVoiceAuditSinkDeliveryWorker<TDelivery>>;
+};
+export type VoiceAuditSinkDeliveryWorkerLoop = {
+    isRunning: () => boolean;
+    start: () => void;
+    stop: () => void;
+    tick: () => Promise<VoiceAuditSinkDeliveryWorkerResult>;
+};
+export type VoiceAuditSinkDeliveryQueueSummary = {
+    deadLettered: number;
+    delivered: number;
+    failed: number;
+    pending: number;
+    retryEligible: number;
+    skipped: number;
+    total: number;
+};
+export declare const createVoiceAuditHTTPSink: <TBody extends Record<string, unknown> = Record<string, unknown>>(options: VoiceAuditHTTPSinkOptions<TBody>) => VoiceAuditSink;
+export declare const createVoiceAuditS3Sink: <TBody extends Record<string, unknown> = Record<string, unknown>>(options: VoiceAuditS3SinkOptions<TBody>) => VoiceAuditSink;
+export declare const createVoiceAuditSinkDeliveryId: (events: StoredVoiceAuditEvent[]) => string;
+export declare const createVoiceAuditSinkDeliveryRecord: (input: {
+    createdAt?: number;
+    events: StoredVoiceAuditEvent[];
+    id?: string;
+} & Partial<Omit<VoiceAuditSinkDeliveryRecord, "createdAt" | "events" | "id">>) => VoiceAuditSinkDeliveryRecord;
+export declare const createVoiceAuditSinkStore: <TEvent extends StoredVoiceAuditEvent = StoredVoiceAuditEvent>(options: VoiceAuditSinkStoreOptions<TEvent>) => VoiceAuditEventStore<TEvent>;
+export declare const createVoiceMemoryAuditSinkDeliveryStore: <TDelivery extends VoiceAuditSinkDeliveryRecord = VoiceAuditSinkDeliveryRecord>() => VoiceAuditSinkDeliveryStore<TDelivery>;
+export declare const deliverVoiceAuditEventsToSinks: (input: {
+    events: StoredVoiceAuditEvent[];
+    redact?: VoiceTraceRedactionConfig;
+    sinks: VoiceAuditSink[];
+}) => Promise<VoiceAuditSinkFanoutResult>;
+export declare const createVoiceAuditSinkDeliveryWorker: <TDelivery extends VoiceAuditSinkDeliveryRecord = VoiceAuditSinkDeliveryRecord>(options: VoiceAuditSinkDeliveryWorkerOptions<TDelivery>) => {
+    drain: () => Promise<VoiceAuditSinkDeliveryWorkerResult>;
+};
+export declare const createVoiceAuditSinkDeliveryWorkerLoop: <TDelivery extends VoiceAuditSinkDeliveryRecord = VoiceAuditSinkDeliveryRecord>(options: VoiceAuditSinkDeliveryWorkerLoopOptions<TDelivery>) => VoiceAuditSinkDeliveryWorkerLoop;
+export declare const summarizeVoiceAuditSinkDeliveries: <TDelivery extends VoiceAuditSinkDeliveryRecord = VoiceAuditSinkDeliveryRecord>(deliveries: TDelivery[], input?: {
+    deadLetters?: VoiceAuditSinkDeliveryStore<TDelivery>;
+}) => Promise<VoiceAuditSinkDeliveryQueueSummary> | VoiceAuditSinkDeliveryQueueSummary;

package/dist/core/backchannel.d.ts

@@ -0,0 +1,25 @@
+export type VoiceBackchannelCue = {
+    audioUrl?: string;
+    metadata?: Record<string, unknown>;
+    text?: string;
+};
+export type VoiceBackchannelDriverOptions = {
+    cues?: ReadonlyArray<VoiceBackchannelCue>;
+    cueIntervalMs?: number;
+    cueIndex?: (index: number) => number;
+    minSpeechMs?: number;
+    onCue: (cue: VoiceBackchannelCue) => Promise<void> | void;
+};
+export type VoiceBackchannelConfig = {
+    enabled?: boolean;
+    cues?: ReadonlyArray<string>;
+    minSpeechMs?: number;
+    cueIntervalMs?: number;
+};
+export type VoiceBackchannelDriver = {
+    noteSpeech: (timestampMs?: number) => void;
+    noteSilence: (timestampMs?: number) => void;
+    reset: () => void;
+};
+export declare const isBackchannelUtterance: (text: string, maxWords?: number) => boolean;
+export declare const createVoiceBackchannelDriver: (options: VoiceBackchannelDriverOptions) => VoiceBackchannelDriver;

package/dist/core/bargeInDetector.d.ts

@@ -0,0 +1,51 @@
+import type { AudioFormat } from "./types";
+export type VoiceBargeInInput = {
+    /** The partial transcript that arrived while the assistant was speaking. */
+    partialText: string;
+    /** Word count of `partialText`. */
+    wordCount: number;
+    /** Whether the text matches a known backchannel cue (isBackchannelUtterance). */
+    isBackchannelByText: boolean;
+    /** The user's buffered PCM for this window (oldest→newest), if any. */
+    turnAudio?: ReadonlyArray<Uint8Array>;
+    turnAudioFormat?: AudioFormat;
+};
+export type VoiceBargeInVerdict = {
+    /** true = real interruption → cancel the assistant's TTS. false = keep talking. */
+    shouldCancel: boolean;
+    /** Diagnostic label, surfaced on the barge_in / barge_in_suppressed trace. */
+    reason?: string;
+    /**
+     * The acoustic measurements the decision used, surfaced on the trace for
+     * tuning against real audio. Omitted when no audio was judged.
+     */
+    metrics?: {
+        voicedMs: number;
+        rms: number;
+    };
+};
+export type VoiceBargeInDetector = {
+    evaluate: (input: VoiceBargeInInput) => Promise<VoiceBargeInVerdict> | VoiceBargeInVerdict;
+};
+export type CreateAcousticBargeInDetectorOptions = {
+    /** Voiced speech sustained this long (ms) is a real interruption — cancel. */
+    sustainedMs?: number;
+    /**
+     * Leading words that mark an interruption ("wait", "hold on", "sorry"). A
+     * short utterance starting with one cancels immediately instead of holding.
+     * Extends (does not replace) the defaults.
+     */
+    interruptionCues?: string[];
+};
+/**
+ * A model-free backchannel-vs-barge-in classifier driven by TEXT + PERSISTENCE
+ * (energy was measured to not discriminate on normalized speech):
+ *   - voiced speech past `sustainedMs`  → real interruption (cancel)
+ *   - known backchannel cue, still short → backchannel (keep talking)
+ *   - starts with an interruption cue     → caller took the floor (cancel)
+ *   - otherwise short + ambiguous         → HOLD: keep talking; a continuing
+ *                                           utterance cancels itself once its
+ *                                           voiced duration crosses sustainedMs
+ * Runs in-process on raw arithmetic — no model, no sidecar.
+ */
+export declare const createAcousticBargeInDetector: (options?: CreateAcousticBargeInDetectorOptions) => VoiceBargeInDetector;

package/dist/core/bargeInRoutes.d.ts

@@ -0,0 +1,56 @@
+import { Elysia } from "elysia";
+import type { StoredVoiceTraceEvent, VoiceTraceEventStore } from "./trace";
+import type { VoiceBargeInMonitorSnapshot } from "./types";
+export type VoiceBargeInRoutesOptions = {
+    headers?: HeadersInit;
+    htmlPath?: string;
+    name?: string;
+    path?: string;
+    store: VoiceTraceEventStore;
+    thresholdMs?: number;
+    title?: string;
+};
+export type VoiceBargeInReport = VoiceBargeInMonitorSnapshot & {
+    checkedAt: number;
+    sessions: Array<{
+        averageLatencyMs?: number;
+        failed: number;
+        passed: number;
+        sessionId: string;
+        total: number;
+    }>;
+};
+export declare const createVoiceBargeInRoutes: (options: VoiceBargeInRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+export declare const renderVoiceBargeInHTML: (report: VoiceBargeInReport, options?: {
+    title?: string;
+}) => string;
+export declare const summarizeVoiceBargeIn: (events: StoredVoiceTraceEvent[], options?: {
+    thresholdMs?: number;
+}) => VoiceBargeInReport;

package/dist/core/bookingFlow.d.ts

@@ -0,0 +1,43 @@
+import type { VoiceCalendarAdapter, VoiceCalendarAppointment } from "./calendarAdapter";
+import type { VoiceCalendarSlot } from "./calendarSlots";
+export type VoiceBookingFlowStep = "ask-service" | "ask-date" | "ask-time" | "confirm" | "booking" | "booked" | "failed";
+export type VoiceBookingFlowState = {
+    step: VoiceBookingFlowStep;
+    serviceId?: string;
+    serviceDurationMinutes?: number;
+    attendees?: string[];
+    proposedSlots: VoiceCalendarSlot[];
+    selectedSlot?: VoiceCalendarSlot;
+    appointment?: VoiceCalendarAppointment;
+    error?: string;
+};
+export type VoiceBookingFlowServiceCatalog = {
+    id: string;
+    label: string;
+    durationMinutes: number;
+}[];
+export type CreateVoiceBookingFlowOptions = {
+    adapter: VoiceCalendarAdapter;
+    calendarId: string;
+    services?: VoiceBookingFlowServiceCatalog;
+    defaultDurationMinutes?: number;
+    initialStep?: VoiceBookingFlowStep;
+    maxSlotsPerDay?: number;
+};
+export declare const createVoiceBookingFlow: (options: CreateVoiceBookingFlowOptions) => {
+    chooseService: (serviceId: string) => void;
+    chooseSlot: (slotIndex: number) => void;
+    confirm: (input?: {
+        attendees?: string[];
+        title?: string;
+        notes?: string;
+    }) => Promise<VoiceCalendarAppointment | null>;
+    proposeSlotsForDay: (input: {
+        fromMs: number;
+        toMs: number;
+    }) => Promise<VoiceCalendarSlot[]>;
+    reset: () => void;
+    getState: () => VoiceBookingFlowState;
+    subscribe(listener: (state: VoiceBookingFlowState) => void): () => void;
+};
+export type VoiceBookingFlow = ReturnType<typeof createVoiceBookingFlow>;

package/dist/core/browserCallProfiles.d.ts

@@ -0,0 +1,120 @@
+import { Elysia } from "elysia";
+export type VoiceBrowserCallProfileStatus = "empty" | "fail" | "pass" | "stale" | "warn";
+export type VoiceBrowserCallProfileFrameworkSummary = {
+    messageCount?: number;
+    openSockets?: number;
+    receivedBytes?: number;
+    sentBytes?: number;
+};
+export type VoiceBrowserCallProfileFrameworkEvidence = {
+    error?: string;
+    framework: string;
+    ok?: boolean;
+    summary?: VoiceBrowserCallProfileFrameworkSummary;
+    url?: string;
+};
+export type VoiceBrowserCallProfileSummary = {
+    failedFrameworks: string[];
+    openSockets: number;
+    passedFrameworks: string[];
+    receivedBytes: number;
+    sentBytes: number;
+    totalFrameworks: number;
+    totalMessages: number;
+};
+export type VoiceBrowserCallProfileReportInput = {
+    ageMs?: number;
+    baseUrl?: string;
+    frameworks?: string[];
+    freshUntil?: string;
+    generatedAt?: string;
+    maxAgeMs?: number;
+    now?: Date | number | string;
+    ok?: boolean;
+    outputDir?: string;
+    profileId?: string;
+    results?: VoiceBrowserCallProfileFrameworkEvidence[];
+    runId?: string;
+    source?: string;
+    status?: VoiceBrowserCallProfileStatus;
+    summary?: Partial<VoiceBrowserCallProfileSummary> & VoiceBrowserCallProfileFrameworkSummary;
+};
+export type VoiceBrowserCallProfileReport = {
+    ageMs?: number;
+    baseUrl?: string;
+    frameworks: string[];
+    freshUntil?: string;
+    generatedAt: string;
+    maxAgeMs: number;
+    ok: boolean;
+    outputDir?: string;
+    profileId: string;
+    results: VoiceBrowserCallProfileFrameworkEvidence[];
+    runId?: string;
+    source: string;
+    status: VoiceBrowserCallProfileStatus;
+    summary: VoiceBrowserCallProfileSummary;
+};
+export type VoiceBrowserCallProfileAssertionInput = {
+    maxAgeMs?: number;
+    minMessageCountPerFramework?: number;
+    minOpenSocketsPerFramework?: number;
+    minSentBytesPerFramework?: number;
+    requireAllFrameworksPass?: boolean;
+    requiredFrameworks?: string[];
+};
+export type VoiceBrowserCallProfileAssertionReport = {
+    failedFrameworks: string[];
+    issues: string[];
+    ok: boolean;
+    passedFrameworks: string[];
+    status: VoiceBrowserCallProfileStatus;
+    summary: VoiceBrowserCallProfileSummary;
+};
+export type VoiceBrowserCallProfileRoutesOptions = {
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    jsonPath?: string;
+    markdownPath?: false | string;
+    maxAgeMs?: number;
+    name?: string;
+    source?: (() => Promise<VoiceBrowserCallProfileReport | VoiceBrowserCallProfileReportInput> | VoiceBrowserCallProfileReport | VoiceBrowserCallProfileReportInput) | VoiceBrowserCallProfileReport | VoiceBrowserCallProfileReportInput;
+    title?: string;
+};
+export declare const assertVoiceBrowserCallProfileEvidence: (report: VoiceBrowserCallProfileReport | VoiceBrowserCallProfileReportInput, input?: VoiceBrowserCallProfileAssertionInput) => VoiceBrowserCallProfileAssertionReport;
+export declare const buildVoiceBrowserCallProfileReport: (input?: VoiceBrowserCallProfileReportInput) => VoiceBrowserCallProfileReport;
+export declare const evaluateVoiceBrowserCallProfileEvidence: (report: VoiceBrowserCallProfileReport | VoiceBrowserCallProfileReportInput, input?: VoiceBrowserCallProfileAssertionInput) => VoiceBrowserCallProfileAssertionReport;
+export declare const renderVoiceBrowserCallProfileHTML: (report: VoiceBrowserCallProfileReport | VoiceBrowserCallProfileReportInput, options?: {
+    title?: string;
+}) => string;
+export declare const renderVoiceBrowserCallProfileMarkdown: (report: VoiceBrowserCallProfileReport | VoiceBrowserCallProfileReportInput, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceBrowserCallProfileRoutes: (options?: VoiceBrowserCallProfileRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/core/browserMediaRoutes.d.ts

@@ -0,0 +1,62 @@
+import { Elysia } from "elysia";
+import type { MediaWebRTCStatsReport, MediaWebRTCStreamContinuityReport } from "@absolutejs/media";
+import type { VoiceTraceEventStore } from "./trace";
+export type VoiceBrowserMediaStatus = "empty" | "fail" | "pass" | "warn";
+export type VoiceBrowserMediaSample = {
+    at: number;
+    continuity?: MediaWebRTCStreamContinuityReport;
+    report: MediaWebRTCStatsReport;
+    scenarioId?: string;
+    sessionId: string;
+    traceId?: string;
+};
+export type VoiceBrowserMediaReport = {
+    checkedAt: number;
+    latest?: VoiceBrowserMediaSample;
+    recent: VoiceBrowserMediaSample[];
+    status: VoiceBrowserMediaStatus;
+    stale: boolean;
+    total: number;
+};
+export type VoiceBrowserMediaRoutesOptions = {
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    maxAgeMs?: number;
+    name?: string;
+    path?: string;
+    store: VoiceTraceEventStore;
+    title?: string;
+};
+export declare const createVoiceBrowserMediaRoutes: (options: VoiceBrowserMediaRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+export declare const getLatestVoiceBrowserMediaReport: (options: Pick<VoiceBrowserMediaRoutesOptions, "maxAgeMs" | "store">) => Promise<MediaWebRTCStatsReport | undefined>;
+export declare const renderVoiceBrowserMediaHTML: (report: VoiceBrowserMediaReport, options?: {
+    title?: string;
+}) => string;
+export declare const summarizeVoiceBrowserMedia: (options: Pick<VoiceBrowserMediaRoutesOptions, "maxAgeMs" | "store">) => Promise<VoiceBrowserMediaReport>;

package/dist/core/cachedTTS.d.ts

@@ -0,0 +1,54 @@
+import type { TTSAdapter, TTSAdapterOpenOptions, TTSAudioEvent } from "./types";
+/**
+ * Optional persistent backing store for the cache — an L2 behind the in-memory
+ * LRU. Lets rendered audio survive process restarts/deploys so a fixed prompt
+ * (e.g. a greeting) is synthesized once *ever* per content key, not once per
+ * process. The store is content-addressed by the same `keyFor` key, so a
+ * changed prompt/voice/model naturally lands on a new key and re-renders.
+ *
+ * The store is told `TTSAudioEvent[]` and must return the same on read; how it
+ * serializes the binary `chunk`s (base64 in JSON, bytea, a file, etc.) is up to
+ * the implementation. `get` returns `null`/`undefined` on a miss. Both may be
+ * sync or async; errors should be swallowed by the implementation (a store
+ * failure must never break playback — the wrapper falls back to live render).
+ */
+export type CachedTTSStore = {
+    get: (key: string) => Promise<TTSAudioEvent[] | null | undefined> | TTSAudioEvent[] | null | undefined;
+    set: (key: string, events: TTSAudioEvent[]) => Promise<void> | void;
+};
+export type CachedTTSOptions = {
+    /**
+     * Return a stable cache key for an utterance whose synthesized audio should
+     * be rendered once and replayed verbatim on later calls (typically a
+     * greeting / fixed prompt), or `null`/`undefined` to synthesize it live every
+     * time (dynamic turn replies).
+     *
+     * The key must encode everything that affects the audio — the text, the
+     * voice, the model, and the output format. Because the cache is
+     * content-addressed, editing any of those naturally produces a new key, so a
+     * stale rendering is never replayed: the first call after a change re-renders
+     * (and re-caches) while the old entry is simply orphaned.
+     */
+    keyFor: (text: string, openOptions: TTSAdapterOpenOptions) => string | null | undefined;
+    /** Max distinct utterances to retain in memory (LRU by insertion). Default 32. */
+    maxEntries?: number;
+    /**
+     * Optional persistent L2 store (see {@link CachedTTSStore}). When set, an
+     * in-memory miss consults the store before rendering; a store hit is replayed
+     * and promoted into memory, and a fresh render is written through to it. Omit
+     * for memory-only behaviour (unchanged).
+     */
+    store?: CachedTTSStore;
+};
+/**
+ * Wrap a TTS adapter so selected utterances are synthesized once and replayed
+ * from memory on subsequent `send()`s — eliminating provider latency for fixed
+ * prompts like a call greeting. Utterances are selected (and keyed) by
+ * `options.keyFor`; everything else passes straight through to the inner
+ * adapter, so dynamic replies are unaffected.
+ *
+ * The cache lives for the lifetime of the wrapper (one per adapter), so it is
+ * shared across every session/call the adapter serves. Warm it ahead of the
+ * first call by opening a session and `send()`ing the cacheable text once.
+ */
+export declare const createCachedTTS: (inner: TTSAdapter, options: CachedTTSOptions) => TTSAdapter<TTSAdapterOpenOptions>;

package/dist/core/calendarAdapter.d.ts

@@ -0,0 +1,47 @@
+import type { VoiceCalendarBookedRange, VoiceCalendarBusinessHours, VoiceCalendarSlot } from "./calendarSlots";
+export type VoiceCalendarAppointment = {
+    id: string;
+    calendarId: string;
+    startMs: number;
+    endMs: number;
+    title?: string;
+    attendees?: string[];
+    notes?: string;
+    metadata?: Record<string, string>;
+    createdAt: number;
+    status: "scheduled" | "cancelled" | "completed" | "no-show";
+};
+export type VoiceCalendarAvailabilityQuery = {
+    calendarId: string;
+    fromMs: number;
+    toMs: number;
+    durationMinutes: number;
+    bufferMinutes?: number;
+    granularityMinutes?: number;
+    maxSlots?: number;
+};
+export type VoiceCalendarBookInput = {
+    calendarId: string;
+    startMs: number;
+    endMs: number;
+    title?: string;
+    attendees?: string[];
+    notes?: string;
+    metadata?: Record<string, string>;
+};
+export type VoiceCalendarAdapter = {
+    readonly providerName: string;
+    listAvailability(query: VoiceCalendarAvailabilityQuery): Promise<VoiceCalendarSlot[]>;
+    book(input: VoiceCalendarBookInput): Promise<VoiceCalendarAppointment>;
+    cancel(appointmentId: string): Promise<VoiceCalendarAppointment | null>;
+    get(appointmentId: string): Promise<VoiceCalendarAppointment | null>;
+    reschedule(appointmentId: string, nextStartMs: number, nextEndMs: number): Promise<VoiceCalendarAppointment | null>;
+};
+export type CreateVoiceInMemoryCalendarAdapterOptions = {
+    businessHours: VoiceCalendarBusinessHours[];
+    timezone?: string;
+    bookedRanges?: VoiceCalendarBookedRange[];
+    generateId?: () => string;
+    now?: () => number;
+};
+export declare const createVoiceInMemoryCalendarAdapter: (options: CreateVoiceInMemoryCalendarAdapterOptions) => VoiceCalendarAdapter;

package/dist/core/calendarSlots.d.ts

@@ -0,0 +1,35 @@
+export type VoiceCalendarBusinessHours = {
+    weekday: number;
+    start: string;
+    end: string;
+};
+export type VoiceCalendarBlackout = {
+    date: string;
+    reason?: string;
+};
+export type VoiceCalendarBookedRange = {
+    startMs: number;
+    endMs: number;
+};
+export type VoiceCalendarSlot = {
+    startMs: number;
+    endMs: number;
+    durationMinutes: number;
+};
+export type GenerateVoiceCalendarSlotsInput = {
+    fromMs: number;
+    toMs: number;
+    durationMinutes: number;
+    bufferMinutes?: number;
+    granularityMinutes?: number;
+    timezone?: string;
+    businessHours: VoiceCalendarBusinessHours[];
+    blackoutDates?: VoiceCalendarBlackout[];
+    bookedRanges?: VoiceCalendarBookedRange[];
+    maxSlots?: number;
+};
+export declare const generateVoiceCalendarSlots: (input: GenerateVoiceCalendarSlotsInput) => VoiceCalendarSlot[];
+export declare const summarizeVoiceCalendarSlot: (slot: VoiceCalendarSlot, options?: {
+    timezone?: string;
+    locale?: string;
+}) => string;