@voicethere/agent 0.3.0 → 0.5.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,48 @@ 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                                   |
+For inbound HTTP webhooks, configure **`AGENT_WEBHOOK_SIGNING_SECRET`** in project settings. The runner forwards the exact request bytes on process-wide **`onWebhook`** IPC (not session-queued). Verify HMAC on `ctx.body` before `JSON.parse` — VoiceThere does not verify signatures in the SDK. See [`templates/webhooks.ts`](./templates/webhooks.ts).
+
+| Export                                                                    | Purpose                                                                                         |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `defineAgent`                                                             | Register `onAgentStart`, `onWebhook`, `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 +281,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 +294,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 +329,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 +376,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,51 @@ 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 isWebhookMessage(value) {
+  if (!value || typeof value !== "object") return false;
+  const msg = value;
+  return msg.type === "webhook" && typeof msg.eventId === "string" && typeof msg.projectId === "string";
+}
+function coerceInboundBinary(value) {
+  if (!value) return null;
+  if (Buffer.isBuffer(value)) return value;
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (value instanceof ArrayBuffer) return Buffer.from(value);
+  if (ArrayBuffer.isView(value)) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (typeof value === "object") {
+    const maybeBufferLike = value;
+    if (maybeBufferLike.type === "Buffer" && Array.isArray(maybeBufferLike.data)) {
+      return Buffer.from(maybeBufferLike.data);
+    }
+  }
+  return null;
+}
+function normalizeWebhookHeaders(value) {
+  if (!value || typeof value !== "object") return {};
+  const out = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw === "string") {
+      out[key] = raw;
+    }
+  }
+  return out;
+}
 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" || msg.type === "webhook";
+}
+function isSessionScopedParentMessage(value) {
+  return isParentMessage(value) && !isWebhookMessage(value);
 }
 function parseDataChannelPayload(raw) {
   try {
@@ -143,6 +185,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;
@@ -219,6 +281,48 @@ function resolveSessionStartInitDelayMs() {
     DEFAULT_SESSION_START_INIT_DELAY_MS
   );
 }
+async function handleWebhookMessage(message, handlers) {
+  if (!handlers.onWebhook) return;
+  const body = coerceInboundBinary(message.body);
+  if (!body) {
+    agentLog("warn", "webhook ipc dropped: body is not binary");
+    return;
+  }
+  const ctx = {
+    eventId: message.eventId,
+    projectId: message.projectId,
+    method: typeof message.method === "string" ? message.method : "POST",
+    path: typeof message.path === "string" ? message.path : "",
+    headers: normalizeWebhookHeaders(message.headers),
+    body,
+    contentType: typeof message.contentType === "string" ? message.contentType : null,
+    receivedAt: typeof message.receivedAt === "string" ? message.receivedAt : ""
+  };
+  try {
+    const started = Date.now();
+    await handlers.onWebhook(ctx);
+    sendParentMessage({
+      type: "webhook_handled",
+      projectId: message.projectId,
+      eventId: message.eventId,
+      durationMs: Date.now() - started
+    });
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    await runErrorHook(handlers, {
+      sessionId: "",
+      projectId: message.projectId,
+      env: process.env,
+      error: err
+    });
+    sendParentMessage({
+      type: "agent_error",
+      sessionId: "",
+      message: err.message,
+      stack: err.stack
+    });
+  }
+}
 async function handleParentMessage(message, handlers) {
   switch (message.type) {
     case "session_start":
@@ -232,7 +336,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 +375,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 +392,18 @@ function defineAgent(handlers) {
   inboundQueueAuthority = inboundBySession;
   const agentStartReady = runAgentStartHook(handlers);
   process.on("message", (message) => {
-    if (!isParentMessage(message)) return;
+    if (isRecordingControlAckMessage(message)) {
+      handleRecordingControlAck(message);
+      return;
+    }
+    if (isWebhookMessage(message)) {
+      void agentStartReady.then(() => handleWebhookMessage(message, handlers));
+      return;
+    }
+    if (!isSessionScopedParentMessage(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, type WebhookMessage, } 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, type WebhookContext, } 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,EACvB,KAAK,cAAc,GACpB,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,EACvB,KAAK,cAAc,GACpB,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,GAwBvB,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,GAUnB,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 | WebhookMessage;
 /**
  * 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 | WebhookHandledMessage;
 /** 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";
 /**
@@ -157,6 +192,34 @@ export interface SendBinaryToClientMessage {
     data: Buffer;
     channel?: DataChannelKind;
 }
+/**
+ * Inbound HTTP webhook forwarded from the edge — process-wide, not tied to a session.
+ *
+ * Delivered to {@link AgentHandlers.onWebhook} on every child in the runner process
+ * (not session-queued). {@link WebhookMessage.body} is the exact inbound bytes — verify
+ * HMAC/signatures on `body` before `JSON.parse` in customer code.
+ */
+export interface WebhookMessage {
+    type: "webhook";
+    /** Edge-generated id for idempotency. */
+    eventId: string;
+    projectId: string;
+    method: string;
+    path: string;
+    /** All inbound request headers (string values). */
+    headers: Record<string, string>;
+    /** Exact inbound body bytes — do not parse in the SDK before the customer handler. */
+    body: Buffer;
+    contentType: string | null;
+    receivedAt: string;
+}
+/** Child reports onWebhook completion latency (process-wide, not session-scoped). */
+export interface WebhookHandledMessage {
+    type: "webhook_handled";
+    projectId: string;
+    eventId: string;
+    durationMs: number;
+}
 /**
  * Idle timeout fired — run {@link AgentHandlers.onIdleTimeout} before disconnect.
  */
@@ -189,8 +252,9 @@ export interface DisconnectClientMessage {
  * The runner may add more project-specific keys over time; customer bundles must
  * not read `process.env` for session fields — only the `env` object on session start.
  *
- * Process-wide secrets such as `AGENT_REDIS_URL` (when project Redis is enabled) are
- * still available on `process.env` inside `onAgentStart`.
+ * Process-wide secrets such as `AGENT_REDIS_URL` (when project Redis is enabled) and
+ * `AGENT_WEBHOOK_SIGNING_SECRET` (for inbound webhook HMAC verification) are still
+ * available on `process.env` inside `onAgentStart` / `onWebhook`.
  * Keys prefixed with `AGENT_` may also be forwarded into the child environment.
  */
 export declare const ALLOWED_CHILD_ENV_KEYS: readonly ["SESSION_ID", "PROJECT_ID", "BUILD_ID", "IDLE_TIMEOUT_SEC", "AGENT_CUSTOMER_CONTEXT"];

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

@@ -14,8 +14,9 @@
  * The runner may add more project-specific keys over time; customer bundles must
  * not read `process.env` for session fields — only the `env` object on session start.
  *
- * Process-wide secrets such as `AGENT_REDIS_URL` (when project Redis is enabled) are
- * still available on `process.env` inside `onAgentStart`.
+ * Process-wide secrets such as `AGENT_REDIS_URL` (when project Redis is enabled) and
+ * `AGENT_WEBHOOK_SIGNING_SECRET` (for inbound webhook HMAC verification) are still
+ * available on `process.env` inside `onAgentStart` / `onWebhook`.
  * Keys prefixed with `AGENT_` may also be forwarded into the child environment.
  */
 export const ALLOWED_CHILD_ENV_KEYS = [

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;AAkSH;;;;;;;;;;GAUG;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;
@@ -26,6 +28,18 @@ export interface AgentStartContext {
     /** Snapshot of `process.env` at child start (includes `AGENT_REDIS_URL` when set). */
     env: Record<string, string>;
 }
+/** Context for process-wide inbound webhook IPC (`type: "webhook"`). */
+export interface WebhookContext {
+    eventId: string;
+    projectId: string;
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    /** Exact inbound bytes — verify HMAC on this, then `JSON.parse`. */
+    body: Buffer;
+    contentType: string | null;
+    receivedAt: string;
+}
 export interface AgentHandlers {
     /**
      * Runs once when the child registers handlers — before any session IPC is handled.
@@ -33,6 +47,12 @@ export interface AgentHandlers {
      * Errors are logged and reported; session IPC is still accepted afterward so the child does not hang.
      */
     onAgentStart?: (ctx: AgentStartContext) => void | Promise<void>;
+    /**
+     * Process-wide inbound HTTP webhook from the edge (not session-queued).
+     * VoiceThere does not verify signatures — use `AGENT_WEBHOOK_SIGNING_SECRET` in
+     * `process.env` and verify HMAC on {@link WebhookContext.body} before parsing JSON.
+     */
+    onWebhook?: (ctx: WebhookContext) => void | Promise<void>;
     /** Alias for {@link AgentHandlers.onSessionStart}. */
     onClientJoin?: (ctx: SessionContext) => void | Promise<void>;
     onSessionStart?: (ctx: SessionContext) => void | Promise<void>;
@@ -105,6 +125,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. */