@absolutejs/voice 0.0.22-beta.1 → 0.0.22-beta.3

package/README.md

@@ -73,6 +73,88 @@ const app = new Elysia()
 
 `createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
 
+## Voice Assistants
+
+Use `createVoiceAssistant(...)` when you want one product-level surface for a voice agent instead of wiring tools, guardrails, experiments, traces, and ops recipes separately. It returns a standard `onTurn` handler, plus an `ops` object you can pass to `voice(...)`.
+
+```ts
+import {
+	createVoiceAssistant,
+	createVoiceExperiment,
+	createVoiceFileRuntimeStorage,
+	createVoiceMemoryStore,
+	createVoiceAgentTool,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+const lookupOrder = createVoiceAgentTool({
+	name: 'lookup_order',
+	description: 'Look up an order by id.',
+	execute: async ({ args }) => ({ orderId: args.orderId, status: 'shipped' })
+});
+
+const assistant = createVoiceAssistant({
+	id: 'support',
+	artifactPlan: {
+		ops: {
+			events: runtimeStorage.events,
+			reviews: runtimeStorage.reviews,
+			tasks: runtimeStorage.tasks
+		},
+		preset: {
+			name: 'support-triage',
+			options: {
+				queue: 'support-triage'
+			}
+		}
+	},
+	experiment: createVoiceExperiment({
+		id: 'support-prompt',
+		variants: [
+			{ id: 'baseline', weight: 1 },
+			{
+				id: 'direct',
+				weight: 1,
+				system: 'You are concise, practical, and resolve the caller quickly.'
+			}
+		]
+	}),
+	guardrails: {
+		beforeTurn: ({ turn }) =>
+			turn.text.toLowerCase().includes('human')
+				? { escalate: { reason: 'caller requested a human' } }
+				: undefined
+	},
+	model: {
+		async generate({ messages, tools }) {
+			return {
+				assistantText: `I can help. Available tools: ${tools.map((tool) => tool.name).join(', ')}`
+			};
+		}
+	},
+	system: 'You are a support voice assistant.',
+	tools: [lookupOrder],
+	trace: runtimeStorage.traces
+});
+
+voice({
+	path: '/voice',
+	session: createVoiceMemoryStore(),
+	stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+	trace: runtimeStorage.traces,
+	ops: assistant.ops,
+	onTurn: assistant.onTurn,
+	onComplete: async () => {}
+});
+```
+
+Assistant experiments are deterministic by session id, so a caller stays on the same variant for a call. Variants can change the model, system prompt, tools, and tool-round budget; guardrails can block a turn before model execution or rewrite the returned `VoiceRouteResult`.
+
 ## Agent Tools And Squads
 
 For assistant-style products, use `createVoiceAgent(...)` as the `onTurn` handler. The agent layer is provider-neutral: plug in any model adapter, register server-side tools, and return normal voice route results like `assistantText`, `transfer`, `escalate`, or `complete`.

package/dist/assistant.d.ts

@@ -0,0 +1,123 @@
+import { type VoiceAgent, type VoiceAgentModel, type VoiceAgentOptions, type VoiceAgentSquadOptions, type VoiceAgentTool } from './agent';
+import { type VoiceOutcomeRecipeName, type VoiceOutcomeRecipeOptions } from './outcomeRecipes';
+import type { VoiceNormalizedRouteConfig, VoiceOnTurnObjectHandler, VoiceRouteConfig, VoiceRouteResult, VoiceRuntimeOpsConfig, VoiceSessionRecord } from './types';
+import type { StoredVoiceTraceEvent, VoiceTraceEventStore } from './trace';
+export type VoiceAssistantPreset = VoiceOutcomeRecipeName;
+export type VoiceAssistantArtifactPlan<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    ops?: VoiceRuntimeOpsConfig<TContext, TSession, TResult>;
+    preset?: VoiceAssistantPreset | {
+        name: VoiceAssistantPreset;
+        options?: VoiceOutcomeRecipeOptions;
+    };
+};
+export type VoiceAssistantGuardrailInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Parameters<VoiceOnTurnObjectHandler<TContext, TSession, TResult>>[0] & {
+    assistantId: string;
+};
+export type VoiceAssistantOutputGuardrailInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceAssistantGuardrailInput<TContext, TSession, TResult> & {
+    result: VoiceRouteResult<TResult>;
+};
+export type VoiceAssistantGuardrails<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    beforeTurn?: (input: VoiceAssistantGuardrailInput<TContext, TSession, TResult>) => Promise<VoiceRouteResult<TResult> | void> | VoiceRouteResult<TResult> | void;
+    afterTurn?: (input: VoiceAssistantOutputGuardrailInput<TContext, TSession, TResult>) => Promise<VoiceRouteResult<TResult> | void> | VoiceRouteResult<TResult> | void;
+};
+export type VoiceAssistantVariant<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    id: string;
+    maxToolRounds?: number;
+    metadata?: Record<string, unknown>;
+    model?: VoiceAgentModel<TContext, TSession, TResult>;
+    system?: VoiceAgentOptions<TContext, TSession, TResult>['system'];
+    tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
+    weight?: number;
+};
+export type VoiceAssistantExperimentResolverInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord> = {
+    assistantId: string;
+    context: TContext;
+    session: TSession;
+    turnId?: string;
+};
+export type VoiceAssistantExperiment<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    id: string;
+    resolve: (input: VoiceAssistantExperimentResolverInput<TContext, TSession>) => VoiceAssistantVariant<TContext, TSession, TResult>;
+    variants: Array<VoiceAssistantVariant<TContext, TSession, TResult>>;
+};
+export type VoiceAssistantExperimentOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    id: string;
+    selectVariant?: (input: VoiceAssistantExperimentResolverInput<TContext, TSession> & {
+        variants: Array<VoiceAssistantVariant<TContext, TSession, TResult>>;
+    }) => VoiceAssistantVariant<TContext, TSession, TResult> | string | void;
+    variants: Array<VoiceAssistantVariant<TContext, TSession, TResult>>;
+};
+type VoiceAssistantAgentSource<TContext, TSession extends VoiceSessionRecord, TResult> = {
+    agent: VoiceAgent<TContext, TSession, TResult>;
+    agents?: never;
+    defaultAgentId?: never;
+    maxHandoffsPerTurn?: never;
+    maxToolRounds?: never;
+    model?: never;
+    selectAgent?: never;
+    system?: never;
+    tools?: never;
+} | {
+    agent?: never;
+    agents: Array<VoiceAgent<TContext, TSession, TResult>>;
+    defaultAgentId: string;
+    maxHandoffsPerTurn?: number;
+    maxToolRounds?: never;
+    model?: never;
+    selectAgent?: VoiceAgentSquadOptions<TContext, TSession, TResult>['selectAgent'];
+    system?: never;
+    tools?: never;
+} | {
+    agent?: never;
+    agents?: never;
+    defaultAgentId?: never;
+    maxHandoffsPerTurn?: never;
+    maxToolRounds?: number;
+    model: VoiceAgentModel<TContext, TSession, TResult>;
+    selectAgent?: never;
+    system?: VoiceAgentOptions<TContext, TSession, TResult>['system'];
+    tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
+};
+export type VoiceAssistantOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceAssistantAgentSource<TContext, TSession, TResult> & {
+    artifactPlan?: VoiceAssistantArtifactPlan<TContext, TSession, TResult>;
+    experiment?: VoiceAssistantExperiment<TContext, TSession, TResult>;
+    guardrails?: VoiceAssistantGuardrails<TContext, TSession, TResult>;
+    id: string;
+    ops?: VoiceRuntimeOpsConfig<TContext, TSession, TResult>;
+    trace?: VoiceAgentOptions<TContext, TSession, TResult>['trace'];
+};
+export type VoiceAssistant<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    agent: VoiceAgent<TContext, TSession, TResult>;
+    id: string;
+    onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
+    ops?: VoiceRuntimeOpsConfig<TContext, TSession, TResult>;
+    route: (overrides: Omit<VoiceRouteConfig<TContext, TSession, TResult>, 'onComplete' | 'onTurn'> & {
+        onComplete?: VoiceRouteConfig<TContext, TSession, TResult>['onComplete'];
+    }) => VoiceNormalizedRouteConfig<TContext, TSession, TResult>;
+};
+export type VoiceAssistantRunSummary = {
+    assistantId: string;
+    artifactPlans: Record<string, number>;
+    averageElapsedMs?: number;
+    blockedGuardrailCount: number;
+    escalationCount: number;
+    experiments: Record<string, number>;
+    guardrailCount: number;
+    outcomes: Record<string, number>;
+    runCount: number;
+    sessions: number;
+    toolCalls: Record<string, number>;
+    transferCount: number;
+    variants: Record<string, number>;
+};
+export type VoiceAssistantRunsSummary = {
+    assistants: VoiceAssistantRunSummary[];
+    totalRuns: number;
+};
+export declare const createVoiceExperiment: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAssistantExperimentOptions<TContext, TSession, TResult>) => VoiceAssistantExperiment<TContext, TSession, TResult>;
+export declare const createVoiceAssistant: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAssistantOptions<TContext, TSession, TResult>) => VoiceAssistant<TContext, TSession, TResult>;
+export declare const summarizeVoiceAssistantRuns: (input: StoredVoiceTraceEvent[] | {
+    events?: StoredVoiceTraceEvent[];
+    store?: VoiceTraceEventStore;
+}) => Promise<VoiceAssistantRunsSummary>;
+export {};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { voice } from './plugin';
+export { createVoiceAssistant, createVoiceExperiment, summarizeVoiceAssistantRuns } from './assistant';
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool } from './agent';
 export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileExternalObjectMapStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore } from './fileStore';
 export { buildVoiceTraceReplay, createVoiceMemoryTraceSinkDeliveryStore, createVoiceTraceHTTPSink, createVoiceMemoryTraceEventStore, createVoiceTraceSinkDeliveryId, createVoiceTraceSinkDeliveryRecord, createVoiceTraceSinkStore, createVoiceTraceEvent, createVoiceTraceEventId, deliverVoiceTraceEventsToSinks, evaluateVoiceTrace, exportVoiceTrace, filterVoiceTraceEvents, pruneVoiceTraceEvents, redactVoiceTraceEvent, redactVoiceTraceEvents, redactVoiceTraceText, renderVoiceTraceHTML, renderVoiceTraceMarkdown, resolveVoiceTraceRedactionOptions, selectVoiceTraceEventsForPrune, summarizeVoiceTrace } from './trace';
@@ -21,6 +22,7 @@ export { conditionAudioChunk, resolveAudioConditioningConfig } from './audioCond
 export { resolveVoiceRuntimePreset } from './presets';
 export { resolveTurnDetectionConfig, TURN_PROFILE_DEFAULTS } from './turnProfiles';
 export { createVoiceCallReviewFromLiveTelephonyReport, createVoiceCallReviewRecorder, renderVoiceCallReviewHTML, renderVoiceCallReviewMarkdown } from './testing/review';
+export type { VoiceAssistant, VoiceAssistantArtifactPlan, VoiceAssistantExperiment, VoiceAssistantExperimentOptions, VoiceAssistantGuardrailInput, VoiceAssistantGuardrails, VoiceAssistantOptions, VoiceAssistantOutputGuardrailInput, VoiceAssistantPreset, VoiceAssistantRunsSummary, VoiceAssistantRunSummary, VoiceAssistantVariant } from './assistant';
 export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
 export type { VoiceOpsRuntime, VoiceOpsRuntimeConfig, VoiceOpsRuntimeSummary, VoiceOpsRuntimeSinkWorkerConfig, VoiceOpsRuntimeTaskWorkerConfig, VoiceOpsRuntimeTickResult, VoiceOpsRuntimeWebhookWorkerConfig } from './opsRuntime';
 export type { VoiceOpsPresetName, VoiceOpsPresetOverrides, VoiceResolvedOpsPreset } from './opsPresets';

package/dist/index.js

@@ -5368,6 +5368,567 @@ var createVoiceAgentSquad = (options) => {
     run
   };
 };
+
+// src/outcomeRecipes.ts
+var RECIPE_DEFAULTS = {
+  "appointment-booking": {
+    completedAction: "Verify appointment details, confirm calendar state, and send any required confirmation.",
+    completedDescription: "The call completed an appointment-booking flow and should be checked against the scheduling system.",
+    completedKind: "appointment-booking",
+    completedTitle: "Confirm booked appointment",
+    defaultCompletedCreatesTask: true,
+    defaultDueInMs: 30 * 60000,
+    defaultPriority: "normal",
+    defaultQueue: "appointments",
+    description: "Creates appointment confirmation work for completed calls and callback/retry work for missed booking attempts.",
+    escalationQueue: "appointments-escalations"
+  },
+  "lead-qualification": {
+    completedAction: "Review qualification signals, update CRM fields, and route the lead to the right owner.",
+    completedDescription: "The call completed a lead-qualification flow and should be reviewed for sales follow-up.",
+    completedKind: "lead-qualification",
+    completedTitle: "Review qualified lead",
+    defaultCompletedCreatesTask: true,
+    defaultDueInMs: 15 * 60000,
+    defaultPriority: "high",
+    defaultQueue: "sales-leads",
+    description: "Creates sales follow-up work for completed qualification calls and fast callbacks for missed leads.",
+    escalationQueue: "sales-escalations"
+  },
+  "support-triage": {
+    completedAction: "Review the triage result, confirm the support category, and route any unresolved issue.",
+    completedDescription: "The call completed support triage and may need queue routing or human follow-up.",
+    completedKind: "support-triage",
+    completedTitle: "Review support triage",
+    defaultCompletedCreatesTask: true,
+    defaultDueInMs: 20 * 60000,
+    defaultPriority: "normal",
+    defaultQueue: "support-triage",
+    description: "Creates support triage work for completed calls and urgent escalation/callback work for unresolved callers.",
+    escalationQueue: "support-escalations"
+  },
+  "voicemail-callback": {
+    completedAction: "No callback is required for completed calls.",
+    completedDescription: "The call completed without requiring voicemail follow-up.",
+    completedKind: "callback",
+    completedTitle: "Completed call",
+    defaultCompletedCreatesTask: false,
+    defaultDueInMs: 15 * 60000,
+    defaultPriority: "high",
+    defaultQueue: "callbacks",
+    description: "Creates callback work for voicemail, no-answer, failed, or escalated calls while ignoring completed calls.",
+    escalationQueue: "callback-escalations"
+  },
+  "warm-transfer": {
+    completedAction: "Confirm the handoff target received the caller context and close the transfer loop.",
+    completedDescription: "The call is part of a warm-transfer flow and should be verified downstream.",
+    completedKind: "transfer-check",
+    completedTitle: "Verify warm transfer",
+    defaultCompletedCreatesTask: false,
+    defaultDueInMs: 10 * 60000,
+    defaultPriority: "normal",
+    defaultQueue: "transfer-verification",
+    description: "Creates transfer verification work for transferred calls and escalation work when the handoff fails.",
+    escalationQueue: "transfer-escalations"
+  }
+};
+var buildRecipeTask = (input) => {
+  const createdAt = input.review.generatedAt ?? Date.now();
+  const queue = input.options.queue ?? input.defaults.defaultQueue;
+  const target = input.options.target ?? input.review.postCall?.target;
+  const common = {
+    assignee: input.options.assignee,
+    createdAt,
+    history: [
+      {
+        actor: "system",
+        at: createdAt,
+        detail: input.review.postCall?.summary,
+        type: "created"
+      }
+    ],
+    id: `${input.review.id}:${input.defaults.completedKind}`,
+    intakeId: input.review.id,
+    outcome: input.review.summary.outcome,
+    priority: input.options.priority ?? input.defaults.defaultPriority,
+    queue,
+    reviewId: input.review.id,
+    status: "open",
+    target,
+    updatedAt: createdAt
+  };
+  switch (input.disposition) {
+    case "completed":
+      if (!(input.options.completedCreatesTask ?? input.defaults.defaultCompletedCreatesTask)) {
+        return null;
+      }
+      return {
+        ...common,
+        description: input.defaults.completedDescription,
+        kind: input.defaults.completedKind,
+        recommendedAction: input.defaults.completedAction,
+        title: target ? `${input.defaults.completedTitle}: ${target}` : input.defaults.completedTitle
+      };
+    case "voicemail":
+      return {
+        ...common,
+        description: input.review.postCall?.summary ?? "The caller reached voicemail and needs a callback.",
+        id: `${input.review.id}:callback`,
+        kind: "callback",
+        recommendedAction: input.review.postCall?.recommendedAction ?? "Call the customer back and continue the original flow.",
+        title: target ? `Call back ${target}` : "Call back voicemail lead"
+      };
+    case "no-answer":
+      return {
+        ...common,
+        description: input.review.postCall?.summary ?? "The call did not reach a live respondent and should be retried.",
+        id: `${input.review.id}:retry`,
+        kind: "callback",
+        recommendedAction: input.review.postCall?.recommendedAction ?? "Retry the call or schedule a callback.",
+        title: "Retry no-answer call"
+      };
+    case "transferred":
+      return {
+        ...common,
+        description: input.review.postCall?.summary ?? "The call was transferred and should be verified downstream.",
+        id: `${input.review.id}:transfer-check`,
+        kind: "transfer-check",
+        recommendedAction: input.review.postCall?.recommendedAction ?? "Confirm the receiving team got the caller context.",
+        title: target ? `Verify transfer to ${target}` : "Verify call transfer"
+      };
+    case "escalated":
+      return {
+        ...common,
+        description: input.review.postCall?.summary ?? "The call escalated and needs human review.",
+        id: `${input.review.id}:escalation`,
+        kind: "escalation",
+        priority: "urgent",
+        queue: input.options.escalationQueue ?? input.defaults.escalationQueue,
+        assignee: input.options.escalationAssignee ?? input.options.assignee,
+        recommendedAction: input.review.postCall?.recommendedAction ?? "Review the escalated call and respond immediately.",
+        title: "Review escalated call"
+      };
+    case "failed":
+    case "closed":
+      return {
+        ...common,
+        description: input.review.postCall?.summary ?? "The call ended before successful completion and needs review.",
+        id: `${input.review.id}:retry-review`,
+        kind: "retry-review",
+        priority: "high",
+        recommendedAction: input.review.postCall?.recommendedAction ?? "Inspect the call and decide whether to retry, escalate, or close.",
+        title: "Inspect incomplete call"
+      };
+    default:
+      return null;
+  }
+};
+var resolveVoiceOutcomeRecipe = (name, options = {}) => {
+  const defaults = RECIPE_DEFAULTS[name];
+  const taskPolicies = {
+    completed: {
+      assignee: options.assignee,
+      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
+      name: `${name}-completed`,
+      priority: options.priority ?? defaults.defaultPriority,
+      queue: options.queue ?? defaults.defaultQueue
+    },
+    escalated: {
+      assignee: options.escalationAssignee ?? options.assignee,
+      dueInMs: Math.min(options.dueInMs ?? defaults.defaultDueInMs, 10 * 60000),
+      name: `${name}-escalation`,
+      priority: "urgent",
+      queue: options.escalationQueue ?? defaults.escalationQueue
+    },
+    failed: {
+      assignee: options.assignee,
+      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
+      name: `${name}-failed-review`,
+      priority: "high",
+      queue: options.queue ?? defaults.defaultQueue
+    },
+    "no-answer": {
+      assignee: options.assignee,
+      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
+      name: `${name}-no-answer`,
+      priority: options.priority ?? defaults.defaultPriority,
+      queue: options.queue ?? defaults.defaultQueue
+    },
+    transferred: {
+      assignee: options.assignee,
+      dueInMs: Math.min(options.dueInMs ?? defaults.defaultDueInMs, 20 * 60000),
+      name: `${name}-transfer-check`,
+      priority: options.priority ?? defaults.defaultPriority,
+      queue: name === "warm-transfer" ? options.queue ?? defaults.defaultQueue : "transfer-verification"
+    },
+    voicemail: {
+      assignee: options.assignee,
+      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
+      name: `${name}-voicemail`,
+      priority: options.priority ?? defaults.defaultPriority,
+      queue: options.queue ?? defaults.defaultQueue
+    }
+  };
+  const taskAssignmentRules = [
+    {
+      assign: options.escalationAssignee ?? options.assignee,
+      description: `Route urgent ${name} work to the escalation lane.`,
+      name: `${name}-urgent-routing`,
+      queue: options.escalationQueue ?? defaults.escalationQueue,
+      when: {
+        priority: "urgent"
+      }
+    }
+  ].filter((rule) => rule.assign || rule.queue);
+  return {
+    createTaskFromReview: ({ disposition, review }) => buildRecipeTask({
+      defaults,
+      disposition,
+      options,
+      review
+    }),
+    description: defaults.description,
+    name,
+    taskAssignmentRules,
+    taskPolicies
+  };
+};
+
+// src/assistant.ts
+var hashString = (value) => {
+  let hash = 2166136261;
+  for (let index = 0;index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+};
+var increment = (record, key) => {
+  record[key] = (record[key] ?? 0) + 1;
+};
+var resolveOutcome = (result) => {
+  if (result.transfer) {
+    return "transferred";
+  }
+  if (result.escalate) {
+    return "escalated";
+  }
+  if (result.voicemail) {
+    return "voicemail";
+  }
+  if (result.noAnswer) {
+    return "no-answer";
+  }
+  if (result.complete) {
+    return "completed";
+  }
+  return "continued";
+};
+var resolveArtifactPlanName = (artifactPlan) => {
+  const preset = artifactPlan?.preset;
+  if (!preset) {
+    return artifactPlan?.ops ? "custom" : undefined;
+  }
+  return typeof preset === "string" ? preset : preset.name;
+};
+var appendAssistantTrace = async (input) => {
+  await input.trace?.append({
+    at: Date.now(),
+    payload: {
+      assistantId: input.assistantId,
+      ...input.event
+    },
+    scenarioId: input.session.scenarioId,
+    sessionId: input.session.id,
+    turnId: input.turnId,
+    type: input.type
+  });
+};
+var resolvePresetOps = (artifactPlan) => {
+  const preset = artifactPlan?.preset;
+  if (!preset) {
+    return artifactPlan?.ops;
+  }
+  const recipe = typeof preset === "string" ? resolveVoiceOutcomeRecipe(preset) : resolveVoiceOutcomeRecipe(preset.name, preset.options);
+  return {
+    ...recipe,
+    ...artifactPlan?.ops
+  };
+};
+var mergeOps = (base, override) => {
+  if (!base && !override) {
+    return;
+  }
+  return {
+    ...base,
+    ...override,
+    taskAssignmentRules: base?.taskAssignmentRules || override?.taskAssignmentRules ? [
+      ...base?.taskAssignmentRules ?? [],
+      ...override?.taskAssignmentRules ?? []
+    ] : undefined,
+    taskPolicies: base?.taskPolicies || override?.taskPolicies ? {
+      ...base?.taskPolicies ?? {},
+      ...override?.taskPolicies ?? {}
+    } : undefined
+  };
+};
+var createVoiceExperiment = (options) => {
+  if (!options.variants.length) {
+    throw new Error("createVoiceExperiment requires at least one variant.");
+  }
+  const firstVariant = options.variants[0];
+  return {
+    id: options.id,
+    resolve: (input) => {
+      const selected = options.selectVariant?.({
+        ...input,
+        variants: options.variants
+      });
+      if (selected && typeof selected !== "object") {
+        const variant = options.variants.find((item) => item.id === selected);
+        if (variant) {
+          return variant;
+        }
+      }
+      if (selected && typeof selected === "object" && "id" in selected) {
+        return selected;
+      }
+      const totalWeight = options.variants.reduce((total, variant) => total + Math.max(0, variant.weight ?? 1), 0);
+      if (totalWeight <= 0) {
+        return firstVariant;
+      }
+      const bucket = hashString(`${options.id}:${input.assistantId}:${input.session.id}`) % totalWeight;
+      let cursor = 0;
+      for (const variant of options.variants) {
+        cursor += Math.max(0, variant.weight ?? 1);
+        if (bucket < cursor) {
+          return variant;
+        }
+      }
+      return firstVariant;
+    },
+    variants: options.variants
+  };
+};
+var createVoiceAssistant = (options) => {
+  const ops = mergeOps(resolvePresetOps(options.artifactPlan), options.ops);
+  const artifactPlanName = resolveArtifactPlanName(options.artifactPlan);
+  let agent;
+  const baseModelOptions = "model" in options && options.model ? {
+    maxToolRounds: options.maxToolRounds,
+    model: options.model,
+    system: options.system,
+    tools: options.tools
+  } : undefined;
+  if ("agent" in options && options.agent) {
+    agent = options.agent;
+  } else if ("agents" in options && options.agents) {
+    agent = createVoiceAgentSquad({
+      agents: options.agents,
+      defaultAgentId: options.defaultAgentId,
+      id: options.id,
+      maxHandoffsPerTurn: options.maxHandoffsPerTurn,
+      selectAgent: options.selectAgent,
+      trace: options.trace
+    });
+  } else {
+    agent = createVoiceAgent({
+      id: options.id,
+      maxToolRounds: options.maxToolRounds,
+      model: options.model,
+      system: options.system,
+      trace: options.trace,
+      tools: options.tools
+    });
+  }
+  const onTurn = async (input) => {
+    const guardrailInput = {
+      ...input,
+      assistantId: options.id
+    };
+    const blocked = await options.guardrails?.beforeTurn?.(guardrailInput);
+    if (blocked) {
+      await appendAssistantTrace({
+        assistantId: options.id,
+        event: {
+          action: "blocked",
+          artifactPlan: artifactPlanName,
+          outcome: resolveOutcome(blocked)
+        },
+        session: input.session,
+        trace: options.trace,
+        turnId: input.turn.id,
+        type: "assistant.guardrail"
+      });
+      await appendAssistantTrace({
+        assistantId: options.id,
+        event: {
+          artifactPlan: artifactPlanName,
+          blocked: true,
+          experimentId: options.experiment?.id,
+          outcome: resolveOutcome(blocked)
+        },
+        session: input.session,
+        trace: options.trace,
+        turnId: input.turn.id,
+        type: "assistant.run"
+      });
+      return blocked;
+    }
+    const startedAt = Date.now();
+    const variant = options.experiment?.resolve({
+      assistantId: options.id,
+      context: input.context,
+      session: input.session,
+      turnId: input.turn.id
+    });
+    const runner = variant && baseModelOptions ? createVoiceAgent({
+      id: `${options.id}:${variant.id}`,
+      maxToolRounds: variant.maxToolRounds ?? baseModelOptions.maxToolRounds,
+      model: variant.model ?? baseModelOptions.model,
+      system: variant.system ?? baseModelOptions.system,
+      trace: options.trace,
+      tools: variant.tools ?? baseModelOptions.tools
+    }) : agent;
+    const runResult = await runner.run(input) ?? {};
+    const result = runResult;
+    const guarded = await options.guardrails?.afterTurn?.({
+      ...guardrailInput,
+      result
+    });
+    const finalResult = guarded ?? result;
+    if (guarded) {
+      await appendAssistantTrace({
+        assistantId: options.id,
+        event: {
+          action: "rewritten",
+          artifactPlan: artifactPlanName,
+          experimentId: options.experiment?.id,
+          outcome: resolveOutcome(finalResult),
+          variantId: variant?.id
+        },
+        session: input.session,
+        trace: options.trace,
+        turnId: input.turn.id,
+        type: "assistant.guardrail"
+      });
+    }
+    await appendAssistantTrace({
+      assistantId: options.id,
+      event: {
+        artifactPlan: artifactPlanName,
+        blocked: false,
+        elapsedMs: Date.now() - startedAt,
+        escalated: Boolean(finalResult.escalate),
+        experimentId: options.experiment?.id,
+        outcome: resolveOutcome(finalResult),
+        toolNames: result.toolResults?.map((tool) => tool.toolName) ?? [],
+        transferred: Boolean(finalResult.transfer),
+        variantId: variant?.id
+      },
+      session: input.session,
+      trace: options.trace,
+      turnId: input.turn.id,
+      type: "assistant.run"
+    });
+    return finalResult;
+  };
+  return {
+    agent,
+    id: options.id,
+    onTurn,
+    ops,
+    route: (overrides) => ({
+      ...overrides,
+      onComplete: overrides.onComplete ?? (() => {
+        return;
+      }),
+      onTurn
+    })
+  };
+};
+var summarizeVoiceAssistantRuns = async (input) => {
+  const events = Array.isArray(input) ? input : input.events ?? await input.store?.list() ?? [];
+  const assistantRuns = events.filter((event) => event.type === "assistant.run");
+  const guardrails = events.filter((event) => event.type === "assistant.guardrail");
+  const byAssistant = new Map;
+  const getSummary = (assistantId) => {
+    let summary = byAssistant.get(assistantId);
+    if (!summary) {
+      summary = {
+        assistantId,
+        artifactPlans: {},
+        blockedGuardrailCount: 0,
+        elapsedCount: 0,
+        elapsedTotal: 0,
+        escalationCount: 0,
+        experiments: {},
+        guardrailCount: 0,
+        outcomes: {},
+        runCount: 0,
+        sessionIds: new Set,
+        sessions: 0,
+        toolCalls: {},
+        transferCount: 0,
+        variants: {}
+      };
+      byAssistant.set(assistantId, summary);
+    }
+    return summary;
+  };
+  for (const event of assistantRuns) {
+    const assistantId = typeof event.payload.assistantId === "string" ? event.payload.assistantId : "unknown";
+    const summary = getSummary(assistantId);
+    summary.runCount += 1;
+    summary.sessionIds.add(event.sessionId);
+    if (typeof event.payload.artifactPlan === "string") {
+      increment(summary.artifactPlans, event.payload.artifactPlan);
+    }
+    if (typeof event.payload.experimentId === "string") {
+      increment(summary.experiments, event.payload.experimentId);
+    }
+    if (typeof event.payload.variantId === "string") {
+      increment(summary.variants, event.payload.variantId);
+    }
+    if (typeof event.payload.outcome === "string") {
+      increment(summary.outcomes, event.payload.outcome);
+    }
+    if (event.payload.escalated === true) {
+      summary.escalationCount += 1;
+    }
+    if (event.payload.transferred === true) {
+      summary.transferCount += 1;
+    }
+    if (event.payload.blocked === true) {
+      summary.blockedGuardrailCount += 1;
+    }
+    if (typeof event.payload.elapsedMs === "number") {
+      summary.elapsedCount += 1;
+      summary.elapsedTotal += event.payload.elapsedMs;
+    }
+    if (Array.isArray(event.payload.toolNames)) {
+      for (const toolName of event.payload.toolNames) {
+        if (typeof toolName === "string") {
+          increment(summary.toolCalls, toolName);
+        }
+      }
+    }
+  }
+  for (const event of guardrails) {
+    const assistantId = typeof event.payload.assistantId === "string" ? event.payload.assistantId : "unknown";
+    const summary = getSummary(assistantId);
+    summary.guardrailCount += 1;
+  }
+  const assistants = [...byAssistant.values()].map(({ elapsedCount, elapsedTotal, sessionIds, ...summary }) => ({
+    ...summary,
+    averageElapsedMs: elapsedCount > 0 ? Math.round(elapsedTotal / elapsedCount) : undefined,
+    sessions: sessionIds.size
+  }));
+  return {
+    assistants: assistants.sort((left, right) => left.assistantId.localeCompare(right.assistantId)),
+    totalRuns: assistantRuns.length
+  };
+};
 // src/fileStore.ts
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "fs/promises";
 import { join } from "path";
@@ -7987,230 +8548,6 @@ var resolveVoiceOpsPreset = (name, overrides = {}) => {
     taskPolicies: mergePolicies(preset.taskPolicies, overrides.taskPolicies)
   };
 };
-// src/outcomeRecipes.ts
-var RECIPE_DEFAULTS = {
-  "appointment-booking": {
-    completedAction: "Verify appointment details, confirm calendar state, and send any required confirmation.",
-    completedDescription: "The call completed an appointment-booking flow and should be checked against the scheduling system.",
-    completedKind: "appointment-booking",
-    completedTitle: "Confirm booked appointment",
-    defaultCompletedCreatesTask: true,
-    defaultDueInMs: 30 * 60000,
-    defaultPriority: "normal",
-    defaultQueue: "appointments",
-    description: "Creates appointment confirmation work for completed calls and callback/retry work for missed booking attempts.",
-    escalationQueue: "appointments-escalations"
-  },
-  "lead-qualification": {
-    completedAction: "Review qualification signals, update CRM fields, and route the lead to the right owner.",
-    completedDescription: "The call completed a lead-qualification flow and should be reviewed for sales follow-up.",
-    completedKind: "lead-qualification",
-    completedTitle: "Review qualified lead",
-    defaultCompletedCreatesTask: true,
-    defaultDueInMs: 15 * 60000,
-    defaultPriority: "high",
-    defaultQueue: "sales-leads",
-    description: "Creates sales follow-up work for completed qualification calls and fast callbacks for missed leads.",
-    escalationQueue: "sales-escalations"
-  },
-  "support-triage": {
-    completedAction: "Review the triage result, confirm the support category, and route any unresolved issue.",
-    completedDescription: "The call completed support triage and may need queue routing or human follow-up.",
-    completedKind: "support-triage",
-    completedTitle: "Review support triage",
-    defaultCompletedCreatesTask: true,
-    defaultDueInMs: 20 * 60000,
-    defaultPriority: "normal",
-    defaultQueue: "support-triage",
-    description: "Creates support triage work for completed calls and urgent escalation/callback work for unresolved callers.",
-    escalationQueue: "support-escalations"
-  },
-  "voicemail-callback": {
-    completedAction: "No callback is required for completed calls.",
-    completedDescription: "The call completed without requiring voicemail follow-up.",
-    completedKind: "callback",
-    completedTitle: "Completed call",
-    defaultCompletedCreatesTask: false,
-    defaultDueInMs: 15 * 60000,
-    defaultPriority: "high",
-    defaultQueue: "callbacks",
-    description: "Creates callback work for voicemail, no-answer, failed, or escalated calls while ignoring completed calls.",
-    escalationQueue: "callback-escalations"
-  },
-  "warm-transfer": {
-    completedAction: "Confirm the handoff target received the caller context and close the transfer loop.",
-    completedDescription: "The call is part of a warm-transfer flow and should be verified downstream.",
-    completedKind: "transfer-check",
-    completedTitle: "Verify warm transfer",
-    defaultCompletedCreatesTask: false,
-    defaultDueInMs: 10 * 60000,
-    defaultPriority: "normal",
-    defaultQueue: "transfer-verification",
-    description: "Creates transfer verification work for transferred calls and escalation work when the handoff fails.",
-    escalationQueue: "transfer-escalations"
-  }
-};
-var buildRecipeTask = (input) => {
-  const createdAt = input.review.generatedAt ?? Date.now();
-  const queue = input.options.queue ?? input.defaults.defaultQueue;
-  const target = input.options.target ?? input.review.postCall?.target;
-  const common = {
-    assignee: input.options.assignee,
-    createdAt,
-    history: [
-      {
-        actor: "system",
-        at: createdAt,
-        detail: input.review.postCall?.summary,
-        type: "created"
-      }
-    ],
-    id: `${input.review.id}:${input.defaults.completedKind}`,
-    intakeId: input.review.id,
-    outcome: input.review.summary.outcome,
-    priority: input.options.priority ?? input.defaults.defaultPriority,
-    queue,
-    reviewId: input.review.id,
-    status: "open",
-    target,
-    updatedAt: createdAt
-  };
-  switch (input.disposition) {
-    case "completed":
-      if (!(input.options.completedCreatesTask ?? input.defaults.defaultCompletedCreatesTask)) {
-        return null;
-      }
-      return {
-        ...common,
-        description: input.defaults.completedDescription,
-        kind: input.defaults.completedKind,
-        recommendedAction: input.defaults.completedAction,
-        title: target ? `${input.defaults.completedTitle}: ${target}` : input.defaults.completedTitle
-      };
-    case "voicemail":
-      return {
-        ...common,
-        description: input.review.postCall?.summary ?? "The caller reached voicemail and needs a callback.",
-        id: `${input.review.id}:callback`,
-        kind: "callback",
-        recommendedAction: input.review.postCall?.recommendedAction ?? "Call the customer back and continue the original flow.",
-        title: target ? `Call back ${target}` : "Call back voicemail lead"
-      };
-    case "no-answer":
-      return {
-        ...common,
-        description: input.review.postCall?.summary ?? "The call did not reach a live respondent and should be retried.",
-        id: `${input.review.id}:retry`,
-        kind: "callback",
-        recommendedAction: input.review.postCall?.recommendedAction ?? "Retry the call or schedule a callback.",
-        title: "Retry no-answer call"
-      };
-    case "transferred":
-      return {
-        ...common,
-        description: input.review.postCall?.summary ?? "The call was transferred and should be verified downstream.",
-        id: `${input.review.id}:transfer-check`,
-        kind: "transfer-check",
-        recommendedAction: input.review.postCall?.recommendedAction ?? "Confirm the receiving team got the caller context.",
-        title: target ? `Verify transfer to ${target}` : "Verify call transfer"
-      };
-    case "escalated":
-      return {
-        ...common,
-        description: input.review.postCall?.summary ?? "The call escalated and needs human review.",
-        id: `${input.review.id}:escalation`,
-        kind: "escalation",
-        priority: "urgent",
-        queue: input.options.escalationQueue ?? input.defaults.escalationQueue,
-        assignee: input.options.escalationAssignee ?? input.options.assignee,
-        recommendedAction: input.review.postCall?.recommendedAction ?? "Review the escalated call and respond immediately.",
-        title: "Review escalated call"
-      };
-    case "failed":
-    case "closed":
-      return {
-        ...common,
-        description: input.review.postCall?.summary ?? "The call ended before successful completion and needs review.",
-        id: `${input.review.id}:retry-review`,
-        kind: "retry-review",
-        priority: "high",
-        recommendedAction: input.review.postCall?.recommendedAction ?? "Inspect the call and decide whether to retry, escalate, or close.",
-        title: "Inspect incomplete call"
-      };
-    default:
-      return null;
-  }
-};
-var resolveVoiceOutcomeRecipe = (name, options = {}) => {
-  const defaults = RECIPE_DEFAULTS[name];
-  const taskPolicies = {
-    completed: {
-      assignee: options.assignee,
-      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
-      name: `${name}-completed`,
-      priority: options.priority ?? defaults.defaultPriority,
-      queue: options.queue ?? defaults.defaultQueue
-    },
-    escalated: {
-      assignee: options.escalationAssignee ?? options.assignee,
-      dueInMs: Math.min(options.dueInMs ?? defaults.defaultDueInMs, 10 * 60000),
-      name: `${name}-escalation`,
-      priority: "urgent",
-      queue: options.escalationQueue ?? defaults.escalationQueue
-    },
-    failed: {
-      assignee: options.assignee,
-      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
-      name: `${name}-failed-review`,
-      priority: "high",
-      queue: options.queue ?? defaults.defaultQueue
-    },
-    "no-answer": {
-      assignee: options.assignee,
-      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
-      name: `${name}-no-answer`,
-      priority: options.priority ?? defaults.defaultPriority,
-      queue: options.queue ?? defaults.defaultQueue
-    },
-    transferred: {
-      assignee: options.assignee,
-      dueInMs: Math.min(options.dueInMs ?? defaults.defaultDueInMs, 20 * 60000),
-      name: `${name}-transfer-check`,
-      priority: options.priority ?? defaults.defaultPriority,
-      queue: name === "warm-transfer" ? options.queue ?? defaults.defaultQueue : "transfer-verification"
-    },
-    voicemail: {
-      assignee: options.assignee,
-      dueInMs: options.dueInMs ?? defaults.defaultDueInMs,
-      name: `${name}-voicemail`,
-      priority: options.priority ?? defaults.defaultPriority,
-      queue: options.queue ?? defaults.defaultQueue
-    }
-  };
-  const taskAssignmentRules = [
-    {
-      assign: options.escalationAssignee ?? options.assignee,
-      description: `Route urgent ${name} work to the escalation lane.`,
-      name: `${name}-urgent-routing`,
-      queue: options.escalationQueue ?? defaults.escalationQueue,
-      when: {
-        priority: "urgent"
-      }
-    }
-  ].filter((rule) => rule.assign || rule.queue);
-  return {
-    createTaskFromReview: ({ disposition, review }) => buildRecipeTask({
-      defaults,
-      disposition,
-      options,
-      review
-    }),
-    description: defaults.description,
-    name,
-    taskAssignmentRules,
-    taskPolicies
-  };
-};
 // src/correction.ts
 var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 var buildAliasMatcher = (alias) => new RegExp(`(?<![\\p{L}\\p{N}'])${escapeRegExp(alias)}(?![\\p{L}\\p{N}'])`, "giu");
@@ -8990,6 +9327,7 @@ export {
   summarizeVoiceOpsTaskQueue,
   summarizeVoiceOpsTaskAnalytics,
   summarizeVoiceIntegrationEvents,
+  summarizeVoiceAssistantRuns,
   startVoiceOpsTask,
   shapeTelephonyAssistantText,
   selectVoiceTraceEventsForPrune,
@@ -9097,11 +9435,13 @@ export {
   createVoiceFileExternalObjectMapStore,
   createVoiceExternalObjectMapId,
   createVoiceExternalObjectMap,
+  createVoiceExperiment,
   createVoiceCallReviewRecorder,
   createVoiceCallReviewFromSession,
   createVoiceCallReviewFromLiveTelephonyReport,
   createVoiceCallCompletedEvent,
   createVoiceCRMActivitySink,
+  createVoiceAssistant,
   createVoiceAgentTool,
   createVoiceAgentSquad,
   createVoiceAgent,

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-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 VoiceTraceEventType = 'assistant.guardrail' | 'assistant.run' | '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;

package/package.json

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