agent-pool-mcp 1.3.0 → 1.5.0

package/README.md

@@ -282,7 +282,7 @@ src/
 - **Live Events**: Progress polling uses a ring buffer to show the latest activity without overwhelming context.
 - **Depth Tracking**: Nested orchestration support with optional `AGENT_POOL_MAX_DEPTH` limit.
 - **Adaptive Polling**: Pipeline daemon uses 3s intervals when active, 30s when idle.
-- **File-Based Communication**: Pipeline agents communicate through `.agent/runs/` JSON files — each Gemini process has its own MCP server instance but shares state via filesystem.
+- **File-Based Communication**: Pipeline agents communicate through `.agents/runs/` JSON files — each Gemini process has its own MCP server instance but shares state via filesystem.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-pool-mcp",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "MCP Server for multi-agent task delegation and orchestration via Gemini CLI",
   "main": "index.js",

package/skills/group-lead.md

@@ -0,0 +1,30 @@
+---
+name: group-lead
+description: Fractal group leader — breaks down tasks and delegates to group members via delegate_to_group.
+---
+
+# Group Lead
+
+You are a group leader in a fractal agent orchestration system. Your role is to:
+
+1. **Analyze** the incoming task and break it into independent subtasks
+2. **Create groups** if they don't exist yet, with appropriate skills and policies
+3. **Delegate** subtasks to group members using `delegate_to_group`
+4. **Collect** results from all agents using `get_task_result`
+5. **Synthesize** a final report combining all results
+
+## Rules
+
+- Break tasks into pieces that can run in parallel
+- Each subtask should be self-contained (agent can complete it without external context)
+- Set appropriate policies: use `read-only` for analysis, `safe-edit` for code changes
+- Always set `max_agents` to prevent runaway spawning
+- Collect ALL results before synthesizing — don't skip slow agents
+- Report both successes and failures
+
+## Output Format
+
+After collecting all results, produce a structured summary:
+1. Task overview (what was asked)
+2. Subtask results (one per agent)
+3. Synthesized conclusion

package/src/scheduler/daemon.js

@@ -17,9 +17,9 @@ import { join, dirname } from 'node:path';
 import { matchesCron } from './cron.js';
 
 const POLL_INTERVAL_MS = 30_000; // Check schedules every 30 seconds
-const PID_FILE = '.agent/scheduler.pid';
-const SCHEDULE_FILE = '.agent/schedule.json';
-const RESULTS_DIR = '.agent/scheduled-results';
+const PID_FILE = '.agents/scheduler.pid';
+const SCHEDULE_FILE = '.agents/schedule.json';
+const RESULTS_DIR = '.agents/scheduled-results';
 
 /** @type {string} */
 const cwd = process.argv[2] || process.cwd();
@@ -163,8 +163,8 @@ function executeSchedule(schedule) {
 
 import { readdirSync } from 'node:fs';
 
-const PIPELINES_DIR = '.agent/pipelines';
-const RUNS_DIR = '.agent/runs';
+const PIPELINES_DIR = '.agents/pipelines';
+const RUNS_DIR = '.agents/runs';
 
 /**
  * Spawn a Gemini CLI agent for a pipeline step.

package/src/scheduler/pipeline.js

@@ -1,8 +1,8 @@
 /**
  * Pipeline management — CRUD for pipeline definitions and run state.
  *
- * Pipelines are stored as JSON templates in .agent/pipelines/.
- * Each execution creates a run state in .agent/runs/.
+ * Pipelines are stored as JSON templates in .agents/pipelines/.
+ * Each execution creates a run state in .agents/runs/.
  *
  * @module agent-pool/scheduler/pipeline
  */
@@ -12,8 +12,8 @@ import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { ensureDaemon } from './scheduler.js';
 
-const PIPELINES_DIR = '.agent/pipelines';
-const RUNS_DIR = '.agent/runs';
+const PIPELINES_DIR = '.agents/pipelines';
+const RUNS_DIR = '.agents/runs';
 
 // ─── Helpers ────────────────────────────────────────────────
 

package/src/scheduler/scheduler.js

@@ -15,9 +15,9 @@ import { nextCronRun } from './cron.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DAEMON_SCRIPT = join(__dirname, 'daemon.js');
 
-const SCHEDULE_FILE = '.agent/schedule.json';
-const RESULTS_DIR = '.agent/scheduled-results';
-const PID_FILE = '.agent/scheduler.pid';
+const SCHEDULE_FILE = '.agents/schedule.json';
+const RESULTS_DIR = '.agents/scheduled-results';
+const PID_FILE = '.agents/scheduler.pid';
 
 // ─── Schedule CRUD ──────────────────────────────────────────
 

package/src/server.js

@@ -22,6 +22,7 @@ import { listSkills, createSkill, deleteSkill, installSkill, provisionSkill } fr
 import { consultPeer } from './tools/consult.js';
 import { addSchedule, listSchedules, removeSchedule, getScheduledResults, getDaemonStatus } from './scheduler/scheduler.js';
 import { createPipeline, listPipelines, runPipeline, getRun, listRuns, cancelRun, signalStepComplete, bounceBack } from './scheduler/pipeline.js';
+import { createGroup, listGroups, getGroup } from './tools/groups.js';
 
 import { TOOL_DEFINITIONS } from './tool-definitions.js';
 
@@ -68,6 +69,7 @@ Docs: https://github.com/google-gemini/gemini-cli`
 /** Tools that require Gemini CLI to be installed */
 const GEMINI_TOOLS = new Set([
   'delegate_task', 'delegate_task_readonly', 'consult_peer', 'list_sessions',
+  'delegate_to_group',
 ]);
 
 // ─── Depth tracking (for nested orchestration) ──────────────
@@ -110,7 +112,7 @@ export function createServer() {
   }
 
   const server = new Server(
-    { name: 'agent-pool', version: '1.2.1' },
+    { name: 'agent-pool', version: '1.5.0' },
     { capabilities: { tools: {}, resources: {} } },
   );
 
@@ -200,6 +202,12 @@ export function createServer() {
           response = handleBounceBack(args); break;
         case 'get_usage_guide':
           response = handleGetUsageGuide(args); break;
+        case 'create_group':
+          response = handleCreateGroup(args); break;
+        case 'list_groups':
+          response = handleListGroups(args); break;
+        case 'delegate_to_group':
+          response = handleDelegateToGroup(args); break;
         default:
           response = { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
       }
@@ -422,7 +430,7 @@ function handleScheduleTask(args) {
     return {
       content: [{
         type: 'text',
-        text: `⏰ Task scheduled.\n\n- **Schedule ID**: \`${result.scheduleId}\`\n- **Cron**: \`${args.cron}\`\n- **Next run**: ${result.nextRun || 'unknown'}\n- **Prompt**: ${args.prompt.substring(0, 100)}...\n\nDaemon is running in the background. Results will be saved to \`.agent/scheduled-results/\`.\nUse \`list_schedules\` to see all schedules, \`get_scheduled_results\` to read outputs.`,
+        text: `⏰ Task scheduled.\n\n- **Schedule ID**: \`${result.scheduleId}\`\n- **Cron**: \`${args.cron}\`\n- **Next run**: ${result.nextRun || 'unknown'}\n- **Prompt**: ${args.prompt.substring(0, 100)}...\n\nDaemon is running in the background. Results will be saved to \`.agents/scheduled-results/\`.\nUse \`list_schedules\` to see all schedules, \`get_scheduled_results\` to read outputs.`,
       }],
     };
   } catch (error) {
@@ -688,3 +696,110 @@ function handleGetUsageGuide(args) {
   return { content: [{ type: 'text', text: topicContent.join('\n').trim() }] };
 }
 
+// ─── Group Handlers ─────────────────────────────────────────────
+
+/** @param {object} args */
+function handleCreateGroup(args) {
+  const cwd = args.cwd ?? defaultCwd;
+  const result = createGroup(cwd, {
+    name: args.name,
+    runner: args.runner,
+    skill: args.skill,
+    policy: args.policy,
+    max_agents: args.max_agents,
+    include_dirs: args.include_dirs,
+  });
+
+  const configParts = [];
+  if (args.runner) configParts.push(`runner: ${args.runner}`);
+  if (args.skill) configParts.push(`skill: ${args.skill}`);
+  if (args.policy) configParts.push(`policy: ${args.policy}`);
+  if (args.max_agents) configParts.push(`max: ${args.max_agents}`);
+
+  return {
+    content: [{
+      type: 'text',
+      text: `✅ Group ${result.created ? 'created' : 'updated'}: \`${args.name}\`${configParts.length > 0 ? `\n- ${configParts.join('\n- ')}` : ''}\n\nUse \`delegate_to_group\` to send tasks to this group.`,
+    }],
+  };
+}
+
+/** @param {object} args */
+function handleListGroups(args) {
+  const cwd = args.cwd ?? defaultCwd;
+  const groups = listGroups(cwd);
+
+  if (groups.length === 0) {
+    return { content: [{ type: 'text', text: 'No groups defined. Use `create_group` to create one.' }] };
+  }
+
+  const lines = groups.map((g) => {
+    const parts = [];
+    if (g.runner) parts.push(`runner: ${g.runner}`);
+    if (g.skill) parts.push(`skill: ${g.skill}`);
+    if (g.policy) parts.push(`policy: ${g.policy}`);
+    if (g.max_agents) parts.push(`max: ${g.max_agents}`);
+    return `- **${g.name}** — ${parts.join(', ') || 'no config'}`;
+  });
+
+  return {
+    content: [{ type: 'text', text: `## Agent Groups (${groups.length})\n\n${lines.join('\n')}` }],
+  };
+}
+
+/** @param {object} args */
+function handleDelegateToGroup(args) {
+  const cwd = args.cwd ?? defaultCwd;
+  const group = getGroup(cwd, args.group);
+
+  if (!group) {
+    return {
+      content: [{ type: 'text', text: `❌ Group \`${args.group}\` not found. Use \`list_groups\` to see available groups.` }],
+      isError: true,
+    };
+  }
+
+  const count = args.count ?? 1;
+
+  // Check max_agents limit
+  if (group.max_agents && count > group.max_agents) {
+    return {
+      content: [{
+        type: 'text',
+        text: `❌ Requested ${count} agents but group \`${args.group}\` allows max ${group.max_agents}.`,
+      }],
+      isError: true,
+    };
+  }
+
+  const taskIds = [];
+
+  for (let i = 0; i < count; i++) {
+    const delegateArgs = {
+      prompt: count > 1 ? `[Agent ${i + 1}/${count} in group "${args.group}"]\n\n${args.prompt}` : args.prompt,
+      cwd,
+      runner: group.runner || undefined,
+      skill: group.skill || undefined,
+      policy: group.policy || undefined,
+      include_dirs: group.include_dirs || undefined,
+      timeout: args.timeout,
+    };
+
+    const result = handleDelegate(delegateArgs, {
+      approvalMode: DEFAULT_APPROVAL_MODE,
+      emoji: '👥',
+      label: `Group task (${args.group} #${i + 1})`,
+    });
+
+    // Extract task_id from response text
+    const match = result.content[0].text.match(/`([0-9a-f-]{36})`/);
+    if (match) taskIds.push(match[1]);
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: `👥 Delegated to group \`${args.group}\` — ${count} agent(s) spawned.\n\n${taskIds.map((id, i) => `- Agent ${i + 1}: \`${id}\``).join('\n')}\n\nUse \`get_task_result\` to check each agent's status.`,
+    }],
+  };
+}

package/src/tool-definitions.js

@@ -199,7 +199,7 @@ export const TOOL_DEFINITIONS = [
     description: [
       'Schedule a Gemini CLI agent to run on a cron schedule or as a delayed one-shot.',
       'Spawns a persistent daemon that survives IDE/CLI restarts.',
-      'Results are saved to .agent/scheduled-results/ and can be retrieved with get_scheduled_results.',
+      'Results are saved to .agents/scheduled-results/ and can be retrieved with get_scheduled_results.',
       '',
       'Cron format: standard 5-field (minute hour day month weekday).',
       'Examples: "*/30 * * * *" (every 30 min), "0 9 * * MON-FRI" (9am weekdays), "0 */2 * * *" (every 2 hours).',
@@ -360,5 +360,53 @@ export const TOOL_DEFINITIONS = [
       required: ['step_name', 'reason'],
     },
   },
+  // ─── Group Tools ────────────────────────────────────────
+  {
+    name: 'create_group',
+    description: 'Create a named agent group with shared config (runner, skill, policy). Groups are reusable presets for fractal orchestration.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Group name (e.g. "backend-team", "qa-group").' },
+        runner: { type: 'string', description: 'Default runner for agents in this group.' },
+        skill: { type: 'string', description: 'Default skill activated for all agents in this group.' },
+        policy: { type: 'string', description: 'Default policy restricting agent permissions.' },
+        max_agents: { type: 'number', description: 'Max concurrent agents allowed in this group.' },
+        include_dirs: { type: 'array', items: { type: 'string' }, description: 'Additional directories agents in this group can access.' },
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'list_groups',
+    description: 'List all registered agent groups with their config.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: { type: 'string', description: 'Project directory. Defaults to current working directory.' },
+      },
+    },
+  },
+  {
+    name: 'delegate_to_group',
+    description: [
+      'Delegate a task to a named agent group. Spawns agents with the group\'s shared config (runner, skill, policy).',
+      'Use `count` to launch multiple agents in parallel (fractal orchestration).',
+      '',
+      'Returns array of task_ids immediately (non-blocking). Use get_task_result to check each.',
+    ].join('\n'),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        group: { type: 'string', description: 'Group name to delegate to.' },
+        prompt: { type: 'string', description: 'Task description for the agents.' },
+        count: { type: 'number', description: 'Number of agents to spawn. Default: 1.' },
+        cwd: { type: 'string', description: 'Working directory. Defaults to current working directory.' },
+        timeout: { type: 'number', description: 'Timeout in seconds. Overrides group default.' },
+      },
+      required: ['group', 'prompt'],
+    },
+  },
 ];
 

package/src/tools/groups.js

@@ -0,0 +1,124 @@
+/**
+ * Agent Groups — named config presets for fractal orchestration.
+ * Groups bundle runner, skill, policy, and max_agents into a reusable team config.
+ *
+ * @module agent-pool/tools/groups
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const GROUPS_DIR = '.agents';
+const GROUPS_FILE = 'groups.json';
+
+/**
+ * Get path to groups.json for a project.
+ *
+ * @param {string} cwd - Project directory
+ * @returns {string}
+ */
+function getGroupsPath(cwd) {
+  return path.join(cwd, GROUPS_DIR, GROUPS_FILE);
+}
+
+/**
+ * Load all groups from disk.
+ *
+ * @param {string} cwd - Project directory
+ * @returns {Object<string, object>}
+ */
+function loadGroups(cwd) {
+  const filePath = getGroupsPath(cwd);
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save groups to disk.
+ *
+ * @param {string} cwd - Project directory
+ * @param {Object<string, object>} groups
+ */
+function saveGroups(cwd, groups) {
+  const dirPath = path.join(cwd, GROUPS_DIR);
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+  fs.writeFileSync(getGroupsPath(cwd), JSON.stringify(groups, null, 2));
+}
+
+/**
+ * Create or update a group.
+ *
+ * @param {string} cwd - Project directory
+ * @param {object} config - Group configuration
+ * @param {string} config.name - Group name (e.g. "backend-team")
+ * @param {string} [config.runner] - Default runner for agents in this group
+ * @param {string} [config.skill] - Default skill for agents in this group
+ * @param {string} [config.policy] - Default policy for agents in this group
+ * @param {number} [config.max_agents] - Max concurrent agents in this group
+ * @param {string[]} [config.include_dirs] - Additional directories agents can access
+ * @returns {{ name: string, created: boolean }}
+ */
+export function createGroup(cwd, config) {
+  const groups = loadGroups(cwd);
+  const existed = !!groups[config.name];
+
+  groups[config.name] = {
+    runner: config.runner || null,
+    skill: config.skill || null,
+    policy: config.policy || null,
+    max_agents: config.max_agents || null,
+    include_dirs: config.include_dirs || null,
+    created_at: existed ? groups[config.name].created_at : new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+  };
+
+  saveGroups(cwd, groups);
+  return { name: config.name, created: !existed };
+}
+
+/**
+ * List all groups.
+ *
+ * @param {string} cwd - Project directory
+ * @returns {Array<{ name: string, runner: string|null, skill: string|null, policy: string|null, max_agents: number|null }>}
+ */
+export function listGroups(cwd) {
+  const groups = loadGroups(cwd);
+  return Object.entries(groups).map(([name, config]) => ({
+    name,
+    ...config,
+  }));
+}
+
+/**
+ * Get a single group by name.
+ *
+ * @param {string} cwd - Project directory
+ * @param {string} name - Group name
+ * @returns {object|null}
+ */
+export function getGroup(cwd, name) {
+  const groups = loadGroups(cwd);
+  return groups[name] || null;
+}
+
+/**
+ * Delete a group.
+ *
+ * @param {string} cwd - Project directory
+ * @param {string} name - Group name
+ * @returns {boolean}
+ */
+export function deleteGroup(cwd, name) {
+  const groups = loadGroups(cwd);
+  if (!groups[name]) return false;
+  delete groups[name];
+  saveGroups(cwd, groups);
+  return true;
+}