@raybase/core 0.0.1 → 0.3.3

package/dist/agent-chapter-archive.js

@@ -0,0 +1,696 @@
+import { sha256Hex } from "./internal.js";
+import { assertRaybaseObjectKey, raybaseObjectKey, raybaseRuntimeScope, raybaseVectorizeNamespace } from "./platform.js";
+import { nowIso, q } from "./sql.js";
+import { id, integer, longText, raybaseSystemTable, text } from "./schema.js";
+export const raybaseAgentChapterArchiveSystemTables = [
+    raybaseSystemTable("_agent_chapter_purges", {
+        id: id(),
+        scopeKind: text({ required: true }),
+        scopeId: text({ required: true }),
+        agentName: text(),
+        conversationId: text(),
+        objectKey: text(),
+        vectorIdsJson: longText(),
+        actionKind: text(),
+        payloadJson: longText(),
+        attempts: integer({ required: true }),
+        lastError: longText(),
+        nextAttemptAt: text(),
+        requestedAt: text({ required: true })
+    }, { indexes: [["scopeKind", "scopeId"], ["attempts", "nextAttemptAt"], ["conversationId"]] })
+];
+export const agentChapterPurgeMaxAttempts = 8;
+export const agentChapterPurgeBaseBackoffMs = 60_000;
+export const agentChapterPurgeMaxBackoffMs = 6 * 60 * 60_000;
+/**
+ * Version stamped on every archive NDJSON line (`raybaseArchiveV`) and on the
+ * R2 object (`customMetadata.raybaseArchiveV`). Lines written before the
+ * stamp existed carry no field and are read as version 1.
+ */
+export const agentChapterArchiveVersion = 1;
+export function agentChapterArchiveObjectKey(chapter, env) {
+    const fallback = () => [
+        "thread-archive",
+        archiveKeySegment(chapter.agentName),
+        archiveKeySegment(chapter.conversationId),
+        `${chapter.ordinal}-${archiveKeySegment(chapter.id)}.ndjson`
+    ].join("/");
+    if (!env)
+        return fallback();
+    return raybaseObjectKey(env, "agent-transcript", [chapter.agentName, chapter.conversationId, `${chapter.ordinal}-${chapter.id}.ndjson`], raybaseRuntimeScope(env), fallback);
+}
+export function agentChapterArchivePrefix(agentName, conversationId, env) {
+    const fallback = () => `thread-archive/${archiveKeySegment(agentName)}/${archiveKeySegment(conversationId)}/`;
+    if (!env)
+        return fallback();
+    return `${raybaseObjectKey(env, "agent-transcript", [agentName, conversationId], raybaseRuntimeScope(env), () => fallback().slice(0, -1))}/`;
+}
+/**
+ * Reconnects prompt-assembly groups to their unresolved stored UI messages.
+ * Model-only image data must never become the verbatim archive source.
+ */
+export function agentChapterArchiveGroupsFromStoredMessages(groups, storedMessages) {
+    const storedById = new Map();
+    for (const message of storedMessages) {
+        const record = archiveRecord(message);
+        if (typeof record.id === "string")
+            storedById.set(record.id, message);
+    }
+    return groups.map((group) => {
+        const raw = archiveRecord(group.raw);
+        const id = typeof raw.id === "string" ? raw.id : group.id;
+        return {
+            ...group,
+            raw: sanitizeAgentChapterArchiveRaw(id ? storedById.get(id) ?? group.raw : group.raw)
+        };
+    });
+}
+export async function prepareAgentChapterArchive(chapter, groups, env) {
+    const lines = groups.map((group) => {
+        const safeRaw = sanitizeAgentChapterArchiveRaw(group.raw);
+        const message = safeRaw && typeof safeRaw === "object" && !Array.isArray(safeRaw)
+            ? {
+                ...safeRaw,
+                createdAt: safeRaw.createdAt ?? group.createdAt ?? null
+            }
+            : {
+                id: group.id,
+                createdAt: group.createdAt ?? null,
+                messages: group.messages
+            };
+        // Member surfaces read this format back for years; a line without the
+        // version field is also version 1 (the field arrived 2026-08, objects
+        // are integrity-locked and never rewritten). Readers dispatch on the
+        // field, never on shape sniffing.
+        return JSON.stringify({ ...message, raybaseArchiveV: agentChapterArchiveVersion });
+    });
+    const ndjson = lines.length ? `${lines.join("\n")}\n` : "";
+    return {
+        chapterId: chapter.id,
+        objectKey: agentChapterArchiveObjectKey(chapter, env),
+        ndjson,
+        sha256: await sha256Hex(ndjson),
+        bytes: new TextEncoder().encode(ndjson).byteLength
+    };
+}
+function sanitizeAgentChapterArchiveRaw(value) {
+    const record = archiveRecord(value);
+    if (!Object.keys(record).length || !Array.isArray(record.parts))
+        return value;
+    return {
+        ...record,
+        parts: record.parts.filter((part) => {
+            const candidate = archiveRecord(part);
+            return !(candidate.type === "file" && typeof candidate.url === "string" && candidate.url.startsWith("data:"));
+        })
+    };
+}
+function archiveRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export async function archivePreparedAgentChapter(input) {
+    const current = await input.control.first(`SELECT * FROM ${q("_agent_chapters")} WHERE "id" = ? LIMIT 1`, [input.prepared.chapterId]);
+    if (!current)
+        throw new Error(`Agent chapter ${input.prepared.chapterId} no longer exists`);
+    if (current.archiveObjectKey === input.prepared.objectKey
+        && current.archiveSha256 === input.prepared.sha256
+        && current.archiveBytes === input.prepared.bytes
+        && current.archivedAt) {
+        return current;
+    }
+    const obligationAt = input.now ?? nowIso();
+    await input.control.run(`UPDATE ${q("_agent_chapters")}
+     SET "archiveObligationAt" = COALESCE("archiveObligationAt", ?), "updatedAt" = ?
+     WHERE "id" = ?`, [obligationAt, obligationAt, input.prepared.chapterId]);
+    if (!input.bucket)
+        throw new Error("RAYBASE_THREAD_ARCHIVE R2 binding is missing");
+    await input.bucket.put(input.prepared.objectKey, input.prepared.ndjson, {
+        httpMetadata: { contentType: "application/x-ndjson" },
+        customMetadata: {
+            raybaseSha256: input.prepared.sha256,
+            raybaseChapterId: input.prepared.chapterId,
+            raybaseArchiveV: String(agentChapterArchiveVersion)
+        }
+    });
+    const head = await input.bucket.head(input.prepared.objectKey);
+    verifyAgentChapterArchiveHead(head, input.prepared);
+    const archivedAt = input.now ?? nowIso();
+    await input.control.run(`UPDATE ${q("_agent_chapters")}
+     SET "archiveObligationAt" = NULL, "archiveObjectKey" = ?, "archiveSha256" = ?, "archiveBytes" = ?,
+         "archivedAt" = ?, "updatedAt" = ?
+     WHERE "id" = ?`, [
+        input.prepared.objectKey,
+        input.prepared.sha256,
+        input.prepared.bytes,
+        archivedAt,
+        archivedAt,
+        input.prepared.chapterId
+    ]);
+    const confirmed = await input.control.first(`SELECT * FROM ${q("_agent_chapters")} WHERE "id" = ? LIMIT 1`, [input.prepared.chapterId]);
+    if (!confirmed
+        || confirmed.archiveObjectKey !== input.prepared.objectKey
+        || confirmed.archiveSha256 !== input.prepared.sha256) {
+        throw new Error(`Agent chapter ${input.prepared.chapterId} archive confirmation failed`);
+    }
+    return confirmed;
+}
+export async function readAgentChapterArchive(bucket, chapter) {
+    if (!chapter.archiveObjectKey)
+        return null;
+    if (!bucket)
+        throw new Error("RAYBASE_THREAD_ARCHIVE R2 binding is missing");
+    const object = await bucket.get(chapter.archiveObjectKey);
+    if (!object)
+        throw new Error(`Archived transcript for chapter ${chapter.id} is missing`);
+    const text = await object.text();
+    const bytes = new TextEncoder().encode(text).byteLength;
+    const sha256 = await sha256Hex(text);
+    if (chapter.archiveBytes !== null && bytes !== chapter.archiveBytes) {
+        throw new Error(`Archived transcript for chapter ${chapter.id} has an unexpected byte length`);
+    }
+    if (chapter.archiveSha256 && sha256 !== chapter.archiveSha256) {
+        throw new Error(`Archived transcript for chapter ${chapter.id} failed sha256 verification`);
+    }
+    return text;
+}
+export function ensureAgentChapterArchiveSpool(spool) {
+    spool.sql `CREATE TABLE IF NOT EXISTS "_agent_chapter_pending_archive" (
+    "chapterId" TEXT PRIMARY KEY NOT NULL,
+    "ndjson" TEXT NOT NULL,
+    "sha256" TEXT NOT NULL,
+    "attempts" INTEGER NOT NULL DEFAULT 0,
+    "lastError" TEXT,
+    "createdAt" TEXT NOT NULL
+  )`;
+}
+export function spoolPendingAgentChapterArchive(spool, prepared, error) {
+    ensureAgentChapterArchiveSpool(spool);
+    const message = error instanceof Error ? error.message : String(error);
+    spool.sql `INSERT INTO "_agent_chapter_pending_archive"
+    ("chapterId", "ndjson", "sha256", "attempts", "lastError", "createdAt")
+    VALUES (${prepared.chapterId}, ${prepared.ndjson}, ${prepared.sha256}, ${1}, ${message.slice(0, 2_000)}, ${nowIso()})
+    ON CONFLICT("chapterId") DO UPDATE SET
+      "ndjson" = excluded."ndjson",
+      "sha256" = excluded."sha256",
+      "attempts" = "_agent_chapter_pending_archive"."attempts" + 1,
+      "lastError" = excluded."lastError"`;
+}
+/**
+ * Stage the only verbatim copy before the first external archive mutation.
+ * This remains synchronous so isolate death cannot land between the R2 put
+ * and a recoverable local copy.
+ */
+export function stagePendingAgentChapterArchive(spool, prepared) {
+    ensureAgentChapterArchiveSpool(spool);
+    spool.sql `INSERT INTO "_agent_chapter_pending_archive"
+    ("chapterId", "ndjson", "sha256", "attempts", "lastError", "createdAt")
+    VALUES (${prepared.chapterId}, ${prepared.ndjson}, ${prepared.sha256}, ${0}, ${null}, ${nowIso()})
+    ON CONFLICT("chapterId") DO UPDATE SET
+      "ndjson" = excluded."ndjson",
+      "sha256" = excluded."sha256"`;
+}
+export async function archivePreparedAgentChapterWithSpool(input) {
+    stagePendingAgentChapterArchive(input.spool, input.prepared);
+    try {
+        const confirmed = await archivePreparedAgentChapter(input);
+        prunePendingAgentChapterArchive(input.spool, input.prepared.chapterId);
+        return confirmed;
+    }
+    catch (error) {
+        spoolPendingAgentChapterArchive(input.spool, input.prepared, error);
+        throw error;
+    }
+}
+/**
+ * Runs chapter-close side effects behind a durable archive handoff. In
+ * archive mode the exact NDJSON is staged synchronously before `afterStage`
+ * may await FTS or embedding work. A retry that has neither a confirmed
+ * object nor staged bytes is unsafe and must leave hot storage intact.
+ */
+export async function finalizeAgentChapterArchiveFirst(input) {
+    if (input.groups.length === 0) {
+        if (!input.archiveRequired || (input.chapter.archiveObjectKey && input.chapter.archivedAt))
+            return;
+        // A chapter closed while transcripts were intentionally discarded never
+        // acquired an archive obligation. A later policy change must not make that
+        // already-closed span retroactively owed or wedge expiry forever.
+        if (!input.chapter.archiveObligationAt)
+            return;
+        const staged = listPendingAgentChapterArchives(input.spool)
+            .some((pending) => pending.chapterId === input.chapter.id);
+        if (!staged) {
+            throw new Error(`Agent chapter ${input.chapter.id} has no confirmed or staged transcript archive; refusing hot-storage cleanup`);
+        }
+        const drained = await drainPendingAgentChapterArchives({
+            control: input.control,
+            bucket: input.bucket,
+            spool: input.spool,
+            env: input.env
+        });
+        if (drained.pending > 0) {
+            throw new Error(`${drained.pending} pending agent chapter archive spool entr${drained.pending === 1 ? "y" : "ies"} remains`);
+        }
+        return;
+    }
+    const prepared = input.archiveRequired
+        ? await prepareAgentChapterArchive(input.chapter, input.groups, input.env)
+        : null;
+    if (prepared)
+        stagePendingAgentChapterArchive(input.spool, prepared);
+    await input.afterStage();
+    if (!prepared)
+        return;
+    try {
+        await archivePreparedAgentChapterWithSpool({
+            control: input.control,
+            bucket: input.bucket,
+            spool: input.spool,
+            prepared
+        });
+    }
+    catch (error) {
+        if (input.failOnArchiveError)
+            throw error;
+        console.warn(`Agent chapter ${input.chapter.id} archive deferred to spool`, error);
+    }
+}
+export async function assertAgentChapterArchivesConfirmed(input) {
+    const unsafe = await input.control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_chapters")}
+     WHERE "agentName" = ? AND "conversationId" = ?
+       AND (
+         "archiveObligationAt" IS NOT NULL
+         OR (
+           "archiveObjectKey" IS NOT NULL
+           AND (
+             "archiveSha256" IS NULL
+             OR "archiveBytes" IS NULL
+             OR "archivedAt" IS NULL
+           )
+         )
+       )`, [input.agentName, input.conversationId]);
+    const count = Number(unsafe?.count ?? 0);
+    if (count > 0) {
+        throw new Error(`${count} agent chapter${count === 1 ? "" : "s"} lack a confirmed transcript archive; refusing hot-storage cleanup`);
+    }
+}
+export function listPendingAgentChapterArchives(spool) {
+    ensureAgentChapterArchiveSpool(spool);
+    return spool.sql `SELECT * FROM "_agent_chapter_pending_archive" ORDER BY "createdAt" ASC`;
+}
+export function prunePendingAgentChapterArchive(spool, chapterId) {
+    ensureAgentChapterArchiveSpool(spool);
+    spool.sql `DELETE FROM "_agent_chapter_pending_archive" WHERE "chapterId" = ${chapterId}`;
+}
+export async function drainPendingAgentChapterArchives(input) {
+    const pending = listPendingAgentChapterArchives(input.spool);
+    let drained = 0;
+    for (const item of pending) {
+        const chapter = await input.control.first(`SELECT * FROM ${q("_agent_chapters")} WHERE "id" = ? LIMIT 1`, [item.chapterId]);
+        if (!chapter) {
+            prunePendingAgentChapterArchive(input.spool, item.chapterId);
+            continue;
+        }
+        const prepared = {
+            chapterId: chapter.id,
+            objectKey: agentChapterArchiveObjectKey(chapter, input.env),
+            ndjson: item.ndjson,
+            sha256: item.sha256,
+            bytes: new TextEncoder().encode(item.ndjson).byteLength
+        };
+        try {
+            await archivePreparedAgentChapter({ control: input.control, bucket: input.bucket, prepared });
+            prunePendingAgentChapterArchive(input.spool, item.chapterId);
+            drained += 1;
+        }
+        catch (error) {
+            spoolPendingAgentChapterArchive(input.spool, prepared, error);
+        }
+    }
+    return {
+        drained,
+        pending: listPendingAgentChapterArchives(input.spool).length
+    };
+}
+export async function deleteVerifiedAgentChapterArchive(bucket, objectKey, env) {
+    if (!bucket)
+        throw new Error("RAYBASE_THREAD_ARCHIVE R2 binding is missing");
+    if (env) {
+        assertRaybaseObjectKey(env, "agent-transcript", objectKey, raybaseRuntimeScope(env));
+    }
+    await bucket.delete(objectKey);
+    if (await bucket.head(objectKey)) {
+        throw new Error(`Thread archive object still exists after delete: ${objectKey}`);
+    }
+}
+export async function purgeAgentChapterArtifactsForConversation(input) {
+    const catalogConversation = input.conversationKind
+        ? null
+        : await input.control.first(`SELECT "kind" FROM ${q("_agent_instances")}
+       WHERE "agentName" = ? AND "conversationId" = ? LIMIT 1`, [input.agentName, input.conversationId]);
+    const conversationKind = input.conversationKind
+        ?? (catalogConversation?.kind === "room" ? "room" : "direct");
+    if (conversationKind === "room" && input.roomDeletion !== true) {
+        throw new Error("Shared Agent room artifacts require an explicit whole-room deletion");
+    }
+    const scopeKind = input.scopeKind ?? "conversation";
+    const scopeId = input.scopeId ?? input.conversationId;
+    if (scopeKind === "user") {
+        // Adopt any retry work created by an earlier conversation-scoped purge
+        // before deleting the chapter rows that associate this conversation with
+        // the user. This also covers direct chat-DO erasure calls.
+        await input.control.run(`UPDATE ${q("_agent_chapter_purges")}
+       SET "scopeKind" = 'user', "scopeId" = ?
+       WHERE "conversationId" = ?
+         AND NOT ("scopeKind" = 'user' AND "scopeId" = ?)`, [scopeId, input.conversationId, scopeId]);
+    }
+    const chapters = await input.control.all(`SELECT * FROM ${q("_agent_chapters")} WHERE "agentName" = ? AND "conversationId" = ?`, [input.agentName, input.conversationId]);
+    const objectKeys = new Set(chapters.flatMap((chapter) => chapter.archiveObjectKey ? [chapter.archiveObjectKey] : []));
+    const hasArchiveObligation = chapters.some((chapter) => Boolean(chapter.archiveObligationAt));
+    if (input.spool) {
+        for (const pending of listPendingAgentChapterArchives(input.spool)) {
+            const chapter = chapters.find((candidate) => candidate.id === pending.chapterId);
+            if (chapter)
+                objectKeys.add(agentChapterArchiveObjectKey(chapter, input.env));
+        }
+    }
+    const ledger = await input.control.all(`SELECT e."vectorId", e."backend" FROM ${q("_ai_embedding_chunks")} e
+     JOIN ${q("_agent_chapters")} c ON c."id" = e."sourceId"
+     WHERE e."sourceType" = 'agent-chapter' AND c."agentName" = ? AND c."conversationId" = ?`, [input.agentName, input.conversationId]).catch(() => []);
+    const vectorIds = [...new Set(ledger
+            .filter((row) => row.backend === "vectorize")
+            .map((row) => row.vectorId)
+            .filter(Boolean))];
+    const failures = [];
+    let deletedObjects = 0;
+    for (const objectKey of objectKeys) {
+        try {
+            await deleteVerifiedAgentChapterArchive(input.env.RAYBASE_THREAD_ARCHIVE, objectKey, input.env);
+            deletedObjects += 1;
+        }
+        catch (error) {
+            failures.push({ objectKey, error: errorMessage(error) });
+        }
+    }
+    if (input.env.RAYBASE_THREAD_ARCHIVE) {
+        try {
+            deletedObjects += await deleteAgentChapterArchivePrefix(input.env.RAYBASE_THREAD_ARCHIVE, input.agentName, input.conversationId, input.env);
+        }
+        catch (error) {
+            failures.push({ error: errorMessage(error) });
+        }
+    }
+    else if (hasArchiveObligation && objectKeys.size === 0) {
+        failures.push({
+            error: "RAYBASE_THREAD_ARCHIVE R2 binding is missing for a durable archive prefix obligation"
+        });
+    }
+    if (vectorIds.length) {
+        try {
+            if (!input.env.RAYBASE_VECTORIZE)
+                throw new Error("RAYBASE_VECTORIZE binding is missing");
+            await input.env.RAYBASE_VECTORIZE.deleteByIds(vectorIds, {
+                namespace: await raybaseVectorizeNamespace(input.env, "agent-history", raybaseRuntimeScope(input.env), "default")
+            });
+        }
+        catch (error) {
+            failures.push({ vectorIds, error: errorMessage(error) });
+        }
+    }
+    for (const failure of failures) {
+        await enqueueAgentChapterPurge(input.control, {
+            scopeKind,
+            scopeId,
+            agentName: input.agentName,
+            conversationId: input.conversationId,
+            objectKey: failure.objectKey ?? null,
+            vectorIds: failure.vectorIds ?? [],
+            error: failure.error
+        });
+    }
+    const chapterFts = await input.control.first(`SELECT "name" FROM sqlite_master WHERE "name" = ? LIMIT 1`, ["_agent_chapter_fts"]);
+    if (chapterFts) {
+        await input.control.run(`DELETE FROM ${q("_agent_chapter_fts")} WHERE "chapterId" IN (
+         SELECT "id" FROM ${q("_agent_chapters")} WHERE "agentName" = ? AND "conversationId" = ?
+       )`, [input.agentName, input.conversationId]);
+    }
+    await input.control.run(`DELETE FROM ${q("_ai_embedding_chunks")} WHERE "sourceType" = 'agent-chapter' AND "sourceId" IN (
+       SELECT "id" FROM ${q("_agent_chapters")} WHERE "agentName" = ? AND "conversationId" = ?
+     )`, [input.agentName, input.conversationId]).catch(() => { });
+    await input.control.run(`DELETE FROM ${q("_agent_chapters")} WHERE "agentName" = ? AND "conversationId" = ?`, [input.agentName, input.conversationId]);
+    if (input.spool) {
+        for (const pending of listPendingAgentChapterArchives(input.spool)) {
+            prunePendingAgentChapterArchive(input.spool, pending.chapterId);
+        }
+    }
+    return {
+        pending: await countAgentChapterPurges(input.control, scopeKind, scopeId),
+        deletedObjects,
+        deletedVectors: vectorIds.length && failures.every((failure) => !failure.vectorIds) ? vectorIds.length : 0
+    };
+}
+export async function purgeAgentChapterArtifactsForUser(input) {
+    const conversations = await input.control.all(`SELECT DISTINCT "agentName", "conversationId" FROM ${q("_agent_chapters")} WHERE "userId" = ?`, [input.userId]);
+    let deletedObjects = 0;
+    let deletedVectors = 0;
+    for (const conversation of conversations) {
+        const result = await purgeAgentChapterArtifactsForConversation({
+            ...input,
+            agentName: conversation.agentName,
+            conversationId: conversation.conversationId,
+            scopeKind: "user",
+            scopeId: input.userId,
+            conversationKind: "direct"
+        });
+        deletedObjects += result.deletedObjects;
+        deletedVectors += result.deletedVectors;
+    }
+    return {
+        pending: await countAgentChapterPurges(input.control, "user", input.userId),
+        deletedObjects,
+        deletedVectors
+    };
+}
+export async function retryAgentChapterPurges(input) {
+    const now = input.now ?? nowIso();
+    const filters = [
+        `"attempts" < ?`,
+        `("nextAttemptAt" IS NULL OR "nextAttemptAt" <= ?)`
+    ];
+    const params = [agentChapterPurgeMaxAttempts, now];
+    if (input.scopeKind) {
+        filters.push(`"scopeKind" = ?`);
+        params.push(input.scopeKind);
+    }
+    if (input.scopeId) {
+        filters.push(`"scopeId" = ?`);
+        params.push(input.scopeId);
+    }
+    const rows = await input.control.all(`SELECT * FROM ${q("_agent_chapter_purges")}
+     WHERE ${filters.join(" AND ")}
+     ORDER BY CASE WHEN "nextAttemptAt" IS NULL THEN 0 ELSE 1 END ASC,
+              COALESCE("nextAttemptAt", "requestedAt") ASC,
+              "requestedAt" ASC
+     LIMIT ?`, [
+        ...params,
+        Math.max(1, Math.min(100, input.limit ?? 25))
+    ]);
+    for (const row of rows) {
+        let drainedScope;
+        try {
+            if (row.scopeKind === "room-member") {
+                if (!input.onRoomMemberAction)
+                    throw new Error("Agent room-member purge action handler is unavailable");
+                await input.onRoomMemberAction(row);
+            }
+            else {
+                if (row.objectKey) {
+                    await deleteVerifiedAgentChapterArchive(input.env.RAYBASE_THREAD_ARCHIVE, row.objectKey, input.env);
+                }
+                const vectorIds = parseStringArray(row.vectorIdsJson);
+                if (vectorIds.length) {
+                    if (!input.env.RAYBASE_VECTORIZE)
+                        throw new Error("RAYBASE_VECTORIZE binding is missing");
+                    await input.env.RAYBASE_VECTORIZE.deleteByIds(vectorIds, {
+                        namespace: await raybaseVectorizeNamespace(input.env, "agent-history", raybaseRuntimeScope(input.env), "default")
+                    });
+                }
+                if (row.agentName && row.conversationId) {
+                    if (input.env.RAYBASE_THREAD_ARCHIVE) {
+                        await deleteAgentChapterArchivePrefix(input.env.RAYBASE_THREAD_ARCHIVE, row.agentName, row.conversationId, input.env);
+                    }
+                    else if (!row.objectKey && vectorIds.length === 0) {
+                        throw new Error("RAYBASE_THREAD_ARCHIVE R2 binding is missing");
+                    }
+                }
+            }
+            const otherRows = await input.control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_chapter_purges")}
+         WHERE "scopeKind" = ? AND "scopeId" = ? AND "id" <> ?`, [row.scopeKind, row.scopeId, row.id]);
+            await input.control.run(`DELETE FROM ${q("_agent_chapter_purges")} WHERE "id" = ?`, [row.id]);
+            if (Number(otherRows?.count ?? 0) === 0) {
+                drainedScope = {
+                    scopeKind: row.scopeKind,
+                    scopeId: row.scopeId,
+                    requestedAt: row.requestedAt,
+                    attempts: row.attempts
+                };
+            }
+        }
+        catch (error) {
+            const attempts = row.attempts + 1;
+            await input.control.run(`UPDATE ${q("_agent_chapter_purges")}
+         SET "attempts" = ?, "lastError" = ?, "nextAttemptAt" = ?
+         WHERE "id" = ?`, [
+                attempts,
+                errorMessage(error).slice(0, 2_000),
+                nextAgentChapterPurgeAttemptAt(attempts, now),
+                row.id
+            ]);
+        }
+        if (drainedScope)
+            await input.onScopeDrained?.(drainedScope);
+    }
+    const backlog = await agentChapterPurgeBacklog(input.control, { limit: 0, now });
+    return {
+        attempted: rows.length,
+        remaining: backlog.total,
+        capped: backlog.capped,
+        deferred: backlog.deferred
+    };
+}
+export async function agentChapterPurgeBacklog(control, options = {}) {
+    const now = options.now ?? nowIso();
+    const summary = await control.first(`SELECT
+       COUNT(*) AS "total",
+       COALESCE(SUM(CASE WHEN "attempts" < ? AND ("nextAttemptAt" IS NULL OR "nextAttemptAt" <= ?) THEN 1 ELSE 0 END), 0) AS "ready",
+       COALESCE(SUM(CASE WHEN "attempts" >= ? THEN 1 ELSE 0 END), 0) AS "capped",
+       MIN("requestedAt") AS "oldestRequestedAt",
+       MIN(CASE WHEN "attempts" < ? AND "nextAttemptAt" > ? THEN "nextAttemptAt" ELSE NULL END) AS "nextAttemptAt"
+     FROM ${q("_agent_chapter_purges")}`, [
+        agentChapterPurgeMaxAttempts,
+        now,
+        agentChapterPurgeMaxAttempts,
+        agentChapterPurgeMaxAttempts,
+        now
+    ]);
+    const total = Number(summary?.total ?? 0);
+    const ready = Number(summary?.ready ?? 0);
+    const capped = Number(summary?.capped ?? 0);
+    const limit = Math.max(0, Math.min(100, Math.floor(options.limit ?? 50)));
+    const rows = limit === 0
+        ? []
+        : await control.all(`SELECT "id", "scopeKind", "scopeId", "agentName", "conversationId", "attempts",
+              "lastError", "nextAttemptAt", "requestedAt"
+       FROM ${q("_agent_chapter_purges")}
+       ORDER BY CASE WHEN "attempts" >= ? THEN 0 ELSE 1 END ASC, "requestedAt" ASC
+       LIMIT ?`, [agentChapterPurgeMaxAttempts, limit]);
+    return {
+        total,
+        ready,
+        deferred: Math.max(0, total - ready - capped),
+        capped,
+        oldestRequestedAt: summary?.oldestRequestedAt ?? null,
+        nextAttemptAt: summary?.nextAttemptAt ?? null,
+        entries: rows.map((row) => ({
+            ...row,
+            attempts: Number(row.attempts),
+            capped: Number(row.attempts) >= agentChapterPurgeMaxAttempts
+        }))
+    };
+}
+export function nextAgentChapterPurgeAttemptAt(attempts, from) {
+    const exponent = Math.max(0, Math.min(16, Math.floor(attempts) - 1));
+    const delay = Math.min(agentChapterPurgeMaxBackoffMs, agentChapterPurgeBaseBackoffMs * (2 ** exponent));
+    return new Date(new Date(from).getTime() + delay).toISOString();
+}
+export async function countAgentChapterPurges(control, scopeKind, scopeId) {
+    const row = await control.first(`SELECT COUNT(*) AS "count" FROM ${q("_agent_chapter_purges")} WHERE "scopeKind" = ? AND "scopeId" = ?`, [scopeKind, scopeId]);
+    return Number(row?.count ?? 0);
+}
+export async function enqueueAgentChapterPurgeAction(input) {
+    const payloadJson = JSON.stringify(input.payload);
+    const existing = await input.control.first(`SELECT "id" FROM ${q("_agent_chapter_purges")}
+     WHERE "scopeKind" = ? AND "scopeId" = ? AND "actionKind" = ?
+       AND json_extract("payloadJson", '$.chapterId') = json_extract(?, '$.chapterId')
+     LIMIT 1`, [input.scopeKind, input.scopeId, input.actionKind, payloadJson]);
+    if (existing)
+        return existing.id;
+    const id = crypto.randomUUID();
+    const requestedAt = input.now ?? nowIso();
+    await input.control.run(`INSERT INTO ${q("_agent_chapter_purges")}
+     ("id", "scopeKind", "scopeId", "agentName", "conversationId", "objectKey", "vectorIdsJson",
+      "actionKind", "payloadJson", "attempts", "lastError", "nextAttemptAt", "requestedAt")
+     VALUES (?, ?, ?, ?, ?, NULL, NULL, ?, ?, 0, NULL, NULL, ?)`, [
+        id,
+        input.scopeKind,
+        input.scopeId,
+        input.agentName,
+        input.conversationId,
+        input.actionKind,
+        payloadJson,
+        requestedAt
+    ]);
+    return id;
+}
+async function deleteAgentChapterArchivePrefix(bucket, agentName, conversationId, env) {
+    let cursor;
+    let deleted = 0;
+    do {
+        const listed = await bucket.list({
+            prefix: agentChapterArchivePrefix(agentName, conversationId, env),
+            cursor
+        });
+        for (const object of listed.objects) {
+            await deleteVerifiedAgentChapterArchive(bucket, object.key, env);
+            deleted += 1;
+        }
+        cursor = listed.truncated ? listed.cursor : undefined;
+    } while (cursor);
+    return deleted;
+}
+async function enqueueAgentChapterPurge(control, input) {
+    const requestedAt = nowIso();
+    await control.run(`INSERT INTO ${q("_agent_chapter_purges")}
+     ("id", "scopeKind", "scopeId", "agentName", "conversationId", "objectKey", "vectorIdsJson",
+      "attempts", "lastError", "nextAttemptAt", "requestedAt")
+     VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?)`, [
+        crypto.randomUUID(),
+        input.scopeKind,
+        input.scopeId,
+        input.agentName,
+        input.conversationId,
+        input.objectKey,
+        input.vectorIds.length ? JSON.stringify(input.vectorIds) : null,
+        input.error.slice(0, 2_000),
+        nextAgentChapterPurgeAttemptAt(1, requestedAt),
+        requestedAt
+    ]);
+}
+function parseStringArray(value) {
+    try {
+        const parsed = value ? JSON.parse(value) : [];
+        return Array.isArray(parsed) ? parsed.filter((item) => typeof item === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function verifyAgentChapterArchiveHead(head, prepared) {
+    if (!head)
+        throw new Error(`Thread archive object was not visible after put: ${prepared.objectKey}`);
+    if (head.size !== prepared.bytes) {
+        throw new Error(`Thread archive object size mismatch for ${prepared.objectKey}`);
+    }
+    if (head.customMetadata?.raybaseSha256 !== prepared.sha256) {
+        throw new Error(`Thread archive object sha256 metadata mismatch for ${prepared.objectKey}`);
+    }
+    if (head.customMetadata?.raybaseChapterId !== prepared.chapterId) {
+        throw new Error(`Thread archive object chapter metadata mismatch for ${prepared.objectKey}`);
+    }
+}
+function archiveKeySegment(value) {
+    return encodeURIComponent(value).replace(/%2F/gi, "%252F");
+}
+//# sourceMappingURL=agent-chapter-archive.js.map