@bahulam/code 0.1.10 → 0.1.12

package/src/orchestration/completion-triggers.mjs

@@ -0,0 +1,40 @@
+import { backgroundTasks } from '../core/background-tasks.mjs';
+import { dispatch } from './dispatch.mjs';
+
+/**
+ * Wake-on-finish: a background job that declared on_complete fires a
+ * TriggerEvent through dispatch() when it exits — so a finished build can
+ * deterministically wake a verifier agent. Chain depth and cycle guards
+ * apply like any other trigger; a job started BY that agent whose own
+ * on_complete points back would be refused by the chain guard.
+ *
+ * buildCtx is called lazily at fire time so the dispatch context always
+ * reflects the live tool executor / registry.
+ */
+export function registerJobCompletionDispatch(buildCtx) {
+  return backgroundTasks.onExit((job) => {
+    const target = job?.on_complete?.target;
+    if (!target) return;
+    const instruction = job.on_complete.instruction
+      || `Background job ${job.id} (${job.name}) finished: ${job.status}`
+        + (job.exit_code != null ? ` (exit ${job.exit_code})` : '')
+        + `. Review the output and act on it:\n${String(job.tail || '').slice(-4000)}`;
+    Promise.resolve()
+      .then(() => dispatch({
+        type: 'invoke',
+        source: `job:${job.id}`,
+        target,
+        params: { instruction },
+        channel: null,
+        initiator: { chain: [`job:${job.id}`] },
+      }, buildCtx()))
+      .then((outcome) => {
+        if (outcome && !outcome.dispatched) {
+          process.stderr.write(`  on_complete for ${job.id} not dispatched: ${outcome.reason}\n`);
+        }
+      })
+      .catch((err) => {
+        process.stderr.write(`  on_complete for ${job.id} failed: ${err?.message || err}\n`);
+      });
+  });
+}

package/src/orchestration/dispatch.mjs

@@ -0,0 +1,118 @@
+import { runGraph } from './runner.mjs';
+import { compileSingleAgentGraph, normalizeGraphSpec } from './graph.mjs';
+
+const MAX_CHAIN_DEPTH = 3;
+
+/**
+ * The single funnel for deterministic runs. Every surface (CLI, /run,
+ * headless, hooks, cron, daemon, programmatic) builds a TriggerEvent and
+ * calls dispatch(); nothing else calls runGraph() directly.
+ *
+ * TriggerEvent: {
+ *   type: 'invoke'|'manual'|'hook'|'prompt_match'|'cron'|'remote',
+ *   source: string,                     // e.g. 'cli:agent-run', 'hook:Stop'
+ *   target: {kind:'agent'|'workflow', slug} | string,  // bare names resolved below
+ *   params: { instruction, ... },
+ *   channel: 'local'|'server'|null,     // null → derived from the target
+ *   initiator: { chain: string[] } | null,
+ * }
+ */
+export async function dispatch(event, ctx) {
+  const chain = event.initiator?.chain || [];
+  if (chain.length >= MAX_CHAIN_DEPTH) {
+    return { dispatched: false, reason: `Trigger chain depth limit (${MAX_CHAIN_DEPTH}) reached` };
+  }
+
+  const resolved = resolveTarget(event.target, ctx);
+  if (!resolved) {
+    return { dispatched: false, reason: `Unknown target '${targetName(event.target)}'` };
+  }
+  if (chain.includes(resolved.key)) {
+    return { dispatched: false, reason: `Trigger cycle detected at '${resolved.key}'` };
+  }
+
+  const channel = event.channel || resolved.channel;
+  if (channel === 'server') {
+    // Synced server workflows keep their exact existing execution path.
+    const result = await ctx.toolExecutor.execute('workflow_run_multi', {
+      name: resolved.slug,
+      instruction: event.params?.instruction || '',
+    });
+    return { dispatched: true, channel, result };
+  }
+
+  const graph = resolved.kind === 'agent'
+    ? compileSingleAgentGraph(resolved.agent, { instruction: event.params?.instruction || '' })
+    : resolved.graph;
+
+  const runCtx = { ...ctx, resolveAgent: slug => resolveAgentBySlug(slug, ctx) };
+  const iterator = runGraph(graph, { instruction: event.params?.instruction || '', params: event.params || {} }, runCtx, {
+    substrate: event.substrate,
+    signal: event.signal,
+  });
+
+  let result = null;
+  while (true) {
+    const { value, done } = await iterator.next();
+    if (done) { result = value; break; }
+    ctx.renderEvent?.(value);
+  }
+  return { dispatched: true, channel: 'local', result };
+}
+
+function targetName(target) {
+  return typeof target === 'string' ? target : `${target?.kind}:${target?.slug}`;
+}
+
+function resolveAgentBySlug(slug, ctx) {
+  return (ctx.listRunnables?.() || []).find(agent => agent.slug === slug) || null;
+}
+
+/**
+ * Bare-name resolution order (uniform across surfaces, preserves today's
+ * /run behavior): project agent → global agent → builtin → allowlisted
+ * plugin agent → local workflow → synced server workflow fallback.
+ * listRunnables() already returns agents deduped in that precedence.
+ */
+function resolveTarget(target, ctx) {
+  const raw = typeof target === 'string' ? String(target || '').trim() : '';
+  const prefixed = raw.match(/^(agent|workflow):(.+)$/);
+  const typed = typeof target === 'object' && target?.kind
+    ? target
+    : prefixed
+      ? { kind: prefixed[1], slug: prefixed[2].trim() }
+      : null;
+  const name = typed ? typed.slug : raw;
+  if (!name) return null;
+
+  if (typed?.kind === 'agent' && typed.agent) {
+    // Caller already resolved the full definition (prompt, readOnly, tools).
+    return { kind: 'agent', slug: name, key: `agent:${name}`, agent: typed.agent, channel: 'local' };
+  }
+  if (!typed || typed.kind === 'agent') {
+    const agent = resolveAgentBySlug(name, ctx);
+    if (agent) return { kind: 'agent', slug: name, key: `agent:${name}`, agent, channel: 'local' };
+    if (typed) return null;
+  }
+
+  const workflows = ctx.listLocalWorkflows?.() || [];
+  const workflow = workflows.find(w => w.slug === name || w.name === name);
+  if (workflow) {
+    // Channel comes from the file: v2 files run locally; v1 files (no
+    // apiVersion) keep today's server execution so nothing silently flips.
+    const isV2 = /\/2$/.test(String(workflow.api_version || workflow.apiVersion || ''));
+    return {
+      kind: 'workflow',
+      slug: workflow.slug || name,
+      key: `workflow:${name}`,
+      graph: isV2 ? normalizeGraphSpec(workflow) : null,
+      channel: isV2 ? 'local' : 'server',
+    };
+  }
+
+  if (!typed || typed.kind === 'workflow') {
+    // Name may exist only as a synced server workflow — let the server path try.
+    return { kind: 'workflow', slug: name, key: `workflow:${name}`, graph: null, channel: 'server' };
+  }
+  return null;
+}

package/src/orchestration/events.mjs

@@ -0,0 +1,19 @@
+/**
+ * Tag every event from a node's execution with graph/node attribution so
+ * renderers group them as sub-agent work and history builders exclude
+ * them from the primary transcript (same treatment direct agent runs get).
+ */
+export async function* namespaceNodeEvents(iterable, { node, runId }) {
+  const slug = node.agent_slug || node.id;
+  for await (const event of iterable) {
+    const data = event.data && typeof event.data === 'object' ? event.data : {};
+    yield {
+      ...event,
+      data: { ...data, internal: true, sub_agent: slug, graph_run_id: runId, node_id: node.id },
+    };
+  }
+}
+
+export function graphEvent(type, runId, data = {}) {
+  return { type, data: { graph_run_id: runId, ...data } };
+}

package/src/orchestration/graph.mjs

@@ -0,0 +1,126 @@
+/**
+ * GraphSpec — the one shape every runnable compiles to.
+ *
+ * A deterministic sub-agent run is a one-node graph (trigger → agent →
+ * output); a multi-agent workflow is the same graph with N agent nodes.
+ * Inputs accepted: an inline GraphSpec, a multi-workflow loader payload
+ * ({ graph: { nodes, edges } }), or a single agent definition via
+ * compileSingleAgentGraph().
+ */
+
+export function compileSingleAgentGraph(agent, { instruction = '' } = {}) {
+  const slug = agent.slug || agent.name;
+  return {
+    name: slug,
+    channel: 'local',
+    pattern: 'sequential',
+    nodes: [
+      { id: 'trigger', type: 'trigger' },
+      { id: slug, type: 'agent', agent_slug: slug, agent, prompt: instruction },
+      { id: 'output', type: 'output' },
+    ],
+    edges: [
+      { source: 'trigger', target: slug },
+      { source: slug, target: 'output' },
+    ],
+    global_params: {},
+  };
+}
+
+export function normalizeGraphSpec(input) {
+  if (!input || typeof input !== 'object') throw new Error('Graph spec is required');
+  // Multi-workflow loader payload: { name, graph: { nodes, edges }, ... }
+  const source = input.graph && Array.isArray(input.graph.nodes) ? input.graph : input;
+  const nodes = (source.nodes || []).map(node => ({
+    id: node.id,
+    type: node.type,
+    agent_slug: node.agent_slug || node.data?.agent_slug || node.data?.user_agent_slug || null,
+    agent: node.agent || null,
+    prompt: node.prompt || node.data?.prompt || '',
+    model: normalizeModel(node.model ?? node.data?.model),
+    tools: Array.isArray(node.tools) ? node.tools : (Array.isArray(node.data?.tools) ? node.data.tools : []),
+    config: node.config || node.data?.config || {},
+    continue_on_error: Boolean(node.continue_on_error),
+    // job nodes: a process instead of an LLM
+    command: node.command || node.data?.command || null,
+    timeout_s: Number(node.timeout_s ?? node.data?.timeout_s) || null,
+    // service nodes: long-lived process (dev server); the node completes
+    // at READINESS, the process lives until the graph run ends.
+    ready: node.ready || node.data?.ready || null,
+  }));
+  const edges = (source.edges || []).map(edge => ({ source: edge.source, target: edge.target }));
+  return {
+    name: input.name || source.name || 'graph',
+    channel: input.channel || 'local',
+    pattern: input.pattern || input.orchestration_pattern || 'sequential',
+    nodes,
+    edges,
+    global_params: input.global_params || {},
+  };
+}
+
+function normalizeModel(value) {
+  const model = String(value || '').trim();
+  return !model || model === 'auto' ? null : model;
+}
+
+/**
+ * Validate the graph and return executable nodes (type 'agent' or 'job')
+ * in execution (topological) order. Throws before any LLM call on:
+ * unknown edge endpoints, cycles, unreachable nodes, agent nodes with no
+ * definition reference, or job nodes with no command.
+ */
+export function validateGraph(spec) {
+  const byId = new Map(spec.nodes.map(node => [node.id, node]));
+  for (const edge of spec.edges) {
+    if (!byId.has(edge.source)) throw new Error(`Edge references unknown node '${edge.source}'`);
+    if (!byId.has(edge.target)) throw new Error(`Edge references unknown node '${edge.target}'`);
+  }
+  const outgoing = new Map(spec.nodes.map(node => [node.id, []]));
+  const indegree = new Map(spec.nodes.map(node => [node.id, 0]));
+  for (const edge of spec.edges) {
+    outgoing.get(edge.source).push(edge.target);
+    indegree.set(edge.target, indegree.get(edge.target) + 1);
+  }
+
+  // Kahn topological sort — leftover nodes mean a cycle.
+  const queue = spec.nodes.filter(node => indegree.get(node.id) === 0).map(node => node.id);
+  const order = [];
+  while (queue.length) {
+    const id = queue.shift();
+    order.push(id);
+    for (const next of outgoing.get(id)) {
+      indegree.set(next, indegree.get(next) - 1);
+      if (indegree.get(next) === 0) queue.push(next);
+    }
+  }
+  if (order.length !== spec.nodes.length) {
+    throw new Error(`Graph '${spec.name}' contains a cycle`);
+  }
+
+  const reachable = new Set();
+  const stack = spec.nodes.filter(node => node.type === 'trigger').map(node => node.id);
+  while (stack.length) {
+    const id = stack.pop();
+    if (reachable.has(id)) continue;
+    reachable.add(id);
+    stack.push(...outgoing.get(id));
+  }
+
+  const executableNodes = order
+    .map(id => byId.get(id))
+    .filter(node => node.type === 'agent' || node.type === 'job' || node.type === 'service');
+  if (!executableNodes.length) throw new Error(`Graph '${spec.name}' has no agent, job, or service nodes`);
+  for (const node of executableNodes) {
+    if (!reachable.has(node.id)) {
+      throw new Error(`Node '${node.id}' is not reachable from the trigger`);
+    }
+    if (node.type === 'agent' && !node.agent && !node.agent_slug) {
+      throw new Error(`Agent node '${node.id}' has neither an inline agent nor an agent_slug`);
+    }
+    if ((node.type === 'job' || node.type === 'service') && !String(node.command || '').trim()) {
+      throw new Error(`${node.type === 'job' ? 'Job' : 'Service'} node '${node.id}' has no command`);
+    }
+  }
+  return executableNodes;
+}

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)) };
+}