evolcore 0.0.1 → 0.0.3

package/dist/ipc.js

@@ -0,0 +1,777 @@
+import net from 'net';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { logger } from './utils/logger.js';
+import { fileCache } from './core/daemon-file-cache.js';
+import { HANDOFF_QUERY_MAX_LIMIT, HANDOFF_STATES } from './core/handoff/types.js';
+import { resolvePaths } from './paths.js';
+import { getProcessStartTime, isSameOrOlderProcess } from './utils/process-introspect.js';
+import { classifyProcessTree, ProcessTreeSampler } from './utils/process-tree-stats.js';
+import { readSystemMemoryUsage } from './utils/system-memory.js';
+const isWindows = process.platform === 'win32';
+const isNamedPipe = (p) => isWindows && p.startsWith('\\\\.\\pipe\\');
+export function summarizeMonitorAgents(agents, aids) {
+    const connectedAgents = new Set(aids.filter(aid => aid.status === 'connected').map(aid => aid.agentName || aid.aid));
+    const enabledAgents = agents.filter(agent => agent.status !== 'disabled');
+    return {
+        total: agents.length,
+        enabled: enabledAgents.length,
+        running: agents.filter(agent => agent.status === 'running').length,
+        connected: enabledAgents.filter(agent => connectedAgents.has(agent.aid)).length,
+        disabled: agents.filter(agent => agent.status === 'disabled').length,
+        errors: agents.filter(agent => agent.status === 'error').length,
+    };
+}
+export class IpcServer {
+    socketPath;
+    getStatus;
+    commandExecutor;
+    server = null;
+    agentRegistry;
+    aunAidProvider;
+    aunAidStatsProvider;
+    aunAidStatsRecorder;
+    menuExecutor;
+    statsProvider;
+    agentStatsProvider;
+    queueSnapshotProvider;
+    queueActionExecutor;
+    triggerExecutor;
+    taskRuntimeContextProvider;
+    aunMsgSender;
+    handoffReturnExecutor;
+    handoffStatusExecutor;
+    handoffListExecutor;
+    handoffTraceExecutor;
+    bindExecutor;
+    configOperationExecutor;
+    contactOperationExecutor;
+    dingtalkContactBindExecutor;
+    wecomContactBindExecutor;
+    // CPU 占用追踪：IPC handler 是一次性同步调用，无法在响应里做 200ms 异步采样，
+    // 故用后台 1s interval 累积 process.cpuUsage() 增量，handler 直接读最近值。
+    // procCpuPercent = 本 daemon 进程占单核的百分比（可 >100% 仅当多核，已 clamp 到 100）；
+    // sysCpuPercent  = 整机所有核平均忙碌百分比（由 os.cpus() times 增量算出）。
+    lastCpuUsage = process.cpuUsage();
+    lastCpuTs = Date.now();
+    cpuPercent = 0; // 进程级
+    sysCpuPercent = 0; // 系统级
+    lastCpuTimes = null;
+    cpuTimer = null;
+    processTreeSampler = new ProcessTreeSampler(process.pid);
+    processTreeSnapshot = null;
+    associatedProcessKinds = new Map();
+    constructor(socketPath, getStatus, commandExecutor) {
+        this.socketPath = socketPath;
+        this.getStatus = getStatus;
+        this.commandExecutor = commandExecutor;
+    }
+    /** Inject EvolAgentRegistry for evolagent.* IPC handlers */
+    setAgentRegistry(registry) {
+        this.agentRegistry = registry;
+    }
+    /** Inject menu.* executor (ECWeb Control proxies menu requests through this) */
+    setMenuExecutor(executor) {
+        this.menuExecutor = executor;
+    }
+    setConfigOperationExecutor(executor) {
+        this.configOperationExecutor = executor;
+    }
+    setContactOperationExecutor(executor) {
+        this.contactOperationExecutor = executor;
+    }
+    /** Inject AUN AID state aggregator for aun-aids IPC handler */
+    setAunAidProvider(provider) {
+        this.aunAidProvider = provider;
+    }
+    /** Inject AUN AID stats provider for aun-aid-stats IPC handler */
+    setAunAidStatsProvider(provider) {
+        this.aunAidStatsProvider = provider;
+    }
+    /** Inject AUN AID stats recorder for aun-aid-stats-record-outbound IPC handler */
+    setAunAidStatsRecorder(recorder) {
+        this.aunAidStatsRecorder = recorder;
+    }
+    /** Inject global StatsSnapshot provider for monitor-snapshot IPC handler */
+    setStatsProvider(provider) {
+        this.statsProvider = provider;
+    }
+    /** Inject per-agent rolling stats provider for ECWeb Agents page. */
+    setAgentStatsProvider(provider) {
+        this.agentStatsProvider = provider;
+    }
+    /** Inject queue snapshot provider for queue-snapshot IPC handler (query mode) */
+    setQueueSnapshotProvider(provider) {
+        this.queueSnapshotProvider = provider;
+    }
+    /** Inject queue action executor for queue-snapshot IPC handler (action mode) */
+    setQueueActionExecutor(executor) {
+        this.queueActionExecutor = executor;
+    }
+    /** Inject daemon-level trigger executor for ec trigger. */
+    setTriggerExecutor(executor) {
+        this.triggerExecutor = executor;
+    }
+    /** Inject active task runtime-context provider for in-task CLI routing. */
+    setTaskRuntimeContextProvider(provider) {
+        this.taskRuntimeContextProvider = provider;
+    }
+    /** Inject daemon-backed AUN private message sender for in-task `ec msg send`. */
+    setAunMsgSender(sender) {
+        this.aunMsgSender = sender;
+    }
+    /** Inject internal handoff result return executor for `ec handoff return`. */
+    setHandoffReturnExecutor(executor) {
+        this.handoffReturnExecutor = executor;
+    }
+    setHandoffStatusExecutor(executor) {
+        this.handoffStatusExecutor = executor;
+    }
+    setHandoffListExecutor(executor) {
+        this.handoffListExecutor = executor;
+    }
+    setHandoffTraceExecutor(executor) {
+        this.handoffTraceExecutor = executor;
+    }
+    /** Inject bootstrap QR bind executor for init/init aun. */
+    setBindExecutor(executor) {
+        this.bindExecutor = executor;
+    }
+    /** Inject DingTalk contact binding-code executor. */
+    setDingtalkContactBindExecutor(executor) {
+        this.dingtalkContactBindExecutor = executor;
+    }
+    /** Inject WeCom contact binding-code executor. */
+    setWecomContactBindExecutor(executor) {
+        this.wecomContactBindExecutor = executor;
+    }
+    /** Start the 1s background CPU sampling loop (for monitor-snapshot). Call after start(). */
+    startCpuTracking() {
+        if (this.cpuTimer)
+            return;
+        this.sampleProcessTree();
+        this.cpuTimer = setInterval(() => {
+            const now = Date.now();
+            const elapsedUs = (now - this.lastCpuTs) * 1000; // wall time in microseconds
+            if (elapsedUs > 0) {
+                const usage = process.cpuUsage(this.lastCpuUsage); // delta since last sample
+                this.cpuPercent = Math.min(100, ((usage.user + usage.system) / elapsedUs) * 100);
+            }
+            this.lastCpuUsage = process.cpuUsage();
+            this.lastCpuTs = now;
+            // 系统级 CPU：os.cpus() 累计 times 的增量 → 整机平均忙碌率
+            try {
+                const cpus = os.cpus();
+                let idle = 0, total = 0;
+                for (const c of cpus) {
+                    idle += c.times.idle;
+                    total += c.times.user + c.times.nice + c.times.sys + c.times.idle + c.times.irq;
+                }
+                if (this.lastCpuTimes) {
+                    const idleDelta = idle - this.lastCpuTimes.idle;
+                    const totalDelta = total - this.lastCpuTimes.total;
+                    if (totalDelta > 0) {
+                        this.sysCpuPercent = Math.max(0, Math.min(100, (1 - idleDelta / totalDelta) * 100));
+                    }
+                }
+                this.lastCpuTimes = { idle, total };
+            }
+            catch { /* os.cpus() 理论上不抛 */ }
+            this.sampleProcessTree();
+        }, 1000);
+        // Don't keep the event loop alive for sampling alone.
+        this.cpuTimer.unref?.();
+    }
+    /** Stop the CPU sampling loop. */
+    stopCpuTracking() {
+        if (this.cpuTimer) {
+            clearInterval(this.cpuTimer);
+            this.cpuTimer = null;
+        }
+    }
+    sampleProcessTree() {
+        try {
+            const roots = this.readAssociatedProcessRoots();
+            this.associatedProcessKinds = new Map(roots.map(root => [root.pid, root.kind]));
+            this.processTreeSnapshot = this.processTreeSampler.sample(roots.map(root => root.pid));
+        }
+        catch {
+            this.processTreeSnapshot = null;
+            this.associatedProcessKinds.clear();
+        }
+    }
+    readAssociatedProcessRoots() {
+        const roots = [];
+        let files;
+        try {
+            files = fs.readdirSync(resolvePaths().instanceDir);
+        }
+        catch {
+            return roots;
+        }
+        for (const file of files) {
+            const match = file.match(/^(ecweb|watch-web|restart-monitor|watch-aid|watch)-(\d+)\.json$/);
+            if (!match)
+                continue;
+            try {
+                const record = JSON.parse(fs.readFileSync(path.join(resolvePaths().instanceDir, file), 'utf8'));
+                const pid = Number(record.pid || match[2]);
+                if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
+                    continue;
+                if (record.startedAt) {
+                    const actual = getProcessStartTime(pid);
+                    if (!isSameOrOlderProcess(Number(record.startedAt), actual))
+                        continue;
+                }
+                roots.push({ pid, kind: match[1] });
+            }
+            catch { }
+        }
+        return roots;
+    }
+    start() {
+        // Remove stale socket file (Unix only — named pipes auto-cleanup on process exit)
+        if (!isNamedPipe(this.socketPath)) {
+            try {
+                fs.unlinkSync(this.socketPath);
+            }
+            catch { }
+        }
+        return new Promise((resolve, reject) => {
+            this.server = net.createServer((conn) => {
+                let buf = '';
+                conn.on('data', async (data) => {
+                    buf += data.toString();
+                    // Simple newline-delimited JSON protocol
+                    const idx = buf.indexOf('\n');
+                    if (idx === -1)
+                        return;
+                    const line = buf.slice(0, idx);
+                    buf = buf.slice(idx + 1);
+                    try {
+                        const cmd = JSON.parse(line);
+                        const response = await this.handleCommand(cmd);
+                        conn.end(JSON.stringify(response) + '\n');
+                    }
+                    catch {
+                        conn.end(JSON.stringify({ error: 'invalid request' }) + '\n');
+                    }
+                });
+                conn.on('error', () => { }); // ignore client errors
+            });
+            const onListenError = (err) => {
+                logger.error('[IPC] Server error:', err);
+                reject(err);
+            };
+            this.server.once('error', onListenError);
+            this.server.listen(this.socketPath, () => {
+                this.server?.off('error', onListenError);
+                this.server?.on('error', (err) => {
+                    logger.error('[IPC] Server error:', err);
+                });
+                // Restrict to current user (Unix only — named pipes use Windows ACLs)
+                if (!isNamedPipe(this.socketPath)) {
+                    try {
+                        fs.chmodSync(this.socketPath, 0o600);
+                    }
+                    catch { }
+                }
+                logger.info(`[IPC] Listening on ${this.socketPath}`);
+                resolve();
+            });
+        });
+    }
+    stop() {
+        if (this.server) {
+            this.server.close();
+            this.server = null;
+        }
+        if (!isNamedPipe(this.socketPath)) {
+            try {
+                fs.unlinkSync(this.socketPath);
+            }
+            catch { }
+        }
+    }
+    async handleCommand(cmd) {
+        switch (cmd.type) {
+            case 'status':
+                return this.getStatus();
+            case 'ping':
+                return { pong: true, pid: process.pid, protocolVersion: 1 };
+            case 'bind.begin': {
+                if (!this.bindExecutor)
+                    return { ok: false, error: 'bind executor not configured' };
+                return this.bindExecutor.begin({
+                    bindType: cmd.bindType,
+                    targetAid: cmd.targetAid,
+                    agentName: cmd.agentName,
+                    ownerMode: cmd.ownerMode,
+                    ttlMs: cmd.ttlMs,
+                });
+            }
+            case 'bind.status': {
+                if (!this.bindExecutor)
+                    return { ok: false, error: 'bind executor not configured' };
+                return this.bindExecutor.status(cmd.taskId);
+            }
+            case 'bind.cancel': {
+                if (!this.bindExecutor)
+                    return { ok: false, error: 'bind executor not configured' };
+                return this.bindExecutor.cancel(cmd.taskId);
+            }
+            case 'dingtalk.contact-bind.register': {
+                if (!this.dingtalkContactBindExecutor) {
+                    return { ok: false, error: 'dingtalk contact bind executor not configured' };
+                }
+                return this.dingtalkContactBindExecutor.register({
+                    selfAid: cmd.selfAid,
+                    channelName: cmd.channelName,
+                    primaryId: cmd.primaryId,
+                });
+            }
+            case 'wecom.contact-bind.register': {
+                if (!this.wecomContactBindExecutor) {
+                    return { ok: false, error: 'wecom contact bind executor not configured' };
+                }
+                return this.wecomContactBindExecutor.register({
+                    selfAid: cmd.selfAid,
+                    channelName: cmd.channelName,
+                    primaryId: cmd.primaryId,
+                });
+            }
+            case 'aun-aids': {
+                const aids = this.aunAidProvider ? this.aunAidProvider() : [];
+                return { ok: true, aids };
+            }
+            case 'aun-aid-stats': {
+                const stats = this.aunAidStatsProvider ? this.aunAidStatsProvider() : [];
+                return { ok: true, stats };
+            }
+            case 'agent-stats': {
+                const stats = this.agentStatsProvider ? this.agentStatsProvider() : [];
+                return { ok: true, stats };
+            }
+            case 'cache-stats': {
+                // daemon 统一 FileCache 的只读运行统计（watch web Cache 页用）。
+                // 直接读单例，无需 provider 注入（与 manifest-engine 等 import 单例同款）。
+                return { ok: true, stats: fileCache.stats() };
+            }
+            case 'queue-snapshot': {
+                if (!cmd.agent)
+                    return { ok: false, error: 'missing agent' };
+                if (!cmd.action) {
+                    // 纯查询
+                    if (!this.queueSnapshotProvider)
+                        return { ok: false, error: 'queue-snapshot not configured' };
+                    return { ok: true, items: this.queueSnapshotProvider({ agent: cmd.agent }) };
+                }
+                // 操作：clear / cancel / interrupt
+                if (!this.queueActionExecutor)
+                    return { ok: false, error: 'queue actions not configured' };
+                return await this.queueActionExecutor({
+                    agent: cmd.agent,
+                    action: cmd.action,
+                    messageId: cmd.messageId,
+                    sessionKey: cmd.sessionKey,
+                });
+            }
+            case 'aun-aid-stats-record-outbound': {
+                if (!this.aunAidStatsRecorder)
+                    return { ok: false, error: 'recorder not configured' };
+                try {
+                    this.aunAidStatsRecorder({
+                        aid: cmd.aid,
+                        toPeer: cmd.toPeer,
+                        text: cmd.text ?? '',
+                        encrypt: cmd.encrypt,
+                        chatmode: cmd.chatmode,
+                    });
+                    return { ok: true };
+                }
+                catch (e) {
+                    return { ok: false, error: String(e?.message || e) };
+                }
+            }
+            case 'task-runtime-context': {
+                if (!this.taskRuntimeContextProvider)
+                    return { ok: false, error: 'task runtime context not configured' };
+                if (!cmd.sessionId || typeof cmd.sessionId !== 'string')
+                    return { ok: false, error: 'missing sessionId' };
+                const context = this.taskRuntimeContextProvider({ sessionId: cmd.sessionId }) ?? null;
+                return { ok: true, context };
+            }
+            case 'aun-msg-send': {
+                if (!this.aunMsgSender)
+                    return { ok: false, error: 'aun msg sender not configured' };
+                if (!cmd.aid || typeof cmd.aid !== 'string')
+                    return { ok: false, error: 'missing aid' };
+                if (!cmd.to || typeof cmd.to !== 'string')
+                    return { ok: false, error: 'missing to' };
+                const payload = cmd.payload && typeof cmd.payload === 'object' && !Array.isArray(cmd.payload)
+                    ? cmd.payload
+                    : undefined;
+                const rawFile = cmd.file && typeof cmd.file === 'object' && !Array.isArray(cmd.file)
+                    ? cmd.file
+                    : undefined;
+                const file = typeof rawFile?.filePath === 'string'
+                    ? {
+                        filePath: rawFile.filePath,
+                        as: typeof rawFile.as === 'string' ? rawFile.as : undefined,
+                        contentType: typeof rawFile.contentType === 'string' ? rawFile.contentType : undefined,
+                        text: typeof rawFile.text === 'string' ? rawFile.text : undefined,
+                        transcript: typeof rawFile.transcript === 'string' ? rawFile.transcript : undefined,
+                    }
+                    : undefined;
+                if ((!payload && !file) || (payload && file)) {
+                    return { ok: false, error: 'exactly one of payload or file is required' };
+                }
+                const rawLog = cmd.log && typeof cmd.log === 'object' && !Array.isArray(cmd.log)
+                    ? cmd.log
+                    : undefined;
+                const log = typeof rawLog?.content === 'string'
+                    ? {
+                        content: rawLog.content,
+                        sessionId: typeof rawLog.sessionId === 'string' ? rawLog.sessionId : undefined,
+                        threadId: typeof rawLog.threadId === 'string' ? rawLog.threadId : rawLog.threadId === null ? null : undefined,
+                        msgType: rawLog.msgType,
+                        payloadType: typeof rawLog.payloadType === 'string' ? rawLog.payloadType : undefined,
+                        payloadSummary: rawLog.payloadSummary,
+                        source: rawLog.source,
+                    }
+                    : undefined;
+                try {
+                    return await this.aunMsgSender({
+                        aid: cmd.aid,
+                        to: cmd.to,
+                        scope: cmd.scope === 'group' ? 'group' : 'msg',
+                        payload,
+                        file,
+                        mentions: Array.isArray(cmd.mentions)
+                            ? cmd.mentions.filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry))
+                            : undefined,
+                        encrypt: cmd.encrypt === true,
+                        thread: typeof cmd.thread === 'string' ? cmd.thread : undefined,
+                        returnPolicy: cmd.returnPolicy === 'required' || cmd.returnPolicy === 'none' ? cmd.returnPolicy : undefined,
+                        originSessionId: typeof cmd.originSessionId === 'string' ? cmd.originSessionId : undefined,
+                        originMessageId: typeof cmd.originMessageId === 'string' ? cmd.originMessageId : undefined,
+                        delegationToken: typeof cmd.delegationToken === 'string' ? cmd.delegationToken : undefined,
+                        log,
+                    });
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message || String(e) };
+                }
+            }
+            case 'handoff-return': {
+                if (!this.handoffReturnExecutor)
+                    return { ok: false, error: 'handoff return not configured' };
+                if (typeof cmd.content !== 'string')
+                    return { ok: false, code: 'HANDOFF_RETURN_CONTENT_REQUIRED', error: 'missing content' };
+                try {
+                    return await this.handoffReturnExecutor({
+                        sessionId: typeof cmd.sessionId === 'string' ? cmd.sessionId : undefined,
+                        handoffId: typeof cmd.handoffId === 'string' ? cmd.handoffId : undefined,
+                        content: cmd.content,
+                        delegationToken: typeof cmd.delegationToken === 'string' ? cmd.delegationToken : undefined,
+                    });
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message || String(e) };
+                }
+            }
+            case 'handoff-status': {
+                if (!this.handoffStatusExecutor)
+                    return { ok: false, code: 'HANDOFF_STATUS_UNAVAILABLE', error: 'handoff status not configured' };
+                if (!cmd.handoffId || typeof cmd.handoffId !== 'string')
+                    return { ok: false, code: 'INVALID_HANDOFF_ID', error: 'missing handoff_id' };
+                return this.handoffStatusExecutor({
+                    sessionId: typeof cmd.sessionId === 'string' ? cmd.sessionId : undefined,
+                    handoffId: cmd.handoffId,
+                });
+            }
+            case 'handoff-list': {
+                if (!this.handoffListExecutor)
+                    return { ok: false, code: 'HANDOFF_LIST_UNAVAILABLE', error: 'handoff list not configured' };
+                const state = typeof cmd.state === 'string' ? cmd.state : undefined;
+                if (state && !HANDOFF_STATES.includes(state)) {
+                    return { ok: false, code: 'INVALID_HANDOFF_STATE', error: `invalid handoff state: ${state}` };
+                }
+                const limit = cmd.limit === undefined ? undefined : Number(cmd.limit);
+                if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > HANDOFF_QUERY_MAX_LIMIT)) {
+                    return { ok: false, code: 'INVALID_HANDOFF_LIMIT', error: `handoff limit must be an integer from 1 to ${HANDOFF_QUERY_MAX_LIMIT}` };
+                }
+                return this.handoffListExecutor({
+                    sessionId: typeof cmd.sessionId === 'string' ? cmd.sessionId : undefined,
+                    agent: typeof cmd.agent === 'string' ? cmd.agent : undefined,
+                    state: state,
+                    filterSessionId: typeof cmd.filterSessionId === 'string' ? cmd.filterSessionId : undefined,
+                    limit,
+                });
+            }
+            case 'handoff-trace': {
+                if (!this.handoffTraceExecutor)
+                    return { ok: false, code: 'HANDOFF_TRACE_UNAVAILABLE', error: 'handoff trace not configured' };
+                if (!cmd.handoffId || typeof cmd.handoffId !== 'string') {
+                    return { ok: false, code: 'INVALID_HANDOFF_ID', error: 'missing handoff_id' };
+                }
+                const limit = cmd.limit === undefined ? undefined : Number(cmd.limit);
+                if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > HANDOFF_QUERY_MAX_LIMIT)) {
+                    return { ok: false, code: 'INVALID_HANDOFF_LIMIT', error: `handoff limit must be an integer from 1 to ${HANDOFF_QUERY_MAX_LIMIT}` };
+                }
+                return this.handoffTraceExecutor({
+                    sessionId: typeof cmd.sessionId === 'string' ? cmd.sessionId : undefined,
+                    agent: typeof cmd.agent === 'string' ? cmd.agent : undefined,
+                    handoffId: cmd.handoffId,
+                    limit,
+                });
+            }
+            case 'ctl': {
+                if (!this.commandExecutor)
+                    return { ok: false, error: 'ctl not configured' };
+                const { cmd: slashCmd, sessionId } = cmd;
+                if (!slashCmd || !sessionId)
+                    return { ok: false, error: 'missing cmd or sessionId' };
+                return await this.commandExecutor(slashCmd, sessionId, typeof cmd.delegationToken === 'string' ? cmd.delegationToken : undefined);
+            }
+            case 'config.op': {
+                if (!this.configOperationExecutor)
+                    return { ok: false, code: 'NOT_CONFIGURED', error: 'config.op not configured' };
+                const { argv, sessionId, delegationToken } = cmd;
+                if (!Array.isArray(argv) || argv.some(value => typeof value !== 'string') || !sessionId) {
+                    return { ok: false, code: 'INVALID_REQUEST', error: 'missing argv or sessionId' };
+                }
+                if (delegationToken !== undefined && typeof delegationToken !== 'string') {
+                    return { ok: false, code: 'INVALID_DELEGATION', error: 'delegationToken must be a string' };
+                }
+                return await this.configOperationExecutor(argv, sessionId, delegationToken);
+            }
+            case 'contact.op': {
+                if (!this.contactOperationExecutor)
+                    return { ok: false, code: 'NOT_CONFIGURED', error: 'contact.op not configured' };
+                const { argv, sessionId, delegationToken } = cmd;
+                if (!Array.isArray(argv) || argv.some(value => typeof value !== 'string') || !sessionId) {
+                    return { ok: false, code: 'INVALID_REQUEST', error: 'missing argv or sessionId' };
+                }
+                if (delegationToken !== undefined && typeof delegationToken !== 'string') {
+                    return { ok: false, code: 'INVALID_DELEGATION', error: 'delegationToken must be a string' };
+                }
+                return await this.contactOperationExecutor(argv, sessionId, delegationToken);
+            }
+            case 'trigger.list':
+            case 'trigger.show':
+            case 'trigger.history':
+            case 'trigger.eventCatalog':
+            case 'trigger.create':
+            case 'trigger.update':
+            case 'trigger.setEnabled':
+            case 'trigger.cancel':
+            case 'trigger.delete':
+            case 'trigger.run': {
+                if (!this.triggerExecutor)
+                    return { ok: false, error: 'trigger executor not configured' };
+                try {
+                    return await this.triggerExecutor(cmd);
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message || String(e) };
+                }
+            }
+            case 'evolagent.list': {
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
+                return { ok: true, agents: this.agentRegistry.list() };
+            }
+            case 'evolagent.show': {
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
+                const name = cmd.name;
+                if (!name || typeof name !== 'string')
+                    return { ok: false, error: 'missing name' };
+                const agent = this.agentRegistry.get(name);
+                if (!agent)
+                    return { ok: false, error: `Agent "${name}" not found` };
+                const info = this.agentRegistry.list().find((i) => i.aid === name);
+                // I7: null-guard list().find() result
+                if (!info)
+                    return { ok: false, error: `Agent "${name}" found but info missing (race?)` };
+                return { ok: true, agent: info };
+            }
+            case 'evolagent.reload': {
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
+                const name = cmd.name;
+                if (!name || typeof name !== 'string')
+                    return { ok: false, error: 'missing name' };
+                const hooks = globalThis.__evolcore_reloadHooks;
+                if (!hooks)
+                    return { ok: false, error: 'Reload hooks not initialized' };
+                try {
+                    const a = this.agentRegistry.get(name);
+                    if (!a)
+                        return { ok: false, error: `Agent "${name}" not found` };
+                    if (!this.agentRegistry.reload)
+                        return { ok: false, error: 'EvolAgentRegistry.reload not available' };
+                    await this.agentRegistry.reload(name, hooks);
+                    return { ok: true, result: `Agent "${name}" reloaded` };
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message || String(e) };
+                }
+            }
+            case 'evolagent.load': {
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
+                const aid = cmd.aid;
+                if (!aid || typeof aid !== 'string')
+                    return { ok: false, error: 'missing aid' };
+                const hotLoad = globalThis.__evolcore_hotLoadAgent;
+                if (!hotLoad)
+                    return { ok: false, error: 'Hot-load handler not initialized' };
+                try {
+                    await hotLoad(aid);
+                    return { ok: true, result: `Agent "${aid}" loaded and online` };
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message || String(e) };
+                }
+            }
+            case 'evolagent.resync': {
+                if (!this.agentRegistry)
+                    return { ok: false, error: 'EvolAgentRegistry not available' };
+                const resync = globalThis.__evolcore_resyncAgents;
+                if (!resync)
+                    return { ok: false, error: 'Resync handler not initialized' };
+                try {
+                    const results = await resync();
+                    return { ok: true, results };
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message || String(e) };
+                }
+            }
+            case 'menu.exec': {
+                if (!this.menuExecutor)
+                    return { ok: false, error: 'menu.exec not configured' };
+                try {
+                    const response = await this.menuExecutor(cmd.payload, cmd.auth);
+                    return { ok: true, response };
+                }
+                catch (e) {
+                    return { ok: false, error: e?.message ?? String(e) };
+                }
+            }
+            case 'monitor-snapshot': {
+                // watch web Monitor 页用：进程级 + 系统级运行指标 + 全局 stats + per-agent 汇总。
+                const mem = process.memoryUsage();
+                const systemMemory = readSystemMemoryUsage();
+                const aids = this.aunAidProvider ? this.aunAidProvider() : [];
+                const aidStats = this.aunAidStatsProvider ? this.aunAidStatsProvider() : [];
+                const statsMap = new Map(aidStats.map((s) => [s.aid, s]));
+                const agentInfos = this.agentRegistry ? this.agentRegistry.list() : [];
+                const agentRuntimeStats = this.agentStatsProvider ? this.agentStatsProvider() : [];
+                const agentRuntimeStatsMap = new Map(agentRuntimeStats.map((s) => [s.aid, s]));
+                const aidStateMap = new Map(aids.map((state) => [state.agentName || state.aid, state]));
+                const agentSummary = summarizeMonitorAgents(agentInfos, aids);
+                const processTree = this.processTreeSnapshot;
+                const processTreeCpu = processTree?.processCount ? processTree.cpuPercent : this.cpuPercent;
+                const processTreeRss = processTree?.processCount ? processTree.rss : mem.rss;
+                const processTreeDetails = processTree ? {
+                    ...processTree,
+                    processes: classifyProcessTree(processTree.processes, process.pid, this.associatedProcessKinds),
+                } : {
+                    rootPid: process.pid,
+                    rootPids: [process.pid],
+                    processCount: 1,
+                    cpuPercent: Math.round(this.cpuPercent * 10) / 10,
+                    rss: mem.rss,
+                    processes: [{
+                            pid: process.pid,
+                            ppid: process.ppid,
+                            name: 'evolcore',
+                            cpuPercent: Math.round(this.cpuPercent * 10) / 10,
+                            rss: mem.rss,
+                            kind: 'daemon',
+                        }],
+                };
+                return {
+                    ok: true,
+                    snapshot: {
+                        ts: Date.now(),
+                        uptimeMs: Math.round(process.uptime() * 1000),
+                        cpuCount: os.cpus().length,
+                        // 进程级：daemon + 子进程 + 登记在册的关联进程树
+                        memory: {
+                            rss: processTreeRss,
+                            heapUsed: mem.heapUsed,
+                            heapTotal: mem.heapTotal,
+                            external: mem.external,
+                        },
+                        cpuPercent: processTreeCpu,
+                        mainProcess: {
+                            pid: process.pid,
+                            cpuPercent: Math.round(this.cpuPercent * 10) / 10,
+                            memory: mem,
+                        },
+                        processTree: processTreeDetails,
+                        // 系统级：整机
+                        system: {
+                            ...systemMemory,
+                            cpuPercent: Math.round(this.sysCpuPercent * 10) / 10,
+                            loadAvg: os.loadavg(), // [1m, 5m, 15m]（Windows 恒 0）
+                        },
+                        stats: this.statsProvider ? this.statsProvider() : null,
+                        agentSummary,
+                        agents: agentInfos.map((a) => ({
+                            aid: a.aid,
+                            agentName: a.name,
+                            status: a.status,
+                            connectionStatus: aidStateMap.get(a.aid)?.status ?? (a.status === 'disabled' ? 'disabled' : 'unavailable'),
+                            online: a.status !== 'disabled' && aidStateMap.get(a.aid)?.status === 'connected',
+                            stats: statsMap.get(a.aid) ?? null,
+                            runtimeStats: agentRuntimeStatsMap.get(a.aid) ?? null,
+                        })),
+                    },
+                };
+            }
+            default:
+                return { error: `unknown command: ${cmd.type}` };
+        }
+    }
+}
+/**
+ * Query the running EvolCore daemon via Unix socket.
+ * Returns null if the service is not running or the socket is unreachable.
+ */
+export function ipcQuery(socketPath, cmd, timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        const conn = net.connect(socketPath);
+        let buf = '';
+        const timer = setTimeout(() => {
+            conn.destroy();
+            resolve(null);
+        }, timeoutMs);
+        conn.on('connect', () => {
+            conn.write(JSON.stringify(cmd) + '\n');
+        });
+        conn.on('data', (data) => {
+            buf += data.toString();
+            const idx = buf.indexOf('\n');
+            if (idx !== -1) {
+                clearTimeout(timer);
+                try {
+                    resolve(JSON.parse(buf.slice(0, idx)));
+                }
+                catch {
+                    resolve(null);
+                }
+                conn.destroy();
+            }
+        });
+        conn.on('error', () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+    });
+}