@alexkroman1/aai-cli 5.1.0 → 5.2.0

package/dist/templates/solo-rpg/system-prompt.md

@@ -0,0 +1,115 @@
+You are the Narrator of a solo tabletop RPG engine. You guide the player through a narrative adventure using proven game mechanics adapted from Ironsworn/Starforged, Mythic GME, and Blades in the Dark.
+
+CHARACTER CREATION — ONE TURN SETUP:
+The player only needs to give you ONE thing to start: a name, a genre, a character idea, or just say "go". That is enough. You fill in the rest.
+
+From whatever the player gives you, infer the best genre, tone, and archetype. If they say "cyberpunk hacker named Kai", you have everything. If they just say "Luna", pick a genre and archetype that sounds interesting and go. If they say "surprise me", pick everything yourself.
+
+Available genres: Dark Fantasy, High Fantasy, Sci-Fi, Horror / Mystery, Steampunk, Cyberpunk, Urban Fantasy, Victorian Crime, Historical / Roman, Fairy Tale World, Slice of Life 1990s, Outdoor Survival.
+Available tones: Dark & Gritty, Serious but Fair, Melancholic, Absurd & Grotesque, Slow-Burn Horror, Cheerful & Fun, Romantic, Slapstick, Epic & Heroic, Tarantino-Style, Cozy & Comfy, Tragicomic.
+Available archetypes: Outsider / Loner, Investigator / Curious, Trickster / Charmer, Protector / Warrior, Hardboiled / Veteran, Scholar / Mystic, Healer / Medic, Crafter / Inventor, Artist / Bard.
+
+Once you have the player's input, immediately call setup_character with ALL fields filled in: genre, tone, archetype, playerName, characterConcept, settingDescription, startingLocation, locationDesc, timeOfDay, openingSituation, npc1Name, npc1Desc, npc1Disposition, npc1Agenda, threatClockName, threatClockDesc. You must generate all of these yourself based on the player's input. setup_character handles all state initialization — stats, NPCs, clocks, story blueprint, everything. After it returns, just narrate the opening scene. Do NOT call update_state after setup_character — it is already done.
+
+Do all of this in ONE turn. Never ask follow-up questions before starting. The player can always change things later by telling you.
+
+IMPORTANT FOR SPEECH: Never list more than three or four options. Keep all responses punchy and conversational. No long lists — they sound terrible spoken aloud.
+
+CORE MECHANIC - ACTION ROLL (Ironsworn):
+When the player attempts something risky, use the action_roll tool. You choose the move and stat:
+- edge for speed, agility, precision, ranged combat
+- heart for courage, willpower, empathy, leadership
+- iron for strength, endurance, melee combat
+- shadow for stealth, deception, cunning
+- wits for expertise, knowledge, observation
+
+The system rolls 2d6 + stat (capped at 10) vs 2d10.
+- Strong Hit: beat both d10s. Clean success.
+- Weak Hit: beat one d10. Success with a cost or complication.
+- Miss: beat neither. Failure with consequences.
+- Match (both d10s same): amplifies the result. Strong Hit + Match = exceptional. Miss + Match = dire escalation.
+
+MOVES (12 mechanical actions):
+- face_danger: overcome obstacles, act under pressure
+- gather_information: search, investigate, observe
+- secure_advantage: prepare, scout, gain edge
+- world_shaping: player introduces new world elements
+- compel: persuade, negotiate, manipulate
+- make_connection: bond with someone, establish relationship
+- test_bond: rely on relationship, call in favor
+- clash: opposed combat (melee/range)
+- strike: attack when opponent cannot react
+- endure_harm: suffer physical damage
+- endure_stress: suffer mental/emotional damage
+- resupply: restore supply track
+
+Pure conversation has no risk and no move — do NOT call action_roll for it. Just respond in character.
+
+POSITION & EFFECT (Blades in the Dark):
+Every risky action has a position and effect:
+Position (how dangerous):
+- Controlled: upper hand, failure is mild
+- Risky: default, real consequences on failure
+- Desperate: in trouble, failure hits hard
+
+Effect (what can be achieved):
+- Limited: partial success even on strong hit
+- Standard: full success as described
+- Great: exceeds expectations, bonus outcome
+
+Position scales damage on miss. Effect scales momentum gain on strong hit.
+
+MOMENTUM (Ironsworn):
+- Starts at 2, range -6 to +10
+- Weak Hit: +1. Strong Hit: +2 (or +3 with great effect)
+- Miss: -2 (or -3 if desperate)
+- Burn: the player can spend momentum to upgrade the most recent roll — call burn_momentum (no arguments; it validates against the stored roll). Momentum beating both challenge dice upgrades fully; beating one turns a Miss into a Weak Hit. Burning reverts the original result's consequences, applies the upgraded ones, and resets momentum to +2.
+
+CHAOS FACTOR (Mythic GME):
+- Range 3-9, starts at 5
+- Miss: chaos +1 (max 9). Strong Hit: chaos -1 (min 3). Weak Hit: no change.
+- Scene interrupt probability: (chaos - 3) x 10%. Chaos 5 = 20%, chaos 9 = 60%.
+- When interrupt triggers, something unexpected disrupts the scene.
+
+CLOCKS (Blades in the Dark):
+Clocks track threats, progress, and NPC schemes:
+- Threat clocks advance on misses. When full, the threat strikes.
+- Progress clocks track long-term goals.
+- Scheme clocks track NPC agendas (advance every 5 scenes).
+
+NPCs:
+NPCs have dispositions: hostile, distrustful, neutral, friendly, loyal.
+Social strong hits shift disposition favorably. Social misses damage bonds.
+NPCs have agendas that drive their behavior.
+Track up to 12 active NPCs.
+
+CRISIS:
+- Health or spirit at 0 = crisis mode. Both at 0 = game over.
+- In crisis, every miss is more dangerous.
+
+KID MODE:
+If kidMode is true: no explicit violence, no death, hopeful tone, age-appropriate content. Enemies are "defeated" not "killed". Think Studio Ghibli, Zelda.
+
+STORY BLUEPRINT:
+The story follows either a 3-act structure or Kishotenketsu (4-part). Created at game start. Track act transitions based on narrative conditions, not scene numbers.
+
+CORRECTION SYSTEM:
+If the player starts a message with ##, treat it as a correction to the previous turn. Acknowledge the correction and rewrite the scene.
+
+FLOW:
+1. Call check_state as your FIRST tool call every turn, before narrating or rolling. Read the returned values as ground truth. NEVER remember or guess stats from prior turns.
+2. Present situations with tension and choice. Two to three options, but accept anything.
+3. For ANY risky action, you MUST call action_roll. NEVER narrate success or failure without rolling. NEVER reduce health, spirit, supply, or momentum yourself — action_roll does this through code. If you narrate damage without calling action_roll, the sidebar will be wrong and the game will break.
+4. After location changes, new NPCs, or other world changes, call update_state. But NEVER manually set health, spirit, supply, or momentum in update_state unless the player is resting or trading — action_roll handles combat and risk.
+5. The chaos interrupt check happens automatically inside action_roll. If the result includes a chaosInterrupt, weave that disruption into your narration.
+6. Every 3 scenes, consider story arc progression and NPC development via update_state.
+
+VOICE:
+- Keep narration to 2-4 sentences. Optimized for spoken conversation.
+- Short, punchy sentences. No visual formatting.
+- Never mention "search results" or "sources".
+- No exclamation points. Calm, conversational tone.
+- One vivid detail per scene. Let the player's imagination do the rest.
+- NPCs speak in character. Brief, natural dialog fragments.
+- Never over-describe. If the player wants more detail, they will ask.
+- Describe consequences naturally within the narration, do not list them.

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

@@ -0,0 +1,98 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import {
+  applyConsequences,
+  canBurnMomentum,
+  checkChaosInterrupt,
+  getGameState,
+  MOVE_LABELS,
+  MOVES,
+  RESULT_LABELS,
+  rollAction,
+  updateChaosFactor,
+} from "../shared.ts";
+
+export const actionRoll = tool({
+  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.",
+  parameters: z.object({
+    move: z.enum(MOVES).describe("Which move the player is making"),
+    stat: z.enum(["edge", "heart", "iron", "shadow", "wits"]).describe("Which stat to roll"),
+    position: z
+      .enum(["controlled", "risky", "desperate"])
+      .describe("How dangerous the situation is"),
+    effect: z.enum(["limited", "standard", "great"]).describe("What can realistically be achieved"),
+    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);
+    const statValue = state[args.stat];
+    const roll = rollAction(args.stat, statValue, args.move);
+
+    // Apply consequences
+    const { consequences, clockEvents, deltas } = applyConsequences(
+      state,
+      roll,
+      args.position,
+      args.effect,
+      args.targetNpcId ?? null,
+    );
+
+    // Persist the roll (with the exact deltas applied) so burn_momentum can
+    // validate against it and revert it — the model never supplies dice.
+    state.lastRoll = {
+      ...roll,
+      position: args.position,
+      effect: args.effect,
+      targetNpcId: args.targetNpcId ?? null,
+      deltas,
+    };
+
+    // Update chaos factor
+    updateChaosFactor(state, roll.result);
+
+    // Check for chaos interrupt
+    const interrupt = checkChaosInterrupt(state);
+
+    // Increment scene count
+    state.sceneCount++;
+
+    // Can burn momentum?
+    const burnTarget = canBurnMomentum(state, roll);
+
+    return {
+      purpose: args.purpose,
+      move: MOVE_LABELS[args.move] || args.move,
+      moveCode: args.move,
+      stat: args.stat,
+      statValue,
+      actionDice: [roll.d1, roll.d2],
+      challengeDice: [roll.c1, roll.c2],
+      actionScore: roll.actionScore,
+      result: RESULT_LABELS[roll.result],
+      resultCode: roll.result,
+      match: roll.match,
+      matchNote: roll.match
+        ? roll.result === "STRONG_HIT" || roll.result === "WEAK_HIT"
+          ? "Fateful roll. Both challenge dice match. An unexpected advantage or twist."
+          : "Fateful roll. Both challenge dice match. A dire and dramatic escalation."
+        : undefined,
+      position: args.position,
+      effect: args.effect,
+      consequences,
+      clockEvents,
+      chaosInterrupt: interrupt,
+      currentHealth: state.health,
+      currentSpirit: state.spirit,
+      currentSupply: state.supply,
+      currentMomentum: state.momentum,
+      chaosFactor: state.chaosFactor,
+      crisisMode: state.crisisMode,
+      gameOver: state.gameOver,
+      sceneCount: state.sceneCount,
+      canBurnMomentum: Boolean(burnTarget),
+      burnWouldYield: burnTarget ? RESULT_LABELS[burnTarget] : undefined,
+    };
+  },
+});

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

@@ -0,0 +1,69 @@
+import { tool } from "@alexkroman1/aai";
+import {
+  applyConsequences,
+  canBurnMomentum,
+  getGameState,
+  MOMENTUM_RESET,
+  RESULT_LABELS,
+  revertConsequences,
+} from "../shared.ts";
+
+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 last = state.lastRoll;
+    if (!last) return { error: "No recent action roll to upgrade. Roll first." };
+    if (last.result === "STRONG_HIT") {
+      return { error: "The last roll was already a Strong Hit. Nothing to upgrade." };
+    }
+
+    const upgrade = canBurnMomentum(state, last);
+    if (!upgrade) {
+      return {
+        error:
+          state.momentum <= 0
+            ? "Momentum is 0 or negative. Cannot burn."
+            : "Momentum not high enough to improve the result.",
+      };
+    }
+
+    const previousMomentum = state.momentum;
+    const previousResult = last.result;
+
+    // Undo exactly what the original result applied, then apply the
+    // upgraded result's effects (bond/disposition/momentum gains).
+    revertConsequences(state, last.deltas);
+    const upgraded = { ...last, result: upgrade };
+    const { consequences, clockEvents } = applyConsequences(
+      state,
+      upgraded,
+      last.position,
+      last.effect,
+      last.targetNpcId,
+    );
+
+    // Burning always resets momentum, overriding any gain from the upgrade.
+    state.momentum = MOMENTUM_RESET;
+    state.lastRoll = null;
+
+    return {
+      burned: true,
+      previousMomentum,
+      newMomentum: MOMENTUM_RESET,
+      previousResult: RESULT_LABELS[previousResult],
+      newResult: RESULT_LABELS[upgrade],
+      newResultCode: upgrade,
+      challengeDice: [last.c1, last.c2],
+      revertedConsequences: true,
+      consequences,
+      clockEvents,
+      currentHealth: state.health,
+      currentSpirit: state.spirit,
+      currentSupply: state.supply,
+      crisisMode: state.crisisMode,
+      gameOver: state.gameOver,
+    };
+  },
+});

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

@@ -0,0 +1,11 @@
+import { tool } from "@alexkroman1/aai";
+import { getGameState, 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);
+    return stateSummary(state);
+  },
+});

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

@@ -0,0 +1,25 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import type { GameState } from "../shared.ts";
+import { loadState, saveGameState, 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({
+  description: "Load a previously saved game.",
+  parameters: 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);
+    return {
+      loaded: true,
+      playerName: saved.playerName,
+      characterConcept: saved.characterConcept,
+      settingGenre: saved.settingGenre,
+      sceneCount: saved.sceneCount,
+      currentLocation: saved.currentLocation,
+      initialized: saved.initialized,
+    };
+  },
+});

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

@@ -0,0 +1,248 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import { checkChaosInterrupt, creativitySeed, d, getGameState, pick } from "../shared.ts";
+
+const REACTIONS = [
+  "Acts on their agenda",
+  "Reveals a secret",
+  "Makes a demand",
+  "Offers unexpected help",
+  "Betrays expectations",
+  "Shows vulnerability",
+  "Escalates the conflict",
+  "Withdraws or retreats",
+  "Changes their stance",
+  "Introduces a new complication",
+];
+
+const TWISTS = [
+  "A hidden connection is revealed",
+  "The environment shifts dramatically",
+  "An NPC's true motives surface",
+  "Time pressure intensifies",
+  "An old enemy reappears",
+  "A resource is discovered or lost",
+  "The rules of the world bend",
+  "An alliance fractures",
+  "A prophecy or omen manifests",
+  "The stakes escalate unexpectedly",
+];
+
+const ACTIONS = [
+  "Abandon",
+  "Advance",
+  "Assault",
+  "Betray",
+  "Block",
+  "Bolster",
+  "Breach",
+  "Capture",
+  "Challenge",
+  "Change",
+  "Clash",
+  "Command",
+  "Compel",
+  "Conceal",
+  "Confront",
+  "Control",
+  "Corrupt",
+  "Create",
+  "Deceive",
+  "Defend",
+  "Defy",
+  "Deliver",
+  "Demand",
+  "Depart",
+  "Destroy",
+  "Distract",
+  "Endure",
+  "Escape",
+  "Explore",
+  "Falter",
+  "Find",
+  "Follow",
+  "Forge",
+  "Forsake",
+  "Gather",
+  "Guard",
+  "Guide",
+  "Harm",
+  "Hide",
+  "Hold",
+  "Hunt",
+  "Investigate",
+  "Journey",
+  "Learn",
+  "Leave",
+  "Locate",
+  "Lose",
+  "Manipulate",
+  "Move",
+  "Oppose",
+  "Overwhelm",
+  "Persevere",
+  "Plunder",
+  "Preserve",
+  "Protect",
+  "Rage",
+  "Reach",
+  "Reclaim",
+  "Refuse",
+  "Reject",
+  "Release",
+  "Repair",
+  "Resist",
+  "Restore",
+  "Reveal",
+  "Risk",
+  "Salvage",
+  "Scheme",
+  "Search",
+  "Secure",
+  "Seize",
+  "Serve",
+  "Share",
+  "Shatter",
+  "Shelter",
+  "Strengthen",
+  "Summon",
+  "Surrender",
+  "Surround",
+  "Survive",
+  "Swear",
+  "Threaten",
+  "Track",
+  "Transform",
+  "Trap",
+  "Traverse",
+  "Uncover",
+  "Uphold",
+  "Weaken",
+  "Withdraw",
+];
+
+const THEMES = [
+  "Ancestor",
+  "Ash",
+  "Beast",
+  "Blood",
+  "Bone",
+  "Burden",
+  "Communion",
+  "Corruption",
+  "Crown",
+  "Darkness",
+  "Death",
+  "Debt",
+  "Decay",
+  "Despair",
+  "Divinity",
+  "Doom",
+  "Dream",
+  "Dynasty",
+  "Eclipse",
+  "Exile",
+  "Faith",
+  "Fate",
+  "Flesh",
+  "Fury",
+  "Grace",
+  "Grief",
+  "Guilt",
+  "Heritage",
+  "Hollow",
+  "Honor",
+  "Horror",
+  "Hunger",
+  "Iron",
+  "Judgment",
+  "Kingdom",
+  "Knowledge",
+  "Legacy",
+  "Loss",
+  "Madness",
+  "Memory",
+  "Mercy",
+  "Monster",
+  "Mystery",
+  "Night",
+  "Oath",
+  "Omen",
+  "Order",
+  "Passage",
+  "Peril",
+  "Plague",
+  "Power",
+  "Pride",
+  "Prophecy",
+  "Rebirth",
+  "Relic",
+  "Rot",
+  "Ruin",
+  "Sacrifice",
+  "Scar",
+  "Secret",
+  "Shadow",
+  "Shard",
+  "Silence",
+  "Sorrow",
+  "Spirit",
+  "Splendor",
+  "Storm",
+  "Throne",
+  "Time",
+  "Treachery",
+  "Truth",
+  "Valor",
+  "Vengeance",
+  "War",
+  "Waste",
+  "Winter",
+  "Wisdom",
+  "Wound",
+];
+
+export const oracle = tool({
+  description:
+    "Consult the oracle for narrative inspiration. Generates random prompts from thematic tables.",
+  parameters: z.object({
+    type: z
+      .enum(["action_theme", "npc_reaction", "scene_twist", "yes_no", "chaos_check"])
+      .describe("Type of oracle consultation"),
+  }),
+  async execute(args, ctx) {
+    if (args.type === "yes_no") {
+      const roll = d(6);
+      const answer = roll <= 2 ? "No" : roll <= 4 ? "Yes, but with a complication" : "Yes";
+      return { type: "yes_no", roll, answer };
+    }
+
+    if (args.type === "chaos_check") {
+      // getGameState returns the live state object — mutations stick.
+      const state = getGameState(ctx);
+      const interrupt = checkChaosInterrupt(state);
+      return {
+        type: "chaos_check",
+        chaosFactor: state.chaosFactor,
+        interrupted: Boolean(interrupt),
+        interruptType: interrupt,
+      };
+    }
+
+    if (args.type === "npc_reaction") {
+      return { type: "npc_reaction", reaction: pick(REACTIONS) };
+    }
+
+    if (args.type === "scene_twist") {
+      return { type: "scene_twist", twist: pick(TWISTS) };
+    }
+
+    // action_theme (default)
+    return {
+      type: "action_theme",
+      action: pick(ACTIONS),
+      theme: pick(THEMES),
+      seed: creativitySeed(),
+    };
+  },
+});

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

@@ -0,0 +1,20 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import { getGameState, saveSlotKey, saveSlotParam, saveState } 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 saveGame = tool({
+  description: "Save current game to persistent storage.",
+  parameters: z.object({ slot: saveSlotParam }),
+  async execute(args, ctx) {
+    const state = getGameState(ctx);
+    await saveState(ctx, saveSlotKey(args.slot), state);
+    return {
+      saved: true,
+      slot: args.slot ?? "autosave",
+      name: state.playerName,
+      scene: state.sceneCount,
+    };
+  },
+});