@voicethere/agent 0.2.0 → 0.2.2

package/README.md

@@ -104,7 +104,9 @@ From `agent/`:
 ```bash
 npm install
 npm run live-test:models   # select/download sherpa models and export env values
-npm run live-test:stack
+npm run live-test:stack:echo  # voice echo template
+# or
+npm run live-test:stack:game  # data-only game-sync template
 ```
 
 This starts the local starter with your sandboxed bundle and serves the page.
@@ -204,7 +206,7 @@ The runtime processes parent IPC **in order per `sessionId`** while different se
 
 For isolated voice agents (default), leave **`shared_child_per_session`** disabled — each session gets its own child process.
 
-See [`templates/game-sync.ts`](./templates/game-sync.ts) for a data-only authoritative server example.
+See [`templates/game-sync.ts`](./templates/game-sync.ts) for a data-only authoritative server example (60Hz server-side movement + collisions, client render-only).
 
 ## Building your agent bundle
 

package/dist/agent.js

@@ -20,9 +20,15 @@ var SessionSerialQueue = class {
   clearAll() {
     this.tails.clear();
   }
+  hasPending(sessionId) {
+    return this.tails.has(sessionId);
+  }
 };
 
 // src/runtime.ts
+var SESSION_START_INIT_DELAY_ENABLED_ENV = "AGENT_SESSION_START_INIT_DELAY_ENABLED";
+var SESSION_START_INIT_DELAY_MS_ENV = "AGENT_SESSION_START_INIT_DELAY_MS";
+var DEFAULT_SESSION_START_INIT_DELAY_MS = 500;
 function isParentMessage(value) {
   if (!value || typeof value !== "object") return false;
   const msg = value;
@@ -38,11 +44,42 @@ function parseDataChannelPayload(raw) {
 var peerEnvBySessionId = /* @__PURE__ */ new Map();
 var endedSessionIds = /* @__PURE__ */ new Set();
 var agentLogSessionContext = new AsyncLocalStorage();
+function parseBooleanEnv(value, defaultValue) {
+  if (value === void 0) return defaultValue;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "") return defaultValue;
+  if (["0", "false", "off", "no"].includes(normalized)) return false;
+  if (["1", "true", "on", "yes"].includes(normalized)) return true;
+  return defaultValue;
+}
+function parseNonNegativeIntegerEnv(value, defaultValue) {
+  if (value === void 0) return defaultValue;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return defaultValue;
+  return Math.floor(parsed);
+}
+function resolveSessionStartInitDelayMs() {
+  const enabled = parseBooleanEnv(
+    process.env[SESSION_START_INIT_DELAY_ENABLED_ENV],
+    true
+  );
+  if (!enabled) return 0;
+  return parseNonNegativeIntegerEnv(
+    process.env[SESSION_START_INIT_DELAY_MS_ENV],
+    DEFAULT_SESSION_START_INIT_DELAY_MS
+  );
+}
 async function handleParentMessage(message, handlers) {
   switch (message.type) {
     case "session_start":
       endedSessionIds.delete(message.sessionId);
       peerEnvBySessionId.set(message.sessionId, message.env);
+      const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
+      if (sessionStartInitDelayMs > 0) {
+        await new Promise(
+          (resolve) => setTimeout(resolve, sessionStartInitDelayMs)
+        );
+      }
       await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
         sessionId: message.sessionId,
         env: message.env

package/dist/runner.d.ts

@@ -1,3 +1,4 @@
 export { buildChildExecArgv, collectAllowFsReadDirs, } from "./sandbox/sandbox.js";
 export { resolveBundlePath, startSandboxedChild, type SandboxedChild, type StartSandboxedChildOptions, } from "./sandbox/start-child.js";
+export { SessionSerialQueue } from "./session-serial-queue.js";
 //# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,0BAA0B,GAChC,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,0BAA0B,GAChC,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/runner.js

@@ -1,3 +1,4 @@
 export { buildChildExecArgv, collectAllowFsReadDirs, } from "./sandbox/sandbox.js";
 export { resolveBundlePath, startSandboxedChild, } from "./sandbox/start-child.js";
+export { SessionSerialQueue } from "./session-serial-queue.js";
 //# sourceMappingURL=runner.js.map

package/dist/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,iBAAiB,EACjB,mBAAmB,GAGpB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/runtime.d.ts

@@ -1,5 +1,7 @@
 import type { SpeechEvent } from "@node-webrtc-rust/sdk/voice";
 import type { DataChannelKind } from "./protocol.js";
+export declare const SESSION_START_INIT_DELAY_ENABLED_ENV = "AGENT_SESSION_START_INIT_DELAY_ENABLED";
+export declare const SESSION_START_INIT_DELAY_MS_ENV = "AGENT_SESSION_START_INIT_DELAY_MS";
 export interface SessionContext {
     sessionId: string;
     env: Record<string, string>;
@@ -81,6 +83,15 @@ export declare function speak(sessionId: string, text: string): void;
 export declare function sendToClient(sessionId: string, payload: unknown): void;
 /** Send raw bytes to the browser peer via the runner parent. */
 export declare function sendBinaryToClient(sessionId: string, data: Buffer | Uint8Array, channel?: DataChannelKind): void;
+/**
+ * Broadcasts binary data to specified clients over a specific data channel.
+ *
+ * @param data The binary data to be sent, either as a Buffer or Uint8Array.
+ * @param sessionIds An array of session IDs representing the target clients.
+ * @param channel The data channel over which the binary data is sent. Defaults to "sync".
+ * @return void
+ */
+export declare function broadCastBinaryToClients(data: Buffer | Uint8Array, sessionIds: readonly string[], channel?: DataChannelKind): void;
 /** Send the same JSON payload to one or more browser peers. */
 export declare function broadcastToClients(payload: unknown, sessionIds: readonly string[]): void;
 /** Structured log forwarded to the runner parent (includes session when in a handler). */

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/runtime.js

@@ -1,5 +1,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { SessionSerialQueue } from "./session-serial-queue.js";
+export const SESSION_START_INIT_DELAY_ENABLED_ENV = "AGENT_SESSION_START_INIT_DELAY_ENABLED";
+export const SESSION_START_INIT_DELAY_MS_ENV = "AGENT_SESSION_START_INIT_DELAY_MS";
+const DEFAULT_SESSION_START_INIT_DELAY_MS = 500;
 function isParentMessage(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -24,11 +27,41 @@ const peerEnvBySessionId = new Map();
 const endedSessionIds = new Set();
 /** Active orchestrator session while a parent IPC handler runs (per-session queue). */
 const agentLogSessionContext = new AsyncLocalStorage();
+function parseBooleanEnv(value, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "")
+        return defaultValue;
+    if (["0", "false", "off", "no"].includes(normalized))
+        return false;
+    if (["1", "true", "on", "yes"].includes(normalized))
+        return true;
+    return defaultValue;
+}
+function parseNonNegativeIntegerEnv(value, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return defaultValue;
+    return Math.floor(parsed);
+}
+function resolveSessionStartInitDelayMs() {
+    const enabled = parseBooleanEnv(process.env[SESSION_START_INIT_DELAY_ENABLED_ENV], true);
+    if (!enabled)
+        return 0;
+    return parseNonNegativeIntegerEnv(process.env[SESSION_START_INIT_DELAY_MS_ENV], DEFAULT_SESSION_START_INIT_DELAY_MS);
+}
 async function handleParentMessage(message, handlers) {
     switch (message.type) {
         case "session_start":
             endedSessionIds.delete(message.sessionId);
             peerEnvBySessionId.set(message.sessionId, message.env);
+            const sessionStartInitDelayMs = resolveSessionStartInitDelayMs();
+            if (sessionStartInitDelayMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, sessionStartInitDelayMs));
+            }
             await (handlers.onClientJoin ?? handlers.onSessionStart)?.({
                 sessionId: message.sessionId,
                 env: message.env,
@@ -163,8 +196,7 @@ async function runIdleTimeoutHook(handlers, message) {
         await handlers.onIdleTimeout?.(ctx);
     }
     catch (hookError) {
-        error =
-            hookError instanceof Error ? hookError.message : String(hookError);
+        error = hookError instanceof Error ? hookError.message : String(hookError);
         agentLog("error", `onIdleTimeout failed: ${error}`, message.sessionId);
     }
     process.send?.({
@@ -208,6 +240,25 @@ export function sendBinaryToClient(sessionId, data, channel = "sync") {
         channel,
     });
 }
+/**
+ * Broadcasts binary data to specified clients over a specific data channel.
+ *
+ * @param data The binary data to be sent, either as a Buffer or Uint8Array.
+ * @param sessionIds An array of session IDs representing the target clients.
+ * @param channel The data channel over which the binary data is sent. Defaults to "sync".
+ * @return void
+ */
+export function broadCastBinaryToClients(data, sessionIds, channel = "sync") {
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    for (const sessionId of sessionIds) {
+        process.send?.({
+            type: "send_binary_to_client",
+            sessionId,
+            data: buffer,
+            channel,
+        });
+    }
+}
 /** Send the same JSON payload to one or more browser peers. */
 export function broadcastToClients(payload, sessionIds) {
     for (const sessionId of sessionIds) {

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"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"}

package/dist/session-serial-queue.d.ts

@@ -7,5 +7,6 @@ export declare class SessionSerialQueue {
     enqueue(sessionId: string, task: () => void | Promise<void>): void;
     clear(sessionId: string): void;
     clearAll(): void;
+    hasPending(sessionId: string): boolean;
 }
 //# sourceMappingURL=session-serial-queue.d.ts.map

package/dist/session-serial-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-serial-queue.d.ts","sourceRoot":"","sources":["../src/session-serial-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAE1D,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAYlE,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,QAAQ,IAAI,IAAI;CAGjB"}
+{"version":3,"file":"session-serial-queue.d.ts","sourceRoot":"","sources":["../src/session-serial-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAE1D,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAYlE,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI9B,QAAQ,IAAI,IAAI;IAIhB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CAGvC"}

package/dist/session-serial-queue.js

@@ -20,5 +20,8 @@ export class SessionSerialQueue {
     clearAll() {
         this.tails.clear();
     }
+    hasPending(sessionId) {
+        return this.tails.has(sessionId);
+    }
 }
 //# sourceMappingURL=session-serial-queue.js.map

package/dist/session-serial-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-serial-queue.js","sourceRoot":"","sources":["../src/session-serial-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACZ,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE1D,OAAO,CAAC,SAAiB,EAAE,IAAgC;QACzD,MAAM,QAAQ,GACZ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACzE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YAChC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,OAAO,EAAE,CAAC;gBAC1C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAED,QAAQ;QACN,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}
+{"version":3,"file":"session-serial-queue.js","sourceRoot":"","sources":["../src/session-serial-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IACZ,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE1D,OAAO,CAAC,SAAiB,EAAE,IAAgC;QACzD,MAAM,QAAQ,GACZ,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACzE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE;YAChC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,OAAO,EAAE,CAAC;gBAC1C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,SAAiB;QACrB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC/B,CAAC;IAED,QAAQ;QACN,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,UAAU,CAAC,SAAiB;QAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voicethere/agent",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "VoiceThere customer agent SDK — IPC types and runtime helpers for sandboxed child bundles",
   "type": "module",
   "exports": {
@@ -42,7 +42,9 @@
     "live-test:models": "bash ./scripts/select-sherpa-models.sh",
     "live-test:page": "bash ./scripts/live-test-page.sh",
     "live-test:starter": "bash ./scripts/live-test-starter.sh",
-    "live-test:stack": "bash ./scripts/live-test-stack.sh",
+    "live-test:stack": "npm run live-test:stack:echo",
+    "live-test:stack:echo": "LIVE_TEST_AGENT_ENTRY=examples/agent.ts LIVE_TEST_PAGE_PATH=/examples/live-test/index.html LIVE_TEST_SESSION_MODE=voice bash ./scripts/live-test-stack.sh",
+    "live-test:stack:game": "LIVE_TEST_AGENT_ENTRY=templates/game-sync.ts LIVE_TEST_PAGE_PATH=/examples/live-test/game-sync.html LIVE_TEST_SESSION_MODE=data-only bash ./scripts/live-test-stack.sh",
     "prepublishOnly": "npm run build"
   },
   "repository": {

package/templates/README.md

@@ -46,3 +46,21 @@ npx @voicethere/agent verify
 ```
 
 **Voice E2E:** host with the VoiceThere agent runner (platform or internal deployment) — set `AGENT_BUNDLE_PATH` to your built `dist/agent.js`.
+
+## `game-sync.ts`
+
+Authoritative multi-object sync sample for real-time games/simulations:
+
+- register tracked objects via control DC (`{ type: "register" }`)
+- receive `register_ack` + `object_registered` ownership notifications
+- run server-authoritative simulation (position + velocity) at 60Hz
+- resolve wall bounce + object-object collisions on the server
+- broadcast world-state snapshots to clients over binary sync channel (9-float records)
+- ignore client binary writes by default (safe base for adding intent/input messages later)
+- reuse freed slots on leave to keep world state compact
+
+Build:
+
+```bash
+npx @voicethere/agent build --entry templates/game-sync.ts
+```

package/templates/game-sync.ts

@@ -1,68 +1,394 @@
 /**
- * Authoritative tick counter — shared child broadcasts `{ type: 'state', tick, players }`.
+ * Multiplayer object-sync template with ownership checks.
+ *
+ * World layout:
+ * - one global Float32Array
+ * - each tracked object uses exactly 9 floats:
+ *   [objectId, posX, posY, posZ, posW, dirX, dirY, dirZ, dirW]
+ *
+ * Control messages:
+ * - `{ type: "register" }` -> allocates (or reuses) one 9-float slot
+ * - server replies `{ type: "register_ack", objectId }`
+ *
+ * Simulation:
+ * - server-authoritative movement at 60Hz
+ * - wall bounce + object-object elastic collisions on server
+ * - clients render server snapshots; client binary writes are ignored
+ *
+ * Broadcast:
+ * - 60Hz world-state broadcast starts when at least 1 client is connected
+ * - stops when connected client count drops below 1
  *
  * Build:
  *   npx @voicethere/agent build --entry templates/game-sync.ts
  */
 import {
-  agentLog,
-  broadcastToClients,
-  defineAgent,
-  sendToClient,
-  type DataChannelContext,
+    agentLog,
+    defineAgent,
+    sendBinaryToClient,
+    sendToClient,
 } from "@voicethere/agent";
 
-let tick = 0;
-const connected = new Set<string>();
+const OBJECT_STRIDE = 9;
+const BROADCAST_HZ = 60;
+const BROADCAST_INTERVAL_MS = Math.floor(1000 / BROADCAST_HZ);
+const BOARD_WIDTH = 1280;
+const BOARD_HEIGHT = 720;
+const OBJECT_RADIUS = 25;
+const MIN_SPEED = 90;
+const MAX_SPEED = 180;
+const COLLISION_RESTITUTION = 1.0;
+
+const connectedSessions = new Set<string>();
+const objectOwners = new Map<number, string>(); // objectId -> sessionId
+const sessionObjects = new Map<string, Set<number>>(); // sessionId -> owned objectIds
+// Slots we can recycle. Keeping a free-list avoids unbounded array growth when
+// clients churn (join/leave repeatedly).
+const freeSlots: number[] = [];
+
+let worldState = new Float32Array(0);
+let broadcastTimer: NodeJS.Timeout | null = null;
+
+interface TrackedObjectInfo {
+    objectId: number;
+    ownerSessionId: string;
+}
+
+function rand(min: number, max: number): number {
+    return min + Math.random() * (max - min);
+}
+
+function randomVelocity(): number {
+    return (Math.random() < 0.5 ? -1 : 1) * rand(MIN_SPEED, MAX_SPEED);
+}
+
+function slotToObjectId(slot: number): number {
+    // Object ids are 1-based so 0 can represent "unused".
+    return slot + 1;
+}
 
-function playerCount(): number {
-  return connected.size;
+function objectIdToSlot(objectId: number): number {
+    // Inverse of slotToObjectId().
+    return objectId - 1;
 }
 
-function broadcastState(excludeSessionId?: string): void {
-  const payload = { type: "state" as const, tick, players: playerCount() };
-  const targets = excludeSessionId
-    ? [...connected].filter((id) => id !== excludeSessionId)
-    : [...connected];
-  broadcastToClients(payload, targets);
+function markSlotFree(slot: number): void {
+    // Zero the entire record. Slot is still allocated in array length terms,
+    // but logically available for reuse.
+    const start = slot * OBJECT_STRIDE;
+    for (let i = 0; i < OBJECT_STRIDE; i += 1) {
+        worldState[start + i] = 0;
+    }
 }
 
-function handleTickMessage(ctx: DataChannelContext): void {
-  const message = ctx.message;
-  if (!message || typeof message !== "object") return;
-  const record = message as { type?: string };
-  if (record.type !== "tick") return;
-  tick += 1;
-  agentLog(
-    "info",
-    `tick=${tick} players=${playerCount()} from=${ctx.sessionId}`,
-  );
-  broadcastToClients({ type: "state", tick, players: playerCount() }, [
-    ...connected,
-  ]);
+function allocateSlot(): number {
+    // Prefer recycling old slots before growing worldState.
+    const reused = freeSlots.shift();
+    if (reused !== undefined) return reused;
+
+    // Grow by exactly one object record (9 floats).
+    const next = new Float32Array(worldState.length + OBJECT_STRIDE);
+    next.set(worldState);
+    worldState = next;
+    return worldState.length / OBJECT_STRIDE - 1;
+}
+
+function attachObjectToSession(sessionId: string, objectId: number): void {
+    // Tracks ownership in both directions so validation and cleanup are O(1).
+    let owned = sessionObjects.get(sessionId);
+    if (!owned) {
+        owned = new Set<number>();
+        sessionObjects.set(sessionId, owned);
+    }
+    owned.add(objectId);
+    objectOwners.set(objectId, sessionId);
+}
+
+function releaseObject(objectId: number): void {
+    // Remove reverse-ownership references first.
+    const owner = objectOwners.get(objectId);
+    if (owner) {
+        const owned = sessionObjects.get(owner);
+        owned?.delete(objectId);
+        if (owned && owned.size === 0) {
+            sessionObjects.delete(owner);
+        }
+    }
+
+    objectOwners.delete(objectId);
+
+    const slot = objectIdToSlot(objectId);
+    if (slot < 0) return;
+    if (slot >= worldState.length / OBJECT_STRIDE) return;
+
+    // Free slot contents and push slot into free-list for future register() calls.
+    markSlotFree(slot);
+    if (!freeSlots.includes(slot)) {
+        freeSlots.push(slot);
+        freeSlots.sort((a, b) => a - b);
+    }
+}
+
+function registerObject(sessionId: string): number {
+    // Allocate (or reuse) one slot and stamp object id plus initial state.
+    const slot = allocateSlot();
+    const objectId = slotToObjectId(slot);
+    const start = slot * OBJECT_STRIDE;
+    worldState[start] = objectId;
+    worldState[start + 1] = rand(OBJECT_RADIUS, BOARD_WIDTH - OBJECT_RADIUS);
+    worldState[start + 2] = rand(OBJECT_RADIUS, BOARD_HEIGHT - OBJECT_RADIUS);
+    worldState[start + 3] = 0;
+    worldState[start + 4] = 1;
+    worldState[start + 5] = randomVelocity();
+    worldState[start + 6] = randomVelocity();
+    worldState[start + 7] = 0;
+    worldState[start + 8] = 0;
+    attachObjectToSession(sessionId, objectId);
+    return objectId;
+}
+
+function parseRegisterCommand(message: unknown): boolean {
+    if (!message || typeof message !== "object") return false;
+    const record = message as { type?: unknown };
+    return record.type === "register";
+}
+
+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};
+}
+
+function trackedObjectsSnapshot(): TrackedObjectInfo[] {
+    const objects: TrackedObjectInfo[] = [];
+    for (const [objectId, ownerSessionId] of objectOwners) {
+        objects.push({objectId, ownerSessionId});
+    }
+    objects.sort((a, b) => a.objectId - b.objectId);
+    return objects;
+}
+
+function notifyObjectRegistered(objectId: number, ownerSessionId: string): void {
+    for (const sessionId of connectedSessions) {
+        if (sessionId === ownerSessionId) continue;
+        sendToClient(sessionId, {
+            type: "object_registered",
+            objectId,
+            ownerSessionId,
+        });
+    }
+}
+
+function notifyObjectReleased(objectId: number, ownerSessionId: string): void {
+    for (const sessionId of connectedSessions) {
+        if (sessionId === ownerSessionId) continue;
+        sendToClient(sessionId, {
+            type: "object_released",
+            objectId,
+            ownerSessionId,
+        });
+    }
+}
+
+function broadcastWorldState(): void {
+    if (connectedSessions.size === 0) return;
+    // Copy to a detached buffer so downstream sends cannot observe mutations
+    // from subsequent writes in the same event loop tick.
+    const payload = Buffer.from(worldState.buffer.slice(0));
+    for (const sessionId of connectedSessions) {
+        sendBinaryToClient(sessionId, payload, "sync");
+    }
+}
+
+function simulateWorldStep(dtSec: number): void {
+    const activeObjectIds = [...objectOwners.keys()];
+    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) {
+                // Deterministic fallback axis when centers overlap exactly.
+                dx = 1;
+                dy = 0;
+                dist = 1;
+                distSq = 1;
+            }
+            const nx = dx / dist;
+            const ny = dy / dist;
+
+            // Positional correction prevents objects from remaining overlapped.
+            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;
+        }
+    }
+}
+
+function startBroadcastLoopIfNeeded(): void {
+    if (broadcastTimer) return;
+    if (connectedSessions.size < 1) return;
+
+    broadcastTimer = setInterval(() => {
+        if (connectedSessions.size < 1) {
+            if (broadcastTimer) {
+                clearInterval(broadcastTimer);
+                broadcastTimer = null;
+            }
+            return;
+        }
+        simulateWorldStep(1 / BROADCAST_HZ);
+        broadcastWorldState();
+    }, BROADCAST_INTERVAL_MS);
+
+    agentLog("info", `world loop started (${BROADCAST_HZ}Hz)`);
+}
+
+function stopBroadcastLoopIfNeeded(): void {
+    if (connectedSessions.size >= 1) return;
+    if (!broadcastTimer) return;
+    clearInterval(broadcastTimer);
+    broadcastTimer = null;
+    agentLog("info", "world loop stopped");
 }
 
 defineAgent({
-  onClientJoin({ sessionId }) {
-    connected.add(sessionId);
-    sendToClient(sessionId, {
-      type: "state",
-      tick,
-      players: playerCount(),
-    });
-    broadcastState(sessionId);
-    agentLog("info", `join ${sessionId} players=${playerCount()}`);
-  },
-
-  onClientLeave({ sessionId }) {
-    connected.delete(sessionId);
-    broadcastToClients({ type: "state", tick, players: playerCount() }, [
-      ...connected,
-    ]);
-    agentLog("info", `leave ${sessionId} players=${playerCount()}`);
-  },
-
-  onDataChannelMessage(ctx) {
-    handleTickMessage(ctx);
-  },
+    onClientJoin({sessionId}) {
+        connectedSessions.add(sessionId);
+        startBroadcastLoopIfNeeded();
+        // New client receives the current ownership map so it can assign stable
+        // colors per owner and immediately render known tracked objects.
+        sendToClient(sessionId, {
+            type: "world_snapshot",
+            objects: trackedObjectsSnapshot(),
+        });
+        agentLog("info", `join ${sessionId} connected=${connectedSessions.size}`);
+    },
+
+    onClientLeave({sessionId}) {
+        connectedSessions.delete(sessionId);
+
+        const owned = sessionObjects.get(sessionId);
+        if (owned) {
+            for (const objectId of [...owned]) {
+                notifyObjectReleased(objectId, sessionId);
+                releaseObject(objectId);
+            }
+            sessionObjects.delete(sessionId);
+        }
+
+        stopBroadcastLoopIfNeeded();
+        agentLog(
+            "info",
+            `leave ${sessionId} connected=${connectedSessions.size} worldFloats=${worldState.length} freeSlots=${freeSlots.length}`,
+        );
+    },
+
+    onDataChannelMessage(ctx) {
+        // Register is a control-plane message over JSON data channel.
+        // Binary channel is reserved for high-frequency state deltas.
+        if (parseRegisterCommand(ctx.message)) {
+            const objectId = registerObject(ctx.sessionId);
+            sendToClient(ctx.sessionId, {type: "register_ack", objectId});
+            notifyObjectRegistered(objectId, ctx.sessionId);
+            agentLog("info", `register session=${ctx.sessionId} objectId=${objectId}`);
+            return;
+        }
+
+        // Optional chat mode for debugging/coordinating live test sessions.
+        const chat = parseChatCommand(ctx.message);
+        if (!chat) return;
+        for (const sessionId of connectedSessions) {
+            sendToClient(sessionId, {
+                type: "chat_broadcast",
+                senderSessionId: ctx.sessionId,
+                text: chat.text,
+            });
+        }
+    },
+
+    onDataChannelBinary(ctx) {
+        // Server-authoritative simulation: ignore client binary state writes.
+        // Keeping the hook makes intent-based controls easy to add later.
+        void ctx;
+    },
 });