SwarmProtocol

import { SwarmProtocol, Timeline, CortexIO } from '@codmir/cortex';

new SwarmProtocol(io: CortexIO, timeline: Timeline)

const io = new CortexIO('/home/dev/my-project');
await io.init();
const timeline = new Timeline(io);
const swarm = new SwarmProtocol(io, timeline);

async create(opts: {
  task: string;
  coordinatorId: string;
  strategy: SwarmStrategy;
  maxAgents?: number;
  maxTokens?: number;
  maxCostUsd?: number;
  maxDurationMs?: number;
  mergePolicy?: Partial<MergePolicy>;
  decomposition: TaskNode;
}): Promise<SwarmManifest>

const manifest = await swarm.create({
  task: 'Build authentication system',
  coordinatorId: 'coordinator_1',
  strategy: 'hierarchical',
  maxAgents: 100,
  maxCostUsd: 10,
  decomposition: SwarmProtocol.decompose(
    'Build authentication system',
    [
      'Implement JWT token generation',
      'Build login/register endpoints',
      'Add threat detection middleware',
      'Write integration tests',
    ],
    'parallel'
  ),
});

async getSwarm(): Promise<SwarmManifest | null>

async disband(): Promise<void>

async recruit(
  agentId: string,
  role: string,
  expertise: string[]
): Promise<SwarmAgent>

const agent = await swarm.recruit('agent_1', 'backend', ['TypeScript', 'NestJS', 'auth']);
console.log(agent.status); // 'idle'

async assign(agentId: string, taskId: string): Promise<void>

await swarm.assign('agent_1', manifest.decomposition.children[0].id);

async complete(
  agentId: string,
  taskId: string,
  tokensUsed: number,
  costUsd: number,
  output?: unknown
): Promise<void>

await swarm.complete('agent_1', taskId, 15000, 0.045, {
  files: ['src/auth/jwt.ts'],
  summary: 'JWT generation with RS256 signing',
});

async fail(agentId: string, taskId: string, reason: string): Promise<void>

await swarm.fail('agent_2', taskId, 'Rate limited by OpenAI API after 50 requests');

async lock(
  agentId: string,
  path: string,
  type?: 'exclusive' | 'shared',
  ttlMs?: number
): Promise<SwarmLock>

const lock = await swarm.lock('agent_1', 'src/auth/jwt.ts');
// ... edit the file ...
await swarm.unlock('agent_1', 'src/auth/jwt.ts');

async unlock(agentId: string, path: string): Promise<void>

async isLocked(path: string): Promise<SwarmLock | null>

async isOverBudget(): Promise<{ over: boolean; details: string[] }>

const budget = await swarm.isOverBudget();
if (budget.over) {
  console.log('Budget exceeded:', budget.details);
  // ['Cost: $10.50/$10.00', 'Tokens: 105000000/100000000']
}

async progress(): Promise<{
  total: number;
  done: number;
  active: number;
  failed: number;
  pending: number;
  percent: number;
}>

const p = await swarm.progress();
console.log(`${p.percent}% complete (${p.done}/${p.total} tasks)`);

static createTask(
  description: string,
  opts?: Partial<TaskNode>
): TaskNode

const task = SwarmProtocol.createTask('Implement rate limiting', {
  priority: 8,
  estimatedTokens: 5000,
});

static decompose(
  root: string,
  subtasks: string[],
  strategy?: 'parallel' | 'sequential'
): TaskNode

// Parallel decomposition — all subtasks can run simultaneously
const parallel = SwarmProtocol.decompose(
  'Build REST API',
  ['Users CRUD', 'Projects CRUD', 'Auth endpoints', 'Webhook handlers'],
  'parallel'
);

// Sequential decomposition — each subtask depends on the previous
const sequential = SwarmProtocol.decompose(
  'Database migration',
  ['Create schema', 'Seed data', 'Run migration', 'Verify integrity'],
  'sequential'
);

interface SwarmManifest {
  id: string;
  task: string;
  created: number;
  coordinator: string;
  strategy: SwarmStrategy;
  agents: SwarmAgent[];
  locks: SwarmLock[];
  decomposition: TaskNode;
  mergePolicy: MergePolicy;
  budget: SwarmBudget;
}

type SwarmStrategy =
  | 'parallel'       // all agents work independently, merge at end
  | 'pipeline'       // sequential, each agent's output feeds the next
  | 'hierarchical'   // queen delegates to workers
  | 'consensus'      // agents vote on approach before executing
  | 'competitive';   // multiple agents solve same task, best wins

interface SwarmAgent {
  id: string;
  role: string;
  expertise: string[];
  assignedTasks: string[];
  status: 'idle' | 'working' | 'blocked' | 'done' | 'failed';
  startedAt?: number;
  completedAt?: number;
  tokensUsed: number;
  costUsd: number;
}

interface TaskNode {
  id: string;
  description: string;
  assignedTo?: string;
  status: 'pending' | 'active' | 'done' | 'failed' | 'skipped';
  priority: number;
  estimatedTokens: number;
  actualTokens?: number;
  dependencies: string[];
  children: TaskNode[];
  output?: unknown;
}

interface SwarmBudget {
  maxAgents: number;
  maxTokens: number;
  maxCostUsd: number;
  maxDurationMs: number;
  spent: {
    agents: number;
    tokens: number;
    costUsd: number;
    durationMs: number;
  };
}

interface MergePolicy {
  strategy: 'auto' | 'voting' | 'coordinator_review' | 'human_review';
  conflictResolution: 'last_write' | 'highest_confidence' | 'coordinator_decides' | 'vote';
  minAgreePercent?: number;
  requireHumanApproval: boolean;
}

interface SwarmLock {
  path: string;
  agentId: string;
  type: 'exclusive' | 'shared';
  acquiredAt: number;
  expiresAt: number;
  reason: string;
}

import { CortexIO, Timeline, SwarmProtocol } from '@codmir/cortex';

const io = new CortexIO('/home/dev/my-project');
await io.init();
const timeline = new Timeline(io);
const swarm = new SwarmProtocol(io, timeline);

// Create a swarm for a feature build
const manifest = await swarm.create({
  task: 'Build real-time collaboration feature',
  coordinatorId: 'queen',
  strategy: 'hierarchical',
  maxAgents: 100,
  maxTokens: 50_000_000,
  maxCostUsd: 25,
  decomposition: SwarmProtocol.decompose(
    'Real-time collaboration',
    [
      'WebSocket gateway with rooms',
      'Presence tracking service',
      'Conflict resolution (CRDT)',
      'UI cursors and selections',
      'Integration tests',
    ],
    'parallel'
  ),
  mergePolicy: {
    strategy: 'coordinator_review',
    conflictResolution: 'coordinator_decides',
    requireHumanApproval: false,
  },
});

// Recruit agents
await swarm.recruit('agent_ws', 'backend', ['WebSocket', 'NestJS']);
await swarm.recruit('agent_crdt', 'backend', ['CRDT', 'distributed-systems']);
await swarm.recruit('agent_ui', 'frontend', ['React', 'Canvas']);
await swarm.recruit('agent_test', 'qa', ['Jest', 'Playwright']);

// Assign tasks
const tasks = manifest.decomposition.children;
await swarm.assign('agent_ws', tasks[0].id);
await swarm.assign('agent_ws', tasks[1].id);
await swarm.assign('agent_crdt', tasks[2].id);
await swarm.assign('agent_ui', tasks[3].id);
await swarm.assign('agent_test', tasks[4].id);

// Lock files before editing
await swarm.lock('agent_ws', 'apps/server/src/gateways/collab.gateway.ts');

// Complete a task
await swarm.complete('agent_ws', tasks[0].id, 25000, 0.075, {
  files: ['apps/server/src/gateways/collab.gateway.ts'],
});

// Check progress
const progress = await swarm.progress();
console.log(`${progress.percent}% complete`);

// Check budget
const budget = await swarm.isOverBudget();
if (budget.over) {
  console.log('Over budget:', budget.details);
  await swarm.disband();
}