chati-dev 4.3.0 → 4.4.0

package/src/autonomy/build-state.js

@@ -1,286 +0,0 @@
-/**
- * @fileoverview Build state manager with checkpoint-based persistence.
- *
- * Manages the state of autonomous build execution, including
- * checkpoints saved after each task completion, abandoned build
- * detection, and attempt logging.
- *
- * Constitution Article XVII — Execution Mode Governance.
- */
-
-import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
-import { join, dirname } from 'path';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Maximum iterations per individual task before giving up */
-export const MAX_ITERATIONS_PER_TASK = 10;
-
-/** Maximum time per individual task before giving up (10 minutes) */
-export const MAX_TIME_PER_TASK_MS = 10 * 60 * 1000;
-
-/** Global timeout for an autonomous build session (30 minutes) */
-export const GLOBAL_TIMEOUT_MS = 30 * 60 * 1000;
-
-/** Time after which a build is considered abandoned (1 hour) */
-export const ABANDONED_THRESHOLD_MS = 60 * 60 * 1000;
-
-/**
- * Build status enum.
- * @enum {string}
- */
-export const BuildStatus = {
-  PENDING: 'pending',
-  IN_PROGRESS: 'in_progress',
-  PAUSED: 'paused',
-  ABANDONED: 'abandoned',
-  FAILED: 'failed',
-  COMPLETED: 'completed',
-};
-
-/**
- * Task checkpoint status.
- * @enum {string}
- */
-export const CheckpointStatus = {
-  PENDING: 'pending',
-  IN_PROGRESS: 'in_progress',
-  COMPLETED: 'completed',
-  FAILED: 'failed',
-  SKIPPED: 'skipped',
-};
-
-// ---------------------------------------------------------------------------
-// State Schema
-// ---------------------------------------------------------------------------
-
-/**
- * @typedef {object} TaskCheckpoint
- * @property {string} taskId
- * @property {string} status - CheckpointStatus
- * @property {number} attempts - Number of execution attempts
- * @property {string|null} firstAttempt - ISO timestamp of first attempt
- * @property {string|null} lastAttempt - ISO timestamp of last attempt
- * @property {string|null} output - Last output summary
- * @property {string|null} error - Last error message (if failed)
- */
-
-/**
- * @typedef {object} BuildState
- * @property {string} sessionId - Build session identifier
- * @property {string} status - BuildStatus
- * @property {TaskCheckpoint[]} checkpoints - Per-task checkpoints
- * @property {string} startedAt - ISO timestamp
- * @property {string|null} lastCheckpoint - ISO timestamp of last checkpoint
- * @property {string|null} completedAt - ISO timestamp of completion
- * @property {number} totalAttempts - Total execution attempts across all tasks
- */
-
-const BUILD_STATE_FILE = '.chati/build-state.json';
-
-// ---------------------------------------------------------------------------
-// State Management
-// ---------------------------------------------------------------------------
-
-/**
- * Initialize a new build state.
- *
- * @param {string[]} taskIds - Array of task IDs to execute
- * @returns {BuildState}
- */
-export function createBuildState(taskIds) {
-  return {
-    sessionId: `build-${Date.now()}`,
-    status: BuildStatus.PENDING,
-    checkpoints: taskIds.map((taskId) => ({
-      taskId,
-      status: CheckpointStatus.PENDING,
-      attempts: 0,
-      firstAttempt: null,
-      lastAttempt: null,
-      output: null,
-      error: null,
-    })),
-    startedAt: new Date().toISOString(),
-    lastCheckpoint: null,
-    completedAt: null,
-    totalAttempts: 0,
-  };
-}
-
-/**
- * Load build state from disk.
- *
- * @param {string} projectDir
- * @returns {BuildState|null}
- */
-export function loadBuildState(projectDir) {
-  const statePath = join(projectDir, BUILD_STATE_FILE);
-  if (!existsSync(statePath)) return null;
-  try {
-    const state = JSON.parse(readFileSync(statePath, 'utf-8'));
-
-    // Check for abandoned builds
-    if (state.status === BuildStatus.IN_PROGRESS && state.lastCheckpoint) {
-      const elapsed = Date.now() - new Date(state.lastCheckpoint).getTime();
-      if (elapsed > ABANDONED_THRESHOLD_MS) {
-        state.status = BuildStatus.ABANDONED;
-      }
-    }
-
-    return state;
-  } catch { /* expected: operation may fail gracefully */
-    return null;
-  }
-}
-
-/**
- * Save build state to disk.
- *
- * @param {string} projectDir
- * @param {BuildState} state
- */
-export function saveBuildState(projectDir, state) {
-  const statePath = join(projectDir, BUILD_STATE_FILE);
-  mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, JSON.stringify(state, null, 2));
-}
-
-/**
- * Update a task checkpoint.
- *
- * @param {BuildState} state
- * @param {string} taskId
- * @param {Partial<TaskCheckpoint>} update
- * @returns {BuildState}
- */
-export function updateCheckpoint(state, taskId, update) {
-  const checkpoint = state.checkpoints.find((c) => c.taskId === taskId);
-  if (!checkpoint) {
-    throw new Error(`Task "${taskId}" not found in build state`);
-  }
-
-  // Set firstAttempt on the first execution attempt
-  if (update.attempts !== undefined && update.attempts > 0 && !checkpoint.firstAttempt) {
-    checkpoint.firstAttempt = new Date().toISOString();
-  }
-
-  Object.assign(checkpoint, update);
-  state.lastCheckpoint = new Date().toISOString();
-
-  if (update.attempts !== undefined) {
-    state.totalAttempts = state.checkpoints.reduce((sum, c) => sum + c.attempts, 0);
-  }
-
-  return state;
-}
-
-/**
- * Mark the build as started.
- *
- * @param {BuildState} state
- * @returns {BuildState}
- */
-export function startBuild(state) {
-  state.status = BuildStatus.IN_PROGRESS;
-  state.startedAt = new Date().toISOString();
-  return state;
-}
-
-/**
- * Mark the build as completed.
- *
- * @param {BuildState} state
- * @returns {BuildState}
- */
-export function completeBuild(state) {
-  state.status = BuildStatus.COMPLETED;
-  state.completedAt = new Date().toISOString();
-  return state;
-}
-
-/**
- * Mark the build as failed.
- *
- * @param {BuildState} state
- * @param {string} [reason]
- * @returns {BuildState}
- */
-export function failBuild(state, _reason) {
-  state.status = BuildStatus.FAILED;
-  state.completedAt = new Date().toISOString();
-  return state;
-}
-
-/**
- * Get the next pending task checkpoint.
- *
- * @param {BuildState} state
- * @returns {TaskCheckpoint|null}
- */
-export function getNextPendingTask(state) {
-  return state.checkpoints.find(
-    (c) => c.status === CheckpointStatus.PENDING || c.status === CheckpointStatus.IN_PROGRESS,
-  ) || null;
-}
-
-/**
- * Check if a task has exceeded max iterations or max time.
- *
- * Dual check: exhausted if attempts >= MAX_ITERATIONS_PER_TASK
- * OR if elapsed time since first attempt >= MAX_TIME_PER_TASK_MS.
- *
- * @param {TaskCheckpoint} checkpoint
- * @returns {boolean}
- */
-export function isTaskExhausted(checkpoint) {
-  if (checkpoint.attempts >= MAX_ITERATIONS_PER_TASK) return true;
-  if (checkpoint.firstAttempt) {
-    const elapsed = Date.now() - new Date(checkpoint.firstAttempt).getTime();
-    if (elapsed >= MAX_TIME_PER_TASK_MS) return true;
-  }
-  return false;
-}
-
-/**
- * Check if the global timeout has been exceeded.
- *
- * @param {BuildState} state
- * @returns {boolean}
- */
-export function isTimedOut(state) {
-  const elapsed = Date.now() - new Date(state.startedAt).getTime();
-  return elapsed > GLOBAL_TIMEOUT_MS;
-}
-
-/**
- * Get build progress summary.
- *
- * @param {BuildState} state
- * @returns {{ total: number, completed: number, failed: number, pending: number, progress: number }}
- */
-export function getProgress(state) {
-  const total = state.checkpoints.length;
-  const completed = state.checkpoints.filter((c) => c.status === CheckpointStatus.COMPLETED).length;
-  const failed = state.checkpoints.filter((c) => c.status === CheckpointStatus.FAILED).length;
-  const pending = state.checkpoints.filter(
-    (c) => c.status === CheckpointStatus.PENDING || c.status === CheckpointStatus.IN_PROGRESS,
-  ).length;
-  const progress = total > 0 ? Math.round((completed / total) * 100) : 0;
-
-  return { total, completed, failed, pending, progress };
-}
-
-/**
- * Clear build state (after completion or manual reset).
- *
- * @param {string} projectDir
- */
-export function clearBuildState(projectDir) {
-  const statePath = join(projectDir, BUILD_STATE_FILE);
-  if (existsSync(statePath)) {
-    unlinkSync(statePath);
-  }
-}

package/src/autonomy/cause-analyzer.js

@@ -1,177 +0,0 @@
-/**
- * @fileoverview Cause analysis for failed build loop tasks.
- *
- * Analyzes agent output to classify failure categories, detect
- * repetitive patterns, and generate retry guidance.
- *
- * Constitution Article XVII — Execution Mode Governance.
- */
-
-// ---------------------------------------------------------------------------
-// Failure Categories
-// ---------------------------------------------------------------------------
-
-/**
- * Categories of task failures.
- * @enum {string}
- */
-export const FAILURE_CATEGORIES = {
-  SYNTAX_ERROR: 'syntax_error',
-  TEST_FAILURE: 'test_failure',
-  LINT_VIOLATION: 'lint_violation',
-  TYPE_ERROR: 'type_error',
-  TIMEOUT: 'timeout',
-  SCOPE_VIOLATION: 'scope_violation',
-  DEPENDENCY: 'dependency',
-  RUNTIME_ERROR: 'runtime_error',
-  UNKNOWN: 'unknown',
-};
-
-/**
- * Patterns for classifying failure output.
- */
-const CATEGORY_PATTERNS = [
-  { regex: /SyntaxError|Unexpected token|parsing error|unterminated/i, category: FAILURE_CATEGORIES.SYNTAX_ERROR },
-  { regex: /test.*fail|assertion.*fail|expect.*receive|expected.*but got/i, category: FAILURE_CATEGORIES.TEST_FAILURE },
-  { regex: /lint.*error|eslint|prettier.*error|formatting/i, category: FAILURE_CATEGORIES.LINT_VIOLATION },
-  { regex: /TypeError|type.*mismatch|cannot read propert|is not a function/i, category: FAILURE_CATEGORIES.TYPE_ERROR },
-  { regex: /timeout|ETIMEDOUT|exceeded.*time|timed out/i, category: FAILURE_CATEGORIES.TIMEOUT },
-  { regex: /scope.*violation|cannot write|not allowed.*mode|Article XI/i, category: FAILURE_CATEGORIES.SCOPE_VIOLATION },
-  { regex: /Cannot find module|ENOENT|module not found|import.*failed|missing dependency/i, category: FAILURE_CATEGORIES.DEPENDENCY },
-  { regex: /ReferenceError|RangeError|Error:|runtime error|ENOMEM/i, category: FAILURE_CATEGORIES.RUNTIME_ERROR },
-];
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Analyze the cause of a task failure.
- *
- * @param {string} output - Agent output/error text
- * @param {Array<{category: string, output: string}>} [previousAttempts=[]] - History of prior attempts
- * @returns {{ category: string, rootCause: string, suggestion: string, isRepetitive: boolean }}
- */
-export function analyzeCause(output, previousAttempts = []) {
-  const text = output || '';
-  const category = classifyOutput(text);
-  const rootCause = extractRootCause(text, category);
-  const suggestion = generateSuggestion(category, rootCause);
-  const isRepetitive = checkRepetitive(category, previousAttempts);
-
-  return { category, rootCause, suggestion, isRepetitive };
-}
-
-/**
- * Build retry guidance for the next attempt based on cause analysis.
- *
- * @param {{ category: string, rootCause: string, suggestion: string, isRepetitive: boolean }} analysis
- * @param {number} attempt - Current attempt number
- * @returns {string} Guidance text for the agent
- */
-export function buildRetryGuidance(analysis, attempt) {
-  const parts = [];
-
-  parts.push(`## Retry Guidance (Attempt ${attempt})`);
-  parts.push('');
-  parts.push(`**Previous failure**: ${analysis.category}`);
-
-  if (analysis.rootCause) {
-    parts.push(`**Root cause**: ${analysis.rootCause}`);
-  }
-
-  parts.push(`**Suggestion**: ${analysis.suggestion}`);
-
-  if (analysis.isRepetitive) {
-    parts.push('');
-    parts.push('**WARNING**: This is a REPETITIVE failure. The same category of error occurred in previous attempts.');
-    parts.push('You MUST try a fundamentally different approach — do not repeat the same fix.');
-  }
-
-  return parts.join('\n');
-}
-
-// ---------------------------------------------------------------------------
-// Internal Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Classify output text into a failure category.
- *
- * @param {string} text
- * @returns {string}
- */
-function classifyOutput(text) {
-  for (const { regex, category } of CATEGORY_PATTERNS) {
-    if (regex.test(text)) {
-      return category;
-    }
-  }
-  return FAILURE_CATEGORIES.UNKNOWN;
-}
-
-/**
- * Extract a concise root cause from the output.
- *
- * @param {string} text
- * @param {string} category
- * @returns {string}
- */
-function extractRootCause(text, category) {
-  if (!text) return 'No output available';
-
-  // Try to find the most informative error line
-  const lines = text.split('\n').filter(l => l.trim());
-
-  // Look for lines containing "Error:" or similar markers
-  const errorLine = lines.find(l =>
-    /error:|Error:|ERR!|FAIL|failed/i.test(l)
-  );
-
-  if (errorLine) {
-    return errorLine.trim().slice(0, 200);
-  }
-
-  // Fall back to last non-empty line (often the summary)
-  if (lines.length > 0) {
-    return lines[lines.length - 1].trim().slice(0, 200);
-  }
-
-  return `${category} detected (no specific error line found)`;
-}
-
-/**
- * Generate a suggestion based on the failure category.
- *
- * @param {string} category
- * @param {string} rootCause
- * @returns {string}
- */
-function generateSuggestion(category, _rootCause) {
-  const suggestions = {
-    [FAILURE_CATEGORIES.SYNTAX_ERROR]: 'Check for missing brackets, semicolons, or malformed expressions. Review the exact line mentioned in the error.',
-    [FAILURE_CATEGORIES.TEST_FAILURE]: 'Review the failing test assertions. Ensure the implementation matches the expected behavior described in the test.',
-    [FAILURE_CATEGORIES.LINT_VIOLATION]: 'Fix formatting and style issues. Check import ordering, unused variables, and indentation.',
-    [FAILURE_CATEGORIES.TYPE_ERROR]: 'Verify that variable types match expected types. Check for null/undefined access and incorrect function signatures.',
-    [FAILURE_CATEGORIES.TIMEOUT]: 'The operation took too long. Consider optimizing the approach or breaking the task into smaller pieces.',
-    [FAILURE_CATEGORIES.SCOPE_VIOLATION]: 'The write operation is outside the allowed scope for the current mode. Only modify files within the permitted directories.',
-    [FAILURE_CATEGORIES.DEPENDENCY]: 'A required module or dependency is missing. Ensure all imports reference existing files and packages are installed.',
-    [FAILURE_CATEGORIES.RUNTIME_ERROR]: 'A runtime error occurred during execution. Check for logic errors, invalid operations, and edge cases.',
-    [FAILURE_CATEGORIES.UNKNOWN]: 'Review the full output to identify the issue. The error does not match known patterns.',
-  };
-
-  return suggestions[category] || suggestions[FAILURE_CATEGORIES.UNKNOWN];
-}
-
-/**
- * Check if the same failure category appeared in previous attempts.
- *
- * @param {string} category
- * @param {Array<{category: string}>} previousAttempts
- * @returns {boolean}
- */
-function checkRepetitive(category, previousAttempts) {
-  if (category === FAILURE_CATEGORIES.UNKNOWN) return false;
-  const sameCategory = previousAttempts.filter(a => a.category === category);
-  return sameCategory.length >= 2;
-}

package/src/autonomy/escalation.js

@@ -1,214 +0,0 @@
-/**
- * @fileoverview Progressive escalation for build loop retries.
- *
- * When a task fails repeatedly, escalation progressively increases
- * the resources (model tier, context enrichment) and ultimately
- * pauses for human intervention.
- *
- * Constitution Article XVII — Execution Mode Governance.
- */
-
-// ---------------------------------------------------------------------------
-// Escalation Levels
-// ---------------------------------------------------------------------------
-
-/**
- * Escalation level definitions.
- * @enum {number}
- */
-export const ESCALATION_LEVELS = {
-  /** Standard — use configured model, no extra context. */
-  STANDARD: 0,
-  /** Enriched — same model, inject cause analysis + retry guidance. */
-  ENRICHED: 1,
-  /** Upgraded — escalate to higher-tier model (e.g. sonnet → opus). */
-  UPGRADED: 2,
-  /** Max — pause execution and request human intervention. */
-  MAX: 3,
-};
-
-/**
- * Model upgrade map — maps current model tier to the next tier.
- * Keys are logical tier names used in chati config.
- */
-const MODEL_UPGRADE_MAP = {
-  haiku: 'sonnet',
-  sonnet: 'opus',
-  opus: 'opus', // opus is ceiling
-  // Gemini equivalents
-  flash: 'pro',
-  pro: 'pro',
-  // Codex equivalents
-  codex: 'codex',
-};
-
-/**
- * Thresholds for automatic escalation.
- */
-const ESCALATION_THRESHOLDS = {
-  /** Attempts before escalating from STANDARD to ENRICHED. */
-  ENRICHED_AFTER: 2,
-  /** Attempts before escalating from ENRICHED to UPGRADED. */
-  UPGRADED_AFTER: 4,
-  /** Attempts before escalating from UPGRADED to MAX. */
-  MAX_AFTER: 7,
-};
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Get the current escalation level for a task checkpoint.
- *
- * @param {{ attempts: number, escalationLevel?: number }} checkpoint
- * @returns {number} Current escalation level (0-3)
- */
-export function getEscalationLevel(checkpoint) {
-  if (!checkpoint) return ESCALATION_LEVELS.STANDARD;
-
-  // Explicit level takes precedence (set by previous escalation)
-  if (typeof checkpoint.escalationLevel === 'number') {
-    return checkpoint.escalationLevel;
-  }
-
-  // Derive from attempt count
-  const attempts = checkpoint.attempts || 0;
-
-  if (attempts >= ESCALATION_THRESHOLDS.MAX_AFTER) {
-    return ESCALATION_LEVELS.MAX;
-  }
-  if (attempts >= ESCALATION_THRESHOLDS.UPGRADED_AFTER) {
-    return ESCALATION_LEVELS.UPGRADED;
-  }
-  if (attempts >= ESCALATION_THRESHOLDS.ENRICHED_AFTER) {
-    return ESCALATION_LEVELS.ENRICHED;
-  }
-
-  return ESCALATION_LEVELS.STANDARD;
-}
-
-/**
- * Determine whether escalation should occur based on checkpoint
- * state and cause analysis.
- *
- * @param {{ attempts: number, escalationLevel?: number }} checkpoint
- * @param {{ isRepetitive: boolean, category: string }} analysis - Cause analysis result
- * @returns {{ escalate: boolean, newLevel: number, reason: string }}
- */
-export function shouldEscalate(checkpoint, analysis) {
-  const currentLevel = getEscalationLevel(checkpoint);
-  const attempts = checkpoint?.attempts || 0;
-
-  // Already at max — no further escalation
-  if (currentLevel >= ESCALATION_LEVELS.MAX) {
-    return {
-      escalate: false,
-      newLevel: ESCALATION_LEVELS.MAX,
-      reason: 'Already at maximum escalation level',
-    };
-  }
-
-  // Repetitive failures trigger immediate escalation (+1 level)
-  if (analysis?.isRepetitive) {
-    const newLevel = Math.min(currentLevel + 1, ESCALATION_LEVELS.MAX);
-    return {
-      escalate: true,
-      newLevel,
-      reason: `Repetitive ${analysis.category} failure — escalating to level ${newLevel}`,
-    };
-  }
-
-  // Threshold-based escalation
-  let targetLevel = ESCALATION_LEVELS.STANDARD;
-  if (attempts >= ESCALATION_THRESHOLDS.MAX_AFTER) {
-    targetLevel = ESCALATION_LEVELS.MAX;
-  } else if (attempts >= ESCALATION_THRESHOLDS.UPGRADED_AFTER) {
-    targetLevel = ESCALATION_LEVELS.UPGRADED;
-  } else if (attempts >= ESCALATION_THRESHOLDS.ENRICHED_AFTER) {
-    targetLevel = ESCALATION_LEVELS.ENRICHED;
-  }
-
-  if (targetLevel > currentLevel) {
-    return {
-      escalate: true,
-      newLevel: targetLevel,
-      reason: `Attempt ${attempts} reached threshold for level ${targetLevel}`,
-    };
-  }
-
-  return {
-    escalate: false,
-    newLevel: currentLevel,
-    reason: 'No escalation needed',
-  };
-}
-
-/**
- * Get configuration for a given escalation level.
- *
- * @param {number} level - Escalation level (0-3)
- * @param {string} [currentModel='sonnet'] - Current model tier name
- * @returns {{ model: string|null, contextBoost: boolean, shouldPause: boolean, description: string }}
- */
-export function getEscalationConfig(level, currentModel = 'sonnet') {
-  switch (level) {
-    case ESCALATION_LEVELS.STANDARD:
-      return {
-        model: null, // no override
-        contextBoost: false,
-        shouldPause: false,
-        description: 'Standard execution — no escalation',
-      };
-
-    case ESCALATION_LEVELS.ENRICHED:
-      return {
-        model: null, // same model
-        contextBoost: true,
-        shouldPause: false,
-        description: 'Enriched context — cause analysis + retry guidance injected',
-      };
-
-    case ESCALATION_LEVELS.UPGRADED:
-      return {
-        model: MODEL_UPGRADE_MAP[currentModel] || currentModel,
-        contextBoost: true,
-        shouldPause: false,
-        description: `Model upgraded from ${currentModel} to ${MODEL_UPGRADE_MAP[currentModel] || currentModel}`,
-      };
-
-    case ESCALATION_LEVELS.MAX:
-      return {
-        model: MODEL_UPGRADE_MAP[currentModel] || currentModel,
-        contextBoost: true,
-        shouldPause: true,
-        description: 'Maximum escalation — pausing for human intervention',
-      };
-
-    default:
-      return {
-        model: null,
-        contextBoost: false,
-        shouldPause: false,
-        description: `Unknown escalation level: ${level}`,
-      };
-  }
-}
-
-/**
- * Build a human-readable escalation summary.
- *
- * @param {number} level - Escalation level
- * @param {string} reason - Escalation reason
- * @returns {string}
- */
-export function buildEscalationSummary(level, reason) {
-  const levelNames = ['STANDARD', 'ENRICHED', 'UPGRADED', 'MAX'];
-  const name = levelNames[level] || 'UNKNOWN';
-  return `[Escalation ${name}] ${reason}`;
-}
-
-/**
- * Exported for testing — escalation thresholds.
- */
-export { ESCALATION_THRESHOLDS };