@alexkroman1/aai-cli 5.13.2 → 6.1.0

package/dist/templates/solo-rpg/agent.test.ts

@@ -1,23 +1,24 @@
 import type { Db, ToolContext } from "@alexkroman1/aai";
+import { createToolContext } from "@alexkroman1/aai/testing";
 import { describe, expect, test, vi } from "vitest";
 import {
   applyConsequences,
   DEFAULT_STATE,
   type GameState,
-  getGameState,
+  gameSlot,
   MAX_NPCS,
   MIN_MOMENTUM,
   makeNpc,
   rollAction,
-  saveGameState,
 } from "./shared.ts";
-import { actionRoll } from "./tools/action_roll.ts";
-import { burnMomentum } from "./tools/burn_momentum.ts";
-import { checkState } from "./tools/check_state.ts";
-import { loadGame } from "./tools/load_game.ts";
-import { saveGame } from "./tools/save_game.ts";
-import { setupCharacter } from "./tools/setup_character.ts";
-import { updateState } from "./tools/update_state.ts";
+import actionRoll from "./tools/action_roll.ts";
+import burnMomentum from "./tools/burn_momentum.ts";
+import checkState from "./tools/check_state.ts";
+import loadGame from "./tools/load_game.ts";
+import oracle from "./tools/oracle.ts";
+import saveGame from "./tools/save_game.ts";
+import setupCharacter from "./tools/setup_character.ts";
+import updateState from "./tools/update_state.ts";
 
 // ── Test doubles ─────────────────────────────────────────────────────────────
 
@@ -46,19 +47,11 @@ function makeDb(): { db: Db; rows: Map<string, unknown> } {
   return { db, rows };
 }
 
-function makeCtx(sessionId = "session-a", db: Db = makeDb().db): ToolContext {
-  return {
-    env: {},
-    state: {},
-    db,
-    generate: () => Promise.reject(new Error("generate not available in tests")),
-    messages: [],
-    sessionId,
-    // Never aborts — a test has no turn to cancel. `ctx.signal` is always
-    // present at runtime, so a stub supplies one rather than omitting it.
-    signal: new AbortController().signal,
-    send: vi.fn(),
-  };
+/** `send` is a spy rather than the recorder `createToolContext` installs,
+ *  because this suite asserts call counts on it. Each call gets its own slot
+ *  store, which is what makes two contexts two games. */
+function makeCtx(db: Db = makeDb().db): ToolContext {
+  return createToolContext({ db, send: vi.fn() });
 }
 
 const SETUP_ARGS = {
@@ -106,19 +99,19 @@ describe("setup_character", () => {
     await setupCharacter.execute(SETUP_ARGS, ctx);
 
     // Simulate a played, damaged game between setups.
-    const played = getGameState(ctx);
-    played.health = 1;
-    played.momentum = -4;
-    played.chaosFactor = 8;
-    played.sceneCount = 42;
-    saveGameState(ctx, played);
+    gameSlot.update(ctx, (played) => {
+      played.health = 1;
+      played.momentum = -4;
+      played.chaosFactor = 8;
+      played.sceneCount = 42;
+    });
 
     const result = (await setupCharacter.execute(
       { ...SETUP_ARGS, playerName: "Luna" },
       ctx,
     )) as Record<string, unknown>;
 
-    const state = getGameState(ctx);
+    const state = gameSlot.get(ctx);
     expect(state.npcs).toHaveLength(1);
     expect(state.npcs[0]?.id).toBe("npc_1");
     expect(state.clocks).toHaveLength(1);
@@ -140,17 +133,21 @@ describe("setup_character", () => {
   test("stats are a permutation of [3,2,2,1,1] with the archetype's stat at 3", async () => {
     const ctx = makeCtx();
     await setupCharacter.execute(SETUP_ARGS, ctx);
-    const state = getGameState(ctx);
+    const state = gameSlot.get(ctx);
     const stats = [state.edge, state.heart, state.iron, state.shadow, state.wits];
     expect([...stats].sort()).toEqual([1, 1, 2, 2, 3]);
     // investigator biases wits (index 4) to the high stat
     expect(state.wits).toBe(3);
   });
 
-  test("game state is scoped per session — a second session sees a fresh game", async () => {
-    await setupCharacter.execute(SETUP_ARGS, makeCtx("session-a"));
-    // ctx.state is per-session by construction — a new session, a new game.
-    const other = (await checkState.execute({} as never, makeCtx("session-b"))) as {
+  test("a second, independent context sees a fresh game", async () => {
+    // What this really checks: the state lives in the SLOT and not in a
+    // module-level variable. `createToolContext()` hands each call its own
+    // detached slot store, so the isolation is per CONTEXT — two distinct
+    // session ids would prove nothing extra, and `sessionSlot` could stop
+    // keying by session with this still passing.
+    await setupCharacter.execute(SETUP_ARGS, makeCtx());
+    const other = (await checkState.execute({} as never, makeCtx())) as {
       initialized: boolean;
     };
     expect(other.initialized).toBe(false);
@@ -267,7 +264,7 @@ describe("burn_momentum", () => {
         clockTicks: 1,
       },
     };
-    saveGameState(ctx, state);
+    gameSlot.set(ctx, state);
   }
 
   test("a legal burn reverts the miss's consequences, upgrades, and resets momentum", async () => {
@@ -278,7 +275,7 @@ describe("burn_momentum", () => {
     expect(result.burned).toBe(true);
     expect(result.newResultCode).toBe("STRONG_HIT");
 
-    const state = getGameState(ctx);
+    const state = gameSlot.get(ctx);
     expect(state.health).toBe(5); // -2 reverted
     expect(state.clocks[0]?.filled).toBe(0); // tick reverted
     expect(state.momentum).toBe(2); // reset, overriding the strong hit's gain
@@ -306,21 +303,21 @@ describe("burn_momentum", () => {
 
     // Strong hits cannot be upgraded
     seedRolledState(8, ctx);
-    const state = getGameState(ctx);
-    state.lastRoll!.result = "STRONG_HIT";
-    saveGameState(ctx, state);
+    gameSlot.update(ctx, (state) => {
+      state.lastRoll!.result = "STRONG_HIT";
+    });
     result = (await burnMomentum.execute({} as never, ctx)) as Record<string, unknown>;
     expect(result.error).toMatch(/already a Strong Hit/);
   });
 
   test("action_roll persists the roll so burn needs no dice arguments", async () => {
     const ctx = makeCtx();
-    saveGameState(ctx, playingState());
+    gameSlot.set(ctx, playingState());
     await actionRoll.execute(
       { move: "clash", stat: "iron", position: "risky", effect: "standard", purpose: "attack" },
       ctx,
     );
-    const state = getGameState(ctx);
+    const state = gameSlot.get(ctx);
     expect(state.lastRoll).not.toBeNull();
     expect(state.lastRoll?.move).toBe("clash");
     expect(state.lastRoll?.deltas).toBeDefined();
@@ -367,18 +364,134 @@ describe("rollAction", () => {
   });
 });
 
+// ── oracle ───────────────────────────────────────────────────────────────────
+//
+// `chaos_check` is the one oracle branch that WRITES: `checkChaosInterrupt`
+// lowers the chaos factor when the roll lands. It used to read the slot with
+// `gameSlot.get` and assign to what came back, under a comment claiming the
+// value was live — which described the removed `ctx.state` bag, not a slot. The
+// stored value is deep-frozen, so ~1 call in 5 at the default chaos factor (and
+// ~6 in 10 as it climbs) threw a `TypeError` instead of answering. These
+// assertions are on the STORED value for that reason: a body writing to a
+// private copy would pass every check on its own return value.
+
+describe("oracle", () => {
+  /** Force `d(sides)` to roll `value` on the next call. */
+  function mockRoll(value: number, sides: number) {
+    return vi.spyOn(Math, "random").mockReturnValue((value - 0.5) / sides);
+  }
+
+  test("a chaos interrupt that LANDS lowers the stored chaos factor", async () => {
+    const ctx = makeCtx();
+    const state = playingState();
+    state.chaosFactor = 9; // threshold 6 — a roll of 1 lands
+    gameSlot.set(ctx, state);
+    mockRoll(1, 10);
+
+    const result = (await oracle.execute({ type: "chaos_check" }, ctx)) as {
+      interrupted: boolean;
+      interruptType: string | null;
+      chaosFactor: number;
+    };
+
+    expect(result.interrupted).toBe(true);
+    expect(result.interruptType).toBeTruthy();
+    expect(result.chaosFactor).toBe(8);
+    // The half the old code could not do: the write reached the slot.
+    expect(gameSlot.get(ctx).chaosFactor).toBe(8);
+  });
+
+  test("the chaos factor floors at 3, where no roll is taken at all", async () => {
+    const ctx = makeCtx();
+    const state = playingState();
+    state.chaosFactor = 3; // threshold 0 — `checkChaosInterrupt` returns early
+    gameSlot.set(ctx, state);
+
+    const result = (await oracle.execute({ type: "chaos_check" }, ctx)) as {
+      interrupted: boolean;
+      chaosFactor: number;
+    };
+    expect(result.interrupted).toBe(false);
+    expect(gameSlot.get(ctx).chaosFactor).toBe(3);
+  });
+
+  test("a chaos check that MISSES changes nothing", async () => {
+    const ctx = makeCtx();
+    const state = playingState();
+    state.chaosFactor = 5; // threshold 2
+    gameSlot.set(ctx, state);
+    mockRoll(10, 10); // past the threshold
+
+    const result = (await oracle.execute({ type: "chaos_check" }, ctx)) as {
+      interrupted: boolean;
+      chaosFactor: number;
+    };
+    expect(result.interrupted).toBe(false);
+    expect(result.chaosFactor).toBe(5);
+    expect(gameSlot.get(ctx).chaosFactor).toBe(5);
+  });
+
+  test("a chaos check on an untouched session starts from the default factor", async () => {
+    const ctx = makeCtx();
+    mockRoll(1, 10); // DEFAULT_STATE.chaosFactor is 5, so threshold 2 — lands
+    const result = (await oracle.execute({ type: "chaos_check" }, ctx)) as { chaosFactor: number };
+    expect(result.chaosFactor).toBe(DEFAULT_STATE.chaosFactor - 1);
+    expect(gameSlot.get(ctx).chaosFactor).toBe(DEFAULT_STATE.chaosFactor - 1);
+  });
+
+  test("yes_no maps the d6 onto its three answers", async () => {
+    const ctx = makeCtx();
+    for (const [roll, answer] of [
+      [1, "No"],
+      [2, "No"],
+      [3, "Yes, but with a complication"],
+      [4, "Yes, but with a complication"],
+      [5, "Yes"],
+      [6, "Yes"],
+    ] as const) {
+      mockRoll(roll, 6);
+      const result = (await oracle.execute({ type: "yes_no" }, ctx)) as {
+        roll: number;
+        answer: string;
+      };
+      expect.soft(result, `roll ${roll}`).toEqual({ type: "yes_no", roll, answer });
+    }
+  });
+
+  test("the four inspiration branches answer without touching the game", async () => {
+    const ctx = makeCtx();
+    gameSlot.set(ctx, playingState());
+    const before = structuredClone(gameSlot.get(ctx));
+
+    const reaction = (await oracle.execute({ type: "npc_reaction" }, ctx)) as { reaction: string };
+    const twist = (await oracle.execute({ type: "scene_twist" }, ctx)) as { twist: string };
+    const theme = (await oracle.execute({ type: "action_theme" }, ctx)) as {
+      action: string;
+      theme: string;
+      seed: string;
+    };
+
+    expect(reaction.reaction).toBeTruthy();
+    expect(twist.twist).toBeTruthy();
+    expect(theme.action).toBeTruthy();
+    expect(theme.theme).toBeTruthy();
+    expect(theme.seed.split(" ")).toHaveLength(3);
+    expect(gameSlot.get(ctx)).toEqual(before);
+  });
+});
+
 // ── update_state: clocks, caps, validation ───────────────────────────────────
 
 describe("update_state", () => {
   test("clock ids never collide after a removal (max-scan, not length+1)", async () => {
     const ctx = makeCtx();
-    saveGameState(ctx, playingState()); // has clock_1
+    gameSlot.set(ctx, playingState()); // has clock_1
 
     await updateState.execute({ addClockName: "Second" }, ctx); // clock_2
     await updateState.execute({ removeClockName: "Doom" }, ctx); // removes clock_1
     await updateState.execute({ addClockName: "Third" }, ctx);
 
-    const state = getGameState(ctx);
+    const state = gameSlot.get(ctx);
     const ids = state.clocks.map((c) => c.id);
     expect(new Set(ids).size).toBe(ids.length);
     expect(ids).toEqual(["clock_2", "clock_3"]);
@@ -388,7 +501,7 @@ describe("update_state", () => {
     const ctx = makeCtx();
     const state = playingState();
     state.clocks[0]!.filled = 3; // 3 of 4
-    saveGameState(ctx, state);
+    gameSlot.set(ctx, state);
 
     const result = (await updateState.execute({ advanceClockName: "Doom" }, ctx)) as {
       clockEvents: { clock: string; trigger: string }[];
@@ -402,13 +515,13 @@ describe("update_state", () => {
     while (state.npcs.length < MAX_NPCS) {
       state.npcs.push(makeNpc({ id: `npc_${state.npcs.length + 1}`, name: "Extra" }));
     }
-    saveGameState(ctx, state);
+    gameSlot.set(ctx, state);
 
     const result = (await updateState.execute({ addNpcName: "One Too Many" }, ctx)) as {
       warnings?: string[];
     };
     expect(result.warnings?.[0]).toMatch(/NPC limit/);
-    const after = getGameState(ctx);
+    const after = gameSlot.get(ctx);
     expect(after.npcs).toHaveLength(MAX_NPCS);
   });
 
@@ -438,11 +551,11 @@ describe("save_game / load_game", () => {
     const { db, rows } = makeDb();
 
     // Session A plays and saves.
-    const sessionA = makeCtx("session-a", db);
+    const sessionA = makeCtx(db);
     const played = playingState();
     played.playerName = "Kael";
     played.sceneCount = 7;
-    saveGameState(sessionA, played);
+    gameSlot.set(sessionA, played);
     const saved = (await saveGame.execute({ slot: "chapter-2" }, sessionA)) as Record<
       string,
       unknown
@@ -451,8 +564,8 @@ describe("save_game / load_game", () => {
     expect(saved.slot).toBe("chapter-2");
     expect(rows.get("save:chapter-2")).toMatchObject({ playerName: "Kael", sceneCount: 7 });
 
-    // Session B (fresh ctx.state, same app db) resumes it.
-    const sessionB = makeCtx("session-b", db);
+    // Session B (a fresh game slot, the same app db) resumes it.
+    const sessionB = makeCtx(db);
     const loaded = (await loadGame.execute({ slot: "chapter-2" }, sessionB)) as Record<
       string,
       unknown
@@ -460,7 +573,7 @@ describe("save_game / load_game", () => {
     expect(loaded.loaded).toBe(true);
     expect(loaded.playerName).toBe("Kael");
     expect(loaded.sceneCount).toBe(7);
-    expect(getGameState(sessionB).playerName).toBe("Kael");
+    expect(gameSlot.get(sessionB).playerName).toBe("Kael");
   });
 
   test("loading a missing slot reports an error instead of resetting the game", async () => {
@@ -471,10 +584,12 @@ describe("save_game / load_game", () => {
 
   test("saving twice to one slot upserts — the newer save wins", async () => {
     const { db, rows } = makeDb();
-    const ctx = makeCtx("session-a", db);
-    saveGameState(ctx, playingState());
+    const ctx = makeCtx(db);
+    gameSlot.set(ctx, playingState());
     await saveGame.execute({}, ctx); // autosave
-    getGameState(ctx).sceneCount = 9;
+    gameSlot.update(ctx, (game) => {
+      game.sceneCount = 9;
+    });
     await saveGame.execute({}, ctx);
     expect(rows.size).toBe(1);
     expect(rows.get("save:autosave")).toMatchObject({ sceneCount: 9 });

package/dist/templates/solo-rpg/agent.ts

@@ -1,18 +1,8 @@
 import { agent } from "@alexkroman1/aai";
-import { DEFAULT_STATE, type StateSlot } from "./shared.ts";
-import systemPrompt from "./system-prompt.md?raw";
-import { actionRoll } from "./tools/action_roll.ts";
-import { burnMomentum } from "./tools/burn_momentum.ts";
-import { checkState } from "./tools/check_state.ts";
-import { loadGame } from "./tools/load_game.ts";
-import { oracle } from "./tools/oracle.ts";
-import { saveGame } from "./tools/save_game.ts";
-import { setupCharacter } from "./tools/setup_character.ts";
-import { updateState } from "./tools/update_state.ts";
+import { gameSlot } from "./shared.ts";
 
 export default agent({
   name: "Solo RPG",
-  systemPrompt,
   greeting:
     "Welcome. Tell me your name, or describe the kind of story you want, and we will begin. You can say something like, dark fantasy warrior named Kael, or just give me a name and I will build a world around you.",
   sttPrompt:
@@ -22,15 +12,7 @@ export default agent({
   // One declaration replaces a `ctx.send("game_state", state)` in every
   // state-mutating tool — six of them, and adding a seventh meant
   // remembering to push or watching the UI quietly fall out of sync.
-  syncState: (s: StateSlot) => s.game ?? DEFAULT_STATE,
-  tools: {
-    action_roll: actionRoll,
-    burn_momentum: burnMomentum,
-    check_state: checkState,
-    load_game: loadGame,
-    oracle,
-    save_game: saveGame,
-    setup_character: setupCharacter,
-    update_state: updateState,
-  },
+  // The identity projection: this campaign IS what the client renders, and the
+  // slot's own default is what a session that has run no tool projects.
+  syncState: gameSlot.projection((game) => game),
 });

package/dist/templates/solo-rpg/client.tsx

@@ -1,12 +1,13 @@
 import "@alexkroman1/aai-ui/styles.css";
+import type { DeepReadonly } from "@alexkroman1/aai";
 import { ChatView, client, SidebarLayout, StartScreen, useAgentState } from "@alexkroman1/aai-ui";
 import type { ReactNode } from "react";
 import {
   type Clock,
-  DEFAULT_STATE,
   type Disposition,
   type GameState,
   GENRES,
+  gameSlot,
   MAX_RESOURCE,
   MIN_MOMENTUM,
   type NPC,
@@ -14,6 +15,18 @@ import {
   type TIME_PHASES,
 } from "./shared.ts";
 
+// The campaign before the first tool call, derived from the SAME projection the
+// server pushes rather than from the module default beside it — so a session
+// that has run no tool renders exactly what its first push will replace. Every
+// sibling template derives its fallback this way; this one read `DEFAULT_STATE`
+// directly, which is a second copy of "what an untouched session looks like".
+//
+// It is typed READONLY because that is what the projection produces, and a
+// client only ever renders what the server pushed — so the four components
+// below take a readonly campaign too, which is the deep-readonly slot
+// propagating exactly as far as it should.
+const EMPTY_GAME = gameSlot.projection((game) => game)(undefined);
+
 // ── Color Palette ────────────────────────────────────────────────────────────
 const C = {
   bg: "#0a0a0c",
@@ -290,7 +303,7 @@ function StatPip({ label, value }: { label: string; value: number }) {
   );
 }
 
-function ClockDisplay({ clock }: { clock: Clock }) {
+function ClockDisplay({ clock }: { clock: DeepReadonly<Clock> }) {
   const typeColor =
     clock.clockType === "threat"
       ? C.threat
@@ -355,7 +368,7 @@ function ClockDisplay({ clock }: { clock: Clock }) {
   );
 }
 
-function NpcCard({ npc }: { npc: NPC }) {
+function NpcCard({ npc }: { npc: DeepReadonly<NPC> }) {
   const dispColor = C.disposition[npc.disposition] || C.textMuted;
   const icon = DISP_ICON[npc.disposition] || "\u25CB";
   return (
@@ -390,7 +403,7 @@ function NpcCard({ npc }: { npc: NPC }) {
   );
 }
 
-function StoryArc({ story }: { story: StoryBlueprint }) {
+function StoryArc({ story }: { story: DeepReadonly<StoryBlueprint> }) {
   const totalActs = story.acts.length;
   const currentPhase = story.acts[story.currentAct - 1]?.phase ?? "";
   const pct = totalActs > 0 ? ((story.currentAct - 1) / totalActs) * 100 : 0;
@@ -443,7 +456,7 @@ function StoryArc({ story }: { story: StoryBlueprint }) {
 
 // ── Sidebar ──────────────────────────────────────────────────────────────────
 
-function Sidebar({ game }: { game: GameState }) {
+function Sidebar({ game }: { game: DeepReadonly<GameState> }) {
   return (
     <div
       style={{
@@ -771,7 +784,7 @@ function SoloRPGApp() {
   // The agent's own session state, projected by `syncState` and pushed after
   // every tool call — no per-tool `ctx.send`, and nothing to keep in step
   // when a new tool starts mutating the game.
-  const game = useAgentState<GameState>() ?? DEFAULT_STATE;
+  const game = useAgentState<DeepReadonly<GameState>>(EMPTY_GAME);
 
   return (
     <StartScreen

package/dist/templates/solo-rpg/shared.ts

@@ -1,4 +1,4 @@
-import type { ToolContext } from "@alexkroman1/aai";
+import { type DeepReadonly, sessionSlot, type ToolContext } from "@alexkroman1/aai";
 import { z } from "zod";
 
 // ── Tuning Constants ─────────────────────────────────────────────────────────
@@ -320,24 +320,24 @@ export const DEFAULT_STATE: GameState = {
   kidMode: false,
 };
 
-// ── Live game state (ctx.state) ─────────────────────────────────────────────
-// The in-play game lives in `ctx.state`, the agent's per-session mutable
-// state — concurrent players get independent games by construction, and the
-// live game needs no persistence of its own (that's what save slots are for).
-export type StateSlot = { game?: GameState };
+// ── Live game state (one session slot) ───────────────────────────────────────
+// The in-play game lives in one `sessionSlot`, keyed per session — concurrent
+// players get independent games by construction. The clone is load-bearing:
+// `DEFAULT_STATE` is one module-level object shared by every session in the
+// process, so a factory without it would let one player's game show up in
+// another's.
+export const gameSlot = sessionSlot("game", () => structuredClone(DEFAULT_STATE));
 
-/** The session's live game. Mutations to the returned object stick — it is
- *  the object stored in `ctx.state`. */
-export function getGameState(ctx: ToolContext): GameState {
-  const slot = ctx.state as StateSlot;
-  slot.game ??= structuredClone(DEFAULT_STATE);
-  return slot.game;
-}
-
-/** Replace the session's live game wholesale (setup, load). */
-export function saveGameState(ctx: ToolContext, state: GameState): void {
-  (ctx.state as StateSlot).game = state;
-}
+/**
+ * The game as a READ hands it out: deep-frozen, and typed to say so.
+ *
+ * Every pure helper below takes this rather than {@link GameState}, which is
+ * the widening a deep-readonly slot forces and the reason it is worth doing:
+ * a mutable `GameState` still satisfies it, so a helper called with an
+ * `updateTool` draft is unaffected, while a helper that WOULD have mutated
+ * stops compiling instead of throwing at its first call in production.
+ */
+export type FrozenGameState = DeepReadonly<GameState>;
 
 // ── Persistent save slots (ctx.db) ───────────────────────────────────────────
 // save_game / load_game are genuine cross-session persistence, so they use
@@ -441,7 +441,7 @@ export function makeNpc(opts: {
   };
 }
 
-export function clockSummary(c: Clock) {
+export function clockSummary(c: DeepReadonly<Clock>) {
   return {
     id: c.id,
     name: c.name,
@@ -458,7 +458,7 @@ export function clockSummary(c: Clock) {
  * setup_character, update_state, and check_state. Includes the player's
  * content boundaries (contentLines) so they survive past the setup turn.
  */
-export function stateSummary(state: GameState) {
+export function stateSummary(state: FrozenGameState) {
   return {
     initialized: state.initialized,
     phase: state.phase,

package/dist/templates/solo-rpg/tools/action_roll.ts

@@ -1,10 +1,9 @@
-import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import {
   applyConsequences,
   canBurnMomentum,
   checkChaosInterrupt,
-  getGameState,
+  gameSlot,
   MOVE_LABELS,
   MOVES,
   RESULT_LABELS,
@@ -12,7 +11,7 @@ import {
   updateChaosFactor,
 } from "../shared.ts";
 
-export const actionRoll = tool({
+export default gameSlot.updateTool({
   description:
     "Core mechanic. Roll 2d6 + stat (capped at 10) vs 2d10 challenge dice. Also applies consequences (health/spirit/supply/momentum changes, clock advancement) based on move type, position, and result. Call for ANY risky action. Pure conversation needs no roll.",
   inputSchema: z.object({
@@ -25,8 +24,7 @@ export const actionRoll = tool({
     purpose: z.string().max(300).describe("What the character is attempting"),
     targetNpcId: z.string().max(32).describe("Target NPC id for social moves").optional(),
   }),
-  async execute(args, ctx) {
-    const state = getGameState(ctx);
+  execute(args, state) {
     const statValue = state[args.stat];
     const roll = rollAction(args.stat, statValue, args.move);
 

package/dist/templates/solo-rpg/tools/burn_momentum.ts

@@ -1,18 +1,16 @@
-import { tool } from "@alexkroman1/aai";
 import {
   applyConsequences,
   canBurnMomentum,
-  getGameState,
+  gameSlot,
   MOMENTUM_RESET,
   RESULT_LABELS,
   revertConsequences,
 } from "../shared.ts";
 
-export const burnMomentum = tool({
+export default gameSlot.updateTool({
   description:
     "Burn momentum to upgrade the most recent action roll. Only valid when current momentum beats the roll's challenge dice (both dice for a full upgrade, one for Miss to Weak Hit). Reverts the original result's consequences, applies the upgraded result, and resets momentum to +2.",
-  async execute(_args, ctx) {
-    const state = getGameState(ctx);
+  execute(_args, state) {
     const last = state.lastRoll;
     if (!last) return { error: "No recent action roll to upgrade. Roll first." };
     if (last.result === "STRONG_HIT") {

package/dist/templates/solo-rpg/tools/check_state.ts

@@ -1,11 +1,11 @@
-import { tool } from "@alexkroman1/aai";
-import { getGameState, stateSummary } from "../shared.ts";
+import { gameSlot, stateSummary } from "../shared.ts";
 
-export const checkState = tool({
+// `gameSlot.tool`, the READING half: the body is handed the value, so it needs
+// neither a context annotation nor an opening `gameSlot.get(ctx)` — and what it
+// is handed is deep-frozen, which is what makes "this tool only reads" a
+// property of the declaration rather than a claim in a comment.
+export default gameSlot.tool({
   description:
     "Returns the full current game state. Call this at the start of every turn, before narrating or rolling, and treat the returned values as ground truth — never guess or remember stats from previous turns.",
-  async execute(_args, ctx) {
-    const state = getGameState(ctx);
-    return stateSummary(state);
-  },
+  execute: (_args, game) => stateSummary(game),
 });

package/dist/templates/solo-rpg/tools/load_game.ts

@@ -1,17 +1,17 @@
 import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import type { GameState } from "../shared.ts";
-import { loadState, saveGameState, saveSlotKey, saveSlotParam } from "../shared.ts";
+import { gameSlot, loadState, saveSlotKey, saveSlotParam } from "../shared.ts";
 
 // Requires storage — `aai storage enable` (or DATABASE_URL in .env under
 // `aai dev`); the rest of the game works without it.
-export const loadGame = tool({
+export default tool({
   description: "Load a previously saved game.",
   inputSchema: z.object({ slot: saveSlotParam }),
   async execute(args, ctx) {
     const saved = await loadState<GameState>(ctx, saveSlotKey(args.slot));
     if (!saved) return { error: "No save found." };
-    saveGameState(ctx, saved);
+    gameSlot.set(ctx, saved);
     return {
       loaded: true,
       playerName: saved.playerName,