@claudemini/ses-cli 1.4.3

package/lib/agent-review.js

@@ -0,0 +1,722 @@
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { basename, join, resolve, sep } from 'path';
+import {
+  Agent,
+  BaseTool,
+  ToolRegistry,
+  createModel,
+  createOpenAIAdapter,
+  createAnthropicAdapter,
+  textContent,
+} from 'goatchain';
+import { getApiConfig } from './summarize.js';
+import {
+  loadJsonIfExists,
+  normalizeEvidence as normalizeEvidenceList,
+  normalizeLocation,
+} from './review-common.js';
+import { REVIEW_AGENT_SYSTEM_PROMPT, buildReviewUserMessage } from './prompts.js';
+
+const MAX_OUTPUT_BYTES = 50 * 1024;
+const MAX_ITERATIONS = 30;
+const BASE_TIMEOUT_MS = 60000;
+const PER_SESSION_TIMEOUT_MS = 30000;
+const DEFAULT_IDLE_TIMEOUT_MS = 30000;
+const MIN_AGENT_TIMEOUT_MS = 1000;
+const BLOCKED_BASENAMES = new Set([
+  '.env',
+  '.env.local',
+  '.env.development',
+  '.env.production',
+  '.env.test',
+  '.npmrc',
+  '.pypirc',
+  '.git-credentials',
+  'id_rsa',
+  'id_ed25519',
+]);
+const BLOCKED_SUFFIXES = ['.pem', '.key', '.p12', '.pfx'];
+
+const VALID_CATEGORY = new Set([
+  'testing',
+  'correctness',
+  'reliability',
+  'maintainability',
+  'security',
+  'performance',
+]);
+
+const VALID_SEVERITY = new Set(['info', 'low', 'medium', 'high', 'critical']);
+const VALID_CONFIDENCE = new Set(['low', 'medium', 'high']);
+
+function truncateText(text, maxBytes = MAX_OUTPUT_BYTES) {
+  const input = String(text || '');
+  if (Buffer.byteLength(input, 'utf8') <= maxBytes) {
+    return input;
+  }
+
+  const suffix = '\n...[truncated]';
+  const bodyBytes = Math.max(0, maxBytes - Buffer.byteLength(suffix, 'utf8'));
+  const body = Buffer.from(input, 'utf8').subarray(0, bodyBytes).toString('utf8');
+  return `${body}${suffix}`;
+}
+
+function runGit(projectRoot, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 12000,
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function getLinkedCommits(state) {
+  const checkpoints = Array.isArray(state?.checkpoints) ? state.checkpoints : [];
+  const commits = [];
+  for (const checkpoint of checkpoints) {
+    const commit = String(checkpoint?.linked_commit || '').trim().toLowerCase();
+    if (/^[a-f0-9]{7,40}$/.test(commit)) {
+      commits.push(commit);
+    }
+  }
+  return [...new Set(commits)];
+}
+
+function preloadSessionData(selectedSessions) {
+  const sessionMap = new Map();
+
+  for (const session of selectedSessions) {
+    const summaryPath = join(session.dir, 'summary.json');
+    const statePath = join(session.dir, 'state.json');
+    const metadataPath = join(session.dir, 'metadata.json');
+
+    const summary = loadJsonIfExists(summaryPath);
+    const state = loadJsonIfExists(statePath, {});
+    const metadata = loadJsonIfExists(metadataPath, {});
+    const linkedCommits = getLinkedCommits(state);
+
+    sessionMap.set(session.id, {
+      id: session.id,
+      dir: session.dir,
+      summaryPath,
+      statePath,
+      metadataPath,
+      summary,
+      state,
+      metadata,
+      linkedCommits,
+    });
+  }
+
+  return sessionMap;
+}
+
+function pickSession(sessionMap, requestedSessionId) {
+  if (requestedSessionId) {
+    const match = sessionMap.get(String(requestedSessionId));
+    if (!match) {
+      throw new Error(`Unknown session_id: ${requestedSessionId}`);
+    }
+    return match;
+  }
+
+  const first = sessionMap.values().next();
+  if (first.done) {
+    throw new Error('No session loaded for review.');
+  }
+  return first.value;
+}
+
+function buildSessionDiff(projectRoot, sessionData, options = {}) {
+  const commits = sessionData.linkedCommits;
+
+  if (commits.length >= 2) {
+    const from = commits[commits.length - 2];
+    const to = commits[commits.length - 1];
+    const diff = runGit(projectRoot, ['diff', '--unified=3', `${from}..${to}`]);
+    if (diff) {
+      return {
+        strategy: 'checkpoint_range',
+        reference: `${from}..${to}`,
+        diff,
+      };
+    }
+  }
+
+  if (commits.length >= 1) {
+    const latest = commits[commits.length - 1];
+    const diff = runGit(projectRoot, ['show', '--format=', '--unified=3', latest]);
+    if (diff) {
+      return {
+        strategy: 'checkpoint_show',
+        reference: latest,
+        diff,
+      };
+    }
+  }
+
+  const changedFiles = Array.isArray(sessionData.summary?.changes?.files)
+    ? sessionData.summary.changes.files
+      .map(file => String(file.path || '').trim())
+      .filter(Boolean)
+      .slice(0, 40)
+    : [];
+
+  if (changedFiles.length > 0 && options.allowWorktreeDiff) {
+    const diff = runGit(projectRoot, ['diff', '--unified=3', '--', ...changedFiles]);
+    if (diff) {
+      return {
+        strategy: 'worktree_files',
+        reference: changedFiles,
+        diff,
+      };
+    }
+  }
+
+  if (changedFiles.length > 0) {
+    return {
+      strategy: 'summary_files_only',
+      reference: changedFiles,
+      diff: '',
+    };
+  }
+
+  return {
+    strategy: 'none',
+    reference: null,
+    diff: '',
+  };
+}
+
+function isSensitivePath(inputPath) {
+  const normalized = String(inputPath || '').replace(/\\/g, '/').toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+  if (normalized.includes('/.git/') || normalized.startsWith('.git/')) {
+    return true;
+  }
+
+  const file = basename(normalized);
+  if (BLOCKED_BASENAMES.has(file)) {
+    return true;
+  }
+
+  return BLOCKED_SUFFIXES.some(suffix => file.endsWith(suffix));
+}
+
+function resolveProjectFile(projectRoot, inputPath) {
+  const root = resolve(projectRoot);
+  const target = resolve(projectRoot, String(inputPath || ''));
+  if (target !== root && !target.startsWith(`${root}${sep}`)) {
+    throw new Error('Path escapes project root.');
+  }
+  return target;
+}
+
+class ReadSessionSummaryTool extends BaseTool {
+  name = 'read_session_summary';
+  description = 'Read summary.json, state.json, and metadata.json for a selected session.';
+  parameters = {
+    type: 'object',
+    properties: {
+      session_id: {
+        type: 'string',
+        description: 'Optional session id. Defaults to the first selected session.',
+      },
+    },
+    additionalProperties: false,
+  };
+  riskLevel = 'safe';
+
+  constructor(sessionMap) {
+    super();
+    this.sessionMap = sessionMap;
+  }
+
+  async execute(args) {
+    const session = pickSession(this.sessionMap, args?.session_id);
+    const payload = {
+      session_id: session.id,
+      source: {
+        summary_file: session.summaryPath,
+        state_file: session.statePath,
+        metadata_file: session.metadataPath,
+      },
+      summary: session.summary,
+      state: session.state,
+      metadata: session.metadata,
+    };
+    return textContent(truncateText(JSON.stringify(payload, null, 2)));
+  }
+}
+
+class ReadGitDiffTool extends BaseTool {
+  name = 'read_git_diff';
+  description = 'Read git diff for a selected session. Prefer checkpoint commit range when available.';
+  parameters = {
+    type: 'object',
+    properties: {
+      session_id: {
+        type: 'string',
+        description: 'Optional session id. Defaults to the first selected session.',
+      },
+    },
+    additionalProperties: false,
+  };
+  riskLevel = 'safe';
+
+  constructor(projectRoot, sessionMap, options) {
+    super();
+    this.projectRoot = projectRoot;
+    this.sessionMap = sessionMap;
+    this.options = options;
+  }
+
+  async execute(args) {
+    const session = pickSession(this.sessionMap, args?.session_id);
+    const diffData = buildSessionDiff(this.projectRoot, session, this.options);
+
+    const payload = [
+      `session_id=${session.id}`,
+      `strategy=${diffData.strategy}`,
+      `reference=${JSON.stringify(diffData.reference)}`,
+      '',
+      diffData.diff || 'No diff available for this session.',
+    ].join('\n');
+
+    return textContent(truncateText(payload));
+  }
+}
+
+class ReadSourceFileTool extends BaseTool {
+  name = 'read_source_file';
+  description = 'Read a source file under project root with optional line range.';
+  parameters = {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path relative to project root.' },
+      start_line: { type: 'integer', minimum: 1 },
+      end_line: { type: 'integer', minimum: 1 },
+    },
+    required: ['path'],
+    additionalProperties: false,
+  };
+  riskLevel = 'safe';
+
+  constructor(projectRoot) {
+    super();
+    this.projectRoot = projectRoot;
+  }
+
+  async execute(args) {
+    if (isSensitivePath(args?.path)) {
+      throw new Error(`Access denied for sensitive path: ${args?.path}`);
+    }
+    const target = resolveProjectFile(this.projectRoot, args?.path);
+    if (!existsSync(target) || !statSync(target).isFile()) {
+      throw new Error(`File not found: ${args?.path}`);
+    }
+
+    const content = readFileSync(target, 'utf8');
+    const lines = content.split('\n');
+
+    const parsedStart = Number(args?.start_line);
+    const parsedEnd = Number(args?.end_line);
+    const startLine = Number.isFinite(parsedStart) ? Math.max(1, Math.floor(parsedStart)) : 1;
+    const endLine = Number.isFinite(parsedEnd)
+      ? Math.max(startLine, Math.floor(parsedEnd))
+      : lines.length;
+
+    const slice = lines.slice(startLine - 1, endLine);
+    const numbered = slice.map((line, index) => `${startLine + index}\t${line}`).join('\n');
+
+    const payload = [
+      `file=${target}`,
+      `line_range=${startLine}-${endLine}`,
+      '',
+      numbered,
+    ].join('\n');
+
+    return textContent(truncateText(payload));
+  }
+}
+
+class SubmitFindingsTool extends BaseTool {
+  name = 'submit_findings';
+  description = 'Submit structured findings. This is the final output channel for review results.';
+  parameters = {
+    type: 'object',
+    properties: {
+      findings: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            rule_id: { type: 'string' },
+            category: { type: 'string' },
+            severity: { type: 'string' },
+            confidence: { type: 'string' },
+            summary: { type: 'string' },
+            details: { type: 'string' },
+            suggestion: { type: 'string' },
+            evidence: {
+              type: 'array',
+              items: { type: 'string' },
+            },
+            location: {
+              type: 'object',
+              properties: {
+                file: { type: 'string' },
+                line: { type: 'integer' },
+                column: { type: 'integer' },
+              },
+              additionalProperties: true,
+            },
+            sessions: {
+              type: 'array',
+              items: { type: 'string' },
+            },
+          },
+          additionalProperties: true,
+        },
+      },
+    },
+    required: ['findings'],
+    additionalProperties: false,
+  };
+  riskLevel = 'safe';
+
+  constructor(resultHolder) {
+    super();
+    this.resultHolder = resultHolder;
+  }
+
+  async execute(args) {
+    let findings = args?.findings;
+
+    if (typeof findings === 'string') {
+      try {
+        findings = JSON.parse(findings);
+      } catch {
+        findings = [];
+      }
+    }
+
+    this.resultHolder.findings = Array.isArray(findings) ? findings : [];
+    this.resultHolder.submitted = true;
+    return textContent(`received_findings=${this.resultHolder.findings.length}`);
+  }
+}
+
+function normalizeEvidenceWithFallback(evidence, fallbackSessionId) {
+  return normalizeEvidenceList(evidence, { fallbackItems: [`session_id=${fallbackSessionId}`] });
+}
+
+function normalizeSubmittedFindings(rawFindings, sessionIds) {
+  const fallbackSessionId = sessionIds[0] || 'unknown';
+  const allowedSessions = new Set(sessionIds);
+
+  const normalized = (Array.isArray(rawFindings) ? rawFindings : []).map((finding, index) => {
+    const input = finding && typeof finding === 'object' ? finding : {};
+
+    const category = VALID_CATEGORY.has(input.category) ? input.category : 'maintainability';
+    const severity = VALID_SEVERITY.has(input.severity) ? input.severity : 'low';
+    const confidence = VALID_CONFIDENCE.has(input.confidence) ? input.confidence : 'medium';
+    const summary = String(input.summary || '').trim() || `Agent finding #${index + 1}`;
+    const details = String(input.details || '').trim();
+    const suggestion = String(input.suggestion || '').trim();
+
+    const requestedSessions = Array.isArray(input.sessions)
+      ? input.sessions.map(id => String(id || '').trim()).filter(Boolean)
+      : [];
+
+    const sessions = requestedSessions.filter(id => allowedSessions.has(id));
+
+    return {
+      rule_id: String(input.rule_id || 'agent.review.finding').trim(),
+      category,
+      severity,
+      confidence,
+      summary,
+      details,
+      suggestion,
+      evidence: normalizeEvidenceWithFallback(input.evidence, fallbackSessionId),
+      location: normalizeLocation(input.location),
+      sessions: sessions.length > 0 ? [...new Set(sessions)] : [fallbackSessionId],
+    };
+  });
+
+  return normalized;
+}
+
+function extractFindingsFromText(outputText) {
+  const raw = String(outputText || '').trim();
+  if (!raw) {
+    return null;
+  }
+
+  const blockMatch = raw.match(/```json\s*([\s\S]*?)```/i);
+  const candidates = [
+    blockMatch ? blockMatch[1] : '',
+    raw,
+  ].filter(Boolean);
+
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (Array.isArray(parsed)) {
+        return parsed;
+      }
+      if (parsed && Array.isArray(parsed.findings)) {
+        return parsed.findings;
+      }
+    } catch {
+      // Keep trying.
+    }
+  }
+
+  return null;
+}
+
+function resolveAgentTimeoutMs(options, sessionCount = 1) {
+  const optionValue = Number(options?.agentTimeoutMs);
+  if (Number.isFinite(optionValue) && optionValue >= MIN_AGENT_TIMEOUT_MS) {
+    return Math.floor(optionValue);
+  }
+
+  const envValue = Number(process.env.SES_REVIEW_AGENT_TIMEOUT_MS);
+  if (Number.isFinite(envValue) && envValue >= MIN_AGENT_TIMEOUT_MS) {
+    return Math.floor(envValue);
+  }
+
+  return BASE_TIMEOUT_MS + PER_SESSION_TIMEOUT_MS * Math.max(1, sessionCount);
+}
+
+function resolveAutoApprove(options) {
+  if (typeof options?.agentAutoApprove === 'boolean') {
+    return options.agentAutoApprove;
+  }
+
+  const env = String(process.env.SES_REVIEW_AUTO_APPROVE || '').trim().toLowerCase();
+  if (env === '0' || env === 'false' || env === 'no') {
+    return false;
+  }
+  if (env === '1' || env === 'true' || env === 'yes') {
+    return true;
+  }
+  return true;
+}
+
+function createModelFromConfig(projectRoot) {
+  const config = getApiConfig(projectRoot);
+  if (!config.api_key) {
+    throw new Error('No API key configured. Set OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable.');
+  }
+
+  if (config.provider === 'anthropic') {
+    const adapter = createAnthropicAdapter({
+      apiKey: config.api_key,
+      defaultModelId: config.model,
+    });
+    return createModel({ adapter });
+  }
+
+  const adapter = createOpenAIAdapter({
+    apiKey: config.api_key,
+    defaultModelId: config.model || 'gpt-4o-mini',
+    baseUrl: config.openai_endpoint || config.openai_base_url,
+  });
+  return createModel({ adapter });
+}
+
+function logAgentEvent(event) {
+  switch (event.type) {
+    case 'tool_call_start':
+      console.error(`[agent] tool start: ${event.toolName || 'unknown'}`);
+      break;
+    case 'tool_call_end':
+      console.error(`[agent] tool end: ${event.toolCall?.function?.name || 'unknown'}`);
+      break;
+    case 'iteration_end':
+      console.error(`[agent] iteration ${event.iteration} complete`);
+      break;
+    case 'done':
+      console.error('[agent] done');
+      break;
+    default:
+      break;
+  }
+}
+
+export async function runAgentReview(projectRoot, selectedSessions, options) {
+  const sessionMap = preloadSessionData(selectedSessions);
+  const model = createModelFromConfig(projectRoot);
+  const autoApprove = resolveAutoApprove(options);
+  const timeoutMs = resolveAgentTimeoutMs(options, selectedSessions.length);
+  const idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS;
+  const resultHolder = {
+    submitted: false,
+    findings: [],
+  };
+
+  const tools = new ToolRegistry();
+  tools.register(new ReadSessionSummaryTool(sessionMap));
+  tools.register(new ReadGitDiffTool(projectRoot, sessionMap, options));
+  tools.register(new ReadSourceFileTool(projectRoot));
+  tools.register(new SubmitFindingsTool(resultHolder));
+
+  const agent = new Agent({
+    name: 'ses-review-agent',
+    systemPrompt: REVIEW_AGENT_SYSTEM_PROMPT,
+    model,
+    tools,
+  });
+
+  const agentSession = await agent.createSession({
+    maxIterations: MAX_ITERATIONS,
+  });
+
+  const userMessage = buildReviewUserMessage(
+    selectedSessions.map(session => session.id),
+    {
+      ...options,
+      timeoutMs,
+      autoApprove,
+    },
+  );
+  agentSession.send(userMessage, {
+    toolContext: { approval: { autoApprove } },
+  });
+
+  const outputChunks = [];
+  let receiveError = null;
+  const startTime = Date.now();
+
+  let globalHandle;
+  let settleGlobal = () => {};
+  const globalTimeoutPromise = new Promise((resolve, reject) => {
+    settleGlobal = resolve;
+    globalHandle = setTimeout(() => {
+      reject(new Error(`Agent review timed out after ${timeoutMs}ms.`));
+    }, timeoutMs);
+  });
+
+  let idleHandle;
+  const resetIdle = () => {
+    if (idleHandle) clearTimeout(idleHandle);
+  };
+  let settleIdle = () => {};
+  let idleReject;
+  const idlePromise = new Promise((resolve, reject) => {
+    settleIdle = resolve;
+    idleReject = reject;
+  });
+  const startIdle = () => {
+    resetIdle();
+    idleHandle = setTimeout(() => {
+      idleReject(new Error(`Agent idle timeout after ${idleTimeoutMs}ms with no activity.`));
+    }, idleTimeoutMs);
+  };
+  startIdle();
+
+  try {
+    await Promise.race([
+      (async () => {
+        for await (const event of agentSession.receive({
+          toolContext: { approval: { autoApprove } },
+        })) {
+          startIdle();
+          logAgentEvent(event);
+
+          if (event.type === 'text_delta' && event.delta) {
+            outputChunks.push(String(event.delta));
+          }
+
+          if (event.type === 'done') {
+            if (event.finalResponse) {
+              outputChunks.push(String(event.finalResponse));
+            }
+            break;
+          }
+
+          if (resultHolder.submitted) {
+            const elapsed = Date.now() - startTime;
+            console.error(`[agent] findings submitted at ${elapsed}ms, wrapping up.`);
+            break;
+          }
+        }
+      })(),
+      globalTimeoutPromise,
+      idlePromise,
+    ]);
+  } catch (error) {
+    receiveError = error;
+    console.error(`[agent] warning: ${error.message}`);
+    if (typeof agentSession.abort === 'function') {
+      try {
+        await agentSession.abort();
+      } catch {
+        // Best-effort cancellation only.
+      }
+    }
+  } finally {
+    settleGlobal();
+    settleIdle();
+    resetIdle();
+    if (globalHandle) {
+      clearTimeout(globalHandle);
+    }
+    const elapsed = Date.now() - startTime;
+    console.error(`[agent] total elapsed: ${elapsed}ms (limit: ${timeoutMs}ms)`);
+  }
+
+  if (!resultHolder.submitted) {
+    const parsed = extractFindingsFromText(outputChunks.join(''));
+    if (Array.isArray(parsed) && parsed.length > 0) {
+      resultHolder.findings = parsed;
+    }
+  }
+
+  const sessionIds = selectedSessions.map(sessionEntry => sessionEntry.id);
+  const normalized = normalizeSubmittedFindings(resultHolder.findings, sessionIds);
+
+  if (normalized.length === 0) {
+    normalized.push({
+      rule_id: 'agent.no_findings',
+      category: 'maintainability',
+      severity: 'info',
+      confidence: 'low',
+      summary: 'Agent review produced no structured findings',
+      details: receiveError
+        ? `Agent run finished without valid findings after error: ${receiveError.message}`
+        : 'Agent run finished but did not submit parseable findings.',
+      suggestion: 'Re-run review and inspect agent tool logs if this repeats.',
+      evidence: sessionIds.map(id => `session_id=${id}`),
+      location: null,
+      sessions: sessionIds.length > 0 ? sessionIds : ['unknown'],
+    });
+  }
+
+  if (!normalized.some(item => item.severity === 'info')) {
+    normalized.push({
+      rule_id: 'agent.review.summary',
+      category: 'maintainability',
+      severity: 'info',
+      confidence: 'high',
+      summary: `Agent review completed for ${sessionIds.length} session(s)`,
+      details: `Analyzed sessions: ${sessionIds.join(', ')}`,
+      suggestion: 'Review high/medium findings first, then verify remaining low-level observations.',
+      evidence: sessionIds.map(id => `session_id=${id}`),
+      location: null,
+      sessions: sessionIds.length > 0 ? sessionIds : ['unknown'],
+    });
+  }
+
+  return normalized;
+}