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

package/src/runtime-client.ts

@@ -0,0 +1,435 @@
+export type AgentPresenceStatus =
+  | "working"
+  | "thinking"
+  | "meeting"
+  | "resting"
+  | "entertaining"
+  | "idle"
+  | "offline";
+
+export type AgentPresenceStatusSource = "runtime" | "simulation" | "system";
+
+export type AgentActivityDisplay = {
+  kind: "received" | "replying" | "replied" | "tool" | "running" | "completed";
+  summary: string;
+  preview?: string;
+  updatedAt: string;
+  expiresAt?: string;
+};
+
+export type AgentPresence = {
+  tenantId: string;
+  agentId: string;
+  displayName: string;
+  status: AgentPresenceStatus;
+  statusSource: AgentPresenceStatusSource;
+  activeRunId?: string;
+  scene?: string;
+  mood?: string;
+  activity?: AgentActivityDisplay;
+  updatedAt: string;
+  expiresAt?: string;
+};
+
+export type GameRuntimeBootstrapStatus = "active" | "pending" | "failed";
+
+export type GameRuntimeSnapshotMessage = {
+  type: "snapshot";
+  tenantId: string;
+  bootstrapStatus: GameRuntimeBootstrapStatus;
+  agents: AgentPresence[];
+  sequence: number;
+  serverTime: string;
+};
+
+export type GameRuntimePatchMessage = {
+  type: "patch";
+  tenantId: string;
+  agents: AgentPresence[];
+  sequence: number;
+  serverTime: string;
+};
+
+export type GameRuntimeServerMessage =
+  | GameRuntimeSnapshotMessage
+  | GameRuntimePatchMessage;
+
+export type GameRuntimeConnectionState = "connecting" | "online" | "closed";
+
+export type GameRuntimeSubscription = {
+  close: () => void;
+  getSocket: () => WebSocket | null;
+};
+
+export type AgentGameRuntimeBrowserClientOptions = {
+  baseUrl: string;
+  tokenPath?: string;
+  fetch?: typeof fetch;
+  accessToken?: string | (() => string | undefined | Promise<string | undefined>);
+  requestId?: string | (() => string | undefined);
+  headers?: HeadersInit | (() => HeadersInit | undefined);
+  WebSocketImpl?: typeof WebSocket;
+};
+
+export type AgentGameRuntimeServerClientOptions = {
+  baseUrl: string;
+  apiKey: string;
+  tokenPath?: string;
+  fetch?: typeof fetch;
+  requestId?: string | (() => string | undefined);
+  headers?: HeadersInit | (() => HeadersInit | undefined);
+};
+
+export type AgentGameRuntimeBrowserRequestOptions = {
+  requestId?: string;
+  signal?: AbortSignal;
+  headers?: HeadersInit;
+};
+
+export type AgentGameRuntimeServerRequestOptions = {
+  requestId?: string;
+  signal?: AbortSignal;
+  headers?: HeadersInit;
+};
+
+export type GameRuntimeTokenResponse = {
+  tenantId: string;
+  publicWsUrl: string;
+  token: string;
+  expiresAt: string;
+};
+
+export type SubscribeGameRuntimeOptions = {
+  tenantId: string;
+  publicWsUrl: string;
+  token: string;
+  pingIntervalMs?: number;
+  WebSocketImpl?: typeof WebSocket;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onError?: (error: Event | Error) => void;
+  onMessage?: (message: GameRuntimeServerMessage) => void;
+  onSnapshot?: (message: GameRuntimeSnapshotMessage) => void;
+  onPatch?: (message: GameRuntimePatchMessage) => void;
+};
+
+export type AgentGameRuntimeBrowserSubscribeOptions =
+  AgentGameRuntimeBrowserRequestOptions &
+  Omit<SubscribeGameRuntimeOptions, "tenantId" | "publicWsUrl" | "token" | "WebSocketImpl">;
+
+export class AgentGameRuntimeBrowserClient {
+  private readonly baseUrl: string;
+  private readonly tokenPath: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly accessToken?: AgentGameRuntimeBrowserClientOptions["accessToken"];
+  private readonly requestId?: AgentGameRuntimeBrowserClientOptions["requestId"];
+  private readonly customHeaders?: AgentGameRuntimeBrowserClientOptions["headers"];
+  private readonly WebSocketImpl?: typeof WebSocket;
+
+  constructor(options: AgentGameRuntimeBrowserClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.tokenPath = options.tokenPath ?? "/api/agent-game-runtime-token";
+    this.fetchImpl = options.fetch ?? boundFetch();
+    this.accessToken = options.accessToken;
+    this.requestId = options.requestId;
+    this.customHeaders = options.headers;
+    this.WebSocketImpl = options.WebSocketImpl;
+  }
+
+  async subscribe(
+    options: AgentGameRuntimeBrowserSubscribeOptions = {},
+  ): Promise<GameRuntimeSubscription> {
+    const tokenResponse = await this.fetchToken(options);
+    return subscribeGameRuntime({
+      ...options,
+      tenantId: tokenResponse.tenantId,
+      publicWsUrl: tokenResponse.publicWsUrl,
+      token: tokenResponse.token,
+      WebSocketImpl: this.WebSocketImpl,
+    });
+  }
+
+  private async fetchToken(
+    options: AgentGameRuntimeBrowserRequestOptions,
+  ): Promise<GameRuntimeTokenResponse> {
+    const response = await this.fetchImpl(this.url(this.tokenPath), {
+      method: "GET",
+      headers: await this.headers(options),
+      signal: options.signal,
+    });
+    if (!response.ok) {
+      throw new Error(`Game runtime token request failed with status ${response.status}.`);
+    }
+    const body = await response.json() as GameRuntimeTokenResponse;
+    if (!isGameRuntimeTokenResponse(body)) {
+      throw new Error("Game runtime token response is invalid.");
+    }
+    return body;
+  }
+
+  private async headers(
+    requestOptions?: AgentGameRuntimeBrowserRequestOptions,
+  ): Promise<Headers> {
+    const headers = safeBrowserHeaders(resolveHeaders(this.customHeaders));
+    mergeSafeBrowserHeaders(headers, requestOptions?.headers);
+    const token = await resolveAccessToken(this.accessToken);
+    if (token) {
+      headers.set("authorization", `Bearer ${token}`);
+    }
+    const requestId = requestOptions?.requestId ?? resolveRequestId(this.requestId);
+    if (requestId) {
+      headers.set("x-hermes-request-id", requestId);
+    }
+    return headers;
+  }
+
+  private url(path: string): string {
+    if (/^https?:\/\//.test(path)) {
+      return path;
+    }
+    return `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  }
+}
+
+export class AgentGameRuntimeServerClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly tokenPath: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly requestId?: AgentGameRuntimeServerClientOptions["requestId"];
+  private readonly customHeaders?: AgentGameRuntimeServerClientOptions["headers"];
+
+  constructor(options: AgentGameRuntimeServerClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.tokenPath = options.tokenPath ?? "/api/v1/game-runtime-token";
+    this.fetchImpl = options.fetch ?? boundFetch();
+    this.requestId = options.requestId;
+    this.customHeaders = options.headers;
+  }
+
+  async createRuntimeToken(
+    options: AgentGameRuntimeServerRequestOptions = {},
+  ): Promise<GameRuntimeTokenResponse> {
+    const response = await this.fetchImpl(this.url(this.tokenPath), {
+      method: "GET",
+      headers: this.headers(options),
+      signal: options.signal,
+    });
+    if (!response.ok) {
+      throw new Error(`Game runtime token request failed with status ${response.status}.`);
+    }
+    const body = await response.json() as GameRuntimeTokenResponse;
+    if (!isGameRuntimeTokenResponse(body)) {
+      throw new Error("Game runtime token response is invalid.");
+    }
+    return body;
+  }
+
+  private headers(requestOptions?: AgentGameRuntimeServerRequestOptions): Headers {
+    const headers = new Headers(resolveHeaders(this.customHeaders));
+    mergeHeaders(headers, requestOptions?.headers);
+    headers.set("authorization", `Bearer ${this.apiKey}`);
+    const requestId = requestOptions?.requestId ?? resolveRequestId(this.requestId);
+    if (requestId) {
+      headers.set("x-hermes-request-id", requestId);
+    }
+    return headers;
+  }
+
+  private url(path: string): string {
+    if (/^https?:\/\//.test(path)) {
+      return path;
+    }
+    return `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+  }
+}
+
+export function subscribeGameRuntime(
+  options: SubscribeGameRuntimeOptions,
+): GameRuntimeSubscription {
+  const WebSocketCtor = options.WebSocketImpl ?? globalThis.WebSocket;
+  if (!WebSocketCtor) {
+    throw new Error("WebSocket is not available in this runtime.");
+  }
+
+  let closed = false;
+  let pingInterval: ReturnType<typeof setInterval> | null = null;
+  const socket = new WebSocketCtor(createGameRuntimeWebSocketUrl(
+    options.publicWsUrl,
+    options.token,
+  ));
+
+  socket.addEventListener("open", () => {
+    if (closed) {
+      return;
+    }
+    options.onOpen?.();
+    socket.send(JSON.stringify({
+      type: "subscribe",
+      tenantId: options.tenantId,
+    }));
+    pingInterval = setInterval(() => {
+      if (socket.readyState === WebSocketCtor.OPEN) {
+        socket.send(JSON.stringify({ type: "ping" }));
+      }
+    }, options.pingIntervalMs ?? 25_000);
+  });
+
+  socket.addEventListener("message", (event) => {
+    const message = parseGameRuntimeMessage(event.data);
+    if (!message || closed) {
+      return;
+    }
+    options.onMessage?.(message);
+    if (message.type === "snapshot") {
+      options.onSnapshot?.(message);
+    } else {
+      options.onPatch?.(message);
+    }
+  });
+
+  socket.addEventListener("close", () => {
+    clearPingInterval();
+    if (!closed) {
+      options.onClose?.();
+    }
+  });
+
+  socket.addEventListener("error", (event) => {
+    if (!closed) {
+      options.onError?.(event);
+    }
+  });
+
+  function clearPingInterval() {
+    if (pingInterval) {
+      clearInterval(pingInterval);
+      pingInterval = null;
+    }
+  }
+
+  return {
+    close: () => {
+      closed = true;
+      clearPingInterval();
+      socket.close();
+    },
+    getSocket: () => socket,
+  };
+}
+
+export function createGameRuntimeWebSocketUrl(
+  publicWsUrl: string,
+  token: string,
+): string {
+  const url = new URL(publicWsUrl);
+  url.searchParams.set("token", token);
+  return url.toString();
+}
+
+export function parseGameRuntimeMessage(
+  value: unknown,
+): GameRuntimeServerMessage | null {
+  try {
+    const parsed = JSON.parse(String(value)) as { type?: string };
+    return parsed.type === "snapshot" || parsed.type === "patch"
+      ? parsed as GameRuntimeServerMessage
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function mergeAgentPresence(
+  current: AgentPresence[],
+  changed: AgentPresence[],
+): AgentPresence[] {
+  const next = new Map(current.map((agent) => [agent.agentId, agent]));
+  for (const agent of changed) {
+    next.set(agent.agentId, agent);
+  }
+  return Array.from(next.values()).sort((left, right) =>
+    left.displayName.localeCompare(right.displayName),
+  );
+}
+
+export function countAgentPresenceStatuses(
+  agents: AgentPresence[],
+): Record<AgentPresenceStatus, number> {
+  const counts = {
+    working: 0,
+    thinking: 0,
+    meeting: 0,
+    resting: 0,
+    entertaining: 0,
+    idle: 0,
+    offline: 0,
+  } satisfies Record<AgentPresenceStatus, number>;
+
+  for (const agent of agents) {
+    counts[agent.status] += 1;
+  }
+  return counts;
+}
+
+function boundFetch(): typeof fetch {
+  return globalThis.fetch.bind(globalThis);
+}
+
+function resolveHeaders(
+  value: AgentGameRuntimeBrowserClientOptions["headers"] | AgentGameRuntimeServerClientOptions["headers"],
+): HeadersInit | undefined {
+  return typeof value === "function" ? value() : value;
+}
+
+async function resolveAccessToken(
+  value: AgentGameRuntimeBrowserClientOptions["accessToken"],
+): Promise<string | undefined> {
+  return typeof value === "function" ? await value() : value;
+}
+
+function resolveRequestId(
+  value: AgentGameRuntimeBrowserClientOptions["requestId"],
+): string | undefined {
+  return typeof value === "function" ? value() : value;
+}
+
+function safeBrowserHeaders(source?: HeadersInit): Headers {
+  const headers = new Headers(source);
+  stripForbiddenBrowserHeaders(headers);
+  return headers;
+}
+
+function mergeSafeBrowserHeaders(target: Headers, source?: HeadersInit): void {
+  const headers = safeBrowserHeaders(source);
+  for (const [key, value] of headers.entries()) {
+    target.set(key, value);
+  }
+}
+
+function mergeHeaders(target: Headers, source?: HeadersInit): void {
+  const headers = new Headers(source);
+  for (const [key, value] of headers.entries()) {
+    target.set(key, value);
+  }
+}
+
+function stripForbiddenBrowserHeaders(headers: Headers): void {
+  headers.delete("authorization");
+  headers.delete("x-hermes-tenant-id");
+  headers.delete("x-agentos-tenant-id");
+}
+
+function isGameRuntimeTokenResponse(value: unknown): value is GameRuntimeTokenResponse {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const response = value as Partial<GameRuntimeTokenResponse>;
+  return (
+    typeof response.tenantId === "string" &&
+    typeof response.publicWsUrl === "string" &&
+    typeof response.token === "string" &&
+    typeof response.expiresAt === "string"
+  );
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+export type AgentGameNodeKind =
+  | "agent"
+  | "profile"
+  | "session"
+  | "memory"
+  | "tool"
+  | "message"
+  | "event";
+
+export type AgentGameNodeStatus = "idle" | "running" | "waiting" | "success" | "error";
+
+export type AgentGameEdgeKind =
+  | "owns"
+  | "runs"
+  | "uses"
+  | "remembers"
+  | "emits"
+  | "calls"
+  | "replies_to"
+  | "custom";
+
+export type AgentGamePoint = {
+  x: number;
+  y: number;
+};
+
+export type AgentGameNode = {
+  id: string;
+  kind: AgentGameNodeKind;
+  label?: string;
+  status?: AgentGameNodeStatus;
+  position?: AgentGamePoint;
+  metadata?: Record<string, unknown>;
+};
+
+export type AgentGameEdge = {
+  id?: string;
+  source: string;
+  target: string;
+  kind: AgentGameEdgeKind;
+  label?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type AgentGameGraph = {
+  nodes: AgentGameNode[];
+  edges: AgentGameEdge[];
+  metadata?: Record<string, unknown>;
+};
+
+export type NormalizedAgentGameNode = Required<Pick<AgentGameNode, "id" | "kind" | "label" | "status" | "metadata">> & {
+  position?: AgentGamePoint;
+};
+
+export type NormalizedAgentGameEdge = Required<Pick<AgentGameEdge, "id" | "source" | "target" | "kind" | "label" | "metadata">>;
+
+export type NormalizedAgentGameGraph = {
+  nodes: NormalizedAgentGameNode[];
+  edges: NormalizedAgentGameEdge[];
+  metadata: Record<string, unknown>;
+};
+
+export type AgentGameSceneNode = NormalizedAgentGameNode & {
+  position: AgentGamePoint;
+};
+
+export type AgentGameSceneEdge = NormalizedAgentGameEdge;
+
+export type AgentGameScene = {
+  nodes: AgentGameSceneNode[];
+  edges: AgentGameSceneEdge[];
+  metadata: Record<string, unknown>;
+};
+
+export type AgentGameSceneOptions = {
+  columnGap?: number;
+  rowGap?: number;
+  origin?: AgentGamePoint;
+  layerOrder?: readonly AgentGameNodeKind[];
+};