jev-agent-tools 0.2.0 → 0.3.0

package/src/core/locate.ts

@@ -29,11 +29,12 @@ export function sectionStateFits(
   goal: string,
   sections: readonly Section[],
   outline = false,
+  maxChars = STATE_MAX_CHARS,
 ): boolean {
   return (
     sections.length < CHOICE_MAX_OPTIONS &&
     JSON.stringify(sectionState(path, goal, sections, outline)).length <=
-      STATE_MAX_CHARS
+      maxChars
   );
 }
 /** Every planned block has at least two sections and fits its full-text refinement budget. */
@@ -41,6 +42,7 @@ export function sectionOutline(
   path: string,
   goal: string,
   sections: readonly Section[],
+  maxChars = STATE_MAX_CHARS,
 ): Section[] {
   const base = JSON.stringify(sectionState(path, goal, [])).length;
   const costs = new Map(
@@ -58,18 +60,18 @@ export function sectionOutline(
   const fits = (items: readonly Section[]) =>
     items.length < CHOICE_MAX_OPTIONS &&
     base + items.reduce((sum, item) => sum + (costs.get(item) ?? 0) + 1, 0) <=
-      STATE_MAX_CHARS;
+      maxChars;
   const groups: Section[][] = [];
   let current: Section[] = [],
     currentSize = base;
   for (const section of sections) {
     const length = (costs.get(section) ?? 0) + 1;
-    if (base + length > STATE_MAX_CHARS) return [];
+    if (base + length > maxChars) return [];
     const owner = section.label.split(".")[0],
       previousOwner = current.at(-1)?.label.split(".")[0];
     if (
       current.length &&
-      (currentSize + length > STATE_MAX_CHARS ||
+      (currentSize + length > maxChars ||
         current.length + 1 >= CHOICE_MAX_OPTIONS ||
         (current.length >= 2 &&
           section.label.includes(".") &&
@@ -131,6 +133,7 @@ export function outlineEvidence(
   path: string,
   goal: string,
   blocks: readonly Section[],
+  maxChars = STATE_MAX_CHARS,
 ): Section[] {
   const overhead = JSON.stringify(
     sectionState(
@@ -139,7 +142,7 @@ export function outlineEvidence(
       blocks.map((block) => ({ ...block, text: "" })),
     ),
   ).length;
-  let remaining = Math.max(0, STATE_MAX_CHARS - overhead);
+  let remaining = Math.max(0, maxChars - overhead);
   const allocations = blocks.map(() => 0);
   let active = blocks.map((_, index) => index);
   while (remaining > 0 && active.length) {

package/src/core/output.ts

@@ -6,6 +6,7 @@ import {
   LIMIT_DISPLAY_MAX_PATHS,
 } from "../constants.ts";
 import type { Answer } from "../jev/types.ts";
+import type { Item, RawValue } from "../result-types.ts";
 
 export interface Limitation {
   fact: string;
@@ -39,6 +40,14 @@ interface CandidateFields {
 export type BandPolicy = (value: DisplayValue, input: AnswerInput) => Band;
 export type BudgetRefusal = { kind: "max_calls" | "session"; message: string };
 export interface AnswerInput extends CandidateFields {
+  unjudged?: boolean;
+  source?: "fresh" | "cache";
+  publicResult?: string | number | boolean;
+  rawValues?: RawValue[];
+  reportControls?: Extract<
+    Item,
+    { treatment: "judged" }
+  >["judgment"]["controls"];
   label: string;
   answer?: Exclude<Answer, { type: "unjudged" }>;
   value?: DisplayValue;
@@ -55,6 +64,13 @@ export type OutputLine =
       value: DisplayValue;
       band: Band;
       uncalibrated: boolean;
+      source?: "fresh" | "cache";
+      publicResult?: string | number | boolean;
+      rawValues?: RawValue[];
+      reportControls?: Extract<
+        Item,
+        { treatment: "judged" }
+      >["judgment"]["controls"];
       reason?: string;
     })
   | { type: "unjudged"; label: string; reason: string; next: string }
@@ -163,6 +179,16 @@ export function buildEnvelope(input: EnvelopeInput): Envelope {
     .map((control) => control.fact)
     .join("; ");
   for (const item of input.answers ?? []) {
+    if (item.unjudged) {
+      lines.push({
+        type: "unjudged",
+        label: item.label,
+        reason: item.reason ?? "required group answer missing",
+        next:
+          item.missing ?? "inspect the available evidence without a judgment",
+      });
+      continue;
+    }
     const value = displayValue(item);
     const initial = item.band ?? (input.policy ?? askBand)(value, item);
     const band = initial === "verdict" && failed ? "unsure" : initial;
@@ -180,6 +206,14 @@ export function buildEnvelope(input: EnvelopeInput): Envelope {
       value,
       band,
       uncalibrated: item.uncalibrated ?? false,
+      ...((item.source ?? item.answer?.source)
+        ? { source: item.source ?? item.answer?.source }
+        : {}),
+      ...(item.publicResult !== undefined
+        ? { publicResult: item.publicResult }
+        : {}),
+      ...(item.rawValues ? { rawValues: item.rawValues } : {}),
+      ...(item.reportControls ? { reportControls: item.reportControls } : {}),
       ...(reason ? { reason } : {}),
       ...(item.orderDependent !== undefined
         ? { orderDependent: item.orderDependent }

package/src/core/result-report.ts

@@ -0,0 +1,410 @@
+import type {
+  Accounting,
+  Action,
+  Context,
+  Diagnostic,
+  Inventory,
+  Item,
+  ItemCommon,
+  Knowledge,
+  ResultReportV1,
+  Scope,
+  Tool,
+} from "../result-types.ts";
+import { type AnswerInput, askBand, type Yield } from "./output.ts";
+
+export type {
+  Accounting,
+  Action,
+  Cause,
+  Context,
+  Diagnostic,
+  Execution,
+  Inventory,
+  Item,
+  ItemCommon,
+  Knowledge,
+  McpStructuredResultV1,
+  RawValue,
+  ResultReportV1,
+  Scope,
+  Tool,
+} from "../result-types.ts";
+/** Structural input prevents the pure core from depending on adapters. */
+export interface EvidenceContextInput {
+  authority?: { path: string; origin: "host" | "server" };
+  authorityReason?: string;
+  requestedRoot?: string;
+  effectiveRoot?: {
+    path: string;
+    origin: "host" | "server" | "override";
+    commonDir?: string;
+  };
+  requestedBase?: string;
+  resolvedBase?: string;
+}
+
+export const known = <T>(value: T): Knowledge<T> => ({
+  status: "known",
+  value,
+});
+export const unknown = (reason: string): Knowledge<never> => ({
+  status: "unknown",
+  reason,
+});
+export const notApplicable = (reason: string): Knowledge<never> => ({
+  status: "not_applicable",
+  reason,
+});
+export const notCollected = (reason: string): Knowledge<never> => ({
+  status: "not_collected",
+  reason,
+});
+
+export function uncollectedContext(input: {
+  authority: Context["authority"];
+  requestedRoot?: Knowledge<string>;
+  requestedBase?: Knowledge<string>;
+  command?: Context["command"];
+}): Context {
+  return {
+    authority: input.authority,
+    requestedRoot:
+      input.requestedRoot ?? notApplicable("no override requested"),
+    effectiveRoot: unknown("effective root not established"),
+    requestedBase: input.requestedBase ?? notApplicable("no base requested"),
+    resolvedBase: input.requestedBase
+      ? notCollected("base resolution not performed")
+      : notApplicable("no base requested"),
+    inventories: [],
+    command: input.command ?? {
+      execution: "not_requested",
+      cwd: notApplicable("no command"),
+      exitCode: notApplicable("no command"),
+      timedOut: notApplicable("no command"),
+    },
+  };
+}
+
+export function contextFromEvidence(
+  evidence: EvidenceContextInput | undefined,
+  options: {
+    inventories?: Inventory[];
+    command?: Context["command"];
+  } = {},
+): Context {
+  const context = uncollectedContext({
+    authority: evidence?.authorityReason
+      ? unknown(evidence.authorityReason)
+      : evidence?.authority
+        ? known(evidence.authority)
+        : unknown("canonical authority not established"),
+    ...(evidence?.requestedRoot !== undefined
+      ? { requestedRoot: known(evidence.requestedRoot) }
+      : {}),
+    ...(evidence?.requestedBase !== undefined
+      ? { requestedBase: known(evidence.requestedBase) }
+      : {}),
+    ...(options.command ? { command: options.command } : {}),
+  });
+  if (evidence?.effectiveRoot)
+    context.effectiveRoot = known({
+      path: evidence.effectiveRoot.path,
+      origin: evidence.effectiveRoot.origin,
+      commonDir:
+        evidence.effectiveRoot.commonDir === undefined
+          ? unknown("Git common directory not collected")
+          : known(evidence.effectiveRoot.commonDir),
+    });
+  if (evidence?.resolvedBase !== undefined)
+    context.resolvedBase = known(evidence.resolvedBase);
+  else if (evidence?.requestedBase !== undefined)
+    context.resolvedBase = unknown("requested base not resolved");
+  context.inventories = options.inventories ?? [];
+  return context;
+}
+
+export interface ReportInput {
+  tool: Tool;
+  context: Context;
+  items: Item[];
+  diagnostics: Diagnostic[];
+  actions: Action[];
+  metrics: Yield;
+  auxiliary: Accounting["auxiliary"];
+  total: Knowledge<number>;
+  /** Call-wide input/admission refusal, not a refusal of one group. */
+  refused?: boolean;
+  /** Explicit missing requested/candidate work outside enumerated items. */
+  missingWork?: boolean;
+}
+
+export function buildResultReport(input: ReportInput): ResultReportV1 {
+  const counts = { fresh: 0, cache: 0, notJudged: 0, static: 0 };
+  for (const item of input.items) {
+    if (item.treatment === "judged") counts[item.source]++;
+    else if (item.treatment === "static") counts.static++;
+    else counts.notJudged++;
+  }
+  const admissible = counts.fresh + counts.cache + counts.static;
+  const usefulFallback = input.items.some(
+    (item) => item.treatment === "not_judged" && item.selection?.selected,
+  );
+  const missing =
+    input.missingWork ||
+    counts.notJudged > 0 ||
+    input.diagnostics.some(
+      (d) => d.cause === "criteria_no_match" || d.effect === "blocking",
+    );
+  const report: ResultReportV1 = {
+    schemaVersion: 1,
+    tool: input.tool,
+    execution:
+      !admissible && !usefulFallback
+        ? input.refused
+          ? "refused"
+          : "not_judged"
+        : missing
+          ? "partial"
+          : "complete",
+    context: input.context,
+    items: input.items,
+    diagnostics: input.diagnostics,
+    actions: input.actions,
+    accounting: {
+      toolInvocations: 1,
+      httpAttempts: input.metrics.calls,
+      questionsSent: input.metrics.questions,
+      cacheHits: input.metrics.cacheHits,
+      cacheRequests: input.metrics.cacheRequests,
+      requestedResults: { total: input.total, ...counts },
+      auxiliary: input.auxiliary,
+      costUsd:
+        input.metrics.costUsd === undefined
+          ? unknown("current request cost not reported")
+          : known(input.metrics.costUsd),
+      elapsedMs: input.metrics.elapsedMs,
+    },
+  };
+  const errors = validateResultReport(report);
+  if (errors.length)
+    throw new Error(`Invalid ResultReportV1: ${errors.join("; ")}`);
+  return report;
+}
+
+/** Semantic checks complement, rather than replace, the public JSON Schema. */
+export function validateResultReport(report: ResultReportV1): string[] {
+  const errors: string[] = [];
+  const counter = (value: number, label: string) => {
+    if (!Number.isSafeInteger(value) || value < 0)
+      errors.push(`invalid counter ${label}`);
+  };
+  const measurement = (
+    value: Knowledge<number>,
+    label: string,
+    probability = false,
+  ) => {
+    if (
+      value.status === "known" &&
+      (!Number.isFinite(value.value) ||
+        value.value < 0 ||
+        (probability && value.value > 1))
+    )
+      errors.push(`invalid measure ${label}`);
+  };
+  const accounting = report.accounting;
+  for (const key of [
+    "httpAttempts",
+    "questionsSent",
+    "cacheHits",
+    "cacheRequests",
+  ] as const)
+    counter(accounting[key], key);
+  if (!Number.isFinite(accounting.elapsedMs) || accounting.elapsedMs < 0)
+    errors.push("invalid elapsedMs");
+  measurement(accounting.costUsd, "costUsd");
+  for (const [kind, values] of Object.entries(accounting.auxiliary))
+    for (const [source, value] of Object.entries(values))
+      counter(value, `${kind}.${source}`);
+  for (const inv of report.context.inventories) {
+    for (const [name, value] of [
+      ["discovered", inv.discovered],
+      ["considered", inv.considered],
+    ] as const)
+      if (value.status === "known") counter(value.value, `${inv.id}.${name}`);
+    for (const criterion of inv.criteria)
+      if (criterion.matches.status === "known")
+        counter(criterion.matches.value, `${inv.id}.matches`);
+  }
+  const ids = (values: { id: string }[], label: string) => {
+    const set = new Set(values.map((v) => v.id));
+    if (set.size !== values.length) errors.push(`duplicate ${label} IDs`);
+    return set;
+  };
+  const items = ids(report.items, "item");
+  const diagnostics = ids(report.diagnostics, "diagnostic");
+  const actions = ids(report.actions, "action");
+  const inventories = ids(report.context.inventories, "inventory");
+  const groups = new Set(report.items.map((i) => i.groupId));
+  const refs = (values: string[], set: Set<string>, label: string) => {
+    for (const id of values)
+      if (!set.has(id)) errors.push(`unknown ${label} ID ${id}`);
+  };
+  const scope = (s: Scope) => {
+    if (s.kind === "item") refs(s.itemIds, items, "item");
+    else if (s.kind === "group") refs(s.groupIds, groups, "group");
+    else if (s.kind === "inventory")
+      refs(s.inventoryIds, inventories, "inventory");
+  };
+  for (const item of report.items) {
+    refs(item.diagnosticIds, diagnostics, "diagnostic");
+    refs(item.actionIds, actions, "action");
+    if (item.treatment === "judged") {
+      ids(item.judgment.controls, `control in ${item.id}`);
+      measurement(item.judgment.measure.value, `${item.id}.measure`, true);
+      for (const raw of [
+        ...item.judgment.rawValues,
+        ...item.judgment.controls.flatMap((c) => c.rawValues),
+      ])
+        measurement(raw.probability, `${item.id}.${raw.label}`, true);
+      if (
+        typeof item.judgment.result === "number" &&
+        !Number.isFinite(item.judgment.result)
+      )
+        errors.push(`invalid result ${item.id}`);
+    }
+  }
+  for (const d of report.diagnostics) {
+    scope(d.scope);
+    refs(d.actionIds, actions, "action");
+  }
+  for (const a of report.actions) scope(a.scope);
+  for (const inv of report.context.inventories)
+    for (const criterion of inv.criteria)
+      refs(criterion.diagnosticIds, diagnostics, "diagnostic");
+  const c = report.accounting.requestedResults;
+  for (const key of ["fresh", "cache", "static", "notJudged"] as const)
+    counter(c[key], `requestedResults.${key}`);
+  if (c.total.status === "known")
+    counter(c.total.value, "requestedResults.total");
+  const actual = { fresh: 0, cache: 0, static: 0, notJudged: 0 };
+  for (const i of report.items) {
+    if (i.treatment === "judged") actual[i.source]++;
+    else if (i.treatment === "static") actual.static++;
+    else actual.notJudged++;
+  }
+  for (const key of ["fresh", "cache", "static", "notJudged"] as const)
+    if (c[key] !== actual[key])
+      errors.push(`requestedResults.${key} does not match items`);
+  if (c.total.status === "known" && c.total.value !== report.items.length)
+    errors.push("known requested total does not match items");
+  const admissible = actual.fresh + actual.cache + actual.static;
+  const usefulFallback = report.items.some(
+    (item) => item.treatment === "not_judged" && item.selection?.selected,
+  );
+  if (
+    (report.execution === "refused" || report.execution === "not_judged") &&
+    (admissible || usefulFallback)
+  )
+    errors.push("non-result execution has admissible items or useful fallback");
+  if (
+    (report.execution === "complete" || report.execution === "partial") &&
+    !admissible &&
+    !usefulFallback
+  )
+    errors.push("result execution has no admissible items or useful fallback");
+  if (
+    report.execution === "complete" &&
+    (actual.notJudged ||
+      report.diagnostics.some(
+        (d) => d.effect === "blocking" || d.cause === "criteria_no_match",
+      ))
+  )
+    errors.push("complete execution omits requested work");
+  if (!admissible && !report.diagnostics.length)
+    errors.push("absent judgment needs an explicit cause");
+  return errors;
+}
+
+export function resultIsError(report: ResultReportV1): boolean {
+  if (report.execution === "refused") return true;
+  if (
+    report.items.some(
+      (i) => i.treatment !== "not_judged" || i.selection?.selected,
+    )
+  )
+    return false;
+  return report.diagnostics.some(
+    (d) =>
+      d.effect === "blocking" &&
+      [
+        "provider_context_refusal",
+        "not_configured",
+        "service_unavailable",
+        "transport_failure",
+        "invalid_response",
+        "internal_error",
+      ].includes(d.cause),
+  );
+}
+
+/** Source must be established by the client, never guessed from footer totals. */
+export function answerItemFromInput(
+  common: ItemCommon,
+  input: AnswerInput,
+): Item {
+  if (input.unjudged)
+    return { ...common, treatment: "not_judged", source: "none" };
+  const source = input.source ?? input.answer?.source;
+  if (source !== "fresh" && source !== "cache")
+    throw new Error(`Answer source not established: ${common.id}`);
+  const value = input.value;
+  const answer = input.answer;
+  if (!value && !answer)
+    throw new Error(`Answer value not established: ${common.id}`);
+  const result =
+    input.publicResult ??
+    (answer?.type === "bool"
+      ? answer.p >= 0.5
+      : (value?.head ??
+        (answer?.type === "choice" ? answer.choice : answer?.score)));
+  if (result === undefined)
+    throw new Error(`Answer result not established: ${common.id}`);
+  const p =
+    value?.p ??
+    (answer?.type === "bool"
+      ? answer.p
+      : answer
+        ? Math.max(...Object.values(answer.probabilities))
+        : undefined);
+  return {
+    ...common,
+    treatment: "judged",
+    source,
+    judgment: {
+      band:
+        input.band ??
+        (p === undefined
+          ? "unsure"
+          : askBand(
+              {
+                head: typeof result === "boolean" ? String(result) : result,
+                p,
+              },
+              input,
+            )),
+      result,
+      measure: {
+        kind: "probability",
+        value:
+          p === undefined
+            ? unknown("leading probability not collected")
+            : known(p),
+      },
+      reason: input.reason ?? "",
+      uncalibrated: input.uncalibrated ?? false,
+      rawValues: input.rawValues ?? [],
+      controls: input.reportControls ?? [],
+    },
+  };
+}

package/src/core/secret-path.ts

@@ -0,0 +1,37 @@
+/** Base-name globs of likely secret files, matched case-insensitively. */
+export const SECRET_NAME_GLOBS = [
+  ".env",
+  ".env.*",
+  "*.pem",
+  "id_rsa*",
+  "*.p12",
+  "credentials*",
+  "secrets*",
+] as const;
+/** Value-free templates that stay admitted despite the `.env.*` rule. */
+const templates = [".env.example", ".env.sample", ".env.template"];
+
+/**
+ * True when a path's base name matches SECRET_NAME_GLOBS (any depth,
+ * case-insensitive) and is not a value-free `.env` template. Such files are
+ * refused before their content is read, on every evidence admission path;
+ * there is no per-call override.
+ */
+export function isSecretPath(path: string): boolean {
+  const name = (path.split(/[\\/]/).pop() ?? "").toLowerCase();
+  if (templates.includes(name)) return false;
+  return (
+    name === ".env" ||
+    name.startsWith(".env.") ||
+    name.endsWith(".pem") ||
+    name.startsWith("id_rsa") ||
+    name.endsWith(".p12") ||
+    name.startsWith("credentials") ||
+    name.startsWith("secrets")
+  );
+}
+
+/** Refusal text for a secret-named path: names the path, never its content. */
+export function secretRefusal(path: string): string {
+  return `${path}: secret file name (secret_pattern): content not read, not sent to Jev`;
+}

package/src/core/state.ts

@@ -2,7 +2,14 @@ import { ASK_NOTE_MAX_CHARS, STATE_MAX_CHARS } from "../constants.ts";
 import type { State } from "../jev/types.ts";
 import { isRecord, type Result } from "../result.ts";
 
-const reservedKeys = ["files", "files_before", "base_sha", "closure"] as const;
+const reservedKeys = [
+  "files",
+  "files_before",
+  "base_sha",
+  "closure",
+  "evidence",
+  "output",
+] as const;
 
 export function assembleState(
   note: string | undefined,

package/src/core/units.ts

@@ -5,7 +5,7 @@ import { truncate } from "./truncate.ts";
 export interface SourceFile extends DiffFile {
   before: string | null;
   after: string | null;
-  limitation?: "too_large" | "unreadable" | "not UTF-8 text";
+  limitation?: "too_large" | "unreadable" | "not UTF-8 text" | "secret_pattern";
 }
 export interface Declaration {
   kind: "function" | "declaration";
@@ -43,6 +43,7 @@ export type UnitLimit =
         | "too_large"
         | "unreadable"
         | "not UTF-8 text"
+        | "secret_pattern"
         | "rename_unpaired";
       file: string;
     }
@@ -148,7 +149,7 @@ export function buildUnits(
   const units: EvidenceUnit[] = [];
   const limits: UnitLimit[] = [];
   for (const file of files) {
-    if (isTestFile(file.path)) continue;
+    if (isTestFile(file.path) && file.limitation !== "secret_pattern") continue;
     if (file.binary) {
       limits.push({ kind: "binary_ignored", file: file.path });
       continue;

package/src/index.ts

@@ -34,6 +34,9 @@ export default function extension(api: ExtensionAPI & { pi?: unknown }): void {
     get client() {
       return config.client;
     },
+    get apiKey() {
+      return config.values().apiKey || undefined;
+    },
     host,
     runtime,
     exec: api.exec.bind(api),