@axplusb/kepler 1.0.10 → 2.0.2

package/src/ui/sub-agent.mjs

@@ -0,0 +1,152 @@
+/**
+ * Sub-agent block renderer — Mission Control (PRD-055 §7).
+ *
+ * Renders the open/close pair for a sub-agent block, dimmed throughout so
+ * the primary agent reads bright by contrast. Inner tool cards are indented
+ * via the `subAgentIndent()` helper so they nest visually under the header.
+ *
+ *   🛰️ explore "JWT lifecycle"  ▸ running (deepseek/deepseek-v4-flash)
+ *        🔭 Search code "expire"        → 6 matches
+ *        🔭 Read file auth.py L120-180   → 60 lines
+ *        └ ✅ returned 3 files identified · $0.004 · 2.1s
+ *
+ * Maintains a depth stack so concurrent / nested sub-agents indent further
+ * and so callers can ask `inSubAgent()` / `depth()` without threading state.
+ *
+ * No I/O — caller writes the returned strings to stderr. This keeps the
+ * module testable from a plain Node script.
+ */
+
+import { paint } from './palette.mjs';
+import { icons } from './icons.mjs';
+
+const SUB_ICONS = {
+  explore: '🔭',
+  plan:    '📐',
+  verify:  '✅',
+  debug:   '🪲',
+  refactor:'♻️',
+};
+
+// ── Active stack ─────────────────────────────────────────────────────────
+
+const _stack = []; // [{ id, type, startedAt }]
+
+/** How many sub-agents are currently open. */
+export function depth() { return _stack.length; }
+export function inSubAgent() { return _stack.length > 0; }
+
+/**
+ * Indent string for a tool card line nested under N sub-agents.
+ * 5 cols per level matches the existing `'     '` legacy indent.
+ */
+export function subAgentIndent(extraDepth = 0) {
+  const d = _stack.length + extraDepth;
+  if (d <= 0) return '  ';
+  return ' '.repeat(2 + d * 3);
+}
+
+// ── Render ───────────────────────────────────────────────────────────────
+
+/**
+ * Open a sub-agent block. Pushes onto the stack; returns the lines to print.
+ *
+ * @returns {string} ANSI-styled multi-line block (no trailing newline).
+ */
+export function renderSubAgentOpen({ id, type, model, query, parentDepth } = {}) {
+  const t = type || 'sub-agent';
+  const depthBefore = _stack.length;
+  _stack.push({ id: id || `${t}-${depthBefore}-${tag()}`, type: t, startedAt: Date.now() });
+
+  const indent = ' '.repeat(2 + depthBefore * 3);
+  const iconChar = SUB_ICONS[t] || icons.subAgent;
+  const head = `${indent}${iconChar} ${paint.brand.data(t)} ${paint.text.dim(`"${truncate(query || '', 60)}"`)}`;
+  const tag1 = paint.text.dim(`▸ running${model ? ` (${model})` : ''}`);
+
+  return query
+    ? `\n${head}  ${tag1}`
+    : `\n${indent}${iconChar} ${paint.brand.data(t)}  ${tag1}`;
+}
+
+/**
+ * Close the most recent sub-agent block. Pops the stack; returns the close
+ * line with optional cost / token / duration attribution per PRD §7.3.
+ *
+ *   └ ✅ returned 3 files identified · 1.2k tok · $0.004 · 2.1s
+ *   └ ✗ explore agent failed
+ *
+ * Caller passes `success` (default true), `summary` ("returned N files"),
+ * and any of `{ costUsd, tokens, durationS, toolCalls, iterations }`.
+ */
+export function renderSubAgentClose({
+  type,
+  success = true,
+  summary = '',
+  costUsd,
+  tokens,
+  durationS,
+  toolCalls,
+  iterations,
+  error,
+} = {}) {
+  // Match-pop: if the type doesn't match the top of stack we still pop the
+  // top entry — backends never emit interleaved open/close, so this is the
+  // safe behavior.
+  const opened = _stack.pop();
+  const t = type || opened?.type || 'sub-agent';
+  const indent = ' '.repeat(2 + _stack.length * 3);
+
+  if (!success) {
+    const line = `${indent}${paint.text.dim('└')} ${paint.state.danger('✗')} ${paint.text.dim(`${t} agent failed`)}`;
+    if (error) {
+      return `${line}\n${indent}    ${paint.state.danger(truncate(error, 140))}`;
+    }
+    return line;
+  }
+
+  const parts = [];
+  if (toolCalls > 0)              parts.push(`${toolCalls} tools`);
+  if (iterations > 0)             parts.push(`${iterations} iter`);
+  if (tokens > 0)                 parts.push(`${formatTokens(tokens)} tok`);
+  if (typeof costUsd === 'number' && costUsd > 0) parts.push(formatCost(costUsd));
+  if (durationS != null)          parts.push(`${Number(durationS).toFixed(1)}s`);
+  const detail = parts.length ? paint.text.dim(' · ' + parts.join(' · ')) : '';
+
+  const body = summary
+    ? paint.text.dim(summary)
+    : paint.text.dim(`${t} returned`);
+
+  return `${indent}${paint.text.dim('└')} ${paint.state.success('✅')} ${body}${detail}`;
+}
+
+/**
+ * Force-clear the stack. Use after a `complete` event or when cancelling so
+ * a stale entry doesn't keep indenting future output.
+ */
+export function resetSubAgents() { _stack.length = 0; }
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+function truncate(text, n) {
+  const s = String(text || '');
+  return s.length <= n ? s : s.slice(0, n - 1) + '…';
+}
+
+function formatTokens(n) {
+  if (!Number.isFinite(n)) return '0';
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`;
+  return String(Math.round(n));
+}
+
+function formatCost(usd) {
+  if (usd < 0.001) return `$${usd.toFixed(5)}`;
+  if (usd < 0.01)  return `$${usd.toFixed(4)}`;
+  return `$${usd.toFixed(3)}`;
+}
+
+function tag() {
+  // Avoid Date.now()/Math.random() drift across re-renders — depth+counter is
+  // enough to keep ids unique within a process.
+  tag._n = (tag._n || 0) + 1;
+  return tag._n.toString(36);
+}

package/src/ui/term.mjs

@@ -0,0 +1,159 @@
+/**
+ * Terminal capability detection.
+ *
+ * Resolves once at import. Re-evaluation requires `refresh()` (used by tests
+ * and the rare command that toggles a relevant env var mid-process).
+ *
+ * Capability tiers (highest first):
+ *   truecolor - 24-bit RGB (e.g. iTerm2, modern xterm, Windows Terminal)
+ *   ansi256  - 256-color palette
+ *   ansi16   - basic 16 colors
+ *   none     - no color (NO_COLOR=1, dumb terminal, non-TTY without override)
+ */
+
+const TRUECOLOR_TERMS = new Set([
+  'truecolor',
+  '24bit',
+  '24-bit',
+]);
+
+const ANSI256_TERMS = [
+  /-256(color)?$/i,
+  /^xterm/i,
+  /^screen/i,
+  /^tmux/i,
+  /^rxvt-unicode/i,
+  /^alacritty/i,
+];
+
+const DUMB_TERMS = new Set(['', 'dumb', 'unknown']);
+
+function readEnv() {
+  const env = process.env || {};
+  return {
+    NO_COLOR: env.NO_COLOR,
+    FORCE_COLOR: env.FORCE_COLOR,
+    KEPLER_PLAIN: env.KEPLER_PLAIN,
+    COLORTERM: (env.COLORTERM || '').toLowerCase(),
+    TERM: (env.TERM || '').toLowerCase(),
+    TERM_PROGRAM: env.TERM_PROGRAM || '',
+    CI: env.CI,
+  };
+}
+
+function detectColorLevel(env, isTTY) {
+  // Hard opt-out (https://no-color.org). Honored even on TTYs.
+  if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return 'none';
+  if (env.KEPLER_PLAIN === '1') return 'none';
+
+  // Hard opt-in. FORCE_COLOR=1|2|3 maps to ansi16|ansi256|truecolor.
+  // FORCE_COLOR with no value or =true falls through to detection.
+  if (env.FORCE_COLOR !== undefined) {
+    const v = String(env.FORCE_COLOR).trim();
+    if (v === '0' || v === 'false') return 'none';
+    if (v === '1') return 'ansi16';
+    if (v === '2') return 'ansi256';
+    if (v === '3') return 'truecolor';
+    // Any other truthy value: continue detection but allow non-TTY.
+    isTTY = true;
+  }
+
+  // No TTY and not forced: no color.
+  if (!isTTY) return 'none';
+
+  if (DUMB_TERMS.has(env.TERM)) return 'none';
+
+  if (TRUECOLOR_TERMS.has(env.COLORTERM)) return 'truecolor';
+
+  // Some terminal emulators advertise truecolor through TERM_PROGRAM.
+  if (env.TERM_PROGRAM === 'iTerm.app' || env.TERM_PROGRAM === 'WezTerm') {
+    return 'truecolor';
+  }
+  if (env.TERM_PROGRAM === 'vscode' || env.TERM_PROGRAM === 'Apple_Terminal') {
+    return 'ansi256';
+  }
+
+  if (ANSI256_TERMS.some(re => re.test(env.TERM))) return 'ansi256';
+
+  return 'ansi16';
+}
+
+function detectUnicode(env) {
+  if (env.KEPLER_PLAIN === '1') return false;
+  // Most modern terminals on macOS/Linux handle UTF-8.
+  // Windows ConEmu / older terminals are the main holdouts; conservative
+  // fallback when LANG and LC_* are missing or explicitly POSIX.
+  const lang = (process.env.LANG || process.env.LC_ALL || process.env.LC_CTYPE || '').toLowerCase();
+  if (!lang) return process.platform !== 'win32';
+  if (lang.includes('utf')) return true;
+  return false;
+}
+
+function compute() {
+  const env = readEnv();
+  const isTTY = !!(process.stdout && process.stdout.isTTY);
+  const level = detectColorLevel(env, isTTY);
+  return {
+    isTTY,
+    colorLevel: level,                       // 'none' | 'ansi16' | 'ansi256' | 'truecolor'
+    color: level !== 'none',
+    truecolor: level === 'truecolor',
+    ansi256: level === 'ansi256' || level === 'truecolor',
+    unicode: detectUnicode(env),
+    plain: env.KEPLER_PLAIN === '1',
+    columns: (process.stdout && process.stdout.columns) || 80,
+    rows: (process.stdout && process.stdout.rows) || 24,
+    ci: !!env.CI,
+  };
+}
+
+let _capabilities = compute();
+
+/**
+ * Current terminal capabilities. Stable until `refresh()` is called.
+ */
+export function term() {
+  return _capabilities;
+}
+
+/**
+ * Re-run capability detection. Tests, `/config` reloads, or runtime env changes.
+ */
+export function refresh() {
+  _capabilities = compute();
+  return _capabilities;
+}
+
+/**
+ * Listen for terminal resizes. Returns an unsubscribe function.
+ * Callers receive the latest capabilities object (with updated columns/rows).
+ */
+export function onResize(handler) {
+  if (typeof handler !== 'function') return () => {};
+  const stream = process.stdout;
+  if (!stream || typeof stream.on !== 'function') return () => {};
+
+  const onChange = () => {
+    _capabilities = {
+      ..._capabilities,
+      columns: stream.columns || _capabilities.columns,
+      rows: stream.rows || _capabilities.rows,
+    };
+    handler(_capabilities);
+  };
+  stream.on('resize', onChange);
+  return () => stream.off('resize', onChange);
+}
+
+/**
+ * Force a capability level. Test-only escape hatch.
+ * Pass `null` to clear and re-detect.
+ */
+export function _setForTesting(overrides) {
+  if (overrides === null) {
+    _capabilities = compute();
+    return _capabilities;
+  }
+  _capabilities = { ..._capabilities, ...overrides };
+  return _capabilities;
+}

package/src/ui/tool-card.mjs

@@ -0,0 +1,322 @@
+/**
+ * Tool cards — Mission Control (PRD-055 §6).
+ *
+ * One-line summary per tool: icon + label + args + outcome.
+ *
+ *   🔭 search_code "JWT validation"             → 4 matches in 2 files
+ *   🔭 read_file auth.py L42-L88                → 47 lines
+ *   🛠️ edit_file auth.py                        → +12 −4
+ *   ⚙️  shell "npm test"                         → passed in 1.2s
+ *
+ * Two render points:
+ *
+ *   formatCardHead(tool, args)            — at tool invocation (no outcome)
+ *   formatCard({ tool, args, result, … })  — once the result arrives
+ *
+ * Cards are recorded in a small ring buffer (`recordCard`, `lastCard`,
+ * `getCard`) so the expand handler in repl.mjs can re-render details on `d`
+ * / `/last` / `/expand <n>` without holding state in the REPL itself.
+ *
+ * No I/O — callers (repl, demo, headless adapter) are responsible for
+ * `process.stderr.write(...)`. This keeps the module pure and testable.
+ */
+
+import { paint, width as visibleWidth } from './palette.mjs';
+import { icon, toolFamily } from './icons.mjs';
+import { term } from './term.mjs';
+import {
+  toolDisplayLabel,
+  toolDisplaySummary,
+  formatShellCommand,
+} from '../terminal/tool-display.mjs';
+
+// ── Family → label colorizer ─────────────────────────────────────────────
+
+function paintLabel(tool, label) {
+  switch (toolFamily(tool)) {
+    case 'subAgent': return paint.brand.data(label);
+    case 'search':   return paint.text.primary(label);
+    case 'write':    return paint.brand.primary(label);
+    case 'shell':    return paint.state.warn(label);
+    case 'network':  return paint.brand.accent(label);
+    default:         return paint.text.primary(label);
+  }
+}
+
+// ── Args summary ─────────────────────────────────────────────────────────
+
+function formatArgs(tool, args, cwd) {
+  const summary = toolDisplaySummary(tool, args || {}, { cwd });
+  if (!summary) return '';
+  if (tool === 'shell') {
+    return formatShellCommand(summary, paintShellAdapter);
+  }
+  return paint.text.muted(summary);
+}
+
+// Adapter so formatShellCommand (from legacy tool-display.mjs) keeps working
+// against the new palette. It expects an object with .red/.blue/.yellow/.white.
+const paintShellAdapter = {
+  red:    (s) => paint.state.danger(s),
+  blue:   (s) => paint.brand.data(s),
+  yellow: (s) => paint.state.warn(s),
+  white:  (s) => paint.text.primary(s),
+};
+
+// ── Result → outcome summary ─────────────────────────────────────────────
+
+/**
+ * Summarize a tool result into a compact outcome label.
+ *
+ * @returns {{ text: string, tone: 'success'|'warn'|'danger'|'dim' }}
+ */
+export function summarizeResult(tool, data) {
+  if (!data) return { text: '', tone: 'dim' };
+
+  if (data._blocked) {
+    return { text: firstOutputLine(data) || 'blocked', tone: 'danger' };
+  }
+  if (data.success === false) {
+    const msg = String(data.error || firstOutputLine(data) || 'failed').slice(0, 140);
+    return { text: msg, tone: 'danger' };
+  }
+
+  switch (tool) {
+    case 'read_file': {
+      const lines = data._total_lines || lineCount(data.output || data.output_preview);
+      return { text: `${lines} line${lines === 1 ? '' : 's'}`, tone: 'success' };
+    }
+    case 'read_files':
+      return { text: 'files read', tone: 'success' };
+
+    case 'search_code':
+    case 'search_files':
+    case 'grep': {
+      const matches = countMatches(data);
+      const files = countMatchFiles(data);
+      if (matches === 0) return { text: 'no matches', tone: 'warn' };
+      const filesPart = files > 0 ? ` in ${files} file${files === 1 ? '' : 's'}` : '';
+      return { text: `${matches} match${matches === 1 ? '' : 'es'}${filesPart}`, tone: 'success' };
+    }
+
+    case 'list_files': {
+      const n = lineCount(data.output);
+      return { text: n > 0 ? `${n} item${n === 1 ? '' : 's'}` : 'empty', tone: 'success' };
+    }
+
+    case 'edit_file':
+    case 'write_file':
+    case 'write_project': {
+      const delta = diffDelta(data);
+      if (delta) return { text: delta, tone: 'success' };
+      return { text: 'updated', tone: 'success' };
+    }
+
+    case 'delete_file':
+      return { text: 'deleted', tone: 'warn' };
+
+    case 'shell':
+    case 'run_tests':
+    case 'validate_build':
+    case 'lint_check':
+    case 'validate_file':
+    case 'validate_structure': {
+      const exit = data.exit_code ?? data.exitCode;
+      if (exit != null && exit !== 0) {
+        return { text: `exit ${exit}`, tone: 'danger' };
+      }
+      const head = firstOutputLine(data).slice(0, 100);
+      return { text: head || 'ok', tone: 'success' };
+    }
+
+    case 'analyze_code': {
+      // Backend returns "filename (N lines, ext)" — the filename already
+      // appears in the card head, so strip it and keep just the metadata.
+      const head = firstOutputLine(data);
+      const m = head.match(/\((\d+)\s+lines?,?\s+([^)]+)\)/);
+      if (m) return { text: `${m[1]} lines · ${m[2].trim()}`, tone: 'success' };
+      return { text: head.slice(0, 80) || 'done', tone: 'success' };
+    }
+
+    case 'plan':
+    case 'explore':
+    case 'verify':
+    case 'debug':
+    case 'refactor': {
+      const head = firstOutputLine(data).slice(0, 100);
+      return { text: head || 'done', tone: 'success' };
+    }
+
+    default: {
+      const head = firstOutputLine(data).slice(0, 100);
+      return { text: head || 'done', tone: 'success' };
+    }
+  }
+}
+
+function firstOutputLine(data) {
+  const o = data?.output_preview || data?.output || data?.message || '';
+  return String(o).split('\n').map(l => l.trim()).find(Boolean) || '';
+}
+
+function lineCount(s) {
+  if (!s) return 0;
+  return String(s).split('\n').filter(Boolean).length;
+}
+
+function countMatches(data) {
+  if (typeof data?.match_count === 'number') return data.match_count;
+  return lineCount(data?.output);
+}
+
+function countMatchFiles(data) {
+  if (typeof data?.file_count === 'number') return data.file_count;
+  const out = String(data?.output || '');
+  if (!out) return 0;
+  const files = new Set();
+  for (const line of out.split('\n')) {
+    const m = line.match(/^([^:]+):/);
+    if (m) files.add(m[1]);
+  }
+  return files.size;
+}
+
+function diffDelta(data) {
+  const add = data?.lines_added ?? data?.additions;
+  const rem = data?.lines_removed ?? data?.deletions;
+  if (add == null && rem == null) return '';
+  const a = add ?? 0;
+  const r = rem ?? 0;
+  return `+${a} −${r}`;
+}
+
+function tone(text, t) {
+  switch (t) {
+    case 'success': return paint.state.success(text);
+    case 'warn':    return paint.state.warn(text);
+    case 'danger':  return paint.state.danger(text);
+    case 'dim':
+    default:        return paint.text.dim(text);
+  }
+}
+
+// ── Card head (printed at invocation) ────────────────────────────────────
+
+/**
+ * Render the leading half of a card — icon + colored label + args.
+ * Width-aware: truncates args from the left when the line would overflow.
+ */
+export function formatCardHead(tool, args, opts = {}) {
+  const cwd = opts.cwd || safeCwd();
+  const cols = opts.columns || term().columns || 120;
+  const indent = opts.indent || '  ';
+
+  const iconText  = icon(tool);
+  const label     = toolDisplayLabel(tool);
+  const argsText  = formatArgs(tool, args, cwd);
+
+  const leadVisible = visibleWidth(`${indent}${iconText} ${label}`);
+  const budget = Math.max(20, cols - leadVisible - 4);
+  const argsTruncated = truncateMiddle(argsText, budget);
+
+  const head = `${indent}${iconText} ${paintLabel(tool, label)}`;
+  return argsTruncated ? `${head} ${argsTruncated}` : head;
+}
+
+/**
+ * Render a full card with outcome.
+ *
+ *   🔭 search_code "JWT"              → 4 matches in 2 files · 120ms
+ *
+ * `result` is the tool_result data from the SSE stream (same shape as
+ * `renderToolResult` consumed). `durationMs` overrides what's on the result.
+ */
+export function formatCard({ tool, args, result, durationMs, indent, columns, cwd } = {}) {
+  const cols = columns || term().columns || 120;
+  const head = formatCardHead(tool, args, { indent, columns: cols, cwd });
+
+  const summary = summarizeResult(tool, result);
+  const duration = formatDuration(durationMs ?? result?.duration_ms ?? (result?.duration_s != null ? result.duration_s * 1000 : null));
+
+  if (!summary.text && !duration) return head;
+
+  const arrow = paint.text.dim('→');
+  const body  = summary.text ? tone(summary.text, summary.tone) : '';
+  const tail  = duration ? paint.text.dim(` · ${duration}`) : '';
+
+  const candidate = `${head}  ${arrow} ${body}${tail}`;
+  if (visibleWidth(candidate) <= cols) return candidate;
+
+  // Doesn't fit on one line → push outcome to a separate gutter line.
+  const gutterIndent = (indent || '  ') + paint.text.dim('⎿  ');
+  return `${head}\n${gutterIndent}${arrow} ${body}${tail}`;
+}
+
+function truncateMiddle(text, max) {
+  if (!text) return '';
+  if (visibleWidth(text) <= max) return text;
+  // Truncate the plain text and re-trust palette helpers to skip codes.
+  const plain = text.replace(/\x1b\[[0-9;]*m/g, '');
+  if (plain.length <= max) return text;
+  const keep = Math.max(8, max - 3);
+  const head = plain.slice(0, Math.floor(keep / 2));
+  const tail = plain.slice(plain.length - Math.ceil(keep / 2));
+  return paint.text.muted(`${head}…${tail}`);
+}
+
+function formatDuration(ms) {
+  if (ms == null || !Number.isFinite(ms)) return '';
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function safeCwd() {
+  try { return process.cwd(); } catch { return ''; }
+}
+
+// ── Ring buffer of recent cards (for expand / /last) ─────────────────────
+
+const MAX_CARDS = 50;
+const _cards = [];
+
+/**
+ * Record a card by its call_id (or generated id). Returns the stored entry.
+ * The entry is updated in place when the matching result arrives.
+ */
+export function recordCard({ id, tool, args, head, result, durationMs, startedAt }) {
+  const entry = { id, tool, args, head, result: result || null, durationMs: durationMs ?? null, startedAt: startedAt ?? null };
+  // Replace if same id already exists (e.g. tool_call followed by tool_result)
+  const existing = _cards.findIndex(c => c.id != null && c.id === id);
+  if (existing >= 0) {
+    _cards[existing] = { ..._cards[existing], ...entry };
+    return _cards[existing];
+  }
+  _cards.push(entry);
+  if (_cards.length > MAX_CARDS) _cards.shift();
+  return entry;
+}
+
+/** Most recently recorded card (the one `d` / `/last` should expand). */
+export function lastCard() {
+  return _cards[_cards.length - 1] || null;
+}
+
+/** Look up a card by id, or 1-based index from the tail (-1 == lastCard). */
+export function getCard(idOrIndex) {
+  if (idOrIndex == null) return lastCard();
+  if (typeof idOrIndex === 'number') {
+    if (idOrIndex < 0) return _cards[_cards.length + idOrIndex] || null;
+    return _cards[idOrIndex] || null;
+  }
+  return _cards.find(c => c.id === idOrIndex) || null;
+}
+
+/** All recorded cards in order. */
+export function allCards() {
+  return _cards.slice();
+}
+
+/** Drop all recorded cards (used by tests and `/clear`). */
+export function clearCards() {
+  _cards.length = 0;
+}