storymode-cli 1.2.0 → 1.2.2

package/src/cli.mjs

@@ -1,4 +1,5 @@
 import { execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
 import { fetchFrames, fetchCharacter } from './api.mjs';
 import { playAnimation, playCompanion, playReactiveCompanion, showFrame } from './player.mjs';
 import { browse } from './browse.mjs';
@@ -6,29 +7,90 @@ import { startMcpServer } from './mcp.mjs';
 import { loadAnimations, clearCache } from './cache.mjs';
 import { installHooks, uninstallHooks } from './hooks.mjs';
 
+function hasTmux() {
+  try {
+    execSync('which tmux', { stdio: 'ignore' });
+    return true;
+  } catch { return false; }
+}
+
+function askYesNo(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+async function ensureTmux() {
+  if (hasTmux()) return true;
+
+  console.error('  Companion mode requires tmux, which is not installed.');
+
+  const platform = process.platform;
+  let installCmd;
+  if (platform === 'darwin') {
+    try { execSync('which brew', { stdio: 'ignore' }); installCmd = 'brew install tmux'; }
+    catch {
+      try { execSync('which port', { stdio: 'ignore' }); installCmd = 'sudo port install tmux'; }
+      catch { /* no package manager found */ }
+    }
+  } else if (platform === 'linux') {
+    for (const [bin, cmd] of [
+      ['apt-get', 'sudo apt-get install -y tmux'],
+      ['dnf',     'sudo dnf install -y tmux'],
+      ['yum',     'sudo yum install -y tmux'],
+      ['pacman',  'sudo pacman -S --noconfirm tmux'],
+      ['apk',     'sudo apk add tmux'],
+    ]) {
+      try { execSync(`which ${bin}`, { stdio: 'ignore' }); installCmd = cmd; break; }
+      catch { /* try next */ }
+    }
+  }
+
+  if (!installCmd) {
+    console.error('  Could not detect a supported package manager.');
+    console.error('  Please install tmux manually and try again.');
+    return false;
+  }
+
+  const yes = await askYesNo(`  Install tmux with \`${installCmd}\`? [y/N] `);
+  if (!yes) {
+    console.error('  tmux is required for companion mode. Install it and try again.');
+    return false;
+  }
+
+  try {
+    console.error(`  Running: ${installCmd}`);
+    execSync(installCmd, { stdio: 'inherit' });
+    if (!hasTmux()) throw new Error('tmux not found after install');
+    console.error('  tmux installed successfully!\n');
+    return true;
+  } catch (err) {
+    console.error(`  Failed to install tmux: ${err.message}`);
+    return false;
+  }
+}
+
 const HELP = `
-  storymode-cli — play AI-animated pixel art in your terminal
+  storymode-cli — AI-animated pixel art companions for your terminal
 
   Usage:
-    storymode play <gallery_id>         Play an animation (full screen)
-    storymode companion <gallery_id>    Play compact sprite alongside your session
-    storymode show <gallery_id>         Show first frame as static portrait
-    storymode browse                    Browse the gallery interactively
-    storymode mcp                       Start MCP server (for Claude Code)
-    storymode hooks install [--global]  Install Claude Code hooks
-    storymode hooks uninstall [--global] Remove Claude Code hooks
-    storymode cache clear [gallery_id]  Clear animation cache
+    storymode play            Run a reactive companion alongside Claude Code
+    storymode browse          Browse the gallery and switch characters
 
   Options:
-    --sextant    Use sextant rendering (sharper, needs modern terminal).
-    --size=compact|tiny   Size for companion mode (default: compact).
-    --reactive   Enable reactive mode (responds to Claude Code events).
-    --detach     Return control immediately (companion mode).
-
-  Controls (during playback):
-    space     pause / resume
-    < / >     step frames (when paused)
-    + / -     increase / decrease speed
+    --compact        Smaller companion pane (default: full)
+    --tiny           Tiny companion pane
+    --no-ai          Disable AI personality (preset speech only)
+    --model=ID       Anthropic model for AI personality
+    --classic        Full-screen animation viewer (non-reactive)
+    --detach         Return control immediately
+
+  Controls:
+    a         add API key (enables AI personality)
     q         quit
 
   https://storymode.fixmy.codes
@@ -48,51 +110,56 @@ function parseFlags(args) {
   return { flags, positional };
 }
 
+const DEFAULT_CHARACTER = 3; // Zephyr
+
 export async function run(args) {
   const cmd = args[0];
   const { flags, positional } = parseFlags(args.slice(1));
-  const id = positional[0];
+  const id = positional[0] || (cmd === 'play' || cmd === 'companion' ? DEFAULT_CHARACTER : undefined);
 
   switch (cmd) {
-    case 'play': {
-      if (!id) {
-        console.error('Usage: storymode play <gallery_id>');
-        process.exit(1);
-      }
-      try {
-        process.stderr.write('  Loading animation...\n');
-        const fetchOpts = {};
-        if (flags.sextant) { fetchOpts.size = 'compact'; fetchOpts.mode = 'sextant'; }
-        const framesData = await fetchFrames(id, fetchOpts);
-        await playAnimation(framesData);
-      } catch (err) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
-      }
-      break;
-    }
-
+    // --- Main command: reactive companion ---
+    case 'play':
     case 'companion': {
-      if (!id) {
-        console.error('Usage: storymode companion <gallery_id> [--reactive] [--detach] [--size=full|compact|tiny]');
-        process.exit(1);
+
+      // --classic: old full-screen animation viewer
+      if (flags.classic) {
+        try {
+          process.stderr.write('  Loading animation...\n');
+          const fetchOpts = {};
+          if (flags.sextant) { fetchOpts.size = 'compact'; fetchOpts.mode = 'sextant'; }
+          const framesData = await fetchFrames(id, fetchOpts);
+          await playAnimation(framesData);
+        } catch (err) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+        break;
       }
-      const size = flags.size || 'compact';
+
+      // Determine size: default full, --compact, --tiny, or explicit --size=
+      const size = flags.tiny ? 'tiny' : flags.compact ? 'compact' : (flags.size || 'full');
       const detach = !!flags.detach;
-      const reactive = !!flags.reactive;
+      const noAi = !!flags['no-ai'];
+      const model = flags.model || '';
+      // Reactive is always on unless --classic
+      const reactive = !flags['no-reactive'];
       const paneWidth = size === 'full' ? 62 : size === 'tiny' ? 14 : 22;
 
       // If we're already the companion pane (spawned by tmux split), play inline
       if (process.env.STORYMODE_COMPANION === '1') {
         try {
           if (reactive) {
-            // Reactive mode: load all animations, start socket server
             const fetchOpts = { size };
             if (flags.sextant) fetchOpts.mode = 'sextant';
-            const { animMap, character } = await loadAnimations(id, fetchOpts);
+            const { animMap, character, personality } = await loadAnimations(id, fetchOpts);
             await playReactiveCompanion(animMap, {
               characterName: character?.name || `#${id}`,
+              character,
+              personality,
               fullscreen: size === 'full',
+              noAi,
+              model: model || undefined,
             });
           } else {
             const fetchOpts = { size };
@@ -107,30 +174,31 @@ export async function run(args) {
         break;
       }
 
-      // Auto-install hooks when reactive mode is used
+      // Auto-install hooks
       if (reactive) {
         installHooks({ global: true });
       }
 
-      // Otherwise, open a tmux side pane
+      // Open tmux side pane — install tmux if needed
+      if (!await ensureTmux()) process.exit(1);
       const inTmux = !!process.env.TMUX;
       const sextantFlag = flags.sextant ? ' --sextant' : '';
       const reactiveFlag = reactive ? ' --reactive' : '';
-      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli companion ${id} --size=${size}${sextantFlag}${reactiveFlag}`;
+      const noAiFlag = noAi ? ' --no-ai' : '';
+      const modelFlag = model ? ` --model=${model}` : '';
+      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli play ${id} --size=${size}${sextantFlag}${reactiveFlag}${noAiFlag}${modelFlag}`;
 
       try {
         if (inTmux) {
-          // Split current window with a side pane
           execSync(
             `tmux split-window -h -l ${paneWidth} '${companionCmd}'`,
             { stdio: 'ignore' }
           );
           if (!detach) {
-            process.stderr.write(`  Companion sprite opened in side pane (${size}${reactive ? ', reactive' : ''}).\n`);
+            process.stderr.write(`  Companion opened in side pane (${size}).\n`);
             process.stderr.write('  Close the pane or press q in it to stop.\n');
           }
         } else {
-          // Not in tmux — start a new tmux session with the split
           process.stderr.write('  Starting tmux session with companion pane...\n');
           execSync(
             `tmux new-session -d -s storymode -x 100 -y 30 \\; ` +
@@ -142,19 +210,29 @@ export async function run(args) {
             process.stderr.write('  Companion running in tmux session "storymode".\n');
             process.stderr.write('  Attach with: tmux attach -t storymode\n');
           } else {
-            // Attach to the session so the user sees it
             execSync('tmux attach -t storymode', { stdio: 'inherit' });
           }
         }
       } catch (err) {
         console.error(`Error: ${err.message}`);
-        console.error('  Make sure tmux is installed: brew install tmux');
         process.exit(1);
       }
       break;
     }
 
+    case 'browse':
+      try {
+        await browse();
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+      break;
+
+    // --- Advanced / hidden commands ---
+
     case 'show': {
+      // Legacy: print first frame. Kept for backward compat.
       if (!id) {
         console.error('Usage: storymode show <gallery_id>');
         process.exit(1);
@@ -178,15 +256,6 @@ export async function run(args) {
       break;
     }
 
-    case 'browse':
-      try {
-        await browse();
-      } catch (err) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
-      }
-      break;
-
     case 'mcp':
       startMcpServer();
       break;

package/src/config.mjs

@@ -0,0 +1,104 @@
+/**
+ * Persistent config at ~/.storymode/config.json
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline';
+
+const STORYMODE_DIR = join(homedir(), '.storymode');
+const CONFIG_PATH = join(STORYMODE_DIR, 'config.json');
+
+function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config) {
+  mkdirSync(STORYMODE_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+/**
+ * Get the Anthropic API key from env or config file.
+ * Priority: ANTHROPIC_API_KEY env var > config file
+ */
+export function getApiKey() {
+  return process.env.ANTHROPIC_API_KEY || readConfig().anthropic_api_key || '';
+}
+
+/**
+ * Save the Anthropic API key to config file.
+ */
+export function saveApiKey(key) {
+  const config = readConfig();
+  config.anthropic_api_key = key;
+  writeConfig(config);
+}
+
+/**
+ * Check if we've already shown the first-run prompt before.
+ */
+export function hasSeenKeyPrompt() {
+  return !!readConfig().seen_key_prompt;
+}
+
+/**
+ * Mark that we've shown the first-run prompt.
+ */
+export function markKeyPromptSeen() {
+  const config = readConfig();
+  config.seen_key_prompt = true;
+  writeConfig(config);
+}
+
+/**
+ * Interactive prompt for API key.
+ * Returns the key if entered, or '' if skipped.
+ *
+ * @param {'first-run'|'reminder'|'hotkey'} mode
+ */
+export function promptForApiKey(mode = 'first-run') {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+
+    if (mode === 'first-run') {
+      process.stderr.write('\n');
+      process.stderr.write('  ┌─────────────────────────────────────────────────┐\n');
+      process.stderr.write('  │  AI Personality (optional)                      │\n');
+      process.stderr.write('  │                                                 │\n');
+      process.stderr.write('  │  Your companion can react with unique, in-      │\n');
+      process.stderr.write('  │  character speech using your Anthropic API key. │\n');
+      process.stderr.write('  │                                                 │\n');
+      process.stderr.write('  │  Without it, you still get animations +         │\n');
+      process.stderr.write('  │  preset speech lines — just not AI-generated.   │\n');
+      process.stderr.write('  │                                                 │\n');
+      process.stderr.write('  │  Key is saved locally in ~/.storymode/config.   │\n');
+      process.stderr.write('  └─────────────────────────────────────────────────┘\n');
+      process.stderr.write('\n');
+    } else if (mode === 'reminder') {
+      process.stderr.write('\n');
+      process.stderr.write('  AI personality is off. Press [a] during playback to add your API key,\n');
+      process.stderr.write('  or enter it now:\n\n');
+    } else if (mode === 'hotkey') {
+      process.stderr.write('\n  Enter your Anthropic API key (or press Enter to cancel):\n\n');
+    }
+
+    rl.question('  ANTHROPIC_API_KEY: ', (answer) => {
+      rl.close();
+      const key = (answer || '').trim();
+      if (key) {
+        saveApiKey(key);
+        process.stderr.write('  Key saved to ~/.storymode/config.json\n\n');
+      } else if (mode === 'first-run') {
+        markKeyPromptSeen();
+        process.stderr.write('  Skipped. Press [a] anytime in companion to add it later.\n\n');
+      }
+      resolve(key);
+    });
+  });
+}

package/src/mcp.mjs

@@ -49,17 +49,20 @@ async function handleToolCall(name, args) {
     case 'list_characters': {
       const items = await fetchGallery();
       if (!items.length) return 'Gallery is empty.';
-      const parts = [];
-      for (const item of items) {
-        const char = await fetchCharacter(item.id).catch(() => null);
+      const chars = await Promise.all(
+        items.map(item => fetchCharacter(item.id).catch(() => null))
+      );
+      const parts = items.map((item, i) => {
+        const char = chars[i];
         let line = `${item.name || 'untitled'} (id: ${item.id})`;
-        if (char?.backstory) line += `\n  ${char.backstory}`;
+        if (char?.prompt) line += `\n  Appearance: ${char.prompt}`;
+        if (char?.backstory) line += `\n  Backstory: ${char.backstory}`;
         if (char?.animations?.length) {
           const names = char.animations.map(a => a.name || a.prompt).join(', ');
-          line += `\n  Animations: ${names}`;
+          line += `\n  Animations (${char.animations.length}): ${names}`;
         }
-        parts.push(line);
-      }
+        return line;
+      });
       return parts.join('\n\n');
     }
     case 'show_character': {

package/src/player.mjs

@@ -1,6 +1,8 @@
 import { createServer } from 'node:net';
 import { unlinkSync, existsSync } from 'node:fs';
-import { mapEventToAnimation, pickSpeech, ONE_SHOT_ANIMS, IDLE_ANIM, SLEEP_ANIM, SLEEP_TIMEOUT_S, narrateEvent, SessionContext } from './reactive.mjs';
+import { mapEventToAnimation, pickSpeech, ONE_SHOT_ANIMS, IDLE_ANIM, SLEEP_ANIM, SLEEP_TIMEOUT_S, narrateEvent, SessionContext, StateEngine } from './reactive.mjs';
+import { createAgent } from './agent.mjs';
+import { getApiKey, hasSeenKeyPrompt, promptForApiKey } from './config.mjs';
 
 const { stdout, stdin } = process;
 
@@ -211,12 +213,29 @@ export function playCompanion(framesData) {
  * @param {Map<string, {fps: number, frames: string[][]}>} animMap - All animations keyed by name
  * @param {object} [opts]
  * @param {string} [opts.characterName] - Character name for status display
+ * @param {object} [opts.character] - Character data {name, backstory, ...} for LLM personality
+ * @param {object} [opts.personality] - Full personality.json data { character, disposition, animations, speech }
  * @param {boolean} [opts.fullscreen] - Use alt screen (full-screen mode)
+ * @param {boolean} [opts.noAi] - Disable LLM personality layer
+ * @param {string} [opts.model] - Anthropic model ID for personality layer
  */
-export function playReactiveCompanion(animMap, opts = {}) {
+export async function playReactiveCompanion(animMap, opts = {}) {
   const characterName = opts.characterName || 'companion';
+  const personality = opts.personality || null;
+  let character = opts.noAi ? null : (personality || opts.character || null);
   const fullscreen = !!opts.fullscreen;
 
+  // --- API key prompt (before terminal setup) ---
+  if (character && !opts.noAi && !getApiKey()) {
+    if (!hasSeenKeyPrompt()) {
+      // First time: full interactive prompt
+      await promptForApiKey('first-run');
+    } else {
+      // Subsequent launches: short reminder
+      process.stderr.write('  AI personality: OFF — press [a] to add your API key\n');
+    }
+  }
+
   // Find idle animation (required)
   const idleData = animMap.get(IDLE_ANIM);
   if (!idleData || idleData.frames.length === 0) {
@@ -261,9 +280,36 @@ export function playReactiveCompanion(animMap, opts = {}) {
   // Recent animation tracking (avoid repeats)
   const recentAnims = [];
 
-  // Session context (for Phase 2 narrator)
+  // Session context
   const sessionCtx = new SessionContext();
 
+  // State engine — tracks internal dimensions over time
+  // Extract state dimensions (skip 'drives' — it's for the LLM, not the engine)
+  const rawState = personality?.state;
+  const stateConfig = rawState ? Object.fromEntries(
+    Object.entries(rawState).filter(([k]) => k !== 'drives')
+  ) : null;
+  const stateEngine = new StateEngine(stateConfig);
+
+  // Personality layer (LLM agent) — requires character data + API key
+  const agentOpts = {
+    model: opts.model,
+    getState: () => stateEngine.active ? stateEngine.toJSON() : null,
+  };
+  function onAgentReaction(reaction) {
+    if (reaction.animation && animMap.has(reaction.animation)) {
+      switchAnimation(reaction.animation, ONE_SHOT_ANIMS.has(reaction.animation) ? 'one-shot' : 'loop');
+    }
+    if (reaction.speech) {
+      speechText = reaction.speech;
+      speechSetAt = Date.now();
+      lastSpeech = reaction.speech;
+    }
+  }
+  let agent = character
+    ? createAgent(character, [...animMap.keys()], onAgentReaction, agentOpts)
+    : null;
+
   // Socket path
   const sockPath = `/tmp/storymode-companion-${process.pid}.sock`;
 
@@ -383,7 +429,11 @@ export function playReactiveCompanion(animMap, opts = {}) {
     }
 
     // Status line
-    out += `\x1b[0m\x1b[K  ${characterName} [${currentAnimName}]  [q]=quit\n`;
+    const stateStr = stateEngine.active
+      ? '  ' + Object.entries(stateEngine.toJSON()).map(([k, v]) => `${k.slice(0,3)}:${v}`).join(' ')
+      : '';
+    const keyHints = !agent && character && !opts.noAi ? '[a]=AI key [q]=quit' : '[q]=quit';
+    out += `\x1b[0m\x1b[K  ${characterName} [${currentAnimName}]${stateStr}  ${keyHints}\n`;
     stdout.write(out);
   }
 
@@ -421,22 +471,43 @@ export function playReactiveCompanion(animMap, opts = {}) {
     // Update session context
     sessionCtx.update(msg);
 
-    // Instant layer: static map
+    // Update state engine
+    stateEngine.update(msg.event);
+
+    // Instant layer: static map (0ms)
     const mapping = mapEventToAnimation(msg.event, animMap);
     if (mapping) {
       switchAnimation(mapping.anim, mapping.type);
     }
 
-    // Speech bubble
+    // State layer: check thresholds (0ms, overrides instant layer)
+    if (stateEngine.active && personality?.animations) {
+      const triggered = stateEngine.checkThresholds(personality.animations);
+      if (triggered && animMap.has(triggered.animName)) {
+        switchAnimation(triggered.animName, triggered.type);
+      }
+    }
+
+    // Speech bubble (static fallback)
     const speech = pickSpeech(msg.event, lastSpeech);
     if (speech) {
       speechText = speech;
       speechSetAt = Date.now();
       lastSpeech = speech;
     }
+
+    // Personality layer: push to LLM agent (debounced, ~3s)
+    if (agent) {
+      const narrated = narrateEvent(msg);
+      agent.pushEvent(
+        { summary: narrated, type: msg.event, tool: msg.tool_name || msg.tool },
+        sessionCtx.toJSON(),
+      );
+    }
   }
 
   function cleanup() {
+    if (agent) agent.destroy();
     if (stdin.isTTY) stdin.setRawMode(false);
     stdin.removeAllListeners('data');
     stdin.pause();
@@ -449,10 +520,41 @@ export function playReactiveCompanion(animMap, opts = {}) {
     try { unlinkSync(sockPath); } catch { /* ignore */ }
   }
 
+  let promptingKey = false;
+
+  async function handleApiKeyPrompt() {
+    if (promptingKey || agent) return;
+    promptingKey = true;
+
+    // Temporarily exit raw mode for readline
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.removeAllListeners('data');
+
+    const key = await promptForApiKey('hotkey');
+
+    // Restore raw mode
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+      stdin.resume();
+      stdin.on('data', handleKey);
+    }
+    promptingKey = false;
+
+    if (key && character) {
+      agent = createAgent(character, [...animMap.keys()], onAgentReaction, agentOpts);
+      if (agent) {
+        speechText = 'AI personality activated!';
+        speechSetAt = Date.now();
+      }
+    }
+  }
+
   function handleKey(data) {
     const key = data.toString();
     if (key === 'q' || key === '\x03') {
       quit = true;
+    } else if (key === 'a' && !agent && character && !opts.noAi) {
+      handleApiKeyPrompt();
     }
   }
 
@@ -472,12 +574,26 @@ export function playReactiveCompanion(animMap, opts = {}) {
         return;
       }
 
-      // Check for sleep
-      const idleTime = (Date.now() - lastEventTime) / 1000;
-      if (idleTime >= SLEEP_TIMEOUT_S && !sleeping) {
-        sleeping = true;
-        if (animMap.has(SLEEP_ANIM)) {
-          switchAnimation(SLEEP_ANIM, 'loop');
+      // State engine tick (passive drain over time)
+      stateEngine.tick();
+
+      // State-driven animation check (e.g. energy < 0.15 → sleep)
+      if (stateEngine.active && personality?.animations) {
+        const triggered = stateEngine.checkThresholds(personality.animations);
+        if (triggered && animMap.has(triggered.animName) && currentAnimName !== triggered.animName) {
+          switchAnimation(triggered.animName, triggered.type);
+          sleeping = triggered.animName === SLEEP_ANIM;
+        }
+      }
+
+      // Fallback sleep check (when no state engine or no energy dimension)
+      if (!sleeping) {
+        const idleTime = (Date.now() - lastEventTime) / 1000;
+        if (idleTime >= SLEEP_TIMEOUT_S) {
+          sleeping = true;
+          if (animMap.has(SLEEP_ANIM)) {
+            switchAnimation(SLEEP_ANIM, 'loop');
+          }
         }
       }
 
@@ -504,6 +620,14 @@ export function playReactiveCompanion(animMap, opts = {}) {
 
     // Print socket path so hooks can find it
     process.stderr.write(`  Socket: ${sockPath}\n`);
+    if (agent) {
+      const modelName = opts.model || 'claude-haiku-4-5';
+      process.stderr.write(`  AI personality: ON (${modelName})\n`);
+    } else if (character && !opts.noAi) {
+      process.stderr.write(`  AI personality: OFF — press [a] to add API key\n`);
+    } else if (opts.noAi) {
+      process.stderr.write(`  AI personality: OFF (--no-ai)\n`);
+    }
     process.stderr.write(`  Listening for Claude Code events...\n`);
 
     const sigHandler = () => { quit = true; };