@rpgm-tools/neo-angband-core 0.10.0

package/dist/agent/types.d.ts

@@ -0,0 +1,436 @@
+/**
+ * The agent API contract (P7 phase 7): the three capability-gated facades a mod
+ * agent - the bundled Borg first, any third-party or AI agent after - drives the
+ * game through. This is the frozen surface BORG_AS_MOD.md section 5 calls for,
+ * built over the existing read model (GameState / KnownMap), act model
+ * (ActionRegistry / PlayerCommand) and the runGameLoop LOOP_STATUS.INPUT seam.
+ *
+ * Three facades:
+ * - PERCEIVE (AgentView): a stable, READ-ONLY view of the world covering the
+ *   BORG_AS_MOD section-3 read surface, plus the message stream and turn
+ *   counter. Capability: state:*.read.
+ * - ACT (AgentActions): the section-3 semantic verbs as command builders, plus
+ *   set-target by monster id or grid. Capability: command:add.
+ * - CONTROLLER (AgentController): a decision function invoked at the
+ *   LOOP_STATUS.INPUT boundary each time the game needs a command.
+ *
+ * Design note - why perceive returns PLAIN DATA, not a live proxy: every view
+ * accessor returns a fresh plain-data snapshot (no references into live engine
+ * objects), so the view is read-only by construction AND already serializable
+ * across a future Web Worker sandbox boundary. That sidesteps the
+ * "snapshot vs read-only proxy" fork (P7 plan phase 7): the same facade shape
+ * serves the in-process bundled Borg now and a sandboxed plugin later, with only
+ * the transport (direct call vs postMessage) differing.
+ *
+ * FREEZE STATUS: FROZEN at AGENT_API_VERSION 1.0.0 (ratified 2026-07-14, the
+ * P7 -> P8 gate). The sample agent (agent.test.ts) exercises the whole surface
+ * end-to-end and the maintainer ratified it against the BORG_AS_MOD section-3
+ * checklist. The contract is now stable: fields may be ADDED (a minor bump) but
+ * existing fields/semantics must not change without a major bump. P8 (the Borg)
+ * rides this facade as the completeness proof.
+ */
+import type { GameConstants, PlayerCommand } from "../game/context.js";
+import type { ContentIdResolver } from "../mod/ids.js";
+import type { ObjRegistry } from "../obj/bind.js";
+import type { ObjectKind } from "../obj/types.js";
+/**
+ * The frozen agent-API version (ratified 2026-07-14). Add-only from here: a new
+ * field is a minor bump (1.x), any change to an existing field/semantics is a
+ * major bump (2.0).
+ */
+export declare const AGENT_API_VERSION = "1.0.0";
+/**
+ * A command an agent emits - identical to the engine's PlayerCommand (codes 1:1
+ * with upstream). Aliased so the public contract does not leak the internal
+ * type name and can diverge later if needed.
+ */
+export type AgentCommand = PlayerCommand;
+/**
+ * The capability check the facades consult. Structurally satisfied by mod-sdk's
+ * CapabilitySet (which exposes has(capability)), so the plugin runtime can pass
+ * its CapabilitySet directly without core depending on mod-sdk. Absent (in-process
+ * trusted host, e.g. the bundled Borg before the sandbox lands) means all granted.
+ */
+export interface AgentCapabilities {
+    has(capability: string): boolean;
+}
+/**
+ * Thrown when a facade or controller is used without a capability it requires.
+ * Lives here (not controller.ts) so perceive/act can throw it without importing
+ * the controller (which imports them).
+ */
+export declare class AgentCapabilityError extends Error {
+}
+/**
+ * The perceive-facade domain each AgentView accessor reads, gated by
+ * "state:<domain>.read" (the "state:*.read" wildcard covers all). A view built
+ * with no AgentCapabilities is a trusted host and every domain is granted.
+ */
+export declare const AGENT_STATE_DOMAINS: {
+    readonly turn: "turn";
+    readonly player: "player";
+    readonly monsters: "monsters";
+    readonly map: "map";
+    readonly inventory: "inventory";
+    readonly floor: "floor";
+    readonly target: "target";
+    readonly messages: "messages";
+    readonly stores: "stores";
+    readonly spells: "spells";
+    readonly constants: "constants";
+};
+/** The player's timed status afflictions (turns remaining, 0 = clear). */
+export interface PlayerStatusView {
+    blind: number;
+    confused: number;
+    afraid: number;
+    poisoned: number;
+    cut: number;
+    stun: number;
+    paralyzed: number;
+    /** food store (p->timed[TMD_FOOD]). */
+    food: number;
+}
+/** A read-only view of the player (BORG_AS_MOD section 3, Player). */
+export interface PlayerView {
+    race: string;
+    cls: string;
+    level: number;
+    maxLevel: number;
+    exp: number;
+    maxExp: number;
+    gold: number;
+    depth: number;
+    maxDepth: number;
+    hp: number;
+    maxHp: number;
+    sp: number;
+    maxSp: number;
+    /** Net speed after effects (110 = normal). */
+    speed: number;
+    ac: number;
+    toHit: number;
+    toDam: number;
+    /** Base stats (STAT order); length STAT_MAX. */
+    stats: number[];
+    /** Derived light radius. */
+    light: number;
+    grid: {
+        x: number;
+        y: number;
+    };
+    status: PlayerStatusView;
+    dead: boolean;
+    winner: boolean;
+    /** Namespaced player-race id, when a ContentIdResolver with player races is supplied. */
+    playerRaceId?: string;
+    /** Namespaced player-class id, when a ContentIdResolver with player classes is supplied. */
+    playerClassId?: string;
+    /** Derived skills (SKILL order); length SKILL_MAX. */
+    skills: number[];
+    /** Current shapechange name, or null in the normal shape. */
+    shape: string | null;
+    /** OF_* codes from the derived player state's flag set (empty if absent). */
+    objectFlags: string[];
+    /** Infravision range in grids. */
+    seeInfra: number;
+    /** state->num_blows (hundredths of a blow; 0 if the combat state is absent). */
+    blows: number;
+    /** state->num_shots (tenths of a shot; 0 if the combat state is absent). */
+    shots: number;
+}
+/** A read-only view of a monster (BORG_AS_MOD section 3, Monsters). */
+export interface MonsterView {
+    /** Stable in-level id (midx). */
+    id: number;
+    /** Race name and index (a namespaced race id is a documented follow-up). */
+    race: string;
+    raceIndex: number;
+    grid: {
+        x: number;
+        y: number;
+    };
+    visible: boolean;
+    hp: number;
+    maxHp: number;
+    /** Net monster speed (110 = normal). */
+    speed: number;
+    asleep: boolean;
+    afraid: boolean;
+    confused: boolean;
+    stunned: boolean;
+    /** race->level. */
+    level: number;
+    /**
+     * No MON_TMD_* poison timer exists upstream (monsters are never "poisoned"
+     * as a timed status in 4.2.6); always false. Kept for section-3 parity.
+     */
+    poisoned: boolean;
+    /** RF_* codes from race->flags. */
+    raceFlags: string[];
+    /** RSF_* codes from race->spellFlags. */
+    spellFlags: string[];
+    /** Namespaced race id, when a ContentIdResolver dep is supplied. */
+    raceId?: string;
+}
+/** A read-only view of one map cell (BORG_AS_MOD section 3, Dungeon grid). */
+export interface CellView {
+    x: number;
+    y: number;
+    /** Terrain feature index. */
+    feat: number;
+    passable: boolean;
+    /** The player has this square in view right now. */
+    inView: boolean;
+    /** The player remembers this square (known map). */
+    known: boolean;
+    /** Occupying monster id, or 0 for none. */
+    monster: number;
+    /** Number of floor objects on the square. */
+    objectCount: number;
+    /** SQUARE_GLOW: the square is self-illuminating. */
+    glow: boolean;
+    /** A live trap pile occupies this square. */
+    trap: boolean;
+    /** Namespaced terrain-feature id, when a ContentIdResolver dep is supplied
+     * and the feature index is bound (never present for an unset sentinel). */
+    featCode?: string;
+}
+/** A read-only view of an object (BORG_AS_MOD section 3, Items). */
+export interface ItemView {
+    /** Gear handle when carried/worn; 0 for a floor object. */
+    handle: number;
+    label: string;
+    tval: number;
+    sval: number;
+    pval: number;
+    number: number;
+    weight: number;
+    ac: number;
+    toA: number;
+    toH: number;
+    toD: number;
+    dd: number;
+    ds: number;
+    ego: boolean;
+    artifact: boolean;
+    /** OF_* codes on obj.flags. */
+    flags: string[];
+    /** Nonzero obj.modifiers entries, by OBJ_MOD code. */
+    modifiers: Array<{
+        code: string;
+        value: number;
+    }>;
+    /** Brand codes active on this object (obj.brands[i] true). */
+    brands: string[];
+    /** Slay codes active on this object (obj.slays[i] true). */
+    slays: string[];
+    /** Nonzero resistances/vulnerabilities, by element name. */
+    resists: Array<{
+        element: string;
+        level: number;
+    }>;
+    /**
+     * Names of active curses (power > 0). A curse whose name cannot be
+     * resolved (no registry dep supplied) falls back to its numeric index
+     * as a string.
+     */
+    curses: string[];
+    egoName: string | null;
+    artifactName: string | null;
+    activation: boolean;
+    timeout: number;
+    inscription: string | null;
+    /** Namespaced kind id, when a ContentIdResolver dep is supplied. */
+    kindId?: string;
+    /** objectValue for this stack, when a registry dep is supplied. */
+    value?: number;
+}
+/** One item in a store's stock (ItemView plus its slot and buy price). */
+export interface StoreItemView extends ItemView {
+    /** Position in the store's stock array. */
+    index: number;
+    /**
+     * The player's buy price (priceItem), when a registry dep is supplied.
+     * Omitted for the home (nothing is for sale) and when no registry dep is
+     * given.
+     */
+    price?: number;
+}
+/** A read-only view of a store (BORG_AS_MOD section 3, Stores). */
+export interface StoreView {
+    feat: number;
+    featName: string;
+    isHome: boolean;
+    owner: {
+        name: string;
+        purse: number;
+    };
+    stock: StoreItemView[];
+}
+/** A read-only view of one learnable/known spell. */
+export interface SpellView {
+    name: string;
+    /** Class-wide spell index. */
+    sidx: number;
+    /** Index of the owning book in the class's books array. */
+    bidx: number;
+    /** Required level to learn. */
+    level: number;
+    mana: number;
+    /** Base failure chance (before level/stat/status adjustments). */
+    fail: number;
+    /**
+     * Live cast-failure percent (spell_chance: base fail adjusted by level,
+     * casting stat, low mana, fear, stun, amnesia). Present only when the
+     * derived stat indices (state.statInd) are available.
+     */
+    chance?: number;
+    learned: boolean;
+    worked: boolean;
+    forgotten: boolean;
+}
+/** A read-only view of one spellbook and its spells. */
+export interface SpellbookView {
+    tval: number;
+    name: string;
+    realm: string;
+    spells: SpellView[];
+}
+/** The current target, if any (BORG_AS_MOD section 3, set-target). */
+export interface TargetView {
+    /** Targeted monster id, or 0 for a bare location target. */
+    midx: number;
+    grid: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * The perceive facade: a read-only view of the world. Every accessor returns
+ * fresh plain data (no live engine references). Capability: state:*.read.
+ */
+export interface AgentView {
+    readonly apiVersion: string;
+    /** The int32 game-turn counter. */
+    turn(): number;
+    player(): PlayerView;
+    /** Live monsters (index 0 unused slot omitted). */
+    monsters(): MonsterView[];
+    /** One map cell, or null when out of bounds. */
+    cell(x: number, y: number): CellView | null;
+    mapBounds(): {
+        width: number;
+        height: number;
+    };
+    /** The carried pack (non-equipped gear), in pack order. */
+    inventory(): ItemView[];
+    /** Worn equipment by body slot; null for an empty slot. */
+    equipment(): Array<ItemView | null>;
+    /** Floor objects on a grid (head-first, newest drop first). */
+    floorItems(x: number, y: number): ItemView[];
+    /** The current target, or null when none is set. */
+    target(): TargetView | null;
+    /** Messages emitted since the previous decision (oldest first). */
+    messages(): string[];
+    /** Live town stores, or [] when none (dungeon levels, worldless harness). */
+    stores(): StoreView[];
+    /** The player class's spellbooks; [] for a non-caster. */
+    spellbooks(): SpellbookView[];
+    /** A plain clone of the bound game constants (z_info). */
+    constants(): GameConstants;
+}
+/**
+ * Optional dependencies that unlock the richer perceive fields (namespaced
+ * ids, store pricing, object value). Every field degrades gracefully when
+ * absent: the corresponding optional ItemView/CellView/MonsterView fields are
+ * simply omitted, never thrown for.
+ */
+export interface AgentViewDeps {
+    /** Enables kindId / raceId / featCode namespaced-id fields. */
+    resolver?: ContentIdResolver;
+    /** Enables ItemView.value and StoreItemView.price. */
+    reg?: ObjRegistry;
+    /** object_flavor_is_aware(kind), for object value/price dispatch. */
+    aware?: (kind: ObjectKind) => boolean;
+    /** OPT(player, birth_no_selling), for store buy pricing. */
+    noSelling?: boolean;
+}
+/**
+ * The act facade: the BORG_AS_MOD section-3 semantic verbs as command builders,
+ * plus set-target (a direct state action, not a queued command). Capability:
+ * command:add. Verbs build a typed AgentCommand; whether a given code is fully
+ * implemented in the engine yet is orthogonal to the contract (the Borg port,
+ * P8, drives the remaining ones as parity fills them in).
+ */
+export interface AgentActions {
+    move(dir: number): AgentCommand;
+    /** Melee an adjacent monster (a walk into its grid). */
+    melee(dir: number): AgentCommand;
+    hold(): AgentCommand;
+    rest(): AgentCommand;
+    descend(): AgentCommand;
+    ascend(): AgentCommand;
+    tunnel(dir: number): AgentCommand;
+    open(dir: number): AgentCommand;
+    close(dir: number): AgentCommand;
+    disarm(dir: number): AgentCommand;
+    quaff(handle: number): AgentCommand;
+    read(handle: number): AgentCommand;
+    eat(handle: number): AgentCommand;
+    wear(handle: number): AgentCommand;
+    takeoff(handle: number): AgentCommand;
+    drop(handle: number, number?: number): AgentCommand;
+    pickup(): AgentCommand;
+    destroy(handle: number): AgentCommand;
+    aimWand(handle: number): AgentCommand;
+    zapRod(handle: number): AgentCommand;
+    useStaff(handle: number): AgentCommand;
+    activate(handle: number): AgentCommand;
+    fire(handle: number): AgentCommand;
+    throw(handle: number): AgentCommand;
+    cast(spell: number): AgentCommand;
+    setTargetMonster(midx: number): boolean;
+    setTargetLocation(x: number, y: number): void;
+    shopBuy(index: number, number?: number): AgentCommand;
+    shopSell(handle: number, number?: number): AgentCommand;
+    shopExit(): AgentCommand;
+    /**
+     * Escape hatch: emit any command code with free-form args (for verbs not yet
+     * given a typed builder, or mod-registered codes).
+     */
+    raw(code: string, args?: Record<string, unknown>): AgentCommand;
+}
+/**
+ * The decision function: given the current perceive view and the act facade,
+ * return the next command, or null to yield control (the loop returns
+ * LOOP_STATUS.INPUT, e.g. to hand back to a human or wait). Invoked once each
+ * time the game needs a command.
+ */
+export type AgentController = (view: AgentView, act: AgentActions) => AgentCommand | null;
+/** Options for installing a controller. */
+export interface ControllerOptions {
+    /**
+     * The capability grant to enforce. Absent means an in-process trusted host
+     * (all capabilities granted) - the bundled-Borg-before-sandbox case.
+     */
+    capabilities?: AgentCapabilities;
+    /**
+     * The controller draws nondeterministic sources (an AI agent, a wall clock, a
+     * network). The runtime should flip the save's determinism mode via
+     * onNondeterministic (the core-owned one-way ratchet, save-blocks.ts).
+     */
+    nondeterministic?: boolean;
+    /** Called once at install when nondeterministic is true, to trip the ratchet. */
+    onNondeterministic?: () => void;
+    /** Optional deps threaded into createAgentView (namespaced ids, pricing). */
+    viewDeps?: AgentViewDeps;
+}
+/** A live agent binding: its facades plus a teardown that restores the loop. */
+export interface AgentSession {
+    view: AgentView;
+    act: AgentActions;
+    /** Restore the previous nextCommand / message sink. */
+    uninstall(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"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"}

package/dist/agent/types.js

@@ -0,0 +1,63 @@
+/**
+ * The agent API contract (P7 phase 7): the three capability-gated facades a mod
+ * agent - the bundled Borg first, any third-party or AI agent after - drives the
+ * game through. This is the frozen surface BORG_AS_MOD.md section 5 calls for,
+ * built over the existing read model (GameState / KnownMap), act model
+ * (ActionRegistry / PlayerCommand) and the runGameLoop LOOP_STATUS.INPUT seam.
+ *
+ * Three facades:
+ * - PERCEIVE (AgentView): a stable, READ-ONLY view of the world covering the
+ *   BORG_AS_MOD section-3 read surface, plus the message stream and turn
+ *   counter. Capability: state:*.read.
+ * - ACT (AgentActions): the section-3 semantic verbs as command builders, plus
+ *   set-target by monster id or grid. Capability: command:add.
+ * - CONTROLLER (AgentController): a decision function invoked at the
+ *   LOOP_STATUS.INPUT boundary each time the game needs a command.
+ *
+ * Design note - why perceive returns PLAIN DATA, not a live proxy: every view
+ * accessor returns a fresh plain-data snapshot (no references into live engine
+ * objects), so the view is read-only by construction AND already serializable
+ * across a future Web Worker sandbox boundary. That sidesteps the
+ * "snapshot vs read-only proxy" fork (P7 plan phase 7): the same facade shape
+ * serves the in-process bundled Borg now and a sandboxed plugin later, with only
+ * the transport (direct call vs postMessage) differing.
+ *
+ * FREEZE STATUS: FROZEN at AGENT_API_VERSION 1.0.0 (ratified 2026-07-14, the
+ * P7 -> P8 gate). The sample agent (agent.test.ts) exercises the whole surface
+ * end-to-end and the maintainer ratified it against the BORG_AS_MOD section-3
+ * checklist. The contract is now stable: fields may be ADDED (a minor bump) but
+ * existing fields/semantics must not change without a major bump. P8 (the Borg)
+ * rides this facade as the completeness proof.
+ */
+/**
+ * The frozen agent-API version (ratified 2026-07-14). Add-only from here: a new
+ * field is a minor bump (1.x), any change to an existing field/semantics is a
+ * major bump (2.0).
+ */
+export const AGENT_API_VERSION = "1.0.0";
+/**
+ * Thrown when a facade or controller is used without a capability it requires.
+ * Lives here (not controller.ts) so perceive/act can throw it without importing
+ * the controller (which imports them).
+ */
+export class AgentCapabilityError extends Error {
+}
+/**
+ * The perceive-facade domain each AgentView accessor reads, gated by
+ * "state:<domain>.read" (the "state:*.read" wildcard covers all). A view built
+ * with no AgentCapabilities is a trusted host and every domain is granted.
+ */
+export const AGENT_STATE_DOMAINS = {
+    turn: "turn",
+    player: "player",
+    monsters: "monsters",
+    map: "map",
+    inventory: "inventory",
+    floor: "floor",
+    target: "target",
+    messages: "messages",
+    stores: "stores",
+    spells: "spells",
+    constants: "constants",
+};
+//# sourceMappingURL=types.js.map

package/dist/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAuBzC;;;;GAIG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;CAAG;AAElD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,IAAI,EAAE,MAAM;IACZ,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,GAAG,EAAE,KAAK;IACV,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,QAAQ;IAChB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,SAAS,EAAE,WAAW;CACd,CAAC"}