opencode-metrics-plugin 0.1.5 → 0.2.1

package/dist/{metrics-types.d.ts → metrics/types.d.ts}

@@ -50,7 +50,7 @@ export interface SessionMeta {
     agentUsage: Record<string, number>;
     modelSwitches: number;
     modelTokenDistribution: Record<string, TokenUsage>;
-    /** opencode session.title（实时事件不产出，采集/回填场景可选填充） */
+    /** opencode session.title（实时事件不产出，可选填充） */
     title?: string;
 }
 export interface FixCycle {
@@ -192,8 +192,8 @@ export interface SubAgentOutput {
 }
 export interface MetricsOutput {
     sessionId: string;
-    /** 快照来源标记：live 进程写入 / opencode.db 回填生成（force 重建仅保护 live 源）。 */
-    source?: "live" | "backfill";
+    /** 快照来源标记（0.2.0 起仅 live） */
+    source?: "live";
     startTime: number;
     endTime: number;
     duration: number;
@@ -300,82 +300,4 @@ export interface MetricsEngine {
     flush(sessionId: string): void;
     dispose(): void;
 }
-export interface SubAgentState {
-    sessionId: string;
-    agentName: string;
-    title: string;
-    messageMap: Map<string, MessageEntry>;
-    toolCallMap: Map<string, ToolCallEntry>;
-    textLengthMap: Map<string, number>;
-    orderCounter: number;
-    _userMessageIds: Set<string>;
-    _pendingUserMessage: string[];
-}
-export interface SessionMetricsState {
-    sessionId: string;
-    startTime: number;
-    endTime: number;
-    rounds: RoundSnapshot[];
-    tokens: TokenUsage;
-    tools: {
-        totalCalls: number;
-        invalidCalls: number;
-        completedCalls: number;
-        errorCalls: number;
-        distribution: Map<string, ToolStats>;
-        slowestCall: {
-            tool: string;
-            duration: number;
-        };
-    };
-    agent: {
-        current: string;
-        switches: number;
-        lastSwitchTime: number;
-        usage: Map<string, number>;
-    };
-    model: {
-        current: string;
-        switches: number;
-        tokenDistribution: Map<string, TokenUsage>;
-    };
-    compactions: number;
-    anomaly: {
-        triggered: boolean;
-        events: string[];
-    };
-    currentStage: StageInfo | null;
-    stages: StageInfo[];
-    lastStageEndTime: number;
-    _stageTokens: TokenUsage;
-    _roundStartTime: number;
-    _firstEventTime: number;
-    _firstTextTime: number;
-    _hasFirstEvent: boolean;
-    _hasTextPart: boolean;
-    _roundTokens: TokenUsage;
-    _roundToolCalls: number;
-    _roundErrors: number;
-    _roundFirstBuildTracked: boolean;
-    _roundIdleProcessed: boolean;
-    _idleFlushed: boolean;
-    messageMap: Map<string, MessageEntry>;
-    toolCallMap: Map<string, ToolCallEntry>;
-    textLengthMap: Map<string, number>;
-    sessionMeta: SessionMeta;
-    compileStats: CompileStats;
-    orderCounter: number;
-    skillCallMap: Map<string, SkillCallEntry>;
-    htmlPreviewMsgId: string | null;
-    skillSearchMap: Map<string, SkillSearchEntry>;
-    _pendingReadChain: {
-        searchCallID: string;
-    } | null;
-    _userMessageIds: Set<string>;
-    _pendingUserMessage: string[];
-    subAgents: Map<string, SubAgentState>;
-    planningCalls: PlanningCall[];
-    systemPrompts: Map<string, string[]>;
-}
 export declare function createTokenUsage(): TokenUsage;
-export declare function createSessionMetrics(sessionId: string): SessionMetricsState;

package/dist/metrics/types.js

@@ -0,0 +1,20 @@
+export const TRACKED_EVENT_TYPES = new Set([
+    "session.created",
+    "session.updated",
+    "session.idle",
+    "session.deleted",
+    "session.compacted",
+    "session.status",
+    "session.error",
+    "message.updated",
+    "message.removed",
+    "message.part.updated",
+    "message.part.removed",
+    "permission.asked",
+    "permission.replied",
+    "command.executed",
+]);
+// ─── Factory Functions ───────────────────────────────────────────────────────
+export function createTokenUsage() {
+    return { input: 0, output: 0, reasoning: 0, cacheRead: 0, cacheWrite: 0, total: 0 };
+}

package/dist/plugin.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import type { MetricsRuntimeOptions } from "./metrics/runtime.js";
+/**
+ * opencode.json 插件配置项（["opencode-metrics-plugin", { ... }] 的第二参）。
+ * 与 MetricsRuntimeOptions 一致：enabled / eventLogging / dirs / onFlush。
+ */
+export type MetricsPluginOptions = MetricsRuntimeOptions;
+/**
+ * opencode 插件入口。
+ *
+ * ```jsonc
+ * // opencode.json
+ * { "plugin": ["opencode-metrics-plugin"] }
+ * // 带配置：
+ * { "plugin": [["opencode-metrics-plugin", { "enabled": true, "eventLogging": true }]] }
+ * ```
+ *
+ * 挂上后自动记录全部会话：每轮 session.idle 落盘快照 JSON，
+ * dispose 时兜底 flush 未落盘会话。@opencode-ai/plugin 仅作类型依赖（零运行时依赖）。
+ */
+export declare const MetricsPlugin: Plugin;
+export default MetricsPlugin;

package/dist/plugin.js

@@ -0,0 +1,49 @@
+import { createMetricsRuntime } from "./metrics/runtime.js";
+import { log } from "./shared/log.js";
+/**
+ * opencode 插件入口。
+ *
+ * ```jsonc
+ * // opencode.json
+ * { "plugin": ["opencode-metrics-plugin"] }
+ * // 带配置：
+ * { "plugin": [["opencode-metrics-plugin", { "enabled": true, "eventLogging": true }]] }
+ * ```
+ *
+ * 挂上后自动记录全部会话：每轮 session.idle 落盘快照 JSON，
+ * dispose 时兜底 flush 未落盘会话。@opencode-ai/plugin 仅作类型依赖（零运行时依赖）。
+ */
+export const MetricsPlugin = async (_input, options) => {
+    const opts = (options ?? {});
+    const runtime = createMetricsRuntime(opts);
+    log.info("[MetricsPlugin] started", {
+        metricsDir: runtime.dirs.metricsDir,
+        eventsDir: runtime.dirs.eventsDir,
+        enabled: opts.enabled !== false,
+    });
+    const hooks = {
+        event: async ({ event }) => {
+            runtime.event({
+                event: event,
+            });
+        },
+        // 记录各模型 system prompt（只读不改写、不返回；子代理跳过）
+        "experimental.chat.system.transform": async (input, output) => {
+            const sessionId = input.sessionID;
+            if (!sessionId)
+                return;
+            if (runtime.eventLogger?.isSubAgent(sessionId))
+                return;
+            const modelId = input.model?.id ?? "unknown";
+            runtime.eventLogger?.logPrompt(sessionId, `system:${modelId}`, output.system);
+            runtime.engine.ingestPrompt(sessionId, modelId, output.system);
+        },
+        dispose: async () => {
+            runtime.eventLogger?.dispose();
+            runtime.engine.dispose();
+            log.info("[MetricsPlugin] disposed");
+        },
+    };
+    return hooks;
+};
+export default MetricsPlugin;

package/dist/{logger.d.ts → shared/log.d.ts}

@@ -1,6 +1,8 @@
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export declare function setLogLevel(level: LogLevel): void;
 export declare function getLogLevel(): LogLevel;
+/** 设置运行日志落盘文件；传 null 关闭文件输出（仅 console）。 */
+export declare function setLogFile(file: string | null): void;
 export declare function flushLogs(): void;
 export declare const log: {
     debug(...parts: unknown[]): void;

package/dist/{logger.js → shared/log.js}

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { getLogFile } from './dirs.js';
+import envPaths from 'env-paths';
 const LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
 let minOrder = LEVEL_ORDER.info;
 export function setLogLevel(level) {
@@ -9,12 +9,19 @@ export function setLogLevel(level) {
 export function getLogLevel() {
     return Object.keys(LEVEL_ORDER).find((k) => LEVEL_ORDER[k] === minOrder) ?? 'info';
 }
+const DEFAULT_LOG_FILE = path.join(envPaths('opencode-metrics-plugin', { suffix: '' }).log, 'plugin.log');
+let logFile = DEFAULT_LOG_FILE;
+/** 设置运行日志落盘文件；传 null 关闭文件输出（仅 console）。 */
+export function setLogFile(file) {
+    logFile = file;
+}
 let buffer = [];
 let flushTimer = null;
 const FLUSH_INTERVAL_MS = 500;
 const BUFFER_SIZE_LIMIT = 50;
 function writeLine(line) {
-    const logFile = getLogFile();
+    if (logFile == null)
+        return;
     try {
         fs.mkdirSync(path.dirname(logFile), { recursive: true });
         fs.appendFileSync(logFile, line + '\n');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-metrics-plugin",
-  "version": "0.1.5",
-  "description": "Engine-agnostic opencode metrics plugin: realtime event ingestion → SessionMetrics snapshots. Configurable scope (all / claimed-by-host / agents / cwd prefixes). No UI.",
+  "version": "0.2.1",
+  "description": "opencode plugin: auto-records every session's metrics (tokens/rounds/steps/sub-agents/hvigor builds) to snapshot JSON. Zero DB, zero config. Pair with session-viewer for visualization.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
     }
   },
   "files": [
@@ -24,7 +28,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc",
     "typecheck": "tsc --noEmit",
     "test": "tsx example/smoke.mts",
     "prepublishOnly": "npm run build && npm test"
@@ -35,9 +39,13 @@
   "dependencies": {
     "env-paths": "^3.0.0"
   },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.18.0"
+  },
   "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.9",
     "@types/node": "^22.9.0",
     "tsx": "^4.23.13",
     "typescript": "^5.6.0"
-  }
+  }
 }

package/dist/backfill-cli.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/backfill-cli.js

@@ -1,74 +0,0 @@
-import * as fs from "fs";
-import * as path from "path";
-import { backfillFromOpencode } from "./backfill.js";
-function loadConfig(configPath) {
-    let raw = fs.readFileSync(configPath, "utf-8");
-    // 容忍 // 行注释与尾逗号外的常见 jsonc 写法（去掉整行注释）
-    raw = raw
-        .split("\n")
-        .map((l) => l.replace(/^\s*\/\/.*$/, ""))
-        .join("\n");
-    const cfg = JSON.parse(raw);
-    if (!Array.isArray(cfg.engines) || cfg.engines.length === 0) {
-        throw new Error("配置文件缺少 engines 数组");
-    }
-    return cfg;
-}
-function parseArgs(argv) {
-    const out = { agents: [], dryRun: false };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--config")
-            out.config = argv[++i];
-        else if (a === "--agent")
-            out.agents.push(argv[++i]);
-        else if (a === "--since") {
-            const v = argv[++i];
-            const n = Number(v);
-            out.since = Number.isFinite(n) && v.trim() !== "" ? n : Date.parse(v);
-        }
-        else if (a === "--dry-run")
-            out.dryRun = true;
-        else if (a === "--db")
-            out.dbPath = argv[++i];
-        else if (a === "--help" || a === "-h") {
-            console.log("用法: node dist/backfill-cli.js --config <engines.json> [--agent <name>...] [--since <ms|ISO>] [--db <path>] [--dry-run]");
-            process.exit(0);
-        }
-    }
-    return out;
-}
-async function main() {
-    const args = parseArgs(process.argv.slice(2));
-    if (!args.config) {
-        console.error("必须指定 --config <engines.json>");
-        process.exit(1);
-    }
-    const cfg = loadConfig(path.resolve(args.config));
-    const filter = { ...(cfg.filter ?? {}) };
-    if (args.agents.length > 0)
-        filter.agents = args.agents;
-    if (typeof args.since === "number" && Number.isFinite(args.since))
-        filter.since = args.since;
-    const opts = {
-        dbPath: args.dbPath ?? cfg.dbPath,
-        engines: cfg.engines,
-        fallback: cfg.fallback,
-        filter,
-        skipExisting: true,
-        dryRun: args.dryRun,
-    };
-    console.log(`回填开始: db=${opts.dbPath ?? "默认"} 引擎数=${opts.engines.length}${opts.dryRun ? " [dry-run]" : ""}`);
-    const result = await backfillFromOpencode(opts);
-    for (const s of result.perEngine) {
-        console.log(`  [${s.label}] ${s.metricsDir} → 写入 ${s.written} | 已有跳过 ${s.skippedExisting} | 空会话 ${s.skippedEmpty}`);
-    }
-    if (result.fallback) {
-        console.log(`  [fallback] ${result.fallback.metricsDir} → 写入 ${result.fallback.written} | 已有跳过 ${result.fallback.skippedExisting} | 空会话 ${result.fallback.skippedEmpty}`);
-    }
-    console.log(`  过滤跳过 ${result.skippedByFilter} | 无人认领 ${result.unattributed} | 顶层会话总数 ${result.total}`);
-}
-main().catch((err) => {
-    console.error("回填失败:", err);
-    process.exit(1);
-});

package/dist/backfill.d.ts

@@ -1,58 +0,0 @@
-import type { MetricsOutput } from "./metrics-types.js";
-/** 引擎归属规则（与运行时 scope 同语义：agents 命中或 cwd 前缀命中即归属，首条命中优先） */
-export interface BackfillEngineRule {
-    label: string;
-    /** 该引擎快照写入目录（<sessionId>.json 落这里） */
-    metricsDir: string;
-    /** agent 名单（session.agent 列，缺失时回退首条含 agent 的 message） */
-    agents?: string[];
-    /** 工作目录前缀（与 session.directory 前缀匹配，斜杠/大小写不敏感） */
-    cwdPrefixes?: string[];
-    /** 摘要库落点；缺省写全局共享库（与 live flush 一致，多宿主聚合） */
-    summaryFile?: string;
-}
-/** 回填会话选择过滤器（在归属判定之前应用） */
-export interface BackfillFilter {
-    agents?: string[];
-    cwdPrefixes?: string[];
-    since?: number;
-    sessionIds?: string[];
-}
-export interface BackfillOptions {
-    /** opencode 数据库路径，默认 ~/.local/share/opencode/opencode.db */
-    dbPath?: string;
-    engines: BackfillEngineRule[];
-    /** 无人认领会话的兜底目录（不配则跳过不回填） */
-    fallback?: {
-        metricsDir: string;
-        summaryFile?: string;
-    };
-    filter?: BackfillFilter;
-    /** 目标目录已有快照（live 优先）则跳过，默认 true */
-    skipExisting?: boolean;
-    /** 增量模式：读各目录 .backfill-state.json 水位，只回填 time_created 更晚的会话 */
-    incremental?: boolean;
-    /** 只统计不写盘 */
-    dryRun?: boolean;
-    /** 单会话回填完成回调 */
-    onSessionBackfilled?: (sessionId: string, label: string, metricsDir: string) => void;
-}
-export interface BackfillEngineStat {
-    label: string;
-    metricsDir: string;
-    written: number;
-    skippedExisting: number;
-    skippedEmpty: number;
-}
-export interface BackfillResult {
-    perEngine: BackfillEngineStat[];
-    fallback: BackfillEngineStat | null;
-    skippedByFilter: number;
-    unattributed: number;
-    total: number;
-}
-export type BackfillMetricsOutput = MetricsOutput & {
-    source: "backfill";
-};
-/** 从 opencode.db 回填历史会话统计：按归属规则路由写入各引擎目录（快照带 source:"backfill"）。 */
-export declare function backfillFromOpencode(opts: BackfillOptions): Promise<BackfillResult>;