@agent-play/sdk 3.0.1 → 3.1.0

package/dist/index.js

@@ -1,20 +1,29 @@
+import {
+  PLAYER_CHAIN_GENESIS_STABLE_KEY,
+  PLAYER_CHAIN_HEADER_STABLE_KEY,
+  boundsContain,
+  clampWorldPosition,
+  mergeSnapshotWithPlayerChainNode,
+  parseAgentOccupantRow,
+  parseHumanOccupantRow,
+  parseMcpOccupantRow,
+  parsePlayerChainFanoutNotify,
+  parsePlayerChainFanoutNotifyFromSsePayload,
+  parsePlayerChainNodeRpcBody,
+  sortNodeRefsForSerializedFetch
+} from "./chunk-G2WV7OYM.js";
+
 // src/world-events.ts
+var SESSION_CONNECTED_EVENT = "session:connected";
+var SESSION_INVALID_EVENT = "session:invalid";
+var SESSION_CLOSED_EVENT = "session:closed";
+var SESSION_SSE_OPEN_EVENT = "session:sse_open";
+var SESSION_SSE_ERROR_EVENT = "session:sse_error";
 var PLAYER_ADDED_EVENT = "world:player_added";
 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) {
@@ -73,6 +82,47 @@ function formatMissingChatToolError() {
     '  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 unwrapZodCell(cell) {
+  let current = cell;
+  for (let depth = 0; depth < 32; depth++) {
+    if (current === null || typeof current !== "object") {
+      return current;
+    }
+    const def = current._def;
+    if (!def || typeof def.typeName !== "string") {
+      return current;
+    }
+    const { typeName } = def;
+    if (typeName === "ZodOptional" || typeName === "ZodNullable" || typeName === "ZodDefault") {
+      const inner = def.innerType;
+      current = inner !== null && typeof inner === "object" ? inner : void 0;
+      continue;
+    }
+    if (typeName === "ZodEffects") {
+      current = def.schema;
+      continue;
+    }
+    return current;
+  }
+  return current;
+}
+function fieldTypeFromZodCell(cell) {
+  const base = unwrapZodCell(cell);
+  if (base === null || typeof base !== "object") {
+    return "string";
+  }
+  const typeName = base._def?.typeName;
+  if (typeName === "ZodNumber") {
+    return "number";
+  }
+  if (typeName === "ZodBoolean") {
+    return "boolean";
+  }
+  if (typeName === "ZodString") {
+    return "string";
+  }
+  return "string";
+}
 function parametersFromSchema(schema) {
   if (schema === null || typeof schema !== "object") {
     return {};
@@ -84,7 +134,10 @@ function parametersFromSchema(schema) {
   const shape = z._def.shape();
   const out = {};
   for (const key of Object.keys(shape)) {
-    out[key] = { field: key };
+    out[key] = {
+      field: key,
+      fieldType: fieldTypeFromZodCell(shape[key])
+    };
   }
   return out;
 }
@@ -130,225 +183,93 @@ function langchainRegistration(agent) {
   };
 }
 
-// src/lib/parse-occupant-row.ts
-function parseAgentOccupantRow(raw) {
-  if (typeof raw.agentId !== "string" || typeof raw.name !== "string") {
-    throw new Error("occupant: agent needs agentId and name");
-  }
-  if (typeof raw.x !== "number" || typeof raw.y !== "number") {
-    throw new Error("occupant: agent needs numeric x and y");
-  }
-  const base = {
-    kind: "agent",
-    agentId: raw.agentId,
-    name: raw.name,
-    x: raw.x,
-    y: raw.y
-  };
-  let platform;
-  if (typeof raw.platform === "string") {
-    platform = raw.platform;
-  } else if (typeof raw.agentType === "string") {
-    platform = raw.agentType;
-  }
-  if (platform !== void 0) {
-    return { ...base, platform };
-  }
-  return base;
-}
-function parseMcpOccupantRow(raw) {
-  if (typeof raw.id !== "string" || typeof raw.name !== "string") {
-    throw new Error("occupant: mcp needs id and name");
-  }
-  if (typeof raw.x !== "number" || typeof raw.y !== "number") {
-    throw new Error("occupant: mcp needs numeric x and y");
-  }
-  const base = {
-    kind: "mcp",
-    id: raw.id,
-    name: raw.name,
-    x: raw.x,
-    y: raw.y
-  };
-  if (typeof raw.url === "string") {
-    return { ...base, url: raw.url };
-  }
-  return base;
-}
-
-// src/lib/world-chain-keys.ts
-var PLAYER_CHAIN_GENESIS_STABLE_KEY = "__genesis__";
-var PLAYER_CHAIN_HEADER_STABLE_KEY = "__header__";
+// src/lib/remote-play-world.ts
+import { randomUUID } from "crypto";
+import {
+  deriveNodeIdFromPassword,
+  loadAgentPlayCredentialsFileFromPathSync,
+  loadRootKey,
+  nodeCredentialsMaterialFromHumanPassphrase,
+  resolveAgentPlayCredentialsPath
+} from "@agent-play/node-tools";
+import { HumanMessage } from "@langchain/core/messages";
+import {
+  INTERCOM_RESPONSE_OP,
+  parseWorldIntercomEventPayload,
+  WORLD_INTERCOM_EVENT
+} from "@agent-play/intercom";
 
-// src/lib/player-chain-merge.ts
-function isRecord(v) {
-  return typeof v === "object" && v !== null;
-}
-function stableOccupantSortKey(occ) {
-  if (occ.kind === "agent") {
-    return `agent:${occ.agentId}`;
+// src/lib/intercom-langchain-chat-result.ts
+function contentToText(content) {
+  if (typeof content === "string") {
+    return content;
   }
-  return `mcp:${occ.id}`;
-}
-function sortNodeRefsForSerializedFetch(nodes) {
-  const removed = nodes.filter((n) => n.removed === true);
-  const rest = nodes.filter((n) => n.removed !== true);
-  removed.sort((a, b) => b.leafIndex - a.leafIndex);
-  rest.sort((a, b) => a.leafIndex - b.leafIndex);
-  return [...removed, ...rest];
-}
-function parsePlayerChainFanoutNotify(raw) {
-  if (!isRecord(raw)) {
-    return void 0;
-  }
-  if (typeof raw.updatedAt !== "string" || raw.updatedAt.length === 0) {
-    return void 0;
-  }
-  if (!Array.isArray(raw.nodes)) {
-    return void 0;
-  }
-  const nodes = [];
-  for (const row of raw.nodes) {
-    if (!isRecord(row)) {
-      return void 0;
-    }
-    if (typeof row.stableKey !== "string" || row.stableKey.length === 0) {
-      return void 0;
-    }
-    if (typeof row.leafIndex !== "number" || !Number.isFinite(row.leafIndex)) {
-      return void 0;
-    }
-    const ref = {
-      stableKey: row.stableKey,
-      leafIndex: row.leafIndex
-    };
-    if (row.removed === true) {
-      ref.removed = true;
-    }
-    if (typeof row.updatedAt === "string" && row.updatedAt.length > 0) {
-      ref.updatedAt = row.updatedAt;
-    }
-    nodes.push(ref);
+  if (Array.isArray(content)) {
+    return content.map((block) => {
+      if (typeof block === "string") {
+        return block;
+      }
+      if (typeof block === "object" && block !== null && "text" in block) {
+        const t = block.text;
+        return typeof t === "string" ? t : "";
+      }
+      return "";
+    }).join("");
   }
-  return { updatedAt: raw.updatedAt, nodes };
-}
-function parsePlayerChainFanoutNotifyFromSsePayload(sseData) {
-  if (!isRecord(sseData)) {
-    return void 0;
+  if (content !== null && typeof content === "object" && "text" in content) {
+    const t = content.text;
+    return typeof t === "string" ? t : JSON.stringify(content);
   }
-  return parsePlayerChainFanoutNotify(sseData.playerChainNotify);
+  return JSON.stringify(content);
 }
-function parsePlayerChainNodeRpcBody(json) {
-  if (!isRecord(json) || !isRecord(json.node)) {
-    throw new Error("getPlayerChainNode: invalid response shape");
-  }
-  const n = json.node;
-  if (n.kind === "genesis") {
-    if (n.stableKey !== PLAYER_CHAIN_GENESIS_STABLE_KEY || typeof n.text !== "string") {
-      throw new Error("getPlayerChainNode: invalid genesis node");
-    }
-    return {
-      kind: "genesis",
-      stableKey: PLAYER_CHAIN_GENESIS_STABLE_KEY,
-      text: n.text
-    };
+function intercomResultRecordFromLangChainInvokeOutput(output) {
+  if (output === null || typeof output !== "object") {
+    return { mode: "chat", message: String(output) };
   }
-  if (n.kind === "header") {
-    if (n.stableKey !== PLAYER_CHAIN_HEADER_STABLE_KEY || typeof n.sid !== "string") {
-      throw new Error("getPlayerChainNode: invalid header node");
+  const o = output;
+  if ("structuredResponse" in o && o.structuredResponse !== void 0) {
+    const sr = o.structuredResponse;
+    if (sr !== null && typeof sr === "object" && !Array.isArray(sr)) {
+      return { ...sr };
     }
-    const b = n.bounds;
-    if (!isRecord(b)) {
-      throw new Error("getPlayerChainNode: invalid header bounds");
-    }
-    const { minX, minY, maxX, maxY } = b;
-    if (typeof minX !== "number" || typeof minY !== "number" || typeof maxX !== "number" || typeof maxY !== "number") {
-      throw new Error("getPlayerChainNode: invalid header bounds");
-    }
-    return {
-      kind: "header",
-      stableKey: PLAYER_CHAIN_HEADER_STABLE_KEY,
-      sid: n.sid,
-      bounds: { minX, minY, maxX, maxY }
-    };
-  }
-  if (n.kind !== "occupant") {
-    throw new Error("getPlayerChainNode: unknown node kind");
-  }
-  if (typeof n.stableKey !== "string" || n.stableKey.length === 0) {
-    throw new Error("getPlayerChainNode: invalid occupant stableKey");
-  }
-  if (n.removed === true) {
-    return { kind: "occupant", stableKey: n.stableKey, removed: true };
-  }
-  const occ = n.occupant;
-  if (!isRecord(occ) || occ.kind !== "agent" && occ.kind !== "mcp") {
-    throw new Error("getPlayerChainNode: invalid occupant payload");
+    return { mode: "chat", structuredResponse: sr };
   }
-  const occupant = occ.kind === "agent" ? parseAgentOccupantRow(occ) : parseMcpOccupantRow(occ);
-  return {
-    kind: "occupant",
-    stableKey: n.stableKey,
-    removed: false,
-    occupant
-  };
-}
-function mergeSnapshotWithPlayerChainNode(snapshot, node) {
-  if (node.kind === "genesis") {
-    return snapshot;
-  }
-  if (node.kind === "header") {
-    return {
-      ...snapshot,
-      sid: node.sid,
-      worldMap: {
-        ...snapshot.worldMap,
-        bounds: node.bounds
+  const messages = o.messages;
+  if (Array.isArray(messages) && messages.length > 0) {
+    const last = messages[messages.length - 1];
+    if (last !== null && typeof last === "object" && "content" in last) {
+      const text = contentToText(last.content);
+      if (text.trim().length > 0) {
+        return { mode: "chat", message: text };
       }
-    };
-  }
-  if (node.removed) {
-    return {
-      ...snapshot,
-      worldMap: {
-        ...snapshot.worldMap,
-        occupants: snapshot.worldMap.occupants.filter(
-          (o) => stableOccupantSortKey(o) !== node.stableKey
-        )
-      }
-    };
-  }
-  const key = stableOccupantSortKey(node.occupant);
-  const occupants = snapshot.worldMap.occupants.filter(
-    (o) => stableOccupantSortKey(o) !== key
-  );
-  return {
-    ...snapshot,
-    worldMap: {
-      ...snapshot.worldMap,
-      occupants: [...occupants, node.occupant]
     }
-  };
+  }
+  return { mode: "chat", output: o };
 }
 
 // src/lib/remote-play-world.ts
-function formatMissingApiKeyError() {
+var PLAYER_CONNECTION_HEARTBEAT_MAX_ATTEMPTS = 10;
+var PLAYER_CONNECTION_HEARTBEAT_RETRY_DELAY_MS = 1e4;
+function formatMissingCredentialsError() {
   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");
+    "RemotePlayWorld: provide nodeCredentials: { rootKey, passw },",
+    "or run agent-play create-main-node so ~/.agent-play/credentials.json exists."
+  ].join(" ");
+}
+function formatMissingBaseUrlError() {
+  return [
+    "RemotePlayWorld: baseUrl is missing.",
+    "Provide options.baseUrl, or ensure credentials.json contains serverUrl."
+  ].join(" ");
 }
 function normalizeBaseUrl(url) {
   return url.replace(/\/$/, "");
 }
-function isRecord2(v) {
+function isRecord(v) {
   return typeof v === "object" && v !== null;
 }
 function parseBounds(raw) {
-  if (!isRecord2(raw)) {
+  if (!isRecord(raw)) {
     throw new Error("getWorldSnapshot: worldMap.bounds must be an object");
   }
   const { minX, minY, maxX, maxY } = raw;
@@ -360,7 +281,7 @@ function parseBounds(raw) {
   return { minX, minY, maxX, maxY };
 }
 function parseWorldMap(raw) {
-  if (!isRecord2(raw)) {
+  if (!isRecord(raw)) {
     throw new Error("getWorldSnapshot: worldMap must be an object");
   }
   const bounds = parseBounds(raw.bounds);
@@ -371,8 +292,10 @@ function parseWorldMap(raw) {
   const occupants = [];
   const coordKeys = /* @__PURE__ */ new Set();
   for (const row of occ) {
-    if (!isRecord2(row) || row.kind !== "agent" && row.kind !== "mcp") {
-      throw new Error("getWorldSnapshot: each occupant must have kind agent or mcp");
+    if (!isRecord(row) || row.kind !== "human" && row.kind !== "agent" && row.kind !== "mcp") {
+      throw new Error(
+        "getWorldSnapshot: each occupant must have kind human, agent, or mcp"
+      );
     }
     const xy = typeof row.x === "number" && typeof row.y === "number" ? `${row.x},${row.y}` : "";
     if (xy.length === 0) {
@@ -382,7 +305,9 @@ function parseWorldMap(raw) {
       throw new Error("getWorldSnapshot: duplicate world map coordinate");
     }
     coordKeys.add(xy);
-    if (row.kind === "agent") {
+    if (row.kind === "human") {
+      occupants.push(parseHumanOccupantRow(row));
+    } else if (row.kind === "agent") {
       occupants.push(parseAgentOccupantRow(row));
     } else {
       occupants.push(parseMcpOccupantRow(row));
@@ -391,7 +316,7 @@ function parseWorldMap(raw) {
   return { bounds, occupants };
 }
 function parseAgentPlaySnapshot(snapshot) {
-  if (!isRecord2(snapshot) || typeof snapshot.sid !== "string") {
+  if (!isRecord(snapshot) || typeof snapshot.sid !== "string") {
     throw new Error("getWorldSnapshot: invalid snapshot");
   }
   const worldMap = parseWorldMap(snapshot.worldMap);
@@ -399,7 +324,7 @@ function parseAgentPlaySnapshot(snapshot) {
   if ("mcpServers" in snapshot && Array.isArray(snapshot.mcpServers)) {
     const servers = [];
     for (const m of snapshot.mcpServers) {
-      if (!isRecord2(m) || typeof m.id !== "string" || typeof m.name !== "string") {
+      if (!isRecord(m) || typeof m.id !== "string" || typeof m.name !== "string") {
         continue;
       }
       const row = {
@@ -414,24 +339,24 @@ function parseAgentPlaySnapshot(snapshot) {
   return out;
 }
 function parseRegisteredAgentSummary(raw) {
-  if (!isRecord2(raw)) {
-    throw new Error("addPlayer: registeredAgent missing");
+  if (!isRecord(raw)) {
+    throw new Error("registerAgent: registeredAgent missing");
   }
   if (typeof raw.agentId !== "string" || typeof raw.name !== "string") {
-    throw new Error("addPlayer: registeredAgent.agentId and name required");
+    throw new Error("registerAgent: registeredAgent.agentId and name required");
   }
   if (!Array.isArray(raw.toolNames)) {
-    throw new Error("addPlayer: registeredAgent.toolNames must be an array");
+    throw new Error("registerAgent: registeredAgent.toolNames must be an array");
   }
   const toolNames = [];
   for (const t of raw.toolNames) {
     if (typeof t !== "string") {
-      throw new Error("addPlayer: registeredAgent.toolNames must be strings");
+      throw new Error("registerAgent: registeredAgent.toolNames must be strings");
     }
     toolNames.push(t);
   }
   if (typeof raw.zoneCount !== "number" || typeof raw.yieldCount !== "number" || typeof raw.flagged !== "boolean") {
-    throw new Error("addPlayer: registeredAgent counters invalid");
+    throw new Error("registerAgent: registeredAgent counters invalid");
   }
   return {
     agentId: raw.agentId,
@@ -449,20 +374,89 @@ function formatInvalidHoldSecondsError() {
     "  Example: await world.hold().for(3600)"
   ].join("\n");
 }
+function getSseEventName(msg) {
+  if (typeof msg !== "object" || msg === null) {
+    return void 0;
+  }
+  const m = msg;
+  if (typeof m.event === "string" && m.event.length > 0) {
+    return m.event;
+  }
+  if (typeof m.type === "string" && m.type.length > 0) {
+    return m.type;
+  }
+  return void 0;
+}
+function invokeLangChainChatAgent(agent, input) {
+  if (typeof agent !== "object" || agent === null) {
+    throw new Error("intercom: chat agent must be a non-null object");
+  }
+  const inv = agent.invoke;
+  if (typeof inv !== "function") {
+    throw new Error("intercom: chat agent must have invoke()");
+  }
+  return Promise.resolve(
+    inv.call(agent, input)
+  );
+}
+function normalizeIntercomSubscribePlayerIds(options) {
+  const raw = "playerIds" in options ? [...options.playerIds] : [options.playerId];
+  return new Set(
+    raw.map((id) => id.trim()).filter((id) => id.length > 0)
+  );
+}
 var RemotePlayWorld = class {
   apiBase;
-  apiKey;
-  authToken;
+  rootKey;
+  /** Node id derived from hashed passphrase material + root (main or agent node id). */
+  derivedNodeId;
+  /** Hex password material (`hashNodePassword` on normalized human phrase); sent as `password` for repository addAgent. */
+  password;
+  onSessionEvent;
+  transportLog;
   sid = null;
   closed = false;
   closeListeners = /* @__PURE__ */ new Set();
-  constructor(options) {
-    if (typeof options.apiKey !== "string" || options.apiKey.trim().length === 0) {
-      throw new Error(formatMissingApiKeyError());
+  playerConnectionInfo = /* @__PURE__ */ new Map();
+  constructor(options = {}) {
+    const creds = loadAgentPlayCredentialsFileFromPathSync(
+      resolveAgentPlayCredentialsPath()
+    );
+    const resolvedBaseUrl = options.baseUrl ?? creds?.serverUrl;
+    if (resolvedBaseUrl === void 0 || resolvedBaseUrl.trim().length === 0) {
+      throw new Error(formatMissingBaseUrlError());
+    }
+    this.apiBase = normalizeBaseUrl(resolvedBaseUrl);
+    this.onSessionEvent = options.onSessionEvent;
+    this.transportLog = options.logging === "on";
+    const nc = options.nodeCredentials ?? (creds === null ? void 0 : { rootKey: loadRootKey(), passw: creds.passw });
+    if (nc !== void 0 && typeof nc.rootKey === "string" && nc.rootKey.trim().length > 0 && typeof nc.passw === "string" && nc.passw.length > 0) {
+      this.rootKey = nc.rootKey.trim().toLowerCase();
+      const material = nodeCredentialsMaterialFromHumanPassphrase(nc.passw);
+      this.password = material;
+      this.derivedNodeId = deriveNodeIdFromPassword({
+        password: material,
+        rootKey: this.rootKey
+      });
+      return;
     }
-    this.apiBase = normalizeBaseUrl(options.baseUrl);
-    this.apiKey = options.apiKey.trim();
-    this.authToken = options.authToken;
+    throw new Error(formatMissingCredentialsError());
+  }
+  logTransport(event, detail) {
+    if (!this.transportLog) {
+      return;
+    }
+    console.info(`[agent-play:RemotePlayWorld] ${event}`, detail);
+  }
+  truncateForLog(value, max = 1600) {
+    return value.length <= max ? value : `${value.slice(0, max)}\u2026`;
+  }
+  emitSessionEvent(event) {
+    this.logTransport("session:event", {
+      name: event.name,
+      detail: event.detail ?? {}
+    });
+    this.onSessionEvent?.(event);
   }
   onClose(handler) {
     this.closeListeners.add(handler);
@@ -484,8 +478,10 @@ var RemotePlayWorld = class {
     };
   }
   authHeaders() {
-    if (this.authToken === void 0) return {};
-    return { Authorization: `Bearer ${this.authToken}` };
+    return {
+      "x-node-id": this.derivedNodeId,
+      "x-node-passw": this.password
+    };
   }
   jsonHeaders() {
     return {
@@ -501,7 +497,51 @@ var RemotePlayWorld = class {
     }
     return fetch(input, { ...init, headers });
   }
-  async connect() {
+  async validateNodeIdentity(options) {
+    const body = {
+      nodeId: options.nodeId,
+      rootKey: this.rootKey
+    };
+    if (options.mainNodeId !== void 0 && options.mainNodeId.trim().length > 0) {
+      body.mainNodeId = options.mainNodeId.trim();
+    }
+    const res = await fetch(`${this.apiBase}/api/nodes/validate`, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify(body)
+    });
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      throw new Error(`node validation failed: ${String(res.status)} invalid JSON`);
+    }
+    if (!isRecord(json) || json.ok !== true) {
+      const reason = isRecord(json) && typeof json.reason === "string" ? json.reason : `HTTP ${String(res.status)}`;
+      throw new Error(`node validation failed: ${reason}`);
+    }
+    const nodeKind = isRecord(json) && typeof json.nodeKind === "string" ? json.nodeKind : void 0;
+    agentPlayDebug("remote-play-world", "node identity validated", {
+      nodeKind,
+      derivedNodeIdPrefix: `${this.derivedNodeId.slice(0, 8)}\u2026`
+    });
+    return nodeKind !== void 0 ? { nodeKind } : {};
+  }
+  /**
+   * Establishes the HTTP session via `GET /api/agent-play/session`. With {@link RemotePlayWorldConnectOptions.mainNodeId},
+   * validates node identity with `POST /api/nodes/validate` first.
+   */
+  async connect(options) {
+    const mainNodeIdOpt = options?.mainNodeId?.trim();
+    if (mainNodeIdOpt !== void 0 && mainNodeIdOpt.length > 0) {
+      const validation = await this.validateNodeIdentity({
+        nodeId: this.derivedNodeId,
+        mainNodeId: mainNodeIdOpt
+      });
+      console.info(
+        `[agent-play] Node identity validated (${validation.nodeKind ?? "unknown"}).`
+      );
+    }
     const res = await fetch(`${this.apiBase}/api/agent-play/session`, {
       headers: this.authHeaders()
     });
@@ -509,16 +549,38 @@ var RemotePlayWorld = class {
       throw new Error(`session failed: ${res.status}`);
     }
     const json = await res.json();
-    if (!isRecord2(json) || typeof json.sid !== "string" || json.sid.length === 0) {
+    if (!isRecord(json) || typeof json.sid !== "string" || json.sid.length === 0) {
       throw new Error("session: invalid response");
     }
     this.sid = json.sid;
+    this.logTransport("connect:session", {
+      sid: this.sid,
+      apiBase: this.apiBase
+    });
+    this.emitSessionEvent({
+      name: SESSION_CONNECTED_EVENT,
+      detail: { sid: this.sid }
+    });
   }
   async close() {
     if (this.closed) {
       return;
     }
+    for (const [playerId, connection] of Array.from(
+      this.playerConnectionInfo.entries()
+    )) {
+      clearInterval(connection.timer);
+      try {
+        await this.disconnectPlayerConnection({
+          playerId,
+          connectionId: connection.connectionId
+        });
+      } catch {
+      }
+    }
+    this.playerConnectionInfo.clear();
     this.closed = true;
+    this.emitSessionEvent({ name: SESSION_CLOSED_EVENT });
     for (const handler of Array.from(this.closeListeners)) {
       try {
         handler();
@@ -553,7 +615,7 @@ var RemotePlayWorld = class {
     } catch {
       throw new Error("getWorldSnapshot: invalid JSON");
     }
-    if (!isRecord2(json) || !("snapshot" in json)) {
+    if (!isRecord(json) || !("snapshot" in json)) {
       throw new Error("getWorldSnapshot: invalid response shape");
     }
     return parseAgentPlaySnapshot(json.snapshot);
@@ -596,29 +658,65 @@ var RemotePlayWorld = class {
         const { createEventSource } = await import("eventsource-client");
         let snapshot = await this.getWorldSnapshot();
         callbacks.onSnapshot(snapshot);
+        const sseUrl = `${this.apiBase}/api/agent-play/events?sid=${encodeURIComponent(
+          this.getSessionId()
+        )}`;
+        this.logTransport("subscribeWorldState:sse_open", { sseUrl });
         const source = createEventSource({
-          url: `${this.apiBase}/api/agent-play/events?sid=${encodeURIComponent(
-            this.getSessionId()
-          )}`,
+          url: sseUrl,
           fetch: (input, init) => this.mergeAuthFetch(input, init)
         });
         closeSource = () => {
           source.close();
         };
         for await (const msg of source) {
+          const eventType = typeof msg === "object" && msg !== null && "type" in msg && typeof msg.type === "string" ? msg.type : "(no type)";
           if (typeof msg.data !== "string") {
+            this.logTransport("sse:worldState:skip", {
+              reason: "data_not_string",
+              eventType
+            });
             continue;
           }
+          this.logTransport("sse:worldState:message", {
+            eventType,
+            dataLength: msg.data.length,
+            dataPreview: this.truncateForLog(msg.data)
+          });
           let data;
           try {
             data = JSON.parse(msg.data);
           } catch {
+            this.logTransport("sse:worldState:parseJson", {
+              reason: "invalid_json",
+              eventType
+            });
             continue;
           }
+          if (callbacks.onIntercomEvent) {
+            try {
+              const inter = parseWorldIntercomEventPayload(data);
+              this.logTransport("sse:worldState:intercom", {
+                status: inter.status,
+                requestId: inter.requestId,
+                kind: inter.kind,
+                channelKey: inter.channelKey
+              });
+              callbacks.onIntercomEvent(inter);
+            } catch {
+              this.logTransport("sse:worldState:intercom", {
+                reason: "not_world_intercom_payload"
+              });
+            }
+          }
           const notify = parsePlayerChainFanoutNotifyFromSsePayload(data);
           if (notify === void 0 || notify.nodes.length === 0) {
             continue;
           }
+          this.logTransport("sse:worldState:playerChainNotify", {
+            nodeCount: notify.nodes.length,
+            stableKeys: notify.nodes.map((n) => n.stableKey)
+          });
           const ordered = sortNodeRefsForSerializedFetch(notify.nodes);
           for (const ref of ordered) {
             const node = await this.getPlayerChainNode(ref.stableKey);
@@ -627,21 +725,43 @@ var RemotePlayWorld = class {
           callbacks.onSnapshot(snapshot);
         }
       } catch (e) {
-        callbacks.onError?.(
-          e instanceof Error ? e : new Error(String(e))
-        );
+        const err = e instanceof Error ? e : new Error(String(e));
+        this.logTransport("sse:worldState:error", {
+          message: err.message
+        });
+        callbacks.onError?.(err);
       }
     })();
     return {
       close: () => {
+        this.logTransport("subscribeWorldState:close", {});
         closeSource?.();
         void task;
       }
     };
   }
-  async addPlayer(input) {
+  /**
+   * Registers an automation agent using **agent node id** (`nodeId`), sent to the server as `agentId`.
+   */
+  async addAgent(input) {
     const sid = this.getSessionId();
+    const effectiveMainNodeId = this.derivedNodeId;
+    const validation = await this.validateNodeIdentity({
+      nodeId: input.nodeId,
+      mainNodeId: effectiveMainNodeId
+    });
+    console.info(
+      [
+        "Agent Node Connection",
+        `  status   : validated`,
+        `  nodeId   : ${input.nodeId}`,
+        `  nodeKind : ${validation.nodeKind ?? "unknown"}`,
+        `  mainNode : ${effectiveMainNodeId}`
+      ].join("\n")
+    );
     const url = `${this.apiBase}/api/agent-play/players?sid=${encodeURIComponent(sid)}`;
+    const connectionId = randomUUID();
+    const leaseTtlSeconds = 45;
     const res = await fetch(url, {
       method: "POST",
       headers: this.jsonHeaders(),
@@ -649,29 +769,60 @@ var RemotePlayWorld = class {
         name: input.name,
         type: input.type,
         agent: input.agent,
-        apiKey: this.apiKey,
-        agentId: input.agentId
+        mainNodeId: effectiveMainNodeId,
+        password: this.password,
+        agentId: input.nodeId,
+        connectionId,
+        leaseTtlSeconds
       })
     });
     const bodyText = await res.text();
     if (!res.ok) {
-      throw new Error(`addPlayer: ${res.status} ${bodyText}`);
+      throw new Error(`addAgent: ${res.status} ${bodyText}`);
     }
     let body;
     try {
       body = JSON.parse(bodyText);
     } catch {
-      throw new Error("addPlayer: invalid JSON");
+      throw new Error("addAgent: invalid JSON");
     }
-    if (!isRecord2(body)) {
-      throw new Error("addPlayer: invalid response shape");
+    if (!isRecord(body)) {
+      throw new Error("addAgent: invalid response shape");
     }
     const playerId = body.playerId;
     const previewUrl = body.previewUrl;
     if (typeof playerId !== "string" || typeof previewUrl !== "string") {
-      throw new Error("addPlayer: missing playerId or previewUrl");
+      throw new Error("addAgent: missing playerId or previewUrl");
     }
     const registeredAgent = parseRegisteredAgentSummary(body.registeredAgent);
+    const bodyConnectionId = typeof body.connectionId === "string" && body.connectionId.length > 0 ? body.connectionId : connectionId;
+    const bodyLeaseTtlSeconds = typeof body.leaseTtlSeconds === "number" && Number.isFinite(body.leaseTtlSeconds) ? body.leaseTtlSeconds : leaseTtlSeconds;
+    const existingConnection = this.playerConnectionInfo.get(playerId);
+    if (existingConnection !== void 0) {
+      clearInterval(existingConnection.timer);
+    }
+    const timer = setInterval(() => {
+      void this.heartbeatPlayerConnection({
+        playerId,
+        connectionId: bodyConnectionId,
+        leaseTtlSeconds: bodyLeaseTtlSeconds
+      }).catch((err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error("[agent-play:RemotePlayWorld] heartbeat:exhausted", {
+          playerId,
+          connectionId: bodyConnectionId,
+          leaseTtlSeconds: bodyLeaseTtlSeconds,
+          attempts: PLAYER_CONNECTION_HEARTBEAT_MAX_ATTEMPTS,
+          retryDelayMs: PLAYER_CONNECTION_HEARTBEAT_RETRY_DELAY_MS,
+          error: message
+        });
+      });
+    }, 12e3);
+    this.playerConnectionInfo.set(playerId, {
+      connectionId: bodyConnectionId,
+      leaseTtlSeconds: bodyLeaseTtlSeconds,
+      timer
+    });
     const now = /* @__PURE__ */ new Date();
     return {
       id: playerId,
@@ -680,8 +831,34 @@ var RemotePlayWorld = class {
       createdAt: now,
       updatedAt: now,
       previewUrl,
-      registeredAgent
+      registeredAgent,
+      connectionId: bodyConnectionId,
+      leaseTtlSeconds: bodyLeaseTtlSeconds
+    };
+  }
+  /**
+   * @deprecated Use {@link addAgent} with `nodeId` (agent node id) for integrations and automation.
+   */
+  async addPlayer(input) {
+    const payload = {
+      name: input.name,
+      type: input.type,
+      agent: input.agent,
+      nodeId: input.agentId
     };
+    if (input.version !== void 0) {
+      payload.version = input.version;
+    }
+    if (input.createdAt !== void 0) {
+      payload.createdAt = input.createdAt;
+    }
+    if (input.updatedAt !== void 0) {
+      payload.updatedAt = input.updatedAt;
+    }
+    if (input.mainNodeId !== void 0) {
+      payload.mainNodeId = input.mainNodeId;
+    }
+    return this.addAgent(payload);
   }
   async recordInteraction(input) {
     await this.rpc("recordInteraction", {
@@ -693,6 +870,210 @@ var RemotePlayWorld = class {
   async recordJourney(playerId, journey) {
     await this.rpc("recordJourney", { playerId, journey });
   }
+  async sendIntercomResponse(payload) {
+    const sid = this.getSessionId();
+    const url = `${this.apiBase}/api/agent-play/sdk/rpc?sid=${encodeURIComponent(sid)}`;
+    this.logTransport("intercom:sendResponse:request", {
+      url,
+      requestId: payload.requestId,
+      toPlayerId: payload.toPlayerId,
+      fromPlayerId: payload.fromPlayerId,
+      kind: payload.kind,
+      status: payload.status,
+      toolName: payload.toolName,
+      error: payload.error,
+      resultPreview: payload.result !== void 0 ? this.truncateForLog(JSON.stringify(payload.result)) : void 0
+    });
+    const res = await fetch(url, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify({ op: INTERCOM_RESPONSE_OP, payload })
+    });
+    const okText = await res.text();
+    this.logTransport("intercom:sendResponse:http", {
+      requestId: payload.requestId,
+      httpStatus: res.status,
+      bodyPreview: this.truncateForLog(okText)
+    });
+    if (!res.ok) {
+      throw new Error(`intercomResponse: ${res.status} ${okText}`);
+    }
+  }
+  /**
+   * Subscribes to the session SSE stream and handles **`forwarded`** intercom commands whose **`toPlayerId`** is in **`playerId`** or **`playerIds`**, invoking **`executeTool`** and posting **`intercomResponse`** (**`completed`** / **`failed`**).
+   * Uses a **single** SSE connection when **`playerIds`** lists multiple automation agents (recommended for several agents in one process).
+   * Not invoked automatically by {@link RemotePlayWorld.addAgent}.
+   */
+  subscribeIntercomCommands(options) {
+    const subscribed = normalizeIntercomSubscribePlayerIds(options);
+    const playerIdsSorted = Array.from(subscribed).sort();
+    if (subscribed.size === 0) {
+      this.logTransport("subscribeIntercomCommands:skip", {
+        reason: "empty_player_ids"
+      });
+      return { close: () => {
+      } };
+    }
+    this.logTransport("subscribeIntercomCommands:start", {
+      playerIds: playerIdsSorted
+    });
+    const { executeTool, chatAgentsByPlayerId } = options;
+    let closeSource = null;
+    const task = (async () => {
+      try {
+        const { createEventSource } = await import("eventsource-client");
+        const sseUrl = `${this.apiBase}/api/agent-play/events?sid=${encodeURIComponent(
+          this.getSessionId()
+        )}`;
+        this.logTransport("subscribeIntercomCommands:sse_open", {
+          sseUrl,
+          subscribePlayerIds: playerIdsSorted
+        });
+        const source = createEventSource({
+          url: sseUrl,
+          fetch: (input, init) => this.mergeAuthFetch(input, init)
+        });
+        closeSource = () => {
+          source.close();
+        };
+        for await (const msg of source) {
+          const sseEvent = getSseEventName(msg);
+          if (sseEvent !== void 0 && sseEvent !== WORLD_INTERCOM_EVENT) {
+            continue;
+          }
+          if (typeof msg.data !== "string") {
+            const eventLabel = sseEvent ?? "(unset)";
+            this.logTransport("sse:intercomCommands:skip", {
+              reason: "data_not_string",
+              sseEvent: eventLabel
+            });
+            continue;
+          }
+          let data;
+          try {
+            data = JSON.parse(msg.data);
+          } catch {
+            this.logTransport("sse:intercomCommands:parseJson", {
+              reason: "invalid_json",
+              sseEvent: sseEvent ?? "(unset)"
+            });
+            continue;
+          }
+          let inter;
+          try {
+            inter = parseWorldIntercomEventPayload(data);
+          } catch {
+            continue;
+          }
+          if (inter.status !== "forwarded") {
+            continue;
+          }
+          const cmd = inter.command;
+          if (cmd === void 0) {
+            this.logTransport("sse:intercomCommands:skip", {
+              reason: "missing_command",
+              requestId: inter.requestId
+            });
+            continue;
+          }
+          if (!subscribed.has(cmd.toPlayerId)) {
+            continue;
+          }
+          this.logTransport("sse:intercomCommands:forwarded", {
+            requestId: cmd.requestId,
+            fromPlayerId: cmd.fromPlayerId,
+            toPlayerId: cmd.toPlayerId,
+            kind: cmd.kind,
+            toolName: cmd.toolName
+          });
+          const toolName = cmd.kind === "chat" ? "chat_tool" : cmd.toolName ?? "";
+          const args = cmd.kind === "chat" ? { text: cmd.text ?? "" } : cmd.args ?? {};
+          this.logTransport("intercom:executeTool", {
+            requestId: cmd.requestId,
+            toolName,
+            argsPreview: this.truncateForLog(JSON.stringify(args))
+          });
+          try {
+            this.logTransport("intercom:executeTool:started", {
+              requestId: cmd.requestId,
+              toolName,
+              argsPreview: this.truncateForLog(JSON.stringify(args))
+            });
+            let result;
+            if (cmd.kind === "chat" && chatAgentsByPlayerId !== void 0 && chatAgentsByPlayerId.has(cmd.toPlayerId)) {
+              const lc = chatAgentsByPlayerId.get(cmd.toPlayerId);
+              if (lc === void 0) {
+                throw new Error("intercom: chatAgentsByPlayerId entry missing");
+              }
+              this.logTransport("intercom:langchain:invoke", {
+                requestId: cmd.requestId,
+                toPlayerId: cmd.toPlayerId,
+                textPreview: this.truncateForLog(cmd.text ?? "")
+              });
+              const rawOut = await invokeLangChainChatAgent(lc, {
+                messages: [new HumanMessage(cmd.text ?? "")]
+              });
+              result = intercomResultRecordFromLangChainInvokeOutput(rawOut);
+              this.logTransport("intercom:langchain:invoke:completed", {
+                requestId: cmd.requestId,
+                resultPreview: this.truncateForLog(JSON.stringify(result))
+              });
+            } else {
+              result = await Promise.resolve(
+                executeTool({ toolName, args })
+              );
+            }
+            this.logTransport("intercom:executeTool:completed", {
+              requestId: cmd.requestId,
+              toolName,
+              argsPreview: this.truncateForLog(JSON.stringify(args)),
+              resultPreview: this.truncateForLog(JSON.stringify(result))
+            });
+            await this.sendIntercomResponse({
+              requestId: cmd.requestId,
+              mainNodeId: cmd.mainNodeId,
+              toPlayerId: cmd.fromPlayerId,
+              fromPlayerId: cmd.toPlayerId,
+              kind: cmd.kind,
+              status: "completed",
+              toolName: cmd.toolName,
+              ts: (/* @__PURE__ */ new Date()).toISOString(),
+              result
+            });
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logTransport("intercom:executeTool:error", {
+              requestId: cmd.requestId,
+              message
+            });
+            await this.sendIntercomResponse({
+              requestId: cmd.requestId,
+              mainNodeId: cmd.mainNodeId,
+              toPlayerId: cmd.fromPlayerId,
+              fromPlayerId: cmd.toPlayerId,
+              kind: cmd.kind,
+              status: "failed",
+              toolName: cmd.toolName,
+              error: message,
+              ts: (/* @__PURE__ */ new Date()).toISOString()
+            });
+          }
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.logTransport("sse:intercomCommands:stream_error", { message });
+      }
+    })();
+    return {
+      close: () => {
+        this.logTransport("subscribeIntercomCommands:close", {
+          playerIds: playerIdsSorted
+        });
+        closeSource?.();
+        void task;
+      }
+    };
+  }
   async registerMcp(options) {
     const sid = this.getSessionId();
     const url = `${this.apiBase}/api/agent-play/mcp/register?sid=${encodeURIComponent(sid)}`;
@@ -715,7 +1096,7 @@ var RemotePlayWorld = class {
     } catch {
       throw new Error("registerMcp: invalid JSON");
     }
-    if (!isRecord2(json) || typeof json.id !== "string") {
+    if (!isRecord(json) || typeof json.id !== "string") {
       throw new Error("registerMcp: invalid response");
     }
     return json.id;
@@ -733,12 +1114,102 @@ var RemotePlayWorld = class {
       throw new Error(`rpc ${op}: ${res.status} ${t}`);
     }
   }
+  async heartbeatPlayerConnection(input) {
+    const sid = this.getSessionId();
+    const url = `${this.apiBase}/api/agent-play/players/heartbeat?sid=${encodeURIComponent(sid)}`;
+    const bodyJson = JSON.stringify({
+      playerId: input.playerId,
+      connectionId: input.connectionId,
+      leaseTtlSeconds: input.leaseTtlSeconds
+    });
+    let lastError = new Error("heartbeat: no attempts completed");
+    for (let attempt = 1; attempt <= PLAYER_CONNECTION_HEARTBEAT_MAX_ATTEMPTS; attempt += 1) {
+      const attemptStartedAt = Date.now();
+      try {
+        const res = await fetch(url, {
+          method: "POST",
+          headers: this.jsonHeaders(),
+          body: bodyJson
+        });
+        const text = await res.text();
+        if (res.ok) {
+          if (attempt > 1) {
+            console.info("[agent-play:RemotePlayWorld] heartbeat:retry_recovered", {
+              playerId: input.playerId,
+              connectionId: input.connectionId,
+              leaseTtlSeconds: input.leaseTtlSeconds,
+              sid,
+              url,
+              successfulAttempt: attempt,
+              attemptsUsed: attempt,
+              maxAttempts: PLAYER_CONNECTION_HEARTBEAT_MAX_ATTEMPTS,
+              durationMs: Date.now() - attemptStartedAt
+            });
+          }
+          return;
+        }
+        lastError = new Error(`heartbeat: ${res.status} ${text}`);
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+      const willRetry = attempt < PLAYER_CONNECTION_HEARTBEAT_MAX_ATTEMPTS;
+      console.warn("[agent-play:RemotePlayWorld] heartbeat:attempt_failed", {
+        phase: "player_connection_lease_refresh",
+        playerId: input.playerId,
+        connectionId: input.connectionId,
+        leaseTtlSeconds: input.leaseTtlSeconds,
+        sid,
+        url,
+        attempt,
+        maxAttempts: PLAYER_CONNECTION_HEARTBEAT_MAX_ATTEMPTS,
+        remainingAttemptsAfterThisFailure: PLAYER_CONNECTION_HEARTBEAT_MAX_ATTEMPTS - attempt,
+        errorMessage: lastError.message,
+        requestBodyBytes: bodyJson.length,
+        attemptDurationMs: Date.now() - attemptStartedAt,
+        nextAction: willRetry ? `sleep ${PLAYER_CONNECTION_HEARTBEAT_RETRY_DELAY_MS}ms then retry` : "no more retries; will throw",
+        retryDelayMs: willRetry ? PLAYER_CONNECTION_HEARTBEAT_RETRY_DELAY_MS : 0
+      });
+      if (!willRetry) {
+        throw lastError;
+      }
+      await new Promise((resolve) => {
+        setTimeout(resolve, PLAYER_CONNECTION_HEARTBEAT_RETRY_DELAY_MS);
+      });
+    }
+  }
+  async disconnectPlayerConnection(input) {
+    const sid = this.getSessionId();
+    const url = `${this.apiBase}/api/agent-play/players/disconnect?sid=${encodeURIComponent(sid)}`;
+    await fetch(url, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify({
+        playerId: input.playerId,
+        connectionId: input.connectionId
+      })
+    });
+  }
 };
+
+// src/index.ts
+import {
+  loadAgentPlayCredentialsFileFromPath,
+  loadAgentPlayCredentialsFileFromPathSync as loadAgentPlayCredentialsFileFromPathSync2,
+  loadRootKey as loadRootKey2,
+  nodeCredentialsMaterialFromHumanPassphrase as nodeCredentialsMaterialFromHumanPassphrase2,
+  parseAgentPlayCredentialsJson,
+  resolveAgentPlayCredentialsPath as resolveAgentPlayCredentialsPath2
+} from "@agent-play/node-tools";
 export {
   PLAYER_ADDED_EVENT,
   PLAYER_CHAIN_GENESIS_STABLE_KEY,
   PLAYER_CHAIN_HEADER_STABLE_KEY,
   RemotePlayWorld,
+  SESSION_CLOSED_EVENT,
+  SESSION_CONNECTED_EVENT,
+  SESSION_INVALID_EVENT,
+  SESSION_SSE_ERROR_EVENT,
+  SESSION_SSE_OPEN_EVENT,
   WORLD_AGENT_SIGNAL_EVENT,
   WORLD_INTERACTION_EVENT,
   WORLD_JOURNEY_EVENT,
@@ -746,13 +1217,20 @@ export {
   boundsContain,
   clampWorldPosition,
   configureAgentPlayDebug,
+  intercomResultRecordFromLangChainInvokeOutput,
   isAgentPlayDebugEnabled,
   langchainRegistration,
+  loadAgentPlayCredentialsFileFromPath,
+  loadAgentPlayCredentialsFileFromPathSync2 as loadAgentPlayCredentialsFileFromPathSync,
+  loadRootKey2 as loadRootKey,
   mergeSnapshotWithPlayerChainNode,
+  nodeCredentialsMaterialFromHumanPassphrase2 as nodeCredentialsMaterialFromHumanPassphrase,
+  parseAgentPlayCredentialsJson,
   parsePlayerChainFanoutNotify,
   parsePlayerChainFanoutNotifyFromSsePayload,
   parsePlayerChainNodeRpcBody,
   resetAgentPlayDebug,
+  resolveAgentPlayCredentialsPath2 as resolveAgentPlayCredentialsPath,
   sortNodeRefsForSerializedFetch
 };
 //# sourceMappingURL=index.js.map