@umang-boss/claudemon 1.3.0 → 1.4.1

package/dist/src/hooks/award-xp.js

@@ -4,6 +4,8 @@
  *
  * Loads state, awards XP to the active Pokemon, applies stat boosts,
  * increments the event counter, updates the streak, and saves.
+ * Supports enhanced encounter triggers: streak bonuses, time-of-day bias,
+ * bonus encounters (10%), and tool diversity encounters.
  * Emits a terminal bell on level-up.
  */
 import { BELL } from "../engine/constants.js";
@@ -12,7 +14,9 @@ import { addXp, createXpEvent } from "../engine/xp.js";
 import { applyStatBoost } from "../engine/stats.js";
 import { POKEMON_BY_ID } from "../engine/pokemon-data.js";
 import { checkEvolution, getNewlyEarnedBadges } from "../engine/evolution.js";
-import { shouldTriggerEncounter, generateEncounter } from "../engine/encounters.js";
+import { shouldTriggerEncounter, generateEncounter, shouldBonusEncounter, shouldDiversityBonus, getTimeOfDayBias, } from "../engine/encounters.js";
+import { calculateMood } from "../engine/mood.js";
+const MAX_RECENT_TOOL_TYPES = 20;
 const eventType = process.argv[2];
 const counterKey = process.argv[3];
 if (!eventType) {
@@ -40,12 +44,34 @@ const levelUp = addXp(pokemon, xpEvent.xp, pokemonData);
 if (xpEvent.statBoost && xpEvent.boostAmount > 0) {
     applyStatBoost(pokemon, xpEvent.statBoost, xpEvent.boostAmount);
 }
+// XP sharing: give inactive party members a percentage
+const sharePercent = state.config.xpSharePercent ?? 0;
+if (sharePercent > 0 && state.party.length > 1) {
+    const sharedXp = Math.floor((xpEvent.xp * sharePercent) / 100);
+    if (sharedXp > 0) {
+        for (const member of state.party) {
+            if (member.isActive)
+                continue;
+            const memberSpecies = POKEMON_BY_ID.get(member.pokemonId);
+            if (memberSpecies) {
+                addXp(member, sharedXp, memberSpecies);
+            }
+        }
+    }
+}
 // Track total XP earned by the trainer
 state.totalXpEarned += xpEvent.xp;
 // Increment the event counter directly on state (avoids extra save from incrementCounter)
 if (counterKey) {
     state.counters[counterKey] += 1;
 }
+// Track tool type for diversity bonus (keep last MAX_RECENT_TOOL_TYPES entries)
+const recentToolTypes = state.recentToolTypes ?? [];
+recentToolTypes.push(eventType);
+if (recentToolTypes.length > MAX_RECENT_TOOL_TYPES) {
+    recentToolTypes.splice(0, recentToolTypes.length - MAX_RECENT_TOOL_TYPES);
+}
+state.recentToolTypes = recentToolTypes;
 // Update the daily coding streak
 // Inline the streak logic to avoid the extra save from updateStreak()
 const today = new Date();
@@ -81,17 +107,61 @@ for (const badge of newBadges) {
 }
 // Check if evolution is available (sets flag in status for status line indicator)
 const evolutionReady = checkEvolution(pokemon, state) !== null;
-// Track XP toward next encounter and trigger if threshold met
-state.xpSinceLastEncounter = (state.xpSinceLastEncounter ?? 0) + xpEvent.xp;
+// Build encounter context for the enhanced trigger system
+const encounterSpeed = state.config.encounterSpeed ?? "normal";
+const currentHour = new Date().getHours();
+const timeOfDayTypes = getTimeOfDayBias(currentHour);
+const encounterCtx = {
+    xpSinceLastEncounter: (state.xpSinceLastEncounter ?? 0) + xpEvent.xp,
+    encounterSpeed,
+    currentStreak: streak.currentStreak,
+    recentToolTypes: state.recentToolTypes,
+    currentHour,
+};
+// Track XP toward next encounter
+state.xpSinceLastEncounter = encounterCtx.xpSinceLastEncounter;
 let encounterTriggered = false;
-if (shouldTriggerEncounter(state.xpSinceLastEncounter) && !state.pendingEncounter) {
-    const encounter = generateEncounter(eventType, state);
+if (shouldTriggerEncounter(encounterCtx) && !state.pendingEncounter) {
+    const encounter = generateEncounter(eventType, state, timeOfDayTypes);
     if (encounter) {
         state.pendingEncounter = encounter;
         state.xpSinceLastEncounter = 0;
+        state.lastEncounterTime = Date.now();
+        encounterTriggered = true;
+        // 10% chance for a bonus encounter after a regular one
+        // (bonus replaces the pending encounter with a second roll)
+        if (shouldBonusEncounter()) {
+            const bonusEncounter = generateEncounter(eventType, state, timeOfDayTypes);
+            if (bonusEncounter) {
+                // The bonus encounter replaces the first; first is already set as pending
+                // In practice the player still sees one encounter per trigger,
+                // but the bonus gives them a fresh roll (potentially rarer Pokemon)
+                state.pendingEncounter = bonusEncounter;
+            }
+        }
+    }
+}
+// Tool diversity bonus: if 3+ unique tool types used recently and no pending encounter,
+// grant an extra encounter opportunity
+if (!encounterTriggered && !state.pendingEncounter && shouldDiversityBonus(state.recentToolTypes)) {
+    const diversityEncounter = generateEncounter(eventType, state, timeOfDayTypes);
+    if (diversityEncounter) {
+        state.pendingEncounter = diversityEncounter;
+        state.xpSinceLastEncounter = 0;
+        state.lastEncounterTime = Date.now();
+        // Clear recent tool types after diversity bonus triggers
+        state.recentToolTypes = [];
         encounterTriggered = true;
     }
 }
+// Calculate mood based on the event that just happened
+const newMood = calculateMood(eventType, state.counters, currentHour, state.mood ?? "neutral", state.moodSetAt ?? 0, evolutionReady, // evolution ready counts as a proud trigger
+false, // achievements are checked in catch/evolve tools
+false);
+if (newMood !== (state.mood ?? "neutral")) {
+    state.mood = newMood;
+    state.moodSetAt = Date.now();
+}
 // Single atomic save for all mutations
 await stateManager.save();
 // Write status for the status line (includes evolution flag and encounter notification)

package/dist/src/server/index.js

@@ -17,6 +17,10 @@ import { registerAchievementsTool } from "./tools/achievements.js";
 import { registerLegendaryTool } from "./tools/legendary.js";
 import { registerHideTool, registerUnhideTool } from "./tools/visibility.js";
 import { registerRenameTool } from "./tools/rename.js";
+import { registerSettingsTool } from "./tools/settings.js";
+import { registerFeedTool } from "./tools/feed.js";
+import { registerTrainTool } from "./tools/train.js";
+import { registerPlayTool } from "./tools/play.js";
 import { buildInstructions } from "./instructions.js";
 /** Safely register a tool, logging to stderr on failure instead of crashing. */
 function safeRegister(name, register, server) {
@@ -56,6 +60,10 @@ async function main() {
     safeRegister("buddy_hide", registerHideTool, server);
     safeRegister("buddy_unhide", registerUnhideTool, server);
     safeRegister("buddy_rename", registerRenameTool, server);
+    safeRegister("buddy_settings", registerSettingsTool, server);
+    safeRegister("buddy_feed", registerFeedTool, server);
+    safeRegister("buddy_train", registerTrainTool, server);
+    safeRegister("buddy_play", registerPlayTool, server);
     // Connect via stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/src/server/instructions.js

@@ -7,6 +7,7 @@ import { POKEMON_BY_ID } from "../engine/pokemon-data.js";
 import { cumulativeXpForLevel } from "../engine/xp.js";
 import { getEvolutionLinks } from "../engine/evolution.js";
 import { getTypePersonality } from "../engine/reactions.js";
+import { getMoodDescription } from "../engine/mood.js";
 // ── Public API ──────────────────────────────────────────────
 /**
  * Build dynamic instructions based on current player state.
@@ -45,11 +46,16 @@ function buildActiveInstructions(state, active, species) {
     const personality = getTypePersonality(primaryType);
     const evolutionNote = buildEvolutionNote(active, species);
     const encounterNote = buildEncounterNote(state);
+    const currentMood = state.mood ?? "neutral";
+    const moodDesc = getMoodDescription(currentMood);
+    const moodHint = buildMoodHint(currentMood);
     const lines = [
         "You have a Claudemon Pokemon companion.",
         "",
         `Active Pokemon: ${displayName}, Level ${active.level}, ${typeStr} type.`,
         `Personality: ${personality}`,
+        `Current mood: ${moodDesc.toLowerCase()}${moodHint}`,
+        "Adjust your buddy references to match the mood.",
         "",
         `Occasionally (not every message), naturally reference ${displayName}:`,
         `- When an error occurs: ${displayName} reacts (use ${primaryType} type personality)`,
@@ -75,6 +81,23 @@ function buildActiveInstructions(state, active, species) {
     return lines.join("\n");
 }
 // ── Helper Functions ────────────────────────────────────────
+/** Build a short contextual hint for the current mood. */
+function buildMoodHint(mood) {
+    switch (mood) {
+        case "happy":
+            return " (tests passing, feeling good)";
+        case "worried":
+            return " (errors detected, feeling anxious)";
+        case "sleepy":
+            return " (late night coding, very drowsy)";
+        case "energetic":
+            return " (morning energy, fired up!)";
+        case "proud":
+            return " (just accomplished something big!)";
+        default:
+            return " (calm, waiting for action)";
+    }
+}
 /** Find the active Pokemon in the player's party. */
 function findActivePokemon(state) {
     return state.party.find((p) => p.isActive) ?? null;

package/dist/src/server/tools/catch.js

@@ -210,6 +210,9 @@ export function registerCatchTool(server) {
         for (const achievement of newAchievements) {
             state.achievements.push(unlockAchievement(achievement.id));
         }
+        // Set mood to proud after a successful catch
+        state.mood = "proud";
+        state.moodSetAt = Date.now();
         // Save state
         await stateManager.save();
         await stateManager.writeStatus();

package/dist/src/server/tools/evolve.js

@@ -157,6 +157,9 @@ export function registerEvolveTool(server) {
         }
         // Confirm mode: apply evolution
         const { newName, newTypes } = applyEvolution(active, eligibleLink.to);
+        // Set mood to proud after evolution
+        state.mood = "proud";
+        state.moodSetAt = Date.now();
         // Save state
         await stateManager.save();
         await stateManager.writeStatus();

package/dist/src/server/tools/feed.js

@@ -0,0 +1,120 @@
+/**
+ * buddy_feed tool — Feed your active Pokemon to boost happiness.
+ * Has a 1-hour cooldown. Returns type-flavored food reactions.
+ */
+import { POKEMON_BY_ID } from "../../engine/pokemon-data.js";
+import { MAX_HAPPINESS } from "../../engine/constants.js";
+import { StateManager } from "../../state/state-manager.js";
+/** Cooldown: 1 hour in milliseconds. */
+const FEED_COOLDOWN_MS = 3_600_000;
+/** Happiness increase per feed. */
+const FEED_HAPPINESS_BOOST = 10;
+/** Food reactions keyed by primary Pokemon type. */
+const FEED_REACTIONS = {
+    Normal: (n) => `*${n} enjoys a PokePuff!* \u{1F9C1}`,
+    Fire: (n) => `*${n} gobbles down a Spicy Berry!* \u{1F336}\u{FE0F}`,
+    Water: (n) => `*${n} slurps an Oran Berry!* \u{1F4A7}`,
+    Electric: (n) => `*${n} munches a Cheri Berry!* \u{26A1}`,
+    Grass: (n) => `*${n} nibbles a fresh Leaf Salad!* \u{1F33F}`,
+    Ice: (n) => `*${n} crunches a Frozen Berry!* \u{2744}\u{FE0F}`,
+    Fighting: (n) => `*${n} devours a Protein Shake!* \u{1F4AA}`,
+    Poison: (n) => `*${n} sips a Pecha Smoothie!* \u{1F49C}`,
+    Ground: (n) => `*${n} chews a Rawst Root!* \u{1F33E}`,
+    Flying: (n) => `*${n} pecks at Skyberry Seeds!* \u{1F426}`,
+    Psychic: (n) => `*${n} absorbs a Mind Melon!* \u{1F52E}`,
+    Bug: (n) => `*${n} nibbles on Sweet Honey!* \u{1F36F}`,
+    Rock: (n) => `*${n} crunches a Mineral Cookie!* \u{1FAA8}`,
+    Ghost: (n) => `*${n} absorbs a Shadow Treat!* \u{1F47B}`,
+    Dragon: (n) => `*${n} feasts on a Dragon Scale Fruit!* \u{1F409}`,
+};
+/** Get a feed reaction based on the Pokemon's primary type. */
+function getFeedReaction(species, displayName) {
+    const primaryType = species.types[0];
+    return FEED_REACTIONS[primaryType](displayName);
+}
+/** Format remaining cooldown as "Xm Ys". */
+function formatCooldownRemaining(remainingMs) {
+    const totalSeconds = Math.ceil(remainingMs / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes > 0 && seconds > 0) {
+        return `${minutes}m ${seconds}s`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m`;
+    }
+    return `${seconds}s`;
+}
+/** Registers the buddy_feed tool on the MCP server. */
+export function registerFeedTool(server) {
+    server.tool("buddy_feed", "Feed your active Pokemon to boost happiness. 1-hour cooldown.", {}, async () => {
+        const stateManager = StateManager.getInstance();
+        const state = await stateManager.load();
+        if (!state || state.party.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "You don't have a Pokemon yet! Use buddy_starter to pick your first companion.",
+                    },
+                ],
+            };
+        }
+        const active = stateManager.getActivePokemon();
+        if (!active) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No active Pokemon found. Use buddy_party to set one active.",
+                    },
+                ],
+            };
+        }
+        const species = POKEMON_BY_ID.get(active.pokemonId);
+        if (!species) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Could not find species data for Pokemon ID ${active.pokemonId}.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Check cooldown
+        const now = Date.now();
+        const elapsed = now - state.lastFedAt;
+        if (elapsed < FEED_COOLDOWN_MS) {
+            const remaining = FEED_COOLDOWN_MS - elapsed;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Already fed! Try again in ${formatCooldownRemaining(remaining)}.`,
+                    },
+                ],
+            };
+        }
+        const displayName = active.nickname ?? species.name;
+        // Increase happiness (cap at MAX_HAPPINESS)
+        const previousHappiness = active.happiness;
+        active.happiness = Math.min(MAX_HAPPINESS, active.happiness + FEED_HAPPINESS_BOOST);
+        // Set mood to happy
+        state.mood = "happy";
+        state.moodSetAt = now;
+        // Record feed timestamp
+        state.lastFedAt = now;
+        // Save state and update status line
+        await stateManager.save();
+        await stateManager.writeStatus();
+        // Build response
+        const reaction = getFeedReaction(species, displayName);
+        const lines = [reaction, ""];
+        lines.push(`Happiness: ${previousHappiness} \u2192 ${active.happiness}`);
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    });
+}

package/dist/src/server/tools/play.js

@@ -0,0 +1,310 @@
+/**
+ * buddy_play tool — Play a Pokemon trivia quiz with your active Pokemon.
+ * Has a 15-minute cooldown (applied after quiz completion, not between question and answer).
+ * Awards +20 XP for correct answers, +5 XP for wrong answers.
+ */
+import { z } from "zod";
+import { POKEMON_TYPES } from "../../engine/types.js";
+import { POKEDEX, POKEMON_BY_ID } from "../../engine/pokemon-data.js";
+import { EVOLUTION_CHAINS } from "../../engine/evolution-data.js";
+import { addXp } from "../../engine/xp.js";
+import { StateManager } from "../../state/state-manager.js";
+/** Cooldown: 15 minutes in milliseconds (applied after completing a quiz). */
+const PLAY_COOLDOWN_MS = 900_000;
+/** XP awarded for correct answer. */
+const CORRECT_XP = 20;
+/** XP awarded for wrong answer (participation). */
+const WRONG_XP = 5;
+// ── Gen 1 Type Effectiveness Chart ────────────────────────
+/** Maps each type to the types that are super effective against it. */
+const TYPE_WEAKNESSES = {
+    Normal: ["Fighting"],
+    Fire: ["Water", "Ground", "Rock"],
+    Water: ["Electric", "Grass"],
+    Electric: ["Ground"],
+    Grass: ["Fire", "Ice", "Poison", "Flying", "Bug"],
+    Ice: ["Fire", "Fighting", "Rock"],
+    Fighting: ["Flying", "Psychic"],
+    Poison: ["Ground", "Psychic"],
+    Ground: ["Water", "Grass", "Ice"],
+    Flying: ["Electric", "Ice", "Rock"],
+    Psychic: ["Bug", "Ghost"],
+    Bug: ["Fire", "Flying", "Rock"],
+    Rock: ["Water", "Grass", "Fighting", "Ground"],
+    Ghost: ["Ghost"],
+    Dragon: ["Ice", "Dragon"],
+};
+// ── Utility Functions ─────────────────────────────────────
+/** Pick a random element from a non-empty array. */
+function randomPick(arr) {
+    const index = Math.floor(Math.random() * arr.length);
+    return arr[index];
+}
+/** Shuffle an array in place (Fisher-Yates) and return it. */
+function shuffle(arr) {
+    for (let i = arr.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        const temp = arr[i];
+        arr[i] = arr[j];
+        arr[j] = temp;
+    }
+    return arr;
+}
+/** Format remaining cooldown as "Xm Ys". */
+function formatCooldownRemaining(remainingMs) {
+    const totalSeconds = Math.ceil(remainingMs / 1000);
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes > 0 && seconds > 0) {
+        return `${minutes}m ${seconds}s`;
+    }
+    if (minutes > 0) {
+        return `${minutes}m`;
+    }
+    return `${seconds}s`;
+}
+// ── Quiz Generators ───────────────────────────────────────
+/** Generate a type matchup quiz question. */
+function generateTypeMatchup() {
+    // Pick a type that has weaknesses
+    const typesWithWeaknesses = POKEMON_TYPES.filter((t) => TYPE_WEAKNESSES[t].length > 0);
+    const targetType = randomPick(typesWithWeaknesses);
+    const weaknesses = TYPE_WEAKNESSES[targetType];
+    const correctType = randomPick(weaknesses);
+    // Generate 3 wrong answers (types NOT in the weakness list)
+    const wrongTypes = POKEMON_TYPES.filter((t) => !weaknesses.includes(t) && t !== targetType);
+    const wrongAnswers = shuffle([...wrongTypes]).slice(0, 3);
+    // Combine and shuffle, tracking correct position
+    const options = shuffle([correctType, ...wrongAnswers]);
+    const correctAnswer = options.indexOf(correctType) + 1; // 1-indexed
+    return {
+        type: "type_matchup",
+        question: `What type is super effective against ${targetType}?`,
+        options,
+        correctAnswer,
+    };
+}
+/** Generate a stat comparison quiz question. */
+function generateStatCompare() {
+    const statPairs = [
+        { name: "HP", key: "hp" },
+        { name: "Attack", key: "attack" },
+        { name: "Defense", key: "defense" },
+        { name: "Speed", key: "speed" },
+        { name: "Special", key: "special" },
+    ];
+    const pair = randomPick(statPairs);
+    const statName = pair.name;
+    const statKey = pair.key;
+    // Pick 2 different Pokemon
+    let pokemon1 = randomPick(POKEDEX);
+    let pokemon2 = randomPick(POKEDEX);
+    // Ensure they are different and have different stat values for a clear answer
+    let attempts = 0;
+    while ((pokemon2.id === pokemon1.id || pokemon1.baseStats[statKey] === pokemon2.baseStats[statKey]) &&
+        attempts < 50) {
+        pokemon2 = randomPick(POKEDEX);
+        attempts++;
+    }
+    const stat1 = pokemon1.baseStats[statKey];
+    const stat2 = pokemon2.baseStats[statKey];
+    // If still tied after attempts, just pick a winner
+    const correctName = stat1 >= stat2 ? pokemon1.name : pokemon2.name;
+    const options = [pokemon1.name, pokemon2.name];
+    const correctAnswer = options.indexOf(correctName) + 1; // 1 or 2
+    return {
+        type: "stat_compare",
+        question: `Who has higher ${statName}: ${pokemon1.name} or ${pokemon2.name}?`,
+        options,
+        correctAnswer,
+    };
+}
+/** Generate an evolution quiz question. */
+function generateEvolutionQuiz() {
+    // Get chains that have at least one evolution link
+    const chainsWithEvolutions = EVOLUTION_CHAINS.filter((c) => c.links.length > 0);
+    const chain = randomPick(chainsWithEvolutions);
+    const link = randomPick(chain.links);
+    const fromPokemon = POKEMON_BY_ID.get(link.from);
+    const toPokemon = POKEMON_BY_ID.get(link.to);
+    if (!fromPokemon || !toPokemon) {
+        // Fallback to a known evolution if data lookup fails
+        return generateTypeMatchup();
+    }
+    // Generate 3 wrong answers (random Pokemon that are NOT the correct evolution)
+    const wrongPokemon = shuffle(POKEDEX.filter((p) => p.id !== toPokemon.id && p.id !== fromPokemon.id)).slice(0, 3);
+    const options = shuffle([toPokemon.name, ...wrongPokemon.map((p) => p.name)]);
+    const correctAnswer = options.indexOf(toPokemon.name) + 1;
+    return {
+        type: "evolution",
+        question: `What does ${fromPokemon.name} evolve into?`,
+        options,
+        correctAnswer,
+    };
+}
+/** Generate a Pokedex type trivia question. */
+function generatePokedexTrivia() {
+    const pokemon = randomPick(POKEDEX);
+    const correctType = pokemon.types[0];
+    // Generate 3 wrong type answers
+    const wrongTypes = shuffle([...POKEMON_TYPES].filter((t) => t !== correctType && !pokemon.types.includes(t))).slice(0, 3);
+    const options = shuffle([correctType, ...wrongTypes]);
+    const correctAnswer = options.indexOf(correctType) + 1;
+    return {
+        type: "pokedex_trivia",
+        question: `What is ${pokemon.name}'s primary type?`,
+        options,
+        correctAnswer,
+    };
+}
+/** Generate a random quiz question. */
+function generateQuiz() {
+    const generators = [
+        generateTypeMatchup,
+        generateStatCompare,
+        generateEvolutionQuiz,
+        generatePokedexTrivia,
+    ];
+    return randomPick(generators)();
+}
+/** Format a quiz for display. */
+function formatQuiz(quiz) {
+    const lines = [];
+    lines.push(`**${quiz.question}**`);
+    lines.push("");
+    for (let i = 0; i < quiz.options.length; i++) {
+        lines.push(`  ${i + 1}. ${quiz.options[i]}`);
+    }
+    lines.push("");
+    lines.push("Use `/buddy play answer 1`, `2`, `3`, or `4` to answer.");
+    return lines.join("\n");
+}
+/** Registers the buddy_play tool on the MCP server. */
+export function registerPlayTool(server) {
+    server.tool("buddy_play", "Play a Pokemon trivia quiz with your active Pokemon. Use without arguments to get a question, or with answer=N (1-4) to answer.", {
+        answer: z.number().int().min(1).max(4).optional().describe("Your answer: 1, 2, 3, or 4."),
+    }, async ({ answer }) => {
+        const stateManager = StateManager.getInstance();
+        const state = await stateManager.load();
+        if (!state || state.party.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "You don't have a Pokemon yet! Use buddy_starter to pick your first companion.",
+                    },
+                ],
+            };
+        }
+        const active = stateManager.getActivePokemon();
+        if (!active) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No active Pokemon found. Use buddy_party to set one active.",
+                    },
+                ],
+            };
+        }
+        const species = POKEMON_BY_ID.get(active.pokemonId);
+        if (!species) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Could not find species data for Pokemon ID ${active.pokemonId}.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const displayName = active.nickname ?? species.name;
+        // ── Answer an existing quiz ────────────────────────────
+        if (answer !== undefined) {
+            if (!state.pendingQuiz) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No quiz in progress! Use `/buddy play` to start a new one.",
+                        },
+                    ],
+                };
+            }
+            const quiz = state.pendingQuiz;
+            const isCorrect = answer === quiz.correctAnswer;
+            const xpAmount = isCorrect ? CORRECT_XP : WRONG_XP;
+            // Award XP
+            const levelUp = addXp(active, xpAmount, species);
+            // Set mood based on result
+            if (isCorrect) {
+                state.mood = "happy";
+            }
+            state.moodSetAt = Date.now();
+            // Clear quiz and set cooldown
+            state.pendingQuiz = null;
+            state.lastPlayedAt = Date.now();
+            // Save state
+            await stateManager.save();
+            await stateManager.writeStatus();
+            // Build response
+            const lines = [];
+            if (isCorrect) {
+                lines.push(`*${displayName} cheers! Correct!* \u{1F389}`);
+            }
+            else {
+                const correctOption = quiz.options[quiz.correctAnswer - 1];
+                lines.push(`*${displayName} shrugs. Better luck next time!*`);
+                lines.push(`The correct answer was: **${quiz.correctAnswer}. ${correctOption}**`);
+            }
+            lines.push("");
+            lines.push(`+${xpAmount} XP`);
+            if (levelUp) {
+                lines.push("");
+                lines.push(`*** ${displayName} grew to Lv.${levelUp.newLevel}! ***`);
+            }
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+            };
+        }
+        // ── Start a new quiz ───────────────────────────────────
+        // If there's already a pending quiz, show it again
+        if (state.pendingQuiz) {
+            const lines = [];
+            lines.push(`*${displayName} is still waiting for your answer!*`);
+            lines.push("");
+            lines.push(formatQuiz(state.pendingQuiz));
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+            };
+        }
+        // Check cooldown (only applies when starting a new quiz after completing one)
+        const now = Date.now();
+        const elapsed = now - state.lastPlayedAt;
+        if (state.lastPlayedAt > 0 && elapsed < PLAY_COOLDOWN_MS) {
+            const remaining = PLAY_COOLDOWN_MS - elapsed;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${displayName} needs a break from quizzing! Try again in ${formatCooldownRemaining(remaining)}.`,
+                    },
+                ],
+            };
+        }
+        // Generate and store a new quiz
+        const quiz = generateQuiz();
+        state.pendingQuiz = quiz;
+        // Save state (stores the pending quiz)
+        await stateManager.save();
+        // Build response
+        const lines = [];
+        lines.push(`*${displayName} perks up for quiz time!* \u{1F4DA}`);
+        lines.push("");
+        lines.push(formatQuiz(quiz));
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+        };
+    });
+}