agent-enderun 0.7.2 → 0.8.0

package/framework-mcp/src/tools/orchestration.ts

@@ -0,0 +1,439 @@
+import { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { promises as fs } from "fs";
+import path from "path";
+
+// ─── Tool Definitions ─────────────────────────────────────────────────────────
+
+export const orchestrationTools: Tool[] = [
+  {
+    name: "create_task_dag",
+    description:
+      "Creates a Directed Acyclic Graph (DAG) of tasks with dependencies. Used by @orchestrator to plan parallel execution. Returns both a JSON structure and a Mermaid diagram for visualization.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        traceId: {
+          type: "string",
+          description: "Trace ID inherited from @manager briefing. Required.",
+        },
+        tasks: {
+          type: "array",
+          description: "Array of task definitions to build the DAG from.",
+          items: {
+            type: "object",
+            required: ["id", "agent", "briefing"],
+            properties: {
+              id: { type: "string", description: "Unique task ID (e.g. T001)" },
+              agent: { type: "string", description: "Assigned agent (e.g. @backend)" },
+              briefing: { type: "string", description: "Task description" },
+              dependsOn: {
+                type: "array",
+                items: { type: "string" },
+                description: "Task IDs that must complete before this task starts",
+              },
+              priority: {
+                type: "string",
+                enum: ["CRITICAL", "HIGH", "MEDIUM", "LOW"],
+                default: "MEDIUM",
+              },
+            },
+          },
+        },
+      },
+      required: ["traceId", "tasks"],
+    },
+  },
+  {
+    name: "assign_agent_to_task",
+    description:
+      "Assigns the most capable available agent to a task based on domain and capability score. Checks STATUS.md for agent availability before assigning.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        traceId: { type: "string", description: "Active Trace ID" },
+        taskId: { type: "string", description: "Task ID to assign" },
+        domain: {
+          type: "string",
+          enum: ["backend", "frontend", "security", "qa", "devops", "mobile", "native", "analysis", "git", "exploration"],
+          description: "Domain of the task — used to filter eligible agents",
+        },
+        preferredAgent: {
+          type: "string",
+          description: "Optional preferred agent. If not available, falls back to capability-based selection.",
+        },
+      },
+      required: ["traceId", "taskId", "domain"],
+    },
+  },
+  {
+    name: "get_agent_workload",
+    description:
+      "Returns the current workload for all agents: active task count, state, current task description, and health score. Used by @orchestrator to make load-aware assignment decisions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectRoot: { type: "string", description: "Root directory of the project." },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "resolve_agent_blockage",
+    description:
+      "Handles a BLOCKED agent by documenting the blockage, escalating to @manager, and optionally reassigning the task to another eligible agent.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        blockedAgent: { type: "string", description: "The agent identifier that is BLOCKED, e.g. @frontend" },
+        traceId: { type: "string", description: "Active Trace ID" },
+        blockReason: { type: "string", description: "Mandatory description of why the agent is blocked" },
+        reassign: {
+          type: "boolean",
+          description: "If true, attempt to find and assign an alternative agent",
+          default: false,
+        },
+      },
+      required: ["blockedAgent", "traceId", "blockReason"],
+    },
+  },
+  {
+    name: "broadcast_army_directive",
+    description:
+      "Broadcasts a directive message to all agents simultaneously via the Hermes messaging system. Used for war-room mode, policy changes, or global state transitions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        traceId: { type: "string", description: "Active Trace ID" },
+        directiveType: {
+          type: "string",
+          enum: [
+            "WAR_ROOM_ACTIVATE",
+            "WAR_ROOM_DEACTIVATE",
+            "CONTRACT_CHANGED",
+            "PHASE_ROLLBACK",
+            "POLICY_UPDATE",
+            "ARMY_PAUSE",
+            "ARMY_RESUME",
+          ],
+          description: "Type of directive being broadcast",
+        },
+        message: { type: "string", description: "Human-readable directive message" },
+        urgency: {
+          type: "string",
+          enum: ["IMMEDIATE", "HIGH", "NORMAL"],
+          default: "NORMAL",
+        },
+      },
+      required: ["traceId", "directiveType", "message"],
+    },
+  },
+];
+
+// ─── Handlers ─────────────────────────────────────────────────────────────────
+
+export const orchestrationHandlers: Record<
+  string,
+  (args: unknown, projectRoot: string) => Promise<{ content: Array<{ type: string; text: string }> }>
+> = {
+  async create_task_dag(args, projectRoot) {
+    const { traceId, tasks } = args as {
+      traceId: string;
+      tasks: Array<{
+        id: string;
+        agent: string;
+        briefing: string;
+        dependsOn?: string[];
+        priority?: string;
+      }>;
+    };
+
+    // Build adjacency structure
+    const dagNodes = tasks.map((t) => ({
+      id: t.id,
+      agent: t.agent,
+      briefing: t.briefing,
+      status: "PENDING",
+      priority: t.priority ?? "MEDIUM",
+      dependsOn: t.dependsOn ?? [],
+    }));
+
+    // Topological sort to find execution order
+    const executionWaves: string[][] = [];
+    const resolved = new Set<string>();
+    const remaining = [...dagNodes];
+
+    while (remaining.length > 0) {
+      const wave = remaining.filter(
+        (n) => n.dependsOn.every((dep) => resolved.has(dep))
+      );
+      if (wave.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "CIRCULAR_DEPENDENCY",
+                message: "Circular dependency detected in task DAG. Check dependsOn fields.",
+              }),
+            },
+          ],
+        };
+      }
+      executionWaves.push(wave.map((n) => n.id));
+      wave.forEach((n) => {
+        resolved.add(n.id);
+        remaining.splice(remaining.indexOf(n), 1);
+      });
+    }
+
+    // Generate Mermaid diagram
+    const mermaidLines = ["graph TD"];
+    for (const node of dagNodes) {
+      const label = `${node.id}["${node.agent}: ${node.briefing.slice(0, 40)}..."]`;
+      mermaidLines.push(`  ${node.id}${label}`);
+    }
+    for (const node of dagNodes) {
+      for (const dep of node.dependsOn) {
+        mermaidLines.push(`  ${dep} --> ${node.id}`);
+      }
+    }
+
+    const dag = {
+      traceId,
+      createdAt: new Date().toISOString(),
+      nodes: dagNodes,
+      executionWaves,
+      mermaid: mermaidLines.join("\n"),
+      parallelOpportunities: executionWaves.filter((w) => w.length > 1).length,
+    };
+
+    // Persist to queue
+    const queueDir = path.join(projectRoot, ".enderun", "queue", "pending");
+    await fs.mkdir(queueDir, { recursive: true });
+    await fs.writeFile(
+      path.join(queueDir, `${traceId}-dag.json`),
+      JSON.stringify(dag, null, 2),
+      "utf-8"
+    );
+
+    return { content: [{ type: "text", text: JSON.stringify(dag, null, 2) }] };
+  },
+
+  async assign_agent_to_task(args, projectRoot) {
+    const { traceId, taskId, domain, preferredAgent } = args as {
+      traceId: string;
+      taskId: string;
+      domain: string;
+      preferredAgent?: string;
+    };
+
+    // Try to load capability roster from shared-facts.json (dynamic — fixes KRITIK-3)
+    let agentCapabilityRoster: Array<{ agent: string; primaryDomain: string; capability: number }> = [];
+    try {
+      const sharedFactsPath = path.join(projectRoot, ".enderun", "memory-graph", "shared-facts.json");
+      const content = await fs.readFile(sharedFactsPath, "utf-8");
+      const facts = JSON.parse(content) as { agentCapabilityRoster?: typeof agentCapabilityRoster };
+      agentCapabilityRoster = facts.agentCapabilityRoster ?? [];
+    } catch {
+      // Fallback to hardcoded map if shared-facts not available
+    }
+
+    // Build domain → agents map from shared-facts roster
+    // Exclude @manager — @manager does NOT execute specialist tasks
+    const domainMap: Record<string, { agent: string; capability: number }[]> = {};
+    for (const entry of agentCapabilityRoster) {
+      if (entry.agent === "@manager" || entry.agent === "@orchestrator") continue;
+      const d = entry.primaryDomain;
+      if (!domainMap[d]) domainMap[d] = [];
+      domainMap[d].push({ agent: entry.agent, capability: entry.capability });
+    }
+
+    // Hardcoded fallback (used only if shared-facts unavailable)
+    const fallbackDomainMap: Record<string, { agent: string; capability: number }[]> = {
+      backend: [{ agent: "@backend", capability: 9.2 }],
+      frontend: [{ agent: "@frontend", capability: 9.0 }],
+      security: [{ agent: "@security", capability: 9.3 }],
+      qa: [{ agent: "@qa", capability: 9.1 }],
+      devops: [{ agent: "@devops", capability: 9.0 }],
+      mobile: [{ agent: "@mobile", capability: 8.8 }],
+      native: [{ agent: "@native", capability: 8.9 }],
+      analysis: [{ agent: "@analyst", capability: 9.6 }],
+      git: [{ agent: "@git", capability: 9.1 }],
+      exploration: [{ agent: "@explorer", capability: 9.4 }],
+    };
+
+    const effectiveMap = Object.keys(domainMap).length > 0 ? domainMap : fallbackDomainMap;
+    const candidates = effectiveMap[domain] ?? [];
+    let assigned = [...candidates].sort((a, b) => b.capability - a.capability)[0];
+
+    if (preferredAgent && preferredAgent !== "@manager" && preferredAgent !== "@orchestrator") {
+      const preferred = candidates.find((c) => c.agent === preferredAgent);
+      if (preferred) assigned = preferred;
+    }
+
+    if (!assigned) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ error: "NO_ELIGIBLE_AGENT", domain, taskId,
+              note: "@manager and @orchestrator are excluded from task assignment" }),
+          },
+        ],
+      };
+    }
+
+    const assignment = {
+      traceId,
+      taskId,
+      assignedAgent: assigned.agent,
+      capabilityScore: assigned.capability,
+      assignedAt: new Date().toISOString(),
+      domain,
+      sourceMap: Object.keys(domainMap).length > 0 ? "shared-facts" : "fallback",
+    };
+
+    // Write assignment log
+    const logPath = path.join(projectRoot, ".enderun", "logs", "orchestrator.json");
+    let log: { assignments: unknown[] } = { assignments: [] };
+    try {
+      const existing = await fs.readFile(logPath, "utf-8");
+      log = JSON.parse(existing) as { assignments: unknown[] };
+    } catch {
+      // File doesn't exist yet — start fresh
+    }
+    log.assignments.push(assignment);
+    await fs.mkdir(path.dirname(logPath), { recursive: true });
+    await fs.writeFile(logPath, JSON.stringify(log, null, 2), "utf-8");
+
+    return { content: [{ type: "text", text: JSON.stringify(assignment, null, 2) }] };
+  },
+
+  async get_agent_workload(_args, projectRoot) {
+    const statusPath = path.join(projectRoot, ".enderun", "STATUS.md");
+    let statusContent: string;
+    try {
+      statusContent = await fs.readFile(statusPath, "utf-8");
+    } catch {
+      statusContent = "";
+    }
+
+    // Parse the markdown table
+    const lines = statusContent.length > 0
+      ? statusContent.split("\n").filter((l) => l.includes("|") && !l.includes("---"))
+      : [];
+    const agents = lines.length > 1
+      ? lines
+          .slice(1) // skip header
+          .map((line) => {
+            const cells = line.split("|").map((c) => c.trim()).filter(Boolean);
+            return cells.length >= 4
+              ? { agent: cells[0], state: cells[1], currentTask: cells[2], healthScore: cells[4] }
+              : null;
+          })
+          .filter(Boolean)
+      : [];
+
+    return { content: [{ type: "text", text: JSON.stringify({ agents, generatedAt: new Date().toISOString() }, null, 2) }] };
+  },
+
+  async resolve_agent_blockage(args, projectRoot) {
+    const { blockedAgent, traceId, blockReason, reassign } = args as {
+      blockedAgent: string;
+      traceId: string;
+      blockReason: string;
+      reassign?: boolean;
+    };
+
+    const resolution = {
+      traceId,
+      blockedAgent,
+      blockReason,
+      detectedAt: new Date().toISOString(),
+      escalatedToManager: true,
+      reassignAttempted: reassign ?? false,
+      status: "ESCALATED_TO_MANAGER",
+    };
+
+    // Log blockage
+    const logPath = path.join(projectRoot, ".enderun", "logs", "orchestrator.json");
+    let log: { assignments: unknown[]; blockages: unknown[] } = { assignments: [], blockages: [] };
+    try {
+      const existing = await fs.readFile(logPath, "utf-8");
+      log = JSON.parse(existing) as { assignments: unknown[]; blockages: unknown[] };
+      if (!log.blockages) log.blockages = [];
+    } catch {
+      // Start fresh
+    }
+    log.blockages.push(resolution);
+    await fs.mkdir(path.dirname(logPath), { recursive: true });
+    await fs.writeFile(logPath, JSON.stringify(log, null, 2), "utf-8");
+
+    // Write a message to @manager's inbox via messages folder
+    const messagesDir = path.join(projectRoot, ".enderun", "messages");
+    await fs.mkdir(messagesDir, { recursive: true });
+    const messageFile = path.join(messagesDir, `BLOCKAGE-${traceId}-${Date.now()}.json`);
+    await fs.writeFile(
+      messageFile,
+      JSON.stringify({
+        from: "@orchestrator",
+        to: "@manager",
+        type: "AGENT_BLOCKED",
+        traceId,
+        payload: { blockedAgent, blockReason, resolution },
+        timestamp: new Date().toISOString(),
+      }),
+      "utf-8"
+    );
+
+    return { content: [{ type: "text", text: JSON.stringify(resolution, null, 2) }] };
+  },
+
+  async broadcast_army_directive(args, projectRoot) {
+    const { traceId, directiveType, message, urgency } = args as {
+      traceId: string;
+      directiveType: string;
+      message: string;
+      urgency?: string;
+    };
+
+    const broadcast = {
+      id: `BROADCAST-${traceId}-${Date.now()}`,
+      from: "@orchestrator",
+      to: "*",
+      traceId,
+      directiveType,
+      message,
+      urgency: urgency ?? "NORMAL",
+      timestamp: new Date().toISOString(),
+    };
+
+    // Write to messages folder for all agents
+    const messagesDir = path.join(projectRoot, ".enderun", "messages");
+    await fs.mkdir(messagesDir, { recursive: true });
+    await fs.writeFile(
+      path.join(messagesDir, `${broadcast.id}.json`),
+      JSON.stringify(broadcast, null, 2),
+      "utf-8"
+    );
+
+    // Log broadcast
+    const logPath = path.join(projectRoot, ".enderun", "logs", "orchestrator.json");
+    let log: { assignments: unknown[]; blockages: unknown[]; broadcasts: unknown[] } = {
+      assignments: [],
+      blockages: [],
+      broadcasts: [],
+    };
+    try {
+      const existing = await fs.readFile(logPath, "utf-8");
+      log = JSON.parse(existing) as typeof log;
+      if (!log.broadcasts) log.broadcasts = [];
+    } catch {
+      // Start fresh
+    }
+    log.broadcasts.push(broadcast);
+    await fs.writeFile(logPath, JSON.stringify(log, null, 2), "utf-8");
+
+    return { content: [{ type: "text", text: JSON.stringify(broadcast, null, 2) }] };
+  },
+};