agent-relay 2.3.13 → 2.4.0

package/packages/wrapper/src/trajectory-integration.ts

@@ -1,1261 +0,0 @@
-/**
- * Trajectory Integration Module
- *
- * Integrates with the agent-trajectories package to provide
- * PDERO paradigm tracking within agent-relay.
- *
- * This module provides a bridge between agent-relay and the
- * external `trail` CLI / agent-trajectories library.
- *
- * Key integration points:
- * - Auto-starts trajectory when agent is instantiated with a task
- * - Records all inter-agent messages
- * - Auto-detects PDERO phase transitions from output
- * - Provides hooks for key agent lifecycle events
- */
-
-import { spawn, execSync } from 'node:child_process';
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { getProjectPaths } from '@agent-relay/config/project-namespace';
-import {
-  getPrimaryTrajectoriesDir,
-  getAllTrajectoriesDirs,
-  getTrajectoryEnvVars,
-} from '@agent-relay/config/trajectory-config';
-
-/**
- * Trajectory index file structure
- */
-interface TrajectoryIndexEntry {
-  title: string;
-  status: 'active' | 'completed' | 'abandoned';
-  startedAt: string;
-  completedAt?: string;
-  path: string;
-}
-
-interface TrajectoryIndex {
-  version: number;
-  lastUpdated: string;
-  trajectories: Record<string, TrajectoryIndexEntry>;
-}
-
-/**
- * Full trajectory file structure
- */
-interface TrajectoryFile {
-  id: string;
-  version: number;
-  task: {
-    title: string;
-    source?: { system: string; id: string };
-  };
-  status: 'active' | 'completed' | 'abandoned';
-  startedAt: string;
-  completedAt?: string;
-  agents: Array<{ name: string; role: string; joinedAt: string }>;
-  chapters: Array<{
-    id: string;
-    title: string;
-    agentName: string;
-    startedAt: string;
-    endedAt?: string;
-    events: Array<{
-      ts: number;
-      type: string;
-      content: string;
-      raw?: Record<string, unknown>;
-      significance?: string;
-    }>;
-  }>;
-  retrospective?: {
-    summary: string;
-    approach: string;
-    confidence: number;
-  };
-}
-
-/**
- * Read a single trajectory index file from a directory
- */
-function resolveIndexEntryPath(trajectoriesDir: string, entryPath: string): string {
-  if (!entryPath) {
-    return entryPath;
-  }
-
-  if (existsSync(entryPath)) {
-    return entryPath;
-  }
-
-  const normalized = entryPath.replace(/\\/g, '/');
-  const marker = '/.trajectories/';
-  const markerIndex = normalized.indexOf(marker);
-
-  if (markerIndex >= 0) {
-    const relative = normalized.slice(markerIndex + marker.length);
-    const candidate = join(trajectoriesDir, relative);
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-
-  const subdirMatch = normalized.match(/\/(active|completed)\/.+$/);
-  if (subdirMatch) {
-    const relative = subdirMatch[0].slice(1);
-    const candidate = join(trajectoriesDir, relative);
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-
-  return entryPath;
-}
-
-function readSingleTrajectoryIndex(trajectoriesDir: string): TrajectoryIndex | null {
-  try {
-    const indexPath = join(trajectoriesDir, 'index.json');
-    if (!existsSync(indexPath)) {
-      return null;
-    }
-    const content = readFileSync(indexPath, 'utf-8');
-    const index = JSON.parse(content) as TrajectoryIndex;
-    const trajectories = index.trajectories ?? {};
-
-    for (const [id, entry] of Object.entries(trajectories)) {
-      trajectories[id] = {
-        ...entry,
-        path: resolveIndexEntryPath(trajectoriesDir, entry.path),
-      };
-    }
-
-    return { ...index, trajectories };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Read and merge trajectory indexes from all locations (repo + user-level)
- * This allows reading trajectories from both places
- */
-function readTrajectoryIndex(): TrajectoryIndex | null {
-  const dirs = getAllTrajectoriesDirs();
-
-  if (dirs.length === 0) {
-    return null;
-  }
-
-  // Read and merge all indexes
-  let mergedIndex: TrajectoryIndex | null = null;
-
-  for (const dir of dirs) {
-    const index = readSingleTrajectoryIndex(dir);
-    if (!index) continue;
-
-    if (!mergedIndex) {
-      mergedIndex = index;
-    } else {
-      // Merge trajectories, preferring more recent entries
-      for (const [id, entry] of Object.entries(index.trajectories)) {
-        const existing = mergedIndex.trajectories[id];
-        if (!existing) {
-          mergedIndex.trajectories[id] = entry;
-        } else {
-          // Keep the more recently updated one
-          const existingTime = new Date(existing.completedAt || existing.startedAt).getTime();
-          const newTime = new Date(entry.completedAt || entry.startedAt).getTime();
-          if (newTime > existingTime) {
-            mergedIndex.trajectories[id] = entry;
-          }
-        }
-      }
-      // Update lastUpdated to most recent
-      if (new Date(index.lastUpdated) > new Date(mergedIndex.lastUpdated)) {
-        mergedIndex.lastUpdated = index.lastUpdated;
-      }
-    }
-  }
-
-  return mergedIndex;
-}
-
-/**
- * Read a specific trajectory file directly from filesystem
- */
-function readTrajectoryFile(trajectoryPath: string): TrajectoryFile | null {
-  try {
-    if (!existsSync(trajectoryPath)) {
-      return null;
-    }
-    const content = readFileSync(trajectoryPath, 'utf-8');
-    return JSON.parse(content) as TrajectoryFile;
-  } catch {
-    return null;
-  }
-}
-
-function getCurrentPhaseFromTrajectory(trajectory: TrajectoryFile | null): PDEROPhase | undefined {
-  if (!trajectory?.chapters?.length) {
-    return undefined;
-  }
-
-  const lastChapter = trajectory.chapters[trajectory.chapters.length - 1];
-  for (const event of [...(lastChapter.events || [])].reverse()) {
-    if (event.type === 'phase_transition' || event.type === 'phase') {
-      const phaseMatch = event.content?.match(/phase[:\s]+(\w+)/i);
-      if (phaseMatch) {
-        return phaseMatch[1].toLowerCase() as PDEROPhase;
-      }
-    }
-  }
-
-  return undefined;
-}
-
-function listActiveTrajectoryFiles(trajectoriesDir: string): string[] {
-  const activeDir = join(trajectoriesDir, 'active');
-  if (!existsSync(activeDir)) {
-    return [];
-  }
-
-  return readdirSync(activeDir, { withFileTypes: true })
-    .filter(entry => entry.isFile() && entry.name.endsWith('.json'))
-    .map(entry => join(activeDir, entry.name));
-}
-
-function findActiveTrajectoryPathById(trajectoryDirs: string[], trajectoryId: string): string | null {
-  for (const dir of trajectoryDirs) {
-    const candidate = join(dir, 'active', `${trajectoryId}.json`);
-    if (existsSync(candidate)) {
-      return candidate;
-    }
-  }
-
-  return null;
-}
-
-/**
- * PDERO phases for agent work lifecycle
- */
-export type PDEROPhase = 'plan' | 'design' | 'execute' | 'review' | 'observe';
-
-/**
- * Options for starting a trajectory
- */
-export interface StartTrajectoryOptions {
-  task: string;
-  taskId?: string;
-  source?: string;
-  agentName: string;
-  phase?: PDEROPhase;
-}
-
-/**
- * Options for completing a trajectory
- */
-export interface CompleteTrajectoryOptions {
-  summary?: string;
-  confidence?: number;
-  challenges?: string[];
-  learnings?: string[];
-}
-
-/**
- * Options for recording a decision
- */
-export interface DecisionOptions {
-  choice: string;
-  question?: string;
-  alternatives?: string[];
-  reasoning?: string;
-  confidence?: number;
-}
-
-/**
- * Run a trail CLI command
- * Uses config-based environment to control trajectory storage location
- */
-async function runTrail(args: string[]): Promise<{ success: boolean; output: string; error?: string }> {
-  return new Promise((resolve) => {
-    // Get trajectory env vars to set correct storage location
-    const trajectoryEnv = getTrajectoryEnvVars();
-
-    const proc = spawn('trail', args, {
-      cwd: getProjectPaths().projectRoot,
-      env: { ...process.env, ...trajectoryEnv },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
-
-    let stdout = '';
-    let stderr = '';
-
-    proc.stdout?.on('data', (data) => {
-      stdout += data.toString();
-    });
-
-    proc.stderr?.on('data', (data) => {
-      stderr += data.toString();
-    });
-
-    proc.on('error', (err) => {
-      resolve({ success: false, output: '', error: `Failed to run trail: ${err.message}` });
-    });
-
-    proc.on('close', (code) => {
-      if (code === 0) {
-        resolve({ success: true, output: stdout.trim() });
-      } else {
-        resolve({ success: false, output: stdout.trim(), error: stderr.trim() || `Exit code: ${code}` });
-      }
-    });
-  });
-}
-
-/**
- * Check if trail CLI is available
- */
-export async function isTrailAvailable(): Promise<boolean> {
-  const result = await runTrail(['--version']);
-  return result.success;
-}
-
-/**
- * Start a new trajectory
- */
-export async function startTrajectory(options: StartTrajectoryOptions): Promise<{ success: boolean; trajectoryId?: string; error?: string }> {
-  const args = ['start', options.task];
-
-  if (options.taskId) {
-    args.push('--task-id', options.taskId);
-  }
-  if (options.source) {
-    args.push('--source', options.source);
-  }
-  if (options.agentName) {
-    args.push('--agent', options.agentName);
-  }
-  if (options.phase) {
-    args.push('--phase', options.phase);
-  }
-
-  const result = await runTrail(args);
-  if (result.success) {
-    // Parse trajectory ID from output like "✓ Trajectory started: traj_xxx"
-    const match = result.output.match(/traj_[a-z0-9]+/i);
-    return { success: true, trajectoryId: match?.[0] };
-  }
-  return { success: false, error: result.error };
-}
-
-/**
- * Get current trajectory status
- * Reads directly from .trajectories/index.json instead of using CLI
- */
-export async function getTrajectoryStatus(): Promise<{ active: boolean; trajectoryId?: string; phase?: PDEROPhase; task?: string }> {
-  const index = readTrajectoryIndex();
-  const trajectoryDirs = getAllTrajectoriesDirs();
-  if (!index && trajectoryDirs.length === 0) {
-    return { active: false };
-  }
-
-  // Find an active trajectory
-  if (index) {
-    for (const [id, entry] of Object.entries(index.trajectories)) {
-      if (entry.status === 'active') {
-        // Read the full trajectory file to get phase info
-        const trajectory = readTrajectoryFile(entry.path);
-        const currentPhase = getCurrentPhaseFromTrajectory(trajectory);
-
-        return {
-          active: true,
-          trajectoryId: id,
-          phase: currentPhase,
-          task: entry.title,
-        };
-      }
-    }
-  }
-
-  for (const dir of trajectoryDirs) {
-    for (const activePath of listActiveTrajectoryFiles(dir)) {
-      const trajectory = readTrajectoryFile(activePath);
-      if (!trajectory) {
-        continue;
-      }
-
-      return {
-        active: true,
-        trajectoryId: trajectory.id,
-        phase: getCurrentPhaseFromTrajectory(trajectory),
-        task: trajectory.task?.title,
-      };
-    }
-  }
-
-  return { active: false };
-}
-
-/**
- * Transition to a new PDERO phase
- */
-export async function transitionPhase(phase: PDEROPhase, reason?: string, agentName?: string): Promise<{ success: boolean; error?: string }> {
-  const args = ['phase', phase];
-
-  if (reason) {
-    args.push('--reason', reason);
-  }
-  if (agentName) {
-    args.push('--agent', agentName);
-  }
-
-  const result = await runTrail(args);
-  return { success: result.success, error: result.error };
-}
-
-/**
- * Record a decision
- */
-export async function recordDecision(options: DecisionOptions): Promise<{ success: boolean; error?: string }> {
-  const args = ['decision', options.choice];
-
-  if (options.question) {
-    args.push('--question', options.question);
-  }
-  if (options.alternatives && options.alternatives.length > 0) {
-    args.push('--alternatives', options.alternatives.join(','));
-  }
-  if (options.reasoning) {
-    args.push('--reasoning', options.reasoning);
-  }
-  if (options.confidence !== undefined) {
-    args.push('--confidence', options.confidence.toString());
-  }
-
-  const result = await runTrail(args);
-  return { success: result.success, error: result.error };
-}
-
-/**
- * Record an event/observation
- */
-export async function recordEvent(
-  content: string,
-  type: 'tool_call' | 'observation' | 'checkpoint' | 'error' = 'observation',
-  agentName?: string
-): Promise<{ success: boolean; error?: string }> {
-  const args = ['event', content, '--type', type];
-
-  if (agentName) {
-    args.push('--agent', agentName);
-  }
-
-  const result = await runTrail(args);
-  return { success: result.success, error: result.error };
-}
-
-/**
- * Record a message (sent or received)
- */
-export async function recordMessage(
-  direction: 'sent' | 'received',
-  from: string,
-  to: string,
-  body: string
-): Promise<{ success: boolean; error?: string }> {
-  const content = `Message ${direction}: ${direction === 'sent' ? `→ ${to}` : `← ${from}`}: ${body.slice(0, 100)}${body.length > 100 ? '...' : ''}`;
-  return recordEvent(content, 'observation');
-}
-
-/**
- * Complete the current trajectory
- */
-export async function completeTrajectory(options: CompleteTrajectoryOptions = {}): Promise<{ success: boolean; error?: string }> {
-  const args = ['complete'];
-
-  if (options.summary) {
-    args.push('--summary', options.summary);
-  }
-  if (options.confidence !== undefined) {
-    args.push('--confidence', options.confidence.toString());
-  }
-  if (options.challenges && options.challenges.length > 0) {
-    args.push('--challenges', options.challenges.join(','));
-  }
-  if (options.learnings && options.learnings.length > 0) {
-    args.push('--learnings', options.learnings.join(','));
-  }
-
-  const result = await runTrail(args);
-  return { success: result.success, error: result.error };
-}
-
-/**
- * Abandon the current trajectory
- */
-export async function abandonTrajectory(reason?: string): Promise<{ success: boolean; error?: string }> {
-  const args = ['abandon'];
-
-  if (reason) {
-    args.push('--reason', reason);
-  }
-
-  const result = await runTrail(args);
-  return { success: result.success, error: result.error };
-}
-
-/**
- * Trajectory step for dashboard display
- */
-export interface TrajectoryStepData {
-  id: string;
-  timestamp: string | number;
-  type: 'tool_call' | 'decision' | 'message' | 'state_change' | 'error' | 'phase_transition';
-  phase?: PDEROPhase;
-  title: string;
-  description?: string;
-  metadata?: Record<string, unknown>;
-  duration?: number;
-  status?: 'pending' | 'running' | 'success' | 'error';
-}
-
-/**
- * List trajectory steps/events
- * Returns steps for the current or specified trajectory
- * Reads directly from filesystem instead of using CLI
- */
-export async function listTrajectorySteps(trajectoryId?: string): Promise<{
-  success: boolean;
-  steps: TrajectoryStepData[];
-  error?: string;
-}> {
-  const trajectoryDirs = getAllTrajectoriesDirs();
-  const index = readTrajectoryIndex();
-
-  if (!index && trajectoryDirs.length === 0) {
-    return { success: true, steps: [] };
-  }
-
-  // Collect all trajectory paths to load
-  const trajectoryPaths = new Set<string>();
-
-  if (trajectoryId) {
-    // Use specified trajectory - try multiple lookup strategies
-    let foundPath: string | null = null;
-
-    // Strategy 1: Look up by index key
-    const entry = index?.trajectories[trajectoryId];
-    if (entry) {
-      foundPath = entry.path;
-    }
-
-    // Strategy 2: If not found by key, search index entries by file's internal ID
-    // This handles cases where the index key differs from the file's internal ID
-    if (!foundPath && index) {
-      for (const [_key, indexEntry] of Object.entries(index.trajectories)) {
-        const trajectory = readTrajectoryFile(indexEntry.path);
-        if (trajectory && trajectory.id === trajectoryId) {
-          foundPath = indexEntry.path;
-          break;
-        }
-      }
-    }
-
-    // Strategy 3: Fall back to active directory filename match
-    if (!foundPath) {
-      foundPath = findActiveTrajectoryPathById(trajectoryDirs, trajectoryId);
-    }
-
-    if (foundPath) {
-      trajectoryPaths.add(foundPath);
-    }
-  } else {
-    // Collect ALL active trajectories (not just the first one)
-    if (index) {
-      for (const [_id, entry] of Object.entries(index.trajectories)) {
-        if (entry.status === 'active') {
-          trajectoryPaths.add(entry.path);
-        }
-      }
-    }
-
-    for (const dir of trajectoryDirs) {
-      for (const activePath of listActiveTrajectoryFiles(dir)) {
-        trajectoryPaths.add(activePath);
-      }
-    }
-  }
-
-  if (trajectoryPaths.size === 0) {
-    return { success: true, steps: [] };
-  }
-
-  // Load all trajectories and merge their steps
-  const steps: TrajectoryStepData[] = [];
-  let stepIndex = 0;
-
-  for (const trajectoryPath of trajectoryPaths) {
-    const trajectory = readTrajectoryFile(trajectoryPath);
-    if (!trajectory) {
-      continue;
-    }
-
-    // Extract events from all chapters
-    // Include trajectory ID in step IDs to ensure uniqueness across trajectories
-    // This prevents React key collisions when switching between trajectories
-    const trajId = trajectory.id || 'unknown';
-    for (const chapter of trajectory.chapters || []) {
-      for (const event of chapter.events || []) {
-        steps.push({
-          id: `${trajId}-step-${stepIndex++}`,
-          timestamp: event.ts || Date.now(),
-          type: mapEventType(event.type),
-          title: event.content?.slice(0, 50) || event.type || 'Event',
-          description: event.content,
-          metadata: event.raw,
-          status: mapEventStatus(trajectory.status),
-        });
-      }
-    }
-  }
-
-  // Sort steps by timestamp to maintain chronological order across all trajectories
-  steps.sort((a, b) => {
-    const timeA = typeof a.timestamp === 'number' ? a.timestamp : new Date(a.timestamp as string).getTime();
-    const timeB = typeof b.timestamp === 'number' ? b.timestamp : new Date(b.timestamp as string).getTime();
-    return timeA - timeB;
-  });
-
-  return { success: true, steps };
-}
-
-/**
- * Trajectory history entry for dashboard display
- */
-export interface TrajectoryHistoryEntry {
-  id: string;
-  title: string;
-  status: 'active' | 'completed' | 'abandoned';
-  startedAt: string;
-  completedAt?: string;
-  agents?: string[];
-  summary?: string;
-  confidence?: number;
-}
-
-/**
- * Get trajectory history - list all trajectories
- * Reads directly from filesystem
- */
-export async function getTrajectoryHistory(): Promise<{
-  success: boolean;
-  trajectories: TrajectoryHistoryEntry[];
-  error?: string;
-}> {
-  const trajectoryDirs = getAllTrajectoriesDirs();
-  const index = readTrajectoryIndex();
-  if (!index && trajectoryDirs.length === 0) {
-    return { success: true, trajectories: [] };
-  }
-
-  const trajectories: TrajectoryHistoryEntry[] = [];
-  const seenIds = new Set<string>();
-
-  if (index) {
-    for (const [indexKey, entry] of Object.entries(index.trajectories)) {
-      // Read the trajectory file to get the actual internal ID
-      // This ensures consistency between history list IDs and file content
-      const trajectory = entry.path ? readTrajectoryFile(entry.path) : null;
-
-      // Use the file's internal ID if available, otherwise fall back to index key
-      // This fixes the mismatch where index key differs from file's internal ID
-      const actualId = trajectory?.id || indexKey;
-
-      // Skip if we've already seen this ID (from a previous directory's index)
-      if (seenIds.has(actualId)) {
-        continue;
-      }
-
-      const historyEntry: TrajectoryHistoryEntry = {
-        id: actualId,
-        title: trajectory?.task?.title || entry.title,
-        status: entry.status,
-        startedAt: trajectory?.startedAt || entry.startedAt,
-        completedAt: trajectory?.completedAt || entry.completedAt,
-      };
-
-      // Add additional details from trajectory file
-      if (trajectory) {
-        historyEntry.agents = trajectory.agents?.map(a => a.name);
-        if (trajectory.retrospective) {
-          historyEntry.summary = trajectory.retrospective.summary;
-          historyEntry.confidence = trajectory.retrospective.confidence;
-        }
-      }
-
-      trajectories.push(historyEntry);
-      seenIds.add(actualId);
-    }
-  }
-
-  for (const dir of trajectoryDirs) {
-    for (const activePath of listActiveTrajectoryFiles(dir)) {
-      const trajectory = readTrajectoryFile(activePath);
-      if (!trajectory || seenIds.has(trajectory.id)) {
-        continue;
-      }
-
-      const historyEntry: TrajectoryHistoryEntry = {
-        id: trajectory.id,
-        title: trajectory.task?.title || 'Untitled trajectory',
-        status: trajectory.status ?? 'active',
-        startedAt: trajectory.startedAt,
-        completedAt: trajectory.completedAt,
-        agents: trajectory.agents?.map(a => a.name),
-      };
-
-      if (trajectory.retrospective) {
-        historyEntry.summary = trajectory.retrospective.summary;
-        historyEntry.confidence = trajectory.retrospective.confidence;
-      }
-
-      trajectories.push(historyEntry);
-      seenIds.add(trajectory.id);
-    }
-  }
-
-  // Sort by startedAt descending (most recent first)
-  trajectories.sort((a, b) =>
-    new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime()
-  );
-
-  return { success: true, trajectories };
-}
-
-/**
- * Map trail event type to dashboard type
- */
-function mapEventType(type?: string): TrajectoryStepData['type'] {
-  switch (type?.toLowerCase()) {
-    case 'tool':
-    case 'tool_call':
-    case 'tool_use':
-      return 'tool_call';
-    case 'decision':
-    case 'choice':
-      return 'decision';
-    case 'message':
-    case 'observation':
-      return 'message';
-    case 'phase':
-    case 'phase_change':
-    case 'phase_transition':
-      return 'phase_transition';
-    case 'error':
-    case 'failure':
-      return 'error';
-    default:
-      return 'state_change';
-  }
-}
-
-/**
- * Map trail status to dashboard status
- */
-function mapEventStatus(status?: string): TrajectoryStepData['status'] | undefined {
-  switch (status?.toLowerCase()) {
-    case 'running':
-    case 'in_progress':
-    case 'active':
-      return 'running';
-    case 'success':
-    case 'completed':
-    case 'done':
-      return 'success';
-    case 'error':
-    case 'failed':
-    case 'abandoned':
-      return 'error';
-    case 'pending':
-    case 'queued':
-      return 'pending';
-    default:
-      return undefined;
-  }
-}
-
-/**
- * Detect PDERO phase from content
- */
-export function detectPhaseFromContent(content: string): PDEROPhase | undefined {
-  const lowerContent = content.toLowerCase();
-
-  const phasePatterns: Array<{ phase: PDEROPhase; patterns: string[] }> = [
-    { phase: 'plan', patterns: ['planning', 'analyzing requirements', 'breaking down', 'creating plan', 'task list', 'todo', 'outline'] },
-    { phase: 'design', patterns: ['designing', 'architecting', 'choosing pattern', 'interface design', 'schema design', 'architecture'] },
-    { phase: 'execute', patterns: ['implementing', 'writing', 'coding', 'building', 'creating file', 'modifying', 'editing'] },
-    { phase: 'review', patterns: ['testing', 'reviewing', 'validating', 'checking', 'verifying', 'running tests', 'test passed', 'test failed'] },
-    { phase: 'observe', patterns: ['observing', 'monitoring', 'reflecting', 'documenting', 'retrospective', 'learnings', 'summary'] },
-  ];
-
-  for (const { phase, patterns } of phasePatterns) {
-    for (const pattern of patterns) {
-      if (lowerContent.includes(pattern)) {
-        return phase;
-      }
-    }
-  }
-
-  return undefined;
-}
-
-/**
- * Detected tool call information
- */
-export interface DetectedToolCall {
-  tool: string;
-  args?: string;
-  status?: 'started' | 'completed' | 'failed';
-}
-
-/**
- * Detected error information
- */
-export interface DetectedError {
-  type: 'error' | 'warning' | 'failure';
-  message: string;
-  stack?: string;
-}
-
-/**
- * All known Claude Code tool names
- */
-const TOOL_NAMES = [
-  'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep', 'Task', 'TaskOutput',
-  'WebFetch', 'WebSearch', 'NotebookEdit', 'TodoWrite', 'AskUserQuestion',
-  'KillShell', 'EnterPlanMode', 'ExitPlanMode', 'Skill', 'SlashCommand',
-];
-
-const TOOL_NAME_PATTERN = TOOL_NAMES.join('|');
-
-/**
- * Tool call patterns for Claude Code and similar AI CLIs
- */
-const TOOL_PATTERNS = [
-  // Claude Code tool invocations (displayed in output with parenthesis/braces)
-  new RegExp(`(?:^|\\n)\\s*(?:${TOOL_NAME_PATTERN})\\s*[({]`, 'i'),
-  // Tool completion markers (checkmarks, spinners)
-  new RegExp(`(?:^|\\n)\\s*(?:✓|✔|⠋|⠙|⠹|⠸|⠼|⠴|⠦|⠧|⠇|⠏)\\s*(${TOOL_NAME_PATTERN})`, 'i'),
-  // Function call patterns (explicit mentions)
-  new RegExp(`(?:^|\\n)\\s*(?:Calling|Using|Invoking)\\s+(?:tool\\s+)?['"]?(${TOOL_NAME_PATTERN})['"]?`, 'i'),
-  // Tool result patterns
-  new RegExp(`(?:^|\\n)\\s*(?:Tool result|Result from)\\s*:?\\s*(${TOOL_NAME_PATTERN})`, 'i'),
-];
-
-/**
- * Error patterns for detecting failures in output
- * Note: Patterns are ordered from most specific to least specific
- */
-const ERROR_PATTERNS = [
-  // JavaScript/TypeScript runtime errors (most specific)
-  /(?:^|\n)((?:TypeError|ReferenceError|SyntaxError|RangeError|EvalError|URIError):\s*.+)/i,
-  // Named Error with message (e.g., "Error: Something went wrong")
-  /(?:^|\n)(Error:\s+.+)/,
-  // Failed assertions
-  /(?:^|\n)\s*(AssertionError:\s*.+)/i,
-  // Test failures (Vitest, Jest patterns)
-  /(?:^|\n)\s*(FAIL\s+\S+\.(?:ts|js|tsx|jsx))/i,
-  /(?:^|\n)\s*(✗|✘|×)\s+(.+)/,
-  // Command/process failures
-  /(?:^|\n)\s*(Command failed[^\n]+)/i,
-  /(?:^|\n)\s*((?:Exit|exit)\s+code[:\s]+[1-9]\d*)/i,
-  /(?:^|\n)\s*(exited with (?:code\s+)?[1-9]\d*)/i,
-  // Node.js/system errors
-  /(?:^|\n)\s*(EACCES|EPERM|ENOENT|ECONNREFUSED|ETIMEDOUT|ENOTFOUND)(?::\s*.+)?/,
-  // Build/compile errors (webpack, tsc, etc.)
-  /(?:^|\n)\s*(error TS\d+:\s*.+)/i,
-  /(?:^|\n)\s*(error\[\S+\]:\s*.+)/i,
-];
-
-/**
- * Warning patterns for detecting potential issues
- */
-const WARNING_PATTERNS = [
-  /(?:^|\n)\s*(?:warning|WARN|⚠️?)\s*[:\[]?\s*(.+)/i,
-  /(?:^|\n)\s*(?:deprecated|DEPRECATED):\s*(.+)/i,
-];
-
-/**
- * Detect tool calls from agent output
- *
- * @example
- * ```typescript
- * const tools = detectToolCalls(output);
- * // Returns: [{ tool: 'Read', args: 'file.ts' }, { tool: 'Bash', status: 'completed' }]
- * ```
- */
-export function detectToolCalls(content: string): DetectedToolCall[] {
-  const detected: DetectedToolCall[] = [];
-  const seenTools = new Set<string>();
-  const toolNameExtractor = new RegExp(`\\b(${TOOL_NAME_PATTERN})\\b`, 'i');
-
-  for (const pattern of TOOL_PATTERNS) {
-    const matches = content.matchAll(new RegExp(pattern.source, 'gi'));
-    for (const match of matches) {
-      // Extract tool name from the match
-      const fullMatch = match[0];
-      const toolNameMatch = fullMatch.match(toolNameExtractor);
-      if (toolNameMatch) {
-        const tool = toolNameMatch[1];
-        // Avoid duplicates by position (same tool at same position)
-        const key = `${tool}:${match.index}`;
-        if (!seenTools.has(key)) {
-          seenTools.add(key);
-          detected.push({
-            tool,
-            status: fullMatch.includes('✓') || fullMatch.includes('✔') ? 'completed' : 'started',
-          });
-        }
-      }
-    }
-  }
-
-  return detected;
-}
-
-/**
- * Detect errors from agent output
- *
- * @example
- * ```typescript
- * const errors = detectErrors(output);
- * // Returns: [{ type: 'error', message: 'TypeError: Cannot read property...' }]
- * ```
- */
-export function detectErrors(content: string): DetectedError[] {
-  const detected: DetectedError[] = [];
-  const seenMessages = new Set<string>();
-
-  // Check for error patterns
-  for (const pattern of ERROR_PATTERNS) {
-    const matches = content.matchAll(new RegExp(pattern, 'gi'));
-    for (const match of matches) {
-      const message = match[1] || match[0];
-      const cleanMessage = message.trim().slice(0, 200); // Limit length
-      if (!seenMessages.has(cleanMessage)) {
-        seenMessages.add(cleanMessage);
-        detected.push({
-          type: 'error',
-          message: cleanMessage,
-        });
-      }
-    }
-  }
-
-  // Check for warning patterns
-  for (const pattern of WARNING_PATTERNS) {
-    const matches = content.matchAll(new RegExp(pattern, 'gi'));
-    for (const match of matches) {
-      const message = match[1] || match[0];
-      const cleanMessage = message.trim().slice(0, 200);
-      if (!seenMessages.has(cleanMessage)) {
-        seenMessages.add(cleanMessage);
-        detected.push({
-          type: 'warning',
-          message: cleanMessage,
-        });
-      }
-    }
-  }
-
-  return detected;
-}
-
-/**
- * TrajectoryIntegration class for managing trajectory state
- *
- * This class enforces trajectory tracking during agent lifecycle:
- * - Auto-starts trajectory when agent is instantiated with a task
- * - Records all inter-agent messages
- * - Auto-detects PDERO phase transitions
- * - Provides lifecycle hooks for tmux/pty wrappers
- */
-export class TrajectoryIntegration {
-  private projectId: string;
-  private agentName: string;
-  private trailAvailable: boolean | null = null;
-  private currentPhase: PDEROPhase | null = null;
-  private trajectoryId: string | null = null;
-  private initialized = false;
-  private task: string | null = null;
-
-  constructor(projectId: string, agentName: string) {
-    this.projectId = projectId;
-    this.agentName = agentName;
-  }
-
-  /**
-   * Check if trail is available (cached)
-   */
-  async isAvailable(): Promise<boolean> {
-    if (this.trailAvailable === null) {
-      this.trailAvailable = await isTrailAvailable();
-    }
-    return this.trailAvailable;
-  }
-
-  /**
-   * Check if trail CLI is installed synchronously
-   */
-  isTrailInstalledSync(): boolean {
-    try {
-      execSync('which trail', { stdio: 'pipe' });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * Initialize trajectory tracking for agent lifecycle
-   * Called automatically when agent starts with a task
-   */
-  async initialize(task?: string, taskId?: string, source?: string): Promise<boolean> {
-    if (this.initialized) return true;
-
-    if (!(await this.isAvailable())) {
-      return false;
-    }
-
-    // If task provided, auto-start trajectory
-    if (task) {
-      const success = await this.start(task, taskId, source);
-      if (success) {
-        this.initialized = true;
-        this.task = task;
-      }
-      return success;
-    }
-
-    this.initialized = true;
-    return true;
-  }
-
-  /**
-   * Start tracking a trajectory
-   */
-  async start(task: string, taskId?: string, source?: string): Promise<boolean> {
-    if (!(await this.isAvailable())) return false;
-
-    const result = await startTrajectory({
-      task,
-      taskId,
-      source,
-      agentName: this.agentName,
-      phase: 'plan',
-    });
-
-    if (result.success) {
-      this.currentPhase = 'plan';
-      this.trajectoryId = result.trajectoryId || null;
-      this.task = task;
-    }
-
-    return result.success;
-  }
-
-  /**
-   * Check if there's an active trajectory
-   */
-  hasActiveTrajectory(): boolean {
-    return this.currentPhase !== null;
-  }
-
-  /**
-   * Get the current task
-   */
-  getTask(): string | null {
-    return this.task;
-  }
-
-  /**
-   * Get trajectory ID
-   */
-  getTrajectoryId(): string | null {
-    return this.trajectoryId;
-  }
-
-  /**
-   * Record a message
-   */
-  async message(direction: 'sent' | 'received', from: string, to: string, body: string): Promise<void> {
-    if (!(await this.isAvailable())) return;
-
-    await recordMessage(direction, from, to, body);
-
-    // Check for phase transition based on content
-    const detectedPhase = detectPhaseFromContent(body);
-    if (detectedPhase && detectedPhase !== this.currentPhase) {
-      await this.transition(detectedPhase, 'Auto-detected from message content');
-    }
-  }
-
-  /**
-   * Transition to a new phase
-   */
-  async transition(phase: PDEROPhase, reason?: string): Promise<boolean> {
-    if (!(await this.isAvailable())) return false;
-    if (phase === this.currentPhase) return true;
-
-    const result = await transitionPhase(phase, reason, this.agentName);
-    if (result.success) {
-      this.currentPhase = phase;
-    }
-    return result.success;
-  }
-
-  /**
-   * Record a decision
-   */
-  async decision(choice: string, options?: Partial<DecisionOptions>): Promise<boolean> {
-    if (!(await this.isAvailable())) return false;
-
-    const result = await recordDecision({
-      choice,
-      ...options,
-    });
-    return result.success;
-  }
-
-  /**
-   * Record an event
-   */
-  async event(content: string, type: 'tool_call' | 'observation' | 'checkpoint' | 'error' = 'observation'): Promise<boolean> {
-    if (!(await this.isAvailable())) return false;
-
-    const result = await recordEvent(content, type, this.agentName);
-
-    // Check for phase transition
-    const detectedPhase = detectPhaseFromContent(content);
-    if (detectedPhase && detectedPhase !== this.currentPhase) {
-      await this.transition(detectedPhase, 'Auto-detected from event content');
-    }
-
-    return result.success;
-  }
-
-  /**
-   * Complete the trajectory
-   */
-  async complete(options?: CompleteTrajectoryOptions): Promise<boolean> {
-    if (!(await this.isAvailable())) return false;
-
-    const result = await completeTrajectory(options);
-    if (result.success) {
-      this.currentPhase = null;
-    }
-    return result.success;
-  }
-
-  /**
-   * Abandon the trajectory
-   */
-  async abandon(reason?: string): Promise<boolean> {
-    if (!(await this.isAvailable())) return false;
-
-    const result = await abandonTrajectory(reason);
-    if (result.success) {
-      this.currentPhase = null;
-    }
-    return result.success;
-  }
-
-  /**
-   * Get current phase
-   */
-  getPhase(): PDEROPhase | null {
-    return this.currentPhase;
-  }
-}
-
-/**
- * Global trajectory integration instances
- */
-const instances = new Map<string, TrajectoryIntegration>();
-
-/**
- * Get or create a TrajectoryIntegration instance
- */
-export function getTrajectoryIntegration(projectId: string, agentName: string): TrajectoryIntegration {
-  const key = `${projectId}:${agentName}`;
-  let instance = instances.get(key);
-  if (!instance) {
-    instance = new TrajectoryIntegration(projectId, agentName);
-    instances.set(key, instance);
-  }
-  return instance;
-}
-
-/**
- * Generate trail usage instructions for agents
- */
-export function getTrailInstructions(): string[] {
-  return [
-    '📍 TRAJECTORY TRACKING (PDERO Paradigm)',
-    '',
-    'You MUST use trail commands to track your work:',
-    '',
-    'PHASES: plan → design → execute → review → observe',
-    '',
-    'COMMANDS:',
-    '  trail start "task"           Start trajectory for a task',
-    '  trail phase <phase>          Transition to new phase',
-    '  trail decision "choice"      Record key decisions',
-    '  trail event "what happened"  Log significant events',
-    '  trail complete               Complete with summary',
-    '',
-    'WHEN TO USE:',
-    '  - Start: At beginning of any task',
-    '  - Phase: When shifting focus (planning→implementing, etc.)',
-    '  - Decision: For architecture/approach choices',
-    '  - Event: For tool calls, errors, milestones',
-    '  - Complete: When task is done',
-    '',
-    'Example workflow:',
-    '  trail start "Implement auth feature"',
-    '  trail phase design',
-    '  trail decision "Use JWT" --reasoning "Stateless, scalable"',
-    '  trail phase execute',
-    '  trail event "Created auth middleware"',
-    '  trail phase review',
-    '  trail event "All tests passing"',
-    '  trail complete --summary "Auth implemented" --confidence 0.9',
-  ];
-}
-
-/**
- * Get a compact trail instruction string for injection
- */
-export function getCompactTrailInstructions(): string {
-  return [
-    '[TRAIL] Track work with PDERO: plan→design→execute→review→observe.',
-    'Commands: trail start "task" | trail phase <phase> | trail decision "choice" | trail event "log" | trail complete',
-    'Use trail often to document your thought process.',
-  ].join(' ');
-}
-
-/**
- * Get environment variables for trail CLI
- * If dataDir is not provided, uses config-based storage location
- */
-export function getTrailEnvVars(projectId: string, agentName: string, dataDir?: string): Record<string, string> {
-  // Use config-based path if dataDir not explicitly provided
-  const effectiveDataDir = dataDir ?? getPrimaryTrajectoriesDir();
-
-  return {
-    TRAJECTORIES_PROJECT: projectId,
-    TRAJECTORIES_DATA_DIR: effectiveDataDir,
-    TRAJECTORIES_AGENT: agentName,
-    TRAIL_AUTO_PHASE: '1', // Enable auto phase detection
-  };
-}