@agent-os-lab/agent-game-sdk 0.1.8 → 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.8",
+  "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,7 +18,7 @@ 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, agent.status),
     sceneState: mapStatusToSceneState(agent.status),

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/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];
+    },
+  };
+}