@absolutejs/voice 0.0.22-beta.5 → 0.0.22-beta.500

package/dist/agent.d.ts

@@ -1,7 +1,21 @@
-import type { VoiceOnTurnObjectHandler, VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord, VoiceTurnRecord } from './types';
-import type { VoiceTraceEventStore } from './trace';
-export type VoiceAgentMessageRole = 'assistant' | 'system' | 'tool' | 'user';
+import type { VoiceOnTurnObjectHandler, VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord, VoiceTurnRecord } from "./types";
+import type { VoiceTraceEventStore } from "./trace";
+import type { VoiceToolRuntime } from "./toolRuntime";
+import { type VoiceAuditEventStore, type VoiceAuditLogger } from "./audit";
+export type VoiceAgentMessageRole = "assistant" | "system" | "tool" | "user";
+export type VoiceAgentImageMediaType = "image/gif" | "image/jpeg" | "image/png" | "image/webp";
+export type VoiceAgentMessageAttachment = {
+    data: string;
+    kind: "image";
+    mediaType: VoiceAgentImageMediaType;
+} | {
+    data: string;
+    kind: "document";
+    mediaType: "application/pdf";
+    name?: string;
+};
 export type VoiceAgentMessage = {
+    attachments?: VoiceAgentMessageAttachment[];
     content: string;
     metadata?: Record<string, unknown>;
     name?: string;
@@ -18,7 +32,7 @@ export type VoiceAgentToolResult<TResult = unknown> = {
     error?: string;
     metadata?: Record<string, unknown>;
     result?: TResult;
-    status: 'error' | 'ok';
+    status: "error" | "ok";
     toolCallId?: string;
     toolName: string;
 };
@@ -59,12 +73,45 @@ export type VoiceAgentModelOutput<TResult = unknown> = VoiceRouteResult<TResult>
 export type VoiceAgentModel<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     generate: (input: VoiceAgentModelInput<TContext, TSession>) => Promise<VoiceAgentModelOutput<TResult>> | VoiceAgentModelOutput<TResult>;
 };
+export type VoiceAgentSquadHandoffStatus = "allowed" | "blocked" | "max-exceeded" | "unknown-target";
+export type VoiceAgentSquadStateHandoff = {
+    at: number;
+    fromAgentId: string;
+    metadata?: Record<string, unknown>;
+    originalTargetAgentId?: string;
+    reason?: string;
+    status: VoiceAgentSquadHandoffStatus;
+    summary?: string;
+    targetAgentId: string;
+    turnId: string;
+};
+export type VoiceAgentSquadState = {
+    agentId: string;
+    handoffCount: number;
+    handoffs: VoiceAgentSquadStateHandoff[];
+    lastHandoff?: VoiceAgentSquadStateHandoff;
+    previousAgentId?: string;
+};
 export type VoiceAgentRunResult<TResult = unknown> = VoiceRouteResult<TResult> & {
     agentId: string;
-    handoff?: VoiceAgentModelOutput<TResult>['handoff'];
+    handoff?: VoiceAgentModelOutput<TResult>["handoff"];
     messages: VoiceAgentMessage[];
+    squad?: VoiceAgentSquadState;
     toolResults: VoiceAgentToolResult[];
 };
+export type VoiceAgentSquadHandoffPolicyResult<TResult = unknown> = {
+    allow?: boolean;
+    escalate?: VoiceRouteResult<TResult>["escalate"];
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    summary?: string;
+    targetAgentId?: string;
+};
+export type VoiceAgentSquadContextPolicyResult = {
+    messages?: VoiceAgentMessage[];
+    metadata?: Record<string, unknown>;
+    system?: string;
+};
 export type VoiceAgent<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     id: string;
     onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
@@ -73,10 +120,14 @@ export type VoiceAgent<TContext = unknown, TSession extends VoiceSessionRecord =
         context: TContext;
         messages?: VoiceAgentMessage[];
         session: TSession;
+        system?: string;
         turn: VoiceTurnRecord;
     }) => Promise<VoiceAgentRunResult<TResult>>;
 };
 export type VoiceAgentOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    audit?: VoiceAuditEventStore | VoiceAuditLogger;
+    auditModel?: string;
+    auditProvider?: string;
     id: string;
     maxToolRounds?: number;
     model: VoiceAgentModel<TContext, TSession, TResult>;
@@ -86,18 +137,41 @@ export type VoiceAgentOptions<TContext = unknown, TSession extends VoiceSessionR
         turn: VoiceTurnRecord;
     }) => Promise<string | undefined> | string | undefined);
     trace?: VoiceTraceEventStore;
+    toolRuntime?: VoiceToolRuntime<TContext, TSession, TResult>;
     tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
 };
 export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    audit?: VoiceAuditEventStore | VoiceAuditLogger;
     agents: Array<VoiceAgent<TContext, TSession, TResult>>;
     defaultAgentId: string;
+    handoffPolicy?: (input: {
+        context: TContext;
+        fromAgentId: string;
+        handoff: NonNullable<VoiceAgentModelOutput<TResult>["handoff"]>;
+        messages: VoiceAgentMessage[];
+        session: TSession;
+        targetAgent?: VoiceAgent<TContext, TSession, TResult>;
+        turn: VoiceTurnRecord;
+    }) => Promise<VoiceAgentSquadHandoffPolicyResult<TResult> | void> | VoiceAgentSquadHandoffPolicyResult<TResult> | void;
+    contextPolicy?: (input: {
+        context: TContext;
+        fromAgentId: string;
+        handoff: VoiceAgentSquadStateHandoff;
+        messages: VoiceAgentMessage[];
+        session: TSession;
+        summaryMessage: VoiceAgentMessage;
+        targetAgent: VoiceAgent<TContext, TSession, TResult>;
+        turn: VoiceTurnRecord;
+    }) => Promise<VoiceAgentSquadContextPolicyResult | void> | VoiceAgentSquadContextPolicyResult | void;
     id: string;
     maxHandoffsPerTurn?: number;
     onHandoff?: (input: {
         context: TContext;
         fromAgentId: string;
+        metadata?: Record<string, unknown>;
         reason?: string;
         session: TSession;
+        summary?: string;
         targetAgentId: string;
         turn: VoiceTurnRecord;
     }) => Promise<void> | void;

package/dist/agentSquadContract.d.ts

@@ -0,0 +1,98 @@
+import type { VoiceAgent, VoiceAgentRunResult, VoiceAgentSquadHandoffStatus } from "./agent";
+import type { VoiceTraceEventStore } from "./trace";
+import type { VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord } from "./types";
+export type VoiceAgentSquadContractOutcome = "assistant" | "complete" | "escalate" | "no-answer" | "transfer" | "voicemail";
+export type VoiceAgentSquadHandoffExpectation = {
+    fromAgentId?: string;
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    reasonIncludes?: string[];
+    status?: VoiceAgentSquadHandoffStatus;
+    summary?: string;
+    summaryIncludes?: string[];
+    targetAgentId?: string;
+};
+export type VoiceAgentSquadTurnExpectation<TResult = unknown> = {
+    assistantIncludes?: string[];
+    finalAgentId?: string;
+    handoffs?: VoiceAgentSquadHandoffExpectation[];
+    outcome?: VoiceAgentSquadContractOutcome;
+    result?: (input: {
+        result: TResult | undefined;
+        routeResult: VoiceRouteResult<TResult>;
+    }) => VoiceAgentSquadContractIssue[];
+    transferTarget?: string;
+};
+export type VoiceAgentSquadContractTurn<TResult = unknown> = {
+    expect?: VoiceAgentSquadTurnExpectation<TResult>;
+    id?: string;
+    text: string;
+};
+export type VoiceAgentSquadContractDefinition<TResult = unknown> = {
+    description?: string;
+    id: string;
+    label?: string;
+    scenarioId?: string;
+    turns: Array<VoiceAgentSquadContractTurn<TResult>>;
+};
+export type VoiceAgentSquadContractIssue = {
+    code: string;
+    message: string;
+    turnId?: string;
+};
+export type VoiceAgentSquadContractTurnReport<TResult = unknown> = {
+    agentId: string;
+    handoffs: VoiceAgentSquadHandoffExpectation[];
+    issues: VoiceAgentSquadContractIssue[];
+    outcome?: VoiceAgentSquadContractOutcome;
+    pass: boolean;
+    result: VoiceAgentRunResult<TResult>;
+    turnId: string;
+};
+export type VoiceAgentSquadContractReport<TResult = unknown> = {
+    contractId: string;
+    issues: VoiceAgentSquadContractIssue[];
+    pass: boolean;
+    scenarioId?: string;
+    sessionId: string;
+    turns: Array<VoiceAgentSquadContractTurnReport<TResult>>;
+};
+export type VoiceAgentSquadContractRunOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    api?: VoiceSessionHandle<TContext, TSession, TResult>;
+    context: TContext;
+    contract: VoiceAgentSquadContractDefinition<TResult>;
+    session?: TSession;
+    squad: VoiceAgent<TContext, TSession, TResult>;
+    trace?: VoiceTraceEventStore;
+};
+export type VoiceAgentSquadContractAssertionInput = {
+    maxBlockedHandoffs?: number;
+    maxFailed?: number;
+    maxIssues?: number;
+    minContracts?: number;
+    minHandoffs?: number;
+    requiredContractIds?: string[];
+    requiredFinalAgentIds?: string[];
+    requiredHandoffStatuses?: VoiceAgentSquadHandoffStatus[];
+    requiredHandoffTargets?: string[];
+    requiredScenarioIds?: string[];
+};
+export type VoiceAgentSquadContractAssertionReport = {
+    blockedHandoffs: number;
+    contractIds: string[];
+    failed: number;
+    finalAgentIds: string[];
+    handoffStatuses: VoiceAgentSquadHandoffStatus[];
+    handoffTargets: string[];
+    handoffs: number;
+    issues: string[];
+    issueCount: number;
+    ok: boolean;
+    passed: number;
+    scenarioIds: string[];
+    total: number;
+};
+export declare const runVoiceAgentSquadContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentSquadContractRunOptions<TContext, TSession, TResult>) => Promise<VoiceAgentSquadContractReport<TResult>>;
+export declare const assertVoiceAgentSquadContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentSquadContractRunOptions<TContext, TSession, TResult>) => Promise<VoiceAgentSquadContractReport<TResult>>;
+export declare const evaluateVoiceAgentSquadContractEvidence: (reports: readonly VoiceAgentSquadContractReport[], input?: VoiceAgentSquadContractAssertionInput) => VoiceAgentSquadContractAssertionReport;
+export declare const assertVoiceAgentSquadContractEvidence: (reports: readonly VoiceAgentSquadContractReport[], input?: VoiceAgentSquadContractAssertionInput) => VoiceAgentSquadContractAssertionReport;

package/dist/agentState.d.ts

@@ -0,0 +1,12 @@
+export type VoiceAgentUIState = "idle" | "listening" | "speaking" | "thinking";
+export type VoiceAgentUIInput = {
+    hasActivePartial: boolean;
+    isConnected: boolean;
+    isPlaying: boolean;
+    isRecording: boolean;
+    lastAssistantAt?: number;
+    lastTranscriptAt?: number;
+};
+export declare const deriveVoiceAgentUIState: (input: VoiceAgentUIInput) => VoiceAgentUIState;
+export declare const describeVoiceAgentUIState: (state: VoiceAgentUIState) => string;
+export declare const voiceAgentUIStateOrder: ReadonlyArray<VoiceAgentUIState>;

package/dist/agentTools.d.ts

@@ -0,0 +1,133 @@
+import { type VoiceAgentTool } from "./agent";
+import type { VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord } from "./types";
+export type VoiceEndCallToolArgs = {
+    reason?: string;
+};
+export type VoiceEndCallToolResult = {
+    farewell?: string;
+    ok: true;
+    reason?: string;
+};
+export type VoiceEndCallToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    description?: string;
+    farewell?: string | ((input: {
+        args: VoiceEndCallToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => string | undefined);
+    name?: string;
+    resolveResult?: (input: {
+        args: VoiceEndCallToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => TResult | undefined;
+};
+export declare const createVoiceEndCallTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: VoiceEndCallToolOptions<TContext, TSession, TResult>) => VoiceAgentTool<TContext, TSession, VoiceEndCallToolArgs, VoiceEndCallToolResult, TResult>;
+export type VoiceTransferCallToolDestination = {
+    description?: string;
+    id: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+    target: string;
+    transferMode?: "cold" | "warm";
+};
+export type VoiceTransferCallToolArgs = {
+    destinationId: string;
+    reason?: string;
+};
+export type VoiceTransferCallToolResult = {
+    destinationId: string;
+    message?: string;
+    ok: true;
+    target: string;
+};
+export type VoiceTransferCallToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    description?: string;
+    destinations: readonly VoiceTransferCallToolDestination[];
+    name?: string;
+    resolveResult?: (input: {
+        args: VoiceTransferCallToolArgs;
+        context: TContext;
+        destination: VoiceTransferCallToolDestination;
+        session: TSession;
+    }) => TResult | undefined;
+};
+export declare const createVoiceTransferCallTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceTransferCallToolOptions<TContext, TSession, TResult>) => VoiceAgentTool<TContext, TSession, VoiceTransferCallToolArgs, VoiceTransferCallToolResult, TResult>;
+export type VoiceDTMFToolArgs = {
+    digits: string;
+};
+export type VoiceDTMFToolResult = {
+    digits: string;
+    ok: true;
+};
+export type VoiceDTMFToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord> = {
+    allowedDigits?: string;
+    description?: string;
+    maxDigits?: number;
+    name?: string;
+    send: (input: {
+        api: VoiceSessionHandle<TContext, TSession>;
+        args: VoiceDTMFToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => Promise<void> | void;
+};
+export declare const createVoiceDTMFTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord>(options: VoiceDTMFToolOptions<TContext, TSession>) => VoiceAgentTool<TContext, TSession, VoiceDTMFToolArgs, VoiceDTMFToolResult>;
+export type VoiceVoicemailDetectionToolArgs = {
+    confidence?: number;
+    reason?: string;
+};
+export type VoiceVoicemailDetectionToolResult = {
+    confidence?: number;
+    ok: true;
+    reason?: string;
+};
+export type VoiceVoicemailDetectionToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    completeAfterMarking?: boolean;
+    description?: string;
+    message?: string;
+    name?: string;
+    resolveResult?: (input: {
+        args: VoiceVoicemailDetectionToolArgs;
+        context: TContext;
+        session: TSession;
+    }) => TResult | undefined;
+};
+export declare const createVoiceVoicemailDetectionTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: VoiceVoicemailDetectionToolOptions<TContext, TSession, TResult>) => VoiceAgentTool<TContext, TSession, VoiceVoicemailDetectionToolArgs, VoiceVoicemailDetectionToolResult, TResult>;
+export type VoiceApiRequestToolHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type VoiceApiRequestToolArgs = Record<string, unknown>;
+export type VoiceApiRequestToolResult<TResponse = unknown> = {
+    body: TResponse;
+    ok: boolean;
+    status: number;
+    url: string;
+};
+export type VoiceApiRequestToolFetch = (request: Request) => Promise<Response> | Response;
+export type VoiceApiRequestToolOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs extends VoiceApiRequestToolArgs = VoiceApiRequestToolArgs, TResponse = unknown> = {
+    buildBody?: (input: {
+        args: TArgs;
+        context: TContext;
+        session: TSession;
+    }) => unknown;
+    buildHeaders?: (input: {
+        args: TArgs;
+        context: TContext;
+        session: TSession;
+    }) => HeadersInit | undefined;
+    buildQuery?: (input: {
+        args: TArgs;
+        context: TContext;
+        session: TSession;
+    }) => Record<string, string | number | undefined> | undefined;
+    description: string;
+    fetch?: VoiceApiRequestToolFetch;
+    formatResult?: (result: VoiceApiRequestToolResult<TResponse>) => string;
+    headers?: HeadersInit;
+    method?: VoiceApiRequestToolHttpMethod;
+    name: string;
+    parameters?: Record<string, unknown>;
+    parseResponse?: (response: Response) => Promise<TResponse> | TResponse;
+    url: string;
+};
+export declare const createVoiceApiRequestTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs extends VoiceApiRequestToolArgs = VoiceApiRequestToolArgs, TResponse = unknown>(options: VoiceApiRequestToolOptions<TContext, TSession, TArgs, TResponse>) => VoiceAgentTool<TContext, TSession, TArgs, VoiceApiRequestToolResult<TResponse>>;
+export type VoiceRouteResultLike = VoiceRouteResult<unknown>;

package/dist/aiVoiceModel.d.ts

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

package/dist/amdDetector.d.ts

@@ -0,0 +1,25 @@
+import type { Transcript, VoiceSessionHandle, VoiceSessionRecord } from "./types";
+export type VoiceAMDDetectorInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    api: VoiceSessionHandle<TContext, TSession, TResult>;
+    audioLevel: number | undefined;
+    elapsedSinceFirstAudioMs: number;
+    elapsedSinceLastTurnCommitMs: number;
+    partialTranscript: string;
+    session: TSession;
+    transcripts: Transcript[];
+};
+export type VoiceAMDVerdict = {
+    metadata?: Record<string, unknown>;
+    reason?: string;
+};
+export type VoiceAMDDetector<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    evaluate: (input: VoiceAMDDetectorInput<TContext, TSession, TResult>) => Promise<VoiceAMDVerdict | undefined> | VoiceAMDVerdict | undefined;
+    intervalMs?: number;
+};
+export type MonologueAMDDetectorOptions = {
+    intervalMs?: number;
+    minMonologueMs?: number;
+    reason?: string;
+    requireFirstAudio?: boolean;
+};
+export declare const createMonologueAMDDetector: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: MonologueAMDDetectorOptions) => VoiceAMDDetector<TContext, TSession, TResult>;

package/dist/angular/index.d.ts

@@ -1,2 +1,26 @@
-export { VoiceStreamService } from './voice-stream.service';
-export { VoiceControllerService } from './voice-controller.service';
+export { VoiceOpsStatusService } from "./voice-ops-status.service";
+export { VoiceWidgetService } from "./voice-widget.service";
+export type { CreateVoiceWidgetServiceOptions } from "./voice-widget.service";
+export { VoicePlatformCoverageService } from "./voice-platform-coverage.service";
+export { VoiceProofTrendsService } from "./voice-proof-trends.service";
+export { VoiceReconnectProfileEvidenceService } from "./voice-reconnect-profile-evidence.service";
+export { VoiceCallDebuggerService } from "./voice-call-debugger.service";
+export { VoiceSessionSnapshotService } from "./voice-session-snapshot.service";
+export { VoiceSessionObservabilityService } from "./voice-session-observability.service";
+export { VoiceProfileComparisonService } from "./voice-profile-comparison.service";
+export { VoiceReadinessFailuresService } from "./voice-readiness-failures.service";
+export { VoiceOpsActionCenterService } from "./voice-ops-action-center.service";
+export { VoiceLiveOpsService } from "./voice-live-ops.service";
+export { VoiceDeliveryRuntimeService } from "./voice-delivery-runtime.service";
+export { VoiceCampaignDialerProofService } from "./voice-campaign-dialer-proof.service";
+export { VoiceStreamService } from "./voice-stream.service";
+export { VoiceControllerService } from "./voice-controller.service";
+export { VoiceProviderCapabilitiesService } from "./voice-provider-capabilities.service";
+export { VoiceProviderContractsService } from "./voice-provider-contracts.service";
+export { VoiceProviderStatusService } from "./voice-provider-status.service";
+export { VoiceRoutingStatusService } from "./voice-routing-status.service";
+export { VoiceTraceTimelineService } from "./voice-trace-timeline.service";
+export { VoiceAgentSquadStatusService } from "./voice-agent-squad-status.service";
+export { VoiceTurnLatencyService } from "./voice-turn-latency.service";
+export { VoiceTurnQualityService } from "./voice-turn-quality.service";
+export { VoiceWorkflowStatusService } from "./voice-workflow-status.service";