chati-dev 4.1.5 → 4.2.0

package/src/terminal/run-team.js

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * CLI runner for Agent Team execution (Article XXI).
+ *
+ * Called by the orchestrator via the Bash tool to spawn a team of agents
+ * that communicate via a shared task list and mailbox.
+ *
+ * Usage:
+ *   node run-team.js --team-id TM-20260411-pln \
+ *     --team-type planning \
+ *     --project-dir /path/to/project \
+ *     --previous-agent brief \
+ *     --provider claude \
+ *     --timeout 1800000
+ *
+ * Outputs consolidated JSON to stdout for the orchestrator to parse.
+ * Same output shape as run-parallel.js + team_id + echo_events.
+ */
+
+import { fileURLToPath } from 'url';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { buildAgentPrompt } from './prompt-builder.js';
+import { spawnParallelGroup, spawnTerminal } from './spawner.js';
+import { TerminalMonitor } from './monitor.js';
+import { collectResults, mergeHandoffs, buildConsolidatedHandoff } from './collector.js';
+import { parseAgentOutput } from './handoff-parser.js';
+import { estimateTokens, COST_PER_1K } from './cost-tracker.js';
+import { getRateLimiter } from './rate-limiter.js';
+import {
+  readTaskList, getTeamProgress, writeMailboxMessage, computeEchoSimilarity,
+} from './team-task-list.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const TEAM_MEMBERS = {
+  planning: ['detail', 'architect', 'ux'],
+  build: ['dev', 'qa-implementation'],
+};
+
+// Task IDs match the Shared Task List template (team-planning-tasks.yaml / team-build-tasks.yaml)
+const TEAM_TASK_IDS = {
+  planning: ['TT-PLN-001', 'TT-PLN-002', 'TT-PLN-003'],
+  build: ['TT-BLD-001-DEV', 'TT-BLD-001-QA'],
+};
+
+// Team-level echo threshold: compares task OUTPUT similarity between consecutive
+// outputs from the same agent. Higher threshold (0.92) because task outputs are
+// structurally similar by nature — only near-identical outputs indicate a stuck loop.
+// This is DISTINCT from the QA-level echo threshold (0.85 per Article XXII §4)
+// which compares DEFECT DESCRIPTIONS against the Decision Trail.
+const ECHO_THRESHOLD = 0.92;
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = 'true';
+      }
+    }
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv);
+
+  const teamId = args['team-id'];
+  const teamType = args['team-type'];
+  const projectDir = args['project-dir'] || process.cwd();
+  const previousAgent = args['previous-agent'] || null;
+  const provider = args.provider || 'claude';
+  const timeout = parseInt(args.timeout, 10) || 1_800_000; // default 30 minutes
+
+  if (!teamId || !teamType) {
+    outputError('Missing required arguments: --team-id and --team-type');
+    process.exit(1);
+  }
+
+  const members = TEAM_MEMBERS[teamType];
+  const taskIds = TEAM_TASK_IDS[teamType];
+
+  if (!members) {
+    outputError(`Unknown team type: ${teamType}. Valid: planning, build`);
+    process.exit(1);
+  }
+
+  const teamDir = join(projectDir, '.chati', 'teams', teamId);
+  const mailboxDir = join(teamDir, 'mailbox');
+  const taskListPath = join(teamDir, 'tasks.yaml');
+
+  // Load session state (minimal parse)
+  let sessionState = {};
+  try {
+    const sessionPath = join(projectDir, '.chati', 'session.yaml');
+    if (existsSync(sessionPath)) {
+      const raw = readFileSync(sessionPath, 'utf-8');
+      for (const line of raw.split('\n')) {
+        const m = line.trim().match(/^([\w_-]+):\s*(.+)/);
+        if (m) sessionState[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+      }
+    }
+  } catch { /* optional */ }
+
+  // Build prompts for all team members
+  const configs = [];
+  const startTime = Date.now();
+
+  for (let i = 0; i < members.length; i++) {
+    try {
+      const promptResult = buildAgentPrompt({
+        agent: members[i],
+        taskId: taskIds[i],
+        projectDir,
+        previousAgent,
+        sessionState,
+        provider,
+      });
+
+      configs.push({
+        agent: members[i],
+        taskId: taskIds[i],
+        model: promptResult.model,
+        provider: promptResult.provider,
+        prompt: promptResult.prompt,
+        workingDir: projectDir,
+        timeout,
+        // Team-specific env vars injected into the spawned process
+        contextPayload: {
+          CHATI_TEAM_ID: teamId,
+          CHATI_TEAM_MEMBER: members[i],
+          CHATI_TEAM_TASK_LIST: taskListPath,
+          CHATI_TEAM_MAILBOX: mailboxDir,
+        },
+      });
+    } catch (err) {
+      outputError(`Failed to build prompt for ${members[i]}: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Check rate limit
+  const limiter = getRateLimiter(provider);
+  const rateStats = limiter.getStats();
+  const availableSlots = rateStats.limit - rateStats.used;
+  if (availableSlots < configs.length) {
+    console.error(`[chati] Rate limiter: ${availableSlots} slots for ${configs.length} team members. May throttle.`);
+  }
+
+  // Spawn team members
+  let group;
+  let fallbackUsed = false;
+  const echoEvents = [];
+
+  try {
+    group = spawnParallelGroup(configs);
+  } catch (err) {
+    console.error(`[chati] Team spawn failed: ${err.message}. Signaling fallback.`);
+    process.stdout.write(JSON.stringify({
+      status: 'spawn_failed',
+      fallback_required: true,
+      error: err.message,
+      team_id: teamId,
+    }, null, 2) + '\n');
+    process.exit(1);
+  }
+
+  // Monitor until all members complete
+  const monitor = new TerminalMonitor({ pollInterval: 2000, timeout });
+
+  for (const terminal of group.terminals) {
+    monitor.addTerminal(terminal);
+  }
+
+  await new Promise((resolve) => {
+    const safetyTimer = setTimeout(() => {
+      monitor.stopMonitoring();
+      resolve();
+    }, timeout + 10_000);
+
+    monitor.onComplete(() => {
+      clearTimeout(safetyTimer);
+      monitor.stopMonitoring();
+      resolve();
+    });
+
+    monitor.startMonitoring();
+  });
+
+  const elapsed = Date.now() - startTime;
+
+  // Echo detection: compare task outputs for cyclical patterns
+  try {
+    const taskList = readTaskList(taskListPath);
+    if (taskList && taskList.tasks) {
+      const completedTasks = taskList.tasks.filter(t => t.status === 'done');
+      for (let i = 1; i < completedTasks.length; i++) {
+        for (let j = 0; j < i; j++) {
+          const t1 = completedTasks[i];
+          const t2 = completedTasks[j];
+          if (t1.assigned_to === t2.assigned_to) {
+            const desc1 = JSON.stringify(t1);
+            const desc2 = JSON.stringify(t2);
+            const similarity = computeEchoSimilarity(desc1, desc2);
+            if (similarity >= ECHO_THRESHOLD) {
+              echoEvents.push({
+                detected_at: new Date().toISOString(),
+                member: t1.assigned_to,
+                similarity: Math.round(similarity * 100) / 100,
+                action_taken: 'echo_logged',
+              });
+              // Notify member via mailbox
+              writeMailboxMessage(mailboxDir, 'orchestrator', t1.assigned_to, 'echo_detected', {
+                similarity,
+                message: `You have submitted nearly identical outputs. Apply Article XX: diagnose root cause, change approach, do not repeat previous attempt.`,
+              });
+            }
+          }
+        }
+      }
+    }
+  } catch { /* echo detection is non-critical */ }
+
+  // Cost estimation
+  const costEstimates = configs.map((cfg, i) => {
+    const terminal = group.terminals[i];
+    const inputTokens = estimateTokens(cfg.prompt || '');
+    const outputTokens = estimateTokens((terminal?.stdout || []).join(''));
+    const modelKey = cfg.model || 'sonnet';
+    const rate = COST_PER_1K[modelKey] || COST_PER_1K.sonnet || 0.015;
+    return {
+      agent: cfg.agent,
+      model: modelKey,
+      provider: cfg.provider || 'claude',
+      inputTokens,
+      outputTokens,
+      estimatedCost: ((inputTokens + outputTokens) / 1000) * rate,
+    };
+  });
+
+  // Collect and merge results
+  const rawResults = collectResults(group.groupId, group.terminals);
+
+  const agentResults = rawResults.results.map(r => {
+    const parsed = parseAgentOutput(r.stdout);
+    return {
+      ...r,
+      handoff: parsed.found ? parsed.handoff : null,
+      handoffFound: parsed.found,
+    };
+  });
+
+  const mergeInput = agentResults.map(r => ({
+    agent: r.agent,
+    status: r.handoff?.status || (r.exitCode === 0 ? 'complete' : 'failed'),
+    outputs: r.handoff?.outputs || [],
+    decisions: r.handoff?.decisions || {},
+    blockers: r.handoff?.blockers || [],
+    summary: r.handoff?.summary || '',
+  }));
+
+  const merged = mergeHandoffs(mergeInput);
+  const nextAgent = determineNextAgent(teamType);
+  const consolidated = buildConsolidatedHandoff(merged, nextAgent);
+
+  // Team progress
+  const progress = getTeamProgress(taskListPath);
+
+  // Output consolidated result
+  const output = {
+    status: rawResults.summary.failed === 0 ? 'complete' : 'partial',
+    team_id: teamId,
+    team_type: teamType,
+    groupId: group.groupId,
+    agents: members.map((a, i) => ({
+      agent: a,
+      model: configs[i].model,
+      status: agentResults[i]?.handoff?.status || (agentResults[i]?.exitCode === 0 ? 'complete' : 'failed'),
+      score: agentResults[i]?.handoff?.score || null,
+      exitCode: agentResults[i]?.exitCode,
+      handoffFound: agentResults[i]?.handoffFound,
+    })),
+    mergedHandoff: consolidated,
+    team_progress: progress,
+    echo_events: echoEvents,
+    summary: rawResults.summary,
+    elapsed,
+    performance: {
+      sequentialEstimate: elapsed * members.length,
+      parallelActual: elapsed,
+      timeSaved: elapsed * (members.length - 1),
+    },
+    costEstimate: costEstimates,
+    fallbackUsed,
+  };
+
+  process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+  process.exit(rawResults.summary.failed > 0 ? 1 : 0);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine the next sequential agent after a team completes.
+ * Planning Team → phases
+ * Build Team → devops
+ */
+function determineNextAgent(teamType) {
+  if (teamType === 'planning') return 'phases';
+  if (teamType === 'build') return 'devops';
+  return null;
+}
+
+function outputError(message) {
+  process.stdout.write(JSON.stringify({
+    status: 'error',
+    error: message,
+    fallback_required: true,
+  }) + '\n');
+}
+
+// Guard pattern
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch(err => {
+    outputError(err.message);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, determineNextAgent };

package/src/terminal/team-task-list.js

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview Team Task List and Mailbox utilities.
+ *
+ * Pure utility functions for managing shared task lists and
+ * inter-agent mailbox communication within Agent Teams (Article XXI).
+ *
+ * Uses file-lock.js for atomic writes to prevent race conditions
+ * when multiple team members update concurrently.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import yaml from 'js-yaml';
+import { withLock } from '../utils/file-lock.js';
+
+// ---------------------------------------------------------------------------
+// Task List Management
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize a team task list from a template.
+ * @param {string} destPath - Destination path for the task list YAML
+ * @param {string} templatePath - Source template path
+ * @param {object} overrides - Optional field overrides (team_id, etc.)
+ * @returns {{ created: boolean, path: string }}
+ */
+export function initTaskList(destPath, templatePath, overrides = {}) {
+  mkdirSync(dirname(destPath), { recursive: true });
+
+  if (!existsSync(templatePath)) {
+    throw new Error(`Team task template not found: ${templatePath}`);
+  }
+
+  const template = yaml.load(readFileSync(templatePath, 'utf-8'));
+  const taskList = {
+    ...template,
+    ...overrides,
+    created_at: new Date().toISOString(),
+    last_updated: new Date().toISOString(),
+  };
+
+  writeFileSync(destPath, yaml.dump(taskList, { lineWidth: -1, noRefs: true }), 'utf-8');
+  return { created: true, path: destPath };
+}
+
+/**
+ * Read and parse a team task list.
+ * @param {string} path - Path to task list YAML
+ * @returns {object|null} Parsed task list or null if not found
+ */
+export function readTaskList(path) {
+  if (!existsSync(path)) return null;
+  return yaml.load(readFileSync(path, 'utf-8'));
+}
+
+/**
+ * Update a task's status atomically using file locking.
+ * @param {string} path - Path to task list YAML
+ * @param {string} taskId - Task ID to update
+ * @param {object} updates - Fields to merge (status, score, etc.)
+ * @returns {Promise<{ updated: boolean, task: object|null }>}
+ */
+export async function updateTaskStatus(path, taskId, updates) {
+  return withLock(path, () => {
+    const taskList = readTaskList(path);
+    if (!taskList || !taskList.tasks) return { updated: false, task: null };
+
+    const task = taskList.tasks.find(t => t.id === taskId);
+    if (!task) return { updated: false, task: null };
+
+    Object.assign(task, updates, { last_updated: new Date().toISOString() });
+    if (updates.status === 'done' && !task.completed_at) {
+      task.completed_at = new Date().toISOString();
+    }
+
+    taskList.last_updated = new Date().toISOString();
+    writeFileSync(path, yaml.dump(taskList, { lineWidth: -1, noRefs: true }), 'utf-8');
+    return { updated: true, task };
+  });
+}
+
+/**
+ * Get team progress summary from task list.
+ * @param {string} path - Path to task list YAML
+ * @returns {{ total: number, done: number, pending: number, blocked: number, inProgress: number, memberProgress: object }}
+ */
+export function getTeamProgress(path) {
+  const taskList = readTaskList(path);
+  if (!taskList || !taskList.tasks) {
+    return { total: 0, done: 0, pending: 0, blocked: 0, inProgress: 0, memberProgress: {} };
+  }
+
+  const tasks = taskList.tasks;
+  const memberProgress = {};
+
+  for (const task of tasks) {
+    const assignee = task.assigned_to;
+    if (!assignee) continue;
+    if (!memberProgress[assignee]) {
+      memberProgress[assignee] = { status: 'pending', score: null, tasks: 0, completed: 0 };
+    }
+    memberProgress[assignee].tasks++;
+    if (task.status === 'done') {
+      memberProgress[assignee].completed++;
+      memberProgress[assignee].score = task.score;
+    } else if (task.status === 'in_progress') {
+      memberProgress[assignee].status = 'in_progress';
+    }
+  }
+
+  // Post-loop: derive correct status for each member
+  for (const member of Object.values(memberProgress)) {
+    if (member.completed === member.tasks && member.tasks > 0) {
+      member.status = 'done';
+    } else if (member.completed > 0 && member.completed < member.tasks) {
+      member.status = 'in_progress';
+    }
+  }
+
+  return {
+    total: tasks.length,
+    done: tasks.filter(t => t.status === 'done').length,
+    pending: tasks.filter(t => t.status === 'pending').length,
+    blocked: tasks.filter(t => t.status === 'blocked').length,
+    inProgress: tasks.filter(t => t.status === 'in_progress').length,
+    memberProgress,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mailbox Management
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a message to the team mailbox.
+ * Messages are JSON files named {timestamp}-{from}-{type}.json
+ * @param {string} mailboxDir - Path to team mailbox directory
+ * @param {string} from - Sender agent name
+ * @param {string} to - Recipient agent name (or 'all' for broadcast)
+ * @param {string} type - Message type (cross_review_request, task_ready_for_review, etc.)
+ * @param {object} payload - Message content
+ * @returns {{ written: boolean, path: string }}
+ */
+export function writeMailboxMessage(mailboxDir, from, to, type, payload) {
+  mkdirSync(mailboxDir, { recursive: true });
+
+  const timestamp = Date.now();
+  const filename = `${timestamp}-${from}-${type}.json`;
+  const messagePath = join(mailboxDir, filename);
+
+  const message = {
+    id: `MSG-${timestamp}-${from.slice(0, 3)}`,
+    from,
+    to,
+    type,
+    timestamp: new Date().toISOString(),
+    payload,
+    read: false,
+  };
+
+  writeFileSync(messagePath, JSON.stringify(message, null, 2), 'utf-8');
+  return { written: true, path: messagePath };
+}
+
+/**
+ * Read all inbox messages for a specific agent.
+ * @param {string} mailboxDir - Path to team mailbox directory
+ * @param {string} member - Agent name to read messages for
+ * @returns {object[]} Array of message objects addressed to this member (or 'all')
+ */
+export function readInbox(mailboxDir, member) {
+  if (!existsSync(mailboxDir)) return [];
+
+  const files = readdirSync(mailboxDir).filter(f => f.endsWith('.json')).sort();
+  const messages = [];
+
+  for (const file of files) {
+    try {
+      const msg = JSON.parse(readFileSync(join(mailboxDir, file), 'utf-8'));
+      if (msg.to === member || msg.to === 'all') {
+        messages.push(msg);
+      }
+    } catch { /* skip malformed messages */ }
+  }
+
+  return messages;
+}
+
+// ---------------------------------------------------------------------------
+// Echo Detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute trigram-based Jaccard similarity between two texts.
+ * Used for Echo Detection (Article XXII) to detect cyclical defects.
+ * @param {string} text1 - First text (normalized)
+ * @param {string} text2 - Second text (normalized)
+ * @returns {number} Similarity ratio 0.0 - 1.0
+ */
+export function computeEchoSimilarity(text1, text2) {
+  if (!text1 || !text2) return 0;
+
+  const normalize = (t) => t.toLowerCase().replace(/\s+/g, ' ').trim();
+  const trigrams = (t) => {
+    const n = normalize(t);
+    const set = new Set();
+    for (let i = 0; i <= n.length - 3; i++) {
+      set.add(n.slice(i, i + 3));
+    }
+    return set;
+  };
+
+  const a = trigrams(text1);
+  const b = trigrams(text2);
+
+  if (a.size === 0 && b.size === 0) return 1;
+  if (a.size === 0 || b.size === 0) return 0;
+
+  let intersection = 0;
+  for (const gram of a) {
+    if (b.has(gram)) intersection++;
+  }
+
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}