@voicethere/agent 0.7.9 → 0.7.11

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

@@ -0,0 +1,1808 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+
+
+// dist/protocol.js
+var MIX_REQUIRES_VOICE_PLUS_DATA = "Mix APIs require sessionMode 'voice+data' (voice tracks and a sync data channel)";
+var TTS_POSE_REQUIRES_VOICE = "TTS pose APIs require voice or voice+data (not data-only)";
+
+// dist/runtime.js
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// dist/session-serial-queue.js
+var SessionSerialQueueCancellationError = class extends Error {
+  sessionId;
+  generation;
+  code = "SESSION_SERIAL_QUEUE_CANCELLED";
+  constructor(sessionId, generation) {
+    super(`session serial queue cancelled (sessionId=${sessionId}, generation=${generation})`);
+    this.sessionId = sessionId;
+    this.generation = generation;
+    this.name = "SessionSerialQueueCancellationError";
+  }
+};
+var SessionSerialQueue = class {
+  sessions = /* @__PURE__ */ new Map();
+  /** Monotonic token source — never reused across clear/enqueue cycles. */
+  nextGeneration = 1;
+  /**
+   * Enqueue work for `sessionId`. Returns a promise that settles when this
+   * task finishes, is skipped as stale, or is cancelled by {@link clear}.
+   * Fire-and-forget callers may ignore the return value (compat).
+   */
+  enqueue(sessionId, task) {
+    const state = this.ensureState(sessionId);
+    const captured = state;
+    const generation = captured.generation;
+    captured.pending += 1;
+    const previous = captured.tail;
+    let taskAbort = null;
+    const settled = previous.catch(() => void 0).then(async () => {
+      if (this.sessions.get(sessionId) !== captured) {
+        return "cancelled";
+      }
+      const abort = new AbortController();
+      taskAbort = abort;
+      captured.abort = abort;
+      const context = {
+        sessionId,
+        generation,
+        signal: abort.signal
+      };
+      try {
+        await Promise.resolve(task(abort.signal, context));
+        if (this.sessions.get(sessionId) !== captured) {
+          return "cancelled";
+        }
+        return "completed";
+      } catch (error) {
+        if (abort.signal.aborted || this.sessions.get(sessionId) !== captured || error instanceof SessionSerialQueueCancellationError) {
+          return "cancelled";
+        }
+        return "failed";
+      } finally {
+        if (captured.abort === abort) {
+          captured.abort = null;
+        }
+      }
+    }).finally(() => {
+      captured.pending = Math.max(0, captured.pending - 1);
+      if (taskAbort && captured.abort === taskAbort) {
+        captured.abort = null;
+      }
+    });
+    captured.tail = settled;
+    return settled;
+  }
+  /**
+   * Invalidate queued + running work for `sessionId`. Aborts the live AbortSignal,
+   * drops the map entry, and leaves a fresh identity for the next enqueue.
+   * Old in-flight `finally` blocks only touch their captured state object.
+   */
+  clear(sessionId) {
+    const old = this.sessions.get(sessionId);
+    if (!old)
+      return;
+    old.abort?.abort();
+    old.abort = null;
+    this.sessions.delete(sessionId);
+  }
+  clearAll() {
+    for (const sessionId of [...this.sessions.keys()]) {
+      this.clear(sessionId);
+    }
+  }
+  hasPending(sessionId) {
+    return (this.sessions.get(sessionId)?.pending ?? 0) > 0;
+  }
+  /** Live generation token for a session, or `undefined` when cleared. */
+  generationOf(sessionId) {
+    return this.sessions.get(sessionId)?.generation;
+  }
+  /** True when `generation` is the live map entry for `sessionId`. */
+  isCurrentGeneration(sessionId, generation) {
+    return this.sessions.get(sessionId)?.generation === generation;
+  }
+  /**
+   * True when a queue row exists for the session (registered since first
+   * enqueue, until {@link clear}). Not the same as {@link hasPending}.
+   */
+  isLive(sessionId) {
+    return this.sessions.has(sessionId);
+  }
+  /** Registered session rows (must not grow without matching `clear` calls). */
+  get activeSessionCount() {
+    return this.sessions.size;
+  }
+  ensureState(sessionId) {
+    const existing = this.sessions.get(sessionId);
+    if (existing)
+      return existing;
+    const created = {
+      generation: this.nextGeneration++,
+      tail: Promise.resolve(),
+      abort: null,
+      pending: 0
+    };
+    this.sessions.set(sessionId, created);
+    return created;
+  }
+};
+
+// dist/runtime.js
+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 isPlayAckMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "play_ack" && typeof msg.requestId === "string";
+}
+function isPlayStatusAckMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "play_status_ack" && typeof msg.requestId === "string";
+}
+function isPlayStopAckMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "play_stop_ack" && typeof msg.requestId === "string";
+}
+function isRecordingControlAckMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "recording_control_ack" && typeof msg.requestId === "string";
+}
+function isMixControlAckMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "mix_control_ack" && typeof msg.requestId === "string";
+}
+function isSttControlAckMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "stt_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" || msg.type === "recording_control_ack" || msg.type === "play_ack" || msg.type === "play_status_ack" || msg.type === "play_stop_ack" || msg.type === "mix_control_ack" || msg.type === "stt_control_ack" || msg.type === "webhook";
+}
+function isSessionScopedParentMessage(value) {
+  return isParentMessage(value) && !isWebhookMessage(value);
+}
+function parseDataChannelPayload(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+var peerEnvBySessionId = /* @__PURE__ */ new Map();
+var recordingAvailableBySessionId = /* @__PURE__ */ new Map();
+var mixAvailableBySessionId = /* @__PURE__ */ new Map();
+var ttsPoseAvailableBySessionId = /* @__PURE__ */ new Map();
+var endedSessionIds = /* @__PURE__ */ new Set();
+var PLAY_CONTROL_ACK_TIMEOUT_MS = 5e3;
+var PLAY_BYTES_MAX_DECODED_LENGTH = 64 * 1024;
+var pendingRecordingAcks = /* @__PURE__ */ new Map();
+var pendingPlayAcks = /* @__PURE__ */ new Map();
+var pendingPlayStatusAcks = /* @__PURE__ */ new Map();
+var pendingPlayStopAcks = /* @__PURE__ */ new Map();
+var MIX_CONTROL_ACK_TIMEOUT_MS = 5e3;
+var pendingMixAcks = /* @__PURE__ */ new Map();
+var pendingSttAcks = /* @__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 handlePlayAck(message) {
+  const pending = pendingPlayAcks.get(message.requestId);
+  if (!pending)
+    return;
+  clearTimeout(pending.timer);
+  pendingPlayAcks.delete(message.requestId);
+  pending.resolve({
+    ok: message.ok,
+    ...message.playId ? { playId: message.playId } : {},
+    reason: message.reason,
+    requestId: message.requestId
+  });
+}
+function handlePlayStatusAck(message) {
+  const pending = pendingPlayStatusAcks.get(message.requestId);
+  if (!pending)
+    return;
+  clearTimeout(pending.timer);
+  pendingPlayStatusAcks.delete(message.requestId);
+  pending.resolve({
+    ok: message.ok,
+    playId: message.playId,
+    ...message.status ? { status: message.status } : {},
+    reason: message.reason,
+    requestId: message.requestId
+  });
+}
+function handlePlayStopAck(message) {
+  const pending = pendingPlayStopAcks.get(message.requestId);
+  if (!pending)
+    return;
+  clearTimeout(pending.timer);
+  pendingPlayStopAcks.delete(message.requestId);
+  pending.resolve({
+    ok: message.ok,
+    playId: message.playId,
+    reason: message.reason,
+    requestId: message.requestId
+  });
+}
+function handleMixControlAck(message) {
+  const pending = pendingMixAcks.get(message.requestId);
+  if (!pending)
+    return;
+  clearTimeout(pending.timer);
+  pendingMixAcks.delete(message.requestId);
+  pending.resolve({
+    ok: message.ok,
+    reason: message.reason,
+    requestId: message.requestId,
+    ...message.statuses ? { statuses: message.statuses } : {}
+  });
+}
+function handleSttControlAck(message) {
+  const pending = pendingSttAcks.get(message.requestId);
+  if (!pending)
+    return;
+  clearTimeout(pending.timer);
+  pendingSttAcks.delete(message.requestId);
+  pending.resolve({
+    ok: message.ok,
+    reason: message.reason,
+    requestId: message.requestId
+  });
+}
+function isMixAvailableInProcess() {
+  for (const available of mixAvailableBySessionId.values()) {
+    if (available)
+      return true;
+  }
+  return false;
+}
+function assertMixAvailable() {
+  if (!isMixAvailableInProcess()) {
+    throw new Error(MIX_REQUIRES_VOICE_PLUS_DATA);
+  }
+}
+function isTtsPoseAvailableInProcess() {
+  for (const available of ttsPoseAvailableBySessionId.values()) {
+    if (available)
+      return true;
+  }
+  return false;
+}
+function assertTtsPoseAvailable() {
+  if (!isTtsPoseAvailableInProcess()) {
+    throw new Error(TTS_POSE_REQUIRES_VOICE);
+  }
+}
+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;
+}
+var sessionExecutionContext = new AsyncLocalStorage();
+var agentLogSessionContext = new AsyncLocalStorage();
+var inboundQueueAuthority = null;
+var childUnhandledRejectionGuardInstalled = false;
+function normalizeRejectionReason(reason) {
+  return reason instanceof Error ? reason : new Error(String(reason));
+}
+function installChildUnhandledRejectionGuard() {
+  if (childUnhandledRejectionGuardInstalled) {
+    return;
+  }
+  childUnhandledRejectionGuardInstalled = true;
+  process.on("unhandledRejection", (reason) => {
+    const err = normalizeRejectionReason(reason);
+    const store = sessionExecutionContext.getStore();
+    const sessionId = store?.sessionId ?? agentLogSessionContext.getStore() ?? "";
+    if (!allowOutboundForSession(sessionId || void 0)) {
+      return;
+    }
+    agentLog("error", `unhandledRejection: ${err.message}`, sessionId || void 0);
+    sendParentMessage({
+      type: "agent_error",
+      sessionId,
+      message: err.message,
+      stack: err.stack
+    });
+  });
+}
+function allowOutboundForSession(sessionId) {
+  if (!sessionId) {
+    return true;
+  }
+  const store = sessionExecutionContext.getStore();
+  const queue = inboundQueueAuthority;
+  if (store && store.sessionId === sessionId) {
+    if (!queue)
+      return !endedSessionIds.has(sessionId);
+    return queue.isCurrentGeneration(sessionId, store.generation);
+  }
+  if (endedSessionIds.has(sessionId))
+    return false;
+  if (!queue)
+    return true;
+  return queue.isLive(sessionId);
+}
+function sendParentMessage(message) {
+  const msgType = message && typeof message === "object" && "type" in message ? message.type : void 0;
+  if (msgType === "mix_control" || msgType === "stt_control") {
+    process.send?.(message);
+    return;
+  }
+  if (msgType === "play" || msgType === "play_status" || msgType === "play_stop") {
+    process.send?.(message);
+    return;
+  }
+  const sessionId = message && typeof message === "object" && "sessionId" in message && typeof message.sessionId === "string" ? message.sessionId : void 0;
+  if (!allowOutboundForSession(sessionId))
+    return;
+  process.send?.(message);
+}
+function parseBooleanEnv(value, defaultValue) {
+  if (value === void 0)
+    return defaultValue;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "")
+    return defaultValue;
+  if (["0", "false", "off", "no"].includes(normalized))
+    return false;
+  if (["1", "true", "on", "yes"].includes(normalized))
+    return true;
+  return defaultValue;
+}
+function parseNonNegativeIntegerEnv(value, defaultValue) {
+  if (value === void 0)
+    return defaultValue;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0)
+    return defaultValue;
+  return Math.floor(parsed);
+}
+function resolveSessionStartInitDelayMs() {
+  const enabled = parseBooleanEnv(process.env[SESSION_START_INIT_DELAY_ENABLED_ENV], true);
+  if (!enabled)
+    return 0;
+  return parseNonNegativeIntegerEnv(process.env[SESSION_START_INIT_DELAY_MS_ENV], 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 : "",
+    sessionIds: Array.isArray(message.sessionIds) ? message.sessionIds.filter((id) => typeof id === "string" && id.length > 0) : []
+  };
+  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
+    });
+  }
+}
+function resolveUserLanguageCode(event) {
+  const withLanguage = event;
+  const candidates = [withLanguage.language, event.text];
+  for (const value of candidates) {
+    if (typeof value === "string" && value.trim()) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+async function handleParentMessage(message, handlers) {
+  switch (message.type) {
+    case "session_start":
+      endedSessionIds.delete(message.sessionId);
+      peerEnvBySessionId.set(message.sessionId, message.env);
+      recordingAvailableBySessionId.set(message.sessionId, message.recordingAvailable ?? false);
+      mixAvailableBySessionId.set(message.sessionId, message.mixAvailable ?? false);
+      ttsPoseAvailableBySessionId.set(message.sessionId, message.ttsPoseAvailable ?? false);
+      const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
+      if (sessionStartInitDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, sessionStartInitDelayMs));
+      }
+      await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
+        sessionId: message.sessionId,
+        env: message.env,
+        recordingAvailable: message.recordingAvailable ?? false,
+        mixAvailable: message.mixAvailable ?? false,
+        ttsPoseAvailable: message.ttsPoseAvailable ?? false
+      });
+      sendParentMessage({
+        type: "session_start_ack",
+        sessionId: message.sessionId
+      });
+      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()
+        });
+      }
+      if (message.event.type === "user_language") {
+        const language = resolveUserLanguageCode(message.event);
+        if (language) {
+          await handlers.onUserLanguage?.({
+            sessionId: message.sessionId,
+            language
+          });
+        }
+      }
+      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":
+      clearPendingRecordingAcksForSession(message.sessionId, "session_ended");
+      peerEnvBySessionId.delete(message.sessionId);
+      recordingAvailableBySessionId.delete(message.sessionId);
+      mixAvailableBySessionId.delete(message.sessionId);
+      ttsPoseAvailableBySessionId.delete(message.sessionId);
+      await (handlers.onClientLeave ?? handlers.onSessionEnd)?.({
+        sessionId: message.sessionId
+      });
+      break;
+    case "idle_timeout":
+      await runIdleTimeoutHook(handlers, message);
+      break;
+  }
+}
+function defineAgent(handlers) {
+  installChildUnhandledRejectionGuard();
+  const inboundBySession = new SessionSerialQueue();
+  inboundQueueAuthority = inboundBySession;
+  const agentStartReady = runAgentStartHook(handlers);
+  process.on("message", (message) => {
+    if (isRecordingControlAckMessage(message)) {
+      handleRecordingControlAck(message);
+      return;
+    }
+    if (isPlayAckMessage(message)) {
+      handlePlayAck(message);
+      return;
+    }
+    if (isPlayStatusAckMessage(message)) {
+      handlePlayStatusAck(message);
+      return;
+    }
+    if (isPlayStopAckMessage(message)) {
+      handlePlayStopAck(message);
+      return;
+    }
+    if (isMixControlAckMessage(message)) {
+      handleMixControlAck(message);
+      return;
+    }
+    if (isSttControlAckMessage(message)) {
+      handleSttControlAck(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") {
+      endedSessionIds.delete(message.sessionId);
+      inboundBySession.clear(message.sessionId);
+    }
+    inboundBySession.enqueue(message.sessionId, async (_signal, context) => {
+      await agentStartReady;
+      try {
+        await sessionExecutionContext.run({
+          sessionId: message.sessionId,
+          generation: context.generation
+        }, async () => agentLogSessionContext.run(message.sessionId, async () => {
+          try {
+            await handleParentMessage(message, handlers);
+          } catch (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)
+            });
+            sendParentMessage({
+              type: "agent_error",
+              sessionId: message.sessionId,
+              message: err.message,
+              stack: err.stack
+            });
+          }
+        }));
+      } finally {
+        if (message.type === "session_end" && inboundBySession.isCurrentGeneration(message.sessionId, context.generation)) {
+          inboundBySession.clear(message.sessionId);
+        }
+      }
+    });
+  });
+}
+async function runAgentStartHook(handlers) {
+  if (!handlers.onAgentStart)
+    return;
+  try {
+    await handlers.onAgentStart({
+      env: process.env
+    });
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    agentLog("error", `onAgentStart failed: ${err.message}`);
+    sendParentMessage({
+      type: "agent_error",
+      sessionId: "",
+      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}`, ctx.sessionId);
+  }
+}
+async function runIdleTimeoutHook(handlers, message) {
+  const onIdleTimeout = handlers.onIdleTimeout;
+  agentLog("info", `idle_timeout ipc received (maxGraceMs=${message.maxGraceMs}, onIdleTimeout=${typeof onIdleTimeout === "function"})`, message.sessionId);
+  if (!onIdleTimeout) {
+    sendParentMessage({
+      type: "idle_timeout_done",
+      sessionId: message.sessionId
+    });
+    agentLog("info", "idle_timeout_done ipc sent (no onIdleTimeout handler)", message.sessionId);
+    return;
+  }
+  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 onIdleTimeout(ctx);
+  } catch (hookError) {
+    error = hookError instanceof Error ? hookError.message : String(hookError);
+    agentLog("error", `onIdleTimeout failed: ${error}`, message.sessionId);
+  }
+  sendParentMessage({
+    type: "idle_timeout_done",
+    sessionId: message.sessionId,
+    error
+  });
+  agentLog("info", error ? `idle_timeout_done ipc sent (onIdleTimeout error: ${error})` : "idle_timeout_done ipc sent (onIdleTimeout completed)", message.sessionId);
+}
+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) {
+  sendParentMessage({ type: "speak", sessionId, text });
+}
+function isMixAvailable(ctx) {
+  return ctx.mixAvailable;
+}
+function isTtsPoseAvailable(ctx) {
+  return ctx.ttsPoseAvailable;
+}
+async function sendMixControl(action, payload) {
+  assertMixAvailable();
+  const requestId = randomUUID();
+  if (!isVoicethereAgentChild()) {
+    return { ok: true, reason: "local_mock", requestId };
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingMixAcks.delete(requestId);
+      resolve({ ok: false, reason: "timeout", requestId });
+    }, MIX_CONTROL_ACK_TIMEOUT_MS);
+    pendingMixAcks.set(requestId, { resolve, timer });
+    sendParentMessage({
+      type: "mix_control",
+      action,
+      requestId,
+      ...payload
+    });
+  });
+}
+async function sendTtsPoseControl(action, payload) {
+  assertTtsPoseAvailable();
+  const requestId = randomUUID();
+  if (!isVoicethereAgentChild()) {
+    return { ok: true, reason: "local_mock", requestId };
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingMixAcks.delete(requestId);
+      resolve({ ok: false, reason: "timeout", requestId });
+    }, MIX_CONTROL_ACK_TIMEOUT_MS);
+    pendingMixAcks.set(requestId, { resolve, timer });
+    sendParentMessage({
+      type: "mix_control",
+      action,
+      requestId,
+      ...payload
+    });
+  });
+}
+function createMixGroup(options) {
+  return sendMixControl("create_group", {
+    groupId: options.id,
+    clientIds: [...options.clientIds]
+  });
+}
+function addClientToMix(groupId, clientId) {
+  return sendMixControl("add_client", { groupId, clientId });
+}
+function removeClientFromMix(groupId, clientId) {
+  return sendMixControl("remove_client", { groupId, clientId });
+}
+function setClientPose(clientId, pose) {
+  return sendTtsPoseControl("set_pose", { clientId, pose });
+}
+function setPositionalMixing(enabled) {
+  return sendTtsPoseControl("set_positional", { enabled });
+}
+function setTtsPose(sessionId, pose) {
+  return sendTtsPoseControl("set_tts_pose", { clientId: sessionId, pose });
+}
+function clearTtsPose(sessionId) {
+  return sendTtsPoseControl("clear_tts_pose", { clientId: sessionId });
+}
+function setListenerMute(options) {
+  return sendMixControl("set_listener_mute", {
+    clientId: options.targetId,
+    listenerId: options.listenerId,
+    muted: options.muted
+  });
+}
+function validatePlayOptions(options) {
+  const requestId = randomUUID();
+  const url = options.url?.trim();
+  if (!url) {
+    return { ok: false, reason: "invalid_payload", requestId };
+  }
+  if (options.placement != null && options.pose != null) {
+    return { ok: false, reason: "invalid_payload", requestId };
+  }
+  if (options.bytes !== void 0) {
+    try {
+      const decoded = Buffer.from(options.bytes, "base64");
+      if (decoded.length > PLAY_BYTES_MAX_DECODED_LENGTH) {
+        return { ok: false, reason: "invalid_payload", requestId };
+      }
+    } catch {
+      return { ok: false, reason: "invalid_payload", requestId };
+    }
+  }
+  return null;
+}
+async function sendPlayControl(options) {
+  const invalid = validatePlayOptions(options);
+  if (invalid)
+    return invalid;
+  const requestId = randomUUID();
+  if (!isVoicethereAgentChild()) {
+    return {
+      ok: true,
+      playId: `local-mock-${requestId}`,
+      reason: "local_mock",
+      requestId
+    };
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingPlayAcks.delete(requestId);
+      resolve({ ok: false, reason: "timeout", requestId });
+    }, PLAY_CONTROL_ACK_TIMEOUT_MS);
+    pendingPlayAcks.set(requestId, { resolve, timer });
+    sendParentMessage({
+      type: "play",
+      requestId,
+      url: options.url.trim(),
+      ...options.sessionIds?.length ? { sessionIds: [...options.sessionIds] } : {},
+      ...options.volume !== void 0 ? { volume: options.volume } : {},
+      ...options.bytes !== void 0 ? { bytes: options.bytes } : {},
+      ...options.placement !== void 0 ? { placement: options.placement } : {},
+      ...options.pose !== void 0 ? { pose: options.pose } : {}
+    });
+  });
+}
+async function sendPlayStatus(playId) {
+  const requestId = randomUUID();
+  if (!playId?.trim()) {
+    return {
+      ok: false,
+      playId: playId ?? "",
+      reason: "invalid_payload",
+      requestId
+    };
+  }
+  if (!isVoicethereAgentChild()) {
+    return {
+      ok: true,
+      playId,
+      status: "ended",
+      reason: "local_mock",
+      requestId
+    };
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingPlayStatusAcks.delete(requestId);
+      resolve({ ok: false, playId, reason: "timeout", requestId });
+    }, PLAY_CONTROL_ACK_TIMEOUT_MS);
+    pendingPlayStatusAcks.set(requestId, { playId, resolve, timer });
+    sendParentMessage({
+      type: "play_status",
+      requestId,
+      playId
+    });
+  });
+}
+async function sendPlayStop(playId) {
+  const requestId = randomUUID();
+  if (!playId?.trim()) {
+    return {
+      ok: false,
+      playId: playId ?? "",
+      reason: "invalid_payload",
+      requestId
+    };
+  }
+  if (!isVoicethereAgentChild()) {
+    return { ok: true, playId, reason: "local_mock", requestId };
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingPlayStopAcks.delete(requestId);
+      resolve({ ok: false, playId, reason: "timeout", requestId });
+    }, PLAY_CONTROL_ACK_TIMEOUT_MS);
+    pendingPlayStopAcks.set(requestId, { playId, resolve, timer });
+    sendParentMessage({
+      type: "play_stop",
+      requestId,
+      playId
+    });
+  });
+}
+function play(options) {
+  return sendPlayControl(options);
+}
+function getPlay(playId) {
+  return sendPlayStatus(playId);
+}
+function stopPlay(playId) {
+  return sendPlayStop(playId);
+}
+function sendToClient(sessionId, payload) {
+  sendParentMessage({ type: "send_to_client", sessionId, payload });
+}
+var AGENT_LOG_MESSAGE_MAX_CHARS = 2048;
+var AGENT_LOG_FIELDS_MAX_CHARS = 8192;
+function truncateAgentLogMessage(message) {
+  if (message.length <= AGENT_LOG_MESSAGE_MAX_CHARS) {
+    return message;
+  }
+  const suffix = "\u2026[truncated]";
+  return message.slice(0, AGENT_LOG_MESSAGE_MAX_CHARS - suffix.length) + suffix;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sanitizeAgentLogFields(fields) {
+  if (Object.keys(fields).length === 0) {
+    return void 0;
+  }
+  try {
+    const serialized = JSON.stringify(fields);
+    if (serialized.length <= AGENT_LOG_FIELDS_MAX_CHARS) {
+      return fields;
+    }
+    return {
+      _agentLogFieldsTruncated: true,
+      _originalBytes: serialized.length,
+      _preview: serialized.slice(0, AGENT_LOG_FIELDS_MAX_CHARS - 80) + "\u2026[truncated]"
+    };
+  } catch {
+    return { _agentLogFieldsError: "not_serializable" };
+  }
+}
+function buildAgentLogPayload(level, message, fields, sessionId) {
+  const resolvedSessionId = sessionId ?? sessionExecutionContext.getStore()?.sessionId ?? agentLogSessionContext.getStore();
+  const sanitizedFields = fields ? sanitizeAgentLogFields(fields) : void 0;
+  return {
+    type: "log",
+    level,
+    message: truncateAgentLogMessage(message),
+    ts: Date.now(),
+    ...resolvedSessionId ? { sessionId: resolvedSessionId } : {},
+    ...sanitizedFields ? { fields: sanitizedFields } : {}
+  };
+}
+function agentLog(level, message, fieldsOrSessionId, sessionId) {
+  let fields;
+  let resolvedSessionId;
+  if (typeof fieldsOrSessionId === "string") {
+    resolvedSessionId = fieldsOrSessionId;
+  } else if (isPlainObject(fieldsOrSessionId)) {
+    fields = fieldsOrSessionId;
+    resolvedSessionId = sessionId;
+  } else {
+    resolvedSessionId = sessionId;
+  }
+  sendParentMessage(buildAgentLogPayload(level, message, fields, resolvedSessionId));
+}
+
+// templates/spatial-showcase/orbit.ts
+function orbitTtsPose(elapsedSec, options = {}) {
+  const radius = options.radius ?? 2;
+  const periodSec = options.periodSec ?? 2 * Math.PI;
+  const elevation = options.elevation ?? 0;
+  const angle = 2 * Math.PI * elapsedSec / periodSec;
+  const x = Math.cos(angle) * radius;
+  const z = Math.sin(angle) * radius;
+  return {
+    position: { x, y: elevation, z },
+    orientation: { x: 0, y: 0, z: 0, w: 1 }
+  };
+}
+
+// templates/spatial-showcase/orbit-session.ts
+function stopOrbitInterval(state) {
+  if (state.orbitTimer) {
+    clearInterval(state.orbitTimer);
+    state.orbitTimer = void 0;
+  }
+}
+function resetOrbitSession(state) {
+  stopOrbitInterval(state);
+  state.orbitStartMs = void 0;
+  state.lastOrbitPoseEmitMs = void 0;
+}
+function beginOrbitClock(state) {
+  state.orbitStartMs = Date.now();
+  state.lastOrbitPoseEmitMs = void 0;
+}
+
+// templates/spatial-showcase/sounds.ts
+var SHOWCASE_SOUND_FILES = {
+  chime: { file: "chime.wav", loop: false, defaultVolume: 0.8 },
+  bell: { file: "bell.wav", loop: false, defaultVolume: 0.8 },
+  laser: { file: "laser.wav", loop: false, defaultVolume: 0.7 },
+  impact: { file: "impact.wav", loop: false, defaultVolume: 0.85 },
+  footsteps: { file: "footsteps.wav", loop: false, defaultVolume: 0.75 },
+  "rain-loop": { file: "rain-loop.wav", loop: true, defaultVolume: 0.5 },
+  "cafe-loop": { file: "cafe-loop.wav", loop: true, defaultVolume: 0.5 },
+  jingle: { file: "jingle.wav", loop: false, defaultVolume: 0.8 }
+};
+var SHOWCASE_ASSET_ORIGINS = [
+  "https://app.voicethere.io",
+  "https://app.voicethere.dev",
+  "http://localhost:3000"
+];
+var CLIP_IDS = new Set(Object.keys(SHOWCASE_SOUND_FILES));
+function isShowcaseClipId(clipId) {
+  return CLIP_IDS.has(clipId);
+}
+function normalizeOrigin(origin) {
+  return origin.replace(/\/+$/, "");
+}
+function isAllowedOrigin(origin) {
+  const normalized = normalizeOrigin(origin);
+  return SHOWCASE_ASSET_ORIGINS.some(
+    (allowed) => normalizeOrigin(allowed) === normalized
+  );
+}
+function resolveClipUrl(assetOrigin, clipId) {
+  if (!isAllowedOrigin(assetOrigin) || !isShowcaseClipId(clipId)) {
+    return null;
+  }
+  const { file } = SHOWCASE_SOUND_FILES[clipId];
+  return `${normalizeOrigin(assetOrigin)}/showcase/sounds/${file}`;
+}
+
+// templates/spatial-showcase/protocol.ts
+var SHOWCASE_DEMOS = /* @__PURE__ */ new Set(["orbit", "soundboard", "proximity"]);
+var MAX_SAY_TEXT_LENGTH = 200;
+var MAX_XZ = 5;
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function clampVolume(value) {
+  return Math.min(1, Math.max(0, value));
+}
+function isInXzRange(value) {
+  return value >= -MAX_XZ && value <= MAX_XZ;
+}
+function isMixPlacement(value) {
+  return value === "center" || value === "left" || value === "right" || value === "front" || value === "behind" || value === "below" || value === "above";
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isShowcaseDemo(value) {
+  return typeof value === "string" && SHOWCASE_DEMOS.has(value);
+}
+function parseShowcaseMessage(message) {
+  if (!message || typeof message !== "object") {
+    return null;
+  }
+  const record = message;
+  if (typeof record.type !== "string") {
+    return null;
+  }
+  switch (record.type) {
+    case "join": {
+      const join = message;
+      if (!isShowcaseDemo(join.demo)) {
+        return null;
+      }
+      if (join.assetOrigin !== void 0 && typeof join.assetOrigin !== "string") {
+        return null;
+      }
+      return {
+        type: "join",
+        demo: join.demo,
+        ...typeof join.assetOrigin === "string" ? { assetOrigin: join.assetOrigin } : {}
+      };
+    }
+    case "orbit": {
+      const orbit = message;
+      if (orbit.action === "set") {
+        const set = message;
+        if (set.radius !== void 0 && (!isFiniteNumber(set.radius) || set.radius <= 0)) {
+          return null;
+        }
+        if (set.periodSec !== void 0 && (!isFiniteNumber(set.periodSec) || set.periodSec <= 0)) {
+          return null;
+        }
+        if (set.elevation !== void 0 && !isFiniteNumber(set.elevation)) {
+          return null;
+        }
+        if (set.paused !== void 0 && typeof set.paused !== "boolean") {
+          return null;
+        }
+        return {
+          type: "orbit",
+          action: "set",
+          ...set.radius !== void 0 ? { radius: set.radius } : {},
+          ...set.periodSec !== void 0 ? { periodSec: set.periodSec } : {},
+          ...set.elevation !== void 0 ? { elevation: set.elevation } : {},
+          ...set.paused !== void 0 ? { paused: set.paused } : {}
+        };
+      }
+      if (orbit.action === "say") {
+        const say = message;
+        if (typeof say.text !== "string" || say.text.length === 0 || say.text.length > MAX_SAY_TEXT_LENGTH) {
+          return null;
+        }
+        return { type: "orbit", action: "say", text: say.text };
+      }
+      return null;
+    }
+    case "pad": {
+      const pad = message;
+      if (!isShowcaseClipId(pad.clipId)) {
+        return null;
+      }
+      if (!isFiniteNumber(pad.x) || !isInXzRange(pad.x)) {
+        return null;
+      }
+      if (!isFiniteNumber(pad.z) || !isInXzRange(pad.z)) {
+        return null;
+      }
+      if (pad.volume !== void 0) {
+        if (!isFiniteNumber(pad.volume)) {
+          return null;
+        }
+      }
+      if (pad.placement !== void 0 && !isMixPlacement(pad.placement)) {
+        return null;
+      }
+      return {
+        type: "pad",
+        clipId: pad.clipId,
+        x: pad.x,
+        z: pad.z,
+        ...pad.volume !== void 0 ? { volume: clampVolume(pad.volume) } : {},
+        ...pad.placement !== void 0 ? { placement: pad.placement } : {}
+      };
+    }
+    case "pad_stop": {
+      const stop = message;
+      if (!isNonEmptyString(stop.playId)) {
+        return null;
+      }
+      return { type: "pad_stop", playId: stop.playId.trim() };
+    }
+    case "pad_status": {
+      const status = message;
+      if (!isNonEmptyString(status.playId)) {
+        return null;
+      }
+      return { type: "pad_status", playId: status.playId.trim() };
+    }
+    case "move": {
+      const move = message;
+      if (!isFiniteNumber(move.x) || !isInXzRange(move.x)) {
+        return null;
+      }
+      if (!isFiniteNumber(move.z) || !isInXzRange(move.z)) {
+        return null;
+      }
+      if (move.yawDeg !== void 0 && !isFiniteNumber(move.yawDeg)) {
+        return null;
+      }
+      return {
+        type: "move",
+        x: move.x,
+        z: move.z,
+        ...move.yawDeg !== void 0 ? { yawDeg: move.yawDeg } : {}
+      };
+    }
+    case "mute_peer": {
+      const mute = message;
+      if (!isNonEmptyString(mute.peerId) || typeof mute.muted !== "boolean") {
+        return null;
+      }
+      return {
+        type: "mute_peer",
+        peerId: mute.peerId.trim(),
+        muted: mute.muted
+      };
+    }
+    case "leave":
+      return { type: "leave" };
+    case "ping":
+      return { type: "ping" };
+    default:
+      return null;
+  }
+}
+function poseAt(x, z, yawDeg = 0) {
+  const yawRad = yawDeg * Math.PI / 180;
+  const half = yawRad / 2;
+  return {
+    position: { x, y: 0, z },
+    orientation: {
+      x: 0,
+      y: Math.sin(half),
+      z: 0,
+      w: Math.cos(half)
+    }
+  };
+}
+
+// templates/spatial-showcase/room.ts
+var MAX_ROOM_PEERS = 8;
+var ProximityRoom = class {
+  members = /* @__PURE__ */ new Map();
+  listenerMutes = /* @__PURE__ */ new Map();
+  join(sessionId) {
+    if (this.members.has(sessionId)) {
+      return "ok";
+    }
+    if (this.members.size >= MAX_ROOM_PEERS) {
+      return "full";
+    }
+    this.members.set(sessionId, { x: 0, z: 0, yawDeg: 0 });
+    return "ok";
+  }
+  leave(sessionId) {
+    this.members.delete(sessionId);
+    this.listenerMutes.delete(sessionId);
+    for (const targets of this.listenerMutes.values()) {
+      targets.delete(sessionId);
+    }
+  }
+  setPose(sessionId, x, z, yawDeg) {
+    const peer = this.members.get(sessionId);
+    if (!peer) {
+      return;
+    }
+    peer.x = x;
+    peer.z = z;
+    peer.yawDeg = yawDeg;
+  }
+  memberIds() {
+    return [...this.members.keys()];
+  }
+  /** Per-listener view — `muted` is whether this listener muted the peer (never true for self). */
+  snapshotFor(listenerId) {
+    const mutesForListener = this.listenerMutes.get(listenerId);
+    return [...this.members.entries()].map(([id, pose]) => ({
+      id,
+      x: pose.x,
+      z: pose.z,
+      yawDeg: pose.yawDeg,
+      muted: id !== listenerId && mutesForListener?.get(id) === true
+    }));
+  }
+  setPeerMuted(listenerId, targetId, muted) {
+    let targets = this.listenerMutes.get(listenerId);
+    if (!targets) {
+      targets = /* @__PURE__ */ new Map();
+      this.listenerMutes.set(listenerId, targets);
+    }
+    targets.set(targetId, muted);
+  }
+  clear() {
+    this.members.clear();
+    this.listenerMutes.clear();
+  }
+};
+
+// templates/spatial-showcase/agent.ts
+var ORBIT_TICK_MS = 50;
+var ORBIT_POSE_EMIT_MS = 100;
+var ROOM_STATE_TICK_MS = 100;
+var LOOP_PAD_POLL_MS = 250;
+var MAX_ACTIVE_PLAYS = 4;
+var SHOWCASE_ROOM_GROUP_ID = "showcase-room";
+var sessions = /* @__PURE__ */ new Map();
+var proximityRoom = new ProximityRoom();
+var showcaseRoomGroupReady = null;
+var lastRoomSnapshotByListener = /* @__PURE__ */ new Map();
+function ensureShowcaseRoomGroup() {
+  if (!showcaseRoomGroupReady) {
+    showcaseRoomGroupReady = createMixGroup({
+      id: SHOWCASE_ROOM_GROUP_ID,
+      clientIds: []
+    }).then((result) => result.ok).catch(() => false);
+  }
+  return showcaseRoomGroupReady;
+}
+function ack(sessionId, action, extra) {
+  sendToClient(sessionId, {
+    type: "showcase_ack",
+    action,
+    ok: true,
+    ...extra
+  });
+}
+function ackError(sessionId, action, error) {
+  sendToClient(sessionId, {
+    type: "showcase_ack",
+    action,
+    ok: false,
+    error
+  });
+}
+async function safeMixCall(sessionId, label, fn) {
+  try {
+    const result = await fn();
+    if (!result.ok) {
+      agentLog(
+        "warn",
+        `spatial-showcase ${label} failed: ${result.reason}`,
+        sessionId
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    agentLog(
+      "warn",
+      `spatial-showcase ${label} error: ${String(err)}`,
+      sessionId
+    );
+    return false;
+  }
+}
+function defaultSessionState(demo, assetOrigin) {
+  return {
+    demo,
+    assetOrigin,
+    orbit: { radius: 2, periodSec: 2 * Math.PI, elevation: 0, paused: false },
+    playIds: /* @__PURE__ */ new Set(),
+    loopPads: /* @__PURE__ */ new Map(),
+    loopPollTimers: /* @__PURE__ */ new Map(),
+    inProximityRoom: false
+  };
+}
+function clearRoomStateTimer(state) {
+  if (state.roomStateTimer) {
+    clearInterval(state.roomStateTimer);
+    state.roomStateTimer = void 0;
+  }
+}
+function clearLoopPad(sessionId, state, playId) {
+  const timer = state.loopPollTimers.get(playId);
+  if (timer) {
+    clearInterval(timer);
+    state.loopPollTimers.delete(playId);
+  }
+  state.loopPads.delete(playId);
+  state.playIds.delete(playId);
+}
+function clearAllPlays(sessionId, state) {
+  for (const playId of [...state.playIds]) {
+    state.loopPads.delete(playId);
+    const timer = state.loopPollTimers.get(playId);
+    if (timer) {
+      clearInterval(timer);
+      state.loopPollTimers.delete(playId);
+    }
+    void stopPlay(playId);
+  }
+  state.playIds.clear();
+  state.loopPads.clear();
+  state.loopPollTimers.clear();
+}
+function emitOrbitPose(sessionId, state) {
+  if (!state.orbitStartMs) {
+    return;
+  }
+  const now = Date.now();
+  if (state.lastOrbitPoseEmitMs !== void 0 && now - state.lastOrbitPoseEmitMs < ORBIT_POSE_EMIT_MS) {
+    return;
+  }
+  state.lastOrbitPoseEmitMs = now;
+  const elapsedSec = (now - state.orbitStartMs) / 1e3;
+  const pose = orbitTtsPose(elapsedSec, state.orbit);
+  const angleRad = 2 * Math.PI * elapsedSec / (state.orbit.periodSec ?? 2 * Math.PI);
+  sendToClient(sessionId, {
+    type: "orbit_pose",
+    angleDeg: angleRad * 180 / Math.PI,
+    x: pose.position.x,
+    z: pose.position.z
+  });
+}
+function startOrbitDemo(sessionId, state) {
+  stopOrbitInterval(state);
+  beginOrbitClock(state);
+  state.orbitTimer = setInterval(() => {
+    if (state.orbit.paused || !state.orbitStartMs) {
+      return;
+    }
+    const elapsedSec = (Date.now() - state.orbitStartMs) / 1e3;
+    void safeMixCall(
+      sessionId,
+      "setTtsPose",
+      () => setTtsPose(sessionId, orbitTtsPose(elapsedSec, state.orbit))
+    );
+    emitOrbitPose(sessionId, state);
+  }, ORBIT_TICK_MS);
+  emitOrbitPose(sessionId, state);
+  speak(sessionId, "I'll circle around you.");
+}
+function broadcastRoomStateIfChanged() {
+  const memberIds = proximityRoom.memberIds();
+  if (memberIds.length === 0) {
+    lastRoomSnapshotByListener.clear();
+    return;
+  }
+  for (const listenerId of memberIds) {
+    const peers = proximityRoom.snapshotFor(listenerId);
+    const payload = JSON.stringify(peers);
+    if (lastRoomSnapshotByListener.get(listenerId) === payload) {
+      continue;
+    }
+    lastRoomSnapshotByListener.set(listenerId, payload);
+    sendToClient(listenerId, { type: "room_state", peers });
+  }
+  for (const listenerId of [...lastRoomSnapshotByListener.keys()]) {
+    if (!memberIds.includes(listenerId)) {
+      lastRoomSnapshotByListener.delete(listenerId);
+    }
+  }
+}
+function startProximityRoomBroadcast(sessionId, state) {
+  clearRoomStateTimer(state);
+  state.roomStateTimer = setInterval(() => {
+    broadcastRoomStateIfChanged();
+  }, ROOM_STATE_TICK_MS);
+  lastRoomSnapshotByListener.clear();
+  broadcastRoomStateIfChanged();
+}
+async function startLoopPadPoll(sessionId, state, playId, pad) {
+  const assetOrigin = state.assetOrigin;
+  if (!assetOrigin) {
+    return;
+  }
+  const timer = setInterval(() => {
+    void (async () => {
+      const loopState = state.loopPads.get(playId);
+      if (!loopState) {
+        clearInterval(timer);
+        return;
+      }
+      const status = await getPlay(playId);
+      if (!status.ok) {
+        return;
+      }
+      if (status.status === "ended") {
+        const url = resolveClipUrl(assetOrigin, pad.clipId);
+        if (!url) {
+          ackError(sessionId, "pad", "invalid_asset_origin");
+          return;
+        }
+        const options = {
+          url,
+          sessionIds: [sessionId],
+          volume: pad.volume,
+          ...pad.placement ? { placement: pad.placement } : { pose: poseAt(pad.x, pad.z) }
+        };
+        const replay = await play(options);
+        if (replay.ok && replay.playId) {
+          clearLoopPad(sessionId, state, playId);
+          state.playIds.add(replay.playId);
+          state.loopPads.set(replay.playId, pad);
+          void startLoopPadPoll(sessionId, state, replay.playId, pad);
+        }
+      } else if (status.status) {
+        sendToClient(sessionId, {
+          type: "pad_progress",
+          playId,
+          status: status.status
+        });
+      }
+    })();
+  }, LOOP_PAD_POLL_MS);
+  state.loopPollTimers.set(playId, timer);
+}
+async function handlePadPlay(sessionId, state, clipId, x, z, volume, placement) {
+  if (state.playIds.size >= MAX_ACTIVE_PLAYS) {
+    ackError(sessionId, "pad", "busy");
+    return;
+  }
+  const assetOrigin = state.assetOrigin;
+  if (!assetOrigin) {
+    ackError(sessionId, "pad", "missing_asset_origin");
+    return;
+  }
+  const url = resolveClipUrl(assetOrigin, clipId);
+  if (!url) {
+    ackError(sessionId, "pad", "invalid_asset_origin");
+    return;
+  }
+  const sound = SHOWCASE_SOUND_FILES[clipId];
+  const playVolume = volume ?? sound.defaultVolume;
+  const options = {
+    url,
+    sessionIds: [sessionId],
+    volume: playVolume,
+    ...placement ? { placement } : { pose: poseAt(x, z) }
+  };
+  const result = await play(options);
+  if (!result.ok || !result.playId) {
+    ackError(sessionId, "pad", result.reason ?? "play_failed");
+    return;
+  }
+  state.playIds.add(result.playId);
+  ack(sessionId, "pad", { playId: result.playId });
+  if (sound.loop) {
+    const pad = {
+      clipId,
+      volume: playVolume,
+      x,
+      z,
+      placement,
+      loop: true
+    };
+    state.loopPads.set(result.playId, pad);
+    void startLoopPadPoll(sessionId, state, result.playId, pad);
+  }
+}
+async function handleJoin(sessionId, demo, assetOrigin) {
+  teardownSession(sessionId);
+  const state = defaultSessionState(demo, assetOrigin);
+  sessions.set(sessionId, state);
+  const mixOk = await safeMixCall(
+    sessionId,
+    "setPositionalMixing",
+    () => setPositionalMixing(true)
+  );
+  if (!mixOk) {
+    ackError(sessionId, "join", "positional_mixing_unavailable");
+    return;
+  }
+  ack(sessionId, "join");
+  switch (demo) {
+    case "orbit":
+      startOrbitDemo(sessionId, state);
+      break;
+    case "soundboard":
+      break;
+    case "proximity": {
+      const groupOk = await ensureShowcaseRoomGroup();
+      if (!groupOk) {
+        ackError(sessionId, "join", "mix_group_unavailable");
+        return;
+      }
+      const joined = proximityRoom.join(sessionId);
+      if (joined === "full") {
+        sendToClient(sessionId, { type: "room_full" });
+        sessions.delete(sessionId);
+        return;
+      }
+      const added = await safeMixCall(
+        sessionId,
+        "addClientToMix",
+        () => addClientToMix(SHOWCASE_ROOM_GROUP_ID, sessionId)
+      );
+      if (!added) {
+        proximityRoom.leave(sessionId);
+        sessions.delete(sessionId);
+        ackError(sessionId, "join", "add_to_mix_failed");
+        return;
+      }
+      state.inProximityRoom = true;
+      startProximityRoomBroadcast(sessionId, state);
+      speak(sessionId, "Welcome to the proximity room.");
+      await safeMixCall(
+        sessionId,
+        "setTtsPose",
+        () => setTtsPose(sessionId, poseAt(0, 0))
+      );
+      break;
+    }
+  }
+}
+function teardownSession(sessionId) {
+  const state = sessions.get(sessionId);
+  if (!state) {
+    return;
+  }
+  resetOrbitSession(state);
+  clearRoomStateTimer(state);
+  clearAllPlays(sessionId, state);
+  void safeMixCall(sessionId, "clearTtsPose", () => clearTtsPose(sessionId));
+  if (state.inProximityRoom) {
+    proximityRoom.leave(sessionId);
+    void safeMixCall(
+      sessionId,
+      "removeClientFromMix",
+      () => removeClientFromMix(SHOWCASE_ROOM_GROUP_ID, sessionId)
+    );
+    state.inProximityRoom = false;
+    broadcastRoomStateIfChanged();
+  }
+  sessions.delete(sessionId);
+}
+async function dispatchMessage(sessionId, message) {
+  const state = sessions.get(sessionId);
+  switch (message.type) {
+    case "join":
+      await handleJoin(sessionId, message.demo, message.assetOrigin);
+      return;
+    case "ping":
+      return;
+    case "leave":
+      teardownSession(sessionId);
+      ack(sessionId, "leave");
+      return;
+    default:
+      if (!state) {
+        ackError(sessionId, message.type, "join_required");
+        return;
+      }
+  }
+  if (!state) {
+    return;
+  }
+  switch (message.type) {
+    case "orbit": {
+      if (state.demo !== "orbit") {
+        ackError(sessionId, "orbit", "wrong_demo");
+        return;
+      }
+      if (message.action === "set") {
+        if (message.radius !== void 0) {
+          state.orbit.radius = message.radius;
+        }
+        if (message.periodSec !== void 0) {
+          state.orbit.periodSec = message.periodSec;
+        }
+        if (message.elevation !== void 0) {
+          state.orbit.elevation = message.elevation;
+        }
+        if (message.paused !== void 0) {
+          state.orbit.paused = message.paused;
+        }
+        ack(sessionId, "orbit_set");
+        return;
+      }
+      speak(sessionId, message.text);
+      ack(sessionId, "orbit_say");
+      return;
+    }
+    case "pad": {
+      if (state.demo !== "soundboard") {
+        ackError(sessionId, "pad", "wrong_demo");
+        return;
+      }
+      await handlePadPlay(
+        sessionId,
+        state,
+        message.clipId,
+        message.x,
+        message.z,
+        message.volume,
+        message.placement
+      );
+      return;
+    }
+    case "pad_stop": {
+      const loopPad = state.loopPads.get(message.playId);
+      if (loopPad) {
+        clearLoopPad(sessionId, state, message.playId);
+      } else {
+        state.playIds.delete(message.playId);
+      }
+      const stopped = await stopPlay(message.playId);
+      if (!stopped.ok) {
+        ackError(sessionId, "pad_stop", stopped.reason ?? "stop_failed");
+        return;
+      }
+      ack(sessionId, "pad_stop");
+      return;
+    }
+    case "pad_status": {
+      const status = await getPlay(message.playId);
+      if (!status.ok) {
+        ackError(sessionId, "pad_status", status.reason ?? "status_failed");
+        return;
+      }
+      if (status.status) {
+        sendToClient(sessionId, {
+          type: "pad_progress",
+          playId: message.playId,
+          status: status.status
+        });
+      } else {
+        ack(sessionId, "pad_status");
+      }
+      return;
+    }
+    case "move": {
+      if (state.demo !== "proximity") {
+        ackError(sessionId, "move", "wrong_demo");
+        return;
+      }
+      const yawDeg = message.yawDeg ?? 0;
+      proximityRoom.setPose(sessionId, message.x, message.z, yawDeg);
+      const poseOk = await safeMixCall(
+        sessionId,
+        "setClientPose",
+        () => setClientPose(sessionId, poseAt(message.x, message.z, yawDeg))
+      );
+      if (!poseOk) {
+        ackError(sessionId, "move", "set_pose_failed");
+        return;
+      }
+      lastRoomSnapshotByListener.clear();
+      broadcastRoomStateIfChanged();
+      ack(sessionId, "move");
+      return;
+    }
+    case "mute_peer": {
+      if (state.demo !== "proximity") {
+        ackError(sessionId, "mute_peer", "wrong_demo");
+        return;
+      }
+      proximityRoom.setPeerMuted(sessionId, message.peerId, message.muted);
+      const muteOk = await safeMixCall(
+        sessionId,
+        "setListenerMute",
+        () => setListenerMute({
+          listenerId: sessionId,
+          targetId: message.peerId,
+          muted: message.muted
+        })
+      );
+      if (!muteOk) {
+        ackError(sessionId, "mute_peer", "mute_failed");
+        return;
+      }
+      lastRoomSnapshotByListener.clear();
+      broadcastRoomStateIfChanged();
+      ack(sessionId, "mute_peer");
+      return;
+    }
+    default:
+      return;
+  }
+}
+defineAgent({
+  onAgentStart() {
+    for (const sessionId of [...sessions.keys()]) {
+      teardownSession(sessionId);
+    }
+    sessions.clear();
+    proximityRoom.clear();
+    showcaseRoomGroupReady = null;
+    lastRoomSnapshotByListener.clear();
+  },
+  onSessionStart(ctx) {
+    const { sessionId } = ctx;
+    if (!isMixAvailable(ctx) && !isTtsPoseAvailable(ctx)) {
+      agentLog(
+        "warn",
+        "spatial-showcase requires voice or Voice+Data \u2014 mix/TTS pose APIs unavailable",
+        sessionId
+      );
+      return;
+    }
+    sendToClient(sessionId, {
+      type: "showcase_ack",
+      action: "hello",
+      ok: true
+    });
+  },
+  onUserSpeechFinal({ sessionId, text }) {
+    const state = sessions.get(sessionId);
+    if (!state || state.demo !== "orbit") {
+      return;
+    }
+    speak(sessionId, `You said: ${text}`);
+  },
+  onDataChannelMessage(ctx) {
+    const message = parseShowcaseMessage(ctx.message);
+    if (!message) {
+      return;
+    }
+    void dispatchMessage(ctx.sessionId, message);
+  },
+  onSessionEnd({ sessionId }) {
+    teardownSession(sessionId);
+    agentLog("info", `spatial-showcase session_end ${sessionId}`, sessionId);
+  }
+});
+export {
+  handlePadPlay
+};