@cyanautomation/kaseki-agent 1.4.1

package/src/utils/response-helpers.test.ts

@@ -0,0 +1,122 @@
+import { sendErrorResponse, buildStatusResponse, detectContentType } from './response-helpers';
+
+describe('response-helpers', () => {
+  describe('sendErrorResponse', () => {
+    it('should send a properly formatted error response', () => {
+      const mockResponse = {
+        body: null as any,
+        statusValue: 200,
+        status: function(code: number) {
+          this.statusValue = code;
+          return this;
+        },
+        json: function(data: any) {
+          this.body = data;
+        },
+      };
+
+      sendErrorResponse(mockResponse as any, 404, 'Not Found', 'Run not found: abc123');
+
+      expect(mockResponse.statusValue).toBe(404);
+      expect(mockResponse.body).toEqual({
+        type: 'https://api.kaseki.local/errors#not-found',
+        title: 'Not Found',
+        status: 404,
+        detail: 'Run not found: abc123',
+      });
+    });
+
+    it('should convert title to kebab-case type URL', () => {
+      const mockResponse = {
+        body: null as any,
+        statusValue: 200,
+        status: function(code: number) {
+          this.statusValue = code;
+          return this;
+        },
+        json: function(data: any) {
+          this.body = data;
+        },
+      };
+
+      sendErrorResponse(mockResponse as any, 400, 'Bad Request', 'Invalid input');
+
+      expect(mockResponse.body.type).toBe('https://api.kaseki.local/errors#bad-request');
+    });
+  });
+
+  describe('buildStatusResponse', () => {
+    it('should build a complete status response', () => {
+      const response = buildStatusResponse({
+        id: 'run-123',
+        status: 'running',
+        exitCode: 0,
+        failureClass: 'test-failure',
+        correlationId: 'corr-456',
+        requestId: 'req-789',
+        error: 'test error',
+        resultDir: '/results/run-123',
+      });
+
+      expect(response).toEqual({
+        id: 'run-123',
+        status: 'running',
+        exitCode: 0,
+        failureClass: 'test-failure',
+        correlationId: 'corr-456',
+        requestId: 'req-789',
+        error: 'test error',
+        resultDir: '/results/run-123',
+      });
+    });
+
+    it('should filter out null and undefined optional fields', () => {
+      const response = buildStatusResponse({
+        id: 'run-123',
+        status: 'completed',
+        exitCode: null,
+        failureClass: undefined,
+        error: null,
+      });
+
+      expect(response).toEqual({
+        id: 'run-123',
+        status: 'completed',
+      });
+    });
+
+    it('should handle optional fields being omitted', () => {
+      const response = buildStatusResponse({
+        id: 'run-123',
+        status: 'completed',
+      });
+
+      expect(response).toEqual({
+        id: 'run-123',
+        status: 'completed',
+      });
+    });
+  });
+
+  describe('detectContentType', () => {
+    it('should detect JSON content type', () => {
+      expect(detectContentType('metadata.json')).toBe('application/json');
+    });
+
+    it('should detect markdown content type', () => {
+      expect(detectContentType('result-summary.md')).toBe('text/markdown');
+    });
+
+    it('should detect JSONL content type', () => {
+      expect(detectContentType('progress.jsonl')).toBe('application/x-jsonl');
+    });
+
+    it('should detect diff content type', () => {
+      expect(detectContentType('git.diff')).toBe('text/plain');
+    });
+
+    it('should default to text/plain', () => {
+      expect(detectContentType('unknown.xyz')).toBe('text/plain');
+    });
+  });
+});

package/src/utils/response-helpers.ts

@@ -0,0 +1,101 @@
+import { Response } from 'express';
+import * as fs from 'fs';
+import { ErrorResponse, StatusResponse } from '../kaseki-api-types';
+
+/**
+ * Send a standardized error response.
+ * Consolidates error response generation across all endpoints.
+ */
+export function sendErrorResponse(
+  res: Response,
+  status: number,
+  title: string,
+  detail: string
+): void {
+  const response: ErrorResponse = {
+    type: 'https://api.kaseki.local/errors#' + title.toLowerCase().replace(/\s+/g, '-'),
+    title,
+    status,
+    detail,
+  };
+
+  res.status(status).json(response);
+}
+
+/**
+ * Build a StatusResponse from job metadata.
+ * Consolidates StatusResponse construction logic used in multiple routes.
+ */
+export function buildStatusResponse(jobData: {
+  id: string;
+  status: 'queued' | 'running' | 'completed' | 'failed';
+  exitCode?: number | null;
+  failureClass?: string | null;
+  correlationId?: string;
+  requestId?: string;
+  error?: string | null;
+  resultDir?: string;
+}): StatusResponse {
+  const response: StatusResponse = {
+    id: jobData.id,
+    status: jobData.status,
+    correlationId: jobData.correlationId,
+    requestId: jobData.requestId,
+    resultDir: jobData.resultDir,
+  };
+
+  // Only include optional fields if they are not null
+  if (jobData.exitCode !== null && jobData.exitCode !== undefined) {
+    response.exitCode = jobData.exitCode;
+  }
+  if (jobData.failureClass !== null && jobData.failureClass !== undefined) {
+    response.failureClass = jobData.failureClass;
+  }
+  if (jobData.error !== null && jobData.error !== undefined) {
+    response.error = jobData.error;
+  }
+
+  return response;
+}
+
+/**
+ * Send a file response with appropriate headers for artifact delivery.
+ * Handles Content-Type detection and streaming.
+ */
+export function sendFileResponse(
+  res: Response,
+  filePath: string,
+  fileName: string,
+  options?: { stream?: boolean }
+): void {
+  try {
+    const stat = fs.statSync(filePath);
+    const contentType = detectContentType(fileName);
+
+    res.setHeader('Content-Type', contentType);
+    res.setHeader('Content-Length', stat.size);
+    res.setHeader('Content-Disposition', `inline; filename="${fileName}"`);
+
+    if (options?.stream) {
+      const stream = fs.createReadStream(filePath);
+      stream.pipe(res);
+    } else {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      res.send(content);
+    }
+  } catch (error) {
+    sendErrorResponse(res, 500, 'Internal Server Error', `Failed to read file: ${fileName}`);
+  }
+}
+
+/**
+ * Detect Content-Type based on file extension.
+ * Used for artifact responses.
+ */
+export function detectContentType(fileName: string): string {
+  if (fileName.endsWith('.json')) return 'application/json';
+  if (fileName.endsWith('.md')) return 'text/markdown';
+  if (fileName.endsWith('.jsonl')) return 'application/x-jsonl';
+  if (fileName.endsWith('.diff')) return 'text/plain';
+  return 'text/plain';
+}

package/src/utils/route-helpers.ts

@@ -0,0 +1,30 @@
+/**
+ * Route helper utilities for common patterns across API routes.
+ */
+
+import { Response } from 'express';
+import { JobScheduler } from '../job-scheduler';
+import { Job } from '../kaseki-api-types';
+import { sendErrorResponse } from './response-helpers';
+
+/**
+ * Extract and validate a job ID from a request, sending an error response if not found.
+ * Consolidates the pattern used across artifact, log, and status routes.
+ *
+ * @param scheduler Job scheduler instance
+ * @param jobId Job ID to look up
+ * @param res Express response object (for error responses)
+ * @returns Job object if found, null if error response already sent
+ */
+export function getJobOrRespond(
+  scheduler: JobScheduler,
+  jobId: string,
+  res: Response
+): Job | null {
+  const job = scheduler.getJob(jobId);
+  if (!job) {
+    sendErrorResponse(res, 404, 'Not Found', `Run not found: ${jobId}`);
+    return null;
+  }
+  return job;
+}

package/src/utils/status-response-builder.ts

@@ -0,0 +1,159 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { Job } from '../kaseki-api-types';
+import { StatusResponse } from '../kaseki-api-types';
+import { KasekiApiConfig } from '../kaseki-api-config';
+import { JobScheduler } from '../job-scheduler';
+import { getRunArtifactMetadata } from '../run-artifact-metadata-cache';
+import { resolveInstanceExitCode, extractValidationFailureReason, extractQualityFailureReason } from '../instance-state-derivation';
+import { toStructuredProgress } from './progress-normalizer';
+import { readLastJsonlEvent } from './file-helpers';
+
+const STATUS_KEY_FILES = ['metadata.json', 'analysis.md', 'result-summary.md', 'failure.json', 'stderr.log'] as const;
+
+/**
+ * Builds StatusResponse objects with timing, progress, and artifact information.
+ * Encapsulates complex response building logic from status routes.
+ */
+export class StatusResponseBuilder {
+  constructor(
+    private scheduler: JobScheduler,
+    private config: KasekiApiConfig
+  ) {}
+
+  /**
+   * Build a complete StatusResponse for a job.
+   */
+  buildStatus(job: Job): StatusResponse {
+    const runDir = job.resultDir || path.join(this.config.resultsDir, job.id);
+    const exitCode = this.resolveExitCode(job, runDir);
+    const metadata = this.readMetadata(runDir);
+    const validationReason = extractValidationFailureReason(metadata);
+    const qualityReason = extractQualityFailureReason(metadata);
+    const response: StatusResponse = {
+      id: job.id,
+      status: job.status,
+      exitCode: exitCode ?? undefined,
+      failureClass: job.failureClass,
+      validationFailureReason: validationReason ?? undefined,
+      qualityFailureReason: qualityReason ?? undefined,
+      correlationId: job.correlationId,
+      requestId: job.requestId,
+      error: job.error,
+      resultDir: job.resultDir,
+    };
+
+    this.addTimingInfo(response, job);
+    this.addProgressInfo(response, job);
+    this.addArtifactInfo(response, job);
+
+    return response;
+  }
+
+  private addTimingInfo(response: StatusResponse, job: Job): void {
+    if (job.startedAt) {
+      const elapsed = (job.completedAt || new Date()).getTime() - job.startedAt.getTime();
+      response.elapsedSeconds = Math.round(elapsed / 1000);
+
+      const timeoutSeconds = job.effectiveTimeoutSeconds ?? this.config.agentTimeoutSeconds;
+      const timeoutMs = timeoutSeconds * 1000;
+      response.timeoutRiskPercent = Math.round((elapsed / timeoutMs) * 100);
+    }
+  }
+
+  private addProgressInfo(response: StatusResponse, job: Job): void {
+    if (job.status !== 'running') {
+      return;
+    }
+
+    try {
+      const progressFile = path.join(this.config.resultsDir, job.id, 'progress.jsonl');
+      const lastFileEvent = readLastJsonlEvent(progressFile);
+      if (lastFileEvent) {
+        const structuredProgress = toStructuredProgress(lastFileEvent);
+        if (structuredProgress) {
+          response.progress = structuredProgress;
+        }
+        return;
+      }
+
+      if (typeof this.scheduler.getLiveProgressEvents === 'function') {
+        const liveEvents = this.scheduler.getLiveProgressEvents(job.id, 1);
+        const lastEvent = liveEvents[liveEvents.length - 1];
+        if (lastEvent) {
+          const structuredProgress = toStructuredProgress(lastEvent, 'running');
+          if (structuredProgress) {
+            response.progress = structuredProgress;
+          }
+        }
+      }
+    } catch {
+      // Ignore progress file errors; status remains resilient
+    }
+  }
+
+  private addArtifactInfo(response: StatusResponse, job: Job): void {
+    if (!(job.status === 'completed' || job.status === 'failed')) {
+      return;
+    }
+
+    const runDir = job.resultDir || path.join(this.config.resultsDir, job.id);
+    const metadata = getRunArtifactMetadata(job.id, runDir, STATUS_KEY_FILES, true);
+    const keyFileAvailability = STATUS_KEY_FILES.reduce(
+      (acc, fileName) => {
+        acc[fileName] = metadata[fileName]?.exists === true && metadata[fileName].size > 0;
+        return acc;
+      },
+      {} as Record<(typeof STATUS_KEY_FILES)[number], boolean>
+    );
+
+    response.artifacts = {
+      metadataJson: keyFileAvailability['metadata.json'],
+      analysisMd: keyFileAvailability['analysis.md'],
+      resultSummaryMd: keyFileAvailability['result-summary.md'],
+      failureJson: keyFileAvailability['failure.json'],
+      stderrLog: keyFileAvailability['stderr.log'],
+      availableFiles: STATUS_KEY_FILES.filter((fileName) => keyFileAvailability[fileName]),
+    };
+
+    if (job.status === 'failed') {
+      if (keyFileAvailability['failure.json']) {
+        response.diagnosticEntryPoint = 'failure.json';
+      } else if (keyFileAvailability['analysis.md']) {
+        response.diagnosticEntryPoint = 'analysis.md';
+      } else if (keyFileAvailability['result-summary.md']) {
+        response.diagnosticEntryPoint = 'result-summary.md';
+      }
+    }
+  }
+
+  private readMetadata(runDir: string): any {
+    try {
+      const metadataPath = path.join(runDir, 'metadata.json');
+      if (fs.existsSync(metadataPath)) {
+        return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+      }
+    } catch {
+      // Ignore metadata read errors
+    }
+    return {};
+  }
+
+  private resolveExitCode(job: Job, runDir: string): number | null {
+    if (job.exitCode !== undefined && job.exitCode !== null) {
+      return job.exitCode;
+    }
+    if (!(job.status === 'completed' || job.status === 'failed')) {
+      return null;
+    }
+    try {
+      const metadataPath = path.join(runDir, 'metadata.json');
+      const metadata = fs.existsSync(metadataPath)
+        ? JSON.parse(fs.readFileSync(metadataPath, 'utf-8'))
+        : {};
+      return resolveInstanceExitCode(runDir, metadata);
+    } catch {
+      return null;
+    }
+  }
+}

package/src/utils/type-guards.ts

@@ -0,0 +1,52 @@
+/**
+ * Type guard utilities for common type checks.
+ * Reduces verbosity and provides reusable predicates across the codebase.
+ */
+
+/**
+ * Check if value is a string.
+ */
+export const isString = (value: unknown): value is string => typeof value === 'string';
+
+/**
+ * Check if value is a number.
+ */
+export const isNumber = (value: unknown): value is number => typeof value === 'number';
+
+/**
+ * Check if value is a boolean.
+ */
+export const isBoolean = (value: unknown): value is boolean => typeof value === 'boolean';
+
+/**
+ * Check if value is a record (plain object).
+ */
+export const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+
+/**
+ * Check if value is an array.
+ */
+export const isArray = (value: unknown): value is unknown[] => Array.isArray(value);
+
+/**
+ * Check if value is an array of strings.
+ */
+export const isStringArray = (value: unknown): value is string[] => {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+};
+
+/**
+ * Check if value is an array of objects (records).
+ */
+export const isRecordArray = (value: unknown): value is Record<string, unknown>[] => {
+  return Array.isArray(value) && value.every((item) => isRecord(item));
+};
+
+/**
+ * Check if value is an object with specific keys (shallow validation).
+ */
+export const hasKeys = (value: unknown, ...keys: string[]): value is Record<string, unknown> => {
+  return isRecord(value) && keys.every((key) => key in value);
+};

package/src/utils/utf8-helpers.ts

@@ -0,0 +1,102 @@
+/**
+ * UTF-8 safe string encoding/decoding utilities.
+ * Handles proper UTF-8 sequence detection to prevent breaking multi-byte characters.
+ */
+
+import * as fs from 'fs';
+
+/**
+ * Check if a byte is a UTF-8 continuation byte.
+ * Continuation bytes have the pattern 10xxxxxx (0x80-0xBF).
+ */
+function isUtf8ContinuationByte(byte: number): boolean {
+  return (byte & 0xc0) === 0x80;
+}
+
+/**
+ * Determine the expected length of a UTF-8 sequence from its leading byte.
+ */
+function utf8SequenceLength(leadingByte: number): number {
+  if ((leadingByte & 0x80) === 0) return 1; // Single-byte: 0xxxxxxx
+  if ((leadingByte & 0xe0) === 0xc0) return 2; // Two-byte: 110xxxxx
+  if ((leadingByte & 0xf0) === 0xe0) return 3; // Three-byte: 1110xxxx
+  if ((leadingByte & 0xf8) === 0xf0) return 4; // Four-byte: 11110xxx
+  return 1; // Invalid; treat as single-byte
+}
+
+/**
+ * Safely decode a buffer tail to UTF-8, avoiding partial UTF-8 sequences.
+ * If the buffer ends in the middle of a multi-byte UTF-8 sequence,
+ * the incomplete sequence is truncated.
+ *
+ * @param buffer Buffer to decode
+ * @returns UTF-8 string without incomplete sequences at the end
+ */
+export function decodeUtf8TailSafely(buffer: Buffer): string {
+  let end = buffer.length;
+  if (end > 0) {
+    let continuationCount = 0;
+    let candidateLead = end - 1;
+
+    // Count continuation bytes at the end
+    while (candidateLead >= 0 && isUtf8ContinuationByte(buffer[candidateLead])) {
+      continuationCount++;
+      candidateLead--;
+    }
+
+    if (candidateLead < 0) {
+      // All bytes are continuation bytes; skip all
+      end = 0;
+    } else {
+      const sequenceLength = utf8SequenceLength(buffer[candidateLead]);
+      const expectedContinuationCount = sequenceLength - 1;
+
+      // If the continuation byte count doesn't match the expected count, truncate
+      if (sequenceLength > 1 && continuationCount !== expectedContinuationCount) {
+        end = candidateLead;
+      }
+    }
+  }
+
+  return buffer.subarray(0, end).toString('utf-8');
+}
+
+/**
+ * Extract the last N lines from a string.
+ *
+ * @param content String content to extract from
+ * @param maxLines Maximum number of lines to return
+ * @returns Last N lines of the content (or entire content if fewer lines)
+ */
+export function tailLogByLines(content: string, maxLines: number): string {
+  if (maxLines <= 0) {
+    return '';
+  }
+
+  const lines = content.split(/\r?\n/);
+  if (lines.length <= maxLines) {
+    return content;
+  }
+  return lines.slice(-maxLines).join('\n');
+}
+
+/**
+ * Read the tail bytes of a file into a buffer.
+ * Useful for reading last N bytes of a large file without loading entire file.
+ *
+ * @param logFile Path to the file
+ * @param size Total size of the file (from fs.statSync)
+ * @param maxSize Maximum bytes to read
+ * @returns Buffer containing the tail bytes
+ */
+export function readTailBytes(logFile: string, size: number, maxSize: number): Buffer {
+  const truncated = Buffer.alloc(maxSize);
+  const fd = fs.openSync(logFile, 'r');
+  try {
+    fs.readSync(fd, truncated, 0, maxSize, size - maxSize);
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return truncated;
+}