@bahulam/code 0.1.21 → 0.1.22

package/src/plugins/preflight.mjs

@@ -22,7 +22,8 @@ import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
 import { composedToolName, validateCompose } from './pi-compose.mjs';
-import { bahulamHome } from '../core/paths.mjs';
+import { expandStateContextTools } from './state-tools.mjs';
+import { pluginDirs } from '../core/paths.mjs';
 
 const TOOL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
 const AGENT_SLUG_RE = /^[a-z][a-z0-9-]{0,63}$/;
@@ -182,6 +183,25 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     }
   }
 
+  // 4b. Generated state tools. A plugin that declares config.state.context_tools
+  // gets read-only tools synthesized at load time (state-tools.mjs), so an
+  // agent may legitimately allowlist them. Without this, a plugin referencing
+  // its own generated tool fails preflight as "not defined by this plugin".
+  const stateToolNames = new Set();
+  for (const generated of expandStateContextTools(name, pluginDir, manifest.config?.state)) {
+    const gname = generated.name;
+    if (!gname) continue;
+    if (toolNames.has(gname) || composedToolNames.has(gname)) {
+      errors.push(`Generated state tool "${gname}" collides with an existing tool of the same name`);
+      continue;
+    }
+    if (RESERVED_TOOL_NAMES.has(gname)) {
+      errors.push(`Generated state tool "${gname}" shadows a built-in tool — rename it in config.state.context_tools`);
+      continue;
+    }
+    stateToolNames.add(gname);
+  }
+
   // 5. Sub-agent checks
   const agentSlugs = new Set();
   for (const [i, agent] of agents.entries()) {
@@ -207,7 +227,8 @@ export async function preflightPlugin(pluginDir, opts = {}) {
         }
         continue;
       }
-      if (!toolNames.has(toolRef) && !composedToolNames.has(toolRef) && !RESERVED_TOOL_NAMES.has(toolRef)) {
+      if (!toolNames.has(toolRef) && !stateToolNames.has(toolRef)
+          && !composedToolNames.has(toolRef) && !RESERVED_TOOL_NAMES.has(toolRef)) {
         errors.push(`Agent "${slug}": tool "${toolRef}" is not defined by this plugin and is not a built-in`);
       }
     }
@@ -245,12 +266,12 @@ export async function preflightPlugin(pluginDir, opts = {}) {
  * Convenience — collect installed plugin names from both search paths.
  * Used by the installer to detect collisions.
  */
-export function existingInstalledNames(cwd = process.cwd()) {
+export function existingInstalledNames(_cwd = process.cwd()) {
   const names = [];
-  for (const dir of [
-    path.join(cwd, '.bahulam', 'plugins'),
-    path.join(bahulamHome(), 'plugins'),
-  ]) {
+  // Plugins live in one global root. `cwd` is kept only so existing call
+  // sites keep working; it must never influence discovery, since that
+  // cwd-dependence is the thing this removed.
+  for (const dir of pluginDirs()) {
     if (!fs.existsSync(dir)) continue;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.endsWith('.disabled')) continue;

package/src/plugins/registry.mjs

@@ -9,24 +9,20 @@ import fs from 'fs';
 import path from 'path';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
 import { expandComposedTools } from './pi-compose.mjs';
-import { bahulamHome } from '../core/paths.mjs';
-
-const DEFAULT_PLUGIN_DIRS = () => [
-  path.join(process.cwd(), '.bahulam', 'plugins'),
-  path.join(bahulamHome(), 'plugins'),
-];
+import { expandStateContextTools } from './state-tools.mjs';
+import { pluginDirs as defaultPluginDirs } from '../core/paths.mjs';
 
 export class PluginRegistry {
   /**
    * @param {Object} [options]
-   * @param {string[]} [options.pluginDirs] - Directories to scan (default: project .bahulam/plugins + ~/.bahulam/plugins)
+   * @param {string[]} [options.pluginDirs] - Directories to scan (default: ~/.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.pluginDirs = pluginDirs || (pluginDir ? [pluginDir] : defaultPluginDirs());
     this.disabled = new Set(
       (Array.isArray(disabled) ? disabled : [])
         .map(s => String(s).trim().toLowerCase())
@@ -113,7 +109,7 @@ export class PluginRegistry {
       return false;
     }
 
-    // Check for existing (first wins — project overrides global)
+    // Duplicates are skipped — the first manifest scanned wins.
     if (this.plugins.has(lowerName)) {
       return false; // silently skip duplicates
     }
@@ -165,6 +161,13 @@ export class PluginRegistry {
         plugin._dir,
         plugin.config?.composes || [],
       ));
+      // Manifest-declared state query tools. Synthesized rather than
+      // imported, so they carry `_state_tool` instead of a module path.
+      tools.push(...expandStateContextTools(
+        plugin.metadata?.name || '',
+        plugin._dir,
+        plugin.config?.state,
+      ));
     }
     return tools;
   }

package/src/plugins/state-tools.mjs

@@ -0,0 +1,86 @@
+/**
+ * Declared-state tool expansion.
+ *
+ * A plugin that declares tables in `config.state.tables` can ask the CLI
+ * to generate read-only query tools for the agent, instead of hand-writing
+ * a `tools/*.mjs` handler for every "let me look at my data" case. The
+ * manifest block looks like:
+ *
+ *   state:
+ *     tables:
+ *       - name: questions
+ *         columns: [...]
+ *     context_tools:
+ *       - name: list_questions
+ *         table: questions
+ *         description: List exam questions, optionally filtered by topic
+ *         parameters:
+ *           type: object
+ *           properties:
+ *             topic: { type: string }
+ *         where: "topic = ?"
+ *         params: [topic]
+ *
+ * `expandStateContextTools` turns that into registry tool entries. The
+ * execution side (tool-executor) recognizes the `_state_tool` marker and
+ * runs the query against the plugin's own state DB — so the same tool
+ * flows through every existing surface: `listPluginToolSchemas()`,
+ * the client_tools map, sub-agent tool allowlists, and `/tools`.
+ *
+ * This mirrors `pi-compose.mjs`: one expansion per composition kind, both
+ * feeding the same `PluginRegistry.listTools()` contract.
+ */
+
+/** Tool names are passed to the model, so keep them in the same charset the rest of the CLI uses. */
+function sanitizeToolName(value) {
+  return String(value || '').trim().replace(/[^A-Za-z0-9_]/g, '_');
+}
+
+/**
+ * Expand a plugin's declared `config.state.context_tools` into tool entries.
+ *
+ * Entries carry no `tool:` module path — they are synthesized, and
+ * `_state_tool` tells the executor to query the plugin's state DB rather
+ * than import a handler file.
+ *
+ * @param {string} pluginName
+ * @param {string} pluginDir
+ * @param {object|null|undefined} state normalized `config.state`
+ * @returns {object[]}
+ */
+export function expandStateContextTools(pluginName, pluginDir, state) {
+  const tools = [];
+  const declared = Array.isArray(state?.context_tools) ? state.context_tools : [];
+  if (!pluginName || declared.length === 0) return tools;
+
+  const tableNames = new Set((state?.tables || []).map(t => t.name));
+
+  for (const tool of declared) {
+    const name = sanitizeToolName(tool?.name);
+    if (!name) continue;
+    // A generated tool must never reach past the plugin's own declared
+    // tables — that is the whole safety story for author-supplied `where`.
+    if (!tableNames.has(tool.table)) continue;
+
+    tools.push({
+      name,
+      description: tool.description || `List rows from ${tool.table}`,
+      input_schema: tool.parameters || { type: 'object', properties: {} },
+      // No module to load — signals "synthesized" to any consumer that
+      // would otherwise try to resolve a handler file.
+      tool: null,
+      plugin_name: pluginName,
+      _plugin_name: pluginName,
+      _plugin_dir: pluginDir,
+      _state_tool: {
+        plugin: pluginName,
+        table: tool.table,
+        where: tool.where || '',
+        params: Array.isArray(tool.params) ? tool.params : [],
+        limit: tool.limit || 50,
+      },
+    });
+  }
+
+  return tools;
+}

package/src/plugins/state.mjs

@@ -206,17 +206,18 @@ function pluginDataDir(pluginName) {
   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 = DatabaseSync ? new DatabaseSync(dbPath) : new JsonStateDb(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(`
+function openDb(pluginName, { tables = [] } = {}) {
+  let handle = _handles.get(pluginName);
+  if (!handle) {
+    const dir = pluginDataDir(pluginName);
+    const dbPath = path.join(dir, 'state.db');
+    const db = DatabaseSync ? new DatabaseSync(dbPath) : new JsonStateDb(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,
@@ -231,11 +232,99 @@ function openDb(pluginName) {
     CREATE INDEX IF NOT EXISTS records_stream_idx
       ON records(stream, id DESC);
   `);
-  const handle = { db, dir, path: dbPath };
-  _handles.set(pluginName, handle);
+    handle = { db, dir, path: dbPath, schemaSig: null, declaredTables: new Set() };
+    _handles.set(pluginName, handle);
+  }
+  // Declared tables are applied on every open call, not just the first —
+  // a plugin installed mid-session (or a version bump that adds columns)
+  // must still converge the DB. The signature check makes the repeat
+  // calls free once the schema already matches.
+  applyDeclaredSchema(handle, tables);
   return handle;
 }
 
+function quoteIdent(name) {
+  return `"${String(name).replace(/"/g, '""')}"`;
+}
+
+/** Render one normalized column as the DDL fragment it contributes. */
+function columnToSql(col) {
+  const parts = [quoteIdent(col.name), col.type];
+  if (col.primary) parts.push('PRIMARY KEY');
+  if (col.autoincrement) parts.push('AUTOINCREMENT');
+  if (col.not_null) parts.push('NOT NULL');
+  // `default` is author-supplied SQL text (e.g. "'medium'", "0"), which is
+  // why normalizeState stringifies it and why it is never parameterized.
+  if (col.default != null) parts.push(`DEFAULT ${col.default}`);
+  if (col.references) parts.push(`REFERENCES ${col.references}`);
+  return parts.join(' ');
+}
+
+/**
+ * Create/evolve the tables a plugin declared in `config.state.tables`.
+ *
+ * Additive by contract: a table that exists is left alone apart from
+ * genuinely new columns, which are appended with ALTER TABLE. Nothing is
+ * ever dropped or retyped, so bumping a plugin version can't cost the
+ * user their data. Re-running with an unchanged declaration is a no-op.
+ *
+ * Silently does nothing on the JSON fallback backend, where arbitrary SQL
+ * isn't available — plugins that need declared tables need node:sqlite.
+ */
+function applyDeclaredSchema(handle, tables) {
+  if (!DatabaseSync) return;
+  if (!Array.isArray(tables) || tables.length === 0) {
+    handle.declaredTables = new Set();
+    handle.schemaSig = null;
+    return;
+  }
+  const sig = JSON.stringify(tables);
+  if (handle.schemaSig === sig) return;
+
+  const { db } = handle;
+  for (const table of tables) {
+    let existing = new Set();
+    try {
+      existing = new Set(db.prepare(`PRAGMA table_info(${quoteIdent(table.name)})`).all().map(r => String(r.name)));
+    } catch { /* table doesn't exist yet — created below */ }
+
+    try {
+      if (existing.size === 0) {
+        const defs = table.columns.map(columnToSql).join(', ');
+        db.exec(`CREATE TABLE IF NOT EXISTS ${quoteIdent(table.name)} (${defs});`);
+      } else {
+        for (const col of table.columns) {
+          if (existing.has(col.name)) continue;
+          // SQLite refuses PRIMARY KEY / NOT NULL-without-default on ALTER
+          // TABLE ADD COLUMN. Strip those rather than fail the migration.
+          const addable = {
+            ...col,
+            primary: false,
+            autoincrement: false,
+            not_null: col.not_null && col.default != null,
+          };
+          db.exec(`ALTER TABLE ${quoteIdent(table.name)} ADD COLUMN ${columnToSql(addable)};`);
+        }
+      }
+      for (const index of (table.indexes || [])) {
+        const cols = index.columns.map(quoteIdent).join(', ');
+        const idxName = `${table.name}_${index.columns.join('_')}_idx`;
+        db.exec(
+          `CREATE ${index.unique ? 'UNIQUE ' : ''}INDEX IF NOT EXISTS ${quoteIdent(idxName)} `
+          + `ON ${quoteIdent(table.name)} (${cols});`,
+        );
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`Failed to apply declared schema for table ${table.name}: ${err.message}`);
+      }
+    }
+  }
+
+  handle.declaredTables = new Set(tables.map(t => t.name));
+  handle.schemaSig = sig;
+}
+
 function now() { return new Date().toISOString(); }
 
 function deepMerge(base, patch) {
@@ -261,10 +350,15 @@ function deepMerge(base, patch) {
  * @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 }
+ * @param {object[]} [opts.tables]
+ *   Tables declared in the plugin manifest's `config.state.tables`. They
+ *   are created (and additively migrated) when the DB opens, so a plugin
+ *   can own real domain tables — questions, documents, answers — without
+ *   shipping its own migration logic.
+ * @returns proxy with { get, set, patch, append, list, query, delete, summary, readTable, close, db, path }
  */
-export function makePluginState(pluginName, { emit = null } = {}) {
-  const { db, path: dbPath } = openDb(pluginName);
+export function makePluginState(pluginName, { emit = null, tables = [] } = {}) {
+  const { db, path: dbPath, declaredTables } = openDb(pluginName, { tables });
 
   // One debounce timer per (kind, target). Fast writes coalesce into
   // exactly one plugin_state_changed event. Pending entry is stored so
@@ -398,6 +492,64 @@ export function makePluginState(pluginName, { emit = null } = {}) {
       return { changes: info.changes, lastInsertRowid: Number(info.lastInsertRowid) };
     },
 
+    /**
+     * Read the slices a manifest flagged as `context_always` so the agent
+     * can orient itself at session start without spending a tool call.
+     *
+     * Returns `{ kv: { <key>: value }, streams: { <stream>: [rows] } }`.
+     * Anything the declaration doesn't name is deliberately omitted —
+     * this is the "small and high-signal" tier, and its whole value is
+     * that it stays cheap.
+     *
+     * @param {object[]} decl normalized `config.state.context_always`
+     */
+    summary(decl = []) {
+      const out = { kv: {}, streams: {} };
+      for (const item of (Array.isArray(decl) ? decl : [])) {
+        if (!item || typeof item !== 'object') continue;
+        try {
+          if (item.kind === 'records' && item.stream) {
+            out.streams[item.stream] = this.list(item.stream, {
+              limit: item.limit || 5,
+              order: 'desc',
+            });
+          } else if (item.kind === 'kv' && item.key) {
+            out.kv[item.key] = this.get(item.key, null);
+          }
+        } catch { /* one unreadable slice must not blank the whole summary */ }
+      }
+      return out;
+    },
+
+    /**
+     * Read rows from a table the plugin declared in `config.state.tables`.
+     * Backs the auto-generated `context_tools`.
+     *
+     * Only declared tables are reachable, so a manifest typo can't turn a
+     * generated tool into arbitrary table access. `where` is plugin-authored
+     * SQL (same trust model as `query()`); values are always bound.
+     *
+     * @param {string} table
+     * @param {object} [opts]
+     * @param {string} [opts.where]   e.g. "topic = ?"
+     * @param {any[]}  [opts.params]  bound positionally against `where`
+     * @param {number} [opts.limit]
+     * @returns {object[]}
+     */
+    readTable(table, { where = '', params = [], limit = 50 } = {}) {
+      if (!DatabaseSync) {
+        throw new Error('Declared state tables require the native node:sqlite backend');
+      }
+      const name = String(table || '');
+      if (!declaredTables.has(name)) {
+        throw new Error(`unknown declared state table: ${name || '(none)'}`);
+      }
+      const args = Array.isArray(params) ? params : [params];
+      const cap = Math.max(1, Math.min(1000, Math.floor(limit) || 50));
+      const clause = where ? ` WHERE ${where}` : '';
+      return db.prepare(`SELECT * FROM ${quoteIdent(name)}${clause} LIMIT ?`).all(...args, cap);
+    },
+
     /** Direct DatabaseSync handle for callers that know what they need. */
     get db() { return db; },
     /** Absolute path to the DB file on disk. */

package/src/terminal/repl-model-form.mjs

@@ -1,7 +1,7 @@
 /**
  * Interactive per-role model form for /model (PRD-076 W7).
  *
- * ↑↓ picks a role row, ←→ cycles through [backend default] + the available
+ * ↑↓ picks a role row, ←→ cycles through [backend default] + the curated
  * platform catalog for that role, Enter applies to session overrides,
  * c resets every row to default, Esc cancels. Same raw-stdin overlay
  * pattern as the resume picker (repl-resume.mjs): pause readline, raw
@@ -35,19 +35,19 @@ function formatTokenLimit(value, label) {
   return `${Math.round(n)} ${label}`;
 }
 
-export function optionRowsForRole(catalog, row) {
-  const available = (catalog || []).filter(m => m?.id);
+function optionRowsForRole(catalog, row) {
+  const curated = (catalog || []).filter(m => m?.harness_validated && m?.id);
   const group = String(row?.optionGroup || 'text').toLowerCase();
   if (group === 'image_analysis') {
-    return available.filter(m => (
+    return curated.filter(m => (
       ['image', 'multimodal'].includes(modelCategory(m))
       && !isImageGenerationModel(m)
     ));
   }
   if (group === 'image_generation') {
-    return available.filter(m => modelCategory(m) === 'image' && isImageGenerationModel(m));
+    return curated.filter(m => modelCategory(m) === 'image' && isImageGenerationModel(m));
   }
-  return available.filter(m => ['text', 'chat', 'multimodal'].includes(modelCategory(m)));
+  return curated.filter(m => ['text', 'chat'].includes(modelCategory(m)));
 }
 
 /**
@@ -63,11 +63,11 @@ export async function pickModelOverridesForm({ rl, roles, catalog, fallbackIds,
   if (!process.stdin.isTTY) return null;
   if (rl) rl.pause();
 
-  const catalogRows = (catalog || []).filter(m => m?.id);
+  const catalogRows = (catalog || []).filter(m => m?.harness_validated && m?.id);
   const usingFallback = catalogRows.length === 0;
   const byId = new Map(catalogRows.map(m => [m.id, m]));
 
-  // Per-row option list; a current override that isn't in the catalog list
+  // Per-row option list; a current override that isn't in the curated list
   // is appended so it stays visible and selectable.
   const rows = roles.map(r => {
     const optionIds = usingFallback
@@ -99,7 +99,9 @@ export async function pickModelOverridesForm({ rl, roles, catalog, fallbackIds,
       }
       const meta = byId.get(value);
       const badge = meta ? creditBadge(meta) : '';
-      const flag = meta && meta.harness_validated === false ? c.yellow(' (uncurated)') : '';
+      // Only flag uncurated picks when a curated catalog actually loaded —
+      // in fallback mode every option is a known backend model, not a stray.
+      const flag = meta || usingFallback ? '' : c.yellow(' (uncurated)');
       return `${c.brand(value)}${badge ? ` ${c.dim(badge)}` : ''}${flag}`;
     };
 

package/src/tools/registry.mjs

@@ -111,7 +111,13 @@ export function createToolRegistry({
         if (!pluginName) return null;
         if (pluginStateHandles.has(pluginName)) return pluginStateHandles.get(pluginName);
         const { makePluginState } = await import('../plugins/state.mjs');
-        const state = makePluginState(pluginName, { emit: stateEmit });
+        // Pass the plugin's declared tables through, otherwise this path
+        // opens the shared handle without them — and `applyDeclaredSchema`
+        // treats an empty list as "this plugin declares nothing", which
+        // would *un-apply* a schema the executor path had already applied.
+        const plugin = pluginRegistry?.get?.(pluginName) || null;
+        const tables = plugin?.config?.state?.tables || [];
+        const state = makePluginState(pluginName, { emit: stateEmit, tables });
         pluginStateHandles.set(pluginName, state);
         return state;
     }