@springbrand/agent-runtime 0.3.0-alpha.16 → 0.3.0-alpha.18

package/src/conversation/harness-stream.ts

@@ -1,7 +1,8 @@
-import type { AgentEvent, Events, HarnessEvent } from "@earendil-works/pi-agent-core";
-import type { OperationResultRecord } from "@earendil-works/pi-agent-core/harness/session";
+import type { AgentEvent as LoopEvent } from "@earendil-works/pi-agent-core";
+import type { AgentEvent, SnapshotEvent } from "@earendil-works/pi-durable";
 import type { AssistantMessage } from "@earendil-works/pi-ai";
 import type { UIMessage, UIMessageChunk } from "ai";
+import type { SessionHarness, SessionRunOutcome } from "../harness/session-harness";
 import { PiChunkEncoder, type ToolInputPreparer } from "./message";
 
 export interface HarnessStreamOptions {
@@ -11,89 +12,103 @@ export interface HarnessStreamOptions {
   readonly userMessageId?: string | null;
   readonly prepareToolInput?: ToolInputPreparer;
 }
-
-/** Project the final Host decision without rewriting Pi's canonical operation result. */
-export function projectSubmissionOutcome(
-  record: OperationResultRecord,
-  submission: { status: string; completedAt?: number | null; error?: string | null },
-): OperationResultRecord {
-  const status = submission.status === "aborted" ? "aborted"
-    : submission.status === "error" ? "failed"
-    : submission.status === "skipped" ? "declined" : "completed";
-  const { error: _previousError, ...result } = record;
-  return {
-    ...result, status, endedAt: submission.completedAt ?? record.endedAt,
-    ...((status === "failed" || status === "aborted") && submission.error
-      ? { error: { code: status, message: submission.error } } : {}),
-  };
+export function projectSubmissionOutcome(record: SessionRunOutcome, submission: { status: string; completedAt?: number | null; error?: string | null }): SessionRunOutcome {
+  const status = submission.status === "aborted" ? "aborted" : submission.status === "error" ? "failed" : submission.status === "skipped" ? "declined" : "completed";
+  return { status, endedAt: submission.completedAt ?? record.endedAt, ...(submission.error ? { error: { code: status, message: submission.error } } : {}) };
 }
 
-/** One projection for both broadcast events and a resumed Pi watch. */
+/** Translates native committed Pi deltas into the browser's AI SDK wire protocol. */
 export class HarnessStreamProjection {
   private readonly encoder: PiChunkEncoder;
-  private terminal: AssistantMessage | undefined;
-
-  constructor(options: HarnessStreamOptions) {
-    this.encoder = new PiChunkEncoder(options);
-  }
-
-  restore(message: UIMessage, streaming: boolean): UIMessageChunk[] {
+  private terminal?: AssistantMessage;
+  private readonly shown = new Map<number, string>();
+  private readonly toolInputStarted = new Set<string>();
+  private readonly toolOutput = new Map<string, string>();
+  constructor(options: HarnessStreamOptions) { this.encoder = new PiChunkEncoder(options); }
+  restore(message: UIMessage, streaming: boolean, snapshot?: SnapshotEvent): UIMessageChunk[] {
+    this.shown.clear();
+    snapshot?.generation?.message?.content.forEach((block, index) => {
+      if (block.type === "text") this.shown.set(index, block.text);
+      if (block.type === "thinking") this.shown.set(index, block.thinking);
+    });
+    for (const tool of snapshot?.tools ?? []) if (tool.output !== undefined) this.toolOutput.set(tool.callId, tool.output);
     return this.encoder.restore(message, streaming);
   }
-
-  event(event: HarnessEvent): UIMessageChunk[] {
+  private block(block: AssistantMessage["content"][number], contentIndex: number, settled = false): UIMessageChunk[] {
+    if (block.type === "toolCall" && (!block.id || !block.name)) return [];
+    if (block.type === "toolCall") {
+      // The encoder keeps the first input it sees, so only a settled message may publish arguments.
+      if (settled) return this.encoder.encode({ type: "tool_execution_start", toolCallId: block.id, toolName: block.name, args: block.arguments } as LoopEvent);
+      if (this.toolInputStarted.has(block.id)) return [];
+      this.toolInputStarted.add(block.id);
+      return [{ type: "tool-input-start", toolCallId: block.id, toolName: block.name, dynamic: true }];
+    }
+    if (block.type !== "text" && block.type !== "thinking") return [];
+    const start = block.type === "thinking"
+      ? this.encoder.encode({ type: "message_update", assistantMessageEvent: { type: "thinking_start", contentIndex } } as LoopEvent)
+      : [];
+    const text = block.type === "text" ? block.text : block.thinking;
+    const previous = this.shown.get(contentIndex) ?? "";
+    const delta = text.startsWith(previous) ? text.slice(previous.length) : text;
+    this.shown.set(contentIndex, text);
+    if (!delta) return start;
+    return [...start, ...this.encoder.encode({ type: "message_update", assistantMessageEvent: { type: block.type === "text" ? "text_delta" : "thinking_delta", contentIndex, delta } } as LoopEvent)];
+  }
+  /**
+   * Pi emits `run_start` only when the live run changes, so a stream bound to a continued run (after an approval or a
+   * slice release) sees tool or message frames first. The encoder's start is idempotent; lead the first frames with it.
+   */
+  private started(chunks: UIMessageChunk[]): UIMessageChunk[] {
+    return chunks.length === 0 ? chunks : [...this.encoder.start(), ...chunks];
+  }
+  event(event: AgentEvent): UIMessageChunk[] { return this.started(this.frames(event)); }
+  private frames(event: AgentEvent): UIMessageChunk[] {
     switch (event.type) {
-      case "run_start":
-      case "run_resume": return this.encoder.start();
-      case "turn_start":
-        this.terminal = undefined;
-        return this.encoder.encode({ type: "turn_start" } as AgentEvent);
-      case "message_update":
-        return event.event.type === "error" ? [] : this.encoder.encode({
-          type: "message_update", message: event.message, assistantMessageEvent: event.event,
-        } as AgentEvent);
-      case "tool_start": return this.encoder.encode({
-        type: "tool_execution_start", toolCallId: event.toolCallId, toolName: event.toolName, args: event.args,
-      } as AgentEvent);
-      case "tool_update": return this.encoder.encode({
-        type: "tool_execution_update", toolCallId: event.toolCallId, toolName: event.toolName, args: {}, partialResult: event.partialResult,
-      } as AgentEvent);
-      case "tool_end": return this.encoder.encode({
-        type: "tool_execution_end", toolCallId: event.toolCallId, toolName: event.toolName, result: event.result, isError: event.isError,
-      } as AgentEvent);
-      case "message_end":
-        if (event.message.role !== "assistant") return [];
-        this.terminal = event.message;
-        return this.encoder.encode({ type: "message_end", message: event.message } as AgentEvent, { terminal: false });
+      case "run_start": return this.encoder.start();
+      case "turn_start": this.terminal = undefined; this.shown.clear(); return this.encoder.encode({ type: "turn_start" } as LoopEvent);
+      case "message_start": return event.message.role === "assistant" ? event.message.content.flatMap((block, index) => this.block(block, index)) : [];
+      case "message_update": return event.changes.flatMap((change) => {
+        if (change.type === "message") return change.message.content.flatMap((block, index) => this.block(block, index));
+        if (change.type === "text_start" || change.type === "thinking_start" || change.type === "block" || change.type === "toolcall_start") return this.block(change.block, change.contentIndex);
+        if (change.type !== "text_delta" && change.type !== "thinking_delta") return [];
+        this.shown.set(change.contentIndex, (this.shown.get(change.contentIndex) ?? "") + change.delta);
+        return this.encoder.encode({ type: "message_update", assistantMessageEvent: change } as LoopEvent);
+      });
+      case "tool_execution_start": return this.encoder.encode(event as LoopEvent);
+      case "tool_execution_update": {
+        let output = this.toolOutput.get(event.toolCallId) ?? "";
+        if (event.output) output = "set" in event.output ? event.output.set : output.slice(event.output.trimStart ?? 0) + (event.output.append ?? "");
+        this.toolOutput.set(event.toolCallId, output);
+        return this.encoder.encode({ type: "tool_execution_update", toolCallId: event.toolCallId, toolName: event.toolName, args: {}, partialResult: { content: [{ type: "text", text: output }], details: event.details } } as LoopEvent);
+      }
+      case "tool_execution_end": {
+        const result = event.entry?.model?.[0];
+        return this.encoder.encode({ type: "tool_execution_end", toolCallId: event.toolCallId, toolName: event.toolName, result: result?.role === "toolResult" ? result : { content: [{ type: "text", text: "Tool execution interrupted" }] }, isError: result?.role !== "toolResult" || result.isError } as LoopEvent);
+      }
+      case "message_end": {
+        const message = event.entry.model?.[0];
+        if (message?.role !== "assistant") return [];
+        this.terminal = message;
+        return [...message.content.flatMap((block, index) => this.block(block, index, true)), ...this.encoder.encode({ type: "message_end", message }, { terminal: false })];
+      }
       default: return [];
     }
   }
-
-  approvalRequested(toolCallId: string, approvalId: string): UIMessageChunk[] {
-    return this.encoder.approvalRequested(toolCallId, approvalId);
-  }
-
-  finish(result: Pick<OperationResultRecord, "status" | "endedAt" | "error">): UIMessageChunk[] {
-    return this.encoder.finish({
-      stopReason: result.status === "aborted" ? "aborted" : result.status === "failed" ? "error" :
-        this.terminal?.stopReason === "length" ? "length" : "stop",
-      timestamp: result.endedAt,
-      ...(result.error?.message ? { errorMessage: result.error.message } : {}),
-    });
+  approvalRequested(toolCallId: string, approvalId: string): UIMessageChunk[] { return this.started(this.encoder.approvalRequested(toolCallId, approvalId)); }
+  finish(result: SessionRunOutcome): UIMessageChunk[] {
+    return this.started(this.encoder.finish({ stopReason: result.status === "aborted" ? "aborted" : result.status === "failed" ? "error" : this.terminal?.stopReason === "length" ? "length" : "stop", timestamp: result.endedAt, ...(result.error ? { errorMessage: result.error.message } : {}) }));
   }
 }
 
-const STREAM_EVENTS = ["run_start", "run_resume", "turn_start", "message_update", "tool_start", "tool_update", "tool_end", "message_end"] as const;
-
-export function bindHarnessStream(
-  events: Events,
-  options: HarnessStreamOptions & { readonly publish: (chunks: readonly UIMessageChunk[]) => Promise<void> },
-) {
+export async function bindHarnessStream(runtime: SessionHarness, options: HarnessStreamOptions & { readonly publish: (chunks: readonly UIMessageChunk[]) => Promise<void> }) {
   const projection = new HarnessStreamProjection(options);
-  const unsubscribers = STREAM_EVENTS.map((type) => events.on(type, (event) => options.publish(projection.event(event))));
+  const watch = await runtime.watch((await import("@earendil-works/chord/context")).BACKGROUND_CONTEXT);
+  let delivery: Promise<void> = Promise.resolve();
+  watch.start((events) => delivery = (async () => { for (const event of events) await options.publish(projection.event(event)); })());
   return {
     publishApprovalRequest: (toolCallId: string, approvalId: string) => options.publish(projection.approvalRequested(toolCallId, approvalId)),
-    flushTerminal: (result: OperationResultRecord) => options.publish(projection.finish(result)),
-    unsubscribe: () => { for (const unsubscribe of unsubscribers) unsubscribe(); },
+    // The Host follows the terminal frame with the canonical transcript, which completes any frame Pi's stop dropped.
+    flushTerminal: async (result: SessionRunOutcome) => { await watch.stop(); await delivery; await options.publish(projection.finish(result)); },
+    unsubscribe: async () => { await watch.stop(); await delivery; },
   };
 }

package/src/conversation/history.ts

@@ -1,8 +1,7 @@
-import type {
-  AgentMessage,
-  Entry,
-  LaneSnapshot,
-} from "@earendil-works/pi-agent-core";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { createSession, type EntryId, type EntryRecord, type Session, type Storage, type SnapshotEvent } from "@earendil-works/pi-durable";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { projectSessionEntry, type ProjectedSessionEntry as Entry } from "./session-entry";
 import type {
   AssistantMessage,
   JsonValue,
@@ -18,11 +17,31 @@ import {
   type PiToolApprovalView,
   type UIUserSidecar,
 } from "./message";
-import { openPiSessionStorage, type CloudflareSessionStorage } from "../session";
-import {
-  isModelStreamStallMessage,
-  isRecoverableAssistantError,
-} from "../models";
+import { openCloudflareSession, RuntimeConversation } from "../session";
+import { dropLegacyPiTables } from "../session/cloudflare/migration";
+
+/**
+ * Pi Durable 1.1 has no public API that deletes a conversation; `Tx` can only create, fork and retire documents.
+ * Clear therefore deletes every record outside the newly selected conversation from the official SQLite schema
+ * version 1. A different schema version keeps the records rather than guessing at its layout.
+ */
+function deleteConversationsExcept(sql: SqlStorage, keep: number): void {
+  const schema = sql.exec<{ version: number }>("SELECT version FROM durable_schema WHERE singleton=1").toArray()[0]?.version;
+  if (schema !== 1) {
+    console.warn("[conversation-clear:degraded]", `Unsupported Pi Durable SQLite schema ${String(schema)}; previous records kept`);
+    return;
+  }
+  const documents = `SELECT id FROM documents WHERE (scope_kind='conversation' AND owner_id<>?1)
+    OR (scope_kind='task' AND owner_id IN (SELECT id FROM tasks WHERE conversation_id<>?1))`;
+  sql.exec(`DELETE FROM document_revisions WHERE document_id IN (${documents})`, keep);
+  sql.exec(`DELETE FROM record_ids WHERE id IN (${documents}
+    UNION SELECT id FROM submissions WHERE conversation_id<>?1 UNION SELECT id FROM tasks WHERE conversation_id<>?1
+    UNION SELECT id FROM entries WHERE conversation_id<>?1 UNION SELECT id FROM conversations WHERE id<>?1)`, keep);
+  sql.exec(`DELETE FROM documents WHERE id IN (${documents})`, keep);
+  for (const [table, column] of [["submissions", "conversation_id"], ["tasks", "conversation_id"], ["entries", "conversation_id"], ["conversations", "id"]]) {
+    sql.exec(`DELETE FROM ${table} WHERE ${column}<>?`, keep);
+  }
+}
 
 /**
  * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
@@ -204,52 +223,42 @@ function hostText(message: UserMessage | AssistantMessage): string {
  * Pi Session 保存规范分支，Runtime 数据库保存 Submission、审批和用户 sidecar；分开保存可避免把 UI 字段写进模型上下文。
  */
 export class ConversationHistory {
-  private readonly store: CloudflareSessionStorage;
-
-  private modelBranch() {
-    return this.store.branch().filter((entry) =>
-      entry.type !== "message" ||
-      entry.message.role !== "assistant" ||
-      (!isModelStreamStallMessage(entry.message.errorMessage) &&
-        !isRecoverableAssistantError(entry.message))
-    );
-  }
-
-  /** Resolve a browser-stable user ID to the Session entry generated by Harness. */
-  private storedMessageId(id: string): string {
-    const direct = this.store.entry(id);
-    if (direct?.type === "message") return id;
-    const submissionByMessage =
-      this.durability.listSessionEntrySubmissionLinks();
-    return this.store.branch().find((entry) => {
-      if (entry.type !== "message" || entry.message.role !== "user") {
-        return false;
-      }
-      const body = this.durability.readUserSidecar(entry.id);
-      if (body) {
-        const sidecar = JSON.parse(body) as UIUserSidecar & { id?: unknown };
-        if (sidecar.id === id) return true;
-      }
-      const submissionId = submissionByMessage.get(entry.id);
-      return submissionId !== undefined &&
-        this.durability.findSubmissionProjection(submissionId)?.userMessageId ===
-          id;
-    })?.id ?? id;
-  }
-
-  /**
-   * 用当前 Agent 的 SQLite、Runtime 持久化端口和 Pi 模型表创建 Transcript。
-   *
-   * `AgentRuntimeKernel` 每个实例构造时调用一次；`hasActiveTurn` 必须反映当前 Submission 生命周期。
-   *
-   * 官方 Storage 契约由同一 DO SQLite 实现；模型目录用于压缩，活动 Turn 检查阻止并发导入。
-   */
   constructor(
-    storage: DurableObjectStorage,
+    private readonly storage: DurableObjectStorage,
     private readonly durability: PiTranscriptDurability,
     private readonly hasActiveTurn: () => boolean,
-  ) {
-    this.store = openPiSessionStorage(storage);
+  ) {}
+
+  private async withSession<T>(run: (session: Session, store: Storage) => Promise<T>): Promise<T> {
+    const store = await openCloudflareSession(this.storage);
+    const session = createSession(store);
+    try { return await run(session, store); }
+    finally { await session.close(BACKGROUND_CONTEXT); }
+  }
+  private async nativeEntries(maxEntryId?: EntryId): Promise<EntryRecord[]> {
+    return this.withSession(async (session, store) => {
+      const pointer = await session.snapshot(RuntimeConversation, BACKGROUND_CONTEXT);
+      if (!pointer?.id) return [];
+      const entries: EntryRecord[] = [];
+      let cursor;
+      do {
+        const page = await store.scanEntries({ conversationId: pointer.id, ...(maxEntryId !== undefined ? { maxEntryId } : {}), order: "ascending" }, 200, cursor, BACKGROUND_CONTEXT);
+        entries.push(...page.items); cursor = page.next;
+      } while (cursor);
+      return entries;
+    });
+  }
+  private async storedMessageId(id: string): Promise<string> {
+    const links = this.durability.listSessionEntrySubmissionLinks();
+    for (const entry of await this.nativeEntries()) {
+      const key = String(entry.id);
+      if (key === id || (entry.data as { displayId?: string } | undefined)?.displayId === id) return key;
+      const body = this.durability.readUserSidecar(key);
+      if (body && (JSON.parse(body) as { id?: string }).id === id) return key;
+      const owner = links.get(key);
+      if (owner && this.durability.findSubmissionProjection(owner)?.userMessageId === id) return key;
+    }
+    return id;
   }
 
   // #region 规范消息写入
@@ -261,33 +270,39 @@ export class ConversationHistory {
    *
    * sidecar 只随首次成功插入写入，使消息 ID 同时承担幂等键，重复请求不能覆盖原视图。
    */
-  append(
+  async append(
     id: string,
     message: AgentMessage,
-    options: {
-      submissionId?: string;
-      userMessage?: UIMessage & { role: "user" };
-    } = {},
-  ): boolean {
-    const inserted = this.store.appendMessage({
-      id,
-      message,
-      ...(options.submissionId
-        ? { submissionId: options.submissionId }
-        : {}),
-    });
-    if (inserted && options.userMessage) {
-      const sidecar = captureUIUserSidecar(options.userMessage);
-      this.durability.upsertUserSidecar(id, JSON.stringify(sidecar));
-    }
-    return inserted;
+    options: { submissionId?: string; userMessage?: UIMessage & { role: "user" } } = {},
+  ): 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) => {
+      const pointer = await session.snapshot(RuntimeConversation, BACKGROUND_CONTEXT);
+      let conversationId = pointer?.id;
+      if (!conversationId) conversationId = await session.commit(async (tx) => {
+        const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
+        (await tx.doc(RuntimeConversation)).id = conversation.id;
+        return conversation.id;
+      }, BACKGROUND_CONTEXT);
+      await session.commit(async (tx) => {
+        const custom = message.role === "custom";
+        const entry = await tx.appendEntry(conversationId!, {
+          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: [] } : {}) })),
+        });
+        if (options.userMessage) this.durability.upsertUserSidecar(String(entry.id), JSON.stringify({ id: options.userMessage.id, ...captureUIUserSidecar(options.userMessage) }));
+      }, BACKGROUND_CONTEXT);
+      return true;
+    }));
   }
 
   /** Persist a stable marker so browser history can distinguish a user stop from other aborts. */
   appendTurnAbortedMarker(
     submissionId: string,
     timestamp: number,
-  ): boolean {
+  ): Promise<boolean> {
     return this.append(`${submissionId}:turn-aborted`, {
       role: "custom",
       customType: "turn-aborted",
@@ -312,7 +327,7 @@ export class ConversationHistory {
    * 这里只返回 `message` entry；compaction 等 Session entry 由上下文转换阶段处理，不能混入原始消息列表。
    */
   async canonicalMessages(): Promise<AgentMessage[]> {
-    return this.modelBranch().flatMap((entry) =>
+    return (await this.storedEntries()).map(({ entry }) => entry).flatMap((entry) =>
       entry.type === "message" ? [entry.message] : []
     );
   }
@@ -325,10 +340,13 @@ export class ConversationHistory {
    * 同时检查 entry 类型和消息角色，防止其他 Session entry 或助手消息被当作 regenerate 起点。
    */
   async findUserMessage(id: string): Promise<UserMessage | undefined> {
-    const entry = this.store.entry(this.storedMessageId(id));
-    return entry?.type === "message" && entry.message.role === "user"
-      ? entry.message
-      : undefined;
+    const key = await this.storedMessageId(id);
+    if (!Number.isSafeInteger(Number(key)) || Number(key) <= 0) return undefined;
+    return this.withSession(async (_session, store) => {
+      const native = await store.entry(Number(key) as EntryId, BACKGROUND_CONTEXT);
+      const message = native?.entry.model?.[0];
+      return message?.role === "user" ? message : undefined;
+    });
   }
 
   // #endregion
@@ -336,12 +354,12 @@ export class ConversationHistory {
   // #region 分支、压缩与导入
 
   /** Resolve the branch position before the user prompt that will be regenerated. */
-  regenerationTarget(id: string): string | null {
-    const entry = this.store.entry(this.storedMessageId(id));
-    if (entry?.type !== "message" || entry.message.role !== "user") {
-      throw new Error(`Unknown regeneration user message: ${id}`);
-    }
-    return entry.parentId;
+  async regenerationTarget(id: string): Promise<EntryId | null> {
+    const key = await this.storedMessageId(id);
+    const entries = await this.nativeEntries();
+    const index = entries.findIndex((entry) => String(entry.id) === key && entry.model?.[0]?.role === "user");
+    if (index < 0) throw new Error(`Unknown regeneration user message: ${id}`);
+    return entries[index - 1]?.id ?? null;
   }
 
   /**
@@ -353,35 +371,18 @@ export class ConversationHistory {
    *
    * 待确认：当前代码没有拒绝以助手消息开头的历史，而这类消息没有 Submission 关联，会被浏览器投影略过。
    */
-  importSnapshot(snapshot: PiCanonicalTranscriptSnapshot): void {
-    if (this.hasActiveTurn()) {
-      throw new Error("Cannot import messages while a SpringBrand Turn is active");
+  async importSnapshot(snapshot: PiCanonicalTranscriptSnapshot): Promise<void> {
+    if (this.hasActiveTurn()) throw new Error("Cannot import messages while a Turn is active");
+    await this.storage.transaction(async () => {
+    let submissionId: string | undefined;
+    for (const entry of snapshot.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 } } : {}),
+      });
+      if (!inserted) throw new Error(`Session message "${entry.id}" already exists`);
     }
-    this.durability.transaction(() => {
-      let currentSubmissionId: string | undefined;
-      for (const entry of snapshot.entries) {
-        if (entry.message.role === "user") {
-          currentSubmissionId = `import:${entry.id}`;
-        }
-        const appended = this.append(entry.id, entry.message, {
-          submissionId: currentSubmissionId,
-          ...(entry.message.role === "user" && entry.userSidecar
-            ? {
-                userMessage: {
-                  id: entry.id,
-                  role: "user",
-                  parts: [...entry.userSidecar.parts],
-                  ...(entry.userSidecar.metadata === undefined
-                    ? {}
-                    : { metadata: entry.userSidecar.metadata }),
-                } satisfies UIMessage & { role: "user" },
-              }
-            : {}),
-        });
-        if (!appended) {
-          throw new Error(`SpringBrand Session message "${entry.id}" already exists`);
-        }
-      }
     });
   }
 
@@ -390,7 +391,7 @@ export class ConversationHistory {
     throughMessageId: string,
   ): Promise<PiCanonicalTranscriptSnapshot> {
     const stored = await this.storedMessages();
-    const storedId = this.storedMessageId(throughMessageId);
+    const storedId = await this.storedMessageId(throughMessageId);
     let cutoff = stored.findIndex((entry) => entry.id === storedId);
     if (cutoff < 0) {
       const targetSubmissionId = stored.find((entry) => {
@@ -442,8 +443,19 @@ export class ConversationHistory {
    *
    * 两类 Transcript 数据必须一起删除，否则复用消息 ID 时可能重新读到旧附件或 UI 元数据。
    */
-  clear(): void {
-    this.store.clear();
+  async clear(): Promise<void> {
+    await this.storage.transaction(() => this.withSession(async (session) => {
+      const next = await session.commit(async (tx) => {
+        const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
+        (await tx.doc(RuntimeConversation)).id = conversation.id;
+        return conversation.id;
+      }, BACKGROUND_CONTEXT);
+      deleteConversationsExcept(this.storage.sql, next);
+      await dropLegacyPiTables(this.storage, session);
+      // Entry associations name records that no longer exist.
+      this.storage.sql.exec("CREATE TABLE IF NOT EXISTS pi_session_entry_submission (entry_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL)");
+      this.storage.sql.exec("DELETE FROM pi_session_entry_submission");
+    }));
     this.durability.clearUserSidecars();
   }
 
@@ -463,39 +475,17 @@ export class ConversationHistory {
   }
 
   /** Reconnect uses Pi's complete lane view, including uncommitted model/tool progress. */
-  async browserSnapshot(snapshot: LaneSnapshot): Promise<UIMessage[]> {
-    const entries = await this.storedMessages(snapshot.transcript);
-    const operation = snapshot.operation;
-    const streaming = operation?.streamingMessage;
-    const streamingId = streaming ? `streaming:${operation.id}` : undefined;
-    if (streaming && streamingId) {
-      entries.push({
-        id: streamingId,
-        submissionId: operation.id,
-        message: streaming,
-        createdAt: streaming.timestamp,
-      });
-    }
+  async browserSnapshot(snapshot: SnapshotEvent, submissionId: string): Promise<UIMessage[]> {
+    const entries = await this.storedMessages((await this.nativeEntries(snapshot.entries.at(-1)?.id)).map(projectSessionEntry));
+    const streaming = snapshot.generation?.message;
+    const streamingId = streaming ? `streaming:${submissionId}` : undefined;
+    if (streaming && streamingId) entries.push({ id: streamingId, submissionId, message: streaming, createdAt: streaming.timestamp });
     let messages = await this.projectBrowserMessages(entries, streamingId);
-    for (const tool of operation?.runningTools ?? []) {
-      const toolResult = tool.result;
-      if (!toolResult) continue;
-      messages = messages.map((message) => {
-        const metadata = message.metadata as { turnId?: string } | undefined;
-        if (message.role !== "assistant" || metadata?.turnId !== operation?.id) {
-          return message;
-        }
-        return applyPiToolResult(message, {
-          role: "toolResult",
-          toolCallId: tool.toolCallId,
-          toolName: tool.toolName,
-          ...toolResult,
-          content: toolResult.content ?? [],
-          details: toolResult.details as JsonValue | undefined,
-          isError: tool.status === "settled" && tool.isError,
-          timestamp: snapshot.operation!.startedAt,
-        }, { preliminary: tool.status === "running" });
-      });
+    for (const tool of snapshot.tools) {
+      if (tool.output === undefined && tool.details === undefined) continue;
+      messages = messages.map((message) => message.role === "assistant" && (message.metadata as { turnId?: string } | undefined)?.turnId === submissionId
+        ? applyPiToolResult(message, { role: "toolResult", toolCallId: tool.callId, toolName: tool.name, content: tool.output ? [{ type: "text", text: tool.output }] : [], details: tool.details, isError: false, timestamp: streaming?.timestamp ?? 0 }, { preliminary: tool.status !== "done" })
+        : message);
     }
     return messages;
   }
@@ -504,6 +494,10 @@ export class ConversationHistory {
     entries: readonly StoredTranscriptMessage[],
     streamingId?: string,
   ): Promise<UIMessage[]> {
+    const lastAnswer = new Map<string, number>();
+    entries.forEach((entry, index) => {
+      if (entry.submissionId && entry.message.role === "assistant" && entry.message.stopReason !== "aborted") lastAnswer.set(entry.submissionId, index);
+    });
     const result: UIMessage[] = [];
     const seenAssistantSubmissions = new Set<string>();
     const seenUserSubmissions = new Set<string>();
@@ -519,7 +513,7 @@ export class ConversationHistory {
       const submissionId = pendingFailedSubmissionId;
       pendingFailedSubmissionId = undefined;
       const submission = this.durability.findSubmissionProjection(submissionId);
-      if (!submission || (submission.status !== "error" &&
+      if (!submission || (submission.status !== "error" && submission.status !== "aborted" &&
         !(submission.status === "skipped" && submission.error))) return;
       const completedAt = submission.completedAt ?? submission.createdAt;
       result.push({
@@ -537,7 +531,8 @@ export class ConversationHistory {
             0,
             completedAt - submission.createdAt,
           ),
-          turnStatus: "error",
+          turnStatus: submission.status === "aborted" ? "aborted" : "error",
+          ...(submission.status === "aborted" ? { interruptedByUser: true } : {}),
           ...(submission.error
             ? { error: publicAssistantError(submission.error) }
             : {}),
@@ -548,7 +543,9 @@ export class ConversationHistory {
     let activeAssistant:
       | { submissionId: string; index: number }
       | undefined;
-    for (const entry of entries) {
+    for (const [index, entry] of entries.entries()) {
+      // Pi retains interrupted attempts; a later answer replaces them only in the browser.
+      if (entry.submissionId && entry.message.role === "assistant" && entry.message.stopReason === "aborted" && (lastAnswer.get(entry.submissionId) ?? -1) > index) continue;
       if (
         pendingFailedSubmissionId &&
         entry.submissionId !== pendingFailedSubmissionId
@@ -599,6 +596,8 @@ export class ConversationHistory {
         entry.message.role === "custom" &&
         entry.message.customType === "turn-aborted"
       ) {
+        // The marker is this stop's terminal; the no-answer fallback would add a second one.
+        if (pendingFailedSubmissionId === entry.submissionId) pendingFailedSubmissionId = undefined;
         const submission = this.durability.findSubmissionProjection(
           entry.submissionId,
         );
@@ -812,7 +811,7 @@ export class ConversationHistory {
    * UI uses the message event time; Pi entry timestamps describe storage commits.
    */
   async storedMessages(
-    snapshotEntries: readonly Entry[] = this.store.branch(),
+    snapshotEntries?: readonly Entry[],
   ): Promise<StoredTranscriptMessage[]> {
     return (await this.storedEntries(snapshotEntries)).flatMap((stored) => {
       const { entry } = stored;
@@ -828,13 +827,14 @@ export class ConversationHistory {
 
   /** Read every Session entry with its recoverable Submission association. */
   async storedEntries(
-    snapshotEntries: readonly Entry[] = this.store.branch(),
+    snapshotEntries?: readonly Entry[],
   ): Promise<StoredSessionEntry[]> {
+    const projected = snapshotEntries ?? (await this.nativeEntries()).map(projectSessionEntry);
     const submissionByEntry =
       this.durability.listSessionEntrySubmissionLinks();
-    return snapshotEntries.map((entry) => ({
+    return projected.map((entry) => ({
       id: entry.id,
-      submissionId: submissionByEntry.get(entry.id) ?? null,
+      submissionId: submissionByEntry.get(entry.id) ?? entry.submissionId ?? null,
       entry,
       createdAt: entry.timestamp,
     }));

package/src/conversation/message/contract.ts

@@ -1,6 +1,18 @@
 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 PiCanonicalUserInput = UserMessage;
 
 export type UIChatTrigger = "submit-message" | "regenerate-message";