@gt-fe/eap-runtime 0.0.8

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

@@ -0,0 +1,411 @@
+/**
+ * InvokeOrchestrator — 同步调用编排器
+ *
+ * 实现 POST /api/v1/agents/:agentCode/invoke 的核心编排逻辑：
+ * 1. 检查 Session 日预算（SessionBudgetChecker）
+ * 2. 解析/创建 Session 上下文（SessionContextService）
+ * 3. 创建 Task（TaskService）
+ * 4. 启动 Task（pending → running）
+ * 5. 构建/执行 Graph（IStateGraphEngine）
+ * 6. 记录 Token 消耗（TokenStatsService + TaskService）
+ * 7. 完成 Task（running → success）
+ * 8. 返回 InvokeResponse
+ *
+ * @see design.md §1.5 /stream 内部执行逻辑
+ * @see requirements.md Requirement 11 AC1-AC2
+ */
+import { randomUUID } from 'node:crypto';
+import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, 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 { resolveExecutionContext } from '../../governance/governance-client.js';
+import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.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 '../../graph/hitl/hitl-handler.js';
+import { resolveTraceId } from '../../common/trace-id.js';
+// ─────────────────────────────────────────────
+// Default Graph DSL fallback
+// ─────────────────────────────────────────────
+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 },
+};
+// ─────────────────────────────────────────────
+// InvokeOrchestrator
+// ─────────────────────────────────────────────
+/**
+ * InvokeOrchestrator — 同步调用全流程编排
+ *
+ * 协调 SessionContextService、TaskService、IStateGraphEngine、TokenStatsService
+ * 等服务完成一次同步 Agent 调用的完整生命周期。
+ */
+export class InvokeOrchestrator {
+    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 - 解析后的调用请求
+     * @param userId - 经认证的用户 ID
+     * @returns 完整的 InvokeResponse（含 taskId, sessionId, output, tokenUsage, duration, status）
+     */
+    async execute(req, userId) {
+        const startTime = Date.now();
+        const agentCode = resolveAgentCode(req);
+        const ctx = resolveExecutionContext({ ...req, agentCode }, userId);
+        const correlationId = ctx.correlationId;
+        const traceId = randomUUID();
+        const effectiveUserId = ctx.userId ?? userId;
+        // ─── Step 1: 检查 Session 日预算 ───
+        // 若已有 sessionId，先检查是否预算耗尽
+        if (req.sessionId) {
+            try {
+                await this.sessionBudgetChecker.assertBudgetAvailable(req.sessionId);
+            }
+            catch (error) {
+                if (error instanceof SessionBudgetExhaustedError) {
+                    return this.buildErrorResponse(traceId, {
+                        taskId: '',
+                        sessionId: req.sessionId,
+                        output: error.message,
+                        tokenUsage: { input: 0, output: 0, total: 0 },
+                        duration: Date.now() - startTime,
+                        status: 'failed',
+                    });
+                }
+                throw error;
+            }
+        }
+        // ─── Step 2: 解析/创建 Session 上下文 ───
+        const sessionContext = await this.sessionContextService.resolveSessionContext({
+            sessionId: req.sessionId,
+            userId: effectiveUserId,
+            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) {
+                    return this.buildErrorResponse(traceId, {
+                        taskId: '',
+                        sessionId,
+                        output: error.message,
+                        tokenUsage: { input: 0, output: 0, total: 0 },
+                        duration: Date.now() - startTime,
+                        status: 'failed',
+                    });
+                }
+                throw error;
+            }
+        }
+        // ─── Step 3: 创建 Task（Hosting 传入 taskId 时复用）───
+        const timeout = req.config?.timeout ?? 60000;
+        const task = await this.taskService.create({
+            id: req.taskId,
+            agentId: agentCode,
+            sessionId,
+            userId: effectiveUserId,
+            correlationId,
+            input: req.input,
+            timeout,
+        });
+        // ─── Step 4: 启动 Task (pending → running) ───
+        await this.taskService.updateStatus(task.id, 'running');
+        // ─── Step 4b: 持久化本轮 user（多轮短期记忆）───
+        await persistUserTurnMessage(this.messageService, {
+            sessionId,
+            taskId: task.id,
+            correlationId,
+            content: req.input,
+        });
+        // ─── Step 5: 构建/执行 Graph ───
+        let graphResult;
+        try {
+            // 构建图 — 每次请求创建独立 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: effectiveUserId,
+                })
+                : 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);
+            // 同步执行图
+            graphResult = await this.graphEngine.invoke(graph, {
+                messages,
+                userId: effectiveUserId,
+                delegationToken: ctx.delegationToken,
+                agentCode,
+                agentVersion: req.agentVersion,
+                correlationId,
+                taskId: task.id,
+                sessionId,
+                executionContext: ctx,
+                forceToolServer: req.config?.forceToolServer,
+                loadedTools,
+                loadedSkills,
+                skillDefinitions,
+                skillInput,
+                promptRoots,
+                traceId: resolveTraceId(req),
+                traceCollector: this.traceCollector,
+            });
+        }
+        catch (error) {
+            const hitlPaused = unwrapHitlPaused(error);
+            if (hitlPaused) {
+                await this.taskService.updateStatus(task.id, 'waiting_hitl', buildHitlWaitingTaskOutput({
+                    threadId: hitlPaused.threadId,
+                    question: hitlPaused.question,
+                    options: hitlPaused.options,
+                }));
+                await persistHitlWaitingPlaceholder(this.messageService, {
+                    sessionId,
+                    taskId: task.id,
+                    correlationId,
+                    question: hitlPaused.question,
+                    options: hitlPaused.options,
+                    threadId: hitlPaused.threadId,
+                });
+                return this.buildResponse(traceId, {
+                    taskId: task.id,
+                    sessionId,
+                    output: hitlPaused.question,
+                    tokenUsage: { input: 0, output: 0, total: 0 },
+                    duration: Date.now() - startTime,
+                    status: 'waiting_hitl',
+                    hitl: {
+                        question: hitlPaused.question,
+                        options: hitlPaused.options,
+                        threadId: hitlPaused.threadId,
+                    },
+                });
+            }
+            // ─── 错误处理：TokenBudgetExhausted ───
+            if (error instanceof TokenBudgetExhaustedError) {
+                await this.taskService.updateStatus(task.id, 'token_exhausted', error.message);
+                return this.buildResponse(traceId, {
+                    taskId: task.id,
+                    sessionId,
+                    output: error.message,
+                    tokenUsage: { input: 0, output: 0, total: 0 },
+                    duration: Date.now() - startTime,
+                    status: 'token_exhausted',
+                });
+            }
+            // ─── 错误处理：Timeout ───
+            if (this.isTimeoutError(error)) {
+                await this.taskService.updateStatus(task.id, 'timeout');
+                return this.buildResponse(traceId, {
+                    taskId: task.id,
+                    sessionId,
+                    output: 'Task execution timed out',
+                    tokenUsage: { input: 0, output: 0, total: 0 },
+                    duration: Date.now() - startTime,
+                    status: 'timeout',
+                });
+            }
+            // ─── 错误处理：通用错误 ───
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            await this.taskService.updateStatus(task.id, 'failed', errorMessage);
+            return this.buildErrorResponse(traceId, {
+                taskId: task.id,
+                sessionId,
+                output: errorMessage,
+                tokenUsage: { input: 0, output: 0, total: 0 },
+                duration: Date.now() - startTime,
+                status: 'failed',
+            });
+        }
+        // ─── Step 6: 记录 Token 消耗 ───
+        //
+        // 合并两个来源：
+        // 1. tokenStatsService：按 task 累计的 token（可能多节点累加）
+        // 2. graphResult.tokenUsage：图执行返回的 token（含 perNode 明细 + total 累计）
+        //
+        // 优先使用 graphResult（它已含多轮 LLM 累加后的 total + perNode 明细）。
+        // 注：早期 `||` 在 0 值时会错误回退，此处改为 `??` 并优先 graphResult。
+        const tokenStats = this.tokenStatsService.getTaskStats(task.id);
+        const graphUsage = graphResult.tokenUsage;
+        const tokenUsage = {
+            input: graphUsage.input > 0 ? graphUsage.input : (tokenStats.total.input ?? 0),
+            output: graphUsage.output > 0 ? graphUsage.output : (tokenStats.total.output ?? 0),
+            total: graphUsage.total > 0 ? graphUsage.total : (tokenStats.total.total ?? 0),
+            perNode: graphUsage.perNode,
+            // 会话累计：当前请求前历史消息 tokenCount 之和 + 本次请求消耗
+            // 注：历史 tokenCount 是输入/输出未区分的粗粒度值，故 conversationTotal.input/output 是近似值
+            conversationTotal: (() => {
+                const historyTokens = sessionContext.messages.reduce((sum, m) => sum + (m.tokenCount ?? 0), 0);
+                const total = historyTokens + (graphUsage.total || tokenStats.total.total || 0);
+                return {
+                    input: historyTokens + graphUsage.input,
+                    output: graphUsage.output,
+                    total,
+                };
+            })(),
+        };
+        // 将 Graph 层面的 token 消耗记录到 Task（按节点明细逐个记录，便于审计）
+        if (graphUsage.perNode && graphUsage.perNode.length > 0) {
+            for (const u of graphUsage.perNode) {
+                await this.taskService.recordTokenUsage(task.id, {
+                    nodeId: u.nodeId,
+                    model: u.model,
+                    inputTokens: u.inputTokens,
+                    outputTokens: u.outputTokens,
+                    costEstimate: 0,
+                });
+            }
+        }
+        else if (graphUsage.total > 0) {
+            await this.taskService.recordTokenUsage(task.id, {
+                nodeId: 'graph',
+                model: 'unknown',
+                inputTokens: graphUsage.input,
+                outputTokens: graphUsage.output,
+                costEstimate: 0,
+            });
+        }
+        // ─── Step 7: 完成 Task (running → success) ───
+        await this.taskService.updateStatus(task.id, 'success', graphResult.output);
+        // ─── Step 7b: 持久化本轮 transcript（统一顺序：assistant tool_calls → tool → assistant 文本）───
+        const initialMessagesCount = sessionContext.messages.length + 1; // history + 本轮 user
+        const allMessages = Array.isArray(graphResult.finalState?.messages)
+            ? graphResult.finalState.messages
+            : [];
+        const newMessages = allMessages.slice(initialMessagesCount);
+        await persistTurnTranscript(this.messageService, {
+            sessionId,
+            taskId: task.id,
+            correlationId,
+            messages: newMessages,
+            fallbackAssistantContent: graphResult.output ?? '',
+            assistantTokenCount: tokenUsage.output,
+        });
+        // ─── Step 8: 返回 InvokeResponse ───
+        const duration = Date.now() - startTime;
+        // 从本轮 Graph 执行结果中提取 tool 事件明细（供 CLI / UI 渲染 ReAct 循环）
+        const toolEvents = extractToolEvents(newMessages);
+        return this.buildResponse(traceId, {
+            taskId: task.id,
+            sessionId,
+            output: graphResult.output,
+            tokenUsage,
+            duration,
+            status: 'success',
+            toolEvents: toolEvents.length > 0 ? toolEvents : undefined,
+        });
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    buildResponse(traceId, data) {
+        return { code: 'ok', data, traceId };
+    }
+    buildErrorResponse(traceId, data) {
+        return { code: data.status === 'token_exhausted' ? 'runtime.budget.task_exhausted' : 'runtime.graph.execution_error', data, traceId };
+    }
+    isTimeoutError(error) {
+        if (error instanceof Error) {
+            const msg = error.message.toLowerCase();
+            return msg.includes('timeout') || msg.includes('timed out');
+        }
+        return false;
+    }
+}
+// ─────────────────────────────────────────────
+// Module-level Helpers
+// ─────────────────────────────────────────────
+/**
+ * 从本轮新增的 GraphMessage 中提取 tool.called / tool.result 事件
+ *
+ * 扫描顺序：按 messages 数组原始顺序（即 Graph 执行的时间顺序）。
+ * - assistant 消息含 toolCalls → 生成一条或多条 kind='calling' 事件
+ * - tool 角色消息 → 生成 kind='result' 事件，content 截断到 500 字符
+ */
+const TOOL_RESULT_PREVIEW_MAX = 500;
+function extractToolEvents(newMessages) {
+    const events = [];
+    for (const msg of newMessages) {
+        if (msg.role === 'assistant' && Array.isArray(msg.toolCalls) && msg.toolCalls.length > 0) {
+            for (const tc of msg.toolCalls) {
+                events.push({
+                    kind: 'calling',
+                    toolName: tc.name ?? 'unknown',
+                    arguments: (tc.arguments ?? {}),
+                });
+            }
+        }
+        else if (msg.role === 'tool') {
+            const rawContent = typeof msg.content === 'string' ? msg.content : '';
+            const truncated = rawContent.length > TOOL_RESULT_PREVIEW_MAX
+                ? rawContent.slice(0, TOOL_RESULT_PREVIEW_MAX) + '…'
+                : rawContent;
+            events.push({
+                kind: 'result',
+                toolName: msg.toolName ?? 'tool',
+                content: truncated,
+                success: msg.success !== false,
+            });
+        }
+    }
+    return events;
+}
+/** @deprecated 请直接从 `graph/hitl/hitl-handler` 导入；此处保留 re-export 兼容旧测试引用 */
+export { unwrapHitlPaused } from '../../graph/hitl/hitl-handler.js';

package/dist/api/handlers/messages.handler.d.ts

@@ -0,0 +1,53 @@
+/**
+ * MessagesOrchestrator — 会话消息编排器
+ *
+ * 实现多轮对话核心逻辑：
+ * - POST /api/v1/sessions/:sessionId/messages: 在已有会话中发送新消息，触发 Agent 执行
+ * - GET /api/v1/sessions/:sessionId/messages: 获取会话消息历史
+ *
+ * 编排步骤（postMessage）：
+ * 1. 验证 Session 存在（SessionService.getSession）
+ * 2. 委托 InvokeOrchestrator.execute()（主路径已写回 user/assistant Message）
+ * 3. 返回 InvokeResponse
+ *
+ * @see design.md §1.5 多轮对话
+ * @see requirements.md Requirement 11 AC3, AC5, AC10
+ */
+import type { SessionService } from '../../session/session.service.js';
+import type { MessageService } from '../../session/message.service.js';
+import type { InvokeOrchestrator } from './invoke.handler.js';
+import type { PostMessageRequest, PostMessageResponse, GetMessagesRequest, GetMessagesResponse } from '../routes/session.routes.js';
+/**
+ * MessagesOrchestrator 构造器依赖
+ */
+export interface MessagesOrchestratorDeps {
+    sessionService: SessionService;
+    messageService: MessageService;
+    invokeOrchestrator: InvokeOrchestrator;
+}
+/**
+ * MessagesOrchestrator — 会话消息编排
+ *
+ * 将 messages 端点与 invoke 编排逻辑关联，确保会话连续性。
+ */
+export declare class MessagesOrchestrator {
+    private readonly sessionService;
+    private readonly messageService;
+    private readonly invokeOrchestrator;
+    constructor(deps: MessagesOrchestratorDeps);
+    /**
+     * 在已有会话中发送新消息并触发 Agent 执行
+     *
+     * @param req - 发送消息请求（含 sessionId, input, config）
+     * @param userId - 经认证的用户 ID
+     * @returns 与 InvokeResponse 相同的响应
+     */
+    postMessage(req: PostMessageRequest, userId: string): Promise<PostMessageResponse>;
+    /**
+     * 获取会话消息历史（支持分页）
+     *
+     * @param req - 获取消息请求（含 sessionId, limit, offset）
+     * @returns 消息列表响应
+     */
+    getMessages(req: GetMessagesRequest): Promise<GetMessagesResponse>;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * MessagesOrchestrator — 会话消息编排器
+ *
+ * 实现多轮对话核心逻辑：
+ * - POST /api/v1/sessions/:sessionId/messages: 在已有会话中发送新消息，触发 Agent 执行
+ * - GET /api/v1/sessions/:sessionId/messages: 获取会话消息历史
+ *
+ * 编排步骤（postMessage）：
+ * 1. 验证 Session 存在（SessionService.getSession）
+ * 2. 委托 InvokeOrchestrator.execute()（主路径已写回 user/assistant Message）
+ * 3. 返回 InvokeResponse
+ *
+ * @see design.md §1.5 多轮对话
+ * @see requirements.md Requirement 11 AC3, AC5, AC10
+ */
+// ─────────────────────────────────────────────
+// MessagesOrchestrator
+// ─────────────────────────────────────────────
+/**
+ * MessagesOrchestrator — 会话消息编排
+ *
+ * 将 messages 端点与 invoke 编排逻辑关联，确保会话连续性。
+ */
+export class MessagesOrchestrator {
+    sessionService;
+    messageService;
+    invokeOrchestrator;
+    constructor(deps) {
+        this.sessionService = deps.sessionService;
+        this.messageService = deps.messageService;
+        this.invokeOrchestrator = deps.invokeOrchestrator;
+    }
+    /**
+     * 在已有会话中发送新消息并触发 Agent 执行
+     *
+     * @param req - 发送消息请求（含 sessionId, input, config）
+     * @param userId - 经认证的用户 ID
+     * @returns 与 InvokeResponse 相同的响应
+     */
+    async postMessage(req, userId) {
+        const { sessionId, input, config } = req;
+        // ─── Step 1: 验证 Session 存在 ───
+        const session = await this.sessionService.getSession(sessionId);
+        const metaVersion = typeof session.metadata?.agentVersion === 'string'
+            ? session.metadata.agentVersion
+            : undefined;
+        const agentVersion = req.agentVersion ?? metaVersion;
+        // ─── Step 2: 委托 InvokeOrchestrator（user/assistant Message 由 invoke 主路径写回）───
+        const invokeReq = {
+            agentId: session.agentId,
+            agentCode: session.agentId,
+            input,
+            sessionId,
+            config,
+            agentVersion,
+        };
+        return this.invokeOrchestrator.execute(invokeReq, userId);
+    }
+    /**
+     * 获取会话消息历史（支持分页）
+     *
+     * @param req - 获取消息请求（含 sessionId, limit, offset）
+     * @returns 消息列表响应
+     */
+    async getMessages(req) {
+        const { sessionId, limit, offset } = req;
+        // ─── Step 1: 验证 Session 存在 ───
+        await this.sessionService.getSession(sessionId);
+        // ─── Step 2: 查询消息列表（分页） ───
+        const messages = await this.messageService.getMessages(sessionId, { limit, offset });
+        // ─── Step 3: 返回消息列表 ───
+        return {
+            code: 'ok',
+            data: {
+                messages,
+                total: messages.length,
+            },
+        };
+    }
+}

package/dist/api/handlers/stream.handler.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 type { ServerResponse } from 'node:http';
+import type { SessionContextService } from '../../session/session-context.service.js';
+import type { MessageService } from '../../session/message.service.js';
+import type { TaskService } from '../../task/task.service.js';
+import type { IStateGraphEngine } from '../../graph/contracts/state-graph.contract.js';
+import type { TokenStatsService } from '../../token/token-stats.service.js';
+import type { TokenBudgetGuard } from '../../token/token-budget-guard.js';
+import type { SessionBudgetChecker } from '../../token/session-budget-checker.js';
+import type { StreamRequest } from '../routes/agent.routes.js';
+import type { GraphLoader } from '../../registry/graph-loader.js';
+import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
+import type { ITraceCollector } from '../../contracts/trace-collector.js';
+/**
+ * StreamOrchestrator 构造器依赖
+ */
+export interface StreamOrchestratorDeps {
+    sessionContextService: SessionContextService;
+    taskService: TaskService;
+    graphEngine: IStateGraphEngine;
+    tokenStatsService: TokenStatsService;
+    tokenBudgetGuard: TokenBudgetGuard;
+    sessionBudgetChecker: SessionBudgetChecker;
+    /** 多轮短期记忆写回；未注入时跳过持久化 */
+    messageService?: MessageService;
+    graphLoader?: GraphLoader;
+    /** 用于判断 session Checkpoint 是否已有历史，避免双重 append */
+    checkpointSaver?: ICheckpointSaver;
+    /** Hosting 注入的 Trace 采集器；与 traceId 同时存在时创建 Skill/Tool span */
+    traceCollector?: ITraceCollector;
+}
+/**
+ * StreamOrchestrator — 流式调用全流程编排
+ *
+ * 协调 SessionContextService、TaskService、IStateGraphEngine、SSEEmitter、TokenStatsService
+ * 等服务完成一次 SSE 流式 Agent 调用的完整生命周期。
+ */
+export declare class StreamOrchestrator {
+    private readonly sessionContextService;
+    private readonly taskService;
+    private readonly graphEngine;
+    private readonly tokenStatsService;
+    private readonly tokenBudgetGuard;
+    private readonly sessionBudgetChecker;
+    private readonly messageService?;
+    private readonly graphLoader?;
+    private readonly checkpointSaver?;
+    private readonly traceCollector?;
+    constructor(deps: StreamOrchestratorDeps);
+    /**
+     * 执行流式调用编排
+     *
+     * @param req - 解析后的调用请求（与 InvokeRequest 相同）
+     * @param res - Node.js HTTP ServerResponse，用于写入 SSE 事件
+     * @param userId - 经认证的用户 ID
+     */
+    execute(req: StreamRequest, res: ServerResponse, userId: string): Promise<void>;
+    private executeInternal;
+    /**
+     * 将 RuntimeEvent 转为 SSEEvent
+     */
+    private runtimeEventToSSE;
+    /**
+     * 构建标准 SSEEvent
+     */
+    private buildSSEEvent;
+    /**
+     * 发射错误事件并关闭连接
+     */
+    private emitErrorAndClose;
+    private isTimeoutError;
+}