@whitesands/agent-player 1.1.0 → 1.3.0

package/dist/index.cjs

@@ -31,11 +31,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   AgentServer: () => AgentServer,
+  Character: () => Character,
   ConnectionLostError: () => ConnectionLostError,
   PlatformAuthError: () => PlatformAuthError,
   ProtocolVersionError: () => ProtocolVersionError,
   TurnFailedError: () => TurnFailedError,
-  TurnTimeoutError: () => TurnTimeoutError
+  TurnTimeoutError: () => TurnTimeoutError,
+  World: () => World,
+  bindDynamic: () => bindDynamic
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -158,7 +161,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.3.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 +170,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 +293,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));
   }
@@ -377,6 +399,15 @@ var PlatformConnection = class {
       waiter.resolve(envelope);
       return;
     }
+    if (envelope.type === "error" && envelope.sessionId) {
+      const key = `session:${envelope.sessionId}:start`;
+      const waiter = this.pending.get(key);
+      if (waiter) {
+        this.pending.delete(key);
+        waiter.reject(new Error(envelope.message));
+      }
+      return;
+    }
     if (envelope.type === "session_resumed" || envelope.type === "resume_err") {
       const waiter = this.pending.get(`session:${envelope.sessionId}:resume`);
       if (!waiter) return;
@@ -416,6 +447,8 @@ var PlatformConnection = class {
       const sessions = this.handlers.sessions?.() ?? [];
       for (const session of sessions) {
         const resumed = this.waitForSessionEvent(session.sessionId, "resume");
+        resumed.catch(() => {
+        });
         this.send({
           type: "resume_session",
           sessionId: session.sessionId,
@@ -482,6 +515,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 +559,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 +644,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,13 +917,14 @@ 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)();
     const sessionToken = (0, import_node_crypto2.randomUUID)();
     const gate = new TurnGate();
     const name = options?.name ?? instance.constructor?.name ?? "player";
-    const memory = this.actionMemory();
+    const memory = options?.memory ? null : this.actionMemory();
     const server = createSessionMcpServer(reflected, gate, {
       name: `agent-player:${name}`,
       ...memory ? {
@@ -842,7 +934,10 @@ var AgentServer = class {
         }
       } : {}
     });
-    const instructions = [this.options.instructions ?? DEFAULT_AGENT_INSTRUCTIONS, options?.instructions].filter((part) => Boolean(part && part.length > 0)).join("\n\n");
+    const instructions = [
+      options?.ownInstructions ? void 0 : this.options.instructions ?? DEFAULT_AGENT_INSTRUCTIONS,
+      options?.instructions
+    ].filter((part) => Boolean(part && part.length > 0)).join("\n\n");
     const listeners = /* @__PURE__ */ new Set();
     const record = {
       id: sessionId,
@@ -851,47 +946,70 @@ var AgentServer = class {
       gate,
       server,
       transport: void 0,
-      listeners
+      listeners,
+      memory: options?.memory === true,
+      relationships: /* @__PURE__ */ new Map()
     };
     const onTurnResult = (result) => {
       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 } : {},
+            ...options.memory ? { memory: true } : {},
+            ...options.maxActions ? { maxActions: options.maxActions } : {},
+            ...options.subgoals === false ? { subgoals: false } : {}
+          });
+          const ack = await started;
+          if (ack.type === "session_started") {
+            for (const relationship of ack.relationships ?? []) {
+              record.relationships.set(relationship.about.toLowerCase(), relationship);
+            }
+          }
+        } 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,
@@ -900,7 +1018,15 @@ var AgentServer = class {
       on: (listener) => {
         listeners.add(listener);
         return () => listeners.delete(listener);
-      }
+      },
+      observe: (text, about) => {
+        if (!record.memory || !text || !this.connection || !this.sessions.has(sessionId)) return;
+        try {
+          this.connection.send({ type: "observe", sessionId, text, ...about ? { about } : {} });
+        } catch {
+        }
+      },
+      relationships: () => Object.fromEntries(record.relationships)
     };
   }
   /** Subscribe to every session plus connection events. Returns unsubscribe. */
@@ -933,7 +1059,8 @@ var AgentServer = class {
       args: outcome.args ?? {},
       result: outcome.result,
       attempts: outcome.attempts ?? 1,
-      usage: outcome.usage ?? { promptTokens: 0, completionTokens: 0 }
+      usage: outcome.usage ?? { promptTokens: 0, completionTokens: 0 },
+      ...outcome.steps ? { steps: outcome.steps } : {}
     };
   }
   emit(event) {
@@ -980,6 +1107,33 @@ var AgentServer = class {
           });
           return;
         }
+        if (envelope.event === "relationship" || envelope.event === "memory") {
+          if (envelope.error) return;
+          const args = envelope.args ?? {};
+          const about = typeof args.about === "string" ? args.about : "";
+          if (envelope.event === "memory") {
+            this.emit({ type: "memory", sessionId: envelope.sessionId, about, note: String(args.note ?? "") });
+            return;
+          }
+          const relationship = {
+            about,
+            affinity: Number(args.affinity ?? 0),
+            label: String(args.label ?? "stranger"),
+            note: String(args.because ?? "")
+          };
+          this.sessions.get(envelope.sessionId)?.relationships.set(about.toLowerCase(), relationship);
+          this.emit({
+            type: "relationship",
+            sessionId: envelope.sessionId,
+            about,
+            affinity: relationship.affinity,
+            label: relationship.label,
+            change: Number(args.change ?? 0),
+            because: relationship.note ?? ""
+          });
+          return;
+        }
+        if (envelope.event !== "turnFailed") return;
         this.emit({
           type: "turnFailed",
           sessionId: envelope.sessionId,
@@ -991,6 +1145,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":
@@ -1004,6 +1161,7 @@ var AgentServer = class {
       case "ping":
       case "pong":
       case "resume_session":
+      case "observe":
         return;
       default: {
         assertNever(envelope);
@@ -1060,13 +1218,692 @@ var AgentServer = class {
     await this.close();
   }
 };
+
+// src/world.ts
+var import_zod2 = require("zod");
+var DEFAULT_EMOTES = ["wave", "laugh", "cheer", "dance", "point", "shrug"];
+function distance(a, b) {
+  return Math.hypot(a.x - b.x, a.y - b.y, (a.z ?? 0) - (b.z ?? 0));
+}
+function clip(text, limit) {
+  return text.length <= limit ? text : `${text.slice(0, limit - 3)}...`;
+}
+var now = () => performance.now() / 1e3;
+var sleep = (seconds) => new Promise((resolve2) => setTimeout(resolve2, seconds * 1e3));
+var CharacterTools = class {
+  constructor(character) {
+    this.character = character;
+  }
+  character;
+  static agent = {
+    actions: {
+      say: {
+        description: "Say one or two short sentences out loud. Set to when you are talking to one person.",
+        args: {
+          text: import_zod2.z.string().describe("What you say, in your own voice."),
+          to: import_zod2.z.string().describe("Name of the person you are talking to. Empty to talk to everyone near you.")
+        }
+      },
+      go_to: {
+        description: "Walk to a place. You are told when you arrive.",
+        args: { place: import_zod2.z.string().describe("One of the places you know.") }
+      },
+      approach: {
+        description: "Walk up to someone you can see, to talk or do something together.",
+        args: { person: import_zod2.z.string() }
+      },
+      use: {
+        description: "Do an activity with a thing listed in things_here. You walk to it first. You are told when you finish.",
+        args: { thing: import_zod2.z.string(), activity: import_zod2.z.string() }
+      },
+      give: {
+        description: "Give something you are carrying to someone next to you.",
+        args: { item: import_zod2.z.string(), to: import_zod2.z.string() }
+      },
+      emote: {
+        description: "Show a feeling with your body.",
+        args: { emote: import_zod2.z.string().describe("wave, laugh, cheer, dance, point or shrug.") }
+      },
+      idle: { description: "Do nothing new for now and carry on as you are." }
+    }
+  };
+  see() {
+    return this.character.view();
+  }
+  say(text, to) {
+    return this.character.doSay(text, to);
+  }
+  go_to(place) {
+    return this.character.doGoTo(place);
+  }
+  approach(person) {
+    return this.character.doApproach(person);
+  }
+  use(thing, activity) {
+    return this.character.doUse(thing, activity);
+  }
+  give(item, to) {
+    return this.character.doGive(item, to);
+  }
+  emote(emote) {
+    return this.character.doEmote(emote);
+  }
+  idle() {
+    return { ok: true };
+  }
+};
+var Character = class {
+  constructor(world, name, body, home, carrying) {
+    this.world = world;
+    this.name = name;
+    this.body = body;
+    this.home = home;
+    this.carrying = [...carrying];
+  }
+  world;
+  name;
+  body;
+  home;
+  kind = "resident";
+  status = null;
+  carrying;
+  needs = {};
+  turns = 0;
+  tokens = 0;
+  agent;
+  /** @internal */
+  inbox = [];
+  /** @internal */
+  wake = now() + 2 + Math.random() * 6;
+  /** @internal */
+  busy = false;
+  /** @internal */
+  greeted = /* @__PURE__ */ new Map();
+  /** @internal */
+  needWarned = /* @__PURE__ */ new Set();
+  task = 0;
+  using = null;
+  chat = { count: 0, resetAt: 0 };
+  position() {
+    return this.body.getPosition();
+  }
+  place() {
+    return this.world.placeAt(this.position());
+  }
+  setStatus(status) {
+    this.status = status;
+    this.body.setStatus?.(status);
+    this.world.emit({ type: "status", character: this.name, status });
+  }
+  /**
+   * Tell this character something happened. It goes into its memory and its
+   * next view. turn asks for a turn; urgent asks for one now.
+   */
+  notice(text, options = {}) {
+    this.inbox.push(text);
+    while (this.inbox.length > 12) this.inbox.shift();
+    this.agent?.observe(text, options.about);
+    if (options.urgent) {
+      this.wakeIn(0.2);
+    } else if (options.turn) {
+      const world = this.world;
+      const far = world.farDelay > 0 && !world.humanNear(this.position(), world.activeRadius);
+      this.wakeIn(far ? world.farDelay : 2.5);
+    }
+  }
+  /** @internal */
+  wakeIn(seconds) {
+    const at = now() + seconds;
+    if (this.wake === null || at < this.wake) this.wake = at;
+  }
+  /** How this character feels about someone, from the platform. */
+  feelingFor(name) {
+    const relationship = this.agent?.relationships()[name.toLowerCase()];
+    return relationship ? { affinity: relationship.affinity, label: relationship.label, ...relationship.note ? { note: relationship.note } : {} } : { affinity: 0, label: "stranger" };
+  }
+  /** @internal Returns true when another character's line should get a reply. */
+  mayReplyToCharacter() {
+    if (now() > this.chat.resetAt) {
+      this.chat.count = 0;
+      this.chat.resetAt = now() + this.world.chatPause;
+    }
+    this.chat.count += 1;
+    return this.chat.count <= this.world.chatReplies;
+  }
+  /** @internal */
+  view() {
+    const world = this.world;
+    const here = this.position();
+    const place = world.placeAt(here);
+    const why = this.inbox.length > 0 ? this.inbox : ["Nothing new has happened. Carry on with your day."];
+    this.inbox = [];
+    const nearby = [];
+    const add = (name, who, at, doing) => {
+      if (!at) return;
+      const d = distance(at, here);
+      if (d > world.sight) return;
+      nearby.push({
+        name,
+        who,
+        steps_away: Math.round(d),
+        can_hear_you: d <= world.hearing,
+        ...doing ? { doing } : {},
+        you_feel: this.feelingFor(name).label
+      });
+    };
+    for (const other of world.characters.values()) {
+      if (other !== this) add(other.name, "resident", other.position(), other.status);
+    }
+    for (const person of world.people.values()) add(person.name, "player", person.getPosition(), null);
+    nearby.sort((a, b) => a.steps_away - b.steps_away);
+    const things = [];
+    for (const thing of world.things.values()) {
+      if (things.length >= 12) break;
+      if (!(place && thing.place === place || distance(thing.position, here) <= 30)) continue;
+      const activities = Object.entries(thing.activities).map(([name, activity]) => `${name}: ${activity.description}${activity.needs ? ` (needs ${activity.needs})` : ""}`).sort();
+      things.push({
+        thing: thing.id,
+        activities,
+        ...thing.usedBy && thing.usedBy !== this.name ? { in_use_by: thing.usedBy } : {}
+      });
+    }
+    const needs = Object.fromEntries(Object.entries(this.needs).map(([need, value]) => [need, Math.floor(value)]));
+    return {
+      ...world.clock ? { time: world.clock() } : {},
+      why_you_are_acting_now: why,
+      you: {
+        at: place ?? "outdoors, between places",
+        doing: this.status ?? "nothing in particular",
+        ...Object.keys(needs).length > 0 ? { needs } : {},
+        ...this.carrying.length > 0 ? { carrying: this.carrying } : {}
+      },
+      people_nearby: nearby.slice(0, 8),
+      things_here: things
+    };
+  }
+  // Stop whatever the body is doing so a new movement can start.
+  interrupt() {
+    this.task += 1;
+    if (this.using) {
+      this.using.usedBy = null;
+      this.using = null;
+    }
+    this.body.stop();
+    return this.task;
+  }
+  async walk(token, goal, status) {
+    this.setStatus(status);
+    const reached = await this.body.moveTo(goal);
+    if (this.task !== token) return false;
+    this.setStatus(null);
+    return reached;
+  }
+  /** @internal */
+  doSay(rawText, to) {
+    let text = clip(String(rawText ?? "").trim(), 240);
+    if (!text) throw new Error("say needs some text");
+    const world = this.world;
+    const target = world.resolve(to);
+    const towards = target ? world.positionOf(target) : null;
+    const shown = this.body.say(text, towards ?? void 0);
+    if (typeof shown === "string" && shown) text = shown;
+    const heard = world.speech(this.name, text, target);
+    return heard === 0 ? { said: text, note: "Nobody was close enough to hear you." } : { said: text };
+  }
+  /** @internal */
+  doGoTo(placeName) {
+    const place = this.world.places.get(placeName);
+    if (!place) throw new Error(`no such place: ${placeName}. Places: ${[...this.world.places.keys()].join(", ")}`);
+    if (this.place() === placeName && !this.status) throw new Error(`you are already at ${placeName}`);
+    const token = this.interrupt();
+    void this.walk(token, place.position, `walking to ${placeName}`).then((reached) => {
+      if (reached) this.notice(`You arrived at ${placeName}.`, { turn: true });
+      else if (this.task === token) this.notice(`You could not get to ${placeName}.`, { turn: true });
+    });
+    return { walking_to: placeName };
+  }
+  /** @internal */
+  doApproach(person) {
+    const world = this.world;
+    const name = world.resolve(person);
+    const at = name ? world.positionOf(name) : null;
+    if (!name || !at || name === this.name) throw new Error(`you cannot see anyone called ${person}`);
+    const gap = distance(at, this.position());
+    if (gap > world.sight) throw new Error(`${name} is too far away to see`);
+    if (gap <= 7) return { note: `You are already next to ${name}.` };
+    const token = this.interrupt();
+    const here = this.position();
+    const goal = { x: at.x + (here.x - at.x) / gap * 4, y: at.y + (here.y - at.y) / gap * 4 };
+    void this.walk(token, goal, `walking over to ${name}`).then((reached) => {
+      if (reached) this.notice(`You walked up to ${name}.`, { turn: true });
+    });
+    return { walking_to: name };
+  }
+  /** @internal */
+  doUse(thingId, activityName) {
+    const thing = this.world.things.get(thingId);
+    if (!thing) throw new Error(`there is no thing called ${thingId}`);
+    const activity = thing.activities[activityName];
+    if (!activity) {
+      throw new Error(`${thingId} has no activity ${activityName}. It has: ${Object.keys(thing.activities).sort().join(", ")}`);
+    }
+    if (thing.usedBy && thing.usedBy !== this.name) throw new Error(`${thing.usedBy} is using ${thingId} right now`);
+    if (activity.needs && !this.carrying.includes(activity.needs)) throw new Error(`you need ${activity.needs} to do that`);
+    const token = this.interrupt();
+    const seconds = activity.seconds ?? 5;
+    thing.usedBy = this.name;
+    this.using = thing;
+    void (async () => {
+      if (distance(thing.position, this.position()) > 6 && !await this.walk(token, thing.position, `walking to ${thing.name}`)) {
+        if (this.task === token) {
+          thing.usedBy = null;
+          this.using = null;
+          this.notice(`You could not reach ${thingId}.`, { turn: true });
+        }
+        return;
+      }
+      this.body.face?.(thing.position);
+      this.setStatus(activity.status ?? activityName.replaceAll("_", " "));
+      if (activity.emote) this.body.emote?.(activity.emote);
+      await sleep(seconds);
+      if (this.task !== token) return;
+      thing.usedBy = null;
+      this.using = null;
+      this.setStatus(null);
+      const outcome = [];
+      if (activity.needs) {
+        const index = this.carrying.indexOf(activity.needs);
+        if (index >= 0) this.carrying.splice(index, 1);
+      }
+      for (const [need, change] of Object.entries(activity.effects ?? {})) {
+        const current = this.needs[need];
+        if (current === void 0) continue;
+        this.needs[need] = Math.min(100, Math.max(0, current + change));
+        outcome.push(`${need} is now ${Math.floor(this.needs[need])}`);
+      }
+      if (activity.gives) {
+        this.carrying.push(activity.gives);
+        outcome.push(`you now carry ${activity.gives}`);
+      }
+      const summary = outcome.length > 0 ? ` (${outcome.join(", ")})` : "";
+      this.notice(`You finished: ${activityName.replaceAll("_", " ")} at ${thing.name}${summary}.`, { turn: true });
+    })();
+    return { started: activityName, takes_seconds: seconds };
+  }
+  /** @internal */
+  doGive(item, to) {
+    const world = this.world;
+    const index = this.carrying.indexOf(item);
+    if (index < 0) throw new Error(`you are not carrying ${item}`);
+    const name = world.resolve(to);
+    const at = name ? world.positionOf(name) : null;
+    if (!name || !at) throw new Error(`you cannot see anyone called ${to}`);
+    if (distance(at, this.position()) > 12) throw new Error(`${name} is too far away. Use approach first.`);
+    this.carrying.splice(index, 1);
+    const other = world.characters.get(name);
+    if (other) {
+      other.carrying.push(item);
+      other.notice(`${this.name} gave you ${item}.`, { about: this.name, urgent: true });
+    } else {
+      world.people.get(name)?.carrying.push(item);
+    }
+    world.emit({ type: "give", from: this.name, to: name, item });
+    return { gave: item, to: name };
+  }
+  /** @internal */
+  doEmote(name) {
+    const emotes = this.body.emotes ?? DEFAULT_EMOTES;
+    if (!emotes.includes(name)) throw new Error(`no such emote. Choose one of: ${emotes.join(", ")}`);
+    this.body.emote?.(name);
+    this.world.emit({ type: "emote", character: this.name, emote: name });
+    return { did: name };
+  }
+};
+var World = class {
+  constructor(server, options) {
+    this.server = server;
+    this.name = options.name;
+    this.about = options.about ?? "";
+    this.rules = options.rules ?? "";
+    this.clock = options.clock;
+    this.hearing = options.hearing ?? 35;
+    this.sight = options.sight ?? 80;
+    this.idleSeconds = options.idleSeconds ?? 45;
+    this.farSlowdown = options.farSlowdown ?? 3;
+    this.activeRadius = options.activeRadius ?? 120;
+    this.farDelay = options.farDelay ?? 20;
+    this.greetDistance = options.greetDistance ?? 12;
+    this.turnsPerMinute = options.turnsPerMinute ?? 30;
+    this.maxActions = options.maxActions ?? 3;
+    this.chatReplies = options.chatReplies ?? 2;
+    this.chatPause = options.chatPause ?? 90;
+    this.needDefs = options.needs ?? {};
+    this.memory = options.memory !== false;
+    this.warn = options.warn ?? (() => void 0);
+  }
+  server;
+  name;
+  about;
+  rules;
+  clock;
+  hearing;
+  sight;
+  idleSeconds;
+  farSlowdown;
+  activeRadius;
+  farDelay;
+  greetDistance;
+  turnsPerMinute;
+  maxActions;
+  chatReplies;
+  chatPause;
+  places = /* @__PURE__ */ new Map();
+  things = /* @__PURE__ */ new Map();
+  characters = /* @__PURE__ */ new Map();
+  people = /* @__PURE__ */ new Map();
+  turnsUsed = 0;
+  needDefs;
+  memory;
+  warn;
+  listeners = /* @__PURE__ */ new Set();
+  timer = null;
+  budget = 0;
+  budgetAt = now();
+  lastTick = now();
+  /** Listen for world events. Returns a function that unsubscribes. */
+  on(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /** @internal */
+  emit(event) {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(event);
+      } catch (error) {
+        this.warn(`world listener failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+  addPlace(name, place) {
+    if (this.places.has(name)) throw new Error(`place already exists: ${name}`);
+    this.places.set(name, { name, description: place.description ?? "", position: place.position, radius: place.radius ?? 22 });
+  }
+  addThing(id, thing) {
+    if (this.things.has(id)) throw new Error(`thing already exists: ${id}`);
+    this.things.set(id, {
+      id,
+      name: thing.name ?? id.replaceAll("_", " "),
+      ...thing.place ? { place: thing.place } : {},
+      position: thing.position,
+      activities: thing.activities,
+      usedBy: null
+    });
+  }
+  /** Add a human player. getPosition returns null while they have no body. */
+  addPerson(person) {
+    this.people.set(person.name, { name: person.name, getPosition: person.getPosition, carrying: [] });
+  }
+  removePerson(name) {
+    this.people.delete(name);
+  }
+  placeAt(position) {
+    let best = null;
+    let bestDistance = Infinity;
+    for (const place of this.places.values()) {
+      const d = distance(place.position, position);
+      if (d <= place.radius && d < bestDistance) {
+        best = place.name;
+        bestDistance = d;
+      }
+    }
+    return best;
+  }
+  positionOf(name) {
+    return this.characters.get(name)?.position() ?? this.people.get(name)?.getPosition() ?? null;
+  }
+  /** Match a name the model wrote to someone in the world, ignoring case. */
+  resolve(name) {
+    if (!name) return void 0;
+    const lower = name.trim().toLowerCase();
+    for (const known of [...this.characters.keys(), ...this.people.keys()]) {
+      if (known.toLowerCase() === lower) return known;
+    }
+    return void 0;
+  }
+  /** @internal */
+  humanNear(position, range) {
+    for (const person of this.people.values()) {
+      const at = person.getPosition();
+      if (at && distance(at, position) <= range) return true;
+    }
+    return false;
+  }
+  /** The instructions every character gets about this world. */
+  guide(home) {
+    const lines = [
+      `You are a character who lives in ${this.name}. ${this.about}`,
+      "You are not an assistant. You are a person with your own life, moods, and plans. Stay in character at all times.",
+      "",
+      "How you act:",
+      "- You act only through tools. To speak, call say. Keep a line to one or two short sentences, the way people talk.",
+      "- Each turn shows why you are acting now, who is near you, and what you can use where you are.",
+      "- You can speak and then act in the same turn, for example say and then go_to. When you agree to do something, do it in that same turn: say yes, then go_to or use.",
+      "- go_to, approach and use take time. You are told when they finish. Do not repeat them while they are under way.",
+      "- use walks you to the thing by itself. To give something to someone who is not next to you, call approach and stop there; give it on your next turn, once you have arrived.",
+      "- When someone speaks to you, answer them. When nothing needs doing, carry on with your day the way your story says, or call idle.",
+      "- A chat between neighbours is a few lines, then you both get on with your day. Do not answer a goodbye or a line that needs no answer.",
+      "- If someone does not answer you, leave them be and get on with your day. Do not keep talking to a person who stays silent.",
+      "- Do not repeat yourself. Check your recent events before you speak.",
+      "- People you do not know are strangers. Treat people the way you feel about them.",
+      "",
+      "Places:"
+    ];
+    for (const place of this.places.values()) {
+      lines.push(`- ${place.name}${place.description ? `: ${place.description}` : ""}${home === place.name ? " (your home)" : ""}`);
+    }
+    if (Object.keys(this.needDefs).length > 0) {
+      lines.push("", "Your needs run from 0 (desperate) to 100 (satisfied) and fall over time. Look after them with the things around you.");
+    }
+    if (this.rules) lines.push("", this.rules);
+    return lines.join("\n");
+  }
+  /** Add a character and start its session. id is the character ID from the web app. */
+  async addCharacter(def) {
+    if (this.characters.has(def.name)) throw new Error(`character already exists: ${def.name}`);
+    const character = new Character(this, def.name, def.body, def.home, def.carrying ?? []);
+    for (const [need, spec] of Object.entries(this.needDefs)) {
+      character.needs[need] = spec.start ?? 55 + Math.floor(Math.random() * 36);
+    }
+    const instructions = [this.guide(def.home), def.instructions].filter(Boolean).join("\n\n");
+    character.agent = await this.server.start(new CharacterTools(character), {
+      name: def.name,
+      playerId: def.id,
+      instructions,
+      ownInstructions: true,
+      memory: this.memory,
+      maxActions: this.maxActions,
+      subgoals: false,
+      ...def.goal ? { goal: def.goal } : {}
+    });
+    this.characters.set(def.name, character);
+    character.agent.on((event) => {
+      if (event.type === "relationship") {
+        this.emit({
+          type: "relationship",
+          character: character.name,
+          about: this.resolve(event.about) ?? event.about,
+          affinity: event.affinity,
+          label: event.label,
+          change: event.change,
+          because: event.because
+        });
+      } else if (event.type === "memory") {
+        this.emit({ type: "memory", character: character.name, about: event.about, note: event.note });
+      } else if (event.type === "action") {
+        this.emit({ type: "action", character: character.name, action: event.action, args: event.args });
+      }
+    });
+    return character;
+  }
+  /** @internal Carry a spoken line to everyone who can hear it. Returns how many heard it. */
+  speech(speaker, text, to) {
+    const from = this.positionOf(speaker);
+    if (!from) return 0;
+    const speakerIsCharacter = this.characters.has(speaker);
+    let heard = 0;
+    for (const person of this.people.values()) {
+      const at = person.getPosition();
+      if (person.name !== speaker && at && distance(at, from) <= this.hearing) heard += 1;
+    }
+    let closest;
+    if (!to) {
+      let closestDistance = 16;
+      for (const other of this.characters.values()) {
+        const d = distance(other.position(), from);
+        if (other.name !== speaker && d < closestDistance) {
+          closest = other.name;
+          closestDistance = d;
+        }
+      }
+    }
+    for (const other of this.characters.values()) {
+      if (other.name === speaker || distance(other.position(), from) > this.hearing) continue;
+      heard += 1;
+      const addressed = to === other.name || !to && closest === other.name;
+      const line = addressed ? `${speaker} said to you: "${text}"` : to ? `${speaker} said to ${to}: "${text}"` : `${speaker} said: "${text}"`;
+      const turn = addressed && (!speakerIsCharacter || other.mayReplyToCharacter());
+      if (addressed && !other.status) other.body.face?.(from);
+      other.notice(line, { about: speaker, urgent: turn && !speakerIsCharacter, turn });
+    }
+    this.emit({ type: "speech", speaker, text, ...to ? { to } : {} });
+    return heard;
+  }
+  /** A human player said something. Without to, the closest resident in talking range takes it. */
+  say(speaker, text, to) {
+    const line = clip(text.trim(), 300);
+    if (!line || !this.people.has(speaker)) return 0;
+    return this.speech(speaker, line, this.resolve(to));
+  }
+  /** Tell one character something happened, in plain words. */
+  tell(characterName, text, options = { turn: true }) {
+    this.characters.get(characterName)?.notice(text, options);
+  }
+  /** Tell every character within range of a position that something happened. */
+  announce(text, position, range) {
+    for (const character of this.characters.values()) {
+      if (!position || distance(character.position(), position) <= (range ?? this.sight)) {
+        character.notice(text, { turn: true });
+      }
+    }
+  }
+  /** A human player hands an item to a character. */
+  give(from, characterName, item) {
+    const character = this.characters.get(characterName);
+    if (!character) return false;
+    character.carrying.push(item);
+    character.notice(`${from} gave you ${item}.`, { about: from, urgent: true });
+    this.emit({ type: "give", from, to: characterName, item });
+    return true;
+  }
+  spend() {
+    const at = now();
+    this.budget = Math.min(this.turnsPerMinute, this.budget + (at - this.budgetAt) * this.turnsPerMinute / 60);
+    this.budgetAt = at;
+    if (this.budget < 1) return false;
+    this.budget -= 1;
+    return true;
+  }
+  idleDelay(character) {
+    const delay = this.idleSeconds * (0.75 + Math.random() * 0.5);
+    return this.humanNear(character.position(), this.activeRadius) ? delay : delay * this.farSlowdown;
+  }
+  runTurn(character) {
+    character.wake = null;
+    character.busy = true;
+    this.emit({ type: "thinking", character: character.name, on: true });
+    character.agent.turn().then((result) => {
+      character.tokens += result.usage.promptTokens + result.usage.completionTokens;
+      this.emit({ type: "turn", character: character.name, ok: true, result });
+      character.wakeIn(character.inbox.length > 0 ? 1 : this.idleDelay(character));
+    }).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      this.warn(`${character.name} turn failed: ${message}`);
+      this.emit({ type: "turn", character: character.name, ok: false, error: message });
+      character.wakeIn(Math.max(20, this.idleSeconds));
+    }).finally(() => {
+      character.busy = false;
+      character.turns += 1;
+      this.turnsUsed += 1;
+      this.emit({ type: "thinking", character: character.name, on: false });
+    });
+  }
+  tick() {
+    const at = now();
+    const dt = at - this.lastTick;
+    this.lastTick = at;
+    for (const character of this.characters.values()) {
+      for (const [need, spec] of Object.entries(this.needDefs)) {
+        const value = Math.max(0, (character.needs[need] ?? 0) - spec.perMinute * dt / 60);
+        character.needs[need] = value;
+        if (value < 25 && !character.needWarned.has(need)) {
+          character.needWarned.add(need);
+          character.notice(`Your ${need} is getting low (${Math.floor(value)}).`, { turn: true });
+        } else if (value > 50) {
+          character.needWarned.delete(need);
+        }
+      }
+      if (this.greetDistance > 0) {
+        const here = character.position();
+        for (const person of this.people.values()) {
+          const where = person.getPosition();
+          if (!where || distance(where, here) > this.greetDistance) continue;
+          const last = character.greeted.get(person.name);
+          character.greeted.set(person.name, at);
+          if (last === void 0 || at - last > 150) {
+            character.notice(`${person.name} walked up to you.`, { about: person.name, turn: true });
+          }
+        }
+      }
+      if (character.wake !== null && at >= character.wake && !character.busy) {
+        if (character.status && character.inbox.length === 0) {
+          character.wake = at + 5;
+        } else if (this.spend()) {
+          this.runTurn(character);
+        }
+      }
+    }
+  }
+  /** Start giving characters turns. Call it once, after adding the characters. */
+  start() {
+    if (this.timer) return;
+    this.budget = Math.min(this.turnsPerMinute, 6);
+    this.budgetAt = now();
+    this.lastTick = now();
+    this.timer = setInterval(() => {
+      try {
+        this.tick();
+      } catch (error) {
+        this.warn(`world tick failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }, 500);
+  }
+  /** Stop giving turns. Sessions stay open until the server closes. */
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentServer,
+  Character,
   ConnectionLostError,
   PlatformAuthError,
   ProtocolVersionError,
   TurnFailedError,
-  TurnTimeoutError
+  TurnTimeoutError,
+  World,
+  bindDynamic
 });
 //# sourceMappingURL=index.cjs.map