@piagent/platform 1.6.1 → 1.8.0

package/packages/piagent-webui/server/loopback-server.ts

@@ -13,13 +13,13 @@ const MAX_BOOTSTRAP_BODY_BYTES = 4_096;
 const MAX_CONTROL_BODY_BYTES = 70_000;
 const MAX_ATTACHMENT_BODY_BYTES = 11_250_000;
 const REQUESTS_PER_MINUTE = 120;
-const BOOTSTRAPS_PER_MINUTE = 8;
+const BOOTSTRAP_FAILURES_PER_MINUTE = 8;
 const CONTROLS_PER_MINUTE = 60;
 const MAX_JSON_RESPONSE_BYTES = 16 * 1024 * 1024;
 const CURSOR = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
 
 type ReadCapabilities = () => unknown | Promise<unknown>;
-type RateState = { windowStart: number; requests: number; bootstraps: number };
+type RateState = { windowStart: number; requests: number; bootstrapFailures: number };
 type ControlRateState = { windowStart: number; controls: number };
 
 export type LoopbackServer = {
@@ -109,8 +109,8 @@ export async function startLoopbackServer(options: {
     const browserSession = auth.authenticate(request, now);
     const rateKey = browserSession ? `${remote}:${browserSession.id}` : `remote:${remote}`;
     for (const [key, value] of rates) if (now - value.windowStart >= 60_000) rates.delete(key);
-    const rate = rates.get(rateKey) ?? { windowStart: now, requests: 0, bootstraps: 0 };
-    if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstraps: 0 });
+    const rate = rates.get(rateKey) ?? { windowStart: now, requests: 0, bootstrapFailures: 0 };
+    if (now - rate.windowStart >= 60_000) Object.assign(rate, { windowStart: now, requests: 0, bootstrapFailures: 0 });
     rate.requests += 1; rates.set(rateKey, rate);
     while (rates.size > 128) rates.delete(rates.keys().next().value as string);
     if (rate.requests > REQUESTS_PER_MINUTE) return errorResponse(response, 429, "rate-limit");
@@ -120,8 +120,6 @@ export async function startLoopbackServer(options: {
     if (url.hash || url.username || url.password || url.origin !== origin) return errorResponse(response, 400, "invalid-url");
 
     if (request.method === "POST" && url.pathname === "/api/v1/bootstrap") {
-      rate.bootstraps += 1;
-      if (rate.bootstraps > BOOTSTRAPS_PER_MINUTE) return errorResponse(response, 429, "bootstrap-rate-limit");
       if (requestOrigin !== origin) return errorResponse(response, 403, "origin-required");
       if (!String(request.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return errorResponse(response, 415, "content-type");
       let value: unknown;
@@ -129,7 +127,11 @@ export async function startLoopbackServer(options: {
       catch (error) { return errorResponse(response, (error as Error).message === "body-limit" ? 413 : 400, "invalid-bootstrap"); }
       const capability = value && typeof value === "object" ? (value as Record<string, unknown>).capability : null;
       const session = typeof capability === "string" ? auth.exchange(capability) : null;
-      if (!session) return errorResponse(response, 403, "bootstrap-rejected");
+      if (!session) {
+        rate.bootstrapFailures += 1;
+        if (rate.bootstrapFailures > BOOTSTRAP_FAILURES_PER_MINUTE) return errorResponse(response, 429, "bootstrap-rate-limit");
+        return errorResponse(response, 403, "bootstrap-rejected");
+      }
       response.setHeader("Set-Cookie", auth.cookieHeader(session));
       return jsonResponse(response, 200, { authenticated: true, csrfToken: session.csrf, expiresAt: new Date(session.expiresAt).toISOString() });
     }

package/packages/piagent-webui/server/terminal-delivery-receipt.ts

@@ -0,0 +1,144 @@
+import { isDeepStrictEqual } from "node:util";
+import fs from "node:fs";
+
+import { webUiMessageCorrelationEntry, type WebUiMessageCorrelation } from "../shared/message-correlation.ts";
+
+// As in CoreInspectionProvider, load core through the server boundary. Its
+// internal source types are not part of the strict browser contract graph.
+const CORE_ROOT = "../../piagent-core";
+const [{ activeSessionTask }, { isUncertainSendContinuation, terminalUncertainSendReceipt }] = await Promise.all([
+  import(`${CORE_ROOT}/extensions/task-state.js`),
+  import(`${CORE_ROOT}/runtime/session/uncertain-send-continuation.ts`)
+]);
+
+export type TerminalDeliveryReceipt = { customType: string; content: string; details: {
+  taskId: string; taskRunId: string; outcome: string; completionApproved: boolean; gateDecision: string;
+  [key: string]: unknown;
+} };
+
+export function readTerminalDeliveryReceipt(cwd: string, task: unknown): TerminalDeliveryReceipt | undefined {
+  return terminalUncertainSendReceipt(cwd, task);
+}
+
+export const TERMINAL_DELIVERY_CONFIRMATION_TYPE = "piagent-webui-terminal-delivery-v1";
+export type TerminalDeliveryPair = { requestEntry: any; receiptEntry: any; confirmationEntry?: any; request: string;
+  correlation: WebUiMessageCorrelation; receipt: TerminalDeliveryReceipt };
+
+/** Strict bounded readback; an in-memory Pi branch is not a persistence acknowledgment. */
+export function terminalDeliverySessionEntries(file: string | undefined, sessionId: string): unknown[] {
+  if (!file) return [];
+  let descriptor: number | undefined;
+  try {
+    descriptor = fs.openSync(file, "r");
+    const stat = fs.fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > 64 * 1024 * 1024) return [];
+    const source = fs.readFileSync(descriptor, "utf8");
+    if (!source.endsWith("\n") || Buffer.byteLength(source) > 64 * 1024 * 1024) return [];
+    const lines = source.trimEnd().split("\n");
+    if (lines.length > 50_001) return [];
+    // Pi's generic parser tolerates corrupt lines. Delivery requires every
+    // persisted record, including the confirmation, to be complete and valid.
+    const [header, ...entries] = lines.map((line) => JSON.parse(line));
+    return header?.type === "session" && header.version === 3 && header.id === sessionId ? entries : [];
+  } catch { return []; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+}
+
+/** Only this handled-input protocol needs a request anchor outside model history. */
+export function terminalDeliveryRequest(message: unknown, images?: unknown[]): string | undefined {
+  return typeof message === "string" && message.length <= 65_536 && !images?.length
+    && isUncertainSendContinuation(message) ? message : undefined;
+}
+
+function matchesReceipt(value: any, expected: TerminalDeliveryReceipt): boolean {
+  return value?.display === true && value.customType === expected.customType && value.content === expected.content
+    && isDeepStrictEqual(value.details, expected.details);
+}
+
+function hasEntryIdentity(value: any): boolean {
+  return typeof value?.id === "string" && value.id.length > 0 && value.id.length <= 160
+    && typeof value.timestamp === "string" && Number.isFinite(Date.parse(value.timestamp));
+}
+
+function confirmationData(pair: TerminalDeliveryPair): Record<string, unknown> {
+  return { schemaVersion: 1, ...pair.correlation, receiptEntryId: pair.receiptEntry.id,
+    taskId: pair.receipt.details.taskId, taskRunId: pair.receipt.details.taskRunId };
+}
+
+function receiptPairs(entries: unknown[], expected: TerminalDeliveryReceipt | undefined,
+  confirmed: boolean): TerminalDeliveryPair[] {
+  if (!expected || !Array.isArray(entries) || entries.length > 50_000) return [];
+  const pairs: TerminalDeliveryPair[] = [];
+  const operations = new Map<string, number>(), requests = new Map<string, number>(), entryIds = new Map<string, number>();
+  for (const entry of entries) {
+    const id = (entry as any)?.id;
+    if (typeof id === "string") entryIds.set(id, (entryIds.get(id) ?? 0) + 1);
+    const correlation = webUiMessageCorrelationEntry(entry);
+    if (correlation) {
+      operations.set(correlation.operationRef, (operations.get(correlation.operationRef) ?? 0) + 1);
+      requests.set(correlation.messageRequestId, (requests.get(correlation.messageRequestId) ?? 0) + 1);
+    }
+  }
+  for (let index = 1; index < entries.length; index += 1) {
+    const requestEntry = entries[index - 1] as any, receiptEntry = entries[index] as any;
+    const correlation = webUiMessageCorrelationEntry(requestEntry);
+    const request = terminalDeliveryRequest(requestEntry?.data?.terminalDeliveryRequest);
+    if (!correlation || request === undefined || receiptEntry?.type !== "custom_message"
+      || !hasEntryIdentity(requestEntry) || !hasEntryIdentity(receiptEntry)
+      || entryIds.get(requestEntry.id) !== 1 || entryIds.get(receiptEntry.id) !== 1
+      || !matchesReceipt(receiptEntry, expected)) continue;
+    const pair: TerminalDeliveryPair = { requestEntry, receiptEntry, request, correlation, receipt: expected };
+    if (confirmed) {
+      const confirmation = entries[index + 1] as any;
+      if (confirmation?.type !== "custom" || confirmation.customType !== TERMINAL_DELIVERY_CONFIRMATION_TYPE
+        || !hasEntryIdentity(confirmation) || entryIds.get(confirmation.id) !== 1
+        || !isDeepStrictEqual(confirmation.data, confirmationData(pair))) continue;
+      pair.confirmationEntry = confirmation;
+    }
+    pairs.push(pair);
+  }
+  return pairs.filter((pair) => operations.get(pair.correlation.operationRef) === 1
+    && requests.get(pair.correlation.messageRequestId) === 1);
+}
+
+/** A projection may show only a receipt whose operation reached durable delivery settlement. */
+export function terminalDeliveryPairs(entries: unknown[], expected: TerminalDeliveryReceipt | undefined,
+  persistedEntries: unknown[] = []): TerminalDeliveryPair[] {
+  const persisted = new Map(receiptPairs(persistedEntries, expected, true).map((pair) => [pair.receiptEntry.id, pair]));
+  return receiptPairs(entries, expected, true).filter((pair) => {
+    const disk = persisted.get(pair.receiptEntry.id);
+    return disk && isDeepStrictEqual(pair.requestEntry, disk.requestEntry) && isDeepStrictEqual(pair.receiptEntry, disk.receiptEntry)
+      && isDeepStrictEqual(pair.confirmationEntry, disk.confirmationEntry);
+  });
+}
+
+/**
+ * Compare the observed custom message with current core state and this exact
+ * operation's latest durable receipt. Persist a delivery observation before
+ * the gateway acknowledges settlement. This marker grants no task authority;
+ * transcript reads still require the independently reread core receipt.
+ */
+export function terminalDeliveryReceiptCommitter(input: { cwd: string; sessionId: string; operationRef: string;
+  messageRequestId: string | null; request?: string; entries(): unknown[]; persistedEntries(): unknown[];
+  appendCustomEntry(type: string, data: Record<string, unknown>): unknown }):
+  (message: unknown) => TerminalDeliveryReceipt | undefined {
+  return (message) => {
+    if (input.request === undefined || !input.messageRequestId || (message as any)?.role !== "custom") return undefined;
+    try {
+      const expected = readTerminalDeliveryReceipt(input.cwd, activeSessionTask(input.cwd, input.sessionId));
+      const entries = input.entries(), pair = receiptPairs(entries, expected, false).find((candidate) =>
+        candidate.correlation.operationRef === input.operationRef
+        && candidate.correlation.messageRequestId === input.messageRequestId && candidate.request === input.request);
+      if (!pair || pair.receiptEntry !== entries.at(-1) || !matchesReceipt(message, pair.receipt)) return undefined;
+      const before = input.persistedEntries();
+      const disk = receiptPairs(before, expected, false).find((candidate) => candidate.receiptEntry.id === pair.receiptEntry.id);
+      if (!disk || disk.receiptEntry !== before.at(-1) || !isDeepStrictEqual(pair.requestEntry, disk.requestEntry)
+        || !isDeepStrictEqual(pair.receiptEntry, disk.receiptEntry)) return undefined;
+      input.appendCustomEntry(TERMINAL_DELIVERY_CONFIRMATION_TYPE, confirmationData(pair));
+      const current = input.entries(), persisted = input.persistedEntries();
+      return terminalDeliveryPairs(current, expected, persisted).some((candidate) => candidate.receiptEntry.id === pair.receiptEntry.id
+        && candidate.confirmationEntry === current.at(-1) && candidate.confirmationEntry.id === (persisted.at(-1) as any)?.id)
+        ? pair.receipt : undefined;
+    } catch { return undefined; }
+  };
+}

package/packages/piagent-webui/server/transcript-projection.ts

@@ -1,13 +1,22 @@
 import { createHash } from "node:crypto";
 
 import { redactSensitiveText } from "../../piagent-core/extensions/redaction-core.js";
+import { looksLikeCompletionClaim } from "../../piagent-core/runtime/session/completion-signals.ts";
+import { isLightweightNonAuthorizingChangeLanguage } from "../../piagent-core/runtime/workflows/change-clarification.ts";
+import { workflowCommandPattern } from "../../piagent-core/runtime/workflows/webui-workflow.ts";
 import { hasVisibleText } from "../shared/text-visibility.ts";
+import { WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE, webUiMessageCorrelationEntry,
+  type WebUiMessageCorrelation } from "../shared/message-correlation.ts";
+import { terminalDeliveryPairs, type TerminalDeliveryPair, type TerminalDeliveryReceipt } from "./terminal-delivery-receipt.ts";
 
 const MAX_ENTRIES = 50_000;
 const MAX_ITEMS = 200;
 const MAX_TEXT = 16_384;
 const ANSI = /\u001b(?:\[[0-?]*[ -/]*[@-~]|[@-_])/g;
 const COMPLETION_GATE = /^\[Piagent completion gate: (CONTINUING|NOT APPROVED)\]/i;
+const INTERNAL_FRESH_TRANSITION = new RegExp(
+  `^\\/fresh\\s+(?:${workflowCommandPattern({ aliases: false })})\\s+(?:--session-title\\s+"[^"\\r\\n]{1,64}"\\s+)?Read task intake from \\.pi\\/task-inbox\\/[A-Za-z0-9._-]+\\.md\\.\\s+Current session is near context limits; use a fresh governed session\\.$`, "u"
+);
 
 type TranscriptIdentity = { projectRef: string; runtimeInstanceId: string; sessionRef: string; taskId: string | null; taskRunId: string | null;
   agentOperationId: null; toolCallId: null };
@@ -16,8 +25,8 @@ type TranscriptRevision = { runtimeRevision: string; taskRevision: string | null
 type TranscriptContent = { state: "available" | "redacted" | "unavailable"; text: string | null; textChars: number | null; digest: string | null;
   truncated: boolean; redacted: boolean; imageCount: number; reasonCode: string | null };
 type TranscriptAttachment = { displayName: string; kind: "file" | "image" | "document"; mimeType: string; truncated: boolean };
-type TranscriptItem = { messageRef: string; parentMessageRef: string | null; role: "user" | "assistant" | "tool-result"; recordedAt: string;
-  agentOperationId: string | null; turnIndex: number | null; content: TranscriptContent;
+type TranscriptItem = { messageRef: string; parentMessageRef: string | null; role: "user" | "assistant" | "tool-result" | "custom"; recordedAt: string;
+  agentOperationId: string | null; messageRequestId?: string; turnIndex: number | null; content: TranscriptContent;
   attachments?: TranscriptAttachment[];
   toolCalls: Array<{ toolCallRef: string; toolName: string; state: "requested" | "completed" | "failed" | "unknown" }> };
 export type TranscriptDocument = { schemaVersion: 1; version: "piagent-webui-transcript-v1"; generatedAt: string; identity: TranscriptIdentity;
@@ -33,6 +42,8 @@ export type TranscriptProjectionInput = {
   limit?: number;
   generatedAt?: string;
   taskOutcome?: string | null;
+  terminalDeliveryReceipt?: TerminalDeliveryReceipt;
+  terminalDeliveryEntries?: unknown[];
 };
 
 function hash(value: string): string { return createHash("sha256").update(value).digest("hex"); }
@@ -135,16 +146,15 @@ function role(message: any): TranscriptItem["role"] | null {
 }
 function isInternalFreshTransition(message: any): boolean {
   if (message?.role !== "user") return false;
-  return /^\/fresh\s+(?:task|scout|be-to-fe)\s+(?:--session-title\s+"[^"\r\n]{1,64}"\s+)?Read task intake from \.pi\/task-inbox\/[A-Za-z0-9._-]+\.md\.\s+Current session is near context limits; use a fresh governed session\.$/u
-    .test(messageText(message).trim());
+  return INTERNAL_FRESH_TRANSITION.test(messageText(message).trim());
 }
 function unavailableContent(reasonCode: string): TranscriptContent {
   return { state: "unavailable", text: null, textChars: null, digest: null, truncated: false, redacted: false, imageCount: 0, reasonCode };
 }
-function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
+function item(entry: any, identity: TranscriptIdentity, customReceipt = false): TranscriptItem | null {
   if (!entry || entry.type !== "message" || !entry.message) return null;
   if (isInternalFreshTransition(entry.message)) return null;
-  const itemRole = role(entry.message), recordedAt = timestamp(entry.timestamp ?? entry.message.timestamp);
+  const itemRole = customReceipt ? "custom" : role(entry.message), recordedAt = timestamp(entry.timestamp ?? entry.message.timestamp);
   if (!itemRole || !recordedAt || typeof entry.id !== "string" || entry.id.length === 0) return null;
   const userProjection = userMessageProjection(entry.message);
   const projectedToolCalls = toolCalls(entry.message, identity.sessionRef, itemRole);
@@ -163,6 +173,41 @@ function item(entry: any, identity: TranscriptIdentity): TranscriptItem | null {
 
 type ProjectedTranscriptItem = { entry: any; item: TranscriptItem; cursor: string };
 
+function correlatedTranscriptItems(entries: unknown[], identity: TranscriptIdentity,
+  receiptPairs: Map<unknown, TerminalDeliveryPair>): ProjectedTranscriptItem[] {
+  let pending: WebUiMessageCorrelation | null = null;
+  let turn: WebUiMessageCorrelation | null = null;
+  const values: ProjectedTranscriptItem[] = [];
+  for (const entry of entries as any[]) {
+    const pair = receiptPairs.get(entry);
+    if (pair) {
+      // Project the admitted request and real custom receipt without writing
+      // fabricated user/assistant messages into Pi's durable model history.
+      for (const [source, itemRole, content] of [[pair.requestEntry, "user", pair.request],
+        [pair.receiptEntry, "custom", pair.receipt.content]] as const) {
+        const projected = item({ ...source, type: "message", message: { role: itemRole, content } }, identity, itemRole === "custom");
+        if (projected) values.push({ entry: source, item: { ...projected, agentOperationId: pair.correlation.operationRef,
+          messageRequestId: pair.correlation.messageRequestId }, cursor: opaque("transcript", [identity.sessionRef, source.id]) });
+      }
+      pending = null; turn = null; continue;
+    }
+    if (entry?.type === "custom" && entry.customType === WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE) {
+      // A newer marker supersedes an older marker that never reached a user
+      // message. Invalid markers fail closed instead of leaking correlation
+      // from an earlier admitted-but-undispatched operation into a later turn.
+      pending = webUiMessageCorrelationEntry(entry);
+      continue;
+    }
+    if (role(entry?.message) === "user") { turn = pending; pending = null; }
+    const projected = item(entry, identity);
+    if (!projected) continue;
+    values.push({ entry, item: turn ? { ...projected, agentOperationId: turn.operationRef,
+      messageRequestId: turn.messageRequestId } : projected,
+    cursor: opaque("transcript", [identity.sessionRef, entry?.id]) });
+  }
+  return values;
+}
+
 function linkTranscriptTurns(values: ProjectedTranscriptItem[]): ProjectedTranscriptItem[] {
   let userMessageRef: string | null = null;
   const toolCallOwners = new Map<string, string>();
@@ -187,15 +232,18 @@ function suppressOpenTaskHandoff(values: ProjectedTranscriptItem[], taskOutcome:
     if (values[index]?.item.role === "user") { latestUser = index; break; }
   }
   if (latestUser < 0) return values;
+  const latestPrompt = values[latestUser]?.item.content.text ?? "";
+  if (isLightweightNonAuthorizingChangeLanguage(latestPrompt)) return values;
   return values.map((value, index) => {
     if (index <= latestUser || value.item.role !== "assistant" || value.item.toolCalls.length > 0
-      || !["available", "redacted"].includes(value.item.content.state)) return value;
+      || !["available", "redacted"].includes(value.item.content.state)
+      || !looksLikeCompletionClaim(value.item.content.text ?? "")) return value;
     return { ...value, item: { ...value.item, content: unavailableContent("assistant-task-pending") } };
   });
 }
 
 function durableAssistant(item: TranscriptItem): boolean {
-  return item.role === "assistant" && item.toolCalls.length === 0
+  return (item.role === "assistant" || item.role === "custom") && item.toolCalls.length === 0
     && (item.content.state === "available" || item.content.state === "redacted")
     && hasVisibleText(item.content.text ?? "");
 }
@@ -252,9 +300,13 @@ function unavailable(input: TranscriptProjectionInput, reasonCode: string, limit
 export function projectTranscript(input: TranscriptProjectionInput): TranscriptDocument {
   const limit = Math.max(1, Math.min(MAX_ITEMS, Number.isInteger(input.limit) ? Number(input.limit) : 50));
   if (!Array.isArray(input.entries) || input.entries.length > MAX_ENTRIES) return unavailable(input, "transcript-history-unavailable", limit);
-  const projected = suppressOpenTaskHandoff(linkTranscriptTurns(input.entries.map((entry) => ({ entry, item: item(entry, input.identity),
-    cursor: opaque("transcript", [input.identity.sessionRef, (entry as any)?.id]) }))
-    .filter((value): value is ProjectedTranscriptItem => Boolean(value.item))), input.taskOutcome);
+  const receipt = input.terminalDeliveryReceipt;
+  const boundReceipt = receipt?.details.taskId === input.identity.taskId && receipt?.details.taskRunId === input.identity.taskRunId
+    && receipt?.details.outcome === input.taskOutcome ? receipt : undefined;
+  const receiptPairs = new Map(terminalDeliveryPairs(input.entries, boundReceipt, input.terminalDeliveryEntries)
+    .map((pair) => [pair.receiptEntry, pair]));
+  const projected = suppressOpenTaskHandoff(linkTranscriptTurns(correlatedTranscriptItems(input.entries, input.identity,
+    receiptPairs)), input.taskOutcome);
   const cursors = projected.map((value) => value.cursor);
   let end = projected.length;
   if (input.beforeCursor) {
@@ -266,5 +318,6 @@ export function projectTranscript(input: TranscriptProjectionInput): TranscriptD
   return { schemaVersion: 1, version: "piagent-webui-transcript-v1", generatedAt: input.generatedAt ?? new Date().toISOString(),
     identity: structuredClone(input.identity), revision: structuredClone(input.revision), eventCursor: input.eventCursor,
     state: "ready", items: selected, page: { beforeCursor: input.beforeCursor ?? null, nextBeforeCursor: hasOlder ? cursors[page.start] : null,
-      hasOlder, limit, truncated: page.compacted || projected.length !== input.entries.filter((entry: any) => entry?.type === "message").length }, reasonCode: null };
+      hasOlder, limit, truncated: page.compacted || projected.length !== input.entries.filter((entry: any) => entry?.type === "message").length
+        + receiptPairs.size * 2 }, reasonCode: null };
 }

package/packages/piagent-webui/shared/message-correlation.ts

@@ -0,0 +1,25 @@
+export const WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE = "piagent-webui-message-correlation";
+
+const OPAQUE_REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+
+export type WebUiMessageCorrelation = {
+  messageRequestId: string;
+  operationRef: string;
+};
+
+/**
+ * A correlation marker is persisted immediately before the host receives the
+ * user prompt. Plain custom entries do not enter model context, but they let a
+ * later transcript projection recover the exact browser request and operation
+ * without trusting browser/server clock alignment or repeated message text.
+ */
+export function webUiMessageCorrelationEntry(entry: unknown): WebUiMessageCorrelation | null {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  const candidate = entry as Record<string, any>;
+  if (candidate.type !== "custom" || candidate.customType !== WEBUI_MESSAGE_CORRELATION_ENTRY_TYPE
+    || !candidate.data || typeof candidate.data !== "object" || Array.isArray(candidate.data)) return null;
+  const data = candidate.data as Record<string, unknown>;
+  if (data.schemaVersion !== 1 || typeof data.messageRequestId !== "string" || !OPAQUE_REF.test(data.messageRequestId)
+    || typeof data.operationRef !== "string" || !OPAQUE_REF.test(data.operationRef)) return null;
+  return { messageRequestId: data.messageRequestId, operationRef: data.operationRef };
+}