@gt-fe/eap-runtime 0.0.8

package/dist/runtime/agent-runtime.js

@@ -0,0 +1,777 @@
+/**
+ * AgentRuntime — Runtime SDK 门面
+ *
+ * Hosting 内嵌调用入口：execute / stream / resumeHitl / fork。
+ * 对外 HTTP 由 Hosting 提供；本地 eap dev 亦可直接实例化本类。
+ *
+ * @see 04-runtime-core/design.md §1.5 / §1.7
+ */
+import { randomUUID } from 'node:crypto';
+import { HitlAlreadyTimedOutError, HitlNotWaitingError, buildHitlWaitedPayload, isHitlDeadlinePassed, readPersistedHitlWaiting, unwrapHitlPaused, } from '../graph/hitl/hitl-handler.js';
+import { toLoadedSkillMap, mergeSkillScriptTools } from '../tool/system-prompt-builder.js';
+import { buildHitlWaitingTaskOutput, buildTurnGraphMessages, buildTurnTranscriptFromStreamEvents, extractHitlThreadId, extractStreamReasoning, extractStreamTextDelta, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, } from '../session/persist-turn-messages.js';
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
+import { resolveExecutionContext } from '../governance/governance-client.js';
+import { resolveAgentCode } from '../common/agent-code.js';
+import { resolveTraceId } from '../common/trace-id.js';
+import { resolveSkillInputFromInvokeInput } from '../registry/skill-io-guard.js';
+const HITL_TERMINAL_STATUSES = [
+    'success',
+    'failed',
+    'timeout',
+    'token_exhausted',
+];
+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 },
+};
+/**
+ * AgentRuntime — 管理 Graph 执行的 SDK 门面
+ */
+export class AgentRuntime {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+        if (typeof this.deps.hitlHandler.setTimeoutListener === 'function') {
+            this.deps.hitlHandler.setTimeoutListener((event) => this.handleHitlTimeout(event));
+        }
+    }
+    /** 从 GraphLoader 解析 tool manifest 映射（invoke/stream/resume/fork 共用） */
+    async resolveLoadedTools(agentCode, agentVersion) {
+        if (!this.deps.graphLoader)
+            return undefined;
+        const { toLoadedToolMap } = await import('../tool/loaded-tool-definition.js');
+        return toLoadedToolMap(await this.deps.graphLoader.loadToolDefinitions(agentCode, { agentVersion }));
+    }
+    /** 从预装重载 Skill 定义（HITL/Fork 时 ephemeral 字段可能丢失） */
+    async resolveLoadedSkills(agentCode, userId, agentVersion) {
+        if (!this.deps.graphLoader)
+            return {};
+        const loadedSkills = await this.deps.graphLoader.loadSkillDefinitions(agentCode, {
+            userId,
+            agentVersion,
+        });
+        return { loadedSkills, skillDefinitions: toLoadedSkillMap(loadedSkills) };
+    }
+    /**
+     * 向会话预置种子消息（开发者 few-shot / 开场白）
+     *
+     * 专为 SDK `createAgentService({ messages })` 提供：在首条真实用户输入之前
+     * 一次性将开发者提供的对话上下文写入 session，后续 execute/stream 直接沿用现有
+     * “Session 历史 + 当前输入”途径。
+     *
+     * 行为：
+     * - `role` 仅接受 `user` / `assistant`；`system` 应写入 graph.json LLM 节点的
+     *   `config.systemPrompt`（由 SystemPromptBuilder 拼平台规则 + 开发者提示词）；
+     *   `tool` 必须与前置 assistant.toolCalls 严格配对，不得单独作为种子。
+     * - 幂等语义（exactly-once）：当 session 已存在任何历史消息时，直接返回
+     *   `seeded: false`，不重复写入。
+     *
+     * @throws PARAMS_INVALID messages 为空、role 不在白名单、content 非字符串或为空
+     * @throws PARAMS_INVALID messageService 未注入（无存储无法写入）
+     */
+    async seedSessionMessages(params) {
+        const agentCode = resolveAgentCode(params);
+        const ctx = resolveExecutionContext({
+            agentCode,
+            sessionId: params.sessionId,
+            executionContext: params.executionContext,
+        }, 'anonymous');
+        const userId = ctx.userId ?? 'anonymous';
+        if (!this.deps.messageService) {
+            throw new AppError(ErrorCodes.PARAMS_INVALID, 'seedSessionMessages requires messageService to be injected', { exposeMessage: true });
+        }
+        if (!Array.isArray(params.messages) || params.messages.length === 0) {
+            throw new AppError(ErrorCodes.PARAMS_INVALID, 'seedSessionMessages requires a non-empty messages array', { exposeMessage: true });
+        }
+        // role 白名单 + content 合法性校验（仅允许 user | assistant）
+        params.messages.forEach((message, index) => {
+            if (!message || typeof message !== 'object') {
+                throw new AppError(ErrorCodes.PARAMS_INVALID, `seedSessionMessages messages[${index}] must be an object`, { exposeMessage: true });
+            }
+            if (message.role !== 'user' && message.role !== 'assistant') {
+                throw new AppError(ErrorCodes.PARAMS_INVALID, `seedSessionMessages messages[${index}].role "${String(message.role)}" is not allowed; only 'user' and 'assistant' are accepted (system belongs to config.systemPrompt; tool must pair with prior assistant.toolCalls)`, { exposeMessage: true });
+            }
+            if (typeof message.content !== 'string' || message.content.length === 0) {
+                throw new AppError(ErrorCodes.PARAMS_INVALID, `seedSessionMessages messages[${index}].content must be a non-empty string`, { exposeMessage: true });
+            }
+        });
+        // 复用或新建 session（resolveSessionContext 已处理 sessionId 存在/采纳/新建 三种分支）
+        const sessionContext = await this.deps.sessionContextService.resolveSessionContext({
+            sessionId: params.sessionId,
+            userId,
+            agentId: agentCode,
+            agentVersion: params.agentVersion,
+        });
+        const sessionId = sessionContext.session.id;
+        // 幂等守护：既有历史则不重复写入，保证 exactly-once 语义
+        if (sessionContext.messages.length > 0) {
+            return { sessionId, seeded: false };
+        }
+        await this.deps.messageService.addMessages(params.messages.map((message) => ({
+            sessionId,
+            correlationId: ctx.correlationId,
+            role: message.role,
+            content: message.content,
+            toolCalls: message.toolCalls ?? undefined,
+            tokenCount: 0,
+            metadata: { seed: true },
+        })));
+        return { sessionId, seeded: true };
+    }
+    /** 同步执行 Graph（经 InvokeOrchestrator，内含 loadedTools 注入） */
+    async execute(params) {
+        const agentCode = resolveAgentCode(params);
+        const ctx = resolveExecutionContext({
+            agentCode,
+            sessionId: params.sessionId,
+            executionContext: params.executionContext,
+        }, 'anonymous');
+        const userId = ctx.userId ?? 'anonymous';
+        const response = await this.deps.invokeOrchestrator.execute({
+            agentCode,
+            input: params.input,
+            sessionId: params.sessionId,
+            taskId: params.taskId,
+            agentVersion: params.agentVersion,
+            config: params.config,
+            executionContext: ctx,
+            userId,
+            traceId: resolveTraceId(params),
+        }, userId);
+        return response.data;
+    }
+    /**
+     * 流式执行 Graph，产出 SSE 事件序列
+     */
+    async *stream(params) {
+        const agentCode = resolveAgentCode(params);
+        const ctx = resolveExecutionContext({
+            agentCode,
+            sessionId: params.sessionId,
+            executionContext: params.executionContext,
+        }, 'anonymous');
+        const userId = ctx.userId ?? 'anonymous';
+        const correlationId = ctx.correlationId;
+        const sessionContext = await this.deps.sessionContextService.resolveSessionContext({
+            sessionId: params.sessionId,
+            userId,
+            agentId: agentCode,
+            agentVersion: params.agentVersion,
+        });
+        const sessionId = sessionContext.session.id;
+        if (sessionContext.isNew) {
+            yield this.toSSE('session.created', correlationId, '', {
+                sessionId,
+                userId,
+            });
+        }
+        const task = await this.deps.taskService.create({
+            id: params.taskId,
+            agentId: agentCode,
+            sessionId,
+            userId,
+            correlationId,
+            input: params.input,
+            timeout: params.config?.timeout ?? 60_000,
+        });
+        await this.deps.taskService.updateStatus(task.id, 'running');
+        await persistUserTurnMessage(this.deps.messageService, {
+            sessionId,
+            taskId: task.id,
+            correlationId,
+            content: params.input,
+        });
+        yield this.toSSE('task.started', correlationId, task.id, { taskId: task.id, sessionId });
+        const loadOpts = { agentVersion: params.agentVersion };
+        const graphDsl = this.deps.graphLoader
+            ? await this.deps.graphLoader.loadGraph(agentCode, loadOpts)
+            : DEFAULT_GRAPH_DSL;
+        const graph = await this.deps.graphEngine.buildGraph(graphDsl);
+        const loadedToolsBase = await this.resolveLoadedTools(agentCode, params.agentVersion);
+        const loadedSkills = this.deps.graphLoader
+            ? await this.deps.graphLoader.loadSkillDefinitions(agentCode, {
+                ...loadOpts,
+                userId,
+            })
+            : undefined;
+        const skillDefinitions = toLoadedSkillMap(loadedSkills);
+        // Skill scripts 虚拟 Tool 并入 loadedTools（同名不覆盖平台 Tool）
+        const loadedTools = mergeSkillScriptTools(loadedToolsBase, loadedSkills);
+        const promptRoots = this.deps.graphLoader
+            ? await this.deps.graphLoader.resolvePromptRoots(agentCode, params.agentVersion)
+            : [];
+        const history = messageRecordsToGraphMessages(sessionContext.messages);
+        const messages = await buildTurnGraphMessages({
+            history,
+            input: params.input,
+            checkpointSaver: this.deps.checkpointSaver,
+            threadId: sessionId,
+        });
+        const startTime = Date.now();
+        let assistantText = '';
+        let toolCallReasoningContent;
+        let assistantReasoningContent;
+        const pendingToolCalls = [];
+        const toolResults = [];
+        try {
+            for await (const runtimeEvent of this.deps.graphEngine.stream(graph, {
+                messages,
+                userId,
+                delegationToken: ctx.delegationToken,
+                agentCode,
+                agentVersion: params.agentVersion,
+                correlationId,
+                taskId: task.id,
+                sessionId,
+                executionContext: ctx,
+                forceToolServer: params.config?.forceToolServer,
+                loadedTools,
+                loadedSkills,
+                skillDefinitions,
+                promptRoots,
+                skillInput: resolveSkillInputFromInvokeInput(params.input),
+                traceId: resolveTraceId(params),
+                traceCollector: this.deps.traceCollector,
+            })) {
+                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') {
+                        if (delta.trim())
+                            assistantText = delta;
+                    }
+                    else {
+                        assistantText += delta;
+                    }
+                }
+                yield this.runtimeEventToSSE(runtimeEvent, correlationId, task.id);
+            }
+            await this.deps.taskService.updateStatus(task.id, 'success');
+            await persistTurnTranscript(this.deps.messageService, {
+                sessionId,
+                taskId: task.id,
+                correlationId,
+                messages: buildTurnTranscriptFromStreamEvents({
+                    pendingToolCalls,
+                    toolResults,
+                    assistantText,
+                    toolCallReasoningContent,
+                    assistantReasoningContent,
+                }),
+            });
+            yield this.toSSE('task.completed', correlationId, task.id, {
+                taskId: task.id,
+                duration: Date.now() - startTime,
+            });
+        }
+        catch (err) {
+            const hitlPaused = unwrapHitlPaused(err);
+            if (hitlPaused) {
+                await this.deps.taskService.updateStatus(task.id, 'waiting_hitl', buildHitlWaitingTaskOutput({
+                    threadId: hitlPaused.threadId,
+                    question: hitlPaused.question,
+                    options: hitlPaused.options,
+                }));
+                await persistHitlWaitingPlaceholder(this.deps.messageService, {
+                    sessionId,
+                    taskId: task.id,
+                    correlationId,
+                    question: hitlPaused.question,
+                    options: hitlPaused.options,
+                    threadId: hitlPaused.threadId,
+                });
+                yield this.toSSE('hitl.waited', correlationId, task.id, buildHitlWaitedPayload(hitlPaused));
+                return;
+            }
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            await this.deps.taskService.updateStatus(task.id, 'failed', message);
+            yield this.toSSE('task.error', correlationId, task.id, {
+                code: 'runtime.graph.execution_error',
+                message,
+                recoverable: false,
+            });
+            throw err;
+        }
+    }
+    /**
+     * HITL 用户响应后继续执行（同步结果）。
+     *
+     * 内部消费 `streamResumeHitl`：成功为 success；再次确认暂停为 waiting_hitl（不抛错）。
+     * 需要过程事件（`hitl.resumed` / `tool.result` / `skill.completed`）时请直接迭代 streamResumeHitl。
+     */
+    async resumeHitl(taskId, response) {
+        let output = '';
+        let waiting;
+        let sawWait = false;
+        let assistantText = '';
+        for await (const event of this.streamResumeHitl(taskId, response)) {
+            if (event.type === 'hitl.waited') {
+                sawWait = true;
+                const data = event.data;
+                waiting = {
+                    question: typeof data.question === 'string' ? data.question : '',
+                    options: Array.isArray(data.options) ? data.options.map(String) : [],
+                    threadId: typeof data.threadId === 'string' ? data.threadId : '',
+                };
+                output = waiting.question;
+            }
+            const delta = extractStreamTextDelta(event.type, event.data);
+            if (delta) {
+                if (event.type === 'response.final') {
+                    if (delta.trim())
+                        assistantText = delta;
+                }
+                else {
+                    assistantText += delta;
+                }
+            }
+        }
+        if (sawWait) {
+            return { taskId, status: 'waiting_hitl', output, hitl: waiting };
+        }
+        return { taskId, status: 'success', output: assistantText || output };
+    }
+    /**
+     * HITL 恢复的流式入口：新开一条 SSE（第一条 stream 在 `hitl.waited` 后已结束）。
+     *
+     * 事件顺序：`hitl.resumed` → 图内 `tool.*` / `skill.*` / `response.*` → `task.completed`
+     * 或再次 `hitl.waited`。拒绝/失败会发出同 `toolCallId` 的 `tool.error`。
+     *
+     * 从 GraphLoader `buildGraph` + Checkpoint GraphState 续跑，不用空的 `restore()`。
+     */
+    async *streamResumeHitl(taskId, response) {
+        const ctx = await this.prepareHitlResume(taskId, response);
+        const { task, threadId, sessionId, correlationId } = ctx;
+        let resumedState;
+        try {
+            resumedState = await this.deps.hitlHandler.resume(taskId, response.choice, response.userId, threadId);
+        }
+        catch (err) {
+            if (err instanceof HitlAlreadyTimedOutError) {
+                throw new AppError(ErrorCodes.TASK_HITL_TIMEOUT, `Task ${taskId} HITL wait exceeded deadline`, { exposeMessage: true });
+            }
+            if (err instanceof HitlNotWaitingError) {
+                throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} is not waiting for HITL`, { exposeMessage: true });
+            }
+            throw err;
+        }
+        const claimed = await this.deps.taskService.tryUpdateStatus(taskId, 'waiting_hitl', 'running');
+        if (!claimed) {
+            throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} is no longer waiting for HITL`, { exposeMessage: true });
+        }
+        yield this.toSSE('hitl.resumed', correlationId, taskId, {
+            choice: response.choice,
+            userId: response.userId,
+        });
+        const checkpoint = await this.deps.checkpointSaver.load(threadId);
+        if (!checkpoint) {
+            throw new AppError(ErrorCodes.HOSTING_CHECKPOINT_NOT_FOUND, `Checkpoint not found for thread: ${threadId}`, { exposeMessage: true });
+        }
+        const agentCode = task.agentId;
+        const agentVersion = (typeof resumedState.agentVersion === 'string' && resumedState.agentVersion) ||
+            undefined;
+        const graph = await this.rebuildExecutableGraph(agentCode, agentVersion);
+        const loadedTools = resumedState.loadedTools ??
+            (await this.resolveLoadedTools(agentCode, agentVersion));
+        const skillFromState = resumedState.skillDefinitions;
+        const skillBundle = skillFromState
+            ? {
+                skillDefinitions: skillFromState,
+                loadedSkills: resumedState.loadedSkills,
+            }
+            : await this.resolveLoadedSkills(agentCode, response.userId, agentVersion);
+        const continueState = {
+            ...resumedState,
+            messages: resumedState.messages ?? [],
+            replaceCheckpointMessages: true,
+            sessionId: resumedState.sessionId ?? sessionId,
+            taskId,
+            correlationId: resumedState.correlationId ?? correlationId,
+            agentVersion: agentVersion ?? resumedState.agentVersion,
+            activatedSkill: resumedState.activatedSkill,
+            skillRoute: resumedState.skillRoute ??
+                (typeof resumedState.activatedSkill === 'string' && resumedState.activatedSkill
+                    ? 'skill'
+                    : resumedState.skillRoute),
+            hitlChoice: resumedState.hitlChoice,
+            userId: response.userId,
+            delegationToken: response.executionContext?.delegationToken ?? resumedState.delegationToken,
+            executionContext: response.executionContext ?? resumedState.executionContext,
+            loadedTools,
+            ...skillBundle,
+            traceId: resolveTraceId(resumedState) ?? resolveTraceId(checkpoint.state),
+            traceCollector: this.deps.traceCollector,
+        };
+        const startTime = Date.now();
+        let assistantText = '';
+        let toolCallReasoningContent;
+        let assistantReasoningContent;
+        const pendingToolCalls = [];
+        const toolResults = [];
+        try {
+            for await (const runtimeEvent of this.deps.graphEngine.stream(graph, continueState)) {
+                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' || runtimeEvent.type === 'tool.error') {
+                    const p = runtimeEvent.payload;
+                    if (p.toolCallId && p.toolName) {
+                        toolResults.push({
+                            toolCallId: p.toolCallId,
+                            toolName: p.toolName,
+                            content: p.content ?? p.error,
+                            success: runtimeEvent.type === 'tool.result' && 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') {
+                        if (delta.trim())
+                            assistantText = delta;
+                    }
+                    else {
+                        assistantText += delta;
+                    }
+                }
+                yield this.runtimeEventToSSE(runtimeEvent, correlationId, taskId);
+            }
+            await this.deps.taskService.updateStatus(taskId, 'success', assistantText || undefined);
+            if (sessionId) {
+                await persistTurnTranscript(this.deps.messageService, {
+                    sessionId,
+                    taskId,
+                    correlationId,
+                    messages: buildTurnTranscriptFromStreamEvents({
+                        pendingToolCalls,
+                        toolResults,
+                        assistantText,
+                        toolCallReasoningContent,
+                        assistantReasoningContent,
+                    }),
+                });
+            }
+            yield this.toSSE('task.completed', correlationId, taskId, {
+                taskId,
+                duration: Date.now() - startTime,
+            });
+        }
+        catch (err) {
+            const hitlPaused = unwrapHitlPaused(err);
+            if (hitlPaused) {
+                await this.deps.taskService.updateStatus(taskId, 'waiting_hitl', buildHitlWaitingTaskOutput({
+                    threadId: hitlPaused.threadId,
+                    question: hitlPaused.question,
+                    options: hitlPaused.options,
+                }));
+                if (sessionId) {
+                    await persistHitlWaitingPlaceholder(this.deps.messageService, {
+                        sessionId,
+                        taskId,
+                        correlationId: task.correlationId,
+                        question: hitlPaused.question,
+                        options: hitlPaused.options,
+                        threadId: hitlPaused.threadId,
+                    });
+                }
+                yield this.toSSE('hitl.waited', correlationId, taskId, buildHitlWaitedPayload(hitlPaused));
+                return;
+            }
+            const appErr = err instanceof AppError ? err : AppError.fromUnknown(err);
+            const failMsg = appErr.exposeMessage ? appErr.message : '系统内部错误';
+            await this.deps.taskService.updateStatus(taskId, 'failed', failMsg);
+            yield this.toSSE('task.error', correlationId, taskId, {
+                code: appErr.code,
+                message: failMsg,
+                recoverable: false,
+            });
+            throw err instanceof AppError ? err : appErr;
+        }
+    }
+    /**
+     * 从 Checkpoint Fork 并真实重新执行
+     */
+    async fork(checkpointId, overrides = {}) {
+        const source = await this.deps.checkpointSaver.loadByCheckpointId(checkpointId);
+        if (!source) {
+            throw new AppError(ErrorCodes.HOSTING_CHECKPOINT_NOT_FOUND, `Checkpoint not found: ${checkpointId}`, { exposeMessage: true });
+        }
+        // 优先级：overrides（agentCode > 废弃 agentId）> Checkpoint state
+        const agentCode = overrides.agentCode ??
+            overrides.agentId ??
+            source.state.agentCode ??
+            source.state.agentId ??
+            'unknown-agent';
+        const userId = overrides.userId ?? source.state.userId;
+        const sessionId = overrides.sessionId ?? source.state.sessionId ?? randomUUID();
+        const originalTraceId = overrides.originalTraceId ??
+            source.state.traceId ??
+            source.checkpointId;
+        const newThreadId = randomUUID();
+        const forkedCheckpoint = await this.deps.checkpointSaver.fork(checkpointId, newThreadId, overrides);
+        const correlationId = randomUUID();
+        const task = await this.deps.taskService.create({
+            agentId: agentCode,
+            sessionId,
+            userId,
+            correlationId,
+            input: { forkFrom: checkpointId, overrides },
+            timeout: 600_000,
+        });
+        await this.deps.taskService.updateStatus(task.id, 'running');
+        let newTraceId = randomUUID();
+        if (this.deps.traceCollector) {
+            newTraceId = await this.deps.traceCollector.createFlow({
+                traceId: newTraceId,
+                agentId: agentCode,
+                agentCode,
+                sessionId,
+                userId,
+                correlationId,
+                callType: 'fork',
+                metadata: { checkpointId, originalTraceId },
+            });
+        }
+        const agentVersion = overrides.agentVersion ??
+            (typeof source.state.agentVersion === 'string' ? source.state.agentVersion : undefined);
+        const graph = await this.rebuildExecutableGraph(agentCode, agentVersion);
+        const loadedToolsBase = await this.resolveLoadedTools(agentCode, agentVersion);
+        const skillBundle = await this.resolveLoadedSkills(agentCode, userId, agentVersion);
+        const loadedTools = mergeSkillScriptTools(loadedToolsBase, skillBundle.loadedSkills);
+        try {
+            const result = await this.deps.graphEngine.invoke(graph, {
+                ...forkedCheckpoint.state,
+                agentVersion,
+                userId,
+                delegationToken: overrides.executionContext?.delegationToken,
+                executionContext: overrides.executionContext,
+                loadedTools,
+                ...skillBundle,
+                traceId: newTraceId,
+                traceCollector: this.deps.traceCollector,
+            });
+            await this.deps.taskService.updateStatus(task.id, 'success', result.output);
+            if (this.deps.recordForkRelation) {
+                await this.deps.recordForkRelation({
+                    originalTraceId,
+                    forkedTraceId: newTraceId,
+                    checkpointId,
+                    overrides,
+                });
+            }
+            return {
+                newTraceId,
+                originalTraceId,
+                newTaskId: task.id,
+                checkpointId,
+                status: 'completed',
+                output: result.output,
+                tokenUsage: {
+                    input_tokens: result.tokenUsage.input,
+                    output_tokens: result.tokenUsage.output,
+                    total_tokens: result.tokenUsage.total,
+                },
+                compareUrl: `/traces/compare?traceId1=${originalTraceId}&traceId2=${newTraceId}`,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            await this.deps.taskService.updateStatus(task.id, 'failed', message);
+            return {
+                newTraceId,
+                originalTraceId,
+                newTaskId: task.id,
+                checkpointId,
+                status: 'failed',
+                output: message,
+                tokenUsage: { input_tokens: 0, output_tokens: 0, total_tokens: 0 },
+            };
+        }
+    }
+    async prepareHitlResume(taskId, response) {
+        const task = await this.deps.taskService.getTask(taskId);
+        if (!task) {
+            throw new AppError(ErrorCodes.TASK_NOT_FOUND, `Task not found: ${taskId}`, {
+                exposeMessage: true,
+            });
+        }
+        if (HITL_TERMINAL_STATUSES.includes(task.status)) {
+            throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} is already ${task.status}`, { exposeMessage: true });
+        }
+        const waiting = this.deps.hitlHandler.getWaitingState(taskId);
+        if (!waiting && task.status !== 'waiting_hitl') {
+            throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} is not waiting for HITL`, { exposeMessage: true });
+        }
+        const sessionId = typeof task.sessionId === 'string' && task.sessionId.trim()
+            ? task.sessionId.trim()
+            : undefined;
+        const threadId = waiting?.threadId ??
+            (typeof response.threadId === 'string' && response.threadId.trim()
+                ? response.threadId.trim()
+                : undefined) ??
+            extractHitlThreadId(task.output) ??
+            sessionId;
+        if (!threadId) {
+            throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} 缺少 sessionId/hitlThreadId，无法冷恢复 HITL Checkpoint`, { exposeMessage: true });
+        }
+        const checkpoint = await this.deps.checkpointSaver.load(threadId);
+        const persisted = readPersistedHitlWaiting(checkpoint?.state);
+        const behavior = persisted?.config.timeoutBehavior ?? 'error';
+        if (persisted &&
+            isHitlDeadlinePassed(persisted) &&
+            behavior !== 'auto-confirm') {
+            await this.finalizeHitlTimeout({
+                taskId,
+                threadId,
+                behavior,
+                timeoutMs: persisted.config.timeout ?? 0,
+                question: persisted.config.question,
+                options: persisted.config.options,
+                toolCallId: persisted.toolCallId,
+                toolName: persisted.toolName,
+                toolSpanId: persisted.toolSpanId,
+                skillSpanId: persisted.skillSpanId,
+            });
+            throw new AppError(ErrorCodes.TASK_HITL_TIMEOUT, `Task ${taskId} HITL wait exceeded deadline`, { exposeMessage: true });
+        }
+        return {
+            task,
+            threadId,
+            sessionId,
+            correlationId: task.correlationId || threadId,
+        };
+    }
+    async rebuildExecutableGraph(agentCode, agentVersion) {
+        const graphDsl = this.deps.graphLoader && typeof this.deps.graphLoader.loadGraph === 'function'
+            ? await this.deps.graphLoader.loadGraph(agentCode, { agentVersion })
+            : DEFAULT_GRAPH_DSL;
+        return this.deps.graphEngine.buildGraph(graphDsl);
+    }
+    async handleHitlTimeout(event) {
+        if (event.behavior === 'auto-confirm') {
+            const choice = event.defaultChoice ?? 'confirm';
+            try {
+                for await (const _ of this.streamResumeHitl(event.taskId, {
+                    choice,
+                    userId: '__system_timeout__',
+                    threadId: event.threadId,
+                })) {
+                    // 系统代确认：无客户端 SSE，只把图跑完并落 Task
+                }
+            }
+            catch {
+                await this.finalizeHitlTimeout({ ...event, behavior: 'error' });
+            }
+            return;
+        }
+        await this.finalizeHitlTimeout(event);
+    }
+    async finalizeHitlTimeout(event) {
+        const task = await this.deps.taskService.getTask(event.taskId);
+        if (!task || task.status !== 'waiting_hitl') {
+            return;
+        }
+        const collector = this.deps.traceCollector;
+        const error = event.behavior === 'cancel' ? 'HITL cancelled by timeout' : 'HITL wait timed out';
+        if (collector) {
+            if (event.toolSpanId) {
+                try {
+                    await collector.completeNode(event.toolSpanId, { status: 'failed', error });
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (event.skillSpanId) {
+                try {
+                    await collector.completeNode(event.skillSpanId, { status: 'failed', error });
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        const status = event.behavior === 'cancel' ? 'failed' : 'timeout';
+        try {
+            await this.deps.taskService.updateStatus(event.taskId, status, {
+                hitlTimeout: true,
+                timeoutBehavior: event.behavior,
+                toolCallId: event.toolCallId,
+                toolName: event.toolName,
+                error,
+            });
+        }
+        catch {
+            // 可能已终态
+        }
+    }
+    toSSE(type, correlationId, taskId, data) {
+        return {
+            type,
+            data,
+            correlationId,
+            taskId,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    runtimeEventToSSE(event, correlationId, taskId) {
+        return {
+            type: event.type,
+            data: event.payload,
+            correlationId: event.correlationId ?? correlationId,
+            taskId: event.taskId ?? taskId,
+            timestamp: event.timestamp,
+        };
+    }
+}
+/** 工厂：从运行时依赖组装 AgentRuntime */
+export function createAgentRuntime(deps) {
+    return new AgentRuntime(deps);
+}