@bahulam/code 0.1.1 → 0.1.3

package/src/terminal/repl.mjs

@@ -25,7 +25,18 @@ import { calculateCost, formatCostValue, formatTokens, costToCredits, formatCred
 import { TarangStreamClient, EVENT_TYPES } from '../core/stream-client.mjs';
 import { AgentHistoryTurnBuilder } from '../core/agent-history.mjs';
 import { JsonlWriter } from '../core/jsonl-writer.mjs';
+import { tapSseEvent, registerBroadcaster } from '../daemon/event-tap.mjs';
+import { startSocketServer } from '../daemon/socket-server.mjs';
+import { resolvePending, interceptApproval, shutdownAllPending, setTimeoutPolicy } from '../daemon/approval-store.mjs';
+import { wireEmit as wireInputLockEmit, resetInputLock } from '../daemon/input-lock.mjs';
+import { startRelayBridge } from '../daemon/relay-client.mjs';
+import { loadRemoteConfig } from '../commands/remote.mjs';
 import { createToolExecutor } from '../core/tool-executor.mjs';
+// PRD-091 Phase 3 preview: opt-in gateway loop path. Set
+// BAHULAM_USE_GATEWAY_LOOP=1 to route the REPL's turn through
+// /v1/agent/turn instead of the local bundled runtime. Falls back to
+// the existing local-agent path if the flag is unset.
+import { createAgentLoop, createGatewaySession } from '../core/loop.mjs';
 import { buildWorkScope, promptProjectRoots } from '../core/work-scope.mjs';
 import { CheckpointManager } from '../core/checkpoints.mjs';
 import { HookRunner } from '../config/hook-runner.mjs';
@@ -49,6 +60,9 @@ import { resolveBackendUrl } from '../core/backend-url.mjs';
 import { formatMessageWindow, lowWindowStatus, messagesRemaining } from '../core/rate-limit-display.mjs';
 import { formatAgentErrorGuidance } from '../core/error-guidance.mjs';
 import { BUILTIN_AGENTS, findBuiltinAgent, localAgentMatches, runAgent, runAgentDefinition } from './agents.mjs';
+import { SkillInstaller } from '../skills/installer.mjs';
+import { SkillsLoader } from '../skills/loader.mjs';
+import { openSkillsPicker, formatSkillsList } from './skills-picker.mjs';
 import { createAgentFile, isVsCodeTerminal, listLocalAgents, openAgentFile, syncAgentsToBackend } from '../agents/scaffold.mjs';
 import { SessionManager } from '../core/session-manager.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
@@ -939,6 +953,163 @@ async function handleAgentsCommand(rest = '', ctx) {
   printAgentsUsage();
 }
 
+function printSkillsUsage() {
+  process.stderr.write(`  ${c.dim('Usage:')}\n`);
+  process.stderr.write(`  ${c.dim('  /skills                       open interactive picker')}\n`);
+  process.stderr.write(`  ${c.dim('  /skills list [--project]      list installed skills')}\n`);
+  process.stderr.write(`  ${c.dim('  /skills install <url|path> [--project] [--force]')}\n`);
+  process.stderr.write(`  ${c.dim('  /skills view <name> [resource]')}\n`);
+  process.stderr.write(`  ${c.dim('  /skills remove <name> [--project]')}\n`);
+  process.stderr.write(`  ${c.dim('  /skills update <name> [--project]')}\n`);
+}
+
+async function handleSkillsCommand(rest = '', ctx) {
+  const parts = String(rest || '').trim().split(/\s+/).filter(Boolean);
+  const hasFlag = (flag) => parts.includes(flag);
+  const positional = parts.filter(p => !p.startsWith('--'));
+  const action = (positional[0] || 'picker').toLowerCase();
+  const scope = hasFlag('--project') ? 'project' : 'global';
+  const cwd = safeCwd();
+  const installer = new SkillInstaller({ cwd });
+  const loader = new SkillsLoader().load(cwd);
+
+  if (action === 'picker' || action === '') {
+    const skills = loader.list({ scope: hasFlag('--all') ? '' : '' });
+    if (!skills.length) {
+      process.stderr.write(`  ${c.dim('No skills installed yet.')}\n`);
+      process.stderr.write(`  ${c.dim('Install one:')} ${c.brand('/skills install https://github.com/<user>/<repo>')}\n`);
+      return;
+    }
+    const rl = ctx?.rl || null;
+    const choice = await openSkillsPicker({ rl, skills });
+    if (!choice) {
+      process.stderr.write(formatSkillsList(skills));
+      return;
+    }
+    if (choice.action === 'view') {
+      try {
+        const view = loader.view(choice.name, null);
+        process.stderr.write(`\n  ${c.bold(view.name)} ${c.dim(`· ${view.source || ''}`)}\n`);
+        if (view.description) process.stderr.write(`  ${c.dim(view.description)}\n`);
+        process.stderr.write(`  ${c.gray('─'.repeat(60))}\n`);
+        process.stderr.write(renderMarkdown(String(view.instructions || '')) + '\n');
+        if (view.resources?.length) {
+          process.stderr.write(`  ${c.dim('Bundled resources:')}\n`);
+          for (const r of view.resources.slice(0, 20)) process.stderr.write(`    ${c.dim('·')} ${r}\n`);
+          if (view.resources.length > 20) process.stderr.write(`    ${c.dim(`(+${view.resources.length - 20} more)`)}\n`);
+          process.stderr.write(`  ${c.dim('View one:')} /skills view ${view.name} <path>\n`);
+        }
+      } catch (err) {
+        process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+      }
+      return;
+    }
+    if (choice.action === 'remove') {
+      try {
+        installer.remove(choice.name, { scope: 'global' });
+        process.stderr.write(`  ${c.green('✓')} ${c.dim('Removed skill:')} ${choice.name}\n`);
+      } catch (err) {
+        // Try project scope if global failed.
+        try {
+          installer.remove(choice.name, { scope: 'project' });
+          process.stderr.write(`  ${c.green('✓')} ${c.dim('Removed skill:')} ${choice.name} ${c.dim('(project)')}\n`);
+        } catch (err2) {
+          process.stderr.write(`  ${c.red(err2.message || String(err2))}\n`);
+        }
+      }
+      return;
+    }
+    return;
+  }
+
+  if (action === 'list' || action === 'ls') {
+    const filter = hasFlag('--all') ? '' : scope;
+    const skills = loader.list({ scope: filter });
+    process.stderr.write(formatSkillsList(skills));
+    return;
+  }
+
+  if (action === 'install') {
+    const source = positional[1];
+    if (!source) {
+      process.stderr.write(`  ${c.yellow('Usage:')} /skills install <git-url|path> [--project] [--force]\n`);
+      return;
+    }
+    try {
+      process.stderr.write(`  ${c.dim('Installing')} ${source} ${c.dim(`→ ${scope}`)}...\n`);
+      const result = installer.install(source, { scope, force: hasFlag('--force') });
+      const unique = [...new Set(result.installed || [])];
+      const dupes = (result.installed?.length || 0) - unique.length;
+      process.stderr.write(`  ${c.green('✓')} ${c.dim('Installed:')} ${unique.join(', ') || '(none)'}\n`);
+      if (dupes > 0) {
+        process.stderr.write(`  ${c.yellow('!')} ${c.dim(`Source shipped ${dupes} duplicate SKILL.md file(s) with the same name — last one won.`)}\n`);
+      }
+      process.stderr.write(`  ${c.dim('Lock file:')} ${result.lock_file}\n`);
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+    }
+    return;
+  }
+
+  if (action === 'view') {
+    const name = positional[1];
+    if (!name) {
+      process.stderr.write(`  ${c.yellow('Usage:')} /skills view <name> [resource-path]\n`);
+      return;
+    }
+    const resource = positional[2] || null;
+    try {
+      const view = loader.view(name, resource);
+      process.stderr.write(`\n  ${c.bold(view.name)}${resource ? c.dim(` · ${resource}`) : ''}\n`);
+      if (!resource && view.description) process.stderr.write(`  ${c.dim(view.description)}\n`);
+      process.stderr.write(`  ${c.gray('─'.repeat(60))}\n`);
+      const body = resource ? view.content : view.instructions;
+      process.stderr.write(renderMarkdown(String(body || '')) + '\n');
+      if (!resource && view.resources?.length) {
+        process.stderr.write(`  ${c.dim('Bundled resources:')}\n`);
+        for (const r of view.resources.slice(0, 20)) process.stderr.write(`    ${c.dim('·')} ${r}\n`);
+        if (view.resources.length > 20) process.stderr.write(`    ${c.dim(`(+${view.resources.length - 20} more)`)}\n`);
+      }
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+    }
+    return;
+  }
+
+  if (action === 'remove' || action === 'rm' || action === 'uninstall') {
+    const name = positional[1];
+    if (!name) {
+      process.stderr.write(`  ${c.yellow('Usage:')} /skills remove <name> [--project]\n`);
+      return;
+    }
+    try {
+      installer.remove(name, { scope });
+      process.stderr.write(`  ${c.green('✓')} ${c.dim('Removed:')} ${name} ${c.dim(`(${scope})`)}\n`);
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+    }
+    return;
+  }
+
+  if (action === 'update' || action === 'upgrade') {
+    const name = positional[1];
+    if (!name) {
+      process.stderr.write(`  ${c.yellow('Usage:')} /skills update <name> [--project]\n`);
+      return;
+    }
+    try {
+      const result = installer.update(name, { scope });
+      process.stderr.write(`  ${c.green('✓')} ${c.dim('Updated:')} ${name} ${c.dim(`(${scope})`)}\n`);
+      if (result?.commit) process.stderr.write(`  ${c.dim('Commit:')} ${result.commit.slice(0, 12)}\n`);
+    } catch (err) {
+      process.stderr.write(`  ${c.red(err.message || String(err))}\n`);
+    }
+    return;
+  }
+
+  printSkillsUsage();
+}
+
 function commandCompletions(line) {
   if (line.startsWith('/help ')) {
     const topic = line.slice('/help '.length).toLowerCase();
@@ -1241,6 +1412,16 @@ function foldedSubAgentName(data = {}) {
   return data?.sub_agent || data?.agent || data?.type || 'sub-agent';
 }
 
+function subAgentStartingLine(agentType = 'sub-agent') {
+  const normalized = String(agentType || 'sub-agent').toLowerCase();
+  if (normalized === 'plan') return '→ preparing plan handoff';
+  if (normalized === 'explore') return '→ starting exploration';
+  if (normalized === 'verify') return '→ preparing verification';
+  if (normalized === 'debug') return '→ isolating failure context';
+  if (normalized === 'refactor') return '→ preparing refactor pass';
+  return `→ starting ${normalized}`;
+}
+
 function ensureFoldedSubAgentTools(agentType) {
   const current = runtime.foldedSubAgentTools;
   if (current && current.agentType === agentType) return current;
@@ -1533,11 +1714,19 @@ function renderEvent(event) {
       const phaseTag = phase === 'mid_turn' ? 'mid-turn' : 'pre-turn';
       const collapsed = Number(data?.collapsed_messages || 0);
       const kept = Number(data?.kept_recent || 0);
-      const before = Number(data?.before_est_tokens || 0);
-      const beforeK = before ? ` · ~${Math.round(before / 1000)}k est tokens` : '';
+      // PRD-213: backend now sends `before_tokens` (real when source is
+      // `ground_truth`, chars/4 estimate when `estimator_fallback`) plus
+      // the resolved threshold. Keep the legacy `before_est_tokens` fall-
+      // back so an older backend that hasn't rolled out yet still renders.
+      const before = Number(data?.before_tokens || data?.before_est_tokens || 0);
+      const threshold = Number(data?.threshold || 160_000);
+      const source = String(data?.source || 'estimator');
+      const tokenLabel = source === 'ground_truth' ? 'real' : 'est';
+      const beforeK = before ? ` · ${Math.round(before / 1000)}k/${Math.round(threshold / 1000)}k ${tokenLabel} tokens` : '';
+      const sourceTag = source === 'ground_truth' ? '' : ` [${source}]`;
       const keptPart = kept ? ` · kept last ${kept}` : '';
       const preview = String(data?.summary_preview || '').trim();
-      process.stderr.write(`  ${c.brand('✎')} ${c.dim(`context summarized (${phaseTag}) · ${collapsed} older message${collapsed === 1 ? '' : 's'} collapsed${keptPart}${beforeK}`)}\n`);
+      process.stderr.write(`  ${c.brand('✎')} ${c.dim(`context summarized (${phaseTag}) · ${collapsed} older message${collapsed === 1 ? '' : 's'} collapsed${keptPart}${beforeK}${sourceTag}`)}\n`);
       if (preview) {
         process.stderr.write(`    ${c.dim('› ' + preview)}\n`);
       }
@@ -1780,6 +1969,7 @@ function renderEvent(event) {
       // Phase per sub-agent run: the status line counts elapsed time and
       // tool calls live ("plan agent · 4 calls · 32s") for the whole run.
       startSpinner(`${agentType} agent`, { phase: `sub:${agentType}:${Date.now()}` });
+      pushSubAgentWindowLine(subAgentStartingLine(agentType));
       break;
     }
 
@@ -1829,7 +2019,12 @@ function renderEvent(event) {
       flushFoldedSubAgentTools();
       const agentType = data?.type || 'sub-agent';
       const usage = data?.usage || {};
-      const tokens = (usage.input_tokens || 0) + (usage.output_tokens || 0);
+      // Output tokens = generation size. Summing input+output across a
+      // multi-iteration sub-agent double-counts the context re-shipped each
+      // iteration (a 16-iter run can inflate to 600k+ "tokens" of which
+      // ~95% is repeated context) — the resulting number reads as usage but
+      // it's really billing accumulation, not useful signal in the close line.
+      const tokens = usage.output_tokens || 0;
       const costUsd = usage.cost_usd ?? usage.total_cost_usd ?? data?.cost_usd ?? null;
       if (typeof costUsd === 'number') session.savedUsd += costUsd;
       const summary = data?.result_summary
@@ -1869,6 +2064,150 @@ function renderEvent(event) {
         session.id = data.session_id;
         // Track in session manager so conversations save to the right file
         if (sessionMgrRef.current) sessionMgrRef.current.setSessionInfo({ session_id: data.session_id });
+        // Wire socket server for attach clients.
+        // renderEvent() is NOT async, so we can't `await startSocketServer(...)`
+        // directly (that fails at import time — "Unexpected reserved word").
+        // Fire-and-forget IIFE, and guard against re-entry on session_info
+        // repeats (backend can re-emit on reconnect; two listen()s on the
+        // same sock path → EADDRINUSE and both server + tap explode).
+        if (process.env.BAHULAM_DAEMON_EVENTLOG === '1' && !session._prd092SocketStarting && !session._prd092SocketServer) {
+          session._prd092SocketStarting = true;
+          const _sid = session.id;
+          (async () => {
+            try {
+              const server = await startSocketServer({
+                sessionId: _sid,
+                onCommand: {
+                  // Slice E — approve/deny now resolve any pending approval
+                  // registered via interceptApproval(). Returns false if the
+                  // apr_id is unknown or already answered (log-only, not an
+                  // error surfaced to the client — the racy nature of two
+                  // attaches answering is expected).
+                  approve: async (payload, attachId) => {
+                    const ok = resolvePending('approve', payload?.apr_id, attachId, payload?.note);
+                    if (!ok) try { process.stderr.write(`[prd-092] approve for unknown apr_id ${payload?.apr_id}\n`); } catch {}
+                  },
+                  deny: async (payload, attachId) => {
+                    const ok = resolvePending('deny', payload?.apr_id, attachId, payload?.note);
+                    if (!ok) try { process.stderr.write(`[prd-092] deny for unknown apr_id ${payload?.apr_id}\n`); } catch {}
+                  },
+                  // Slice C/E — interrupt from an attach holder cancels the
+                  // current turn. Uses the stream client on the closure
+                  // above (streamClient variable is in scope in this file
+                  // at the outer REPL loop; if unavailable, log and skip).
+                  interrupt: async (_payload, _attachId) => {
+                    try { if (typeof streamClient?.cancel === 'function') streamClient.cancel(); } catch {}
+                  },
+                  send_message: async (_payload, _attachId) => {
+                    // Slice C follow-up. Requires plumbing into the turn
+                    // handler; enqueued as a TODO for the daemon slice.
+                  },
+                }
+              });
+              session._prd092SocketServer = server;
+              session._prd092Unregister = registerBroadcaster(evt => server.broadcastEvent(evt));
+              // Slice E — input-lock changes broadcast via the tap so the
+              // input_lock_changed events flow to attached clients + land
+              // in the event log. Emit under the sessionId in scope.
+              wireInputLockEmit((type, data) => {
+                try { tapSseEvent({ type, data }, { sessionId: _sid }); }
+                catch { /* never blocks a lock transition */ }
+              });
+              // Slice E — apply the timeout policy from env (safe default:
+              // 'hold' = never times out). Explicit opt-in via env var so
+              // running unattended is a conscious choice, not a surprise.
+              //   BAHULAM_APPROVAL_TIMEOUT=hold                (default)
+              //   BAHULAM_APPROVAL_TIMEOUT=deny:300            (auto-deny after 5min)
+              //   BAHULAM_APPROVAL_TIMEOUT=allow:300           (auto-approve; gated behind --dangerously-skip-permissions elsewhere)
+              try {
+                const p = String(process.env.BAHULAM_APPROVAL_TIMEOUT || 'hold').trim();
+                const [mode, secStr] = p.split(':');
+                setTimeoutPolicy({
+                  mode: (mode === 'deny' || mode === 'allow') ? mode : 'hold',
+                  durationSec: Number(secStr) || 0,
+                });
+              } catch { /* stay on hold */ }
+              // Slice E — intercept ApprovalManager.check so every prompt
+              // also emits approval_required to attached clients AND can be
+              // resolved by a remote approve/deny command (racing the local
+              // TTY prompt; first answer wins). Only patch once per session.
+              try {
+                if (approval && !approval._prd092Intercepted) {
+                  const orig = approval.check.bind(approval);
+                  approval.check = (tool, args, req, ctx) => interceptApproval(orig, {
+                    tool, args, req, ctx,
+                    sessionId: _sid,
+                    emit: (type, data) => {
+                      try { tapSseEvent({ type, data }, { sessionId: _sid }); }
+                      catch { /* never blocks approval */ }
+                    },
+                  });
+                  approval._prd092Intercepted = true;
+                }
+              } catch (err) {
+                try { process.stderr.write(`[prd-092] approval intercept: ${err.message}\n`); } catch {}
+              }
+              // Slice H — dial the relay if `bahulam remote enable` set the
+              // flag. Bridge is bidirectional: local events go out as
+              // control-frame envelopes, incoming envelopes dispatch to the
+              // same handlers the local socket-server uses (so approve/deny
+              // from a phone runs the same resolvePending path).
+              try {
+                const remoteCfg = loadRemoteConfig();
+                if (remoteCfg?.enabled) {
+                  const bridge = startRelayBridge({
+                    sessionId: _sid,
+                    remoteConfig: remoteCfg,
+                    registerBroadcaster,
+                    onCommand: {
+                      approve: async (payload, attachId) => resolvePending('approve', payload?.apr_id, attachId, payload?.note),
+                      deny: async (payload, attachId) => resolvePending('deny', payload?.apr_id, attachId, payload?.note),
+                      interrupt: async () => { try { if (typeof streamClient?.cancel === 'function') streamClient.cancel(); } catch {} },
+                      send_message: async (_p, _a) => { /* Slice C follow-up */ },
+                    },
+                  });
+                  session._prd092RelayBridge = bridge;
+                }
+              } catch (err) {
+                try { process.stderr.write(`[prd-092] relay bridge: ${err.message}\n`); } catch {}
+              }
+              // Populate ~/.bahulam/sessions/<id>/meta.json + daemon.pid so
+              // `bahulam list` and `bahulam stop <id>` see this session.
+              // These files are what session-list.mjs / stop-daemon.mjs
+              // read; without them those commands are cosmetic. Fire-and-
+              // forget imports so a write failure never affects the turn.
+              try {
+                const [{ writeSessionMeta }, fs, path, { daemonSessionDir }] = await Promise.all([
+                  import('../core/event-log.mjs'),
+                  import('node:fs'),
+                  import('node:path'),
+                  import('../core/paths.mjs'),
+                ]);
+                await writeSessionMeta({
+                  sessionId: _sid,
+                  meta: {
+                    cwd: process.cwd(),
+                    model: session.model || null,
+                    pid: process.pid,
+                    sock_path: server.sockPath,
+                    opened_at: new Date().toISOString(),
+                  },
+                });
+                fs.writeFileSync(
+                  path.join(daemonSessionDir(_sid), 'daemon.pid'),
+                  String(process.pid),
+                  { mode: 0o600 },
+                );
+              } catch (err) {
+                try { process.stderr.write(`[prd-092] meta/pid write: ${err.message}\n`); } catch {}
+              }
+            } catch (err) {
+              try { process.stderr.write(`[prd-092] socket server: ${err.message}\n`); } catch {}
+            } finally {
+              session._prd092SocketStarting = false;
+            }
+          })();
+        }
       }
       if (data?.model) session.model = data.model;
       if (data?.models?.coder) session.model = data.models.coder;
@@ -3240,9 +3579,14 @@ async function handleCommand(input, ctx) {
     }
 
     case '/agents':
+    case '/subagents':
       await handleAgentsCommand(rest, ctx);
       return;
 
+    case '/skills':
+      await handleSkillsCommand(rest, ctx);
+      return;
+
     case '/explore':
     case '/review':
     case '/architect': {
@@ -3398,7 +3742,7 @@ export async function startTerminalRepl() {
     stopSpinner();
     flushContent();
     flushPendingHead();
-    flushCompactReadRun();
+    flushExploreRun();
     runtime.foldedSubAgentTools = null;
     clearCards();
 
@@ -4932,8 +5276,47 @@ export async function startTerminalRepl() {
         }
       }
 
-      for await (const event of client.execute(input, execContext, session.agentHistory)) {
+      // PRD-091 Phase 3 preview: BAHULAM_USE_GATEWAY_LOOP=1 routes the
+      // turn through the gateway's /v1/agent/turn (thin CLI loop) instead
+      // of the local bundled runtime. Session is bootstrapped lazily on
+      // first turn and reused across the REPL. Falls through to the
+      // existing local-agent path when the flag is unset (default today).
+      const _useGatewayLoop = process.env.BAHULAM_USE_GATEWAY_LOOP === '1';
+      let _turnIterable;
+      if (_useGatewayLoop) {
+        if (!session.gatewaySession) {
+          try {
+            session.gatewaySession = await createGatewaySession({
+              workspace: process.env.BAHULAM_WORKSPACE || 'kepler-code',
+              model: process.env.BAHULAM_MODEL || undefined,
+            });
+            process.stderr.write(
+              `  ${c.dim(`[gateway] session ${session.gatewaySession.session_id.slice(0, 20)}… ${session.gatewaySession.tool_schemas.length} tools, model=${session.gatewaySession.model}`)}\n`,
+            );
+          } catch (err) {
+            process.stderr.write(`  ${c.warn(`[gateway] session create failed: ${err.message}`)}\n`);
+            process.stderr.write(`  ${c.dim('falling back to local-agent path')}\n`);
+            session.gatewaySession = null;  // don't retry every turn
+          }
+        }
+        if (session.gatewaySession) {
+          _turnIterable = createAgentLoop({
+            session: session.gatewaySession,
+            messages: session.agentHistory,
+            toolExecutor,
+          });
+        }
+      }
+      if (!_turnIterable) {
+        _turnIterable = client.execute(input, execContext, session.agentHistory);
+      }
+      for await (const event of _turnIterable) {
         jsonlWriter.writeKeplerEvent(event);
+        // . daemon event log. Env-var gated (off by default) —
+        // when BAHULAM_DAEMON_EVENTLOG=1, mirror each SSE frame that maps
+        // to a first-class type into ~/.bahulam/sessions/<id>/events.jsonl.
+        // No-op otherwise; zero effect on the render path either way.
+        tapSseEvent(event, { sessionId: session.id });
         if (event.type === 'plan_created' || event.type === 'goal_created') {
           persistProjectArtifacts(
             event.data,

package/src/terminal/skills-picker.mjs

@@ -0,0 +1,121 @@
+/**
+ * Interactive skills picker — reuses the raw-stdin overlay pattern from
+ * repl-ask-form.mjs. Arrow keys move, Enter views the selected SKILL.md,
+ * Esc/q closes. Emits nothing when the terminal is not a TTY (falls
+ * back to plain-text listing at the call site).
+ */
+
+import { c, renderMarkdown, stripAnsi } from './ansi.mjs';
+import { fitAnsiLine, writeOverlayFrame, eraseOverlayFrame } from './repl-format.mjs';
+
+function truncate(str, max) {
+  const s = String(str || '');
+  if (s.length <= max) return s;
+  return s.slice(0, Math.max(1, max - 1)) + '…';
+}
+
+/**
+ * @param {object} opts
+ * @param {object|null} opts.rl              readline instance to pause/resume
+ * @param {Array<{name,description,scope,source}>} opts.skills
+ * @returns {Promise<{action:'view',name:string}|{action:'remove',name:string}|null>}
+ */
+export async function openSkillsPicker({ rl, skills }) {
+  if (!process.stdin.isTTY) return null;
+  if (!skills?.length) return null;
+  if (rl) rl.pause();
+
+  const rows = skills.map(s => ({
+    name: s.name,
+    description: s.description || '',
+    scope: s.scope,
+    source: s.source,
+  }));
+
+  return await new Promise((resolve) => {
+    const wasRaw = process.stdin.isRaw;
+    let cursor = 0;
+    let renderedLines = 0;
+
+    const render = () => {
+      const cols = Math.max(60, process.stderr.columns || 120);
+      const nameWidth = Math.min(24, Math.max(...rows.map(r => r.name.length)));
+      const scopeWidth = 8;
+      const lines = [];
+      lines.push(`  ${c.bold('Installed skills')} ${c.dim(`· ${rows.length} bundle${rows.length === 1 ? '' : 's'}`)}`);
+      lines.push('');
+      rows.forEach((row, i) => {
+        const active = i === cursor;
+        const marker = active ? c.brand('▸') : ' ';
+        const name = row.name.padEnd(nameWidth).slice(0, nameWidth);
+        const scope = row.scope.padEnd(scopeWidth).slice(0, scopeWidth);
+        const descBudget = Math.max(20, cols - 6 - nameWidth - scopeWidth - 4);
+        const desc = truncate(row.description, descBudget);
+        const painted = active
+          ? `${c.brand(name)}  ${c.dim(scope)}  ${c.brand(desc)}`
+          : `${c.bold(name)}  ${c.dim(scope)}  ${desc}`;
+        lines.push(fitAnsiLine(`  ${marker} ${painted}`, cols - 1));
+      });
+      lines.push('');
+      lines.push(fitAnsiLine(
+        `  ${c.dim('↑↓ move · Enter view SKILL.md · r remove · Esc close')}`,
+        cols - 1,
+      ));
+      writeOverlayFrame(renderedLines, lines);
+      renderedLines = lines.length;
+    };
+
+    const cleanup = (value) => {
+      process.stdin.removeListener('data', onData);
+      process.stdin.setRawMode(wasRaw || false);
+      eraseOverlayFrame(renderedLines);
+      if (rl) rl.resume();
+      resolve(value);
+    };
+
+    const onData = (data) => {
+      const key = data.toString('utf8');
+      if (key === '\x1b' || key === '\x03' || key === 'q') { cleanup(null); return; }
+      if (key === '\r' || key === '\n') {
+        cleanup({ action: 'view', name: rows[cursor].name });
+        return;
+      }
+      if (key === 'r' || key === 'R') {
+        cleanup({ action: 'remove', name: rows[cursor].name });
+        return;
+      }
+      if (key === '\x1b[A' || key === 'k') { cursor = Math.max(0, cursor - 1); render(); return; }
+      if (key === '\x1b[B' || key === 'j') { cursor = Math.min(rows.length - 1, cursor + 1); render(); return; }
+      if (key === '\x1b[H' || key === 'g') { cursor = 0; render(); return; }
+      if (key === '\x1b[F' || key === 'G') { cursor = rows.length - 1; render(); return; }
+    };
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+    render();
+  });
+}
+
+/**
+ * Render a nicely-aligned static list (fallback when no TTY, or for `/skills list`).
+ * Returns the printable string; caller writes it to stderr.
+ */
+export function formatSkillsList(skills) {
+  if (!skills?.length) return `  ${c.dim('No skills installed. Try /skills install <git-url>')}\n`;
+  const nameWidth = Math.min(28, Math.max(...skills.map(s => s.name.length)));
+  const scopeWidth = 8;
+  const cols = Math.max(60, process.stderr.columns || 120);
+  const descBudget = Math.max(20, cols - 6 - nameWidth - scopeWidth - 4);
+  const lines = [`  ${c.bold('Installed skills')} ${c.dim(`· ${skills.length} bundle${skills.length === 1 ? '' : 's'}`)}\n`];
+  for (const s of skills) {
+    const name = s.name.padEnd(nameWidth).slice(0, nameWidth);
+    const scope = String(s.scope || '').padEnd(scopeWidth).slice(0, scopeWidth);
+    const desc = truncate(s.description || '', descBudget);
+    lines.push(`    ${c.bold(name)}  ${c.dim(scope)}  ${desc}\n`);
+  }
+  lines.push(`\n  ${c.dim('Open interactively:')} /skills\n`);
+  return lines.join('');
+}
+
+export { renderMarkdown, stripAnsi };

package/src/terminal/skills.mjs

@@ -1,5 +1,6 @@
 import { SkillInstaller } from '../skills/installer.mjs';
 import { SkillsLoader } from '../skills/loader.mjs';
+import { formatSkillsList } from './skills-picker.mjs';
 
 function has(args, flag) {
     return args.includes(flag);
@@ -22,9 +23,8 @@ export async function runSkillsCommand(args, { cwd = process.cwd() } = {}) {
 
     if (action === 'list') {
         const rows = loader.list({ scope: has(rest, '--all') ? '' : scope });
-        if (has(rest, '--json')) print(rows);
-        else if (!rows.length) print('No skills found.');
-        else for (const row of rows) print(`${row.name}\t${row.scope}\t${row.source}\t${row.description}`);
+        if (has(rest, '--json')) { print(rows); return; }
+        process.stdout.write(formatSkillsList(rows));
         return;
     }
     if (action === 'view') {

package/src/tools/analyze-code.mjs

@@ -0,0 +1,39 @@
+/**
+ * Analyze Code Tool — AST-based structured code analysis (matches Python schema).
+ */
+import { analyzeCode } from '../context/ast-parser.mjs';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export const AnalyzeCodeTool = {
+    name: 'analyze_code',
+    description:
+        'Get structured analysis of one specific file: function/class names with LINE NUMBERS, imports, exports. Never pass a directory or project root.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            file_path: { type: 'string', description: 'Path to a specific file to analyze' },
+        },
+        required: ['file_path'],
+    },
+    validateInput(input) {
+        return input.file_path ? [] : ['file_path required'];
+    },
+    async call(input) {
+        const filePath = path.resolve(input.file_path);
+        let stat;
+        try {
+            stat = fs.statSync(filePath);
+        } catch (err) {
+            return `Error: ${err.message}`;
+        }
+        if (stat.isDirectory()) {
+            return `Error: analyze_code expects a file, but got directory: ${filePath}. Use list_files/search_code first, then pass a specific source file.`;
+        }
+        const result = analyzeCode(filePath, {
+            startLine: input.start_line,
+            endLine: input.end_line,
+        });
+        return result.summary;
+    },
+};

package/src/tools/bash.mjs

@@ -20,7 +20,7 @@ const MAX_OUTPUT_BYTES = 1024 * 1024; // 1MB
 const TIMEOUT_TAIL_BYTES = 64 * 1024;
 
 export const BashTool = {
-    name: 'Bash',
+    name: 'shell',
     description: 'Execute a bash command and return its output.',
     inputSchema: {
         type: 'object',