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

package/README.md

@@ -37,6 +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 |
 | 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 |
@@ -113,6 +114,25 @@ 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.
+
+```ts
+import {
+	createVoiceGuardrailRoutes,
+	voiceGuardrailPolicyPresets
+} from '@absolutejs/voice';
+
+app.use(
+	createVoiceGuardrailRoutes({
+		path: '/api/voice/guardrails',
+		policies: [voiceGuardrailPolicyPresets.supportSafeDefaults],
+		trace: runtime.traces
+	})
+);
+```
+
 ## Use-Case Recipe: Support Triage
 
 Use this path when you want a Vapi-style support assistant that can answer web or phone calls, look up customer context, route billing issues to a specialist, create follow-up work, and leave one debuggable call record. It is a recipe over primitives, not a support app kit.

package/dist/guardrails.d.ts

@@ -0,0 +1,108 @@
+import { Elysia } from 'elysia';
+import type { VoiceTraceEventStore } from './trace';
+export type VoiceGuardrailStage = 'assistant-output' | 'handoff' | 'model-input' | 'tool-input' | 'tool-output' | 'transcript';
+export type VoiceGuardrailSeverity = 'block' | 'warn';
+export type VoiceGuardrailStatus = 'blocked' | 'pass' | 'warn';
+export type VoiceGuardrailRule = {
+    action?: VoiceGuardrailSeverity;
+    description?: string;
+    id: string;
+    label?: string;
+    match: RegExp | string | ((input: VoiceGuardrailEvaluationInput) => boolean | Promise<boolean>);
+    redactWith?: string;
+    stages?: VoiceGuardrailStage[];
+};
+export type VoiceGuardrailEvaluationInput = {
+    content?: unknown;
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+    stage: VoiceGuardrailStage;
+    turnId?: string;
+};
+export type VoiceGuardrailFinding = {
+    action: VoiceGuardrailSeverity;
+    description?: string;
+    label: string;
+    ruleId: string;
+    stage: VoiceGuardrailStage;
+};
+export type VoiceGuardrailDecision = {
+    allowed: boolean;
+    checkedAt: number;
+    content?: unknown;
+    findings: VoiceGuardrailFinding[];
+    redactedContent?: unknown;
+    sessionId?: string;
+    stage: VoiceGuardrailStage;
+    status: VoiceGuardrailStatus;
+    turnId?: string;
+};
+export type VoiceGuardrailPolicy = {
+    defaultAction?: VoiceGuardrailSeverity;
+    id: string;
+    label?: string;
+    rules: VoiceGuardrailRule[];
+};
+export type VoiceGuardrailReport = {
+    checkedAt: number;
+    decisions: VoiceGuardrailDecision[];
+    failed: number;
+    policies: Array<{
+        id: string;
+        label?: string;
+        rules: number;
+    }>;
+    status: 'fail' | 'pass' | 'warn';
+    summary: {
+        blocked: number;
+        passed: number;
+        warned: number;
+    };
+    total: number;
+};
+export type VoiceGuardrailRoutesOptions = {
+    headers?: HeadersInit;
+    name?: string;
+    path?: string;
+    policies?: VoiceGuardrailPolicy[];
+    source?: ((input: VoiceGuardrailEvaluationInput) => Promise<VoiceGuardrailDecision | VoiceGuardrailReport> | VoiceGuardrailDecision | VoiceGuardrailReport) | VoiceGuardrailDecision | VoiceGuardrailReport;
+    trace?: VoiceTraceEventStore;
+};
+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 voiceGuardrailPolicyPresets: {
+    supportSafeDefaults: VoiceGuardrailPolicy;
+};
+export declare const renderVoiceGuardrailMarkdown: (report: VoiceGuardrailReport) => string;
+export declare const createVoiceGuardrailRoutes: (options?: VoiceGuardrailRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/index.d.ts

@@ -84,6 +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 { createId, createVoiceSessionRecord } from './store';
 export { createVoiceSTTRoutingCorrectionHandler, resolveVoiceSTTRoutingStrategy } from './routing';
 export { applyRiskTieredPhraseHintCorrections, applyPhraseHintCorrections, createDomainLexicon, createDomainPhraseHints, createPhraseHintCorrectionHandler, createRiskyTurnCorrectionHandler } from './correction';
@@ -137,6 +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 { 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

@@ -28931,6 +28931,191 @@ var createVoicePostCallAnalysisRoutes = (options = {}) => {
   });
   return routes;
 };
+// src/guardrails.ts
+import { Elysia as Elysia50 } from "elysia";
+var stringifyContent = (value) => typeof value === "string" ? value : JSON.stringify(value) ?? "";
+var appliesToStage = (rule, stage) => !rule.stages || rule.stages.length === 0 || rule.stages.includes(stage);
+var matchesRule = async (rule, input) => {
+  if (!appliesToStage(rule, input.stage)) {
+    return false;
+  }
+  if (typeof rule.match === "function") {
+    return rule.match(input);
+  }
+  const content = stringifyContent(input.content);
+  return typeof rule.match === "string" ? content.toLowerCase().includes(rule.match.toLowerCase()) : rule.match.test(content);
+};
+var applyRedactions = (content, rules, findings) => {
+  if (typeof content !== "string") {
+    return content;
+  }
+  return findings.reduce((value, finding) => {
+    const rule = rules.find((candidate) => candidate.id === finding.ruleId);
+    if (!rule || !rule.redactWith) {
+      return value;
+    }
+    if (typeof rule.match === "string") {
+      return value.replaceAll(rule.match, rule.redactWith);
+    }
+    if (rule.match instanceof RegExp) {
+      return value.replace(rule.match, rule.redactWith);
+    }
+    return value;
+  }, content);
+};
+var evaluateVoiceGuardrailPolicy = async (policy, input) => {
+  const findings = [];
+  for (const rule of policy.rules) {
+    if (!await matchesRule(rule, input)) {
+      continue;
+    }
+    findings.push({
+      action: rule.action ?? policy.defaultAction ?? "block",
+      description: rule.description,
+      label: rule.label ?? rule.id,
+      ruleId: rule.id,
+      stage: input.stage
+    });
+  }
+  const blocked = findings.some((finding) => finding.action === "block");
+  const status = blocked ? "blocked" : findings.length > 0 ? "warn" : "pass";
+  return {
+    allowed: !blocked,
+    checkedAt: Date.now(),
+    content: input.content,
+    findings,
+    redactedContent: applyRedactions(input.content, policy.rules, findings),
+    sessionId: input.sessionId,
+    stage: input.stage,
+    status,
+    turnId: input.turnId
+  };
+};
+var buildVoiceGuardrailReport = (input = { decisions: [] }) => {
+  const blocked = input.decisions.filter((decision) => decision.status === "blocked").length;
+  const warned = input.decisions.filter((decision) => decision.status === "warn").length;
+  const passed = input.decisions.filter((decision) => decision.status === "pass").length;
+  const status = blocked > 0 ? "fail" : warned > 0 ? "warn" : "pass";
+  return {
+    checkedAt: Date.now(),
+    decisions: input.decisions,
+    failed: blocked,
+    policies: (input.policies ?? []).map((policy) => ({
+      id: policy.id,
+      label: policy.label,
+      rules: policy.rules.length
+    })),
+    status,
+    summary: {
+      blocked,
+      passed,
+      warned
+    },
+    total: input.decisions.length
+  };
+};
+var createVoiceGuardrailPolicy = (policy) => policy;
+var voiceGuardrailPolicyPresets = {
+  supportSafeDefaults: createVoiceGuardrailPolicy({
+    id: "support-safe-defaults",
+    label: "Support safe defaults",
+    rules: [
+      {
+        description: "Blocks final legal, medical, or financial advice claims that should route to a human or qualified professional.",
+        id: "regulated-advice",
+        label: "Regulated advice",
+        match: /\b(legal advice|medical advice|financial advice|diagnose|prescribe|guaranteed refund|guaranteed approval)\b/i,
+        stages: ["assistant-output"]
+      },
+      {
+        description: "Warns when payment-card-like data appears in transcripts or tool payloads.",
+        action: "warn",
+        id: "payment-card-like-data",
+        label: "Payment card-like data",
+        match: /\b(?:\d[ -]*?){13,19}\b/,
+        redactWith: "[redacted-card]",
+        stages: ["transcript", "tool-input", "tool-output"]
+      }
+    ]
+  })
+};
+var renderVoiceGuardrailMarkdown = (report) => {
+  const lines = [
+    "# Voice Guardrail Report",
+    "",
+    `Status: ${report.status}`,
+    `Checked: ${new Date(report.checkedAt).toISOString()}`,
+    `Decisions: ${report.total}`,
+    `Blocked: ${report.summary.blocked}`,
+    `Warned: ${report.summary.warned}`,
+    "",
+    "## Decisions",
+    ...report.decisions.length > 0 ? report.decisions.map((decision) => `- ${decision.status}: ${decision.stage}${decision.sessionId ? ` session=${decision.sessionId}` : ""} findings=${decision.findings.length}`) : ["- none"]
+  ];
+  return `${lines.join(`
+`)}
+`;
+};
+var isGuardrailReport = (value) => ("decisions" in value) && ("summary" in value);
+var normalizeGuardrailRouteInput = async (request) => {
+  if (request.method === "POST") {
+    return await request.json().catch(() => ({}));
+  }
+  const url = new URL(request.url);
+  return {
+    content: url.searchParams.get("content") ?? "",
+    sessionId: url.searchParams.get("sessionId") ?? undefined,
+    stage: url.searchParams.get("stage") ?? "assistant-output",
+    turnId: url.searchParams.get("turnId") ?? undefined
+  };
+};
+var resolveGuardrailReport = async (options, input) => {
+  if (options.source !== undefined) {
+    const value = typeof options.source === "function" ? await options.source(input) : options.source;
+    return isGuardrailReport(value) ? value : buildVoiceGuardrailReport({ decisions: [value] });
+  }
+  const decisions = await Promise.all((options.policies ?? []).map((policy) => evaluateVoiceGuardrailPolicy(policy, input)));
+  return buildVoiceGuardrailReport({
+    decisions,
+    policies: options.policies
+  });
+};
+var createVoiceGuardrailRoutes = (options = {}) => {
+  const path = options.path ?? "/api/voice/guardrails";
+  const routes = new Elysia50({
+    name: options.name ?? "absolutejs-voice-guardrails"
+  });
+  routes.all(path, async ({ request }) => {
+    const input = await normalizeGuardrailRouteInput(request);
+    const report = await resolveGuardrailReport(options, input);
+    if (options.trace) {
+      await Promise.all(report.decisions.map((decision) => options.trace.append({
+        at: decision.checkedAt,
+        payload: {
+          allowed: decision.allowed,
+          findings: decision.findings,
+          stage: decision.stage,
+          status: decision.status
+        },
+        sessionId: decision.sessionId ?? "guardrail-check",
+        turnId: decision.turnId,
+        type: "assistant.guardrail"
+      })));
+    }
+    return Response.json(report, { headers: options.headers });
+  });
+  routes.all(`${path}.md`, async ({ request }) => {
+    const input = await normalizeGuardrailRouteInput(request);
+    const report = await resolveGuardrailReport(options, input);
+    return new Response(renderVoiceGuardrailMarkdown(report), {
+      headers: {
+        "content-type": "text/markdown; charset=utf-8",
+        ...options.headers
+      }
+    });
+  });
+  return routes;
+};
 // 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");
@@ -29323,6 +29508,7 @@ export {
   voiceTelephonyOutcomeToRouteResult,
   voiceObservabilityExportSchemaVersion,
   voiceObservabilityExportSchemaId,
+  voiceGuardrailPolicyPresets,
   voiceComplianceRedactionDefaults,
   voice,
   verifyVoiceTwilioWebhookSignature,
@@ -29438,6 +29624,7 @@ export {
   renderVoiceLiveLatencyHTML,
   renderVoiceLatencySLOMarkdown,
   renderVoiceHandoffHealthHTML,
+  renderVoiceGuardrailMarkdown,
   renderVoiceEvalHTML,
   renderVoiceEvalBaselineHTML,
   renderVoiceDemoReadyHTML,
@@ -29497,6 +29684,7 @@ export {
   evaluateVoiceTelephonyContract,
   evaluateVoiceQuality,
   evaluateVoiceProviderStackGaps,
+  evaluateVoiceGuardrailPolicy,
   encodeTwilioMulawBase64,
   deliverVoiceTraceEventsToSinks,
   deliverVoiceObservabilityExport,
@@ -29676,6 +29864,8 @@ export {
   createVoiceHandoffDeliveryWorkerLoop,
   createVoiceHandoffDeliveryWorker,
   createVoiceHandoffDeliveryRecord,
+  createVoiceGuardrailRoutes,
+  createVoiceGuardrailPolicy,
   createVoiceFileTraceSinkDeliveryStore,
   createVoiceFileTraceEventStore,
   createVoiceFileTaskStore,
@@ -29792,6 +29982,7 @@ export {
   buildVoiceLiveOpsControlState,
   buildVoiceLatencySLOGate,
   buildVoiceIncidentBundle,
+  buildVoiceGuardrailReport,
   buildVoiceDiagnosticsMarkdown,
   buildVoiceDemoReadyReport,
   buildVoiceDeliverySinkReport,

package/package.json

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