@piagent/platform 1.5.5 → 1.6.0

package/packages/piagent-core/runtime/quality/performance-assurance.ts

@@ -2,6 +2,7 @@ import type { TaskContract } from "../../extensions/guard-types.ts";
 import { acceptanceBoundaryProofGuidance } from "../../extensions/acceptance-boundary-guidance.js";
 import { normalizePathCandidate } from "../../extensions/policy-core.js";
 import { acceptanceLanguageAdapterStatus } from "../../extensions/acceptance-language-adapters.js";
+import { hasGraphOrderContract } from "./performance-assurance-signals.ts";
 import {
   MAX_PERFORMANCE_MUTATIONS_PER_REVISION,
   MAX_PERFORMANCE_REPAIR_PATHS,
@@ -55,8 +56,7 @@ const SIGNALS: Array<{ code: string; pattern: RegExp }> = [
   { code: "boundary-contract", pattern: /\b(?:backpressure|boundary|budget|capacity|ceil(?:ing)?|clamp|inclusive|minimum|maximum|maxchars|overflow|round(?:ing)?|safe[-\s]+integer|basis points?|positive integer|non-negative|falsey|falsy|nullish)\b/i },
   { code: "return-shape-contract", pattern: /\b(?:return shape|returned? (?:element|object|value|representation)s?|preserve (?:the )?return)\b/i },
   { code: "public-api-contract", pattern: /\b(?:exported api|public api|do not change (?:the )?(?:api|signature)|preserve (?:the )?(?:api|input|output|return)|without changing unrelated behavior)\b/i },
-  { code: "graph-order-contract", pattern: /\b(?:dependency|topolog|cycle|stable order|input order|first[-\s]+(?:observed|seen|encountered)[-\s]+order|replay order|deduplicat(?:e|ion).*order|exactly once|before its dependent)\b/i },
-  { code: "identity-isolation-contract", pattern: /\b(?:tenant|authorization|permission|cache[- ]?key|collision|isolation|same tuple|cross[- ]tenant)\b/i },
+  { code: "identity-isolation-contract", pattern: /\b(?:auth(?:orization)?|unauthoriz(?:ed|ation)|permission|cache[- ]?key|collision|same tuple|cross[- ]tenant|same[- ]tenant|tenant boundary|tenant[- ]scoped (?:cache|storage))\b/i },
   { code: "concurrency-contract", pattern: /\b(?:concurren|race condition|stale response|bounded retry|idempot(?:ent|ency)?|lock)\b/i },
   { code: "data-migration-contract", pattern: /\b(?:migration|schema|money|invoice|ledger|transaction|data loss)\b/i },
   { code: "non-mutation-contract", pattern: /\b(?:do not mutate|must not mutate|without mutating|input unchanged|preserve input)\b/i }
@@ -97,6 +97,10 @@ export function analyzePerformanceAssurance(input: AssuranceInput): PerformanceA
   }
 
   const reasonCodes = SIGNALS.filter((signal) => signal.pattern.test(request)).map((signal) => signal.code);
+  if (hasGraphOrderContract(request)) reasonCodes.push("graph-order-contract");
+  if (/\b(?:tenants?|tenantid)\b/i.test(request) && /\bisolat(?:e|ed|es|ing|ion)\b/i.test(request)) {
+    reasonCodes.push("identity-isolation-contract");
+  }
   if (request.length >= 320) reasonCodes.push("long-contract");
   if (namedEntrypoints(request) > 1) reasonCodes.push("multiple-entrypoints");
   const exactnessSignals = reasonCodes.filter((code) => [

package/packages/piagent-core/runtime/recovery/edit-recovery-context.ts

@@ -0,0 +1,113 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { shouldIndexPath } from "../../extensions/context-engine.js";
+import { matchesProtectedPath } from "../../extensions/policy-core.js";
+import { redactSensitiveProjectFileText, redactSensitiveText } from "../../security/sensitive-data.js";
+import type { ToolFailureReasonCode } from "../inspection/tool-failure-classification.ts";
+
+const MAX_RECOVERY_FILE_BYTES = 8_192;
+const PRIVATE_PATH = /(?:^|\/)(?:\.git|\.pi|node_modules)(?:\/|$)|(?:^|\/)\.env(?:\.|$)|(?:^|\/)(?:auth|credentials?|secrets?|tokens?)\.json$/i;
+
+export type EditRecoveryContext = {
+  key: string;
+  targetPath: string;
+  text: string;
+  contentHash: string;
+  originalChars: number;
+  redacted: boolean;
+};
+
+function projectRelativeTarget(cwd: string, supplied: string): { root: string; absolute: string; relative: string } | undefined {
+  try {
+    const root = fs.realpathSync.native(cwd);
+    const suppliedAbsolute = path.resolve(root, supplied);
+    const suppliedRelative = path.relative(root, suppliedAbsolute).split(path.sep).join("/");
+    if (!suppliedRelative || suppliedRelative === "." || suppliedRelative === ".."
+      || suppliedRelative.startsWith("../") || path.isAbsolute(suppliedRelative)) return undefined;
+    let cursor = root;
+    for (const segment of suppliedRelative.split("/")) {
+      cursor = path.join(cursor, segment);
+      if (fs.lstatSync(cursor).isSymbolicLink()) return undefined;
+    }
+    const absolute = fs.realpathSync.native(suppliedAbsolute);
+    const relative = path.relative(root, absolute).split(path.sep).join("/");
+    if (!relative || relative === "." || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative)) return undefined;
+    return { root, absolute, relative };
+  } catch {
+    return undefined;
+  }
+}
+
+function stableSmallTextFile(root: string, absolute: string): string | undefined {
+  let descriptor: number | undefined;
+  try {
+    const initial = fs.lstatSync(absolute);
+    if (!initial.isFile() || initial.isSymbolicLink() || initial.size > MAX_RECOVERY_FILE_BYTES) return undefined;
+    const real = fs.realpathSync.native(absolute);
+    if (real !== root && !real.startsWith(`${root}${path.sep}`)) return undefined;
+    descriptor = fs.openSync(real, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    const observed = fs.fstatSync(descriptor);
+    if (!observed.isFile() || observed.dev !== initial.dev || observed.ino !== initial.ino
+      || observed.size !== initial.size || observed.mtimeMs !== initial.mtimeMs || observed.ctimeMs !== initial.ctimeMs
+      || observed.size > MAX_RECOVERY_FILE_BYTES) return undefined;
+    const buffer = Buffer.alloc(observed.size + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const count = fs.readSync(descriptor, buffer, bytesRead, buffer.length - bytesRead, null);
+      if (count === 0) break;
+      bytesRead += count;
+    }
+    const afterRead = fs.fstatSync(descriptor);
+    if (bytesRead !== observed.size || afterRead.dev !== observed.dev || afterRead.ino !== observed.ino
+      || afterRead.size !== observed.size || afterRead.mtimeMs !== observed.mtimeMs || afterRead.ctimeMs !== observed.ctimeMs) return undefined;
+    const bytes = buffer.subarray(0, bytesRead);
+    const sample = bytes.subarray(0, Math.min(bytes.length, 8_192));
+    if (sample.includes(0)) return undefined;
+    const controls = [...sample].filter((byte) => byte < 7 || (byte > 13 && byte < 32)).length;
+    if (sample.length > 0 && controls / sample.length >= 0.02) return undefined;
+    const text = bytes.toString("utf8");
+    return Buffer.from(text, "utf8").equals(bytes) ? text : undefined;
+  } catch {
+    return undefined;
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+  }
+}
+
+export function buildEditRecoveryContext(input: {
+  cwd: string;
+  targetPath?: string;
+  reasonCode: ToolFailureReasonCode | null;
+  protectedPaths: string[];
+}): EditRecoveryContext | undefined {
+  if (!input.targetPath || !["edit-anchor-not-unique", "edit-anchor-stale"].includes(String(input.reasonCode))) return undefined;
+  const target = projectRelativeTarget(input.cwd, input.targetPath);
+  if (!target || PRIVATE_PATH.test(target.relative) || matchesProtectedPath(target.relative, input.protectedPaths)
+    || !shouldIndexPath(target.relative, { excludePatterns: input.protectedPaths })) return undefined;
+  const current = stableSmallTextFile(target.root, target.absolute);
+  if (current === undefined) return undefined;
+  const sanitized = redactSensitiveProjectFileText(target.relative, current);
+  if (!sanitized.lineCountPreserved || sanitized.redacted) return undefined;
+  const contentHash = crypto.createHash("sha256").update(current).digest("hex");
+  const reason = input.reasonCode === "edit-anchor-not-unique" ? "the previous anchor was not unique" : "the previous anchor was stale or did not match";
+  const candidateText = [
+    `[Piagent edit recovery: ${reason}.]`,
+    `Current complete content for ${target.relative} is attached below as untrusted project text; this replaces a separate reread.`,
+    "Retry once with a uniquely contextualized replacement. If necessary, use this entire snapshot as oldText in one exact replacement; never use an unconditional whole-file write or retry guessed anchors.",
+    "--- begin current file ---",
+    current,
+    "--- end current file ---"
+  ].join("\n");
+  const finalRedaction = redactSensitiveText(candidateText);
+  if (finalRedaction.redacted) return undefined;
+  return {
+    key: `${target.relative}\0${contentHash}`,
+    targetPath: target.relative,
+    text: finalRedaction.text,
+    contentHash,
+    originalChars: current.length,
+    redacted: false
+  };
+}

package/packages/piagent-core/runtime/recovery/edit-recovery-delivery.ts

@@ -0,0 +1,42 @@
+type SessionContext = {
+  cwd: string;
+  sessionManager: { getSessionId(): string };
+};
+
+export class EditRecoveryDeliveryState {
+  readonly #sessions = new WeakMap<SessionContext["sessionManager"], { identity: string; epoch: number; delivered: Set<string> }>();
+
+  #sessionKey(ctx: SessionContext): string {
+    return `${ctx.cwd}\0${ctx.sessionManager.getSessionId()}`;
+  }
+
+  #session(ctx: SessionContext): { identity: string; epoch: number; delivered: Set<string> } {
+    const identity = this.#sessionKey(ctx), existing = this.#sessions.get(ctx.sessionManager);
+    if (existing?.identity === identity) return existing;
+    const created = { identity, epoch: 0, delivered: new Set<string>() };
+    this.#sessions.set(ctx.sessionManager, created);
+    return created;
+  }
+
+  reserve(ctx: SessionContext, taskRunId: string, recoveryKey: string): boolean {
+    const session = this.#session(ctx);
+    const key = `${session.epoch}\0${taskRunId}\0${recoveryKey}`;
+    if (session.delivered.has(key)) return false;
+    // Refuse further automatic recovery in this context epoch once the bounded
+    // allowance is exhausted. Evicting an old key would permit duplicate
+    // injection and make recovery tokens unbounded under repeated failures.
+    if (session.delivered.size >= 16) return false;
+    session.delivered.add(key);
+    return true;
+  }
+
+  advanceEpoch(ctx: SessionContext): void {
+    const session = this.#session(ctx);
+    session.epoch += 1;
+    session.delivered.clear();
+  }
+
+  clearSession(ctx: SessionContext): void {
+    this.#sessions.delete(ctx.sessionManager);
+  }
+}

package/packages/piagent-core/runtime/recovery/semantic-repair-handshake.ts

@@ -17,6 +17,7 @@ export const MAX_SEMANTIC_REPAIR_PATHS = 12;
 export const MAX_SEMANTIC_REPAIR_REVISIONS = 2;
 export const MAX_SEMANTIC_REPAIR_MUTATIONS = 8;
 export const MAX_SEMANTIC_REPAIR_UNSUCCESSFUL_CALLS = 3;
+export const BOUNDED_RECOVERY_CONFLICT_CODE = "post-verifier-model-omission";
 
 type RepairStatus = "reserved" | "authorized" | "active" | "retry-ready" | "verifier-pending" | "passed" | "cancelled" | "locked";
 type RepairPendingCall = {
@@ -173,6 +174,46 @@ export function decideSemanticRepairHandshake(input: {
   return { authorized: includesConflictingSource && targets.length === eligibleTargets.length, conflictCodes, eligibleTargets, eligiblePaths, pathConflictCodes };
 }
 
+/**
+ * Grant a single fail-closed recovery entry when the model notices an omission
+ * after a current exact verifier has already moved the task into verify.
+ *
+ * This is intentionally narrower than semantic repair: every target must be
+ * an actual current task delta, must have been observed in this task, and must
+ * still carry successful structured-mutation authorship for the exact task,
+ * run, and session. The caller separately enforces task scope and CAP-09/12/13
+ * authority before persisting the reservation.
+ */
+export function decideBoundedRecoveryHandshake(input: {
+  task: TaskContract;
+  mutationTargets: string[];
+  currentDeltaPaths: string[];
+  observedChangedPaths: string[];
+  authoredFileDigests: Record<string, string>;
+  verifierCurrent: boolean;
+}): SemanticRepairHandshakeDecision {
+  const targets = uniquePaths(input.mutationTargets);
+  const empty = { authorized: false, conflictCodes: [], eligibleTargets: [], eligiblePaths: [], pathConflictCodes: {} };
+  if (!input.verifierCurrent || targets.length === 0 || targets.length > MAX_SEMANTIC_REPAIR_PATHS) return empty;
+
+  const delta = new Set(uniquePaths(input.currentDeltaPaths));
+  const observed = new Set(uniquePaths(input.observedChangedPaths));
+  const authored = new Set(uniquePaths(Object.entries(input.authoredFileDigests)
+    .filter(([, digest]) => typeof digest === "string" && digest.length > 0)
+    .map(([file]) => file)));
+  const eligibleTargets = targets.filter((file) => delta.has(file) && observed.has(file) && authored.has(file));
+  if (eligibleTargets.length !== targets.length) return empty;
+
+  const pathConflictCodes = Object.fromEntries(targets.map((file) => [file, [BOUNDED_RECOVERY_CONFLICT_CODE]]));
+  return {
+    authorized: true,
+    conflictCodes: [BOUNDED_RECOVERY_CONFLICT_CODE],
+    eligibleTargets: targets,
+    eligiblePaths: targets,
+    pathConflictCodes
+  };
+}
+
 export function semanticRepairStatePath(cwd: string, taskRunId: string): string {
   return path.join(cwd, ".pi", "piagent-state", "semantic-repair", `${safeTaskId(taskRunId)}.json`);
 }
@@ -364,6 +405,7 @@ export function authorizeSemanticRepairCall(input: {
     return { handled: true, allowed: true, bypassPhase: false, state: writeState(input.cwd, state) };
   }
   if (state.status !== "active") return { handled: true, allowed: false, bypassPhase: false, reason: `semantic repair is ${state.status}` };
+  const boundedRecovery = state.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE);
   if (input.exactVerifier) {
     if (state.successfulMutationsInRevision < 1) return denyActiveCall(input.cwd, state, "semantic repair verifier requires a successful mutation in this revision", input.recordedAt);
     state.status = "verifier-pending";
@@ -372,6 +414,7 @@ export function authorizeSemanticRepairCall(input: {
     return { handled: true, allowed: true, bypassPhase: false, state: writeState(input.cwd, state) };
   }
   if (input.projectMutation) {
+    if (boundedRecovery) return denyActiveCall(input.cwd, state, "bounded recovery permits exactly one successful mutation before the exact verifier", input.recordedAt);
     const targets = uniquePaths(input.targetPaths);
     if (input.targetExtractionComplete === false) return denyActiveCall(input.cwd, state, "semantic repair mutation targets are not statically complete", input.recordedAt);
     if (targets.length === 0 || targets.some((file) => !state.eligiblePaths.includes(file))) return denyActiveCall(input.cwd, state, "semantic repair mutation is outside the exact persisted grant", input.recordedAt);
@@ -402,6 +445,7 @@ export function pendingSemanticRepairCall(cwd: string, taskRunId: string, toolCa
 export function completeSemanticRepairCall(input: {
   cwd: string; taskRunId: string; toolCallId: string; success: boolean; exitCode?: number;
   currentDigest: string; changedPaths: string[]; retryableFailure?: boolean; correctiveFailure?: boolean; recordedAt?: string;
+  authoredChangedPaths?: string[];
 }): { result: "unmatched" | "opened" | "recorded" | "retry" | "correction" | "passed" | "cancelled" | "locked"; state?: SemanticRepairState } {
   const view = readSemanticRepairState(input.cwd, input.taskRunId), state = view.state;
   if (!view.enforcementSafe || !state?.pending || state.pending.toolCallId !== input.toolCallId) return { result: "unmatched", state };
@@ -410,6 +454,7 @@ export function completeSemanticRepairCall(input: {
     return { result: "locked", state: writeState(input.cwd, state) };
   }
   const pending = state.pending, changed = uniquePaths(input.changedPaths), treeChanged = input.currentDigest !== pending.preDigest;
+  const boundedRecovery = state.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE);
   const now = input.recordedAt ?? new Date().toISOString();
   if (!pending.authorized) { state.status = "locked"; state.pending = null; state.updatedAt = now; return { result: "locked", state: writeState(input.cwd, state) }; }
   if (pending.kind === "verifier") {
@@ -418,12 +463,20 @@ export function completeSemanticRepairCall(input: {
     state.failedCalls += 1;
     if (treeChanged || unsuccessful(state) >= MAX_SEMANTIC_REPAIR_UNSUCCESSFUL_CALLS) state.status = "locked";
     else if (input.retryableFailure && !state.transientRetryUsed) { state.transientRetryUsed = true; state.status = "retry-ready"; }
-    else if (input.correctiveFailure && state.revision < MAX_SEMANTIC_REPAIR_REVISIONS) { state.revision += 1; state.successfulMutationsInRevision = 0; state.status = "active"; }
+    else if (!boundedRecovery && input.correctiveFailure && state.revision < MAX_SEMANTIC_REPAIR_REVISIONS) { state.revision += 1; state.successfulMutationsInRevision = 0; state.status = "active"; }
     else state.status = "locked";
     const result = state.status === "retry-ready" ? "retry" : state.status === "active" ? "correction" : "locked";
     return { result, state: writeState(input.cwd, state) };
   }
-  const unexpected = changed.length === 0 || changed.some((file) => !pending.targetPaths.includes(file) || !state.eligiblePaths.includes(file));
+  const authoredChanged = uniquePaths(input.authoredChangedPaths ?? []);
+  const boundedTargetMismatch = boundedRecovery
+    && (changed.length !== pending.targetPaths.length || changed.some((file, index) => pending.targetPaths[index] !== file));
+  const boundedAuthorshipMissing = boundedRecovery
+    && (authoredChanged.length !== changed.length || changed.some((file, index) => authoredChanged[index] !== file));
+  const unexpected = changed.length === 0
+    || changed.some((file) => !pending.targetPaths.includes(file) || !state.eligiblePaths.includes(file))
+    || boundedTargetMismatch
+    || boundedAuthorshipMissing;
   if (treeChanged && (!input.success || unexpected)) { state.status = "locked"; state.pending = null; state.updatedAt = now; return { result: "locked", state: writeState(input.cwd, state) }; }
   if (input.success && treeChanged) {
     if (pending.opensRepair) writeSemanticRepairOrigin(input.cwd, state, input.currentDigest, now);

package/packages/piagent-core/runtime/recovery/semantic-repair-runtime.ts

@@ -3,8 +3,10 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { TaskContract } from "../../extensions/guard-types.ts";
 import type { TrajectorySyncResult } from "../trajectory/trajectory-runtime.ts";
 import {
+  BOUNDED_RECOVERY_CONFLICT_CODE,
   authorizeSemanticRepairCall,
   completeSemanticRepairCall,
+  decideBoundedRecoveryHandshake,
   decideSemanticRepairHandshake,
   pendingSemanticRepairCall,
   readSemanticRepairState,
@@ -31,6 +33,7 @@ export type SemanticRepairCompletionMetadata = {
   exitCode: number;
   currentWorkingTreeDigest: string;
   changedPaths: string[];
+  authoredChangedPaths?: string[];
   retryableFailure: boolean; correctiveFailure: boolean;
 };
 
@@ -100,6 +103,52 @@ export class SemanticRepairRuntime {
     return true;
   }
 
+  prepareBoundedRecovery(input: {
+    ctx: ExtensionContext; task: TaskContract; event: ToolEvent; currentDigest: string;
+    currentDeltaPaths: string[]; observedChangedPaths: string[];
+    authoredFileDigests: Record<string, string>; targetPaths: string[]; verifierCurrent: boolean;
+  }): boolean {
+    // This path is a one-shot CAP-12 bridge, not CAP-13's multi-revision
+    // semantic-repair protocol. Any durable state, including a cancelled or
+    // interrupted reservation, consumes the task-run grant and fails closed.
+    if (readSemanticRepairState(input.ctx.cwd, input.task.taskRunId).status !== "missing"
+      || semanticRepairStateRequired(input.ctx.cwd, input.task.taskRunId)) return false;
+    const decision = decideBoundedRecoveryHandshake({
+      task: input.task,
+      mutationTargets: input.targetPaths,
+      currentDeltaPaths: input.currentDeltaPaths,
+      observedChangedPaths: input.observedChangedPaths,
+      authoredFileDigests: input.authoredFileDigests,
+      verifierCurrent: input.verifierCurrent
+    });
+    if (!decision.authorized) return false;
+    const toolCallId = String(input.event.toolCallId);
+    const reserved = reserveSemanticRepairCall({
+      cwd: input.ctx.cwd,
+      task: input.task,
+      sessionId: input.ctx.sessionManager.getSessionId(),
+      toolCallId,
+      toolName: input.event.toolName,
+      currentDigest: input.currentDigest,
+      decision,
+      targetPaths: input.targetPaths,
+      recordedAt: this.dependencies.now()
+    });
+    if (!reserved.reserved) return false;
+    this.reservationTokens.set(
+      this.reservationKey(input.ctx.cwd, input.task.taskRunId, toolCallId),
+      reserved.reservationToken!
+    );
+    this.dependencies.trace(input.ctx, input.task, {
+      event: "bounded_recovery_repair_reserved",
+      workingTreeDigest: input.currentDigest,
+      reasonCode: BOUNDED_RECOVERY_CONFLICT_CODE,
+      eligiblePaths: decision.eligiblePaths,
+      targetCount: input.targetPaths.length
+    });
+    return true;
+  }
+
   reservedCallMatches(input: {
     cwd: string; taskRunId: string; sessionId: string; toolCallId: string;
     toolName: string; currentDigest: string; targetPaths: string[];
@@ -131,7 +180,8 @@ export class SemanticRepairRuntime {
     if (view.state.successfulMutations > 0 && !semanticRepairOriginMatches(cwd, view.state)) return "semantic repair durable origin is missing or invalid";
     if (view.state.status === "passed") return;
     if (view.state.successfulMutations === 0 && view.state.pending === null && !semanticRepairStateRequired(cwd, taskRunId)) return;
-    return `semantic repair exact final verifier is not satisfied (${view.state.status})`;
+    const label = view.state.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE) ? "bounded recovery" : "semantic repair";
+    return `${label} exact final verifier is not satisfied (${view.state.status})`;
   }
 
   complete(
@@ -148,13 +198,16 @@ export class SemanticRepairRuntime {
       exitCode: metadata.exitCode,
       currentDigest: metadata.currentWorkingTreeDigest,
       changedPaths: metadata.changedPaths,
+      authoredChangedPaths: metadata.authoredChangedPaths,
       retryableFailure: metadata.retryableFailure,
       correctiveFailure: metadata.correctiveFailure,
       recordedAt: this.dependencies.now()
     });
     if (completion.result === "unmatched") return;
     this.dependencies.trace(ctx, task, {
-      event: completion.result === "opened" ? "semantic_contradiction_repair_opened" : `semantic_repair_${completion.result}`,
+      event: completion.state?.conflictCodes.includes(BOUNDED_RECOVERY_CONFLICT_CODE)
+        ? `bounded_recovery_repair_${completion.result}`
+        : completion.result === "opened" ? "semantic_contradiction_repair_opened" : `semantic_repair_${completion.result}`,
       toolName: event.toolName,
       revision: completion.state?.revision,
       successfulMutations: completion.state?.successfulMutations,

package/packages/piagent-core/runtime/registration/context-commands.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { stageContextDelivery } from "../context/context-delivery.ts";
 
 type ExtensionContext = any;
 
@@ -10,7 +11,7 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
     contextIndexV2Status, crypto, emitRuntimeMessage, ensureContextIndexV2, estimateContextTokens,
     formatContextPreflight,
     formatCount, formatPercent, fs, helpersMode, loadProfileFromContext, memoryHandbookPath,
-    policy, projectFilePath, resolveMemorySettings, resolveOrchestrationPolicy, searchContextIndex,
+    policy, projectFilePath, resolveMemorySettings, resolveOrchestrationPolicy, retrievalKey, runtimeState, searchContextIndex,
     searchContextIndexV2, selectRuntimeAction, semanticCompactionInstructions, telemetry
   } = deps;
   function emitContextIndexSearch(ctx: ExtensionContext, query: string): void {
@@ -123,6 +124,7 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
     });
     telemetry(ctx, {
       event: "context_pack",
+      turnId: runtimeState.currentTurn(ctx)?.turnId,
       queryHash: pack.queryHash,
       confidence: pack.confidence,
       candidates: pack.candidates,
@@ -131,12 +133,65 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
       selectedPaths: pack.selected.map((item) => item.path),
       source: "command"
     });
+    const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId());
+    const deliveryId = task?.trace?.outcome === "pending" && pack.selected.length > 0 ? crypto.randomUUID() : undefined;
+    if (deliveryId) {
+      stageContextDelivery(ctx, {
+        deliveryId,
+        taskRunId: task.taskRunId,
+        turnId: runtimeState.currentTurn(ctx)?.turnId,
+        entries: pack.selected.map((item) => ({
+          path: item.path,
+          reason: "Runtime confirmed delivery of a /context pack message."
+        })),
+        pack: {
+          retrievalKey: retrievalKey(ctx, query),
+          queryHash: pack.queryHash,
+          confidence: pack.confidence,
+          estimatedTokens: pack.estimatedTokens,
+          paths: pack.selected.map((item) => item.path)
+        },
+        injection: {
+          source: "context-command",
+          queryHash: pack.queryHash,
+          confidence: pack.confidence,
+          estimatedTokens: pack.estimatedTokens,
+          selectedItems: pack.selected.map((item) => ({
+            path: item.path,
+            estimatedTokens: item.estimatedTokens,
+            sources: item.sources,
+            links: item.links,
+            fileContentHash: item.fileContentHash,
+            ...(item.sanitizedContentDigest ? { sanitizedContentDigest: item.sanitizedContentDigest } : {}),
+            payloadHash: item.payloadHash,
+            representation: item.representation,
+            ranges: item.ranges,
+            generation: item.generation,
+            sensitiveContentRedacted: item.sensitiveContentRedacted
+          }))
+        }
+      }, { state: runtimeState, telemetry });
+    }
     emitRuntimeMessage(ctx, "piagent-context-pack-v2", pack.text, {
       queryHash: pack.queryHash,
       confidence: pack.confidence,
       estimatedTokens: pack.estimatedTokens,
       paths: pack.selected.map((item) => item.path),
-      finderRecommended: pack.finderRecommended
+      selectedItems: pack.selected.map((item) => ({
+        path: item.path,
+        estimatedTokens: item.estimatedTokens,
+        sources: item.sources,
+        links: item.links,
+        fileContentHash: item.fileContentHash,
+        ...(item.sanitizedContentDigest ? { sanitizedContentDigest: item.sanitizedContentDigest } : {}),
+        payloadHash: item.payloadHash,
+        representation: item.representation,
+        ranges: item.ranges,
+        generation: item.generation,
+        sensitiveContentRedacted: item.sensitiveContentRedacted
+      })),
+      finderRecommended: pack.finderRecommended,
+      contextDelivery: deliveryId ? { schemaVersion: 1, deliveryId } : undefined
     });
   }
 
@@ -156,13 +211,19 @@ export function registerContextCommands(pi: ExtensionAPI, deps: Record<string, a
     const report = buildContextEfficiencyReport(ctx.cwd);
     const task = activeSessionTask(ctx);
     const taskEfficiency = task ? buildTaskEfficiencyMetrics(ctx.cwd, task) : null;
+    const wasteScore = report.metrics.contextWasteScore === null
+      ? `unavailable (diagnostic estimate ${report.metrics.contextWasteScoreEstimate}/100; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`
+      : `${report.metrics.contextWasteScore}/100 (lower is better; evidence ${formatPercent(report.metrics.contextWasteScoreEvidenceCoverage)}, ${report.coverage.wasteScore.status})`;
     emitRuntimeMessage(ctx, "piagent-context-efficiency", [
-      `contextWasteScore: ${report.metrics.contextWasteScore}/100 (lower is better)`,
+      `contextWasteScore: ${wasteScore}`,
       `activeTools: ${report.metrics.averageActiveTools}`,
-      `toolSchemaShare: ${formatPercent(report.metrics.toolSchemaShare)}`,
-      `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.readCalls}`,
+      `toolSchemaPrefixShare: ${formatPercent(report.metrics.toolSchemaPrefixShare)}`,
+      `toolSchemaToSystemRatio: ${report.metrics.toolSchemaToSystemRatio}`,
+      `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.comparableReadCalls} comparable (${report.metrics.readCalls} observed; coverage ${formatPercent(report.metrics.readEvidenceCoverage)})`,
+      `fallbackRereads: ${report.metrics.contextFallbackRereads}/${report.metrics.contextSelections}`,
       `duplicateOutput: ${formatPercent(report.metrics.duplicateOutputRate)}`,
       `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
+      `editRecovery: ${report.metrics.editRecoveryContextCount}/${report.metrics.editRecoveryFailures} failures returned context; ${report.metrics.editRecoverySuppressedFailures} suppressed; ${report.metrics.editRecoveryEstimatedTokens} estimated tokens; classification coverage ${formatPercent(report.metrics.editRecoveryFailureEvidenceCoverage)}`,
       `taskEfficiency: ${taskEfficiency ? `${taskEfficiency.solver.route}; verify=${taskEfficiency.verification.attempts}; outcome=${taskEfficiency.outcome.task}` : "no active task"}`,
       ...report.recommendations.map((recommendation) => `- ${recommendation}`)
     ].join("\n"), { ...report, taskEfficiency });

package/packages/piagent-core/runtime/registration/policy-tools.ts

@@ -1,4 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { stageContextDelivery } from "../context/context-delivery.ts";
+import { formatContextEfficiencyReport } from "../context/context-efficiency-format.ts";
 
 type PiagentToolGroup = any;
 type TechStackManifest = any;
@@ -6,7 +8,7 @@ type TechStackManifest = any;
 
 export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>): void {
   const {
-    PIAGENT_TOOL_NAMES, READ_ONLY_TOOL_NAMES, StringEnum, Type, activateToolGroups,
+    PIAGENT_TOOL_NAMES, READ_ONLY_TOOL_NAMES, StringEnum, Type, activateToolGroups, activeSessionTask,
     buildContextEfficiencyReport, buildContextIndexStatus, buildContextIndexV2, buildContextPack, buildContextPreflight,
     buildTestImpact, buildUsageSnapshot, candidateFileBudget, contextBudgetConfig, contextIndexExcludePatterns,
     contextIndexV2Status, crypto, dynamicToolsEnabled, effectiveProtectedPaths, ensureContextIndexV2,
@@ -142,7 +144,48 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
           limit: 18,
           excludePatterns
         });
-        result = { ...pack, text: undefined, status };
+        telemetry(ctx, { event: "context_pack", turnId: runtimeState.currentTurn(ctx)?.turnId, source: "context-tool", queryHash: pack.queryHash, confidence: pack.confidence, candidates: pack.candidates, selected: pack.selected.length, estimatedTokens: pack.estimatedTokens, selectedPaths: pack.selected.map((item) => item.path) });
+        const task = activeSessionTask(ctx.cwd, ctx.sessionManager.getSessionId());
+        const deliveryId = task?.trace?.outcome === "pending" && pack.selected.length > 0 ? crypto.randomUUID() : undefined;
+        if (deliveryId) {
+          const packRetrievalKey = retrievalKey(ctx, params.query);
+          stageContextDelivery(ctx, {
+            deliveryId,
+            taskRunId: task.taskRunId,
+            turnId: runtimeState.currentTurn(ctx)?.turnId,
+            entries: pack.selected.map((item) => ({
+              path: item.path,
+              reason: "Runtime confirmed delivery of an explicit Context Engine tool pack."
+            })),
+            pack: {
+              retrievalKey: packRetrievalKey,
+              queryHash: pack.queryHash,
+              confidence: pack.confidence,
+              estimatedTokens: pack.estimatedTokens,
+              paths: pack.selected.map((item) => item.path)
+            },
+            injection: {
+              source: "context-tool",
+              queryHash: pack.queryHash,
+              confidence: pack.confidence,
+              estimatedTokens: pack.estimatedTokens,
+              selectedItems: pack.selected.map((item) => ({
+                path: item.path,
+                estimatedTokens: item.estimatedTokens,
+                sources: item.sources,
+                links: item.links,
+                fileContentHash: item.fileContentHash,
+                ...(item.sanitizedContentDigest ? { sanitizedContentDigest: item.sanitizedContentDigest } : {}),
+                payloadHash: item.payloadHash,
+                representation: item.representation,
+                ranges: item.ranges,
+                generation: item.generation,
+                sensitiveContentRedacted: item.sensitiveContentRedacted
+              }))
+            }
+          }, { state: runtimeState, telemetry });
+        }
+        result = { ...pack, text: undefined, status, contextDelivery: deliveryId ? { schemaVersion: 1, deliveryId } : undefined };
         text = pack.text;
       } else if (params.action === "impact") {
         await ensureContextIndexV2(ctx.cwd, { excludePatterns, rebuildMissing: false });
@@ -156,15 +199,7 @@ export function registerPolicyTools(pi: ExtensionAPI, deps: Record<string, any>)
       } else {
         result = buildContextEfficiencyReport(ctx.cwd);
         const report = result as ReturnType<typeof buildContextEfficiencyReport>;
-        text = [
-          `contextWasteScore: ${report.metrics.contextWasteScore}/100 (lower is better)`,
-          `activeTools: ${report.metrics.averageActiveTools}`,
-          `toolSchemaShare: ${formatPercent(report.metrics.toolSchemaShare)}`,
-          `duplicateReads: ${report.metrics.duplicateReads}/${report.metrics.readCalls}`,
-          `duplicateOutput: ${formatPercent(report.metrics.duplicateOutputRate)}`,
-          `lowConfidencePacks: ${report.metrics.lowConfidencePacks}/${report.sample.contextPacks}`,
-          ...report.recommendations.map((recommendation) => `- ${recommendation}`)
-        ].join("\n");
+        text = formatContextEfficiencyReport(report, formatPercent);
       }
       telemetry(ctx, {
         event: "context_engine_action",