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

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,8 @@ 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 { createVoiceToolContract, createVoiceToolRuntimeContractDefaults, runVoiceToolContract } from './toolContract';
 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 +55,8 @@ 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 { VoiceToolContractCase, VoiceToolContractCaseReport, VoiceToolContractDefinition, VoiceToolContractExpectation, VoiceToolContractIssue, VoiceToolContractReport } from './toolContract';
 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,359 @@ 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/toolContract.ts
+var createDefaultSession = (contractId, caseId) => createVoiceSessionRecord(`tool-contract-${contractId}-${caseId}`);
+var createDefaultTurn = (caseId) => ({
+  committedAt: Date.now(),
+  id: `turn-${caseId}`,
+  text: `Run tool contract case ${caseId}.`,
+  transcripts: []
+});
+var defaultApi = {};
+var sameJSON = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+var evaluateExpectation = (input) => {
+  const issues = [];
+  const expect = input.expect;
+  if (!expect) {
+    return issues;
+  }
+  if (expect.expectStatus && input.status !== expect.expectStatus) {
+    issues.push({
+      caseId: input.caseId,
+      code: "tool.status_mismatch",
+      message: `Expected ${expect.expectStatus}, saw ${input.status}.`
+    });
+  }
+  if (typeof expect.expectedAttempts === "number" && input.attempts !== expect.expectedAttempts) {
+    issues.push({
+      caseId: input.caseId,
+      code: "tool.attempt_mismatch",
+      message: `Expected ${expect.expectedAttempts} attempts, saw ${input.attempts}.`
+    });
+  }
+  if (expect.expectedResult !== undefined && !sameJSON(input.result, expect.expectedResult)) {
+    issues.push({
+      caseId: input.caseId,
+      code: "tool.result_mismatch",
+      message: "Tool result did not match expected result."
+    });
+  }
+  if (expect.expectedErrorIncludes && !input.error?.includes(expect.expectedErrorIncludes)) {
+    issues.push({
+      caseId: input.caseId,
+      code: "tool.error_mismatch",
+      message: `Expected error to include ${expect.expectedErrorIncludes}.`
+    });
+  }
+  if (typeof expect.expectTimedOut === "boolean" && input.timedOut !== expect.expectTimedOut) {
+    issues.push({
+      caseId: input.caseId,
+      code: "tool.timeout_mismatch",
+      message: `Expected timedOut=${String(expect.expectTimedOut)}, saw ${String(input.timedOut)}.`
+    });
+  }
+  if (typeof expect.maxElapsedMs === "number" && input.elapsedMs > expect.maxElapsedMs) {
+    issues.push({
+      caseId: input.caseId,
+      code: "tool.elapsed_exceeded",
+      message: `Expected elapsed <= ${expect.maxElapsedMs}ms, saw ${input.elapsedMs}ms.`
+    });
+  }
+  return issues;
+};
+var runVoiceToolContract = async (definition) => {
+  const cases = [];
+  for (const testCase of definition.cases) {
+    const session = testCase.session ?? createDefaultSession(definition.id, testCase.id);
+    const turn = testCase.turn ?? createDefaultTurn(testCase.id);
+    const context = testCase.context ?? {};
+    const runtimeOptions = {
+      ...definition.defaultRuntime,
+      ...testCase.runtime
+    };
+    const runtime = createVoiceToolRuntime(runtimeOptions);
+    const toolCall = {
+      args: testCase.args,
+      id: testCase.toolCallId ?? testCase.id,
+      name: definition.tool.name
+    };
+    const executeOnce = () => runtime.execute({
+      api: defaultApi,
+      args: toolCall.args,
+      context,
+      session,
+      tool: definition.tool,
+      toolCallId: toolCall.id,
+      turn
+    });
+    const result = await executeOnce();
+    let issues2 = evaluateExpectation({
+      attempts: result.attempts,
+      caseId: testCase.id,
+      elapsedMs: result.elapsedMs,
+      error: result.error,
+      expect: testCase.expect,
+      result: result.result,
+      status: result.status,
+      timedOut: result.timedOut
+    });
+    if (testCase.expect?.expectIdempotent) {
+      const second = await executeOnce();
+      if (second.result !== result.result && !sameJSON(second.result, result.result)) {
+        issues2.push({
+          caseId: testCase.id,
+          code: "tool.idempotency_result_mismatch",
+          message: "Repeated idempotent execution returned a different result."
+        });
+      }
+      if (second.idempotencyKey !== result.idempotencyKey) {
+        issues2.push({
+          caseId: testCase.id,
+          code: "tool.idempotency_key_mismatch",
+          message: "Repeated idempotent execution used a different idempotency key."
+        });
+      }
+    }
+    cases.push({
+      attempts: result.attempts,
+      caseId: testCase.id,
+      elapsedMs: result.elapsedMs,
+      error: result.error,
+      issues: issues2,
+      label: testCase.label,
+      pass: issues2.length === 0,
+      status: result.status,
+      timedOut: result.timedOut
+    });
+  }
+  const issues = cases.flatMap((testCase) => testCase.issues);
+  return {
+    cases,
+    contractId: definition.id,
+    issues,
+    pass: issues.length === 0,
+    toolName: definition.tool.name
+  };
+};
+var createVoiceToolContract = (definition) => ({
+  assert: async () => {
+    const report = await runVoiceToolContract(definition);
+    if (!report.pass) {
+      throw new Error(`Voice tool contract ${definition.id} failed: ${report.issues.map((issue) => issue.message).join(" ")}`);
+    }
+    return report;
+  },
+  definition,
+  run: () => runVoiceToolContract(definition)
+});
+var createVoiceToolRuntimeContractDefaults = () => ({
+  idempotencyKey: ({ args, session, toolCallId, toolName, turn }) => createVoiceToolIdempotencyKey({
+    args,
+    sessionId: session.id,
+    toolCallId,
+    toolName,
+    turnId: turn.id
+  }),
+  idempotencyTtlMs: 60000,
+  maxRetries: 1,
+  timeoutMs: 5000
+});
 // src/fileStore.ts
 import { mkdir as mkdir2, readFile, readdir, rename, rm, writeFile } from "fs/promises";
 import { join } from "path";
@@ -10193,7 +10568,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 +11277,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 +11332,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 +11516,7 @@ var createVoiceSTTProviderRouter = (options) => {
         }
         const startedAt = Date.now();
         try {
-          const session = await withTimeout({
+          const session = await withTimeout2({
             kind: "stt",
             operation: "open",
             provider,
@@ -11218,7 +11593,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 +11672,7 @@ var createVoiceTTSProviderRouter = (options) => {
           }
           const startedAt = Date.now();
           try {
-            await withTimeout({
+            await withTimeout2({
               kind: "tts",
               operation: "send",
               provider,
@@ -14116,6 +14491,7 @@ export {
   startVoiceOpsTask,
   shapeTelephonyAssistantText,
   selectVoiceTraceEventsForPrune,
+  runVoiceToolContract,
   runVoiceSessionEvals,
   runVoiceScenarioFixtureEvals,
   runVoiceScenarioEvals,
@@ -14194,6 +14570,10 @@ export {
   createVoiceTraceHTTPSink,
   createVoiceTraceEventId,
   createVoiceTraceEvent,
+  createVoiceToolRuntimeContractDefaults,
+  createVoiceToolRuntime,
+  createVoiceToolIdempotencyKey,
+  createVoiceToolContract,
   createVoiceTaskUpdatedEvent,
   createVoiceTaskSLABreachedEvent,
   createVoiceTaskCreatedEvent,

package/dist/toolContract.d.ts

@@ -0,0 +1,61 @@
+import type { VoiceAgentTool } from './agent';
+import { type VoiceToolRuntimeOptions } from './toolRuntime';
+import type { VoiceSessionRecord, VoiceTurnRecord } from './types';
+export type VoiceToolContractExpectation = {
+    expectedAttempts?: number;
+    expectedErrorIncludes?: string;
+    expectedResult?: unknown;
+    expectIdempotent?: boolean;
+    expectStatus?: 'error' | 'ok';
+    expectTimedOut?: boolean;
+    maxElapsedMs?: number;
+};
+export type VoiceToolContractCase<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
+    args: TArgs;
+    context?: TContext;
+    expect?: VoiceToolContractExpectation;
+    id: string;
+    label?: string;
+    runtime?: VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>;
+    session?: TSession;
+    toolCallId?: string;
+    turn?: VoiceTurnRecord;
+};
+export type VoiceToolContractDefinition<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown> = {
+    cases: Array<VoiceToolContractCase<TContext, TSession, TArgs, TToolResult, TRouteResult>>;
+    defaultRuntime?: VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>;
+    description?: string;
+    id: string;
+    label?: string;
+    tool: VoiceAgentTool<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+};
+export type VoiceToolContractIssue = {
+    caseId: string;
+    code: string;
+    message: string;
+};
+export type VoiceToolContractCaseReport = {
+    attempts: number;
+    caseId: string;
+    elapsedMs: number;
+    error?: string;
+    issues: VoiceToolContractIssue[];
+    label?: string;
+    pass: boolean;
+    status: 'error' | 'ok';
+    timedOut: boolean;
+};
+export type VoiceToolContractReport = {
+    cases: VoiceToolContractCaseReport[];
+    contractId: string;
+    issues: VoiceToolContractIssue[];
+    pass: boolean;
+    toolName: string;
+};
+export declare const runVoiceToolContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown>(definition: VoiceToolContractDefinition<TContext, TSession, TArgs, TToolResult, TRouteResult>) => Promise<VoiceToolContractReport>;
+export declare const createVoiceToolContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TArgs = Record<string, unknown>, TToolResult = unknown, TRouteResult = unknown>(definition: VoiceToolContractDefinition<TContext, TSession, TArgs, TToolResult, TRouteResult>) => {
+    assert: () => Promise<VoiceToolContractReport>;
+    definition: VoiceToolContractDefinition<TContext, TSession, TArgs, TToolResult, TRouteResult>;
+    run: () => Promise<VoiceToolContractReport>;
+};
+export declare const createVoiceToolRuntimeContractDefaults: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TRouteResult = unknown>() => VoiceToolRuntimeOptions<TContext, TSession, TRouteResult>;

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.63",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",