@bahulam/code 0.1.21 → 0.1.23

package/src/core/tool-executor.mjs

@@ -31,6 +31,7 @@ import { backgroundTasks } from './background-tasks.mjs';
 import { normalizeLintOutput, resolveLintCommand } from './lint-resolver.mjs';
 import { PluginRegistry } from '../plugins/registry.mjs';
 import { loadPluginTool } from '../plugins/executor.mjs';
+import { makePluginState } from '../plugins/state.mjs';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -60,9 +61,9 @@ export function createToolExecutor({
     // no reactive pulse.
     stateEmit = null,
     delegateRunner = null,
-    // Execution channel. 'main' (REPL/headless/CLI): plugin agents are
-    // workspace-scoped and excluded from listings and the agent-context
-    // envelope unless allowlisted in settings plugins.agent_allowlist.
+    // Execution channel. 'main' (REPL/headless/CLI): plugin entry agents and
+    // allowlisted plugin agents are listed in the agent-context envelope.
+    // Other plugin helpers stay workspace-scoped.
     // 'workspace' (plugin workspace sessions via agent-relay): the
     // session plugin's agents are fully available.
     channel = 'main',
@@ -632,20 +633,82 @@ export function createToolExecutor({
         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.
+    // Per-plugin state handles are opened lazily on first 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 — and to keep the agent-context summary reading the
+    // same connection a plugin tool writes through.
     const _pluginStateHandles = new Map(); // pluginName -> state proxy
-    async function _pluginStateFor(pluginName) {
+
+    /**
+     * The normalized `config.state` block a plugin declared, or null when
+     * it declared none. Declared tables are created and additively
+     * migrated when the DB opens, so this is also the schema the plugin's
+     * own handlers query via `state.query()`.
+     */
+    function pluginStateDecl(pluginName) {
+        if (!pluginName || typeof pluginRegistry?.list !== 'function') return null;
+        const plugin = pluginRegistry.list().find(p => p.metadata?.name === pluginName);
+        return plugin?.config?.state || null;
+    }
+
+    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 });
+        const decl = pluginStateDecl(pluginName);
+        const state = makePluginState(pluginName, {
+            emit: stateEmit,
+            tables: decl?.tables || [],
+        });
         _pluginStateHandles.set(pluginName, state);
         return state;
     }
 
+    // ── Declared plugin state → agent context ────────────────────
+    // Tier 1 of the state-visibility contract. Plugins that declare
+    // `config.state.context_always` get exactly those keys and streams
+    // injected into the agent context each turn, so a fresh session opens
+    // already knowing what the previous one left behind — instead of
+    // spending a tool call to rediscover it, or silently redoing work.
+    //
+    // Opt-in by construction: a plugin that declares nothing contributes
+    // nothing, and an opted-in plugin that has recorded nothing yet is
+    // skipped rather than shipping an empty block.
+    //
+    // Reads are keyed on the state DB's size+mtime so the payload stays
+    // byte-identical between turns when nothing wrote. Same reasoning as
+    // the memory digest above: a context block that churns on every turn
+    // invalidates the backend's prompt cache on every ExecuteRequest.
+    const _pluginStateCache = new Map(); // pluginName -> { key, entry }
+
+    function pluginStateContext() {
+        if (typeof pluginRegistry?.list !== 'function') return [];
+        const out = [];
+        for (const plugin of pluginRegistry.list()) {
+            const name = plugin.metadata?.name;
+            const decl = plugin.config?.state;
+            if (!name || !decl?.context_always?.length) continue;
+            try {
+                const state = _pluginStateFor(name);
+                const stat = fs.existsSync(state.path) ? fs.statSync(state.path) : null;
+                const key = stat ? `${stat.size}:${Math.round(stat.mtimeMs)}` : 'missing';
+                const cached = _pluginStateCache.get(name);
+                if (cached && cached.key === key) {
+                    out.push(cached.entry);
+                    continue;
+                }
+                const summary = state.summary(decl.context_always);
+                const hasContent = Object.keys(summary.kv).length > 0
+                    || Object.values(summary.streams).some(rows => rows.length > 0);
+                if (!hasContent) continue;
+                const entry = { plugin: name, ...summary };
+                _pluginStateCache.set(name, { key, entry });
+                out.push(entry);
+            } catch { /* one broken plugin must never break the session */ }
+        }
+        return out;
+    }
+
     /**
      * Register one MCP tool under `<serverName>.<toolName>` (namespaced
      * to prevent collisions between plugins that ship servers with the
@@ -706,6 +769,56 @@ export function createToolExecutor({
             const name = String(toolDef.name || '').trim();
             if (!name || toolMap[name]) continue;
             const pluginName = toolDef._plugin_name || toolDef.plugin_name || null;
+            if (toolDef._state_tool) {
+                // Manifest-declared state query tool (config.state.context_tools).
+                // There is no module to import — the author declared a table
+                // and an optional WHERE clause; the CLI supplies the handler.
+                // `readTable` refuses undeclared tables, so author-supplied
+                // SQL can't be steered into arbitrary table access.
+                const spec = toolDef._state_tool;
+                registerPluginTool(name, async (args) => {
+                    try {
+                        const state = _pluginStateFor(spec.plugin || pluginName);
+                        if (!state) {
+                            return {
+                                success: false,
+                                output: `Plugin state unavailable for '${name}'.`,
+                                _tool: name,
+                                _plugin: pluginName,
+                            };
+                        }
+                        const bound = (spec.params || []).map(key => args?.[key] ?? null);
+                        // An unfiltered call should list everything, not match
+                        // nothing — `topic = NULL` is never true in SQL. Apply
+                        // the WHERE only once a declared param was supplied.
+                        const useWhere = Boolean(spec.where) && bound.some(v => v !== null);
+                        const rows = state.readTable(spec.table, {
+                            where: useWhere ? spec.where : '',
+                            params: useWhere ? bound : [],
+                            limit: args?.limit ?? spec.limit,
+                        });
+                        return {
+                            success: true,
+                            output: rows.length
+                                ? JSON.stringify(rows, null, 2)
+                                : `No rows in ${spec.table}${useWhere ? ' matching those filters' : ''}.`,
+                            rows,
+                            count: rows.length,
+                            _tool: name,
+                            _plugin: pluginName,
+                            _state_tool: true,
+                        };
+                    } catch (err) {
+                        return {
+                            success: false,
+                            output: `Plugin state tool error (${name}): ${err.message}`,
+                            _tool: name,
+                            _plugin: pluginName,
+                        };
+                    }
+                }, { pluginName, source: 'state', stateTool: spec });
+                continue;
+            }
             if (toolDef._composed?.kind === 'pi') {
                 // Composed pi tools resolve at invocation time: look up the
                 // installed pi package's directory, load the specific handler
@@ -2281,7 +2394,7 @@ export function createToolExecutor({
             const agents = filterLocalAgents(args).map(compactAgentMetadata);
             const payload = { agents, count: agents.length };
             if (agents.some(agent => agent.runnable === false)) {
-                payload.note = 'Agents with runnable:false are workspace-scoped plugin agents; add their slug to settings plugins.agent_allowlist to invoke them from the main loop.';
+                payload.note = 'Agents with runnable:false are workspace-scoped plugin helpers; declare an entry_agent or add their slug to settings plugins.agent_allowlist to invoke them from the main loop.';
             }
             return {
                 success: true,
@@ -2777,6 +2890,7 @@ export function createToolExecutor({
         getAgentContext() {
             const global = projectRegistry.getGlobalContext();
             const mem = _readMemorySnapshot();
+            const pluginState = pluginStateContext();
             return {
                 identity: global.identity,
                 preferences: global.preferences,
@@ -2804,6 +2918,14 @@ export function createToolExecutor({
                     spec: agent.spec,
                 })),
                 sub_agent_observability: agentRegistry.observability(),
+                // Cross-session plugin state. Only plugins that opted in via
+                // config.state.context_always appear here, and only the keys
+                // and streams they named — this is how a plugin's local app
+                // state survives a session boundary without the agent having
+                // to know to go looking for it.
+                ...(pluginState.length ? {
+                    plugin_state: pluginState,
+                } : {}),
                 // Background jobs the model should know about. Stable fields
                 // only (no durations) so the entry — and the prompt cache —
                 // changes on status transitions, not every turn.

package/src/local-service/server.mjs

@@ -640,10 +640,7 @@ function scanPlugins(session) {
   const dirs = new Map();
   try {
     const registry = new PluginRegistry({
-      pluginDirs: [
-        path.join(session.root_path || process.cwd(), '.bahulam', 'plugins'),
-        path.join(os.homedir(), '.bahulam', 'plugins'),
-      ],
+      pluginDirs: [path.join(os.homedir(), '.bahulam', 'plugins')],
     }).scan();
     for (const manifest of registry.list()) {
       const pluginName = manifest.metadata?.name || '';

package/src/mcp/client.mjs

@@ -13,6 +13,7 @@
 import { spawn } from 'child_process';
 
 const MCP_PROTOCOL_VERSION = '2024-11-05';
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 
 export class McpClient {
     /**
@@ -102,7 +103,9 @@ export class McpClient {
             }
         });
         this.connected = true;
-        return this._initRemote();
+        await this._initRemote();
+        this._notifyRemote('notifications/initialized', {});
+        return this.serverInfo;
     }
 
     async _connectWebSocket() {
@@ -117,6 +120,7 @@ export class McpClient {
             capabilities: {},
             clientInfo: { name: 'bahulam-code', version: '2.0.0' },
         });
+        this._notifyRemote('notifications/initialized', {});
         return this.serverInfo;
     }
 
@@ -132,6 +136,7 @@ export class McpClient {
             capabilities: {},
             clientInfo: { name: 'bahulam-code', version: '2.0.0' },
         });
+        this._notifyRemote('notifications/initialized', {});
         return this.serverInfo;
     }
 
@@ -145,11 +150,39 @@ export class McpClient {
         return result;
     }
 
+    _notifyRemote(method, params) {
+        if (this.transport?.request) {
+            // WebSocket / sHTTP transports have native request() — use send()
+            // for notifications (no id, no response expected).
+            if (this.transport.send) {
+                this.transport.send({ jsonrpc: '2.0', method, params }).catch(() => {});
+            }
+        } else if (this.transport) {
+            // SSE transport — fire-and-forget via send()
+            this.transport.send({ jsonrpc: '2.0', method, params }).catch(() => {});
+        }
+    }
+
     async _transportRequest(method, params) {
         return new Promise((resolve, reject) => {
             const id = ++this.requestId;
-            this.pending.set(id, { resolve, reject });
-            this.transport.send({ jsonrpc: '2.0', id, method, params });
+            const timeout = setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`MCP request timeout: ${method} (${DEFAULT_REQUEST_TIMEOUT_MS}ms)`));
+                }
+            }, DEFAULT_REQUEST_TIMEOUT_MS);
+            this.pending.set(id, {
+                resolve: (val) => { clearTimeout(timeout); resolve(val); },
+                reject: (err) => { clearTimeout(timeout); reject(err); },
+            });
+            this.transport.send({ jsonrpc: '2.0', id, method, params }).catch(err => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    clearTimeout(timeout);
+                    reject(err);
+                }
+            });
         });
     }
 
@@ -177,7 +210,14 @@ export class McpClient {
             result = await this._request('tools/call', params);
         }
         if (result?.content && Array.isArray(result.content)) {
-            return result.content.filter(c => c.type === 'text').map(c => c.text).join('\n');
+            const textParts = result.content.filter(c => c.type === 'text').map(c => c.text);
+            const imageParts = result.content.filter(c => c.type === 'image');
+            if (imageParts.length > 0 && textParts.length === 0) {
+                return result;
+            }
+            if (textParts.length > 0) {
+                return textParts.join('\n');
+            }
         }
         return result;
     }
@@ -222,7 +262,16 @@ export class McpClient {
     _request(method, params) {
         return new Promise((resolve, reject) => {
             const id = ++this.requestId;
-            this.pending.set(id, { resolve, reject });
+            const timeout = setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`MCP request timeout: ${method} (${DEFAULT_REQUEST_TIMEOUT_MS}ms)`));
+                }
+            }, DEFAULT_REQUEST_TIMEOUT_MS);
+            this.pending.set(id, {
+                resolve: (val) => { clearTimeout(timeout); resolve(val); },
+                reject: (err) => { clearTimeout(timeout); reject(err); },
+            });
             const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params });
             this.process.stdin.write(msg + '\n');
         });

package/src/mcp/loader.mjs

@@ -0,0 +1,98 @@
+/**
+ * MCP Settings Loader — bridges settings-based mcpServers to the tool executor.
+ *
+ * The agent-relay path already spawns MCP servers from plugin manifests.
+ * This module provides the same capability for CLI/REPL/headless mode by
+ * reading mcpServers from the settings chain (~/.claude/settings.json etc.)
+ * and optionally from ~/.bahulam/config.json.
+ *
+ * Usage:
+ *   import { loadMcpServers } from '../mcp/loader.mjs';
+ *   const mcpClients = await loadMcpServers(toolExecutor, settings);
+ *   // ... later ...
+ *   await mcpClients.disconnectAll();
+ */
+
+import { McpClient } from './client.mjs';
+
+/**
+ * Recursively expand ${VAR} patterns in a config object using process.env.
+ * Matches the behavior in agent-relay.mjs _expandEnvInMcpConfig.
+ * @param {*} value
+ * @returns {*}
+ */
+function expandEnv(value) {
+    if (typeof value === 'string') {
+        return value.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? '');
+    }
+    if (Array.isArray(value)) return value.map(expandEnv);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value).map(([k, v]) => [k, expandEnv(v)]),
+        );
+    }
+    return value;
+}
+
+/**
+ * Load and connect MCP servers from settings, registering their tools
+ * with the tool executor.
+ *
+ * @param {object} toolExecutor - the createToolExecutor() instance
+ * @param {object} settings - loaded settings (from loadSettings())
+ * @param {object} [options]
+ * @param {string} [options.pluginName='settings'] - namespace for tool registration
+ * @returns {Promise<{clients: Array, disconnectAll: Function}>}
+ */
+export async function loadMcpServers(toolExecutor, settings, options = {}) {
+    const pluginName = options.pluginName || 'settings';
+    const servers = settings?.mcpServers || {};
+    const clients = [];
+
+    for (const [name, config] of Object.entries(servers)) {
+        if (!config || typeof config !== 'object') continue;
+        if (!config.command && !config.url) continue;
+
+        try {
+            // Merge the config's env block into process.env BEFORE expanding
+            // ${VAR} patterns in args/env. This matches the Claude Desktop
+            // convention: the env block sets vars for the spawned process
+            // AND for ${VAR} expansion in the same config.
+            if (config.env && typeof config.env === 'object') {
+                for (const [k, v] of Object.entries(config.env)) {
+                    if (typeof v === 'string' && !process.env[k]) {
+                        process.env[k] = v;
+                    }
+                }
+            }
+            const expanded = expandEnv(config);
+            const client = new McpClient(expanded);
+            await client.connect();
+            const tools = await client.listTools();
+            for (const tool of tools) {
+                if (toolExecutor.registerMcpTool) {
+                    toolExecutor.registerMcpTool(pluginName, name, tool.name, client, tool.inputSchema || {});
+                }
+            }
+            clients.push({ name, client });
+            if (process.env.MCP_DEBUG) {
+                process.stderr.write(`[mcp:settings] ${name}: ${tools.length} tools registered\n`);
+            }
+        } catch (err) {
+            // One server failure must never block the session.
+            if (process.env.MCP_DEBUG) {
+                process.stderr.write(`[mcp:settings] ${name} failed: ${err.message}\n`);
+            }
+        }
+    }
+
+    return {
+        clients,
+        async disconnectAll() {
+            for (const { name, client } of clients) {
+                try { toolExecutor?.unregisterMcpServer?.(pluginName, name); } catch {}
+                try { await client.disconnect(); } catch {}
+            }
+        },
+    };
+}

package/src/mcp/transport-shttp.mjs

@@ -16,6 +16,7 @@ export class StreamableHttpTransport {
         this.timeout = options.timeout || 30000;
         this.sessionId = options.sessionId || null;
         this.connected = false;
+        this.requestId = 0;
     }
 
     async connect() {
@@ -42,7 +43,7 @@ export class StreamableHttpTransport {
      * Collects all events and returns the final result.
      */
     async request(method, params) {
-        const id = Date.now();
+        const id = ++this.requestId;
         const body = { jsonrpc: '2.0', id, method, params };
 
         const headers = {