@gt-fe/eap-runtime 0.0.30 → 0.0.32

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

@@ -16,6 +16,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { buildHitlWaitingTaskOutput, loadModelFacingHistory, messageRecordsToGraphMessages, persistGraphMessageBaseline, turnGraphMessagesAfterCompression, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, resolveCheckpointThreadId, sessionVisibleGraphMessages, } from '../../session/persist-turn-messages.js';
+import { applyInjectedAssistant, collectPublicArtifactLinks, injectPublicArtifactLinks, } from '../../tool/inject-public-artifact-links.js';
 import { SessionBudgetExhaustedError } from '../../token/session-budget-checker.js';
 import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
 import { recordTaskTokenUsages, tokenUsagesFromLlmChannel, } from '../../token/record-task-token-usage.js';
@@ -380,21 +381,24 @@ export class InvokeOrchestrator {
                 },
             ]);
         }
-        // ─── Step 7: 完成 Task (running → success) ───
-        await this.taskService.updateStatus(task.id, 'success', graphResult.output);
         // ─── Step 7b: 持久化本轮 transcript（统一顺序：assistant tool_calls → tool → assistant 文本）───
         // 切点是入图 messages 基线（压缩 `__set` 后 Graph 短于 Session 全文）。user 已在 4b 写入。
         const allMessages = Array.isArray(graphResult.finalState?.messages)
             ? graphResult.finalState.messages
             : [];
         const newMessages = sessionVisibleGraphMessages(allMessages.slice(persistBaseline), finishPoints);
+        const links = collectPublicArtifactLinks(allMessages);
+        const { injected } = injectPublicArtifactLinks(graphResult.output ?? '', links);
+        const persisted = applyInjectedAssistant(newMessages, injected, links);
+        // ─── Step 7: 完成 Task (running → success) ───
+        await this.taskService.updateStatus(task.id, 'success', injected);
         const duration = Date.now() - startTime;
         await persistTurnTranscript(this.messageService, {
             sessionId,
             taskId: task.id,
             correlationId,
-            messages: newMessages,
-            fallbackAssistantContent: graphResult.output ?? '',
+            messages: persisted,
+            fallbackAssistantContent: injected,
             assistantTokenCount: tokenUsage.output,
             assistantDurationMs: duration,
         });
@@ -404,7 +408,7 @@ export class InvokeOrchestrator {
         return this.buildResponse(traceId, {
             taskId: task.id,
             sessionId,
-            output: graphResult.output,
+            output: injected,
             tokenUsage,
             duration,
             status: 'success',

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

@@ -20,6 +20,7 @@
  * @see requirements.md Requirement 11 AC2
  */
 import { buildHitlWaitingTaskOutput, buildTurnTranscriptFromStreamEvents, loadModelFacingHistory, turnGraphMessagesAfterCompression, extractStreamReasoning, applyStreamTextDelta, createStreamAssistantBuckets, visibleStreamAssistantText, streamAssistantTexts, messageRecordsToGraphMessages, persistHitlWaitingPlaceholder, persistTurnTranscript, persistUserTurnMessage, appendTerminalToolResult, } from '../../session/persist-turn-messages.js';
+import { collectPublicArtifactLinks, collectPublicArtifactLinksFromEvent, injectPublicArtifactLinks, mergeArtifactLinks, } from '../../tool/inject-public-artifact-links.js';
 import { SessionBudgetExhaustedError } from '../../token/session-budget-checker.js';
 import { TokenBudgetExhaustedError } from '../../token/token-budget-guard.js';
 import { recordTaskTokenUsages } from '../../token/record-task-token-usage.js';
@@ -268,6 +269,7 @@ export class StreamOrchestrator {
         let assistantReasoningContent;
         const pendingToolCalls = [];
         const toolResults = [];
+        const artifactLinks = [];
         // ─── Step 6: Graph.stream() 流式执行 ───
         try {
             const eventStream = runWithExecutionTrace({ abortSignal }, () => this.graphEngine.stream(graph, {
@@ -326,6 +328,7 @@ export class StreamOrchestrator {
                     }
                 }
                 appendTerminalToolResult(runtimeEvent.type, runtimeEvent.payload, toolResults);
+                collectPublicArtifactLinksFromEvent(runtimeEvent.type, runtimeEvent.payload, artifactLinks);
                 const streamedReasoning = extractStreamReasoning(runtimeEvent.type, runtimeEvent.payload);
                 if (streamedReasoning)
                     assistantReasoningContent = streamedReasoning;
@@ -387,10 +390,18 @@ export class StreamOrchestrator {
             this.timeoutManager?.clearTimer(taskId);
         }
         // ─── Step 7: 发送结束事件序列 ───
-        // Emit: response.final（带完整 assistant 文本，供客户端兜底）
         const tokenStats = this.tokenStatsService.getTaskStats(taskId);
+        const visible = visibleStreamAssistantText(assistantBuckets);
+        const links = mergeArtifactLinks(artifactLinks, collectPublicArtifactLinks(toolResults));
+        const { injected, suffix } = injectPublicArtifactLinks(visible, links);
+        if (suffix) {
+            emitter.emit(this.buildSSEEvent('response.chunk', correlationId, taskId, {
+                content: suffix,
+                format: 'text',
+            }));
+        }
         emitter.emit(this.buildSSEEvent('response.final', correlationId, taskId, {
-            content: visibleStreamAssistantText(assistantBuckets),
+            content: injected,
             format: 'text',
         }));
         const totalTokens = (tokenStats.total.input ?? 0) + (tokenStats.total.output ?? 0);
@@ -424,8 +435,8 @@ export class StreamOrchestrator {
             messages: buildTurnTranscriptFromStreamEvents({
                 pendingToolCalls,
                 toolResults,
-                assistantTexts: streamAssistantTexts(assistantBuckets),
-                assistantText: visibleStreamAssistantText(assistantBuckets),
+                assistantTexts: suffix ? undefined : streamAssistantTexts(assistantBuckets),
+                assistantText: injected,
                 finishPoints: graph.finishPoints,
                 toolCallReasoningContent,
                 assistantReasoningContent,

package/dist/common/index.d.ts

@@ -4,3 +4,4 @@ export * from './health.js';
 export * from './agent-code.js';
 export * from './trace-id.js';
 export { RUNTIME_PACKAGE_VERSION } from './runtime-package-version.js';
+export { userRoot, USERS_DIR_NAME, MISSING_USER_DIR } from './user-root.js';

package/dist/common/index.js

@@ -4,3 +4,4 @@ export * from './health.js';
 export * from './agent-code.js';
 export * from './trace-id.js';
 export { RUNTIME_PACKAGE_VERSION } from './runtime-package-version.js';
+export { userRoot, USERS_DIR_NAME, MISSING_USER_DIR } from './user-root.js';

package/dist/common/user-root.d.ts

@@ -0,0 +1,8 @@
+export declare const MISSING_USER_DIR = "\u7F3A\u5C11\u7528\u6237\u76EE\u5F55\uFF0C\u62D2\u7EDD\u8BE5\u64CD\u4F5C";
+/** `agents/<code>/users/`：与 `<ver>` 平级，不是版本目录。 */
+export declare const USERS_DIR_NAME = "users";
+/**
+ * jail 写根：`dirname(agentDir)/users/<userId>`。
+ * `agentDir` 仍是版本目录 `agents/<code>/<ver>`。
+ */
+export declare function userRoot(agentDir: string, userId: string): string;

package/dist/common/user-root.js

@@ -0,0 +1,19 @@
+import path from 'node:path';
+export const MISSING_USER_DIR = '缺少用户目录，拒绝该操作';
+/** `agents/<code>/users/`：与 `<ver>` 平级，不是版本目录。 */
+export const USERS_DIR_NAME = 'users';
+/**
+ * jail 写根：`dirname(agentDir)/users/<userId>`。
+ * `agentDir` 仍是版本目录 `agents/<code>/<ver>`。
+ */
+export function userRoot(agentDir, userId) {
+    const dir = agentDir.trim();
+    const uid = userId.trim();
+    if (!dir || !uid) {
+        throw new Error(MISSING_USER_DIR);
+    }
+    if (uid === '.' || uid === '..' || /[\\/]/.test(uid)) {
+        throw new Error('非法用户标识');
+    }
+    return path.resolve(path.dirname(dir), USERS_DIR_NAME, uid);
+}

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

@@ -34,8 +34,8 @@ import { preloadSkillNotFound } from '../../registry/preload-errors.js';
 import { AppError, ErrorCodes } from '@gt-fe/eap-contracts';
 import { pickContextFields } from '../../token/context-window.js';
 import { isHitlDecision, lastAssistantHasUnansweredToolCalls } from '../hitl/hitl-handler.js';
-import { classifySkillRead } from './skill-read.js';
-import { skillEntryInvocationFromTool } from './skill-entry-span.js';
+import { classifySkillFile, isReadTool } from './skill-read.js';
+import { recordSkillEntrySpan, skillEntryInvocationFromTool } from './skill-entry-span.js';
 import { llmSpanInput, llmSpanOutputFromResult, withGraphSpan } from '../trace-span.js';
 import { executionTraceFromState, getExecutionStream, getExecutionTrace, runWithExecutionTrace, } from '../execution-trace-context.js';
 import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
@@ -283,8 +283,10 @@ export class LangGraphAdapter {
             ...(progress.node ? { node: progress.node } : {}),
             ...(progress.skillId ? { skillId: progress.skillId } : {}),
         };
-        const skillRead = classifySkillRead(progress.toolName, progress.arguments, progress.skillDirs);
-        if (skillRead && progress.status === 'completed') {
+        const skillRead = progress.status === 'completed' && progress.resolvedPath && isReadTool(progress.toolName)
+            ? classifySkillFile(progress.resolvedPath, progress.skillDirs)
+            : null;
+        if (skillRead) {
             if (skillRead.kind === 'loaded') {
                 const skillId = skillRead.skillId || loc.skillId || skillRead.path;
                 stream.sink({
@@ -299,7 +301,7 @@ export class LangGraphAdapter {
                 });
                 const catalogSkill = skillEntryInvocationFromTool({
                     toolName: progress.toolName,
-                    arguments: progress.arguments,
+                    resolvedPath: progress.resolvedPath,
                     skillDirs: progress.skillDirs,
                     alreadyInSkillSpan: progress.inSkillSubgraph,
                 });
@@ -355,12 +357,14 @@ export class LangGraphAdapter {
                 },
             });
         }
+        // resolvedPath / skillDirs 只给上面 classifySkillFile；inSkillSubgraph 只给 skill.started 去重。不进对话流。
+        const { resolvedPath: _resolvedPath, skillDirs: _skillDirs, inSkillSubgraph: _inSkillSubgraph, ...progressView } = progress;
         stream.sink({
             type: 'tool.progress',
             taskId,
             correlationId,
             timestamp,
-            payload: { ...progress },
+            payload: progressView,
         });
         if (progress.status === 'completed') {
             stream.sink({
@@ -374,6 +378,8 @@ export class LangGraphAdapter {
                     ...(progress.toolset ? { toolset: progress.toolset } : {}),
                     content: progress.content,
                     success: true,
+                    ...(progress.file ? { file: progress.file } : {}),
+                    ...(progress.files?.length ? { files: progress.files } : {}),
                     ...loc,
                 },
             });
@@ -390,6 +396,9 @@ export class LangGraphAdapter {
                     ...(progress.toolset ? { toolset: progress.toolset } : {}),
                     error: progress.error ?? 'Unknown error',
                     willRetry: progress.willRetry === true,
+                    ...(progress.content ? { content: progress.content } : {}),
+                    ...(progress.file ? { file: progress.file } : {}),
+                    ...(progress.files?.length ? { files: progress.files } : {}),
                     ...loc,
                 },
             });
@@ -931,6 +940,13 @@ export class LangGraphAdapter {
                     node: node.id,
                 });
                 const skillDefs = state['skillDefinitions'];
+                const jail = resolveJailFromState({
+                    agentDir: state['agentDir'],
+                    userId: state['userId'],
+                    executionContext: state['executionContext'],
+                    loadedTools: state['loadedTools'],
+                    skillDefinitions: skillDefs,
+                });
                 const jailExtraRoots = Object.values(skillDefs ?? {})
                     .map((skill) => skill.bundlePath)
                     .filter((p) => Boolean(p));
@@ -941,6 +957,7 @@ export class LangGraphAdapter {
                     authContext: { userId, delegationToken, agentCode },
                     correlationId,
                     taskId,
+                    ...(jail.workdir ? { jailWorkdir: jail.workdir } : {}),
                     ...(jailExtraRoots.length > 0 ? { jailExtraRoots } : {}),
                 };
                 const retry = resolveToolRetryConfig(node.retry);
@@ -976,13 +993,21 @@ export class LangGraphAdapter {
                     executionTime,
                     node: node.id,
                     ...(skillDirs.length > 0 ? { skillDirs } : {}),
+                    ...(result.resolvedPath ? { resolvedPath: result.resolvedPath } : {}),
                 });
+                if (result.success) {
+                    await recordSkillEntrySpan(state, {
+                        toolName: result.toolName,
+                        resolvedPath: result.resolvedPath,
+                        skillDirs,
+                    });
+                }
                 // 重要：messages channel 的 reducer 是 append 语义，只返回新增消息
                 return {
                     messages: [
                         {
                             role: 'tool',
-                            content: result.content || JSON.stringify(result),
+                            content: result.content ?? '',
                             toolCallId,
                             toolName,
                             success: result.success ?? true,
@@ -1592,10 +1617,20 @@ export class LangGraphAdapter {
                     continue;
                 }
                 if (msg.role === 'tool') {
-                    // tool.result / tool.error 由 Tool 节点旁路发出，此处只补 file.created
+                    // tool.result / tool.error 由 Tool 节点旁路发出（已带 file/files）；此处再补 file.created
                     const raw = typeof msg.content === 'string' ? msg.content : '';
-                    const file = msg.file ?? fileArtifactFromToolOutput(raw);
-                    if (file) {
+                    const files = [
+                        ...(msg.file ? [msg.file] : []),
+                        ...(msg.files ?? []),
+                    ];
+                    if (files.length === 0) {
+                        const parsed = fileArtifactFromToolOutput(raw);
+                        if (parsed)
+                            files.push(parsed);
+                    }
+                    for (const file of files) {
+                        if (!file?.url)
+                            continue;
                         yield {
                             type: 'file.created',
                             taskId: undefined,
@@ -1662,6 +1697,7 @@ export class LangGraphAdapter {
                 success: typeof m['success'] === 'boolean' ? m['success'] : undefined,
                 reasoningContent: typeof m['reasoningContent'] === 'string' ? m['reasoningContent'] : undefined,
                 file: readFileArtifact(m['file']),
+                files: readFileArtifactList(m['files']),
             };
         });
     }
@@ -1679,3 +1715,14 @@ function readFileArtifact(value) {
         url: rec.url,
     };
 }
+function readFileArtifactList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const out = [];
+    for (const item of value) {
+        const file = readFileArtifact(item);
+        if (file)
+            out.push(file);
+    }
+    return out.length > 0 ? out : undefined;
+}

package/dist/graph/adapters/skill-entry-span.d.ts

@@ -2,6 +2,8 @@
  * 成功读 SKILL.md 时写 Trace `type=skill` Span。
  *
  * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 入口是执行器返回的实际文件（resolvedPath）对已装配 skillDirs。
+ * 没有实际路径不记，不再用 arguments.path 猜。
  * 与子图激活走同一 collector.createNode({ type: 'skill' })。
  * 声明版本在 createNode.version；skillSpace 只在 input。
  * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
@@ -23,7 +25,7 @@ export declare function skillSpanFields(identity: SkillTraceIdentity, extra?: {
 };
 export declare function skillEntryInvocationFromTool(input: {
     toolName: string;
-    arguments?: Record<string, unknown>;
+    resolvedPath?: string;
     skillDirs?: SkillDirRef[];
     alreadyInSkillSpan?: boolean;
 }): {
@@ -32,6 +34,6 @@ export declare function skillEntryInvocationFromTool(input: {
 } | null;
 export declare function recordSkillEntrySpan(state: Record<string, unknown>, input: {
     toolName: string;
-    arguments?: Record<string, unknown>;
+    resolvedPath?: string;
     skillDirs?: SkillDirRef[];
 }): Promise<void>;

package/dist/graph/adapters/skill-entry-span.js

@@ -2,11 +2,13 @@
  * 成功读 SKILL.md 时写 Trace `type=skill` Span。
  *
  * 假设：Skill 被调用 = 一次成功读取技能包入口（SKILL.md），
+ * 入口是执行器返回的实际文件（resolvedPath）对已装配 skillDirs。
+ * 没有实际路径不记，不再用 arguments.path 猜。
  * 与子图激活走同一 collector.createNode({ type: 'skill' })。
  * 声明版本在 createNode.version；skillSpace 只在 input。
  * 子图已有 skillSpanId 时不记第二条。write_file / 包内附属读 / 失败读不是调用。
  */
-import { classifySkillRead, classifySkillSpace } from './skill-read.js';
+import { classifySkillFile, classifySkillSpace, isReadTool, } from './skill-read.js';
 import { completeGraphSpan, startGraphSpan } from '../trace-span.js';
 function declaredSkillVersion(skillId, version) {
     const raw = version?.trim();
@@ -46,7 +48,12 @@ export function skillSpanFields(identity, extra) {
 export function skillEntryInvocationFromTool(input) {
     if (input.alreadyInSkillSpan)
         return null;
-    const hit = classifySkillRead(input.toolName, input.arguments, input.skillDirs);
+    if (!isReadTool(input.toolName))
+        return null;
+    const resolved = input.resolvedPath?.trim();
+    if (!resolved)
+        return null;
+    const hit = classifySkillFile(resolved, input.skillDirs);
     if (!hit || hit.kind !== 'loaded' || !hit.skillId)
         return null;
     return { skillId: hit.skillId, path: hit.path };
@@ -55,7 +62,7 @@ export async function recordSkillEntrySpan(state, input) {
     const alreadyInSkillSpan = typeof state['skillSpanId'] === 'string' && Boolean(state['skillSpanId']);
     const hit = skillEntryInvocationFromTool({
         toolName: input.toolName,
-        arguments: input.arguments,
+        resolvedPath: input.resolvedPath,
         skillDirs: input.skillDirs,
         alreadyInSkillSpan,
     });

package/dist/graph/adapters/skill-read.d.ts

@@ -12,10 +12,26 @@ export declare function classifySkillSpace(bundleOrFilePath: string, opts?: {
     agentDir?: string;
     userId?: string;
 }): SkillSpace | undefined;
+/** 与 Harness `read_file` 相同的相对路径定位（workdir / skillDir / overlay extraRoots）。 */
+export interface SkillReadLocate {
+    workdir?: string;
+    skillDir?: string;
+    extraRoots?: string[];
+}
+export declare function isReadTool(toolName: string): boolean;
+/**
+ * 实际读到的文件是否落在已装配技能包内。不解析定位符。
+ */
+export declare function classifySkillFile(absPath: string, skillDirs?: SkillDirRef[]): {
+    kind: 'loaded' | 'resource';
+    path: string;
+    skillId: string;
+} | null;
 /**
- * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
+ * 给 EAP_SKILL_DIR 推断：把 `arguments.path` 按 Harness 规则落到文件再对 skillDirs。
+ * Trace / SSE 入口判定走 `classifySkillFile`（实际读到的文件），不走这里。
  */
-export declare function classifySkillRead(toolName: string, args: Record<string, unknown> | undefined, skillDirs?: SkillDirRef[]): {
+export declare function classifySkillRead(toolName: string, args: Record<string, unknown> | undefined, skillDirs?: SkillDirRef[], locate?: SkillReadLocate): {
     kind: 'loaded' | 'resource';
     path: string;
     skillId: string;

package/dist/graph/adapters/skill-read.js

@@ -1,5 +1,7 @@
 import { realpathSync } from 'node:fs';
 import path from 'node:path';
+import { userRoot } from '../../common/user-root.js';
+import { resolveSkillReadTarget } from '../../tool/skill-relative-read.js';
 function tryRealpath(p) {
     try {
         return realpathSync(p);
@@ -29,10 +31,6 @@ function longestSkillMatch(filePath, skillDirs) {
     }
     return best;
 }
-function skillIdFromSkillsSegment(norm) {
-    const match = norm.match(/(?:^|\/)(?:preinstall\/)?skills\/([^/]+)(?:\/|$)/i);
-    return match?.[1] ?? '';
-}
 /**
  * 按实际 bundle 路径判定空间。有 agentDir 时相对预装根与 users/ 判定；
  * 否则看路径段 `preinstall/skills` / `users/<id>/skills`。
@@ -49,12 +47,20 @@ export function classifySkillSpace(bundleOrFilePath, opts) {
             return 'agent';
         const uid = opts?.userId?.trim();
         if (uid) {
-            const user = `${root}/users/${uid}/skills`;
-            if (target === user || target.startsWith(`${user}/`))
-                return 'user';
+            try {
+                const user = normalizeForMatch(path.join(userRoot(agentDir, uid), 'skills'));
+                if (target === user || target.startsWith(`${user}/`))
+                    return 'user';
+            }
+            catch {
+                // 非法 userId 时不按用户槽判定
+            }
         }
-        if (new RegExp(`^${escapeRegExp(root)}/users/[^/]+/skills(/|$)`).test(target))
+        const usersRoot = normalizeForMatch(path.join(path.dirname(agentDir), 'users'));
+        if ((target === usersRoot || target.startsWith(`${usersRoot}/`)) &&
+            /(^|\/)skills(\/|$)/.test(target.slice(usersRoot.length))) {
             return 'user';
+        }
         return 'local';
     }
     if (/(^|\/)preinstall\/skills(\/|$)/i.test(target))
@@ -63,34 +69,63 @@ export function classifySkillSpace(bundleOrFilePath, opts) {
         return 'user';
     return undefined;
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+function extraRootsForSkillRead(skillDirs, locate) {
+    const out = [];
+    for (const dir of skillDirs ?? []) {
+        if (dir.bundlePath)
+            out.push(dir.bundlePath);
+    }
+    for (const root of locate?.extraRoots ?? []) {
+        if (root)
+            out.push(root);
+    }
+    return out;
+}
+export function isReadTool(toolName) {
+    const n = toolName.toLowerCase().replace(/-/g, '_');
+    return n === 'read_file' || n === 'read_skill_file' || n === 'readfile';
 }
 /**
- * 判断 harness 读操作是否命中技能包，并用 bundlePath 最长前缀解析 skillId。
+ * 实际读到的文件是否落在已装配技能包内。不解析定位符。
  */
-export function classifySkillRead(toolName, args, skillDirs) {
-    const n = toolName.toLowerCase().replace(/-/g, '_');
-    if (n !== 'read_file' && n !== 'read_skill_file' && n !== 'readfile')
+export function classifySkillFile(absPath, skillDirs) {
+    const trimmed = absPath.trim();
+    if (!trimmed)
+        return null;
+    const matched = longestSkillMatch(trimmed, skillDirs);
+    if (!matched)
+        return null;
+    const resolved = normalizeForMatch(trimmed);
+    const isEntry = /(^|\/)(SKILL\.md|skill.md)$/i.test(resolved);
+    return {
+        kind: isEntry ? 'loaded' : 'resource',
+        path: resolved,
+        skillId: matched.skillId,
+    };
+}
+/**
+ * 给 EAP_SKILL_DIR 推断：把 `arguments.path` 按 Harness 规则落到文件再对 skillDirs。
+ * Trace / SSE 入口判定走 `classifySkillFile`（实际读到的文件），不走这里。
+ */
+export function classifySkillRead(toolName, args, skillDirs, locate) {
+    if (!isReadTool(toolName))
         return null;
     const filePath = String(args?.path ?? args?.file ?? '');
     if (!filePath)
         return null;
-    const norm = filePath.replace(/\\/g, '/');
-    const matched = longestSkillMatch(filePath, skillDirs);
-    const isEntry = /(^|\/)(SKILL\.md|skill\.md)$/i.test(norm);
-    if (matched) {
-        return {
-            kind: isEntry ? 'loaded' : 'resource',
-            path: filePath,
-            skillId: matched.skillId,
-        };
-    }
-    if (isEntry) {
-        return { kind: 'loaded', path: filePath, skillId: skillIdFromSkillsSegment(norm) };
-    }
-    if (/(^|\/)(?:preinstall\/)?skills\//i.test(norm)) {
-        return { kind: 'resource', path: filePath, skillId: skillIdFromSkillsSegment(norm) };
-    }
-    return null;
+    const target = resolveSkillReadTarget(filePath, {
+        workdir: locate?.workdir,
+        skillDir: locate?.skillDir,
+        extraRoots: extraRootsForSkillRead(skillDirs, locate),
+    });
+    const matched = longestSkillMatch(target, skillDirs);
+    if (!matched)
+        return null;
+    const slash = target.replace(/\\/g, '/');
+    const isEntry = /(^|\/)(SKILL\.md|skill.md)$/i.test(slash);
+    return {
+        kind: isEntry ? 'loaded' : 'resource',
+        path: target,
+        skillId: matched.skillId,
+    };
 }

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

@@ -276,13 +276,19 @@ export interface GraphMessage {
      * 多轮请求必须原样回传，否则上游会 400。
      */
     reasoningContent?: string;
-    /** 工具产出的文件；仅 Runtime 发 file.created，不进模型正文 */
+    /** 工具产出的文件；SSE tool.result / tool.error 与 file.created 共用，不进模型正文 */
     file?: {
         fileName: string;
         fileType: string;
         size: number;
         url: string;
     };
+    files?: Array<{
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    }>;
 }
 /** Tool 调用信息 */
 export interface ToolCallInfo {

package/dist/graph/nodes/tool-node.d.ts

@@ -10,7 +10,7 @@
  * @see requirements.md Requirement 8 AC1, AC3, AC5
  */
 import type { NodeRetryConfig } from '../contracts/executable-graph.js';
-import type { AuthContext } from '../../tool/tool-executor.interface.js';
+import type { AuthContext, ToolCallResult } from '../../tool/tool-executor.interface.js';
 import type { ToolOrchestrator } from '../../tool/tool-orchestrator.js';
 import type { ToolResultInjector } from '../../tool/tool-result-injector.js';
 import type { SkillDirRef } from '../adapters/skill-read.js';
@@ -41,10 +41,15 @@ export interface ToolNodeProgress {
     arguments?: Record<string, unknown>;
     content?: string;
     error?: string;
+    /** 与 ToolCallResult.file / files 同形；completed 与失败终态都带 */
+    file?: ToolCallResult['file'];
+    files?: ToolCallResult['files'];
     executionTime?: number;
     node?: string;
     skillId?: string;
     skillDirs?: SkillDirRef[];
+    /** read_file 实际读到的文件；与 ToolCallResult.resolvedPath 相同 */
+    resolvedPath?: string;
     /** 已在 Skill 子图内（state.skillSpanId）；读 SKILL.md 不再发 skill.started */
     inSkillSubgraph?: boolean;
     skillSpace?: 'agent' | 'user' | 'local';

package/dist/graph/nodes/tool-node.js

@@ -19,9 +19,17 @@ import { resolveCheckpointThreadId } from '../../session/persist-turn-messages.j
 import { mcpToolsetCode, toolTraceIdentity } from '../../tool/mcp-list.js';
 import { resolveExecutionTrace, warnTraceSpanFailure, } from '../execution-trace-context.js';
 import { emitRuntimeLog } from '../../common/logger.js';
+import { toolResultHasArtifacts } from '../../tool/inject-public-artifact-links.js';
 import { decideBeforeTool, } from '../../execution/interceptors.js';
 import { isRetryableToolFailure, resolveToolRetryConfig, sleepToolRetry, toolRetryDelayMs, } from '../../tool/tool-retry.js';
 import { isIsolatedSkillState } from '../adapters/skill-isolate.js';
+function toolArtifactFields(result) {
+    return {
+        ...(result.content ? { content: result.content } : {}),
+        ...(result.file ? { file: result.file } : {}),
+        ...(result.files?.length ? { files: result.files } : {}),
+    };
+}
 function skillDirsFromState(state) {
     const defs = state['skillDefinitions'];
     return Object.values(defs ?? {})
@@ -287,7 +295,7 @@ export class ToolNode {
                 if (result.success) {
                     const catalog = skillEntryInvocationFromTool({
                         toolName: req.toolName,
-                        arguments: req.arguments,
+                        resolvedPath: result.resolvedPath,
                         skillDirs,
                         alreadyInSkillSpan: inSkillSubgraph,
                     });
@@ -302,7 +310,9 @@ export class ToolNode {
                         status: 'completed',
                         arguments: req.arguments,
                         content: result.content,
+                        ...toolArtifactFields(result),
                         executionTime,
+                        ...(result.resolvedPath ? { resolvedPath: result.resolvedPath } : {}),
                         ...(skillIdentity?.skillSpace ? { skillSpace: skillIdentity.skillSpace } : {}),
                         ...(skillIdentity?.skillVersion ? { skillVersion: skillIdentity.skillVersion } : {}),
                         ...(skillIdentity?.skillName ? { skillName: skillIdentity.skillName } : {}),
@@ -317,6 +327,7 @@ export class ToolNode {
                         status: 'error',
                         arguments: req.arguments,
                         error: result.error ?? 'unknown error',
+                        ...toolArtifactFields(result),
                         executionTime,
                     });
                 }
@@ -336,7 +347,7 @@ export class ToolNode {
                 if (result.success) {
                     await recordSkillEntrySpan(state, {
                         toolName: req.toolName,
-                        arguments: req.arguments,
+                        resolvedPath: result.resolvedPath,
                         skillDirs,
                     });
                 }
@@ -421,12 +432,15 @@ export class ToolNode {
             role: 'tool',
             content: result.success
                 ? result.content
-                : `[Tool Error] ${result.error ?? 'unknown error'}`,
+                : toolResultHasArtifacts(result) && result.content
+                    ? `${result.content}\n[Tool Error] ${result.error ?? 'unknown error'}`
+                    : `[Tool Error] ${result.error ?? 'unknown error'}`,
             // 以下字段符合 LLM function-calling 协议（ToolMessage 接口）
             toolCallId: result.toolCallId,
             toolName: result.toolName,
             success: result.success,
             ...('file' in result && result.file ? { file: result.file } : {}),
+            ...('files' in result && result.files?.length ? { files: result.files } : {}),
         }));
         const lastSpanId = [...spanIds].reverse().find((id) => Boolean(id));
         return {
@@ -477,6 +491,7 @@ export class ToolNode {
                 status: 'error',
                 arguments: req.arguments,
                 error: last.error ?? 'unknown error',
+                ...toolArtifactFields(last),
                 willRetry: true,
             });
             await sleepToolRetry(toolRetryDelayMs(attempt, retry.backoff));