@bahulam/code 0.1.10 → 0.1.11

package/src/core/stream-client.mjs

@@ -11,6 +11,7 @@
 
 import { llmToolResultContent, sendCallback, sendSkippedCallback, sendApprovalDecision } from './callback-client.mjs';
 import { ApprovalManager } from './approval.mjs';
+import { upsertFacts } from './memory-disk.mjs';
 import { normalizeBillingBrandCopy, quotaErrorDetail, rateLimitErrorMessage } from './rate-limit-display.mjs';
 import * as telemetry from '../telemetry/index.mjs';
 
@@ -93,6 +94,17 @@ function transportDebug(message, data = {}) {
     } catch {}
 }
 
+function memoryFactsFromComplete(data) {
+    const facts = data?.memory_facts_to_persist;
+    if (!Array.isArray(facts) || facts.length === 0) return [];
+    return facts.filter(fact => (
+        fact
+        && typeof fact === 'object'
+        && fact.fact_id
+        && String(fact.content || '').trim()
+    ));
+}
+
 // Full jitter around the scheduled delay: pick a value in [delay*0.5, delay*1.5].
 // Spreads out reconnect storms so N clients dropping simultaneously don't
 // synchronize their retries. Clamped to the same 30s ceiling as the base delay.
@@ -136,6 +148,7 @@ export class BahulamStreamClient {
         approvalManager = null,
         reconnectMaxElapsedMs = null,
         mode = null,
+        pluginRegistry = null,
     }) {
         this.baseUrl = (baseUrl || '').replace(/\/$/, '');
         this.token = token;
@@ -148,7 +161,7 @@ export class BahulamStreamClient {
         this.retryDelayMs = null;
         this.pendingToolCallbacks = new Map();
         this.reconnectMaxElapsedMs = reconnectMaxElapsedMs
-            ?? Number(process.env.KEPLER_RECONNECT_MAX_ELAPSED_MS || 300_000);
+            ?? Number(process.env.BAHULAM_RECONNECT_MAX_ELAPSED_MS || 300_000);
         // Set by backend on first turn, reused on subsequent turns. Headless mode
         // (which starts fresh per invocation) can pre-seed via TARANG_SESSION_ID
         // so multi-turn benchmarks share one backend session across `node` runs.
@@ -173,9 +186,38 @@ export class BahulamStreamClient {
             || (process.env.TARANG_ENV === 'remote' ? 'remote' : null)
             || (process.env.TARANG_ENV === 'bundled' ? 'bundled' : null)
             || 'remote';
+        this.pluginRegistry = pluginRegistry || null;
         this._bundledReady = false;
     }
 
+    /**
+     * Get plugin tool schemas for client_tools injection.
+     * @returns {Array<{name: string, description: string, input_schema: object}>}
+     */
+    _getPluginToolSchemas() {
+        if (!this.pluginRegistry) return [];
+        return this.pluginRegistry.listTools().map(t => ({
+            name: t.name,
+            description: t.description || '',
+            input_schema: t.input_schema || { type: 'object', properties: {} },
+        }));
+    }
+
+    /**
+     * Get plugin agent schemas for client_agents injection.
+     * @returns {Array<{slug: string, name: string, role: string, description: string, tools: string[]}>}
+     */
+    _getPluginAgentSchemas() {
+        if (!this.pluginRegistry) return [];
+        return this.pluginRegistry.listAgents().map(a => ({
+            slug: a.slug || a.name || '',
+            name: a.name || a.slug || '',
+            role: a.role || 'specialist',
+            description: a.description || '',
+            tools: Array.isArray(a.tools) ? a.tools : [],
+        }));
+    }
+
     /**
      * Ensure the bundled runtime is spawned and this.baseUrl points at it.
      * No-op in remote mode. Callers that hit the backend should invoke this
@@ -251,6 +293,10 @@ export class BahulamStreamClient {
         const body = { instruction, context };
         if (messages && messages.length > 0) body.messages = messages;
         if (this.sessionId) body.session_id = this.sessionId;
+        const clientTools = this._getPluginToolSchemas();
+        if (clientTools.length > 0) body.client_tools = clientTools;
+        const clientAgents = this._getPluginAgentSchemas();
+        if (clientAgents.length > 0) body.client_agents = clientAgents;
         const requestId = `cli-${_uuidLike()}`;
 
         // daemon cache-guard hook. If BAHULAM_CAPTURE_REQUEST is set to a file
@@ -461,6 +507,10 @@ export class BahulamStreamClient {
             return;
         }
 
+        if (event === EVENT_TYPES.COMPLETE) {
+            this._persistMemoryFactsFromComplete(data);
+        }
+
         // Tool requests — show to user, then execute locally and POST callback.
         if (event === EVENT_TYPES.TOOL_REQUEST || event === EVENT_TYPES.TOOL_CALL) {
             yield rendered;
@@ -486,6 +536,23 @@ export class BahulamStreamClient {
         }
     }
 
+    _persistMemoryFactsFromComplete(data) {
+        const facts = memoryFactsFromComplete(data);
+        if (facts.length === 0) return;
+        try {
+            upsertFacts(facts, process.cwd());
+            telemetry.track('memory.disk.upserted', { facts: facts.length });
+        } catch (err) {
+            telemetry.track('memory.disk.upsert_failed', {
+                facts: facts.length,
+                message: err?.message || String(err),
+            });
+            if (data && typeof data === 'object') {
+                data.memory_persist_error = err?.message || String(err);
+            }
+        }
+    }
+
     async *_reconnectAfterDrop(err) {
         const taskId = this.currentTaskId;
         if (!taskId || this.lastEventId == null) {

package/src/core/system-prompt.mjs

@@ -1,8 +1,8 @@
 /**
- * System Prompt Builder — loads and merges CLAUDE.md and KEPLER.md files.
+ * System Prompt Builder — loads and merges CLAUDE.md and BAHULAM.md files.
  *
  * Features:
- * - Loads CLAUDE.md from: ~/.claude/CLAUDE.md, project root, parent dirs
+ * - Loads CLAUDE.md and BAHULAM.md from: global dir, project root, parent dirs
  * - Merges in order (global -> project -> local)
  * - Splits at cache boundary (static prefix cached, dynamic suffix not)
  * - Includes tool schemas in the system prompt
@@ -13,27 +13,46 @@ import os from 'os';
 import { loadBahulamMemory } from '../config/memory-loader.mjs';
 
 /**
- * Load all CLAUDE.md files and merge them in order.
+ * Load all instruction files and merge them in order (global → parent → project).
+ *
+ * Three first-class formats, per industry standard (2026):
+ *   AGENTS.md   — universal baseline: build rules, code style, monorepo layout.
+ *                 Loaded by 30+ agents (Cursor, Copilot CLI, Gemini CLI, Claude Code).
+ *   BAHULAM.md  — Bahulam-native persistent memory: tool directives, preferences,
+ *                 project-specific context that travels every session.
+ *   CLAUDE.md   — Claude Code / Claude-specific instructions and memory tiers.
+ *
+ * Search order per directory: AGENTS.md → BAHULAM.md → .bahulam/BAHULAM.md
+ *                                       → CLAUDE.md  → .claude/CLAUDE.md
+ *
  * @param {string} [cwd] - current working directory
- * @returns {string[]} Array of CLAUDE.md contents in merge order
+ * @returns {Array<{source,content,path}>} files in merge order
  */
 export function loadClaudeMdFiles(cwd = process.cwd()) {
     const files = [];
 
-    // 1. Global: ~/.claude/CLAUDE.md
-    const globalPath = path.join(os.homedir(), '.claude', 'CLAUDE.md');
-    if (fs.existsSync(globalPath)) {
-        try {
-            files.push({ source: 'global', content: fs.readFileSync(globalPath, 'utf-8') });
-        } catch { /* skip */ }
+    // 1. Global files
+    for (const globalPath of [
+        path.join(os.homedir(), '.bahulam', 'AGENTS.md'),
+        path.join(os.homedir(), '.bahulam', 'BAHULAM.md'),
+        path.join(os.homedir(), '.claude', 'CLAUDE.md'),
+    ]) {
+        if (fs.existsSync(globalPath)) {
+            try {
+                files.push({ source: 'global', content: fs.readFileSync(globalPath, 'utf-8'), path: globalPath });
+            } catch { /* skip */ }
+        }
     }
 
-    // 2. Walk from cwd up to root, collecting CLAUDE.md files
+    // 2. Walk from cwd up to root, collecting per-directory instruction files
     const projectFiles = [];
     let dir = path.resolve(cwd);
     const root = path.parse(dir).root;
     while (dir !== root) {
         const candidates = [
+            path.join(dir, 'AGENTS.md'),
+            path.join(dir, 'BAHULAM.md'),
+            path.join(dir, '.bahulam', 'BAHULAM.md'),
             path.join(dir, 'CLAUDE.md'),
             path.join(dir, '.claude', 'CLAUDE.md'),
         ];
@@ -47,7 +66,7 @@ export function loadClaudeMdFiles(cwd = process.cwd()) {
         dir = path.dirname(dir);
     }
 
-    // Reverse so parent dirs come first (global -> project -> local)
+    // Reverse so parent dirs come first (global → project → local)
     projectFiles.reverse();
     files.push(...projectFiles);
 

package/src/core/tool-executor.mjs

@@ -16,7 +16,7 @@ import { analyzeCode } from '../context/ast-parser.mjs';
 import { ProjectRegistry } from '../tools/project-overview.mjs';
 import { SkillInstaller } from '../skills/installer.mjs';
 import { SkillsLoader } from '../skills/loader.mjs';
-import { createAgentFile, listLocalAgents, syncAgentsToBackend } from '../agents/scaffold.mjs';
+import { agentToSpec, createAgentFile, listLocalAgents, syncAgentsToBackend } from '../agents/scaffold.mjs';
 import { createWorkflowFile, listLocalWorkflows, WORKFLOW_SYNC_ENDPOINT, slugifyWorkflowName } from '../agents/workflow_scaffold.mjs';
 import { BahulamAuth } from '../auth/bahulam-auth.mjs';
 import { detectImageFile } from './attachments.mjs';
@@ -27,6 +27,8 @@ import { buildFileDiff } from './file-diff.mjs';
 import { buildWorkScope } from './work-scope.mjs';
 import { loadDiskMemory, ensureBahulamDir, globalMemoryPath, projectMemoryPath } from './memory-disk.mjs';
 import { resolveLintCommand } from './lint-resolver.mjs';
+import { PluginRegistry } from '../plugins/registry.mjs';
+import { loadPluginTool } from '../plugins/executor.mjs';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -48,6 +50,13 @@ export function createToolExecutor({
     interactionHandler = null,
     onAutoRegisterStart = null,
     onAutoRegisterDone = null,
+    pluginRegistry = null,
+    // Optional emit hook: called (debounced per key) after any plugin
+    // state write commits. Wired by the workspace server so writes turn
+    // into SSE `plugin_state_changed` events for live view updates.
+    // REPL/headless callers leave this null — state still works, just
+    // no reactive pulse.
+    stateEmit = null,
 } = {}) {
     // Cross-session memory cache. Ships in getAgentContext() on every turn,
     // so we need it to be byte-identical when the underlying disk file hasn't
@@ -146,7 +155,7 @@ export function createToolExecutor({
     }
 
     function longRunningObservationTimeoutMs() {
-        const configured = Number(process.env.KEPLER_LONG_RUNNING_TIMEOUT_MS);
+        const configured = Number(process.env.BAHULAM_LONG_RUNNING_TIMEOUT_MS);
         return Number.isFinite(configured) && configured > 0 ? configured : 15_000;
     }
 
@@ -246,14 +255,76 @@ export function createToolExecutor({
         };
     }
 
+    function pluginAgentToLocalShape(agentDef) {
+        const pluginName = agentDef._plugin_name
+            || String(agentDef.source || '').replace(/^plugin:/, '')
+            || 'unknown';
+        const source = `plugin:${pluginName}`;
+        const base = {
+            ...agentDef,
+            slug: agentDef.slug || agentDef.name || '',
+            name: agentDef.name || agentDef.slug || '',
+            description: agentDef.description || '',
+            role: agentDef.role || 'specialist',
+            model: agentDef.model || null,
+            models: agentDef.models || undefined,
+            tools: Array.isArray(agentDef.tools)
+                ? agentDef.tools
+                : (Array.isArray(agentDef.agent_tools) ? agentDef.agent_tools : []),
+            capabilities: Array.isArray(agentDef.capabilities) ? agentDef.capabilities : [],
+            domains: Array.isArray(agentDef.domains) ? agentDef.domains : [],
+            system_prompt: agentDef.system_prompt || agentDef.prompt || agentDef.instructions || '',
+            prompt: agentDef.prompt || agentDef.system_prompt || agentDef.instructions || '',
+            source_scope: 'plugin',
+            source,
+        };
+        const spec = {
+            ...agentToSpec(base),
+            source,
+            source_scope: 'plugin',
+            plugin_name: pluginName,
+        };
+        if (spec.config?.metadata && typeof spec.config.metadata === 'object') {
+            spec.config.metadata.source = source;
+            spec.config.metadata.source_scope = 'plugin';
+        }
+        const content = JSON.stringify(spec);
+        return {
+            ...base,
+            slug: spec.slug,
+            spec,
+            source,
+            source_scope: 'plugin',
+            content_hash: crypto.createHash('sha256').update(content).digest('hex'),
+        };
+    }
+
+    function listPluginAgents() {
+        if (!pluginRegistry) return [];
+        return pluginRegistry.listAgents()
+            .map(pluginAgentToLocalShape)
+            .filter(agent => agent.slug);
+    }
+
+    function listAvailableAgents() {
+        const bySlug = new Map();
+        for (const agent of listLocalAgents(process.cwd())) {
+            if (agent.slug && !bySlug.has(agent.slug)) bySlug.set(agent.slug, agent);
+        }
+        for (const agent of listPluginAgents()) {
+            if (agent.slug && !bySlug.has(agent.slug)) bySlug.set(agent.slug, agent);
+        }
+        return [...bySlug.values()];
+    }
+
     function filterLocalAgents(args = {}) {
         const scope = String(args.scope || '').trim();
-        if (scope && scope !== 'project' && scope !== 'global') {
-            throw new Error('scope must be "project" or "global"');
+        if (scope && !['project', 'global', 'plugin'].includes(scope)) {
+            throw new Error('scope must be "project", "global", or "plugin"');
         }
-        return listLocalAgents(process.cwd())
-            .filter(agent => !scope || agent.source_scope === scope)
-            .filter(agent => agentMatches(agent, args.query || args.name || ''));
+        const combined = listAvailableAgents()
+            .filter(agent => !scope || agent.source_scope === scope);
+        return combined.filter(agent => agentMatches(agent, args.query || args.name || ''));
     }
 
     function selectAgentsForSync(args = {}) {
@@ -618,8 +689,149 @@ export function createToolExecutor({
         return { output: lines.join('\n'), files, directories, truncated };
     }
 
+    // ── Plugin tool map ──────────────────────────────────────────
+    // Plugin tools are registered here alongside the built-in toolMap.
+    // They are dispatched with lower priority (built-in tools win on name collision).
+    const pluginToolMap = new Map(); // name → async handler function
+
+    function registerPluginTool(name, handler) {
+        if (pluginToolMap.has(name)) {
+            if (process.env.DEBUG) {
+                console.warn(`Plugin tool "${name}" already registered from another plugin — skipping.`);
+            }
+            return false;
+        }
+        pluginToolMap.set(name, handler);
+        return true;
+    }
+
+    // Per-plugin state handles are opened lazily on first tool call and
+    // cached process-wide. `makePluginState` itself dedupes on plugin
+    // name, so this Map only exists to avoid re-attaching stateEmit on
+    // every registered tool.
+    const _pluginStateHandles = new Map(); // pluginName -> state proxy
+    async function _pluginStateFor(pluginName) {
+        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 });
+        _pluginStateHandles.set(pluginName, state);
+        return state;
+    }
+
+    /**
+     * Register one MCP tool under `<serverName>.<toolName>` (namespaced
+     * to prevent collisions between plugins that ship servers with the
+     * same tool name). The MCP client is owned by the caller (agent-
+     * relay) which spawns/tears it down with the workspace lifetime.
+     * Handler receives the same options shape as JS plugin tools so
+     * `state`, `signal`, `pluginName` all work uniformly.
+     */
+    function registerMcpTool(pluginName, serverName, toolName, mcpClient, toolSchema = {}) {
+        const qualified = `${serverName}.${toolName}`;
+        if (toolMap[qualified] || pluginToolMap.has(qualified)) {
+            if (process.env.DEBUG) {
+                console.warn(`MCP tool "${qualified}" from plugin "${pluginName}" collides with an existing tool — skipping.`);
+            }
+            return false;
+        }
+        pluginToolMap.set(qualified, async (args, options = {}) => {
+            // The lazy-state getter matches JS plugin tools so an MCP
+            // "wrapper" tool can trivially write its result to the same
+            // Shared Blackboard (rare, but useful for cache-and-return).
+            const handlerOpts = {
+                ...options,
+                pluginName,
+                mcpServer: serverName,
+                get state() {
+                    if (this._stateP) return this._stateP;
+                    this._stateP = _pluginStateFor(pluginName);
+                    return this._stateP;
+                },
+            };
+            try {
+                const result = await mcpClient.callTool(toolName, args || {});
+                // callTool returns joined text for text/* content; pass through as output.
+                const output = typeof result === 'string' ? result : (result?.output ?? result);
+                // Allow the caller (state-writer wrapper) to introspect via handlerOpts.
+                void handlerOpts;
+                return { success: true, output, _tool: qualified, _plugin: pluginName, _mcp_server: serverName };
+            } catch (err) {
+                return {
+                    success: false,
+                    output: `MCP tool error (${qualified}): ${err.message}`,
+                    _tool: qualified,
+                    _plugin: pluginName,
+                    _mcp_server: serverName,
+                };
+            }
+        });
+        // Track schema for tool-listing surfaces (also help /tools discovery).
+        pluginToolMap.get(qualified)._mcp = { pluginName, serverName, toolName, schema: toolSchema };
+        return true;
+    }
+
+    function registerPluginToolsFromRegistry() {
+        if (!pluginRegistry) return;
+        for (const toolDef of pluginRegistry.listTools?.() || []) {
+            const name = String(toolDef.name || '').trim();
+            if (!name || toolMap[name]) continue;
+            const pluginName = toolDef._plugin_name || toolDef.plugin_name || null;
+            registerPluginTool(name, async (args, options = {}) => {
+                const handler = await loadPluginTool(toolDef._plugin_dir, toolDef.handler);
+                if (!handler) {
+                    return {
+                        success: false,
+                        output: `Plugin tool handler could not be loaded: ${name}`,
+                        _tool: name,
+                        _plugin: pluginName,
+                    };
+                }
+                // Shared-blackboard injection: handlers opt in by naming
+                // `state` in their signature (`async call(args, { state })`).
+                // The property is a getter so the SQLite file is only
+                // opened when a handler actually asks for it — plugins
+                // that never touch state pay zero disk / init cost.
+                const handlerOpts = {
+                    ...options,
+                    pluginName,
+                    get state() { /* eslint-disable no-unused-vars */
+                        // Sync getter fronting an async loader — first
+                        // access returns a Promise, which is unusual
+                        // for handler code but common enough as
+                        // `const s = await opts.state`. The awaited
+                        // value is cached on this options object so
+                        // repeat accesses in the same call don't re-await.
+                        if (this._stateP) return this._stateP;
+                        this._stateP = _pluginStateFor(pluginName);
+                        return this._stateP;
+                    },
+                };
+                try {
+                    const result = await handler.call(args || {}, handlerOpts);
+                    if (result && typeof result === 'object' && 'success' in result) {
+                        return { ...result, _tool: name, _plugin: pluginName };
+                    }
+                    return {
+                        success: true,
+                        output: typeof result === 'string' ? result : JSON.stringify(result),
+                        _tool: name,
+                        _plugin: pluginName,
+                    };
+                } catch (err) {
+                    return {
+                        success: false,
+                        output: `Plugin tool error (${name}): ${err.message}`,
+                        _tool: name,
+                        _plugin: pluginName,
+                    };
+                }
+            });
+        }
+    }
+
     async function executeToolWithHooks(name, args, options = {}) {
-        const handler = toolMap[name];
+        const handler = toolMap[name] || pluginToolMap.get(name);
         if (!handler) {
             return { success: false, output: `Unknown tool: ${name}`, _tool: name };
         }
@@ -2293,6 +2505,8 @@ export function createToolExecutor({
         },
     };
 
+    registerPluginToolsFromRegistry();
+
     return {
         /**
          * Execute a Bahulam tool by name.
@@ -2306,7 +2520,33 @@ export function createToolExecutor({
 
         /** List all available tool names. */
         listTools() {
-            return Object.keys(toolMap);
+            return [...Object.keys(toolMap), ...pluginToolMap.keys()];
+        },
+
+        /**
+         * Register one MCP-backed tool as `<serverName>.<toolName>`.
+         * Called by the workspace lifecycle after spawning per-plugin
+         * MCP clients. Returns true on success, false on name collision.
+         */
+        registerMcpTool(pluginName, serverName, toolName, mcpClient, toolSchema) {
+            return registerMcpTool(pluginName, serverName, toolName, mcpClient, toolSchema);
+        },
+
+        /**
+         * Unregister every MCP tool sourced from one server, called on
+         * plugin teardown / workspace close so subsequent sessions don't
+         * see stale `serverName.tool` entries.
+         */
+        unregisterMcpServer(pluginName, serverName) {
+            let removed = 0;
+            for (const [key, fn] of pluginToolMap) {
+                const meta = fn?._mcp;
+                if (meta && meta.pluginName === pluginName && meta.serverName === serverName) {
+                    pluginToolMap.delete(key);
+                    removed++;
+                }
+            }
+            return removed;
         },
 
         getProjectResources() {
@@ -2355,7 +2595,7 @@ export function createToolExecutor({
                 // hasn't changed between turns.
                 memory_facts: mem.facts,
                 memory_digest: mem.digest,
-                available_agents: listLocalAgents(process.cwd()).map(agent => ({
+                available_agents: listAvailableAgents().map(agent => ({
                     slug: agent.slug,
                     name: agent.name,
                     description: agent.description,
@@ -2366,6 +2606,7 @@ export function createToolExecutor({
                     capabilities: agent.capabilities,
                     domains: agent.domains,
                     source_scope: agent.source_scope,
+                    source: agent.source,
                     spec: agent.spec,
                 })),
                 available_workflows: listLocalWorkflows(process.cwd()).map(workflow => ({