@voicethere/agent 0.4.0 → 0.5.0

package/dist/templates/webhooks/agent.js

@@ -0,0 +1,674 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+
+
+// templates/webhooks.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// 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 isRecordingControlAckMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "recording_control_ack" && typeof msg.requestId === "string";
+}
+function isWebhookMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "webhook" && typeof msg.eventId === "string" && typeof msg.projectId === "string";
+}
+function coerceInboundBinary(value) {
+  if (!value)
+    return null;
+  if (Buffer.isBuffer(value))
+    return value;
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (value instanceof ArrayBuffer)
+    return Buffer.from(value);
+  if (ArrayBuffer.isView(value)) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  if (typeof value === "object") {
+    const maybeBufferLike = value;
+    if (maybeBufferLike.type === "Buffer" && Array.isArray(maybeBufferLike.data)) {
+      return Buffer.from(maybeBufferLike.data);
+    }
+  }
+  return null;
+}
+function normalizeWebhookHeaders(value) {
+  if (!value || typeof value !== "object")
+    return {};
+  const out = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw === "string") {
+      out[key] = raw;
+    }
+  }
+  return out;
+}
+function isParentMessage(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const msg = value;
+  return msg.type === "session_start" || msg.type === "speech_event" || msg.type === "session_end" || msg.type === "data_channel_message" || msg.type === "data_channel_binary" || msg.type === "idle_timeout" || msg.type === "recording_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 endedSessionIds = /* @__PURE__ */ new Set();
+var pendingRecordingAcks = /* @__PURE__ */ new Map();
+function handleRecordingControlAck(message) {
+  const pending = pendingRecordingAcks.get(message.requestId);
+  if (!pending)
+    return;
+  clearTimeout(pending.timer);
+  pendingRecordingAcks.delete(message.requestId);
+  pending.resolve({
+    ok: message.ok,
+    reason: message.reason,
+    requestId: message.requestId
+  });
+}
+function clearPendingRecordingAcksForSession(sessionId, reason) {
+  for (const [requestId, pending] of pendingRecordingAcks) {
+    if (pending.sessionId !== sessionId)
+      continue;
+    clearTimeout(pending.timer);
+    pendingRecordingAcks.delete(requestId);
+    pending.resolve({ ok: false, reason, requestId });
+  }
+}
+var sessionExecutionContext = new AsyncLocalStorage();
+var agentLogSessionContext = new AsyncLocalStorage();
+var inboundQueueAuthority = null;
+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 handleWebhookMessage(message, handlers) {
+  if (!handlers.onWebhook)
+    return;
+  const body = coerceInboundBinary(message.body);
+  if (!body) {
+    agentLog("warn", "webhook ipc dropped: body is not binary");
+    return;
+  }
+  const ctx = {
+    eventId: message.eventId,
+    projectId: message.projectId,
+    method: typeof message.method === "string" ? message.method : "POST",
+    path: typeof message.path === "string" ? message.path : "",
+    headers: normalizeWebhookHeaders(message.headers),
+    body,
+    contentType: typeof message.contentType === "string" ? message.contentType : null,
+    receivedAt: typeof message.receivedAt === "string" ? message.receivedAt : ""
+  };
+  try {
+    const started = Date.now();
+    await handlers.onWebhook(ctx);
+    sendParentMessage({
+      type: "webhook_handled",
+      projectId: message.projectId,
+      eventId: message.eventId,
+      durationMs: Date.now() - started
+    });
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    await runErrorHook(handlers, {
+      sessionId: "",
+      projectId: message.projectId,
+      env: process.env,
+      error: err
+    });
+    sendParentMessage({
+      type: "agent_error",
+      sessionId: "",
+      message: err.message,
+      stack: err.stack
+    });
+  }
+}
+async function handleParentMessage(message, handlers) {
+  switch (message.type) {
+    case "session_start":
+      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,
+        recordingAvailable: message.recordingAvailable ?? 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()
+        });
+      }
+      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);
+      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 (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 sendToClient(sessionId, payload) {
+  sendParentMessage({ type: "send_to_client", sessionId, payload });
+}
+function broadcastToClients(payload, sessionIds) {
+  for (const sessionId of sessionIds) {
+    sendToClient(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/webhooks.ts
+var WEBHOOK_SIGNATURE_HEADER = "x-agent-webhook-signature";
+var connectedSessions = /* @__PURE__ */ new Set();
+function verifyWebhookSignature(body, headers, secret) {
+  const received = headers[WEBHOOK_SIGNATURE_HEADER] ?? headers[WEBHOOK_SIGNATURE_HEADER.toUpperCase()];
+  if (!received?.trim()) {
+    return false;
+  }
+  const expected = createHmac("sha256", secret).update(body).digest("hex");
+  try {
+    const actual = Buffer.from(received.trim(), "hex");
+    const want = Buffer.from(expected, "hex");
+    return actual.length === want.length && timingSafeEqual(actual, want);
+  } catch {
+    return false;
+  }
+}
+defineAgent({
+  onSessionStart({ sessionId }) {
+    connectedSessions.add(sessionId);
+  },
+  onSessionEnd({ sessionId }) {
+    connectedSessions.delete(sessionId);
+  },
+  async onWebhook(ctx) {
+    const secret = process.env.AGENT_WEBHOOK_SIGNING_SECRET?.trim();
+    if (!secret) {
+      agentLog("warn", "webhook ignored: AGENT_WEBHOOK_SIGNING_SECRET unset");
+      return;
+    }
+    if (!verifyWebhookSignature(ctx.body, ctx.headers, secret)) {
+      agentLog("warn", `webhook signature invalid eventId=${ctx.eventId}`);
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(ctx.body.toString("utf8"));
+    } catch {
+      agentLog("warn", `webhook body is not JSON eventId=${ctx.eventId}`);
+      return;
+    }
+    const record = payload && typeof payload === "object" ? payload : null;
+    const messageType = record?.type ?? "webhook";
+    const text = typeof record?.text === "string" && record.text.trim() ? record.text.trim() : `webhook:${messageType}`;
+    const sessionIds = [...connectedSessions];
+    if (sessionIds.length === 0) {
+      agentLog("info", `webhook verified with no live sessions eventId=${ctx.eventId}`);
+      return;
+    }
+    broadcastToClients(
+      {
+        type: "webhook_event",
+        eventId: ctx.eventId,
+        path: ctx.path,
+        payload
+      },
+      sessionIds
+    );
+    for (const sessionId of sessionIds) {
+      speak(sessionId, text);
+    }
+    agentLog(
+      "info",
+      `webhook delivered to ${sessionIds.length} session(s) eventId=${ctx.eventId}`
+    );
+  }
+});