jev-agent-tools 0.2.0 → 0.3.0

package/dist/tools/find.js

@@ -1,5 +1,5 @@
 import { Type } from "@sinclair/typebox";
-import { canonicalPath } from "../adapters/canonical-path.js";
+import { resolveEvidenceContext, withEvidenceContext, } from "../adapters/evidence-context.js";
 import { collectSearchExcerpts } from "../adapters/files.js";
 import { prefilter } from "../adapters/find.js";
 import { shareGitInventory } from "../adapters/git-inventory.js";
@@ -8,11 +8,14 @@ import * as C from "../constants.js";
 import { contentWords, findKeywords, rankFiles, retainFiles, } from "../core/find.js";
 import { buildEnvelope, } from "../core/output.js";
 import { needsReverse, pointerQuestion, readPointer } from "../core/pointer.js";
+import { answerItemFromInput, buildResultReport, contextFromEvidence, known, } from "../core/result-report.js";
+import { secretRefusal } from "../core/secret-path.js";
 import { interpolate } from "../describe.js";
-import { renderEnvelope } from "../render.js";
+import { renderResultReport } from "../render.js";
 import { NOT_CONFIGURED } from "../texts/configuration.js";
 import { FIND_DESCRIPTION } from "../texts/find.js";
 export const findParameters = Type.Object({
+    root: Type.Optional(Type.String()),
     goal: Type.String({ minLength: 1 }),
     keywords: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
     scope: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
@@ -45,7 +48,13 @@ export function createFindFilesTool(dependencies) {
             }),
         async execute(_id, args, signal, _update, ctx) {
             const client = dependencies.client;
-            const cwd = await canonicalPath(ctx.cwd);
+            const evidence = await resolveEvidenceContext(ctx.cwd, args.root, {
+                exec: execute,
+                signal,
+                origin: dependencies.evidenceOrigin,
+            });
+            const evidenceContext = evidence.context;
+            const cwd = evidence.ok ? evidence.cwd : evidenceContext.authority.path;
             const started = performance.now();
             const exec = shareGitInventory(execute);
             const totals = {
@@ -59,6 +68,88 @@ export function createFindFilesTool(dependencies) {
             const unchecked = [];
             let budget;
             let sent = 0;
+            const context = contextFromEvidence(evidenceContext);
+            const diagnostics = [];
+            const actions = [];
+            const auxiliary = {
+                controls: { fresh: 0, cache: 0, notJudged: 0, static: 0 },
+                passages: { fresh: 0, cache: 0, notJudged: 0 },
+            };
+            let entryPaths = [];
+            let costObserved = true;
+            let failureCause = "invalid_response";
+            let primary;
+            let confirmation;
+            let confirmationRequired = false;
+            const raw = (answer) => answer.type === "choice"
+                ? Object.entries(answer.probabilities).map(([label, probability]) => ({
+                    label,
+                    value: label,
+                    probability: known(probability),
+                }))
+                : [];
+            const diagnostic = (cause, fact, members = []) => {
+                const id = `d${diagnostics.length + 1}`;
+                const actionId = `a${actions.length + 1}`;
+                const code = cause === "invalid_root"
+                    ? "correct_context"
+                    : cause === "not_configured"
+                        ? "configure_client"
+                        : cause === "service_unavailable" || cause === "transport_failure"
+                            ? "recover_service"
+                            : "inspect_native";
+                actions.push({
+                    id: actionId,
+                    code,
+                    target: known(members.join(", ") || "entry"),
+                    scope: { kind: "call" },
+                    condition: code === "correct_context"
+                        ? "If the requested root is incorrect"
+                        : code === "configure_client"
+                            ? "If Jev judgment is still useful after configuring the client"
+                            : code === "recover_service"
+                                ? "Only after service recovery is observed"
+                                : "If the entry decision remains open",
+                    instruction: code === "correct_context"
+                        ? "Provide the exact registered worktree top-level; no fallback was performed."
+                        : code === "configure_client"
+                            ? "Configure the Jev client, or continue with native discovery."
+                            : code === "recover_service"
+                                ? "Continue natively while unavailable; revisit only after a material service change."
+                                : "Inspect the candidate paths or collected passages natively; retain uncertainty without repeating unchanged evidence.",
+                    repeatUnchanged: false,
+                });
+                diagnostics.push({
+                    id,
+                    cause,
+                    fact,
+                    target: known(members.join(", ") ||
+                        (cause === "invalid_root"
+                            ? (args.root ?? cwd)
+                            : cause === "forbidden_path"
+                                ? JSON.stringify({ scope: args.scope, exclude: args.exclude })
+                                : "entry")),
+                    origin: cause === "invalid_root" || cause === "forbidden_path"
+                        ? "input"
+                        : cause === "call_budget" || cause === "session_budget"
+                            ? "budget"
+                            : cause === "control_failure"
+                                ? "control"
+                                : cause === "service_unavailable" ||
+                                    cause === "transport_failure" ||
+                                    cause === "invalid_response" ||
+                                    cause === "provider_context_refusal" ||
+                                    cause === "not_configured"
+                                    ? "provider"
+                                    : "collection",
+                    scope: { kind: "call" },
+                    effect: "blocking",
+                    material: true,
+                    omittedMembers: members,
+                    memberCount: known(members.length),
+                    actionIds: [actionId],
+                });
+            };
             const finish = (input) => {
                 const envelope = buildEnvelope({
                     ...input,
@@ -70,16 +161,140 @@ export function createFindFilesTool(dependencies) {
                         elapsedMs: performance.now() - started,
                     },
                 });
+                if (input.refusal)
+                    diagnostic(failureCause, input.refusal);
+                if (!input.refusal &&
+                    !diagnostics.length &&
+                    !budget &&
+                    !unchecked.length &&
+                    !primary?.source)
+                    diagnostic("invalid_response", "entry decision was not received with established answer provenance");
+                if (budget)
+                    diagnostic(budget.kind === "max_calls" ? "call_budget" : "session_budget", budget.message, [...new Set(unchecked)]);
+                if (unchecked.length && !budget)
+                    diagnostic(failureCause, "candidate ranking or entry work was not judged", [...new Set(unchecked)]);
+                const entryLine = input.lines?.find((line) => line.type === "entry");
+                if (entryLine?.type === "entry" && primary?.source)
+                    actions.push({
+                        id: `a${actions.length + 1}`,
+                        code: "inspect_native",
+                        target: known((entryLine.nextRead ?? []).join(", ") || "candidate inventory"),
+                        scope: { kind: "group", groupIds: ["entry"] },
+                        condition: "If the entry decision remains open after this bounded judgment",
+                        instruction: entryLine.candidate.label === "none"
+                            ? "Search elsewhere or widen the admitted scope for the goal; inspect any named alternative before collecting genuinely new evidence. Do not retry unchanged evidence."
+                            : "Read the named candidate passages; add only genuinely discriminating evidence if needed. Do not reword unchanged evidence to retry.",
+                        repeatUnchanged: false,
+                    });
+                const common = {
+                    id: "entry",
+                    kind: "entry",
+                    label: "entry",
+                    groupId: "entry",
+                    evidence: entryPaths.map((path) => ({
+                        target: path,
+                        canonicalPath: known(`${cwd}/${path}`),
+                        aliases: [],
+                        side: "current",
+                        revision: context.resolvedBase,
+                    })),
+                    diagnosticIds: diagnostics.map((d) => d.id),
+                    actionIds: actions.map((a) => a.id),
+                };
+                let item = { ...common, treatment: "not_judged", source: "none" };
+                if (entryLine?.type === "entry" &&
+                    primary?.type === "choice" &&
+                    primary.source &&
+                    (!confirmationRequired ||
+                        (confirmation?.type === "choice" && confirmation.source))) {
+                    auxiliary.passages[primary.source]--;
+                    item = answerItemFromInput(common, {
+                        label: "entry",
+                        answer: primary,
+                        value: entryLine.candidate.value,
+                        publicResult: entryLine.candidate.value.head,
+                        band: entryLine.band,
+                        reason: limitations.map((limit) => limit.fact).join("; "),
+                        rawValues: raw(primary),
+                        reportControls: confirmation?.type === "choice" && confirmation.source
+                            ? [
+                                {
+                                    id: "entry-order",
+                                    kind: "order",
+                                    source: confirmation.source,
+                                    outcome: entryLine.orderDependent
+                                        ? "order-dependent"
+                                        : "consistent",
+                                    rawValues: raw(confirmation),
+                                },
+                            ]
+                            : [],
+                    });
+                }
+                const report = buildResultReport({
+                    tool: "jev_find_files",
+                    context,
+                    items: [item],
+                    diagnostics,
+                    actions,
+                    metrics: {
+                        ...totals,
+                        costUsd: costObserved ? totals.usage.costUsd : undefined,
+                        elapsedMs: performance.now() - started,
+                    },
+                    auxiliary,
+                    total: known(1),
+                    refused: Boolean(input.refusal &&
+                        (failureCause === "invalid_root" ||
+                            failureCause === "forbidden_path")),
+                    missingWork: unchecked.length > 0,
+                });
                 runtime.session.record(envelope);
                 runtime.guide.deliver(ctx);
                 return {
-                    content: [{ type: "text", text: renderEnvelope(envelope) }],
-                    details: totals,
+                    content: [
+                        {
+                            type: "text",
+                            text: renderResultReport(report, {
+                                details: {
+                                    lines: [
+                                        ...envelope.lines,
+                                        ...(entryLine?.type === "entry"
+                                            ? [
+                                                {
+                                                    type: "list",
+                                                    title: "read",
+                                                    items: [...(entryLine.nextRead ?? [])],
+                                                },
+                                                {
+                                                    type: "list",
+                                                    title: "auxiliary ranking",
+                                                    items: (entryLine.relevant ?? []).map((candidate) => `${candidate.label} (${candidate.value.p})`),
+                                                },
+                                            ]
+                                            : []),
+                                        {
+                                            type: "list",
+                                            title: "discovery reservations",
+                                            items: [...limitations, ...(input.limitations ?? [])].map((limit) => limit.fact),
+                                        },
+                                    ],
+                                },
+                            }),
+                        },
+                    ],
+                    details: { ...totals, evidenceContext, result: report },
                     ...hostUsage(host.isOmp, totals.usage),
                 };
             };
-            if (!client)
+            if (!evidence.ok) {
+                failureCause = evidence.cause ?? "invalid_root";
+                return finish({ refusal: evidence.error });
+            }
+            if (!client) {
+                failureCause = "not_configured";
                 return finish({ refusal: NOT_CONFIGURED });
+            }
             const words = contentWords(args.goal);
             const short = words.length < C.FIND_GOAL_MIN_WORDS;
             if (short)
@@ -99,8 +314,30 @@ export function createFindFilesTool(dependencies) {
                     ? C.FIND_THOROUGH_READ
                     : C.FIND_FILES_READ;
             const candidates = await prefilter(exec, cwd, keywords, candidateLimit, args.scope, args.exclude, signal);
-            if (!candidates.ok)
+            if (!candidates.ok) {
+                failureCause = candidates.cause ?? "git_failure";
                 return finish({ refusal: candidates.error });
+            }
+            for (const path of candidates.secret)
+                diagnostic("secret_pattern", secretRefusal(path), [path]);
+            context.inventories.push({
+                id: "candidates",
+                kind: "repository",
+                rules: [
+                    "Git tracked and non-ignored untracked files",
+                    "keyword prefilter with existing effort limit",
+                ],
+                restrictions: [
+                    ...(typeof args.scope === "string"
+                        ? [args.scope]
+                        : (args.scope ?? [])),
+                    ...(args.exclude ?? []).map((path) => `exclude ${path}`),
+                ],
+                discovered: known(candidates.scopeFiles),
+                considered: known(candidates.paths.length),
+                scopeRestricted: Boolean(args.scope || args.exclude?.length),
+                criteria: [],
+            });
             const entry = (path, p, band, alternatives = [], orderDependent = false, orderProbabilities, relevant = []) => ({
                 type: "entry",
                 candidate: { label: path, value: { head: path, p } },
@@ -127,17 +364,18 @@ export function createFindFilesTool(dependencies) {
                     ],
             });
             if (!candidates.paths.length) {
-                limitations.push({
-                    fact: candidates.scopeFiles === 0
-                        ? "scope matched 0 files"
-                        : "no file shares a word with the goal",
-                    next: "rephrase goal or widen scope",
-                });
-                return finish({
-                    lines: [entry("none", 1, short ? "unsure" : "verdict")],
-                });
+                diagnostic("collection_empty", candidates.scopeFiles === 0
+                    ? "scope matched 0 files; no entry judgment"
+                    : "no file shares a word with the goal; no entry judgment");
+                return finish({});
             }
             const judge = async (state, questions) => {
+                state = withEvidenceContext(state, evidenceContext);
+                if (JSON.stringify(state).length > C.STATE_MAX_CHARS)
+                    return {
+                        ok: false,
+                        error: `required evidence exceeds STATE_MAX_CHARS=${C.STATE_MAX_CHARS}`,
+                    };
                 const result = await client.judge(state, questions, {
                     signal,
                     ...runtime.session.requestGate(),
@@ -158,6 +396,7 @@ export function createFindFilesTool(dependencies) {
                         return admission;
                     },
                     onUsage: (usage) => runtime.session.recordUsage(usage),
+                    admissionCause: () => budget?.kind === "max_calls" ? "call_budget" : "session_budget",
                 });
                 for (const key of [
                     "calls",
@@ -167,7 +406,25 @@ export function createFindFilesTool(dependencies) {
                 ])
                     totals[key] += result[key] ?? 0;
                 totals.usage.inputTokens += result.usage?.inputTokens ?? 0;
+                if (result.calls && !result.usage)
+                    costObserved = false;
+                if (!result.ok) {
+                    failureCause = result.failureCause ?? "invalid_response";
+                    auxiliary.passages.notJudged += Object.keys(questions).length;
+                }
                 totals.usage.costUsd += result.usage?.costUsd ?? 0;
+                if (result.ok)
+                    for (const id of Object.keys(questions)) {
+                        const answer = result.answers[id];
+                        if (answer?.type === "unjudged") {
+                            failureCause = answer.cause ?? "invalid_response";
+                            auxiliary.passages.notJudged++;
+                        }
+                        else if (answer?.source)
+                            auxiliary.passages[answer.source]++;
+                        else
+                            auxiliary.passages.notJudged++;
+                    }
                 return result;
             };
             const boolQuestions = (paths, content) => Object.fromEntries(paths.map((path) => [
@@ -203,6 +460,12 @@ export function createFindFilesTool(dependencies) {
             const rankedNames = rankFiles(names);
             let bestRanking = rankedNames;
             const fallback = () => {
+                primary = undefined;
+                if (bestRanking.length)
+                    limitations.push({
+                        fact: `auxiliary ranking retained: ${bestRanking.map((item) => `${item.path} (${item.p})`).join(" · ")}; entry was not judged`,
+                        next: "inspect these paths natively",
+                    });
                 const top = bestRanking.slice(0, 2);
                 return finish({
                     lines: [
@@ -227,18 +490,23 @@ export function createFindFilesTool(dependencies) {
             const contentBatches = Array.from({ length: Math.ceil(readPaths.length / C.FIND_READ_PER_CALL) }, (_, index) => readPaths.slice(index * C.FIND_READ_PER_CALL, (index + 1) * C.FIND_READ_PER_CALL));
             const contentResults = await Promise.all(contentBatches.map(async (paths) => {
                 const read = await collectSearchExcerpts(cwd, paths, keywords, signal, exec);
-                if (!read.ok)
+                if (!read.ok) {
+                    failureCause = read.cause ?? "file_unavailable";
                     return { paths, result: read };
+                }
                 Object.assign(files, read.pointers);
                 limitations.push(...read.limits.map((limit) => ({
                     fact: `${limit.path}: ${limit.reason}`,
                     next: "provide a UTF-8 text file",
                 })));
-                if (read.ignored.length)
+                if (read.ignored.length) {
+                    for (const omission of read.omissions)
+                        diagnostic(omission.cause, `${omission.path}: ${omission.reason}`, [omission.path]);
                     limitations.push({
                         fact: `${read.ignored.length} binary, empty or unreadable paths ignored: ${read.ignored.join(", ")}`,
                         next: "narrow scope to text files",
                     });
+                }
                 const textPaths = paths.filter((path) => read.files[path] !== undefined);
                 if (!textPaths.length)
                     return { paths: [], result: { ok: true, answers: {} } };
@@ -279,12 +547,23 @@ export function createFindFilesTool(dependencies) {
                 ],
             });
             if (!retained.length) {
-                limitations.push({
-                    fact: "no file retained by content or names guard",
-                    next: "rephrase goal or widen scope",
-                });
-                return output("none", 1, short ? "unsure" : "verdict");
+                diagnostic("collection_empty", "no file retained by content or names guard; no entry decision was judged");
+                return finish({});
             }
+            entryPaths = retained.map((item) => item.path);
+            context.inventories.push({
+                id: "entry-passages",
+                kind: "repository",
+                rules: [
+                    "name ranking then bounded passage ranking",
+                    "existing content and names guard",
+                ],
+                restrictions: entryPaths,
+                discovered: known(content.length),
+                considered: known(retained.length),
+                scopeRestricted: true,
+                criteria: [],
+            });
             const idByPath = Object.fromEntries(retained.map((item, index) => [item.path, `c${index + 1}`]));
             const pathById = Object.fromEntries(retained.map((item, index) => [`c${index + 1}`, item.path]));
             const pointer = async (paths) => {
@@ -311,6 +590,7 @@ export function createFindFilesTool(dependencies) {
             if (!firstResult.ok && !budget)
                 return finish({ refusal: firstResult.error });
             const first = firstResult.ok ? firstResult.answers.entry : undefined;
+            primary = first;
             if (first?.type !== "choice") {
                 unchecked.push("entry");
                 return fallback();
@@ -329,15 +609,28 @@ export function createFindFilesTool(dependencies) {
                 (args.effort === "thorough" ||
                     (args.effort !== "quick" &&
                         needsReverse(first.probabilities, retained.length)))) {
+                confirmationRequired = true;
                 const secondResult = await pointer([...paths].reverse());
-                if (!secondResult.ok && !budget)
+                if (!secondResult.ok && !budget) {
+                    auxiliary.passages.notJudged--;
+                    auxiliary.controls.notJudged++;
                     return finish({ refusal: secondResult.error });
+                }
                 const second = secondResult.ok ? secondResult.answers.entry : undefined;
-                if (second?.type !== "choice") {
-                    unchecked.push("entry confirmation");
-                    band = "unsure";
+                confirmation = second;
+                if (second?.type === "choice" && second.source) {
+                    auxiliary.passages[second.source]--;
+                    auxiliary.controls[second.source]++;
                 }
                 else {
+                    auxiliary.passages.notJudged--;
+                    auxiliary.controls.notJudged++;
+                    diagnostic(second?.type === "unjudged"
+                        ? (second.cause ?? "control_failure")
+                        : "control_failure", "required reversed-order entry control was not judged");
+                    return fallback();
+                }
+                {
                     const secondRanks = ranked(second.probabilities);
                     const combined = readPointer(first.probabilities, second.probabilities);
                     ranks = combined.ranked.map(({ id, p }) => ({ path: id, p }));