@whitesands/agent-player 1.2.0 → 1.3.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { A as AgentServerOptions, S as StartOptions, a as AgentHandle, E as EventListener } from './types-Zi-2YmF2.cjs';
-export { b as AgentEvent, L as Logger, T as TurnOptions, c as TurnResult } from './types-Zi-2YmF2.cjs';
+import { A as AgentServerOptions, S as StartOptions, a as AgentHandle, E as EventListener, T as TurnResult } from './types-gmAkYoQr.cjs';
+export { b as AgentEvent, L as Logger, c as TurnOptions } from './types-gmAkYoQr.cjs';
 import { AttemptRecord } from './protocol.cjs';
-export { TokenUsage } from './protocol.cjs';
+export { Relationship, StepRecord, TokenUsage } from './protocol.cjs';
 import { ZodRawShape } from 'zod';
 import '@modelcontextprotocol/sdk/shared/transport.js';
 
@@ -77,4 +77,312 @@ type DynamicCallback = (args: Record<string, unknown>) => unknown | Promise<unkn
  */
 declare function bindDynamic(player: object, name: string, description: string, args: ZodRawShape | undefined, callback?: DynamicCallback): void;
 
-export { type ActionSpec, AgentHandle, type AgentMetadata, AgentServer, AgentServerOptions, AttemptRecord, ConnectionLostError, EventListener, PlatformAuthError, ProtocolVersionError, StartOptions, TurnFailedError, TurnTimeoutError, bindDynamic };
+type Position = {
+    x: number;
+    y: number;
+    z?: number;
+};
+type Body = {
+    getPosition(): Position;
+    /** Walk to a position. Resolves true on arrival, false if interrupted or unreachable. */
+    moveTo(goal: Position): Promise<boolean>;
+    stop(): void;
+    /** Show a spoken line. May return the text as shown, when the game filters it. */
+    say(text: string, towards?: Position): string | void;
+    emote?(name: string): void;
+    face?(position: Position): void;
+    setStatus?(status: string | null): void;
+    emotes?: string[];
+};
+type Activity = {
+    description: string;
+    /** How long it takes. Default 5. */
+    seconds?: number;
+    /** Shown while it runs, such as "making coffee". Defaults to the activity name. */
+    status?: string;
+    /** Change to the character's needs when it finishes, such as { food: 40 }. */
+    effects?: Record<string, number>;
+    /** An item the character carries afterwards. */
+    gives?: string;
+    /** An item the character must carry. It is used up. */
+    needs?: string;
+    /** Emote played while it runs. */
+    emote?: string;
+};
+type WorldOptions = {
+    name: string;
+    /** One or two sentences about the world, for every character. */
+    about?: string;
+    /** Extra rules of the game, in plain words. */
+    rules?: string;
+    /** The time of day as text, such as "Tuesday 14:30, afternoon". */
+    clock?: () => string;
+    /** How far speech carries, and how far a character sees. Defaults 35 and 80. */
+    hearing?: number;
+    sight?: number;
+    /** A character with nothing to react to gets a turn about this often, in seconds. Default 45. */
+    idleSeconds?: number;
+    /** Idle turns are this many times rarer when no human is within activeRadius. Defaults 3 and 120. */
+    farSlowdown?: number;
+    activeRadius?: number;
+    /** A character no human can see waits this long before a turn for something it did itself. Default 20. */
+    farDelay?: number;
+    /** A human who comes this close is noticed. Default 12. 0 turns it off. */
+    greetDistance?: number;
+    /** Cap on turns per minute for the whole world. Default 30. */
+    turnsPerMinute?: number;
+    /** Actions per turn, 1 to 4. Default 3. */
+    maxActions?: number;
+    /** Needs every character has. 100 is satisfied, 0 is desperate. perMinute is how fast it falls. */
+    needs?: Record<string, {
+        perMinute: number;
+        start?: number;
+    }>;
+    /** Each character replies at most chatReplies times per chatPause seconds to another character. Defaults 2 and 90. */
+    chatReplies?: number;
+    chatPause?: number;
+    /** Keep memory and relationships on the platform. Default true. */
+    memory?: boolean;
+    /** Receives warnings. */
+    warn?: (message: string) => void;
+};
+type WorldEvent = {
+    type: "speech";
+    speaker: string;
+    text: string;
+    to?: string;
+} | {
+    type: "status";
+    character: string;
+    status: string | null;
+} | {
+    type: "relationship";
+    character: string;
+    about: string;
+    affinity: number;
+    label: string;
+    change: number;
+    because: string;
+} | {
+    type: "memory";
+    character: string;
+    about: string;
+    note: string;
+} | {
+    type: "action";
+    character: string;
+    action: string;
+    args: Record<string, unknown>;
+} | {
+    type: "thinking";
+    character: string;
+    on: boolean;
+} | {
+    type: "give";
+    from: string;
+    to: string;
+    item: string;
+} | {
+    type: "emote";
+    character: string;
+    emote: string;
+} | {
+    type: "turn";
+    character: string;
+    ok: boolean;
+    result?: TurnResult;
+    error?: string;
+};
+type Place = {
+    name: string;
+    description: string;
+    position: Position;
+    radius: number;
+};
+type Thing = {
+    id: string;
+    name: string;
+    place?: string;
+    position: Position;
+    activities: Record<string, Activity>;
+    usedBy: string | null;
+};
+type Person = {
+    name: string;
+    getPosition: () => Position | null;
+    carrying: string[];
+};
+type NoticeOptions = {
+    about?: string;
+    turn?: boolean;
+    urgent?: boolean;
+};
+declare class Character {
+    readonly world: World;
+    readonly name: string;
+    readonly body: Body;
+    readonly home: string | undefined;
+    readonly kind = "resident";
+    status: string | null;
+    carrying: string[];
+    needs: Record<string, number>;
+    turns: number;
+    tokens: number;
+    agent: AgentHandle;
+    /** @internal */ inbox: string[];
+    /** @internal */ wake: number | null;
+    /** @internal */ busy: boolean;
+    /** @internal */ greeted: Map<string, number>;
+    /** @internal */ needWarned: Set<string>;
+    private task;
+    private using;
+    private chat;
+    constructor(world: World, name: string, body: Body, home: string | undefined, carrying: string[]);
+    position(): Position;
+    place(): string | null;
+    setStatus(status: string | null): void;
+    /**
+     * 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: string, options?: NoticeOptions): void;
+    /** @internal */
+    wakeIn(seconds: number): void;
+    /** How this character feels about someone, from the platform. */
+    feelingFor(name: string): {
+        affinity: number;
+        label: string;
+        note?: string;
+    };
+    /** @internal Returns true when another character's line should get a reply. */
+    mayReplyToCharacter(): boolean;
+    /** @internal */
+    view(): Record<string, unknown>;
+    private interrupt;
+    private walk;
+    /** @internal */
+    doSay(rawText: string, to: string): {
+        said: string;
+        note: string;
+    } | {
+        said: string;
+        note?: undefined;
+    };
+    /** @internal */
+    doGoTo(placeName: string): {
+        walking_to: string;
+    };
+    /** @internal */
+    doApproach(person: string): {
+        note: string;
+        walking_to?: undefined;
+    } | {
+        walking_to: string;
+        note?: undefined;
+    };
+    /** @internal */
+    doUse(thingId: string, activityName: string): {
+        started: string;
+        takes_seconds: number;
+    };
+    /** @internal */
+    doGive(item: string, to: string): {
+        gave: string;
+        to: string;
+    };
+    /** @internal */
+    doEmote(name: string): {
+        did: string;
+    };
+}
+declare class World {
+    private readonly server;
+    readonly name: string;
+    readonly about: string;
+    readonly rules: string;
+    readonly clock: (() => string) | undefined;
+    readonly hearing: number;
+    readonly sight: number;
+    readonly idleSeconds: number;
+    readonly farSlowdown: number;
+    readonly activeRadius: number;
+    readonly farDelay: number;
+    readonly greetDistance: number;
+    readonly turnsPerMinute: number;
+    readonly maxActions: number;
+    readonly chatReplies: number;
+    readonly chatPause: number;
+    readonly places: Map<string, Place>;
+    readonly things: Map<string, Thing>;
+    readonly characters: Map<string, Character>;
+    readonly people: Map<string, Person>;
+    turnsUsed: number;
+    private readonly needDefs;
+    private readonly memory;
+    private readonly warn;
+    private readonly listeners;
+    private timer;
+    private budget;
+    private budgetAt;
+    private lastTick;
+    constructor(server: AgentServer, options: WorldOptions);
+    /** Listen for world events. Returns a function that unsubscribes. */
+    on(listener: (event: WorldEvent) => void): () => void;
+    /** @internal */
+    emit(event: WorldEvent): void;
+    addPlace(name: string, place: {
+        description?: string;
+        position: Position;
+        radius?: number;
+    }): void;
+    addThing(id: string, thing: {
+        name?: string;
+        place?: string;
+        position: Position;
+        activities: Record<string, Activity>;
+    }): void;
+    /** Add a human player. getPosition returns null while they have no body. */
+    addPerson(person: {
+        name: string;
+        getPosition: () => Position | null;
+    }): void;
+    removePerson(name: string): void;
+    placeAt(position: Position): string | null;
+    positionOf(name: string): Position | null;
+    /** Match a name the model wrote to someone in the world, ignoring case. */
+    resolve(name: string | undefined): string | undefined;
+    /** @internal */
+    humanNear(position: Position, range: number): boolean;
+    /** The instructions every character gets about this world. */
+    guide(home?: string): string;
+    /** Add a character and start its session. id is the character ID from the web app. */
+    addCharacter(def: {
+        id: string;
+        name: string;
+        body: Body;
+        home?: string;
+        goal?: string;
+        instructions?: string;
+        carrying?: string[];
+    }): Promise<Character>;
+    /** @internal Carry a spoken line to everyone who can hear it. Returns how many heard it. */
+    speech(speaker: string, text: string, to: string | undefined): number;
+    /** A human player said something. Without to, the closest resident in talking range takes it. */
+    say(speaker: string, text: string, to?: string): number;
+    /** Tell one character something happened, in plain words. */
+    tell(characterName: string, text: string, options?: NoticeOptions): void;
+    /** Tell every character within range of a position that something happened. */
+    announce(text: string, position?: Position, range?: number): void;
+    /** A human player hands an item to a character. */
+    give(from: string, characterName: string, item: string): boolean;
+    private spend;
+    private idleDelay;
+    private runTurn;
+    private tick;
+    /** Start giving characters turns. Call it once, after adding the characters. */
+    start(): void;
+    /** Stop giving turns. Sessions stay open until the server closes. */
+    stop(): void;
+}
+
+export { type ActionSpec, type Activity, AgentHandle, type AgentMetadata, AgentServer, AgentServerOptions, AttemptRecord, type Body, Character, ConnectionLostError, EventListener, PlatformAuthError, type Position, ProtocolVersionError, StartOptions, TurnFailedError, TurnResult, TurnTimeoutError, World, type WorldEvent, type WorldOptions, bindDynamic };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { A as AgentServerOptions, S as StartOptions, a as AgentHandle, E as EventListener } from './types-DXqkV7YA.js';
-export { b as AgentEvent, L as Logger, T as TurnOptions, c as TurnResult } from './types-DXqkV7YA.js';
+import { A as AgentServerOptions, S as StartOptions, a as AgentHandle, E as EventListener, T as TurnResult } from './types-BcH7_ozx.js';
+export { b as AgentEvent, L as Logger, c as TurnOptions } from './types-BcH7_ozx.js';
 import { AttemptRecord } from './protocol.js';
-export { TokenUsage } from './protocol.js';
+export { Relationship, StepRecord, TokenUsage } from './protocol.js';
 import { ZodRawShape } from 'zod';
 import '@modelcontextprotocol/sdk/shared/transport.js';
 
@@ -77,4 +77,312 @@ type DynamicCallback = (args: Record<string, unknown>) => unknown | Promise<unkn
  */
 declare function bindDynamic(player: object, name: string, description: string, args: ZodRawShape | undefined, callback?: DynamicCallback): void;
 
-export { type ActionSpec, AgentHandle, type AgentMetadata, AgentServer, AgentServerOptions, AttemptRecord, ConnectionLostError, EventListener, PlatformAuthError, ProtocolVersionError, StartOptions, TurnFailedError, TurnTimeoutError, bindDynamic };
+type Position = {
+    x: number;
+    y: number;
+    z?: number;
+};
+type Body = {
+    getPosition(): Position;
+    /** Walk to a position. Resolves true on arrival, false if interrupted or unreachable. */
+    moveTo(goal: Position): Promise<boolean>;
+    stop(): void;
+    /** Show a spoken line. May return the text as shown, when the game filters it. */
+    say(text: string, towards?: Position): string | void;
+    emote?(name: string): void;
+    face?(position: Position): void;
+    setStatus?(status: string | null): void;
+    emotes?: string[];
+};
+type Activity = {
+    description: string;
+    /** How long it takes. Default 5. */
+    seconds?: number;
+    /** Shown while it runs, such as "making coffee". Defaults to the activity name. */
+    status?: string;
+    /** Change to the character's needs when it finishes, such as { food: 40 }. */
+    effects?: Record<string, number>;
+    /** An item the character carries afterwards. */
+    gives?: string;
+    /** An item the character must carry. It is used up. */
+    needs?: string;
+    /** Emote played while it runs. */
+    emote?: string;
+};
+type WorldOptions = {
+    name: string;
+    /** One or two sentences about the world, for every character. */
+    about?: string;
+    /** Extra rules of the game, in plain words. */
+    rules?: string;
+    /** The time of day as text, such as "Tuesday 14:30, afternoon". */
+    clock?: () => string;
+    /** How far speech carries, and how far a character sees. Defaults 35 and 80. */
+    hearing?: number;
+    sight?: number;
+    /** A character with nothing to react to gets a turn about this often, in seconds. Default 45. */
+    idleSeconds?: number;
+    /** Idle turns are this many times rarer when no human is within activeRadius. Defaults 3 and 120. */
+    farSlowdown?: number;
+    activeRadius?: number;
+    /** A character no human can see waits this long before a turn for something it did itself. Default 20. */
+    farDelay?: number;
+    /** A human who comes this close is noticed. Default 12. 0 turns it off. */
+    greetDistance?: number;
+    /** Cap on turns per minute for the whole world. Default 30. */
+    turnsPerMinute?: number;
+    /** Actions per turn, 1 to 4. Default 3. */
+    maxActions?: number;
+    /** Needs every character has. 100 is satisfied, 0 is desperate. perMinute is how fast it falls. */
+    needs?: Record<string, {
+        perMinute: number;
+        start?: number;
+    }>;
+    /** Each character replies at most chatReplies times per chatPause seconds to another character. Defaults 2 and 90. */
+    chatReplies?: number;
+    chatPause?: number;
+    /** Keep memory and relationships on the platform. Default true. */
+    memory?: boolean;
+    /** Receives warnings. */
+    warn?: (message: string) => void;
+};
+type WorldEvent = {
+    type: "speech";
+    speaker: string;
+    text: string;
+    to?: string;
+} | {
+    type: "status";
+    character: string;
+    status: string | null;
+} | {
+    type: "relationship";
+    character: string;
+    about: string;
+    affinity: number;
+    label: string;
+    change: number;
+    because: string;
+} | {
+    type: "memory";
+    character: string;
+    about: string;
+    note: string;
+} | {
+    type: "action";
+    character: string;
+    action: string;
+    args: Record<string, unknown>;
+} | {
+    type: "thinking";
+    character: string;
+    on: boolean;
+} | {
+    type: "give";
+    from: string;
+    to: string;
+    item: string;
+} | {
+    type: "emote";
+    character: string;
+    emote: string;
+} | {
+    type: "turn";
+    character: string;
+    ok: boolean;
+    result?: TurnResult;
+    error?: string;
+};
+type Place = {
+    name: string;
+    description: string;
+    position: Position;
+    radius: number;
+};
+type Thing = {
+    id: string;
+    name: string;
+    place?: string;
+    position: Position;
+    activities: Record<string, Activity>;
+    usedBy: string | null;
+};
+type Person = {
+    name: string;
+    getPosition: () => Position | null;
+    carrying: string[];
+};
+type NoticeOptions = {
+    about?: string;
+    turn?: boolean;
+    urgent?: boolean;
+};
+declare class Character {
+    readonly world: World;
+    readonly name: string;
+    readonly body: Body;
+    readonly home: string | undefined;
+    readonly kind = "resident";
+    status: string | null;
+    carrying: string[];
+    needs: Record<string, number>;
+    turns: number;
+    tokens: number;
+    agent: AgentHandle;
+    /** @internal */ inbox: string[];
+    /** @internal */ wake: number | null;
+    /** @internal */ busy: boolean;
+    /** @internal */ greeted: Map<string, number>;
+    /** @internal */ needWarned: Set<string>;
+    private task;
+    private using;
+    private chat;
+    constructor(world: World, name: string, body: Body, home: string | undefined, carrying: string[]);
+    position(): Position;
+    place(): string | null;
+    setStatus(status: string | null): void;
+    /**
+     * 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: string, options?: NoticeOptions): void;
+    /** @internal */
+    wakeIn(seconds: number): void;
+    /** How this character feels about someone, from the platform. */
+    feelingFor(name: string): {
+        affinity: number;
+        label: string;
+        note?: string;
+    };
+    /** @internal Returns true when another character's line should get a reply. */
+    mayReplyToCharacter(): boolean;
+    /** @internal */
+    view(): Record<string, unknown>;
+    private interrupt;
+    private walk;
+    /** @internal */
+    doSay(rawText: string, to: string): {
+        said: string;
+        note: string;
+    } | {
+        said: string;
+        note?: undefined;
+    };
+    /** @internal */
+    doGoTo(placeName: string): {
+        walking_to: string;
+    };
+    /** @internal */
+    doApproach(person: string): {
+        note: string;
+        walking_to?: undefined;
+    } | {
+        walking_to: string;
+        note?: undefined;
+    };
+    /** @internal */
+    doUse(thingId: string, activityName: string): {
+        started: string;
+        takes_seconds: number;
+    };
+    /** @internal */
+    doGive(item: string, to: string): {
+        gave: string;
+        to: string;
+    };
+    /** @internal */
+    doEmote(name: string): {
+        did: string;
+    };
+}
+declare class World {
+    private readonly server;
+    readonly name: string;
+    readonly about: string;
+    readonly rules: string;
+    readonly clock: (() => string) | undefined;
+    readonly hearing: number;
+    readonly sight: number;
+    readonly idleSeconds: number;
+    readonly farSlowdown: number;
+    readonly activeRadius: number;
+    readonly farDelay: number;
+    readonly greetDistance: number;
+    readonly turnsPerMinute: number;
+    readonly maxActions: number;
+    readonly chatReplies: number;
+    readonly chatPause: number;
+    readonly places: Map<string, Place>;
+    readonly things: Map<string, Thing>;
+    readonly characters: Map<string, Character>;
+    readonly people: Map<string, Person>;
+    turnsUsed: number;
+    private readonly needDefs;
+    private readonly memory;
+    private readonly warn;
+    private readonly listeners;
+    private timer;
+    private budget;
+    private budgetAt;
+    private lastTick;
+    constructor(server: AgentServer, options: WorldOptions);
+    /** Listen for world events. Returns a function that unsubscribes. */
+    on(listener: (event: WorldEvent) => void): () => void;
+    /** @internal */
+    emit(event: WorldEvent): void;
+    addPlace(name: string, place: {
+        description?: string;
+        position: Position;
+        radius?: number;
+    }): void;
+    addThing(id: string, thing: {
+        name?: string;
+        place?: string;
+        position: Position;
+        activities: Record<string, Activity>;
+    }): void;
+    /** Add a human player. getPosition returns null while they have no body. */
+    addPerson(person: {
+        name: string;
+        getPosition: () => Position | null;
+    }): void;
+    removePerson(name: string): void;
+    placeAt(position: Position): string | null;
+    positionOf(name: string): Position | null;
+    /** Match a name the model wrote to someone in the world, ignoring case. */
+    resolve(name: string | undefined): string | undefined;
+    /** @internal */
+    humanNear(position: Position, range: number): boolean;
+    /** The instructions every character gets about this world. */
+    guide(home?: string): string;
+    /** Add a character and start its session. id is the character ID from the web app. */
+    addCharacter(def: {
+        id: string;
+        name: string;
+        body: Body;
+        home?: string;
+        goal?: string;
+        instructions?: string;
+        carrying?: string[];
+    }): Promise<Character>;
+    /** @internal Carry a spoken line to everyone who can hear it. Returns how many heard it. */
+    speech(speaker: string, text: string, to: string | undefined): number;
+    /** A human player said something. Without to, the closest resident in talking range takes it. */
+    say(speaker: string, text: string, to?: string): number;
+    /** Tell one character something happened, in plain words. */
+    tell(characterName: string, text: string, options?: NoticeOptions): void;
+    /** Tell every character within range of a position that something happened. */
+    announce(text: string, position?: Position, range?: number): void;
+    /** A human player hands an item to a character. */
+    give(from: string, characterName: string, item: string): boolean;
+    private spend;
+    private idleDelay;
+    private runTurn;
+    private tick;
+    /** Start giving characters turns. Call it once, after adding the characters. */
+    start(): void;
+    /** Stop giving turns. Sessions stay open until the server closes. */
+    stop(): void;
+}
+
+export { type ActionSpec, type Activity, AgentHandle, type AgentMetadata, AgentServer, AgentServerOptions, AttemptRecord, type Body, Character, ConnectionLostError, EventListener, PlatformAuthError, type Position, ProtocolVersionError, StartOptions, TurnFailedError, TurnResult, TurnTimeoutError, World, type WorldEvent, type WorldOptions, bindDynamic };