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

package/README.md

@@ -51,13 +51,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";
 
 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 +71,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "files": [
     "src",
@@ -14,6 +14,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 {