@winspan/claude-forge 8.51.1 → 8.54.3

package/src/hooks/pre-tool-use.sh

@@ -1,63 +0,0 @@
-#!/usr/bin/env bash
-# Claude Forge - PreToolUse Hook（双向通信）
-
-# shellcheck source=./hook-lib.sh
-source "$(dirname "$0")/hook-lib.sh"
-
-AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
-
-# 读取 stdin（Claude Code 传入的 JSON）
-INPUT=$(cat)
-
-# 提取字段（单次 jq 调用，替代 3 个 python3 进程）
-TOOL_NAME="${CLAUDE_TOOL_NAME:-$(echo "$INPUT" | jq -r '.tool_name // ""')}"
-TOOL_INPUT=$(echo "$INPUT" | jq -c '.tool_input // {}')
-RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
-SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
-
-# 构造事件 JSON（jq -n 替代 python3 heredoc）
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
-EVENT=$(jq -n \
-  --arg hook_type "PreToolUse" \
-  --arg timestamp "$TIMESTAMP" \
-  --arg session_id "$SESSION_ID" \
-  --arg project_path "$PROJECT_PATH" \
-  --arg tool_name "$TOOL_NAME" \
-  --argjson tool_input "$TOOL_INPUT" \
-  --arg auth "$AUTH_TOKEN" \
-  '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
-    project_path: $project_path, tool_name: $tool_name, tool_input: $tool_input,
-    _auth: $auth}')
-
-# 发送事件（5 秒超时；失败时入队）
-send_event_or_enqueue "$EVENT" 5
-RESPONSE="$HOOK_RESPONSE"
-
-if [ -n "$RESPONSE" ]; then
-  ALLOW=$(echo "$RESPONSE" | jq -r '.allow // true')
-
-  if [ "$ALLOW" = "false" ]; then
-    # 优先使用 hookSpecificOutput（Claude Code 官方格式），否则降级到 stderr + exit 2
-    HAS_HOOK_OUTPUT=$(echo "$RESPONSE" | jq -r 'if .hookSpecificOutput then "yes" else "no" end')
-    if [ "$HAS_HOOK_OUTPUT" = "yes" ]; then
-      # 输出 hookSpecificOutput 格式到 stdout，但必须 exit 非0 才能真正阻止工具执行
-      echo "$RESPONSE" | jq '{hookSpecificOutput: .hookSpecificOutput}'
-      exit 1
-    else
-      # 降级：输出原因到 stderr，exit 2 强制阻断
-      REASON=$(echo "$RESPONSE" | jq -r '.reason // "操作被 Forge 阻断"')
-      echo "$REASON" >&2
-      exit 2
-    fi
-  fi
-
-  # 有 additionalContext 时输出
-  HAS_CONTEXT=$(echo "$RESPONSE" | jq -r 'if .additionalContext and (.additionalContext != "") then "yes" else "no" end')
-  if [ "$HAS_CONTEXT" = "yes" ]; then
-    echo "$RESPONSE"
-  fi
-fi
-
-exit 0

package/src/hooks/stop.sh

@@ -1,43 +0,0 @@
-#!/usr/bin/env bash
-# Claude Forge - Stop Hook
-
-# shellcheck source=./hook-lib.sh
-source "$(dirname "$0")/hook-lib.sh"
-
-AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
-
-# 读取 stdin
-INPUT=$(cat 2>/dev/null || echo '{}')
-
-# 提取 cwd，上溯 git root
-RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
-SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
-
-# 构造事件 JSON
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
-EVENT=$(jq -n \
-  --arg hook_type "Stop" \
-  --arg timestamp "$TIMESTAMP" \
-  --arg session_id "$SESSION_ID" \
-  --arg project_path "$PROJECT_PATH" \
-  --arg auth "$AUTH_TOKEN" \
-  '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
-    project_path: $project_path, tool_name: "stop", tool_input: {}, _auth: $auth}')
-
-# 发送事件并读取响应（失败时入队）
-send_event_or_enqueue "$EVENT" 5
-RESPONSE="$HOOK_RESPONSE"
-
-# 解析响应：allow=false 时输出 reason 并以 exit 2 阻断
-if [ -n "$RESPONSE" ]; then
-  ALLOW=$(echo "$RESPONSE" | jq -r '.allow // true' 2>/dev/null)
-  if [ "$ALLOW" = "false" ]; then
-    REASON=$(echo "$RESPONSE" | jq -r '.reason // "质量门禁阻断"' 2>/dev/null)
-    echo "$REASON"
-    exit 2
-  fi
-fi
-
-exit 0

package/src/hooks/user-prompt-submit.sh

@@ -1,69 +0,0 @@
-#!/usr/bin/env bash
-# Claude Forge - UserPromptSubmit Hook
-# 拦截用户输入，触发意图分析和自动 Pipeline 编排
-
-# shellcheck source=./hook-lib.sh
-source "$(dirname "$0")/hook-lib.sh"
-
-AUTH_TOKEN=$(cat "$HOME/.claude-forge/daemon.token" 2>/dev/null || echo '')
-
-# 读取 stdin（Claude Code 传入的 JSON）
-INPUT=$(cat)
-
-# 提取字段（jq 替代 python3）
-USER_PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""')
-RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
-PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // .sessionId // ""')
-SESSION_ID="${SESSION_ID:-${CLAUDE_CODE_SESSION_ID:-cli}}"
-
-# 空 prompt 跳过
-if [ -z "$USER_PROMPT" ]; then
-  exit 0
-fi
-
-# 构造事件 JSON（jq -n 替代 python3 heredoc）
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
-EVENT=$(jq -n \
-  --arg hook_type "UserPromptSubmit" \
-  --arg timestamp "$TIMESTAMP" \
-  --arg session_id "$SESSION_ID" \
-  --arg project_path "$PROJECT_PATH" \
-  --arg user_prompt "$USER_PROMPT" \
-  --arg auth "$AUTH_TOKEN" \
-  '{hook_type: $hook_type, timestamp: $timestamp, session_id: $session_id,
-    project_path: $project_path, tool_name: "UserPrompt",
-    user_prompt: $user_prompt, tool_input: {user_prompt: $user_prompt}, _auth: $auth}')
-
-if [ -z "$EVENT" ]; then
-  exit 0
-fi
-
-# 发送事件（10 秒超时，AI 分析可能需要更多时间）
-# 失败时自动入队（daemon 停机期间事件不丢失）
-send_event_or_enqueue "$EVENT" 10
-RESPONSE="$HOOK_RESPONSE"
-
-if [ -n "$RESPONSE" ]; then
-  HAS_SYSTEM=$(echo "$RESPONSE" | jq -r 'if .systemMessage and (.systemMessage != "") then "yes" else "no" end')
-  HAS_CONTEXT=$(echo "$RESPONSE" | jq -r 'if .additionalContext and (.additionalContext != "") then "yes" else "no" end')
-
-  if [ "$HAS_SYSTEM" = "yes" ] || [ "$HAS_CONTEXT" = "yes" ]; then
-    # stderr 输出摘要到终端
-    if [ "$HAS_SYSTEM" = "yes" ]; then
-      SM_LEN=$(echo "$RESPONSE" | jq -r '.systemMessage | length')
-      printf '\033[36m💉 [Forge] 注入 systemMessage (%s chars)\033[0m\n' "$SM_LEN" >&2
-    fi
-    if [ "$HAS_CONTEXT" = "yes" ]; then
-      CONTEXT=$(echo "$RESPONSE" | jq -r '.additionalContext // ""')
-      DISPLAY_LINES=$(printf '%s' "$CONTEXT" | head -3)
-      if [ -n "$DISPLAY_LINES" ]; then
-        printf '\033[36m💉 [Forge] %s\033[0m\n' "$DISPLAY_LINES" >&2
-      fi
-    fi
-    # stdout 返回给 Claude Code
-    echo "$RESPONSE"
-  fi
-fi
-
-exit 0

package/src/mcp/server.ts

@@ -1,322 +0,0 @@
-/**
- * MCP Server for claude-forge
- *
- * 嵌入在 daemon 进程内，通过 HTTP（Streamable HTTP transport）向 Claude Code
- * 暴露以下工具：
- *   - skill_invoke：Agent 按需获取某个 Skill 的方法论内容
- *   - skill_list：列出所有可用 Skill（id / name / description / keywords）
- *
- * 调用链路：
- *   Claude Code → HTTP POST /mcp → MCP server → skillInvoke()/skillList()
- *                                            → writeSkillInvocation() 记录
- *
- * 设计要点：
- *   - 复用现有 Express app（不新增端口），路径前缀固定为 /mcp
- *   - 沿用 daemon auth token（Bearer），与 /api 写操作同一鉴权链路
- *   - Stateless 模式：每个请求开一对 server/transport，避免长连接污染
- *     daemon 主循环；Skill 调用本身是短平快、无需流式推送的场景
- *   - Session 追踪：优先 header `X-Forge-Session-Id`，缺失时生成匿名 session
- *     (Ruflo 模式下 Claude 自主决策，不需要 routing state 回退)
- */
-
-import type { Application, Request, Response } from 'express';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { z } from 'zod';
-
-import type { SkillRegistry } from '../skills/registry.js';
-import type { SQLiteStorage } from '../core/storage/sqlite.js';
-import type { InvocationGuard } from '../skills/invocation-guard.js';
-import { skillInvoke } from '../skills/tools/skill-invoke.js';
-import { skillList } from '../skills/tools/skill-list.js';
-import { pipelineSuggest } from '../skills/tools/pipeline-suggest.js';
-import { logger } from '../core/utils/logger.js';
-import { requireAuth } from '../web/auth-middleware.js';
-
-/** Resolved session context for a single MCP tool call. */
-export interface SessionContext {
-  sessionId: string | null;
-  routeRequestId: string | null;
-  agentId: string | null;
-}
-
-export interface McpServerOptions {
-  skillRegistry: SkillRegistry;
-  storage: SQLiteStorage;
-  guard?: InvocationGuard;
-  /**
-   * Override the session-resolution strategy. Default behavior:
-   *   1. Read header `X-Forge-Session-Id` (passed by the harness if available)
-   *   2. Fallback: pick the freshest live routing entry from routingState
-   *   3. If neither yields a sessionId → return all-null context (invocation
-   *      will be recorded with session_id derived from the synthetic
-   *      "mcp-anon-<ts>" so the writeSkillInvocation NOT NULL constraint still
-   *      passes; see resolveSessionContext below).
-   */
-  resolveSession?: (req: Request) => SessionContext;
-}
-
-const SERVER_INFO = {
-  name: 'claude-forge',
-  version: '1.0.0',
-} as const;
-
-/**
- * Resolve session context for a request.
- *
- * Priority order:
- *   1. Explicit header `X-Forge-Session-Id` (+ optional `X-Forge-Route-Request-Id`,
- *      `X-Forge-Agent-Id`).
- *   2. routingState.getMostRecent() — heuristic fallback during the routing
- *      window (≤30min TTL).
- *   3. Synthetic anonymous session "mcp-anon-<unix-ts>" so we never blow the
- *      NOT NULL session_id constraint when persisting invocations.
- */
-function resolveSessionContext(req: Request): SessionContext {
-  const headerSession = req.header('X-Forge-Session-Id');
-  if (headerSession && headerSession.trim().length > 0) {
-    const headerRoute = req.header('X-Forge-Route-Request-Id');
-    const headerAgent = req.header('X-Forge-Agent-Id');
-    return {
-      sessionId: headerSession.trim(),
-      routeRequestId: headerRoute?.trim() || null,
-      agentId: headerAgent?.trim() || null,
-    };
-  }
-
-  // In Ruflo mode, Claude makes autonomous decisions via CLAUDE.md.
-  // MCP tools no longer need routing state fallback.
-  return {
-    sessionId: `mcp-anon-${Date.now()}`,
-    routeRequestId: null,
-    agentId: null,
-  };
-}
-
-/** Build a fresh MCP server instance bound to the given options & context. */
-function buildServer(
-  options: McpServerOptions,
-  sessionCtx: SessionContext,
-): McpServer {
-  const server = new McpServer(SERVER_INFO, {
-    capabilities: { tools: { listChanged: false } },
-  });
-
-  // ── Tool 1: skill_invoke ───────────────────────────────────────────────
-  server.registerTool(
-    'skill_invoke',
-    {
-      title: 'Invoke a claude-forge skill',
-      description:
-        '调用指定的 Skill，获取该方法论的完整内容。使用场景：当你需要特定领域的方法论指导（如 TDD、重构、性能优化）时。',
-      inputSchema: {
-        skill_id: z
-          .string()
-          .min(1)
-          .describe('Skill 的 ID（如 "official-tdd"）。可通过 skill_list 工具查询。'),
-        reason: z
-          .string()
-          .optional()
-          .describe('调用理由（可选，用于审计 / skill_invocations.reason 列）'),
-      },
-    },
-    async (args) => {
-      try {
-        const sessionId = sessionCtx.sessionId ?? `mcp-anon-${Date.now()}`;
-        const result = await skillInvoke(
-          { skill_id: args.skill_id, reason: args.reason },
-          {
-            skillRegistry: options.skillRegistry,
-            guard: options.guard,
-            storage: options.storage,
-            sessionId,
-            routeRequestId: sessionCtx.routeRequestId ?? undefined,
-            agentId: sessionCtx.agentId ?? undefined,
-            invocationType: 'dynamic',
-          },
-        );
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `# ${result.skill_name}\n\n${result.content}`,
-            },
-          ],
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.warn(`[MCP] skill_invoke failed: ${message}`);
-        return {
-          isError: true,
-          content: [{ type: 'text' as const, text: message }],
-        };
-      }
-    },
-  );
-
-  // ── Tool 2: skill_list ─────────────────────────────────────────────────
-  server.registerTool(
-    'skill_list',
-    {
-      title: 'List available claude-forge skills',
-      description: '列出所有可用的 Skill。可以通过 keywords 过滤（OR 语义）。',
-      inputSchema: {
-        keywords: z
-          .array(z.string())
-          .optional()
-          .describe('可选的关键词过滤（如 ["test", "tdd"]）'),
-      },
-    },
-    async (args) => {
-      try {
-        logger.info(`[MCP] skill_list called with args: ${JSON.stringify(args)}`);
-        const result = await skillList(
-          { keywords: args.keywords },
-          { skillRegistry: options.skillRegistry },
-        );
-        return {
-          content: [
-            { type: 'text' as const, text: JSON.stringify(result, null, 2) },
-          ],
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.warn(`[MCP] skill_list failed: ${message}`);
-        return {
-          isError: true,
-          content: [{ type: 'text' as const, text: message }],
-        };
-      }
-    },
-  );
-
-  // ── Tool 3: pipeline_suggest ───────────────────────────────────────────
-  server.registerTool(
-    'pipeline_suggest',
-    {
-      title: 'Suggest a swarm pipeline for a task',
-      description:
-        '根据任务特征判断是否需要启动多 Agent 协作的 Pipeline，并生成可直接使用的 Task({...}) 调用代码。',
-      inputSchema: {
-        task_description: z
-          .string()
-          .min(1)
-          .describe('任务描述（如 "修复用户登录时的 session 过期问题"）'),
-        file_count: z
-          .number()
-          .int()
-          .optional()
-          .describe('预估涉及的文件数量（>=2 时建议使用 Pipeline）'),
-        is_new_feature: z
-          .boolean()
-          .optional()
-          .describe('是否为新功能开发'),
-        is_refactor: z
-          .boolean()
-          .optional()
-          .describe('是否为重构任务'),
-        is_bug_fix: z
-          .boolean()
-          .optional()
-          .describe('是否为 Bug 修复'),
-        is_performance: z
-          .boolean()
-          .optional()
-          .describe('是否为性能优化'),
-        is_migration: z
-          .boolean()
-          .optional()
-          .describe('是否为技术迁移/升级'),
-        is_security: z
-          .boolean()
-          .optional()
-          .describe('是否为安全审计/漏洞修复'),
-      },
-    },
-    async (args) => {
-      try {
-        const result = await pipelineSuggest({
-          task_description: args.task_description,
-          file_count: args.file_count,
-          is_new_feature: args.is_new_feature,
-          is_refactor: args.is_refactor,
-          is_bug_fix: args.is_bug_fix,
-          is_performance: args.is_performance,
-          is_migration: args.is_migration,
-          is_security: args.is_security,
-        });
-        return {
-          content: [
-            { type: 'text' as const, text: JSON.stringify(result, null, 2) },
-          ],
-        };
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        logger.warn(`[MCP] pipeline_suggest failed: ${message}`);
-        return {
-          isError: true,
-          content: [{ type: 'text' as const, text: message }],
-        };
-      }
-    },
-  );
-
-  return server;
-}
-
-/**
- * Mount the MCP server endpoints on an existing Express application.
- *
- * Routes:
- *   POST /mcp   — JSON-RPC over Streamable HTTP (initialize, tools/list, tools/call)
- *   GET  /mcp   — Standalone SSE channel (server→client notifications)
- *   DELETE /mcp — Session termination (stateful mode only; no-op in stateless)
- *
- * Authentication: every method requires the daemon Bearer token. Token-file
- * absence still falls through (early-startup safety, identical to /api).
- */
-export function mountMcpServer(app: Application, options: McpServerOptions): void {
-  const resolveSession = options.resolveSession ?? resolveSessionContext;
-
-  const handler = async (req: Request, res: Response): Promise<void> => {
-    // Stateless: build a fresh server+transport per request. The transport
-    // mutates res so it cannot be reused across requests anyway.
-    const sessionCtx = resolveSession(req);
-    const server = buildServer(options, sessionCtx);
-    const transport = new StreamableHTTPServerTransport({
-      // Stateless mode — no session ID generator.
-      sessionIdGenerator: undefined,
-      enableJsonResponse: true,
-    });
-
-    res.on('close', () => {
-      // best-effort cleanup; ignore errors because transport may already be closed
-      void transport.close().catch(() => undefined);
-      void server.close().catch(() => undefined);
-    });
-
-    try {
-      await server.connect(transport);
-      // express.json() has already populated req.body; pass it through.
-      await transport.handleRequest(req, res, req.body);
-    } catch (err) {
-      logger.warn(`[MCP] request failed: ${err instanceof Error ? err.message : String(err)}`);
-      if (!res.headersSent) {
-        res.status(500).json({
-          jsonrpc: '2.0',
-          error: { code: -32603, message: 'Internal error' },
-          id: null,
-        });
-      }
-    }
-  };
-
-  // All MCP requests are auth-gated. We deliberately gate GET too because MCP
-  // tool-calls (sensitive ops) can come over GET via SSE; /api keeps GET open
-  // only for read-only dashboard polling.
-  app.post('/mcp', requireAuth, handler);
-  app.get('/mcp', requireAuth, handler);
-  app.delete('/mcp', requireAuth, handler);
-
-  logger.info('[MCP] Server mounted on /mcp (Streamable HTTP, stateless)');
-}

package/src/skills/index.ts

@@ -1,2 +0,0 @@
-export { SkillRegistry, type Skill } from './registry.js';
-export { matchKeywords, formatSkillRecommendation } from './matcher.js';

package/src/skills/invocation-guard.ts

@@ -1,177 +0,0 @@
-/**
- * InvocationGuard — Skill 调用防护机制
- *
- * 防止 Agent 陷入无限调用 Skill 的循环，限制：
- * - 单会话总调用次数（默认 10）
- * - 单会话调用深度（默认 3）
- * - 同 session 同 skill 幂等（避免重复调用）
- * - TTL 机制：会话状态 30 分钟后自动过期
- *
- * 状态为进程内存，进程重启会清空；调用链路通常集中在单个会话内，
- * 重启后重建状态是可接受的。
- */
-
-const MAX_INVOCATIONS_PER_SESSION = 10;
-const MAX_INVOCATION_DEPTH = 3;
-const SESSION_TTL_MS = 30 * 60 * 1000; // 30 minutes
-const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
-
-export interface SessionInvocations {
-  total: number;
-  depth: number;
-  calledSkills: Set<string>;
-  lastAccessTime: number; // Timestamp of last access
-}
-
-export interface InvocationCheckResult {
-  allowed: boolean;
-  reason?: string;
-}
-
-export class InvocationGuard {
-  private sessions = new Map<string, SessionInvocations>();
-  private cleanupTimer: NodeJS.Timeout | null = null;
-
-  constructor() {
-    // Start automatic cleanup timer
-    this.startCleanupTimer();
-  }
-
-  /**
-   * 检查是否允许调用。
-   * 不修改状态；调用方决定是否继续后调用 record()。
-   */
-  check(sessionId: string, skillId: string): InvocationCheckResult {
-    const session = this.sessions.get(sessionId) ?? {
-      total: 0,
-      depth: 0,
-      calledSkills: new Set<string>(),
-      lastAccessTime: Date.now(),
-    };
-
-    // Check if session has expired
-    if (Date.now() - session.lastAccessTime > SESSION_TTL_MS) {
-      this.sessions.delete(sessionId);
-      return { allowed: true }; // Expired session, allow new invocation
-    }
-
-    if (session.total >= MAX_INVOCATIONS_PER_SESSION) {
-      return {
-        allowed: false,
-        reason: `Reached max invocations per session (${MAX_INVOCATIONS_PER_SESSION})`,
-      };
-    }
-
-    if (session.depth >= MAX_INVOCATION_DEPTH) {
-      return {
-        allowed: false,
-        reason: `Reached max invocation depth (${MAX_INVOCATION_DEPTH})`,
-      };
-    }
-
-    if (session.calledSkills.has(skillId)) {
-      return {
-        allowed: false,
-        reason: `Skill '${skillId}' already invoked in this session (idempotent guard)`,
-      };
-    }
-
-    return { allowed: true };
-  }
-
-  /**
-   * 记录一次调用开始（递增 total 和 depth，登记 skill）。
-   */
-  record(sessionId: string, skillId: string): void {
-    const session = this.sessions.get(sessionId) ?? {
-      total: 0,
-      depth: 0,
-      calledSkills: new Set<string>(),
-      lastAccessTime: Date.now(),
-    };
-    session.total += 1;
-    session.depth += 1;
-    session.calledSkills.add(skillId);
-    session.lastAccessTime = Date.now(); // Update access time
-    this.sessions.set(sessionId, session);
-  }
-
-  /**
-   * 调用完成，递减 depth（不清除已调用 skills）。
-   */
-  complete(sessionId: string): void {
-    const session = this.sessions.get(sessionId);
-    if (session) {
-      session.depth = Math.max(0, session.depth - 1);
-      session.lastAccessTime = Date.now(); // Update access time
-    }
-  }
-
-  /**
-   * 清理会话（Stop hook 或会话结束时调用）。
-   */
-  clear(sessionId: string): void {
-    this.sessions.delete(sessionId);
-  }
-
-  /**
-   * 获取会话统计（调试/观测用）。
-   */
-  getStats(sessionId: string): SessionInvocations | null {
-    return this.sessions.get(sessionId) ?? null;
-  }
-
-  /**
-   * 清理过期会话（TTL 机制）。
-   */
-  private cleanupExpiredSessions(): void {
-    const now = Date.now();
-    const expiredSessions: string[] = [];
-
-    for (const [sessionId, session] of this.sessions.entries()) {
-      if (now - session.lastAccessTime > SESSION_TTL_MS) {
-        expiredSessions.push(sessionId);
-      }
-    }
-
-    for (const sessionId of expiredSessions) {
-      this.sessions.delete(sessionId);
-    }
-
-    if (expiredSessions.length > 0) {
-      // Use console.log instead of logger to avoid circular dependency
-      console.log(`[InvocationGuard] Cleaned up ${expiredSessions.length} expired sessions`);
-    }
-  }
-
-  /**
-   * 启动自动清理定时器。
-   */
-  private startCleanupTimer(): void {
-    if (this.cleanupTimer) return;
-
-    this.cleanupTimer = setInterval(() => {
-      this.cleanupExpiredSessions();
-    }, CLEANUP_INTERVAL_MS);
-
-    // Prevent timer from keeping process alive
-    this.cleanupTimer.unref();
-  }
-
-  /**
-   * 停止自动清理定时器（用于测试或进程关闭）。
-   */
-  stopCleanupTimer(): void {
-    if (this.cleanupTimer) {
-      clearInterval(this.cleanupTimer);
-      this.cleanupTimer = null;
-    }
-  }
-
-  /**
-   * 获取当前会话数量（用于监控）。
-   */
-  getSessionCount(): number {
-    return this.sessions.size;
-  }
-}