@springbrand/agent-runtime 0.3.0-alpha.21 → 0.3.0-alpha.23

package/dist/canonical-context.js

@@ -0,0 +1,122 @@
+import { z } from "zod";
+const identifier = z.string().min(1);
+const amount = z.number().nonnegative();
+const jsonObject = z.record(z.string(), z.json());
+const providerMetadata = z.record(z.string(), z.record(z.string(), z.json().optional()));
+const text = z.looseObject({
+    type: z.literal("text"), text: z.string(), textSignature: z.string().exactOptional(),
+});
+const thinking = z.looseObject({
+    type: z.literal("thinking"), thinking: z.string(), thinkingSignature: z.string().exactOptional(), redacted: z.boolean().exactOptional(),
+});
+const image = z.looseObject({
+    type: z.literal("image"), data: z.string(), mimeType: identifier,
+});
+const file = z.looseObject({
+    type: z.literal("file"), url: z.string(), mimeType: identifier, filename: z.string().exactOptional(),
+});
+const toolCall = z.looseObject({
+    type: z.literal("toolCall"), id: identifier, name: identifier, arguments: jsonObject,
+    thoughtSignature: z.string().exactOptional(), namespace: z.string().exactOptional(),
+});
+const providerNative = z.looseObject({
+    type: z.literal("providerNative"), api: identifier, block: z.record(z.string(), z.unknown()),
+});
+const usage = z.looseObject({
+    input: amount, output: amount, cacheRead: amount, cacheWrite: amount, totalTokens: amount,
+    cacheWrite1h: amount.exactOptional(), reasoning: amount.exactOptional(),
+    cost: z.looseObject({ input: amount, output: amount, cacheRead: amount, cacheWrite: amount, total: amount }),
+});
+const deferred = z.looseObject({
+    provider: identifier, modelId: identifier, api: identifier, id: identifier,
+    expiresAt: amount.exactOptional(), pollAfterMs: amount.exactOptional(), data: z.json().exactOptional(),
+});
+const diagnostics = z.array(z.looseObject({
+    type: z.string(), timestamp: amount,
+    error: z.looseObject({
+        name: z.string().exactOptional(), message: z.string(), stack: z.string().exactOptional(), code: z.union([z.string(), z.number()]).exactOptional(),
+    }).exactOptional(),
+    details: jsonObject.exactOptional(),
+}));
+const nestedCalls = z.looseObject({
+    calls: z.array(z.looseObject({
+        id: identifier, name: identifier, arguments: jsonObject.exactOptional(), argumentsBytes: amount.exactOptional(),
+        status: z.enum(["ok", "error", "unfinished"]), durationMs: amount.exactOptional(), error: z.string().exactOptional(),
+    })),
+    complete: z.boolean(),
+});
+const protocolResponseSchema = z.looseObject({ output: z.array(z.record(z.string(), z.unknown())) });
+const user = z.looseObject({
+    role: z.literal("user"), content: z.union([z.string(), z.array(z.discriminatedUnion("type", [text, image, file]))]), timestamp: amount,
+});
+const assistant = z.looseObject({
+    role: z.literal("assistant"), content: z.array(z.discriminatedUnion("type", [text, thinking, toolCall, providerNative])),
+    api: identifier, provider: identifier, model: identifier, timestamp: amount, usage,
+    stopReason: z.enum(["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"]),
+    responseModel: z.string().exactOptional(), responseId: z.string().exactOptional(), providerThinkingLevel: z.string().exactOptional(),
+    thinkingLevel: z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]).exactOptional(), diagnostics: diagnostics.exactOptional(),
+    deferred: deferred.exactOptional(), errorMessage: z.string().exactOptional(), rawStopReason: z.string().exactOptional(),
+    endTurn: z.boolean().exactOptional(), durationMs: amount.exactOptional(), protocolResponse: protocolResponseSchema.exactOptional(),
+});
+const toolResult = z.looseObject({
+    role: z.literal("toolResult"), toolCallId: identifier, toolName: identifier,
+    content: z.array(z.discriminatedUnion("type", [text, image])), isError: z.boolean(), timestamp: amount,
+    details: z.json().exactOptional(), usage: usage.exactOptional(), nestedCalls: nestedCalls.exactOptional(), durationMs: amount.exactOptional(),
+});
+const tool = z.looseObject({
+    name: identifier, description: z.string(), parameters: z.record(z.string(), z.unknown()),
+    constrainedSampling: z.union([z.literal(false), z.discriminatedUnion("type", [
+            z.looseObject({ type: z.literal("json_schema"), strict: z.enum(["prefer", "require"]) }),
+            z.looseObject({ type: z.literal("grammar"), variants: z.looseObject({ openai_lark: z.string().exactOptional(), openai_regex: z.string().exactOptional() }) }),
+        ])]).exactOptional(),
+    deferLoading: z.literal(true).exactOptional(),
+});
+const system = z.looseObject({
+    role: z.literal("system"), content: z.union([z.string(), z.array(text)]), timestamp: amount,
+    sections: z.record(z.string(), z.union([z.string(), z.null()])).exactOptional(), toolsAdded: z.array(tool).exactOptional(),
+    toolsRemoved: z.array(z.looseObject({ name: identifier })).exactOptional(),
+});
+const custom = z.looseObject({
+    role: z.literal("custom"), customType: identifier, content: z.array(z.looseObject({ type: z.literal("text"), text: z.string() })).readonly(),
+    display: z.boolean().exactOptional(), timestamp: amount,
+});
+/** Native model history and Runtime extensions share one import/export contract. */
+const messageSchemas = { user, assistant, toolResult, system, custom };
+const { user: userSchema, ...otherMessageSchemas } = messageSchemas;
+export const canonicalMessageSchema = z.discriminatedUnion("role", [userSchema, ...Object.values(otherMessageSchemas)]);
+const userSidecarSchema = z.strictObject({
+    metadata: z.unknown().exactOptional(),
+    parts: z.array(z.discriminatedUnion("type", [
+        z.looseObject({ type: z.literal("text"), text: z.string(), state: z.enum(["streaming", "done"]).exactOptional(), providerMetadata: providerMetadata.exactOptional() }),
+        z.looseObject({ type: z.literal("file"), mediaType: z.string(), url: z.string(), filename: z.string().exactOptional(),
+            providerReference: z.record(z.string(), z.string()).exactOptional(), providerMetadata: providerMetadata.exactOptional() }),
+    ])),
+});
+const entrySchema = z.strictObject({
+    id: identifier, message: canonicalMessageSchema, createdAt: z.number().int().nonnegative().safe(), userSidecar: userSidecarSchema.exactOptional(),
+}).superRefine((entry, context) => {
+    if (entry.userSidecar && entry.message.role !== "user") {
+        context.addIssue({ code: "custom", path: ["userSidecar"], message: "Only user messages can carry a user sidecar" });
+    }
+});
+/** Validate the whole snapshot before any import writes; retain opaque native extension values. */
+const snapshotSchema = z.strictObject({ entries: z.array(entrySchema).readonly() }).superRefine((snapshot, context) => {
+    const seen = new Set();
+    for (const [index, entry] of snapshot.entries.entries()) {
+        if (seen.has(entry.id))
+            context.addIssue({ code: "custom", path: ["entries", index, "id"], message: "Duplicate canonical message ID" });
+        seen.add(entry.id);
+    }
+    const first = snapshot.entries.findIndex(({ message }) => message.role === "user" || message.role === "assistant" || message.role === "toolResult");
+    if (first >= 0 && snapshot.entries[first].message.role !== "user") {
+        context.addIssue({ code: "custom", path: ["entries", first, "message", "role"], message: "Canonical history must begin with a user message" });
+    }
+});
+export const canonicalTranscriptSnapshotSchema = snapshotSchema.superRefine((snapshot, context) => {
+    const json = z.json().safeParse(snapshot);
+    if (!json.success)
+        for (const issue of json.error.issues)
+            context.addIssue({
+                code: "custom", path: issue.path, message: "Canonical history must contain only JSON values",
+            });
+});

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@springbrand/agent-runtime",
-  "version": "0.3.0-alpha.21",
+  "version": "0.3.0-alpha.23",
   "type": "module",
   "files": [
     "src",
-    "!src/**/*.test.ts"
+    "!src/**/*.test.ts",
+    "dist",
+    "scripts"
   ],
   "publishConfig": {
     "access": "public"
@@ -13,14 +15,18 @@
     ".": "./src/index.ts",
     "./adapter/cloudflare": "./src/adapter/cloudflare/index.ts",
     "./contracts": "./src/config/public-contracts.ts",
+    "./canonical-context": {
+      "types": "./dist/canonical-context.d.ts",
+      "import": "./dist/canonical-context.js"
+    },
     "./declared-tool": "./src/tools/adapters/declared.ts",
     "./models": "./src/lib/model-catalog.ts"
   },
   "dependencies": {
-    "@cloudflare/codemode": "0.5.2",
+    "@cloudflare/codemode": "0.5.4",
     "@cloudflare/sandbox": "0.12.4",
     "@cloudflare/shell": "0.4.3",
-    "@cloudflare/think": "0.18.0",
+    "@cloudflare/think": "0.20.2",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@types/lodash-es": "^4.17.12",
@@ -32,11 +38,13 @@
     "@earendil-works/chord": "1.1.0"
   },
   "peerDependencies": {
-    "agents": "^0.23.0",
+    "agents": ">=0.28.1 <0.29.0",
     "ai": "^7.0.0"
   },
   "devDependencies": {
-    "agents": "0.23.0",
-    "ai": "7.0.56"
-  }
+    "agents": "0.28.1",
+    "ai": "7.0.56",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {}
 }

package/scripts/build-canonical-context.mjs

@@ -0,0 +1,38 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+// The public validation entry must work without compiling Runtime implementation
+// or inheriting the publisher workspace's patched Pi type declarations.
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const entry = path.join(root, "src/conversation/canonical-context.ts");
+const program = ts.createProgram([entry, path.join(root, "src/conversation/native-extensions.ts")], {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ES2022,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  strict: true,
+  skipLibCheck: true,
+  declaration: true,
+  noEmitOnError: true,
+  types: [],
+});
+const diagnostics = ts.getPreEmitDiagnostics(program);
+if (diagnostics.length > 0) {
+  throw new Error(ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+    getCanonicalFileName: (name) => name,
+    getCurrentDirectory: () => root,
+    getNewLine: () => "\n",
+  }));
+}
+const output = new Map();
+const result = program.emit(program.getSourceFile(entry), (filename, content) => {
+  output.set(path.basename(filename), content);
+});
+if (result.emitSkipped || !output.has("canonical-context.js") || !output.has("canonical-context.d.ts")) {
+  throw new Error("Canonical context build did not emit its JavaScript and declarations");
+}
+await mkdir(path.join(root, "dist"), { recursive: true });
+for (const [filename, content] of output) {
+  await writeFile(path.join(root, "dist", filename), content);
+}

package/src/adapter/cloudflare/agent.ts

@@ -1316,9 +1316,9 @@ export abstract class AgentRuntimeKernel<
 
   // #region Session 消息与 Submission 公开控制面
 
-  /** Export canonical history through one message for fork/import. */
+  /** Export full canonical history, or through one message for fork/import. */
   async getCanonicalSnapshot(
-    throughMessageId: string,
+    throughMessageId?: string,
   ): Promise<PiCanonicalTranscriptSnapshot> {
     return this.transcript.exportSnapshot(throughMessageId);
   }

package/src/adapter/cloudflare/define-agent.ts

@@ -197,15 +197,13 @@ export interface RuntimeAgentControls {
    */
   getMessages(): Promise<UIMessage[]>;
   /**
-   * 把一组既有消息一次性导入 canonical transcript。
+   * 导出完整 canonical transcript；提供消息 ID 时只导出至该条消息。
    *
    * @remarks
-   * 只供真实 fork 或 import 流程在新 Session 初始化时调用。
-   *
-   * 普通发送必须经过 `submitPrompt`，否则会绕过 admission 和回执状态。
+   * 用于 fork、import，以及初始化重试时核对已导入的完整上下文。
    */
   getCanonicalSnapshot(
-    throughMessageId: string,
+    throughMessageId?: string,
   ): Promise<PiCanonicalTranscriptSnapshot>;
   /** Import a server-authored canonical transcript snapshot into a new Session. */
   addCanonicalSnapshot(snapshot: PiCanonicalTranscriptSnapshot): Promise<void>;
@@ -376,7 +374,7 @@ const TERMINAL_AGENT_TOOL_STATUSES = [
   "interrupted",
 ] as const;
 const AGENT_TOOL_RETENTION_MS = 24 * 60 * 60 * 1_000;
-const STABLE_RUNTIME_KEY_MIGRATION = "agent-runtime:stable-runtime-key-migration-v1";
+export const STABLE_RUNTIME_KEY_MIGRATION = "agent-runtime:stable-runtime-key-migration-v1";
 
 function parseTemporaryAgentLaunch(input: unknown): TemporaryAgentLaunchSelection {
   const record = input != null && typeof input === "object"

package/src/config/public-contracts.ts

@@ -14,6 +14,7 @@ export * from "./profile";
 export * from "./assembly-view";
 export * from "./runtime-config";
 export * from "../conversation/message";
+export * from "../conversation/canonical-context";
 export * from "../submission/contracts";
 export * from "../conversation/state";
 export * from "../lib/execution-level";

package/src/conversation/canonical-context.ts

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { UIMessage } from "ai";
+import type { UIUserSidecar } from "./message/user-sidecar";
+import type {
+  AssistantMessage, DeferredHandle, FileContent, ImageContent, NestedToolCallRecord,
+  NestedToolCalls, ProviderNativeContent, SystemMessage, TextContent, ThinkingContent,
+  Tool, ToolCall, ToolReference, ToolResultMessage, Usage, UserMessage,
+} from "@earendil-works/pi-ai";
+
+/** Every upstream field, including optional fields, must have a validator. */
+type NativeShape<T> = { [Key in keyof T]-?: z.ZodType<T[Key]> };
+
+const identifier = z.string().min(1);
+const amount = z.number().nonnegative();
+const jsonObject = z.record(z.string(), z.json());
+const providerMetadata = z.record(z.string(), z.record(z.string(), z.json().optional()));
+
+const text = z.looseObject({
+  type: z.literal("text"), text: z.string(), textSignature: z.string().exactOptional(),
+} satisfies NativeShape<TextContent>);
+const thinking = z.looseObject({
+  type: z.literal("thinking"), thinking: z.string(), thinkingSignature: z.string().exactOptional(), redacted: z.boolean().exactOptional(),
+} satisfies NativeShape<ThinkingContent>);
+const image = z.looseObject({
+  type: z.literal("image"), data: z.string(), mimeType: identifier,
+} satisfies NativeShape<ImageContent>);
+const file = z.looseObject({
+  type: z.literal("file"), url: z.string(), mimeType: identifier, filename: z.string().exactOptional(),
+} satisfies NativeShape<FileContent>);
+const toolCall = z.looseObject({
+  type: z.literal("toolCall"), id: identifier, name: identifier, arguments: jsonObject,
+  thoughtSignature: z.string().exactOptional(), namespace: z.string().exactOptional(),
+} satisfies NativeShape<ToolCall>);
+const providerNative = z.looseObject({
+  type: z.literal("providerNative"), api: identifier, block: z.record(z.string(), z.unknown()),
+} satisfies NativeShape<ProviderNativeContent>);
+const usage = z.looseObject({
+  input: amount, output: amount, cacheRead: amount, cacheWrite: amount, totalTokens: amount,
+  cacheWrite1h: amount.exactOptional(), reasoning: amount.exactOptional(),
+  cost: z.looseObject({ input: amount, output: amount, cacheRead: amount, cacheWrite: amount, total: amount } satisfies NativeShape<Usage["cost"]>),
+} satisfies NativeShape<Usage>);
+const deferred = z.looseObject({
+  provider: identifier, modelId: identifier, api: identifier, id: identifier,
+  expiresAt: amount.exactOptional(), pollAfterMs: amount.exactOptional(), data: z.json().exactOptional(),
+} satisfies NativeShape<DeferredHandle>);
+const diagnostics = z.array(z.looseObject({
+  type: z.string(), timestamp: amount,
+  error: z.looseObject({
+    name: z.string().exactOptional(), message: z.string(), stack: z.string().exactOptional(), code: z.union([z.string(), z.number()]).exactOptional(),
+  } satisfies NativeShape<NonNullable<NonNullable<AssistantMessage["diagnostics"]>[number]["error"]>>).exactOptional(),
+  details: jsonObject.exactOptional(),
+} satisfies NativeShape<NonNullable<AssistantMessage["diagnostics"]>[number]>));
+const nestedCalls = z.looseObject({
+  calls: z.array(z.looseObject({
+    id: identifier, name: identifier, arguments: jsonObject.exactOptional(), argumentsBytes: amount.exactOptional(),
+    status: z.enum(["ok", "error", "unfinished"]), durationMs: amount.exactOptional(), error: z.string().exactOptional(),
+  } satisfies NativeShape<NestedToolCallRecord>)),
+  complete: z.boolean(),
+} satisfies NativeShape<NestedToolCalls>);
+
+const protocolResponseSchema = z.looseObject({ output: z.array(z.record(z.string(), z.unknown())) });
+export type ModelProtocolResponse = z.output<typeof protocolResponseSchema>;
+
+const user = z.looseObject({
+  role: z.literal("user"), content: z.union([z.string(), z.array(z.discriminatedUnion("type", [text, image, file]))]), timestamp: amount,
+} satisfies NativeShape<UserMessage>);
+const assistant = z.looseObject({
+  role: z.literal("assistant"), content: z.array(z.discriminatedUnion("type", [text, thinking, toolCall, providerNative])),
+  api: identifier, provider: identifier, model: identifier, timestamp: amount, usage,
+  stopReason: z.enum(["pending", "stop", "length", "toolUse", "error", "aborted", "deferred"]),
+  responseModel: z.string().exactOptional(), responseId: z.string().exactOptional(), providerThinkingLevel: z.string().exactOptional(),
+  thinkingLevel: z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]).exactOptional(), diagnostics: diagnostics.exactOptional(),
+  deferred: deferred.exactOptional(), errorMessage: z.string().exactOptional(), rawStopReason: z.string().exactOptional(),
+  endTurn: z.boolean().exactOptional(), durationMs: amount.exactOptional(), protocolResponse: protocolResponseSchema.exactOptional(),
+} satisfies NativeShape<AssistantMessage>);
+const toolResult = z.looseObject({
+  role: z.literal("toolResult"), toolCallId: identifier, toolName: identifier,
+  content: z.array(z.discriminatedUnion("type", [text, image])), isError: z.boolean(), timestamp: amount,
+  details: z.json().exactOptional(), usage: usage.exactOptional(), nestedCalls: nestedCalls.exactOptional(), durationMs: amount.exactOptional(),
+} satisfies NativeShape<ToolResultMessage>);
+const tool = z.looseObject({
+  name: identifier, description: z.string(), parameters: z.record(z.string(), z.unknown()),
+  constrainedSampling: z.union([z.literal(false), z.discriminatedUnion("type", [
+    z.looseObject({ type: z.literal("json_schema"), strict: z.enum(["prefer", "require"]) }),
+    z.looseObject({ type: z.literal("grammar"), variants: z.looseObject({ openai_lark: z.string().exactOptional(), openai_regex: z.string().exactOptional() }) }),
+  ])]).exactOptional(),
+  deferLoading: z.literal(true).exactOptional(),
+} satisfies NativeShape<Tool>);
+const system = z.looseObject({
+  role: z.literal("system"), content: z.union([z.string(), z.array(text)]), timestamp: amount,
+  sections: z.record(z.string(), z.union([z.string(), z.null()])).exactOptional(), toolsAdded: z.array(tool).exactOptional(),
+  toolsRemoved: z.array(z.looseObject({ name: identifier } satisfies NativeShape<ToolReference>)).exactOptional(),
+} satisfies NativeShape<SystemMessage>);
+const custom = z.looseObject({
+  role: z.literal("custom"), customType: identifier, content: z.array(z.looseObject({ type: z.literal("text"), text: z.string() })).readonly(),
+  display: z.boolean().exactOptional(), timestamp: amount,
+});
+export type RuntimeCustomMessage = z.output<typeof custom>;
+
+/** Native model history and Runtime extensions share one import/export contract. */
+const messageSchemas = { user, assistant, toolResult, system, custom } satisfies {
+  [Role in AgentMessage["role"]]: z.ZodType<Extract<AgentMessage, { role: Role }>>;
+};
+const { user: userSchema, ...otherMessageSchemas } = messageSchemas;
+export const canonicalMessageSchema = z.discriminatedUnion("role", [userSchema, ...Object.values(otherMessageSchemas)]);
+
+const userSidecarSchema = z.strictObject({
+  metadata: z.unknown().exactOptional(),
+  parts: z.array(z.discriminatedUnion("type", [
+    z.looseObject({ type: z.literal("text"), text: z.string(), state: z.enum(["streaming", "done"]).exactOptional(), providerMetadata: providerMetadata.exactOptional() } satisfies NativeShape<Extract<UIMessage["parts"][number], { type: "text" }>>),
+    z.looseObject({ type: z.literal("file"), mediaType: z.string(), url: z.string(), filename: z.string().exactOptional(),
+      providerReference: z.record(z.string(), z.string()).exactOptional(), providerMetadata: providerMetadata.exactOptional() } satisfies NativeShape<Extract<UIMessage["parts"][number], { type: "file" }>>),
+  ])),
+} satisfies NativeShape<UIUserSidecar>);
+
+const entrySchema = z.strictObject({
+  id: identifier, message: canonicalMessageSchema, createdAt: z.number().int().nonnegative().safe(), userSidecar: userSidecarSchema.exactOptional(),
+}).superRefine((entry, context) => {
+  if (entry.userSidecar && entry.message.role !== "user") {
+    context.addIssue({ code: "custom", path: ["userSidecar"], message: "Only user messages can carry a user sidecar" });
+  }
+});
+export type PiCanonicalTranscriptSnapshotEntry = z.output<typeof entrySchema>;
+
+/** Validate the whole snapshot before any import writes; retain opaque native extension values. */
+const snapshotSchema = z.strictObject({ entries: z.array(entrySchema).readonly() }).superRefine((snapshot, context) => {
+  const seen = new Set<string>();
+  for (const [index, entry] of snapshot.entries.entries()) {
+    if (seen.has(entry.id)) context.addIssue({ code: "custom", path: ["entries", index, "id"], message: "Duplicate canonical message ID" });
+    seen.add(entry.id);
+  }
+  const first = snapshot.entries.findIndex(({ message }) => message.role === "user" || message.role === "assistant" || message.role === "toolResult");
+  if (first >= 0 && snapshot.entries[first]!.message.role !== "user") {
+    context.addIssue({ code: "custom", path: ["entries", first, "message", "role"], message: "Canonical history must begin with a user message" });
+  }
+});
+export const canonicalTranscriptSnapshotSchema = snapshotSchema.superRefine((snapshot, context) => {
+  const json = z.json().safeParse(snapshot);
+  if (!json.success) for (const issue of json.error.issues) context.addIssue({
+    code: "custom", path: issue.path, message: "Canonical history must contain only JSON values",
+  });
+});
+export type PiCanonicalTranscriptSnapshot = z.output<typeof canonicalTranscriptSnapshotSchema>;

package/src/conversation/history.ts

@@ -11,7 +11,6 @@ import type {
 import type { UIMessage } from "ai";
 import {
   applyPiToolResult,
-  captureUIUserSidecar,
   piAssistantToUIMessage,
   publicAssistantError,
   type PiToolApprovalView,
@@ -19,6 +18,8 @@ import {
 } from "./message";
 import { openCloudflareSession, RuntimeConversation } from "../session";
 import { dropLegacyPiTables } from "../session/cloudflare/migration";
+import { canonicalTranscriptSnapshotSchema, type PiCanonicalTranscriptSnapshot } from "./canonical-context";
+export type { PiCanonicalTranscriptSnapshot, PiCanonicalTranscriptSnapshotEntry } from "./canonical-context";
 
 /**
  * Pi Durable 1.1 has no public API that deletes a conversation; `Tx` can only create, fork and retire documents.
@@ -138,17 +139,6 @@ export interface StoredSessionEntry {
   createdAt: number;
 }
 
-export interface PiCanonicalTranscriptSnapshotEntry {
-  readonly id: string;
-  readonly message: AgentMessage;
-  readonly createdAt: number;
-  readonly userSidecar?: UIUserSidecar;
-}
-
-export interface PiCanonicalTranscriptSnapshot {
-  readonly entries: readonly PiCanonicalTranscriptSnapshotEntry[];
-}
-
 // #endregion
 
 // #region 浏览器与 Host 投影辅助函数
@@ -273,7 +263,7 @@ export class ConversationHistory {
   async append(
     id: string,
     message: AgentMessage,
-    options: { submissionId?: string; userMessage?: UIMessage & { role: "user" } } = {},
+    options: { submissionId?: string; userSidecar?: UIUserSidecar & { readonly id: string }; createdAt?: number } = {},
   ): Promise<boolean> {
     if ((await this.nativeEntries()).some((entry) => (entry.data as { displayId?: string } | undefined)?.displayId === id)) return false;
     return this.storage.transaction(() => this.withSession(async (session) => {
@@ -290,9 +280,9 @@ export class ConversationHistory {
           kind: custom ? "springbrand.custom" : message.role === "toolResult" ? "pi.tool-result" : `pi.${message.role}`,
           // Custom messages reach the model as user context, as Pi's convertToLlm did before the native harness.
           model: [custom ? { role: "user", content: [...message.content], timestamp: message.timestamp } : message],
-          data: JSON.parse(JSON.stringify({ displayId: id, createdAt: message.timestamp, ...(custom ? { message } : {}), ...(options.submissionId ? { submissionId: options.submissionId } : {}), ...(message.role === "toolResult" ? { diagnostics: [] } : {}) })),
+          data: JSON.parse(JSON.stringify({ displayId: id, createdAt: options.createdAt ?? message.timestamp, ...(custom ? { message } : {}), ...(options.submissionId ? { submissionId: options.submissionId } : {}), ...(message.role === "toolResult" ? { diagnostics: [] } : {}) })),
         });
-        if (options.userMessage) this.durability.upsertUserSidecar(String(entry.id), JSON.stringify({ id: options.userMessage.id, ...captureUIUserSidecar(options.userMessage) }));
+        if (options.userSidecar) this.durability.upsertUserSidecar(String(entry.id), JSON.stringify(options.userSidecar));
       }, BACKGROUND_CONTEXT);
       return true;
     }));
@@ -369,53 +359,58 @@ export class ConversationHistory {
    *
    * 整批写入使用同一个同步事务，用户消息用 import ID 开启投影分组，后续助手步骤沿用该分组并保留首条用户 sidecar。
    *
-   * 待确认：当前代码没有拒绝以助手消息开头的历史，而这类消息没有 Submission 关联，会被浏览器投影略过。
+   * 同一公开契约在事务前校验完整快照，非法消息不会留下任何持久化记录。
    */
   async importSnapshot(snapshot: PiCanonicalTranscriptSnapshot): Promise<void> {
     if (this.hasActiveTurn()) throw new Error("Cannot import messages while a Turn is active");
+    const validated = canonicalTranscriptSnapshotSchema.parse(snapshot);
     await this.storage.transaction(async () => {
     let submissionId: string | undefined;
-    for (const entry of snapshot.entries) {
+    for (const entry of validated.entries) {
       if (entry.message.role === "user") submissionId = `import:${entry.id}`;
       const inserted = await this.append(entry.id, entry.message, {
-        submissionId,
-        ...(entry.message.role === "user" && entry.userSidecar ? { userMessage: { id: entry.id, role: "user" as const, parts: [...entry.userSidecar.parts], metadata: entry.userSidecar.metadata } } : {}),
+        submissionId, createdAt: entry.createdAt,
+        ...(entry.userSidecar ? { userSidecar: { ...entry.userSidecar, id: entry.id } } : {}),
       });
       if (!inserted) throw new Error(`Session message "${entry.id}" already exists`);
     }
     });
   }
 
-  /** Export canonical entries through one browser-visible message identity. */
+  /** Export the full canonical history, or entries through one browser-visible message identity. */
   async exportSnapshot(
-    throughMessageId: string,
+    throughMessageId?: string,
   ): Promise<PiCanonicalTranscriptSnapshot> {
     const stored = await this.storedMessages();
-    const storedId = await this.storedMessageId(throughMessageId);
-    let cutoff = stored.findIndex((entry) => entry.id === storedId);
-    if (cutoff < 0) {
-      const targetSubmissionId = stored.find((entry) => {
-        if (!entry.submissionId) return false;
-        const submission = this.durability.findSubmissionProjection(
-          entry.submissionId,
-        );
-        return submission?.assistantMessageId === throughMessageId ||
-          submission?.userMessageId === throughMessageId;
-      })?.submissionId;
-      if (targetSubmissionId) {
-        for (let index = stored.length - 1; index >= 0; index -= 1) {
-          if (stored[index]?.submissionId === targetSubmissionId) {
-            cutoff = index;
-            break;
+    let selected = stored;
+    if (throughMessageId !== undefined) {
+      const storedId = await this.storedMessageId(throughMessageId);
+      let cutoff = stored.findIndex((entry) => entry.id === storedId);
+      if (cutoff < 0) {
+        const targetSubmissionId = stored.find((entry) => {
+          if (!entry.submissionId) return false;
+          const submission = this.durability.findSubmissionProjection(
+            entry.submissionId,
+          );
+          return submission?.assistantMessageId === throughMessageId ||
+            submission?.userMessageId === throughMessageId;
+        })?.submissionId;
+        if (targetSubmissionId) {
+          for (let index = stored.length - 1; index >= 0; index -= 1) {
+            if (stored[index]?.submissionId === targetSubmissionId) {
+              cutoff = index;
+              break;
+            }
           }
         }
       }
+      if (cutoff < 0) {
+        throw new Error(`message "${throughMessageId}" not found`);
+      }
+      selected = stored.slice(0, cutoff + 1);
     }
-    if (cutoff < 0) {
-      throw new Error(`message "${throughMessageId}" not found`);
-    }
-    return {
-      entries: stored.slice(0, cutoff + 1).map((entry) => {
+    return canonicalTranscriptSnapshotSchema.parse({
+      entries: selected.map((entry) => {
         if (entry.message.role !== "user") {
           return {
             id: entry.id,
@@ -424,16 +419,17 @@ export class ConversationHistory {
           };
         }
         const body = this.durability.readUserSidecar(entry.id);
+        const sidecar = body ? JSON.parse(body) as UIUserSidecar & { id: string } : undefined;
         return {
           id: entry.id,
           message: entry.message,
           createdAt: entry.createdAt,
-          ...(body
-            ? { userSidecar: JSON.parse(body) as UIUserSidecar }
+          ...(sidecar
+            ? { userSidecar: { parts: sidecar.parts, ...(sidecar.metadata === undefined ? {} : { metadata: sidecar.metadata }) } }
             : {}),
         };
       }),
-    };
+    });
   }
 
   /**

package/src/conversation/message/contract.ts

@@ -1,17 +1,8 @@
 import type { UIMessage } from "ai";
 import type { UserMessage } from "@earendil-works/pi-ai";
 
-declare module "@earendil-works/pi-agent-core" {
-  interface CustomAgentMessages {
-    springbrand: {
-      role: "custom";
-      customType: string;
-      content: readonly { type: "text"; text: string }[];
-      display?: boolean;
-      timestamp: number;
-    };
-  }
-}
+export type { RuntimeCustomMessage } from "../canonical-context";
+import type {} from "../native-extensions";
 
 export type PiCanonicalUserInput = UserMessage;
 

package/src/conversation/message/conversion.ts

@@ -117,10 +117,8 @@ export function normalizeUIUserInput(
   return uiUserMessageToPi(message, context.join("\n"));
 }
 
-export interface UIUserSidecar {
-  readonly metadata?: unknown;
-  readonly parts: ReadonlyArray<UIMessage["parts"][number]>;
-}
+export type { UIUserSidecar } from "./user-sidecar";
+import type { UIUserSidecar } from "./user-sidecar";
 
 function recordOf(value: unknown): Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value)
@@ -225,7 +223,7 @@ export function captureUIUserSidecar(
 ): UIUserSidecar {
   return {
     ...(message.metadata === undefined ? {} : { metadata: message.metadata }),
-    parts: message.parts.flatMap<UIMessage["parts"][number]>((part) => {
+    parts: message.parts.flatMap<UIUserSidecar["parts"][number]>((part) => {
       if (part.type === "text") return [part];
       if (part.type !== "file") return [];
       const providerMetadata = recordOf(part.providerMetadata);

package/src/conversation/message/user-sidecar.ts

@@ -0,0 +1,7 @@
+import type { UIMessage } from "ai";
+
+/** Browser-only user facts travel with native history without entering model input. */
+export interface UIUserSidecar {
+  readonly metadata?: unknown;
+  readonly parts: ReadonlyArray<Extract<UIMessage["parts"][number], { type: "text" | "file" }>>;
+}

package/src/conversation/native-extensions.ts

@@ -0,0 +1,13 @@
+import type { ModelProtocolResponse, RuntimeCustomMessage } from "./canonical-context";
+
+declare module "@earendil-works/pi-ai" {
+  interface AssistantMessage {
+    protocolResponse?: ModelProtocolResponse;
+  }
+}
+
+declare module "@earendil-works/pi-agent-core" {
+  interface CustomAgentMessages {
+    springbrand: RuntimeCustomMessage;
+  }
+}