@voicethere/agent 0.2.16 → 0.3.0

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

@@ -0,0 +1,598 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+
+
+// dist/runtime.js
+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 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";
+}
+function parseDataChannelPayload(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+var peerEnvBySessionId = /* @__PURE__ */ new Map();
+var endedSessionIds = /* @__PURE__ */ new Set();
+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 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 handleParentMessage(message, handlers) {
+  switch (message.type) {
+    case "session_start":
+      endedSessionIds.delete(message.sessionId);
+      peerEnvBySessionId.set(message.sessionId, message.env);
+      const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
+      if (sessionStartInitDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, sessionStartInitDelayMs));
+      }
+      await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
+        sessionId: message.sessionId,
+        env: message.env
+      });
+      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()
+        });
+      }
+      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) {
+  installChildUnhandledRejectionGuard();
+  const inboundBySession = new SessionSerialQueue();
+  inboundQueueAuthority = inboundBySession;
+  const agentStartReady = runAgentStartHook(handlers);
+  process.on("message", (message) => {
+    if (!isParentMessage(message))
+      return;
+    if (message.type === "session_end") {
+      endedSessionIds.add(message.sessionId);
+      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 });
+}
+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/agent.ts
+var peers = /* @__PURE__ */ new Map();
+function peerState(sessionId) {
+  let state = peers.get(sessionId);
+  if (!state) {
+    state = {
+      userSpeaking: false,
+      agentSpeaking: false,
+      lastPartial: "",
+      sttActive: false
+    };
+    peers.set(sessionId, state);
+  }
+  return state;
+}
+function formatSpeechDetail(speech) {
+  if (speech.text) return `"${speech.text}"`;
+  if (speech.error) return speech.error;
+  return "";
+}
+function handleSpeechEvent(sessionId, speech) {
+  const state = peerState(sessionId);
+  const detail = formatSpeechDetail(speech);
+  switch (speech.type) {
+    // --- User turn (VAD + STT) ---
+    case "user_speaking_start":
+      state.userSpeaking = true;
+      agentLog("info", `[${sessionId}] user_speaking_start`);
+      break;
+    case "user_speaking_end":
+      state.userSpeaking = false;
+      agentLog("info", `[${sessionId}] user_speaking_end`);
+      break;
+    case "vad_triggered":
+      agentLog(
+        "info",
+        `[${sessionId}] vad_triggered \u2014 STT listen window opened`
+      );
+      break;
+    case "stt_stream_start":
+      agentLog("info", `[${sessionId}] stt_stream_start`);
+      break;
+    case "stt_stream_end":
+      agentLog("info", `[${sessionId}] stt_stream_end`);
+      break;
+    case "user_stt_start":
+      state.sttActive = true;
+      state.lastPartial = "";
+      agentLog("info", `[${sessionId}] user_stt_start`);
+      break;
+    case "user_stt_end":
+      state.sttActive = false;
+      agentLog("info", `[${sessionId}] user_stt_end`);
+      break;
+    case "user_stt_not_found":
+      agentLog(
+        "info",
+        `[${sessionId}] user_stt_not_found \u2014 no speech recognized in listen window`
+      );
+      break;
+    case "user_speech_partial":
+      state.lastPartial = speech.text ?? "";
+      agentLog("info", `[${sessionId}] user_speech_partial ${detail}`);
+      break;
+    case "user_speech_final":
+      state.lastPartial = "";
+      agentLog("info", `[${sessionId}] user_speech_final ${detail}`);
+      break;
+    // --- Agent playback (TTS) ---
+    case "agent_speaking_start":
+      state.agentSpeaking = true;
+      agentLog("info", `[${sessionId}] agent_speaking_start`);
+      break;
+    case "agent_speaking_end":
+      state.agentSpeaking = false;
+      agentLog("info", `[${sessionId}] agent_speaking_end`);
+      break;
+    case "barge_in":
+      agentLog(
+        "info",
+        `[${sessionId}] barge_in \u2014 user interrupted agent playback`
+      );
+      break;
+    case "error":
+      agentLog(
+        "error",
+        `[${sessionId}] pipeline error: ${speech.error ?? "unknown"}`
+      );
+      break;
+    default: {
+      const _exhaustive = speech.type;
+      agentLog(
+        "error",
+        `[${sessionId}] unhandled speech event: ${String(_exhaustive)}`
+      );
+    }
+  }
+}
+defineAgent({
+  onSessionStart({ sessionId, env }) {
+    agentLog("info", `session_start ${sessionId} env=${JSON.stringify(env)}`);
+    speak(sessionId, "Hello! How can I help?");
+  },
+  onSpeechEvent({ sessionId }, speech) {
+    handleSpeechEvent(sessionId, speech);
+  },
+  onUserSpeechFinal({ sessionId, text }) {
+    speak(sessionId, `You said: ${text}`);
+  },
+  onSessionEnd({ sessionId }) {
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voicethere/agent",
-  "version": "0.2.16",
+  "version": "0.3.0",
   "description": "VoiceThere customer agent SDK — IPC types and runtime helpers for sandboxed child bundles",
   "type": "module",
   "exports": {
@@ -21,6 +21,18 @@
       "import": "./dist/verify/run-verify.js",
       "require": "./dist/verify/run-verify.js",
       "default": "./dist/verify/run-verify.js"
+    },
+    "./templates": {
+      "types": "./dist/templates/index.d.ts",
+      "import": "./dist/templates/index.js",
+      "require": "./dist/templates/index.js",
+      "default": "./dist/templates/index.js"
+    },
+    "./templates/redis-sync/world-layout": {
+      "types": "./templates/redis-sync/world-layout.ts",
+      "import": "./templates/redis-sync/world-layout.ts",
+      "require": "./templates/redis-sync/world-layout.ts",
+      "default": "./templates/redis-sync/world-layout.ts"
     }
   },
   "bin": "./dist/cli.js",
@@ -32,8 +44,9 @@
   ],
   "scripts": {
     "build:lib": "tsc -p tsconfig.json && mkdir -p dist/sandbox && cp src/sandbox/loader-entry.js dist/sandbox/",
+    "build:templates": "node dist/templates/build-seed-bundles-cli.js",
     "build:example": "node dist/cli.js build --entry examples/agent.ts --outfile dist/agent.js",
-    "build": "npm run build:lib && npm run build:example",
+    "build": "npm run build:lib && npm run build:templates && npm run build:example",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
     "test:ci": "npm run typecheck && npm run build && npm run test && node scripts/ci/verify-package-exports.mjs",
@@ -75,9 +88,9 @@
     "@node-webrtc-rust/sdk": ">=0.6.5"
   },
   "devDependencies": {
-    "@node-webrtc-rust/helpers": "^0.6.24",
-    "@node-webrtc-rust/sdk": "0.6.24",
-    "@node-webrtc-rust/signaling": "0.6.24",
+    "@node-webrtc-rust/helpers": "^0.7.0",
+    "@node-webrtc-rust/sdk": "0.7.0",
+    "@node-webrtc-rust/signaling": "0.7.0",
     "@types/node": "^22.10.0",
     "http-server": "^14.1.1",
     "ioredis": "^5.11.1",