@cyanautomation/kaseki-agent 1.4.1

package/src/result-cache.test.ts

@@ -0,0 +1,195 @@
+import { ResultCache } from './result-cache';
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('ResultCache', () => {
+  let cache: ResultCache;
+  let testFile: string;
+  let testDir: string;
+
+  beforeEach(() => {
+    cache = new ResultCache(3, 1000); // 3 entries, 1 sec TTL for testing
+    testDir = fs.mkdtempSync(path.join('/tmp', 'kaseki-cache-test-'));
+    testFile = path.join(testDir, 'test.txt');
+    fs.writeFileSync(testFile, 'test content');
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  test('API contract: cache miss returns null, increments miss counter, and does not crash', () => {
+    const statsBefore = cache.getStats();
+
+    let content: string | null = null;
+    expect(() => {
+      content = cache.getOrLoad('/non/existent/file');
+    }).not.toThrow();
+
+    expect(content).toBeNull();
+
+    const statsAfter = cache.getStats();
+    expect(statsAfter.entries).toBe(statsBefore.entries);
+    expect(statsAfter.bytes).toBe(statsBefore.bytes);
+    expect(statsAfter.misses).toBe(statsBefore.misses + 1);
+  });
+
+  test('reloads content when file is updated within TTL', () => {
+    jest.useFakeTimers();
+    const baseTime = new Date('2026-01-01T00:00:00.000Z');
+    jest.setSystemTime(baseTime);
+
+    const initialContent = cache.getOrLoad(testFile);
+    expect(initialContent).toBe('test content');
+
+    jest.setSystemTime(new Date(baseTime.getTime() + 100));
+    fs.writeFileSync(testFile, 'modified content');
+
+    const reloadedContent = cache.getOrLoad(testFile);
+    expect(reloadedContent).toBe('modified content');
+
+    jest.useRealTimers();
+  });
+
+  test('returns cached content when file is unchanged within TTL', () => {
+    jest.useFakeTimers();
+    const baseTime = new Date('2026-01-01T00:00:00.000Z');
+    jest.setSystemTime(baseTime);
+
+    const initialContent = cache.getOrLoad(testFile);
+    expect(initialContent).toBe('test content');
+
+    jest.setSystemTime(new Date(baseTime.getTime() + 999));
+    const cachedContent = cache.getOrLoad(testFile);
+    expect(cachedContent).toBe('test content');
+
+    jest.useRealTimers();
+  });
+
+  test('expires cached entries after TTL using deterministic time control', () => {
+    jest.useFakeTimers();
+    const baseTime = new Date('2026-01-01T00:00:00.000Z');
+    jest.setSystemTime(baseTime);
+
+    const initialContent = cache.getOrLoad(testFile);
+    expect(initialContent).toBe('test content');
+
+    jest.setSystemTime(new Date(baseTime.getTime() + 1001));
+    fs.writeFileSync(testFile, 'modified content');
+
+    const reloadedContent = cache.getOrLoad(testFile);
+    expect(reloadedContent).toBe('modified content');
+
+    jest.useRealTimers();
+  });
+
+  test('evicts oldest entry when cache is full', () => {
+    const files = [];
+    for (let i = 0; i < 4; i++) {
+      const file = path.join(testDir, `file-${i}.txt`);
+      fs.writeFileSync(file, `content-${i}`);
+      const initialContent = cache.getOrLoad(file);
+      expect(initialContent).toBe(`content-${i}`);
+      files.push(file);
+    }
+
+    // First file should be evicted after initial load of all entries.
+    fs.writeFileSync(files[0], 'evicted content');
+    const content = cache.getOrLoad(files[0]);
+    expect(content).toBe('evicted content');
+  });
+
+  test('clears cache for a job', () => {
+    const file = path.join(testDir, 'kaseki-1/data.txt');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, 'job data');
+
+    cache.getOrLoad(file);
+    cache.clearForJob('kaseki-1');
+
+    // Modify file and reload
+    fs.writeFileSync(file, 'modified job data');
+    const content = cache.getOrLoad(file);
+    expect(content).toBe('modified job data');
+  });
+
+  test('clears cache entries for POSIX-style path strings by job segment', () => {
+    const internalCache = (cache as unknown as { cache: Map<string, { content: string; timestamp: number; size: number; mtimeMs?: number; inode?: number }> }).cache;
+    internalCache.set('/tmp/jobs/kaseki-1/result.txt', { content: 'a', timestamp: Date.now(), size: 1 });
+    internalCache.set('/tmp/jobs/kaseki-10/result.txt', { content: 'b', timestamp: Date.now(), size: 1 });
+
+    cache.clearForJob('kaseki-1');
+
+    expect(internalCache.has('/tmp/jobs/kaseki-1/result.txt')).toBe(false);
+    expect(internalCache.has('/tmp/jobs/kaseki-10/result.txt')).toBe(true);
+  });
+
+  test('clears cache entries for Windows-style path strings by job segment', () => {
+    const internalCache = (cache as unknown as { cache: Map<string, { content: string; timestamp: number; size: number; mtimeMs?: number; inode?: number }> }).cache;
+    internalCache.set('C:\\kaseki\\runs\\kaseki-1\\result.txt', {
+      content: 'a',
+      timestamp: Date.now(),
+      size: 1,
+    });
+    internalCache.set('C:\\kaseki\\runs\\kaseki-10\\result.txt', {
+      content: 'b',
+      timestamp: Date.now(),
+      size: 1,
+    });
+
+    cache.clearForJob('kaseki-1');
+
+    expect(internalCache.has('C:\\kaseki\\runs\\kaseki-1\\result.txt')).toBe(false);
+    expect(internalCache.has('C:\\kaseki\\runs\\kaseki-10\\result.txt')).toBe(true);
+  });
+
+  test('provides cache statistics', () => {
+    cache.getOrLoad(testFile);
+
+    const stats = cache.getStats();
+    expect(stats.entries).toBe(1);
+    expect(stats.bytes).toBeGreaterThan(0);
+    expect(stats.hits).toBe(0);
+    expect(stats.misses).toBe(1);
+    expect(stats.maxEntries).toBe(3);
+    expect(stats.ttlMs).toBe(1000);
+    expect(stats.maxFileBytes).toBe(10 * 1024 * 1024);
+  });
+
+  test('tracks cache hits and misses', () => {
+    expect(cache.getOrLoad(testFile)).toBe('test content');
+    expect(cache.getOrLoad(testFile)).toBe('test content');
+
+    expect(cache.getStats()).toMatchObject({ hits: 1, misses: 1 });
+  });
+
+  test('honors configured max file bytes by not caching oversized files', () => {
+    const smallCache = new ResultCache({ maxEntries: 3, ttlMs: 1000, maxFileBytes: 4 });
+    const content = smallCache.getOrLoad(testFile);
+    expect(content).toBe('test content');
+    expect(smallCache.getStats()).toMatchObject({ entries: 0, bytes: 0, hits: 0, misses: 1 });
+  });
+
+  test('honors zero max entries by disabling caching', () => {
+    const disabledCache = new ResultCache({ maxEntries: 0, ttlMs: 1000, maxFileBytes: 100 });
+    expect(disabledCache.getOrLoad(testFile)).toBe('test content');
+    expect(disabledCache.getOrLoad(testFile)).toBe('test content');
+    expect(disabledCache.getStats()).toMatchObject({ entries: 0, hits: 0, misses: 2, maxEntries: 0 });
+  });
+
+  test('clears all cache', () => {
+    const initialContent = cache.getOrLoad(testFile);
+    expect(initialContent).toBe('test content');
+
+    cache.clearAll();
+
+    const stats = cache.getStats();
+    expect(stats.entries).toBe(0);
+    expect(stats.bytes).toBe(0);
+
+    // Mutate file after clearAll to prove subsequent load comes from disk, not stale cache.
+    fs.writeFileSync(testFile, 'content after clear');
+    const reloadedContent = cache.getOrLoad(testFile);
+    expect(reloadedContent).toBe('content after clear');
+  });
+});

package/src/result-cache.ts

@@ -0,0 +1,181 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Cached artifact entry.
+ */
+export interface ResultCacheOptions {
+  maxEntries?: number;
+  ttlMs?: number;
+  maxFileBytes?: number;
+}
+
+export interface ResultCacheStats {
+  entries: number;
+  bytes: number;
+  hits: number;
+  misses: number;
+  maxEntries: number;
+  ttlMs: number;
+  maxFileBytes: number;
+}
+
+interface CacheEntry {
+  content: string;
+  timestamp: number;
+  size: number;
+  mtimeMs: number;
+  inode?: number;
+}
+
+/**
+ * Result cache for lazily loading and caching kaseki artifacts.
+ * Reduces filesystem reads for frequently accessed files.
+ */
+export class ResultCache {
+  private cache = new Map<string, CacheEntry>();
+  private readonly maxEntries: number;
+  private readonly ttlMs: number;
+  private readonly maxFileBytes: number;
+  private hits = 0;
+  private misses = 0;
+
+  constructor(maxEntries?: number, ttlMs?: number, maxFileBytes?: number);
+  constructor(options?: ResultCacheOptions);
+  constructor(
+    maxEntriesOrOptions: number | ResultCacheOptions = 20,
+    ttlMs = 5 * 60 * 1000,
+    maxFileBytes = 10 * 1024 * 1024
+  ) {
+    if (typeof maxEntriesOrOptions === 'object') {
+      this.maxEntries = maxEntriesOrOptions.maxEntries ?? 20;
+      this.ttlMs = maxEntriesOrOptions.ttlMs ?? 5 * 60 * 1000;
+      this.maxFileBytes = maxEntriesOrOptions.maxFileBytes ?? 10 * 1024 * 1024;
+    } else {
+      this.maxEntries = maxEntriesOrOptions;
+      this.ttlMs = ttlMs;
+      this.maxFileBytes = maxFileBytes;
+    }
+  }
+
+  /**
+   * Get or load a file from disk.
+   */
+  getOrLoad(filePath: string): string | null {
+    let fileStat: fs.Stats | undefined;
+
+    // Check cache
+    const cached = this.cache.get(filePath);
+    if (cached) {
+      const age = Date.now() - cached.timestamp;
+      if (age < this.ttlMs) {
+        try {
+          fileStat = fs.statSync(filePath);
+          const inode = typeof fileStat.ino === 'number' ? fileStat.ino : undefined;
+          const unchanged =
+            fileStat.mtimeMs === cached.mtimeMs &&
+            fileStat.size === cached.size &&
+            (cached.inode === undefined || inode === cached.inode);
+
+          if (unchanged) {
+            this.hits += 1;
+            return cached.content;
+          }
+        } catch {
+          // Fall through to reload from disk
+        }
+      } else {
+        // Expired, remove from cache
+        this.cache.delete(filePath);
+      }
+    }
+
+    this.misses += 1;
+
+    // Load from disk
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+
+    try {
+      const stat = fileStat ?? fs.statSync(filePath);
+      const content = fs.readFileSync(filePath, 'utf-8');
+
+      if (this.maxEntries > 0 && stat.size <= this.maxFileBytes) {
+        this.set(filePath, content, stat.size, stat.mtimeMs, typeof stat.ino === 'number' ? stat.ino : undefined);
+      }
+
+      return content;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Set a cache entry.
+   */
+  private set(filePath: string, content: string, size: number, mtimeMs: number, inode?: number): void {
+    if (this.maxEntries <= 0) {
+      return;
+    }
+
+    // Evict oldest entry if cache is full
+    if (this.cache.size >= this.maxEntries) {
+      const oldest = Array.from(this.cache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp)[0];
+      if (oldest) {
+        this.cache.delete(oldest[0]);
+      }
+    }
+
+    this.cache.set(filePath, {
+      content,
+      timestamp: Date.now(),
+      size,
+      mtimeMs,
+      inode,
+    });
+  }
+
+  /**
+   * Clear cache for a job (e.g., when cleaning up after completion).
+   */
+  clearForJob(jobId: string): void {
+    const normalizedJobId = path.basename(path.normalize(jobId));
+
+    for (const key of this.cache.keys()) {
+      const normalizedKey = path.normalize(key);
+      const keySegments = normalizedKey.split(/[\\/]+/).filter(Boolean);
+      const hasJobSegment = keySegments.includes(normalizedJobId);
+
+      if (hasJobSegment) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Clear all cache.
+   */
+  clearAll(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics.
+   */
+  getStats(): ResultCacheStats {
+    let bytes = 0;
+    for (const entry of this.cache.values()) {
+      bytes += entry.size;
+    }
+    return {
+      entries: this.cache.size,
+      bytes,
+      hits: this.hits,
+      misses: this.misses,
+      maxEntries: this.maxEntries,
+      ttlMs: this.ttlMs,
+      maxFileBytes: this.maxFileBytes,
+    };
+  }
+}

package/src/routes/artifact-routes.ts

@@ -0,0 +1,169 @@
+import { Router, Request, Response } from 'express';
+import * as path from 'path';
+import * as fs from 'fs';
+import { JobScheduler } from '../job-scheduler';
+import { ResultCache } from '../result-cache';
+import { KasekiApiConfig } from '../kaseki-api-config';
+import { ArtifactResponse, RunArtifactsResponse } from '../kaseki-api-types';
+import { sendErrorResponse } from '../utils/response-helpers';
+import { getJobOrRespond } from '../utils/route-helpers';
+import { getRunArtifactMetadata } from '../run-artifact-metadata-cache';
+
+const ALWAYS_SAFE_SUMMARY_ARTIFACTS = [
+  'git.diff',
+  'metadata.json',
+  'analysis.md',
+  'result-summary.md',
+  'pi-events.jsonl',
+  'pi-summary.json',
+  'progress.log',
+] as const;
+
+const FAILURE_ONLY_DIAGNOSTICS_ARTIFACTS = [
+  'failure.json',
+  'stderr.log',
+  'stdout.log',
+  'validation.log',
+  'quality.log',
+] as const;
+
+function isTerminalJobStatus(status: 'queued' | 'running' | 'completed' | 'failed'): boolean {
+  return status === 'completed' || status === 'failed';
+}
+
+function artifactContentType(fileName: string): string {
+  if (fileName.endsWith('.json')) return 'application/json';
+  if (fileName.endsWith('.md')) return 'text/markdown';
+  return 'text/plain';
+}
+
+export function readArtifactContent(
+  filePath: string,
+  jobStatus: 'queued' | 'running' | 'completed' | 'failed',
+  cache: ResultCache
+): string | null {
+  if (!isTerminalJobStatus(jobStatus)) {
+    try {
+      return fs.readFileSync(filePath, 'utf-8');
+    } catch {
+      return null;
+    }
+  }
+  return cache.getOrLoad(filePath);
+}
+
+/**
+ * Create artifact-related routes (list artifacts, download artifacts).
+ */
+export function createArtifactRoutes(scheduler: JobScheduler, config: KasekiApiConfig, cache: ResultCache): Router {
+  const router = Router();
+
+  /**
+   * GET /api/results/:id/:file - Download artifact.
+   */
+  router.get('/results/:id/:file', (req: Request, res: Response) => {
+    const job = getJobOrRespond(scheduler, req.params.id, res);
+    if (!job) {
+      return;
+    }
+
+    const fileName = req.params.file;
+    const allowedFiles = [...ALWAYS_SAFE_SUMMARY_ARTIFACTS, ...FAILURE_ONLY_DIAGNOSTICS_ARTIFACTS];
+
+    if (!allowedFiles.some((allowedFile) => allowedFile === fileName)) {
+      return sendErrorResponse(
+        res,
+        400,
+        'Bad Request',
+        `Artifact not allowed: ${fileName}. Allowed: ${allowedFiles.join(', ')}`
+      );
+    }
+
+    if (FAILURE_ONLY_DIAGNOSTICS_ARTIFACTS.some((artifact) => artifact === fileName) && job.status !== 'failed') {
+      return sendErrorResponse(
+        res,
+        400,
+        'Bad Request',
+        `Artifact only available for failed runs: ${fileName}`
+      );
+    }
+
+    try {
+      const filePath = path.join(config.resultsDir, job.id, fileName);
+
+      if (!fs.existsSync(filePath)) {
+        return sendErrorResponse(res, 404, 'Not Found', `Artifact not found: ${fileName}`);
+      }
+
+      const contentType = artifactContentType(fileName);
+
+      // Read from disk for non-terminal jobs; cache only terminal artifacts.
+      const content = readArtifactContent(filePath, job.status, cache);
+      if (content === null) {
+        return sendErrorResponse(res, 500, 'Internal Server Error', `Failed to read artifact: ${fileName}`);
+      }
+
+      const stat = fs.statSync(filePath);
+
+      const response: ArtifactResponse = {
+        file: fileName,
+        contentType,
+        size: stat.size,
+        content,
+      };
+
+      res.setHeader('Content-Type', contentType);
+      res.json(response);
+    } catch (err) {
+      sendErrorResponse(
+        res,
+        500,
+        'Internal Server Error',
+        `Failed to read artifact: ${(err as Error).message}`
+      );
+    }
+  });
+
+  /**
+   * GET /api/runs/:id/artifacts - Enumerate allowlisted artifacts and availability.
+   */
+  router.get('/runs/:id/artifacts', (req: Request, res: Response) => {
+    const job = getJobOrRespond(scheduler, req.params.id, res);
+    if (!job) {
+      return;
+    }
+
+    const runDir = job.resultDir || path.join(config.resultsDir, job.id);
+    const allowedFiles = [...ALWAYS_SAFE_SUMMARY_ARTIFACTS, ...FAILURE_ONLY_DIAGNOSTICS_ARTIFACTS];
+
+    const metadata = getRunArtifactMetadata(job.id, runDir, allowedFiles, isTerminalJobStatus(job.status));
+    const artifacts = allowedFiles.map((fileName) => {
+      const artifactMetadata = metadata[fileName] ?? { exists: false, size: 0 };
+      const isFailureOnly = FAILURE_ONLY_DIAGNOSTICS_ARTIFACTS.some((artifact) => artifact === fileName);
+      const hasContent = artifactMetadata.exists && artifactMetadata.size > 0;
+      const available = hasContent && (!isFailureOnly || job.status === 'failed');
+
+      return {
+        name: fileName,
+        size: artifactMetadata.size,
+        contentType: artifactContentType(fileName),
+        available,
+      };
+    });
+
+    const response: RunArtifactsResponse = {
+      id: job.id,
+      runStatus: job.status,
+      exitCode: job.exitCode,
+      artifacts,
+      recommended:
+        job.status === 'failed'
+          ? ['failure.json', 'stderr.log', 'stdout.log', 'validation.log', 'quality.log']
+          : ['result-summary.md', 'metadata.json', 'pi-summary.json', 'git.diff'],
+    };
+
+    res.json(response);
+  });
+
+  return router;
+}