agent-orchestration 0.5.0

package/src/index.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Agent Orchestration Server
+ * 
+ * A Model Context Protocol server that enables multiple AI agents to share
+ * memory, coordinate tasks, and collaborate effectively across IDEs and CLI tools.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getDatabase, closeDatabase } from './database.js';
+import {
+  registerAgentTools,
+  registerMemoryTools,
+  registerTaskTools,
+  registerCoordinationTools,
+  registerUtilityTools,
+} from './tools/index.js';
+
+// Create server instance
+const server = new McpServer({
+  name: 'agent-orchestration',
+  version: '0.5.0',
+});
+
+// Register all tools
+registerAgentTools(server);
+registerMemoryTools(server);
+registerTaskTools(server);
+registerCoordinationTools(server);
+registerUtilityTools(server);
+
+/**
+ * Start the MCP server
+ */
+export async function startServer(): Promise<void> {
+  // Initialize database
+  const db = getDatabase();
+  console.error(`Agent Orchestration server started. Database: ${db.dbPath}`);
+
+  // Create stdio transport
+  const transport = new StdioServerTransport();
+
+  // Handle shutdown
+  process.on('SIGINT', () => {
+    console.error('Shutting down...');
+    closeDatabase();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    console.error('Shutting down...');
+    closeDatabase();
+    process.exit(0);
+  });
+
+  // Connect and run
+  await server.connect(transport);
+}
+
+// Auto-run when executed directly (node dist/index.js)
+// Check if this file is the main module being run
+const isMainModule = process.argv[1]?.endsWith('index.js') && !process.argv[1]?.includes('cli.js');
+
+if (isMainModule) {
+  startServer().catch((error) => {
+    console.error('Fatal error:', error);
+    closeDatabase();
+    process.exit(1);
+  });
+}

package/src/models.ts

@@ -0,0 +1,226 @@
+/**
+ * Type definitions for MCP Memory Orchestrator
+ */
+
+import { ulid } from 'ulid';
+
+// ==================== Enums ====================
+
+export enum AgentRole {
+  MAIN = 'main',
+  SUB = 'sub',
+}
+
+export enum AgentStatus {
+  ACTIVE = 'active',
+  IDLE = 'idle',
+  BUSY = 'busy',
+  OFFLINE = 'offline',
+}
+
+export enum TaskStatus {
+  PENDING = 'pending',
+  ASSIGNED = 'assigned',
+  IN_PROGRESS = 'in_progress',
+  COMPLETED = 'completed',
+  FAILED = 'failed',
+  CANCELLED = 'cancelled',
+}
+
+export enum TaskPriority {
+  LOW = 'low',
+  NORMAL = 'normal',
+  HIGH = 'high',
+  URGENT = 'urgent',
+}
+
+export enum EventType {
+  AGENT_REGISTERED = 'agent_registered',
+  AGENT_UNREGISTERED = 'agent_unregistered',
+  AGENT_HEARTBEAT = 'agent_heartbeat',
+  TASK_CREATED = 'task_created',
+  TASK_ASSIGNED = 'task_assigned',
+  TASK_CLAIMED = 'task_claimed',
+  TASK_UPDATED = 'task_updated',
+  TASK_COMPLETED = 'task_completed',
+  MEMORY_SET = 'memory_set',
+  MEMORY_DELETE = 'memory_delete',
+  LOCK_ACQUIRED = 'lock_acquired',
+  LOCK_RELEASED = 'lock_released',
+}
+
+// ==================== Core Types ====================
+
+export interface Agent {
+  id: string;
+  name: string;
+  role: AgentRole;
+  status: AgentStatus;
+  capabilities: string[];
+  metadata: Record<string, unknown>;
+  registeredAt: Date;
+  lastHeartbeat: Date;
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  priority: TaskPriority;
+  createdBy: string | null;
+  assignedTo: string | null;
+  dependencies: string[];
+  metadata: Record<string, unknown>;
+  output: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+  startedAt: Date | null;
+  completedAt: Date | null;
+}
+
+export interface MemoryEntry {
+  id: string;
+  key: string;
+  value: unknown;
+  namespace: string;
+  createdBy: string | null;
+  ttlSeconds: number | null;
+  createdAt: Date;
+  updatedAt: Date;
+  expiresAt: Date | null;
+}
+
+export interface Lock {
+  id: string;
+  resource: string;
+  heldBy: string;
+  acquiredAt: Date;
+  expiresAt: Date | null;
+  metadata: Record<string, unknown>;
+}
+
+export interface Event {
+  id: string;
+  eventType: EventType;
+  agentId: string | null;
+  resourceId: string | null;
+  details: Record<string, unknown>;
+  timestamp: Date;
+}
+
+// ==================== Factory Functions ====================
+
+export function createAgent(params: {
+  name: string;
+  role?: AgentRole;
+  capabilities?: string[];
+  status?: AgentStatus;
+  metadata?: Record<string, unknown>;
+}): Agent {
+  const now = new Date();
+  return {
+    id: ulid(),
+    name: params.name,
+    role: params.role ?? AgentRole.SUB,
+    status: params.status ?? AgentStatus.IDLE,
+    capabilities: params.capabilities ?? [],
+    metadata: params.metadata ?? {},
+    registeredAt: now,
+    lastHeartbeat: now,
+  };
+}
+
+export function createTask(params: {
+  title: string;
+  description?: string;
+  priority?: TaskPriority;
+  createdBy?: string | null;
+  assignedTo?: string | null;
+  dependencies?: string[];
+  metadata?: Record<string, unknown>;
+  status?: TaskStatus;
+  startedAt?: Date | null;
+}): Task {
+  const now = new Date();
+  return {
+    id: ulid(),
+    title: params.title,
+    description: params.description ?? '',
+    status: params.status ?? TaskStatus.PENDING,
+    priority: params.priority ?? TaskPriority.NORMAL,
+    createdBy: params.createdBy ?? null,
+    assignedTo: params.assignedTo ?? null,
+    dependencies: params.dependencies ?? [],
+    metadata: params.metadata ?? {},
+    output: null,
+    createdAt: now,
+    updatedAt: now,
+    startedAt: params.startedAt ?? null,
+    completedAt: null,
+  };
+}
+
+export function createMemoryEntry(params: {
+  key: string;
+  value: unknown;
+  namespace?: string;
+  createdBy?: string | null;
+  ttlSeconds?: number | null;
+}): MemoryEntry {
+  const now = new Date();
+  let expiresAt: Date | null = null;
+
+  if (params.ttlSeconds) {
+    expiresAt = new Date(now.getTime() + params.ttlSeconds * 1000);
+  }
+
+  return {
+    id: ulid(),
+    key: params.key,
+    value: params.value,
+    namespace: params.namespace ?? 'default',
+    createdBy: params.createdBy ?? null,
+    ttlSeconds: params.ttlSeconds ?? null,
+    createdAt: now,
+    updatedAt: now,
+    expiresAt,
+  };
+}
+
+export function createLock(params: {
+  resource: string;
+  heldBy: string;
+  timeoutSeconds?: number;
+  metadata?: Record<string, unknown>;
+}): Lock {
+  const now = new Date();
+  const expiresAt = params.timeoutSeconds
+    ? new Date(now.getTime() + params.timeoutSeconds * 1000)
+    : null;
+
+  return {
+    id: ulid(),
+    resource: params.resource,
+    heldBy: params.heldBy,
+    acquiredAt: now,
+    expiresAt,
+    metadata: params.metadata ?? {},
+  };
+}
+
+export function createEvent(params: {
+  eventType: EventType;
+  agentId?: string | null;
+  resourceId?: string | null;
+  details?: Record<string, unknown>;
+}): Event {
+  return {
+    id: ulid(),
+    eventType: params.eventType,
+    agentId: params.agentId ?? null,
+    resourceId: params.resourceId ?? null,
+    details: params.details ?? {},
+    timestamp: new Date(),
+  };
+}

package/src/tools/agent.ts

@@ -0,0 +1,241 @@
+/**
+ * Agent management tools
+ */
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getDatabase } from '../database.js';
+import { AgentRole, AgentStatus } from '../models.js';
+
+// Current agent state (per server instance)
+let currentAgentId: string | null = null;
+let currentAgentName: string | null = null;
+
+export function getCurrentAgentId(): string | null {
+  return currentAgentId;
+}
+
+export function getCurrentAgentName(): string | null {
+  return currentAgentName;
+}
+
+export function setCurrentAgent(id: string, name: string): void {
+  currentAgentId = id;
+  currentAgentName = name;
+}
+
+export function clearCurrentAgent(): void {
+  currentAgentId = null;
+  currentAgentName = null;
+}
+
+export function registerAgentTools(server: McpServer): void {
+  // agent_register
+  server.tool(
+    'agent_register',
+    'Register this agent with the orchestration system. Call this at the start of your session.',
+    {
+      name: z.string().describe('A unique name for this agent'),
+      role: z.enum(['main', 'sub']).optional().default('sub').describe('Agent role'),
+      capabilities: z
+        .array(z.string())
+        .optional()
+        .default(['code'])
+        .describe('List of capabilities'),
+    },
+    async ({ name, role, capabilities }) => {
+      const db = getDatabase();
+
+      // Check if agent with this name already exists
+      const existing = db.getAgentByName(name);
+      if (existing) {
+        // Reconnect to existing agent
+        setCurrentAgent(existing.id, existing.name);
+        db.updateAgentHeartbeat(existing.id, AgentStatus.ACTIVE);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Reconnected as '${existing.name}' (${existing.id})`,
+            },
+          ],
+        };
+      }
+
+      const agent = db.createAgent({
+        name,
+        role: role === 'main' ? AgentRole.MAIN : AgentRole.SUB,
+        capabilities,
+        status: AgentStatus.ACTIVE,
+      });
+
+      setCurrentAgent(agent.id, agent.name);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Registered as '${agent.name}' (${agent.id})`,
+          },
+        ],
+      };
+    }
+  );
+
+  // agent_heartbeat
+  server.tool(
+    'agent_heartbeat',
+    'Send a heartbeat to indicate agent is still active. Call periodically during long operations.',
+    {
+      status: z
+        .enum(['active', 'idle', 'busy'])
+        .optional()
+        .describe('Current status (active, idle, busy)'),
+    },
+    async ({ status }) => {
+      if (!currentAgentId) {
+        return {
+          content: [{ type: 'text', text: 'Error: Not registered. Call agent_register first.' }],
+        };
+      }
+
+      const agentStatus = status
+        ? (status as AgentStatus)
+        : undefined;
+
+      const updated = getDatabase().updateAgentHeartbeat(currentAgentId, agentStatus);
+
+      if (updated) {
+        return {
+          content: [{ type: 'text', text: `Heartbeat recorded${status ? ` (${status})` : ''}.` }],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Error: Agent not found.' }],
+      };
+    }
+  );
+
+  // agent_list
+  server.tool(
+    'agent_list',
+    'List all registered agents in the orchestration system.',
+    {
+      status: z
+        .enum(['active', 'idle', 'busy', 'offline'])
+        .optional()
+        .describe('Filter by status'),
+      role: z.enum(['main', 'sub']).optional().describe('Filter by role'),
+    },
+    async ({ status, role }) => {
+      const db = getDatabase();
+
+      // Cleanup stale agents first
+      db.cleanupStaleAgents();
+
+      const agents = db.listAgents({
+        status: status as AgentStatus | undefined,
+        role: role === 'main' ? AgentRole.MAIN : role === 'sub' ? AgentRole.SUB : undefined,
+      });
+
+      if (agents.length === 0) {
+        return {
+          content: [{ type: 'text', text: 'No agents registered.' }],
+        };
+      }
+
+      const lines = ['# Registered Agents\n'];
+      for (const agent of agents) {
+        const isMe = agent.id === currentAgentId ? ' (you)' : '';
+        const statusEmoji = {
+          active: '🟢',
+          idle: '🟡',
+          busy: '🔵',
+          offline: '⚫',
+        }[agent.status];
+
+        lines.push(`${statusEmoji} **${agent.name}**${isMe} - ${agent.role}`);
+        lines.push(`   ID: \`${agent.id}\``);
+        lines.push(`   Capabilities: ${agent.capabilities.join(', ') || 'none'}`);
+        lines.push('');
+      }
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+
+  // agent_unregister
+  server.tool(
+    'agent_unregister',
+    'Unregister this agent and release all held locks. Call at the end of your session.',
+    {},
+    async () => {
+      if (!currentAgentId) {
+        return {
+          content: [{ type: 'text', text: 'Not registered.' }],
+        };
+      }
+
+      const db = getDatabase();
+      const deleted = db.deleteAgent(currentAgentId);
+
+      if (deleted) {
+        const name = currentAgentName;
+        clearCurrentAgent();
+        return {
+          content: [{ type: 'text', text: `Agent '${name}' unregistered. All locks released.` }],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Error: Could not unregister agent.' }],
+      };
+    }
+  );
+
+  // agent_whoami
+  server.tool(
+    'agent_whoami',
+    'Get information about your current agent identity.',
+    {},
+    async () => {
+      if (!currentAgentId) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'Not registered. Use `bootstrap` or `agent_register` to register.',
+            },
+          ],
+        };
+      }
+
+      const agent = getDatabase().getAgent(currentAgentId);
+      if (!agent) {
+        clearCurrentAgent();
+        return {
+          content: [{ type: 'text', text: 'Agent not found in database. Registration expired.' }],
+        };
+      }
+
+      const lines = [
+        '# Your Agent Info',
+        '',
+        `**Name**: ${agent.name}`,
+        `**ID**: \`${agent.id}\``,
+        `**Role**: ${agent.role}`,
+        `**Status**: ${agent.status}`,
+        `**Capabilities**: ${agent.capabilities.join(', ') || 'none'}`,
+        `**Registered**: ${agent.registeredAt.toISOString()}`,
+        `**Last Heartbeat**: ${agent.lastHeartbeat.toISOString()}`,
+      ];
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+}

package/src/tools/coordination.ts

@@ -0,0 +1,152 @@
+/**
+ * Coordination tools (locks and status)
+ */
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getDatabase } from '../database.js';
+import { TaskStatus } from '../models.js';
+import { getCurrentAgentId } from './agent.js';
+
+export function registerCoordinationTools(server: McpServer): void {
+  // lock_acquire
+  server.tool(
+    'lock_acquire',
+    'Acquire a lock on a resource to prevent concurrent access.',
+    {
+      resource: z.string().describe("The resource to lock (file path, 'namespace:key', etc.)"),
+      timeout_seconds: z
+        .number()
+        .optional()
+        .default(300)
+        .describe('Lock timeout. Auto-releases after this time.'),
+      reason: z.string().optional().describe('Why you need this lock'),
+    },
+    async ({ resource, timeout_seconds, reason }) => {
+      const agentId = getCurrentAgentId();
+      if (!agentId) {
+        return {
+          content: [{ type: 'text', text: 'Error: Not registered.' }],
+        };
+      }
+
+      const db = getDatabase();
+
+      // Check if already locked
+      const existing = db.checkLock(resource);
+      if (existing) {
+        if (existing.heldBy === agentId) {
+          return {
+            content: [{ type: 'text', text: 'You already hold this lock.' }],
+          };
+        }
+        return {
+          content: [{ type: 'text', text: `Lock denied: held by ${existing.heldBy}` }],
+        };
+      }
+
+      const lock = db.acquireLock({
+        resource,
+        heldBy: agentId,
+        timeoutSeconds: timeout_seconds,
+        metadata: { reason: reason ?? '' },
+      });
+
+      if (lock) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Lock acquired on '${resource}' (expires in ${timeout_seconds}s)`,
+            },
+          ],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Failed to acquire lock.' }],
+      };
+    }
+  );
+
+  // lock_release
+  server.tool(
+    'lock_release',
+    'Release a lock you are holding.',
+    {
+      resource: z.string().describe('The resource to unlock'),
+    },
+    async ({ resource }) => {
+      const agentId = getCurrentAgentId();
+      if (!agentId) {
+        return {
+          content: [{ type: 'text', text: 'Error: Not registered.' }],
+        };
+      }
+
+      const released = getDatabase().releaseLock(resource, agentId);
+
+      if (released) {
+        return {
+          content: [{ type: 'text', text: 'Lock released.' }],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Could not release lock. You may not hold it.' }],
+      };
+    }
+  );
+
+  // lock_check
+  server.tool(
+    'lock_check',
+    'Check if a resource is currently locked.',
+    {
+      resource: z.string().describe('The resource to check'),
+    },
+    async ({ resource }) => {
+      const agentId = getCurrentAgentId();
+      const lock = getDatabase().checkLock(resource);
+
+      if (lock) {
+        const isYou = lock.heldBy === agentId ? ' (you)' : '';
+        return {
+          content: [{ type: 'text', text: `Locked by ${lock.heldBy}${isYou}` }],
+        };
+      }
+
+      return {
+        content: [{ type: 'text', text: 'Not locked.' }],
+      };
+    }
+  );
+
+  // coordination_status
+  server.tool(
+    'coordination_status',
+    'Get overall coordination status: active agents, pending tasks, held locks.',
+    {},
+    async () => {
+      const db = getDatabase();
+
+      const agents = db.listAgents();
+      const active = agents.filter((a) => ['active', 'busy'].includes(a.status));
+      const pending = db.listTasks({ status: TaskStatus.PENDING });
+      const inProgress = db.listTasks({ status: TaskStatus.IN_PROGRESS });
+      const stats = db.getStats();
+
+      const lines = [
+        '# Coordination Status\n',
+        `**Agents**: ${active.length} active / ${agents.length} total`,
+        `**Tasks**: ${pending.length} pending, ${inProgress.length} in progress`,
+        `**Locks**: ${stats.locks} active`,
+        `**Memory**: ${stats.memory} entries`,
+      ];
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+      };
+    }
+  );
+}

package/src/tools/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Tool registration index
+ */
+
+export { registerAgentTools, getCurrentAgentId, getCurrentAgentName, setCurrentAgent, clearCurrentAgent } from './agent.js';
+export { registerMemoryTools } from './memory.js';
+export { registerTaskTools } from './task.js';
+export { registerCoordinationTools } from './coordination.js';
+export { registerUtilityTools } from './utility.js';