jev-agent-tools 0.2.0 → 0.3.0

package/src/tools/find.ts

@@ -1,5 +1,8 @@
 import { type Static, Type } from "@sinclair/typebox";
-import { canonicalPath } from "../adapters/canonical-path.ts";
+import {
+  resolveEvidenceContext,
+  withEvidenceContext,
+} from "../adapters/evidence-context.ts";
 import { collectSearchExcerpts } from "../adapters/files.ts";
 import { prefilter } from "../adapters/find.ts";
 import { shareGitInventory } from "../adapters/git-inventory.ts";
@@ -19,16 +22,29 @@ import {
   type EnvelopeInput,
 } from "../core/output.ts";
 import { needsReverse, pointerQuestion, readPointer } from "../core/pointer.ts";
+import {
+  type Action,
+  answerItemFromInput,
+  buildResultReport,
+  type Cause,
+  contextFromEvidence,
+  type Diagnostic,
+  type Item,
+  known,
+  type RawValue,
+} from "../core/result-report.ts";
+import { secretRefusal } from "../core/secret-path.ts";
 import { interpolate } from "../describe.ts";
 import type { GuideContext } from "../guide.ts";
-import type { Judgment, Question, State } from "../jev/types.ts";
-import { renderEnvelope } from "../render.ts";
+import type { Answer, Judgment, Question, State } from "../jev/types.ts";
+import { renderResultReport } from "../render.ts";
 import type { ToolDependencies } from "../runtime.ts";
 import { NOT_CONFIGURED } from "../texts/configuration.ts";
 import { FIND_DESCRIPTION } from "../texts/find.ts";
 
 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(
@@ -75,7 +91,13 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
       ctx: { cwd: string } & GuideContext,
     ) {
       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 = {
@@ -90,6 +112,101 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
       const unchecked: string[] = [];
       let budget: BudgetRefusal | undefined;
       let sent = 0;
+      const context = contextFromEvidence(evidenceContext);
+      const diagnostics: Diagnostic[] = [];
+      const actions: Action[] = [];
+      const auxiliary = {
+        controls: { fresh: 0, cache: 0, notJudged: 0, static: 0 },
+        passages: { fresh: 0, cache: 0, notJudged: 0 },
+      };
+      let entryPaths: string[] = [];
+      let costObserved = true;
+      let failureCause: Cause = "invalid_response";
+      let primary: Answer | undefined;
+      let confirmation: Answer | undefined;
+      let confirmationRequired = false;
+      const raw = (answer: Answer): RawValue[] =>
+        answer.type === "choice"
+          ? Object.entries(answer.probabilities).map(
+              ([label, probability]) => ({
+                label,
+                value: label,
+                probability: known(probability),
+              }),
+            )
+          : [];
+      const diagnostic = (
+        cause: Cause,
+        fact: string,
+        members: string[] = [],
+      ) => {
+        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: Omit<EnvelopeInput, "yield">) => {
         const envelope = buildEnvelope({
           ...input,
@@ -101,15 +218,166 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
             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" as const,
+          label: "entry",
+          groupId: "entry",
+          evidence: entryPaths.map((path) => ({
+            target: path,
+            canonicalPath: known(`${cwd}/${path}`),
+            aliases: [],
+            side: "current" as const,
+            revision: context.resolvedBase,
+          })),
+          diagnosticIds: diagnostics.map((d) => d.id),
+          actionIds: actions.map((a) => a.id),
+        };
+        let item: 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" as const, text: renderEnvelope(envelope) }],
-          details: totals,
+          content: [
+            {
+              type: "text" as const,
+              text: renderResultReport(report, {
+                details: {
+                  lines: [
+                    ...envelope.lines,
+                    ...(entryLine?.type === "entry"
+                      ? [
+                          {
+                            type: "list" as const,
+                            title: "read",
+                            items: [...(entryLine.nextRead ?? [])],
+                          },
+                          {
+                            type: "list" as const,
+                            title: "auxiliary ranking",
+                            items: (entryLine.relevant ?? []).map(
+                              (candidate) =>
+                                `${candidate.label} (${candidate.value.p})`,
+                            ),
+                          },
+                        ]
+                      : []),
+                    {
+                      type: "list" as const,
+                      title: "discovery reservations",
+                      items: [...limitations, ...(input.limitations ?? [])].map(
+                        (limit) => limit.fact,
+                      ),
+                    },
+                  ],
+                },
+              }),
+            },
+          ],
+          details: { ...totals, evidenceContext, result: report },
           ...hostUsage(host.isOmp, totals.usage),
         };
       };
-      if (!client) return finish({ refusal: NOT_CONFIGURED });
+      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)
@@ -139,7 +407,30 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
         args.exclude,
         signal,
       );
-      if (!candidates.ok) return finish({ refusal: candidates.error });
+      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: string,
         p: number,
@@ -175,21 +466,24 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
               ],
       });
       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: State,
         questions: Record<string, Question>,
       ): Promise<Judgment> => {
+        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(),
@@ -210,6 +504,8 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
             return admission;
           },
           onUsage: (usage) => runtime.session.recordUsage(usage),
+          admissionCause: () =>
+            budget?.kind === "max_calls" ? "call_budget" : "session_budget",
         });
         for (const key of [
           "calls",
@@ -219,7 +515,21 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
         ] as const)
           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 = (
@@ -270,6 +580,12 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
       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: [
@@ -317,7 +633,10 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
             signal,
             exec,
           );
-          if (!read.ok) return { paths, result: read };
+          if (!read.ok) {
+            failureCause = read.cause ?? "file_unavailable";
+            return { paths, result: read };
+          }
           Object.assign(files, read.pointers);
           limitations.push(
             ...read.limits.map((limit) => ({
@@ -325,11 +644,18 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
               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,
           );
@@ -398,12 +724,26 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
           ],
         });
       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}`]),
       );
@@ -437,6 +777,7 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
       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();
@@ -459,14 +800,30 @@ export function createFindFilesTool(dependencies: ToolDependencies) {
           (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,