@gt-fe/eap-runtime 0.0.29 → 0.0.31

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;
+};

package/dist/tool/inject-public-artifact-links.js

@@ -0,0 +1,142 @@
+/**
+ * 本轮带 url 的公开副本 → 助手正文末尾 GFM 链接。
+ * stream / streamResumeHitl / stream.handler / invoke.handler 共用。
+ */
+function escapeMdLinkText(text) {
+    return text.replace(/\\/g, '\\\\').replace(/([\[\]()])/g, '\\$1');
+}
+function addLink(out, seen, fileName, url) {
+    const href = url.trim();
+    if (!href || seen.has(href))
+        return;
+    seen.add(href);
+    out.push({ fileName: fileName.trim() || href, url: href });
+}
+function parseContentLinks(content, out, seen) {
+    if (typeof content !== 'string' || !content.trim())
+        return;
+    const first = content.split('\n', 1)[0] ?? '';
+    try {
+        const parsed = JSON.parse(first);
+        if (Array.isArray(parsed.publicFiles)) {
+            for (const item of parsed.publicFiles) {
+                if (!item || typeof item !== 'object')
+                    continue;
+                const row = item;
+                if (typeof row.url === 'string') {
+                    const name = (typeof row.fileName === 'string' && row.fileName) ||
+                        (typeof row.path === 'string' && row.path) ||
+                        'file';
+                    addLink(out, seen, name, row.url);
+                }
+            }
+            return;
+        }
+        if (parsed.ok === true && typeof parsed.url === 'string') {
+            const name = typeof parsed.path === 'string' ? parsed.path : 'file';
+            addLink(out, seen, name, parsed.url);
+        }
+    }
+    catch {
+        // 非 JSON 行忽略
+    }
+}
+export function mergeArtifactLinks(...groups) {
+    const out = [];
+    const seen = new Set();
+    for (const group of groups) {
+        for (const item of group)
+            addLink(out, seen, item.fileName, item.url);
+    }
+    return out;
+}
+export function collectPublicArtifactLinks(results) {
+    const out = [];
+    const seen = new Set();
+    for (const result of results) {
+        if (result.file?.url) {
+            addLink(out, seen, result.file.fileName ?? result.file.url, result.file.url);
+        }
+        for (const f of result.files ?? []) {
+            if (f?.url)
+                addLink(out, seen, f.fileName ?? f.url, f.url);
+        }
+        parseContentLinks(result.content, out, seen);
+    }
+    return out;
+}
+export function collectPublicArtifactLinksFromEvent(eventType, payload, bucket) {
+    if (!payload || typeof payload !== 'object')
+        return;
+    const p = payload;
+    const seen = new Set(bucket.map((l) => l.url));
+    if (eventType === 'file.created' && typeof p.url === 'string') {
+        addLink(bucket, seen, typeof p.fileName === 'string' ? p.fileName : p.url, p.url);
+        return;
+    }
+    if (eventType === 'tool.result' || eventType === 'tool.error') {
+        const extra = collectPublicArtifactLinks([
+            { content: p.content, file: p.file, files: p.files },
+        ]);
+        for (const link of extra)
+            addLink(bucket, seen, link.fileName, link.url);
+    }
+}
+export function toolResultHasArtifacts(result) {
+    if (result.file?.url)
+        return true;
+    if ((result.files ?? []).some((f) => Boolean(f?.url)))
+        return true;
+    if (typeof result.content !== 'string' || !result.content.trim())
+        return false;
+    const first = result.content.split('\n', 1)[0] ?? '';
+    try {
+        const parsed = JSON.parse(first);
+        if (Array.isArray(parsed.publicFiles) && parsed.publicFiles.length > 0)
+            return true;
+        if (parsed.ok === true && typeof parsed.url === 'string' && parsed.url)
+            return true;
+    }
+    catch {
+        return false;
+    }
+    return false;
+}
+export function applyInjectedAssistant(messages, injected, links) {
+    if (!injected || links.length === 0)
+        return messages;
+    let idx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role !== 'assistant')
+            continue;
+        if (!m.content.trim())
+            continue;
+        idx = i;
+        break;
+    }
+    if (idx >= 0) {
+        const copy = messages.slice();
+        copy[idx] = { ...copy[idx], content: injected };
+        return copy;
+    }
+    return [...messages, { role: 'assistant', content: injected }];
+}
+export function injectPublicArtifactLinks(visibleText, artifacts) {
+    const seen = new Set();
+    const lines = [];
+    for (const item of artifacts) {
+        const url = item.url.trim();
+        if (!url || seen.has(url))
+            continue;
+        seen.add(url);
+        if (visibleText.includes(url))
+            continue;
+        lines.push(`[${escapeMdLinkText(item.fileName)}](${url})`);
+    }
+    if (lines.length === 0)
+        return { injected: visibleText, suffix: '' };
+    const block = lines.join('\n');
+    const suffix = visibleText ? `\n\n${block}` : block;
+    return { injected: `${visibleText}${suffix}`, suffix };
+}

package/dist/tool/static-artifact-url.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 用户产物公开副本：files/ 工作稿 → public/ 时间戳 copy；拼 Hosting /static url。
+ * @see docs/design/user-artifact-delivery.md
+ */
+/** 与 contracts `DEFAULT_BUILTIN_MAX_WRITE_BYTES` 同值；本地编译不依赖未发版 contracts */
+export declare const DEFAULT_MAX_WRITE_BYTES: number;
+export declare const PUBLIC_DIR_MODE = 493;
+export declare const PUBLIC_FILE_MODE = 420;
+export declare const MAX_SNAPSHOT_ENUM = 5000;
+export declare const MAX_SNAPSHOT_URLS = 20;
+export declare const MAX_PUBLIC_NAME_ATTEMPTS = 8;
+export declare const PUBLIC_EXTENSIONS: Set<string>;
+export type ArtifactEnv = NodeJS.ProcessEnv | Record<string, string | undefined>;
+export type PublishedArtifact = {
+    fileName: string;
+    fileType: string;
+    size: number;
+    url?: string;
+    absPath: string;
+    /** 工作稿相对 `files/` 的路径 */
+    sourceRel?: string;
+};
+export declare function staticBaseUrlFromEnv(env?: ArtifactEnv): string | undefined;
+export declare function preinstallRootFromEnv(env?: ArtifactEnv): string | undefined;
+export declare function encodePublicRel(rel: string): string;
+export declare function isPublicUserArtifactRel(rel: string): boolean;
+export declare function publicArtifactUrl(absPath: string, env?: ArtifactEnv): string | undefined;
+export declare function publicTimeSuffix(now?: Date, withMs?: boolean): string;
+export declare function stripPublicSuffix(name: string): string;
+export declare function extensionOf(name: string): string;
+export declare function isPublicExtension(name: string): boolean;
+export declare function isSnapshotJunkName(name: string): boolean;
+export declare function mkdirChmod(dir: string, mode?: number): Promise<void>;
+/** 四槽 `skills/` `work/` `files/` `public/`，目录 0755（与 Hosting `ensureUserWorkspace` 对齐）。 */
+export declare function ensureUserSlots(userDir: string): Promise<{
+    filesDir: string;
+    workDir: string;
+    publicDir: string;
+    skillsDir: string;
+}>;
+export declare function allocPublicBasename(publicDir: string, srcFile: string, originalBasename: string): Promise<string | undefined>;
+export declare function allocPublicDir(publicDir: string, srcDir: string, originalDirName: string): Promise<string | undefined>;
+export declare function publishFromFiles(userDir: string, relFromFiles: string[], env?: ArtifactEnv): Promise<PublishedArtifact[]>;
+export type FilesWalkEntry = {
+    rel: string;
+    size: number;
+    mtimeMs: number;
+    ctimeMs: number;
+};
+export declare function walkFilesTree(filesDir: string): Promise<{
+    entries: Map<string, FilesWalkEntry>;
+    truncated: boolean;
+}>;
+export declare function snapshotCandidates(before: Map<string, FilesWalkEntry>, after: Map<string, FilesWalkEntry>, maxWriteBytes?: number): {
+    rels: string[];
+    skippedOversize: number;
+};
+export type UserProductSlot = 'files' | 'skills';
+export type ResolvedUserProductPath = {
+    abs: string;
+    jsonPath: string;
+    slot: UserProductSlot;
+    relFromFiles?: string;
+};
+export declare function resolveUserProductPath(requested: string, userDir: string, kind: 'write' | 'cwd' | 'read'): ResolvedUserProductPath;
+export declare function maxWriteBytesFromEnv(env?: ArtifactEnv): number;