@voicethere/agent 0.7.13 → 0.8.0

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

@@ -18,8 +18,37 @@ export const PEER_FIELD_X = 1;
 export const PEER_FIELD_Y = 2;
 export const PEER_FIELD_ACTIVE = 3;
 
+/** Client → agent position frame: float32le [clientIndex, x, y] (12 bytes). */
+export const POSITION_FLOAT_COUNT = 3;
+export const POSITION_BYTE_LENGTH = POSITION_FLOAT_COUNT * 4;
+
+export type PeerPosition = {
+  clientIndex: number;
+  x: number;
+  y: number;
+};
+
 export const REDIS_WORLD_KEY = "e2e:redis-sync:world";
 
+/** Atomic splice of one peer slot (16 bytes) into the world blob. */
+export 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
+`;
+
 export type PeerSlot = {
   clientIndex: number;
   x: number;
@@ -53,6 +82,51 @@ export function clearPeerSlot(world: Float32Array, clientIndex: number): void {
   writePeerSlot(world, clientIndex, 0, 0, 0);
 }
 
+function asDataView(data: ArrayBufferLike | ArrayBufferView): DataView {
+  if (ArrayBuffer.isView(data)) {
+    return new DataView(data.buffer, data.byteOffset, data.byteLength);
+  }
+  return new DataView(data);
+}
+
+/** Decode a 12-byte inbound position frame. */
+export function decodePositionBuffer(
+  data: ArrayBufferLike | ArrayBufferView | null | undefined,
+): PeerPosition | null {
+  if (data == null) {
+    return null;
+  }
+  const view = asDataView(data);
+  if (view.byteLength < POSITION_BYTE_LENGTH) {
+    return null;
+  }
+  const clientIndex = view.getFloat32(0, true);
+  const x = view.getFloat32(4, true);
+  const y = view.getFloat32(8, true);
+  if (
+    !Number.isFinite(clientIndex) ||
+    clientIndex < 0 ||
+    !Number.isFinite(x) ||
+    !Number.isFinite(y)
+  ) {
+    return null;
+  }
+  return { clientIndex: Math.trunc(clientIndex), x, y };
+}
+
+/** Write [clientIndex, x, y] into `dest` (length >= 3) and return it. */
+export function encodePositionInto(
+  dest: Float32Array,
+  clientIndex: number,
+  x: number,
+  y: number,
+): Float32Array {
+  dest[0] = clientIndex;
+  dest[1] = x;
+  dest[2] = y;
+  return dest;
+}
+
 export function readPeerSlot(
   world: Float32Array,
   clientIndex: number,
@@ -71,46 +145,49 @@ export function readPeerSlot(
 }
 
 /**
- * Decode a Redis / Node Buffer (or any Uint8Array) into a world Float32Array.
+ * Copy Redis / Node Buffer bytes into `dest` (default: a new world).
  *
- * 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.
+ * Node Buffer pools can have `byteOffset` not divisible by 4, so we copy via
+ * a Uint8Array view onto `dest` instead of slicing a new ArrayBuffer.
  */
 export function normalizeWorldBuffer(
   raw: Uint8Array | null | undefined,
+  dest: Float32Array = createEmptyWorldBuffer(),
 ): Float32Array {
+  const destBytes = new Uint8Array(
+    dest.buffer,
+    dest.byteOffset,
+    dest.byteLength,
+  );
   if (!raw || raw.byteLength === 0) {
-    return createEmptyWorldBuffer();
+    destBytes.fill(0);
+    return dest;
   }
-  const bytes = Math.floor(raw.byteLength / 4) * 4;
-  if (bytes === 0) {
-    return createEmptyWorldBuffer();
+  const byteCount = Math.min(
+    Math.floor(raw.byteLength / 4) * 4,
+    destBytes.byteLength,
+  );
+  if (byteCount > 0) {
+    destBytes.set(raw.subarray(0, byteCount));
   }
-  const aligned = raw.buffer.slice(raw.byteOffset, raw.byteOffset + bytes);
-  const decoded = new Float32Array(aligned);
-  if (decoded.length === WORLD_FLOAT_COUNT) {
-    return decoded;
+  if (byteCount < destBytes.byteLength) {
+    destBytes.fill(0, byteCount);
   }
-  const normalized = createEmptyWorldBuffer();
-  normalized.set(
-    decoded.subarray(0, Math.min(decoded.length, WORLD_FLOAT_COUNT)),
-  );
-  return normalized;
+  return dest;
 }
 
-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 decodeWorldBuffer(
+  data: ArrayBuffer,
+  dest: Float32Array = createEmptyWorldBuffer(),
+): Float32Array {
+  return normalizeWorldBuffer(new Uint8Array(data), dest);
 }
 
+/** Same backing ArrayBuffer when the world is a standalone Float32Array. */
 export function worldBufferToArrayBuffer(world: Float32Array): ArrayBuffer {
+  if (world.byteOffset === 0 && world.byteLength === world.buffer.byteLength) {
+    return world.buffer as ArrayBuffer;
+  }
   return world.buffer.slice(
     world.byteOffset,
     world.byteOffset + world.byteLength,

package/templates/spatial-showcase/README.md

@@ -0,0 +1,13 @@
+# spatial-showcase
+
+Spatial audio showcase for `/showcase`. A `{ type: "join", demo }` DataChannel message selects `orbit`, `soundboard`, or `proximity`.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/spatial-showcase/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`, `protocol.ts`, `sounds.ts`, `room.ts`, `orbit.ts`, `orbit-session.ts`, `sine.ts`

package/templates/voice-showcase/README.md

@@ -0,0 +1,13 @@
+# voice-showcase
+
+Conversational voice demo for landing and dashboard previews — greeting, name, then a menu (weather, count, recipes, fun facts).
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/voice-showcase/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`, `conversation.ts`, `delivery.ts`, `weather.ts`, `recipes.ts`, `fun-facts.ts`

package/templates/voice-starter/README.md

@@ -0,0 +1,13 @@
+# voice-starter
+
+Starter bundle covering every speech event from `@node-webrtc-rust/sdk/voice`. Customize `onUserSpeechFinal` for your LLM or tools.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/voice-starter/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/webhooks/README.md

@@ -0,0 +1,13 @@
+# webhooks
+
+Inbound HTTP webhook sample — verifies `x-agent-webhook-signature` HMAC on the raw body, then fans out to connected sessions via DataChannel + `speak`.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/webhooks/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/{webhooks.ts → webhooks/agent.ts}

@@ -6,7 +6,7 @@
  * `AGENT_WEBHOOK_SIGNING_SECRET` **before** `JSON.parse`.
  *
  * Build:
- *   npx @voicethere/agent build --entry templates/webhooks.ts --outfile dist/agent.js
+ *   npx @voicethere/agent build --entry templates/webhooks/agent.ts --outfile dist/agent.js
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
 

package/templates/webhooks-redis/README.md

@@ -0,0 +1,13 @@
+# webhooks-redis
+
+Same HMAC verify path as `webhooks`, plus an atomic Redis counter (`AGENT_REDIS_URL`) before DataChannel fan-out.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/webhooks-redis/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/{webhooks-redis.ts → webhooks-redis/agent.ts}

@@ -8,22 +8,18 @@
  * before `JSON.parse`. Atomic counter uses Redis Lua (read-modify-write in one round trip).
  *
  * Build:
- *   npx @voicethere/agent build --entry templates/webhooks-redis.ts --outfile dist/agent.js
+ *   npx @voicethere/agent build --entry templates/webhooks-redis/agent.ts --outfile dist/agent.js
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 
-import {
-  agentLog,
-  broadcastToClients,
-  defineAgent,
-} from "@voicethere/agent";
+import { agentLog, broadcastToClients, defineAgent } from "@voicethere/agent";
 
 const WEBHOOK_SIGNATURE_HEADER = "x-agent-webhook-signature";
 const REDIS_COUNTER_KEY = "agent:webhook:event_count";
 
 /** Atomic increment — safe under concurrent webhook delivery on one pod. */
-const LUA_INCREMENT_COUNTER = `
+export const LUA_INCREMENT_COUNTER = `
 local key = KEYS[1]
 local n = redis.call('INCR', key)
 return n
@@ -114,7 +110,11 @@ defineAgent({
 
     let eventCount: number | null = null;
     if (redis) {
-      const result = await redis.eval(LUA_INCREMENT_COUNTER, 1, REDIS_COUNTER_KEY);
+      const result = await redis.eval(
+        LUA_INCREMENT_COUNTER,
+        1,
+        REDIS_COUNTER_KEY,
+      );
       eventCount = typeof result === "number" ? result : Number(result);
     }
 

package/templates/world-sync/README.md

@@ -0,0 +1,20 @@
+# world-sync
+
+Super-simple positional sync for a **data-only** project. One in-memory agent (no Redis) stores the latest `{ x, y, z }` per session and broadcasts a JSON world snapshot.
+
+Use this when you want `onDataChannelMessage` plus `sendToClient` and nothing else.
+
+## Protocol
+
+- **Inbound:** `{ "type": "pose", "x": 1, "y": 0, "z": -2 }` (or `{ "x", "y", "z" }`)
+- **Outbound:** `{ "type": "world", "poses": { "<sessionId>": { "x", "y", "z" } } }`
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/world-sync/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts` — `defineAgent` wiring and pose parse helper

package/templates/world-sync/agent.ts

@@ -0,0 +1,62 @@
+/**
+ * Super-simple world sync — one in-memory agent, JSON DataChannel messages, no Redis.
+ *
+ * Clients send `{ type: "pose", x, y, z }` (or `{ x, y, z }`) on the sync channel.
+ * The agent stores the latest pose per session and broadcasts
+ * `{ type: "world", poses }` to every connected peer.
+ *
+ * Build:
+ *   npx @voicethere/agent build --entry templates/world-sync/agent.ts --outfile dist/agent.js
+ */
+import { defineAgent, sendToClient } from "@voicethere/agent";
+
+export type Pose = { x: number; y: number; z: number };
+
+const poses = new Map<string, Pose>();
+
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+export function parsePoseMessage(message: unknown): Pose | null {
+  if (!message || typeof message !== "object") {
+    return null;
+  }
+  const record = message as { type?: unknown; x?: unknown; y?: unknown; z?: unknown };
+  if (record.type !== undefined && record.type !== "pose") {
+    return null;
+  }
+  if (!isFiniteNumber(record.x) || !isFiniteNumber(record.y) || !isFiniteNumber(record.z)) {
+    return null;
+  }
+  return { x: record.x, y: record.y, z: record.z };
+}
+
+function broadcastWorld(): void {
+  const payload = {
+    type: "world",
+    poses: Object.fromEntries(poses),
+  };
+  for (const sessionId of poses.keys()) {
+    sendToClient(sessionId, payload);
+  }
+}
+
+export default defineAgent({
+  onClientJoin({ sessionId }) {
+    poses.set(sessionId, { x: 0, y: 0, z: 0 });
+    broadcastWorld();
+  },
+
+  onClientLeave({ sessionId }) {
+    poses.delete(sessionId);
+    broadcastWorld();
+  },
+
+  onDataChannelMessage({ sessionId, message }) {
+    const pose = parsePoseMessage(message);
+    if (!pose) return;
+    poses.set(sessionId, pose);
+    broadcastWorld();
+  },
+});

package/templates/world-sync-binary/README.md

@@ -0,0 +1,21 @@
+# world-sync-binary
+
+Single-agent positional sync using **binary** DataChannel frames. No Redis.
+
+Clients send an `ArrayBuffer` of three little-endian float32 values `[x, y, z]`. Reuse one `Float32Array(3)` on the client. The agent stores xyz in one `Float32Array`, rewrites a single `WorldSnapshotBuffer` in place, and fans the resulting view out with `broadCastBinaryToClients` — one `Buffer` wrap per tick, zero byte copies.
+
+## Protocol
+
+- **Inbound (12 bytes):** `Float32Array([x, y, z]).buffer`
+- **Outbound snapshot:** `uint32le peerCount`, then per peer `uint16le idLength` + UTF-8 `sessionId` + `float32le x,y,z`
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/world-sync-binary/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts` — `onDataChannelBinary` + `broadCastBinaryToClients`
+- `protocol.ts` — encode/decode helpers; `WorldSnapshotBuffer` reuses one backing array

package/templates/world-sync-binary/agent.ts

@@ -0,0 +1,107 @@
+/**
+ * Single-agent binary world sync — no Redis.
+ *
+ * Clients send an ArrayBuffer of 3 float32 values `[x, y, z]` on the sync
+ * DataChannel. Poses live in one Float32Array; the outbound snapshot is one
+ * growable buffer rewritten in place and fanned out as a single Buffer view
+ * (no per-tick or per-peer copies).
+ *
+ * Build:
+ *   npx @voicethere/agent build --entry templates/world-sync-binary/agent.ts --outfile dist/agent.js
+ */
+import { broadCastBinaryToClients, defineAgent } from "@voicethere/agent";
+
+import {
+  decodePoseInto,
+  POSE_FLOAT_COUNT,
+  WorldSnapshotBuffer,
+} from "./protocol.js";
+
+const snapshot = new WorldSnapshotBuffer();
+const indexBySession = new Map<string, number>();
+const sessionIds: string[] = [];
+let xyz = new Float32Array(8 * POSE_FLOAT_COUNT);
+let peerCount = 0;
+
+function ensurePeerCapacity(count: number): void {
+  const needed = count * POSE_FLOAT_COUNT;
+  if (xyz.length >= needed) {
+    return;
+  }
+  let nextLength = xyz.length;
+  while (nextLength < needed) {
+    nextLength *= 2;
+  }
+  const grown = new Float32Array(nextLength);
+  grown.set(xyz);
+  xyz = grown;
+}
+
+function setPose(sessionId: string, x: number, y: number, z: number): void {
+  let index = indexBySession.get(sessionId);
+  if (index === undefined) {
+    index = peerCount;
+    peerCount += 1;
+    sessionIds[index] = sessionId;
+    indexBySession.set(sessionId, index);
+    ensurePeerCapacity(peerCount);
+  }
+  const offset = index * POSE_FLOAT_COUNT;
+  xyz[offset] = x;
+  xyz[offset + 1] = y;
+  xyz[offset + 2] = z;
+}
+
+function removePeer(sessionId: string): void {
+  const index = indexBySession.get(sessionId);
+  if (index === undefined) {
+    return;
+  }
+  const last = peerCount - 1;
+  if (index !== last) {
+    const lastId = sessionIds[last]!;
+    sessionIds[index] = lastId;
+    indexBySession.set(lastId, index);
+    const dest = index * POSE_FLOAT_COUNT;
+    const src = last * POSE_FLOAT_COUNT;
+    xyz[dest] = xyz[src]!;
+    xyz[dest + 1] = xyz[src + 1]!;
+    xyz[dest + 2] = xyz[src + 2]!;
+  }
+  indexBySession.delete(sessionId);
+  peerCount -= 1;
+  sessionIds.length = peerCount;
+}
+
+function broadcastWorld(): void {
+  // sessionIds.length === peerCount, so one Buffer view is shared by every send.
+  const payload = snapshot.encodePacked(sessionIds, xyz, peerCount);
+  broadCastBinaryToClients(payload, sessionIds, "sync");
+}
+
+export default defineAgent({
+  onClientJoin({ sessionId }) {
+    setPose(sessionId, 0, 0, 0);
+    broadcastWorld();
+  },
+
+  onClientLeave({ sessionId }) {
+    removePeer(sessionId);
+    broadcastWorld();
+  },
+
+  onDataChannelBinary({ sessionId, rawBinary }) {
+    let index = indexBySession.get(sessionId);
+    if (index === undefined) {
+      setPose(sessionId, 0, 0, 0);
+      index = indexBySession.get(sessionId);
+      if (index === undefined) {
+        return;
+      }
+    }
+    if (!decodePoseInto(rawBinary, xyz, index * POSE_FLOAT_COUNT)) {
+      return;
+    }
+    broadcastWorld();
+  },
+});