@absolutejs/voice 0.0.22-beta.67 → 0.0.22-beta.670

package/dist/client/turnQuality.d.ts

@@ -1,7 +1,9 @@
-import type { VoiceTurnQualityReport } from '../turnQuality';
+import type { VoiceTurnQualityReport } from "../core/turnQuality";
+import { type VoiceReactiveSource } from "./reactiveSource";
 export type VoiceTurnQualityClientOptions = {
     fetch?: typeof fetch;
     intervalMs?: number;
+    reactiveSource?: VoiceReactiveSource;
 };
 export type VoiceTurnQualitySnapshot = {
     error: string | null;
@@ -9,11 +11,11 @@ export type VoiceTurnQualitySnapshot = {
     report?: VoiceTurnQualityReport;
     updatedAt?: number;
 };
-export declare const fetchVoiceTurnQuality: (path?: string, options?: Pick<VoiceTurnQualityClientOptions, "fetch">) => Promise<VoiceTurnQualityReport>;
 export declare const createVoiceTurnQualityStore: (path?: string, options?: VoiceTurnQualityClientOptions) => {
     close: () => void;
+    refresh: () => Promise<VoiceTurnQualityReport | undefined>;
     getServerSnapshot: () => VoiceTurnQualitySnapshot;
     getSnapshot: () => VoiceTurnQualitySnapshot;
-    refresh: () => Promise<VoiceTurnQualityReport | undefined>;
     subscribe: (listener: () => void) => () => void;
 };
+export declare const fetchVoiceTurnQuality: (path?: string, options?: Pick<VoiceTurnQualityClientOptions, "fetch">) => Promise<VoiceTurnQualityReport>;

package/dist/client/turnQualityWidget.d.ts

@@ -1,5 +1,5 @@
-import type { VoiceTurnQualityItem } from '../turnQuality';
-import { type VoiceTurnQualityClientOptions, type VoiceTurnQualitySnapshot } from './turnQuality';
+import type { VoiceTurnQualityItem } from "../core/turnQuality";
+import { type VoiceTurnQualityClientOptions, type VoiceTurnQualitySnapshot } from "./turnQuality";
 export type VoiceTurnQualityCardView = VoiceTurnQualityItem & {
     detail: string;
     label: string;
@@ -13,7 +13,7 @@ export type VoiceTurnQualityViewModel = {
     error: string | null;
     isLoading: boolean;
     label: string;
-    status: 'empty' | 'error' | 'loading' | 'ready' | 'warning';
+    status: "empty" | "error" | "loading" | "ready" | "warning";
     title: string;
     turns: VoiceTurnQualityCardView[];
     updatedAt?: number;
@@ -23,10 +23,10 @@ export type VoiceTurnQualityWidgetOptions = VoiceTurnQualityClientOptions & {
     title?: string;
 };
 export declare const createVoiceTurnQualityViewModel: (snapshot: VoiceTurnQualitySnapshot, options?: VoiceTurnQualityWidgetOptions) => VoiceTurnQualityViewModel;
-export declare const renderVoiceTurnQualityHTML: (snapshot: VoiceTurnQualitySnapshot, options?: VoiceTurnQualityWidgetOptions) => string;
+export declare const defineVoiceTurnQualityElement: (tagName?: string) => void;
 export declare const getVoiceTurnQualityCSS: () => string;
 export declare const mountVoiceTurnQuality: (element: Element, path?: string, options?: VoiceTurnQualityWidgetOptions) => {
-    close: () => void;
     refresh: () => Promise<import("..").VoiceTurnQualityReport | undefined>;
+    close: () => void;
 };
-export declare const defineVoiceTurnQualityElement: (tagName?: string) => void;
+export declare const renderVoiceTurnQualityHTML: (snapshot: VoiceTurnQualitySnapshot, options?: VoiceTurnQualityWidgetOptions) => string;

package/dist/client/voiceWidgetView.d.ts

@@ -0,0 +1,48 @@
+import type { VoiceAgentUIState } from "../core/agentState";
+import type { VoiceControllerState } from "../core/types";
+export type VoiceWidgetTheme = {
+    accent?: string;
+    background?: string;
+    errorAccent?: string;
+    fontFamily?: string;
+    foreground?: string;
+    radius?: number | string;
+};
+export type VoiceWidgetLabels = {
+    callEnded?: string;
+    connecting?: string;
+    endCall?: string;
+    idle?: string;
+    listening?: string;
+    mute?: string;
+    speaking?: string;
+    startCall?: string;
+    thinking?: string;
+    unmute?: string;
+};
+export type VoiceWidgetViewModelInput = {
+    labels?: VoiceWidgetLabels;
+    state: Pick<VoiceControllerState, "assistantAudio" | "error" | "isConnected" | "isRecording" | "partial" | "status" | "turns">;
+    theme?: VoiceWidgetTheme;
+    title?: string;
+};
+export type VoiceWidgetViewModel = {
+    agentState: VoiceAgentUIState;
+    classes: {
+        container: string;
+        dot: string;
+    };
+    controls: {
+        canEnd: boolean;
+        canMute: boolean;
+        canStart: boolean;
+    };
+    errorMessage?: string;
+    labels: Required<VoiceWidgetLabels>;
+    partial?: string;
+    statusLabel: string;
+    theme: Required<VoiceWidgetTheme>;
+    title: string;
+};
+export declare const createVoiceWidgetViewModel: (input: VoiceWidgetViewModelInput) => VoiceWidgetViewModel;
+export declare const renderVoiceWidgetHTML: (model: VoiceWidgetViewModel) => string;

package/dist/client/workflowStatus.d.ts

@@ -1,7 +1,9 @@
-import type { VoiceScenarioEvalReport } from '../evalRoutes';
+import type { VoiceScenarioEvalReport } from "../core/evalRoutes";
+import { type VoiceReactiveSource } from "./reactiveSource";
 export type VoiceWorkflowStatusClientOptions = {
     fetch?: typeof fetch;
     intervalMs?: number;
+    reactiveSource?: VoiceReactiveSource;
 };
 export type VoiceWorkflowStatusSnapshot = {
     error: string | null;
@@ -9,11 +11,11 @@ export type VoiceWorkflowStatusSnapshot = {
     report?: VoiceScenarioEvalReport;
     updatedAt?: number;
 };
-export declare const fetchVoiceWorkflowStatus: (path?: string, options?: Pick<VoiceWorkflowStatusClientOptions, "fetch">) => Promise<VoiceScenarioEvalReport>;
 export declare const createVoiceWorkflowStatusStore: (path?: string, options?: VoiceWorkflowStatusClientOptions) => {
     close: () => void;
+    refresh: () => Promise<VoiceScenarioEvalReport | undefined>;
     getServerSnapshot: () => VoiceWorkflowStatusSnapshot;
     getSnapshot: () => VoiceWorkflowStatusSnapshot;
-    refresh: () => Promise<VoiceScenarioEvalReport | undefined>;
     subscribe: (listener: () => void) => () => void;
 };
+export declare const fetchVoiceWorkflowStatus: (path?: string, options?: Pick<VoiceWorkflowStatusClientOptions, "fetch">) => Promise<VoiceScenarioEvalReport>;

package/dist/core/agent.d.ts

@@ -0,0 +1,251 @@
+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";
+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;
+    role: VoiceAgentMessageRole;
+    toolCallId?: string;
+};
+export type VoiceAgentToolCall<TArgs = Record<string, unknown>> = {
+    args: TArgs;
+    id?: string;
+    name: string;
+};
+export type VoiceAgentToolResult<TResult = unknown> = {
+    content?: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+    result?: TResult;
+    status: "error" | "ok";
+    toolCallId?: string;
+    toolName: string;
+};
+export type VoiceAgentToolPolicyDecision = {
+    allowed: boolean;
+    reason?: string;
+};
+export type VoiceAgentToolPolicy<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = (input: {
+    api: VoiceSessionHandle<TContext, TSession, TResult>;
+    assistantText?: string;
+    context: TContext;
+    messages: ReadonlyArray<VoiceAgentMessage>;
+    round: number;
+    session: TSession;
+    toolCall: VoiceAgentToolCall;
+    turn: VoiceTurnRecord;
+}) => Promise<VoiceAgentToolPolicyDecision> | VoiceAgentToolPolicyDecision;
+export type VoiceAgentTool<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
+    description?: string;
+    execute: (input: {
+        api: VoiceSessionHandle<TContext, TSession, TRouteResult>;
+        args: TArgs;
+        context: TContext;
+        session: TSession;
+        turn: VoiceTurnRecord;
+    }) => Promise<TToolResult> | TToolResult;
+    name: string;
+    parameters?: Record<string, unknown>;
+    /** Authorize a model-requested side effect before `execute` runs. Unlike
+     *  post-turn guardrails, this policy sees the assistant text produced in the
+     *  same model round and can prevent an unsafe tool from mutating call state.
+     *  A blocked terminal tool still ends the conversational turn so the already
+     *  streamed reply is not followed by a second model response. */
+    policy?: (input: {
+        api: VoiceSessionHandle<TContext, TSession, TRouteResult>;
+        args: TArgs;
+        assistantText?: string;
+        context: TContext;
+        messages: ReadonlyArray<VoiceAgentMessage>;
+        round: number;
+        session: TSession;
+        toolCall: VoiceAgentToolCall<TArgs>;
+        turn: VoiceTurnRecord;
+    }) => Promise<VoiceAgentToolPolicyDecision> | VoiceAgentToolPolicyDecision;
+    resultToMessage?: (result: TToolResult) => string;
+    /** End the turn after this tool runs — do NOT loop back to the model for
+     *  another generation. Use for tools that wrap up the call (an app-defined
+     *  end_call) where the closing line is already in the SAME response: without
+     *  this the agent generates again off the tool result and the caller hears a
+     *  SECOND closing. Built-in lifecycle tools (complete/transfer/…) are already
+     *  terminal; this flag gives an app tool the same behavior. Default false. */
+    endsTurn?: boolean;
+};
+export type VoiceAgentModelInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord> = {
+    agentId: string;
+    context: TContext;
+    messages: VoiceAgentMessage[];
+    onTextDelta?: (delta: string) => void;
+    session: TSession;
+    system?: string;
+    signal?: AbortSignal;
+    tools: Array<{
+        description?: string;
+        name: string;
+        parameters?: Record<string, unknown>;
+    }>;
+    turn: VoiceTurnRecord;
+};
+export type VoiceAgentModelOutput<TResult = unknown> = VoiceRouteResult<TResult> & {
+    handoff?: {
+        metadata?: Record<string, unknown>;
+        reason?: string;
+        targetAgentId: string;
+    };
+    toolCalls?: VoiceAgentToolCall[];
+};
+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"];
+    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>;
+    run: (input: {
+        api: VoiceSessionHandle<TContext, TSession, TResult>;
+        context: TContext;
+        messages?: VoiceAgentMessage[];
+        onTextDelta?: (delta: string) => void;
+        session: TSession;
+        system?: string;
+        turn: VoiceTurnRecord;
+    }) => Promise<VoiceAgentRunResult<TResult>>;
+    /**
+     * Speculative, side-effect-free generation for eager replies (P3). Runs a
+     * SINGLE model round and returns the text the model would say — but executes
+     * NOTHING: no tools, no streaming to TTS, no traces, no commit. Returns null
+     * if the model wants any tool (the real turn must run so tools fire exactly
+     * once) or on any error. Optional — agents that don't implement it simply
+     * can't be speculated against. Honors no abort itself; the caller discards
+     * the result if the user resumes.
+     */
+    runSpeculative?: (input: {
+        api: VoiceSessionHandle<TContext, TSession, TResult>;
+        context: TContext;
+        messages?: VoiceAgentMessage[];
+        session: TSession;
+        system?: string;
+        turn: VoiceTurnRecord;
+        signal?: AbortSignal;
+    }) => Promise<{
+        text: string;
+    } | null>;
+};
+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>;
+    system?: string | ((input: {
+        context: TContext;
+        session: TSession;
+        turn: VoiceTurnRecord;
+    }) => Promise<string | undefined> | string | undefined);
+    trace?: VoiceTraceEventStore;
+    /** Authorize every model-requested tool before dispatch, including built-in
+     *  lifecycle tools such as `complete` and `transfer_call`. */
+    toolPolicy?: VoiceAgentToolPolicy<TContext, TSession, TResult>;
+    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;
+    trace?: VoiceTraceEventStore;
+    selectAgent?: (input: {
+        context: TContext;
+        session: TSession;
+        turn: VoiceTurnRecord;
+    }) => Promise<string | undefined> | string | undefined;
+};
+export declare const createVoiceAgent: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentOptions<TContext, TSession, TResult>) => VoiceAgent<TContext, TSession, TResult>;
+export declare const createVoiceAgentSquad: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentSquadOptions<TContext, TSession, TResult>) => VoiceAgent<TContext, TSession, TResult>;
+export declare const createVoiceAgentTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown>(tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>) => VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+export {};

package/dist/core/agentPerformanceReport.d.ts

@@ -0,0 +1,40 @@
+import type { VoiceScorecard } from "./callScorecard";
+export type VoiceAgentPerformanceBucket = "day" | "week" | "month";
+export type VoiceAgentPerformanceCriterionSummary = {
+    criterionId: string;
+    averageScore: number;
+    passRate: number;
+    trend: "up" | "down" | "flat";
+    delta: number;
+};
+export type VoiceAgentPerformanceBucketSummary = {
+    bucketKey: string;
+    callsScored: number;
+    averageWeightedScore: number;
+    passRate: number;
+    needsReviewRate: number;
+    failRate: number;
+};
+export type VoiceAgentPerformanceReport = {
+    agentId: string;
+    rubricId: string;
+    fromMs: number;
+    toMs: number;
+    bucket: VoiceAgentPerformanceBucket;
+    totalCalls: number;
+    buckets: VoiceAgentPerformanceBucketSummary[];
+    criteria: VoiceAgentPerformanceCriterionSummary[];
+    overallPassRate: number;
+    overallAverageScore: number;
+    worstCriterion: string | null;
+    bestCriterion: string | null;
+};
+export type BuildVoiceAgentPerformanceReportInput = {
+    agentId: string;
+    rubricId: string;
+    scorecards: VoiceScorecard[];
+    fromMs?: number;
+    toMs?: number;
+    bucket?: VoiceAgentPerformanceBucket;
+};
+export declare const buildVoiceAgentPerformanceReport: (input: BuildVoiceAgentPerformanceReportInput) => VoiceAgentPerformanceReport;

package/dist/core/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 assertVoiceAgentSquadContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentSquadContractRunOptions<TContext, TSession, TResult>) => Promise<VoiceAgentSquadContractReport<TResult>>;
+export declare const assertVoiceAgentSquadContractEvidence: (reports: readonly VoiceAgentSquadContractReport[], input?: VoiceAgentSquadContractAssertionInput) => VoiceAgentSquadContractAssertionReport;
+export declare const evaluateVoiceAgentSquadContractEvidence: (reports: readonly VoiceAgentSquadContractReport[], input?: VoiceAgentSquadContractAssertionInput) => VoiceAgentSquadContractAssertionReport;
+export declare const runVoiceAgentSquadContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentSquadContractRunOptions<TContext, TSession, TResult>) => Promise<VoiceAgentSquadContractReport<TResult>>;

package/dist/core/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 voiceAgentUIStateOrder: ReadonlyArray<VoiceAgentUIState>;
+export declare const deriveVoiceAgentUIState: (input: VoiceAgentUIInput) => VoiceAgentUIState;
+export declare const describeVoiceAgentUIState: (state: VoiceAgentUIState) => string;

package/dist/core/agentTools.d.ts

@@ -0,0 +1,132 @@
+import { type VoiceAgentTool } from "./agent";
+import type { 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>>;