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

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,36 @@ 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;
 
 type LegacyRecord = Record<string, unknown> & {
   id: string;
@@ -76,7 +93,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 +106,290 @@ 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));
+}
+
+/** 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}`);
+    }
+    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 +408,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 +445,7 @@ export function migrateLegacyPiSession(
   try {
     storage.transactionSync(() => {
       if (hasTable(sql, "pi_storage_state")) {
+        migrateCurrentPiSession(storage);
         const store = new CloudflareSessionStorage(storage);
         report = {
           sourceEntries: 0,
@@ -567,7 +891,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>,
@@ -585,6 +909,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 +951,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);
+}