@semalt-ai/code 1.8.5 → 1.19.0

package/lib/subagents.js

@@ -0,0 +1,516 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Subagents — isolated child agent loops (Task 3.6)
+// ---------------------------------------------------------------------------
+//
+// A subagent is a SECOND agent loop run with its OWN isolated message history.
+// It exists to keep the parent's context clean: noisy work (research, reading
+// large files, review) happens in the child, and ONLY the child's final result
+// returns to the parent. The parent never absorbs the child's intermediate
+// turns.
+//
+// This builds directly on the runAgentLoop factory (lib/agent.js): a child
+// runner is just another createAgentRunner instance, wired with WRAPPED
+// executors that enforce the child's allowed-tool set, and sharing the parent's
+// permission manager (no privilege escalation).
+//
+// Security model (load-bearing, per Phase 0):
+//   * No privilege escalation — the child uses the SAME permissionManager as
+//     the parent, so it can never auto-approve anything the parent wouldn't.
+//   * Tool constraint — a child's tools are restricted to its allowed set (from
+//     a `.semalt/agents/<name>.md` definition or an inline `tools` list). The
+//     wrapped agentExecShell/agentExecFile HARD-REFUSE anything outside the set,
+//     which is the enforcement that holds for BOTH the XML and native paths.
+//   * No recursion — a child can never invoke `spawn_agent` itself.
+//   * Untrusted result — a subagent's returned text may include external data it
+//     read, so the parent fences it in the UNTRUSTED_EXTERNAL_CONTENT delimiter
+//     (lib/agent.js), exactly like http_get / MCP / hook output.
+//
+// Custom agent definitions live at `.semalt/agents/<name>.md` (project) and
+// `~/.semalt-ai/agents/<name>.md` (global) with optional frontmatter
+// (name / model / tools / description) and a Markdown body = the child's system
+// prompt. Discovery mirrors skills (Task 3.5) and custom commands (Task 3.1).
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { TOOL_REGISTRY } = require('./tool_registry');
+
+const DEFAULT_MAX_CONCURRENCY = 3;
+const DEFAULT_MAX_ITERATIONS = 12;
+const SPAWN_AGENT_TOOL = 'spawn_agent';
+
+// ── Agent-definition discovery ─────────────────────────────────────────────
+
+// Split a frontmatter list value: `read_file, grep shell` or `[a, b]` → [a,b].
+function _splitList(val) {
+  if (Array.isArray(val)) return val.map((v) => String(v).trim()).filter(Boolean);
+  if (typeof val !== 'string') return [];
+  const s = val.trim().replace(/^\[|\]$/g, '');
+  return s.split(/[\s,]+/).map((x) => x.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+
+// Turn a name into a slash/command-safe slug (lowercase, hyphenated). Mirrors
+// the skills slugifier so `Code Reviewer` → `code-reviewer`.
+function _slugify(s) {
+  return String(s || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+// Parse optional `---`-delimited frontmatter at the top of an agent definition.
+// Recognized keys: name, model, tools (a.k.a. allowed-tools), description. The
+// body is the child's system prompt. Pure. With no frontmatter the whole text
+// is the body.
+function parseAgentFrontmatter(text) {
+  const meta = { name: '', model: '', description: '', tools: [] };
+  if (typeof text !== 'string') return { meta, body: '' };
+  const src = text.replace(/^/, '').replace(/\r\n/g, '\n');
+  const m = /^---\n([\s\S]*?)\n---[ \t]*\n?/.exec(src);
+  if (!m) return { meta, body: src };
+  const body = src.slice(m[0].length);
+  for (const rawLine of m[1].split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx < 0) continue;
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const val = line.slice(idx + 1).trim().replace(/^['"]|['"]$/g, '');
+    if (key === 'name') meta.name = val;
+    else if (key === 'model') meta.model = val;
+    else if (key === 'description') meta.description = val;
+    else if (key === 'tools' || key === 'allowed-tools' || key === 'allowed_tools') meta.tools = _splitList(val);
+  }
+  return { meta, body };
+}
+
+// Walk up from startDir for the nearest `.semalt/agents` directory, bounded by
+// the repo root (the directory holding `.git` is the last one checked). Mirrors
+// findProjectSkillsDir (Task 3.5). Returns the directory path or null.
+function findProjectAgentsDir(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(dir, '.semalt', 'agents');
+    try { if (fs.statSync(candidate).isDirectory()) return candidate; } catch {}
+    let atRepoRoot = false;
+    try { atRepoRoot = fs.existsSync(path.join(dir, '.git')); } catch {}
+    if (atRepoRoot) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// Read every `<name>.md` agent definition under `dir` into a def list, sorted by
+// filename for deterministic order. Unreadable files are skipped.
+function loadAgentDefsFromDir(dir, source) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return out; }
+  for (const entry of entries.slice().sort()) {
+    if (!/\.md$/i.test(entry)) continue;
+    const file = path.join(dir, entry);
+    let raw;
+    try {
+      if (!fs.statSync(file).isFile()) continue;
+      raw = fs.readFileSync(file, 'utf8');
+    } catch { continue; }
+    const { meta, body } = parseAgentFrontmatter(raw);
+    const base = entry.replace(/\.md$/i, '');
+    const slug = _slugify(meta.name || base);
+    if (!slug) continue;
+    out.push({
+      name: meta.name || base,
+      slug,
+      model: meta.model || '',
+      tools: meta.tools || [],
+      description: meta.description || '',
+      systemPrompt: (body || '').trim(),
+      source,
+      file,
+    });
+  }
+  return out;
+}
+
+// Discover agent definitions for a (home, cwd). Global defs load first, then the
+// nearest project defs; on a slug collision project wins. home/cwd injectable.
+function discoverAgentDefs(opts = {}) {
+  const home = opts.home || os.homedir();
+  const cwd = opts.cwd || process.cwd();
+  const global = loadAgentDefsFromDir(path.join(home, '.semalt-ai', 'agents'), 'global');
+  const projectDir = findProjectAgentsDir(cwd);
+  const project = projectDir ? loadAgentDefsFromDir(projectDir, 'project') : [];
+  const bySlug = new Map();
+  for (const d of project) if (!bySlug.has(d.slug)) bySlug.set(d.slug, d);
+  for (const d of global) if (!bySlug.has(d.slug)) bySlug.set(d.slug, d);
+  return Array.from(bySlug.values());
+}
+
+// ── Allowed-tool resolution ────────────────────────────────────────────────
+
+// identifier (tag / specName / canonical action) → canonical action, built once
+// from the static registry so a def listing `read_file` or `grep` resolves to
+// the action tuple[0] the loop dispatches on.
+let _idMap = null;
+function _identifierMap() {
+  if (_idMap) return _idMap;
+  _idMap = new Map();
+  for (const e of TOOL_REGISTRY) {
+    const ids = new Set([e.tool, ...(e.specNames || []), ...(e.tags || [])]);
+    for (const id of ids) _idMap.set(String(id).toLowerCase(), e.tool);
+  }
+  return _idMap;
+}
+
+// Resolve a list of tool identifiers to a Set of canonical actions the child may
+// run. `null`/empty → null, meaning "inherit all of the parent's tools" (still
+// bounded by the shared permission manager). `*`/`all` also means inherit-all.
+// `spawn_agent` is always dropped (no recursion). Unknown names are kept verbatim
+// so dynamic/MCP tool names still pass through.
+function resolveAllowedActions(list) {
+  if (!list || !list.length) return null;
+  const map = _identifierMap();
+  const set = new Set();
+  for (const name of list) {
+    const key = String(name || '').toLowerCase().trim();
+    if (!key) continue;
+    if (key === '*' || key === 'all') return null;
+    if (key === SPAWN_AGENT_TOOL) continue;
+    set.add(map.get(key) || key);
+  }
+  return set;
+}
+
+// ── Result formatting ──────────────────────────────────────────────────────
+
+function _lastAssistantText(messages) {
+  if (!Array.isArray(messages)) return '';
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (m && m.role === 'assistant' && typeof m.content === 'string' && m.content.trim()) {
+      return m.content.trim();
+    }
+  }
+  return '';
+}
+
+function _formatResults(results, parallel) {
+  if (!results.length) return '(no subagents were run)';
+  if (results.length === 1 && !parallel) {
+    const r = results[0];
+    return r.error ? `Subagent failed: ${r.error}` : (r.output || '(subagent produced no output)');
+  }
+  return results.map((r, i) => {
+    const head = `--- Subagent ${i + 1}${r.label ? ` (${r.label})` : ''} ---`;
+    const bodyText = r.error ? `failed: ${r.error}` : (r.output || '(no output)');
+    return `${head}\n${bodyText}`;
+  }).join('\n\n');
+}
+
+// ── Manager ────────────────────────────────────────────────────────────────
+
+// Build the subagent manager. `deps` carries the same collaborators the agent
+// runner needs (chatStream / extractToolCalls / agentExecShell / agentExecFile /
+// describePermission / permissionManager / ui / getConfig) so it can construct a
+// constrained CHILD runner per spawn. `agentDefs` are the discovered custom
+// definitions. `createRunner` and `runChild` are injectable seams for tests.
+function createSubagentManager(deps = {}) {
+  const {
+    chatStream,
+    extractToolCalls,
+    agentExecShell,
+    agentExecFile,
+    describePermission,
+    permissionManager,
+    ui,
+    getConfig,
+    agentDefs = [],
+    maxConcurrency = DEFAULT_MAX_CONCURRENCY,
+    maxIterations = DEFAULT_MAX_ITERATIONS,
+    createRunner = null,
+    runChild = null,
+  } = deps;
+
+  const _concurrency = Math.max(1, parseInt(maxConcurrency, 10) || DEFAULT_MAX_CONCURRENCY);
+
+  const _defsBySlug = new Map();
+  for (const d of agentDefs) if (d && d.slug && !_defsBySlug.has(d.slug)) _defsBySlug.set(d.slug, d);
+
+  function _resolveRunner() {
+    if (typeof createRunner === 'function') return createRunner;
+    // Lazy require to avoid a load-time cycle (agent.js does not require this).
+    return require('./agent').createAgentRunner;
+  }
+
+  // Normalize a raw spawn spec (string prompt or an object) into a concrete
+  // child-run plan: prompt, model, system prompt, allowed-action set, label.
+  function resolveSpec(raw) {
+    let r = raw;
+    if (typeof raw === 'string') r = { prompt: raw };
+    r = (r && typeof r === 'object') ? r : {};
+
+    const prompt = String(r.prompt != null ? r.prompt : (r.task != null ? r.task : '')).trim();
+    const agentName = r.agent || r.agent_type || r.name || '';
+    const def = agentName ? (_defsBySlug.get(_slugify(agentName)) || null) : null;
+
+    const cfg = (getConfig ? getConfig() : {}) || {};
+    const model = r.model || (def && def.model) || cfg.default_model || 'default';
+
+    const sysOverride = r.system_prompt || r.systemPrompt || (def && def.systemPrompt) || null;
+
+    let toolList = null;
+    if (Array.isArray(r.tools)) toolList = r.tools;
+    else if (typeof r.tools === 'string') toolList = _splitList(r.tools);
+    else if (def && def.tools && def.tools.length) toolList = def.tools;
+    const allowedActions = resolveAllowedActions(toolList);
+
+    const label = r.label || (def && def.name) || agentName || 'subagent';
+    const iters = Number.isInteger(r.max_iterations) && r.max_iterations > 0 ? r.max_iterations : maxIterations;
+
+    return {
+      prompt,
+      agentName: def ? def.name : (agentName || ''),
+      model,
+      systemPrompt: sysOverride ? String(sysOverride) : null,
+      allowedActions,
+      label,
+      maxIterations: iters,
+      def,
+    };
+  }
+
+  // Build a CHILD agent runner whose executors enforce `allowedActions` and can
+  // never spawn further subagents, sharing the parent's permission manager.
+  function _buildChildRunner(allowedActions) {
+    // Tool constraint is enforced at the EXECUTOR (not by filtering parse
+    // output): a hard refusal here holds for BOTH the XML and native paths, and
+    // gives the child feedback so it can adapt to an allowed tool instead of
+    // silently ending.
+    const isAllowed = (action) => {
+      if (action === SPAWN_AGENT_TOOL) return false; // no recursion, ever
+      if (!allowedActions) return true;              // inherit-all (still permission-bounded)
+      return allowedActions.has(action);
+    };
+
+    const childExecShell = (command, options) => {
+      if (!isAllowed('shell')) {
+        return Promise.resolve({ exit_code: -1, stdout: '', stderr: 'shell is not permitted for this subagent', blocked: true });
+      }
+      return agentExecShell(command, options);
+    };
+
+    const childExecFile = (action, ...rest) => {
+      if (!isAllowed(action)) {
+        return Promise.resolve({ error: `tool "${action}" is not permitted for this subagent` });
+      }
+      return agentExecFile(action, ...rest);
+    };
+
+    // Lifecycle hooks are about the USER turn, not internal sub-loops — give the
+    // child a no-op runner so Stop/UserPromptSubmit don't double-fire.
+    const noopHooks = { run: async () => ({ feedback: [], blocked: false, blockReason: '' }) };
+
+    const create = _resolveRunner();
+    return create({
+      chatStream,
+      extractToolCalls,
+      agentExecShell: childExecShell,
+      agentExecFile: childExecFile,
+      describePermission,
+      permissionManager,
+      ui,
+      getConfig,
+      hooks: noopHooks,
+    });
+  }
+
+  // Run one subagent through a fresh, isolated message history and return only
+  // its final assistant text.
+  async function _defaultRunChild(spec, opts = {}) {
+    const runner = _buildChildRunner(spec.allowedActions);
+    const childMessages = [{ role: 'user', content: spec.prompt || '(no task provided)' }];
+    const signal = opts.signal || null;
+    const result = await runner.runAgentLoop(childMessages, spec.model, spec.maxIterations, null, {
+      // A bare onError keeps any warning/abort path from calling array methods
+      // (messages.sysWarn) that only exist on the chat's message wrapper.
+      callbacks: { onError: () => {} },
+      systemPrompt: spec.systemPrompt, // null → child uses the default system prompt
+      getAbortFlag: signal ? () => signal.aborted : null,
+      // Self-verification (Task 4.2) is a TOP-LEVEL gate on the user's task. A
+      // child declaring its sub-task done must not trigger the configured verify
+      // command — that belongs to the parent's final "done", not each subagent.
+      noVerify: true,
+    });
+    return _lastAssistantText(result && result.messages ? result.messages : childMessages);
+  }
+
+  async function runOne(raw, opts = {}) {
+    const spec = resolveSpec(raw);
+    const exec = typeof runChild === 'function' ? runChild : _defaultRunChild;
+    let output = '';
+    let error = null;
+    try {
+      output = await exec(spec, opts);
+    } catch (err) {
+      error = err && err.message ? err.message : String(err);
+    }
+    return { label: spec.label, agent: spec.agentName || '', model: spec.model, output: output || '', error };
+  }
+
+  // Run many subagents with bounded concurrency (a fixed-size worker pool).
+  async function runMany(rawSpecs, opts = {}) {
+    const specs = Array.isArray(rawSpecs) ? rawSpecs : [rawSpecs];
+    if (!specs.length) return [];
+    const limit = Math.max(1, Math.min(_concurrency, specs.length));
+    const results = new Array(specs.length);
+    let next = 0;
+    async function worker() {
+      while (true) {
+        const i = next++;
+        if (i >= specs.length) return;
+        results[i] = await runOne(specs[i], opts);
+      }
+    }
+    const workers = [];
+    for (let i = 0; i < limit; i++) workers.push(worker());
+    await Promise.all(workers);
+    return results;
+  }
+
+  // Tool entry point. Accepts a single spec or a `{ tasks: [...] }` / array form
+  // for bounded-parallel execution. Returns the subagent envelope the agent loop
+  // fences as untrusted.
+  async function spawn(params, opts = {}) {
+    let specs;
+    let parallel = false;
+    if (params && Array.isArray(params.tasks) && params.tasks.length) {
+      specs = params.tasks;
+      parallel = true;
+    } else if (Array.isArray(params)) {
+      specs = params;
+      parallel = true;
+    } else {
+      specs = [params];
+    }
+    const results = await runMany(specs, opts);
+    return { subagent: true, content: _formatResults(results, parallel), count: results.length, results };
+  }
+
+  return {
+    spawn,
+    runOne,
+    runMany,
+    resolveSpec,
+    listAgents: () => agentDefs.slice(),
+    permissionManager, // exposed so callers/tests can confirm no new manager was built
+    maxConcurrency: _concurrency,
+  };
+}
+
+// ── spawn_agent dynamic tool entry ─────────────────────────────────────────
+
+function _parseSpawnXml(text, name) {
+  const out = [];
+  const re = new RegExp(`<${name}\\b([^>]*?)(?:\\/>|>([\\s\\S]*?)<\\/${name}>)`, 'g');
+  for (const m of text.matchAll(re)) {
+    const attrStr = m[1] || '';
+    const body = m[2] != null ? m[2] : '';
+    const attr = (k) => {
+      const mm = attrStr.match(new RegExp(`${k}="([^"]*)"`)) || attrStr.match(new RegExp(`${k}='([^']*)'`));
+      return mm ? mm[1] : null;
+    };
+    const trimmed = body.trim();
+    let params = {};
+    if (trimmed.startsWith('{')) {
+      try { params = JSON.parse(trimmed); } catch { params = { prompt: trimmed }; }
+    } else if (trimmed) {
+      params = { prompt: trimmed };
+    }
+    const agent = attr('agent') || attr('name');
+    const model = attr('model');
+    if (agent && !params.agent) params.agent = agent;
+    if (model && !params.model) params.model = model;
+    out.push([name, params]);
+  }
+  return out;
+}
+
+// Build the dynamic tool-registry entry for `spawn_agent`. Same shape as a
+// static / MCP entry so it dispatches through the SAME agent loop. Registered at
+// startup via lib/tool_registry.registerDynamicTool — kept out of the static
+// parity check (lib/constants.js) like all dynamic tools.
+function buildSpawnAgentEntry(manager) {
+  const name = SPAWN_AGENT_TOOL;
+  return {
+    tool: name,
+    subagent: true,
+    spec: {
+      description:
+        'Launch a subagent with its OWN isolated context to handle a focused, ' +
+        'noisy task (research, reading large files, review) and return ONLY its ' +
+        'final result, keeping your context clean. Optionally pass `agent` to use ' +
+        'a named definition from .semalt/agents, `model` to override the model, or ' +
+        '`tasks` (an array of task objects) to run several independent subagents ' +
+        'in parallel with bounded concurrency.',
+      parameters: {
+        type: 'object',
+        properties: {
+          prompt: { type: 'string', description: 'The task/instructions for the subagent.' },
+          agent: { type: 'string', description: 'Optional named agent definition (.semalt/agents/<name>.md).' },
+          model: { type: 'string', description: 'Optional model override for the subagent.' },
+          tasks: {
+            type: 'array',
+            description: 'Optional independent subagent tasks to run in parallel. Each item is an object with the same fields as a single call.',
+            items: {
+              type: 'object',
+              properties: {
+                prompt: { type: 'string' },
+                agent: { type: 'string' },
+                model: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+    },
+    fromParams: (p) => [name, (p && typeof p === 'object') ? p : {}],
+    parseXml: (text) => _parseSpawnXml(text, name),
+    // Spawning a subagent runs a whole tool-use loop, so it REQUIRES approval by
+    // default — its tag is in no --allow-* tier, so a tier flag can never
+    // auto-launch one. The child's own tool calls are then gated by the SAME
+    // permission manager (no privilege escalation).
+    permission: (_ctx, args) => {
+      const p = (args && args[0]) || {};
+      const label = p.agent
+        ? `agent "${p.agent}"`
+        : (Array.isArray(p.tasks) ? `${p.tasks.length} parallel subagent(s)` : 'subagent');
+      return { actionType: 'agent', description: `Spawn ${label}`, tag: name };
+    },
+    execute: async (_ctx, args, options) => {
+      const params = (args && args[0]) || {};
+      const signal = (options && options.signal) || null;
+      return manager.spawn(params, { signal });
+    },
+  };
+}
+
+module.exports = {
+  DEFAULT_MAX_CONCURRENCY,
+  DEFAULT_MAX_ITERATIONS,
+  SPAWN_AGENT_TOOL,
+  parseAgentFrontmatter,
+  findProjectAgentsDir,
+  loadAgentDefsFromDir,
+  discoverAgentDefs,
+  resolveAllowedActions,
+  createSubagentManager,
+  buildSpawnAgentEntry,
+};