opencode-metrics-plugin 0.1.5

package/dist/index.js

@@ -0,0 +1,61 @@
+import { createMetricsEngine } from "./metrics-engine.js";
+import { createEventLogger } from "./event-logger.js";
+import { resolveDirs } from "./dirs.js";
+import { backfillFromOpencode } from "./backfill.js";
+export { createMetricsEngine } from "./metrics-engine.js";
+export { configureDirs, defaultDirs, getDirs, resolveDirs, getSummaryFile } from "./dirs.js";
+export { createEventLogger } from "./event-logger.js";
+export { backfillFromOpencode } from "./backfill.js";
+export { querySummaries, countSummaries, getDetail, getSubagentSteps, getSessionRaw, setSessionTaskId, reindexDir, upsertSessionSnapshot, openSummaryDb, closeSummaryDbs, removeSession, extractSummaryFields, snapshotToSummary, detailFromRaw, detailFullFromRaw, sumTokens, subtractTokens, toIsoString, firstUserMessageOf, } from "./summary-store.js";
+/**
+ * 组装一整套"通用统计插件"的运行时：事件记录 + 指标引擎。
+ * 目录为实例级（不产生全局副作用）：defaultDirs → 进程级默认（configureDirs）→ opts.dirs 三层合并。
+ * 同一进程可创建多个 runtime（不同插件各配各目录），scope 门控同时作用于引擎计数与事件写盘。
+ */
+export function createMetricsRuntime(opts = {}) {
+    const dirs = resolveDirs(opts.dirs);
+    const engine = createMetricsEngine({
+        enabled: opts.enabled,
+        scope: opts.scope,
+        dirs,
+        onFlush: opts.onFlush,
+    });
+    const eventLogger = (opts.eventLogging ?? true)
+        ? createEventLogger(true, false, {
+            eventsDir: dirs.eventsDir,
+            // 事件记录与引擎共用同一归属判定：引擎不统计的会话不写事件日志
+            isTracked: (sessionId, event) => engine.shouldTrack(sessionId, event.type, event.properties),
+        })
+        : null;
+    if (opts.backfillOnStart) {
+        const scope = opts.scope ?? { mode: "all" };
+        const staticallyAttributable = scope.mode === "all" || (scope.agents?.length ?? 0) > 0 || (scope.cwdPrefixes?.length ?? 0) > 0;
+        if (staticallyAttributable) {
+            setImmediate(() => {
+                backfillFromOpencode({
+                    engines: [{
+                            label: "self",
+                            metricsDir: dirs.metricsDir,
+                            agents: scope.agents,
+                            cwdPrefixes: scope.cwdPrefixes,
+                            summaryFile: dirs.summaryFile, // 与 live flush 同库（缺省全局共享库）
+                        }],
+                    skipExisting: true,
+                    incremental: true,
+                }).catch((err) => {
+                    console.error("[opencode-metrics-plugin] 启动增量回填失败:", err);
+                });
+            });
+        }
+    }
+    return {
+        dirs,
+        eventLogger,
+        engine,
+        /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
+        event(input) {
+            eventLogger?.log(input.event);
+            engine.ingest(input.event);
+        },
+    };
+}

package/dist/logger.d.ts

@@ -0,0 +1,10 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare function setLogLevel(level: LogLevel): void;
+export declare function getLogLevel(): LogLevel;
+export declare function flushLogs(): void;
+export declare const log: {
+    debug(...parts: unknown[]): void;
+    info(...parts: unknown[]): void;
+    warn(...parts: unknown[]): void;
+    error(...parts: unknown[]): void;
+};

package/dist/logger.js

@@ -0,0 +1,76 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { getLogFile } from './dirs.js';
+const LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+let minOrder = LEVEL_ORDER.info;
+export function setLogLevel(level) {
+    minOrder = LEVEL_ORDER[level];
+}
+export function getLogLevel() {
+    return Object.keys(LEVEL_ORDER).find((k) => LEVEL_ORDER[k] === minOrder) ?? 'info';
+}
+let buffer = [];
+let flushTimer = null;
+const FLUSH_INTERVAL_MS = 500;
+const BUFFER_SIZE_LIMIT = 50;
+function writeLine(line) {
+    const logFile = getLogFile();
+    try {
+        fs.mkdirSync(path.dirname(logFile), { recursive: true });
+        fs.appendFileSync(logFile, line + '\n');
+    }
+    catch {
+        // 文件不可写时回退 console，避免静默吞日志
+        console.log(line);
+    }
+}
+function push(line) {
+    buffer.push(line);
+    if (buffer.length >= BUFFER_SIZE_LIMIT) {
+        const batch = buffer;
+        buffer = [];
+        batch.forEach(writeLine);
+    }
+    else if (!flushTimer) {
+        flushTimer = setTimeout(() => {
+            flushTimer = null;
+            const batch = buffer;
+            buffer = [];
+            batch.forEach(writeLine);
+        }, FLUSH_INTERVAL_MS);
+        flushTimer.unref?.();
+    }
+}
+export function flushLogs() {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    const batch = buffer;
+    buffer = [];
+    batch.forEach(writeLine);
+}
+function fmt(level, parts) {
+    const ts = new Date().toISOString();
+    const msg = parts.map((p) => {
+        if (typeof p === 'string')
+            return p;
+        try {
+            return JSON.stringify(p);
+        }
+        catch {
+            return String(p);
+        }
+    }).join(' ');
+    return `${ts} [${level}] ${msg}`;
+}
+export const log = {
+    debug(...parts) { if (LEVEL_ORDER.debug >= minOrder)
+        push(fmt('debug', parts)); },
+    info(...parts) { if (LEVEL_ORDER.info >= minOrder)
+        push(fmt('info', parts)); },
+    warn(...parts) { if (LEVEL_ORDER.warn >= minOrder)
+        push(fmt('warn', parts)); },
+    error(...parts) { if (LEVEL_ORDER.error >= minOrder)
+        push(fmt('error', parts)); },
+};

package/dist/metrics-engine.d.ts

@@ -0,0 +1,37 @@
+import type { MetricsEngine, MetricsOutput } from "./metrics-types.js";
+import type { MetricsDirs } from "./dirs.js";
+export type { TokenUsage, ToolStats, StageType, StageInfo, MessageEntry, ToolCallEntry, SessionMeta, CompileStats, SkillCallEntry, SkillSearchEntry, StepData, RoundSnapshot, SubAgentOutput, MetricsOutput, MetricsEngine, } from "./metrics-types.js";
+export type MetricsScopeMode = "all" | "none" | "declared" | "cwd";
+export interface MetricsScope {
+    mode: MetricsScopeMode;
+    /** 交叉生效的 agent 白名单：非空时仅统计这些 agent 名的会话（session.created/updated 的 info.agent） */
+    agents?: string[];
+    /** mode==='cwd' 时生效：仅统计工作目录命中这些前缀的会话 */
+    cwdPrefixes?: string[];
+}
+export interface MetricsEngineOptions {
+    enabled?: boolean;
+    scope?: MetricsScope;
+    /** 本引擎专属输出目录（多引擎各自独立）；缺省回退进程级默认（configureDirs），构造时解析固化 */
+    dirs?: Partial<MetricsDirs>;
+    /** flush 会话快照后回调（宿主可在此把快照写入 DB/上报，替代或补充文件落盘） */
+    onFlush?: (sessionId: string, snapshot: MetricsOutput) => void;
+}
+/**
+ * 创建指标引擎。
+ * 兼容旧布尔入参：true = scope all，false = scope none。
+ * 统计范围 = 策略 + 宿主声明（claimSession）的交集判定：
+ *   - mode all     —— 全部（配合 agents 即只统计白名单 agent）
+ *   - mode none    —— 默认不统计；宿主 claimSession 才统计
+ *   - mode declared—— 仅宿主 claimSession 的会话（或 agents 白名单命中）
+ *   - mode cwd     —— 仅工作目录命中 cwdPrefixes
+ * 子会话（parentID 归属已统计父会话）自动随父会话统计。
+ */
+export declare function createMetricsEngine(opts?: MetricsEngineOptions | boolean): MetricsEngine & {
+    claimSession: (sessionId: string, meta?: {
+        agent?: string;
+    }) => void;
+    scopeOf: (sessionId: string) => boolean;
+    /** 归属判定（供 event-logger 等共用同一 scope 语义；与 ingest 内部判定一致） */
+    shouldTrack: (sessionId: string, eventType: string, props: Record<string, unknown> | undefined) => boolean;
+};

package/dist/metrics-engine.js

@@ -0,0 +1,331 @@
+import { createSessionMetrics, TRACKED_EVENT_TYPES } from "./metrics-types.js";
+import { handlePartUpdated, handleSessionUpdated, handleMessageUpdated, handleSubAgentParts } from "./metrics-handlers.js";
+import { handleSessionIdle, flushMetrics, mergeChildMetrics } from "./metrics-output.js";
+import { resolveDirs } from "./dirs.js";
+import { log } from "./logger.js";
+/**
+ * 创建指标引擎。
+ * 兼容旧布尔入参：true = scope all，false = scope none。
+ * 统计范围 = 策略 + 宿主声明（claimSession）的交集判定：
+ *   - mode all     —— 全部（配合 agents 即只统计白名单 agent）
+ *   - mode none    —— 默认不统计；宿主 claimSession 才统计
+ *   - mode declared—— 仅宿主 claimSession 的会话（或 agents 白名单命中）
+ *   - mode cwd     —— 仅工作目录命中 cwdPrefixes
+ * 子会话（parentID 归属已统计父会话）自动随父会话统计。
+ */
+export function createMetricsEngine(opts = { enabled: true, scope: { mode: "all" } }) {
+    const options = typeof opts === "boolean"
+        ? { enabled: opts, scope: { mode: opts ? "all" : "none" } }
+        : opts;
+    const enabled = options.enabled !== false;
+    const scope = options.scope ?? { mode: "all" };
+    // 实例目录：构造时按 defaultDirs → 进程级默认 → 实例传入 三层合并固化；未传则 flush 时动态回退进程级默认
+    const instanceDirs = options.dirs ? resolveDirs(options.dirs) : undefined;
+    const agents = scope.agents && scope.agents.length > 0 ? new Set(scope.agents) : null;
+    const cwdPrefixes = scope.cwdPrefixes ?? [];
+    const sessions = new Map();
+    const childToParent = new Map();
+    const childSessionIds = new Set();
+    const claimed = new Set();
+    // 已定案的会话统计与否（false 不缓存“信息未齐”的暂定，等 session.created 带 agent/dir 再定）
+    const resolved = new Map();
+    // 工作目录缓存（session.created 记录；cwd 策略与删除时反查用）
+    const sessionDirs = new Map();
+    const sessionAgents = new Map();
+    function decideFresh(id, agent, directory) {
+        if (claimed.has(id))
+            return true;
+        if (agents) {
+            if (!agent || !agents.has(agent))
+                return false;
+        }
+        switch (scope.mode) {
+            case "all": return true;
+            case "none": return false;
+            case "declared": return false;
+            case "cwd": return directory != null && cwdPrefixes.some((p) => directory.startsWith(p));
+            default: return false;
+        }
+    }
+    /** 需等待 agent/directory 才可定案（事件带信息前先跳过，session.created 到达后定案）。 */
+    function needsInfo(id, agent, directory) {
+        if (agents && !agent)
+            return true;
+        if (scope.mode === "cwd" && directory == null)
+            return true;
+        return false;
+    }
+    function resolveSessionId(rawId) {
+        return childToParent.get(rawId) ?? rawId;
+    }
+    /** 判断事件目标会话是否纳入统计（子会话跟随父会话定案）。 */
+    function isTracked(id, eventType, props) {
+        let target = id;
+        if (id.startsWith("__migrate__:")) {
+            target = id.split(":")[2] ?? "";
+        }
+        else {
+            target = childToParent.get(id) ?? id;
+        }
+        if (!target)
+            return false;
+        const info = (props?.info ?? {});
+        const agent = typeof info.agent === "string" ? info.agent : sessionAgents.get(target);
+        const directory = typeof info.directory === "string" ? info.directory : sessionDirs.get(target);
+        // 记录目录/agent（含迁移解析出的父子关系场景）
+        if (eventType === "session.created" || eventType === "session.updated") {
+            if (typeof info.directory === "string")
+                sessionDirs.set(target, info.directory);
+            if (typeof info.agent === "string")
+                sessionAgents.set(target, info.agent);
+        }
+        const cached = resolved.get(target);
+        if (cached !== undefined)
+            return cached;
+        if (needsInfo(target, agent, directory))
+            return false;
+        const decision = decideFresh(target, agent, directory);
+        resolved.set(target, decision);
+        return decision;
+    }
+    function extractSessionId(event) {
+        const props = event.properties;
+        if (!props) {
+            log.info("[Metrics] extractSessionId: no props", { type: event.type });
+            return undefined;
+        }
+        if (event.type === "session.created" || event.type === "session.updated") {
+            const info = props.info;
+            if (info) {
+                const id = info.id;
+                const parentID = info.parentID;
+                if (id && parentID) {
+                    childToParent.set(id, parentID);
+                    childSessionIds.add(id);
+                    const agentName = info.agent || "";
+                    const title = info.title || "";
+                    log.info("[Metrics] MIGRATE detected", { type: event.type, id, parentID, agentName, title });
+                    return `__migrate__:${id}:${parentID}:${agentName}:${title}`;
+                }
+                if (id)
+                    return id;
+            }
+        }
+        const sessionID = props.sessionID;
+        if (sessionID)
+            return resolveSessionId(sessionID);
+        const info = props.info;
+        if (info?.id)
+            return resolveSessionId(info.id);
+        log.info("[Metrics] extractSessionId: no sessionID found", { type: event.type, hasSessionID: !!props.sessionID, hasInfo: !!info, hasInfoId: !!info?.id });
+        return undefined;
+    }
+    function getOrCreateSession(sessionId) {
+        let state = sessions.get(sessionId);
+        if (!state) {
+            state = createSessionMetrics(sessionId);
+            sessions.set(sessionId, state);
+        }
+        return state;
+    }
+    return {
+        ingest(event) {
+            if (!enabled)
+                return;
+            if (!TRACKED_EVENT_TYPES.has(event.type))
+                return;
+            let sessionId = extractSessionId(event);
+            if (!sessionId) {
+                log.info("[Metrics] DROPPED event — no sessionId", { type: event.type });
+                return;
+            }
+            const props = event.properties;
+            // 统计范围门：未纳入范围的会话整条丢弃（含其子代理）
+            if (!isTracked(sessionId, event.type, props))
+                return;
+            // Handle buffer migration when sub-agent relationship is discovered
+            if (sessionId.startsWith("__migrate__:")) {
+                const parts = sessionId.split(":");
+                const childId = parts[1];
+                const parentId = parts[2];
+                const agentName = parts[3] || "";
+                const title = parts[4] || "";
+                sessionId = parentId;
+                const parentState = getOrCreateSession(parentId);
+                // Merge child's existing metrics to parent
+                const childState = sessions.get(childId);
+                if (childState) {
+                    log.info("[Metrics] Migration: merging existing child state", { childId, parentId });
+                    mergeChildMetrics(parentState, childState, { childId, agentName, title });
+                    sessions.delete(childId);
+                    childToParent.delete(childId);
+                    childSessionIds.delete(childId);
+                }
+                else {
+                    if (!parentState.subAgents.has(childId)) {
+                        parentState.subAgents.set(childId, {
+                            sessionId: childId,
+                            agentName,
+                            title,
+                            messageMap: new Map(),
+                            toolCallMap: new Map(),
+                            textLengthMap: new Map(),
+                            orderCounter: 0,
+                            _userMessageIds: new Set(),
+                            _pendingUserMessage: [],
+                        });
+                        log.info("[Metrics] SubAgent entry created", { childId, subAgentsSize: parentState.subAgents.size });
+                    }
+                }
+            }
+            const state = getOrCreateSession(sessionId);
+            // Sub-agent routing: check if the original event was from a child session
+            const originalSessionId = props?.sessionID || "";
+            if (childSessionIds.has(originalSessionId)) {
+                const sub = state.subAgents.get(originalSessionId);
+                if (sub) {
+                    handleSubAgentParts(sub, event);
+                    return;
+                }
+                else {
+                    log.info("[Metrics] Sub-agent routing MISS — entry not found", { eventType: event.type, originalSessionId, subAgentsKeys: [...state.subAgents.keys()] });
+                }
+            }
+            // Extract directory from session.created
+            if (event.type === "session.created" && props) {
+                const info = props.info;
+                const directory = info?.directory;
+                if (directory) {
+                    state.sessionMeta.workingDirectory = directory;
+                    sessionDirs.set(sessionId, directory);
+                }
+            }
+            // Track per-round first event time
+            if (!state._hasFirstEvent) {
+                state._hasFirstEvent = true;
+                state._firstEventTime = Date.now();
+            }
+            // Route to handler by event type
+            if (event.type === "message.part.updated" && props) {
+                handlePartUpdated(state, props);
+            }
+            if (event.type === "session.updated" && props) {
+                handleSessionUpdated(state, props);
+            }
+            if (event.type === "session.idle") {
+                const snapshot = handleSessionIdle(state, sessionId, instanceDirs);
+                if (options.onFlush && snapshot) {
+                    try {
+                        options.onFlush(sessionId, snapshot);
+                    }
+                    catch (err) {
+                        log.error("[Metrics] onFlush failed", { sessionId, error: String(err) });
+                    }
+                }
+            }
+            if (event.type === "session.compacted") {
+                state.compactions++;
+            }
+            if (event.type === "session.error") {
+                state._roundErrors++;
+            }
+            if (event.type === "message.updated" && props) {
+                handleMessageUpdated(state, props);
+            }
+            if (event.type === "permission.asked" ||
+                event.type === "permission.replied" ||
+                event.type === "command.executed") {
+                if (!state.anomaly.events.includes(event.type)) {
+                    state.anomaly.triggered = true;
+                    state.anomaly.events.push(event.type);
+                }
+            }
+        },
+        ingestPrompt(sessionId, modelId, system) {
+            if (!enabled)
+                return;
+            const resolvedId = resolveSessionId(sessionId);
+            const allowed = (scope.mode === "all" && !agents) ||
+                claimed.has(resolvedId) ||
+                resolved.get(resolvedId) === true;
+            if (!allowed)
+                return;
+            const state = getOrCreateSession(resolvedId);
+            state.systemPrompts.set(modelId, system);
+        },
+        isSubAgent(sessionId) {
+            return childSessionIds.has(sessionId);
+        },
+        flush(sessionId) {
+            const state = sessions.get(sessionId);
+            if (!state)
+                return;
+            const now = Date.now();
+            state.endTime = now;
+            const snapshot = flushMetrics(sessionId, state, now, instanceDirs);
+            if (options.onFlush && snapshot) {
+                try {
+                    options.onFlush(sessionId, snapshot);
+                }
+                catch (err) {
+                    log.error("[Metrics] onFlush failed", { sessionId, error: String(err) });
+                }
+            }
+        },
+        dispose() {
+            const now = Date.now();
+            for (const [sessionId, state] of sessions) {
+                if (state._idleFlushed)
+                    continue;
+                if (state.currentStage) {
+                    state.currentStage.endTime = now;
+                    state.currentStage.tokens = { ...state._stageTokens };
+                    if (state.currentStage.stage === "build") {
+                        state.currentStage.hvigorwCalls = state.compileStats.hvigorwCalls;
+                    }
+                    state.stages.push(state.currentStage);
+                    state.currentStage = null;
+                }
+                state.lastStageEndTime = now;
+                if (state.compileStats._pendingFix) {
+                    state.compileStats.fixCycles.push({
+                        failTime: state.compileStats._pendingFix.failTime,
+                        successTime: 0,
+                        attempts: state.compileStats._pendingFix.attempts,
+                        codeChanges: state.compileStats._pendingFix.codeChanges,
+                    });
+                    state.compileStats._pendingFix = null;
+                }
+                state.endTime = now;
+                const snapshot = flushMetrics(sessionId, state, now, instanceDirs);
+                if (options.onFlush && snapshot) {
+                    try {
+                        options.onFlush(sessionId, snapshot);
+                    }
+                    catch (err) {
+                        log.error("[Metrics] onFlush failed", { sessionId, error: String(err) });
+                    }
+                }
+            }
+            sessions.clear();
+            childToParent.clear();
+            childSessionIds.clear();
+        },
+        claimSession(sessionId, meta) {
+            claimed.add(sessionId);
+            if (meta?.agent)
+                sessionAgents.set(sessionId, meta.agent);
+            // 允许 claim 推翻早前“信息未齐暂不统计”的判定；宿主显式声明即强制纳入
+            resolved.set(sessionId, true);
+        },
+        scopeOf(sessionId) {
+            const v = resolved.get(sessionId);
+            if (v !== undefined)
+                return v;
+            return claimed.has(sessionId);
+        },
+        shouldTrack(sessionId, eventType, props) {
+            return isTracked(sessionId, eventType, props);
+        },
+    };
+}

package/dist/metrics-handlers.d.ts

@@ -0,0 +1,9 @@
+import type { SessionMetricsState, SubAgentState } from "./metrics-types.js";
+declare function handlePartUpdated(state: SessionMetricsState, props: Record<string, unknown>): void;
+declare function handleSessionUpdated(state: SessionMetricsState, props: Record<string, unknown>): void;
+declare function handleMessageUpdated(state: SessionMetricsState, props: Record<string, unknown>): void;
+declare function handleSubAgentParts(sub: SubAgentState, event: {
+    type: string;
+    properties?: Record<string, unknown>;
+}): void;
+export { handlePartUpdated, handleSessionUpdated, handleMessageUpdated, handleSubAgentParts };