@caupulican/pi-adaptative 0.80.99 → 0.80.102

package/dist/utils/safe-write-stream.d.ts

@@ -7,4 +7,12 @@ import { type WriteStream } from "node:fs";
  * an uncaught exception. Errors are reported through the optional callback instead.
  */
 export declare function createSafeWriteStream(path: string, onError?: (error: Error) => void): WriteStream;
+/**
+ * End a write stream and resolve only once its buffered data has been flushed and the file closed, so
+ * a subsequent read of the path sees the COMPLETE content. `stream.end()` alone is fire-and-forget:
+ * the flush runs asynchronously, so returning a temp-file path right after `.end()` lets a fast reader
+ * observe a partial (or empty) file. Resolves (never rejects) on "error" too — best-effort artifact
+ * writes must not hang or crash the caller; the caller drops the artifact on error separately.
+ */
+export declare function endWriteStream(stream: WriteStream): Promise<void>;
 //# sourceMappingURL=safe-write-stream.d.ts.map

package/dist/utils/safe-write-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safe-write-stream.d.ts","sourceRoot":"","sources":["../../src/utils/safe-write-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,WAAW,CAMjG","sourcesContent":["import { createWriteStream, type WriteStream } from \"node:fs\";\n\n/**\n * Create a WriteStream whose \"error\" event is always handled.\n *\n * Best-effort artifact writes (full-output temp files, overflow spills) must never\n * crash the host process: an fs.WriteStream \"error\" event with no listener becomes\n * an uncaught exception. Errors are reported through the optional callback instead.\n */\nexport function createSafeWriteStream(path: string, onError?: (error: Error) => void): WriteStream {\n\tconst stream = createWriteStream(path);\n\tstream.on(\"error\", (error: Error) => {\n\t\tonError?.(error);\n\t});\n\treturn stream;\n}\n"]}
+{"version":3,"file":"safe-write-stream.d.ts","sourceRoot":"","sources":["../../src/utils/safe-write-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAE9D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,WAAW,CAMjG;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBjE","sourcesContent":["import { createWriteStream, type WriteStream } from \"node:fs\";\n\n/**\n * Create a WriteStream whose \"error\" event is always handled.\n *\n * Best-effort artifact writes (full-output temp files, overflow spills) must never\n * crash the host process: an fs.WriteStream \"error\" event with no listener becomes\n * an uncaught exception. Errors are reported through the optional callback instead.\n */\nexport function createSafeWriteStream(path: string, onError?: (error: Error) => void): WriteStream {\n\tconst stream = createWriteStream(path);\n\tstream.on(\"error\", (error: Error) => {\n\t\tonError?.(error);\n\t});\n\treturn stream;\n}\n\n/**\n * End a write stream and resolve only once its buffered data has been flushed and the file closed, so\n * a subsequent read of the path sees the COMPLETE content. `stream.end()` alone is fire-and-forget:\n * the flush runs asynchronously, so returning a temp-file path right after `.end()` lets a fast reader\n * observe a partial (or empty) file. Resolves (never rejects) on \"error\" too — best-effort artifact\n * writes must not hang or crash the caller; the caller drops the artifact on error separately.\n */\nexport function endWriteStream(stream: WriteStream): Promise<void> {\n\treturn new Promise((resolve) => {\n\t\t// A stream that already reached a terminal state (finished, destroyed, closed, or\n\t\t// errored) before this call will never re-emit \"close\"/\"finish\"/\"error\": EventEmitter\n\t\t// does not replay past events, so listeners attached below would wait forever. Resolve\n\t\t// immediately instead of racing events that already happened.\n\t\tif (stream.writableFinished || stream.destroyed || stream.closed || stream.errored !== null) {\n\t\t\tresolve();\n\t\t\treturn;\n\t\t}\n\t\tlet settled = false;\n\t\tconst done = () => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tresolve();\n\t\t};\n\t\tstream.once(\"close\", done);\n\t\tstream.once(\"finish\", done);\n\t\tstream.once(\"error\", done);\n\t\tif (!stream.writableEnded) {\n\t\t\tstream.end();\n\t\t}\n\t});\n}\n"]}

package/dist/utils/safe-write-stream.js

@@ -13,4 +13,36 @@ export function createSafeWriteStream(path, onError) {
     });
     return stream;
 }
+/**
+ * End a write stream and resolve only once its buffered data has been flushed and the file closed, so
+ * a subsequent read of the path sees the COMPLETE content. `stream.end()` alone is fire-and-forget:
+ * the flush runs asynchronously, so returning a temp-file path right after `.end()` lets a fast reader
+ * observe a partial (or empty) file. Resolves (never rejects) on "error" too — best-effort artifact
+ * writes must not hang or crash the caller; the caller drops the artifact on error separately.
+ */
+export function endWriteStream(stream) {
+    return new Promise((resolve) => {
+        // A stream that already reached a terminal state (finished, destroyed, closed, or
+        // errored) before this call will never re-emit "close"/"finish"/"error": EventEmitter
+        // does not replay past events, so listeners attached below would wait forever. Resolve
+        // immediately instead of racing events that already happened.
+        if (stream.writableFinished || stream.destroyed || stream.closed || stream.errored !== null) {
+            resolve();
+            return;
+        }
+        let settled = false;
+        const done = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        };
+        stream.once("close", done);
+        stream.once("finish", done);
+        stream.once("error", done);
+        if (!stream.writableEnded) {
+            stream.end();
+        }
+    });
+}
 //# sourceMappingURL=safe-write-stream.js.map

package/dist/utils/safe-write-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe-write-stream.js","sourceRoot":"","sources":["../../src/utils/safe-write-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,OAAgC,EAAe;IAClG,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE,CAAC;QACpC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IAAA,CACjB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["import { createWriteStream, type WriteStream } from \"node:fs\";\n\n/**\n * Create a WriteStream whose \"error\" event is always handled.\n *\n * Best-effort artifact writes (full-output temp files, overflow spills) must never\n * crash the host process: an fs.WriteStream \"error\" event with no listener becomes\n * an uncaught exception. Errors are reported through the optional callback instead.\n */\nexport function createSafeWriteStream(path: string, onError?: (error: Error) => void): WriteStream {\n\tconst stream = createWriteStream(path);\n\tstream.on(\"error\", (error: Error) => {\n\t\tonError?.(error);\n\t});\n\treturn stream;\n}\n"]}
+{"version":3,"file":"safe-write-stream.js","sourceRoot":"","sources":["../../src/utils/safe-write-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,OAAgC,EAAe;IAClG,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE,CAAC;QACpC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IAAA,CACjB,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAAA,CACd;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAiB;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/B,kFAAkF;QAClF,sFAAsF;QACtF,uFAAuF;QACvF,8DAA8D;QAC9D,IAAI,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YAC7F,OAAO,EAAE,CAAC;YACV,OAAO;QACR,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC;YAClB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,CAAC;QAAA,CACV,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC3B,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAC5B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,EAAE,CAAC;QACd,CAAC;IAAA,CACD,CAAC,CAAC;AAAA,CACH","sourcesContent":["import { createWriteStream, type WriteStream } from \"node:fs\";\n\n/**\n * Create a WriteStream whose \"error\" event is always handled.\n *\n * Best-effort artifact writes (full-output temp files, overflow spills) must never\n * crash the host process: an fs.WriteStream \"error\" event with no listener becomes\n * an uncaught exception. Errors are reported through the optional callback instead.\n */\nexport function createSafeWriteStream(path: string, onError?: (error: Error) => void): WriteStream {\n\tconst stream = createWriteStream(path);\n\tstream.on(\"error\", (error: Error) => {\n\t\tonError?.(error);\n\t});\n\treturn stream;\n}\n\n/**\n * End a write stream and resolve only once its buffered data has been flushed and the file closed, so\n * a subsequent read of the path sees the COMPLETE content. `stream.end()` alone is fire-and-forget:\n * the flush runs asynchronously, so returning a temp-file path right after `.end()` lets a fast reader\n * observe a partial (or empty) file. Resolves (never rejects) on \"error\" too — best-effort artifact\n * writes must not hang or crash the caller; the caller drops the artifact on error separately.\n */\nexport function endWriteStream(stream: WriteStream): Promise<void> {\n\treturn new Promise((resolve) => {\n\t\t// A stream that already reached a terminal state (finished, destroyed, closed, or\n\t\t// errored) before this call will never re-emit \"close\"/\"finish\"/\"error\": EventEmitter\n\t\t// does not replay past events, so listeners attached below would wait forever. Resolve\n\t\t// immediately instead of racing events that already happened.\n\t\tif (stream.writableFinished || stream.destroyed || stream.closed || stream.errored !== null) {\n\t\t\tresolve();\n\t\t\treturn;\n\t\t}\n\t\tlet settled = false;\n\t\tconst done = () => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tresolve();\n\t\t};\n\t\tstream.once(\"close\", done);\n\t\tstream.once(\"finish\", done);\n\t\tstream.once(\"error\", done);\n\t\tif (!stream.writableEnded) {\n\t\t\tstream.end();\n\t\t}\n\t});\n}\n"]}

package/dist/utils/tools-manager.d.ts

@@ -1,5 +1,95 @@
+type ModuleRequire = ((id: string) => unknown) & {
+    resolve?: (id: string) => string;
+};
 export declare function getToolPath(tool: "fd" | "rg"): string | null;
-export declare function loadAvailableFffNodePackage(): unknown | undefined;
-export declare function ensureFffNodePackage(silent?: boolean, forceManagedInstall?: boolean): Promise<unknown | undefined>;
+/** Presence check for a SYSTEM tool the doctor only ever reports on -- never installs. */
+export interface SystemToolStatus {
+    present: boolean;
+    command?: string;
+    version?: string;
+}
+/**
+ * Detect a usable Python interpreter. SYSTEM tool (see src/core/doctor.ts):
+ * the doctor reports presence/version, it never installs this itself.
+ *
+ * @param commands Override the candidate command names, for tests.
+ */
+export declare function detectPython(commands?: readonly string[]): SystemToolStatus;
+/**
+ * Runs `<command> --version` (or `versionArgs`) and returns its trimmed
+ * combined stdout+stderr, or undefined if the command can't be run. Used by
+ * the doctor (src/core/doctor.ts) to show a version alongside a tool it has
+ * already located by some other means (e.g. getToolPath("rg"), or the binary
+ * path OllamaRuntime.detect() reports) -- callers that only need a yes/no
+ * presence check should use commandExists/getToolPath/detectPython instead.
+ */
+export declare function probeVersion(command: string, versionArgs?: readonly string[]): string | undefined;
+/**
+ * @param requires Override the resolution candidates, for tests (mirrors
+ * fff-search-backend.ts's loadFffModule(requires?)). Whether this resolves
+ * depends on the ambient environment -- @ff-labs/fff-node is a real npm
+ * dependency (package.json), so moduleRequire succeeds wherever a normal
+ * `npm install`/`npm ci` provisioned it (e.g. CI) even though it fails on a
+ * dev checkout that never ran that install here (this repo resolves fff-node
+ * via the separate managed-dir path instead). A test asserting "nothing is
+ * available" must pass `[]` here rather than relying on that being true.
+ */
+export declare function loadAvailableFffNodePackage(requires?: readonly ModuleRequire[]): unknown | undefined;
+/**
+ * Outcome of the most recent {@link ensureFffNodePackage} call, kept for
+ * observability (e.g. a future `doctor` check) since the function itself
+ * only ever returns the loaded module or `undefined` either way.
+ *
+ * `install-failed` is distinguished from `offline`/`unsupported-platform`
+ * because it is the only one worth *retrying*: offline mode and an
+ * unsupported platform are stable for the life of the process, but a real
+ * install attempt can fail on a transient issue (registry hiccup, timeout)
+ * that may no longer apply on the next search. See
+ * DefaultFffSearchBackend.getFinder in fff-search-backend.ts, which uses
+ * this distinction to decide whether a failed finder is retryable.
+ */
+export type FffInstallOutcome = {
+    status: "already-available";
+} | {
+    status: "offline";
+} | {
+    status: "unsupported-platform";
+} | {
+    status: "installed";
+} | {
+    status: "install-failed";
+    reason: string;
+};
+/**
+ * How long a genuine install failure gates out a NEW npm spawn. An agent turn
+ * can fire several find/grep calls in quick succession, and each one now
+ * primes the finder in the background (see tryFffFind/tryFffGrep) -- without
+ * this, a persistently-failing install (registry down, disk full, ...) would
+ * re-spawn npm on every single one of those calls instead of once.
+ *
+ * This gates the SPAWN inside ensureFffNodePackage, not whether a failed
+ * finder is retryable (see isFffInstallRetryable): DefaultFffSearchBackend
+ * always evicts a failed finder so the next search re-enters this function,
+ * and it is THIS cooldown check -- evaluated fresh, at call time -- that
+ * decides whether that re-entry is a real attempt or a fast, spawn-free bail.
+ * (An earlier version conflated the two: it gated eviction itself on the
+ * cooldown, which is checked once, immediately after the failure it's timing
+ * -- i.e. always still within the window -- so the failed finder was never
+ * evicted and the retry never got a chance to happen at all.)
+ */
+export declare const FFF_INSTALL_RETRY_COOLDOWN_MS = 30000;
+/** The outcome of the last {@link ensureFffNodePackage} call, if any. */
+export declare function getLastFffInstallOutcome(): FffInstallOutcome | undefined;
+/** Whether the last install outcome was a genuine failure worth retrying (as opposed to a stable "not applicable" result). Cooldown-independent by design -- see FFF_INSTALL_RETRY_COOLDOWN_MS. */
+export declare function isFffInstallRetryable(): boolean;
+/**
+ * Pure decision logic behind {@link isFffInstallCoolingDown}, exposed directly
+ * so tests can assert the cooldown boundary without faking the system clock.
+ */
+export declare function computeIsFffInstallCoolingDown(outcome: FffInstallOutcome | undefined, failedAt: number | undefined, now: number): boolean;
+export declare function ensureFffNodePackage(silent?: boolean, forceManagedInstall?: boolean, 
+/** Override the "is it already available" resolution candidates, for tests. See loadAvailableFffNodePackage's doc. */
+requires?: readonly ModuleRequire[]): Promise<unknown | undefined>;
 export declare function ensureTool(tool: "fd" | "rg", silent?: boolean): Promise<string | undefined>;
+export {};
 //# sourceMappingURL=tools-manager.d.ts.map

package/dist/utils/tools-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools-manager.d.ts","sourceRoot":"","sources":["../../src/utils/tools-manager.ts"],"names":[],"mappings":"AAwGA,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAmB5D;AAgSD,wBAAgB,2BAA2B,IAAI,OAAO,GAAG,SAAS,CAQjE;AAuDD,wBAAsB,oBAAoB,CACzC,MAAM,GAAE,OAAe,EACvB,mBAAmB,GAAE,OAAe,GAClC,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAuB9B;AAID,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA2CxG","sourcesContent":["import chalk from \"chalk\";\nimport { type SpawnSyncReturns, spawnSync } from \"child_process\";\nimport {\n\tchmodSync,\n\tcreateWriteStream,\n\texistsSync,\n\tmkdirSync,\n\treaddirSync,\n\trenameSync,\n\trmSync,\n\twriteFileSync,\n} from \"fs\";\nimport { createRequire } from \"module\";\nimport { arch, platform } from \"os\";\nimport { dirname, join } from \"path\";\nimport { Readable } from \"stream\";\nimport { pipeline } from \"stream/promises\";\nimport { pathToFileURL } from \"url\";\nimport { APP_NAME, getBinDir } from \"../config.ts\";\nimport { spawnProcess, waitForChildProcess } from \"./child-process.ts\";\n\nconst TOOLS_DIR = getBinDir();\nconst NETWORK_TIMEOUT_MS = 10_000;\nconst DOWNLOAD_TIMEOUT_MS = 120_000;\nconst FFF_NODE_VERSION = \"0.9.6\";\nconst FFF_MANAGED_DIR = join(TOOLS_DIR, \"fff-node\");\nconst FFF_MANAGED_PACKAGE_JSON = join(FFF_MANAGED_DIR, \"package.json\");\n\ntype ModuleRequire = ((id: string) => unknown) & { resolve?: (id: string) => string };\n\nconst moduleRequire = createRequire(import.meta.url);\nconst executableDirRequire = createRequire(pathToFileURL(join(dirname(process.execPath), \"package.json\")).href);\n\nfunction isOfflineModeEnabled(): boolean {\n\tconst value = process.env.PI_OFFLINE;\n\tif (!value) return false;\n\treturn value === \"1\" || value.toLowerCase() === \"true\" || value.toLowerCase() === \"yes\";\n}\n\ninterface ToolConfig {\n\tname: string;\n\trepo: string; // GitHub repo (e.g., \"sharkdp/fd\")\n\tbinaryName: string; // Name of the binary inside the archive\n\tsystemBinaryNames?: string[]; // Alternative system command names to try before downloading\n\ttagPrefix: string; // Prefix for tags (e.g., \"v\" for v1.0.0, \"\" for 1.0.0)\n\tgetAssetName: (version: string, plat: string, architecture: string) => string | null;\n}\n\nconst TOOLS: Record<string, ToolConfig> = {\n\tfd: {\n\t\tname: \"fd\",\n\t\trepo: \"sharkdp/fd\",\n\t\tbinaryName: \"fd\",\n\t\tsystemBinaryNames: [\"fd\", \"fdfind\"],\n\t\ttagPrefix: \"v\",\n\t\tgetAssetName: (version, plat, architecture) => {\n\t\t\tif (plat === \"darwin\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `fd-v${version}-${archStr}-apple-darwin.tar.gz`;\n\t\t\t} else if (plat === \"linux\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `fd-v${version}-${archStr}-unknown-linux-gnu.tar.gz`;\n\t\t\t} else if (plat === \"win32\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `fd-v${version}-${archStr}-pc-windows-msvc.zip`;\n\t\t\t}\n\t\t\treturn null;\n\t\t},\n\t},\n\trg: {\n\t\tname: \"ripgrep\",\n\t\trepo: \"BurntSushi/ripgrep\",\n\t\tbinaryName: \"rg\",\n\t\ttagPrefix: \"\",\n\t\tgetAssetName: (version, plat, architecture) => {\n\t\t\tif (plat === \"darwin\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `ripgrep-${version}-${archStr}-apple-darwin.tar.gz`;\n\t\t\t} else if (plat === \"linux\") {\n\t\t\t\tif (architecture === \"arm64\") {\n\t\t\t\t\treturn `ripgrep-${version}-aarch64-unknown-linux-gnu.tar.gz`;\n\t\t\t\t}\n\t\t\t\treturn `ripgrep-${version}-x86_64-unknown-linux-musl.tar.gz`;\n\t\t\t} else if (plat === \"win32\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `ripgrep-${version}-${archStr}-pc-windows-msvc.zip`;\n\t\t\t}\n\t\t\treturn null;\n\t\t},\n\t},\n};\n\n// Check if a command exists in PATH by trying to run it\nfunction commandExists(cmd: string): boolean {\n\ttry {\n\t\tconst result = spawnSync(cmd, [\"--version\"], { stdio: \"pipe\" });\n\t\t// Check for ENOENT error (command not found)\n\t\treturn result.error === undefined || result.error === null;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n// Get the path to a tool (system-wide or in our tools dir)\nexport function getToolPath(tool: \"fd\" | \"rg\"): string | null {\n\tconst config = TOOLS[tool];\n\tif (!config) return null;\n\n\t// Check our tools directory first\n\tconst localPath = join(TOOLS_DIR, config.binaryName + (platform() === \"win32\" ? \".exe\" : \"\"));\n\tif (existsSync(localPath)) {\n\t\treturn localPath;\n\t}\n\n\t// Check system PATH - if found, just return the command name (it's in PATH)\n\tconst systemBinaryNames = config.systemBinaryNames ?? [config.binaryName];\n\tfor (const systemBinaryName of systemBinaryNames) {\n\t\tif (commandExists(systemBinaryName)) {\n\t\t\treturn systemBinaryName;\n\t\t}\n\t}\n\n\treturn null;\n}\n\n// Fetch latest release version from GitHub\nasync function getLatestVersion(repo: string): Promise<string> {\n\tconst response = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {\n\t\theaders: { \"User-Agent\": `${APP_NAME}-coding-agent` },\n\t\tsignal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),\n\t});\n\n\tif (!response.ok) {\n\t\tthrow new Error(`GitHub API error: ${response.status}`);\n\t}\n\n\tconst data = (await response.json()) as { tag_name: string };\n\treturn data.tag_name.replace(/^v/, \"\");\n}\n\n// Download a file from URL\nasync function downloadFile(url: string, dest: string): Promise<void> {\n\tconst response = await fetch(url, {\n\t\tsignal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),\n\t});\n\n\tif (!response.ok) {\n\t\tthrow new Error(`Failed to download: ${response.status}`);\n\t}\n\n\tif (!response.body) {\n\t\tthrow new Error(\"No response body\");\n\t}\n\n\tconst fileStream = createWriteStream(dest);\n\tawait pipeline(Readable.fromWeb(response.body as any), fileStream);\n}\n\nfunction findBinaryRecursively(rootDir: string, binaryFileName: string): string | null {\n\tconst stack: string[] = [rootDir];\n\n\twhile (stack.length > 0) {\n\t\tconst currentDir = stack.pop();\n\t\tif (!currentDir) continue;\n\n\t\tconst entries = readdirSync(currentDir, { withFileTypes: true });\n\t\tfor (const entry of entries) {\n\t\t\tconst fullPath = join(currentDir, entry.name);\n\t\t\tif (entry.isFile() && entry.name === binaryFileName) {\n\t\t\t\treturn fullPath;\n\t\t\t}\n\t\t\tif (entry.isDirectory()) {\n\t\t\t\tstack.push(fullPath);\n\t\t\t}\n\t\t}\n\t}\n\n\treturn null;\n}\n\nfunction formatSpawnFailure(result: SpawnSyncReturns<Buffer>): string {\n\tif (result.error?.message) {\n\t\treturn result.error.message;\n\t}\n\tconst stderr = result.stderr?.toString().trim();\n\tif (stderr) {\n\t\treturn stderr;\n\t}\n\tconst stdout = result.stdout?.toString().trim();\n\tif (stdout) {\n\t\treturn stdout;\n\t}\n\treturn `exit status ${result.status ?? \"unknown\"}`;\n}\n\nfunction runExtractionCommand(command: string, args: string[]): string | null {\n\tconst result = spawnSync(command, args, { stdio: \"pipe\" });\n\tif (!result.error && result.status === 0) {\n\t\treturn null;\n\t}\n\treturn `${command}: ${formatSpawnFailure(result)}`;\n}\n\nfunction extractTarGzArchive(archivePath: string, extractDir: string, assetName: string): void {\n\tconst failure = runExtractionCommand(\"tar\", [\"xzf\", archivePath, \"-C\", extractDir]);\n\tif (failure) {\n\t\tthrow new Error(`Failed to extract ${assetName}: ${failure}`);\n\t}\n}\n\nfunction getWindowsTarCommand(): string {\n\tconst systemRoot = process.env.SystemRoot ?? process.env.WINDIR;\n\tif (systemRoot) {\n\t\tconst systemTar = join(systemRoot, \"System32\", \"tar.exe\");\n\t\tif (existsSync(systemTar)) {\n\t\t\treturn systemTar;\n\t\t}\n\t}\n\treturn \"tar.exe\";\n}\n\nfunction extractZipArchive(archivePath: string, extractDir: string, assetName: string): void {\n\tconst failures: string[] = [];\n\n\tif (platform() === \"win32\") {\n\t\t// Windows ships bsdtar as tar.exe, which supports zip files. Prefer the\n\t\t// System32 binary over Git Bash's GNU tar, which does not handle zip archives.\n\t\tconst tarFailure = runExtractionCommand(getWindowsTarCommand(), [\"xf\", archivePath, \"-C\", extractDir]);\n\t\tif (!tarFailure) return;\n\t\tfailures.push(tarFailure);\n\n\t\tconst script =\n\t\t\t\"& { param($archive, $destination) $ErrorActionPreference = 'Stop'; Expand-Archive -LiteralPath $archive -DestinationPath $destination -Force }\";\n\t\tconst powershellFailure = runExtractionCommand(\"powershell.exe\", [\n\t\t\t\"-NoLogo\",\n\t\t\t\"-NoProfile\",\n\t\t\t\"-NonInteractive\",\n\t\t\t\"-ExecutionPolicy\",\n\t\t\t\"Bypass\",\n\t\t\t\"-Command\",\n\t\t\tscript,\n\t\t\tarchivePath,\n\t\t\textractDir,\n\t\t]);\n\t\tif (!powershellFailure) return;\n\t\tfailures.push(powershellFailure);\n\t} else {\n\t\tconst unzipFailure = runExtractionCommand(\"unzip\", [\"-q\", archivePath, \"-d\", extractDir]);\n\t\tif (!unzipFailure) return;\n\t\tfailures.push(unzipFailure);\n\n\t\tconst tarFailure = runExtractionCommand(\"tar\", [\"xf\", archivePath, \"-C\", extractDir]);\n\t\tif (!tarFailure) return;\n\t\tfailures.push(tarFailure);\n\t}\n\n\tthrow new Error(`Failed to extract ${assetName}: ${failures.join(\"; \")}`);\n}\n\n// Download and install a tool\nasync function downloadTool(tool: \"fd\" | \"rg\"): Promise<string> {\n\tconst config = TOOLS[tool];\n\tif (!config) throw new Error(`Unknown tool: ${tool}`);\n\n\tconst plat = platform();\n\tconst architecture = arch();\n\n\t// Get latest version\n\tlet version = await getLatestVersion(config.repo);\n\tif (tool === \"fd\" && plat === \"darwin\" && architecture === \"x64\") {\n\t\tversion = \"10.3.0\";\n\t}\n\n\t// Get asset name for this platform\n\tconst assetName = config.getAssetName(version, plat, architecture);\n\tif (!assetName) {\n\t\tthrow new Error(`Unsupported platform: ${plat}/${architecture}`);\n\t}\n\n\t// Create tools directory\n\tmkdirSync(TOOLS_DIR, { recursive: true });\n\n\tconst downloadUrl = `https://github.com/${config.repo}/releases/download/${config.tagPrefix}${version}/${assetName}`;\n\tconst archivePath = join(TOOLS_DIR, assetName);\n\tconst binaryExt = plat === \"win32\" ? \".exe\" : \"\";\n\tconst binaryPath = join(TOOLS_DIR, config.binaryName + binaryExt);\n\n\t// Download\n\tawait downloadFile(downloadUrl, archivePath);\n\n\t// Extract into a unique temp directory. fd and rg downloads can run concurrently\n\t// during startup, so sharing a fixed directory causes races.\n\tconst extractDir = join(\n\t\tTOOLS_DIR,\n\t\t`extract_tmp_${config.binaryName}_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,\n\t);\n\tmkdirSync(extractDir, { recursive: true });\n\n\ttry {\n\t\tif (assetName.endsWith(\".tar.gz\")) {\n\t\t\textractTarGzArchive(archivePath, extractDir, assetName);\n\t\t} else if (assetName.endsWith(\".zip\")) {\n\t\t\textractZipArchive(archivePath, extractDir, assetName);\n\t\t} else {\n\t\t\tthrow new Error(`Unsupported archive format: ${assetName}`);\n\t\t}\n\n\t\t// Find the binary in extracted files. Some archives contain files directly\n\t\t// at root, others nest under a versioned subdirectory.\n\t\tconst binaryFileName = config.binaryName + binaryExt;\n\t\tconst extractedDir = join(extractDir, assetName.replace(/\\.(tar\\.gz|zip)$/, \"\"));\n\t\tconst extractedBinaryCandidates = [join(extractedDir, binaryFileName), join(extractDir, binaryFileName)];\n\t\tlet extractedBinary = extractedBinaryCandidates.find((candidate) => existsSync(candidate));\n\n\t\tif (!extractedBinary) {\n\t\t\textractedBinary = findBinaryRecursively(extractDir, binaryFileName) ?? undefined;\n\t\t}\n\n\t\tif (extractedBinary) {\n\t\t\trenameSync(extractedBinary, binaryPath);\n\t\t} else {\n\t\t\tthrow new Error(`Binary not found in archive: expected ${binaryFileName} under ${extractDir}`);\n\t\t}\n\n\t\t// Make executable (Unix only)\n\t\tif (plat !== \"win32\") {\n\t\t\tchmodSync(binaryPath, 0o755);\n\t\t}\n\t} finally {\n\t\t// Cleanup\n\t\trmSync(archivePath, { force: true });\n\t\trmSync(extractDir, { recursive: true, force: true });\n\t}\n\n\treturn binaryPath;\n}\n\n// Termux package names for tools\nconst TERMUX_PACKAGES: Record<string, string> = {\n\tfd: \"fd\",\n\trg: \"ripgrep\",\n};\n\nconst FFF_PLATFORM_PACKAGES: Record<string, string> = {\n\t\"darwin/arm64\": \"@ff-labs/fff-bin-darwin-arm64\",\n\t\"darwin/x64\": \"@ff-labs/fff-bin-darwin-x64\",\n\t\"linux/arm64/glibc\": \"@ff-labs/fff-bin-linux-arm64-gnu\",\n\t\"linux/arm64/musl\": \"@ff-labs/fff-bin-linux-arm64-musl\",\n\t\"linux/x64/glibc\": \"@ff-labs/fff-bin-linux-x64-gnu\",\n\t\"linux/x64/musl\": \"@ff-labs/fff-bin-linux-x64-musl\",\n\t\"win32/arm64\": \"@ff-labs/fff-bin-win32-arm64\",\n\t\"win32/x64\": \"@ff-labs/fff-bin-win32-x64\",\n};\n\nlet fffNodeInstallPromise: Promise<unknown | undefined> | undefined;\n\nfunction detectLinuxLibc(): \"glibc\" | \"musl\" {\n\tlet output = \"\";\n\ttry {\n\t\tconst result = spawnSync(\"ldd\", [\"--version\"], { encoding: \"utf-8\", stdio: \"pipe\", timeout: 5000 });\n\t\toutput = `${result.stdout ?? \"\"}${result.stderr ?? \"\"}`;\n\t} catch (e: unknown) {\n\t\tconst err = e as { stdout?: string | Buffer; stderr?: string | Buffer };\n\t\toutput = `${String(err.stdout ?? \"\")}${String(err.stderr ?? \"\")}`;\n\t}\n\treturn output.toLowerCase().includes(\"musl\") ? \"musl\" : \"glibc\";\n}\n\nfunction getFffPlatformPackageName(): string | undefined {\n\tconst plat = platform();\n\tconst architecture = arch();\n\tif (plat === \"linux\") {\n\t\treturn FFF_PLATFORM_PACKAGES[`${plat}/${architecture}/${detectLinuxLibc()}`];\n\t}\n\treturn FFF_PLATFORM_PACKAGES[`${plat}/${architecture}`];\n}\n\nfunction createManagedFffRequire(): ModuleRequire | undefined {\n\tif (!existsSync(FFF_MANAGED_PACKAGE_JSON)) return undefined;\n\treturn createRequire(pathToFileURL(FFF_MANAGED_PACKAGE_JSON).href);\n}\n\nfunction findFffNodeDistEntry(startPath: string): string | undefined {\n\tlet currentDir = dirname(startPath);\n\twhile (currentDir !== dirname(currentDir)) {\n\t\tconst candidate = join(currentDir, \"node_modules\", \"@ff-labs\", \"fff-node\", \"dist\", \"src\", \"index.js\");\n\t\tif (existsSync(candidate)) return candidate;\n\t\tcurrentDir = dirname(currentDir);\n\t}\n\treturn undefined;\n}\n\nfunction loadFffNodeDistEntry(requireFff: ModuleRequire): unknown | undefined {\n\tif (!requireFff.resolve) return undefined;\n\ttry {\n\t\tconst ffiPath = requireFff.resolve(\"ffi-rs\");\n\t\tconst fffEntry = findFffNodeDistEntry(ffiPath);\n\t\treturn fffEntry ? requireFff(fffEntry) : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction loadFffNodeWith(requireFff: ModuleRequire): unknown | undefined {\n\ttry {\n\t\treturn requireFff(\"@ff-labs/fff-node\");\n\t} catch {\n\t\treturn loadFffNodeDistEntry(requireFff);\n\t}\n}\n\nexport function loadAvailableFffNodePackage(): unknown | undefined {\n\tfor (const requireFff of [moduleRequire, executableDirRequire, createManagedFffRequire()].filter(\n\t\t(candidate): candidate is ModuleRequire => Boolean(candidate),\n\t)) {\n\t\tconst loaded = loadFffNodeWith(requireFff);\n\t\tif (loaded) return loaded;\n\t}\n\treturn undefined;\n}\n\nasync function runNpmInstall(args: string[]): Promise<{ code: number | null; stderr: string }> {\n\ttry {\n\t\tconst child = spawnProcess(\"npm\", args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\tlet stderr = \"\";\n\t\tchild.stderr?.on(\"data\", (chunk) => {\n\t\t\tstderr += chunk.toString();\n\t\t});\n\t\tconst code = await waitForChildProcess(child);\n\t\treturn { code, stderr };\n\t} catch (error) {\n\t\treturn { code: 1, stderr: error instanceof Error ? error.message : String(error) };\n\t}\n}\n\nasync function installManagedFffNodePackage(platformPackage: string, silent: boolean): Promise<unknown | undefined> {\n\tmkdirSync(FFF_MANAGED_DIR, { recursive: true });\n\tif (!existsSync(FFF_MANAGED_PACKAGE_JSON)) {\n\t\twriteFileSync(FFF_MANAGED_PACKAGE_JSON, '{\"name\":\"pi-managed-fff-node\",\"private\":true,\"version\":\"0.0.0\"}\\n');\n\t}\n\n\tif (!silent) {\n\t\tconsole.log(chalk.dim(\"FFF native search not found. Installing managed FFF package...\"));\n\t}\n\n\tconst args = [\n\t\t\"install\",\n\t\t\"--ignore-scripts\",\n\t\t\"--omit=dev\",\n\t\t\"--include=optional\",\n\t\t\"--no-audit\",\n\t\t\"--no-fund\",\n\t\t\"--package-lock=false\",\n\t\t\"--prefix\",\n\t\tFFF_MANAGED_DIR,\n\t\t`@ff-labs/fff-node@${FFF_NODE_VERSION}`,\n\t\t`${platformPackage}@${FFF_NODE_VERSION}`,\n\t];\n\tconst result = await runNpmInstall(args);\n\tif (result.code !== 0) {\n\t\tif (!silent) {\n\t\t\tconsole.log(\n\t\t\t\tchalk.yellow(`Failed to install FFF native search: ${result.stderr.trim() || `exit code ${result.code}`}`),\n\t\t\t);\n\t\t}\n\t\treturn undefined;\n\t}\n\tconst loaded = loadFffNodeWith(createRequire(pathToFileURL(FFF_MANAGED_PACKAGE_JSON).href));\n\tif (!loaded && !silent) {\n\t\tconsole.log(chalk.yellow(\"Managed FFF install completed but @ff-labs/fff-node could not be loaded.\"));\n\t}\n\treturn loaded;\n}\n\nexport async function ensureFffNodePackage(\n\tsilent: boolean = false,\n\tforceManagedInstall: boolean = false,\n): Promise<unknown | undefined> {\n\tconst existing = forceManagedInstall ? undefined : loadAvailableFffNodePackage();\n\tif (existing) return existing;\n\n\tif (isOfflineModeEnabled()) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(\"FFF native search not found. Offline mode enabled, skipping install.\"));\n\t\t}\n\t\treturn undefined;\n\t}\n\n\tconst platformPackage = getFffPlatformPackageName();\n\tif (!platformPackage) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`FFF native search is not available for ${platform()}/${arch()}.`));\n\t\t}\n\t\treturn undefined;\n\t}\n\n\tfffNodeInstallPromise ??= installManagedFffNodePackage(platformPackage, silent).finally(() => {\n\t\tfffNodeInstallPromise = undefined;\n\t});\n\treturn fffNodeInstallPromise;\n}\n\n// Ensure a tool is available, downloading if necessary\n// Returns the path to the tool, or null if unavailable\nexport async function ensureTool(tool: \"fd\" | \"rg\", silent: boolean = false): Promise<string | undefined> {\n\tconst existingPath = getToolPath(tool);\n\tif (existingPath) {\n\t\treturn existingPath;\n\t}\n\n\tconst config = TOOLS[tool];\n\tif (!config) return undefined;\n\n\tif (isOfflineModeEnabled()) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`${config.name} not found. Offline mode enabled, skipping download.`));\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// On Android/Termux, Linux binaries don't work due to Bionic libc incompatibility.\n\t// Users must install via pkg.\n\tif (platform() === \"android\") {\n\t\tconst pkgName = TERMUX_PACKAGES[tool] ?? tool;\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`${config.name} not found. Install with: pkg install ${pkgName}`));\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// Tool not found - download it\n\tif (!silent) {\n\t\tconsole.log(chalk.dim(`${config.name} not found. Downloading...`));\n\t}\n\n\ttry {\n\t\tconst path = await downloadTool(tool);\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.dim(`${config.name} installed to ${path}`));\n\t\t}\n\t\treturn path;\n\t} catch (e) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`Failed to download ${config.name}: ${e instanceof Error ? e.message : e}`));\n\t\t}\n\t\treturn undefined;\n\t}\n}\n"]}
+{"version":3,"file":"tools-manager.d.ts","sourceRoot":"","sources":["../../src/utils/tools-manager.ts"],"names":[],"mappings":"AA4BA,KAAK,aAAa,GAAG,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAA;CAAE,CAAC;AA4EtF,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAmB5D;AAED,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,GAAE,SAAS,MAAM,EAAoB,GAAG,gBAAgB,CAe5F;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,GAAE,SAAS,MAAM,EAAkB,GAAG,MAAM,GAAG,SAAS,CAShH;AAgSD;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,GAAG,SAAS,CAWpG;AAgBD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GAC1B;IAAE,MAAM,EAAE,mBAAmB,CAAA;CAAE,GAC/B;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,sBAAsB,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAKpD,yEAAyE;AACzE,wBAAgB,wBAAwB,IAAI,iBAAiB,GAAG,SAAS,CAExE;AAED,mMAAmM;AACnM,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,MAAM,GACT,OAAO,CAIT;AAsED,wBAAsB,oBAAoB,CACzC,MAAM,GAAE,OAAe,EACvB,mBAAmB,GAAE,OAAe;AACpC,sHAAsH;AACtH,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,GACjC,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAoC9B;AAID,wBAAsB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,GAAE,OAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA2CxG","sourcesContent":["import chalk from \"chalk\";\nimport { type SpawnSyncReturns, spawnSync } from \"child_process\";\nimport {\n\tchmodSync,\n\tcreateWriteStream,\n\texistsSync,\n\tmkdirSync,\n\treaddirSync,\n\trenameSync,\n\trmSync,\n\twriteFileSync,\n} from \"fs\";\nimport { createRequire } from \"module\";\nimport { arch, platform } from \"os\";\nimport { dirname, join } from \"path\";\nimport { Readable } from \"stream\";\nimport { pipeline } from \"stream/promises\";\nimport { pathToFileURL } from \"url\";\nimport { APP_NAME, getBinDir } from \"../config.ts\";\nimport { spawnProcess, waitForChildProcess } from \"./child-process.ts\";\n\nconst TOOLS_DIR = getBinDir();\nconst NETWORK_TIMEOUT_MS = 10_000;\nconst DOWNLOAD_TIMEOUT_MS = 120_000;\nconst FFF_NODE_VERSION = \"0.9.6\";\nconst FFF_MANAGED_DIR = join(TOOLS_DIR, \"fff-node\");\nconst FFF_MANAGED_PACKAGE_JSON = join(FFF_MANAGED_DIR, \"package.json\");\n\ntype ModuleRequire = ((id: string) => unknown) & { resolve?: (id: string) => string };\n\nconst moduleRequire = createRequire(import.meta.url);\nconst executableDirRequire = createRequire(pathToFileURL(join(dirname(process.execPath), \"package.json\")).href);\n\nfunction isOfflineModeEnabled(): boolean {\n\tconst value = process.env.PI_OFFLINE;\n\tif (!value) return false;\n\treturn value === \"1\" || value.toLowerCase() === \"true\" || value.toLowerCase() === \"yes\";\n}\n\ninterface ToolConfig {\n\tname: string;\n\trepo: string; // GitHub repo (e.g., \"sharkdp/fd\")\n\tbinaryName: string; // Name of the binary inside the archive\n\tsystemBinaryNames?: string[]; // Alternative system command names to try before downloading\n\ttagPrefix: string; // Prefix for tags (e.g., \"v\" for v1.0.0, \"\" for 1.0.0)\n\tgetAssetName: (version: string, plat: string, architecture: string) => string | null;\n}\n\nconst TOOLS: Record<string, ToolConfig> = {\n\tfd: {\n\t\tname: \"fd\",\n\t\trepo: \"sharkdp/fd\",\n\t\tbinaryName: \"fd\",\n\t\tsystemBinaryNames: [\"fd\", \"fdfind\"],\n\t\ttagPrefix: \"v\",\n\t\tgetAssetName: (version, plat, architecture) => {\n\t\t\tif (plat === \"darwin\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `fd-v${version}-${archStr}-apple-darwin.tar.gz`;\n\t\t\t} else if (plat === \"linux\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `fd-v${version}-${archStr}-unknown-linux-gnu.tar.gz`;\n\t\t\t} else if (plat === \"win32\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `fd-v${version}-${archStr}-pc-windows-msvc.zip`;\n\t\t\t}\n\t\t\treturn null;\n\t\t},\n\t},\n\trg: {\n\t\tname: \"ripgrep\",\n\t\trepo: \"BurntSushi/ripgrep\",\n\t\tbinaryName: \"rg\",\n\t\ttagPrefix: \"\",\n\t\tgetAssetName: (version, plat, architecture) => {\n\t\t\tif (plat === \"darwin\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `ripgrep-${version}-${archStr}-apple-darwin.tar.gz`;\n\t\t\t} else if (plat === \"linux\") {\n\t\t\t\tif (architecture === \"arm64\") {\n\t\t\t\t\treturn `ripgrep-${version}-aarch64-unknown-linux-gnu.tar.gz`;\n\t\t\t\t}\n\t\t\t\treturn `ripgrep-${version}-x86_64-unknown-linux-musl.tar.gz`;\n\t\t\t} else if (plat === \"win32\") {\n\t\t\t\tconst archStr = architecture === \"arm64\" ? \"aarch64\" : \"x86_64\";\n\t\t\t\treturn `ripgrep-${version}-${archStr}-pc-windows-msvc.zip`;\n\t\t\t}\n\t\t\treturn null;\n\t\t},\n\t},\n};\n\n// Check if a command exists in PATH by trying to run it\nfunction commandExists(cmd: string): boolean {\n\ttry {\n\t\tconst result = spawnSync(cmd, [\"--version\"], { stdio: \"pipe\" });\n\t\t// Check for ENOENT error (command not found)\n\t\treturn result.error === undefined || result.error === null;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n// Get the path to a tool (system-wide or in our tools dir)\nexport function getToolPath(tool: \"fd\" | \"rg\"): string | null {\n\tconst config = TOOLS[tool];\n\tif (!config) return null;\n\n\t// Check our tools directory first\n\tconst localPath = join(TOOLS_DIR, config.binaryName + (platform() === \"win32\" ? \".exe\" : \"\"));\n\tif (existsSync(localPath)) {\n\t\treturn localPath;\n\t}\n\n\t// Check system PATH - if found, just return the command name (it's in PATH)\n\tconst systemBinaryNames = config.systemBinaryNames ?? [config.binaryName];\n\tfor (const systemBinaryName of systemBinaryNames) {\n\t\tif (commandExists(systemBinaryName)) {\n\t\t\treturn systemBinaryName;\n\t\t}\n\t}\n\n\treturn null;\n}\n\n/** Presence check for a SYSTEM tool the doctor only ever reports on -- never installs. */\nexport interface SystemToolStatus {\n\tpresent: boolean;\n\tcommand?: string;\n\tversion?: string;\n}\n\nconst PYTHON_COMMANDS = [\"python3\", \"python\"];\n\n/**\n * Detect a usable Python interpreter. SYSTEM tool (see src/core/doctor.ts):\n * the doctor reports presence/version, it never installs this itself.\n *\n * @param commands Override the candidate command names, for tests.\n */\nexport function detectPython(commands: readonly string[] = PYTHON_COMMANDS): SystemToolStatus {\n\tfor (const command of commands) {\n\t\ttry {\n\t\t\tconst result = spawnSync(command, [\"--version\"], { encoding: \"utf-8\", stdio: \"pipe\", timeout: 5_000 });\n\t\t\tif (result.error) continue;\n\t\t\t// Python 2 prints its version to stderr; Python 3 prints to stdout. Some\n\t\t\t// platforms' `python` alias is one or the other, so check both.\n\t\t\tconst version = `${result.stdout ?? \"\"}${result.stderr ?? \"\"}`.trim() || undefined;\n\t\t\tif (result.status !== 0 && !version) continue;\n\t\t\treturn { present: true, command, version };\n\t\t} catch {\n\t\t\t// Try the next candidate.\n\t\t}\n\t}\n\treturn { present: false };\n}\n\n/**\n * Runs `<command> --version` (or `versionArgs`) and returns its trimmed\n * combined stdout+stderr, or undefined if the command can't be run. Used by\n * the doctor (src/core/doctor.ts) to show a version alongside a tool it has\n * already located by some other means (e.g. getToolPath(\"rg\"), or the binary\n * path OllamaRuntime.detect() reports) -- callers that only need a yes/no\n * presence check should use commandExists/getToolPath/detectPython instead.\n */\nexport function probeVersion(command: string, versionArgs: readonly string[] = [\"--version\"]): string | undefined {\n\ttry {\n\t\tconst result = spawnSync(command, versionArgs, { encoding: \"utf-8\", stdio: \"pipe\", timeout: 5_000 });\n\t\tif (result.error) return undefined;\n\t\tconst output = `${result.stdout ?? \"\"}${result.stderr ?? \"\"}`.trim();\n\t\treturn output || undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n// Fetch latest release version from GitHub\nasync function getLatestVersion(repo: string): Promise<string> {\n\tconst response = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {\n\t\theaders: { \"User-Agent\": `${APP_NAME}-coding-agent` },\n\t\tsignal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),\n\t});\n\n\tif (!response.ok) {\n\t\tthrow new Error(`GitHub API error: ${response.status}`);\n\t}\n\n\tconst data = (await response.json()) as { tag_name: string };\n\treturn data.tag_name.replace(/^v/, \"\");\n}\n\n// Download a file from URL\nasync function downloadFile(url: string, dest: string): Promise<void> {\n\tconst response = await fetch(url, {\n\t\tsignal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),\n\t});\n\n\tif (!response.ok) {\n\t\tthrow new Error(`Failed to download: ${response.status}`);\n\t}\n\n\tif (!response.body) {\n\t\tthrow new Error(\"No response body\");\n\t}\n\n\tconst fileStream = createWriteStream(dest);\n\tawait pipeline(Readable.fromWeb(response.body as any), fileStream);\n}\n\nfunction findBinaryRecursively(rootDir: string, binaryFileName: string): string | null {\n\tconst stack: string[] = [rootDir];\n\n\twhile (stack.length > 0) {\n\t\tconst currentDir = stack.pop();\n\t\tif (!currentDir) continue;\n\n\t\tconst entries = readdirSync(currentDir, { withFileTypes: true });\n\t\tfor (const entry of entries) {\n\t\t\tconst fullPath = join(currentDir, entry.name);\n\t\t\tif (entry.isFile() && entry.name === binaryFileName) {\n\t\t\t\treturn fullPath;\n\t\t\t}\n\t\t\tif (entry.isDirectory()) {\n\t\t\t\tstack.push(fullPath);\n\t\t\t}\n\t\t}\n\t}\n\n\treturn null;\n}\n\nfunction formatSpawnFailure(result: SpawnSyncReturns<Buffer>): string {\n\tif (result.error?.message) {\n\t\treturn result.error.message;\n\t}\n\tconst stderr = result.stderr?.toString().trim();\n\tif (stderr) {\n\t\treturn stderr;\n\t}\n\tconst stdout = result.stdout?.toString().trim();\n\tif (stdout) {\n\t\treturn stdout;\n\t}\n\treturn `exit status ${result.status ?? \"unknown\"}`;\n}\n\nfunction runExtractionCommand(command: string, args: string[]): string | null {\n\tconst result = spawnSync(command, args, { stdio: \"pipe\" });\n\tif (!result.error && result.status === 0) {\n\t\treturn null;\n\t}\n\treturn `${command}: ${formatSpawnFailure(result)}`;\n}\n\nfunction extractTarGzArchive(archivePath: string, extractDir: string, assetName: string): void {\n\tconst failure = runExtractionCommand(\"tar\", [\"xzf\", archivePath, \"-C\", extractDir]);\n\tif (failure) {\n\t\tthrow new Error(`Failed to extract ${assetName}: ${failure}`);\n\t}\n}\n\nfunction getWindowsTarCommand(): string {\n\tconst systemRoot = process.env.SystemRoot ?? process.env.WINDIR;\n\tif (systemRoot) {\n\t\tconst systemTar = join(systemRoot, \"System32\", \"tar.exe\");\n\t\tif (existsSync(systemTar)) {\n\t\t\treturn systemTar;\n\t\t}\n\t}\n\treturn \"tar.exe\";\n}\n\nfunction extractZipArchive(archivePath: string, extractDir: string, assetName: string): void {\n\tconst failures: string[] = [];\n\n\tif (platform() === \"win32\") {\n\t\t// Windows ships bsdtar as tar.exe, which supports zip files. Prefer the\n\t\t// System32 binary over Git Bash's GNU tar, which does not handle zip archives.\n\t\tconst tarFailure = runExtractionCommand(getWindowsTarCommand(), [\"xf\", archivePath, \"-C\", extractDir]);\n\t\tif (!tarFailure) return;\n\t\tfailures.push(tarFailure);\n\n\t\tconst script =\n\t\t\t\"& { param($archive, $destination) $ErrorActionPreference = 'Stop'; Expand-Archive -LiteralPath $archive -DestinationPath $destination -Force }\";\n\t\tconst powershellFailure = runExtractionCommand(\"powershell.exe\", [\n\t\t\t\"-NoLogo\",\n\t\t\t\"-NoProfile\",\n\t\t\t\"-NonInteractive\",\n\t\t\t\"-ExecutionPolicy\",\n\t\t\t\"Bypass\",\n\t\t\t\"-Command\",\n\t\t\tscript,\n\t\t\tarchivePath,\n\t\t\textractDir,\n\t\t]);\n\t\tif (!powershellFailure) return;\n\t\tfailures.push(powershellFailure);\n\t} else {\n\t\tconst unzipFailure = runExtractionCommand(\"unzip\", [\"-q\", archivePath, \"-d\", extractDir]);\n\t\tif (!unzipFailure) return;\n\t\tfailures.push(unzipFailure);\n\n\t\tconst tarFailure = runExtractionCommand(\"tar\", [\"xf\", archivePath, \"-C\", extractDir]);\n\t\tif (!tarFailure) return;\n\t\tfailures.push(tarFailure);\n\t}\n\n\tthrow new Error(`Failed to extract ${assetName}: ${failures.join(\"; \")}`);\n}\n\n// Download and install a tool\nasync function downloadTool(tool: \"fd\" | \"rg\"): Promise<string> {\n\tconst config = TOOLS[tool];\n\tif (!config) throw new Error(`Unknown tool: ${tool}`);\n\n\tconst plat = platform();\n\tconst architecture = arch();\n\n\t// Get latest version\n\tlet version = await getLatestVersion(config.repo);\n\tif (tool === \"fd\" && plat === \"darwin\" && architecture === \"x64\") {\n\t\tversion = \"10.3.0\";\n\t}\n\n\t// Get asset name for this platform\n\tconst assetName = config.getAssetName(version, plat, architecture);\n\tif (!assetName) {\n\t\tthrow new Error(`Unsupported platform: ${plat}/${architecture}`);\n\t}\n\n\t// Create tools directory\n\tmkdirSync(TOOLS_DIR, { recursive: true });\n\n\tconst downloadUrl = `https://github.com/${config.repo}/releases/download/${config.tagPrefix}${version}/${assetName}`;\n\tconst archivePath = join(TOOLS_DIR, assetName);\n\tconst binaryExt = plat === \"win32\" ? \".exe\" : \"\";\n\tconst binaryPath = join(TOOLS_DIR, config.binaryName + binaryExt);\n\n\t// Download\n\tawait downloadFile(downloadUrl, archivePath);\n\n\t// Extract into a unique temp directory. fd and rg downloads can run concurrently\n\t// during startup, so sharing a fixed directory causes races.\n\tconst extractDir = join(\n\t\tTOOLS_DIR,\n\t\t`extract_tmp_${config.binaryName}_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,\n\t);\n\tmkdirSync(extractDir, { recursive: true });\n\n\ttry {\n\t\tif (assetName.endsWith(\".tar.gz\")) {\n\t\t\textractTarGzArchive(archivePath, extractDir, assetName);\n\t\t} else if (assetName.endsWith(\".zip\")) {\n\t\t\textractZipArchive(archivePath, extractDir, assetName);\n\t\t} else {\n\t\t\tthrow new Error(`Unsupported archive format: ${assetName}`);\n\t\t}\n\n\t\t// Find the binary in extracted files. Some archives contain files directly\n\t\t// at root, others nest under a versioned subdirectory.\n\t\tconst binaryFileName = config.binaryName + binaryExt;\n\t\tconst extractedDir = join(extractDir, assetName.replace(/\\.(tar\\.gz|zip)$/, \"\"));\n\t\tconst extractedBinaryCandidates = [join(extractedDir, binaryFileName), join(extractDir, binaryFileName)];\n\t\tlet extractedBinary = extractedBinaryCandidates.find((candidate) => existsSync(candidate));\n\n\t\tif (!extractedBinary) {\n\t\t\textractedBinary = findBinaryRecursively(extractDir, binaryFileName) ?? undefined;\n\t\t}\n\n\t\tif (extractedBinary) {\n\t\t\trenameSync(extractedBinary, binaryPath);\n\t\t} else {\n\t\t\tthrow new Error(`Binary not found in archive: expected ${binaryFileName} under ${extractDir}`);\n\t\t}\n\n\t\t// Make executable (Unix only)\n\t\tif (plat !== \"win32\") {\n\t\t\tchmodSync(binaryPath, 0o755);\n\t\t}\n\t} finally {\n\t\t// Cleanup\n\t\trmSync(archivePath, { force: true });\n\t\trmSync(extractDir, { recursive: true, force: true });\n\t}\n\n\treturn binaryPath;\n}\n\n// Termux package names for tools\nconst TERMUX_PACKAGES: Record<string, string> = {\n\tfd: \"fd\",\n\trg: \"ripgrep\",\n};\n\nconst FFF_PLATFORM_PACKAGES: Record<string, string> = {\n\t\"darwin/arm64\": \"@ff-labs/fff-bin-darwin-arm64\",\n\t\"darwin/x64\": \"@ff-labs/fff-bin-darwin-x64\",\n\t\"linux/arm64/glibc\": \"@ff-labs/fff-bin-linux-arm64-gnu\",\n\t\"linux/arm64/musl\": \"@ff-labs/fff-bin-linux-arm64-musl\",\n\t\"linux/x64/glibc\": \"@ff-labs/fff-bin-linux-x64-gnu\",\n\t\"linux/x64/musl\": \"@ff-labs/fff-bin-linux-x64-musl\",\n\t\"win32/arm64\": \"@ff-labs/fff-bin-win32-arm64\",\n\t\"win32/x64\": \"@ff-labs/fff-bin-win32-x64\",\n};\n\nlet fffNodeInstallPromise: Promise<unknown | undefined> | undefined;\n\nfunction detectLinuxLibc(): \"glibc\" | \"musl\" {\n\tlet output = \"\";\n\ttry {\n\t\tconst result = spawnSync(\"ldd\", [\"--version\"], { encoding: \"utf-8\", stdio: \"pipe\", timeout: 5000 });\n\t\toutput = `${result.stdout ?? \"\"}${result.stderr ?? \"\"}`;\n\t} catch (e: unknown) {\n\t\tconst err = e as { stdout?: string | Buffer; stderr?: string | Buffer };\n\t\toutput = `${String(err.stdout ?? \"\")}${String(err.stderr ?? \"\")}`;\n\t}\n\treturn output.toLowerCase().includes(\"musl\") ? \"musl\" : \"glibc\";\n}\n\nfunction getFffPlatformPackageName(): string | undefined {\n\tconst plat = platform();\n\tconst architecture = arch();\n\tif (plat === \"linux\") {\n\t\treturn FFF_PLATFORM_PACKAGES[`${plat}/${architecture}/${detectLinuxLibc()}`];\n\t}\n\treturn FFF_PLATFORM_PACKAGES[`${plat}/${architecture}`];\n}\n\nfunction createManagedFffRequire(): ModuleRequire | undefined {\n\tif (!existsSync(FFF_MANAGED_PACKAGE_JSON)) return undefined;\n\treturn createRequire(pathToFileURL(FFF_MANAGED_PACKAGE_JSON).href);\n}\n\nfunction findFffNodeDistEntry(startPath: string): string | undefined {\n\tlet currentDir = dirname(startPath);\n\twhile (currentDir !== dirname(currentDir)) {\n\t\tconst candidate = join(currentDir, \"node_modules\", \"@ff-labs\", \"fff-node\", \"dist\", \"src\", \"index.js\");\n\t\tif (existsSync(candidate)) return candidate;\n\t\tcurrentDir = dirname(currentDir);\n\t}\n\treturn undefined;\n}\n\nfunction loadFffNodeDistEntry(requireFff: ModuleRequire): unknown | undefined {\n\tif (!requireFff.resolve) return undefined;\n\ttry {\n\t\tconst ffiPath = requireFff.resolve(\"ffi-rs\");\n\t\tconst fffEntry = findFffNodeDistEntry(ffiPath);\n\t\treturn fffEntry ? requireFff(fffEntry) : undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nfunction loadFffNodeWith(requireFff: ModuleRequire): unknown | undefined {\n\ttry {\n\t\treturn requireFff(\"@ff-labs/fff-node\");\n\t} catch {\n\t\treturn loadFffNodeDistEntry(requireFff);\n\t}\n}\n\n/**\n * @param requires Override the resolution candidates, for tests (mirrors\n * fff-search-backend.ts's loadFffModule(requires?)). Whether this resolves\n * depends on the ambient environment -- @ff-labs/fff-node is a real npm\n * dependency (package.json), so moduleRequire succeeds wherever a normal\n * `npm install`/`npm ci` provisioned it (e.g. CI) even though it fails on a\n * dev checkout that never ran that install here (this repo resolves fff-node\n * via the separate managed-dir path instead). A test asserting \"nothing is\n * available\" must pass `[]` here rather than relying on that being true.\n */\nexport function loadAvailableFffNodePackage(requires?: readonly ModuleRequire[]): unknown | undefined {\n\tconst candidates =\n\t\trequires ??\n\t\t[moduleRequire, executableDirRequire, createManagedFffRequire()].filter((candidate): candidate is ModuleRequire =>\n\t\t\tBoolean(candidate),\n\t\t);\n\tfor (const requireFff of candidates) {\n\t\tconst loaded = loadFffNodeWith(requireFff);\n\t\tif (loaded) return loaded;\n\t}\n\treturn undefined;\n}\n\nasync function runNpmInstall(args: string[]): Promise<{ code: number | null; stderr: string }> {\n\ttry {\n\t\tconst child = spawnProcess(\"npm\", args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\tlet stderr = \"\";\n\t\tchild.stderr?.on(\"data\", (chunk) => {\n\t\t\tstderr += chunk.toString();\n\t\t});\n\t\tconst code = await waitForChildProcess(child);\n\t\treturn { code, stderr };\n\t} catch (error) {\n\t\treturn { code: 1, stderr: error instanceof Error ? error.message : String(error) };\n\t}\n}\n\n/**\n * Outcome of the most recent {@link ensureFffNodePackage} call, kept for\n * observability (e.g. a future `doctor` check) since the function itself\n * only ever returns the loaded module or `undefined` either way.\n *\n * `install-failed` is distinguished from `offline`/`unsupported-platform`\n * because it is the only one worth *retrying*: offline mode and an\n * unsupported platform are stable for the life of the process, but a real\n * install attempt can fail on a transient issue (registry hiccup, timeout)\n * that may no longer apply on the next search. See\n * DefaultFffSearchBackend.getFinder in fff-search-backend.ts, which uses\n * this distinction to decide whether a failed finder is retryable.\n */\nexport type FffInstallOutcome =\n\t| { status: \"already-available\" }\n\t| { status: \"offline\" }\n\t| { status: \"unsupported-platform\" }\n\t| { status: \"installed\" }\n\t| { status: \"install-failed\"; reason: string };\n\n/**\n * How long a genuine install failure gates out a NEW npm spawn. An agent turn\n * can fire several find/grep calls in quick succession, and each one now\n * primes the finder in the background (see tryFffFind/tryFffGrep) -- without\n * this, a persistently-failing install (registry down, disk full, ...) would\n * re-spawn npm on every single one of those calls instead of once.\n *\n * This gates the SPAWN inside ensureFffNodePackage, not whether a failed\n * finder is retryable (see isFffInstallRetryable): DefaultFffSearchBackend\n * always evicts a failed finder so the next search re-enters this function,\n * and it is THIS cooldown check -- evaluated fresh, at call time -- that\n * decides whether that re-entry is a real attempt or a fast, spawn-free bail.\n * (An earlier version conflated the two: it gated eviction itself on the\n * cooldown, which is checked once, immediately after the failure it's timing\n * -- i.e. always still within the window -- so the failed finder was never\n * evicted and the retry never got a chance to happen at all.)\n */\nexport const FFF_INSTALL_RETRY_COOLDOWN_MS = 30_000;\n\nlet lastFffInstallOutcome: FffInstallOutcome | undefined;\nlet lastFffInstallFailureAt: number | undefined;\n\n/** The outcome of the last {@link ensureFffNodePackage} call, if any. */\nexport function getLastFffInstallOutcome(): FffInstallOutcome | undefined {\n\treturn lastFffInstallOutcome;\n}\n\n/** Whether the last install outcome was a genuine failure worth retrying (as opposed to a stable \"not applicable\" result). Cooldown-independent by design -- see FFF_INSTALL_RETRY_COOLDOWN_MS. */\nexport function isFffInstallRetryable(): boolean {\n\treturn lastFffInstallOutcome?.status === \"install-failed\";\n}\n\n/**\n * Pure decision logic behind {@link isFffInstallCoolingDown}, exposed directly\n * so tests can assert the cooldown boundary without faking the system clock.\n */\nexport function computeIsFffInstallCoolingDown(\n\toutcome: FffInstallOutcome | undefined,\n\tfailedAt: number | undefined,\n\tnow: number,\n): boolean {\n\tif (outcome?.status !== \"install-failed\") return false;\n\tif (failedAt === undefined) return false;\n\treturn now - failedAt < FFF_INSTALL_RETRY_COOLDOWN_MS;\n}\n\n/** Whether a real install attempt happened too recently to try again right now. */\nfunction isFffInstallCoolingDown(): boolean {\n\treturn computeIsFffInstallCoolingDown(lastFffInstallOutcome, lastFffInstallFailureAt, Date.now());\n}\n\n/** Records a genuine install failure and stamps when it happened, so the cooldown above has a start time to measure from. */\nfunction recordFffInstallFailure(reason: string): void {\n\tlastFffInstallOutcome = { status: \"install-failed\", reason };\n\tlastFffInstallFailureAt = Date.now();\n}\n\nasync function installManagedFffNodePackage(platformPackage: string, silent: boolean): Promise<unknown | undefined> {\n\ttry {\n\t\tmkdirSync(FFF_MANAGED_DIR, { recursive: true });\n\t\tif (!existsSync(FFF_MANAGED_PACKAGE_JSON)) {\n\t\t\twriteFileSync(FFF_MANAGED_PACKAGE_JSON, '{\"name\":\"pi-managed-fff-node\",\"private\":true,\"version\":\"0.0.0\"}\\n');\n\t\t}\n\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.dim(\"FFF native search not found. Installing managed FFF package...\"));\n\t\t}\n\n\t\tconst args = [\n\t\t\t\"install\",\n\t\t\t\"--ignore-scripts\",\n\t\t\t\"--omit=dev\",\n\t\t\t\"--include=optional\",\n\t\t\t\"--no-audit\",\n\t\t\t\"--no-fund\",\n\t\t\t\"--package-lock=false\",\n\t\t\t\"--prefix\",\n\t\t\tFFF_MANAGED_DIR,\n\t\t\t`@ff-labs/fff-node@${FFF_NODE_VERSION}`,\n\t\t\t`${platformPackage}@${FFF_NODE_VERSION}`,\n\t\t];\n\t\tconst result = await runNpmInstall(args);\n\t\tif (result.code !== 0) {\n\t\t\tconst reason = result.stderr.trim() || `npm exited with code ${result.code}`;\n\t\t\tif (!silent) {\n\t\t\t\tconsole.log(chalk.yellow(`Failed to install FFF native search: ${reason}`));\n\t\t\t}\n\t\t\trecordFffInstallFailure(reason);\n\t\t\treturn undefined;\n\t\t}\n\t\tconst loaded = loadFffNodeWith(createRequire(pathToFileURL(FFF_MANAGED_PACKAGE_JSON).href));\n\t\tif (!loaded) {\n\t\t\tconst reason = \"Managed FFF install completed but @ff-labs/fff-node could not be loaded.\";\n\t\t\tif (!silent) {\n\t\t\t\tconsole.log(chalk.yellow(reason));\n\t\t\t}\n\t\t\trecordFffInstallFailure(reason);\n\t\t\treturn undefined;\n\t\t}\n\t\tlastFffInstallOutcome = { status: \"installed\" };\n\t\treturn loaded;\n\t} catch (error) {\n\t\t// Never let a filesystem/spawn surprise (e.g. a read-only home directory)\n\t\t// crash the caller: fall back like any other install failure, but keep\n\t\t// the reason observable.\n\t\tconst reason = error instanceof Error ? error.message : String(error);\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`Failed to install FFF native search: ${reason}`));\n\t\t}\n\t\trecordFffInstallFailure(reason);\n\t\treturn undefined;\n\t}\n}\n\nexport async function ensureFffNodePackage(\n\tsilent: boolean = false,\n\tforceManagedInstall: boolean = false,\n\t/** Override the \"is it already available\" resolution candidates, for tests. See loadAvailableFffNodePackage's doc. */\n\trequires?: readonly ModuleRequire[],\n): Promise<unknown | undefined> {\n\tconst existing = forceManagedInstall ? undefined : loadAvailableFffNodePackage(requires);\n\tif (existing) {\n\t\tlastFffInstallOutcome = { status: \"already-available\" };\n\t\treturn existing;\n\t}\n\n\tif (isOfflineModeEnabled()) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(\"FFF native search not found. Offline mode enabled, skipping install.\"));\n\t\t}\n\t\tlastFffInstallOutcome = { status: \"offline\" };\n\t\treturn undefined;\n\t}\n\n\t// A prior attempt failed too recently to try again: bail out fast (no npm\n\t// spawn, no platform/libc probing) rather than repeating a doomed attempt.\n\t// Leaves lastFffInstallOutcome/lastFffInstallFailureAt untouched -- this\n\t// isn't a new attempt, so there's nothing new to record.\n\tif (isFffInstallCoolingDown()) {\n\t\treturn undefined;\n\t}\n\n\tconst platformPackage = getFffPlatformPackageName();\n\tif (!platformPackage) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`FFF native search is not available for ${platform()}/${arch()}.`));\n\t\t}\n\t\tlastFffInstallOutcome = { status: \"unsupported-platform\" };\n\t\treturn undefined;\n\t}\n\n\tfffNodeInstallPromise ??= installManagedFffNodePackage(platformPackage, silent).finally(() => {\n\t\tfffNodeInstallPromise = undefined;\n\t});\n\treturn fffNodeInstallPromise;\n}\n\n// Ensure a tool is available, downloading if necessary\n// Returns the path to the tool, or null if unavailable\nexport async function ensureTool(tool: \"fd\" | \"rg\", silent: boolean = false): Promise<string | undefined> {\n\tconst existingPath = getToolPath(tool);\n\tif (existingPath) {\n\t\treturn existingPath;\n\t}\n\n\tconst config = TOOLS[tool];\n\tif (!config) return undefined;\n\n\tif (isOfflineModeEnabled()) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`${config.name} not found. Offline mode enabled, skipping download.`));\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// On Android/Termux, Linux binaries don't work due to Bionic libc incompatibility.\n\t// Users must install via pkg.\n\tif (platform() === \"android\") {\n\t\tconst pkgName = TERMUX_PACKAGES[tool] ?? tool;\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`${config.name} not found. Install with: pkg install ${pkgName}`));\n\t\t}\n\t\treturn undefined;\n\t}\n\n\t// Tool not found - download it\n\tif (!silent) {\n\t\tconsole.log(chalk.dim(`${config.name} not found. Downloading...`));\n\t}\n\n\ttry {\n\t\tconst path = await downloadTool(tool);\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.dim(`${config.name} installed to ${path}`));\n\t\t}\n\t\treturn path;\n\t} catch (e) {\n\t\tif (!silent) {\n\t\t\tconsole.log(chalk.yellow(`Failed to download ${config.name}: ${e instanceof Error ? e.message : e}`));\n\t\t}\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/utils/tools-manager.js

@@ -100,6 +100,52 @@ export function getToolPath(tool) {
     }
     return null;
 }
+const PYTHON_COMMANDS = ["python3", "python"];
+/**
+ * Detect a usable Python interpreter. SYSTEM tool (see src/core/doctor.ts):
+ * the doctor reports presence/version, it never installs this itself.
+ *
+ * @param commands Override the candidate command names, for tests.
+ */
+export function detectPython(commands = PYTHON_COMMANDS) {
+    for (const command of commands) {
+        try {
+            const result = spawnSync(command, ["--version"], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+            if (result.error)
+                continue;
+            // Python 2 prints its version to stderr; Python 3 prints to stdout. Some
+            // platforms' `python` alias is one or the other, so check both.
+            const version = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim() || undefined;
+            if (result.status !== 0 && !version)
+                continue;
+            return { present: true, command, version };
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return { present: false };
+}
+/**
+ * Runs `<command> --version` (or `versionArgs`) and returns its trimmed
+ * combined stdout+stderr, or undefined if the command can't be run. Used by
+ * the doctor (src/core/doctor.ts) to show a version alongside a tool it has
+ * already located by some other means (e.g. getToolPath("rg"), or the binary
+ * path OllamaRuntime.detect() reports) -- callers that only need a yes/no
+ * presence check should use commandExists/getToolPath/detectPython instead.
+ */
+export function probeVersion(command, versionArgs = ["--version"]) {
+    try {
+        const result = spawnSync(command, versionArgs, { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+        if (result.error)
+            return undefined;
+        const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+        return output || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 // Fetch latest release version from GitHub
 async function getLatestVersion(repo) {
     const response = await fetch(`https://api.github.com/repos/${repo}/releases/latest`, {
@@ -356,8 +402,20 @@ function loadFffNodeWith(requireFff) {
         return loadFffNodeDistEntry(requireFff);
     }
 }
-export function loadAvailableFffNodePackage() {
-    for (const requireFff of [moduleRequire, executableDirRequire, createManagedFffRequire()].filter((candidate) => Boolean(candidate))) {
+/**
+ * @param requires Override the resolution candidates, for tests (mirrors
+ * fff-search-backend.ts's loadFffModule(requires?)). Whether this resolves
+ * depends on the ambient environment -- @ff-labs/fff-node is a real npm
+ * dependency (package.json), so moduleRequire succeeds wherever a normal
+ * `npm install`/`npm ci` provisioned it (e.g. CI) even though it fails on a
+ * dev checkout that never ran that install here (this repo resolves fff-node
+ * via the separate managed-dir path instead). A test asserting "nothing is
+ * available" must pass `[]` here rather than relying on that being true.
+ */
+export function loadAvailableFffNodePackage(requires) {
+    const candidates = requires ??
+        [moduleRequire, executableDirRequire, createManagedFffRequire()].filter((candidate) => Boolean(candidate));
+    for (const requireFff of candidates) {
         const loaded = loadFffNodeWith(requireFff);
         if (loaded)
             return loaded;
@@ -378,48 +436,129 @@ async function runNpmInstall(args) {
         return { code: 1, stderr: error instanceof Error ? error.message : String(error) };
     }
 }
+/**
+ * How long a genuine install failure gates out a NEW npm spawn. An agent turn
+ * can fire several find/grep calls in quick succession, and each one now
+ * primes the finder in the background (see tryFffFind/tryFffGrep) -- without
+ * this, a persistently-failing install (registry down, disk full, ...) would
+ * re-spawn npm on every single one of those calls instead of once.
+ *
+ * This gates the SPAWN inside ensureFffNodePackage, not whether a failed
+ * finder is retryable (see isFffInstallRetryable): DefaultFffSearchBackend
+ * always evicts a failed finder so the next search re-enters this function,
+ * and it is THIS cooldown check -- evaluated fresh, at call time -- that
+ * decides whether that re-entry is a real attempt or a fast, spawn-free bail.
+ * (An earlier version conflated the two: it gated eviction itself on the
+ * cooldown, which is checked once, immediately after the failure it's timing
+ * -- i.e. always still within the window -- so the failed finder was never
+ * evicted and the retry never got a chance to happen at all.)
+ */
+export const FFF_INSTALL_RETRY_COOLDOWN_MS = 30_000;
+let lastFffInstallOutcome;
+let lastFffInstallFailureAt;
+/** The outcome of the last {@link ensureFffNodePackage} call, if any. */
+export function getLastFffInstallOutcome() {
+    return lastFffInstallOutcome;
+}
+/** Whether the last install outcome was a genuine failure worth retrying (as opposed to a stable "not applicable" result). Cooldown-independent by design -- see FFF_INSTALL_RETRY_COOLDOWN_MS. */
+export function isFffInstallRetryable() {
+    return lastFffInstallOutcome?.status === "install-failed";
+}
+/**
+ * Pure decision logic behind {@link isFffInstallCoolingDown}, exposed directly
+ * so tests can assert the cooldown boundary without faking the system clock.
+ */
+export function computeIsFffInstallCoolingDown(outcome, failedAt, now) {
+    if (outcome?.status !== "install-failed")
+        return false;
+    if (failedAt === undefined)
+        return false;
+    return now - failedAt < FFF_INSTALL_RETRY_COOLDOWN_MS;
+}
+/** Whether a real install attempt happened too recently to try again right now. */
+function isFffInstallCoolingDown() {
+    return computeIsFffInstallCoolingDown(lastFffInstallOutcome, lastFffInstallFailureAt, Date.now());
+}
+/** Records a genuine install failure and stamps when it happened, so the cooldown above has a start time to measure from. */
+function recordFffInstallFailure(reason) {
+    lastFffInstallOutcome = { status: "install-failed", reason };
+    lastFffInstallFailureAt = Date.now();
+}
 async function installManagedFffNodePackage(platformPackage, silent) {
-    mkdirSync(FFF_MANAGED_DIR, { recursive: true });
-    if (!existsSync(FFF_MANAGED_PACKAGE_JSON)) {
-        writeFileSync(FFF_MANAGED_PACKAGE_JSON, '{"name":"pi-managed-fff-node","private":true,"version":"0.0.0"}\n');
+    try {
+        mkdirSync(FFF_MANAGED_DIR, { recursive: true });
+        if (!existsSync(FFF_MANAGED_PACKAGE_JSON)) {
+            writeFileSync(FFF_MANAGED_PACKAGE_JSON, '{"name":"pi-managed-fff-node","private":true,"version":"0.0.0"}\n');
+        }
+        if (!silent) {
+            console.log(chalk.dim("FFF native search not found. Installing managed FFF package..."));
+        }
+        const args = [
+            "install",
+            "--ignore-scripts",
+            "--omit=dev",
+            "--include=optional",
+            "--no-audit",
+            "--no-fund",
+            "--package-lock=false",
+            "--prefix",
+            FFF_MANAGED_DIR,
+            `@ff-labs/fff-node@${FFF_NODE_VERSION}`,
+            `${platformPackage}@${FFF_NODE_VERSION}`,
+        ];
+        const result = await runNpmInstall(args);
+        if (result.code !== 0) {
+            const reason = result.stderr.trim() || `npm exited with code ${result.code}`;
+            if (!silent) {
+                console.log(chalk.yellow(`Failed to install FFF native search: ${reason}`));
+            }
+            recordFffInstallFailure(reason);
+            return undefined;
+        }
+        const loaded = loadFffNodeWith(createRequire(pathToFileURL(FFF_MANAGED_PACKAGE_JSON).href));
+        if (!loaded) {
+            const reason = "Managed FFF install completed but @ff-labs/fff-node could not be loaded.";
+            if (!silent) {
+                console.log(chalk.yellow(reason));
+            }
+            recordFffInstallFailure(reason);
+            return undefined;
+        }
+        lastFffInstallOutcome = { status: "installed" };
+        return loaded;
     }
-    if (!silent) {
-        console.log(chalk.dim("FFF native search not found. Installing managed FFF package..."));
-    }
-    const args = [
-        "install",
-        "--ignore-scripts",
-        "--omit=dev",
-        "--include=optional",
-        "--no-audit",
-        "--no-fund",
-        "--package-lock=false",
-        "--prefix",
-        FFF_MANAGED_DIR,
-        `@ff-labs/fff-node@${FFF_NODE_VERSION}`,
-        `${platformPackage}@${FFF_NODE_VERSION}`,
-    ];
-    const result = await runNpmInstall(args);
-    if (result.code !== 0) {
+    catch (error) {
+        // Never let a filesystem/spawn surprise (e.g. a read-only home directory)
+        // crash the caller: fall back like any other install failure, but keep
+        // the reason observable.
+        const reason = error instanceof Error ? error.message : String(error);
         if (!silent) {
-            console.log(chalk.yellow(`Failed to install FFF native search: ${result.stderr.trim() || `exit code ${result.code}`}`));
+            console.log(chalk.yellow(`Failed to install FFF native search: ${reason}`));
         }
+        recordFffInstallFailure(reason);
         return undefined;
     }
-    const loaded = loadFffNodeWith(createRequire(pathToFileURL(FFF_MANAGED_PACKAGE_JSON).href));
-    if (!loaded && !silent) {
-        console.log(chalk.yellow("Managed FFF install completed but @ff-labs/fff-node could not be loaded."));
-    }
-    return loaded;
 }
-export async function ensureFffNodePackage(silent = false, forceManagedInstall = false) {
-    const existing = forceManagedInstall ? undefined : loadAvailableFffNodePackage();
-    if (existing)
+export async function ensureFffNodePackage(silent = false, forceManagedInstall = false, 
+/** Override the "is it already available" resolution candidates, for tests. See loadAvailableFffNodePackage's doc. */
+requires) {
+    const existing = forceManagedInstall ? undefined : loadAvailableFffNodePackage(requires);
+    if (existing) {
+        lastFffInstallOutcome = { status: "already-available" };
         return existing;
+    }
     if (isOfflineModeEnabled()) {
         if (!silent) {
             console.log(chalk.yellow("FFF native search not found. Offline mode enabled, skipping install."));
         }
+        lastFffInstallOutcome = { status: "offline" };
+        return undefined;
+    }
+    // A prior attempt failed too recently to try again: bail out fast (no npm
+    // spawn, no platform/libc probing) rather than repeating a doomed attempt.
+    // Leaves lastFffInstallOutcome/lastFffInstallFailureAt untouched -- this
+    // isn't a new attempt, so there's nothing new to record.
+    if (isFffInstallCoolingDown()) {
         return undefined;
     }
     const platformPackage = getFffPlatformPackageName();
@@ -427,6 +566,7 @@ export async function ensureFffNodePackage(silent = false, forceManagedInstall =
         if (!silent) {
             console.log(chalk.yellow(`FFF native search is not available for ${platform()}/${arch()}.`));
         }
+        lastFffInstallOutcome = { status: "unsupported-platform" };
         return undefined;
     }
     fffNodeInstallPromise ??= installManagedFffNodePackage(platformPackage, silent).finally(() => {