evolclaw 2.8.2 → 3.0.0

package/dist/utils/instance-registry.js

@@ -0,0 +1,433 @@
+/**
+ * Instance registry — manages {HOME}/data/instance/ directory.
+ *
+ * 真相源：每个进程写一份带 PID 的 record 文件。判定"是否已有实例运行"时，
+ * 遍历所有 record，根据 (pid, startedAt) 对每个 record 做存活校验。
+ *
+ * 不使用 lock 文件——record 文件本身就是登记簿，"互斥"由 post-write 自检
+ * （写完 record 立刻扫一遍，比自己早的赢）保证。这样 6 个并发进程同时启动
+ * 也不会互相覆盖（PID 不同名字也不同），最终通过 startedAt 比较选出唯一赢家。
+ */
+import fs from 'fs';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { resolvePaths } from '../paths.js';
+import { isProcessRunning, killProcess, isWindows, findProcesses } from './cross-platform.js';
+import { getProcessStartTime, startTimeMatches } from './process-introspect.js';
+// ── Helpers ──
+function instanceDir() {
+    return resolvePaths().instanceDir;
+}
+function writeAtomic(filePath, data) {
+    const tmp = filePath + '.tmp';
+    fs.writeFileSync(tmp, data);
+    fs.renameSync(tmp, filePath);
+}
+function safeParseJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function isAlive(pid, recordedStartedAt) {
+    if (!isProcessRunning(pid))
+        return false;
+    const actual = getProcessStartTime(pid);
+    // 拿不到启动时间时保守认为是我们的进程（宁可误判活着，不误杀）
+    if (actual === null)
+        return true;
+    return startTimeMatches(recordedStartedAt, actual);
+}
+// ── Main record ──
+function mainFileName(pid) {
+    return `main-${pid}.json`;
+}
+export function writeMain(launchedBy) {
+    const dir = instanceDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const startedAt = getProcessStartTime(process.pid) ?? Date.now();
+    const record = {
+        pid: process.pid,
+        startedAt,
+        startedAtIso: new Date(startedAt).toISOString(),
+        launchedBy,
+    };
+    const filePath = path.join(dir, mainFileName(process.pid));
+    writeAtomic(filePath, JSON.stringify(record, null, 2));
+    return filePath;
+}
+export function removeMain(pid) {
+    const target = pid ?? process.pid;
+    const filePath = path.join(instanceDir(), mainFileName(target));
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch { }
+}
+/**
+ * Post-write 自检：写完 main record 后立刻扫一次目录。
+ * 如果发现别的活 main，按 (startedAt, pid) 选最早的赢家。
+ *
+ * @returns 当前进程是否赢家。false 表示应该让出（删自己的 record + exit）。
+ */
+export function isMainWinner() {
+    const status = scanInstances();
+    const aliveMains = status.mains.filter(m => m.alive);
+    if (aliveMains.length <= 1)
+        return { winner: true };
+    const self = aliveMains.find(m => m.record.pid === process.pid);
+    if (!self)
+        return { winner: true }; // 自己的记录都没了，让别人去争吧
+    // (startedAt, pid) 字典序最小者赢
+    const winnerEntry = aliveMains.reduce((best, cur) => {
+        if (cur.record.startedAt < best.record.startedAt)
+            return cur;
+        if (cur.record.startedAt > best.record.startedAt)
+            return best;
+        return cur.record.pid < best.record.pid ? cur : best;
+    });
+    if (winnerEntry.record.pid === process.pid)
+        return { winner: true };
+    return { winner: false, conflictingPid: winnerEntry.record.pid };
+}
+// ── Restart monitor record ──
+function restartMonitorFileName(pid) {
+    return `restart-monitor-${pid}.json`;
+}
+export function writeRestartMonitor() {
+    const dir = instanceDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const startedAt = getProcessStartTime(process.pid) ?? Date.now();
+    const record = {
+        pid: process.pid,
+        startedAt,
+        startedAtIso: new Date(startedAt).toISOString(),
+        launchedBy: 'restart-monitor',
+    };
+    const filePath = path.join(dir, restartMonitorFileName(process.pid));
+    writeAtomic(filePath, JSON.stringify(record, null, 2));
+    return filePath;
+}
+export function removeRestartMonitor(pid) {
+    const target = pid ?? process.pid;
+    const filePath = path.join(instanceDir(), restartMonitorFileName(target));
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch { }
+}
+/**
+ * Post-write 自检：与 isMainWinner 同语义，用于 restart-monitor。
+ */
+export function isRestartMonitorWinner() {
+    const status = scanInstances();
+    const alive = status.restartMonitors.filter(m => m.alive);
+    if (alive.length <= 1)
+        return { winner: true };
+    const self = alive.find(m => m.record.pid === process.pid);
+    if (!self)
+        return { winner: true };
+    const winnerEntry = alive.reduce((best, cur) => {
+        if (cur.record.startedAt < best.record.startedAt)
+            return cur;
+        if (cur.record.startedAt > best.record.startedAt)
+            return best;
+        return cur.record.pid < best.record.pid ? cur : best;
+    });
+    if (winnerEntry.record.pid === process.pid)
+        return { winner: true };
+    return { winner: false, conflictingPid: winnerEntry.record.pid };
+}
+// ─ AID event log ──
+function aidFileName(pid) {
+    return `aid-${pid}.jsonl`;
+}
+export function appendAidEvent(event, pid) {
+    const target = pid ?? process.pid;
+    const dir = instanceDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const filePath = path.join(dir, aidFileName(target));
+    const line = JSON.stringify(event) + '\n';
+    fs.appendFileSync(filePath, line);
+}
+export function removeAidLog(pid) {
+    const target = pid ?? process.pid;
+    const filePath = path.join(instanceDir(), aidFileName(target));
+    try {
+        fs.unlinkSync(filePath);
+    }
+    catch { }
+}
+/**
+ * 读取 aid jsonl 文件尾部，提取每个 AID 的最后活动时间和事件类型。
+ */
+export function readAidLastActivity(pid) {
+    const filePath = path.join(instanceDir(), aidFileName(pid));
+    const result = new Map();
+    if (!fs.existsSync(filePath))
+        return result;
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.trim().split('\n');
+        for (const line of lines) {
+            if (!line)
+                continue;
+            try {
+                const ev = JSON.parse(line);
+                if (ev.aid && ev.ts) {
+                    result.set(ev.aid, { ts: ev.ts, event: ev.event });
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return result;
+}
+// ── Scan & cleanup ──
+/**
+ * 扫描 instance/ 目录，返回所有实例记录（含死活状态）。
+ *
+ * 损坏的 JSON 文件直接删除。aid-*.jsonl 在 scan 时不解析，由调用方按需读取。
+ */
+export function scanInstances() {
+    const status = {
+        mains: [],
+        restartMonitors: [],
+        aidLastActivity: new Map(),
+    };
+    const dir = instanceDir();
+    if (!fs.existsSync(dir))
+        return status;
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return status;
+    }
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        if (file.startsWith('main-') && file.endsWith('.json')) {
+            const record = safeParseJson(filePath);
+            if (record && record.pid && record.startedAt) {
+                const alive = isAlive(record.pid, record.startedAt);
+                status.mains.push({ record, alive });
+                if (alive) {
+                    // 合并所有活 main 的 AID 活动记录（按 ts 取最新）
+                    for (const [aid, info] of readAidLastActivity(record.pid)) {
+                        const prev = status.aidLastActivity.get(aid);
+                        if (!prev || info.ts > prev.ts) {
+                            status.aidLastActivity.set(aid, info);
+                        }
+                    }
+                }
+            }
+            else {
+                try {
+                    fs.unlinkSync(filePath);
+                }
+                catch { }
+            }
+        }
+        else if (file.startsWith('restart-monitor-') && file.endsWith('.json')) {
+            const record = safeParseJson(filePath);
+            if (record && record.pid && record.startedAt) {
+                const alive = isAlive(record.pid, record.startedAt);
+                status.restartMonitors.push({ record, alive });
+            }
+            else {
+                try {
+                    fs.unlinkSync(filePath);
+                }
+                catch { }
+            }
+        }
+    }
+    return status;
+}
+/**
+ * 清理所有非自己 PID 的残留文件。仍活着的旧实例进程会被 SIGKILL。
+ * 返回被杀掉的 PID 列表。
+ */
+export function cleanupInstances() {
+    const dir = instanceDir();
+    if (!fs.existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const killed = [];
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        if (file.startsWith('main-') && file.endsWith('.json')) {
+            const record = safeParseJson(filePath);
+            if (record?.pid) {
+                if (record.pid === process.pid)
+                    continue;
+                if (isProcessRunning(record.pid)) {
+                    const actual = getProcessStartTime(record.pid);
+                    if (startTimeMatches(record.startedAt, actual)) {
+                        killPid(record.pid);
+                        killed.push(record.pid);
+                    }
+                }
+            }
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { }
+        }
+        else if (file.startsWith('restart-monitor-') && file.endsWith('.json')) {
+            const record = safeParseJson(filePath);
+            if (record?.pid) {
+                if (record.pid === process.pid)
+                    continue;
+                if (isProcessRunning(record.pid)) {
+                    const actual = getProcessStartTime(record.pid);
+                    if (startTimeMatches(record.startedAt, actual)) {
+                        killPid(record.pid);
+                        killed.push(record.pid);
+                    }
+                }
+            }
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { }
+        }
+        else if (file.startsWith('aid-') && file.endsWith('.jsonl')) {
+            // aid-<pid>.jsonl：自己的不动，其他的清掉
+            const m = file.match(/^aid-(\d+)\.jsonl$/);
+            if (m && parseInt(m[1], 10) === process.pid)
+                continue;
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { }
+        }
+        else if (file.endsWith('.tmp')) {
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { }
+        }
+    }
+    return killed;
+}
+/**
+ * 删除当前进程拥有的所有 instance 文件（正常关闭时调用）。
+ */
+export function removeAll(pid) {
+    const target = pid ?? process.pid;
+    removeMain(target);
+    removeAidLog(target);
+}
+// ── Internal ──
+function killPid(pid) {
+    killProcess(pid, true);
+}
+/**
+ * 扫所有 node 进程中跑 dist/index.js 的 PID，减去当前 HOME 已登记的 main PID。
+ *
+ * 用途：检测跨 HOME 残留的 evolclaw 主进程（例如测试套件 spawn 后未清理、
+ * 旧版本 pidfile 模式遗留等），由 cmdStart/cmdRestart 在启动前提示用户。
+ *
+ * Linux 下额外读取 /proc/<pid>/environ 提取 EVOLCLAW_HOME 用于展示。
+ * Windows / macOS 取不到环境变量时 evolclawHome 为 null。
+ *
+ * 不会主动 kill——清理由调用方决定（cmdRestart --kill-orphans 才执行）。
+ */
+export function findOrphanProcesses() {
+    // 1. 已登记 PID（自己 HOME 下的 main + 自己进程）
+    const known = new Set([process.pid]);
+    const status = scanInstances();
+    for (const m of status.mains)
+        known.add(m.record.pid);
+    for (const m of status.restartMonitors)
+        known.add(m.record.pid);
+    // 2. 系统中所有跑 dist/index.js 的 node 进程
+    const candidates = findProcesses('node.*dist/index.js');
+    const orphans = [];
+    for (const pid of candidates) {
+        if (known.has(pid))
+            continue;
+        if (!isProcessRunning(pid))
+            continue;
+        const cmdline = readCmdline(pid);
+        // 二次验证：确实是 evolclaw 的 dist/index.js
+        if (!/dist[\\/]index\.js/.test(cmdline))
+            continue;
+        orphans.push({
+            pid,
+            evolclawHome: readEvolclawHome(pid),
+            cmdline,
+        });
+    }
+    return orphans;
+}
+/**
+ * SIGKILL 所有传入的孤儿 PID。返回成功杀掉的 PID 列表（即调用后已停的）。
+ */
+export function killOrphans(orphans) {
+    const killed = [];
+    for (const o of orphans) {
+        try {
+            killProcess(o.pid, true);
+            killed.push(o.pid);
+        }
+        catch { }
+    }
+    return killed;
+}
+function readCmdline(pid) {
+    if (isWindows) {
+        try {
+            const out = execFileSync('wmic', ['process', 'where', `ProcessId=${pid}`, 'get', 'CommandLine', '/value'], { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+            const m = out.match(/CommandLine=([^\r\n]+)/);
+            return m ? m[1].trim() : '';
+        }
+        catch {
+            return '';
+        }
+    }
+    try {
+        return fs.readFileSync(`/proc/${pid}/cmdline`, 'utf-8').replace(/\0/g, ' ').trim();
+    }
+    catch {
+        // macOS / 权限不足
+        try {
+            return execFileSync('ps', ['-p', String(pid), '-o', 'args='], {
+                encoding: 'utf-8',
+                timeout: 3000,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            }).trim();
+        }
+        catch {
+            return '';
+        }
+    }
+}
+function readEvolclawHome(pid) {
+    // Linux: /proc/<pid>/environ
+    if (!isWindows && process.platform !== 'darwin') {
+        try {
+            const env = fs.readFileSync(`/proc/${pid}/environ`, 'utf-8');
+            for (const entry of env.split('\0')) {
+                if (entry.startsWith('EVOLCLAW_HOME='))
+                    return entry.slice('EVOLCLAW_HOME='.length);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}

package/dist/utils/log-writer.js

@@ -0,0 +1,216 @@
+/**
+ * LogWriter — 统一的日志文件管理。
+ *
+ * 一个实例 = 一份"活跃日志 + 历史归档"。所有 EvolClaw 内部需要写日志的地方
+ * 都应通过它，避免每个模块各自实现切片/清理。
+ *
+ * 切片规则：
+ *   - 'hourly' / 'daily'：进入新时段时把当前活跃文件 rename 成
+ *     `<base>-YYYYMMDD-HH.log` / `<base>-YYYYMMDD.log`，活跃文件名固定为
+ *     `<base>.log`。这样 `tail -F <base>.log` 能跨切片续接（必须 -F，跟 path）。
+ *   - 'size'：活跃文件超过 maxSize 时 rename 成 `<base>.log.<ISO-15>`。
+ *   - 'none'：不切。
+ *
+ * 清理：进入新时段或启动时按 retention 删除过旧的归档文件。
+ *
+ * 设计取舍：LogWriter 不持有 stream，每次 write 时按需 open-append-close。
+ *   优点：跨切片简单（rename 后下次 write 自动开新文件）；
+ *   代价：每行一次 open/close 在高频日志下不便宜——但 EvolClaw 的日志量
+ *   远低于 OS 缓存带宽，实测无瓶颈。
+ *   后续若有热点（如 messages.log）可改成持流模式 + 切片时 close。
+ */
+import fs from 'fs';
+import path from 'path';
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+export class LogWriter {
+    baseName;
+    logDir;
+    rotation;
+    maxSize;
+    retentionMs;
+    /** 当前活跃时段 tag（hourly: YYYYMMDD-HH，daily: YYYYMMDD），用于检测切片 */
+    currentTag;
+    /** 周期清理 timer（unref 不阻塞退出） */
+    cleanupTimer = null;
+    constructor(opts) {
+        this.baseName = opts.baseName;
+        this.logDir = opts.logDir;
+        this.rotation = opts.rotation;
+        this.maxSize = opts.maxSize ?? 10 * 1024 * 1024;
+        this.retentionMs =
+            (opts.retention.hours ?? 0) * HOUR_MS +
+                (opts.retention.days ?? 0) * DAY_MS;
+        fs.mkdirSync(this.logDir, { recursive: true });
+        this.currentTag = this.tagOfNow();
+        // 启动时如果 active 文件已存在但归属上一时段，先归档掉
+        this.rotateIfNeeded(/* sync */ true);
+        this.cleanupOldArchives();
+        // 周期触发切片+清理。两段式定时器：先用 setTimeout 对齐到下一个整点
+        //（hourly: 下个整点；daily: 明日 00:00），然后切到每小时一次的 setInterval。
+        // 这样空闲期也能按时切片——而不是等到下一次有人 write 才补切。
+        if (this.rotation === 'hourly' || this.rotation === 'daily') {
+            const tick = () => {
+                this.rotateIfNeeded(false);
+                this.cleanupOldArchives();
+            };
+            const initialDelay = this.msUntilNextBoundary();
+            const initialTimer = setTimeout(() => {
+                tick();
+                this.cleanupTimer = setInterval(tick, HOUR_MS);
+                this.cleanupTimer.unref?.();
+            }, initialDelay);
+            initialTimer.unref?.();
+        }
+    }
+    /** 写一行（自动加 \n） */
+    write(line) {
+        this.rotateIfNeeded(false);
+        try {
+            fs.appendFileSync(this.activePath(), line + '\n');
+        }
+        catch {
+            // 写入失败不抛——日志不能影响业务
+        }
+    }
+    /** 关闭（停掉清理 timer）。一般不需要调用，进程退出 timer 自动失效 */
+    close() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+    /** 当前活跃文件绝对路径 */
+    activePath() {
+        return path.join(this.logDir, `${this.baseName}.log`);
+    }
+    // ── Internal ──
+    /** 距离下一个整时段边界的毫秒数（hourly: 下个整点；daily: 明日 00:00） */
+    msUntilNextBoundary() {
+        const now = new Date();
+        const next = new Date(now);
+        if (this.rotation === 'daily') {
+            next.setDate(next.getDate() + 1);
+            next.setHours(0, 0, 0, 0);
+        }
+        else {
+            next.setHours(next.getHours() + 1, 0, 0, 0);
+        }
+        // 给 1 秒余量，确保 Date 时钟跨越整点后再触发，避免边界误差
+        return Math.max(1000, next.getTime() - now.getTime() + 1000);
+    }
+    tagOfNow() {
+        const d = new Date();
+        const pad = (n) => String(n).padStart(2, '0');
+        const day = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`;
+        if (this.rotation === 'daily')
+            return day;
+        return `${day}-${pad(d.getHours())}`;
+    }
+    archivePath(tag) {
+        return path.join(this.logDir, `${this.baseName}-${tag}.log`);
+    }
+    rotateIfNeeded(initial) {
+        const active = this.activePath();
+        if (this.rotation === 'none')
+            return;
+        if (this.rotation === 'size') {
+            let stat;
+            try {
+                stat = fs.statSync(active);
+            }
+            catch {
+                return;
+            }
+            if (stat.size <= this.maxSize)
+                return;
+            const tag = new Date().toISOString().replace(/[:.]/g, '').slice(0, 15);
+            try {
+                fs.renameSync(active, `${active}.${tag}`);
+            }
+            catch { }
+            this.cleanupOldArchives();
+            return;
+        }
+        // hourly / daily
+        const nowTag = this.tagOfNow();
+        // 文件不存在 → 直接更新 currentTag，下次 write 会创建
+        let stat = null;
+        try {
+            stat = fs.statSync(active);
+        }
+        catch { /* not exist */ }
+        if (!stat) {
+            this.currentTag = nowTag;
+            return;
+        }
+        // 启动时：用 mtime 判断 active 文件归属哪个 tag
+        const ownerTag = initial ? this.tagOfTime(stat.mtimeMs) : this.currentTag;
+        if (ownerTag === nowTag) {
+            this.currentTag = nowTag;
+            return;
+        }
+        // 切片：把 active 重命名为 archive
+        const archive = this.archivePath(ownerTag);
+        try {
+            // 如果 archive 已存在（重名），先合并：append 老 active 内容到 archive 末尾
+            if (fs.existsSync(archive)) {
+                try {
+                    const content = fs.readFileSync(active);
+                    fs.appendFileSync(archive, content);
+                    fs.unlinkSync(active);
+                }
+                catch { }
+            }
+            else {
+                fs.renameSync(active, archive);
+            }
+        }
+        catch { }
+        this.currentTag = nowTag;
+    }
+    tagOfTime(ms) {
+        const d = new Date(ms);
+        const pad = (n) => String(n).padStart(2, '0');
+        const day = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`;
+        if (this.rotation === 'daily')
+            return day;
+        return `${day}-${pad(d.getHours())}`;
+    }
+    cleanupOldArchives() {
+        LogWriter.cleanupArchivesIn(this.logDir, this.retentionMs);
+    }
+    /**
+     * 全局清理：扫整个 logDir，按 retention 删除所有匹配 LogWriter 归档命名约定的文件。
+     *
+     * 命名约定：`<baseName>-YYYYMMDD-HH.log`（hourly）或 `<baseName>-YYYYMMDD.log`（daily），
+     * 其中 baseName 由字母/数字/连字符组成。
+     *
+     * 这条规则跨 baseName 统一——只要文件按这个 pattern 命名就认为受 LogWriter 体系管辖。
+     * 这样 conditional 启用的 LogWriter（如 aun trace 关闭时）不会留下永久无人清的归档：
+     * 任意 LogWriter 实例化都会顺便清掉它们。
+     */
+    static cleanupArchivesIn(logDir, retentionMs) {
+        if (retentionMs <= 0)
+            return;
+        const cutoff = Date.now() - retentionMs;
+        let entries;
+        try {
+            entries = fs.readdirSync(logDir);
+        }
+        catch {
+            return;
+        }
+        const generalPattern = /^[A-Za-z0-9][A-Za-z0-9_-]*-\d{8}(?:-\d{2})?\.log$/;
+        for (const name of entries) {
+            if (!generalPattern.test(name))
+                continue;
+            const full = path.join(logDir, name);
+            try {
+                if (fs.statSync(full).mtimeMs < cutoff)
+                    fs.unlinkSync(full);
+            }
+            catch { }
+        }
+    }
+}