@xrkseek/harness 0.5.12 → 0.5.13

package/node_modules/@xrkseek/exec-fs/dist/search.js

@@ -1,6 +1,37 @@
 import { readdir, readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
 import path from "node:path";
+import { scheduler } from "node:timers/promises";
 import { resolveWithinRoot } from "./paths.js";
+/** Skip heavy / generated trees so grep/glob stay interactive on monorepos. */
+export const FS_SEARCH_SKIP_DIR_NAMES = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    ".next",
+    ".nuxt",
+    ".turbo",
+    ".cache",
+    ".parcel-cache",
+    ".vite",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "target",
+    ".idea",
+    ".gradle",
+    ".codegraph",
+    ".scratch-opus",
+    "Pods",
+]);
+/** Soft walk ceiling (still high enough for late-sorted paths). */
+export const FS_SEARCH_WALK_CAP = 100_000;
+/** Skip individual files larger than this for content grep. */
+export const FS_GREP_MAX_FILE_BYTES = 1_000_000;
+/** Yield the event loop this often while walking / grepping. */
+const YIELD_EVERY = 48;
 /** Convert a posix-ish glob to a RegExp. Supports * and ** segments. */
 export function globToRegExp(pattern) {
     const norm = pattern.replace(/\\/g, "/").replace(/^\/+/, "");
@@ -44,62 +75,119 @@ export function matchGlob(relPosix, pattern) {
     const rel = relPosix.replace(/\\/g, "/").replace(/^\.\//, "");
     return globToRegExp(pattern).test(rel);
 }
-async function walkFiles(absDir, rootAbs, out, cap) {
-    if (out.length >= cap)
-        return;
-    let entries;
-    try {
-        entries = await readdir(absDir, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const ent of entries) {
-        if (out.length >= cap)
-            return;
-        if (ent.name === ".git" || ent.name === "node_modules")
-            continue;
-        const abs = path.join(absDir, ent.name);
-        if (ent.isDirectory()) {
-            await walkFiles(abs, rootAbs, out, cap);
-            continue;
+/**
+ * Depth-first walk under `absDir`. Skips junk dir basenames. Invokes `visit`
+ * for each file (posix path relative to `rootAbs`). Stop when visit returns
+ * false or `cap` files have been visited. Yields periodically so Host LLM /
+ * mux work can interleave.
+ */
+export async function walkFilesUnder(absDir, rootAbs, visit, cap = FS_SEARCH_WALK_CAP) {
+    let visited = 0;
+    let sinceYield = 0;
+    const walk = async (dir) => {
+        if (visited >= cap)
+            return false;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
         }
-        if (ent.isFile()) {
+        catch {
+            return true;
+        }
+        for (const ent of entries) {
+            if (visited >= cap)
+                return false;
+            if (ent.isDirectory()) {
+                if (FS_SEARCH_SKIP_DIR_NAMES.has(ent.name))
+                    continue;
+                const abs = path.join(dir, ent.name);
+                if (!(await walk(abs)))
+                    return false;
+                continue;
+            }
+            if (!ent.isFile())
+                continue;
+            const abs = path.join(dir, ent.name);
             const rel = path.relative(rootAbs, abs).replace(/\\/g, "/");
-            out.push(rel);
+            visited += 1;
+            sinceYield += 1;
+            if (sinceYield >= YIELD_EVERY) {
+                sinceYield = 0;
+                await scheduler.yield();
+            }
+            const cont = await visit(rel);
+            if (cont === false)
+                return false;
         }
-    }
+        return true;
+    };
+    await walk(absDir);
 }
 /**
- * Collect files under `root` matching `pattern` (posix paths relative to root).
- * Walks with a generous traversal cap so later-sorted paths aren't missed;
- * only the returned list is cut at `maxResults`.
+ * In-process glob walk (fallback when packaged ripgrep is unavailable).
+ * Matches during the walk and stops at `maxResults`.
  */
-export async function globUnderRoot(root, pattern, options) {
+export async function globWalkUnderRoot(root, pattern, options) {
     const rootAbs = path.resolve(root);
     const maxResults = options?.maxResults ?? 200;
     if (!pattern || typeof pattern !== "string") {
         throw new Error("glob pattern required");
     }
-    const all = [];
-    // Walk cap decoupled from maxResults: a 200-result request must still see
-    // every file (the old Math.max(maxResults*4, 2000) truncated the walk at
-    // 2000 entries, silently dropping later paths like README.md).
-    await walkFiles(rootAbs, rootAbs, all, 100_000);
     const matched = [];
-    for (const rel of all) {
-        if (matchGlob(rel, pattern)) {
-            matched.push(rel);
-            if (matched.length >= maxResults)
-                break;
+    await walkFilesUnder(rootAbs, rootAbs, (rel) => {
+        if (!matchGlob(rel, pattern))
+            return;
+        matched.push(rel);
+        if (matched.length >= maxResults)
+            return false;
+    });
+    return matched;
+}
+/**
+ * Collect files under `root` matching `pattern` (posix paths relative to root).
+ * Prefers packaged ripgrep (`@vscode/ripgrep`, Codex / pi / DSH); falls back
+ * to {@link globWalkUnderRoot} when the binary is missing. Set `XRK_FS_SEARCH=js`
+ * to force the walk.
+ */
+export async function globUnderRoot(root, pattern, options) {
+    if (!pattern || typeof pattern !== "string") {
+        throw new Error("glob pattern required");
+    }
+    const { preferJsSearch, RipgrepUnavailableError, globWithRipgrep } = await import("./ripgrep.js");
+    if (!preferJsSearch()) {
+        try {
+            return await globWithRipgrep(root, pattern, options);
+        }
+        catch (err) {
+            if (!(err instanceof RipgrepUnavailableError))
+                throw err;
         }
     }
-    return matched;
+    return globWalkUnderRoot(root, pattern, options);
+}
+/** Line scan without allocating a full `split` array (hot for large files). */
+export function forEachLine(text, fn) {
+    let start = 0;
+    let lineNo = 1;
+    while (start <= text.length) {
+        let end = text.indexOf("\n", start);
+        if (end < 0)
+            end = text.length;
+        let line = text.slice(start, end);
+        if (line.endsWith("\r"))
+            line = line.slice(0, -1);
+        if (!fn(line, lineNo))
+            return;
+        if (end === text.length)
+            break;
+        start = end + 1;
+        lineNo += 1;
+    }
 }
 /**
- * Search file contents under root for a JS RegExp `pattern` string.
+ * In-process content search (fallback when packaged ripgrep is unavailable).
  */
-export async function grepUnderRoot(root, pattern, options) {
+export async function grepWalkUnderRoot(root, pattern, options) {
     if (!pattern || typeof pattern !== "string") {
         throw new Error("grep pattern required");
     }
@@ -118,56 +206,85 @@ export async function grepUnderRoot(root, pattern, options) {
         const message = err instanceof Error ? err.message : String(err);
         throw new Error(`invalid grep pattern: ${message}`, { cause: err });
     }
-    let files = [];
-    const scopeAbs = scope === "." || scope === ""
-        ? rootAbs
-        : resolveWithinRoot(rootAbs, scope);
-    const st = await fsStat(scopeAbs);
-    if (st.isFile()) {
-        const rel = path.relative(rootAbs, scopeAbs).replace(/\\/g, "/");
-        files = [rel];
-    }
-    else if (st.isDirectory()) {
-        const gathered = [];
-        // Walk cap decoupled from maxResults: same truncation fix as globUnderRoot.
-        await walkFiles(scopeAbs, rootAbs, gathered, 100_000);
-        files = gathered;
-    }
-    if (fileGlob) {
-        files = files.filter((f) => matchGlob(f, fileGlob));
-    }
     const hits = [];
-    for (const rel of files) {
-        if (hits.length >= maxResults)
-            break;
+    const scanFile = async (rel) => {
+        if (fileGlob && !matchGlob(rel, fileGlob))
+            return true;
         const abs = resolveWithinRoot(rootAbs, rel);
+        let st;
+        try {
+            st = await fsStat(abs);
+        }
+        catch {
+            return true;
+        }
+        if (!st.isFile() || st.size > FS_GREP_MAX_FILE_BYTES)
+            return true;
         let text;
         try {
             const buf = await fsReadFile(abs);
-            if (buf.byteLength > 1_000_000)
-                continue;
+            if (buf.byteLength > FS_GREP_MAX_FILE_BYTES)
+                return true;
+            // Cheap binary reject before UTF-8 decode of the whole buffer.
+            const sample = buf.subarray(0, Math.min(buf.byteLength, 8192));
+            if (sample.includes(0))
+                return true;
             text = buf.toString("utf8");
         }
         catch {
-            continue;
+            return true;
         }
-        if (text.includes("\0"))
-            continue;
-        const lines = text.split(/\r?\n/);
-        for (let i = 0; i < lines.length; i += 1) {
-            if (hits.length >= maxResults)
-                break;
-            const line = lines[i] ?? "";
+        forEachLine(text, (line, lineNo) => {
             re.lastIndex = 0;
             if (re.test(line)) {
                 hits.push({
                     path: rel,
-                    line: i + 1,
+                    line: lineNo,
                     text: line.length > 400 ? `${line.slice(0, 400)}…` : line,
                 });
+                if (hits.length >= maxResults)
+                    return false;
             }
-        }
+            return true;
+        });
+        return hits.length < maxResults;
+    };
+    const scopeAbs = scope === "." || scope === ""
+        ? rootAbs
+        : resolveWithinRoot(rootAbs, scope);
+    const st = await fsStat(scopeAbs);
+    if (st.isFile()) {
+        const rel = path.relative(rootAbs, scopeAbs).replace(/\\/g, "/");
+        await scanFile(rel);
+        return hits;
     }
+    if (!st.isDirectory())
+        return hits;
+    await walkFilesUnder(scopeAbs, rootAbs, async (rel) => {
+        if (!(await scanFile(rel)))
+            return false;
+    });
     return hits;
 }
+/**
+ * Search file contents under root. Prefers packaged ripgrep (`--json`);
+ * falls back to {@link grepWalkUnderRoot} when the binary is missing.
+ * Set `XRK_FS_SEARCH=js` to force the walk.
+ */
+export async function grepUnderRoot(root, pattern, options) {
+    if (!pattern || typeof pattern !== "string") {
+        throw new Error("grep pattern required");
+    }
+    const { preferJsSearch, RipgrepUnavailableError, grepWithRipgrep } = await import("./ripgrep.js");
+    if (!preferJsSearch()) {
+        try {
+            return await grepWithRipgrep(root, pattern, options);
+        }
+        catch (err) {
+            if (!(err instanceof RipgrepUnavailableError))
+                throw err;
+        }
+    }
+    return grepWalkUnderRoot(root, pattern, options);
+}
 //# sourceMappingURL=search.js.map

package/node_modules/@xrkseek/exec-fs/dist/search.js.map

@@ -1 +1 @@
-{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/exec-fs/package.json

@@ -14,8 +14,10 @@
     "README.md"
   ],
   "dependencies": {
+    "@vscode/ripgrep": "^1.18.0",
     "@xrkseek/attachment": "workspace:*",
     "@xrkseek/core-tools": "workspace:*",
+    "@xrkseek/exec-subprocess": "workspace:*",
     "@xrkseek/protocol": "workspace:*"
   },
   "license": "MIT",

package/node_modules/@xrkseek/exec-shell/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition } from "@xrkseek/core-tools";
-import type { SubprocessService } from "@xrkseek/exec-subprocess";
+import { type SubprocessService } from "@xrkseek/exec-subprocess";
 export { candidatePwshPaths, PWSH_ENCODING_PREAMBLE, resolvePwshPath, } from "./resolve-pwsh.js";
 export type ShellBackend = "bash" | "cmd" | "pwsh";
 /**
@@ -21,6 +21,13 @@ export interface ShellJobInfo {
     readonly signal?: NodeJS.Signals | null;
     readonly stdout?: string;
     readonly stderr?: string;
+    /**
+     * Complete-stream spill files when the in-memory 256KiB tail dropped the head
+     * (DSH OutputCollector). Omitted from Face wire JobView; surfaced in
+     * `job_output` text when truncated.
+     */
+    readonly stdoutSpillPath?: string;
+    readonly stderrSpillPath?: string;
     /** Managed-job producer detail (DSH JobOutcome.detail). */
     readonly detail?: string;
     /** Epoch ms when the job reached a terminal status; absent while live/stopping. */
@@ -155,6 +162,12 @@ export interface ShellLocalOptions {
     readonly prepareArgv?: (argv: readonly string[], cwd: string | undefined, signal: AbortSignal | undefined, ctx?: {
         readonly ownerSessionId?: string;
     }) => Promise<readonly string[]>;
+    /**
+     * Directory for subprocess spill files on overflow (prefer Host
+     * `{XRK_HOME}/spill` so paths stay inside `hostReadableRoots`). When set,
+     * bash jobs enable spill; omit for in-memory tail only.
+     */
+    readonly spillDir?: string;
 }
 /**
  * One AbortSignal for preparation + execution (DSH bash-local `deadline`).

package/node_modules/@xrkseek/exec-shell/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/exec-shell/dist/index.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { appendUtf8TailCap, prepareSpillBinding, StreamTailCollector, SUBPROCESS_CAPTURE_MAX_BYTES, } from "@xrkseek/exec-subprocess";
 import { fitWithErrorHead, fitWithSuffix } from "./bytes.js";
 import { presentBashCall, presentBashResult } from "./present.js";
 import { PWSH_ENCODING_PREAMBLE, resolvePwshPath, } from "./resolve-pwsh.js";
@@ -95,6 +96,8 @@ export function createLocalShell(options) {
     const backend = options.backend ?? defaultBackend();
     const pwshPath = resolvePwshPath(options.pwshPath);
     const defaultCwd = options.defaultCwd?.trim() || undefined;
+    const spillDir = options.spillDir?.trim() || undefined;
+    const spillOpts = spillDir !== undefined ? prepareSpillBinding({ spillDir }) : undefined;
     const maxJobs = options.maxJobs ?? 64;
     const maxConcurrent = options.maxConcurrentJobs ?? DEFAULT_MAX_CONCURRENT_JOBS;
     if (!Number.isSafeInteger(maxConcurrent) || maxConcurrent < 1) {
@@ -139,6 +142,14 @@ export function createLocalShell(options) {
             throw new Error(`background job limit reached (limit: ${maxConcurrent}); use job_kill to stop an unneeded job, wait for it to finish, then retry`);
         }
     }
+    function dropJob(id) {
+        const job = jobs.get(id);
+        if (job === undefined)
+            return;
+        StreamTailCollector.unlinkSpill(job.info.stdoutSpillPath);
+        StreamTailCollector.unlinkSpill(job.info.stderrSpillPath);
+        jobs.delete(id);
+    }
     function pruneSettled() {
         const settled = [...jobs.entries()]
             .filter(([, job]) => isTerminalStatus(job.info.status))
@@ -148,7 +159,7 @@ export function createLocalShell(options) {
             const oldest = settled.shift();
             if (oldest === undefined)
                 break;
-            jobs.delete(oldest[0]);
+            dropJob(oldest[0]);
         }
     }
     function pruneIfNeeded() {
@@ -159,7 +170,7 @@ export function createLocalShell(options) {
         for (const [id] of finished) {
             if (jobs.size <= maxJobs)
                 break;
-            jobs.delete(id);
+            dropJob(id);
         }
     }
     function markReported(job) {
@@ -202,7 +213,10 @@ export function createLocalShell(options) {
         if (!job || isTerminalStatus(job.info.status))
             return;
         const prev = job.info[channel] ?? "";
-        job.info = { ...job.info, [channel]: prev + chunk };
+        job.info = {
+            ...job.info,
+            [channel]: appendUtf8TailCap(prev, chunk, SUBPROCESS_CAPTURE_MAX_BYTES),
+        };
         scheduleOutputNotify();
     }
     function track(command, handle, ownerSessionId, id) {
@@ -235,6 +249,12 @@ export function createLocalShell(options) {
                     : {}),
                 stdout: r.stdout,
                 stderr: r.stderr,
+                ...(r.stdoutSpillPath !== undefined
+                    ? { stdoutSpillPath: r.stdoutSpillPath }
+                    : {}),
+                ...(r.stderrSpillPath !== undefined
+                    ? { stderrSpillPath: r.stderrSpillPath }
+                    : {}),
                 finishedAt: Date.now(),
             });
         })
@@ -278,6 +298,8 @@ export function createLocalShell(options) {
                 ...(spawnCwd ? { cwd: spawnCwd } : {}),
                 // Remaining budget lives on `deadline` — do not restart timeoutMs.
                 ...(deadline ? { signal: deadline } : {}),
+                // Opt-in spill under `{XRK_HOME}/spill` (readable); default off elsewhere.
+                ...(spillOpts !== undefined ? { spill: spillOpts } : { spill: false }),
                 onStdout: (chunk) => {
                     appendLiveOutput(id, "stdout", chunk);
                 },
@@ -413,6 +435,13 @@ export function createLocalShell(options) {
             }
             if (body.length === 0)
                 body = "(no output)";
+            const spills = [
+                job.info.stdoutSpillPath,
+                job.info.stderrSpillPath,
+            ].filter((p) => typeof p === "string" && p.length > 0);
+            if (spills.length > 0) {
+                body += `\n[some output was dropped from memory; full output: ${spills.join(", ")}]`;
+            }
             return body;
         },
         waitJob(id, timeoutMs, signal) {
@@ -531,7 +560,8 @@ export function createLocalShell(options) {
                 }
             }
             await Promise.all(all.map((j) => j.settled));
-            jobs.clear();
+            for (const id of [...jobs.keys()])
+                dropJob(id);
             notifyChanged();
         },
     };
@@ -851,7 +881,9 @@ export function createBashTools(shell, options = {}) {
         },
         {
             name: "job_output",
-            description: "Read a background job. Stream jobs return only output since the previous read. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`.",
+            description: "Read a background job. Stream jobs return only output since the previous read. " +
+                "Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`. " +
+                "If the body notes a spill file under product home, use read_file on that absolute path for the full log.",
             parameters: {
                 type: "object",
                 properties: {