@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.10

package/src/{pi/runtime-adapter/transcript.ts → conversation/history.ts}

@@ -1,18 +1,14 @@
-import type { SnapshotMessage } from "agents/chat";
 import type {
   AgentMessage,
-  CustomMessage,
+  Entry,
+  LaneSnapshot,
 } from "@earendil-works/pi-agent-core";
 import type {
-  Api,
   AssistantMessage,
-  Model,
-  Models,
   ToolResultMessage,
   UserMessage,
 } from "@earendil-works/pi-ai";
 import type { UIMessage } from "ai";
-import { compactPiContext } from "../assembly";
 import {
   applyPiToolResult,
   captureUIUserSidecar,
@@ -20,15 +16,12 @@ import {
   publicAssistantError,
   type PiToolApprovalView,
   type UIUserSidecar,
-} from "../message";
+} from "./message";
 import { openPiSessionStorage, type CloudflareSessionStorage } from "../session";
-import type { PiCanonicalMessageCommit } from "./execution";
-import type { PiRecoveredToolSettlement } from "./recovery";
-import type { RuntimeModelUsageEvent } from "../../kernel/bindings";
 import {
   isModelStreamStallMessage,
   isRecoverableAssistantError,
-} from "./models";
+} from "../models";
 
 /**
  * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
@@ -43,7 +36,7 @@ import {
  * 定义 Transcript 读写持久层所需的最小能力。
  *
  * @remarks
- * `PiRuntimeAdapter.createTranscript` 接收该端口，`AgentRuntimeKernel` 在构造时用 Runtime 数据库实现它。
+ * `AgentRuntimeKernel` 在构造 `ConversationHistory` 时用 Runtime 数据库实现该端口。
  *
  * 端口只暴露投影和旁路数据所需的操作，避免 Transcript 直接依赖具体 Repository。
  */
@@ -73,11 +66,11 @@ export interface PiTranscriptDurability {
    */
   clearUserSidecars(): void;
   /**
-   * 读取当前消息 ID 到 Submission ID 的关联。
+   * 读取当前 Session entry ID 到 Submission ID 的关联。
    *
-   * `storedMessages` 用它补齐 Pi Session 本身不保存的 Runtime Submission 归属。
+   * `storedEntries` 用它补齐 Pi Session 本身不保存的 Runtime Submission 归属。
    */
-  listMessageSubmissionLinks(): Map<string, string>;
+  listSessionEntrySubmissionLinks(): Map<string, string>;
   /**
    * 读取一个 Submission 的浏览器投影字段。
    *
@@ -85,6 +78,7 @@ export interface PiTranscriptDurability {
    */
   findSubmissionProjection(submissionId: string): {
     assistantMessageId: string;
+    userMessageId?: string | null;
     createdAt: number;
     completedAt?: number | null;
     status?: unknown;
@@ -117,6 +111,13 @@ export interface StoredTranscriptMessage {
   createdAt: number;
 }
 
+export interface StoredSessionEntry {
+  id: string;
+  submissionId: string | null;
+  entry: Entry;
+  createdAt: number;
+}
+
 export interface PiCanonicalTranscriptSnapshotEntry {
   readonly id: string;
   readonly message: AgentMessage;
@@ -140,6 +141,7 @@ function userUIMessage(
   options: {
     id: string;
     createdAt: number;
+    turnId?: string;
     sidecar?: UIUserSidecar;
   },
 ): UIMessage {
@@ -160,12 +162,19 @@ function userUIMessage(
           return [];
           },
         );
+  const sidecarMetadata = options.sidecar?.metadata !== null &&
+      typeof options.sidecar?.metadata === "object" &&
+      !Array.isArray(options.sidecar.metadata)
+    ? options.sidecar.metadata as Record<string, unknown>
+    : {};
   return {
     id: options.id,
     role: "user",
     parts,
-    metadata: options.sidecar?.metadata ?? {
+    metadata: {
       createdAt: message.timestamp || options.createdAt,
+      ...sidecarMetadata,
+      ...(options.turnId ? { turnId: options.turnId } : {}),
     },
   };
 }
@@ -189,11 +198,11 @@ function hostText(message: UserMessage | AssistantMessage): string {
  * 管理一个 Runtime 实例的 Pi 规范 Transcript 及其对外投影。
  *
  * @remarks
- * `PiRuntimeAdapter.createTranscript` 在 `AgentRuntimeKernel` 构造期间创建它，Runtime 随后把所有消息提交、恢复、压缩和历史读取收口到这里。
+ * `AgentRuntimeKernel` 在构造期间创建它，Runtime 随后把消息投影、恢复读取和历史导入导出收口到这里。
  *
  * Pi Session 保存规范分支，Runtime 数据库保存 Submission、审批和用户 sidecar；分开保存可避免把 UI 字段写进模型上下文。
  */
-export class PiRuntimeTranscript {
+export class ConversationHistory {
   private readonly store: CloudflareSessionStorage;
 
   private modelBranch() {
@@ -205,17 +214,38 @@ export class PiRuntimeTranscript {
     );
   }
 
+  /** 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。
    *
-   * `PiRuntimeAdapter.createTranscript` 每个 Runtime Kernel 构造时调用一次；`hasActiveTurn` 必须反映当前 Submission 生命周期。
+   * `AgentRuntimeKernel` 每个实例构造时调用一次；`hasActiveTurn` 必须反映当前 Submission 生命周期。
    *
    * 官方 Storage 契约由同一 DO SQLite 实现；模型目录用于压缩，活动 Turn 检查阻止并发导入。
    */
   constructor(
     storage: DurableObjectStorage,
     private readonly durability: PiTranscriptDurability,
-    private readonly models: Models,
     private readonly hasActiveTurn: () => boolean,
   ) {
     this.store = openPiSessionStorage(storage);
@@ -252,55 +282,7 @@ export class PiRuntimeTranscript {
     return inserted;
   }
 
-  /**
-   * 保存一次 Turn 产生的助手消息或工具结果。
-   *
-   * `commitAdapterMessage` 在执行适配器发出 `commit-turn` 时调用，并传入同一 Submission 内递增的助手序号。
-   *
-   * 工具结果用 toolCallId 去重，助手步骤用 ordinal 区分；这两种 ID 形状还被恢复写入复用，不能单边修改。
-   */
-  commitTurnMessage(
-    submissionId: string,
-    message: AssistantMessage | ToolResultMessage,
-    ordinal: number,
-  ): { id: string; inserted: boolean } {
-    const id = message.role === "toolResult"
-      ? `${submissionId}:tool:${message.toolCallId}`
-      : `${submissionId}:assistant:${ordinal}`;
-    return {
-      id,
-      inserted: this.append(id, message, {
-        submissionId,
-      }),
-    };
-  }
-
-  /**
-   * 把执行适配器发出的规范提交路由到对应写入路径。
-   *
-   * `AgentRuntimeKernel` 的 `onCanonicalMessage` 回调在数据库事务内调用它；用户 steering 使用自带 ID，其余 Turn 消息使用统一生成规则。
-   *
-   * 分流集中在这里可让实时执行和 Transcript 的消息身份规则保持一致。
-   */
-  commitAdapterMessage(
-    submissionId: string,
-    commit: PiCanonicalMessageCommit,
-  ): { id: string; inserted: boolean } {
-    return commit.kind === "append-user"
-      ? {
-          id: commit.id,
-          inserted: this.append(commit.id, commit.message, {
-            submissionId,
-          }),
-        }
-      : this.commitTurnMessage(
-          submissionId,
-          commit.message,
-          commit.ordinal,
-        );
-  }
-
-  /** Stable identity makes terminal recovery replay idempotent. */
+  /** Persist a stable marker so browser history can distinguish a user stop from other aborts. */
   appendTurnAbortedMarker(
     submissionId: string,
     timestamp: number,
@@ -318,55 +300,7 @@ export class PiRuntimeTranscript {
       }],
       display: true,
       timestamp,
-    } satisfies CustomMessage, { submissionId });
-  }
-
-  /**
-   * 把恢复流程重建出的工具终态补写进规范 Transcript。
-   *
-   * `materializeRecoveredToolResults` 在恢复决策补齐 settlement 后调用，并先按原工具调用顺序排序。
-   *
-   * ID 与实时工具结果使用相同的 `submissionId + toolCallId` 形状，因此重复恢复只会命中 `append` 的幂等检查。
-   */
-  appendRecoveredToolSettlement(
-    submissionId: string,
-    settlement: PiRecoveredToolSettlement,
-  ): boolean {
-    return this.append(
-      `${submissionId}:tool:${settlement.message.toolCallId}`,
-      settlement.message,
-      {
-        submissionId,
-      },
-    );
-  }
-
-  /**
-   * 按当前规范分支中工具调用出现的顺序排列恢复结果。
-   *
-   * `materializeRecoveredToolResults` 在批量补写前调用；调用方应使用返回的新数组，不依赖输入数组被修改。
-   *
-   * 顺序从助手消息里的 toolCall ID 推导，避免恢复里程碑的读取顺序改变模型看到的工具结果顺序。
-   */
-  orderRecoveredToolSettlements(
-    settlements: readonly PiRecoveredToolSettlement[],
-  ): PiRecoveredToolSettlement[] {
-    const callOrder = new Map<string, number>();
-    for (const entry of this.store.branch()) {
-      if (entry.type !== "message") continue;
-      const message = entry.message;
-      if (message.role !== "assistant") continue;
-      for (const part of message.content) {
-        if (part.type === "toolCall" && !callOrder.has(part.id)) {
-          callOrder.set(part.id, callOrder.size);
-        }
-      }
-    }
-    return [...settlements].sort(
-      (left, right) =>
-        (callOrder.get(left.message.toolCallId) ?? Number.MAX_SAFE_INTEGER) -
-        (callOrder.get(right.message.toolCallId) ?? Number.MAX_SAFE_INTEGER),
-    );
+    }, { submissionId });
   }
 
   /**
@@ -382,20 +316,6 @@ export class PiRuntimeTranscript {
     );
   }
 
-  /**
-   * 生成可恢复流只需要的消息 ID 与角色快照。
-   *
-   * `executeSubmission` 启动 `runRecoverableChatFiber` 前调用，并把结果写进 Fiber 快照。
-   *
-   * 快照不复制消息正文，正文仍以耐久 Transcript 为准，避免维护第二份完整历史。
-   */
-  async snapshotMessages(): Promise<SnapshotMessage[]> {
-    return (await this.storedMessages()).map((entry) => ({
-      id: entry.id,
-      role: entry.message.role,
-    }));
-  }
-
   /**
    * 按 ID 查找一条规范用户消息。
    *
@@ -404,7 +324,7 @@ export class PiRuntimeTranscript {
    * 同时检查 entry 类型和消息角色，防止其他 Session entry 或助手消息被当作 regenerate 起点。
    */
   async findUserMessage(id: string): Promise<UserMessage | undefined> {
-    const entry = this.store.entry(id);
+    const entry = this.store.entry(this.storedMessageId(id));
     return entry?.type === "message" && entry.message.role === "user"
       ? entry.message
       : undefined;
@@ -414,85 +334,13 @@ export class PiRuntimeTranscript {
 
   // #region 分支、压缩与导入
 
-  /**
-   * 把当前 Pi 分支叶子移动到指定 Session entry。
-   *
-   * regenerate admission 在验证原用户消息后调用，使后续写入从该用户消息继续。
-   *
-   * 这里委托同步 Session 存储辅助函数写入叶子标记，不删除原分支，保留 Pi 的分支结构。
-   */
-  moveLeaf(id: string): void {
-    this.store.moveBranchTip(id);
-  }
-
-  /**
-   * 在 Pi 请求模型前按 Runtime 阈值压缩当前上下文，并把压缩 entry 写回 Session。
-   *
-   * `AgentRuntimeKernel.transformPiContext` 作为 Pi 的 `transformContext` 调用它，并提供本次固定的模型和取消信号。
-   *
-   * 方法先逐条核对调用参数与耐久分支；不一致或压缩不可用时保留原消息，避免把漂移的内存上下文提交成新的规范分支。
-   */
-  async compactContext(
-    messages: AgentMessage[],
-    options: {
-      compactAfterTokens: number;
-      force?: boolean;
-      model: Model<Api>;
-      signal?: AbortSignal;
-      submissionId?: string;
-      onCompactionUsage?: (event: RuntimeModelUsageEvent, didCompact: boolean) => void;
-    },
-  ): Promise<AgentMessage[]> {
-    const branch = this.modelBranch();
-    const current = branch.flatMap((entry) =>
-      entry.type === "message" ? [entry.message] : []
-    );
-    if (
-      current.length !== messages.length ||
-      current.some((message, index) =>
-        JSON.stringify(message) !== JSON.stringify(messages[index])
-      )
-    ) {
-      if (options.force) {
-        throw new Error("Forced context compaction requires canonical messages");
-      }
-      console.warn(
-        "[runtime-compaction:degraded]",
-        JSON.stringify({ reason: "canonical-message-mismatch" }),
-      );
-      return messages;
-    }
-    const result = await compactPiContext({
-      branch,
-      compactAfterTokens: options.compactAfterTokens,
-      force: options.force,
-      models: this.models,
-      model: options.model,
-      signal: options.signal,
-    });
-    if (result.compactionEntry || result.modelUsage) {
-      this.durability.transaction(() => {
-        const eventId = this.store.recordCompaction(result.compactionEntry, result.modelUsage?.usage);
-        if (options.submissionId && options.onCompactionUsage && result.modelUsage) {
-          options.onCompactionUsage({
-            eventId,
-            submissionId: options.submissionId,
-            kind: "compaction",
-            ...result.modelUsage,
-          }, result.didCompact);
-        }
-      });
-    }
-    if (options.force && !result.didCompact) {
-      throw new Error("Forced context compaction did not reduce the model input");
-    }
-    if (result.degraded) {
-      console.warn(
-        "[runtime-compaction:degraded]",
-        JSON.stringify({ reason: "compaction-unavailable" }),
-      );
+  /** 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 result.messages;
+    return entry.parentId;
   }
 
   /**
@@ -541,13 +389,17 @@ export class PiRuntimeTranscript {
     throughMessageId: string,
   ): Promise<PiCanonicalTranscriptSnapshot> {
     const stored = await this.storedMessages();
-    let cutoff = stored.findIndex((entry) => entry.id === throughMessageId);
+    const storedId = this.storedMessageId(throughMessageId);
+    let cutoff = stored.findIndex((entry) => entry.id === storedId);
     if (cutoff < 0) {
-      const targetSubmissionId = stored.find((entry) =>
-        entry.submissionId &&
-        this.durability.findSubmissionProjection(entry.submissionId)
-            ?.assistantMessageId === throughMessageId
-      )?.submissionId;
+      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) {
@@ -606,9 +458,54 @@ export class PiRuntimeTranscript {
    * 多个助手步骤用现有的 `step-start` 保留边界，工具结果回填原 toolCall，避免浏览器维护另一套 Turn 拼装逻辑。
    */
   async browserMessages(): Promise<UIMessage[]> {
+    return this.projectBrowserMessages(await this.storedMessages());
+  }
+
+  /** 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,
+      });
+    }
+    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 ?? [],
+          isError: tool.status === "settled" && tool.isError,
+          timestamp: snapshot.operation!.startedAt,
+        }, { preliminary: tool.status === "running" });
+      });
+    }
+    return messages;
+  }
+
+  private async projectBrowserMessages(
+    entries: readonly StoredTranscriptMessage[],
+    streamingId?: string,
+  ): Promise<UIMessage[]> {
     const result: UIMessage[] = [];
     const seenAssistantSubmissions = new Set<string>();
-    const entries = await this.storedMessages();
+    const seenUserSubmissions = new Set<string>();
+    const userSubmissionByMessageId = new Map<string, string>();
     const assistantSubmissions = new Set(entries.flatMap((entry) =>
       entry.submissionId && entry.message.role === "assistant"
         ? [entry.submissionId]
@@ -620,7 +517,8 @@ export class PiRuntimeTranscript {
       const submissionId = pendingFailedSubmissionId;
       pendingFailedSubmissionId = undefined;
       const submission = this.durability.findSubmissionProjection(submissionId);
-      if (submission?.status !== "error") return;
+      if (!submission || (submission.status !== "error" &&
+        !(submission.status === "skipped" && submission.error))) return;
       const completedAt = submission.completedAt ?? submission.createdAt;
       result.push({
         id: submission.assistantMessageId,
@@ -628,6 +526,9 @@ export class PiRuntimeTranscript {
         parts: [],
         metadata: {
           turnId: submissionId,
+          ...(submission.userMessageId
+            ? { userMessageId: submission.userMessageId }
+            : {}),
           createdAt: submission.createdAt,
           completedAt,
           turnDurationMs: Math.max(
@@ -654,13 +555,33 @@ export class PiRuntimeTranscript {
       }
       if (entry.message.role === "user") {
         const body = this.durability.readUserSidecar(entry.id);
+        const sidecar = body
+          ? JSON.parse(body) as UIUserSidecar & { id?: unknown }
+          : undefined;
+        const submission = entry.submissionId
+          ? this.durability.findSubmissionProjection(entry.submissionId)
+          : null;
+        const alreadySeen = entry.submissionId
+          ? seenUserSubmissions.has(entry.submissionId)
+          : false;
+        const sidecarId = typeof sidecar?.id === "string"
+          ? sidecar.id
+          : undefined;
+        const stableMessageId = sidecarId
+          ? sidecarId
+          : !alreadySeen && submission?.userMessageId
+            ? submission.userMessageId
+            : entry.id;
         result.push(userUIMessage(entry.message, {
-          id: entry.id,
+          id: stableMessageId,
           createdAt: entry.createdAt,
-          sidecar: body
-            ? JSON.parse(body) as UIUserSidecar
-            : undefined,
+          turnId: entry.submissionId ?? undefined,
+          sidecar,
         }));
+        if (entry.submissionId) {
+          seenUserSubmissions.add(entry.submissionId);
+          userSubmissionByMessageId.set(stableMessageId, entry.submissionId);
+        }
         if (
           entry.submissionId &&
           !assistantSubmissions.has(entry.submissionId) &&
@@ -681,11 +602,18 @@ export class PiRuntimeTranscript {
         );
         const index = activeAssistant?.submissionId === entry.submissionId
           ? activeAssistant.index
-          : undefined;
+          : result.findIndex((message) =>
+            message.role === "assistant" &&
+            (message.metadata as { turnId?: string } | undefined)?.turnId ===
+              entry.submissionId
+          );
         const createdAt = submission?.createdAt ?? entry.createdAt;
         const completedAt = submission?.completedAt ?? entry.createdAt;
         const metadata = {
           turnId: entry.submissionId,
+          ...(submission?.userMessageId
+            ? { userMessageId: submission.userMessageId }
+            : {}),
           createdAt,
           completedAt,
           turnDurationMs: Math.max(
@@ -695,7 +623,7 @@ export class PiRuntimeTranscript {
           turnStatus: "aborted",
           interruptedByUser: true,
         };
-        if (index === undefined) {
+        if (index < 0) {
           seenAssistantSubmissions.add(entry.submissionId);
           result.push({
             id: submission?.assistantMessageId ?? entry.id,
@@ -703,7 +631,10 @@ export class PiRuntimeTranscript {
             parts: [],
             metadata,
           });
-          activeAssistant = { submissionId: entry.submissionId, index: result.length - 1 };
+          activeAssistant = {
+            submissionId: entry.submissionId,
+            index: result.length - 1,
+          };
         } else {
           const previous = result[index]!;
           result[index] = {
@@ -713,6 +644,7 @@ export class PiRuntimeTranscript {
               ...metadata,
             },
           };
+          activeAssistant = { submissionId: entry.submissionId, index };
         }
         // A stream may settle after the stop marker. Keep its existing UI identity
         // until the next user message rather than creating a second assistant.
@@ -736,6 +668,9 @@ export class PiRuntimeTranscript {
             : submission?.assistantMessageId ?? entry.id,
           metadata: {
             turnId: entry.submissionId,
+            ...(submission?.userMessageId
+              ? { userMessageId: submission.userMessageId }
+              : {}),
             createdAt: submission?.createdAt ?? entry.createdAt,
             completedAt,
             ...(completedAt === undefined
@@ -752,6 +687,7 @@ export class PiRuntimeTranscript {
               : {}),
           },
           approvals: this.approvalViews(entry.submissionId),
+          state: entry.id === streamingId ? "streaming" : "done",
         });
         if (existingIndex === undefined) {
           activeAssistant = {
@@ -793,6 +729,28 @@ export class PiRuntimeTranscript {
       }
     }
     flushFailedSubmission();
+    for (let index = 0; index < result.length; index += 1) {
+      const message = result[index]!;
+      if (message.role !== "assistant") continue;
+      const metadata = message.metadata as {
+        turnId?: string;
+        turnStatus?: string;
+      } | undefined;
+      if (metadata?.turnStatus !== "aborted" || !metadata.turnId) continue;
+      let lastSteerIndex = index;
+      for (let candidate = index + 1; candidate < result.length; candidate += 1) {
+        const following = result[candidate]!;
+        if (
+          following.role === "user" &&
+          userSubmissionByMessageId.get(following.id) === metadata.turnId
+        ) {
+          lastSteerIndex = candidate;
+        }
+      }
+      if (lastSteerIndex === index) continue;
+      result.splice(index, 1);
+      result.splice(lastSteerIndex, 0, message);
+    }
     return result;
   }
 
@@ -851,20 +809,35 @@ export class PiRuntimeTranscript {
    *
    * UI uses the message event time; Pi entry timestamps describe storage commits.
    */
-  async storedMessages(): Promise<StoredTranscriptMessage[]> {
-    const submissionByMessage =
-      this.durability.listMessageSubmissionLinks();
-    return this.store.branch().flatMap((entry) => {
+  async storedMessages(
+    snapshotEntries: readonly Entry[] = this.store.branch(),
+  ): Promise<StoredTranscriptMessage[]> {
+    return (await this.storedEntries(snapshotEntries)).flatMap((stored) => {
+      const { entry } = stored;
       if (entry.type !== "message") return [];
       return [{
-        id: entry.id,
-        submissionId: submissionByMessage.get(entry.id) ?? null,
+        id: stored.id,
+        submissionId: stored.submissionId,
         message: entry.message,
-        createdAt: entry.message.timestamp,
+        createdAt: stored.createdAt,
       }];
     });
   }
 
+  /** Read every Session entry with its recoverable Submission association. */
+  async storedEntries(
+    snapshotEntries: readonly Entry[] = this.store.branch(),
+  ): Promise<StoredSessionEntry[]> {
+    const submissionByEntry =
+      this.durability.listSessionEntrySubmissionLinks();
+    return snapshotEntries.map((entry) => ({
+      id: entry.id,
+      submissionId: submissionByEntry.get(entry.id) ?? null,
+      entry,
+      createdAt: entry.timestamp,
+    }));
+  }
+
   // #endregion
 }
 

package/src/conversation/index.ts

@@ -0,0 +1,6 @@
+export * from "./history";
+export * from "./harness-stream";
+export * from "./harness-resume";
+export * from "./message";
+export * from "./repository";
+export * from "./state";

package/src/{pi → conversation}/message/contract.ts

@@ -1,4 +1,7 @@
 import type { UIMessage } from "ai";
+import type { UserMessage } from "@earendil-works/pi-ai";
+
+export type PiCanonicalUserInput = UserMessage;
 
 export type UIChatTrigger = "submit-message" | "regenerate-message";