@winspan/claude-forge 8.30.0 → 8.33.2

package/dist/core/ai/provider.js

@@ -1,12 +1,61 @@
 /**
- * Claude AI provider — simple wrapper around @anthropic-ai/sdk
- * No rate limiter, no circuit breaker, no caching, no multi-provider factory
+ * Claude AI provider — wrapper around @anthropic-ai/sdk.
+ *
+ * Adds per-request timeout (AbortController) and bounded retry with exponential
+ * backoff for transient failures (AbortError / 429 / 5xx / network errors).
+ * SDK's built-in retry is disabled (maxRetries: 0) to avoid double retry layers.
  */
 import Anthropic from '@anthropic-ai/sdk';
 import { logger } from '../utils/logger.js';
 const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
 const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const MAX_BACKOFF_MS = 8_000;
+/** Sleep helper — exported via object indirection so tests can stub it. */
+export const timing = {
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    },
+};
+/** @deprecated Use `timing.delay`; kept for backward compatibility. */
+export function delay(ms) {
+    return timing.delay(ms);
+}
+/**
+ * Determine whether an error from the Anthropic SDK (or network layer) is
+ * worth retrying. Covers:
+ *   - Abort (our own timeout fires an AbortController)
+ *   - 429 rate limit
+ *   - 5xx server errors
+ *   - Connection / network errors without a status code
+ */
+function isRetriable(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.name === 'AbortError' || e.name === 'APIUserAbortError')
+        return true;
+    if (typeof e.status === 'number') {
+        if (e.status === 429)
+            return true;
+        if (e.status >= 500 && e.status < 600)
+            return true;
+        return false;
+    }
+    // No HTTP status -> typically a connection error, worth retrying.
+    if (e.name === 'APIConnectionError' || e.name === 'APIConnectionTimeoutError')
+        return true;
+    if (e.code === 'ECONNRESET' || e.code === 'ETIMEDOUT' || e.code === 'ENOTFOUND')
+        return true;
+    return false;
+}
+function computeBackoffMs(attempt) {
+    return Math.min(1000 * Math.pow(2, attempt), MAX_BACKOFF_MS);
+}
 export class ClaudeProvider {
+    // Exposed for tests; production code treats it as private.
+    /** @internal */
     client;
     model;
     callCount = 0;
@@ -21,29 +70,87 @@ export class ClaudeProvider {
         });
     }
     async complete(prompt, options) {
+        const response = await this.completeWithUsage(prompt, options);
+        return response.text;
+    }
+    async completeWithUsage(prompt, options) {
         this.callCount++;
-        const start = Date.now();
-        try {
-            const response = await this.client.messages.create({
-                model: options?.model || this.model,
-                max_tokens: options?.maxTokens || DEFAULT_MAX_TOKENS,
-                ...(options?.system ? { system: options.system } : {}),
-                messages: [{ role: 'user', content: prompt }],
-            });
-            const latency = Date.now() - start;
-            this.totalLatencyMs += latency;
-            const usage = response.usage;
-            this.totalTokens += (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0);
-            logger.debug(`[AI] ${latency}ms | ${usage?.input_tokens ?? 0}+${usage?.output_tokens ?? 0} tokens`);
-            const textBlock = response.content.find((c) => c.type === 'text');
-            return textBlock?.text ?? '';
-        }
-        catch (err) {
-            this.totalErrors++;
-            this.totalLatencyMs += Date.now() - start;
-            logger.error(`[AI] Claude API error: ${err}`);
-            throw err;
+        const modelUsed = options?.model || this.model;
+        const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const externalSignal = options?.signal;
+        let lastErr;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const start = Date.now();
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            // Forward external aborts into our controller so both sources cancel
+            // the in-flight request.
+            const onExternalAbort = () => controller.abort();
+            if (externalSignal) {
+                if (externalSignal.aborted)
+                    controller.abort();
+                else
+                    externalSignal.addEventListener('abort', onExternalAbort, { once: true });
+            }
+            try {
+                const response = await this.client.messages.create({
+                    model: modelUsed,
+                    max_tokens: options?.maxTokens || DEFAULT_MAX_TOKENS,
+                    ...(options?.system ? { system: options.system } : {}),
+                    messages: [{ role: 'user', content: prompt }],
+                }, {
+                    signal: controller.signal,
+                    // Disable SDK-level retry; this method owns retry semantics.
+                    maxRetries: 0,
+                    timeout: timeoutMs,
+                });
+                const latency = Date.now() - start;
+                this.totalLatencyMs += latency;
+                const usage = response.usage;
+                this.totalTokens += (usage?.input_tokens ?? 0) + (usage?.output_tokens ?? 0);
+                logger.debug(`[AI] ${latency}ms | ${usage?.input_tokens ?? 0}+${usage?.output_tokens ?? 0} tokens` +
+                    (attempt > 0 ? ` (after ${attempt} retry)` : ''));
+                const textBlock = response.content.find((c) => c.type === 'text');
+                return {
+                    text: textBlock?.text ?? '',
+                    usage: usage
+                        ? {
+                            input_tokens: usage.input_tokens,
+                            output_tokens: usage.output_tokens,
+                        }
+                        : undefined,
+                    model: modelUsed,
+                };
+            }
+            catch (err) {
+                this.totalLatencyMs += Date.now() - start;
+                lastErr = err;
+                // External caller aborted -> never retry, propagate immediately.
+                if (externalSignal?.aborted) {
+                    this.totalErrors++;
+                    throw err;
+                }
+                const canRetry = attempt < maxRetries && isRetriable(err);
+                if (!canRetry) {
+                    this.totalErrors++;
+                    logger.error(`[AI] Claude API error: ${err instanceof Error ? err.message : String(err)}`);
+                    throw err;
+                }
+                const backoffMs = computeBackoffMs(attempt);
+                const reason = err instanceof Error ? err.message : String(err);
+                logger.warn(`[ClaudeProvider] retry ${attempt + 1}/${maxRetries} after ${backoffMs}ms (reason: ${reason})`);
+                await timing.delay(backoffMs);
+            }
+            finally {
+                clearTimeout(timer);
+                if (externalSignal) {
+                    externalSignal.removeEventListener('abort', onExternalAbort);
+                }
+            }
         }
+        // Unreachable: loop either returns or throws. Included for type safety.
+        throw lastErr instanceof Error ? lastErr : new Error('ClaudeProvider: exhausted retries');
     }
     formatStats() {
         if (this.callCount === 0)

package/dist/core/ai/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../src/core/ai/provider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../src/core/ai/provider.ts"],"names":[],"mappings":"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"}

package/dist/core/ai/types.d.ts

@@ -1,12 +1,33 @@
 /**
  * AI Provider abstraction — minimal interface
  */
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+export interface AIResponse {
+    text: string;
+    usage?: TokenUsage;
+    model?: string;
+}
+/**
+ * Options for AI completion calls.
+ *
+ * `timeoutMs` (default 30_000) caps each individual request via AbortController.
+ * `maxRetries` (default 2) controls retry attempts for AbortError/429/5xx/network errors.
+ * `signal` lets callers abort externally (composed with internal timeout signal).
+ */
+export interface CompleteOptions {
+    system?: string;
+    maxTokens?: number;
+    model?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+}
 export interface AIProvider {
-    complete(prompt: string, options?: {
-        system?: string;
-        maxTokens?: number;
-        model?: string;
-    }): Promise<string>;
+    complete(prompt: string, options?: CompleteOptions): Promise<string>;
+    completeWithUsage(prompt: string, options?: CompleteOptions): Promise<AIResponse>;
     formatStats(): string;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/core/ai/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/ai/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpB,WAAW,IAAI,MAAM,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/ai/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErE,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAElF,WAAW,IAAI,MAAM,CAAC;CACvB"}

package/dist/core/storage/rows.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 数据库行的 TypeScript 类型定义。
+ *
+ * 每个 interface 对应一张表的查询结果行（shape 与 schema.sql + runMigrations 后
+ * 的最终结构一致）。sqlite.ts 的所有 get/all 返回值都应该用这些类型而非 any，
+ * 以确保 schema 变动能在编译期而不是运行期暴露。
+ *
+ * 约定：
+ * - 字段可空性严格对齐 schema.sql 的 NOT NULL / DEFAULT NULL / 外键约束
+ * - enum 字段（status / mode / trigger_type 等）使用 string literal union
+ * - timestamp 字段按实际存储类型：文本时间戳 → string，Unix 毫秒数 → number
+ */
+export interface EventRow {
+    event_id: string;
+    session_id: string;
+    project_path: string;
+    timestamp: string;
+    hook_type: 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'Notification' | 'Stop';
+    tool_name: string | null;
+    tool_input: string | null;
+    tool_output: string | null;
+    user_prompt: string | null;
+    ai_response: string | null;
+    distilled: number;
+    created_at: string;
+}
+export interface SessionRow {
+    session_id: string;
+    project_path: string;
+    status: 'active' | 'completed' | 'interrupted' | 'resumed' | 'abandoned';
+    first_prompt: string | null;
+    start_time: string;
+    end_time: string | null;
+    last_event_time: string | null;
+    event_count: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface QualityIssueRow {
+    id: string;
+    session_id: string;
+    project_path: string;
+    file_path: string;
+    category: string;
+    level: string;
+    message: string;
+    resolved: number;
+    resolved_at: string | null;
+    created_at: string;
+}
+export interface DistillResultRow {
+    id: number;
+    session_id: string;
+    event_ids: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    retry_count: number;
+    error_message: string | null;
+    created_at: string;
+    processed_at: string | null;
+}
+export interface ToolEventRow {
+    id: number;
+    session_id: string;
+    route_request_id: string | null;
+    tool: string;
+    args: string;
+    result: string | null;
+    success: number;
+    error: string | null;
+    timestamp: number;
+    created_at: string;
+}
+export interface DecisionRow {
+    id: number;
+    session_id: string;
+    event_id: number;
+    rule_id: string | null;
+    level: 'allow' | 'warn' | 'confirm' | 'block';
+    reason: string | null;
+    suggestion: string | null;
+    user_choice: string | null;
+    timestamp: number;
+    created_at: string;
+}
+export interface InjectionRow {
+    id: string;
+    event_id: string | null;
+    session_id: string;
+    timestamp: string;
+    source_handler: string;
+    injection_type: 'systemMessage' | 'additionalContext' | 'reason';
+    content: string;
+    created_at: string;
+}
+export interface TaskRow {
+    id: string;
+    session_id: string;
+    title: string;
+    description: string | null;
+    start_time: string;
+    end_time: string | null;
+    status: 'active' | 'completed' | 'abandoned';
+    event_count: number;
+    created_at: string;
+}
+export interface MethodologyExecutionRow {
+    id: number;
+    session_id: string;
+    methodology_id: string;
+    plan_json: string;
+    original_plan_json: string | null;
+    current_phase_index: number;
+    status: 'running' | 'completed' | 'failed' | 'cancelled' | 'stale';
+    mode: 'foreground' | 'background';
+    worker_pid: number | null;
+    worker_session_id: string | null;
+    trigger_type: 'manual' | 'idle' | 'scheduled' | null;
+    retry_count: number | null;
+    last_progress_at: number | null;
+    started_at: number;
+    completed_at: number | null;
+    created_at: string;
+}
+export interface PhaseExecutionRow {
+    id: number;
+    methodology_execution_id: number;
+    phase_id: string;
+    phase_index: number;
+    agent_name: string;
+    prompt: string;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    started_at: number | null;
+    completed_at: number | null;
+    duration_ms: number | null;
+    artifacts_json: string | null;
+    output_text: string | null;
+    error_message: string | null;
+    stream_log_path: string | null;
+    created_at: string;
+}
+export interface TokenUsageRow {
+    id: number;
+    session_id: string;
+    methodology_execution_id: number | null;
+    timestamp: number;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    model: string | null;
+    tool_name: string | null;
+    created_at: string;
+}
+//# sourceMappingURL=rows.d.ts.map

package/dist/core/storage/rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.d.ts","sourceRoot":"","sources":["../../../src/core/storage/rows.ts"],"names":[],"mappings":"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"}

package/dist/core/storage/rows.js

@@ -0,0 +1,14 @@
+/**
+ * 数据库行的 TypeScript 类型定义。
+ *
+ * 每个 interface 对应一张表的查询结果行（shape 与 schema.sql + runMigrations 后
+ * 的最终结构一致）。sqlite.ts 的所有 get/all 返回值都应该用这些类型而非 any，
+ * 以确保 schema 变动能在编译期而不是运行期暴露。
+ *
+ * 约定：
+ * - 字段可空性严格对齐 schema.sql 的 NOT NULL / DEFAULT NULL / 外键约束
+ * - enum 字段（status / mode / trigger_type 等）使用 string literal union
+ * - timestamp 字段按实际存储类型：文本时间戳 → string，Unix 毫秒数 → number
+ */
+export {};
+//# sourceMappingURL=rows.js.map

package/dist/core/storage/rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rows.js","sourceRoot":"","sources":["../../../src/core/storage/rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/core/storage/schema.sql

@@ -28,6 +28,7 @@ CREATE TABLE IF NOT EXISTS sessions (
     session_id TEXT PRIMARY KEY,
     project_path TEXT NOT NULL,
     status TEXT NOT NULL DEFAULT 'active' CHECK(status IN ('active', 'completed', 'interrupted', 'resumed', 'abandoned')),
+    first_prompt TEXT,  -- 首条 UserPromptSubmit 的 user_prompt 截断后入库，避免 querySessions 跑子查询
     start_time TEXT NOT NULL,
     end_time TEXT,
     last_event_time TEXT,
@@ -38,6 +39,7 @@ CREATE TABLE IF NOT EXISTS sessions (
 
 CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_path);
 CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
+CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC);
 
 -- ── Quality Issues ─────────────────────────────────────────────────────
 
@@ -229,9 +231,10 @@ CREATE TABLE IF NOT EXISTS methodology_executions (
     methodology_id TEXT NOT NULL,
     plan_json TEXT NOT NULL,  -- 动态生成的执行计划（JSON）
     current_phase_index INTEGER DEFAULT 0,
-    status TEXT NOT NULL DEFAULT 'running' CHECK(status IN ('running', 'completed', 'failed', 'cancelled')),
+    status TEXT NOT NULL DEFAULT 'running' CHECK(status IN ('running', 'completed', 'failed', 'cancelled', 'stale')),
     started_at INTEGER NOT NULL,
     completed_at INTEGER,
+    last_progress_at INTEGER,  -- 最后一次推进时间戳（ms），用于 stale 判定
     created_at TEXT DEFAULT (datetime('now'))
 );
 
@@ -248,7 +251,7 @@ CREATE TABLE IF NOT EXISTS phase_executions (
     phase_index INTEGER NOT NULL,
     agent_name TEXT NOT NULL,
     prompt TEXT NOT NULL,
-    status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'running', 'completed', 'failed')),
+    status TEXT NOT NULL DEFAULT 'pending' CHECK(status IN ('pending', 'running', 'completed', 'failed', 'cancelled')),
     started_at INTEGER,
     completed_at INTEGER,
     duration_ms INTEGER,
@@ -259,3 +262,24 @@ CREATE TABLE IF NOT EXISTS phase_executions (
 
 CREATE INDEX IF NOT EXISTS idx_phase_exec_methodology ON phase_executions(methodology_execution_id);
 CREATE INDEX IF NOT EXISTS idx_phase_exec_status ON phase_executions(status);
+
+-- ── Token Usage (Token 用量追踪) ──────────────────────────────────────────
+-- 记录每次 AI 调用的 token 用量，用于成本可观测和预算控制
+
+CREATE TABLE IF NOT EXISTS token_usage (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    methodology_execution_id INTEGER,  -- 可选，关联方法论执行
+    timestamp INTEGER NOT NULL,
+    input_tokens INTEGER NOT NULL,
+    output_tokens INTEGER NOT NULL,
+    total_tokens INTEGER NOT NULL,
+    model TEXT,  -- 如 'claude-opus-4-7'
+    tool_name TEXT,  -- 如 'Task' / 'Read' / 'Agent' / 'classify' / 'plan'
+    created_at TEXT DEFAULT (datetime('now')),
+    FOREIGN KEY (methodology_execution_id) REFERENCES methodology_executions(id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_token_usage_session ON token_usage(session_id);
+CREATE INDEX IF NOT EXISTS idx_token_usage_methodology ON token_usage(methodology_execution_id);
+CREATE INDEX IF NOT EXISTS idx_token_usage_timestamp ON token_usage(timestamp DESC);

package/dist/core/storage/sqlite.d.ts

@@ -5,6 +5,8 @@
 import Database from 'better-sqlite3';
 import { EventEmitter } from 'node:events';
 import type { ForgeEvent } from '../types.js';
+import type { MethodologyExecutionRow, PhaseExecutionRow } from './rows.js';
+export type { EventRow, SessionRow, QualityIssueRow, DistillResultRow, ToolEventRow, DecisionRow, InjectionRow, TaskRow, MethodologyExecutionRow, PhaseExecutionRow, TokenUsageRow, } from './rows.js';
 type DecisionLevel = 'allow' | 'warn' | 'confirm' | 'block';
 export interface SessionSummary {
     session_id: string;
@@ -104,9 +106,48 @@ export declare class SQLiteStorage extends EventEmitter {
      * New columns since the base schema.sql go here.
      */
     private runMigrations;
+    /**
+     * 将 events 表按 session_id 聚合回填到 sessions 表，仅在 sessions 尚未对齐
+     * （没有任何一行带 first_prompt）时触发。旧库升级场景：引入 sessions 聚合表 +
+     * upsert 写入路径后，历史 events 不会自动同步到 sessions，必须通过一次性回填补齐。
+     *
+     * 幂等策略：检测到已有 first_prompt 非空的聚合行就跳过；避免覆盖已被新写路径
+     * upsert 过的数据。
+     */
+    private backfillSessionsIfNeeded;
+    /**
+     * SQLite 无法直接修改 CHECK 约束。若旧库的 phase_executions.status CHECK
+     * 还没有 'cancelled'，走经典的"新表 + 拷数据 + 重命名"路径升级。
+     *
+     * 幂等：检测到当前 CREATE TABLE 语句里已有 'cancelled' 就跳过。fresh install
+     * 的库会直接命中 schema.sql 里的新定义，这里也直接跳过。
+     */
+    private rebuildPhaseExecutionsIfNeeded;
+    /**
+     * methodology_executions.status CHECK 升级：加入 'stale' 枚举值。
+     * 幂等：CREATE TABLE 语句里已含 'stale' 则跳过；fresh install 会命中 schema.sql
+     * 的新定义，这里也跳过。
+     *
+     * 注意：必须在 addColumnIfMissing('last_progress_at' / 'retry_count' /
+     * 'original_plan_json' / 'trigger_type', ...) 之后执行，重建表时才能把它们一起
+     * 拷贝过去。重建方法内部再做一次兜底 addColumnIfMissing，避免未来新列漏同步。
+     */
+    private rebuildMethodologyExecutionsIfNeeded;
     getDatabase(): Database.Database;
     getDbPath(): string;
     writeEvent(event: ForgeEvent): void;
+    /**
+     * 将事件聚合到 sessions 表，供 querySessions 直接读取，避免对 events 做 O(n²)
+     * 的 GROUP BY + 相关子查询。
+     *
+     * 语义：
+     * - 首次出现 session_id → 插入一行，start/end/last_event_time 都取当前事件时间戳
+     * - 已存在 → event_count += 1，end/last_event_time 取更晚的，first_prompt 只在
+     *   原值为 NULL 时才被 UserPromptSubmit 的前 200 字填充（保留"首条"语义）
+     * - 非 UserPromptSubmit 事件或 user_prompt 为空时 first_prompt 传 NULL，不会
+     *   覆盖已有值
+     */
+    upsertSession(event: ForgeEvent): void;
     writeToolEvent(event: ToolEventRecord): number;
     writeDecision(decision: DecisionRecord): number;
     queryEvents(filter: {
@@ -220,21 +261,32 @@ export declare class SQLiteStorage extends EventEmitter {
         methodology_id: string;
         plan_json: string;
         mode?: 'foreground' | 'background';
+        trigger_type?: 'manual' | 'idle' | 'scheduled';
     }): number;
-    getActiveMethodologyExecution(session_id: string): any | null;
+    getActiveMethodologyExecution(session_id: string): MethodologyExecutionRow | null;
     updateMethodologyExecution(id: number, data: {
         current_phase_index?: number;
-        status?: string;
+        status?: MethodologyExecutionRow['status'];
         completed_at?: number;
         worker_pid?: number | null;
         worker_session_id?: string | null;
+        last_progress_at?: number;
+        plan_json?: string;
+        retry_count?: number;
     }): void;
-    getMethodologyExecution(id: number): any | null;
+    getMethodologyExecution(id: number): MethodologyExecutionRow | null;
     /**
      * List all methodology_executions with status='running' and mode='background'.
      * Used at daemon startup to detect crashed workers (worker_pid not alive).
      */
-    listRunningBackgroundExecutions(): any[];
+    listRunningBackgroundExecutions(): MethodologyExecutionRow[];
+    /**
+     * List all methodology_executions with status='running' and mode='foreground'.
+     * Used at daemon startup to sweep stale foreground executions — rows left
+     * behind when the originating Claude session ended without Stop hook firing
+     * (crash / detach / pre-guard legacy data).
+     */
+    listRunningForegroundExecutions(): MethodologyExecutionRow[];
     createPhaseExecution(data: {
         methodology_execution_id: number;
         phase_id: string;
@@ -243,14 +295,50 @@ export declare class SQLiteStorage extends EventEmitter {
         prompt: string;
     }): number;
     updatePhaseExecution(id: number, data: {
-        status?: string;
+        status?: PhaseExecutionRow['status'];
         completed_at?: number;
         artifacts_json?: string;
         output_text?: string | null;
         error_message?: string | null;
         stream_log_path?: string | null;
     }): void;
-    getPhaseExecutions(methodology_execution_id: number): any[];
+    getPhaseExecutions(methodology_execution_id: number): PhaseExecutionRow[];
+    /**
+     * 获取指定 session 和 methodology 的最后一次 idle 触发时间
+     */
+    getLastIdleTrigger(session_id: string, methodology_id: string): number | null;
+    recordTokenUsage(params: {
+        session_id: string;
+        methodology_execution_id?: number;
+        input_tokens: number;
+        output_tokens: number;
+        model?: string;
+        tool_name?: string;
+    }): void;
+    getTokenUsageBySession(session_id: string): {
+        total_tokens: number;
+        input_tokens: number;
+        output_tokens: number;
+    };
+    getTokenUsageByMethodology(methodology_execution_id: number): {
+        total_tokens: number;
+        input_tokens: number;
+        output_tokens: number;
+    };
+    listTokenUsage(filter?: {
+        session_id?: string;
+        methodology_execution_id?: number;
+        limit?: number;
+    }): Array<{
+        id: number;
+        session_id: string;
+        methodology_execution_id: number | null;
+        timestamp: number;
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+        model: string | null;
+        tool_name: string | null;
+    }>;
 }
-export {};
 //# sourceMappingURL=sqlite.d.ts.map