@gt-fe/eap-runtime 0.0.22 → 0.0.24

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

@@ -22,6 +22,7 @@ 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 { InvokeRequest, InvokeResponse } from '../routes/agent.routes.js';
+import type { TaskTimeoutManager } from '../../task/task-timeout.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';
@@ -46,6 +47,8 @@ export interface InvokeOrchestratorDeps {
     traceCollector?: ITraceCollector;
     sessionCompression?: SessionCompressionOptions;
     sessionMemory?: SessionMemoryOptions;
+    /** 未注入时不启动整图超时（测试桩） */
+    timeoutManager?: TaskTimeoutManager;
 }
 /**
  * InvokeOrchestrator — 同步调用全流程编排
@@ -66,6 +69,7 @@ export declare class InvokeOrchestrator {
     private readonly traceCollector?;
     private readonly sessionCompression?;
     private readonly sessionMemory?;
+    private readonly timeoutManager?;
     constructor(deps: InvokeOrchestratorDeps);
     /**
      * 执行同步调用编排

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

@@ -21,6 +21,11 @@ import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
 import { recordTaskTokenUsages, tokenUsagesFromLlmChannel, } from '../../token/record-task-token-usage.js';
 import { resolveExecutionContext } from '../../governance/governance-client.js';
 import { resolveSkillInputFromInvokeInput } from '../../registry/skill-io-guard.js';
+import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
+import { classifyRuntimeError } from '../../utils/http-error.js';
+import { DEFAULT_GRAPH_TIMEOUT_MS } from '../../common/types.js';
+import { resolveTaskTimeoutMs } from '../../task/resolve-task-timeout.js';
+import { runWithExecutionTrace } from '../../graph/execution-trace-context.js';
 import { resolveAgentSystemPromptFromLoader } from '../../registry/graph-loader.js';
 import { toLoadedToolMap } from '../../tool/loaded-tool-definition.js';
 import { toLoadedSkillMap } from '../../tool/system-prompt-builder.js';
@@ -44,7 +49,7 @@ const DEFAULT_GRAPH_DSL = {
         { from: '__start__', to: 'llm' },
         { from: 'llm', to: '__end__' },
     ],
-    config: { timeout: 60000 },
+    config: { timeout: DEFAULT_GRAPH_TIMEOUT_MS },
 };
 // ─────────────────────────────────────────────
 // InvokeOrchestrator
@@ -68,6 +73,7 @@ export class InvokeOrchestrator {
     traceCollector;
     sessionCompression;
     sessionMemory;
+    timeoutManager;
     constructor(deps) {
         this.sessionContextService = deps.sessionContextService;
         this.taskService = deps.taskService;
@@ -81,6 +87,7 @@ export class InvokeOrchestrator {
         this.traceCollector = deps.traceCollector;
         this.sessionCompression = deps.sessionCompression;
         this.sessionMemory = deps.sessionMemory;
+        this.timeoutManager = deps.timeoutManager;
     }
     /**
      * 执行同步调用编排
@@ -143,8 +150,12 @@ export class InvokeOrchestrator {
                 throw error;
             }
         }
-        // ─── Step 3: 创建 Task（Hosting 传入 taskId 时复用）───
-        const timeout = req.config?.timeout ?? 60000;
+        // ─── Step 3: 加载图并创建 Task（Hosting 传入 taskId 时复用）───
+        const loadOpts = { agentVersion: req.agentVersion };
+        const graphDsl = this.graphLoader
+            ? await this.graphLoader.loadGraph(agentCode, loadOpts)
+            : DEFAULT_GRAPH_DSL;
+        const timeout = resolveTaskTimeoutMs(req.config?.timeout, graphDsl.config?.timeout);
         const task = await this.taskService.create({
             id: req.taskId,
             agentId: agentCode,
@@ -156,6 +167,9 @@ export class InvokeOrchestrator {
         });
         // ─── Step 4: 启动 Task (pending → running) ───
         await this.taskService.updateStatus(task.id, 'running');
+        const abortSignal = this.timeoutManager?.startTimer(task.id, timeout, async () => {
+            await this.taskService.tryUpdateStatus(task.id, 'running', 'timeout', 'Task execution timed out');
+        });
         // ─── Step 4b: 持久化本轮 user（多轮短期记忆）───
         await persistUserTurnMessage(this.messageService, {
             sessionId,
@@ -168,10 +182,6 @@ export class InvokeOrchestrator {
         let finishPoints;
         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);
             finishPoints = graph.finishPoints;
             const loadedToolsBase = this.graphLoader
@@ -216,7 +226,7 @@ export class InvokeOrchestrator {
             });
             const skillInput = resolveSkillInputFromInvokeInput(req.input);
             // 同步执行图
-            graphResult = await this.graphEngine.invoke(graph, {
+            graphResult = await runWithExecutionTrace({ abortSignal }, () => this.graphEngine.invoke(graph, {
                 messages,
                 userId: effectiveUserId,
                 delegationToken: ctx.delegationToken,
@@ -238,7 +248,9 @@ export class InvokeOrchestrator {
                 agentSystemPrompt,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
-            });
+                abortSignal,
+                abortDeadlineMs: Date.now() + timeout,
+            }));
         }
         catch (error) {
             const usages = await this.persistInvokeUsages(task.id, sessionId);
@@ -286,7 +298,7 @@ export class InvokeOrchestrator {
             }
             // ─── 错误处理：Timeout ───
             if (this.isTimeoutError(error)) {
-                await this.taskService.updateStatus(task.id, 'timeout');
+                await this.taskService.tryUpdateStatus(task.id, 'running', 'timeout');
                 return this.buildResponse(traceId, {
                     taskId: task.id,
                     sessionId,
@@ -297,7 +309,9 @@ export class InvokeOrchestrator {
                 });
             }
             // ─── 错误处理：通用错误 ───
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            const classified = classifyRuntimeError(error);
+            const fuse = classified.code === ErrorCodes.GRAPH_MAX_ITERATIONS ? classified : undefined;
+            const errorMessage = fuse?.message ?? (error instanceof Error ? error.message : 'Unknown error');
             await this.taskService.updateStatus(task.id, 'failed', errorMessage);
             return this.buildErrorResponse(traceId, {
                 taskId: task.id,
@@ -306,7 +320,10 @@ export class InvokeOrchestrator {
                 tokenUsage,
                 duration: Date.now() - startTime,
                 status: 'failed',
-            });
+            }, fuse ?? error);
+        }
+        finally {
+            this.timeoutManager?.clearTimer(task.id);
         }
         // ─── Step 6: 记录 Token 消耗 ───
         //
@@ -387,15 +404,17 @@ export class InvokeOrchestrator {
     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 };
+    buildErrorResponse(traceId, data, error) {
+        if (data.status === 'token_exhausted') {
+            return { code: 'runtime.budget.task_exhausted', data, traceId };
+        }
+        if (error instanceof AppError) {
+            return { code: error.code, data, traceId };
+        }
+        return { code: '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;
+        return error instanceof Error && /timed out/i.test(error.message);
     }
     async persistInvokeUsages(taskId, sessionId) {
         if (!this.checkpointSaver)

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

@@ -33,6 +33,7 @@ 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';
+import type { TaskTimeoutManager } from '../../task/task-timeout.js';
 /**
  * StreamOrchestrator 构造器依赖
  */
@@ -52,6 +53,8 @@ export interface StreamOrchestratorDeps {
     traceCollector?: ITraceCollector;
     sessionCompression?: SessionCompressionOptions;
     sessionMemory?: SessionMemoryOptions;
+    /** 未注入时不启动整图超时（测试桩） */
+    timeoutManager?: TaskTimeoutManager;
 }
 /**
  * StreamOrchestrator — 流式调用全流程编排
@@ -72,6 +75,7 @@ export declare class StreamOrchestrator {
     private readonly traceCollector?;
     private readonly sessionCompression?;
     private readonly sessionMemory?;
+    private readonly timeoutManager?;
     constructor(deps: StreamOrchestratorDeps);
     /**
      * 执行流式调用编排

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

@@ -39,6 +39,9 @@ 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';
+import { DEFAULT_GRAPH_TIMEOUT_MS } from '../../common/types.js';
+import { resolveTaskTimeoutMs } from '../../task/resolve-task-timeout.js';
+import { runWithExecutionTrace } from '../../graph/execution-trace-context.js';
 // ─────────────────────────────────────────────
 // Placeholder Graph DSL (Agent Registry 接入前)
 // ─────────────────────────────────────────────
@@ -53,7 +56,7 @@ const DEFAULT_GRAPH_DSL = {
         { from: '__start__', to: 'llm' },
         { from: 'llm', to: '__end__' },
     ],
-    config: { timeout: 60000 },
+    config: { timeout: DEFAULT_GRAPH_TIMEOUT_MS },
 };
 // ─────────────────────────────────────────────
 // StreamOrchestrator
@@ -77,6 +80,7 @@ export class StreamOrchestrator {
     traceCollector;
     sessionCompression;
     sessionMemory;
+    timeoutManager;
     constructor(deps) {
         this.sessionContextService = deps.sessionContextService;
         this.taskService = deps.taskService;
@@ -90,6 +94,7 @@ export class StreamOrchestrator {
         this.traceCollector = deps.traceCollector;
         this.sessionCompression = deps.sessionCompression;
         this.sessionMemory = deps.sessionMemory;
+        this.timeoutManager = deps.timeoutManager;
     }
     /**
      * 执行流式调用编排
@@ -166,8 +171,12 @@ export class StreamOrchestrator {
                 userId,
             }));
         }
-        // ─── Step 3: 创建 Task（Hosting 传入 taskId 时复用）───
-        const timeout = req.config?.timeout ?? 60000;
+        // ─── Step 3: 加载图并创建 Task（Hosting 传入 taskId 时复用）───
+        const loadOpts = { agentVersion: req.agentVersion };
+        const graphDsl = this.graphLoader
+            ? await this.graphLoader.loadGraph(agentCode, loadOpts)
+            : DEFAULT_GRAPH_DSL;
+        const timeout = resolveTaskTimeoutMs(req.config?.timeout, graphDsl.config?.timeout);
         const task = await this.taskService.create({
             id: req.taskId,
             agentId: agentCode,
@@ -180,6 +189,9 @@ export class StreamOrchestrator {
         const taskId = task.id;
         // ─── Step 4: 启动 Task (pending → running) ───
         await this.taskService.updateStatus(taskId, 'running');
+        const abortSignal = this.timeoutManager?.startTimer(taskId, timeout, async () => {
+            await this.taskService.tryUpdateStatus(taskId, 'running', 'timeout', 'Task execution timed out');
+        });
         // ─── Step 4b: 持久化本轮 user（多轮短期记忆）───
         await persistUserTurnMessage(this.messageService, {
             sessionId,
@@ -193,10 +205,6 @@ export class StreamOrchestrator {
             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))
@@ -253,7 +261,7 @@ export class StreamOrchestrator {
         const toolResults = [];
         // ─── Step 6: Graph.stream() 流式执行 ───
         try {
-            const eventStream = this.graphEngine.stream(graph, {
+            const eventStream = runWithExecutionTrace({ abortSignal }, () => this.graphEngine.stream(graph, {
                 messages,
                 userId,
                 delegationToken: executionContext.delegationToken,
@@ -275,7 +283,9 @@ export class StreamOrchestrator {
                 agentSystemPrompt,
                 traceId: resolveTraceId(req),
                 traceCollector: this.traceCollector,
-            });
+                abortSignal,
+                abortDeadlineMs: Date.now() + timeout,
+            }));
             // 逐事件转发到 SSE；顺带把节点 token 记入 TokenStatsService（stream 原先未 record → 结尾全 0）
             for await (const runtimeEvent of eventStream) {
                 // 连接已断开则提前退出
@@ -347,7 +357,7 @@ export class StreamOrchestrator {
             // ─── 错误处理：Timeout ───
             if (this.isTimeoutError(error)) {
                 await recordTaskTokenUsages(this.taskService, taskId, this.tokenStatsService.list(taskId));
-                await this.taskService.updateStatus(taskId, 'timeout');
+                await this.taskService.tryUpdateStatus(taskId, 'running', 'timeout');
                 emitter.emit(this.buildSSEEvent('task.error', correlationId, taskId, {
                     code: ErrorCodes.TASK_TIMEOUT,
                     message: 'Task execution timed out',
@@ -363,6 +373,9 @@ export class StreamOrchestrator {
             this.emitErrorAndClose(emitter, correlationId, taskId, error);
             return;
         }
+        finally {
+            this.timeoutManager?.clearTimer(taskId);
+        }
         // ─── Step 7: 发送结束事件序列 ───
         // Emit: response.final（带完整 assistant 文本，供客户端兜底）
         const tokenStats = this.tokenStatsService.getTaskStats(taskId);
@@ -454,10 +467,6 @@ export class StreamOrchestrator {
         emitter.close();
     }
     isTimeoutError(error) {
-        if (error instanceof Error) {
-            const msg = error.message.toLowerCase();
-            return msg.includes('timeout') || msg.includes('timed out');
-        }
-        return false;
+        return error instanceof Error && /timed out/i.test(error.message);
     }
 }

package/dist/api/routes/agent.routes.js

@@ -3,6 +3,7 @@
  *
  * 生产环境由 Hosting 提供对外 HTTP；本模块供 `EAP_DEV_HTTP=1` 本地调试。
  */
+import { classifyRuntimeError } from '../../utils/http-error.js';
 // ─────────────────────────────────────────────
 // Route Handlers
 // ─────────────────────────────────────────────
@@ -85,18 +86,18 @@ export function createAgentRouteHandlers(deps) {
             };
         }
         catch (error) {
-            // 错误处理
             const duration = Date.now() - startTime;
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            const classified = classifyRuntimeError(error);
+            const output = classified.exposeMessage ? classified.message : '系统内部错误';
             return {
-                code: 'runtime.graph.execution_error',
+                code: classified.code,
                 data: {
                     taskId: '',
                     sessionId: sessionId ?? '',
-                    output: '',
+                    output,
                     tokenUsage: { input: 0, output: 0, total: 0 },
                     duration,
-                    status: 'failed',
+                    status: classified.code === 'runtime.task.timeout' ? 'timeout' : 'failed',
                 },
                 traceId: '',
             };

package/dist/checkpoint/checkpoint-ref-notify.js

@@ -12,7 +12,7 @@ function pickString(...values) {
     return undefined;
 }
 function omitTraceCollector(record) {
-    const { traceCollector: _drop, ...rest } = record;
+    const { traceCollector: _drop, abortSignal: _abort, abortDeadlineMs: _deadline, ...rest } = record;
     return rest;
 }
 /** 去掉不可序列化的 collector，再交给 Saver。 */

package/dist/common/types.d.ts

@@ -12,6 +12,8 @@
  * - detail: 每次 LLM 调用输出 stats.node_token_usage + 结束时汇总
  */
 export type TokenDetailLevel = 'none' | 'summary' | 'detail';
+/** 未写请求/图 timeout 时的整图缺省（毫秒）。20 分钟，须大于单次 LLM HTTP 缺省 180s。 */
+export declare const DEFAULT_GRAPH_TIMEOUT_MS = 1200000;
 /**
  * Runtime 执行引擎配置
  *
@@ -20,9 +22,11 @@ export type TokenDetailLevel = 'none' | 'summary' | 'detail';
 export interface RuntimeConfig {
     /** Token 统计输出粒度 */
     tokenDetail: TokenDetailLevel;
-    /** Task 执行超时时间（毫秒） */
+    /** Task 执行超时时间（毫秒）。未写请求/图 timeout 时为 {@link DEFAULT_GRAPH_TIMEOUT_MS} */
     timeout: number;
-    /** ReAct 循环最大迭代次数 */
+    /**
+     * @deprecated Runtime 忽略。图级 / 请求级步数不是限长手段。整图限长用 timeout。
+     */
     maxIterations: number;
     /** SSE 心跳间隔（毫秒），默认 30000 */
     heartbeatInterval: number;

package/dist/common/types.js

@@ -5,10 +5,12 @@
  * - @gt-fe/eap-contracts 定义跨模块的公共协议（如 Task 实体、Session 实体、Agent Manifest）
  * - 本文件定义 Runtime 执行引擎内部流转的配置、上下文、枚举等
  */
+/** 未写请求/图 timeout 时的整图缺省（毫秒）。20 分钟，须大于单次 LLM HTTP 缺省 180s。 */
+export const DEFAULT_GRAPH_TIMEOUT_MS = 1_200_000;
 /** RuntimeConfig 默认值 */
 export const DEFAULT_RUNTIME_CONFIG = {
     tokenDetail: 'detail',
-    timeout: 60000,
+    timeout: DEFAULT_GRAPH_TIMEOUT_MS,
     maxIterations: 10,
     heartbeatInterval: 30000,
 };

package/dist/graph/adapters/langgraph.adapter.d.ts

@@ -17,12 +17,14 @@ import type { IToolExecutor } from '../../tool/tool-executor.interface.js';
 import type { IGovernanceClient } from '../../governance/governance-client.js';
 import { type ConditionEvaluatorFn } from '../condition-evaluator.js';
 import type { ExecutionInterceptors } from '../../execution/interceptors.js';
-/** 图未写 `config.maxIterations` 时的 recursionLimit。`agent ⇄ tools` 一圈约 2，50 ≈ 24 次工具往返。 */
-export declare const DEFAULT_GRAPH_RECURSION_LIMIT = 50;
 /**
- * LangGraph `recursionLimit` 计 superstep（每进一个节点 +1），不是 ReAct 圈数。
- * 图上 `config.maxIterations` 优先；缺省 {@link DEFAULT_GRAPH_RECURSION_LIMIT}。
+ * 传给 LangGraph 的 `recursionLimit`：一轮调度（superstep）+1。
+ * 同一步里并行的多个节点只 +1。ReAct 的 llm 再 tool 大约 +2。
+ * 不读图级 / 请求级 `maxIterations`。整图运行时长用 `timeout`。
+ * 配了 Token 配额才会因预算停止。
  */
+export declare const DEFAULT_GRAPH_RECURSION_LIMIT = 5000;
+export declare function isGraphRecursionError(error: unknown): boolean;
 /** 并行节点各自返回 [id] 时合并进同一路径；末项相同不重复。 */
 export declare function mergeHistoryPath(current: unknown, update: unknown): string[];
 /**

package/dist/graph/adapters/langgraph.adapter.js

@@ -37,14 +37,34 @@ import { isHitlDecision, lastAssistantHasUnansweredToolCalls } from '../hitl/hit
 import { classifySkillRead } from './skill-read.js';
 import { skillEntryInvocationFromTool } from './skill-entry-span.js';
 import { withGraphSpan } from '../trace-span.js';
-import { executionTraceFromState, getExecutionStream, runWithExecutionTrace, } from '../execution-trace-context.js';
+import { executionTraceFromState, getExecutionStream, getExecutionTrace, runWithExecutionTrace, } from '../execution-trace-context.js';
 import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
-/** 图未写 `config.maxIterations` 时的 recursionLimit。`agent ⇄ tools` 一圈约 2，50 ≈ 24 次工具往返。 */
-export const DEFAULT_GRAPH_RECURSION_LIMIT = 50;
 /**
- * LangGraph `recursionLimit` 计 superstep（每进一个节点 +1），不是 ReAct 圈数。
- * 图上 `config.maxIterations` 优先；缺省 {@link DEFAULT_GRAPH_RECURSION_LIMIT}。
+ * 传给 LangGraph 的 `recursionLimit`：一轮调度（superstep）+1。
+ * 同一步里并行的多个节点只 +1。ReAct 的 llm 再 tool 大约 +2。
+ * 不读图级 / 请求级 `maxIterations`。整图运行时长用 `timeout`。
+ * 配了 Token 配额才会因预算停止。
  */
+export const DEFAULT_GRAPH_RECURSION_LIMIT = 5000;
+const GRAPH_RECURSION_LIMIT_MESSAGE = '图执行超过平台调度步上限。整图限长请用 config.timeout。';
+export function isGraphRecursionError(error) {
+    if (!(error instanceof Error))
+        return false;
+    if (error.name === 'GraphRecursionError')
+        return true;
+    return /Recursion limit of \d+/i.test(error.message);
+}
+function rethrowGraphRunError(error) {
+    if (error instanceof AppError)
+        throw error;
+    if (isGraphRecursionError(error)) {
+        throw new AppError(ErrorCodes.GRAPH_MAX_ITERATIONS, GRAPH_RECURSION_LIMIT_MESSAGE, {
+            exposeMessage: true,
+            cause: error,
+        });
+    }
+    throw error;
+}
 /** 并行节点各自返回 [id] 时合并进同一路径；末项相同不重复。 */
 export function mergeHistoryPath(current, update) {
     const path = Array.isArray(current)
@@ -63,16 +83,54 @@ export function mergeHistoryPath(current, update) {
     }
     return path.length > 1000 ? path.slice(path.length - 1000) : path;
 }
-function langGraphRunOptions(dsl, extra) {
-    const raw = dsl.config?.maxIterations;
-    const recursionLimit = typeof raw === 'number' && Number.isFinite(raw) && raw > 0
-        ? Math.trunc(raw)
-        : DEFAULT_GRAPH_RECURSION_LIMIT;
+function langGraphRunOptions(extra) {
     return {
         ...extra,
-        recursionLimit,
+        recursionLimit: DEFAULT_GRAPH_RECURSION_LIMIT,
     };
 }
+function graphAbortSignal(state) {
+    const fromState = state?.abortSignal;
+    if (fromState instanceof AbortSignal)
+        return fromState;
+    return getExecutionTrace()?.abortSignal;
+}
+function abortReason(signal) {
+    return signal.reason instanceof Error
+        ? signal.reason
+        : new Error(String(signal.reason ?? 'aborted'));
+}
+function graphAbortDeadlineMs(state) {
+    const fromState = state?.abortDeadlineMs;
+    if (typeof fromState === 'number' && Number.isFinite(fromState))
+        return fromState;
+    return getExecutionTrace()?.abortDeadlineMs;
+}
+function throwIfGraphAborted(state) {
+    const deadline = graphAbortDeadlineMs(state);
+    if (deadline !== undefined && Date.now() >= deadline) {
+        const signal = graphAbortSignal(state);
+        throw signal?.aborted
+            ? abortReason(signal)
+            : new Error('Task timed out after graph deadline');
+    }
+    const signal = graphAbortSignal(state);
+    if (signal?.aborted)
+        throw abortReason(signal);
+}
+function withGraphAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(abortReason(signal));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortReason(signal));
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => {
+            signal.removeEventListener('abort', onAbort);
+        });
+    });
+}
 // ─────────────────────────────────────────────
 // LangGraphAdapter
 // ─────────────────────────────────────────────
@@ -532,12 +590,25 @@ export class LangGraphAdapter {
             streamedTextThisTurn: false,
         };
         const traceCtx = executionTraceFromState(state);
-        const producer = runWithExecutionTrace({ ...traceCtx, stream: streamBag }, () => (async () => {
+        const graphSignal = graphAbortSignal(state);
+        const onGraphAbort = () => {
+            failure = graphSignal ? abortReason(graphSignal) : new Error('aborted');
+            finished = true;
+            signal();
+        };
+        graphSignal?.addEventListener('abort', onGraphAbort, { once: true });
+        const producer = runWithExecutionTrace({
+            ...traceCtx,
+            stream: streamBag,
+            abortSignal: graphSignal,
+            abortDeadlineMs: graphAbortDeadlineMs(state),
+        }, () => (async () => {
             try {
-                const streamIterator = await ref.compiled.stream(input, langGraphRunOptions(ref.dsl, {
+                throwIfGraphAborted(state);
+                const streamIterator = await withGraphAbort(Promise.resolve(ref.compiled.stream(input, langGraphRunOptions({
                     configurable: this.checkpointConfigurable(state, graph),
                     streamMode: 'updates',
-                }));
+                }))), graphSignal);
                 for await (const update of streamIterator) {
                     for (const event of this.convertUpdatesToEvents(update, graph.id, () => streamBag.chunkIndex++, ref.silentNodeIds, ref.subgraphNodeIds)) {
                         enqueue(event);
@@ -562,8 +633,9 @@ export class LangGraphAdapter {
             yield queue.shift();
         }
         await producer;
+        graphSignal?.removeEventListener('abort', onGraphAbort);
         if (failure)
-            throw failure;
+            rethrowGraphRunError(failure);
     }
     /**
      * 同步调用图执行，返回完整结果
@@ -573,10 +645,22 @@ export class LangGraphAdapter {
         const input = this.graphStateToLangGraphInput(this.applyDeclaredSearchFace(state, ref.dsl));
         const startTime = Date.now();
         const traceCtx = executionTraceFromState(state);
+        const abortSignal = graphAbortSignal(state);
+        const abortDeadlineMs = graphAbortDeadlineMs(state);
         // 只补 collector/traceId。子图套娃时外层 stream 袋经 ?? 保留。
-        const result = await runWithExecutionTrace(traceCtx, () => ref.compiled.invoke(input, langGraphRunOptions(ref.dsl, {
-            configurable: this.checkpointConfigurable(state, graph),
-        })));
+        let result;
+        try {
+            result = await withGraphAbort(runWithExecutionTrace({
+                ...traceCtx,
+                abortSignal,
+                abortDeadlineMs,
+            }, () => ref.compiled.invoke(input, langGraphRunOptions({
+                configurable: this.checkpointConfigurable(state, graph),
+            }))), abortSignal);
+        }
+        catch (error) {
+            rethrowGraphRunError(error);
+        }
         const duration = Date.now() - startTime;
         const messages = Array.isArray(result['messages']) ? result['messages'] : [];
         const lastMessage = messages[messages.length - 1];
@@ -684,6 +768,7 @@ export class LangGraphAdapter {
     createNodeFunction(node) {
         const impl = this.createNodeFunctionBody(node);
         return async (state) => {
+            throwIfGraphAborted(state);
             const update = await impl(state);
             const patch = update && typeof update === 'object' ? { ...update } : {};
             const currentNode = typeof patch['currentNode'] === 'string' && String(patch['currentNode']).trim()

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

@@ -243,6 +243,15 @@ export interface GraphState {
      * 仅 stream/invoke 入口使用，不入持久化语义。
      */
     replaceCheckpointMessages?: boolean;
+    /**
+     * 整图超时用的 AbortSignal。不入 Checkpoint。不传给 LangGraph。
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * 整图超时截止（`Date.now()`）。不入 Checkpoint。
+     * 节点入口检查，避免同步循环占满事件循环导致 timer 不能触发。
+     */
+    abortDeadlineMs?: number;
     /**
      * 子图 invoke 写入 LangGraph `checkpoint_ns`。
      * 父图为空；子图为父节点 id。存储槽与父 thread 分开，不覆盖父 latest。

package/dist/graph/execution-trace-context.d.ts

@@ -16,6 +16,10 @@ export interface ExecutionRunContext {
     collector?: ITraceCollector;
     traceId?: string;
     stream?: ExecutionStreamBag;
+    /** 整图超时 AbortSignal；不入 Checkpoint；不传给 LangGraph */
+    abortSignal?: AbortSignal;
+    /** 整图超时截止（Date.now()）；不入 Checkpoint */
+    abortDeadlineMs?: number;
 }
 /** 入口从本次入参取出可绑定的 collector+traceId；缺一则不算。 */
 export declare function executionTraceFromState(state: GraphState | Record<string, unknown> | undefined): {

package/dist/graph/execution-trace-context.js

@@ -33,8 +33,10 @@ export function runWithExecutionTrace(patch, fn) {
         collector: patch.collector ?? outer?.collector,
         traceId: patch.traceId ?? outer?.traceId,
         stream: patch.stream ?? outer?.stream,
+        abortSignal: patch.abortSignal ?? outer?.abortSignal,
+        abortDeadlineMs: patch.abortDeadlineMs ?? outer?.abortDeadlineMs,
     };
-    if (!next.collector && !next.traceId && !next.stream)
+    if (!next.collector && !next.traceId && !next.stream && !next.abortSignal && next.abortDeadlineMs === undefined)
         return fn();
     return storage.run(next, fn);
 }

package/dist/graph/nodes/rag/types.d.ts

@@ -173,7 +173,10 @@ export interface RagNodeConfig {
     model?: string;
     /** 融合后总条数，缺省 10 */
     totalK?: number;
-    /** ReAct 决策轮硬上限（按决策轮计次，同轮并发多个 tool_call 只计 1），缺省 5 */
+    /**
+     * 本节点检索轮次上限（同轮并发多个 tool_call 只计 1），缺省 5。
+     * 到上限该节点带着已有结果正常结束，后续图节点继续。不是整图停止。
+     */
     maxIterations?: number;
     /** 近重判定阈值（字符 n-gram Jaccard，M4 启用），缺省 0.8 */
     nearDupThreshold?: number;