echelon-dev 1.0.0

package/lib/echelon-pair-program.js

@@ -0,0 +1,610 @@
+#!/usr/bin/env node
+
+/**
+ * Echelon Dev Team - Multi-Agent Pair Programming
+ *
+ * Coordinates Knoxis, Solan, and Astrahelm as a dev team working
+ * together on a shared codebase. Each agent is a generalist engineer
+ * with a specialty — they contribute what's useful, nothing more.
+ *
+ * Usage:
+ *   node echelon-pair-program.js --workspace /path --prompt "task"
+ *   node echelon-pair-program.js -w my-project --prompt "add auth" --agents knoxis,astrahelm
+ *   node echelon-pair-program.js --workspace /path --prompt-base64 "..." --timeline-base64 "..."
+ *
+ * ZERO EXTERNAL DEPENDENCIES
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn, spawnSync } = require('child_process');
+const { getAgent, getAllAgents, getAgentIds, colorize, buildTeamSystemPrompt, RESET } = require('./agents');
+const { SessionRecorder } = require('./session-recorder');
+
+// ===== ARGUMENT PARSING =====
+
+function parseArgs(argv) {
+  const args = {};
+  const multi = {};
+  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] = true;
+      } else {
+        if (multi[key]) {
+          multi[key].push(next);
+        } else if (args[key]) {
+          multi[key] = [args[key], next];
+          delete args[key];
+        } else {
+          args[key] = next;
+        }
+        i++;
+      }
+    }
+  }
+  Object.entries(multi).forEach(([key, list]) => { args[key] = list; });
+  return args;
+}
+
+function decodeBase64(value) {
+  try {
+    return Buffer.from(value, 'base64').toString('utf8');
+  } catch (err) {
+    console.error('Failed to decode base64 value:', err.message);
+    process.exit(1);
+  }
+}
+
+function decodeJsonBase64(value, label) {
+  const decoded = decodeBase64(value);
+  try {
+    return JSON.parse(decoded);
+  } catch (err) {
+    console.error(`Failed to parse ${label} JSON: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+// ===== UTILITY =====
+
+function commandExists(cmd) {
+  const detector = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(detector, [cmd], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function resolveWorkspacePath(nameOrPath) {
+  if (fs.existsSync(nameOrPath)) {
+    return path.resolve(nameOrPath);
+  }
+
+  // Try workspace registries (echelon + knoxis)
+  const registries = [
+    path.join(os.homedir(), '.echelon', 'workspaces.json'),
+    path.join(os.homedir(), '.knoxis', 'workspaces.json')
+  ];
+
+  for (const registryFile of registries) {
+    if (fs.existsSync(registryFile)) {
+      try {
+        const workspaces = JSON.parse(fs.readFileSync(registryFile, 'utf8'));
+        if (workspaces[nameOrPath]) return workspaces[nameOrPath];
+        const lower = nameOrPath.toLowerCase();
+        for (const [name, wsPath] of Object.entries(workspaces)) {
+          if (name.toLowerCase().includes(lower)) {
+            console.log(`Matched workspace: ${name} -> ${wsPath}`);
+            return wsPath;
+          }
+        }
+      } catch (e) {}
+    }
+  }
+
+  return null;
+}
+
+function resolveAiProvider(preference) {
+  const normalized = (preference || 'auto').toLowerCase();
+  if (normalized === 'claude' && commandExists('claude')) {
+    return { cmd: 'claude', args: ['--dangerously-skip-permissions'], label: 'Claude Code' };
+  }
+  if (normalized === 'codex' && commandExists('codex')) {
+    return { cmd: 'codex', args: [], label: 'Codex' };
+  }
+  if (normalized === 'auto') {
+    if (commandExists('claude')) {
+      return { cmd: 'claude', args: ['--dangerously-skip-permissions'], label: 'Claude Code' };
+    }
+    if (commandExists('codex')) {
+      return { cmd: 'codex', args: [], label: 'Codex' };
+    }
+  }
+  console.error('No supported AI provider found. Install the Claude or Codex CLI and try again.');
+  process.exit(1);
+}
+
+function toArray(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) {
+    const result = [];
+    value.forEach(item => result.push(...toArray(item)));
+    return result;
+  }
+  return [value];
+}
+
+function formatSection(title, body) {
+  const border = '-'.repeat(title.length + 4);
+  return `${border}\n| ${title} |\n${border}\n${body.trim()}\n`;
+}
+
+function gatherContext(workspace, inputs) {
+  const sections = [];
+  const labels = [];
+  const seen = new Set();
+
+  toArray(inputs).forEach(entry => {
+    if (typeof entry !== 'string') return;
+    const trimmed = entry.trim();
+    if (!trimmed) return;
+    const absolute = path.isAbsolute(trimmed) ? trimmed : path.join(workspace, trimmed);
+    if (!fs.existsSync(absolute)) return;
+    if (seen.has(absolute)) return;
+    seen.add(absolute);
+    const content = fs.readFileSync(absolute, 'utf8');
+    const title = path.relative(workspace, absolute) || path.basename(absolute);
+    labels.push(title);
+    sections.push(formatSection(title, content));
+  });
+
+  return { sections, labels };
+}
+
+// ===== DEFAULT MULTI-AGENT TIMELINES =====
+
+/**
+ * Build the default multi-agent timeline.
+ * The timeline adapts based on which agents are included.
+ *
+ * With all 3 agents: understand → team plan → implement → review
+ * With 2 agents: understand → plan → implement → review
+ * With 1 agent: falls back to knoxis-style 4-step
+ */
+function buildDefaultTimeline(task, activeAgents) {
+  const agentIds = activeAgents.map(a => a.id);
+  const hasKnoxis = agentIds.includes('knoxis');
+  const hasSolan = agentIds.includes('solan');
+  const hasAstrahelm = agentIds.includes('astrahelm');
+
+  // Pick a lead agent — first available in priority order
+  const lead = hasKnoxis ? 'knoxis' : hasSolan ? 'solan' : 'astrahelm';
+  const leadAgent = getAgent(lead);
+
+  const steps = [];
+
+  // Step 1: Lead agent understands the codebase
+  steps.push({
+    key: 'understand',
+    title: 'Understanding',
+    agentId: lead,
+    displayName: leadAgent.name,
+    persona: leadAgent.persona,
+    instruction: `Let's understand what we're working with before diving in.
+
+The task: ${task}
+
+First:
+1. Read the relevant code to understand the current state
+2. Identify what needs to change
+3. Note any potential issues or dependencies
+
+Share your understanding briefly. For any ambiguities, state your assumption and move on - do not ask questions.`,
+    includeContext: true
+  });
+
+  // Step 2: Team weighs in on approach (if multiple agents)
+  if (activeAgents.length > 1) {
+    const otherAgents = activeAgents.filter(a => a.id !== lead);
+    const othersIntro = otherAgents.map(a => `${a.name} (${a.specialty})`).join(' and ');
+
+    steps.push({
+      key: 'team-input',
+      title: 'Team Input',
+      agentId: otherAgents[0].id,
+      displayName: otherAgents.map(a => a.name).join(' & '),
+      persona: otherAgents.length === 1
+        ? otherAgents[0].persona
+        : `You are providing perspective from ${othersIntro}. Think from each angle but only contribute what's genuinely useful for this specific task. If your specialty doesn't apply here, say so briefly and focus on general engineering quality.`,
+      instruction: `You've seen ${leadAgent.name}'s assessment. Now weigh in from your perspective${otherAgents.length > 1 ? 's' : ''}.
+
+Rules:
+- Only raise points that are actually relevant to THIS task
+- If your specialty doesn't apply, say "nothing specific from my angle" and move on
+- Don't repeat what ${leadAgent.name} already covered
+- If you agree with the approach, say so briefly and add any considerations
+- Be concrete — if you flag something, suggest what to do about it`,
+      includeContext: false
+    });
+  }
+
+  // Step 3: Lead plans and implements
+  steps.push({
+    key: 'plan',
+    title: 'Planning',
+    agentId: lead,
+    displayName: leadAgent.name,
+    persona: leadAgent.persona,
+    instruction: `Good.${activeAgents.length > 1 ? " Incorporate the team's input where it makes sense." : ''} Now create a concrete implementation plan for: ${task}
+
+Plan requirements:
+1. What files need to be created or modified?
+2. What's the order of changes?
+3. What could go wrong?
+4. How will we verify it works?
+
+For any open questions, make your best judgment call and note the decision. Do not ask - decide and move forward.`,
+    includeContext: false
+  });
+
+  // Step 4: Implement
+  steps.push({
+    key: 'implement',
+    title: 'Implementation',
+    agentId: lead,
+    displayName: leadAgent.name,
+    persona: leadAgent.persona,
+    instruction: `Now implement the plan. Work through it step by step.
+
+Rules:
+- Make one logical change at a time
+- For any decisions or unknowns, pick the most standard approach and note your choice
+- If you flagged questions earlier, answer them yourself with reasonable defaults and proceed
+- Flag if you hit something truly blocking (missing credentials, broken dependencies)
+- Otherwise, keep building
+
+Start implementing now.`,
+    includeContext: false
+  });
+
+  // Step 5: Team review (if multiple agents)
+  if (activeAgents.length > 1) {
+    // Each non-lead agent reviews from their angle
+    const reviewAgents = activeAgents.filter(a => a.id !== lead);
+
+    steps.push({
+      key: 'review',
+      title: 'Team Review',
+      agentId: reviewAgents[0].id,
+      displayName: reviewAgents.map(a => a.name).join(' & '),
+      persona: reviewAgents.length === 1
+        ? reviewAgents[0].persona
+        : `You are reviewing the implementation from the perspectives of ${reviewAgents.map(a => `${a.name} (${a.specialty})`).join(' and ')}. Be pragmatic — only flag real issues.`,
+      instruction: `Review what ${leadAgent.name} built.
+
+For each perspective you represent:
+- Does it solve the original problem correctly?
+- Are there any genuine issues from your angle? (Only flag real problems, not theoretical ones)
+- Any quick improvements that are clearly worth making?
+
+If everything looks good from your angle, say so. Don't invent problems.
+If you find real issues, be specific about what to fix and why.`,
+      includeContext: false
+    });
+  }
+
+  // Final step: Verify
+  steps.push({
+    key: 'verify',
+    title: 'Final Check',
+    agentId: lead,
+    displayName: leadAgent.name,
+    persona: leadAgent.persona,
+    instruction: `Let's do a final check on what we built.
+
+Quick checklist:
+- Does it solve the original problem?
+- Any edge cases we missed?
+- Is the code clean and following project patterns?
+- Anything we should test?
+${activeAgents.length > 1 ? `- Address any issues the team flagged in the review\n` : ''}
+Give me the summary and any follow-up recommendations.`,
+    includeContext: false
+  });
+
+  return steps;
+}
+
+// ===== PROMPT BUILDING =====
+
+function buildPrompt(options) {
+  const {
+    systemIntro,
+    personaIntro,
+    conversation,
+    instructionLabel,
+    instructionTitle,
+    instruction,
+    includeContextBlock,
+    globalContext,
+    stepContext,
+    agentLabel
+  } = options;
+
+  const sections = [];
+
+  if (systemIntro) sections.push(systemIntro);
+  if (personaIntro) sections.push(`Your role for this step:\n${personaIntro}`);
+  if (includeContextBlock && globalContext) sections.push(`Project context:\n${globalContext}`);
+  if (includeContextBlock && stepContext) sections.push(`Step-specific context:\n${stepContext}`);
+  if (conversation) sections.push(`Conversation so far:\n${conversation}`);
+
+  const heading = instructionTitle
+    ? `${instructionLabel} -> ${agentLabel} (${instructionTitle})`
+    : `${instructionLabel} -> ${agentLabel}`;
+
+  sections.push(`${heading}:\n${instruction}`);
+  sections.push(`${agentLabel}:`);
+
+  return sections.join('\n\n');
+}
+
+// ===== AI EXECUTION =====
+
+async function callAi(aiConfig, prompt, livePrinter) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(aiConfig.cmd, aiConfig.args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    let pendingLine = '';
+
+    proc.stdout.on('data', chunk => {
+      const text = chunk.toString();
+      stdout += text;
+      pendingLine += text;
+      let index;
+      while ((index = pendingLine.indexOf('\n')) !== -1) {
+        const line = pendingLine.slice(0, index);
+        pendingLine = pendingLine.slice(index + 1);
+        livePrinter(line);
+      }
+    });
+
+    proc.stderr.on('data', chunk => {
+      stderr += chunk.toString();
+    });
+
+    proc.on('close', code => {
+      if (pendingLine.length) {
+        livePrinter(pendingLine);
+        pendingLine = '';
+      }
+      if (code === 0) {
+        resolve(stdout.trim());
+      } else {
+        reject(new Error(stderr.trim() || `AI command exited with status ${code}`));
+      }
+    });
+
+    proc.stdin.write(prompt);
+    proc.stdin.end();
+  });
+}
+
+// ===== MAIN =====
+
+async function run() {
+  const args = parseArgs(process.argv);
+  const workspaceArg = args.workspace || args['workspace-dir'] || args['working-directory'] || args.w;
+
+  if (!workspaceArg) {
+    console.error('Missing required --workspace argument.');
+    console.error('Usage: echelon-pair-program --workspace <path> --prompt "task"');
+    console.error('       echelon-pair-program -w my-project --prompt "build auth" --agents knoxis,solan');
+    process.exit(1);
+  }
+
+  let workspace = resolveWorkspacePath(workspaceArg);
+  if (!workspace) {
+    workspace = path.resolve(workspaceArg);
+    console.log(`Creating new workspace: ${workspace}`);
+  }
+  if (!fs.existsSync(workspace)) {
+    fs.mkdirSync(workspace, { recursive: true });
+  }
+
+  // Parse timeline (custom steps from backend)
+  const timeline = args['timeline-base64'] ? decodeJsonBase64(args['timeline-base64'], 'timeline') : null;
+
+  // Parse task
+  let task = args['prompt-base64'] ? decodeBase64(args['prompt-base64']) : args.prompt;
+  if ((!task || !task.trim()) && timeline && typeof timeline.task === 'string') {
+    task = timeline.task;
+  }
+  if (!task || !task.trim()) {
+    console.error('A task prompt is required via --prompt, --prompt-base64, or timeline.task.');
+    process.exit(1);
+  }
+  task = task.trim();
+
+  // Resolve AI provider
+  const aiConfig = resolveAiProvider(args['ai-provider'] || args.provider);
+
+  // Resolve which agents are active
+  let activeAgents;
+  const agentArg = args.agents;
+  if (agentArg) {
+    const requested = (Array.isArray(agentArg) ? agentArg.join(',') : agentArg)
+      .split(',')
+      .map(s => s.trim().toLowerCase())
+      .filter(Boolean);
+    activeAgents = requested.map(id => getAgent(id)).filter(Boolean);
+  } else if (timeline && Array.isArray(timeline.agents)) {
+    activeAgents = timeline.agents.map(id => getAgent(id)).filter(Boolean);
+  } else {
+    activeAgents = getAllAgents();
+  }
+
+  if (activeAgents.length === 0) {
+    console.error('No valid agents specified. Available: ' + getAgentIds().join(', '));
+    process.exit(1);
+  }
+
+  // Gather context files
+  const globalContextInputs = [];
+  if (args['context']) globalContextInputs.push(args['context']);
+  if (args['context-file']) globalContextInputs.push(args['context-file']);
+  if (timeline && Array.isArray(timeline.sharedContext)) {
+    globalContextInputs.push(timeline.sharedContext);
+  }
+  const globalContext = gatherContext(workspace, globalContextInputs);
+  const globalContextBlock = globalContext.sections.join('\n\n');
+
+  // Build steps
+  let scheduledSteps;
+  if (timeline && Array.isArray(timeline.steps) && timeline.steps.length) {
+    // Custom timeline from backend
+    scheduledSteps = timeline.steps.map((step, index) => ({
+      key: step.key || `step-${index + 1}`,
+      title: step.title || '',
+      agentId: step.agentId || step.displayName?.toLowerCase() || activeAgents[0].id,
+      displayName: step.displayName || step.agentId || `Agent ${index + 1}`,
+      persona: step.persona || null,
+      instruction: typeof step.instruction === 'string' && step.instruction.trim().length
+        ? step.instruction
+        : `Proceed with the shared task: ${task}`,
+      contextPaths: step.contextFiles || [],
+      includeContext: Boolean(step.includeContext)
+    }));
+  } else {
+    // Smart default timeline
+    scheduledSteps = buildDefaultTimeline(task, activeAgents);
+  }
+
+  if (!scheduledSteps.length) {
+    console.error('No steps configured for the session.');
+    process.exit(1);
+  }
+
+  // Disable recording with --no-record
+  const recordingEnabled = !args['no-record'];
+
+  // Initialize session recorder
+  let recorder = null;
+  if (recordingEnabled) {
+    recorder = new SessionRecorder({
+      task,
+      workspace,
+      agents: activeAgents.map(a => a.id),
+      aiProvider: aiConfig.label
+    });
+  }
+
+  // Print session header
+  const agentNames = activeAgents.map(a => colorize(a.id, a.name)).join(', ');
+  console.log('==============================================');
+  console.log('Echelon Dev Team - Pair Programming Session');
+  console.log(`Workspace: ${workspace}`);
+  console.log(`AI Partner: ${aiConfig.label}`);
+  console.log(`Team: ${agentNames}${RESET}`);
+  console.log(`Task: ${task}`);
+  if (recordingEnabled) console.log(`Recording: ON`);
+  console.log('==============================================');
+  console.log('');
+
+  if (globalContext.labels.length) {
+    console.log(`Shared context files: ${globalContext.labels.join(', ')}`);
+    console.log('');
+  }
+
+  // Build team system prompt
+  const systemIntro = buildTeamSystemPrompt(activeAgents);
+
+  // Execute steps
+  const history = [];
+  const conversationLines = () => history.map(entry => `${entry.role}: ${entry.content}`).join('\n\n');
+
+  for (let i = 0; i < scheduledSteps.length; i++) {
+    const step = scheduledSteps[i];
+    const agent = getAgent(step.agentId);
+
+    // Gather step-specific context
+    const stepContext = gatherContext(workspace, step.contextPaths || []);
+    if (stepContext.labels.length) {
+      console.log(`Step context for ${step.displayName}: ${stepContext.labels.join(', ')}`);
+      console.log('');
+    }
+
+    // Print step header
+    const titleSuffix = step.title ? ` (${step.title})` : '';
+    const agentColor = agent ? agent.color : '';
+    console.log(`Coordinator -> ${agentColor}${step.displayName}${RESET}${titleSuffix}:`);
+    console.log(step.instruction);
+    console.log('');
+
+    history.push({ role: 'Coordinator', content: step.instruction });
+
+    console.log(`${agentColor}${step.displayName}${RESET}:`);
+
+    // Build prompt
+    const includeContext = history.length <= 2 || step.includeContext || (stepContext.sections.length > 0);
+    const prompt = buildPrompt({
+      systemIntro,
+      personaIntro: step.persona,
+      conversation: conversationLines(),
+      instructionLabel: 'Coordinator',
+      instructionTitle: step.title,
+      instruction: step.instruction,
+      includeContextBlock: includeContext,
+      globalContext: globalContextBlock,
+      stepContext: stepContext.sections.join('\n\n'),
+      agentLabel: step.displayName
+    });
+
+    // Record step
+    let stepIndex = -1;
+    if (recorder) {
+      stepIndex = recorder.startStep(step.key, step.agentId, step.instruction);
+      recorder.setStepPrompt(stepIndex, prompt);
+    }
+
+    try {
+      const response = await callAi(aiConfig, prompt, line => {
+        console.log(`  ${line}`);
+      });
+      history.push({ role: step.displayName, content: response });
+
+      if (recorder) {
+        recorder.completeStep(stepIndex, response, null);
+      }
+
+      console.log('');
+    } catch (err) {
+      console.error(`Failed to complete step "${step.title || step.key}": ${err.message}`);
+
+      if (recorder) {
+        recorder.completeStep(stepIndex, null, err.message);
+      }
+
+      process.exit(1);
+    }
+  }
+
+  // Save recording
+  if (recorder) {
+    const recordPath = recorder.save();
+    console.log(`Session recorded: ${recordPath}`);
+    console.log('');
+  }
+
+  console.log('Session complete. The Echelon dev team is standing by for further instructions.');
+}
+
+run().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});