@agent-play/sdk 2.0.0 → 3.0.0

package/README.md

@@ -2,6 +2,8 @@
 
 Node.js SDK for **Agent Play**: register agents, stream world state, and call the web UI over HTTP (`RemotePlayWorld`, LangChain helpers, SSE, RPC).
 
+**Incremental world sync** — After `connect()`, call **`getWorldSnapshot()`** for a full parse, or **`subscribeWorldState()`** to follow SSE **`playerChainNotify`** (stable keys + leaf indices) and merge each slice with **`getPlayerChainNode`** using **`mergeSnapshotWithPlayerChainNode`**. Pure merge/parse helpers are exported for custom transports. Server fanout previously carried **`playerChainDelta`** (per-leaf digests); it is now **`playerChainNotify`** + serialized node RPC — a breaking change for anyone parsing Redis payloads or custom SSE clients.
+
 ## Documentation
 
 - **[Repository](https://github.com/wilforlan/agent-play)** — source and monorepo layout  

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Domain types for sessions, journeys, players, and world structures shared by the SDK and server.
+ * Domain types for sessions, journeys, agents, and the shared world map exposed by the SDK and server.
  */
 /** Role for a single line in the interaction log / chat stream. */
 type WorldInteractionRole = "user" | "assistant" | "tool";
@@ -59,16 +59,14 @@ type PlatformAgentInformation = {
  * Use **`langchainRegistration(agent)`** for `agent` (requires a **`chat_tool`** tool; `assist_*`
  * tools are indexed for the watch UI).
  *
- * **`apiKey`** is set on **`RemotePlayWorld`** options, not here. With a registered-agent
- * repository, you may pass **`agentId`** from **`agent-play create`**, or omit it: the server
- * matches an existing agent by **`name`** plus **`agent.toolNames`**, or creates a registered
- * agent when under the account limit. Without Redis, omit **`apiKey`** and **`agentId`**.
+ * **`agentId`** is required: use an id from **`agent-play create`** when the server uses a repository
+ * (with **`apiKey`** from **`RemotePlayWorld`**), or any stable string for local dev without Redis.
  */
 type AddPlayerInput = PlatformAgentInformation & {
     /** Registration from {@link import("./platforms/langchain.js").langchainRegistration}. */
     agent: LangChainAgentRegistration;
-    /** Optional explicit registered agent id when using Redis repository. */
-    agentId?: string;
+    /** Registered agent id (or session-local id without Redis). */
+    agentId: string;
 };
 /** Zone counter event surfaced on snapshots and signals. */
 type ZoneEventInfo = {
@@ -81,29 +79,19 @@ type YieldEventInfo = {
     yieldCount: number;
     at: string;
 };
-/** Kind of world structure tile (home base, tool pad, API, etc.). */
-type WorldStructureKind = "home" | "tool" | "api" | "database" | "model";
-/**
- * One placed structure on the world map for a player.
- *
- * @property id - Stable id (often derived from tool name / layout).
- * @property kind - Visual category.
- * @property x, y - Coordinates in world grid units.
- * @property toolName - When kind is tool-related, the tool name.
- * @property label - Optional human label for the canvas.
- */
-type WorldStructure = {
-    id: string;
-    kind: WorldStructureKind;
-    x: number;
-    y: number;
-    toolName?: string;
-    label?: string;
+/** Repository-backed summary returned with `addPlayer` when the agent is (or maps to) a stored registration. */
+type RegisteredAgentSummary = {
+    agentId: string;
+    name: string;
+    toolNames: string[];
+    zoneCount: number;
+    yieldCount: number;
+    flagged: boolean;
 };
-/** Result of `addPlayer` including watch URL and laid-out structures. */
+/** Result of `addPlayer` including watch URL and registered-agent metadata from the server. */
 type RegisteredPlayer = PlayAgentInformation & {
     previewUrl: string;
-    structures: WorldStructure[];
+    registeredAgent: RegisteredAgentSummary;
 };
 /** First step of a journey: user message origin. */
 type OriginJourneyStep = {
@@ -130,7 +118,7 @@ type JourneyStep = OriginJourneyStep | StructureJourneyStep | DestinationJourney
 /**
  * Ordered journey with timestamps; sent to the server via `recordJourney`.
  *
- * @property steps - Ordered path from origin through structures to destination.
+ * @property steps - Ordered path from origin through tool steps to destination.
  * @property startedAt, completedAt - Wall times for the run (client or server).
  */
 type Journey = {
@@ -144,12 +132,110 @@ type PositionedStep = JourneyStep & {
     y?: number;
     structureId?: string;
 };
-/** Full snapshot row for a journey update (SSE `world:journey`). */
+type AgentPlayWorldMapBounds = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+/**
+ * One agent on the world map. Coordinates are grid positions; the server enforces unique `(x,y)` per occupant.
+ */
+type AgentPlayWorldMapAgentOccupant = {
+    kind: "agent";
+    agentId: string;
+    name: string;
+    x: number;
+    y: number;
+    /**
+     * Integration label from addPlayer `type` (e.g. `langchain`). Populated from the snapshot field `platform`. The legacy wire field `agentType` is deprecated and accepted only for backward compatibility when parsing JSON.
+     */
+    platform?: string;
+    toolNames?: string[];
+    assistToolNames?: string[];
+    assistTools?: AssistToolSpec[];
+    hasChatTool?: boolean;
+    stationary?: boolean;
+    lastUpdate?: unknown;
+    recentInteractions?: Array<{
+        role: WorldInteractionRole;
+        text: string;
+        at: string;
+        seq: number;
+    }>;
+    zoneCount?: number;
+    yieldCount?: number;
+    flagged?: boolean;
+    onZone?: ZoneEventInfo;
+    onYield?: YieldEventInfo;
+};
+/** MCP server shown as a separate map occupant (distinct from LangChain agents). */
+type AgentPlayWorldMapMcpOccupant = {
+    kind: "mcp";
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    url?: string;
+};
+/** Spatial index: axis-aligned bounds plus every agent and MCP registration placed on the grid. */
+type AgentPlayWorldMap = {
+    bounds: AgentPlayWorldMapBounds;
+    occupants: (AgentPlayWorldMapAgentOccupant | AgentPlayWorldMapMcpOccupant)[];
+};
+/**
+ * Session snapshot from {@link import("./lib/remote-play-world.js").RemotePlayWorld.getWorldSnapshot}.
+ * Agents and MCP servers appear only under **`worldMap.occupants`** (no separate `players` list).
+ */
+type AgentPlaySnapshot = {
+    sid: string;
+    worldMap: AgentPlayWorldMap;
+    mcpServers?: Array<{
+        id: string;
+        name: string;
+        url?: string;
+    }>;
+};
+type PlayerChainNotifyNodeRef = {
+    stableKey: string;
+    leafIndex: number;
+    removed?: boolean;
+    updatedAt?: string;
+};
+type PlayerChainFanoutNotify = {
+    updatedAt: string;
+    nodes: PlayerChainNotifyNodeRef[];
+};
+type PlayerChainGenesisStableKey = "__genesis__";
+type PlayerChainHeaderStableKey = "__header__";
+type PlayerChainGenesisNode = {
+    kind: "genesis";
+    stableKey: PlayerChainGenesisStableKey;
+    text: string;
+};
+type PlayerChainHeaderNode = {
+    kind: "header";
+    stableKey: PlayerChainHeaderStableKey;
+    sid: string;
+    bounds: AgentPlayWorldMapBounds;
+};
+type PlayerChainOccupantRemovedNode = {
+    kind: "occupant";
+    stableKey: string;
+    removed: true;
+};
+type PlayerChainOccupantPresentNode = {
+    kind: "occupant";
+    stableKey: string;
+    removed: false;
+    occupant: AgentPlayWorldMapAgentOccupant | AgentPlayWorldMapMcpOccupant;
+};
+type PlayerChainNodeResponse = PlayerChainGenesisNode | PlayerChainHeaderNode | PlayerChainOccupantRemovedNode | PlayerChainOccupantPresentNode;
+/** Full journey + path update (SSE `world:journey`); coordinates are embedded in `path` steps. */
 type WorldJourneyUpdate = {
     playerId: string;
     journey: Journey;
     path: PositionedStep[];
-    structures: WorldStructure[];
 };
 
 /**
@@ -161,8 +247,6 @@ type WorldJourneyUpdate = {
 
 /** Fired when `addPlayer` completes; payload includes snapshot row for the new player. */
 declare const PLAYER_ADDED_EVENT = "world:player_added";
-/** Fired when structures change (sync tools, layout refresh). */
-declare const WORLD_STRUCTURES_EVENT = "world:structures";
 /** Fired for each new chat/interaction line. */
 declare const WORLD_INTERACTION_EVENT = "world:interaction";
 /** Lightweight signals (zone, yield, assist, journey metadata, etc.). */
@@ -193,17 +277,6 @@ type WorldInteractionPayload = {
     at: string;
     seq: number;
 };
-/**
- * Payload for {@link WORLD_STRUCTURES_EVENT}.
- *
- * @property type - Optional agent platform type string.
- */
-type WorldStructuresPayload = {
-    playerId: string;
-    name: string;
-    structures: WorldStructure[];
-    type?: string;
-};
 
 /**
  * Axis-aligned rectangle in world coordinates (grid units). Used by the server to clamp paths
@@ -298,165 +371,71 @@ declare function agentPlayDebug(scope: string, message: string, detail?: unknown
  */
 declare function langchainRegistration(agent: unknown): LangChainAgentRegistration;
 
-/** Options for {@link RemotePlayWorld}: API origin and credentials for RPC calls. */
 type RemotePlayWorldOptions = {
-    /** Web UI base URL (no trailing slash), e.g. `https://host` or `http://127.0.0.1:3000`. */
     baseUrl: string;
-    /** Account API key when the server uses `AgentRepository`; use a non-empty placeholder if none. */
     apiKey: string;
-    /** Optional bearer token for authenticated routes. */
     authToken?: string;
 };
-/**
- * Return value of {@link RemotePlayWorld.hold}: a delayed promise helper for long-running processes.
- */
 type RemotePlayWorldHold = {
-    /**
-     * Sleeps for the given number of seconds (non-negative).
-     *
-     * @remarks **Callers:** integration scripts that must keep the Node process alive after `start()`.
-     * **Callees:** `setTimeout` via `Promise`.
-     */
     for: (seconds: number) => Promise<void>;
 };
 /**
- * HTTP client for Agent Play: starts a session, registers players, records journeys and
- * interactions, and syncs structures. Designed for long-running Node processes with
- * {@link RemotePlayWorld.hold `hold().for()`} to keep the process alive.
- *
- * @remarks **Callers:** user code and SDK examples. All public methods except `constructor` require
- * {@link RemotePlayWorld.start} to have succeeded first (except `start` itself).
+ * HTTP client for the Agent Play web UI: session, snapshot RPC, mutating RPC with `sid`, and optional SSE subscription.
  *
- * **Protocol:** Uses `fetch` to `GET /api/agent-play/session`, `POST /api/agent-play/players`, and
- * `POST /api/agent-play/sdk/rpc` with JSON body `{ op, payload }`, plus MCP registration
- * `POST /api/agent-play/mcp/register`.
+ * Incremental updates: {@link RemotePlayWorld.subscribeWorldState} listens for **`playerChainNotify`** in SSE `data`, then fetches each changed leaf via {@link RemotePlayWorld.getPlayerChainNode} and merges with {@link mergeSnapshotWithPlayerChainNode}.
  */
 declare class RemotePlayWorld {
-    /** Normalized {@link RemotePlayWorldOptions.baseUrl} (no trailing slash). Used for `fetch` base. */
     private readonly apiBase;
-    /** Trimmed account API key; sent on `addPlayer` and implied for RPC auth expectations. */
     private readonly apiKey;
-    /** Optional bearer token merged into request headers when set. */
     private readonly authToken;
-    /** Session id from `GET /api/agent-play/session`; `null` until {@link RemotePlayWorld.start} succeeds. */
     private sid;
-    /** When true, {@link RemotePlayWorld.close} is a no-op and listeners already ran. */
     private closed;
-    /** Unsubscribe callbacks registered via {@link RemotePlayWorld.onClose}. */
     private readonly closeListeners;
-    /**
-     * @param options - Base URL, API key, and optional auth token.
-     * @throws Error if `apiKey` is missing or whitespace-only (see {@link formatMissingApiKeyError}).
-     *
-     * @remarks **Callees:** {@link formatMissingApiKeyError}, {@link normalizeBaseUrl}.
-     */
     constructor(options: RemotePlayWorldOptions);
-    /**
-     * Registers a one-shot listener invoked when {@link RemotePlayWorld.close} runs (e.g. process shutdown).
-     *
-     * @param handler - Synchronous callback; errors are swallowed.
-     * @returns Unsubscribe function that removes this `handler` from the set.
-     *
-     * @remarks **Callers:** user code. **Callees:** `Set.prototype.add` / `delete`.
-     */
     onClose(handler: () => void): () => void;
-    /**
-     * Returns a helper that sleeps for wall-clock seconds (useful for `await world.hold().for(3600)`).
-     *
-     * @remarks **Callers:** user code. **Callees:** {@link formatInvalidHoldSecondsError}.
-     */
     hold(): RemotePlayWorldHold;
-    /**
-     * Authorization header map for requests that only need session cookie or bearer auth.
-     *
-     * @internal
-     * @remarks **Callers:** {@link RemotePlayWorld.start}, {@link RemotePlayWorld.addPlayer} (via headers),
-     * {@link RemotePlayWorld.registerMcp}, and any future GET-only calls.
-     */
     private authHeaders;
-    /**
-     * Headers for JSON `POST` bodies (RPC, players, MCP).
-     *
-     * @internal
-     * @remarks **Callers:** {@link RemotePlayWorld.addPlayer}, {@link RemotePlayWorld.rpc}, {@link RemotePlayWorld.registerMcp}.
-     * **Callees:** {@link authHeaders}.
-     */
     private jsonHeaders;
-    /**
-     * Creates a session and stores `sid` from `GET /api/agent-play/session`.
-     *
-     * @throws Error if the response is not OK or JSON lacks a non-empty `sid` string.
-     *
-     * @remarks **Callers:** user code. **Callees:** `fetch`, {@link isRecord}.
-     */
-    start(): Promise<void>;
-    /**
-     * Marks the client closed and invokes all {@link onClose} listeners once.
-     *
-     * @remarks **Callers:** user code. **Callees:** `Array.from` over {@link closeListeners}.
-     */
+    private mergeAuthFetch;
+    connect(): Promise<void>;
     close(): Promise<void>;
-    /**
-     * @returns Current session id.
-     * @throws Error if {@link RemotePlayWorld.start} has not been called successfully.
-     *
-     * @remarks **Callers:** user code. **Callees:** none.
-     */
     getSessionId(): string;
-    /**
-     * @returns Absolute watch URL for the session (`/agent-play/watch` on `apiBase`). Query `sid` is not appended;
-     * consumers append `?sid=` from {@link getSessionId} when needed.
-     *
-     * @remarks **Callers:** user code. **Callees:** `URL` constructor.
-     */
     getPreviewUrl(): string;
+    getWorldSnapshot(): Promise<AgentPlaySnapshot>;
     /**
-     * Registers a player agent with the server for the current session.
-     *
-     * @param input - Name, type, `agent` registration from {@link langchainRegistration}, optional `agentId`.
-     * @returns Resolved player row with `previewUrl` and `structures`.
-     * @throws Error on HTTP errors or malformed JSON.
-     *
-     * @remarks **Callers:** user code. **Callees:** {@link getSessionId}, `fetch`, `JSON.parse`, {@link parseStructures}.
+     * Fetches one player-chain node (genesis, header, occupant row, or removal) for `stableKey`, same snapshot scope as {@link RemotePlayWorld.getWorldSnapshot}.
      */
-    addPlayer(input: AddPlayerInput): Promise<RegisteredPlayer>;
+    getPlayerChainNode(stableKey: string): Promise<PlayerChainNodeResponse>;
     /**
-     * Appends a chat-style interaction line for a player (RPC `recordInteraction`).
-     *
-     * @remarks **Callers:** user code. **Callees:** {@link rpc}.
+     * Opens the session SSE stream, emits an initial snapshot from {@link RemotePlayWorld.getWorldSnapshot}, then on each **`playerChainNotify`** merges nodes in deterministic order via {@link RemotePlayWorld.getPlayerChainNode}.
      */
+    subscribeWorldState(callbacks: {
+        onSnapshot: (snapshot: AgentPlaySnapshot) => void;
+        onError?: (err: Error) => void;
+    }): {
+        close: () => void;
+    };
+    addPlayer(input: AddPlayerInput): Promise<RegisteredPlayer>;
     recordInteraction(input: RecordInteractionInput): Promise<void>;
-    /**
-     * Records a full journey for a player (RPC `recordJourney`).
-     *
-     * @remarks **Callers:** user code. **Callees:** {@link rpc}.
-     */
     recordJourney(playerId: string, journey: Journey): Promise<void>;
-    /**
-     * Re-syncs layout structures from an ordered tool name list (RPC `syncPlayerStructuresFromTools`).
-     *
-     * @remarks **Callers:** user code. **Callees:** {@link rpc}.
-     */
-    syncPlayerStructuresFromTools(playerId: string, toolNames: string[]): Promise<void>;
-    /**
-     * Registers an MCP server metadata row for the session (HTTP POST, not the same as RPC `op`).
-     *
-     * @returns New registration id string from JSON `{ id }`.
-     *
-     * @remarks **Callers:** user code. **Callees:** `fetch`, {@link getSessionId}, {@link jsonHeaders}.
-     */
     registerMcp(options: {
         name: string;
         url?: string;
     }): Promise<string>;
-    /**
-     * Posts `{ op, payload }` to `/api/agent-play/sdk/rpc?sid=...`.
-     *
-     * @internal
-     * @remarks **Callers:** {@link recordInteraction}, {@link recordJourney}, {@link syncPlayerStructuresFromTools}.
-     * **Callees:** {@link getSessionId}, `fetch`, {@link jsonHeaders}.
-     */
     private rpc;
 }
 
-export { type AddPlayerInput, type AssistToolSpec, type DestinationJourneyStep, type Journey, type JourneyStep, type LangChainAgentRegistration, type OriginJourneyStep, PLAYER_ADDED_EVENT, type PlatformAgentInformation, type PlayAgentInformation, type PositionedStep, type RecordInteractionInput, type RegisteredPlayer, RemotePlayWorld, type RemotePlayWorldHold, type RemotePlayWorldOptions, type StructureJourneyStep, WORLD_AGENT_SIGNAL_EVENT, WORLD_INTERACTION_EVENT, WORLD_JOURNEY_EVENT, WORLD_STRUCTURES_EVENT, type WorldAgentSignalPayload, type WorldBounds, type WorldInteractionPayload, type WorldInteractionRole, type WorldJourneyUpdate, type WorldStructure, type WorldStructureKind, type WorldStructuresPayload, type YieldEventInfo, type ZoneEventInfo, agentPlayDebug, boundsContain, clampWorldPosition, configureAgentPlayDebug, isAgentPlayDebugEnabled, langchainRegistration, resetAgentPlayDebug };
+/**
+ * Parses **`playerChainNotify`** envelopes and merges {@link PlayerChainNodeResponse} slices into {@link AgentPlaySnapshot} (pure functions + fetch ordering for serialized RPC).
+ */
+
+declare function sortNodeRefsForSerializedFetch(nodes: ReadonlyArray<PlayerChainNotifyNodeRef>): PlayerChainNotifyNodeRef[];
+declare function parsePlayerChainFanoutNotify(raw: unknown): PlayerChainFanoutNotify | undefined;
+declare function parsePlayerChainFanoutNotifyFromSsePayload(sseData: unknown): PlayerChainFanoutNotify | undefined;
+declare function parsePlayerChainNodeRpcBody(json: unknown): PlayerChainNodeResponse;
+declare function mergeSnapshotWithPlayerChainNode(snapshot: AgentPlaySnapshot, node: PlayerChainNodeResponse): AgentPlaySnapshot;
+
+declare const PLAYER_CHAIN_GENESIS_STABLE_KEY: "__genesis__";
+declare const PLAYER_CHAIN_HEADER_STABLE_KEY: "__header__";
+
+export { type AddPlayerInput, type AgentPlaySnapshot, type AgentPlayWorldMap, type AgentPlayWorldMapAgentOccupant, type AgentPlayWorldMapBounds, type AgentPlayWorldMapMcpOccupant, type AssistToolSpec, type DestinationJourneyStep, type Journey, type JourneyStep, type LangChainAgentRegistration, type OriginJourneyStep, PLAYER_ADDED_EVENT, PLAYER_CHAIN_GENESIS_STABLE_KEY, PLAYER_CHAIN_HEADER_STABLE_KEY, type PlatformAgentInformation, type PlayAgentInformation, type PlayerChainFanoutNotify, type PlayerChainGenesisNode, type PlayerChainHeaderNode, type PlayerChainNodeResponse, type PlayerChainNotifyNodeRef, type PlayerChainOccupantPresentNode, type PlayerChainOccupantRemovedNode, type PositionedStep, type RecordInteractionInput, type RegisteredAgentSummary, type RegisteredPlayer, RemotePlayWorld, type RemotePlayWorldHold, type RemotePlayWorldOptions, type StructureJourneyStep, WORLD_AGENT_SIGNAL_EVENT, WORLD_INTERACTION_EVENT, WORLD_JOURNEY_EVENT, type WorldAgentSignalPayload, type WorldBounds, type WorldInteractionPayload, type WorldInteractionRole, type WorldJourneyUpdate, type YieldEventInfo, type ZoneEventInfo, agentPlayDebug, boundsContain, clampWorldPosition, configureAgentPlayDebug, isAgentPlayDebugEnabled, langchainRegistration, mergeSnapshotWithPlayerChainNode, parsePlayerChainFanoutNotify, parsePlayerChainFanoutNotifyFromSsePayload, parsePlayerChainNodeRpcBody, resetAgentPlayDebug, sortNodeRefsForSerializedFetch };