@bahulam/code 0.1.11 → 0.1.13

package/src/core/background-tasks.mjs

@@ -0,0 +1,186 @@
+/**
+ * BackgroundTasks — the one registry for long-running processes the agent
+ * starts (docker build, npm run dev, test suites). Jobs get a run id,
+ * a per-job timeout with SIGTERM→SIGKILL escalation, output spooled to
+ * .bahulam/tmp/jobs/<id>.log (with a bounded in-memory tail), completion
+ * listeners for wake-on-finish delivery, and best-effort cleanup of the
+ * whole process group when the CLI exits.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const KILL_ESCALATION_MS = 5000;
+const MAX_TAIL_BYTES = 64 * 1024;
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return String(str || '').replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+}
+
+class BackgroundTasks {
+  constructor() {
+    this.jobs = new Map();
+    this._seq = 0;
+    this._listeners = new Set();
+    this._exitHookInstalled = false;
+  }
+
+  onExit(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  start({ command, cwd = process.cwd(), timeoutMs = DEFAULT_TIMEOUT_MS, name = '', on_complete = null }) {
+    this._installExitHook();
+    const id = `job-${++this._seq}-${Date.now().toString(36)}`;
+    const logDir = path.join(cwd, '.bahulam', 'tmp', 'jobs');
+    fs.mkdirSync(logDir, { recursive: true });
+    const logPath = path.join(logDir, `${id}.log`);
+    const logStream = fs.createWriteStream(logPath);
+
+    const proc = spawn('bash', ['-c', command], {
+      cwd,
+      env: { ...process.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+
+    const job = {
+      id,
+      name: name || command.slice(0, 60),
+      command,
+      cwd,
+      pid: proc.pid,
+      status: 'running',
+      exit_code: null,
+      started_at: Date.now(),
+      ended_at: null,
+      log_path: logPath,
+      tail: '',
+      timed_out: false,
+      on_complete,
+      _proc: proc,
+      _done: null,
+    };
+
+    const appendTail = (chunk) => {
+      const next = job.tail + chunk.toString();
+      job.tail = next.length > MAX_TAIL_BYTES ? next.slice(next.length - MAX_TAIL_BYTES) : next;
+    };
+    proc.stdout.on('data', (d) => { logStream.write(d); appendTail(d); });
+    proc.stderr.on('data', (d) => { logStream.write(d); appendTail(d); });
+
+    let killTimer = null;
+    const timer = timeoutMs > 0 ? setTimeout(() => {
+      job.timed_out = true;
+      this._kill(job, 'SIGTERM');
+      killTimer = setTimeout(() => this._kill(job, 'SIGKILL'), KILL_ESCALATION_MS);
+    }, timeoutMs) : null;
+    if (timer?.unref) timer.unref();
+
+    job._done = new Promise((resolve) => {
+      proc.on('close', (code) => {
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        job.exit_code = code;
+        job.ended_at = Date.now();
+        job.status = job.timed_out ? 'timeout'
+          : job.status === 'killed' ? 'killed'
+          : code === 0 ? 'completed' : 'failed';
+        job.tail = stripAnsi(job.tail);
+        logStream.end();
+        for (const listener of this._listeners) {
+          try { listener(this.describe(job.id)); } catch { /* listeners are best-effort */ }
+        }
+        resolve(this.describe(job.id));
+      });
+      proc.on('error', (err) => {
+        job.status = 'failed';
+        job.tail = `${job.tail}\n${err.message}`.trim();
+        job.ended_at = Date.now();
+        logStream.end();
+        resolve(this.describe(job.id));
+      });
+    });
+
+    proc.unref();
+    this.jobs.set(id, job);
+    return this.describe(id);
+  }
+
+  /** Await a job's completion; resolves with its final description. */
+  wait(id) {
+    const job = this.jobs.get(id);
+    if (!job) return Promise.resolve(null);
+    if (job.status !== 'running') return Promise.resolve(this.describe(id));
+    // Background jobs are unref'd so fire-and-forget tasks do not pin the CLI
+    // open. When a caller explicitly awaits wait(id), temporarily ref the
+    // process so fast commands still get their close event before Node decides
+    // the top-level await is unsettled.
+    try { job._proc?.ref?.(); } catch { /* best effort */ }
+    return job._done.finally(() => {
+      try { job._proc?.unref?.(); } catch { /* best effort */ }
+    });
+  }
+
+  describe(id) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    return {
+      id: job.id,
+      name: job.name,
+      command: job.command,
+      pid: job.pid,
+      status: job.status,
+      exit_code: job.exit_code,
+      duration_s: Math.round(((job.ended_at || Date.now()) - job.started_at) / 1000),
+      log_path: job.log_path,
+      tail: job.tail,
+      timed_out: job.timed_out,
+      on_complete: job.on_complete || null,
+    };
+  }
+
+  list() {
+    return [...this.jobs.keys()].map(id => {
+      const d = this.describe(id);
+      return { ...d, tail: undefined };
+    });
+  }
+
+  kill(id) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    if (job.status === 'running') {
+      job.status = 'killed';
+      this._kill(job, 'SIGTERM');
+      setTimeout(() => this._kill(job, 'SIGKILL'), KILL_ESCALATION_MS)?.unref?.();
+    }
+    return this.describe(id);
+  }
+
+  _kill(job, signal) {
+    if (!job?._proc?.pid) return;
+    try {
+      if (process.platform !== 'win32') {
+        process.kill(-job._proc.pid, signal);
+        return;
+      }
+    } catch { /* fall through */ }
+    try { job._proc.kill(signal); } catch { /* already exited */ }
+  }
+
+  _installExitHook() {
+    if (this._exitHookInstalled) return;
+    this._exitHookInstalled = true;
+    process.on('exit', () => {
+      for (const job of this.jobs.values()) {
+        if (job.status === 'running') this._kill(job, 'SIGKILL');
+      }
+    });
+  }
+}
+
+export const backgroundTasks = new BackgroundTasks();

package/src/core/headless.mjs

@@ -47,7 +47,7 @@ import {
  * @param {number} [opts.maxCost] - abort if cost exceeds this USD amount
  * @param {boolean} [opts.verbose] - show progress on stderr
  */
-export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false, cacheReport = null, local = false, vision = [] }) {
+export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false, cacheReport = null, local = false, vision = [], agent = null, workflow = null }) {
     const startTime = Date.now();
 
     const log = (msg) => {
@@ -61,12 +61,63 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     // ── Auth ──
     const auth = new BahulamAuth();
     const creds = auth.loadCredentials();
-    if (!creds.token) {
+    const graphTarget = agent || workflow;
+    const anthKey = process.env.ANTHROPIC_API_KEY || creds.anthropicKey;
+    const orKey = process.env.OPENROUTER_API_KEY || creds.openRouterKey;
+    // Graph runs execute locally and only need a model key; everything
+    // else still requires login (the backend runs the agent loop).
+    if (!creds.token && !(graphTarget && (anthKey || orKey))) {
         emit({ type: 'error', error: 'Not logged in. Run: bahulam login' });
         process.exit(1);
     }
 
-    // Scan plugins so client_tools and client_agents are sent to the backend.
+    // ── Deterministic graph target: --agent <slug> / --workflow <name> ──
+    if (graphTarget) {
+        const { dispatch } = await import('../orchestration/dispatch.mjs');
+        const { listLocalWorkflows } = await import('../agents/workflow_scaffold.mjs');
+        const pluginRegistry = new PluginRegistry().scan();
+        const toolExecutor = createToolExecutor({ pluginRegistry });
+        const timer = setTimeout(() => {
+            emit({ type: 'timeout', duration_s: timeout });
+            process.exit(2);
+        }, timeout * 1000);
+
+        const outcome = await dispatch({
+            type: 'invoke',
+            source: 'cli:headless',
+            target: agent ? { kind: 'agent', slug: agent } : { kind: 'workflow', slug: workflow },
+            params: { instruction: instruction || '' },
+            channel: null,
+            substrate: 'direct',
+        }, {
+            toolExecutor,
+            listRunnables: () => toolExecutor.listRunnables(),
+            listLocalWorkflows: () => listLocalWorkflows(process.cwd()),
+            renderEvent: (event) => emit({ type: event.type, ...event.data }),
+            credentials: { apiKey: anthKey, openRouterKey: orKey },
+            defaultModel: model || null,
+            cwd: process.cwd(),
+        });
+
+        clearTimeout(timer);
+        if (!outcome.dispatched) {
+            emit({ type: 'error', error: outcome.reason });
+            process.exit(1);
+        }
+        const result = outcome.result || {};
+        emit({
+            type: 'result',
+            status: result.status || (result.success === false ? 'failed' : 'completed'),
+            channel: outcome.channel,
+            output: result.output || '',
+            node_results: result.node_results || undefined,
+            duration_s: Math.round((Date.now() - startTime) / 1000),
+        });
+        process.exit(result.status === 'failed' || result.success === false ? 1 : 0);
+    }
+
+    // Scan plugins so client_agents and agent-scoped plugin tool schemas
+    // are sent to the backend.
     const pluginRegistry = new PluginRegistry().scan();
 
     // Projects are registered and indexed only when the agent requests an overview.

package/src/core/local-agent.mjs

@@ -206,6 +206,11 @@ export class LocalAgent {
         maxTurns = null,
         stagnationDetection = false,
         stagnationThreshold = 3,
+        // Additional tool schemas beyond the built-in set — e.g. plugin
+        // tools a sub-agent node declares. Execution still routes through
+        // the (scoped) toolExecutor; this only makes the schemas visible
+        // to the model.
+        extraToolSchemas = [],
     }) {
         this.apiKey = apiKey;
         this.openRouterKey = openRouterKey;
@@ -218,6 +223,7 @@ export class LocalAgent {
         this.maxTurns = maxTurns || MAX_ITERATIONS;
         this.stagnationDetection = stagnationDetection;
         this.stagnationThreshold = stagnationThreshold;
+        this.extraToolSchemas = Array.isArray(extraToolSchemas) ? extraToolSchemas : [];
         this._cancelled = false;
         this.promptCache = new PromptCache();
     }
@@ -498,7 +504,10 @@ export class LocalAgent {
     }
 
     _buildToolDefs() {
-        return TOOL_SCHEMAS;
+        if (!this.extraToolSchemas.length) return TOOL_SCHEMAS;
+        const names = new Set(TOOL_SCHEMAS.map(t => t.name));
+        const extras = this.extraToolSchemas.filter(t => t?.name && !names.has(t.name));
+        return extras.length ? [...TOOL_SCHEMAS, ...extras] : TOOL_SCHEMAS;
     }
 
     _buildSystemPrompt(context, retrievedContext = null) {

package/src/core/risk-tier.mjs

@@ -63,6 +63,7 @@ const READ_TOOLS = new Set([
   'analyze_code',
   'validate_file', 'validate_structure',
   'agents_list', 'workflow_list',
+  'bahulam_info', 'job_output',
 ]);
 
 const READ_PATH_KEYS = [

package/src/core/stream-client.mjs

@@ -190,17 +190,69 @@ export class BahulamStreamClient {
         this._bundledReady = false;
     }
 
+    _getPluginToolMap() {
+        const tools = new Map();
+        if (!this.pluginRegistry) return tools;
+        for (const tool of this.pluginRegistry.listTools?.() || []) {
+            const name = String(tool.name || '').trim();
+            if (!name || tools.has(name)) continue;
+            tools.set(name, tool);
+        }
+        return tools;
+    }
+
     /**
-     * Get plugin tool schemas for client_tools injection.
-     * @returns {Array<{name: string, description: string, input_schema: object}>}
+     * Plugin tools are intentionally not advertised as primary client_tools.
+     * They are executable by the local callback handler, but the primary model
+     * should reach them by delegating to an agent that declares them.
      */
     _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: {} },
-        }));
+        return [];
+    }
+
+    _collectAgentScopedToolRefs(context = {}, clientAgents = []) {
+        const refs = new Map();
+        const pluginTools = this._getPluginToolMap();
+        const addAgent = (agent = {}) => {
+            const slug = String(agent.slug || agent.command || agent.name || '').trim();
+            const tools = Array.isArray(agent.tools) ? agent.tools : [];
+            for (const toolName of tools) {
+                const name = String(toolName || '').trim();
+                if (!name || !pluginTools.has(name)) continue;
+                if (!refs.has(name)) refs.set(name, new Set());
+                if (slug) refs.get(name).add(slug);
+            }
+        };
+
+        for (const agent of clientAgents || []) addAgent(agent);
+        for (const agent of context?.agent_ctx?.available_agents || []) addAgent(agent);
+        for (const agent of context?.available_agents || []) addAgent(agent);
+        if (context?.sub_agent) addAgent(context.sub_agent);
+        return refs;
+    }
+
+    /**
+     * Plugin tool schemas scoped to sub-agents that declare those tools.
+     * This keeps plugin tools out of the primary model's direct tool surface
+     * while still giving delegated/custom/plugin agents the schemas they need.
+     *
+     * @returns {Array<{name: string, description: string, input_schema: object, source_scope: string, plugin_name: string|null, allowed_agents: string[]}>}
+     */
+    _getClientAgentToolSchemas(context = {}, clientAgents = []) {
+        const pluginTools = this._getPluginToolMap();
+        if (!pluginTools.size) return [];
+        const refs = this._collectAgentScopedToolRefs(context, clientAgents);
+        return [...refs.entries()].map(([name, allowedAgents]) => {
+            const tool = pluginTools.get(name) || {};
+            return {
+                name,
+                description: tool.description || '',
+                input_schema: tool.input_schema || { type: 'object', properties: {} },
+                source_scope: 'plugin',
+                plugin_name: tool._plugin_name || tool.plugin_name || null,
+                allowed_agents: [...allowedAgents],
+            };
+        });
     }
 
     /**
@@ -209,13 +261,30 @@ export class BahulamStreamClient {
      */
     _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 : [],
-        }));
+        // Only plugin agents admitted to the main-loop registry (settings
+        // plugins.agent_allowlist, or the session plugin in workspace-channel
+        // executors) are advertised. Workspace-scoped plugin agents stay out
+        // of the main-turn payload; without an executor registry, fall back
+        // to advertising everything (legacy behavior).
+        const runnables = this.toolExecutor?.listRunnables?.();
+        const admitted = Array.isArray(runnables)
+            ? new Set(runnables.filter(a => a.source_scope === 'plugin').map(a => a.slug))
+            : null;
+        return this.pluginRegistry.listAgents()
+            .filter(a => !admitted || admitted.has(a.slug || a.name || ''))
+            .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 : [],
+                system_prompt: a.system_prompt || a.systemPrompt || a.prompt || '',
+                model: a.model || null,
+                models: a.models || null,
+                source: a.source || (a._plugin_name ? `plugin:${a._plugin_name}` : 'plugin'),
+                source_scope: 'plugin',
+                plugin_name: a._plugin_name || null,
+            }));
     }
 
     /**
@@ -297,6 +366,8 @@ export class BahulamStreamClient {
         if (clientTools.length > 0) body.client_tools = clientTools;
         const clientAgents = this._getPluginAgentSchemas();
         if (clientAgents.length > 0) body.client_agents = clientAgents;
+        const clientAgentTools = this._getClientAgentToolSchemas(context, clientAgents);
+        if (clientAgentTools.length > 0) body.client_agent_tools = clientAgentTools;
         const requestId = `cli-${_uuidLike()}`;
 
         // daemon cache-guard hook. If BAHULAM_CAPTURE_REQUEST is set to a file
@@ -795,6 +866,7 @@ export class BahulamStreamClient {
         const callId = call_id || request_id;
         const toolName = tool;
         const isInternal = Boolean(data?.internal || data?.sub_agent);
+        const subAgentRunId = data?.run_id || data?.sub_agent_run_id || null;
 
         if (this.verbose) {
             process.stderr.write(`\x1b[2m[tool] ${toolName}(${JSON.stringify(args).slice(0, 80)}...)\x1b[0m\n`);
@@ -812,6 +884,8 @@ export class BahulamStreamClient {
                     _cancelled: true,
                     internal: isInternal,
                     sub_agent: data?.sub_agent || null,
+                    run_id: subAgentRunId,
+                    sub_agent_run_id: subAgentRunId,
                     local_callback: false,
                 },
             };
@@ -823,6 +897,10 @@ export class BahulamStreamClient {
         try {
             result = await this.toolExecutor.execute(toolName, args || {}, {
                 signal: this._toolAbort?.signal,
+                toolCallSource: 'model',
+                internal: isInternal,
+                subAgent: data?.sub_agent || null,
+                subAgentRunId,
             });
         } catch (err) {
             if (err?.name === 'AbortError' || this._cancelled) {
@@ -862,6 +940,8 @@ export class BahulamStreamClient {
                 duration_ms: durationMs,
                 internal: isInternal,
                 sub_agent: data?.sub_agent || null,
+                run_id: subAgentRunId,
+                sub_agent_run_id: subAgentRunId,
                 local_callback: true,
             },
         };