@absolutejs/voice 0.0.22-beta.245 → 0.0.22-beta.246

package/dist/guardrails.d.ts

@@ -1,5 +1,8 @@
 import { Elysia } from 'elysia';
+import type { VoiceAgentTool } from './agent';
 import type { VoiceTraceEventStore } from './trace';
+import type { VoiceOnTurnObjectHandler, VoiceRouteResult, VoiceSessionRecord } from './types';
+import type { VoiceAssistantGuardrails } from './assistant';
 export type VoiceGuardrailStage = 'assistant-output' | 'handoff' | 'model-input' | 'tool-input' | 'tool-output' | 'transcript';
 export type VoiceGuardrailSeverity = 'block' | 'warn';
 export type VoiceGuardrailStatus = 'blocked' | 'pass' | 'warn';
@@ -68,12 +71,29 @@ export type VoiceGuardrailRoutesOptions = {
     source?: ((input: VoiceGuardrailEvaluationInput) => Promise<VoiceGuardrailDecision | VoiceGuardrailReport> | VoiceGuardrailDecision | VoiceGuardrailReport) | VoiceGuardrailDecision | VoiceGuardrailReport;
     trace?: VoiceTraceEventStore;
 };
+export type VoiceGuardrailRuntimeBlockInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Parameters<VoiceOnTurnObjectHandler<TContext, TSession, TResult>>[0] & {
+    decision: VoiceGuardrailDecision;
+    stage: VoiceGuardrailStage;
+};
+export type VoiceGuardrailRuntimeOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    blockResult?: (input: VoiceGuardrailRuntimeBlockInput<TContext, TSession, TResult>) => Promise<VoiceRouteResult<TResult>> | VoiceRouteResult<TResult>;
+    name?: string;
+    policies: VoiceGuardrailPolicy[];
+    trace?: VoiceTraceEventStore;
+};
+export type VoiceGuardrailRuntime<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    assistantGuardrails: VoiceAssistantGuardrails<TContext, TSession, TResult>;
+    evaluate: (input: VoiceGuardrailEvaluationInput) => Promise<VoiceGuardrailDecision>;
+    wrapTool: <TArgs extends Record<string, unknown>, TToolResult>(tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TResult>) => VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TResult>;
+    wrapTools: (tools: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>) => Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
+};
 export declare const evaluateVoiceGuardrailPolicy: (policy: VoiceGuardrailPolicy, input: VoiceGuardrailEvaluationInput) => Promise<VoiceGuardrailDecision>;
 export declare const buildVoiceGuardrailReport: (input?: {
     decisions: VoiceGuardrailDecision[];
     policies?: VoiceGuardrailPolicy[];
 }) => VoiceGuardrailReport;
 export declare const createVoiceGuardrailPolicy: (policy: VoiceGuardrailPolicy) => VoiceGuardrailPolicy;
+export declare const createVoiceGuardrailRuntime: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceGuardrailRuntimeOptions<TContext, TSession, TResult>) => VoiceGuardrailRuntime<TContext, TSession, TResult>;
 export declare const voiceGuardrailPolicyPresets: {
     supportSafeDefaults: VoiceGuardrailPolicy;
 };

package/dist/index.d.ts

@@ -84,7 +84,7 @@ export { createVoiceOpsRuntime } from './opsRuntime';
 export { resolveVoiceOpsPreset } from './opsPresets';
 export { resolveVoiceOutcomeRecipe } from './outcomeRecipes';
 export { buildVoicePostCallAnalysisReport, createVoicePostCallAnalysisRoutes, renderVoicePostCallAnalysisMarkdown } from './postCallAnalysis';
-export { buildVoiceGuardrailReport, createVoiceGuardrailPolicy, createVoiceGuardrailRoutes, evaluateVoiceGuardrailPolicy, renderVoiceGuardrailMarkdown, voiceGuardrailPolicyPresets } from './guardrails';
+export { buildVoiceGuardrailReport, createVoiceGuardrailPolicy, createVoiceGuardrailRuntime, createVoiceGuardrailRoutes, evaluateVoiceGuardrailPolicy, renderVoiceGuardrailMarkdown, voiceGuardrailPolicyPresets } from './guardrails';
 export { createId, createVoiceSessionRecord } from './store';
 export { createVoiceSTTRoutingCorrectionHandler, resolveVoiceSTTRoutingStrategy } from './routing';
 export { applyRiskTieredPhraseHintCorrections, applyPhraseHintCorrections, createDomainLexicon, createDomainPhraseHints, createPhraseHintCorrectionHandler, createRiskyTurnCorrectionHandler } from './correction';
@@ -138,7 +138,7 @@ export type { VoiceOpsRuntime, VoiceOpsRuntimeConfig, VoiceOpsRuntimeSummary, Vo
 export type { VoiceOpsPresetName, VoiceOpsPresetOverrides, VoiceResolvedOpsPreset } from './opsPresets';
 export type { VoiceOutcomeRecipe, VoiceOutcomeRecipeName, VoiceOutcomeRecipeOptions } from './outcomeRecipes';
 export type { VoicePostCallAnalysisFieldRequirement, VoicePostCallAnalysisFieldResult, VoicePostCallAnalysisIssue, VoicePostCallAnalysisIssueCode, VoicePostCallAnalysisOptions, VoicePostCallAnalysisReport, VoicePostCallAnalysisRoutesOptions, VoicePostCallAnalysisStatus } from './postCallAnalysis';
-export type { VoiceGuardrailDecision, VoiceGuardrailEvaluationInput, VoiceGuardrailFinding, VoiceGuardrailPolicy, VoiceGuardrailReport, VoiceGuardrailRoutesOptions, VoiceGuardrailRule, VoiceGuardrailSeverity, VoiceGuardrailStage, VoiceGuardrailStatus } from './guardrails';
+export type { VoiceGuardrailDecision, VoiceGuardrailEvaluationInput, VoiceGuardrailFinding, VoiceGuardrailPolicy, VoiceGuardrailReport, VoiceGuardrailRuntime, VoiceGuardrailRuntimeBlockInput, VoiceGuardrailRuntimeOptions, VoiceGuardrailRoutesOptions, VoiceGuardrailRule, VoiceGuardrailSeverity, VoiceGuardrailStage, VoiceGuardrailStatus } from './guardrails';
 export type { VoiceCRMActivitySinkOptions, VoiceHubSpotTaskSinkOptions, VoiceHubSpotTaskUpdateSinkOptions, VoiceHelpdeskTicketSinkOptions, VoiceIntegrationHTTPSinkOptions, VoiceIntegrationSink, VoiceIntegrationSinkDeliveryResult, VoiceLinearIssueSinkOptions, VoiceLinearIssueUpdateSinkOptions, VoiceZendeskTicketSinkOptions, VoiceZendeskTicketUpdateSinkOptions } from './opsSinks';
 export type { VoiceOpsWebhookEnvelope, VoiceOpsWebhookEntity, VoiceOpsWebhookLinkResolver, VoiceOpsWebhookReceiverRoutesOptions, VoiceOpsWebhookSinkOptions, VoiceOpsWebhookVerificationResult } from './opsWebhook';
 export type { VoiceHandoffDelivery, VoiceHandoffDeliveryRecord, VoiceHandoffDeliveryRecordInput, VoiceHandoffFanoutResult, VoiceQueuedHandoffDeliveryOptions, VoiceTwilioRedirectHandoffAdapterOptions, VoiceWebhookHandoffAdapterOptions } from './handoff';

package/dist/index.js

@@ -29015,6 +29015,158 @@ var buildVoiceGuardrailReport = (input = { decisions: [] }) => {
   };
 };
 var createVoiceGuardrailPolicy = (policy) => policy;
+var appendGuardrailTrace = async (trace, decision, metadata) => {
+  await trace?.append({
+    at: decision.checkedAt,
+    payload: {
+      allowed: decision.allowed,
+      findingCount: decision.findings.length,
+      findings: decision.findings,
+      metadata,
+      redactedContent: decision.redactedContent,
+      stage: decision.stage,
+      status: decision.status
+    },
+    sessionId: decision.sessionId ?? "guardrail-check",
+    turnId: decision.turnId,
+    type: "assistant.guardrail"
+  });
+};
+var defaultGuardrailBlockResult = (reason) => ({
+  assistantText: "I cannot safely complete that in the automated flow. I am routing this to a human specialist.",
+  escalate: {
+    metadata: {
+      guardrail: true
+    },
+    reason
+  }
+});
+var createVoiceGuardrailRuntime = (options) => {
+  const evaluate = async (input) => {
+    const decisions = await Promise.all(options.policies.map((policy) => evaluateVoiceGuardrailPolicy(policy, input)));
+    await Promise.all(decisions.map((decision) => appendGuardrailTrace(options.trace, decision, input.metadata)));
+    return decisions.find((decision) => !decision.allowed) ?? decisions[0];
+  };
+  const blockResult = async (input) => options.blockResult?.(input) ?? defaultGuardrailBlockResult(`guardrail-blocked-${input.stage}`);
+  const assistantGuardrails = {
+    beforeTurn: async (input) => {
+      const transcriptDecision = await evaluate({
+        content: input.turn.text,
+        metadata: {
+          runtime: options.name,
+          surface: "live-transcript"
+        },
+        sessionId: input.session.id,
+        stage: "transcript",
+        turnId: input.turn.id
+      });
+      if (!transcriptDecision.allowed) {
+        return blockResult({
+          ...input,
+          decision: transcriptDecision,
+          stage: "transcript"
+        });
+      }
+      const modelInputDecision = await evaluate({
+        content: JSON.stringify({
+          scenarioId: input.session.scenarioId,
+          turn: input.turn.text
+        }),
+        metadata: {
+          runtime: options.name,
+          surface: "live-model-input"
+        },
+        sessionId: input.session.id,
+        stage: "model-input",
+        turnId: input.turn.id
+      });
+      if (!modelInputDecision.allowed) {
+        return blockResult({
+          ...input,
+          decision: modelInputDecision,
+          stage: "model-input"
+        });
+      }
+      return;
+    },
+    afterTurn: async (input) => {
+      if (!input.result.assistantText) {
+        return;
+      }
+      const decision = await evaluate({
+        content: input.result.assistantText,
+        metadata: {
+          runtime: options.name,
+          surface: "live-assistant-output"
+        },
+        sessionId: input.session.id,
+        stage: "assistant-output",
+        turnId: input.turn.id
+      });
+      if (!decision.allowed) {
+        return blockResult({
+          ...input,
+          decision,
+          stage: "assistant-output"
+        });
+      }
+      if (typeof decision.redactedContent === "string" && decision.redactedContent !== input.result.assistantText) {
+        return {
+          ...input.result,
+          assistantText: decision.redactedContent
+        };
+      }
+      return;
+    }
+  };
+  const wrapTool = (tool) => ({
+    ...tool,
+    execute: async (input) => {
+      const inputDecision = await evaluate({
+        content: JSON.stringify({
+          args: input.args,
+          toolName: tool.name
+        }),
+        metadata: {
+          runtime: options.name,
+          surface: "live-tool-input",
+          toolName: tool.name
+        },
+        sessionId: input.session.id,
+        stage: "tool-input",
+        turnId: input.turn.id
+      });
+      if (!inputDecision.allowed) {
+        throw new Error(`Guardrail blocked tool input for ${tool.name}.`);
+      }
+      const result = await tool.execute(input);
+      const outputDecision = await evaluate({
+        content: JSON.stringify({
+          result,
+          toolName: tool.name
+        }),
+        metadata: {
+          runtime: options.name,
+          surface: "live-tool-output",
+          toolName: tool.name
+        },
+        sessionId: input.session.id,
+        stage: "tool-output",
+        turnId: input.turn.id
+      });
+      if (!outputDecision.allowed) {
+        throw new Error(`Guardrail blocked tool output for ${tool.name}.`);
+      }
+      return result;
+    }
+  });
+  return {
+    assistantGuardrails,
+    evaluate,
+    wrapTool,
+    wrapTools: (tools) => tools.map((tool) => wrapTool(tool))
+  };
+};
 var voiceGuardrailPolicyPresets = {
   supportSafeDefaults: createVoiceGuardrailPolicy({
     id: "support-safe-defaults",
@@ -29864,6 +30016,7 @@ export {
   createVoiceHandoffDeliveryWorkerLoop,
   createVoiceHandoffDeliveryWorker,
   createVoiceHandoffDeliveryRecord,
+  createVoiceGuardrailRuntime,
   createVoiceGuardrailRoutes,
   createVoiceGuardrailPolicy,
   createVoiceFileTraceSinkDeliveryStore,

package/package.json

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