@girardmedia/bootspring 1.2.0 → 2.0.3

package/intelligence/agent-collab.js

@@ -0,0 +1,2057 @@
+/**
+ * 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.
+ *
+ * Features:
+ * - Multi-agent task delegation with priority queues
+ * - Handoff protocol with context preservation
+ * - Primary agent leadership with supporting agent coordination
+ * - Dependency-aware task scheduling
+ * - Agent capability matching
+ * - Real-time collaboration state tracking
+ *
+ * @package bootspring
+ * @module intelligence/agent-collab
+ */
+
+const fs = require('fs');
+const path = require('path');
+const telemetry = require('../core/telemetry');
+
+/**
+ * Task priority levels
+ */
+const TASK_PRIORITY = {
+  CRITICAL: 'critical',
+  HIGH: 'high',
+  MEDIUM: 'medium',
+  LOW: 'low'
+};
+
+/**
+ * Task status values
+ */
+const TASK_STATUS = {
+  PENDING: 'pending',
+  IN_PROGRESS: 'in_progress',
+  BLOCKED: 'blocked',
+  COMPLETE: 'complete',
+  FAILED: 'failed'
+};
+
+/**
+ * Handoff status values
+ */
+const HANDOFF_STATUS = {
+  PENDING: 'pending',
+  ACCEPTED: 'accepted',
+  REJECTED: 'rejected',
+  COMPLETED: 'completed'
+};
+
+/**
+ * Agent roles in collaboration
+ */
+const AGENT_ROLE = {
+  PRIMARY: 'primary',
+  SUPPORTING: 'supporting',
+  SPECIALIST: 'specialist'
+};
+
+/**
+ * Get bootspring directory
+ */
+function getBootspringDir() {
+  let bootspringDir = __dirname;
+  while (!fs.existsSync(path.join(bootspringDir, 'package.json')) && bootspringDir !== '/') {
+    bootspringDir = path.dirname(bootspringDir);
+  }
+  return bootspringDir;
+}
+
+/**
+ * Collaboration state file path
+ */
+function getCollabPath() {
+  const projectRoot = process.cwd();
+  return path.join(projectRoot, '.bootspring', 'collab-state.json');
+}
+
+/**
+ * Emit telemetry event
+ */
+function emitCollabTelemetry(event, payload = {}) {
+  try {
+    telemetry.emitEvent(event, payload, { projectRoot: process.cwd() });
+  } catch {
+    // Telemetry should not block collaboration execution
+  }
+}
+
+/**
+ * Load collaboration state
+ */
+function loadCollabState() {
+  const statePath = getCollabPath();
+  if (fs.existsSync(statePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    } catch {
+      return createDefaultCollabState();
+    }
+  }
+  return createDefaultCollabState();
+}
+
+/**
+ * Create default collaboration state
+ */
+function createDefaultCollabState() {
+  return {
+    activeSessions: {},
+    pendingHandoffs: [],
+    completedSessions: [],
+    taskQueues: {},  // Per-agent task queues
+    agentStates: {}, // Current state of each agent
+    blockedTasks: [], // Tasks waiting on dependencies
+    history: [],
+    metrics: {
+      totalSessions: 0,
+      successfulSessions: 0,
+      totalHandoffs: 0,
+      totalSubtasks: 0,
+      avgSessionDuration: 0
+    }
+  };
+}
+
+/**
+ * Save collaboration state
+ */
+function saveCollabState(state) {
+  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));
+}
+
+/**
+ * Generate unique session ID
+ */
+function generateSessionId() {
+  return `collab-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Get agent registry for capability matching
+ * Thin client: agents module may not exist locally
+ * Agent contexts are now served from the API
+ */
+function getAgentRegistry() {
+  try {
+    const agentsModule = require('../agents');
+    return agentsModule.AGENTS || {};
+  } catch {
+    // Thin client fallback - use cli/agent.js AGENTS registry
+    try {
+      const agentCli = require('../cli/agent');
+      return agentCli.AGENTS || {};
+    } catch {
+      return {};
+    }
+  }
+}
+
+/**
+ * Find best agent for a task based on expertise
+ * @param {string} taskDescription - Task description
+ * @param {Array<string>} availableAgents - List of available agents
+ */
+function findBestAgentForTask(taskDescription, availableAgents = []) {
+  const registry = getAgentRegistry();
+  const descLower = taskDescription.toLowerCase();
+  const scores = [];
+
+  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 || [];
+
+    for (const skill of expertise) {
+      if (descLower.includes(skill.toLowerCase())) {
+        score += 10;
+      }
+    }
+
+    // Check description match
+    if (agent.description && descLower.includes(agent.description.toLowerCase())) {
+      score += 5;
+    }
+
+    if (score > 0) {
+      scores.push({ agentId, agent, score });
+    }
+  }
+
+  // Sort by score descending
+  scores.sort((a, b) => b.score - a.score);
+
+  return scores.length > 0 ? scores[0] : null;
+}
+
+/**
+ * Start a new collaboration session
+ * @param {object} options - Session options
+ * @param {string} options.task - Main task description
+ * @param {string} options.primaryAgent - Primary agent leading the collaboration
+ * @param {Array<string>} options.supportingAgents - Supporting agents
+ * @param {object} options.context - Initial context for the session
+ * @param {string} options.parentSessionId - Parent session if this is a nested collaboration
+ */
+function startSession(options) {
+  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();
+
+  // Initialize agent states for this session
+  const agentParticipants = {
+    [primaryAgent]: {
+      role: AGENT_ROLE.PRIMARY,
+      joinedAt: new Date().toISOString(),
+      tasksAssigned: 0,
+      tasksCompleted: 0,
+      status: 'active'
+    }
+  };
+
+  supportingAgents.forEach(agent => {
+    agentParticipants[agent] = {
+      role: AGENT_ROLE.SUPPORTING,
+      joinedAt: new Date().toISOString(),
+      tasksAssigned: 0,
+      tasksCompleted: 0,
+      status: 'standby'
+    };
+  });
+
+  const session = {
+    id: sessionId,
+    task,
+    primaryAgent,
+    supportingAgents,
+    agentParticipants,
+    status: 'active',
+    createdAt: new Date().toISOString(),
+    parentSessionId,
+    subtasks: [],
+    taskQueue: [], // Priority queue for tasks
+    handoffs: [],
+    results: {},
+    artifacts: [], // Shared artifacts between agents
+    context: {
+      initial: context,
+      current: { ...context },
+      history: []
+    },
+    checkpoints: [], // Session checkpoints for recovery
+    metrics: {
+      startTime: Date.now(),
+      handoffCount: 0,
+      delegationCount: 0,
+      blockedTime: 0
+    }
+  };
+
+  state.activeSessions[sessionId] = session;
+  state.metrics.totalSessions++;
+
+  // Initialize task queue for primary agent
+  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`
+  };
+}
+
+/**
+ * Create a subtask and delegate to an agent
+ * @param {string} sessionId - Collaboration session ID
+ * @param {object} subtask - Subtask definition
+ */
+function delegateTask(sessionId, subtask) {
+  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 = TASK_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()}`;
+
+  // Check if dependencies are met
+  const unmetDependencies = dependencies.filter(depId => {
+    const dep = session.subtasks.find(t => t.id === depId);
+    return !dep || dep.status !== TASK_STATUS.COMPLETE;
+  });
+
+  const newSubtask = {
+    id: subtaskId,
+    title,
+    description,
+    delegatedTo,
+    delegatedBy,
+    context: {
+      ...session.context.current,
+      ...context
+    },
+    priority,
+    dependencies,
+    unmetDependencies,
+    expectedDuration,
+    acceptanceCriteria,
+    artifacts,
+    status: unmetDependencies.length > 0 ? TASK_STATUS.BLOCKED : TASK_STATUS.PENDING,
+    createdAt: new Date().toISOString(),
+    startedAt: null,
+    completedAt: null,
+    result: null,
+    feedback: null,
+    retryCount: 0
+  };
+
+  session.subtasks.push(newSubtask);
+  session.metrics.delegationCount++;
+
+  // Update agent participant stats
+  if (session.agentParticipants[delegatedTo]) {
+    session.agentParticipants[delegatedTo].tasksAssigned++;
+  } else {
+    // Add new specialist agent
+    session.agentParticipants[delegatedTo] = {
+      role: AGENT_ROLE.SPECIALIST,
+      joinedAt: new Date().toISOString(),
+      tasksAssigned: 1,
+      tasksCompleted: 0,
+      status: 'active'
+    };
+  }
+
+  // Add to priority queue
+  insertIntoTaskQueue(session.taskQueue, newSubtask);
+
+  // Add to agent's global task queue
+  if (!state.taskQueues[delegatedTo]) {
+    state.taskQueues[delegatedTo] = [];
+  }
+  state.taskQueues[delegatedTo].push({
+    sessionId,
+    subtaskId,
+    priority,
+    createdAt: newSubtask.createdAt
+  });
+
+  // Track blocked tasks
+  if (newSubtask.status === TASK_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 === TASK_STATUS.BLOCKED,
+    message: newSubtask.status === TASK_STATUS.BLOCKED
+      ? `Task "${title}" delegated to ${delegatedTo} (blocked on dependencies)`
+      : `Task "${title}" delegated to ${delegatedTo}`
+  };
+}
+
+/**
+ * Insert task into priority queue maintaining priority order
+ */
+function insertIntoTaskQueue(queue, task) {
+  const priorityOrder = {
+    [TASK_PRIORITY.CRITICAL]: 0,
+    [TASK_PRIORITY.HIGH]: 1,
+    [TASK_PRIORITY.MEDIUM]: 2,
+    [TASK_PRIORITY.LOW]: 3
+  };
+
+  const taskPriority = priorityOrder[task.priority] ?? 2;
+  let inserted = false;
+
+  for (let i = 0; i < queue.length; i++) {
+    const queuePriority = priorityOrder[queue[i].priority] ?? 2;
+    if (taskPriority < queuePriority) {
+      queue.splice(i, 0, task);
+      inserted = true;
+      break;
+    }
+  }
+
+  if (!inserted) {
+    queue.push(task);
+  }
+}
+
+/**
+ * Start working on a subtask
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} subtaskId - Subtask ID
+ */
+function startSubtask(sessionId, subtaskId) {
+  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 === TASK_STATUS.BLOCKED) {
+    return {
+      success: false,
+      error: 'Subtask is blocked on dependencies',
+      unmetDependencies: subtask.unmetDependencies
+    };
+  }
+
+  if (subtask.status === TASK_STATUS.IN_PROGRESS) {
+    return { success: false, error: 'Subtask already in progress' };
+  }
+
+  subtask.status = TASK_STATUS.IN_PROGRESS;
+  subtask.startedAt = new Date().toISOString();
+
+  // Update agent status
+  if (session.agentParticipants[subtask.delegatedTo]) {
+    session.agentParticipants[subtask.delegatedTo].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}"`
+  };
+}
+
+/**
+ * Update subtask progress
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} subtaskId - Subtask ID
+ * @param {object} update - Progress update
+ */
+function updateSubtaskProgress(sessionId, subtaskId, update) {
+  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];
+    // Also add to session artifacts
+    session.artifacts.push(...artifacts.map(a => ({
+      ...a,
+      subtaskId,
+      addedAt: new Date().toISOString()
+    })));
+  }
+
+  if (blockedReason) {
+    subtask.status = TASK_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'
+  };
+}
+
+/**
+ * Complete a subtask
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} subtaskId - Subtask ID
+ * @param {object} result - Subtask result
+ */
+function completeSubtask(sessionId, subtaskId, result) {
+  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 ? TASK_STATUS.COMPLETE : TASK_STATUS.FAILED;
+  subtask.completedAt = new Date().toISOString();
+  subtask.result = {
+    output,
+    success,
+    duration: subtask.startedAt
+      ? Date.now() - new Date(subtask.startedAt).getTime()
+      : null
+  };
+
+  // Add artifacts to session
+  if (artifacts.length > 0) {
+    subtask.artifacts = [...(subtask.artifacts || []), ...artifacts];
+    session.artifacts.push(...artifacts.map(a => ({
+      ...a,
+      subtaskId,
+      addedAt: new Date().toISOString()
+    })));
+  }
+
+  // Update session context with learnings from this subtask
+  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
+    };
+  }
+
+  // Store learnings
+  if (learnings.length > 0) {
+    session.learnings = session.learnings || [];
+    session.learnings.push(...learnings.map(l => ({
+      ...l,
+      subtaskId,
+      agent: subtask.delegatedTo,
+      timestamp: new Date().toISOString()
+    })));
+  }
+
+  session.results[subtaskId] = result;
+
+  // Update agent participant stats
+  if (session.agentParticipants[subtask.delegatedTo]) {
+    session.agentParticipants[subtask.delegatedTo].tasksCompleted++;
+    session.agentParticipants[subtask.delegatedTo].status = 'standby';
+  }
+
+  // Remove from agent's task queue
+  if (state.taskQueues[subtask.delegatedTo]) {
+    state.taskQueues[subtask.delegatedTo] = state.taskQueues[subtask.delegatedTo]
+      .filter(t => !(t.sessionId === sessionId && t.subtaskId === subtaskId));
+  }
+
+  // Unblock dependent tasks
+  const unblockedTasks = [];
+  session.subtasks.forEach(t => {
+    if (t.status === TASK_STATUS.BLOCKED && t.dependencies.includes(subtaskId)) {
+      t.unmetDependencies = t.unmetDependencies.filter(d => d !== subtaskId);
+      if (t.unmetDependencies.length === 0) {
+        t.status = TASK_STATUS.PENDING;
+        unblockedTasks.push(t.id);
+      }
+    }
+  });
+
+  // Remove from blocked tasks list
+  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
+  });
+
+  // Check if all subtasks are complete
+  const allComplete = session.subtasks.every(
+    s => s.status === TASK_STATUS.COMPLETE || s.status === TASK_STATUS.FAILED
+  );
+  const allSuccessful = session.subtasks.every(s => s.status === TASK_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`
+  };
+}
+
+/**
+ * Fail a subtask
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} subtaskId - Subtask ID
+ * @param {object} failure - Failure details
+ */
+function failSubtask(sessionId, subtaskId, failure) {
+  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 = TASK_STATUS.FAILED;
+  subtask.completedAt = new Date().toISOString();
+  subtask.failure = {
+    reason,
+    canRetry,
+    suggestedAction,
+    failedAt: new Date().toISOString()
+  };
+  subtask.retryCount++;
+
+  // Update agent status
+  if (session.agentParticipants[subtask.delegatedTo]) {
+    session.agentParticipants[subtask.delegatedTo].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}`
+  };
+}
+
+/**
+ * Retry a failed subtask
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} subtaskId - Subtask ID
+ * @param {object} options - Retry options
+ */
+function retrySubtask(sessionId, subtaskId, options = {}) {
+  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 !== TASK_STATUS.FAILED) {
+    return { success: false, error: 'Can only retry failed subtasks' };
+  }
+
+  const { reassignTo, additionalContext = {} } = options;
+
+  // Reset subtask state
+  subtask.status = TASK_STATUS.PENDING;
+  subtask.completedAt = null;
+  subtask.startedAt = null;
+  subtask.result = null;
+
+  // Optionally reassign to different agent
+  if (reassignTo) {
+    subtask.delegatedTo = reassignTo;
+    subtask.reassignedFrom = subtask.delegatedTo;
+  }
+
+  // Add additional context
+  if (Object.keys(additionalContext).length > 0) {
+    subtask.context = {
+      ...subtask.context,
+      ...additionalContext,
+      previousAttemptFailed: true
+    };
+  }
+
+  // Re-add to task queue
+  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`
+  };
+}
+
+/**
+ * Request handoff from one agent to another
+ * @param {string} sessionId - Collaboration session ID
+ * @param {object} handoff - Handoff details
+ */
+function requestHandoff(sessionId, handoff) {
+  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()}`;
+
+  // Collect context for handoff
+  const handoffContext = {
+    ...session.context.current,
+    ...context,
+    handoffReason: reason,
+    previousAgent: fromAgent,
+    sessionProgress: {
+      completedSubtasks: session.subtasks.filter(s => s.status === TASK_STATUS.COMPLETE).length,
+      totalSubtasks: session.subtasks.length,
+      artifacts: session.artifacts.length
+    }
+  };
+
+  // If transferring a specific subtask, include its context
+  let transferredSubtask = null;
+  if (subtaskId) {
+    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 = {
+    id: handoffId,
+    fromAgent,
+    toAgent,
+    reason,
+    context: handoffContext,
+    artifacts,
+    transferPrimaryRole,
+    subtaskId,
+    urgency,
+    expectedDuration,
+    status: HANDOFF_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}`
+  };
+}
+
+/**
+ * Accept a handoff
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} handoffId - Handoff ID
+ * @param {object} options - Accept options
+ */
+function acceptHandoff(sessionId, handoffId, options = {}) {
+  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 !== HANDOFF_STATUS.PENDING) {
+    return { success: false, error: `Handoff already ${handoff.status}` };
+  }
+
+  const { acknowledgment = null, estimatedCompletion = null } = options;
+
+  handoff.status = HANDOFF_STATUS.ACCEPTED;
+  handoff.acceptedAt = new Date().toISOString();
+  handoff.acknowledgment = acknowledgment;
+  handoff.estimatedCompletion = estimatedCompletion;
+
+  // Update primary agent if this was a primary role transfer
+  const previousPrimary = session.primaryAgent;
+  if (handoff.transferPrimaryRole) {
+    session.primaryAgent = handoff.toAgent;
+
+    // Update agent roles
+    if (session.agentParticipants[previousPrimary]) {
+      session.agentParticipants[previousPrimary].role = AGENT_ROLE.SUPPORTING;
+    }
+    if (session.agentParticipants[handoff.toAgent]) {
+      session.agentParticipants[handoff.toAgent].role = AGENT_ROLE.PRIMARY;
+    }
+  }
+
+  // Transfer subtask if specified
+  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()
+      });
+    }
+  }
+
+  // Update agent states
+  if (session.agentParticipants[handoff.toAgent]) {
+    session.agentParticipants[handoff.toAgent].status = 'active';
+  }
+
+  // Remove from pending
+  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}`
+  };
+}
+
+/**
+ * Reject a handoff
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} handoffId - Handoff ID
+ * @param {string} reason - Rejection reason
+ */
+function rejectHandoff(sessionId, handoffId, reason) {
+  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 !== HANDOFF_STATUS.PENDING) {
+    return { success: false, error: `Handoff already ${handoff.status}` };
+  }
+
+  handoff.status = HANDOFF_STATUS.REJECTED;
+  handoff.rejectionReason = reason;
+  handoff.rejectedAt = new Date().toISOString();
+
+  // Remove from pending
+  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}`
+  };
+}
+
+/**
+ * Complete a handoff (mark work as done)
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} handoffId - Handoff ID
+ * @param {object} result - Handoff result
+ */
+function completeHandoff(sessionId, handoffId, result = {}) {
+  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 !== HANDOFF_STATUS.ACCEPTED) {
+    return { success: false, error: 'Handoff must be accepted before completing' };
+  }
+
+  handoff.status = 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}`
+  };
+}
+
+/**
+ * Create a checkpoint for session recovery
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} description - Checkpoint description
+ */
+function createCheckpoint(sessionId, description = '') {
+  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 = {
+    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}`
+  };
+}
+
+/**
+ * Restore session from checkpoint
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} checkpointId - Checkpoint ID
+ */
+function restoreFromCheckpoint(sessionId, checkpointId) {
+  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}` };
+  }
+
+  // Restore from snapshot
+  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}`
+  };
+}
+
+/**
+ * Finalize collaboration session
+ * @param {string} sessionId - Collaboration session ID
+ * @param {object} summary - Final summary
+ */
+function finalizeSession(sessionId, summary = {}) {
+  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 === TASK_STATUS.COMPLETE);
+  const failedSubtasks = session.subtasks.filter(s => s.status === TASK_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 === HANDOFF_STATUS.ACCEPTED).length,
+    rejectedHandoffs: session.handoffs.filter(h => h.status === HANDOFF_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
+  };
+
+  // Calculate success rate
+  session.summary.successRate = session.subtasks.length > 0
+    ? Math.round((completedSubtasks.length / session.subtasks.length) * 100)
+    : 100;
+
+  // Move to completed
+  state.completedSessions.push(session);
+  delete state.activeSessions[sessionId];
+
+  // Clean up agent task queues
+  for (const agent of Object.keys(session.agentParticipants)) {
+    if (state.taskQueues[agent]) {
+      state.taskQueues[agent] = state.taskQueues[agent]
+        .filter(t => t.sessionId !== sessionId);
+    }
+  }
+
+  // Update global metrics
+  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,
+    summary: session.summary,
+    message: 'Collaboration session finalized'
+  };
+}
+
+/**
+ * Abort a collaboration session
+ * @param {string} sessionId - Collaboration session ID
+ * @param {string} reason - Abort reason
+ */
+function abortSession(sessionId, reason = '') {
+  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;
+
+  // Move to completed (as aborted)
+  state.completedSessions.push(session);
+  delete state.activeSessions[sessionId];
+
+  // Clean up pending handoffs
+  state.pendingHandoffs = state.pendingHandoffs
+    .filter(h => h.sessionId !== sessionId);
+
+  // Clean up agent task queues
+  for (const agent of Object.keys(session.agentParticipants)) {
+    if (state.taskQueues[agent]) {
+      state.taskQueues[agent] = state.taskQueues[agent]
+        .filter(t => t.sessionId !== sessionId);
+    }
+  }
+
+  state.history.push({
+    action: 'session_aborted',
+    sessionId,
+    reason,
+    timestamp: new Date().toISOString()
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    sessionId,
+    reason,
+    message: `Collaboration session aborted: ${reason}`
+  };
+}
+
+/**
+ * Format duration in human-readable format
+ */
+function formatDuration(ms) {
+  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`;
+}
+
+/**
+ * Get session status
+ * @param {string} sessionId - Collaboration session ID
+ */
+function getSessionStatus(sessionId) {
+  const state = loadCollabState();
+  const session = state.activeSessions[sessionId];
+
+  if (!session) {
+    // Check completed sessions
+    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 === TASK_STATUS.PENDING);
+  const inProgressSubtasks = session.subtasks.filter(s => s.status === TASK_STATUS.IN_PROGRESS);
+  const blockedSubtasks = session.subtasks.filter(s => s.status === TASK_STATUS.BLOCKED);
+  const completedSubtasks = session.subtasks.filter(s => s.status === TASK_STATUS.COMPLETE);
+  const failedSubtasks = session.subtasks.filter(s => s.status === TASK_STATUS.FAILED);
+  const pendingHandoffs = session.handoffs.filter(h => h.status === HANDOFF_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 === HANDOFF_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)
+  };
+}
+
+/**
+ * Get suggested next actions for a session
+ */
+function getNextActions(session, pendingSubtasks, pendingHandoffs, blockedSubtasks) {
+  const actions = [];
+
+  // Pending handoffs need attention
+  if (pendingHandoffs.length > 0) {
+    actions.push({
+      type: 'accept_handoffs',
+      urgency: 'high',
+      count: pendingHandoffs.length,
+      message: `${pendingHandoffs.length} handoff(s) awaiting acceptance`
+    });
+  }
+
+  // Blocked tasks need resolution
+  if (blockedSubtasks.length > 0) {
+    actions.push({
+      type: 'resolve_blockers',
+      urgency: 'medium',
+      count: blockedSubtasks.length,
+      message: `${blockedSubtasks.length} task(s) blocked on dependencies`
+    });
+  }
+
+  // Pending tasks ready to start
+  if (pendingSubtasks.length > 0) {
+    const highPriority = pendingSubtasks.filter(t => t.priority === TASK_PRIORITY.HIGH || t.priority === TASK_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`
+      });
+    }
+  }
+
+  // Check if ready to finalize
+  const allComplete = session.subtasks.length > 0 &&
+    session.subtasks.every(s =>
+      s.status === TASK_STATUS.COMPLETE || s.status === TASK_STATUS.FAILED
+    );
+
+  if (allComplete) {
+    actions.push({
+      type: 'finalize_session',
+      urgency: 'low',
+      message: 'All tasks processed. Ready to finalize session.'
+    });
+  }
+
+  return actions;
+}
+
+/**
+ * Get the next task for an agent
+ * @param {string} agentName - Agent name
+ */
+function getNextTaskForAgent(agentName) {
+  const state = loadCollabState();
+  const agentQueue = state.taskQueues[agentName] || [];
+
+  if (agentQueue.length === 0) {
+    return { hasTask: false, message: 'No tasks in queue' };
+  }
+
+  // Sort by priority and creation time
+  const priorityOrder = {
+    [TASK_PRIORITY.CRITICAL]: 0,
+    [TASK_PRIORITY.HIGH]: 1,
+    [TASK_PRIORITY.MEDIUM]: 2,
+    [TASK_PRIORITY.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) - new Date(b.createdAt);
+  });
+
+  const nextItem = agentQueue[0];
+  const session = state.activeSessions[nextItem.sessionId];
+
+  if (!session) {
+    // Task from completed/aborted session, remove it
+    state.taskQueues[agentName] = agentQueue.slice(1);
+    saveCollabState(state);
+    return getNextTaskForAgent(agentName); // Recurse
+  }
+
+  const subtask = session.subtasks.find(s => s.id === nextItem.subtaskId);
+
+  if (!subtask || subtask.status === TASK_STATUS.BLOCKED) {
+    // Skip blocked tasks
+    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}`
+  };
+}
+
+/**
+ * List active sessions
+ */
+function listActiveSessions() {
+  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
+  }));
+}
+
+/**
+ * Get pending handoffs for an agent
+ * @param {string} agentName - Agent name
+ */
+function getPendingHandoffsForAgent(agentName) {
+  const state = loadCollabState();
+
+  return state.pendingHandoffs.filter(h => h.toAgent === agentName);
+}
+
+/**
+ * Collaboration patterns for common scenarios
+ */
+const COLLAB_PATTERNS = {
+  '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: TASK_PRIORITY.HIGH },
+      { title: 'Performance Review', delegatedTo: 'performance-expert', priority: TASK_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: TASK_PRIORITY.CRITICAL },
+      { title: 'Database Schema', delegatedTo: 'database-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'API Implementation', delegatedTo: 'backend-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-2'] },
+      { title: 'UI Implementation', delegatedTo: 'frontend-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Integration Tests', delegatedTo: 'testing-expert', priority: TASK_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: TASK_PRIORITY.CRITICAL },
+      { title: 'Code Security Fixes', delegatedTo: 'backend-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Infrastructure Hardening', delegatedTo: 'devops-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Security Verification', delegatedTo: 'security-expert', priority: TASK_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: TASK_PRIORITY.CRITICAL },
+      { title: 'Data Model', delegatedTo: 'database-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'API Implementation', delegatedTo: 'api-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-2'] },
+      { title: 'Security Review', delegatedTo: 'security-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-3'] },
+      { title: 'API Tests', delegatedTo: 'testing-expert', priority: TASK_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: TASK_PRIORITY.CRITICAL },
+      { title: 'UI/UX Design', delegatedTo: 'ui-ux-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Data Model', delegatedTo: 'database-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Backend API', delegatedTo: 'backend-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-3'] },
+      { title: 'Frontend UI', delegatedTo: 'frontend-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-2', 'subtask-4'] },
+      { title: 'Integration Testing', delegatedTo: 'testing-expert', priority: TASK_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: TASK_PRIORITY.CRITICAL },
+      { title: 'Database Optimization', delegatedTo: 'database-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Backend Optimization', delegatedTo: 'backend-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Frontend Optimization', delegatedTo: 'frontend-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1'] },
+      { title: 'Performance Verification', delegatedTo: 'performance-expert', priority: TASK_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: TASK_PRIORITY.CRITICAL },
+      { title: 'Performance Testing', delegatedTo: 'performance-expert', priority: TASK_PRIORITY.CRITICAL },
+      { title: 'End-to-End Tests', delegatedTo: 'testing-expert', priority: TASK_PRIORITY.HIGH },
+      { title: 'Deployment Config', delegatedTo: 'devops-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-1', 'subtask-2'] },
+      { title: 'Launch Verification', delegatedTo: 'devops-expert', priority: TASK_PRIORITY.HIGH, dependencies: ['subtask-3', 'subtask-4'] }
+    ]
+  }
+};
+
+/**
+ * Start session from pattern
+ * @param {string} patternName - Pattern name
+ * @param {string} task - Task description
+ * @param {object} options - Additional options
+ */
+function startFromPattern(patternName, task, options = {}) {
+  const pattern = COLLAB_PATTERNS[patternName];
+  if (!pattern) {
+    return {
+      success: false,
+      error: `Unknown pattern: ${patternName}`,
+      availablePatterns: Object.keys(COLLAB_PATTERNS)
+    };
+  }
+
+  const { context = {}, autoStart = false } = options;
+
+  // Start session
+  const sessionResult = startSession({
+    task,
+    primaryAgent: pattern.primaryAgent,
+    supportingAgents: pattern.supportingAgents,
+    context: {
+      pattern: patternName,
+      ...context
+    }
+  });
+
+  if (!sessionResult.success) {
+    return sessionResult;
+  }
+
+  // Create subtasks from template, mapping template dependencies to real IDs
+  const subtaskResults = [];
+  const idMapping = {};
+
+  for (let i = 0; i < pattern.subtaskTemplate.length; i++) {
+    const template = pattern.subtaskTemplate[i];
+    const templateId = `subtask-${i + 1}`;
+
+    // Map template dependencies to actual subtask IDs
+    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) {
+      idMapping[templateId] = result.subtaskId;
+    }
+    subtaskResults.push(result);
+  }
+
+  // Auto-start first task if requested
+  if (autoStart && subtaskResults.length > 0 && subtaskResults[0].success) {
+    startSubtask(sessionResult.sessionId, subtaskResults[0].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`
+  };
+}
+
+/**
+ * Get collaboration statistics
+ */
+function getCollabStats() {
+  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
+  };
+}
+
+/**
+ * Get session history
+ * @param {string} sessionId - Optional session ID for filtered history
+ */
+function getSessionHistory(sessionId = null) {
+  const state = loadCollabState();
+
+  if (sessionId) {
+    return state.history.filter(h => h.sessionId === sessionId);
+  }
+
+  return state.history.slice(-100); // Last 100 events
+}
+
+/**
+ * List available patterns
+ */
+function listPatterns() {
+  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
+  }));
+}
+
+/**
+ * Broadcast message to all agents in a session
+ * @param {string} sessionId - Collaboration session ID
+ * @param {object} message - Message to broadcast
+ */
+function broadcastToSession(sessionId, message) {
+  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 = {
+    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`
+  };
+}
+
+/**
+ * Share an artifact with the session
+ * @param {string} sessionId - Collaboration session ID
+ * @param {object} artifact - Artifact to share
+ */
+function shareArtifact(sessionId, artifact) {
+  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 = {
+    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
+  });
+
+  saveCollabState(state);
+
+  return {
+    success: true,
+    artifactId: sharedArtifact.id,
+    message: `Artifact "${name}" shared with session`
+  };
+}
+
+/**
+ * Get all artifacts from a session
+ * @param {string} sessionId - Collaboration session ID
+ */
+function getSessionArtifacts(sessionId) {
+  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
+  };
+}
+
+module.exports = {
+  // Session management
+  startSession,
+  finalizeSession,
+  abortSession,
+  getSessionStatus,
+  listActiveSessions,
+  getSessionHistory,
+
+  // Task delegation
+  delegateTask,
+  startSubtask,
+  updateSubtaskProgress,
+  completeSubtask,
+  failSubtask,
+  retrySubtask,
+  getNextTaskForAgent,
+
+  // Handoff protocol
+  requestHandoff,
+  acceptHandoff,
+  rejectHandoff,
+  completeHandoff,
+  getPendingHandoffsForAgent,
+
+  // Checkpoints and recovery
+  createCheckpoint,
+  restoreFromCheckpoint,
+
+  // Patterns
+  startFromPattern,
+  listPatterns,
+  COLLAB_PATTERNS,
+
+  // Communication
+  broadcastToSession,
+  shareArtifact,
+  getSessionArtifacts,
+
+  // Agent capabilities
+  findBestAgentForTask,
+
+  // Statistics and state
+  getCollabStats,
+  loadCollabState,
+
+  // Constants
+  TASK_PRIORITY,
+  TASK_STATUS,
+  HANDOFF_STATUS,
+  AGENT_ROLE
+};