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

package/src/{pi/session → session/cloudflare}/migration.ts

@@ -2,7 +2,7 @@ import { isEqual } from "lodash-es";
 import {
   decodePiToolRecoveryMilestone,
   replayPiToolRecovery,
-} from "../turn/tool-recovery";
+} from "./legacy-tool-recovery";
 /** Versioned SQL data migration, called before the Runtime opens its transcript. */
 import {
   branchTip,
@@ -12,19 +12,43 @@ import {
   setValue,
   deleteValue,
   sessionName,
+  laneState,
+  operationMeta,
+  operationState,
+  pendingEntry,
   sessionEntryToContextMessages,
   value,
   type Entry,
   type JsonValue,
   type Write,
+  type Value,
+  type LaneState,
+  type ToolExecution,
 } from "@earendil-works/pi-agent-core/harness/session";
-import {
-  createToolResultMessage,
-  type AgentToolResult,
-  type AgentMessage,
+import type {
+  AgentToolResult,
+  AgentMessage,
 } from "@earendil-works/pi-agent-core";
 import type { Usage, ToolResultMessage } from "@earendil-works/pi-ai";
-import { CloudflareSessionStorage } from "./storage";
+import {
+  CloudflareSessionStorage,
+  CURRENT_PI_STORAGE_VERSION,
+} from "./storage";
+
+const RETIRED_SCHEDULE_CALLBACKS = [
+  "_cleanupStreamBuffers",
+  "_piPlannedContinuation",
+  "_piContinuationWatchdog",
+  "_piApprovalContinuation",
+  "_chatRecoveryRetry",
+] as const;
+
+const LEGACY_TERMINAL_SUBMISSION_STATUSES = new Set([
+  "completed",
+  "failed",
+  "aborted",
+  "skipped",
+]);
 
 type LegacyRecord = Record<string, unknown> & {
   id: string;
@@ -76,7 +100,7 @@ function message(input: unknown): AgentMessage {
   finite(record.timestamp);
   if (record.role === "assistant" && record.stopReason === "pending")
     throw new Error("Unsettled legacy assistant message");
-  return record as unknown as AgentMessage;
+  return normalizeLegacyAskUserMessage(record) as AgentMessage;
 }
 function hasTable(sql: SqlStorage, name: string): boolean {
   return (
@@ -89,6 +113,319 @@ function hasTable(sql: SqlStorage, name: string): boolean {
   );
 }
 
+const ASK_USER_RESPONSE_TYPES = new Set([
+  "text",
+  "single_select",
+  "multi_select",
+  "attachment",
+]);
+
+function normalizeLegacyAskUserInput(input: unknown): unknown {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return input;
+  const record = input as Record<string, unknown>;
+  if (!Array.isArray(record.questions)) return input;
+  return {
+    ...record,
+    questions: record.questions.map((value) => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+      const question = value as Record<string, unknown>;
+      const { kind, multiSelect, ...current } = question;
+      if (ASK_USER_RESPONSE_TYPES.has(question.responseType as string)) {
+        return current;
+      }
+      if (kind !== undefined && kind !== "attachment") return value;
+      const responseType = kind === "attachment"
+        ? "attachment"
+        : Array.isArray(question.options)
+          ? multiSelect === true ? "multi_select" : "single_select"
+          : "text";
+      return { ...current, responseType };
+    }),
+  };
+}
+
+function normalizeLegacyAskUserMessage(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const message = value as Record<string, unknown>;
+  if (message.role !== "assistant" || !Array.isArray(message.content)) return value;
+  return {
+    ...message,
+    content: message.content.map((part) => {
+      if (!part || typeof part !== "object" || Array.isArray(part)) return part;
+      const block = part as Record<string, unknown>;
+      return block.type === "toolCall" && block.name === "ask_user"
+        ? {
+            ...block,
+            arguments: normalizeLegacyAskUserInput(block.arguments),
+          }
+        : part;
+    }),
+  };
+}
+
+function normalizeLegacyAskUserEntry(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const entry = value as Record<string, unknown>;
+  if (entry.type === "message") {
+    return { ...entry, message: normalizeLegacyAskUserMessage(entry.message) };
+  }
+  if (entry.type === "compaction" && Array.isArray(entry.retainedTail)) {
+    return {
+      ...entry,
+      retainedTail: entry.retainedTail.map(normalizeLegacyAskUserMessage),
+    };
+  }
+  return value;
+}
+
+function migrateLegacyAskUserData(sql: SqlStorage): void {
+  if (hasTable(sql, "pi_entries")) {
+    for (const row of sql.exec<{ id: string; body: string }>(
+      "SELECT id, body FROM pi_entries",
+    ).toArray()) {
+      sql.exec(
+        "UPDATE pi_entries SET body = ? WHERE id = ?",
+        JSON.stringify(normalizeLegacyAskUserEntry(JSON.parse(row.body))),
+        row.id,
+      );
+    }
+  }
+  if (hasTable(sql, "pi_tool_interactions")) {
+    for (const row of sql.exec<{ interaction_id: string; input_json: string }>(
+      "SELECT interaction_id, input_json FROM pi_tool_interactions WHERE tool_name = 'ask_user'",
+    ).toArray()) {
+      sql.exec(
+        "UPDATE pi_tool_interactions SET input_json = ? WHERE interaction_id = ?",
+        JSON.stringify(normalizeLegacyAskUserInput(JSON.parse(row.input_json))),
+        row.interaction_id,
+      );
+    }
+  }
+  if (hasTable(sql, "pi_values")) {
+    for (const row of sql.exec<{ key: string; body: string }>(
+      "SELECT key, body FROM pi_values WHERE namespace = 'pi.op.state'",
+    ).toArray()) {
+      const state = JSON.parse(row.body) as {
+        batch?: {
+          assistantEntryId?: unknown;
+          turnId?: unknown;
+        };
+      };
+      const assistantEntryId = state.batch?.assistantEntryId;
+      const turnId = state.batch?.turnId;
+      if (typeof assistantEntryId !== "string" || typeof turnId !== "string") {
+        continue;
+      }
+      const entryRow = sql.exec<{ body: string }>(
+        "SELECT body FROM pi_entries WHERE id = ?",
+        assistantEntryId,
+      ).toArray()[0];
+      if (!entryRow) continue;
+      const entry = JSON.parse(entryRow.body) as {
+        type?: unknown;
+        message?: { role?: unknown; content?: unknown };
+      };
+      if (
+        entry.type !== "message" || entry.message?.role !== "assistant" ||
+        !Array.isArray(entry.message.content)
+      ) continue;
+      entry.message.content.forEach((part, sourceIndex) => {
+        if (!part || typeof part !== "object" || Array.isArray(part)) return;
+        const block = part as Record<string, unknown>;
+        if (block.type !== "toolCall" || block.name !== "ask_user") return;
+        const key = `${row.key}:${turnId}:${sourceIndex}`;
+        const args = sql.exec<{ body: string }>(
+          "SELECT body FROM pi_values WHERE namespace = 'pi.op.tool_args' AND key = ?",
+          key,
+        ).toArray()[0];
+        if (!args) return;
+        sql.exec(
+          "UPDATE pi_values SET body = ? WHERE namespace = 'pi.op.tool_args' AND key = ?",
+          JSON.stringify(normalizeLegacyAskUserInput(JSON.parse(args.body))),
+          key,
+        );
+      });
+    }
+  }
+}
+
+function removeRetiredRuntimeArtifacts(sql: SqlStorage): void {
+  sql.exec(
+    "CREATE TABLE IF NOT EXISTS pi_session_entry_submission (entry_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL)",
+  );
+  if (hasTable(sql, "pi_session_message_submission")) {
+    sql.exec(`
+      INSERT OR IGNORE INTO pi_session_entry_submission (entry_id, submission_id)
+        SELECT message_id, submission_id FROM pi_session_message_submission;
+      DROP TABLE pi_session_message_submission;
+    `);
+  }
+  if (hasTable(sql, "cf_agents_schedules")) {
+    const placeholders = RETIRED_SCHEDULE_CALLBACKS.map(() => "?").join(", ");
+    sql.exec(
+      `DELETE FROM cf_agents_schedules WHERE callback IN (${placeholders})`,
+      ...RETIRED_SCHEDULE_CALLBACKS,
+    );
+  }
+  migrateLegacyAskUserData(sql);
+}
+
+/** Older Harness adapters copied the initial user sidecar onto consumed Steers. */
+function repairDuplicatedUserSidecars(sql: SqlStorage): void {
+  if (!hasTable(sql, "pi_message_ui") || !hasTable(sql, "pi_submissions")) return;
+  const entries = new Map(sql.exec<{
+    id: string;
+    parent_id: string | null;
+    body: string;
+    submission_id: string | null;
+  }>(`
+    SELECT entry.id, entry.parent_id, entry.body, link.submission_id
+    FROM pi_entries AS entry
+    LEFT JOIN pi_session_entry_submission AS link ON link.entry_id = entry.id
+  `).toArray().map((row) => [row.id, { ...row, entry: JSON.parse(row.body) as Entry }]));
+  const candidates = sql.exec<{ message_id: string }>(`
+    SELECT ui.message_id
+    FROM pi_message_ui AS ui
+    JOIN pi_session_entry_submission AS link ON link.entry_id = ui.message_id
+    JOIN pi_submissions AS submission ON submission.submission_id = link.submission_id
+    WHERE json_extract(ui.body, '$.id') = submission.user_message_id
+  `).toArray();
+  for (const candidate of candidates) {
+    const current = entries.get(candidate.message_id);
+    if (current?.entry.type !== "message" || current.entry.message.role !== "user") continue;
+    let parentId = current.parent_id;
+    const visited = new Set<string>();
+    while (parentId !== null) {
+      if (visited.has(parentId)) throw new Error(`Cyclic Pi ancestry: ${parentId}`);
+      visited.add(parentId);
+      const parent = entries.get(parentId);
+      if (!parent) throw new Error(`Missing Pi ancestor: ${parentId}`);
+      if (parent.submission_id === current.submission_id &&
+        parent.entry.type === "message" && parent.entry.message.role === "user") {
+        // The copied parts are also wrong: canonical Steer content is authoritative.
+        sql.exec("DELETE FROM pi_message_ui WHERE message_id = ?", candidate.message_id);
+        break;
+      }
+      parentId = parent.parent_id;
+    }
+  }
+}
+
+function hasToolExecution(value: ToolExecution | undefined): boolean {
+  return value?.status === "blocked" ||
+    (value?.status === "executed" && value.args !== null &&
+      typeof value.args === "object" && !Array.isArray(value.args));
+}
+
+/** A terminal Submission cannot resume, so its stale lane pointer is not active work. */
+function clearTerminalOperationPointers(sql: SqlStorage): void {
+  if (!hasTable(sql, "pi_submissions")) return;
+  const lanes = sql.exec<{ key: string; body: string }>(
+    "SELECT key, body FROM pi_values WHERE namespace = ?",
+    laneState("").namespace,
+  ).toArray();
+  for (const lane of lanes) {
+    const state = JSON.parse(lane.body) as LaneState;
+    if (state.currentOperationId === null) continue;
+    const terminal = sql.exec(
+      `SELECT 1 FROM pi_submissions
+       WHERE submission_id = ?
+         AND status IN ('completed', 'failed', 'aborted', 'skipped')
+       LIMIT 1`,
+      state.currentOperationId,
+    ).toArray().length === 1;
+    if (!terminal) continue;
+    sql.exec(
+      `UPDATE pi_values
+       SET body = json_set(body, '$.currentOperationId', json('null'))
+       WHERE namespace = ? AND key = ?`,
+      laneState("").namespace,
+      lane.key,
+    );
+  }
+}
+
+/** Old active tool outcomes cannot be reconstructed from error text or approval facts. */
+function assertActiveToolProvenance(sql: SqlStorage): void {
+  const read = <T>(address: Value<T>): T | undefined => {
+    const row = sql.exec<{ body: string }>(
+      "SELECT body FROM pi_values WHERE namespace = ? AND key = ?",
+      address.namespace, address.key,
+    ).toArray()[0];
+    return row ? JSON.parse(row.body) as T : undefined;
+  };
+  const lanes = sql.exec<{ key: string; body: string }>(
+    "SELECT key, body FROM pi_values WHERE namespace = ?",
+    laneState("").namespace,
+  ).toArray();
+  for (const lane of lanes) {
+    const operationId = (JSON.parse(lane.body) as LaneState).currentOperationId;
+    if (operationId === null) continue;
+    const reject: (reason: string) => never = (reason) => {
+      throw new Error(
+        `Cannot upgrade Pi storage while operation ${operationId} is active: ${reason}. ` +
+        "Complete this operation with the previous runtime version, then retry the upgrade.",
+      );
+    };
+    const meta = read(operationMeta(operationId));
+    const state = read(operationState(operationId));
+    if (!meta || !state) reject("its durable operation metadata is incomplete");
+    let tip = read(branchTip(lane.key));
+    if (tip === undefined) reject("its lane branch tip is missing");
+    const visited = new Set<string>();
+    while (tip !== meta.sourceTipId) {
+      if (tip === null || visited.has(tip)) reject("its operation branch cannot be verified");
+      visited.add(tip);
+      const row = sql.exec<{ body: string }>("SELECT body FROM pi_entries WHERE id = ?", tip).toArray()[0];
+      if (!row) reject(`its canonical entry ${tip} is missing`);
+      const entry = JSON.parse(row.body) as Entry;
+      if (entry.type === "message" && entry.message.role === "toolResult" &&
+        !hasToolExecution(entry.toolExecution)) {
+        reject(`ToolResult ${entry.id} has no reliable execution provenance`);
+      }
+      tip = entry.parentId;
+    }
+    if (state.at !== "tools") continue;
+    for (const call of state.batch.calls) {
+      if (call.status === "planned" || call.status === "completed") continue;
+      if (call.status === "effect_pending") {
+        reject(`Tool invocation ${call.resultEntryId} has an unresolved execution outcome`);
+      }
+      const pending = read(pendingEntry(call.resultEntryId));
+      if (pending?.type !== "message" || pending.payload.role !== "toolResult" ||
+        !hasToolExecution(pending.toolExecution)) {
+        reject(`pending ToolResult ${call.resultEntryId} has no reliable execution provenance`);
+      }
+    }
+  }
+}
+
+/** Upgrade an already-Harness-backed Session before normal reads begin. */
+export function migrateCurrentPiSession(
+  storage: DurableObjectStorage,
+): boolean {
+  return storage.transactionSync(() => {
+    const sql = storage.sql;
+    if (!hasTable(sql, "pi_storage_state")) return false;
+    const version = sql.exec<{ storage_version: number }>(
+      "SELECT storage_version FROM pi_storage_state WHERE singleton = 1",
+    ).one().storage_version;
+    if (version === CURRENT_PI_STORAGE_VERSION) return false;
+    if (version !== 1 && version !== 2) {
+      throw new Error(`Unsupported Cloudflare Pi storage version: ${version}`);
+    }
+    clearTerminalOperationPointers(sql);
+    assertActiveToolProvenance(sql);
+    if (version === 1) removeRetiredRuntimeArtifacts(sql);
+    repairDuplicatedUserSidecars(sql);
+    sql.exec(
+      "UPDATE pi_storage_state SET storage_version = ? WHERE singleton = 1",
+      CURRENT_PI_STORAGE_VERSION,
+    );
+    return true;
+  });
+}
+
 function assertSameToolResult(
   left: ToolResultMessage,
   right: ToolResultMessage,
@@ -107,6 +444,28 @@ function assertSameToolResult(
   }
 }
 
+function legacyToolResultMessage(input: {
+  toolCallId: string;
+  toolName: string;
+  result: AgentToolResult<unknown>;
+  isError: boolean;
+  timestamp: number;
+}): ToolResultMessage {
+  return {
+    role: "toolResult",
+    toolCallId: input.toolCallId,
+    toolName: input.toolName,
+    content: input.result.content ?? [],
+    details: input.result.details,
+    ...(input.result.usage ? { usage: input.result.usage } : {}),
+    ...(input.result.addedToolNames?.length
+      ? { addedToolNames: input.result.addedToolNames }
+      : {}),
+    isError: input.isError,
+    timestamp: input.timestamp,
+  };
+}
+
 /**
  * Called synchronously during DO startup, before admission or recovery can execute.
  * Durable pending work keeps its IDs and state; no old executor runs across this boundary.
@@ -122,6 +481,7 @@ export function migrateLegacyPiSession(
   try {
     storage.transactionSync(() => {
       if (hasTable(sql, "pi_storage_state")) {
+        migrateCurrentPiSession(storage);
         const store = new CloudflareSessionStorage(storage);
         report = {
           sourceEntries: 0,
@@ -356,6 +716,20 @@ export function migrateLegacyPiSession(
               .map((row) => [row.message_id, row.submission_id] as const)
           : [],
       );
+      const submissionStatuses = new Map(
+        hasTable(sql, "pi_submissions")
+          ? sql
+              .exec<{ submission_id: string; status: string }>(
+                "SELECT submission_id, status FROM pi_submissions",
+              )
+              .toArray()
+              .map((row) => [row.submission_id, row.status] as const)
+          : [],
+      );
+      const terminalSubmission = (submissionId: string): boolean =>
+        LEGACY_TERMINAL_SUBMISSION_STATUSES.has(
+          submissionStatuses.get(submissionId) ?? "",
+        );
       const results = new Map<string, ToolResultMessage>();
       for (const entry of converted.values()) {
         if (entry.type !== "message" || entry.message.role !== "toolResult")
@@ -485,8 +859,12 @@ export function migrateLegacyPiSession(
             if (!knownSubmissions.has(row.submission_id))
               throw new Error("Dangling recovery submission");
             const record = decodePiToolRecoveryMilestone(row.body);
-            if (!record || record.turnId !== row.submission_id)
+            if (!record || record.turnId !== row.submission_id) {
+              if (LEGACY_TERMINAL_SUBMISSION_STATUSES.has(
+                submissionStatuses.get(row.submission_id) ?? "",
+              )) continue;
               throw new Error("Invalid legacy recovery milestone");
+            }
             const bodies = bySubmission.get(row.submission_id) ?? [];
             bodies.push(row.body);
             bySubmission.set(row.submission_id, bodies);
@@ -495,8 +873,12 @@ export function migrateLegacyPiSession(
                 .canonicalToolResults) {
                 const key = `${row.submission_id}:${result.toolCallId}`;
                 const previous = results.get(key);
-                if (previous) assertSameToolResult(previous, result);
-                results.set(key, result);
+                if (previous && !terminalSubmission(row.submission_id)) {
+                  assertSameToolResult(previous, result);
+                }
+                if (!previous || !terminalSubmission(row.submission_id)) {
+                  results.set(key, result);
+                }
               }
             }
           }
@@ -508,8 +890,12 @@ export function migrateLegacyPiSession(
               if (call.result) {
                 const key = `${submissionId}:${call.toolCallId}`;
                 const previous = results.get(key);
-                if (previous) assertSameToolResult(previous, call.result);
-                results.set(key, call.result);
+                if (previous && !terminalSubmission(submissionId)) {
+                  assertSameToolResult(previous, call.result);
+                }
+                if (!previous || !terminalSubmission(submissionId)) {
+                  results.set(key, call.result);
+                }
               }
             }
           }
@@ -567,7 +953,7 @@ export function migrateLegacyPiSession(
             "SELECT submission_id, tool_call_id, tool_name, result, is_error, created_at FROM pi_tool_settlements",
           )
           .toArray()) {
-          const expected = createToolResultMessage({
+          const expected = legacyToolResultMessage({
             toolCallId: row.tool_call_id,
             toolName: row.tool_name,
             result: JSON.parse(row.result) as AgentToolResult<unknown>,
@@ -577,7 +963,9 @@ export function migrateLegacyPiSession(
           const recorded = results.get(
             `${row.submission_id}:${row.tool_call_id}`,
           );
-          if (recorded) assertSameToolResult(recorded, expected);
+          if (recorded && !terminalSubmission(row.submission_id)) {
+            assertSameToolResult(recorded, expected);
+          }
         }
       }
       // The old table remains an inert backup. Failure rolls back DDL, data and the version together.
@@ -585,6 +973,7 @@ export function migrateLegacyPiSession(
         "ALTER TABLE pi_session_entries RENAME TO pi_legacy_entries_backup",
       );
       const store = new CloudflareSessionStorage(storage);
+      removeRetiredRuntimeArtifacts(sql);
       for (const entry of converted.values()) {
         const { seq: _seq, timestamp, ...next } = entry;
         const writes: Write[] = [insertEntry(next)];
@@ -626,6 +1015,7 @@ export function migrateLegacyPiSession(
           values.push(setValue(branchTip(`history:${entry.id}`), entry.id));
       }
       store.commitSync([...values, setValue(branchTip("main"), tip)]);
+      repairDuplicatedUserSidecars(sql);
       sql.exec(
         "UPDATE pi_storage_state SET session_id = ?, created_at = ? WHERE singleton = 1",
         metadata.id,

package/src/{pi/session → session/cloudflare}/storage.ts

@@ -8,7 +8,6 @@ import {
   setValue,
   insertEntry,
   insertUsage,
-  type CompactionEntry,
   type Storage,
   type Write,
   type CommitResult,
@@ -26,9 +25,10 @@ import {
   type SessionStats,
   type SessionMetadata,
 } from "@earendil-works/pi-agent-core/harness/session";
-import type { Usage } from "@earendil-works/pi-ai";
 import type { Context } from "@earendil-works/pi-agent-core/harness/context";
 
+export const CURRENT_PI_STORAGE_VERSION = 3;
+
 /** Pi's Storage contract, with every physical commit confined to one DO transaction. */
 export class CloudflareSessionStorage implements Storage {
   private closed = false;
@@ -60,13 +60,13 @@ export class CloudflareSessionStorage implements Storage {
           storage_version: number;
         }>("SELECT storage_version FROM pi_storage_state WHERE singleton = 1")
         .one().storage_version;
-      if (version !== 1)
+      if (version !== CURRENT_PI_STORAGE_VERSION)
         throw new Error(
           `Unsupported Cloudflare Pi storage version: ${version}`,
         );
     }
     this.sql.exec(`
-      CREATE TABLE IF NOT EXISTS pi_session_message_submission (message_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS pi_session_entry_submission (entry_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS pi_entries (
         id TEXT PRIMARY KEY, seq INTEGER NOT NULL UNIQUE, parent_id TEXT,
         type TEXT NOT NULL, custom_type TEXT, timestamp INTEGER NOT NULL, body TEXT NOT NULL
@@ -83,7 +83,8 @@ export class CloudflareSessionStorage implements Storage {
       CREATE TABLE IF NOT EXISTS pi_storage_state (singleton INTEGER PRIMARY KEY CHECK(singleton = 1), next_seq INTEGER NOT NULL, storage_version INTEGER NOT NULL, session_id TEXT NOT NULL, created_at INTEGER NOT NULL, stats TEXT NOT NULL);
     `);
     this.sql.exec(
-      "INSERT OR IGNORE INTO pi_storage_state VALUES (1, 1, 1, ?, ?, ?)",
+      "INSERT OR IGNORE INTO pi_storage_state VALUES (1, 1, ?, ?, ?, ?)",
+      CURRENT_PI_STORAGE_VERSION,
       crypto.randomUUID(),
       Date.now(),
       JSON.stringify({
@@ -495,7 +496,7 @@ export class CloudflareSessionStorage implements Storage {
       ]);
       if (input.submissionId)
         this.sql.exec(
-          "INSERT INTO pi_session_message_submission VALUES (?, ?)",
+          "INSERT INTO pi_session_entry_submission VALUES (?, ?)",
           input.id,
           input.submissionId,
         );
@@ -503,35 +504,6 @@ export class CloudflareSessionStorage implements Storage {
     });
   }
 
-  moveBranchTip(id: string | null): void {
-    if (id !== null && !this.entry(id))
-      throw new Error(`Unknown branch target: ${id}`);
-    this.commitSync([setValue(branchTip("main"), id)]);
-  }
-
-  recordCompaction(
-    entry: Omit<CompactionEntry, "id" | "parentId" | "seq" | "timestamp"> | undefined,
-    usage: Usage | undefined = entry?.usage,
-  ): string {
-    const id = crypto.randomUUID();
-    const writes: Write[] = [];
-    if (entry) writes.push(
-      insertEntry({
-        ...entry, id,
-        parentId: this.getValueSync(branchTip("main"))?.value ?? null,
-      }),
-      setValue(branchTip("main"), id),
-    );
-    if (usage) writes.push(insertUsage({
-      id: entry ? crypto.randomUUID() : id,
-      ...(entry ? { entryId: id } : {}),
-      usage,
-      adjustment: false,
-    }));
-    this.commitSync(writes);
-    return id;
-  }
-
   entries(): Entry[] {
     return this.sql
       .exec<{ body: string }>("SELECT body FROM pi_entries ORDER BY seq")
@@ -542,7 +514,7 @@ export class CloudflareSessionStorage implements Storage {
   clear(): void {
     this.storage.transactionSync(() => {
       this.sql.exec(
-        "DELETE FROM pi_session_message_submission; DELETE FROM pi_entries; DELETE FROM pi_values; DELETE FROM pi_lists; DELETE FROM pi_usage;",
+        "DELETE FROM pi_session_entry_submission; DELETE FROM pi_entries; DELETE FROM pi_values; DELETE FROM pi_lists; DELETE FROM pi_usage;",
       );
       const usage = {
         input: 0,

package/src/session/index.ts

@@ -0,0 +1,39 @@
+import { StorageBackedSession } from "@earendil-works/pi-agent-core/harness/session";
+import {
+  migrateCurrentPiSession,
+  migrateLegacyPiSession,
+} from "./cloudflare/migration";
+import { CloudflareSessionStorage } from "./cloudflare/storage";
+
+export { migrateLegacyPiSession } from "./cloudflare/migration";
+export { CloudflareSessionStorage } from "./cloudflare/storage";
+
+/** Open only after the startup transaction has installed the current database format. */
+export function openPiSessionStorage(
+  storage: DurableObjectStorage,
+): CloudflareSessionStorage {
+  return storage.transactionSync(() => {
+    const tables = new Set(
+      storage.sql
+        .exec<{ name: string }>(
+          "SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('pi_storage_state', 'pi_session_entries')",
+        )
+        .toArray()
+        .map((row) => row.name),
+    );
+    if (!tables.has("pi_storage_state") && tables.has("pi_session_entries")) {
+      migrateLegacyPiSession(storage, { dryRun: false });
+    } else if (tables.has("pi_storage_state")) {
+      migrateCurrentPiSession(storage);
+    }
+    return new CloudflareSessionStorage(storage);
+  });
+}
+
+/** Open the single official Pi Session owned by one Cloudflare Agent facet. */
+export function openCloudflareSession(
+  storage: DurableObjectStorage,
+): StorageBackedSession {
+  const store = openPiSessionStorage(storage);
+  return new StorageBackedSession(store.metadata, store);
+}

package/src/skills/springbrand-worker-website/index.ts

@@ -163,7 +163,7 @@ export const SPRINGBRAND_WORKER_WEBSITE_SKILL = {
     "5. Call `get_browser_console_logs` for the home page and for every primary internal page. Check navigation responses, missing assets, exceptions, CSP or CORS failures, and client fetch failures.",
     "6. Open the Website with the available browser evidence tools. For a multi-page Website, follow real links from the home page to every primary internal page and verify navigation back to the home page. Check at least the normal desktop viewport and one narrow viewport; capture and inspect a screenshot when visual appearance matters.",
     "7. Fix every failure, redeploy, and repeat the same checks. A clean home page does not prove a multi-page Website works.",
-    "8. After browser verification succeeds, call `save_creation` exactly once with the existing entry HTML Working Copy path. For the recommended layout, that is `/creations/<website-name>/public/index.html`.",
+    "8. After browser verification succeeds, call `save_creation` exactly once with a user-visible title and the existing entry HTML Working Copy path. For the recommended layout, that path is `/creations/<website-name>/public/index.html`.",
     "9. Do not call the Website complete until `save_creation` returns an `artifactId`. Do not save referenced assets as separate Creations.",
     "",
     "## Publication contract",