@whitesands/agent-player 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.3.0
+
+- `start()` takes `memory`, `maxActions`, `subgoals` and `ownInstructions`.
+- With `memory: true` the platform keeps the character's memory and relationships. `handle.observe(text, about)` adds an event without a turn, `handle.relationships()` reads how it feels about people, and `memory` and `relationship` events are emitted.
+- `TurnResult.steps` lists every action when a turn played more than one.
+- `World`: describe places, things and characters once; it builds each character's view and standard actions, carries speech, and decides when a character gets a turn. Port of `WSI.World` from the Luau SDK.
+- `examples/town`: Sandy Shores as a browser game on `World`.
+- A refused `start_session` now rejects `start()` with the platform's reason instead of timing out.
+- A reconnect that fails part-way can no longer end the process with an unhandled "Timed out waiting for session resume".
+
+## 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";
@@ -309,3 +341,26 @@ PLATFORM_KEY=pk_... npm run forest -- --remote
 ```
 
 Releases are recorded in [CHANGELOG.md](CHANGELOG.md).
+
+## World
+
+`World` builds a living world on top of the agent player, so a game does not write a view or actions per character. The game provides the engine: places, things with activities, and a body per character (`getPosition`, `moveTo`, `stop`, `say`). `World` serves each character's tools over MCP (`say`, `go_to`, `approach`, `use`, `give`, `emote`, `idle`), carries speech between characters and players, and decides when a character needs a turn. Who each character is comes from its role and story on the platform.
+
+```ts
+import { AgentServer, World } from "@whitesands/agent-player";
+
+const world = new World(new AgentServer(), { name: "Sandy Shores", about: "A small beach town." });
+world.addPlace("cafe", { description: "Mia's cafe", position: { x: 60, y: 0 } });
+world.addThing("espresso_machine", {
+  place: "cafe",
+  position: { x: 64, y: -4 },
+  activities: { make_coffee: { description: "Make a coffee", seconds: 6, gives: "coffee" } },
+});
+await world.addCharacter({ id: miaCharacterId, name: "Mia", body: miaBody, home: "cafe" });
+world.addPerson({ name: "Alex", getPosition: () => alexPosition });
+world.on((event) => { /* speech, relationship, status, give, thinking, turn */ });
+world.start();
+world.say("Alex", "Hi Mia!");
+```
+
+`examples/town` is a complete browser game built this way: `npm run build && WSI_PLATFORM_KEY=pk_... npm run town`, then open `http://localhost:8080`.