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

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: "",
@@ -18,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,
@@ -25,36 +34,57 @@ const view = await mountAgentGameOffice(container, {
 });
 
 view.focusAgent("agent-1");
+view.refreshAgents();
 view.destroy();
 ```
 
 React wrapper:
 
 ```tsx
-import { AgentGameRuntimeBrowserClient } from "agent-game-sdk";
-import { AgentGameOfficeView } from "agent-game-sdk/office/react";
+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({
   baseUrl: "",
 });
 
 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
-import { AgentGameRuntimeServerClient } from "agent-game-sdk";
+import { AgentGameRuntimeServerClient } from "@agent-os-lab/agent-game-sdk";
 
 const client = new AgentGameRuntimeServerClient({
   baseUrl: process.env.AGENT_GAME_RUNTIME_BASE_URL!,

package/USAGE.md

@@ -0,0 +1,333 @@
+# 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",
+  office: {
+    rooms: [
+      { type: "office", capacity: 12 },
+      { type: "auditorium", capacity: 40 },
+      { type: "gym", capacity: 8 },
+    ],
+  },
+  source: {
+    type: "runtime",
+    client,
+  },
+});
+
+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({
+  baseUrl: "",
+});
+
+export function Office() {
+  const [view, setView] = useState<AgentGameOfficeController | null>(null);
+
+  return (
+    <>
+      <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 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
+
+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.2",
+  "version": "0.1.4",
   "type": "module",
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "USAGE.md"
   ],
   "exports": {
     ".": "./src/index.ts",

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";