@gt-fe/eap-runtime 0.0.8

package/dist/task/task.service.js

@@ -0,0 +1,233 @@
+/**
+ * TaskService — ITaskManager 实现
+ *
+ * 管理 Task 生命周期：创建、状态流转、查询、Token消耗记录、进度跟踪。
+ * v1 使用 in-memory Map 存储，后续由 TaskRepository 替换。
+ *
+ * @see task-manager.contract.ts
+ * @see requirements.md Requirement 7 AC1-AC5
+ */
+import { randomUUID } from 'node:crypto';
+import { TaskProgressTracker } from './task-progress-tracker.js';
+// ─────────────────────────────────────────────
+// State Transition Validation
+// ─────────────────────────────────────────────
+/**
+ * 合法状态流转映射
+ *
+ * pending → running
+ * running → success | failed | timeout | token_exhausted
+ */
+const VALID_TRANSITIONS = {
+    pending: ['running'],
+    running: ['success', 'failed', 'timeout', 'token_exhausted', 'waiting_hitl'],
+    waiting_hitl: ['running', 'timeout', 'failed'],
+    success: [],
+    failed: [],
+    timeout: [],
+    token_exhausted: [],
+};
+// ─────────────────────────────────────────────
+// In-Memory Repository (Default)
+// ─────────────────────────────────────────────
+/**
+ * InMemoryTaskRepository — 内存存储实现
+ *
+ * 用于开发/测试阶段，后续替换为 MySQL 实现。
+ */
+export class InMemoryTaskRepository {
+    store = new Map();
+    async save(task) {
+        this.store.set(task.id, { ...task });
+    }
+    async findById(id) {
+        const record = this.store.get(id);
+        return record ? { ...record } : null;
+    }
+    async update(task) {
+        this.store.set(task.id, { ...task });
+    }
+}
+// ─────────────────────────────────────────────
+// TaskService Implementation
+// ─────────────────────────────────────────────
+export class TaskService {
+    repository;
+    progressTracker;
+    constructor(repository, progressTracker) {
+        this.repository = repository ?? new InMemoryTaskRepository();
+        this.progressTracker = progressTracker ?? new TaskProgressTracker();
+    }
+    /**
+     * 获取内部 progressTracker 实例（供 Graph 引擎更新节点进度）
+     */
+    getProgressTracker() {
+        return this.progressTracker;
+    }
+    /**
+     * 创建新 Task，初始状态为 pending
+     */
+    async create(params) {
+        const now = new Date().toISOString();
+        const id = params.id?.trim() || randomUUID();
+        // 上游复用 id 时禁止静默覆盖已有 Task
+        if (params.id?.trim()) {
+            const existing = await this.repository.findById(id);
+            if (existing && !existing.isDeleted) {
+                throw new Error(`Task already exists: ${id}`);
+            }
+        }
+        const task = {
+            id,
+            agentId: params.agentId,
+            sessionId: params.sessionId,
+            userId: params.userId,
+            correlationId: params.correlationId,
+            input: params.input,
+            output: null,
+            status: 'pending',
+            traceId: null,
+            tokenUsage: [],
+            cost: 0,
+            startedAt: null,
+            completedAt: null,
+            createdBy: params.userId,
+            createdAt: now,
+            updatedBy: params.userId,
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.repository.save(task);
+        return task;
+    }
+    /**
+     * 获取完整 Task 记录（供 AgentRuntime.resumeHitl / fork 使用）
+     */
+    async getTask(taskId) {
+        return this.repository.findById(taskId);
+    }
+    /**
+     * 更新 Task 状态
+     *
+     * 验证状态流转合法性，设置时间戳：
+     * - pending→running: 设置 startedAt
+     * - running→终态: 设置 completedAt 和 output
+     */
+    async updateStatus(taskId, status, output) {
+        const task = await this.findTaskOrThrow(taskId);
+        if (!this.isValidTransition(task.status, status)) {
+            throw new Error(`Invalid state transition: cannot transition from '${task.status}' to '${status}' for task '${taskId}'`);
+        }
+        const now = new Date().toISOString();
+        task.status = status;
+        if (status === 'running') {
+            task.startedAt = now;
+        }
+        // waiting_hitl：写入 output（含 hitlThreadId）供冷恢复；非终态、不设 completedAt
+        if (status === 'waiting_hitl' && output !== undefined) {
+            task.output = output;
+        }
+        if (status === 'success' || status === 'failed' || status === 'timeout' || status === 'token_exhausted') {
+            task.completedAt = now;
+            if (output !== undefined) {
+                task.output = output;
+            }
+            // 终态时清理进度跟踪
+            this.progressTracker.removeProgress(taskId);
+        }
+        await this.repository.update(task);
+    }
+    /**
+     * 仅当当前状态为 `from` 时流转。并发下 timeout/resume 抢占时返回 false，不抛错。
+     */
+    async tryUpdateStatus(taskId, from, to, output) {
+        const task = await this.repository.findById(taskId);
+        if (!task || task.isDeleted || task.status !== from) {
+            return false;
+        }
+        if (!this.isValidTransition(from, to)) {
+            return false;
+        }
+        await this.updateStatus(taskId, to, output);
+        return true;
+    }
+    /**
+     * 获取 Task 当前状态信息（供轮询使用）
+     *
+     * 优先返回 progressTracker 中的显式进度，回退到基于状态的粗粒度计算。
+     */
+    async getStatus(taskId) {
+        const task = await this.findTaskOrThrow(taskId);
+        const trackedProgress = this.progressTracker.getProgress(taskId);
+        const progress = trackedProgress !== null
+            ? trackedProgress.progress
+            : this.calculateProgress(task.status);
+        const duration = this.calculateDuration(task);
+        return {
+            status: task.status,
+            progress,
+            startedAt: task.startedAt,
+            duration,
+        };
+    }
+    /**
+     * 记录一次 Token 消耗，累加到 Task 的 tokenUsage 和 cost
+     */
+    async recordTokenUsage(taskId, usage) {
+        const task = await this.findTaskOrThrow(taskId);
+        task.tokenUsage.push(usage);
+        task.cost += usage.costEstimate;
+        await this.repository.update(task);
+    }
+    /**
+     * 更新 Task 执行进度（用于长任务轮询）
+     *
+     * 进度值会被 clamp 到 0-100 范围。仅 running 状态的 Task 可更新进度。
+     */
+    async updateProgress(taskId, progress) {
+        const task = await this.findTaskOrThrow(taskId);
+        if (task.status !== 'running') {
+            throw new Error(`Cannot update progress for task '${taskId}' in '${task.status}' status (must be 'running')`);
+        }
+        this.progressTracker.updateProgress(taskId, progress);
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    async findTaskOrThrow(taskId) {
+        const task = await this.repository.findById(taskId);
+        if (!task) {
+            throw new Error(`Task not found: '${taskId}'`);
+        }
+        return task;
+    }
+    isValidTransition(from, to) {
+        return VALID_TRANSITIONS[from]?.includes(to) ?? false;
+    }
+    calculateProgress(status) {
+        switch (status) {
+            case 'pending':
+                return 0;
+            case 'running':
+                return 50;
+            case 'success':
+            case 'failed':
+            case 'timeout':
+            case 'token_exhausted':
+                return 100;
+            default:
+                return 0;
+        }
+    }
+    calculateDuration(task) {
+        if (!task.startedAt) {
+            return 0;
+        }
+        const start = new Date(task.startedAt).getTime();
+        if (task.completedAt) {
+            return new Date(task.completedAt).getTime() - start;
+        }
+        // 仍在运行中，返回到当前的时长
+        return Date.now() - start;
+    }
+}

package/dist/token/compression-budget-integration.d.ts

@@ -0,0 +1,145 @@
+/**
+ * CompressionBudgetIntegration — 压缩与预算集成
+ *
+ * 将 CompressionMiddleware 与 ContextWindowBudget 集成，
+ * 实现基于 Token 预算的自动压缩触发。
+ *
+ * @see context-window-budget.ts 上下文窗口预算
+ * @see compression-middleware.ts 压缩中间件
+ */
+import type { MessageRecord } from '../session/session.service.js';
+import type { ILLMProvider } from '../graph/nodes/llm-node.js';
+import type { ContextSource } from './context-window-budget.js';
+import type { ICompressionRepository } from '../memory/compression/compression.repository.js';
+import type { IMessageRepository } from '../session/session.service.js';
+/**
+ * 集成配置
+ */
+export interface CompressionBudgetConfig {
+    /** 模型 context window 大小 */
+    modelContextWindow: number;
+    /** 历史消息占比阈值（超过此比例触发压缩，默认 0.8） */
+    historyThreshold?: number;
+    /** 压缩后目标占比（默认 0.5） */
+    targetRatio?: number;
+    /** 是否启用自动压缩（默认 true） */
+    autoCompress?: boolean;
+    /** LLM 配置 */
+    llmConfig?: {
+        provider?: ILLMProvider;
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+    };
+}
+/**
+ * 预算检查结果
+ */
+export interface BudgetCheckResult {
+    /** 是否需要压缩 */
+    needsCompression: boolean;
+    /** 当前历史消息 Token 数 */
+    currentTokens: number;
+    /** 历史消息 Token 上限 */
+    maxTokens: number;
+    /** 使用率 */
+    usageRatio: number;
+    /** 压缩后目标 Token 数 */
+    targetTokens?: number;
+}
+/**
+ * 压缩执行结果
+ */
+export interface CompressionExecutionResult {
+    /** 是否执行了压缩 */
+    compressed: boolean;
+    /** 原始消息数 */
+    originalCount: number;
+    /** 压缩后消息数 */
+    compressedCount?: number;
+    /** 原始 Token 数 */
+    originalTokens: number;
+    /** 压缩后 Token 数 */
+    compressedTokens?: number;
+    /** 压缩率 */
+    compressionRatio?: number;
+    /** 压缩耗时（毫秒） */
+    durationMs?: number;
+}
+/**
+ * CompressionBudgetIntegration — 压缩与预算集成服务
+ *
+ * 功能：
+ * 1. 监控历史消息的 Token 使用情况
+ * 2. 当历史消息超出预算阈值时自动触发压缩
+ * 3. 压缩后确保历史消息在预算范围内
+ */
+export declare class CompressionBudgetIntegration {
+    private readonly budget;
+    private readonly compression;
+    private readonly config;
+    constructor(config: CompressionBudgetConfig, repository?: ICompressionRepository, messageRepository?: IMessageRepository);
+    /**
+     * 检查历史消息是否需要压缩
+     *
+     * @param messages - 历史消息列表
+     * @returns 预算检查结果
+     */
+    checkBudget(messages: MessageRecord[]): BudgetCheckResult;
+    /**
+     * 处理历史消息（自动压缩）
+     *
+     * @param messages - 原始历史消息
+     * @param context - 上下文信息
+     * @returns 处理后的消息列表
+     */
+    processHistory(messages: MessageRecord[], context: {
+        sessionId: string;
+        taskId?: string;
+        userId: string;
+    }): Promise<{
+        messages: MessageRecord[];
+        result: CompressionExecutionResult;
+    }>;
+    /**
+     * 获取预算分配情况
+     *
+     * @param usage - 各来源的已使用 Token 数
+     * @returns 预算分配结果
+     */
+    getBudgetAllocation(usage?: Partial<Record<ContextSource, number>>): import("./context-window-budget.js").BudgetAllocation;
+    /**
+     * 获取配置
+     */
+    getConfig(): {
+        modelContextWindow: number;
+        historyThreshold: number;
+        targetRatio: number;
+        autoCompress: boolean;
+        llmConfig?: CompressionBudgetConfig["llmConfig"];
+    };
+    /**
+     * MessageRecord 转 GraphMessage
+     */
+    private toGraphMessages;
+}
+/**
+ * 创建压缩预算集成服务
+ *
+ * @param config - 配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选）
+ * @returns CompressionBudgetIntegration 实例
+ */
+export declare function createCompressionBudgetIntegration(config: CompressionBudgetConfig, repository?: ICompressionRepository, messageRepository?: IMessageRepository): CompressionBudgetIntegration;
+/**
+ * 创建带 LLM 能力的压缩预算集成服务
+ *
+ * @param provider - ILLMProvider 实例
+ * @param modelContextWindow - 模型 context window 大小
+ * @param config - 可选配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选）
+ * @returns CompressionBudgetIntegration 实例
+ */
+export declare function createCompressionBudgetIntegrationWithLLM(provider: ILLMProvider, modelContextWindow: number, config?: Partial<CompressionBudgetConfig>, repository?: ICompressionRepository, messageRepository?: IMessageRepository): CompressionBudgetIntegration;

package/dist/token/compression-budget-integration.js

@@ -0,0 +1,185 @@
+/**
+ * CompressionBudgetIntegration — 压缩与预算集成
+ *
+ * 将 CompressionMiddleware 与 ContextWindowBudget 集成，
+ * 实现基于 Token 预算的自动压缩触发。
+ *
+ * @see context-window-budget.ts 上下文窗口预算
+ * @see compression-middleware.ts 压缩中间件
+ */
+import { createContextBudget } from './context-window-budget.js';
+import { CompressionMiddleware, createCompressionMiddlewareWithLLM, } from '../session/compression-middleware.js';
+import { estimateMessagesTokens } from '../memory/message-compression.service.js';
+// ─────────────────────────────────────────────
+// CompressionBudgetIntegration
+// ─────────────────────────────────────────────
+/**
+ * CompressionBudgetIntegration — 压缩与预算集成服务
+ *
+ * 功能：
+ * 1. 监控历史消息的 Token 使用情况
+ * 2. 当历史消息超出预算阈值时自动触发压缩
+ * 3. 压缩后确保历史消息在预算范围内
+ */
+export class CompressionBudgetIntegration {
+    budget;
+    compression;
+    config;
+    constructor(config, repository, messageRepository) {
+        this.config = {
+            modelContextWindow: config.modelContextWindow,
+            historyThreshold: config.historyThreshold ?? 0.8,
+            targetRatio: config.targetRatio ?? 0.5,
+            autoCompress: config.autoCompress ?? true,
+            llmConfig: config.llmConfig,
+        };
+        // 创建预算管理器
+        this.budget = createContextBudget(this.config.modelContextWindow);
+        // 创建压缩中间件
+        if (this.config.llmConfig?.provider) {
+            this.compression = createCompressionMiddlewareWithLLM(this.config.llmConfig.provider, {
+                llmConfig: this.config.llmConfig,
+            }, repository, messageRepository);
+        }
+        else {
+            this.compression = new CompressionMiddleware({}, undefined, repository, messageRepository);
+        }
+    }
+    /**
+     * 检查历史消息是否需要压缩
+     *
+     * @param messages - 历史消息列表
+     * @returns 预算检查结果
+     */
+    checkBudget(messages) {
+        // 估算当前 Token 数
+        const graphMessages = this.toGraphMessages(messages);
+        const currentTokens = estimateMessagesTokens(graphMessages);
+        // 获取历史消息的 Token 上限
+        const maxTokens = this.budget.getMaxTokens('history');
+        // 计算使用率
+        const usageRatio = maxTokens > 0 ? currentTokens / maxTokens : 0;
+        // 检查是否超过阈值
+        const needsCompression = usageRatio > this.config.historyThreshold;
+        // 计算压缩目标
+        const targetTokens = needsCompression
+            ? Math.floor(maxTokens * this.config.targetRatio)
+            : undefined;
+        return {
+            needsCompression,
+            currentTokens,
+            maxTokens,
+            usageRatio,
+            targetTokens,
+        };
+    }
+    /**
+     * 处理历史消息（自动压缩）
+     *
+     * @param messages - 原始历史消息
+     * @param context - 上下文信息
+     * @returns 处理后的消息列表
+     */
+    async processHistory(messages, context) {
+        // 检查预算
+        const budgetCheck = this.checkBudget(messages);
+        // 如果不需要压缩或未启用自动压缩，直接返回
+        if (!budgetCheck.needsCompression || !this.config.autoCompress) {
+            return {
+                messages,
+                result: {
+                    compressed: false,
+                    originalCount: messages.length,
+                    originalTokens: budgetCheck.currentTokens,
+                },
+            };
+        }
+        // 执行压缩
+        const startTime = Date.now();
+        const compressedMessages = await this.compression.processMessages(messages, context);
+        const duration = Date.now() - startTime;
+        // 计算压缩后的 Token 数
+        const compressedGraphMessages = this.toGraphMessages(compressedMessages);
+        const compressedTokens = estimateMessagesTokens(compressedGraphMessages);
+        // 计算压缩率
+        const compressionRatio = budgetCheck.currentTokens > 0
+            ? compressedTokens / budgetCheck.currentTokens
+            : 1;
+        return {
+            messages: compressedMessages,
+            result: {
+                compressed: true,
+                originalCount: messages.length,
+                compressedCount: compressedMessages.length,
+                originalTokens: budgetCheck.currentTokens,
+                compressedTokens,
+                compressionRatio,
+                durationMs: duration,
+            },
+        };
+    }
+    /**
+     * 获取预算分配情况
+     *
+     * @param usage - 各来源的已使用 Token 数
+     * @returns 预算分配结果
+     */
+    getBudgetAllocation(usage) {
+        return this.budget.calculateAllocation(usage ?? {});
+    }
+    /**
+     * 获取配置
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    // ─────────────────────────────────────────────
+    // Private
+    // ─────────────────────────────────────────────
+    /**
+     * MessageRecord 转 GraphMessage
+     */
+    toGraphMessages(messages) {
+        return messages.map((m) => ({
+            role: m.role,
+            content: m.content,
+            toolCalls: m.toolCalls,
+        }));
+    }
+}
+// ─────────────────────────────────────────────
+// 工厂函数
+// ─────────────────────────────────────────────
+/**
+ * 创建压缩预算集成服务
+ *
+ * @param config - 配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选）
+ * @returns CompressionBudgetIntegration 实例
+ */
+export function createCompressionBudgetIntegration(config, repository, messageRepository) {
+    return new CompressionBudgetIntegration(config, repository, messageRepository);
+}
+/**
+ * 创建带 LLM 能力的压缩预算集成服务
+ *
+ * @param provider - ILLMProvider 实例
+ * @param modelContextWindow - 模型 context window 大小
+ * @param config - 可选配置
+ * @param repository - 压缩记录存储（可选）
+ * @param messageRepository - 消息存储（可选）
+ * @returns CompressionBudgetIntegration 实例
+ */
+export function createCompressionBudgetIntegrationWithLLM(provider, modelContextWindow, config, repository, messageRepository) {
+    return new CompressionBudgetIntegration({
+        ...config,
+        modelContextWindow,
+        llmConfig: {
+            provider,
+            model: config?.llmConfig?.model ?? 'DeepSeek-V4-Pro',
+            temperature: config?.llmConfig?.temperature ?? 0.3,
+            maxTokens: config?.llmConfig?.maxTokens ?? 1024,
+        },
+    }, repository, messageRepository);
+}

package/dist/token/context-window-budget.d.ts

@@ -0,0 +1,113 @@
+/**
+ * ContextWindowBudget — 上下文窗口预算分配
+ *
+ * 管理上下文窗口的 Token 分配，防止单一来源占满上下文。
+ * 支持配置历史消息、RAG 结果、Tool Schema 各占上下文窗口的比例上限。
+ *
+ * @see requirements.md Requirement 12.5
+ * @see token/token-budget.service.ts Token Budget 控制
+ */
+/**
+ * 上下文来源类型
+ */
+export type ContextSource = 'history' | 'rag' | 'tools' | 'system' | 'memory';
+/**
+ * 上下文窗口预算配置
+ */
+export interface ContextWindowBudgetConfig {
+    /** 模型 context window 总 Token 数 */
+    totalTokens: number;
+    /** 各来源的 Token 比例上限 */
+    sourceRatios: Record<ContextSource, number>;
+    /** 预留给模型输出的 Token 数（默认 20%） */
+    outputReserve: number;
+}
+/**
+ * 默认上下文窗口预算配置
+ */
+export declare const DEFAULT_CONTEXT_BUDGET_CONFIG: ContextWindowBudgetConfig;
+/**
+ * 来源 Token 分配
+ */
+export interface SourceAllocation {
+    /** 来源类型 */
+    source: ContextSource;
+    /** 分配的 Token 上限 */
+    maxTokens: number;
+    /** 已使用的 Token 数 */
+    usedTokens: number;
+    /** 剩余可用 Token 数 */
+    remainingTokens: number;
+    /** 使用率（0-1） */
+    usageRatio: number;
+}
+/**
+ * 预算分配结果
+ */
+export interface BudgetAllocation {
+    /** 总 Token 数 */
+    totalTokens: number;
+    /** 可用 Token 数（扣除输出预留） */
+    availableTokens: number;
+    /** 各来源的分配情况 */
+    sources: SourceAllocation[];
+    /** 是否超限 */
+    isExceeded: boolean;
+    /** 超限的来源列表 */
+    exceededSources: ContextSource[];
+}
+/**
+ * ContextWindowBudget — 上下文窗口预算管理
+ */
+export declare class ContextWindowBudget {
+    private readonly config;
+    constructor(config?: Partial<ContextWindowBudgetConfig>);
+    /**
+     * 获取指定来源的 Token 上限
+     *
+     * @param source - 来源类型
+     * @returns Token 上限
+     */
+    getMaxTokens(source: ContextSource): number;
+    /**
+     * 检查指定来源是否超限
+     *
+     * @param source - 来源类型
+     * @param usedTokens - 已使用的 Token 数
+     * @returns 是否超限
+     */
+    isExceeded(source: ContextSource, usedTokens: number): boolean;
+    /**
+     * 计算预算分配
+     *
+     * @param usage - 各来源的已使用 Token 数
+     * @returns 预算分配结果
+     */
+    calculateAllocation(usage: Partial<Record<ContextSource, number>>): BudgetAllocation;
+    /**
+     * 裁剪消息以符合预算
+     *
+     * 如果历史消息超出预算，从前面开始删除旧消息。
+     *
+     * @param messages - 原始消息列表
+     * @param maxTokens - Token 上限
+     * @param estimateFn - Token 估算函数
+     * @returns 裁剪后的消息列表
+     */
+    trimMessages<T extends {
+        role: string;
+        content: string;
+    }>(messages: T[], maxTokens: number, estimateFn: (messages: T[]) => number): T[];
+    /**
+     * 获取配置
+     */
+    getConfig(): ContextWindowBudgetConfig;
+}
+/**
+ * 创建上下文窗口预算实例
+ *
+ * @param modelContextWindow - 模型的 context window 大小
+ * @param config - 可选的自定义配置
+ * @returns ContextWindowBudget 实例
+ */
+export declare function createContextBudget(modelContextWindow: number, config?: Partial<ContextWindowBudgetConfig>): ContextWindowBudget;