@absolutejs/voice 0.0.22-beta.61 → 0.0.22-beta.62

package/dist/agent.d.ts

@@ -1,5 +1,6 @@
 import type { VoiceOnTurnObjectHandler, VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord, VoiceTurnRecord } from './types';
 import type { VoiceTraceEventStore } from './trace';
+import type { VoiceToolRuntime } from './toolRuntime';
 export type VoiceAgentMessageRole = 'assistant' | 'system' | 'tool' | 'user';
 export type VoiceAgentMessage = {
     content: string;
@@ -86,6 +87,7 @@ export type VoiceAgentOptions<TContext = unknown, TSession extends VoiceSessionR
         turn: VoiceTurnRecord;
     }) => Promise<string | undefined> | string | undefined);
     trace?: VoiceTraceEventStore;
+    toolRuntime?: VoiceToolRuntime<TContext, TSession, TResult>;
     tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
 };
 export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { compareVoiceEvalBaseline, createVoiceFileEvalBaselineStore, createVoice
 export { createVoiceWorkflowContract, createVoiceWorkflowContractHandler, createVoiceWorkflowContractPreset, createVoiceWorkflowScenario, recordVoiceWorkflowContractTrace, validateVoiceWorkflowRouteResult } from './workflowContract';
 export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, createVoiceSessionReplayJSONHandler, createVoiceSessionReplayRoutes, createVoiceSessionsHTMLHandler, createVoiceSessionsJSONHandler, renderVoiceSessionsHTML, summarizeVoiceSessions, summarizeVoiceSessionReplay } from './sessionReplay';
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool } from './agent';
+export { createVoiceToolIdempotencyKey, createVoiceToolRuntime } from './toolRuntime';
 export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore } from './fileStore';
 export { createVoiceAssistantMemoryHandle, createVoiceAssistantMemoryRecord, createVoiceMemoryAssistantMemoryStore, resolveVoiceAssistantMemoryNamespace } from './assistantMemory';
 export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
@@ -53,6 +54,7 @@ export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQua
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind } from './resilienceRoutes';
 export type { VoiceIOProviderRouterEvent, VoiceIOProviderRouterOptions, VoiceIOProviderRouterPolicy, VoiceIOProviderRouterPolicyConfig, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions } from './providerAdapters';
 export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
+export type { VoiceToolRetryDelay, VoiceToolRuntime, VoiceToolRuntimeExecuteInput, VoiceToolRuntimeOptions, VoiceToolRuntimeResult } from './toolRuntime';
 export type { VoiceOpsRuntime, VoiceOpsRuntimeConfig, VoiceOpsRuntimeSummary, VoiceOpsRuntimeSinkWorkerConfig, VoiceOpsRuntimeTaskWorkerConfig, VoiceOpsRuntimeTickResult, VoiceOpsRuntimeWebhookWorkerConfig } from './opsRuntime';
 export type { VoiceOpsPresetName, VoiceOpsPresetOverrides, VoiceResolvedOpsPreset } from './opsPresets';
 export type { VoiceOutcomeRecipe, VoiceOutcomeRecipeName, VoiceOutcomeRecipeOptions } from './outcomeRecipes';

package/dist/index.js

@@ -5627,16 +5627,34 @@ var createVoiceAgent = (options) => {
         }
         try {
           const toolStartedAt = Date.now();
-          const result = await tool.execute({
+          const runtimeResult = options.toolRuntime ? await options.toolRuntime.execute({
+            api: input.api,
+            args: toolCall.args,
+            context: input.context,
+            session: input.session,
+            tool,
+            toolCallId: toolCall.id,
+            turn: input.turn
+          }) : undefined;
+          if (runtimeResult?.status === "error") {
+            throw new Error(runtimeResult.error);
+          }
+          const result = runtimeResult?.result ?? await tool.execute({
             api: input.api,
             args: toolCall.args,
             context: input.context,
             session: input.session,
             turn: input.turn
           });
-          const content = tool.resultToMessage?.(result) ?? formatToolResult(result);
+          const content = runtimeResult?.content ?? tool.resultToMessage?.(result) ?? formatToolResult(result);
           toolResults.push({
             content,
+            metadata: runtimeResult ? {
+              attempts: runtimeResult.attempts,
+              elapsedMs: runtimeResult.elapsedMs,
+              idempotencyKey: runtimeResult.idempotencyKey,
+              timedOut: runtimeResult.timedOut
+            } : undefined,
             result,
             status: "ok",
             toolCallId: toolCall.id,
@@ -5646,7 +5664,11 @@ var createVoiceAgent = (options) => {
             agentId: options.id,
             event: {
               elapsedMs: Date.now() - toolStartedAt,
+              runtimeElapsedMs: runtimeResult?.elapsedMs,
+              attempts: runtimeResult?.attempts,
+              idempotencyKey: runtimeResult?.idempotencyKey,
               status: "ok",
+              timedOut: runtimeResult?.timedOut,
               toolCallId: toolCall.id,
               toolName: tool.name
             },
@@ -9728,6 +9750,202 @@ var createVoiceWorkflowContractHandler = (input) => {
     return result;
   };
 };
+// src/toolRuntime.ts
+var toErrorMessage4 = (error) => error instanceof Error ? error.message : String(error);
+var sleep4 = (ms) => new Promise((resolve2) => {
+  setTimeout(resolve2, ms);
+});
+var formatToolResult2 = (result) => {
+  if (typeof result === "string") {
+    return result;
+  }
+  if (result === undefined) {
+    return "";
+  }
+  try {
+    return JSON.stringify(result);
+  } catch {
+    return String(result);
+  }
+};
+var withTimeout = async (promise, timeoutMs) => {
+  if (!timeoutMs || timeoutMs <= 0) {
+    return promise;
+  }
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(`Voice tool timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+};
+var resolveRetryDelay = (retryDelayMs, input) => typeof retryDelayMs === "function" ? retryDelayMs(input) : retryDelayMs ?? 0;
+var createVoiceToolRuntime = (options = {}) => {
+  const inFlight = new Map;
+  const completed = new Map;
+  const execute = async (input) => {
+    const idempotencyKey = options.idempotencyKey?.({
+      args: input.args,
+      context: input.context,
+      session: input.session,
+      toolCallId: input.toolCallId,
+      toolName: input.tool.name,
+      turn: input.turn
+    });
+    if (idempotencyKey) {
+      const cached = completed.get(idempotencyKey);
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.result;
+      }
+      if (cached) {
+        completed.delete(idempotencyKey);
+      }
+      const existing = inFlight.get(idempotencyKey);
+      if (existing) {
+        return await existing;
+      }
+    }
+    const runPromise = (async () => {
+      const startedAt = Date.now();
+      const maxRetries = Math.max(0, options.maxRetries ?? 0);
+      let attempts = 0;
+      let lastError;
+      let timedOut = false;
+      for (let retry = 0;retry <= maxRetries; retry += 1) {
+        attempts = retry + 1;
+        try {
+          const result = await withTimeout(Promise.resolve(input.tool.execute({
+            api: input.api,
+            args: input.args,
+            context: input.context,
+            session: input.session,
+            turn: input.turn
+          })), options.timeoutMs);
+          const elapsedMs2 = Date.now() - startedAt;
+          const content = input.tool.resultToMessage?.(result) ?? formatToolResult2(result);
+          const runtimeResult2 = {
+            attempts,
+            content,
+            elapsedMs: elapsedMs2,
+            idempotencyKey,
+            result,
+            status: "ok",
+            timedOut,
+            toolCallId: input.toolCallId,
+            toolName: input.tool.name
+          };
+          await options.trace?.append({
+            at: Date.now(),
+            payload: {
+              attempts,
+              elapsedMs: elapsedMs2,
+              idempotencyKey,
+              status: "ok",
+              toolCallId: input.toolCallId,
+              toolName: input.tool.name
+            },
+            scenarioId: input.session.scenarioId,
+            sessionId: input.session.id,
+            turnId: input.turn.id,
+            type: "agent.tool"
+          });
+          return runtimeResult2;
+        } catch (error) {
+          lastError = error;
+          timedOut ||= toErrorMessage4(error).includes("timed out");
+          if (retry < maxRetries) {
+            const delay = resolveRetryDelay(options.retryDelayMs, {
+              attempt: attempts,
+              error,
+              toolName: input.tool.name
+            });
+            if (delay > 0) {
+              await sleep4(delay);
+            }
+          }
+        }
+      }
+      const elapsedMs = Date.now() - startedAt;
+      const runtimeResult = {
+        attempts,
+        elapsedMs,
+        error: toErrorMessage4(lastError),
+        idempotencyKey,
+        status: "error",
+        timedOut,
+        toolCallId: input.toolCallId,
+        toolName: input.tool.name
+      };
+      await options.trace?.append({
+        at: Date.now(),
+        payload: {
+          attempts,
+          elapsedMs,
+          error: runtimeResult.error,
+          idempotencyKey,
+          status: "error",
+          timedOut,
+          toolCallId: input.toolCallId,
+          toolName: input.tool.name
+        },
+        scenarioId: input.session.scenarioId,
+        sessionId: input.session.id,
+        turnId: input.turn.id,
+        type: "agent.tool"
+      });
+      return runtimeResult;
+    })();
+    if (idempotencyKey) {
+      inFlight.set(idempotencyKey, runPromise);
+      runPromise.then((result) => {
+        if (options.idempotencyTtlMs && options.idempotencyTtlMs > 0) {
+          completed.set(idempotencyKey, {
+            expiresAt: Date.now() + options.idempotencyTtlMs,
+            result
+          });
+        }
+      }).finally(() => {
+        inFlight.delete(idempotencyKey);
+      });
+    }
+    return await runPromise;
+  };
+  return {
+    execute,
+    wrapTool: (tool) => ({
+      ...tool,
+      execute: async (input) => {
+        const result = await execute({
+          ...input,
+          tool
+        });
+        if (result.status === "error") {
+          throw new Error(result.error);
+        }
+        return result.result;
+      }
+    })
+  };
+};
+var createVoiceToolIdempotencyKey = (input) => {
+  const args = typeof input.args === "string" ? input.args : JSON.stringify(input.args ?? null);
+  return [
+    input.sessionId,
+    input.turnId,
+    input.toolCallId ?? "no-call-id",
+    input.toolName,
+    args
+  ].join(":");
+};
 // src/fileStore.ts
 import { mkdir as mkdir2, readFile, readdir, rename, rm, writeFile } from "fs/promises";
 import { join } from "path";
@@ -10193,7 +10411,7 @@ var getMessageToolCalls = (message) => {
   return Array.isArray(toolCalls) ? toolCalls.filter((toolCall) => toolCall && typeof toolCall === "object" && typeof toolCall.name === "string") : [];
 };
 var createHTTPError = (provider, response) => new Error(`${provider} voice assistant model failed: HTTP ${response.status}`);
-var sleep4 = (ms) => new Promise((resolve2) => {
+var sleep5 = (ms) => new Promise((resolve2) => {
   setTimeout(resolve2, ms);
 });
 var errorMessage = (error) => error instanceof Error ? error.message : String(error);
@@ -10902,7 +11120,7 @@ var createGeminiVoiceAssistantModel = (options) => {
           break;
         }
         const retryAfter = Number(response.headers.get("retry-after"));
-        await sleep4(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt);
+        await sleep5(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt);
       }
       if (!response) {
         throw new Error("Gemini voice assistant model failed: no response");
@@ -10957,7 +11175,7 @@ var getTimeoutMs = (options, provider) => {
   const timeoutMs = options.providerProfiles?.[provider]?.timeoutMs ?? options.timeoutMs;
   return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
 };
-var withTimeout = async (input) => {
+var withTimeout2 = async (input) => {
   if (!input.timeoutMs) {
     return input.run();
   }
@@ -11141,7 +11359,7 @@ var createVoiceSTTProviderRouter = (options) => {
         }
         const startedAt = Date.now();
         try {
-          const session = await withTimeout({
+          const session = await withTimeout2({
             kind: "stt",
             operation: "open",
             provider,
@@ -11218,7 +11436,7 @@ var createVoiceTTSProviderRouter = (options) => {
           throw new Error(`Voice TTS provider ${provider} is not configured.`);
         }
         const startedAt = Date.now();
-        const session = await withTimeout({
+        const session = await withTimeout2({
           kind: "tts",
           operation: "open",
           provider,
@@ -11297,7 +11515,7 @@ var createVoiceTTSProviderRouter = (options) => {
           }
           const startedAt = Date.now();
           try {
-            await withTimeout({
+            await withTimeout2({
               kind: "tts",
               operation: "send",
               provider,
@@ -14194,6 +14412,8 @@ export {
   createVoiceTraceHTTPSink,
   createVoiceTraceEventId,
   createVoiceTraceEvent,
+  createVoiceToolRuntime,
+  createVoiceToolIdempotencyKey,
   createVoiceTaskUpdatedEvent,
   createVoiceTaskSLABreachedEvent,
   createVoiceTaskCreatedEvent,

package/dist/toolRuntime.d.ts

@@ -0,0 +1,50 @@
+import type { VoiceAgentTool, VoiceAgentToolResult } from './agent';
+import type { VoiceSessionHandle, VoiceSessionRecord, VoiceTurnRecord } from './types';
+import type { VoiceTraceEventStore } from './trace';
+export type VoiceToolRetryDelay = number | ((input: {
+    attempt: number;
+    error: unknown;
+    toolName: string;
+}) => number);
+export type VoiceToolRuntimeOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown> = {
+    idempotencyKey?: (input: {
+        args: unknown;
+        context: TContext;
+        session: TSession;
+        toolCallId?: string;
+        toolName: string;
+        turn: VoiceTurnRecord;
+    }) => string | undefined;
+    idempotencyTtlMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: VoiceToolRetryDelay;
+    timeoutMs?: number;
+    trace?: VoiceTraceEventStore;
+};
+export type VoiceToolRuntimeExecuteInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
+    api: VoiceSessionHandle<TContext, TSession, TRouteResult>;
+    args: TArgs;
+    context: TContext;
+    session: TSession;
+    tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+    toolCallId?: string;
+    turn: VoiceTurnRecord;
+};
+export type VoiceToolRuntimeResult<TToolResult = unknown> = VoiceAgentToolResult<TToolResult> & {
+    attempts: number;
+    elapsedMs: number;
+    idempotencyKey?: string;
+    timedOut: boolean;
+};
+export type VoiceToolRuntime<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown> = {
+    execute: <TArgs = Record<string, unknown>, TToolResult = unknown>(input: VoiceToolRuntimeExecuteInput<TContext, TSession, TArgs, TToolResult, TRouteResult>) => Promise<VoiceToolRuntimeResult<TToolResult>>;
+    wrapTool: <TArgs = Record<string, unknown>, TToolResult = unknown>(tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>) => VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+};
+export declare const createVoiceToolRuntime: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown>(options?: VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>) => VoiceToolRuntime<TContext, TSession, TRouteResult>;
+export declare const createVoiceToolIdempotencyKey: (input: {
+    args: unknown;
+    sessionId: string;
+    toolCallId?: string;
+    toolName: string;
+    turnId: string;
+}) => string;

package/package.json

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