@cyanautomation/kaseki-agent 1.4.1

package/src/kaseki-api-service.ts

@@ -0,0 +1,192 @@
+import express from 'express';
+import type { Server } from 'http';
+import { loadConfig } from './kaseki-api-config';
+import { JobScheduler } from './job-scheduler';
+import { WebhookManager } from './webhook-manager';
+import { IdempotencyStore } from './idempotency-store';
+import { PreFlightValidator } from './pre-flight-validator';
+import { createApiRouter } from './kaseki-api-routes';
+import { createEventLogger } from './logger';
+import { ResultCache } from './result-cache';
+
+type ShutdownDeps = {
+  server: Server;
+  scheduler: Pick<JobScheduler, 'shutdown'>;
+  webhookManager: WebhookManager;
+  idempotencyStore: IdempotencyStore;
+  forceExitAfterMs?: number;
+  exit?: (code: number) => never;
+};
+
+export function createGracefulShutdown({
+  server,
+  scheduler,
+  webhookManager,
+  idempotencyStore,
+  forceExitAfterMs = 8000,
+  exit = process.exit,
+}: ShutdownDeps): (signal: string) => Promise<void> {
+  const logger = createEventLogger('kaseki-api');
+
+  return async (signal: string) => {
+    logger.info(`Received ${signal}, shutting down gracefully...`);
+
+    const hardTimeout = setTimeout(() => {
+      logger.error(
+        `Graceful shutdown timeout after ${forceExitAfterMs}ms, forcing exit`,
+      );
+      exit(1);
+    }, forceExitAfterMs);
+
+    try {
+      await new Promise<void>((resolve, reject) => {
+        server.close((err?: Error) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          logger.info('HTTP server closed');
+          resolve();
+        });
+      });
+
+      scheduler.shutdown();
+      logger.info('Job scheduler shutdown');
+
+      await webhookManager.shutdown();
+      logger.info('Webhook manager shutdown');
+
+      idempotencyStore.shutdown();
+      logger.info('Idempotency store shutdown');
+
+      exit(0);
+    } catch (err) {
+      logger.error('Error during graceful shutdown:', { error: String(err) });
+      exit(1);
+    } finally {
+      clearTimeout(hardTimeout);
+    }
+  };
+}
+
+export function assertSupportedNodeVersion(
+  version: string = process.versions.node,
+  minimumMajor: number = 24,
+): void {
+  const normalizedVersion = version.trim();
+  const isValidVersion = /^\d+(?:\.\d+){0,2}$/.test(normalizedVersion);
+  const major = Number.parseInt(normalizedVersion.split('.')[0] ?? '', 10);
+
+  const logger = createEventLogger('kaseki-api');
+  logger.info(`Node runtime detected: v${normalizedVersion}`);
+
+  if (!isValidVersion || !Number.isFinite(major) || major < minimumMajor) {
+    logger.error(
+      `Unsupported Node.js runtime v${normalizedVersion}. Kaseki API service requires Node.js >= ${minimumMajor}. Please upgrade Node or deploy the Docker image built from this repo's Dockerfile (node:24-bookworm-slim).`,
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * Main Kaseki API service.
+ */
+async function main(): Promise<void> {
+  const logger = createEventLogger('kaseki-api');
+
+  assertSupportedNodeVersion();
+
+  // Load configuration
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    logger.error('Configuration error:', { error: String(err) });
+    process.exit(1);
+  }
+
+  // Log detailed startup information
+  logger.event('service_startup_config', {
+    port: config.port,
+    logLevel: config.logLevel,
+    maxConcurrentRuns: config.maxConcurrentRuns,
+    resultsDir: config.resultsDir,
+    maxDiffBytes: config.maxDiffBytes,
+    agentTimeoutSeconds: config.agentTimeoutSeconds,
+    artifactCacheMaxEntries: config.artifactCacheMaxEntries,
+    artifactCacheTtlMs: config.artifactCacheTtlMs,
+    artifactCacheMaxFileBytes: config.artifactCacheMaxFileBytes,
+    nodeVersion: process.versions.node,
+    npmVersion: process.versions.npm || 'unknown',
+    platform: process.platform,
+    arch: process.arch,
+  });
+
+  // Log environment info
+  logger.event('service_startup_environment', {
+    pid: process.pid,
+    uptime: process.uptime(),
+    memoryUsage: JSON.stringify(process.memoryUsage()),
+    cpuUsage: JSON.stringify(process.cpuUsage()),
+  });
+
+  // Create Express app
+  const app = express();
+  app.use(express.json());
+
+  // Create shared artifact content cache
+  const artifactCache = new ResultCache({
+    maxEntries: config.artifactCacheMaxEntries,
+    ttlMs: config.artifactCacheTtlMs,
+    maxFileBytes: config.artifactCacheMaxFileBytes,
+  });
+
+  // Create webhook manager
+  const webhookManager = new WebhookManager(config.resultsDir);
+
+  // Create idempotency store
+  const idempotencyStore = new IdempotencyStore(config.resultsDir, 24);
+
+  // Create pre-flight validator
+  const preFlightValidator = new PreFlightValidator();
+
+  // Create scheduler
+  const scheduler = new JobScheduler(config, webhookManager, artifactCache);
+
+  // Mount API routes
+  const apiRouter = createApiRouter(scheduler, config, idempotencyStore, preFlightValidator, artifactCache);
+  app.use('/api', apiRouter);
+  app.use('/', apiRouter);
+
+  // Start server
+  const server = app.listen(config.port, () => {
+    logger.event('service_started', {
+      port: config.port,
+      logLevel: config.logLevel,
+      maxConcurrentRuns: config.maxConcurrentRuns,
+      resultsDir: config.resultsDir,
+      nodeVersion: process.versions.node,
+    });
+  });
+
+  // Graceful shutdown
+  const gracefulShutdown = createGracefulShutdown({ server, scheduler, webhookManager, idempotencyStore });
+
+  process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));
+  process.on('SIGINT', () => void gracefulShutdown('SIGINT'));
+
+  // Catch unhandled errors
+  process.on('uncaughtException', (err) => {
+    logger.error('Uncaught exception:', { error: String(err), stack: err instanceof Error ? err.stack : undefined });
+    process.exit(1);
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled rejection:', { reason: String(reason) });
+    process.exit(1);
+  });
+}
+
+if (!process.env.JEST_WORKER_ID) {
+  void main();
+}

package/src/kaseki-api-types.ts

@@ -0,0 +1,320 @@
+import { z } from 'zod';
+
+/**
+ * Webhook event types.
+ */
+export enum WebhookEventType {
+  JOB_SUBMITTED = 'job.submitted',
+  JOB_STARTED = 'job.started',
+  JOB_PROGRESS = 'job.progress',
+  JOB_COMPLETED = 'job.completed',
+  JOB_FAILED = 'job.failed',
+  JOB_CANCELLED = 'job.cancelled',
+}
+
+/**
+ * Webhook configuration for a run.
+ */
+export const WebhookConfigSchema = z.object({
+  url: z.string().url('Webhook URL must be valid'),
+  secret: z.string().min(16).optional().describe('HMAC secret for signature verification'),
+  events: z.array(z.nativeEnum(WebhookEventType)).optional().describe('Event types to deliver'),
+  retryPolicy: z.object({
+    maxAttempts: z.number().int().min(1).max(10).default(5),
+    initialDelayMs: z.number().int().min(100).max(5000).default(1000),
+    maxDelayMs: z.number().int().min(1000).max(60000).default(30000),
+  }).optional(),
+});
+
+export type WebhookConfig = z.infer<typeof WebhookConfigSchema>;
+
+/**
+ * Webhook payload event.
+ */
+export interface WebhookPayload {
+  eventType: WebhookEventType;
+  jobId: string;
+  timestamp: string; // ISO 8601
+  data: {
+    status?: 'queued' | 'running' | 'completed' | 'failed';
+    stage?: string;
+    elapsed?: number; // seconds
+    timeoutRiskPercent?: number;
+    exitCode?: number;
+    failureClass?: string;
+    error?: string;
+  };
+}
+
+/**
+ * Request tracing info.
+ */
+export const RequestTracingSchema = z.object({
+  correlationId: z.string().uuid().optional().describe('Correlation ID for tracking'),
+  requestId: z.string().uuid().optional().describe('Unique request ID'),
+});
+
+export type RequestTracing = z.infer<typeof RequestTracingSchema>;
+
+/**
+ * Request to trigger a new kaseki run.
+ */
+export const RunRequestSchema = z.object({
+  repoUrl: z.string().url('Repository URL must be valid').describe('Git repository URL'),
+  ref: z.string().min(1).default('main').describe('Git branch/tag/commit'),
+  taskPrompt: z.string().min(10).optional().describe('Task prompt for Pi agent'),
+  changedFilesAllowlist: z.array(z.string()).optional().describe('Space-separated file patterns'),
+  allowlist: z
+    .object({
+      include: z.array(z.string()).optional().describe('Alias for changedFilesAllowlist'),
+    })
+    .optional()
+    .describe('Controller-friendly allowlist alias'),
+  maxDiffBytes: z.number().int().positive().optional().describe('Max diff size in bytes'),
+  validationCommands: z.array(z.string()).optional().describe('Validation commands to run'),
+  validation: z
+    .object({
+      commands: z.array(z.string()).optional().describe('Alias for validationCommands'),
+    })
+    .optional()
+    .describe('Controller-friendly validation alias'),
+  taskMode: z.enum(['patch', 'inspect']).optional().describe('Task mode: patch or inspect'),
+  publishMode: z.enum(['none', 'branch', 'draft_pr']).optional().describe('Publishing mode after validation'),
+  startupCheck: z.boolean().optional().describe('Start a worker container and exit after boot/runtime checks'),
+  webhookConfig: WebhookConfigSchema.optional().describe('Webhook configuration for job events'),
+  tracing: RequestTracingSchema.optional().describe('Request tracing identifiers'),
+  idempotencyKey: z.string().uuid().optional().describe('Idempotency key for safe retries'),
+  timeoutSeconds: z.number().int().min(60).max(10800).optional().describe('Per-run timeout in seconds'),
+});
+
+export type RunRequest = z.infer<typeof RunRequestSchema>;
+
+/**
+ * Response after triggering a run.
+ */
+export interface RunResponse {
+  id: string; // kaseki-N instance ID
+  status: 'queued' | 'running' | 'completed' | 'failed';
+  createdAt: string; // ISO 8601
+  correlationId?: string; // Request correlation ID
+  requestId?: string; // Unique request ID
+  cached?: boolean; // True when returned from an idempotency replay
+  completedAt?: string; // ISO 8601 when replaying a terminal run
+  exitCode?: number;
+  failureClass?: string;
+  error?: string;
+}
+
+/**
+ * Structured progress information for a run.
+ */
+export interface StructuredProgress {
+  stage: string; // Required: current stage name
+  percentComplete?: number; // Optional: 0-100
+  message?: string; // Optional: detailed message
+  updatedAt?: string; // Optional: ISO 8601 timestamp
+}
+
+/**
+ * Status poll response.
+ */
+export interface StatusResponse {
+  id: string;
+  status: 'queued' | 'running' | 'completed' | 'failed';
+  progress?: StructuredProgress;
+  elapsedSeconds?: number;
+  timeoutRiskPercent?: number;
+  exitCode?: number;
+  failureClass?: string;
+  validationFailureReason?: string; // e.g., "validation_command_failed: npm run test (exit 1)"
+  qualityFailureReason?: string; // e.g., "max_diff_bytes: 250KB exceeds limit of 200KB"
+  error?: string;
+  resultDir?: string;
+  correlationId?: string; // Request correlation ID
+  requestId?: string; // Unique request ID
+  artifacts?: {
+    metadataJson: boolean;
+    analysisMd: boolean;
+    resultSummaryMd: boolean;
+    failureJson: boolean;
+    stderrLog: boolean;
+    availableFiles: string[];
+  };
+  diagnosticEntryPoint?: 'failure.json' | 'analysis.md' | 'result-summary.md';
+}
+
+/**
+ * Pre-flight validation check result.
+ */
+export interface ValidationCheck {
+  name: string; // e.g., 'repo-reachable', 'ref-exists', 'repo-size'
+  status: 'pass' | 'fail' | 'warning';
+  message: string;
+  detail?: string;
+}
+
+/**
+ * Pre-flight validation response.
+ */
+export interface ValidationResponse {
+  isValid: boolean;
+  checks: ValidationCheck[];
+  warnings: string[];
+  errors: string[];
+  estimatedDurationSeconds?: number;
+}
+
+/**
+ * Log retrieval response.
+ */
+export interface LogResponse {
+  logType: 'stdout' | 'stderr' | 'validation' | 'progress' | 'quality' | 'secret-scan';
+  content: string;
+  size: number;
+}
+
+/**
+ * Artifact download response.
+ */
+export interface ArtifactResponse {
+  file: string;
+  contentType: string;
+  size: number;
+  content?: string; // For text artifacts
+  url?: string; // For large artifacts, provide signed URL
+}
+
+export interface RunArtifactFileMetadata {
+  name: string;
+  size: number;
+  contentType: string;
+  available: boolean;
+}
+
+export interface RunArtifactsResponse {
+  id: string;
+  runStatus: 'queued' | 'running' | 'completed' | 'failed';
+  exitCode?: number;
+  artifacts: RunArtifactFileMetadata[];
+  recommended: string[];
+}
+
+/**
+ * Run analysis response (comprehensive summary).
+ */
+export interface AnalysisResponse {
+  id: string;
+  status: 'queued' | 'running' | 'completed' | 'failed';
+  createdAt: string;
+  completedAt?: string;
+  elapsedSeconds?: number;
+  exitCode?: number;
+  failureClass?: string;
+  metadata?: {
+    model?: string;
+    instance?: string;
+    repo?: string;
+    ref?: string;
+  };
+  changes?: {
+    changedFiles: string[];
+    diffSize: number;
+  };
+  validation?: {
+    passed: boolean;
+    commandResults: Array<{
+      command: string;
+      exitCode: number;
+      elapsed: number;
+    }>;
+  };
+  errors?: string[];
+}
+
+/**
+ * List runs response.
+ */
+export interface RunsListResponse {
+  runs: Array<{
+    id: string;
+    status: 'queued' | 'running' | 'completed' | 'failed';
+    createdAt: string;
+    completedAt?: string;
+    resultDir?: string;
+    exitCode?: number;
+    failureClass?: string;
+    error?: string;
+  }>;
+  total: number;
+  retention?: {
+    terminalJobIndexMaxEntries: number;
+    note: string;
+  };
+}
+
+export interface PreflightCheck {
+  name: string;
+  ok: boolean;
+  detail?: string;
+  remediation?: string;
+}
+
+export interface PreflightResponse {
+  status: 'ok' | 'degraded' | 'error';
+  timestamp: string;
+  checks: PreflightCheck[];
+  image?: string;
+  imageDigest?: string;
+  templateImage?: string;
+  templateImageDigest?: string;
+  templateDir?: string;
+  templateRef?: string;
+  resultsDir: string;
+  runtime?: {
+    nodeVersion: string;
+    uid?: number;
+    gid?: number;
+    groups?: number[];
+  };
+  docker?: {
+    version?: string;
+    clientVersion?: string;
+    serverVersion?: string;
+  };
+}
+
+/**
+ * Error response (RFC 7807 Problem Details).
+ */
+export interface ErrorResponse {
+  type: string; // e.g., 'https://api.kaseki.local/errors#unauthorized'
+  title: string; // e.g., 'Unauthorized'
+  status: number;
+  detail: string;
+  instance?: string; // Run ID if applicable
+}
+
+/**
+ * Internal job representation.
+ */
+export interface Job {
+  id: string; // kaseki-N instance ID
+  status: 'queued' | 'running' | 'completed' | 'failed';
+  request: RunRequest;
+  createdAt: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  exitCode?: number;
+  failureClass?: string;
+  error?: string;
+  resultDir?: string;
+  processId?: number;
+  timeout?: NodeJS.Timeout;
+  finalized?: boolean;
+  webhookConfig?: WebhookConfig; // Webhook delivery config
+  correlationId?: string; // Request correlation ID
+  requestId?: string; // Unique request ID
+  currentStage?: string; // Current job stage for progress tracking
+  idempotencyKey?: string; // Idempotency key for deduplication
+  effectiveTimeoutSeconds?: number; // Resolved timeout applied to this job
+}