@agent-os-lab/agent-game-sdk 0.1.2 → 0.1.3

package/README.md

@@ -2,13 +2,15 @@
 
 Embeddable agent game views and runtime clients.
 
+For the full integration guide, see [USAGE.md](./USAGE.md).
+
 ## Office View
 
 Framework-neutral mount API:
 
 ```ts
-import { AgentGameRuntimeBrowserClient } from "agent-game-sdk";
-import { mountAgentGameOffice } from "agent-game-sdk/office";
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";
 
 const client = new AgentGameRuntimeBrowserClient({
   baseUrl: "",
@@ -31,8 +33,8 @@ view.destroy();
 React wrapper:
 
 ```tsx
-import { AgentGameRuntimeBrowserClient } from "agent-game-sdk";
-import { AgentGameOfficeView } from "agent-game-sdk/office/react";
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
 
 const client = new AgentGameRuntimeBrowserClient({
   baseUrl: "",
@@ -54,7 +56,7 @@ export function Office() {
 Browser clients should call an application BFF endpoint. Keep the AgentOS service API key on the server; the SDK server client forwards it to Agent Game Runtime:
 
 ```ts
-import { AgentGameRuntimeServerClient } from "agent-game-sdk";
+import { AgentGameRuntimeServerClient } from "@agent-os-lab/agent-game-sdk";
 
 const client = new AgentGameRuntimeServerClient({
   baseUrl: process.env.AGENT_GAME_RUNTIME_BASE_URL!,

package/USAGE.md

@@ -0,0 +1,303 @@
+# Agent Game SDK Usage Guide
+
+This document describes how to use `@agent-os-lab/agent-game-sdk` from browser-facing applications and trusted backend services.
+
+## Overview
+
+`@agent-os-lab/agent-game-sdk` provides embeddable agent game views and a browser-safe client for Agent Game Runtime presence streams.
+
+Use it when another application needs to render an AgentOS office view, subscribe to live agent presence, or bridge a trusted backend API key into short-lived runtime tokens for browser clients.
+
+The SDK is intentionally split by responsibility:
+
+- Runtime clients handle token creation and WebSocket subscription.
+- Office view APIs mount a framework-neutral 3D office view into a DOM container.
+- React APIs wrap the same office view for React applications.
+
+## Installation
+
+```bash
+npm install @agent-os-lab/agent-game-sdk
+```
+
+Runtime requirements:
+
+- A modern browser runtime with `fetch`, `Headers`, `Response`, and `WebSocket` for frontend usage.
+- A trusted backend runtime with `fetch` for runtime token proxy endpoints.
+- React 19+ and React DOM 19+ only when using `@agent-os-lab/agent-game-sdk/office/react`.
+
+## Entry Points
+
+```ts
+import {
+  AgentGameRuntimeBrowserClient,
+  AgentGameRuntimeServerClient,
+} from "@agent-os-lab/agent-game-sdk";
+import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";
+import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
+import type { AgentPresence } from "@agent-os-lab/agent-game-sdk/office";
+```
+
+Available entry points:
+
+- `@agent-os-lab/agent-game-sdk`: runtime clients and office exports.
+- `@agent-os-lab/agent-game-sdk/office`: framework-neutral office view APIs and office types.
+- `@agent-os-lab/agent-game-sdk/office/react`: React office view component.
+
+Do not import files from `src/` in application code. Use the published entry points above.
+
+## Authentication Model
+
+Use `AgentGameRuntimeServerClient` only in trusted backend code. It sends the AgentOS service API key as a bearer token to Agent Game Runtime and returns a short-lived runtime token response.
+
+```ts
+import { AgentGameRuntimeServerClient } from "@agent-os-lab/agent-game-sdk";
+
+const serverClient = new AgentGameRuntimeServerClient({
+  baseUrl: process.env.AGENT_GAME_RUNTIME_BASE_URL!,
+  apiKey: process.env.AGENTOS_API_KEY!,
+  requestId: () => crypto.randomUUID(),
+});
+
+export async function GET() {
+  return Response.json(await serverClient.createRuntimeToken());
+}
+```
+
+Do not expose `AGENTOS_API_KEY` or any AgentOS service API key to browser code.
+
+Use `AgentGameRuntimeBrowserClient` in the frontend against a same-origin BFF/proxy endpoint that returns `GameRuntimeTokenResponse`.
+
+```ts
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+
+const browserClient = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+  tokenPath: "/api/agent-game-runtime-token",
+});
+```
+
+If your application backend expects an application-scoped browser token, provide `accessToken`. This token is for your BFF/proxy, not for Agent Game Runtime directly.
+
+```ts
+const browserClient = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+  tokenPath: "/api/agent-game-runtime-token",
+  accessToken: async () => getScopedApplicationToken(),
+});
+```
+
+The browser client strips caller-provided `authorization`, `x-hermes-tenant-id`, and `x-agentos-tenant-id` headers. Only the `accessToken` option may set a browser bearer token.
+
+## Runtime Subscription
+
+Use `subscribe` when the application wants direct access to live runtime messages instead of using the office view.
+
+```ts
+const subscription = await browserClient.subscribe({
+  onSnapshot: (message) => {
+    console.log("snapshot", message.agents);
+  },
+  onPatch: (message) => {
+    console.log("patch", message.agents);
+  },
+  onError: (error) => {
+    console.error("runtime stream error", error);
+  },
+});
+
+subscription.close();
+```
+
+Runtime messages are either:
+
+- `snapshot`: full current presence list for the tenant.
+- `patch`: changed agent presence records.
+
+Use `mergeAgentPresence` when maintaining your own local presence array from snapshots and patches.
+
+```ts
+import { mergeAgentPresence } from "@agent-os-lab/agent-game-sdk";
+
+let agents = [];
+
+await browserClient.subscribe({
+  onSnapshot: (message) => {
+    agents = message.agents;
+  },
+  onPatch: (message) => {
+    agents = mergeAgentPresence(agents, message.agents);
+  },
+});
+```
+
+## Office View
+
+Use `mountAgentGameOffice` for framework-neutral embedding.
+
+```ts
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { mountAgentGameOffice } from "@agent-os-lab/agent-game-sdk/office";
+
+const client = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+  tokenPath: "/api/agent-game-runtime-token",
+});
+
+const view = await mountAgentGameOffice(container, {
+  renderer: "three",
+  source: {
+    type: "runtime",
+    client,
+  },
+});
+
+view.focusAgent("agent-1");
+view.destroy();
+```
+
+`renderer: "three"` is the built-in renderer and the default renderer. The container must have a stable size; the React wrapper supplies a default `minHeight`, but framework-neutral callers should size the container in CSS.
+
+## React Office View
+
+Use `AgentGameOfficeView` when embedding the office view in a React application.
+
+```tsx
+import { AgentGameRuntimeBrowserClient } from "@agent-os-lab/agent-game-sdk";
+import { AgentGameOfficeView } from "@agent-os-lab/agent-game-sdk/office/react";
+
+const client = new AgentGameRuntimeBrowserClient({
+  baseUrl: "",
+});
+
+export function Office() {
+  return (
+    <AgentGameOfficeView
+      renderer="three"
+      source={{ type: "runtime", client }}
+      focusedAgentId="agent-1"
+      style={{ height: 640 }}
+    />
+  );
+}
+```
+
+Keep `source` object identity stable across renders when possible. Recreating `source` every render can remount the view because the React wrapper treats `options.source` as an effect dependency.
+
+## Snapshot Source
+
+Use `source.type: "snapshot"` for demos, tests, static previews, or applications that already have agent presence data.
+
+```ts
+import { mountAgentGameOffice, type AgentPresence } from "@agent-os-lab/agent-game-sdk/office";
+
+const agents: AgentPresence[] = [
+  {
+    tenantId: "tenant-demo",
+    agentId: "agent-1",
+    displayName: "Research Agent",
+    status: "working",
+    statusSource: "simulation",
+    activity: {
+      kind: "running",
+      summary: "Reading customer notes",
+      updatedAt: new Date().toISOString(),
+    },
+    updatedAt: new Date().toISOString(),
+  },
+];
+
+const view = await mountAgentGameOffice(container, {
+  source: {
+    type: "snapshot",
+    agents,
+  },
+});
+
+view.updateAgents([
+  {
+    ...agents[0],
+    status: "meeting",
+    updatedAt: new Date().toISOString(),
+  },
+]);
+```
+
+`updateAgents` only mutates SDK-managed snapshot sources. Runtime and custom sources own their own updates.
+
+## Custom Source
+
+Use `source.type: "custom"` when another state manager already projects runtime state into office snapshots.
+
+```ts
+import type {
+  AgentGameOfficeSnapshot,
+  AgentGameOfficeSource,
+} from "@agent-os-lab/agent-game-sdk/office";
+
+const source: AgentGameOfficeSource = {
+  subscribe(listener: (snapshot: AgentGameOfficeSnapshot) => void) {
+    const unsubscribe = store.subscribe(() => {
+      listener(store.getState().officeSnapshot);
+    });
+    listener(store.getState().officeSnapshot);
+    return unsubscribe;
+  },
+};
+
+await mountAgentGameOffice(container, {
+  source: {
+    type: "custom",
+    source,
+  },
+});
+```
+
+## Agent Presence Shape
+
+Office rendering is driven by `AgentPresence`.
+
+Important fields:
+
+- `tenantId`: tenant that owns the presence record.
+- `agentId`: stable agent identifier.
+- `displayName`: label shown in the office view.
+- `status`: one of `working`, `thinking`, `meeting`, `resting`, `entertaining`, `idle`, or `offline`.
+- `statusSource`: `runtime`, `simulation`, or `system`.
+- `activity`: optional visible activity summary and preview.
+- `updatedAt`: ISO timestamp for the latest presence update.
+- `expiresAt`: optional ISO timestamp after which the presence should be considered stale by the producer.
+
+## Local Demo
+
+Run the SDK office view demo from `agent-game-sdk`:
+
+```bash
+AGENT_GAME_RUNTIME_BASE_URL=http://localhost:3107 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 the 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

@@ -1,10 +1,11 @@
 {
   "name": "@agent-os-lab/agent-game-sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "USAGE.md"
   ],
   "exports": {
     ".": "./src/index.ts",