@cyanautomation/kaseki-agent 1.4.1

package/src/kaseki-report.test.ts

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+describe('kaseki-report', () => {
+  let baseDir: string;
+  let suiteStartNs: bigint;
+
+  beforeAll(() => {
+    suiteStartNs = process.hrtime.bigint();
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kaseki-report-test-'));
+  });
+
+  afterAll(() => {
+    const elapsedMs = Number(process.hrtime.bigint() - suiteStartNs) / 1_000_000;
+    process.stdout.write(`\n[kaseki-report.test] runtime_ms=${elapsedMs.toFixed(2)}\n`);
+    fs.rmSync(baseDir, { recursive: true, force: true });
+  });
+
+  function createFixture(
+    name: string,
+    exitCodeValue: any,
+    validationFailedCommand = ''
+  ): { fixtureDir: string; metadataPath: string } {
+    const dir = path.join(baseDir, name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, 'metadata.json'),
+      JSON.stringify({
+        instance: name,
+        exit_code: exitCodeValue,
+        pi_exit_code: exitCodeValue,
+        validation_exit_code: exitCodeValue,
+        validation_failed_command: validationFailedCommand,
+        quality_exit_code: exitCodeValue,
+        secret_scan_exit_code: exitCodeValue,
+      })
+    );
+    fs.writeFileSync(path.join(dir, 'changed-files.txt'), 'src/index.js\n');
+    return { fixtureDir: dir, metadataPath: path.join(dir, 'metadata.json') };
+  }
+
+  function runFixture(fixtureDir: string): {
+    stdout: string;
+    stderr: string;
+    code: number | null;
+  } {
+    const result = spawnSync('npx', ['tsx', 'src/kaseki-report.ts', fixtureDir], {
+      cwd: path.join(__dirname, '..'),
+      encoding: 'utf8',
+    });
+    return { stdout: result.stdout || '', stderr: result.stderr || '', code: result.status };
+  }
+
+  const testCases = [
+    {
+      name: 'exit-num-zero',
+      exitCodeValue: 0,
+      expectedStatus: 'passed',
+      expectedCode: '0',
+    },
+    {
+      name: 'exit-str-zero',
+      exitCodeValue: '0',
+      expectedStatus: 'passed',
+      expectedCode: '0',
+    },
+    {
+      name: 'exit-num-one',
+      exitCodeValue: 1,
+      expectedStatus: 'failed',
+      expectedCode: '1',
+    },
+    {
+      name: 'exit-str-one',
+      exitCodeValue: '1',
+      expectedStatus: 'failed',
+      expectedCode: '1',
+    },
+    {
+      name: 'exit-invalid',
+      exitCodeValue: 'invalid',
+      expectedStatus: 'failed',
+      expectedCode: 'unknown',
+    },
+  ];
+
+  testCases.forEach(({ name, exitCodeValue, expectedStatus, expectedCode }) => {
+    test(`${name}: normalizes exit code and reflects status`, () => {
+      const { fixtureDir } = createFixture(name, exitCodeValue);
+      const result = runFixture(fixtureDir);
+
+      expect(result.code).toBe(0);
+      const expectedLines = [
+        `Status: ${expectedStatus}`,
+        `Exit code: ${expectedCode}`,
+        `Pi exit code: ${expectedCode}`,
+      ];
+      expectedLines.forEach((line) => expect(result.stdout).toContain(line));
+    });
+  });
+
+  test('prints validation failed command detail when metadata includes it', () => {
+    const { fixtureDir } = createFixture(
+      'validation-detail',
+      1,
+      'first failing command was "npm run check" with exit 1'
+    );
+    const result = runFixture(fixtureDir);
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain(
+      'Validation failed command: first failing command was "npm run check" with exit 1'
+    );
+  });
+
+});

package/src/kaseki-report.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { normalizeExitCodeCandidate } from './instance-state-derivation';
+
+const resultDir = process.argv[2] ?? '/results';
+
+interface Metadata {
+  instance?: string;
+  exit_code?: number | string;
+  failed_command?: string;
+  pi_exit_code?: number | string;
+  validation_exit_code?: number | string;
+  validation_failed_command?: string;
+  validation_fail_fast_mode?: boolean;
+  validation_stopped_early?: boolean;
+  validation_commands_attempted?: number;
+  quality_exit_code?: number | string;
+  secret_scan_exit_code?: number | string;
+  model?: string;
+  actual_model?: string;
+  pi_version?: string;
+  duration_seconds?: number;
+  pi_duration_seconds?: number;
+  diff_nonempty?: boolean;
+  [key: string]: any;
+}
+
+interface PiSummary {
+  selected_model?: string;
+  [key: string]: any;
+}
+
+interface FileContent {
+  name: string;
+  text: string;
+}
+
+function readText(name: string): string {
+  try {
+    return fs.readFileSync(path.join(resultDir, name), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function readJson(name: string): Record<string, any> {
+  const text = readText(name);
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+function firstReadableNonEmpty(names: string[]): FileContent | null {
+  for (const name of names) {
+    try {
+      const text = fs.readFileSync(path.join(resultDir, name), 'utf8');
+      if (text.trim()) return { name, text };
+    } catch {
+      // ignore files that cannot be read at decision time
+    }
+  }
+  return null;
+}
+
+function normalizeExitCode(value: any): number | null {
+  return normalizeExitCodeCandidate(value);
+}
+
+function printableExitCode(value: any): string {
+  const normalized = normalizeExitCode(value);
+  return normalized === null ? 'unknown' : String(normalized);
+}
+
+function printList(title: string, values: string[]): void {
+  console.log(`${title}:`);
+  if (values.length === 0) {
+    console.log('  none');
+    return;
+  }
+  for (const value of values) console.log(`  ${value}`);
+}
+
+if (!fs.existsSync(resultDir)) {
+  console.error(`Result directory not found: ${resultDir}`);
+  process.exit(2);
+}
+
+const metadata: Metadata = readJson('metadata.json');
+const summary: PiSummary = readJson('pi-summary.json');
+const changedFiles = readText('changed-files.txt')
+  .split(/\r?\n/)
+  .filter(Boolean);
+const timings = readText('validation-timings.tsv')
+  .split(/\r?\n/)
+  .filter(Boolean);
+const stageTimings = readText('stage-timings.tsv')
+  .split(/\r?\n/)
+  .filter(Boolean);
+const dependencyCache = readText('dependency-cache.log')
+  .split(/\r?\n/)
+  .filter(Boolean);
+const secretScanBytes = Buffer.byteLength(readText('secret-scan.log'));
+
+// Parse restoration.jsonl for metrics
+interface RestorationEvent {
+  status: 'restored' | 'kept';
+  file: string;
+  [key: string]: any;
+}
+
+function parseRestorationMetrics(): { restored: number; kept: number } {
+  const restorationJsonl = readText('restoration.jsonl');
+  if (!restorationJsonl.trim()) return { restored: 0, kept: 0 };
+
+  let restored = 0, kept = 0;
+  for (const line of restorationJsonl.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const event = JSON.parse(line) as RestorationEvent;
+      if (event.status === 'restored') restored++;
+      else if (event.status === 'kept') kept++;
+    } catch {
+      // ignore malformed lines
+    }
+  }
+  return { restored, kept };
+}
+
+const { restored: restoredCount, kept: keptCount } = parseRestorationMetrics();
+const normalizedExitCode = normalizeExitCode(metadata.exit_code);
+const status = normalizedExitCode === 0 ? 'passed' : 'failed';
+const resultName = metadata.instance || path.basename(resultDir);
+const nextDiagnostic =
+  normalizedExitCode === 0
+    ? 'none'
+    : firstReadableNonEmpty([
+      'failure.json',
+      'quality.log',
+      'secret-scan.log',
+      'pi-stderr.log',
+      'validation.log',
+      'preflight-git.log',
+      'stderr.log',
+    ])?.name ?? 'metadata.json';
+
+console.log(`Kaseki result: ${resultName}`);
+console.log(`Status: ${status}`);
+console.log(`Failed command: ${metadata.failed_command || 'none'}`);
+console.log(`Exit code: ${printableExitCode(metadata.exit_code)}`);
+console.log(`Pi exit code: ${printableExitCode(metadata.pi_exit_code)}`);
+console.log(
+  `Validation exit code: ${printableExitCode(metadata.validation_exit_code)}`
+);
+console.log(
+  `Validation failed command: ${metadata.validation_failed_command || 'none'}`
+);
+if (metadata.validation_stopped_early) {
+  console.log(
+    `⚠️  Validation stopped early (fail-fast mode): ${metadata.validation_commands_attempted ?? 'unknown'} command(s) attempted`
+  );
+}
+console.log(`Quality exit code: ${printableExitCode(metadata.quality_exit_code)}`);
+console.log(
+  `Secret scan exit code: ${printableExitCode(metadata.secret_scan_exit_code)}`
+);
+console.log(`Requested model: ${metadata.model || 'unknown'}`);
+console.log(
+  `Actual model: ${metadata.actual_model || summary.selected_model || 'unknown'}`
+);
+console.log(`Pi version: ${metadata.pi_version || 'unknown'}`);
+console.log(`Duration seconds: ${metadata.duration_seconds ?? 'unknown'}`);
+console.log(
+  `Agent duration seconds: ${metadata.pi_duration_seconds ?? 'unknown'}`
+);
+console.log(`Diff non-empty: ${metadata.diff_nonempty ?? 'unknown'}`);
+printList('Changed files', changedFiles);
+if (restoredCount > 0 || keptCount > 0) {
+  const totalFiles = restoredCount + keptCount;
+  const coverage = totalFiles > 0 ? Math.round((keptCount * 100) / totalFiles) : 0;
+  console.log(`Allowlist coverage: ${keptCount}/${totalFiles} files (${coverage}%)`);
+  console.log(`Files restored: ${restoredCount}`);
+  console.log(`Files kept (allowlist match): ${keptCount}`);
+}
+printList('Stage timings', stageTimings);
+printList('Validation timings', timings);
+printList('Dependency cache', dependencyCache);
+console.log(`Secret scan bytes: ${secretScanBytes}`);
+console.log(`Next diagnostic: ${nextDiagnostic}`);

package/src/lib/subprocess-helpers.ts

@@ -0,0 +1,177 @@
+/**
+ * Shared subprocess execution utilities and patterns.
+ * Consolidates error handling, timeouts, and Docker-specific logic
+ * to reduce duplication across job-scheduler.ts, kaseki-api-routes.ts, and file-helpers.ts.
+ */
+
+import { spawnSync, SpawnSyncReturns } from 'child_process';
+
+/**
+ * Result of a subprocess execution.
+ */
+export interface SubprocessResult {
+  ok: boolean;
+  status?: number;
+  stdout?: string;
+  stderr?: string;
+  detail?: string;
+  error?: string;
+}
+
+/**
+ * Classification of a Docker command failure with remediation steps.
+ */
+export interface DockerFailureClassification {
+  detail: string;
+  remediation: string;
+}
+
+/**
+ * Default timeout for subprocess operations in milliseconds.
+ */
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/**
+ * Classify a Docker command failure based on error message.
+ * Returns actionable detail and remediation information.
+ *
+ * @param stderr Error output from Docker command
+ * @returns Object with detail and remediation strings
+ */
+export function classifyDockerFailure(stderr: string): DockerFailureClassification {
+  const normalized = stderr.toLowerCase();
+  if (normalized.includes('permission denied') || normalized.includes('connect: permission denied')) {
+    return {
+      detail: 'Docker daemon socket is not accessible from the API process.',
+      remediation:
+        'Add the API container user to the host Docker socket group, for example group_add: ["${DOCKER_GID:-985}"].',
+    };
+  }
+  if (normalized.includes('cannot connect') || normalized.includes('is the docker daemon running')) {
+    return {
+      detail: 'Docker daemon is unreachable from the API process.',
+      remediation: 'Mount /var/run/docker.sock and verify the host Docker daemon is running.',
+    };
+  }
+  return {
+    detail: stderr.trim() || 'Docker command failed.',
+    remediation: 'Verify Docker CLI, daemon access, and the mounted Docker socket.',
+  };
+}
+
+/**
+ * Extract error message from a SpawnSyncReturns result.
+ * Prioritizes stderr, then stdout, then error message.
+ *
+ * @param result SpawnSync result object
+ * @returns Combined error message string
+ */
+export function extractErrorMessage(result: SpawnSyncReturns<string | Buffer>): string {
+  const parts: string[] = [];
+  if (result.stderr) {
+    parts.push(typeof result.stderr === 'string' ? result.stderr : result.stderr.toString());
+  }
+  if (result.stdout && !result.stderr) {
+    parts.push(typeof result.stdout === 'string' ? result.stdout : result.stdout.toString());
+  }
+  if (result.error?.message && !parts.length) {
+    parts.push(result.error.message);
+  }
+  return parts.join(' ').trim();
+}
+
+/**
+ * Execute a shell command with standard error handling and timeout.
+ * Returns success/failure status with combined output.
+ *
+ * @param command Command to execute
+ * @param args Arguments to pass
+ * @param options.cwd Working directory (optional)
+ * @param options.timeoutMs Timeout in milliseconds (default: 5000)
+ * @returns SubprocessResult with status, output, and detail
+ *
+ * @example
+ * const result = execSubprocess('docker', ['version']);
+ * if (result.ok) {
+ *   console.log(result.stdout);
+ * } else {
+ *   console.error(result.detail);
+ * }
+ */
+export function execSubprocess(
+  command: string,
+  args: string[],
+  options?: {
+    cwd?: string;
+    timeoutMs?: number;
+  },
+): SubprocessResult {
+  const result = spawnSync(command, args, {
+    cwd: options?.cwd,
+    encoding: 'utf-8',
+    timeout: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  });
+
+  const detail = extractErrorMessage(result);
+
+  return {
+    ok: result.status === 0,
+    status: result.status ?? undefined,
+    stdout: typeof result.stdout === 'string' ? result.stdout.trim() || undefined : undefined,
+    stderr: typeof result.stderr === 'string' ? result.stderr.trim() || undefined : undefined,
+    detail: detail || undefined,
+    error: result.error?.message,
+  };
+}
+
+/**
+ * Execute a Docker command with error classification and timeout.
+ * Automatically classifies Docker-specific error messages.
+ *
+ * @param args Docker command arguments (e.g., ['version', '--format', '{{.Client.Version}}'])
+ * @param timeoutMs Timeout in milliseconds (default: 5000)
+ * @returns Object with status, output, and Docker-specific error classification
+ *
+ * @example
+ * const result = execDockerCommand(['version']);
+ * if (result.ok) {
+ *   console.log(result.stdout);
+ * } else {
+ *   console.error(result.classification.remediation);
+ * }
+ */
+export function execDockerCommand(
+  args: string[],
+  timeoutMs?: number,
+): SubprocessResult & { classification?: DockerFailureClassification } {
+  const result = execSubprocess('docker', args, { timeoutMs });
+
+  if (!result.ok && result.detail) {
+    return {
+      ...result,
+      classification: classifyDockerFailure(result.detail),
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Execute a command and return only its stdout output on success, undefined on failure.
+ * Useful for extracting single-value outputs (version strings, git refs, etc.).
+ *
+ * @param command Command to execute
+ * @param args Arguments to pass
+ * @param cwd Working directory (optional)
+ * @returns Trimmed stdout on success, undefined on failure
+ *
+ * @example
+ * const version = commandOutput('git', ['rev-parse', '--short', 'HEAD']);
+ * if (version) {
+ *   console.log('Commit:', version);
+ * }
+ */
+export function commandOutput(command: string, args: string[], cwd?: string): string | undefined {
+  const result = execSubprocess(command, args, { cwd });
+  return result.ok ? result.stdout : undefined;
+}

package/src/logger.ts

@@ -0,0 +1,114 @@
+/**
+ * Centralized logging utility with log level filtering.
+ *
+ * Emits structured JSON events to stdout, respecting LOG_LEVEL env var.
+ * All timestamps are ISO 8601 format.
+ *
+ * Log levels: debug < info < warn < error
+ * - DEBUG: All messages
+ * - INFO: info, warn, error (default)
+ * - WARN: warn, error
+ * - ERROR: error only
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/**
+ * Get the log level from environment variable with default.
+ */
+function getLogLevel(): LogLevel {
+  const envLevel = process.env.LOG_LEVEL || process.env.KASEKI_API_LOG_LEVEL || 'info';
+  const normalized = envLevel.toLowerCase() as LogLevel;
+
+  if (normalized in LOG_LEVEL_ORDER) {
+    return normalized;
+  }
+
+  console.error(`Invalid LOG_LEVEL: ${envLevel}, defaulting to info`);
+  return 'info';
+}
+
+/**
+ * Logger instance for a component.
+ */
+export interface Logger {
+  debug(message: string, detail?: Record<string, unknown>): void;
+  info(message: string, detail?: Record<string, unknown>): void;
+  warn(message: string, detail?: Record<string, unknown>): void;
+  error(message: string, detail?: Record<string, unknown>): void;
+}
+
+/**
+ * Create a logger for a component.
+ */
+export function createLogger(component: string): Logger {
+  const currentLogLevel = getLogLevel();
+  const currentLevelOrder = LOG_LEVEL_ORDER[currentLogLevel];
+
+  function shouldLog(messageLevel: LogLevel): boolean {
+    return LOG_LEVEL_ORDER[messageLevel] >= currentLevelOrder;
+  }
+
+  function emit(level: LogLevel, message: string, detail?: Record<string, unknown>): void {
+    if (!shouldLog(level)) {
+      return;
+    }
+
+    const event = {
+      timestamp: new Date().toISOString(),
+      level,
+      component,
+      message,
+      ...(detail && Object.keys(detail).length > 0 && { detail }),
+    };
+
+    console.log(JSON.stringify(event));
+  }
+
+  return {
+    debug: (message: string, detail?: Record<string, unknown>) => emit('debug', message, detail),
+    info: (message: string, detail?: Record<string, unknown>) => emit('info', message, detail),
+    warn: (message: string, detail?: Record<string, unknown>) => emit('warn', message, detail),
+    error: (message: string, detail?: Record<string, unknown>) => emit('error', message, detail),
+  };
+}
+
+/**
+ * Create a logger that can also emit structured events (for progress.jsonl format).
+ *
+ * Events are JSON objects with timestamp, component, event_type, and optional detail.
+ * This is used for structured operational events (job_submitted, stage_started, etc.).
+ */
+export interface EventLogger extends Logger {
+  event(eventType: string, detail?: Record<string, unknown>): void;
+}
+
+/**
+ * Create an event-capable logger.
+ */
+export function createEventLogger(component: string): EventLogger {
+  const baseLogger = createLogger(component);
+
+  function emitEvent(eventType: string, detail?: Record<string, unknown>): void {
+    const event = {
+      timestamp: new Date().toISOString(),
+      component,
+      event_type: eventType,
+      ...(detail && Object.keys(detail).length > 0 && detail),
+    };
+
+    console.log(JSON.stringify(event));
+  }
+
+  return {
+    ...baseLogger,
+    event: (eventType: string, detail?: Record<string, unknown>) => emitEvent(eventType, detail),
+  };
+}

package/src/metrics.ts

@@ -0,0 +1,66 @@
+export class MetricsRegistry {
+  private queuePending = 0;
+  private runningJobs = 0;
+  private runsTotal = { success: 0, failure: 0 };
+  private timeoutsTotal = 0;
+  private readonly durationBuckets = [0.5, 1, 2.5, 5, 10, 30, 60, 120, 300, 600, 1800];
+  private durationBucketCounts: number[] = this.durationBuckets.map(() => 0);
+  private durationSum = 0;
+  private durationCount = 0;
+
+  setQueuePending(count: number): void { this.queuePending = Math.max(0, count); }
+  setRunningJobs(count: number): void { this.runningJobs = Math.max(0, count); }
+  incRunSuccess(): void { this.runsTotal.success += 1; }
+  incRunFailure(): void { this.runsTotal.failure += 1; }
+  incTimeout(): void { this.timeoutsTotal += 1; }
+
+  observeRunDuration(seconds: number): void {
+    const value = Number.isFinite(seconds) && seconds >= 0 ? seconds : 0;
+    this.durationSum += value;
+    this.durationCount += 1;
+    for (let i = 0; i < this.durationBuckets.length; i += 1) {
+      if (value <= this.durationBuckets[i]) {
+        for (let j = i; j < this.durationBuckets.length; j += 1) {
+          this.durationBucketCounts[j] += 1;
+        }
+        break;
+      }
+    }
+  }
+
+  renderPrometheus(): string {
+    const lines: string[] = [];
+    lines.push('# HELP kaseki_queue_pending Number of queued jobs awaiting execution.');
+    lines.push('# TYPE kaseki_queue_pending gauge');
+    lines.push(`kaseki_queue_pending ${this.queuePending}`);
+    lines.push('# HELP kaseki_running_jobs Number of jobs currently running.');
+    lines.push('# TYPE kaseki_running_jobs gauge');
+    lines.push(`kaseki_running_jobs ${this.runningJobs}`);
+
+    lines.push('# HELP kaseki_runs_total Total number of completed runs partitioned by outcome.');
+    lines.push('# TYPE kaseki_runs_total counter');
+    lines.push(`kaseki_runs_total{result="success"} ${this.runsTotal.success}`);
+    lines.push(`kaseki_runs_total{result="failure"} ${this.runsTotal.failure}`);
+
+    lines.push('# HELP kaseki_run_duration_seconds Runtime duration of completed jobs in seconds.');
+    lines.push('# TYPE kaseki_run_duration_seconds histogram');
+    this.durationBuckets.forEach((bucket, idx) => {
+      lines.push(`kaseki_run_duration_seconds_bucket{le="${bucket}"} ${this.durationBucketCounts[idx]}`);
+    });
+    lines.push(`kaseki_run_duration_seconds_bucket{le="+Inf"} ${this.durationCount}`);
+    lines.push(`kaseki_run_duration_seconds_sum ${this.durationSum}`);
+    lines.push(`kaseki_run_duration_seconds_count ${this.durationCount}`);
+
+    lines.push('# HELP kaseki_timeouts_total Total number of timed out runs.');
+    lines.push('# TYPE kaseki_timeouts_total counter');
+    lines.push(`kaseki_timeouts_total ${this.timeoutsTotal}`);
+    lines.push('# HELP kaseki_timeout_rate Ratio of timed out runs to all completed runs.');
+    lines.push('# TYPE kaseki_timeout_rate gauge');
+    const totalRuns = this.runsTotal.success + this.runsTotal.failure;
+    lines.push(`kaseki_timeout_rate ${totalRuns > 0 ? this.timeoutsTotal / totalRuns : 0}`);
+
+    return `${lines.join('\n')}\n`;
+  }
+}
+
+export const metricsRegistry = new MetricsRegistry();