@absolutejs/voice 0.0.22-beta.513 → 0.0.22-beta.514

package/dist/index.d.ts

@@ -341,4 +341,14 @@ export { computeVoiceScorecardCalibration } from "./scorecardCalibration";
 export type { VoiceScorecardCalibrationDivergence, VoiceScorecardCalibrationPair, VoiceScorecardCalibrationReport, } from "./scorecardCalibration";
 export { detectVoiceQualityDrift } from "./qualityDriftDetector";
 export type { DetectVoiceQualityDriftInput, VoiceQualityDriftCriterionAlert, VoiceQualityDriftReport, VoiceQualityDriftSeverity, } from "./qualityDriftDetector";
+export { findVoicePathwaySlot, findVoicePathwayState, validateVoicePathway, } from "./pathway";
+export type { VoicePathway, VoicePathwayAction, VoicePathwayCondition, VoicePathwaySlot, VoicePathwaySlotType, VoicePathwayState, VoicePathwayTransition, VoicePathwayValidationIssue, VoicePathwayValidationReport, } from "./pathway";
+export { createVoicePathwayRuntime } from "./pathwayRuntime";
+export type { CreateVoicePathwayRuntimeOptions, VoicePathwayRuntime, VoicePathwayRuntimeEvent, VoicePathwayRuntimeState, VoicePathwayRuntimeStatus, VoicePathwaySlotValue, VoicePathwayToolCall, } from "./pathwayRuntime";
+export { createVoicePathwaySlotCollector, DEFAULT_VOICE_PATHWAY_SLOT_PARSERS, } from "./pathwaySlotCollector";
+export type { CreateVoicePathwaySlotCollectorOptions, VoicePathwaySlotCollector, VoicePathwaySlotCollectorAttempt, VoicePathwaySlotParser, VoicePathwaySlotParseResult, } from "./pathwaySlotCollector";
+export { compileVoicePathwayToAssistant } from "./pathwayCompiler";
+export type { CompileVoicePathwayOptions, VoicePathwayCompiledAssistant, VoicePathwayCompilerToolDefinition, } from "./pathwayCompiler";
+export { renderVoicePathwayMermaid, renderVoicePathwayText, visualizeVoicePathway, } from "./pathwayVisualizer";
+export type { VoicePathwayVisualization } from "./pathwayVisualizer";
 export * from "./types";

package/dist/index.js

@@ -50589,6 +50589,777 @@ var detectVoiceQualityDrift = (input) => {
     scope: { from: baselineFrom, to: cutoff }
   };
 };
+// src/pathway.ts
+var slotRefsInActions = (actions) => {
+  if (!actions)
+    return [];
+  const refs = [];
+  for (const action of actions) {
+    if (action.kind === "collect-slot")
+      refs.push(action.slotId);
+    if (action.kind === "set-slot")
+      refs.push(action.slotId);
+    if (action.kind === "call-tool" && action.argsFromSlots) {
+      refs.push(...action.argsFromSlots);
+    }
+  }
+  return refs;
+};
+var slotRefsInCondition = (condition) => {
+  if (condition.kind === "always" || condition.kind === "fallback")
+    return [];
+  return [condition.slotId];
+};
+var validateVoicePathway = (pathway) => {
+  const issues = [];
+  const stateIds = new Set;
+  for (const state of pathway.states) {
+    if (stateIds.has(state.id)) {
+      issues.push({
+        code: "duplicate-state",
+        message: `Duplicate state id: ${state.id}`,
+        severity: "error",
+        stateId: state.id
+      });
+    }
+    stateIds.add(state.id);
+  }
+  const slotIds = new Set;
+  for (const slot of pathway.slots) {
+    if (slotIds.has(slot.id)) {
+      issues.push({
+        code: "duplicate-slot",
+        message: `Duplicate slot id: ${slot.id}`,
+        severity: "error",
+        slotId: slot.id
+      });
+    }
+    slotIds.add(slot.id);
+  }
+  if (!stateIds.has(pathway.entryStateId)) {
+    issues.push({
+      code: "unknown-entry",
+      message: `Entry state ${pathway.entryStateId} is not defined`,
+      severity: "error"
+    });
+  }
+  for (const state of pathway.states) {
+    const seenTransitionKeys = new Set;
+    state.transitions.forEach((transition, index) => {
+      if (!stateIds.has(transition.to)) {
+        issues.push({
+          code: "missing-transition-target",
+          message: `State ${state.id} transitions to unknown state ${transition.to}`,
+          severity: "error",
+          stateId: state.id
+        });
+      }
+      const key = `${transition.to}::${transition.condition.kind}::${"slotId" in transition.condition ? transition.condition.slotId : ""}`;
+      if (seenTransitionKeys.has(key)) {
+        issues.push({
+          code: "duplicate-transition",
+          message: `State ${state.id} has duplicate transition to ${transition.to}`,
+          severity: "warning",
+          stateId: state.id
+        });
+      }
+      seenTransitionKeys.add(key);
+      if (transition.condition.kind === "fallback" && index !== state.transitions.length - 1) {
+        issues.push({
+          code: "fallback-not-last",
+          message: `Fallback transition in ${state.id} must be the last transition`,
+          severity: "error",
+          stateId: state.id
+        });
+      }
+      for (const ref of slotRefsInCondition(transition.condition)) {
+        if (!slotIds.has(ref)) {
+          issues.push({
+            code: "missing-slot-ref",
+            message: `Transition condition references unknown slot ${ref}`,
+            severity: "error",
+            slotId: ref,
+            stateId: state.id
+          });
+        }
+      }
+    });
+    for (const ref of slotRefsInActions(state.actions)) {
+      if (!slotIds.has(ref)) {
+        issues.push({
+          code: "missing-slot-ref",
+          message: `Action in ${state.id} references unknown slot ${ref}`,
+          severity: "error",
+          slotId: ref,
+          stateId: state.id
+        });
+      }
+    }
+  }
+  const reachable = new Set;
+  const queue = stateIds.has(pathway.entryStateId) ? [pathway.entryStateId] : [];
+  const stateById = new Map(pathway.states.map((s) => [s.id, s]));
+  while (queue.length > 0) {
+    const id = queue.shift();
+    if (reachable.has(id))
+      continue;
+    reachable.add(id);
+    const state = stateById.get(id);
+    if (!state)
+      continue;
+    for (const transition of state.transitions) {
+      if (stateIds.has(transition.to) && !reachable.has(transition.to)) {
+        queue.push(transition.to);
+      }
+    }
+  }
+  for (const state of pathway.states) {
+    if (!reachable.has(state.id)) {
+      issues.push({
+        code: "unreachable-state",
+        message: `State ${state.id} is not reachable from entry ${pathway.entryStateId}`,
+        severity: "warning",
+        stateId: state.id
+      });
+    }
+  }
+  const hasReachableTerminal = pathway.states.some((state) => reachable.has(state.id) && (state.kind === "terminal" || state.transitions.length === 0));
+  if (!hasReachableTerminal) {
+    issues.push({
+      code: "no-terminal-reachable",
+      message: "No terminal state is reachable; pathway has no exit condition",
+      severity: "error"
+    });
+  }
+  const fatal = issues.some((i) => i.severity === "error");
+  return {
+    issues,
+    reachableStates: Array.from(reachable),
+    valid: !fatal
+  };
+};
+var findVoicePathwayState = (pathway, id) => pathway.states.find((s) => s.id === id) ?? null;
+var findVoicePathwaySlot = (pathway, id) => pathway.slots.find((s) => s.id === id) ?? null;
+// src/pathwayRuntime.ts
+var evaluateCondition = (condition, slots) => {
+  switch (condition.kind) {
+    case "always":
+      return true;
+    case "fallback":
+      return true;
+    case "slot-filled":
+      return slots[condition.slotId] !== undefined && slots[condition.slotId] !== null && slots[condition.slotId] !== "";
+    case "slot-equals":
+      return slots[condition.slotId] === condition.value;
+    case "slot-matches": {
+      const raw = slots[condition.slotId];
+      if (typeof raw !== "string")
+        return false;
+      try {
+        return new RegExp(condition.pattern, "u").test(raw);
+      } catch {
+        return false;
+      }
+    }
+  }
+};
+var pickTransition = (state, slots) => {
+  for (const transition of state.transitions) {
+    if (transition.condition.kind === "fallback")
+      continue;
+    if (evaluateCondition(transition.condition, slots))
+      return transition;
+  }
+  const fallback = state.transitions.find((t) => t.condition.kind === "fallback");
+  return fallback ?? null;
+};
+var buildPendingActions = (state, slots, pathway, emit2) => {
+  const pending = [];
+  let awaitingSlotId = null;
+  for (const action of state.actions ?? []) {
+    if (action.kind === "say") {
+      emit2({ text: action.text, type: "say" });
+      continue;
+    }
+    if (action.kind === "collect-slot") {
+      if (slots[action.slotId] === undefined || slots[action.slotId] === null) {
+        const slot = findVoicePathwaySlot(pathway, action.slotId);
+        emit2({
+          prompt: slot?.prompt ?? `Please provide ${action.slotId}.`,
+          slotId: action.slotId,
+          type: "ask-slot"
+        });
+        awaitingSlotId = action.slotId;
+        break;
+      }
+      continue;
+    }
+    if (action.kind === "call-tool") {
+      const args = {};
+      for (const id of action.argsFromSlots ?? []) {
+        args[id] = slots[id] ?? null;
+      }
+      emit2({ call: { args, toolId: action.toolId }, type: "tool-call" });
+      continue;
+    }
+    if (action.kind === "set-slot") {
+      pending.push(action);
+      continue;
+    }
+    if (action.kind === "transfer") {
+      emit2({ destination: action.destination, type: "transfer" });
+      return { actions: pending, awaitingSlotId: null, ended: true, reason: `transfer:${action.destination}` };
+    }
+    if (action.kind === "end-call") {
+      emit2({ ...action.reason !== undefined ? { reason: action.reason } : {}, type: "end-call" });
+      return { actions: pending, awaitingSlotId: null, ended: true, ...action.reason !== undefined ? { reason: action.reason } : {} };
+    }
+  }
+  return { actions: pending, awaitingSlotId, ended: false };
+};
+var createVoicePathwayRuntime = (options) => {
+  if (!options.skipValidation) {
+    const report = validateVoicePathway(options.pathway);
+    if (!report.valid) {
+      throw new Error(`Invalid pathway: ${report.issues.filter((i) => i.severity === "error").map((i) => i.message).join("; ")}`);
+    }
+  }
+  const now = options.now ?? (() => Date.now());
+  const listeners = new Set;
+  const emit2 = (event) => {
+    for (const l of listeners)
+      l(event);
+  };
+  let state = {
+    awaitingSlotId: null,
+    currentStateId: options.pathway.entryStateId,
+    history: [],
+    pendingActions: [],
+    slots: { ...options.initialSlots ?? {} },
+    status: "ready"
+  };
+  const enter = (stateId) => {
+    const target = findVoicePathwayState(options.pathway, stateId);
+    if (!target) {
+      state = { ...state, lastError: `Unknown state ${stateId}`, status: "errored" };
+      emit2({ message: state.lastError, type: "errored" });
+      return;
+    }
+    state = {
+      ...state,
+      currentStateId: stateId,
+      history: [...state.history, { at: now(), stateId }],
+      pendingActions: []
+    };
+    emit2({ stateId, type: "state-entered" });
+    const result = buildPendingActions(target, state.slots, options.pathway, emit2);
+    state = {
+      ...state,
+      awaitingSlotId: result.awaitingSlotId,
+      pendingActions: result.actions,
+      status: result.ended ? "ended" : result.awaitingSlotId ? "awaiting-slot" : "branching",
+      ...result.reason !== undefined ? { endedReason: result.reason } : {}
+    };
+    if (state.status === "branching")
+      tryTransition();
+  };
+  const tryTransition = () => {
+    const current = findVoicePathwayState(options.pathway, state.currentStateId);
+    if (!current)
+      return;
+    if (current.transitions.length === 0) {
+      state = { ...state, status: "ended" };
+      return;
+    }
+    const transition = pickTransition(current, state.slots);
+    if (!transition) {
+      state = { ...state, status: "awaiting-slot" };
+      return;
+    }
+    enter(transition.to);
+  };
+  const start = () => {
+    state.history = [];
+    enter(options.pathway.entryStateId);
+  };
+  const fillSlot = (slotId, value) => {
+    state = { ...state, slots: { ...state.slots, [slotId]: value } };
+    if (state.awaitingSlotId === slotId) {
+      state = { ...state, awaitingSlotId: null, status: "branching" };
+      const current = findVoicePathwayState(options.pathway, state.currentStateId);
+      if (current) {
+        const result = buildPendingActions(current, state.slots, options.pathway, emit2);
+        state = {
+          ...state,
+          awaitingSlotId: result.awaitingSlotId,
+          pendingActions: result.actions,
+          status: result.ended ? "ended" : result.awaitingSlotId ? "awaiting-slot" : "branching",
+          ...result.reason !== undefined ? { endedReason: result.reason } : {}
+        };
+        if (state.status === "branching")
+          tryTransition();
+      }
+    }
+  };
+  return {
+    fillSlot,
+    getState: () => state,
+    start,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    tryTransition
+  };
+};
+// src/pathwaySlotCollector.ts
+var numberWords = {
+  eight: 8,
+  five: 5,
+  four: 4,
+  nine: 9,
+  one: 1,
+  seven: 7,
+  six: 6,
+  ten: 10,
+  three: 3,
+  two: 2,
+  zero: 0
+};
+var parseString = (raw, slot) => {
+  const trimmed = raw.trim();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  const min = slot.validation?.minLength ?? 1;
+  const max = slot.validation?.maxLength ?? Number.MAX_SAFE_INTEGER;
+  if (trimmed.length < min || trimmed.length > max) {
+    return {
+      hint: `Expected ${min}\u2013${max} characters`,
+      ok: false,
+      reason: "out-of-range"
+    };
+  }
+  if (slot.validation?.pattern) {
+    try {
+      if (!new RegExp(slot.validation.pattern, "u").test(trimmed)) {
+        return { ok: false, reason: "no-match" };
+      }
+    } catch {
+      return { ok: false, reason: "no-match" };
+    }
+  }
+  return { normalized: trimmed, ok: true, value: trimmed };
+};
+var parseNumber = (raw, slot) => {
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  let value;
+  if (numberWords[trimmed] !== undefined) {
+    value = numberWords[trimmed];
+  } else {
+    const cleaned = trimmed.replace(/[$,]/gu, "");
+    value = Number(cleaned);
+    if (Number.isNaN(value))
+      return { ok: false, reason: "type-mismatch" };
+  }
+  const min = slot.validation?.min ?? Number.NEGATIVE_INFINITY;
+  const max = slot.validation?.max ?? Number.POSITIVE_INFINITY;
+  if (value < min || value > max) {
+    return { hint: `Expected ${min}\u2013${max}`, ok: false, reason: "out-of-range" };
+  }
+  return { normalized: String(value), ok: true, value };
+};
+var parseBoolean2 = (raw) => {
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  if (["yes", "yeah", "yep", "correct", "true", "sure", "ok"].includes(trimmed)) {
+    return { normalized: "true", ok: true, value: true };
+  }
+  if (["no", "nope", "nah", "false", "incorrect"].includes(trimmed)) {
+    return { normalized: "false", ok: true, value: false };
+  }
+  return { ok: false, reason: "type-mismatch" };
+};
+var parseDate = (raw) => {
+  const trimmed = raw.trim();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  const date = new Date(trimmed);
+  if (Number.isNaN(date.getTime()))
+    return { ok: false, reason: "type-mismatch" };
+  const iso = date.toISOString().slice(0, 10);
+  return { normalized: iso, ok: true, value: iso };
+};
+var parseTime2 = (raw) => {
+  const trimmed = raw.trim();
+  const match = /^([0-9]{1,2}):?([0-9]{2})?\s*(am|pm)?$/iu.exec(trimmed);
+  if (!match)
+    return { ok: false, reason: "type-mismatch" };
+  let hour = Number(match[1]);
+  const minute = Number(match[2] ?? "0");
+  const meridiem = match[3]?.toLowerCase();
+  if (meridiem === "pm" && hour < 12)
+    hour += 12;
+  if (meridiem === "am" && hour === 12)
+    hour = 0;
+  if (hour > 23 || minute > 59)
+    return { ok: false, reason: "out-of-range" };
+  const formatted = `${String(hour).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+  return { normalized: formatted, ok: true, value: formatted };
+};
+var parsePhone = (raw) => {
+  const trimmed = raw.trim();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  const digits = trimmed.replace(/\D/gu, "");
+  if (digits.length < 10 || digits.length > 15) {
+    return { ok: false, reason: "type-mismatch" };
+  }
+  const normalized = digits.length === 10 ? `+1${digits}` : `+${digits}`;
+  return { normalized, ok: true, value: normalized };
+};
+var parseEmail = (raw) => {
+  const trimmed = raw.trim();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  const collapsed = trimmed.replace(/\s+at\s+/gu, "@").replace(/\s+dot\s+/gu, ".");
+  const ok = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/iu.test(collapsed);
+  if (!ok)
+    return { ok: false, reason: "type-mismatch" };
+  return { normalized: collapsed.toLowerCase(), ok: true, value: collapsed.toLowerCase() };
+};
+var parseCurrency = (raw, slot) => {
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  const cleaned = trimmed.replace(/[$,]/gu, "").replace(/\s*(dollars?|usd)$/u, "");
+  const value = Number(cleaned);
+  if (Number.isNaN(value))
+    return { ok: false, reason: "type-mismatch" };
+  const min = slot.validation?.min ?? 0;
+  const max = slot.validation?.max ?? Number.POSITIVE_INFINITY;
+  if (value < min || value > max) {
+    return { hint: `Expected ${min}\u2013${max}`, ok: false, reason: "out-of-range" };
+  }
+  return { normalized: value.toFixed(2), ok: true, value };
+};
+var parseChoice = (raw, slot) => {
+  const trimmed = raw.trim().toLowerCase();
+  if (!trimmed)
+    return { ok: false, reason: "empty" };
+  const match = (slot.choices ?? []).find((choice) => choice.toLowerCase() === trimmed);
+  if (!match)
+    return { ok: false, reason: "no-match" };
+  return { normalized: match, ok: true, value: match };
+};
+var DEFAULT_VOICE_PATHWAY_SLOT_PARSERS = {
+  boolean: parseBoolean2,
+  choice: parseChoice,
+  currency: parseCurrency,
+  date: parseDate,
+  email: parseEmail,
+  number: parseNumber,
+  phone: parsePhone,
+  string: parseString,
+  time: parseTime2
+};
+var createVoicePathwaySlotCollector = (options = {}) => {
+  const parsers = {
+    ...DEFAULT_VOICE_PATHWAY_SLOT_PARSERS,
+    ...options.parsers ?? {}
+  };
+  const maxAttempts = options.maxAttemptsPerSlot ?? 3;
+  const attemptCounts = new Map;
+  const interpret = (slot, raw) => {
+    const parser = parsers[slot.type];
+    if (!parser) {
+      return {
+        attempt: (attemptCounts.get(slot.id) ?? 0) + 1,
+        raw,
+        result: {
+          hint: `No parser for ${slot.type}`,
+          ok: false,
+          reason: "no-match"
+        },
+        slotId: slot.id
+      };
+    }
+    const next = (attemptCounts.get(slot.id) ?? 0) + 1;
+    attemptCounts.set(slot.id, next);
+    return {
+      attempt: next,
+      raw,
+      result: parser(raw, slot),
+      slotId: slot.id
+    };
+  };
+  const attemptsExceeded = (slotId) => (attemptCounts.get(slotId) ?? 0) >= maxAttempts;
+  return {
+    attemptsExceeded,
+    interpret,
+    reset: (slotId) => {
+      if (slotId)
+        attemptCounts.delete(slotId);
+      else
+        attemptCounts.clear();
+    }
+  };
+};
+// src/pathwayCompiler.ts
+var describeAction = (action) => {
+  switch (action.kind) {
+    case "say":
+      return `Say to the caller: "${action.text}"`;
+    case "collect-slot":
+      return `Collect slot \`${action.slotId}\` from the caller.`;
+    case "call-tool":
+      return `Call tool \`${action.toolId}\`${action.argsFromSlots ? ` with slots: ${action.argsFromSlots.join(", ")}` : ""}.`;
+    case "set-slot":
+      return `Set slot \`${action.slotId}\` to expression \`${action.valueExpression}\`.`;
+    case "transfer":
+      return `Transfer the call to \`${action.destination}\`.`;
+    case "end-call":
+      return `End the call${action.reason ? ` (reason: ${action.reason})` : ""}.`;
+  }
+};
+var describeCondition = (condition) => {
+  switch (condition.kind) {
+    case "always":
+      return "always";
+    case "fallback":
+      return "if no other condition matches";
+    case "slot-filled":
+      return `when slot \`${condition.slotId}\` is filled`;
+    case "slot-equals":
+      return `when slot \`${condition.slotId}\` equals ${JSON.stringify(condition.value)}`;
+    case "slot-matches":
+      return `when slot \`${condition.slotId}\` matches /${condition.pattern}/`;
+  }
+};
+var describeTransition = (transition) => `\u2192 ${transition.to} (${describeCondition(transition.condition)})`;
+var describeState = (state) => {
+  const header = `## State: ${state.id} \u2014 ${state.label}${state.kind ? ` (${state.kind})` : ""}`;
+  const description = state.description ? `
+${state.description}` : "";
+  const note = state.systemNote ? `
+Note: ${state.systemNote}` : "";
+  const actions = (state.actions ?? []).map((a) => `- ${describeAction(a)}`).join(`
+`);
+  const transitions = state.transitions.map((t) => `- ${describeTransition(t)}`).join(`
+`);
+  return [
+    header,
+    description,
+    note,
+    actions ? `
+Actions:
+${actions}` : "",
+    transitions ? `
+Transitions:
+${transitions}` : ""
+  ].filter((s) => s.length > 0).join(`
+`);
+};
+var buildTools = (pathway, prefix) => {
+  const advanceTool = {
+    description: `Advance the ${pathway.label} pathway by transitioning to the next state. Always call when a state's conditions are met.`,
+    name: `${prefix}_advance`,
+    parameters: {
+      properties: {
+        rationale: {
+          description: "Why this transition is being taken now.",
+          type: "string"
+        },
+        toStateId: {
+          description: "ID of the target state.",
+          enum: pathway.states.map((s) => s.id),
+          type: "string"
+        }
+      },
+      required: ["toStateId"],
+      type: "object"
+    }
+  };
+  const fillSlotTool = {
+    description: `Record a slot value collected from the caller within the ${pathway.label} pathway.`,
+    name: `${prefix}_fill_slot`,
+    parameters: {
+      properties: {
+        slotId: {
+          description: "ID of the slot being filled.",
+          enum: pathway.slots.map((s) => s.id),
+          type: "string"
+        },
+        value: {
+          description: "The value the caller provided.",
+          type: "string"
+        }
+      },
+      required: ["slotId", "value"],
+      type: "object"
+    }
+  };
+  const endCallTool = {
+    description: `End the ${pathway.label} call.`,
+    name: `${prefix}_end_call`,
+    parameters: {
+      properties: {
+        reason: { description: "Reason for ending.", type: "string" }
+      },
+      required: [],
+      type: "object"
+    }
+  };
+  const userTools = (pathway.tools ?? []).map((tool) => ({
+    description: tool.description,
+    name: `${prefix}_tool_${tool.id}`,
+    parameters: {
+      properties: {
+        arguments: { description: "JSON-encoded arguments.", type: "string" }
+      },
+      required: [],
+      type: "object"
+    }
+  }));
+  return [advanceTool, fillSlotTool, endCallTool, ...userTools];
+};
+var compileVoicePathwayToAssistant = (options) => {
+  const report = validateVoicePathway(options.pathway);
+  if (!report.valid) {
+    throw new Error(`Cannot compile invalid pathway: ${report.issues.filter((i) => i.severity === "error").map((i) => i.message).join("; ")}`);
+  }
+  const prefix = options.toolNamePrefix ?? `pathway_${options.pathway.id}`;
+  const tools = buildTools(options.pathway, prefix);
+  const fallback = options.fallbackBehavior === "end-call" ? "If no transition condition is met, end the call politely." : options.fallbackBehavior === "transfer" ? "If no transition condition is met, transfer to a human agent." : "If no transition condition is met, ask a clarifying question and stay in the current state.";
+  const slotBlock = options.pathway.slots.map((slot) => `- \`${slot.id}\` (${slot.type}${slot.required ? ", required" : ""}): ${slot.description ?? slot.prompt}`).join(`
+`);
+  const stateBlock = options.pathway.states.map(describeState).join(`
+
+`);
+  const systemPrompt = [
+    `You are operating the "${options.pathway.label}" pathway as a voice agent.`,
+    `Follow the state machine exactly. Use the provided tools to advance states, fill slots, and end the call.`,
+    `Start in state \`${options.pathway.entryStateId}\`. Track which state you are in. Do not invent states or transitions.`,
+    fallback,
+    "",
+    `Slots:
+${slotBlock || "(none)"}`,
+    "",
+    `States:
+${stateBlock}`
+  ].join(`
+`);
+  return {
+    metadata: {
+      entryStateId: options.pathway.entryStateId,
+      pathwayId: options.pathway.id,
+      pathwayLabel: options.pathway.label
+    },
+    systemPrompt,
+    tools,
+    ...options.introduction !== undefined ? { initialPrompt: options.introduction } : {}
+  };
+};
+// src/pathwayVisualizer.ts
+var escapeMermaidLabel = (text) => text.replace(/[<>"]/gu, "").replace(/\|/gu, "/");
+var conditionLabel = (condition) => {
+  switch (condition.kind) {
+    case "always":
+      return "always";
+    case "fallback":
+      return "else";
+    case "slot-filled":
+      return `${condition.slotId} \u2713`;
+    case "slot-equals":
+      return `${condition.slotId}=${condition.value}`;
+    case "slot-matches":
+      return `${condition.slotId}~/${condition.pattern}/`;
+  }
+};
+var mermaidShape = (state) => {
+  switch (state.kind) {
+    case "entry":
+      return { close: ")", open: "((" };
+    case "terminal":
+      return { close: "))", open: "((" };
+    case "branch":
+      return { close: "}", open: "{" };
+    case "action":
+      return { close: "]", open: "[" };
+    case "collect":
+      return { close: "]", open: "[" };
+    default:
+      return { close: "]", open: "[" };
+  }
+};
+var renderVoicePathwayMermaid = (pathway) => {
+  const lines = ["flowchart TD"];
+  for (const state of pathway.states) {
+    const shape = mermaidShape(state);
+    const label = escapeMermaidLabel(`${state.id}: ${state.label}`);
+    lines.push(`    ${state.id}${shape.open}"${label}"${shape.close}`);
+  }
+  for (const state of pathway.states) {
+    for (const transition of state.transitions) {
+      const label = escapeMermaidLabel(conditionLabel(transition.condition));
+      lines.push(`    ${state.id} -- "${label}" --> ${transition.to}`);
+    }
+  }
+  return lines.join(`
+`);
+};
+var renderVoicePathwayText = (pathway) => {
+  const stateById = new Map(pathway.states.map((s) => [s.id, s]));
+  const visited = new Set;
+  const lines = [
+    `Pathway: ${pathway.label} (${pathway.id})`,
+    `Entry: ${pathway.entryStateId}`,
+    ""
+  ];
+  if (pathway.slots.length > 0) {
+    lines.push("Slots:");
+    for (const slot of pathway.slots) {
+      lines.push(`  - ${slot.id} (${slot.type}${slot.required ? ", required" : ""}): ${slot.prompt}`);
+    }
+    lines.push("");
+  }
+  const walk = (stateId, depth) => {
+    if (visited.has(stateId)) {
+      lines.push(`${"  ".repeat(depth)}\u2192 ${stateId} (already shown)`);
+      return;
+    }
+    visited.add(stateId);
+    const state = stateById.get(stateId);
+    if (!state) {
+      lines.push(`${"  ".repeat(depth)}\u2192 ${stateId} (missing)`);
+      return;
+    }
+    const indent = "  ".repeat(depth);
+    const kind = state.kind ? ` [${state.kind}]` : "";
+    lines.push(`${indent}- ${state.id}: ${state.label}${kind}`);
+    if (state.actions && state.actions.length > 0) {
+      for (const action of state.actions) {
+        lines.push(`${indent}    \xB7 ${action.kind}`);
+      }
+    }
+    for (const transition of state.transitions) {
+      lines.push(`${indent}    \u2192 ${transition.to} (${conditionLabel(transition.condition)})`);
+      walk(transition.to, depth + 1);
+    }
+  };
+  lines.push("States:");
+  walk(pathway.entryStateId, 1);
+  return lines.join(`
+`);
+};
+var visualizeVoicePathway = (pathway) => ({
+  mermaid: renderVoicePathwayMermaid(pathway),
+  text: renderVoicePathwayText(pathway)
+});
 export {
   writeVoiceProofPack,
   writeVoiceMediaPipelineArtifacts,
@@ -50603,12 +51374,14 @@ export {
   voiceComplianceRedactionDefaults,
   voiceAgentUIStateOrder,
   voice,
+  visualizeVoicePathway,
   verifyVoiceWebhookSignature,
   verifyVoiceTwilioWebhookSignature,
   verifyVoiceTelnyxWebhookSignature,
   verifyVoicePlivoWebhookSignature,
   verifyVoiceOpsWebhookSignature,
   validateVoiceWorkflowRouteResult,
+  validateVoicePathway,
   validateVoiceObservabilityExportRecord,
   validateVoiceDTMFLuhn,
   ttsAdapterSessionCanCancel,
@@ -50759,6 +51532,8 @@ export {
   renderVoiceProductionReadinessHTML,
   renderVoicePostCallAnalysisMarkdown,
   renderVoicePhoneAgentProductionSmokeHTML,
+  renderVoicePathwayText,
+  renderVoicePathwayMermaid,
   renderVoiceOutcomeContractHTML,
   renderVoiceOpsStatusHTML,
   renderVoiceOpsRecoveryMarkdown,
@@ -50872,6 +51647,8 @@ export {
   fromVapiAssistantConfig,
   formatVoiceProofTrendAge,
   formatVoiceCallPlayerTimestamp,
+  findVoicePathwayState,
+  findVoicePathwaySlot,
   filterVoiceTraceEvents,
   filterVoiceAuditEvents,
   fetchVoiceProofTarget,
@@ -51127,6 +51904,8 @@ export {
   createVoicePhoneAgentProductionSmokeJSONHandler,
   createVoicePhoneAgentProductionSmokeHTMLHandler,
   createVoicePhoneAgent,
+  createVoicePathwaySlotCollector,
+  createVoicePathwayRuntime,
   createVoiceOutcomeContractRoutes,
   createVoiceOutcomeContractJSONHandler,
   createVoiceOutcomeContractHTMLHandler,
@@ -51332,6 +52111,7 @@ export {
   computeVoiceScorecardCalibration,
   computePcmDurationMs,
   completeVoiceOpsTask,
+  compileVoicePathwayToAssistant,
   compareVoiceEvalBaseline,
   compareVoiceCostScenarios,
   collectVoiceDTMFInput,
@@ -51502,6 +52282,7 @@ export {
   DEFAULT_VOICE_PROMPT_INJECTION_RULES,
   DEFAULT_VOICE_PRICE_BOOK,
   DEFAULT_VOICE_POST_CALL_SURVEY_QUESTIONS,
+  DEFAULT_VOICE_PATHWAY_SLOT_PARSERS,
   DEFAULT_VOICE_CAMPAIGN_TEMPLATE_FILTERS,
   DEFAULT_VOICE_CALL_DISPOSITIONS,
   DEFAULT_VOICE_ANNOTATION_KIND_SEVERITY,

package/dist/pathway.d.ts

@@ -0,0 +1,94 @@
+export type VoicePathwaySlotType = "string" | "number" | "boolean" | "date" | "time" | "phone" | "email" | "currency" | "choice";
+export type VoicePathwaySlot = {
+    id: string;
+    type: VoicePathwaySlotType;
+    prompt: string;
+    required?: boolean;
+    choices?: string[];
+    description?: string;
+    validation?: {
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+        min?: number;
+        max?: number;
+    };
+};
+export type VoicePathwayCondition = {
+    kind: "slot-equals";
+    slotId: string;
+    value: string | number | boolean;
+} | {
+    kind: "slot-filled";
+    slotId: string;
+} | {
+    kind: "slot-matches";
+    slotId: string;
+    pattern: string;
+} | {
+    kind: "always";
+} | {
+    kind: "fallback";
+};
+export type VoicePathwayAction = {
+    kind: "say";
+    text: string;
+} | {
+    kind: "collect-slot";
+    slotId: string;
+} | {
+    kind: "call-tool";
+    toolId: string;
+    argsFromSlots?: string[];
+} | {
+    kind: "set-slot";
+    slotId: string;
+    valueExpression: string;
+} | {
+    kind: "transfer";
+    destination: string;
+} | {
+    kind: "end-call";
+    reason?: string;
+};
+export type VoicePathwayTransition = {
+    to: string;
+    condition: VoicePathwayCondition;
+    description?: string;
+};
+export type VoicePathwayState = {
+    id: string;
+    label: string;
+    kind?: "entry" | "collect" | "branch" | "action" | "terminal";
+    description?: string;
+    systemNote?: string;
+    actions?: VoicePathwayAction[];
+    transitions: VoicePathwayTransition[];
+};
+export type VoicePathway = {
+    id: string;
+    label: string;
+    entryStateId: string;
+    states: VoicePathwayState[];
+    slots: VoicePathwaySlot[];
+    tools?: {
+        id: string;
+        description: string;
+    }[];
+    metadata?: Record<string, string>;
+};
+export type VoicePathwayValidationIssue = {
+    severity: "error" | "warning";
+    code: "duplicate-state" | "duplicate-slot" | "unknown-entry" | "unreachable-state" | "missing-transition-target" | "missing-slot-ref" | "no-terminal-reachable" | "fallback-not-last" | "duplicate-transition";
+    message: string;
+    stateId?: string;
+    slotId?: string;
+};
+export type VoicePathwayValidationReport = {
+    valid: boolean;
+    issues: VoicePathwayValidationIssue[];
+    reachableStates: string[];
+};
+export declare const validateVoicePathway: (pathway: VoicePathway) => VoicePathwayValidationReport;
+export declare const findVoicePathwayState: (pathway: VoicePathway, id: string) => VoicePathwayState | null;
+export declare const findVoicePathwaySlot: (pathway: VoicePathway, id: string) => VoicePathwaySlot | null;

package/dist/pathwayCompiler.d.ts

@@ -0,0 +1,31 @@
+import { type VoicePathway } from "./pathway";
+export type VoicePathwayCompilerToolDefinition = {
+    name: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+        }>;
+        required: string[];
+    };
+};
+export type VoicePathwayCompiledAssistant = {
+    systemPrompt: string;
+    tools: VoicePathwayCompilerToolDefinition[];
+    initialPrompt?: string;
+    metadata: {
+        pathwayId: string;
+        pathwayLabel: string;
+        entryStateId: string;
+    };
+};
+export type CompileVoicePathwayOptions = {
+    pathway: VoicePathway;
+    introduction?: string;
+    fallbackBehavior?: "stay" | "end-call" | "transfer";
+    toolNamePrefix?: string;
+};
+export declare const compileVoicePathwayToAssistant: (options: CompileVoicePathwayOptions) => VoicePathwayCompiledAssistant;

package/dist/pathwayRuntime.d.ts

@@ -0,0 +1,57 @@
+import { type VoicePathway, type VoicePathwayAction } from "./pathway";
+export type VoicePathwaySlotValue = string | number | boolean | null;
+export type VoicePathwayRuntimeStatus = "ready" | "awaiting-slot" | "branching" | "ended" | "errored";
+export type VoicePathwayRuntimeState = {
+    currentStateId: string;
+    status: VoicePathwayRuntimeStatus;
+    slots: Record<string, VoicePathwaySlotValue>;
+    awaitingSlotId: string | null;
+    history: {
+        stateId: string;
+        at: number;
+    }[];
+    pendingActions: VoicePathwayAction[];
+    lastError?: string;
+    endedReason?: string;
+};
+export type VoicePathwayToolCall = {
+    toolId: string;
+    args: Record<string, VoicePathwaySlotValue>;
+};
+export type VoicePathwayRuntimeEvent = {
+    type: "say";
+    text: string;
+} | {
+    type: "ask-slot";
+    slotId: string;
+    prompt: string;
+} | {
+    type: "tool-call";
+    call: VoicePathwayToolCall;
+} | {
+    type: "transfer";
+    destination: string;
+} | {
+    type: "end-call";
+    reason?: string;
+} | {
+    type: "state-entered";
+    stateId: string;
+} | {
+    type: "errored";
+    message: string;
+};
+export type CreateVoicePathwayRuntimeOptions = {
+    pathway: VoicePathway;
+    initialSlots?: Record<string, VoicePathwaySlotValue>;
+    now?: () => number;
+    skipValidation?: boolean;
+};
+export declare const createVoicePathwayRuntime: (options: CreateVoicePathwayRuntimeOptions) => {
+    fillSlot: (slotId: string, value: VoicePathwaySlotValue) => void;
+    getState: () => VoicePathwayRuntimeState;
+    start: () => void;
+    subscribe(listener: (event: VoicePathwayRuntimeEvent) => void): () => void;
+    tryTransition: () => void;
+};
+export type VoicePathwayRuntime = ReturnType<typeof createVoicePathwayRuntime>;

package/dist/pathwaySlotCollector.d.ts

@@ -0,0 +1,29 @@
+import type { VoicePathwaySlot, VoicePathwaySlotType } from "./pathway";
+import type { VoicePathwaySlotValue } from "./pathwayRuntime";
+export type VoicePathwaySlotParseResult = {
+    ok: true;
+    value: VoicePathwaySlotValue;
+    normalized: string;
+} | {
+    ok: false;
+    reason: "empty" | "type-mismatch" | "out-of-range" | "no-match";
+    hint?: string;
+};
+export type VoicePathwaySlotParser = (raw: string, slot: VoicePathwaySlot) => VoicePathwaySlotParseResult;
+export declare const DEFAULT_VOICE_PATHWAY_SLOT_PARSERS: Record<VoicePathwaySlotType, VoicePathwaySlotParser>;
+export type CreateVoicePathwaySlotCollectorOptions = {
+    parsers?: Partial<Record<VoicePathwaySlotType, VoicePathwaySlotParser>>;
+    maxAttemptsPerSlot?: number;
+};
+export type VoicePathwaySlotCollectorAttempt = {
+    slotId: string;
+    raw: string;
+    result: VoicePathwaySlotParseResult;
+    attempt: number;
+};
+export declare const createVoicePathwaySlotCollector: (options?: CreateVoicePathwaySlotCollectorOptions) => {
+    attemptsExceeded: (slotId: string) => boolean;
+    interpret: (slot: VoicePathwaySlot, raw: string) => VoicePathwaySlotCollectorAttempt;
+    reset: (slotId?: string) => void;
+};
+export type VoicePathwaySlotCollector = ReturnType<typeof createVoicePathwaySlotCollector>;

package/dist/pathwayVisualizer.d.ts

@@ -0,0 +1,8 @@
+import type { VoicePathway } from "./pathway";
+export declare const renderVoicePathwayMermaid: (pathway: VoicePathway) => string;
+export declare const renderVoicePathwayText: (pathway: VoicePathway) => string;
+export type VoicePathwayVisualization = {
+    mermaid: string;
+    text: string;
+};
+export declare const visualizeVoicePathway: (pathway: VoicePathway) => VoicePathwayVisualization;

package/package.json

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