@springbrand/agent-runtime 0.3.0-alpha.2 → 0.3.0-alpha.21

package/src/session/cloudflare/storage.ts

@@ -1,537 +1,14 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import {
-  prepareStorageCommit,
-  validateCommittedWrites,
-  resolveListReadOptions,
-  value,
-  branchTip,
-  setValue,
-  insertEntry,
-  insertUsage,
-  type Storage,
-  type Write,
-  type CommitResult,
-  type Entry,
-  type EntryStructure,
-  type EntryScan,
-  type StorageBranchScan,
-  type UsageRow,
-  type UsageScan,
-  type Value,
-  type ValueList,
-  type StoredValue,
-  type ListElement,
-  type ListReadOptions,
-  type SessionStats,
-  type SessionMetadata,
-} from "@earendil-works/pi-agent-core/harness/session";
-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;
-  private readonly sql: SqlStorage;
-  readonly metadata: SessionMetadata;
-
-  constructor(private readonly storage: DurableObjectStorage) {
-    this.sql = storage.sql;
-    const hasVersion =
-      this.sql
-        .exec(
-          "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'pi_storage_state'",
-        )
-        .toArray().length > 0;
-    const hasLegacy =
-      this.sql
-        .exec(
-          "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'pi_session_entries'",
-        )
-        .toArray().length > 0;
-    if (!hasVersion && hasLegacy) {
-      throw new Error(
-        "Pi session requires an explicit legacy-to-0.85 migration",
-      );
-    }
-    if (hasVersion) {
-      const version = this.sql
-        .exec<{
-          storage_version: number;
-        }>("SELECT storage_version FROM pi_storage_state WHERE singleton = 1")
-        .one().storage_version;
-      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_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
-      );
-      CREATE TABLE IF NOT EXISTS pi_values (
-        namespace TEXT NOT NULL, key TEXT NOT NULL, seq INTEGER NOT NULL, body TEXT NOT NULL,
-        PRIMARY KEY(namespace, key)
-      );
-      CREATE TABLE IF NOT EXISTS pi_lists (
-        namespace TEXT NOT NULL, key TEXT NOT NULL, seq INTEGER PRIMARY KEY, body TEXT NOT NULL
-      );
-      CREATE INDEX IF NOT EXISTS pi_lists_address ON pi_lists(namespace, key, seq);
-      CREATE TABLE IF NOT EXISTS pi_usage (id TEXT PRIMARY KEY, seq INTEGER NOT NULL UNIQUE, body TEXT NOT NULL);
-      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, ?, ?, ?, ?)",
-      CURRENT_PI_STORAGE_VERSION,
-      crypto.randomUUID(),
-      Date.now(),
-      JSON.stringify({
-        messageCount: 0,
-        usage: {
-          input: 0,
-          output: 0,
-          cacheRead: 0,
-          cacheWrite: 0,
-          totalTokens: 0,
-          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-        },
-      }),
-    );
-    const row = this.sql
-      .exec<{
-        storage_version: number;
-        session_id: string;
-        created_at: number;
-      }>(
-        "SELECT storage_version, session_id, created_at FROM pi_storage_state WHERE singleton = 1",
-      )
-      .one();
-    this.metadata = {
-      id: row.session_id,
-      createdAt: row.created_at,
-      storageVersion: row.storage_version,
-    };
-  }
-
-  private assertOpen(context?: Context): void {
-    if (this.closed) throw new Error("Session storage is closed");
-    context?.abortSignal?.throwIfAborted();
-  }
-
-  /** Synchronous boundary also used by the host's admission/settlement transaction. */
-  commitSync(writes: Write[], context?: Context): CommitResult {
-    this.assertOpen(context);
-    return this.storage.transactionSync(() => {
-      const firstSeq = this.sql
-        .exec<{
-          next_seq: number;
-        }>("SELECT next_seq FROM pi_storage_state WHERE singleton = 1")
-        .one().next_seq;
-      const prepared = prepareStorageCommit(writes, firstSeq, Date.now());
-      validateCommittedWrites(prepared.writes, firstSeq, {
-        hasEntryId: (id) =>
-          this.sql.exec("SELECT 1 FROM pi_entries WHERE id = ?", id).toArray()
-            .length > 0,
-        hasEntryOrUsageId: (id) =>
-          this.sql
-            .exec(
-              "SELECT 1 FROM pi_entries WHERE id = ? UNION ALL SELECT 1 FROM pi_usage WHERE id = ?",
-              id,
-              id,
-            )
-            .toArray().length > 0,
-      });
-      const stats = this.statsSync();
-      for (const write of prepared.writes) {
-        switch (write.kind) {
-          case "entry": {
-            const { kind: _kind, ...entry } = write;
-            if (entry.type === "message") stats.messageCount += 1;
-            this.sql.exec(
-              "INSERT INTO pi_entries VALUES (?, ?, ?, ?, ?, ?, ?)",
-              entry.id,
-              entry.seq,
-              entry.parentId,
-              entry.type,
-              entry.customType ?? null,
-              entry.timestamp,
-              JSON.stringify(entry),
-            );
-            break;
-          }
-          case "usage": {
-            const { kind: _kind, ...row } = write;
-            for (const key of [
-              "input",
-              "output",
-              "cacheRead",
-              "cacheWrite",
-              "totalTokens",
-              "cacheWrite1h",
-              "reasoning",
-            ] as const) {
-              if (row.usage[key] !== undefined)
-                stats.usage[key] = (stats.usage[key] ?? 0) + row.usage[key];
-            }
-            for (const key of [
-              "input",
-              "output",
-              "cacheRead",
-              "cacheWrite",
-              "total",
-            ] as const)
-              stats.usage.cost[key] += row.usage.cost[key];
-            this.sql.exec(
-              "INSERT INTO pi_usage VALUES (?, ?, ?)",
-              row.id,
-              row.seq,
-              JSON.stringify(row),
-            );
-            break;
-          }
-          case "value":
-            if (write.op === "delete")
-              this.sql.exec(
-                "DELETE FROM pi_values WHERE namespace = ? AND key = ?",
-                write.namespace,
-                write.key,
-              );
-            else
-              this.sql.exec(
-                "INSERT INTO pi_values VALUES (?, ?, ?, ?) ON CONFLICT(namespace, key) DO UPDATE SET seq = excluded.seq, body = excluded.body",
-                write.namespace,
-                write.key,
-                write.seq,
-                JSON.stringify(write.value),
-              );
-            break;
-          case "list":
-            if (write.op === "delete")
-              this.sql.exec(
-                "DELETE FROM pi_lists WHERE namespace = ? AND key = ?",
-                write.namespace,
-                write.key,
-              );
-            else
-              this.sql.exec(
-                "INSERT INTO pi_lists VALUES (?, ?, ?, ?)",
-                write.namespace,
-                write.key,
-                write.seq,
-                JSON.stringify(write.value),
-              );
-            break;
-        }
-      }
-      this.sql.exec(
-        "UPDATE pi_storage_state SET next_seq = ?, stats = ? WHERE singleton = 1",
-        firstSeq + writes.length,
-        JSON.stringify(stats),
-      );
-      return { ...prepared.result, stats };
-    });
-  }
-
-  async commit(writes: Write[], context: Context): Promise<CommitResult> {
-    return this.commitSync(writes, context);
-  }
-
-  async getEntries(
-    ids: string[],
-    context: Context,
-  ): Promise<Map<string, Entry>> {
-    return this.getEntriesSync(ids, context);
-  }
-
-  getEntriesSync(ids: string[], context?: Context): Map<string, Entry> {
-    this.assertOpen(context);
-    const entries = new Map<string, Entry>();
-    for (const id of ids) {
-      const row = this.sql
-        .exec<{ body: string }>("SELECT body FROM pi_entries WHERE id = ?", id)
-        .toArray()[0];
-      if (row) entries.set(id, JSON.parse(row.body));
-    }
-    return entries;
-  }
-
-  async getValue<T>(
-    address: Value<T>,
-    context: Context,
-  ): Promise<StoredValue<T> | undefined> {
-    return this.getValueSync(address, context);
-  }
-
-  getValueSync<T>(
-    address: Value<T>,
-    context?: Context,
-  ): StoredValue<T> | undefined {
-    this.assertOpen(context);
-    const row = this.sql
-      .exec<{
-        seq: number;
-        body: string;
-      }>(
-        "SELECT seq, body FROM pi_values WHERE namespace = ? AND key = ?",
-        address.namespace,
-        address.key,
-      )
-      .toArray()[0];
-    return row
-      ? { address, seq: row.seq, value: JSON.parse(row.body) }
-      : undefined;
-  }
-
-  async scanValues<T>(
-    prefix: Value<T>,
-    context: Context,
-  ): Promise<StoredValue<T>[]> {
-    this.assertOpen(context);
-    return this.sql
-      .exec<{ key: string; seq: number; body: string }>(
-        "SELECT key, seq, body FROM pi_values WHERE namespace = ? AND substr(key, 1, length(?)) = ? ORDER BY key COLLATE BINARY",
-        prefix.namespace,
-        prefix.key,
-        prefix.key,
-      )
-      .toArray()
-      .map((row) => ({
-        address: value<T>(prefix.namespace, row.key),
-        seq: row.seq,
-        value: JSON.parse(row.body),
-      }));
-  }
-
-  async readList<T>(
-    address: ValueList<T>,
-    options: ListReadOptions | undefined,
-    context: Context,
-  ): Promise<ListElement<T>[]> {
-    this.assertOpen(context);
-    const resolved = resolveListReadOptions(options);
-    const descending = resolved.order === "desc";
-    const comparison = descending ? "<" : ">";
-    return this.sql
-      .exec<{ seq: number; body: string }>(
-        `SELECT seq, body FROM pi_lists WHERE namespace = ? AND key = ? AND (? IS NULL OR seq ${comparison} ?) ORDER BY seq ${descending ? "DESC" : "ASC"} LIMIT ?`,
-        address.namespace,
-        address.key,
-        resolved.cursor?.seq ?? null,
-        resolved.cursor?.seq ?? null,
-        resolved.limit,
-      )
-      .toArray()
-      .map((row) => ({ seq: row.seq, value: JSON.parse(row.body) }));
-  }
-
-  private branchRows(query: StorageBranchScan, structure: boolean) {
-    // Stops follow the requested traversal direction; filters must not hide a stop entry.
-    const oldestFirst = query.order === "oldestFirst";
-    const rows = this.sql
-      .exec<{
-        id: string;
-        parentId: string | null;
-        seq: number;
-        timestamp: number;
-        type: Entry["type"];
-        customType: string | null;
-        body?: string;
-      }>(
-        `
-      WITH RECURSIVE path AS (
-        SELECT id, parent_id, seq, timestamp, type, custom_type${structure ? "" : ", body"} FROM pi_entries WHERE id = ?
-        UNION ALL
-        SELECT e.id, e.parent_id, e.seq, e.timestamp, e.type, e.custom_type${structure ? "" : ", e.body"}
-        FROM pi_entries e JOIN path p ON e.id = p.parent_id
-      ) SELECT id, parent_id AS parentId, seq, timestamp, type, custom_type AS customType${structure ? "" : ", body"}
-        FROM path ORDER BY seq ${oldestFirst ? "ASC" : "DESC"}
-    `,
-        query.start,
-      )
-      .toArray();
-    if (!rows.length) throw new Error(`Unknown branch start: ${query.start}`);
-    const root = oldestFirst ? rows[0]! : rows.at(-1)!;
-    if (root.parentId !== null)
-      throw new Error("Corrupt branch: missing parent");
-    const stop = rows.findIndex(
-      (row) => row.id === query.stopAtId || row.type === query.stopAtType,
-    );
-    return (stop < 0 ? rows : rows.slice(0, stop + 1))
-      .filter(
-        (row) =>
-          (query.type === undefined || query.type === row.type) &&
-          (query.customType === undefined ||
-            query.customType === row.customType) &&
-          (query.cursor === undefined ||
-            (oldestFirst
-              ? row.seq > query.cursor.seq
-              : row.seq < query.cursor.seq)),
-      )
-      .slice(
-        0,
-        query.limit === undefined ? undefined : Math.max(0, query.limit),
-      );
-  }
-
-  async scanBranch(
-    query: StorageBranchScan,
-    context: Context,
-  ): Promise<Entry[]> {
-    return this.scanBranchSync(query, context);
-  }
-
-  scanBranchSync(query: StorageBranchScan, context?: Context): Entry[] {
-    this.assertOpen(context);
-    return this.branchRows(query, false).map((row) => JSON.parse(row.body!));
-  }
-
-  async scanBranchStructure(
-    query: StorageBranchScan,
-    context: Context,
-  ): Promise<EntryStructure[]> {
-    this.assertOpen(context);
-    return this.branchRows(query, true).map(
-      ({ customType, body: _body, ...row }) => ({
-        ...row,
-        ...(customType === null ? {} : { customType }),
-      }),
-    );
-  }
-
-  async scanEntries(query: EntryScan, context: Context): Promise<Entry[]> {
-    this.assertOpen(context);
-    return this.sql
-      .exec<{ body: string }>(
-        `
-      SELECT body FROM pi_entries WHERE (? IS NULL OR type = ?) AND (? IS NULL OR custom_type = ?)
-      AND (? IS NULL OR seq >= ?) AND (? IS NULL OR seq <= ?) ORDER BY seq ${query.order === "desc" ? "DESC" : "ASC"} LIMIT ?`,
-        query.type ?? null,
-        query.type ?? null,
-        query.customType ?? null,
-        query.customType ?? null,
-        query.fromSeq ?? null,
-        query.fromSeq ?? null,
-        query.toSeq ?? null,
-        query.toSeq ?? null,
-        query.limit === undefined ? -1 : Math.max(0, Math.trunc(query.limit)),
-      )
-      .toArray()
-      .map((row) => JSON.parse(row.body));
-  }
-
-  async scanUsage(query: UsageScan, context: Context): Promise<UsageRow[]> {
-    this.assertOpen(context);
-    return this.sql
-      .exec<{ body: string }>(
-        `
-      SELECT body FROM pi_usage WHERE (? IS NULL OR seq >= ?) AND (? IS NULL OR seq <= ?)
-      ORDER BY seq ${query.order === "desc" ? "DESC" : "ASC"} LIMIT ?`,
-        query.fromSeq ?? null,
-        query.fromSeq ?? null,
-        query.toSeq ?? null,
-        query.toSeq ?? null,
-        query.limit === undefined ? -1 : Math.max(0, Math.trunc(query.limit)),
-      )
-      .toArray()
-      .map((row) => JSON.parse(row.body));
-  }
-
-  private statsSync(): SessionStats {
-    return JSON.parse(
-      this.sql
-        .exec<{
-          stats: string;
-        }>("SELECT stats FROM pi_storage_state WHERE singleton = 1")
-        .one().stats,
-    );
-  }
-
-  async getStats(context: Context): Promise<SessionStats> {
-    this.assertOpen(context);
-    return this.statsSync();
-  }
-
-  /** Host commits use this single branch; off-branch entries remain available by ID. */
-  branch(): Entry[] {
-    const tip = this.getValueSync(branchTip("main"))?.value;
-    return tip ? this.scanBranchSync({ start: tip, order: "oldestFirst" }) : [];
-  }
-
-  entry(id: string): Entry | undefined {
-    return this.getEntriesSync([id]).get(id);
-  }
-
-  appendMessage(input: {
-    id: string;
-    message: AgentMessage;
-    submissionId?: string;
-  }): boolean {
-    return this.storage.transactionSync(() => {
-      if (this.entry(input.id)) return false;
-      const usage =
-        input.message.role === "assistant" ||
-        input.message.role === "toolResult"
-          ? input.message.usage
-          : undefined;
-      this.commitSync([
-        insertEntry({
-          id: input.id,
-          parentId: this.getValueSync(branchTip("main"))?.value ?? null,
-          type: "message",
-          message: input.message,
-        }),
-        setValue(branchTip("main"), input.id),
-        ...(usage
-          ? [
-              insertUsage({
-                id: crypto.randomUUID(),
-                entryId: input.id,
-                usage,
-                adjustment: false,
-              }),
-            ]
-          : []),
-      ]);
-      if (input.submissionId)
-        this.sql.exec(
-          "INSERT INTO pi_session_entry_submission VALUES (?, ?)",
-          input.id,
-          input.submissionId,
-        );
-      return true;
-    });
-  }
-
-  entries(): Entry[] {
-    return this.sql
-      .exec<{ body: string }>("SELECT body FROM pi_entries ORDER BY seq")
-      .toArray()
-      .map((row) => JSON.parse(row.body));
-  }
-
-  clear(): void {
-    this.storage.transactionSync(() => {
-      this.sql.exec(
-        "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,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        totalTokens: 0,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-      };
-      this.sql.exec(
-        "UPDATE pi_storage_state SET stats = ? WHERE singleton = 1",
-        JSON.stringify({ messageCount: 0, usage }),
-      );
-    });
-  }
-
-  async close(_context?: Context): Promise<void> {
-    this.closed = true;
-  }
+import { defineDoc, type ConversationId, type Storage } from "@earendil-works/pi-durable";
+import { openDurableObjectSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/cloudflare";
+
+/** The host selects a native conversation when regenerating or clearing history. */
+export const RuntimeConversation = defineDoc({
+  kind: "springbrand.conversation",
+  version: 1,
+  scope: "session",
+  initial: (): { id: ConversationId | null } => ({ id: null }),
+});
+
+export async function openNativeStorage(storage: DurableObjectStorage): Promise<Storage> {
+  return openDurableObjectSqliteStorage(storage);
 }

package/src/session/index.ts

@@ -1,39 +1,26 @@
-import { StorageBackedSession } from "@earendil-works/pi-agent-core/harness/session";
-import {
-  migrateCurrentPiSession,
-  migrateLegacyPiSession,
-} from "./cloudflare/migration";
-import { CloudflareSessionStorage } from "./cloudflare/storage";
+import { createSession, type Storage } from "@earendil-works/pi-durable";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { migratePiSession } from "./cloudflare/migration";
+import { openNativeStorage } from "./cloudflare/storage";
 
-export { migrateLegacyPiSession } from "./cloudflare/migration";
-export { CloudflareSessionStorage } from "./cloudflare/storage";
+export { RuntimeConversation } from "./cloudflare/storage";
+export { migratePiSession } from "./cloudflare/migration";
 
-/** 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);
-  });
-}
+const migrations = new WeakMap<DurableObjectStorage, Promise<void>>();
 
-/** 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);
+/** Migration completes before native execution or history reads are admitted. */
+export async function openCloudflareSession(storage: DurableObjectStorage): Promise<Storage> {
+  let migrating = migrations.get(storage);
+  if (!migrating) {
+    migrating = (async () => {
+      const native = await openNativeStorage(storage);
+      const session = createSession(native);
+      try { await migratePiSession(storage, session); }
+      finally { await session.close(BACKGROUND_CONTEXT); }
+    })();
+    migrations.set(storage, migrating);
+    migrating.catch(() => migrations.delete(storage));
+  }
+  await migrating;
+  return openNativeStorage(storage);
 }

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",