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

package/README.md

@@ -0,0 +1,99 @@
+# Agent Game SDK
+
+Embeddable agent game views and runtime clients.
+
+## Office View
+
+Framework-neutral mount API:
+
+```ts
+import { AgentGameRuntimeBrowserClient } from "agent-game-sdk";
+import { mountAgentGameOffice } from "agent-game-sdk/office";
+
+const client = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+  tokenPath: "/api/agent-game-runtime-token",
+  accessToken: async () => getScopedToken(),
+});
+
+const view = await mountAgentGameOffice(container, {
+  renderer: "three",
+  source: {
+    type: "runtime",
+    client,
+  },
+});
+
+view.focusAgent("agent-1");
+view.destroy();
+```
+
+React wrapper:
+
+```tsx
+import { AgentGameRuntimeBrowserClient } from "agent-game-sdk";
+import { AgentGameOfficeView } from "agent-game-sdk/office/react";
+
+const client = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+});
+
+export function Office() {
+  return (
+    <AgentGameOfficeView
+      renderer="three"
+      source={{ type: "runtime", client }}
+      style={{ height: 640 }}
+    />
+  );
+}
+```
+
+`agent-game-sdk/office` is renderer and framework neutral. `agent-game-sdk/office/react` is the React-only entrypoint.
+
+Browser clients should call an application BFF endpoint. Keep the AgentOS service API key on the server:
+
+```ts
+import { AgentGameRuntimeServerClient } from "agent-game-sdk";
+
+const client = new AgentGameRuntimeServerClient({
+  baseUrl: process.env.AGENTOS_BASE_URL!,
+  apiKey: process.env.AGENTOS_API_KEY!,
+});
+
+export async function GET() {
+  return Response.json(await client.createRuntimeToken());
+}
+```
+
+## Local Demo
+
+Run the SDK office view demo:
+
+```bash
+AGENTOS_BASE_URL=http://localhost:3000 AGENTOS_API_KEY=... bun run demo
+```
+
+Open `http://localhost:7357`. Set `PORT=7358` or another value to change the port.
+
+## Publish
+
+Publishing is controlled from this SDK package directory. The script bumps the package version, builds the package, runs `npm pack --dry-run`, and then publishes to npm:
+
+```bash
+bun run sdk:publish
+```
+
+The default release is patch. Use `--minor` or `--major` when needed:
+
+```bash
+bun run sdk:publish -- --minor
+```
+
+Use `--dry-run` to validate the next version and package contents without publishing. The script restores the previous version after a dry run.
+
+If npm requires two-factor authentication, pass the one-time password with `--otp`:
+
+```bash
+bun run sdk:publish -- --otp 123456
+```

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@agent-os-lab/agent-game-sdk",
+  "version": "0.1.1",
+  "type": "module",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./office": "./src/office/index.ts",
+    "./office/react": "./src/office/react/index.ts"
+  },
+  "scripts": {
+    "build": "tsc --noEmit -p tsconfig.json",
+    "demo": "bun --env-file=.env.development --hot demo/server.ts",
+    "sdk:publish": "bun scripts/publish-agent-game-sdk.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.184.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "typescript": "latest"
+  },
+  "dependencies": {
+    "phaser": "^3.90.0",
+    "three": "^0.184.0"
+  }
+}

package/src/core/agent-game-store.ts

@@ -0,0 +1,110 @@
+import { applyAgentGameCommand, createAgentGameSnapshot } from "./reducer.js";
+import { validateAgentGameScene, type AgentGameSceneDefinition } from "./scene.js";
+import type { AgentGameCommand } from "./commands.js";
+import type { AgentGameAgent, AgentGameSnapshot } from "./state.js";
+import type {
+  AgentGameConnectionStatus,
+  AgentGameRealtimeCursor,
+  AgentGameRealtimeEvent,
+  AgentGameSnapshotPatch,
+} from "./realtime-events.js";
+
+export type AgentGameStoreListener = (snapshot: AgentGameSnapshot) => void;
+
+export type AgentGameStore = {
+  getSnapshot(): AgentGameSnapshot;
+  getCursor(): AgentGameRealtimeCursor | null;
+  getConnectionStatus(): AgentGameConnectionStatus;
+  dispatch(command: AgentGameCommand): AgentGameSnapshot;
+  applyRemoteEvent(event: AgentGameRealtimeEvent): AgentGameSnapshot;
+  replaceSnapshot(snapshot: AgentGameSnapshot, cursor?: AgentGameRealtimeCursor): AgentGameSnapshot;
+  subscribe(listener: AgentGameStoreListener): () => void;
+};
+
+export function createAgentGameStore(scene: AgentGameSceneDefinition): AgentGameStore {
+  let snapshot = createAgentGameSnapshot(scene);
+  let cursor: AgentGameRealtimeCursor | null = null;
+  let connectionStatus: AgentGameConnectionStatus = { kind: "closed" };
+  const appliedEventIds = new Set<string>();
+  const listeners = new Set<AgentGameStoreListener>();
+
+  const notify = () => {
+    for (const listener of listeners) {
+      listener(snapshot);
+    }
+  };
+
+  return {
+    getSnapshot() {
+      return snapshot;
+    },
+    getCursor() {
+      return cursor;
+    },
+    getConnectionStatus() {
+      return connectionStatus;
+    },
+    dispatch(command) {
+      snapshot = applyAgentGameCommand(snapshot, command);
+      notify();
+      return snapshot;
+    },
+    applyRemoteEvent(event) {
+      if (appliedEventIds.has(event.id)) {
+        return snapshot;
+      }
+      appliedEventIds.add(event.id);
+      cursor = event.cursor;
+
+      switch (event.type) {
+        case "snapshot":
+          snapshot = event.snapshot;
+          break;
+        case "command":
+          snapshot = applyAgentGameCommand(snapshot, event.command);
+          break;
+        case "patch":
+          snapshot = applySnapshotPatch(snapshot, event.patch);
+          break;
+        case "connection":
+          connectionStatus = event.status;
+          break;
+      }
+
+      notify();
+      return snapshot;
+    },
+    replaceSnapshot(nextSnapshot, nextCursor) {
+      snapshot = nextSnapshot;
+      cursor = nextCursor ?? cursor;
+      notify();
+      return snapshot;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+function applySnapshotPatch(snapshot: AgentGameSnapshot, patch: AgentGameSnapshotPatch): AgentGameSnapshot {
+  const agents = { ...snapshot.agents };
+  for (const [agentId, agentPatch] of Object.entries(patch.agents ?? {})) {
+    if (agentPatch === null) {
+      delete agents[agentId];
+      continue;
+    }
+    const current = agents[agentId];
+    if (!current) {
+      continue;
+    }
+    agents[agentId] = { ...current, ...agentPatch } as AgentGameAgent;
+  }
+
+  return {
+    scene: patch.scene ? validateAgentGameScene(patch.scene) : snapshot.scene,
+    agents,
+  };
+}

package/src/core/agent-service-event-adapter.ts

@@ -0,0 +1,20 @@
+import type { AgentGameRealtimeEvent } from "./realtime-events.js";
+import { mapAgentServiceEventToGameCommands, type AgentServiceEventLike } from "./event-adapter.js";
+
+export type MapAgentServiceEventToRealtimeEventsOptions = {
+  nextId: () => string;
+  nextCursor: () => string;
+};
+
+export function mapAgentServiceEventToRealtimeEvents(
+  agentId: string,
+  event: AgentServiceEventLike,
+  options: MapAgentServiceEventToRealtimeEventsOptions,
+): AgentGameRealtimeEvent[] {
+  return mapAgentServiceEventToGameCommands(agentId, event).map((command) => ({
+    id: options.nextId(),
+    cursor: options.nextCursor(),
+    type: "command",
+    command,
+  }));
+}

package/src/core/assets.ts

@@ -0,0 +1,119 @@
+import { AgentGameError } from "./errors.js";
+import type { TiledMapLike } from "./scene.js";
+
+export const REQUIRED_AGENT_AVATAR_ANIMATIONS = [
+  "idle.down",
+  "idle.up",
+  "idle.left",
+  "idle.right",
+  "walk.down",
+  "walk.up",
+  "walk.left",
+  "walk.right",
+  "work.typing",
+  "emote.think",
+  "emote.talk",
+] as const;
+
+export type AgentAvatarAnimationName = (typeof REQUIRED_AGENT_AVATAR_ANIMATIONS)[number];
+export type AgentAvatarAnimationFrames = string | string[];
+
+export type AgentAvatarDefinition = {
+  id: string;
+  imageUrl: string;
+  atlasUrl: string;
+  animations: Partial<Record<AgentAvatarAnimationName, AgentAvatarAnimationFrames>> & Record<string, AgentAvatarAnimationFrames>;
+};
+
+export type AgentGameMapAsset = {
+  key: string;
+  url: string;
+  tilesets: Array<{ key: string; imageUrl: string }>;
+};
+
+export type AgentGameAssetManifest = {
+  avatars: AgentAvatarDefinition[];
+  maps: AgentGameMapAsset[];
+};
+
+export type CreateAgentGameMapAssetFromTiledMapOptions = {
+  key: string;
+  url: string;
+  tiledMap: TiledMapLike;
+};
+
+export function validateAgentAvatarDefinition(avatar: AgentAvatarDefinition): AgentAvatarDefinition {
+  assertNonEmpty(avatar.id, "avatar id");
+  assertNonEmpty(avatar.imageUrl, "avatar image url");
+  assertNonEmpty(avatar.atlasUrl, "avatar atlas url");
+
+  for (const animation of REQUIRED_AGENT_AVATAR_ANIMATIONS) {
+    if (!avatar.animations[animation]) {
+      throw new AgentGameError("missing_animation", `Agent game avatar ${avatar.id} is missing animation: ${animation}`);
+    }
+    const frames = normalizeAgentAvatarAnimationFrames(avatar.animations[animation]);
+    if (frames.length === 0) {
+      throw new AgentGameError("missing_animation", `Agent game avatar ${avatar.id} is missing animation: ${animation}`);
+    }
+  }
+
+  return avatar;
+}
+
+export function normalizeAgentAvatarAnimationFrames(frames: AgentAvatarAnimationFrames | undefined): string[] {
+  if (frames === undefined) {
+    return [];
+  }
+  return Array.isArray(frames) ? frames : [frames];
+}
+
+export function validateAgentGameAssetManifest(manifest: AgentGameAssetManifest): AgentGameAssetManifest {
+  const avatarIds = new Set<string>();
+  for (const avatar of manifest.avatars) {
+    validateAgentAvatarDefinition(avatar);
+    if (avatarIds.has(avatar.id)) {
+      throw new AgentGameError("invalid_asset_manifest", `Duplicate agent game avatar id: ${avatar.id}`);
+    }
+    avatarIds.add(avatar.id);
+  }
+
+  const mapKeys = new Set<string>();
+  for (const map of manifest.maps) {
+    assertNonEmpty(map.key, "map key");
+    assertNonEmpty(map.url, "map url");
+    if (mapKeys.has(map.key)) {
+      throw new AgentGameError("invalid_asset_manifest", `Duplicate agent game map key: ${map.key}`);
+    }
+    mapKeys.add(map.key);
+  }
+
+  return manifest;
+}
+
+export function createAgentGameMapAssetFromTiledMap(options: CreateAgentGameMapAssetFromTiledMapOptions): AgentGameMapAsset {
+  const map: AgentGameMapAsset = {
+    key: options.key,
+    url: options.url,
+    tilesets: (options.tiledMap.tilesets ?? []).map((tileset) => ({
+      key: requireNonEmpty(tileset.name, "tileset name"),
+      imageUrl: requireNonEmpty(tileset.image, "tileset image"),
+    })),
+  };
+
+  assertNonEmpty(map.key, "map key");
+  assertNonEmpty(map.url, "map url");
+  return map;
+}
+
+function requireNonEmpty(value: string | undefined, field: string): string {
+  if (!value || value.trim().length === 0) {
+    throw new AgentGameError("invalid_asset_manifest", `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_asset_manifest", `Agent game ${field} must not be empty`);
+  }
+}

package/src/core/commands.ts

@@ -0,0 +1,42 @@
+export type AgentToolCallStatus = "started" | "succeeded" | "failed";
+export type AgentGameEmotion = "focused" | "happy" | "blocked" | "tired";
+
+export type AgentGameCommand =
+  | {
+      type: "agent.spawn";
+      agentId: string;
+      name: string;
+      avatarId: string;
+      locationId: string;
+    }
+  | {
+      type: "agent.move";
+      agentId: string;
+      locationId: string;
+    }
+  | {
+      type: "agent.work";
+      agentId: string;
+      workstationId: string;
+    }
+  | {
+      type: "agent.think";
+      agentId: string;
+      text?: string;
+    }
+  | {
+      type: "agent.talk";
+      agentId: string;
+      text: string;
+    }
+  | {
+      type: "agent.tool_call";
+      agentId: string;
+      toolName: string;
+      status: AgentToolCallStatus;
+    }
+  | {
+      type: "agent.emote";
+      agentId: string;
+      emotion: AgentGameEmotion;
+    };

package/src/core/errors.ts

@@ -0,0 +1,19 @@
+export type AgentGameErrorCode =
+  | "invalid_scene"
+  | "invalid_asset_manifest"
+  | "missing_agent"
+  | "missing_anchor"
+  | "missing_avatar"
+  | "missing_animation"
+  | "invalid_renderer"
+  | "runtime_destroyed";
+
+export class AgentGameError extends Error {
+  readonly code: AgentGameErrorCode;
+
+  constructor(code: AgentGameErrorCode, message: string) {
+    super(message);
+    this.name = "AgentGameError";
+    this.code = code;
+  }
+}

package/src/core/event-adapter.ts

@@ -0,0 +1,40 @@
+import type { AgentGameCommand } from "./commands.js";
+import { AgentGameError } from "./errors.js";
+
+export type AgentServiceEventLike = {
+  type: string;
+  name?: string;
+  toolName?: string;
+  message?: string;
+  delta?: string;
+};
+
+export function mapAgentServiceEventToGameCommands(
+  agentId: string,
+  event: AgentServiceEventLike,
+): AgentGameCommand[] {
+  switch (event.type) {
+    case "message.started":
+      return [{ type: "agent.think", agentId, text: "Thinking" }];
+    case "message.delta":
+      return [];
+    case "message.completed":
+      return event.message ? [{ type: "agent.talk", agentId, text: event.message }] : [];
+    case "tool.started":
+      return [{ type: "agent.tool_call", agentId, toolName: requireToolName(event), status: "started" }];
+    case "tool.completed":
+      return [{ type: "agent.tool_call", agentId, toolName: requireToolName(event), status: "succeeded" }];
+    case "tool.failed":
+      return [{ type: "agent.tool_call", agentId, toolName: requireToolName(event), status: "failed" }];
+    default:
+      return [];
+  }
+}
+
+function requireToolName(event: AgentServiceEventLike): string {
+  const toolName = event.name ?? event.toolName;
+  if (!toolName) {
+    throw new AgentGameError("invalid_asset_manifest", `Agent service event is missing tool name for ${event.type}`);
+  }
+  return toolName;
+}

package/src/core/index.ts

@@ -0,0 +1,23 @@
+export * from "./assets.js";
+export * from "./agent-game-store.js";
+export * from "./agent-service-event-adapter.js";
+export * from "./commands.js";
+export * from "./event-adapter.js";
+export * from "./errors.js";
+export * from "./life-presets.js";
+export * from "./movement.js";
+export * from "./office-building-layout.js";
+export * from "./office-layout.js";
+export * from "./pixel-character-avatar.js";
+export * from "./pixel-character.js";
+export * from "./reducer.js";
+export * from "./realtime-events.js";
+export * from "./realtime-transport.js";
+export * from "./schedule.js";
+export * from "./scene.js";
+export * from "./sequence.js";
+export * from "./state.js";
+export * from "./svg-pixel-avatar.js";
+export * from "./town-office-assets.js";
+export * from "./town-office-room-presets.js";
+export * from "./town-office-seat-layout.js";

package/src/core/life-presets.ts

@@ -0,0 +1,54 @@
+import type { AgentGameAnchor, AgentGameSceneDefinition } from "./scene.js";
+import { validateAgentGameScene } from "./scene.js";
+
+export type AgentGameLifeSceneKind = "home" | "cafe" | "commute" | "sleep";
+
+export type CreateLifeScenePresetOptions = {
+  id: string;
+  kind: AgentGameLifeSceneKind;
+  mapUrl: string;
+  tilesetImageUrl: string;
+};
+
+export function createLifeScenePreset(options: CreateLifeScenePresetOptions): AgentGameSceneDefinition {
+  return validateAgentGameScene({
+    id: options.id,
+    map: {
+      key: options.id,
+      url: options.mapUrl,
+      tilesets: [{ key: `${options.id}-tiles`, imageUrl: options.tilesetImageUrl }],
+    },
+    anchors: createLifeSceneAnchors(options.kind),
+  });
+}
+
+function createLifeSceneAnchors(kind: AgentGameLifeSceneKind): AgentGameAnchor[] {
+  switch (kind) {
+    case "home":
+      return [
+        { id: "home-spawn", kind: "spawn", x: 80, y: 128, direction: "down" },
+        { id: "home-desk", kind: "desk", x: 208, y: 128, direction: "up" },
+        { id: "home-living", kind: "living", x: 144, y: 224, direction: "down" },
+        { id: "home-sleep", kind: "break", x: 304, y: 96, direction: "left" },
+      ];
+    case "cafe":
+      return [
+        { id: "cafe-spawn", kind: "spawn", x: 64, y: 192, direction: "right" },
+        { id: "cafe-table", kind: "desk", x: 192, y: 160, direction: "down" },
+        { id: "cafe-counter", kind: "meeting", x: 320, y: 112, direction: "up" },
+        { id: "cafe-break", kind: "break", x: 384, y: 224, direction: "left" },
+      ];
+    case "commute":
+      return [
+        { id: "commute-spawn", kind: "spawn", x: 64, y: 160, direction: "right" },
+        { id: "commute-stop", kind: "meeting", x: 224, y: 160, direction: "right" },
+        { id: "commute-seat", kind: "break", x: 352, y: 160, direction: "left" },
+      ];
+    case "sleep":
+      return [
+        { id: "sleep-spawn", kind: "spawn", x: 96, y: 160, direction: "right" },
+        { id: "sleep-room", kind: "living", x: 208, y: 160, direction: "down" },
+        { id: "sleep-bed", kind: "break", x: 320, y: 128, direction: "left" },
+      ];
+  }
+}

package/src/core/movement.ts

@@ -0,0 +1,50 @@
+import { AgentGameError } from "./errors.js";
+import { findAgentGameAnchor } from "./scene.js";
+import type { AgentGameCommand } from "./commands.js";
+import type { AgentGameSnapshot } from "./state.js";
+
+export type CreateAgentGameMovePathCommandsOptions = {
+  agentId: string;
+  locationIds: string[];
+};
+
+export function createAgentGameMovePathCommands(options: CreateAgentGameMovePathCommandsOptions): AgentGameCommand[] {
+  if (options.locationIds.length === 0) {
+    throw new AgentGameError("missing_anchor", "Agent game move path must include at least one waypoint");
+  }
+
+  return options.locationIds.map((locationId) => ({
+    type: "agent.move",
+    agentId: options.agentId,
+    locationId,
+  }));
+}
+
+export function completeAgentGameMove(snapshot: AgentGameSnapshot, agentId: string): AgentGameSnapshot {
+  const agent = snapshot.agents[agentId];
+  if (!agent) {
+    throw new AgentGameError("missing_agent", `Agent game command references missing agent: ${agentId}`);
+  }
+  if (agent.activity.kind !== "moving") {
+    throw new AgentGameError("missing_anchor", `Agent game agent ${agentId} is not moving`);
+  }
+
+  const anchor = findAgentGameAnchor(snapshot.scene, agent.activity.toLocationId);
+  if (!anchor) {
+    throw new AgentGameError("missing_anchor", `Agent game move references missing anchor: ${agent.activity.toLocationId}`);
+  }
+
+  return {
+    scene: snapshot.scene,
+    agents: {
+      ...snapshot.agents,
+      [agentId]: {
+        ...agent,
+        locationId: anchor.id,
+        direction: anchor.direction ?? agent.direction,
+        activity: { kind: "idle" },
+        visibleText: undefined,
+      },
+    },
+  };
+}