@cyanautomation/kaseki-agent 1.4.1

package/src/test-utils.ts

@@ -0,0 +1,81 @@
+/**
+ * Shared generic test utilities and fixtures for unit and integration tests.
+ * Consolidates common test setup patterns to reduce duplication.
+ *
+ * This module contains reusable test factories and types that can be imported
+ * by multiple test files. For API-route-specific test setup, see kaseki-api-routes.test.ts.
+ */
+
+import type { KasekiApiConfig } from './kaseki-api-config';
+
+/**
+ * Test-specific config type with jest.fn() mocks.
+ */
+export interface TestScheduler {
+  getQueueStatus: jest.Mock;
+  getReadiness: jest.Mock;
+  getJob: jest.Mock;
+  submitJob: jest.Mock;
+  listJobs: jest.Mock;
+  cancelJob: jest.Mock;
+}
+
+/**
+ * Possible job statuses for mock scheduler.
+ */
+export type MockJobStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * Mock job object for tests.
+ */
+export interface MockJob {
+  id: string;
+  status: MockJobStatus;
+  createdAt: Date;
+  resultDir?: string;
+  exitCode?: number;
+  failureClass?: string;
+  error?: string;
+}
+
+/**
+ * Creates a mock scheduler with standard behavior for tests.
+ * Customize by providing jobData to override default getJob behavior.
+ *
+ * @example
+ * const scheduler = createMockScheduler();
+ * scheduler.getReadiness.mockReturnValue({ ready: false, reasons: ['error'] });
+ */
+export function createMockScheduler(jobData?: { [jobId: string]: MockJob }): TestScheduler {
+  return {
+    getQueueStatus: jest.fn(() => ({ pending: 0, running: 0, maxConcurrent: 1 })),
+    getReadiness: jest.fn(() => ({ ready: true, reasons: [] })),
+    getJob: jest.fn((id: string) => jobData?.[id]),
+    submitJob: jest.fn(),
+    listJobs: jest.fn(() => []),
+    cancelJob: jest.fn(),
+  };
+}
+
+/**
+ * Creates a standard test configuration object.
+ * Pass resultsDir to set the directory; other params use reasonable defaults.
+ *
+ * @example
+ * const config = createTestConfig('/tmp/results');
+ */
+export function createTestConfig(resultsDir: string): KasekiApiConfig {
+  return {
+    port: 0,
+    apiKeys: ['test-key'],
+    resultsDir,
+    maxConcurrentRuns: 1,
+    defaultTaskMode: 'patch' as const,
+    maxDiffBytes: 200000,
+    agentTimeoutSeconds: 1200,
+    logLevel: 'info' as const,
+    artifactCacheMaxEntries: 20,
+    artifactCacheTtlMs: 5 * 60 * 1000,
+    artifactCacheMaxFileBytes: 10 * 1024 * 1024,
+  };
+}

package/src/timestamp-tracker.test.ts

@@ -0,0 +1,134 @@
+import { TimestampTracker } from './timestamp-tracker';
+
+describe('TimestampTracker', () => {
+  it('should record and retrieve first and last ISO timestamps', () => {
+    const tracker = new TimestampTracker();
+    tracker.record('2024-01-01T10:00:00Z');
+    tracker.record('2024-01-01T10:05:00Z');
+    tracker.record('2024-01-01T10:10:00Z');
+
+    expect(tracker.firstTimestamp()).toBe('2024-01-01T10:00:00Z');
+    expect(tracker.lastTimestamp()).toBe('2024-01-01T10:10:00Z');
+  });
+
+  it('should return null for first/last when no timestamps recorded', () => {
+    const tracker = new TimestampTracker();
+    expect(tracker.firstTimestamp()).toBeNull();
+    expect(tracker.lastTimestamp()).toBeNull();
+  });
+
+  it('should ignore null and empty timestamps', () => {
+    const tracker = new TimestampTracker();
+    tracker.record(null);
+    tracker.record('');
+
+    expect(tracker.firstTimestamp()).toBeNull();
+    expect(tracker.lastTimestamp()).toBeNull();
+  });
+
+  it('should convert ISO timestamps to epoch milliseconds', () => {
+    const tracker = new TimestampTracker();
+    const iso = '2024-01-01T00:00:00Z';
+    tracker.record(iso);
+
+    const epochMs = tracker.getEpochMs(iso);
+    expect(epochMs).toBe(1704067200000);
+  });
+
+  it('should return null for malformed timestamps', () => {
+    const tracker = new TimestampTracker();
+    const malformed = 'not-a-timestamp';
+
+    const epochMs = tracker.getEpochMs(malformed);
+    expect(epochMs).toBeNull();
+  });
+
+  it('should handle malformed timestamps gracefully during record', () => {
+    const tracker = new TimestampTracker();
+    tracker.record('2024-01-01T10:00:00Z');
+    tracker.record('invalid-timestamp');
+    tracker.record('2024-01-01T10:05:00Z');
+
+    // Should still track valid timestamps
+    expect(tracker.firstTimestamp()).toBe('2024-01-01T10:00:00Z');
+    expect(tracker.lastTimestamp()).toBe('2024-01-01T10:05:00Z');
+  });
+
+  it('should track min and max epoch milliseconds', () => {
+    const tracker = new TimestampTracker();
+    tracker.record('2024-01-01T10:05:00Z');
+    tracker.record('2024-01-01T10:00:00Z');
+    tracker.record('2024-01-01T10:10:00Z');
+
+    const firstEpochMs = tracker.firstEpochMs();
+    const lastEpochMs = tracker.lastEpochMs();
+
+    // Epoch millis should be min and max across all recorded timestamps
+    const expectedMin = new Date('2024-01-01T10:00:00Z').getTime();
+    const expectedMax = new Date('2024-01-01T10:10:00Z').getTime();
+
+    expect(firstEpochMs).toBe(expectedMin);
+    expect(lastEpochMs).toBe(expectedMax);
+  });
+
+  it('should calculate duration in milliseconds between first and last epochs', () => {
+    const tracker = new TimestampTracker();
+    tracker.record('2024-01-01T10:00:00Z');
+    tracker.record('2024-01-01T10:05:00Z');
+
+    const duration = tracker.durationMs();
+    expect(duration).toBe(5 * 60 * 1000); // 5 minutes in ms
+  });
+
+  it('should return null for duration when timestamps are missing', () => {
+    const tracker = new TimestampTracker();
+    expect(tracker.durationMs()).toBeNull();
+  });
+
+  it('should return 0 for duration when only one timestamp is recorded', () => {
+    const tracker = new TimestampTracker();
+    tracker.record('2024-01-01T10:00:00Z');
+    // After recording one timestamp, both first and last are the same
+    const duration = tracker.durationMs();
+    expect(duration).toBe(0);
+  });
+
+  it('should return 0 for duration when first and last are the same', () => {
+    const tracker = new TimestampTracker();
+    const timestamp = '2024-01-01T10:00:00Z';
+    tracker.record(timestamp);
+    tracker.record(timestamp);
+
+    const duration = tracker.durationMs();
+    expect(duration).toBe(0);
+  });
+
+  it('should provide complete range information', () => {
+    const tracker = new TimestampTracker();
+    tracker.record('2024-01-01T10:00:00Z');
+    tracker.record('2024-01-01T10:05:00Z');
+
+    const range = tracker.range();
+    expect(range.first).toBe('2024-01-01T10:00:00Z');
+    expect(range.last).toBe('2024-01-01T10:05:00Z');
+    expect(range.minEpochMs).toBe(new Date('2024-01-01T10:00:00Z').getTime());
+    expect(range.maxEpochMs).toBe(new Date('2024-01-01T10:05:00Z').getTime());
+  });
+
+  it('should handle millisecond precision in timestamps', () => {
+    const tracker = new TimestampTracker();
+    tracker.record('2024-01-01T10:00:00.123Z');
+    tracker.record('2024-01-01T10:00:00.456Z');
+
+    const duration = tracker.durationMs();
+    expect(duration).toBe(333); // 456 - 123 = 333 ms
+  });
+
+  it('should handle numeric epoch timestamps (if converted to ISO)', () => {
+    const tracker = new TimestampTracker();
+    const isoString = new Date(1704067200000).toISOString();
+    tracker.record(isoString);
+
+    expect(tracker.getEpochMs(isoString)).toBe(1704067200000);
+  });
+});

package/src/timestamp-tracker.ts

@@ -0,0 +1,132 @@
+/**
+ * timestamp-tracker.ts
+ *
+ * Encapsulates timestamp tracking logic for Pi event stream processing.
+ * Safely parses ISO timestamps, tracks min/max values, and converts to epoch milliseconds.
+ */
+
+export interface TimestampRange {
+  first: string | null;
+  last: string | null;
+  minEpochMs: number | null;
+  maxEpochMs: number | null;
+}
+
+/**
+ * TimestampTracker manages timestamp observations from an event stream.
+ *
+ * Responsibilities:
+ * - Parse and record ISO 8601 timestamps
+ * - Track first and last observed timestamps (as ISO strings)
+ * - Track min/max epoch milliseconds for duration calculation
+ * - Provide safe conversion from ISO string to epoch milliseconds
+ * - Handle malformed timestamps gracefully
+ */
+export class TimestampTracker {
+  private first: string | null = null;
+  private last: string | null = null;
+  private minEpochMs: number | null = null;
+  private maxEpochMs: number | null = null;
+
+  /**
+   * Convert ISO 8601 string to epoch milliseconds.
+   * Returns null if the string cannot be parsed.
+   */
+  private parseToEpochMs(timestamp: string | null): number | null {
+    if (!timestamp) return null;
+    const epochMs = Date.parse(timestamp);
+    return Number.isFinite(epochMs) ? epochMs : null;
+  }
+
+  /**
+   * Record an ISO timestamp observation.
+   * Safely handles malformed timestamps by ignoring them.
+   */
+  record(timestamp: string | null): void {
+    if (!timestamp) return;
+
+    // Track first and last as ISO strings
+    if (this.first === null) {
+      this.first = timestamp;
+    }
+    this.last = timestamp;
+
+    // Track min/max as epoch milliseconds for duration calculation
+    const epochMs = this.parseToEpochMs(timestamp);
+    if (epochMs !== null) {
+      this.minEpochMs =
+        this.minEpochMs === null ? epochMs : Math.min(this.minEpochMs, epochMs);
+      this.maxEpochMs =
+        this.maxEpochMs === null ? epochMs : Math.max(this.maxEpochMs, epochMs);
+    }
+  }
+
+  /**
+   * Get epoch milliseconds for a given ISO timestamp string.
+   * Useful for extracting individual timestamp conversions.
+   */
+  getEpochMs(timestamp: string | null): number | null {
+    return this.parseToEpochMs(timestamp);
+  }
+
+  /**
+   * Get the first recorded timestamp (ISO string).
+   * Returns null if no timestamps have been recorded.
+   */
+  firstTimestamp(): string | null {
+    return this.first;
+  }
+
+  /**
+   * Get the last recorded timestamp (ISO string).
+   * Returns null if no timestamps have been recorded.
+   */
+  lastTimestamp(): string | null {
+    return this.last;
+  }
+
+  /**
+   * Get the first timestamp as epoch milliseconds.
+   * If first timestamp string exists but is malformed, attempts parse; otherwise
+   * uses tracked minEpochMs (which may be different if timestamps came from different sources).
+   */
+  firstEpochMs(): number | null {
+    if (this.minEpochMs !== null) return this.minEpochMs;
+    if (this.first !== null) return this.parseToEpochMs(this.first);
+    return null;
+  }
+
+  /**
+   * Get the last timestamp as epoch milliseconds.
+   * If last timestamp string exists but is malformed, attempts parse; otherwise
+   * uses tracked maxEpochMs (which may be different if timestamps came from different sources).
+   */
+  lastEpochMs(): number | null {
+    if (this.maxEpochMs !== null) return this.maxEpochMs;
+    if (this.last !== null) return this.parseToEpochMs(this.last);
+    return null;
+  }
+
+  /**
+   * Calculate duration in milliseconds between first and last recorded epochs.
+   * Returns null if either bound is missing or invalid.
+   */
+  durationMs(): number | null {
+    const first = this.firstEpochMs();
+    const last = this.lastEpochMs();
+    if (first === null || last === null) return null;
+    return Math.max(0, last - first);
+  }
+
+  /**
+   * Get complete timestamp range information.
+   */
+  range(): TimestampRange {
+    return {
+      first: this.first,
+      last: this.last,
+      minEpochMs: this.minEpochMs,
+      maxEpochMs: this.maxEpochMs,
+    };
+  }
+}

package/src/utils/failure-artifact-writer.ts

@@ -0,0 +1,187 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { StringDecoder } from 'node:string_decoder';
+import { Job } from '../kaseki-api-types';
+
+export type CleanupResult = {
+  attempted: boolean;
+  ok?: boolean;
+  detail?: string;
+};
+
+/**
+ * Handles writing failure artifacts (failure.json, analysis.md, result-summary.md, etc.)
+ * when a job fails before complete diagnostics are available.
+ */
+export class FailureArtifactWriter {
+  constructor(private resultsDir: string) {}
+
+  /**
+   * Write API finalization artifacts when job fails before container diagnostics.
+   */
+  writeFailureArtifacts(
+    job: Job,
+    cleanup: CleanupResult,
+    options?: { stdoutTail?: Buffer<ArrayBufferLike>; stderrTail?: Buffer<ArrayBufferLike>; lastStage?: string }
+  ): void {
+    if (job.status !== 'failed' && !job.failureClass) {
+      return;
+    }
+
+    const resultDir = path.join(this.resultsDir, job.id);
+    const now = (job.completedAt || new Date()).toISOString();
+    try {
+      fs.mkdirSync(resultDir, { recursive: true });
+
+      this.writeFailureJson(resultDir, job, now, cleanup);
+      this.writeResultSummary(resultDir, job, now);
+      this.writeAnalysis(resultDir, job, now, cleanup, options?.lastStage);
+      this.writeMetadata(resultDir, job, now);
+      this.writeStderrLog(resultDir, job, options?.stdoutTail, options?.stderrTail);
+    } catch {
+      // Best effort diagnostics; never mask the primary job failure.
+    }
+  }
+
+  private writeFailureJson(resultDir: string, job: Job, now: string, cleanup: CleanupResult): void {
+    const failurePath = path.join(resultDir, 'failure.json');
+    const shouldWriteFailure = !fs.existsSync(failurePath) || fs.statSync(failurePath).size === 0;
+    if (shouldWriteFailure) {
+      const payload = {
+        failureClass: job.failureClass || 'api_finalized',
+        error: job.error || 'Job failed before runner failure metadata was written',
+        exitCode: job.exitCode,
+        cancelledAt: job.failureClass === 'cancelled' ? now : undefined,
+        completedAt: now,
+        apiFinalized: true,
+        cleanup,
+      };
+      fs.writeFileSync(failurePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+    }
+  }
+
+  private writeResultSummary(resultDir: string, job: Job, now: string): void {
+    const summaryPath = path.join(resultDir, 'result-summary.md');
+    const shouldWriteSummary = !fs.existsSync(summaryPath) || fs.statSync(summaryPath).size === 0;
+    if (shouldWriteSummary) {
+      fs.writeFileSync(
+        summaryPath,
+        [
+          `# ${job.id} failed`,
+          '',
+          `Failure class: ${job.failureClass || 'unknown'}`,
+          `Exit code: ${job.exitCode ?? 'unknown'}`,
+          `Error: ${job.error || 'unknown'}`,
+          `Completed at: ${now}`,
+          '',
+        ].join('\n'),
+        'utf-8'
+      );
+    }
+  }
+
+  private writeAnalysis(resultDir: string, job: Job, now: string, cleanup: CleanupResult, lastStage?: string): void {
+    const analysisPath = path.join(resultDir, 'analysis.md');
+    const shouldWriteAnalysis = !fs.existsSync(analysisPath) || fs.statSync(analysisPath).size === 0;
+    if (shouldWriteAnalysis) {
+      fs.writeFileSync(
+        analysisPath,
+        [
+          `# Failure analysis for ${job.id}`,
+          '',
+          '## Completed work',
+          `- Job lifecycle entered: ${job.startedAt ? 'running' : 'queued'}`,
+          '- API finalization fallback written: yes',
+          '',
+          '## Failure classification',
+          `- Failure class: ${job.failureClass || 'unknown'}`,
+          `- Exit code: ${job.exitCode ?? 'unknown'}`,
+          `- Error: ${job.error || 'unknown'}`,
+          `- Last stage: ${lastStage || 'unknown'}`,
+          '',
+          '## Known warnings',
+          `- Container cleanup attempted: ${cleanup.attempted ? 'yes' : 'no'}`,
+          `- Container cleanup ok: ${cleanup.ok ? 'yes' : 'no'}`,
+          `- Cleanup detail: ${cleanup.detail || 'none'}`,
+          '',
+          `Completed at: ${now}`,
+          '',
+        ].join('\n'),
+        'utf-8'
+      );
+    }
+  }
+
+  private writeMetadata(resultDir: string, job: Job, now: string): void {
+    const metadataPath = path.join(resultDir, 'metadata.json');
+    const shouldWriteMetadata = !fs.existsSync(metadataPath) || fs.statSync(metadataPath).size === 0;
+    if (shouldWriteMetadata) {
+      const startedAt = job.startedAt?.toISOString();
+      const completedAt = job.completedAt?.toISOString() || now;
+      const durationSeconds =
+        job.startedAt && (job.completedAt || now)
+          ? Math.max(0, Math.round((new Date(completedAt).getTime() - job.startedAt.getTime()) / 1000))
+          : undefined;
+      const payload = {
+        id: job.id,
+        status: job.status,
+        timestamps: {
+          createdAt: job.createdAt.toISOString(),
+          startedAt,
+          completedAt,
+        },
+        durations: {
+          totalSeconds: durationSeconds,
+        },
+        runtime: {
+          timeoutSeconds: job.effectiveTimeoutSeconds,
+          pid: job.processId,
+          nodeVersion: process.version,
+          platform: process.platform,
+        },
+        env: {
+          taskMode: job.request.taskMode,
+          startupCheck: !!job.request.startupCheck,
+        },
+        failure: {
+          failureClass: job.failureClass || 'api_finalized',
+          error: job.error || 'Job failed before runner failure metadata was written',
+          exitCode: job.exitCode,
+        },
+      };
+      fs.writeFileSync(metadataPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
+    }
+  }
+
+  private writeStderrLog(
+    resultDir: string,
+    job: Job,
+    stdoutTail?: Buffer<ArrayBufferLike>,
+    stderrTail?: Buffer<ArrayBufferLike>
+  ): void {
+    const stderrPath = path.join(resultDir, 'stderr.log');
+    const shouldWriteStderr = !fs.existsSync(stderrPath) || fs.statSync(stderrPath).size === 0;
+    if (shouldWriteStderr) {
+      const decodedStderr = stderrTail ? this.decodeUtf8Tail(stderrTail) : '';
+      const decodedStdout = stdoutTail ? this.decodeUtf8Tail(stdoutTail) : '';
+      const content = [
+        'stderr fallback generated by API finalization',
+        `failureClass=${job.failureClass || 'unknown'} exitCode=${job.exitCode ?? 'unknown'}`,
+        `error=${job.error || 'unknown'}`,
+        '',
+        decodedStderr ? '--- captured stderr tail ---' : '',
+        decodedStderr,
+        decodedStdout ? '--- captured stdout tail ---' : '',
+        decodedStdout,
+      ]
+        .filter(Boolean)
+        .join('\n');
+      fs.writeFileSync(stderrPath, `${content}\n`, 'utf-8');
+    }
+  }
+
+  private decodeUtf8Tail(tail: Buffer<ArrayBufferLike>): string {
+    const decoder = new StringDecoder('utf8');
+    return decoder.end(tail);
+  }
+}