@piagent/platform 1.5.4 → 1.6.0

package/packages/piagent-core/extensions/context-engine.js

@@ -2,7 +2,6 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
-
 import {
   contextIndexExcludeDigest,
   contextIndexExcludePolicyVersion,
@@ -11,9 +10,13 @@ import {
 import { matchesAnyPath, matchesProtectedPath } from "./policy-core.js";
 import { appendJsonlBounded, readJsonlTail } from "./state-retention.js";
 import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
-
+import { contextMetricPartition } from "./context-efficiency-metrics.js";
+import { writeContextEfficiencyReport } from "./context-efficiency-report.js";
+import { inspectContextTelemetryIntegrity } from "./context-telemetry-integrity.js";
+import { directExplicitImportLinks, extractJavaScriptModuleImports } from "./context-import-links.js";
+import { redactSensitiveProjectFileText } from "../security/sensitive-data.js";
 const INDEX_SCHEMA_VERSION = 2;
-const TELEMETRY_SCHEMA_VERSION = 1;
+const TELEMETRY_SCHEMA_VERSION = 2;
 const RRF_K = 60;
 const DEFAULT_MAX_FILE_BYTES = 512 * 1024;
 const DEFAULT_MAX_FILES = 8_000;
@@ -75,6 +78,10 @@ function clampInteger(value, fallback, min, max) {
   return Math.max(min, Math.min(max, Math.trunc(number)));
 }
 
+function ratio(numerator, denominator) {
+  return denominator > 0 ? numerator / denominator : 0;
+}
+
 function requireExplicitExcludePatterns(options, operation) {
   if (!Array.isArray(options?.excludePatterns)) {
     throw new TypeError(`${operation} requires an explicit excludePatterns array`);
@@ -258,7 +265,7 @@ function isTextBuffer(buffer) {
   return sample.length === 0 || suspicious / sample.length < 0.02;
 }
 
-function shouldIndexPath(relativePath, options) {
+export function shouldIndexPath(relativePath, options = {}) {
   const rel = normalizeRelative(relativePath);
   if (!rel || path.isAbsolute(rel) || rel.startsWith("../")) return false;
   const segments = rel.split("/");
@@ -417,12 +424,12 @@ function extractSymbols(text, language) {
   return symbols;
 }
 
-function extractImports(text, language) {
+function extractImports(text, language, filePath = "") {
   const lines = text.split(/\r?\n/);
   const imports = [];
   const patterns = [];
   if (["typescript", "javascript", "svelte", "vue"].includes(language)) {
-    patterns.push(/\bfrom\s+["']([^"']+)["']/, /\brequire\(\s*["']([^"']+)["']\s*\)/, /\bimport\(\s*["']([^"']+)["']\s*\)/);
+    return extractJavaScriptModuleImports(text, { embedded: ["svelte", "vue"].includes(language), jsx: /\.[jt]sx$/i.test(filePath) });
   } else if (language === "python") {
     patterns.push(/^\s*from\s+([A-Za-z_][\w.]*)\s+import\b/, /^\s*import\s+([A-Za-z_][\w.]*)/);
   } else if (["java", "kotlin", "scala"].includes(language)) {
@@ -627,7 +634,7 @@ export async function buildContextIndexV2(cwd, options = {}) {
     for (const item of changed) {
       const language = languageForPath(item.relativePath);
       const symbols = extractSymbols(item.text, language);
-      const imports = extractImports(item.text, language);
+      const imports = extractImports(item.text, language, item.relativePath);
       insertFile.run(item.relativePath, item.contentHash, item.stat.size, item.stat.mtimeMs, language, indexedAt);
       insertFts.run(item.relativePath, item.text, symbols.map((symbol) => symbol.name).join(" "));
       for (const symbol of symbols) {
@@ -859,10 +866,13 @@ function retrievalFeedback(cwd) {
   } catch {
     return {
       rows: [],
+      observedSelected: 0,
       selected: 0,
       used: 0,
       unused: 0,
-      utilizationRate: 0
+      utilizationRate: 0,
+      fallbackRereads: 0,
+      fallbackRereadRate: 0
     };
   }
   const cached = retrievalFeedbackCache.get(cwd);
@@ -871,33 +881,61 @@ function retrievalFeedback(cwd) {
   const events = readContextTelemetry(cwd, { limit: 12_000, maxBytes: 12 * 1024 * 1024 });
   const selectedCounts = new Map();
   const usedCounts = new Map();
-  const latestPackBySession = new Map();
-  let selected = 0;
-  let used = 0;
+  const fallbackReadCounts = new Map();
+  const latestPackByPartition = new Map();
+  const taskByTurn = new Map(events.filter((event) => event.event === "turn_task_bound" && typeof event.sessionId === "string" && typeof event.turnId === "string" && typeof event.taskRunId === "string")
+    .map((event) => [`${event.sessionId}\0${event.turnId}`, event.taskRunId]));
+  let observedSelected = 0, selected = 0, used = 0, fallbackRereads = 0;
+
+  const eventPaths = (event) => [...new Set([
+    ...(Array.isArray(event.selectedPaths) ? event.selectedPaths : []),
+    ...(Array.isArray(event.selectedItems) ? event.selectedItems.map((item) => item?.path) : [])
+  ].map(normalizeRelative).filter((filePath) => shouldIndexPath(filePath, {})))];
+  const successfulMutationPaths = (event) => {
+    if (event.event !== "tool_result" || event.isError === true) return [];
+    const explicit = [event.changedPaths, event.mutationPaths, event.targetPaths]
+      .find((value) => Array.isArray(value));
+    if (explicit) return [...new Set(explicit.map(normalizeRelative).filter(Boolean))];
+    // These tools have direct file-mutation semantics. Shell and opaque MCP
+    // results are intentionally excluded unless they carry explicit changed
+    // paths; a zero exit code alone is not mutation evidence.
+    const toolName = String(event.toolName ?? "").toLowerCase();
+    if (!["write", "edit", "apply_patch", "patch"].includes(toolName)) return [];
+    const targetPath = normalizeRelative(event.targetPath);
+    return targetPath ? [targetPath] : [];
+  };
 
   for (const event of events) {
-    const sessionId = typeof event.sessionId === "string" ? event.sessionId : "";
-    if (event.event === "context_pack" && sessionId) {
-      const selectedPaths = [...new Set(
-        (Array.isArray(event.selectedPaths) ? event.selectedPaths : [])
-          .map(normalizeRelative)
-          .filter((filePath) => shouldIndexPath(filePath, {}))
-      )];
-      const pack = { selectedPaths: new Set(selectedPaths), usedPaths: new Set() };
-      latestPackBySession.set(sessionId, pack);
+    const partition = contextMetricPartition(event, taskByTurn);
+    if (event.event === "context_pack_injected") {
+      const selectedPaths = eventPaths(event);
+      observedSelected += selectedPaths.length;
+      if (!partition) continue;
+      const pack = { selectedPaths: new Set(selectedPaths), usedPaths: new Set(), fallbackReadPaths: new Set() };
+      latestPackByPartition.set(partition, pack);
       for (const filePath of selectedPaths) {
         selectedCounts.set(filePath, (selectedCounts.get(filePath) ?? 0) + 1);
         selected += 1;
       }
       continue;
     }
-    if (event.event !== "tool_call" || !sessionId) continue;
+    if (!partition) continue;
+    const pack = latestPackByPartition.get(partition);
+    if (!pack) continue;
     const targetPath = normalizeRelative(event.targetPath);
-    const pack = latestPackBySession.get(sessionId);
-    if (!targetPath || !pack?.selectedPaths.has(targetPath) || pack.usedPaths.has(targetPath)) continue;
-    pack.usedPaths.add(targetPath);
-    usedCounts.set(targetPath, (usedCounts.get(targetPath) ?? 0) + 1);
-    used += 1;
+    if (event.event === "tool_call" && ["read", "grep", "find", "ls"].includes(event.toolName)
+      && targetPath && pack.selectedPaths.has(targetPath) && !pack.fallbackReadPaths.has(targetPath)) {
+      pack.fallbackReadPaths.add(targetPath);
+      fallbackReadCounts.set(targetPath, (fallbackReadCounts.get(targetPath) ?? 0) + 1);
+      fallbackRereads += 1;
+      continue;
+    }
+    for (const mutationPath of successfulMutationPaths(event)) {
+      if (!pack.selectedPaths.has(mutationPath) || pack.usedPaths.has(mutationPath)) continue;
+      pack.usedPaths.add(mutationPath);
+      usedCounts.set(mutationPath, (usedCounts.get(mutationPath) ?? 0) + 1);
+      used += 1;
+    }
   }
 
   const rows = [...usedCounts.entries()]
@@ -909,16 +947,20 @@ function retrievalFeedback(cwd) {
         path: filePath,
         selectedCount,
         usedCount,
+        fallbackRereadCount: fallbackReadCounts.get(filePath) ?? 0,
         feedbackScore: utilization * evidence
       };
     })
     .sort((left, right) => right.feedbackScore - left.feedbackScore || right.usedCount - left.usedCount || left.path.localeCompare(right.path));
   const value = {
     rows,
+    observedSelected,
     selected,
     used,
     unused: Math.max(0, selected - used),
-    utilizationRate: ratio(used, selected)
+    utilizationRate: ratio(used, selected),
+    fallbackRereads,
+    fallbackRereadRate: ratio(fallbackRereads, selected)
   };
   retrievalFeedbackCache.set(cwd, { signature, value });
   return value;
@@ -941,15 +983,15 @@ export async function searchContextIndexV2(cwd, query, options = {}) {
     const allFiles = db.prepare("SELECT path, mtime_ms FROM files").all().filter((file) => pathAllowed(file.path));
     const explicitRows = [];
     for (const file of allFiles) {
+      const normalizedFile = file.path.toLowerCase();
       const basename = path.posix.basename(file.path).toLowerCase();
       const matched = explicitPaths.some((candidate) => {
         const normalized = candidate.toLowerCase();
-        return file.path.toLowerCase() === normalized || file.path.toLowerCase().endsWith(`/${normalized}`) || basename === path.posix.basename(normalized);
+        return normalizedFile === normalized || (!normalized.includes("/") && basename === normalized);
       });
       if (matched) explicitRows.push({ path: file.path, exact: true });
     }
     addRankedList(scores, explicitRows, "explicit", 3);
-
     let lexicalRows = [];
     if (terms.length > 0) {
       lexicalRows = db.prepare(`
@@ -958,7 +1000,6 @@ export async function searchContextIndexV2(cwd, query, options = {}) {
       `).all(ftsQuery(terms), Math.max(limit * 4, 30)).filter((row) => pathAllowed(row.path));
       addRankedList(scores, lexicalRows, "lexical", 1.5);
     }
-
     const symbolRows = [];
     const symbolStatement = db.prepare(`
       SELECT file_path, name, kind, line, end_line, signature
@@ -973,13 +1014,11 @@ export async function searchContextIndexV2(cwd, query, options = {}) {
 
     const changedRows = gitChangedFiles(cwd).map((filePath) => ({ path: filePath })).filter((row) => scores.has(row.path));
     addRankedList(scores, changedRows, "git-change", 0.8);
-
     const testRows = allFiles
       .filter((file) => /(^|\/)(?:test|tests|__tests__)(\/|$)|(?:\.test|\.spec|_test)\./i.test(file.path))
       .filter((file) => terms.some((term) => file.path.toLowerCase().includes(term)))
       .map((file) => ({ path: file.path }));
     addRankedList(scores, testRows, "test", 1.1);
-
     // Feedback is deliberately positive-only and weak. A file is boosted only
     // after a prior context pack selected it and the same session actually used
     // it. New files and unused historical candidates are never penalized.
@@ -987,12 +1026,13 @@ export async function searchContextIndexV2(cwd, query, options = {}) {
     addRankedList(scores, feedbackRows, "feedback", 0.45);
 
     const graphSeeds = new Map([...scores.entries()].map(([filePath, value]) => [filePath, value.score]));
-    const importRows = db.prepare("SELECT file_path, target_path FROM imports WHERE target_path IS NOT NULL")
+    const importRows = db.prepare("SELECT file_path, specifier, target_path FROM imports WHERE target_path IS NOT NULL")
       .all()
       .filter((row) => pathAllowed(row.file_path) && pathAllowed(row.target_path));
+    const directLinks = directExplicitImportLinks(importRows, explicitRows);
+    addRankedList(scores, directLinks.rankingRows, "import", 1.8);
     const graphRows = personalizedPageRank(importRows, graphSeeds).slice(0, Math.max(limit * 3, 30));
     addRankedList(scores, graphRows, "graph", 1);
-
     const ranked = [...scores.values()]
       .filter((candidate) => (
         shouldIndexPath(candidate.path, { excludePatterns })
@@ -1012,6 +1052,7 @@ export async function searchContextIndexV2(cwd, query, options = {}) {
         path: candidate.path,
         score: Number(candidate.score.toFixed(6)),
         sources: [...candidate.sources],
+        links: directLinks.byPath.get(candidate.path) ?? [],
         symbols
       };
     });
@@ -1105,31 +1146,79 @@ export async function buildContextPack(cwd, query, options = {}) {
   }
 
   for (const result of rankedResults) {
-    let text;
+    let text, fileContentHash, sanitizedContentDigest, sensitiveContentRedacted = false;
+    let safeResult = result;
     try {
       const file = projectFileInfo(cwd, result.path, projectRoot, directoryCache);
       if (!file) continue;
-      text = fs.readFileSync(file.absolute, "utf8");
+      const bytes = fs.readFileSync(file.absolute);
+      const sanitized = redactSensitiveProjectFileText(result.path, bytes.toString("utf8"));
+      if (!sanitized.lineCountPreserved) continue;
+      text = sanitized.text;
+      sensitiveContentRedacted = sanitized.redacted;
+      safeResult = {
+        ...result,
+        symbols: result.symbols.map((symbol) => ({
+          ...symbol,
+          signature: redactSensitiveProjectFileText(result.path, String(symbol.signature ?? "")).text
+        }))
+      };
+      sanitizedContentDigest = sanitized.redacted
+        ? `context-sanitized-file-v1:${sha256(sanitized.text)}`
+        : undefined;
+      fileContentHash = sanitizedContentDigest ?? `context-file-v1:${sha256(bytes)}`;
     } catch {
       continue;
     }
-    const snippets = lineRangesForFile(text, result, search.terms, includeCode);
+    const snippets = lineRangesForFile(text, safeResult, search.terms, includeCode);
     const body = snippets.length > 0
       ? snippets.map((snippet) => `lines ${snippet.start}-${snippet.end}\n${snippet.text}`).join("\n\n")
-      : result.symbols.slice(0, 8).map((symbol) => `line ${symbol.line}: ${symbol.signature}`).join("\n");
+      : safeResult.symbols.slice(0, 8).map((symbol) => `line ${symbol.line}: ${symbol.signature}`).join("\n");
     const itemText = [`### ${result.path}`, `why: ${result.sources.join(", ")}`, body].filter(Boolean).join("\n");
     const tokens = estimateContextTokens(itemText);
-    const item = { ...result, text: itemText, estimatedTokens: tokens, truncated: false };
+    const itemRanges = snippets.length > 0
+      ? snippets.map(({ start, end }) => ({ start, end }))
+      : safeResult.symbols.slice(0, 8).map((symbol) => ({ start: symbol.line, end: symbol.endLine ?? symbol.line }));
+    const representation = snippets.length > 0 ? "snippet" : body ? "symbol-map" : "navigation";
+    const item = {
+      ...safeResult,
+      text: itemText,
+      estimatedTokens: tokens,
+      truncated: false,
+      fileContentHash,
+      ...(sanitizedContentDigest ? { sanitizedContentDigest } : {}),
+      payloadHash: `context-payload-v1:${sha256(itemText)}`,
+      representation,
+      ranges: itemRanges,
+      generation: 1,
+      sensitiveContentRedacted
+    };
     if (estimateContextTokens(renderPack([...selected, item])) > budgetTokens) {
       if (selected.length === 0) {
         const remaining = budgetTokens - estimateContextTokens(renderPack([]));
         let chars = Math.max(0, remaining * 4 - 16);
-        let truncated = { ...result, text: itemText.slice(0, chars), estimatedTokens: remaining, truncated: true };
+        let truncated = {
+          ...safeResult,
+          text: itemText.slice(0, chars),
+          estimatedTokens: remaining,
+          truncated: true,
+          fileContentHash,
+          ...(sanitizedContentDigest ? { sanitizedContentDigest } : {}),
+          payloadHash: "",
+          representation: `${representation}-truncated`,
+          ranges: [],
+          generation: 1,
+          sensitiveContentRedacted
+        };
         while (chars > 0 && estimateContextTokens(renderPack([truncated])) > budgetTokens) {
           chars = Math.max(0, chars - 16);
           truncated = { ...truncated, text: itemText.slice(0, chars) };
         }
-        if (chars > 0) selected.push(truncated);
+        if (chars > 0) selected.push({
+          ...truncated,
+          estimatedTokens: estimateContextTokens(truncated.text),
+          payloadHash: `context-payload-v1:${sha256(truncated.text)}`
+        });
       }
       continue;
     }
@@ -1203,10 +1292,10 @@ export async function buildTestImpact(cwd, changedFiles = [], options = {}) {
 export function appendContextTelemetry(cwd, event) {
   const paths = contextEnginePaths(cwd);
   const record = {
-    schemaVersion: TELEMETRY_SCHEMA_VERSION,
     source: "piagent",
-    recordedAt: nowIso(),
-    ...event
+    ...event,
+    schemaVersion: TELEMETRY_SCHEMA_VERSION, telemetrySource: "piagent",
+    recordedAt: typeof event?.recordedAt === "string" ? event.recordedAt : nowIso()
   };
   appendJsonlBounded(paths.telemetry, record, { maxBytes: MAX_TELEMETRY_FILE_BYTES, mode: 0o600, projectRoot: cwd });
   return record;
@@ -1219,113 +1308,27 @@ export function readContextTelemetry(cwd, options = {}) {
   return readJsonlTail(target, { limit, maxBytes, projectRoot: cwd });
 }
 
-function ratio(numerator, denominator) {
-  return denominator > 0 ? numerator / denominator : 0;
+/** Fail-closed telemetry inspection for benchmark evidence. */
+export function inspectContextTelemetry(cwd, options = {}) {
+  return inspectContextTelemetryIntegrity(cwd, contextEnginePaths(cwd).telemetry, options);
 }
-
 export function buildContextEfficiencyReport(cwd, options = {}) {
   const events = readContextTelemetry(cwd, options);
-  const prompts = events.filter((event) => event.event === "agent_prompt");
-  const toolCalls = events.filter((event) => event.event === "tool_call");
-  const toolResults = events.filter((event) => event.event === "tool_result");
-  const packs = events.filter((event) => event.event === "context_pack");
-  const compactions = events.filter((event) => event.event === "session_compact");
-  const seenReads = new Set();
-  let duplicateReads = 0;
-  let readCalls = 0;
-  for (const event of toolCalls) {
-    if (!["read", "grep", "find", "ls"].includes(event.toolName)) continue;
-    readCalls += 1;
-    const key = `${event.toolName}:${event.targetHash ?? event.inputHash ?? ""}`;
-    if (seenReads.has(key)) duplicateReads += 1;
-    else seenReads.add(key);
-  }
-  const outputChars = toolResults.reduce((sum, event) => sum + Number(event.outputChars ?? 0), 0);
-  const duplicateOutputChars = toolResults.reduce((sum, event) => sum + (event.repeated ? Number(event.outputChars ?? 0) : 0), 0);
-  const averageActiveTools = prompts.length > 0
-    ? prompts.reduce((sum, event) => sum + Number(event.activeTools ?? 0), 0) / prompts.length
-    : 0;
-  const averageSystemPromptTokens = prompts.length > 0
-    ? prompts.reduce((sum, event) => sum + Number(event.systemPromptTokens ?? 0), 0) / prompts.length
-    : 0;
-  const averageToolSchemaTokens = prompts.length > 0
-    ? prompts.reduce((sum, event) => sum + Number(event.toolSchemaTokens ?? 0), 0) / prompts.length
-    : 0;
-  const lowConfidencePacks = packs.filter((event) => ["none", "low"].includes(event.confidence)).length;
-  const feedback = retrievalFeedback(cwd);
-  const duplicateReadRate = ratio(duplicateReads, readCalls);
-  const duplicateOutputRate = ratio(duplicateOutputChars, outputChars);
-  const schemaShare = ratio(averageToolSchemaTokens, averageSystemPromptTokens);
-  const lowConfidenceRate = ratio(lowConfidencePacks, packs.length);
-  const activeToolPenalty = Math.max(0, Math.min(1, (averageActiveTools - 12) / 24));
-  const wasteScore = Math.round(100 * (
-    duplicateReadRate * 0.3
-    + duplicateOutputRate * 0.25
-    + Math.min(1, schemaShare * 3) * 0.2
-    + lowConfidenceRate * 0.15
-    + activeToolPenalty * 0.1
-  ));
-  const recommendations = [];
-  if (duplicateReadRate > 0.2) recommendations.push("Repeated reads are high; reuse the current working set before searching again.");
-  if (duplicateOutputRate > 0.15) recommendations.push("Repeated tool output is high; prefer delta results and narrower verification.");
-  if (schemaShare > 0.15 || averageActiveTools > 20) recommendations.push("Tool surface is large; activate only the workflow groups needed for the next turn.");
-  if (lowConfidenceRate > 0.4) recommendations.push("Retrieval confidence is low; rebuild the index or run one bounded finder pass.");
-  if (feedback.selected >= 4 && feedback.utilizationRate < 0.45) recommendations.push("Context-pack utilization is low; reduce pack breadth or improve task-specific ranking signals.");
-  if (recommendations.length === 0) recommendations.push("No dominant context waste signal was detected in the sampled events.");
-  const report = {
-    schemaVersion: 1,
-    source: "piagent",
-    generatedAt: nowIso(),
-    sample: {
-      events: events.length,
-      prompts: prompts.length,
-      toolCalls: toolCalls.length,
-      toolResults: toolResults.length,
-      contextPacks: packs.length,
-      compactions: compactions.length
-    },
-    metrics: {
-      averageActiveTools: Number(averageActiveTools.toFixed(2)),
-      averageSystemPromptTokens: Math.round(averageSystemPromptTokens),
-      averageToolSchemaTokens: Math.round(averageToolSchemaTokens),
-      toolSchemaShare: Number(schemaShare.toFixed(4)),
-      readCalls,
-      duplicateReads,
-      duplicateReadRate: Number(duplicateReadRate.toFixed(4)),
-      outputChars,
-      duplicateOutputChars,
-      duplicateOutputRate: Number(duplicateOutputRate.toFixed(4)),
-      lowConfidencePacks,
-      lowConfidenceRate: Number(lowConfidenceRate.toFixed(4)),
-      contextSelections: feedback.selected,
-      contextSelectionsUsed: feedback.used,
-      contextSelectionsUnused: feedback.unused,
-      contextUtilizationRate: Number(feedback.utilizationRate.toFixed(4)),
-      contextWasteScore: wasteScore
-    },
-    methodology: {
-      scoreRange: "0-100; lower is better",
-      weights: {
-        duplicateReads: 0.3,
-        duplicateOutput: 0.25,
-        toolSchemaShare: 0.2,
-        lowConfidenceRetrieval: 0.15,
-        activeToolExcess: 0.1
-      },
-      retrievalFeedback: "Positive-only reranking: a path receives a weak boost only when a prior pack selected it and the same session later used it. Unseen and unused paths are not penalized.",
-      note: "This is an operational signal, not a quality verdict. Compare it with task acceptance and verification results."
-    },
-    recommendations
-  };
-  const paths = contextEnginePaths(cwd);
-  ensurePrivateStateDirectory(cwd, paths.root, "Context report directory");
-  const reportPath = resolveLocalStatePath(cwd, paths.report, { label: "Context efficiency report" });
-  fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
-  return report;
+  return writeContextEfficiencyReport(cwd, events, {
+    contextEnginePaths: () => contextEnginePaths(cwd),
+    nowIso,
+    retrievalFeedback: () => retrievalFeedback(cwd)
+  });
+}
+function canonicalJson(value) {
+  return JSON.stringify(value, (_key, nested) => {
+    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return nested;
+    return Object.fromEntries(Object.keys(nested).sort().map((key) => [key, nested[key]]));
+  });
 }
 
 export function toolResultFingerprint(toolName, input, content) {
-  const inputHash = sha256(JSON.stringify(input ?? {}));
+  const inputHash = sha256(canonicalJson(input ?? {}));
   const text = Array.isArray(content)
     ? content.filter((block) => block && typeof block === "object" && block.type === "text").map((block) => block.text ?? "").join("\n")
     : String(content ?? "");

package/packages/piagent-core/extensions/context-evidence.js

@@ -0,0 +1,48 @@
+const PLANNED_CONTEXT_REASON = /^criterion-[a-z0-9_-]+(?:\s|$)/i;
+const RUNTIME_OBSERVED_READ_REASONS = new Set([
+  "Runtime observed successful source read.",
+  "Runtime observed successful document read."
+]);
+const RUNTIME_CONFIRMED_DELIVERY_REASONS = new Set([
+  "Runtime confirmed delivery of a bounded Context Engine navigation pack.",
+  "Runtime confirmed delivery of criterion-selected context.",
+  "Runtime confirmed delivery of a /context pack message.",
+  "Runtime confirmed delivery of an explicit Context Engine tool pack."
+]);
+
+export function isPlannedContextEntry(entry) {
+  return Boolean(
+    entry
+    && typeof entry.path === "string"
+    && typeof entry.reason === "string"
+    && PLANNED_CONTEXT_REASON.test(entry.reason.trim())
+  );
+}
+
+export function isRuntimeOwnedContextEvidenceEntry(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  const reason = typeof entry.reason === "string" ? entry.reason.trim() : "";
+  return RUNTIME_OBSERVED_READ_REASONS.has(reason) || RUNTIME_CONFIRMED_DELIVERY_REASONS.has(reason);
+}
+
+export function isDurableContextEvidenceEntry(entry) {
+  return Boolean(
+    entry
+    && typeof entry.path === "string"
+    && entry.path.trim().length > 0
+    && isRuntimeOwnedContextEvidenceEntry(entry)
+  );
+}
+
+export function durableContextEvidenceEntries(taskOrEntries) {
+  const entries = Array.isArray(taskOrEntries)
+    ? taskOrEntries
+    : Array.isArray(taskOrEntries?.contextManifest)
+      ? taskOrEntries.contextManifest
+      : [];
+  return entries.filter(isDurableContextEvidenceEntry);
+}
+
+export function hasDurableContextEvidence(taskOrEntries) {
+  return durableContextEvidenceEntries(taskOrEntries).length > 0;
+}