@absolutejs/voice 0.0.22-beta.6 → 0.0.22-beta.600

package/dist/core/supervisorPermissions.d.ts

@@ -0,0 +1,33 @@
+export type VoiceSupervisorCapability = "monitor" | "annotate" | "coach" | "whisper" | "barge" | "takeover" | "release" | "end-call" | "view-pii" | "export-recording";
+export type VoiceSupervisorTier = "monitor-only" | "annotate" | "coach" | "whisper" | "full-control";
+export type VoiceSupervisorPermission = {
+    supervisorId: string;
+    tier: VoiceSupervisorTier;
+    extraCapabilities?: VoiceSupervisorCapability[];
+    deniedCapabilities?: VoiceSupervisorCapability[];
+    expiresAt?: number;
+};
+export type VoiceSupervisorPermissionCheck = {
+    allowed: boolean;
+    reason?: "no-permission" | "expired" | "denied" | "tier-too-low";
+};
+export type CreateVoiceSupervisorPermissionsOptions = {
+    defaultTier?: VoiceSupervisorTier;
+    permissions?: VoiceSupervisorPermission[];
+    now?: () => number;
+};
+export declare const createVoiceSupervisorPermissions: (options?: CreateVoiceSupervisorPermissionsOptions) => {
+    can: (supervisorId: string, capability: VoiceSupervisorCapability) => VoiceSupervisorPermissionCheck;
+    capabilitiesFor: (supervisorId: string) => VoiceSupervisorCapability[];
+    enforce: (supervisorId: string, capability: VoiceSupervisorCapability) => void;
+    get: (supervisorId: string) => VoiceSupervisorPermission | null;
+    grant: (supervisorId: string, tier: VoiceSupervisorTier, options?: {
+        extraCapabilities?: VoiceSupervisorCapability[];
+        deniedCapabilities?: VoiceSupervisorCapability[];
+        expiresAt?: number;
+    }) => VoiceSupervisorPermission;
+    revoke: (supervisorId: string) => boolean;
+    tiers: () => VoiceSupervisorTier[];
+};
+export type VoiceSupervisorPermissions = ReturnType<typeof createVoiceSupervisorPermissions>;
+export declare const VOICE_SUPERVISOR_TIER_CAPABILITIES: Record<VoiceSupervisorTier, VoiceSupervisorCapability[]>;

package/dist/core/supervisorPresence.d.ts

@@ -0,0 +1,49 @@
+export type VoiceSupervisorRole = "viewer" | "coach" | "whisperer" | "owner";
+export type VoiceSupervisorWatcher = {
+    supervisorId: string;
+    sessionId: string;
+    joinedAt: number;
+    lastSeenAt: number;
+    role: VoiceSupervisorRole;
+    displayName?: string;
+};
+export type VoiceSupervisorPresenceEvent = {
+    type: "join";
+    watcher: VoiceSupervisorWatcher;
+} | {
+    type: "leave";
+    supervisorId: string;
+    sessionId: string;
+    at: number;
+} | {
+    type: "role-change";
+    supervisorId: string;
+    sessionId: string;
+    from: VoiceSupervisorRole;
+    to: VoiceSupervisorRole;
+    at: number;
+} | {
+    type: "heartbeat";
+    supervisorId: string;
+    sessionId: string;
+    at: number;
+};
+export type CreateVoiceSupervisorPresenceOptions = {
+    staleAfterMs?: number;
+    now?: () => number;
+};
+export declare const createVoiceSupervisorPresence: (options?: CreateVoiceSupervisorPresenceOptions) => {
+    heartbeat: (sessionId: string, supervisorId: string) => boolean;
+    join: (input: {
+        supervisorId: string;
+        sessionId: string;
+        role?: VoiceSupervisorRole;
+        displayName?: string;
+    }) => VoiceSupervisorWatcher;
+    leave: (sessionId: string, supervisorId: string) => boolean;
+    list: (sessionId: string) => VoiceSupervisorWatcher[];
+    setRole: (sessionId: string, supervisorId: string, role: VoiceSupervisorRole) => boolean;
+    sessionsWatchedBy(supervisorId: string): string[];
+    subscribe(listener: (event: VoiceSupervisorPresenceEvent) => void): () => void;
+};
+export type VoiceSupervisorPresence = ReturnType<typeof createVoiceSupervisorPresence>;

package/dist/core/telephonyMediaRoutes.d.ts

@@ -0,0 +1,72 @@
+import { Elysia } from "elysia";
+import type { MediaFrame, MediaTelephonyCarrier, MediaTelephonyEnvelope, MediaTelephonyStreamLifecycleReport } from "@absolutejs/media";
+import type { VoiceTraceEventStore } from "./trace";
+export type VoiceTelephonyMediaStatus = "fail" | "pass";
+export type VoiceTelephonyMediaCarrierInput = {
+    carrier: MediaTelephonyCarrier;
+    envelope?: MediaTelephonyEnvelope;
+    lifecycleEnvelopes?: readonly MediaTelephonyEnvelope[];
+};
+export type VoiceTelephonyMediaCarrierReport = {
+    audioBytes: number;
+    carrier: MediaTelephonyCarrier;
+    frame?: MediaFrame;
+    issues: string[];
+    lifecycle: MediaTelephonyStreamLifecycleReport;
+    serialized?: MediaTelephonyEnvelope;
+    status: VoiceTelephonyMediaStatus;
+};
+export type VoiceTelephonyMediaReport = {
+    carriers: readonly VoiceTelephonyMediaCarrierReport[];
+    checkedAt: number;
+    issues: string[];
+    status: VoiceTelephonyMediaStatus;
+};
+export type VoiceTelephonyMediaRoutesOptions = {
+    carriers?: readonly VoiceTelephonyMediaCarrierInput[];
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    name?: string;
+    path?: string;
+    store?: VoiceTraceEventStore;
+    title?: string;
+};
+export type VoiceTelephonyMediaTraceReportOptions = {
+    carriers?: readonly MediaTelephonyCarrier[];
+    store: VoiceTraceEventStore;
+};
+export declare const buildVoiceTelephonyMediaReport: (input?: {
+    carriers?: readonly VoiceTelephonyMediaCarrierInput[];
+}) => VoiceTelephonyMediaReport;
+export declare const createVoiceTelephonyMediaRoutes: (options?: VoiceTelephonyMediaRoutesOptions) => 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 getLatestVoiceTelephonyMediaReport: (options: VoiceTelephonyMediaTraceReportOptions) => Promise<VoiceTelephonyMediaReport | undefined>;
+export declare const renderVoiceTelephonyMediaHTML: (report: VoiceTelephonyMediaReport, options?: {
+    title?: string;
+}) => string;

package/dist/core/telephonyOutcome.d.ts

@@ -0,0 +1,269 @@
+import { Elysia } from "elysia";
+import type { VoiceCallDisposition, VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord } from "./types";
+export type VoiceTelephonyOutcomeAction = "complete" | "escalate" | "ignore" | "no-answer" | "transfer" | "voicemail";
+export type VoiceTelephonyOutcomeProviderEvent = {
+    answeredBy?: string;
+    durationMs?: number;
+    from?: string;
+    metadata?: Record<string, unknown>;
+    provider?: string;
+    reason?: string;
+    sipCode?: number;
+    status?: string;
+    target?: string;
+    to?: string;
+};
+export type VoiceTelephonyOutcomeDecision = {
+    action: VoiceTelephonyOutcomeAction;
+    confidence: "high" | "low" | "medium";
+    disposition?: VoiceCallDisposition;
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    source: "answered-by" | "duration" | "explicit-target" | "policy" | "sip" | "status";
+    target?: string;
+};
+export type VoiceTelephonyOutcomeStatusDecision = VoiceTelephonyOutcomeAction | (Omit<VoiceTelephonyOutcomeDecision, "confidence" | "source"> & {
+    confidence?: VoiceTelephonyOutcomeDecision["confidence"];
+    source?: VoiceTelephonyOutcomeDecision["source"];
+});
+export type VoiceTelephonyOutcomePolicy = {
+    completedStatuses?: string[];
+    escalationStatuses?: string[];
+    failedAsNoAnswer?: boolean;
+    failedStatuses?: string[];
+    includeProviderPayload?: boolean;
+    machineDetectionVoicemailValues?: string[];
+    metadata?: Record<string, unknown>;
+    minAnsweredDurationMs?: number;
+    noAnswerOnZeroDuration?: boolean;
+    noAnswerSipCodes?: number[];
+    noAnswerStatuses?: string[];
+    statusMap?: Record<string, VoiceTelephonyOutcomeStatusDecision>;
+    transferStatuses?: string[];
+    transferTarget?: string | ((event: VoiceTelephonyOutcomeProviderEvent) => string | undefined);
+    voicemailStatuses?: string[];
+};
+export type VoiceTelephonyOutcomeRouteResult<TResult = unknown> = VoiceRouteResult<TResult>;
+export type VoiceTelephonyWebhookProvider = "generic" | "plivo" | "telnyx" | "twilio";
+export type VoiceTelephonyWebhookParseInput = {
+    body: unknown;
+    headers: Headers;
+    provider: VoiceTelephonyWebhookProvider;
+    query: Record<string, unknown>;
+    request: Request;
+};
+export type VoiceTelephonyWebhookDecision<TResult = unknown> = {
+    applied: boolean;
+    decision: VoiceTelephonyOutcomeDecision;
+    duplicate?: boolean;
+    event: VoiceTelephonyOutcomeProviderEvent;
+    idempotencyKey?: string;
+    routeResult: VoiceTelephonyOutcomeRouteResult<TResult>;
+    sessionId?: string;
+};
+export type StoredVoiceTelephonyWebhookDecision<TResult = unknown> = VoiceTelephonyWebhookDecision<TResult> & {
+    createdAt: number;
+    updatedAt: number;
+};
+export type VoiceTelephonyWebhookNormalizationEvidenceDecision = {
+    action?: VoiceTelephonyOutcomeAction | string;
+    applied?: boolean;
+    decision?: {
+        action?: VoiceTelephonyOutcomeAction | string;
+        disposition?: VoiceCallDisposition | string;
+        source?: VoiceTelephonyOutcomeDecision["source"] | string;
+    };
+    disposition?: VoiceCallDisposition | string;
+    duplicate?: boolean;
+    campaignOutcome?: unknown;
+    event?: VoiceTelephonyOutcomeProviderEvent;
+    idempotencyKey?: string;
+    provider?: VoiceTelephonyWebhookProvider | string;
+    routeResult?: unknown;
+    sessionId?: string;
+    source?: VoiceTelephonyOutcomeDecision["source"] | string;
+};
+export type VoiceTelephonyWebhookVerificationEvidenceAttempt = {
+    decisions?: number;
+    provider?: VoiceTelephonyWebhookProvider | string;
+    rejected?: boolean;
+    replayRejected?: boolean;
+    sideEffects?: number;
+    status?: number;
+    verification?: VoiceTelephonyWebhookVerificationResult;
+};
+export type VoiceTelephonyWebhookNormalizationEvidenceInput = {
+    decisions?: VoiceTelephonyWebhookNormalizationEvidenceDecision[];
+    maxMissingSessionIds?: number;
+    minApplied?: number;
+    minDecisions?: number;
+    minDuplicateIdempotencyKeys?: number;
+    minDuplicates?: number;
+    maxDuplicateCampaignOutcomesApplied?: number;
+    maxRejectedVerificationSideEffects?: number;
+    minRejectedVerificationAttempts?: number;
+    minReplayRejectedVerificationAttempts?: number;
+    requiredActions?: VoiceTelephonyOutcomeAction[];
+    requiredDispositions?: VoiceCallDisposition[];
+    requiredDuplicateProviders?: VoiceTelephonyWebhookProvider[];
+    requiredProviders?: VoiceTelephonyWebhookProvider[];
+    requiredReplayRejectedVerificationProviders?: VoiceTelephonyWebhookProvider[];
+    requiredRejectedVerificationProviders?: VoiceTelephonyWebhookProvider[];
+    requireRouteResults?: boolean;
+    verificationAttempts?: VoiceTelephonyWebhookVerificationEvidenceAttempt[];
+};
+export type VoiceTelephonyWebhookNormalizationEvidenceReport = {
+    actions: VoiceTelephonyOutcomeAction[];
+    applied: number;
+    decisions: number;
+    dispositions: VoiceCallDisposition[];
+    duplicateCampaignOutcomesApplied: number;
+    duplicateIdempotencyKeys: number;
+    duplicateOutcomeReasons: string[];
+    duplicateProviders: VoiceTelephonyWebhookProvider[];
+    duplicates: number;
+    issues: string[];
+    missingSessionIds: number;
+    ok: boolean;
+    providers: VoiceTelephonyWebhookProvider[];
+    rejectedVerificationAttempts: number;
+    rejectedVerificationProviders: VoiceTelephonyWebhookProvider[];
+    rejectedVerificationSideEffects: number;
+    replayRejectedVerificationAttempts: number;
+    replayRejectedVerificationProviders: VoiceTelephonyWebhookProvider[];
+    routeResults: number;
+    sources: string[];
+    verificationAttempts: number;
+};
+export type VoiceTelephonyWebhookIdempotencyStore<TResult = unknown> = {
+    get: (key: string) => Promise<StoredVoiceTelephonyWebhookDecision<TResult> | undefined> | StoredVoiceTelephonyWebhookDecision<TResult> | undefined;
+    set: (key: string, decision: StoredVoiceTelephonyWebhookDecision<TResult>) => Promise<void> | void;
+};
+export type VoiceTelephonyWebhookVerificationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "invalid-signature" | "missing-secret" | "missing-signature" | "unsupported-provider";
+};
+export type VoiceTelephonyWebhookHandlerOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    apply?: boolean | ((input: VoiceTelephonyWebhookDecision<TResult>) => boolean);
+    context?: TContext;
+    getSessionHandle?: (input: {
+        context: TContext;
+        decision: VoiceTelephonyOutcomeDecision;
+        event: VoiceTelephonyOutcomeProviderEvent;
+        request: Request;
+        sessionId?: string;
+    }) => Promise<VoiceSessionHandle<TContext, TSession, TResult> | undefined> | VoiceSessionHandle<TContext, TSession, TResult> | undefined;
+    idempotency?: {
+        enabled?: boolean;
+        key?: (input: {
+            body: unknown;
+            event: VoiceTelephonyOutcomeProviderEvent;
+            provider: VoiceTelephonyWebhookProvider;
+            query: Record<string, unknown>;
+            request: Request;
+            sessionId?: string;
+        }) => Promise<string | undefined> | string | undefined;
+        store?: VoiceTelephonyWebhookIdempotencyStore<TResult>;
+    };
+    onDecision?: (input: VoiceTelephonyWebhookDecision<TResult> & {
+        context: TContext;
+        request: Request;
+    }) => Promise<void> | void;
+    parse?: (input: VoiceTelephonyWebhookParseInput) => Promise<VoiceTelephonyOutcomeProviderEvent> | VoiceTelephonyOutcomeProviderEvent;
+    policy?: VoiceTelephonyOutcomePolicy;
+    provider?: VoiceTelephonyWebhookProvider;
+    requireVerification?: boolean;
+    resolveSessionId?: (input: {
+        body: unknown;
+        event: VoiceTelephonyOutcomeProviderEvent;
+        query: Record<string, unknown>;
+        request: Request;
+    }) => Promise<string | undefined> | string | undefined;
+    result?: TResult | ((input: {
+        decision: VoiceTelephonyOutcomeDecision;
+        event: VoiceTelephonyOutcomeProviderEvent;
+        sessionId?: string;
+    }) => Promise<TResult | undefined> | TResult | undefined);
+    signingSecret?: string;
+    verificationUrl?: string | ((input: {
+        query: Record<string, unknown>;
+        request: Request;
+    }) => string);
+    verify?: (input: {
+        body: unknown;
+        headers: Headers;
+        provider: VoiceTelephonyWebhookProvider;
+        query: Record<string, unknown>;
+        rawBody: string;
+        request: Request;
+    }) => Promise<VoiceTelephonyWebhookVerificationResult> | VoiceTelephonyWebhookVerificationResult;
+};
+export type VoiceTelephonyWebhookRoutesOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceTelephonyWebhookHandlerOptions<TContext, TSession, TResult> & {
+    name?: string;
+    path?: string;
+};
+export declare const createMemoryVoiceTelephonyWebhookIdempotencyStore: <TResult = unknown>() => VoiceTelephonyWebhookIdempotencyStore<TResult>;
+export declare const assertVoiceTelephonyWebhookNormalizationEvidence: (input?: VoiceTelephonyWebhookNormalizationEvidenceInput) => VoiceTelephonyWebhookNormalizationEvidenceReport;
+export declare const evaluateVoiceTelephonyWebhookNormalizationEvidence: (input?: VoiceTelephonyWebhookNormalizationEvidenceInput) => VoiceTelephonyWebhookNormalizationEvidenceReport;
+export declare const applyVoiceTelephonyOutcome: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(api: VoiceSessionHandle<TContext, TSession, TResult>, decision: VoiceTelephonyOutcomeDecision, result?: TResult) => Promise<void>;
+export declare const createVoiceTelephonyOutcomePolicy: (policy?: VoiceTelephonyOutcomePolicy) => Required<Pick<VoiceTelephonyOutcomePolicy, "completedStatuses" | "escalationStatuses" | "failedAsNoAnswer" | "failedStatuses" | "includeProviderPayload" | "machineDetectionVoicemailValues" | "noAnswerOnZeroDuration" | "noAnswerSipCodes" | "noAnswerStatuses" | "transferStatuses" | "voicemailStatuses">> & VoiceTelephonyOutcomePolicy;
+export declare const resolveVoiceTelephonyOutcome: (event: VoiceTelephonyOutcomeProviderEvent, policyInput?: VoiceTelephonyOutcomePolicy) => VoiceTelephonyOutcomeDecision;
+export declare const voiceTelephonyOutcomeToRouteResult: <TResult = unknown>(decision: VoiceTelephonyOutcomeDecision, result?: TResult) => VoiceTelephonyOutcomeRouteResult<TResult>;
+export declare const signVoiceTwilioWebhook: (input: {
+    authToken: string;
+    body?: unknown;
+    url: string;
+}) => Promise<string>;
+export declare const verifyVoiceTwilioWebhookSignature: (input: {
+    authToken?: string;
+    body?: unknown;
+    headers: Headers;
+    url: string;
+}) => Promise<VoiceTelephonyWebhookVerificationResult>;
+export declare const parseVoiceTelephonyWebhookEvent: (input: VoiceTelephonyWebhookParseInput) => VoiceTelephonyOutcomeProviderEvent;
+export declare const createVoiceTelephonyWebhookHandler: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: VoiceTelephonyWebhookHandlerOptions<TContext, TSession, TResult>) => (input: {
+    query?: Record<string, unknown>;
+    request: Request;
+}) => Promise<VoiceTelephonyWebhookDecision<TResult>>;
+export declare const createVoiceTelephonyWebhookRoutes: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options?: VoiceTelephonyWebhookRoutesOptions<TContext, TSession, TResult>) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        post: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response | VoiceTelephonyWebhookDecision<TResult>;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/core/toolContract.d.ts

@@ -0,0 +1,161 @@
+import { Elysia } from "elysia";
+import type { VoiceAgentTool } from "./agent";
+import { type VoiceToolRuntimeOptions } from "./toolRuntime";
+import type { VoiceSessionRecord, VoiceTurnRecord } from "./types";
+export type VoiceToolContractExpectation = {
+    expectedAttempts?: number;
+    expectedErrorIncludes?: string;
+    expectedResult?: unknown;
+    expectIdempotent?: boolean;
+    expectStatus?: "error" | "ok";
+    expectTimedOut?: boolean;
+    maxElapsedMs?: number;
+};
+export type VoiceToolContractCase<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
+    args: TArgs;
+    context?: TContext;
+    expect?: VoiceToolContractExpectation;
+    id: string;
+    label?: string;
+    runtime?: VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>;
+    session?: TSession;
+    toolCallId?: string;
+    turn?: VoiceTurnRecord;
+};
+export type VoiceToolContractDefinition<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
+    cases: Array<VoiceToolContractCase<TContext, TSession, TArgs, TToolResult, TRouteResult>>;
+    defaultRuntime?: VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>;
+    description?: string;
+    id: string;
+    label?: string;
+    tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+};
+export type VoiceToolContractIssue = {
+    caseId: string;
+    code: string;
+    message: string;
+};
+export type VoiceToolContractCaseReport = {
+    attempts: number;
+    caseId: string;
+    elapsedMs: number;
+    error?: string;
+    issues: VoiceToolContractIssue[];
+    label?: string;
+    operationsRecordHref?: string;
+    pass: boolean;
+    sessionId: string;
+    status: "error" | "ok";
+    timedOut: boolean;
+};
+export type VoiceToolContractReport = {
+    cases: VoiceToolContractCaseReport[];
+    contractId: string;
+    label?: string;
+    issues: VoiceToolContractIssue[];
+    pass: boolean;
+    toolName: string;
+};
+export type VoiceToolContractSuiteReport = {
+    checkedAt: number;
+    contracts: VoiceToolContractReport[];
+    failed: number;
+    passed: number;
+    status: "fail" | "pass";
+    total: number;
+};
+export type VoiceToolContractAssertionInput = {
+    maxFailed?: number;
+    maxIssues?: number;
+    maxTimedOut?: number;
+    minCases?: number;
+    minContracts?: number;
+    requireOperationRecordHrefs?: boolean;
+    requiredCaseStatuses?: Array<"error" | "ok">;
+    requiredContractIds?: string[];
+    requiredToolNames?: string[];
+};
+export type VoiceToolContractAssertionReport = {
+    caseStatuses: Array<"error" | "ok">;
+    cases: number;
+    contractIds: string[];
+    failed: number;
+    issues: string[];
+    issueCount: number;
+    missingOperationsRecordHrefs: number;
+    ok: boolean;
+    passed: number;
+    status: VoiceToolContractSuiteReport["status"];
+    timedOut: number;
+    toolNames: string[];
+    total: number;
+};
+export type VoiceToolContractHandlerOptions = {
+    contracts: VoiceToolContractDefinition[];
+    operationsRecordHref?: false | string | ((sessionId: string) => string);
+};
+export type VoiceToolContractHTMLHandlerOptions = VoiceToolContractHandlerOptions & {
+    headers?: HeadersInit;
+    render?: (report: VoiceToolContractSuiteReport) => string | Promise<string>;
+    title?: string;
+};
+export type VoiceToolContractRoutesOptions = VoiceToolContractHTMLHandlerOptions & {
+    htmlPath?: false | string;
+    name?: string;
+    path?: string;
+};
+export declare const assertVoiceToolContractEvidence: (report: VoiceToolContractSuiteReport, input?: VoiceToolContractAssertionInput) => VoiceToolContractAssertionReport;
+export declare const createVoiceToolContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown>(definition: VoiceToolContractDefinition<TContext, TSession, TArgs, TToolResult, TRouteResult>) => {
+    definition: VoiceToolContractDefinition<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+    assert: () => Promise<VoiceToolContractReport>;
+    run: () => Promise<VoiceToolContractReport>;
+};
+export declare const createVoiceToolContractHTMLHandler: (options: VoiceToolContractHTMLHandlerOptions) => () => Promise<Response>;
+export declare const createVoiceToolContractJSONHandler: (options: VoiceToolContractHandlerOptions) => () => Promise<VoiceToolContractSuiteReport>;
+export declare const createVoiceToolContractRoutes: (options: VoiceToolContractRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceToolContractSuiteReport;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+export declare const createVoiceToolRuntimeContractDefaults: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown>() => VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>;
+export declare const evaluateVoiceToolContractEvidence: (report: VoiceToolContractSuiteReport, input?: VoiceToolContractAssertionInput) => VoiceToolContractAssertionReport;
+export declare const renderVoiceToolContractHTML: (report: VoiceToolContractSuiteReport, options?: {
+    title?: string;
+}) => string;
+export declare const runVoiceToolContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown>(definition: VoiceToolContractDefinition<TContext, TSession, TArgs, TToolResult, TRouteResult>, options?: Pick<VoiceToolContractHandlerOptions, "operationsRecordHref">) => Promise<VoiceToolContractReport>;
+export declare const runVoiceToolContractSuite: (options: VoiceToolContractHandlerOptions) => Promise<VoiceToolContractSuiteReport>;

package/dist/core/toolRuntime.d.ts

@@ -0,0 +1,50 @@
+import type { VoiceAgentTool, VoiceAgentToolResult } from "./agent";
+import type { VoiceSessionHandle, VoiceSessionRecord, VoiceTurnRecord } from "./types";
+import type { VoiceTraceEventStore } from "./trace";
+export type VoiceToolRetryDelay = number | ((input: {
+    attempt: number;
+    error: unknown;
+    toolName: string;
+}) => number);
+export type VoiceToolRuntimeOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown> = {
+    idempotencyKey?: (input: {
+        args: unknown;
+        context: TContext;
+        session: TSession;
+        toolCallId?: string;
+        toolName: string;
+        turn: VoiceTurnRecord;
+    }) => string | undefined;
+    idempotencyTtlMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: VoiceToolRetryDelay;
+    timeoutMs?: number;
+    trace?: VoiceTraceEventStore;
+};
+export type VoiceToolRuntimeExecuteInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
+    api: VoiceSessionHandle<TContext, TSession, TRouteResult>;
+    args: TArgs;
+    context: TContext;
+    session: TSession;
+    tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+    toolCallId?: string;
+    turn: VoiceTurnRecord;
+};
+export type VoiceToolRuntimeResult<TToolResult = unknown> = VoiceAgentToolResult<TToolResult> & {
+    attempts: number;
+    elapsedMs: number;
+    idempotencyKey?: string;
+    timedOut: boolean;
+};
+export type VoiceToolRuntime<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown> = {
+    execute: <TArgs = Record<string, unknown>, TToolResult = unknown>(input: VoiceToolRuntimeExecuteInput<TContext, TSession, TArgs, TToolResult, TRouteResult>) => Promise<VoiceToolRuntimeResult<TToolResult>>;
+    wrapTool: <TArgs = Record<string, unknown>, TToolResult = unknown>(tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>) => VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+};
+export declare const createVoiceToolIdempotencyKey: (input: {
+    args: unknown;
+    sessionId: string;
+    toolCallId?: string;
+    toolName: string;
+    turnId: string;
+}) => string;
+export declare const createVoiceToolRuntime: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown>(options?: VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>) => VoiceToolRuntime<TContext, TSession, TRouteResult>;