@absolutejs/voice 0.0.22-beta.669 → 0.0.22-beta.670

package/dist/core/agent.d.ts

@@ -40,6 +40,16 @@ export type VoiceAgentToolPolicyDecision = {
     allowed: boolean;
     reason?: string;
 };
+export type VoiceAgentToolPolicy<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = (input: {
+    api: VoiceSessionHandle<TContext, TSession, TResult>;
+    assistantText?: string;
+    context: TContext;
+    messages: ReadonlyArray<VoiceAgentMessage>;
+    round: number;
+    session: TSession;
+    toolCall: VoiceAgentToolCall;
+    turn: VoiceTurnRecord;
+}) => Promise<VoiceAgentToolPolicyDecision> | VoiceAgentToolPolicyDecision;
 export type VoiceAgentTool<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
     description?: string;
     execute: (input: {
@@ -187,6 +197,9 @@ export type VoiceAgentOptions<TContext = unknown, TSession extends VoiceSessionR
         turn: VoiceTurnRecord;
     }) => Promise<string | undefined> | string | undefined);
     trace?: VoiceTraceEventStore;
+    /** Authorize every model-requested tool before dispatch, including built-in
+     *  lifecycle tools such as `complete` and `transfer_call`. */
+    toolPolicy?: VoiceAgentToolPolicy<TContext, TSession, TResult>;
     toolRuntime?: VoiceToolRuntime<TContext, TSession, TResult>;
     tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
 };

package/dist/core/assistant.d.ts

@@ -68,6 +68,7 @@ export type VoiceAssistantAgentSource<TContext, TSession extends VoiceSessionRec
     model?: never;
     selectAgent?: never;
     system?: never;
+    toolPolicy?: never;
     tools?: never;
 } | {
     agent?: never;
@@ -78,6 +79,7 @@ export type VoiceAssistantAgentSource<TContext, TSession extends VoiceSessionRec
     model?: never;
     selectAgent?: VoiceAgentSquadOptions<TContext, TSession, TResult>["selectAgent"];
     system?: never;
+    toolPolicy?: never;
     tools?: never;
 } | {
     agent?: never;
@@ -88,6 +90,7 @@ export type VoiceAssistantAgentSource<TContext, TSession extends VoiceSessionRec
     model: VoiceAgentModel<TContext, TSession, TResult>;
     selectAgent?: never;
     system?: VoiceAgentOptions<TContext, TSession, TResult>["system"];
+    toolPolicy?: VoiceAgentOptions<TContext, TSession, TResult>["toolPolicy"];
     tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
 };
 export type VoiceAssistantOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceAssistantAgentSource<TContext, TSession, TResult> & {

package/dist/index.d.ts

@@ -257,7 +257,7 @@ export type { StoredVoiceIncidentBundleArtifact, VoiceIncidentBundle, VoiceIncid
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds, } from "./core/qualityRoutes";
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingKindSummary, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind, VoiceRoutingSessionSummary, VoiceRoutingSessionSummaryOptions, } from "./core/resilienceRoutes";
 export type { VoiceIOProviderRouterEvent, VoiceIOProviderRouterOptions, VoiceIOProviderRouterPolicy, VoiceIOProviderRouterPolicyConfig, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions, } from "./core/providerAdapters";
-export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadContextPolicyResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadHandoffStatus, VoiceAgentSquadOptions, VoiceAgentSquadState, VoiceAgentSquadStateHandoff, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolPolicyDecision, VoiceAgentToolResult, } from "./core/agent";
+export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadContextPolicyResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadHandoffStatus, VoiceAgentSquadOptions, VoiceAgentSquadState, VoiceAgentSquadStateHandoff, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolPolicy, VoiceAgentToolPolicyDecision, VoiceAgentToolResult, } from "./core/agent";
 export type { VoiceAgentSquadContractAssertionInput, VoiceAgentSquadContractAssertionReport, VoiceAgentSquadContractDefinition, VoiceAgentSquadContractIssue, VoiceAgentSquadContractOutcome, VoiceAgentSquadContractReport, VoiceAgentSquadContractRunOptions, VoiceAgentSquadContractTurn, VoiceAgentSquadContractTurnReport, VoiceAgentSquadHandoffExpectation, VoiceAgentSquadTurnExpectation, } from "./core/agentSquadContract";
 export type { VoiceToolRetryDelay, VoiceToolRuntime, VoiceToolRuntimeExecuteInput, VoiceToolRuntimeOptions, VoiceToolRuntimeResult, } from "./core/toolRuntime";
 export type { VoiceToolContractAssertionInput, VoiceToolContractAssertionReport, VoiceToolContractCase, VoiceToolContractCaseReport, VoiceToolContractDefinition, VoiceToolContractExpectation, VoiceToolContractHandlerOptions, VoiceToolContractHTMLHandlerOptions, VoiceToolContractIssue, VoiceToolContractReport, VoiceToolContractRoutesOptions, VoiceToolContractSuiteReport, } from "./core/toolContract";

package/dist/index.js

@@ -8412,6 +8412,47 @@ var createVoiceAgent = (options) => {
 
 `) || undefined;
     stamp("agent.system-resolved", { systemChars: system?.length ?? 0 });
+    const recordPolicyBlock = async (toolCall, reason) => {
+      const blockedResult = {
+        error: reason,
+        status: "error",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name
+      };
+      toolResults.push(blockedResult);
+      await appendVoiceAgentTrace({
+        agentId: options.id,
+        event: {
+          error: reason,
+          policyBlocked: true,
+          status: "error",
+          toolCallId: toolCall.id,
+          toolName: toolCall.name
+        },
+        session: input.session,
+        trace: options.trace,
+        turn: input.turn,
+        type: "agent.tool"
+      });
+      await audit?.toolCall({
+        actor: {
+          id: options.id,
+          kind: "agent"
+        },
+        error: reason,
+        metadata: { policyBlocked: true },
+        outcome: "error",
+        sessionId: input.session.id,
+        toolCallId: toolCall.id,
+        toolName: toolCall.name
+      });
+      messages.push({
+        content: reason,
+        name: toolCall.name,
+        role: "tool",
+        toolCallId: toolCall.id
+      });
+    };
     let output = {};
     let turnUsage;
     for (let round = 0;round <= maxToolRounds; round += 1) {
@@ -8482,6 +8523,27 @@ var createVoiceAgent = (options) => {
         turn: input.turn,
         type: "agent.model"
       });
+      if (options.toolPolicy && output.toolCalls?.length) {
+        const allowedToolCalls = [];
+        for (const toolCall of output.toolCalls) {
+          const decision = await options.toolPolicy({
+            api: input.api,
+            assistantText: output.assistantText,
+            context: input.context,
+            messages,
+            round,
+            session: input.session,
+            toolCall,
+            turn: input.turn
+          });
+          if (decision.allowed) {
+            allowedToolCalls.push(toolCall);
+          } else {
+            await recordPolicyBlock(toolCall, decision.reason ?? `Voice agent tool policy blocked ${toolCall.name}.`);
+          }
+        }
+        output.toolCalls = allowedToolCalls;
+      }
       if (output.assistantText?.trim()) {
         messages.push({
           content: output.assistantText,
@@ -8559,45 +8621,7 @@ var createVoiceAgent = (options) => {
         });
         if (policyDecision && !policyDecision.allowed) {
           const error = policyDecision.reason ?? `Voice agent tool policy blocked ${tool.name}.`;
-          const blockedResult = {
-            error,
-            status: "error",
-            toolCallId: toolCall.id,
-            toolName: tool.name
-          };
-          toolResults.push(blockedResult);
-          await appendVoiceAgentTrace({
-            agentId: options.id,
-            event: {
-              error,
-              policyBlocked: true,
-              status: "error",
-              toolCallId: toolCall.id,
-              toolName: tool.name
-            },
-            session: input.session,
-            trace: options.trace,
-            turn: input.turn,
-            type: "agent.tool"
-          });
-          await audit?.toolCall({
-            actor: {
-              id: options.id,
-              kind: "agent"
-            },
-            error,
-            metadata: { policyBlocked: true },
-            outcome: "error",
-            sessionId: input.session.id,
-            toolCallId: toolCall.id,
-            toolName: tool.name
-          });
-          messages.push({
-            content: error,
-            name: tool.name,
-            role: "tool",
-            toolCallId: toolCall.id
-          });
+          await recordPolicyBlock(toolCall, error);
           if (tool.endsTurn) {
             endTurnAfterDispatch = true;
           }
@@ -9498,6 +9522,7 @@ var createVoiceAssistant = (options) => {
     maxToolRounds: options.maxToolRounds,
     model: options.model,
     system: options.system,
+    toolPolicy: options.toolPolicy,
     tools: options.tools
   } : undefined;
   if ("agent" in options && options.agent) {
@@ -9517,6 +9542,7 @@ var createVoiceAssistant = (options) => {
       maxToolRounds: options.maxToolRounds,
       model: options.model,
       system: options.system,
+      toolPolicy: options.toolPolicy,
       tools: options.tools,
       trace: options.trace
     });
@@ -9590,6 +9616,7 @@ var createVoiceAssistant = (options) => {
       maxToolRounds: variant.maxToolRounds ?? baseModelOptions.maxToolRounds,
       model: variant.model ?? baseModelOptions.model,
       system: variant.system ?? baseModelOptions.system,
+      toolPolicy: baseModelOptions.toolPolicy,
       tools: variant.tools ?? baseModelOptions.tools,
       trace: options.trace
     }) : agent;

package/package.json

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