@voicethere/agent 0.2.16 → 0.3.0

package/templates/README.md

@@ -1,66 +1,79 @@
 # Agent templates
 
-## `echo.ts`
+`@voicethere/agent` is the single source of truth for starter templates. Import the registry from `@voicethere/agent/templates`:
+
+```typescript
+import {
+  listTemplates,
+  getTemplate,
+  resolveTemplateEntryPath,
+  loadTemplateSources,
+  loadTemplateBundle,
+  hasSeedBundle,
+} from "@voicethere/agent/templates";
+```
 
-Full echo debug agent for the VoiceThere dashboard — speaks **"you said: …"** on voice finals and text chat, relays speech events over DataChannel, and echoes chat replies on DC.
+## Product vs e2e
+
+| Kind | Dashboard create | Prebuilt seed bundle | Typical consumer |
+| --- | --- | --- | --- |
+| **product** | Yes (`echo`, `echo-dc`, `voice-starter`, `game-sync`) | Yes — `dist/templates/<id>/agent.js` | Platform project create |
+| **e2e** | No | No — build from sources at test time | `voicethere/e2e` smokes |
+
+Product templates always set `seedOnCreate: true`. CI fails if a product template is missing its prebuilt bundle after `npm run build`.
 
-**Build:**
+## Sources vs prebuilt
+
+- **Sources** live under `templates/` in the published package (editable TypeScript).
+- **Prebuilt** bundles are derived artifacts at `dist/templates/<id>/agent.js` for product templates only.
+- `loadTemplateSources(id)` returns `{ path, content }[]` — the canonical tree for a future web editor.
+- `loadTemplateBundle(id)` returns prebuilt bytes for platform seed/deploy (runner-ready `agent.js`).
+
+Build a template locally:
 
 ```bash
-npm install @voicethere/agent
-npx @voicethere/agent build --entry templates/echo.ts
+npx @voicethere/agent build --entry templates/echo.ts --outfile dist/agent.js
 ```
 
-Platform auto-seeds the built bundle when a project is created with the **Echo (voice + chat)** template.
+Prebuild all product seed bundles (also runs in `npm run build`):
 
-## `echo-dc.ts`
+```bash
+npm run build:templates
+```
 
-Data-channel-only echo — relays speech events and chat text over DC without TTS. Use when debugging the dashboard chat panel without agent playback.
+## Product templates
 
-## `agent.ts`
+### `echo.ts` (`echo`)
 
-Full starter bundle covering every speech event from `@node-webrtc-rust/sdk/voice`:
+Full echo debug agent for the VoiceThere dashboard — speaks **"you said: …"** on voice finals and text chat, relays speech events over DataChannel, and echoes chat replies on DC.
 
-| Group       | Events                                                                                       |
-| ----------- | -------------------------------------------------------------------------------------------- |
-| User VAD    | `user_speaking_start`, `user_speaking_end`, `vad_triggered`                                  |
-| STT stream  | `stt_stream_start`, `stt_stream_end`, `user_stt_start`, `user_stt_end`, `user_stt_not_found` |
-| Transcripts | `user_speech_partial`, `user_speech_final`                                                   |
-| Agent TTS   | `agent_speaking_start`, `agent_speaking_end`, `barge_in`                                     |
-| Failures    | `error`                                                                                      |
+### `echo-dc.ts` (`echo-dc`)
 
-**Customize:** replace `onUserSpeechFinal` body with your LLM/tools; extend `PeerState` or swap `handleSpeechEvent` for your architecture.
+Data-channel-only echo — relays speech events and chat text over DC without TTS.
 
-**Build:**
+### `agent.ts` (`voice-starter`)
 
-```bash
-npm install @voicethere/agent
-npx @voicethere/agent build
-# optional: --entry agent.ts --outfile dist/agent.js
-```
+Full starter bundle covering every speech event from `@node-webrtc-rust/sdk/voice`. Customize `onUserSpeechFinal` for your LLM/tools.
 
-**Verify sandbox (no WebRTC):**
+### `game-sync.ts` (`game-sync`)
 
-```bash
-npx @voicethere/agent verify
-```
+Authoritative multi-object sync sample for real-time games/simulations (register, simulate, binary world snapshots).
 
-**Voice E2E:** host with the VoiceThere agent runner (platform or internal deployment) — set `AGENT_BUNDLE_PATH` to your built `dist/agent.js`.
+## E2e templates
 
-## `game-sync.ts`
+These mirror former `e2e/fixtures/*` sources. E2E resolves entries from the package, builds into ephemeral workdirs, and uploads `dist/agent.js`.
 
-Authoritative multi-object sync sample for real-time games/simulations:
+| Id | Source | Purpose |
+| --- | --- | --- |
+| `echo-smoke` | `echo-smoke.ts` | voice-smoke, agent-smoke, cli-smoke |
+| `crash` | `crash.ts` | session-errors-smoke, crash-policy smokes |
+| `game-sync-smoke` | `game-sync-smoke.ts` | deploy-smoke, shared-child, idle smokes |
+| `redis-sync` | `redis-sync/agent.ts` + `world-layout.ts` | redis-sync-smoke (project Redis world buffer) |
 
-- register tracked objects via control DC (`{ type: "register" }`)
-- receive `register_ack` + `object_registered` ownership notifications
-- run server-authoritative simulation (position + velocity) at 60Hz
-- resolve wall bounce + object-object collisions on the server
-- broadcast world-state snapshots to clients over binary sync channel (9-float records)
-- ignore client binary writes by default (safe base for adding intent/input messages later)
-- reuse freed slots on leave to keep world state compact
+**Note:** Product `echo` is not the same as e2e `echo-smoke` — keep both ids.
 
-Build:
+## Verify sandbox (no WebRTC)
 
 ```bash
-npx @voicethere/agent build --entry templates/game-sync.ts
+npx @voicethere/agent verify
 ```

package/templates/crash.ts

@@ -0,0 +1,61 @@
+/**
+ * Crash / echo agent for session-errors-smoke and agent-crash-policy-*-smoke.
+ *
+ * Protocol:
+ * - `{ type: "crash_trigger" }` → throw (AGENT_HANDLER_FAILED)
+ * - `{ type: "crash_exit" }` → process.exit(1)
+ * - `{ type: "ping", id }` → `{ type: "pong", id }`
+ * - `onUserSpeechFinal` text starting with "crash" → throw
+ * - other finals → speak(`echo:${text}`)
+ * - onSessionStart → speak("ready") after 1s (voice ready waiter)
+ */
+import { defineAgent, sendToClient, speak } from "@voicethere/agent";
+
+export const CRASH_AGENT_MESSAGE =
+  "e2e crash-agent: intentional handler failure";
+
+function isRecord(message: unknown): message is Record<string, unknown> {
+  return !!message && typeof message === "object";
+}
+
+function isCrashTrigger(message: unknown): boolean {
+  return isRecord(message) && message.type === "crash_trigger";
+}
+
+function isCrashExit(message: unknown): boolean {
+  return isRecord(message) && message.type === "crash_exit";
+}
+
+function isPing(message: unknown): message is { type: "ping"; id: string } {
+  if (!isRecord(message) || message.type !== "ping") return false;
+  return typeof message.id === "string" && message.id.trim().length > 0;
+}
+
+defineAgent({
+  onSessionStart({ sessionId }) {
+    setTimeout(() => {
+      speak(sessionId, "ready");
+    }, 1000);
+  },
+
+  onUserSpeechFinal({ sessionId, text }) {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    if (/^crash\b/i.test(trimmed)) {
+      throw new Error(CRASH_AGENT_MESSAGE);
+    }
+    speak(sessionId, `echo:${trimmed}`);
+  },
+
+  onDataChannelMessage(ctx) {
+    if (isCrashTrigger(ctx.message)) {
+      throw new Error(CRASH_AGENT_MESSAGE);
+    }
+    if (isCrashExit(ctx.message)) {
+      process.exit(1);
+    }
+    if (isPing(ctx.message)) {
+      sendToClient(ctx.sessionId, { type: "pong", id: ctx.message.id });
+    }
+  },
+});

package/templates/echo-smoke.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal echo agent for e2e voice-smoke, agent-smoke, and cli-smoke uploads.
+ *
+ * Echoes voice finals and DataChannel chat via speak() → TTS (client sees agent_speaking_* speech_events).
+ */
+import { defineAgent, parseChatText, speak } from "@voicethere/agent";
+
+defineAgent({
+  onSessionStart({ sessionId }) {
+    setTimeout(() => {
+      speak(sessionId, "ready");
+    }, 1000);
+  },
+
+  onUserSpeechFinal({ sessionId, text }) {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    speak(sessionId, `echo:${trimmed}`);
+  },
+
+  onDataChannelMessage(ctx) {
+    const text = parseChatText(ctx.message);
+    if (!text?.trim()) return;
+    if (text.trim().toLowerCase() === "ping") return;
+    speak(ctx.sessionId, `echo:${text.trim()}`);
+  },
+});

package/templates/game-sync-smoke.ts

@@ -0,0 +1,81 @@
+/**
+ * Minimal data-channel agent for staging smokes (data-only / shared-child / idle).
+ *
+ * Protocol:
+ * - On join/leave: broadcast `{ type: "state", tick, players }` to every session.
+ * - On `{ type: "tick" }`: increment tick and rebroadcast.
+ * - On `{ type: "agent_log_probe", id }`: `agentLog` the id (agent-logs-smoke) and ack.
+ *
+ * Load-staging uses the full `game-sync` product template (object-sync).
+ */
+import { agentLog, defineAgent, sendToClient } from "@voicethere/agent";
+
+/** E2E deploy-smoke — rewritten before each fixture upload. */
+export const FIXTURE_MARKER = "deploy-smoke-fixture-b";
+
+const connectedSessions = new Set<string>();
+let tick = 0;
+
+function broadcastState(): void {
+  const players = connectedSessions.size;
+  for (const sessionId of connectedSessions) {
+    sendToClient(sessionId, {
+      type: "state",
+      tick,
+      players,
+      marker: FIXTURE_MARKER,
+    });
+  }
+}
+
+function isTickMessage(message: unknown): boolean {
+  return (
+    !!message &&
+    typeof message === "object" &&
+    (message as { type?: unknown }).type === "tick"
+  );
+}
+
+function isAgentLogProbe(
+  message: unknown,
+): message is { type: "agent_log_probe"; id: string } {
+  if (!message || typeof message !== "object") return false;
+  const record = message as { type?: unknown; id?: unknown };
+  return (
+    record.type === "agent_log_probe" &&
+    typeof record.id === "string" &&
+    record.id.trim().length > 0
+  );
+}
+
+defineAgent({
+  onClientJoin({ sessionId }) {
+    connectedSessions.add(sessionId);
+    broadcastState();
+  },
+
+  onClientLeave({ sessionId }) {
+    connectedSessions.delete(sessionId);
+    broadcastState();
+  },
+
+  onDataChannelMessage(ctx) {
+    if (isAgentLogProbe(ctx.message)) {
+      const id = ctx.message.id.trim();
+      agentLog(
+        "info",
+        `agent-logs-e2e probe ${id}`,
+        { probeId: id, e2e: "agent-logs-smoke" },
+        ctx.sessionId,
+      );
+      sendToClient(ctx.sessionId, { type: "agent_log_probe_ack", id });
+      return;
+    }
+
+    if (!isTickMessage(ctx.message)) {
+      return;
+    }
+    tick += 1;
+    broadcastState();
+  },
+});

package/templates/redis-sync/agent.ts

@@ -0,0 +1,255 @@
+/**
+ * Redis-backed world buffer sync for redis-sync-smoke (Advanced tier + project Redis).
+ *
+ * Game-style layout: one Float32Array world blob in Redis (`e2e:redis-sync:world`).
+ * Each client owns a fixed slot and publishes `{ type: "position", clientIndex, x, y }`.
+ * Each runner pod runs its own broadcast loop: one Redis GET per tick, then binary
+ * fan-out on voicethere-sync to all local sessions (no pub/sub). Clients patch
+ * out of sync; the 20Hz server tick is the authoritative sync path.
+ *
+ * Slot writes use a Lua read-modify-write so concurrent patches from many sessions
+ * cannot clobber each other (WATCH/MULTI lost slots under 30-way connect storms).
+ *
+ * Build:
+ *   npx @voicethere/agent build --entry templates/redis-sync/agent.ts --outfile dist/agent.js
+ */
+import Redis from "ioredis";
+import { agentLog, defineAgent, sendBinaryToClient } from "@voicethere/agent";
+
+import {
+  createEmptyWorldBuffer,
+  normalizeWorldBuffer,
+  peerSlotOffset,
+  PEER_SLOT_BYTE_LENGTH,
+  REDIS_WORLD_KEY,
+  WORLD_BYTE_LENGTH,
+  writePeerSlot,
+} from "./world-layout.js";
+
+/** Atomic splice of one peer slot (16 bytes) into the world blob. */
+const LUA_PATCH_PEER_SLOT = `
+local key = KEYS[1]
+local offset = tonumber(ARGV[1])
+local slot = ARGV[2]
+local size = tonumber(ARGV[3])
+local world = redis.call('GET', key)
+if not world then
+  world = string.rep(string.char(0), size)
+elseif #world < size then
+  world = world .. string.rep(string.char(0), size - #world)
+elseif #world > size then
+  world = string.sub(world, 1, size)
+end
+world = string.sub(world, 1, offset) .. slot .. string.sub(world, offset + #slot + 1)
+redis.call('SET', key, world)
+return size
+`;
+
+const WORLD_BROADCAST_HZ = 20;
+const WORLD_BROADCAST_INTERVAL_MS = Math.floor(1000 / WORLD_BROADCAST_HZ);
+
+const connectedSessions = new Set<string>();
+const sessionClientIndex = new Map<string, number>();
+let localWorld = createEmptyWorldBuffer();
+let redis: Redis | null = null;
+let broadcastTimer: NodeJS.Timeout | null = null;
+
+function parsePositionMessage(
+  message: unknown,
+): { clientIndex: number; x: number; y: number } | null {
+  if (!message || typeof message !== "object") {
+    return null;
+  }
+  const record = message as {
+    type?: unknown;
+    clientIndex?: unknown;
+    x?: unknown;
+    y?: unknown;
+  };
+  if (record.type !== "position") {
+    return null;
+  }
+  if (
+    typeof record.clientIndex !== "number" ||
+    !Number.isFinite(record.clientIndex) ||
+    record.clientIndex < 0
+  ) {
+    return null;
+  }
+  if (typeof record.x !== "number" || !Number.isFinite(record.x)) {
+    return null;
+  }
+  if (typeof record.y !== "number" || !Number.isFinite(record.y)) {
+    return null;
+  }
+  return {
+    clientIndex: record.clientIndex,
+    x: record.x,
+    y: record.y,
+  };
+}
+
+function copyWorldBuffer(world: Float32Array): Buffer {
+  return Buffer.from(world.buffer, world.byteOffset, world.byteLength);
+}
+
+function encodePeerSlot(
+  clientIndex: number,
+  x: number,
+  y: number,
+  active: number,
+): Buffer {
+  const floats = new Float32Array([clientIndex, x, y, active]);
+  return Buffer.from(floats.buffer, floats.byteOffset, floats.byteLength);
+}
+
+function broadcastWorldBuffer(
+  world: Float32Array,
+  targetSessionId?: string,
+): void {
+  const payload = copyWorldBuffer(world);
+  if (targetSessionId) {
+    try {
+      sendBinaryToClient(targetSessionId, payload, "sync");
+    } catch (error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      agentLog(
+        "error",
+        `world send failed session=${targetSessionId}: ${detail}`,
+      );
+    }
+    return;
+  }
+  for (const sessionId of connectedSessions) {
+    try {
+      sendBinaryToClient(sessionId, payload, "sync");
+    } catch (error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      agentLog("error", `world send failed session=${sessionId}: ${detail}`);
+    }
+  }
+}
+
+async function loadWorldFromRedis(): Promise<Float32Array> {
+  if (!redis) {
+    return new Float32Array(localWorld);
+  }
+  const raw = await redis.getBuffer(REDIS_WORLD_KEY);
+  return normalizeWorldBuffer(raw);
+}
+
+async function broadcastWorldFromRedis(
+  targetSessionId?: string,
+): Promise<void> {
+  const world = await loadWorldFromRedis();
+  broadcastWorldBuffer(world, targetSessionId);
+}
+
+function startBroadcastLoopIfNeeded(): void {
+  if (broadcastTimer || connectedSessions.size === 0) {
+    return;
+  }
+  broadcastTimer = setInterval(() => {
+    void broadcastWorldFromRedis().catch((error: unknown) => {
+      const detail = error instanceof Error ? error.message : String(error);
+      agentLog("error", `world broadcast failed: ${detail}`);
+    });
+  }, WORLD_BROADCAST_INTERVAL_MS);
+  agentLog("info", `world loop started (${WORLD_BROADCAST_HZ}Hz)`);
+}
+
+function stopBroadcastLoopIfNeeded(): void {
+  if (connectedSessions.size > 0 || !broadcastTimer) {
+    return;
+  }
+  clearInterval(broadcastTimer);
+  broadcastTimer = null;
+  agentLog("info", "world loop stopped");
+}
+
+async function patchWorldSlot(
+  clientIndex: number,
+  x: number,
+  y: number,
+  active: number,
+): Promise<void> {
+  if (!redis) {
+    writePeerSlot(localWorld, clientIndex, x, y, active);
+    return;
+  }
+
+  const byteOffset = peerSlotOffset(clientIndex) * 4;
+  const slot = encodePeerSlot(clientIndex, x, y, active);
+  if (slot.byteLength !== PEER_SLOT_BYTE_LENGTH) {
+    throw new Error(
+      `peer slot encode length ${slot.byteLength} != ${PEER_SLOT_BYTE_LENGTH}`,
+    );
+  }
+  await redis.eval(
+    LUA_PATCH_PEER_SLOT,
+    1,
+    REDIS_WORLD_KEY,
+    String(byteOffset),
+    slot,
+    String(WORLD_BYTE_LENGTH),
+  );
+}
+
+defineAgent({
+  async onAgentStart({ env }) {
+    const redisUrl = env.AGENT_REDIS_URL ?? process.env.AGENT_REDIS_URL;
+    if (!redisUrl?.trim()) {
+      agentLog(
+        "warn",
+        "AGENT_REDIS_URL unset — redis-sync fixture falls back to per-pod memory only",
+      );
+      return;
+    }
+
+    redis = new Redis(redisUrl, {
+      maxRetriesPerRequest: 3,
+      lazyConnect: true,
+    });
+    await redis.connect();
+    agentLog(
+      "info",
+      "redis-sync agent connected to project Redis world buffer",
+    );
+  },
+
+  async onClientJoin({ sessionId }) {
+    connectedSessions.add(sessionId);
+    startBroadcastLoopIfNeeded();
+    await broadcastWorldFromRedis(sessionId);
+  },
+
+  async onClientLeave({ sessionId }) {
+    connectedSessions.delete(sessionId);
+    const clientIndex = sessionClientIndex.get(sessionId);
+    sessionClientIndex.delete(sessionId);
+    stopBroadcastLoopIfNeeded();
+    if (clientIndex === undefined) {
+      return;
+    }
+    try {
+      await patchWorldSlot(clientIndex, 0, 0, 0);
+    } catch (error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      agentLog("error", `world leave patch failed: ${detail}`);
+    }
+  },
+
+  async onDataChannelMessage(ctx) {
+    const position = parsePositionMessage(ctx.message);
+    if (!position) {
+      return;
+    }
+    sessionClientIndex.set(ctx.sessionId, position.clientIndex);
+    try {
+      await patchWorldSlot(position.clientIndex, position.x, position.y, 1);
+    } catch (error: unknown) {
+      const detail = error instanceof Error ? error.message : String(error);
+      agentLog("error", `world position patch failed: ${detail}`);
+    }
+  },
+});

package/templates/redis-sync/world-layout.ts

@@ -0,0 +1,118 @@
+/**
+ * Shared world buffer layout for redis-sync template (agent + E2E helpers).
+ *
+ * One Float32Array backs the full multiplayer state in Redis:
+ *   peer slot = clientIndex * PEER_STRIDE
+ *   [clientIndex, x, y, active]
+ *
+ * active: 1 = present, 0 = left / empty slot
+ */
+export const MAX_PEERS = 128;
+export const PEER_STRIDE = 4;
+export const WORLD_FLOAT_COUNT = MAX_PEERS * PEER_STRIDE;
+export const WORLD_BYTE_LENGTH = WORLD_FLOAT_COUNT * 4;
+export const PEER_SLOT_BYTE_LENGTH = PEER_STRIDE * 4;
+
+export const PEER_FIELD_INDEX = 0;
+export const PEER_FIELD_X = 1;
+export const PEER_FIELD_Y = 2;
+export const PEER_FIELD_ACTIVE = 3;
+
+export const REDIS_WORLD_KEY = "e2e:redis-sync:world";
+
+export type PeerSlot = {
+  clientIndex: number;
+  x: number;
+  y: number;
+  active: number;
+};
+
+export function peerSlotOffset(clientIndex: number): number {
+  return clientIndex * PEER_STRIDE;
+}
+
+export function createEmptyWorldBuffer(): Float32Array {
+  return new Float32Array(WORLD_FLOAT_COUNT);
+}
+
+export function writePeerSlot(
+  world: Float32Array,
+  clientIndex: number,
+  x: number,
+  y: number,
+  active: number,
+): void {
+  const offset = peerSlotOffset(clientIndex);
+  world[offset + PEER_FIELD_INDEX] = clientIndex;
+  world[offset + PEER_FIELD_X] = x;
+  world[offset + PEER_FIELD_Y] = y;
+  world[offset + PEER_FIELD_ACTIVE] = active;
+}
+
+export function clearPeerSlot(world: Float32Array, clientIndex: number): void {
+  writePeerSlot(world, clientIndex, 0, 0, 0);
+}
+
+export function readPeerSlot(
+  world: Float32Array,
+  clientIndex: number,
+): PeerSlot | null {
+  const offset = peerSlotOffset(clientIndex);
+  const active = world[offset + PEER_FIELD_ACTIVE];
+  if (active !== 1) {
+    return null;
+  }
+  return {
+    clientIndex: world[offset + PEER_FIELD_INDEX],
+    x: world[offset + PEER_FIELD_X],
+    y: world[offset + PEER_FIELD_Y],
+    active,
+  };
+}
+
+/**
+ * Decode a Redis / Node Buffer (or any Uint8Array) into a world Float32Array.
+ *
+ * Node Buffer pools often hand out views whose `byteOffset` is not a multiple of
+ * 4. `new Float32Array(buf.buffer, buf.byteOffset, …)` then throws:
+ *   "start offset of Float32Array should be a multiple of 4"
+ * Copy via `ArrayBuffer.slice` so the view always starts at offset 0.
+ */
+export function normalizeWorldBuffer(
+  raw: Uint8Array | null | undefined,
+): Float32Array {
+  if (!raw || raw.byteLength === 0) {
+    return createEmptyWorldBuffer();
+  }
+  const bytes = Math.floor(raw.byteLength / 4) * 4;
+  if (bytes === 0) {
+    return createEmptyWorldBuffer();
+  }
+  const aligned = raw.buffer.slice(raw.byteOffset, raw.byteOffset + bytes);
+  const decoded = new Float32Array(aligned);
+  if (decoded.length === WORLD_FLOAT_COUNT) {
+    return decoded;
+  }
+  const normalized = createEmptyWorldBuffer();
+  normalized.set(
+    decoded.subarray(0, Math.min(decoded.length, WORLD_FLOAT_COUNT)),
+  );
+  return normalized;
+}
+
+export function decodeWorldBuffer(data: ArrayBuffer): Float32Array {
+  const view = new Float32Array(data);
+  if (view.length === WORLD_FLOAT_COUNT) {
+    return view;
+  }
+  const normalized = createEmptyWorldBuffer();
+  normalized.set(view.subarray(0, Math.min(view.length, WORLD_FLOAT_COUNT)));
+  return normalized;
+}
+
+export function worldBufferToArrayBuffer(world: Float32Array): ArrayBuffer {
+  return world.buffer.slice(
+    world.byteOffset,
+    world.byteOffset + world.byteLength,
+  ) as ArrayBuffer;
+}