feat(agent): define the provider replay checkpoint contract (stage 1 of 4, emission disabled)

docs/guides/errors.md

@@ -819,6 +819,13 @@ Default model has no matching provider credential.
 - **HTTP status:** 400
 - **What to do:** Set the agent's model to a provider you have a key for, or use model: "auto"
 
+### provider-replay-checkpoint-invalid
+
+Provider replay checkpoint is invalid.
+
+- **HTTP status:** 500
+- **What to do:** Verify the trusted source that resolved the run's provider replay checkpoints; do not retry with the same replay state
+
 ## General
 
 Raised anywhere; these are not specific to one subsystem.

extensions/ext-llm-anthropic/src/anthropic-provider.test.ts

@@ -86,6 +86,16 @@ function createSettledLegacyMcpPrompt(toolCallId: string) {
 }
 
 describe("anthropic-provider", () => {
+  it("keeps canonical provider identity when the runtime label is customized", () => {
+    const runtime = createAnthropicModelRuntime(
+      { name: "private-anthropic-gateway" },
+      "claude-sonnet-4-6",
+    );
+
+    assertEquals(runtime.provider, "private-anthropic-gateway");
+    assertEquals(runtime.modelProvider, "anthropic");
+  });
+
   it("creates an Anthropic-compatible language runtime without SDK helpers for generate", async () => {
     let requestedUrl = "";
     let requestedInit: RequestInit | undefined;

extensions/ext-llm-anthropic/src/anthropic-provider.ts

@@ -526,6 +526,7 @@ export function createAnthropicModelRuntime(
 
   return {
     provider: providerName,
+    modelProvider: "anthropic",
     modelId,
     specificationVersion: "v3",
     supportedUrls: {},

extensions/ext-llm-anthropic/src/anthropic-request-builder.test.ts

@@ -2988,6 +2988,73 @@ describe("ext-llm-anthropic/anthropic-request-builder", () => {
     }]);
   });
 
+  it("replays checkpoint-shaped signed thinking blocks byte-exact on the resume turn", () => {
+    // Shape delivered by a provider replay checkpoint (veryfront-issue-inbox#522):
+    // on Opus 4.7+/Sonnet 5/Fable 5 the thinking text comes back empty and the
+    // signature is the only carrier, so the rebuilt turn must echo the raw
+    // blocks unchanged beside the tool_use they accompanied.
+    const rawAssistantContent = [{
+      type: "thinking",
+      thinking: "",
+      signature: "sig-checkpoint-secret",
+    }, {
+      type: "redacted_thinking",
+      data: "redacted-checkpoint-secret",
+    }, {
+      type: "tool_use",
+      id: "local_lookup_2",
+      name: "local_lookup",
+      input: { query: "resume" },
+    }];
+    const prompt = [{
+      role: "user",
+      content: [{ type: "text", text: "Look this up" }],
+    }, {
+      role: "assistant",
+      content: [{
+        type: "reasoning",
+        text: "",
+      }, {
+        type: "tool-call",
+        toolCallId: "local_lookup_2",
+        toolName: "local_lookup",
+        input: { query: "resume" },
+      }],
+      providerMetadata: { anthropic: { rawAssistantMessages: [rawAssistantContent] } },
+    }, {
+      role: "tool",
+      content: [{
+        type: "tool-result",
+        toolCallId: "local_lookup_2",
+        toolName: "local_lookup",
+        output: { type: "json", value: { matches: 2 } },
+      }],
+    }] as unknown as RuntimePromptMessage[];
+
+    const body = buildAnthropicMessagesRequest(
+      "claude-sonnet-4-6",
+      "anthropic",
+      { prompt, maxOutputTokens: 64 },
+      false,
+      createWarningCollector(),
+    );
+
+    assertEquals(body.messages, [{
+      role: "user",
+      content: [{ type: "text", text: "Look this up" }],
+    }, {
+      role: "assistant",
+      content: rawAssistantContent,
+    }, {
+      role: "user",
+      content: [{
+        type: "tool_result",
+        tool_use_id: "local_lookup_2",
+        content: '{"matches":2}',
+      }],
+    }]);
+  });
+
   it("replays hidden signed thinking with canonical assistant content on resume", () => {
     const rawAssistantContent = [{
       type: "thinking",

scripts/lint/ban-chat-antipatterns.ts

@@ -112,7 +112,7 @@ const FILE_SIZE_CEILINGS: Record<string, number> = {
   // reconciliation). Not React components, so this map does not subject them
   // to the antipattern ratchets above — it only pins their size.
   "src/chat/conversation.ts": 557,
-  "src/chat/message-prep.ts": 2016,
+  "src/chat/message-prep.ts": 1823,
   "src/chat/tool-replay-reconciliation.ts": 291,
   "src/chat/message-part-parsing.ts": 264,
   "src/chat/part-field-access.ts": 65,

scripts/test/run-deno-suite.ts

@@ -259,7 +259,9 @@ if (import.meta.main) {
   for (const [index, files] of batches.entries()) {
     if (batches.length > 1) {
       console.log(
-        `[test-suite] ${suite} batch ${index + 1}/${batches.length} (${files.length} files)`,
+        `[test-suite] ${suite} batch ${
+          index + 1
+        }/${batches.length} (${files.length} files)`,
       );
     }
     const status = await new Deno.Command("deno", {

scripts/typecheck/fixtures/chat-message-prep-augmentation.ts

@@ -0,0 +1,19 @@
+// Consumer fixture — documented `veryfront/chat/message-prep` declaration merging.
+//
+// Never executed. It exists so the consumer `tsc --noEmit` gate proves the
+// published options contract remains an augmentable interface for downstream
+// TypeScript consumers.
+import type { PrepareProviderModelMessagesFromUiMessagesOptions } from "veryfront/chat/message-prep";
+
+declare module "veryfront/chat/message-prep" {
+  interface PrepareProviderModelMessagesFromUiMessagesOptions {
+    downstreamTraceId?: string;
+  }
+}
+
+const options: PrepareProviderModelMessagesFromUiMessagesOptions = {
+  downstreamTraceId: "consumer-owned-field",
+};
+
+// The annotation is the proof: augmentation must widen the interface with a string.
+export const upperTraceId: string | undefined = options.downstreamTraceId?.toUpperCase();

scripts/typecheck/tsconfig.consumer.json

@@ -30,6 +30,7 @@
       "veryfront/ui": ["./npm/esm/src/react/components/ui/index.d.ts"],
       "veryfront/ui/icons": ["./npm/esm/src/react/components/ui/icons/index.d.ts"],
       "veryfront/chat": ["./npm/esm/src/chat/index.d.ts"],
+      "veryfront/chat/message-prep": ["./npm/esm/src/chat/message-prep.d.ts"],
       "veryfront/chat/types": ["./npm/esm/src/chat/types.d.ts"],
       "veryfront/chat/uploads": ["./npm/esm/src/chat/upload-handler.d.ts"],
       "veryfront/schedule": ["./npm/esm/src/schedule/index.d.ts"],

src/agent/ag-ui/encoder.test.ts

@@ -1075,4 +1075,56 @@ describe("agent/ag-ui-encoder tool-input lifecycle", () => {
     // emitted it, so a normal tool failure must not emit a second.
     assertEquals(events.map((entry) => entry.event), ["ToolCallResult"]);
   });
+
+  it("never carries reasoning signatures or redacted data into AG-UI payloads", () => {
+    // Signed reasoning blocks are replayed through the private provider replay
+    // channel (veryfront-issue-inbox#522); the AG-UI transcript boundary must
+    // stay signature-free so signed material cannot reach display text.
+    const state = createAgUiEncoderState({ nowMs: null, epochMs: null });
+    const signature = "sig-secret-3c2b1a";
+    const redactedData = "redacted-secret-4d5e6f";
+
+    const events = [
+      ...mapRuntimeStreamEventToAgUiEvents(state, {
+        type: "message-start",
+        messageId: "assistant-signed",
+      }),
+      ...mapRuntimeStreamEventToAgUiEvents(state, {
+        type: "reasoning-start",
+        id: "reasoning-signed",
+      }),
+      ...mapRuntimeStreamEventToAgUiEvents(state, {
+        type: "reasoning-delta",
+        id: "reasoning-signed",
+        delta: "",
+      }),
+      ...mapRuntimeStreamEventToAgUiEvents(state, {
+        type: "reasoning-end",
+        id: "reasoning-signed",
+        signature,
+        redactedData,
+      }),
+    ];
+
+    assertEquals(
+      events.map((entry) => entry.event),
+      ["ReasoningMessageStart", "ReasoningMessageContent", "ReasoningMessageEnd"],
+      "reasoning lifecycle only",
+    );
+    const serialized = JSON.stringify(events);
+    assertEquals(serialized.includes(signature), false, "signature never leaves the runtime");
+    assertEquals(
+      serialized.includes(redactedData),
+      false,
+      "redacted data never leaves the runtime",
+    );
+    assertEquals(
+      events.at(-1),
+      {
+        event: "ReasoningMessageEnd",
+        payload: { messageId: "assistant-signed:reasoning:0" },
+      },
+      "reasoning end carries only its message anchor",
+    );
+  });
 });

src/agent/ag-ui/host-support.test.ts

@@ -7,6 +7,7 @@ import {
 } from "#veryfront/testing/assert.ts";
 import { describe, it } from "#veryfront/testing/bdd.ts";
 import { AG_UI_MAX_REQUEST_BODY_BYTES } from "./request-shared.ts";
+import { DEFAULT_LIMITS } from "#veryfront/security/input-validation/types.ts";
 import {
   createAgUiRunErrorEvent,
   createAgUiSseErrorResponse,
@@ -167,6 +168,89 @@ describe("agent/ag-ui-host-support", () => {
     );
   });
 
+  it("accepts private provider replay state outside the forwarded props budget", async () => {
+    const request = new Request("http://localhost/api/ag-ui", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        messages: [{
+          id: "msg-1",
+          role: "user",
+          parts: [{ type: "text", text: "hello" }],
+        }],
+        forwardedProps: {
+          traceId: "trace-1",
+        },
+        serverResolvedProviderReplayCheckpoints: [{
+          version: 1,
+          messageId: "assistant-message-1",
+          provider: "anthropic",
+          providerBlocks: [{
+            type: "provider-block",
+            provider: "anthropic",
+            block: {
+              type: "thinking",
+              thinking: "x".repeat(220_000),
+              signature: "sig-private-large",
+            },
+          }],
+          providerBlockPositions: [0],
+          totalPartCount: 1,
+        }],
+      }),
+    });
+
+    const parsed = await parseAgUiRequest(request);
+
+    assertEquals(parsed.forwardedProps, { traceId: "trace-1" });
+    assertEquals(
+      Array.isArray(parsed.serverResolvedProviderReplayCheckpoints),
+      true,
+      "large replay payload must not be counted against forwardedProps",
+    );
+  });
+
+  it("rejects public AG-UI provider replay state above the generic request body limit", async () => {
+    const request = new Request("http://localhost/api/ag-ui", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        messages: [{
+          id: "msg-1",
+          role: "user",
+          parts: [{ type: "text", text: "hello" }],
+        }],
+        serverResolvedProviderReplayCheckpoints: [{
+          version: 1,
+          messageId: "assistant-message-1",
+          provider: "anthropic",
+          providerBlocks: [{
+            type: "provider-block",
+            provider: "anthropic",
+            block: {
+              type: "thinking",
+              thinking: "x".repeat(1_049_600),
+              signature: "sig-private-large",
+            },
+          }],
+          providerBlockPositions: [0],
+          totalPartCount: 1,
+        }],
+      }),
+    });
+
+    const result = await parseAgUiRequestOrError(request);
+
+    assertInstanceOf(result, Response);
+    assertEquals(result.status, 413);
+    const body = await result.json();
+    assertEquals(body.error, "Invalid AG-UI request");
+    assertEquals(body.details, [{
+      path: [],
+      message: `Request body exceeds ${DEFAULT_LIMITS.maxBodySize} bytes`,
+    }]);
+  });
+
   it("returns a 400 Response from parseAgUiRequestOrError for malformed JSON bodies", async () => {
     const request = new Request("http://localhost/api/ag-ui", {
       method: "POST",

src/agent/ag-ui/host-support.ts

@@ -106,6 +106,7 @@ export const getAgUiRequestSchema = defineSchema((v) =>
       (value) => value === undefined || isWithinJsonSizeLimit(value, MAX_FORWARDED_PROPS_BYTES),
       { message: "forwardedProps must be less than 192 KB" },
     ),
+    serverResolvedProviderReplayCheckpoints: v.unknown().optional(),
     model: v.string().optional(),
     maxOutputTokens: v.number().int().positive().optional(),
   })

src/agent/hosted/ag-ui-chat-request.ts

@@ -202,6 +202,8 @@ export async function buildParsedHostedAgUiRequest(
     model: chatContext.model,
     allowDelegation: chatContext.allowDelegation,
     forwardedProps: input.agUiInput.forwardedProps,
+    serverResolvedProviderReplayCheckpoints:
+      input.agUiInput.serverResolvedProviderReplayCheckpoints,
     runtimeOverrides: chatContext.runtimeOverrides,
     durableRootRun: undefined,
     persistLatestUserMessageBeforeDurableRun: true,