@absolutejs/voice 0.0.22-beta.193 → 0.0.22-beta.195

package/README.md

@@ -1045,6 +1045,19 @@ const frontDesk = createVoiceAgentSquad({
 	id: 'front-desk',
 	defaultAgentId: 'support',
 	agents: [supportAgent, billingAgent],
+	contextPolicy: ({ summaryMessage, turn }) => ({
+		messages: [
+			summaryMessage,
+			{
+				content: turn.text,
+				role: 'user'
+			}
+		],
+		metadata: {
+			contextPolicy: 'handoff-summary-and-current-turn'
+		},
+		system: 'Use only the handoff summary and current caller turn.'
+	}),
 	handoffPolicy: ({ handoff }) => {
 		if (handoff.targetAgentId === 'billing') {
 			return {
@@ -1074,6 +1087,10 @@ voice({
 
 For production call centers, pass `handoffPolicy` to keep routing code-owned instead of dashboard-owned. The policy can allow a handoff, reroute it to a different specialist, merge handoff metadata, summarize the reason for the target agent, or block the handoff and return an escalation. Squad traces mark each handoff as `allowed`, `blocked`, `unknown-target`, or `max-exceeded`, so support teams can audit why a caller moved between specialists.
 
+Pass `contextPolicy` when a specialist should receive a controlled context window. The default behavior preserves the accumulated conversation plus a system handoff summary. A context policy can trim that to a handoff summary and current turn, add a specialist-specific system prompt, or attach metadata that appears in the returned squad state. This is the code-owned equivalent of Vapi Squads context controls: the app decides what each specialist sees, and `agent.context` traces show whether default or custom context was applied.
+
+Each specialist owns its own `tools`, so tool permissions stay explicit per agent. For example, support can have `lookup_order`, billing can have `refund_invoice`, and scheduling can have `book_appointment`. The squad only routes; it does not give every specialist every tool by default.
+
 Use `runVoiceAgentSquadContract(...)` in tests or readiness checks when you need proof that a specialist graph still routes correctly:
 
 ```ts
@@ -1292,6 +1309,47 @@ await applyVoiceDataRetentionPolicy({
 });
 ```
 
+For a compliance-facing control surface, mount `createVoiceDataControlRoutes(...)`. It packages the same primitives into a self-hosted report for customer-owned storage, retention dry-runs, guarded deletion, redacted audit export, zero-retention mode, and provider-key handling.
+
+```ts
+import {
+	createVoiceDataControlRoutes,
+	createVoiceZeroRetentionPolicy,
+	voiceComplianceRedactionDefaults
+} from '@absolutejs/voice';
+
+app.use(
+	createVoiceDataControlRoutes({
+		...runtimeStorage,
+		audit: runtimeStorage.audit,
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		path: '/data-control',
+		redact: voiceComplianceRedactionDefaults,
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+
+const zeroRetentionPlan = await buildVoiceDataRetentionPlan(
+	createVoiceZeroRetentionPolicy({
+		...runtimeStorage,
+		audit: runtimeStorage.audit,
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+```
+
+Mounted routes:
+
+- `GET /data-control`: HTML compliance/data-control report.
+- `GET /data-control.json`: JSON report with redaction, storage, retention plan, audit export, and provider-key recommendations.
+- `GET /data-control.md`: Markdown report for release/security reviews.
+- `POST /data-control/retention/plan`: dry-run deletion proof from a JSON policy body.
+- `POST /data-control/retention/apply`: applies retention only when the body includes `confirm: "apply-retention-policy"`.
+- `GET /data-control/audit.json`, `/data-control/audit.md`, `/data-control/audit.html`: redacted audit exports.
+
+`createVoiceZeroRetentionPolicy(...)` intentionally defaults to `dryRun: true`; callers must explicitly apply the generated policy after reviewing the deletion proof. This gives compliance-sensitive deployments a concrete zero-retention recipe without making accidental deletion easy.
+
 Use `createVoiceAuditLogger(...)` when you need append-only compliance evidence outside call traces. The logger records provider calls, tool calls, handoffs, retention runs, and operator actions into `runtimeStorage.audit`, so self-hosted teams can prove who changed what, which provider ran, which tool fired, and what data-control policy deleted.
 
 Pass `audit` directly to `createVoiceAgent(...)` to record model calls as provider-call audit events and tool executions as tool-call audit events. Pass it to `createVoiceAgentSquad(...)` to record squad handoffs automatically. Use `auditProvider` and `auditModel` on agents when you want readiness and compliance reports to show the actual model provider instead of the agent id.

package/dist/agent.d.ts

@@ -95,6 +95,11 @@ export type VoiceAgentSquadHandoffPolicyResult<TResult = unknown> = {
     summary?: string;
     targetAgentId?: string;
 };
+export type VoiceAgentSquadContextPolicyResult = {
+    messages?: VoiceAgentMessage[];
+    metadata?: Record<string, unknown>;
+    system?: string;
+};
 export type VoiceAgent<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     id: string;
     onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
@@ -136,6 +141,16 @@ export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSes
         targetAgent?: VoiceAgent<TContext, TSession, TResult>;
         turn: VoiceTurnRecord;
     }) => Promise<VoiceAgentSquadHandoffPolicyResult<TResult> | void> | VoiceAgentSquadHandoffPolicyResult<TResult> | void;
+    contextPolicy?: (input: {
+        context: TContext;
+        fromAgentId: string;
+        handoff: VoiceAgentSquadStateHandoff;
+        messages: VoiceAgentMessage[];
+        session: TSession;
+        summaryMessage: VoiceAgentMessage;
+        targetAgent: VoiceAgent<TContext, TSession, TResult>;
+        turn: VoiceTurnRecord;
+    }) => Promise<VoiceAgentSquadContextPolicyResult | void> | VoiceAgentSquadContextPolicyResult | void;
     id: string;
     maxHandoffsPerTurn?: number;
     onHandoff?: (input: {

package/dist/client/index.js

@@ -3533,6 +3533,8 @@ var renderTraceEventMarkdown = (event, startedAt) => {
       return event.payload.text ? `${label} assistant "${formatTraceValue(event.payload.text)}"` : `${label} ${formatTraceValue(event.payload.status)}`;
     case "agent.tool":
       return `${label} ${formatTraceValue(event.payload.toolName)} ${formatTraceValue(event.payload.status)}`;
+    case "agent.context":
+      return `${label} ${formatTraceValue(event.payload.fromAgentId)} -> ${formatTraceValue(event.payload.targetAgentId)} ${formatTraceValue(event.payload.status)}`;
     case "agent.handoff":
       return `${label} ${formatTraceValue(event.payload.fromAgentId)} -> ${formatTraceValue(event.payload.targetAgentId)}`;
     case "session.error":

package/dist/dataControl.d.ts

@@ -1,11 +1,18 @@
 import type { VoiceCampaignStore } from './campaign';
-import { type VoiceAuditActor, type VoiceAuditEventStore } from './audit';
+import { Elysia } from 'elysia';
+import { type VoiceAuditActor, type VoiceAuditEventFilter, type VoiceAuditEventStore } from './audit';
+import { exportVoiceAuditTrail } from './auditExport';
 import type { VoiceAuditSinkDeliveryStore } from './auditSinks';
 import type { VoiceIntegrationEventStore, VoiceOpsTaskStore } from './ops';
 import type { VoiceIncidentBundleStore } from './incidentBundle';
 import type { VoiceCallReviewStore } from './testing/review';
 import type { VoiceTraceEventStore, VoiceTracePruneFilter, VoiceTraceSinkDeliveryStore } from './trace';
 import type { VoiceSessionStore } from './types';
+export declare const voiceComplianceRedactionDefaults: {
+    keys: string[];
+    redactEmails: true;
+    redactPhoneNumbers: true;
+};
 export type VoiceDataRetentionScope = 'auditDeliveries' | 'campaigns' | 'events' | 'incidentBundles' | 'reviews' | 'sessions' | 'tasks' | 'traceDeliveries' | 'traces';
 export type VoiceDataRetentionStores = {
     campaigns?: VoiceCampaignStore;
@@ -45,5 +52,89 @@ export type VoiceDataRetentionReport = {
     dryRun: boolean;
     scopes: VoiceDataRetentionScopeReport[];
 };
+export type VoiceDataControlStorageSurface = {
+    configured: boolean;
+    control: 'audit' | 'artifact' | 'queue' | 'session' | 'workflow';
+    name: string;
+    selfHosted: boolean;
+};
+export type VoiceDataControlProviderKeySurface = {
+    env?: string;
+    name: string;
+    recommendation: string;
+    required: boolean;
+};
+export type VoiceDataControlReport = {
+    auditExport?: Awaited<ReturnType<typeof exportVoiceAuditTrail>>;
+    checkedAt: number;
+    deletionProof?: VoiceDataRetentionReport;
+    redaction: {
+        defaults: typeof voiceComplianceRedactionDefaults;
+        enabled: boolean;
+    };
+    retentionPlan: VoiceDataRetentionReport;
+    storage: VoiceDataControlStorageSurface[];
+    providerKeys: VoiceDataControlProviderKeySurface[];
+    zeroRetentionAvailable: boolean;
+};
+export type VoiceDataControlRoutesOptions = VoiceDataRetentionStores & {
+    audit?: VoiceAuditEventStore;
+    auditActor?: VoiceAuditActor;
+    auditDeliveries?: VoiceAuditSinkDeliveryStore;
+    headers?: HeadersInit;
+    name?: string;
+    path?: string;
+    providerKeys?: VoiceDataControlProviderKeySurface[];
+    redact?: import('./trace').VoiceTraceRedactionConfig | boolean;
+    title?: string;
+    traceDeliveries?: VoiceTraceSinkDeliveryStore;
+};
 export declare const applyVoiceDataRetentionPolicy: (options: VoiceDataRetentionPolicy) => Promise<VoiceDataRetentionReport>;
 export declare const buildVoiceDataRetentionPlan: (options: Omit<VoiceDataRetentionPolicy, "dryRun">) => Promise<VoiceDataRetentionReport>;
+export declare const createVoiceZeroRetentionPolicy: (options: VoiceDataRetentionStores & {
+    audit?: VoiceAuditEventStore;
+    auditActor?: VoiceAuditActor;
+    auditDeliveries?: VoiceAuditSinkDeliveryStore;
+    beforeOrAt?: number;
+    dryRun?: boolean;
+    scopes?: VoiceDataRetentionScope[];
+    traceDeliveries?: VoiceTraceSinkDeliveryStore;
+}) => VoiceDataRetentionPolicy;
+export declare const buildVoiceDataControlReport: (options: VoiceDataControlRoutesOptions & {
+    auditFilter?: VoiceAuditEventFilter;
+    retention?: Omit<VoiceDataRetentionPolicy, "dryRun">;
+}) => Promise<VoiceDataControlReport>;
+export declare const renderVoiceDataControlHTML: (report: VoiceDataControlReport, options?: {
+    title?: string;
+}) => string;
+export declare const renderVoiceDataControlMarkdown: (report: VoiceDataControlReport, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceDataControlRoutes: (options: VoiceDataControlRoutesOptions) => 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

@@ -17,8 +17,8 @@ export { buildVoiceOpsActionHistoryReport, createVoiceOpsActionAuditRoutes, reco
 export { buildVoiceLiveOpsControlState, createVoiceLiveOpsController, createVoiceLiveOpsRoutes, createVoiceMemoryLiveOpsControlStore, getVoiceLiveOpsControlStatus, VOICE_LIVE_OPS_ACTIONS } from './liveOps';
 export type { VoiceLiveOpsAction, VoiceLiveOpsActionInput, VoiceLiveOpsActionResult, VoiceLiveOpsControllerOptions, VoiceLiveOpsControlState, VoiceLiveOpsControlStatus, VoiceLiveOpsControlStore, VoiceLiveOpsRoutesOptions } from './liveOps';
 export { buildVoiceDeliveryRuntimeReport, createVoiceDeliveryRuntime, createVoiceDeliveryRuntimePresetConfig, createVoiceDeliveryRuntimeRoutes, renderVoiceDeliveryRuntimeHTML } from './deliveryRuntime';
-export { applyVoiceDataRetentionPolicy, buildVoiceDataRetentionPlan } from './dataControl';
-export type { VoiceDataRetentionPolicy, VoiceDataRetentionReport, VoiceDataRetentionScope, VoiceDataRetentionScopeReport, VoiceDataRetentionStores } from './dataControl';
+export { applyVoiceDataRetentionPolicy, buildVoiceDataControlReport, buildVoiceDataRetentionPlan, createVoiceDataControlRoutes, createVoiceZeroRetentionPolicy, renderVoiceDataControlHTML, renderVoiceDataControlMarkdown, voiceComplianceRedactionDefaults } from './dataControl';
+export type { VoiceDataControlProviderKeySurface, VoiceDataControlReport, VoiceDataControlRoutesOptions, VoiceDataControlStorageSurface, VoiceDataRetentionPolicy, VoiceDataRetentionReport, VoiceDataRetentionScope, VoiceDataRetentionScopeReport, VoiceDataRetentionStores } from './dataControl';
 export type { VoiceDemoReadyReport, VoiceDemoReadyRoutesOptions, VoiceDemoReadySection, VoiceDemoReadyStatus } from './demoReadyRoutes';
 export type { VoiceDeliverySinkDescriptor, VoiceDeliverySinkDescriptorInput, VoiceDeliverySinkKind, VoiceDeliverySinkPairOptions, VoiceDeliverySinkReport, VoiceDeliverySinkRoutesOptions, VoiceTraceDeliverySinkSurface } from './deliverySinkRoutes';
 export type { VoiceOpsActionAuditRecord, VoiceOpsActionAuditRoutesOptions, VoiceOpsActionHistoryEntry, VoiceOpsActionHistoryReport } from './opsActionAuditRoutes';
@@ -118,7 +118,7 @@ export type { StoredVoiceIncidentBundleArtifact, VoiceIncidentBundle, VoiceIncid
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingKindSummary, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind, VoiceRoutingSessionSummary, VoiceRoutingSessionSummaryOptions } from './resilienceRoutes';
 export type { VoiceIOProviderRouterEvent, VoiceIOProviderRouterOptions, VoiceIOProviderRouterPolicy, VoiceIOProviderRouterPolicyConfig, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions } from './providerAdapters';
-export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadHandoffStatus, VoiceAgentSquadOptions, VoiceAgentSquadState, VoiceAgentSquadStateHandoff, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
+export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadContextPolicyResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadHandoffStatus, VoiceAgentSquadOptions, VoiceAgentSquadState, VoiceAgentSquadStateHandoff, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
 export type { VoiceAgentSquadContractDefinition, VoiceAgentSquadContractIssue, VoiceAgentSquadContractOutcome, VoiceAgentSquadContractReport, VoiceAgentSquadContractRunOptions, VoiceAgentSquadContractTurn, VoiceAgentSquadContractTurnReport, VoiceAgentSquadHandoffExpectation, VoiceAgentSquadTurnExpectation } from './agentSquadContract';
 export type { VoiceToolRetryDelay, VoiceToolRuntime, VoiceToolRuntimeExecuteInput, VoiceToolRuntimeOptions, VoiceToolRuntimeResult } from './toolRuntime';
 export type { VoiceToolContractCase, VoiceToolContractCaseReport, VoiceToolContractDefinition, VoiceToolContractExpectation, VoiceToolContractHandlerOptions, VoiceToolContractHTMLHandlerOptions, VoiceToolContractIssue, VoiceToolContractReport, VoiceToolContractRoutesOptions, VoiceToolContractSuiteReport } from './toolContract';