@gt-fe/eap-runtime 0.0.32 → 0.0.34

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();
     }
 }

package/dist/task/task.service.js

@@ -16,16 +16,17 @@ import { TaskProgressTracker } from './task-progress-tracker.js';
  * 合法状态流转映射
  *
  * pending → running
- * running → success | failed | timeout | token_exhausted
+ * running → success | failed | timeout | token_exhausted | cancelled | waiting_hitl
  */
 const VALID_TRANSITIONS = {
-    pending: ['running'],
-    running: ['success', 'failed', 'timeout', 'token_exhausted', 'waiting_hitl'],
-    waiting_hitl: ['running', 'timeout', 'failed'],
+    pending: ['running', 'cancelled'],
+    running: ['success', 'failed', 'timeout', 'token_exhausted', 'cancelled', 'waiting_hitl'],
+    waiting_hitl: ['running', 'timeout', 'failed', 'cancelled'],
     success: [],
     failed: [],
     timeout: [],
     token_exhausted: [],
+    cancelled: [],
 };
 // ─────────────────────────────────────────────
 // In-Memory Repository (Default)
@@ -128,7 +129,11 @@ export class TaskService {
         if (status === 'waiting_hitl' && output !== undefined) {
             task.output = output;
         }
-        if (status === 'success' || status === 'failed' || status === 'timeout' || status === 'token_exhausted') {
+        if (status === 'success' ||
+            status === 'failed' ||
+            status === 'timeout' ||
+            status === 'token_exhausted' ||
+            status === 'cancelled') {
             task.completedAt = now;
             if (output !== undefined) {
                 task.output = output;
@@ -215,6 +220,7 @@ export class TaskService {
             case 'failed':
             case 'timeout':
             case 'token_exhausted':
+            case 'cancelled':
                 return 100;
             default:
                 return 0;

package/dist/tool/index.d.ts

@@ -22,4 +22,4 @@ export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './s
 export { ToolResultInjector, type ToolMessage, } from './tool-result-injector.js';
 export { ToolEventEmitter } from './tool-event-emitter.js';
 export { ToolConfirmationInterceptor } from './tool-confirmation.js';
-export { SystemPromptBuilder, naturalTimeWindows, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, type PromptBuildContext, type PromptSection, type AssembledSystemPrompt, type ApiToolDefinition, type LoadedSkillInfo, type LoadedSkillMap, } from './system-prompt-builder.js';
+export { SystemPromptBuilder, naturalTimeWindows, buildSkillCatalog, catalogEntryTitle, spokenName, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, type PromptBuildContext, type PromptSection, type AssembledSystemPrompt, type ApiToolDefinition, type LoadedSkillInfo, type LoadedSkillMap, } from './system-prompt-builder.js';

package/dist/tool/index.js

@@ -21,4 +21,4 @@ export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './s
 export { ToolResultInjector, } from './tool-result-injector.js';
 export { ToolEventEmitter } from './tool-event-emitter.js';
 export { ToolConfirmationInterceptor } from './tool-confirmation.js';
-export { SystemPromptBuilder, naturalTimeWindows, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, } from './system-prompt-builder.js';
+export { SystemPromptBuilder, naturalTimeWindows, buildSkillCatalog, catalogEntryTitle, spokenName, loadedToolsToApiTools, toLoadedSkillMap, filterLoadedToolsForSkill, } from './system-prompt-builder.js';

package/dist/tool/mcp-list.d.ts

@@ -53,17 +53,19 @@ export declare function mcpToolsetCode(loaded: {
         execution?: unknown;
     };
 } | undefined): string | undefined;
-/** Tool Span：工具集 code + 声明版本。与 Skill 的 skillSpace/version 同一假设。 */
+/** Tool Span：工具集 code + 声明版本 + 展示名（与函数名不同才写）。 */
 export declare function toolTraceIdentity(loaded: {
     toolId?: string;
     name?: string;
     manifest?: {
         id?: string;
+        name?: string;
         version?: string;
     };
 } | undefined, toolName: string): {
     toolset?: string;
     toolVersion?: string;
+    toolDisplayName?: string;
 };
 export interface HydrateMcpToolsAuth {
     authContext: AuthContext;

package/dist/tool/mcp-list.js

@@ -130,13 +130,16 @@ function declaredToolVersion(toolName, version) {
         return undefined;
     return raw;
 }
-/** Tool Span：工具集 code + 声明版本。与 Skill 的 skillSpace/version 同一假设。 */
+/** Tool Span：工具集 code + 声明版本 + 展示名（与函数名不同才写）。 */
 export function toolTraceIdentity(loaded, toolName) {
     const toolset = toolsetCodeFromLoaded(loaded);
     const toolVersion = declaredToolVersion(toolName, loaded?.manifest?.version);
+    const display = loaded?.manifest?.name?.trim();
+    const toolDisplayName = display && display !== toolName ? display : undefined;
     return {
         ...(toolset ? { toolset } : {}),
         ...(toolVersion ? { toolVersion } : {}),
+        ...(toolDisplayName ? { toolDisplayName } : {}),
     };
 }
 /**

package/dist/tool/system-prompt-builder.d.ts

@@ -7,8 +7,8 @@
  * ```
  * [平台规则常量]          ← 代码内置，安全约束 + 行为准则（最高优先级）
  * [当前时间]              ← 运行时动态注入（自然周等时间规则的判定基准）
- * [Agent 身份]            ← agentName / agentCode（目录身份，不是 prompts.system）
- * [可用工具短目录]        ← 名称 + 一句话用途；完整 schema 仍走 API tools
+ * [Agent 身份]            ← 展示名 agentName，缺省 agentCode（对用户说话，不是路由键）
+ * [可用技能短目录]        ← 展示名 + skillId + SKILL.md 路径（技能不是 function）
  * [Agent 基线]            ← agent.manifest.json prompts.system；非 silent LLM
  * [节点提示词]            ← Graph LLM 节点 config.systemPrompt / systemPromptFile
  * ```
@@ -16,7 +16,7 @@
  * 基线只走 GraphState.agentSystemPrompt，不写进节点 config。无图时节点无增量。
  * silent 节点不带基线。技能正文不灌 system。
  *
- * 工具 schema 走 API 的 tools 参数（见 loadedToolsToApiTools）；system 短目录给模型发现用，不是对用户报菜名。
+ * 工具只走 API 的 tools 参数（见 loadedToolsToApiTools），不写入 system。
  *
  * @see docs/status/module-status-and-backlog.md RT-5
  */
@@ -97,8 +97,6 @@ export interface PromptBuildContext {
     }>;
     /** 已装配 Skill 短目录；单独成段，不并进 Agent 基线 / 节点提示词 */
     skillCatalog?: string;
-    /** 已装配工具短目录（名称 + 用途）；schema 仍走 API tools */
-    toolCatalog?: string;
 }
 export interface PromptSection {
     id: string;
@@ -109,6 +107,10 @@ export interface AssembledSystemPrompt {
     text: string;
     sections: PromptSection[];
 }
+/** 对人展示的名称。有展示名用展示名，否则用编码。 */
+export declare function spokenName(displayName: string | undefined, code: string | undefined): string | undefined;
+/** 短目录标题：展示名在前，调用键在行内。名称与编码相同则只写编码。 */
+export declare function catalogEntryTitle(code: string, displayName: string | undefined, codePhrase: string): string;
 /**
  * 非 silent LLM 才带 Agent 基线；节点提示词空则省略。
  * silent 只保留节点增量（选技能 / JSON）。
@@ -125,7 +127,7 @@ export declare function resolveLlmPromptInputs(input: {
  * SystemPromptBuilder — 系统提示词拼接
  *
  * 具名段拼接（无模板引擎）。顺序固定，段标题用于排查。
- * 工具短目录进 system；完整 schema 走 API tools 参数。
+ * 工具只走 API tools 参数，不进 system。技能短目录进 system（技能不是 function）。
  * Agent 基线与节点提示词整段透传，不做 {{ }} 替换。
  */
 export declare class SystemPromptBuilder {
@@ -154,6 +156,8 @@ export declare function naturalTimeWindows(now?: Date): {
  * 方便 tool 模块的使用者按领域引用。
  */
 export type ApiToolDefinition = LLMToolDefinition;
+/** 展示名 + skillId，供 system「可用技能」段。read_file 仍用 skillId。 */
+export declare function buildSkillCatalog(defs: LoadedSkillMap | undefined): string | undefined;
 /**
  * 将平台的 LoadedToolMap 转为 OpenAI API 的 tools 参数
  *
@@ -164,6 +168,4 @@ export type ApiToolDefinition = LLMToolDefinition;
  * @param skillTools - 可选，当前 Skill 所需的工具名称列表（过滤子集）
  * @returns OpenAI API tools 参数数组
  */
-/** 名称 + 一句话用途，供 system「可用工具」段。schema 仍走 loadedToolsToApiTools。 */
-export declare function buildToolCatalog(loadedTools: LoadedToolMap | undefined): string | undefined;
 export declare function loadedToolsToApiTools(loadedTools: LoadedToolMap | undefined, skillTools?: string[]): ApiToolDefinition[];