hyacinth-ai 0.9.6

package/dist/lifecycle/manager.js

@@ -0,0 +1,374 @@
+import { spawn, execSync } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { createConnection } from 'node:net';
+import http from 'node:http';
+import os from 'node:os';
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('process-manager');
+const isWindows = os.platform() === 'win32';
+/**
+ * ProcessManager — 通用子进程生命周期管理器。
+ *
+ * 职责：
+ *   - 启动/停止/重启子进程
+ *   - 健康检查（HTTP / TCP）
+ *   - 崩溃自动恢复
+ *   - 超时强杀（SIGTERM → taskkill 回退）
+ *   - 进程树清理（Windows taskkill /T，Unix kill -pid）
+ *   - 状态追踪与事件通知
+ */
+export class ProcessManager {
+    config;
+    callbacks;
+    proc = null;
+    state = 'stopped';
+    startedAt = null;
+    restartCount = 0;
+    lastExitCode = null;
+    lastError = null;
+    healthTimer = null;
+    healthOk = false;
+    healthFailCount = 0;
+    manualStop = false;
+    childPids = new Set();
+    constructor(config, callbacks) {
+        this.config = config;
+        this.callbacks = callbacks;
+    }
+    // ===== 公共 API =====
+    /** 获取当前状态 */
+    getState() {
+        return this.state;
+    }
+    /** 获取当前进程实例 */
+    getProcess() {
+        return this.proc;
+    }
+    /** 获取完整状态快照 */
+    getStatus() {
+        return {
+            name: this.config.name,
+            state: this.state,
+            pid: this.proc?.pid ?? null,
+            uptime: this.startedAt ? Math.floor((Date.now() - this.startedAt.getTime()) / 1000) : null,
+            restartCount: this.restartCount,
+            lastExitCode: this.lastExitCode,
+            lastError: this.lastError,
+            startedAt: this.startedAt?.toISOString() ?? null,
+        };
+    }
+    /** 启动进程 + 等待健康检查通过 */
+    async start() {
+        if (this.state === 'running')
+            return;
+        this.manualStop = false;
+        this.transitionTo('starting');
+        this.spawnProcess();
+        await this.waitForStartup();
+    }
+    /** 停止进程（优雅 → 强制进程树杀） */
+    async stop() {
+        if (this.state === 'stopped' || this.state === 'stopping')
+            return;
+        this.manualStop = true;
+        this.transitionTo('stopping');
+        this.stopHealthCheck();
+        const pid = this.proc?.pid ?? null;
+        if (!this.proc || pid === null) {
+            this.proc = null;
+            this.transitionTo('stopped');
+            return;
+        }
+        const stopSignal = this.config.stopSignal ?? 'SIGTERM';
+        const timeout = this.config.stopTimeoutMs ?? 10_000;
+        try {
+            if (stopSignal !== 'SIGKILL') {
+                this.proc.kill(stopSignal);
+            }
+            await this.waitForExit(timeout);
+            if (this.proc && this.proc.exitCode === null) {
+                this.killProcessTree(pid);
+            }
+        }
+        catch {
+            this.killProcessTree(pid);
+        }
+        this.proc = null;
+        this.transitionTo('stopped');
+    }
+    /**
+     * 同步强制杀死进程及其所有子进程。
+     * 用于进程退出事件（exit handler 中异步不可用）。
+     */
+    forceKill() {
+        const pid = this.proc?.pid ?? null;
+        if (pid === null)
+            return;
+        this.killProcessTree(pid);
+        this.proc = null;
+    }
+    /** 重启进程 */
+    async restart() {
+        await this.stop();
+        this.restartCount = 0;
+        this.lastError = null;
+        await this.start();
+    }
+    /** 销毁管理器，清理所有资源 */
+    async destroy() {
+        await this.stop();
+        this.callbacks = undefined;
+    }
+    /** 合并回调（公开接口） */
+    setCallbacks(callbacks) {
+        this.callbacks = { ...this.callbacks, ...callbacks };
+    }
+    // ===== 内部方法 =====
+    spawnProcess() {
+        if (this.proc) {
+            try {
+                this.proc.kill('SIGKILL');
+            }
+            catch { /* 忽略 */ }
+            this.proc = null;
+        }
+        const { command, args, env, cwd } = this.config;
+        this.proc = spawn(command, args ?? [], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: env ? { ...process.env, ...env } : process.env,
+            cwd,
+            // Windows 上 npx/npm 等 .cmd 命令需要 shell 模式才能执行
+            shell: isWindows,
+            windowsHide: true,
+            detached: false,
+        });
+        this.startedAt = new Date();
+        if (this.proc.pid) {
+            this.childPids.add(this.proc.pid);
+        }
+        this.proc.stdout?.on('data', (data) => {
+            const text = data.toString().trimEnd();
+            if (text)
+                logger.debug(`[${this.config.name}] ${text}`);
+        });
+        this.proc.stderr?.on('data', (data) => {
+            const text = data.toString().trimEnd();
+            if (text)
+                logger.warn(`[${this.config.name}] ${text}`);
+        });
+        this.proc.on('exit', (code, signal) => {
+            if (this.proc?.pid)
+                this.childPids.delete(this.proc.pid);
+            this.lastExitCode = code;
+            this.proc = null;
+            this.stopHealthCheck();
+            if (signal || this.manualStop) {
+                if (!this.manualStop && this.state !== 'stopping') {
+                    this.handleCrash(code);
+                }
+                return;
+            }
+            if (code !== null && code !== 0) {
+                this.handleCrash(code);
+            }
+            else if (code === 0 && !this.manualStop) {
+                this.handleCrash(code);
+            }
+        });
+        this.proc.on('error', (err) => {
+            this.lastError = err.message;
+            if (!this.manualStop) {
+                this.handleCrash(null);
+            }
+        });
+    }
+    handleCrash(exitCode) {
+        this.healthOk = false;
+        this.transitionTo('crashed');
+        this.callbacks?.onCrash?.(this.config.name, exitCode);
+        if (this.manualStop)
+            return;
+        if (this.config.autoRestart && this.restartCount < (this.config.maxRestarts ?? 5)) {
+            const delay = this.config.restartDelayMs ?? 2000;
+            this.restartCount++;
+            setTimeout(() => {
+                if (!this.manualStop) {
+                    this.transitionTo('starting');
+                    this.spawnProcess();
+                    this.waitForStartup();
+                }
+            }, delay);
+        }
+    }
+    async waitForStartup() {
+        if (!this.config.healthCheck) {
+            // 无健康检查：给进程一点时间启动，然后直接标记 running
+            await sleep(1000);
+            if (this.state !== 'stopping') {
+                this.transitionTo('running');
+            }
+            return;
+        }
+        const hc = this.config.healthCheck;
+        const timeout = this.config.startupTimeoutMs ?? 60_000;
+        const deadline = Date.now() + timeout;
+        while (Date.now() < deadline) {
+            if (this.manualStop || this.state === 'stopping')
+                return;
+            const ok = await this.performHealthCheck(hc);
+            if (ok) {
+                this.healthOk = true;
+                this.healthFailCount = 0;
+                this.startPeriodicHealthCheck(hc);
+                this.transitionTo('running');
+                return;
+            }
+            await sleep(hc.intervalMs ?? 2000);
+        }
+        // 启动超时
+        this.lastError = `Startup health check timed out after ${timeout}ms`;
+        this.transitionTo('failed');
+        if (this.config.autoRestart) {
+            this.handleCrash(null);
+        }
+    }
+    async performHealthCheck(hc) {
+        try {
+            if (hc.url) {
+                await httpGet(hc.url, hc.timeoutMs ?? 3000);
+                return true;
+            }
+            if (hc.host && hc.port !== undefined) {
+                await tcpConnect(hc.host, hc.port, hc.timeoutMs ?? 3000);
+                return true;
+            }
+            return true; // 无健康检查方式
+        }
+        catch {
+            return false;
+        }
+    }
+    startPeriodicHealthCheck(hc) {
+        this.stopHealthCheck();
+        this.healthTimer = setInterval(async () => {
+            if (this.state !== 'running')
+                return;
+            const ok = await this.performHealthCheck(hc);
+            if (ok) {
+                if (!this.healthOk) {
+                    this.healthOk = true;
+                    this.healthFailCount = 0;
+                    this.callbacks?.onHealthRecover?.(this.config.name);
+                }
+                return;
+            }
+            this.healthFailCount++;
+            if (this.healthFailCount >= (hc.maxRetries ?? 3)) {
+                this.healthOk = false;
+                this.lastError = `Health check failed after ${this.healthFailCount} attempts`;
+                this.callbacks?.onHealthFail?.(this.config.name, this.lastError);
+                this.handleCrash(this.lastExitCode);
+            }
+        }, hc.intervalMs ?? 5000);
+    }
+    stopHealthCheck() {
+        if (this.healthTimer) {
+            clearInterval(this.healthTimer);
+            this.healthTimer = null;
+        }
+    }
+    waitForExit(timeoutMs) {
+        return new Promise((resolve, reject) => {
+            if (!this.proc || this.proc.exitCode !== null) {
+                resolve();
+                return;
+            }
+            const timer = setTimeout(() => reject(new Error('Timeout')), timeoutMs);
+            this.proc.once('exit', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            this.proc.once('error', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    /**
+     * 杀死进程及其所有子进程（进程树）。
+     * Windows: taskkill /F /T /PID
+     * Unix:    kill -SIGKILL -pid (进程组)
+     */
+    killProcessTree(pid) {
+        try {
+            if (isWindows) {
+                execSync(`taskkill /F /T /PID ${pid}`, {
+                    stdio: 'ignore',
+                    windowsHide: true,
+                });
+            }
+            else {
+                process.kill(-pid, 'SIGKILL');
+            }
+        }
+        catch {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                // 进程已不存在
+            }
+        }
+    }
+    /**
+     * 清理所有已知的子进程 PID。
+     * 在 exit handler 中同步调用，不依赖异步操作。
+     */
+    forceKillAll() {
+        for (const pid of this.childPids) {
+            this.killProcessTree(pid);
+        }
+        this.childPids.clear();
+    }
+    transitionTo(newState) {
+        const old = this.state;
+        this.state = newState;
+        this.callbacks?.onStateChange?.(this.config.name, old, newState);
+    }
+}
+// ===== HTTP / TCP 健康检查工具 =====
+function httpGet(url, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const req = http.get(url, { timeout: timeoutMs }, (res) => {
+            res.resume();
+            if (res.statusCode && res.statusCode < 500) {
+                resolve();
+            }
+            else {
+                reject(new Error(`HTTP ${res.statusCode}`));
+            }
+        });
+        req.on('error', reject);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error('Timeout'));
+        });
+    });
+}
+function tcpConnect(host, port, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection({ host, port, timeout: timeoutMs }, () => {
+            socket.destroy();
+            resolve();
+        });
+        socket.on('error', (err) => {
+            socket.destroy();
+            reject(err);
+        });
+        socket.on('timeout', () => {
+            socket.destroy();
+            reject(new Error('Timeout'));
+        });
+    });
+}
+//# sourceMappingURL=manager.js.map

package/dist/lifecycle/supervisor.d.ts

@@ -0,0 +1,89 @@
+import { type ProcessStatus } from './interface.js';
+import { ProcessManager } from './manager.js';
+import { LocalModelManager, type LoadedModelInfo } from './local-model.js';
+import type { BackgroundProcessRegistry } from '../tools/background-registry.js';
+export type ManagedEntityType = 'local-model' | 'mcp-server' | 'custom';
+interface ManagedEntity {
+    type: ManagedEntityType;
+    manager: ProcessManager;
+    name: string;
+}
+/**
+ * LifecycleSupervisor — 统一管理所有受管进程的生命周期。
+ *
+ * 职责：
+ *   1. 作为中心注册表，管理 LocalModel 和 MCP Server 的 ProcessManager
+ *   2. 提供统一的启动/停止/状态查询接口
+ *   3. 协调应用退出时的优雅关闭（按依赖顺序停止）
+ *   4. 暴露全局事件回调
+ */
+export declare class LifecycleSupervisor {
+    private entities;
+    private localModelManager;
+    private _shuttingDown;
+    private backgroundRegistry?;
+    /** 是否正在关闭中 */
+    get shuttingDown(): boolean;
+    /** 获取所有实体的状态 */
+    getAllStatus(): (ProcessStatus & {
+        type: ManagedEntityType;
+    })[];
+    /** 获取特定实体的状态 */
+    getStatus(name: string): (ProcessStatus & {
+        type: ManagedEntityType;
+    }) | null;
+    /** 获取指定类型的所有实体 */
+    getByType(type: ManagedEntityType): ManagedEntity[];
+    /**
+     * 从项目目录加载并启动本地模型
+     * @returns 加载到的模型信息列表
+     */
+    loadAndStartModels(projectDir: string): Promise<LoadedModelInfo[]>;
+    /** 启动指定模型 */
+    startModel(name: string): Promise<void>;
+    /**
+     * 运行时按需启动模型。
+     * 用于 CLI 中用户切换 provider 到 local 时。
+     */
+    startModelOnDemand(projectDir: string, modelKey: string): Promise<LoadedModelInfo | null>;
+    /** 停止指定模型（同时检查 localModelManager 和 entities） */
+    stopModel(name: string): Promise<void>;
+    /**
+     * 自动检测并启动 Ollama（无需预先配置模型注册表）。
+     * 用于 switchProvider("local") 时自动拉起。
+     */
+    startOllamaOnDemand(projectDir: string): Promise<LoadedModelInfo | null>;
+    /** 获取 LocalModelManager 实例（供 CLI 获取模型信息以配置 Provider） */
+    getModelManager(): LocalModelManager;
+    /** 注册一个 MCP Server 的 ProcessManager */
+    registerMCPServer(manager: ProcessManager): void;
+    /** 注册任意受管进程 */
+    register(name: string, type: ManagedEntityType, manager: ProcessManager): void;
+    /** 注册后台进程注册表（用于异步工具如 bash async:true），关闭时自动清理 */
+    registerBackgroundRegistry(registry: BackgroundProcessRegistry): void;
+    /**
+     * 关闭所有受管进程。
+     * 关闭顺序：local-model → mcp-server → custom
+     * （模型和 MCP Server 无严格依赖，并行关闭即可）
+     */
+    shutdownAll(): Promise<void>;
+    /**
+     * 安装 SIGINT / SIGTERM / 进程退出处理器，实现优雅关闭。
+     *
+     * 三层防护：
+     *   1. SIGINT / SIGTERM → 异步优雅关闭
+     *   2. beforeExit      → 异步关闭（覆盖正常退出路径）
+     *   3. exit            → 同步 forceKill（最后防线，确保子进程不留孤儿）
+     *
+     * 返回一个函数，调用后可移除这些处理器。
+     */
+    installSignalHandlers(): () => void;
+    /**
+     * 同步强制杀死所有受管子进程。
+     * 用于 exit handler 中，不依赖异步操作。
+     */
+    private forceKillAll;
+    private createCallbacks;
+}
+export {};
+//# sourceMappingURL=supervisor.d.ts.map