@girardmedia/bootspring 2.0.21 → 2.0.22

package/src/intelligence/agent-collab.ts

@@ -0,0 +1,2376 @@
+/**
+ * Bootspring Agent Collaboration Framework
+ *
+ * Enables multi-agent task delegation with handoff protocol.
+ * Allows agents to collaborate on complex tasks by delegating
+ * subtasks to specialized agents.
+ *
+ * @package bootspring
+ * @module intelligence/agent-collab
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Telemetry module (JavaScript)
+const telemetry = require('../../core/telemetry') as {
+  emitEvent: (event: string, payload?: Record<string, unknown>, options?: Record<string, unknown>) => void;
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type TaskPriorityValue = 'critical' | 'high' | 'medium' | 'low';
+export type TaskStatusValue = 'pending' | 'in_progress' | 'blocked' | 'complete' | 'failed';
+export type HandoffStatusValue = 'pending' | 'accepted' | 'rejected' | 'completed';
+export type AgentRoleValue = 'primary' | 'supporting' | 'specialist';
+
+export interface AgentParticipant {
+  role: AgentRoleValue;
+  joinedAt: string;
+  tasksAssigned: number;
+  tasksCompleted: number;
+  status: 'active' | 'standby' | 'working';
+}
+
+export interface ProgressNote {
+  note: string;
+  timestamp: string;
+}
+
+export interface Artifact {
+  id?: string | undefined;
+  name: string;
+  type: string;
+  content?: unknown | undefined;
+  description?: string | undefined;
+  fromAgent?: string | undefined;
+  subtaskId?: string | undefined;
+  addedAt?: string | undefined;
+  sharedAt?: string | undefined;
+}
+
+export interface SubtaskResult {
+  output?: unknown | undefined;
+  success: boolean;
+  duration?: number | null | undefined;
+}
+
+export interface SubtaskFailure {
+  reason: string;
+  canRetry: boolean;
+  suggestedAction?: string | null | undefined;
+  failedAt: string;
+}
+
+export interface TransferHistoryEntry {
+  from: string;
+  to: string;
+  handoffId: string;
+  timestamp: string;
+}
+
+export interface Subtask {
+  id: string;
+  title: string;
+  description?: string | undefined;
+  delegatedTo: string;
+  delegatedBy: string;
+  context: Record<string, unknown>;
+  priority: TaskPriorityValue;
+  dependencies: string[];
+  unmetDependencies: string[];
+  expectedDuration?: number | null | undefined;
+  acceptanceCriteria: string[];
+  artifacts: Artifact[];
+  status: TaskStatusValue;
+  createdAt: string;
+  startedAt?: string | null | undefined;
+  completedAt?: string | null | undefined;
+  result?: SubtaskResult | null | undefined;
+  failure?: SubtaskFailure | undefined;
+  feedback?: unknown | undefined;
+  retryCount: number;
+  progress?: number | undefined;
+  progressNotes?: ProgressNote[] | undefined;
+  blockedReason?: string | undefined;
+  reassignedFrom?: string | undefined;
+  transferHistory?: TransferHistoryEntry[] | undefined;
+}
+
+export interface SessionContext {
+  initial: Record<string, unknown>;
+  current: Record<string, unknown>;
+  history: Array<{
+    update: Record<string, unknown>;
+    source: string;
+    timestamp: string;
+  }>;
+}
+
+export interface SessionMetrics {
+  startTime: number;
+  handoffCount: number;
+  delegationCount: number;
+  blockedTime: number;
+}
+
+export interface Handoff {
+  id: string;
+  fromAgent: string;
+  toAgent: string;
+  reason: string;
+  context: Record<string, unknown>;
+  artifacts: Artifact[];
+  transferPrimaryRole: boolean;
+  subtaskId?: string | null | undefined;
+  urgency: 'low' | 'normal' | 'high' | 'critical';
+  expectedDuration?: number | null | undefined;
+  status: HandoffStatusValue;
+  requestedAt: string;
+  acceptedAt?: string | null | undefined;
+  completedAt?: string | null | undefined;
+  rejectionReason?: string | null | undefined;
+  rejectedAt?: string | undefined;
+  acknowledgment?: string | null | undefined;
+  estimatedCompletion?: string | null | undefined;
+  result?: Record<string, unknown> | undefined;
+}
+
+export interface Checkpoint {
+  id: string;
+  description: string;
+  createdAt: string;
+  snapshot: {
+    subtasks: Subtask[];
+    context: SessionContext;
+    results: Record<string, unknown>;
+    artifacts: Artifact[];
+    primaryAgent: string;
+  };
+}
+
+export interface Learning {
+  content: unknown;
+  subtaskId: string;
+  agent: string;
+  timestamp: string;
+}
+
+export interface Broadcast {
+  id: string;
+  type: string;
+  content: unknown;
+  fromAgent: string;
+  priority: string;
+  timestamp: string;
+  recipients: string[];
+}
+
+export interface SessionSummary {
+  task: string;
+  primaryAgent: string;
+  subtasksCompleted: number;
+  subtasksFailed: number;
+  totalSubtasks: number;
+  handoffsCount: number;
+  acceptedHandoffs: number;
+  rejectedHandoffs: number;
+  duration: number;
+  durationFormatted: string;
+  artifactsCount: number;
+  agentParticipation: Array<{
+    agent: string;
+    role: AgentRoleValue;
+    tasksAssigned: number;
+    tasksCompleted: number;
+  }>;
+  learnings: Learning[];
+  checkpointsCount: number;
+  successRate: number;
+}
+
+export interface CollabSession {
+  id: string;
+  task: string;
+  primaryAgent: string;
+  supportingAgents: string[];
+  agentParticipants: Record<string, AgentParticipant>;
+  status: 'active' | 'complete' | 'aborted';
+  createdAt: string;
+  parentSessionId?: string | null | undefined;
+  subtasks: Subtask[];
+  taskQueue: Subtask[];
+  handoffs: Handoff[];
+  results: Record<string, unknown>;
+  artifacts: Artifact[];
+  context: SessionContext;
+  checkpoints: Checkpoint[];
+  metrics: SessionMetrics;
+  broadcasts?: Broadcast[] | undefined;
+  learnings?: Learning[] | undefined;
+  completedAt?: string | undefined;
+  abortedAt?: string | undefined;
+  abortReason?: string | undefined;
+  summary?: SessionSummary | undefined;
+}
+
+export interface TaskQueueItem {
+  sessionId: string;
+  subtaskId: string;
+  priority: TaskPriorityValue;
+  createdAt: string;
+}
+
+export interface BlockedTask {
+  sessionId: string;
+  subtaskId: string;
+  dependencies?: string[] | undefined;
+  reason?: string | undefined;
+  blockedAt?: string | undefined;
+}
+
+export interface CollabMetrics {
+  totalSessions: number;
+  successfulSessions: number;
+  totalHandoffs: number;
+  totalSubtasks: number;
+  avgSessionDuration: number;
+}
+
+export interface HistoryEntry {
+  action: string;
+  sessionId?: string | undefined;
+  subtaskId?: string | undefined;
+  handoffId?: string | undefined;
+  checkpointId?: string | undefined;
+  broadcastId?: string | undefined;
+  artifactId?: string | undefined;
+  agent?: string | undefined;
+  fromAgent?: string | undefined;
+  toAgent?: string | undefined;
+  from?: string | undefined;
+  to?: string | undefined;
+  byAgent?: string | undefined;
+  primaryAgent?: string | undefined;
+  supportingAgents?: string[] | undefined;
+  parentSessionId?: string | null | undefined;
+  transferPrimaryRole?: boolean | undefined;
+  previousPrimary?: string | null | undefined;
+  priority?: TaskPriorityValue | undefined;
+  hasDepedencies?: boolean | undefined;
+  success?: boolean | undefined;
+  reason?: string | undefined;
+  canRetry?: boolean | undefined;
+  retryCount?: number | undefined;
+  reassignedTo?: string | null | undefined;
+  urgency?: string | undefined;
+  description?: string | undefined;
+  name?: string | undefined;
+  type?: string | undefined;
+  recipientCount?: number | undefined;
+  unblockedTasks?: string[] | undefined;
+  duration?: number | undefined;
+  successRate?: number | undefined;
+  timestamp: string;
+}
+
+export interface PendingHandoffItem extends Handoff {
+  sessionId: string;
+  handoffId: string;
+}
+
+export interface CollabState {
+  activeSessions: Record<string, CollabSession>;
+  pendingHandoffs: PendingHandoffItem[];
+  completedSessions: CollabSession[];
+  taskQueues: Record<string, TaskQueueItem[]>;
+  agentStates: Record<string, unknown>;
+  blockedTasks: BlockedTask[];
+  history: HistoryEntry[];
+  metrics: CollabMetrics;
+  lastUpdated?: string | undefined;
+}
+
+export interface SubtaskTemplate {
+  title: string;
+  delegatedTo: string;
+  priority: TaskPriorityValue;
+  dependencies?: string[] | undefined;
+}
+
+export interface CollabPattern {
+  name: string;
+  description: string;
+  primaryAgent: string;
+  supportingAgents: string[];
+  subtaskTemplate: SubtaskTemplate[];
+}
+
+export interface OperationResult {
+  success: boolean;
+  error?: string | undefined;
+  message?: string | undefined;
+}
+
+export interface StartSessionOptions {
+  task: string;
+  primaryAgent: string;
+  supportingAgents?: string[] | undefined;
+  context?: Record<string, unknown> | undefined;
+  parentSessionId?: string | null | undefined;
+}
+
+export interface StartSessionResult extends OperationResult {
+  sessionId?: string | undefined;
+  session?: CollabSession | undefined;
+}
+
+export interface DelegateTaskInput {
+  title: string;
+  description?: string | undefined;
+  delegatedTo: string;
+  delegatedBy?: string | undefined;
+  context?: Record<string, unknown> | undefined;
+  priority?: TaskPriorityValue | undefined;
+  dependencies?: string[] | undefined;
+  expectedDuration?: number | null | undefined;
+  acceptanceCriteria?: string[] | undefined;
+  artifacts?: Artifact[] | undefined;
+}
+
+export interface DelegateTaskResult extends OperationResult {
+  sessionId?: string | undefined;
+  subtaskId?: string | undefined;
+  subtask?: Subtask | undefined;
+  isBlocked?: boolean | undefined;
+}
+
+export interface SubtaskOperationResult extends OperationResult {
+  sessionId?: string | undefined;
+  subtaskId?: string | undefined;
+  subtask?: Subtask | undefined;
+}
+
+export interface CompleteSubtaskInput {
+  output?: unknown | undefined;
+  artifacts?: Artifact[] | undefined;
+  contextUpdates?: Record<string, unknown> | undefined;
+  learnings?: unknown[] | undefined;
+  success?: boolean | undefined;
+}
+
+export interface CompleteSubtaskResult extends OperationResult {
+  sessionId?: string | undefined;
+  subtaskId?: string | undefined;
+  taskSuccess?: boolean | undefined;
+  allSubtasksComplete?: boolean | undefined;
+  allSubtasksSuccessful?: boolean | undefined;
+  unblockedTasks?: string[] | undefined;
+}
+
+export interface FailSubtaskInput {
+  reason: string;
+  canRetry?: boolean | undefined;
+  suggestedAction?: string | null | undefined;
+}
+
+export interface FailSubtaskResult extends OperationResult {
+  sessionId?: string | undefined;
+  subtaskId?: string | undefined;
+  canRetry?: boolean | undefined;
+  suggestedAction?: string | null | undefined;
+}
+
+export interface RetryOptions {
+  reassignTo?: string | undefined;
+  additionalContext?: Record<string, unknown> | undefined;
+}
+
+export interface RetryResult extends OperationResult {
+  sessionId?: string | undefined;
+  subtaskId?: string | undefined;
+  retryCount?: number | undefined;
+}
+
+export interface RequestHandoffInput {
+  fromAgent: string;
+  toAgent: string;
+  reason: string;
+  context?: Record<string, unknown> | undefined;
+  artifacts?: Artifact[] | undefined;
+  transferPrimaryRole?: boolean | undefined;
+  subtaskId?: string | null | undefined;
+  urgency?: 'low' | 'normal' | 'high' | 'critical' | undefined;
+  expectedDuration?: number | null | undefined;
+}
+
+export interface HandoffResult extends OperationResult {
+  sessionId?: string | undefined;
+  handoffId?: string | undefined;
+  handoff?: Handoff | undefined;
+  newPrimaryAgent?: string | undefined;
+  transferredSubtask?: string | null | undefined;
+  context?: Record<string, unknown> | undefined;
+  rejectionReason?: string | undefined;
+}
+
+export interface AcceptHandoffOptions {
+  acknowledgment?: string | null | undefined;
+  estimatedCompletion?: string | null | undefined;
+}
+
+export interface CheckpointResult extends OperationResult {
+  sessionId?: string | undefined;
+  checkpointId?: string | undefined;
+}
+
+export interface SessionStatusResult {
+  found: boolean;
+  session?: Partial<CollabSession> | undefined;
+  isActive?: boolean | undefined;
+  summary?: SessionSummary | undefined;
+  progress?: {
+    subtasks: {
+      pending: number;
+      inProgress: number;
+      blocked: number;
+      completed: number;
+      failed: number;
+      total: number;
+      percent: number;
+    };
+    handoffs: {
+      pending: number;
+      total: number;
+      accepted: number;
+    };
+    artifacts: number;
+    checkpoints: number;
+  } | undefined;
+  agents?: Array<{
+    agent: string;
+    role: AgentRoleValue;
+    status: string;
+    tasksAssigned: number;
+    tasksCompleted: number;
+  }> | undefined;
+  timing?: {
+    elapsed: number;
+    elapsedFormatted: string;
+  } | undefined;
+  nextActions?: NextAction[] | undefined;
+}
+
+export interface NextAction {
+  type: string;
+  urgency: 'low' | 'medium' | 'high';
+  count?: number | undefined;
+  message: string;
+}
+
+export interface NextTaskResult {
+  hasTask: boolean;
+  blocked?: boolean | undefined;
+  sessionId?: string | undefined;
+  subtask?: Subtask | undefined;
+  sessionContext?: Record<string, unknown> | undefined;
+  message: string;
+}
+
+export interface ActiveSessionInfo {
+  id: string;
+  task: string;
+  primaryAgent: string;
+  status: string;
+  subtaskCount: number;
+  createdAt: string;
+}
+
+export interface PatternInfo {
+  key: string;
+  name: string;
+  description: string;
+  primaryAgent: string;
+  supportingAgents: string[];
+  subtaskCount: number;
+}
+
+export interface StartFromPatternOptions {
+  context?: Record<string, unknown> | undefined;
+  autoStart?: boolean | undefined;
+}
+
+export interface StartFromPatternResult extends OperationResult {
+  sessionId?: string | undefined;
+  pattern?: string | undefined;
+  patternName?: string | undefined;
+  primaryAgent?: string | undefined;
+  subtasks?: Array<{
+    id?: string | undefined;
+    title?: string | undefined;
+    delegatedTo?: string | undefined;
+    status?: TaskStatusValue | undefined;
+  }> | undefined;
+  availablePatterns?: string[] | undefined;
+}
+
+export interface CollabStats {
+  activeSessions: number;
+  completedSessions: number;
+  totalSessions: number;
+  successfulSessions: number;
+  totalSubtasks: number;
+  totalHandoffs: number;
+  activeSubtasks: number;
+  pendingHandoffs: number;
+  avgSessionDuration: number;
+  avgSessionDurationFormatted: string;
+  blockedTasks: number;
+}
+
+export interface BroadcastInput {
+  type: string;
+  content: unknown;
+  fromAgent: string;
+  priority?: string | undefined;
+}
+
+export interface BroadcastResult extends OperationResult {
+  broadcastId?: string | undefined;
+  recipients?: string[] | undefined;
+}
+
+export interface ShareArtifactInput {
+  name: string;
+  type: string;
+  content?: unknown | undefined;
+  fromAgent: string;
+  description?: string | undefined;
+}
+
+export interface ShareArtifactResult extends OperationResult {
+  artifactId?: string | undefined;
+}
+
+export interface GetArtifactsResult extends OperationResult {
+  sessionId?: string | undefined;
+  artifacts?: Artifact[] | undefined;
+  count?: number | undefined;
+}
+
+export interface AgentScore {
+  agentId: string;
+  agent: Record<string, unknown>;
+  score: number;
+}
+
+export interface UpdateProgressInput {
+  progress?: number | undefined;
+  notes?: string | undefined;
+  artifacts?: Artifact[] | undefined;
+  blockedReason?: string | undefined;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const TASK_PRIORITY: Record<string, TaskPriorityValue> = {
+  CRITICAL: 'critical',
+  HIGH: 'high',
+  MEDIUM: 'medium',
+  LOW: 'low'
+};
+
+export const TASK_STATUS: Record<string, TaskStatusValue> = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  BLOCKED: 'blocked',
+  COMPLETE: 'complete',
+  FAILED: 'failed'
+};
+
+export const HANDOFF_STATUS: Record<string, HandoffStatusValue> = {
+  PENDING: 'pending',
+  ACCEPTED: 'accepted',
+  REJECTED: 'rejected',
+  COMPLETED: 'completed'
+};
+
+export const AGENT_ROLE: Record<string, AgentRoleValue> = {
+  PRIMARY: 'primary',
+  SUPPORTING: 'supporting',
+  SPECIALIST: 'specialist'
+};
+
+// ============================================================================
+// Collaboration Patterns
+// ============================================================================
+
+export const COLLAB_PATTERNS: Record<string, CollabPattern> = {
+  'code-review': {
+    name: 'Code Review',
+    description: 'Multi-agent code review with security and performance focus',
+    primaryAgent: 'code-review-expert',
+    supportingAgents: ['security-expert', 'performance-expert'],
+    subtaskTemplate: [
+      { title: 'Security Review', delegatedTo: 'security-expert', priority: 'high' },
+      { title: 'Performance Review', delegatedTo: 'performance-expert', priority: 'medium' }
+    ]
+  },
+  'feature-build': {
+    name: 'Feature Build',
+    description: 'Collaborative feature development with parallel tracks',
+    primaryAgent: 'architecture-expert',
+    supportingAgents: ['backend-expert', 'frontend-expert', 'database-expert', 'testing-expert'],
+    subtaskTemplate: [
+      { title: 'Architecture Design', delegatedTo: 'architecture-expert', priority: 'critical' },
+      { title: 'Database Schema', delegatedTo: 'database-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'API Implementation', delegatedTo: 'backend-expert', priority: 'high', dependencies: ['subtask-2'] },
+      { title: 'UI Implementation', delegatedTo: 'frontend-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Integration Tests', delegatedTo: 'testing-expert', priority: 'medium', dependencies: ['subtask-3', 'subtask-4'] }
+    ]
+  },
+  'security-hardening': {
+    name: 'Security Hardening',
+    description: 'Security-focused collaboration',
+    primaryAgent: 'security-expert',
+    supportingAgents: ['backend-expert', 'devops-expert'],
+    subtaskTemplate: [
+      { title: 'Vulnerability Assessment', delegatedTo: 'security-expert', priority: 'critical' },
+      { title: 'Code Security Fixes', delegatedTo: 'backend-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Infrastructure Hardening', delegatedTo: 'devops-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Security Verification', delegatedTo: 'security-expert', priority: 'high', dependencies: ['subtask-2', 'subtask-3'] }
+    ]
+  },
+  'api-development': {
+    name: 'API Development',
+    description: 'End-to-end API development with documentation',
+    primaryAgent: 'api-expert',
+    supportingAgents: ['database-expert', 'security-expert', 'testing-expert'],
+    subtaskTemplate: [
+      { title: 'API Design', delegatedTo: 'api-expert', priority: 'critical' },
+      { title: 'Data Model', delegatedTo: 'database-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'API Implementation', delegatedTo: 'api-expert', priority: 'high', dependencies: ['subtask-2'] },
+      { title: 'Security Review', delegatedTo: 'security-expert', priority: 'high', dependencies: ['subtask-3'] },
+      { title: 'API Tests', delegatedTo: 'testing-expert', priority: 'medium', dependencies: ['subtask-3'] }
+    ]
+  },
+  'full-stack-feature': {
+    name: 'Full Stack Feature',
+    description: 'Complete full-stack feature with frontend, backend, and testing',
+    primaryAgent: 'architecture-expert',
+    supportingAgents: ['frontend-expert', 'backend-expert', 'database-expert', 'testing-expert', 'ui-ux-expert'],
+    subtaskTemplate: [
+      { title: 'Feature Specification', delegatedTo: 'architecture-expert', priority: 'critical' },
+      { title: 'UI/UX Design', delegatedTo: 'ui-ux-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Data Model', delegatedTo: 'database-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Backend API', delegatedTo: 'backend-expert', priority: 'high', dependencies: ['subtask-3'] },
+      { title: 'Frontend UI', delegatedTo: 'frontend-expert', priority: 'high', dependencies: ['subtask-2', 'subtask-4'] },
+      { title: 'Integration Testing', delegatedTo: 'testing-expert', priority: 'medium', dependencies: ['subtask-4', 'subtask-5'] }
+    ]
+  },
+  'performance-optimization': {
+    name: 'Performance Optimization',
+    description: 'Performance analysis and optimization across the stack',
+    primaryAgent: 'performance-expert',
+    supportingAgents: ['database-expert', 'frontend-expert', 'backend-expert'],
+    subtaskTemplate: [
+      { title: 'Performance Audit', delegatedTo: 'performance-expert', priority: 'critical' },
+      { title: 'Database Optimization', delegatedTo: 'database-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Backend Optimization', delegatedTo: 'backend-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Frontend Optimization', delegatedTo: 'frontend-expert', priority: 'high', dependencies: ['subtask-1'] },
+      { title: 'Performance Verification', delegatedTo: 'performance-expert', priority: 'medium', dependencies: ['subtask-2', 'subtask-3', 'subtask-4'] }
+    ]
+  },
+  'launch-prep': {
+    name: 'Launch Preparation',
+    description: 'Pre-launch checklist with security, performance, and deployment',
+    primaryAgent: 'devops-expert',
+    supportingAgents: ['security-expert', 'performance-expert', 'testing-expert'],
+    subtaskTemplate: [
+      { title: 'Security Audit', delegatedTo: 'security-expert', priority: 'critical' },
+      { title: 'Performance Testing', delegatedTo: 'performance-expert', priority: 'critical' },
+      { title: 'End-to-End Tests', delegatedTo: 'testing-expert', priority: 'high' },
+      { title: 'Deployment Config', delegatedTo: 'devops-expert', priority: 'high', dependencies: ['subtask-1', 'subtask-2'] },
+      { title: 'Launch Verification', delegatedTo: 'devops-expert', priority: 'high', dependencies: ['subtask-3', 'subtask-4'] }
+    ]
+  }
+};
+
+// ============================================================================
+// Internal Functions
+// ============================================================================
+
+function getCollabPath(): string {
+  const projectRoot = process.cwd();
+  return path.join(projectRoot, '.bootspring', 'collab-state.json');
+}
+
+function emitCollabTelemetry(event: string, payload: Record<string, unknown> = {}): void {
+  try {
+    telemetry.emitEvent(event, payload, { projectRoot: process.cwd() });
+  } catch {
+    // Telemetry should not block collaboration execution
+  }
+}
+
+function createDefaultCollabState(): CollabState {
+  return {
+    activeSessions: {},
+    pendingHandoffs: [],
+    completedSessions: [],
+    taskQueues: {},
+    agentStates: {},
+    blockedTasks: [],
+    history: [],
+    metrics: {
+      totalSessions: 0,
+      successfulSessions: 0,
+      totalHandoffs: 0,
+      totalSubtasks: 0,
+      avgSessionDuration: 0
+    }
+  };
+}
+
+export function loadCollabState(): CollabState {
+  const statePath = getCollabPath();
+  if (fs.existsSync(statePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(statePath, 'utf8')) as CollabState;
+    } catch {
+      return createDefaultCollabState();
+    }
+  }
+  return createDefaultCollabState();
+}
+
+function saveCollabState(state: CollabState): void {
+  const statePath = getCollabPath();
+  const dir = path.dirname(statePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  state.lastUpdated = new Date().toISOString();
+  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
+}
+
+function generateSessionId(): string {
+  return `collab-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+function getAgentRegistry(): Record<string, Record<string, unknown>> {
+  try {
+    const agentsModule = require('../../agents') as { AGENTS?: Record<string, Record<string, unknown>> };
+    return agentsModule.AGENTS ?? {};
+  } catch {
+    try {
+      const agentCli = require('../../cli/agent') as { AGENTS?: Record<string, Record<string, unknown>> };
+      return agentCli.AGENTS ?? {};
+    } catch {
+      return {};
+    }
+  }
+}
+
+function insertIntoTaskQueue(queue: Subtask[], task: Subtask): void {
+  const priorityOrder: Record<string, number> = {
+    'critical': 0,
+    'high': 1,
+    'medium': 2,
+    'low': 3
+  };
+
+  const taskPriority = priorityOrder[task.priority] ?? 2;
+  let inserted = false;
+
+  for (let i = 0; i < queue.length; i++) {
+    const queueItem = queue[i];
+    if (!queueItem) continue;
+    const queuePriority = priorityOrder[queueItem.priority] ?? 2;
+    if (taskPriority < queuePriority) {
+      queue.splice(i, 0, task);
+      inserted = true;
+      break;
+    }
+  }
+
+  if (!inserted) {
+    queue.push(task);
+  }
+}
+
+function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`;
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+function getNextActions(
+  session: CollabSession,
+  pendingSubtasks: Subtask[],
+  pendingHandoffs: Handoff[],
+  blockedSubtasks: Subtask[]
+): NextAction[] {
+  const actions: NextAction[] = [];
+
+  if (pendingHandoffs.length > 0) {
+    actions.push({
+      type: 'accept_handoffs',
+      urgency: 'high',
+      count: pendingHandoffs.length,
+      message: `${pendingHandoffs.length} handoff(s) awaiting acceptance`
+    });
+  }
+
+  if (blockedSubtasks.length > 0) {
+    actions.push({
+      type: 'resolve_blockers',
+      urgency: 'medium',
+      count: blockedSubtasks.length,
+      message: `${blockedSubtasks.length} task(s) blocked on dependencies`
+    });
+  }
+
+  if (pendingSubtasks.length > 0) {
+    const highPriority = pendingSubtasks.filter(t =>
+      t.priority === 'high' || t.priority === 'critical'
+    );
+    if (highPriority.length > 0) {
+      actions.push({
+        type: 'start_high_priority',
+        urgency: 'high',
+        count: highPriority.length,
+        message: `${highPriority.length} high priority task(s) ready to start`
+      });
+    }
+  }
+
+  const allComplete = session.subtasks.length > 0 &&
+    session.subtasks.every(s =>
+      s.status === 'complete' || s.status === 'failed'
+    );
+
+  if (allComplete) {
+    actions.push({
+      type: 'finalize_session',
+      urgency: 'low',
+      message: 'All tasks processed. Ready to finalize session.'
+    });
+  }
+
+  return actions;
+}
+
+// ============================================================================
+// Public Functions
+// ============================================================================
+
+export function findBestAgentForTask(
+  taskDescription: string,
+  availableAgents: string[] = []
+): AgentScore | null {
+  const registry = getAgentRegistry();
+  const descLower = taskDescription.toLowerCase();
+  const scores: AgentScore[] = [];
+
+  const searchAgents = availableAgents.length > 0
+    ? availableAgents
+    : Object.keys(registry);
+
+  for (const agentId of searchAgents) {
+    const agent = registry[agentId];
+    if (!agent) continue;
+
+    let score = 0;
+    const expertise = (agent.expertise as string[]) ?? [];
+
+    for (const skill of expertise) {
+      if (typeof skill === 'string' && descLower.includes(skill.toLowerCase())) {
+        score += 10;
+      }
+    }
+
+    const agentDesc = agent.description;
+    if (typeof agentDesc === 'string' && descLower.includes(agentDesc.toLowerCase())) {
+      score += 5;
+    }
+
+    if (score > 0) {
+      scores.push({ agentId, agent, score });
+    }
+  }
+
+  scores.sort((a, b) => b.score - a.score);
+
+  return scores.length > 0 ? scores[0] ?? null : null;
+}
+
+export function startSession(options: StartSessionOptions): StartSessionResult {
+  const {
+    task,
+    primaryAgent,
+    supportingAgents = [],
+    context = {},
+    parentSessionId = null
+  } = options;
+
+  if (!task || !primaryAgent) {
+    return { success: false, error: 'Task and primaryAgent are required' };
+  }
+
+  const state = loadCollabState();
+  const sessionId = generateSessionId();
+
+  const agentParticipants: Record<string, AgentParticipant> = {
+    [primaryAgent]: {
+      role: 'primary',
+      joinedAt: new Date().toISOString(),
+      tasksAssigned: 0,
+      tasksCompleted: 0,
+      status: 'active'
+    }
+  };
+
+  for (const agent of supportingAgents) {
+    agentParticipants[agent] = {
+      role: 'supporting',
+      joinedAt: new Date().toISOString(),
+      tasksAssigned: 0,
+      tasksCompleted: 0,
+      status: 'standby'
+    };
+  }
+
+  const session: CollabSession = {
+    id: sessionId,
+    task,
+    primaryAgent,
+    supportingAgents,
+    agentParticipants,
+    status: 'active',
+    createdAt: new Date().toISOString(),
+    parentSessionId,
+    subtasks: [],
+    taskQueue: [],
+    handoffs: [],
+    results: {},
+    artifacts: [],
+    context: {
+      initial: context,
+      current: { ...context },
+      history: []
+    },
+    checkpoints: [],
+    metrics: {
+      startTime: Date.now(),
+      handoffCount: 0,
+      delegationCount: 0,
+      blockedTime: 0
+    }
+  };
+
+  state.activeSessions[sessionId] = session;
+  state.metrics.totalSessions++;
+
+  if (!state.taskQueues[primaryAgent]) {
+    state.taskQueues[primaryAgent] = [];
+  }
+
+  state.history.push({
+    action: 'session_started',
+    sessionId,
+    primaryAgent,
+    supportingAgents,
+    parentSessionId,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  emitCollabTelemetry('collab_session_started', {
+    sessionId,
+    primaryAgent,
+    supportingAgentCount: supportingAgents.length
+  });
+
+  return {
+    success: true,
+    sessionId,
+    session,
+    message: `Collaboration session started with ${primaryAgent} as primary agent`
+  };
+}
+
+export function delegateTask(sessionId: string, subtask: DelegateTaskInput): DelegateTaskResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const {
+    title,
+    description = '',
+    delegatedTo,
+    delegatedBy = session.primaryAgent,
+    context = {},
+    priority = 'medium',
+    dependencies = [],
+    expectedDuration = null,
+    acceptanceCriteria = [],
+    artifacts = []
+  } = subtask;
+
+  if (!title || !delegatedTo) {
+    return { success: false, error: 'Title and delegatedTo are required' };
+  }
+
+  const subtaskId = `subtask-${session.subtasks.length + 1}-${Date.now()}`;
+
+  const unmetDependencies = dependencies.filter(depId => {
+    const dep = session.subtasks.find(t => t.id === depId);
+    return !dep || dep.status !== 'complete';
+  });
+
+  const newSubtask: Subtask = {
+    id: subtaskId,
+    title,
+    description,
+    delegatedTo,
+    delegatedBy,
+    context: {
+      ...session.context.current,
+      ...context
+    },
+    priority,
+    dependencies,
+    unmetDependencies,
+    expectedDuration,
+    acceptanceCriteria,
+    artifacts,
+    status: unmetDependencies.length > 0 ? 'blocked' : 'pending',
+    createdAt: new Date().toISOString(),
+    startedAt: null,
+    completedAt: null,
+    result: null,
+    feedback: null,
+    retryCount: 0
+  };
+
+  session.subtasks.push(newSubtask);
+  session.metrics.delegationCount++;
+
+  const participant = session.agentParticipants[delegatedTo];
+  if (participant) {
+    participant.tasksAssigned++;
+  } else {
+    session.agentParticipants[delegatedTo] = {
+      role: 'specialist',
+      joinedAt: new Date().toISOString(),
+      tasksAssigned: 1,
+      tasksCompleted: 0,
+      status: 'active'
+    };
+  }
+
+  insertIntoTaskQueue(session.taskQueue, newSubtask);
+
+  if (!state.taskQueues[delegatedTo]) {
+    state.taskQueues[delegatedTo] = [];
+  }
+  state.taskQueues[delegatedTo].push({
+    sessionId,
+    subtaskId,
+    priority,
+    createdAt: newSubtask.createdAt
+  });
+
+  if (newSubtask.status === 'blocked') {
+    state.blockedTasks.push({
+      sessionId,
+      subtaskId,
+      dependencies: unmetDependencies
+    });
+  }
+
+  state.metrics.totalSubtasks++;
+
+  state.history.push({
+    action: 'task_delegated',
+    sessionId,
+    subtaskId,
+    from: delegatedBy,
+    to: delegatedTo,
+    priority,
+    hasDepedencies: dependencies.length > 0,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  emitCollabTelemetry('task_delegated', {
+    sessionId,
+    subtaskId,
+    delegatedTo,
+    priority
+  });
+
+  return {
+    success: true,
+    sessionId,
+    subtaskId,
+    subtask: newSubtask,
+    isBlocked: newSubtask.status === 'blocked',
+    message: newSubtask.status === 'blocked'
+      ? `Task "${title}" delegated to ${delegatedTo} (blocked on dependencies)`
+      : `Task "${title}" delegated to ${delegatedTo}`
+  };
+}
+
+export function startSubtask(sessionId: string, subtaskId: string): SubtaskOperationResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const subtask = session.subtasks.find(s => s.id === subtaskId);
+  if (!subtask) {
+    return { success: false, error: `Subtask not found: ${subtaskId}` };
+  }
+
+  if (subtask.status === 'blocked') {
+    return {
+      success: false,
+      error: 'Subtask is blocked on dependencies'
+    };
+  }
+
+  if (subtask.status === 'in_progress') {
+    return { success: false, error: 'Subtask already in progress' };
+  }
+
+  subtask.status = 'in_progress';
+  subtask.startedAt = new Date().toISOString();
+
+  const participant = session.agentParticipants[subtask.delegatedTo];
+  if (participant) {
+    participant.status = 'working';
+  }
+
+  state.history.push({
+    action: 'subtask_started',
+    sessionId,
+    subtaskId,
+    agent: subtask.delegatedTo,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    subtaskId,
+    subtask,
+    message: `Started working on "${subtask.title}"`
+  };
+}
+
+export function updateSubtaskProgress(
+  sessionId: string,
+  subtaskId: string,
+  update: UpdateProgressInput
+): SubtaskOperationResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const subtask = session.subtasks.find(s => s.id === subtaskId);
+  if (!subtask) {
+    return { success: false, error: `Subtask not found: ${subtaskId}` };
+  }
+
+  const { progress, notes, artifacts, blockedReason } = update;
+
+  if (progress !== undefined) {
+    subtask.progress = progress;
+  }
+
+  if (notes) {
+    subtask.progressNotes = subtask.progressNotes ?? [];
+    subtask.progressNotes.push({
+      note: notes,
+      timestamp: new Date().toISOString()
+    });
+  }
+
+  if (artifacts && artifacts.length > 0) {
+    subtask.artifacts = [...(subtask.artifacts ?? []), ...artifacts];
+    session.artifacts.push(...artifacts.map(a => ({
+      ...a,
+      subtaskId,
+      addedAt: new Date().toISOString()
+    })));
+  }
+
+  if (blockedReason) {
+    subtask.status = 'blocked';
+    subtask.blockedReason = blockedReason;
+    state.blockedTasks.push({
+      sessionId,
+      subtaskId,
+      reason: blockedReason,
+      blockedAt: new Date().toISOString()
+    });
+  }
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    subtaskId,
+    subtask,
+    message: 'Subtask progress updated'
+  };
+}
+
+export function completeSubtask(
+  sessionId: string,
+  subtaskId: string,
+  result: CompleteSubtaskInput
+): CompleteSubtaskResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const subtask = session.subtasks.find(s => s.id === subtaskId);
+  if (!subtask) {
+    return { success: false, error: `Subtask not found: ${subtaskId}` };
+  }
+
+  const {
+    output,
+    artifacts = [],
+    contextUpdates = {},
+    learnings = [],
+    success = true
+  } = result;
+
+  subtask.status = success ? 'complete' : 'failed';
+  subtask.completedAt = new Date().toISOString();
+  subtask.result = {
+    output,
+    success,
+    duration: subtask.startedAt
+      ? Date.now() - new Date(subtask.startedAt).getTime()
+      : null
+  };
+
+  if (artifacts.length > 0) {
+    subtask.artifacts = [...(subtask.artifacts ?? []), ...artifacts];
+    session.artifacts.push(...artifacts.map(a => ({
+      ...a,
+      subtaskId,
+      addedAt: new Date().toISOString()
+    })));
+  }
+
+  if (Object.keys(contextUpdates).length > 0) {
+    session.context.history.push({
+      update: contextUpdates,
+      source: subtaskId,
+      timestamp: new Date().toISOString()
+    });
+    session.context.current = {
+      ...session.context.current,
+      ...contextUpdates
+    };
+  }
+
+  if (learnings.length > 0) {
+    session.learnings = session.learnings ?? [];
+    session.learnings.push(...learnings.map(l => ({
+      content: l,
+      subtaskId,
+      agent: subtask.delegatedTo,
+      timestamp: new Date().toISOString()
+    })));
+  }
+
+  session.results[subtaskId] = result;
+
+  const participant = session.agentParticipants[subtask.delegatedTo];
+  if (participant) {
+    participant.tasksCompleted++;
+    participant.status = 'standby';
+  }
+
+  const agentQueue = state.taskQueues[subtask.delegatedTo];
+  if (agentQueue) {
+    state.taskQueues[subtask.delegatedTo] = agentQueue
+      .filter(t => !(t.sessionId === sessionId && t.subtaskId === subtaskId));
+  }
+
+  const unblockedTasks: string[] = [];
+  for (const t of session.subtasks) {
+    if (t.status === 'blocked' && t.dependencies.includes(subtaskId)) {
+      t.unmetDependencies = t.unmetDependencies.filter(d => d !== subtaskId);
+      if (t.unmetDependencies.length === 0) {
+        t.status = 'pending';
+        unblockedTasks.push(t.id);
+      }
+    }
+  }
+
+  state.blockedTasks = state.blockedTasks.filter(
+    bt => !(bt.sessionId === sessionId && bt.subtaskId === subtaskId)
+  );
+
+  state.history.push({
+    action: 'subtask_completed',
+    sessionId,
+    subtaskId,
+    agent: subtask.delegatedTo,
+    success,
+    unblockedTasks,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  emitCollabTelemetry('subtask_completed', {
+    sessionId,
+    subtaskId,
+    agent: subtask.delegatedTo,
+    success,
+    unblockedCount: unblockedTasks.length
+  });
+
+  const allComplete = session.subtasks.every(
+    s => s.status === 'complete' || s.status === 'failed'
+  );
+  const allSuccessful = session.subtasks.every(s => s.status === 'complete');
+
+  return {
+    success: true,
+    sessionId,
+    subtaskId,
+    taskSuccess: success,
+    allSubtasksComplete: allComplete,
+    allSubtasksSuccessful: allSuccessful,
+    unblockedTasks,
+    message: allComplete
+      ? allSuccessful
+        ? 'All subtasks complete. Ready to finalize session.'
+        : 'All subtasks processed with some failures.'
+      : `Subtask "${subtask.title}" completed`
+  };
+}
+
+export function failSubtask(
+  sessionId: string,
+  subtaskId: string,
+  failure: FailSubtaskInput
+): FailSubtaskResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const subtask = session.subtasks.find(s => s.id === subtaskId);
+  if (!subtask) {
+    return { success: false, error: `Subtask not found: ${subtaskId}` };
+  }
+
+  const { reason, canRetry = false, suggestedAction = null } = failure;
+
+  subtask.status = 'failed';
+  subtask.completedAt = new Date().toISOString();
+  subtask.failure = {
+    reason,
+    canRetry,
+    suggestedAction,
+    failedAt: new Date().toISOString()
+  };
+  subtask.retryCount++;
+
+  const participant = session.agentParticipants[subtask.delegatedTo];
+  if (participant) {
+    participant.status = 'standby';
+  }
+
+  state.history.push({
+    action: 'subtask_failed',
+    sessionId,
+    subtaskId,
+    agent: subtask.delegatedTo,
+    reason,
+    canRetry,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    subtaskId,
+    canRetry,
+    suggestedAction,
+    message: `Subtask "${subtask.title}" failed: ${reason}`
+  };
+}
+
+export function retrySubtask(
+  sessionId: string,
+  subtaskId: string,
+  options: RetryOptions = {}
+): RetryResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const subtask = session.subtasks.find(s => s.id === subtaskId);
+  if (!subtask) {
+    return { success: false, error: `Subtask not found: ${subtaskId}` };
+  }
+
+  if (subtask.status !== 'failed') {
+    return { success: false, error: 'Can only retry failed subtasks' };
+  }
+
+  const { reassignTo, additionalContext = {} } = options;
+
+  subtask.status = 'pending';
+  subtask.completedAt = null;
+  subtask.startedAt = null;
+  subtask.result = null;
+
+  if (reassignTo) {
+    subtask.reassignedFrom = subtask.delegatedTo;
+    subtask.delegatedTo = reassignTo;
+  }
+
+  if (Object.keys(additionalContext).length > 0) {
+    subtask.context = {
+      ...subtask.context,
+      ...additionalContext,
+      previousAttemptFailed: true
+    };
+  }
+
+  insertIntoTaskQueue(session.taskQueue, subtask);
+
+  state.history.push({
+    action: 'subtask_retried',
+    sessionId,
+    subtaskId,
+    retryCount: subtask.retryCount,
+    reassignedTo: reassignTo ?? null,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    subtaskId,
+    retryCount: subtask.retryCount,
+    message: `Subtask "${subtask.title}" queued for retry`
+  };
+}
+
+export function requestHandoff(sessionId: string, handoff: RequestHandoffInput): HandoffResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const {
+    fromAgent,
+    toAgent,
+    reason,
+    context = {},
+    artifacts = [],
+    transferPrimaryRole = false,
+    subtaskId = null,
+    urgency = 'normal',
+    expectedDuration = null
+  } = handoff;
+
+  if (!fromAgent || !toAgent) {
+    return { success: false, error: 'fromAgent and toAgent are required' };
+  }
+
+  const handoffId = `handoff-${session.handoffs.length + 1}-${Date.now()}`;
+
+  const handoffContext: Record<string, unknown> = {
+    ...session.context.current,
+    ...context,
+    handoffReason: reason,
+    previousAgent: fromAgent,
+    sessionProgress: {
+      completedSubtasks: session.subtasks.filter(s => s.status === 'complete').length,
+      totalSubtasks: session.subtasks.length,
+      artifacts: session.artifacts.length
+    }
+  };
+
+  if (subtaskId) {
+    const transferredSubtask = session.subtasks.find(s => s.id === subtaskId);
+    if (transferredSubtask) {
+      handoffContext.subtask = {
+        id: transferredSubtask.id,
+        title: transferredSubtask.title,
+        description: transferredSubtask.description,
+        progress: transferredSubtask.progress,
+        progressNotes: transferredSubtask.progressNotes
+      };
+    }
+  }
+
+  const newHandoff: Handoff = {
+    id: handoffId,
+    fromAgent,
+    toAgent,
+    reason,
+    context: handoffContext,
+    artifacts,
+    transferPrimaryRole,
+    subtaskId,
+    urgency,
+    expectedDuration,
+    status: 'pending',
+    requestedAt: new Date().toISOString(),
+    acceptedAt: null,
+    completedAt: null,
+    rejectionReason: null
+  };
+
+  session.handoffs.push(newHandoff);
+  session.metrics.handoffCount++;
+
+  state.pendingHandoffs.push({
+    sessionId,
+    handoffId,
+    ...newHandoff
+  });
+
+  state.metrics.totalHandoffs++;
+
+  state.history.push({
+    action: 'handoff_requested',
+    sessionId,
+    handoffId,
+    fromAgent,
+    toAgent,
+    transferPrimaryRole,
+    urgency,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  emitCollabTelemetry('handoff_requested', {
+    sessionId,
+    handoffId,
+    fromAgent,
+    toAgent,
+    transferPrimaryRole,
+    urgency
+  });
+
+  return {
+    success: true,
+    sessionId,
+    handoffId,
+    handoff: newHandoff,
+    message: transferPrimaryRole
+      ? `Primary role handoff requested from ${fromAgent} to ${toAgent}`
+      : `Handoff requested from ${fromAgent} to ${toAgent}`
+  };
+}
+
+export function acceptHandoff(
+  sessionId: string,
+  handoffId: string,
+  options: AcceptHandoffOptions = {}
+): HandoffResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const handoff = session.handoffs.find(h => h.id === handoffId);
+  if (!handoff) {
+    return { success: false, error: `Handoff not found: ${handoffId}` };
+  }
+
+  if (handoff.status !== 'pending') {
+    return { success: false, error: `Handoff already ${handoff.status}` };
+  }
+
+  const { acknowledgment = null, estimatedCompletion = null } = options;
+
+  handoff.status = 'accepted';
+  handoff.acceptedAt = new Date().toISOString();
+  handoff.acknowledgment = acknowledgment;
+  handoff.estimatedCompletion = estimatedCompletion;
+
+  const previousPrimary = session.primaryAgent;
+  if (handoff.transferPrimaryRole) {
+    session.primaryAgent = handoff.toAgent;
+
+    const prevParticipant = session.agentParticipants[previousPrimary];
+    if (prevParticipant) {
+      prevParticipant.role = 'supporting';
+    }
+    const newParticipant = session.agentParticipants[handoff.toAgent];
+    if (newParticipant) {
+      newParticipant.role = 'primary';
+    }
+  }
+
+  if (handoff.subtaskId) {
+    const subtask = session.subtasks.find(s => s.id === handoff.subtaskId);
+    if (subtask) {
+      subtask.delegatedTo = handoff.toAgent;
+      subtask.transferHistory = subtask.transferHistory ?? [];
+      subtask.transferHistory.push({
+        from: handoff.fromAgent,
+        to: handoff.toAgent,
+        handoffId,
+        timestamp: new Date().toISOString()
+      });
+    }
+  }
+
+  const toParticipant = session.agentParticipants[handoff.toAgent];
+  if (toParticipant) {
+    toParticipant.status = 'active';
+  }
+
+  state.pendingHandoffs = state.pendingHandoffs.filter(
+    h => !(h.sessionId === sessionId && h.handoffId === handoffId)
+  );
+
+  state.history.push({
+    action: 'handoff_accepted',
+    sessionId,
+    handoffId,
+    byAgent: handoff.toAgent,
+    transferPrimaryRole: handoff.transferPrimaryRole,
+    previousPrimary: handoff.transferPrimaryRole ? previousPrimary : null,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  emitCollabTelemetry('handoff_accepted', {
+    sessionId,
+    handoffId,
+    byAgent: handoff.toAgent,
+    transferPrimaryRole: handoff.transferPrimaryRole
+  });
+
+  return {
+    success: true,
+    sessionId,
+    handoffId,
+    newPrimaryAgent: session.primaryAgent,
+    transferredSubtask: handoff.subtaskId,
+    context: handoff.context,
+    message: handoff.transferPrimaryRole
+      ? `Primary role transferred to ${handoff.toAgent}`
+      : `Handoff accepted by ${handoff.toAgent}`
+  };
+}
+
+export function rejectHandoff(sessionId: string, handoffId: string, reason: string): HandoffResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const handoff = session.handoffs.find(h => h.id === handoffId);
+  if (!handoff) {
+    return { success: false, error: `Handoff not found: ${handoffId}` };
+  }
+
+  if (handoff.status !== 'pending') {
+    return { success: false, error: `Handoff already ${handoff.status}` };
+  }
+
+  handoff.status = 'rejected';
+  handoff.rejectionReason = reason;
+  handoff.rejectedAt = new Date().toISOString();
+
+  state.pendingHandoffs = state.pendingHandoffs.filter(
+    h => !(h.sessionId === sessionId && h.handoffId === handoffId)
+  );
+
+  state.history.push({
+    action: 'handoff_rejected',
+    sessionId,
+    handoffId,
+    byAgent: handoff.toAgent,
+    reason,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    handoffId,
+    rejectionReason: reason,
+    message: `Handoff rejected by ${handoff.toAgent}: ${reason}`
+  };
+}
+
+export function completeHandoff(
+  sessionId: string,
+  handoffId: string,
+  result: Record<string, unknown> = {}
+): HandoffResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const handoff = session.handoffs.find(h => h.id === handoffId);
+  if (!handoff) {
+    return { success: false, error: `Handoff not found: ${handoffId}` };
+  }
+
+  if (handoff.status !== 'accepted') {
+    return { success: false, error: 'Handoff must be accepted before completing' };
+  }
+
+  handoff.status = 'completed';
+  handoff.completedAt = new Date().toISOString();
+  handoff.result = result;
+
+  state.history.push({
+    action: 'handoff_completed',
+    sessionId,
+    handoffId,
+    byAgent: handoff.toAgent,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    handoffId,
+    message: `Handoff completed by ${handoff.toAgent}`
+  };
+}
+
+export function createCheckpoint(sessionId: string, description: string = ''): CheckpointResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const checkpointId = `checkpoint-${session.checkpoints.length + 1}`;
+  const checkpoint: Checkpoint = {
+    id: checkpointId,
+    description,
+    createdAt: new Date().toISOString(),
+    snapshot: {
+      subtasks: JSON.parse(JSON.stringify(session.subtasks)),
+      context: JSON.parse(JSON.stringify(session.context)),
+      results: JSON.parse(JSON.stringify(session.results)),
+      artifacts: JSON.parse(JSON.stringify(session.artifacts)),
+      primaryAgent: session.primaryAgent
+    }
+  };
+
+  session.checkpoints.push(checkpoint);
+
+  state.history.push({
+    action: 'checkpoint_created',
+    sessionId,
+    checkpointId,
+    description,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    checkpointId,
+    message: `Checkpoint created: ${description || checkpointId}`
+  };
+}
+
+export function restoreFromCheckpoint(sessionId: string, checkpointId: string): CheckpointResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const checkpoint = session.checkpoints.find(c => c.id === checkpointId);
+  if (!checkpoint) {
+    return { success: false, error: `Checkpoint not found: ${checkpointId}` };
+  }
+
+  session.subtasks = JSON.parse(JSON.stringify(checkpoint.snapshot.subtasks));
+  session.context = JSON.parse(JSON.stringify(checkpoint.snapshot.context));
+  session.results = JSON.parse(JSON.stringify(checkpoint.snapshot.results));
+  session.artifacts = JSON.parse(JSON.stringify(checkpoint.snapshot.artifacts));
+  session.primaryAgent = checkpoint.snapshot.primaryAgent;
+
+  state.history.push({
+    action: 'checkpoint_restored',
+    sessionId,
+    checkpointId,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    checkpointId,
+    message: `Session restored to checkpoint: ${checkpoint.description || checkpointId}`
+  };
+}
+
+export function finalizeSession(
+  sessionId: string,
+  summary: Record<string, unknown> = {}
+): StartSessionResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const endTime = Date.now();
+  const duration = endTime - session.metrics.startTime;
+
+  const completedSubtasks = session.subtasks.filter(s => s.status === 'complete');
+  const failedSubtasks = session.subtasks.filter(s => s.status === 'failed');
+
+  session.status = 'complete';
+  session.completedAt = new Date().toISOString();
+  session.summary = {
+    ...summary,
+    task: session.task,
+    primaryAgent: session.primaryAgent,
+    subtasksCompleted: completedSubtasks.length,
+    subtasksFailed: failedSubtasks.length,
+    totalSubtasks: session.subtasks.length,
+    handoffsCount: session.handoffs.length,
+    acceptedHandoffs: session.handoffs.filter(h => h.status === 'accepted').length,
+    rejectedHandoffs: session.handoffs.filter(h => h.status === 'rejected').length,
+    duration,
+    durationFormatted: formatDuration(duration),
+    artifactsCount: session.artifacts.length,
+    agentParticipation: Object.entries(session.agentParticipants).map(([agent, data]) => ({
+      agent,
+      role: data.role,
+      tasksAssigned: data.tasksAssigned,
+      tasksCompleted: data.tasksCompleted
+    })),
+    learnings: session.learnings ?? [],
+    checkpointsCount: session.checkpoints.length,
+    successRate: session.subtasks.length > 0
+      ? Math.round((completedSubtasks.length / session.subtasks.length) * 100)
+      : 100
+  };
+
+  state.completedSessions.push(session);
+  delete state.activeSessions[sessionId];
+
+  for (const agent of Object.keys(session.agentParticipants)) {
+    const agentQueue = state.taskQueues[agent];
+    if (agentQueue) {
+      state.taskQueues[agent] = agentQueue.filter(t => t.sessionId !== sessionId);
+    }
+  }
+
+  state.metrics.successfulSessions++;
+  const totalDuration = state.metrics.avgSessionDuration * (state.metrics.successfulSessions - 1);
+  state.metrics.avgSessionDuration = (totalDuration + duration) / state.metrics.successfulSessions;
+
+  state.history.push({
+    action: 'session_finalized',
+    sessionId,
+    duration,
+    successRate: session.summary.successRate,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  emitCollabTelemetry('collab_session_completed', {
+    sessionId,
+    duration,
+    successRate: session.summary.successRate,
+    subtaskCount: session.subtasks.length,
+    handoffCount: session.handoffs.length
+  });
+
+  return {
+    success: true,
+    sessionId,
+    session,
+    message: 'Collaboration session finalized'
+  };
+}
+
+export function abortSession(sessionId: string, reason: string = ''): StartSessionResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  session.status = 'aborted';
+  session.abortedAt = new Date().toISOString();
+  session.abortReason = reason;
+
+  state.completedSessions.push(session);
+  delete state.activeSessions[sessionId];
+
+  state.pendingHandoffs = state.pendingHandoffs.filter(h => h.sessionId !== sessionId);
+
+  for (const agent of Object.keys(session.agentParticipants)) {
+    const agentQueue = state.taskQueues[agent];
+    if (agentQueue) {
+      state.taskQueues[agent] = agentQueue.filter(t => t.sessionId !== sessionId);
+    }
+  }
+
+  state.history.push({
+    action: 'session_aborted',
+    sessionId,
+    reason,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    message: `Collaboration session aborted: ${reason}`
+  };
+}
+
+export function getSessionStatus(sessionId: string): SessionStatusResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    const completed = state.completedSessions.find(s => s.id === sessionId);
+    if (completed) {
+      return {
+        found: true,
+        session: completed,
+        isActive: false,
+        summary: completed.summary
+      };
+    }
+    return { found: false };
+  }
+
+  const pendingSubtasks = session.subtasks.filter(s => s.status === 'pending');
+  const inProgressSubtasks = session.subtasks.filter(s => s.status === 'in_progress');
+  const blockedSubtasks = session.subtasks.filter(s => s.status === 'blocked');
+  const completedSubtasks = session.subtasks.filter(s => s.status === 'complete');
+  const failedSubtasks = session.subtasks.filter(s => s.status === 'failed');
+  const pendingHandoffs = session.handoffs.filter(h => h.status === 'pending');
+
+  const elapsed = Date.now() - session.metrics.startTime;
+
+  return {
+    found: true,
+    isActive: true,
+    session: {
+      id: session.id,
+      task: session.task,
+      status: session.status,
+      primaryAgent: session.primaryAgent,
+      supportingAgents: session.supportingAgents,
+      createdAt: session.createdAt
+    },
+    progress: {
+      subtasks: {
+        pending: pendingSubtasks.length,
+        inProgress: inProgressSubtasks.length,
+        blocked: blockedSubtasks.length,
+        completed: completedSubtasks.length,
+        failed: failedSubtasks.length,
+        total: session.subtasks.length,
+        percent: session.subtasks.length > 0
+          ? Math.round((completedSubtasks.length / session.subtasks.length) * 100)
+          : 0
+      },
+      handoffs: {
+        pending: pendingHandoffs.length,
+        total: session.handoffs.length,
+        accepted: session.handoffs.filter(h => h.status === 'accepted').length
+      },
+      artifacts: session.artifacts.length,
+      checkpoints: session.checkpoints.length
+    },
+    agents: Object.entries(session.agentParticipants).map(([agent, data]) => ({
+      agent,
+      role: data.role,
+      status: data.status,
+      tasksAssigned: data.tasksAssigned,
+      tasksCompleted: data.tasksCompleted
+    })),
+    timing: {
+      elapsed,
+      elapsedFormatted: formatDuration(elapsed)
+    },
+    nextActions: getNextActions(session, pendingSubtasks, pendingHandoffs, blockedSubtasks)
+  };
+}
+
+export function getNextTaskForAgent(agentName: string): NextTaskResult {
+  const state = loadCollabState();
+  const agentQueue = state.taskQueues[agentName] ?? [];
+
+  if (agentQueue.length === 0) {
+    return { hasTask: false, message: 'No tasks in queue' };
+  }
+
+  const priorityOrder: Record<string, number> = {
+    'critical': 0,
+    'high': 1,
+    'medium': 2,
+    'low': 3
+  };
+
+  agentQueue.sort((a, b) => {
+    const priorityDiff = (priorityOrder[a.priority] ?? 2) - (priorityOrder[b.priority] ?? 2);
+    if (priorityDiff !== 0) return priorityDiff;
+    return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+  });
+
+  const nextItem = agentQueue[0];
+  if (!nextItem) {
+    return { hasTask: false, message: 'No tasks in queue' };
+  }
+
+  const session = state.activeSessions[nextItem.sessionId];
+
+  if (!session) {
+    state.taskQueues[agentName] = agentQueue.slice(1);
+    saveCollabState(state);
+    return getNextTaskForAgent(agentName);
+  }
+
+  const subtask = session.subtasks.find(s => s.id === nextItem.subtaskId);
+
+  if (!subtask || subtask.status === 'blocked') {
+    return {
+      hasTask: false,
+      blocked: true,
+      message: 'Next task is blocked on dependencies'
+    };
+  }
+
+  return {
+    hasTask: true,
+    sessionId: nextItem.sessionId,
+    subtask,
+    sessionContext: session.context.current,
+    message: `Next task: ${subtask.title}`
+  };
+}
+
+export function listActiveSessions(): ActiveSessionInfo[] {
+  const state = loadCollabState();
+
+  return Object.values(state.activeSessions).map(session => ({
+    id: session.id,
+    task: session.task,
+    primaryAgent: session.primaryAgent,
+    status: session.status,
+    subtaskCount: session.subtasks.length,
+    createdAt: session.createdAt
+  }));
+}
+
+export function getPendingHandoffsForAgent(agentName: string): PendingHandoffItem[] {
+  const state = loadCollabState();
+  return state.pendingHandoffs.filter(h => h.toAgent === agentName);
+}
+
+export function startFromPattern(
+  patternName: string,
+  task: string,
+  options: StartFromPatternOptions = {}
+): StartFromPatternResult {
+  const pattern = COLLAB_PATTERNS[patternName];
+  if (!pattern) {
+    return {
+      success: false,
+      error: `Unknown pattern: ${patternName}`,
+      availablePatterns: Object.keys(COLLAB_PATTERNS)
+    };
+  }
+
+  const { context = {}, autoStart = false } = options;
+
+  const sessionResult = startSession({
+    task,
+    primaryAgent: pattern.primaryAgent,
+    supportingAgents: pattern.supportingAgents,
+    context: {
+      pattern: patternName,
+      ...context
+    }
+  });
+
+  if (!sessionResult.success || !sessionResult.sessionId) {
+    return sessionResult;
+  }
+
+  const subtaskResults: DelegateTaskResult[] = [];
+  const idMapping: Record<string, string> = {};
+
+  for (let i = 0; i < pattern.subtaskTemplate.length; i++) {
+    const template = pattern.subtaskTemplate[i];
+    if (!template) continue;
+
+    const templateId = `subtask-${i + 1}`;
+
+    const mappedDependencies = (template.dependencies ?? []).map(depId => {
+      return idMapping[depId] ?? depId;
+    });
+
+    const result = delegateTask(sessionResult.sessionId, {
+      ...template,
+      description: `${template.title} for: ${task}`,
+      dependencies: mappedDependencies
+    });
+
+    if (result.success && result.subtaskId) {
+      idMapping[templateId] = result.subtaskId;
+    }
+    subtaskResults.push(result);
+  }
+
+  const firstResult = subtaskResults[0];
+  if (autoStart && firstResult && firstResult.success && firstResult.subtaskId) {
+    startSubtask(sessionResult.sessionId, firstResult.subtaskId);
+  }
+
+  return {
+    success: true,
+    sessionId: sessionResult.sessionId,
+    pattern: patternName,
+    patternName: pattern.name,
+    primaryAgent: pattern.primaryAgent,
+    subtasks: subtaskResults.map(r => ({
+      id: r.subtaskId,
+      title: r.subtask?.title,
+      delegatedTo: r.subtask?.delegatedTo,
+      status: r.subtask?.status
+    })),
+    message: `Started collaboration from "${pattern.name}" pattern`
+  };
+}
+
+export function getCollabStats(): CollabStats {
+  const state = loadCollabState();
+
+  const activeSessions = Object.values(state.activeSessions);
+  const totalActive = activeSessions.length;
+  const totalSubtasksActive = activeSessions.reduce((sum, s) => sum + s.subtasks.length, 0);
+  const pendingHandoffs = state.pendingHandoffs.length;
+
+  return {
+    activeSessions: totalActive,
+    completedSessions: state.completedSessions.length,
+    totalSessions: state.metrics.totalSessions,
+    successfulSessions: state.metrics.successfulSessions,
+    totalSubtasks: state.metrics.totalSubtasks,
+    totalHandoffs: state.metrics.totalHandoffs,
+    activeSubtasks: totalSubtasksActive,
+    pendingHandoffs,
+    avgSessionDuration: state.metrics.avgSessionDuration,
+    avgSessionDurationFormatted: formatDuration(state.metrics.avgSessionDuration || 0),
+    blockedTasks: state.blockedTasks.length
+  };
+}
+
+export function getSessionHistory(sessionId: string | null = null): HistoryEntry[] {
+  const state = loadCollabState();
+
+  if (sessionId) {
+    return state.history.filter(h => h.sessionId === sessionId);
+  }
+
+  return state.history.slice(-100);
+}
+
+export function listPatterns(): PatternInfo[] {
+  return Object.entries(COLLAB_PATTERNS).map(([key, pattern]) => ({
+    key,
+    name: pattern.name,
+    description: pattern.description,
+    primaryAgent: pattern.primaryAgent,
+    supportingAgents: pattern.supportingAgents,
+    subtaskCount: pattern.subtaskTemplate.length
+  }));
+}
+
+export function broadcastToSession(sessionId: string, message: BroadcastInput): BroadcastResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const { type, content, fromAgent, priority = 'normal' } = message;
+
+  const broadcast: Broadcast = {
+    id: `broadcast-${Date.now()}`,
+    type,
+    content,
+    fromAgent,
+    priority,
+    timestamp: new Date().toISOString(),
+    recipients: Object.keys(session.agentParticipants)
+  };
+
+  session.broadcasts = session.broadcasts ?? [];
+  session.broadcasts.push(broadcast);
+
+  state.history.push({
+    action: 'broadcast_sent',
+    sessionId,
+    broadcastId: broadcast.id,
+    fromAgent,
+    recipientCount: broadcast.recipients.length,
+    timestamp: broadcast.timestamp
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    broadcastId: broadcast.id,
+    recipients: broadcast.recipients,
+    message: `Broadcast sent to ${broadcast.recipients.length} agents`
+  };
+}
+
+export function shareArtifact(sessionId: string, artifact: ShareArtifactInput): ShareArtifactResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  const { name, type, content, fromAgent, description = '' } = artifact;
+
+  if (!name || !type || !fromAgent) {
+    return { success: false, error: 'name, type, and fromAgent are required' };
+  }
+
+  const sharedArtifact: Artifact = {
+    id: `artifact-${Date.now()}`,
+    name,
+    type,
+    content,
+    description,
+    fromAgent,
+    sharedAt: new Date().toISOString()
+  };
+
+  session.artifacts.push(sharedArtifact);
+
+  state.history.push({
+    action: 'artifact_shared',
+    sessionId,
+    artifactId: sharedArtifact.id,
+    name,
+    type,
+    fromAgent,
+    timestamp: sharedArtifact.sharedAt ?? new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    artifactId: sharedArtifact.id,
+    message: `Artifact "${name}" shared with session`
+  };
+}
+
+export function getSessionArtifacts(sessionId: string): GetArtifactsResult {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId] ??
+    state.completedSessions.find(s => s.id === sessionId);
+
+  if (!session) {
+    return { success: false, error: `Session not found: ${sessionId}` };
+  }
+
+  return {
+    success: true,
+    sessionId,
+    artifacts: session.artifacts ?? [],
+    count: (session.artifacts ?? []).length
+  };
+}