@cyanautomation/kaseki-agent 1.4.1

package/src/instance-state-derivation.test.ts

@@ -0,0 +1,263 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import {
+  deriveInstanceLifecycleStatus,
+  resolveInstanceExitCode,
+  resolveInstanceStage,
+  classifyFailure,
+  extractValidationFailureReason,
+  extractQualityFailureReason,
+} from './instance-state-derivation';
+
+describe('instance-state-derivation', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kaseki-test-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('deriveInstanceLifecycleStatus', () => {
+    it('should return running when isRunning is true', () => {
+      const status = deriveInstanceLifecycleStatus(true, 0);
+      expect(status).toBe('running');
+    });
+
+    it('should return completed when isRunning is false and exitCode is 0', () => {
+      const status = deriveInstanceLifecycleStatus(false, 0);
+      expect(status).toBe('completed');
+    });
+
+    it('should return failed when isRunning is false and exitCode is non-zero', () => {
+      const status = deriveInstanceLifecycleStatus(false, 1);
+      expect(status).toBe('failed');
+    });
+
+    it('should return pending when isRunning is false and exitCode is null', () => {
+      const status = deriveInstanceLifecycleStatus(false, null);
+      expect(status).toBe('pending');
+    });
+  });
+
+  describe('resolveInstanceExitCode', () => {
+    it('should read exit code from metadata', () => {
+      const metadata = { exit_code: 42 };
+      const exitCode = resolveInstanceExitCode(tempDir, metadata);
+      expect(exitCode).toBe(42);
+    });
+
+    it('should parse string exit code from metadata', () => {
+      const metadata = { exit_code: '99' };
+      const exitCode = resolveInstanceExitCode(tempDir, metadata);
+      expect(exitCode).toBe(99);
+    });
+
+    it('should prefer /exit_code file over metadata', () => {
+      const metadata = { exit_code: 1 };
+      fs.writeFileSync(path.join(tempDir, 'exit_code'), '42');
+
+      const exitCode = resolveInstanceExitCode(tempDir, metadata);
+      expect(exitCode).toBe(42);
+    });
+
+    it('should fall back to metadata if /exit_code file is invalid', () => {
+      const metadata = { exit_code: 1 };
+      fs.writeFileSync(path.join(tempDir, 'exit_code'), 'invalid');
+
+      const exitCode = resolveInstanceExitCode(tempDir, metadata);
+      expect(exitCode).toBe(1);
+    });
+
+    it('should return null when no exit code is available', () => {
+      const exitCode = resolveInstanceExitCode(tempDir, {});
+      expect(exitCode).toBeNull();
+    });
+
+    it('should treat malformed metadata exit codes as pending', () => {
+      const metadata = { exit_code: 1.5 };
+
+      const exitCode = resolveInstanceExitCode(tempDir, metadata);
+      const status = deriveInstanceLifecycleStatus(false, exitCode);
+
+      expect(exitCode).toBeNull();
+      expect(status).toBe('pending');
+    });
+  });
+
+  describe('resolveInstanceStage', () => {
+    it('should return current_stage from metadata when available', () => {
+      const metadata = { current_stage: 'validation' };
+      const instanceDir = path.join(tempDir, 'kaseki-1');
+      fs.mkdirSync(instanceDir, { recursive: true });
+
+      const stage = resolveInstanceStage(tempDir, 'kaseki-1', metadata);
+      expect(stage).toBe('validation');
+    });
+
+    it('should parse stage from stdout.log when metadata is missing', () => {
+      const instanceDir = path.join(tempDir, 'kaseki-1');
+      fs.mkdirSync(instanceDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(instanceDir, 'stdout.log'),
+        '==> Clone repo\n==> Install dependencies\n==> pi coding agent'
+      );
+
+      const stage = resolveInstanceStage(tempDir, 'kaseki-1', {});
+      expect(stage).toBe('pi coding agent');
+    });
+
+    it('should return fallback when no stage information is available', () => {
+      const instanceDir = path.join(tempDir, 'kaseki-1');
+      fs.mkdirSync(instanceDir, { recursive: true });
+
+      const stage = resolveInstanceStage(tempDir, 'kaseki-1', {}, 'default');
+      expect(stage).toBe('default');
+    });
+
+    it('should ignore empty current_stage in metadata', () => {
+      const metadata = { current_stage: '   ' };
+      const instanceDir = path.join(tempDir, 'kaseki-1');
+      fs.mkdirSync(instanceDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(instanceDir, 'stdout.log'),
+        '==> Stage from stdout'
+      );
+
+      const stage = resolveInstanceStage(tempDir, 'kaseki-1', metadata);
+      expect(stage).toBe('Stage from stdout');
+    });
+  });
+
+  describe('classifyFailure', () => {
+    it('should classify zero exit code as none', () => {
+      const classification = classifyFailure({}, 0);
+      expect(classification).toBe('none');
+    });
+
+    it('should classify exit code 124 as timeout', () => {
+      const classification = classifyFailure({}, 124);
+      expect(classification).toBe('timeout');
+    });
+
+    it('should classify empty diff failures', () => {
+      const classification1 = classifyFailure({ failed_command: 'empty git diff' }, 3);
+      const classification2 = classifyFailure({}, 3);
+      expect(classification1).toBe('empty-diff');
+      expect(classification2).toBe('empty-diff');
+    });
+
+    it('should classify validation failures', () => {
+      const classification = classifyFailure({ failed_command: 'validation' }, 1);
+      expect(classification).toBe('validation');
+    });
+
+    it('should classify quality gate failures', () => {
+      const classification = classifyFailure({ failed_command: 'quality checks' }, 5);
+      expect(classification).toBe('quality');
+    });
+
+    it('should classify secret scan failures', () => {
+      const classification = classifyFailure({ failed_command: 'secret scan' }, 6);
+      expect(classification).toBe('secret-scan');
+    });
+
+    it('should classify github-related failures', () => {
+      const classification = classifyFailure({ failed_command: 'github-api-error' }, 1);
+      expect(classification).toBe('github');
+    });
+
+    it('should classify credential-related failures', () => {
+      const c1 = classifyFailure({ failed_command: 'OPENROUTER_API_KEY missing' }, 1);
+      const c2 = classifyFailure({ failed_command: 'OpenRouter error' }, 1);
+      expect(c1).toBe('credentials');
+      expect(c2).toBe('credentials');
+    });
+
+    it('should return unknown for unclassified failures', () => {
+      const classification = classifyFailure({}, 42);
+      expect(classification).toBe('nonzero-exit');
+    });
+
+    it('should sanitize failed_command by replacing spaces with dashes', () => {
+      const classification = classifyFailure(
+        { failed_command: 'npm test run' },
+        1
+      );
+      expect(classification).toBe('npm-test-run');
+    });
+
+    it('should handle string exit codes', () => {
+      const classification = classifyFailure({}, '124');
+      expect(classification).toBe('timeout');
+    });
+  });
+
+  describe('extractValidationFailureReason', () => {
+    it('should return null when validation_failure_reason is not set', () => {
+      const reason = extractValidationFailureReason({});
+      expect(reason).toBeNull();
+    });
+
+    it('should return the reason when validation_failure_reason is set', () => {
+      const reason = extractValidationFailureReason({
+        validation_failure_reason: 'validation_command_failed: npm run test (exit 1)',
+      });
+      expect(reason).toBe('validation_command_failed: npm run test (exit 1)');
+    });
+
+    it('should trim whitespace from reason', () => {
+      const reason = extractValidationFailureReason({
+        validation_failure_reason: '  missing_npm_script: check  ',
+      });
+      expect(reason).toBe('missing_npm_script: check');
+    });
+
+    it('should return null for empty reason string', () => {
+      const reason = extractValidationFailureReason({
+        validation_failure_reason: '   ',
+      });
+      expect(reason).toBeNull();
+    });
+  });
+
+  describe('extractQualityFailureReason', () => {
+    it('should return null when quality_failure_reason is not set', () => {
+      const reason = extractQualityFailureReason({});
+      expect(reason).toBeNull();
+    });
+
+    it('should return the reason when quality_failure_reason is set', () => {
+      const reason = extractQualityFailureReason({
+        quality_failure_reason: "allowlist_check: file 'src/forbidden.ts' not in allowlist",
+      });
+      expect(reason).toBe(
+        "allowlist_check: file 'src/forbidden.ts' not in allowlist"
+      );
+    });
+
+    it('should handle max_diff_bytes failure reason', () => {
+      const reason = extractQualityFailureReason({
+        quality_failure_reason: 'max_diff_bytes: 250000 bytes exceeds limit of 200000 bytes',
+      });
+      expect(reason).toBe('max_diff_bytes: 250000 bytes exceeds limit of 200000 bytes');
+    });
+
+    it('should trim whitespace from reason', () => {
+      const reason = extractQualityFailureReason({
+        quality_failure_reason: '  max_diff_bytes: overflow  ',
+      });
+      expect(reason).toBe('max_diff_bytes: overflow');
+    });
+
+    it('should return null for empty reason string', () => {
+      const reason = extractQualityFailureReason({
+        quality_failure_reason: '',
+      });
+      expect(reason).toBeNull();
+    });
+  });
+});

package/src/instance-state-derivation.ts

@@ -0,0 +1,148 @@
+/**
+ * instance-state-derivation.ts
+ *
+ * Encapsulates state derivation logic for kaseki instances.
+ * Derives lifecycle status, exit codes, stages, and failure classifications
+ * from metadata and instance artifacts.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { Metadata } from './instance-metadata-reader';
+
+export type InstanceLifecycleStatus = 'running' | 'completed' | 'failed' | 'pending';
+
+/**
+ * Normalize an exit code candidate into an integer or null.
+ */
+export function normalizeExitCodeCandidate(value: any): number | null {
+  if (typeof value === 'number' && Number.isInteger(value)) {
+    return value;
+  }
+  if (typeof value === 'string' && /^-?\d+$/.test(value.trim())) {
+    return parseInt(value.trim(), 10);
+  }
+  return null;
+}
+
+/**
+ * Derive lifecycle status from running flag and exit code.
+ */
+export function deriveInstanceLifecycleStatus(
+  isRunning: boolean,
+  exitCode: number | null
+): InstanceLifecycleStatus {
+  if (isRunning) return 'running';
+  if (exitCode === 0) return 'completed';
+  if (Number.isInteger(exitCode)) return 'failed';
+  return 'pending';
+}
+
+/**
+ * Resolve exit code from metadata and optional /exit_code file.
+ * Prefers /exit_code file when readable, falls back to metadata.exit_code.
+ * Returns null only when neither source has a valid integer.
+ */
+export function resolveInstanceExitCode(
+  resultDir: string,
+  metadata: Metadata = {}
+): number | null {
+  const metadataExitCode = normalizeExitCodeCandidate(metadata.exit_code);
+  const exitCodePath = path.join(resultDir, 'exit_code');
+  if (!fs.existsSync(exitCodePath)) {
+    return metadataExitCode;
+  }
+
+  try {
+    const fileExitCode = normalizeExitCodeCandidate(fs.readFileSync(exitCodePath, 'utf8'));
+    return fileExitCode !== null ? fileExitCode : metadataExitCode;
+  } catch {
+    return metadataExitCode;
+  }
+}
+
+/**
+ * Get the current stage of a running or completed instance.
+ * Parses stdout.log for "==> stage_name" markers.
+ */
+function getCurrentStage(resultsDir: string, instanceName: string): string {
+  const stdoutPath = path.join(resultsDir, instanceName, 'stdout.log');
+  if (!fs.existsSync(stdoutPath)) {
+    return 'unknown';
+  }
+
+  try {
+    const stdout = fs.readFileSync(stdoutPath, 'utf8');
+    const matches = stdout.match(/^==> (.+?)$/gm);
+    if (!matches || matches.length === 0) return 'unknown';
+
+    const lastMarker = matches[matches.length - 1];
+    return lastMarker.replace(/^==> /, '').trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Resolve stage from metadata first, then fallback to stdout markers.
+ */
+export function resolveInstanceStage(
+  resultsDir: string,
+  instanceName: 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(resultsDir, instanceName);
+  return parsedStage !== 'unknown' ? parsedStage : fallback;
+}
+
+/**
+ * Extract validation failure reason from metadata.
+ * Returns the reason if validation failed, otherwise null.
+ */
+export function extractValidationFailureReason(metadata: Metadata = {}): string | null {
+  const reason = typeof metadata.validation_failure_reason === 'string'
+    ? metadata.validation_failure_reason.trim()
+    : '';
+  return reason.length > 0 ? reason : null;
+}
+
+/**
+ * Extract quality gate failure reason from metadata.
+ * Returns the reason if quality checks failed, otherwise null.
+ */
+export function extractQualityFailureReason(metadata: Metadata = {}): string | null {
+  const reason = typeof metadata.quality_failure_reason === 'string'
+    ? metadata.quality_failure_reason.trim()
+    : '';
+  return reason.length > 0 ? reason : null;
+}
+
+/**
+ * Classify failure type from metadata and exit code.
+ */
+export function classifyFailure(
+  metadata: Metadata = {},
+  exitCode: number | string | null = null
+): string {
+  const normalizedExitCode = normalizeExitCodeCandidate(exitCode);
+  const failedCommand =
+    typeof metadata.failed_command === 'string' ? metadata.failed_command.trim() : '';
+
+  if (normalizedExitCode === 0) return 'none';
+  if (normalizedExitCode === 124) return 'timeout';
+  if (failedCommand === 'empty git diff' || normalizedExitCode === 3) return 'empty-diff';
+  if (failedCommand === 'validation') return 'validation';
+  if (failedCommand === 'quality checks') return 'quality';
+  if (failedCommand === 'secret scan') return 'secret-scan';
+  if (failedCommand.startsWith('github')) return 'github';
+  if (failedCommand.includes('OPENROUTER_API_KEY') || failedCommand.includes('OpenRouter')) {
+    return 'credentials';
+  }
+  if (failedCommand) return failedCommand.replace(/\s+/g, '-');
+  if (Number.isInteger(normalizedExitCode)) return 'nonzero-exit';
+  return 'unknown';
+}