@alexkroman1/aai-cli 6.11.0 → 8.0.0

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

@@ -1,17 +1,26 @@
 import { z } from "zod";
-import { gameSlot, saveSlotKey, saveSlotParam, saveState } from "../shared.ts";
+import { gameSlot, saveSlotKey, saveSlotParam, saveState, storyFlow } from "../shared.ts";
 
 // Requires storage — `aai storage enable` (or DATABASE_URL in .env under
 // `aai dev`); the rest of the game works without it.
 //
-// `gameSlot.tool` even though the body AWAITS: the reading half places no
-// constraint on the body (only `updateTool` must be synchronous, because its
-// draft is stored when it returns). What it does place is the frozen value, and
-// a save is the purest read there is.
-export default gameSlot.tool({
+/**
+ * Gated on `playing` or `gameOver` — i.e. anything but `awaitingSetup`.
+ *
+ * Saving before a character exists writes an empty campaign under a slot name,
+ * and `load_game` would then cheerfully restore it over a real game. That is a
+ * position, so it is a `when`.
+ *
+ * The body AWAITS, which a flow tool allows: only `slot.updateTool` must be
+ * synchronous, because its draft is stored when it returns. What a save needs is
+ * the frozen value, and `gameSlot.get` is what hands it over.
+ */
+export default storyFlow.tool({
   description: "Save current game to persistent storage.",
   inputSchema: z.object({ slot: saveSlotParam }),
-  async execute(args, game, ctx) {
+  when: ["playing", "gameOver"],
+  async execute(args, ctx) {
+    const game = gameSlot.get(ctx);
     await saveState(ctx, saveSlotKey(args.slot), game);
     return {
       saved: true,

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

@@ -14,10 +14,24 @@ import {
   makeNpc,
   shuffle,
   stateSummary,
+  storyFlow,
   TIME_PHASES,
   TONES,
 } from "../shared.ts";
 
+/**
+ * **Not a `storyFlow.tool`, deliberately.** Setting up is legal in every state —
+ * a player may start over at any point, an ended story included — so a `when`
+ * listing all of them would be a gate that gates nothing. It drives the flow
+ * itself, which is what `dialog.reset` and `dialog.send` are public for, and reports
+ * the position it landed in so the narrator reads what the opening turn expects.
+ *
+ * **`reset` before `send`, because a restart is not a transition.** This body
+ * replaces the campaign with a pristine `DEFAULT_STATE`; resetting the flow is
+ * the same statement on the other side, and it is what makes starting over work
+ * from `gameOver` — a final state delivers no events, so a `SETUP` transition
+ * out of it would be dead config.
+ */
 export default tool({
   description:
     "Set up the entire game in one call. Starts a completely fresh game (any previous unsaved game is replaced), generates stats, initializes state, and marks the game as ready. After this returns, just narrate the opening scene. No need to call update_state — everything is already done.",
@@ -186,12 +200,16 @@ export default tool({
       storyComplete: false,
     };
 
-    // Mark initialized
+    // Mark initialized. `initialized` is the CLIENT's render flag; the flow is
+    // what gates the tools, and `SETUP` is what puts it in `playing` — so the
+    // roll tools become available in the same call that gives them stats to
+    // roll against.
     state.initialized = true;
-    state.phase = "playing";
     state.sceneCount = 1;
 
     gameSlot.set(ctx, state);
+    storyFlow.reset(ctx);
+    const at = storyFlow.send(ctx, { type: "SETUP" });
 
     return {
       success: true,
@@ -201,6 +219,8 @@ export default tool({
       archetypeLabel: ARCHETYPES[args.archetype as keyof typeof ARCHETYPES] || args.archetype,
       openingSituation: args.openingSituation,
       creativitySeed: creativitySeed(),
+      // The position spread verbatim — the same keys every gated tool reports.
+      ...at,
       // The real saved state — never hardcoded values
       ...stateSummary(state),
     };

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

@@ -15,13 +15,23 @@ import {
   makeNpc,
   nextSeqId,
   stateSummary,
+  storyFlow,
   TIME_PHASES,
-  updateCrisisFlags,
 } from "../shared.ts";
 
-export default gameSlot.updateTool({
+/**
+ * Gated on `playing`: there is nothing to sync before a character exists (that
+ * is `setup_character`'s whole job, and the prompt says not to call this after
+ * it), and nothing to sync after the story has ended.
+ *
+ * It sends `SETTLED`, because moving the scene on is what SPENDS a standing
+ * roll: once the narrator has changed the location or logged the scene, the
+ * player's window to burn momentum on the last roll has closed.
+ */
+export default storyFlow.tool({
   description:
     "Lightweight state sync for during gameplay. Handles location changes, NPC additions, clock additions, time changes, and session log entries. Resource changes (health/spirit/supply/momentum) are auto-applied by action_roll — only use those fields here for manual adjustments like resting or trading. Pass only what changed.",
+  when: "playing",
   inputSchema: z.object({
     location: z.string().max(200).describe("New location name").optional(),
     locationDesc: z.string().max(500).describe("Short location description").optional(),
@@ -54,117 +64,120 @@ export default gameSlot.updateTool({
     storyComplete: z.boolean().describe("Mark story as complete").optional(),
     logEntry: z.string().max(500).describe("Short log entry for this scene").optional(),
   }),
-  execute(args, state) {
-    const warnings: string[] = [];
-    const clockEvents: { clock: string; trigger: string }[] = [];
+  execute: (args, ctx) =>
+    gameSlot.update(ctx, (state) => {
+      const warnings: string[] = [];
+      const clockEvents: { clock: string; trigger: string }[] = [];
 
-    // Resources
-    if (args.health !== undefined) state.health = Math.max(0, Math.min(MAX_RESOURCE, args.health));
-    if (args.spirit !== undefined) state.spirit = Math.max(0, Math.min(MAX_RESOURCE, args.spirit));
-    if (args.supply !== undefined) state.supply = Math.max(0, Math.min(MAX_RESOURCE, args.supply));
-    if (args.momentum !== undefined)
-      state.momentum = Math.max(MIN_MOMENTUM, Math.min(state.maxMomentum, args.momentum));
+      // Resources
+      if (args.health !== undefined)
+        state.health = Math.max(0, Math.min(MAX_RESOURCE, args.health));
+      if (args.spirit !== undefined)
+        state.spirit = Math.max(0, Math.min(MAX_RESOURCE, args.spirit));
+      if (args.supply !== undefined)
+        state.supply = Math.max(0, Math.min(MAX_RESOURCE, args.supply));
+      if (args.momentum !== undefined)
+        state.momentum = Math.max(MIN_MOMENTUM, Math.min(state.maxMomentum, args.momentum));
 
-    // Location
-    if (args.location !== undefined) state.currentLocation = args.location;
-    if (args.locationDesc !== undefined) state.currentSceneContext = args.locationDesc;
-    if (args.timeOfDay !== undefined) state.timeOfDay = args.timeOfDay;
+      // Location
+      if (args.location !== undefined) state.currentLocation = args.location;
+      if (args.locationDesc !== undefined) state.currentSceneContext = args.locationDesc;
+      if (args.timeOfDay !== undefined) state.timeOfDay = args.timeOfDay;
 
-    // Add NPC
-    if (args.addNpcName) {
-      if (state.npcs.length >= MAX_NPCS) {
-        warnings.push(
-          `NPC limit of ${MAX_NPCS} reached — mark an existing NPC deceased or background instead.`,
-        );
-      } else {
-        state.npcs.push(
-          makeNpc({
-            id: nextSeqId(state.npcs, "npc"),
-            name: args.addNpcName,
-            description: args.addNpcDesc,
-            disposition: args.addNpcDisposition,
-            agenda: args.addNpcAgenda,
-          }),
-        );
+      // Add NPC
+      if (args.addNpcName) {
+        if (state.npcs.length >= MAX_NPCS) {
+          warnings.push(
+            `NPC limit of ${MAX_NPCS} reached — mark an existing NPC deceased or background instead.`,
+          );
+        } else {
+          state.npcs.push(
+            makeNpc({
+              id: nextSeqId(state.npcs, "npc"),
+              name: args.addNpcName,
+              description: args.addNpcDesc,
+              disposition: args.addNpcDisposition,
+              agenda: args.addNpcAgenda,
+            }),
+          );
+        }
       }
-    }
 
-    // Update NPC
-    if (args.updateNpcId) {
-      const npc = state.npcs.find((n) => n.id === args.updateNpcId);
-      if (npc) {
-        if (args.updateNpcDisposition !== undefined) npc.disposition = args.updateNpcDisposition;
-        if (args.updateNpcBond !== undefined) npc.bond = args.updateNpcBond;
-        if (args.updateNpcStatus !== undefined) npc.status = args.updateNpcStatus;
-      } else {
-        warnings.push(`No NPC with id ${args.updateNpcId}.`);
+      // Update NPC
+      if (args.updateNpcId) {
+        const npc = state.npcs.find((n) => n.id === args.updateNpcId);
+        if (npc) {
+          if (args.updateNpcDisposition !== undefined) npc.disposition = args.updateNpcDisposition;
+          if (args.updateNpcBond !== undefined) npc.bond = args.updateNpcBond;
+          if (args.updateNpcStatus !== undefined) npc.status = args.updateNpcStatus;
+        } else {
+          warnings.push(`No NPC with id ${args.updateNpcId}.`);
+        }
       }
-    }
 
-    // Add clock
-    if (args.addClockName) {
-      if (state.clocks.length >= MAX_CLOCKS) {
-        warnings.push(`Clock limit of ${MAX_CLOCKS} reached — remove a finished clock first.`);
-      } else {
-        state.clocks.push({
-          id: nextSeqId(state.clocks, "clock"),
-          name: args.addClockName,
-          clockType: args.addClockType ?? "threat",
-          segments: args.addClockSegments ?? DEFAULT_CLOCK_SEGMENTS,
-          filled: 0,
-          triggerDescription: args.addClockTrigger ?? "",
-        });
+      // Add clock
+      if (args.addClockName) {
+        if (state.clocks.length >= MAX_CLOCKS) {
+          warnings.push(`Clock limit of ${MAX_CLOCKS} reached — remove a finished clock first.`);
+        } else {
+          state.clocks.push({
+            id: nextSeqId(state.clocks, "clock"),
+            name: args.addClockName,
+            clockType: args.addClockType ?? "threat",
+            segments: args.addClockSegments ?? DEFAULT_CLOCK_SEGMENTS,
+            filled: 0,
+            triggerDescription: args.addClockTrigger ?? "",
+          });
+        }
       }
-    }
 
-    // Advance clock
-    if (args.advanceClockName) {
-      const clock = state.clocks.find((c) => c.name === args.advanceClockName);
-      if (clock && clock.filled < clock.segments) {
-        clock.filled = Math.min(clock.segments, clock.filled + 1);
-        if (clock.filled >= clock.segments) {
-          clockEvents.push({ clock: clock.name, trigger: clock.triggerDescription });
+      // Advance clock
+      if (args.advanceClockName) {
+        const clock = state.clocks.find((c) => c.name === args.advanceClockName);
+        if (clock && clock.filled < clock.segments) {
+          clock.filled = Math.min(clock.segments, clock.filled + 1);
+          if (clock.filled >= clock.segments) {
+            clockEvents.push({ clock: clock.name, trigger: clock.triggerDescription });
+          }
         }
       }
-    }
-
-    // Remove clock
-    if (args.removeClockName) {
-      state.clocks = state.clocks.filter((c) => c.name !== args.removeClockName);
-    }
 
-    // Story arc
-    if (args.advanceAct && state.storyBlueprint) {
-      state.storyBlueprint.currentAct = Math.min(
-        state.storyBlueprint.acts.length,
-        state.storyBlueprint.currentAct + 1,
-      );
-    }
-    if (args.storyComplete && state.storyBlueprint) {
-      state.storyBlueprint.storyComplete = true;
-    }
+      // Remove clock
+      if (args.removeClockName) {
+        state.clocks = state.clocks.filter((c) => c.name !== args.removeClockName);
+      }
 
-    // Session log
-    if (args.logEntry) {
-      pushCapped(
-        state.sessionLog,
-        {
-          scene: state.sceneCount,
-          summary: args.logEntry,
-          location: state.currentLocation,
-        },
-        MAX_SESSION_LOG,
-      );
-    }
+      // Story arc
+      if (args.advanceAct && state.storyBlueprint) {
+        state.storyBlueprint.currentAct = Math.min(
+          state.storyBlueprint.acts.length,
+          state.storyBlueprint.currentAct + 1,
+        );
+      }
+      if (args.storyComplete && state.storyBlueprint) {
+        state.storyBlueprint.storyComplete = true;
+      }
 
-    // Crisis check
-    updateCrisisFlags(state);
+      // Session log
+      if (args.logEntry) {
+        pushCapped(
+          state.sessionLog,
+          {
+            scene: state.sceneCount,
+            summary: args.logEntry,
+            location: state.currentLocation,
+          },
+          MAX_SESSION_LOG,
+        );
+      }
 
-    return {
-      success: true,
-      ...(warnings.length > 0 ? { warnings } : {}),
-      clockEvents,
-      ...stateSummary(state),
-    };
-  },
+      return {
+        success: true,
+        ...(warnings.length > 0 ? { warnings } : {}),
+        clockEvents,
+        ...stateSummary(state),
+      };
+    }),
+  sendFrom: (result) =>
+    result.gameOver ? { type: "DOWNED" as const } : { type: "SETTLED" as const },
 });