@axplusb/kepler 1.0.9 → 2.0.0

package/src/state/orbit.mjs

@@ -0,0 +1,263 @@
+/**
+ * Orbit state machine — Mission Control (PRD-055 §5.2).
+ *
+ * The "orbit" is the current phase of the session. The status bar reads
+ * from this module; the REPL pushes events into it. It is intentionally a
+ * pure state machine — no I/O, no side effects, no globals. Each REPL
+ * creates one instance.
+ *
+ *   const orbit = createOrbit();
+ *   orbit.on('change', state => statusBar.render(state));
+ *   orbit.onEvent({ type: 'tool_call', data: { tool: 'edit_file' } });
+ *
+ * States (PRD §5.2):
+ *   IDLE        — waiting for user input
+ *   DISCOVERY   — first message until first plan or edit
+ *   PLANNING    — preflight plan running OR plan() sub-agent active
+ *   EXECUTION   — write/edit/shell tools firing
+ *   ALIGNMENT   — tests / validators running
+ *   AWAITING    — approval required
+ *   PAUSED      — user pressed `p`
+ *
+ * Transitions are derived from existing backend SSE events. We never
+ * teach the backend about orbits; the CLI infers them from tool activity.
+ */
+
+// Tool families used for orbit inference. Mirrors src/ui/icons.mjs but
+// scoped to the few orbits actually need.
+const PLANNING_TOOLS = new Set(['plan']);
+const EXECUTION_TOOLS = new Set(['edit_file', 'write_file', 'write_project', 'shell', 'delete_file']);
+const ALIGNMENT_TOOLS = new Set(['run_tests', 'validate_build', 'lint_check', 'validate_file', 'validate_structure', 'git_diff', 'git_status']);
+const RESEARCH_TOOLS  = new Set(['search_code', 'search_files', 'grep', 'read_file', 'read_files', 'list_files', 'analyze_code', 'get_project_overview', 'explore']);
+
+export const ORBITS = Object.freeze({
+  IDLE:      'IDLE',
+  DISCOVERY: 'DISCOVERY',
+  PLANNING:  'PLANNING',
+  EXECUTION: 'EXECUTION',
+  ALIGNMENT: 'ALIGNMENT',
+  AWAITING:  'AWAITING',
+  PAUSED:    'PAUSED',
+});
+
+/**
+ * @returns the snapshot consumed by the status bar.
+ */
+function snapshot(s) {
+  return {
+    orbit:           s.orbit,
+    task:            s.task || '',
+    turn:            s.turn,
+    maxTurn:         s.maxTurn,
+    cost:            s.cost,
+    activeTool:      s.activeTool || '',
+    subAgents:       s.subAgents,
+    paused:          s.paused,
+    awaitingTier:    s.awaitingTier || null,
+    awaitingTool:    s.awaitingTool || '',
+  };
+}
+
+export function createOrbit() {
+  const state = {
+    orbit:        ORBITS.IDLE,
+    task:         '',
+    turn:         0,
+    maxTurn:      0,
+    cost:         0,
+    activeTool:   '',
+    subAgents:    0,           // count of currently-active sub-agents
+    paused:       false,
+    awaitingTool: '',
+    awaitingTier: null,
+    _hasEdited:   false,       // for DISCOVERY → EXECUTION transition
+    _resumeOrbit: null,        // remembered orbit when paused
+  };
+
+  const listeners = new Set();
+
+  function emit() {
+    const snap = snapshot(state);
+    for (const fn of listeners) {
+      try { fn(snap); } catch {}
+    }
+  }
+
+  function setOrbit(next) {
+    if (state.paused && next !== ORBITS.PAUSED && next !== ORBITS.IDLE) {
+      // While paused, remember the orbit that would have applied but stay paused.
+      state._resumeOrbit = next;
+      return;
+    }
+    if (state.orbit === next) return;
+    state.orbit = next;
+    emit();
+  }
+
+  function inferOrbitFromTool(toolName) {
+    if (state.paused) return null;
+    if (state.subAgents > 0 && PLANNING_TOOLS.has(toolName)) return ORBITS.PLANNING;
+    if (PLANNING_TOOLS.has(toolName)) return ORBITS.PLANNING;
+    if (EXECUTION_TOOLS.has(toolName)) {
+      state._hasEdited = true;
+      return ORBITS.EXECUTION;
+    }
+    if (ALIGNMENT_TOOLS.has(toolName)) return ORBITS.ALIGNMENT;
+    if (RESEARCH_TOOLS.has(toolName)) {
+      // Stay in DISCOVERY until first edit; afterwards research stays in
+      // current orbit (EXECUTION) so the status doesn't flicker back.
+      return state._hasEdited ? null : ORBITS.DISCOVERY;
+    }
+    return null;
+  }
+
+  return {
+    state: () => snapshot(state),
+
+    on(event, fn) {
+      if (event !== 'change') return () => {};
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+
+    // ── Inbound events from the REPL ──────────────────────────────────
+
+    onUserInput(text) {
+      // First user message of the session OR a new turn opens DISCOVERY.
+      state.turn++;
+      state.task = (text || '').replace(/\s+/g, ' ').trim().slice(0, 80);
+      state._hasEdited = false;
+      state.activeTool = '';
+      setOrbit(ORBITS.DISCOVERY);
+    },
+
+    onMaxTurn(n) {
+      if (typeof n === 'number' && n > 0) {
+        state.maxTurn = n;
+        emit();
+      }
+    },
+
+    onTask(text) {
+      if (!text) return;
+      state.task = String(text).replace(/\s+/g, ' ').trim().slice(0, 80);
+      emit();
+    },
+
+    onCost(value) {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        state.cost = value;
+        emit();
+      }
+    },
+
+    onToolCall(toolName) {
+      state.activeTool = toolName || '';
+      const next = inferOrbitFromTool(toolName);
+      if (next) setOrbit(next);
+      else emit();
+    },
+
+    onToolResult() {
+      state.activeTool = '';
+      emit();
+    },
+
+    onSubAgentStart() {
+      state.subAgents = Math.max(0, state.subAgents) + 1;
+      setOrbit(ORBITS.PLANNING);
+    },
+
+    onSubAgentEnd() {
+      state.subAgents = Math.max(0, state.subAgents - 1);
+      // Fall back to whatever the parent was doing — we don't track that
+      // precisely, so go to EXECUTION if an edit has happened, else
+      // DISCOVERY. The next tool_call event will refine.
+      if (state.subAgents === 0) {
+        setOrbit(state._hasEdited ? ORBITS.EXECUTION : ORBITS.DISCOVERY);
+      } else {
+        emit();
+      }
+    },
+
+    onApprovalRequired({ tool, tier } = {}) {
+      state.awaitingTool = tool || '';
+      state.awaitingTier = tier || null;
+      setOrbit(ORBITS.AWAITING);
+    },
+
+    onApprovalResolved() {
+      state.awaitingTool = '';
+      state.awaitingTier = null;
+      // Drop back to the inferred orbit for the active tool, or EXECUTION
+      // if we have an active tool but can't classify, or IDLE.
+      const inferred = inferOrbitFromTool(state.activeTool) || (state._hasEdited ? ORBITS.EXECUTION : ORBITS.DISCOVERY);
+      setOrbit(inferred);
+    },
+
+    onComplete({ cost } = {}) {
+      if (typeof cost === 'number') state.cost = cost;
+      state.activeTool = '';
+      setOrbit(ORBITS.IDLE);
+    },
+
+    onPause() {
+      if (state.paused) return;
+      state.paused = true;
+      state._resumeOrbit = state.orbit;
+      state.orbit = ORBITS.PAUSED;
+      emit();
+    },
+
+    onResume() {
+      if (!state.paused) return;
+      state.paused = false;
+      const resume = state._resumeOrbit || ORBITS.IDLE;
+      state._resumeOrbit = null;
+      state.orbit = resume;
+      emit();
+    },
+
+    /**
+     * Generic event router so the REPL can feed raw SSE events without a
+     * giant switch in this module. Returns true if the event was handled.
+     */
+    onEvent(event) {
+      if (!event || !event.type) return false;
+      const { type, data } = event;
+      switch (type) {
+        case 'tool_call':
+        case 'tool_request':
+          this.onToolCall(data?.tool || '');
+          return true;
+        case 'tool_result':
+        case 'tool_done':
+          this.onToolResult();
+          return true;
+        case 'sub_agent_start':
+          this.onSubAgentStart();
+          return true;
+        case 'sub_agent_complete':
+          this.onSubAgentEnd();
+          return true;
+        case 'approval_required':
+          this.onApprovalRequired({ tool: data?.tool, tier: data?.tier });
+          return true;
+        case 'approval_granted':
+        case 'approval_denied':
+          this.onApprovalResolved();
+          return true;
+        case 'complete': {
+          const usage = data?.usage || {};
+          this.onComplete({ cost: usage.total_cost_usd ?? usage.cost_usd });
+          return true;
+        }
+        case 'plan_created':
+          this.onTask(data?.title || data?.task || '');
+          return true;
+        default:
+          return false;
+      }
+    },
+  };
+}

package/src/state/verbosity.mjs

@@ -0,0 +1,99 @@
+/**
+ * Verbosity modes — Mission Control (PRD-055 §12).
+ *
+ *   quiet     Folded summary only. Sub-agent inner tools hidden.
+ *   default   Folded summary. Sub-agent header shown, inner tools folded.
+ *   verbose   Folded summary. Sub-agent inner tools shown.
+ *   surgical  Expanded tool details + raw model reasoning.
+ *
+ * Persisted to `~/.kepler/config.json` under the `verbosity` key so the
+ * choice survives across sessions.
+ *
+ *   import { getVerbosity, setVerbosity, showSubAgentTools, showReasoning } from './verbosity.mjs';
+ *
+ * No imports from the REPL — this module is pure state + filesystem.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const MODES = Object.freeze({
+  QUIET:    'quiet',
+  DEFAULT:  'default',
+  VERBOSE:  'verbose',
+  SURGICAL: 'surgical',
+});
+
+const VALID = new Set(Object.values(MODES));
+
+const CONFIG_DIR = process.env.KEPLER_HOME || path.join(os.homedir(), '.kepler');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+
+let _cached = null;
+
+function readConfig() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); }
+  catch { return {}; }
+}
+
+function writeConfig(obj) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(obj, null, 2));
+  } catch { /* best effort */ }
+}
+
+/** Read the current mode (falls back to default). */
+export function getVerbosity() {
+  if (_cached) return _cached;
+  const v = readConfig().verbosity;
+  _cached = VALID.has(v) ? v : MODES.DEFAULT;
+  return _cached;
+}
+
+/** Update the persisted mode. Returns the new mode. */
+export function setVerbosity(mode) {
+  if (!VALID.has(mode)) throw new Error(`Unknown verbosity mode: ${mode}`);
+  const cfg = readConfig();
+  cfg.verbosity = mode;
+  writeConfig(cfg);
+  _cached = mode;
+  return mode;
+}
+
+/** Force-reload from disk (used by tests). */
+export function _resetCache() { _cached = null; }
+
+// ── Predicates — let other modules ask "should I render X?" ─────────────
+
+/** Should sub-agent inner tool cards be printed? */
+export function showSubAgentTools(mode = getVerbosity()) {
+  return mode === MODES.VERBOSE || mode === MODES.SURGICAL;
+}
+
+/** Should raw model reasoning be printed? */
+export function showReasoning(mode = getVerbosity()) {
+  return mode === MODES.SURGICAL;
+}
+
+/** Should tool cards default to expanded instead of folded? */
+export function defaultExpanded(mode = getVerbosity()) {
+  return mode === MODES.SURGICAL;
+}
+
+/** Should markdown be rendered? (only `surgical` shows raw, others render) */
+export function renderMarkdown(mode = getVerbosity()) {
+  return mode !== MODES.SURGICAL;
+}
+
+/** Per-mode label for /help and status display. */
+export function label(mode = getVerbosity()) {
+  switch (mode) {
+    case MODES.QUIET:    return 'quiet (compact)';
+    case MODES.DEFAULT:  return 'default';
+    case MODES.VERBOSE:  return 'verbose (sub-agent tools visible)';
+    case MODES.SURGICAL: return 'surgical (everything shown)';
+    default:             return String(mode || 'default');
+  }
+}

package/src/terminal/ansi.mjs

@@ -1,10 +1,16 @@
 /**
- * ANSI Terminal Renderer — zero dependencies, zero flickering.
+ * ANSI Terminal Renderer — cursor control, box drawing, status bars.
  *
- * Provides cursor control, colors, box drawing, progress bars,
- * in-place updates, and a persistent status bar.
+ * Color helpers (the `c` object) now route through the semantic palette
+ * (`src/ui/palette.mjs`) so the entire CLI honors the Kepler brand and
+ * tier fallbacks (truecolor, ansi256, ansi16, none) without touching
+ * each call site. Hot-swap-friendly: external semantics like `c.red`,
+ * `c.bold`, `c.cyan` are preserved as the legacy contract; new code
+ * should prefer importing `paint` directly.
  */
 
+import { paint } from '../ui/palette.mjs';
+
 const ESC = '\x1b[';
 const write = (s) => process.stderr.write(s);
 
@@ -27,27 +33,43 @@ export const cursor = {
 };
 
 // ── Colors ──
+// Legacy color names re-mapped onto semantic palette tokens. The CLI's
+// branding is centralized in palette.mjs; this object is preserved only
+// so existing imports keep compiling. Internal Kepler color choices are
+// documented next to each mapping for the next code review.
+
+const identity = (s) => String(s ?? '');
 
 export const c = {
-  reset:   (s) => `${ESC}0m${s}${ESC}0m`,
-  bold:    (s) => `${ESC}1m${s}${ESC}0m`,
-  dim:     (s) => `${ESC}2m${s}${ESC}0m`,
-  italic:  (s) => `${ESC}3m${s}${ESC}0m`,
-  underline: (s) => `${ESC}4m${s}${ESC}0m`,
-  red:     (s) => `${ESC}31m${s}${ESC}0m`,
-  green:   (s) => `${ESC}32m${s}${ESC}0m`,
-  yellow:  (s) => `${ESC}33m${s}${ESC}0m`,
-  blue:    (s) => `${ESC}34m${s}${ESC}0m`,
-  magenta: (s) => `${ESC}35m${s}${ESC}0m`,
-  brand:   (s) => `${ESC}36m${s}${ESC}0m`,
-  cyan:    (s) => `${ESC}94m${s}${ESC}0m`,
-  cyanRegular: (s) => `${ESC}36m${s}${ESC}0m`,
-  cyanBold: (s) => `${ESC}1;36m${s}${ESC}0m`,
-  white:   (s) => `${ESC}97m${s}${ESC}0m`,
-  gray:    (s) => `${ESC}90m${s}${ESC}0m`,
-  bgRed:   (s) => `${ESC}41m${s}${ESC}0m`,
-  bgGreen: (s) => `${ESC}42m${s}${ESC}0m`,
-  bgCyan:  (s) => `${ESC}46m${s}${ESC}0m`,
+  reset:       identity,                       // palette already wraps with RESET
+
+  // Styles — work at every tier
+  bold:        paint.bold,
+  dim:         paint.dim,
+  italic:      paint.italic,
+  underline:   paint.underline,
+
+  // State semantics
+  red:         paint.state.danger,             // failure / hard error
+  green:       paint.state.success,            // pass / aligned
+  yellow:      paint.state.warn,               // soft warn / retry
+
+  // Brand semantics
+  blue:        paint.brand.primary,            // headers, primary brand
+  magenta:     paint.brand.accent,             // attention required
+  brand:       paint.brand.primary,            // primary brand surface
+  cyan:        paint.brand.data,               // code / file paths
+  cyanRegular: paint.brand.data,
+  cyanBold:    (s) => paint.bold(paint.brand.data(s)),
+
+  // Text semantics
+  white:       paint.text.primary,             // primary text
+  gray:        paint.text.dim,                 // hints, metadata, dim text
+
+  // Backgrounds — kept as raw ANSI; rarely used and have no palette analog
+  bgRed:       (s) => `${ESC}41m${String(s ?? '')}${ESC}0m`,
+  bgGreen:     (s) => `${ESC}42m${String(s ?? '')}${ESC}0m`,
+  bgCyan:      (s) => `${ESC}46m${String(s ?? '')}${ESC}0m`,
 };
 
 // ── Box Drawing ──
@@ -399,7 +421,7 @@ export function formatElapsed(startMs) {
 
 // ── Format Cost ──
 
-import { calculateCost, formatCostValue } from '../core/pricing.mjs';
+import { calculateCost, formatCostValue, costToCredits, formatCredits } from '../core/pricing.mjs';
 
 /**
  * Format cost from token counts.
@@ -407,15 +429,13 @@ import { calculateCost, formatCostValue } from '../core/pricing.mjs';
  * or a single usage object with optional per-model breakdown.
  */
 export function formatCost(inputOrUsage, outputTokens) {
-  // New API: pass a usage object directly
   if (typeof inputOrUsage === 'object' && inputOrUsage !== null) {
     const { total } = calculateCost(inputOrUsage);
-    return formatCostValue(total);
+    return formatCredits(costToCredits(total));
   }
-  // Legacy API: flat input/output token counts, default pricing
   const { total } = calculateCost({
     input_tokens: inputOrUsage || 0,
     output_tokens: outputTokens || 0,
   });
-  return formatCostValue(total);
+  return formatCredits(costToCredits(total));
 }