@gt-fe/eap-runtime 0.0.23 → 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;

package/dist/providers/http-llm-provider.js

@@ -9,6 +9,7 @@
 import { resolveLlmModelName } from './resolve-llm-model.js';
 import { createFileLlmTurnLogFromEnv, maskApiKey } from '../debug/llm-turn-log.js';
 import { buildContextUsage, turnSectionChars } from '../token/context-window.js';
+import { getExecutionTrace } from '../graph/execution-trace-context.js';
 export const DEFAULT_LLM_HTTP_TIMEOUT_MS = 180_000;
 export class HttpLLMProvider {
     apiKey;
@@ -101,6 +102,7 @@ export class HttpLLMProvider {
         }
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const unlinkGraphAbort = linkGraphAbort(controller);
         const url = `${this.baseUrl}/chat/completions`;
         const startedAt = Date.now();
         try {
@@ -117,6 +119,7 @@ export class HttpLLMProvider {
                 });
             }
             catch (err) {
+                throwIfGraphTimedOut();
                 throw new Error(this.formatNetworkError(url, err));
             }
             if (!response.ok) {
@@ -184,6 +187,7 @@ export class HttpLLMProvider {
         }
         finally {
             clearTimeout(timeout);
+            unlinkGraphAbort();
         }
     }
     async *stream(messages, config) {
@@ -217,6 +221,7 @@ export class HttpLLMProvider {
         }
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        const unlinkGraphAbort = linkGraphAbort(controller);
         const url = `${this.baseUrl}/chat/completions`;
         const startedAt = Date.now();
         const contentChunks = [];
@@ -239,6 +244,7 @@ export class HttpLLMProvider {
                 });
             }
             catch (err) {
+                throwIfGraphTimedOut();
                 throw new Error(this.formatNetworkError(url, err));
             }
             if (!response.ok) {
@@ -412,6 +418,7 @@ export class HttpLLMProvider {
         }
         finally {
             clearTimeout(timeout);
+            unlinkGraphAbort();
         }
     }
     // ─────────────────────────────────────────────
@@ -509,6 +516,24 @@ export class HttpLLMProvider {
         return `LLM network error calling ${url}: ${detail}`;
     }
 }
+function linkGraphAbort(controller) {
+    const graphSignal = getExecutionTrace()?.abortSignal;
+    if (!graphSignal)
+        return () => undefined;
+    if (graphSignal.aborted) {
+        controller.abort(graphSignal.reason);
+        return () => undefined;
+    }
+    const onAbort = () => controller.abort(graphSignal.reason);
+    graphSignal.addEventListener('abort', onAbort, { once: true });
+    return () => graphSignal.removeEventListener('abort', onAbort);
+}
+function throwIfGraphTimedOut() {
+    const reason = getExecutionTrace()?.abortSignal?.reason;
+    if (reason instanceof Error && /timed out/i.test(reason.message)) {
+        throw reason;
+    }
+}
 function formatNetworkDetail(error, depth = 0) {
     if (depth > 5)
         return '...';

package/dist/registry/graph-loader.js

@@ -4,6 +4,7 @@
  * 生产（server + EAP_PREINSTALL_ROOT）：以预装为准，缺失则失败（04 Req 8.1）。
  * 开发态：Registry + 可选 ./tools 本地 manifest。
  */
+import { DEFAULT_GRAPH_TIMEOUT_MS } from '../common/types.js';
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveAgentModelAllowlist, resolveAgentDefaultModel } from './agent-models.js';
@@ -142,7 +143,7 @@ const DEFAULT_GRAPH_DSL = {
     ],
     entryPoint: 'llm',
     finishPoints: ['__end__'],
-    config: { timeout: 60000 },
+    config: { timeout: DEFAULT_GRAPH_TIMEOUT_MS },
 };
 /** 源图有非空字符串则保留；缺省或空数组为 `['__end__']`。预装 graph.json 与清单内嵌图同一收口。 */
 function finishPointsFromGraphDocument(graph) {
@@ -155,8 +156,8 @@ function finishPointsFromGraphDocument(graph) {
         .filter((id) => id.length > 0);
     return ids.length > 0 ? ids : ['__end__'];
 }
-const DEFAULT_LOADED_GRAPH_CONFIG = { timeout: 60000 };
-/** 默认 timeout 60000；源图 `config` 覆盖。缺 `maxIterations` 时由引擎用 50。 */
+const DEFAULT_LOADED_GRAPH_CONFIG = { timeout: DEFAULT_GRAPH_TIMEOUT_MS };
+/** 默认 timeout {@link DEFAULT_GRAPH_TIMEOUT_MS}；源图 `config` 覆盖。`maxIterations` 可留在 DSL 上，引擎忽略。 */
 function configFromGraphDocument(graph) {
     const raw = graph.config;
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
@@ -758,7 +759,7 @@ export class GraphLoader {
                 },
             ],
             config: {
-                timeout: manifest.config?.timeout ?? 60000,
+                timeout: manifest.config?.timeout ?? DEFAULT_GRAPH_TIMEOUT_MS,
                 maxRetries: manifest.config?.retryCount,
             },
         };

package/dist/runtime/agent-runtime.d.ts

@@ -10,6 +10,7 @@ import type { InvokeOrchestrator } from '../api/handlers/invoke.handler.js';
 import type { ICheckpointSaver } from '../checkpoint/contracts/checkpoint-saver.contract.js';
 import type { ITraceCollector } from '../contracts/trace-collector.js';
 import type { IStateGraphEngine } from '../graph/contracts/state-graph.contract.js';
+import type { TaskTimeoutManager } from '../task/task-timeout.js';
 import { HitlHandler } from '../graph/hitl/hitl-handler.js';
 import { type GraphLoader } from '../registry/graph-loader.js';
 import type { SessionContextService } from '../session/session-context.service.js';
@@ -51,6 +52,8 @@ export interface AgentRuntimeDeps {
     sessionCompression?: SessionCompressionOptions;
     /** 长期记忆注入；默认关。见 EAP_RUNTIME_MEMORY */
     sessionMemory?: import('../session/apply-session-memory.js').SessionMemoryOptions;
+    /** 未注入时不启动整图超时（测试桩） */
+    timeoutManager?: TaskTimeoutManager;
 }
 /** 一次对话详情：消息 + 每步 LLM 入参/响应。File / 内存 / Postgres 同一套结构。 */
 export interface ConversationDetail {

package/dist/runtime/agent-runtime.js

@@ -7,6 +7,9 @@
  * @see 04-runtime-core/design.md §1.5 / §1.7
  */
 import { randomUUID } from 'node:crypto';
+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 { HITL_TIMEOUT_ERROR_CODE, HITL_TIMEOUT_MESSAGE, HitlAlreadyTimedOutError, HitlNotWaitingError, buildHitlWaitedPayload, isHitlDeadlinePassed, loadHitlCheckpoint, readPersistedHitlWaiting, unwrapHitlPaused, } from '../graph/hitl/hitl-handler.js';
 import { resolveAgentSystemPromptFromLoader } from '../registry/graph-loader.js';
 import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
@@ -37,7 +40,7 @@ const DEFAULT_GRAPH_DSL = {
         { from: '__start__', to: 'llm' },
         { from: 'llm', to: '__end__' },
     ],
-    config: { timeout: 60000 },
+    config: { timeout: DEFAULT_GRAPH_TIMEOUT_MS },
 };
 /**
  * AgentRuntime — 管理 Graph 执行的 SDK 门面
@@ -214,6 +217,14 @@ export class AgentRuntime {
             ragScope: params.ragScope,
             ragSources: params.ragSources,
         }, userId);
+        if (response.code !== 'ok') {
+            const output = typeof response.data?.output === 'string' && response.data.output
+                ? response.data.output
+                : response.code;
+            throw new AppError(response.code, output, {
+                exposeMessage: true,
+            });
+        }
         return response.data;
     }
     /**
@@ -241,6 +252,11 @@ export class AgentRuntime {
                 userId,
             });
         }
+        const loadOpts = { agentVersion: params.agentVersion };
+        const graphDsl = this.deps.graphLoader
+            ? await this.deps.graphLoader.loadGraph(agentCode, loadOpts)
+            : DEFAULT_GRAPH_DSL;
+        const timeout = resolveTaskTimeoutMs(params.config?.timeout, graphDsl.config?.timeout);
         const task = await this.deps.taskService.create({
             id: params.taskId,
             agentId: agentCode,
@@ -248,9 +264,12 @@ export class AgentRuntime {
             userId,
             correlationId,
             input: params.input,
-            timeout: params.config?.timeout ?? 60_000,
+            timeout,
         });
         await this.deps.taskService.updateStatus(task.id, 'running');
+        const abortSignal = this.deps.timeoutManager?.startTimer(task.id, timeout, async () => {
+            await this.deps.taskService.tryUpdateStatus(task.id, 'running', 'timeout', 'Task execution timed out');
+        });
         await persistUserTurnMessage(this.deps.messageService, {
             sessionId,
             taskId: task.id,
@@ -258,10 +277,6 @@ export class AgentRuntime {
             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
@@ -321,7 +336,7 @@ export class AgentRuntime {
         const toolResults = [];
         const nodeTokenUsages = [];
         try {
-            for await (const runtimeEvent of this.deps.graphEngine.stream(graph, {
+            for await (const runtimeEvent of runWithExecutionTrace({ abortSignal }, () => this.deps.graphEngine.stream(graph, {
                 messages,
                 userId,
                 delegationToken: ctx.delegationToken,
@@ -343,7 +358,9 @@ export class AgentRuntime {
                 skillInput: resolveSkillInputFromInvokeInput(params.input),
                 traceId: resolveTraceId(params),
                 traceCollector: this.deps.traceCollector,
-            })) {
+                abortSignal,
+                abortDeadlineMs: Date.now() + timeout,
+            }))) {
                 if (runtimeEvent.type === 'tool.called') {
                     const p = runtimeEvent.payload;
                     if (p.toolCallId && p.toolName) {
@@ -415,6 +432,17 @@ export class AgentRuntime {
                 yield this.toSSE('hitl.waited', correlationId, task.id, buildHitlWaitedPayload(hitlPaused));
                 return;
             }
+            const timedOut = err instanceof Error && /timed out/i.test(err.message);
+            if (timedOut) {
+                await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
+                await this.deps.taskService.tryUpdateStatus(task.id, 'running', 'timeout');
+                yield this.toSSE('task.error', correlationId, task.id, {
+                    code: ErrorCodes.TASK_TIMEOUT,
+                    message: 'Task execution timed out',
+                    recoverable: false,
+                });
+                return;
+            }
             const message = err instanceof Error ? err.message : 'Unknown error';
             await recordTaskTokenUsages(this.deps.taskService, task.id, nodeTokenUsages);
             await this.deps.taskService.updateStatus(task.id, 'failed', message);
@@ -425,6 +453,9 @@ export class AgentRuntime {
             });
             throw err;
         }
+        finally {
+            this.deps.timeoutManager?.clearTimer(task.id);
+        }
     }
     /**
      * HITL 用户响应后继续执行（同步结果）。
@@ -483,6 +514,9 @@ export class AgentRuntime {
         if (!claimed) {
             throw new AppError(ErrorCodes.TASK_HITL_INVALID_STATE, `Task ${taskId} is no longer waiting for HITL`, { exposeMessage: true });
         }
+        const abortSignal = this.deps.timeoutManager?.startTimer(taskId, resolveTaskTimeoutMs(task.timeout), async () => {
+            await this.deps.taskService.tryUpdateStatus(taskId, 'running', 'timeout', 'Task execution timed out');
+        });
         const tokenDetail = resolveTokenDetail(response.tokenDetail);
         yield this.toSSE('hitl.resumed', correlationId, taskId, {
             choice: response.choice,
@@ -507,6 +541,8 @@ export class AgentRuntime {
             : await this.resolveLoadedSkills(agentCode, response.userId, agentVersion);
         const continueState = {
             ...resumedState,
+            abortSignal,
+            abortDeadlineMs: Date.now() + resolveTaskTimeoutMs(task.timeout),
             messages: resumedState.messages ?? [],
             replaceCheckpointMessages: true,
             sessionId: resumedState.sessionId ?? sessionId,
@@ -542,7 +578,7 @@ export class AgentRuntime {
         const toolResults = [];
         const nodeTokenUsages = [];
         try {
-            for await (const runtimeEvent of this.deps.graphEngine.stream(graph, continueState)) {
+            for await (const runtimeEvent of runWithExecutionTrace({ abortSignal, abortDeadlineMs: continueState.abortDeadlineMs }, () => this.deps.graphEngine.stream(graph, continueState))) {
                 if (runtimeEvent.type === 'tool.called') {
                     const p = runtimeEvent.payload;
                     if (p.toolCallId && p.toolName) {
@@ -617,6 +653,17 @@ export class AgentRuntime {
                 yield this.toSSE('hitl.waited', correlationId, taskId, buildHitlWaitedPayload(hitlPaused));
                 return;
             }
+            const timedOut = err instanceof Error && /timed out/i.test(err.message);
+            if (timedOut) {
+                await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
+                await this.deps.taskService.tryUpdateStatus(taskId, 'running', 'timeout');
+                yield this.toSSE('task.error', correlationId, taskId, {
+                    code: ErrorCodes.TASK_TIMEOUT,
+                    message: 'Task execution timed out',
+                    recoverable: false,
+                });
+                return;
+            }
             const appErr = err instanceof AppError ? err : AppError.fromUnknown(err);
             const failMsg = appErr.exposeMessage ? appErr.message : '系统内部错误';
             await recordTaskTokenUsages(this.deps.taskService, taskId, nodeTokenUsages);
@@ -628,6 +675,9 @@ export class AgentRuntime {
             });
             throw err instanceof AppError ? err : appErr;
         }
+        finally {
+            this.deps.timeoutManager?.clearTimer(taskId);
+        }
     }
     /**
      * 从 Checkpoint Fork 并真实重新执行。
@@ -658,6 +708,12 @@ export class AgentRuntime {
         const newThreadId = randomUUID();
         const forkedCheckpoint = await this.deps.checkpointSaver.fork(checkpointId, newThreadId, overrides);
         const correlationId = overrides.executionContext?.correlationId ?? randomUUID();
+        const agentVersion = overrides.agentVersion ??
+            (typeof source.state.agentVersion === 'string' ? source.state.agentVersion : undefined);
+        const graphDsl = this.deps.graphLoader && typeof this.deps.graphLoader.loadGraph === 'function'
+            ? await this.deps.graphLoader.loadGraph(agentCode, { agentVersion })
+            : DEFAULT_GRAPH_DSL;
+        const timeout = resolveTaskTimeoutMs(undefined, graphDsl.config?.timeout);
         const task = await this.deps.taskService.create({
             id: taskId,
             agentId: agentCode,
@@ -665,12 +721,13 @@ export class AgentRuntime {
             userId,
             correlationId,
             input: { forkFrom: checkpointId, overrides },
-            timeout: 600_000,
+            timeout,
         });
         await this.deps.taskService.updateStatus(task.id, 'running');
-        const agentVersion = overrides.agentVersion ??
-            (typeof source.state.agentVersion === 'string' ? source.state.agentVersion : undefined);
-        const graph = await this.rebuildExecutableGraph(agentCode, agentVersion);
+        const abortSignal = this.deps.timeoutManager?.startTimer(task.id, timeout, async () => {
+            await this.deps.taskService.tryUpdateStatus(task.id, 'running', 'timeout', 'Task execution timed out');
+        });
+        const graph = await this.deps.graphEngine.buildGraph(graphDsl);
         const loadedToolsBase = await this.resolveLoadedTools(agentCode, agentVersion);
         const skillBundle = await this.resolveLoadedSkills(agentCode, userId, agentVersion);
         const loadedTools = assembleLoadedTools(loadedToolsBase);
@@ -681,11 +738,12 @@ export class AgentRuntime {
         const agentSystemPrompt = (await resolveAgentSystemPromptFromLoader(this.deps.graphLoader, agentCode, agentVersion)) ?? (typeof forkedCheckpoint.state.agentSystemPrompt === 'string'
             ? forkedCheckpoint.state.agentSystemPrompt
             : undefined);
+        const abortDeadlineMs = Date.now() + timeout;
         try {
             const forkState = { ...forkedCheckpoint.state };
             delete forkState.toolSpanId;
             delete forkState.hitlToolCallId;
-            const result = await this.deps.graphEngine.invoke(graph, {
+            const result = await runWithExecutionTrace({ abortSignal, abortDeadlineMs }, () => this.deps.graphEngine.invoke(graph, {
                 messages: Array.isArray(forkState.messages)
                     ? forkState.messages
                     : [],
@@ -701,7 +759,9 @@ export class AgentRuntime {
                 taskId: task.id,
                 traceId,
                 traceCollector: this.deps.traceCollector,
-            });
+                abortSignal,
+                abortDeadlineMs,
+            }));
             if (result.tokenUsage.perNode && result.tokenUsage.perNode.length > 0) {
                 await recordTaskTokenUsages(this.deps.taskService, task.id, result.tokenUsage.perNode);
             }
@@ -760,6 +820,23 @@ export class AgentRuntime {
             await recordTaskTokenUsages(this.deps.taskService, task.id, usages);
             const input_tokens = usages.reduce((sum, row) => sum + row.inputTokens, 0);
             const output_tokens = usages.reduce((sum, row) => sum + row.outputTokens, 0);
+            const timedOut = err instanceof Error && /timed out/i.test(err.message);
+            if (timedOut) {
+                await this.deps.taskService.tryUpdateStatus(task.id, 'running', 'timeout');
+                return {
+                    newTraceId: traceId,
+                    originalTraceId,
+                    newTaskId: task.id,
+                    checkpointId,
+                    status: 'timeout',
+                    output: message,
+                    tokenUsage: {
+                        input_tokens,
+                        output_tokens,
+                        total_tokens: input_tokens + output_tokens,
+                    },
+                };
+            }
             await this.deps.taskService.updateStatus(task.id, 'failed', message);
             return {
                 newTraceId: traceId,
@@ -775,6 +852,9 @@ export class AgentRuntime {
                 },
             };
         }
+        finally {
+            this.deps.timeoutManager?.clearTimer(task.id);
+        }
     }
     async prepareHitlResume(taskId, response) {
         const task = await this.deps.taskService.getTask(taskId);

package/dist/runtime/dev-runtime.js

@@ -31,7 +31,7 @@ import { createToolExecutor } from '../tool/create-tool-executor.js';
 import { DevToolExecutor } from '../tool/dev-tool-executor.js';
 import { captureOverlayJailOptions, withHarnessPrimitives } from '../tool/harness-primitives.js';
 import { AllowAllGovernanceClient, HttpGovernanceClient, } from '../governance/index.js';
-import { InvokeOrchestrator, StreamOrchestrator, SessionService, MessageService, SessionContextService, TaskService, LangGraphAdapter, HitlHandler, TokenBudgetService, TokenStatsService, TokenBudgetGuard, SessionBudgetChecker, createAgentRegistryClient, GraphLoader, } from '../index.js';
+import { InvokeOrchestrator, StreamOrchestrator, SessionService, MessageService, SessionContextService, TaskService, TaskTimeoutManager, LangGraphAdapter, HitlHandler, TokenBudgetService, TokenStatsService, TokenBudgetGuard, SessionBudgetChecker, createAgentRegistryClient, GraphLoader, } from '../index.js';
 import { createAgentRuntime } from './agent-runtime.js';
 import { assembleRuntimeStorage } from './storage-profile.js';
 import { createDevRagNodeDeps } from './dev-rag-deps.js';
@@ -139,6 +139,7 @@ export function createDevRuntime(options) {
     const sessionContextService = new SessionContextService(sessionService, messageService);
     // ── Task / Token ──
     const taskService = new TaskService();
+    const timeoutManager = new TaskTimeoutManager();
     const budgetService = new TokenBudgetService(storage.tokenBudgetRepository);
     const tokenStatsService = new TokenStatsService();
     const tokenBudgetGuard = new TokenBudgetGuard(budgetService);
@@ -202,6 +203,7 @@ export function createDevRuntime(options) {
         checkpointSaver: storage.checkpointSaver,
         sessionCompression,
         sessionMemory,
+        timeoutManager,
     });
     const streamOrchestrator = new StreamOrchestrator({
         sessionContextService,
@@ -215,6 +217,7 @@ export function createDevRuntime(options) {
         checkpointSaver: storage.checkpointSaver,
         sessionCompression,
         sessionMemory,
+        timeoutManager,
     });
     const agentRuntime = createAgentRuntime({
         invokeOrchestrator,
@@ -229,6 +232,7 @@ export function createDevRuntime(options) {
         turnLog,
         sessionCompression,
         sessionMemory,
+        timeoutManager,
     });
     return {
         invokeOrchestrator,
@@ -243,7 +247,10 @@ export function createDevRuntime(options) {
         taskService,
         tokenStatsService,
         graphLoader,
-        dispose: stopSkillWatch,
+        dispose: () => {
+            stopSkillWatch();
+            timeoutManager.dispose();
+        },
         diagnostics: {
             packageVersion: RUNTIME_PACKAGE_VERSION,
             deploymentContext,

package/dist/runtime/types.d.ts

@@ -78,7 +78,7 @@ export interface ForkResult {
     originalTraceId: string;
     newTaskId: string;
     checkpointId: string;
-    status: 'completed' | 'failed';
+    status: 'completed' | 'failed' | 'timeout';
     output: unknown;
     tokenUsage: {
         input_tokens: number;

package/dist/sse/events/response-events.d.ts

@@ -5,7 +5,7 @@
  * - response.final
  *
  * 可选事件：
- * - response.max_iterations_reached
+ * - response.max_iterations_reached（契约保留；调度步上限走 task.error / runtime.graph.max_iterations，不发本事件）
  *
  * @see design.md §1.6 SSE事件协议定义
  */
@@ -16,7 +16,7 @@ export interface ResponseFinalPayload {
     /** 回复格式（如 text, markdown, json） */
     format: string;
 }
-/** 达到最大迭代次数 */
+/** 契约保留。整图调度步上限不发此事件。 */
 export interface ResponseMaxIterationsReachedPayload {
     /** 最大迭代次数 */
     maxIterations: number;

package/dist/sse/events/response-events.js

@@ -5,7 +5,7 @@
  * - response.final
  *
  * 可选事件：
- * - response.max_iterations_reached
+ * - response.max_iterations_reached（契约保留；调度步上限走 task.error / runtime.graph.max_iterations，不发本事件）
  *
  * @see design.md §1.6 SSE事件协议定义
  */

package/dist/task/contracts/task-manager.contract.d.ts

@@ -46,6 +46,8 @@ export interface TaskRecord {
     correlationId: string;
     /** 用户输入 */
     input: unknown;
+    /** 整图超时（毫秒）。未写入旧记录时 resume 用平台缺省 */
+    timeout?: number;
     /** 执行输出 */
     output: unknown | null;
     /** 当前状态 */

package/dist/task/index.d.ts

@@ -3,5 +3,6 @@ export { TaskService, InMemoryTaskRepository } from './task.service.js';
 export type { ITaskRepository } from './task.service.js';
 export { TaskTimeoutManager } from './task-timeout.js';
 export type { TaskTimeoutManagerOptions } from './task-timeout.js';
+export { resolveTaskTimeoutMs } from './resolve-task-timeout.js';
 export { TaskProgressTracker } from './task-progress-tracker.js';
 export type { TaskProgressInfo } from './task-progress-tracker.js';

package/dist/task/index.js

@@ -2,4 +2,5 @@
 export * from './contracts/index.js';
 export { TaskService, InMemoryTaskRepository } from './task.service.js';
 export { TaskTimeoutManager } from './task-timeout.js';
+export { resolveTaskTimeoutMs } from './resolve-task-timeout.js';
 export { TaskProgressTracker } from './task-progress-tracker.js';

package/dist/task/resolve-task-timeout.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 整图超时：请求 config.timeout，否则图 config.timeout，否则平台缺省 1200000 毫秒（20 分钟）。
+ * 官方模板图上不写 timeout，用平台缺省。LLM HTTP 超时、HITL 等待另算。
+ */
+/** 请求显式值优先，否则图配置，否则 {@link DEFAULT_GRAPH_TIMEOUT_MS}。 */
+export declare function resolveTaskTimeoutMs(requestTimeout?: number, graphTimeout?: number): number;

package/dist/task/resolve-task-timeout.js

@@ -0,0 +1,16 @@
+/**
+ * 整图超时：请求 config.timeout，否则图 config.timeout，否则平台缺省 1200000 毫秒（20 分钟）。
+ * 官方模板图上不写 timeout，用平台缺省。LLM HTTP 超时、HITL 等待另算。
+ */
+import { DEFAULT_GRAPH_TIMEOUT_MS } from '../common/types.js';
+function positiveMs(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        return undefined;
+    return Math.trunc(value);
+}
+/** 请求显式值优先，否则图配置，否则 {@link DEFAULT_GRAPH_TIMEOUT_MS}。 */
+export function resolveTaskTimeoutMs(requestTimeout, graphTimeout) {
+    return (positiveMs(requestTimeout) ??
+        positiveMs(graphTimeout) ??
+        DEFAULT_GRAPH_TIMEOUT_MS);
+}

package/dist/task/task-timeout.d.ts

@@ -13,7 +13,7 @@
  * TaskTimeoutManager 配置选项
  */
 export interface TaskTimeoutManagerOptions {
-    /** 默认超时时间（毫秒），默认 60000 (60s) */
+    /** 默认超时时间（毫秒），默认 {@link DEFAULT_GRAPH_TIMEOUT_MS} */
     defaultTimeoutMs?: number;
 }
 /**

package/dist/task/task-timeout.js

@@ -9,11 +9,12 @@
  * @see design.md §1.1 任务管理 — Task级超时
  * @see requirements.md Requirement 7 AC4
  */
+import { DEFAULT_GRAPH_TIMEOUT_MS } from '../common/types.js';
 // ─────────────────────────────────────────────
 // Default Constants
 // ─────────────────────────────────────────────
-/** 默认超时：60 秒 */
-const DEFAULT_TIMEOUT_MS = 60_000;
+/** 默认超时：与图/请求缺省同一常数 */
+const DEFAULT_TIMEOUT_MS = DEFAULT_GRAPH_TIMEOUT_MS;
 /** 最大允许超时：3600 秒（1 小时） */
 const MAX_TIMEOUT_MS = 3_600_000;
 // ─────────────────────────────────────────────

package/dist/task/task.service.js

@@ -84,6 +84,7 @@ export class TaskService {
             userId: params.userId,
             correlationId: params.correlationId,
             input: params.input,
+            timeout: params.timeout,
             output: null,
             status: 'pending',
             traceId: null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,7 @@
     "ioredis": "^5.4.0",
     "pg": "^8.13.0",
     "yaml": "^2.6.1",
-    "@gt-fe/eap-contracts": "0.0.13"
+    "@gt-fe/eap-contracts": "0.0.14"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",