@gt-fe/eap-runtime 0.0.30 → 0.0.31

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

@@ -30,6 +30,19 @@ export interface ToolResultPayload {
     content: unknown;
     /** 是否执行成功 */
     success: boolean;
+    /** 与 ToolCallResult.file 同形；SSE / persist / 注入共用 */
+    file?: {
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    };
+    files?: Array<{
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    }>;
 }
 /** 工具执行进度 */
 export type ToolProgressStatus = 'started' | 'completed' | 'error' | (string & {});
@@ -52,6 +65,8 @@ export interface ToolProgressPayload {
     content?: unknown;
     /** status=error 时可选：错误信息 */
     error?: string;
+    file?: ToolResultPayload['file'];
+    files?: ToolResultPayload['files'];
     /** 执行耗时（毫秒），status=completed|error 时可选 */
     executionTime?: number;
 }
@@ -65,4 +80,18 @@ export interface ToolErrorPayload {
     error: string;
     /** 是否会自动重试 */
     willRetry: boolean;
+    /** 失败且有交付物时保留原正文（与 ToolCallResult.content 同形） */
+    content?: unknown;
+    file?: {
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    };
+    files?: Array<{
+        fileName: string;
+        fileType: string;
+        size: number;
+        url: string;
+    }>;
 }

package/dist/tool/harness-command.d.ts

@@ -27,6 +27,6 @@ export declare function ensurePythonShims(workdir: string): string | undefined;
  * spawn 前替换成绝对路径，不依赖壳去展开。
  */
 export declare function substituteSkillDir(command: string, skillDir?: string): string;
-export declare function sandboxEnv(workdir: string, cwd: string, allowlist: string[], shimDir?: string, skillDir?: string): NodeJS.ProcessEnv;
+export declare function sandboxEnv(workdir: string, cwd: string, allowlist: string[], shimDir?: string, skillDir?: string, homeDir?: string): NodeJS.ProcessEnv;
 export declare function formatSpawnError(err: unknown, shellFile: string): Error;
 export declare function killProcessTree(child: ChildProcess): void;

package/dist/tool/harness-command.js

@@ -21,7 +21,7 @@ export function commandDialectLines(platform = process.platform) {
     else {
         lines.push('基础命令：当前目录 `pwd`；列目录 `ls`；环境变量 `$VAR`；串命令用 `&&`。');
     }
-    lines.push('解释器：`python`/`python3`、`node`/`nodejs`、`sh`/`bash`（Windows 上 `sh` 需本机有 Git Bash 等）。', '可执行文件：用绝对路径或相对于 cwd（Windows `.exe`/`.bat`/`.cmd`；Unix 二进制需可执行或用 `sh`）。', '`execute_command` 的 cwd 是用户目录。技能包只读。包内任意文件用 `EAP_SKILL_DIR` 加相对路径（不限 `scripts/`）。读到的 SKILL.md 里本包存在的相对路径已展开为绝对路径。不要把 cwd 设成技能目录。相对写出在用户目录。');
+    lines.push('解释器：`python`/`python3`、`node`/`nodejs`、`sh`/`bash`（Windows 上 `sh` 需本机有 Git Bash 等）。', '可执行文件：用绝对路径或相对于 cwd（Windows `.exe`/`.bat`/`.cmd`；Unix 二进制需可执行或用 `sh`）。', '`execute_command` 的 cwd 默认是用户目录下的 `files/`。技能包只读。包内任意文件用 `EAP_SKILL_DIR` 加相对路径（不限 `scripts/`）。读到的 SKILL.md 里本包存在的相对路径已展开为绝对路径。不要把 cwd 设成技能目录、`work/` 或 `public/`。相对写出在 `files/`。');
     return lines;
 }
 export function resolveShellSpawn(command, platform = process.platform) {
@@ -179,22 +179,23 @@ export function substituteSkillDir(command, skillDir) {
         .replace(/\$EAP_SKILL_DIR\b/g, dir)
         .replace(/%EAP_SKILL_DIR%/gi, dir);
 }
-export function sandboxEnv(workdir, cwd, allowlist, shimDir, skillDir) {
+export function sandboxEnv(workdir, cwd, allowlist, shimDir, skillDir, homeDir) {
     const win = process.platform === 'win32';
     const hostPath = process.env.PATH
         ?? (win
             ? (process.env.SystemRoot ? path.join(process.env.SystemRoot, 'System32') : 'C:\\Windows\\System32')
             : '/usr/bin:/bin:/usr/local/bin');
     const pathValue = shimDir ? `${shimDir}${path.delimiter}${hostPath}` : hostPath;
+    const home = homeDir?.trim() ? path.resolve(homeDir) : workdir;
     const env = {
         PATH: pathValue,
         LANG: process.env.LANG ?? 'C.UTF-8',
         LC_ALL: process.env.LC_ALL ?? process.env.LANG ?? 'C.UTF-8',
-        HOME: workdir,
-        USERPROFILE: workdir,
-        TMPDIR: workdir,
-        TMP: workdir,
-        TEMP: workdir,
+        HOME: home,
+        USERPROFILE: home,
+        TMPDIR: home,
+        TMP: home,
+        TEMP: home,
         PWD: cwd,
         PYTHONUTF8: '1',
         PYTHONIOENCODING: 'utf-8',

package/dist/tool/harness-primitives.d.ts

@@ -2,9 +2,9 @@
  * 平台默认 Harness 原语：read_file / write_file / execute_command。
  *
  * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
- * 写：`users/<userId>/`（含用户自己的 skills）。
+ * 写：`dirname(agentDir)/users/<userId>/`（含用户自己的 skills）。产物默认 `files/`，公开副本 `public/`。
  * 读：写根 + 已装配 `preinstall/tools`、`preinstall/skills`。
- * 命令：cwd 仅写根。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
+ * 命令：cwd 默认 `files/`。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
  * 开发态 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。在 `createDevRuntime` /
  * `createToolExecutor` 时钉进执行器 extraRoots；SDK `createAgent` 构造完会恢复 process.env，
  * 请求时不再读这两项。相对 `read_file` 会把 overlay 根下直接子目录里带 SKILL.md 的包纳入唯一命中。
@@ -19,7 +19,7 @@ export interface HarnessJailOptions {
     workdir?: string;
     extraRoots?: string[];
 }
-/** `{agentDir}/users/<userId>`（写根；含用户 skills） */
+/** `dirname(agentDir)/users/<userId>`（写根；含用户 skills） */
 export declare function resolveUserDir(agentDir: string, userId: string): string;
 export declare function collectToolBundlePaths(loadedTools?: LoadedToolMap): string[];
 export declare function resolveJailFromState(state: {

package/dist/tool/harness-primitives.js

@@ -2,20 +2,24 @@
  * 平台默认 Harness 原语：read_file / write_file / execute_command。
  *
  * 不写进 agent.manifest.toolsets。同名业务工具优先（问数 file-io 等）。
- * 写：`users/<userId>/`（含用户自己的 skills）。
+ * 写：`dirname(agentDir)/users/<userId>/`（含用户自己的 skills）。产物默认 `files/`，公开副本 `public/`。
  * 读：写根 + 已装配 `preinstall/tools`、`preinstall/skills`。
- * 命令：cwd 仅写根。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
+ * 命令：cwd 默认 `files/`。技能包只读，EAP_SKILL_DIR 为整包绝对根（不限 scripts/）。不把预装拷进用户装配槽。
  * 开发态 overlay：`EAP_LOCAL_SKILLS_DIR` / `EAP_LOCAL_TOOLS_DIR`（只读）。在 `createDevRuntime` /
  * `createToolExecutor` 时钉进执行器 extraRoots；SDK `createAgent` 构造完会恢复 process.env，
  * 请求时不再读这两项。相对 `read_file` 会把 overlay 根下直接子目录里带 SKILL.md 的包纳入唯一命中。
  */
 import { spawn } from 'node:child_process';
 import { constants as fsConstants, existsSync, readdirSync, realpathSync } from 'node:fs';
-import { mkdir, open, readFile } from 'node:fs/promises';
+import { chmod, mkdir, open, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { MISSING_USER_DIR, userRoot } from '../common/user-root.js';
+import { MAX_SNAPSHOT_ENUM, MAX_SNAPSHOT_URLS, PUBLIC_FILE_MODE, ensureUserSlots, maxWriteBytesFromEnv, publishFromFiles, resolveUserProductPath, snapshotCandidates, walkFilesTree, } from './static-artifact-url.js';
 import { BUILTIN_TOOL_SOURCE, DEFAULT_BUILTIN_TIMEOUT_MS, MAX_BUILTIN_TIMEOUT_MS, clampBuiltinTimeout, isBuiltinToolExecution, resolveBuiltinToolsConfig, } from '@gt-fe/eap-contracts';
 import { ensureInterpreterShims, formatSpawnError, killProcessTree, resolveShellSpawn, sandboxEnv, spawnOptionsFor, substituteSkillDir, } from './harness-command.js';
 import { expandSkillScriptRefs, isSkillEntryFile } from './skill-script-refs.js';
+/** 超时杀进程或 spawn 失败后等 `close`；未到则最多再等此时长再快照。 */
+const SPAWN_CLOSE_GRACE_MS = 1000;
 function builtinConfig() {
     return resolveBuiltinToolsConfig(process.env);
 }
@@ -66,7 +70,7 @@ function harnessDefinitions() {
             manifest: {
                 id: 'builtin:write_file',
                 name: 'write_file',
-                description: '把文本整份写入当前用户目录（含用户自己的 skills）。没有该文件则创建；已有文件会整份换成 content，不是改某一行。只要在末尾加内容请用 append_to_file。不能写预装 tools/skills，不能写 .assembly.json 等平台文件。成功时工具结果是 JSON：{"ok":true,"path":"相对用户目录的路径","bytesWritten":字节数}。路径越权或禁写文件名会失败。',
+                description: '把 UTF-8 文本整份写入当前用户的 files/（装配槽用 skills/ 前缀）。没有该文件则创建；已有文件会整份换成 content，不是改某一行。只要在末尾加内容请用 append_to_file。不能写 public/ 或 work/，不能写预装 tools/skills，不能写 .assembly.json 等平台文件。png/xlsx/docx/zip/pdf 等二进制请用 execute_command 写。成功时工具结果是 JSON：{"ok":true,"path":"工作稿原名","bytesWritten":字节数,"url":"公开副本链接，未配基址则无此字段"}。路径越权或禁写文件名会失败。',
                 ...common,
             },
             inputSchema: {
@@ -77,11 +81,11 @@ function harnessDefinitions() {
                     path: {
                         type: 'string',
                         minLength: 1,
-                        description: '相对当前用户目录的路径，例如 notes/todo.md。不能写预装 tools/skills。',
+                        description: '相对 files/ 的路径，例如 notes/todo.md 或 page/index.html。装配槽用 skills/ 前缀。不能写预装 tools/skills、public/、work/。',
                     },
                     content: {
                         type: 'string',
-                        description: '文件的完整新内容。会覆盖原文件全部内容。',
+                        description: '文件的完整新内容（UTF-8 文本）。会覆盖原文件全部内容。',
                     },
                 },
             },
@@ -92,7 +96,7 @@ function harnessDefinitions() {
             manifest: {
                 id: 'builtin:append_to_file',
                 name: 'append_to_file',
-                description: '在当前用户目录的文件末尾追加文本，不覆盖已有内容。没有该文件则创建。不要用它整份改写文件，那是 write_file。不能写预装 tools/skills，不能写 .assembly.json 等平台文件。成功时工具结果是 JSON：{"ok":true,"path":"相对用户目录的路径","bytesWritten":本次追加字节数}。路径越权或禁写文件名会失败。',
+                description: '在当前用户 files/ 的文件末尾追加 UTF-8 文本，不覆盖已有内容。没有该文件则创建。不要用它整份改写文件，那是 write_file。不能写 public/ 或 work/，不能写预装 tools/skills，不能写 .assembly.json 等平台文件。成功时工具结果是 JSON：{"ok":true,"path":"工作稿原名","bytesWritten":本次追加字节数,"url":"公开副本链接，未配基址则无此字段"}。路径越权或禁写文件名会失败。',
                 ...common,
             },
             inputSchema: {
@@ -103,11 +107,11 @@ function harnessDefinitions() {
                     path: {
                         type: 'string',
                         minLength: 1,
-                        description: '相对当前用户目录的路径，例如 notes/todo.md。不能写预装 tools/skills。',
+                        description: '相对 files/ 的路径，例如 notes/todo.md。装配槽用 skills/ 前缀。不能写预装 tools/skills、public/、work/。',
                     },
                     content: {
                         type: 'string',
-                        description: '接到文件末尾的文本。不会删除或替换原有内容。',
+                        description: '接到文件末尾的 UTF-8 文本。不会删除或替换原有内容。',
                     },
                 },
             },
@@ -118,7 +122,7 @@ function harnessDefinitions() {
             manifest: {
                 id: 'builtin:execute_command',
                 name: 'execute_command',
-                description: `用本机 shell 在用户目录执行命令（Windows cmd.exe，其它 /bin/sh）。技能包只读，用 EAP_SKILL_DIR 加包内相对路径跑文件（不限 scripts/）。python/python3、node/nodejs、sh/bash 经 shim。默认超时 ${DEFAULT_BUILTIN_TIMEOUT_MS}ms，可用 timeoutMs 延长，上限 ${MAX_BUILTIN_TIMEOUT_MS}ms。不继承密钥。`,
+                description: `用本机 shell 在用户 files/ 执行命令（Windows cmd.exe，其它 /bin/sh）。技能包只读，用 EAP_SKILL_DIR 加包内相对路径跑文件（不限 scripts/）。python/python3、node/nodejs、sh/bash 经 shim。默认超时 ${DEFAULT_BUILTIN_TIMEOUT_MS}ms，可用 timeoutMs 延长，上限 ${MAX_BUILTIN_TIMEOUT_MS}ms。不继承密钥。HOME/TMPDIR 在 work/。子进程 close 后（含超时杀进程）把 files/ 里新的或有改动的公开类型文件做成 public/ 时间戳副本。`,
                 ...common,
             },
             inputSchema: {
@@ -126,7 +130,7 @@ function harnessDefinitions() {
                 required: ['command'],
                 properties: {
                     command: { type: 'string' },
-                    cwd: { type: 'string', description: '用户目录内的子目录，可选；省略则用户目录。不能是预装技能/工具包' },
+                    cwd: { type: 'string', description: 'files/ 内的子目录，可选；省略则 files/。不能是 work/、public/ 或预装技能/工具包' },
                     timeoutMs: {
                         type: 'integer',
                         description: `超时毫秒。省略则 ${DEFAULT_BUILTIN_TIMEOUT_MS}。上限 ${MAX_BUILTIN_TIMEOUT_MS}。`,
@@ -151,19 +155,10 @@ export function mergeHarnessPrimitives(loadedTools) {
 export function assembleLoadedTools(loadedTools) {
     return mergeHarnessPrimitives(loadedTools);
 }
-const MISSING_USER_DIR = '缺少用户目录，拒绝该操作';
 const PROTECTED_WRITE_NAMES = new Set(['.assembly.json', 'assembly.json', '.ready']);
-/** `{agentDir}/users/<userId>`（写根；含用户 skills） */
+/** `dirname(agentDir)/users/<userId>`（写根；含用户 skills） */
 export function resolveUserDir(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(dir, 'users', uid);
+    return userRoot(agentDir, userId);
 }
 export function collectToolBundlePaths(loadedTools) {
     const roots = [];
@@ -270,6 +265,17 @@ async function writeFileNoFollow(target, content, append = false) {
         await handle.close();
     }
 }
+function maxWriteBytes(config) {
+    const n = config.maxWriteBytes;
+    if (typeof n === 'number' && Number.isFinite(n) && n > 0)
+        return Math.floor(n);
+    return maxWriteBytesFromEnv();
+}
+function toolFileFromPublished(p) {
+    if (!p.url)
+        return undefined;
+    return { fileName: p.fileName, fileType: p.fileType, size: p.size, url: p.url };
+}
 function isInsideRoot(candidate, root) {
     const rel = path.relative(root, candidate);
     return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
@@ -473,10 +479,27 @@ export class HarnessPrimitiveExecutor {
         const filePath = String(request.arguments.path ?? '');
         const workdir = this.workdirFor(request);
         const located = locateSkillRelativeRead(filePath, workdir, request.skillDir, this.extraRootsFor(request));
-        const target = resolveJailedPath(located.path, this.rootsFor(request), {
-            mustExist: true,
-            relativeBase: located.relativeBase,
-        });
+        const userBase = userReadBase(workdir);
+        let target;
+        if (path.isAbsolute(filePath.trim())) {
+            target = resolveJailedPath(filePath, this.rootsFor(request), { mustExist: true });
+        }
+        else if (located.relativeBase && located.relativeBase !== userBase) {
+            target = resolveJailedPath(located.path, this.rootsFor(request), {
+                mustExist: true,
+                relativeBase: located.relativeBase,
+            });
+        }
+        else if (workdir) {
+            const product = resolveUserProductPath(filePath, workdir, 'read');
+            target = resolveJailedPath(product.abs, this.rootsFor(request), { mustExist: true });
+        }
+        else {
+            target = resolveJailedPath(located.path, this.rootsFor(request), {
+                mustExist: true,
+                relativeBase: located.relativeBase,
+            });
+        }
         const buf = await readFile(target);
         const config = builtinConfig();
         const lines = buf.toString('utf8').split('\n');
@@ -513,38 +536,75 @@ export class HarnessPrimitiveExecutor {
         const filePath = String(request.arguments.path ?? '');
         const content = String(request.arguments.content ?? '');
         const workdir = this.requireWorkdir(request);
-        const writeRoots = [workdir];
-        const jailed = { relativeBase: workdir };
-        const target = resolveJailedPath(filePath, writeRoots, jailed);
-        if (PROTECTED_WRITE_NAMES.has(path.basename(target))) {
-            throw new Error(`禁止写入平台文件：${path.basename(target)}`);
+        await ensureUserSlots(workdir);
+        const resolved = resolveUserProductPath(filePath, workdir, 'write');
+        if (PROTECTED_WRITE_NAMES.has(path.basename(resolved.abs))) {
+            throw new Error(`禁止写入平台文件：${path.basename(resolved.abs)}`);
+        }
+        const incomingBytes = Buffer.byteLength(content, 'utf8');
+        const limit = maxWriteBytes(builtinConfig());
+        if (append) {
+            const existing = await stat(resolved.abs)
+                .then((s) => s.size)
+                .catch(() => 0);
+            if (existing + incomingBytes > limit) {
+                throw new Error(`文件超过 ${limit} 字节上限`);
+            }
+        }
+        else if (incomingBytes > limit) {
+            throw new Error(`文件超过 ${limit} 字节上限`);
         }
-        await mkdir(path.dirname(target), { recursive: true });
-        const recast = resolveJailedPath(filePath, writeRoots, jailed);
-        if (PROTECTED_WRITE_NAMES.has(path.basename(recast))) {
-            throw new Error(`禁止写入平台文件：${path.basename(recast)}`);
+        await mkdir(path.dirname(resolved.abs), { recursive: true });
+        const recast = resolveUserProductPath(filePath, workdir, 'write');
+        if (PROTECTED_WRITE_NAMES.has(path.basename(recast.abs))) {
+            throw new Error(`禁止写入平台文件：${path.basename(recast.abs)}`);
         }
-        const bytesWritten = await writeFileNoFollow(recast, content, append);
-        return ok(request, JSON.stringify({ ok: true, path: path.relative(workdir, recast), bytesWritten }));
+        const bytesWritten = await writeFileNoFollow(recast.abs, content, append);
+        await chmod(recast.abs, PUBLIC_FILE_MODE).catch(() => undefined);
+        const payload = {
+            ok: true,
+            path: recast.jsonPath,
+            bytesWritten,
+        };
+        let file;
+        if (recast.slot === 'files' && recast.relFromFiles) {
+            const published = await publishFromFiles(workdir, [recast.relFromFiles]);
+            const first = published[0];
+            if (first?.url) {
+                payload.url = first.url;
+                file = toolFileFromPublished(first);
+            }
+        }
+        return { ...ok(request, JSON.stringify(payload)), ...(file ? { file } : {}) };
     }
     async executeCommand(request) {
         const command = substituteSkillDir(String(request.arguments.command ?? '').trim(), request.skillDir);
         if (!command)
             return fail(request, 'command 不能为空');
         const workdir = this.requireWorkdir(request);
-        await mkdir(workdir, { recursive: true });
-        const cwdArg = request.arguments.cwd != null ? String(request.arguments.cwd) : workdir;
-        const cwd = resolveJailedPath(cwdArg, [workdir], {
-            mustExist: true,
-            relativeBase: workdir,
-        });
+        const slots = await ensureUserSlots(workdir);
+        let cwd;
+        if (request.arguments.cwd != null && String(request.arguments.cwd).trim() !== '') {
+            const resolvedCwd = resolveUserProductPath(String(request.arguments.cwd), workdir, 'cwd');
+            if (resolvedCwd.slot !== 'files') {
+                throw new Error(`路径超出允许目录：${String(request.arguments.cwd)}`);
+            }
+            cwd = resolvedCwd.abs;
+        }
+        else {
+            cwd = slots.filesDir;
+        }
+        await mkdir(cwd, { recursive: true });
         const config = builtinConfig();
         const timeoutMs = clampBuiltinTimeout(request.arguments.timeoutMs, config);
         const maxOutput = config.maxOutputBytes;
+        const writeLimit = maxWriteBytes(config);
+        const before = await walkFilesTree(slots.filesDir);
         const shell = resolveShellSpawn(command);
-        const shimDir = ensureInterpreterShims(workdir);
-        const env = sandboxEnv(workdir, cwd, config.envAllowlist, shimDir, request.skillDir);
-        const output = await new Promise((resolve, reject) => {
+        const shimDir = ensureInterpreterShims(slots.workDir);
+        const env = sandboxEnv(workdir, cwd, config.envAllowlist, shimDir, request.skillDir, slots.workDir);
+        // 子进程 close 后再快照 files/（超时先杀进程再等 close；close 未到则最多再等 SPAWN_CLOSE_GRACE_MS）。
+        const output = await new Promise((resolve) => {
             const child = spawn(shell.file, shell.args, {
                 cwd,
                 env,
@@ -555,9 +615,36 @@ export class HarnessPrimitiveExecutor {
             let stderr = Buffer.alloc(0);
             let stdoutTruncated = false;
             let stderrTruncated = false;
+            let settled = false;
+            let timedOut = false;
+            let spawnError;
+            let closeFallback;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (closeFallback !== undefined)
+                    clearTimeout(closeFallback);
+                resolve(value);
+            };
+            const snapshotStdio = () => ({
+                stdout: stdout.toString('utf8'),
+                stderr: stderr.toString('utf8'),
+                stdoutTruncated,
+                stderrTruncated,
+            });
+            const waitForCloseThenFinish = () => {
+                if (closeFallback !== undefined)
+                    clearTimeout(closeFallback);
+                closeFallback = setTimeout(() => {
+                    finish({ ...snapshotStdio(), code: null, timedOut, spawnError });
+                }, SPAWN_CLOSE_GRACE_MS);
+            };
             const timer = setTimeout(() => {
+                timedOut = true;
                 killProcessTree(child);
-                reject(new Error(`命令超时（${timeoutMs}ms）`));
+                waitForCloseThenFinish();
             }, timeoutMs);
             child.stdout?.on('data', (chunk) => {
                 if (stdout.length >= maxOutput) {
@@ -578,33 +665,71 @@ export class HarnessPrimitiveExecutor {
                     stderrTruncated = true;
             });
             child.on('error', (err) => {
+                spawnError = formatSpawnError(err, shell.file);
                 clearTimeout(timer);
-                reject(formatSpawnError(err, shell.file));
+                waitForCloseThenFinish();
             });
             child.on('close', (code) => {
-                clearTimeout(timer);
-                resolve({
-                    stdout: stdout.toString('utf8'),
-                    stderr: stderr.toString('utf8'),
-                    code,
-                    stdoutTruncated,
-                    stderrTruncated,
-                });
+                finish({ ...snapshotStdio(), code, timedOut, spawnError });
             });
         });
-        const body = [
+        const after = await walkFilesTree(slots.filesDir);
+        const { rels, skippedOversize } = snapshotCandidates(before.entries, after.entries, writeLimit);
+        const limited = rels.slice(0, MAX_SNAPSHOT_URLS);
+        const published = limited.length > 0 ? await publishFromFiles(workdir, limited) : [];
+        const publicFiles = published.map((p) => ({
+            path: p.sourceRel ?? p.fileName,
+            fileName: p.fileName,
+            size: p.size,
+            ...(p.url ? { url: p.url } : {}),
+        }));
+        const notes = [];
+        if (before.truncated || after.truncated) {
+            notes.push(`快照枚举达到 ${MAX_SNAPSHOT_ENUM} 上限`);
+        }
+        if (skippedOversize > 0) {
+            notes.push(`跳过 ${skippedOversize} 个超过大小上限的文件`);
+        }
+        if (rels.length > MAX_SNAPSHOT_URLS) {
+            notes.push(`快照 url 最多 ${MAX_SNAPSHOT_URLS} 个`);
+        }
+        const withUrl = published
+            .map(toolFileFromPublished)
+            .filter((f) => Boolean(f));
+        const file = withUrl[0];
+        const files = withUrl.slice(1);
+        const ended = output.timedOut
+            ? `命令超时（${timeoutMs}ms）`
+            : output.spawnError
+                ? output.spawnError.message
+                : `exit ${output.code ?? -1}`;
+        const commandBody = [
             output.stdout.trimEnd(),
             output.stdoutTruncated ? `[stdout truncated at ${maxOutput} bytes]` : '',
             output.stderr.trim() ? `stderr:\n${output.stderr.trimEnd()}` : '',
             output.stderrTruncated ? `[stderr truncated at ${maxOutput} bytes]` : '',
-            `exit ${output.code ?? -1}`,
+            ended,
+            ...notes,
         ]
             .filter(Boolean)
             .join('\n');
+        const body = publicFiles.length > 0
+            ? `${JSON.stringify({ publicFiles })}\n${commandBody}`
+            : commandBody;
+        const extra = {
+            ...(file ? { file } : {}),
+            ...(files.length > 0 ? { files } : {}),
+        };
+        if (output.spawnError) {
+            return { ...fail(request, output.spawnError.message), content: body, ...extra };
+        }
+        if (output.timedOut) {
+            return { ...fail(request, `命令超时（${timeoutMs}ms）`), content: body, ...extra };
+        }
         if (output.code !== 0) {
-            return { ...fail(request, `命令退出码 ${output.code}`), content: body };
+            return { ...fail(request, `命令退出码 ${output.code}`), content: body, ...extra };
         }
-        return ok(request, body);
+        return { ...ok(request, body), ...extra };
     }
 }
 export function withHarnessPrimitives(inner, options) {

package/dist/tool/index.d.ts

@@ -15,6 +15,8 @@ export { formatMcpOutput, toModelVisibleToolContent, MAX_MODEL_RESULT_ROWS, MAX_
 export { ToolExecutionRouter, type DeploymentContext, type ToolExecutionRouterOptions, } from './tool-execution-router.js';
 export { createToolExecutor, EmptyInstallStore, type CreateToolExecutorOptions, } from './create-tool-executor.js';
 export { assembleLoadedTools, mergeHarnessPrimitives as mergeBuiltinTools, withHarnessPrimitives as withBuiltinTools, HarnessPrimitiveExecutor as BuiltinToolExecutor, resolveUserDir, resolveJailFromState, captureOverlayJailOptions, collectToolBundlePaths, type HarnessJailOptions as BuiltinJailOptions, } from './harness-primitives.js';
+export { injectPublicArtifactLinks, collectPublicArtifactLinks, applyInjectedAssistant, } from './inject-public-artifact-links.js';
+export { publishFromFiles, ensureUserSlots, publicArtifactUrl, PUBLIC_EXTENSIONS, } from './static-artifact-url.js';
 export { resolveShellSpawn, shellNameFor, commandDialectLines, findPythonInterpreter, findNodeInterpreter, ensureInterpreterShims, substituteSkillDir, } from './harness-command.js';
 export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './skill-script-refs.js';
 export { ToolResultInjector, type ToolMessage, } from './tool-result-injector.js';

package/dist/tool/index.js

@@ -14,6 +14,8 @@ export { formatMcpOutput, toModelVisibleToolContent, MAX_MODEL_RESULT_ROWS, MAX_
 export { ToolExecutionRouter, } from './tool-execution-router.js';
 export { createToolExecutor, EmptyInstallStore, } from './create-tool-executor.js';
 export { assembleLoadedTools, mergeHarnessPrimitives as mergeBuiltinTools, withHarnessPrimitives as withBuiltinTools, HarnessPrimitiveExecutor as BuiltinToolExecutor, resolveUserDir, resolveJailFromState, captureOverlayJailOptions, collectToolBundlePaths, } from './harness-primitives.js';
+export { injectPublicArtifactLinks, collectPublicArtifactLinks, applyInjectedAssistant, } from './inject-public-artifact-links.js';
+export { publishFromFiles, ensureUserSlots, publicArtifactUrl, PUBLIC_EXTENSIONS, } from './static-artifact-url.js';
 export { resolveShellSpawn, shellNameFor, commandDialectLines, findPythonInterpreter, findNodeInterpreter, ensureInterpreterShims, substituteSkillDir, } from './harness-command.js';
 export { expandSkillScriptRefs, isSkillEntryFile, EAP_SKILL_DIR_ENV, } from './skill-script-refs.js';
 export { ToolResultInjector, } from './tool-result-injector.js';

package/dist/tool/inject-public-artifact-links.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 本轮带 url 的公开副本 → 助手正文末尾 GFM 链接。
+ * stream / streamResumeHitl / stream.handler / invoke.handler 共用。
+ */
+export type ArtifactLink = {
+    fileName: string;
+    url: string;
+};
+export type ToolResultLike = {
+    content?: unknown;
+    file?: {
+        fileName?: string;
+        url?: string;
+    };
+    files?: Array<{
+        fileName?: string;
+        url?: string;
+    }>;
+};
+export declare function mergeArtifactLinks(...groups: ArtifactLink[][]): ArtifactLink[];
+export declare function collectPublicArtifactLinks(results: ToolResultLike[]): ArtifactLink[];
+export declare function collectPublicArtifactLinksFromEvent(eventType: string, payload: unknown, bucket: ArtifactLink[]): void;
+export declare function toolResultHasArtifacts(result: ToolResultLike): boolean;
+export declare function applyInjectedAssistant<T extends {
+    role?: string;
+    content: string;
+    toolCalls?: unknown[];
+}>(messages: T[], injected: string, links: ArtifactLink[]): T[];
+export declare function injectPublicArtifactLinks(visibleText: string, artifacts: ArtifactLink[]): {
+    injected: string;
+    suffix: string;
+};