@agent-play/sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,462 @@
+/**
+ * Domain types for sessions, journeys, players, and world structures shared by the SDK and server.
+ */
+/** Role for a single line in the interaction log / chat stream. */
+type WorldInteractionRole = "user" | "assistant" | "tool";
+/**
+ * Payload for {@link import("./lib/remote-play-world.js").RemotePlayWorld.recordInteraction}.
+ *
+ * @property playerId - Player id returned from `addPlayer`.
+ * @property role - Who "spoke" the line.
+ * @property text - Plain text; may be truncated for display server-side.
+ */
+type RecordInteractionInput = {
+    playerId: string;
+    role: WorldInteractionRole;
+    text: string;
+};
+/**
+ * Metadata for a tool whose name starts with `assist_`, shown as assist actions on the watch UI.
+ *
+ * @property parameters - Derived from Zod object `schema` when present; placeholder hints otherwise.
+ */
+type AssistToolSpec = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+/**
+ * Serializable shape returned by {@link import("./platforms/langchain.js").langchainRegistration} for `addPlayer`.
+ *
+ * @property type - Always `"langchain"` for this adapter.
+ * @property toolNames - All tool names from the agent (must include `chat_tool`).
+ * @property assistTools - Subset of tools with `assist_` prefix, for UI buttons.
+ */
+type LangChainAgentRegistration = {
+    type: "langchain";
+    toolNames: string[];
+    assistTools?: AssistToolSpec[];
+};
+/** Minimal player identity in the SDK (without preview URL). */
+type PlayAgentInformation = {
+    id: string;
+    name: string;
+    sid: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/** Input fields for `addPlayer` before `agent` is attached. */
+type PlatformAgentInformation = {
+    name: string;
+    type: string;
+    version?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+};
+/**
+ * Register a player (agent) in the world.
+ *
+ * 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`**.
+ */
+type AddPlayerInput = PlatformAgentInformation & {
+    /** Registration from {@link import("./platforms/langchain.js").langchainRegistration}. */
+    agent: LangChainAgentRegistration;
+    /** Optional explicit registered agent id when using Redis repository. */
+    agentId?: string;
+};
+/** Zone counter event surfaced on snapshots and signals. */
+type ZoneEventInfo = {
+    zoneCount: number;
+    flagged?: boolean;
+    at: string;
+};
+/** Yield counter event surfaced on snapshots and signals. */
+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;
+};
+/** Result of `addPlayer` including watch URL and laid-out structures. */
+type RegisteredPlayer = PlayAgentInformation & {
+    previewUrl: string;
+    structures: WorldStructure[];
+};
+/** First step of a journey: user message origin. */
+type OriginJourneyStep = {
+    type: "origin";
+    content: string;
+    messageId: string;
+};
+/** Middle step: tool invocation on the map. */
+type StructureJourneyStep = {
+    type: "structure";
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    result?: string;
+};
+/** Final step: assistant reply. */
+type DestinationJourneyStep = {
+    type: "destination";
+    content: string;
+    messageId: string;
+};
+/** Union of journey step shapes. */
+type JourneyStep = OriginJourneyStep | StructureJourneyStep | DestinationJourneyStep;
+/**
+ * Ordered journey with timestamps; sent to the server via `recordJourney`.
+ *
+ * @property steps - Ordered path from origin through structures to destination.
+ * @property startedAt, completedAt - Wall times for the run (client or server).
+ */
+type Journey = {
+    steps: JourneyStep[];
+    startedAt: Date;
+    completedAt: Date;
+};
+/** Journey step after server assigns coordinates (and optional structure id). */
+type PositionedStep = JourneyStep & {
+    x?: number;
+    y?: number;
+    structureId?: string;
+};
+/** Full snapshot row for a journey update (SSE `world:journey`). */
+type WorldJourneyUpdate = {
+    playerId: string;
+    journey: Journey;
+    path: PositionedStep[];
+    structures: WorldStructure[];
+};
+
+/**
+ * String constants and payload shapes for SSE and in-process world events.
+ *
+ * @remarks **Emitters:** server `PlayWorld` and Redis fanout. **Consumers:** watch UI `EventSource`,
+ * integration tests, and any host that forwards `POST` events.
+ */
+
+/** 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.). */
+declare const WORLD_AGENT_SIGNAL_EVENT = "world:agent_signal";
+/** Full journey + path update for a player. */
+declare const WORLD_JOURNEY_EVENT = "world:journey";
+/**
+ * Payload for {@link WORLD_AGENT_SIGNAL_EVENT}.
+ *
+ * @property playerId - Target player.
+ * @property kind - Signal category; `journey` often carries `{ stepCount }` in `data`.
+ * @property data - Optional free-form metadata.
+ */
+type WorldAgentSignalPayload = {
+    playerId: string;
+    kind: "zone" | "yield" | "assist" | "chat" | "metadata" | "journey";
+    data?: Record<string, unknown>;
+};
+/**
+ * Payload for {@link WORLD_INTERACTION_EVENT}.
+ *
+ * @property seq - Monotonic sequence for ordering in the UI.
+ */
+type WorldInteractionPayload = {
+    playerId: string;
+    role: WorldInteractionRole;
+    text: string;
+    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
+ * and by the watch UI to clamp joystick-driven movement.
+ *
+ * @remarks **Consumers:** {@link clampWorldPosition}, {@link boundsContain}; server `PlayWorld` and
+ * play-ui canvas both import these helpers from `@agent-play/sdk`.
+ */
+type WorldBounds = {
+    /** Inclusive minimum X. */
+    minX: number;
+    /** Inclusive minimum Y. */
+    minY: number;
+    /** Inclusive maximum X. */
+    maxX: number;
+    /** Inclusive maximum Y. */
+    maxY: number;
+};
+/**
+ * Clamps a point to lie inside `bounds` along both axes.
+ *
+ * @param p - Position with `x` and `y` in world units.
+ * @param bounds - Valid rectangle (`min` ≤ `max` per axis).
+ * @returns Same point if inside, otherwise clamped to the nearest edge.
+ *
+ * @remarks **Callers:** server `PlayWorld` path enrichment; play-ui joystick and preview. **Callees:** `Math.min/Math.max`.
+ */
+declare function clampWorldPosition(p: {
+    x: number;
+    y: number;
+}, bounds: WorldBounds): {
+    x: number;
+    y: number;
+};
+/**
+ * @returns Whether `p` lies inside or on the border of `bounds`.
+ *
+ * @remarks **Callers:** optional UI checks. **Callees:** none.
+ */
+declare function boundsContain(bounds: WorldBounds, p: {
+    x: number;
+    y: number;
+}): boolean;
+
+/**
+ * Optional structured `console.debug` for SDK internals; gated by {@link configureAgentPlayDebug} or `AGENT_PLAY_DEBUG=1`.
+ */
+type DebugConfigure = {
+    /** When set, overrides environment: `true` forces debug on, `false` forces off. */
+    debug?: boolean;
+};
+/**
+ * Sets whether SDK debug logging is enabled regardless of `AGENT_PLAY_DEBUG`.
+ *
+ * @param opts.debug - `true` / `false` to force; omit to clear override.
+ *
+ * @remarks **Callers:** tests and user code. **Callees:** none.
+ */
+declare function configureAgentPlayDebug(opts: DebugConfigure): void;
+/**
+ * Clears the in-memory override so only `AGENT_PLAY_DEBUG` applies.
+ *
+ * @remarks **Callers:** tests. **Callees:** none.
+ */
+declare function resetAgentPlayDebug(): void;
+/**
+ * @returns Whether debug logging should run: override wins, else `AGENT_PLAY_DEBUG === "1"`.
+ *
+ * @remarks **Callers:** {@link agentPlayDebug}. **Callees:** `process.env` read.
+ */
+declare function isAgentPlayDebugEnabled(): boolean;
+/**
+ * Emits `console.debug` when {@link isAgentPlayDebugEnabled} is true.
+ *
+ * @param scope - Short label (e.g. `"langchain"`).
+ * @param message - Human-readable message.
+ * @param detail - Optional object serialized by {@link safeSerialize}.
+ *
+ * @remarks **Callers:** {@link langchainRegistration} and other SDK modules. **Callees:** {@link isAgentPlayDebugEnabled}, {@link safeSerialize}.
+ */
+declare function agentPlayDebug(scope: string, message: string, detail?: unknown): void;
+
+/**
+ * Validates a LangChain-style agent exposes tools (including required `chat_tool`) and returns
+ * a {@link LangChainAgentRegistration} for `addPlayer`.
+ *
+ * @param agent - Return value from `createAgent` (or equivalent) with a `tools` array.
+ * @throws Error if tools are missing or `chat_tool` is not present.
+ *
+ * @remarks **Callers:** user code before `RemotePlayWorld.addPlayer`. **Callees:** {@link extractToolsArray},
+ * {@link formatMissingAgentToolsError}, {@link formatMissingChatToolError}, {@link describeTool}, {@link agentPlayDebug}.
+ */
+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).
+ *
+ * **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`.
+ */
+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}.
+     */
+    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;
+    /**
+     * 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}.
+     */
+    addPlayer(input: AddPlayerInput): Promise<RegisteredPlayer>;
+    /**
+     * Appends a chat-style interaction line for a player (RPC `recordInteraction`).
+     *
+     * @remarks **Callers:** user code. **Callees:** {@link rpc}.
+     */
+    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 };

package/dist/index.js

@@ -0,0 +1,485 @@
+// src/world-events.ts
+var PLAYER_ADDED_EVENT = "world:player_added";
+var WORLD_STRUCTURES_EVENT = "world:structures";
+var WORLD_INTERACTION_EVENT = "world:interaction";
+var WORLD_AGENT_SIGNAL_EVENT = "world:agent_signal";
+var WORLD_JOURNEY_EVENT = "world:journey";
+
+// src/lib/world-bounds.ts
+function clampWorldPosition(p, bounds) {
+  return {
+    x: Math.min(Math.max(p.x, bounds.minX), bounds.maxX),
+    y: Math.min(Math.max(p.y, bounds.minY), bounds.maxY)
+  };
+}
+function boundsContain(bounds, p) {
+  return p.x >= bounds.minX && p.x <= bounds.maxX && p.y >= bounds.minY && p.y <= bounds.maxY;
+}
+
+// src/lib/agent-play-debug.ts
+var configuredDebug;
+function configureAgentPlayDebug(opts) {
+  configuredDebug = opts.debug ?? void 0;
+}
+function resetAgentPlayDebug() {
+  configuredDebug = void 0;
+}
+function isAgentPlayDebugEnabled() {
+  if (configuredDebug === false) return false;
+  if (configuredDebug === true) return true;
+  return process.env.AGENT_PLAY_DEBUG === "1";
+}
+var MAX_JSON_LENGTH = 2e3;
+function safeSerialize(detail) {
+  if (detail === void 0) return "";
+  try {
+    const seen = /* @__PURE__ */ new WeakSet();
+    const json = JSON.stringify(detail, (_k, v) => {
+      if (typeof v === "object" && v !== null) {
+        if (seen.has(v)) return "[Circular]";
+        seen.add(v);
+      }
+      if (typeof v === "bigint") return String(v);
+      return v;
+    });
+    if (typeof json !== "string") return String(detail);
+    return json.length > MAX_JSON_LENGTH ? `${json.slice(0, MAX_JSON_LENGTH)}\u2026` : json;
+  } catch {
+    return String(detail);
+  }
+}
+function agentPlayDebug(scope, message, detail) {
+  if (!isAgentPlayDebugEnabled()) return;
+  const tail = detail === void 0 ? "" : ` ${safeSerialize(detail)}`;
+  console.debug(`[agent-play:${scope}] ${message}${tail}`);
+}
+
+// src/platforms/langchain.ts
+var CHAT_TOOL = "chat_tool";
+function formatMissingAgentToolsError() {
+  return [
+    "langchainRegistration: expected a LangChain agent with a tools array.",
+    "",
+    "  Pass the object returned from createAgent({ tools: [...] }) (or equivalent) so tool names are available for the play world.",
+    '  The tools array must include named tools; see the separate message if "chat_tool" or assist_* tools are missing.'
+  ].join("\n");
+}
+function formatMissingChatToolError() {
+  return [
+    'langchainRegistration: missing required tool "chat_tool".',
+    "",
+    '  Add a tool named "chat_tool" to your LangChain agent so the play world can show chat and proximity interactions.',
+    '  Example: tool(() => "\u2026", { name: "chat_tool", description: "\u2026", schema: z.object({ \u2026 }) })',
+    "",
+    '  Tools whose names start with "assist_" are listed as assist actions on the watch UI; give each a Zod object schema so parameters can be shown in the UI.'
+  ].join("\n");
+}
+function parametersFromSchema(schema) {
+  if (schema === null || typeof schema !== "object") {
+    return {};
+  }
+  const z = schema;
+  if (typeof z._def?.shape !== "function") {
+    return { _note: "Pass a Zod object schema on each tool for parameter hints in the watch UI." };
+  }
+  const shape = z._def.shape();
+  const out = {};
+  for (const key of Object.keys(shape)) {
+    out[key] = { field: key };
+  }
+  return out;
+}
+function describeTool(t) {
+  return {
+    name: t.name,
+    description: typeof t.description === "string" && t.description.length > 0 ? t.description : t.name,
+    parameters: parametersFromSchema(t.schema)
+  };
+}
+function extractToolsArray(agent) {
+  if (typeof agent !== "object" || agent === null) {
+    return null;
+  }
+  const a = agent;
+  if (Array.isArray(a.tools)) {
+    return a.tools;
+  }
+  if (a.options !== void 0 && typeof a.options === "object" && a.options !== null && "tools" in a.options && Array.isArray(a.options.tools)) {
+    return a.options.tools;
+  }
+  return null;
+}
+function langchainRegistration(agent) {
+  const rawTools = extractToolsArray(agent);
+  if (rawTools === null) {
+    throw new Error(formatMissingAgentToolsError());
+  }
+  const tools = rawTools;
+  const names = tools.map((x) => x.name);
+  if (!names.includes(CHAT_TOOL)) {
+    throw new Error(formatMissingChatToolError());
+  }
+  const assistTools = tools.filter((t) => t.name.startsWith("assist_")).map((t) => describeTool(t));
+  agentPlayDebug("langchain", "langchainRegistration", {
+    toolCount: names.length,
+    assistCount: assistTools.length
+  });
+  return {
+    type: "langchain",
+    toolNames: names,
+    assistTools
+  };
+}
+
+// src/lib/remote-play-world.ts
+function formatMissingApiKeyError() {
+  return [
+    "RemotePlayWorld: options.apiKey is required.",
+    "",
+    "  Register an agent with `agent-play create` (after `agent-play login`) and use the printed API key.",
+    "  Pass it here so addPlayer can authenticate against the server repository when Redis is enabled.",
+    "  If the server has no agent repository (local dev), still pass a non-empty placeholder string."
+  ].join("\n");
+}
+function normalizeBaseUrl(url) {
+  return url.replace(/\/$/, "");
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+var STRUCTURE_KINDS = [
+  "home",
+  "tool",
+  "api",
+  "database",
+  "model"
+];
+function isWorldStructureKind(s) {
+  return STRUCTURE_KINDS.includes(s);
+}
+function parseWorldStructure(x) {
+  if (!isRecord(x)) return null;
+  if (typeof x.id !== "string" || typeof x.kind !== "string") return null;
+  if (!isWorldStructureKind(x.kind)) return null;
+  if (typeof x.x !== "number" || typeof x.y !== "number") return null;
+  const out = {
+    id: x.id,
+    kind: x.kind,
+    x: x.x,
+    y: x.y
+  };
+  if (typeof x.toolName === "string") out.toolName = x.toolName;
+  if (typeof x.label === "string") out.label = x.label;
+  return out;
+}
+function parseStructures(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const x of v) {
+    const row = parseWorldStructure(x);
+    if (row !== null) out.push(row);
+  }
+  return out;
+}
+function formatInvalidHoldSecondsError() {
+  return [
+    "RemotePlayWorld.hold().for(seconds): seconds must be a finite number.",
+    "",
+    "  Example: await world.hold().for(3600)"
+  ].join("\n");
+}
+var RemotePlayWorld = class {
+  /** Normalized {@link RemotePlayWorldOptions.baseUrl} (no trailing slash). Used for `fetch` base. */
+  apiBase;
+  /** Trimmed account API key; sent on `addPlayer` and implied for RPC auth expectations. */
+  apiKey;
+  /** Optional bearer token merged into request headers when set. */
+  authToken;
+  /** Session id from `GET /api/agent-play/session`; `null` until {@link RemotePlayWorld.start} succeeds. */
+  sid = null;
+  /** When true, {@link RemotePlayWorld.close} is a no-op and listeners already ran. */
+  closed = false;
+  /** Unsubscribe callbacks registered via {@link RemotePlayWorld.onClose}. */
+  closeListeners = /* @__PURE__ */ new Set();
+  /**
+   * @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) {
+    if (typeof options.apiKey !== "string" || options.apiKey.trim().length === 0) {
+      throw new Error(formatMissingApiKeyError());
+    }
+    this.apiBase = normalizeBaseUrl(options.baseUrl);
+    this.apiKey = options.apiKey.trim();
+    this.authToken = options.authToken;
+  }
+  /**
+   * 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) {
+    this.closeListeners.add(handler);
+    return () => {
+      this.closeListeners.delete(handler);
+    };
+  }
+  /**
+   * Returns a helper that sleeps for wall-clock seconds (useful for `await world.hold().for(3600)`).
+   *
+   * @remarks **Callers:** user code. **Callees:** {@link formatInvalidHoldSecondsError}.
+   */
+  hold() {
+    return {
+      for: async (seconds) => {
+        if (typeof seconds !== "number" || !Number.isFinite(seconds)) {
+          throw new Error(formatInvalidHoldSecondsError());
+        }
+        const ms = Math.max(0, seconds) * 1e3;
+        await new Promise((resolve) => {
+          setTimeout(resolve, ms);
+        });
+      }
+    };
+  }
+  /**
+   * 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.
+   */
+  authHeaders() {
+    if (this.authToken === void 0) return {};
+    return { Authorization: `Bearer ${this.authToken}` };
+  }
+  /**
+   * Headers for JSON `POST` bodies (RPC, players, MCP).
+   *
+   * @internal
+   * @remarks **Callers:** {@link RemotePlayWorld.addPlayer}, {@link RemotePlayWorld.rpc}, {@link RemotePlayWorld.registerMcp}.
+   * **Callees:** {@link authHeaders}.
+   */
+  jsonHeaders() {
+    return {
+      "content-type": "application/json",
+      ...this.authHeaders()
+    };
+  }
+  /**
+   * 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}.
+   */
+  async start() {
+    const res = await fetch(`${this.apiBase}/api/agent-play/session`, {
+      headers: this.authHeaders()
+    });
+    if (!res.ok) {
+      throw new Error(`session failed: ${res.status}`);
+    }
+    const json = await res.json();
+    if (!isRecord(json) || typeof json.sid !== "string" || json.sid.length === 0) {
+      throw new Error("session: invalid response");
+    }
+    this.sid = json.sid;
+  }
+  /**
+   * Marks the client closed and invokes all {@link onClose} listeners once.
+   *
+   * @remarks **Callers:** user code. **Callees:** `Array.from` over {@link closeListeners}.
+   */
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    for (const handler of Array.from(this.closeListeners)) {
+      try {
+        handler();
+      } catch {
+      }
+    }
+  }
+  /**
+   * @returns Current session id.
+   * @throws Error if {@link RemotePlayWorld.start} has not been called successfully.
+   *
+   * @remarks **Callers:** user code. **Callees:** none.
+   */
+  getSessionId() {
+    if (this.sid === null) {
+      throw new Error("RemotePlayWorld.start() must be called first");
+    }
+    return this.sid;
+  }
+  /**
+   * @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() {
+    const u = new URL("/agent-play/watch", this.apiBase);
+    u.search = "";
+    return u.toString();
+  }
+  /**
+   * 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}.
+   */
+  async addPlayer(input) {
+    const sid = this.getSessionId();
+    const url = `${this.apiBase}/api/agent-play/players?sid=${encodeURIComponent(sid)}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify({
+        name: input.name,
+        type: input.type,
+        agent: input.agent,
+        apiKey: this.apiKey,
+        agentId: input.agentId
+      })
+    });
+    const bodyText = await res.text();
+    if (!res.ok) {
+      throw new Error(`addPlayer: ${res.status} ${bodyText}`);
+    }
+    let json;
+    try {
+      json = JSON.parse(bodyText);
+    } catch {
+      throw new Error("addPlayer: invalid JSON");
+    }
+    if (!isRecord(json)) {
+      throw new Error("addPlayer: invalid response shape");
+    }
+    const playerId = json.playerId;
+    const previewUrl = json.previewUrl;
+    if (typeof playerId !== "string" || typeof previewUrl !== "string") {
+      throw new Error("addPlayer: missing playerId or previewUrl");
+    }
+    const structures = parseStructures(json.structures);
+    const now = /* @__PURE__ */ new Date();
+    return {
+      id: playerId,
+      name: input.name,
+      sid,
+      createdAt: now,
+      updatedAt: now,
+      previewUrl,
+      structures
+    };
+  }
+  /**
+   * Appends a chat-style interaction line for a player (RPC `recordInteraction`).
+   *
+   * @remarks **Callers:** user code. **Callees:** {@link rpc}.
+   */
+  async recordInteraction(input) {
+    await this.rpc("recordInteraction", {
+      playerId: input.playerId,
+      role: input.role,
+      text: input.text
+    });
+  }
+  /**
+   * Records a full journey for a player (RPC `recordJourney`).
+   *
+   * @remarks **Callers:** user code. **Callees:** {@link rpc}.
+   */
+  async recordJourney(playerId, journey) {
+    await this.rpc("recordJourney", { playerId, journey });
+  }
+  /**
+   * Re-syncs layout structures from an ordered tool name list (RPC `syncPlayerStructuresFromTools`).
+   *
+   * @remarks **Callers:** user code. **Callees:** {@link rpc}.
+   */
+  async syncPlayerStructuresFromTools(playerId, toolNames) {
+    await this.rpc("syncPlayerStructuresFromTools", { playerId, toolNames });
+  }
+  /**
+   * 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}.
+   */
+  async registerMcp(options) {
+    const sid = this.getSessionId();
+    const url = `${this.apiBase}/api/agent-play/mcp/register?sid=${encodeURIComponent(sid)}`;
+    const body = { name: options.name };
+    if (options.url !== void 0) {
+      body.url = options.url;
+    }
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify(body)
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`registerMcp: ${res.status} ${text}`);
+    }
+    let json;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error("registerMcp: invalid JSON");
+    }
+    if (!isRecord(json) || typeof json.id !== "string") {
+      throw new Error("registerMcp: invalid response");
+    }
+    return json.id;
+  }
+  /**
+   * 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}.
+   */
+  async rpc(op, payload) {
+    const sid = this.getSessionId();
+    const url = `${this.apiBase}/api/agent-play/sdk/rpc?sid=${encodeURIComponent(sid)}`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify({ op, payload })
+    });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new Error(`rpc ${op}: ${res.status} ${t}`);
+    }
+  }
+};
+export {
+  PLAYER_ADDED_EVENT,
+  RemotePlayWorld,
+  WORLD_AGENT_SIGNAL_EVENT,
+  WORLD_INTERACTION_EVENT,
+  WORLD_JOURNEY_EVENT,
+  WORLD_STRUCTURES_EVENT,
+  agentPlayDebug,
+  boundsContain,
+  clampWorldPosition,
+  configureAgentPlayDebug,
+  isAgentPlayDebugEnabled,
+  langchainRegistration,
+  resetAgentPlayDebug
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/world-events.ts","../src/lib/world-bounds.ts","../src/lib/agent-play-debug.ts","../src/platforms/langchain.ts","../src/lib/remote-play-world.ts"],"sourcesContent":["/**\n * String constants and payload shapes for SSE and in-process world events.\n *\n * @remarks **Emitters:** server `PlayWorld` and Redis fanout. **Consumers:** watch UI `EventSource`,\n * integration tests, and any host that forwards `POST` events.\n */\nimport type { WorldInteractionRole, WorldStructure } from \"./public-types.js\";\n\n/** Fired when `addPlayer` completes; payload includes snapshot row for the new player. */\nexport const PLAYER_ADDED_EVENT = \"world:player_added\";\n\n/** Fired when structures change (sync tools, layout refresh). */\nexport const WORLD_STRUCTURES_EVENT = \"world:structures\";\n\n/** Fired for each new chat/interaction line. */\nexport const WORLD_INTERACTION_EVENT = \"world:interaction\";\n\n/** Lightweight signals (zone, yield, assist, journey metadata, etc.). */\nexport const WORLD_AGENT_SIGNAL_EVENT = \"world:agent_signal\";\n\n/** Full journey + path update for a player. */\nexport const WORLD_JOURNEY_EVENT = \"world:journey\";\n\n/**\n * Payload for {@link WORLD_AGENT_SIGNAL_EVENT}.\n *\n * @property playerId - Target player.\n * @property kind - Signal category; `journey` often carries `{ stepCount }` in `data`.\n * @property data - Optional free-form metadata.\n */\nexport type WorldAgentSignalPayload = {\n  playerId: string;\n  kind: \"zone\" | \"yield\" | \"assist\" | \"chat\" | \"metadata\" | \"journey\";\n  data?: Record<string, unknown>;\n};\n\n/**\n * Payload for {@link WORLD_INTERACTION_EVENT}.\n *\n * @property seq - Monotonic sequence for ordering in the UI.\n */\nexport type WorldInteractionPayload = {\n  playerId: string;\n  role: WorldInteractionRole;\n  text: string;\n  at: string;\n  seq: number;\n};\n\n/**\n * Payload for {@link WORLD_STRUCTURES_EVENT}.\n *\n * @property type - Optional agent platform type string.\n */\nexport type WorldStructuresPayload = {\n  playerId: string;\n  name: string;\n  structures: WorldStructure[];\n  type?: string;\n};\n","/**\n * Axis-aligned rectangle in world coordinates (grid units). Used by the server to clamp paths\n * and by the watch UI to clamp joystick-driven movement.\n *\n * @remarks **Consumers:** {@link clampWorldPosition}, {@link boundsContain}; server `PlayWorld` and\n * play-ui canvas both import these helpers from `@agent-play/sdk`.\n */\nexport type WorldBounds = {\n  /** Inclusive minimum X. */\n  minX: number;\n  /** Inclusive minimum Y. */\n  minY: number;\n  /** Inclusive maximum X. */\n  maxX: number;\n  /** Inclusive maximum Y. */\n  maxY: number;\n};\n\n/**\n * Clamps a point to lie inside `bounds` along both axes.\n *\n * @param p - Position with `x` and `y` in world units.\n * @param bounds - Valid rectangle (`min` ≤ `max` per axis).\n * @returns Same point if inside, otherwise clamped to the nearest edge.\n *\n * @remarks **Callers:** server `PlayWorld` path enrichment; play-ui joystick and preview. **Callees:** `Math.min/Math.max`.\n */\nexport function clampWorldPosition(\n  p: { x: number; y: number },\n  bounds: WorldBounds\n): { x: number; y: number } {\n  return {\n    x: Math.min(Math.max(p.x, bounds.minX), bounds.maxX),\n    y: Math.min(Math.max(p.y, bounds.minY), bounds.maxY),\n  };\n}\n\n/**\n * @returns Whether `p` lies inside or on the border of `bounds`.\n *\n * @remarks **Callers:** optional UI checks. **Callees:** none.\n */\nexport function boundsContain(\n  bounds: WorldBounds,\n  p: { x: number; y: number }\n): boolean {\n  return (\n    p.x >= bounds.minX &&\n    p.x <= bounds.maxX &&\n    p.y >= bounds.minY &&\n    p.y <= bounds.maxY\n  );\n}\n","/**\n * Optional structured `console.debug` for SDK internals; gated by {@link configureAgentPlayDebug} or `AGENT_PLAY_DEBUG=1`.\n */\ntype DebugConfigure = {\n  /** When set, overrides environment: `true` forces debug on, `false` forces off. */\n  debug?: boolean;\n};\n\n/**\n * In-memory override for debug enablement (undefined = follow env only).\n *\n * @remarks **Writers:** {@link configureAgentPlayDebug}, {@link resetAgentPlayDebug}.\n * **Readers:** {@link isAgentPlayDebugEnabled}.\n */\nlet configuredDebug: boolean | undefined;\n\n/**\n * Sets whether SDK debug logging is enabled regardless of `AGENT_PLAY_DEBUG`.\n *\n * @param opts.debug - `true` / `false` to force; omit to clear override.\n *\n * @remarks **Callers:** tests and user code. **Callees:** none.\n */\nexport function configureAgentPlayDebug(opts: DebugConfigure): void {\n  configuredDebug = opts.debug ?? undefined;\n}\n\n/**\n * Clears the in-memory override so only `AGENT_PLAY_DEBUG` applies.\n *\n * @remarks **Callers:** tests. **Callees:** none.\n */\nexport function resetAgentPlayDebug(): void {\n  configuredDebug = undefined;\n}\n\n/**\n * @returns Whether debug logging should run: override wins, else `AGENT_PLAY_DEBUG === \"1\"`.\n *\n * @remarks **Callers:** {@link agentPlayDebug}. **Callees:** `process.env` read.\n */\nexport function isAgentPlayDebugEnabled(): boolean {\n  if (configuredDebug === false) return false;\n  if (configuredDebug === true) return true;\n  return process.env.AGENT_PLAY_DEBUG === \"1\";\n}\n\n/** Max length of JSON detail string before truncation in {@link safeSerialize}. */\nconst MAX_JSON_LENGTH = 2000;\n\n/**\n * Serializes `detail` for log lines, truncating long JSON and handling circular refs.\n *\n * @internal\n * @remarks **Callers:** {@link agentPlayDebug} only. **Callees:** `JSON.stringify` with replacer.\n */\nfunction safeSerialize(detail: unknown): string {\n  if (detail === undefined) return \"\";\n  try {\n    const seen = new WeakSet<object>();\n    const json = JSON.stringify(detail, (_k, v: unknown) => {\n      if (typeof v === \"object\" && v !== null) {\n        if (seen.has(v)) return \"[Circular]\";\n        seen.add(v);\n      }\n      if (typeof v === \"bigint\") return String(v);\n      return v;\n    });\n    if (typeof json !== \"string\") return String(detail);\n    return json.length > MAX_JSON_LENGTH\n      ? `${json.slice(0, MAX_JSON_LENGTH)}…`\n      : json;\n  } catch {\n    return String(detail);\n  }\n}\n\n/**\n * Emits `console.debug` when {@link isAgentPlayDebugEnabled} is true.\n *\n * @param scope - Short label (e.g. `\"langchain\"`).\n * @param message - Human-readable message.\n * @param detail - Optional object serialized by {@link safeSerialize}.\n *\n * @remarks **Callers:** {@link langchainRegistration} and other SDK modules. **Callees:** {@link isAgentPlayDebugEnabled}, {@link safeSerialize}.\n */\nexport function agentPlayDebug(\n  scope: string,\n  message: string,\n  detail?: unknown\n): void {\n  if (!isAgentPlayDebugEnabled()) return;\n  const tail =\n    detail === undefined ? \"\" : ` ${safeSerialize(detail)}`;\n  console.debug(`[agent-play:${scope}] ${message}${tail}`);\n}\n","/**\n * LangChain adapter: derives tool names and assist metadata from a LangChain agent for\n * {@link import(\"../public-types.js\").LangChainAgentRegistration}.\n *\n * @remarks **Primary export:** {@link langchainRegistration}. Private helpers build error strings and\n * `AssistToolSpec` rows from Zod schemas when available.\n */\nimport { agentPlayDebug } from \"../lib/agent-play-debug.js\";\nimport type { AssistToolSpec, LangChainAgentRegistration } from \"../public-types.js\";\n\n/** Required tool name enforced by the watch UI contract. */\nconst CHAT_TOOL = \"chat_tool\";\n\n/**\n * Error text when the agent has no `tools` array.\n *\n * @remarks **Callers:** {@link langchainRegistration}. **Callees:** none.\n */\nfunction formatMissingAgentToolsError(): string {\n  return [\n    \"langchainRegistration: expected a LangChain agent with a tools array.\",\n    \"\",\n    \"  Pass the object returned from createAgent({ tools: [...] }) (or equivalent) so tool names are available for the play world.\",\n    \"  The tools array must include named tools; see the separate message if \\\"chat_tool\\\" or assist_* tools are missing.\",\n  ].join(\"\\n\");\n}\n\n/**\n * Error text when `chat_tool` is missing from tool names.\n *\n * @remarks **Callers:** {@link langchainRegistration}. **Callees:** none.\n */\nfunction formatMissingChatToolError(): string {\n  return [\n    \"langchainRegistration: missing required tool \\\"chat_tool\\\".\",\n    \"\",\n    \"  Add a tool named \\\"chat_tool\\\" to your LangChain agent so the play world can show chat and proximity interactions.\",\n    \"  Example: tool(() => \\\"…\\\", { name: \\\"chat_tool\\\", description: \\\"…\\\", schema: z.object({ … }) })\",\n    \"\",\n    \"  Tools whose names start with \\\"assist_\\\" are listed as assist actions on the watch UI; give each a Zod object schema so parameters can be shown in the UI.\",\n  ].join(\"\\n\");\n}\n\n/**\n * Best-effort parameter shape from a Zod object schema’s `shape()` for UI hints.\n *\n * @remarks **Callers:** {@link describeTool}. **Callees:** none.\n */\nfunction parametersFromSchema(schema: unknown): Record<string, unknown> {\n  if (schema === null || typeof schema !== \"object\") {\n    return {};\n  }\n  const z = schema as {\n    _def?: { typeName?: string; shape?: () => Record<string, unknown> };\n  };\n  if (typeof z._def?.shape !== \"function\") {\n    return { _note: \"Pass a Zod object schema on each tool for parameter hints in the watch UI.\" };\n  }\n  const shape = z._def.shape();\n  const out: Record<string, unknown> = {};\n  for (const key of Object.keys(shape)) {\n    out[key] = { field: key };\n  }\n  return out;\n}\n\n/**\n * Builds an {@link AssistToolSpec} from a LangChain tool descriptor.\n *\n * @remarks **Callers:** {@link langchainRegistration} for `assist_*` tools only. **Callees:** {@link parametersFromSchema}.\n */\nfunction describeTool(t: {\n  name: string;\n  description?: string;\n  schema?: unknown;\n}): AssistToolSpec {\n  return {\n    name: t.name,\n    description:\n      typeof t.description === \"string\" && t.description.length > 0\n        ? t.description\n        : t.name,\n    parameters: parametersFromSchema(t.schema),\n  };\n}\n\n/**\n * Reads `agent.tools` or `agent.options.tools` from common LangChain agent shapes.\n *\n * @returns The tools array, or `null` if not found.\n *\n * @remarks **Callers:** {@link langchainRegistration} only. **Callees:** none.\n */\nfunction extractToolsArray(agent: unknown): unknown[] | null {\n  if (typeof agent !== \"object\" || agent === null) {\n    return null;\n  }\n  const a = agent as {\n    tools?: unknown;\n    options?: { tools?: unknown };\n  };\n  if (Array.isArray(a.tools)) {\n    return a.tools;\n  }\n  if (\n    a.options !== undefined &&\n    typeof a.options === \"object\" &&\n    a.options !== null &&\n    \"tools\" in a.options &&\n    Array.isArray((a.options as { tools: unknown }).tools)\n  ) {\n    return (a.options as { tools: unknown[] }).tools;\n  }\n  return null;\n}\n\n/**\n * Validates a LangChain-style agent exposes tools (including required `chat_tool`) and returns\n * a {@link LangChainAgentRegistration} for `addPlayer`.\n *\n * @param agent - Return value from `createAgent` (or equivalent) with a `tools` array.\n * @throws Error if tools are missing or `chat_tool` is not present.\n *\n * @remarks **Callers:** user code before `RemotePlayWorld.addPlayer`. **Callees:** {@link extractToolsArray},\n * {@link formatMissingAgentToolsError}, {@link formatMissingChatToolError}, {@link describeTool}, {@link agentPlayDebug}.\n */\nexport function langchainRegistration(\n  agent: unknown\n): LangChainAgentRegistration {\n  const rawTools = extractToolsArray(agent);\n  if (rawTools === null) {\n    throw new Error(formatMissingAgentToolsError());\n  }\n  const tools =\n    rawTools as readonly { name: string; description?: string; schema?: unknown }[];\n  const names = tools.map((x) => x.name);\n  if (!names.includes(CHAT_TOOL)) {\n    throw new Error(formatMissingChatToolError());\n  }\n  const assistTools = tools\n    .filter((t) => t.name.startsWith(\"assist_\"))\n    .map((t) => describeTool(t));\n  agentPlayDebug(\"langchain\", \"langchainRegistration\", {\n    toolCount: names.length,\n    assistCount: assistTools.length,\n  });\n  return {\n    type: \"langchain\",\n    toolNames: names,\n    assistTools,\n  };\n}\n","import type {\n  AddPlayerInput,\n  Journey,\n  RecordInteractionInput,\n  RegisteredPlayer,\n  WorldStructure,\n  WorldStructureKind,\n} from \"../public-types.js\";\n\n/** Options for {@link RemotePlayWorld}: API origin and credentials for RPC calls. */\nexport type RemotePlayWorldOptions = {\n  /** Web UI base URL (no trailing slash), e.g. `https://host` or `http://127.0.0.1:3000`. */\n  baseUrl: string;\n  /** Account API key when the server uses `AgentRepository`; use a non-empty placeholder if none. */\n  apiKey: string;\n  /** Optional bearer token for authenticated routes. */\n  authToken?: string;\n};\n\n/**\n * Builds the error string thrown when {@link RemotePlayWorld}'s constructor receives an empty `apiKey`.\n *\n * @remarks **Callers:** {@link RemotePlayWorld} constructor only.\n * **Callees:** none.\n */\nfunction formatMissingApiKeyError(): string {\n  return [\n    'RemotePlayWorld: options.apiKey is required.',\n    \"\",\n    \"  Register an agent with `agent-play create` (after `agent-play login`) and use the printed API key.\",\n    \"  Pass it here so addPlayer can authenticate against the server repository when Redis is enabled.\",\n    \"  If the server has no agent repository (local dev), still pass a non-empty placeholder string.\",\n  ].join(\"\\n\");\n}\n\n/**\n * Strips a single trailing slash from a base URL for consistent `fetch` URL construction.\n *\n * @remarks **Callers:** {@link RemotePlayWorld} constructor.\n * **Callees:** none.\n */\nfunction normalizeBaseUrl(url: string): string {\n  return url.replace(/\\/$/, \"\");\n}\n\n/**\n * Narrowing type guard for plain object records.\n *\n * @remarks **Callers:** JSON response parsing in {@link RemotePlayWorld.start}, {@link RemotePlayWorld.addPlayer},\n * {@link RemotePlayWorld.registerMcp}, and structure parsing helpers.\n */\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n  return typeof v === \"object\" && v !== null;\n}\n\nconst STRUCTURE_KINDS: readonly WorldStructureKind[] = [\n  \"home\",\n  \"tool\",\n  \"api\",\n  \"database\",\n  \"model\",\n];\n\n/**\n * @remarks **Callers:** {@link parseWorldStructure}.\n */\nfunction isWorldStructureKind(s: string): s is WorldStructureKind {\n  return (STRUCTURE_KINDS as readonly string[]).includes(s);\n}\n\n/**\n * Parses one server JSON structure into {@link WorldStructure} or `null` if invalid.\n *\n * @remarks **Callers:** {@link parseStructures}.\n * **Callees:** {@link isRecord}, {@link isWorldStructureKind}.\n */\nfunction parseWorldStructure(x: unknown): WorldStructure | null {\n  if (!isRecord(x)) return null;\n  if (typeof x.id !== \"string\" || typeof x.kind !== \"string\") return null;\n  if (!isWorldStructureKind(x.kind)) return null;\n  if (typeof x.x !== \"number\" || typeof x.y !== \"number\") return null;\n  const out: WorldStructure = {\n    id: x.id,\n    kind: x.kind,\n    x: x.x,\n    y: x.y,\n  };\n  if (typeof x.toolName === \"string\") out.toolName = x.toolName;\n  if (typeof x.label === \"string\") out.label = x.label;\n  return out;\n}\n\n/**\n * Parses `structures` JSON array from `addPlayer` response.\n *\n * @remarks **Callers:** {@link RemotePlayWorld.addPlayer}.\n * **Callees:** {@link parseWorldStructure}.\n */\nfunction parseStructures(v: unknown): WorldStructure[] {\n  if (!Array.isArray(v)) return [];\n  const out: WorldStructure[] = [];\n  for (const x of v) {\n    const row = parseWorldStructure(x);\n    if (row !== null) out.push(row);\n  }\n  return out;\n}\n\n/**\n * Error message for invalid `seconds` in {@link RemotePlayWorld.hold}.\n *\n * @remarks **Callers:** {@link RemotePlayWorld.hold `hold().for()`} only.\n */\nfunction formatInvalidHoldSecondsError(): string {\n  return [\n    \"RemotePlayWorld.hold().for(seconds): seconds must be a finite number.\",\n    \"\",\n    \"  Example: await world.hold().for(3600)\",\n  ].join(\"\\n\");\n}\n\n/**\n * Return value of {@link RemotePlayWorld.hold}: a delayed promise helper for long-running processes.\n */\nexport type RemotePlayWorldHold = {\n  /**\n   * Sleeps for the given number of seconds (non-negative).\n   *\n   * @remarks **Callers:** integration scripts that must keep the Node process alive after `start()`.\n   * **Callees:** `setTimeout` via `Promise`.\n   */\n  for: (seconds: number) => Promise<void>;\n};\n\n/**\n * HTTP client for Agent Play: starts a session, registers players, records journeys and\n * interactions, and syncs structures. Designed for long-running Node processes with\n * {@link RemotePlayWorld.hold `hold().for()`} to keep the process alive.\n *\n * @remarks **Callers:** user code and SDK examples. All public methods except `constructor` require\n * {@link RemotePlayWorld.start} to have succeeded first (except `start` itself).\n *\n * **Protocol:** Uses `fetch` to `GET /api/agent-play/session`, `POST /api/agent-play/players`, and\n * `POST /api/agent-play/sdk/rpc` with JSON body `{ op, payload }`, plus MCP registration\n * `POST /api/agent-play/mcp/register`.\n */\nexport class RemotePlayWorld {\n  /** Normalized {@link RemotePlayWorldOptions.baseUrl} (no trailing slash). Used for `fetch` base. */\n  private readonly apiBase: string;\n  /** Trimmed account API key; sent on `addPlayer` and implied for RPC auth expectations. */\n  private readonly apiKey: string;\n  /** Optional bearer token merged into request headers when set. */\n  private readonly authToken: string | undefined;\n  /** Session id from `GET /api/agent-play/session`; `null` until {@link RemotePlayWorld.start} succeeds. */\n  private sid: string | null = null;\n  /** When true, {@link RemotePlayWorld.close} is a no-op and listeners already ran. */\n  private closed = false;\n  /** Unsubscribe callbacks registered via {@link RemotePlayWorld.onClose}. */\n  private readonly closeListeners = new Set<() => void>();\n\n  /**\n   * @param options - Base URL, API key, and optional auth token.\n   * @throws Error if `apiKey` is missing or whitespace-only (see {@link formatMissingApiKeyError}).\n   *\n   * @remarks **Callees:** {@link formatMissingApiKeyError}, {@link normalizeBaseUrl}.\n   */\n  constructor(options: RemotePlayWorldOptions) {\n    if (typeof options.apiKey !== \"string\" || options.apiKey.trim().length === 0) {\n      throw new Error(formatMissingApiKeyError());\n    }\n    this.apiBase = normalizeBaseUrl(options.baseUrl);\n    this.apiKey = options.apiKey.trim();\n    this.authToken = options.authToken;\n  }\n\n  /**\n   * Registers a one-shot listener invoked when {@link RemotePlayWorld.close} runs (e.g. process shutdown).\n   *\n   * @param handler - Synchronous callback; errors are swallowed.\n   * @returns Unsubscribe function that removes this `handler` from the set.\n   *\n   * @remarks **Callers:** user code. **Callees:** `Set.prototype.add` / `delete`.\n   */\n  onClose(handler: () => void): () => void {\n    this.closeListeners.add(handler);\n    return () => {\n      this.closeListeners.delete(handler);\n    };\n  }\n\n  /**\n   * Returns a helper that sleeps for wall-clock seconds (useful for `await world.hold().for(3600)`).\n   *\n   * @remarks **Callers:** user code. **Callees:** {@link formatInvalidHoldSecondsError}.\n   */\n  hold(): RemotePlayWorldHold {\n    return {\n      for: async (seconds: number) => {\n        if (typeof seconds !== \"number\" || !Number.isFinite(seconds)) {\n          throw new Error(formatInvalidHoldSecondsError());\n        }\n        const ms = Math.max(0, seconds) * 1000;\n        await new Promise<void>((resolve) => {\n          setTimeout(resolve, ms);\n        });\n      },\n    };\n  }\n\n  /**\n   * Authorization header map for requests that only need session cookie or bearer auth.\n   *\n   * @internal\n   * @remarks **Callers:** {@link RemotePlayWorld.start}, {@link RemotePlayWorld.addPlayer} (via headers),\n   * {@link RemotePlayWorld.registerMcp}, and any future GET-only calls.\n   */\n  private authHeaders(): Record<string, string> {\n    if (this.authToken === undefined) return {};\n    return { Authorization: `Bearer ${this.authToken}` };\n  }\n\n  /**\n   * Headers for JSON `POST` bodies (RPC, players, MCP).\n   *\n   * @internal\n   * @remarks **Callers:** {@link RemotePlayWorld.addPlayer}, {@link RemotePlayWorld.rpc}, {@link RemotePlayWorld.registerMcp}.\n   * **Callees:** {@link authHeaders}.\n   */\n  private jsonHeaders(): Record<string, string> {\n    return {\n      \"content-type\": \"application/json\",\n      ...this.authHeaders(),\n    };\n  }\n\n  /**\n   * Creates a session and stores `sid` from `GET /api/agent-play/session`.\n   *\n   * @throws Error if the response is not OK or JSON lacks a non-empty `sid` string.\n   *\n   * @remarks **Callers:** user code. **Callees:** `fetch`, {@link isRecord}.\n   */\n  async start(): Promise<void> {\n    const res = await fetch(`${this.apiBase}/api/agent-play/session`, {\n      headers: this.authHeaders(),\n    });\n    if (!res.ok) {\n      throw new Error(`session failed: ${res.status}`);\n    }\n    const json: unknown = await res.json();\n    if (!isRecord(json) || typeof json.sid !== \"string\" || json.sid.length === 0) {\n      throw new Error(\"session: invalid response\");\n    }\n    this.sid = json.sid;\n  }\n\n  /**\n   * Marks the client closed and invokes all {@link onClose} listeners once.\n   *\n   * @remarks **Callers:** user code. **Callees:** `Array.from` over {@link closeListeners}.\n   */\n  async close(): Promise<void> {\n    if (this.closed) {\n      return;\n    }\n    this.closed = true;\n    for (const handler of Array.from(this.closeListeners)) {\n      try {\n        handler();\n      } catch {\n        // ignore listener errors\n      }\n    }\n  }\n\n  /**\n   * @returns Current session id.\n   * @throws Error if {@link RemotePlayWorld.start} has not been called successfully.\n   *\n   * @remarks **Callers:** user code. **Callees:** none.\n   */\n  getSessionId(): string {\n    if (this.sid === null) {\n      throw new Error(\"RemotePlayWorld.start() must be called first\");\n    }\n    return this.sid;\n  }\n\n  /**\n   * @returns Absolute watch URL for the session (`/agent-play/watch` on `apiBase`). Query `sid` is not appended;\n   * consumers append `?sid=` from {@link getSessionId} when needed.\n   *\n   * @remarks **Callers:** user code. **Callees:** `URL` constructor.\n   */\n  getPreviewUrl(): string {\n    const u = new URL(\"/agent-play/watch\", this.apiBase);\n    u.search = \"\";\n    return u.toString();\n  }\n\n  /**\n   * Registers a player agent with the server for the current session.\n   *\n   * @param input - Name, type, `agent` registration from {@link langchainRegistration}, optional `agentId`.\n   * @returns Resolved player row with `previewUrl` and `structures`.\n   * @throws Error on HTTP errors or malformed JSON.\n   *\n   * @remarks **Callers:** user code. **Callees:** {@link getSessionId}, `fetch`, `JSON.parse`, {@link parseStructures}.\n   */\n  async addPlayer(input: AddPlayerInput): Promise<RegisteredPlayer> {\n    const sid = this.getSessionId();\n    const url = `${this.apiBase}/api/agent-play/players?sid=${encodeURIComponent(sid)}`;\n    const res = await fetch(url, {\n      method: \"POST\",\n      headers: this.jsonHeaders(),\n      body: JSON.stringify({\n        name: input.name,\n        type: input.type,\n        agent: input.agent,\n        apiKey: this.apiKey,\n        agentId: input.agentId,\n      }),\n    });\n    const bodyText = await res.text();\n    if (!res.ok) {\n      throw new Error(`addPlayer: ${res.status} ${bodyText}`);\n    }\n    let json: unknown;\n    try {\n      json = JSON.parse(bodyText) as unknown;\n    } catch {\n      throw new Error(\"addPlayer: invalid JSON\");\n    }\n    if (!isRecord(json)) {\n      throw new Error(\"addPlayer: invalid response shape\");\n    }\n    const playerId = json.playerId;\n    const previewUrl = json.previewUrl;\n    if (typeof playerId !== \"string\" || typeof previewUrl !== \"string\") {\n      throw new Error(\"addPlayer: missing playerId or previewUrl\");\n    }\n    const structures = parseStructures(json.structures);\n    const now = new Date();\n    return {\n      id: playerId,\n      name: input.name,\n      sid,\n      createdAt: now,\n      updatedAt: now,\n      previewUrl,\n      structures,\n    };\n  }\n\n  /**\n   * Appends a chat-style interaction line for a player (RPC `recordInteraction`).\n   *\n   * @remarks **Callers:** user code. **Callees:** {@link rpc}.\n   */\n  async recordInteraction(input: RecordInteractionInput): Promise<void> {\n    await this.rpc(\"recordInteraction\", {\n      playerId: input.playerId,\n      role: input.role,\n      text: input.text,\n    });\n  }\n\n  /**\n   * Records a full journey for a player (RPC `recordJourney`).\n   *\n   * @remarks **Callers:** user code. **Callees:** {@link rpc}.\n   */\n  async recordJourney(playerId: string, journey: Journey): Promise<void> {\n    await this.rpc(\"recordJourney\", { playerId, journey });\n  }\n\n  /**\n   * Re-syncs layout structures from an ordered tool name list (RPC `syncPlayerStructuresFromTools`).\n   *\n   * @remarks **Callers:** user code. **Callees:** {@link rpc}.\n   */\n  async syncPlayerStructuresFromTools(\n    playerId: string,\n    toolNames: string[]\n  ): Promise<void> {\n    await this.rpc(\"syncPlayerStructuresFromTools\", { playerId, toolNames });\n  }\n\n  /**\n   * Registers an MCP server metadata row for the session (HTTP POST, not the same as RPC `op`).\n   *\n   * @returns New registration id string from JSON `{ id }`.\n   *\n   * @remarks **Callers:** user code. **Callees:** `fetch`, {@link getSessionId}, {@link jsonHeaders}.\n   */\n  async registerMcp(options: { name: string; url?: string }): Promise<string> {\n    const sid = this.getSessionId();\n    const url = `${this.apiBase}/api/agent-play/mcp/register?sid=${encodeURIComponent(sid)}`;\n    const body: { name: string; url?: string } = { name: options.name };\n    if (options.url !== undefined) {\n      body.url = options.url;\n    }\n    const res = await fetch(url, {\n      method: \"POST\",\n      headers: this.jsonHeaders(),\n      body: JSON.stringify(body),\n    });\n    const text = await res.text();\n    if (!res.ok) {\n      throw new Error(`registerMcp: ${res.status} ${text}`);\n    }\n    let json: unknown;\n    try {\n      json = JSON.parse(text) as unknown;\n    } catch {\n      throw new Error(\"registerMcp: invalid JSON\");\n    }\n    if (!isRecord(json) || typeof json.id !== \"string\") {\n      throw new Error(\"registerMcp: invalid response\");\n    }\n    return json.id;\n  }\n\n  /**\n   * Posts `{ op, payload }` to `/api/agent-play/sdk/rpc?sid=...`.\n   *\n   * @internal\n   * @remarks **Callers:** {@link recordInteraction}, {@link recordJourney}, {@link syncPlayerStructuresFromTools}.\n   * **Callees:** {@link getSessionId}, `fetch`, {@link jsonHeaders}.\n   */\n  private async rpc(op: string, payload: unknown): Promise<void> {\n    const sid = this.getSessionId();\n    const url = `${this.apiBase}/api/agent-play/sdk/rpc?sid=${encodeURIComponent(sid)}`;\n    const res = await fetch(url, {\n      method: \"POST\",\n      headers: this.jsonHeaders(),\n      body: JSON.stringify({ op, payload }),\n    });\n    if (!res.ok) {\n      const t = await res.text();\n      throw new Error(`rpc ${op}: ${res.status} ${t}`);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/examples/01-remote-web-ui-langchain.ts

@@ -0,0 +1,89 @@
+/**
+ * Example 01 — LangChain agent against the hosted web UI (session + RPC)
+ *
+ * App shape today: **@agent-play/web-ui** serves `/api/agent-play/session`, player registration,
+ * SDK RPC, SSE events, and the watch canvas at `/agent-play/watch`. This script uses only the
+ * public SDK (`RemotePlayWorld` + `langchainRegistration`); it does not embed Express or `PlayWorld`.
+ *
+ * Prerequisites
+ * - Start the app: `npm run dev -w @agent-play/web-ui` (from repo root). Optional: Redis for
+ *   durable sessions; see docs for `REDIS_URL`.
+ * - If the server uses registered agents (Redis + repository), run `agent-play login`,
+ *   `agent-play create-key`, then `agent-play create`, then pass **`agentId`** and set
+ *   **`AGENT_PLAY_API_KEY`** on **`RemotePlayWorld`** (see SDK `AddPlayerInput` and
+ *   `RemotePlayWorldOptions` JSDoc).
+ * - `OPENAI_API_KEY` is only needed if you extend this script to call the model; registration-only
+ *   runs use a placeholder below.
+ *
+ * Run (from `packages/sdk` or via `npm run example` at repo root):
+ *   `tsx -r dotenv/config examples/01-remote-web-ui-langchain.ts`
+ *
+ * Env: `AGENT_PLAY_WEB_UI_URL`, `AGENT_PLAY_API_KEY`, `AGENT_PLAY_HOLD_SECONDS` (default 3600),
+ * `AGENT_PLAY_AGENT_ID` when using a registered agent repository, optional `OPENAI_API_KEY`.
+ */
+
+import { RemotePlayWorld, langchainRegistration } from "../src/index.js";
+import { createAgent, tool } from "langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { z } from "zod";
+
+const model = new ChatOpenAI({
+  apiKey: process.env.OPENAI_API_KEY ?? "unused-registration-only",
+  model: "gpt-4.1",
+});
+
+const chatTool = tool(
+  ({ message }: { message: string }) => `echo:${message}`,
+  {
+    name: "chat_tool",
+    description: "Record chat for the play world",
+    schema: z.object({ message: z.string() }),
+  }
+);
+
+const increment = tool(
+  ({ n }: { n: number }) => String(n + 1),
+  {
+    name: "increment",
+    description: "Add one to a number",
+    schema: z.object({ n: z.number() }),
+  }
+);
+
+const agent = createAgent({
+  name: "remote-demo",
+  model,
+  tools: [chatTool, increment],
+  systemPrompt: "Use increment when the user asks to bump a number.",
+});
+
+async function main() {
+  const base = process.env.AGENT_PLAY_WEB_UI_URL ?? "http://127.0.0.1:3000";
+  const apiKey = process.env.AGENT_PLAY_API_KEY ?? "dev-placeholder";
+  const holdSeconds = Number(process.env.AGENT_PLAY_HOLD_SECONDS ?? 3600);
+
+  const world = new RemotePlayWorld({ baseUrl: base, apiKey });
+  world.onClose(() => {
+    console.log("RemotePlayWorld closed.");
+  });
+  await world.start();
+
+  const player = await world.addPlayer({
+    name: "remote-demo",
+    type: "langchain",
+    agent: langchainRegistration(agent),
+    ...(process.env.AGENT_PLAY_AGENT_ID !== undefined &&
+    process.env.AGENT_PLAY_AGENT_ID.length > 0
+      ? { agentId: process.env.AGENT_PLAY_AGENT_ID }
+      : {}),
+  });
+
+  console.log("Open the watch UI (session is server-side; UI resolves session via API):");
+  console.log(player.previewUrl);
+  console.log(`Holding the process for ${String(holdSeconds)}s (set AGENT_PLAY_HOLD_SECONDS to change).`);
+
+  await world.hold().for(holdSeconds);
+  await world.close();
+}
+
+await main();

package/examples/02-remote-two-players-langchain.ts

@@ -0,0 +1,117 @@
+/**
+ * Example 02 — Two LangChain agents as two players on one remote session
+ *
+ * Same architecture as example 01: **RemotePlayWorld** talks to **@agent-play/web-ui** over HTTP
+ * (`/api/agent-play/session`, `/api/agent-play/players`, `/api/agent-play/sdk/rpc`). One session
+ * (`sid`) holds multiple players; each `addPlayer` gets a distinct `playerId` and tool-derived
+ * structures.
+ *
+ * Open the printed preview URL once: both avatars share the same world and session.
+ *
+ * Prerequisites: web-ui running (`npm run dev -w @agent-play/web-ui`). With Redis-backed agents,
+ * run `agent-play login`, `agent-play create-key`, then `agent-play create` twice (max 2 agents
+ * per account), pass each **`agentId`** on **`addPlayer`**, and set **`AGENT_PLAY_API_KEY`** on
+ * **`RemotePlayWorld`** (one account key for both).
+ *
+ * Run: `tsx -r dotenv/config examples/02-remote-two-players-langchain.ts`
+ * Env: `AGENT_PLAY_WEB_UI_URL`, `AGENT_PLAY_API_KEY`, `AGENT_PLAY_HOLD_SECONDS` (default 3600),
+ * `AGENT_PLAY_AGENT_ID_ALPHA` / `AGENT_PLAY_AGENT_ID_BETA` when using a registered repository.
+ */
+
+import { RemotePlayWorld, langchainRegistration } from "../src/index.js";
+import { createAgent, tool } from "langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { z } from "zod";
+
+const model = new ChatOpenAI({
+  apiKey: process.env.OPENAI_API_KEY ?? "unused-registration-only",
+  model: "gpt-4.1",
+});
+
+const chatToolAlpha = tool(
+  ({ message }: { message: string }) => `alpha:${message}`,
+  {
+    name: "chat_tool",
+    description: "Chat for alpha",
+    schema: z.object({ message: z.string() }),
+  }
+);
+
+const chatToolBeta = tool(
+  ({ message }: { message: string }) => `beta:${message}`,
+  {
+    name: "chat_tool",
+    description: "Chat for beta",
+    schema: z.object({ message: z.string() }),
+  }
+);
+
+const alphaOp = tool(
+  () => "alpha-ok",
+  {
+    name: "alpha_op",
+    description: "Alpha operation",
+    schema: z.object({}),
+  }
+);
+
+const betaOp = tool(
+  () => "beta-ok",
+  {
+    name: "beta_op",
+    description: "Beta operation",
+    schema: z.object({}),
+  }
+);
+
+const agentAlpha = createAgent({
+  name: "agent-alpha",
+  model,
+  tools: [chatToolAlpha, alphaOp],
+  systemPrompt: "Use alpha_op when the user asks for the alpha operation.",
+});
+
+const agentBeta = createAgent({
+  name: "agent-beta",
+  model,
+  tools: [chatToolBeta, betaOp],
+  systemPrompt: "Use beta_op when the user asks for the beta operation.",
+});
+
+async function main() {
+  const base = process.env.AGENT_PLAY_WEB_UI_URL ?? "http://127.0.0.1:3000";
+  const apiKey = process.env.AGENT_PLAY_API_KEY ?? "dev-placeholder";
+  const holdSeconds = Number(process.env.AGENT_PLAY_HOLD_SECONDS ?? 3600);
+
+  const world = new RemotePlayWorld({ baseUrl: base, apiKey });
+  await world.start();
+
+  const playerA = await world.addPlayer({
+    name: "alpha",
+    type: "langchain",
+    agent: langchainRegistration(agentAlpha),
+    ...(process.env.AGENT_PLAY_AGENT_ID_ALPHA !== undefined &&
+    process.env.AGENT_PLAY_AGENT_ID_ALPHA.length > 0
+      ? { agentId: process.env.AGENT_PLAY_AGENT_ID_ALPHA }
+      : {}),
+  });
+  const playerB = await world.addPlayer({
+    name: "beta",
+    type: "langchain",
+    agent: langchainRegistration(agentBeta),
+    ...(process.env.AGENT_PLAY_AGENT_ID_BETA !== undefined &&
+    process.env.AGENT_PLAY_AGENT_ID_BETA.length > 0
+      ? { agentId: process.env.AGENT_PLAY_AGENT_ID_BETA }
+      : {}),
+  });
+
+  console.log("Session id:", world.getSessionId());
+  console.log("Watch (both players):", playerA.previewUrl);
+  console.log("Player B id:", playerB.id);
+  console.log(`Holding the process for ${String(holdSeconds)}s (set AGENT_PLAY_HOLD_SECONDS to change).`);
+
+  await world.hold().for(holdSeconds);
+  await world.close();
+}
+
+await main();

package/examples/README.md

@@ -0,0 +1,51 @@
+# @agent-play/sdk examples
+
+These scripts use the **public SDK** only: `RemotePlayWorld` (HTTP session + RPC to the app), **`langchainRegistration`**, **`hold().for()`**, and optional **`onClose`**. They do **not** embed Express or import `PlayWorld` from the server.
+
+Run the **web UI** first so APIs exist:
+
+```bash
+# from repository root
+npm run dev -w @agent-play/web-ui
+```
+
+With a **registered-agent** repository (**`REDIS_URL`** on the server): run **`agent-play login`**, **`agent-play create-key`** (once per account), **`agent-play create`** for each agent (up to two per account). Set **`AGENT_PLAY_API_KEY`** to the account key and pass **`AGENT_PLAY_AGENT_ID`** (and **`AGENT_PLAY_AGENT_ID_ALPHA`** / **`AGENT_PLAY_AGENT_ID_BETA`** for example 02) when calling **`addPlayer`**. Without Redis, use the examples’ placeholder API key and omit agent ids.
+
+| Order | File | Purpose |
+|------:|------|---------|
+| 1 | [01-remote-web-ui-langchain.ts](./01-remote-web-ui-langchain.ts) | One LangChain registration, one player; process stays up via **`hold().for()`**. |
+| 2 | [02-remote-two-players-langchain.ts](./02-remote-two-players-langchain.ts) | Two registrations, two players, same session. |
+
+## Environment
+
+- `AGENT_PLAY_WEB_UI_URL` — Base URL of the running app (default `http://127.0.0.1:3000`).
+- `AGENT_PLAY_API_KEY` — Account API key for **`RemotePlayWorld`** (use a dev placeholder if the server has no repository).
+- `AGENT_PLAY_HOLD_SECONDS` — How long **`hold().for()`** waits (default `3600`).
+- `AGENT_PLAY_AGENT_ID` / `AGENT_PLAY_AGENT_ID_ALPHA` / `AGENT_PLAY_AGENT_ID_BETA` — Registered agent ids when using Redis.
+- `OPENAI_API_KEY` — Only if you extend the scripts to call the model; registration-only runs use a placeholder.
+- `AGENT_PLAY_DEBUG=1` — Verbose SDK logging (see `configureAgentPlayDebug` in package exports).
+
+## Commands
+
+From repo root:
+
+```bash
+npm run example              # example 01
+npm run example:02           # example 02
+```
+
+From `packages/sdk`:
+
+```bash
+npx tsx -r dotenv/config examples/01-remote-web-ui-langchain.ts
+npx tsx -r dotenv/config examples/02-remote-two-players-langchain.ts
+```
+
+## What the app provides
+
+- `GET /api/agent-play/session` — Creates or resumes a session (`sid`).
+- `POST /api/agent-play/players` — Registers a player; response includes a **preview URL** for `/agent-play/watch`.
+- `POST /api/agent-play/sdk/rpc` — Tool sync, interactions, invoke ingestion, and `op: getSnapshot` (used by `RemotePlayWorld` and the watch UI for JSON snapshot).
+- Watch UI loads snapshot via RPC + SSE (`/api/agent-play/...`) for live world state across instances when Redis is enabled.
+
+Assist actions on the watch UI call `POST /api/agent-play/assist-tool` when **`assist_*`** tools were registered via **`langchainRegistration`**.

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@agent-play/sdk",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Node.js SDK to register agents, stream world state, and connect to the Agent Play web UI over HTTP.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples"
+  ],
+  "author": "Isaac Williams",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wilforlan/agent-play.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "example": "tsx -r dotenv/config examples/01-remote-web-ui-langchain.ts",
+    "example:02": "tsx -r dotenv/config examples/02-remote-two-players-langchain.ts",
+    "lint": "eslint src",
+    "lint:fix": "npm run lint --fix",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@langchain/core": "^1.1.35",
+    "@langchain/openai": "^1.3.0",
+    "dotenv": "^17.3.1",
+    "eventsource-client": "^1.2.0",
+    "langchain": "^1.2.36",
+    "node-fetch": "^3.3.2",
+    "ws": "^8.18.0",
+    "uuidv4": "^6.2.13"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "@types/ws": "^8.5.13",
+    "@types/express": "^4.17.21",
+    "@types/supertest": "^6.0.3",
+    "express": "^4.21.2",
+    "supertest": "^7.1.4",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.0.9"
+  },
+  "peerDependencies": {
+    "express": "^4.21.0 || ^5.0.0"
+  }
+}