@bahulam/code 0.1.10 → 0.1.12

package/src/plugins/registry.mjs

@@ -0,0 +1,233 @@
+/**
+ * Plugin Registry — scan, load, validate, and deduplicate plugin manifests.
+ *
+ * Scans standard directories for plugin.yaml / plugin.json manifests.
+ * Follows the same pattern as AgentLoader and SkillsLoader.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
+
+const DEFAULT_PLUGIN_DIRS = () => [
+  path.join(process.cwd(), '.bahulam', 'plugins'),
+  path.join(os.homedir(), '.bahulam', 'plugins'),
+];
+
+export class PluginRegistry {
+  /**
+   * @param {Object} [options]
+   * @param {string[]} [options.pluginDirs] - Directories to scan (default: project .bahulam/plugins + ~/.bahulam/plugins)
+   * @param {string[]} [options.disabled] - Plugin names to skip
+   * @param {string[]} [options.enabled] - If provided, only these plugin names are loaded
+   * @param {string[]} [options.active] - Alias for enabled
+   * @param {string} [options.pluginDir] - Legacy single plugin dir (mapped to pluginDirs[0])
+   */
+  constructor({ pluginDirs, disabled = [], enabled = null, active = null, pluginDir } = {}) {
+    this.pluginDirs = pluginDirs || (pluginDir ? [pluginDir] : DEFAULT_PLUGIN_DIRS());
+    this.disabled = new Set(
+      (Array.isArray(disabled) ? disabled : [])
+        .map(s => String(s).trim().toLowerCase())
+        .filter(Boolean),
+    );
+    const enabledList = Array.isArray(enabled) ? enabled : (Array.isArray(active) ? active : []);
+    this.enabled = new Set(
+      enabledList
+        .map(s => String(s).trim().toLowerCase())
+        .filter(Boolean),
+    );
+    this.plugins = new Map(); // name → manifest
+    this.errors = [];         // { name, message }
+  }
+
+  /**
+   * Scan all plugin directories and load manifests.
+   * @returns {this}
+   */
+  scan() {
+    for (const dir of this.pluginDirs) {
+      this._scanDir(dir);
+    }
+    return this;
+  }
+
+  _scanDir(dir) {
+    try {
+      if (!fs.existsSync(dir)) return;
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const pluginDir = path.join(dir, entry.name);
+
+        // Try plugin.yaml, plugin.json (in that order)
+        let manifestPath = path.join(pluginDir, 'plugin.yaml');
+        if (!fs.existsSync(manifestPath)) {
+          manifestPath = path.join(pluginDir, 'plugin.json');
+          if (!fs.existsSync(manifestPath)) continue;
+        }
+
+        const manifest = parsePluginManifestFile(manifestPath);
+        if (!manifest) {
+          this.errors.push({
+            plugin: entry.name,
+            message: `Failed to parse manifest: ${manifestPath}`,
+          });
+          continue;
+        }
+
+        this.register(manifest);
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`Plugin registry scan error in ${dir}: ${err.message}`);
+      }
+    }
+  }
+
+  /**
+   * Register a plugin manifest.
+   * @param {object} manifest - Normalized manifest from normalizeManifest()
+   * @returns {boolean} true if registered, false if skipped (disabled or duplicate)
+   */
+  register(manifest) {
+    const name = manifest.metadata?.name || '';
+    if (!name) return false;
+
+    const lowerName = name.toLowerCase();
+    const aliases = [
+      lowerName,
+      manifest._dir ? path.basename(manifest._dir).toLowerCase() : '',
+    ].filter(Boolean);
+
+    if (this.enabled.size > 0 && !aliases.some(alias => this.enabled.has(alias))) {
+      return false;
+    }
+
+    // Check disabled list
+    if (aliases.some(alias => this.disabled.has(alias))) {
+      if (process.env.DEBUG) {
+        console.warn(`Plugin "${name}" is disabled, skipping`);
+      }
+      return false;
+    }
+
+    // Check for existing (first wins — project overrides global)
+    if (this.plugins.has(lowerName)) {
+      return false; // silently skip duplicates
+    }
+
+    // Validate
+    const { valid, errors } = validatePluginManifest(manifest);
+    if (!valid) {
+      this.errors.push({ plugin: name, message: errors.join('; ') });
+      return false;
+    }
+
+    this.plugins.set(lowerName, manifest);
+    return true;
+  }
+
+  /**
+   * Get a plugin by name.
+   * @param {string} name
+   * @returns {object|null}
+   */
+  get(name) {
+    return this.plugins.get(String(name || '').toLowerCase()) || null;
+  }
+
+  /**
+   * List all registered plugins.
+   * @returns {object[]}
+   */
+  list() {
+    return [...this.plugins.values()];
+  }
+
+  /**
+   * List all tools from all plugins.
+   * @returns {object[]}
+   */
+  listTools() {
+    const tools = [];
+    for (const plugin of this.plugins.values()) {
+      for (const tool of (plugin.spec?.tools || [])) {
+        tools.push({
+          ...tool,
+          _plugin_name: plugin.metadata?.name,
+          _plugin_dir: plugin._dir,
+        });
+      }
+    }
+    return tools;
+  }
+
+  /**
+   * List every plugin-declared MCP server across the registry.
+   *
+   * Each entry is [{plugin, name, config}] where `config` is a
+   * Claude-Desktop-compatible object (command/args/env or url/headers).
+   * Consumers spawn one McpClient per entry at session start; the
+   * server's tools are then namespaced as `<name>.<tool>` in the
+   * tool executor so two plugins can ship servers with the same tool
+   * name without collision.
+   * @returns {{plugin: string, name: string, config: object}[]}
+   */
+  listMcpServers() {
+    const out = [];
+    for (const plugin of this.plugins.values()) {
+      const servers = plugin.spec?.mcpServers || {};
+      const pluginName = plugin.metadata?.name || '';
+      for (const [name, config] of Object.entries(servers)) {
+        if (config && typeof config === 'object') {
+          out.push({ plugin: pluginName, name, config });
+        }
+      }
+    }
+    return out;
+  }
+
+  /**
+   * List all agents from all plugins.
+   * @returns {object[]}
+   */
+  listAgents() {
+    const agents = [];
+    for (const plugin of this.plugins.values()) {
+      for (const agent of (plugin.spec?.agents || [])) {
+        agents.push({
+          ...agent,
+          _plugin_name: plugin.metadata?.name,
+        });
+      }
+    }
+    return agents;
+  }
+
+  /**
+   * Check if a plugin exists.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this.plugins.has(String(name || '').toLowerCase());
+  }
+
+  /**
+   * Remove a plugin by name.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  remove(name) {
+    return this.plugins.delete(String(name || '').toLowerCase());
+  }
+
+  /**
+   * Get plugin count.
+   * @returns {number}
+   */
+  count() {
+    return this.plugins.size;
+  }
+}

package/src/plugins/state.mjs

@@ -0,0 +1,290 @@
+/**
+ * Plugin state — the Shared Blackboard.
+ *
+ * Every plugin gets its own SQLite sidecar at ~/.bahulam/data/<name>/state.db.
+ * Two built-in tables ship with every DB; plugins are free to `CREATE TABLE`
+ * additional ones via `state.query(sql)`:
+ *
+ *   kv        — small structured values (watchlists, prefs, cursors, form
+ *               state). One row per key, JSON-encoded value, last-write-wins
+ *               with an updated_at timestamp.
+ *
+ *   records   — append-only event log (backtest runs, decisions, alerts,
+ *               anything you want a history of). Named streams via the
+ *               `stream` column; plugin owns the stream namespace.
+ *
+ * The exported `makePluginState(pluginName, {emit})` returns a proxy with
+ * the methods handlers and view routes call. Every write fires `emit(evt)`
+ * synchronously AFTER commit — the SSE bus turns that into a
+ * `plugin_state_changed` event so views can re-render live. When the same
+ * key/stream is written many times in quick succession the emit hook
+ * debounces to at most one event per 50ms per (plugin, kind, target).
+ *
+ * We use Node's built-in `node:sqlite` (v22+, experimental) so plugin
+ * authors get relational storage with zero install steps. The
+ * ExperimentalWarning is silenced once at module load.
+ *
+ * A NOTE ON SAFETY: `state.query(sql, params)` is a raw SQL escape hatch
+ * intended for the plugin's OWN tools and views — never expose it to
+ * untrusted input (the plugin author owns the SQL). The higher-level
+ * get/set/patch/append/list methods parameterize everything.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+// Silence the single "SQLite is an experimental feature" warning that
+// node:sqlite emits at first import. Users would see it on every plugin
+// launch otherwise, which is noise, not signal.
+{
+  const orig = process.emit;
+  process.emit = function (name, warning, ...rest) {
+    if (name === 'warning' && warning?.name === 'ExperimentalWarning'
+        && /SQLite/i.test(String(warning.message || ''))) {
+      return false;
+    }
+    return orig.call(this, name, warning, ...rest);
+  };
+}
+
+const DATA_ROOT = () => path.join(os.homedir(), '.bahulam', 'data');
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+const DEBOUNCE_MS = 50;
+
+// Open handles cached per plugin — SQLite in WAL mode is happy with one
+// handle per process, and this is a single-process dev tool. Handles live
+// for the lifetime of the CLI; explicit close() is available for tests.
+const _handles = new Map(); // pluginName -> { db, dir, path }
+
+function pluginDataDir(pluginName) {
+  if (!PLUGIN_NAME_RE.test(pluginName)) {
+    throw new Error(`invalid plugin name for state dir: ${pluginName}`);
+  }
+  const dir = path.join(DATA_ROOT(), pluginName);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+function openDb(pluginName) {
+  if (_handles.has(pluginName)) return _handles.get(pluginName);
+  const dir = pluginDataDir(pluginName);
+  const dbPath = path.join(dir, 'state.db');
+  const db = new DatabaseSync(dbPath);
+  // WAL: multiple readers, one writer; robust against concurrent view+agent.
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA synchronous = NORMAL');
+  db.exec('PRAGMA foreign_keys = ON');
+  // Bootstrap schema — idempotent so evolving plugins never crash on start.
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS kv (
+      key        TEXT PRIMARY KEY,
+      value      TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS records (
+      id         INTEGER PRIMARY KEY AUTOINCREMENT,
+      stream     TEXT NOT NULL,
+      payload    TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS records_stream_idx
+      ON records(stream, id DESC);
+  `);
+  const handle = { db, dir, path: dbPath };
+  _handles.set(pluginName, handle);
+  return handle;
+}
+
+function now() { return new Date().toISOString(); }
+
+function deepMerge(base, patch) {
+  if (Array.isArray(base) || Array.isArray(patch)) return patch;
+  if (base == null || typeof base !== 'object') return patch;
+  if (patch == null || typeof patch !== 'object') return patch;
+  const out = { ...base };
+  for (const [k, v] of Object.entries(patch)) {
+    if (v && typeof v === 'object' && !Array.isArray(v)
+        && out[k] && typeof out[k] === 'object' && !Array.isArray(out[k])) {
+      out[k] = deepMerge(out[k], v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a per-plugin state proxy.
+ * @param {string} pluginName  Must match /^[a-z0-9][a-z0-9._-]{0,63}$/i
+ * @param {object} [opts]
+ * @param {(evt: {plugin: string, op: string, kind: 'kv'|'records', target: string, at: string}) => void} [opts.emit]
+ *   Called (debounced) after every write commits. The workspace server
+ *   turns this into an SSE `plugin_state_changed` event for the browser.
+ * @returns proxy with { get, set, patch, append, list, query, delete, close, db, path }
+ */
+export function makePluginState(pluginName, { emit = null } = {}) {
+  const { db, path: dbPath } = openDb(pluginName);
+
+  // One debounce timer per (kind, target). Fast writes coalesce into
+  // exactly one plugin_state_changed event. Pending entry is stored so
+  // close() can flush synchronously for tests and controlled shutdown.
+  const timers = new Map();  // key -> timeout handle
+  const pending = new Map(); // key -> event payload to fire on flush
+  function fire(op, kind, target) {
+    if (typeof emit !== 'function') return;
+    const key = `${kind}:${target}`;
+    if (timers.has(key)) clearTimeout(timers.get(key));
+    pending.set(key, { plugin: pluginName, op, kind, target, at: now() });
+    timers.set(key, setTimeout(() => {
+      const evt = pending.get(key);
+      timers.delete(key);
+      pending.delete(key);
+      if (evt) {
+        try { emit(evt); }
+        catch { /* emit failure must never surface into the tool call */ }
+      }
+    }, DEBOUNCE_MS));
+  }
+  function flushPending() {
+    for (const [key, evt] of pending) {
+      clearTimeout(timers.get(key));
+      try { emit(evt); } catch { /* swallow */ }
+    }
+    timers.clear();
+    pending.clear();
+  }
+
+  // Prepared statements are cached on first use (better-sqlite3-style perf,
+  // node:sqlite exposes prepare() too).
+  const stmts = {
+    get:    db.prepare('SELECT value FROM kv WHERE key = ?'),
+    upsert: db.prepare('INSERT INTO kv(key, value, updated_at) VALUES(?, ?, ?) '
+                     + 'ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at'),
+    del:    db.prepare('DELETE FROM kv WHERE key = ?'),
+    keys:   db.prepare('SELECT key FROM kv ORDER BY key'),
+    append: db.prepare('INSERT INTO records(stream, payload, created_at) VALUES(?, ?, ?)'),
+    listAsc:  db.prepare('SELECT id, payload, created_at FROM records WHERE stream = ? ORDER BY id ASC  LIMIT ?'),
+    listDesc: db.prepare('SELECT id, payload, created_at FROM records WHERE stream = ? ORDER BY id DESC LIMIT ?'),
+  };
+
+  return {
+    /** Read one key. Returns `fallback` (default null) when the key is absent. */
+    get(key, fallback = null) {
+      const row = stmts.get.get(String(key));
+      if (!row) return fallback;
+      try { return JSON.parse(row.value); }
+      catch { return fallback; }
+    },
+
+    /** Write one key with a whole value. Fires plugin_state_changed. */
+    set(key, value) {
+      const k = String(key);
+      stmts.upsert.run(k, JSON.stringify(value), now());
+      fire('set', 'kv', k);
+      return value;
+    },
+
+    /**
+     * Deep-merge a partial into an existing object under `key`. Arrays
+     * replace; nested objects merge recursively. When the key is absent,
+     * `patch` is stored as-is. Matches the "PATCH endpoint for surgeon
+     * precision" contract.
+     */
+    patch(key, partial) {
+      const k = String(key);
+      const cur = this.get(k, null);
+      const next = deepMerge(cur, partial);
+      stmts.upsert.run(k, JSON.stringify(next), now());
+      fire('patch', 'kv', k);
+      return next;
+    },
+
+    /** Remove one key. */
+    delete(key) {
+      const k = String(key);
+      const info = stmts.del.run(k);
+      if (info.changes > 0) fire('delete', 'kv', k);
+      return info.changes > 0;
+    },
+
+    /** List every kv key currently present. */
+    keys() { return stmts.keys.all().map(r => r.key); },
+
+    /** Append one row to a named stream. Returns the new row's id. */
+    append(stream, payload) {
+      const s = String(stream);
+      const info = stmts.append.run(s, JSON.stringify(payload), now());
+      fire('append', 'records', s);
+      return Number(info.lastInsertRowid);
+    },
+
+    /**
+     * Read from a stream.
+     * @param {string} stream
+     * @param {object} [opts]  { limit?: number = 50, order?: 'asc'|'desc' = 'desc' }
+     * @returns [{ id, payload, created_at }]
+     */
+    list(stream, { limit = 50, order = 'desc' } = {}) {
+      const s = String(stream);
+      const cap = Math.max(1, Math.min(10000, Math.floor(limit)));
+      const stmt = order === 'asc' ? stmts.listAsc : stmts.listDesc;
+      return stmt.all(s, cap).map(r => ({
+        id: r.id,
+        payload: safeParse(r.payload),
+        created_at: r.created_at,
+      }));
+    },
+
+    /**
+     * Raw SQL escape hatch — for the plugin's own advanced use. Always
+     * use parameters, never string-concat user input into SQL. Returns
+     * whatever the underlying prepared statement returns; SELECTs come
+     * back as an array of rows.
+     */
+    query(sql, params = []) {
+      const stmt = db.prepare(String(sql));
+      const args = Array.isArray(params) ? params : [params];
+      // node:sqlite prepared statements expose all() for SELECT-like
+      // queries and run() for DML; iterate() is available too.
+      const first = String(sql).trim().slice(0, 6).toUpperCase();
+      if (first.startsWith('SELECT') || first.startsWith('PRAGMA')) {
+        return stmt.all(...args);
+      }
+      const info = stmt.run(...args);
+      // Any DML on kv/records is announced generically so views can
+      // refresh; more specific writes go through set/patch/append.
+      fire('query', 'kv', '*');
+      return { changes: info.changes, lastInsertRowid: Number(info.lastInsertRowid) };
+    },
+
+    /** Direct DatabaseSync handle for callers that know what they need. */
+    get db() { return db; },
+    /** Absolute path to the DB file on disk. */
+    get path() { return dbPath; },
+
+    /** Test hook — closes the underlying handle. Flushes any pending
+     * emit events synchronously so tests can observe them without a wait. */
+    close() {
+      flushPending();
+      db.close();
+      _handles.delete(pluginName);
+    },
+  };
+}
+
+function safeParse(text) {
+  try { return JSON.parse(text); } catch { return text; }
+}
+
+/**
+ * Test helper — reset all cached handles. Called by tests between cases so
+ * a temp $HOME override actually takes effect.
+ */
+export function _resetForTests() {
+  for (const h of _handles.values()) {
+    try { h.db.close(); } catch { /* ignore */ }
+  }
+  _handles.clear();
+}

package/src/terminal/agents.mjs

@@ -113,7 +113,7 @@ const TOOL_ALIASES = new Map([
   ['grep', 'search_code'],
 ]);
 
-function canonicalToolName(value) {
+export function canonicalToolName(value) {
   const key = String(value || '').trim().toLowerCase();
   return TOOL_ALIASES.get(key) || key;
 }
@@ -133,7 +133,7 @@ function normalizeScopedArgs(toolName, args = {}, { projectRoot = null } = {}) {
   return next;
 }
 
-function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } = {}) {
+export function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } = {}) {
   const tools = Array.isArray(agent.tools) ? agent.tools : [];
   const allowed = new Set(tools.map(canonicalToolName).filter(Boolean));
   if (!allowed.size) return baseExecutor;
@@ -152,7 +152,11 @@ function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } =
         baseExecutor,
         toolName,
         normalizeScopedArgs(toolName, args, { projectRoot }),
-        options,
+        {
+          ...options,
+          internal: true,
+          subAgent: agent.slug || agent.command || agent.name || true,
+        },
       );
     },
   };
@@ -163,6 +167,22 @@ export function findBuiltinAgent(agentName) {
   return BUILTIN_AGENTS.find(agent => agent.command === target || agent.name.toLowerCase() === target) || null;
 }
 
+/**
+ * Search for an agent across built-in agents, project .bahulam/agents, and plugin agents.
+ * @param {string} agentName
+ * @param {object} [agentLoader] - Instance of AgentLoader with loadFromPlugins() called
+ * @returns {object|null}
+ */
+export function findAgent(agentName, agentLoader = null) {
+  const builtin = findBuiltinAgent(agentName);
+  if (builtin) return builtin;
+  if (agentLoader) {
+    const local = agentLoader.get(agentName);
+    if (local) return local;
+  }
+  return null;
+}
+
 export function localAgentMatches(agent, target) {
   const needle = String(target || '').trim().toLowerCase();
   if (!needle) return false;
@@ -301,6 +321,7 @@ export async function runAgentDefinition(agentDefinition, instruction, ctx, sess
     token: creds.token,
     toolExecutor,
     approvalManager: agentApproval,
+    pluginRegistry: options.pluginRegistry || ctx.pluginRegistry || null,
   });
 
   session.turns++;
@@ -344,7 +365,8 @@ export async function runAgentDefinition(agentDefinition, instruction, ctx, sess
  * @param {Function} renderEvent - Event renderer function
  */
 export async function runAgent(agentName, instruction, ctx, session, renderEvent) {
-  const agent = findBuiltinAgent(agentName);
+  const agentLoader = ctx?.agentLoader || null;
+  const agent = findAgent(agentName, agentLoader);
   if (!agent) {
     process.stderr.write(`  ${c.red('Unknown agent: ' + agentName)}\n`);
     return;

package/src/terminal/init.mjs

@@ -28,7 +28,7 @@ Format v1. Markdown files are intentionally hand-editable.
   'config.json': JSON.stringify({
     version: 1,
     context: {
-      loadEveryTurn: ['KEPLER.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
+      loadEveryTurn: ['BAHULAM.md', 'project.md', 'style.md', 'goal.md', 'plan.md', 'tasks/*.md'],
       showReloadNotice: true,
     },
     planning: { owner: 'auto', onUserEditedPlan: 'prefer_user_plan' },
@@ -57,7 +57,7 @@ Format v1. Markdown files are intentionally hand-editable.
       Stop: [],
     },
   }, null, 2) + '\n',
-  'KEPLER.md': `# Project
+  'BAHULAM.md': `# Project
 
 ## Quick Facts
 - Stack: