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

package/README.md

@@ -37,7 +37,7 @@ These are the primitive-first paths a Vapi-style buyer usually needs. Each path
 | Phone voice assistant | `createVoicePhoneAgent(...)` | carrier matrix, setup instructions, phone smoke contract, production readiness, operations record | phone setup HTML/JSON, smoke HTML/JSON, framework status UI |
 | Multi-specialist support flow | `createVoiceAgentSquad(...)` | squad contract, handoff traces, context traces, operations record | Agent Squad status hooks/composables/services/widgets |
 | Business actions and tools | `createVoiceAgentTool(...)` plus agent tool runtime | tool contracts, audit events, integration events, outcome contracts | operations record, action center, contract routes |
-| Guardrails and policy checks | `createVoiceGuardrailPolicy(...)` plus `createVoiceGuardrailRoutes(...)` | blocking/warning decisions, redacted content, `assistant.guardrail` trace events | guardrail JSON/Markdown routes and operations record traces |
+| Guardrails and policy checks | `createVoiceGuardrailPolicy(...)`, `createVoiceGuardrailRuntime(...)`, and `createVoiceGuardrailRoutes(...)` | live assistant/tool enforcement, blocking/warning decisions, redacted content, `assistant.guardrail` trace events | guardrail JSON/Markdown routes and operations record traces |
 | Provider routing and fallback | provider routers, health checks, simulation controls | provider contract matrix, provider-stage traces, latency SLO reports | provider contract hooks/composables/services/widgets |
 | Production operations | ops status, ops recovery, production readiness, delivery runtime | readiness gates, recovery report, incident Markdown, delivery queues | ops action center, delivery runtime UI, operations record |
 | Outbound campaigns | `createVoiceCampaignRoutes(...)` | recipient validation, consent/dedupe, carrier dry-run, campaign readiness | campaign routes and operations-record-linked attempt proof |
@@ -116,14 +116,33 @@ app.use(
 
 ## Guardrails
 
-Use `createVoiceGuardrailRoutes(...)` when you need code-owned policy checks for what an agent may say, what tool payloads may contain, or which transcript content should warn/redact before downstream workflow. The primitive does not force a moderation vendor or hosted dashboard; it returns JSON/Markdown proof and can emit `assistant.guardrail` trace events.
+Use `createVoiceGuardrailRuntime(...)` when you need code-owned live enforcement for what an agent may say, what tool payloads may contain, or which transcript content should warn/redact before downstream workflow. Use `createVoiceGuardrailRoutes(...)` beside it when you also want JSON/Markdown proof. The primitive does not force a moderation vendor or hosted dashboard; it emits `assistant.guardrail` trace events from the runtime and route surfaces.
 
 ```ts
 import {
+	createVoiceGuardrailRuntime,
 	createVoiceGuardrailRoutes,
 	voiceGuardrailPolicyPresets
 } from '@absolutejs/voice';
 
+const guardrails = createVoiceGuardrailRuntime({
+	blockResult: ({ decision }) => ({
+		assistantText: 'I need to route this to a human specialist.',
+		escalate: {
+			reason: `guardrail-blocked-${decision.stage}`
+		}
+	}),
+	policies: [voiceGuardrailPolicyPresets.supportSafeDefaults],
+	trace: runtime.traces
+});
+
+const assistant = createVoiceAssistant({
+	guardrails: guardrails.assistantGuardrails,
+	id: 'support',
+	model,
+	tools: guardrails.wrapTools([lookupCustomerTool, createTicketTool])
+});
+
 app.use(
 	createVoiceGuardrailRoutes({
 		path: '/api/voice/guardrails',

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.247",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",