@agent-os-lab/agent-game-sdk 0.1.8 → 0.1.10

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.10",
   "type": "module",
   "files": [
     "src",

package/src/index.ts

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

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/core/types.ts

@@ -88,9 +88,22 @@ export type AgentGameOfficeSourceInput =
 export type AgentGameOfficeRendererController = {
   update(snapshot: AgentGameOfficeSnapshot): void;
   focusAgent?(agentId: string | null): void;
+  focusFloor?(floorId: string | null): void;
+  getFocusedFloor?(): string | null;
+  getNavigationErrors?(): AgentNavigationError[];
   destroy(): void;
 };
 
+export type AgentNavigationError = {
+  agentId: string;
+  code: "missing-zone-anchor" | "missing-route" | "stale-location-node";
+  message: string;
+  zoneId?: AgentGameOfficeZoneId;
+  fromNodeId?: string;
+  toNodeId?: string;
+  floorId?: string;
+};
+
 export type AgentGameOfficeCameraState = {
   zoom: number;
   distance: number;
@@ -114,8 +127,10 @@ export type AgentGameOfficeMountOptions = {
   source: AgentGameOfficeSourceInput;
   office?: AgentGameOfficeConfig;
   focusedAgentId?: string | null;
+  focusedFloorId?: string | null;
   className?: string;
   onCameraChange?: (state: AgentGameOfficeCameraState) => void;
+  onFocusedFloorChange?: (floorId: string | null) => void;
 };
 
 export type AgentGameOfficeResolvedOptions = Omit<AgentGameOfficeMountOptions, "renderer"> & {
@@ -126,6 +141,9 @@ export type AgentGameOfficeResolvedOptions = Omit<AgentGameOfficeMountOptions, "
 export type AgentGameOfficeController = {
   updateAgents(agents: AgentPresence[]): void;
   focusAgent(agentId: string | null): void;
+  focusFloor(floorId: string | null): void;
+  getFocusedFloor(): string | null;
   refreshAgents(): void;
+  getNavigationErrors(): AgentNavigationError[];
   destroy(): void;
 };

package/src/office/layout/config.ts

@@ -1,75 +1,284 @@
-export type AgentGameOfficeRoomType = "office" | "auditorium" | "gym";
+export type AgentGameOfficeRoomType = "office" | "auditorium" | "gym" | "dining" | "cafe" | "skyGarden";
 
 export type AgentGameOfficeRoomConfig = {
   type: AgentGameOfficeRoomType;
   capacity?: number;
 };
 
-export type AgentGameOfficeConfig = {
+export type AgentGameOfficeConnectorType = "elevator";
+
+export type AgentGameOfficeFloorConfig = {
+  id: string;
+  name: string;
   rooms: AgentGameOfficeRoomConfig[];
 };
 
+export type AgentGameOfficeConnectorConfig = {
+  id: string;
+  type: AgentGameOfficeConnectorType;
+  name: string;
+  serves: string[];
+};
+
+export type AgentGameOfficeConfig = {
+  building: {
+    floors: AgentGameOfficeFloorConfig[];
+    connectors: AgentGameOfficeConnectorConfig[];
+  };
+};
+
 export type NormalizedOfficeRoomConfig = {
   id: string;
   type: AgentGameOfficeRoomType;
   capacity: number;
 };
 
-export type NormalizedOfficeConfig = {
+export type NormalizedOfficeFloorConfig = {
+  id: string;
+  name: string;
+  level: number;
   rooms: NormalizedOfficeRoomConfig[];
 };
 
+export type NormalizedOfficeConnectorConfig = {
+  id: string;
+  type: AgentGameOfficeConnectorType;
+  name: string;
+  serves: string[];
+};
+
+export type NormalizedOfficeConfig = {
+  building: {
+    floors: NormalizedOfficeFloorConfig[];
+    connectors: NormalizedOfficeConnectorConfig[];
+  };
+};
+
 const DEFAULT_ROOM_CAPACITY = {
   office: 12,
   auditorium: 40,
   gym: 8,
+  dining: 16,
+  cafe: 12,
+  skyGarden: 12,
 } satisfies Record<AgentGameOfficeRoomType, number>;
 
 const MAX_ROOM_CAPACITY = {
   office: 48,
   auditorium: 120,
   gym: 24,
+  dining: 48,
+  cafe: 32,
+  skyGarden: 32,
 } satisfies Record<AgentGameOfficeRoomType, number>;
 
 export const DEFAULT_OFFICE_CONFIG: AgentGameOfficeConfig = {
-  rooms: [
-    { type: "office" },
-    { type: "auditorium" },
-    { type: "gym" },
-  ],
+  building: {
+    floors: [
+      {
+        id: "floor-1",
+        name: "1F",
+        rooms: [
+          { type: "office" },
+          { type: "auditorium" },
+          { type: "gym" },
+        ],
+      },
+    ],
+    connectors: [],
+  },
 };
 
 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");
+  if (isRecord(config) && "rooms" in config) {
+    throw new Error("Agent game office config must use building floors instead of top-level rooms");
+  }
+  if (!config || !isRecord(config.building)) {
+    throw new Error("Agent game office config requires a building");
+  }
+
+  const floors = config.building.floors;
+  if (!Array.isArray(floors) || floors.length === 0) {
+    throw new Error("Agent game office building requires at least one floor");
+  }
+
+  const floorIds = new Set<string>();
+  const normalizedFloors = floors.map((floor, level) => {
+    if (!isRecord(floor)) {
+      throw new Error("Agent game office building floor config must be an object");
+    }
+    const floorId = assertNonEmptyId(floor.id, "floor");
+    assertUnique(floorId, floorIds, "floor");
+    if (!Array.isArray(floor.rooms) || floor.rooms.length === 0) {
+      throw new Error(`Agent game office floor ${floorId} requires at least one room`);
+    }
+
+    const counts = new Map<AgentGameOfficeRoomType, number>();
+    return {
+      id: floorId,
+      name: normalizeName(floor.name, "floor", floorId),
+      level,
+      rooms: floor.rooms.map((room) => {
+        if (!isRecord(room)) {
+          throw new Error(`Agent game office floor ${floorId} room config must be an object`);
+        }
+        assertRoomType(room.type);
+        const nextCount = (counts.get(room.type) ?? 0) + 1;
+        counts.set(room.type, nextCount);
+        return {
+          id: `${floorId}:${room.type}-${nextCount}`,
+          type: room.type,
+          capacity: normalizeRoomCapacity(room.type, room.capacity),
+        };
+      }),
+    };
+  });
+
+  const connectors = config.building.connectors;
+  if (!Array.isArray(connectors)) {
+    throw new Error("Agent game office building connectors must be an array");
+  }
+  if (normalizedFloors.length === 1 && connectors.length > 0) {
+    throw new Error("Agent game office single-floor building should not define connectors");
   }
+  if (normalizedFloors.length > 1 && connectors.length === 0) {
+    throw new Error("Agent game office building with multiple floors requires at least one connector");
+  }
+
+  const connectorIds = new Set<string>();
+  const normalizedConnectors = connectors.map((connector) => {
+    if (!isRecord(connector)) {
+      throw new Error("Agent game office building connector config must be an object");
+    }
+    const connectorId = assertNonEmptyId(connector.id, "connector");
+    assertUnique(connectorId, connectorIds, "connector");
+    assertConnectorType(connector.type);
+    if (!Array.isArray(connector.serves)) {
+      throw new Error(`Agent game office connector ${connectorId} must serve at least two floors`);
+    }
+    const servedFloorIds = new Set<string>();
+    const serves = connector.serves.map((floorId) => {
+      const normalizedFloorId = assertNonEmptyId(floorId, "connector floor");
+      if (!floorIds.has(normalizedFloorId)) {
+        throw new Error(`Agent game office connector ${connectorId} serves unknown floor: ${normalizedFloorId}`);
+      }
+      assertUnique(normalizedFloorId, servedFloorIds, "connector served floor");
+      return normalizedFloorId;
+    });
+    if (serves.length < 2) {
+      throw new Error(`Agent game office connector ${connectorId} must serve at least two floors`);
+    }
+
+    return {
+      id: connectorId,
+      type: connector.type,
+      name: normalizeName(connector.name, "connector", connectorId),
+      serves,
+    };
+  });
+  validateConnectorCoverage(normalizedFloors.map((floor) => floor.id), normalizedConnectors);
 
-  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),
-      };
-    }),
+    building: {
+      floors: normalizedFloors,
+      connectors: normalizedConnectors,
+    },
   };
 }
 
-function assertRoomType(value: string): asserts value is AgentGameOfficeRoomType {
-  if (value !== "office" && value !== "auditorium" && value !== "gym") {
+function validateConnectorCoverage(
+  floorIds: string[],
+  connectors: NormalizedOfficeConnectorConfig[],
+) {
+  if (floorIds.length <= 1) {
+    return;
+  }
+
+  const neighbors = new Map(floorIds.map((floorId) => [floorId, new Set<string>()]));
+  for (const connector of connectors) {
+    for (let leftIndex = 0; leftIndex < connector.serves.length; leftIndex += 1) {
+      for (let rightIndex = leftIndex + 1; rightIndex < connector.serves.length; rightIndex += 1) {
+        const left = connector.serves[leftIndex]!;
+        const right = connector.serves[rightIndex]!;
+        neighbors.get(left)?.add(right);
+        neighbors.get(right)?.add(left);
+      }
+    }
+  }
+
+  const visited = new Set<string>();
+  const queue = [floorIds[0]!];
+  while (queue.length > 0) {
+    const floorId = queue.shift()!;
+    if (visited.has(floorId)) {
+      continue;
+    }
+    visited.add(floorId);
+    for (const next of neighbors.get(floorId) ?? []) {
+      if (!visited.has(next)) {
+        queue.push(next);
+      }
+    }
+  }
+
+  if (visited.size !== floorIds.length) {
+    throw new Error("Agent game office building connector graph is disconnected");
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function assertNonEmptyId(value: unknown, label: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`Agent game office ${label} id must be non-empty`);
+  }
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new Error(`Agent game office ${label} id must be non-empty`);
+  }
+  return normalized;
+}
+
+function assertUnique(value: string, seen: Set<string>, label: string) {
+  if (seen.has(value)) {
+    throw new Error(`duplicate agent game office ${label} id: ${value}`);
+  }
+  seen.add(value);
+}
+
+function normalizeName(value: unknown, label: string, id: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Agent game office ${label} ${id} name must be non-empty`);
+  }
+  return value.trim();
+}
+
+function assertRoomType(value: unknown): asserts value is AgentGameOfficeRoomType {
+  if (
+    value !== "office"
+    && value !== "auditorium"
+    && value !== "gym"
+    && value !== "dining"
+    && value !== "cafe"
+    && value !== "skyGarden"
+  ) {
     throw new Error(`Unsupported agent game office room type: ${value}`);
   }
 }
 
-function normalizeRoomCapacity(type: AgentGameOfficeRoomType, capacity: number | undefined): number {
+function assertConnectorType(value: unknown): asserts value is AgentGameOfficeConnectorType {
+  if (value !== "elevator") {
+    throw new Error(`Unsupported agent game office connector type: ${value}`);
+  }
+}
+
+function normalizeRoomCapacity(type: AgentGameOfficeRoomType, capacity: unknown): number {
   const value = capacity ?? DEFAULT_ROOM_CAPACITY[type];
-  if (!Number.isInteger(value) || value <= 0) {
+  if (typeof value !== "number" || !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

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

package/src/office/layout/navigation.ts

@@ -0,0 +1,168 @@
+export type Vector3Like = { x: number; y: number; z: number };
+
+export type NavigationNodeKind =
+  | "seat"
+  | "zone"
+  | "connector-entry"
+  | "connector-cabin"
+  | "offstage";
+
+export type NavigationNode = {
+  id: string;
+  floorId: string | null;
+  kind: NavigationNodeKind;
+  anchorId?: string;
+  connectorId?: string;
+  position: Vector3Like;
+};
+
+export type NavigationEdge =
+  | { kind: "walk"; from: string; to: string; floorId: string }
+  | {
+      kind: "elevator";
+      from: string;
+      to: string;
+      connectorId: string;
+      fromFloorId: string;
+      toFloorId: string;
+    };
+
+export type ResolvedBuildingNavigationGraph = {
+  nodes: NavigationNode[];
+  edges: NavigationEdge[];
+};
+
+export type AgentRouteStep =
+  | {
+      kind: "walk";
+      fromNodeId: string;
+      toNodeId: string;
+      floorId: string;
+      from: Vector3Like;
+      to: Vector3Like;
+    }
+  | {
+      kind: "elevator";
+      connectorId: string;
+      fromFloorId: string;
+      toFloorId: string;
+      fromNodeId: string;
+      toNodeId: string;
+      from: Vector3Like;
+      to: Vector3Like;
+    };
+
+export type AgentRoute = {
+  id: string;
+  agentId?: string;
+  fromNodeId: string;
+  toNodeId: string;
+  steps: AgentRouteStep[];
+};
+
+export class NoBuildingRouteError extends Error {
+  constructor(fromNodeId: string, toNodeId: string) {
+    super(`No building navigation route from ${fromNodeId} to ${toNodeId}`);
+    this.name = "NoBuildingRouteError";
+  }
+}
+
+export function planAgentRoute(
+  graph: ResolvedBuildingNavigationGraph,
+  fromNodeId: string,
+  toNodeId: string,
+): AgentRoute {
+  const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+  if (!nodes.has(fromNodeId) || !nodes.has(toNodeId)) {
+    throw new NoBuildingRouteError(fromNodeId, toNodeId);
+  }
+  if (fromNodeId === toNodeId) {
+    return {
+      id: `${fromNodeId}->${toNodeId}`,
+      fromNodeId,
+      toNodeId,
+      steps: [],
+    };
+  }
+
+  const edgesByFrom = new Map<string, NavigationEdge[]>();
+  for (const edge of graph.edges) {
+    const edges = edgesByFrom.get(edge.from);
+    if (edges) {
+      edges.push(edge);
+    } else {
+      edgesByFrom.set(edge.from, [edge]);
+    }
+  }
+
+  const queue = [fromNodeId];
+  const visited = new Set<string>([fromNodeId]);
+  const previous = new Map<string, NavigationEdge>();
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    for (const edge of edgesByFrom.get(current) ?? []) {
+      if (visited.has(edge.to)) {
+        continue;
+      }
+      visited.add(edge.to);
+      previous.set(edge.to, edge);
+      if (edge.to === toNodeId) {
+        queue.length = 0;
+        break;
+      }
+      queue.push(edge.to);
+    }
+  }
+
+  if (!previous.has(toNodeId)) {
+    throw new NoBuildingRouteError(fromNodeId, toNodeId);
+  }
+
+  const path: NavigationEdge[] = [];
+  let cursor = toNodeId;
+  while (cursor !== fromNodeId) {
+    const edge = previous.get(cursor);
+    if (!edge) {
+      throw new NoBuildingRouteError(fromNodeId, toNodeId);
+    }
+    path.push(edge);
+    cursor = edge.from;
+  }
+  path.reverse();
+
+  return {
+    id: `${fromNodeId}->${toNodeId}`,
+    fromNodeId,
+    toNodeId,
+    steps: path.map((edge) => edgeToRouteStep(edge, nodes)),
+  };
+}
+
+function edgeToRouteStep(edge: NavigationEdge, nodes: Map<string, NavigationNode>): AgentRouteStep {
+  const from = nodes.get(edge.from);
+  const to = nodes.get(edge.to);
+  if (!from || !to) {
+    throw new NoBuildingRouteError(edge.from, edge.to);
+  }
+  if (edge.kind === "walk") {
+    return {
+      kind: "walk",
+      fromNodeId: edge.from,
+      toNodeId: edge.to,
+      floorId: edge.floorId,
+      from: from.position,
+      to: to.position,
+    };
+  }
+  return {
+    kind: "elevator",
+    connectorId: edge.connectorId,
+    fromFloorId: edge.fromFloorId,
+    toFloorId: edge.toFloorId,
+    fromNodeId: edge.from,
+    toNodeId: edge.to,
+    from: from.position,
+    to: to.position,
+  };
+}