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-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("rejects raw client tool tampering when canonical content survives", () => {
     const canonicalCall = {
       type: "tool-call" as const,

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/hosted/chat-preparation.test.ts

@@ -301,6 +301,18 @@ Deno.test("prepareHostedChatRuntimeCreationOptions builds runtime options from r
       version: 1,
       loadedToolNames: ["get_release"],
     },
+    serverResolvedProviderReplayCheckpoints: [{
+      version: 1,
+      messageId: "assistant-message-1",
+      provider: "anthropic",
+      providerBlocks: [{
+        type: "provider-block",
+        provider: "anthropic",
+        block: { type: "thinking", thinking: "", signature: "sig-threading" },
+      }],
+      providerBlockPositions: [0],
+      totalPartCount: 1,
+    }],
     resolveModelId: (modelId) => modelId ? `resolved:${modelId}` : undefined,
     resolveModelThinking: (modelId) => modelId ? { enabled: true, budgetTokens: 1234 } : undefined,
     fetchSteering: (input) => {
@@ -369,6 +381,18 @@ Deno.test("prepareHostedChatRuntimeCreationOptions builds runtime options from r
       version: 1,
       loadedToolNames: ["get_release"],
     },
+    serverResolvedProviderReplayCheckpoints: [{
+      version: 1,
+      messageId: "assistant-message-1",
+      provider: "anthropic",
+      providerBlocks: [{
+        type: "provider-block",
+        provider: "anthropic",
+        block: { type: "thinking", thinking: "", signature: "sig-threading" },
+      }],
+      providerBlockPositions: [0],
+      totalPartCount: 1,
+    }],
     liveProjectSteering: {
       agent: {
         id: "agent-1",

src/agent/hosted/chat-preparation.ts

@@ -40,6 +40,7 @@ import {
 } from "./context-budget-manager.ts";
 import { findSubmittedFormInputResult } from "./form-input-tool.ts";
 import type { ToolExposureCheckpoint } from "../runtime/tool-exposure.ts";
+import type { ProviderReplayCheckpoint } from "../runtime/provider-replay.ts";
 import {
   createToolExposureCheckpointEvent,
   TOOL_SEARCH_TOOL_NAME,
@@ -126,6 +127,8 @@ export type HostedChatRuntimeCreationPreparationInput<TRuntimeAgentDefinition> =
   rootRunContext?: HostedChatRuntimePreparationRootRunContext;
   /** Trusted checkpoint resolved after hosted service authentication. */
   serverResolvedToolExposureCheckpoint?: ToolExposureCheckpoint;
+  /** Verified provider replay state resolved by the authenticated server. */
+  serverResolvedProviderReplayCheckpoints?: readonly ProviderReplayCheckpoint[];
   /** Verified integration tool grant for this run, resolved by the control plane. */
   serverResolvedIntegrationToolNames?: readonly string[];
   /** Service-owned authorization ceiling for Framework host tools. */
@@ -273,6 +276,8 @@ export type HostedChatExecutionPreparationInput<
   contextBudget?: HostedChatContextBudgetOptions;
   /** Trusted checkpoint resolved by the authenticated hosted service. */
   serverResolvedToolExposureCheckpoint?: ToolExposureCheckpoint;
+  /** Verified provider replay state resolved by the authenticated server. */
+  serverResolvedProviderReplayCheckpoints?: readonly ProviderReplayCheckpoint[];
   /** Verified integration tool grant for this run, resolved by the control plane. */
   serverResolvedIntegrationToolNames?: readonly string[];
   /** Service-owned authorization ceiling for Framework host tools. */
@@ -438,6 +443,11 @@ export async function prepareHostedChatRuntimeCreationOptions<
       ...(input.serverResolvedToolExposureCheckpoint
         ? { serverResolvedToolExposureCheckpoint: input.serverResolvedToolExposureCheckpoint }
         : {}),
+      ...(input.serverResolvedProviderReplayCheckpoints?.length
+        ? {
+          serverResolvedProviderReplayCheckpoints: input.serverResolvedProviderReplayCheckpoints,
+        }
+        : {}),
       ...(input.serverResolvedIntegrationToolNames?.length
         ? { serverResolvedIntegrationToolNames: input.serverResolvedIntegrationToolNames }
         : {}),
@@ -555,6 +565,7 @@ export async function prepareHostedChatExecution<
     fetchSteering: input.fetchSteering,
     buildInstructions: input.buildInstructions,
     serverResolvedToolExposureCheckpoint: input.serverResolvedToolExposureCheckpoint,
+    serverResolvedProviderReplayCheckpoints: input.serverResolvedProviderReplayCheckpoints,
     serverResolvedIntegrationToolNames: input.serverResolvedIntegrationToolNames,
     hostToolPolicy: input.hostToolPolicy,
   });

src/agent/hosted/chat-runtime-contract.ts

@@ -9,6 +9,7 @@ import type { AgentRuntimeMessage } from "../runtime/message-adapter.ts";
 import type { ConversationRunEvent } from "../conversation/run-events.ts";
 import type { RuntimeClientProfile } from "../runtime/client-profile.ts";
 import type { ToolExposureCheckpoint } from "../runtime/tool-exposure.ts";
+import type { ProviderReplayCheckpoint } from "../runtime/provider-replay.ts";
 import type { RuntimeSkillDefinition } from "../runtime/skill-metadata.ts";
 import type { ResolvedSkillSelectorPolicy } from "#veryfront/skill/selector.ts";
 
@@ -164,6 +165,8 @@ export type HostedChatRuntimeCreationOptions<TRuntimeAgentDefinition, TThinkingC
   submittedFormInputResult?: HostedSubmittedFormInputResult;
   /** @internal Latest private checkpoint loaded from trusted run state. */
   serverResolvedToolExposureCheckpoint?: ToolExposureCheckpoint;
+  /** @internal Verified provider replay state for persisted assistant turns. */
+  serverResolvedProviderReplayCheckpoints?: readonly ProviderReplayCheckpoint[];
   /** @internal Persists private checkpoint state outside model messages. */
   persistToolExposureCheckpoint?: (
     checkpoint: ToolExposureCheckpoint,

src/agent/hosted/cloud-agent-chat-execution.ts

@@ -68,7 +68,10 @@ import {
   resolveMcpServers,
   setFilteredTraceAttributes,
 } from "./cloud-agent-child-tools.ts";
-import { getServerResolvedToolExposureCheckpoint } from "./runtime-request-config.ts";
+import {
+  getServerResolvedProviderReplayCheckpoints,
+  getServerResolvedToolExposureCheckpoint,
+} from "./runtime-request-config.ts";
 import { resolveHostedRequestPreparationSignal } from "../service/request-preparation-context.ts";
 
 const DEFAULT_FORWARDED_CONFIG_NAMESPACE = "veryfront";
@@ -329,6 +332,10 @@ export async function prepareChatExecutionWithinProjectRuntime(
       req.forwardedProps,
       req.serverEnvelopeVerified === true,
     ),
+    serverResolvedProviderReplayCheckpoints: getServerResolvedProviderReplayCheckpoints(
+      req.forwardedProps,
+      req.serverEnvelopeVerified === true,
+    ),
     // Sourced from the verified run-event token, never from forwardedProps, so
     // it is trusted on the durable-chat path without trusting that body.
     ...(req.serverResolvedIntegrationToolNames?.length

src/agent/hosted/default-chat-runtime.ts

@@ -326,6 +326,7 @@ function createRuntimeAgentConfig(input: {
     __vfAllowedRemoteTools: input.toolAssembly.compatibleRemoteToolNames,
     __vfSourceIntegrationPolicy: input.sourceIntegrationPolicy,
     __vfToolExposureCheckpoint: input.options.serverResolvedToolExposureCheckpoint,
+    __vfProviderReplayCheckpoints: input.options.serverResolvedProviderReplayCheckpoints,
     __vfPersistToolExposureCheckpoint: input.options.persistToolExposureCheckpoint,
     __vfToolExposureCheckpointPersistenceRequired:
       input.options.requireToolExposureCheckpointPersistence === true,