@gt-fe/eap-runtime 0.0.8

package/dist/token/token-budget-guard.js

@@ -0,0 +1,97 @@
+/**
+ * TokenBudgetGuard — Token 配额守卫
+ *
+ * 在每次 LLM/Tool 调用后执行配额检查：
+ * 1. 累加消耗到 task / session / agent 三级 scope
+ * 2. 检查三级配额是否耗尽
+ * 3. 若任一级耗尽，抛出 TokenBudgetExhaustedError，Graph 执行循环捕获后标记 Task 为 token_exhausted
+ *
+ * @see design.md §1.2 Token Budget检查（贯穿执行过程）
+ * @see requirements.md Requirement 12 AC2
+ */
+// ─────────────────────────────────────────────
+// TokenBudgetExhaustedError — 配额耗尽异常
+// ─────────────────────────────────────────────
+/**
+ * TokenBudgetExhaustedError — Token 配额耗尽时抛出
+ *
+ * Graph 执行循环应捕获此错误并将 Task 标记为 token_exhausted。
+ */
+export class TokenBudgetExhaustedError extends Error {
+    /** 耗尽的配额作用域 */
+    scope;
+    /** 对应 scope 的实体 ID */
+    scopeId;
+    /** 已消耗 Token 数 */
+    consumed;
+    /** 配额上限 */
+    quota;
+    constructor(scope, scopeId, consumed, quota) {
+        super(`Token budget exhausted: scope=${scope}, scopeId=${scopeId}, consumed=${consumed}, quota=${quota}`);
+        this.name = 'TokenBudgetExhaustedError';
+        this.scope = scope;
+        this.scopeId = scopeId;
+        this.consumed = consumed;
+        this.quota = quota;
+    }
+}
+// ─────────────────────────────────────────────
+// TokenBudgetGuard — 配额守卫实现
+// ─────────────────────────────────────────────
+/**
+ * TokenBudgetGuard — 每次 LLM/Tool 调用后的配额检查守卫
+ *
+ * 使用方式：在 Graph 执行循环中，每次 LLM/Tool 调用完成后调用 checkAndConsume。
+ * 若配额耗尽，将抛出 TokenBudgetExhaustedError，Graph 循环捕获后终止执行。
+ *
+ * @example
+ * ```ts
+ * const guard = new TokenBudgetGuard(budgetService);
+ * try {
+ *   // ... LLM/Tool 调用 ...
+ *   await guard.checkAndConsume(taskId, sessionId, agentCode, tokensUsed);
+ * } catch (e) {
+ *   if (e instanceof TokenBudgetExhaustedError) {
+ *     await taskService.updateStatus(taskId, 'token_exhausted');
+ *   }
+ * }
+ * ```
+ */
+export class TokenBudgetGuard {
+    budgetService;
+    constructor(budgetService) {
+        this.budgetService = budgetService;
+    }
+    /**
+     * 消耗并检查三级配额
+     *
+     * 执行顺序：
+     * 1. 对 task / session / agent 三个 scope 依次调用 consume 累加消耗
+     * 2. 按优先级 task → session → agent 检查是否耗尽
+     * 3. 任一级耗尽即抛出 TokenBudgetExhaustedError
+     *
+     * @param taskId - 当前 Task ID
+     * @param sessionId - 当前 Session ID
+     * @param agentCode - 当前 Agent ID
+     * @param amount - 本次调用消耗的 Token 数量
+     * @throws {TokenBudgetExhaustedError} 当任一级配额耗尽时
+     */
+    async checkAndConsume(taskId, sessionId, agentCode, amount) {
+        // 1. 对三个 scope 累加消耗
+        await this.budgetService.consume('task', taskId, amount);
+        await this.budgetService.consume('session', sessionId, amount);
+        await this.budgetService.consume('agent', agentCode, amount);
+        // 2. 按优先级检查：per-Task → per-Session → per-Agent
+        const scopes = [
+            { scope: 'task', scopeId: taskId },
+            { scope: 'session', scopeId: sessionId },
+            { scope: 'agent', scopeId: agentCode },
+        ];
+        for (const { scope, scopeId } of scopes) {
+            const result = await this.budgetService.check(scope, scopeId);
+            if (result.isExhausted) {
+                throw new TokenBudgetExhaustedError(scope, scopeId, result.consumed, result.quota);
+            }
+        }
+    }
+}

package/dist/token/token-budget.service.d.ts

@@ -0,0 +1,86 @@
+/**
+ * TokenBudgetService — Token 配额控制服务实现
+ *
+ * 实现三级配额体系：
+ * - per-Task: 单次 Task 执行的 Token 上限 (per-execution)
+ * - per-Session: 会话级日预算 (daily)
+ * - per-Agent: 单次 Agent 执行 cap (per-execution)
+ *
+ * @see design.md §1.3 token_budgets 数据模型
+ * @see requirements.md Requirement 12 AC1-AC3
+ */
+import type { ITokenBudgetService, BudgetScope, BudgetPeriod, BudgetCheckResult } from './contracts/index.js';
+/**
+ * BudgetRecord — token_budgets 表对应的领域模型
+ */
+export interface BudgetRecord {
+    id: string;
+    scope: BudgetScope;
+    scopeId: string;
+    quota: number;
+    consumed: number;
+    period: BudgetPeriod;
+    status: 'active' | 'exhausted';
+    createdBy: string;
+    createdAt: string;
+    updatedBy: string;
+    updatedAt: string;
+    isDeleted: boolean;
+    deletedBy?: string | null;
+    deletedAt?: string | null;
+}
+/**
+ * ITokenBudgetRepository — 配额记录持久化抽象
+ *
+ * 由 InMemoryTokenBudgetRepository（默认）或 MySQL 实现注入。
+ */
+export interface ITokenBudgetRepository {
+    /**
+     * 获取或创建指定 scope + scopeId 的配额记录
+     */
+    getOrCreate(scope: BudgetScope, scopeId: string, defaultQuota: number, period: BudgetPeriod): Promise<BudgetRecord>;
+    /**
+     * 更新配额记录（consumed / status 等字段）
+     */
+    update(record: BudgetRecord): Promise<void>;
+}
+/**
+ * InMemoryTokenBudgetRepository — 基于 Map 的内存持久化
+ *
+ * 适用于单进程/测试场景。生产环境应替换为 MySQL 实现。
+ */
+export declare class InMemoryTokenBudgetRepository implements ITokenBudgetRepository {
+    private store;
+    private buildKey;
+    getOrCreate(scope: BudgetScope, scopeId: string, defaultQuota: number, period: BudgetPeriod): Promise<BudgetRecord>;
+    update(record: BudgetRecord): Promise<void>;
+}
+/**
+ * 三级配额默认值配置
+ */
+export interface TokenBudgetServiceOptions {
+    /** per-Task Token 上限（默认 100,000） */
+    taskQuota: number;
+    /** per-Session 日预算（默认 500,000） */
+    sessionDailyQuota: number;
+    /** per-Agent 单次执行 cap（默认 200,000） */
+    agentExecutionQuota: number;
+}
+/**
+ * TokenBudgetService — ITokenBudgetService 的具体实现
+ *
+ * 通过 ITokenBudgetRepository 管理配额记录，
+ * 支持三级配额：per-Task / per-Session(daily) / per-Agent(execution)。
+ */
+export declare class TokenBudgetService implements ITokenBudgetService {
+    private readonly options;
+    private readonly repository;
+    constructor(repository: ITokenBudgetRepository, options?: Partial<TokenBudgetServiceOptions>);
+    /**
+     * 根据 scope 获取对应的默认配额上限
+     */
+    private getDefaultQuota;
+    check(scope: BudgetScope, scopeId: string): Promise<BudgetCheckResult>;
+    consume(scope: BudgetScope, scopeId: string, amount: number): Promise<void>;
+    isExhausted(scope: BudgetScope, scopeId: string): Promise<boolean>;
+}

package/dist/token/token-budget.service.js

@@ -0,0 +1,130 @@
+/**
+ * TokenBudgetService — Token 配额控制服务实现
+ *
+ * 实现三级配额体系：
+ * - per-Task: 单次 Task 执行的 Token 上限 (per-execution)
+ * - per-Session: 会话级日预算 (daily)
+ * - per-Agent: 单次 Agent 执行 cap (per-execution)
+ *
+ * @see design.md §1.3 token_budgets 数据模型
+ * @see requirements.md Requirement 12 AC1-AC3
+ */
+// ─────────────────────────────────────────────
+// InMemoryTokenBudgetRepository — 默认内存实现
+// ─────────────────────────────────────────────
+/**
+ * InMemoryTokenBudgetRepository — 基于 Map 的内存持久化
+ *
+ * 适用于单进程/测试场景。生产环境应替换为 MySQL 实现。
+ */
+export class InMemoryTokenBudgetRepository {
+    store = new Map();
+    buildKey(scope, scopeId) {
+        return `${scope}:${scopeId}`;
+    }
+    async getOrCreate(scope, scopeId, defaultQuota, period) {
+        const key = this.buildKey(scope, scopeId);
+        const existing = this.store.get(key);
+        if (existing) {
+            return existing;
+        }
+        const now = new Date();
+        const record = {
+            id: `budget_${scope}_${scopeId}_${now.getTime()}`,
+            scope,
+            scopeId,
+            quota: defaultQuota,
+            consumed: 0,
+            period,
+            status: 'active',
+            createdBy: 'system',
+            createdAt: now.toISOString(),
+            updatedBy: 'system',
+            updatedAt: now.toISOString(),
+            isDeleted: false,
+        };
+        this.store.set(key, record);
+        return record;
+    }
+    async update(record) {
+        const key = this.buildKey(record.scope, record.scopeId);
+        record.updatedAt = new Date().toISOString();
+        this.store.set(key, record);
+    }
+}
+// ─────────────────────────────────────────────
+// TokenBudgetService — 服务实现
+// ─────────────────────────────────────────────
+/**
+ * 根据 scope 推导对应的 BudgetPeriod
+ */
+function scopeToPeriod(scope) {
+    switch (scope) {
+        case 'session':
+            return 'daily';
+        case 'task':
+        case 'agent':
+            return 'per-execution';
+    }
+}
+/**
+ * TokenBudgetService — ITokenBudgetService 的具体实现
+ *
+ * 通过 ITokenBudgetRepository 管理配额记录，
+ * 支持三级配额：per-Task / per-Session(daily) / per-Agent(execution)。
+ */
+export class TokenBudgetService {
+    options;
+    repository;
+    constructor(repository, options) {
+        this.repository = repository;
+        this.options = {
+            taskQuota: options?.taskQuota ?? 100_000,
+            sessionDailyQuota: options?.sessionDailyQuota ?? 500_000,
+            agentExecutionQuota: options?.agentExecutionQuota ?? 200_000,
+        };
+    }
+    /**
+     * 根据 scope 获取对应的默认配额上限
+     */
+    getDefaultQuota(scope) {
+        switch (scope) {
+            case 'task':
+                return this.options.taskQuota;
+            case 'session':
+                return this.options.sessionDailyQuota;
+            case 'agent':
+                return this.options.agentExecutionQuota;
+        }
+    }
+    async check(scope, scopeId) {
+        const defaultQuota = this.getDefaultQuota(scope);
+        const period = scopeToPeriod(scope);
+        const record = await this.repository.getOrCreate(scope, scopeId, defaultQuota, period);
+        const remaining = Math.max(0, record.quota - record.consumed);
+        const isExhausted = record.consumed >= record.quota;
+        return {
+            quota: record.quota,
+            consumed: record.consumed,
+            remaining,
+            isExhausted,
+            period: record.period,
+        };
+    }
+    async consume(scope, scopeId, amount) {
+        const defaultQuota = this.getDefaultQuota(scope);
+        const period = scopeToPeriod(scope);
+        const record = await this.repository.getOrCreate(scope, scopeId, defaultQuota, period);
+        record.consumed += amount;
+        if (record.consumed >= record.quota) {
+            record.status = 'exhausted';
+        }
+        await this.repository.update(record);
+    }
+    async isExhausted(scope, scopeId) {
+        const defaultQuota = this.getDefaultQuota(scope);
+        const period = scopeToPeriod(scope);
+        const record = await this.repository.getOrCreate(scope, scopeId, defaultQuota, period);
+        return record.consumed >= record.quota;
+    }
+}

package/dist/token/token-detail-mode.d.ts

@@ -0,0 +1,73 @@
+/**
+ * TokenDetailMode — Token 统计输出粒度控制
+ *
+ * 通过 tokenDetail 参数控制 Token 消耗的 SSE 输出行为：
+ * - none: 不输出任何 Token 统计事件
+ * - summary: 仅 Task 结束时输出 stats.token_usage 汇总
+ * - detail: 每次 LLM 调用输出 stats.node_token + 结束时汇总
+ *
+ * `eap dev` 默认 detail；线上默认 summary。
+ *
+ * @see design.md §1.6 Token统计输出控制
+ * @see requirements.md Requirement 6 AC1
+ */
+import type { ISSEEmitter } from '../sse/contracts/index.js';
+import type { NodeTokenUsage, TaskTokenSummary } from './token-stats.service.js';
+import { TokenStatsService } from './token-stats.service.js';
+/**
+ * TokenDetailMode — tokenDetail 参数类型
+ *
+ * | 值      | 行为                                         | 场景              |
+ * |---------|----------------------------------------------|-------------------|
+ * | none    | 不输出任何 Token 统计事件                     | 生产环境前端       |
+ * | summary | 仅 Task 结束时输出 stats.token_usage 汇总    | 生产环境后台/API   |
+ * | detail  | 每次 LLM 调用输出 stats.node_token + 汇总    | 本地开发调试       |
+ */
+export type TokenDetailMode = 'none' | 'summary' | 'detail';
+/**
+ * TokenStatsEmitter — 整合 TokenStatsService 与 ISSEEmitter 的输出控制器
+ *
+ * 职责：
+ * 1. 始终记录 Token 消耗到 TokenStatsService（无论模式）
+ * 2. 根据 TokenDetailMode 有条件地通过 SSE 发射统计事件
+ *
+ * 用法：
+ * ```ts
+ * const emitter = new TokenStatsEmitter(statsService, sseEmitter, 'detail');
+ * // 每次 LLM 调用后
+ * emitter.recordAndEmit(taskId, usage, correlationId);
+ * // Task 结束时
+ * emitter.emitSummary(taskId, correlationId);
+ * ```
+ */
+export declare class TokenStatsEmitter {
+    private readonly statsService;
+    private readonly sseEmitter;
+    private readonly mode;
+    constructor(statsService: TokenStatsService, sseEmitter: ISSEEmitter | null, mode: TokenDetailMode);
+    /**
+     * 记录 Token 消耗并按模式决定是否立即发射 stats.node_token 事件
+     *
+     * - 始终调用 statsService.record() 记录数据
+     * - mode='detail': 立即 emit stats.node_token SSE 事件
+     * - mode='none' / 'summary': 不 emit per-call 事件
+     *
+     * @param taskId - 所属 Task ID
+     * @param usage - 本次 LLM 调用的 Token 消耗
+     * @param correlationId - 请求关联 ID
+     */
+    recordAndEmit(taskId: string, usage: NodeTokenUsage, correlationId: string): void;
+    /**
+     * Task 结束时发射 stats.token_usage 汇总事件
+     *
+     * - mode='summary' / 'detail': emit stats.token_usage SSE 事件
+     * - mode='none': 不 emit
+     *
+     * @param taskId - 所属 Task ID
+     * @param correlationId - 请求关联 ID
+     * @returns 聚合后的 TaskTokenSummary（无论是否 emit 都返回，供业务层使用）
+     */
+    emitSummary(taskId: string, correlationId: string): TaskTokenSummary;
+    /** 获取当前输出模式 */
+    get detailMode(): TokenDetailMode;
+}

package/dist/token/token-detail-mode.js

@@ -0,0 +1,107 @@
+/**
+ * TokenDetailMode — Token 统计输出粒度控制
+ *
+ * 通过 tokenDetail 参数控制 Token 消耗的 SSE 输出行为：
+ * - none: 不输出任何 Token 统计事件
+ * - summary: 仅 Task 结束时输出 stats.token_usage 汇总
+ * - detail: 每次 LLM 调用输出 stats.node_token + 结束时汇总
+ *
+ * `eap dev` 默认 detail；线上默认 summary。
+ *
+ * @see design.md §1.6 Token统计输出控制
+ * @see requirements.md Requirement 6 AC1
+ */
+// ─────────────────────────────────────────────
+// TokenStatsEmitter
+// ─────────────────────────────────────────────
+/**
+ * TokenStatsEmitter — 整合 TokenStatsService 与 ISSEEmitter 的输出控制器
+ *
+ * 职责：
+ * 1. 始终记录 Token 消耗到 TokenStatsService（无论模式）
+ * 2. 根据 TokenDetailMode 有条件地通过 SSE 发射统计事件
+ *
+ * 用法：
+ * ```ts
+ * const emitter = new TokenStatsEmitter(statsService, sseEmitter, 'detail');
+ * // 每次 LLM 调用后
+ * emitter.recordAndEmit(taskId, usage, correlationId);
+ * // Task 结束时
+ * emitter.emitSummary(taskId, correlationId);
+ * ```
+ */
+export class TokenStatsEmitter {
+    statsService;
+    sseEmitter;
+    mode;
+    constructor(statsService, sseEmitter, mode) {
+        this.statsService = statsService;
+        this.sseEmitter = sseEmitter;
+        this.mode = mode;
+    }
+    /**
+     * 记录 Token 消耗并按模式决定是否立即发射 stats.node_token 事件
+     *
+     * - 始终调用 statsService.record() 记录数据
+     * - mode='detail': 立即 emit stats.node_token SSE 事件
+     * - mode='none' / 'summary': 不 emit per-call 事件
+     *
+     * @param taskId - 所属 Task ID
+     * @param usage - 本次 LLM 调用的 Token 消耗
+     * @param correlationId - 请求关联 ID
+     */
+    recordAndEmit(taskId, usage, correlationId) {
+        // 始终记录到统计服务
+        this.statsService.record(taskId, usage);
+        // detail 模式: 立即发射 per-call 事件
+        if (this.mode === 'detail' && this.sseEmitter) {
+            const event = {
+                type: 'stats.node_token',
+                data: {
+                    nodeId: usage.nodeId,
+                    model: usage.model,
+                    inputTokens: usage.inputTokens,
+                    outputTokens: usage.outputTokens,
+                    costEstimate: usage.costEstimate,
+                },
+                correlationId,
+                taskId,
+                timestamp: new Date().toISOString(),
+            };
+            this.sseEmitter.emit(event);
+        }
+    }
+    /**
+     * Task 结束时发射 stats.token_usage 汇总事件
+     *
+     * - mode='summary' / 'detail': emit stats.token_usage SSE 事件
+     * - mode='none': 不 emit
+     *
+     * @param taskId - 所属 Task ID
+     * @param correlationId - 请求关联 ID
+     * @returns 聚合后的 TaskTokenSummary（无论是否 emit 都返回，供业务层使用）
+     */
+    emitSummary(taskId, correlationId) {
+        const summary = this.statsService.getTaskStats(taskId);
+        if ((this.mode === 'summary' || this.mode === 'detail') && this.sseEmitter) {
+            const event = {
+                type: 'stats.token_usage',
+                data: {
+                    total: summary.total,
+                    byNode: summary.byNode,
+                    byModel: summary.byModel,
+                    costEstimate: summary.costEstimate,
+                },
+                correlationId,
+                taskId,
+                timestamp: new Date().toISOString(),
+            };
+            this.sseEmitter.emit(event);
+        }
+        return summary;
+    }
+    /** 获取当前输出模式 */
+    get detailMode() {
+        return this.mode;
+    }
+}

package/dist/token/token-estimator.d.ts

@@ -0,0 +1,80 @@
+/**
+ * TiktokenEstimator — 基于 tiktoken 的 Token 估算器
+ *
+ * 提供更精确的 Token 计数，支持多种模型的 tokenizer。
+ * 当 tiktoken 不可用时，回退到基于字符的估算。
+ *
+ * @see message-compression.service.ts Token 估算
+ */
+/**
+ * Token 估算器接口
+ */
+export interface ITokenEstimator {
+    /**
+     * 估算文本的 Token 数
+     *
+     * @param text - 文本内容
+     * @returns Token 数
+     */
+    estimateTokens(text: string): number;
+    /**
+     * 估算消息列表的 Token 数
+     *
+     * @param messages - 消息列表
+     * @returns Token 数
+     */
+    estimateMessagesTokens(messages: Array<{
+        role: string;
+        content: string;
+        toolCalls?: unknown;
+    }>): number;
+}
+/**
+ * 基于字符的 Token 估算器
+ *
+ * 粗略但快速，适用于：
+ * - tiktoken 不可用时的回退方案
+ * - 对精度要求不高的场景
+ */
+export declare class CharBasedTokenEstimator implements ITokenEstimator {
+    /**
+     * 估算文本的 Token 数
+     *
+     * 基于字符数估算：
+     * - 中文约 1.5 字符 = 1 Token
+     * - 英文约 4 字符 = 1 Token
+     */
+    estimateTokens(text: string): number;
+    estimateMessagesTokens(messages: Array<{
+        role: string;
+        content: string;
+        toolCalls?: unknown;
+    }>): number;
+}
+/**
+ * 模型特定的 Token 估算器
+ *
+ * 基于不同模型的 tokenizer 特性进行更精确的估算。
+ */
+export declare class ModelBasedTokenEstimator implements ITokenEstimator {
+    private readonly model;
+    private readonly charsPerToken;
+    constructor(model?: string);
+    estimateTokens(text: string): number;
+    estimateMessagesTokens(messages: Array<{
+        role: string;
+        content: string;
+        toolCalls?: unknown;
+    }>): number;
+    /**
+     * 获取模型的字符/Token 比率
+     */
+    private getCharsPerToken;
+}
+/**
+ * 创建 Token 估算器
+ *
+ * @param model - 模型名称（可选）
+ * @returns Token 估算器实例
+ */
+export declare function createTokenEstimator(model?: string): ITokenEstimator;