chati-dev 1.4.0 → 2.0.2

package/src/tasks/handoff.js

@@ -0,0 +1,226 @@
+/**
+ * Handoff Manager — Manages context handoffs between tasks and agents.
+ *
+ * A handoff preserves critical context when execution transitions from
+ * one agent to another. It captures what was done, what was produced,
+ * and what the next agent needs to know.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Build a handoff document from task execution results.
+ *
+ * @param {object} params
+ * @param {object} params.task - Completed task definition
+ * @param {object} [params.validation] - Validation results
+ * @param {string[]} [params.outputs] - Produced artifact paths
+ * @param {object} [params.decisions] - Key decisions made during execution
+ * @param {string} [params.summary] - Human-readable summary
+ * @param {string[]} [params.blockers] - Unresolved issues
+ * @returns {object} Handoff document
+ */
+export function buildHandoff(params) {
+  const { task, validation, outputs, decisions, summary, blockers } = params;
+
+  return {
+    from: {
+      agent: task.agent,
+      task_id: task.id,
+      phase: task.phase,
+    },
+    to: task.handoff_to || null,
+    timestamp: new Date().toISOString(),
+    status: validation?.valid ? 'complete' : 'partial',
+    score: validation?.score ?? null,
+    summary: summary || `Task ${task.id} completed.`,
+    outputs: outputs || task.outputs || [],
+    decisions: decisions || {},
+    blockers: blockers || [],
+    criteria_met: task.criteria.filter((_, i) => {
+      const unmet = new Set(validation?.unmet || []);
+      return !unmet.has(task.criteria[i]);
+    }),
+    criteria_unmet: validation?.unmet || [],
+  };
+}
+
+/**
+ * Serialize a handoff document to YAML-like markdown.
+ *
+ * @param {object} handoff - Handoff document from buildHandoff
+ * @returns {string} Formatted handoff string
+ */
+export function formatHandoff(handoff) {
+  const lines = [
+    '---',
+    `from_agent: ${handoff.from.agent}`,
+    `from_task: ${handoff.from.task_id}`,
+    `from_phase: ${handoff.from.phase}`,
+    `to: ${handoff.to || 'orchestrator'}`,
+    `timestamp: ${handoff.timestamp}`,
+    `status: ${handoff.status}`,
+    `score: ${handoff.score ?? 'N/A'}`,
+    '---',
+    '',
+    `# Handoff: ${handoff.from.agent} → ${handoff.to || 'orchestrator'}`,
+    '',
+    '## Summary',
+    handoff.summary,
+    '',
+  ];
+
+  if (handoff.outputs.length > 0) {
+    lines.push('## Outputs');
+    for (const output of handoff.outputs) {
+      lines.push(`- ${output}`);
+    }
+    lines.push('');
+  }
+
+  if (Object.keys(handoff.decisions).length > 0) {
+    lines.push('## Decisions');
+    for (const [key, value] of Object.entries(handoff.decisions)) {
+      lines.push(`- **${key}**: ${value}`);
+    }
+    lines.push('');
+  }
+
+  if (handoff.blockers.length > 0) {
+    lines.push('## Blockers');
+    for (const blocker of handoff.blockers) {
+      lines.push(`- ${blocker}`);
+    }
+    lines.push('');
+  }
+
+  if (handoff.criteria_met.length > 0) {
+    lines.push('## Criteria Met');
+    for (const c of handoff.criteria_met) {
+      lines.push(`- [x] ${c}`);
+    }
+    lines.push('');
+  }
+
+  if (handoff.criteria_unmet.length > 0) {
+    lines.push('## Criteria Unmet');
+    for (const c of handoff.criteria_unmet) {
+      lines.push(`- [ ] ${c}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Save a handoff document to the artifacts directory.
+ *
+ * @param {string} projectDir - Project root directory
+ * @param {object} handoff - Handoff document
+ * @returns {{ saved: boolean, path: string|null, error: string|null }}
+ */
+export function saveHandoff(projectDir, handoff) {
+  try {
+    const handoffsDir = join(projectDir, 'chati.dev', 'artifacts', 'handoffs');
+    if (!existsSync(handoffsDir)) {
+      mkdirSync(handoffsDir, { recursive: true });
+    }
+
+    const filename = `${handoff.from.agent}-handoff.md`;
+    const filePath = join(handoffsDir, filename);
+    const content = formatHandoff(handoff);
+
+    writeFileSync(filePath, content, 'utf-8');
+    return { saved: true, path: filePath, error: null };
+  } catch (err) {
+    return { saved: false, path: null, error: `Failed to save handoff: ${err.message}` };
+  }
+}
+
+/**
+ * Load the most recent handoff from a specific agent.
+ *
+ * @param {string} projectDir - Project root directory
+ * @param {string} agentName - Agent that produced the handoff
+ * @returns {{ loaded: boolean, handoff: object|null, error: string|null }}
+ */
+export function loadHandoff(projectDir, agentName) {
+  const filePath = join(projectDir, 'chati.dev', 'artifacts', 'handoffs', `${agentName}-handoff.md`);
+
+  if (!existsSync(filePath)) {
+    return { loaded: false, handoff: null, error: `No handoff found from agent '${agentName}'.` };
+  }
+
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = parseHandoffContent(raw);
+    return { loaded: true, handoff: parsed, error: null };
+  } catch (err) {
+    return { loaded: false, handoff: null, error: `Failed to parse handoff: ${err.message}` };
+  }
+}
+
+/**
+ * Parse a handoff markdown document back into structured data.
+ *
+ * @param {string} content - Handoff file content
+ * @returns {object} Parsed handoff data
+ */
+export function parseHandoffContent(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+
+  const meta = {};
+  let body = content;
+
+  if (frontmatterMatch) {
+    const yamlPart = frontmatterMatch[1];
+    body = frontmatterMatch[2];
+
+    for (const line of yamlPart.split('\n')) {
+      const match = line.match(/^(\w[\w_-]*):\s*(.+)$/);
+      if (match) {
+        meta[match[1]] = match[2].trim();
+      }
+    }
+  }
+
+  // Extract sections from body
+  const sections = {};
+  let currentSection = null;
+  const sectionLines = {};
+
+  for (const line of body.split('\n')) {
+    const headerMatch = line.match(/^## (.+)/);
+    if (headerMatch) {
+      currentSection = headerMatch[1].toLowerCase().replace(/\s+/g, '_');
+      sectionLines[currentSection] = [];
+    } else if (currentSection) {
+      sectionLines[currentSection].push(line);
+    }
+  }
+
+  // Parse list items from sections
+  for (const [key, lines] of Object.entries(sectionLines)) {
+    sections[key] = lines
+      .map(l => l.trim())
+      .filter(l => l.startsWith('- '))
+      .map(l => l.replace(/^- (\[.\] )?/, '').trim());
+  }
+
+  return {
+    from_agent: meta.from_agent || null,
+    from_task: meta.from_task || null,
+    to: meta.to || null,
+    timestamp: meta.timestamp || null,
+    status: meta.status || 'unknown',
+    score: meta.score !== 'N/A' ? parseInt(meta.score, 10) || null : null,
+    summary: (sectionLines.summary || []).join(' ').trim(),
+    outputs: sections.outputs || [],
+    decisions: sections.decisions || [],
+    blockers: sections.blockers || [],
+    criteria_met: sections.criteria_met || [],
+    criteria_unmet: sections.criteria_unmet || [],
+  };
+}

package/src/tasks/index.js

@@ -0,0 +1,4 @@
+export { loadTask, parseTaskContent, loadAllTasks, getAgentTasks, getTaskSummary } from './loader.js';
+export { TaskRouter, createRouter } from './router.js';
+export { buildExecutionPayload, validateResults, determinePostAction } from './executor.js';
+export { buildHandoff, formatHandoff, saveHandoff, loadHandoff, parseHandoffContent } from './handoff.js';

package/src/tasks/loader.js

@@ -0,0 +1,210 @@
+/**
+ * Task Loader — Parses task definition files (YAML frontmatter + markdown body).
+ *
+ * Task files live in chati.dev/tasks/{agent}-{action}.md and contain:
+ * - YAML frontmatter: id, agent, trigger, phase, requires_input, parallelizable, outputs, handoff_to, autonomous_gate, criteria
+ * - Markdown body: Step-by-step instructions for the agent
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Parse a single task definition file.
+ * @param {string} filePath - Absolute path to .md file with YAML frontmatter
+ * @returns {{ loaded: boolean, task: object|null, error: string|null }}
+ */
+export function loadTask(filePath) {
+  if (!existsSync(filePath)) {
+    return { loaded: false, task: null, error: `Task file not found: ${filePath}` };
+  }
+
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    return parseTaskContent(raw, filePath);
+  } catch (err) {
+    return { loaded: false, task: null, error: `Failed to read ${filePath}: ${err.message}` };
+  }
+}
+
+/**
+ * Parse task content string (YAML frontmatter + markdown body).
+ * @param {string} content - Raw file content
+ * @param {string} [source] - Source file path for error messages
+ * @returns {{ loaded: boolean, task: object|null, error: string|null }}
+ */
+export function parseTaskContent(content, source = 'unknown') {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+
+  if (!frontmatterMatch) {
+    return { loaded: false, task: null, error: `No YAML frontmatter found in ${source}` };
+  }
+
+  const yamlStr = frontmatterMatch[1];
+  const body = frontmatterMatch[2].trim();
+
+  try {
+    const meta = parseSimpleYaml(yamlStr);
+
+    if (!meta.id) {
+      return { loaded: false, task: null, error: `Missing required field 'id' in ${source}` };
+    }
+    if (!meta.agent) {
+      return { loaded: false, task: null, error: `Missing required field 'agent' in ${source}` };
+    }
+
+    return {
+      loaded: true,
+      task: {
+        id: meta.id,
+        agent: meta.agent,
+        trigger: meta.trigger || 'orchestrator',
+        phase: meta.phase || 'clarity',
+        requires_input: meta.requires_input === true || meta.requires_input === 'true',
+        parallelizable: meta.parallelizable === true || meta.parallelizable === 'true',
+        outputs: parseArray(meta.outputs),
+        handoff_to: meta.handoff_to || null,
+        autonomous_gate: meta.autonomous_gate !== false && meta.autonomous_gate !== 'false',
+        criteria: parseArray(meta.criteria),
+        instructions: body,
+        source,
+      },
+      error: null,
+    };
+  } catch (err) {
+    return { loaded: false, task: null, error: `YAML parse error in ${source}: ${err.message}` };
+  }
+}
+
+/**
+ * Load all task definitions from a directory.
+ * @param {string} tasksDir - Path to chati.dev/tasks/
+ * @returns {{ tasks: Map<string, object>, errors: string[] }}
+ */
+export function loadAllTasks(tasksDir) {
+  const tasks = new Map();
+  const errors = [];
+
+  if (!existsSync(tasksDir)) {
+    errors.push(`Tasks directory not found: ${tasksDir}`);
+    return { tasks, errors };
+  }
+
+  const files = readdirSync(tasksDir).filter(f => f.endsWith('.md'));
+
+  for (const file of files) {
+    const result = loadTask(join(tasksDir, file));
+    if (result.loaded) {
+      tasks.set(result.task.id, result.task);
+    } else {
+      errors.push(result.error);
+    }
+  }
+
+  return { tasks, errors };
+}
+
+/**
+ * Get all tasks for a specific agent.
+ * @param {Map<string, object>} taskMap - Map from loadAllTasks
+ * @param {string} agentName - Agent name to filter by
+ * @returns {object[]}
+ */
+export function getAgentTasks(taskMap, agentName) {
+  const result = [];
+  for (const task of taskMap.values()) {
+    if (task.agent === agentName) {
+      result.push(task);
+    }
+  }
+  return result;
+}
+
+/**
+ * Get a task's info summary (without instructions body).
+ * @param {object} task - Task object from loadTask
+ * @returns {object}
+ */
+export function getTaskSummary(task) {
+  return {
+    id: task.id,
+    agent: task.agent,
+    phase: task.phase,
+    parallelizable: task.parallelizable,
+    outputs: task.outputs,
+    handoff_to: task.handoff_to,
+    criteria_count: task.criteria.length,
+  };
+}
+
+/**
+ * Simple YAML parser for frontmatter (no external deps).
+ * Handles key: value, key: [array], and key: true/false.
+ */
+function parseSimpleYaml(str) {
+  const result = {};
+  let currentKey = null;
+  let currentArray = null;
+
+  for (const line of str.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Array item under current key
+    if (trimmed.startsWith('- ') && currentKey && currentArray) {
+      currentArray.push(trimmed.slice(2).trim());
+      continue;
+    }
+
+    // Key: value pair
+    const kvMatch = trimmed.match(/^(\w[\w_-]*):\s*(.*)$/);
+    if (kvMatch) {
+      // Save previous array if any
+      if (currentKey && currentArray) {
+        result[currentKey] = currentArray;
+      }
+
+      const key = kvMatch[1];
+      const val = kvMatch[2].trim();
+
+      if (val === '') {
+        // Could be start of an array
+        currentKey = key;
+        currentArray = [];
+      } else if (val.startsWith('[') && val.endsWith(']')) {
+        // Inline array: [a, b, c]
+        result[key] = val.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+        currentKey = null;
+        currentArray = null;
+      } else if (val === 'true') {
+        result[key] = true;
+        currentKey = null;
+        currentArray = null;
+      } else if (val === 'false') {
+        result[key] = false;
+        currentKey = null;
+        currentArray = null;
+      } else {
+        result[key] = val;
+        currentKey = null;
+        currentArray = null;
+      }
+    }
+  }
+
+  // Save trailing array
+  if (currentKey && currentArray) {
+    result[currentKey] = currentArray;
+  }
+
+  return result;
+}
+
+/**
+ * Ensure a value is an array.
+ */
+function parseArray(val) {
+  if (Array.isArray(val)) return val;
+  if (typeof val === 'string') return [val];
+  return [];
+}

package/src/tasks/router.js

@@ -0,0 +1,182 @@
+/**
+ * Task Router — Maps orchestrator intents to the correct task definition.
+ *
+ * The router is used internally by the orchestrator to determine
+ * which task an agent should execute based on:
+ * - Current pipeline position
+ * - Agent state
+ * - User intent signals
+ */
+
+import { loadAllTasks, getAgentTasks } from './loader.js';
+
+/**
+ * Task Router instance.
+ * Holds the loaded task registry and provides routing methods.
+ */
+export class TaskRouter {
+  /**
+   * @param {string} tasksDir - Path to chati.dev/tasks/
+   */
+  constructor(tasksDir) {
+    this.tasksDir = tasksDir;
+    this.taskMap = new Map();
+    this.errors = [];
+    this.loaded = false;
+  }
+
+  /**
+   * Initialize the router by loading all task definitions.
+   * @returns {this}
+   */
+  load() {
+    const result = loadAllTasks(this.tasksDir);
+    this.taskMap = result.tasks;
+    this.errors = result.errors;
+    this.loaded = true;
+    return this;
+  }
+
+  /**
+   * Route to the correct task for an agent at a given pipeline position.
+   *
+   * Routing priority:
+   * 1. Exact task ID match (if provided)
+   * 2. Agent's consolidate task (if pipeline position = consolidate)
+   * 3. Agent's first non-consolidate task (default entry point)
+   *
+   * @param {object} intent
+   * @param {string} intent.agent - Target agent name
+   * @param {string} [intent.taskId] - Explicit task ID (highest priority)
+   * @param {string} [intent.action] - Action keyword (e.g., 'consolidate', 'extract')
+   * @param {string} [intent.phase] - Pipeline phase filter
+   * @returns {{ found: boolean, task: object|null, reason: string }}
+   */
+  route(intent) {
+    if (!this.loaded) {
+      return { found: false, task: null, reason: 'Router not loaded. Call load() first.' };
+    }
+
+    if (!intent || !intent.agent) {
+      return { found: false, task: null, reason: 'No agent specified in routing intent.' };
+    }
+
+    // 1. Exact task ID match
+    if (intent.taskId) {
+      const task = this.taskMap.get(intent.taskId);
+      if (task) {
+        return { found: true, task, reason: `Exact match: ${intent.taskId}` };
+      }
+      return { found: false, task: null, reason: `Task ID '${intent.taskId}' not found in registry.` };
+    }
+
+    // Get all tasks for this agent
+    const agentTasks = getAgentTasks(this.taskMap, intent.agent);
+    if (agentTasks.length === 0) {
+      return { found: false, task: null, reason: `No tasks registered for agent '${intent.agent}'.` };
+    }
+
+    // Filter by phase if provided
+    let candidates = agentTasks;
+    if (intent.phase) {
+      const phaseFiltered = agentTasks.filter(t => t.phase === intent.phase);
+      if (phaseFiltered.length > 0) {
+        candidates = phaseFiltered;
+      }
+    }
+
+    // 2. Action keyword match
+    if (intent.action) {
+      const actionTask = candidates.find(t =>
+        t.id.includes(intent.action) || t.id.endsWith(`-${intent.action}`)
+      );
+      if (actionTask) {
+        return { found: true, task: actionTask, reason: `Action match: ${intent.action}` };
+      }
+    }
+
+    // 3. Consolidate task (if action is consolidate or implied)
+    if (intent.action === 'consolidate') {
+      const consolidateTask = candidates.find(t => t.id.endsWith('-consolidate'));
+      if (consolidateTask) {
+        return { found: true, task: consolidateTask, reason: 'Consolidate task selected.' };
+      }
+    }
+
+    // 4. Default: first non-consolidate task (entry point)
+    const entryTask = candidates.find(t => !t.id.endsWith('-consolidate')) || candidates[0];
+    return { found: true, task: entryTask, reason: `Default entry: ${entryTask.id}` };
+  }
+
+  /**
+   * Get the next task in an agent's task sequence.
+   * Uses the handoff_to field to determine chaining.
+   *
+   * @param {string} currentTaskId - Currently executing task ID
+   * @returns {{ found: boolean, task: object|null, reason: string }}
+   */
+  getNextTask(currentTaskId) {
+    const current = this.taskMap.get(currentTaskId);
+    if (!current) {
+      return { found: false, task: null, reason: `Current task '${currentTaskId}' not found.` };
+    }
+
+    // If handoff_to is an agent name, it means we switch agents (orchestrator handles this)
+    // If handoff_to is a task ID within the same agent, it's internal chaining
+    if (!current.handoff_to) {
+      return { found: false, task: null, reason: 'No handoff defined for this task.' };
+    }
+
+    // Check if handoff_to is a task ID
+    const nextTask = this.taskMap.get(current.handoff_to);
+    if (nextTask) {
+      return { found: true, task: nextTask, reason: `Internal chain: ${current.handoff_to}` };
+    }
+
+    // Otherwise it's an agent-level handoff (handled by orchestrator)
+    return {
+      found: false,
+      task: null,
+      reason: `Agent handoff to '${current.handoff_to}'. Orchestrator handles inter-agent routing.`,
+    };
+  }
+
+  /**
+   * Get all parallelizable tasks for a given agent.
+   * @param {string} agentName
+   * @returns {object[]}
+   */
+  getParallelTasks(agentName) {
+    return getAgentTasks(this.taskMap, agentName).filter(t => t.parallelizable);
+  }
+
+  /**
+   * Get routing statistics.
+   * @returns {{ totalTasks: number, byAgent: object, byPhase: object, errors: number }}
+   */
+  getStats() {
+    const byAgent = {};
+    const byPhase = {};
+
+    for (const task of this.taskMap.values()) {
+      byAgent[task.agent] = (byAgent[task.agent] || 0) + 1;
+      byPhase[task.phase] = (byPhase[task.phase] || 0) + 1;
+    }
+
+    return {
+      totalTasks: this.taskMap.size,
+      byAgent,
+      byPhase,
+      errors: this.errors.length,
+    };
+  }
+}
+
+/**
+ * Create and load a TaskRouter instance.
+ * @param {string} tasksDir - Path to chati.dev/tasks/
+ * @returns {TaskRouter}
+ */
+export function createRouter(tasksDir) {
+  return new TaskRouter(tasksDir).load();
+}