@whitesands/agent-player 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -1,14 +1,18 @@
 # Changelog
 
+## 1.0.0
+
+### Major Changes
+
+- Remember each character's actions in a local SQLite file and include them on the next view.
+
 ## 0.2.0
 
 ### Minor Changes
 
 - 46faef6: Publish the agent player SDK: typed actions, turn results, reconnect, and an offline testing entry.
 
-## 0.1.0
-
-First public SDK release.
+First release published to npm.
 
 - `AgentServer` reads `WSI_PLATFORM_KEY` and `WSI_PLATFORM_URL`.
 - Player classes can declare zod argument schemas and descriptions.

package/README.md

@@ -1,35 +1,111 @@
-# @whitesands/agent-player
+# WSI Agent Player
 
-Start a remote game agent from a player class. You call `start` and `turn`. The SDK owns the MCP server. The model stays on the platform, so the game never sees the model key.
+[![npm version](https://img.shields.io/npm/v/@whitesands/agent-player.svg)](https://www.npmjs.com/package/@whitesands/agent-player)
+[![Build Status](https://github.com/White-Sands-Interactive/WSI-Node-Framework/actions/workflows/ci.yml/badge.svg)](https://github.com/White-Sands-Interactive/WSI-Node-Framework/actions/workflows/ci.yml)
 
-```bash
+The library starts a remote game agent from a player class. The game calls `start` and `turn`. The SDK publishes that class as tools. The model runs on the [platform](https://github.com/White-Sands-Interactive/Platform), so the game process never holds the model key.
+
+The library also provides:
+
+- A player class turned into tools, with optional Zod argument schemas.
+- One action per turn, and one retry when that action throws.
+- An offline loop for tests, with no socket and no platform key.
+- A local SQLite log of what each character has already called.
+
+## Documentation
+
+This page is the guide. Generate the API reference with:
+
+```sh
+npm run docs
+```
+
+TypeDoc writes HTML to `docs`.
+
+## Installation
+
+You don't need this source code unless you want to modify the SDK. To use the package:
+
+```sh
 npm install @whitesands/agent-player
+```
+
+### Requirements
+
+Node.js 20 or newer.
+
+Installing the package builds `better-sqlite3`. npm uses a prebuilt binary on current macOS, Linux, and Windows. That module is the action log described below.
+
+Use the same Zod 3 the SDK depends on when you declare argument schemas. Zod 4 objects are not read as schemas.
+
+## 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.
+
+```sh
 export WSI_PLATFORM_KEY=pk_...
-export WSI_PLATFORM_URL=wss://your-platform.example
+export WSI_PLATFORM_URL=ws://127.0.0.1:8787
 ```
 
+`WSI_PLATFORM_URL` defaults to `ws://127.0.0.1:8787` when it is unset.
+
 ```ts
 import { AgentServer } from "@whitesands/agent-player";
 
 const agents = new AgentServer();
 const ada = await agents.start(new Villager(world, "Ada"), {
-  goal: "Collect all the wood",
+  name: "Ada",
+  goal: "Stand on the tree and chop it",
 });
 
 const result = await ada.turn();
 // { action: "move", args: { dx: 1, dy: 0 }, result, attempts: 1, usage }
 ```
 
-`new AgentServer()` reads `WSI_PLATFORM_KEY` and `WSI_PLATFORM_URL`. Until a hosted URL is the default, set `WSI_PLATFORM_URL` (it falls back to `ws://127.0.0.1:8787`).
+`new AgentServer({ platformKey, platformUrl })` overrides the environment variables.
 
-## Player class
+### The player class
 
-- `see()` is the state tool. It must be public and return JSON-safe data.
-- Every other public method is an action. The model calls one per turn.
-- Methods whose names start with `_`, and the constructor, are not tools.
-- Throw to reject an action. The platform asks the model once more, then `turn()` rejects with `TurnFailedError`.
+`see()` is required. It returns the JSON the model reads at the start of the turn. Every other public method is an action the model may call. Names that start with `_`, and the constructor, are left off the tool list.
 
-Optional static metadata adds descriptions and argument types. Undeclared public methods are still tools. Without metadata, arguments accept any JSON value.
+Throw to refuse an action. The platform asks the model once more. A second failure rejects `turn()` with `TurnFailedError`.
+
+```ts
+class Villager {
+  x = 0;
+  y = 0;
+  wood = 0;
+
+  see() {
+    return { x: this.x, y: this.y, wood: this.wood, tile: world.get(this.x, this.y) };
+  }
+
+  move(dx: number, dy: number) {
+    const nextX = this.x + dx;
+    const nextY = this.y + dy;
+    if (!world.inBounds(nextX, nextY)) {
+      throw new Error(`Cannot move to ${nextX},${nextY}`);
+    }
+    this.x = nextX;
+    this.y = nextY;
+    return { x: this.x, y: this.y };
+  }
+
+  chop() {
+    if (world.get(this.x, this.y) !== "T") {
+      throw new Error(`No tree at ${this.x},${this.y}`);
+    }
+    this.wood += 1;
+    return { wood: this.wood };
+  }
+}
+```
+
+A method with no `static agent` entry is still a tool. Its arguments accept any JSON value.
+
+### Declaring arguments
+
+`static agent` adds the description the model sees and checks arguments with Zod before your method runs. A schema failure counts as a failed action and uses the one retry.
 
 ```ts
 import { z } from "zod";
@@ -39,20 +115,22 @@ class Villager {
     description: "A villager who gathers wood",
     actions: {
       move: {
-        description: "Step by dx, dy",
+        description: "Step by dx and dy. Stay inside the map.",
         args: { dx: z.number().int(), dy: z.number().int() },
       },
       chop: { description: "Chop the tree on your tile" },
     },
   };
+
+  see() {
+    return { x: this.x, y: this.y };
+  }
 }
 ```
 
-Use the same Zod major version the SDK depends on (`zod@3`).
-
-## Turns
+### Turns
 
-`turn()` does not choose the action. It unblocks that session's `wait`, then resolves when the platform has called one action (or retried once).
+`turn()` does not choose the action. It unblocks that session's `wait`. The platform reads `see()`, calls one action, and reports back.
 
 ```ts
 const result = await ada.turn({ timeoutMs: 30_000, signal });
@@ -63,28 +141,108 @@ const result = await ada.turn({ timeoutMs: 30_000, signal });
 | `action` | Tool the model called |
 | `args` | Arguments it passed |
 | `result` | What your method returned |
-| `attempts` | `1`, or `2` when the first call failed |
-| `usage` | Prompt and completion tokens for that turn |
+| `attempts` | `1`, or `2` when the first call failed and the retry succeeded |
+| `usage` | `promptTokens` and `completionTokens` for that turn |
+
+The default timeout is 60 seconds. Pass `signal` to abort the wait. `handle.stop()` ends that session. `agents.close()`, also run by `await using`, stops every session on the server. The platform process keeps running.
+
+```ts
+await using agents = new AgentServer();
+```
 
-## Errors
+### Errors
 
 | Error | When |
 | --- | --- |
-| `PlatformAuthError` | The platform key was rejected |
-| `ProtocolVersionError` | The SDK and platform disagree on the protocol |
-| `TurnFailedError` | Both the action and the retry failed. `error.attempts` lists both |
-| `TurnTimeoutError` | The platform did not finish within `timeoutMs` (default 60s) |
-| `ConnectionLostError` | The socket dropped and could not be resumed |
+| `PlatformAuthError` | The platform rejected the key |
+| `ProtocolVersionError` | This SDK and the platform disagree on the protocol |
+| `TurnFailedError` | The action and the retry both failed. `error.attempts` lists both calls |
+| `TurnTimeoutError` | The platform did not finish within `timeoutMs` |
+| `ConnectionLostError` | The socket dropped and the session could not be resumed |
 
-The SDK reconnects with backoff and resumes sessions for 30 seconds. Subscribe with `agents.on(listener)` or `handle.on(listener)` for `action`, `retry`, `turnFailed`, `disconnected`, and `reconnected`.
+The SDK reconnects with backoff. A disconnected session can be resumed for 30 seconds.
 
 ```ts
-await using agents = new AgentServer();
+import { TurnFailedError } from "@whitesands/agent-player";
+
+try {
+  await ada.turn();
+} catch (error) {
+  if (error instanceof TurnFailedError) {
+    console.log(error.attempts);
+  }
+  throw error;
+}
 ```
 
-`await using` calls `close()`, which stops every session. The platform process keeps running.
+### Several characters
 
-## Testing without a network
+One `AgentServer` hosts every character. Each `start()` is its own session.
+
+```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" });
+
+await ada.turn();
+await bea.turn();
+```
+
+The game decides whose turn it is by calling `turn()` on that handle.
+
+### Events
+
+`agents.on` hears every session. `handle.on` hears one session. Both return an unsubscribe function.
+
+```ts
+const stop = ada.on((event) => {
+  if (event.type === "action") console.log(event.action, event.args);
+  if (event.type === "retry") console.log(event.action, event.error);
+  if (event.type === "turnFailed") console.log(event.error);
+});
+```
+
+Connection events are `disconnected` and `reconnected`. Those have no `sessionId`.
+
+### Action history
+
+Every `start()` records that character's calls in one SQLite file, `.wsi/agent-memory.sqlite` in the process's current directory. The directory is created on the first `start()`. Deleting it is safe. The next start creates it again.
+
+The next `see()` view includes `done`, oldest first, up to the last 50 calls for that session:
+
+```json
+{
+  "x": 1,
+  "y": 0,
+  "done": [
+    { "action": "move", "args": { "dx": 1, "dy": 0 }, "ok": true }
+  ]
+}
+```
+
+A refused call is `{ "ok": false, "error": "..." }`. A new `start()` has an empty `done` list. Older rows stay in the file. Two characters on one server share the file and see only their own rows. The name on each row is the `name` passed to `start()`, or the class name.
+
+```ts
+const agents = new AgentServer({
+  memoryPath: "saves/agents.sqlite",
+});
+```
+
+`memoryPath: false` turns the log off. The view then has no `done` field.
+
+### Goal and instructions
+
+`goal` is added to the model prompt for that character. `instructions` on `start()` is appended to the default prompt. `instructions` on `AgentServer` replaces the default prompt for every character on that server.
+
+```ts
+await agents.start(ferry, {
+  name: "Ferryman",
+  goal: "Get the wolf, the goat, and the cabbage onto the far bank.",
+});
+```
+
+### 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.
 
 ```ts
 import { AgentServer } from "@whitesands/agent-player";
@@ -93,26 +251,64 @@ import { createTestPlatform } from "@whitesands/agent-player/testing";
 const agents = new AgentServer({
   inline: createTestPlatform([
     { name: "move", arguments: { dx: 1, dy: 0 } },
+    { name: "chop", arguments: {} },
   ]),
 });
 ```
 
-`createTestPlatform` runs the same wait / act / retry loop in memory. No key, no socket.
-
-## What runs where
+### Where each piece runs
 
 | | Game process | Platform |
 | --- | --- | --- |
-| World and player methods | yes | no |
-| MCP tools (`see`, actions, `wait`) | yes | calls them |
-| Whose turn it is | `turn()` | no |
-| Which action to take | no | the model |
-| Model API key | no | yes |
+| World and player methods | yes | |
+| Tools (`see`, actions, `wait`) | yes | calls them |
+| Whose turn it is | `turn()` | |
+| Which action to take | | the model |
+| Model API key | | yes |
+
+### Logging
+
+Pass a `logger` to print SDK warnings. Omit it and nothing is written.
+
+```ts
+const agents = new AgentServer({
+  logger: {
+    warn: (message) => console.warn(message),
+    error: (message) => console.error(message),
+  },
+});
+```
+
+`debug`, `info`, `warn`, and `error` are all optional.
+
+### Protocol
+
+`@whitesands/agent-player/protocol` exports the wire types and `PROTOCOL_VERSION`. The platform's copy is `internal/protocol` in [White-Sands-Interactive/Platform](https://github.com/White-Sands-Interactive/Platform). A change to the wire format has to land in both places. Game code uses the main entry and does not import the protocol.
+
+## This repository
+
+| Path | Role |
+| --- | --- |
+| `src` | The published SDK |
+| `examples/forest` | Two villagers, reflected methods |
+| `examples/courier` | Zod arguments and a goal |
+| `examples/ferry` | One passenger chosen each turn |
+
+```sh
+npm install
+npm test
+npm run build
+npm run forest
+npm run courier
+npm run ferry
+```
 
-## API reference
+Each example replays a script. Add `-- --remote` to use a platform that is already serving:
 
-```bash
-npm run docs -w @whitesands/agent-player
+```sh
+./platform create-key demo
+MODEL_API_KEY=... MODEL_BASE_URL=... MODEL_NAME=... ./platform serve
+PLATFORM_KEY=pk_... npm run forest -- --remote
 ```
 
-TypeDoc writes HTML to `packages/agent-player/docs`.
+`./platform` is the Go server from the Platform repository. Releases are recorded in [CHANGELOG.md](CHANGELOG.md).

package/dist/index.cjs

@@ -32,11 +32,8 @@ var src_exports = {};
 __export(src_exports, {
   AgentServer: () => AgentServer,
   ConnectionLostError: () => ConnectionLostError,
-  DEFAULT_AGENT_INSTRUCTIONS: () => DEFAULT_AGENT_INSTRUCTIONS,
-  PROTOCOL_VERSION: () => PROTOCOL_VERSION,
   PlatformAuthError: () => PlatformAuthError,
   ProtocolVersionError: () => ProtocolVersionError,
-  SDK_VERSION: () => SDK_VERSION,
   TurnFailedError: () => TurnFailedError,
   TurnTimeoutError: () => TurnTimeoutError
 });
@@ -85,18 +82,89 @@ function log(logger, level, message, extra) {
   logger?.[level]?.(message, extra);
 }
 
+// src/memory.ts
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var MAX_DONE = 50;
+var SessionMemory = class {
+  db;
+  constructor(path) {
+    (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(path), { recursive: true });
+    this.db = new import_better_sqlite3.default(path, { timeout: 5e3 });
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS actions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL,
+        character TEXT NOT NULL,
+        action TEXT NOT NULL,
+        args TEXT NOT NULL,
+        ok INTEGER NOT NULL,
+        error TEXT
+      );
+      CREATE INDEX IF NOT EXISTS actions_by_session ON actions(session_id, id);
+    `);
+  }
+  record(sessionId, character, entry) {
+    this.db.prepare(
+      `INSERT INTO actions (session_id, character, action, args, ok, error)
+         VALUES (@sessionId, @character, @action, @args, @ok, @error)`
+    ).run({
+      sessionId,
+      character,
+      action: entry.action,
+      args: JSON.stringify(entry.args),
+      ok: entry.ok ? 1 : 0,
+      error: entry.error ?? null
+    });
+  }
+  /** Oldest first, capped to the most recent actions for this session. */
+  done(sessionId) {
+    const rows = this.db.prepare(
+      `SELECT action, args, ok, error FROM (
+           SELECT id, action, args, ok, error FROM actions
+           WHERE session_id = ?
+           ORDER BY id DESC
+           LIMIT ?
+         ) ORDER BY id ASC`
+    ).all(sessionId, MAX_DONE);
+    return rows.map((row) => {
+      const entry = {
+        action: row.action,
+        args: JSON.parse(row.args),
+        ok: row.ok === 1
+      };
+      if (row.error) entry.error = row.error;
+      return entry;
+    });
+  }
+  close() {
+    this.db.close();
+  }
+};
+function defaultMemoryPath() {
+  return (0, import_node_path.resolve)(process.cwd(), ".wsi", "agent-memory.sqlite");
+}
+function viewWithDone(view, done) {
+  if (view && typeof view === "object" && !Array.isArray(view)) {
+    return { ...view, done };
+  }
+  return { view, done };
+}
+
 // src/platform-connection.ts
 var import_node_crypto = require("crypto");
 var import_ws = __toESM(require("ws"), 1);
 
 // src/protocol.ts
 var PROTOCOL_VERSION = 1;
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "1.0.0";
 var SESSION_RESUME_GRACE_MS = 3e4;
 var DEFAULT_AGENT_INSTRUCTIONS = [
   "You are a remote game agent. Tools are provided by the game.",
   "On every turn: call wait first. It blocks until the game grants your turn and then returns the current view from see.",
   "After wait returns, call exactly one action tool (not see, not wait).",
+  "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");
 function assertNever(value) {
@@ -194,7 +262,7 @@ var PlatformConnection = class {
   }
   waitForSessionEvent(sessionId, kind, timeoutMs = 15e3) {
     const key = `session:${sessionId}:${kind}`;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(key);
         reject(new Error(`Timed out waiting for session ${kind}`));
@@ -202,7 +270,7 @@ var PlatformConnection = class {
       this.pending.set(key, {
         resolve: (envelope) => {
           clearTimeout(timer);
-          resolve(envelope);
+          resolve2(envelope);
         },
         reject: (error) => {
           clearTimeout(timer);
@@ -224,13 +292,13 @@ var PlatformConnection = class {
     if (!this.ws) return;
     const ws = this.ws;
     this.ws = null;
-    await new Promise((resolve) => {
-      ws.once("close", () => resolve());
+    await new Promise((resolve2) => {
+      ws.once("close", () => resolve2());
       ws.close();
     });
   }
   openSocket() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const ws = new import_ws.default(this.url);
       this.ws = ws;
       let settled = false;
@@ -269,7 +337,7 @@ var PlatformConnection = class {
           this.accountName = envelope.accountName;
           this.startHeartbeat();
           this.flushOutbox();
-          resolve(envelope.accountName);
+          resolve2(envelope.accountName);
           return;
         }
         if (envelope.type === "pong") {
@@ -540,13 +608,17 @@ function createSessionMcpServer(player, gate, options) {
     { name: options?.name ?? "agent-player", version: SDK_VERSION },
     { capabilities: { tools: {} } }
   );
+  const actions = options?.actions;
+  const viewed = async () => {
+    const view = await player.see.invoke({});
+    return actions ? viewWithDone(view, actions.done()) : view;
+  };
   server.registerTool(
     "see",
     { description: player.see.description },
     async () => {
       try {
-        const view = await player.see.invoke({});
-        return jsonResult(view);
+        return jsonResult(await viewed());
       } catch (error) {
         return toolError(error);
       }
@@ -558,8 +630,7 @@ function createSessionMcpServer(player, gate, options) {
     async () => {
       try {
         await gate.waitForTurn();
-        const view = await player.see.invoke({});
-        return jsonResult(view);
+        return jsonResult(await viewed());
       } catch (error) {
         return toolError(error);
       }
@@ -569,8 +640,11 @@ function createSessionMcpServer(player, gate, options) {
     const handler = async (args) => {
       try {
         const result = await action.invoke(args);
+        actions?.record({ action: action.name, args, ok: true });
         return jsonResult(result ?? { ok: true });
       } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        actions?.record({ action: action.name, args, ok: false, error: message });
         return toolError(error);
       }
     };
@@ -615,8 +689,8 @@ var TurnGate = class {
       return;
     }
     if (!this.waitPromise) {
-      this.waitPromise = new Promise((resolve) => {
-        this.waitResolve = resolve;
+      this.waitPromise = new Promise((resolve2) => {
+        this.waitResolve = resolve2;
       });
     }
     await this.waitPromise;
@@ -638,8 +712,8 @@ var TurnGate = class {
     let timeoutId;
     let onAbort;
     const signal = options?.signal;
-    this.turnPromise = new Promise((resolve, reject) => {
-      this.turnResolve = resolve;
+    this.turnPromise = new Promise((resolve2, reject) => {
+      this.turnResolve = resolve2;
       this.turnReject = reject;
       if (options?.timeoutMs != null) {
         timeoutId = setTimeout(() => {
@@ -672,11 +746,11 @@ var TurnGate = class {
   }
   /** Platform finished one action cycle (success or second failure). */
   completeTurn(outcome) {
-    const resolve = this.turnResolve;
-    if (!resolve) return;
+    const resolve2 = this.turnResolve;
+    if (!resolve2) return;
     this.turnResolve = null;
     this.turnReject = null;
-    resolve(outcome);
+    resolve2(outcome);
   }
   /** Fail an in-flight turn, for example when the connection cannot be resumed. */
   failTurn(error) {
@@ -710,6 +784,7 @@ var AgentServer = class {
   sessions = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
   inline;
+  memory = null;
   started = false;
   closing = false;
   constructor(options = {}) {
@@ -757,8 +832,15 @@ var AgentServer = class {
     const sessionToken = (0, import_node_crypto2.randomUUID)();
     const gate = new TurnGate();
     const name = options?.name ?? instance.constructor?.name ?? "player";
+    const memory = this.actionMemory();
     const server = createSessionMcpServer(reflected, gate, {
-      name: `agent-player:${name}`
+      name: `agent-player:${name}`,
+      ...memory ? {
+        actions: {
+          record: (entry) => memory.record(sessionId, name, entry),
+          done: () => memory.done(sessionId)
+        }
+      } : {}
     });
     const instructions = [this.options.instructions ?? DEFAULT_AGENT_INSTRUCTIONS, options?.instructions].filter((part) => Boolean(part && part.length > 0)).join("\n\n");
     const listeners = /* @__PURE__ */ new Set();
@@ -961,9 +1043,19 @@ var AgentServer = class {
       await this.connection.close();
       this.connection = null;
     }
+    this.memory?.close();
+    this.memory = null;
     this.started = false;
     this.closing = false;
   }
+  actionMemory() {
+    if (this.options.memoryPath === false) return null;
+    if (!this.memory) {
+      const path = this.options.memoryPath ?? defaultMemoryPath();
+      this.memory = new SessionMemory(path);
+    }
+    return this.memory;
+  }
   async [Symbol.asyncDispose]() {
     await this.close();
   }
@@ -972,11 +1064,8 @@ var AgentServer = class {
 0 && (module.exports = {
   AgentServer,
   ConnectionLostError,
-  DEFAULT_AGENT_INSTRUCTIONS,
-  PROTOCOL_VERSION,
   PlatformAuthError,
   ProtocolVersionError,
-  SDK_VERSION,
   TurnFailedError,
   TurnTimeoutError
 });