@whitesands/agent-player 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.2.0
+
+### Minor Changes
+
+- Register a tool from a name, description, Zod schema, and callback with `bindDynamic`.
+- `start()` requires `playerId`, the character UUID from the web app. One platform key serves the game, and each session names the character to play.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -40,7 +40,7 @@ Use the same Zod 3 the SDK depends on when you declare argument schemas. Zod 4 o
 
 ## Usage
 
-Set the platform key, then start one agent per character. `turn()` grants that character one chance to act and resolves with what they did.
+Set the platform key, then start one agent per character. The key belongs to the game. `playerId` is the character id from the Players page, and every `start()` sends it. `turn()` grants that character one chance to act and resolves with what they did.
 
 ```sh
 export WSI_PLATFORM_KEY=pk_...
@@ -53,6 +53,7 @@ import { AgentServer } from "@whitesands/agent-player";
 
 const agents = new AgentServer();
 const ada = await agents.start(new Villager(world, "Ada"), {
+  playerId: "3f6c2d1e-8b7a-4c5d-9e0f-1a2b3c4d5e6f",
   name: "Ada",
   goal: "Stand on the tree and chop it",
 });
@@ -127,6 +128,28 @@ class Villager {
 }
 ```
 
+### Tools from data
+
+`bindDynamic` registers one tool when the action is data rather than a method. Call it on the player before `start()`. `see` is allowed, including when the player has no `see()` method. `wait`, an empty name, a name starting with `_`, and a missing callback are rejected. An empty description becomes `Action: <name>`. Registering the same name again replaces that tool, including a reflected method of the same name.
+
+Arguments use the same Zod shape as `static agent`. A schema failure throws before the callback runs and uses the one retry. Extra keys are ignored.
+
+```ts
+import { AgentServer, bindDynamic } from "@whitesands/agent-player";
+import { z } from "zod";
+
+const scout = { n: 1 };
+const playerId = "3f6c2d1e-8b7a-4c5d-9e0f-1a2b3c4d5e6f";
+bindDynamic(scout, "see", "", undefined, () => ({ n: scout.n }));
+bindDynamic(scout, "add", "Add dx", { dx: z.number().int() }, (args) => {
+  scout.n += args.dx as number;
+  return { n: scout.n };
+});
+
+const agents = new AgentServer();
+const agent = await agents.start(scout, { playerId });
+```
+
 ### Turns
 
 `turn()` does not choose the action. It unblocks that session's `wait`. The platform reads `see()`, calls one action, and reports back.
@@ -176,11 +199,19 @@ try {
 
 ### Several characters
 
-One `AgentServer` hosts every character. Each `start()` is its own session.
+One `AgentServer` and one platform key host every character in the game. Each `start()` is its own session and names that character with `playerId`. The id is a UUID, and it stays the same when the character is renamed. A missing id, a value that is not a UUID, or an id from another game is rejected and no session is created.
 
 ```ts
-const ada = await agents.start(new Villager(world, "Ada"), { name: "Ada", goal: "Chop the tree" });
-const bea = await agents.start(new Villager(world, "Bea"), { name: "Bea", goal: "Carry wood home" });
+const ada = await agents.start(new Villager(world, "Ada"), {
+  playerId: "3f6c2d1e-8b7a-4c5d-9e0f-1a2b3c4d5e6f",
+  name: "Ada",
+  goal: "Chop the tree",
+});
+const bea = await agents.start(new Villager(world, "Bea"), {
+  playerId: "6b1e2a30-0c1d-4e5f-8a9b-0c1d2e3f4a5b",
+  name: "Bea",
+  goal: "Carry wood home",
+});
 
 await ada.turn();
 await bea.turn();
@@ -234,6 +265,7 @@ const agents = new AgentServer({
 
 ```ts
 await agents.start(ferry, {
+  playerId: "3f6c2d1e-8b7a-4c5d-9e0f-1a2b3c4d5e6f",
   name: "Ferryman",
   goal: "Get the wolf, the goat, and the cabbage onto the far bank.",
 });
@@ -241,7 +273,7 @@ await agents.start(ferry, {
 
 ### Testing without a platform
 
-`@whitesands/agent-player/testing` runs the same wait, act, and retry loop in memory. The script is the list of tool calls, in order. No key and no socket.
+`@whitesands/agent-player/testing` runs the same wait, act, and retry loop in memory. The script is the list of tool calls, in order. No key and no socket. `start()` still requires `playerId`.
 
 ```ts
 import { AgentServer } from "@whitesands/agent-player";

package/dist/index.cjs

@@ -35,7 +35,8 @@ __export(src_exports, {
   PlatformAuthError: () => PlatformAuthError,
   ProtocolVersionError: () => ProtocolVersionError,
   TurnFailedError: () => TurnFailedError,
-  TurnTimeoutError: () => TurnTimeoutError
+  TurnTimeoutError: () => TurnTimeoutError,
+  bindDynamic: () => bindDynamic
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -158,7 +159,7 @@ var import_ws = __toESM(require("ws"), 1);
 
 // src/protocol.ts
 var PROTOCOL_VERSION = 1;
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "1.2.0";
 var SESSION_RESUME_GRACE_MS = 3e4;
 var DEFAULT_AGENT_INSTRUCTIONS = [
   "You are a remote game agent. Tools are provided by the game.",
@@ -167,6 +168,17 @@ var DEFAULT_AGENT_INSTRUCTIONS = [
   "The view's done list is what this character has already called in this session, oldest first. Use it when choosing the next action.",
   "If an action tool returns an error, retry once with a corrected action. A second failure ends the turn as failed."
 ].join("\n");
+var PLAYER_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requirePlayerId(value) {
+  const id = value?.trim() ?? "";
+  if (id.length === 0) {
+    throw new Error("playerId is required. Copy the character ID from the web app");
+  }
+  if (!PLAYER_ID.test(id)) {
+    throw new Error(`playerId "${id}" is not a character ID. Copy the ID from the character in the web app`);
+  }
+  return id;
+}
 function assertNever(value) {
   throw new Error(`Unhandled protocol message: ${JSON.stringify(value)}`);
 }
@@ -279,6 +291,14 @@ var PlatformConnection = class {
       });
     });
   }
+  /** Reject a start, stop, or resume wait. No-op when nothing is waiting. */
+  failSessionEvent(sessionId, kind, error) {
+    const key = `session:${sessionId}:${kind}`;
+    const waiter = this.pending.get(key);
+    if (!waiter) return;
+    this.pending.delete(key);
+    waiter.reject(error);
+  }
   createTransport(sessionId) {
     return new SessionMuxTransport(sessionId, (envelope) => this.send(envelope));
   }
@@ -482,6 +502,7 @@ var PlatformConnection = class {
 var import_zod = require("zod");
 var import_zod_to_json_schema = require("zod-to-json-schema");
 var SKIP = /* @__PURE__ */ new Set(["constructor"]);
+var dynamicTools = /* @__PURE__ */ new WeakMap();
 var SEE_DESCRIPTION = "Read the current game view for this player. Prefer wait, which returns this after the game grants a turn.";
 var WAIT_DESCRIPTION = "Block until the game calls turn() for this session, then return the current see() view.";
 function getParamNames(fn) {
@@ -525,6 +546,56 @@ function formatZodError(error) {
     return `${path}: ${issue.message}`;
   }).join("; ");
 }
+function rejectDynamicName(name) {
+  if (name.length === 0 || name === "wait" || name.startsWith("_")) {
+    throw new Error(`cannot publish action "${name}"`);
+  }
+}
+function dynamicBindings(player) {
+  return dynamicTools.get(player) ?? /* @__PURE__ */ new Map();
+}
+function bindDynamic(player, name, description, args, callback) {
+  rejectDynamicName(name);
+  if (typeof callback !== "function") {
+    throw new Error(`cannot publish action "${name}"`);
+  }
+  const shape = args && Object.keys(args).length > 0 ? { ...args } : void 0;
+  let tools = dynamicTools.get(player);
+  if (!tools) {
+    tools = /* @__PURE__ */ new Map();
+    dynamicTools.set(player, tools);
+  }
+  tools.set(name, {
+    name,
+    description: description.length > 0 ? description : `Action: ${name}`,
+    ...shape ? { args: shape } : {},
+    callback
+  });
+}
+function buildDynamicTool(binding) {
+  const shape = binding.args;
+  const paramNames = shape ? Object.keys(shape) : [];
+  const argsSchema = shape ? import_zod.z.object(shape) : void 0;
+  const inputSchema = argsSchema ? toJsonSchema(argsSchema) : { type: "object", properties: {} };
+  return {
+    name: binding.name,
+    description: binding.description,
+    paramNames,
+    ...argsSchema ? { argsSchema } : {},
+    descriptor: { name: binding.name, description: binding.description, inputSchema },
+    async invoke(args) {
+      let parsed = {};
+      if (argsSchema) {
+        const result = argsSchema.safeParse(args ?? {});
+        if (!result.success) {
+          throw new Error(formatZodError(result.error));
+        }
+        parsed = result.data;
+      }
+      return await Promise.resolve(binding.callback(parsed));
+    }
+  };
+}
 function buildTool(instance, name, description, spec) {
   const fn = instance[name];
   if (typeof fn !== "function") {
@@ -560,24 +631,31 @@ function buildTool(instance, name, description, spec) {
 }
 function reflectPlayer(instance) {
   const names = collectMethodNames(instance);
-  if (!names.includes("see")) {
+  const dynamic = dynamicBindings(instance);
+  if (!names.includes("see") && !dynamic.has("see")) {
     throw new Error("Player must implement a public see() method");
   }
   const metadata = readMetadata(instance);
   const declared = metadata?.actions ?? {};
   const className = instance.constructor?.name || "Player";
   for (const name of Object.keys(declared)) {
-    if (!names.includes(name) || name === "see") {
+    if (name === "see" || !names.includes(name) && !dynamic.has(name)) {
       throw new Error(`Declared action "${name}" is not a public method on ${className}`);
     }
   }
-  const see = buildTool(instance, "see", SEE_DESCRIPTION);
-  const actionNames = names.filter((name) => name !== "see");
-  const actions = actionNames.map((name) => {
+  const dynamicSee = dynamic.get("see");
+  const see = dynamicSee ? buildDynamicTool(dynamicSee) : buildTool(instance, "see", SEE_DESCRIPTION);
+  const actions = [];
+  for (const name of names) {
+    if (name === "see" || dynamic.has(name)) continue;
     const spec = declared[name];
     const description = spec?.description ?? `Action: ${name}`;
-    return buildTool(instance, name, description, spec);
-  });
+    actions.push(buildTool(instance, name, description, spec));
+  }
+  for (const [name, binding] of dynamic) {
+    if (name === "see") continue;
+    actions.push(buildDynamicTool(binding));
+  }
   const wait = {
     name: "wait",
     description: WAIT_DESCRIPTION,
@@ -826,6 +904,7 @@ var AgentServer = class {
    * `turn()` on that handle lets the remote model act once.
    */
   async start(instance, options) {
+    const playerId = requirePlayerId(options.playerId);
     await this.connect();
     const reflected = reflectPlayer(instance);
     const sessionId = (0, import_node_crypto2.randomUUID)();
@@ -857,41 +936,54 @@ var AgentServer = class {
       gate.completeTurn(result);
     };
     const onEvent = (event) => this.emit(event);
-    if (this.inline) {
-      const [serverTransport, clientTransport] = import_inMemory.InMemoryTransport.createLinkedPair();
-      await server.connect(serverTransport);
-      record.transport = serverTransport;
-      this.sessions.set(sessionId, record);
-      await this.inline.startSession({
-        sessionId,
-        sessionToken,
-        name,
-        tools: reflected.tools,
-        instructions,
-        ...options?.goal ? { goal: options.goal } : {},
-        ...this.logger ? { logger: this.logger } : {},
-        transport: clientTransport,
-        onTurnResult,
-        onEvent
-      });
-    } else {
-      if (!this.connection) throw new Error("Not connected");
-      const mux = this.connection.createTransport(sessionId);
-      await server.connect(mux);
-      record.transport = mux;
-      record.mux = mux;
-      this.sessions.set(sessionId, record);
-      const started = this.connection.waitForSessionEvent(sessionId, "start");
-      this.connection.send({
-        type: "start_session",
-        sessionId,
-        sessionToken,
-        name,
-        tools: reflected.tools,
-        instructions,
-        ...options?.goal ? { goal: options.goal } : {}
-      });
-      await started;
+    this.sessions.set(sessionId, record);
+    try {
+      if (this.inline) {
+        const [serverTransport, clientTransport] = import_inMemory.InMemoryTransport.createLinkedPair();
+        await server.connect(serverTransport);
+        record.transport = serverTransport;
+        await this.inline.startSession({
+          sessionId,
+          sessionToken,
+          playerId,
+          name,
+          tools: reflected.tools,
+          instructions,
+          ...options.goal ? { goal: options.goal } : {},
+          ...this.logger ? { logger: this.logger } : {},
+          transport: clientTransport,
+          onTurnResult,
+          onEvent
+        });
+      } else {
+        if (!this.connection) throw new Error("Not connected");
+        const mux = this.connection.createTransport(sessionId);
+        await server.connect(mux);
+        record.transport = mux;
+        record.mux = mux;
+        const started = this.connection.waitForSessionEvent(sessionId, "start");
+        try {
+          this.connection.send({
+            type: "start_session",
+            sessionId,
+            sessionToken,
+            playerId,
+            name,
+            tools: reflected.tools,
+            instructions,
+            ...options.goal ? { goal: options.goal } : {}
+          });
+          await started;
+        } catch (error) {
+          const wrapped = error instanceof Error ? error : new Error(String(error));
+          this.connection.failSessionEvent(sessionId, "start", wrapped);
+          await started.catch(() => void 0);
+          throw wrapped;
+        }
+      }
+    } catch (error) {
+      await this.stopSession(sessionId);
+      throw error;
     }
     return {
       sessionId,
@@ -991,6 +1083,9 @@ var AgentServer = class {
       }
       case "error":
         log(this.logger, "error", envelope.message);
+        if (envelope.sessionId) {
+          this.connection?.failSessionEvent(envelope.sessionId, "start", new Error(envelope.message));
+        }
         return;
       case "session_started":
       case "session_stopped":
@@ -1067,6 +1162,7 @@ var AgentServer = class {
   PlatformAuthError,
   ProtocolVersionError,
   TurnFailedError,
-  TurnTimeoutError
+  TurnTimeoutError,
+  bindDynamic
 });
 //# sourceMappingURL=index.cjs.map