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

package/src/core/realtime-events.ts

@@ -0,0 +1,44 @@
+import type { AgentGameCommand } from "./commands.js";
+import type { AgentGameSceneDefinition } from "./scene.js";
+import type { AgentGameAgent, AgentGameSnapshot } from "./state.js";
+
+export type AgentGameRealtimeCursor = string;
+
+export type AgentGameConnectionStatus =
+  | { kind: "connecting" }
+  | { kind: "open" }
+  | { kind: "closed"; reason?: string }
+  | { kind: "error"; message: string };
+
+export type AgentGameAgentPatch = Partial<AgentGameAgent> | null;
+
+export type AgentGameSnapshotPatch = {
+  scene?: AgentGameSceneDefinition;
+  agents?: Record<string, AgentGameAgentPatch>;
+};
+
+export type AgentGameRealtimeEvent =
+  | {
+      id: string;
+      cursor: AgentGameRealtimeCursor;
+      type: "snapshot";
+      snapshot: AgentGameSnapshot;
+    }
+  | {
+      id: string;
+      cursor: AgentGameRealtimeCursor;
+      type: "command";
+      command: AgentGameCommand;
+    }
+  | {
+      id: string;
+      cursor: AgentGameRealtimeCursor;
+      type: "patch";
+      patch: AgentGameSnapshotPatch;
+    }
+  | {
+      id: string;
+      cursor: AgentGameRealtimeCursor;
+      type: "connection";
+      status: AgentGameConnectionStatus;
+    };

package/src/core/realtime-transport.ts

@@ -0,0 +1,39 @@
+import type { AgentGameRealtimeEvent } from "./realtime-events.js";
+
+export type AgentGameTransportMessage = AgentGameRealtimeEvent | AgentGameRealtimeEvent[];
+
+export type AgentGameTransport = {
+  start(): void | Promise<void>;
+  stop(): void | Promise<void>;
+  subscribe(listener: (event: AgentGameRealtimeEvent) => void): () => void;
+};
+
+export type LocalAgentGameTransport = AgentGameTransport & {
+  publish(message: AgentGameTransportMessage): void;
+};
+
+export function createLocalAgentGameTransport(): LocalAgentGameTransport {
+  const listeners = new Set<(event: AgentGameRealtimeEvent) => void>();
+
+  return {
+    start() {},
+    stop() {},
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    publish(message) {
+      for (const event of normalizeAgentGameTransportMessage(message)) {
+        for (const listener of listeners) {
+          listener(event);
+        }
+      }
+    },
+  };
+}
+
+export function normalizeAgentGameTransportMessage(message: AgentGameTransportMessage): AgentGameRealtimeEvent[] {
+  return Array.isArray(message) ? message : [message];
+}

package/src/core/reducer.ts

@@ -0,0 +1,105 @@
+import type { AgentGameCommand } from "./commands.js";
+import { AgentGameError } from "./errors.js";
+import { findAgentGameAnchor, validateAgentGameScene, type AgentGameSceneDefinition } from "./scene.js";
+import type { AgentGameAgent, AgentGameSnapshot } from "./state.js";
+
+export function createAgentGameSnapshot(scene: AgentGameSceneDefinition): AgentGameSnapshot {
+  return {
+    scene: validateAgentGameScene(scene),
+    agents: {},
+  };
+}
+
+export function applyAgentGameCommand(snapshot: AgentGameSnapshot, command: AgentGameCommand): AgentGameSnapshot {
+  const next: AgentGameSnapshot = {
+    scene: snapshot.scene,
+    agents: { ...snapshot.agents },
+  };
+
+  if (command.type === "agent.spawn") {
+    const anchor = requireAnchor(next.scene, command.locationId);
+    next.agents[command.agentId] = {
+      agentId: command.agentId,
+      name: command.name,
+      avatarId: command.avatarId,
+      locationId: command.locationId,
+      direction: anchor.direction ?? "down",
+      activity: { kind: "idle" },
+    };
+    return next;
+  }
+
+  const agent = requireAgent(next, command.agentId);
+
+  switch (command.type) {
+    case "agent.move": {
+      const anchor = requireAnchor(next.scene, command.locationId);
+      next.agents[command.agentId] = {
+        ...agent,
+        locationId: command.locationId,
+        direction: anchor.direction ?? agent.direction,
+        activity: { kind: "moving", toLocationId: command.locationId },
+        visibleText: undefined,
+      };
+      return next;
+    }
+    case "agent.work": {
+      const anchor = requireAnchor(next.scene, command.workstationId);
+      next.agents[command.agentId] = {
+        ...agent,
+        locationId: command.workstationId,
+        direction: anchor.direction ?? agent.direction,
+        activity: { kind: "working", workstationId: command.workstationId },
+        visibleText: undefined,
+      };
+      return next;
+    }
+    case "agent.think": {
+      next.agents[command.agentId] = {
+        ...agent,
+        activity: command.text === undefined ? { kind: "thinking" } : { kind: "thinking", text: command.text },
+        visibleText: command.text,
+      };
+      return next;
+    }
+    case "agent.talk": {
+      next.agents[command.agentId] = {
+        ...agent,
+        activity: { kind: "talking", text: command.text },
+        visibleText: command.text,
+      };
+      return next;
+    }
+    case "agent.tool_call": {
+      next.agents[command.agentId] = {
+        ...agent,
+        activity: { kind: "tool_call", toolName: command.toolName, status: command.status },
+        visibleText: `${command.toolName}: ${command.status}`,
+      };
+      return next;
+    }
+    case "agent.emote": {
+      next.agents[command.agentId] = {
+        ...agent,
+        emotion: command.emotion,
+      };
+      return next;
+    }
+  }
+}
+
+function requireAgent(snapshot: AgentGameSnapshot, agentId: string): AgentGameAgent {
+  const agent = snapshot.agents[agentId];
+  if (!agent) {
+    throw new AgentGameError("missing_agent", `Agent game command references missing agent: ${agentId}`);
+  }
+  return agent;
+}
+
+function requireAnchor(scene: AgentGameSceneDefinition, anchorId: string) {
+  const anchor = findAgentGameAnchor(scene, anchorId);
+  if (!anchor) {
+    throw new AgentGameError("missing_anchor", `Agent game command references missing anchor: ${anchorId}`);
+  }
+  return anchor;
+}

package/src/core/scene.ts

@@ -0,0 +1,144 @@
+import { AgentGameError } from "./errors.js";
+
+export type AgentGameDirection = "up" | "down" | "left" | "right";
+export type AgentGameAnchorKind = "spawn" | "desk" | "meeting" | "break" | "living";
+
+export type AgentGameAnchor = {
+  id: string;
+  kind: AgentGameAnchorKind;
+  x: number;
+  y: number;
+  direction?: AgentGameDirection;
+};
+
+export type AgentGameSceneDefinition = {
+  id: string;
+  map: {
+    key: string;
+    url: string;
+    tilesets: Array<{ key: string; imageUrl: string }>;
+  };
+  anchors: AgentGameAnchor[];
+};
+
+export type TiledMapLike = {
+  layers?: TiledLayerLike[];
+  tilesets?: TiledTilesetLike[];
+};
+
+export type TiledLayerLike = {
+  type?: string;
+  name?: string;
+  objects?: TiledObjectLike[];
+};
+
+export type TiledObjectLike = {
+  name?: string;
+  type?: string;
+  x?: number;
+  y?: number;
+  properties?: Array<{ name?: string; value?: unknown }>;
+};
+
+export type TiledTilesetLike = {
+  name?: string;
+  image?: string;
+};
+
+export type CreateAgentGameSceneFromTiledMapOptions = {
+  id: string;
+  mapUrl: string;
+  tiledMap: TiledMapLike;
+};
+
+export function validateAgentGameScene(scene: AgentGameSceneDefinition): AgentGameSceneDefinition {
+  assertNonEmpty(scene.id, "scene id");
+  assertNonEmpty(scene.map.key, "map key");
+  assertNonEmpty(scene.map.url, "map url");
+
+  const anchorIds = new Set<string>();
+  for (const anchor of scene.anchors) {
+    assertNonEmpty(anchor.id, "anchor id");
+    if (anchorIds.has(anchor.id)) {
+      throw new AgentGameError("invalid_scene", `Duplicate agent game anchor id: ${anchor.id}`);
+    }
+    anchorIds.add(anchor.id);
+  }
+
+  return scene;
+}
+
+export function findAgentGameAnchor(scene: AgentGameSceneDefinition, anchorId: string): AgentGameAnchor | null {
+  return scene.anchors.find((anchor) => anchor.id === anchorId) ?? null;
+}
+
+export function createAgentGameSceneFromTiledMap(options: CreateAgentGameSceneFromTiledMapOptions): AgentGameSceneDefinition {
+  const anchors: AgentGameAnchor[] = [];
+  for (const layer of options.tiledMap.layers ?? []) {
+    if (layer.type !== "objectgroup") {
+      continue;
+    }
+    for (const object of layer.objects ?? []) {
+      if (!object.name || !object.type || object.x === undefined || object.y === undefined) {
+        continue;
+      }
+      anchors.push({
+        id: object.name,
+        kind: parseAnchorKind(object.type),
+        x: object.x,
+        y: object.y,
+        direction: parseOptionalDirection(object.properties),
+      });
+    }
+  }
+
+  return validateAgentGameScene({
+    id: options.id,
+    map: {
+      key: options.id,
+      url: options.mapUrl,
+      tilesets: (options.tiledMap.tilesets ?? []).map((tileset) => ({
+        key: requireTilesetField(tileset.name, "tileset name"),
+        imageUrl: requireTilesetField(tileset.image, "tileset image"),
+      })),
+    },
+    anchors,
+  });
+}
+
+function parseAnchorKind(value: string): AgentGameAnchorKind {
+  switch (value) {
+    case "spawn":
+    case "desk":
+    case "meeting":
+    case "break":
+    case "living":
+      return value;
+    default:
+      throw new AgentGameError("invalid_scene", `Unsupported agent game anchor kind: ${value}`);
+  }
+}
+
+function parseOptionalDirection(properties: TiledObjectLike["properties"]): AgentGameDirection | undefined {
+  const value = properties?.find((property) => property.name === "direction")?.value;
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === "up" || value === "down" || value === "left" || value === "right") {
+    return value;
+  }
+  throw new AgentGameError("invalid_scene", `Unsupported agent game direction: ${String(value)}`);
+}
+
+function requireTilesetField(value: string | undefined, field: string): string {
+  if (!value) {
+    throw new AgentGameError("invalid_scene", `Agent game ${field} must not be empty`);
+  }
+  return value;
+}
+
+function assertNonEmpty(value: string, field: string): void {
+  if (value.trim().length === 0) {
+    throw new AgentGameError("invalid_scene", `Agent game ${field} must not be empty`);
+  }
+}

package/src/core/schedule.ts

@@ -0,0 +1,20 @@
+import type { AgentGameCommand } from "./commands.js";
+
+export type OfficeWorkdaySequenceOptions = {
+  agentId: string;
+  workstationId: string;
+  meetingSpotId: string;
+  breakSpotId: string;
+};
+
+export function createOfficeWorkdaySequence(options: OfficeWorkdaySequenceOptions): AgentGameCommand[] {
+  return [
+    { type: "agent.work", agentId: options.agentId, workstationId: options.workstationId },
+    { type: "agent.think", agentId: options.agentId, text: "Preparing meeting notes" },
+    { type: "agent.move", agentId: options.agentId, locationId: options.meetingSpotId },
+    { type: "agent.talk", agentId: options.agentId, text: "Joining the meeting." },
+    { type: "agent.move", agentId: options.agentId, locationId: options.breakSpotId },
+    { type: "agent.think", agentId: options.agentId, text: "Taking a short break" },
+    { type: "agent.work", agentId: options.agentId, workstationId: options.workstationId },
+  ];
+}

package/src/core/sequence.ts

@@ -0,0 +1,48 @@
+import type { AgentGameCommand } from "./commands.js";
+
+export type PlayAgentGameSequenceOptions = {
+  dispatch: (command: AgentGameCommand) => void;
+  delayMs?: number;
+  signal?: AbortSignal;
+};
+
+export type PlayAgentGameSequenceResult = {
+  completed: boolean;
+  dispatchedCount: number;
+};
+
+export async function playAgentGameSequence(
+  commands: readonly AgentGameCommand[],
+  options: PlayAgentGameSequenceOptions,
+): Promise<PlayAgentGameSequenceResult> {
+  let dispatchedCount = 0;
+
+  for (const command of commands) {
+    if (options.signal?.aborted) {
+      return { completed: false, dispatchedCount };
+    }
+
+    options.dispatch(command);
+    dispatchedCount += 1;
+
+    if (options.signal?.aborted) {
+      return { completed: false, dispatchedCount };
+    }
+
+    if (options.delayMs && options.delayMs > 0) {
+      await delay(options.delayMs, options.signal);
+    }
+  }
+
+  return { completed: true, dispatchedCount };
+}
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      resolve();
+    }, { once: true });
+  });
+}

package/src/core/state.ts

@@ -0,0 +1,26 @@
+import type { AgentGameEmotion, AgentToolCallStatus } from "./commands.js";
+import type { AgentGameDirection, AgentGameSceneDefinition } from "./scene.js";
+
+export type AgentGameActivity =
+  | { kind: "idle" }
+  | { kind: "moving"; toLocationId: string }
+  | { kind: "working"; workstationId: string }
+  | { kind: "thinking"; text?: string }
+  | { kind: "talking"; text: string }
+  | { kind: "tool_call"; toolName: string; status: AgentToolCallStatus };
+
+export type AgentGameAgent = {
+  agentId: string;
+  name: string;
+  avatarId: string;
+  locationId: string;
+  direction: AgentGameDirection;
+  activity: AgentGameActivity;
+  emotion?: AgentGameEmotion;
+  visibleText?: string;
+};
+
+export type AgentGameSnapshot = {
+  scene: AgentGameSceneDefinition;
+  agents: Record<string, AgentGameAgent>;
+};