Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

4.8 KB
Raw Blame
/**
 * Agent TUI finalize helpers
 *
 * Failure-analysis + worktree-inspection support for spawnTuiAgent's finalize
 * path. All side-effect-narrow and non-throwing: a failure to read the raw
 * spool, inspect the worktree, or capture a diff must never abort finish()
 * before finalizeAgent runs. Extracted from spawnTuiAgent so the "read the
 * spool tail → analyze the failure" concern is self-contained and testable.
 */

import { join } from 'path';
import { writeFile } from 'fs/promises';
import * as git from '../git.js';
import { readFileTail } from '../../lib/fileUtils.js';
import { commitsSince } from '../../lib/gitCommitProbe.js';
import { analyzeAgentFailure } from '../agentErrorAnalysis.js';

// Re-exported so this module's existing importers (and its tests) keep their
// entry point after the implementation moved to lib/fileUtils.js (#3498) —
// `getAgent`'s transcript cap needed the same bounded tail read.
export { readFileTail };

// Same deal for the run-window commit probe: it moved to lib/gitCommitProbe.js
// (#3637) once finalize's success-criteria evaluation, run completion, and
// orphan recovery all needed the same answer, but this stays its historical
// entry point.
export { commitsSince };

// Tail-read window for raw.txt at failure analysis. analyzeAgentFailure narrows
// further (ANSI-stripped, last ~200 lines AND ≤16K chars), so reading the whole
// file (which has no upper bound for long-running agents) would reintroduce the
// OOM risk the disk spool was meant to avoid. 1MB comfortably covers the
// analyzer's window on any realistic PTY stream — including a repaint-heavy TUI
// transcript, where escape sequences dominate the byte count — while keeping
// peak finalize memory bounded.
export const RAW_TAIL_ANALYSIS_BYTES = 1024 * 1024;

/**
 * Capture the git diff (staged + unstaged) from a worktree and save it to the
 * agent archive dir. Called before worktree cleanup so post-mortems can see
 * what changes existed even if the worktree is deleted. Non-throwing — a
 * failure to capture shouldn't block finalize.
 *
 * @returns {string|null} The captured diff, or null if none/error.
 */
export async function captureWorktreeDiff(workspacePath, agentDir) {
  if (!workspacePath || typeof workspacePath !== 'string') return null;
  if (!agentDir || typeof agentDir !== 'string') return null;
  const [staged, unstaged] = await Promise.all([
    git.getDiff(workspacePath, true).catch(() => ''),
    git.getDiff(workspacePath, false).catch(() => ''),
  ]);
  const combined = [
    staged ? `### STAGED CHANGES ###\n${staged}` : '',
    unstaged ? `### UNSTAGED CHANGES ###\n${unstaged}` : '',
  ].filter(Boolean).join('\n\n');
  if (!combined.trim()) return null;
  const diffFile = join(agentDir, 'worktree-diff.txt');
  await writeFile(diffFile, combined).catch((err) => {
    console.error(`❌ Failed to capture worktree diff for agent: ${err.message}`);
  });
  return combined;
}

/**
 * Resolve the error-analysis payload for a finalizing agent. Successful runs
 * skip the raw-spool read entirely (that's what keeps the disk-spool's
 * bounded-memory guarantee for healthy long runs); failures read only the
 * tail of raw.txt and hand it to analyzeAgentFailure.
 *
 * `??` (not `||`) so an empty raw spool ('') stays distinguishable from a read
 * failure (null) — readFileTail's contract. A zero-byte raw.txt lets analysis
 * run against ''; both a missing file AND a read error return null and fall
 * back to `fallbackText` (the capped output buffer, which has the spawn-startup
 * notices). An immediate-fallback signal, if one was detected mid-stream,
 * short-circuits the analysis entirely.
 *
 * `completionReason` / `completionError` carry the finalize path's OWN verdict
 * (legacy forced-stop reason or spawn failure). The analyzer prefers that
 * structural signal over a loose keyword match in the transcript — a
 * repaint-driven PTY transcript is a whole session's worth of text, and any
 * keyword in it (including ones the agent itself typed) would otherwise
 * classify the failure.
 *
 * @returns {Promise<object|null>} The error-analysis object, or null on success.
 */
export async function resolveErrorAnalysis({ finalSuccess, rawFile, fallbackText, task, model, immediateFallbackAnalysis, completionReason, completionError }) {
  if (immediateFallbackAnalysis?.category === 'content-refusal') return immediateFallbackAnalysis;
  if (finalSuccess) return null;
  // Short-circuit BEFORE the tail read: a mid-stream fallback signal already is
  // the verdict, so reading ~16KB of spool only to discard it is pure waste.
  if (immediateFallbackAnalysis) return immediateFallbackAnalysis;
  const rawAnalysisText = await readFileTail(rawFile, RAW_TAIL_ANALYSIS_BYTES);
  return analyzeAgentFailure(rawAnalysisText ?? fallbackText, task, model, { completionReason, completionError });
}