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

package/README.md

@@ -20,6 +20,13 @@ const client = new AgentGameRuntimeBrowserClient({
 
 const view = await mountAgentGameOffice(container, {
   renderer: "three",
+  office: {
+    rooms: [
+      { type: "office" },
+      { type: "auditorium", capacity: 40 },
+      { type: "gym" },
+    ],
+  },
   source: {
     type: "runtime",
     client,
@@ -27,13 +34,16 @@ const view = await mountAgentGameOffice(container, {
 });
 
 view.focusAgent("agent-1");
+view.refreshAgents();
 view.destroy();
 ```
 
 React wrapper:
 
 ```tsx
+import { useState } from "react";
 import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import type { AgentGameOfficeController } from "@agent-os-lab/agent-game-sdk/office";
 import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
 
 const client = new AgentGameRuntimeBrowserClient({
@@ -41,18 +51,36 @@ const client = new AgentGameRuntimeBrowserClient({
 });
 
 export function Office() {
+  const [view, setView] = useState<AgentGameOfficeController | null>(null);
+
   return (
-    <AgentGameOfficeView
-      renderer="three"
-      source={{ type: "runtime", client }}
-      style={{ height: 640 }}
-    />
+    <>
+      <button type="button" onClick={() => view?.refreshAgents()}>
+        Refresh agents
+      </button>
+      <AgentGameOfficeView
+        renderer="three"
+        office={{
+          rooms: [
+            { type: "office" },
+            { type: "auditorium" },
+            { type: "gym" },
+          ],
+        }}
+        source={{ type: "runtime", client }}
+        style={{ height: 640 }}
+        onReady={setView}
+        onDestroy={() => setView(null)}
+      />
+    </>
   );
 }
 ```
 
 `agent-game-sdk/office` is renderer and framework neutral. `agent-game-sdk/office/react` is the React-only entrypoint.
 
+The built-in 3D renderer supports semantic room configuration. If `office` is omitted, the SDK renders the default `office + auditorium + gym` layout. Consumers choose room types and optional capacity; component coordinates and Three.js objects stay internal to the SDK.
+
 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

package/USAGE.md

@@ -146,6 +146,13 @@ const client = new AgentGameRuntimeBrowserClient({
 
 const view = await mountAgentGameOffice(container, {
   renderer: "three",
+  office: {
+    rooms: [
+      { type: "office", capacity: 12 },
+      { type: "auditorium", capacity: 40 },
+      { type: "gym", capacity: 8 },
+    ],
+  },
   source: {
     type: "runtime",
     client,
@@ -153,17 +160,24 @@ const view = await mountAgentGameOffice(container, {
 });
 
 view.focusAgent("agent-1");
+view.refreshAgents();
 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.
 
+`office.rooms` configures the 3D office by semantic room type. The built-in room types are `office`, `auditorium`, and `gym`. If `office` is omitted, the SDK renders all three rooms. `capacity` is optional and influences the generated anchors used for agent placement. Do not configure desks, walls, whiteboards, fitness equipment, or raw coordinates from application code; those components remain SDK-managed presets.
+
+`refreshAgents` asks Agent Game Runtime to refresh the tenant roster through the existing bootstrap flow. It is intended for UI controls such as a refresh button after an Agent was created or deleted in another surface.
+
 ## React Office View
 
 Use `AgentGameOfficeView` when embedding the office view in a React application.
 
 ```tsx
+import { useState } from "react";
 import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import type { AgentGameOfficeController } from "@agent-os-lab/agent-game-sdk/office";
 import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
 
 const client = new AgentGameRuntimeBrowserClient({
@@ -171,18 +185,34 @@ const client = new AgentGameRuntimeBrowserClient({
 });
 
 export function Office() {
+  const [view, setView] = useState<AgentGameOfficeController | null>(null);
+
   return (
-    <AgentGameOfficeView
-      renderer="three"
-      source={{ type: "runtime", client }}
-      focusedAgentId="agent-1"
-      style={{ height: 640 }}
-    />
+    <>
+      <button type="button" onClick={() => view?.refreshAgents()}>
+        Refresh agents
+      </button>
+      <AgentGameOfficeView
+        renderer="three"
+        office={{
+          rooms: [
+            { type: "office" },
+            { type: "auditorium" },
+            { type: "gym" },
+          ],
+        }}
+        source={{ type: "runtime", client }}
+        focusedAgentId="agent-1"
+        style={{ height: 640 }}
+        onReady={setView}
+        onDestroy={() => setView(null)}
+      />
+    </>
   );
 }
 ```
 
-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.
+Keep `source` object identity stable across renders when possible. Recreating `source` every render can remount the view because the React wrapper treats it as an effect dependency. Equivalent inline `office` objects do not remount the view, but memoizing office config is still preferable when constructing it dynamically.
 
 ## Snapshot Source
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "files": [
     "src",

package/src/office/core/types.ts

@@ -5,6 +5,10 @@ import type {
   AgentPresenceStatus,
   GameRuntimeSubscription,
 } from "../../runtime-client";
+import type {
+  AgentGameOfficeConfig,
+  ResolvedOfficeLayout,
+} from "../layout";
 
 export type {
   AgentActivityDisplay,
@@ -95,16 +99,19 @@ export type AgentGameOfficeRenderer = {
 export type AgentGameOfficeMountOptions = {
   renderer?: AgentGameOfficeRendererKind | AgentGameOfficeRenderer;
   source: AgentGameOfficeSourceInput;
+  office?: AgentGameOfficeConfig;
   focusedAgentId?: string | null;
   className?: string;
 };
 
 export type AgentGameOfficeResolvedOptions = Omit<AgentGameOfficeMountOptions, "renderer"> & {
   renderer: AgentGameOfficeRendererKind | AgentGameOfficeRenderer;
+  officeLayout: ResolvedOfficeLayout;
 };
 
 export type AgentGameOfficeController = {
   updateAgents(agents: AgentPresence[]): void;
   focusAgent(agentId: string | null): void;
+  refreshAgents(): void;
   destroy(): void;
 };

package/src/office/index.ts

@@ -1,4 +1,5 @@
 export * from "./core/types";
 export * from "./core/projection";
 export * from "./core/source";
+export * from "./layout";
 export * from "./mount";

package/src/office/layout/config.ts

@@ -0,0 +1,76 @@
+export type AgentGameOfficeRoomType = "office" | "auditorium" | "gym";
+
+export type AgentGameOfficeRoomConfig = {
+  type: AgentGameOfficeRoomType;
+  capacity?: number;
+};
+
+export type AgentGameOfficeConfig = {
+  rooms: AgentGameOfficeRoomConfig[];
+};
+
+export type NormalizedOfficeRoomConfig = {
+  id: string;
+  type: AgentGameOfficeRoomType;
+  capacity: number;
+};
+
+export type NormalizedOfficeConfig = {
+  rooms: NormalizedOfficeRoomConfig[];
+};
+
+const DEFAULT_ROOM_CAPACITY = {
+  office: 12,
+  auditorium: 40,
+  gym: 8,
+} satisfies Record<AgentGameOfficeRoomType, number>;
+
+const MAX_ROOM_CAPACITY = {
+  office: 48,
+  auditorium: 120,
+  gym: 24,
+} satisfies Record<AgentGameOfficeRoomType, number>;
+
+export const DEFAULT_OFFICE_CONFIG: AgentGameOfficeConfig = {
+  rooms: [
+    { type: "office" },
+    { type: "auditorium" },
+    { type: "gym" },
+  ],
+};
+
+export function normalizeOfficeConfig(
+  config: AgentGameOfficeConfig | undefined = DEFAULT_OFFICE_CONFIG,
+): NormalizedOfficeConfig {
+  if (!Array.isArray(config.rooms) || config.rooms.length === 0) {
+    throw new Error("Agent game office config requires at least one room");
+  }
+
+  const counts = new Map<AgentGameOfficeRoomType, number>();
+  return {
+    rooms: config.rooms.map((room) => {
+      assertRoomType(room.type);
+      const nextCount = (counts.get(room.type) ?? 0) + 1;
+      counts.set(room.type, nextCount);
+      return {
+        id: `${room.type}-${nextCount}`,
+        type: room.type,
+        capacity: normalizeRoomCapacity(room.type, room.capacity),
+      };
+    }),
+  };
+}
+
+function assertRoomType(value: string): asserts value is AgentGameOfficeRoomType {
+  if (value !== "office" && value !== "auditorium" && value !== "gym") {
+    throw new Error(`Unsupported agent game office room type: ${value}`);
+  }
+}
+
+function normalizeRoomCapacity(type: AgentGameOfficeRoomType, capacity: number | undefined): number {
+  const value = capacity ?? DEFAULT_ROOM_CAPACITY[type];
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`Agent game office room ${type} capacity must be a positive integer`);
+  }
+  return Math.min(value, MAX_ROOM_CAPACITY[type]);
+}

package/src/office/layout/index.ts

@@ -0,0 +1,2 @@
+export * from "./config";
+export * from "./resolver";