opencode-metrics-plugin 0.1.5

package/dist/compile-analyzer.js

@@ -0,0 +1,161 @@
+/**
+ * compile-analyzer.ts — Pure-function module for parsing hvigorw build output
+ * and extracting compile metrics (errors, warnings, module timings).
+ */
+// ─── Duration parsing ───────────────────────────────────────────────────────
+function parseDuration(text) {
+    let ms = 0;
+    const secMatch = text.match(/(\d+)\s*s\b/);
+    if (secMatch)
+        ms += parseInt(secMatch[1], 10) * 1000;
+    const msMatch = text.match(/(\d+)\s*ms/);
+    if (msMatch)
+        ms += parseInt(msMatch[1], 10);
+    return ms;
+}
+// ─── stripAnsi ──────────────────────────────────────────────────────────────
+export function stripAnsi(raw) {
+    return raw.replace(/\x1b\[[0-9;]*m/g, "").replace(/\r\n/g, "\n");
+}
+// ─── extractErrorCodes ──────────────────────────────────────────────────────
+export function extractErrorCodes(stripped) {
+    const errors = [];
+    const seen = new Set();
+    // Strict match: N ERROR: code Type\nError Message: ... At File: path:line:col
+    const strictRegex = /(\d+)\s+ERROR:\s+(\d+)\s+(.+?)\nError Message:\s+(.+?)\s+At [Ff]ile:\s+(.+?):(\d+)(?::(\d+))?/g;
+    let match;
+    while ((match = strictRegex.exec(stripped)) !== null) {
+        errors.push({
+            code: match[2],
+            type: match[3],
+            message: match[4],
+            file: match[5],
+            line: parseInt(match[6], 10),
+            col: match[7] ? parseInt(match[7], 10) : 0,
+        });
+        seen.add(match[1]);
+    }
+    // Fallback: match N ERROR: code Type without requiring Error Message line
+    const fallbackRegex = /(\d+)\s+ERROR:\s+(\d+)\s+(.+?)(?:\r?\n|$)/g;
+    while ((match = fallbackRegex.exec(stripped)) !== null) {
+        if (!seen.has(match[1])) {
+            errors.push({
+                code: match[2],
+                type: match[3].trim(),
+                message: "",
+                file: "",
+                line: 0,
+                col: 0,
+            });
+        }
+    }
+    return errors;
+}
+// ─── extractWarnings ────────────────────────────────────────────────────────
+function classifyWarning(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes("deprecated"))
+        return "deprecated_api";
+    if (lower.includes("conflict"))
+        return "resource_conflict";
+    if (/\bsign\b/.test(lower) || lower.includes("signingconfigs"))
+        return "signing";
+    if (lower.includes("obfuscation"))
+        return "obfuscation";
+    return "other";
+}
+export function extractWarnings(stripped) {
+    const warnings = [];
+    // ArkTS warnings with file location
+    const arktsRegex = /WARN:\s+ArkTS:WARN\s+File:\s+(.+?):(\d+):\d+\n\s+(.+)/g;
+    let match;
+    while ((match = arktsRegex.exec(stripped)) !== null) {
+        const message = match[3].trim();
+        warnings.push({
+            type: classifyWarning(message),
+            message,
+            file: match[1],
+            line: parseInt(match[2], 10),
+        });
+    }
+    // Build-system warnings (WARN: or Warning:)
+    const buildRegex = /^(?:WARN:\s+|Warning:\s+)(.+)$/gm;
+    while ((match = buildRegex.exec(stripped)) !== null) {
+        // Skip lines already captured as ArkTS warnings
+        if (/ArkTS:WARN/.test(match[0]))
+            continue;
+        const message = match[1].trim();
+        warnings.push({
+            type: classifyWarning(message),
+            message,
+        });
+    }
+    return warnings;
+}
+// ─── extractModuleTimings ───────────────────────────────────────────────────
+export function extractModuleTimings(stripped) {
+    const timings = new Map();
+    // Module tasks: Finished :moduleName:default@taskName... after X ms
+    const moduleRegex = /Finished\s+:(\w+):\S+?@(\w+)\.\.\.\s+after\s+(.+?)$/gm;
+    let match;
+    while ((match = moduleRegex.exec(stripped)) !== null) {
+        const moduleName = match[1];
+        const taskName = match[2];
+        const duration = parseDuration(match[3]);
+        addTiming(timings, moduleName, taskName, duration);
+    }
+    // Root module: Finished ::default... after X ms
+    const rootRegex = /Finished\s+::(\w+)\.\.\.\s+after\s+(.+?)$/gm;
+    while ((match = rootRegex.exec(stripped)) !== null) {
+        const taskName = match[1];
+        const duration = parseDuration(match[2]);
+        addTiming(timings, "(root)", taskName, duration);
+    }
+    return timings;
+}
+function addTiming(timings, moduleName, taskName, duration) {
+    const existing = timings.get(moduleName);
+    if (existing) {
+        existing.totalDuration += duration;
+        existing.taskCount += 1;
+        if (duration > existing.slowestTask.duration) {
+            existing.slowestTask = { name: taskName, duration };
+        }
+    }
+    else {
+        timings.set(moduleName, {
+            totalDuration: duration,
+            taskCount: 1,
+            slowestTask: { name: taskName, duration },
+        });
+    }
+}
+// ─── parseHvigorwOutput ─────────────────────────────────────────────────────
+export function parseHvigorwOutput(raw) {
+    const stripped = stripAnsi(raw);
+    // BUILD result
+    let success = false;
+    let duration = 0;
+    const buildMatch = stripped.match(/BUILD\s+(SUCCESSFUL|FAILED)\s+in\s+(.+?)$/m);
+    if (buildMatch) {
+        success = buildMatch[1] === "SUCCESSFUL";
+        duration = parseDuration(buildMatch[2]);
+    }
+    // COMPILE RESULT
+    let errorCount = 0;
+    let warnCount = 0;
+    const compileMatch = stripped.match(/COMPILE RESULT:(?:FAIL|SUCCESS)\s+\{ERROR:(\d+)\s+WARN:(\d+)\}/);
+    if (compileMatch) {
+        errorCount = parseInt(compileMatch[1], 10);
+        warnCount = parseInt(compileMatch[2], 10);
+    }
+    return {
+        success,
+        duration,
+        errorCount,
+        warnCount,
+        errors: extractErrorCodes(stripped),
+        warnings: extractWarnings(stripped),
+        moduleTimings: extractModuleTimings(stripped),
+    };
+}

package/dist/dirs.d.ts

@@ -0,0 +1,34 @@
+/** metrics/events 写入目录集。host 可自定义；默认按应用名 env paths（与 session-viewer-plugin 约定一致）。 */
+export interface MetricsDirs {
+    /** 会话快照 JSON 目录（<sessionId>.json 直接落这里；各宿主必须隔离，避免多写者冲突） */
+    metricsDir: string;
+    /** events 逐会话日志目录 */
+    eventsDir: string;
+    /** 运行日志文件（可选；logger 无文件权限时回退 console） */
+    logFile: string;
+    /**
+     * 摘要/详情双表 sqlite 落点。缺省为包级全局路径：本机多宿主共享同一个 summary.db，
+     * 查询一处即可获得全部宿主的会话摘要。显式传入本字段的宿主可获得独立隔离库。
+     * （快照 JSON 目录仍按宿主隔离，summary 双表在库层聚合。）
+     */
+    summaryFile: string;
+}
+export declare function defaultDirs(appName?: string): MetricsDirs;
+/**
+ * 供 host 设定进程级默认目录（未显式传 dirs 的引擎/事件记录器使用）。
+ * 注意：多引擎场景请优先在 createMetricsEngine/createEventLogger 实例级传 dirs，
+ * 进程级配置仅作默认兜底，避免多宿主互相覆盖。
+ * summaryFile 未显式配置时保持包级全局路径（跨宿主聚合语义）。
+ */
+export declare function configureDirs(dirs: Partial<MetricsDirs>): void;
+/** 当前进程级默认目录（defaultDirs 与 configureDirs 的合并结果）。 */
+export declare function getDirs(): MetricsDirs;
+/**
+ * 解析实例目录：defaultDirs → 进程级默认（configureDirs）→ 实例传入，三层合并。
+ * summaryFile 不随 metricsDir 派生：缺省恒为全局共享库（实例/进程级显式指定才能改写）。
+ */
+export declare function resolveDirs(partial?: Partial<MetricsDirs>): MetricsDirs;
+export declare function getMetricsDir(): string;
+export declare function getEventsDir(): string;
+export declare function getLogFile(): string;
+export declare function getSummaryFile(): string;

package/dist/dirs.js

@@ -0,0 +1,44 @@
+import envPaths from 'env-paths';
+import path from 'path';
+export function defaultDirs(appName = 'opencode-metrics-plugin') {
+    const base = envPaths(appName, { suffix: '' });
+    return {
+        metricsDir: path.join(base.log, 'metrics'),
+        eventsDir: path.join(base.log, 'events'),
+        logFile: path.join(base.log, 'plugin.log'),
+        summaryFile: path.join(base.log, 'summary.db'),
+    };
+}
+let _dirs = defaultDirs();
+/**
+ * 供 host 设定进程级默认目录（未显式传 dirs 的引擎/事件记录器使用）。
+ * 注意：多引擎场景请优先在 createMetricsEngine/createEventLogger 实例级传 dirs，
+ * 进程级配置仅作默认兜底，避免多宿主互相覆盖。
+ * summaryFile 未显式配置时保持包级全局路径（跨宿主聚合语义）。
+ */
+export function configureDirs(dirs) {
+    _dirs = { ...defaultDirs(), ...dirs };
+}
+/** 当前进程级默认目录（defaultDirs 与 configureDirs 的合并结果）。 */
+export function getDirs() {
+    return _dirs;
+}
+/**
+ * 解析实例目录：defaultDirs → 进程级默认（configureDirs）→ 实例传入，三层合并。
+ * summaryFile 不随 metricsDir 派生：缺省恒为全局共享库（实例/进程级显式指定才能改写）。
+ */
+export function resolveDirs(partial) {
+    return partial ? { ...getDirs(), ...partial } : { ...getDirs() };
+}
+export function getMetricsDir() {
+    return _dirs.metricsDir;
+}
+export function getEventsDir() {
+    return _dirs.eventsDir;
+}
+export function getLogFile() {
+    return _dirs.logFile;
+}
+export function getSummaryFile() {
+    return _dirs.summaryFile;
+}

package/dist/event-logger.d.ts

@@ -0,0 +1,20 @@
+export interface EventLogger {
+    log(event: {
+        type: string;
+        properties?: Record<string, unknown>;
+    }): void;
+    logPrompt(sessionId: string, type: string, content: string[]): void;
+    isSubAgent(sessionId: string): boolean;
+    flush(): void;
+    dispose(): void;
+}
+export interface EventLoggerOptions {
+    /** 本实例事件日志目录（多引擎场景各自独立）；缺省回退进程级默认（configureDirs） */
+    eventsDir?: string;
+    /** 会话归属门控：返回 false 的事件不写入本实例日志（与引擎共用同一 scope 判定） */
+    isTracked?: (sessionId: string, event: {
+        type: string;
+        properties?: Record<string, unknown>;
+    }) => boolean;
+}
+export declare function createEventLogger(enabled: boolean, cleanupEnabled?: boolean, opts?: EventLoggerOptions): EventLogger;

package/dist/event-logger.js

@@ -0,0 +1,329 @@
+import * as fs from "fs";
+import * as path from "path";
+import { getEventsDir } from "./dirs.js";
+import { TRACKED_EVENT_TYPES } from "./metrics-types.js";
+// Rotation constants
+const MAX_LOG_SIZE_BYTES = 20 * 1024 * 1024;
+const MAX_LOG_AGE_DAYS = 7;
+const MAX_ROTATED_FILES = 5;
+const FLUSH_INTERVAL_MS = 500;
+const BUFFER_SIZE_LIMIT = 50;
+const SEPARATOR = "=".repeat(72);
+// 鈹€鈹€鈹€ Helpers 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+function formatTimestamp(date) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const ms = String(Math.floor(date.getMilliseconds() / 10)).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${ms}`;
+}
+function formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const m = Math.floor(seconds / 60);
+    const s = seconds % 60;
+    return m > 0 ? `${m}m ${s}s` : `${s}s`;
+}
+// Maps child sessionID → parent sessionID for sub-agent sessions（实例级，见 createEventLogger 闭包）
+function getLogFile(sessionId, eventsDir) {
+    return path.join(eventsDir, `${sessionId}.log`);
+}
+function safeJson(obj, indent = 2) {
+    try {
+        return JSON.stringify(obj, null, indent);
+    }
+    catch {
+        return String(obj);
+    }
+}
+// 鈹€鈹€鈹€ Rotation 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/** Delete all event log files older than MAX_LOG_AGE_DAYS */
+function cleanupStaleLogs(eventsDir) {
+    try {
+        if (!fs.existsSync(eventsDir))
+            return;
+        const entries = fs.readdirSync(eventsDir);
+        const now = Date.now();
+        const maxAgeMs = MAX_LOG_AGE_DAYS * 24 * 60 * 60 * 1000;
+        for (const file of entries) {
+            if (!file.endsWith(".log"))
+                continue;
+            const full = path.join(eventsDir, file);
+            try {
+                if (now - fs.statSync(full).mtimeMs > maxAgeMs) {
+                    fs.unlinkSync(full);
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+}
+function cleanupRotatedLogs(sessionId, eventsDir) {
+    try {
+        const entries = fs.readdirSync(eventsDir);
+        const prefix = `${sessionId}.`;
+        const rotated = entries
+            .filter((f) => f.startsWith(prefix) && f.endsWith(".log") && f !== `${sessionId}.log`)
+            .map((f) => {
+            const full = path.join(eventsDir, f);
+            try {
+                return { file: full, mtimeMs: fs.statSync(full).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((e) => e !== null);
+        const now = Date.now();
+        const maxAgeMs = MAX_LOG_AGE_DAYS * 24 * 60 * 60 * 1000;
+        for (const entry of rotated) {
+            if (now - entry.mtimeMs > maxAgeMs) {
+                try {
+                    fs.unlinkSync(entry.file);
+                }
+                catch { }
+            }
+        }
+        const surviving = rotated
+            .filter((e) => now - e.mtimeMs <= maxAgeMs)
+            .sort((a, b) => a.mtimeMs - b.mtimeMs);
+        if (surviving.length > MAX_ROTATED_FILES) {
+            const doomed = surviving.slice(0, surviving.length - MAX_ROTATED_FILES);
+            for (const entry of doomed) {
+                try {
+                    fs.unlinkSync(entry.file);
+                }
+                catch { }
+            }
+        }
+    }
+    catch { }
+}
+function rotateIfNeeded(sessionId, eventsDir) {
+    try {
+        const logFile = getLogFile(sessionId, eventsDir);
+        const stat = fs.statSync(logFile);
+        if (stat.size >= MAX_LOG_SIZE_BYTES) {
+            const now = new Date();
+            const pad = (n) => String(n).padStart(2, "0");
+            const ts = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+            fs.renameSync(logFile, path.join(eventsDir, `${sessionId}.${ts}.log`));
+        }
+    }
+    catch { }
+}
+// 鈹€鈹€鈹€ Log Formatting 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+function formatEventBlock(ts, eventType, properties, subAgent) {
+    const lines = [];
+    const tag = subAgent ? ` [sub-agent:${subAgent.childId}]` : "";
+    lines.push(`[${ts}] EVENT:${tag} ${eventType}`);
+    if (properties && Object.keys(properties).length > 0) {
+        lines.push(`  DATA: ${safeJson(properties)}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function formatSessionSummary(startTime, roundCount) {
+    const duration = Date.now() - startTime;
+    const lines = [];
+    lines.push("");
+    lines.push(SEPARATOR);
+    lines.push("  SESSION SUMMARY");
+    lines.push(SEPARATOR);
+    lines.push("");
+    lines.push(`  Duration:           ${formatDuration(duration)}`);
+    lines.push(`  Rounds:             ${roundCount}`);
+    lines.push(`  End Time: ${formatTimestamp(new Date())}`);
+    lines.push(SEPARATOR);
+    lines.push("");
+    return lines.join("\n");
+}
+export function createEventLogger(enabled, cleanupEnabled = false, opts = {}) {
+    const sessionBuffers = new Map();
+    // 子代理父子映射（实例级，多引擎互不共享）
+    const childToParent = new Map();
+    const childSessionIds = new Set();
+    // 实例目录优先，未配置时动态回退进程级默认（保持 configureDirs 后生效的旧行为）
+    const evDir = () => opts.eventsDir ?? getEventsDir();
+    function resolveSessionId(rawId) {
+        return childToParent.get(rawId) ?? rawId;
+    }
+    function extractSessionId(event) {
+        const props = event.properties;
+        if (!props)
+            return undefined;
+        // session.created/updated — detect sub-agent and record parent mapping
+        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);
+                    // Return both childId (for buffer migration) and parentId (for logging)
+                    return `__migrate__:${id}:${parentID}`;
+                }
+                if (id)
+                    return id;
+            }
+        }
+        const sessionID = props.sessionID;
+        if (sessionID)
+            return resolveSessionId(sessionID);
+        const info = props.info;
+        if (info?.id)
+            return resolveSessionId(info.id);
+        return undefined;
+    }
+    if (enabled) {
+        try {
+            fs.mkdirSync(evDir(), { recursive: true });
+        }
+        catch { }
+        if (cleanupEnabled) {
+            setImmediate(() => cleanupStaleLogs(evDir()));
+        }
+    }
+    function flushSession(sessionId, buf) {
+        if (buf.lines.length === 0)
+            return;
+        const data = buf.lines.join("");
+        buf.lines = [];
+        try {
+            fs.appendFileSync(getLogFile(sessionId, evDir()), data);
+            rotateIfNeeded(sessionId, evDir());
+        }
+        catch { }
+    }
+    function scheduleFlush(sessionId, buf) {
+        if (buf.flushTimer)
+            return;
+        buf.flushTimer = setTimeout(() => {
+            buf.flushTimer = null;
+            flushSession(sessionId, buf);
+        }, FLUSH_INTERVAL_MS);
+    }
+    function write(sessionId, content) {
+        const buf = sessionBuffers.get(sessionId);
+        if (!buf)
+            return;
+        buf.lines.push(content);
+        if (buf.lines.length >= BUFFER_SIZE_LIMIT) {
+            flushSession(sessionId, buf);
+        }
+        else {
+            scheduleFlush(sessionId, buf);
+        }
+    }
+    function getOrCreateBuffer(sessionId) {
+        let buf = sessionBuffers.get(sessionId);
+        if (!buf) {
+            buf = { lines: [], flushTimer: null, startTime: Date.now(), roundCount: 0 };
+            sessionBuffers.set(sessionId, buf);
+            if (cleanupEnabled) {
+                setImmediate(() => cleanupRotatedLogs(sessionId, evDir()));
+            }
+        }
+        return buf;
+    }
+    return {
+        log(event) {
+            if (!enabled)
+                return;
+            if (!TRACKED_EVENT_TYPES.has(event.type))
+                return;
+            let sessionId = extractSessionId(event);
+            if (!sessionId)
+                return;
+            const props = event.properties;
+            // Handle buffer migration when sub-agent relationship is discovered
+            if (sessionId.startsWith("__migrate__:")) {
+                const [, childId, parentId] = sessionId.split(":");
+                sessionId = parentId;
+                // 子会话归属随父：父未纳入统计时丢弃子缓冲，不产生日志文件
+                if (opts.isTracked && !opts.isTracked(parentId, event)) {
+                    const dropBuf = sessionBuffers.get(childId);
+                    if (dropBuf) {
+                        if (dropBuf.flushTimer) {
+                            clearTimeout(dropBuf.flushTimer);
+                            dropBuf.flushTimer = null;
+                        }
+                        sessionBuffers.delete(childId);
+                    }
+                    return;
+                }
+                // Move child's existing buffer to parent
+                const childBuf = sessionBuffers.get(childId);
+                if (childBuf) {
+                    const parentBuf = getOrCreateBuffer(parentId);
+                    parentBuf.lines = parentBuf.lines.concat(childBuf.lines);
+                    childBuf.lines = [];
+                    parentBuf.roundCount += childBuf.roundCount;
+                    if (childBuf.flushTimer) {
+                        clearTimeout(childBuf.flushTimer);
+                        childBuf.flushTimer = null;
+                    }
+                    sessionBuffers.delete(childId);
+                }
+            }
+            // Detect sub-agent for tag (skip if no child sessions exist)
+            let subAgent;
+            if (childSessionIds.size > 0) {
+                const rawSessionId = props?.sessionID ?? props?.info?.id;
+                if (rawSessionId && childSessionIds.has(rawSessionId)) {
+                    subAgent = { childId: rawSessionId };
+                }
+            }
+            // 归属门控：未纳入统计范围的会话不记录事件
+            if (opts.isTracked && !opts.isTracked(sessionId, event))
+                return;
+            const buf = getOrCreateBuffer(sessionId);
+            const ts = formatTimestamp(new Date());
+            // Write formatted event block
+            write(sessionId, formatEventBlock(ts, event.type, props, subAgent));
+            // Track round count on step-finish
+            if (event.type === "message.part.updated") {
+                const part = props?.part;
+                if (part && part.type === "step-finish") {
+                    buf.roundCount++;
+                }
+            }
+            // Round ended 鈥?write summary as a round marker, keep logging if conversation continues
+            if (event.type === "session.idle") {
+                write(sessionId, formatSessionSummary(buf.startTime, buf.roundCount));
+                flushSession(sessionId, buf);
+            }
+        },
+        logPrompt(sessionId, type, content) {
+            if (!enabled)
+                return;
+            const buf = getOrCreateBuffer(sessionId);
+            const ts = formatTimestamp(new Date());
+            const lines = [];
+            lines.push(`[${ts}] PROMPT:${type} [session:${sessionId}]`);
+            lines.push(`  ${safeJson(content)}`);
+            lines.push("");
+            write(sessionId, lines.join("\n"));
+        },
+        isSubAgent(sessionId) {
+            return childSessionIds.has(sessionId);
+        },
+        flush() {
+            for (const [sessionId, buf] of sessionBuffers) {
+                flushSession(sessionId, buf);
+            }
+        },
+        dispose() {
+            for (const [sessionId, buf] of sessionBuffers) {
+                if (buf.flushTimer) {
+                    clearTimeout(buf.flushTimer);
+                    buf.flushTimer = null;
+                }
+                write(sessionId, formatSessionSummary(buf.startTime, buf.roundCount));
+                flushSession(sessionId, buf);
+            }
+            sessionBuffers.clear();
+            childToParent.clear();
+            childSessionIds.clear();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import type { MetricsEngineOptions } from "./metrics-engine.js";
+import type { EventLoggerOptions } from "./event-logger.js";
+import type { MetricsDirs } from "./dirs.js";
+export { createMetricsEngine } from "./metrics-engine.js";
+export type { MetricsEngineOptions, MetricsScope, MetricsScopeMode, MetricsEngine } from "./metrics-engine.js";
+export { configureDirs, defaultDirs, getDirs, resolveDirs, getSummaryFile } from "./dirs.js";
+export type { MetricsDirs } from "./dirs.js";
+export { createEventLogger } from "./event-logger.js";
+export type { EventLogger, EventLoggerOptions } from "./event-logger.js";
+export { backfillFromOpencode } from "./backfill.js";
+export type { BackfillOptions, BackfillEngineRule, BackfillFilter, BackfillResult, BackfillEngineStat, BackfillMetricsOutput, } 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";
+export type { SummaryFilter, SessionSummary, SessionDetail, SubagentView, ReindexResult, UpsertMode, SummaryFields, RemoveSessionResult, } from "./summary-store.js";
+export type * from "./metrics-types.js";
+export interface MetricsRuntimeOptions extends Omit<MetricsEngineOptions, "enabled"> {
+    dirs?: Partial<MetricsDirs>;
+    enabled?: boolean;
+    /** 事件写盘（events/<sessionId>.log）；仅记录归属命中本引擎 scope 的会话 */
+    eventLogging?: boolean;
+    /** 事件记录器额外选项（如外部传入的 isTracked 门控，一般由 runtime 自动注入无需配置） */
+    eventLoggerOptions?: Omit<EventLoggerOptions, "eventsDir" | "isTracked">;
+    /**
+     * 启动时增量回填本引擎归属的历史会话（读 opencode.db，水位存于 metricsDir/.backfill-state.json）。
+     * 仅当 scope 可静态判定（mode all，或配置了 agents/cwdPrefixes）时生效，用于补齐"插件未运行期间"的间隙会话。
+     */
+    backfillOnStart?: boolean;
+}
+/**
+ * 组装一整套"通用统计插件"的运行时：事件记录 + 指标引擎。
+ * 目录为实例级（不产生全局副作用）：defaultDirs → 进程级默认（configureDirs）→ opts.dirs 三层合并。
+ * 同一进程可创建多个 runtime（不同插件各配各目录），scope 门控同时作用于引擎计数与事件写盘。
+ */
+export declare function createMetricsRuntime(opts?: MetricsRuntimeOptions): {
+    dirs: MetricsDirs;
+    eventLogger: import("./event-logger.js").EventLogger | null;
+    engine: import("./metrics-types.js").MetricsEngine & {
+        claimSession: (sessionId: string, meta?: {
+            agent?: string;
+        }) => void;
+        scopeOf: (sessionId: string) => boolean;
+        shouldTrack: (sessionId: string, eventType: string, props: Record<string, unknown> | undefined) => boolean;
+    };
+    /** opencode event hook：`async ({ event }) => { runtime.event({ event }) }` */
+    event(input: {
+        event: {
+            type: string;
+            properties?: Record<string, unknown>;
+        };
+    }): void;
+};
+export type MetricsRuntime = ReturnType<typeof createMetricsRuntime>;