@bahulam/code 0.1.10 → 0.1.12

package/src/orchestration/runner.mjs

@@ -0,0 +1,200 @@
+import * as crypto from 'node:crypto';
+import { backgroundTasks } from '../core/background-tasks.mjs';
+import { normalizeGraphSpec, validateGraph } from './graph.mjs';
+import { deriveApprovalScope } from './approval.mjs';
+import { runNode } from './node-runner.mjs';
+import { graphEvent } from './events.mjs';
+
+/**
+ * Execute a graph of agent nodes locally, in-process. Yields the same
+ * event vocabulary the main renderer already consumes, plus lifecycle
+ * events: graph_run_start, graph_node_start, graph_node_result,
+ * graph_run_result.
+ *
+ * pattern: 'sequential' runs nodes one at a time in topological order.
+ * pattern: 'parallel' groups nodes into dependency levels — nodes in the
+ * same level (no path between them) execute concurrently; their events
+ * are buffered and flushed contiguously in topological order so the
+ * output stays deterministic while wall-clock shrinks. Handoffs are
+ * snapshotted at level start: same-level nodes never see each other,
+ * only completed upstream levels.
+ */
+export async function* runGraph(graphSpec, triggerInput = {}, ctx = {}, options = {}) {
+  const spec = normalizeGraphSpec(graphSpec);
+  const agentNodes = validateGraph(spec);
+  const runId = options.runId || `gr-${crypto.randomUUID().slice(0, 12)}`;
+
+  const resolveAgent = ctx.resolveAgent || (() => null);
+  for (const node of agentNodes) {
+    if (node.type === 'job' || node.type === 'service') continue;
+    if (!node.agent) node.agent = resolveAgent(node.agent_slug);
+    if (!node.agent) throw new Error(`Unknown agent '${node.agent_slug}' in graph '${spec.name}'`);
+  }
+
+  const approvalScope = deriveApprovalScope(agentNodes, resolveAgent);
+  yield graphEvent('graph_run_start', runId, {
+    graph: spec.name,
+    pattern: spec.pattern,
+    node_count: agentNodes.length,
+    approval_scope: approvalScope,
+  });
+
+  const levels = spec.pattern === 'parallel'
+    ? dependencyLevels(agentNodes, spec.edges)
+    : agentNodes.map(node => [node]);
+
+  const nodeResults = [];
+  const handoffs = [];
+  let status = 'completed';
+  // Service nodes register their process here; the run is their lifetime
+  // scope — everything still running is killed when the graph ends,
+  // whatever path it ends by (finally covers errors and early consumer
+  // abandonment too).
+  const serviceJobs = [];
+  const nodeOptions = { ...options, runId, serviceJobs };
+
+  try {
+  for (const level of levels) {
+    if (status === 'failed') break;
+    const levelHandoffs = [...handoffs];
+
+    for (const node of level) {
+      yield graphEvent('graph_node_start', runId, {
+        node_id: node.id,
+        agent: node.agent_slug || node.id,
+        parallel_group: level.length > 1 ? level.map(n => n.id) : undefined,
+      });
+    }
+
+    // Solo level: stream events live (no buffering) — this is the /run
+    // and sequential-pattern hot path.
+    if (level.length === 1) {
+      const node = level[0];
+      const instruction = buildNodeInstruction(node, triggerInput, levelHandoffs, spec.global_params);
+      let output = '';
+      let accumulated = '';
+      let nodeStatus = 'completed';
+      try {
+        for await (const event of runNode(node, node.agent, instruction, ctx, nodeOptions)) {
+          if (event.type === 'content' || event.type === 'content_partial') {
+            accumulated += event.data?.text || event.data?.content || '';
+          }
+          if (event.type === 'complete' && typeof event.data?.final_response === 'string') {
+            output = event.data.final_response;
+          }
+          yield event;
+        }
+      } catch (err) {
+        nodeStatus = 'failed';
+        output = err?.message || String(err);
+      }
+      if (!output && nodeStatus === 'completed') output = accumulated;
+      const result = { node_id: node.id, agent: node.agent_slug || node.id, status: nodeStatus, output };
+      nodeResults.push(result);
+      yield graphEvent('graph_node_result', runId, result);
+      if (result.status === 'failed' && !node.continue_on_error) {
+        status = 'failed';
+      } else if (result.status === 'completed' && result.output) {
+        handoffs.push({ node_id: result.node_id, agent: result.agent, output: result.output });
+      }
+      continue;
+    }
+
+    // Parallel level: start every node concurrently; drain buffers in
+    // topological order so events stay contiguous per node.
+    const runs = level.map(node => collectNodeRun(
+      node,
+      buildNodeInstruction(node, triggerInput, levelHandoffs, spec.global_params),
+      ctx,
+      nodeOptions,
+    ));
+
+    for (let i = 0; i < level.length; i++) {
+      const { events, result } = await runs[i];
+      for (const event of events) yield event;
+      nodeResults.push(result);
+      yield graphEvent('graph_node_result', runId, result);
+      if (result.status === 'failed' && !level[i].continue_on_error) {
+        status = 'failed';
+      } else if (result.status === 'completed' && result.output) {
+        handoffs.push({ node_id: result.node_id, agent: result.agent, output: result.output });
+      }
+    }
+  }
+
+  } finally {
+    for (const id of serviceJobs) {
+      try { backgroundTasks.kill(id); } catch { /* already gone */ }
+    }
+  }
+
+  const result = {
+    run_id: runId,
+    graph: spec.name,
+    status,
+    node_results: nodeResults,
+    output: nodeResults.length ? nodeResults[nodeResults.length - 1].output : '',
+  };
+  yield graphEvent('graph_run_result', runId, result);
+  return result;
+}
+
+async function collectNodeRun(node, instruction, ctx, options) {
+  const events = [];
+  let output = '';
+  let accumulated = '';
+  let nodeStatus = 'completed';
+  try {
+    for await (const event of runNode(node, node.agent, instruction, ctx, options)) {
+      if (event.type === 'content' || event.type === 'content_partial') {
+        accumulated += event.data?.text || event.data?.content || '';
+      }
+      if (event.type === 'complete' && typeof event.data?.final_response === 'string') {
+        output = event.data.final_response;
+      }
+      events.push(event);
+    }
+  } catch (err) {
+    nodeStatus = 'failed';
+    output = err?.message || String(err);
+  }
+  if (!output && nodeStatus === 'completed') output = accumulated;
+  return {
+    events,
+    result: { node_id: node.id, agent: node.agent_slug || node.id, status: nodeStatus, output },
+  };
+}
+
+// Group agent nodes by dependency depth: level N nodes depend only on
+// nodes in levels < N. agentNodes arrive topologically ordered, so each
+// node's predecessors are resolved before it.
+function dependencyLevels(agentNodes, edges) {
+  const ids = new Set(agentNodes.map(node => node.id));
+  const preds = new Map(agentNodes.map(node => [node.id, []]));
+  for (const edge of edges) {
+    if (ids.has(edge.source) && ids.has(edge.target)) preds.get(edge.target).push(edge.source);
+  }
+  const depth = new Map();
+  const levels = [];
+  for (const node of agentNodes) {
+    const upstream = preds.get(node.id);
+    const d = upstream.length ? 1 + Math.max(...upstream.map(id => depth.get(id) ?? 0)) : 0;
+    depth.set(node.id, d);
+    (levels[d] ||= []).push(node);
+  }
+  return levels;
+}
+
+function buildNodeInstruction(node, triggerInput, handoffs, globalParams) {
+  const parts = [node.prompt || triggerInput.instruction || ''];
+  if (globalParams && Object.keys(globalParams).length) {
+    parts.push(`Parameters:\n${JSON.stringify(globalParams, null, 2)}`);
+  }
+  if (handoffs.length) {
+    const upstream = handoffs
+      .map(h => `--- handoff from ${h.agent} ---\n${h.output}`)
+      .join('\n\n');
+    parts.push(`Results from earlier steps:\n\n${upstream}`);
+  }
+  return parts.filter(Boolean).join('\n\n');
+}

package/src/plugins/executor.mjs

@@ -0,0 +1,121 @@
+/**
+ * Plugin Executor — dynamic import() of plugin tool handler modules.
+ *
+ * Plugin tools are .mjs / .js files that export at minimum a `call(input)` function.
+ * They are loaded relative to the plugin directory.
+ */
+
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'path';
+import { makePluginState } from './state.mjs';
+
+/**
+ * Load a plugin tool handler by resolving its path relative to the plugin directory.
+ * @param {string} pluginDir - Absolute path to the plugin directory
+ * @param {string} handlerPath - Relative path from plugin.yaml (e.g. ./tools/my-tool.mjs)
+ * @returns {Promise<object|null>} { name, description, inputSchema, call } or null
+ */
+export async function loadPluginTool(pluginDir, handlerPath) {
+  try {
+    const absPath = path.resolve(pluginDir, handlerPath);
+    const fileUrl = pathToFileURL(absPath).href;
+
+    // Cache-busting for development: append timestamp
+    const url = `${fileUrl}?t=${Date.now()}`;
+    const mod = await import(url);
+
+    // The module should export at minimum: call(input) => { success, output }
+    if (typeof mod.call !== 'function') {
+      if (process.env.DEBUG) {
+        console.error(`Plugin handler ${handlerPath} does not export a call() function`);
+      }
+      return null;
+    }
+
+    return {
+      name: mod.name || path.basename(handlerPath, path.extname(handlerPath)),
+      description: mod.description || '',
+      inputSchema: mod.inputSchema || mod.input_schema || { type: 'object', properties: {} },
+      call: mod.call,
+      validateInput: mod.validateInput || null,
+    };
+  } catch (err) {
+    if (process.env.DEBUG) {
+      console.error(`Failed to load plugin tool handler ${handlerPath}: ${err.message}`);
+    }
+    return null;
+  }
+}
+
+/**
+ * Create a plugin tool executor for a given plugin directory.
+ * Loads all tool handlers and returns an execute function.
+ *
+ * @param {object} manifest - Normalized plugin manifest
+ * @returns {Promise<{ execute(name, args): Promise<object>, list(): string[] }>}
+ */
+/**
+ * Create a plugin tool executor for a given plugin directory.
+ * Loads all tool handlers and returns an execute function.
+ *
+ * @param {object} manifest - Normalized plugin manifest
+ * @param {object} [opts]
+ * @param {(evt: {plugin: string, op: string, kind: string, target: string, at: string}) => void} [opts.stateEmit]
+ *   Called (debounced) after every state write commits. The workspace
+ *   server threads this in so state changes turn into SSE events for
+ *   live view updates — the Shared Blackboard's reactive pulse.
+ * @returns {Promise<{ execute(name, args): Promise<object>, list(): string[], state: object|null }>}
+ */
+export async function createPluginToolExecutor(manifest, opts = {}) {
+  const pluginDir = manifest._dir || '';
+  const tools = manifest.spec?.tools || [];
+  const handlers = new Map(); // name → { handler, toolDef }
+  const pluginName = manifest.metadata?.name || '';
+
+  for (const toolDef of tools) {
+    if (!toolDef.tool) continue;
+    const handler = await loadPluginTool(pluginDir, toolDef.tool);
+    if (handler) {
+      handlers.set(toolDef.name, { handler, toolDef });
+    }
+  }
+
+  // One state instance per plugin, opened lazily so plugins that never
+  // touch state don't create empty ~/.bahulam/data/<name> directories.
+  let _state = null;
+  function getState() {
+    if (!pluginName) return null; // no name → no isolation → refuse state
+    if (_state) return _state;
+    _state = makePluginState(pluginName, { emit: opts.stateEmit || null });
+    return _state;
+  }
+
+  return {
+    execute: async (name, args, options = {}) => {
+      const entry = handlers.get(name);
+      if (!entry) {
+        return { success: false, output: `Plugin tool not found: ${name}` };
+      }
+      // Inject the shared-blackboard handle. Handlers opt in by naming
+      // it in their signature: `async call(args, { state })`. The
+      // getter defers opening the SQLite file until the first access,
+      // so handlers that don't use state pay no cost.
+      const handlerOpts = {
+        ...options,
+        get state() { return getState(); },
+        pluginName,
+      };
+      try {
+        const result = await entry.handler.call(args || {}, handlerOpts);
+        return result?.success !== false
+          ? { success: true, output: result?.output ?? result, _tool: name, _plugin: pluginName }
+          : { success: false, output: result?.output ?? String(result), _tool: name, _plugin: pluginName };
+      } catch (err) {
+        return { success: false, output: `Plugin tool error (${name}): ${err.message}`, _tool: name, _plugin: pluginName };
+      }
+    },
+    list: () => [...handlers.keys()],
+    /** Get (or open) the plugin's state handle — used by the view API. */
+    get state() { return getState(); },
+  };
+}

package/src/plugins/loader.mjs

@@ -1,138 +1,138 @@
 /**
- * Plugin Loader — load plugins from directory, git, or npm.
+ * Plugin Loader — high-level facade for installing, listing, and removing plugins.
  *
- * Plugins can provide: tools, agents, skills, hooks.
- * Plugin format: a directory with a plugin.json manifest.
+ * Uses PluginRegistry for scanning/loading, and provides git-based install.
+ * Plugin format: a directory with plugin.yaml (bahulam.plugin/1).
  */
 
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { execSync } from 'child_process';
+import { PluginRegistry } from './registry.mjs';
 
 export class PluginLoader {
-    /**
-     * @param {string} [pluginDir] - directory to scan for plugins
-     */
-    constructor(pluginDir) {
-        this.pluginDir = pluginDir ||
-            path.join(os.homedir(), '.claude', 'plugins');
-        this.plugins = new Map();
-    }
-
-    /**
-     * Load plugins from the plugin directory.
-     * @returns {Array<object>} loaded plugin manifests
-     */
-    async loadFromDirectory(dir) {
-        const targetDir = dir || this.pluginDir;
-        const loaded = [];
-
-        try {
-            if (!fs.existsSync(targetDir)) return loaded;
-
-            const entries = fs.readdirSync(targetDir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (!entry.isDirectory()) continue;
-
-                const manifestPath = path.join(targetDir, entry.name, 'plugin.json');
-                if (!fs.existsSync(manifestPath)) continue;
-
-                try {
-                    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-                    manifest._dir = path.join(targetDir, entry.name);
-                    manifest._name = entry.name;
-                    this.plugins.set(manifest.name || entry.name, manifest);
-                    loaded.push(manifest);
-                } catch {
-                    // Skip malformed plugins
-                }
-            }
-        } catch {
-            // Directory not readable
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.pluginDir] - Primary plugin directory
+   * @param {string[]} [options.pluginDirs] - Additional plugin directories
+   * @param {string[]} [options.disabled] - Plugin names to disable
+   */
+  constructor(options = {}) {
+    const { pluginDir, pluginDirs, disabled } = options;
+    this.registry = new PluginRegistry({
+      pluginDir: pluginDir || path.join(os.homedir(), '.bahulam', 'plugins'),
+      pluginDirs,
+      disabled,
+    });
+    this.pluginDir = pluginDir || path.join(os.homedir(), '.bahulam', 'plugins');
+  }
+
+  /**
+   * Load all plugins from registered directories.
+   * @returns {PluginRegistry}
+   */
+  load() {
+    this.registry.scan();
+    return this.registry;
+  }
+
+  /**
+   * Load plugins from a specific directory (scans subdirectories).
+   * @param {string} dir
+   * @returns {PluginRegistry}
+   */
+  loadFromDirectory(dir) {
+    this.registry._scanDir(dir);
+    return this.registry;
+  }
+
+  /**
+   * Clone a plugin from a git repo and load it.
+   * @param {string} repoUrl - git repository URL
+   * @param {string} [name] - plugin name (default: repo name)
+   * @returns {object|null} loaded manifest
+   */
+  loadFromGit(repoUrl, name) {
+    const pluginName = name || repoUrl.split('/').pop()?.replace('.git', '') || 'plugin';
+    const targetDir = path.join(this.pluginDir, pluginName);
+
+    try {
+      fs.mkdirSync(this.pluginDir, { recursive: true });
+
+      if (fs.existsSync(targetDir)) {
+        // Update existing
+        execSync('git pull', { cwd: targetDir, stdio: 'pipe' });
+      } else {
+        // Clone new
+        execSync(`git clone --depth 1 ${repoUrl} ${targetDir}`, { stdio: 'pipe' });
+      }
+
+      const manifestPath = path.join(targetDir, 'plugin.yaml');
+      const altPath = path.join(targetDir, 'plugin.json');
+      const exists = fs.existsSync(manifestPath) ? manifestPath : (fs.existsSync(altPath) ? altPath : null);
+
+      if (exists) {
+        const { parsePluginManifestFile } = await import('./manifest.mjs');
+        const manifest = parsePluginManifestFile(exists);
+        if (manifest) {
+          this.registry.register(manifest);
+          return manifest;
         }
-
-        return loaded;
-    }
-
-    /**
-     * Clone a plugin from a git repo and load it.
-     * @param {string} repoUrl - git repository URL
-     * @param {string} [name] - plugin name (default: repo name)
-     * @returns {object|null} loaded manifest
-     */
-    async loadFromGit(repoUrl, name) {
-        const pluginName = name || repoUrl.split('/').pop()?.replace('.git', '') || 'plugin';
-        const targetDir = path.join(this.pluginDir, pluginName);
-
-        try {
-            fs.mkdirSync(this.pluginDir, { recursive: true });
-
-            if (fs.existsSync(targetDir)) {
-                // Update existing
-                execSync('git pull', { cwd: targetDir, stdio: 'pipe' });
-            } else {
-                // Clone new
-                execSync(`git clone --depth 1 ${repoUrl} ${targetDir}`, { stdio: 'pipe' });
-            }
-
-            const manifestPath = path.join(targetDir, 'plugin.json');
-            if (fs.existsSync(manifestPath)) {
-                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-                manifest._dir = targetDir;
-                manifest._name = pluginName;
-                this.plugins.set(manifest.name || pluginName, manifest);
-                return manifest;
-            }
-        } catch {
-            // Git operation failed
-        }
-
-        return null;
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`Failed to clone plugin ${repoUrl}: ${err.message}`);
+      }
     }
 
-    /**
-     * Get all installed plugins.
-     * @returns {Array<object>}
-     */
-    getInstalledPlugins() {
-        return [...this.plugins.values()];
+    return null;
+  }
+
+  /**
+   * Get all installed plugins.
+   * @returns {object[]}
+   */
+  getInstalledPlugins() {
+    return this.registry.list();
+  }
+
+  /**
+   * Get a plugin by name.
+   * @param {string} name
+   * @returns {object|undefined}
+   */
+  getPlugin(name) {
+    return this.registry.get(name);
+  }
+
+  /**
+   * Remove a plugin by name.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  removePlugin(name) {
+    const plugin = this.registry.get(name);
+    if (!plugin) return false;
+
+    try {
+      if (plugin._dir && fs.existsSync(plugin._dir)) {
+        fs.rmSync(plugin._dir, { recursive: true, force: true });
+      }
+    } catch (err) {
+      if (process.env.DEBUG) {
+        console.error(`Failed to remove plugin directory ${plugin._dir}: ${err.message}`);
+      }
     }
 
-    /**
-     * Get a plugin by name.
-     * @param {string} name
-     * @returns {object|undefined}
-     */
-    getPlugin(name) {
-        return this.plugins.get(name);
-    }
-
-    /**
-     * Remove a plugin by name.
-     * @param {string} name
-     * @returns {boolean}
-     */
-    removePlugin(name) {
-        const plugin = this.plugins.get(name);
-        if (!plugin) return false;
-
-        try {
-            if (plugin._dir && fs.existsSync(plugin._dir)) {
-                fs.rmSync(plugin._dir, { recursive: true, force: true });
-            }
-        } catch {
-            // Best effort
-        }
-
-        return this.plugins.delete(name);
-    }
-
-    /**
-     * Get plugin count.
-     * @returns {number}
-     */
-    count() {
-        return this.plugins.size;
-    }
-}
+    return this.registry.remove(name);
+  }
+
+  /**
+   * Get plugin count.
+   * @returns {number}
+   */
+  count() {
+    return this.registry.count();
+  }
+}