agent-orchestration 0.5.0

package/src/tools/memory.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared memory tools
+ */
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getDatabase } from '../database.js';
+import { getCurrentAgentId } from './agent.js';
+
+export function registerMemoryTools(server: McpServer): void {
+  // memory_set
+  server.tool(
+    'memory_set',
+    'Store a value in shared memory. Use namespaces to organize: context, decisions, findings, blockers.',
+    {
+      key: z.string().describe('The key to store the value under'),
+      value: z.string().describe('The value to store (will be stored as-is)'),
+      namespace: z
+        .string()
+        .optional()
+        .default('default')
+        .describe('Namespace for organization (context, decisions, findings, blockers)'),
+      ttl_seconds: z
+        .number()
+        .optional()
+        .describe('Time-to-live in seconds. Entry auto-deletes after this time.'),
+    },
+    async ({ key, value, namespace, ttl_seconds }) => {
+      const agentId = getCurrentAgentId();
+
+      const entry = getDatabase().setMemory({
+        key,
+        value,
+        namespace,
+        createdBy: agentId,
+        ttlSeconds: ttl_seconds ?? null,
+      });
+
+      const ttlInfo = entry.ttlSeconds ? ` (expires in ${entry.ttlSeconds}s)` : '';
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Stored '${key}' in namespace '${namespace}'${ttlInfo}`,
+          },
+        ],
+      };
+    }
+  );
+
+  // memory_get
+  server.tool(
+    'memory_get',
+    'Retrieve a value from shared memory.',
+    {
+      key: z.string().describe('The key to retrieve'),
+      namespace: z.string().optional().default('default').describe('The namespace to search in'),
+    },
+    async ({ key, namespace }) => {
+      const entry = getDatabase().getMemory(key, namespace);
+
+      if (!entry) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Key '${key}' not found in namespace '${namespace}'.`,
+            },
+          ],
+        };
+      }
+
+      const valueStr =
+        typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value, null, 2);
+
+      const lines = [
+        `**${namespace}:${key}**`,
+        '',
+        valueStr,
+        '',
+        `_Updated: ${entry.updatedAt.toISOString()}_`,
+      ];
+
+      if (entry.expiresAt) {
+        lines.push(`_Expires: ${entry.expiresAt.toISOString()}_`);
+      }
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+
+  // memory_list
+  server.tool(
+    'memory_list',
+    'List all keys in a namespace.',
+    {
+      namespace: z.string().optional().default('default').describe('The namespace to list'),
+    },
+    async ({ namespace }) => {
+      const entries = getDatabase().listMemory(namespace);
+
+      if (entries.length === 0) {
+        return {
+          content: [{ type: 'text', text: `No entries in namespace '${namespace}'.` }],
+        };
+      }
+
+      const lines = [`# Memory: ${namespace}\n`];
+
+      for (const entry of entries) {
+        const valuePreview =
+          typeof entry.value === 'string'
+            ? entry.value.slice(0, 100) + (entry.value.length > 100 ? '...' : '')
+            : JSON.stringify(entry.value).slice(0, 100);
+
+        lines.push(`- **${entry.key}**: ${valuePreview}`);
+      }
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+
+  // memory_delete
+  server.tool(
+    'memory_delete',
+    'Delete a value from shared memory.',
+    {
+      key: z.string().describe('The key to delete'),
+      namespace: z.string().optional().default('default').describe('The namespace'),
+    },
+    async ({ key, namespace }) => {
+      const deleted = getDatabase().deleteMemory(key, namespace);
+
+      if (deleted) {
+        return {
+          content: [{ type: 'text', text: `Deleted '${key}' from namespace '${namespace}'.` }],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: `Key '${key}' not found in namespace '${namespace}'.` }],
+      };
+    }
+  );
+}

package/src/tools/task.ts

@@ -0,0 +1,334 @@
+/**
+ * Task management tools
+ */
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getDatabase } from '../database.js';
+import { TaskPriority, TaskStatus } from '../models.js';
+import { getCurrentAgentId } from './agent.js';
+
+export function registerTaskTools(server: McpServer): void {
+  // task_create
+  server.tool(
+    'task_create',
+    'Create a new task in the task queue.',
+    {
+      title: z.string().describe('Short title for the task'),
+      description: z.string().optional().default('').describe('Detailed description'),
+      priority: z
+        .enum(['low', 'normal', 'high', 'urgent'])
+        .optional()
+        .default('normal')
+        .describe('Priority level'),
+      assigned_to: z.string().optional().describe('Agent ID to assign to'),
+      dependencies: z
+        .array(z.string())
+        .optional()
+        .default([])
+        .describe('List of task IDs that must complete first'),
+    },
+    async ({ title, description, priority, assigned_to, dependencies }) => {
+      const agentId = getCurrentAgentId();
+
+      const task = getDatabase().createTask({
+        title,
+        description,
+        priority: priority as TaskPriority,
+        createdBy: agentId,
+        assignedTo: assigned_to ?? null,
+        dependencies,
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Task created: '${task.title}' (\`${task.id}\`)`,
+          },
+        ],
+      };
+    }
+  );
+
+  // task_claim
+  server.tool(
+    'task_claim',
+    'Claim a task to work on it. Sets status to in_progress.',
+    {
+      task_id: z
+        .string()
+        .optional()
+        .describe('Task ID to claim. If omitted, claims the next available task.'),
+    },
+    async ({ task_id }) => {
+      const agentId = getCurrentAgentId();
+      if (!agentId) {
+        return {
+          content: [{ type: 'text', text: 'Error: Not registered.' }],
+        };
+      }
+
+      const db = getDatabase();
+      let task;
+
+      if (task_id) {
+        task = db.getTask(task_id);
+        if (!task) {
+          return {
+            content: [{ type: 'text', text: `Task ${task_id} not found.` }],
+          };
+        }
+      } else {
+        task = db.getNextAvailableTask(agentId);
+        if (!task) {
+          return {
+            content: [{ type: 'text', text: 'No available tasks to claim.' }],
+          };
+        }
+      }
+
+      // Check dependencies
+      if (!db.checkDependenciesMet(task.id)) {
+        return {
+          content: [{ type: 'text', text: `Cannot claim: dependencies not met.` }],
+        };
+      }
+
+      // Claim it
+      const updated = db.updateTask(task.id, {
+        status: TaskStatus.IN_PROGRESS,
+        assignedTo: agentId,
+      });
+
+      if (updated) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Claimed task: '${updated.title}' (\`${updated.id}\`)`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Failed to claim task.' }],
+      };
+    }
+  );
+
+  // task_update
+  server.tool(
+    'task_update',
+    'Update a task status or progress.',
+    {
+      task_id: z.string().describe('The task ID to update'),
+      status: z
+        .enum(['pending', 'assigned', 'in_progress', 'completed', 'failed', 'cancelled'])
+        .optional()
+        .describe('New status'),
+      progress: z.number().min(0).max(100).optional().describe('Progress percentage (0-100)'),
+      output: z.string().optional().describe('Output or notes'),
+    },
+    async ({ task_id, status, progress, output }) => {
+      const db = getDatabase();
+      const task = db.getTask(task_id);
+
+      if (!task) {
+        return {
+          content: [{ type: 'text', text: `Task ${task_id} not found.` }],
+        };
+      }
+
+      const metadata = progress !== undefined ? { progress } : undefined;
+
+      const updated = db.updateTask(task_id, {
+        status: status as TaskStatus | undefined,
+        output,
+        metadata,
+      });
+
+      if (updated) {
+        const statusInfo = status ? ` → ${status}` : '';
+        const progressInfo = progress !== undefined ? ` (${progress}%)` : '';
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Updated task '${updated.title}'${statusInfo}${progressInfo}`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Failed to update task.' }],
+      };
+    }
+  );
+
+  // task_complete
+  server.tool(
+    'task_complete',
+    'Mark a task as completed with optional output.',
+    {
+      task_id: z.string().describe('The task ID to complete'),
+      output: z.string().optional().describe('Summary of what was done'),
+    },
+    async ({ task_id, output }) => {
+      const db = getDatabase();
+      const task = db.getTask(task_id);
+
+      if (!task) {
+        return {
+          content: [{ type: 'text', text: `Task ${task_id} not found.` }],
+        };
+      }
+
+      const updated = db.updateTask(task_id, {
+        status: TaskStatus.COMPLETED,
+        output,
+      });
+
+      if (updated) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `✅ Task completed: '${updated.title}'`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Failed to complete task.' }],
+      };
+    }
+  );
+
+  // task_list
+  server.tool(
+    'task_list',
+    'List tasks with optional filters.',
+    {
+      status: z
+        .enum(['pending', 'assigned', 'in_progress', 'completed', 'failed', 'cancelled'])
+        .optional()
+        .describe('Filter by status'),
+      assigned_to: z.string().optional().describe('Filter by assigned agent ID'),
+      mine: z.boolean().optional().describe('Show only my tasks'),
+    },
+    async ({ status, assigned_to, mine }) => {
+      const agentId = getCurrentAgentId();
+      const db = getDatabase();
+
+      let assignee = assigned_to;
+      if (mine && agentId) {
+        assignee = agentId;
+      }
+
+      const tasks = db.listTasks({
+        status: status as TaskStatus | undefined,
+        assignedTo: assignee,
+      });
+
+      if (tasks.length === 0) {
+        return {
+          content: [{ type: 'text', text: 'No tasks found.' }],
+        };
+      }
+
+      const lines = ['# Tasks\n'];
+
+      for (const task of tasks) {
+        const emoji = {
+          pending: '⏳',
+          assigned: '📋',
+          in_progress: '🔄',
+          completed: '✅',
+          failed: '❌',
+          cancelled: '🚫',
+        }[task.status];
+
+        lines.push(`${emoji} **${task.title}** (\`${task.id.slice(0, 8)}...\`)`);
+        lines.push(`   Status: ${task.status} | Assigned: ${task.assignedTo || 'none'}`);
+      }
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+
+  // is_my_turn
+  server.tool(
+    'is_my_turn',
+    "Check if it's your turn to work on a task or if work is available.",
+    {
+      task_id: z
+        .string()
+        .optional()
+        .describe('Specific task ID, or leave empty to check for any available task'),
+    },
+    async ({ task_id }) => {
+      const agentId = getCurrentAgentId();
+      if (!agentId) {
+        return {
+          content: [{ type: 'text', text: 'Error: Not registered.' }],
+        };
+      }
+
+      const db = getDatabase();
+
+      if (task_id) {
+        const task = db.getTask(task_id);
+        if (!task) {
+          return {
+            content: [{ type: 'text', text: `Task ${task_id} not found.` }],
+          };
+        }
+
+        if (task.assignedTo !== agentId) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `No - assigned to ${task.assignedTo || 'no one'}.`,
+              },
+            ],
+          };
+        }
+
+        if (!db.checkDependenciesMet(task_id)) {
+          return {
+            content: [{ type: 'text', text: 'No - waiting for dependencies.' }],
+          };
+        }
+
+        if (task.status === TaskStatus.COMPLETED) {
+          return {
+            content: [{ type: 'text', text: 'No - already completed.' }],
+          };
+        }
+
+        return {
+          content: [{ type: 'text', text: 'Yes - task is ready for you. Use task_claim to start.' }],
+        };
+      } else {
+        const available = db.getNextAvailableTask(agentId);
+        if (available) {
+          return {
+            content: [{ type: 'text', text: `Yes - '${available.title}' is available.` }],
+          };
+        }
+
+        return {
+          content: [{ type: 'text', text: 'No - no tasks available.' }],
+        };
+      }
+    }
+  );
+}

package/src/tools/utility.ts

@@ -0,0 +1,202 @@
+/**
+ * Utility tools (bootstrap, claim_todo)
+ */
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getDatabase } from '../database.js';
+import { AgentRole, AgentStatus, TaskPriority, TaskStatus } from '../models.js';
+import {
+  getCurrentAgentId,
+  setCurrentAgent,
+} from './agent.js';
+import { syncToActiveContext } from '../utils/contextSync.js';
+
+export function registerUtilityTools(server: McpServer): void {
+  // bootstrap
+  server.tool(
+    'bootstrap',
+    'Initialize agent session: register (if needed), get current focus, pending tasks, and recent decisions. Call this once at the start of your session.',
+    {
+      name: z
+        .string()
+        .optional()
+        .describe('Agent name. If not provided, uses env MCP_ORCH_AGENT_NAME or generates one.'),
+      role: z
+        .enum(['main', 'sub'])
+        .optional()
+        .default('sub')
+        .describe("Agent role. Defaults to env MCP_ORCH_AGENT_ROLE or 'sub'."),
+    },
+    async ({ name, role }) => {
+      const db = getDatabase();
+
+      // Get or generate agent name
+      let agentName = name ?? process.env.MCP_ORCH_AGENT_NAME;
+      if (!agentName) {
+        agentName = `agent-${Date.now()}`;
+      }
+
+      const agentRole =
+        role === 'main'
+          ? AgentRole.MAIN
+          : role === 'sub'
+            ? AgentRole.SUB
+            : process.env.MCP_ORCH_AGENT_ROLE === 'main'
+              ? AgentRole.MAIN
+              : AgentRole.SUB;
+
+      const capabilities = (process.env.MCP_ORCH_CAPABILITIES ?? 'code').split(',');
+
+      // Check if agent already exists
+      let agent = db.getAgentByName(agentName);
+
+      if (agent) {
+        // Reconnect
+        setCurrentAgent(agent.id, agent.name);
+        db.updateAgentHeartbeat(agent.id, AgentStatus.ACTIVE);
+      } else {
+        // Register new
+        agent = db.createAgent({
+          name: agentName,
+          role: agentRole,
+          capabilities,
+          status: AgentStatus.ACTIVE,
+        });
+        setCurrentAgent(agent.id, agent.name);
+      }
+
+      // Get current context
+      const focusEntry = db.getMemory('current_focus', 'context');
+      const focusText = focusEntry ? String(focusEntry.value) : 'Not set';
+
+      // Get pending tasks for this agent
+      const myTasks = db.listTasks({ assignedTo: agent.id });
+      const pendingTasks = myTasks.filter((t) =>
+        ['pending', 'assigned'].includes(t.status)
+      );
+
+      // Get recent decisions
+      const decisions = db.listMemory('decisions');
+
+      // Sync context
+      syncToActiveContext();
+
+      const lines: string[] = [
+        '# Session Initialized',
+        '',
+        `**Agent**: ${agent.name} (\`${agent.id}\`)`,
+        `**Role**: ${agent.role}`,
+        '',
+        '## Current Focus',
+        focusText,
+        '',
+        '## Your Pending Tasks',
+      ];
+
+      if (pendingTasks.length > 0) {
+        for (const t of pendingTasks.slice(0, 5)) {
+          lines.push(`- ${t.title} (\`${t.id.slice(0, 8)}...\`)`);
+        }
+      } else {
+        lines.push('_No tasks assigned to you._');
+      }
+
+      lines.push('', '## Recent Decisions');
+
+      if (decisions.length > 0) {
+        for (const d of decisions.slice(0, 5)) {
+          lines.push(`- **${d.key}**: ${String(d.value).slice(0, 80)}`);
+        }
+      } else {
+        lines.push('_No decisions recorded._');
+      }
+
+      lines.push('', '---', 'Use `is_my_turn` to check for available work.');
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+
+  // claim_todo
+  server.tool(
+    'claim_todo',
+    'FOR SUB-AGENTS: Register yourself AND claim a specific task in one call. Use this when you were spawned to work on a specific todo. This creates the task if it doesn\'t exist, then claims it for you.',
+    {
+      title: z.string().describe('The title of the todo/task you were spawned to work on'),
+      description: z.string().optional().default('').describe('Additional details about the task'),
+      priority: z
+        .enum(['low', 'normal', 'high', 'urgent'])
+        .optional()
+        .default('normal')
+        .describe('Priority level'),
+    },
+    async ({ title, description, priority }) => {
+      const db = getDatabase();
+
+      // Generate agent name
+      const agentName = `sub-${Date.now()}`;
+
+      // Register as sub-agent
+      const agent = db.createAgent({
+        name: agentName,
+        role: AgentRole.SUB,
+        capabilities: ['code'],
+        status: AgentStatus.BUSY, // Already working
+      });
+      setCurrentAgent(agent.id, agent.name);
+
+      // Check if a task with this title already exists and is pending
+      const allTasks = db.listTasks();
+      let task = allTasks.find(
+        (t) =>
+          t.title.toLowerCase().trim() === title.toLowerCase().trim() &&
+          ['pending', 'assigned'].includes(t.status)
+      );
+
+      if (task) {
+        // Claim the existing task
+        task = db.updateTask(task.id, {
+          assignedTo: agent.id,
+          status: TaskStatus.IN_PROGRESS,
+        })!;
+      } else {
+        // Create a new task and claim it
+        task = db.createTask({
+          title,
+          description,
+          priority: priority as TaskPriority,
+          status: TaskStatus.IN_PROGRESS,
+          assignedTo: agent.id,
+          createdBy: agent.id,
+          startedAt: new Date(),
+        });
+      }
+
+      // Sync context
+      syncToActiveContext();
+
+      const lines: string[] = [
+        '# Task Claimed',
+        '',
+        `**You are**: ${agent.name} (\`${agent.id}\`)`,
+        `**Working on**: ${task.title}`,
+        `**Task ID**: \`${task.id}\``,
+        '',
+        '---',
+        '',
+        'Now you can start working. Remember to:',
+        '1. `lock_acquire` on any files you edit',
+        '2. `task_update` to report progress',
+        '3. `task_complete` when done',
+        '4. `agent_unregister` when finished',
+      ];
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+}