@kadi.build/core 0.8.0 → 0.11.0

package/src/process-manager.ts

@@ -0,0 +1,821 @@
+/**
+ * ProcessManager for kadi-core
+ *
+ * Manages background child processes with three execution modes:
+ *
+ * - **headless**: Fire-and-forget. No communication channel.
+ * - **piped**: stdout/stderr are streamed back and buffered.
+ * - **bridge**: Full JSON-RPC stdio bridge (Content-Length framing).
+ *
+ * Primary use case: Running long tasks (builds, deploys, inference) in the
+ * background so the main agent's event loop stays free for broker heartbeats.
+ *
+ * @example
+ * ```typescript
+ * import { ProcessManager } from '@kadi.build/core';
+ *
+ * const pm = new ProcessManager();
+ *
+ * // Headless build
+ * const build = await pm.spawn('build', {
+ *   command: 'docker', args: ['build', '.'], mode: 'headless',
+ * });
+ * const status = pm.getStatus('build');
+ *
+ * // Piped deploy with live output
+ * const deploy = await pm.spawn('deploy', {
+ *   command: 'kadi', args: ['deploy'], mode: 'piped',
+ * });
+ * deploy.on('stdout', (data) => console.log(data));
+ *
+ * // Bridge mode for interactive workers
+ * const worker = await pm.spawn('worker', {
+ *   command: 'python3', args: ['worker.py'], mode: 'bridge',
+ * });
+ * const result = await worker.request('run-inference', { prompt: 'hello' });
+ * ```
+ */
+
+import { spawn, type ChildProcess } from 'child_process';
+import { EventEmitter } from 'events';
+import type {
+  ProcessMode,
+  ProcessState,
+  SpawnOptions,
+  ProcessInfo,
+  ProcessExitInfo,
+  ProcessOutput,
+  ProcessListOptions,
+  ProcessPruneOptions,
+} from './types.js';
+import { KadiError } from './errors.js';
+import { StdioMessageReader, StdioMessageWriter, type JsonRpcNotification } from './stdio-framing.js';
+import * as protocol from './protocol.js';
+
+// ═══════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════
+
+const DEFAULT_KILL_GRACE_PERIOD = 5000;
+const DEFAULT_MAX_OUTPUT_BUFFER = 10 * 1024 * 1024; // 10 MB
+
+// ═══════════════════════════════════════════════════════════════════════
+// MANAGED PROCESS
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * A handle to a spawned background process.
+ *
+ * Provides event subscription, lifecycle management, and (in bridge mode)
+ * JSON-RPC request/response communication.
+ */
+export class ManagedProcess extends EventEmitter {
+  /** Unique identifier */
+  readonly id: string;
+
+  /** OS process ID */
+  readonly pid: number;
+
+  /** Execution mode */
+  readonly mode: ProcessMode;
+
+  /** Internal state */
+  private _state: ProcessState = 'running';
+  private _exitCode: number | null = null;
+  private _signal: string | null = null;
+  private _startedAt: Date;
+  private _endedAt: Date | null = null;
+
+  /** Command info for getInfo() */
+  private readonly _command: string;
+  private readonly _args: string[];
+  private readonly _cwd: string;
+
+  /** Output buffering (piped mode) */
+  private _stdout = '';
+  private _stderr = '';
+  private readonly _maxOutputBuffer: number;
+
+  /** Bridge mode internals */
+  private _reader: StdioMessageReader | null = null;
+  private _writer: StdioMessageWriter | null = null;
+  private _bridgeIdCounter = 1;
+
+  /** The underlying child process */
+  private readonly _proc: ChildProcess;
+
+  /** Timeout timer for auto-kill */
+  private _timeoutTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /** Kill grace period */
+  private readonly _killGracePeriod: number;
+
+  /** Waiters for the exit event */
+  private readonly _exitWaiters: Array<{
+    resolve: (info: ProcessExitInfo) => void;
+  }> = [];
+
+  constructor(
+    id: string,
+    proc: ChildProcess,
+    options: SpawnOptions,
+  ) {
+    super();
+
+    this.id = id;
+    this._proc = proc;
+    this.pid = proc.pid!;
+    this.mode = options.mode;
+    this._command = options.command;
+    this._args = options.args ?? [];
+    this._cwd = options.cwd ?? process.cwd();
+    this._startedAt = new Date();
+    this._killGracePeriod = options.killGracePeriod ?? DEFAULT_KILL_GRACE_PERIOD;
+    this._maxOutputBuffer = options.maxOutputBuffer ?? DEFAULT_MAX_OUTPUT_BUFFER;
+
+    // Set up auto-kill timeout
+    if (options.timeout && options.timeout > 0) {
+      this._timeoutTimer = setTimeout(() => {
+        this.kill().catch(() => {});
+      }, options.timeout);
+    }
+
+    // Set up process exit handler
+    proc.on('exit', (code, signal) => {
+      this.handleExit(code, signal);
+    });
+
+    proc.on('error', (error) => {
+      if (this._state === 'running') {
+        this._state = 'errored';
+        this._endedAt = new Date();
+        this.emit('error', error);
+        this.resolveExitWaiters();
+      }
+    });
+
+    // Set up output streaming based on mode
+    if (options.mode === 'piped') {
+      this.setupPipedMode(proc);
+    } else if (options.mode === 'bridge') {
+      this.setupBridgeMode(proc, options);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // STATE GETTERS
+  // ─────────────────────────────────────────────────────────────────
+
+  /** Current lifecycle state */
+  get state(): ProcessState { return this._state; }
+
+  /** Whether the process is still running */
+  get isRunning(): boolean { return this._state === 'running'; }
+
+  // ─────────────────────────────────────────────────────────────────
+  // MODE SETUP
+  // ─────────────────────────────────────────────────────────────────
+
+  private setupPipedMode(proc: ChildProcess): void {
+    if (proc.stdout) {
+      proc.stdout.on('data', (chunk: Buffer) => {
+        const str = chunk.toString('utf-8');
+        this.appendOutput('stdout', str);
+        this.emit('stdout', str);
+      });
+    }
+
+    if (proc.stderr) {
+      proc.stderr.on('data', (chunk: Buffer) => {
+        const str = chunk.toString('utf-8');
+        this.appendOutput('stderr', str);
+        this.emit('stderr', str);
+      });
+    }
+  }
+
+  private setupBridgeMode(proc: ChildProcess, _options: SpawnOptions): void {
+    if (!proc.stdin || !proc.stdout) {
+      throw new KadiError(
+        'Failed to get stdio streams for bridge mode',
+        'PROCESS_BRIDGE_ERROR',
+        { processId: this.id },
+      );
+    }
+
+    this._reader = new StdioMessageReader(proc.stdout);
+    this._writer = new StdioMessageWriter(proc.stdin);
+
+    // Route notifications to event emitter
+    this._reader.setNotificationHandler((notification: JsonRpcNotification) => {
+      this.emit('notification', notification.method, notification.params);
+    });
+
+    // Also capture stderr for debugging
+    if (proc.stderr) {
+      proc.stderr.on('data', (chunk: Buffer) => {
+        const str = chunk.toString('utf-8');
+        this.appendOutput('stderr', str);
+        this.emit('stderr', str);
+      });
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // OUTPUT BUFFERING
+  // ─────────────────────────────────────────────────────────────────
+
+  private appendOutput(stream: 'stdout' | 'stderr', data: string): void {
+    if (stream === 'stdout') {
+      this._stdout += data;
+      if (this._stdout.length > this._maxOutputBuffer) {
+        // Ring buffer: keep the most recent data
+        this._stdout = this._stdout.slice(-this._maxOutputBuffer);
+      }
+    } else {
+      this._stderr += data;
+      if (this._stderr.length > this._maxOutputBuffer) {
+        this._stderr = this._stderr.slice(-this._maxOutputBuffer);
+      }
+    }
+  }
+
+  /**
+   * Get all buffered output.
+   * Only available in piped and bridge modes.
+   */
+  getOutput(): ProcessOutput {
+    return { stdout: this._stdout, stderr: this._stderr };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // BRIDGE MODE API
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Send a JSON-RPC request and await the response.
+   * Only available in bridge mode.
+   *
+   * @param method - The RPC method to invoke
+   * @param params - Parameters to send
+   * @param timeout - Timeout in ms (default: 600000)
+   * @returns The result from the response
+   *
+   * @example
+   * ```typescript
+   * const result = await proc.request('run-inference', { prompt: 'hello' });
+   * ```
+   */
+  async request(method: string, params?: unknown, timeout?: number): Promise<unknown> {
+    if (this.mode !== 'bridge') {
+      throw new KadiError(
+        'request() is only available in bridge mode',
+        'PROCESS_BRIDGE_ERROR',
+        { processId: this.id, mode: this.mode },
+      );
+    }
+
+    if (!this.isRunning) {
+      throw new KadiError(
+        `Process "${this.id}" is not running (state: ${this._state})`,
+        'PROCESS_NOT_RUNNING',
+        { processId: this.id, state: this._state },
+      );
+    }
+
+    if (!this._reader || !this._writer) {
+      throw new KadiError(
+        'Bridge streams not initialized',
+        'PROCESS_BRIDGE_ERROR',
+        { processId: this.id },
+      );
+    }
+
+    const id = this._bridgeIdCounter++;
+    const request = protocol.request(id, method, params ?? {});
+
+    this._writer.write(request);
+    const response = await this._reader.waitForResponse(id, timeout);
+
+    if (response.error) {
+      throw new KadiError(
+        response.error.message,
+        'PROCESS_BRIDGE_ERROR',
+        { processId: this.id, code: response.error.code, data: response.error.data },
+      );
+    }
+
+    return response.result;
+  }
+
+  /**
+   * Send a JSON-RPC notification (no response expected).
+   * Only available in bridge mode.
+   */
+  notify(method: string, params?: unknown): void {
+    if (this.mode !== 'bridge') {
+      throw new KadiError(
+        'notify() is only available in bridge mode',
+        'PROCESS_BRIDGE_ERROR',
+        { processId: this.id, mode: this.mode },
+      );
+    }
+
+    if (!this.isRunning || !this._writer) {
+      throw new KadiError(
+        `Process "${this.id}" is not running`,
+        'PROCESS_NOT_RUNNING',
+        { processId: this.id },
+      );
+    }
+
+    // Notifications have no id
+    const notification = {
+      jsonrpc: '2.0' as const,
+      method,
+      params: params ?? {},
+    };
+
+    const json = JSON.stringify(notification);
+    const contentLength = Buffer.byteLength(json, 'utf-8');
+    const header = `Content-Length: ${contentLength}\r\n\r\n`;
+
+    this._proc.stdin!.write(header + json);
+  }
+
+  /**
+   * Write raw data to the process stdin.
+   * Available in piped and bridge modes.
+   */
+  write(data: string | Buffer): void {
+    if (this.mode === 'headless') {
+      throw new KadiError(
+        'write() is not available in headless mode',
+        'PROCESS_BRIDGE_ERROR',
+        { processId: this.id },
+      );
+    }
+
+    if (!this.isRunning || !this._proc.stdin) {
+      throw new KadiError(
+        `Process "${this.id}" is not running`,
+        'PROCESS_NOT_RUNNING',
+        { processId: this.id },
+      );
+    }
+
+    this._proc.stdin.write(data);
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // LIFECYCLE
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Kill this process.
+   * Sends SIGTERM, waits for grace period, then SIGKILL.
+   */
+  async kill(signal: NodeJS.Signals = 'SIGTERM'): Promise<void> {
+    if (!this.isRunning) return;
+
+    this._proc.kill(signal);
+
+    await new Promise<void>((resolve) => {
+      const forceKillTimer = setTimeout(() => {
+        if (this.isRunning) {
+          this._proc.kill('SIGKILL');
+        }
+        resolve();
+      }, this._killGracePeriod);
+
+      this._proc.once('exit', () => {
+        clearTimeout(forceKillTimer);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Wait for the process to exit.
+   * Resolves immediately if already exited.
+   */
+  waitForExit(): Promise<ProcessExitInfo> {
+    if (!this.isRunning) {
+      return Promise.resolve({
+        exitCode: this._exitCode,
+        signal: this._signal,
+        duration: this._endedAt
+          ? this._endedAt.getTime() - this._startedAt.getTime()
+          : 0,
+      });
+    }
+
+    return new Promise((resolve) => {
+      this._exitWaiters.push({ resolve });
+    });
+  }
+
+  /**
+   * Get a snapshot of this process's info.
+   */
+  getInfo(): ProcessInfo {
+    const endedAt = this._endedAt;
+    return {
+      id: this.id,
+      pid: this.pid,
+      state: this._state,
+      mode: this.mode,
+      startedAt: this._startedAt,
+      endedAt,
+      exitCode: this._exitCode,
+      signal: this._signal,
+      duration: endedAt
+        ? endedAt.getTime() - this._startedAt.getTime()
+        : null,
+      command: this._command,
+      args: this._args,
+      cwd: this._cwd,
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // INTERNAL: EXIT HANDLING
+  // ─────────────────────────────────────────────────────────────────
+
+  private handleExit(code: number | null, signal: string | null): void {
+    if (this._timeoutTimer) {
+      clearTimeout(this._timeoutTimer);
+      this._timeoutTimer = null;
+    }
+
+    this._exitCode = code;
+    this._signal = signal;
+    this._endedAt = new Date();
+
+    if (this._state === 'running') {
+      this._state = signal ? 'killed' : 'exited';
+    }
+
+    // Cancel any pending bridge requests
+    if (this._reader) {
+      this._reader.cancelAll(
+        new KadiError('Process exited', 'PROCESS_NOT_RUNNING', { processId: this.id }),
+      );
+    }
+
+    const exitInfo: ProcessExitInfo = {
+      exitCode: code,
+      signal,
+      duration: this._endedAt.getTime() - this._startedAt.getTime(),
+    };
+
+    this.emit('exit', exitInfo);
+    this.resolveExitWaiters();
+  }
+
+  private resolveExitWaiters(): void {
+    const info: ProcessExitInfo = {
+      exitCode: this._exitCode,
+      signal: this._signal,
+      duration: this._endedAt
+        ? this._endedAt.getTime() - this._startedAt.getTime()
+        : 0,
+    };
+
+    for (const waiter of this._exitWaiters) {
+      waiter.resolve(info);
+    }
+    this._exitWaiters.length = 0;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// PROCESS MANAGER
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Manages background child processes.
+ *
+ * Provides spawn, status, kill, and lifecycle management across
+ * headless, piped, and bridge execution modes.
+ */
+export class ProcessManager {
+  /** Active and recently exited processes */
+  private readonly processes: Map<string, ManagedProcess> = new Map();
+
+  /** Cleanup handler registered with process.on('exit') */
+  private cleanupRegistered = false;
+
+  constructor() {
+    this.registerCleanup();
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // SPAWN
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Spawn a new managed background process.
+   *
+   * @param id - Unique name for this process
+   * @param options - Spawn configuration (command, args, mode, etc.)
+   * @returns A ManagedProcess handle
+   * @throws PROCESS_ALREADY_EXISTS if a running process with this id exists
+   * @throws PROCESS_SPAWN_FAILED if the command fails to start
+   *
+   * @example
+   * ```typescript
+   * const build = await pm.spawn('build', {
+   *   command: 'docker',
+   *   args: ['build', '-t', 'my-app', '.'],
+   *   cwd: '/path/to/project',
+   *   mode: 'piped',
+   * });
+   * ```
+   */
+  async spawn(id: string, options: SpawnOptions): Promise<ManagedProcess> {
+    // Check for duplicate running process
+    const existing = this.processes.get(id);
+    if (existing && existing.isRunning) {
+      throw new KadiError(
+        `Process "${id}" is already running`,
+        'PROCESS_ALREADY_EXISTS',
+        {
+          processId: id,
+          pid: existing.pid,
+          hint: `Kill it first with pm.kill("${id}") or use a different name`,
+        },
+      );
+    }
+
+    // Replace dead process entry
+    if (existing) {
+      this.processes.delete(id);
+    }
+
+    // Determine stdio configuration based on mode
+    const stdio = this.getStdioConfig(options.mode);
+
+    // Spawn the child process
+    let proc: ChildProcess;
+    try {
+      proc = spawn(options.command, options.args ?? [], {
+        stdio,
+        cwd: options.cwd,
+        env: options.env
+          ? { ...process.env, ...options.env }
+          : undefined,
+        detached: options.mode === 'headless', // Detach headless processes
+      });
+    } catch (error) {
+      throw new KadiError(
+        `Failed to spawn process "${id}": ${options.command}`,
+        'PROCESS_SPAWN_FAILED',
+        {
+          processId: id,
+          command: options.command,
+          args: options.args,
+          reason: error instanceof Error ? error.message : String(error),
+          hint: 'Check that the command exists and is executable',
+        },
+      );
+    }
+
+    // Verify PID was assigned
+    if (proc.pid === undefined) {
+      throw new KadiError(
+        `Failed to spawn process "${id}": no PID assigned`,
+        'PROCESS_SPAWN_FAILED',
+        { processId: id, command: options.command },
+      );
+    }
+
+    // Handle spawn errors (e.g., ENOENT — command not found)
+    // This must be set up synchronously before the next tick
+    const spawnError = await new Promise<Error | null>((resolve) => {
+      proc.once('error', (err) => resolve(err));
+      // If no error by next tick, the spawn succeeded
+      setImmediate(() => resolve(null));
+    });
+
+    if (spawnError) {
+      throw new KadiError(
+        `Failed to spawn process "${id}": ${spawnError.message}`,
+        'PROCESS_SPAWN_FAILED',
+        {
+          processId: id,
+          command: options.command,
+          reason: spawnError.message,
+          hint: 'Check that the command exists and is executable',
+        },
+      );
+    }
+
+    // Create and track the managed process
+    const managed = new ManagedProcess(id, proc, options);
+    this.processes.set(id, managed);
+
+    return managed;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // STATUS & QUERYING
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Get status information for a specific process.
+   *
+   * @param id - Process identifier
+   * @returns ProcessInfo snapshot
+   * @throws PROCESS_NOT_FOUND if no process with this id exists
+   */
+  getStatus(id: string): ProcessInfo {
+    const proc = this.processes.get(id);
+    if (!proc) {
+      throw new KadiError(
+        `Process "${id}" not found`,
+        'PROCESS_NOT_FOUND',
+        {
+          processId: id,
+          available: Array.from(this.processes.keys()),
+          hint: 'Use pm.list() to see all managed processes',
+        },
+      );
+    }
+    return proc.getInfo();
+  }
+
+  /**
+   * Get the ManagedProcess handle for a specific process.
+   * Useful when you need to attach events or call bridge methods.
+   *
+   * @param id - Process identifier
+   * @returns The ManagedProcess instance
+   * @throws PROCESS_NOT_FOUND if no process with this id exists
+   */
+  get(id: string): ManagedProcess {
+    const proc = this.processes.get(id);
+    if (!proc) {
+      throw new KadiError(
+        `Process "${id}" not found`,
+        'PROCESS_NOT_FOUND',
+        {
+          processId: id,
+          available: Array.from(this.processes.keys()),
+        },
+      );
+    }
+    return proc;
+  }
+
+  /**
+   * Get buffered output for a process (piped/bridge modes).
+   *
+   * @param id - Process identifier
+   * @returns Buffered stdout and stderr
+   */
+  getOutput(id: string): ProcessOutput {
+    return this.get(id).getOutput();
+  }
+
+  /**
+   * List all managed processes, optionally filtered by state.
+   *
+   * @param options - Optional filter criteria
+   * @returns Array of ProcessInfo snapshots
+   */
+  list(options?: ProcessListOptions): ProcessInfo[] {
+    const results: ProcessInfo[] = [];
+
+    for (const proc of this.processes.values()) {
+      const info = proc.getInfo();
+      if (options?.state && info.state !== options.state) continue;
+      if (options?.mode && info.mode !== options.mode) continue;
+      results.push(info);
+    }
+
+    return results;
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // LIFECYCLE MANAGEMENT
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Wait for a process to exit.
+   *
+   * @param id - Process identifier
+   * @returns Exit information
+   */
+  async waitFor(id: string): Promise<ProcessExitInfo> {
+    return this.get(id).waitForExit();
+  }
+
+  /**
+   * Kill a specific process.
+   *
+   * @param id - Process identifier
+   * @param signal - Signal to send (default: SIGTERM)
+   */
+  async kill(id: string, signal?: NodeJS.Signals): Promise<void> {
+    const proc = this.processes.get(id);
+    if (!proc) {
+      throw new KadiError(
+        `Process "${id}" not found`,
+        'PROCESS_NOT_FOUND',
+        { processId: id },
+      );
+    }
+    await proc.kill(signal);
+  }
+
+  /**
+   * Kill all running managed processes.
+   */
+  async killAll(): Promise<void> {
+    const kills: Promise<void>[] = [];
+
+    for (const proc of this.processes.values()) {
+      if (proc.isRunning) {
+        kills.push(proc.kill());
+      }
+    }
+
+    await Promise.allSettled(kills);
+  }
+
+  /**
+   * Remove exited/errored/killed processes from tracking.
+   *
+   * @param options - Optional criteria for which processes to remove
+   */
+  prune(options?: ProcessPruneOptions): void {
+    const now = Date.now();
+
+    for (const [id, proc] of this.processes) {
+      if (proc.isRunning) continue;
+
+      const info = proc.getInfo();
+      if (options?.olderThan !== undefined) {
+        const endedAt = info.endedAt?.getTime() ?? now;
+        const ageSeconds = (now - endedAt) / 1000;
+        if (ageSeconds >= options.olderThan) {
+          this.processes.delete(id);
+        }
+      } else {
+        // No filter — remove all non-running
+        this.processes.delete(id);
+      }
+    }
+  }
+
+  /**
+   * Graceful shutdown: SIGTERM all running processes, wait, then SIGKILL remainders.
+   */
+  async shutdown(): Promise<void> {
+    await this.killAll();
+    this.prune();
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // INTERNAL
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Determine stdio configuration based on process mode.
+   */
+  private getStdioConfig(mode: ProcessMode): Array<'pipe' | 'ignore' | 'inherit'> {
+    switch (mode) {
+      case 'headless':
+        return ['ignore', 'ignore', 'ignore'];
+      case 'piped':
+        return ['ignore', 'pipe', 'pipe'];
+      case 'bridge':
+        return ['pipe', 'pipe', 'pipe'];
+    }
+  }
+
+  /**
+   * Register a cleanup handler to kill child processes when the parent exits.
+   */
+  private registerCleanup(): void {
+    if (this.cleanupRegistered) return;
+    this.cleanupRegistered = true;
+
+    const cleanup = () => {
+      for (const proc of this.processes.values()) {
+        if (proc.isRunning) {
+          try {
+            proc.kill('SIGTERM').catch(() => {});
+          } catch {
+            // Best-effort cleanup
+          }
+        }
+      }
+    };
+
+    process.on('exit', cleanup);
+    process.on('SIGTERM', cleanup);
+    process.on('SIGINT', cleanup);
+  }
+}