@voicethere/agent 0.2.17 → 0.4.0

package/README.md

@@ -2,15 +2,16 @@
 
 VoiceThere **customer agent SDK** — TypeScript types and runtime helpers for sandboxed child bundles running inside the **VoiceThere agent runner** (session worker).
 
+**Website:** [voicethere.io](https://voicethere.io)  
 **npm:** `@voicethere/agent`  
 **Repo:** [`voicethere/agent`](https://github.com/voicethere/agent)
 
 ## Role
 
-| Layer     | Package                                                     | Runs in                              |
-| --------- | ----------------------------------------------------------- | ------------------------------------ |
-| Parent    | VoiceThere agent runner                                     | Trusted Node + WebRTC + speech stack |
-| **Child** | **`@voicethere/agent`**                                     | Sandboxed customer `agent.js` bundle |
+| Layer     | Package                 | Runs in                              |
+| --------- | ----------------------- | ------------------------------------ |
+| Parent    | VoiceThere agent runner | Trusted Node + WebRTC + speech stack |
+| **Child** | **`@voicethere/agent`** | Sandboxed customer `agent.js` bundle |
 
 The child receives speech lifecycle events over IPC (same shapes as `@node-webrtc-rust/sdk/voice`) and calls `speak()` to request TTS from the parent.
 
@@ -41,12 +42,12 @@ npx @voicethere/agent verify-start --no-build --bundle ./dist/agent.js
 
 `verify-start` launches the bundle in the sandboxed child with restricted Node flags (`--permission` + fs-read allowlist), sends `session_start`, and requires `session_start_ack`.
 
-| Command | When to use |
-| ------- | ----------- |
-| `npx @voicethere/agent verify` | **Default** — build `agent.ts` → `dist/agent.js`, then run all static checks |
-| `npx @voicethere/agent verify --no-build` | Re-run checks on an existing bundle |
-| `npx @voicethere/agent verify --no-build --bundle ./dist/agent.js` | Verify a specific bundle path |
-| `npx @voicethere/agent verify-start --no-build --bundle ./dist/agent.js` | Verify sandbox startup + restricted Node flags on a specific bundle |
+| Command                                                                  | When to use                                                                  |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| `npx @voicethere/agent verify`                                           | **Default** — build `agent.ts` → `dist/agent.js`, then run all static checks |
+| `npx @voicethere/agent verify --no-build`                                | Re-run checks on an existing bundle                                          |
+| `npx @voicethere/agent verify --no-build --bundle ./dist/agent.js`       | Verify a specific bundle path                                                |
+| `npx @voicethere/agent verify-start --no-build --bundle ./dist/agent.js` | Verify sandbox startup + restricted Node flags on a specific bundle          |
 
 Optional flags: `--entry` / `-e`, `--outfile` / `-o` (same as `build`).
 
@@ -146,45 +147,46 @@ import {
   defineAgent,
   speak,
   type SpeechEvent,
-} from '@voicethere/agent'
-import { SPEECH_EVENT_TYPE } from '@node-webrtc-rust/sdk/voice'
+} from "@voicethere/agent";
+import { SPEECH_EVENT_TYPE } from "@node-webrtc-rust/sdk/voice";
 
 defineAgent({
   async onAgentStart({ env }) {
     // When project Redis is enabled, VoiceThere injects AGENT_REDIS_URL.
     // Depend on `ioredis` in your agent package and connect here (once per child).
-    const redisUrl = env.AGENT_REDIS_URL // or process.env.AGENT_REDIS_URL
+    const redisUrl = env.AGENT_REDIS_URL; // or process.env.AGENT_REDIS_URL
     if (redisUrl) {
       // const Redis = (await import('ioredis')).default
       // globalThis.redis = new Redis(redisUrl)
     }
   },
   onSessionStart({ sessionId }) {
-    speak(sessionId, 'Hello!')
+    speak(sessionId, "Hello!");
   },
   onUserSpeechFinal({ sessionId, text }) {
-    speak(sessionId, `You said: ${text}`)
+    speak(sessionId, `You said: ${text}`);
   },
   onSpeechEvent({ sessionId }, speech: SpeechEvent) {
     if (speech.type === SPEECH_EVENT_TYPE.bargeIn) {
-      agentLog('info', `User interrupted on ${sessionId}`)
+      agentLog("info", `User interrupted on ${sessionId}`);
     }
   },
-})
+});
 ```
 
 ### Shared Redis (project-scoped)
 
 On plans that include project Redis, the runner injects **`AGENT_REDIS_URL`** into the child environment and grants scoped `--allow-net` for that host. Add **`ioredis`** as a dependency of your agent, bundle it with the CLI, and open the client in **`onAgentStart`** so it is ready before any `onSessionStart` / session IPC.
 
-| Export                                          | Purpose                                                                               |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `defineAgent`                                   | Register `onAgentStart`, `onSessionStart`, `onSpeechEvent`, `onUserSpeechFinal`, `onSessionEnd` |
-| `SpeechEvent`, `SpeechEventType`                | Re-exported **types** from `@node-webrtc-rust/sdk/voice`                              |
-| `SPEECH_EVENT_TYPE`                             | Import from `@node-webrtc-rust/sdk/voice` (runtime constants; not bundled into child) |
-| `speak`                                         | Request parent TTS                                                                    |
-| `agentLog`                                      | Forward structured logs to parent                                                     |
-| `ParentToChildMessage` / `ChildToParentMessage` | IPC contract shared with the VoiceThere agent runner                                   |
+| Export                                                                    | Purpose                                                                                         |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `defineAgent`                                                             | Register `onAgentStart`, `onSessionStart`, `onSpeechEvent`, `onUserSpeechFinal`, `onSessionEnd` |
+| `SpeechEvent`, `SpeechEventType`                                          | Re-exported **types** from `@node-webrtc-rust/sdk/voice`                                        |
+| `SPEECH_EVENT_TYPE`                                                       | Import from `@node-webrtc-rust/sdk/voice` (runtime constants; not bundled into child)           |
+| `speak`                                                                   | Request parent TTS                                                                              |
+| `startRecording` / `pauseRecording` / `resumeRecording` / `stopRecording` | Request parent conversation recording control                                                   |
+| `agentLog`                                                                | Forward structured logs to parent                                                               |
+| `ParentToChildMessage` / `ChildToParentMessage`                           | IPC contract shared with the VoiceThere agent runner                                            |
 
 ### Runner runtime subpath (minimal shared sandbox API)
 
@@ -277,12 +279,12 @@ Customer code runs in a **forked child process**, separate from the trusted agen
 
 ### Layer 1 — Process isolation
 
-| Mechanism | What it means for your bundle |
-| --------- | ----------------------------- |
-| **Separate process** | Crash or `process.exit` in your bundle does not take down the parent voice stack |
-| **IPC only for media** | WebRTC, mic, STT, and TTS go through the parent — use `defineAgent`, `speak`, and speech events |
+| Mechanism                  | What it means for your bundle                                                                                                            |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| **Separate process**       | Crash or `process.exit` in your bundle does not take down the parent voice stack                                                         |
+| **IPC only for media**     | WebRTC, mic, STT, and TTS go through the parent — use `defineAgent`, `speak`, and speech events                                          |
 | **Stripped `process.env`** | Child receives only `NODE_ENV`, internal loader path, and allowlisted keys (`SESSION_ID`, `PROJECT_ID`, `BUILD_ID`) — not parent secrets |
-| **Console redirection** | `console.log` / `warn` / `error` → IPC logs |
+| **Console redirection**    | `console.log` / `warn` / `error` → IPC logs                                                                                              |
 
 ### Layer 2 — Node `--permission` (runtime-enforced)
 
@@ -290,24 +292,24 @@ The parent starts the child with Node’s [Permission Model](https://nodejs.org/
 
 **Granted today** (via `execArgv` on `fork()`):
 
-| Flag | Effect |
-| ---- | ------ |
-| `--permission` | Enables restriction mode |
-| `--allow-fs-read=<loaderDir>` | Read files under the child loader directory |
-| `--allow-fs-read=<bundleParentDir>` | Read files under the **directory containing your `agent.js`** (see below) |
-| `--allow-net` | Outbound network (HTTPS/fetch, TCP) for customer LLM and tool APIs (Node **26+**) |
-| `--allow-net=<host>` | Reserved for project Redis host entries when Node supports host-scoped net ACLs |
+| Flag                                | Effect                                                                            |
+| ----------------------------------- | --------------------------------------------------------------------------------- |
+| `--permission`                      | Enables restriction mode                                                          |
+| `--allow-fs-read=<loaderDir>`       | Read files under the child loader directory                                       |
+| `--allow-fs-read=<bundleParentDir>` | Read files under the **directory containing your `agent.js`** (see below)         |
+| `--allow-net`                       | Outbound network (HTTPS/fetch, TCP) for customer LLM and tool APIs (Node **26+**) |
+| `--allow-net=<host>`                | Reserved for project Redis host entries when Node supports host-scoped net ACLs   |
 
 **Not granted → blocked at runtime:**
 
-| Missing flag | What fails |
-| ------------ | ---------- |
-| No `--allow-child-process` | `child_process`, `exec`, `spawn`, `fork` |
-| No `--allow-fs-write` | Any file write (`writeFile`, logs to disk, etc.) |
+| Missing flag                     | What fails                                                   |
+| -------------------------------- | ------------------------------------------------------------ |
+| No `--allow-child-process`       | `child_process`, `exec`, `spawn`, `fork`                     |
+| No `--allow-fs-write`            | Any file write (`writeFile`, logs to disk, etc.)             |
 | No extra `--allow-fs-read` paths | Reading `/etc/passwd`, parent files, etc. outside bundle dir |
-| No `--allow-addons` | Native `.node` addons (`bcrypt`, `sharp`, …) |
-| No `--allow-worker-threads` | `worker_threads` |
-| No `--allow-wasi` | WASI modules |
+| No `--allow-addons`              | Native `.node` addons (`bcrypt`, `sharp`, …)                 |
+| No `--allow-worker-threads`      | `worker_threads`                                             |
+| No `--allow-wasi`                | WASI modules                                                 |
 
 This is **not** an import allowlist — Node gates **capability classes**, not package names. Using `node:fs` inside the allowed read tree can work; using it on `/etc/passwd` does not.
 
@@ -325,23 +327,23 @@ This is **not** an import allowlist — Node gates **capability classes**, not p
   node_modules/     ← JS-only deps may resolve; native addons still blocked
 ```
 
-| Artifact in bundle dir | Works? |
-| ---------------------- | ------ |
-| Single bundled `agent.js` (recommended) | Yes |
-| Extra pure `.js` / `.json` siblings | Usually yes (same allowed tree) |
+| Artifact in bundle dir                            | Works?                                                       |
+| ------------------------------------------------- | ------------------------------------------------------------ |
+| Single bundled `agent.js` (recommended)           | Yes                                                          |
+| Extra pure `.js` / `.json` siblings               | Usually yes (same allowed tree)                              |
 | `node_modules/` with **JavaScript-only** packages | Often yes (Node resolves imports by reading under that tree) |
-| **Native** npm packages (`.node` binaries) | **No** — requires `--allow-addons` (not enabled) |
-| Packages that **spawn subprocesses** | **No** — no `--allow-child-process` |
+| **Native** npm packages (`.node` binaries)        | **No** — requires `--allow-addons` (not enabled)             |
+| Packages that **spawn subprocesses**              | **No** — no `--allow-child-process`                          |
 
 Prefer **one esbuild bundle** so production behavior matches `npm run verify:local`.
 
 ### Layer 3 — Platform policy
 
-| Capability | Behavior |
-| ---------- | -------- |
+| Capability                                      | Behavior                                                                                                                                             |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Outbound network** (`fetch`, `http`, `https`) | **Public internet:** allowed — typical for LLM/tool calls from your agent code. **Internal platform / private network:** blocked on hosted sessions. |
-| **`process.exit`** | Not blocked — kills your agent leg; parent may play crash TTS |
-| **Direct WebRTC / mic / STT / TTS** | Parent only — use `speak()` and speech event handlers |
+| **`process.exit`**                              | Not blocked — kills your agent leg; parent may play crash TTS                                                                                        |
+| **Direct WebRTC / mic / STT / TTS**             | Parent only — use `speak()` and speech event handlers                                                                                                |
 
 ### What you should use in agent code
 
@@ -372,9 +374,9 @@ For iterative work: `npx @voicethere/agent build` then `npx @voicethere/agent ve
 
 ## Build outputs
 
-| Path            | Purpose                                                     |
-| --------------- | ----------------------------------------------------------- |
-| `dist/index.js` | Published npm library entry                                 |
+| Path            | Purpose                                                        |
+| --------------- | -------------------------------------------------------------- |
+| `dist/index.js` | Published npm library entry                                    |
 | `dist/agent.js` | Example bundle (`examples/agent.ts`) for local runner / verify |
 
 ## Scripts

package/dist/agent.js

@@ -3,6 +3,7 @@ const require = createRequire(import.meta.url);
 
 
 // src/runtime.ts
+import { randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 
 // src/session-serial-queue.ts
@@ -129,10 +130,15 @@ var SessionSerialQueue = class {
 var SESSION_START_INIT_DELAY_ENABLED_ENV = "AGENT_SESSION_START_INIT_DELAY_ENABLED";
 var SESSION_START_INIT_DELAY_MS_ENV = "AGENT_SESSION_START_INIT_DELAY_MS";
 var DEFAULT_SESSION_START_INIT_DELAY_MS = 500;
+function isRecordingControlAckMessage(value) {
+  if (!value || typeof value !== "object") return false;
+  const msg = value;
+  return msg.type === "recording_control_ack" && typeof msg.requestId === "string";
+}
 function isParentMessage(value) {
   if (!value || typeof value !== "object") return false;
   const msg = value;
-  return msg.type === "session_start" || msg.type === "speech_event" || msg.type === "session_end" || msg.type === "data_channel_message" || msg.type === "data_channel_binary" || msg.type === "idle_timeout";
+  return msg.type === "session_start" || msg.type === "speech_event" || msg.type === "session_end" || msg.type === "data_channel_message" || msg.type === "data_channel_binary" || msg.type === "idle_timeout" || msg.type === "recording_control_ack";
 }
 function parseDataChannelPayload(raw) {
   try {
@@ -143,6 +149,26 @@ function parseDataChannelPayload(raw) {
 }
 var peerEnvBySessionId = /* @__PURE__ */ new Map();
 var endedSessionIds = /* @__PURE__ */ new Set();
+var pendingRecordingAcks = /* @__PURE__ */ new Map();
+function handleRecordingControlAck(message) {
+  const pending = pendingRecordingAcks.get(message.requestId);
+  if (!pending) return;
+  clearTimeout(pending.timer);
+  pendingRecordingAcks.delete(message.requestId);
+  pending.resolve({
+    ok: message.ok,
+    reason: message.reason,
+    requestId: message.requestId
+  });
+}
+function clearPendingRecordingAcksForSession(sessionId, reason) {
+  for (const [requestId, pending] of pendingRecordingAcks) {
+    if (pending.sessionId !== sessionId) continue;
+    clearTimeout(pending.timer);
+    pendingRecordingAcks.delete(requestId);
+    pending.resolve({ ok: false, reason, requestId });
+  }
+}
 var sessionExecutionContext = new AsyncLocalStorage();
 var agentLogSessionContext = new AsyncLocalStorage();
 var inboundQueueAuthority = null;
@@ -232,7 +258,8 @@ async function handleParentMessage(message, handlers) {
       }
       await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
         sessionId: message.sessionId,
-        env: message.env
+        env: message.env,
+        recordingAvailable: message.recordingAvailable ?? false
       });
       sendParentMessage({
         type: "session_start_ack",
@@ -270,6 +297,7 @@ async function handleParentMessage(message, handlers) {
       });
       break;
     case "session_end":
+      clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
       peerEnvBySessionId.delete(message.sessionId);
       await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
         sessionId: message.sessionId
@@ -286,9 +314,14 @@ function defineAgent(handlers) {
   inboundQueueAuthority = inboundBySession;
   const agentStartReady = runAgentStartHook(handlers);
   process.on("message", (message) => {
+    if (isRecordingControlAckMessage(message)) {
+      handleRecordingControlAck(message);
+      return;
+    }
     if (!isParentMessage(message)) return;
     if (message.type === "session_end") {
       endedSessionIds.add(message.sessionId);
+      clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
       inboundBySession.clear(message.sessionId);
     }
     if (message.type === "session_start") {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export type { SpeechEvent, SpeechEventListener, SpeechEventName, SpeechEventType, } from "@node-webrtc-rust/sdk/voice";
-export { ALLOWED_CHILD_ENV_KEYS, type AgentErrorMessage, type AgentLogLevel, type AgentLogMessage, type AllowedChildEnvKey, type ChildToParentMessage, type ParentToChildMessage, type SessionEndMessage, type SessionStartMessage, type SendToClientMessage, type DataChannelMessageMessage, type DataChannelBinaryMessage, type DataChannelKind, type DisconnectClientMessage, type IdleTimeoutDoneMessage, type IdleTimeoutMessage, type SendBinaryToClientMessage, type SpeakMessage, type SpeechEventMessage, } from "./protocol.js";
-export { agentLog, defineAgent, disconnectClient, parseChatText, sendToClient, sendBinaryToClient, speak, broadcastToClients, type AgentHandlers, type AgentErrorContext, type AgentStartContext, type DataChannelContext, type IdleTimeoutContext, type SessionContext, type SpeechContext, type SpeechEventContext, } from "./runtime.js";
+export { ALLOWED_CHILD_ENV_KEYS, type AgentErrorMessage, type AgentLogLevel, type AgentLogMessage, type AllowedChildEnvKey, type ChildToParentMessage, type ParentToChildMessage, type SessionEndMessage, type SessionStartMessage, type SendToClientMessage, type DataChannelMessageMessage, type DataChannelBinaryMessage, type DataChannelKind, type DisconnectClientMessage, type IdleTimeoutDoneMessage, type IdleTimeoutMessage, type RecordingControlMessage, type RecordingControlAckMessage, type RecordingControlAction, type RecordingControlResult, type SendBinaryToClientMessage, type SpeakMessage, type SpeechEventMessage, } from "./protocol.js";
+export { agentLog, defineAgent, disconnectClient, parseChatText, pauseRecording, resumeRecording, sendToClient, sendBinaryToClient, speak, startRecording, stopRecording, isRecordingAvailable, broadcastToClients, type AgentHandlers, type AgentErrorContext, type AgentStartContext, type DataChannelContext, type IdleTimeoutContext, type SessionContext, type SpeechContext, type SpeechEventContext, } from "./runtime.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,KAAK,EACL,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,eAAe,EACf,eAAe,GAChB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,KAAK,EACL,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,3 +1,3 @@
 export { ALLOWED_CHILD_ENV_KEYS, } from "./protocol.js";
-export { agentLog, defineAgent, disconnectClient, parseChatText, sendToClient, sendBinaryToClient, speak, broadcastToClients, } from "./runtime.js";
+export { agentLog, defineAgent, disconnectClient, parseChatText, pauseRecording, resumeRecording, sendToClient, sendBinaryToClient, speak, startRecording, stopRecording, isRecordingAvailable, broadcastToClients, } from "./runtime.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,sBAAsB,GAmBvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,KAAK,EACL,kBAAkB,GASnB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,sBAAsB,GAuBvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,KAAK,EACL,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,kBAAkB,GASnB,MAAM,cAAc,CAAC"}

package/dist/protocol.d.ts

@@ -16,13 +16,13 @@ export type { SpeechEvent } from "@node-webrtc-rust/sdk/voice";
  * Register handlers via {@link defineAgent} in `@voicethere/agent` — do not read
  * `process.on('message')` directly in customer bundles.
  */
-export type ParentToChildMessage = SessionStartMessage | SpeechEventMessage | SessionEndMessage | DataChannelMessageMessage | DataChannelBinaryMessage | IdleTimeoutMessage;
+export type ParentToChildMessage = SessionStartMessage | SpeechEventMessage | SessionEndMessage | DataChannelMessageMessage | DataChannelBinaryMessage | IdleTimeoutMessage | RecordingControlAckMessage;
 /**
  * Messages the customer child may send back to the runner parent.
  *
- * Prefer {@link speak}, {@link sendToClient}, {@link sendBinaryToClient}, and {@link agentLog} helpers over raw `process.send`.
+ * Prefer {@link speak}, {@link startRecording}, {@link sendToClient}, {@link sendBinaryToClient}, and {@link agentLog} helpers over raw `process.send`.
  */
-export type ChildToParentMessage = SessionStartAckMessage | SpeakMessage | AgentLogMessage | AgentErrorMessage | SendToClientMessage | SendBinaryToClientMessage | IdleTimeoutDoneMessage | DisconnectClientMessage;
+export type ChildToParentMessage = SessionStartAckMessage | SpeakMessage | RecordingControlMessage | AgentLogMessage | AgentErrorMessage | SendToClientMessage | SendBinaryToClientMessage | IdleTimeoutDoneMessage | DisconnectClientMessage;
 /** Which WebRTC data channel carried a binary IPC payload. */
 export type DataChannelKind = "control" | "sync";
 /**
@@ -40,6 +40,11 @@ export interface SessionStartMessage {
      * Keys are a subset of {@link ALLOWED_CHILD_ENV_KEYS}.
      */
     env: Record<string, string>;
+    /**
+     * When `true`, the runner has conversation recording enabled for this project.
+     * Absent on older runners — treat as `false`.
+     */
+    recordingAvailable?: boolean;
 }
 /**
  * Forwards one speech lifecycle event from the parent Sherpa/VAD/STT/TTS pipeline.
@@ -109,6 +114,36 @@ export interface SpeakMessage {
     /** UTF-8 text passed to the parent TTS vendor. */
     text: string;
 }
+/**
+ * Ask the parent to start, pause, resume, or stop conversation recording for a session.
+ *
+ * Recording runs in the runner parent — use {@link startRecording}, {@link pauseRecording},
+ * {@link resumeRecording}, and {@link stopRecording} instead of raw `process.send`.
+ */
+export type RecordingControlAction = "start" | "pause" | "resume" | "stop";
+export interface RecordingControlMessage {
+    type: "recording_control";
+    /** Target peer/session id (must match a prior {@link SessionStartMessage}). */
+    sessionId: string;
+    action: RecordingControlAction;
+    /** Correlates with {@link RecordingControlAckMessage.requestId}. */
+    requestId: string;
+}
+/** Runner acknowledgement for a {@link RecordingControlMessage}. */
+export interface RecordingControlAckMessage {
+    type: "recording_control_ack";
+    sessionId: string;
+    action: RecordingControlAction;
+    requestId: string;
+    ok: boolean;
+    reason?: "applied" | "disabled" | "unsupported" | "stopped" | "local_mock" | "timeout" | string;
+}
+/** Result returned by {@link startRecording} and related helpers. */
+export type RecordingControlResult = {
+    ok: boolean;
+    reason?: string;
+    requestId: string;
+};
 /** Log severity forwarded to the runner parent process. */
 export type AgentLogLevel = "debug" | "info" | "warn" | "error";
 /**

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkNH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,kBAAkB;IAClB,wEAAwE;IACxE,wBAAwB;CAChB,CAAC"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkQH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,kBAAkB;IAClB,wEAAwE;IACxE,wBAAwB;CAChB,CAAC"}

package/dist/runtime.d.ts

@@ -1,10 +1,12 @@
 import type { SpeechEvent } from "@node-webrtc-rust/sdk/voice";
-import type { AgentLogLevel, DataChannelKind } from "./protocol.js";
+import type { AgentLogLevel, DataChannelKind, RecordingControlResult } from "./protocol.js";
 export declare const SESSION_START_INIT_DELAY_ENABLED_ENV = "AGENT_SESSION_START_INIT_DELAY_ENABLED";
 export declare const SESSION_START_INIT_DELAY_MS_ENV = "AGENT_SESSION_START_INIT_DELAY_MS";
 export interface SessionContext {
     sessionId: string;
     env: Record<string, string>;
+    /** `true` when the runner advertises conversation recording for this project. */
+    recordingAvailable: boolean;
 }
 export interface SpeechContext {
     sessionId: string;
@@ -105,6 +107,16 @@ export declare function defineAgent(handlers: AgentHandlers): void;
 export declare function resetAgentIpcStateForTests(): void;
 /** Ask the runner parent to synthesize speech for the session. */
 export declare function speak(sessionId: string, text: string): void;
+/** True when {@link SessionStartMessage.recordingAvailable} was set for the session. */
+export declare function isRecordingAvailable(ctx: SessionContext): boolean;
+/** Ask the runner parent to start conversation recording for the session. */
+export declare function startRecording(sessionId: string): Promise<RecordingControlResult>;
+/** Ask the runner parent to pause an in-progress recording for the session. */
+export declare function pauseRecording(sessionId: string): Promise<RecordingControlResult>;
+/** Ask the runner parent to resume a paused recording for the session. */
+export declare function resumeRecording(sessionId: string): Promise<RecordingControlResult>;
+/** Ask the runner parent to stop conversation recording for the session. */
+export declare function stopRecording(sessionId: string): Promise<RecordingControlResult>;
 /** Send a JSON payload to the browser peer via the runner parent. */
 export declare function sendToClient(sessionId: string, payload: unknown): void;
 /** Send raw bytes to the browser peer via the runner parent. */

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/runtime.js

@@ -1,8 +1,15 @@
+import { randomUUID } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { SessionSerialQueue } from "./session-serial-queue.js";
 export const SESSION_START_INIT_DELAY_ENABLED_ENV = "AGENT_SESSION_START_INIT_DELAY_ENABLED";
 export const SESSION_START_INIT_DELAY_MS_ENV = "AGENT_SESSION_START_INIT_DELAY_MS";
 const DEFAULT_SESSION_START_INIT_DELAY_MS = 500;
+function isRecordingControlAckMessage(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const msg = value;
+    return (msg.type === "recording_control_ack" && typeof msg.requestId === "string");
+}
 function isParentMessage(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -12,7 +19,8 @@ function isParentMessage(value) {
         msg.type === "session_end" ||
         msg.type === "data_channel_message" ||
         msg.type === "data_channel_binary" ||
-        msg.type === "idle_timeout");
+        msg.type === "idle_timeout" ||
+        msg.type === "recording_control_ack");
 }
 function parseDataChannelPayload(raw) {
     try {
@@ -25,6 +33,35 @@ function parseDataChannelPayload(raw) {
 const peerEnvBySessionId = new Map();
 /** Sessions that received `session_end`; `speak()` becomes a no-op when no live gen. */
 const endedSessionIds = new Set();
+const RECORDING_CONTROL_ACK_TIMEOUT_MS = 5000;
+const pendingRecordingAcks = new Map();
+function handleRecordingControlAck(message) {
+    const pending = pendingRecordingAcks.get(message.requestId);
+    if (!pending)
+        return;
+    clearTimeout(pending.timer);
+    pendingRecordingAcks.delete(message.requestId);
+    pending.resolve({
+        ok: message.ok,
+        reason: message.reason,
+        requestId: message.requestId,
+    });
+}
+function clearPendingRecordingAcksForSession(sessionId, reason) {
+    for (const [requestId, pending] of pendingRecordingAcks) {
+        if (pending.sessionId !== sessionId)
+            continue;
+        clearTimeout(pending.timer);
+        pendingRecordingAcks.delete(requestId);
+        pending.resolve({ ok: false, reason, requestId });
+    }
+}
+function isVoicethereAgentChild() {
+    return (typeof process.send === "function" &&
+        process.connected !== false &&
+        typeof process.env.__CHILD_BUNDLE_PATH__ === "string" &&
+        process.env.__CHILD_BUNDLE_PATH__.trim().length > 0);
+}
 /**
  * Generation-aware execution context for inbound handlers. Outbound helpers
  * (`speak`, `sendToClient`, …) consult this so a late old-generation callback
@@ -145,6 +182,7 @@ async function handleParentMessage(message, handlers) {
             await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
                 sessionId: message.sessionId,
                 env: message.env,
+                recordingAvailable: message.recordingAvailable ?? false,
             });
             sendParentMessage({
                 type: "session_start_ack",
@@ -181,6 +219,7 @@ async function handleParentMessage(message, handlers) {
             });
             break;
         case "session_end":
+            clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
             peerEnvBySessionId.delete(message.sessionId);
             await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
                 sessionId: message.sessionId,
@@ -207,6 +246,10 @@ export function defineAgent(handlers) {
     inboundQueueAuthority = inboundBySession;
     const agentStartReady = runAgentStartHook(handlers);
     process.on("message", (message) => {
+        if (isRecordingControlAckMessage(message)) {
+            handleRecordingControlAck(message);
+            return;
+        }
         if (!isParentMessage(message))
             return;
         // Invalidate immediately on arrival — do not wait behind queued work that
@@ -214,6 +257,7 @@ export function defineAgent(handlers) {
         // the leave hook only.
         if (message.type === "session_end") {
             endedSessionIds.add(message.sessionId);
+            clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
             inboundBySession.clear(message.sessionId);
         }
         // session_start must not chain onto a dying session_end generation — clear
@@ -361,11 +405,57 @@ export function resetAgentIpcStateForTests() {
     endedSessionIds.clear();
     peerEnvBySessionId.clear();
     inboundQueueAuthority = null;
+    for (const [requestId, pending] of pendingRecordingAcks) {
+        clearTimeout(pending.timer);
+        pendingRecordingAcks.delete(requestId);
+    }
 }
 /** Ask the runner parent to synthesize speech for the session. */
 export function speak(sessionId, text) {
     sendParentMessage({ type: "speak", sessionId, text });
 }
+/** True when {@link SessionStartMessage.recordingAvailable} was set for the session. */
+export function isRecordingAvailable(ctx) {
+    return ctx.recordingAvailable;
+}
+async function sendRecordingControl(sessionId, action) {
+    const requestId = randomUUID();
+    if (!allowOutboundForSession(sessionId)) {
+        return { ok: false, reason: "session_ended", requestId };
+    }
+    if (!isVoicethereAgentChild()) {
+        return { ok: true, reason: "local_mock", requestId };
+    }
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            pendingRecordingAcks.delete(requestId);
+            resolve({ ok: false, reason: "timeout", requestId });
+        }, RECORDING_CONTROL_ACK_TIMEOUT_MS);
+        pendingRecordingAcks.set(requestId, { sessionId, resolve, timer });
+        sendParentMessage({
+            type: "recording_control",
+            sessionId,
+            action,
+            requestId,
+        });
+    });
+}
+/** Ask the runner parent to start conversation recording for the session. */
+export function startRecording(sessionId) {
+    return sendRecordingControl(sessionId, "start");
+}
+/** Ask the runner parent to pause an in-progress recording for the session. */
+export function pauseRecording(sessionId) {
+    return sendRecordingControl(sessionId, "pause");
+}
+/** Ask the runner parent to resume a paused recording for the session. */
+export function resumeRecording(sessionId) {
+    return sendRecordingControl(sessionId, "resume");
+}
+/** Ask the runner parent to stop conversation recording for the session. */
+export function stopRecording(sessionId) {
+    return sendRecordingControl(sessionId, "stop");
+}
 /** Send a JSON payload to the browser peer via the runner parent. */
 export function sendToClient(sessionId, payload) {
     sendParentMessage({ type: "send_to_client", sessionId, payload });