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

package/dist/assistant.d.ts

@@ -1,6 +1,7 @@
 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>;
@@ -94,6 +95,29 @@ export type VoiceAssistant<TContext = unknown, TSession extends VoiceSessionReco
         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,5 +1,5 @@
 export { voice } from './plugin';
-export { createVoiceAssistant, createVoiceExperiment } from './assistant';
+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';
@@ -22,7 +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, VoiceAssistantVariant } from './assistant';
+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

@@ -5603,6 +5603,47 @@ var hashString = (value) => {
   }
   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) {
@@ -5671,6 +5712,7 @@ var createVoiceExperiment = (options) => {
 };
 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,
@@ -5706,8 +5748,34 @@ var createVoiceAssistant = (options) => {
     };
     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,
@@ -5722,12 +5790,48 @@ var createVoiceAssistant = (options) => {
       trace: options.trace,
       tools: variant.tools ?? baseModelOptions.tools
     }) : agent;
-    const result = await runner.run(input) ?? {};
+    const runResult = await runner.run(input) ?? {};
+    const result = runResult;
     const guarded = await options.guardrails?.afterTurn?.({
       ...guardrailInput,
       result
     });
-    return guarded ?? 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,
@@ -5743,6 +5847,88 @@ var createVoiceAssistant = (options) => {
     })
   };
 };
+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";
@@ -9141,6 +9327,7 @@ export {
   summarizeVoiceOpsTaskQueue,
   summarizeVoiceOpsTaskAnalytics,
   summarizeVoiceIntegrationEvents,
+  summarizeVoiceAssistantRuns,
   startVoiceOpsTask,
   shapeTelephonyAssistantText,
   selectVoiceTraceEventsForPrune,

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.2",
+	"version": "0.0.22-beta.3",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",