jev-layer 0.1.0 → 0.3.0

package/src/route.mjs

@@ -1,221 +1,228 @@
-import { byteLength, decisionEnvelope, normalizeRequest } from "./contract.mjs";
-import { projectState } from "./context-filter.mjs";
-import { discoverCapabilities } from "./discovery.mjs";
-import { decisionCandidates, DEFAULT_POLICY, deterministicCandidate, filterCapabilities, normalizeCapabilities } from "./registry.mjs";
-import { DemoProvider } from "./providers/demo.mjs";
-import { OpenRouterDecisionsProvider, TypeSafeProvider } from "./providers/typesafe.mjs";
-
-export async function routeRequest(input, options = {}) {
-  const discovered = options.discovery ? discoverCapabilities(options.discovery) : [];
-  const request = normalizeRequest(discovered.length ? { ...input, capabilities: [...(Array.isArray(input?.capabilities) ? input.capabilities : []), ...discovered] } : input);
-  if (options.engine === "jevrouter") return routeViaJevRouter(request, options);
-
-  const started = performance.now();
-  const effectivePolicy = { ...DEFAULT_POLICY, ...request.policy, ...(options.policy ?? {}) };
-  const capabilities = normalizeCapabilities(request.capabilities);
-  const { policy, assessments, eligible } = filterCapabilities(capabilities, request, effectivePolicy);
-  const projection = projectState(request, eligible, options.maxContextBytes ?? 6_000, { mode: options.contextFilterMode });
-  const provider = resolveProvider(options.provider ?? "demo", options);
-  const base = {
-    provider: provider.name,
-    candidateCount: eligible.length,
-    contextBytes: projection.context_bytes,
-    started,
-  };
-
-  if (process.env.JEV_LAYER_ENABLED === "0") {
-    return fallback(base, assessments, "disabled", "Jev layer disabled by JEV_LAYER_ENABLED=0", projection.state);
-  }
-  if (eligible.length === 0) {
-    return decisionEnvelope({
-      status: "no_decision",
-      reason: "no capability passed availability, risk, and permission policy",
-      provider: provider.name,
-      latencyMs: elapsed(started),
-      candidateCount: 0,
-      contextBytes: projection.context_bytes,
-      candidates: decisionCandidates(assessments),
-    });
-  }
-  const deterministic = policy.deterministic === true
-    ? deterministicCandidate(eligible, policy)
-    : null;
-  if (deterministic) {
-    const selected = deterministic.capability;
-    const probabilities = Object.fromEntries(eligible.map((candidate) => [candidate.id, candidate.id === selected.id ? 1 : 0]));
-    const candidates = decisionCandidates(assessments, probabilities, 1);
-    const requiresConfirmation = policy.confirmation_risk_levels.includes(selected.risk) || selected.requires_confirmation;
-    return decisionEnvelope({
-      status: requiresConfirmation ? "needs_confirmation" : "selected",
-      reason: deterministic.reason,
-      provider: `${provider.name}:deterministic`,
-      latencyMs: elapsed(started),
-      candidateCount: eligible.length,
-      contextBytes: projection.context_bytes,
-      candidates,
-      selected: selected.id,
-      probabilities,
-      confidence: 1,
-    });
-  }
-
-  let raw;
-  try {
-    raw = await provider.decide({ state: projection.state, candidates: eligible });
-  } catch (error) {
-    return fallback(base, assessments, "provider_error", error instanceof Error ? error.message : String(error), projection.state);
-  }
-
-  let answer;
-  try {
-    answer = readChoiceAnswer(raw);
-  } catch (error) {
-    return fallback(base, assessments, "malformed_response", error instanceof Error ? error.message : String(error), projection.state, raw);
-  }
-
-  const selected = eligible.find((candidate) => candidate.id === answer.choice);
-  const candidates = decisionCandidates(assessments, answer.probabilities, answer.confidence);
-  if (!selected) {
-    return decisionEnvelope({
-      status: "fallback",
-      reason: `provider selected unknown or filtered capability: ${answer.choice}`,
-      provider: provider.name,
-      latencyMs: elapsed(started),
-      candidateCount: eligible.length,
-      contextBytes: projection.context_bytes,
-      candidates,
-      probabilities: answer.probabilities,
-      confidence: answer.confidence,
-      rawJev: raw,
-      fallback: { type: "invalid_selection", reason: "selection is not in the eligible candidate set" },
-    });
-  }
-  if (answer.confidence < policy.min_confidence) {
-    return decisionEnvelope({
-      status: "fallback",
-      reason: `confidence ${answer.confidence.toFixed(3)} is below policy minimum ${policy.min_confidence.toFixed(3)}`,
-      provider: provider.name,
-      latencyMs: elapsed(started),
-      candidateCount: eligible.length,
-      contextBytes: projection.context_bytes,
-      candidates,
-      selected: selected.id,
-      probabilities: answer.probabilities,
-      confidence: answer.confidence,
-      rawJev: raw,
-      fallback: { type: "low_confidence", reason: "host must continue with normal planning" },
-    });
-  }
-
-  const requiresConfirmation = policy.confirmation_risk_levels.includes(selected.risk) || selected.requires_confirmation;
-  return decisionEnvelope({
-    status: requiresConfirmation ? "needs_confirmation" : "selected",
-    reason: requiresConfirmation ? "selected capability requires host confirmation" : "selected by bounded Jev decision",
-    provider: provider.name,
-    latencyMs: elapsed(started),
-    candidateCount: eligible.length,
-    contextBytes: projection.context_bytes,
-    candidates,
-    selected: selected.id,
-    probabilities: answer.probabilities,
-    confidence: answer.confidence,
-    rawJev: raw,
-  });
-}
-
-function resolveProvider(provider, options) {
-  if (provider && typeof provider === "object" && typeof provider.decide === "function") return provider;
-  if (provider === "demo") return new DemoProvider();
-  if (provider === "openrouter") return new OpenRouterDecisionsProvider(options.openrouter);
-  throw new Error(`unsupported provider: ${provider}`);
-}
-
-function readChoiceAnswer(raw) {
-  const answers = raw?.answers;
-  if (!answers || typeof answers !== "object") throw new Error("response has no answers object");
-  const answer = answers.tool ?? Object.values(answers).find((value) => value?.type === "choice");
-  if (!answer || answer.type !== "choice" || typeof answer.choice !== "string" || !answer.probabilities || typeof answer.probabilities !== "object") {
-    throw new Error("response does not contain a valid Choice answer");
-  }
-  const probabilities = Object.fromEntries(Object.entries(answer.probabilities).map(([id, value]) => {
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) throw new Error(`invalid probability for ${id}`);
-    return [id, value];
-  }));
-  const confidence = typeof answer.confidence === "number" ? answer.confidence : Math.max(...Object.values(probabilities), 0);
-  if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error("invalid confidence");
-  return { choice: answer.choice, probabilities, confidence };
-}
-
-function fallback(base, assessments, type, reason, state, rawJev = null) {
-  return decisionEnvelope({
-    status: "fallback",
-    reason,
-    provider: base.provider,
-    latencyMs: elapsed(base.started),
-    candidateCount: base.candidateCount,
-    contextBytes: byteLength(state),
-    candidates: decisionCandidates(assessments),
-    rawJev,
-    fallback: { type, reason },
-  });
-}
-
-function elapsed(started) {
-  return Number((performance.now() - started).toFixed(3));
-}
-
-async function routeViaJevRouter(request, options) {
-  const started = performance.now();
-  const capabilities = normalizeCapabilities(request.capabilities);
-  const { assessments, eligible } = filterCapabilities(capabilities, request, { ...DEFAULT_POLICY, ...request.policy, ...(options.policy ?? {}) });
-  const projection = projectState(request, eligible, options.maxContextBytes ?? 6_000, { mode: options.contextFilterMode });
-  if (eligible.length === 0) return decisionEnvelope({ status: "no_decision", reason: "no eligible capability", provider: "jevrouter", latencyMs: elapsed(started), candidateCount: 0, contextBytes: projection.context_bytes, candidates: decisionCandidates(assessments) });
-
-  let module;
-  try {
-    module = await import("jevrouter");
-  } catch (error) {
-    return fallback({ provider: "jevrouter", candidateCount: eligible.length, contextBytes: projection.context_bytes, started }, assessments, "dependency_error", error instanceof Error ? error.message : String(error), projection.state);
-  }
-  try {
-    const result = await module.route({
-      request: request.intent,
-      context: projection.state.context,
-      candidates: eligible.map(toJevRouterCapability),
-    }, {
-      provider: options.innerProvider ?? process.env.JEVROUTER_PROVIDER ?? "demo",
-      policy: options.policy,
-    });
-    const selected = result.decision?.selected ?? null;
-    const raw = result.raw_jev ?? null;
-    const candidates = decisionCandidates(assessments, Object.fromEntries((result.decision?.candidates ?? []).map((candidate) => [candidate.id, candidate.jev_probability ?? 0])), null);
-    return decisionEnvelope({
-      status: result.status === "selected" ? "selected" : result.status === "needs_confirmation" ? "needs_confirmation" : "fallback",
-      selected,
-      reason: result.fallback?.reason ?? "selected by JevRouter",
-      provider: `jevrouter:${options.innerProvider ?? process.env.JEVROUTER_PROVIDER ?? "demo"}`,
-      latencyMs: elapsed(started),
-      candidateCount: eligible.length,
-      contextBytes: projection.context_bytes,
-      candidates,
-      rawJev: raw,
-      fallback: result.fallback?.type ? { type: result.fallback.type, reason: result.fallback.reason } : null,
-    });
-  } catch (error) {
-    return fallback({ provider: "jevrouter", candidateCount: eligible.length, contextBytes: projection.context_bytes, started }, assessments, "provider_error", error instanceof Error ? error.message : String(error), projection.state);
-  }
-}
-
-function toJevRouterCapability(capability) {
-  return {
-    id: capability.id,
-    name: capability.name,
-    type: capability.kind === "mcp" ? "mcp_tool" : capability.kind,
-    description: capability.description,
-    permissions: capability.permissions,
-    risk: { level: capability.risk },
-    availability: { available: capability.available },
-    execution: { mode: capability.kind === "mcp" ? "mcp" : capability.kind, target: capability.execution.target },
-    policy: { requires_confirmation: capability.requires_confirmation },
-  };
-}
+import { byteLength, decisionEnvelope, normalizeRequest } from "./contract.mjs";
+import { projectState } from "./context-filter.mjs";
+import { discoverCapabilities } from "./discovery.mjs";
+import { decisionCandidates, DEFAULT_POLICY, deterministicCandidate, filterCapabilities, normalizeCapabilities } from "./registry.mjs";
+import { resolveProvider } from "./providers/index.mjs";
+import { normalizeImageAssets } from "./images.mjs";
+
+export async function routeRequest(input, options = {}) {
+  const discovered = options.discovery ? discoverCapabilities(options.discovery) : [];
+  const request = normalizeRequest(discovered.length ? { ...input, capabilities: [...(Array.isArray(input?.capabilities) ? input.capabilities : []), ...discovered] } : input);
+  if (options.engine === "jevrouter" && !input.assets && !input.assets_omitted) return routeViaJevRouter(request, options);
+
+  const started = performance.now();
+  const effectivePolicy = { ...DEFAULT_POLICY, ...request.policy, ...(options.policy ?? {}) };
+  const capabilities = normalizeCapabilities(request.capabilities);
+  const { policy, assessments, eligible } = filterCapabilities(capabilities, request, effectivePolicy);
+  const projection = projectState(request, eligible, options.maxContextBytes ?? 6_000, { mode: options.contextFilterMode });
+  const base = {
+    provider: typeof options.provider === "string" ? options.provider : options.provider?.name ?? "jev-demo",
+    candidateCount: eligible.length,
+    contextBytes: projection.context_bytes,
+    started,
+  };
+
+  if (process.env.JEV_LAYER_ENABLED === "0") {
+    return fallback(base, assessments, "disabled", "Jev layer disabled by JEV_LAYER_ENABLED=0", projection.state);
+  }
+  let provider;
+  try {
+    provider = resolveProvider(options.provider ?? "demo", options);
+    base.provider = provider.name;
+    if (request.assets_omitted) throw new Error("visual replay requires the original images; stored screenshots are intentionally omitted");
+    const assets = normalizeImageAssets(request.assets);
+    if (Object.keys(assets).length) {
+      if (options.engine === "jevrouter" || provider.supportsImages !== true) throw new Error("provider does not support image decisions");
+      projection.state.visual_assets = Object.keys(assets);
+      projection.context_bytes = byteLength(projection.state);
+    }
+    request.assets = assets;
+  } catch (error) {
+    return fallback(base, assessments, "provider_error", error instanceof Error ? error.message : String(error), projection.state);
+  }
+  if (eligible.length === 0) {
+    return decisionEnvelope({
+      status: "no_decision",
+      reason: "no capability passed availability, risk, and permission policy",
+      provider: provider.name,
+      latencyMs: elapsed(started),
+      candidateCount: 0,
+      contextBytes: projection.context_bytes,
+      candidates: decisionCandidates(assessments),
+    });
+  }
+  const deterministic = policy.deterministic === true
+    ? deterministicCandidate(eligible, policy)
+    : null;
+  if (deterministic) {
+    const selected = deterministic.capability;
+    const probabilities = Object.fromEntries(eligible.map((candidate) => [candidate.id, candidate.id === selected.id ? 1 : 0]));
+    const candidates = decisionCandidates(assessments, probabilities, 1);
+    const requiresConfirmation = policy.confirmation_risk_levels.includes(selected.risk) || selected.requires_confirmation;
+    return decisionEnvelope({
+      status: requiresConfirmation ? "needs_confirmation" : "selected",
+      reason: deterministic.reason,
+      provider: `${provider.name}:deterministic`,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      selected: selected.id,
+      probabilities,
+      confidence: 1,
+    });
+  }
+
+  let raw;
+  try {
+    raw = await provider.decide({ state: projection.state, candidates: eligible, assets: request.assets });
+  } catch (error) {
+    return fallback(base, assessments, "provider_error", error instanceof Error ? error.message : String(error), projection.state);
+  }
+
+  let answer;
+  try {
+    answer = readChoiceAnswer(raw);
+  } catch (error) {
+    return fallback(base, assessments, "malformed_response", error instanceof Error ? error.message : String(error), projection.state, raw);
+  }
+
+  const selected = eligible.find((candidate) => candidate.id === answer.choice);
+  const candidates = decisionCandidates(assessments, answer.probabilities, answer.confidence);
+  if (!selected) {
+    return decisionEnvelope({
+      status: "fallback",
+      reason: `provider selected unknown or filtered capability: ${answer.choice}`,
+      provider: provider.name,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      probabilities: answer.probabilities,
+      confidence: answer.confidence,
+      rawJev: raw,
+      fallback: { type: "invalid_selection", reason: "selection is not in the eligible candidate set" },
+    });
+  }
+  if (answer.confidence < policy.min_confidence) {
+    return decisionEnvelope({
+      status: "fallback",
+      reason: `confidence ${answer.confidence.toFixed(3)} is below policy minimum ${policy.min_confidence.toFixed(3)}`,
+      provider: provider.name,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      selected: selected.id,
+      probabilities: answer.probabilities,
+      confidence: answer.confidence,
+      rawJev: raw,
+      fallback: { type: "low_confidence", reason: "host must continue with normal planning" },
+    });
+  }
+
+  const requiresConfirmation = policy.confirmation_risk_levels.includes(selected.risk) || selected.requires_confirmation;
+  return decisionEnvelope({
+    status: requiresConfirmation ? "needs_confirmation" : "selected",
+    reason: requiresConfirmation ? "selected capability requires host confirmation" : "selected by bounded Jev decision",
+    provider: provider.name,
+    latencyMs: elapsed(started),
+    candidateCount: eligible.length,
+    contextBytes: projection.context_bytes,
+    candidates,
+    selected: selected.id,
+    probabilities: answer.probabilities,
+    confidence: answer.confidence,
+    rawJev: raw,
+  });
+}
+
+function readChoiceAnswer(raw) {
+  const answers = raw?.answers;
+  if (!answers || typeof answers !== "object") throw new Error("response has no answers object");
+  const answer = answers.tool ?? Object.values(answers).find((value) => value?.type === "choice");
+  if (!answer || answer.type !== "choice" || typeof answer.choice !== "string" || !answer.probabilities || typeof answer.probabilities !== "object") {
+    throw new Error("response does not contain a valid Choice answer");
+  }
+  const probabilities = Object.fromEntries(Object.entries(answer.probabilities).map(([id, value]) => {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) throw new Error(`invalid probability for ${id}`);
+    return [id, value];
+  }));
+  const confidence = typeof answer.confidence === "number" ? answer.confidence : Math.max(...Object.values(probabilities), 0);
+  if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error("invalid confidence");
+  return { choice: answer.choice, probabilities, confidence };
+}
+
+function fallback(base, assessments, type, reason, state, rawJev = null) {
+  return decisionEnvelope({
+    status: "fallback",
+    reason,
+    provider: base.provider,
+    latencyMs: elapsed(base.started),
+    candidateCount: base.candidateCount,
+    contextBytes: byteLength(state),
+    candidates: decisionCandidates(assessments),
+    rawJev,
+    fallback: { type, reason },
+  });
+}
+
+function elapsed(started) {
+  return Number((performance.now() - started).toFixed(3));
+}
+
+async function routeViaJevRouter(request, options) {
+  const started = performance.now();
+  const capabilities = normalizeCapabilities(request.capabilities);
+  const { assessments, eligible } = filterCapabilities(capabilities, request, { ...DEFAULT_POLICY, ...request.policy, ...(options.policy ?? {}) });
+  const projection = projectState(request, eligible, options.maxContextBytes ?? 6_000, { mode: options.contextFilterMode });
+  if (eligible.length === 0) return decisionEnvelope({ status: "no_decision", reason: "no eligible capability", provider: "jevrouter", latencyMs: elapsed(started), candidateCount: 0, contextBytes: projection.context_bytes, candidates: decisionCandidates(assessments) });
+
+  let module;
+  try {
+    module = await import("jevrouter");
+  } catch (error) {
+    return fallback({ provider: "jevrouter", candidateCount: eligible.length, contextBytes: projection.context_bytes, started }, assessments, "dependency_error", error instanceof Error ? error.message : String(error), projection.state);
+  }
+  try {
+    const result = await module.route({
+      request: request.intent,
+      context: projection.state.context,
+      candidates: eligible.map(toJevRouterCapability),
+    }, {
+      provider: options.innerProvider ?? process.env.JEVROUTER_PROVIDER ?? "demo",
+      policy: options.policy,
+    });
+    const selected = result.decision?.selected ?? null;
+    const raw = result.raw_jev ?? null;
+    const candidates = decisionCandidates(assessments, Object.fromEntries((result.decision?.candidates ?? []).map((candidate) => [candidate.id, candidate.jev_probability ?? 0])), null);
+    return decisionEnvelope({
+      status: result.status === "selected" ? "selected" : result.status === "needs_confirmation" ? "needs_confirmation" : "fallback",
+      selected,
+      reason: result.fallback?.reason ?? "selected by JevRouter",
+      provider: `jevrouter:${options.innerProvider ?? process.env.JEVROUTER_PROVIDER ?? "demo"}`,
+      latencyMs: elapsed(started),
+      candidateCount: eligible.length,
+      contextBytes: projection.context_bytes,
+      candidates,
+      rawJev: raw,
+      fallback: result.fallback?.type ? { type: result.fallback.type, reason: result.fallback.reason } : null,
+    });
+  } catch (error) {
+    return fallback({ provider: "jevrouter", candidateCount: eligible.length, contextBytes: projection.context_bytes, started }, assessments, "provider_error", error instanceof Error ? error.message : String(error), projection.state);
+  }
+}
+
+function toJevRouterCapability(capability) {
+  return {
+    id: capability.id,
+    name: capability.name,
+    type: capability.kind === "mcp" ? "mcp_tool" : capability.kind,
+    description: capability.description,
+    permissions: capability.permissions,
+    risk: { level: capability.risk },
+    availability: { available: capability.available },
+    execution: { mode: capability.kind === "mcp" ? "mcp" : capability.kind, target: capability.execution.target },
+    policy: { requires_confirmation: capability.requires_confirmation },
+  };
+}

package/src/shadow-compaction.mjs

@@ -0,0 +1,170 @@
+import { sanitizeContext } from "./context-filter.mjs";
+import { isPinnedEvidence } from "./relevance-filter.mjs";
+import { resolveProvider } from "./providers/index.mjs";
+
+const LIST_KEYS = new Set(["messages", "events", "logs", "tool_results", "history", "transcript"]);
+const DEFAULT_BATCH_SIZE = 8;
+const DEFAULT_KEEP_THRESHOLD = 0.5;
+const DEFAULT_MIN_CONFIDENCE = 0.7;
+const MAX_ITEMS = 64;
+const MAX_PREVIEW = 320;
+
+/**
+ * Produce advisory Jev compaction decisions without mutating context.
+ * Pinned evidence is never sent as droppable and provider failure retains all items.
+ */
+export async function buildShadowCompactionReport({
+  intent = "Assess which context records must remain available to a later agent.",
+  context = {},
+  provider = "demo",
+  config,
+  batchSize = DEFAULT_BATCH_SIZE,
+  keepThreshold = DEFAULT_KEEP_THRESHOLD,
+  minConfidence = DEFAULT_MIN_CONFIDENCE,
+} = {}) {
+  const items = collectContextItems(context);
+  const normalizedBatchSize = boundedInteger(batchSize, DEFAULT_BATCH_SIZE, 1, DEFAULT_BATCH_SIZE);
+  const normalizedThreshold = boundedNumber(keepThreshold, DEFAULT_KEEP_THRESHOLD);
+  const normalizedConfidence = boundedNumber(minConfidence, DEFAULT_MIN_CONFIDENCE);
+  const protectedItems = items.filter((item) => item.pinned);
+  const evaluable = items.filter((item) => !item.pinned);
+  const decisions = new Map(protectedItems.map((item) => [item.id, {
+    decision: "keep",
+    probability: 1,
+    confidence: 1,
+    reason: `pinned:${item.pinned_reasons.join(",")}`,
+  }]));
+  let costUsd = 0;
+  let failed = null;
+
+  try {
+    const resolved = resolveProvider(provider, { config });
+    if (!resolved || typeof resolved.evaluate !== "function") throw new Error("provider does not support batched evaluation");
+    for (const batch of batches(evaluable, normalizedBatchSize)) {
+      const raw = await resolved.evaluate({
+        state: {
+          intent: boundedText(intent),
+          compaction: {
+            mode: "shadow",
+            instruction: "For each item, decide whether dropping it would lose a requirement, exact identifier, path, command, error, user decision, execution receipt, or other evidence needed later. Be conservative: keep when uncertain.",
+            items: batch.map(publicItem),
+          },
+        },
+        questions: Object.fromEntries(batch.map((item, index) => [`item_${index}`, keepQuestion()])),
+      });
+      costUsd += finiteCost(raw?.usage?.cost) ?? 0;
+      for (const [index, item] of batch.entries()) {
+        const answer = readNoul(raw?.answers?.[`item_${index}`]);
+        if (!answer) throw new Error(`provider response has no valid item_${index} judgment`);
+        const decision = answer.confidence < normalizedConfidence || answer.probability >= normalizedThreshold ? "keep" : "drop_candidate";
+        decisions.set(item.id, {
+          decision,
+          probability: answer.probability,
+          confidence: answer.confidence,
+          reason: answer.confidence < normalizedConfidence ? "low_confidence" : decision === "keep" ? "provider_keep" : "provider_drop_candidate",
+        });
+      }
+    }
+  } catch (error) {
+    failed = error instanceof Error ? error.message : String(error);
+    for (const item of evaluable) {
+      decisions.set(item.id, { decision: "keep", probability: null, confidence: null, reason: "provider_error" });
+    }
+  }
+
+  const reportedItems = items.map((item) => ({ ...publicItem(item), ...decisions.get(item.id) }));
+  const droppableCount = reportedItems.filter((item) => item.decision === "drop_candidate").length;
+  return {
+    schema_version: 1,
+    mode: "jev_shadow",
+    status: failed ? "fallback" : "judged",
+    changed: false,
+    candidate_count: reportedItems.length,
+    evaluated_count: evaluable.length,
+    protected_count: protectedItems.length,
+    retained_count: reportedItems.length - droppableCount,
+    droppable_count: droppableCount,
+    keep_threshold: normalizedThreshold,
+    min_confidence: normalizedConfidence,
+    cost_usd: failed ? null : Number(costUsd.toFixed(8)),
+    fallback: failed ? { type: "provider_error", reason: failed } : null,
+    items: reportedItems,
+  };
+}
+
+export function collectContextItems(context = {}) {
+  const source = context && typeof context === "object" ? context : {};
+  const items = [];
+  for (const [list, value] of Object.entries(source)) {
+    if (!LIST_KEYS.has(list) || !Array.isArray(value)) continue;
+    for (const [index, original] of value.entries()) {
+      if (items.length >= MAX_ITEMS) return items;
+      const sanitized = sanitizeContext(original);
+      const evidence = isPinnedEvidence(sanitized);
+      items.push({
+        id: `${list}[${index}]`,
+        list,
+        index,
+        value: sanitized,
+        pinned: evidence.pinned,
+        pinned_reasons: evidence.reasons,
+      });
+    }
+  }
+  return items;
+}
+
+function publicItem(item) {
+  return {
+    id: item.id,
+    list: item.list,
+    index: item.index,
+    pinned: item.pinned,
+    pinned_reasons: item.pinned_reasons,
+    preview: boundedText(typeof item.value === "string" ? item.value : JSON.stringify(item.value)),
+  };
+}
+
+function keepQuestion() {
+  return {
+    type: "noul",
+    instructions: "Would dropping this context record lose information needed by a later agent? Return true to keep it and false only when it is safely stale or redundant.",
+    criteria: {
+      true: "Keep: it contains a requirement, decision, identifier, path, command, error, execution evidence, or context that may matter later; uncertainty means keep.",
+      false: "Drop candidate: it is safely stale or redundant and losing it would not affect later work.",
+    },
+  };
+}
+
+function readNoul(answer) {
+  if (!answer || typeof answer !== "object") return null;
+  const probability = ["probability", "p_true", "score", "value", "noul"].map((key) => answer[key]).find(validProbability);
+  if (!validProbability(probability)) return null;
+  const confidence = validProbability(answer.confidence) ? answer.confidence : probability;
+  return { probability, confidence };
+}
+
+function batches(items, size) {
+  return Array.from({ length: Math.ceil(items.length / size) }, (_, index) => items.slice(index * size, (index + 1) * size));
+}
+
+function boundedText(value) {
+  const text = String(value ?? "");
+  return text.length > MAX_PREVIEW ? `${text.slice(0, MAX_PREVIEW)}…` : text;
+}
+
+function boundedNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : fallback;
+}
+
+function boundedInteger(value, fallback, min, max) {
+  return Number.isInteger(value) ? Math.max(min, Math.min(max, value)) : fallback;
+}
+
+function validProbability(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function finiteCost(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}