@caupulican/pi-adaptative 0.80.86 → 0.80.89

package/dist/core/tools/fff-search-backend.js

@@ -0,0 +1,151 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { ensureFffNodePackage, loadAvailableFffNodePackage } from "../../utils/tools-manager.js";
+const DEFAULT_WAIT_FOR_SCAN_MS = 15_000;
+const MAX_FINDER_CACHE_SIZE = 8;
+const FFF_GITIGNORE_SKIP_DIRS = new Set([".git", "node_modules"]);
+let loadedFffModule;
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object";
+}
+function hasProperties(value) {
+    return Boolean(value) && (typeof value === "object" || typeof value === "function");
+}
+function isFffResult(value) {
+    if (!isRecord(value))
+        return false;
+    return value.ok === true || value.ok === false;
+}
+function isFffModule(value) {
+    if (!isRecord(value))
+        return false;
+    const fileFinder = value.FileFinder;
+    return hasProperties(fileFinder) && typeof fileFinder.create === "function";
+}
+export function loadFffModule(requires) {
+    if (requires) {
+        for (const requireFff of requires) {
+            try {
+                const loaded = requireFff("@ff-labs/fff-node");
+                if (isFffModule(loaded))
+                    return loaded;
+            }
+            catch {
+                // Try the next resolution root.
+            }
+        }
+        return null;
+    }
+    if (loadedFffModule !== undefined)
+        return loadedFffModule;
+    const loaded = loadAvailableFffNodePackage();
+    loadedFffModule = isFffModule(loaded) ? loaded : null;
+    return loadedFffModule;
+}
+async function ensureFffModule() {
+    const loaded = loadFffModule();
+    if (loaded)
+        return loaded;
+    const installed = await ensureFffNodePackage(true);
+    loadedFffModule = isFffModule(installed) ? installed : null;
+    return loadedFffModule;
+}
+function isFffRuntimeDisabled() {
+    const value = process.env.PI_FFF_DISABLED ?? process.env.PI_SEARCH_BACKEND;
+    if (!value)
+        return false;
+    return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "disabled";
+}
+function isRootScanningEnabled() {
+    const value = process.env.PI_FFF_ENABLE_ROOT_SCAN;
+    return value === "1" || value?.toLowerCase() === "true";
+}
+function destroyFinder(finder) {
+    if (finder && !finder.isDestroyed) {
+        finder.destroy();
+    }
+}
+export function relativePathInside(basePath, targetPath) {
+    const relative = path.relative(path.resolve(basePath), path.resolve(targetPath));
+    if (relative === "")
+        return "";
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        return undefined;
+    return relative.split(path.sep).join("/");
+}
+export async function hasGitignoreInTree(rootPath) {
+    const stack = [path.resolve(rootPath)];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return true;
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name === ".gitignore")
+                return true;
+            if (entry.isDirectory() && !FFF_GITIGNORE_SKIP_DIRS.has(entry.name)) {
+                stack.push(path.join(current, entry.name));
+            }
+        }
+    }
+    return false;
+}
+class DefaultFffSearchBackend {
+    finders = new Map();
+    async getFinder(basePath) {
+        if (isFffRuntimeDisabled())
+            return undefined;
+        const normalizedBasePath = path.resolve(basePath);
+        const cached = this.finders.get(normalizedBasePath);
+        if (cached)
+            return cached;
+        const created = this.createFinder(normalizedBasePath);
+        this.finders.set(normalizedBasePath, created);
+        this.evictIfNeeded();
+        return created;
+    }
+    evictIfNeeded() {
+        while (this.finders.size > MAX_FINDER_CACHE_SIZE) {
+            const firstKey = this.finders.keys().next().value;
+            if (!firstKey)
+                return;
+            const first = this.finders.get(firstKey);
+            this.finders.delete(firstKey);
+            void first?.then(destroyFinder, () => undefined);
+        }
+    }
+    async createFinder(basePath) {
+        let fff = await ensureFffModule();
+        if (!fff)
+            return undefined;
+        if (fff.FileFinder.isAvailable && !fff.FileFinder.isAvailable()) {
+            const installed = await ensureFffNodePackage(true, true);
+            loadedFffModule = isFffModule(installed) ? installed : null;
+            fff = loadedFffModule;
+            if (!fff || (fff.FileFinder.isAvailable && !fff.FileFinder.isAvailable()))
+                return undefined;
+        }
+        const created = fff.FileFinder.create({
+            basePath,
+            aiMode: true,
+            enableHomeDirScanning: true,
+            enableFsRootScanning: isRootScanningEnabled(),
+        });
+        if (!isFffResult(created) || !created.ok)
+            return undefined;
+        const scan = await created.value.waitForScan(DEFAULT_WAIT_FOR_SCAN_MS);
+        if (!scan.ok) {
+            destroyFinder(created.value);
+            return undefined;
+        }
+        return created.value;
+    }
+}
+export const defaultFffSearchBackend = new DefaultFffSearchBackend();
+//# sourceMappingURL=fff-search-backend.js.map

package/dist/core/tools/fff-search-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fff-search-backend.js","sourceRoot":"","sources":["../../../src/core/tools/fff-search-backend.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Dirent } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { ensureFffNodePackage, loadAvailableFffNodePackage } from \"../../utils/tools-manager.ts\";\n\nexport type FffResult<T> = { ok: true; value: T } | { ok: false; error: string };\nexport type FffGrepMode = \"plain\" | \"regex\" | \"fuzzy\";\n\nexport interface FffFileItem {\n\trelativePath: string;\n\tfileName: string;\n\tsize: number;\n\tmodified: number;\n\tgitStatus: string;\n\taccessFrecencyScore?: number;\n\tmodificationFrecencyScore?: number;\n\ttotalFrecencyScore?: number;\n}\n\nexport interface FffScore {\n\ttotal: number;\n\tbaseScore: number;\n\tmatchType: string;\n}\n\nexport interface FffSearchResult {\n\titems: FffFileItem[];\n\tscores: FffScore[];\n\ttotalMatched: number;\n\ttotalFiles: number;\n}\n\nexport interface FffSearchOptions {\n\tpageIndex?: number;\n\tpageSize?: number;\n}\n\nexport interface FffGlobOptions {\n\tpageIndex?: number;\n\tpageSize?: number;\n}\n\nexport interface FffGrepOptions {\n\tmaxMatchesPerFile?: number;\n\tsmartCase?: boolean;\n\tmode?: FffGrepMode;\n\tbeforeContext?: number;\n\tafterContext?: number;\n\tpageSize?: number;\n}\n\nexport interface FffGrepMatch {\n\trelativePath: string;\n\tfileName: string;\n\tgitStatus: string;\n\tsize: number;\n\tmodified: number;\n\tisBinary: boolean;\n\ttotalFrecencyScore: number;\n\taccessFrecencyScore: number;\n\tmodificationFrecencyScore: number;\n\tlineNumber: number;\n\tcol: number;\n\tbyteOffset: number;\n\tlineContent: string;\n\tmatchRanges: [number, number][];\n\tcontextBefore?: string[];\n\tcontextAfter?: string[];\n}\n\nexport interface FffGrepResult {\n\titems: FffGrepMatch[];\n\ttotalMatched: number;\n\ttotalFilesSearched: number;\n\ttotalFiles: number;\n\tfilteredFileCount: number;\n\tnextCursor: unknown | null;\n\tregexFallbackError?: string;\n}\n\nexport interface FffFileFinder {\n\treadonly isDestroyed: boolean;\n\tdestroy(): void;\n\tfileSearch(query: string, options?: FffSearchOptions): FffResult<FffSearchResult>;\n\tglob(pattern: string, options?: FffGlobOptions): FffResult<FffSearchResult>;\n\tgrep(query: string, options?: FffGrepOptions): FffResult<FffGrepResult>;\n\twaitForScan(timeoutMs?: number): Promise<FffResult<boolean>>;\n}\n\ninterface FffInitOptions {\n\tbasePath: string;\n\taiMode?: boolean;\n\tenableHomeDirScanning?: boolean;\n\tenableFsRootScanning?: boolean;\n}\n\ninterface FffFileFinderConstructor {\n\tcreate(options: FffInitOptions): FffResult<FffFileFinder>;\n\tisAvailable?: () => boolean;\n}\n\ninterface FffModule {\n\tFileFinder: FffFileFinderConstructor;\n}\n\nexport interface FffSearchBackend {\n\tgetFinder(basePath: string): Promise<FffFileFinder | undefined>;\n}\n\ntype ModuleRequire = (id: string) => unknown;\n\nconst DEFAULT_WAIT_FOR_SCAN_MS = 15_000;\nconst MAX_FINDER_CACHE_SIZE = 8;\nconst FFF_GITIGNORE_SKIP_DIRS = new Set([\".git\", \"node_modules\"]);\n\nlet loadedFffModule: FffModule | null | undefined;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn Boolean(value) && typeof value === \"object\";\n}\n\nfunction hasProperties(value: unknown): value is Record<string, unknown> {\n\treturn Boolean(value) && (typeof value === \"object\" || typeof value === \"function\");\n}\n\nfunction isFffResult<T>(value: unknown): value is FffResult<T> {\n\tif (!isRecord(value)) return false;\n\treturn value.ok === true || value.ok === false;\n}\n\nfunction isFffModule(value: unknown): value is FffModule {\n\tif (!isRecord(value)) return false;\n\tconst fileFinder = value.FileFinder;\n\treturn hasProperties(fileFinder) && typeof fileFinder.create === \"function\";\n}\n\nexport function loadFffModule(requires?: readonly ModuleRequire[]): FffModule | null {\n\tif (requires) {\n\t\tfor (const requireFff of requires) {\n\t\t\ttry {\n\t\t\t\tconst loaded = requireFff(\"@ff-labs/fff-node\");\n\t\t\t\tif (isFffModule(loaded)) return loaded;\n\t\t\t} catch {\n\t\t\t\t// Try the next resolution root.\n\t\t\t}\n\t\t}\n\t\treturn null;\n\t}\n\n\tif (loadedFffModule !== undefined) return loadedFffModule;\n\tconst loaded = loadAvailableFffNodePackage();\n\tloadedFffModule = isFffModule(loaded) ? loaded : null;\n\treturn loadedFffModule;\n}\n\nasync function ensureFffModule(): Promise<FffModule | null> {\n\tconst loaded = loadFffModule();\n\tif (loaded) return loaded;\n\tconst installed = await ensureFffNodePackage(true);\n\tloadedFffModule = isFffModule(installed) ? installed : null;\n\treturn loadedFffModule;\n}\n\nfunction isFffRuntimeDisabled(): boolean {\n\tconst value = process.env.PI_FFF_DISABLED ?? process.env.PI_SEARCH_BACKEND;\n\tif (!value) return false;\n\treturn value === \"1\" || value.toLowerCase() === \"true\" || value.toLowerCase() === \"disabled\";\n}\n\nfunction isRootScanningEnabled(): boolean {\n\tconst value = process.env.PI_FFF_ENABLE_ROOT_SCAN;\n\treturn value === \"1\" || value?.toLowerCase() === \"true\";\n}\n\nfunction destroyFinder(finder: FffFileFinder | undefined): void {\n\tif (finder && !finder.isDestroyed) {\n\t\tfinder.destroy();\n\t}\n}\n\nexport function relativePathInside(basePath: string, targetPath: string): string | undefined {\n\tconst relative = path.relative(path.resolve(basePath), path.resolve(targetPath));\n\tif (relative === \"\") return \"\";\n\tif (relative.startsWith(\"..\") || path.isAbsolute(relative)) return undefined;\n\treturn relative.split(path.sep).join(\"/\");\n}\n\nexport async function hasGitignoreInTree(rootPath: string): Promise<boolean> {\n\tconst stack = [path.resolve(rootPath)];\n\twhile (stack.length > 0) {\n\t\tconst current = stack.pop();\n\t\tif (!current) continue;\n\n\t\tlet entries: Dirent[];\n\t\ttry {\n\t\t\tentries = await readdir(current, { withFileTypes: true });\n\t\t} catch {\n\t\t\treturn true;\n\t\t}\n\n\t\tfor (const entry of entries) {\n\t\t\tif (entry.isFile() && entry.name === \".gitignore\") return true;\n\t\t\tif (entry.isDirectory() && !FFF_GITIGNORE_SKIP_DIRS.has(entry.name)) {\n\t\t\t\tstack.push(path.join(current, entry.name));\n\t\t\t}\n\t\t}\n\t}\n\treturn false;\n}\n\nclass DefaultFffSearchBackend implements FffSearchBackend {\n\tprivate readonly finders = new Map<string, Promise<FffFileFinder | undefined>>();\n\n\tasync getFinder(basePath: string): Promise<FffFileFinder | undefined> {\n\t\tif (isFffRuntimeDisabled()) return undefined;\n\n\t\tconst normalizedBasePath = path.resolve(basePath);\n\t\tconst cached = this.finders.get(normalizedBasePath);\n\t\tif (cached) return cached;\n\n\t\tconst created = this.createFinder(normalizedBasePath);\n\t\tthis.finders.set(normalizedBasePath, created);\n\t\tthis.evictIfNeeded();\n\t\treturn created;\n\t}\n\n\tprivate evictIfNeeded(): void {\n\t\twhile (this.finders.size > MAX_FINDER_CACHE_SIZE) {\n\t\t\tconst firstKey = this.finders.keys().next().value;\n\t\t\tif (!firstKey) return;\n\t\t\tconst first = this.finders.get(firstKey);\n\t\t\tthis.finders.delete(firstKey);\n\t\t\tvoid first?.then(destroyFinder, () => undefined);\n\t\t}\n\t}\n\n\tprivate async createFinder(basePath: string): Promise<FffFileFinder | undefined> {\n\t\tlet fff = await ensureFffModule();\n\t\tif (!fff) return undefined;\n\t\tif (fff.FileFinder.isAvailable && !fff.FileFinder.isAvailable()) {\n\t\t\tconst installed = await ensureFffNodePackage(true, true);\n\t\t\tloadedFffModule = isFffModule(installed) ? installed : null;\n\t\t\tfff = loadedFffModule;\n\t\t\tif (!fff || (fff.FileFinder.isAvailable && !fff.FileFinder.isAvailable())) return undefined;\n\t\t}\n\n\t\tconst created = fff.FileFinder.create({\n\t\t\tbasePath,\n\t\t\taiMode: true,\n\t\t\tenableHomeDirScanning: true,\n\t\t\tenableFsRootScanning: isRootScanningEnabled(),\n\t\t});\n\t\tif (!isFffResult<FffFileFinder>(created) || !created.ok) return undefined;\n\n\t\tconst scan = await created.value.waitForScan(DEFAULT_WAIT_FOR_SCAN_MS);\n\t\tif (!scan.ok) {\n\t\t\tdestroyFinder(created.value);\n\t\t\treturn undefined;\n\t\t}\n\t\treturn created.value;\n\t}\n}\n\nexport const defaultFffSearchBackend: FffSearchBackend = new DefaultFffSearchBackend();\n"]}

package/dist/core/tools/find.d.ts

@@ -1,6 +1,10 @@
 import type { AgentTool } from "@caupulican/pi-agent-core";
 import { type Static, Type } from "typebox";
+import type { ArtifactStore } from "../context/context-artifacts.ts";
+import { type BroadQueryTracker } from "../context/tool-output-packer.ts";
 import type { ToolDefinition } from "../extensions/types.ts";
+import { type FffSearchBackend } from "./fff-search-backend.ts";
+import { type SearchRouter } from "./search-router.ts";
 import { type TruncationResult } from "./truncate.ts";
 declare const findSchema: Type.TObject<{
     pattern: Type.TString;
@@ -12,6 +16,10 @@ export type FindToolInput = Static<typeof findSchema>;
 export interface FindToolDetails {
     truncation?: TruncationResult;
     resultLimitReached?: number;
+    /** Set only when output was packed to an artifact; see tool-output-packer.ts. */
+    artifactId?: string;
+    /** Set when this exact query has repeatedly produced broad/truncated results. */
+    invalidationCandidate?: boolean;
 }
 /**
  * Pluggable operations for the find tool.
@@ -27,8 +35,20 @@ export interface FindOperations {
     }) => Promise<string[]> | string[];
 }
 export interface FindToolOptions {
-    /** Custom operations for find. Default: local filesystem plus fd */
+    /** Custom operations for find. Default: local filesystem plus routed FFF/fd search */
     operations?: FindOperations;
+    /** FFF backend for resident indexed search. Set false to force fd fallback. */
+    fff?: FffSearchBackend | false;
+    /** Pure router that selects FFF or fd from request filters and environment facts. */
+    searchRouter?: SearchRouter;
+    /**
+     * Opt-in artifact store for first-capture-then-bound output packing (Phase 3). When
+     * omitted (the default), behavior is byte-for-byte unchanged from before this option
+     * existed: output is truncated the same way, just never artifact-backed.
+     */
+    artifactStore?: ArtifactStore;
+    /** Opt-in tracker for repeated-broad-query "do not repeat" signals. Also default-off. */
+    broadQueryTracker?: BroadQueryTracker;
 }
 export declare function createFindToolDefinition(cwd: string, options?: FindToolOptions): ToolDefinition<typeof findSchema, FindToolDetails | undefined>;
 export declare function createFindTool(cwd: string, options?: FindToolOptions): AgentTool<typeof findSchema>;

package/dist/core/tools/find.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/core/tools/find.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAI3D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,wBAAwB,CAAC;AAItF,OAAO,EAAiC,KAAK,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AAMnG,QAAA,MAAM,UAAU;;;;;EAQd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAItD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,2BAA2B;IAC3B,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7D,4EAA4E;IAC5E,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;CACnH;AAQD,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;CAC5B;AAoHD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CA0NhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG","sourcesContent":["import { createInterface } from \"node:readline\";\nimport type { AgentTool } from \"@caupulican/pi-agent-core\";\nimport { Text } from \"@caupulican/pi-tui\";\nimport { spawn } from \"child_process\";\nimport path from \"path\";\nimport { type Static, Type } from \"typebox\";\nimport { keyHint } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { ensureTool } from \"../../utils/tools-manager.ts\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport { pathExists, resolveToCwd } from \"./path-utils.ts\";\nimport { getTextOutput, invalidArgText, shortenPath, str } from \"./render-utils.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from \"./truncate.ts\";\n\nfunction toPosixPath(value: string): string {\n\treturn value.split(path.sep).join(\"/\");\n}\n\nconst findSchema = Type.Object({\n\tpattern: Type.String({\n\t\tdescription:\n\t\t\t\"Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.spec.ts'. Use '.' to match all files.\",\n\t}),\n\tpath: Type.Optional(Type.String({ description: \"Directory to search in (default: current directory)\" })),\n\tlimit: Type.Optional(Type.Number({ description: \"Maximum number of results (default: 1000)\" })),\n\tignoreCase: Type.Optional(Type.Boolean({ description: \"Case-insensitive matching (default: false)\" })),\n});\n\nexport type FindToolInput = Static<typeof findSchema>;\n\nconst DEFAULT_LIMIT = 1000;\n\nexport interface FindToolDetails {\n\ttruncation?: TruncationResult;\n\tresultLimitReached?: number;\n}\n\n/**\n * Pluggable operations for the find tool.\n * Override these to delegate file search to remote systems (for example SSH).\n */\nexport interface FindOperations {\n\t/** Check if path exists */\n\texists: (absolutePath: string) => Promise<boolean> | boolean;\n\t/** Find files matching glob pattern. Returns relative or absolute paths. */\n\tglob: (pattern: string, cwd: string, options: { ignore: string[]; limit: number }) => Promise<string[]> | string[];\n}\n\nconst defaultFindOperations: FindOperations = {\n\texists: pathExists,\n\t// This is a placeholder. Actual fd execution happens in execute() when no custom glob is provided.\n\tglob: () => [],\n};\n\nexport interface FindToolOptions {\n\t/** Custom operations for find. Default: local filesystem plus fd */\n\toperations?: FindOperations;\n}\n\nfunction formatFindCall(\n\targs: { pattern: string; path?: string; limit?: number } | undefined,\n\ttheme: Theme,\n\tcwd: string,\n): string {\n\tconst pattern = str(args?.pattern);\n\tconst rawPath = str(args?.path);\n\tconst path = rawPath !== null ? shortenPath(rawPath || \".\", cwd) : null;\n\tconst limit = args?.limit;\n\tconst invalidArg = invalidArgText(theme);\n\tlet text =\n\t\ttheme.fg(\"toolTitle\", theme.bold(\"find\")) +\n\t\t\" \" +\n\t\t(pattern === null ? invalidArg : theme.fg(\"accent\", pattern || \"\")) +\n\t\ttheme.fg(\"toolOutput\", ` in ${path === null ? invalidArg : path}`);\n\tif (limit !== undefined) {\n\t\ttext += theme.fg(\"toolOutput\", ` (limit ${limit})`);\n\t}\n\treturn text;\n}\n\nfunction formatFindResult(\n\tresult: {\n\t\tcontent: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;\n\t\tdetails?: FindToolDetails;\n\t},\n\toptions: ToolRenderResultOptions,\n\ttheme: Theme,\n\tshowImages: boolean,\n): string {\n\tconst output = getTextOutput(result, showImages).trim();\n\tlet text = \"\";\n\tif (output) {\n\t\tconst lines = output.split(\"\\n\");\n\t\tconst maxLines = options.expanded ? lines.length : 20;\n\t\tconst displayLines = lines.slice(0, maxLines);\n\t\tconst remaining = lines.length - maxLines;\n\t\ttext += `\\n${displayLines.map((line) => theme.fg(\"toolOutput\", line)).join(\"\\n\")}`;\n\t\tif (remaining > 0) {\n\t\t\ttext += `${theme.fg(\"muted\", `\\n... (${remaining} more lines,`)} ${keyHint(\"app.tools.expand\", \"to expand\")})`;\n\t\t}\n\t}\n\n\tconst resultLimit = result.details?.resultLimitReached;\n\tconst truncation = result.details?.truncation;\n\tif (resultLimit || truncation?.truncated) {\n\t\tconst warnings: string[] = [];\n\t\tif (resultLimit) warnings.push(`${resultLimit} results limit`);\n\t\tif (truncation?.truncated) warnings.push(`${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit`);\n\t\ttext += `\\n${theme.fg(\"warning\", `[Truncated: ${warnings.join(\", \")}]`)}`;\n\t}\n\treturn text;\n}\n\nfunction formatFindResults(relativized: string[], effectiveLimit: number): { text: string; details: FindToolDetails } {\n\tif (relativized.length === 0) {\n\t\treturn { text: \"No files found matching pattern\", details: {} };\n\t}\n\n\tconst dirGroups = new Map<string, string[]>();\n\tconst extCounts = new Map<string, number>();\n\n\tfor (const p of relativized) {\n\t\tconst dir = path.dirname(p);\n\t\tconst base = path.basename(p);\n\t\tconst dirKey = dir === \".\" ? \"./\" : `${dir}/`;\n\t\tif (!dirGroups.has(dirKey)) {\n\t\t\tdirGroups.set(dirKey, []);\n\t\t}\n\t\tdirGroups.get(dirKey)!.push(base);\n\n\t\tconst ext = path.extname(p).toLowerCase() || \"(no extension)\";\n\t\textCounts.set(ext, (extCounts.get(ext) || 0) + 1);\n\t}\n\n\tconst sortedDirs = Array.from(dirGroups.keys()).sort((a, b) => a.localeCompare(b));\n\tconst formattedLines: string[] = [];\n\tfor (const dir of sortedDirs) {\n\t\tformattedLines.push(dir);\n\t\tconst files = dirGroups.get(dir)!;\n\t\tfiles.sort((a, b) => a.localeCompare(b));\n\t\tfor (const file of files) {\n\t\t\tformattedLines.push(`  ${file}`);\n\t\t}\n\t}\n\n\tconst extSummaryParts = Array.from(extCounts.entries())\n\t\t.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))\n\t\t.map(([ext, count]) => `${ext}: ${count}`);\n\tconst extSummary = `Extensions: ${extSummaryParts.join(\", \")}`;\n\n\tconst resultLimitReached = relativized.length >= effectiveLimit;\n\tconst rawOutput = formattedLines.join(\"\\n\");\n\tconst truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });\n\tlet resultOutput = truncation.content;\n\tconst details: FindToolDetails = {};\n\tconst notices: string[] = [];\n\tif (resultLimitReached) {\n\t\tnotices.push(`${effectiveLimit} results limit reached`);\n\t\tdetails.resultLimitReached = effectiveLimit;\n\t}\n\tif (truncation.truncated) {\n\t\tnotices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);\n\t\tdetails.truncation = truncation;\n\t}\n\tif (relativized.length > 0) {\n\t\tresultOutput += `\\n\\n[Summary - ${extSummary}]`;\n\t}\n\tif (notices.length > 0) {\n\t\tresultOutput += `\\n\\n[${notices.join(\". \")}]`;\n\t}\n\treturn { text: resultOutput, details };\n}\n\nexport function createFindToolDefinition(\n\tcwd: string,\n\toptions?: FindToolOptions,\n): ToolDefinition<typeof findSchema, FindToolDetails | undefined> {\n\tconst customOps = options?.operations;\n\treturn {\n\t\tname: \"find\",\n\t\tlabel: \"find\",\n\t\tdescription: `Search for files by glob pattern. Returns matching file paths relative to the search directory. Respects .gitignore. Output is truncated to ${DEFAULT_LIMIT} results or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,\n\t\tpromptSnippet: \"Find files by glob pattern (respects .gitignore)\",\n\t\tparameters: findSchema,\n\t\ttoolGroup: \"explore\",\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{\n\t\t\t\tpattern,\n\t\t\t\tpath: searchDir,\n\t\t\t\tlimit,\n\t\t\t\tignoreCase,\n\t\t\t}: { pattern: string; path?: string; limit?: number; ignoreCase?: boolean },\n\t\t\tsignal?: AbortSignal,\n\t\t\t_onUpdate?,\n\t\t\t_ctx?,\n\t\t) {\n\t\t\treturn new Promise((resolve, reject) => {\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tlet settled = false;\n\t\t\t\tlet stopChild: (() => void) | undefined;\n\t\t\t\tconst settle = (fn: () => void) => {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\tstopChild = undefined;\n\t\t\t\t\tfn();\n\t\t\t\t};\n\t\t\t\tconst onAbort = () => {\n\t\t\t\t\tstopChild?.();\n\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t};\n\t\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\n\t\t\t\t(async () => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst searchPath = resolveToCwd(searchDir || \".\", cwd);\n\t\t\t\t\t\tconst effectiveLimit = limit ?? DEFAULT_LIMIT;\n\t\t\t\t\t\tconst ops = customOps ?? defaultFindOperations;\n\n\t\t\t\t\t\tlet effectivePattern = pattern;\n\t\t\t\t\t\tif (pattern === \".\") {\n\t\t\t\t\t\t\teffectivePattern = \"**/*\";\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// If custom operations provide glob(), use that instead of fd.\n\t\t\t\t\t\tif (customOps?.glob) {\n\t\t\t\t\t\t\tif (!(await ops.exists(searchPath))) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(`Path not found: ${searchPath}`)));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst results = await ops.glob(effectivePattern, searchPath, {\n\t\t\t\t\t\t\t\tignore: [\"**/node_modules/**\", \"**/.git/**\"],\n\t\t\t\t\t\t\t\tlimit: effectiveLimit,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\t// Relativize paths against the search root for stable output.\n\t\t\t\t\t\t\tconst relativized = results.map((p) => {\n\t\t\t\t\t\t\t\tif (p.startsWith(searchPath)) return toPosixPath(p.slice(searchPath.length + 1));\n\t\t\t\t\t\t\t\treturn toPosixPath(path.relative(searchPath, p));\n\t\t\t\t\t\t\t});\n\n\t\t\t\t\t\t\tconst formatted = formatFindResults(relativized, effectiveLimit);\n\t\t\t\t\t\t\tsettle(() =>\n\t\t\t\t\t\t\t\tresolve({\n\t\t\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: formatted.text }],\n\t\t\t\t\t\t\t\t\tdetails: Object.keys(formatted.details).length > 0 ? formatted.details : undefined,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Default implementation uses fd.\n\t\t\t\t\t\tconst fdPath = await ensureTool(\"fd\", true);\n\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tif (!fdPath) {\n\t\t\t\t\t\t\tsettle(() => reject(new Error(\"fd is not available and could not be downloaded\")));\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Build fd arguments. --no-require-git makes fd apply hierarchical .gitignore\n\t\t\t\t\t\t// semantics whether or not the search path is inside a git repository, without\n\t\t\t\t\t\t// leaking sibling-directory rules the way --ignore-file (a global source) would.\n\t\t\t\t\t\tconst args: string[] = [\n\t\t\t\t\t\t\t\"--glob\",\n\t\t\t\t\t\t\t\"--color=never\",\n\t\t\t\t\t\t\t\"--hidden\",\n\t\t\t\t\t\t\t\"--no-require-git\",\n\t\t\t\t\t\t\t\"--max-results\",\n\t\t\t\t\t\t\tString(effectiveLimit),\n\t\t\t\t\t\t];\n\t\t\t\t\t\tif (ignoreCase) {\n\t\t\t\t\t\t\targs.push(\"--ignore-case\");\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// fd --glob matches against the basename unless --full-path is set; in --full-path\n\t\t\t\t\t\t// mode it matches against the absolute candidate path, so a path-containing\n\t\t\t\t\t\t// pattern like 'src/**/*.spec.ts' needs a leading '**/' to match anything.\n\t\t\t\t\t\tlet finalPattern = effectivePattern;\n\t\t\t\t\t\tif (effectivePattern.includes(\"/\")) {\n\t\t\t\t\t\t\targs.push(\"--full-path\");\n\t\t\t\t\t\t\tif (\n\t\t\t\t\t\t\t\t!effectivePattern.startsWith(\"/\") &&\n\t\t\t\t\t\t\t\t!effectivePattern.startsWith(\"**/\") &&\n\t\t\t\t\t\t\t\teffectivePattern !== \"**\"\n\t\t\t\t\t\t\t) {\n\t\t\t\t\t\t\t\tfinalPattern = `**/${effectivePattern}`;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\targs.push(\"--\", finalPattern, searchPath);\n\n\t\t\t\t\t\tconst child = spawn(fdPath, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\t\t\t\t\tconst rl = createInterface({ input: child.stdout });\n\t\t\t\t\t\tlet stderr = \"\";\n\t\t\t\t\t\tconst lines: string[] = [];\n\n\t\t\t\t\t\tstopChild = () => {\n\t\t\t\t\t\t\tif (!child.killed) {\n\t\t\t\t\t\t\t\tchild.kill();\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t};\n\n\t\t\t\t\t\tconst cleanup = () => {\n\t\t\t\t\t\t\trl.close();\n\t\t\t\t\t\t};\n\n\t\t\t\t\t\tchild.stderr?.on(\"data\", (chunk) => {\n\t\t\t\t\t\t\tstderr += chunk.toString();\n\t\t\t\t\t\t});\n\n\t\t\t\t\t\trl.on(\"line\", (line) => {\n\t\t\t\t\t\t\tlines.push(line);\n\t\t\t\t\t\t});\n\n\t\t\t\t\t\tchild.on(\"error\", (error) => {\n\t\t\t\t\t\t\tcleanup();\n\t\t\t\t\t\t\tsettle(() => reject(new Error(`Failed to run fd: ${error.message}`)));\n\t\t\t\t\t\t});\n\n\t\t\t\t\t\tchild.on(\"close\", (code) => {\n\t\t\t\t\t\t\tcleanup();\n\t\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst output = lines.join(\"\\n\");\n\t\t\t\t\t\t\tif (code !== 0) {\n\t\t\t\t\t\t\t\tconst errorMsg = stderr.trim() || `fd exited with code ${code}`;\n\t\t\t\t\t\t\t\tif (!output) {\n\t\t\t\t\t\t\t\t\tsettle(() => reject(new Error(errorMsg)));\n\t\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tconst relativized: string[] = [];\n\t\t\t\t\t\t\tfor (const rawLine of lines) {\n\t\t\t\t\t\t\t\tconst line = rawLine.replace(/\\r$/, \"\").trim();\n\t\t\t\t\t\t\t\tif (!line) continue;\n\t\t\t\t\t\t\t\tconst hadTrailingSlash = line.endsWith(\"/\") || line.endsWith(\"\\\\\");\n\t\t\t\t\t\t\t\tlet relativePath = line;\n\t\t\t\t\t\t\t\tif (line.startsWith(searchPath)) {\n\t\t\t\t\t\t\t\t\trelativePath = line.slice(searchPath.length + 1);\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\trelativePath = path.relative(searchPath, line);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tif (hadTrailingSlash && !relativePath.endsWith(\"/\")) relativePath += \"/\";\n\t\t\t\t\t\t\t\trelativized.push(toPosixPath(relativePath));\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tconst formatted = formatFindResults(relativized, effectiveLimit);\n\t\t\t\t\t\t\tsettle(() =>\n\t\t\t\t\t\t\t\tresolve({\n\t\t\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: formatted.text }],\n\t\t\t\t\t\t\t\t\tdetails: Object.keys(formatted.details).length > 0 ? formatted.details : undefined,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t});\n\t\t\t\t\t} catch (e) {\n\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst error = e instanceof Error ? e : new Error(String(e));\n\t\t\t\t\t\tsettle(() => reject(error));\n\t\t\t\t\t}\n\t\t\t\t})();\n\t\t\t});\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatFindCall(args, theme, context.cwd));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatFindResult(result as any, options, theme, context.showImages));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createFindTool(cwd: string, options?: FindToolOptions): AgentTool<typeof findSchema> {\n\treturn wrapToolDefinition(createFindToolDefinition(cwd, options));\n}\n"]}
+{"version":3,"file":"find.d.ts","sourceRoot":"","sources":["../../../src/core/tools/find.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAI3D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EACN,KAAK,iBAAiB,EAKtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,wBAAwB,CAAC;AACtF,OAAO,EAEN,KAAK,gBAAgB,EAIrB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,EAAiC,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAMrF,QAAA,MAAM,UAAU;;;;;EAQd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAItD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B,2BAA2B;IAC3B,MAAM,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7D,4EAA4E;IAC5E,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC;CACnH;AAQD,MAAM,WAAW,eAAe;IAC/B,sFAAsF;IACtF,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,+EAA+E;IAC/E,GAAG,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAC;IAC/B,qFAAqF;IACrF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACtC;AA6RD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAuQhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG","sourcesContent":["import { createInterface } from \"node:readline\";\nimport type { AgentTool } from \"@caupulican/pi-agent-core\";\nimport { Text } from \"@caupulican/pi-tui\";\nimport { spawn } from \"child_process\";\nimport path from \"path\";\nimport { type Static, Type } from \"typebox\";\nimport { keyHint } from \"../../modes/interactive/components/keybinding-hints.ts\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { ensureTool } from \"../../utils/tools-manager.ts\";\nimport type { ArtifactStore } from \"../context/context-artifacts.ts\";\nimport {\n\ttype BroadQueryTracker,\n\tbroadQueryInvalidationNote,\n\tformatArtifactNotice,\n\tnormalizeBroadQueryKey,\n\tpackToolOutput,\n} from \"../context/tool-output-packer.ts\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport {\n\tdefaultFffSearchBackend,\n\ttype FffSearchBackend,\n\ttype FffSearchResult,\n\thasGitignoreInTree,\n\trelativePathInside,\n} from \"./fff-search-backend.ts\";\nimport { pathExists, resolveToCwd } from \"./path-utils.ts\";\nimport { getTextOutput, invalidArgText, shortenPath, str } from \"./render-utils.ts\";\nimport { defaultSearchRouter, type SearchRouter } from \"./search-router.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\nimport { DEFAULT_MAX_BYTES, formatSize, type TruncationResult } from \"./truncate.ts\";\n\nfunction toPosixPath(value: string): string {\n\treturn value.split(path.sep).join(\"/\");\n}\n\nconst findSchema = Type.Object({\n\tpattern: Type.String({\n\t\tdescription:\n\t\t\t\"Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.spec.ts'. Use '.' to match all files.\",\n\t}),\n\tpath: Type.Optional(Type.String({ description: \"Directory to search in (default: current directory)\" })),\n\tlimit: Type.Optional(Type.Number({ description: \"Maximum number of results (default: 1000)\" })),\n\tignoreCase: Type.Optional(Type.Boolean({ description: \"Case-insensitive matching (default: false)\" })),\n});\n\nexport type FindToolInput = Static<typeof findSchema>;\n\nconst DEFAULT_LIMIT = 1000;\n\nexport interface FindToolDetails {\n\ttruncation?: TruncationResult;\n\tresultLimitReached?: number;\n\t/** Set only when output was packed to an artifact; see tool-output-packer.ts. */\n\tartifactId?: string;\n\t/** Set when this exact query has repeatedly produced broad/truncated results. */\n\tinvalidationCandidate?: boolean;\n}\n\n/**\n * Pluggable operations for the find tool.\n * Override these to delegate file search to remote systems (for example SSH).\n */\nexport interface FindOperations {\n\t/** Check if path exists */\n\texists: (absolutePath: string) => Promise<boolean> | boolean;\n\t/** Find files matching glob pattern. Returns relative or absolute paths. */\n\tglob: (pattern: string, cwd: string, options: { ignore: string[]; limit: number }) => Promise<string[]> | string[];\n}\n\nconst defaultFindOperations: FindOperations = {\n\texists: pathExists,\n\t// This is a placeholder. Actual fd execution happens in execute() when no custom glob is provided.\n\tglob: () => [],\n};\n\nexport interface FindToolOptions {\n\t/** Custom operations for find. Default: local filesystem plus routed FFF/fd search */\n\toperations?: FindOperations;\n\t/** FFF backend for resident indexed search. Set false to force fd fallback. */\n\tfff?: FffSearchBackend | false;\n\t/** Pure router that selects FFF or fd from request filters and environment facts. */\n\tsearchRouter?: SearchRouter;\n\t/**\n\t * Opt-in artifact store for first-capture-then-bound output packing (Phase 3). When\n\t * omitted (the default), behavior is byte-for-byte unchanged from before this option\n\t * existed: output is truncated the same way, just never artifact-backed.\n\t */\n\tartifactStore?: ArtifactStore;\n\t/** Opt-in tracker for repeated-broad-query \"do not repeat\" signals. Also default-off. */\n\tbroadQueryTracker?: BroadQueryTracker;\n}\n\nfunction formatFindCall(\n\targs: { pattern: string; path?: string; limit?: number } | undefined,\n\ttheme: Theme,\n\tcwd: string,\n): string {\n\tconst pattern = str(args?.pattern);\n\tconst rawPath = str(args?.path);\n\tconst path = rawPath !== null ? shortenPath(rawPath || \".\", cwd) : null;\n\tconst limit = args?.limit;\n\tconst invalidArg = invalidArgText(theme);\n\tlet text =\n\t\ttheme.fg(\"toolTitle\", theme.bold(\"find\")) +\n\t\t\" \" +\n\t\t(pattern === null ? invalidArg : theme.fg(\"accent\", pattern || \"\")) +\n\t\ttheme.fg(\"toolOutput\", ` in ${path === null ? invalidArg : path}`);\n\tif (limit !== undefined) {\n\t\ttext += theme.fg(\"toolOutput\", ` (limit ${limit})`);\n\t}\n\treturn text;\n}\n\nfunction formatFindResult(\n\tresult: {\n\t\tcontent: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;\n\t\tdetails?: FindToolDetails;\n\t},\n\toptions: ToolRenderResultOptions,\n\ttheme: Theme,\n\tshowImages: boolean,\n): string {\n\tconst output = getTextOutput(result, showImages).trim();\n\tlet text = \"\";\n\tif (output) {\n\t\tconst lines = output.split(\"\\n\");\n\t\tconst maxLines = options.expanded ? lines.length : 20;\n\t\tconst displayLines = lines.slice(0, maxLines);\n\t\tconst remaining = lines.length - maxLines;\n\t\ttext += `\\n${displayLines.map((line) => theme.fg(\"toolOutput\", line)).join(\"\\n\")}`;\n\t\tif (remaining > 0) {\n\t\t\ttext += `${theme.fg(\"muted\", `\\n... (${remaining} more lines,`)} ${keyHint(\"app.tools.expand\", \"to expand\")})`;\n\t\t}\n\t}\n\n\tconst resultLimit = result.details?.resultLimitReached;\n\tconst truncation = result.details?.truncation;\n\tif (resultLimit || truncation?.truncated) {\n\t\tconst warnings: string[] = [];\n\t\tif (resultLimit) warnings.push(`${resultLimit} results limit`);\n\t\tif (truncation?.truncated) warnings.push(`${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit`);\n\t\ttext += `\\n${theme.fg(\"warning\", `[Truncated: ${warnings.join(\", \")}]`)}`;\n\t}\n\treturn text;\n}\n\nfunction hasGlobSyntax(pattern: string): boolean {\n\treturn pattern === \".\" || /[*?[{]/.test(pattern);\n}\n\nfunction fffQueryParts(parts: string[]): string {\n\treturn parts.filter(Boolean).join(\" \");\n}\n\nfunction toSearchRelative(repoRelativePath: string, searchPathRelativeToCwd: string): string | undefined {\n\tif (!searchPathRelativeToCwd) return repoRelativePath;\n\tconst prefix = `${searchPathRelativeToCwd}/`;\n\tif (!repoRelativePath.startsWith(prefix)) return undefined;\n\treturn repoRelativePath.slice(prefix.length);\n}\n\nfunction fffGlobPattern(pattern: string, searchPathRelativeToCwd: string): string {\n\tconst effectivePattern = pattern === \".\" ? \"**/*\" : pattern;\n\tif (!searchPathRelativeToCwd) {\n\t\tif (effectivePattern.includes(\"/\") || effectivePattern.startsWith(\"**/\")) return effectivePattern;\n\t\treturn `**/${effectivePattern}`;\n\t}\n\tif (effectivePattern === \"**\" || effectivePattern === \"**/*\") return `${searchPathRelativeToCwd}/**/*`;\n\tif (effectivePattern.includes(\"/\")) return `${searchPathRelativeToCwd}/${effectivePattern}`;\n\treturn `${searchPathRelativeToCwd}/**/${effectivePattern}`;\n}\n\ninterface FindPackingOptions {\n\ttoolCallId: string;\n\tartifactStore?: ArtifactStore;\n\tbroadQueryTracker?: BroadQueryTracker;\n\tpattern: string;\n\trawPath?: string;\n}\n\nfunction fffSearchOutput(\n\tresult: FffSearchResult,\n\tsearchPathRelativeToCwd: string,\n\teffectiveLimit: number,\n\tpacking: FindPackingOptions,\n) {\n\tconst relativized = result.items\n\t\t.map((item) => toSearchRelative(item.relativePath, searchPathRelativeToCwd))\n\t\t.filter((item): item is string => Boolean(item));\n\treturn formatFindResults(relativized, effectiveLimit, packing);\n}\n\nasync function tryFffFind(options: {\n\tbackend: FffSearchBackend;\n\trouter: SearchRouter;\n\tcwd: string;\n\tsearchPath: string;\n\tpattern: string;\n\tignoreCase?: boolean;\n\teffectiveLimit: number;\n\ttoolCallId: string;\n\tartifactStore?: ArtifactStore;\n\tbroadQueryTracker?: BroadQueryTracker;\n\trawPath?: string;\n}): Promise<{ text: string; details: FindToolDetails } | undefined> {\n\tif (!(await pathExists(options.searchPath))) return undefined;\n\n\tconst searchPathRelativeToCwd = relativePathInside(options.cwd, options.searchPath);\n\tconst glob = hasGlobSyntax(options.pattern);\n\tconst baseRoute = options.router.route({\n\t\ttool: \"find\",\n\t\tglob,\n\t\tignoreCase: Boolean(options.ignoreCase),\n\t\tlimit: options.effectiveLimit,\n\t\tfinderAvailable: true,\n\t\tpathResolvable: searchPathRelativeToCwd !== undefined,\n\t\tgitignoreInTree: false,\n\t});\n\tif (baseRoute.backend !== \"fff\") return undefined;\n\tif (searchPathRelativeToCwd === undefined) return undefined;\n\n\tconst gitignoreInTree = await hasGitignoreInTree(options.searchPath);\n\tconst semanticRoute = options.router.route({\n\t\ttool: \"find\",\n\t\tglob,\n\t\tignoreCase: Boolean(options.ignoreCase),\n\t\tlimit: options.effectiveLimit,\n\t\tfinderAvailable: true,\n\t\tpathResolvable: true,\n\t\tgitignoreInTree,\n\t});\n\tif (semanticRoute.backend !== \"fff\") return undefined;\n\n\tconst finder = await options.backend.getFinder(options.cwd);\n\tconst finderRoute = options.router.route({\n\t\ttool: \"find\",\n\t\tglob,\n\t\tignoreCase: Boolean(options.ignoreCase),\n\t\tlimit: options.effectiveLimit,\n\t\tfinderAvailable: Boolean(finder),\n\t\tpathResolvable: true,\n\t\tgitignoreInTree: false,\n\t});\n\tif (!finder || finderRoute.backend !== \"fff\") return undefined;\n\n\tconst packing: FindPackingOptions = {\n\t\ttoolCallId: options.toolCallId,\n\t\tartifactStore: options.artifactStore,\n\t\tbroadQueryTracker: options.broadQueryTracker,\n\t\tpattern: options.pattern,\n\t\trawPath: options.rawPath,\n\t};\n\n\tif (glob) {\n\t\tconst result = finder.glob(fffGlobPattern(options.pattern, searchPathRelativeToCwd), {\n\t\t\tpageSize: options.effectiveLimit,\n\t\t});\n\t\treturn result.ok\n\t\t\t? fffSearchOutput(result.value, searchPathRelativeToCwd, options.effectiveLimit, packing)\n\t\t\t: undefined;\n\t}\n\n\tconst pathConstraint = searchPathRelativeToCwd ? `${searchPathRelativeToCwd}/` : \"\";\n\tconst result = finder.fileSearch(fffQueryParts([pathConstraint, options.pattern]), {\n\t\tpageSize: options.effectiveLimit,\n\t});\n\treturn result.ok\n\t\t? fffSearchOutput(result.value, searchPathRelativeToCwd, options.effectiveLimit, packing)\n\t\t: undefined;\n}\n\nfunction formatFindResults(\n\trelativized: string[],\n\teffectiveLimit: number,\n\tpacking: FindPackingOptions,\n): { text: string; details: FindToolDetails } {\n\tif (relativized.length === 0) {\n\t\treturn { text: \"No files found matching pattern\", details: {} };\n\t}\n\n\tconst dirGroups = new Map<string, string[]>();\n\tconst extCounts = new Map<string, number>();\n\n\tfor (const p of relativized) {\n\t\tconst dir = path.dirname(p);\n\t\tconst base = path.basename(p);\n\t\tconst dirKey = dir === \".\" ? \"./\" : `${dir}/`;\n\t\tif (!dirGroups.has(dirKey)) {\n\t\t\tdirGroups.set(dirKey, []);\n\t\t}\n\t\tdirGroups.get(dirKey)!.push(base);\n\n\t\tconst ext = path.extname(p).toLowerCase() || \"(no extension)\";\n\t\textCounts.set(ext, (extCounts.get(ext) || 0) + 1);\n\t}\n\n\tconst sortedDirs = Array.from(dirGroups.keys()).sort((a, b) => a.localeCompare(b));\n\tconst formattedLines: string[] = [];\n\tfor (const dir of sortedDirs) {\n\t\tformattedLines.push(dir);\n\t\tconst files = dirGroups.get(dir)!;\n\t\tfiles.sort((a, b) => a.localeCompare(b));\n\t\tfor (const file of files) {\n\t\t\tformattedLines.push(`  ${file}`);\n\t\t}\n\t}\n\n\tconst extSummaryParts = Array.from(extCounts.entries())\n\t\t.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))\n\t\t.map(([ext, count]) => `${ext}: ${count}`);\n\tconst extSummary = `Extensions: ${extSummaryParts.join(\", \")}`;\n\n\tconst resultLimitReached = relativized.length >= effectiveLimit;\n\tconst rawOutput = formattedLines.join(\"\\n\");\n\t// Measure -> pack (artifact-backed if oversized and a store was provided) -> notices.\n\tconst packed = packToolOutput(\n\t\t{\n\t\t\ttoolName: \"find\",\n\t\t\tpath: packing.rawPath,\n\t\t\trawContent: rawOutput,\n\t\t\t// No line limit here because the result limit already caps rows; only the byte\n\t\t\t// cap should apply, matching the pre-Slice-B truncateHead call exactly.\n\t\t\ttruncation: { maxLines: Number.MAX_SAFE_INTEGER },\n\t\t},\n\t\tpacking.artifactStore,\n\t\tpacking.toolCallId,\n\t);\n\tlet resultOutput = packed.content;\n\tconst details: FindToolDetails = {};\n\tconst notices: string[] = [];\n\tif (packed.artifactId) {\n\t\tnotices.push(formatArtifactNotice(packed.artifactId));\n\t\tdetails.artifactId = packed.artifactId;\n\t}\n\tif (resultLimitReached) {\n\t\tnotices.push(\n\t\t\t`${effectiveLimit} results limit reached. Use limit=${effectiveLimit * 2} for more, or narrow path/pattern`,\n\t\t);\n\t\tdetails.resultLimitReached = effectiveLimit;\n\t}\n\tif (packed.truncation.truncated) {\n\t\tnotices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);\n\t\t// Drop the duplicated bounded-preview text: it's already in the message's own\n\t\t// content, and re-including it here can push `details` past\n\t\t// MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES (message-retention.ts), which replaces\n\t\t// the *entire* details object with a stub -- silently losing artifactId and every\n\t\t// other field alongside it. This is load-bearing beyond just the retention budget:\n\t\t// agent-session.ts's _releaseGcPackedArtifactReferences() reads artifactId back off\n\t\t// this same canonical message at eviction time (potentially many turns later), so\n\t\t// keeping `details` small here is what keeps that release path working at all. If\n\t\t// this field ever grows a large addition again, add a regression proving artifactId\n\t\t// survives compactToolResultDetailsForRetention (see\n\t\t// test/suite/agent-session-artifact-lifecycle.test.ts), not just a details-size check.\n\t\tdetails.truncation = { ...packed.truncation, content: \"\" };\n\t}\n\tif (resultLimitReached || packed.truncation.truncated) {\n\t\tconst note = broadQueryInvalidationNote(\n\t\t\tpacking.broadQueryTracker,\n\t\t\tnormalizeBroadQueryKey({ toolName: \"find\", pattern: packing.pattern, path: packing.rawPath }),\n\t\t\t`find \"${packing.pattern}\" in ${packing.rawPath ?? \".\"}`,\n\t\t);\n\t\tif (note) {\n\t\t\tnotices.push(note);\n\t\t\tdetails.invalidationCandidate = true;\n\t\t}\n\t}\n\tif (relativized.length > 0) {\n\t\tresultOutput += `\\n\\n[Summary - ${extSummary}]`;\n\t}\n\tif (notices.length > 0) {\n\t\tresultOutput += `\\n\\n[${notices.join(\". \")}]`;\n\t}\n\treturn { text: resultOutput, details };\n}\n\nexport function createFindToolDefinition(\n\tcwd: string,\n\toptions?: FindToolOptions,\n): ToolDefinition<typeof findSchema, FindToolDetails | undefined> {\n\tconst customOps = options?.operations;\n\tconst fffBackend = options?.fff === false ? undefined : (options?.fff ?? defaultFffSearchBackend);\n\tconst searchRouter = options?.searchRouter ?? defaultSearchRouter;\n\tconst artifactStore = options?.artifactStore;\n\tconst broadQueryTracker = options?.broadQueryTracker;\n\treturn {\n\t\tname: \"find\",\n\t\tlabel: \"find\",\n\t\tdescription: `Search for files by glob pattern. Returns matching file paths relative to the search directory. Respects .gitignore. Output is truncated to ${DEFAULT_LIMIT} results or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,\n\t\tpromptSnippet: \"Find files by glob pattern (respects .gitignore)\",\n\t\tparameters: findSchema,\n\t\ttoolGroup: \"explore\",\n\t\tasync execute(\n\t\t\ttoolCallId,\n\t\t\t{\n\t\t\t\tpattern,\n\t\t\t\tpath: searchDir,\n\t\t\t\tlimit,\n\t\t\t\tignoreCase,\n\t\t\t}: { pattern: string; path?: string; limit?: number; ignoreCase?: boolean },\n\t\t\tsignal?: AbortSignal,\n\t\t\t_onUpdate?,\n\t\t\t_ctx?,\n\t\t) {\n\t\t\treturn new Promise((resolve, reject) => {\n\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\treject(new Error(\"Operation aborted\"));\n\t\t\t\t\treturn;\n\t\t\t\t}\n\n\t\t\t\tlet settled = false;\n\t\t\t\tlet stopChild: (() => void) | undefined;\n\t\t\t\tconst settle = (fn: () => void) => {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t\t\tstopChild = undefined;\n\t\t\t\t\tfn();\n\t\t\t\t};\n\t\t\t\tconst onAbort = () => {\n\t\t\t\t\tstopChild?.();\n\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t};\n\t\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\n\t\t\t\t(async () => {\n\t\t\t\t\ttry {\n\t\t\t\t\t\tconst searchPath = resolveToCwd(searchDir || \".\", cwd);\n\t\t\t\t\t\tconst effectiveLimit = limit ?? DEFAULT_LIMIT;\n\t\t\t\t\t\tconst ops = customOps ?? defaultFindOperations;\n\n\t\t\t\t\t\tlet effectivePattern = pattern;\n\t\t\t\t\t\tif (pattern === \".\") {\n\t\t\t\t\t\t\teffectivePattern = \"**/*\";\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tif (!customOps && fffBackend) {\n\t\t\t\t\t\t\tconst fffResult = await tryFffFind({\n\t\t\t\t\t\t\t\tbackend: fffBackend,\n\t\t\t\t\t\t\t\trouter: searchRouter,\n\t\t\t\t\t\t\t\tcwd,\n\t\t\t\t\t\t\t\tsearchPath,\n\t\t\t\t\t\t\t\tpattern: effectivePattern,\n\t\t\t\t\t\t\t\tignoreCase,\n\t\t\t\t\t\t\t\teffectiveLimit,\n\t\t\t\t\t\t\t\ttoolCallId,\n\t\t\t\t\t\t\t\tartifactStore,\n\t\t\t\t\t\t\t\tbroadQueryTracker,\n\t\t\t\t\t\t\t\trawPath: searchDir,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tif (fffResult) {\n\t\t\t\t\t\t\t\tsettle(() =>\n\t\t\t\t\t\t\t\t\tresolve({\n\t\t\t\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: fffResult.text }],\n\t\t\t\t\t\t\t\t\t\tdetails: Object.keys(fffResult.details).length > 0 ? fffResult.details : undefined,\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// If custom operations provide glob(), use that instead of fd.\n\t\t\t\t\t\tif (customOps?.glob) {\n\t\t\t\t\t\t\tif (!(await ops.exists(searchPath))) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(`Path not found: ${searchPath}`)));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst results = await ops.glob(effectivePattern, searchPath, {\n\t\t\t\t\t\t\t\tignore: [\"**/node_modules/**\", \"**/.git/**\"],\n\t\t\t\t\t\t\t\tlimit: effectiveLimit,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\t// Relativize paths against the search root for stable output.\n\t\t\t\t\t\t\tconst relativized = results.map((p) => {\n\t\t\t\t\t\t\t\tif (p.startsWith(searchPath)) return toPosixPath(p.slice(searchPath.length + 1));\n\t\t\t\t\t\t\t\treturn toPosixPath(path.relative(searchPath, p));\n\t\t\t\t\t\t\t});\n\n\t\t\t\t\t\t\tconst formatted = formatFindResults(relativized, effectiveLimit, {\n\t\t\t\t\t\t\t\ttoolCallId,\n\t\t\t\t\t\t\t\tartifactStore,\n\t\t\t\t\t\t\t\tbroadQueryTracker,\n\t\t\t\t\t\t\t\tpattern: effectivePattern,\n\t\t\t\t\t\t\t\trawPath: searchDir,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tsettle(() =>\n\t\t\t\t\t\t\t\tresolve({\n\t\t\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: formatted.text }],\n\t\t\t\t\t\t\t\t\tdetails: Object.keys(formatted.details).length > 0 ? formatted.details : undefined,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Default implementation uses fd.\n\t\t\t\t\t\tconst fdPath = await ensureTool(\"fd\", true);\n\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tif (!fdPath) {\n\t\t\t\t\t\t\tsettle(() => reject(new Error(\"fd is not available and could not be downloaded\")));\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// Build fd arguments. --no-require-git makes fd apply hierarchical .gitignore\n\t\t\t\t\t\t// semantics whether or not the search path is inside a git repository, without\n\t\t\t\t\t\t// leaking sibling-directory rules the way --ignore-file (a global source) would.\n\t\t\t\t\t\tconst args: string[] = [\n\t\t\t\t\t\t\t\"--glob\",\n\t\t\t\t\t\t\t\"--color=never\",\n\t\t\t\t\t\t\t\"--hidden\",\n\t\t\t\t\t\t\t\"--no-require-git\",\n\t\t\t\t\t\t\t\"--max-results\",\n\t\t\t\t\t\t\tString(effectiveLimit),\n\t\t\t\t\t\t];\n\t\t\t\t\t\tif (ignoreCase) {\n\t\t\t\t\t\t\targs.push(\"--ignore-case\");\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\t// fd --glob matches against the basename unless --full-path is set; in --full-path\n\t\t\t\t\t\t// mode it matches against the absolute candidate path, so a path-containing\n\t\t\t\t\t\t// pattern like 'src/**/*.spec.ts' needs a leading '**/' to match anything.\n\t\t\t\t\t\tlet finalPattern = effectivePattern;\n\t\t\t\t\t\tif (effectivePattern.includes(\"/\")) {\n\t\t\t\t\t\t\targs.push(\"--full-path\");\n\t\t\t\t\t\t\tif (\n\t\t\t\t\t\t\t\t!effectivePattern.startsWith(\"/\") &&\n\t\t\t\t\t\t\t\t!effectivePattern.startsWith(\"**/\") &&\n\t\t\t\t\t\t\t\teffectivePattern !== \"**\"\n\t\t\t\t\t\t\t) {\n\t\t\t\t\t\t\t\tfinalPattern = `**/${effectivePattern}`;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t\targs.push(\"--\", finalPattern, searchPath);\n\n\t\t\t\t\t\tconst child = spawn(fdPath, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\t\t\t\t\tconst rl = createInterface({ input: child.stdout });\n\t\t\t\t\t\tlet stderr = \"\";\n\t\t\t\t\t\tconst lines: string[] = [];\n\n\t\t\t\t\t\tstopChild = () => {\n\t\t\t\t\t\t\tif (!child.killed) {\n\t\t\t\t\t\t\t\tchild.kill();\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t};\n\n\t\t\t\t\t\tconst cleanup = () => {\n\t\t\t\t\t\t\trl.close();\n\t\t\t\t\t\t};\n\n\t\t\t\t\t\tchild.stderr?.on(\"data\", (chunk) => {\n\t\t\t\t\t\t\tstderr += chunk.toString();\n\t\t\t\t\t\t});\n\n\t\t\t\t\t\trl.on(\"line\", (line) => {\n\t\t\t\t\t\t\tlines.push(line);\n\t\t\t\t\t\t});\n\n\t\t\t\t\t\tchild.on(\"error\", (error) => {\n\t\t\t\t\t\t\tcleanup();\n\t\t\t\t\t\t\tsettle(() => reject(new Error(`Failed to run fd: ${error.message}`)));\n\t\t\t\t\t\t});\n\n\t\t\t\t\t\tchild.on(\"close\", (code) => {\n\t\t\t\t\t\t\tcleanup();\n\t\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\tconst output = lines.join(\"\\n\");\n\t\t\t\t\t\t\tif (code !== 0) {\n\t\t\t\t\t\t\t\tconst errorMsg = stderr.trim() || `fd exited with code ${code}`;\n\t\t\t\t\t\t\t\tif (!output) {\n\t\t\t\t\t\t\t\t\tsettle(() => reject(new Error(errorMsg)));\n\t\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tconst relativized: string[] = [];\n\t\t\t\t\t\t\tfor (const rawLine of lines) {\n\t\t\t\t\t\t\t\tconst line = rawLine.replace(/\\r$/, \"\").trim();\n\t\t\t\t\t\t\t\tif (!line) continue;\n\t\t\t\t\t\t\t\tconst hadTrailingSlash = line.endsWith(\"/\") || line.endsWith(\"\\\\\");\n\t\t\t\t\t\t\t\tlet relativePath = line;\n\t\t\t\t\t\t\t\tif (line.startsWith(searchPath)) {\n\t\t\t\t\t\t\t\t\trelativePath = line.slice(searchPath.length + 1);\n\t\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\t\trelativePath = path.relative(searchPath, line);\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t\tif (hadTrailingSlash && !relativePath.endsWith(\"/\")) relativePath += \"/\";\n\t\t\t\t\t\t\t\trelativized.push(toPosixPath(relativePath));\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tconst formatted = formatFindResults(relativized, effectiveLimit, {\n\t\t\t\t\t\t\t\ttoolCallId,\n\t\t\t\t\t\t\t\tartifactStore,\n\t\t\t\t\t\t\t\tbroadQueryTracker,\n\t\t\t\t\t\t\t\tpattern: effectivePattern,\n\t\t\t\t\t\t\t\trawPath: searchDir,\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tsettle(() =>\n\t\t\t\t\t\t\t\tresolve({\n\t\t\t\t\t\t\t\t\tcontent: [{ type: \"text\", text: formatted.text }],\n\t\t\t\t\t\t\t\t\tdetails: Object.keys(formatted.details).length > 0 ? formatted.details : undefined,\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t});\n\t\t\t\t\t} catch (e) {\n\t\t\t\t\t\tif (signal?.aborted) {\n\t\t\t\t\t\t\tsettle(() => reject(new Error(\"Operation aborted\")));\n\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tconst error = e instanceof Error ? e : new Error(String(e));\n\t\t\t\t\t\tsettle(() => reject(error));\n\t\t\t\t\t}\n\t\t\t\t})();\n\t\t\t});\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatFindCall(args, theme, context.cwd));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatFindResult(result as any, options, theme, context.showImages));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createFindTool(cwd: string, options?: FindToolOptions): AgentTool<typeof findSchema> {\n\treturn wrapToolDefinition(createFindToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/find.js

@@ -5,10 +5,13 @@ import path from "path";
 import { Type } from "typebox";
 import { keyHint } from "../../modes/interactive/components/keybinding-hints.js";
 import { ensureTool } from "../../utils/tools-manager.js";
+import { broadQueryInvalidationNote, formatArtifactNotice, normalizeBroadQueryKey, packToolOutput, } from "../context/tool-output-packer.js";
+import { defaultFffSearchBackend, hasGitignoreInTree, relativePathInside, } from "./fff-search-backend.js";
 import { pathExists, resolveToCwd } from "./path-utils.js";
 import { getTextOutput, invalidArgText, shortenPath, str } from "./render-utils.js";
+import { defaultSearchRouter } from "./search-router.js";
 import { wrapToolDefinition } from "./tool-definition-wrapper.js";
-import { DEFAULT_MAX_BYTES, formatSize, truncateHead } from "./truncate.js";
+import { DEFAULT_MAX_BYTES, formatSize } from "./truncate.js";
 function toPosixPath(value) {
     return value.split(path.sep).join("/");
 }
@@ -66,7 +69,105 @@ function formatFindResult(result, options, theme, showImages) {
     }
     return text;
 }
-function formatFindResults(relativized, effectiveLimit) {
+function hasGlobSyntax(pattern) {
+    return pattern === "." || /[*?[{]/.test(pattern);
+}
+function fffQueryParts(parts) {
+    return parts.filter(Boolean).join(" ");
+}
+function toSearchRelative(repoRelativePath, searchPathRelativeToCwd) {
+    if (!searchPathRelativeToCwd)
+        return repoRelativePath;
+    const prefix = `${searchPathRelativeToCwd}/`;
+    if (!repoRelativePath.startsWith(prefix))
+        return undefined;
+    return repoRelativePath.slice(prefix.length);
+}
+function fffGlobPattern(pattern, searchPathRelativeToCwd) {
+    const effectivePattern = pattern === "." ? "**/*" : pattern;
+    if (!searchPathRelativeToCwd) {
+        if (effectivePattern.includes("/") || effectivePattern.startsWith("**/"))
+            return effectivePattern;
+        return `**/${effectivePattern}`;
+    }
+    if (effectivePattern === "**" || effectivePattern === "**/*")
+        return `${searchPathRelativeToCwd}/**/*`;
+    if (effectivePattern.includes("/"))
+        return `${searchPathRelativeToCwd}/${effectivePattern}`;
+    return `${searchPathRelativeToCwd}/**/${effectivePattern}`;
+}
+function fffSearchOutput(result, searchPathRelativeToCwd, effectiveLimit, packing) {
+    const relativized = result.items
+        .map((item) => toSearchRelative(item.relativePath, searchPathRelativeToCwd))
+        .filter((item) => Boolean(item));
+    return formatFindResults(relativized, effectiveLimit, packing);
+}
+async function tryFffFind(options) {
+    if (!(await pathExists(options.searchPath)))
+        return undefined;
+    const searchPathRelativeToCwd = relativePathInside(options.cwd, options.searchPath);
+    const glob = hasGlobSyntax(options.pattern);
+    const baseRoute = options.router.route({
+        tool: "find",
+        glob,
+        ignoreCase: Boolean(options.ignoreCase),
+        limit: options.effectiveLimit,
+        finderAvailable: true,
+        pathResolvable: searchPathRelativeToCwd !== undefined,
+        gitignoreInTree: false,
+    });
+    if (baseRoute.backend !== "fff")
+        return undefined;
+    if (searchPathRelativeToCwd === undefined)
+        return undefined;
+    const gitignoreInTree = await hasGitignoreInTree(options.searchPath);
+    const semanticRoute = options.router.route({
+        tool: "find",
+        glob,
+        ignoreCase: Boolean(options.ignoreCase),
+        limit: options.effectiveLimit,
+        finderAvailable: true,
+        pathResolvable: true,
+        gitignoreInTree,
+    });
+    if (semanticRoute.backend !== "fff")
+        return undefined;
+    const finder = await options.backend.getFinder(options.cwd);
+    const finderRoute = options.router.route({
+        tool: "find",
+        glob,
+        ignoreCase: Boolean(options.ignoreCase),
+        limit: options.effectiveLimit,
+        finderAvailable: Boolean(finder),
+        pathResolvable: true,
+        gitignoreInTree: false,
+    });
+    if (!finder || finderRoute.backend !== "fff")
+        return undefined;
+    const packing = {
+        toolCallId: options.toolCallId,
+        artifactStore: options.artifactStore,
+        broadQueryTracker: options.broadQueryTracker,
+        pattern: options.pattern,
+        rawPath: options.rawPath,
+    };
+    if (glob) {
+        const result = finder.glob(fffGlobPattern(options.pattern, searchPathRelativeToCwd), {
+            pageSize: options.effectiveLimit,
+        });
+        return result.ok
+            ? fffSearchOutput(result.value, searchPathRelativeToCwd, options.effectiveLimit, packing)
+            : undefined;
+    }
+    const pathConstraint = searchPathRelativeToCwd ? `${searchPathRelativeToCwd}/` : "";
+    const result = finder.fileSearch(fffQueryParts([pathConstraint, options.pattern]), {
+        pageSize: options.effectiveLimit,
+    });
+    return result.ok
+        ? fffSearchOutput(result.value, searchPathRelativeToCwd, options.effectiveLimit, packing)
+        : undefined;
+}
+function formatFindResults(relativized, effectiveLimit, packing) {
     if (relativized.length === 0) {
         return { text: "No files found matching pattern", details: {} };
     }
@@ -99,17 +200,47 @@ function formatFindResults(relativized, effectiveLimit) {
     const extSummary = `Extensions: ${extSummaryParts.join(", ")}`;
     const resultLimitReached = relativized.length >= effectiveLimit;
     const rawOutput = formattedLines.join("\n");
-    const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
-    let resultOutput = truncation.content;
+    // Measure -> pack (artifact-backed if oversized and a store was provided) -> notices.
+    const packed = packToolOutput({
+        toolName: "find",
+        path: packing.rawPath,
+        rawContent: rawOutput,
+        // No line limit here because the result limit already caps rows; only the byte
+        // cap should apply, matching the pre-Slice-B truncateHead call exactly.
+        truncation: { maxLines: Number.MAX_SAFE_INTEGER },
+    }, packing.artifactStore, packing.toolCallId);
+    let resultOutput = packed.content;
     const details = {};
     const notices = [];
+    if (packed.artifactId) {
+        notices.push(formatArtifactNotice(packed.artifactId));
+        details.artifactId = packed.artifactId;
+    }
     if (resultLimitReached) {
-        notices.push(`${effectiveLimit} results limit reached`);
+        notices.push(`${effectiveLimit} results limit reached. Use limit=${effectiveLimit * 2} for more, or narrow path/pattern`);
         details.resultLimitReached = effectiveLimit;
     }
-    if (truncation.truncated) {
+    if (packed.truncation.truncated) {
         notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
-        details.truncation = truncation;
+        // Drop the duplicated bounded-preview text: it's already in the message's own
+        // content, and re-including it here can push `details` past
+        // MAX_RETAINED_TOOL_RESULT_DETAILS_BYTES (message-retention.ts), which replaces
+        // the *entire* details object with a stub -- silently losing artifactId and every
+        // other field alongside it. This is load-bearing beyond just the retention budget:
+        // agent-session.ts's _releaseGcPackedArtifactReferences() reads artifactId back off
+        // this same canonical message at eviction time (potentially many turns later), so
+        // keeping `details` small here is what keeps that release path working at all. If
+        // this field ever grows a large addition again, add a regression proving artifactId
+        // survives compactToolResultDetailsForRetention (see
+        // test/suite/agent-session-artifact-lifecycle.test.ts), not just a details-size check.
+        details.truncation = { ...packed.truncation, content: "" };
+    }
+    if (resultLimitReached || packed.truncation.truncated) {
+        const note = broadQueryInvalidationNote(packing.broadQueryTracker, normalizeBroadQueryKey({ toolName: "find", pattern: packing.pattern, path: packing.rawPath }), `find "${packing.pattern}" in ${packing.rawPath ?? "."}`);
+        if (note) {
+            notices.push(note);
+            details.invalidationCandidate = true;
+        }
     }
     if (relativized.length > 0) {
         resultOutput += `\n\n[Summary - ${extSummary}]`;
@@ -121,6 +252,10 @@ function formatFindResults(relativized, effectiveLimit) {
 }
 export function createFindToolDefinition(cwd, options) {
     const customOps = options?.operations;
+    const fffBackend = options?.fff === false ? undefined : (options?.fff ?? defaultFffSearchBackend);
+    const searchRouter = options?.searchRouter ?? defaultSearchRouter;
+    const artifactStore = options?.artifactStore;
+    const broadQueryTracker = options?.broadQueryTracker;
     return {
         name: "find",
         label: "find",
@@ -128,7 +263,7 @@ export function createFindToolDefinition(cwd, options) {
         promptSnippet: "Find files by glob pattern (respects .gitignore)",
         parameters: findSchema,
         toolGroup: "explore",
-        async execute(_toolCallId, { pattern, path: searchDir, limit, ignoreCase, }, signal, _onUpdate, _ctx) {
+        async execute(toolCallId, { pattern, path: searchDir, limit, ignoreCase, }, signal, _onUpdate, _ctx) {
             return new Promise((resolve, reject) => {
                 if (signal?.aborted) {
                     reject(new Error("Operation aborted"));
@@ -158,6 +293,32 @@ export function createFindToolDefinition(cwd, options) {
                         if (pattern === ".") {
                             effectivePattern = "**/*";
                         }
+                        if (!customOps && fffBackend) {
+                            const fffResult = await tryFffFind({
+                                backend: fffBackend,
+                                router: searchRouter,
+                                cwd,
+                                searchPath,
+                                pattern: effectivePattern,
+                                ignoreCase,
+                                effectiveLimit,
+                                toolCallId,
+                                artifactStore,
+                                broadQueryTracker,
+                                rawPath: searchDir,
+                            });
+                            if (signal?.aborted) {
+                                settle(() => reject(new Error("Operation aborted")));
+                                return;
+                            }
+                            if (fffResult) {
+                                settle(() => resolve({
+                                    content: [{ type: "text", text: fffResult.text }],
+                                    details: Object.keys(fffResult.details).length > 0 ? fffResult.details : undefined,
+                                }));
+                                return;
+                            }
+                        }
                         // If custom operations provide glob(), use that instead of fd.
                         if (customOps?.glob) {
                             if (!(await ops.exists(searchPath))) {
@@ -182,7 +343,13 @@ export function createFindToolDefinition(cwd, options) {
                                     return toPosixPath(p.slice(searchPath.length + 1));
                                 return toPosixPath(path.relative(searchPath, p));
                             });
-                            const formatted = formatFindResults(relativized, effectiveLimit);
+                            const formatted = formatFindResults(relativized, effectiveLimit, {
+                                toolCallId,
+                                artifactStore,
+                                broadQueryTracker,
+                                pattern: effectivePattern,
+                                rawPath: searchDir,
+                            });
                             settle(() => resolve({
                                 content: [{ type: "text", text: formatted.text }],
                                 details: Object.keys(formatted.details).length > 0 ? formatted.details : undefined,
@@ -279,7 +446,13 @@ export function createFindToolDefinition(cwd, options) {
                                     relativePath += "/";
                                 relativized.push(toPosixPath(relativePath));
                             }
-                            const formatted = formatFindResults(relativized, effectiveLimit);
+                            const formatted = formatFindResults(relativized, effectiveLimit, {
+                                toolCallId,
+                                artifactStore,
+                                broadQueryTracker,
+                                pattern: effectivePattern,
+                                rawPath: searchDir,
+                            });
                             settle(() => resolve({
                                 content: [{ type: "text", text: formatted.text }],
                                 details: Object.keys(formatted.details).length > 0 ? formatted.details : undefined,