@voicethere/agent 0.1.9 → 0.1.11

package/README.md

@@ -94,6 +94,18 @@ Forwarded from the runner voice pipeline as SDK `SpeechEvent` payloads on `speec
 
 Copy [`templates/agent.ts`](./templates/agent.ts) as a starting point — exhaustive `switch` over all 14 `SpeechEvent` types with per-peer state stubs and `agentLog` tracing.
 
+## Multiplayer / shared state
+
+Each end-user connection must call **`startSession()`** once — one orchestrator session id per client (one signaling room per client). Do **not** join multiple browsers to the same session credentials.
+
+When the VoiceThere project has **`shared_child_per_session`** enabled, every session on a runner pod shares **one** sandboxed `agent.js` process. Your handlers receive `sessionId` equal to the orchestrator session id (see `onClientJoin` / `onSessionStart`). Use that id with `speak`, `sendToClient`, and `broadcastToClients` to target the right WebRTC client.
+
+The runtime processes parent IPC **in order per `sessionId`** while different sessions run independently — safe for greet-on-join and load with many concurrent connections.
+
+For isolated voice agents (default), leave **`shared_child_per_session`** disabled — each session gets its own child process.
+
+See [`templates/game-sync.ts`](./templates/game-sync.ts) for a data-only authoritative server example.
+
 ## Building your agent bundle
 
 **Recommended:** bundle with the package CLI (same esbuild settings VoiceThere uses in production):

package/dist/agent.js

@@ -1,8 +1,31 @@
+// src/session-serial-queue.ts
+var SessionSerialQueue = class {
+  tails = /* @__PURE__ */ new Map();
+  enqueue(sessionId, task) {
+    const previous = this.tails.get(sessionId)?.catch(() => void 0) ?? Promise.resolve();
+    const next = previous.then(() => Promise.resolve(task()));
+    this.tails.set(
+      sessionId,
+      next.finally(() => {
+        if (this.tails.get(sessionId) === next) {
+          this.tails.delete(sessionId);
+        }
+      })
+    );
+  }
+  clear(sessionId) {
+    this.tails.delete(sessionId);
+  }
+  clearAll() {
+    this.tails.clear();
+  }
+};
+
 // src/runtime.ts
 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";
+  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";
 }
 function parseDataChannelPayload(raw) {
   try {
@@ -11,63 +34,136 @@ function parseDataChannelPayload(raw) {
     return raw;
   }
 }
+var peerEnvBySessionId = /* @__PURE__ */ new Map();
+async function handleParentMessage(message, handlers) {
+  switch (message.type) {
+    case "session_start":
+      peerEnvBySessionId.set(message.sessionId, message.env);
+      await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
+        sessionId: message.sessionId,
+        env: message.env
+      });
+      break;
+    case "speech_event":
+      await handlers.onSpeechEvent?.(
+        { sessionId: message.sessionId },
+        message.event
+      );
+      if (message.event.type === "user_speech_final" && typeof message.event.text === "string" && message.event.text.trim()) {
+        await handlers.onUserSpeechFinal?.({
+          sessionId: message.sessionId,
+          text: message.event.text.trim()
+        });
+      }
+      break;
+    case "data_channel_message":
+      await handlers.onDataChannelMessage?.({
+        sessionId: message.sessionId,
+        message: parseDataChannelPayload(message.payload),
+        raw: message.payload,
+        rawBinary: null,
+        channel: "control"
+      });
+      break;
+    case "data_channel_binary":
+      await handlers.onDataChannelBinary?.({
+        sessionId: message.sessionId,
+        message: null,
+        raw: null,
+        rawBinary: message.data,
+        channel: message.channel ?? "sync"
+      });
+      break;
+    case "session_end":
+      peerEnvBySessionId.delete(message.sessionId);
+      await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
+        sessionId: message.sessionId
+      });
+      break;
+    case "idle_timeout":
+      await runIdleTimeoutHook(handlers, message);
+      break;
+  }
+}
 function defineAgent(handlers) {
+  const inboundBySession = new SessionSerialQueue();
   process.on("message", (message) => {
     if (!isParentMessage(message)) return;
-    void (async () => {
+    inboundBySession.enqueue(message.sessionId, async () => {
       try {
-        switch (message.type) {
-          case "session_start":
-            await handlers.onSessionStart?.({
-              sessionId: message.sessionId,
-              env: message.env
-            });
-            break;
-          case "speech_event":
-            await handlers.onSpeechEvent?.(
-              { sessionId: message.sessionId },
-              message.event
-            );
-            if (message.event.type === "user_speech_final" && typeof message.event.text === "string" && message.event.text.trim()) {
-              await handlers.onUserSpeechFinal?.({
-                sessionId: message.sessionId,
-                text: message.event.text.trim()
-              });
-            }
-            break;
-          case "data_channel_message":
-            await handlers.onDataChannelMessage?.({
-              sessionId: message.sessionId,
-              message: parseDataChannelPayload(message.payload),
-              raw: message.payload,
-              rawBinary: null,
-              channel: "control"
-            });
-            break;
-          case "data_channel_binary":
-            await handlers.onDataChannelBinary?.({
-              sessionId: message.sessionId,
-              message: null,
-              raw: null,
-              rawBinary: message.data,
-              channel: message.channel ?? "sync"
-            });
-            break;
-          case "session_end":
-            await handlers.onSessionEnd?.({ sessionId: message.sessionId });
-            break;
-        }
+        await handleParentMessage(message, handlers);
       } catch (error) {
-        const errMessage = error instanceof Error ? error.message : String(error);
+        const err = error instanceof Error ? error : new Error(String(error));
+        const env = peerEnvBySessionId.get(message.sessionId) ?? buildIdleEnv(message.sessionId);
+        await runErrorHook(handlers, {
+          sessionId: message.sessionId,
+          projectId: env.PROJECT_ID,
+          buildId: env.BUILD_ID,
+          env,
+          error: err,
+          customerContext: parseCustomerContext(env.AGENT_CUSTOMER_CONTEXT)
+        });
         process.send?.({
           type: "agent_error",
           sessionId: message.sessionId,
-          message: errMessage
+          message: err.message,
+          stack: err.stack
         });
       }
-    })();
+    });
+  });
+}
+function parseCustomerContext(raw) {
+  if (!raw?.trim()) return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function runErrorHook(handlers, ctx) {
+  if (!handlers.errorHook) return;
+  try {
+    await handlers.errorHook(ctx);
+  } catch (hookError) {
+    const message = hookError instanceof Error ? hookError.message : String(hookError);
+    agentLog("error", `errorHook failed: ${message}`);
+  }
+}
+async function runIdleTimeoutHook(handlers, message) {
+  const env = peerEnvBySessionId.get(message.sessionId) ?? buildIdleEnv(message.sessionId);
+  const idleTimeoutSeconds = Number(env.IDLE_TIMEOUT_SEC) || 0;
+  const ctx = {
+    sessionId: message.sessionId,
+    projectId: env.PROJECT_ID,
+    buildId: env.BUILD_ID,
+    env,
+    idleTimeoutSeconds
+  };
+  let error;
+  try {
+    await handlers.onIdleTimeout?.(ctx);
+  } catch (hookError) {
+    error = hookError instanceof Error ? hookError.message : String(hookError);
+    agentLog("error", `onIdleTimeout failed: ${error}`);
+  }
+  process.send?.({
+    type: "idle_timeout_done",
+    sessionId: message.sessionId,
+    error
   });
 }
+function buildIdleEnv(sessionId) {
+  return {
+    SESSION_ID: sessionId,
+    ...process.env.PROJECT_ID ? { PROJECT_ID: process.env.PROJECT_ID } : {},
+    ...process.env.BUILD_ID ? { BUILD_ID: process.env.BUILD_ID } : {},
+    ...process.env.IDLE_TIMEOUT_SEC ? { IDLE_TIMEOUT_SEC: process.env.IDLE_TIMEOUT_SEC } : {}
+  };
+}
 function speak(sessionId, text) {
   process.send?.({ type: "speak", sessionId, text });
 }

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 AgentLogMessage, type AllowedChildEnvKey, type ChildToParentMessage, type ParentToChildMessage, type SessionEndMessage, type SessionStartMessage, type SendToClientMessage, type DataChannelMessageMessage, type DataChannelBinaryMessage, type DataChannelKind, type SendBinaryToClientMessage, type SpeakMessage, type SpeechEventMessage, } from "./protocol.js";
-export { agentLog, defineAgent, parseChatText, sendToClient, sendBinaryToClient, speak, type AgentHandlers, type DataChannelContext, type SessionContext, type SpeechContext, type SpeechEventContext, } from "./runtime.js";
+export { ALLOWED_CHILD_ENV_KEYS, type AgentErrorMessage, 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 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,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,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,KAAK,EACL,KAAK,aAAa,EAClB,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,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,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, parseChatText, sendToClient, sendBinaryToClient, speak, } from "./runtime.js";
+export { agentLog, defineAgent, disconnectClient, parseChatText, sendToClient, sendBinaryToClient, speak, 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,GAevB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,KAAK,GAMN,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,sBAAsB,GAkBvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,kBAAkB,EAClB,KAAK,EACL,kBAAkB,GAQnB,MAAM,cAAc,CAAC"}

package/dist/protocol.d.ts

@@ -15,13 +15,13 @@ import 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;
+export type ParentToChildMessage = SessionStartMessage | SpeechEventMessage | SessionEndMessage | DataChannelMessageMessage | DataChannelBinaryMessage | IdleTimeoutMessage;
 /**
  * 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`.
  */
-export type ChildToParentMessage = SpeakMessage | AgentLogMessage | AgentErrorMessage | SendToClientMessage | SendBinaryToClientMessage;
+export type ChildToParentMessage = SpeakMessage | AgentLogMessage | AgentErrorMessage | SendToClientMessage | SendBinaryToClientMessage | IdleTimeoutDoneMessage | DisconnectClientMessage;
 /** Which WebRTC data channel carried a binary IPC payload. */
 export type DataChannelKind = "control" | "sync";
 /**
@@ -119,6 +119,8 @@ export interface AgentErrorMessage {
     sessionId: string;
     /** Human-readable error summary (no stack traces required). */
     message: string;
+    /** Optional stack trace from handler throw. */
+    stack?: string;
 }
 /**
  * Send a JSON-serializable payload to the browser peer over the WebRTC data channel.
@@ -135,13 +137,39 @@ export interface SendBinaryToClientMessage {
     data: Buffer;
     channel?: DataChannelKind;
 }
+/**
+ * Idle timeout fired — run {@link AgentHandlers.onIdleTimeout} before disconnect.
+ */
+export interface IdleTimeoutMessage {
+    type: "idle_timeout";
+    sessionId: string;
+    /** Wall-clock grace for the customer callback (default 30000). */
+    maxGraceMs: number;
+}
+/**
+ * Customer callback finished (or failed) after {@link IdleTimeoutMessage}.
+ */
+export interface IdleTimeoutDoneMessage {
+    type: "idle_timeout_done";
+    sessionId: string;
+    /** Set when the customer hook threw or rejected. */
+    error?: string;
+}
+/**
+ * Ask the runner to disconnect a browser peer (customer-initiated).
+ */
+export interface DisconnectClientMessage {
+    type: "disconnect_client";
+    sessionId: string;
+    reason?: string;
+}
 /**
  * Environment variable names the runner may inject into {@link SessionStartMessage.env}.
  *
  * The runner may add more project-specific keys over time; customer bundles must
  * not read `process.env` directly — only the `env` object on session start.
  */
-export declare const ALLOWED_CHILD_ENV_KEYS: readonly ["SESSION_ID", "PROJECT_ID", "BUILD_ID"];
+export declare const ALLOWED_CHILD_ENV_KEYS: readonly ["SESSION_ID", "PROJECT_ID", "BUILD_ID", "IDLE_TIMEOUT_SEC", "AGENT_CUSTOMER_CONTEXT"];
 /** Union of allowlisted env key names. */
 export type AllowedChildEnvKey = (typeof ALLOWED_CHILD_ENV_KEYS)[number];
 //# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB,kBAAkB,GAClB,iBAAiB,GACjB,yBAAyB,GACzB,wBAAwB,CAAC;AAE7B;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,eAAe,GACf,iBAAiB,GACjB,mBAAmB,GACnB,yBAAyB,CAAC;AAE9B,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,cAAc,CAAC;IACrB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qEAAqE;AACrE,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,mDAIzB,CAAC;AAEX,0CAA0C;AAC1C,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -18,5 +18,8 @@ export const ALLOWED_CHILD_ENV_KEYS = [
     "SESSION_ID",
     "PROJECT_ID",
     "BUILD_ID",
+    "IDLE_TIMEOUT_SEC",
+    /** JSON string — opaque customer context from browser session start. */
+    "AGENT_CUSTOMER_CONTEXT",
 ];
 //# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyJH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,YAAY;IACZ,YAAY;IACZ,UAAU;CACF,CAAC"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA2LH;;;;;GAKG;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

@@ -21,11 +21,17 @@ export interface DataChannelContext {
     channel: DataChannelKind;
 }
 export interface AgentHandlers {
+    /** Alias for {@link AgentHandlers.onSessionStart}. */
+    onClientJoin?: (ctx: SessionContext) => void | Promise<void>;
     onSessionStart?: (ctx: SessionContext) => void | Promise<void>;
     /** Fired for every speech lifecycle event from the parent voice pipeline. */
     onSpeechEvent?: (ctx: SpeechEventContext, event: SpeechEvent) => void | Promise<void>;
     /** Convenience handler — also invoked when `speech.type` is `user_speech_final`. */
     onUserSpeechFinal?: (ctx: SpeechContext) => void | Promise<void>;
+    /** Alias for {@link AgentHandlers.onSessionEnd}. */
+    onClientLeave?: (ctx: {
+        sessionId: string;
+    }) => void | Promise<void>;
     onSessionEnd?: (ctx: {
         sessionId: string;
     }) => void | Promise<void>;
@@ -33,10 +39,38 @@ export interface AgentHandlers {
     onDataChannelMessage?: (ctx: DataChannelContext) => void | Promise<void>;
     /** Browser data channel binary (game state, custom framing). */
     onDataChannelBinary?: (ctx: DataChannelContext) => void | Promise<void>;
+    /**
+     * Idle timeout fired — run cleanup before the runner disconnects the peer.
+     * Must not throw; errors are logged and reported as session errors.
+     */
+    onIdleTimeout?: (ctx: IdleTimeoutContext) => void | Promise<void>;
+    /**
+     * Optional — runs when handler code throws before runner crash handling.
+     * Must not throw; hook errors are logged via {@link agentLog}.
+     */
+    errorHook?: (ctx: AgentErrorContext) => void | Promise<void>;
+}
+export interface IdleTimeoutContext {
+    sessionId: string;
+    projectId?: string;
+    buildId?: string;
+    env: Record<string, string>;
+    idleTimeoutSeconds: number;
+}
+export interface AgentErrorContext {
+    sessionId: string;
+    projectId?: string;
+    buildId?: string;
+    env: Record<string, string>;
+    error: Error;
+    customerContext?: Record<string, unknown>;
 }
 /**
  * Register IPC handlers for a customer agent child process.
  * Call once at bundle entry; runner parent sends {@link ParentToChildMessage} events.
+ *
+ * Parent messages for the same `sessionId` are handled strictly in arrival order;
+ * different sessions run independently (shared-child / load-safe).
  */
 export declare function defineAgent(handlers: AgentHandlers): void;
 /** Ask the runner parent to synthesize speech for the session. */
@@ -45,8 +79,14 @@ export declare function speak(sessionId: string, text: string): void;
 export declare function sendToClient(sessionId: string, payload: unknown): void;
 /** Send raw bytes to the browser peer via the runner parent. */
 export declare function sendBinaryToClient(sessionId: string, data: Buffer | Uint8Array, channel?: DataChannelKind): void;
+/** Send the same JSON payload to one or more browser peers. */
+export declare function broadcastToClients(payload: unknown, sessionIds: readonly string[]): void;
 /** Structured log forwarded to the runner parent. */
 export declare function agentLog(level: "info" | "error", message: string): void;
+/** Ask the runner to disconnect a browser peer (customer-initiated). */
+export declare function disconnectClient(sessionId: string, options?: {
+    reason?: string;
+}): void;
 /** Extract chat text from a parsed data channel message. */
 export declare function parseChatText(message: unknown): string | null;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EACV,eAAe,EAEhB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,6EAA6E;IAC7E,aAAa,CAAC,EAAE,CACd,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,WAAW,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,6DAA6D;IAC7D,oBAAoB,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzE,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;AAsBD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CA8DzD;AAED,kEAAkE;AAClE,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3D;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAEtE;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,OAAO,GAAE,eAAwB,GAChC,IAAI,CAGN;AAED,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAEvE;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAM7D"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/runtime.js

@@ -1,3 +1,4 @@
+import { SessionSerialQueue } from "./session-serial-queue.js";
 function isParentMessage(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -6,7 +7,8 @@ function isParentMessage(value) {
         msg.type === "speech_event" ||
         msg.type === "session_end" ||
         msg.type === "data_channel_message" ||
-        msg.type === "data_channel_binary");
+        msg.type === "data_channel_binary" ||
+        msg.type === "idle_timeout");
 }
 function parseDataChannelPayload(raw) {
     try {
@@ -16,68 +18,155 @@ function parseDataChannelPayload(raw) {
         return raw;
     }
 }
+const peerEnvBySessionId = new Map();
+async function handleParentMessage(message, handlers) {
+    switch (message.type) {
+        case "session_start":
+            peerEnvBySessionId.set(message.sessionId, message.env);
+            await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
+                sessionId: message.sessionId,
+                env: message.env,
+            });
+            break;
+        case "speech_event":
+            await handlers.onSpeechEvent?.({ sessionId: message.sessionId }, message.event);
+            if (message.event.type === "user_speech_final" &&
+                typeof message.event.text === "string" &&
+                message.event.text.trim()) {
+                await handlers.onUserSpeechFinal?.({
+                    sessionId: message.sessionId,
+                    text: message.event.text.trim(),
+                });
+            }
+            break;
+        case "data_channel_message":
+            await handlers.onDataChannelMessage?.({
+                sessionId: message.sessionId,
+                message: parseDataChannelPayload(message.payload),
+                raw: message.payload,
+                rawBinary: null,
+                channel: "control",
+            });
+            break;
+        case "data_channel_binary":
+            await handlers.onDataChannelBinary?.({
+                sessionId: message.sessionId,
+                message: null,
+                raw: null,
+                rawBinary: message.data,
+                channel: message.channel ?? "sync",
+            });
+            break;
+        case "session_end":
+            peerEnvBySessionId.delete(message.sessionId);
+            await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
+                sessionId: message.sessionId,
+            });
+            break;
+        case "idle_timeout":
+            await runIdleTimeoutHook(handlers, message);
+            break;
+    }
+}
 /**
  * Register IPC handlers for a customer agent child process.
  * Call once at bundle entry; runner parent sends {@link ParentToChildMessage} events.
+ *
+ * Parent messages for the same `sessionId` are handled strictly in arrival order;
+ * different sessions run independently (shared-child / load-safe).
  */
 export function defineAgent(handlers) {
+    const inboundBySession = new SessionSerialQueue();
     process.on("message", (message) => {
         if (!isParentMessage(message))
             return;
-        void (async () => {
+        inboundBySession.enqueue(message.sessionId, async () => {
             try {
-                switch (message.type) {
-                    case "session_start":
-                        await handlers.onSessionStart?.({
-                            sessionId: message.sessionId,
-                            env: message.env,
-                        });
-                        break;
-                    case "speech_event":
-                        await handlers.onSpeechEvent?.({ sessionId: message.sessionId }, message.event);
-                        if (message.event.type === "user_speech_final" &&
-                            typeof message.event.text === "string" &&
-                            message.event.text.trim()) {
-                            await handlers.onUserSpeechFinal?.({
-                                sessionId: message.sessionId,
-                                text: message.event.text.trim(),
-                            });
-                        }
-                        break;
-                    case "data_channel_message":
-                        await handlers.onDataChannelMessage?.({
-                            sessionId: message.sessionId,
-                            message: parseDataChannelPayload(message.payload),
-                            raw: message.payload,
-                            rawBinary: null,
-                            channel: "control",
-                        });
-                        break;
-                    case "data_channel_binary":
-                        await handlers.onDataChannelBinary?.({
-                            sessionId: message.sessionId,
-                            message: null,
-                            raw: null,
-                            rawBinary: message.data,
-                            channel: message.channel ?? "sync",
-                        });
-                        break;
-                    case "session_end":
-                        await handlers.onSessionEnd?.({ sessionId: message.sessionId });
-                        break;
-                }
+                await handleParentMessage(message, handlers);
             }
             catch (error) {
-                const errMessage = error instanceof Error ? error.message : String(error);
+                const err = error instanceof Error ? error : new Error(String(error));
+                const env = peerEnvBySessionId.get(message.sessionId) ??
+                    buildIdleEnv(message.sessionId);
+                await runErrorHook(handlers, {
+                    sessionId: message.sessionId,
+                    projectId: env.PROJECT_ID,
+                    buildId: env.BUILD_ID,
+                    env,
+                    error: err,
+                    customerContext: parseCustomerContext(env.AGENT_CUSTOMER_CONTEXT),
+                });
                 process.send?.({
                     type: "agent_error",
                     sessionId: message.sessionId,
-                    message: errMessage,
+                    message: err.message,
+                    stack: err.stack,
                 });
             }
-        })();
+        });
     });
 }
+function parseCustomerContext(raw) {
+    if (!raw?.trim())
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // ignore malformed context
+    }
+    return undefined;
+}
+async function runErrorHook(handlers, ctx) {
+    if (!handlers.errorHook)
+        return;
+    try {
+        await handlers.errorHook(ctx);
+    }
+    catch (hookError) {
+        const message = hookError instanceof Error ? hookError.message : String(hookError);
+        agentLog("error", `errorHook failed: ${message}`);
+    }
+}
+async function runIdleTimeoutHook(handlers, message) {
+    const env = peerEnvBySessionId.get(message.sessionId) ??
+        buildIdleEnv(message.sessionId);
+    const idleTimeoutSeconds = Number(env.IDLE_TIMEOUT_SEC) || 0;
+    const ctx = {
+        sessionId: message.sessionId,
+        projectId: env.PROJECT_ID,
+        buildId: env.BUILD_ID,
+        env,
+        idleTimeoutSeconds,
+    };
+    let error;
+    try {
+        await handlers.onIdleTimeout?.(ctx);
+    }
+    catch (hookError) {
+        error =
+            hookError instanceof Error ? hookError.message : String(hookError);
+        agentLog("error", `onIdleTimeout failed: ${error}`);
+    }
+    process.send?.({
+        type: "idle_timeout_done",
+        sessionId: message.sessionId,
+        error,
+    });
+}
+function buildIdleEnv(sessionId) {
+    return {
+        SESSION_ID: sessionId,
+        ...(process.env.PROJECT_ID ? { PROJECT_ID: process.env.PROJECT_ID } : {}),
+        ...(process.env.BUILD_ID ? { BUILD_ID: process.env.BUILD_ID } : {}),
+        ...(process.env.IDLE_TIMEOUT_SEC
+            ? { IDLE_TIMEOUT_SEC: process.env.IDLE_TIMEOUT_SEC }
+            : {}),
+    };
+}
 /** Ask the runner parent to synthesize speech for the session. */
 export function speak(sessionId, text) {
     process.send?.({ type: "speak", sessionId, text });
@@ -89,12 +178,31 @@ export function sendToClient(sessionId, payload) {
 /** Send raw bytes to the browser peer via the runner parent. */
 export function sendBinaryToClient(sessionId, data, channel = "sync") {
     const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
-    process.send?.({ type: "send_binary_to_client", sessionId, data: buffer, channel });
+    process.send?.({
+        type: "send_binary_to_client",
+        sessionId,
+        data: buffer,
+        channel,
+    });
+}
+/** Send the same JSON payload to one or more browser peers. */
+export function broadcastToClients(payload, sessionIds) {
+    for (const sessionId of sessionIds) {
+        sendToClient(sessionId, payload);
+    }
 }
 /** Structured log forwarded to the runner parent. */
 export function agentLog(level, message) {
     process.send?.({ type: "log", level, message });
 }
+/** Ask the runner to disconnect a browser peer (customer-initiated). */
+export function disconnectClient(sessionId, options) {
+    process.send?.({
+        type: "disconnect_client",
+        sessionId,
+        reason: options?.reason,
+    });
+}
 /** Extract chat text from a parsed data channel message. */
 export function parseChatText(message) {
     if (!message || typeof message !== "object")

package/dist/runtime.js.map

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

package/dist/sandbox/sandbox.d.ts

@@ -3,6 +3,8 @@
  *
  * Keep in sync with the agent runner `src/child/sandbox.ts`.
  */
+/** Collect unique fs-read allowlist paths (resolved + realpath for /var/run → /run symlinks). */
+export declare function collectAllowFsReadDirs(paths: string[]): string[];
 /**
  * Node --permission flags for the customer child: no subprocesses, no fs writes.
  * `fs` read is limited to the loader + bundle directories (no `--allow-child-process`).

package/dist/sandbox/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/sandbox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,EAAE,CAUX"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox/sandbox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,iGAAiG;AACjG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAchE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,EAAE,CAWX"}

package/dist/sandbox/sandbox.js

@@ -3,19 +3,38 @@
  *
  * Keep in sync with the agent runner `src/child/sandbox.ts`.
  */
+import { existsSync, realpathSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+/** Collect unique fs-read allowlist paths (resolved + realpath for /var/run → /run symlinks). */
+export function collectAllowFsReadDirs(paths) {
+    const readDirs = new Set();
+    for (const raw of paths) {
+        const resolved = resolve(raw);
+        readDirs.add(resolved);
+        try {
+            if (existsSync(resolved)) {
+                readDirs.add(realpathSync(resolved));
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return [...readDirs];
+}
 /**
  * Node --permission flags for the customer child: no subprocesses, no fs writes.
  * `fs` read is limited to the loader + bundle directories (no `--allow-child-process`).
  */
 export function buildChildExecArgv(options) {
-    const readDirs = new Set([
-        resolve(options.loaderDir),
-        resolve(dirname(options.bundlePath)),
+    const readDirs = collectAllowFsReadDirs([
+        options.loaderDir,
+        dirname(options.bundlePath),
+        options.bundlePath,
     ]);
     return [
         "--permission",
-        ...[...readDirs].map((dir) => `--allow-fs-read=${dir}`),
+        ...readDirs.map((dir) => `--allow-fs-read=${dir}`),
     ];
 }
 //# sourceMappingURL=sandbox.js.map

package/dist/sandbox/sandbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/sandbox/sandbox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAGlC;IACC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS;QAC/B,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;QAC1B,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;KACrC,CAAC,CAAC;IAEH,OAAO;QACL,cAAc;QACd,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,mBAAmB,GAAG,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/sandbox/sandbox.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,iGAAiG;AACjG,MAAM,UAAU,sBAAsB,CAAC,KAAe;IACpD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACvB,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAGlC;IACC,MAAM,QAAQ,GAAG,sBAAsB,CAAC;QACtC,OAAO,CAAC,SAAS;QACjB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;QAC3B,OAAO,CAAC,UAAU;KACnB,CAAC,CAAC;IAEH,OAAO;QACL,cAAc;QACd,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,mBAAmB,GAAG,EAAE,CAAC;KACnD,CAAC;AACJ,CAAC"}

package/dist/sandbox/start-child.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start-child.d.ts","sourceRoot":"","sources":["../../src/sandbox/start-child.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AAMxB,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxE,MAAM,CACJ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,GACpE,MAAM,IAAI,CAAC;CACf;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM5D;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,cAAc,CAiEhB"}
+{"version":3,"file":"start-child.d.ts","sourceRoot":"","sources":["../../src/sandbox/start-child.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AAMxB,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACpC,SAAS,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxE,MAAM,CACJ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,KAAK,IAAI,GACpE,MAAM,IAAI,CAAC;CACf;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAU5D;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,0BAA0B,GAClC,cAAc,CAiEhB"}

package/dist/sandbox/start-child.js

@@ -4,7 +4,7 @@
  * Keep behavior aligned with runner `src/child/starter.ts`.
  */
 import { fork } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ALLOWED_CHILD_ENV_KEYS, } from "../protocol.js";
@@ -16,7 +16,12 @@ export function resolveBundlePath(bundlePath) {
     if (!existsSync(resolved)) {
         throw new Error(`Bundle not found: ${resolved}`);
     }
-    return resolved;
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
 }
 export function startSandboxedChild(options) {
     const bundlePath = resolveBundlePath(options.bundlePath);

package/dist/sandbox/start-child.js.map

@@ -1 +1 @@
-{"version":3,"file":"start-child.js","sourceRoot":"","sources":["../../src/sandbox/start-child.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAqB,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EACL,sBAAsB,GAGvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC5D,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC;AAqB1D,MAAM,UAAU,iBAAiB,CAAC,UAAkB;IAClD,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,OAAmC;IAEnC,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACzD,MAAM,GAAG,GAAsB;QAC7B,QAAQ,EAAE,YAAY;QACtB,qBAAqB,EAAE,UAAU;KAClC,CAAC;IAEF,KAAK,MAAM,GAAG,IAAI,sBAAsB,EAAE,CAAC;QACzC,IAAI,GAAG,KAAK,YAAY;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;QACvD,IAAI,GAAG,KAAK,YAAY,IAAI,OAAO,CAAC,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC;QAC5E,IAAI,GAAG,KAAK,UAAU,IAAI,OAAO,CAAC,OAAO;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;IACxE,CAAC;IAED,MAAM,KAAK,GAAiB,IAAI,CAAC,YAAY,EAAE,EAAE,EAAE;QACjD,GAAG;QACH,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;QACxC,QAAQ,EAAE,kBAAkB,CAAC;YAC3B,SAAS,EAAE,WAAW;YACtB,UAAU;SACX,CAAC;KACH,CAAC,CAAC;IAEH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;QACjC,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,IAAI,OAAO;YAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,MAAM,eAAe,GAAG,IAAI,GAAG,EAA2C,CAAC;IAC3E,MAAM,YAAY,GAAG,IAAI,GAAG,EAEzB,CAAC;IAEJ,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,OAAgB,EAAE,EAAE;QACvC,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;YAAE,OAAO;QACpD,MAAM,OAAO,GAAG,OAA+B,CAAC;QAChD,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;YACtC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;QAChC,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACxB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;QACpB,UAAU;QACV,IAAI,CAAC,OAA6B;YAChC,IAAI,CAAC,KAAK,CAAC,SAAS;gBAAE,OAAO,KAAK,CAAC;YACnC,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,SAAyB,SAAS;YACrC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,CAAC;QACD,SAAS,CAAC,OAAO;YACf,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC7B,OAAO,GAAG,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/C,CAAC;QACD,MAAM,CAAC,OAAO;YACZ,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC1B,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"start-child.js","sourceRoot":"","sources":["../../src/sandbox/start-child.ts"],"names":[],"mappings":"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"}

package/dist/session-serial-queue.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Per-session FIFO task chain. Different sessionIds run independently; the same
+ * sessionId is processed strictly in enqueue order (no overlapping handlers).
+ */
+export declare class SessionSerialQueue {
+    private readonly tails;
+    enqueue(sessionId: string, task: () => void | Promise<void>): void;
+    clear(sessionId: string): void;
+    clearAll(): void;
+}
+//# sourceMappingURL=session-serial-queue.d.ts.map

package/dist/session-serial-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-serial-queue.d.ts","sourceRoot":"","sources":["../src/session-serial-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAE1D,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAclE,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,QAAQ,IAAI,IAAI;CAGjB"}

package/dist/session-serial-queue.js

@@ -0,0 +1,23 @@
+/**
+ * Per-session FIFO task chain. Different sessionIds run independently; the same
+ * sessionId is processed strictly in enqueue order (no overlapping handlers).
+ */
+export class SessionSerialQueue {
+    tails = new Map();
+    enqueue(sessionId, task) {
+        const previous = this.tails.get(sessionId)?.catch(() => undefined) ?? Promise.resolve();
+        const next = previous.then(() => Promise.resolve(task()));
+        this.tails.set(sessionId, next.finally(() => {
+            if (this.tails.get(sessionId) === next) {
+                this.tails.delete(sessionId);
+            }
+        }));
+    }
+    clear(sessionId) {
+        this.tails.delete(sessionId);
+    }
+    clearAll() {
+        this.tails.clear();
+    }
+}
+//# sourceMappingURL=session-serial-queue.js.map

package/dist/session-serial-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-serial-queue.js","sourceRoot":"","sources":["../src/session-serial-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACZ,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE1D,OAAO,CAAC,SAAiB,EAAE,IAAgC;QACzD,MAAM,QAAQ,GACZ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACzE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC,KAAK,CAAC,GAAG,CACZ,SAAS,EACT,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YAChB,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;gBACvC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAED,QAAQ;QACN,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/package.json

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

package/templates/agent.ts

@@ -18,6 +18,7 @@
 import {
   agentLog,
   defineAgent,
+  disconnectClient,
   speak,
   type SpeechEvent,
 } from "@voicethere/agent";
@@ -173,4 +174,19 @@ defineAgent({
     peers.delete(sessionId);
     agentLog("info", `session_end ${sessionId}`);
   },
+
+  // async onIdleTimeout({ sessionId, idleTimeoutSeconds }) {
+  //   agentLog("info", `idle timeout after ${idleTimeoutSeconds}s for ${sessionId}`);
+  //   // Optional: notify client, persist state — runner disconnects after this returns (max 30s).
+  // },
+
+  // async errorHook({ sessionId, error, customerContext }) {
+  //   agentLog("error", `handler failed for ${sessionId}: ${error.message}`);
+  //   // Optional: sendToClient(sessionId, { type: "alert", message: error.message });
+  // },
+
+  // Example: disconnect a stale multiplayer client from agent code:
+  // onDataChannelMessage({ sessionId, message }) {
+  //   if (isStaleGameState(message)) disconnectClient(sessionId, { reason: "stale_state" });
+  // },
 });

package/templates/game-sync.ts

@@ -0,0 +1,68 @@
+/**
+ * Authoritative tick counter — shared child broadcasts `{ type: 'state', tick, players }`.
+ *
+ * Build:
+ *   npx @voicethere/agent build --entry templates/game-sync.ts
+ */
+import {
+  agentLog,
+  broadcastToClients,
+  defineAgent,
+  sendToClient,
+  type DataChannelContext,
+} from "@voicethere/agent";
+
+let tick = 0;
+const connected = new Set<string>();
+
+function playerCount(): number {
+  return connected.size;
+}
+
+function broadcastState(excludeSessionId?: string): void {
+  const payload = { type: "state" as const, tick, players: playerCount() };
+  const targets = excludeSessionId
+    ? [...connected].filter((id) => id !== excludeSessionId)
+    : [...connected];
+  broadcastToClients(payload, targets);
+}
+
+function handleTickMessage(ctx: DataChannelContext): void {
+  const message = ctx.message;
+  if (!message || typeof message !== "object") return;
+  const record = message as { type?: string };
+  if (record.type !== "tick") return;
+  tick += 1;
+  agentLog(
+    "info",
+    `tick=${tick} players=${playerCount()} from=${ctx.sessionId}`,
+  );
+  broadcastToClients({ type: "state", tick, players: playerCount() }, [
+    ...connected,
+  ]);
+}
+
+defineAgent({
+  onClientJoin({ sessionId }) {
+    connected.add(sessionId);
+    sendToClient(sessionId, {
+      type: "state",
+      tick,
+      players: playerCount(),
+    });
+    broadcastState(sessionId);
+    agentLog("info", `join ${sessionId} players=${playerCount()}`);
+  },
+
+  onClientLeave({ sessionId }) {
+    connected.delete(sessionId);
+    broadcastToClients({ type: "state", tick, players: playerCount() }, [
+      ...connected,
+    ]);
+    agentLog("info", `leave ${sessionId} players=${playerCount()}`);
+  },
+
+  onDataChannelMessage(ctx) {
+    handleTickMessage(ctx);
+  },
+});