@bahulam/code 0.1.11 → 0.1.12

package/src/orchestration/node-runner.mjs

@@ -0,0 +1,193 @@
+import { LocalAgent } from '../core/local-agent.mjs';
+import { backgroundTasks } from '../core/background-tasks.mjs';
+import { classifyShell, TIERS } from '../core/risk-tier.mjs';
+import { createScopedToolExecutor } from '../terminal/agents.mjs';
+import { namespaceNodeEvents } from './events.mjs';
+
+/**
+ * Execute one agent node. Substrates:
+ *   'direct'  — a per-node LocalAgent instance calling the model API
+ *               directly. One instance per node makes the node's resolved
+ *               model deterministic (LocalAgent fixes model at construction).
+ *   'session' — an injected adapter (ctx.sessionSubstrate) that runs the
+ *               node through the logged-in backend flow. The engine stays
+ *               terminal-agnostic; the REPL provides the adapter.
+ *
+ * Every tool call flows through a scoped executor that enforces the
+ * node's effective allowlist and tags calls internal/subAgent, so hooks,
+ * plugin-tool gating, and attribution behave exactly like direct agent
+ * runs today.
+ */
+export async function* runNode(node, agent, instruction, ctx, options = {}) {
+  if (node.type === 'job') {
+    yield* namespaceNodeEvents(runJobNode(node, ctx, options), { node, runId: options.runId });
+    return;
+  }
+  if (node.type === 'service') {
+    yield* namespaceNodeEvents(runServiceNode(node, ctx, options), { node, runId: options.runId });
+    return;
+  }
+  const effectiveAgent = withEffectiveTools(node, agent);
+  const scopedExecutor = createScopedToolExecutor(ctx.toolExecutor, effectiveAgent, {
+    projectRoot: ctx.cwd || process.cwd(),
+  });
+  const substrate = selectSubstrate(ctx, options);
+
+  if (substrate === 'session') {
+    yield* namespaceNodeEvents(
+      ctx.sessionSubstrate(effectiveAgent, node, instruction, { scopedExecutor }),
+      { node, runId: options.runId },
+    );
+    return;
+  }
+
+  const model = node.model || effectiveAgent.model || ctx.defaultModel || null;
+  const { apiKey = null, openRouterKey = null } = ctx.credentials || {};
+  if (!apiKey && !openRouterKey) {
+    throw new Error(
+      `Cannot run node '${node.id}' locally: no model API key. ` +
+      'Set ANTHROPIC_API_KEY or OPENROUTER_API_KEY, or log in and use the session substrate.',
+    );
+  }
+
+  // Plugin tools the agent declares need their schemas in the model's
+  // tool list (built-ins are hardcoded in LocalAgent; plugin schemas are
+  // dynamic). Execution still flows through the scoped executor.
+  const declaredTools = new Set(
+    (Array.isArray(effectiveAgent.tools) ? effectiveAgent.tools : []).map(String),
+  );
+  const extraToolSchemas = (ctx.toolExecutor?.listPluginToolSchemas?.() || [])
+    .filter(schema => declaredTools.has(schema.name));
+
+  const localAgent = new LocalAgent({
+    apiKey,
+    openRouterKey,
+    model,
+    toolExecutor: scopedExecutor,
+    cwd: ctx.cwd || process.cwd(),
+    systemPromptOverride: effectiveAgent.prompt || effectiveAgent.system_prompt || null,
+    maxTurns: effectiveAgent.max_iterations || null,
+    extraToolSchemas,
+  });
+  if (options.signal) options.signal.addEventListener('abort', () => localAgent.cancel?.(), { once: true });
+
+  yield* namespaceNodeEvents(localAgent.execute(instruction, {}), { node, runId: options.runId });
+}
+
+// A job node runs a process instead of an LLM. It blocks its graph edge
+// until the process exits (graph-level parallelism provides concurrency),
+// and its handoff is the exit code plus the output tail. Commands are
+// risk-classified up front — dangerous patterns fail the node
+// deterministically rather than prompting mid-graph.
+async function* runJobNode(node, ctx, options = {}) {
+  const command = String(node.command || '').trim();
+  const tier = classifyShell(command);
+  if (tier === TIERS.SHELL_DANGEROUS) {
+    throw new Error(`Job '${node.id}' blocked: command matches a high-risk pattern (${command.slice(0, 80)})`);
+  }
+
+  const started = backgroundTasks.start({
+    command,
+    cwd: ctx.cwd || process.cwd(),
+    timeoutMs: node.timeout_s ? node.timeout_s * 1000 : undefined,
+    name: node.id,
+  });
+  yield { type: 'status', data: { message: `job ${node.id}: ${command.slice(0, 80)} (${started.id})` } };
+  if (options.signal) {
+    options.signal.addEventListener('abort', () => backgroundTasks.kill(started.id), { once: true });
+  }
+
+  const done = await backgroundTasks.wait(started.id);
+  const ok = done.status === 'completed';
+  const summaryLine = `job ${node.id} ${done.status} (exit ${done.exit_code ?? 'n/a'}, ${done.duration_s}s)`;
+  const tail = String(done.tail || '').trim();
+  if (!ok) {
+    throw new Error(`${summaryLine}${tail ? `\n${tail.slice(-2000)}` : ''}`);
+  }
+  yield {
+    type: 'complete',
+    data: {
+      final_response: `${summaryLine}${tail ? `\n${tail}` : ''}`,
+      job_id: done.id,
+      exit_code: done.exit_code,
+      log_path: done.log_path,
+    },
+  };
+}
+
+// A service node starts a long-lived process (dev server) and completes
+// at READINESS, not exit — downstream nodes run against the live service.
+// The process is registered in options.serviceJobs so the graph runner
+// kills it when the run ends. Readiness: ready.port (TCP connect),
+// ready.log_pattern (regex on output tail), or ready.delay_s (default 2s).
+async function* runServiceNode(node, ctx, options = {}) {
+  const command = String(node.command || '').trim();
+  const tier = classifyShell(command);
+  if (tier === TIERS.SHELL_DANGEROUS) {
+    throw new Error(`Service '${node.id}' blocked: command matches a high-risk pattern (${command.slice(0, 80)})`);
+  }
+
+  const started = backgroundTasks.start({
+    command,
+    cwd: ctx.cwd || process.cwd(),
+    timeoutMs: 0, // services live until the graph run ends
+    name: node.id,
+  });
+  if (Array.isArray(options.serviceJobs)) options.serviceJobs.push(started.id);
+  yield { type: 'status', data: { message: `service ${node.id}: ${command.slice(0, 80)} (${started.id})` } };
+
+  const ready = node.ready || {};
+  const timeoutMs = (Number(ready.timeout_s) || 60) * 1000;
+  const deadline = Date.now() + timeoutMs;
+  const poll = async () => {
+    const job = backgroundTasks.describe(started.id);
+    if (!job || job.status !== 'running') {
+      throw new Error(`service ${node.id} exited before becoming ready (${job?.status}, exit ${job?.exit_code})\n${String(job?.tail || '').slice(-1000)}`);
+    }
+    if (ready.port) return await portOpen(Number(ready.port));
+    if (ready.log_pattern) return new RegExp(ready.log_pattern).test(job.tail || '');
+    return true; // no probe declared → ready after the initial delay
+  };
+
+  await new Promise(resolve => setTimeout(resolve, (Number(ready.delay_s) || 2) * 1000));
+  while (!(await poll())) {
+    if (Date.now() > deadline) {
+      backgroundTasks.kill(started.id);
+      throw new Error(`service ${node.id} not ready within ${timeoutMs / 1000}s`);
+    }
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  }
+
+  yield {
+    type: 'complete',
+    data: {
+      final_response: `service ${node.id} ready (${started.id}${ready.port ? `, port ${ready.port}` : ''}). It stays up for the rest of this run.`,
+      job_id: started.id,
+    },
+  };
+}
+
+async function portOpen(port) {
+  const { Socket } = await import('node:net');
+  return new Promise(resolve => {
+    const socket = new Socket();
+    const done = (ok) => { socket.destroy(); resolve(ok); };
+    socket.setTimeout(750, () => done(false));
+    socket.once('error', () => done(false));
+    socket.connect(port, '127.0.0.1', () => done(true));
+  });
+}
+
+function selectSubstrate(ctx, options) {
+  const requested = options.substrate || 'auto';
+  if (requested === 'session' || requested === 'direct') return requested;
+  return typeof ctx.sessionSubstrate === 'function' && ctx.auth?.token ? 'session' : 'direct';
+}
+
+// node.tools, when present, narrows the agent's own allowlist (intersection).
+function withEffectiveTools(node, agent) {
+  const agentTools = Array.isArray(agent.tools) ? agent.tools : [];
+  if (!Array.isArray(node.tools) || !node.tools.length) return agent;
+  const narrowed = new Set(node.tools);
+  return { ...agent, tools: agentTools.filter(tool => narrowed.has(tool)) };
+}

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

@@ -73,8 +73,8 @@ export async function createPluginToolExecutor(manifest, opts = {}) {
   const pluginName = manifest.metadata?.name || '';
 
   for (const toolDef of tools) {
-    if (!toolDef.handler) continue;
-    const handler = await loadPluginTool(pluginDir, toolDef.handler);
+    if (!toolDef.tool) continue;
+    const handler = await loadPluginTool(pluginDir, toolDef.tool);
     if (handler) {
       handlers.set(toolDef.name, { handler, toolDef });
     }

package/src/plugins/manifest.mjs

@@ -26,40 +26,40 @@ function normalizeToolNames(value) {
   }).filter(Boolean);
 }
 
-function loadAgentHandler(agentDef, pluginDir) {
-  const handler = String(agentDef.handler || agentDef.file || '').trim();
-  if (!handler || !pluginDir) return {};
+function loadAgentFile(agentDef, pluginDir) {
+  const file = String(agentDef.file || agentDef.handler || '').trim();
+  if (!file || !pluginDir) return {};
   try {
-    const handlerPath = path.resolve(pluginDir, handler);
-    const raw = fs.readFileSync(handlerPath, 'utf-8');
-    return path.extname(handlerPath).toLowerCase() === '.json'
+    const filePath = path.resolve(pluginDir, file);
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return path.extname(filePath).toLowerCase() === '.json'
       ? JSON.parse(raw)
       : parseYaml(raw);
   } catch (err) {
     if (process.env.DEBUG) {
-      console.error(`Failed to load plugin agent handler ${handler}: ${err.message}`);
+      console.error(`Failed to load plugin agent file ${file}: ${err.message}`);
     }
     return {};
   }
 }
 
 function normalizeAgentDef(agentDef, pluginName, pluginDir) {
-  const handlerConfig = loadAgentHandler(agentDef, pluginDir);
-  const metadata = handlerConfig.metadata || handlerConfig.meta || {};
-  const agent = handlerConfig.agent || handlerConfig.spec?.agent || {};
-  const handlerTools = (
-    handlerConfig.tools
-    || handlerConfig.spec?.tools
+  const fileConfig = loadAgentFile(agentDef, pluginDir);
+  const metadata = fileConfig.metadata || fileConfig.meta || {};
+  const agent = fileConfig.agent || fileConfig.spec?.agent || {};
+  const fileTools = (
+    fileConfig.tools
+    || fileConfig.spec?.tools
     || agent.tools
     || []
   );
   const inlineTools = normalizeToolNames(agentDef.tools);
 
   return {
-    slug: agentDef.slug || metadata.slug || handlerConfig.slug || metadata.name || handlerConfig.name || agentDef.name || '',
-    name: agentDef.name || metadata.name || handlerConfig.name || agentDef.slug || '',
-    description: agentDef.description || metadata.description || handlerConfig.description || '',
-    role: agentDef.role || metadata.role || handlerConfig.role || 'specialist',
+    slug: agentDef.slug || metadata.slug || fileConfig.slug || metadata.name || fileConfig.name || agentDef.name || '',
+    name: agentDef.name || metadata.name || fileConfig.name || agentDef.slug || '',
+    description: agentDef.description || metadata.description || fileConfig.description || '',
+    role: agentDef.role || metadata.role || fileConfig.role || 'specialist',
     system_prompt: (
       agentDef.system_prompt
       || agentDef.systemPrompt
@@ -67,16 +67,16 @@ function normalizeAgentDef(agentDef, pluginName, pluginDir) {
       || agent.system_prompt
       || agent.systemPrompt
       || agent.prompt
-      || handlerConfig.system_prompt
-      || handlerConfig.prompt
+      || fileConfig.system_prompt
+      || fileConfig.prompt
       || ''
     ),
-    tools: inlineTools.length ? inlineTools : normalizeToolNames(handlerTools),
-    model: agentDef.model || agent.model || handlerConfig.model || null,
-    models: agentDef.models || agent.models || handlerConfig.models || undefined,
-    max_tokens: agentDef.max_tokens || agent.max_tokens || handlerConfig.max_tokens || undefined,
-    max_iterations: agentDef.max_iterations || agent.max_iterations || handlerConfig.max_iterations || undefined,
-    handler: agentDef.handler || agentDef.file || '',
+    tools: inlineTools.length ? inlineTools : normalizeToolNames(fileTools),
+    model: agentDef.model || agent.model || fileConfig.model || null,
+    models: agentDef.models || agent.models || fileConfig.models || undefined,
+    max_tokens: agentDef.max_tokens || agent.max_tokens || fileConfig.max_tokens || undefined,
+    max_iterations: agentDef.max_iterations || agent.max_iterations || fileConfig.max_iterations || undefined,
+    file: agentDef.file || agentDef.handler || '',
     source: `plugin:${pluginName}`,
     source_scope: 'plugin',
   };
@@ -164,7 +164,7 @@ export function normalizeManifest(raw, source = '') {
       name: toolDef.name || '',
       description: toolDef.description || '',
       input_schema: toolDef.parameters || toolDef.input_schema || toolDef.inputSchema || { type: 'object', properties: {} },
-      handler: toolDef.handler || toolDef.file || '',
+      tool: toolDef.tool || toolDef.file || toolDef.handler || '',
       plugin_name: name,
     };
     if (tool.name) tools.push(tool);
@@ -277,7 +277,7 @@ export function validatePluginManifest(manifest) {
   if (manifest.spec) {
     for (const tool of (manifest.spec.tools || [])) {
       if (!tool.name) errors.push('Tool missing name');
-      if (!tool.handler) errors.push(`Tool "${tool.name || '(unnamed)'}" missing handler path`);
+      if (!tool.tool) errors.push(`Tool "${tool.name || '(unnamed)'}" missing tool module path (tool: ./tools/<name>.mjs)`);
     }
     for (const agent of (manifest.spec.agents || [])) {
       if (!agent.slug && !agent.name) errors.push('Agent missing slug or name');

package/src/plugins/preflight.mjs

@@ -117,23 +117,23 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     if (!tool.description || tool.description.length < 8) {
       warnings.push(`Tool "${t}": description is missing or very short (<8 chars) — the model uses this to decide when to call it`);
     }
-    if (!tool.handler) { errors.push(`Tool "${t}": missing handler path`); continue; }
+    if (!tool.tool) { errors.push(`Tool "${t}": missing tool module path (tool: ./tools/<name>.mjs)`); continue; }
 
-    const handlerPath = path.resolve(pluginDir, tool.handler);
+    const toolModulePath = path.resolve(pluginDir, tool.tool);
     // Traversal guard
-    const inside = handlerPath === pluginDir || handlerPath.startsWith(pluginDir + path.sep);
-    if (!inside) errors.push(`Tool "${t}": handler path escapes the plugin directory`);
-    else if (!fs.existsSync(handlerPath)) errors.push(`Tool "${t}": handler file not found: ${tool.handler}`);
+    const inside = toolModulePath === pluginDir || toolModulePath.startsWith(pluginDir + path.sep);
+    if (!inside) errors.push(`Tool "${t}": tool module path escapes the plugin directory`);
+    else if (!fs.existsSync(toolModulePath)) errors.push(`Tool "${t}": tool module not found: ${tool.tool}`);
     else {
       try {
         // Cache-bust because a previous install may have imported an older
         // copy at the same path in this process.
-        const mod = await import(`${pathToFileURL(handlerPath).href}?preflight=${Date.now()}`);
+        const mod = await import(`${pathToFileURL(toolModulePath).href}?preflight=${Date.now()}`);
         if (typeof mod.call !== 'function') {
-          errors.push(`Tool "${t}": handler ${tool.handler} does not export an async \`call\` function`);
+          errors.push(`Tool "${t}": tool module ${tool.tool} does not export an async \`call\` function`);
         }
       } catch (err) {
-        errors.push(`Tool "${t}": handler ${tool.handler} failed to import: ${err.message}`);
+        errors.push(`Tool "${t}": tool module ${tool.tool} failed to import: ${err.message}`);
       }
     }
 

package/src/terminal/agents.mjs

@@ -113,7 +113,7 @@ const TOOL_ALIASES = new Map([
   ['grep', 'search_code'],
 ]);
 
-function canonicalToolName(value) {
+export function canonicalToolName(value) {
   const key = String(value || '').trim().toLowerCase();
   return TOOL_ALIASES.get(key) || key;
 }
@@ -133,7 +133,7 @@ function normalizeScopedArgs(toolName, args = {}, { projectRoot = null } = {}) {
   return next;
 }
 
-function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } = {}) {
+export function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } = {}) {
   const tools = Array.isArray(agent.tools) ? agent.tools : [];
   const allowed = new Set(tools.map(canonicalToolName).filter(Boolean));
   if (!allowed.size) return baseExecutor;
@@ -152,7 +152,11 @@ function createScopedToolExecutor(baseExecutor, agent, { projectRoot = null } =
         baseExecutor,
         toolName,
         normalizeScopedArgs(toolName, args, { projectRoot }),
-        options,
+        {
+          ...options,
+          internal: true,
+          subAgent: agent.slug || agent.command || agent.name || true,
+        },
       );
     },
   };
@@ -317,6 +321,7 @@ export async function runAgentDefinition(agentDefinition, instruction, ctx, sess
     token: creds.token,
     toolExecutor,
     approvalManager: agentApproval,
+    pluginRegistry: options.pluginRegistry || ctx.pluginRegistry || null,
   });
 
   session.turns++;

package/src/terminal/main.mjs

@@ -306,6 +306,8 @@ async function main() {
   \x1b[1mUsage:\x1b[0m
     bahulam                        Start interactive REPL
     bahulam "instruction"          Run a single instruction
+    bahulam --agent <slug> -p "x"  Run a named agent (local deterministic graph)
+    bahulam --workflow <name> -p   Run a named workflow (local deterministic graph)
     bahulam --headless -p "x"      Non-interactive: auto-approve, JSONL output
     bahulam --headless -p "x" --vision screenshot.png
                               Attach an image via the vision analysis pipeline
@@ -360,7 +362,7 @@ async function main() {
     /architect <query>      Spawn architecture planning agent
     /agents create <name>   Create project-local user-defined agent YAML
     /agents edit <name>     Open a local agent YAML in your editor
-    /agents sync [name]     Sync all or one local agent to Supabase
+    /agents sync [name]     Optionally publish local agents to backend/account
     /attach <image-path>    Attach an image to next prompt
     /attach clipboard       Attach image copied to macOS/Windows clipboard
     /exit                   Exit the REPL
@@ -480,7 +482,9 @@ async function main() {
   const daemonSpawned = process.env.BAHULAM_DAEMON_SPAWNED === '1';
   const daemonPrompt = daemonSpawned ? (process.env.BAHULAM_DAEMON_INITIAL_PROMPT || '').trim() : '';
   const effectivePrompt = args.prompt || (daemonSpawned && daemonPrompt) || '';
-  if (effectivePrompt && (daemonSpawned || process.argv.includes('--headless') || !process.stdin.isTTY)) {
+  const hasGraphTarget = Boolean(args.agent || args.workflow);
+  if ((effectivePrompt || hasGraphTarget)
+      && (daemonSpawned || process.argv.includes('--headless') || !process.stdin.isTTY || hasGraphTarget)) {
     const { runHeadless } = await import('../core/headless.mjs');
     await runHeadless({
       instruction: effectivePrompt,
@@ -490,6 +494,8 @@ async function main() {
       cacheReport: args.cacheReport,
       local: args.local,
       vision: args.vision,
+      agent: args.agent,
+      workflow: args.workflow,
     });
     return;
   }