@winspan/claude-forge 8.41.0 → 8.50.6

package/src/core/utils/forge-resume-block.ts

@@ -0,0 +1,74 @@
+/**
+ * 项目根目录 CLAUDE.md 中的「续接」状态摘要的统一落盘格式。
+ *
+ * - 写入：`buildForgeResumeEnvelope`（ResumeEngine）
+ * - 剥离：`stripForgeResumeBlocks`（注入前清理、clearResumeBlock）
+ * - 检测：`hasForgeResumeBlock`（含旧版 `<!-- forge:resume -->` 与新版 begin 标记）
+ */
+import { randomUUID } from 'crypto';
+
+/** 旧版续接块（正文裸放，易被 HTML 注释子串破坏） */
+const LEGACY_RESUME_BLOCK_RE = /\n*<!-- forge:resume -->[\s\S]*?<!-- forge:end-resume -->\s*/g;
+
+/** forge:resume-begin / end 之间的 UUID（randomUUID 小写） */
+const RESUME_UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+
+function scopedResumeBlockRe(): RegExp {
+  return new RegExp(
+    `\\n*<!-- forge:resume-begin:(${RESUME_UUID}) -->[\\s\\S]*?<!-- forge:resume-end:\\1 -->\\s*`,
+    'gi'
+  );
+}
+
+/**
+ * 构造续接信封：外层用 UUID 配对注释定界，正文保存在兼容旧解析器的 fenced block 中。
+ */
+export function buildForgeResumeEnvelope(innerUtf8Markdown: string): string {
+  const id = randomUUID();
+  const iso = new Date().toISOString();
+  const body = innerUtf8Markdown.trim();
+
+  return [
+    `<!-- forge:resume-begin:${id} -->`,
+    '```forge-resume-body',
+    body,
+    '```',
+    '',
+    `_生成时间: ${iso}_`,
+    `<!-- forge:resume-end:${id} -->`,
+  ].join('\n');
+}
+
+/** 是否包含旧版或新版续接块 */
+export function hasForgeResumeBlock(content: string): boolean {
+  return (
+    content.includes('<!-- forge:resume -->') ||
+    new RegExp(`<!-- forge:resume-begin:${RESUME_UUID} -->`).test(content)
+  );
+}
+
+/**
+ * 移除全部续接块（新版 UUID 信封 + 旧版裸正文），并压缩多余空行。
+ */
+export function stripForgeResumeBlocks(content: string): string {
+  let s = content.replace(scopedResumeBlockRe(), '\n');
+  s = s.replace(LEGACY_RESUME_BLOCK_RE, '\n');
+  s = s.replace(/\n{4,}/g, '\n\n\n');
+  return s.trimEnd();
+}
+
+export function decodeForgeResumeInnerFromClaudeMd(content: string): string {
+  const fencedMatch = content.match(/```forge-resume-body\n([\s\S]*?)\n```/);
+  if (fencedMatch) {
+    return fencedMatch[1].trim();
+  }
+
+  const scopedMatch = content.match(
+    new RegExp(`<!-- forge:resume-begin:${RESUME_UUID} -->\\n([\\s\\S]*?)\\n(?:_生成时间:[\\s\\S]*?)?<!-- forge:resume-end:${RESUME_UUID} -->`)
+  );
+  if (scopedMatch) {
+    return scopedMatch[1].trim();
+  }
+
+  return '';
+}

package/src/core/utils/format.ts

@@ -0,0 +1,69 @@
+/**
+ * 通用格式化工具（日志、错误）
+ */
+
+/**
+ * 格式化错误对象为日志友好的字符串
+ */
+export function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}${error.stack ? '\n' + error.stack : ''}`;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  return JSON.stringify(error);
+}
+
+/**
+ * 格式化错误对象为简短消息（不含堆栈）
+ */
+export function formatErrorShort(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`;
+  }
+  if (typeof error === 'string') {
+    return error;
+  }
+  return String(error);
+}
+
+/**
+ * 格式化日志上下文（添加时间戳和级别）
+ */
+export function formatLogContext(level: string, message: string, context?: Record<string, unknown>): string {
+  const timestamp = new Date().toISOString();
+  const contextStr = context ? ` ${JSON.stringify(context)}` : '';
+  return `[${timestamp}] [${level.toUpperCase()}] ${message}${contextStr}`;
+}
+
+/**
+ * 截断长字符串（用于日志显示）
+ */
+export function truncateString(str: string, maxLength: number = 100): string {
+  if (!str) return '';
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength) + '...';
+}
+
+/**
+ * 格式化 JSON 为紧凑格式（单行，无缩进）
+ */
+export function formatCompactJson(obj: unknown): string {
+  try {
+    return JSON.stringify(obj);
+  } catch {
+    return String(obj);
+  }
+}
+
+/**
+ * 格式化 JSON 为可读格式（多行，带缩进）
+ */
+export function formatPrettyJson(obj: unknown): string {
+  try {
+    return JSON.stringify(obj, null, 2);
+  } catch {
+    return String(obj);
+  }
+}

package/src/core/utils/logger.ts

@@ -0,0 +1,119 @@
+/**
+ * Simple logger writing to stderr (or file in daemon mode)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+let currentLevel = LogLevel.INFO;
+let logFilePath: string | null = null;
+let lastSizeCheck = 0;
+let cachedSize = 0;
+
+const MAX_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_FILES = 3;
+const SIZE_CHECK_INTERVAL = 60000; // Check size every 60s
+
+function timestamp(): string {
+  return new Date().toISOString();
+}
+
+function format(level: string, message: string): string {
+  return `[${timestamp()}] [${level}] ${message}`;
+}
+
+function rotateLogIfNeeded(): void {
+  if (!logFilePath || !fs.existsSync(logFilePath)) return;
+
+  // Cache size check to avoid frequent stat calls
+  const now = Date.now();
+  if (now - lastSizeCheck >= SIZE_CHECK_INTERVAL) {
+    const stats = fs.statSync(logFilePath);
+    cachedSize = stats.size;
+    lastSizeCheck = now;
+  }
+
+  // Check if rotation is needed
+  if (cachedSize < MAX_SIZE) return;
+
+  // Rotate: .log -> .log.1 -> .log.2 -> .log.3 (delete oldest)
+  try {
+    for (let i = MAX_FILES - 1; i >= 1; i--) {
+      const oldPath = `${logFilePath}.${i}`;
+      const newPath = `${logFilePath}.${i + 1}`;
+      if (fs.existsSync(oldPath)) {
+        if (i === MAX_FILES - 1) {
+          fs.unlinkSync(oldPath); // Delete oldest
+        } else {
+          fs.renameSync(oldPath, newPath);
+        }
+      }
+    }
+    fs.renameSync(logFilePath, `${logFilePath}.1`);
+    cachedSize = 0; // Reset cache after rotation
+    lastSizeCheck = 0; // Force recheck on next write
+  } catch (err) {
+    // If rotation fails, just continue (better than crashing)
+    console.error(`[Logger] Log rotation failed: ${err}`);
+  }
+}
+
+function write(level: LogLevel, levelName: string, message: string): void {
+  if (level < currentLevel) return;
+  const formatted = format(levelName, message);
+
+  if (logFilePath) {
+    rotateLogIfNeeded();
+    try {
+      fs.appendFileSync(logFilePath, formatted + '\n');
+      // Update cached size after write
+      cachedSize += formatted.length + 1;
+    } catch (err) {
+      // Fallback to stderr if file write fails
+      console.error(formatted);
+    }
+  } else {
+    console.error(formatted);
+  }
+}
+
+export const logger = {
+  debug(message: string): void {
+    write(LogLevel.DEBUG, 'DEBUG', message);
+  },
+
+  info(message: string): void {
+    write(LogLevel.INFO, 'INFO', message);
+  },
+
+  warn(message: string): void {
+    write(LogLevel.WARN, 'WARN', message);
+  },
+
+  error(message: string): void {
+    write(LogLevel.ERROR, 'ERROR', message);
+  },
+};
+
+export function setLogLevel(level: LogLevel): void {
+  currentLevel = level;
+}
+
+/**
+ * Enable file logging (for daemon mode)
+ * @param filePath Path to log file
+ */
+export function enableFileLogging(filePath: string): void {
+  logFilePath = filePath;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}

package/src/core/utils/lru-cache.ts

@@ -0,0 +1,50 @@
+/**
+ * Simple LRU cache for AI responses
+ */
+
+export class LRUCache<K, V> {
+  private cache = new Map<K, V>();
+  private maxSize: number;
+
+  constructor(maxSize: number = 100) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // Move to end (most recently used)
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    // Remove if exists (to update position)
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Add to end
+    this.cache.set(key, value);
+
+    // Evict oldest if over capacity
+    if (this.cache.size > this.maxSize) {
+      const firstKey = this.cache.keys().next().value as K;
+      this.cache.delete(firstKey);
+    }
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  size(): number {
+    return this.cache.size;
+  }
+}

package/src/core/utils/path.ts

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { relative } from 'node:path';
+
+/**
+ * Expand ~ to the user's home directory
+ */
+export function expandPath(p: string): string {
+  if (p.startsWith('~/') || p === '~') {
+    return homedir() + p.slice(1);
+  }
+  return p;
+}
+
+/**
+ * Return path relative to cwd
+ */
+export function relPath(p: string): string {
+  return relative(process.cwd(), p);
+}

package/src/core/utils/session.ts

@@ -0,0 +1,26 @@
+/**
+ * Session ID 处理工具
+ */
+
+/**
+ * 截断 Session ID 到指定长度（用于日志显示）
+ */
+export function truncateSessionId(sessionId: string, length: number = 8): string {
+  if (!sessionId) return 'unknown';
+  return sessionId.slice(0, length);
+}
+
+/**
+ * 验证 Session ID 格式（UUID v4）
+ */
+export function isValidSessionId(sessionId: string): boolean {
+  const uuidV4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidV4Regex.test(sessionId);
+}
+
+/**
+ * 生成短 Session ID（用于显示）
+ */
+export function formatSessionId(sessionId: string): string {
+  return `session:${truncateSessionId(sessionId)}`;
+}

package/src/core/utils/time.ts

@@ -0,0 +1,37 @@
+/**
+ * 时间戳归一化工具
+ *
+ * 统一处理 ISO 8601 时间戳的 Z 后缀问题，确保所有时间戳都带 Z。
+ */
+
+/**
+ * 归一化时间戳，确保带 Z 后缀
+ */
+export function normalizeTimestamp(timestamp: string): string {
+  if (!timestamp) return new Date().toISOString();
+  return timestamp.endsWith('Z') ? timestamp : timestamp + 'Z';
+}
+
+/**
+ * 将时间戳转换为 Unix 毫秒数
+ */
+export function timestampToMs(timestamp: string): number {
+  return new Date(normalizeTimestamp(timestamp)).getTime();
+}
+
+/**
+ * 计算两个时间戳之间的毫秒差
+ */
+export function timeDiff(start: string, end: string): number {
+  return timestampToMs(end) - timestampToMs(start);
+}
+
+/**
+ * 格式化时间差为人类可读格式
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms < 3600000) return `${(ms / 60000).toFixed(1)}m`;
+  return `${(ms / 3600000).toFixed(1)}h`;
+}

package/src/core/utils/token-tracker.ts

@@ -0,0 +1,97 @@
+/**
+ * Token usage tracker — centralized token recording and budget alerting
+ */
+
+import type { SQLiteStorage } from '../storage/sqlite.js';
+import type { TokenUsage } from '../ai/types.js';
+import { logger } from './logger.js';
+
+export interface TokenRecordParams {
+  session_id: string;
+  usage: TokenUsage;
+  model?: string;
+  tool_name?: string;
+}
+
+export class TokenTracker {
+  private storage: SQLiteStorage;
+  private budgetPerSession: number;
+  private warningThreshold: number;
+
+  constructor(storage: SQLiteStorage, options?: {
+    budgetPerSession?: number;
+    warningThreshold?: number;
+  }) {
+    this.storage = storage;
+    this.budgetPerSession = options?.budgetPerSession
+      ?? parseInt(process.env.TOKEN_BUDGET_PER_SESSION ?? '1000000');
+    this.warningThreshold = options?.warningThreshold ?? 0.8;
+  }
+
+  /**
+   * Record token usage and check budget
+   */
+  record(params: TokenRecordParams): void {
+    try {
+      this.storage.recordTokenUsage({
+        session_id: params.session_id,
+        input_tokens: params.usage.input_tokens,
+        output_tokens: params.usage.output_tokens,
+        model: params.model,
+        tool_name: params.tool_name,
+      });
+
+      this.checkBudget(params.session_id);
+    } catch (err) {
+      logger.debug(`[TokenTracker] Failed to record token usage: ${err}`);
+    }
+  }
+
+  /**
+   * Check if session has exceeded budget thresholds
+   */
+  private checkBudget(session_id: string): void {
+    try {
+      const usage = this.storage.getTokenUsageBySession(session_id);
+      const usageRatio = usage.total_tokens / this.budgetPerSession;
+
+      if (usageRatio >= 1.0) {
+        console.error(
+          `\x1b[31m🚨 [Forge:Token预算] Session ${session_id.slice(0, 8)} 已超预算！\x1b[0m\n` +
+          `   已用: ${usage.total_tokens.toLocaleString()} tokens\n` +
+          `   预算: ${this.budgetPerSession.toLocaleString()} tokens\n` +
+          `   超出: ${((usageRatio - 1) * 100).toFixed(1)}%`
+        );
+        logger.warn(
+          `[TokenTracker] Session ${session_id} exceeded budget: ${usage.total_tokens}/${this.budgetPerSession}`
+        );
+      } else if (usageRatio >= this.warningThreshold) {
+        console.warn(
+          `\x1b[33m⚠️  [Forge:Token预算] Session ${session_id.slice(0, 8)} 已用 ${(usageRatio * 100).toFixed(1)}% 预算\x1b[0m\n` +
+          `   已用: ${usage.total_tokens.toLocaleString()} tokens\n` +
+          `   预算: ${this.budgetPerSession.toLocaleString()} tokens`
+        );
+      }
+    } catch (err) {
+      logger.debug(`[TokenTracker] Failed to check budget: ${err}`);
+    }
+  }
+
+  /**
+   * Get current usage for a session
+   */
+  getSessionUsage(session_id: string): {
+    total_tokens: number;
+    input_tokens: number;
+    output_tokens: number;
+    budget: number;
+    usage_ratio: number;
+  } {
+    const usage = this.storage.getTokenUsageBySession(session_id);
+    return {
+      ...usage,
+      budget: this.budgetPerSession,
+      usage_ratio: usage.total_tokens / this.budgetPerSession,
+    };
+  }
+}

package/src/daemon/event-parser.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import type { ForgeEvent } from '../core/types.js';
+import { randomUUID } from 'crypto';
+
+const RawHookEventSchema = z.object({
+  hook_type: z.enum(['PreToolUse', 'PostToolUse', 'Notification', 'Stop', 'UserPromptSubmit']),
+  timestamp: z.string(),
+  session_id: z.string(),
+  project_path: z.string(),
+  tool_name: z.string().optional(),
+  tool_input: z.record(z.string(), z.unknown()).optional(),
+  tool_output: z.record(z.string(), z.unknown()).optional(),
+  user_prompt: z.string().optional(),
+  ai_response: z.string().optional(),
+});
+
+export class EventParser {
+  parse(raw: string): ForgeEvent {
+    const json = JSON.parse(raw);
+    const validated = RawHookEventSchema.parse(json);
+
+    return {
+      event_id: randomUUID(),
+      session_id: validated.session_id,
+      project_path: validated.project_path,
+      timestamp: validated.timestamp,
+      hook_type: validated.hook_type,
+      tool_name: validated.tool_name,
+      tool_input: validated.tool_input as Record<string, unknown> | undefined,
+      tool_output: validated.tool_output as Record<string, unknown> | undefined,
+      user_prompt: validated.user_prompt,
+      ai_response: validated.ai_response,
+    };
+  }
+}

package/src/daemon/handlers/history-exporter.ts

@@ -0,0 +1,117 @@
+/**
+ * HistoryExporter — exports session history to markdown
+ *
+ * Writes session history to .claude-forge/history/YYYY-MM-DD-{session}.md
+ * Adapted from src-old with simplified dependencies.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { ForgeEvent } from '../../core/types.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { logger } from '../../core/utils/logger.js';
+import { truncateSessionId } from '../../core/utils/session.js';
+import { normalizeTimestamp } from '../../core/utils/time.js';
+
+export class HistoryExporter {
+  constructor(private storage: SQLiteStorage) {}
+
+  async export(event: ForgeEvent): Promise<void> {
+    const { session_id, project_path } = event;
+    if (!project_path) return;
+
+    try {
+      const historyDir = path.join(project_path, '.claude-forge', 'history');
+      if (!fs.existsSync(historyDir)) {
+        fs.mkdirSync(historyDir, { recursive: true });
+      }
+
+      const events = this.storage.queryEvents({
+        session_id,
+        project_path,
+      });
+      if (events.length === 0) return;
+
+      const now = new Date();
+      const dateStr = now.toISOString().slice(0, 10);
+      const shortSession = truncateSessionId(session_id);
+      const filePath = path.join(
+        historyDir,
+        `${dateStr}-${shortSession}.md`
+      );
+
+      const content = this.buildMarkdown(events, session_id, project_path);
+      fs.writeFileSync(filePath, content, 'utf-8');
+      logger.info(`[HistoryExporter] Wrote ${filePath}`);
+    } catch (err) {
+      logger.warn(`[HistoryExporter] Export failed: ${err}`);
+    }
+  }
+
+  private buildMarkdown(
+    events: ForgeEvent[],
+    sessionId: string,
+    projectPath: string
+  ): string {
+    const lines: string[] = [];
+    const startTime = normalizeTimestamp(events[0]?.timestamp ?? new Date().toISOString());
+    const endTime = normalizeTimestamp(events[events.length - 1]?.timestamp ?? startTime);
+
+    lines.push(`# 会话记录 ${truncateSessionId(sessionId)}`);
+    lines.push('');
+    lines.push(`- **时间**: ${startTime} → ${endTime}`);
+    lines.push(`- **项目**: ${projectPath}`);
+    lines.push(`- **事件数**: ${events.length}`);
+    lines.push('');
+
+    // User prompt summary
+    const prompts = events.filter(
+      (e) => e.hook_type === 'UserPromptSubmit' && e.user_prompt
+    );
+    if (prompts.length > 0) {
+      lines.push('## 用户指令');
+      lines.push('');
+      for (const p of prompts) {
+        const time = new Date(p.timestamp).toLocaleTimeString();
+        const text = (p.user_prompt as string).slice(0, 200);
+        lines.push(`- **${time}**: ${text}`);
+      }
+      lines.push('');
+    }
+
+    // Tool call timeline
+    const toolCalls = events.filter(
+      (e) => e.hook_type === 'PostToolUse' && e.tool_name
+    );
+    if (toolCalls.length > 0) {
+      lines.push('## 工具调用');
+      lines.push('');
+      const grouped = new Map<string, number>();
+      for (const t of toolCalls) {
+        grouped.set(t.tool_name!, (grouped.get(t.tool_name!) ?? 0) + 1);
+      }
+      for (const [tool, count] of grouped) {
+        lines.push(`- ${tool}: ${count} 次`);
+      }
+      lines.push('');
+
+      lines.push('### 时间线');
+      lines.push('');
+      for (const t of toolCalls.slice(-30)) {
+        const time = new Date(t.timestamp).toLocaleTimeString();
+        const input = t.tool_input as Record<string, unknown> | undefined;
+        const filePath = input?.file_path ?? input?.command ?? '';
+        const summary =
+          typeof filePath === 'string' ? filePath.slice(0, 80) : '';
+        lines.push(`- ${time} \`${t.tool_name}\` ${summary}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('---');
+    lines.push(`_生成时间: ${new Date().toISOString()}_`);
+    lines.push('');
+
+    return lines.join('\n');
+  }
+}

package/src/daemon/handlers/post-tool-use.ts

@@ -0,0 +1,50 @@
+/**
+ * PostToolUseHandler — handles PostToolUse hook
+ *
+ * Simplified: only tracks token usage if available.
+ * Also observes Agent tool calls to update routing_events.
+ */
+
+import type { PostToolUseEvent, HookResult } from '../../core/types.js';
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import { logger } from '../../core/utils/logger.js';
+import { TokenTracker } from '../../core/utils/token-tracker.js';
+
+export class PostToolUseHandler {
+  private tokenTracker: TokenTracker | null = null;
+
+  constructor(
+    private storage: SQLiteStorage | null = null,
+  ) {
+    if (storage) {
+      this.tokenTracker = new TokenTracker(storage);
+    }
+  }
+
+  async handle(event: PostToolUseEvent): Promise<HookResult> {
+    // Observe Agent tool calls and update routing_events
+    if (this.storage && event.tool_name === 'Agent') {
+      try {
+        // PostToolUseEvent.tool_input is already a Record (narrowed by type guard).
+        const agentType = (event.tool_input.subagent_type as string) || 'general-purpose';
+
+        // Find the most recent routing_event for this session
+        const recentEvent = this.storage.getRecentRoutingEvent(event.session_id);
+        if (recentEvent) {
+          this.storage.updateRoutingEvent(recentEvent.id, {
+            routed_to_type: 'agent',
+            routed_to_name: agentType,
+            obeyed: 1,
+            first_tool_name: 'Agent',
+            first_tool_ts: Date.now(),
+          });
+          logger.debug(`[PostToolUse] Updated routing_event ${recentEvent.id} with Agent: ${agentType}`);
+        }
+      } catch (err) {
+        logger.debug(`[PostToolUse] Failed to update routing_event: ${err}`);
+      }
+    }
+
+    return { allow: true };
+  }
+}