@bahulam/code 0.1.1

package/src/ui/slash-commands.mjs

@@ -0,0 +1,257 @@
+/**
+ * Slash Commands — canonical catalog + input normalizer.
+ *
+ * This module is the ONE source of truth for the REPL's slash commands.
+ * Consumers:
+ *   - src/terminal/repl.mjs imports COMMANDS, HELP_GROUPS, etc. for its
+ *     runtime dispatch and slash-hint suggestions.
+ *   - src/index.mjs iterates COMMANDS for `bahulam-code --help` output.
+ *
+ * The runtime *handlers* live in repl.mjs (they need session/ctx access
+ * that only the REPL has). This module is data-only + pure normalization.
+ */
+
+// name -> one-line description (bare string).
+export const COMMANDS = {
+  '/help':        'Show commands',
+  '/login':       'Sign in via browser',
+  '/whoami':      'Show logged-in user',
+  '/status':      'Session status & system info',
+  '/plan':        'Show plan/tasks',
+  '/tasks':       'Show or update project tasks',
+  '/stats':       'Progress bars & metrics',
+  '/new':         'Start a new session',
+  '/clear':       'Clear conversation',
+  '/git':         'Git status',
+  '/diff':        'Git diff',
+  '/cost':        'Show session cost',
+  '/model':       'Show or set session model overrides',
+  '/attach':      'Attach image path or clipboard image to next prompt',
+  '/attachments': 'List or clear pending image attachments',
+  '/history':     'Show conversation',
+  '/settings':    'Show policy/settings',
+  '/last':        'Expand last tool output',
+  '/expand':      'Expand tool output by index (or "all")',
+  '/fold':        'Hide previously expanded tool output',
+  '/checkpoint':  'List recent file checkpoints',
+  '/undo':        'Restore the last file checkpoint',
+  '/preflight':   'Re-run the onboarding diagnostic',
+  '/report':      'Save the mission report as markdown',
+  '/why':         'Print the agent reasoning for the last decision',
+  '/map':         'Show the registered project tree',
+  '/budget':      'Set / clear a hard session cost cap',
+  '/quiet':       'Verbosity: hide sub-agent inner tools',
+  '/verbose':     'Verbosity: show sub-agent inner tools',
+  '/surgical':    'Verbosity: show everything (reasoning, expanded tools)',
+  '/compact':     'Compact conversation context',
+  '/agents':      'List available agents',
+  '/run':         'Run a sub-agent or synced workflow',
+  '/explore':     'Code explorer agent',
+  '/review':      'Code review agent',
+  '/architect':   'Feature architect agent',
+  '/safety':      'Show safety guardrail status',
+  '/auto':        'Session autopilot: auto-approve routine tools (dangerous still prompts)',
+  '/approvals':   'List or edit session approval grants',
+  '/revoke':      'Revoke auto-approvals',
+  '/resume':      'Resume a previous session',
+  '/sessions':    'List resumable sessions',
+  '/logout':      'Sign out and clear credentials',
+  '/exit':        'Exit CLI',
+};
+
+// Grouped view for the `/help` interactive display. Each entry is
+// [command-with-args, description] so subcommands appear inline.
+export const HELP_GROUPS = [
+  {
+    key: 'plan',
+    title: 'Plan',
+    summary: 'plan and project tasks',
+    commands: [
+      ['/plan', 'Plan and task overview'],
+      ['/plan status', 'Plan owner and task files'],
+      ['/plan edit', 'Show editable task/plan paths'],
+      ['/tasks', 'List project tasks'],
+      ['/tasks add <text>', 'Add backlog task'],
+      ['/tasks active|blocked|done <text>', 'Append to a task list'],
+    ],
+  },
+  {
+    key: 'status',
+    title: 'Status',
+    summary: 'session, usage, budget',
+    commands: [
+      ['/status', 'Session snapshot'],
+      ['/status context', 'Loaded .bahulam context'],
+      ['/status metrics', 'Progress bars and runtime metrics'],
+      ['/status cost', 'Credits and message window'],
+      ['/model [role] [model]', 'Show or set session model override'],
+      ['/attach <image>', 'Attach image to the next prompt'],
+      ['/attach clipboard', 'Attach image currently copied to macOS/Windows clipboard'],
+      ['/attachments', 'List pending image attachments'],
+      ['/attachments clear', 'Clear pending image attachments'],
+      ['/status budget <amount|clear>', 'Set or clear session budget'],
+    ],
+  },
+  {
+    key: 'history',
+    title: 'History',
+    summary: 'transcript, reports, undo',
+    commands: [
+      ['/history', 'Recent transcript'],
+      ['/history approvals', 'Approval log'],
+      ['/history last', 'Expand last tool output'],
+      ['/history expand [n|all]', 'Expand tool output'],
+      ['/history checkpoint', 'List checkpoints'],
+      ['/history undo', 'Restore latest checkpoint'],
+      ['/history report', 'Save mission report'],
+    ],
+  },
+  {
+    key: 'settings',
+    title: 'Settings',
+    summary: 'auth, policy, verbosity',
+    commands: [
+      ['/settings policy', 'Effective project policy'],
+      ['/settings login', 'Sign in'],
+      ['/settings logout', 'Sign out'],
+      ['/settings whoami', 'Current user'],
+      ['/settings quiet|verbose|surgical', 'Verbosity'],
+      ['/settings revoke', 'Revoke auto-approvals'],
+    ],
+  },
+  {
+    key: 'worktree',
+    title: 'Worktree',
+    summary: 'git and files',
+    commands: [
+      ['/git', 'Git status'],
+      ['/diff', 'Git diff'],
+      ['/map', 'Registered project tree'],
+      ['/preflight', 'Onboarding diagnostic'],
+      ['/safety', 'Safety guardrail status'],
+    ],
+  },
+  {
+    key: 'agents',
+    title: 'Agents',
+    summary: 'specialist modes',
+    commands: [
+      ['/agents', 'List built-in and local agents'],
+      ['/agents create <name>', 'Create .bahulam/agents/<name>.yaml'],
+      ['/agents edit <name>', 'Open local agent YAML'],
+      ['/agents sync [name]', 'Sync all or one local agent to cloud'],
+      ['/run <agent> [instruction]', 'Run a local or built-in agent'],
+      ['/explore <instruction>', 'Explore code'],
+      ['/review <instruction>', 'Review code'],
+      ['/architect <instruction>', 'Design an approach'],
+    ],
+  },
+  {
+    key: 'workflows',
+    title: 'Workflows',
+    summary: 'saved automations',
+    commands: [
+      ['/run <workflow> [instruction]', 'Run a synced workflow if no agent matches'],
+    ],
+  },
+  {
+    key: 'session',
+    title: 'Session',
+    summary: 'resume and clear',
+    commands: [
+      ['/sessions', 'List resumable sessions'],
+      ['/resume [id]', 'Resume a session'],
+      ['/compact', 'Compact conversation context'],
+      ['/new', 'Start a fresh session'],
+      ['/clear', 'Clear conversation'],
+      ['/exit', 'Exit CLI'],
+    ],
+  },
+];
+
+export const HELP_GROUP_ALIASES = new Map(
+  HELP_GROUPS.flatMap(group => [[group.key, group], [group.title.toLowerCase(), group]])
+);
+
+// Old flat commands that the user might still type. Map them to the new
+// namespaced form so completion + help nudge them toward the current UX.
+export const LEGACY_COMMAND_HINTS = {
+  '/stats':      '/status metrics',
+  '/cost':       '/status cost',
+  '/budget':     '/status budget',
+  '/last':       '/history last',
+  '/expand':     '/history expand',
+  '/fold':       '/history fold',
+  '/undo':       '/history undo',
+  '/checkpoint': '/history checkpoint',
+  '/report':     '/history report',
+  '/login':      '/settings login',
+  '/logout':     '/settings logout',
+  '/whoami':     '/settings whoami',
+  '/quiet':      '/settings quiet',
+  '/verbose':    '/settings verbose',
+  '/surgical':   '/settings surgical',
+  '/revoke':     '/settings revoke',
+};
+
+// Namespaced subcommands. `/status metrics` -> `/stats`, etc.
+export const NAMESPACED_COMMANDS = {
+  '/status': {
+    metrics: '/stats',
+    stats:   '/stats',
+    cost:    '/cost',
+    credits: '/cost',
+    budget:  '/budget',
+  },
+  '/history': {
+    last:        '/last',
+    expand:      '/expand',
+    fold:        '/fold',
+    undo:        '/undo',
+    checkpoint:  '/checkpoint',
+    checkpoints: '/checkpoint',
+    report:      '/report',
+  },
+  '/settings': {
+    login:    '/login',
+    logout:   '/logout',
+    whoami:   '/whoami',
+    quiet:    '/quiet',
+    verbose:  '/verbose',
+    surgical: '/surgical',
+    revoke:   '/revoke',
+  },
+};
+
+/**
+ * Normalize a raw slash-command input like "/status metrics arg" into
+ * { cmd: '/stats', rest: 'arg', rawCmd, aliasTarget }, resolving legacy
+ * aliases and namespaced subcommands to their canonical form.
+ *
+ * - `rawCmd`      the lower-cased first token as the user typed it
+ * - `cmd`         the canonical command (namespaced hit if any, else rawCmd)
+ * - `rest`        the remaining args joined with spaces
+ * - `aliasTarget` for legacy flat commands, the new namespaced form to
+ *                 suggest to the user (null when not aliased)
+ */
+export function normalizeCommandInput(input) {
+  const parts = String(input || '').trim().split(/\s+/).filter(Boolean);
+  const rawCmd = (parts[0] || '').toLowerCase();
+  const restParts = parts.slice(1);
+  const sub = (restParts[0] || '').toLowerCase();
+  const namespaced = NAMESPACED_COMMANDS[rawCmd]?.[sub];
+  if (namespaced) {
+    return {
+      cmd: namespaced,
+      rest: restParts.slice(1).join(' '),
+      rawCmd,
+      aliasTarget: null,
+    };
+  }
+  return {
+    cmd: rawCmd,
+    rest: restParts.join(' '),
+    rawCmd,
+    aliasTarget: LEGACY_COMMAND_HINTS[rawCmd] || null,
+  };
+}

package/src/ui/spinner.mjs

@@ -0,0 +1,116 @@
+/**
+ * Single shared spinner — Mission Control (PRD-055 §4.4).
+ *
+ * One spinner instance per process. The repl and status bar consume frames
+ * from the same source so the eye never sees two animations out of phase.
+ *
+ * Usage:
+ *
+ *   const stop = startSpinner('Reading auth.py');
+ *   await doWork();
+ *   stop();                          // clears the line and stops the timer
+ *
+ * Or, for a managed line that already exists (e.g. the status bar):
+ *
+ *   const tick = spinnerFrame();     // current frame, advances on next call
+ *
+ * Behavior:
+ *   - 120ms per frame.
+ *   - Suppressed entirely when stdout is not a TTY or when KEPLER_PLAIN=1.
+ *     The `start`/`stop` API is still safe to call (no-op).
+ *   - Color follows the current orbit (orchestrated by the caller via the
+ *     palette token). Default: brand.primary.
+ *   - ASCII fallback (when no Unicode): 'plain dot rotation'.
+ */
+
+import { paint } from './palette.mjs';
+import { term } from './term.mjs';
+
+// 8-step rotation. The PRD spec calls for ◯ → ◔ → ◑ → ◕ → ● → ◕ → ◑ → ◔
+// which yields a perceptual "breathing" cycle rather than a left-right spin.
+const FRAMES_UTF = ['◯', '◔', '◑', '◕', '●', '◕', '◑', '◔'];
+const FRAMES_ASCII = ['.', 'o', 'O', '@', 'O', 'o', '.', ' '];
+
+const INTERVAL_MS = 120;
+
+let _frame = 0;
+
+/**
+ * Current spinner glyph. Advances the cursor each call.
+ * Honors capability detection automatically.
+ */
+export function spinnerFrame(painter = paint.brand.primary) {
+  const frames = term().unicode ? FRAMES_UTF : FRAMES_ASCII;
+  const ch = frames[_frame % frames.length];
+  _frame = (_frame + 1) % frames.length;
+  return painter ? painter(ch) : ch;
+}
+
+/**
+ * Reset to frame 0 — useful at the start of a new turn so consecutive
+ * tool calls do not inherit each other's phase.
+ */
+export function resetSpinner() {
+  _frame = 0;
+}
+
+/**
+ * Start an inline spinner attached to `text`. Returns a stop function.
+ *
+ * The line is re-rendered in place using carriage return + erase, so the
+ * caller does not need to manage cursor state. If the terminal cannot
+ * render in place (non-TTY, dumb terminal, plain mode), the spinner becomes
+ * a single static line `"… text"` written once.
+ */
+export function startSpinner(text, { stream = process.stderr, painter, color = 'brand.primary' } = {}) {
+  const t = term();
+  if (!t.isTTY || t.plain || !t.color) {
+    try { stream.write(`… ${text}\n`); } catch {}
+    return () => {};
+  }
+
+  const paintFn = painter || tokenPainter(color);
+  let stopped = false;
+
+  const render = () => {
+    if (stopped) return;
+    const glyph = spinnerFrame(paintFn);
+    try {
+      stream.write(`\r\x1b[2K${glyph} ${paint.text.dim(text)}`);
+    } catch {
+      // Stream closed mid-spin — stop quietly.
+      stop();
+    }
+  };
+
+  render();
+  const handle = setInterval(render, INTERVAL_MS);
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(handle);
+    try {
+      stream.write('\r\x1b[2K');
+    } catch {}
+  }
+
+  return stop;
+}
+
+/**
+ * Look up a painter function from a dotted token name (e.g. 'brand.accent').
+ * Falls back to the identity painter when the token does not exist.
+ */
+function tokenPainter(tokenPath) {
+  const [ns, name] = String(tokenPath || '').split('.');
+  const group = paint[ns];
+  if (group && typeof group[name] === 'function') return group[name];
+  return (s) => String(s ?? '');
+}
+
+/**
+ * Interval used by the shared spinner. Exposed for the status bar to
+ * synchronize its own re-paints with the spinner phase.
+ */
+export const SPINNER_INTERVAL_MS = INTERVAL_MS;

package/src/ui/sub-agent.mjs

@@ -0,0 +1,167 @@
+/**
+ * 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
+ *        🔭 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).
+ */
+/**
+ * Reduce a sub-agent query to its human-readable core. Handoff envelopes
+ * ([User intent], ## Work Scope, Schema:, Active roots:) are machine
+ * context — printing them flooded the transcript with 15+ lines per
+ * spawn. Full text stays available via /expand on the recorded card.
+ */
+export function displayQuery(query, max = 140) {
+  let s = String(query || '');
+  const cut = s.search(/\n\s*(?:\[User intent\]|##\s*Work Scope|Schema:\s*kepler\.|Active roots:)/);
+  if (cut >= 0) s = s.slice(0, cut);
+  s = s.replace(/^\[Thoroughness:\s*[^\]]*\]\s*/i, '').replace(/\s+/g, ' ').trim();
+  return truncate(s, max);
+}
+
+export function renderSubAgentOpen({ id, type, 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 shown = displayQuery(query);
+  const head = `${indent}${iconChar} ${paint.brand.data(t)} ${paint.text.dim(`"${shown}"`)}`;
+  const tag1 = paint.text.dim('▸ running');
+
+  return shown
+    ? `\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);
+}