@turingflow/agent-kit 0.0.0-stage → 0.1.0

package/dist/server/artifact-tool-tracker.js

@@ -0,0 +1,347 @@
+/**
+ * Attribute file changes to actual tool executions. Explicit file tools retain a
+ * before image; shell tools compare bounded filesystem snapshots around the call.
+ * This is deliberately independent of command syntax (Python, redirects, scripts,
+ * and PowerShell all work), and never sweeps the server's implicit process.cwd().
+ *
+ * Shell attribution covers the supplied workspace/cwd and this session's output
+ * directories only. Dependencies, builds, caches, logs, staging and symlinks are
+ * excluded. Concurrent external writes inside those roots cannot be distinguished
+ * from a shell's writes; background commands that finish after flush are likewise
+ * outside the observation window. Explicit file tools do not have these scan limits.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { capturePreWriteSnapshot, isIntermediateRel, isTextDiffable, normalizeArtifactAbsPath, registerArtifactPath, sessionDirCandidates, } from "./artifacts.js";
+const FILE_TOOLS = new Set(["write", "edit", "multiedit", "notebookedit"]);
+const SHELL_TOOLS = new Set(["bash", "powershell"]);
+const SKIP_DIRECTORIES = new Set([
+    ".agent", ".git", ".hg", ".svn", ".codebuddy", ".workbuddy", ".browser-agent-profile",
+    ".web-fetch-profile", ".shots", "node_modules", "vendor", ".venv", "venv", "__pycache__",
+    ".cache", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".next", ".nuxt", ".turbo",
+    ".vite", "coverage", "dist", "build", "out", "target", "bin", "obj", "logs", "log",
+    "tmp", "temp", "_tmp", "_drafts", "_intermediate", "attachments", "tool-results", "subagents",
+]);
+const SKIP_FILES = /(?:\.(?:log|tmp|temp|swp|swo|pid|tsbuildinfo)|(?:^|[.])DS_Store|^Thumbs\.db)$/i;
+const CONTENT_LIMIT = 512 * 1024;
+const ABSENT = { exists: false, mtimeNs: 0n, size: 0, content: null };
+const DEFAULT_LIMITS = {
+    maxEntries: 20_000,
+    maxFiles: 8_000,
+    maxDirectories: 1_500,
+    maxDepth: 24,
+    maxTotalContentBytes: 32 * 1024 * 1024,
+    maxDurationMs: 5_000,
+};
+function isWithin(abs, root) {
+    const rel = path.relative(root, abs);
+    return rel === "" || (!path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(".." + path.sep));
+}
+/** Unknown (unreadable/truncated/excluded) is not the same as absent. */
+function snapshotStamp(snapshot, abs) {
+    const known = snapshot.files.get(abs);
+    if (known)
+        return known;
+    for (const root of snapshot.missingRoots)
+        if (isWithin(abs, root))
+            return ABSENT;
+    let child = abs;
+    for (;;) {
+        const parent = path.dirname(child);
+        if (child === parent)
+            return undefined;
+        const names = snapshot.directories.get(parent);
+        if (names && !names.has(path.basename(child)))
+            return ABSENT;
+        child = parent;
+    }
+}
+function sameStamp(before, after) {
+    if (before.exists === false || after.exists === false)
+        return before.exists === after.exists;
+    if (before.digest && after.digest)
+        return before.digest === after.digest;
+    if (before.content != null && after.content != null)
+        return before.content === after.content;
+    return before.mtimeNs === after.mtimeNs && before.size === after.size;
+}
+function fingerprint(input) {
+    try {
+        return JSON.stringify(input);
+    }
+    catch {
+        return "";
+    }
+}
+function extractPaths(input) {
+    const paths = new Set();
+    const add = (record) => {
+        for (const key of ["file_path", "path", "notebook_path"]) {
+            if (typeof record[key] === "string" && record[key].trim())
+                paths.add(record[key]);
+        }
+    };
+    // MultiEdit normally has ONE top-level file_path, with only replacement pairs
+    // inside edits; some providers instead supply a path on every edit.
+    add(input);
+    if (Array.isArray(input.edits)) {
+        for (const edit of input.edits)
+            if (edit && typeof edit === "object")
+                add(edit);
+    }
+    return [...paths];
+}
+export function createArtifactToolTracker(options) {
+    const { sessionId, workspaceDir, cwd, preWrite } = options;
+    const limits = { ...DEFAULT_LIMITS, ...options.scanLimits };
+    const warnings = new Set();
+    const warn = (reason) => {
+        if (warnings.has(reason))
+            return;
+        warnings.add(reason);
+        const message = `[artifacts] ${reason}`;
+        try {
+            (options.onWarning ?? console.warn)(message);
+        }
+        catch { /* Observability must not stop a tool. */ }
+    };
+    const roots = [];
+    for (const supplied of [workspaceDir, cwd]) {
+        if (!supplied?.trim())
+            continue;
+        const abs = path.resolve(supplied.trim());
+        // Even an explicitly configured drive root is not a useful scan boundary.
+        if (abs === path.parse(abs).root) {
+            warn("Shell artifact scanning skipped a filesystem root; use a specific workspace directory.");
+            continue;
+        }
+        if (!roots.some((root) => root.abs === abs))
+            roots.push({ abs, session: false });
+    }
+    // The normal workspace walk skips all .agent directories. Add only this
+    // session's roots explicitly, including nested documents and sandbox outputs.
+    for (const candidate of sessionDirCandidates(sessionId, workspaceDir)) {
+        const abs = path.resolve(candidate);
+        const existing = roots.find((root) => root.abs === abs);
+        if (existing)
+            existing.session = true;
+        else
+            roots.push({ abs, session: true });
+    }
+    const scan = async () => {
+        const result = { files: new Map(), directories: new Map(), missingRoots: new Set() };
+        const started = Date.now();
+        let entries = 0;
+        let directories = 0;
+        let contentBytes = 0;
+        let exhausted = false;
+        const atLimit = () => {
+            if (exhausted)
+                return true;
+            if (entries >= limits.maxEntries || result.files.size >= limits.maxFiles ||
+                directories >= limits.maxDirectories || Date.now() - started >= limits.maxDurationMs) {
+                exhausted = true;
+                warn("Shell artifact scan reached its entry/file/directory/time limit; some changes may be untracked. Narrow the workspace or use explicit file tools.");
+            }
+            return exhausted;
+        };
+        const visit = async (abs, root, depth) => {
+            if (result.directories.has(abs) || atLimit())
+                return;
+            if (depth > limits.maxDepth) {
+                warn("Shell artifact scan reached its directory depth limit; deeper files may be untracked.");
+                return;
+            }
+            const names = new Set();
+            const children = [];
+            try {
+                // opendir bounds memory even when a directory contains many entries.
+                const dir = await fs.opendir(abs);
+                directories++;
+                let complete = true;
+                for await (const entry of dir) {
+                    if (atLimit()) {
+                        complete = false;
+                        break;
+                    }
+                    entries++;
+                    names.add(entry.name);
+                    const child = path.join(abs, entry.name);
+                    if (entry.isSymbolicLink())
+                        continue;
+                    const rel = path.relative(root.abs, child);
+                    if (root.session && isIntermediateRel(rel))
+                        continue;
+                    if (entry.isDirectory()) {
+                        if (!SKIP_DIRECTORIES.has(entry.name.toLowerCase()))
+                            children.push(child);
+                        continue;
+                    }
+                    if (!entry.isFile() || SKIP_FILES.test(entry.name))
+                        continue;
+                    try {
+                        const stat = await fs.lstat(child, { bigint: true });
+                        if (!stat.isFile())
+                            continue;
+                        const size = Number(stat.size);
+                        let data;
+                        if (size <= CONTENT_LIMIT) {
+                            if (contentBytes + size <= limits.maxTotalContentBytes) {
+                                contentBytes += size;
+                                data = await fs.readFile(child).catch(() => undefined);
+                            }
+                            else {
+                                warn("Shell artifact snapshots reached their content budget; additional files retain metadata but may have no text diff.");
+                            }
+                        }
+                        result.files.set(child, {
+                            exists: true,
+                            mtimeNs: stat.mtimeNs,
+                            size,
+                            content: data && isTextDiffable(child) && !data.includes(0) ? data.toString("utf8") : null,
+                            digest: data ? createHash("sha256").update(data).digest("hex") : undefined,
+                        });
+                    }
+                    catch (error) {
+                        if (!["ENOENT", "ENOTDIR"].includes(error.code ?? "")) {
+                            warn("Shell artifact scan could not read some files; their changes may be untracked.");
+                        }
+                    }
+                }
+                if (complete)
+                    result.directories.set(abs, names);
+            }
+            catch (error) {
+                const code = error.code;
+                if (depth === 0 && (code === "ENOENT" || code === "ENOTDIR"))
+                    result.missingRoots.add(abs);
+                else if (code !== "ENOENT" && code !== "ENOTDIR")
+                    warn("Shell artifact scan could not read some directories; their changes may be untracked.");
+                return;
+            }
+            for (const child of children) {
+                if (atLimit())
+                    break;
+                await visit(child, root, depth + 1);
+            }
+        };
+        // User-facing session documents get priority over a potentially large repo.
+        for (const root of [...roots].sort((a, b) => Number(b.session) - Number(a.session))) {
+            if (atLimit())
+                break;
+            try {
+                const stat = await fs.lstat(root.abs);
+                if (stat.isSymbolicLink() || !stat.isDirectory())
+                    continue;
+            }
+            catch (error) {
+                if (["ENOENT", "ENOTDIR"].includes(error.code ?? ""))
+                    result.missingRoots.add(root.abs);
+                else
+                    warn("Shell artifact scan could not inspect one of its roots; some changes may be untracked.");
+                continue;
+            }
+            await visit(root.abs, root, 0);
+        }
+        return result;
+    };
+    const pending = [];
+    let queue = Promise.resolve();
+    const serialized = (work) => {
+        const next = queue.then(work);
+        queue = next.catch((error) => { warn(`Artifact tool tracking failed: ${error instanceof Error ? error.message : String(error)}`); });
+        return queue;
+    };
+    const remember = (abs, stamp) => {
+        if (preWrite.has(abs))
+            return;
+        // When tools overlap, an earlier shell may already have written this path
+        // before a later explicit tool captures it. Preserve the earliest observation.
+        for (const tool of pending) {
+            const earlier = tool.before && snapshotStamp(tool.before, abs);
+            if (earlier) {
+                preWrite.set(abs, earlier);
+                return;
+            }
+        }
+        preWrite.set(abs, stamp);
+    };
+    const register = async (abs, before) => {
+        remember(abs, before);
+        await registerArtifactPath(sessionId, abs, workspaceDir, cwd, "model", preWrite.get(abs));
+    };
+    const complete = async (tool, shellAfter) => {
+        if (tool.before) {
+            const after = shellAfter ?? await scan();
+            const paths = new Set([...tool.before.files.keys(), ...after.files.keys()]);
+            for (const abs of paths) {
+                const beforeStamp = snapshotStamp(tool.before, abs);
+                const afterStamp = snapshotStamp(after, abs);
+                // A partial scan cannot establish absence. Never turn its omissions into
+                // fabricated additions or deletions.
+                if (beforeStamp && afterStamp && !sameStamp(beforeStamp, afterStamp))
+                    await register(abs, beforeStamp);
+            }
+        }
+        else {
+            const current = new Map();
+            for (const abs of tool.paths) {
+                await capturePreWriteSnapshot(abs, current);
+                const before = tool.explicitBefore?.get(abs);
+                const after = current.get(abs);
+                if (before && after && !sameStamp(before, after))
+                    await register(abs, before);
+            }
+        }
+    };
+    return {
+        before(toolName, input, toolUseId) {
+            return serialized(async () => {
+                const name = toolName.toLowerCase();
+                if (!FILE_TOOLS.has(name) && !SHELL_TOOLS.has(name))
+                    return;
+                if (toolUseId && pending.some((tool) => tool.id === toolUseId))
+                    return;
+                const tool = { id: toolUseId, name, fingerprint: fingerprint(input), paths: [] };
+                if (SHELL_TOOLS.has(name)) {
+                    tool.before = await scan();
+                }
+                else {
+                    tool.paths = [...new Set(extractPaths(input).map((raw) => normalizeArtifactAbsPath(raw, workspaceDir, cwd)).filter((abs) => !!abs))];
+                    tool.explicitBefore = new Map();
+                    for (const abs of tool.paths) {
+                        await capturePreWriteSnapshot(abs, tool.explicitBefore);
+                        const stamp = tool.explicitBefore.get(abs);
+                        if (stamp)
+                            remember(abs, stamp);
+                    }
+                }
+                pending.push(tool);
+            });
+        },
+        after(toolName, input, toolUseId) {
+            return serialized(async () => {
+                const name = toolName.toLowerCase();
+                const index = pending.findIndex((tool) => toolUseId ? tool.id === toolUseId : tool.name === name && tool.fingerprint === fingerprint(input));
+                if (index === -1)
+                    return;
+                const tool = pending[index];
+                // Keep this snapshot available to remember() until its changed paths have
+                // been registered. This also handles missing-file stamps for new outputs.
+                await complete(tool);
+                pending.splice(index, 1);
+            });
+        },
+        /** Called at turn end/abort, including partial writes from failed tools. */
+        flush() {
+            return serialized(async () => {
+                const after = pending.some((tool) => tool.before) ? await scan() : undefined;
+                while (pending.length) {
+                    await complete(pending[0], after);
+                    pending.shift();
+                }
+            });
+        },
+    };
+}

package/dist/server/artifacts.d.ts

@@ -0,0 +1,227 @@
+/**
+ * agent-kit · 产物（Artifact）管理
+ *
+ * 问题背景：模型用 Write 工具生成的 HTML / Markdown / 图片等「供用户查看的文件」，
+ * 原来会落到任意磁盘位置（如 apps/web/），且模型常在回复里复述真实路径，
+ * 既泄露服务器目录结构，前端也无法直接渲染。
+ *
+ * 本模块提供：
+ *   - 会话隔离目录：<产物根>/.agent/<sessionId>/（选了项目 → 项目根/.agent/；无项目 → ~/.agent/），
+ *     每个会话只能看到自己的产出；
+ *   - 模型只接触虚拟路径 /agent-output/<sessionId>/...，真实目录永不进入模型上下文；
+ *   - 产物登记表（registry）：模型按用户指示写到「任意位置」（如用户指定目录）的文件，
+ *     在执行层登记真实路径后即成为本会话产物——原位置即产物，不复制、不搬移进 .agent；
+ *     用户未指定位置时仍默认落 .agent/<sessionId>（见 buildArtifactPrompt）；
+ *   - 基线/增量扫描：一轮对话后找出新文件，作为产物推给前端；
+ *   - 安全读取：readArtifact 严格限制在 session 目录内与已登记的产物路径上，任何穿越尝试返回 null；
+ *   - 脱敏：redactOutputPaths 抹掉模型可能复述的 /agent-output 标记。
+ */
+/** 真实磁盘产物目录名（隐藏目录：选了项目在项目根、无项目在 ~ 下），靠 .gitignore 排除 */
+export declare const ARTIFACT_DIR_NAME = ".agent";
+/** 模型上下文里的虚拟输出根：模型写文件用 /agent-output/<sessionId>/<name>（保持稳定，不改） */
+export declare const ARTIFACT_VIRTUAL_ROOT = "/agent-output";
+/** 产物根目录（真实磁盘位置，宿主侧）：无工作区时统一放用户目录 ~/.agent */
+export declare function artifactRoot(): string;
+/**
+ * CodeBuddy CLI 沙箱项目根：<homedir>/.codebuddy/projects/<cwd转写>/。
+ * 模型用 Bash/Python 等工具写文件时，默认落在沙箱会话目录 <project>/<sessionId>/（而非宿主 .agent），
+ * 因此产物收集与读取必须同时覆盖两个位置。转写规则：X:\a\b → x-a-b。
+ * cwdOverride：工作区模式下传工作目录（CLI cwd 已是工作目录，沙箱根随 cwd 变化）；
+ * 目录不存在时返回 null（非 CodeBuddy CLI 环境不启用）。
+ */
+export declare function sandboxProjectRoot(cwdOverride?: string): string | null;
+/** 某会话的候选产物目录：产物根/.agent/<sid> + 沙箱 <project>/<sid>（存在时），产物根优先 */
+export declare function sessionDirCandidates(sessionId: string, workspaceDir?: string): string[];
+/**
+ * 取会话「基 id」：编辑重发/重新生成时，前端会把发给服务端的 SDK transcript id
+ * 换成 `${sid}_${uuid}`（让 CLI 不加载旧 transcript，见 ChatWindow 的 rt.sdkSid），
+ * 产物目录因此跟着换成一个「分叉目录」。但产物**归属仍是原会话**——前端卡片与
+ * 预览请求一律带基 sid（activeSid）。会话 id 是 UUID 本身不含 '_'，故 '_' 前段即基 id。
+ */
+export declare function baseSessionId(sessionId: string): string;
+/**
+ * 同源分叉目录列表：某基会话下所有 `<base>_<uuid>` 目录（宿主根 + 沙箱根）。
+ *
+ * 为什么需要：模型写文件时用的是当轮真实的 SDK transcript id（编辑重发 = 新 transcript），
+ * 于是文件落在分叉目录里；而读取/列举一律按基会话走。不把分叉目录并进来就会出现
+ * 「卡片在、点开 404」的错觉（文件明明在磁盘上）。按基 id 前缀扫一层目录即可覆盖，
+ * 根目录条目数量级为会话数，可接受。
+ */
+export declare function forkSessionDirs(sessionId: string, workspaceDir?: string): Promise<string[]>;
+/** 读取用：基目录候选 + 全部分叉目录（去重，保持「宿主根优先」的既有次序）。 */
+export declare function readDirCandidates(sessionId: string, workspaceDir?: string): Promise<string[]>;
+/** 只允许会话 ID 使用安全字符，杜绝路径穿越 */
+export declare function sanitizeSessionId(s: string): string;
+/** 清洗文件名：去除前导分隔符、去除 . 与 .. 段，防穿越；过长截断 */
+export declare function sanitizeArtifactName(name: string): string;
+/**
+ * 中间产物目录名（相对会话目录的**第一段**命中即视为中间产物，不向用户展示）：
+ *  - _drafts / _intermediate / _tmp：模型写草稿 / 临时 / 半成品文件的约定目录（见 buildArtifactPrompt）；
+ *  - tool-results：CodeBuddy CLI 沙箱会话目录里的内部工具执行记录（chatcmpl-tool-*-render.txt、
+ *    mcp-web-fetch-*.txt 等），不是用户可见产物；
+ *  - subagents：CLI 子代理（subagent）的 transcript / 结果目录（位于会话目录内 subagents/<id>/），
+ *    同样属于 SDK 内部文件，不是用户交互产物；
+ *  - attachments：**用户上传附件的 staging 目录**（服务端把用户文件复制到 CLI cwd 的
+ *    attachments/<rel>，见 handlers.ts stageVirtualCopy）。用户的文件永远不是模型生成的产物，
+ *    收集/列表必须整体跳过——否则用户截图会出现在「产物」面板里。
+ * 只有会话目录根下（及非保留子目录）的文件才是「最终产物」。
+ * 点开头（隐藏文件/目录）同样视为中间产物，避免 .DS_Store/.gitkeep 之类进入产物列表。
+ */
+export declare const INTERMEDIATE_DIR_NAMES: ReadonlySet<string>;
+/** 判断一个相对路径是否属于中间产物：第一段命中保留目录名 / 以点开头；
+ *  或**任意路径段**命中 CodeBuddy CLI 内部目录（tool-results / subagents / .codebuddy）——
+ *  subagents/<id>/tool-results/xxx 这类 SDK 内部文件即使不在第一段也必须过滤。 */
+export declare function isIntermediateRel(rel: string): boolean;
+/** CLI 内部绝对路径判定（registry 登记条目用）：路径任意段命中 tool-results/subagents/.codebuddy
+ *  → CodeBuddy SDK 内部文件，不是用户交互产物，不展示。 */
+export declare function isCliInternalAbsPath(abs: string): boolean;
+/** 登记条目：absPath 是唯一权威路径，lastSeen/戳 用于 added/modified/deleted 判定 */
+export interface RegistryEntry {
+    /** 稳定唯一 id：会话目录内 = 相对路径（与扫描产物一致）；工作目录根 = 文件名（兼容历史）；
+     *  其他任意路径（用户指定目录）= ext-<hash8>-<basename> */
+    id: string;
+    /** 展示名（文件 basename） */
+    name: string;
+    /** 真实绝对路径（原位置，不复制） */
+    absPath: string;
+    type: ArtifactType;
+    /** 上次收集时的 mtimeNs（bigint 转字符串）；从未成功收集则无 */
+    mtimeNs?: string;
+    /** 上次收集时的文件字节数 */
+    size?: number;
+    /** 登记来源：model=模型工具写的真产物；scan=列表兜底扫描顺带的工程文件（需再判定） */
+    origin?: RegistryOrigin;
+    /** 登记时刻 ms（scan 条目用它：登记之后没被改写过 = 本来就存在的工程文件 → 不展示） */
+    registeredAt?: number;
+    /** 上次收集时文件是否存在于磁盘（false 且仍不存在 → 登记但写入失败，不报 deleted） */
+    lastSeen: boolean;
+    /** 首次写入前不存在才是本会话产出；编辑已有文件只进入变更列表。 */
+    createdBySession?: boolean;
+}
+/** 读取会话登记表（损坏/不存在 → 空数组）。
+ *  含编辑重发/重新生成产生的分叉登记表（`<base>_<uuid>`）：模型那一轮写的是分叉
+ *  transcript id，登记项落在分叉登记表里，而读取一律按基会话走 → 必须合并，
+ *  否则「模型写到用户指定目录」的文件会出现同样的卡片 404。 */
+export declare function loadRegistry(sessionId: string, workspaceDir?: string): Promise<RegistryEntry[]>;
+/** 原子替换登记表，读取列表不会看到半截 JSON。 */
+export declare function saveRegistry(sessionId: string, entries: RegistryEntry[], workspaceDir?: string): Promise<void>;
+/** 把模型工具入参里的路径归一化为真实绝对路径：
+ *  - /agent-output/<sid>/x → <产物根>/<sid>/x（与 pathAliases 同一映射，登记层拿原始入参时自行解析）
+ *  - bash 风格 /d/a/b → D:\a\b（Windows）
+ *  - 相对路径 → 相对执行 cwd 解析
+ *  无法解析返回 null。 */
+export declare function normalizeArtifactAbsPath(rawPath: string, workspaceDir?: string, cwd?: string): string | null;
+/**
+ * 登记一个产物路径（幂等：absPath 已登记则跳过）。id 规则：
+ *  - 在会话目录候选内 → 相对会话目录路径（与扫描产物 id 一致，天然去重）；
+ *  - 工作目录根散落文件 → 文件名（与历史 collectWorkFiles id 一致，旧卡片可继续预览）；
+ *  - 其他任意路径（用户指定目录）→ ext-<hash8>-<basename>。
+ */
+export declare function registerArtifactPath(sessionId: string, rawPath: string, workspaceDir?: string, cwd?: string, origin?: RegistryOrigin, before?: ArtifactStamp): Promise<void>;
+export type ArtifactType = "html" | "markdown" | "image" | "pdf" | "text" | "word" | "other";
+export declare function artifactType(name: string): ArtifactType;
+export declare function mimeFor(name: string): string;
+export interface ArtifactMeta {
+    id: string;
+    name: string;
+    type: ArtifactType;
+    /** 文件字节数（前端展示大小） */
+    size?: number;
+    /** 文件所在真实目录（「打开文件夹」跟随文件用）：会话目录内 = 会话目录；
+     *  登记产物（模型写到任意位置） = 该文件自己的父目录。前端桌面壳据此 shell.openPath。 */
+    dir?: string;
+}
+/** 确保会话目录存在并返回其路径（工作区模式下为 <工作区>/.agent/<sid>，无工作区 ~/.agent/<sid>） */
+export declare function ensureSessionDir(sessionId: string, workspaceDir?: string): Promise<string>;
+/** 文件是否参与文本 diff（扩展名在白名单内） */
+export declare function isTextDiffable(name: string): boolean;
+/** 登记条目的来源：model=模型工具写的（真产物）；scan=列表兜底扫描顺带的工程文件（待判定） */
+export type RegistryOrigin = "model" | "scan";
+/** 产物文件戳：记录修改时间（纳秒 BigInt）与大小，用于识别「新增」与「内容更新」（同名覆盖）。
+ *  content：文本文件（isTextDiffable 且 ≤ 上限）在本轮开始前的内容快照，供本轮 diff 展示旧内容；
+ *  二进制/超大文件为 null（只标记变更类型，不参与内容对比）。
+ *  注意：bigint 模式下 fs.stat 的 mtimeNs 是 bigint、size 是 bigint，统一在存取处转 Number(size)。 */
+export interface ArtifactStamp {
+    mtimeNs: bigint;
+    size: number;
+    content?: string | null;
+    /** false 是已确认的不存在状态，必须保留，不能让后续编辑覆盖为已有文件。 */
+    exists?: boolean;
+    digest?: string;
+}
+/**
+ * 基线：记录某会话「开始前」已存在的产物（宿主 + 沙箱两个位置的会话目录，以及产物根下散落文件），
+ * 返回 key（"s:"/"t:" + 文件名）→ 文件戳，用于增量与更新识别。
+ */
+export declare function baselineArtifacts(sessionId: string, workspaceDir?: string): Promise<Map<string, ArtifactStamp>>;
+/** 产物变更：本轮对会话目录内文件的新增/修改/删除，带新旧内容（文本文件）供前端 diff 展示。 */
+export interface ArtifactChange extends ArtifactMeta {
+    /** 本轮变更类型：added=新增、modified=内容更新、deleted=被删除 */
+    change: "added" | "modified" | "deleted";
+    /** 变更前内容（文本基线快照；deleted 时为被删文件的最后内容；二进制/超限为 null） */
+    oldContent?: string | null;
+    /** 变更后内容（added/modified 的当前内容；deleted 无此字段） */
+    newContent?: string | null;
+}
+/**
+ * 写工具执行前采集：目标文件在本轮编辑前是否已存在 + 文本内容快照（供 diff 旧内容）。
+ * 写入 into（键 = 归一化绝对路径）。同一文件本轮多次编辑只保留首次快照（= 本轮开始前状态）。
+ *
+ * 用途：模型用 Edit/Write 改「已有文件」（如工作区里的工程源码）时，登记表（registry）新建
+ * 条目的 lastSeen 恒为 false，光靠 collectArtifacts 无法区分「新建文件」与「编辑已有文件」，
+ * 会把编辑误判为 added（→ 只进「产物」不进「变更」，且缺旧内容无法 diff）。执行前若文件已存在，
+ * 不存在也保留快照：本轮先 Write 新建再 Edit 时，仍按新建文件归类。
+ */
+export declare function capturePreWriteSnapshot(absPath: string, into: Map<string, ArtifactStamp>): Promise<void>;
+/**
+ * 一轮对话结束后收集本轮「变更」（新增、内容更新、删除）：
+ *  - 会话子目录（宿主 .agent 与 CodeBuddy 沙箱两处）里的新文件/更新文件记为变更（added/modified），
+ *    递归扫描子目录（模型常把产物写进 brand-icons/ 等子目录，此前只扫顶层导致卡片缺失）；
+ *  - 中间产物目录（_drafts/、_intermediate/、_tmp/ 及点开头隐藏项）一律不收集，
+ *    只有会话目录根下（及非保留子目录）的文件才作为「最终产物」呈现给用户；
+ *  - 宿主根目录下「散落」的新**文件**（模型忘记带 sessionId 子目录）移入会话子目录，保证隔离；
+ *    **根目录下的目录不做任何搬移/扫描**——它可能是其他会话自己的目录，搬入会造成跨会话产物混入；
+ *  - 同名文件被重新写入（覆盖/更新，mtime 或大小变化）记为 modified；
+ *  - 删除检测：会话子目录内基线存在、本轮结束后磁盘已无 → deleted（根目录散落文件不判，
+ *    它们可能被搬移进会话目录或属其他会话，误判风险高）；
+ *  - 文本文件（isTextDiffable 且 ≤ 上限）携带 oldContent/newContent 供前端左右 diff；
+ *    二进制/超大文件只标记变更类型。
+ * 返回变更清单（新增/修改在前、删除在后，按 id 去重）。id 为相对会话目录的 posix 路径。
+ */
+export declare function collectArtifacts(sessionId: string, baseline: Map<string, ArtifactStamp>, workspaceDir?: string, 
+/** 写工具执行前的目标文件快照（键 = 归一化绝对路径）：区分「编辑已有文件」与「新建文件」并提供 diff 旧内容 */
+preWrite?: Map<string, ArtifactStamp>): Promise<ArtifactChange[]>;
+/**
+ * 列出某会话的全部产物（递归，含非保留子目录），用于「查看所有产物 (N)」按钮与右侧列表面板。
+ * 与 collectArtifacts 不同：不做基线增量，直接返回磁盘上当前存在的全部文件；
+ * 中间产物目录（_drafts/ 等）与隐藏文件不进入列表，只呈现最终产物。
+ * 会话目录不存在时返回空数组。
+ */
+export declare function listSessionArtifacts(sessionId: string, workspaceDir?: string): Promise<ArtifactMeta[]>;
+/** 安全读取产物：在产物根与沙箱候选会话目录内查找（产物根优先），任何穿越尝试返回 null；
+ *  会话目录未命中时，回查登记表（registry）：模型写到任意位置的文件按登记 id/name 读原路径，
+ *  仅限已登记的真实路径（任意 id 无法读取未登记文件）。 */
+export declare function readArtifact(sessionId: string, id: string, workspaceDir?: string): Promise<{
+    buf: Buffer;
+    mime: string;
+} | null>;
+/** 构造前端拉取产物的隔离 URL（session 与 file 均经编码，服务端二次校验） */
+export declare function artifactUrl(basePath: string, sessionId: string, id: string): string;
+/**
+ * 脱敏（第一道）：把「真实产物根目录」替换成虚拟标记 /agent-output。
+ * 同时处理 Windows 盘符路径（D:\...\agent-output）与 CLI 使用的 bash 风格路径（/d/.../agent-output），
+ * 避免任一真实路径残留在模型输出中。
+ */
+export declare function redactArtifactPaths(text: string): string;
+/**
+ * 脱敏：抹掉模型可能复述的虚拟输出路径标记（/agent-output...），
+ * 避免内部约定外泄。配合系统提示（不要提路径）作为安全网。
+ */
+export declare function redactOutputPaths(text: string): string;
+/**
+ * 清洗助手文本里的限流噪音（服务端源头，防止 429 错误进入回复正文/存库）：
+ *  - CLI transcript 会给消息加 trace 前缀（(32hex/uuid)），剥离前缀、保留正文；
+ *  - 429 频率限制错误整段（可能带 trace 前缀/后缀）直接丢弃；
+ *  - 内容若清洗后为空（纯错误轮次），返回空串，前端不展示空气泡。
+ */
+export declare function sanitizeAssistantText(text: string): string;