@agent-os-lab/agent-game-sdk 0.1.7 → 0.1.9

package/README.md

@@ -78,6 +78,38 @@ export function Office() {
 
 `agent-game-sdk/office` is renderer and framework neutral. `agent-game-sdk/office/react` is the React-only entrypoint.
 
+## Runtime Agent List
+
+Use `subscribeAgentPresenceList` when an app needs the live Agent roster and status outside the 3D office view:
+
+```ts
+import {
+  AgentGameRuntimeBrowserClient,
+  formatAgentPresenceStatus,
+  subscribeAgentPresenceList,
+} from "@agent-os-lab/agent-game-sdk";
+
+const client = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+});
+
+const subscription = await subscribeAgentPresenceList(client, {
+  onAgentsChange: (agents) => {
+    renderAgentList(agents.map((agent) => ({
+      id: agent.agentId,
+      name: agent.displayName,
+      status: formatAgentPresenceStatus(agent.status),
+      activity: agent.activity?.summary,
+    })));
+  },
+});
+
+const currentAgents = subscription.getAgents();
+subscription.close();
+```
+
+The helper applies runtime `snapshot` messages as the full roster and `patch` messages as incremental updates, so consumers always receive a complete sorted Agent list.
+
 The built-in 3D renderer supports semantic room configuration. If `office` is omitted, the SDK renders the default `office + auditorium + gym` layout. To choose visible rooms, pass `office.rooms` in the order you want them assembled:
 
 ```ts

package/USAGE.md

@@ -32,6 +32,7 @@ Runtime requirements:
 import {
   AgentGameRuntimeBrowserClient,
   AgentGameRuntimeServerClient,
+  subscribeAgentPresenceList,
 } 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";
@@ -91,7 +92,50 @@ The browser client strips caller-provided `authorization`, `x-hermes-tenant-id`,
 
 ## Runtime Subscription
 
-Use `subscribe` when the application wants direct access to live runtime messages instead of using the office view.
+Use `subscribeAgentPresenceList` when the application wants the current Agent roster and realtime status outside the office view.
+
+```ts
+import {
+  AgentGameRuntimeBrowserClient,
+  formatAgentPresenceStatus,
+  subscribeAgentPresenceList,
+  type AgentPresence,
+} from "@agent-os-lab/agent-game-sdk";
+
+const browserClient = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+});
+
+let agents: AgentPresence[] = [];
+
+const subscription = await subscribeAgentPresenceList(browserClient, {
+  onAgentsChange: (nextAgents, message) => {
+    agents = nextAgents;
+    console.log("agent roster updated from", message.type);
+    console.table(agents.map((agent) => ({
+      name: agent.displayName,
+      status: formatAgentPresenceStatus(agent.status),
+      activity: agent.activity?.summary ?? "",
+    })));
+  },
+  onError: (error) => {
+    console.error("runtime stream error", error);
+  },
+});
+
+const latestAgents = subscription.getAgents();
+subscription.refresh();
+subscription.close();
+```
+
+`subscribeAgentPresenceList` handles both runtime message shapes:
+
+- `snapshot`: replaces the current roster with the full current presence list.
+- `patch`: merges changed Agent presence records into the current roster.
+
+The `onAgentsChange` callback receives a complete display-name-sorted `AgentPresence[]` after every snapshot or patch. The returned subscription extends the normal runtime subscription with `getAgents()` for synchronous reads of the latest list.
+
+Use `subscribe` when the application needs raw runtime messages instead of the SDK-maintained Agent list.
 
 ```ts
 const subscription = await browserClient.subscribe({
@@ -114,7 +158,7 @@ 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.
+Use `mergeAgentPresence` only when maintaining your own custom presence reducer from snapshots and patches.
 
 ```ts
 import { mergeAgentPresence } from "@agent-os-lab/agent-game-sdk";

package/package.json

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

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from "./runtime-client";
+export * from "./runtime-agent-list";
 export * from "./office";

package/src/office/core/projection.ts

@@ -7,16 +7,7 @@ import type {
   AgentPresence,
   AgentPresenceStatus,
 } from "./types";
-
-const statusLabels = {
-  working: "Working",
-  thinking: "Thinking",
-  meeting: "Meeting",
-  resting: "Resting",
-  entertaining: "Entertainment",
-  idle: "Idle",
-  offline: "Offline",
-} satisfies Record<AgentPresenceStatus, string>;
+import { formatAgentPresenceStatus } from "../../runtime-agent-list";
 
 const ambientZoneIds = ["lounge", "pantry", "gym", "reading"] as const;
 
@@ -27,9 +18,9 @@ export function mapPresenceToOfficeAgents(
     id: agent.agentId,
     name: agent.displayName,
     role: agent.scene ?? null,
-    statusLabel: statusLabels[agent.status],
+    statusLabel: formatAgentPresenceStatus(agent.status),
     activity: agent.activity,
-    activityLabel: sanitizeActivityLabel(agent.activity),
+    activityLabel: sanitizeActivityLabel(agent.activity, agent.status),
     sceneState: mapStatusToSceneState(agent.status),
     zoneId: mapStatusToZoneId(agent.status, agent.agentId),
     updatedAt: agent.updatedAt,
@@ -68,7 +59,13 @@ function mapStatusToSceneState(status: AgentPresenceStatus): AgentGameOfficeScen
   return status;
 }
 
-function sanitizeActivityLabel(activity: AgentPresence["activity"]): string | undefined {
+function sanitizeActivityLabel(
+  activity: AgentPresence["activity"],
+  status: AgentPresenceStatus,
+): string | undefined {
+  if (!isActiveWorkStatus(status)) {
+    return undefined;
+  }
   if (activity?.kind === "completed") {
     return undefined;
   }
@@ -108,6 +105,10 @@ function formatToolActivityLabel(label: string): string {
   return label === "正在使用工具" ? "正在调用工具..." : label;
 }
 
+function isActiveWorkStatus(status: AgentPresenceStatus): boolean {
+  return status === "working" || status === "thinking";
+}
+
 function mapStatusToZoneId(status: AgentPresenceStatus, agentId: string): AgentGameOfficeZoneId {
   switch (status) {
     case "working":

package/src/office/mount.ts

@@ -2,7 +2,10 @@ import {
   createSnapshotOfficeSource,
   resolveOfficeSource,
 } from "./core/source";
-import { mergeAgentPresence, type GameRuntimeSubscription } from "../runtime-client";
+import {
+  subscribeAgentPresenceList,
+  type AgentPresenceListSubscription,
+} from "../runtime-agent-list";
 import { resolveOfficeLayout } from "./layout";
 import type {
   AgentGameOfficeMountOptions,
@@ -29,8 +32,7 @@ export async function mountAgentGameOffice(
   const source = mutableSource ?? runtimeSource ?? resolveOfficeSource(options.source);
   let controller: AgentGameOfficeRendererController | null = null;
   let latestSnapshot: AgentGameOfficeSnapshot | null = null;
-  let runtimeSubscription: GameRuntimeSubscription | null = null;
-  let runtimeAgents: AgentPresence[] = [];
+  let runtimeSubscription: AgentPresenceListSubscription | null = null;
 
   const unsubscribe = source.subscribe((snapshot) => {
     latestSnapshot = snapshot;
@@ -45,14 +47,9 @@ export async function mountAgentGameOffice(
 
   if (options.source.type === "runtime" && runtimeSource) {
     try {
-      runtimeSubscription = await options.source.client.subscribe({
-        onSnapshot: (message) => {
-          runtimeAgents = message.agents;
-          runtimeSource.updateAgents(runtimeAgents);
-        },
-        onPatch: (message) => {
-          runtimeAgents = mergeAgentPresence(runtimeAgents, message.agents);
-          runtimeSource.updateAgents(runtimeAgents);
+      runtimeSubscription = await subscribeAgentPresenceList(options.source.client, {
+        onAgentsChange: (agents) => {
+          runtimeSource.updateAgents(agents);
         },
       });
     } catch (error) {

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

@@ -44,6 +44,7 @@ const WORKING_FOLLOW_RESET_DELAY_MS = 30_000;
 const WORK_EXIT_WAIT_MS = 30_000;
 const WORKING_FOLLOW_CAMERA_OFFSET = new THREE.Vector3(9, 12, 12);
 const OFFICE_CAMERA_TRANSITION_DURATION_MS = 600;
+const OFFICE_CAMERA_UP = new THREE.Vector3(0, 1, 0);
 
 export type WorkingAgentFollowState = {
   selectedAgentId: string | null;
@@ -478,14 +479,14 @@ export function createFollowOfficeCameraView(agentPosition: THREE.Vector3): Offi
   const target = new THREE.Vector3(agentPosition.x, 1, agentPosition.z);
   const position = target.clone().add(WORKING_FOLLOW_CAMERA_OFFSET);
   const rotation = new THREE.Euler();
-  const matrix = new THREE.Matrix4().lookAt(position, target, new THREE.Vector3(0, 1, 0));
+  const matrix = new THREE.Matrix4().lookAt(position, target, OFFICE_CAMERA_UP);
   rotation.setFromRotationMatrix(matrix);
 
   return {
     position,
     rotation,
     target,
-    up: new THREE.Vector3(0, 1, 0),
+    up: OFFICE_CAMERA_UP.clone(),
     distance: position.distanceTo(target),
   };
 }
@@ -502,16 +503,20 @@ export function createInitialOfficeCameraView(
   );
   const quaternion = new THREE.Quaternion().setFromEuler(rotation);
   const forward = new THREE.Vector3(0, 0, -1).applyQuaternion(quaternion).normalize();
-  const up = new THREE.Vector3(0, 1, 0).applyQuaternion(quaternion).normalize();
   const target = new THREE.Vector3(layout.scene.center.x, OFFICE_CAMERA_BOUNDS_HEIGHT / 2, layout.scene.center.z);
-  const distance = resolveOfficeCameraDistance(layout, target, quaternion, aspect, fovDegrees);
+  const preliminaryPosition = target.clone().sub(forward.clone());
+  const orbitRotation = new THREE.Euler();
+  const matrix = new THREE.Matrix4().lookAt(preliminaryPosition, target, OFFICE_CAMERA_UP);
+  orbitRotation.setFromRotationMatrix(matrix);
+  const orbitQuaternion = new THREE.Quaternion().setFromEuler(orbitRotation);
+  const distance = resolveOfficeCameraDistance(layout, target, orbitQuaternion, aspect, fovDegrees);
   const position = target.clone().sub(forward.multiplyScalar(distance));
 
   return {
     position,
-    rotation,
+    rotation: orbitRotation,
     target,
-    up,
+    up: OFFICE_CAMERA_UP.clone(),
     distance,
   };
 }

package/src/runtime-agent-list.ts

@@ -0,0 +1,86 @@
+import {
+  mergeAgentPresence,
+  type AgentGameRuntimeBrowserSubscribeOptions,
+  type AgentPresence,
+  type AgentPresenceStatus,
+  type GameRuntimePatchMessage,
+  type GameRuntimeServerMessage,
+  type GameRuntimeSnapshotMessage,
+  type GameRuntimeSubscription,
+} from "./runtime-client";
+
+export const AGENT_PRESENCE_STATUS_LABELS = {
+  working: "Working",
+  thinking: "Thinking",
+  meeting: "Meeting",
+  resting: "Resting",
+  entertaining: "Entertainment",
+  idle: "Idle",
+  offline: "Offline",
+} satisfies Record<AgentPresenceStatus, string>;
+
+export type AgentPresenceListSubscription = GameRuntimeSubscription & {
+  getAgents(): AgentPresence[];
+};
+
+export type AgentPresenceListClient = {
+  subscribe(options?: AgentGameRuntimeBrowserSubscribeOptions): Promise<GameRuntimeSubscription>;
+};
+
+export type SubscribeAgentPresenceListOptions = AgentGameRuntimeBrowserSubscribeOptions & {
+  onAgentsChange?: (
+    agents: AgentPresence[],
+    message: GameRuntimeSnapshotMessage | GameRuntimePatchMessage,
+  ) => void;
+};
+
+export function reduceAgentPresenceList(
+  current: AgentPresence[],
+  message: GameRuntimeServerMessage,
+): AgentPresence[] {
+  if (message.type === "snapshot") {
+    return mergeAgentPresence([], message.agents);
+  }
+  return mergeAgentPresence(current, message.agents);
+}
+
+export function formatAgentPresenceStatus(status: AgentPresenceStatus): string {
+  return AGENT_PRESENCE_STATUS_LABELS[status];
+}
+
+export async function subscribeAgentPresenceList(
+  client: AgentPresenceListClient,
+  options: SubscribeAgentPresenceListOptions = {},
+): Promise<AgentPresenceListSubscription> {
+  let agents: AgentPresence[] = [];
+  const {
+    onAgentsChange,
+    onPatch,
+    onSnapshot,
+    ...subscribeOptions
+  } = options;
+
+  function applyMessage(message: GameRuntimeSnapshotMessage | GameRuntimePatchMessage) {
+    agents = reduceAgentPresenceList(agents, message);
+    onAgentsChange?.([...agents], message);
+  }
+
+  const subscription = await client.subscribe({
+    ...subscribeOptions,
+    onSnapshot: (message) => {
+      applyMessage(message);
+      onSnapshot?.(message);
+    },
+    onPatch: (message) => {
+      applyMessage(message);
+      onPatch?.(message);
+    },
+  });
+
+  return {
+    ...subscription,
+    getAgents() {
+      return [...agents];
+    },
+  };
+}