@voicethere/agent 0.5.5 → 0.5.6

package/dist/templates/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,KAAK,CAAC;AAE7C,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,uBAAuB,EAgHpD,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAMrE,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,eAAe,CAEnE;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,CAMnE;AAED,wBAAgB,yBAAyB,IAAI,uBAAuB,EAAE,CAErE"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,KAAK,CAAC;AAE7C,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,YAAY,CAAC;IACnB,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,uBAAuB,EA4HpD,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAMrE,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,eAAe,CAEnE;AAED,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,uBAAuB,CAMnE;AAED,wBAAgB,yBAAyB,IAAI,uBAAuB,EAAE,CAErE"}

package/dist/templates/registry.js

@@ -51,6 +51,17 @@ export const AGENT_TEMPLATES = [
             "voice-showcase/fun-facts.ts",
         ],
     },
+    {
+        id: "recording-consent",
+        entry: "recording-consent/agent.ts",
+        kind: "product",
+        seedOnCreate: true,
+        description: "Recording consent flow — ask consent, pause capture for PII, resume when allowed.",
+        sourceFiles: [
+            "recording-consent/agent.ts",
+            "recording-consent/conversation.ts",
+        ],
+    },
     {
         id: "webhooks",
         entry: "webhooks.ts",

package/dist/templates/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/templates/registry.ts"],"names":[],"mappings":"AAcA,MAAM,CAAC,MAAM,eAAe,GAAuC;IACjE;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,8EAA8E;QAChF,WAAW,EAAE,CAAC,SAAS,CAAC;KACzB;IACD;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,YAAY;QACnB,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,qEAAqE;QACvE,WAAW,EAAE,CAAC,YAAY,CAAC;KAC5B;IACD;QACE,EAAE,EAAE,eAAe;QACnB,KAAK,EAAE,UAAU;QACjB,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,uFAAuF;QACzF,WAAW,EAAE,CAAC,UAAU,CAAC;KAC1B;IACD;QACE,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,cAAc;QACrB,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,6EAA6E;QAC/E,WAAW,EAAE;YACX,cAAc;YACd,uBAAuB;YACvB,2BAA2B;YAC3B,kBAAkB;YAClB,oBAAoB;SACrB;KACF;IACD;QACE,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,yBAAyB;QAChC,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,0FAA0F;QAC5F,WAAW,EAAE;YACX,yBAAyB;YACzB,gCAAgC;YAChC,2BAA2B;YAC3B,2BAA2B;YAC3B,6BAA6B;SAC9B;KACF;IACD;QACE,EAAE,EAAE,mBAAmB;QACvB,KAAK,EAAE,4BAA4B;QACnC,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,mFAAmF;QACrF,WAAW,EAAE;YACX,4BAA4B;YAC5B,mCAAmC;SACpC;KACF;IACD;QACE,EAAE,EAAE,UAAU;QACd,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,sFAAsF;QACxF,WAAW,EAAE,CAAC,aAAa,CAAC;KAC7B;IACD;QACE,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,IAAI;QAClB,WAAW,EACT,4EAA4E;QAC9E,WAAW,EAAE,CAAC,mBAAmB,CAAC;KACnC;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,KAAK;QACX,YAAY,EAAE,KAAK;QACnB,WAAW,EACT,6EAA6E;QAC/E,WAAW,EAAE,CAAC,eAAe,CAAC;KAC/B;IACD;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,UAAU;QACjB,IAAI,EAAE,KAAK;QACX,YAAY,EAAE,KAAK;QACnB,WAAW,EACT,4EAA4E;QAC9E,WAAW,EAAE,CAAC,UAAU,CAAC;KAC1B;IACD;QACE,EAAE,EAAE,iBAAiB;QACrB,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,KAAK;QACX,YAAY,EAAE,KAAK;QACnB,WAAW,EACT,6EAA6E;QAC/E,WAAW,EAAE,CAAC,oBAAoB,CAAC;KACpC;IACD;QACE,EAAE,EAAE,YAAY;QAChB,KAAK,EAAE,qBAAqB;QAC5B,IAAI,EAAE,KAAK;QACX,YAAY,EAAE,KAAK;QACnB,WAAW,EACT,sFAAsF;QACxF,WAAW,EAAE,CAAC,qBAAqB,EAAE,4BAA4B,CAAC;KACnE;CACO,CAAC;AAIX,MAAM,cAAc,GAAG,IAAI,GAAG,CAC5B,eAAe,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAC3D,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,OAAO,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,8BAA8B,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,yBAAyB;IACvC,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AACrE,CAAC"}

package/dist/templates/voice-showcase/agent.js

@@ -191,6 +191,7 @@ function parseDataChannelPayload(raw) {
   }
 }
 var peerEnvBySessionId = /* @__PURE__ */ new Map();
+var recordingAvailableBySessionId = /* @__PURE__ */ new Map();
 var endedSessionIds = /* @__PURE__ */ new Set();
 var pendingRecordingAcks = /* @__PURE__ */ new Map();
 function handleRecordingControlAck(message) {
@@ -340,6 +341,7 @@ async function handleParentMessage(message, handlers) {
     case "session_start":
       endedSessionIds.delete(message.sessionId);
       peerEnvBySessionId.set(message.sessionId, message.env);
+      recordingAvailableBySessionId.set(message.sessionId, message.recordingAvailable ?? false);
       const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
       if (sessionStartInitDelayMs > 0) {
         await new Promise((resolve) => setTimeout(resolve, sessionStartInitDelayMs));
@@ -384,6 +386,7 @@ async function handleParentMessage(message, handlers) {
     case "session_end":
       clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
       peerEnvBySessionId.delete(message.sessionId);
+      recordingAvailableBySessionId.delete(message.sessionId);
       await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
         sessionId: message.sessionId
       });

package/dist/templates/voice-starter/agent.js

@@ -191,6 +191,7 @@ function parseDataChannelPayload(raw) {
   }
 }
 var peerEnvBySessionId = /* @__PURE__ */ new Map();
+var recordingAvailableBySessionId = /* @__PURE__ */ new Map();
 var endedSessionIds = /* @__PURE__ */ new Set();
 var pendingRecordingAcks = /* @__PURE__ */ new Map();
 function handleRecordingControlAck(message) {
@@ -340,6 +341,7 @@ async function handleParentMessage(message, handlers) {
     case "session_start":
       endedSessionIds.delete(message.sessionId);
       peerEnvBySessionId.set(message.sessionId, message.env);
+      recordingAvailableBySessionId.set(message.sessionId, message.recordingAvailable ?? false);
       const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
       if (sessionStartInitDelayMs > 0) {
         await new Promise((resolve) => setTimeout(resolve, sessionStartInitDelayMs));
@@ -384,6 +386,7 @@ async function handleParentMessage(message, handlers) {
     case "session_end":
       clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
       peerEnvBySessionId.delete(message.sessionId);
+      recordingAvailableBySessionId.delete(message.sessionId);
       await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
         sessionId: message.sessionId
       });

package/dist/templates/webhooks/agent.js

@@ -194,6 +194,7 @@ function parseDataChannelPayload(raw) {
   }
 }
 var peerEnvBySessionId = /* @__PURE__ */ new Map();
+var recordingAvailableBySessionId = /* @__PURE__ */ new Map();
 var endedSessionIds = /* @__PURE__ */ new Set();
 var pendingRecordingAcks = /* @__PURE__ */ new Map();
 function handleRecordingControlAck(message) {
@@ -343,6 +344,7 @@ async function handleParentMessage(message, handlers) {
     case "session_start":
       endedSessionIds.delete(message.sessionId);
       peerEnvBySessionId.set(message.sessionId, message.env);
+      recordingAvailableBySessionId.set(message.sessionId, message.recordingAvailable ?? false);
       const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
       if (sessionStartInitDelayMs > 0) {
         await new Promise((resolve) => setTimeout(resolve, sessionStartInitDelayMs));
@@ -387,6 +389,7 @@ async function handleParentMessage(message, handlers) {
     case "session_end":
       clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
       peerEnvBySessionId.delete(message.sessionId);
+      recordingAvailableBySessionId.delete(message.sessionId);
       await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
         sessionId: message.sessionId
       });

package/dist/templates/webhooks-redis/agent.js

@@ -10946,6 +10946,7 @@ function parseDataChannelPayload(raw) {
   }
 }
 var peerEnvBySessionId = /* @__PURE__ */ new Map();
+var recordingAvailableBySessionId = /* @__PURE__ */ new Map();
 var endedSessionIds = /* @__PURE__ */ new Set();
 var pendingRecordingAcks = /* @__PURE__ */ new Map();
 function handleRecordingControlAck(message) {
@@ -11095,6 +11096,7 @@ async function handleParentMessage(message, handlers) {
     case "session_start":
       endedSessionIds.delete(message.sessionId);
       peerEnvBySessionId.set(message.sessionId, message.env);
+      recordingAvailableBySessionId.set(message.sessionId, message.recordingAvailable ?? false);
       const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
       if (sessionStartInitDelayMs > 0) {
         await new Promise((resolve) => setTimeout(resolve, sessionStartInitDelayMs));
@@ -11139,6 +11141,7 @@ async function handleParentMessage(message, handlers) {
     case "session_end":
       clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
       peerEnvBySessionId.delete(message.sessionId);
+      recordingAvailableBySessionId.delete(message.sessionId);
       await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
         sessionId: message.sessionId
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voicethere/agent",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "VoiceThere customer agent SDK — IPC types and runtime helpers for sandboxed child bundles",
   "type": "module",
   "exports": {

package/templates/README.md

@@ -15,10 +15,10 @@ import {
 
 ## Product vs e2e
 
-| Kind        | Dashboard create                                                                                      | Prebuilt seed bundle                 | Typical consumer        |
-| ----------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------- |
-| **product** | Yes (`echo`, `echo-dc`, `voice-starter`, `game-sync`, `voice-showcase`, `webhooks`, `webhooks-redis`) | Yes — `dist/templates/<id>/agent.js` | Platform project create |
-| **e2e**     | No                                                                                                    | No — build from sources at test time | `voicethere/e2e` smokes |
+| Kind        | Dashboard create                                                                                                           | Prebuilt seed bundle                 | Typical consumer        |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------- |
+| **product** | Yes (`echo`, `echo-dc`, `voice-starter`, `game-sync`, `voice-showcase`, `recording-consent`, `webhooks`, `webhooks-redis`) | Yes — `dist/templates/<id>/agent.js` | Platform project create |
+| **e2e**     | No                                                                                                                         | No — build from sources at test time | `voicethere/e2e` smokes |
 
 Product templates always set `seedOnCreate: true`. CI fails if a product template is missing its prebuilt bundle after `npm run build`.
 
@@ -67,6 +67,12 @@ Conversational voice demo for landing and dashboard previews — greets the user
 
 Sources: `voice-showcase/agent.ts` (defineAgent wiring), `conversation.ts` (pure state machine), `weather.ts`, `recipes.ts`, `fun-facts.ts`.
 
+### `recording-consent/` (`recording-consent`)
+
+Demonstrates conversation recording consent on connect: asks whether recording is OK when the project has recording enabled, pauses capture while collecting name and date of birth, then resumes only if the customer consented. When project recording is off, logs a warning and never calls `startRecording`. Voice finals and typed chat share the same handler.
+
+Sources: `recording-consent/agent.ts` (defineAgent wiring), `conversation.ts` (pure state machine).
+
 ### `webhooks.ts` (`webhooks`)
 
 Inbound HTTP webhook sample — verifies `x-agent-webhook-signature` HMAC on the **raw body** with `AGENT_WEBHOOK_SIGNING_SECRET`, then `JSON.parse` and fans out to connected sessions via DataChannel + `speak`.

package/templates/recording-consent/agent.ts

@@ -0,0 +1,162 @@
+/**
+ * Recording consent template — ask consent, pause for PII, resume when allowed.
+ *
+ * Build:
+ *   npx @voicethere/agent build --entry templates/recording-consent/agent.ts
+ */
+import {
+  agentLog,
+  defineAgent,
+  parseChatText,
+  pauseRecording,
+  resumeRecording,
+  sendToClient,
+  speak,
+  stopRecording,
+  type SpeechEvent,
+} from "@voicethere/agent";
+
+import {
+  beginSession,
+  handleUtterance,
+  type ConversationState,
+  type ConversationTurnResult,
+  type OutboundMessage,
+  type RecordingAction,
+} from "./conversation.js";
+
+let sessions = new Map<string, ConversationState>();
+/** Per-session consent flag (shared-child safe — not one process-wide boolean). */
+let consentBySessionId = new Map<string, boolean>();
+
+function getState(sessionId: string): ConversationState {
+  const state = sessions.get(sessionId);
+  if (!state) {
+    throw new Error(
+      `recording-consent: missing session state for ${sessionId}`,
+    );
+  }
+  return state;
+}
+
+function relaySpeechEvent(sessionId: string, event: SpeechEvent): void {
+  sendToClient(sessionId, {
+    type: "agent_event",
+    event: event.type,
+    text: event.text,
+    raw: event,
+  });
+}
+
+function deliverMessages(sessionId: string, messages: OutboundMessage[]): void {
+  for (const message of messages) {
+    sendToClient(sessionId, message);
+  }
+}
+
+function speakLines(sessionId: string, lines: string[]): void {
+  for (const line of lines) {
+    speak(sessionId, line);
+  }
+}
+
+async function applyRecordingAction(
+  sessionId: string,
+  action: RecordingAction,
+): Promise<void> {
+  if (!action) return;
+  switch (action) {
+    case "pause":
+      await pauseRecording(sessionId);
+      break;
+    case "stop":
+      await stopRecording(sessionId);
+      break;
+    case "start":
+    case "resume":
+      await resumeRecording(sessionId);
+      break;
+  }
+}
+
+async function applyTurn(
+  sessionId: string,
+  result: ConversationTurnResult,
+): Promise<void> {
+  sessions.set(sessionId, result.state);
+  if (result.state.consent !== undefined) {
+    consentBySessionId.set(sessionId, result.state.consent);
+  }
+  if (result.warnRecordingDisabled) {
+    agentLog(
+      "warn",
+      "Project conversation recording is disabled; skipping consent and will not call startRecording",
+      sessionId,
+    );
+  }
+  speakLines(sessionId, result.speakLines);
+  deliverMessages(sessionId, result.messages);
+  await applyRecordingAction(sessionId, result.recordingAction);
+}
+
+async function onUserText(sessionId: string, text: string): Promise<void> {
+  const state = getState(sessionId);
+  const result = handleUtterance(state, text);
+  await applyTurn(sessionId, result);
+}
+
+defineAgent({
+  onAgentStart() {
+    sessions = new Map();
+    consentBySessionId = new Map();
+  },
+
+  onSessionStart({ sessionId, recordingAvailable }) {
+    const result = beginSession(recordingAvailable);
+    sessions.set(sessionId, result.state);
+    if (result.warnRecordingDisabled) {
+      agentLog(
+        "warn",
+        "Project conversation recording is disabled; skipping consent and will not call startRecording",
+        sessionId,
+      );
+    }
+    speakLines(sessionId, result.speakLines);
+    deliverMessages(sessionId, result.messages);
+    sendToClient(sessionId, {
+      type: "agent_event",
+      event: "session_start",
+      sessionId,
+    });
+    agentLog(
+      "info",
+      `recording-consent session_start ${sessionId} recordingAvailable=${recordingAvailable}`,
+      sessionId,
+    );
+  },
+
+  onSpeechEvent({ sessionId }, event: SpeechEvent) {
+    relaySpeechEvent(sessionId, event);
+  },
+
+  onUserSpeechFinal({ sessionId, text }) {
+    void onUserText(sessionId, text);
+  },
+
+  onDataChannelMessage(ctx) {
+    const text = parseChatText(ctx.message);
+    if (!text) return;
+    void onUserText(ctx.sessionId, text);
+  },
+
+  onSessionEnd({ sessionId }) {
+    sessions.delete(sessionId);
+    consentBySessionId.delete(sessionId);
+    sendToClient(sessionId, {
+      type: "agent_event",
+      event: "session_end",
+      sessionId,
+    });
+    agentLog("info", `recording-consent session_end ${sessionId}`, sessionId);
+  },
+});

package/templates/recording-consent/conversation.ts

@@ -0,0 +1,300 @@
+/**
+ * Pure conversation state machine for the recording-consent template.
+ * Tests import this module directly — no defineAgent dependency.
+ */
+
+export const CONSENT_PROMPT =
+  "This call may be recorded for quality purposes. Is that OK?";
+
+export const NAME_PROMPT = "May I have your name please?";
+
+export const BIRTHDATE_PROMPT = "And your date of birth?";
+
+export const RECORDING_DISABLED_SKIP_MESSAGE =
+  "Conversation recording is not enabled for this project.";
+
+export type ConversationPhase =
+  "awaitingConsent" | "awaitingName" | "awaitingBirthdate" | "complete";
+
+export type RecordingAction = "pause" | "stop" | "start" | "resume" | null;
+
+export interface ConversationState {
+  phase: ConversationPhase;
+  recordingAvailable: boolean;
+  consent?: boolean;
+  /** True when consent was skipped because project recording is off. */
+  consentSkipped: boolean;
+  name?: string;
+  birthdate?: string;
+}
+
+export interface OutboundMessage {
+  type: "chat_reply" | "agent_event";
+  text?: string;
+  event?: string;
+  sessionId?: string;
+}
+
+export interface ConversationTurnResult {
+  state: ConversationState;
+  speakLines: string[];
+  messages: OutboundMessage[];
+  recordingAction: RecordingAction;
+  /** When true, agent should warn that project recording is disabled. */
+  warnRecordingDisabled?: boolean;
+}
+
+export function createInitialState(
+  recordingAvailable: boolean,
+): ConversationState {
+  if (recordingAvailable) {
+    return {
+      phase: "awaitingConsent",
+      recordingAvailable,
+      consentSkipped: false,
+    };
+  }
+  return {
+    phase: "awaitingName",
+    recordingAvailable,
+    consentSkipped: true,
+  };
+}
+
+function speakAndChat(text: string): {
+  speakLines: string[];
+  messages: OutboundMessage[];
+} {
+  return {
+    speakLines: [text],
+    messages: [{ type: "chat_reply", text }],
+  };
+}
+
+export function beginSession(
+  recordingAvailable: boolean,
+): ConversationTurnResult {
+  const state = createInitialState(recordingAvailable);
+  if (recordingAvailable) {
+    const prompt = speakAndChat(CONSENT_PROMPT);
+    return {
+      state,
+      speakLines: prompt.speakLines,
+      messages: prompt.messages,
+      recordingAction: null,
+    };
+  }
+  const skip = speakAndChat(RECORDING_DISABLED_SKIP_MESSAGE);
+  const name = speakAndChat(NAME_PROMPT);
+  return {
+    state,
+    speakLines: [...skip.speakLines, ...name.speakLines],
+    messages: [...skip.messages, ...name.messages],
+    recordingAction: null,
+    warnRecordingDisabled: true,
+  };
+}
+
+export function isConsentNo(utterance: string): boolean {
+  const lower = utterance.toLowerCase().trim();
+  if (/\bnot\s+ok(?:ay)?\b/i.test(lower)) return true;
+  const noPhrases = [
+    "no",
+    "nope",
+    "nah",
+    "don't",
+    "do not",
+    "decline",
+    "refuse",
+  ];
+  if (noPhrases.some((p) => lower === p || lower.startsWith(`${p} `))) {
+    return true;
+  }
+  return /\b(no|nope|nah)\b/i.test(utterance) && !/\bknow\b/i.test(utterance);
+}
+
+export function isConsentYes(utterance: string): boolean {
+  if (isConsentNo(utterance)) return false;
+  const lower = utterance.toLowerCase().trim();
+  const yesPhrases = [
+    "yes",
+    "yeah",
+    "yep",
+    "sure",
+    "ok",
+    "okay",
+    "that's fine",
+    "that is fine",
+    "go ahead",
+    "fine",
+    "absolutely",
+  ];
+  if (yesPhrases.some((p) => lower === p || lower.startsWith(`${p} `))) {
+    return true;
+  }
+  return /\b(yes|yeah|yep|sure|ok|okay)\b/i.test(utterance);
+}
+
+export function extractName(utterance: string): string | null {
+  const trimmed = utterance.trim();
+  const patterns = [/(?:my name is|i'm|i am|call me)\s+(.+)/i];
+  for (const pattern of patterns) {
+    const match = trimmed.match(pattern);
+    if (match?.[1]) {
+      return sanitizeToken(match[1], 40);
+    }
+  }
+  if (trimmed.length > 0 && trimmed.length <= 60) {
+    return sanitizeToken(trimmed, 40);
+  }
+  return null;
+}
+
+export function extractBirthdate(utterance: string): string | null {
+  const trimmed = utterance.trim();
+  const iso = trimmed.match(/\b(\d{4}-\d{2}-\d{2})\b/);
+  if (iso?.[1]) return iso[1];
+  const slash = trimmed.match(/\b(\d{1,2}\/\d{1,2}\/\d{2,4})\b/);
+  if (slash?.[1]) return slash[1];
+  const spoken = trimmed.match(
+    /\b(january|february|march|april|may|june|july|august|september|october|november|december)\s+\d{1,2}(?:st|nd|rd|th)?,?\s+\d{4}\b/i,
+  );
+  if (spoken?.[0]) return spoken[0];
+  if (trimmed.length >= 4 && trimmed.length <= 40) {
+    return sanitizeToken(trimmed, 40);
+  }
+  return null;
+}
+
+function sanitizeToken(raw: string, maxLen: number): string {
+  let value = raw
+    .trim()
+    .replace(/[.,!?;:]+$/g, "")
+    .trim();
+  if (value.length > maxLen) {
+    value = value.slice(0, maxLen).trim();
+  }
+  return value;
+}
+
+function askNameAgain(state: ConversationState): ConversationTurnResult {
+  const prompt = speakAndChat(
+    "Sorry, I didn't catch your name. May I have your name please?",
+  );
+  return {
+    state,
+    speakLines: prompt.speakLines,
+    messages: prompt.messages,
+    recordingAction: null,
+  };
+}
+
+function askBirthdateAgain(state: ConversationState): ConversationTurnResult {
+  const prompt = speakAndChat(
+    "Sorry, I didn't catch your date of birth. Could you repeat it?",
+  );
+  return {
+    state,
+    speakLines: prompt.speakLines,
+    messages: prompt.messages,
+    recordingAction: null,
+  };
+}
+
+function finishAfterPii(state: ConversationState): ConversationTurnResult {
+  const next: ConversationState = { ...state, phase: "complete" };
+  const thankYou = speakAndChat(
+    `Thank you, ${state.name}. We have your date of birth on file.`,
+  );
+  let recordingAction: RecordingAction = null;
+  if (state.consent === true && state.recordingAvailable) {
+    recordingAction = "resume";
+  }
+  return {
+    state: next,
+    speakLines: thankYou.speakLines,
+    messages: thankYou.messages,
+    recordingAction,
+  };
+}
+
+export function handleUtterance(
+  state: ConversationState,
+  utterance: string,
+): ConversationTurnResult {
+  switch (state.phase) {
+    case "awaitingConsent": {
+      if (isConsentNo(utterance)) {
+        const next: ConversationState = {
+          ...state,
+          phase: "awaitingName",
+          consent: false,
+        };
+        const name = speakAndChat(NAME_PROMPT);
+        return {
+          state: next,
+          speakLines: name.speakLines,
+          messages: name.messages,
+          recordingAction: "stop",
+        };
+      }
+      if (isConsentYes(utterance)) {
+        const next: ConversationState = {
+          ...state,
+          phase: "awaitingName",
+          consent: true,
+        };
+        const name = speakAndChat(NAME_PROMPT);
+        return {
+          state: next,
+          speakLines: name.speakLines,
+          messages: name.messages,
+          recordingAction: "pause",
+        };
+      }
+      const retry = speakAndChat(
+        "Please say yes or no — may we record this conversation?",
+      );
+      return {
+        state,
+        speakLines: retry.speakLines,
+        messages: retry.messages,
+        recordingAction: null,
+      };
+    }
+    case "awaitingName": {
+      const name = extractName(utterance);
+      if (!name) {
+        return askNameAgain(state);
+      }
+      const next: ConversationState = {
+        ...state,
+        phase: "awaitingBirthdate",
+        name,
+      };
+      const birthdate = speakAndChat(BIRTHDATE_PROMPT);
+      return {
+        state: next,
+        speakLines: birthdate.speakLines,
+        messages: birthdate.messages,
+        recordingAction: null,
+      };
+    }
+    case "awaitingBirthdate": {
+      const birthdate = extractBirthdate(utterance);
+      if (!birthdate) {
+        return askBirthdateAgain(state);
+      }
+      return finishAfterPii({ ...state, birthdate });
+    }
+    case "complete": {
+      const done = speakAndChat("We are all set. How can I help you today?");
+      return {
+        state,
+        speakLines: done.speakLines,
+        messages: done.messages,
+        recordingAction: null,
+      };
+    }
+  }
+}