@gt-fe/eap-runtime 0.0.8

package/dist/api/handlers/stream.handler.js

@@ -0,0 +1,432 @@
+/**
+ * StreamOrchestrator — 流式调用编排器
+ *
+ * 实现 POST /api/v1/agents/:agentCode/stream 的核心编排逻辑：
+ * 1. 检查 Session 日预算（SessionBudgetChecker）
+ * 2. 解析/创建 Session 上下文（SessionContextService），sessionId 缺失时自动创建
+ * 3. 创建 Task（TaskService）
+ * 4. 启动 Task（pending → running）
+ * 5. 通过 SSEEmitter 推送事件流
+ * 6. 构建/流式执行 Graph（IStateGraphEngine.stream()）
+ * 7. 将 RuntimeEvent 转为 SSE 事件推送
+ * 8. 记录 Token 消耗 + 完成 Task + 关闭 SSE 连接
+ *
+ * 与 InvokeOrchestrator 区别：
+ * - 使用 Graph.stream() 而非 invoke()
+ * - 通过 SSEEmitter 实时推送事件，而非等待完整结果
+ * - 在流式过程中逐步 emit 各类事件（session.created, task.started, response.chunk 等）
+ *
+ * @see design.md §1.5 /stream 内部执行逻辑
+ * @see requirements.md Requirement 11 AC2
+ */
+import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractStreamReasoning, extractStreamTextDelta, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../../session/persist-turn-messages.js';
+import { SessionBudgetExhaustedError } from '../../token/session-budget-checker.js';
+import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
+import { SSEEmitter } from '../../sse/sse-emitter.js';
+import { resolveExecutionContext } from '../../governance/governance-client.js';
+import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
+import { ErrorCodes } from '@gt-fe/eap-contracts';
+import { classifyRuntimeError } from '../../utils/http-error.js';
+import { toLoadedToolMap } from '../../tool/loaded-tool-definition.js';
+import { toLoadedSkillMap, mergeSkillScriptTools } from '../../tool/system-prompt-builder.js';
+import { resolveAgentCode } from '../../common/agent-code.js';
+import { unwrapHitlPaused } from './invoke.handler.js';
+import { buildHitlWaitedPayload } from '../../graph/hitl/hitl-handler.js';
+import { resolveTraceId } from '../../common/trace-id.js';
+// ─────────────────────────────────────────────
+// Placeholder Graph DSL (Agent Registry 接入前)
+// ─────────────────────────────────────────────
+const DEFAULT_GRAPH_DSL = {
+    name: 'default-graph',
+    version: '1.0.0',
+    state: { messages: 'array' },
+    nodes: [
+        { id: 'llm', type: 'llm', config: {} },
+    ],
+    edges: [
+        { from: '__start__', to: 'llm' },
+        { from: 'llm', to: '__end__' },
+    ],
+    config: { timeout: 60000 },
+};
+// ─────────────────────────────────────────────
+// StreamOrchestrator
+// ─────────────────────────────────────────────
+/**
+ * StreamOrchestrator — 流式调用全流程编排
+ *
+ * 协调 SessionContextService、TaskService、IStateGraphEngine、SSEEmitter、TokenStatsService
+ * 等服务完成一次 SSE 流式 Agent 调用的完整生命周期。
+ */
+export class StreamOrchestrator {
+    sessionContextService;
+    taskService;
+    graphEngine;
+    tokenStatsService;
+    tokenBudgetGuard;
+    sessionBudgetChecker;
+    messageService;
+    graphLoader;
+    checkpointSaver;
+    traceCollector;
+    constructor(deps) {
+        this.sessionContextService = deps.sessionContextService;
+        this.taskService = deps.taskService;
+        this.graphEngine = deps.graphEngine;
+        this.tokenStatsService = deps.tokenStatsService;
+        this.tokenBudgetGuard = deps.tokenBudgetGuard;
+        this.sessionBudgetChecker = deps.sessionBudgetChecker;
+        this.messageService = deps.messageService;
+        this.graphLoader = deps.graphLoader;
+        this.checkpointSaver = deps.checkpointSaver;
+        this.traceCollector = deps.traceCollector;
+    }
+    /**
+     * 执行流式调用编排
+     *
+     * @param req - 解析后的调用请求（与 InvokeRequest 相同）
+     * @param res - Node.js HTTP ServerResponse，用于写入 SSE 事件
+     * @param userId - 经认证的用户 ID
+     */
+    async execute(req, res, userId) {
+        const startTime = Date.now();
+        const agentCode = resolveAgentCode(req);
+        const ctx = resolveExecutionContext({ ...req, agentCode }, userId);
+        const correlationId = ctx.correlationId;
+        const effectiveUserId = ctx.userId ?? userId;
+        // 创建 SSEEmitter 绑定到 ServerResponse
+        const emitter = new SSEEmitter(res, {
+            heartbeatInterval: 30000,
+            correlationId,
+        });
+        // 启动自动心跳
+        emitter.startHeartbeat();
+        try {
+            await this.executeInternal(req, emitter, effectiveUserId, correlationId, startTime, ctx);
+        }
+        catch (error) {
+            // 确保异常情况下也能正确关闭 SSE 连接
+            this.emitErrorAndClose(emitter, correlationId, '', error);
+        }
+    }
+    // ─────────────────────────────────────────────
+    // Private: 内部编排逻辑
+    // ─────────────────────────────────────────────
+    async executeInternal(req, emitter, userId, correlationId, startTime, executionContext) {
+        const agentCode = resolveAgentCode(req);
+        // ─── Step 1: 检查 Session 日预算 ───
+        if (req.sessionId) {
+            try {
+                await this.sessionBudgetChecker.assertBudgetAvailable(req.sessionId);
+            }
+            catch (error) {
+                if (error instanceof SessionBudgetExhaustedError) {
+                    this.emitErrorAndClose(emitter, correlationId, '', error);
+                    return;
+                }
+                throw error;
+            }
+        }
+        // ─── Step 2: 解析/创建 Session 上下文（auto-create when absent） ───
+        const sessionContext = await this.sessionContextService.resolveSessionContext({
+            sessionId: req.sessionId,
+            userId,
+            agentId: agentCode,
+            agentVersion: req.agentVersion,
+        });
+        const sessionId = sessionContext.session.id;
+        // 新创建的 Session 也检查预算
+        if (!req.sessionId) {
+            try {
+                await this.sessionBudgetChecker.assertBudgetAvailable(sessionId);
+            }
+            catch (error) {
+                if (error instanceof SessionBudgetExhaustedError) {
+                    this.emitErrorAndClose(emitter, correlationId, '', error);
+                    return;
+                }
+                throw error;
+            }
+        }
+        // 更新 emitter 的 taskId 上下文（此时还没 taskId，后续再更新）
+        // ─── Emit: session.created（仅新 Session 时推送） ───
+        if (sessionContext.isNew) {
+            emitter.emit(this.buildSSEEvent('session.created', correlationId, '', {
+                sessionId,
+                userId,
+            }));
+        }
+        // ─── Step 3: 创建 Task（Hosting 传入 taskId 时复用）───
+        const timeout = req.config?.timeout ?? 60000;
+        const task = await this.taskService.create({
+            id: req.taskId,
+            agentId: agentCode,
+            sessionId,
+            userId,
+            correlationId,
+            input: req.input,
+            timeout,
+        });
+        const taskId = task.id;
+        // ─── Step 4: 启动 Task (pending → running) ───
+        await this.taskService.updateStatus(taskId, 'running');
+        // ─── Step 4b: 持久化本轮 user（多轮短期记忆）───
+        await persistUserTurnMessage(this.messageService, {
+            sessionId,
+            taskId,
+            correlationId,
+            content: req.input,
+        });
+        // ─── Emit: task.started ───
+        emitter.emit(this.buildSSEEvent('task.started', correlationId, taskId, {
+            taskId,
+            sessionId,
+        }));
+        // ─── Step 5: 构建 Graph — 每次请求创建独立 StateGraph 实例，确保请求间无共享可变状态 ───
+        const loadOpts = { agentVersion: req.agentVersion };
+        const graphDsl = this.graphLoader
+            ? await this.graphLoader.loadGraph(agentCode, loadOpts)
+            : DEFAULT_GRAPH_DSL;
+        const graph = await this.graphEngine.buildGraph(graphDsl);
+        const loadedToolsBase = this.graphLoader
+            ? toLoadedToolMap(await this.graphLoader.loadToolDefinitions(agentCode, loadOpts))
+            : undefined;
+        const loadedSkills = this.graphLoader
+            ? await this.graphLoader.loadSkillDefinitions(agentCode, { ...loadOpts, userId })
+            : undefined;
+        const skillDefinitions = toLoadedSkillMap(loadedSkills);
+        // Skill scripts 虚拟 Tool 并入 loadedTools（同名不覆盖平台 Tool）
+        const loadedTools = mergeSkillScriptTools(loadedToolsBase, loadedSkills);
+        const promptRoots = this.graphLoader
+            ? await this.graphLoader.resolvePromptRoots(agentCode, req.agentVersion)
+            : [];
+        // 组装 GraphState：有 Checkpoint 历史则只追加本轮 user，避免双重 append
+        const history = messageRecordsToGraphMessages(sessionContext.messages);
+        const messages = await buildTurnGraphMessages({
+            history,
+            input: req.input,
+            checkpointSaver: this.checkpointSaver,
+            threadId: sessionId,
+        });
+        const skillInput = resolveSkillInputFromInvokeInput(req.input);
+        let assistantText = '';
+        let toolCallReasoningContent;
+        let assistantReasoningContent;
+        const pendingToolCalls = [];
+        const toolResults = [];
+        // ─── Step 6: Graph.stream() 流式执行 ───
+        try {
+            const eventStream = this.graphEngine.stream(graph, {
+                messages,
+                userId,
+                delegationToken: executionContext.delegationToken,
+                agentCode,
+                agentVersion: req.agentVersion,
+                correlationId,
+                taskId,
+                sessionId,
+                executionContext,
+                forceToolServer: req.config?.forceToolServer,
+                loadedTools,
+                loadedSkills,
+                skillDefinitions,
+                skillInput,
+                promptRoots,
+                traceId: resolveTraceId(req),
+                traceCollector: this.traceCollector,
+            });
+            // 逐事件转发到 SSE；顺带把节点 token 记入 TokenStatsService（stream 原先未 record → 结尾全 0）
+            for await (const runtimeEvent of eventStream) {
+                // 连接已断开则提前退出
+                if (!emitter.isConnected) {
+                    break;
+                }
+                if (runtimeEvent.type === 'stats.node_token_usage') {
+                    const p = runtimeEvent.payload;
+                    this.tokenStatsService.record(taskId, {
+                        nodeId: p.nodeId ?? 'unknown',
+                        model: p.model ?? 'unknown',
+                        inputTokens: p.inputTokens ?? 0,
+                        outputTokens: p.outputTokens ?? 0,
+                        costEstimate: p.costEstimate ?? 0,
+                    });
+                }
+                if (runtimeEvent.type === 'tool.called') {
+                    const p = runtimeEvent.payload;
+                    if (p.toolCallId && p.toolName) {
+                        pendingToolCalls.push({
+                            id: p.toolCallId,
+                            name: p.toolName,
+                            arguments: p.arguments ?? {},
+                        });
+                    }
+                    if (typeof p.reasoningContent === 'string' && p.reasoningContent) {
+                        toolCallReasoningContent = p.reasoningContent;
+                    }
+                }
+                if (runtimeEvent.type === 'tool.result') {
+                    const p = runtimeEvent.payload;
+                    if (p.toolCallId && p.toolName) {
+                        toolResults.push({
+                            toolCallId: p.toolCallId,
+                            toolName: p.toolName,
+                            content: p.content,
+                            success: p.success !== false,
+                        });
+                    }
+                }
+                const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
+                if (streamedReasoning)
+                    assistantReasoningContent = streamedReasoning;
+                const delta = extractStreamTextDelta(runtimeEvent.type, runtimeEvent.payload);
+                if (delta) {
+                    if (runtimeEvent.type === 'response.final') {
+                        // final 若带完整文本则覆盖累加，避免与 chunk 重复拼接
+                        if (delta.trim())
+                            assistantText = delta;
+                    }
+                    else {
+                        assistantText += delta;
+                    }
+                }
+                // 将 RuntimeEvent 转为 SSEEvent 并推送
+                emitter.emit(this.runtimeEventToSSE(runtimeEvent, correlationId, taskId));
+            }
+        }
+        catch (error) {
+            const hitlPaused = unwrapHitlPaused(error);
+            if (hitlPaused) {
+                await this.taskService.updateStatus(taskId, 'waiting_hitl', buildHitlWaitingTaskOutput({
+                    threadId: hitlPaused.threadId,
+                    question: hitlPaused.question,
+                    options: hitlPaused.options,
+                }));
+                await persistHitlWaitingPlaceholder(this.messageService, {
+                    sessionId,
+                    taskId,
+                    correlationId,
+                    question: hitlPaused.question,
+                    options: hitlPaused.options,
+                    threadId: hitlPaused.threadId,
+                });
+                // interrupt 已 emit hitl.waiting；此处补状态事件并正常收尾（非 failed）
+                emitter.emit(this.buildSSEEvent('hitl.waited', correlationId, taskId, buildHitlWaitedPayload(hitlPaused)));
+                emitter.close();
+                return;
+            }
+            // ─── 错误处理：TokenBudgetExhausted ───
+            if (error instanceof TokenBudgetExhaustedError) {
+                await this.taskService.updateStatus(taskId, 'token_exhausted', error.message);
+                this.emitErrorAndClose(emitter, correlationId, taskId, error);
+                return;
+            }
+            // ─── 错误处理：Timeout ───
+            if (this.isTimeoutError(error)) {
+                await this.taskService.updateStatus(taskId, 'timeout');
+                emitter.emit(this.buildSSEEvent('task.error', correlationId, taskId, {
+                    code: ErrorCodes.TASK_TIMEOUT,
+                    message: 'Task execution timed out',
+                    recoverable: false,
+                }));
+                emitter.close();
+                return;
+            }
+            // ─── 错误处理：通用错误 ───
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            await this.taskService.updateStatus(taskId, 'failed', errorMessage);
+            this.emitErrorAndClose(emitter, correlationId, taskId, error);
+            return;
+        }
+        // ─── Step 7: 发送结束事件序列 ───
+        // Emit: response.final（带完整 assistant 文本，供客户端兜底）
+        const tokenStats = this.tokenStatsService.getTaskStats(taskId);
+        emitter.emit(this.buildSSEEvent('response.final', correlationId, taskId, {
+            content: assistantText,
+            format: 'text',
+        }));
+        // Emit: stats.token_usage
+        const totalTokens = (tokenStats.total.input ?? 0) + (tokenStats.total.output ?? 0);
+        emitter.emit(this.buildSSEEvent('stats.token_usage', correlationId, taskId, {
+            total: {
+                input: tokenStats.total.input,
+                output: tokenStats.total.output,
+                total: tokenStats.total.total ?? totalTokens,
+            },
+            byNode: tokenStats.byNode,
+            byModel: tokenStats.byModel,
+            costEstimate: tokenStats.costEstimate,
+        }));
+        // ─── Step 8: 记录 Token + 完成 Task + 关闭 SSE ───
+        const duration = Date.now() - startTime;
+        // Emit: task.completed
+        emitter.emit(this.buildSSEEvent('task.completed', correlationId, taskId, {
+            taskId,
+            duration,
+        }));
+        // Task 状态流转 → success
+        await this.taskService.updateStatus(taskId, 'success');
+        // ─── Step 8b: 持久化 transcript（与 invoke 同序）───
+        await persistTurnTranscript(this.messageService, {
+            sessionId,
+            taskId,
+            correlationId,
+            messages: buildTurnTranscriptFromStreamEvents({
+                pendingToolCalls,
+                toolResults,
+                assistantText,
+                toolCallReasoningContent,
+                assistantReasoningContent,
+            }),
+            assistantTokenCount: tokenStats.total.output ?? 0,
+        });
+        // 关闭 SSE 连接
+        emitter.close();
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 将 RuntimeEvent 转为 SSEEvent
+     */
+    runtimeEventToSSE(event, correlationId, taskId) {
+        return {
+            type: event.type,
+            data: event.payload,
+            correlationId: event.correlationId ?? correlationId,
+            taskId: event.taskId ?? taskId,
+            timestamp: event.timestamp,
+        };
+    }
+    /**
+     * 构建标准 SSEEvent
+     */
+    buildSSEEvent(type, correlationId, taskId, data) {
+        return {
+            type,
+            data,
+            correlationId,
+            taskId,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * 发射错误事件并关闭连接
+     */
+    emitErrorAndClose(emitter, correlationId, taskId, error) {
+        const appErr = classifyRuntimeError(error);
+        const body = appErr.toApiResponse();
+        emitter.emit(this.buildSSEEvent('task.error', correlationId, taskId, {
+            code: body.code,
+            message: body.message ?? '系统内部错误',
+            recoverable: false,
+        }));
+        emitter.close();
+    }
+    isTimeoutError(error) {
+        if (error instanceof Error) {
+            const msg = error.message.toLowerCase();
+            return msg.includes('timeout') || msg.includes('timed out');
+        }
+        return false;
+    }
+}

package/dist/api/index.d.ts

@@ -0,0 +1,3 @@
+export * from './routes/index.js';
+export * from './middleware/index.js';
+export * from './handlers/index.js';

package/dist/api/index.js

@@ -0,0 +1,4 @@
+// API module barrel export
+export * from './routes/index.js';
+export * from './middleware/index.js';
+export * from './handlers/index.js';

package/dist/api/middleware/auth.middleware.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Auth Middleware — 3种认证方式
+ *
+ * 支持:
+ * - CAS SSO Token (Cookie: CAS_TOKEN) — 浏览器用户
+ * - API Key (Authorization: Bearer <token>) — 业务系统集成
+ * - CLI Token (X-CLI-Token header) — 开发者 Playground
+ *
+ * Requirement 11 AC8: THE 系统 SHALL 支持3种认证方式调用
+ */
+/**
+ * 认证模式
+ */
+export type AuthMode = 'cas_sso' | 'api_key' | 'cli_token';
+/**
+ * 认证后的用户信息
+ */
+export interface AuthenticatedUser {
+    /** 用户 ID */
+    userId: string;
+    /** 用户角色列表 */
+    roles: string[];
+    /** 使用的认证方式 */
+    authMode: AuthMode;
+    /** 关联的 Agent（值为 agentCode；API Key 场景可能绑定特定 Agent） */
+    agentId?: string;
+}
+/**
+ * 框架无关的请求抽象
+ */
+export interface AuthRequest {
+    /** HTTP 请求头（key 小写） */
+    headers: Record<string, string | undefined>;
+    /** 解析后的 Cookie（可选） */
+    cookies?: Record<string, string>;
+}
+/**
+ * 认证服务接口 — 由外部实现注入
+ */
+export interface IAuthService {
+    /**
+     * 验证 token 并返回用户信息
+     * @param token - 待验证的凭证
+     * @param mode - 认证模式
+     * @returns 验证成功返回用户信息，失败返回 null
+     */
+    validate(token: string, mode: AuthMode): Promise<AuthenticatedUser | null>;
+}
+/**
+ * 认证失败自定义错误
+ */
+export declare class AuthenticationError extends Error {
+    readonly code = "AUTHENTICATION_FAILED";
+    constructor(message?: string);
+}
+/**
+ * Auth Middleware — 按优先级尝试3种认证方式
+ *
+ * 优先级：CAS SSO Cookie > Authorization Bearer > X-CLI-Token
+ */
+export declare class AuthMiddleware {
+    private readonly authService;
+    constructor(authService: IAuthService);
+    /**
+     * 认证入口
+     *
+     * 按优先级依次尝试:
+     * 1. CAS SSO Cookie (CAS_TOKEN)
+     * 2. Authorization: Bearer <token> (API Key)
+     * 3. X-CLI-Token header (CLI Token)
+     *
+     * @throws AuthenticationError 如果无有效凭证或验证失败
+     */
+    authenticate(req: AuthRequest): Promise<AuthenticatedUser>;
+    /**
+     * 从 Cookie 中提取 CAS Token
+     */
+    private extractCasToken;
+    /**
+     * 从 Authorization header 提取 Bearer Token
+     */
+    private extractBearerToken;
+    /**
+     * 从 X-CLI-Token header 提取 CLI Token
+     */
+    private extractCliToken;
+}
+/**
+ * 便捷函数 — 创建 AuthMiddleware 实例并执行认证
+ *
+ * @param req - 框架无关的请求对象
+ * @param authService - 认证服务实现
+ * @returns 认证后的用户信息
+ * @throws AuthenticationError
+ */
+export declare function authenticate(req: AuthRequest, authService: IAuthService): Promise<AuthenticatedUser>;