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

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { createVoiceWorkflowContract, createVoiceWorkflowContractHandler, create
 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';
@@ -55,6 +56,7 @@ export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePa
 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

@@ -9946,6 +9946,163 @@ var createVoiceToolIdempotencyKey = (input) => {
     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";
@@ -14334,6 +14491,7 @@ export {
   startVoiceOpsTask,
   shapeTelephonyAssistantText,
   selectVoiceTraceEventsForPrune,
+  runVoiceToolContract,
   runVoiceSessionEvals,
   runVoiceScenarioFixtureEvals,
   runVoiceScenarioEvals,
@@ -14412,8 +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/package.json

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