@kadi.build/core 0.8.0 → 0.11.0

package/dist/process-manager.d.ts

@@ -0,0 +1,235 @@
+/**
+ * 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 { type ChildProcess } from 'child_process';
+import { EventEmitter } from 'events';
+import type { ProcessMode, ProcessState, SpawnOptions, ProcessInfo, ProcessExitInfo, ProcessOutput, ProcessListOptions, ProcessPruneOptions } from './types.js';
+/**
+ * A handle to a spawned background process.
+ *
+ * Provides event subscription, lifecycle management, and (in bridge mode)
+ * JSON-RPC request/response communication.
+ */
+export declare class ManagedProcess extends EventEmitter {
+    /** Unique identifier */
+    readonly id: string;
+    /** OS process ID */
+    readonly pid: number;
+    /** Execution mode */
+    readonly mode: ProcessMode;
+    /** Internal state */
+    private _state;
+    private _exitCode;
+    private _signal;
+    private _startedAt;
+    private _endedAt;
+    /** Command info for getInfo() */
+    private readonly _command;
+    private readonly _args;
+    private readonly _cwd;
+    /** Output buffering (piped mode) */
+    private _stdout;
+    private _stderr;
+    private readonly _maxOutputBuffer;
+    /** Bridge mode internals */
+    private _reader;
+    private _writer;
+    private _bridgeIdCounter;
+    /** The underlying child process */
+    private readonly _proc;
+    /** Timeout timer for auto-kill */
+    private _timeoutTimer;
+    /** Kill grace period */
+    private readonly _killGracePeriod;
+    /** Waiters for the exit event */
+    private readonly _exitWaiters;
+    constructor(id: string, proc: ChildProcess, options: SpawnOptions);
+    /** Current lifecycle state */
+    get state(): ProcessState;
+    /** Whether the process is still running */
+    get isRunning(): boolean;
+    private setupPipedMode;
+    private setupBridgeMode;
+    private appendOutput;
+    /**
+     * Get all buffered output.
+     * Only available in piped and bridge modes.
+     */
+    getOutput(): ProcessOutput;
+    /**
+     * 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' });
+     * ```
+     */
+    request(method: string, params?: unknown, timeout?: number): Promise<unknown>;
+    /**
+     * Send a JSON-RPC notification (no response expected).
+     * Only available in bridge mode.
+     */
+    notify(method: string, params?: unknown): void;
+    /**
+     * Write raw data to the process stdin.
+     * Available in piped and bridge modes.
+     */
+    write(data: string | Buffer): void;
+    /**
+     * Kill this process.
+     * Sends SIGTERM, waits for grace period, then SIGKILL.
+     */
+    kill(signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Wait for the process to exit.
+     * Resolves immediately if already exited.
+     */
+    waitForExit(): Promise<ProcessExitInfo>;
+    /**
+     * Get a snapshot of this process's info.
+     */
+    getInfo(): ProcessInfo;
+    private handleExit;
+    private resolveExitWaiters;
+}
+/**
+ * Manages background child processes.
+ *
+ * Provides spawn, status, kill, and lifecycle management across
+ * headless, piped, and bridge execution modes.
+ */
+export declare class ProcessManager {
+    /** Active and recently exited processes */
+    private readonly processes;
+    /** Cleanup handler registered with process.on('exit') */
+    private cleanupRegistered;
+    constructor();
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    spawn(id: string, options: SpawnOptions): Promise<ManagedProcess>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Get buffered output for a process (piped/bridge modes).
+     *
+     * @param id - Process identifier
+     * @returns Buffered stdout and stderr
+     */
+    getOutput(id: string): ProcessOutput;
+    /**
+     * List all managed processes, optionally filtered by state.
+     *
+     * @param options - Optional filter criteria
+     * @returns Array of ProcessInfo snapshots
+     */
+    list(options?: ProcessListOptions): ProcessInfo[];
+    /**
+     * Wait for a process to exit.
+     *
+     * @param id - Process identifier
+     * @returns Exit information
+     */
+    waitFor(id: string): Promise<ProcessExitInfo>;
+    /**
+     * Kill a specific process.
+     *
+     * @param id - Process identifier
+     * @param signal - Signal to send (default: SIGTERM)
+     */
+    kill(id: string, signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Kill all running managed processes.
+     */
+    killAll(): Promise<void>;
+    /**
+     * Remove exited/errored/killed processes from tracking.
+     *
+     * @param options - Optional criteria for which processes to remove
+     */
+    prune(options?: ProcessPruneOptions): void;
+    /**
+     * Graceful shutdown: SIGTERM all running processes, wait, then SIGKILL remainders.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Determine stdio configuration based on process mode.
+     */
+    private getStdioConfig;
+    /**
+     * Register a cleanup handler to kill child processes when the parent exits.
+     */
+    private registerCleanup;
+}
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../src/process-manager.ts"],"names":[],"mappings":"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"}