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

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

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/index.d.ts

@@ -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';

package/dist/index.js

@@ -7756,7 +7756,7 @@ var createVoiceAgentSquad = (options) => {
         targetAgentId: nextAgent.id,
         turn: input.turn
       });
-      await appendVoiceAgentSquadHandoff({
+      const handoff = await appendVoiceAgentSquadHandoff({
         agentId: options.id,
         fromAgentId: agent.id,
         handoffs,
@@ -7782,17 +7782,54 @@ var createVoiceAgentSquad = (options) => {
         sessionId: input.session.id,
         toAgentId: nextAgent.id
       });
-      messages.push({
+      const summaryMessage = {
         content: handoffSummary ?? handoffReason ?? `Handoff to ${nextAgent.id}`,
         metadata,
         name: nextAgent.id,
         role: "system"
+      };
+      messages.push(summaryMessage);
+      const contextPolicy = await options.contextPolicy?.({
+        context: input.context,
+        fromAgentId: agent.id,
+        handoff,
+        messages,
+        session: input.session,
+        summaryMessage,
+        targetAgent: nextAgent,
+        turn: input.turn
+      });
+      if (contextPolicy?.metadata && Object.keys(contextPolicy.metadata).length > 0) {
+        handoff.metadata = {
+          ...handoff.metadata,
+          ...contextPolicy.metadata
+        };
+        const latest = handoffs.at(-1);
+        if (latest === handoff) {
+          latest.metadata = handoff.metadata;
+        }
+      }
+      await appendVoiceAgentTrace({
+        agentId: options.id,
+        event: {
+          fromAgentId: handoff.fromAgentId,
+          messageCount: messages.length,
+          nextMessageCount: contextPolicy?.messages?.length ?? messages.length,
+          status: contextPolicy ? "applied" : "default",
+          summaryIncluded: (contextPolicy?.messages ?? messages).some((message) => message === summaryMessage),
+          targetAgentId: nextAgent.id
+        },
+        session: input.session,
+        trace: options.trace,
+        turn: input.turn,
+        type: "agent.context"
       });
       agent = nextAgent;
       agentId = nextAgent.id;
       result = await agent.run({
         ...input,
-        messages
+        messages: contextPolicy?.messages ?? messages,
+        system: contextPolicy?.system ?? input.system
       });
       toolResults.push(...result.toolResults);
     }
@@ -9503,6 +9540,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/svelte/index.js

@@ -1621,6 +1621,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/trace.d.ts

@@ -1,5 +1,5 @@
 import type { S3Client, S3Options } from 'bun';
-export type VoiceTraceEventType = 'assistant.guardrail' | 'assistant.memory' | 'assistant.run' | 'agent.handoff' | 'agent.model' | 'agent.result' | 'agent.tool' | 'call.handoff' | 'call.lifecycle' | 'client.barge_in' | 'client.live_latency' | 'client.reconnect' | 'operator.action' | 'session.error' | 'turn.assistant' | 'turn.committed' | 'turn.cost' | 'turn_latency.stage' | 'turn.transcript' | 'workflow.contract';
+export type VoiceTraceEventType = 'assistant.guardrail' | 'assistant.memory' | 'assistant.run' | 'agent.context' | 'agent.handoff' | 'agent.model' | 'agent.result' | 'agent.tool' | 'call.handoff' | 'call.lifecycle' | 'client.barge_in' | 'client.live_latency' | 'client.reconnect' | 'operator.action' | 'session.error' | 'turn.assistant' | 'turn.committed' | 'turn.cost' | 'turn_latency.stage' | 'turn.transcript' | 'workflow.contract';
 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.193",
+	"version": "0.0.22-beta.194",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",