@youweichen/pi-harness 0.0.0-stage → 1.1.0

package/dist/server/files-service.js

@@ -0,0 +1,787 @@
+/**
+ * Files service — 从 agent-service.ts 抽出（文件树列目录 / 预览读写 / 路径补全 /
+ * SCM 只读查询 / 目录与 git-dir watcher）。
+ *
+ * 全部为无状态 fs 操作 + 两个自持的 watcher（当前列出目录、git dir），
+ * 经 FilesHost 回调与 ClientSession 解耦。
+ */
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync, statSync, writeFileSync, watch } from "node:fs";
+import { isAbsolute, resolve, relative, sep } from "node:path";
+import { previewKind, looksLikeText, decodeText, hexDump, countLines, } from "./text-sniff.js";
+import { gitDirOf, isNotRepoError, scmStatus, scmCurrentBranch, scmHistory, scmFileDiff, scmDiff, scmCommitDetail, } from "./scm.js";
+export const IS_WIN32 = process.platform === "win32";
+/** 预览只读文件前 512KB。 */
+export const MAX_PREVIEW_BYTES = 512 * 1024;
+/** Confirm history-derived paths exist as files inside this workspace. */
+export function existingConversationFiles(cwd, paths) {
+    let root;
+    try {
+        root = realpathSync(cwd);
+    }
+    catch {
+        return [];
+    }
+    const seen = new Set();
+    const found = [];
+    for (const path of paths.slice(0, 64)) {
+        if (typeof path !== "string" || path.length > 4096 || path.includes("\0") || seen.has(path))
+            continue;
+        seen.add(path);
+        const normalized = path.replaceAll("\\", "/");
+        if (normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized) || normalized.split("/").includes(".."))
+            continue;
+        try {
+            const target = realpathSync(resolve(root, normalized));
+            const rel = relative(root, target);
+            if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || resolve(root, rel) !== target)
+                continue;
+            if (statSync(target).isFile())
+                found.push(path);
+        }
+        catch { /* removed, unreadable, or invalid */ }
+    }
+    return found;
+}
+// mac/linux: hide build & dependency noise (original behavior).
+const IGNORED_ENTRIES = new Set([
+    "node_modules",
+    ".git",
+    ".svn",
+    ".hg",
+    "dist",
+    ".next",
+    ".nuxt",
+    ".cache",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "coverage",
+    ".pi-web",
+    ".DS_Store",
+    "Thumbs.db",
+]);
+// Windows: the file tree is the primary way to navigate a project, so only
+// hide what would flood or destabilize the panel (dependency trees, VCS
+// internals, session data) plus pure junk. Build output (dist/.next/…) and
+// local env dirs (venv/__pycache__/…) stay visible — "所有文件可查看".
+const IGNORED_ENTRIES_WIN = new Set([
+    "node_modules",
+    ".git",
+    ".pi-web",
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+]);
+/** The ignore set for the current platform — keeps win/posix lists separate. */
+function ignoredEntries() {
+    return IS_WIN32 ? IGNORED_ENTRIES_WIN : IGNORED_ENTRIES;
+}
+/**
+ * Resolve a workspace-relative path against a root, refusing traversal
+ * (".." escapes). Returns { abs, rel } — rel is normalized and slash-
+ * separated — or null when the path leaves the workspace.
+ */
+export function workspacePath(root, raw) {
+    const abs = resolve(root, raw);
+    const rawRel = relative(root, abs);
+    // relative() yields an absolute path across Windows drives / UNC shares, and
+    // "..foo" is a legitimate file name — only a real ".." segment escapes.
+    if (isAbsolute(rawRel) || rawRel === ".." || rawRel.startsWith(`..${sep}`))
+        return null;
+    // Normalize to forward slashes: the wire protocol and the frontend always
+    // use "/", but relative() returns "\\" on Windows.
+    return { abs, rel: rawRel.split(sep).join("/") };
+}
+/**
+ * Symlink-aware containment: a link inside the workspace that points outside
+ * must not expose the target. A missing file is left to the caller's own
+ * stat/open to report.
+ */
+export function isRealPathInWorkspace(root, abs) {
+    try {
+        const rel = relative(realpathSync(root), realpathSync(abs));
+        return !(isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`));
+    }
+    catch (err) {
+        return err.code === "ENOENT";
+    }
+}
+/**
+ * Read a directory for the file panel. The two platforms intentionally use
+ * different strategies — do NOT unify them:
+ *
+ * darwin/linux (posix): original behavior — hide build/dependency noise,
+ * small cap, hard error notice when the directory itself is unreadable.
+ *
+ * win32: stability and completeness first, preview second. ACL-protected
+ * system dirs (C:\$Recycle.Bin, Program Files internals, OneDrive placeholders)
+ * throw EPERM/EACCES on open — that must not kill the panel, so it degrades
+ * to an empty listing with a node-local error. Directory symlinks/junctions are
+ * followed so mklink /D folders stay navigable; broken links still show as
+ * files instead of vanishing. The cap is 4x posix and truncation is reported
+ * via `truncated` instead of happening silently.
+ */
+async function readDirForUI(abs, rel) {
+    const { join } = await import("node:path");
+    const fs = await import("node:fs/promises");
+    const ignored = ignoredEntries();
+    const MAX = IS_WIN32 ? 2000 : 500;
+    let dirents;
+    try {
+        dirents = await fs.readdir(abs, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        return { entries: [], truncated: false, error: {
+                code: code === "ENOENT" ? "missing" : code === "ENOTDIR" ? "not_directory" : code === "EACCES" || code === "EPERM" ? "denied" : "unavailable",
+                message: err.message,
+            } };
+    }
+    const out = [];
+    for (const d of dirents) {
+        if (ignored.has(d.name))
+            continue;
+        let type;
+        if (IS_WIN32 && d.isSymbolicLink()) {
+            // mklink /D symlinks and junctions are reparse points — libuv
+            // classifies them as links, so isDirectory() is false. Follow the
+            // target so folder links stay navigable; broken links still show.
+            try {
+                const st = await fs.stat(join(abs, d.name));
+                type = st.isDirectory() ? "dir" : "file";
+            }
+            catch {
+                type = "file";
+            }
+        }
+        else {
+            type = d.isDirectory() ? "dir" : "file";
+        }
+        const entry = {
+            name: d.name,
+            path: rel === "" ? d.name : `${rel}/${d.name}`,
+            type,
+        };
+        if (type === "file")
+            entry.kind = previewKind(d.name);
+        out.push(entry);
+    }
+    out.sort((a, b) => a.type === b.type
+        ? a.name.localeCompare(b.name)
+        : a.type === "dir"
+            ? -1
+            : 1);
+    const truncated = out.length > MAX;
+    if (truncated)
+        out.length = MAX;
+    return { entries: out, truncated };
+}
+export class FilesService {
+    host;
+    // ---- 当前列出目录的 watcher ----
+    fsWatcher = null;
+    watchPath = null;
+    watchTimer = null;
+    /** Recursive-watch state (win32/darwin): one native recursive watcher on the
+     *  workspace root covers the WHOLE tree; watchPath just tracks which listed
+     *  directory file_changed should refresh. */
+    recursiveWatcher = false;
+    watchRoot = null;
+    /** 已对哪个工作区根提示过「实时监听不可用，已回落轮询」——只提示一次。 */
+    degradedNoticedFor = null;
+    // ---- git dir watcher ----
+    gitWatcher = null;
+    gitWatchCwd = null;
+    gitDirtyTimer = null;
+    constructor(host) {
+        this.host = host;
+    }
+    listingRequests = new Map();
+    async listFiles(relPath) {
+        const cwd = this.host.getCwd();
+        const key = `${cwd}\0${relPath ?? ""}`;
+        const existing = this.listingRequests.get(key);
+        if (existing)
+            return existing;
+        const pending = this.scanFiles(cwd, relPath).finally(() => this.listingRequests.delete(key));
+        this.listingRequests.set(key, pending);
+        return pending;
+    }
+    async scanFiles(cwd, relPath) {
+        const { resolve, sep, relative } = await import("node:path");
+        const root = resolve(cwd);
+        const target = relPath ? resolve(root, relPath) : root;
+        const rawRel = relative(root, target);
+        if (rawRel.startsWith("..") || rawRel.includes(`${sep}..`)) {
+            this.host.emit({
+                type: "notice",
+                level: "warning",
+                text: `路径超出工作区：${relPath ?? ""}`,
+            });
+            return;
+        }
+        // Normalize to forward slashes: the wire protocol and the frontend
+        // always use "/", but relative() returns "\\" on Windows.
+        const rel = rawRel.split(sep).join("/");
+        const { entries, truncated, error } = await readDirForUI(target, rel);
+        this.host.emit({
+            type: "files",
+            cwd,
+            path: rel === "" ? "" : rel,
+            parent: rel === ""
+                ? null
+                : rel.includes("/")
+                    ? rel.slice(0, rel.lastIndexOf("/"))
+                    : "",
+            entries,
+            truncated,
+            ...(error ? { error } : {}),
+        });
+        // Watch the listed directory — deferred until AFTER the response is on
+        // the wire. On win32, fs.watch(root, {recursive:true}) registering over
+        // a big tree (node_modules et al) can itself take a noticeable moment
+        // (ReadDirectoryChangesW setup cost scales with tree size, unlike
+        // macOS's FSEvents); doing it inline before the emit made every
+        // project switch wait on that registration instead of just seeing the
+        // file list immediately and having the watcher arm a beat later.
+        if (!error && cwd === this.host.getCwd())
+            this.watchDir(target, rel);
+    }
+    /**
+     * Global search: recursive filename match across the active workspace.
+     * Best-effort bounded walk — ignored dirs (node_modules/.git/…) are
+     * skipped, unreadable dirs silently passed, and hard caps on results /
+     * visited entries / elapsed time keep big repos responsive. Always answers
+     * with a search_files_result echoing reqId so the client's request never
+     * stalls (ok:false on unexpected failure).
+     */
+    async searchFiles(query, reqId) {
+        const cwd = this.host.getActiveCwd();
+        const { join } = await import("node:path");
+        const fsp = await import("node:fs/promises");
+        const q = query.trim().toLowerCase();
+        if (!q) {
+            this.host.emit({ type: "search_files_result", cwd, reqId, ok: true, results: [] });
+            return;
+        }
+        const root = resolve(cwd);
+        const ignored = ignoredEntries();
+        const MAX_RESULTS = 50;
+        const MAX_VISITED = 20000;
+        const MAX_MS = 4000;
+        const start = Date.now();
+        const results = [];
+        let visited = 0;
+        let truncated = false;
+        const budgetLeft = () => results.length < MAX_RESULTS &&
+            visited < MAX_VISITED &&
+            Date.now() - start < MAX_MS;
+        // Breadth-first-ish iterative stack; depth cap is a symlink-cycle guard.
+        const walk = async (abs, rel, depth) => {
+            if (!budgetLeft() || depth > 24) {
+                truncated = true;
+                return;
+            }
+            let dirents;
+            try {
+                dirents = await fsp.readdir(abs, { withFileTypes: true });
+            }
+            catch {
+                return; // unreadable dir (ACL/permissions) — skip silently
+            }
+            for (const d of dirents) {
+                visited++;
+                if (!budgetLeft()) {
+                    truncated = true;
+                    break;
+                }
+                if (ignored.has(d.name))
+                    continue;
+                const childRel = rel ? `${rel}/${d.name}` : d.name;
+                if (d.name.toLowerCase().includes(q)) {
+                    results.push({
+                        path: childRel,
+                        name: d.name,
+                        type: d.isDirectory() ? "dir" : "file",
+                    });
+                }
+                if (d.isDirectory()) {
+                    await walk(join(abs, d.name), childRel, depth + 1);
+                }
+            }
+        };
+        try {
+            await walk(root, "", 0);
+            this.host.emit({
+                type: "search_files_result", cwd,
+                reqId,
+                ok: true,
+                results,
+                ...(truncated ? { truncated: true } : {}),
+            });
+        }
+        catch {
+            this.host.emit({ type: "search_files_result", cwd, reqId, ok: false, results: [] });
+        }
+    }
+    /**
+     * Source-control panel: read-only git queries via server-side execFile
+     * (no shell, no prompts). Always responds with an scm_data message echoing
+     * reqId so the client's request matching never stalls. Also (re)arms the
+     * git-dir watcher so external repo changes push scm_changed.
+     */
+    branchRequests = new Map();
+    diffRequests = new Map();
+    async gitBranch() {
+        const cwd = this.host.getActiveCwd();
+        const pending = this.branchRequests.get(cwd);
+        if (pending)
+            return pending;
+        const request = (async () => {
+            await this.watchGitDir(cwd);
+            const info = await scmCurrentBranch(cwd);
+            this.host.emit({ type: "git_branch", cwd, ...info });
+        })().finally(() => this.branchRequests.delete(cwd));
+        this.branchRequests.set(cwd, request);
+        return request;
+    }
+    async scmQuery(kind, reqId, arg) {
+        const cwd = this.host.getActiveCwd();
+        if (kind === "status")
+            this.watchGitDir(cwd);
+        try {
+            if (kind === "status") {
+                const data = await scmStatus(cwd);
+                this.host.emit({ type: "scm_data", cwd, reqId, kind, ok: true, ...data });
+                return;
+            }
+            if (kind === "diff" && (arg?.scope === "branch" || arg?.scope === "work")) {
+                // The panel refreshes on a timer and on every file change; join a
+                // request that is still running instead of starting another git diff.
+                const key = `${cwd}\0${arg.scope}\0${arg.base ?? ""}`;
+                let pending = this.diffRequests.get(key);
+                if (!pending) {
+                    pending = scmDiff(cwd, { scope: arg.scope, base: arg.base }).finally(() => this.diffRequests.delete(key));
+                    this.diffRequests.set(key, pending);
+                }
+                const data = await pending;
+                this.host.emit({ type: "scm_data", cwd, reqId, kind, ok: true, ...data });
+                return;
+            }
+            if (kind === "history") {
+                const history = await scmHistory(cwd);
+                this.host.emit({ type: "scm_data", cwd, reqId, kind, ok: true, history });
+                return;
+            }
+            if (kind === "filediff" && arg?.path) {
+                // Path stays inside the workspace (defense in depth — paths come
+                // from our own listing, and execFile passes args verbatim anyway).
+                const { resolve, relative } = await import("node:path");
+                const rel = relative(resolve(cwd), resolve(cwd, arg.path));
+                if (rel.startsWith("..") || rel === "")
+                    throw new Error("路径超出工作区");
+                const diff = await scmFileDiff(cwd, arg.path);
+                this.host.emit({
+                    type: "scm_data", cwd, reqId, kind, ok: true,
+                    stagedText: diff.staged, worktreeText: diff.worktree,
+                    untracked: diff.untracked,
+                    untrackedText: diff.untrackedText,
+                    untrackedKind: diff.untrackedKind,
+                    untrackedTruncated: diff.untrackedTruncated,
+                });
+                return;
+            }
+            if (kind === "commit" && arg?.hash && /^[0-9a-f]{7,40}$/i.test(arg.hash)) {
+                const text = await scmCommitDetail(cwd, arg.hash);
+                this.host.emit({ type: "scm_data", cwd, reqId, kind, ok: true, text });
+                return;
+            }
+            throw new Error("无效的 scm 查询参数");
+        }
+        catch (err) {
+            if (isNotRepoError(err)) {
+                // Not a repo — a valid empty answer so the panel shows its hint.
+                this.host.emit({
+                    type: "scm_data", cwd, reqId, kind, ok: true, notRepo: true,
+                    branch: "", detached: false, upstream: null,
+                    ahead: 0, behind: 0, upstreamGone: false,
+                    files: [], branches: [], stats: {}, history: [],
+                });
+                this.unwatchGit();
+                return;
+            }
+            this.host.emit({
+                type: "scm_data", cwd,
+                reqId,
+                kind,
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * Watch the active repo's git dir (HEAD / index / packed-refs live at the
+     * top level, which covers commit / stage / checkout). Re-targets when the
+     * queried workspace changes. Uses `git rev-parse --absolute-git-dir` so
+     * worktrees and submodules resolve to the real dir.
+     */
+    gitWatchGeneration = 0;
+    async watchGitDir(cwd) {
+        if (this.gitWatchCwd === cwd && this.gitWatcher)
+            return;
+        this.unwatchGit();
+        this.gitWatchCwd = cwd;
+        const generation = this.gitWatchGeneration;
+        try {
+            const gitDir = await gitDirOf(cwd);
+            if (!gitDir || this.host.isDisposed() || this.gitWatchGeneration !== generation)
+                return;
+            this.gitWatcher = watch(gitDir, { persistent: false }, () => {
+                if (this.host.isDisposed() || this.gitDirtyTimer)
+                    return;
+                // Debounce: one checkout/commit fires several fs events.
+                this.gitDirtyTimer = setTimeout(() => {
+                    this.gitDirtyTimer = null;
+                    this.host.emit({ type: "scm_changed" });
+                }, 600);
+            });
+            this.gitWatcher.on("error", () => {
+                // Unsupported filesystem — silently fall back to manual refresh.
+                this.unwatchGit();
+            });
+        }
+        catch {
+            // no .git here (or git missing) — watcher stays off; queries still work
+            if (this.gitWatchGeneration === generation)
+                this.unwatchGit();
+        }
+    }
+    unwatchGit() {
+        this.gitWatchGeneration++;
+        if (this.gitWatcher) {
+            try {
+                this.gitWatcher.close();
+            }
+            catch {
+                // already gone
+            }
+        }
+        this.gitWatcher = null;
+        this.gitWatchCwd = null;
+        if (this.gitDirtyTimer) {
+            clearTimeout(this.gitDirtyTimer);
+            this.gitDirtyTimer = null;
+        }
+    }
+    watchDir(absPath, rel) {
+        if (this.host.isDisposed())
+            return;
+        // ---- Recursive mode (native on win32 / darwin): watch the workspace
+        // root once, so deep changes in NOT-listed subdirectories still refresh
+        // the panel (the old per-directory watch only saw the current level).
+        if (process.platform === "win32" || process.platform === "darwin") {
+            const root = resolve(this.host.getCwd());
+            if (this.recursiveWatcher) {
+                if (this.watchRoot === root) {
+                    // Same workspace — only retarget the refresh path.
+                    this.watchPath = rel;
+                    return;
+                }
+                this.unwatchDir(); // cwd switched to another project
+            }
+            try {
+                const w = watch(root, { persistent: false, recursive: true }, (_event, filename) => {
+                    // Skip high-churn subtrees (npm install storms); .git has its
+                    // own watcher for the SCM panel. filename may be null on some
+                    // platforms — let those through (debounce absorbs bursts).
+                    if (filename) {
+                        const f = String(filename).split("\\").join("/");
+                        // Single-segment names (e.g. the dir itself) have no "/" —
+                        // slice(0, -1) would corrupt them, so special-case that.
+                        const slash = f.indexOf("/");
+                        const top = slash === -1 ? f : f.slice(0, slash);
+                        if (top === "node_modules" || top === ".git")
+                            return;
+                    }
+                    // Burst events are debounced into a single refresh.
+                    if (this.watchTimer)
+                        return;
+                    this.watchTimer = setTimeout(() => {
+                        this.watchTimer = null;
+                        this.host.emit({
+                            type: "file_changed",
+                            path: this.watchPath ?? "",
+                        });
+                    }, 400);
+                });
+                w.on("error", () => {
+                    // Directory deleted / unsupported — fall back to poll semantics.
+                    this.noticeDegraded(root);
+                    this.unwatchDir();
+                });
+                this.fsWatcher = w;
+                this.watchRoot = root;
+                this.recursiveWatcher = true;
+                this.watchPath = rel;
+                return;
+            }
+            catch {
+                // recursive unsupported here — fall through to per-directory watch.
+                this.fsWatcher = null;
+                this.recursiveWatcher = false;
+                this.watchRoot = null;
+                this.noticeDegraded(root);
+            }
+        }
+        // ---- Fallback: single non-recursive watch on the LISTED directory.
+        if (!this.recursiveWatcher && this.watchPath === rel && this.fsWatcher)
+            return;
+        this.unwatchDir();
+        this.watchPath = rel;
+        try {
+            // persistent: false — the watcher must not keep the process alive.
+            this.fsWatcher = watch(absPath, { persistent: false }, () => {
+                // Burst events (npm install, git ops, editor save→rename) are
+                // debounced into a single refresh.
+                if (this.watchTimer)
+                    return;
+                this.watchTimer = setTimeout(() => {
+                    this.watchTimer = null;
+                    this.host.emit({ type: "file_changed", path: this.watchPath ?? "" });
+                }, 400);
+            });
+            this.fsWatcher.on("error", () => {
+                // Directory deleted / unsupported fs — stop watching; the poll (or
+                // the next navigation) restores things.
+                this.unwatchDir();
+            });
+        }
+        catch {
+            // fs.watch unsupported (some network mounts, containers) — poll covers it.
+            this.fsWatcher = null;
+            this.watchPath = null;
+            this.noticeDegraded(absPath);
+        }
+    }
+    /** 实时监听不可用（网络盘/WSL/受限目录）：一次性告知用户已回落 10s 轮询，
+     *  免得疑惑「面板为什么不实时」。每个工作区根只提示一次。 */
+    noticeDegraded(root) {
+        if (this.degradedNoticedFor === root)
+            return;
+        this.degradedNoticedFor = root;
+        this.host.emit({
+            type: "notice",
+            level: "info",
+            text: "此目录不支持实时文件监听（网络盘/受限目录），文件面板已改为每 10 秒自动刷新。",
+        });
+    }
+    unwatchDir() {
+        if (this.watchTimer) {
+            clearTimeout(this.watchTimer);
+            this.watchTimer = null;
+        }
+        if (this.fsWatcher) {
+            try {
+                this.fsWatcher.close();
+            }
+            catch {
+                // already closed
+            }
+            this.fsWatcher = null;
+        }
+        this.recursiveWatcher = false;
+        this.watchRoot = null;
+        this.watchPath = null;
+    }
+    /** Read a workspace file for the preview panel (size-capped, binary-safe). */
+    async readFile(relPath, options = {}) {
+        const cwd = this.host.getCwd();
+        try {
+            if (options.cwd !== undefined && options.cwd !== cwd)
+                throw new Error("工作区已改变");
+            const fs = await import("node:fs/promises");
+            const root = cwd;
+            const wp = workspacePath(resolve(root), relPath);
+            if (!wp) {
+                throw new Error("路径超出工作区");
+            }
+            const { abs, rel } = wp;
+            if (!isRealPathInWorkspace(root, abs))
+                throw new Error("路径超出工作区");
+            const stat = await fs.stat(abs);
+            if (!stat.isFile()) {
+                throw new Error("不是文件");
+            }
+            const name = relPath.split(/[\\/]/).pop() ?? relPath;
+            const kind = previewKind(name);
+            // Media previews stream over the /api/file HTTP endpoint, so only
+            // metadata is sent here — the raw bytes never touch the socket.
+            if (kind === "image" || kind === "video" || kind === "sqlite") {
+                this.host.emit({
+                    type: "file_content",
+                    requestId: options.requestId,
+                    cwd,
+                    path: rel,
+                    name,
+                    text: "",
+                    truncated: false,
+                    binary: true,
+                    kind,
+                    lines: 0,
+                    size: stat.size,
+                });
+                return;
+            }
+            // Everything else: read a capped prefix and sniff the content.
+            // Anything that looks like text previews as text regardless of its
+            // extension (jsonl, .log.1, weird suffixes, …); binary content gets
+            // a hex dump of the first few KB instead of being refused.
+            const handle = await fs.open(abs, "r");
+            try {
+                const buf = Buffer.alloc(Math.min(stat.size, MAX_PREVIEW_BYTES));
+                const { bytesRead } = await handle.read(buf, 0, buf.length, 0);
+                const data = buf.subarray(0, bytesRead);
+                if (data.subarray(0, 16).toString("utf8") === "SQLite format 3\0") {
+                    this.host.emit({ type: "file_content", requestId: options.requestId, cwd, path: rel, name, text: "", truncated: false, binary: true, kind: "sqlite", lines: 0, size: stat.size });
+                }
+                else if (looksLikeText(data)) {
+                    this.host.emit({
+                        type: "file_content",
+                        requestId: options.requestId,
+                        cwd,
+                        path: rel,
+                        name,
+                        text: decodeText(data),
+                        version: createHash("sha256").update(data).digest("hex"),
+                        truncated: bytesRead < stat.size,
+                        binary: false,
+                        kind: "text",
+                        lines: countLines(data),
+                        size: stat.size,
+                    });
+                }
+                else {
+                    this.host.emit({
+                        type: "file_content",
+                        requestId: options.requestId,
+                        cwd,
+                        path: rel,
+                        name,
+                        text: hexDump(data),
+                        truncated: bytesRead < stat.size,
+                        binary: true,
+                        kind: kind === "text" ? "text" : "none",
+                        lines: 0,
+                        size: stat.size,
+                    });
+                }
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (err) {
+            this.host.emit({ type: "file_result", operation: "read", requestId: options.requestId, cwd, path: relPath, ok: false, error: err.message });
+        }
+    }
+    /** Save text from the file preview panel within the active workspace. */
+    async writeFile(relPath, text, options = {}) {
+        const cwd = this.host.getCwd();
+        const result = { type: "file_result", operation: "write", requestId: options.requestId, cwd, path: relPath };
+        try {
+            if (options.cwd !== undefined && options.cwd !== cwd)
+                throw new Error("工作区已改变");
+            const wp = workspacePath(resolve(cwd), relPath);
+            if (!wp || !isRealPathInWorkspace(cwd, wp.abs))
+                throw new Error("路径超出工作区");
+            if (Buffer.byteLength(text, "utf8") > 2 * 1024 * 1024)
+                throw new Error("文件内容过大（上限 2MB）");
+            const stat = statSync(wp.abs);
+            if (!stat.isFile() || stat.size > MAX_PREVIEW_BYTES)
+                throw new Error("文件不是可编辑的完整文本");
+            const data = readFileSync(wp.abs);
+            if (!looksLikeText(data))
+                throw new Error("二进制文件不可编辑");
+            const version = createHash("sha256").update(data).digest("hex");
+            if (!options.force && options.expectedVersion !== version) {
+                this.host.emit({ ...result, ok: false, conflict: true, error: "磁盘内容已改变，请重新加载或明确覆盖" });
+                return;
+            }
+            // No await between checking the version and writing: concurrent UI saves serialize.
+            writeFileSync(wp.abs, text, "utf8");
+            this.host.emit({ ...result, ok: true, version: createHash("sha256").update(text).digest("hex") });
+        }
+        catch (err) {
+            this.host.emit({ ...result, ok: false, error: err.message });
+        }
+    }
+    /**
+     * Path completion for the cwd input: expand ~/relative paths, list the parent
+     * directory, and return prefix matches (dirs first, capped).
+     */
+    async completePath(input) {
+        const empty = () => this.host.emit({ type: "path_completions", completions: [] });
+        try {
+            const fs = await import("node:fs/promises");
+            const { resolve, sep, isAbsolute } = await import("node:path");
+            const { homedir } = await import("node:os");
+            const home = homedir();
+            const cwd = this.host.getCwd();
+            // Expand ~ and relative inputs to an absolute path. Windows users type
+            // backslashes (P:\agent) and ~\ — handle both separator styles.
+            let expanded = input.trim();
+            if (expanded === "") {
+                empty();
+                return;
+            }
+            if (expanded === "~" || expanded === "~\\") {
+                expanded = home;
+            }
+            else if (expanded.startsWith("~/") || expanded.startsWith("~\\")) {
+                expanded = home + sep + expanded.slice(2);
+            }
+            else if (!isAbsolute(expanded)) {
+                expanded = resolve(cwd, expanded);
+            }
+            // Split into parent dir + prefix on the LAST separator of either style
+            // (Windows accepts both / and \, so P:\agent/de must work too).
+            const lastSlash = Math.max(expanded.lastIndexOf("/"), expanded.lastIndexOf("\\"));
+            const dirPart = lastSlash >= 0 ? expanded.slice(0, lastSlash + 1) : "";
+            const prefix = lastSlash >= 0 ? expanded.slice(lastSlash + 1) : expanded;
+            const dirents = await fs
+                .readdir(dirPart, { withFileTypes: true })
+                .catch(() => null);
+            if (!dirents) {
+                empty();
+                return;
+            }
+            const { join } = await import("node:path");
+            const completions = dirents
+                .filter((d) => d.name.startsWith(prefix) && !ignoredEntries().has(d.name))
+                .map((d) => ({
+                name: d.name,
+                // Windows users type backslashes — normalize the completion to the
+                // wire format ("/") so the picked path round-trips cleanly.
+                path: IS_WIN32
+                    ? join(dirPart, d.name).split(sep).join("/")
+                    : dirPart + d.name,
+                type: (d.isDirectory() ? "dir" : "file"),
+            }))
+                .sort((a, b) => {
+                const aHidden = a.name.startsWith(".");
+                const bHidden = b.name.startsWith(".");
+                if (aHidden !== bHidden)
+                    return aHidden ? 1 : -1;
+                if (a.type !== b.type)
+                    return a.type === "dir" ? -1 : 1;
+                return a.name.localeCompare(b.name);
+            })
+                .slice(0, 30);
+            this.host.emit({ type: "path_completions", completions });
+        }
+        catch {
+            empty();
+        }
+    }
+}