@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/execution/subagent-dispatcher.js

@@ -0,0 +1,721 @@
+/**
+ * Subagent Dispatcher
+ *
+ * Dispatches work to sub-agents (terminal spawning equivalent).
+ * Builds agent-specific prompts, manages dispatch lifecycle, and
+ * collects results with timeout support.
+ *
+ * Merlin Framework — Gestao Merlin v3.0.0
+ *
+ * @module core/execution/subagent-dispatcher
+ * @version 3.0.0
+ */
+
+/* global AbortController */
+const { EventEmitter } = require("events");
+const { spawn } = require("child_process");
+const crypto = require("crypto");
+const {
+  sanitizeId,
+  sanitizeContent,
+  wrapUntrustedContent,
+} = require("../alkimia/security/content-sanitizer");
+const {
+  resolveToolMask,
+  formatToolMaskInstruction,
+} = require("../orchestration/phase-tool-masks");
+const { MessageType } = require("../orchestration/session-state");
+
+/**
+ * Model shorthand → CLI model identifier map.
+ * @constant
+ */
+const MODEL_MAP = {
+  opus: "claude-opus-4-6",
+  sonnet: "claude-sonnet-4-6",
+  haiku: "claude-haiku-4-5-20251001",
+};
+
+/**
+ * Sentinel returned by `_resolveModel` for the v3.4 local Manager tier. It is
+ * deliberately NOT a `MODEL_MAP` key: a missing key would resolve to `null` and
+ * silently spawn the default Claude (the documented gotcha). The explicit
+ * sentinel routes the dispatch to the dashboard-hosted local LLM instead.
+ * @constant
+ */
+const LOCAL_MODEL = "local";
+
+/** Where the dashboard hosts the local-LLM transport (loopback). */
+const DASHBOARD_URL =
+  process.env.MERLIN_DASHBOARD_URL || "http://127.0.0.1:3939";
+
+// ---------------------------------------------------------------------------
+//  SubagentDispatcher
+// ---------------------------------------------------------------------------
+
+class SubagentDispatcher extends EventEmitter {
+  /**
+   * @param {Object} [config]
+   * @param {string}   [config.rootPath]         Project root.
+   * @param {number}   [config.defaultTimeout=300000] Default per-dispatch timeout (5 min).
+   * @param {Object}   [config.agentMapping]     Task-type-to-agent map.
+   */
+  constructor(config = {}) {
+    super();
+    this.rootPath = config.rootPath || process.cwd();
+    this.defaultTimeout = config.defaultTimeout || 300000;
+    this.agentMapping = config.agentMapping || {
+      backend: "@dev",
+      frontend: "@dev",
+      feature: "@dev",
+      test: "@qa",
+      review: "@qa",
+      deploy: "@devops",
+      architecture: "@architect",
+    };
+
+    /** Active dispatches keyed by dispatchId. */
+    this._active = new Map();
+
+    /** GuardrailEngine — full pre/post/env checks (set via config or setGuardrailEngine). */
+    this._guardrailEngine = config.guardrailEngine || null;
+
+    /** Track whether we've warned about missing guardrails (once per instance). */
+    this._guardrailWarningEmitted = false;
+
+    /** Optional ModelRouter for smart model selection. */
+    this._modelRouter = config.modelRouter || null;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Public API
+  // -----------------------------------------------------------------------
+
+  /**
+   * Dispatch a single task to an agent.
+   *
+   * @param {string} agentId - Agent identifier (e.g. "@dev").
+   * @param {Object} task    - Task descriptor (id, description, files, ...).
+   * @param {Object} [options]
+   * @param {number}  [options.timeout]       Per-dispatch timeout override.
+   * @param {string}  [options.currentPhase]  Workflow phase for tool mask resolution.
+   * @param {Object}  [options.toolMaskOverrides] Project-level tool mask overrides.
+   * @param {string}  [options.agentModel]    Model override (opus|sonnet|haiku).
+   * @param {string}  [options.mode]          Execution mode (heartbeat|cron|interactive) for cost-split routing.
+   * @returns {Promise<Object>} Dispatch result.
+   */
+  async dispatch(agentId, task, options = {}) {
+    const dispatchId = this._generateId();
+    const timeout = options.timeout || this.defaultTimeout;
+
+    // --- Guardrail: warn if absent ---
+    if (!this._guardrailEngine && !this._guardrailWarningEmitted) {
+      this._guardrailWarningEmitted = true;
+      this.emit("guardrail-missing", {
+        dispatchId,
+        message:
+          "SubagentDispatcher has no GuardrailEngine — all safety checks skipped",
+      });
+    }
+
+    // --- Guardrail: preCheck before dispatch ---
+    if (this._guardrailEngine) {
+      const preResult = this._guardrailEngine.preCheck(agentId, task);
+      if (!preResult.passed) {
+        this.emit("dispatch-blocked", {
+          dispatchId,
+          agentId,
+          taskId: task.id,
+          reason: "preCheck",
+          issues: preResult.issues,
+        });
+        return {
+          dispatchId,
+          agentId,
+          taskId: task.id,
+          success: false,
+          error: `Dispatch blocked by preCheck: ${preResult.issues.map((i) => i.message).join("; ")}`,
+          output: "",
+          duration: 0,
+          filesModified: [],
+          blocked: true,
+          issues: preResult.issues,
+        };
+      }
+
+      // --- Guardrail: environment preflight ---
+      const envResult = await this._guardrailEngine.envPreflightCheck(task);
+      if (!envResult.passed) {
+        this.emit("dispatch-blocked", {
+          dispatchId,
+          agentId,
+          taskId: task.id,
+          reason: "envPreflight",
+          issues: envResult.issues,
+        });
+        return {
+          dispatchId,
+          agentId,
+          taskId: task.id,
+          success: false,
+          error: `Dispatch blocked by envPreflight: ${envResult.issues.map((i) => i.message).join("; ")}`,
+          output: "",
+          duration: 0,
+          filesModified: [],
+          blocked: true,
+          issues: envResult.issues,
+        };
+      }
+    }
+
+    // Resolve tool mask if a workflow phase is specified
+    if (options.currentPhase && !options.toolMaskInstruction) {
+      const mask = resolveToolMask(
+        options.currentPhase,
+        options.toolMaskOverrides,
+      );
+      options.toolMaskInstruction = formatToolMaskInstruction(
+        mask,
+        options.currentPhase,
+      );
+    }
+
+    this._active.set(dispatchId, {
+      dispatchId,
+      agentId,
+      taskId: task.id,
+      status: "running",
+      startTime: Date.now(),
+      agentModel: options.agentModel || null,
+      taskComplexity: options.taskComplexity || null,
+      taskType: options.taskType || null,
+      mode: options.mode || null,
+    });
+
+    this.emit("dispatch-start", { dispatchId, agentId, taskId: task.id });
+
+    try {
+      const prompt = this._preparePrompt(agentId, task, options);
+      // H2 fix: Store startTime before dispatch (active entry deleted before use)
+      const startTime = Date.now();
+      const result = await this._waitForResult(dispatchId, prompt, timeout);
+
+      this._active.delete(dispatchId);
+      this.emit("dispatch-end", { dispatchId, success: result.success });
+
+      // Parse structured messages from output
+      const messages = this._parseMessages(result.output);
+      const askMessages = messages.filter((m) => m.type === MessageType.ASK);
+      if (askMessages.length > 0) {
+        this.emit("agent-ask", { dispatchId, agentId, questions: askMessages });
+      }
+
+      // Per-turn invariant check (Self-Correction Protocol)
+      if (this._guardrailEngine) {
+        const turnData = {
+          toolsUsed: result.filesModified.length > 0 ? ["write"] : [],
+          codeWritten: result.filesModified.length > 0,
+          testRun: /(?:test|jest|vitest|npm test)/i.test(result.output || ""),
+          statusReported: messages.some(
+            (m) =>
+              m.type === MessageType.RESULT || m.type === MessageType.PROGRESS,
+          ),
+          errorDetected: /(?:error|failed|exception)/i.test(
+            result.output || "",
+          ),
+          errorHandled: /(?:fix|retry|resolved|workaround)/i.test(
+            result.output || "",
+          ),
+        };
+        const turnResult = this._guardrailEngine.turnCheck(turnData);
+        if (!turnResult.passed) {
+          this.emit("turn-check-violation", {
+            dispatchId,
+            agentId,
+            violations: turnResult.violations,
+          });
+        }
+
+        // --- Guardrail: postCheck — success verification, secret detection, journal ---
+        const postResult = this._guardrailEngine.postCheck(
+          agentId,
+          result,
+          task,
+        );
+        if (!postResult.passed) {
+          result.success = false;
+          result.guardrailIssues = postResult.issues;
+        }
+      }
+
+      return {
+        dispatchId,
+        agentId,
+        taskId: task.id,
+        success: result.success,
+        output: result.output,
+        messages,
+        duration: Date.now() - startTime,
+        filesModified: result.filesModified || [],
+        guardrailIssues: result.guardrailIssues || [],
+        verification: result.verification || null,
+      };
+    } catch (err) {
+      this._active.delete(dispatchId);
+      this.emit("dispatch-end", {
+        dispatchId,
+        success: false,
+        error: err.message,
+      });
+
+      // --- Guardrail: record failed attempt + check escalation ---
+      if (this._guardrailEngine) {
+        this._guardrailEngine.attemptJournal.record(task.id || dispatchId, {
+          approach: task.description || task.id || "unknown",
+          error: err.message,
+          success: false,
+          context: { agentId, dispatchId },
+        });
+
+        if (
+          this._guardrailEngine.attemptJournal.mustEscalate(
+            task.id || dispatchId,
+          )
+        ) {
+          this.emit("dispatch-escalate", {
+            dispatchId,
+            agentId,
+            taskId: task.id,
+            journal: this._guardrailEngine.attemptJournal.getSummary(
+              task.id || dispatchId,
+            ),
+          });
+        }
+      }
+
+      return {
+        dispatchId,
+        agentId,
+        taskId: task.id,
+        success: false,
+        error: err.message,
+        output: "",
+        duration: 0,
+        filesModified: [],
+      };
+    }
+  }
+
+  /**
+   * Dispatch multiple tasks to their resolved agents in parallel.
+   *
+   * @param {Array<{agentId: string, task: Object}>} assignments
+   * @returns {Promise<Array<Object>>} Array of dispatch results.
+   */
+  async dispatchParallel(assignments) {
+    const promises = assignments.map(({ agentId, task, options }) =>
+      this.dispatch(agentId, task, options || {}),
+    );
+    return Promise.allSettled(promises).then((settled) =>
+      settled.map((s) =>
+        s.status === "fulfilled"
+          ? s.value
+          : { success: false, error: s.reason?.message || "Unknown error" },
+      ),
+    );
+  }
+
+  /**
+   * Get currently active dispatches.
+   *
+   * @returns {Array<Object>}
+   */
+  getActiveDispatches() {
+    return Array.from(this._active.values()).map((d) => ({
+      ...d,
+      elapsed: Date.now() - d.startTime,
+    }));
+  }
+
+  /**
+   * Attach a GuardrailEngine for per-turn invariant checking.
+   * @param {Object} engine - GuardrailEngine instance
+   */
+  setGuardrailEngine(engine) {
+    this._guardrailEngine = engine;
+  }
+
+  /**
+   * Attach a ModelRouter for smart model selection.
+   * @param {Object} router - ModelRouter instance
+   */
+  setModelRouter(router) {
+    this._modelRouter = router;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Prompt Builder
+  // -----------------------------------------------------------------------
+
+  /**
+   * Build the instruction prompt for an agent.
+   *
+   * @param {string} agentId
+   * @param {Object} task
+   * @returns {string}
+   */
+  _preparePrompt(agentId, task, options = {}) {
+    let prompt = `You are ${sanitizeId(agentId)}, a specialised agent in the Merlin framework.\n\n`;
+
+    prompt += "## Task\n";
+    prompt += `**ID:** ${sanitizeId(task.id)}\n`;
+    prompt += `**Description:** ${sanitizeContent(task.description, { maxLength: 2000 })}\n\n`;
+
+    if (task.acceptanceCriteria && task.acceptanceCriteria.length > 0) {
+      prompt += "## Acceptance Criteria\n";
+      task.acceptanceCriteria.forEach((ac, i) => {
+        prompt += `${i + 1}. ${sanitizeContent(ac, { maxLength: 500 })}\n`;
+      });
+      prompt += "\n";
+    }
+
+    if (task.files && task.files.length > 0) {
+      prompt += "## Files to Modify\n";
+      task.files.forEach((f) => {
+        prompt += `- \`${sanitizeId(f)}\`\n`;
+      });
+      prompt += "\n";
+    }
+
+    // Injected context (from ContextInjector) — treated as untrusted
+    // Stateless delegation (#43): exclude context when options.stateless = true
+    if (options.stateless) {
+      prompt += "## Context Isolation\n";
+      prompt +=
+        "You have NO access to parent session context. Work only with the task description and files provided above.\n\n";
+    } else if (task.injectedContext) {
+      prompt +=
+        wrapUntrustedContent(task.injectedContext, "context-injector") + "\n";
+    }
+
+    // Tool mask injection (phase-based access control)
+    if (options.toolMaskInstruction) {
+      prompt += options.toolMaskInstruction + "\n";
+    }
+
+    // Tool reminders from activated skills (Step 13.1)
+    if (options.toolReminders && options.toolReminders.length > 0) {
+      prompt += "## Tool Reminders\n";
+      prompt +=
+        "Before completing, verify you have followed these tool-specific rules:\n\n";
+      for (const reminder of options.toolReminders) {
+        prompt += `- ${sanitizeContent(reminder, { maxLength: 200 })}\n`;
+      }
+      prompt += "\n";
+    }
+
+    // Brevity injection (#40): adjust response length expectations
+    if (options.brevity) {
+      prompt += "## Response Brevity\n";
+      if (options.brevity === "terse") {
+        prompt += "This is a trivial task. Respond in 1 line, no preamble.\n\n";
+      } else if (options.brevity === "brief") {
+        prompt += "This is a simple task. Respond in under 100 words.\n\n";
+      }
+      // "standard" = no additional instruction
+    }
+
+    // Communication protocol
+    prompt += "## Communication Protocol\n";
+    prompt += "Use structured message tags in your output:\n";
+    prompt += "- `[NOTIFY: message]` — Status updates (non-blocking)\n";
+    prompt +=
+      "- `[ASK: question]` — Questions requiring a response (blocking)\n";
+    prompt += "- `[PROGRESS: X% description]` — Progress updates\n";
+    prompt += "- `[RESULT: summary]` — Final result summary\n";
+    prompt +=
+      "- `[THOUGHT: reasoning]` — Internal reasoning (logged, not shown to user)\n\n";
+
+    prompt += "## Instructions\n";
+    prompt += "1. Implement the task completely.\n";
+    prompt += "2. Follow existing patterns in the codebase.\n";
+    prompt += "3. Verify your changes work.\n";
+    prompt += "4. Respond with a `[RESULT: summary]` of what you did.\n";
+
+    return prompt;
+  }
+
+  // -----------------------------------------------------------------------
+  //  Result Collection
+  // -----------------------------------------------------------------------
+
+  /**
+   * Resolve the model and dispatch to the right transport.
+   *
+   * v3.4 local tier: when the router selects the `local` sentinel, the prepared
+   * prompt is sent to the dashboard-hosted local LLM over loopback HTTP. On ANY
+   * failure or timeout it falls back to the Claude spawn — the dispatcher never
+   * hard-depends on the dashboard being up.
+   *
+   * @param {string} dispatchId
+   * @param {string} prompt
+   * @param {number} timeout
+   * @returns {Promise<Object>}
+   */
+  _waitForResult(dispatchId, prompt, timeout) {
+    const model = this._resolveModel(dispatchId);
+
+    if (model === LOCAL_MODEL) {
+      return this._localComplete(prompt, timeout).catch((err) => {
+        // Resilience: a cold/absent local model must never break the dispatch.
+        this.emit("local-fallback", {
+          dispatchId,
+          error: err && err.message,
+        });
+        return this._spawnClaude(dispatchId, prompt, timeout, null);
+      });
+    }
+
+    return this._spawnClaude(dispatchId, prompt, timeout, model);
+  }
+
+  /**
+   * POST the prepared prompt to the dashboard's local-LLM endpoint and map the
+   * `{data:{text}}` response into the standard dispatch result shape. Rejects on
+   * non-2xx, empty text, or timeout (the caller falls back to Claude).
+   *
+   * @param {string} prompt
+   * @param {number} timeout
+   * @returns {Promise<Object>}
+   */
+  async _localComplete(prompt, timeout) {
+    const url = `${DASHBOARD_URL.replace(/\/+$/, "")}/api/local-llm/complete`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ prompt }),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        throw new Error(`local-llm endpoint returned HTTP ${res.status}`);
+      }
+      const json = await res.json();
+      const text =
+        json && json.data && typeof json.data.text === "string"
+          ? json.data.text
+          : "";
+      if (!text) throw new Error("local-llm endpoint returned no text");
+      return {
+        success: true,
+        output: text,
+        filesModified: this._extractFiles(text),
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Spawn a sub-process (Claude CLI) and wait for the result.
+   *
+   * @param {string} dispatchId
+   * @param {string} prompt
+   * @param {number} timeout
+   * @param {string|null} model - Resolved CLI model id, or null for the default.
+   * @returns {Promise<Object>}
+   */
+  _spawnClaude(dispatchId, prompt, timeout, model) {
+    const MAX_OUTPUT = 1024 * 512; // 512KB output limit
+
+    return new Promise((resolve, reject) => {
+      // C3 fix: Use argument array with shell: false to prevent command injection
+      // Build spawn args with optional model selection
+      const spawnArgs = ["--print"];
+      if (model) {
+        spawnArgs.push("--model", model);
+      }
+      spawnArgs.push("-p", prompt);
+
+      const child = spawn("claude", spawnArgs, {
+        cwd: this.rootPath,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: false,
+      });
+
+      let stdout = "";
+      let stderr = "";
+      let killed = false;
+
+      // Manual timeout (spawn doesn't support timeout option)
+      const timer = setTimeout(() => {
+        killed = true;
+        child.kill("SIGTERM");
+        setTimeout(() => {
+          if (!child.killed) child.kill("SIGKILL");
+        }, 5000);
+      }, timeout);
+
+      child.stdout.on("data", (data) => {
+        stdout += data.toString();
+        if (stdout.length > MAX_OUTPUT) {
+          killed = true;
+          child.kill("SIGTERM");
+        }
+      });
+      child.stderr.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        if (killed) {
+          reject(
+            new Error(`Dispatch ${dispatchId} timed out after ${timeout}ms`),
+          );
+        } else if (code === 0) {
+          resolve({
+            success: true,
+            output: stdout,
+            filesModified: this._extractFiles(stdout),
+          });
+        } else {
+          reject(
+            new Error(`Agent exited with code ${code}: ${stderr || stdout}`),
+          );
+        }
+      });
+
+      child.on("error", (err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  //  Helpers
+  // -----------------------------------------------------------------------
+
+  /**
+   * Resolve the model CLI identifier from agent model shorthand.
+   * Uses ModelRouter when available and no explicit override is set.
+   * Returns null to use the default model.
+   *
+   * @param {string} dispatchId
+   * @returns {string|null}
+   */
+  _resolveModel(dispatchId) {
+    const active = this._active.get(dispatchId);
+    const shorthand = active?.agentModel;
+
+    // If explicit model override was provided, use it directly
+    if (shorthand) {
+      if (shorthand === LOCAL_MODEL) return LOCAL_MODEL;
+      return MODEL_MAP[shorthand] || null;
+    }
+
+    // If ModelRouter is available, use it for smart routing
+    if (this._modelRouter && active) {
+      const complexity = active.taskComplexity || "MODERATE";
+      const taskType = active.taskType || null;
+      const agentId = active.agentId || null;
+      const mode = active.mode || null;
+      const { model } = this._modelRouter.resolveModel(
+        complexity,
+        taskType,
+        agentId,
+        mode,
+      );
+      // Explicit local-tier passthrough — MUST come before the MODEL_MAP lookup,
+      // which would yield null → silent default-Claude (the documented gotcha).
+      if (model === LOCAL_MODEL) return LOCAL_MODEL;
+      return MODEL_MAP[model] || null;
+    }
+
+    return null;
+  }
+
+  /**
+   * Generate a unique dispatch ID.
+   * @returns {string}
+   */
+  _generateId() {
+    return `d-${Date.now().toString(36)}-${crypto.randomBytes(4).toString("hex")}`;
+  }
+
+  /**
+   * Parse structured messages from agent output.
+   *
+   * Agents emit messages using the pattern: `[TYPE: content]`
+   * where TYPE is one of NOTIFY, ASK, PROGRESS, RESULT.
+   * Untagged output is treated as NOTIFY.
+   *
+   * @param {string} output - Raw agent output
+   * @returns {Array<{type: string, content: string}>}
+   */
+  _parseMessages(output) {
+    if (!output) return [];
+
+    const messages = [];
+    const tagPattern =
+      /\[(NOTIFY|ASK|PROGRESS|RESULT|THOUGHT):\s*([\s\S]*?)\]/g;
+    let lastIndex = 0;
+    let match;
+
+    while ((match = tagPattern.exec(output)) !== null) {
+      // Capture untagged text before this match as NOTIFY
+      if (match.index > lastIndex) {
+        const before = output.slice(lastIndex, match.index).trim();
+        if (before) {
+          messages.push({ type: MessageType.NOTIFY, content: before });
+        }
+      }
+      messages.push({
+        type: MessageType[match[1]] || MessageType.NOTIFY,
+        content: match[2].trim(),
+      });
+      lastIndex = match.index + match[0].length;
+    }
+
+    // Remaining untagged text
+    if (lastIndex < output.length) {
+      const remaining = output.slice(lastIndex).trim();
+      if (remaining) {
+        messages.push({ type: MessageType.NOTIFY, content: remaining });
+      }
+    }
+
+    return messages;
+  }
+
+  /**
+   * Extract file paths mentioned in agent output.
+   * @param {string} output
+   * @returns {string[]}
+   */
+  _extractFiles(output) {
+    const files = [];
+    const patterns = [
+      /(?:created|modified|updated|wrote|edited)\s+[`'"]?([^\s`'"]+\.[a-z]+)[`'"]?/gi,
+      /file:\s*[`'"]?([^\s`'"]+\.[a-z]+)[`'"]?/gi,
+    ];
+
+    for (const re of patterns) {
+      let m;
+      while ((m = re.exec(output)) !== null) {
+        if (!files.includes(m[1])) files.push(m[1]);
+      }
+    }
+
+    return files;
+  }
+}
+
+// ---------------------------------------------------------------------------
+//  Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { SubagentDispatcher };