@agent-os-lab/agent-game-sdk 0.1.1

package/src/graph.ts

@@ -0,0 +1,112 @@
+import type {
+  AgentGameGraph,
+  AgentGameNodeKind,
+  AgentGameScene,
+  AgentGameSceneOptions,
+  NormalizedAgentGameEdge,
+  NormalizedAgentGameGraph,
+  NormalizedAgentGameNode,
+} from "./types.js";
+
+const DEFAULT_LAYER_ORDER = [
+  "profile",
+  "agent",
+  "session",
+  "memory",
+  "tool",
+  "message",
+  "event",
+] as const satisfies readonly AgentGameNodeKind[];
+
+export function normalizeAgentGameGraph(graph: AgentGameGraph): NormalizedAgentGameGraph {
+  const nodeIds = new Set<string>();
+  const nodes = graph.nodes.map((node): NormalizedAgentGameNode => {
+    assertNonEmptyId(node.id, "node.id");
+    if (nodeIds.has(node.id)) {
+      throw new Error(`Duplicate agent game node id: ${node.id}`);
+    }
+    nodeIds.add(node.id);
+
+    return {
+      id: node.id,
+      kind: node.kind,
+      label: node.label ?? node.id,
+      status: node.status ?? "idle",
+      metadata: node.metadata ?? {},
+      ...(node.position ? { position: { x: node.position.x, y: node.position.y } } : {}),
+    };
+  });
+
+  const edgeIds = new Set<string>();
+  const edges = graph.edges.map((edge, index): NormalizedAgentGameEdge => {
+    assertNonEmptyId(edge.source, "edge.source");
+    assertNonEmptyId(edge.target, "edge.target");
+    if (!nodeIds.has(edge.source)) {
+      throw new Error(`Agent game edge references missing source node: ${edge.source}`);
+    }
+    if (!nodeIds.has(edge.target)) {
+      throw new Error(`Agent game edge references missing target node: ${edge.target}`);
+    }
+
+    const id = edge.id ?? `${edge.source}->${edge.target}:${edge.kind}:${index}`;
+    if (edgeIds.has(id)) {
+      throw new Error(`Duplicate agent game edge id: ${id}`);
+    }
+    edgeIds.add(id);
+
+    return {
+      id,
+      source: edge.source,
+      target: edge.target,
+      kind: edge.kind,
+      label: edge.label ?? edge.kind,
+      metadata: edge.metadata ?? {},
+    };
+  });
+
+  return {
+    nodes,
+    edges,
+    metadata: graph.metadata ?? {},
+  };
+}
+
+export function createAgentGameScene(graph: AgentGameGraph, options: AgentGameSceneOptions = {}): AgentGameScene {
+  const normalized = normalizeAgentGameGraph(graph);
+  const columnGap = options.columnGap ?? 220;
+  const rowGap = options.rowGap ?? 140;
+  const origin = options.origin ?? { x: 0, y: 0 };
+  const layerOrder = options.layerOrder ?? DEFAULT_LAYER_ORDER;
+  const layerIndex = new Map(layerOrder.map((kind, index) => [kind, index]));
+  const rowByLayer = new Map<number, number>();
+
+  const nodes = normalized.nodes.map((node) => {
+    if (node.position) {
+      return { ...node, position: { x: node.position.x, y: node.position.y } };
+    }
+
+    const layer = layerIndex.get(node.kind) ?? layerOrder.length;
+    const row = rowByLayer.get(layer) ?? 0;
+    rowByLayer.set(layer, row + 1);
+
+    return {
+      ...node,
+      position: {
+        x: origin.x + layer * columnGap,
+        y: origin.y + row * rowGap,
+      },
+    };
+  });
+
+  return {
+    nodes,
+    edges: normalized.edges,
+    metadata: normalized.metadata,
+  };
+}
+
+function assertNonEmptyId(value: string, field: string): void {
+  if (value.trim().length === 0) {
+    throw new Error(`Agent game ${field} must not be empty`);
+  }
+}

package/src/index.ts

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

package/src/office/core/projection.ts

@@ -0,0 +1,89 @@
+import type {
+  AgentGameOfficeAgent,
+  AgentGameOfficeSceneState,
+  AgentGameOfficeSnapshot,
+  AgentGameOfficeSummary,
+  AgentGameOfficeZoneId,
+  AgentPresence,
+  AgentPresenceStatus,
+} from "./types";
+
+const statusLabels = {
+  working: "Working",
+  thinking: "Thinking",
+  meeting: "Meeting",
+  resting: "Resting",
+  entertaining: "Entertainment",
+  idle: "Idle",
+  offline: "Offline",
+} satisfies Record<AgentPresenceStatus, string>;
+
+export function mapPresenceToOfficeAgents(
+  agents: AgentPresence[],
+): AgentGameOfficeAgent[] {
+  return agents.map((agent) => ({
+    id: agent.agentId,
+    name: agent.displayName,
+    role: agent.scene ?? null,
+    statusLabel: statusLabels[agent.status],
+    activity: agent.activity,
+    activityLabel: sanitizeActivityLabel(agent.activity?.summary),
+    sceneState: mapStatusToSceneState(agent.status),
+    zoneId: mapStatusToZoneId(agent.status),
+    updatedAt: agent.updatedAt,
+    targetPosition: null,
+    raw: agent,
+  }));
+}
+
+export function createOfficeSnapshot(
+  agents: AgentPresence[],
+): AgentGameOfficeSnapshot {
+  const officeAgents = mapPresenceToOfficeAgents(agents);
+  return {
+    agents: officeAgents,
+    summary: summarizeOfficeAgents(officeAgents),
+  };
+}
+
+export function summarizeOfficeAgents(
+  agents: AgentGameOfficeAgent[],
+): AgentGameOfficeSummary {
+  return {
+    totalAgents: agents.length,
+    workingAgents: agents.filter((agent) =>
+      agent.sceneState === "working" || agent.sceneState === "thinking",
+    ).length,
+    meetingAgents: agents.filter((agent) => agent.sceneState === "meeting").length,
+    restingAgents: agents.filter((agent) =>
+      agent.sceneState === "resting" || agent.sceneState === "entertaining" || agent.sceneState === "idle",
+    ).length,
+    offlineAgents: agents.filter((agent) => agent.sceneState === "offline").length,
+  };
+}
+
+function mapStatusToSceneState(status: AgentPresenceStatus): AgentGameOfficeSceneState {
+  return status;
+}
+
+function sanitizeActivityLabel(value: string | undefined): string | undefined {
+  const label = value?.trim();
+  return label ? label : undefined;
+}
+
+function mapStatusToZoneId(status: AgentPresenceStatus): AgentGameOfficeZoneId {
+  switch (status) {
+    case "working":
+    case "thinking":
+      return "desk";
+    case "meeting":
+      return "meeting-room";
+    case "resting":
+    case "idle":
+      return "lounge";
+    case "entertaining":
+      return "review-area";
+    case "offline":
+      return "offstage";
+  }
+}

package/src/office/core/source.ts

@@ -0,0 +1,46 @@
+import type {
+  AgentGameOfficeSnapshot,
+  AgentGameOfficeSource,
+  AgentGameOfficeSourceInput,
+  AgentPresence,
+} from "./types";
+import { createOfficeSnapshot } from "./projection";
+
+export type SnapshotOfficeSource = AgentGameOfficeSource & {
+  updateAgents(agents: AgentPresence[]): void;
+  getSnapshot(): AgentGameOfficeSnapshot;
+};
+
+export function createSnapshotOfficeSource(input: {
+  agents: AgentPresence[];
+}): SnapshotOfficeSource {
+  let snapshot = createOfficeSnapshot(input.agents);
+  const listeners = new Set<(snapshot: AgentGameOfficeSnapshot) => void>();
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(snapshot);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    updateAgents(agents) {
+      snapshot = createOfficeSnapshot(agents);
+      listeners.forEach((listener) => listener(snapshot));
+    },
+    getSnapshot() {
+      return snapshot;
+    },
+  };
+}
+
+export function resolveOfficeSource(input: AgentGameOfficeSourceInput): AgentGameOfficeSource {
+  if (input.type === "snapshot") {
+    return createSnapshotOfficeSource({ agents: input.agents });
+  }
+  if (input.type === "runtime") {
+    return createSnapshotOfficeSource({ agents: [] });
+  }
+  return input.source;
+}

package/src/office/core/types.ts

@@ -0,0 +1,110 @@
+import type {
+  AgentActivityDisplay,
+  AgentGameRuntimeBrowserSubscribeOptions,
+  AgentPresence,
+  AgentPresenceStatus,
+  GameRuntimeSubscription,
+} from "../../runtime-client";
+
+export type {
+  AgentActivityDisplay,
+  AgentPresence,
+  AgentPresenceStatus,
+} from "../../runtime-client";
+
+export type AgentGameOfficeRendererKind = "three";
+
+export type AgentGameOfficeSceneState =
+  | "working"
+  | "thinking"
+  | "meeting"
+  | "resting"
+  | "entertaining"
+  | "idle"
+  | "offline";
+
+export type AgentGameOfficeZoneId =
+  | "desk"
+  | "meeting-room"
+  | "lounge"
+  | "pantry"
+  | "review-area"
+  | "offstage";
+
+export type AgentGameOfficeAgent = {
+  id: string;
+  name: string;
+  role: string | null;
+  statusLabel: string;
+  activity?: AgentActivityDisplay;
+  activityLabel?: string;
+  sceneState: AgentGameOfficeSceneState;
+  zoneId: AgentGameOfficeZoneId;
+  updatedAt: string;
+  targetPosition?: { x: number; z: number } | null;
+  raw: AgentPresence;
+};
+
+export type AgentGameOfficeSummary = {
+  totalAgents: number;
+  workingAgents: number;
+  meetingAgents: number;
+  restingAgents: number;
+  offlineAgents: number;
+};
+
+export type AgentGameOfficeSnapshot = {
+  agents: AgentGameOfficeAgent[];
+  summary: AgentGameOfficeSummary;
+};
+
+export type AgentGameOfficeSource = {
+  subscribe(listener: (snapshot: AgentGameOfficeSnapshot) => void): () => void;
+};
+
+export type AgentGameOfficeSourceInput =
+  | {
+      type: "snapshot";
+      agents: AgentPresence[];
+    }
+  | {
+      type: "runtime";
+      client: {
+        subscribe(options?: AgentGameRuntimeBrowserSubscribeOptions): Promise<GameRuntimeSubscription>;
+      };
+    }
+  | {
+      type: "custom";
+      source: AgentGameOfficeSource;
+    };
+
+export type AgentGameOfficeRendererController = {
+  update(snapshot: AgentGameOfficeSnapshot): void;
+  focusAgent?(agentId: string | null): void;
+  destroy(): void;
+};
+
+export type AgentGameOfficeRenderer = {
+  mount(
+    container: HTMLElement,
+    initialSnapshot: AgentGameOfficeSnapshot,
+    options: AgentGameOfficeResolvedOptions,
+  ): AgentGameOfficeRendererController | Promise<AgentGameOfficeRendererController>;
+};
+
+export type AgentGameOfficeMountOptions = {
+  renderer?: AgentGameOfficeRendererKind | AgentGameOfficeRenderer;
+  source: AgentGameOfficeSourceInput;
+  focusedAgentId?: string | null;
+  className?: string;
+};
+
+export type AgentGameOfficeResolvedOptions = Omit<AgentGameOfficeMountOptions, "renderer"> & {
+  renderer: AgentGameOfficeRendererKind | AgentGameOfficeRenderer;
+};
+
+export type AgentGameOfficeController = {
+  updateAgents(agents: AgentPresence[]): void;
+  focusAgent(agentId: string | null): void;
+  destroy(): void;
+};

package/src/office/index.ts

@@ -0,0 +1,4 @@
+export * from "./core/types";
+export * from "./core/projection";
+export * from "./core/source";
+export * from "./mount";

package/src/office/mount.ts

@@ -0,0 +1,104 @@
+import {
+  createSnapshotOfficeSource,
+  resolveOfficeSource,
+} from "./core/source";
+import { mergeAgentPresence, type GameRuntimeSubscription } from "../runtime-client";
+import type {
+  AgentGameOfficeMountOptions,
+  AgentGameOfficeRenderer,
+  AgentGameOfficeRendererController,
+  AgentGameOfficeController,
+  AgentGameOfficeSnapshot,
+  AgentPresence,
+} from "./core/types";
+import { mountThreeAgentGameOffice } from "./renderers/three/mount";
+
+export async function mountAgentGameOffice(
+  container: HTMLElement,
+  options: AgentGameOfficeMountOptions,
+): Promise<AgentGameOfficeController> {
+  const renderer = resolveRenderer(options.renderer ?? "three");
+  const mutableSource = options.source.type === "snapshot"
+    ? createSnapshotOfficeSource({ agents: options.source.agents })
+    : null;
+  const runtimeSource = options.source.type === "runtime"
+    ? createSnapshotOfficeSource({ agents: [] })
+    : null;
+  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[] = [];
+
+  const unsubscribe = source.subscribe((snapshot) => {
+    latestSnapshot = snapshot;
+    controller?.update(snapshot);
+  });
+
+  controller = await renderer.mount(container, latestSnapshot ?? emptySnapshot(), {
+    ...options,
+    renderer: options.renderer ?? "three",
+  });
+
+  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);
+        },
+      });
+    } catch (error) {
+      unsubscribe();
+      controller.destroy();
+      throw error;
+    }
+  }
+
+  if (options.focusedAgentId !== undefined) {
+    controller.focusAgent?.(options.focusedAgentId);
+  }
+
+  return {
+    updateAgents(agents: AgentPresence[]) {
+      if (mutableSource) {
+        mutableSource.updateAgents(agents);
+      }
+    },
+    focusAgent(agentId) {
+      controller?.focusAgent?.(agentId);
+    },
+    destroy() {
+      unsubscribe();
+      runtimeSubscription?.close();
+      controller?.destroy();
+      controller = null;
+    },
+  };
+}
+
+function resolveRenderer(
+  renderer: AgentGameOfficeMountOptions["renderer"],
+): AgentGameOfficeRenderer {
+  if (!renderer || renderer === "three") {
+    return { mount: mountThreeAgentGameOffice };
+  }
+  return renderer;
+}
+
+function emptySnapshot(): AgentGameOfficeSnapshot {
+  return {
+    agents: [],
+    summary: {
+      totalAgents: 0,
+      workingAgents: 0,
+      meetingAgents: 0,
+      restingAgents: 0,
+      offlineAgents: 0,
+    },
+  };
+}

package/src/office/react/AgentGameOfficeView.ts

@@ -0,0 +1,58 @@
+import React, { useEffect, useRef } from "react";
+
+import { mountAgentGameOffice } from "../mount";
+import type {
+  AgentGameOfficeController,
+  AgentGameOfficeMountOptions,
+} from "../core/types";
+
+export type AgentGameOfficeViewProps = AgentGameOfficeMountOptions & {
+  className?: string;
+  style?: React.CSSProperties;
+};
+
+export function AgentGameOfficeView({
+  className,
+  style,
+  ...options
+}: AgentGameOfficeViewProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const viewRef = useRef<AgentGameOfficeController | null>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+
+    let disposed = false;
+    void mountAgentGameOffice(container, options).then((view) => {
+      if (disposed) {
+        view.destroy();
+        return;
+      }
+      viewRef.current = view;
+    });
+
+    return () => {
+      disposed = true;
+      viewRef.current?.destroy();
+      viewRef.current = null;
+    };
+  }, [options.renderer, options.source]);
+
+  useEffect(() => {
+    viewRef.current?.focusAgent(options.focusedAgentId ?? null);
+  }, [options.focusedAgentId]);
+
+  return React.createElement("div", {
+    ref: containerRef,
+    className,
+    style: {
+      width: "100%",
+      height: "100%",
+      minHeight: 360,
+      ...style,
+    },
+  });
+}

package/src/office/react/index.ts

@@ -0,0 +1 @@
+export * from "./AgentGameOfficeView";

package/src/office/renderers/three/agent-activity-effects.ts

@@ -0,0 +1,161 @@
+import * as THREE from "three";
+
+import type { AgentGameOfficeAgent } from "../../core/types";
+
+export type AgentActivityEffectMode =
+  | "none"
+  | "typing"
+  | "tool"
+  | "running"
+  | "completion"
+  | "attention";
+
+export type AgentActivityEffects = {
+  group: THREE.Group;
+  typingDots: THREE.Mesh[];
+  toolBlock: THREE.Mesh;
+  runningRing: THREE.Mesh;
+  completionRing: THREE.Mesh;
+};
+
+const typingDotGeometry = new THREE.SphereGeometry(0.055, 12, 8);
+const typingDotMaterial = new THREE.MeshBasicMaterial({ color: 0xe0f2fe });
+const toolBlockGeometry = new THREE.BoxGeometry(0.34, 0.22, 0.08);
+const toolBlockMaterial = new THREE.MeshBasicMaterial({ color: 0x0f172a });
+const ringGeometryCache = new Map<string, THREE.RingGeometry>();
+const ringMaterialCache = new Map<number, THREE.MeshBasicMaterial>();
+
+export function resolveActivityEffectMode(
+  agent: Pick<AgentGameOfficeAgent, "activity" | "activityLabel" | "sceneState">,
+): AgentActivityEffectMode {
+  if (agent.sceneState === "offline" || !agent.activityLabel?.trim()) {
+    return "none";
+  }
+  switch (agent.activity?.kind) {
+    case "replying":
+      return "typing";
+    case "tool":
+      return "tool";
+    case "running":
+      return "running";
+    case "completed":
+    case "replied":
+      return "completion";
+    case "received":
+      return "attention";
+    default:
+      return "none";
+  }
+}
+
+export function createAgentActivityEffects(): AgentActivityEffects {
+  const group = new THREE.Group();
+  const typingDots = [0, 1, 2].map((index) => {
+    const dot = new THREE.Mesh(
+      typingDotGeometry,
+      typingDotMaterial,
+    );
+    dot.position.set(-0.18 + index * 0.18, 1.95, 0.18);
+    dot.visible = false;
+    group.add(dot);
+    return dot;
+  });
+
+  const toolBlock = new THREE.Mesh(
+    toolBlockGeometry,
+    toolBlockMaterial,
+  );
+  toolBlock.position.set(0.48, 1.18, 0.18);
+  toolBlock.visible = false;
+  group.add(toolBlock);
+
+  const runningRing = createRing(0x38bdf8, 0.48, 0.68);
+  const completionRing = createRing(0x22c55e, 0.58, 0.82);
+  group.add(runningRing, completionRing);
+
+  return { group, typingDots, toolBlock, runningRing, completionRing };
+}
+
+export function updateAgentActivityEffects(
+  effects: AgentActivityEffects,
+  agent: AgentGameOfficeAgent,
+  elapsedSeconds: number,
+): void {
+  const mode = resolveActivityEffectMode(agent);
+  hideEffects(effects);
+
+  switch (mode) {
+    case "typing":
+      effects.typingDots.forEach((dot, index) => {
+        dot.visible = true;
+        dot.position.y = 1.95 + Math.abs(Math.sin(elapsedSeconds * 5 + index * 0.7)) * 0.08;
+      });
+      return;
+    case "tool":
+      effects.toolBlock.visible = true;
+      effects.toolBlock.scale.setScalar(1 + Math.sin(elapsedSeconds * 8) * 0.04);
+      return;
+    case "running":
+      effects.runningRing.visible = true;
+      effects.runningRing.rotation.z = elapsedSeconds * 1.8;
+      effects.runningRing.scale.setScalar(1 + Math.sin(elapsedSeconds * 3) * 0.07);
+      return;
+    case "completion":
+      effects.completionRing.visible = true;
+      effects.completionRing.scale.setScalar(1 + Math.abs(Math.sin(elapsedSeconds * 5)) * 0.12);
+      return;
+    case "attention":
+      effects.runningRing.visible = true;
+      effects.runningRing.scale.setScalar(1 + Math.abs(Math.sin(elapsedSeconds * 6)) * 0.16);
+      return;
+    case "none":
+      return;
+  }
+}
+
+function createRing(color: number, innerRadius: number, outerRadius: number): THREE.Mesh {
+  const ring = new THREE.Mesh(
+    getRingGeometry(innerRadius, outerRadius),
+    getRingMaterial(color),
+  );
+  ring.rotation.x = -Math.PI / 2;
+  ring.position.y = 0.04;
+  ring.visible = false;
+  return ring;
+}
+
+function getRingGeometry(innerRadius: number, outerRadius: number): THREE.RingGeometry {
+  const key = `${innerRadius}:${outerRadius}`;
+  const cached = ringGeometryCache.get(key);
+  if (cached) {
+    return cached;
+  }
+  const geometry = new THREE.RingGeometry(innerRadius, outerRadius, 32);
+  ringGeometryCache.set(key, geometry);
+  return geometry;
+}
+
+function getRingMaterial(color: number): THREE.MeshBasicMaterial {
+  const cached = ringMaterialCache.get(color);
+  if (cached) {
+    return cached;
+  }
+  const material = new THREE.MeshBasicMaterial({
+    color,
+    transparent: true,
+    opacity: 0.36,
+    side: THREE.DoubleSide,
+    depthWrite: false,
+  });
+  ringMaterialCache.set(color, material);
+  return material;
+}
+
+function hideEffects(effects: AgentActivityEffects): void {
+  effects.typingDots.forEach((dot) => {
+    dot.visible = false;
+  });
+  effects.toolBlock.visible = false;
+  effects.runningRing.visible = false;
+  effects.completionRing.visible = false;
+}