@voicethere/agent 0.7.12 → 0.8.0

package/templates/spatial-showcase/protocol.ts

@@ -8,6 +8,8 @@ const SHOWCASE_DEMOS = new Set<string>(["orbit", "soundboard", "proximity"]);
 
 export const MAX_SAY_TEXT_LENGTH = 200;
 export const MAX_XZ = 5;
+export const ORBIT_SINE_MIN_FREQUENCY_HZ = 110;
+export const ORBIT_SINE_MAX_FREQUENCY_HZ = 1760;
 
 export type ShowcaseJoinMessage = {
   type: "join";
@@ -22,6 +24,8 @@ export type ShowcaseOrbitSetMessage = {
   periodSec?: number;
   elevation?: number;
   paused?: boolean;
+  frequencyHz?: number;
+  sinePlaying?: boolean;
 };
 
 export type ShowcaseOrbitSayMessage = {
@@ -30,6 +34,13 @@ export type ShowcaseOrbitSayMessage = {
   text: string;
 };
 
+export type ShowcaseOrbitPlaceMessage = {
+  type: "orbit";
+  action: "place";
+  x: number;
+  z: number;
+};
+
 export type ShowcasePadMessage = {
   type: "pad";
   clipId: string;
@@ -49,6 +60,13 @@ export type ShowcasePadStatusMessage = {
   playId: string;
 };
 
+export type ShowcasePadMoveMessage = {
+  type: "pad_move";
+  playId: string;
+  x: number;
+  z: number;
+};
+
 export type ShowcaseMoveMessage = {
   type: "move";
   x: number;
@@ -74,9 +92,11 @@ export type ShowcaseInbound =
   | ShowcaseJoinMessage
   | ShowcaseOrbitSetMessage
   | ShowcaseOrbitSayMessage
+  | ShowcaseOrbitPlaceMessage
   | ShowcasePadMessage
   | ShowcasePadStopMessage
   | ShowcasePadStatusMessage
+  | ShowcasePadMoveMessage
   | ShowcaseMoveMessage
   | ShowcaseMutePeerMessage
   | ShowcaseLeaveMessage
@@ -98,6 +118,11 @@ export type ShowcaseOrbitPose = {
   z: number;
 };
 
+export type ShowcaseOrbitSayStatus = {
+  type: "orbit_say_status";
+  status: "playing" | "ended";
+};
+
 export type ShowcasePadProgress = {
   type: "pad_progress";
   playId: string;
@@ -127,6 +152,7 @@ export type ShowcaseError = {
 export type ShowcaseOutbound =
   | ShowcaseAck
   | ShowcaseOrbitPose
+  | ShowcaseOrbitSayStatus
   | ShowcasePadProgress
   | ShowcaseRoomState
   | ShowcaseRoomFull
@@ -144,6 +170,12 @@ function isInXzRange(value: number): boolean {
   return value >= -MAX_XZ && value <= MAX_XZ;
 }
 
+function isOrbitSineFrequencyHz(value: number): boolean {
+  return (
+    value >= ORBIT_SINE_MIN_FREQUENCY_HZ && value <= ORBIT_SINE_MAX_FREQUENCY_HZ
+  );
+}
+
 function isMixPlacement(value: unknown): value is MixPlacement {
   return (
     value === "center" ||
@@ -221,6 +253,19 @@ export function parseShowcaseMessage(message: unknown): ShowcaseInbound | null {
         if (set.paused !== undefined && typeof set.paused !== "boolean") {
           return null;
         }
+        if (
+          set.frequencyHz !== undefined &&
+          (!isFiniteNumber(set.frequencyHz) ||
+            !isOrbitSineFrequencyHz(set.frequencyHz))
+        ) {
+          return null;
+        }
+        if (
+          set.sinePlaying !== undefined &&
+          typeof set.sinePlaying !== "boolean"
+        ) {
+          return null;
+        }
         return {
           type: "orbit",
           action: "set",
@@ -228,8 +273,24 @@ export function parseShowcaseMessage(message: unknown): ShowcaseInbound | null {
           ...(set.periodSec !== undefined ? { periodSec: set.periodSec } : {}),
           ...(set.elevation !== undefined ? { elevation: set.elevation } : {}),
           ...(set.paused !== undefined ? { paused: set.paused } : {}),
+          ...(set.frequencyHz !== undefined
+            ? { frequencyHz: set.frequencyHz }
+            : {}),
+          ...(set.sinePlaying !== undefined
+            ? { sinePlaying: set.sinePlaying }
+            : {}),
         };
       }
+      if (orbit.action === "place") {
+        const place = message as ShowcaseOrbitPlaceMessage;
+        if (!isFiniteNumber(place.x) || !isInXzRange(place.x)) {
+          return null;
+        }
+        if (!isFiniteNumber(place.z) || !isInXzRange(place.z)) {
+          return null;
+        }
+        return { type: "orbit", action: "place", x: place.x, z: place.z };
+      }
       if (orbit.action === "say") {
         const say = message as ShowcaseOrbitSayMessage;
         if (
@@ -287,6 +348,24 @@ export function parseShowcaseMessage(message: unknown): ShowcaseInbound | null {
       }
       return { type: "pad_status", playId: status.playId.trim() };
     }
+    case "pad_move": {
+      const padMove = message as ShowcasePadMoveMessage;
+      if (!isNonEmptyString(padMove.playId)) {
+        return null;
+      }
+      if (!isFiniteNumber(padMove.x) || !isInXzRange(padMove.x)) {
+        return null;
+      }
+      if (!isFiniteNumber(padMove.z) || !isInXzRange(padMove.z)) {
+        return null;
+      }
+      return {
+        type: "pad_move",
+        playId: padMove.playId.trim(),
+        x: padMove.x,
+        z: padMove.z,
+      };
+    }
     case "move": {
       const move = message as ShowcaseMoveMessage;
       if (!isFiniteNumber(move.x) || !isInXzRange(move.x)) {

package/templates/spatial-showcase/sine.ts

@@ -1,22 +1,45 @@
 /** Inline orbit sine clip — 16 kHz mono s16le, decoded size under 64 KiB play cap. */
 
-/** 2 s keeps loop-restart gaps (250 ms poll) infrequent; 16 kHz mono still fits under 64 KiB. */
+/** 2 s keeps loop-restart gaps infrequent; 16 kHz mono still fits under 64 KiB. */
 export const ORBIT_SINE_DURATION_MS = 2000;
 export const ORBIT_SINE_FREQUENCY_HZ = 440;
 export const ORBIT_SINE_AMPLITUDE = 8000;
+export const ORBIT_SINE_SAMPLE_RATE = 16_000;
 export const ORBIT_SINE_INLINE_URL =
   "https://example.com/inline-orbit-sine.wav";
 
-/** Looping ~440 Hz sine WAV as base64 for {@link play} inline bytes. */
+/** Snap duration to an integer number of cycles so the clip loops at a zero crossing. */
+export function orbitSineSampleCount(
+  durationMs = ORBIT_SINE_DURATION_MS,
+  frequencyHz = ORBIT_SINE_FREQUENCY_HZ,
+  sampleRate = ORBIT_SINE_SAMPLE_RATE,
+): number {
+  const targetCycles = (durationMs / 1000) * frequencyHz;
+  const cycles = Math.max(1, Math.floor(targetCycles));
+  return Math.round((cycles * sampleRate) / frequencyHz);
+}
+
+/** Duration in ms for a clip built with {@link orbitSineSampleCount}. */
+export function orbitSineClipDurationMs(
+  durationMs = ORBIT_SINE_DURATION_MS,
+  frequencyHz = ORBIT_SINE_FREQUENCY_HZ,
+  sampleRate = ORBIT_SINE_SAMPLE_RATE,
+): number {
+  const numSamples = orbitSineSampleCount(durationMs, frequencyHz, sampleRate);
+  return (numSamples / sampleRate) * 1000;
+}
+
+/** Looping sine WAV as base64 for {@link play} inline bytes. */
 export function buildOrbitSineInlineClipBase64(
   durationMs = ORBIT_SINE_DURATION_MS,
   frequencyHz = ORBIT_SINE_FREQUENCY_HZ,
   amplitude = ORBIT_SINE_AMPLITUDE,
+  phaseRad = 0,
 ): string {
-  const sampleRate = 16_000;
+  const sampleRate = ORBIT_SINE_SAMPLE_RATE;
   const channels = 1;
   const bytesPerSample = 2;
-  const numSamples = Math.floor((sampleRate * durationMs) / 1000);
+  const numSamples = orbitSineSampleCount(durationMs, frequencyHz, sampleRate);
   const dataSize = numSamples * channels * bytesPerSample;
   const buffer = Buffer.alloc(44 + dataSize);
   buffer.write("RIFF", 0);
@@ -35,7 +58,7 @@ export function buildOrbitSineInlineClipBase64(
   for (let i = 0; i < numSamples; i++) {
     const t = i / sampleRate;
     const sample = Math.round(
-      amplitude * Math.sin(2 * Math.PI * frequencyHz * t),
+      amplitude * Math.sin(2 * Math.PI * frequencyHz * t + phaseRad),
     );
     buffer.writeInt16LE(sample, 44 + i * 2);
   }

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();
+  },
+});