@gt-fe/eap-runtime 0.0.33 → 0.0.34

package/dist/runtime/agent-runtime.js

@@ -9,13 +9,14 @@
 import { randomUUID } from 'node:crypto';
 import { DEFAULT_GRAPH_TIMEOUT_MS } from '../common/types.js';
 import { resolveTaskTimeoutMs } from '../task/resolve-task-timeout.js';
+import { taskAbortKindOf } from '../task/task-abort.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 { resolveAgentDisplayNameFromLoader, resolveAgentSystemPromptFromLoader, } from '../registry/graph-loader.js';
 import { toLoadedSkillMap } from '../tool/system-prompt-builder.js';
 import { assembleLoadedTools } from '../tool/harness-primitives.js';
 import { createFileLlmTurnLogFromEnv, } from '../debug/llm-turn-log.js';
-import { buildHitlWaitingTaskOutput, buildTurnTranscriptFromStreamEvents, loadModelFacingHistory, turnGraphMessagesAfterCompression, extractHitlThreadId, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, appendTerminalToolResult, } from '../session/persist-turn-messages.js';
+import { buildHitlWaitingTaskOutput, buildTurnTranscriptFromStreamEvents, loadModelFacingHistory, turnGraphMessagesAfterCompression, extractHitlThreadId, applyStreamReasoningEvent, applyStreamTextDelta, createStreamAssistantBuckets, createStreamReasoningState, resolvedStreamReasoning, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, appendTerminalToolResult, } from '../session/persist-turn-messages.js';
 import { collectPublicArtifactLinks, collectPublicArtifactLinksFromEvent, injectPublicArtifactLinks, mergeArtifactLinks, } from '../tool/inject-public-artifact-links.js';
 import { iterSessionCompression, withCompressionSummaryModel, } from '../session/apply-session-compression.js';
 import { applySessionMemory } from '../session/apply-session-memory.js';
@@ -33,7 +34,33 @@ const HITL_TERMINAL_STATUSES = [
     'failed',
     'timeout',
     'token_exhausted',
+    'cancelled',
 ];
+const TASK_CANCELLED_SSE_CODE = 'runtime.task.cancelled';
+function taskAbortSseData(kind) {
+    if (kind === 'timeout') {
+        return {
+            code: ErrorCodes.TASK_TIMEOUT,
+            message: 'Task execution timed out',
+            recoverable: false,
+        };
+    }
+    return {
+        code: TASK_CANCELLED_SSE_CODE,
+        message: 'Task cancelled',
+        recoverable: false,
+    };
+}
+async function settleAbortedTask(taskService, taskId, kind) {
+    if (kind === 'timeout') {
+        await taskService.tryUpdateStatus(taskId, 'running', 'timeout');
+        return;
+    }
+    const moved = await taskService.tryUpdateStatus(taskId, 'running', 'cancelled');
+    if (!moved) {
+        await taskService.tryUpdateStatus(taskId, 'waiting_hitl', 'cancelled');
+    }
+}
 const DEFAULT_GRAPH_DSL = {
     name: 'default-graph',
     version: '1.0.0',
@@ -57,6 +84,17 @@ export class AgentRuntime {
         }
         this.deps.hitlHandler.setTraceCollector?.(this.deps.traceCollector);
     }
+    /**
+     * 停止这一轮。超时和用户停止共用 timeoutManager 上的那条 AbortSignal。
+     * 计时器还没启动时先记下，startTimer 会返回已 abort 的 signal，且不调用 onTimeout。
+     * @returns 已 abort 或已记下。没有 timeoutManager 时返回 false。
+     */
+    abort(taskId, kind = 'cancelled') {
+        const manager = this.deps.timeoutManager;
+        if (!manager || !taskId.trim())
+            return false;
+        return manager.abort(taskId, kind);
+    }
     /** 从 GraphLoader 解析 tool manifest 映射（invoke/stream/resume/fork 共用） */
     async resolveLoadedTools(agentCode, agentVersion) {
         if (!this.deps.graphLoader)
@@ -376,8 +414,8 @@ export class AgentRuntime {
         });
         const startTime = Date.now();
         const assistantBuckets = createStreamAssistantBuckets();
+        const reasoningState = createStreamReasoningState();
         let toolCallReasoningContent;
-        let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
         const artifactLinks = [];
@@ -419,16 +457,12 @@ export class AgentRuntime {
                             arguments: p.arguments ?? {},
                         });
                     }
-                    if (typeof p.reasoningContent === 'string' && p.reasoningContent) {
-                        toolCallReasoningContent = p.reasoningContent;
-                    }
+                    toolCallReasoningContent = resolvedStreamReasoning(reasoningState);
                 }
                 // 终态 tool.result / tool.error 回填历史；willRetry 的 error 不进 transcript
                 appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
                 collectPublicArtifactLinksFromEvent(runtimeEvent.type, runtimeEvent.payload, artifactLinks);
-                const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
-                if (streamedReasoning)
-                    assistantReasoningContent = streamedReasoning;
+                applyStreamReasoningEvent(reasoningState, runtimeEvent.type, runtimeEvent.payload);
                 applyStreamTextDelta(assistantBuckets, runtimeEvent.type, runtimeEvent.payload);
                 collectStreamNodeTokenUsage(runtimeEvent, nodeTokenUsages);
                 if (shouldEmitTokenSse(tokenDetail, runtimeEvent.type)) {
@@ -462,7 +496,7 @@ export class AgentRuntime {
                     assistantText: injected,
                     finishPoints: graph.finishPoints,
                     toolCallReasoningContent,
-                    assistantReasoningContent,
+                    assistantReasoningContent: resolvedStreamReasoning(reasoningState),
                 }),
                 assistantTokenCount: tokenSummary.total.output,
                 assistantDurationMs: Date.now() - startTime,
@@ -495,15 +529,11 @@ 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) {
+            const abortKind = taskAbortKindOf(err, abortSignal);
+            if (abortKind) {
                 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,
-                });
+                await settleAbortedTask(this.deps.taskService, task.id, abortKind);
+                yield this.toSSE('task.error', correlationId, task.id, taskAbortSseData(abortKind));
                 return;
             }
             const message = err instanceof Error ? err.message : 'Unknown error';
@@ -638,8 +668,8 @@ export class AgentRuntime {
         };
         const startTime = Date.now();
         const assistantBuckets = createStreamAssistantBuckets();
+        const reasoningState = createStreamReasoningState();
         let toolCallReasoningContent;
-        let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
         const artifactLinks = [];
@@ -655,15 +685,11 @@ export class AgentRuntime {
                             arguments: p.arguments ?? {},
                         });
                     }
-                    if (typeof p.reasoningContent === 'string' && p.reasoningContent) {
-                        toolCallReasoningContent = p.reasoningContent;
-                    }
+                    toolCallReasoningContent = resolvedStreamReasoning(reasoningState);
                 }
                 appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
                 collectPublicArtifactLinksFromEvent(runtimeEvent.type, runtimeEvent.payload, artifactLinks);
-                const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
-                if (streamedReasoning)
-                    assistantReasoningContent = streamedReasoning;
+                applyStreamReasoningEvent(reasoningState, runtimeEvent.type, runtimeEvent.payload);
                 applyStreamTextDelta(assistantBuckets, runtimeEvent.type, runtimeEvent.payload);
                 collectStreamNodeTokenUsage(runtimeEvent, nodeTokenUsages);
                 if (shouldEmitTokenSse(tokenDetail, runtimeEvent.type)) {
@@ -698,7 +724,7 @@ export class AgentRuntime {
                         assistantText: injected,
                         finishPoints: graph.finishPoints,
                         toolCallReasoningContent,
-                        assistantReasoningContent,
+                        assistantReasoningContent: resolvedStreamReasoning(reasoningState),
                     }),
                     assistantTokenCount: tokenSummary.total.output,
                     assistantDurationMs: Date.now() - startTime,
@@ -734,15 +760,11 @@ 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) {
+            const abortKind = taskAbortKindOf(err, abortSignal);
+            if (abortKind) {
                 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,
-                });
+                await settleAbortedTask(this.deps.taskService, taskId, abortKind);
+                yield this.toSSE('task.error', correlationId, taskId, taskAbortSseData(abortKind));
                 return;
             }
             const appErr = err instanceof AppError ? err : AppError.fromUnknown(err);
@@ -905,15 +927,15 @@ 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');
+            const abortKind = taskAbortKindOf(err, abortSignal);
+            if (abortKind) {
+                await settleAbortedTask(this.deps.taskService, task.id, abortKind);
                 return {
                     newTraceId: traceId,
                     originalTraceId,
                     newTaskId: task.id,
                     checkpointId,
-                    status: 'timeout',
+                    status: abortKind === 'timeout' ? 'timeout' : 'cancelled',
                     output: message,
                     tokenUsage: {
                         input_tokens,

package/dist/runtime/types.d.ts

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

package/dist/session/persist-turn-messages.d.ts

@@ -85,10 +85,18 @@ export declare function sessionVisibleAssistantTexts(texts: Array<{
  */
 export declare function sessionVisibleGraphMessages(messages: GraphMessage[], finishPoints?: string[]): GraphMessage[];
 /**
- * 从流式事件抽取 assistant reasoning。
- * 子图在 skill.completed 上回传（父图不再为 subgraph 节点发空 response.chunk）。
+ * 从流式事件抽取本事件上的思考字符串。
+ * 认 reasoning.completed / reasoning.chunk 的 content，以及 skill.completed 的 reasoningContent。
  */
 export declare function extractStreamReasoning(eventType: string, payload: unknown): string | undefined;
+/** 本回合思考累加：started 清空；completed 优先，没有 completed 时拼接 chunk */
+export type StreamReasoningState = {
+    chunkFallback: string;
+    lastCompleted?: string;
+};
+export declare function createStreamReasoningState(): StreamReasoningState;
+export declare function applyStreamReasoningEvent(state: StreamReasoningState, eventType: string, payload: unknown): void;
+export declare function resolvedStreamReasoning(state: StreamReasoningState): string | undefined;
 /** 落盘 / 回填历史只收终态：result，或不会再试的 error。willRetry 的 error 只给直播 UI。 */
 export declare function isTerminalToolStreamEvent(eventType: string, payload: unknown): boolean;
 export declare function appendTerminalToolResult(eventType: string, payload: unknown, bucket: StreamToolResult[]): void;

package/dist/session/persist-turn-messages.js

@@ -202,20 +202,45 @@ export function sessionVisibleGraphMessages(messages, finishPoints) {
     return out;
 }
 /**
- * 从流式事件抽取 assistant reasoning。
- * 子图在 skill.completed 上回传（父图不再为 subgraph 节点发空 response.chunk）。
+ * 从流式事件抽取本事件上的思考字符串。
+ * 认 reasoning.completed / reasoning.chunk 的 content，以及 skill.completed 的 reasoningContent。
  */
 export function extractStreamReasoning(eventType, payload) {
-    if (eventType !== 'response.chunk' &&
-        eventType !== 'response.delta' &&
-        eventType !== 'response.final' &&
-        eventType !== 'skill.completed') {
-        return undefined;
-    }
     if (!payload || typeof payload !== 'object')
         return undefined;
-    const value = payload.reasoningContent;
-    return typeof value === 'string' && value ? value : undefined;
+    const p = payload;
+    if (eventType === 'reasoning.chunk' || eventType === 'reasoning.completed') {
+        return typeof p.content === 'string' && p.content ? p.content : undefined;
+    }
+    if (eventType === 'skill.completed') {
+        return typeof p.reasoningContent === 'string' && p.reasoningContent
+            ? p.reasoningContent
+            : undefined;
+    }
+    return undefined;
+}
+export function createStreamReasoningState() {
+    return { chunkFallback: '' };
+}
+export function applyStreamReasoningEvent(state, eventType, payload) {
+    if (eventType === 'reasoning.started') {
+        state.chunkFallback = '';
+        state.lastCompleted = undefined;
+        return;
+    }
+    const text = extractStreamReasoning(eventType, payload);
+    if (!text)
+        return;
+    if (eventType === 'reasoning.chunk') {
+        state.chunkFallback += text;
+        return;
+    }
+    state.lastCompleted = text;
+}
+export function resolvedStreamReasoning(state) {
+    if (state.lastCompleted)
+        return state.lastCompleted;
+    return state.chunkFallback ? state.chunkFallback : undefined;
 }
 /** 落盘 / 回填历史只收终态：result，或不会再试的 error。willRetry 的 error 只给直播 UI。 */
 export function isTerminalToolStreamEvent(eventType, payload) {

package/dist/sse/events/index.d.ts

@@ -10,7 +10,7 @@
  * - 时态：过去式（started/completed）或名词（final/heartbeat）
  *
  * 分层设计：
- * - 核心事件（14 种）：所有 Agent 必须支持
+ * - 核心事件（16 种）：所有 Agent 必须支持
  * - 可选事件：Agent 按需支持
  *
  * @see design.md §1.6 SSE事件协议定义
@@ -36,7 +36,7 @@ export type SseEventLevel = 'core' | 'optional';
 /**
  * 核心事件类型（所有 Agent 必须支持）
  */
-export declare const CORE_SSE_EVENTS: readonly ["session.created", "task.started", "task.completed", "task.error", "reasoning.started", "response.chunk", "tool.called", "tool.result", "tool.error", "hitl.waited", "hitl.resumed", "response.final", "stats.token_usage", "connection.heartbeat"];
+export declare const CORE_SSE_EVENTS: readonly ["session.created", "task.started", "task.completed", "task.error", "reasoning.started", "reasoning.chunk", "reasoning.completed", "response.chunk", "tool.called", "tool.result", "tool.error", "hitl.waited", "hitl.resumed", "response.final", "stats.token_usage", "connection.heartbeat"];
 /**
  * 可选事件类型（Agent 按需支持）
  */
@@ -44,10 +44,10 @@ export declare const OPTIONAL_SSE_EVENTS: readonly ["skill.matched", "skill.unma
 /**
  * SSEEventType — SSE 事件类型字符串联合类型
  */
-export type SSEEventType = 'session.created' | 'task.started' | 'task.completed' | 'task.error' | 'reasoning.started' | 'response.chunk' | 'tool.called' | 'tool.result' | 'tool.error' | 'hitl.waited' | 'hitl.resumed' | 'response.final' | 'stats.token_usage' | 'connection.heartbeat' | 'skill.matched' | 'skill.unmatched' | 'skill.started' | 'skill.completed' | 'skill.failed' | 'skill.loaded' | 'skill.resource_read' | 'reasoning.step' | 'tool.progress' | 'file.created' | 'file.updated' | 'code.executed' | 'collaboration.handed_off' | 'collaboration.subtask.started' | 'collaboration.subtask.completed' | 'plan.created' | 'plan.step.started' | 'plan.step.completed' | 'response.max_iterations_reached' | 'stats.node_token_usage' | 'session.compression.started' | 'session.compression.completed' | 'rag.round' | 'rag.search' | 'rag.denoise' | 'rag.rewrite' | 'rag.finish';
+export type SSEEventType = 'session.created' | 'task.started' | 'task.completed' | 'task.error' | 'reasoning.started' | 'reasoning.chunk' | 'reasoning.completed' | 'response.chunk' | 'tool.called' | 'tool.result' | 'tool.error' | 'hitl.waited' | 'hitl.resumed' | 'response.final' | 'stats.token_usage' | 'connection.heartbeat' | 'skill.matched' | 'skill.unmatched' | 'skill.started' | 'skill.completed' | 'skill.failed' | 'skill.loaded' | 'skill.resource_read' | 'reasoning.step' | 'tool.progress' | 'file.created' | 'file.updated' | 'code.executed' | 'collaboration.handed_off' | 'collaboration.subtask.started' | 'collaboration.subtask.completed' | 'plan.created' | 'plan.step.started' | 'plan.step.completed' | 'response.max_iterations_reached' | 'stats.node_token_usage' | 'session.compression.started' | 'session.compression.completed' | 'rag.round' | 'rag.search' | 'rag.denoise' | 'rag.rewrite' | 'rag.finish';
 import type { SessionCreatedPayload, TaskStartedPayload, TaskCompletedPayload, TaskErrorPayload, SessionCompressionStartedPayload, SessionCompressionCompletedPayload } from './session-events.js';
 import type { SkillMatchedPayload, SkillUnmatchedPayload, SkillStartedPayload, SkillCompletedPayload, SkillFailedPayload, SkillLoadedPayload, SkillResourceReadPayload } from './skill-events.js';
-import type { ReasoningStartedPayload, ReasoningStepPayload, ResponseChunkPayload } from './reasoning-events.js';
+import type { ReasoningStartedPayload, ReasoningChunkPayload, ReasoningCompletedPayload, ReasoningStepPayload, ResponseChunkPayload } from './reasoning-events.js';
 import type { ToolCalledPayload, ToolResultPayload, ToolProgressPayload, ToolErrorPayload } from './tool-events.js';
 import type { FileCreatedPayload, FileUpdatedPayload } from './file-events.js';
 import type { CodeExecutedPayload } from './code-events.js';
@@ -67,6 +67,8 @@ export interface SSEEventPayloadMap {
     'task.completed': TaskCompletedPayload;
     'task.error': TaskErrorPayload;
     'reasoning.started': ReasoningStartedPayload;
+    'reasoning.chunk': ReasoningChunkPayload;
+    'reasoning.completed': ReasoningCompletedPayload;
     'response.chunk': ResponseChunkPayload;
     'tool.called': ToolCalledPayload;
     'tool.result': ToolResultPayload;

package/dist/sse/events/index.js

@@ -10,7 +10,7 @@
  * - 时态：过去式（started/completed）或名词（final/heartbeat）
  *
  * 分层设计：
- * - 核心事件（14 种）：所有 Agent 必须支持
+ * - 核心事件（16 种）：所有 Agent 必须支持
  * - 可选事件：Agent 按需支持
  *
  * @see design.md §1.6 SSE事件协议定义
@@ -41,6 +41,8 @@ export const CORE_SSE_EVENTS = [
     'task.completed',
     'task.error',
     'reasoning.started',
+    'reasoning.chunk',
+    'reasoning.completed',
     'response.chunk',
     'tool.called',
     'tool.result',

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

@@ -3,10 +3,12 @@
  *
  * 核心事件：
  * - reasoning.started
+ * - reasoning.chunk
+ * - reasoning.completed
  * - response.chunk
  *
  * 可选事件：
- * - reasoning.step
+ * - reasoning.step（ReAct thought/plan，不是模型 CoT）
  *
  * @see design.md §1.6 SSE事件协议定义
  */
@@ -17,7 +19,27 @@ export interface ReasoningStartedPayload {
     /** 使用的模型名称（可选；未知时可省略） */
     model?: string;
 }
-/** 推理中间步骤（思考过程） */
+/** 思考增量（与 response.chunk 对称；空增量不发） */
+export interface ReasoningChunkPayload {
+    /** 思考片段 */
+    content: string;
+    /** 片段序号（本轮从 0 开始，与 response.chunk 分开计） */
+    index: number;
+    /** 发出该增量的 LLM 节点 */
+    node?: string;
+    /** 所属图 */
+    graphId?: string;
+}
+/** 本轮思考全文（有思考才发） */
+export interface ReasoningCompletedPayload {
+    /** 本轮思考全文 */
+    content: string;
+    /** 发出该全文的 LLM 节点 */
+    node?: string;
+    /** 所属图 */
+    graphId?: string;
+}
+/** 推理中间步骤（ReAct thought/plan，不是模型 CoT） */
 export interface ReasoningStepPayload {
     /** 步骤序号 */
     step: number;

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

@@ -3,10 +3,12 @@
  *
  * 核心事件：
  * - reasoning.started
+ * - reasoning.chunk
+ * - reasoning.completed
  * - response.chunk
  *
  * 可选事件：
- * - reasoning.step
+ * - reasoning.step（ReAct thought/plan，不是模型 CoT）
  *
  * @see design.md §1.6 SSE事件协议定义
  */

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

@@ -39,6 +39,8 @@ export interface SkillCompletedPayload {
     skillId: string;
     skillName: string;
     output?: unknown;
+    /** 子图最后一条 assistant 的思考全文；只订 skill 事件的落库用 */
+    reasoningContent?: string;
 }
 /** Skill 子图执行失败 */
 export interface SkillFailedPayload {

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

@@ -2,7 +2,7 @@
  * Task Manager Contract — 任务生命周期管理接口
  *
  * 定义 Task 的创建、状态流转、查询、Token 消耗记录等核心操作。
- * 状态流转：pending → running → success/failed/timeout/token_exhausted
+ * 状态流转：pending → running → success/failed/timeout/token_exhausted/cancelled
  *
  * @see design.md §1.3 数据模型 — tasks 表
  * @see requirements.md Requirement 7 AC1-AC5
@@ -126,7 +126,7 @@ export interface ITaskManager {
     /**
      * 更新 Task 状态
      *
-     * 合法流转：pending→running, running→success/failed/timeout/token_exhausted
+     * 合法流转：pending→running|cancelled, running→success/failed/timeout/token_exhausted/cancelled/waiting_hitl
      *
      * @param taskId - Task ID
      * @param status - 目标状态

package/dist/task/contracts/task-manager.contract.js

@@ -2,7 +2,7 @@
  * Task Manager Contract — 任务生命周期管理接口
  *
  * 定义 Task 的创建、状态流转、查询、Token 消耗记录等核心操作。
- * 状态流转：pending → running → success/failed/timeout/token_exhausted
+ * 状态流转：pending → running → success/failed/timeout/token_exhausted/cancelled
  *
  * @see design.md §1.3 数据模型 — tasks 表
  * @see requirements.md Requirement 7 AC1-AC5

package/dist/task/index.d.ts

@@ -3,6 +3,8 @@ 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 { TaskAbortError, taskAbortKind, taskAbortKindOf, TASK_CANCELLED_MESSAGE } from './task-abort.js';
+export type { TaskAbortKind } from './task-abort.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,5 +2,6 @@
 export * from './contracts/index.js';
 export { TaskService, InMemoryTaskRepository } from './task.service.js';
 export { TaskTimeoutManager } from './task-timeout.js';
+export { TaskAbortError, taskAbortKind, taskAbortKindOf, TASK_CANCELLED_MESSAGE } from './task-abort.js';
 export { resolveTaskTimeoutMs } from './resolve-task-timeout.js';
 export { TaskProgressTracker } from './task-progress-tracker.js';

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

@@ -0,0 +1,14 @@
+/**
+ * 一次 Task 一条 AbortSignal。超时和用户停止都 abort 它，用 kind 区分。
+ * name 固定 AbortError，节点重试会跳过。
+ */
+export type TaskAbortKind = 'timeout' | 'cancelled';
+export declare const TASK_CANCELLED_MESSAGE = "Task cancelled";
+export declare class TaskAbortError extends Error {
+    readonly kind: TaskAbortKind;
+    readonly taskId: string;
+    constructor(taskId: string, kind: TaskAbortKind, timeoutMs?: number);
+}
+export declare function taskAbortKind(err: unknown): TaskAbortKind | undefined;
+/** 图把 AbortError 包了一层时，回看这一轮 signal 上的 reason。 */
+export declare function taskAbortKindOf(err: unknown, signal?: AbortSignal): TaskAbortKind | undefined;

package/dist/task/task-abort.js

@@ -0,0 +1,33 @@
+/**
+ * 一次 Task 一条 AbortSignal。超时和用户停止都 abort 它，用 kind 区分。
+ * name 固定 AbortError，节点重试会跳过。
+ */
+export const TASK_CANCELLED_MESSAGE = 'Task cancelled';
+export class TaskAbortError extends Error {
+    kind;
+    taskId;
+    constructor(taskId, kind, timeoutMs) {
+        const message = kind === 'timeout'
+            ? `Task '${taskId}' timed out after ${timeoutMs ?? 0}ms`
+            : `Task '${taskId}' cancelled`;
+        super(message);
+        this.name = 'AbortError';
+        this.kind = kind;
+        this.taskId = taskId;
+    }
+}
+export function taskAbortKind(err) {
+    if (err instanceof TaskAbortError)
+        return err.kind;
+    if (!(err instanceof Error))
+        return undefined;
+    if (/timed out/i.test(err.message))
+        return 'timeout';
+    if (err.name === 'AbortError' && /cancell?ed/i.test(err.message))
+        return 'cancelled';
+    return undefined;
+}
+/** 图把 AbortError 包了一层时，回看这一轮 signal 上的 reason。 */
+export function taskAbortKindOf(err, signal) {
+    return taskAbortKind(err) ?? (signal?.aborted ? taskAbortKind(signal.reason) : undefined);
+}

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

@@ -9,6 +9,7 @@
  * @see design.md §1.1 任务管理 — Task级超时
  * @see requirements.md Requirement 7 AC4
  */
+import { type TaskAbortKind } from './task-abort.js';
 /**
  * TaskTimeoutManager 配置选项
  */
@@ -27,6 +28,11 @@ export interface TaskTimeoutManagerOptions {
  */
 export declare class TaskTimeoutManager {
     private readonly entries;
+    /**
+     * startTimer 之前到达的停止。startTimer 消费后返回已 abort 的 signal，且不调用 onTimeout。
+     * clearTimer 只在计时器已经启动时清掉残留，避免把还没被 startTimer 看到的停止丢掉。
+     */
+    private readonly pendingAborts;
     private readonly defaultTimeoutMs;
     constructor(options?: TaskTimeoutManagerOptions);
     /**
@@ -39,6 +45,11 @@ export declare class TaskTimeoutManager {
      * @throws 如果该 taskId 已存在活跃计时器
      */
     startTimer(taskId: string, timeoutMs: number | undefined, onTimeout: () => Promise<void>): AbortSignal;
+    /**
+     * 停止这一轮。清掉计时器，不调用 onTimeout。
+     * 计时器还没启动时记下 kind，等 startTimer 返回已 abort 的 signal。
+     */
+    abort(taskId: string, kind?: TaskAbortKind): boolean;
     /**
      * 取消超时计时器（Task 正常完成时调用）
      *

package/dist/task/task-timeout.js

@@ -10,6 +10,7 @@
  * @see requirements.md Requirement 7 AC4
  */
 import { DEFAULT_GRAPH_TIMEOUT_MS } from '../common/types.js';
+import { TaskAbortError } from './task-abort.js';
 // ─────────────────────────────────────────────
 // Default Constants
 // ─────────────────────────────────────────────
@@ -31,6 +32,11 @@ const MAX_TIMEOUT_MS = 3_600_000;
  */
 export class TaskTimeoutManager {
     entries = new Map();
+    /**
+     * startTimer 之前到达的停止。startTimer 消费后返回已 abort 的 signal，且不调用 onTimeout。
+     * clearTimer 只在计时器已经启动时清掉残留，避免把还没被 startTimer 看到的停止丢掉。
+     */
+    pendingAborts = new Map();
     defaultTimeoutMs;
     constructor(options) {
         this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -49,12 +55,22 @@ export class TaskTimeoutManager {
             throw new Error(`Timeout timer already exists for task '${taskId}'. Call clearTimer() first.`);
         }
         const effectiveTimeout = Math.min(Math.max(timeoutMs ?? this.defaultTimeoutMs, 0), MAX_TIMEOUT_MS);
+        const pendingKind = this.pendingAborts.get(taskId);
+        if (pendingKind) {
+            this.pendingAborts.delete(taskId);
+            const already = new AbortController();
+            already.abort(new TaskAbortError(taskId, pendingKind, effectiveTimeout));
+            return already.signal;
+        }
         const abortController = new AbortController();
         const timer = setTimeout(() => {
-            // 超时触发：abort signal + 执行回调
-            abortController.abort(new Error(`Task '${taskId}' timed out after ${effectiveTimeout}ms`));
+            // abort() 已取走条目时不再标 timeout
+            if (!this.entries.has(taskId))
+                return;
             this.entries.delete(taskId);
-            // 触发外部回调（fire-and-forget，错误不应阻塞清理）
+            if (!abortController.signal.aborted) {
+                abortController.abort(new TaskAbortError(taskId, 'timeout', effectiveTimeout));
+            }
             void onTimeout().catch(() => {
                 // onTimeout 回调的错误由调用方处理，这里静默忽略
             });
@@ -63,9 +79,27 @@ export class TaskTimeoutManager {
         if (timer.unref) {
             timer.unref();
         }
-        this.entries.set(taskId, { timer, abortController });
+        this.entries.set(taskId, { timer, abortController, timeoutMs: effectiveTimeout });
         return abortController.signal;
     }
+    /**
+     * 停止这一轮。清掉计时器，不调用 onTimeout。
+     * 计时器还没启动时记下 kind，等 startTimer 返回已 abort 的 signal。
+     */
+    abort(taskId, kind = 'cancelled') {
+        this.pendingAborts.delete(taskId);
+        const entry = this.entries.get(taskId);
+        if (!entry) {
+            this.pendingAborts.set(taskId, kind);
+            return true;
+        }
+        clearTimeout(entry.timer);
+        this.entries.delete(taskId);
+        if (!entry.abortController.signal.aborted) {
+            entry.abortController.abort(new TaskAbortError(taskId, kind, entry.timeoutMs));
+        }
+        return true;
+    }
     /**
      * 取消超时计时器（Task 正常完成时调用）
      *
@@ -79,6 +113,7 @@ export class TaskTimeoutManager {
         }
         clearTimeout(entry.timer);
         this.entries.delete(taskId);
+        this.pendingAborts.delete(taskId);
         return true;
     }
     /**
@@ -113,5 +148,6 @@ export class TaskTimeoutManager {
             entry.abortController.abort(new Error(`TaskTimeoutManager disposed, task '${taskId}' aborted`));
         }
         this.entries.clear();
+        this.pendingAborts.clear();
     }
 }