opencode-metrics-plugin 0.1.5

package/dist/summary-store.d.ts

@@ -0,0 +1,150 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { MetricsDirs } from "./dirs.js";
+import type { MetricsOutput, RoundSnapshot, StepData, SubAgentOutput, TokenUsage } from "./metrics-types.js";
+/** 打开（或复用）摘要库连接：建目录 + WAL + busy_timeout + 幂等建表；不可用返回 null。 */
+export declare function openSummaryDb(summaryFile: string): DatabaseSync | null;
+/** 关闭全部缓存的连接（宿主 dispose 时可选调用）。 */
+export declare function closeSummaryDbs(): void;
+/** 归一化 created_at（number 时间戳 / ISO 字符串 / Date）为 ISO 字符串。 */
+export declare function toIsoString(value: string | number | Date | null | undefined): string | null;
+/** 从 rounds 提取首条用户消息（兼容 string 与 string[] 形态）。 */
+export declare function firstUserMessageOf(rounds: RoundSnapshot[] | undefined): string | undefined;
+export interface SummaryFields {
+    sessionId: string;
+    taskId: string | null;
+    agent: string;
+    model: string;
+    directory: string;
+    title: string | null;
+    firstUserMessage: string | null;
+    stepCount: number;
+    toolCalls: number;
+    totalTokensInput: number;
+    totalTokensOutput: number;
+    totalTokensCacheRead: number;
+    totalTokensCacheWrite: number;
+    totalTokensReasoning: number;
+    totalTokens: number;
+    duration: number;
+    createdAt: string | null;
+    sourceFile: string;
+}
+/** 摘要表一行所需的全部字段（文件→表共用的提取逻辑）。 */
+export declare function extractSummaryFields(m: MetricsOutput, filePath: string): SummaryFields;
+export type UpsertMode = "force" | "soft";
+/** 快照双表入库（事务内 summary + detail；source_file 保留首见值）。返回是否成功。 */
+export declare function upsertSessionSnapshot(summaryFile: string, snapshot: MetricsOutput, filePath: string, mode?: UpsertMode): boolean;
+export interface SessionSummary {
+    id: string;
+    directory: string;
+    model: string;
+    agent: string;
+    title?: string;
+    stepCount: number;
+    totalTokens: TokenUsage;
+    mainTokens?: TokenUsage;
+    subagentTokens?: TokenUsage;
+    subagentCount?: number;
+    totalCost: number;
+    duration: number;
+    createdAt: string;
+    startTime?: number;
+    endTime?: number;
+    toolCalls: number;
+    successRate: number;
+    firstUserMessage?: string;
+    filePath?: string;
+}
+export interface SubagentView {
+    sessionId: string;
+    agent: string;
+    title: string;
+    tokens: TokenUsage;
+    tools: SubAgentOutput["tools"];
+    userMessages?: string[];
+    /** 完整步骤（仅 full 模式下发；默认摘要化为 stepCount 懒加载） */
+    steps?: StepData[];
+    stepCount?: number;
+}
+export interface SessionDetail extends SessionSummary {
+    steps: StepData[];
+    tools: MetricsOutput["tools"];
+    codeStats?: MetricsOutput["codeStats"];
+    rounds: RoundSnapshot[];
+    subagents?: SubagentView[];
+    skills?: MetricsOutput["skills"];
+    planning?: MetricsOutput["planning"];
+    systemPrompts?: Record<string, string[]>;
+}
+/** 逐元素累加 token 用量。 */
+export declare function sumTokens(items: TokenUsage[]): TokenUsage;
+/** a 减去 b（用于剥离子代理 token 得 main tokens）。 */
+export declare function subtractTokens(a: TokenUsage, b: TokenUsage): TokenUsage;
+/** 快照 → 列表摘要（含 subagent 拆分出的 main/subagent tokens）。 */
+export declare function snapshotToSummary(m: MetricsOutput, filePath?: string): SessionSummary;
+/** 快照 → 详情；默认子代理摘要化（steps 抽为 stepCount，完整 steps 走 getSubagentSteps 懒加载）。 */
+export declare function detailFromRaw(raw: MetricsOutput, opts?: {
+    keepSubagentSteps?: boolean;
+}): SessionDetail;
+/** 保留完整子代理 steps 的详情（供直接渲染子代理树的宿主使用）。 */
+export declare function detailFullFromRaw(raw: MetricsOutput): SessionDetail;
+export interface SummaryFilter {
+    /** 单个 agent（精确） */
+    agent?: string;
+    /** agent 名单（IN 精确） */
+    agents?: string[];
+    /** 任务分组（宿主经 setSessionTaskId 标记） */
+    taskId?: string;
+    /** 工作目录前缀（反斜杠归一 + 大小写不敏感） */
+    directoryPrefix?: string;
+    model?: string;
+    /** 会话 id 名单（IN 精确；宿主按 sessionId 集合聚合汇总用） */
+    sessionIds?: string[];
+    /** created_at 下界（ISO 或毫秒时间戳） */
+    since?: string | number;
+    /** created_at 上界（ISO 或毫秒时间戳） */
+    until?: string | number;
+    limit?: number;
+    offset?: number;
+}
+/** 摘要筛选查询（created_at 倒序；目录/筛选参数归一后走 SQL）。同步函数。 */
+export declare function querySummaries(filter?: SummaryFilter, dirs?: Partial<MetricsDirs>): SessionSummary[];
+/** 按同一筛选条件计数（分页用）。 */
+export declare function countSummaries(filter?: SummaryFilter, dirs?: Partial<MetricsDirs>): number;
+/** 单会话详情（DB full_data → 文件回退）；默认子代理摘要化，fullSubagents=true 保留完整 steps。 */
+export declare function getDetail(sessionId: string, dirs?: Partial<MetricsDirs>, opts?: {
+    fullSubagents?: boolean;
+}): SessionDetail | null;
+/** 子代理完整 steps 懒加载（DB full_data → 文件回退）。 */
+export declare function getSubagentSteps(sessionId: string, index: number, dirs?: Partial<MetricsDirs>): StepData[] | null;
+/** 原始快照 JSON 字符串（文件优先 → DB full_data 回退；等价"下载"能力）。 */
+export declare function getSessionRaw(sessionId: string, dirs?: Partial<MetricsDirs>): string | null;
+/** 给会话标记任务分组（宿主任务关联）。返回是否命中行。 */
+export declare function setSessionTaskId(sessionId: string, taskId: string | null, dirs?: Partial<MetricsDirs>): boolean;
+export interface ReindexResult {
+    scanned: number;
+    upserted: number;
+    pruned: number;
+}
+/**
+ * 扫描 metricsDir 现有快照 JSON 重建摘要行（soft：live 已有数据不覆盖）。
+ * 摘要库缺省为全局共享库（多宿主聚合）；显式 summaryFile 可指向隔离库。
+ * prune=true 时清理 source_file 已不存在于磁盘的孤儿行（双表同删）——
+ * 共享库语义下会清理**全库**的孤儿行（含其他宿主目录已消失的快照），属预期行为。
+ */
+export declare function reindexDir(metricsDir: string, opts?: {
+    summaryFile?: string;
+    prune?: boolean;
+}): ReindexResult;
+export interface RemoveSessionResult {
+    deleted: boolean;
+    /** 被删摘要行的 source_file（供宿主清理快照文件/事件日志） */
+    sourceFile?: string;
+}
+/**
+ * 删除双表中的会话行（宿主删除链路用）。
+ * 返回是否删除及被删行的 source_file；库不存在/行不存在时 deleted=false。
+ */
+export declare function removeSession(sessionId: string, dirs?: Partial<MetricsDirs>): RemoveSessionResult;
+/** 进程级默认摘要库路径（与 getMetricsDir/getEventsDir 对称的便捷取法）。 */
+export declare function getDefaultSummaryFile(): string;