@voicethere/agent 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voicethere/agent",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "VoiceThere customer agent SDK — IPC types and runtime helpers for sandboxed child bundles",
   "type": "module",
   "exports": {
@@ -83,20 +83,20 @@
   },
   "license": "MIT",
   "dependencies": {
-    "esbuild": "^0.25.12"
+    "esbuild": "0.25.12"
   },
   "peerDependencies": {
     "@node-webrtc-rust/sdk": ">=0.6.5"
   },
   "devDependencies": {
-    "@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",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.0",
-    "vitest": "^2.1.8"
+    "@node-webrtc-rust/helpers": "0.7.4",
+    "@node-webrtc-rust/sdk": "0.7.4",
+    "@node-webrtc-rust/signaling": "0.7.4",
+    "@types/node": "22.20.1",
+    "http-server": "14.1.1",
+    "ioredis": "5.11.1",
+    "tsx": "4.19.2",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7"
   }
 }

package/templates/README.md

@@ -15,10 +15,10 @@ import {
 
 ## Product vs e2e
 
-| Kind | Dashboard create | Prebuilt seed bundle | Typical consumer |
-| --- | --- | --- | --- |
-| **product** | Yes (`echo`, `echo-dc`, `voice-starter`, `game-sync`, `webhooks`, `webhooks-redis`) | Yes — `dist/templates/<id>/agent.js` | Platform project create |
-| **e2e** | No | No — build from sources at test time | `voicethere/e2e` smokes |
+| Kind        | Dashboard create                                                                                      | Prebuilt seed bundle                 | Typical consumer        |
+| ----------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------- |
+| **product** | Yes (`echo`, `echo-dc`, `voice-starter`, `game-sync`, `voice-showcase`, `webhooks`, `webhooks-redis`) | 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`.
 
@@ -57,7 +57,15 @@ Full starter bundle covering every speech event from `@node-webrtc-rust/sdk/voic
 
 ### `game-sync.ts` (`game-sync`)
 
-Authoritative multi-object sync sample for real-time games/simulations (register, simulate, binary world snapshots).
+Authoritative multi-object sync sample for real-time games/simulations (register, simulate, binary world snapshots). Live objects are capped at **25** per world; clients can send `{ type: "unregister" }` (or `{ type: "remove", objectId?: number }`) to release owned objects. Protocol helpers live in `game-sync-protocol.ts`.
+
+When `AGENT_REDIS_URL` is set (project Redis), the world blob is stored at `game-sync:world` and shared across runner workers — Lua atomic allocate/release enforces the global cap; one worker holds a sim lock per tick. Without Redis, the template falls back to per-worker in-memory state (local live-test stack).
+
+### `voice-showcase/` (`voice-showcase`)
+
+Conversational voice demo for landing and dashboard previews — greets the user, asks for a name, then offers a menu: weather (Open-Meteo, no API key), count 1–10, short recipes, and rotating fun facts. Typed chat and voice finals share the same handler. Sends structured `menu` payloads plus `chat_reply` for the chat log.
+
+Sources: `voice-showcase/agent.ts` (defineAgent wiring), `conversation.ts` (pure state machine), `weather.ts`, `recipes.ts`, `fun-facts.ts`.
 
 ### `webhooks.ts` (`webhooks`)
 
@@ -71,12 +79,12 @@ Same HMAC verify path plus an atomic Redis counter (`AGENT_REDIS_URL`) before Da
 
 These mirror former `e2e/fixtures/*` sources. E2E resolves entries from the package, builds into ephemeral workdirs, and uploads `dist/agent.js`.
 
-| 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) |
+| 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) |
 
 **Note:** Product `echo` is not the same as e2e `echo-smoke` — keep both ids.
 

package/templates/game-sync-protocol.ts

@@ -0,0 +1,65 @@
+/**
+ * game-sync control-plane message parsers and constants (no defineAgent).
+ */
+
+export const MAX_LIVE_OBJECTS = 25;
+
+export const REGISTER_NACK_REASON_WORLD_FULL = "world_full" as const;
+export const UNREGISTER_NACK_REASON_NOT_FOUND = "not_found" as const;
+export const UNREGISTER_NACK_REASON_NOT_OWNER = "not_owner" as const;
+
+export function parseRegisterCommand(message: unknown): boolean {
+  if (!message || typeof message !== "object") return false;
+  const record = message as { type?: unknown };
+  return record.type === "register";
+}
+
+export interface UnregisterCommand {
+  type: "unregister" | "remove";
+  objectId?: number;
+}
+
+export function resolveRemoveTarget(
+  objectId: number | undefined,
+  ownedObjectIds: ReadonlySet<number> | undefined | null,
+): { ok: true; objectId: number } | { ok: false; reason: string } {
+  if (objectId !== undefined) {
+    return { ok: true, objectId };
+  }
+  if (!ownedObjectIds || ownedObjectIds.size === 0) {
+    return { ok: false, reason: UNREGISTER_NACK_REASON_NOT_FOUND };
+  }
+  return { ok: true, objectId: Math.max(...ownedObjectIds) };
+}
+
+export function parseUnregisterCommand(
+  message: unknown,
+): UnregisterCommand | null {
+  if (!message || typeof message !== "object") return null;
+  const record = message as { type?: unknown; objectId?: unknown };
+  if (record.type !== "unregister" && record.type !== "remove") {
+    return null;
+  }
+  if (record.objectId === undefined) {
+    return { type: record.type as "unregister" | "remove" };
+  }
+  if (
+    typeof record.objectId !== "number" ||
+    !Number.isFinite(record.objectId)
+  ) {
+    return null;
+  }
+  return {
+    type: record.type as "unregister" | "remove",
+    objectId: Math.trunc(record.objectId),
+  };
+}
+
+export function parseChatCommand(message: unknown): { text: string } | null {
+  if (!message || typeof message !== "object") return null;
+  const record = message as { type?: unknown; text?: unknown };
+  if (record.type !== "chat" || typeof record.text !== "string") return null;
+  const text = record.text.trim();
+  if (!text) return null;
+  return { text };
+}

package/templates/game-sync-redis.ts

@@ -0,0 +1,121 @@
+/**
+ * Redis Lua scripts and helpers for game-sync world buffer.
+ */
+import { MAX_LIVE_OBJECTS } from "./game-sync-protocol.js";
+import {
+  objectIdHeaderBytes,
+  OBJECT_SLOT_BYTE_LENGTH,
+  WORLD_BYTE_LENGTH,
+  REDIS_WORLD_KEY,
+} from "./game-sync-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();
+
+/**
+ * Atomic allocate: find first empty slot, enforce global live cap, write 9-float record.
+ * Returns objectId (1-based) or -1 when world is full.
+ *
+ * ARGV[4] = 32-byte tail (8 floats: pos + dir without objectId header)
+ * ARGV[5] = 100-byte objectId header lookup blob
+ */
+export const LUA_ALLOCATE_OBJECT = `
+local key = KEYS[1]
+local size = tonumber(ARGV[1])
+local slot_bytes = tonumber(ARGV[2])
+local max_slots = tonumber(ARGV[3])
+local tail = ARGV[4]
+local headers = ARGV[5]
+
+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
+
+local live = 0
+local empty_off = nil
+for i = 0, max_slots - 1 do
+  local off = i * slot_bytes + 1
+  local b1, b2, b3, b4 = string.byte(world, off, off + 3)
+  if b1 == 0 and b2 == 0 and b3 == 0 and b4 == 0 then
+    if empty_off == nil then empty_off = off end
+  else
+    live = live + 1
+  end
+end
+
+if live >= max_slots or empty_off == nil then
+  return -1
+end
+
+local slot_index = math.floor((empty_off - 1) / slot_bytes)
+local object_id = slot_index + 1
+local header = string.sub(headers, (object_id - 1) * 4 + 1, object_id * 4)
+local new_slot = header .. tail
+if #new_slot ~= slot_bytes then
+  return -2
+end
+
+world = string.sub(world, 1, empty_off - 1) .. new_slot .. string.sub(world, empty_off + slot_bytes)
+redis.call('SET', key, world)
+return object_id
+`;
+
+/**
+ * Zero the fixed slot for objectId when the header matches.
+ * Returns 1 on success, 0 when slot empty or objectId mismatch.
+ */
+export const LUA_RELEASE_OBJECT = `
+local key = KEYS[1]
+local size = tonumber(ARGV[1])
+local slot_bytes = tonumber(ARGV[2])
+local max_slots = tonumber(ARGV[3])
+local object_id = tonumber(ARGV[4])
+local headers = ARGV[5]
+
+if object_id < 1 or object_id > max_slots then
+  return 0
+end
+
+local world = redis.call('GET', key)
+if not world then
+  return 0
+elseif #world < size then
+  world = world .. string.rep(string.char(0), size - #world)
+elseif #world > size then
+  world = string.sub(world, 1, size)
+end
+
+local slot_index = object_id - 1
+local off = slot_index * slot_bytes + 1
+local header = string.sub(headers, (object_id - 1) * 4 + 1, object_id * 4)
+local current = string.sub(world, off, off + 3)
+if current ~= header then
+  return 0
+end
+
+local zero_slot = string.rep(string.char(0), slot_bytes)
+world = string.sub(world, 1, off - 1) .. zero_slot .. string.sub(world, off + slot_bytes)
+redis.call('SET', key, world)
+return 1
+`;
+
+export const REDIS_EVAL_KEYS = {
+  worldKey: REDIS_WORLD_KEY,
+  worldByteLength: String(WORLD_BYTE_LENGTH),
+  slotByteLength: String(OBJECT_SLOT_BYTE_LENGTH),
+  maxSlots: String(MAX_LIVE_OBJECTS),
+  headers: OBJECT_ID_HEADERS_BLOB,
+} as const;

package/templates/game-sync-sim.ts

@@ -0,0 +1,122 @@
+/**
+ * Server-authoritative game-sync physics step (pure Float32Array, no Redis).
+ */
+import { objectIdToSlot } from "./game-sync-world-layout.js";
+
+export const BOARD_WIDTH = 1280;
+export const BOARD_HEIGHT = 720;
+export const OBJECT_RADIUS = 25;
+export const COLLISION_RESTITUTION = 1.0;
+export const OBJECT_STRIDE = 9;
+
+export function simulateWorldStep(
+  worldState: Float32Array,
+  dtSec: number,
+  activeObjectIds: number[],
+): void {
+  for (const objectId of activeObjectIds) {
+    const slot = objectIdToSlot(objectId);
+    const start = slot * OBJECT_STRIDE;
+    if (start < 0 || start + OBJECT_STRIDE > worldState.length) continue;
+
+    let x = worldState[start + 1] ?? 0;
+    let y = worldState[start + 2] ?? 0;
+    let vx = worldState[start + 5] ?? 0;
+    let vy = worldState[start + 6] ?? 0;
+
+    x += vx * dtSec;
+    y += vy * dtSec;
+
+    if (x < OBJECT_RADIUS || x > BOARD_WIDTH - OBJECT_RADIUS) {
+      vx *= -1;
+      x = Math.max(OBJECT_RADIUS, Math.min(BOARD_WIDTH - OBJECT_RADIUS, x));
+    }
+    if (y < OBJECT_RADIUS || y > BOARD_HEIGHT - OBJECT_RADIUS) {
+      vy *= -1;
+      y = Math.max(OBJECT_RADIUS, Math.min(BOARD_HEIGHT - OBJECT_RADIUS, y));
+    }
+
+    worldState[start + 1] = x;
+    worldState[start + 2] = y;
+    worldState[start + 5] = vx;
+    worldState[start + 6] = vy;
+  }
+
+  for (let i = 0; i < activeObjectIds.length; i += 1) {
+    const aId = activeObjectIds[i];
+    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];
+      const bSlot = objectIdToSlot(bId);
+      const bStart = bSlot * OBJECT_STRIDE;
+      if (bStart < 0 || bStart + OBJECT_STRIDE > worldState.length) continue;
+
+      let ax = worldState[aStart + 1] ?? 0;
+      let ay = worldState[aStart + 2] ?? 0;
+      let avx = worldState[aStart + 5] ?? 0;
+      let avy = worldState[aStart + 6] ?? 0;
+      let bx = worldState[bStart + 1] ?? 0;
+      let by = worldState[bStart + 2] ?? 0;
+      let bvx = worldState[bStart + 5] ?? 0;
+      let bvy = worldState[bStart + 6] ?? 0;
+
+      let dx = bx - ax;
+      let dy = by - ay;
+      let distSq = dx * dx + dy * dy;
+      const minDist = OBJECT_RADIUS * 2;
+      const minDistSq = minDist * minDist;
+      if (!(distSq > 0 && distSq < minDistSq)) continue;
+
+      let dist = Math.sqrt(distSq);
+      if (dist === 0) {
+        dx = 1;
+        dy = 0;
+        dist = 1;
+        distSq = 1;
+      }
+      const nx = dx / dist;
+      const ny = dy / dist;
+
+      const overlap = minDist - dist;
+      const half = overlap * 0.5;
+      ax -= nx * half;
+      ay -= ny * half;
+      bx += nx * half;
+      by += ny * half;
+
+      const rvx = bvx - avx;
+      const rvy = bvy - avy;
+      const velAlongNormal = rvx * nx + rvy * ny;
+      if (velAlongNormal < 0) {
+        const impulse = (-(1 + COLLISION_RESTITUTION) * velAlongNormal) / 2;
+        avx -= impulse * nx;
+        avy -= impulse * ny;
+        bvx += impulse * nx;
+        bvy += impulse * ny;
+      }
+
+      worldState[aStart + 1] = Math.max(
+        OBJECT_RADIUS,
+        Math.min(BOARD_WIDTH - OBJECT_RADIUS, ax),
+      );
+      worldState[aStart + 2] = Math.max(
+        OBJECT_RADIUS,
+        Math.min(BOARD_HEIGHT - OBJECT_RADIUS, ay),
+      );
+      worldState[aStart + 5] = avx;
+      worldState[aStart + 6] = avy;
+      worldState[bStart + 1] = Math.max(
+        OBJECT_RADIUS,
+        Math.min(BOARD_WIDTH - OBJECT_RADIUS, bx),
+      );
+      worldState[bStart + 2] = Math.max(
+        OBJECT_RADIUS,
+        Math.min(BOARD_HEIGHT - OBJECT_RADIUS, by),
+      );
+      worldState[bStart + 5] = bvx;
+      worldState[bStart + 6] = bvy;
+    }
+  }
+}

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

@@ -0,0 +1,194 @@
+/**
+ * Shared world buffer layout for game-sync (agent + unit tests).
+ *
+ * Fixed-size Float32Array: MAX_LIVE_OBJECTS slots × OBJECT_STRIDE floats each.
+ * Slot layout: [objectId, posX, posY, posZ, posW, dirX, dirY, dirZ, dirW]
+ * Empty slot: objectId === 0
+ */
+import { MAX_LIVE_OBJECTS } from "./game-sync-protocol.js";
+
+export const OBJECT_STRIDE = 9;
+export const WORLD_FLOAT_COUNT = MAX_LIVE_OBJECTS * OBJECT_STRIDE;
+export const WORLD_BYTE_LENGTH = WORLD_FLOAT_COUNT * 4;
+export const OBJECT_SLOT_BYTE_LENGTH = OBJECT_STRIDE * 4;
+
+export const REDIS_WORLD_KEY = "game-sync:world";
+export const REDIS_SIM_LOCK_KEY = "game-sync:sim-lock";
+
+export function slotToObjectId(slot: number): number {
+  return slot + 1;
+}
+
+export function objectIdToSlot(objectId: number): number {
+  return objectId - 1;
+}
+
+export function createEmptyWorldBuffer(): Float32Array {
+  return new Float32Array(WORLD_FLOAT_COUNT);
+}
+
+export function slotByteOffset(slot: number): number {
+  return slot * OBJECT_SLOT_BYTE_LENGTH;
+}
+
+export function readSlotObjectId(world: Float32Array, slot: number): number {
+  const id = world[slot * OBJECT_STRIDE];
+  return Number.isFinite(id) ? id : 0;
+}
+
+export function countLiveObjects(world: Float32Array): number {
+  let live = 0;
+  for (let slot = 0; slot < MAX_LIVE_OBJECTS; slot += 1) {
+    if (readSlotObjectId(world, slot) !== 0) {
+      live += 1;
+    }
+  }
+  return live;
+}
+
+export function findFirstEmptySlot(world: Float32Array): number | null {
+  for (let slot = 0; slot < MAX_LIVE_OBJECTS; slot += 1) {
+    if (readSlotObjectId(world, slot) === 0) {
+      return slot;
+    }
+  }
+  return null;
+}
+
+export function findSlotByObjectId(
+  world: Float32Array,
+  objectId: number,
+): number | null {
+  for (let slot = 0; slot < MAX_LIVE_OBJECTS; slot += 1) {
+    if (readSlotObjectId(world, slot) === objectId) {
+      return slot;
+    }
+  }
+  return null;
+}
+
+export function markSlotFree(world: Float32Array, slot: number): void {
+  const start = slot * OBJECT_STRIDE;
+  for (let i = 0; i < OBJECT_STRIDE; i += 1) {
+    world[start + i] = 0;
+  }
+}
+
+export function encodeObjectSlot(
+  objectId: number,
+  posX: number,
+  posY: number,
+  posZ: number,
+  posW: number,
+  dirX: number,
+  dirY: number,
+  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);
+}
+
+export function writeObjectSlot(
+  world: Float32Array,
+  slot: number,
+  objectId: number,
+  posX: number,
+  posY: number,
+  posZ: number,
+  posW: number,
+  dirX: number,
+  dirY: number,
+  dirZ: number,
+  dirW: number,
+): void {
+  const start = slot * OBJECT_STRIDE;
+  world[start] = objectId;
+  world[start + 1] = posX;
+  world[start + 2] = posY;
+  world[start + 3] = posZ;
+  world[start + 4] = posW;
+  world[start + 5] = dirX;
+  world[start + 6] = dirY;
+  world[start + 7] = dirZ;
+  world[start + 8] = dirW;
+}
+
+/**
+ * After simulating from a Redis load, keep slots empty that a concurrent release
+ * zeroed in Redis while the tick was in flight — prevents saveWorldToRedis from
+ * restoring an object Lua just cleared (sim GET → simulate → SET race).
+ *
+ * `authoritative` must be a fresh Redis GET after simulate (never stale in-memory
+ * worldState — an empty buffer would wipe every live slot).
+ */
+export function preserveEmptySlots(
+  simulated: Float32Array,
+  authoritative: Float32Array,
+): void {
+  for (let slot = 0; slot < MAX_LIVE_OBJECTS; slot += 1) {
+    if (readSlotObjectId(authoritative, slot) === 0) {
+      markSlotFree(simulated, slot);
+    }
+  }
+}
+
+/** Merge a simulated world with the latest Redis snapshot before SET. */
+export function commitSimulatedWorld(
+  simulated: Float32Array,
+  latestRedis: Float32Array,
+): void {
+  preserveEmptySlots(simulated, latestRedis);
+}
+
+export function collectActiveObjectIds(world: Float32Array): number[] {
+  const ids: number[] = [];
+  for (let slot = 0; slot < MAX_LIVE_OBJECTS; slot += 1) {
+    const objectId = readSlotObjectId(world, slot);
+    if (objectId !== 0) {
+      ids.push(objectId);
+    }
+  }
+  return ids;
+}
+
+/**
+ * Decode a Redis / Node Buffer into a fixed-size world Float32Array.
+ */
+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;
+}
+
+/** Float32 objectId bytes for Lua slot header splice (objectId 1..MAX_LIVE_OBJECTS). */
+export function objectIdHeaderBytes(objectId: number): Buffer {
+  const header = new Float32Array([objectId]);
+  return Buffer.from(header.buffer, header.byteOffset, 4);
+}