@agent-os-lab/agent-game-sdk 0.1.1 → 0.1.3

package/README.md

@@ -2,13 +2,15 @@
 
 Embeddable agent game views and runtime clients.
 
+For the full integration guide, see [USAGE.md](./USAGE.md).
+
 ## Office View
 
 Framework-neutral mount API:
 
 ```ts
-import { AgentGameRuntimeBrowserClient } from "agent-game-sdk";
-import { mountAgentGameOffice } from "agent-game-sdk/office";
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";
 
 const client = new AgentGameRuntimeBrowserClient({
   baseUrl: "",
@@ -31,8 +33,8 @@ view.destroy();
 React wrapper:
 
 ```tsx
-import { AgentGameRuntimeBrowserClient } from "agent-game-sdk";
-import { AgentGameOfficeView } from "agent-game-sdk/office/react";
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
 
 const client = new AgentGameRuntimeBrowserClient({
   baseUrl: "",
@@ -51,13 +53,13 @@ export function Office() {
 
 `agent-game-sdk/office` is renderer and framework neutral. `agent-game-sdk/office/react` is the React-only entrypoint.
 
-Browser clients should call an application BFF endpoint. Keep the AgentOS service API key on the server:
+Browser clients should call an application BFF endpoint. Keep the AgentOS service API key on the server; the SDK server client forwards it to Agent Game Runtime:
 
 ```ts
-import { AgentGameRuntimeServerClient } from "agent-game-sdk";
+import { AgentGameRuntimeServerClient } from "@agent-os-lab/agent-game-sdk";
 
 const client = new AgentGameRuntimeServerClient({
-  baseUrl: process.env.AGENTOS_BASE_URL!,
+  baseUrl: process.env.AGENT_GAME_RUNTIME_BASE_URL!,
   apiKey: process.env.AGENTOS_API_KEY!,
 });
 
@@ -71,7 +73,7 @@ export async function GET() {
 Run the SDK office view demo:
 
 ```bash
-AGENTOS_BASE_URL=http://localhost:3000 AGENTOS_API_KEY=... bun run demo
+AGENT_GAME_RUNTIME_BASE_URL=http://localhost:3107 AGENTOS_API_KEY=... bun run demo
 ```
 
 Open `http://localhost:7357`. Set `PORT=7358` or another value to change the port.

package/USAGE.md

@@ -0,0 +1,303 @@
+# Agent Game SDK Usage Guide
+
+This document describes how to use `@agent-os-lab/agent-game-sdk` from browser-facing applications and trusted backend services.
+
+## Overview
+
+`@agent-os-lab/agent-game-sdk` provides embeddable agent game views and a browser-safe client for Agent Game Runtime presence streams.
+
+Use it when another application needs to render an AgentOS office view, subscribe to live agent presence, or bridge a trusted backend API key into short-lived runtime tokens for browser clients.
+
+The SDK is intentionally split by responsibility:
+
+- Runtime clients handle token creation and WebSocket subscription.
+- Office view APIs mount a framework-neutral 3D office view into a DOM container.
+- React APIs wrap the same office view for React applications.
+
+## Installation
+
+```bash
+npm install @agent-os-lab/agent-game-sdk
+```
+
+Runtime requirements:
+
+- A modern browser runtime with `fetch`, `Headers`, `Response`, and `WebSocket` for frontend usage.
+- A trusted backend runtime with `fetch` for runtime token proxy endpoints.
+- React 19+ and React DOM 19+ only when using `@agent-os-lab/agent-game-sdk/office/react`.
+
+## Entry Points
+
+```ts
+import {
+  AgentGameRuntimeBrowserClient,
+  AgentGameRuntimeServerClient,
+} from "@agent-os-lab/agent-game-sdk";
+import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";
+import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
+import type { AgentPresence } from "@agent-os-lab/agent-game-sdk/office";
+```
+
+Available entry points:
+
+- `@agent-os-lab/agent-game-sdk`: runtime clients and office exports.
+- `@agent-os-lab/agent-game-sdk/office`: framework-neutral office view APIs and office types.
+- `@agent-os-lab/agent-game-sdk/office/react`: React office view component.
+
+Do not import files from `src/` in application code. Use the published entry points above.
+
+## Authentication Model
+
+Use `AgentGameRuntimeServerClient` only in trusted backend code. It sends the AgentOS service API key as a bearer token to Agent Game Runtime and returns a short-lived runtime token response.
+
+```ts
+import { AgentGameRuntimeServerClient } from "@agent-os-lab/agent-game-sdk";
+
+const serverClient = new AgentGameRuntimeServerClient({
+  baseUrl: process.env.AGENT_GAME_RUNTIME_BASE_URL!,
+  apiKey: process.env.AGENTOS_API_KEY!,
+  requestId: () => crypto.randomUUID(),
+});
+
+export async function GET() {
+  return Response.json(await serverClient.createRuntimeToken());
+}
+```
+
+Do not expose `AGENTOS_API_KEY` or any AgentOS service API key to browser code.
+
+Use `AgentGameRuntimeBrowserClient` in the frontend against a same-origin BFF/proxy endpoint that returns `GameRuntimeTokenResponse`.
+
+```ts
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+
+const browserClient = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+  tokenPath: "/api/agent-game-runtime-token",
+});
+```
+
+If your application backend expects an application-scoped browser token, provide `accessToken`. This token is for your BFF/proxy, not for Agent Game Runtime directly.
+
+```ts
+const browserClient = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+  tokenPath: "/api/agent-game-runtime-token",
+  accessToken: async () => getScopedApplicationToken(),
+});
+```
+
+The browser client strips caller-provided `authorization`, `x-hermes-tenant-id`, and `x-agentos-tenant-id` headers. Only the `accessToken` option may set a browser bearer token.
+
+## Runtime Subscription
+
+Use `subscribe` when the application wants direct access to live runtime messages instead of using the office view.
+
+```ts
+const subscription = await browserClient.subscribe({
+  onSnapshot: (message) => {
+    console.log("snapshot", message.agents);
+  },
+  onPatch: (message) => {
+    console.log("patch", message.agents);
+  },
+  onError: (error) => {
+    console.error("runtime stream error", error);
+  },
+});
+
+subscription.close();
+```
+
+Runtime messages are either:
+
+- `snapshot`: full current presence list for the tenant.
+- `patch`: changed agent presence records.
+
+Use `mergeAgentPresence` when maintaining your own local presence array from snapshots and patches.
+
+```ts
+import { mergeAgentPresence } from "@agent-os-lab/agent-game-sdk";
+
+let agents = [];
+
+await browserClient.subscribe({
+  onSnapshot: (message) => {
+    agents = message.agents;
+  },
+  onPatch: (message) => {
+    agents = mergeAgentPresence(agents, message.agents);
+  },
+});
+```
+
+## Office View
+
+Use `mountAgentGameOffice` for framework-neutral embedding.
+
+```ts
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";
+
+const client = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+  tokenPath: "/api/agent-game-runtime-token",
+});
+
+const view = await mountAgentGameOffice(container, {
+  renderer: "three",
+  source: {
+    type: "runtime",
+    client,
+  },
+});
+
+view.focusAgent("agent-1");
+view.destroy();
+```
+
+`renderer: "three"` is the built-in renderer and the default renderer. The container must have a stable size; the React wrapper supplies a default `minHeight`, but framework-neutral callers should size the container in CSS.
+
+## React Office View
+
+Use `AgentGameOfficeView` when embedding the office view in a React application.
+
+```tsx
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
+
+const client = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+});
+
+export function Office() {
+  return (
+    <AgentGameOfficeView
+      renderer="three"
+      source={{ type: "runtime", client }}
+      focusedAgentId="agent-1"
+      style={{ height: 640 }}
+    />
+  );
+}
+```
+
+Keep `source` object identity stable across renders when possible. Recreating `source` every render can remount the view because the React wrapper treats `options.source` as an effect dependency.
+
+## Snapshot Source
+
+Use `source.type: "snapshot"` for demos, tests, static previews, or applications that already have agent presence data.
+
+```ts
+import { mountAgentGameOffice, type AgentPresence } from "@agent-os-lab/agent-game-sdk/office";
+
+const agents: AgentPresence[] = [
+  {
+    tenantId: "tenant-demo",
+    agentId: "agent-1",
+    displayName: "Research Agent",
+    status: "working",
+    statusSource: "simulation",
+    activity: {
+      kind: "running",
+      summary: "Reading customer notes",
+      updatedAt: new Date().toISOString(),
+    },
+    updatedAt: new Date().toISOString(),
+  },
+];
+
+const view = await mountAgentGameOffice(container, {
+  source: {
+    type: "snapshot",
+    agents,
+  },
+});
+
+view.updateAgents([
+  {
+    ...agents[0],
+    status: "meeting",
+    updatedAt: new Date().toISOString(),
+  },
+]);
+```
+
+`updateAgents` only mutates SDK-managed snapshot sources. Runtime and custom sources own their own updates.
+
+## Custom Source
+
+Use `source.type: "custom"` when another state manager already projects runtime state into office snapshots.
+
+```ts
+import type {
+  AgentGameOfficeSnapshot,
+  AgentGameOfficeSource,
+} from "@agent-os-lab/agent-game-sdk/office";
+
+const source: AgentGameOfficeSource = {
+  subscribe(listener: (snapshot: AgentGameOfficeSnapshot) => void) {
+    const unsubscribe = store.subscribe(() => {
+      listener(store.getState().officeSnapshot);
+    });
+    listener(store.getState().officeSnapshot);
+    return unsubscribe;
+  },
+};
+
+await mountAgentGameOffice(container, {
+  source: {
+    type: "custom",
+    source,
+  },
+});
+```
+
+## Agent Presence Shape
+
+Office rendering is driven by `AgentPresence`.
+
+Important fields:
+
+- `tenantId`: tenant that owns the presence record.
+- `agentId`: stable agent identifier.
+- `displayName`: label shown in the office view.
+- `status`: one of `working`, `thinking`, `meeting`, `resting`, `entertaining`, `idle`, or `offline`.
+- `statusSource`: `runtime`, `simulation`, or `system`.
+- `activity`: optional visible activity summary and preview.
+- `updatedAt`: ISO timestamp for the latest presence update.
+- `expiresAt`: optional ISO timestamp after which the presence should be considered stale by the producer.
+
+## Local Demo
+
+Run the SDK office view demo from `agent-game-sdk`:
+
+```bash
+AGENT_GAME_RUNTIME_BASE_URL=http://localhost:3107 AGENTOS_API_KEY=... bun run demo
+```
+
+Open `http://localhost:7357`.
+
+Set `PORT=7358` or another value to change the port.
+
+## Publish
+
+Publishing is controlled from the SDK package directory. The script bumps the package version, builds the package, runs `npm pack --dry-run`, and then publishes to npm:
+
+```bash
+bun run sdk:publish
+```
+
+The default release is patch. Use `--minor` or `--major` when needed:
+
+```bash
+bun run sdk:publish -- --minor
+```
+
+Use `--dry-run` to validate the next version and package contents without publishing. The script restores the previous version after a dry run.
+
+If npm requires two-factor authentication, pass the one-time password with `--otp`:
+
+```bash
+bun run sdk:publish -- --otp 123456
+```

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "USAGE.md"
   ],
   "exports": {
     ".": "./src/index.ts",
@@ -14,6 +15,7 @@
   "scripts": {
     "build": "tsc --noEmit -p tsconfig.json",
     "demo": "bun --env-file=.env.development --hot demo/server.ts",
+    "demo:stop": "bun scripts/stop-demo.ts",
     "sdk:publish": "bun scripts/publish-agent-game-sdk.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit -p tsconfig.json"

package/src/office/renderers/three/agent-activity-effects.ts

@@ -12,19 +12,12 @@ export type AgentActivityEffectMode =
 
 export type AgentActivityEffects = {
   group: THREE.Group;
-  typingDots: THREE.Mesh[];
-  toolBlock: THREE.Mesh;
-  runningRing: THREE.Mesh;
-  completionRing: THREE.Mesh;
+  typingDots: THREE.Object3D[];
+  toolBlock: THREE.Object3D;
+  runningRing: THREE.Object3D;
+  completionRing: THREE.Object3D;
 };
 
-const typingDotGeometry = new THREE.SphereGeometry(0.055, 12, 8);
-const typingDotMaterial = new THREE.MeshBasicMaterial({ color: 0xe0f2fe });
-const toolBlockGeometry = new THREE.BoxGeometry(0.34, 0.22, 0.08);
-const toolBlockMaterial = new THREE.MeshBasicMaterial({ color: 0x0f172a });
-const ringGeometryCache = new Map<string, THREE.RingGeometry>();
-const ringMaterialCache = new Map<number, THREE.MeshBasicMaterial>();
-
 export function resolveActivityEffectMode(
   agent: Pick<AgentGameOfficeAgent, "activity" | "activityLabel" | "sceneState">,
 ): AgentActivityEffectMode {
@@ -51,26 +44,20 @@ export function resolveActivityEffectMode(
 export function createAgentActivityEffects(): AgentActivityEffects {
   const group = new THREE.Group();
   const typingDots = [0, 1, 2].map((index) => {
-    const dot = new THREE.Mesh(
-      typingDotGeometry,
-      typingDotMaterial,
-    );
+    const dot = new THREE.Object3D();
     dot.position.set(-0.18 + index * 0.18, 1.95, 0.18);
     dot.visible = false;
     group.add(dot);
     return dot;
   });
 
-  const toolBlock = new THREE.Mesh(
-    toolBlockGeometry,
-    toolBlockMaterial,
-  );
+  const toolBlock = new THREE.Object3D();
   toolBlock.position.set(0.48, 1.18, 0.18);
   toolBlock.visible = false;
   group.add(toolBlock);
 
-  const runningRing = createRing(0x38bdf8, 0.48, 0.68);
-  const completionRing = createRing(0x22c55e, 0.58, 0.82);
+  const runningRing = createRing();
+  const completionRing = createRing();
   group.add(runningRing, completionRing);
 
   return { group, typingDots, toolBlock, runningRing, completionRing };
@@ -113,44 +100,14 @@ export function updateAgentActivityEffects(
   }
 }
 
-function createRing(color: number, innerRadius: number, outerRadius: number): THREE.Mesh {
-  const ring = new THREE.Mesh(
-    getRingGeometry(innerRadius, outerRadius),
-    getRingMaterial(color),
-  );
+function createRing(): THREE.Object3D {
+  const ring = new THREE.Object3D();
   ring.rotation.x = -Math.PI / 2;
   ring.position.y = 0.04;
   ring.visible = false;
   return ring;
 }
 
-function getRingGeometry(innerRadius: number, outerRadius: number): THREE.RingGeometry {
-  const key = `${innerRadius}:${outerRadius}`;
-  const cached = ringGeometryCache.get(key);
-  if (cached) {
-    return cached;
-  }
-  const geometry = new THREE.RingGeometry(innerRadius, outerRadius, 32);
-  ringGeometryCache.set(key, geometry);
-  return geometry;
-}
-
-function getRingMaterial(color: number): THREE.MeshBasicMaterial {
-  const cached = ringMaterialCache.get(color);
-  if (cached) {
-    return cached;
-  }
-  const material = new THREE.MeshBasicMaterial({
-    color,
-    transparent: true,
-    opacity: 0.36,
-    side: THREE.DoubleSide,
-    depthWrite: false,
-  });
-  ringMaterialCache.set(color, material);
-  return material;
-}
-
 function hideEffects(effects: AgentActivityEffects): void {
   effects.typingDots.forEach((dot) => {
     dot.visible = false;

package/src/office/renderers/three/agent-body-instancing.ts

@@ -41,7 +41,7 @@ export class AgentBodyInstancedLayer {
       }
       record.mesh.group.updateMatrixWorld(true);
       resolveAgentBodyPartRenderSpecs(record.renderIndex).forEach((part) => {
-        const batch = this.ensureBatch(part, records.length);
+        const batch = this.ensureBatch(part, records.length * 2);
         const object = record.mesh[part.key];
         object.updateMatrixWorld(true);
         matrixHelper.copy(object.matrixWorld);
@@ -68,7 +68,7 @@ export class AgentBodyInstancedLayer {
     part: ReturnType<typeof resolveAgentBodyPartRenderSpecs>[number],
     requiredCapacity: number,
   ): AgentBodyBatch {
-    const key = `${part.key}:${part.width}:${part.height}:${part.depth}:${part.color}`;
+    const key = `${part.width}:${part.height}:${part.depth}:${part.color}`;
     const existing = this.batches.get(key);
     if (existing && existing.capacity >= requiredCapacity) {
       return existing;

package/src/office/renderers/three/agent-effect-instancing.ts

@@ -0,0 +1,134 @@
+import * as THREE from "three";
+
+import type { AgentMeshParts } from "./agent-mesh";
+
+export type AgentEffectInstanceRecord = {
+  mesh: AgentMeshParts;
+  visible: boolean;
+};
+
+type EffectBatch = {
+  mesh: THREE.InstancedMesh;
+  capacity: number;
+  count: number;
+};
+
+const matrixHelper = new THREE.Matrix4();
+
+export class AgentEffectInstancedLayer {
+  private readonly scene: THREE.Scene;
+  private readonly batches = new Map<string, EffectBatch>();
+
+  constructor(scene: THREE.Scene) {
+    this.scene = scene;
+  }
+
+  update(records: AgentEffectInstanceRecord[]): void {
+    this.batches.forEach((batch) => {
+      batch.count = 0;
+      batch.mesh.count = 0;
+    });
+
+    records.forEach((record) => {
+      if (!record.visible) {
+        return;
+      }
+      record.mesh.group.updateMatrixWorld(true);
+      this.addObject("glow", record.mesh.activityGlow, records.length);
+      record.mesh.activityEffects.typingDots.forEach((dot) => {
+        this.addObject("typingDot", dot, records.length * 3);
+      });
+      this.addObject("toolBlock", record.mesh.activityEffects.toolBlock, records.length);
+      this.addObject("runningRing", record.mesh.activityEffects.runningRing, records.length);
+      this.addObject("completionRing", record.mesh.activityEffects.completionRing, records.length);
+    });
+
+    this.batches.forEach((batch) => {
+      batch.mesh.count = batch.count;
+      batch.mesh.visible = batch.count > 0;
+      batch.mesh.instanceMatrix.needsUpdate = true;
+    });
+  }
+
+  dispose(): void {
+    this.batches.forEach((batch) => {
+      this.scene.remove(batch.mesh);
+    });
+    this.batches.clear();
+  }
+
+  private addObject(key: EffectKey, object: THREE.Object3D, capacity: number): void {
+    if (!object.visible) {
+      return;
+    }
+    const batch = this.ensureBatch(key, capacity);
+    object.updateMatrixWorld(true);
+    matrixHelper.copy(object.matrixWorld);
+    batch.mesh.setMatrixAt(batch.count, matrixHelper);
+    batch.count += 1;
+  }
+
+  private ensureBatch(key: EffectKey, requiredCapacity: number): EffectBatch {
+    const existing = this.batches.get(key);
+    if (existing && existing.capacity >= requiredCapacity) {
+      return existing;
+    }
+    if (existing) {
+      this.scene.remove(existing.mesh);
+    }
+
+    const spec = effectSpecs[key];
+    const mesh = new THREE.InstancedMesh(
+      spec.geometry,
+      spec.material,
+      Math.max(requiredCapacity, 1),
+    );
+    mesh.castShadow = false;
+    mesh.receiveShadow = false;
+    mesh.name = `agentEffect:${key}`;
+    this.scene.add(mesh);
+
+    const batch = { mesh, capacity: Math.max(requiredCapacity, 1), count: 0 };
+    this.batches.set(key, batch);
+    return batch;
+  }
+}
+
+export function createAgentEffectInstancedLayer(scene: THREE.Scene): AgentEffectInstancedLayer {
+  return new AgentEffectInstancedLayer(scene);
+}
+
+type EffectKey = "glow" | "typingDot" | "toolBlock" | "runningRing" | "completionRing";
+
+const effectSpecs: Record<EffectKey, { geometry: THREE.BufferGeometry; material: THREE.Material }> = {
+  glow: {
+    geometry: new THREE.RingGeometry(0.56, 0.92, 32),
+    material: createTransparentMaterial(0x38bdf8, 0.35),
+  },
+  typingDot: {
+    geometry: new THREE.SphereGeometry(0.055, 12, 8),
+    material: new THREE.MeshBasicMaterial({ color: 0xe0f2fe }),
+  },
+  toolBlock: {
+    geometry: new THREE.BoxGeometry(0.34, 0.22, 0.08),
+    material: new THREE.MeshBasicMaterial({ color: 0x0f172a }),
+  },
+  runningRing: {
+    geometry: new THREE.RingGeometry(0.48, 0.68, 32),
+    material: createTransparentMaterial(0x38bdf8, 0.36),
+  },
+  completionRing: {
+    geometry: new THREE.RingGeometry(0.58, 0.82, 32),
+    material: createTransparentMaterial(0x22c55e, 0.36),
+  },
+};
+
+function createTransparentMaterial(color: number, opacity: number): THREE.MeshBasicMaterial {
+  return new THREE.MeshBasicMaterial({
+    color,
+    transparent: true,
+    opacity,
+    side: THREE.DoubleSide,
+    depthWrite: false,
+  });
+}

package/src/office/renderers/three/agent-mesh.ts

@@ -21,23 +21,14 @@ export type AgentMeshParts = {
   rightLeg: THREE.Object3D;
   leftFoot: THREE.Object3D;
   rightFoot: THREE.Object3D;
-  activityGlow: THREE.Mesh;
+  activityGlow: THREE.Object3D;
   activityEffects: AgentActivityEffects;
 };
 
-const agentColors = [0x2563eb, 0xdc2626, 0x059669, 0xd97706, 0x7c3aed, 0x0891b2];
-const skinColors = [0xffdbac, 0xf5cba7, 0xd4a574, 0xc68642];
-const hairColors = [0x3f2a1d, 0x111827, 0x7c2d12, 0x4b5563];
+const agentColors = [0x2563eb, 0xdc2626, 0x059669];
+const skinColors = [0xffdbac, 0xd4a574];
+const hairColors = [0x3f2a1d, 0x111827];
 export const AGENT_MESH_SCALE = 1.15;
-const activityGlowGeometry = new THREE.RingGeometry(0.56, 0.92, 32);
-const activityGlowMaterial = new THREE.MeshBasicMaterial({
-  color: 0x38bdf8,
-  transparent: true,
-  opacity: 0.35,
-  side: THREE.DoubleSide,
-  depthWrite: false,
-});
-
 export type AgentBodyPartKey =
   | "body"
   | "leftLeg"
@@ -133,11 +124,8 @@ function addPart(
   return part;
 }
 
-function createActivityGlow(): THREE.Mesh {
-  const glow = new THREE.Mesh(
-    activityGlowGeometry,
-    activityGlowMaterial,
-  );
+function createActivityGlow(): THREE.Object3D {
+  const glow = new THREE.Object3D();
   glow.rotation.x = -Math.PI / 2;
   glow.position.y = 0.03;
   glow.visible = false;

package/src/office/renderers/three/mount.ts

@@ -9,6 +9,7 @@ import type {
 } from "../../core/types";
 import { applyAgentPose, updateAgentMotion } from "./agent-animation";
 import { createAgentBodyInstancedLayer } from "./agent-body-instancing";
+import { createAgentEffectInstancedLayer } from "./agent-effect-instancing";
 import { resolveAgentFacingTarget, resolveAgentPosition } from "./agent-layout";
 import {
   type AgentLabelRecord,
@@ -113,6 +114,7 @@ export function mountThreeAgentGameOffice(
   addLights(scene);
   buildOfficeScene(scene);
   const agentBodyLayer = createAgentBodyInstancedLayer(scene);
+  const agentEffectLayer = createAgentEffectInstancedLayer(scene);
 
   const agents = new Map<string, AgentMeshRecord>();
   let frameId = 0;
@@ -193,6 +195,10 @@ export function mountThreeAgentGameOffice(
       renderIndex: record.renderIndex,
       visible: record.agent.sceneState !== "offline",
     })));
+    agentEffectLayer.update(Array.from(agents.values()).map((record) => ({
+      mesh: record.mesh,
+      visible: record.agent.sceneState !== "offline",
+    })));
     renderer.render(scene, camera);
     labelsDirty = false;
     frameId = requestAnimationFrame(animate);
@@ -245,6 +251,7 @@ export function mountThreeAgentGameOffice(
       });
       agents.clear();
       agentBodyLayer.dispose();
+      agentEffectLayer.dispose();
       disposeObject(scene);
       renderer.dispose();
       root.remove();

package/src/runtime-client.ts

@@ -158,7 +158,7 @@ export class AgentGameRuntimeBrowserClient {
       signal: options.signal,
     });
     if (!response.ok) {
-      throw new Error(`Game runtime token request failed with status ${response.status}.`);
+      throw new Error(await formatGameRuntimeTokenRequestError(response));
     }
     const body = await response.json() as GameRuntimeTokenResponse;
     if (!isGameRuntimeTokenResponse(body)) {
@@ -217,7 +217,7 @@ export class AgentGameRuntimeServerClient {
       signal: options.signal,
     });
     if (!response.ok) {
-      throw new Error(`Game runtime token request failed with status ${response.status}.`);
+      throw new Error(await formatGameRuntimeTokenRequestError(response));
     }
     const body = await response.json() as GameRuntimeTokenResponse;
     if (!isGameRuntimeTokenResponse(body)) {
@@ -377,6 +377,31 @@ function boundFetch(): typeof fetch {
   return globalThis.fetch.bind(globalThis);
 }
 
+async function formatGameRuntimeTokenRequestError(response: Response): Promise<string> {
+  const detail = await readErrorDetail(response);
+  return `Game runtime token request failed with status ${response.status}${detail ? `: ${detail}` : ""}.`;
+}
+
+async function readErrorDetail(response: Response): Promise<string> {
+  try {
+    const body = await response.clone().json() as unknown;
+    if (!body || typeof body !== "object") {
+      return "";
+    }
+    const error = (body as { error?: unknown }).error;
+    if (typeof error === "string") {
+      return error;
+    }
+    if (error && typeof error === "object") {
+      const message = (error as { message?: unknown }).message;
+      return typeof message === "string" ? message : "";
+    }
+  } catch {
+    return "";
+  }
+  return "";
+}
+
 function resolveHeaders(
   value: AgentGameRuntimeBrowserClientOptions["headers"] | AgentGameRuntimeServerClientOptions["headers"],
 ): HeadersInit | undefined {