chati-dev 2.0.4 → 2.0.6

package/src/terminal/handoff-parser.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Parse structured handoff data from spawned agent output.
+ *
+ * Agents running in separate `claude -p` terminals include a
+ * <chati-handoff> block in their output. This module extracts
+ * and parses that block so the orchestrator can read the results.
+ */
+
+/**
+ * Parse the <chati-handoff> block from agent stdout.
+ *
+ * @param {string} output - Full stdout from the agent process
+ * @returns {{ found: boolean, handoff: object|null, rawOutput: string }}
+ */
+export function parseAgentOutput(output) {
+  if (!output || typeof output !== 'string') {
+    return { found: false, handoff: null, rawOutput: '' };
+  }
+
+  const match = output.match(/<chati-handoff>([\s\S]*?)<\/chati-handoff>/);
+  if (!match) {
+    return { found: false, handoff: null, rawOutput: output };
+  }
+
+  const content = match[1].trim();
+  const handoff = parseHandoffFields(content);
+
+  return { found: true, handoff, rawOutput: output };
+}
+
+/**
+ * Parse YAML-like key-value fields from the handoff block content.
+ *
+ * Supports:
+ *   scalar: value
+ *   list:
+ *     - item1
+ *     - item2
+ *   map:
+ *     key1: value1
+ *     key2: value2
+ *
+ * @param {string} content - Content inside <chati-handoff> tags
+ * @returns {object} Parsed handoff data
+ */
+function parseHandoffFields(content) {
+  const result = {
+    status: 'unknown',
+    score: null,
+    summary: '',
+    outputs: [],
+    decisions: {},
+    blockers: [],
+    needs_input_question: null,
+  };
+
+  const lines = content.split('\n');
+  let currentKey = null;
+  let currentType = null; // 'list' | 'map'
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    // Check if this is a list item (  - value)
+    const listMatch = trimmed.match(/^-\s+(.+)/);
+    if (listMatch && currentKey && currentType === 'list') {
+      if (Array.isArray(result[currentKey])) {
+        result[currentKey].push(listMatch[1].trim());
+      }
+      continue;
+    }
+
+    // Check if this is a map item (  key: value) under a map key
+    const mapMatch = trimmed.match(/^(\w[\w_-]*):\s+(.+)/);
+    if (mapMatch && currentKey && currentType === 'map') {
+      if (typeof result[currentKey] === 'object' && !Array.isArray(result[currentKey])) {
+        result[currentKey][mapMatch[1]] = mapMatch[2].trim();
+      }
+      continue;
+    }
+
+    // Top-level key: value
+    const kvMatch = trimmed.match(/^(\w[\w_-]*):\s*(.*)/);
+    if (kvMatch) {
+      const key = kvMatch[1];
+      const value = kvMatch[2].trim();
+
+      // Known list keys
+      if (['outputs', 'blockers'].includes(key)) {
+        currentKey = key;
+        currentType = 'list';
+        // If value is inline (not empty), treat as single item
+        if (value && value !== '') {
+          result[key] = [value];
+          currentKey = null;
+          currentType = null;
+        }
+        continue;
+      }
+
+      // Known map keys
+      if (['decisions'].includes(key)) {
+        currentKey = key;
+        currentType = 'map';
+        continue;
+      }
+
+      // Scalar keys
+      currentKey = null;
+      currentType = null;
+
+      if (key === 'status') {
+        result.status = value || 'unknown';
+      } else if (key === 'score') {
+        const num = parseInt(value, 10);
+        result.score = isNaN(num) ? null : num;
+      } else if (key === 'summary') {
+        result.summary = value || '';
+      } else if (key === 'needs_input_question') {
+        result.needs_input_question = value === 'null' || value === '' ? null : value;
+      }
+    }
+  }
+
+  return result;
+}

package/src/terminal/index.js

@@ -28,3 +28,12 @@ export {
   getReadScope,
   buildIsolationEnv,
 } from './isolation.js';
+
+export {
+  buildAgentPrompt,
+  AGENT_FILE_MAP,
+} from './prompt-builder.js';
+
+export {
+  parseAgentOutput,
+} from './handoff-parser.js';

package/src/terminal/prompt-builder.js

@@ -0,0 +1,313 @@
+/**
+ * @fileoverview Prompt builder for multi-terminal agent execution.
+ *
+ * Builds a complete, self-contained prompt for spawned agent terminals.
+ * When an agent runs in a separate `claude -p` process, it has zero
+ * conversation history — the prompt must contain everything: PRISM
+ * context, agent definition, previous handoff, write scope, and
+ * output format instructions.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { runPrism } from '../context/engine.js';
+import { loadHandoff, formatHandoff } from '../tasks/handoff.js';
+import { getWriteScope } from './isolation.js';
+
+// Re-read at import time so the prompt builder always uses the correct map
+// without circular dependency issues (the hook file runs main() on import
+// which writes to stdout — we only need the data, so we inline the map).
+const AGENT_MODELS = {
+  orchestrator: 'sonnet',
+  'greenfield-wu': 'haiku',
+  'brownfield-wu': 'opus',
+  brief: 'sonnet',
+  detail: 'opus',
+  architect: 'opus',
+  ux: 'sonnet',
+  phases: 'sonnet',
+  tasks: 'sonnet',
+  'qa-planning': 'opus',
+  'qa-implementation': 'opus',
+  dev: 'opus',
+  devops: 'sonnet',
+};
+
+/**
+ * Map of agent names to their definition file paths (relative to project root).
+ */
+export const AGENT_FILE_MAP = {
+  'greenfield-wu': 'chati.dev/agents/planning/greenfield-wu.md',
+  'brownfield-wu': 'chati.dev/agents/planning/brownfield-wu.md',
+  brief: 'chati.dev/agents/planning/brief.md',
+  detail: 'chati.dev/agents/planning/detail.md',
+  architect: 'chati.dev/agents/planning/architect.md',
+  ux: 'chati.dev/agents/planning/ux.md',
+  phases: 'chati.dev/agents/planning/phases.md',
+  tasks: 'chati.dev/agents/planning/tasks.md',
+  'qa-planning': 'chati.dev/agents/quality/qa-planning.md',
+  dev: 'chati.dev/agents/build/dev.md',
+  'qa-implementation': 'chati.dev/agents/quality/qa-implementation.md',
+  devops: 'chati.dev/agents/deploy/devops.md',
+};
+
+/**
+ * @typedef {object} PromptBuildConfig
+ * @property {string} agent           - Agent name (e.g. 'detail')
+ * @property {string} taskId          - Task identifier
+ * @property {string} projectDir      - Project root (absolute path)
+ * @property {string} [previousAgent] - Agent that produced the handoff
+ * @property {string} [workflow]      - Active workflow name
+ * @property {object} [sessionState]  - Parsed session.yaml fields
+ * @property {string[]} [writeScope]  - Override write scope
+ * @property {string} [additionalContext] - Extra context (e.g. user answer to needs_input)
+ */
+
+/**
+ * Build a complete, self-contained prompt for a spawned agent terminal.
+ *
+ * @param {PromptBuildConfig} config
+ * @returns {{ prompt: string, model: string, metadata: { agent: string, layers: number, promptSize: number } }}
+ */
+export function buildAgentPrompt(config) {
+  if (!config || !config.agent) {
+    throw new Error('buildAgentPrompt requires config.agent');
+  }
+  if (!config.projectDir) {
+    throw new Error('buildAgentPrompt requires config.projectDir');
+  }
+
+  const sections = [];
+
+  // 1. PRISM Context (L0-L4) — spawned terminals always start FRESH
+  const prismResult = buildPrismSection(config);
+  if (prismResult.xml) {
+    sections.push(prismResult.xml);
+  }
+
+  // 2. Agent definition (.md file)
+  const agentDef = loadAgentDefinition(config.agent, config.projectDir);
+  if (agentDef) {
+    sections.push('<!-- AGENT DEFINITION -->\n' + agentDef);
+  }
+
+  // 3. Previous handoff
+  const handoffSection = buildHandoffSection(config);
+  if (handoffSection) {
+    sections.push(handoffSection);
+  }
+
+  // 4. Additional context (user input relay for needs_input)
+  if (config.additionalContext) {
+    sections.push(
+      '<!-- ADDITIONAL CONTEXT -->\n' +
+      '## Additional Context from User\n\n' +
+      config.additionalContext
+    );
+  }
+
+  // 5. Write scope instructions
+  sections.push(buildWriteScopeSection(config));
+
+  // 6. Session context
+  sections.push(buildSessionSection(config));
+
+  // 7. Output format instructions (handoff template)
+  sections.push(buildOutputInstructions());
+
+  const prompt = sections.join('\n\n---\n\n');
+  const model = AGENT_MODELS[config.agent] || 'sonnet';
+
+  return {
+    prompt,
+    model,
+    metadata: {
+      agent: config.agent,
+      layers: prismResult.layerCount || 0,
+      promptSize: prompt.length,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the PRISM context engine for the agent.
+ * Spawned terminals always start FRESH (remainingPercent: 100).
+ */
+function buildPrismSection(config) {
+  const domainsDir = join(config.projectDir, 'chati.dev', 'domains');
+
+  if (!existsSync(domainsDir)) {
+    return { xml: null, layerCount: 0 };
+  }
+
+  const state = config.sessionState || {};
+
+  // Load handoff data for PRISM L3
+  let handoff = {};
+  if (config.previousAgent) {
+    const loaded = loadHandoff(config.projectDir, config.previousAgent);
+    if (loaded.loaded && loaded.handoff) {
+      handoff = loaded.handoff;
+    }
+  }
+
+  const result = runPrism({
+    domainsDir,
+    remainingPercent: 100, // Spawned terminals are always FRESH
+    mode: state.project?.state || 'planning',
+    agent: config.agent,
+    workflow: config.workflow || null,
+    pipelinePosition: config.agent,
+    taskId: config.taskId || null,
+    handoff,
+    artifacts: state.artifacts || [],
+    taskCriteria: [],
+  });
+
+  return {
+    xml: result.xml || null,
+    layerCount: result.layerCount || 0,
+  };
+}
+
+/**
+ * Load the agent's full .md definition file.
+ */
+function loadAgentDefinition(agent, projectDir) {
+  const relativePath = AGENT_FILE_MAP[agent];
+  if (!relativePath) return null;
+
+  const fullPath = join(projectDir, relativePath);
+  if (!existsSync(fullPath)) return null;
+
+  return readFileSync(fullPath, 'utf-8');
+}
+
+/**
+ * Build the previous handoff section for the prompt.
+ */
+function buildHandoffSection(config) {
+  if (!config.previousAgent) return null;
+
+  const result = loadHandoff(config.projectDir, config.previousAgent);
+  if (!result.loaded || !result.handoff) return null;
+
+  return (
+    '<!-- PREVIOUS HANDOFF -->\n' +
+    `## Handoff from ${config.previousAgent}\n\n` +
+    formatHandoff({
+      from: {
+        agent: result.handoff.from_agent || config.previousAgent,
+        task_id: result.handoff.from_task || 'unknown',
+        phase: result.handoff.from_phase || 'unknown',
+      },
+      to: config.agent,
+      timestamp: result.handoff.timestamp || new Date().toISOString(),
+      status: result.handoff.status || 'unknown',
+      score: result.handoff.score,
+      summary: result.handoff.summary || '',
+      outputs: result.handoff.outputs || [],
+      decisions: result.handoff.decisions || {},
+      blockers: result.handoff.blockers || [],
+      criteria_met: result.handoff.criteria_met || [],
+      criteria_unmet: result.handoff.criteria_unmet || [],
+    })
+  );
+}
+
+/**
+ * Build write scope instructions embedded in the prompt.
+ * This is the primary enforcement mechanism — env vars alone are not
+ * respected by the spawned Claude process.
+ */
+function buildWriteScopeSection(config) {
+  const scope = config.writeScope || getWriteScope(config.agent);
+
+  if (scope.length === 0) {
+    return (
+      '<!-- WRITE SCOPE -->\n' +
+      '## Write Scope (MANDATORY)\n\n' +
+      'You have NO write access. This is a read-only execution.\n' +
+      'Do NOT use Write, Edit, or any file-modifying tool.'
+    );
+  }
+
+  const paths = scope.map(p => `- \`${p}\``).join('\n');
+
+  return (
+    '<!-- WRITE SCOPE -->\n' +
+    '## Write Scope (MANDATORY)\n\n' +
+    'You may ONLY write to these paths:\n' +
+    paths + '\n\n' +
+    '**All other write operations are BLOCKED.** Do NOT attempt to write, edit, or create files outside these paths. ' +
+    'Read access is unrestricted — you may read any file in the project.'
+  );
+}
+
+/**
+ * Build session context section.
+ */
+function buildSessionSection(config) {
+  const state = config.sessionState || {};
+  const project = state.project || {};
+
+  const lines = [
+    '<!-- SESSION CONTEXT -->',
+    '## Session Context',
+    '',
+    `- **Project**: ${project.name || '(unnamed)'}`,
+    `- **Type**: ${project.type || 'greenfield'}`,
+    `- **Mode**: ${project.state || 'planning'}`,
+    `- **Language**: ${state.language || 'en'} (interaction) / English (artifacts)`,
+    `- **User Level**: ${state.user_level || 'auto'}`,
+    `- **Execution Mode**: ${state.execution_mode || 'autonomous'}`,
+    `- **Your Agent**: ${config.agent}`,
+    `- **Your Model**: ${AGENT_MODELS[config.agent] || 'sonnet'}`,
+  ];
+
+  return lines.join('\n');
+}
+
+/**
+ * Build output format instructions so the agent produces a parseable handoff.
+ */
+function buildOutputInstructions() {
+  return `<!-- OUTPUT INSTRUCTIONS -->
+## Output Instructions (MANDATORY)
+
+When you complete your work, you MUST include a structured handoff block at the END of your response.
+This block is how the orchestrator reads your results. Without it, your work cannot be collected.
+
+\`\`\`
+<chati-handoff>
+status: complete
+score: 95
+summary: One to three sentence summary of what was accomplished.
+outputs:
+  - path/to/artifact1.md
+  - path/to/artifact2.md
+decisions:
+  key1: value1
+  key2: value2
+blockers:
+  - Description of any unresolved blocker
+needs_input_question: null
+</chati-handoff>
+\`\`\`
+
+### Status values:
+- **complete**: All work finished successfully (score >= 95 required)
+- **partial**: Some work done but not all criteria met
+- **needs_input**: You need information from the user to continue. Set \`needs_input_question\` to your question.
+- **error**: Something went wrong that you cannot recover from
+
+### Important:
+- The \`<chati-handoff>\` block MUST appear in your response
+- Score must be 0-100 (95+ to pass quality gate)
+- List ALL artifacts you created/modified in outputs
+- If you need user input, set status to "needs_input" and write your question in needs_input_question`;
+}

package/src/terminal/run-agent.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * CLI runner for single-agent terminal execution.
+ *
+ * Called by the orchestrator via the Bash tool to spawn an agent
+ * in a separate Claude Code process with the correct model.
+ *
+ * Usage:
+ *   node run-agent.js --agent detail --task-id expand-prd \
+ *     --project-dir /path/to/project --previous-agent brief \
+ *     --timeout 600000
+ *
+ * Outputs JSON to stdout for the orchestrator to parse.
+ */
+
+import { fileURLToPath } from 'url';
+import { buildAgentPrompt } from './prompt-builder.js';
+import { spawnTerminal } from './spawner.js';
+import { parseAgentOutput } from './handoff-parser.js';
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing (no external deps)
+// ---------------------------------------------------------------------------
+
+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);
+
+  // Validate required args
+  if (!args.agent) {
+    outputError('Missing required argument: --agent');
+    process.exit(1);
+  }
+  if (!args['task-id']) {
+    outputError('Missing required argument: --task-id');
+    process.exit(1);
+  }
+
+  const projectDir = args['project-dir'] || process.cwd();
+  const timeout = parseInt(args.timeout, 10) || 600_000; // default 10 minutes
+
+  // Load session state if available
+  let sessionState = {};
+  try {
+    const { existsSync, readFileSync } = await import('fs');
+    const { join } = await import('path');
+    const sessionPath = join(projectDir, '.chati', 'session.yaml');
+    if (existsSync(sessionPath)) {
+      const raw = readFileSync(sessionPath, 'utf-8');
+      sessionState = parseSimpleYaml(raw);
+    }
+  } catch {
+    // Session state is optional — continue without it
+  }
+
+  // Build the agent prompt
+  let promptResult;
+  try {
+    promptResult = buildAgentPrompt({
+      agent: args.agent,
+      taskId: args['task-id'],
+      projectDir,
+      previousAgent: args['previous-agent'] || null,
+      workflow: args.workflow || null,
+      sessionState,
+      additionalContext: args['additional-context'] || null,
+    });
+  } catch (err) {
+    outputError(`Failed to build prompt: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Spawn the agent terminal
+  const startTime = Date.now();
+  let handle;
+
+  try {
+    handle = spawnTerminal({
+      agent: args.agent,
+      taskId: args['task-id'],
+      model: promptResult.model,
+      prompt: promptResult.prompt,
+      workingDir: projectDir,
+      timeout,
+    });
+  } catch (err) {
+    outputError(`Failed to spawn terminal: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Wait for the process to complete
+  try {
+    await waitForExit(handle, timeout);
+  } catch (err) {
+    outputError(`Terminal execution failed: ${err.message}`);
+    process.exit(2);
+  }
+
+  const elapsed = Date.now() - startTime;
+  const stdout = handle.stdout.join('');
+  const stderr = handle.stderr.join('');
+
+  // Parse the handoff from stdout
+  const parsed = parseAgentOutput(stdout);
+
+  if (parsed.found) {
+    outputResult({
+      status: parsed.handoff.status,
+      agent: args.agent,
+      model: promptResult.model,
+      exitCode: handle.exitCode,
+      handoff: parsed.handoff,
+      elapsed,
+    });
+  } else {
+    // No handoff block found — return raw output
+    outputResult({
+      status: handle.exitCode === 0 ? 'partial' : 'error',
+      agent: args.agent,
+      model: promptResult.model,
+      exitCode: handle.exitCode,
+      handoff: null,
+      rawOutput: stdout.slice(0, 5000), // Truncate to avoid huge JSON
+      stderr: stderr.slice(0, 2000),
+      elapsed,
+    });
+  }
+
+  process.exit(handle.exitCode === 0 ? 0 : 1);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wait for a terminal handle's process to exit.
+ */
+function waitForExit(handle, timeout) {
+  return new Promise((resolve, reject) => {
+    if (handle.status === 'exited') {
+      return resolve();
+    }
+
+    const timer = setTimeout(() => {
+      if (handle.process && typeof handle.process.kill === 'function') {
+        try { handle.process.kill('SIGKILL'); } catch { /* ignore */ }
+      }
+      handle.status = 'exited';
+      handle.exitCode = -2;
+      reject(new Error(`Terminal timed out after ${Math.round(timeout / 1000)}s`));
+    }, timeout);
+
+    handle.process.once('exit', () => {
+      clearTimeout(timer);
+      resolve();
+    });
+
+    handle.process.once('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Output a structured JSON result to stdout.
+ */
+function outputResult(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Output an error as JSON to stdout (so orchestrator can parse it).
+ */
+function outputError(message) {
+  process.stdout.write(JSON.stringify({ status: 'error', error: message }) + '\n');
+}
+
+/**
+ * Minimal YAML parser for session.yaml (handles flat and one-level nested keys).
+ */
+function parseSimpleYaml(content) {
+  const result = {};
+  let currentSection = null;
+
+  for (const line of content.split('\n')) {
+    if (line.trim() === '' || line.trim().startsWith('#')) continue;
+
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+    const kvMatch = trimmed.match(/^([\w_-]+):\s*(.*)/);
+
+    if (kvMatch) {
+      const key = kvMatch[1];
+      const value = kvMatch[2].trim().replace(/^["']|["']$/g, '');
+
+      if (indent === 0) {
+        if (value === '' || value === undefined) {
+          // Section header
+          currentSection = key;
+          result[key] = result[key] || {};
+        } else {
+          result[key] = value;
+          currentSection = null;
+        }
+      } else if (currentSection && indent > 0) {
+        if (typeof result[currentSection] !== 'object') {
+          result[currentSection] = {};
+        }
+        result[currentSection][key] = value;
+      }
+    }
+  }
+
+  return result;
+}
+
+// Guard pattern (per project convention)
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch(err => {
+    outputError(err.message);
+    process.exit(1);
+  });
+}
+
+export { parseArgs, waitForExit, parseSimpleYaml };