@evoclock/pi-agentic-driver 1.1.1 → 2.0.0

package/scripts/enforcement/herdr_communication_pi.js

@@ -219,7 +219,7 @@ function boundedString(value, field, maxBytes = MAX_PROCESS_OUTPUT_BYTES) {
   return value;
 }
 
-function expectedRepository(context) {
+export function expectedRepository(context) {
   const value = context?.repository ?? context?.cwd;
   if (typeof value !== "string" || !value.trim()) {
     throw communicationError("repository_unavailable", "the current repository is unavailable");
@@ -303,7 +303,7 @@ function checkedRegistryPath(primary) {
   // Registry lookup order (coordinator decision): the session repository's
   // own config first; when missing (ENOENT only) the active Pi profile's
   // shared config under {PI_CODING_AGENT_DIR}/config/ (fallback
-  // ~/.pi/agent/config/). When neither exists, return the repo-local path so
+  // the installed agent config directory). When neither exists, return the repo-local path so
   // the caller's primary-only fallback applies exactly as before.
   const profileDir = process.env.PI_CODING_AGENT_DIR;
   const base = typeof profileDir === "string" && profileDir.trim()
@@ -1257,10 +1257,81 @@ export function extractLatestHerdrReport(text, role) {
 // ---------------------------------------------------------------------------
 
 const deliveries = new Map();
+let offlineDeliveries = new WeakMap();
 let deliverySeq = 0;
 
+function deliveryRecords(options) {
+  if (!options.offlinePersistence) return deliveries;
+  if (!offlineDeliveries.has(options.offlinePersistence)) offlineDeliveries.set(options.offlinePersistence, new Map());
+  return offlineDeliveries.get(options.offlinePersistence);
+}
+
+function requireOfflinePersistence(options) {
+  const store = options.offlinePersistence;
+  if (!store) return;
+  if (store.schema !== "agentic-driver.offline-seam-store.v1" || typeof options.runProcess !== "function" ||
+      ["get", "reserve", "update"].some((name) => typeof store[name] !== "function")) {
+    throw communicationError("offline_persistence_required", "persistence requires the offline store and injected process adapter", "denied");
+  }
+}
+
+async function deliverPersistedPrompt(operation, request, context, options, signal, repositories) {
+  const repository = expectedRepository(context);
+  const digest = createHash("sha256").update(JSON.stringify({ repository, role: request.role, prompt: request.prompt })).digest("hex");
+  const requestId = options.offlineRequestId ?? digest;
+  if (typeof requestId !== "string" || !/^[a-z0-9-]{1,128}$/.test(requestId)) throw communicationError("offline_request_invalid", "bounded offline request identity required", "denied");
+  const identity = createHash("sha256").update(`${repository}\u0000${requestId}`).digest("hex");
+  // Retain the existing correlation grammar; the suffix is opaque, not a clock.
+  const id = `dlv-${identity.slice(0, 16)}-${identity.slice(16, 32)}`;
+  // Validate the complete framed brief before leaving a persistent tombstone.
+  promptWithReportRequirement(request.role, request.prompt, id);
+  const store = options.offlinePersistence;
+  const reserved = await store.reserve("delivery", { id, digest, repository, role: request.role, createdAt: Date.now(), state: "queued" });
+  if (!reserved.created) {
+    const accepted = ["delivered", "answered"].includes(reserved.record.state);
+    return { schema: HERDR_COMMUNICATION_SCHEMA, ok: accepted, status: accepted ? "accepted" : "refused", operation,
+      deliveryId: id, role: request.role, deliveryState: reserved.record.state, acceptedAt: reserved.record.acceptedAt,
+      duplicate: true, promptSent: false, held: !accepted, persisted: true, nonAuthorizing: true, authorityCreated: false };
+  }
+  await options.offlineBoundary?.("after-delivery-intent", { deliveryId: id });
+  const sent = await deliverPrompt(operation, request, context, { ...options, offlineDeliveryId: id }, signal, repositories);
+  await options.offlineBoundary?.("after-delivery-send", { deliveryId: id });
+  const latest = await store.get("delivery", id);
+  const patch = { state: latest.state === "held" ? "held" : sent.deliveryState ?? "failed" };
+  if (sent.acceptedAt) patch.acceptedAt = sent.acceptedAt;
+  if (sent.code) patch.code = sent.code;
+  const committed = await store.update("delivery", id, digest, patch);
+  await options.offlineBoundary?.("after-delivery-ack", { deliveryId: id });
+  return { ...sent, ...(committed.state === "held" ? { ok: false, status: "refused", held: true, deliveryState: "unknown" } : {}), deliveryId: id, persisted: true };
+}
+
+async function queryPersistedDelivery(request, context, options, signal, repositories) {
+  const store = options.offlinePersistence;
+  const saved = await store.get("delivery", request.deliveryId);
+  if (!saved) return deliveryRefusal("delivery", communicationError("delivery_unknown", "no persisted delivery is known"));
+  if (saved.repository !== expectedRepository(context)) throw communicationError("repository_mismatch", "delivery belongs to another repository", "denied");
+  requireRole(saved.role);
+  if (saved.state === "held") return deliverySnapshot({ ...saved, deliveryId: saved.id, state: "unknown" }, { held: true, code: saved.code ?? "delivery-held", persisted: true });
+  if (saved.state === "answered" && saved.proof === "snapshot-backed-v1") {
+    return deliverySnapshot({ ...saved, deliveryId: saved.id }, { report: saved.report, reportMarkers: reportMarkersForRole(saved.role), answeredAt: saved.answeredAt, persisted: true });
+  }
+  if (!deliveryRecords(options).has(saved.id)) {
+    // Neither terminal snapshots nor framed echoes are restored from disk.
+    // Original proof lost means hold, even if the role is now idle/done.
+    if (saved.state !== "failed" && saved.state !== "held") await store.update("delivery", saved.id, saved.digest, { state: "held", code: "attribution-lost" });
+    return deliverySnapshot({ ...saved, deliveryId: saved.id, state: saved.state === "failed" ? "failed" : "unknown" },
+      { held: saved.state !== "failed", code: saved.state === "failed" ? saved.code : "attribution-lost", persisted: true });
+  }
+  const observed = await queryDelivery(request, context, options, signal, repositories);
+  if (observed.deliveryState === "answered") {
+    await store.update("delivery", saved.id, saved.digest, { state: "answered", report: observed.report, answeredAt: observed.answeredAt, proof: "snapshot-backed-v1" });
+  }
+  return { ...observed, persisted: true };
+}
+
 export function resetHerdrDeliveriesForTests() {
   deliveries.clear();
+  offlineDeliveries = new WeakMap();
 }
 
 function evictDeliveries() {
@@ -1280,12 +1351,12 @@ function stateChangeSeq(value) {
   return Number.isSafeInteger(seq) && seq >= 0 ? seq : undefined;
 }
 
-function createDelivery(role, prompt, pre, seqBefore) {
-  evictDeliveries();
+function createDelivery(role, prompt, pre, seqBefore, options = {}) {
+  if (!options.offlinePersistence) evictDeliveries();
   const createdAt = Date.now();
   const seq = (deliverySeq += 1);
   const digest = createHash("sha256").update(`${role}\u0000${createdAt}\u0000${seq}`).digest("hex");
-  const deliveryId = `dlv-${digest.slice(0, 16)}-${createdAt.toString(36)}`;
+  const deliveryId = options.offlineDeliveryId ?? `dlv-${digest.slice(0, 16)}-${createdAt.toString(36)}`;
   const sentPrompt = promptWithReportRequirement(role, prompt, deliveryId);
   const record = {
     deliveryId,
@@ -1304,7 +1375,7 @@ function createDelivery(role, prompt, pre, seqBefore) {
     code: undefined,
     reason: undefined,
   };
-  deliveries.set(record.deliveryId, record);
+  deliveryRecords(options).set(record.deliveryId, record);
   return record;
 }
 
@@ -1370,7 +1441,7 @@ async function deliverPrompt(operation, request, context, options, signal, repos
   // unconfirmed returns the existing delivery instead of re-handing off.
   // After the window, or once the prior delivery is confirmed
   // (delivered/answered/failed), a repeat is a genuinely new delivery.
-  const duplicate = findUnconfirmedDelivery(role, request.prompt);
+  const duplicate = options.offlinePersistence ? undefined : findUnconfirmedDelivery(role, request.prompt);
   if (duplicate) {
     if (duplicate.state === "queued") {
       return {
@@ -1419,7 +1490,11 @@ async function deliverPrompt(operation, request, context, options, signal, repos
     } catch {
       pre = undefined;
     }
-    record = createDelivery(role, request.prompt, pre, stateChangeSeq(current));
+    record = createDelivery(role, request.prompt, pre, stateChangeSeq(current), options);
+    if (options.offlinePersistence) {
+      const latest = await options.offlinePersistence.get("delivery", record.deliveryId);
+      if (latest?.state !== "queued") throw communicationError("delivery_held", "persisted delivery is held; no handoff started");
+    }
     // Handoff: `agent prompt` without --wait returns as soon as the CLI
     // accepts the brief. The acceptance window is internal
     // (COMMAND_TIMEOUT_MS); timeoutMs never schedules a model round-trip.
@@ -1468,28 +1543,88 @@ async function deliverPrompt(operation, request, context, options, signal, repos
   }
 }
 
-// The per-handoff echo boundary. A boundary exists only where the FULL
-// framed prompt — caller text, contract line, marker template, this
-// delivery's correlation line, and the instruction line — is echoed at a
-// line start and parses as one echoed contract unit. A bare or partially
-// fabricated "Delivery:" line in live terminal text mints no boundary, and
-// a delivery without a pre-delivery snapshot is unattributed before any
-// boundary is ever searched. The correlation line is not an authenticator:
-// terminal text stays untrusted evidence, and no authority is ever derived
-// from it.
+// The per-handoff echo boundary. A boundary exists only where a FULL
+// echoed contract unit is observable in the snapshot: the caller's prompt
+// text (bounded terminal normalization), the contract line at
+// a line start (bounded horizontal whitespace only), the marker template
+// (with the same horizontal padding and right-hand box-border tolerance
+// marker parsing already applies — Herdr's recent-unwrapped snapshot pads
+// standalone marker lines to the terminal width and can retain Pi's `│`
+// border, so a byte-exact sentPrompt echo must not be required), this
+// delivery's correlation line, and the instruction line. A bare or partially
+// fabricated "Delivery:" line mints no boundary, and a delivery without a
+// pre-delivery snapshot is unattributed before any boundary is ever
+// searched. The correlation line is not an authenticator: terminal text
+// stays untrusted evidence, and no authority is ever derived from it.
+// A framed echo renders the caller's prompt text immediately before the
+// contract line. Compare its complete, bounded line sequence so embedded
+// contract text in the caller prompt cannot truncate the expected text.
+// Preserve caller whitespace and line breaks; allow only bounded extra
+// horizontal terminal padding (and its optional right-hand box border) after
+// each exact caller line. A contract-plus-tail echo with a missing caller line
+// is a partial echo.
+function echoedCallerPromptPrecedes(text, range, callerPrompt) {
+  const expectedLines = callerPrompt.replace(/\r\n/g, "\n").split("\n");
+  const window = Math.min(
+    MAX_PROCESS_OUTPUT_BYTES,
+    Buffer.byteLength(callerPrompt, "utf8")
+      + expectedLines.length * (MAX_MARKER_HORIZONTAL_WHITESPACE + 8) + 8,
+  );
+  const from = Math.max(0, range.start - window);
+  const beforeContract = text.slice(from, range.start).replace(/\r\n/g, "\n");
+  if (!beforeContract.endsWith("\n")) return false;
+  const observedLines = beforeContract.slice(0, -1).split("\n");
+  if (observedLines.length < expectedLines.length) return false;
+  const callerLines = observedLines.slice(-expectedLines.length);
+  return expectedLines.every((expected, index) => {
+    const observed = callerLines[index];
+    if (!observed.startsWith(expected)) return false;
+    let padding = observed.slice(expected.length);
+    if (padding.endsWith("│")) padding = padding.slice(0, -1);
+    return Buffer.byteLength(padding, "utf8") <= MAX_MARKER_HORIZONTAL_WHITESPACE
+      && /^[ \t]*$/.test(padding);
+  });
+}
+
+function handoffEchoTailEnd(text, from, correlationLine) {
+  // Each padded line may consume up to MAX_MARKER_HORIZONTAL_WHITESPACE
+  // bytes; the window must span three framing lines plus the literal tail.
+  const window = text.slice(from, from + MAX_MARKER_HORIZONTAL_WHITESPACE * 3 + correlationLine.length + 128);
+  const match = new RegExp(
+    "^[ \\t]*(?:│)?\\r?\\n[ \\t]*(?:│)?" + correlationLine + "[ \\t│]*\\r?\\n"
+    + "[ \\t]*(?:│)?Begin your report with the Delivery line above, exactly as written\\.[ \\t│]*(?:\\r?\\n|$)",
+  ).exec(window);
+  return match ? from + match[0].length : undefined;
+}
+
 function handoffBoundaryIn(text, record) {
   const marker = reportMarkersForRole(record.role);
-  const starts = lineStarts(text);
-  let from = 0;
-  while (true) {
-    const start = text.indexOf(record.sentPrompt, from);
-    if (start < 0) return undefined;
-    from = start + 1;
-    if (!starts.includes(start)) continue;
-    const range = promptContractRange(text, marker, start + record.sentPrompt.length, { boundEnd: true });
-    if (!range || range.end !== start + record.sentPrompt.length) continue;
-    return { start, end: range.end };
+  const correlationLine = `Delivery: ${record.deliveryId}`;
+  for (const occurrence of allMarkerOccurrences(text, true, marker)) {
+    if (occurrence.marker !== marker.close) continue;
+    // promptContractRange validates the echoed contract structure tolerantly
+    // (contract line, both markers, bounded size, no foreign markers) and
+    // already tolerates horizontal padding and the box border between the
+    // markers themselves.
+    const range = promptContractRange(text, marker, occurrence.index);
+    if (!range || range.end <= occurrence.index) continue;
+    // The echoed contract must begin at a line start, exactly as the
+    // byte-exact boundary it replaces did.
+    const lineStart = text.lastIndexOf("\n", range.start - 1) + 1;
+    const leading = text.slice(lineStart, range.start);
+    if (Buffer.byteLength(leading, "utf8") > MAX_MARKER_HORIZONTAL_WHITESPACE || !/^[ \\t]*$/.test(leading)) continue;
+    // The tail must self-identify THIS handoff by its unique correlation
+    // line, with the same padding/border tolerance as marker lines.
+    const end = handoffEchoTailEnd(text, occurrence.end, correlationLine);
+    if (end === undefined) continue;
+    // The caller's own prompt text must be echoed immediately before the
+    // contract line under the same bounded terminal normalization. A bare
+    // contract-plus-tail echo is a fabricated partial echo and mints no
+    // boundary even when it quotes this delivery's correlation line.
+    if (!echoedCallerPromptPrecedes(text, range, record.prompt)) continue;
+    return { start: range.start, end };
   }
+  return undefined;
 }
 
 function reportRegionsAfter(text, role, fromIndex) {
@@ -1542,7 +1677,7 @@ function regionBody(text, role, region, correlationLine) {
 }
 
 async function queryDelivery(request, context, options, signal, repositories) {
-  const record = typeof request.deliveryId === "string" ? deliveries.get(request.deliveryId) : undefined;
+  const record = typeof request.deliveryId === "string" ? deliveryRecords(options).get(request.deliveryId) : undefined;
   if (!record) {
     return deliveryRefusal("delivery", communicationError("delivery_unknown", "no live delivery record is known for this deliveryId (bounded, in-memory)"));
   }
@@ -1644,6 +1779,36 @@ async function queryDelivery(request, context, options, signal, repositories) {
 // Legacy blocking exchange (prompt → wait → provenanced report read). It is
 // no longer reachable from the tool surface; the dispatch journey keeps its
 // single-exchange semantics through this entry point unchanged.
+export async function inspectHerdrJourneyMarker(role, requestId, context, options = {}, signal) {
+  requireRole(role);
+  if (typeof requestId !== "string" || !/^[a-zA-Z0-9_-]{1,100}:[1-9][0-9]{0,2}$/.test(requestId)) {
+    throw communicationError("journey-id-invalid", "bounded journey request ID required", "denied");
+  }
+  const repositories = trustedRepositories(expectedRepository(context));
+  const current = await invokeHerdr("get", { action: "get", role }, context, options, signal);
+  publicAgentObservation(extractAgent(current, "agent_info"), role, repositories);
+  const history = readText(await invokeHerdr("read", { action: "read", role, readLines: MAX_REPORT_READ_LINES }, context, options, signal));
+  // Absence is never evidence that an asynchronous pane send did not land.
+  const lines = history.split("\n");
+  const tag = `[journey:${requestId}]`;
+  const occurrences = lines.filter((line) => line.trim() === tag).length;
+  if (occurrences !== 1) return { present: false };
+  const from = history.indexOf(tag) + tag.length;
+  const tail = history.slice(from);
+  // One report only, with no later journey prompt. An unrelated or ambiguous
+  // pane exchange is not attributable merely because it is the latest text.
+  if (/^\[journey:[^\]]+\]$/m.test(tail)) return { present: true };
+  const markers = reportMarkersForRole(role);
+  const relevant = allMarkerOccurrences(tail, true, markers)
+    .filter((item) => (item.marker === markers.open || item.marker === markers.close)
+      && !isPromptContractMarker(history, { index: item.index + from, end: item.end + from }, markers));
+  if (relevant.length !== 2 || relevant[0].marker !== markers.open || relevant[1].marker !== markers.close) {
+    return { present: true };
+  }
+  try { return { present: true, report: extractReportFromSegment(history, role, from) }; }
+  catch { return { present: true }; }
+}
+
 export async function executeHerdrPromptExchange(params, context, options = {}, signal) {
   let request;
   const operation = "prompt";
@@ -1742,6 +1907,10 @@ export async function executeHerdrCommunication(params, context, options = {}, s
   try {
     request = validateParams(params);
     operation = request.action;
+    requireOfflinePersistence(options);
+    if (options.offlinePersistence && !["prompt", "submit", "delivery"].includes(operation)) {
+      throw communicationError("offline_delivery_required", "offline persistence requires a delivery-bound operation; role-keyed fallback is refused", "denied");
+    }
     const repository = expectedRepository(context);
     const repositories = trustedRepositories(repository);
     if (operation === "list") {
@@ -1758,11 +1927,16 @@ export async function executeHerdrCommunication(params, context, options = {}, s
       // return an explicit receipt immediately. No model round-trip happens
       // on this path; settlement is observed through the `delivery` action,
       // get, wait, and read.
-      return await deliverPrompt(operation, request, context, options, signal, repositories);
+      return options.offlinePersistence
+        ? await deliverPersistedPrompt(operation, request, context, options, signal, repositories)
+        : await deliverPrompt(operation, request, context, options, signal, repositories);
     }
     if (operation === "delivery") {
-      // Read-only, non-authorizing per-delivery state query.
-      return await queryDelivery(request, context, options, signal, repositories);
+      // Non-authorizing observation. Offline mode may persist proof or an
+      // attribution-loss hold, but never sends; default mode is unchanged.
+      return options.offlinePersistence
+        ? await queryPersistedDelivery(request, context, options, signal, repositories)
+        : await queryDelivery(request, context, options, signal, repositories);
     }
     if (operation === "wait") {
       const raw = await invokeHerdr(operation, request, context, options, signal);