@alexkroman1/aai-cli 5.13.2 → 5.14.0

package/dist/templates/retail/tools/exchange_delivered_order_items.ts

@@ -1,6 +1,7 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { resolveOrder } from "../resolve.ts";
-import { authenticatedUser, getState, isError, retailTool, setFocus } from "../store.ts";
+import { authenticatedUser, retailSlot, retailTool, setFocus } from "../store.ts";
 import { assertCanCoverDiff, planItemSwap } from "../swap.ts";
 
 export const exchangeDeliveredOrderItems = retailTool({
@@ -34,12 +35,12 @@ export const exchangeDeliveredOrderItems = retailTool({
   // source order — with `summary` first, `result` in its signature can't be
   // inferred and silently falls back to `unknown`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
 
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
 
     if (order.status !== "delivered") {
@@ -53,7 +54,7 @@ export const exchangeDeliveredOrderItems = retailTool({
     const plan = planItemSwap(state, order, args.item_ids, args.new_item_ids, {
       requireDifferent: false,
     });
-    if (isError(plan)) return plan;
+    if (isToolFailure(plan)) return plan;
 
     const blocked = assertCanCoverDiff(user, args.payment_method_id, plan.diff);
     if (blocked) return blocked;

package/dist/templates/retail/tools/find_user_id_by_email.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { authenticateAs } from "../authenticate.ts";
-import { getState, retailTool } from "../store.ts";
+import { retailSlot, retailTool } from "../store.ts";
 
 export const findUserIdByEmail = retailTool({
   name: "find_user_id_by_email",
@@ -17,7 +17,7 @@ export const findUserIdByEmail = retailTool({
   // literal properties in source order — with `summary` first, `result` in its
   // signature can't be inferred and silently falls back to `unknown`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const target = args.email.trim().toLowerCase();
     const match = Object.values(state.store.users).find(
       (user) => user.email.toLowerCase() === target,

package/dist/templates/retail/tools/find_user_id_by_name_zip.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { authenticateAs } from "../authenticate.ts";
-import { getState, retailTool } from "../store.ts";
+import { retailSlot, retailTool } from "../store.ts";
 
 export const findUserIdByNameZip = retailTool({
   name: "find_user_id_by_name_zip",
@@ -16,7 +16,7 @@ export const findUserIdByNameZip = retailTool({
   // `execute` before `summary`: see find_user_id_by_email.ts for why the order
   // is load-bearing for the generic `result` type in `summary`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const first = args.first_name.trim().toLowerCase();
     const last = args.last_name.trim().toLowerCase();
     const zip = args.zip.replace(/\D/g, "");

package/dist/templates/retail/tools/get_item_details.ts

@@ -1,5 +1,6 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { findItem, getState, isError, retailTool } from "../store.ts";
+import { findItem, retailSlot, retailTool } from "../store.ts";
 
 export const getItemDetails = retailTool({
   name: "get_item_details",
@@ -13,8 +14,8 @@ export const getItemDetails = retailTool({
   // `execute` before `summary`: see find_user_id_by_email.ts for why the order
   // is load-bearing for the generic `result` type in `summary`.
   execute: (args, ctx) => {
-    const found = findItem(getState(ctx), args.item_id);
-    if (isError(found)) return found;
+    const found = findItem(retailSlot.get(ctx), args.item_id);
+    if (isToolFailure(found)) return found;
     return {
       item_id: found.variant.item_id,
       product_id: found.product.product_id,

package/dist/templates/retail/tools/get_order_details.ts

@@ -1,6 +1,7 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { resolveOrder } from "../resolve.ts";
-import { getState, isError, retailTool, setFocus } from "../store.ts";
+import { retailSlot, retailTool, setFocus } from "../store.ts";
 
 export const getOrderDetails = retailTool({
   name: "get_order_details",
@@ -17,9 +18,9 @@ export const getOrderDetails = retailTool({
   // `execute` before `summary`: see find_user_id_by_email.ts for why the order
   // is load-bearing for the generic `result` type in `summary`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
     return {
       order_id: order.order_id,

package/dist/templates/retail/tools/get_product_details.ts

@@ -1,5 +1,6 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { findProduct, getState, isError, retailTool, setFocus } from "../store.ts";
+import { findProduct, retailSlot, retailTool, setFocus } from "../store.ts";
 
 export const getProductDetails = retailTool({
   name: "get_product_details",
@@ -13,9 +14,9 @@ export const getProductDetails = retailTool({
   // `execute` before `summary`: see find_user_id_by_email.ts for why the order
   // is load-bearing for the generic `result` type in `summary`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const product = findProduct(state, args.product_id);
-    if (isError(product)) return product;
+    if (isToolFailure(product)) return product;
     setFocus(state, { productId: product.product_id });
     return {
       name: product.name,

package/dist/templates/retail/tools/get_user_details.ts

@@ -1,5 +1,6 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { authenticatedUser, getState, isError, retailTool } from "../store.ts";
+import { authenticatedUser, retailSlot, retailTool } from "../store.ts";
 
 export const getUserDetails = retailTool({
   name: "get_user_details",
@@ -12,9 +13,9 @@ export const getUserDetails = retailTool({
   // `execute` before `summary`: see find_user_id_by_email.ts for why the order
   // is load-bearing for the generic `result` type in `summary`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
     if (user.user_id !== args.user_id) {
       return {
         error: `${args.user_id} is not the customer on this call. You can help only one customer per conversation.`,

package/dist/templates/retail/tools/list_all_product_types.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { getState, retailTool } from "../store.ts";
+import { retailSlot, retailTool } from "../store.ts";
 
 export const listAllProductTypes = retailTool({
   name: "list_all_product_types",
@@ -13,7 +13,7 @@ export const listAllProductTypes = retailTool({
   // `execute` before `summary`: see find_user_id_by_email.ts for why the order
   // is load-bearing for the generic `result` type in `summary`.
   execute: (_args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const entries = Object.values(state.store.products)
       .map((product) => [product.name, product.product_id] as const)
       .sort(([a], [b]) => a.localeCompare(b));

package/dist/templates/retail/tools/modify_pending_order_address.ts

@@ -1,7 +1,8 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { AddressFields, formatAddress, toAddress } from "../address.ts";
 import { resolveOrder } from "../resolve.ts";
-import { getState, isError, retailTool, setFocus } from "../store.ts";
+import { retailSlot, retailTool, setFocus } from "../store.ts";
 
 export const modifyPendingOrderAddress = retailTool({
   name: "modify_pending_order_address",
@@ -20,9 +21,9 @@ export const modifyPendingOrderAddress = retailTool({
   // source order — with `summary` first, `result` in its signature can't be
   // inferred and silently falls back to `unknown`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
 
     // Any pending variant is fine here — unlike cancel and modify-items, which

package/dist/templates/retail/tools/modify_pending_order_items.ts

@@ -1,11 +1,11 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { resolveOrder } from "../resolve.ts";
 import {
   authenticatedUser,
-  getState,
-  isError,
   isGiftCard,
   money,
+  retailSlot,
   retailTool,
   setFocus,
 } from "../store.ts";
@@ -42,12 +42,12 @@ export const modifyPendingOrderItems = retailTool({
   // source order — with `summary` first, `result` in its signature can't be
   // inferred and silently falls back to `unknown`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
 
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
 
     // Exactly 'pending'. A 'pending (item modified)' order has already used its
@@ -61,7 +61,7 @@ export const modifyPendingOrderItems = retailTool({
     const plan = planItemSwap(state, order, args.item_ids, args.new_item_ids, {
       requireDifferent: true,
     });
-    if (isError(plan)) return plan;
+    if (isToolFailure(plan)) return plan;
 
     const blocked = assertCanCoverDiff(user, args.payment_method_id, plan.diff);
     if (blocked) return blocked;

package/dist/templates/retail/tools/modify_pending_order_payment.ts

@@ -1,12 +1,12 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { resolveOrder } from "../resolve.ts";
 import {
   authenticatedUser,
   findPaymentMethod,
-  getState,
-  isError,
   isGiftCard,
   money,
+  retailSlot,
   retailTool,
   setFocus,
 } from "../store.ts";
@@ -32,12 +32,12 @@ export const modifyPendingOrderPayment = retailTool({
   // source order — with `summary` first, `result` in its signature can't be
   // inferred and silently falls back to `unknown`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
 
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
 
     if (!order.status.startsWith("pending")) {
@@ -47,7 +47,7 @@ export const modifyPendingOrderPayment = retailTool({
     }
 
     const newMethod = findPaymentMethod(user, args.payment_method_id);
-    if (isError(newMethod)) return newMethod;
+    if (isToolFailure(newMethod)) return newMethod;
 
     const original = order.payment_history[0];
     if (order.payment_history.length !== 1 || original?.transaction_type !== "payment") {

package/dist/templates/retail/tools/modify_user_address.ts

@@ -1,6 +1,7 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { AddressFields, formatAddress, toAddress } from "../address.ts";
-import { authenticatedUser, getState, isError, retailTool } from "../store.ts";
+import { authenticatedUser, retailSlot, retailTool } from "../store.ts";
 
 export const modifyUserAddress = retailTool({
   name: "modify_user_address",
@@ -17,9 +18,9 @@ export const modifyUserAddress = retailTool({
   // source order — with `summary` first, `result` in its signature can't be
   // inferred and silently falls back to `unknown`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
     if (user.user_id !== args.user_id) {
       return {
         error: `${args.user_id} is not the customer on this call. You can help only one customer per conversation.`,

package/dist/templates/retail/tools/return_delivered_order_items.ts

@@ -1,11 +1,11 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { resolveOrder } from "../resolve.ts";
 import {
   authenticatedUser,
   findPaymentMethod,
-  getState,
-  isError,
   isGiftCard,
+  retailSlot,
   retailTool,
   setFocus,
 } from "../store.ts";
@@ -37,12 +37,12 @@ export const returnDeliveredOrderItems = retailTool({
   // source order — with `summary` first, `result` in its signature can't be
   // inferred and silently falls back to `unknown`.
   execute: (args, ctx) => {
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
 
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
 
     if (order.status !== "delivered") {
@@ -52,7 +52,7 @@ export const returnDeliveredOrderItems = retailTool({
     }
 
     const method = findPaymentMethod(user, args.payment_method_id);
-    if (isError(method)) return method;
+    if (isToolFailure(method)) return method;
 
     const originalMethodId = order.payment_history[0]?.payment_method_id;
     if (!isGiftCard(method) && args.payment_method_id !== originalMethodId) {

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

@@ -1,15 +1,16 @@
 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,
+  type StateSlot,
 } from "./shared.ts";
 import { actionRoll } from "./tools/action_roll.ts";
 import { burnMomentum } from "./tools/burn_momentum.ts";
@@ -46,19 +47,10 @@ 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. */
+function makeCtx(sessionId = "session-a", db: Db = makeDb().db): ToolContext<StateSlot> {
+  return createToolContext<StateSlot>({ sessionId, db, send: vi.fn() });
 }
 
 const SETUP_ARGS = {
@@ -106,19 +98,19 @@ describe("setup_character", () => {
     await setupCharacter.execute(SETUP_ARGS, ctx);
 
     // Simulate a played, damaged game between setups.
-    const played = getGameState(ctx);
+    const played = gameSlot.get(ctx);
     played.health = 1;
     played.momentum = -4;
     played.chaosFactor = 8;
     played.sceneCount = 42;
-    saveGameState(ctx, played);
+    gameSlot.set(ctx, played);
 
     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,7 +132,7 @@ 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
@@ -267,7 +259,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 +270,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 +298,21 @@ describe("burn_momentum", () => {
 
     // Strong hits cannot be upgraded
     seedRolledState(8, ctx);
-    const state = getGameState(ctx);
+    const state = gameSlot.get(ctx);
     state.lastRoll!.result = "STRONG_HIT";
-    saveGameState(ctx, state);
+    gameSlot.set(ctx, state);
     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();
@@ -372,13 +364,13 @@ describe("rollAction", () => {
 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 +380,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 +394,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);
   });
 
@@ -442,7 +434,7 @@ describe("save_game / load_game", () => {
     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
@@ -460,7 +452,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 () => {
@@ -472,9 +464,9 @@ 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());
+    gameSlot.set(ctx, playingState());
     await saveGame.execute({}, ctx); // autosave
-    getGameState(ctx).sceneCount = 9;
+    gameSlot.get(ctx).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,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { DEFAULT_STATE, type StateSlot } from "./shared.ts";
+import { gameSlot } from "./shared.ts";
 import systemPrompt from "./system-prompt.md?raw";
 import { actionRoll } from "./tools/action_roll.ts";
 import { burnMomentum } from "./tools/burn_momentum.ts";
@@ -22,7 +22,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,
+  syncState: gameSlot.read,
   tools: {
     action_roll: actionRoll,
     burn_momentum: burnMomentum,

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

@@ -771,7 +771,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<GameState>(DEFAULT_STATE);
 
   return (
     <StartScreen

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

@@ -1,4 +1,4 @@
-import type { ToolContext } from "@alexkroman1/aai";
+import { type SlotStateOf, sessionSlot, type ToolContext } from "@alexkroman1/aai";
 import { z } from "zod";
 
 // ── Tuning Constants ─────────────────────────────────────────────────────────
@@ -324,20 +324,12 @@ export const DEFAULT_STATE: GameState = {
 // 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 };
+// The clone is load-bearing: `DEFAULT_STATE` is one module-level object shared
+// by every session in the process, so a mutation 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;
-}
+export type StateSlot = SlotStateOf<typeof gameSlot>;
 
 // ── Persistent save slots (ctx.db) ───────────────────────────────────────────
 // save_game / load_game are genuine cross-session persistence, so they use

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

@@ -4,7 +4,7 @@ import {
   applyConsequences,
   canBurnMomentum,
   checkChaosInterrupt,
-  getGameState,
+  gameSlot,
   MOVE_LABELS,
   MOVES,
   RESULT_LABELS,
@@ -26,7 +26,7 @@ export const actionRoll = tool({
     targetNpcId: z.string().max(32).describe("Target NPC id for social moves").optional(),
   }),
   async execute(args, ctx) {
-    const state = getGameState(ctx);
+    const state = gameSlot.get(ctx);
     const statValue = state[args.stat];
     const roll = rollAction(args.stat, statValue, args.move);
 

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

@@ -2,7 +2,7 @@ import { tool } from "@alexkroman1/aai";
 import {
   applyConsequences,
   canBurnMomentum,
-  getGameState,
+  gameSlot,
   MOMENTUM_RESET,
   RESULT_LABELS,
   revertConsequences,
@@ -12,7 +12,7 @@ export const burnMomentum = tool({
   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);
+    const state = gameSlot.get(ctx);
     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({
   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);
+    const state = gameSlot.get(ctx);
     return stateSummary(state);
   },
 });

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

@@ -1,7 +1,7 @@
 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.
@@ -11,7 +11,7 @@ export const loadGame = tool({
   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,