@rpgm-tools/neo-angband-core 0.26.0 → 0.27.0

package/dist/store/store-cmd.js

@@ -16,8 +16,20 @@
  * - or anything that moves the player mid-transaction - reaches these. They are
  * therefore real guards on the command path, returning upstream's message or
  * null to proceed, rather than assertions.
+ *
+ * Also here: `installStoreCommands`, which registers the `shop-buy` /
+ * `shop-sell` / `shop-exit` action-registry handlers `createAgentActions`
+ * (agent/act.ts) builds commands for. Those three codes had no handler at
+ * all until this was added (docs/PLANNED.md, "An agent cannot trade") - a
+ * controller's shopping decisions reached the queue and were silently
+ * dropped. The handlers use the guards above plus `storeAtGrid` to resolve
+ * "which store" fresh from the player's grid, then commit through the same
+ * `StartedGame.buy` / `.sell` closures the interactive shop screen calls.
  */
 import { FEAT } from "../generated/index.js";
+import { describeObject } from "../game/describe.js";
+import { gearGet } from "../game/gear.js";
+import { ODESC } from "../obj/desc.js";
 /**
  * do_cmd_buy (store.c:1667-1670): purchasing requires standing in a store.
  * Returns the refusal message, or null when the command may proceed.
@@ -70,4 +82,154 @@ export function enterStoreGuard(store) {
         return "You see no store here.";
     return null;
 }
+/**
+ * store_at (store.c, read fresh from `square_shopnum`): the live store whose
+ * entrance feature the player is standing on right now, or null. Every store
+ * command below re-resolves this rather than trust a Store handed to it, for
+ * the same reason the guards above exist - do_cmd_buy / do_cmd_sell /
+ * do_cmd_retrieve / do_cmd_stash all call store_at(cave, player->grid) fresh,
+ * every time (store.c:1665, :1795, :1872, :2014). The shell's own
+ * `storeAtPlayer` (packages/web/src/main.ts) does the same lookup for the
+ * interactive shop screen; this is the engine-side twin an agent's direct
+ * commands need, since they carry no Store reference at all - only a stock
+ * index or a gear handle.
+ */
+export function storeAtGrid(state) {
+    const feat = state.chunk.feat(state.actor.grid);
+    return state.stores?.find((s) => s.feat === feat) ?? null;
+}
+const BUY_FAILURE_SHOP = {
+    "not-in-stock": "You cannot buy that item because it's not in the store.",
+    "no-room": "You cannot carry that many items.",
+    "cannot-afford": "You cannot afford that purchase.",
+};
+const BUY_FAILURE_HOME = {
+    "not-in-stock": "You cannot retrieve that item because it's not in the home.",
+    "no-room": "You cannot carry that many items.",
+};
+/**
+ * Register `shop-buy`, `shop-sell` and `shop-exit` on the action registry -
+ * the three command codes `createAgentActions` (agent/act.ts) builds and
+ * nothing in the engine handled (docs/PLANNED.md, "An agent cannot trade").
+ * On the same terms as every other verb: a plain `registry.register` entry
+ * that runs whether the command arrived from a keystroke or an agent's
+ * controller, and spends no energy - do_cmd_buy/_sell/_retrieve/_stash pass
+ * no game turn (a shop visit does not let monsters act), and there is no
+ * upstream leave-store command to spend one either.
+ *
+ * `shop-buy`/`shop-sell` carry no Store reference (an agent addresses a ware
+ * by its stock index, an item by its gear handle - AgentView.stores()[n]
+ * and view.inventory()[n], never a live object), so the handler resolves
+ * "which store" itself via storeAtGrid and re-runs the entry guard
+ * do_cmd_buy/_sell/_retrieve/_stash each run first, exactly as those C
+ * functions do. `shop-exit` has no upstream engine counterpart at all - the
+ * C command is a UI-only "close the shop screen" with no game-state effect -
+ * so it is registered as a legitimate no-op rather than left unhandled.
+ */
+export function installStoreCommands(registry, deps) {
+    registry.register("shop-buy", (state, cmd) => {
+        const args = cmd.args ?? {};
+        const index = typeof args["index"] === "number" ? args["index"] : null;
+        if (index === null)
+            return 0;
+        const store = storeAtGrid(state);
+        if (!store) {
+            state.msg?.(storeBuyGuard(null) ?? "You cannot purchase items when not in a store.");
+            return 0;
+        }
+        const isHome = store.feat === FEAT.HOME;
+        const refusal = isHome ? storeRetrieveGuard(store) : storeBuyGuard(store);
+        if (refusal) {
+            state.msg?.(refusal);
+            return 0;
+        }
+        const obj = store.stock[index];
+        if (!obj) {
+            state.msg?.(isHome
+                ? "You cannot retrieve that item because it's not in the home."
+                : "You cannot buy that item because it's not in the store.");
+            return 0;
+        }
+        const rawQty = typeof args["quantity"] === "number" ? args["quantity"] : 1;
+        const amt = Math.min(Math.max(1, rawQty), obj.number);
+        const result = deps.buy(store, obj, amt);
+        if (!result.ok) {
+            const table = isHome ? BUY_FAILURE_HOME : BUY_FAILURE_SHOP;
+            state.msg?.(table[result.failure ?? ""] ?? "The purchase failed.");
+            return 0;
+        }
+        const bought = result.bought
+            ? describeObject(state, result.bought, ODESC.PREFIX | ODESC.FULL)
+            : "the item";
+        /* comment_accept (do_cmd_buy L1717) prints before the sale line, exactly
+         * as the interactive shop screen orders it. */
+        if (result.acceptComment)
+            state.msg?.(result.acceptComment);
+        if (isHome)
+            state.msg?.(`You have ${bought}.`);
+        else
+            state.msg?.(`You bought ${bought} for ${result.price} gold.`);
+        if (result.emptied === "retired")
+            state.msg?.("The shopkeeper retires.");
+        else if (result.emptied === "restocked") {
+            state.msg?.("The shopkeeper brings out some new stock.");
+        }
+        return 0;
+    });
+    registry.register("shop-sell", (state, cmd) => {
+        const args = cmd.args ?? {};
+        const handle = typeof args["handle"] === "number" ? args["handle"] : null;
+        if (handle === null)
+            return 0;
+        const store = storeAtGrid(state);
+        if (!store) {
+            state.msg?.(storeSellGuard(null) ?? "You cannot sell items when not in a store.");
+            return 0;
+        }
+        const isHome = store.feat === FEAT.HOME;
+        const refusal = isHome ? storeStashGuard(store) : storeSellGuard(store);
+        if (refusal) {
+            state.msg?.(refusal);
+            return 0;
+        }
+        const obj = gearGet(state.gear, handle);
+        if (!obj) {
+            state.msg?.("You do not have that item.");
+            return 0;
+        }
+        const rawQty = typeof args["quantity"] === "number" ? args["quantity"] : obj.number;
+        const amt = Math.min(Math.max(1, rawQty), obj.number);
+        const result = deps.sell(store, handle, amt);
+        if (!result.ok) {
+            const why = {
+                "no-item": "You do not have that item.",
+                stuck: "Hmmm, it seems to be stuck.",
+                refused: "I do not wish to purchase this item.",
+                "no-room": isHome
+                    ? "Your home is full."
+                    : "I have not the room in my store to keep it.",
+            };
+            state.msg?.(why[result.failure ?? ""] ?? "The sale failed.");
+            return 0;
+        }
+        const sold = result.sold
+            ? describeObject(state, result.sold, ODESC.PREFIX | ODESC.FULL)
+            : "the item";
+        if (isHome)
+            state.msg?.(`You have stashed ${sold}.`);
+        else if (result.price)
+            state.msg?.(`You sold ${sold} for ${result.price} gold.`);
+        else
+            state.msg?.(`You had ${sold}.`);
+        /* purchase_analyze's reaction comment (do_cmd_sell L1972), same ordering
+         * as the interactive shop screen. */
+        if (result.reactionComment)
+            state.msg?.(result.reactionComment);
+        return 0;
+    });
+    /* leave_store (ui-store.c): a UI-only close with no upstream game-state
+     * effect. Registered so the code has a real handler rather than falling
+     * through to the base registry's no-op stub silently. */
+    registry.register("shop-exit", () => 0);
+}
 //# sourceMappingURL=store-cmd.js.map

package/dist/store/store-cmd.js.map

@@ -1 +1 @@
-{"version":3,"file":"store-cmd.js","sourceRoot":"","sources":["../../src/store/store-cmd.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAG7C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAmB;IAC/C,IAAI,CAAC,KAAK;QAAE,OAAO,gDAAgD,CAAC;IACpE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAmB;IACpD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;QAAE,OAAO,gCAAgC,CAAC;IACtE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAmB;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,4CAA4C,CAAC;IAChE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI;QAAE,OAAO,2BAA2B,CAAC;IAC3E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,wBAAwB,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"store-cmd.js","sourceRoot":"","sources":["../../src/store/store-cmd.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -21,5 +21,5 @@ export declare const PARITY_BASELINE = "4.2.6";
  * released tag is iterated takes a MINOR bump, because a published tag is pinned
  * by digest in a catalogue and must never be moved.
  */
-export declare const ENGINE_VERSION = "0.26.0";
+export declare const ENGINE_VERSION = "0.27.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -21,5 +21,5 @@ export const PARITY_BASELINE = "4.2.6";
  * released tag is iterated takes a MINOR bump, because a published tag is pinned
  * by digest in a catalogue and must never be moved.
  */
-export const ENGINE_VERSION = "0.26.0";
+export const ENGINE_VERSION = "0.27.0";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rpgm-tools/neo-angband-core",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Headless Neo Angband game engine: rules, world, entities, effects, generation",
   "license": "GPL-2.0-only",
   "author": "neostryder (RPGM Tools)",

package/src/agent/act.ts

@@ -17,6 +17,7 @@
  */
 
 import type { GameState } from "../game/context.js";
+import { REST_COMPLETE } from "../game/context.js";
 import { targetSetLocation, targetSetMonster } from "../game/target.js";
 import { loc } from "../loc.js";
 import { AgentCapabilityError } from "./types.js";
@@ -67,7 +68,7 @@ export function createAgentActions(
     move: (dir) => dirCmd("walk", dir),
     melee: (dir) => dirCmd("walk", dir),
     hold: () => cmd("hold"),
-    rest: () => cmd("rest"),
+    rest: (count) => cmd("rest", { count: count ?? REST_COMPLETE }),
     descend: () => cmd("descend"),
     ascend: () => cmd("ascend"),
     tunnel: (dir) => dirCmd("tunnel", dir),

package/src/agent/types.ts

@@ -634,7 +634,17 @@ export interface AgentActions {
   /** Melee an adjacent monster (a walk into its grid). */
   melee(dir: number): AgentCommand;
   hold(): AgentCommand;
-  rest(): AgentCommand;
+  /**
+   * do_cmd_rest (cmd-cave.c:1619): rest for `count` game turns, or one of the
+   * REST_ special modes (REST_COMPLETE / REST_ALL_POINTS / REST_SOME_POINTS,
+   * player-util.h:53-55, exported from game/context.js). One command turn is
+   * many game turns: the engine self-continues on its internal queue exactly
+   * like a run, so a caller normally issues this ONCE and is not asked for
+   * another command until the rest ends (disturbed, or its own condition met).
+   * Omitting `count` rests as needed (REST_COMPLETE), matching the human UI's
+   * own default prompt answer ("&").
+   */
+  rest(count?: number): AgentCommand;
   descend(): AgentCommand;
   ascend(): AgentCommand;
   tunnel(dir: number): AgentCommand;

package/src/game/context.ts

@@ -458,8 +458,7 @@ export interface GameState {
    * (the per-session file-static player_turns_rested that gates the x2 regen):
    * resting_turn accumulates for the character's whole life. Bumped once per rested
    * turn (player-util.c:1487). Persists in the save; absent is treated as 0.
-   * The live producer (the rest command) lives outside this module - see the
-   * WIRING-NEEDED note in session/save.ts.
+   * The live producer is the rest command's restAction (game/player-turn.ts).
    */
   restingTurn?: number;
   /**
@@ -604,11 +603,20 @@ export interface GameState {
    * player->upkeep->resting + the file-static player_turns_rested
    * (player-util.c:1417,1472). count mirrors upkeep->resting (>0 = timed turns
    * left, or a REST_ special: COMPLETE=-2, ALL_POINTS=-1, SOME_POINTS=-3);
-   * turnsRested gates the x2 regen. Set/tracked by the web rest command
-   * (packages/web main.ts driveRest); absent when not resting.
+   * turnsRested gates the x2 regen. Set/tracked by the rest command
+   * (restAction, game/player-turn.ts); absent when not resting.
    */
   resting?: { count: number; turnsRested: number };
 
+  /**
+   * player_resting_repeat_count (player-util.c:1523): the file-static count
+   * remembered from the last TIMED rest, so re-issuing rest with count === 1
+   * repeats it (cmd-cave.c:1638-1643). Session-transient like the file-static
+   * it mirrors - never persisted, reset only by a fresh rest that supplies a
+   * new count > 1. Absent is the upstream static's zero-initialized state.
+   */
+  restRepeatCount?: number;
+
   /* --- injected hooks --- */
   /**
    * The EffectBuilder injections this session was wired with: the resolvers for
@@ -1168,6 +1176,17 @@ export interface RunState {
  * reach for. The HOST still resolves the choice map (it is save state, and the
  * Fixes & tweaks menu is built from it) - that reading lives in the host. */
 
+/**
+ * The REST_ constants (player-util.h:53-55): conditional rest modes, which
+ * rest until a condition is met rather than for a fixed turn count. Exported
+ * so callers outside the engine (the agent facade, a mod, a host UI) can build
+ * a rest command's `args.count` without re-declaring the magic numbers - the
+ * web shell used to carry its own private copy of exactly these three.
+ */
+export const REST_COMPLETE = -2;
+export const REST_ALL_POINTS = -1;
+export const REST_SOME_POINTS = -3;
+
 /**
  * player_resting_is_special (player-util.c:1382): the conditional REST_ modes,
  * which rest until a condition is met rather than for a fixed count.
@@ -1180,7 +1199,11 @@ export interface RunState {
  * three bodies only agrees by luck.
  */
 export function playerRestingIsSpecial(count: number): boolean {
-  return count === -1 || count === -2 || count === -3;
+  return (
+    count === REST_ALL_POINTS ||
+    count === REST_COMPLETE ||
+    count === REST_SOME_POINTS
+  );
 }
 
 /**

package/src/game/loop.ts

@@ -49,6 +49,7 @@ import {
   playAmbientSound,
   playerHasWorld,
   playerOfHasWorld,
+  playerRestingCompleteSpecial,
   playerUpdateLight,
   processDamageOverTime,
   processExpDrain,
@@ -177,7 +178,8 @@ const REST_REQUIRED_FOR_REGEN = 5;
  * player_resting_can_regenerate (player-util.c:1461): the player earns the x2
  * regeneration bonus once REST_REQUIRED_FOR_REGEN turns of the current rest
  * have elapsed, or immediately for the conditional REST_ modes. The rest
- * command (WP-11, web) sets state.resting; absent when not resting. No RNG.
+ * command's restAction (game/player-turn.ts) sets state.resting; absent when
+ * not resting. No RNG.
  */
 function playerRestingCanRegenerate(state: GameState): boolean {
   const r = state.resting;
@@ -551,10 +553,10 @@ function loopStop(state: GameState): LoopStatus | null {
  * keeps the headless harnesses, the borg and the tests driving a whole run
  * inside one call.
  *
- * The upstream call sits at the top of process_player, before its do-while;
- * calling it immediately before processPlayer() is the same point in the order.
- * player_resting_complete_special, signalled on the line above it, is ported as
- * a predicate the host's rest lifecycle owns (restingCompleteSpecial, WP-11).
+ * The upstream call sits at the top of process_player, right after
+ * player_resting_complete_special (game-world.c:936-937); processPlayerChecked
+ * calls playerRestingCompleteSpecial immediately before this, which is the
+ * same point in the order.
  */
 export function checkForPlayerInterrupt(state: GameState): InterruptResponse {
   if (!state.checkInterrupt) return "go";
@@ -582,8 +584,15 @@ export function checkForPlayerInterrupt(state: GameState): InterruptResponse {
 }
 
 /**
- * process_player (game-world.c:933): the interrupt check, then the turn. "pause"
- * is the host asking for its event loop back before the turn is taken.
+ * process_player (game-world.c:933-937): player_resting_complete_special, the
+ * interrupt check, then the turn. "pause" is the host asking for its event
+ * loop back before the turn is taken.
+ *
+ * playerRestingCompleteSpecial runs first, exactly as upstream orders it -
+ * a conditional rest (REST_ALL_POINTS / REST_COMPLETE / REST_SOME_POINTS) that
+ * has already met its own stopping condition (HP/SP full, no bad statuses) is
+ * disturbed before the interrupt check or the turn, so it does not spend one
+ * extra turn beyond upstream's.
  *
  * mayPause is false for the FIRST turn of a runGameLoop call. A call resumed
  * after LOOP_STATUS.PAUSE re-enters at that same point, so pausing there would
@@ -596,6 +605,7 @@ function processPlayerChecked(
   registry: ActionRegistry,
   mayPause: boolean,
 ): PlayerTurnResult | "pause" {
+  playerRestingCompleteSpecial(state);
   if (checkForPlayerInterrupt(state) === "pause" && mayPause) return "pause";
   return processPlayer(state, registry);
 }

package/src/game/player-turn.ts

@@ -59,6 +59,8 @@ import {
   deleteMonster,
   gameTakeHitHooks,
   movePlayer,
+  playerIsResting,
+  playerRestingIsSpecial,
   squareMonster,
 } from "./context.js";
 import { gearGet } from "./gear.js";
@@ -800,6 +802,98 @@ export function sleepAction(state: GameState, _cmd: PlayerCommand): number {
   return state.z.moveEnergy;
 }
 
+/**
+ * rest (do_cmd_rest, cmd-cave.c:1619-1669): rest for `cmd.args.count` turns, or
+ * until one of the REST_ special conditions (REST_COMPLETE / REST_ALL_POINTS /
+ * REST_SOME_POINTS, player-util.h:53-55). A DIFFERENT upstream function from
+ * hold/sleep - it calls neither search nor autopickup nor the shop-entry
+ * disturb (see holdAction's doc for the contrast).
+ *
+ * ONE CALL IS ONE GAME TURN, exactly like upstream's own do_cmd_rest: the C
+ * takes a single player_resting_step_turn and then re-queues itself with
+ * cmdq_push(CMD_REST) so process_player's do-while keeps draining it without a
+ * fresh keypress. This is the same shape as runAction's self-continuation
+ * (player-path.ts) - the command pushes its own follow-up onto
+ * state.cmdQueue, which processPlayer drains before asking the host's
+ * nextCommand for anything. A host that never pauses (a headless harness, an
+ * agent, the tests) therefore gets every turn of a whole rest inside one
+ * runGameLoop call, same as it already does for a run.
+ *
+ * disturb() (player-path.ts) is what stops the self-continuation: it deletes
+ * state.resting AND empties state.cmdQueue, so a rest interrupted mid-flight
+ * (a monster becoming visible, damage taken, the HP/SP-full check in
+ * playerRestingCompleteSpecial) simply has nothing left to pop next time
+ * process_player asks - upstream's player_rest_disturb flag achieves the same
+ * "the stale queued continuation must not fire" result with a lagging flag;
+ * this port's synchronous queue-clear needs no flag at all.
+ */
+export function restAction(state: GameState, cmd: PlayerCommand): number {
+  /* cmd_get_arg_choice returning != CMD_OK (cmd-cave.c:1624-1625): no count at
+   * all is a silent no-op, taking no turn. */
+  const arg = cmd.args?.count;
+  let n = typeof arg === "number" ? arg : NaN;
+  if (!Number.isFinite(n)) return 0;
+
+  /* "A little sanity checking on the input" (cmd-cave.c:1627-1632): only the
+   * three REST_ codes are valid negative choices. */
+  if (n < 0 && !playerRestingIsSpecial(n)) return 0;
+
+  /* Do some upkeep on the first turn of rest (cmd-cave.c:1634-1644). Checked
+   * BEFORE this call's count takes effect, exactly as upstream checks
+   * player_is_resting() before player_resting_set_count() runs. */
+  if (!playerIsResting(state)) {
+    /* player->upkeep->update |= PU_BONUS (cmd-cave.c:1636): applied eagerly
+     * here rather than deferred, matching how the rest of this port recomputes
+     * derived state through direct hook calls instead of dirty bits. */
+    state.updateBonuses?.();
+
+    if (n > 1) state.restRepeatCount = n;
+    else if (n === 1) n = state.restRepeatCount ?? 0;
+  }
+
+  /* player_resting_set_count (player-util.c:1425-1445): store the count (or
+   * cancel to the not-resting sentinel), clamped at 9999. This port represents
+   * "not resting" as state.resting being absent rather than count === 0, so a
+   * count of 0 (an explicit "0 turns", or a repeat with nothing remembered)
+   * deletes the field instead of storing a zero. */
+  if (n === 0 || (n < 0 && !playerRestingIsSpecial(n))) {
+    delete state.resting;
+  } else if (!state.resting) {
+    state.resting = { count: Math.min(n, 9999), turnsRested: 0 };
+  } else {
+    state.resting.count = Math.min(n, 9999);
+  }
+
+  /* "Set the counter, and stop if told to" (cmd-cave.c:1646-1649). */
+  if (!playerIsResting(state)) return 0;
+  const r = state.resting!;
+
+  /* player_resting_step_turn (player-util.c:1472-1489): spend the turn,
+   * decrement a timed count, bump both rested counters. */
+  if (r.count > 0) r.count--;
+  r.turnsRested++;
+  state.restingTurn = (state.restingTurn ?? 0) + 1;
+
+  /* "Prepare to continue, or cancel and clean up" (cmd-cave.c:1657-1667). `n`
+   * here is upstream's own local n: unchanged since the upkeep block above for
+   * a special rest, or the count this call was asked to do, decremented by
+   * step_turn's already-applied r.count-- for a timed one - so r.count IS
+   * upstream's `n - 1` at this point, and pushing it as the next choice is
+   * pushing exactly that. */
+  if (r.count > 0) {
+    if (!state.cmdQueue) state.cmdQueue = [];
+    state.cmdQueue.push({ code: "rest", args: { count: r.count } });
+  } else if (playerRestingIsSpecial(n)) {
+    if (!state.cmdQueue) state.cmdQueue = [];
+    state.cmdQueue.push({ code: "rest", args: { count: n } });
+    state.restRepeatCount = 0;
+  } else {
+    delete state.resting;
+  }
+
+  return state.z.moveEnergy;
+}
+
 /**
  * descend / ascend: signal a level change (player->upkeep->generate_level).
  * The generation and depth change belong to the world integration, which does
@@ -854,7 +948,7 @@ export function createDefaultRegistry(): ActionRegistry {
   reg.register("walk", walkAction);
   reg.register("jump", jumpAction);
   reg.register("hold", holdAction);
-  reg.register("rest", holdAction);
+  reg.register("rest", restAction);
   reg.register("sleep", sleepAction);
   reg.register("descend", descendAction);
   reg.register("ascend", ascendAction);

package/src/game/world.ts

@@ -59,7 +59,13 @@ import { floorPile } from "./floor.js";
 import { monsterGroupChangeIndex } from "./mon-group.js";
 import { disturb } from "./player-path.js";
 import { DEFAULT_HITPOINT_WARN } from "./project-cast.js";
-import { deleteMonster } from "./context.js";
+import {
+  REST_ALL_POINTS,
+  REST_COMPLETE,
+  REST_SOME_POINTS,
+  deleteMonster,
+  playerRestingIsSpecial,
+} from "./context.js";
 import type { GameState } from "./context.js";
 
 /** player-util.h PY_EXERT_* over-exertion bit flags. */
@@ -126,6 +132,52 @@ export function playerHasWorld(state: GameState, flag: number): boolean {
   return state.playerState?.pflags.has(flag) ?? false;
 }
 
+/**
+ * player_resting_complete_special (player-util.c:1495-1520): decide whether a
+ * conditional rest (one of the REST_ special counts) has met its own stopping
+ * condition, and disturb() to end it if so. A no-op when not resting on a
+ * special count. No RNG.
+ *
+ * Lives here rather than in context.ts (where state.resting and the REST_
+ * constants are declared) because it needs disturb() (player-path.ts) and
+ * playerHasWorld (below); context.ts cannot import either without a cycle
+ * (player-path.ts and this module both import GameState from context.ts).
+ * loop.ts calls this at the top of every process_player equivalent
+ * (game-world.c:936, immediately before EVENT_CHECK_INTERRUPT), which is
+ * upstream's own call site.
+ */
+export function playerRestingCompleteSpecial(state: GameState): void {
+  const r = state.resting;
+  if (!r || !playerRestingIsSpecial(r.count)) return;
+  const p = state.actor.player;
+  const t = p.timed;
+
+  if (r.count === REST_ALL_POINTS) {
+    if (p.chp === p.mhp && p.csp === p.msp) disturb(state);
+  } else if (r.count === REST_COMPLETE) {
+    if (
+      p.chp === p.mhp &&
+      (p.csp === p.msp || playerHasWorld(state, PF.COMBAT_REGEN)) &&
+      !(t[TMD.BLIND] ?? 0) &&
+      !(t[TMD.CONFUSED] ?? 0) &&
+      !(t[TMD.POISONED] ?? 0) &&
+      !(t[TMD.AFRAID] ?? 0) &&
+      !(t[TMD.TERROR] ?? 0) &&
+      !(t[TMD.STUN] ?? 0) &&
+      !(t[TMD.CUT] ?? 0) &&
+      !(t[TMD.SLOW] ?? 0) &&
+      !(t[TMD.PARALYZED] ?? 0) &&
+      !(t[TMD.IMAGE] ?? 0) &&
+      !p.wordRecall &&
+      !p.deepDescent
+    ) {
+      disturb(state);
+    }
+  } else if (r.count === REST_SOME_POINTS) {
+    if (p.chp === p.mhp || p.csp === p.msp) disturb(state);
+  }
+}
+
 /** state.dam_red / state.perc_dam_red from the last calc_bonuses (else zero). */
 function worldReduction(state: GameState): DamageReduction {
   const ps = state.playerState;

package/src/session/game.ts

@@ -215,6 +215,7 @@ import {
 } from "../store/transact.js";
 import type { BuyResult, SellResult, TxnKnowledge } from "../store/transact.js";
 import { storeCheckNum } from "../store/store.js";
+import { installStoreCommands } from "../store/store-cmd.js";
 import { priceItem } from "../store/price.js";
 import {
   addMonsterMessage,
@@ -3803,7 +3804,7 @@ export function startGame(pack: GamePack, opts: StartGameOptions = {}): StartedG
       changeLevel,
     ),
     wizardBundles: wired.wizardBundles,
-    ...makeStoreApi(state, reg, wired.flavor, options),
+    ...makeStoreApi(state, reg, wired.flavor, options, wired.registry),
   };
 }
 
@@ -3818,6 +3819,7 @@ function makeStoreApi(
   reg: CoreRegistries,
   flavor: FlavorKnowledge,
   options: OptionState,
+  registry: ActionRegistry,
 ): Pick<StartedGame, "buy" | "sell" | "sellFloor" | "price" | "willBuy"> {
   const storeCtx = (): StoreMaintContext => ({
     rng: state.rng,
@@ -3901,7 +3903,7 @@ function makeStoreApi(
      * stale. Unused by storeBuy, which learns flavour only. */
     learnRunes: { env: state.runeEnv, runes: buildRuneList(state.runeEnv) },
   });
-  return {
+  const storeApi: Pick<StartedGame, "buy" | "sell" | "sellFloor" | "price" | "willBuy"> = {
     buy: (store, obj, amt): BuyResult => {
       /* do_cmd_retrieve (store.c:1783): Home Take is free - no price, no
        * ORIGIN_STORE, no shuffle/maint RNG. Reuse the existing homeRetrieve. */
@@ -4055,6 +4057,12 @@ function makeStoreApi(
         state.storeBehaviour,
       ),
   };
+  /* shop-buy / shop-sell / shop-exit (docs/PLANNED.md, "An agent cannot
+   * trade"): wire the agent-facing store commands through the SAME buy/sell
+   * closures the interactive shop screen calls, so a keystroke and an
+   * agent's command reach identical pack/gold/knowledge effects. */
+  installStoreCommands(registry, { buy: storeApi.buy, sell: storeApi.sell });
+  return storeApi;
 }
 
 /**
@@ -4691,6 +4699,6 @@ export function loadGame(
       changeLevel,
     ),
     wizardBundles: wired.wizardBundles,
-    ...makeStoreApi(state, reg, wired.flavor, options),
+    ...makeStoreApi(state, reg, wired.flavor, options, wired.registry),
   };
 }