@cyanautomation/kaseki-agent 1.4.1

package/src/kaseki-cli-lib.ts

@@ -0,0 +1,760 @@
+#!/usr/bin/env node
+
+/**
+ * kaseki-cli-lib.ts
+ *
+ * Core library for querying and analyzing kaseki instances.
+ * Provides functions for listing instances, reading status, detecting errors,
+ * and performing post-run analysis.
+ *
+ * Usage:
+ *   import { listInstances, getInstanceStatus } from './kaseki-cli-lib';
+ *   const instances = listInstances();
+ *   const status = getInstanceStatus('kaseki-1');
+ */
+
+import fs from 'fs';
+import path from 'path';
+import childProcess from 'child_process';
+import {
+  readInstanceMetadata,
+  Metadata,
+  HostStart,
+} from './instance-metadata-reader';
+import {
+  deriveInstanceLifecycleStatus,
+  resolveInstanceExitCode as importedResolveInstanceExitCode,
+  classifyFailure as importedClassifyFailure,
+  normalizeExitCodeCandidate as importedNormalizeExitCodeCandidate,
+} from './instance-state-derivation';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Config {
+  KASEKI_RESULTS_DIR: string;
+  KASEKI_RUNS_DIR: string;
+}
+
+interface KasekiInstance {
+  name: string;
+  status: 'running' | 'completed' | 'failed' | 'pending';
+  running: boolean;
+  exitCode: number | null;
+  elapsedSeconds: number | null;
+  stage: string;
+  model: string;
+  repo: string;
+  ref: string;
+}
+
+interface InstanceStatus {
+  instance?: string;
+  error?: { kind: string; message: string };
+  status?: 'running' | 'completed' | 'failed' | 'pending';
+  running?: boolean;
+  stage?: string;
+  elapsedSeconds?: number | null;
+  totalDurationSeconds?: number | null;
+  agentElapsedSeconds?: number | null;
+  timeoutSeconds?: number;
+  timeoutRiskPercent?: number;
+  timeoutImminent?: boolean;
+  timedOut?: boolean;
+  exitCode?: number | null;
+  failureClass?: string;
+  repo?: string;
+  ref?: string;
+  model?: string;
+}
+
+interface ProgressEvent {
+  timestamp?: string;
+  stage: string;
+  message: string;
+  malformed?: boolean;
+  [key: string]: any;
+}
+
+interface DetectedError {
+  severity: string;
+  source: string;
+  line: number;
+  message: string;
+}
+
+interface AnalysisResult {
+  instance?: string;
+  error?: { kind: string; message: string };
+  status?: string;
+  exit_code?: number | string;
+  failure_class?: string;
+  failed_command?: string;
+  validation_failed_command?: string;
+  duration_seconds?: number;
+  pi_duration_seconds?: number;
+  model?: string;
+  changed_files_count?: number;
+  changed_files?: string[];
+  tool_executions?: number;
+  errors?: DetectedError[];
+  error_count?: number;
+}
+
+// Configuration object (can be overridden for testing)
+const config: Config = {
+  KASEKI_RESULTS_DIR: process.env.KASEKI_RESULTS_DIR || '/agents/kaseki-results',
+  KASEKI_RUNS_DIR: process.env.KASEKI_RUNS_DIR || '/agents/kaseki-runs',
+};
+
+// For backwards compatibility, also export as constants
+const KASEKI_RESULTS_DIR = config.KASEKI_RESULTS_DIR;
+const KASEKI_RUNS_DIR = config.KASEKI_RUNS_DIR;
+
+// ============================================================================
+// Instance Discovery
+// ============================================================================
+
+/**
+ * Parse docker ps --format '{{.Names}}' output into container name array.
+ */
+function parseDockerContainerNames(dockerNamesOutput: string): string[] {
+  if (!dockerNamesOutput) return [];
+  return dockerNamesOutput
+    .split('\n')
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+}
+
+/**
+ * Exact container-name matcher (test seam).
+ * Ensures "kaseki-1" does NOT match "kaseki-10".
+ */
+function isExactContainerNameMatch(containerName: string, instance: string): boolean {
+  return containerName === instance;
+}
+
+/**
+ * Check whether docker ps names output contains an exact instance match.
+ */
+function dockerNamesOutputHasInstance(dockerNamesOutput: string, instance: string): boolean {
+  const containerNames = parseDockerContainerNames(dockerNamesOutput);
+  return containerNames.some((name) => isExactContainerNameMatch(name, instance));
+}
+
+/**
+ * Determine if an instance is currently running as a Docker container.
+ * Gracefully falls back to false when Docker is unavailable.
+ */
+function isInstanceRunning(instance: string): boolean {
+  try {
+    const dockerNamesOutput = childProcess.execSync('docker ps --format "{{.Names}}" 2>/dev/null || true', {
+      encoding: 'utf8',
+    });
+    return dockerNamesOutputHasInstance(dockerNamesOutput, instance);
+  } catch {
+    // Docker may not be available
+    return false;
+  }
+}
+
+function isSkippableInstanceIoError(error: any): boolean {
+  return error && (error.code === 'ENOENT' || error.code === 'ESTALE');
+}
+
+/**
+ * Normalize an exit code candidate into an integer or null.
+ * (Re-exported from instance-state-derivation for backward compatibility)
+ */
+function normalizeExitCodeCandidate(value: any): number | null {
+  return importedNormalizeExitCodeCandidate(value);
+}
+
+/**
+ * Wrapper around resolveInstanceExitCode from instance-state-derivation.
+ * @deprecated Use the imported resolveInstanceExitCode directly.
+ * Kept for API compatibility; delegates to imported function.
+ */
+function resolveInstanceExitCodeLocal(
+  resultDir: string,
+  metadata: Metadata = {}
+): number | null {
+  return importedResolveInstanceExitCode(resultDir, metadata);
+}
+
+/**
+ * Wrapper around resolveInstanceStage from instance-state-derivation.
+ * Adapts the interface to match existing call sites.
+ * Note: The imported function requires resultsDir, but this wrapper uses the config.
+ */
+function resolveInstanceStageLocal(
+  instance: string,
+  metadata: Metadata = {},
+  fallback: string = 'unknown'
+): string {
+  if (typeof metadata.current_stage === 'string' && metadata.current_stage.trim().length > 0) {
+    return metadata.current_stage;
+  }
+  const parsedStage = getCurrentStage(instance);
+  return parsedStage || fallback;
+}
+
+/**
+ * Wrapper around classifyFailure from instance-state-derivation.
+ * @deprecated Use the imported classifyFailure directly.
+ * Kept for API compatibility; delegates to imported function.
+ */
+function classifyFailureLocal(
+  metadata: Metadata = {},
+  exitCode: number | string | null = null
+): string {
+  return importedClassifyFailure(metadata, exitCode);
+}
+
+/**
+ * List all kaseki instances (running and completed).
+ * Returns array of instance objects with basic metadata.
+ */
+function listInstances(): KasekiInstance[] {
+  const instances: KasekiInstance[] = [];
+
+  // Scan results directory for completed instances
+  let dirs: string[] = [];
+  try {
+    dirs = fs
+      .readdirSync(config.KASEKI_RESULTS_DIR)
+      .filter((d) => d.match(/^kaseki-\d+$/) !== null);
+  } catch {
+    // Results directory may disappear between checks or be transiently unreadable
+    dirs = [];
+  }
+
+  for (const dir of dirs) {
+    try {
+      const instance = dir;
+      const resultDir = path.join(config.KASEKI_RESULTS_DIR, instance);
+
+      // Read metadata and host config
+      const { metadata, hostStart, elapsedSeconds } = readInstanceMetadata(resultDir);
+
+      // Check if currently running via Docker (exact name match)
+      const isRunning = isInstanceRunning(instance);
+
+      // Read exit code from metadata and optional /exit_code file
+      const exitCode = importedResolveInstanceExitCode(resultDir, metadata);
+
+      instances.push({
+        name: instance,
+        status: deriveInstanceLifecycleStatus(isRunning, exitCode),
+        running: isRunning,
+        exitCode,
+        elapsedSeconds,
+        stage: resolveInstanceStageLocal(instance, metadata, 'unknown'),
+        model: hostStart.model || metadata.model || 'unknown',
+        repo: hostStart.repo_url || hostStart.repo || 'unknown',
+        ref: hostStart.git_ref || hostStart.ref || 'unknown',
+      });
+    } catch (e) {
+      if (isSkippableInstanceIoError(e)) {
+        // Instance directory can disappear while scanning; skip just this instance.
+        continue;
+      }
+      throw e;
+    }
+  }
+
+  return instances.sort((a, b) => {
+    // Sort by instance number descending (newest first)
+    const aNum = parseInt((a.name.match(/\d+/) || ['0'])[0], 10);
+    const bNum = parseInt((b.name.match(/\d+/) || ['0'])[0], 10);
+    return bNum - aNum;
+  });
+}
+
+// ============================================================================
+// Artifact Reading
+// ============================================================================
+
+/**
+ * Read an artifact file from a kaseki results directory.
+ * Returns file contents as string, or null if not found.
+ */
+function readArtifact(instance: string, filename: string): string | null {
+  const filePath = path.join(config.KASEKI_RESULTS_DIR, instance, filename);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a live-writable log file (tail the last N lines).
+ * Useful for stdout.log, stderr.log, validation.log which are continuously written.
+ */
+function readLiveLog(instance: string, filename: string, tailLines: number = 50): string | null {
+  const content = readArtifact(instance, filename);
+  if (content === null) return null;
+
+  const lines = content.split('\n').filter((line) => line.length > 0);
+  return lines.slice(Math.max(0, lines.length - tailLines)).join('\n');
+}
+
+/**
+ * Read sanitized progress events emitted by the runner.
+ */
+function readProgressEvents(instance: string, tailLines: number = 20): ProgressEvent[] | null {
+  const content = readArtifact(instance, 'progress.jsonl');
+  if (content === null) return null;
+
+  const lines = content.split('\n').filter((line) => line.trim().length > 0);
+  return lines.slice(Math.max(0, lines.length - tailLines)).map((line) => {
+    try {
+      return JSON.parse(line) as ProgressEvent;
+    } catch {
+      return {
+        timestamp: undefined,
+        stage: 'progress',
+        message: line,
+        malformed: true,
+      };
+    }
+  });
+}
+
+/**
+ * Parse JSON artifact file.
+ * Returns parsed object, or empty object if not found or invalid.
+ */
+function readJsonArtifact(instance: string, filename: string): Record<string, any> {
+  const content = readArtifact(instance, filename);
+  if (!content) return {};
+  try {
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+
+function parseTimestampSeconds(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const parsed = new Date(value).getTime();
+  if (Number.isNaN(parsed)) return null;
+  return Math.floor(parsed / 1000);
+}
+
+function getPiStageStartedAtSeconds(instance: string): number | null {
+  const events = readProgressEvents(instance, 500);
+  if (!events) return null;
+  const started = [...events].reverse().find(
+    (event) =>
+      event &&
+      event.stage === 'pi coding agent' &&
+      (event.message === 'started' || (event as any).type === 'agent_start')
+  );
+  return started ? parseTimestampSeconds(started.timestamp) : null;
+}
+
+// ============================================================================
+// Status and Progress
+// ============================================================================
+
+/**
+ * Get the current stage of a running or completed instance.
+ * Parses stdout.log for "==> stage_name" markers.
+ */
+function getCurrentStage(instance: string): string {
+  const stdout = readArtifact(instance, 'stdout.log');
+  if (!stdout) return 'unknown';
+
+  // Look for the last "==> Stage:" marker
+  const matches = stdout.match(/^==> (.+?)$/gm);
+  if (!matches || matches.length === 0) return 'unknown';
+
+  const lastMarker = matches[matches.length - 1];
+  return lastMarker.replace(/^==> /, '').trim();
+}
+
+/**
+ * Get the configured timeout seconds for the instance.
+ * Reads from host-start.json or falls back to default (1200).
+ */
+function getConfiguredTimeout(instance: string): number {
+  const hostStart = readJsonArtifact(instance, 'host-start.json') as HostStart;
+  return hostStart.agentTimeoutSeconds ?? 1200;
+}
+
+/**
+ * Calculate timeout risk percentage (0-100).
+ * Returns 0 if no risk, 100 if timed out, or percentage if approaching timeout.
+ * Flags warning at 85% of timeout.
+ */
+function calculateTimeoutRiskPercent(
+  instance: string,
+  elapsedSeconds: number | null | undefined
+): number {
+  if (elapsedSeconds === null || elapsedSeconds === undefined) return 0;
+
+  const timeout = getConfiguredTimeout(instance);
+  const percent = (elapsedSeconds / timeout) * 100;
+
+  return Math.min(Math.max(percent, 0), 100);
+}
+
+/**
+ * Determine the overall status of an instance.
+ * Synthesizes all available state into a unified status object.
+ */
+function getInstanceStatus(instance: string): InstanceStatus {
+  const resultDir = path.join(config.KASEKI_RESULTS_DIR, instance);
+  if (!fs.existsSync(resultDir)) {
+    return {
+      instance,
+      status: 'pending',
+      running: false,
+      error: {
+        kind: 'missing-instance',
+        message: `Instance ${instance} not found`,
+      },
+    };
+  }
+
+  const metadata = readJsonArtifact(instance, 'metadata.json') as Metadata;
+  const hostStart = readJsonArtifact(instance, 'host-start.json') as HostStart;
+
+  // Determine if running
+  const isRunning = isInstanceRunning(instance);
+
+  // Get elapsed time
+  let elapsedSeconds: number | null = null;
+  if (metadata.duration_seconds !== undefined) {
+    elapsedSeconds = metadata.duration_seconds;
+  } else if (isRunning) {
+    // For running instances, estimate from start timestamp (new key first, legacy fallback)
+    const startTimestamp = metadata.started_at || metadata.start_time;
+    if (startTimestamp) {
+      const startTime = new Date(startTimestamp).getTime();
+      if (!Number.isNaN(startTime)) {
+        elapsedSeconds = Math.floor((Date.now() - startTime) / 1000);
+      }
+    }
+  }
+
+  // Get stage
+  const stage = resolveInstanceStageLocal(instance, metadata, 'unknown');
+
+  // Get exit code from metadata fallback and /exit_code when available
+  const exitCode = importedResolveInstanceExitCode(resultDir, metadata);
+
+  let agentElapsedSeconds: number | null = null;
+  if (metadata.pi_duration_seconds !== undefined) {
+    agentElapsedSeconds = metadata.pi_duration_seconds;
+  } else if (isRunning && stage === 'pi coding agent') {
+    const piStartedAt = getPiStageStartedAtSeconds(instance);
+    if (piStartedAt !== null) {
+      agentElapsedSeconds = Math.max(Math.floor(Date.now() / 1000) - piStartedAt, 0);
+    }
+  }
+
+  const timeoutSeconds = getConfiguredTimeout(instance);
+  const timedOut = exitCode === 124;
+  const timeoutRiskPercent =
+    isRunning && stage === 'pi coding agent'
+      ? calculateTimeoutRiskPercent(instance, agentElapsedSeconds)
+      : timedOut
+        ? 100
+        : 0;
+  const status = deriveInstanceLifecycleStatus(isRunning, exitCode);
+
+  return {
+    instance,
+    status,
+    running: isRunning,
+    stage,
+    elapsedSeconds,
+    totalDurationSeconds: elapsedSeconds,
+    agentElapsedSeconds,
+    timeoutSeconds,
+    timeoutRiskPercent,
+    timeoutImminent: isRunning && stage === 'pi coding agent' && timeoutRiskPercent >= 85,
+    timedOut,
+    exitCode,
+    failureClass: importedClassifyFailure(metadata, exitCode),
+    repo: hostStart.repo_url || hostStart.repo || 'unknown',
+    ref: hostStart.git_ref || hostStart.ref || 'unknown',
+    model: hostStart.model || 'unknown',
+  };
+}
+
+// ============================================================================
+// Error Detection
+// ============================================================================
+
+/**
+ * Error severity levels
+ */
+const ErrorSeverity = {
+  CRITICAL: 'critical',
+  ERROR: 'error',
+  WARNING: 'warning',
+};
+
+/**
+ * Centralized error pattern matchers.
+ * Used by detectErrors to identify error patterns in log files.
+ */
+const ERROR_PATTERNS = {
+  stderr: /error|failed|exception|panic|abort/i,
+  stderrExclude: /^#.*error/,
+  validation: /FAILED|error|failed/i,
+};
+
+/**
+ * Scan a log file for lines matching an error pattern.
+ * @param instance The kaseki instance name
+ * @param artifactName The artifact filename to scan (e.g., 'stderr.log')
+ * @param pattern The regex pattern to match against each line
+ * @param source The error source label
+ * @param severity The error severity level
+ * @param excludePattern Optional regex to exclude certain lines
+ * @param exitCodeCondition Optional condition to check before scanning (e.g., secret_scan_exit_code !== 0)
+ * @returns Array of detected errors
+ */
+function scanLogForErrors(
+  instance: string,
+  artifactName: string,
+  pattern: RegExp,
+  source: string,
+  severity: string,
+  options?: {
+    excludePattern?: RegExp;
+    exitCodeCondition?: boolean;
+    allNonEmptyLines?: boolean;
+  }
+): DetectedError[] {
+  const errors: DetectedError[] = [];
+
+  // Check optional exit code condition (e.g., for secret-scan.log)
+  if (options?.exitCodeCondition === false) {
+    return errors;
+  }
+
+  const log = readArtifact(instance, artifactName);
+  if (!log) {
+    return errors;
+  }
+
+  const lines = log.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNumber = i + 1;
+
+    // Option: treat all non-empty lines as errors (e.g., quality.log)
+    if (options?.allNonEmptyLines) {
+      if (line.trim().length > 0) {
+        errors.push({
+          severity,
+          source,
+          line: lineNumber,
+          message: line.substring(0, 150),
+        });
+      }
+      continue;
+    }
+
+    // Standard pattern matching with optional exclusion
+    if (line.match(pattern)) {
+      if (options?.excludePattern && line.match(options.excludePattern)) {
+        continue;
+      }
+      errors.push({
+        severity,
+        source,
+        line: lineNumber,
+        message: line.substring(0, 150),
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Detect errors in a kaseki instance.
+ * Scans stderr, quality gates, secret scans, and validation failures.
+ */
+function detectErrors(instance: string): DetectedError[] {
+  const errors: DetectedError[] = [];
+  const resultDir = path.join(config.KASEKI_RESULTS_DIR, instance);
+  if (!fs.existsSync(resultDir)) {
+    return errors;
+  }
+
+  const metadata = readJsonArtifact(instance, 'metadata.json') as Metadata;
+  const exitCode = importedResolveInstanceExitCode(resultDir, metadata);
+
+  // Check for empty diff
+  if (importedClassifyFailure(metadata, exitCode) === 'empty-diff') {
+    errors.push({
+      severity: ErrorSeverity.WARNING,
+      source: 'empty-diff',
+      line: 0,
+      message: 'Agent completed without producing a git diff; set KASEKI_TASK_MODE=inspect or KASEKI_ALLOW_EMPTY_DIFF=1 when this is expected.',
+    });
+  }
+
+  // Check stderr.log for error patterns
+  errors.push(
+    ...scanLogForErrors(
+      instance,
+      'stderr.log',
+      ERROR_PATTERNS.stderr,
+      'stderr',
+      ErrorSeverity.ERROR,
+      { excludePattern: ERROR_PATTERNS.stderrExclude }
+    )
+  );
+
+  // Check quality.log (all non-empty lines are errors)
+  errors.push(
+    ...scanLogForErrors(
+      instance,
+      'quality.log',
+      /.*/,
+      'quality-gate',
+      ErrorSeverity.CRITICAL,
+      { allNonEmptyLines: true }
+    )
+  );
+
+  // Check secret-scan.log (conditional on exit code)
+  const secretScanExitCode = normalizeExitCodeCandidate(metadata.secret_scan_exit_code);
+  errors.push(
+    ...scanLogForErrors(
+      instance,
+      'secret-scan.log',
+      /.*/,
+      'secret-scan',
+      ErrorSeverity.CRITICAL,
+      { allNonEmptyLines: true, exitCodeCondition: secretScanExitCode !== 0 }
+    )
+  );
+
+  // Check validation metadata for failed commands
+  if (typeof metadata.validation_failed_command === 'string' && metadata.validation_failed_command.trim().length > 0) {
+    errors.push({
+      severity: ErrorSeverity.ERROR,
+      source: 'validation',
+      line: 0,
+      message: `Validation failed: ${metadata.validation_failed_command}`.substring(0, 150),
+    });
+  }
+
+  // Check validation.log for error patterns
+  errors.push(
+    ...scanLogForErrors(
+      instance,
+      'validation.log',
+      ERROR_PATTERNS.validation,
+      'validation',
+      ErrorSeverity.ERROR
+    )
+  );
+
+  return errors;
+}
+
+// ============================================================================
+// Analysis
+// ============================================================================
+
+/**
+ * Perform comprehensive post-run analysis.
+ * Returns aggregate metrics and diagnostics.
+ */
+function getAnalysis(instance: string): AnalysisResult {
+  const resultDir = path.join(config.KASEKI_RESULTS_DIR, instance);
+  if (!fs.existsSync(resultDir)) {
+    return {
+      instance,
+      status: 'failed',
+      error: {
+        kind: 'missing-instance',
+        message: `Instance ${instance} not found`,
+      },
+    };
+  }
+
+  const metadata = readJsonArtifact(instance, 'metadata.json') as Metadata;
+  const piSummary = readJsonArtifact(instance, 'pi-summary.json');
+  const changedFilesContent = readArtifact(instance, 'changed-files.txt');
+  const changedFiles =
+    changedFilesContent?.split('\n').filter(Boolean) || [];
+  const errors = detectErrors(instance);
+  const resolvedExitCode = importedResolveInstanceExitCode(resultDir, metadata);
+  const exitCode = resolvedExitCode !== null ? resolvedExitCode : 'unknown';
+  const status = exitCode === 0 ? 'passed' : 'failed';
+
+  return {
+    instance,
+    status,
+    exit_code: exitCode,
+    failure_class: importedClassifyFailure(metadata, resolvedExitCode),
+    failed_command: metadata.failed_command || '',
+    validation_failed_command: metadata.validation_failed_command || '',
+    duration_seconds: metadata.duration_seconds || 0,
+    pi_duration_seconds: metadata.pi_duration_seconds || 0,
+    model: metadata.model || piSummary.selected_model || 'unknown',
+    changed_files_count: changedFiles.length,
+    changed_files: changedFiles.slice(0, 10),
+    tool_executions: (piSummary.tool_start_count || 0) + (piSummary.tool_end_count || 0),
+    errors: errors.slice(0, 10),
+    error_count: errors.length,
+  };
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export {
+  config,
+  KASEKI_RESULTS_DIR,
+  KASEKI_RUNS_DIR,
+  listInstances,
+  readArtifact,
+  readLiveLog,
+  readProgressEvents,
+  readJsonArtifact,
+  getCurrentStage,
+  getConfiguredTimeout,
+  calculateTimeoutRiskPercent,
+  getInstanceStatus,
+  detectErrors,
+  scanLogForErrors,
+  ERROR_PATTERNS,
+  getAnalysis,
+  ErrorSeverity,
+  parseDockerContainerNames,
+  isExactContainerNameMatch,
+  dockerNamesOutputHasInstance,
+  isInstanceRunning,
+  deriveInstanceLifecycleStatus,
+  normalizeExitCodeCandidate,
+  resolveInstanceExitCodeLocal,
+  resolveInstanceStageLocal,
+  classifyFailureLocal,
+  // Types
+  type Config,
+  type KasekiInstance,
+  type Metadata,
+  type HostStart,
+  type InstanceStatus,
+  type ProgressEvent,
+  type DetectedError,
+  type AnalysisResult,
+};