@hassangameryt/freeflow 0.2.0 → 0.3.0

package/{plugins/freeflow/router/dist/retrieve.js → router/dist/tools/search.js}

@@ -1,11 +1,16 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { buildBoundedEdgeChunks, buildBoundedExcerpt } from "./bounded-evidence.js";
-import { findBestLineForQuery, searchRepoEvidenceCandidates, } from "./evidence-search.js";
-import { resolveExactLineRange } from "./line-ranges.js";
-import { collectRepoTextFileRefs, resolveRepoPath } from "./repo-traversal.js";
-import { createVault, readOutputText, readVaultRecord } from "./vault.js";
+import { buildBoundedEdgeChunks, buildBoundedExcerpt } from "../evidence/bounded-evidence.js";
+import { findBestLineForQuery, searchRepoEvidenceCandidates, } from "../evidence/evidence-search.js";
+import { resolveExactLineRange } from "../evidence/line-ranges.js";
+import { collectRepoTextFileRefs, resolveRepoPath } from "../repo/repo-traversal.js";
+import { createLocalVaultIndex } from "../vault/vault-index.js";
+import { createVault, readOutputText, readVaultRecord } from "../vault/vault.js";
+export const FREEFLOW_SEARCH_ACTIONS = ["query", "locate", "get", "retrieve", "expand", "explain", "transform"];
+export function searchActionForRetrievalAction(action) {
+    return action;
+}
 const DEFAULT_CONTEXT_LINES = 2;
 const DEFAULT_QUERY_TOP_K = 1;
 const DEFAULT_LOCATE_TOP_K = 5;
@@ -29,7 +34,7 @@ const BOUNDED_EVIDENCE_CAPS = {
     expandLines80MaxLines: EXPAND_LINES_80_MAX_LINES,
     exactChunkMaxBytes: EXACT_CHUNK_MAX_BYTES,
 };
-export async function freeflowRetrieve(options) {
+export async function freeflowSearch(options) {
     const preserve = options.preserve ?? "important";
     try {
         if (options.source.kind === "vault") {
@@ -42,6 +47,9 @@ export async function freeflowRetrieve(options) {
         if (options.action === "locate") {
             return await locateRepo(root, options, preserve);
         }
+        if (options.action === "get") {
+            return await getRepo(root, options, preserve);
+        }
         if (options.action === "expand") {
             return await expandRepoEvidence(root, options, preserve);
         }
@@ -55,44 +63,65 @@ export async function freeflowRetrieve(options) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return errorResult(preserve, `freeflow_retrieve failed while reading ${options.source.kind} source: ${message}`);
+        return errorResult(preserve, `freeflow_search failed while reading ${options.source.kind} source: ${message}`);
     }
 }
 async function retrieveVault(options, preserve) {
     if (options.action === "retrieve") {
+        if (!hasVaultOutputId(options)) {
+            return errorResult(preserve, "Vault retrieve requires source.outputId.");
+        }
         return retrieveVaultLines(options, preserve);
     }
     if (options.action === "expand") {
+        if (!hasVaultOutputId(options)) {
+            return errorResult(preserve, "Vault expansion requires source.outputId for exact raw recovery.");
+        }
         return expandVaultEvidence(options, preserve);
     }
     if (options.action === "explain") {
+        if (!hasVaultOutputId(options)) {
+            return errorResult(preserve, "Vault explain requires source.outputId.");
+        }
         return explainVaultOutput(options, preserve);
     }
-    if (options.action !== "query") {
+    if (options.action !== "query" && options.action !== "locate" && options.action !== "get") {
         return errorResult(preserve, `Vault retrieval action ${options.action} is not implemented yet.`);
     }
     if (!options.query?.trim()) {
+        return errorResult(preserve, `Vault ${options.action} requires a non-empty query string.`);
+    }
+    if (hasVaultOutputId(options) && (options.action === "query" || options.action === "get")) {
+        return querySingleVaultOutput(options, preserve, options.action);
+    }
+    return queryVaultIndex(options, preserve, options.action);
+}
+async function querySingleVaultOutput(options, preserve, action = "query") {
+    const query = options.query?.trim();
+    if (!query) {
         return errorResult(preserve, "Vault query requires a non-empty query string.");
     }
-    const stream = options.source.stream ?? "combined";
     const vault = createVault({ root: options.source.root });
+    const record = await readVaultRecord(vault, options.source.sessionId, options.source.outputId);
+    const stream = resolveVaultStream(record, options.source.stream);
     const text = await readOutputText(vault, options.source.sessionId, options.source.outputId, stream);
     const lines = splitLines(text);
-    const candidateLine = findBestLineForQuery(lines, options.query);
+    const candidateLine = findBestLineForQuery(lines, query);
     if (candidateLine === null) {
         return {
             toolStatus: "ok",
-            decisionId: decisionId("vault-query", options.source.outputId, stream, options.query, "none"),
+            decisionId: decisionId(`vault-${action}`, options.source.outputId, stream, query, "none"),
             preserve,
             source: { kind: "vault", outputId: options.source.outputId, stream },
+            ...vaultRecordResultFields(record),
             routing: {
                 status: "routed",
                 route: "retrieve",
-                reason: "Deterministic lexical vault retrieval found no matching output evidence.",
+                reason: action === "get" ? "Freeflow search get found no matching vaulted output evidence." : "Deterministic lexical vault retrieval found no matching output evidence.",
             },
             evidence: [],
             recovery: {
-                how: `Refine the query or use freeflow_retrieve action=retrieve with outputId=${options.source.outputId} and an exact line range.`,
+                how: `Refine the query or use freeflow_search action=retrieve with outputId=${options.source.outputId} and an exact line range.`,
                 outputId: options.source.outputId,
             },
         };
@@ -100,41 +129,157 @@ async function retrieveVault(options, preserve) {
     const start = Math.max(0, candidateLine - DEFAULT_CONTEXT_LINES);
     const end = Math.min(lines.length - 1, candidateLine + DEFAULT_CONTEXT_LINES);
     const evidenceLines = `${start + 1}-${end + 1}`;
+    const match = matchMetadataForText(lines[candidateLine] ?? "", query);
     const evidence = {
-        id: evidenceIdFor(`${options.source.outputId}:${stream}`, evidenceLines, options.query),
+        id: evidenceIdFor(`${options.source.outputId}:${stream}`, evidenceLines, query),
         source: { kind: "vault", outputId: options.source.outputId, stream },
         path: `${options.source.outputId}:${stream}`,
         lines: evidenceLines,
         excerpt: excerptForLineRange(lines, { start: start + 1, end: end + 1 }, "small"),
-        why: `Deterministic lexical match for query terms in vaulted ${stream} output near line ${candidateLine + 1}.`,
+        why: action === "get"
+            ? `Best vaulted get match near line ${candidateLine + 1}; matchType=${match.type} confidence=${match.confidence.toFixed(2)}.`
+            : `Deterministic lexical match for query terms in vaulted ${stream} output near line ${candidateLine + 1}.`,
         window: "small",
         expandable: true,
+        ...(action === "get" ? { match } : {}),
     };
     return {
         toolStatus: "ok",
-        decisionId: decisionId("vault-query", options.source.outputId, stream, options.query, evidenceLines),
+        decisionId: decisionId(`vault-${action}`, options.source.outputId, stream, query, evidenceLines),
         preserve,
         source: { kind: "vault", outputId: options.source.outputId, stream },
+        ...vaultRecordResultFields(record),
         routing: {
             status: "routed",
             route: "retrieve",
-            reason: `Deterministic lexical retrieval selected vaulted outputId=${options.source.outputId} stream=${stream} lines=${evidenceLines}.`,
+            reason: action === "get"
+                ? `Freeflow search get selected best vaulted outputId=${options.source.outputId} stream=${stream} lines=${evidenceLines}; matchType=${match.type} confidence=${match.confidence.toFixed(2)}.`
+                : `Deterministic lexical retrieval selected vaulted outputId=${options.source.outputId} stream=${stream} lines=${evidenceLines}.`,
         },
         evidence: [evidence],
         recovery: {
-            how: `Use freeflow_retrieve action=expand with evidenceId=${evidence.id}, or action=retrieve with outputId=${options.source.outputId} and stream=${stream}.`,
+            how: action === "get"
+                ? `Use freeflow_search action=retrieve with outputId=${options.source.outputId}, stream=${stream}, and lineRange=${evidenceLines} for exact recovery; use action=expand with evidenceId=${evidence.id} for more context.`
+                : `Use freeflow_search action=expand with evidenceId=${evidence.id}, or action=retrieve with outputId=${options.source.outputId} and stream=${stream}.`,
             outputId: options.source.outputId,
             evidenceId: evidence.id,
         },
     };
 }
+async function queryVaultIndex(options, preserve, action) {
+    const query = options.query?.trim();
+    if (!query) {
+        return errorResult(preserve, `Vault ${action} requires a non-empty query string.`);
+    }
+    const topK = parseTopK(options.topK, action === "locate" ? DEFAULT_LOCATE_TOP_K : DEFAULT_QUERY_TOP_K);
+    if (typeof topK === "string") {
+        return errorResult(preserve, topK);
+    }
+    const vault = createVault({ root: options.source.root });
+    const indexResult = await createLocalVaultIndex(vault).queryVault(query, vaultIndexFiltersFromSource(options.source, options.filters), {
+        topK,
+        maxExcerptBytes: action === "locate" ? LINE_PREVIEW_MAX_BYTES : QUERY_EXCERPT_MAX_BYTES,
+    });
+    if (indexResult.matches.length === 0) {
+        return {
+            toolStatus: "ok",
+            decisionId: decisionId(`vault-${action}-index`, query, String(topK), "none"),
+            preserve,
+            routing: {
+                status: "routed",
+                route: "retrieve",
+                reason: `Vault-wide ${action} found no matching indexed evidence for the current filters.`,
+            },
+            evidence: [],
+            recovery: {
+                how: "Refine the query, adjust vault filters, or use source.outputId with action=retrieve/explain when the exact output is known.",
+            },
+        };
+    }
+    const evidence = indexResult.matches.map((match) => evidenceFromVaultIndexMatch(match, query, action));
+    const first = indexResult.matches[0];
+    const firstEvidence = evidence[0];
+    if (!first || !firstEvidence) {
+        return errorResult(preserve, `Vault ${action} produced no usable indexed evidence.`);
+    }
+    return {
+        toolStatus: "ok",
+        decisionId: decisionId(`vault-${action}-index`, query, String(topK), evidence.map((packet) => `${packet.path}:${packet.lines ?? ""}`).join("|")),
+        preserve,
+        source: sourceRefForVaultIndexMatch(first),
+        routing: {
+            status: "routed",
+            route: "retrieve",
+            reason: action === "locate"
+                ? `Located ${evidence.length} indexed vault candidate(s) without raw output retrieval; top result ${first.outputId}${first.stream ? `:${first.stream}` : ""}${firstEvidence.lines ? `:${firstEvidence.lines}` : ""}.`
+                : action === "get"
+                    ? `Freeflow search get selected best indexed vault match ${first.outputId}${first.stream ? `:${first.stream}` : ""}${firstEvidence.lines ? `:${firstEvidence.lines}` : ""}; matchType=${firstEvidence.match?.type ?? "lexical"} confidence=${(firstEvidence.match?.confidence ?? scoreConfidence(first.score)).toFixed(2)}.`
+                    : `Vault-wide query selected ${evidence.length} indexed candidate(s); top result ${first.outputId}${first.stream ? `:${first.stream}` : ""}${firstEvidence.lines ? `:${firstEvidence.lines}` : ""}.`,
+        },
+        evidence,
+        recovery: {
+            how: first.metadataOnly
+                ? `Top match ${first.outputId} is metadata-only; use freeflow_search action=explain with outputId=${first.outputId} for recoverability details.`
+                : `Use freeflow_search action=expand with source.outputId=${first.outputId} and evidenceId=${firstEvidence.id}, or action=retrieve with outputId=${first.outputId}${first.stream ? ` and stream=${first.stream}` : ""}.`,
+            outputId: first.outputId,
+            evidenceId: firstEvidence.id,
+        },
+    };
+}
+function evidenceFromVaultIndexMatch(match, query, action) {
+    const source = sourceRefForVaultIndexMatch(match);
+    const lines = match.lineStart !== undefined && match.lineEnd !== undefined ? `${match.lineStart}-${match.lineEnd}` : undefined;
+    const path = `${match.outputId}${match.stream ? `:${match.stream}` : ":metadata"}`;
+    const matchMetadata = match.metadataOnly ? { type: "metadata", confidence: scoreConfidence(match.score) } : matchMetadataForText(match.excerpt, query, match.score);
+    const why = match.metadataOnly
+        ? `Indexed metadata-only ${action} match for query terms; raw content is not recoverable from this entry.`
+        : action === "get"
+            ? `Best indexed vault get match; matchType=${matchMetadata.type} confidence=${matchMetadata.confidence.toFixed(2)} score=${match.score}.`
+            : `Indexed vault ${action} match for query terms with score ${match.score}.`;
+    return {
+        id: evidenceIdFor(path, lines ?? match.chunkId, query),
+        source,
+        path,
+        ...(lines !== undefined ? { lines } : {}),
+        excerpt: match.excerpt,
+        why,
+        window: "small",
+        expandable: !match.metadataOnly && lines !== undefined && match.stream !== undefined,
+        ...(action === "get" ? { match: matchMetadata } : {}),
+    };
+}
+function sourceRefForVaultIndexMatch(match) {
+    return {
+        kind: "vault",
+        outputId: match.outputId,
+        ...(match.stream !== undefined ? { stream: match.stream } : {}),
+    };
+}
+function vaultIndexFiltersFromSource(source, filters) {
+    return {
+        ...filters,
+        sessionId: filters?.sessionId ?? source.sessionId,
+        ...(source.outputId !== undefined ? { outputId: source.outputId } : {}),
+        ...(source.producerKind !== undefined ? { producerKind: source.producerKind } : {}),
+        ...(source.server !== undefined ? { server: source.server } : {}),
+        ...(source.tool !== undefined ? { tool: source.tool } : {}),
+        ...(source.hostToolName !== undefined ? { hostToolName: source.hostToolName } : {}),
+        ...(source.stream !== undefined ? { stream: source.stream } : {}),
+        ...(source.recordKind !== undefined ? { recordKind: source.recordKind } : {}),
+        ...(source.recoverability !== undefined ? { recoverability: source.recoverability } : {}),
+    };
+}
+function hasVaultOutputId(options) {
+    return typeof options.source.outputId === "string" && options.source.outputId.length > 0;
+}
 async function retrieveVaultLines(options, preserve) {
-    const stream = options.source.stream ?? "combined";
     const lineRange = options.lineRange;
     if (!lineRange) {
         return errorResult(preserve, "Vault retrieve requires a valid 1-based lineRange.");
     }
     const vault = createVault({ root: options.source.root });
+    const record = await readVaultRecord(vault, options.source.sessionId, options.source.outputId);
+    const stream = resolveVaultStream(record, options.source.stream);
     const text = await readOutputText(vault, options.source.sessionId, options.source.outputId, stream);
     const lines = splitLines(text);
     const resolvedRange = resolveExactLineRange({
@@ -150,7 +295,7 @@ async function retrieveVaultLines(options, preserve) {
     const evidenceLines = `${start}-${end}`;
     const excerpt = lines.slice(start - 1, end).join("\n");
     if (byteLength(excerpt) > EXACT_LINE_RANGE_MAX_BYTES) {
-        return retrieveVaultLineRangeOverCap(options, preserve, stream, lines, { start, end }, byteLength(excerpt));
+        return retrieveVaultLineRangeOverCap(options, preserve, stream, record, lines, { start, end }, byteLength(excerpt));
     }
     const evidence = {
         id: evidenceIdFor(`${options.source.outputId}:${stream}`, evidenceLines, "retrieve"),
@@ -167,6 +312,7 @@ async function retrieveVaultLines(options, preserve) {
         decisionId: decisionId("vault-retrieve", options.source.outputId, stream, evidenceLines),
         preserve,
         source: { kind: "vault", outputId: options.source.outputId, stream },
+        ...vaultRecordResultFields(record),
         routing: {
             status: "routed",
             route: "retrieve",
@@ -174,13 +320,13 @@ async function retrieveVaultLines(options, preserve) {
         },
         evidence: [evidence],
         recovery: {
-            how: `Use freeflow_retrieve action=expand with evidenceId=${evidence.id} for more vaulted output context.`,
+            how: `Use freeflow_search action=expand with evidenceId=${evidence.id} for more vaulted output context.`,
             outputId: options.source.outputId,
             evidenceId: evidence.id,
         },
     };
 }
-function retrieveVaultLineRangeOverCap(options, preserve, stream, lines, requestedRange, requestedBytes) {
+function retrieveVaultLineRangeOverCap(options, preserve, stream, record, lines, requestedRange, requestedBytes) {
     const evidence = buildBoundedEdgeChunks({ lines, range: requestedRange, caps: BOUNDED_EVIDENCE_CAPS }).map((chunk, index) => {
         const evidenceLines = chunk.linesLabel;
         return {
@@ -199,6 +345,7 @@ function retrieveVaultLineRangeOverCap(options, preserve, stream, lines, request
         decisionId: decisionId("vault-retrieve-lines-over-cap", options.source.outputId, stream, `${requestedRange.start}-${requestedRange.end}`, String(requestedBytes)),
         preserve,
         source: { kind: "vault", outputId: options.source.outputId, stream },
+        ...vaultRecordResultFields(record),
         routing: {
             status: "partial",
             route: "retrieve",
@@ -206,12 +353,12 @@ function retrieveVaultLineRangeOverCap(options, preserve, stream, lines, request
         },
         evidence,
         recovery: {
-            how: `Use narrower freeflow_retrieve action=retrieve lineRange spans for exact vaulted output recovery, or native vault file access if a full raw span is required.`,
+            how: `Use narrower freeflow_search action=retrieve lineRange spans for exact vaulted output recovery, or native vault file access if a full raw span is required.`,
             outputId: options.source.outputId,
         },
     };
 }
-function expandVaultEvidenceOverCap(options, preserve, stream, evidence, lines, expandedRange, expandedBytes) {
+function expandVaultEvidenceOverCap(options, preserve, stream, record, evidence, lines, expandedRange, expandedBytes) {
     const chunks = buildBoundedEdgeChunks({ lines, range: expandedRange, caps: BOUNDED_EVIDENCE_CAPS }).map((chunk, index) => {
         const evidenceLines = chunk.linesLabel;
         return {
@@ -231,6 +378,7 @@ function expandVaultEvidenceOverCap(options, preserve, stream, evidence, lines,
         decisionId: decisionId("vault-expand-over-cap", evidence.id, expandedLines, String(expandedBytes)),
         preserve,
         source: { kind: "vault", outputId: options.source.outputId, stream },
+        ...vaultRecordResultFields(record),
         routing: {
             status: "partial",
             route: "retrieve",
@@ -238,7 +386,7 @@ function expandVaultEvidenceOverCap(options, preserve, stream, evidence, lines,
         },
         evidence: chunks,
         recovery: {
-            how: `Use narrower freeflow_retrieve action=retrieve lineRange spans for exact vaulted output recovery.`,
+            how: `Use narrower freeflow_search action=retrieve lineRange spans for exact vaulted output recovery.`,
             outputId: options.source.outputId,
             evidenceId: evidence.id,
         },
@@ -249,20 +397,21 @@ async function expandVaultEvidence(options, preserve) {
     if (!evidence?.lines || evidence.source.kind !== "vault") {
         return errorResult(preserve, "Vault expansion requires a previous vault evidence packet with lines.");
     }
-    const stream = options.source.stream ?? evidence.source.stream ?? "combined";
     const originalRange = parseLineRange(evidence.lines);
     if (!originalRange) {
         return errorResult(preserve, `Cannot expand unsupported vault evidence line range ${evidence.lines}.`);
     }
     const expansion = options.expansion ?? "lines_30";
     const vault = createVault({ root: options.source.root });
+    const record = await readVaultRecord(vault, options.source.sessionId, options.source.outputId);
+    const stream = resolveVaultStream(record, options.source.stream ?? evidence.source.stream);
     const text = await readOutputText(vault, options.source.sessionId, options.source.outputId, stream);
     const lines = splitLines(text);
     const expandedRange = expandLineRange(originalRange, lines.length, expansion);
     const window = windowForExpansion(expansion);
     const expandedExcerpt = lines.slice(expandedRange.start - 1, expandedRange.end).join("\n");
     if (expansion === "full" && byteLength(expandedExcerpt) > EXACT_LINE_RANGE_MAX_BYTES) {
-        return expandVaultEvidenceOverCap(options, preserve, stream, evidence, lines, expandedRange, byteLength(expandedExcerpt));
+        return expandVaultEvidenceOverCap(options, preserve, stream, record, evidence, lines, expandedRange, byteLength(expandedExcerpt));
     }
     const bounded = buildBoundedExcerpt({ lines, range: expandedRange, window, caps: BOUNDED_EVIDENCE_CAPS });
     const expandedLines = bounded.linesLabel;
@@ -283,6 +432,7 @@ async function expandVaultEvidence(options, preserve) {
         decisionId: decisionId("vault-expand", evidence.id, expandedLines),
         preserve,
         source: { kind: "vault", outputId: options.source.outputId, stream },
+        ...vaultRecordResultFields(record),
         routing: {
             status: "routed",
             route: "retrieve",
@@ -290,7 +440,7 @@ async function expandVaultEvidence(options, preserve) {
         },
         evidence: [expandedEvidence],
         recovery: {
-            how: `Use freeflow_retrieve action=retrieve with outputId=${options.source.outputId}, stream=${stream}, and an exact line range for precise recovery.`,
+            how: `Use freeflow_search action=retrieve with outputId=${options.source.outputId}, stream=${stream}, and an exact line range for precise recovery.`,
             outputId: options.source.outputId,
             evidenceId: evidence.id,
         },
@@ -299,9 +449,10 @@ async function expandVaultEvidence(options, preserve) {
 async function explainVaultOutput(options, preserve) {
     const vault = createVault({ root: options.source.root });
     const record = await readVaultRecord(vault, options.source.sessionId, options.source.outputId);
-    const details = record.kind === "command"
-        ? `kind=command executionStatus=${record.executionStatus} exitCode=${record.exitCode} decisions=${record.decisionIds.join(",")}`
-        : `kind=${record.kind} decisions=${record.decisionIds.join(",")}`;
+    const producer = producerForVaultRecord(record);
+    const persistence = persistenceForVaultRecord(record);
+    const details = vaultRecordDetails(record);
+    const recovery = vaultRecordRecovery(record, options.source.stream);
     const source = { kind: "vault", outputId: options.source.outputId };
     if (options.source.stream !== undefined) {
         Object.assign(source, { stream: options.source.stream });
@@ -311,15 +462,138 @@ async function explainVaultOutput(options, preserve) {
         decisionId: decisionId("vault-explain", options.source.outputId, record.contentHashSha256),
         preserve,
         source,
+        ...vaultRecordResultFields(record),
         routing: {
             status: "routed",
             route: "retrieve",
-            reason: `Vault outputId=${options.source.outputId} ${details}. Raw output is recoverable from the vault record without rerunning the original command.`,
+            reason: `Vault outputId=${options.source.outputId} ${details}; producer=${producer.kind}; persistence.status=${persistence.status}; recoverability=${persistence.recoverability}. ${recovery.reason}`,
         },
         evidence: [],
-        recovery: {
-            how: `Use freeflow_retrieve action=retrieve with outputId=${options.source.outputId}, stream=stdout|stderr|combined, and an exact lineRange to recover raw command output.`,
-            outputId: options.source.outputId,
+        recovery: recovery.hint,
+    };
+}
+function resolveVaultStream(record, requested) {
+    if (requested !== undefined) {
+        return requested;
+    }
+    if (record.kind === "command") {
+        return "combined";
+    }
+    if (record.kind === "text") {
+        return "raw";
+    }
+    if (record.kind === "metadata") {
+        throw new Error("Metadata only records store no raw stream.");
+    }
+    throw new Error("Repo file reference records store metadata only and have no raw stream.");
+}
+function vaultRecordResultFields(record) {
+    const fields = {
+        producer: producerForVaultRecord(record),
+        persistence: persistenceForVaultRecord(record),
+    };
+    const recordId = record.recordId;
+    if (typeof recordId === "string") {
+        fields.recordId = recordId;
+    }
+    if (record.lineage !== undefined) {
+        fields.lineage = record.lineage;
+    }
+    return fields;
+}
+function producerForVaultRecord(record) {
+    const producer = record.producer;
+    if (producer?.kind) {
+        return producer;
+    }
+    if (record.kind === "command") {
+        return { kind: "command" };
+    }
+    if (record.kind === "text" || record.kind === "metadata") {
+        if (record.sourceKind === "native") {
+            return { kind: "native" };
+        }
+        if (record.sourceKind === "mcp") {
+            return { kind: "mcp" };
+        }
+        if (record.sourceKind === "web") {
+            return { kind: "web" };
+        }
+        if (record.sourceKind === "fetch") {
+            return { kind: "fetch" };
+        }
+        if (record.sourceKind === "code_search") {
+            return { kind: "code_search" };
+        }
+        return { kind: "other" };
+    }
+    return { kind: "repo" };
+}
+function persistenceForVaultRecord(record) {
+    const persistence = record.persistence;
+    if (persistence?.status && persistence.recoverability) {
+        return persistence;
+    }
+    if (record.kind === "repo-file" || record.kind === "metadata") {
+        return { status: "metadata_only", recoverability: "metadata_only", outputId: record.outputId };
+    }
+    return {
+        status: "vaulted",
+        recoverability: "exact",
+        recoveryOutputId: record.outputId,
+        outputId: record.outputId,
+    };
+}
+function vaultRecordDetails(record) {
+    const decisions = Array.isArray(record.decisionIds) ? record.decisionIds.join(",") : "";
+    const recordId = record.recordId;
+    const recordIdText = typeof recordId === "string" ? ` recordId=${recordId}` : "";
+    if (record.kind === "command") {
+        return `kind=command${recordIdText} executionStatus=${record.executionStatus} exitCode=${record.exitCode} decisions=${decisions}`;
+    }
+    if (record.kind === "text") {
+        return `kind=text${recordIdText} sourceKind=${record.sourceKind} decisions=${decisions}`;
+    }
+    if (record.kind === "metadata") {
+        return `kind=metadata${recordIdText} sourceKind=${record.sourceKind} rawLines=${record.lineCounts.raw} rawBytes=${record.byteCounts.raw} decisions=${decisions}`;
+    }
+    return `kind=repo-file${recordIdText} path=${record.path} decisions=${decisions}`;
+}
+function vaultRecordRecovery(record, requestedStream) {
+    const persistence = persistenceForVaultRecord(record);
+    const recoveryOutputId = persistence.recoveryOutputId ?? persistence.outputId ?? record.outputId;
+    if (persistence.recoverability === "exact") {
+        const stream = requestedStream ?? resolveVaultStream(record);
+        const streamText = record.kind === "command" && requestedStream === undefined ? "stdout|stderr|combined" : stream;
+        return {
+            reason: `Exact content is recoverable from the vault with recoveryOutputId=${recoveryOutputId}.`,
+            hint: {
+                how: `Use freeflow_search action=retrieve with outputId=${recoveryOutputId}, stream=${streamText}, and an exact lineRange to recover exact vaulted content.`,
+                outputId: recoveryOutputId,
+            },
+        };
+    }
+    if (persistence.recoverability === "redacted") {
+        return {
+            reason: `Only redacted content is recoverable from the vault; exact raw content is intentionally unavailable.`,
+            hint: {
+                how: `Use freeflow_search action=retrieve with outputId=${recoveryOutputId} to recover redacted persisted content. Exact raw recovery is unavailable.`,
+                outputId: recoveryOutputId,
+            },
+        };
+    }
+    if (persistence.recoverability === "metadata_only") {
+        return {
+            reason: "Only metadata was persisted; no raw content recovery is promised.",
+            hint: {
+                how: "Only vault metadata is available for this record. There is no raw content stream to recover.",
+            },
+        };
+    }
+    return {
+        reason: "No content was persisted; recovery is unavailable.",
+        hint: {
+            how: "No persisted content is available for this record.",
         },
     };
 }
@@ -375,11 +649,63 @@ async function queryRepo(root, options, preserve) {
         },
         evidence,
         recovery: {
-            how: `Use freeflow_retrieve action=expand with evidenceId=${first.id} for more surrounding context, action=locate for candidate paths, or action=retrieve with path=${firstCandidate.file.path} for an explicit span.`,
+            how: `Use freeflow_search action=expand with evidenceId=${first.id} for more surrounding context, action=locate for candidate paths, or action=retrieve with path=${firstCandidate.file.path} for an explicit span.`,
             evidenceId: first.id,
         },
     };
 }
+async function getRepo(root, options, preserve) {
+    if (!options.query?.trim()) {
+        return errorResult(preserve, "Repo get requires a non-empty query string.");
+    }
+    const query = options.query.trim();
+    const files = await readRepoTextFiles(root, options.source.path, options.generatedPathGlobs);
+    const candidates = searchRepoEvidenceCandidates({
+        files,
+        query,
+        topK: 1,
+        defaultContextLines: DEFAULT_CONTEXT_LINES,
+        queryCoverageMaxLines: QUERY_COVERAGE_MAX_LINES,
+    });
+    const candidate = candidates[0];
+    if (!candidate) {
+        return {
+            toolStatus: "ok",
+            decisionId: decisionId("repo-get", query, root, "none"),
+            preserve,
+            source: { kind: "repo", path: options.source.path ?? "." },
+            routing: {
+                status: "routed",
+                route: "retrieve",
+                reason: "Freeflow search get found no matching repo evidence.",
+            },
+            evidence: [],
+            recovery: {
+                how: "Refine the query, use action=locate for candidate paths, or use native read for a known whole file.",
+            },
+        };
+    }
+    const match = matchMetadataForCandidate(candidate);
+    const evidence = evidenceFromCandidate(candidate, query);
+    evidence.why = `Best repo get match; matchType=${match.type} confidence=${match.confidence.toFixed(2)}. ${evidence.why}`;
+    evidence.match = match;
+    return {
+        toolStatus: "ok",
+        decisionId: decisionId("repo-get", query, evidence.path ?? candidate.file.path, evidence.lines ?? ""),
+        preserve,
+        source: { kind: "repo", path: candidate.file.path },
+        routing: {
+            status: "routed",
+            route: "retrieve",
+            reason: `Freeflow search get selected best repo match ${candidate.file.path}:${evidence.lines}; matchType=${match.type} confidence=${match.confidence.toFixed(2)} (${candidate.reason}).`,
+        },
+        evidence: [evidence],
+        recovery: {
+            how: `Use freeflow_search action=retrieve with path=${candidate.file.path} and lineRange=${evidence.lines} for exact recovery, or action=expand with evidenceId=${evidence.id}.`,
+            evidenceId: evidence.id,
+        },
+    };
+}
 async function locateRepo(root, options, preserve) {
     if (!options.query?.trim()) {
         return errorResult(preserve, "Repo locate requires a non-empty query string.");
@@ -442,7 +768,7 @@ async function locateRepo(root, options, preserve) {
         },
         evidence,
         recovery: {
-            how: `Use freeflow_retrieve action=retrieve with path=${firstCandidate.file.path} for an explicit span, or action=expand with evidenceId=${first.id}.`,
+            how: `Use freeflow_search action=retrieve with path=${firstCandidate.file.path} for an explicit span, or action=expand with evidenceId=${first.id}.`,
             evidenceId: first.id,
         },
     };
@@ -486,7 +812,7 @@ async function expandRepoEvidence(root, options, preserve) {
         recovery: {
             how: expansion === "full"
                 ? `Use native read for direct whole-file behavior if needed for ${evidence.path}.`
-                : `Use freeflow_retrieve action=expand with expansion=lines_80 or full for more context from ${evidence.path}.`,
+                : `Use freeflow_search action=expand with expansion=lines_80 or full for more context from ${evidence.path}.`,
             evidenceId: evidence.id,
         },
     };
@@ -524,7 +850,7 @@ async function retrieveRepoPath(root, options, preserve) {
         },
         evidence: [evidence],
         recovery: {
-            how: `Use freeflow_retrieve action=expand with evidenceId=${evidence.id} for more context from ${file.path}.`,
+            how: `Use freeflow_search action=expand with evidenceId=${evidence.id} for more context from ${file.path}.`,
             evidenceId: evidence.id,
         },
     };
@@ -544,7 +870,7 @@ function expandRepoEvidenceOverCap(file, evidence, expandedRange, preserve, expa
         },
         evidence: chunks,
         recovery: {
-            how: `Use narrower freeflow_retrieve action=retrieve lineRange spans for exact content recovery from ${file.path}, or native read for direct whole-file host behavior.`,
+            how: `Use narrower freeflow_search action=retrieve lineRange spans for exact content recovery from ${file.path}, or native read for direct whole-file host behavior.`,
             evidenceId: evidence.id,
         },
     };
@@ -585,7 +911,7 @@ function retrieveRepoLineRange(file, lineRange, preserve) {
         },
         evidence: [evidence],
         recovery: {
-            how: `Use freeflow_retrieve action=expand with evidenceId=${evidence.id} for more context from ${file.path}.`,
+            how: `Use freeflow_search action=expand with evidenceId=${evidence.id} for more context from ${file.path}.`,
             evidenceId: evidence.id,
         },
     };
@@ -604,7 +930,7 @@ function retrieveRepoLineRangeOverCap(file, requestedRange, preserve, requestedB
         },
         evidence,
         recovery: {
-            how: `Use narrower freeflow_retrieve action=retrieve lineRange spans for exact content recovery from ${file.path}, or native read for direct whole-file host behavior.`,
+            how: `Use narrower freeflow_search action=retrieve lineRange spans for exact content recovery from ${file.path}, or native read for direct whole-file host behavior.`,
         },
     };
 }
@@ -666,7 +992,7 @@ function retrieveFullFile(file, maxFullBytes) {
         },
         evidence,
         recovery: {
-            how: `Use freeflow_retrieve action=retrieve with path=${file.path} and an explicit span to recover exact content, or native read for direct whole-file output.`,
+            how: `Use freeflow_search action=retrieve with path=${file.path} and an explicit span to recover exact content, or native read for direct whole-file output.`,
         },
     };
 }
@@ -677,7 +1003,7 @@ function explainRepoDecision(options, preserve) {
     }
     const recovery = {
         how: decision.recovery?.how ??
-            "Use freeflow_retrieve action=expand with a returned evidence id, or action=retrieve for an explicit repo span.",
+            "Use freeflow_search action=expand with a returned evidence id, or action=retrieve for an explicit repo span.",
     };
     if (decision.recovery?.outputId !== undefined) {
         Object.assign(recovery, { outputId: decision.recovery.outputId });
@@ -751,6 +1077,30 @@ function parseTopK(value, defaultValue) {
     }
     return value;
 }
+function matchMetadataForCandidate(candidate) {
+    return {
+        type: candidate.exactNormalizedPhrase ? "exact_phrase" : "lexical",
+        confidence: candidate.exactNormalizedPhrase ? 0.95 : scoreConfidence(candidate.score),
+    };
+}
+function matchMetadataForText(text, query, score) {
+    const normalizedText = normalizeComparableText(text);
+    const normalizedQuery = normalizeComparableText(query);
+    const exact = normalizedQuery.length > 0 && normalizedText.includes(normalizedQuery);
+    return {
+        type: exact ? "exact_phrase" : "lexical",
+        confidence: exact ? 0.95 : scoreConfidence(score),
+    };
+}
+function scoreConfidence(score) {
+    if (score === undefined || !Number.isFinite(score) || score <= 0) {
+        return 0.6;
+    }
+    return Math.max(0.6, Math.min(0.9, score / (score + 10)));
+}
+function normalizeComparableText(value) {
+    return value.toLowerCase().replace(/[^a-z0-9_.$/-]+/g, " ").replace(/\s+/g, " ").trim();
+}
 function evidenceFromCandidate(candidate, query) {
     const defaultStart = Math.max(0, candidate.lineIndex - DEFAULT_CONTEXT_LINES);
     const defaultEnd = Math.min(candidate.file.lines.length - 1, candidate.lineIndex + DEFAULT_CONTEXT_LINES);
@@ -849,7 +1199,7 @@ function errorResult(preserve, reason) {
         },
         evidence: [],
         recovery: {
-            how: "Use native read for a known whole file, or retry freeflow_retrieve with a supported repo query.",
+            how: "Use native read for a known whole file, or retry freeflow_search with a supported repo query.",
         },
     };
 }