@bahulam/code 2.6.0

package/src/skills/loader.mjs

@@ -0,0 +1,252 @@
+/**
+ * Portable Agent Skills loader.
+ *
+ * Discovers standard <root>/<skill>/SKILL.md bundles from Bahulam and Claude
+ * locations. Only metadata is exposed eagerly; instructions and resources are
+ * loaded on demand through view().
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DEFAULT_MAX_CHARS = 12_000;
+
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function parseScalar(value) {
+    const trimmed = value.trim();
+    if (
+        (trimmed.startsWith('"') && trimmed.endsWith('"'))
+        || (trimmed.startsWith("'") && trimmed.endsWith("'"))
+    ) {
+        return trimmed.slice(1, -1);
+    }
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        return trimmed.slice(1, -1).split(',').map(item => parseScalar(item)).filter(Boolean);
+    }
+    if (trimmed === 'true') return true;
+    if (trimmed === 'false') return false;
+    return trimmed;
+}
+
+export function parseSkill(content, fallbackName) {
+    const match = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?/);
+    if (!match) throw new Error('SKILL.md requires YAML frontmatter');
+
+    const metadata = {};
+    let activeList = null;
+    for (const rawLine of match[1].split(/\r?\n/)) {
+        if (!rawLine.trim() || rawLine.trimStart().startsWith('#')) continue;
+        const listMatch = rawLine.match(/^\s*-\s+(.+)$/);
+        if (listMatch && activeList) {
+            metadata[activeList].push(parseScalar(listMatch[1]));
+            continue;
+        }
+        const fieldMatch = rawLine.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!fieldMatch) continue;
+        const [, key, rawValue] = fieldMatch;
+        if (!rawValue.trim()) {
+            metadata[key] = [];
+            activeList = key;
+        } else {
+            metadata[key] = parseScalar(rawValue);
+            activeList = null;
+        }
+    }
+
+    const name = String(metadata.name || fallbackName || '').trim();
+    const description = String(metadata.description || '').trim();
+    const instructions = content.slice(match[0].length).trim();
+    if (!name) throw new Error("SKILL.md requires non-empty 'name'");
+    if (!description) throw new Error("SKILL.md requires non-empty 'description'");
+    if (!instructions) throw new Error('SKILL.md requires instruction content');
+
+    return {
+        name,
+        description,
+        aliases: Array.isArray(metadata.aliases) ? metadata.aliases : [],
+        compatibility: Array.isArray(metadata.compatibility) ? metadata.compatibility : [],
+        metadata,
+        instructions,
+        prompt: instructions,
+    };
+}
+
+export function discoverSkillDirectories(root) {
+    if (!root || !fs.existsSync(root)) return [];
+    const resolved = fs.realpathSync(root);
+    if (fs.existsSync(path.join(resolved, 'SKILL.md'))) return [resolved];
+    return fs.readdirSync(resolved, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && !entry.isSymbolicLink())
+        .map(entry => path.join(resolved, entry.name))
+        .filter(dir => fs.existsSync(path.join(dir, 'SKILL.md')))
+        .sort();
+}
+
+function walkFiles(root) {
+    const files = [];
+    const queue = [root];
+    while (queue.length) {
+        const current = queue.shift();
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            const fullPath = path.join(current, entry.name);
+            if (entry.isSymbolicLink()) continue;
+            if (entry.isDirectory()) queue.push(fullPath);
+            else if (entry.isFile()) files.push(fullPath);
+        }
+    }
+    return files.sort((a, b) => a.localeCompare(b));
+}
+
+function contentHash(root) {
+    const digest = crypto.createHash('sha256');
+    for (const filePath of walkFiles(root)) {
+        digest.update(path.relative(root, filePath).split(path.sep).join('/'));
+        digest.update('\0');
+        digest.update(fs.readFileSync(filePath));
+        digest.update('\0');
+    }
+    return `sha256:${digest.digest('hex')}`;
+}
+
+function bounded(content, maxChars) {
+    if (content.length <= maxChars) return content;
+    const head = Math.floor(maxChars * 0.7);
+    const tail = maxChars - head;
+    return `${content.slice(0, head)}\n\n[... skill content truncated ...]\n\n${content.slice(-tail)}`;
+}
+
+export class SkillsLoader {
+    constructor({ homeDir = os.homedir() } = {}) {
+        this.homeDir = homeDir;
+        this.skills = new Map();
+        this.versions = new Map();
+        this.searchPaths = [];
+    }
+
+    load(cwd = process.cwd()) {
+        this.skills.clear();
+        this.versions.clear();
+        const project = path.resolve(cwd);
+        this.searchPaths = [
+            { dir: path.join(project, '.bahulam', 'skills'), source: 'bahulam-project', scope: 'project', priority: 500 },
+            { dir: path.join(project, '.claude', 'skills'), source: 'claude-project', scope: 'project', priority: 400 },
+            { dir: path.join(this.homeDir, '.bahulam', 'skills'), source: 'bahulam-global', scope: 'global', priority: 300 },
+            { dir: path.join(this.homeDir, '.claude', 'skills'), source: 'claude-global', scope: 'global', priority: 200 },
+        ];
+
+        for (const config of this.searchPaths) this._loadFromDir(config);
+        return this;
+    }
+
+    _loadFromDir(config) {
+        for (const skillDir of discoverSkillDirectories(config.dir)) {
+            try {
+                const skillFile = path.join(skillDir, 'SKILL.md');
+                if (fs.lstatSync(skillFile).isSymbolicLink()) continue;
+                const parsed = parseSkill(fs.readFileSync(skillFile, 'utf-8'), path.basename(skillDir));
+                const skill = {
+                    ...parsed,
+                    root: skillDir,
+                    source: config.source,
+                    source_id: `${config.source}:${parsed.name}`,
+                    scope: config.scope,
+                    priority: config.priority,
+                    content_hash: contentHash(skillDir),
+                };
+                const versions = this.versions.get(skill.name) || [];
+                versions.push(skill);
+                versions.sort((a, b) => b.priority - a.priority || a.source.localeCompare(b.source));
+                this.versions.set(skill.name, versions);
+                this.skills.set(skill.name, versions[0]);
+            } catch {
+                // Invalid third-party bundles are ignored during discovery.
+            }
+        }
+    }
+
+    get(name, sourceId = null) {
+        if (sourceId) {
+            return (this.versions.get(name) || []).find(skill => skill.source_id === sourceId) || null;
+        }
+        if (this.skills.has(name)) return this.skills.get(name);
+        for (const skill of this.skills.values()) {
+            if (skill.name.startsWith(name) || skill.aliases.includes(name)) return skill;
+        }
+        return null;
+    }
+
+    list({ query = '', source = '', scope = '' } = {}) {
+        const needle = query.toLowerCase();
+        return [...this.skills.values()]
+            .filter(skill => !source || skill.source === source)
+            .filter(skill => !scope || skill.scope === scope)
+            .filter(skill => !needle || `${skill.name} ${skill.description}`.toLowerCase().includes(needle))
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map(skill => ({
+                name: skill.name,
+                description: skill.description,
+                source: skill.source,
+                source_id: skill.source_id,
+                scope: skill.scope,
+                content_hash: skill.content_hash,
+                compatibility: skill.compatibility,
+                shadowed_sources: (this.versions.get(skill.name) || []).slice(1).map(item => item.source_id),
+            }));
+    }
+
+    view(name, resourcePath = null, { sourceId = null, maxChars = DEFAULT_MAX_CHARS } = {}) {
+        const skill = this.get(name, sourceId);
+        if (!skill) throw new Error(`Unknown skill: ${name}`);
+        if (!resourcePath) {
+            return {
+                name: skill.name,
+                description: skill.description,
+                source: skill.source,
+                source_id: skill.source_id,
+                scope: skill.scope,
+                content_hash: skill.content_hash,
+                compatibility: skill.compatibility,
+                shadowed_sources: (this.versions.get(skill.name) || [])
+                    .filter(item => item.source_id !== skill.source_id)
+                    .map(item => item.source_id),
+                instructions: bounded(skill.instructions, maxChars),
+                resources: walkFiles(skill.root)
+                    .map(file => path.relative(skill.root, file).split(path.sep).join('/'))
+                    .filter(file => file !== 'SKILL.md'),
+                metadata: skill.metadata,
+            };
+        }
+
+        if (path.isAbsolute(resourcePath)) throw new Error('Skill resource path must be relative');
+        const candidate = path.resolve(skill.root, resourcePath);
+        if (!isWithin(skill.root, candidate)) throw new Error('Skill resource escapes its bundle');
+        const relativeParts = path.relative(skill.root, candidate).split(path.sep);
+        let cursor = skill.root;
+        for (const part of relativeParts) {
+            cursor = path.join(cursor, part);
+            if (!fs.existsSync(cursor)) throw new Error(`Skill resource not found: ${resourcePath}`);
+            if (fs.lstatSync(cursor).isSymbolicLink()) throw new Error('Symlinked skill resources are not allowed');
+        }
+        if (!fs.statSync(candidate).isFile()) throw new Error(`Skill resource not found: ${resourcePath}`);
+        return {
+            name: skill.name,
+            source_id: skill.source_id,
+            path: resourcePath,
+            content: bounded(fs.readFileSync(candidate, 'utf-8'), maxChars),
+        };
+    }
+
+    async run(name, args) {
+        const skill = this.get(name);
+        if (!skill) throw new Error(`Unknown skill: ${name}`);
+        let prompt = skill.instructions;
+        if (args) prompt = prompt.replace(/\$ARGUMENTS/g, args);
+        return `[Skill: ${skill.name}]\n${prompt}${args ? `\n\nArguments: ${args}` : ''}`;
+    }
+}

package/src/skills/runner.mjs

@@ -0,0 +1,55 @@
+/**
+ * Skills Runner — executes a skill by injecting its prompt.
+ *
+ * When a skill is invoked, its prompt is injected as a system message
+ * into the conversation context, guiding the agent's behavior.
+ */
+
+export class SkillRunner {
+    /**
+     * @param {object} loader - SkillsLoader instance
+     * @param {object} agentLoop - agent loop instance
+     */
+    constructor(loader, agentLoop) {
+        this.loader = loader;
+        this.loop = agentLoop;
+    }
+
+    /**
+     * Execute a skill.
+     * @param {string} name - skill name
+     * @param {string} [args] - optional arguments
+     * @returns {AsyncGenerator} event stream from agent loop
+     */
+    async *execute(name, args) {
+        const skill = this.loader.get(name);
+        if (!skill) {
+            yield { type: 'error', message: `Unknown skill: ${name}` };
+            return;
+        }
+
+        // Build the skill prompt
+        let prompt = skill.prompt;
+        if (args) {
+            prompt = prompt.replace(/\$ARGUMENTS/g, args);
+        }
+
+        // Inject skill context as a user message
+        const message = `[Invoking skill: ${skill.name}]\n\n${prompt}${args ? `\n\nArguments: ${args}` : ''}`;
+
+        // Run through agent loop
+        yield* this.loop.run(message);
+    }
+
+    /**
+     * List available skills for display.
+     * @returns {Array<{name: string, description: string}>}
+     */
+    listAvailable() {
+        return this.loader.list().map(s => ({
+            name: s.name,
+            description: s.description,
+            aliases: s.aliases || [],
+        }));
+    }
+}

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 `~/.bahulam/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 path from 'node:path';
+import { bahulamHome } from '../core/paths.mjs';
+
+export const MODES = Object.freeze({
+  QUIET:    'quiet',
+  DEFAULT:  'default',
+  VERBOSE:  'verbose',
+  SURGICAL: 'surgical',
+});
+
+const VALID = new Set(Object.values(MODES));
+
+const CONFIG_DIR = bahulamHome();
+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');
+  }
+}