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

package/README.md

@@ -33,6 +33,7 @@ const view = await mountAgentGameOffice(container, {
 });
 
 view.focusAgent("agent-1");
+view.resetCamera();
 view.refreshAgents();
 view.destroy();
 ```
@@ -57,6 +58,9 @@ export function Office() {
       <button type="button" onClick={() => view?.refreshAgents()}>
         Refresh agents
       </button>
+      <button type="button" onClick={() => view?.resetCamera()}>
+        Reset view
+      </button>
       <AgentGameOfficeView
         renderer="three"
         office={{

package/USAGE.md

@@ -203,6 +203,7 @@ const view = await mountAgentGameOffice(container, {
 });
 
 view.focusAgent("agent-1");
+view.resetCamera();
 view.refreshAgents();
 view.destroy();
 ```
@@ -221,6 +222,8 @@ The layout packs up to three rooms per row, then starts another row. `capacity`
 
 The SDK keeps runtime statuses simple. `idle` and `resting` agents are locally distributed across ambient anchors for lounge, pantry, gym, and reading areas. `entertaining` stays biased toward the review area. If a configured room does not provide the selected ambient zone, the SDK falls back to another available non-offstage anchor.
 
+`resetCamera` returns the office view to its initial camera position, rotation, target, zoom, and follow state. It is intended for UI controls such as a reset-view button after a user pans, rotates, zooms, or follows an Agent.
+
 `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
@@ -245,6 +248,9 @@ export function Office() {
       <button type="button" onClick={() => view?.refreshAgents()}>
         Refresh agents
       </button>
+      <button type="button" onClick={() => view?.resetCamera()}>
+        Reset view
+      </button>
       <AgentGameOfficeView
         renderer="three"
         office={{
@@ -308,6 +314,8 @@ view.updateAgents([
 
 `updateAgents` only mutates SDK-managed snapshot sources. Runtime and custom sources own their own updates.
 
+`resetCamera` is source-independent and can be called for snapshot, runtime, and custom sources.
+
 ## Custom Source
 
 Use `source.type: "custom"` when another state manager already projects runtime state into office snapshots.

package/package.json

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

package/src/index.ts

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

package/src/office/core/types.ts

@@ -87,10 +87,24 @@ export type AgentGameOfficeSourceInput =
 
 export type AgentGameOfficeRendererController = {
   update(snapshot: AgentGameOfficeSnapshot): void;
+  resetCamera?(): 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 +128,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"> & {
@@ -125,7 +141,11 @@ export type AgentGameOfficeResolvedOptions = Omit<AgentGameOfficeMountOptions, "
 
 export type AgentGameOfficeController = {
   updateAgents(agents: AgentPresence[]): void;
+  resetCamera(): 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,
+  };
+}