@gt-fe/eap-runtime 0.0.8

package/dist/graph/contracts/executable-graph.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Executable Graph 类型定义
+ *
+ * 定义 Graph 引擎核心的可执行图、DSL、节点、边等类型。
+ * 与 @gt-fe/eap-contracts 的 GraphDSL 基础类型互补，在 Runtime 层提供更丰富的类型支持。
+ *
+ * @see design.md §1.4 StateGraph Contract
+ * @see requirements.md Requirement 1 AC1-AC2
+ */
+import type { GraphDSL as BaseGraphDSL, GraphNode as BaseGraphNode, GraphEdge as BaseGraphEdge, GraphNodeType, GraphConfig } from '@gt-fe/eap-contracts';
+export type { GraphNodeType, GraphConfig };
+/**
+ * RuntimeGraphConfig — Runtime 层扩展的 Graph 配置
+ *
+ * 在 @gt-fe/eap-contracts GraphConfig 基础上增加 Runtime 执行所需的 maxRetries。
+ */
+export interface RuntimeGraphConfig extends GraphConfig {
+    /** Graph 级默认重试次数（节点级 retry 可覆盖） */
+    maxRetries?: number;
+}
+/**
+ * GraphNode — Runtime 层扩展的节点定义
+ *
+ * 继承 @gt-fe/eap-contracts 基础 GraphNode，增加 Runtime 执行所需的字段：
+ * - 重试配置（节点级 maxRetries + 退避策略）
+ * - HITL 标记（interrupt_before / interrupt_after）
+ * - 描述信息（调试/Trace 用）
+ */
+export interface GraphNode extends BaseGraphNode {
+    /** 节点显示名称（调试/Trace 用） */
+    label?: string;
+    /** 节点描述 */
+    description?: string;
+    /** 节点级重试配置（覆盖 GraphConfig.maxRetries） */
+    retry?: NodeRetryConfig;
+    /** HITL 中断策略 */
+    interrupt?: NodeInterruptConfig;
+    /** 子图引用 ID（type=subgraph 时必填） */
+    subgraphId?: string;
+    /** 并行分支定义（type=parallel 时使用） */
+    branches?: string[];
+}
+/**
+ * GraphEdge — 基础边定义
+ *
+ * 从源节点到目标节点的连接，可选条件表达式。
+ */
+export interface GraphEdge extends BaseGraphEdge {
+    /** 边的优先级（多条出边时决定评估顺序） */
+    priority?: number;
+}
+/**
+ * ConditionalEdge — 条件路由边
+ *
+ * 对应 LangGraph 的 addConditionalEdges，根据运行时状态动态选择目标节点。
+ * 支持多分支路由和 fallback 默认路径。
+ */
+export interface ConditionalEdge {
+    /** 条件路由的源节点 ID */
+    from: string;
+    /** 条件分支列表 */
+    branches: ConditionalBranch[];
+    /** 条件判断函数名或表达式（DSL 中声明） */
+    conditionFn?: string;
+    /** 无分支匹配时的默认目标节点 */
+    fallback?: string;
+}
+/**
+ * ConditionalBranch — 条件分支定义
+ */
+export interface ConditionalBranch {
+    /** 分支匹配值（conditionFn 返回此值时走此分支） */
+    value: string;
+    /** 目标节点 ID */
+    to: string;
+    /** 分支描述（调试用） */
+    description?: string;
+}
+/**
+ * GraphDSL — Runtime 层扩展的声明式工作流定义
+ *
+ * 扩展 @gt-fe/eap-contracts 的 BaseGraphDSL，增加条件路由、入口/终止节点等。
+ */
+export interface GraphDSL extends Omit<BaseGraphDSL, 'config' | 'nodes' | 'edges'> {
+    /** 覆盖节点类型为 Runtime 扩展版本 */
+    nodes: GraphNode[];
+    /** 覆盖边类型为 Runtime 扩展版本 */
+    edges: GraphEdge[];
+    /** Runtime 扩展配置（含 maxRetries） */
+    config?: RuntimeGraphConfig;
+    /** 条件路由边列表（addConditionalEdges） */
+    conditionalEdges?: ConditionalEdge[];
+    /** 入口节点 ID（默认为 __start__） */
+    entryPoint?: string;
+    /** 终止节点 ID 列表（默认为 __end__） */
+    finishPoints?: string[];
+    /** Graph 描述信息 */
+    description?: string;
+}
+/**
+ * NodeRetryConfig — 节点重试配置
+ *
+ * LLM 节点默认 3 次重试 + 指数退避。
+ * @see design.md Issue#1: 两级重试
+ */
+export interface NodeRetryConfig {
+    /** 最大重试次数（默认 3） */
+    maxRetries: number;
+    /** 退避策略 */
+    backoff?: BackoffStrategy;
+}
+/** 退避策略 */
+export interface BackoffStrategy {
+    /** 策略类型 */
+    type: 'exponential' | 'linear' | 'fixed';
+    /** 基础延迟（毫秒，默认 1000） */
+    baseDelay: number;
+    /** 最大延迟（毫秒，默认 30000） */
+    maxDelay: number;
+    /** 抖动因子（0-1，减少惊群效应） */
+    jitter?: number;
+}
+/**
+ * NodeInterruptConfig — 节点 HITL 中断配置
+ */
+export interface NodeInterruptConfig {
+    /** 在节点执行前暂停 */
+    before?: boolean;
+    /** 在节点执行后暂停 */
+    after?: boolean;
+    /** 暂停时展示给用户的问题 */
+    question?: string;
+    /** 用户可选项 */
+    options?: string[];
+    /** 等待超时（毫秒） */
+    timeout?: number;
+}
+/** 图执行状态 */
+export type GraphExecutionStatus = 'idle' | 'running' | 'paused' | 'completed' | 'failed';
+/**
+ * ExecutableGraph — buildGraph 编译后的可执行图
+ *
+ * 封装已注册节点、边、条件路由等完整执行信息。
+ * 具体内部结构由底层引擎决定，上层只通过 Contract 方法操作。
+ */
+export interface ExecutableGraph {
+    /** 图的唯一标识 */
+    id: string;
+    /** 图名称（来自 DSL） */
+    name: string;
+    /** 图的当前执行状态 */
+    status: GraphExecutionStatus;
+    /** 已注册的节点 ID 列表 */
+    nodeIds: string[];
+    /** 入口节点 ID */
+    entryPoint: string;
+    /** 终止节点 ID 列表 */
+    finishPoints: string[];
+    /** 关联的原始 DSL 版本号 */
+    dslVersion: string;
+    /** 编译时间 (ISO 8601) */
+    compiledAt: string;
+    /** 底层引擎内部实例引用（opaque，由 adapter 管理） */
+    _engineInstance?: unknown;
+}
+import type { ExecutionContext as PlatformExecutionContext } from '@gt-fe/eap-contracts';
+/**
+ * GraphState — 传入 stream/invoke 的上下文数据
+ */
+export interface GraphState {
+    messages: GraphMessage[];
+    userId: string;
+    delegationToken?: string;
+    /** @deprecated 使用 agentCode；仅作旧 Checkpoint 恢复双读兜底，新代码不再写入 */
+    agentId?: string;
+    /** Agent 对外主键 */
+    agentCode?: string;
+    /** Hosting 路由选定的预装版本（AR-3b；写入 Checkpoint 供 HITL/Fork 恢复） */
+    agentVersion?: string;
+    correlationId?: string;
+    taskId?: string;
+    /** 平台执行上下文（06 R16 / 04 R15） */
+    executionContext?: PlatformExecutionContext;
+    /** ExecuteConfig.forceToolServer — 单次 invoke 强制走 Gateway 的 toolName */
+    forceToolServer?: string[];
+    /** GraphLoader 注入：toolName → 运行期 manifest 引用 */
+    loadedTools?: import('../../tool/loaded-tool-definition.js').LoadedToolMap;
+    /** GraphLoader 注入：已装配 Skill 列表（兼容） */
+    loadedSkills?: import('../../tool/system-prompt-builder.js').LoadedSkillInfo[];
+    /** GraphLoader 注入：skillId → 完整定义（子图解析 / prompt） */
+    skillDefinitions?: import('../../tool/system-prompt-builder.js').LoadedSkillMap;
+    /** 当前子图 / 已绑定技能提示词（按 skillId 注入，入口 LLM 读取） */
+    activeSkillPrompt?: string;
+    /** silent LLM 的原始输出；不入对话 messages */
+    silentOutput?: string;
+    /** @deprecated 同 silentOutput，兼容旧图 */
+    skillSelectRaw?: string;
+    /** 解析 graph 内 ./prompts/*.md 的根目录（agentDir + 工程根） */
+    promptRoots?: string[];
+    activatedSkill?: string | null;
+    skillRoute?: string;
+    /** bind / invoke 解析出的 Skill 入参；子图 IO 校验读取 */
+    skillInput?: Record<string, unknown>;
+    /** Hosting 已建 Trace id（与 Foundation traces.id 同值） */
+    traceId?: string;
+    /** Trace 采集器（RT-7；不入 Checkpoint 序列化语义） */
+    traceCollector?: import('../../contracts/trace-collector.js').ITraceCollector;
+    /** 当前 Skill 子图 createNode 返回的 span id；子图内 Tool span 的 parentNodeId */
+    skillSpanId?: string;
+    /**
+     * HITL 续跑：入口 messages 以 __set 覆盖 checkpoint 历史，避免 append 重复。
+     * 仅 stream/invoke 入口使用，不入持久化语义。
+     */
+    replaceCheckpointMessages?: boolean;
+    [key: string]: unknown;
+}
+/** Graph 内部消息格式 */
+export interface GraphMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    toolCalls?: ToolCallInfo[];
+    /** tool 角色消息的工具名称（由 adapter 填充） */
+    toolName?: string;
+    /** tool 角色消息对应的 tool call ID */
+    toolCallId?: string;
+    /** tool 执行是否成功 */
+    success?: boolean;
+    /**
+     * DeepSeek 等 thinking 模式的 reasoning_content。
+     * 多轮请求必须原样回传，否则上游会 400。
+     */
+    reasoningContent?: string;
+    /** 工具产出的文件；仅 Runtime 发 file.created，不进模型正文 */
+    file?: {
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    };
+}
+/** Tool 调用信息 */
+export interface ToolCallInfo {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * RuntimeEvent — stream 方法产出的事件流元素
+ *
+ * 对应 SSE 事件协议中的各类事件（约 30 种），
+ * 由 Contract stream 方法 yield，经 SSE Emitter 推送给客户端。
+ */
+export interface RuntimeEvent {
+    /** 事件类型（如 response.chunk, tool.called 等） */
+    type: string;
+    /** 关联的 Task ID */
+    taskId?: string;
+    /** 请求关联 ID */
+    correlationId?: string;
+    /** 事件时间戳 (ISO 8601) */
+    timestamp: string;
+    /** 事件负载 */
+    payload: Record<string, unknown>;
+}
+/**
+ * CheckpointData — 图执行状态的可持久化快照
+ /**
+  * 包含恢复执行所需的全部信息：当前节点、历史路径、完整 State。
+  */
+export interface CheckpointData {
+    /** Checkpoint 唯一 ID */
+    checkpointId: string;
+    /** 所属线程 ID（一个 Task 对应一个 thread） */
+    threadId: string;
+    /** 暂停时所在的节点 ID */
+    currentNodeId: string;
+    /** 已执行的节点历史路径 */
+    historyPath: string[];
+    /** 完整的 Graph State 快照 */
+    state: GraphState;
+    /**
+     * LangGraph 引擎原生 Checkpoint 快照（含 pending_sends / channel_versions 等）。
+     * 回读时优先使用，避免同 thread 多轮出现 `pending_sends is not iterable`。
+     */
+    engineSnapshot?: Record<string, unknown>;
+    /** 创建人 */
+    createdBy: string;
+    /** 快照创建时间 (ISO 8601) */
+    createdAt: string;
+    /** 最后更新人 */
+    updatedBy: string;
+    /** 最后更新时间 (ISO 8601) */
+    updatedAt: string;
+    /** 是否删除（软删除标记） */
+    isDeleted: boolean;
+    /** 删除人 */
+    deletedBy?: string | null;
+    /** 删除时间 (ISO 8601) */
+    deletedAt?: string | null;
+}
+/**
+ * GraphResult — invoke 方法的返回值
+ *
+ * 同步调用结束后返回的完整结果。
+ */
+export interface GraphResult {
+    /** 最终输出内容 */
+    output: string;
+    /** 执行结束后的完整 State */
+    finalState: GraphState;
+    /** 本次执行的 Token 消耗汇总 */
+    tokenUsage: GraphTokenUsage;
+    /** 执行耗时（毫秒） */
+    duration: number;
+}
+/** Graph 级 Token 消耗汇总
+ *
+ * - input/output/total：单次 invoke/stream 请求内所有 LLM 轮次的累计消耗
+ * - perNode：按 LLM 节点维度的明细数组（每次 LLM 调用一条）
+ * - conversationTotal（可选）：当前会话（跨请求）累计消耗，由 session 层服务填充
+ */
+export interface GraphTokenUsage {
+    input: number;
+    output: number;
+    total: number;
+    /** 每个 LLM 节点的 token 明细（多轮对话会有多条） */
+    perNode?: Array<{
+        nodeId: string;
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+    }>;
+    /** 当前会话跨请求累计消耗（可选；由 session 层服务填充） */
+    conversationTotal?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+}
+export type { IStateGraphEngine } from './state-graph.contract.js';

package/dist/graph/contracts/executable-graph.js

@@ -0,0 +1,10 @@
+/**
+ * Executable Graph 类型定义
+ *
+ * 定义 Graph 引擎核心的可执行图、DSL、节点、边等类型。
+ * 与 @gt-fe/eap-contracts 的 GraphDSL 基础类型互补，在 Runtime 层提供更丰富的类型支持。
+ *
+ * @see design.md §1.4 StateGraph Contract
+ * @see requirements.md Requirement 1 AC1-AC2
+ */
+export {};

package/dist/graph/contracts/index.d.ts

@@ -0,0 +1,2 @@
+export * from './executable-graph.js';
+export * from './state-graph.contract.js';

package/dist/graph/contracts/index.js

@@ -0,0 +1,2 @@
+export * from './executable-graph.js';
+export * from './state-graph.contract.js';

package/dist/graph/contracts/state-graph.contract.d.ts

@@ -0,0 +1,76 @@
+/**
+ * StateGraph Contract — 平台 Graph 引擎抽象接口
+ *
+ * 定义 Graph 执行引擎的核心 Contract，确保底层引擎可插拔替换。
+ * v1 实现使用 LangGraph.js（见 adapters/langgraph.adapter.ts），
+ * 后续可替换为其他 Graph 引擎，只需实现本接口即可。
+ *
+ * @see requirements.md Requirement 1 AC5
+ * @see design.md §1.4 StateGraph Contract
+ */
+import type { ExecutableGraph, GraphDSL, GraphState, RuntimeEvent, CheckpointData, GraphResult } from './executable-graph.js';
+export type { ExecutableGraph, GraphDSL, GraphState, GraphMessage, ToolCallInfo, RuntimeEvent, CheckpointData, GraphResult, GraphTokenUsage, GraphExecutionStatus, } from './executable-graph.js';
+/**
+ * IStateGraphEngine — StateGraph 引擎 Contract
+ *
+ * 平台 Graph 执行引擎的抽象接口。所有 Graph 引擎实现（LangGraph.js、自研引擎等）
+ * 必须实现此接口，以保证底层引擎可插拔替换。
+ *
+ * 核心方法：
+ * - buildGraph: 将声明式 DSL 编译为可执行图
+ * - stream: 流式驱动图执行，逐步产出事件
+ * - invoke: 同步执行，等待完整结果
+ * - checkpoint: 从运行中的图提取状态快照
+ * - restore: 从快照恢复图执行
+ */
+export interface IStateGraphEngine {
+    /**
+     * 解析 Graph DSL 并构建可执行图
+     *
+     * 将 YAML/JSON 声明式工作流定义编译为引擎可执行的内部表示，
+     * 包括注册节点函数、添加边和条件路由、配置 Checkpoint 等。
+     *
+     * @param dsl - Graph DSL 定义（来自 graph.yaml 或 graph.json）
+     * @returns 编译后的可执行图实例
+     */
+    buildGraph(dsl: GraphDSL): Promise<ExecutableGraph>;
+    /**
+     * 流式驱动图执行，实时产出各节点的执行事件
+     *
+     * 以 AsyncIterableIterator 方式逐步 yield 事件（供 SSE/Trace 采集），
+     * 直到图到达终止节点或被中断。
+     *
+     * @param graph - 已构建的可执行图
+     * @param state - 初始执行状态（含消息历史、用户上下文等）
+     * @returns 异步可迭代的事件流
+     */
+    stream(graph: ExecutableGraph, state: GraphState): AsyncIterableIterator<RuntimeEvent>;
+    /**
+     * 同步调用图执行，等待完整结果返回
+     *
+     * 适用于简单任务场景，阻塞等待图执行完毕后返回最终结果。
+     *
+     * @param graph - 已构建的可执行图
+     * @param state - 初始执行状态
+     * @returns 执行结果（含 output、finalState、tokenUsage）
+     */
+    invoke(graph: ExecutableGraph, state: GraphState): Promise<GraphResult>;
+    /**
+     * 从运行中的图提取 Checkpoint（状态快照）
+     *
+     * 用于 HITL 暂停、断线恢复等场景，将当前执行进度持久化。
+     *
+     * @param graph - 当前运行中的可执行图
+     * @returns Checkpoint 数据（含当前节点、历史路径、完整 State）
+     */
+    checkpoint(graph: ExecutableGraph): CheckpointData;
+    /**
+     * 从 Checkpoint 数据恢复可执行图
+     *
+     * 供断点恢复、HITL 继续、Replay/Fork（05-Trace 模块）等场景使用。
+     *
+     * @param checkpointData - 之前保存的 Checkpoint 快照
+     * @returns 恢复后的可执行图，可继续执行
+     */
+    restore(checkpointData: CheckpointData): Promise<ExecutableGraph>;
+}

package/dist/graph/contracts/state-graph.contract.js

@@ -0,0 +1,11 @@
+/**
+ * StateGraph Contract — 平台 Graph 引擎抽象接口
+ *
+ * 定义 Graph 执行引擎的核心 Contract，确保底层引擎可插拔替换。
+ * v1 实现使用 LangGraph.js（见 adapters/langgraph.adapter.ts），
+ * 后续可替换为其他 Graph 引擎，只需实现本接口即可。
+ *
+ * @see requirements.md Requirement 1 AC5
+ * @see design.md §1.4 StateGraph Contract
+ */
+export {};

package/dist/graph/hitl/hitl-handler.d.ts

@@ -0,0 +1,199 @@
+/**
+ * HITL (Human-In-The-Loop) Handler
+ *
+ * 实现人工介入的中断、恢复、超时逻辑。
+ * 当 Graph 到达 HITL 节点时暂停执行，等待人工确认后继续。
+ *
+ * 超时不得在 setTimeout 回调里 throw（会变成未捕获异常）；
+ * 由 AgentRuntime 监听器关 Task / Span。deadline 写入 Checkpoint，冷恢复可校验。
+ *
+ * @see design.md §1.6 hitl.waiting / hitl.resumed 事件
+ * @see tasks.md Task 14
+ */
+import type { ICheckpointSaver } from '../../checkpoint/contracts/checkpoint-saver.contract.js';
+import type { ISSEEmitter } from '../../sse/contracts/sse-emitter.contract.js';
+import type { GraphState } from '../contracts/executable-graph.js';
+/** HITL 默认等待时长（毫秒）= 300 秒。SSE `hitl.waited.timeout` 对外用秒。 */
+export declare const DEFAULT_HITL_TIMEOUT_MS = 300000;
+/** HITL 超时行为 */
+export type HitlTimeoutBehavior = 'error' | 'cancel' | 'auto-confirm';
+/** HITL 中断配置 */
+export interface HitlInterruptConfig {
+    /** 展示给用户的确认问题 */
+    question: string;
+    /** 可选项列表 */
+    options: string[];
+    /** 等待超时（毫秒），默认 300000 (5min) */
+    timeout?: number;
+    /** 超时后执行的行为，默认 error */
+    timeoutBehavior?: HitlTimeoutBehavior;
+    /** 超时自动确认时使用的默认选项 */
+    defaultOption?: string;
+}
+/** interrupt 时附带的 Tool/Span 对账信息（确认类 Tool 路径） */
+export interface HitlInterruptExtras {
+    toolCallId?: string;
+    toolName?: string;
+    toolSpanId?: string;
+    skillSpanId?: string;
+}
+/** HITL 等待中状态（内存中维护） */
+export interface HitlWaitingState {
+    taskId: string;
+    threadId: string;
+    config: HitlInterruptConfig;
+    /** 超时定时器引用 */
+    timer: ReturnType<typeof setTimeout> | null;
+    /** 中断时间 */
+    interruptedAt: string;
+    deadlineAt: string;
+    toolCallId?: string;
+    toolName?: string;
+    toolSpanId?: string;
+    skillSpanId?: string;
+}
+/** HITL 超时错误（保留类型；timer 不再 throw，resume 逾期改走 AppError） */
+export declare class HitlTimeoutError extends Error {
+    readonly taskId: string;
+    readonly timeoutMs: number;
+    constructor(taskId: string, timeoutMs: number);
+}
+/** Checkpoint 已标记超时，禁止再 resume */
+export declare class HitlAlreadyTimedOutError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+/** 内存与 Checkpoint 都没有等待态（已被 resume/timeout 抢走） */
+export declare class HitlNotWaitingError extends Error {
+    readonly taskId: string;
+    constructor(taskId: string);
+}
+export declare function isHitlDecision(choice: unknown): choice is 'confirm' | 'reject';
+/** 最后一条 assistant 仍有未配对的 toolCalls（HITL 暂停后尚未 result/error） */
+export declare function lastAssistantHasUnansweredToolCalls(messages: Array<{
+    role?: string;
+    toolCalls?: Array<{
+        id?: string;
+    }>;
+    toolCallId?: string;
+}>): boolean;
+/**
+ * HITL 已中断、等待外部 resume（非阻塞）
+ *
+ * Tool 确认节点 interrupt 后抛出本错误，由 invoke/stream 捕获并返回 waiting_hitl，
+ * 客户端再通过 POST .../hitl 或 streamResumeHitl 继续。
+ */
+export declare class HitlPausedError extends Error {
+    readonly taskId: string;
+    readonly threadId: string;
+    readonly question: string;
+    readonly options: string[];
+    readonly toolCallId?: string | undefined;
+    readonly toolName?: string | undefined;
+    readonly timeoutMs: number;
+    toolSpanId?: string;
+    skillSpanId?: string;
+    constructor(taskId: string, threadId: string, question: string, options: string[], toolCallId?: string | undefined, toolName?: string | undefined, timeoutMs?: number);
+}
+/**
+ * 向上解包 HitlPausedError（LangGraph / Promise 可能挂在 `.cause`）
+ */
+export declare function unwrapHitlPaused(error: unknown): HitlPausedError | null;
+/** Checkpoint state 中持久化的 HITL 等待元数据（进程重启 / 无内存 Map 时冷恢复） */
+export declare const HITL_WAITING_STATE_KEY = "__hitlWaiting";
+export interface PersistedHitlWaiting {
+    taskId: string;
+    threadId: string;
+    config: HitlInterruptConfig;
+    interruptedAt: string;
+    /** ISO；超过后 resume 拒绝，按 timeoutBehavior 收口 */
+    deadlineAt: string;
+    toolCallId?: string;
+    toolName?: string;
+    toolSpanId?: string;
+    skillSpanId?: string;
+    /** error/cancel 超时已占用此等待；resume 必须拒绝 */
+    timedOut?: boolean;
+}
+/** 超时回调（AgentRuntime 注册：关 Task / Span，或 auto-confirm 续跑） */
+export interface HitlTimeoutEvent {
+    taskId: string;
+    threadId: string;
+    behavior: HitlTimeoutBehavior;
+    timeoutMs: number;
+    question: string;
+    options: string[];
+    defaultChoice?: string;
+    toolCallId?: string;
+    toolName?: string;
+    toolSpanId?: string;
+    skillSpanId?: string;
+}
+export type HitlTimeoutListener = (event: HitlTimeoutEvent) => Promise<void>;
+export declare function toHitlTimeoutMs(timeoutMs?: number): number;
+/** SSE `hitl.waited.data.timeout`：秒 */
+export declare function toHitlTimeoutSeconds(timeoutMs?: number): number;
+export declare function isHitlDeadlinePassed(persisted: Pick<PersistedHitlWaiting, 'deadlineAt'> | undefined, now?: number): boolean;
+export declare function readPersistedHitlWaiting(state: unknown): PersistedHitlWaiting | undefined;
+/** 门面 stream / HTTP StreamOrchestrator / streamResumeHitl 共用 */
+export declare function buildHitlWaitedPayload(paused: HitlPausedError): {
+    question: string;
+    options: string[];
+    threadId: string;
+    timeout: number;
+    toolCallId?: string;
+    toolName?: string;
+};
+/**
+ * HitlHandler — 管理 HITL 中断/恢复/超时
+ *
+ * 职责：
+ * - interrupt: 保存 checkpoint + 发射 hitl.waiting + 启动超时计时
+ * - resume: 加载 checkpoint + 注入用户选择 + 发射 hitl.resumed
+ * - handleTimeout: 不 throw；回调 listener（error/cancel 收口，auto-confirm 续跑）
+ */
+export declare class HitlHandler {
+    private readonly checkpointSaver;
+    private readonly sseEmitter;
+    /** taskId → waiting state */
+    private waitingTasks;
+    /** resume 后暂存的用户选择（供 ToolConfirmationInterceptor 轮询读取） */
+    private resolvedChoices;
+    private timeoutListener?;
+    /** 同一 taskId 上串行化 resume 与 timeout，避免双边占用 */
+    private taskLocks;
+    constructor(checkpointSaver: ICheckpointSaver, sseEmitter: ISSEEmitter, timeoutListener?: HitlTimeoutListener);
+    setTimeoutListener(listener: HitlTimeoutListener | undefined): void;
+    /**
+     * 中断 Graph 执行，等待人工确认
+     *
+     * 写入 `__hitlWaiting`（含 deadlineAt）到同一 thread 的 Checkpoint。
+     * 不保留 LangGraph `engineSnapshot`：子图与父图共用 session thread，
+     * resume 时用 GraphState 从父图入口重入（skillSpanId / hitlChoice 防重复 span）。
+     */
+    interrupt(taskId: string, threadId: string, state: GraphState, config: HitlInterruptConfig, extras?: HitlInterruptExtras): Promise<void>;
+    /**
+     * 用户响应后恢复执行
+     *
+     * 优先用进程内 waitingTasks；若进程重启丢失，可用 threadId 从 Checkpoint 冷恢复
+     *（interrupt 时已写入 `__hitlWaiting`）。
+     *
+     * @returns 注入用户选择后的 GraphState
+     */
+    resume(taskId: string, choice: string, userId: string, threadIdHint?: string): Promise<GraphState>;
+    /**
+     * 超时处理入口（同步包装）。timer 回调不得 throw。
+     */
+    handleTimeout(taskId: string): void;
+    handleTimeoutAsync(taskId: string): Promise<void>;
+    private clearWaiting;
+    private withTaskLock;
+    /** 查询某 task 是否在等待 HITL */
+    isWaiting(taskId: string): boolean;
+    /** 获取等待状态（测试/调试用） */
+    getWaitingState(taskId: string): HitlWaitingState | undefined;
+    /**
+     * 取出并清除 resume 写入的用户选择（确认拦截器轮询用）
+     */
+    consumeResolvedChoice(taskId: string): string | undefined;
+}