@springbrand/agent-runtime 0.1.0

package/src/pi/runtime-adapter/transcript.ts

@@ -0,0 +1,825 @@
+import type { SnapshotMessage, SqlTaggedTemplate } from "agents/chat";
+import type {
+  AgentMessage,
+  CustomMessage,
+} 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,
+  piAssistantToUIMessage,
+  type PiToolApprovalView,
+  type UIUserSidecar,
+} from "../message";
+import {
+  appendSessionMessageSync,
+  clearSessionSync,
+  PiTranscriptStore,
+  moveSessionLeafSync,
+} from "../session";
+import type { PiCanonicalMessageCommit } from "./execution";
+import type { PiRecoveredToolSettlement } from "./recovery";
+import type { RuntimeModelUsageEvent } from "../../kernel/bindings";
+
+/**
+ * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
+ *
+ * @remarks
+ * Runtime、Pi、Submission、Turn 和 transcript 的统一定义见本目录入口 `./index.ts`。
+ */
+
+// #region Transcript 持久化契约
+
+/**
+ * 定义 Transcript 读写持久层所需的最小能力。
+ *
+ * @remarks
+ * `PiRuntimeAdapter.createTranscript` 接收该端口，`AgentRuntimeKernel` 在构造时用 Runtime 数据库实现它。
+ *
+ * 端口只暴露投影和旁路数据所需的操作，避免 Transcript 直接依赖具体 Repository。
+ */
+export interface PiTranscriptDurability {
+  /**
+   * 在一个同步事务中执行一组 Transcript 写入。
+   *
+   * `importMessages` 用它保证整批导入共享同一个持久化边界；回调必须保持同步。
+   */
+  transaction<T>(run: () => T): T;
+  /**
+   * 保存一条用户消息的浏览器补充数据。
+   *
+   * `append` 仅在规范消息首次插入成功时调用，避免重复 ID 改写原来的用户视图。
+   */
+  upsertUserSidecar(id: string, body: string): void;
+  /**
+   * 读取一条用户消息的浏览器补充数据。
+   *
+   * `browserMessages` 重建用户视图时调用；没有补充数据时返回 `null` 并回退到规范消息。
+   */
+  readUserSidecar(id: string): string | null;
+  /**
+   * 删除全部用户消息补充数据。
+   *
+   * `clear` 与规范 Session 一起清理它，避免清空聊天后残留旧附件或元数据。
+   */
+  clearUserSidecars(): void;
+  /**
+   * 读取当前消息 ID 到 Submission ID 的关联。
+   *
+   * `storedMessages` 用它补齐 Pi Session 本身不保存的 Runtime Submission 归属。
+   */
+  listMessageSubmissionLinks(): Map<string, string>;
+  /**
+   * 读取一个 Submission 的浏览器投影字段。
+   *
+   * `browserMessages` 投影助手消息时调用，以复用稳定的消息 ID、时间和终态。
+   */
+  findSubmissionProjection(submissionId: string): {
+    assistantMessageId: string;
+    createdAt: number;
+    completedAt?: number | null;
+    status?: unknown;
+    error?: string | null;
+  } | null;
+  /**
+   * 读取一个 Submission 下的工具审批视图。
+   *
+   * `approvalViews` 在投影助手工具调用时调用，并只把已知决策映射成布尔值。
+   */
+  listApprovalViews(submissionId: string): readonly {
+    toolCallId: string;
+    executionId: string;
+    status: string;
+  }[];
+}
+
+/**
+ * 表示当前 Pi 分支上一条带 Runtime 关联信息的规范消息。
+ *
+ * @remarks
+ * `storedMessages` 生成该结构，浏览器投影、Host 历史和 Turn 启动逻辑读取它。
+ *
+ * Submission 关联和解析后的时间集中放在这里，避免每个读取方重复查询和回退。
+ */
+export interface StoredTranscriptMessage {
+  id: string;
+  submissionId: string | null;
+  message: AgentMessage;
+  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 投影辅助函数
+
+// 作用：把一条 Pi 用户消息还原成浏览器使用的消息视图。
+// 调用：browserMessages 遇到用户消息时调用，并传入持久化 ID、时间和可选 sidecar。
+// 原因：sidecar 优先保留附件和 UI 元数据；待确认：timestamp 为 0 时是否应保留而不是回退到 createdAt。
+function userUIMessage(
+  message: UserMessage,
+  options: {
+    id: string;
+    createdAt: number;
+    sidecar?: UIUserSidecar;
+  },
+): UIMessage {
+  const parts: UIMessage["parts"] = options.sidecar
+    ? [...options.sidecar.parts]
+    : typeof message.content === "string"
+      ? [{ type: "text", text: message.content }]
+      : message.content.flatMap(
+          (part): Array<UIMessage["parts"][number]> => {
+          if (part.type === "text") return [{ type: "text", text: part.text }];
+          if (part.type === "image") {
+            return [{
+              type: "file",
+              mediaType: part.mimeType,
+              url: `data:${part.mimeType};base64,${part.data}`,
+            }];
+          }
+          return [];
+          },
+        );
+  return {
+    id: options.id,
+    role: "user",
+    parts,
+    metadata: options.sidecar?.metadata ?? {
+      createdAt: message.timestamp || options.createdAt,
+    },
+  };
+}
+
+// 作用：从用户或助手消息里取出 Extension Host 可以读取的纯文本。
+// 调用：hostMessages 为每条用户或助手历史调用，调用方只会收到一个字符串。
+// 原因：thinking、工具调用和媒体不是 Host 文本契约的一部分；文本片段直接拼接可保留原始分段内容。
+function hostText(message: UserMessage | AssistantMessage): string {
+  return typeof message.content === "string"
+    ? message.content
+    : message.content
+        .flatMap((part) => part.type === "text" ? [part.text] : [])
+        .join("");
+}
+
+// #endregion
+
+// #region Transcript 适配器
+
+/**
+ * 管理一个 Runtime 实例的 Pi 规范 Transcript 及其对外投影。
+ *
+ * @remarks
+ * `PiRuntimeAdapter.createTranscript` 在 `AgentRuntimeKernel` 构造期间创建它，Runtime 随后把所有消息提交、恢复、压缩和历史读取收口到这里。
+ *
+ * Pi Session 保存规范分支，Runtime 数据库保存 Submission、审批和用户 sidecar；分开保存可避免把 UI 字段写进模型上下文。
+ */
+export class PiRuntimeTranscript {
+  private readonly store: PiTranscriptStore;
+
+  /**
+   * 用当前 Agent 的 SQLite、Runtime 持久化端口和 Pi 模型表创建 Transcript。
+   *
+   * `PiRuntimeAdapter.createTranscript` 每个 Runtime Kernel 构造时调用一次；`hasActiveTurn` 必须反映当前 Submission 生命周期。
+   *
+   * Session 统一包住 `DoSqliteSessionStorage`，模型表只用于压缩，活动 Turn 检查只用于阻止并发导入。
+   */
+  constructor(
+    private readonly sql: SqlTaggedTemplate,
+    private readonly durability: PiTranscriptDurability,
+    private readonly models: Models,
+    private readonly hasActiveTurn: () => boolean,
+  ) {
+    this.store = new PiTranscriptStore(sql);
+  }
+
+  // #region 规范消息写入
+
+  /**
+   * 向当前 Pi 分支追加一条规范消息，并按需保存 Submission 关联和用户 sidecar。
+   *
+   * Runtime 接收新用户消息、Extension Host 追加消息以及本类的 Turn 提交辅助方法都会调用它；返回 `false` 表示该 ID 已存在。
+   *
+   * sidecar 只随首次成功插入写入，使消息 ID 同时承担幂等键，重复请求不能覆盖原视图。
+   */
+  append(
+    id: string,
+    message: AgentMessage,
+    options: {
+      submissionId?: string;
+      createdAt?: number;
+      userMessage?: UIMessage & { role: "user" };
+    } = {},
+  ): boolean {
+    const inserted = appendSessionMessageSync(this.sql, {
+      id,
+      message,
+      ...(options.submissionId
+        ? { submissionId: options.submissionId }
+        : {}),
+      ...(options.createdAt === undefined
+        ? {}
+        : { createdAt: options.createdAt }),
+    });
+    if (inserted && options.userMessage) {
+      const sidecar = captureUIUserSidecar(options.userMessage);
+      this.durability.upsertUserSidecar(id, JSON.stringify(sidecar));
+    }
+    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,
+        createdAt: message.timestamp,
+      }),
+    };
+  }
+
+  /**
+   * 把执行适配器发出的规范提交路由到对应写入路径。
+   *
+   * `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,
+            createdAt: commit.message.timestamp,
+          }),
+        }
+      : this.commitTurnMessage(
+          submissionId,
+          commit.message,
+          commit.ordinal,
+        );
+  }
+
+  /** Stable identity makes terminal recovery replay idempotent. */
+  appendTurnAbortedMarker(
+    submissionId: string,
+    timestamp: number,
+  ): boolean {
+    return this.append(`${submissionId}:turn-aborted`, {
+      role: "custom",
+      customType: "turn-aborted",
+      content: [{
+        type: "text",
+        text: [
+          "<turn_aborted>",
+          "The previous turn was interrupted by the user.",
+          "</turn_aborted>",
+        ].join("\n"),
+      }],
+      display: true,
+      timestamp,
+    } satisfies CustomMessage, { submissionId, createdAt: timestamp });
+  }
+
+  /**
+   * 把恢复流程重建出的工具终态补写进规范 Transcript。
+   *
+   * `materializeRecoveredToolResults` 在恢复决策补齐 settlement 后调用，并先按原工具调用顺序排序。
+   *
+   * ID 与实时工具结果使用相同的 `submissionId + toolCallId` 形状，因此重复恢复只会命中 `append` 的幂等检查。
+   */
+  appendRecoveredToolSettlement(
+    submissionId: string,
+    settlement: PiRecoveredToolSettlement,
+  ): boolean {
+    return this.append(
+      `${submissionId}:tool:${settlement.toolCallId}`,
+      {
+        role: "toolResult",
+        toolCallId: settlement.toolCallId,
+        toolName: settlement.toolName,
+        content: settlement.result.content,
+        details: settlement.result.details,
+        isError: settlement.isError,
+        timestamp: settlement.createdAt,
+      },
+      {
+        submissionId,
+        createdAt: settlement.createdAt,
+      },
+    );
+  }
+
+  /**
+   * 按当前规范分支中工具调用出现的顺序排列恢复结果。
+   *
+   * `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.toolCallId) ?? Number.MAX_SAFE_INTEGER) -
+        (callOrder.get(right.toolCallId) ?? Number.MAX_SAFE_INTEGER),
+    );
+  }
+
+  /**
+   * 读取当前 Pi 分支上的全部规范消息。
+   *
+   * Turn 执行器在创建 PiCore 初始状态时调用，压缩一致性检查也以同一分支为准。
+   *
+   * 这里只返回 `message` entry；compaction 等 Session entry 由上下文转换阶段处理，不能混入原始消息列表。
+   */
+  async canonicalMessages(): Promise<AgentMessage[]> {
+    return this.store.branch().flatMap((entry) =>
+      entry.type === "message" ? [entry.message] : []
+    );
+  }
+
+  /**
+   * 生成可恢复流只需要的消息 ID 与角色快照。
+   *
+   * `executeSubmission` 启动 `runRecoverableChatFiber` 前调用，并把结果写进 Fiber 快照。
+   *
+   * 快照不复制消息正文，正文仍以耐久 Transcript 为准，避免维护第二份完整历史。
+   */
+  async snapshotMessages(): Promise<SnapshotMessage[]> {
+    return (await this.storedMessages()).map((entry) => ({
+      id: entry.id,
+      role: entry.message.role,
+    }));
+  }
+
+  /**
+   * 按 ID 查找一条规范用户消息。
+   *
+   * regenerate 的 admission 检查在移动分支叶子前调用，并核对请求内容是否与原用户消息一致。
+   *
+   * 同时检查 entry 类型和消息角色，防止其他 Session entry 或助手消息被当作 regenerate 起点。
+   */
+  async findUserMessage(id: string): Promise<UserMessage | undefined> {
+    const entry = this.store.entry(id);
+    return entry?.type === "message" && entry.message.role === "user"
+      ? entry.message
+      : undefined;
+  }
+
+  // #endregion
+
+  // #region 分支、压缩与导入
+
+  /**
+   * 把当前 Pi 分支叶子移动到指定 Session entry。
+   *
+   * regenerate admission 在验证原用户消息后调用，使后续写入从该用户消息继续。
+   *
+   * 这里委托同步 Session 存储辅助函数写入叶子标记，不删除原分支，保留 Pi 的分支结构。
+   */
+  moveLeaf(id: string): void {
+    moveSessionLeafSync(this.sql, id);
+  }
+
+  /**
+   * 在 Pi 请求模型前按 Runtime 阈值压缩当前上下文，并把压缩 entry 写回 Session。
+   *
+   * `AgentRuntimeKernel.transformPiContext` 作为 Pi 的 `transformContext` 调用它，并提供本次固定的模型、密钥和取消信号。
+   *
+   * 方法先逐条核对调用参数与耐久分支；不一致或压缩不可用时保留原消息，避免把漂移的内存上下文提交成新的规范分支。
+   */
+  async compactContext(
+    messages: AgentMessage[],
+    options: {
+      compactAfterTokens: number;
+      model: Model<Api>;
+      apiKey: string;
+      signal?: AbortSignal;
+      submissionId?: string;
+      onCompactionPersisted?: (event: RuntimeModelUsageEvent) => void;
+    },
+  ): Promise<AgentMessage[]> {
+    const branch = this.store.branch();
+    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])
+      )
+    ) {
+      console.warn(
+        "[runtime-compaction:degraded]",
+        JSON.stringify({ reason: "canonical-message-mismatch" }),
+      );
+      return messages;
+    }
+    const result = await compactPiContext({
+      branch,
+      compactAfterTokens: options.compactAfterTokens,
+      models: this.models,
+      model: options.model,
+      apiKey: options.apiKey,
+      signal: options.signal,
+    });
+    if (result.compactionEntry) {
+      // 整对象写入:assembly 侧已经造好了完整的 compaction 条目,这里不再拆成位置
+      // 参数。旧写法拆 5 个参数喂 pi 的 Session.appendCompaction,pi 0.81 把它加到
+      // 7 个参数(usage / retainedTail)之后,多出来的会被静默丢掉且编译器不报。
+      this.durability.transaction(() => {
+        const eventId = this.store.appendCompaction(result.compactionEntry!);
+        if (
+          options.submissionId &&
+          options.onCompactionPersisted &&
+          result.modelUsage
+        ) {
+          options.onCompactionPersisted({
+            eventId,
+            submissionId: options.submissionId,
+            kind: "compaction",
+            ...result.modelUsage,
+          });
+        }
+      });
+    }
+    if (result.degraded) {
+      console.warn(
+        "[runtime-compaction:degraded]",
+        JSON.stringify({ reason: "compaction-unavailable" }),
+      );
+    }
+    return result.messages;
+  }
+
+  /**
+   * 把一组浏览器消息一次性转换并导入规范 Transcript。
+   *
+   * `AgentRuntimeKernel.addMessages` 只在真实 fork 或 import 场景调用；活动 Turn 期间会直接拒绝，调用方应等当前 Submission 稳定后再导入。
+   *
+   * 整批写入使用同一个同步事务，用户消息用 import ID 开启投影分组，后续助手步骤沿用该分组并保留首条用户 sidecar。
+   *
+   * 待确认：当前代码没有拒绝以助手消息开头的历史，而这类消息没有 Submission 关联，会被浏览器投影略过。
+   */
+  importSnapshot(snapshot: PiCanonicalTranscriptSnapshot): void {
+    if (this.hasActiveTurn()) {
+      throw new Error("Cannot import messages while a Pi Turn is active");
+    }
+    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,
+          createdAt: entry.createdAt,
+          ...(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(`Pi Session message "${entry.id}" already exists`);
+        }
+      }
+    });
+  }
+
+  /** Export canonical entries through one browser-visible message identity. */
+  async exportSnapshot(
+    throughMessageId: string,
+  ): Promise<PiCanonicalTranscriptSnapshot> {
+    const stored = await this.storedMessages();
+    let cutoff = stored.findIndex((entry) => entry.id === throughMessageId);
+    if (cutoff < 0) {
+      const targetSubmissionId = stored.find((entry) =>
+        entry.submissionId &&
+        this.durability.findSubmissionProjection(entry.submissionId)
+            ?.assistantMessageId === 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`);
+    }
+    return {
+      entries: stored.slice(0, cutoff + 1).map((entry) => {
+        if (entry.message.role !== "user") {
+          return {
+            id: entry.id,
+            message: entry.message,
+            createdAt: entry.createdAt,
+          };
+        }
+        const body = this.durability.readUserSidecar(entry.id);
+        return {
+          id: entry.id,
+          message: entry.message,
+          createdAt: entry.createdAt,
+          ...(body
+            ? { userSidecar: JSON.parse(body) as UIUserSidecar }
+            : {}),
+        };
+      }),
+    };
+  }
+
+  /**
+   * 清空规范 Session 和全部用户 sidecar。
+   *
+   * 客户端 clear 事件仅在没有活动 Submission 时调用，并在外层数据库事务中继续清理其他 Turn 数据。
+   *
+   * 两类 Transcript 数据必须一起删除，否则复用消息 ID 时可能重新读到旧附件或 UI 元数据。
+   */
+  clear(): void {
+    clearSessionSync(this.sql);
+    this.durability.clearUserSidecars();
+  }
+
+  // #endregion
+
+  // #region 对外历史投影
+
+  /**
+   * 把当前规范分支重建成浏览器使用的 Pi 消息视图。
+   *
+   * `AgentRuntimeKernel.getMessages` 和聊天广播读取该结果；用户消息恢复 sidecar，助手消息按 Submission 合并步骤并套用审批与工具结果。
+   *
+   * 多个助手步骤用现有的 `step-start` 保留边界，工具结果回填原 toolCall，避免浏览器维护另一套 Turn 拼装逻辑。
+   */
+  async browserMessages(): Promise<UIMessage[]> {
+    const result: UIMessage[] = [];
+    const seenAssistantSubmissions = new Set<string>();
+    let activeAssistant:
+      | { submissionId: string; index: number }
+      | undefined;
+    for (const entry of await this.storedMessages()) {
+      if (entry.message.role === "user") {
+        const body = this.durability.readUserSidecar(entry.id);
+        result.push(userUIMessage(entry.message, {
+          id: entry.id,
+          createdAt: entry.createdAt,
+          sidecar: body
+            ? JSON.parse(body) as UIUserSidecar
+            : undefined,
+        }));
+        activeAssistant = undefined;
+        continue;
+      }
+      if (!entry.submissionId) continue;
+      if (
+        entry.message.role === "custom" &&
+        entry.message.customType === "turn-aborted"
+      ) {
+        const submission = this.durability.findSubmissionProjection(
+          entry.submissionId,
+        );
+        const index = activeAssistant?.submissionId === entry.submissionId
+          ? activeAssistant.index
+          : undefined;
+        const createdAt = submission?.createdAt ?? entry.createdAt;
+        const completedAt = submission?.completedAt ?? entry.createdAt;
+        const metadata = {
+          createdAt,
+          completedAt,
+          turnDurationMs: Math.max(
+            0,
+            completedAt - createdAt,
+          ),
+          turnStatus: "aborted",
+          interruptedByUser: true,
+        };
+        if (index === undefined) {
+          seenAssistantSubmissions.add(entry.submissionId);
+          result.push({
+            id: submission?.assistantMessageId ?? entry.id,
+            role: "assistant",
+            parts: [],
+            metadata,
+          });
+        } else {
+          const previous = result[index]!;
+          result[index] = {
+            ...previous,
+            metadata: {
+              ...(previous.metadata as Record<string, unknown> | undefined),
+              ...metadata,
+            },
+          };
+        }
+        activeAssistant = undefined;
+        continue;
+      }
+      if (entry.message.role === "assistant") {
+        const existingIndex =
+          activeAssistant?.submissionId === entry.submissionId
+            ? activeAssistant.index
+            : undefined;
+        const submission = this.durability.findSubmissionProjection(
+          entry.submissionId,
+        );
+        const terminal = submission?.status !== undefined &&
+          submission.status !== "pending" &&
+          submission.status !== "running";
+        const completedAt = terminal ? entry.message.timestamp : undefined;
+        const projected = piAssistantToUIMessage(entry.message, {
+          id: seenAssistantSubmissions.has(entry.submissionId)
+            ? entry.id
+            : submission?.assistantMessageId ?? entry.id,
+          metadata: {
+            createdAt: submission?.createdAt ?? entry.createdAt,
+            completedAt,
+            ...(completedAt === undefined
+              ? {}
+              : {
+                  turnDurationMs: Math.max(
+                    0,
+                    completedAt - (submission?.createdAt ?? entry.createdAt),
+                  ),
+                }),
+            turnStatus: submission?.status,
+            ...(submission?.error ? { error: submission.error } : {}),
+          },
+          approvals: this.approvalViews(entry.submissionId),
+        });
+        if (existingIndex === undefined) {
+          activeAssistant = {
+            submissionId: entry.submissionId,
+            index: result.length,
+          };
+          seenAssistantSubmissions.add(entry.submissionId);
+          result.push({
+            ...projected,
+            parts: [{ type: "step-start" }, ...projected.parts],
+          });
+        } else {
+          const previous = result[existingIndex]!;
+          result[existingIndex] = {
+            ...previous,
+            parts: [
+              ...previous.parts,
+              { type: "step-start" },
+              ...projected.parts,
+            ],
+            metadata: projected.metadata,
+          };
+        }
+        continue;
+      }
+      if (entry.message.role === "toolResult") {
+        const index = activeAssistant?.submissionId === entry.submissionId
+          ? activeAssistant.index
+          : undefined;
+        if (index !== undefined) {
+          result[index] = applyPiToolResult(
+            result[index]!,
+            entry.message,
+          );
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 生成 Extension Host 可读取的纯文本消息历史。
+   *
+   * `_hostGetMessages` 和 Session 信息统计调用它；`limit` 有值时只保留末尾指定数量，非正数返回空数组。
+   *
+   * 该端口只暴露用户和助手文本，不泄露 thinking、工具结果或浏览器附件，并在投影完成后统一截取最新记录。
+   */
+  async hostMessages(
+    limit?: number,
+  ): Promise<Array<{ id: string; role: string; content: string }>> {
+    const history = (await this.storedMessages()).flatMap((entry) => {
+      if (
+        entry.message.role !== "user" &&
+        entry.message.role !== "assistant"
+      ) {
+        return [];
+      }
+      return [{
+        id: entry.id,
+        role: entry.message.role,
+        content: hostText(entry.message),
+      }];
+    });
+    if (limit === undefined || limit === null) return history;
+    return limit <= 0 ? [] : history.slice(-limit);
+  }
+
+  // 作用：把一个 Submission 的审批行整理成按 toolCallId 索引的浏览器视图。
+  // 调用：browserMessages 每次投影助手消息时调用。
+  // 原因：只有 approved 和 rejected 能映射为布尔决策，pending 状态只保留 executionId，避免把未决审批误写成拒绝。
+  private approvalViews(
+    submissionId: string,
+  ): Record<string, PiToolApprovalView> {
+    return Object.fromEntries(
+      this.durability.listApprovalViews(submissionId).map((row) => [
+        row.toolCallId,
+        {
+          id: row.executionId,
+          ...(row.status === "approved"
+            ? { approved: true }
+            : row.status === "rejected"
+              ? { approved: false }
+              : {}),
+        },
+      ]),
+    );
+  }
+
+  /**
+   * 读取当前 Pi 分支，并为每条规范消息补齐 Submission 关联和创建时间。
+   *
+   * 浏览器投影、Host 历史、Snapshot 以及 Turn 启动时的助手序号计算都从这里读取，调用方无需再查关联表。
+   *
+   * Session entry 的 ISO 时间优先，解析失败才回退到消息时间；非消息 entry 在这一层统一排除。
+   */
+  async storedMessages(): Promise<StoredTranscriptMessage[]> {
+    const submissionByMessage =
+      this.durability.listMessageSubmissionLinks();
+    return this.store.branch().flatMap((entry) => {
+      if (entry.type !== "message") return [];
+      const parsedTimestamp = Date.parse(entry.timestamp);
+      return [{
+        id: entry.id,
+        submissionId: submissionByMessage.get(entry.id) ?? null,
+        message: entry.message,
+        createdAt: Number.isFinite(parsedTimestamp)
+          ? parsedTimestamp
+          : entry.message.timestamp,
+      }];
+    });
+  }
+
+  // #endregion
+}
+
+// #endregion