@voicethere/agent 0.7.8 → 0.7.10

package/templates/spatial-showcase/protocol.ts

@@ -0,0 +1,339 @@
+import type { MixPlacement, MixPose } from "@voicethere/agent";
+
+import { isShowcaseClipId } from "./sounds.js";
+
+export type ShowcaseDemo = "orbit" | "soundboard" | "proximity";
+
+const SHOWCASE_DEMOS = new Set<string>(["orbit", "soundboard", "proximity"]);
+
+export const MAX_SAY_TEXT_LENGTH = 200;
+export const MAX_XZ = 5;
+
+export type ShowcaseJoinMessage = {
+  type: "join";
+  demo: ShowcaseDemo;
+  assetOrigin?: string;
+};
+
+export type ShowcaseOrbitSetMessage = {
+  type: "orbit";
+  action: "set";
+  radius?: number;
+  periodSec?: number;
+  elevation?: number;
+  paused?: boolean;
+};
+
+export type ShowcaseOrbitSayMessage = {
+  type: "orbit";
+  action: "say";
+  text: string;
+};
+
+export type ShowcasePadMessage = {
+  type: "pad";
+  clipId: string;
+  x: number;
+  z: number;
+  volume?: number;
+  placement?: MixPlacement;
+};
+
+export type ShowcasePadStopMessage = {
+  type: "pad_stop";
+  playId: string;
+};
+
+export type ShowcasePadStatusMessage = {
+  type: "pad_status";
+  playId: string;
+};
+
+export type ShowcaseMoveMessage = {
+  type: "move";
+  x: number;
+  z: number;
+  yawDeg?: number;
+};
+
+export type ShowcaseMutePeerMessage = {
+  type: "mute_peer";
+  peerId: string;
+  muted: boolean;
+};
+
+export type ShowcaseLeaveMessage = {
+  type: "leave";
+};
+
+export type ShowcasePingMessage = {
+  type: "ping";
+};
+
+export type ShowcaseInbound =
+  | ShowcaseJoinMessage
+  | ShowcaseOrbitSetMessage
+  | ShowcaseOrbitSayMessage
+  | ShowcasePadMessage
+  | ShowcasePadStopMessage
+  | ShowcasePadStatusMessage
+  | ShowcaseMoveMessage
+  | ShowcaseMutePeerMessage
+  | ShowcaseLeaveMessage
+  | ShowcasePingMessage;
+
+export type ShowcaseAck =
+  | {
+      type: "showcase_ack";
+      action: string;
+      ok: true;
+      playId?: string;
+    }
+  | { type: "showcase_ack"; action: string; ok: false; error: string };
+
+export type ShowcaseOrbitPose = {
+  type: "orbit_pose";
+  angleDeg: number;
+  x: number;
+  z: number;
+};
+
+export type ShowcasePadProgress = {
+  type: "pad_progress";
+  playId: string;
+  status: string;
+};
+
+export type ShowcaseRoomState = {
+  type: "room_state";
+  peers: Array<{
+    id: string;
+    x: number;
+    z: number;
+    yawDeg: number;
+    muted: boolean;
+  }>;
+};
+
+export type ShowcaseRoomFull = {
+  type: "room_full";
+};
+
+export type ShowcaseError = {
+  type: "error";
+  message: string;
+};
+
+export type ShowcaseOutbound =
+  | ShowcaseAck
+  | ShowcaseOrbitPose
+  | ShowcasePadProgress
+  | ShowcaseRoomState
+  | ShowcaseRoomFull
+  | ShowcaseError;
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function clampVolume(value: number): number {
+  return Math.min(1, Math.max(0, value));
+}
+
+function isInXzRange(value: number): boolean {
+  return value >= -MAX_XZ && value <= MAX_XZ;
+}
+
+function isMixPlacement(value: unknown): value is MixPlacement {
+  return (
+    value === "center" ||
+    value === "left" ||
+    value === "right" ||
+    value === "front" ||
+    value === "behind" ||
+    value === "below" ||
+    value === "above"
+  );
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function isShowcaseDemo(value: unknown): value is ShowcaseDemo {
+  return typeof value === "string" && SHOWCASE_DEMOS.has(value);
+}
+
+export function isShowcaseInbound(message: unknown): message is ShowcaseInbound {
+  return parseShowcaseMessage(message) !== null;
+}
+
+export function parseShowcaseMessage(message: unknown): ShowcaseInbound | null {
+  if (!message || typeof message !== "object") {
+    return null;
+  }
+  const record = message as { type?: unknown };
+  if (typeof record.type !== "string") {
+    return null;
+  }
+
+  switch (record.type) {
+    case "join": {
+      const join = message as ShowcaseJoinMessage & { assetOrigin?: unknown };
+      if (!isShowcaseDemo(join.demo)) {
+        return null;
+      }
+      if (
+        join.assetOrigin !== undefined &&
+        typeof join.assetOrigin !== "string"
+      ) {
+        return null;
+      }
+      return {
+        type: "join",
+        demo: join.demo,
+        ...(typeof join.assetOrigin === "string"
+          ? { assetOrigin: join.assetOrigin }
+          : {}),
+      };
+    }
+    case "orbit": {
+      const orbit = message as { action?: unknown };
+      if (orbit.action === "set") {
+        const set = message as ShowcaseOrbitSetMessage;
+        if (
+          set.radius !== undefined &&
+          (!isFiniteNumber(set.radius) || set.radius <= 0)
+        ) {
+          return null;
+        }
+        if (
+          set.periodSec !== undefined &&
+          (!isFiniteNumber(set.periodSec) || set.periodSec <= 0)
+        ) {
+          return null;
+        }
+        if (set.elevation !== undefined && !isFiniteNumber(set.elevation)) {
+          return null;
+        }
+        if (set.paused !== undefined && typeof set.paused !== "boolean") {
+          return null;
+        }
+        return {
+          type: "orbit",
+          action: "set",
+          ...(set.radius !== undefined ? { radius: set.radius } : {}),
+          ...(set.periodSec !== undefined ? { periodSec: set.periodSec } : {}),
+          ...(set.elevation !== undefined ? { elevation: set.elevation } : {}),
+          ...(set.paused !== undefined ? { paused: set.paused } : {}),
+        };
+      }
+      if (orbit.action === "say") {
+        const say = message as ShowcaseOrbitSayMessage;
+        if (
+          typeof say.text !== "string" ||
+          say.text.length === 0 ||
+          say.text.length > MAX_SAY_TEXT_LENGTH
+        ) {
+          return null;
+        }
+        return { type: "orbit", action: "say", text: say.text };
+      }
+      return null;
+    }
+    case "pad": {
+      const pad = message as ShowcasePadMessage;
+      if (!isShowcaseClipId(pad.clipId)) {
+        return null;
+      }
+      if (!isFiniteNumber(pad.x) || !isInXzRange(pad.x)) {
+        return null;
+      }
+      if (!isFiniteNumber(pad.z) || !isInXzRange(pad.z)) {
+        return null;
+      }
+      if (pad.volume !== undefined) {
+        if (!isFiniteNumber(pad.volume)) {
+          return null;
+        }
+      }
+      if (pad.placement !== undefined && !isMixPlacement(pad.placement)) {
+        return null;
+      }
+      return {
+        type: "pad",
+        clipId: pad.clipId,
+        x: pad.x,
+        z: pad.z,
+        ...(pad.volume !== undefined
+          ? { volume: clampVolume(pad.volume) }
+          : {}),
+        ...(pad.placement !== undefined ? { placement: pad.placement } : {}),
+      };
+    }
+    case "pad_stop": {
+      const stop = message as ShowcasePadStopMessage;
+      if (!isNonEmptyString(stop.playId)) {
+        return null;
+      }
+      return { type: "pad_stop", playId: stop.playId.trim() };
+    }
+    case "pad_status": {
+      const status = message as ShowcasePadStatusMessage;
+      if (!isNonEmptyString(status.playId)) {
+        return null;
+      }
+      return { type: "pad_status", playId: status.playId.trim() };
+    }
+    case "move": {
+      const move = message as ShowcaseMoveMessage;
+      if (!isFiniteNumber(move.x) || !isInXzRange(move.x)) {
+        return null;
+      }
+      if (!isFiniteNumber(move.z) || !isInXzRange(move.z)) {
+        return null;
+      }
+      if (move.yawDeg !== undefined && !isFiniteNumber(move.yawDeg)) {
+        return null;
+      }
+      return {
+        type: "move",
+        x: move.x,
+        z: move.z,
+        ...(move.yawDeg !== undefined ? { yawDeg: move.yawDeg } : {}),
+      };
+    }
+    case "mute_peer": {
+      const mute = message as ShowcaseMutePeerMessage;
+      if (!isNonEmptyString(mute.peerId) || typeof mute.muted !== "boolean") {
+        return null;
+      }
+      return {
+        type: "mute_peer",
+        peerId: mute.peerId.trim(),
+        muted: mute.muted,
+      };
+    }
+    case "leave":
+      return { type: "leave" };
+    case "ping":
+      return { type: "ping" };
+    default:
+      return null;
+  }
+}
+
+/** Y-up world pose; forward −Z. Yaw is degrees about Y. */
+export function poseAt(x: number, z: number, yawDeg = 0): MixPose {
+  const yawRad = (yawDeg * Math.PI) / 180;
+  const half = yawRad / 2;
+  return {
+    position: { x, y: 0, z },
+    orientation: {
+      x: 0,
+      y: Math.sin(half),
+      z: 0,
+      w: Math.cos(half),
+    },
+  };
+}

package/templates/spatial-showcase/room.ts

@@ -0,0 +1,80 @@
+export type RoomPeer = {
+  id: string;
+  x: number;
+  z: number;
+  yawDeg: number;
+  muted: boolean;
+};
+
+export const MAX_ROOM_PEERS = 8;
+
+type PeerPose = {
+  x: number;
+  z: number;
+  yawDeg: number;
+};
+
+/** In-memory proximity room — pure TS, no agent runtime imports. */
+export class ProximityRoom {
+  private readonly members = new Map<string, PeerPose>();
+  private readonly listenerMutes = new Map<string, Map<string, boolean>>();
+
+  join(sessionId: string): "ok" | "full" {
+    if (this.members.has(sessionId)) {
+      return "ok";
+    }
+    if (this.members.size >= MAX_ROOM_PEERS) {
+      return "full";
+    }
+    this.members.set(sessionId, { x: 0, z: 0, yawDeg: 0 });
+    return "ok";
+  }
+
+  leave(sessionId: string): void {
+    this.members.delete(sessionId);
+    this.listenerMutes.delete(sessionId);
+    for (const targets of this.listenerMutes.values()) {
+      targets.delete(sessionId);
+    }
+  }
+
+  setPose(sessionId: string, x: number, z: number, yawDeg: number): void {
+    const peer = this.members.get(sessionId);
+    if (!peer) {
+      return;
+    }
+    peer.x = x;
+    peer.z = z;
+    peer.yawDeg = yawDeg;
+  }
+
+  memberIds(): string[] {
+    return [...this.members.keys()];
+  }
+
+  /** Per-listener view — `muted` is whether this listener muted the peer (never true for self). */
+  snapshotFor(listenerId: string): RoomPeer[] {
+    const mutesForListener = this.listenerMutes.get(listenerId);
+    return [...this.members.entries()].map(([id, pose]) => ({
+      id,
+      x: pose.x,
+      z: pose.z,
+      yawDeg: pose.yawDeg,
+      muted: id !== listenerId && mutesForListener?.get(id) === true,
+    }));
+  }
+
+  setPeerMuted(listenerId: string, targetId: string, muted: boolean): void {
+    let targets = this.listenerMutes.get(listenerId);
+    if (!targets) {
+      targets = new Map();
+      this.listenerMutes.set(listenerId, targets);
+    }
+    targets.set(targetId, muted);
+  }
+
+  clear(): void {
+    this.members.clear();
+    this.listenerMutes.clear();
+  }
+}

package/templates/spatial-showcase/sounds.ts

@@ -0,0 +1,68 @@
+/**
+ * Showcase clip catalog — browser sends clipId only; the agent resolves URLs here.
+ *
+ * Production agents receive `assetOrigin` from the browser's `window.location.origin`
+ * (typically https://app.voicethere.io or https://app.voicethere.dev). Local dev may
+ * use http://localhost:3000 — also allowlisted for resolveClipUrl.
+ */
+export type ShowcaseClipId =
+  | "chime"
+  | "bell"
+  | "laser"
+  | "impact"
+  | "footsteps"
+  | "rain-loop"
+  | "cafe-loop"
+  | "jingle";
+
+export type ShowcaseSoundFile = {
+  file: string;
+  loop: boolean;
+  defaultVolume: number;
+};
+
+export const SHOWCASE_SOUND_FILES: Record<ShowcaseClipId, ShowcaseSoundFile> = {
+  chime: { file: "chime.wav", loop: false, defaultVolume: 0.8 },
+  bell: { file: "bell.wav", loop: false, defaultVolume: 0.8 },
+  laser: { file: "laser.wav", loop: false, defaultVolume: 0.7 },
+  impact: { file: "impact.wav", loop: false, defaultVolume: 0.85 },
+  footsteps: { file: "footsteps.wav", loop: false, defaultVolume: 0.75 },
+  "rain-loop": { file: "rain-loop.wav", loop: true, defaultVolume: 0.5 },
+  "cafe-loop": { file: "cafe-loop.wav", loop: true, defaultVolume: 0.5 },
+  jingle: { file: "jingle.wav", loop: false, defaultVolume: 0.8 },
+};
+
+export const SHOWCASE_ASSET_ORIGINS = [
+  "https://app.voicethere.io",
+  "https://app.voicethere.dev",
+  "http://localhost:3000",
+] as const;
+
+const CLIP_IDS = new Set<string>(Object.keys(SHOWCASE_SOUND_FILES));
+
+export function isShowcaseClipId(clipId: string): clipId is ShowcaseClipId {
+  return CLIP_IDS.has(clipId);
+}
+
+function normalizeOrigin(origin: string): string {
+  return origin.replace(/\/+$/, "");
+}
+
+function isAllowedOrigin(origin: string): boolean {
+  const normalized = normalizeOrigin(origin);
+  return SHOWCASE_ASSET_ORIGINS.some(
+    (allowed) => normalizeOrigin(allowed) === normalized,
+  );
+}
+
+/** Resolve a clip URL from an allowlisted asset origin and clipId — never accept arbitrary URLs. */
+export function resolveClipUrl(
+  assetOrigin: string,
+  clipId: string,
+): string | null {
+  if (!isAllowedOrigin(assetOrigin) || !isShowcaseClipId(clipId)) {
+    return null;
+  }
+  const { file } = SHOWCASE_SOUND_FILES[clipId];
+  return `${normalizeOrigin(assetOrigin)}/showcase/sounds/${file}`;
+}