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

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,7 @@ import {
   type PiToolApprovalView,
   type UIUserSidecar,
 } from "./message";
-import { openPiSessionStorage, type CloudflareSessionStorage } from "../session";
-import {
-  isModelStreamStallMessage,
-  isRecoverableAssistantError,
-} from "../models";
+import { openCloudflareSession, RuntimeConversation } from "../session";
 
 /**
  * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
@@ -204,52 +199,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 +246,38 @@ 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 ? {} : { model: [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 +302,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 +315,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 +329,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 +346,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 +366,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 +418,11 @@ export class ConversationHistory {
    *
    * 两类 Transcript 数据必须一起删除，否则复用消息 ID 时可能重新读到旧附件或 UI 元数据。
    */
-  clear(): void {
-    this.store.clear();
+  async clear(): Promise<void> {
+    await this.withSession((session) => session.commit(async (tx) => {
+      const conversation = await tx.createConversation({ ownership: { kind: "ownerless" } });
+      (await tx.doc(RuntimeConversation)).id = conversation.id;
+    }, BACKGROUND_CONTEXT));
     this.durability.clearUserSidecars();
   }
 
@@ -463,39 +442,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 +461,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 +480,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 +498,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 +510,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
@@ -812,7 +776,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 +792,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";

package/src/conversation/session-entry.ts

@@ -0,0 +1,29 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { EntryRecord } from "@earendil-works/pi-durable";
+import type { Usage } from "@earendil-works/pi-ai";
+
+/** Browser/Host projection only; Pi's EntryRecord remains the canonical record. */
+export type ProjectedSessionEntry = {
+  id: string;
+  identity: string;
+  timestamp: number;
+  submissionId?: string;
+} & ({ type: "message"; message: AgentMessage } | {
+  type: "compaction" | "branch_summary";
+  summary: string;
+  usage?: Usage;
+});
+
+export function projectSessionEntry(entry: EntryRecord): ProjectedSessionEntry {
+  const data = entry.data as { createdAt?: number; displayId?: string; submissionId?: string; message?: AgentMessage } | undefined;
+  const message = entry.model?.[0];
+  const base = { id: String(entry.id), identity: data?.displayId ?? String(entry.id), timestamp: data?.createdAt ?? message?.timestamp ?? 0, ...(data?.submissionId ? { submissionId: data.submissionId } : {}) };
+  if (entry.kind === "pi.compaction") return {
+    ...base, type: "compaction",
+    summary: message?.role === "user" ? typeof message.content === "string" ? message.content : message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("") : "",
+  };
+  return {
+    ...base, type: "message",
+    message: entry.kind === "springbrand.retained-context" ? { role: "custom", customType: entry.kind, content: [], timestamp: base.timestamp } : data?.message ?? message ?? { role: "custom", customType: entry.kind, content: [], timestamp: base.timestamp },
+  };
+}

package/src/harness/index.ts

@@ -3,5 +3,7 @@ export type {
   SessionHarnessLimits,
   SessionHarnessOptions,
   SessionHarnessRunResult,
+  SessionRunOutcome,
+  SessionRunRequest,
 } from "./session-harness";
 export { prepareSubmissionOperation } from "./submission-operation";