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

package/dist/core/agent.d.ts

@@ -36,6 +36,10 @@ export type VoiceAgentToolResult<TResult = unknown> = {
     toolCallId?: string;
     toolName: string;
 };
+export type VoiceAgentToolPolicyDecision = {
+    allowed: boolean;
+    reason?: string;
+};
 export type VoiceAgentTool<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
     description?: string;
     execute: (input: {
@@ -47,6 +51,22 @@ export type VoiceAgentTool<TContext = unknown, TSession extends VoiceSessionReco
     }) => Promise<TToolResult> | TToolResult;
     name: string;
     parameters?: Record<string, unknown>;
+    /** Authorize a model-requested side effect before `execute` runs. Unlike
+     *  post-turn guardrails, this policy sees the assistant text produced in the
+     *  same model round and can prevent an unsafe tool from mutating call state.
+     *  A blocked terminal tool still ends the conversational turn so the already
+     *  streamed reply is not followed by a second model response. */
+    policy?: (input: {
+        api: VoiceSessionHandle<TContext, TSession, TRouteResult>;
+        args: TArgs;
+        assistantText?: string;
+        context: TContext;
+        messages: ReadonlyArray<VoiceAgentMessage>;
+        round: number;
+        session: TSession;
+        toolCall: VoiceAgentToolCall<TArgs>;
+        turn: VoiceTurnRecord;
+    }) => Promise<VoiceAgentToolPolicyDecision> | VoiceAgentToolPolicyDecision;
     resultToMessage?: (result: TToolResult) => string;
     /** End the turn after this tool runs — do NOT loop back to the model for
      *  another generation. Use for tools that wrap up the call (an app-defined

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, VoiceAgentToolResult, } from "./core/agent";
+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 { 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

@@ -8546,6 +8546,63 @@ var createVoiceAgent = (options) => {
           });
           continue;
         }
+        const policyDecision = await tool.policy?.({
+          api: input.api,
+          args: toolCall.args,
+          assistantText: output.assistantText,
+          context: input.context,
+          messages,
+          round,
+          session: input.session,
+          toolCall,
+          turn: input.turn
+        });
+        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
+          });
+          if (tool.endsTurn) {
+            endTurnAfterDispatch = true;
+          }
+          continue;
+        }
         try {
           const toolStartedAt = Date.now();
           const runtimeResult = options.toolRuntime ? await options.toolRuntime.execute({

package/package.json

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