@whitesands/agent-player 1.2.0 → 1.3.0

package/dist/index.js

@@ -117,7 +117,7 @@ import WebSocket from "ws";
 
 // src/protocol.ts
 var PROTOCOL_VERSION = 1;
-var SDK_VERSION = "1.2.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.",
@@ -355,6 +355,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;
@@ -394,6 +403,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,
@@ -869,7 +880,7 @@ var AgentServer = class {
     const sessionToken = randomUUID2();
     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 ? {
@@ -879,7 +890,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,
@@ -888,7 +902,9 @@ var AgentServer = class {
       gate,
       server,
       transport: void 0,
-      listeners
+      listeners,
+      memory: options?.memory === true,
+      relationships: /* @__PURE__ */ new Map()
     };
     const onTurnResult = (result) => {
       gate.completeTurn(result);
@@ -929,9 +945,17 @@ var AgentServer = class {
             name,
             tools: reflected.tools,
             instructions,
-            ...options.goal ? { goal: options.goal } : {}
+            ...options.goal ? { goal: options.goal } : {},
+            ...options.memory ? { memory: true } : {},
+            ...options.maxActions ? { maxActions: options.maxActions } : {},
+            ...options.subgoals === false ? { subgoals: false } : {}
           });
-          await started;
+          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);
@@ -950,7 +974,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. */
@@ -983,7 +1015,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) {
@@ -1030,6 +1063,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,
@@ -1057,6 +1117,7 @@ var AgentServer = class {
       case "ping":
       case "pong":
       case "resume_session":
+      case "observe":
         return;
       default: {
         assertNever(envelope);
@@ -1113,13 +1174,691 @@ var AgentServer = class {
     await this.close();
   }
 };
+
+// src/world.ts
+import { z as z2 } from "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: z2.string().describe("What you say, in your own voice."),
+          to: z2.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: z2.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: z2.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: z2.string(), activity: z2.string() }
+      },
+      give: {
+        description: "Give something you are carrying to someone next to you.",
+        args: { item: z2.string(), to: z2.string() }
+      },
+      emote: {
+        description: "Show a feeling with your body.",
+        args: { emote: z2.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;
+  }
+};
 export {
   AgentServer,
+  Character,
   ConnectionLostError,
   PlatformAuthError,
   ProtocolVersionError,
   TurnFailedError,
   TurnTimeoutError,
+  World,
   bindDynamic
 };
 //# sourceMappingURL=index.js.map