@voicethere/agent 0.7.12 → 0.8.0

package/templates/{game-sync-redis.ts → game-sync/redis.ts}

@@ -1,24 +1,15 @@
 /**
  * Redis Lua scripts and helpers for game-sync world buffer.
  */
-import { MAX_LIVE_OBJECTS } from "./game-sync-protocol.js";
+import { MAX_LIVE_OBJECTS } from "./protocol.js";
 import {
-  objectIdHeaderBytes,
+  OBJECT_ID_HEADERS_BLOB,
   OBJECT_SLOT_BYTE_LENGTH,
   WORLD_BYTE_LENGTH,
   REDIS_WORLD_KEY,
-} from "./game-sync-world-layout.js";
+} from "./world-layout.js";
 
-/** Concatenated 4-byte float32 headers for objectId 1..MAX_LIVE_OBJECTS. */
-export function buildObjectIdHeadersBlob(): Buffer {
-  const parts: Buffer[] = [];
-  for (let objectId = 1; objectId <= MAX_LIVE_OBJECTS; objectId += 1) {
-    parts.push(objectIdHeaderBytes(objectId));
-  }
-  return Buffer.concat(parts);
-}
-
-export const OBJECT_ID_HEADERS_BLOB = buildObjectIdHeadersBlob();
+export { OBJECT_ID_HEADERS_BLOB };
 
 /**
  * Atomic allocate: find first empty slot, enforce global live cap, write 9-float record.

package/templates/{game-sync-sim.ts → game-sync/sim.ts}

@@ -1,7 +1,7 @@
 /**
  * Server-authoritative game-sync physics step (pure Float32Array, no Redis).
  */
-import { objectIdToSlot } from "./game-sync-world-layout.js";
+import { objectIdToSlot } from "./world-layout.js";
 
 export const BOARD_WIDTH = 1280;
 export const BOARD_HEIGHT = 720;
@@ -9,12 +9,19 @@ export const OBJECT_RADIUS = 25;
 export const COLLISION_RESTITUTION = 1.0;
 export const OBJECT_STRIDE = 9;
 
+/**
+ * Advance every active object by `dtSec`. `activeObjectIds` may be a plain
+ * array or a persistent Int32Array; `count` limits how many leading entries
+ * are live so the caller can reuse one typed array across ticks.
+ */
 export function simulateWorldStep(
   worldState: Float32Array,
   dtSec: number,
-  activeObjectIds: number[],
+  activeObjectIds: ArrayLike<number>,
+  count: number = activeObjectIds.length,
 ): void {
-  for (const objectId of activeObjectIds) {
+  for (let i = 0; i < count; i += 1) {
+    const objectId = activeObjectIds[i] ?? 0;
     const slot = objectIdToSlot(objectId);
     const start = slot * OBJECT_STRIDE;
     if (start < 0 || start + OBJECT_STRIDE > worldState.length) continue;
@@ -42,13 +49,13 @@ export function simulateWorldStep(
     worldState[start + 6] = vy;
   }
 
-  for (let i = 0; i < activeObjectIds.length; i += 1) {
-    const aId = activeObjectIds[i];
+  for (let i = 0; i < count; i += 1) {
+    const aId = activeObjectIds[i] ?? 0;
     const aSlot = objectIdToSlot(aId);
     const aStart = aSlot * OBJECT_STRIDE;
     if (aStart < 0 || aStart + OBJECT_STRIDE > worldState.length) continue;
-    for (let j = i + 1; j < activeObjectIds.length; j += 1) {
-      const bId = activeObjectIds[j];
+    for (let j = i + 1; j < count; j += 1) {
+      const bId = activeObjectIds[j] ?? 0;
       const bSlot = objectIdToSlot(bId);
       const bStart = bSlot * OBJECT_STRIDE;
       if (bStart < 0 || bStart + OBJECT_STRIDE > worldState.length) continue;

package/templates/{game-sync-world-layout.ts → game-sync/world-layout.ts}

@@ -5,7 +5,7 @@
  * Slot layout: [objectId, posX, posY, posZ, posW, dirX, dirY, dirZ, dirW]
  * Empty slot: objectId === 0
  */
-import { MAX_LIVE_OBJECTS } from "./game-sync-protocol.js";
+import { MAX_LIVE_OBJECTS } from "./protocol.js";
 
 export const OBJECT_STRIDE = 9;
 export const WORLD_FLOAT_COUNT = MAX_LIVE_OBJECTS * OBJECT_STRIDE;
@@ -74,6 +74,14 @@ export function markSlotFree(world: Float32Array, slot: number): void {
   }
 }
 
+const OBJECT_SLOT_SCRATCH = new Float32Array(OBJECT_STRIDE);
+const OBJECT_SLOT_SCRATCH_BUF = Buffer.from(
+  OBJECT_SLOT_SCRATCH.buffer,
+  OBJECT_SLOT_SCRATCH.byteOffset,
+  OBJECT_SLOT_BYTE_LENGTH,
+);
+
+/** Shared 9-float slot buffer (overwritten on the next call). */
 export function encodeObjectSlot(
   objectId: number,
   posX: number,
@@ -85,18 +93,16 @@ export function encodeObjectSlot(
   dirZ: number,
   dirW: number,
 ): Buffer {
-  const floats = new Float32Array([
-    objectId,
-    posX,
-    posY,
-    posZ,
-    posW,
-    dirX,
-    dirY,
-    dirZ,
-    dirW,
-  ]);
-  return Buffer.from(floats.buffer, floats.byteOffset, floats.byteLength);
+  OBJECT_SLOT_SCRATCH[0] = objectId;
+  OBJECT_SLOT_SCRATCH[1] = posX;
+  OBJECT_SLOT_SCRATCH[2] = posY;
+  OBJECT_SLOT_SCRATCH[3] = posZ;
+  OBJECT_SLOT_SCRATCH[4] = posW;
+  OBJECT_SLOT_SCRATCH[5] = dirX;
+  OBJECT_SLOT_SCRATCH[6] = dirY;
+  OBJECT_SLOT_SCRATCH[7] = dirZ;
+  OBJECT_SLOT_SCRATCH[8] = dirW;
+  return OBJECT_SLOT_SCRATCH_BUF;
 }
 
 export function writeObjectSlot(
@@ -162,6 +168,26 @@ export function collectActiveObjectIds(world: Float32Array): number[] {
   return ids;
 }
 
+/**
+ * Allocation-free variant for the sim loop: writes live object ids into `dest`
+ * (capacity >= MAX_LIVE_OBJECTS) and returns how many were written.
+ */
+export function collectActiveObjectIdsInto(
+  world: Float32Array,
+  dest: Int32Array,
+): number {
+  let count = 0;
+  const limit = Math.min(MAX_LIVE_OBJECTS, dest.length);
+  for (let slot = 0; slot < MAX_LIVE_OBJECTS && count < limit; slot += 1) {
+    const objectId = readSlotObjectId(world, slot);
+    if (objectId !== 0) {
+      dest[count] = objectId;
+      count += 1;
+    }
+  }
+  return count;
+}
+
 export interface LiveWorldObjectInfo {
   objectId: number;
   ownerSessionId: string;
@@ -208,32 +234,48 @@ export function clampSimulationDtSec(
 }
 
 /**
- * Decode a Redis / Node Buffer into a fixed-size world Float32Array.
+ * Copy Redis / Node Buffer bytes into `dest` (default: a new world).
+ *
+ * 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;
 }
 
-/** Float32 objectId bytes for Lua slot header splice (objectId 1..MAX_LIVE_OBJECTS). */
+/** Concatenated float32 objectId headers (1..MAX_LIVE_OBJECTS), one allocation. */
+export const OBJECT_ID_HEADERS_BLOB = (() => {
+  const blob = Buffer.alloc(MAX_LIVE_OBJECTS * 4);
+  for (let objectId = 1; objectId <= MAX_LIVE_OBJECTS; objectId += 1) {
+    blob.writeFloatLE(objectId, (objectId - 1) * 4);
+  }
+  return blob;
+})();
+
+/** View into {@link OBJECT_ID_HEADERS_BLOB} for Lua slot header splice. */
 export function objectIdHeaderBytes(objectId: number): Buffer {
-  const header = new Float32Array([objectId]);
-  return Buffer.from(header.buffer, header.byteOffset, 4);
+  const index = objectId - 1;
+  return OBJECT_ID_HEADERS_BLOB.subarray(index * 4, index * 4 + 4);
 }

package/templates/game-sync-smoke/README.md

@@ -0,0 +1,13 @@
+# game-sync-smoke
+
+Minimal data-channel agent for deploy-smoke, shared-child, and idle smokes. Not seeded on project create.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/game-sync-smoke/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/mix-smoke/README.md

@@ -0,0 +1,13 @@
+# mix-smoke
+
+Positional mix DataChannel commands for voice-data-mix-smoke (Voice+Data, shared child). Not seeded on project create.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/mix-smoke/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/positional-tts/README.md

@@ -0,0 +1,13 @@
+# positional-tts
+
+Voice+Data demo — enables positional mixing and orbits each listener’s TTS speaker with `setTtsPose`. Requires Voice+Data runner mode.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/positional-tts/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`, `orbit.ts`

package/templates/recording-consent/README.md

@@ -0,0 +1,13 @@
+# recording-consent
+
+Conversation recording consent on connect. Pauses capture while collecting name and date of birth, then resumes only if the customer consented.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/recording-consent/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`, `conversation.ts`

package/templates/redis-sync/README.md

@@ -0,0 +1,23 @@
+# redis-sync
+
+Redis-backed world buffer sync for redis-sync-smoke (Advanced tier + project Redis). Not seeded on project create.
+
+Clients publish a 12-byte `Float32Array([clientIndex, x, y])` on `voicethere-sync`. Each tick's Redis GET is copied into one `Float32Array` in place and every broadcast is one `broadCastBinaryToClients` call with the same persistent `Buffer` view over a live session array. Slot patches reuse one 16-byte scratch buffer.
+
+## Protocol
+
+- **Inbound (12 bytes):** little-endian `float32` `[clientIndex, x, y]` via `onDataChannelBinary`
+- **Outbound:** full world blob (`MAX_PEERS` slots × `[clientIndex, x, y, active]`)
+- **Redis:** key `e2e:redis-sync:world`, Lua `LUA_PATCH_PEER_SLOT`
+
+Reuse one `Float32Array(3)` on the client (`sendSyncBinary`).
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/redis-sync/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`, `world-layout.ts`

package/templates/redis-sync/agent.ts

@@ -2,10 +2,11 @@
  * 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.
+ * Each client owns a fixed slot and publishes a 12-byte `ArrayBuffer`
+ * `Float32Array([clientIndex, x, y])` on the sync DataChannel. 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).
@@ -13,85 +14,50 @@
  * 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 { Redis } from "ioredis";
+import {
+  agentLog,
+  broadCastBinaryToClients,
+  defineAgent,
+  sendBinaryToClient,
+} from "@voicethere/agent";
 
 import {
   createEmptyWorldBuffer,
+  decodePositionBuffer,
   normalizeWorldBuffer,
   peerSlotOffset,
   PEER_SLOT_BYTE_LENGTH,
+  PEER_STRIDE,
   REDIS_WORLD_KEY,
   WORLD_BYTE_LENGTH,
   writePeerSlot,
+  LUA_PATCH_PEER_SLOT,
 } 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>();
+/** Same members as connectedSessions; array form for the per-tick broadcast. */
+const connectedSessionList: string[] = [];
 const sessionClientIndex = new Map<string, number>();
-let localWorld = createEmptyWorldBuffer();
+/** The one world buffer: Redis GETs copy into it, every broadcast sends this view. */
+const localWorld = createEmptyWorldBuffer();
+const localWorldBytes = Buffer.from(
+  localWorld.buffer,
+  localWorld.byteOffset,
+  localWorld.byteLength,
+);
 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);
-}
+const PEER_SLOT = new Float32Array(PEER_STRIDE);
+const PEER_SLOT_BUF = Buffer.from(
+  PEER_SLOT.buffer,
+  PEER_SLOT.byteOffset,
+  PEER_SLOT.byteLength,
+);
 
 function encodePeerSlot(
   clientIndex: number,
@@ -99,15 +65,15 @@ function encodePeerSlot(
   y: number,
   active: number,
 ): Buffer {
-  const floats = new Float32Array([clientIndex, x, y, active]);
-  return Buffer.from(floats.buffer, floats.byteOffset, floats.byteLength);
+  PEER_SLOT[0] = clientIndex;
+  PEER_SLOT[1] = x;
+  PEER_SLOT[2] = y;
+  PEER_SLOT[3] = active;
+  return PEER_SLOT_BUF;
 }
 
-function broadcastWorldBuffer(
-  world: Float32Array,
-  targetSessionId?: string,
-): void {
-  const payload = copyWorldBuffer(world);
+function broadcastWorldBuffer(targetSessionId?: string): void {
+  const payload = localWorldBytes;
   if (targetSessionId) {
     try {
       sendBinaryToClient(targetSessionId, payload, "sync");
@@ -120,41 +86,44 @@ function broadcastWorldBuffer(
     }
     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}`);
-    }
+  if (connectedSessionList.length === 0) return;
+  try {
+    // payload is already a Buffer: forwarded as-is, one call, no Set iterator.
+    broadCastBinaryToClients(payload, connectedSessionList, "sync");
+  } catch (error: unknown) {
+    const detail = error instanceof Error ? error.message : String(error);
+    agentLog("error", `world broadcast send failed: ${detail}`);
   }
 }
 
-async function loadWorldFromRedis(): Promise<Float32Array> {
-  if (!redis) {
-    return new Float32Array(localWorld);
-  }
+/** Copy the Redis blob into `localWorld` in place; the GET reply is the only allocation. */
+async function loadWorldFromRedis(): Promise<void> {
+  if (!redis) return;
   const raw = await redis.getBuffer(REDIS_WORLD_KEY);
-  return normalizeWorldBuffer(raw);
+  normalizeWorldBuffer(raw, localWorld);
 }
 
 async function broadcastWorldFromRedis(
   targetSessionId?: string,
 ): Promise<void> {
-  const world = await loadWorldFromRedis();
-  broadcastWorldBuffer(world, targetSessionId);
+  await loadWorldFromRedis();
+  broadcastWorldBuffer(targetSessionId);
+}
+
+function logBroadcastError(error: unknown): void {
+  const detail = error instanceof Error ? error.message : String(error);
+  agentLog("error", `world broadcast failed: ${detail}`);
+}
+
+function onBroadcastTick(): void {
+  void broadcastWorldFromRedis().catch(logBroadcastError);
 }
 
 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);
+  broadcastTimer = setInterval(onBroadcastTick, WORLD_BROADCAST_INTERVAL_MS);
   agentLog("info", `world loop started (${WORLD_BROADCAST_HZ}Hz)`);
 }
 
@@ -218,13 +187,21 @@ defineAgent({
   },
 
   async onClientJoin({ sessionId }) {
-    connectedSessions.add(sessionId);
+    if (!connectedSessions.has(sessionId)) {
+      connectedSessions.add(sessionId);
+      connectedSessionList.push(sessionId);
+    }
     startBroadcastLoopIfNeeded();
     await broadcastWorldFromRedis(sessionId);
   },
 
   async onClientLeave({ sessionId }) {
-    connectedSessions.delete(sessionId);
+    if (connectedSessions.delete(sessionId)) {
+      const index = connectedSessionList.indexOf(sessionId);
+      if (index !== -1) {
+        connectedSessionList.splice(index, 1);
+      }
+    }
     const clientIndex = sessionClientIndex.get(sessionId);
     sessionClientIndex.delete(sessionId);
     stopBroadcastLoopIfNeeded();
@@ -239,8 +216,8 @@ defineAgent({
     }
   },
 
-  async onDataChannelMessage(ctx) {
-    const position = parsePositionMessage(ctx.message);
+  async onDataChannelBinary(ctx) {
+    const position = decodePositionBuffer(ctx.rawBinary);
     if (!position) {
       return;
     }