@absolutejs/voice 0.0.22-beta.0 → 0.0.22-beta.2

package/dist/trace.d.ts

@@ -0,0 +1,236 @@
+export type VoiceTraceEventType = 'agent.handoff' | 'agent.model' | 'agent.result' | 'agent.tool' | 'call.lifecycle' | 'session.error' | 'turn.assistant' | 'turn.committed' | 'turn.cost' | 'turn.transcript';
+export type VoiceTraceEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = {
+    at: number;
+    id?: string;
+    metadata?: Record<string, unknown>;
+    payload: TPayload;
+    scenarioId?: string;
+    sessionId: string;
+    traceId?: string;
+    turnId?: string;
+    type: VoiceTraceEventType;
+};
+export type StoredVoiceTraceEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = VoiceTraceEvent<TPayload> & {
+    id: string;
+};
+export type VoiceTraceEventFilter = {
+    limit?: number;
+    scenarioId?: string;
+    sessionId?: string;
+    traceId?: string;
+    turnId?: string;
+    type?: VoiceTraceEventType | VoiceTraceEventType[];
+};
+export type VoiceTraceEventStore<TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent> = {
+    append: (event: VoiceTraceEvent | TEvent) => Promise<TEvent>;
+    get: (id: string) => Promise<TEvent | undefined>;
+    list: (filter?: VoiceTraceEventFilter) => Promise<TEvent[]>;
+    remove: (id: string) => Promise<void>;
+};
+export type VoiceTracePruneFilter = Omit<VoiceTraceEventFilter, 'limit'>;
+export type VoiceTracePruneOptions = {
+    before?: number;
+    beforeOrAt?: number;
+    dryRun?: boolean;
+    filter?: VoiceTracePruneFilter;
+    keepNewest?: number;
+    limit?: number;
+    store: VoiceTraceEventStore;
+};
+export type VoiceTracePruneResult = {
+    deleted: StoredVoiceTraceEvent[];
+    deletedCount: number;
+    dryRun: boolean;
+    scannedCount: number;
+};
+export type VoiceTraceSinkDeliveryStatus = 'delivered' | 'failed' | 'skipped';
+export type VoiceTraceSinkDeliveryQueueStatus = VoiceTraceSinkDeliveryStatus | 'pending';
+export type VoiceTraceSinkDeliveryResult = {
+    attempts: number;
+    deliveredAt?: number;
+    deliveredTo?: string;
+    error?: string;
+    eventCount: number;
+    responseBody?: unknown;
+    status: VoiceTraceSinkDeliveryStatus;
+};
+export type VoiceTraceSink = {
+    deliver: (input: {
+        events: StoredVoiceTraceEvent[];
+    }) => Promise<VoiceTraceSinkDeliveryResult> | VoiceTraceSinkDeliveryResult;
+    eventTypes?: VoiceTraceEventType[];
+    id: string;
+    kind?: string;
+};
+export type VoiceTraceSinkFanoutResult = {
+    deliveredAt: number;
+    eventCount: number;
+    sinkDeliveries: Record<string, VoiceTraceSinkDeliveryResult>;
+    status: VoiceTraceSinkDeliveryStatus;
+};
+export type VoiceTraceSinkDeliveryRecord = {
+    createdAt: number;
+    deliveredAt?: number;
+    deliveryAttempts?: number;
+    deliveryError?: string;
+    deliveryStatus: VoiceTraceSinkDeliveryQueueStatus;
+    events: StoredVoiceTraceEvent[];
+    id: string;
+    sinkDeliveries?: Record<string, VoiceTraceSinkDeliveryResult>;
+    updatedAt: number;
+};
+export type VoiceTraceSinkDeliveryStore<TDelivery extends VoiceTraceSinkDeliveryRecord = VoiceTraceSinkDeliveryRecord> = {
+    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 VoiceTraceHTTPSinkOptions<TBody extends Record<string, unknown> = Record<string, unknown>> = {
+    backoffMs?: number;
+    body?: (input: {
+        events: StoredVoiceTraceEvent[];
+    }) => Promise<TBody> | TBody;
+    eventTypes?: VoiceTraceEventType[];
+    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 VoiceTraceSinkStoreOptions<TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent> = {
+    awaitDelivery?: boolean;
+    deliveryQueue?: VoiceTraceSinkDeliveryStore;
+    onDelivery?: (result: VoiceTraceSinkFanoutResult) => Promise<void> | void;
+    onError?: (error: unknown) => Promise<void> | void;
+    redact?: VoiceTraceRedactionConfig;
+    sinks: VoiceTraceSink[];
+    store: VoiceTraceEventStore<TEvent>;
+};
+export type VoiceTraceSummary = {
+    assistantReplyCount: number;
+    callDurationMs?: number;
+    cost: {
+        estimatedRelativeCostUnits: number;
+        totalBillableAudioMs: number;
+    };
+    endedAt?: number;
+    errorCount: number;
+    eventCount: number;
+    failed: boolean;
+    handoffCount: number;
+    modelCallCount: number;
+    sessionId?: string;
+    startedAt?: number;
+    toolCallCount: number;
+    toolErrorCount: number;
+    traceId?: string;
+    transcriptCount: number;
+    turnCount: number;
+};
+export type VoiceTraceIssueSeverity = 'error' | 'warning';
+export type VoiceTraceIssue = {
+    code: string;
+    message: string;
+    severity: VoiceTraceIssueSeverity;
+};
+export type VoiceTraceEvaluationOptions = {
+    maxHandoffs?: number;
+    maxModelCallsPerTurn?: number;
+    maxToolErrors?: number;
+    requireAssistantReply?: boolean;
+    requireCompletedCall?: boolean;
+    requireTranscript?: boolean;
+    requireTurn?: boolean;
+};
+export type VoiceTraceEvaluation = {
+    issues: VoiceTraceIssue[];
+    pass: boolean;
+    summary: VoiceTraceSummary;
+};
+export type VoiceTraceRedactionReplacement = string | ((input: {
+    key?: string;
+    path: string[];
+    value: string;
+}) => string);
+export type VoiceTraceRedactionOptions = {
+    keys?: string[];
+    redactEmails?: boolean;
+    redactPhoneNumbers?: boolean;
+    redactText?: boolean;
+    replacement?: VoiceTraceRedactionReplacement;
+    textKeys?: string[];
+};
+export type VoiceTraceRedactionConfig = boolean | VoiceTraceRedactionOptions;
+export type VoiceResolvedTraceRedactionOptions = Required<Pick<VoiceTraceRedactionOptions, 'redactEmails' | 'redactPhoneNumbers' | 'redactText'>> & {
+    keys: string[];
+    replacement: VoiceTraceRedactionReplacement;
+    textKeys: string[];
+};
+export declare const createVoiceTraceEventId: (event: {
+    at?: number;
+    sessionId: string;
+    turnId?: string;
+    type: VoiceTraceEventType;
+}) => string;
+export declare const createVoiceTraceEvent: <TEvent extends VoiceTraceEvent = VoiceTraceEvent>(event: TEvent) => StoredVoiceTraceEvent<TEvent["payload"]>;
+export declare const createVoiceTraceSinkDeliveryId: (events: StoredVoiceTraceEvent[]) => string;
+export declare const createVoiceTraceSinkDeliveryRecord: (input: {
+    createdAt?: number;
+    events: StoredVoiceTraceEvent[];
+    id?: string;
+} & Partial<Omit<VoiceTraceSinkDeliveryRecord, "createdAt" | "events" | "id">>) => VoiceTraceSinkDeliveryRecord;
+export declare const filterVoiceTraceEvents: <TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent>(events: TEvent[], filter?: VoiceTraceEventFilter) => TEvent[];
+export declare const selectVoiceTraceEventsForPrune: <TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent>(events: TEvent[], options?: Omit<VoiceTracePruneOptions, "store">) => TEvent[];
+export declare const pruneVoiceTraceEvents: (options: VoiceTracePruneOptions) => Promise<VoiceTracePruneResult>;
+export declare const createVoiceTraceHTTPSink: <TBody extends Record<string, unknown> = Record<string, unknown>>(options: VoiceTraceHTTPSinkOptions<TBody>) => VoiceTraceSink;
+export declare const deliverVoiceTraceEventsToSinks: (input: {
+    events: StoredVoiceTraceEvent[];
+    redact?: VoiceTraceRedactionConfig;
+    sinks: VoiceTraceSink[];
+}) => Promise<VoiceTraceSinkFanoutResult>;
+export declare const createVoiceTraceSinkStore: <TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent>(options: VoiceTraceSinkStoreOptions<TEvent>) => VoiceTraceEventStore<TEvent>;
+export declare const createVoiceMemoryTraceSinkDeliveryStore: <TDelivery extends VoiceTraceSinkDeliveryRecord = VoiceTraceSinkDeliveryRecord>() => VoiceTraceSinkDeliveryStore<TDelivery>;
+export declare const createVoiceMemoryTraceEventStore: <TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent>() => VoiceTraceEventStore<TEvent>;
+export declare const exportVoiceTrace: (input: {
+    filter?: VoiceTraceEventFilter;
+    redact?: VoiceTraceRedactionConfig;
+    store: VoiceTraceEventStore;
+}) => Promise<{
+    exportedAt: number;
+    events: StoredVoiceTraceEvent<Record<string, unknown>>[];
+    filter: VoiceTraceEventFilter | undefined;
+    redacted: boolean;
+}>;
+export declare const resolveVoiceTraceRedactionOptions: (options?: VoiceTraceRedactionConfig) => VoiceResolvedTraceRedactionOptions;
+export declare const redactVoiceTraceText: (value: string, options?: VoiceTraceRedactionConfig, input?: {
+    key?: string;
+    path?: string[];
+}) => string;
+export declare const redactVoiceTraceEvent: <TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent>(event: TEvent, options?: VoiceTraceRedactionConfig) => TEvent;
+export declare const redactVoiceTraceEvents: <TEvent extends StoredVoiceTraceEvent = StoredVoiceTraceEvent>(events: TEvent[], options?: VoiceTraceRedactionConfig) => TEvent[];
+export declare const summarizeVoiceTrace: (events: StoredVoiceTraceEvent[]) => VoiceTraceSummary;
+export declare const evaluateVoiceTrace: (events: StoredVoiceTraceEvent[], options?: VoiceTraceEvaluationOptions) => VoiceTraceEvaluation;
+export declare const renderVoiceTraceMarkdown: (events: StoredVoiceTraceEvent[], options?: {
+    title?: string;
+    evaluation?: VoiceTraceEvaluationOptions;
+    redact?: VoiceTraceRedactionConfig;
+}) => string;
+export declare const renderVoiceTraceHTML: (events: StoredVoiceTraceEvent[], options?: {
+    title?: string;
+    evaluation?: VoiceTraceEvaluationOptions;
+    redact?: VoiceTraceRedactionConfig;
+}) => string;
+export declare const buildVoiceTraceReplay: (events: StoredVoiceTraceEvent[], options?: {
+    evaluation?: VoiceTraceEvaluationOptions;
+    redact?: VoiceTraceRedactionConfig;
+    title?: string;
+}) => {
+    evaluation: VoiceTraceEvaluation;
+    html: string;
+    markdown: string;
+    summary: VoiceTraceSummary;
+};

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 import type { SessionStore } from '@absolutejs/absolute';
-import type { StoredVoiceIntegrationEvent, StoredVoiceOpsTask, VoiceIntegrationEventStore, VoiceOpsTask, VoiceOpsTaskStore } from './ops';
+import type { VoiceOpsDispositionTaskPolicies, VoiceOpsTaskAssignmentRule, VoiceOpsTaskAssignmentRules, VoiceIntegrationWebhookConfig, StoredVoiceIntegrationEvent, StoredVoiceOpsTask, VoiceIntegrationEventStore, VoiceOpsTaskPolicy, VoiceOpsTask, VoiceOpsTaskStore } from './ops';
+import type { VoiceIntegrationSink } from './opsSinks';
 import type { StoredVoiceCallReviewArtifact, VoiceCallReviewArtifact, VoiceCallReviewStore } from './testing/review';
+import type { VoiceTraceEventStore } from './trace';
 export type AudioFormat = {
     container: 'raw';
     encoding: 'alaw' | 'mulaw' | 'pcm_s16le';
@@ -499,6 +501,30 @@ export type VoiceRuntimeOpsConfig<TContext = unknown, TSession extends VoiceSess
         review: StoredVoiceCallReviewArtifact;
         session: TSession;
     }) => Promise<Omit<VoiceOpsTask, 'id'> | VoiceOpsTask | StoredVoiceOpsTask | null | void> | Omit<VoiceOpsTask, 'id'> | VoiceOpsTask | StoredVoiceOpsTask | null | void;
+    resolveTaskPolicy?: (input: {
+        api: VoiceSessionHandle<TContext, TSession, TResult>;
+        context: TContext;
+        disposition: VoiceCallDisposition;
+        metadata?: Record<string, unknown>;
+        reason?: string;
+        review?: StoredVoiceCallReviewArtifact;
+        session: TSession;
+        target?: string;
+        task: StoredVoiceOpsTask;
+    }) => Promise<VoiceOpsTaskPolicy | void> | VoiceOpsTaskPolicy | void;
+    resolveTaskAssignment?: (input: {
+        api: VoiceSessionHandle<TContext, TSession, TResult>;
+        context: TContext;
+        disposition: VoiceCallDisposition;
+        metadata?: Record<string, unknown>;
+        reason?: string;
+        review?: StoredVoiceCallReviewArtifact;
+        session: TSession;
+        target?: string;
+        task: StoredVoiceOpsTask;
+    }) => Promise<VoiceOpsTaskAssignmentRule | void> | VoiceOpsTaskAssignmentRule | void;
+    taskAssignmentRules?: VoiceOpsTaskAssignmentRules;
+    taskPolicies?: VoiceOpsDispositionTaskPolicies;
     events?: VoiceIntegrationEventStore;
     onEvent?: (input: {
         api: VoiceSessionHandle<TContext, TSession, TResult>;
@@ -507,7 +533,9 @@ export type VoiceRuntimeOpsConfig<TContext = unknown, TSession extends VoiceSess
         session: TSession;
     }) => Promise<void> | void;
     reviews?: VoiceCallReviewStore;
+    sinks?: VoiceIntegrationSink[];
     tasks?: VoiceOpsTaskStore;
+    webhook?: VoiceIntegrationWebhookConfig;
 };
 export type VoiceNormalizedRouteConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Omit<VoiceRouteConfig<TContext, TSession, TResult>, 'onTurn'> & {
     onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
@@ -540,6 +568,7 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
     logger?: VoiceLogger;
     htmx?: boolean | VoiceHTMXConfig<TSession, NoInfer<TResult>>;
     ops?: VoiceRuntimeOpsConfig<TContext, TSession, TResult>;
+    trace?: VoiceTraceEventStore;
 } & VoiceRouteConfig<TContext, TSession, TResult>;
 export type CreateVoiceSessionOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     costTelemetry?: VoiceCostTelemetryConfig<TContext, TSession, TResult>;
@@ -552,6 +581,7 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     lexicon?: VoiceLexiconEntry[];
     sttFallback?: VoiceResolvedSTTFallbackConfig;
     store: VoiceSessionStore<TSession>;
+    trace?: VoiceTraceEventStore;
     reconnect: Required<VoiceReconnectConfig>;
     phraseHints?: VoicePhraseHint[];
     scenarioId?: string;

package/package.json

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