@cursor/bdk 0.2.13 → 0.2.14

package/dist/internal/conversation-mirror.js

@@ -5,6 +5,13 @@
  * persists it after each local turn. Conversation data uses framework-owned
  * storage, isolated from author-facing files and KV.
  *
+ * Checkpoint blobs are written in content-addressed packs
+ * (`conversation-pack.ts`): a turn's new blobs are one store write, not one
+ * per blob. The manifest (v2) lists the packs and is written last. Manifests
+ * from engines that wrote one object per blob (v1) still restore; the first
+ * persist after such a restore re-packs the whole conversation from the
+ * local store.
+ *
  * Restore failures propagate so a temporary storage outage cannot fork an
  * existing thread into a fresh conversation. Run bookkeeping remains local;
  * the durable session event stream already records user-visible history.
@@ -12,6 +19,7 @@
 import { agentSdkAgentStoreKeys } from "../files.js";
 import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
 import { mapBounded } from "./bounded.js";
+import { conversationPackEntrySize, decodeConversationPack, encodeConversationPack, } from "./conversation-pack.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { describeError } from "./describe-error.js";
 import { resolveAgentV2Hosting } from "./v2-hosting.js";
@@ -19,41 +27,27 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 export function createConversationMirror(options) {
     const { sink, agentName } = options;
     const logger = options.logger ?? (() => { });
+    const packTargetBytes = options.packTargetBytes ?? PACK_TARGET_BYTES;
+    const maxPacks = options.maxPacks ?? MAX_PACKS;
     /**
-     * Blob ids known to be in the sink, per SDK agent id (upload dedupe).
-     * Bounded oldest-out like the files backend's etag cache: a resident
-     * engine touches an unbounded number of conversations over its lifetime,
-     * and a miss costs one manifest read, never correctness.
+     * Packs each conversation's last successful manifest listed. Bounded
+     * oldest-out like the files backend's etag cache: a resident engine
+     * touches an unbounded number of conversations over its lifetime, and a
+     * miss costs one manifest read, never correctness.
      */
-    const mirrored = new Map();
-    const rememberMirrored = (sdkAgentId, blobIds) => {
-        if (!mirrored.has(sdkAgentId) && mirrored.size >= MAX_TRACKED_CONVERSATIONS) {
-            const oldest = mirrored.keys().next();
-            if (!oldest.done) {
-                mirrored.delete(oldest.value);
-            }
-        }
-        mirrored.set(sdkAgentId, blobIds);
+    const packStates = new Map();
+    const rememberPacks = (sdkAgentId, packs) => {
+        rememberBounded(packStates, sdkAgentId, packs);
     };
     /**
      * Content of the last manifest each conversation **successfully** wrote
      * (minus `persistedAtMs`, which changes on every call by construction).
-     * A persist whose agent document and blob list are unchanged skips the
+     * A persist whose agent document and pack list are unchanged skips the
      * manifest rewrite — `persist` runs on every turn boundary, but most
      * boundaries between checkpoints change nothing durable. Same bound and
-     * eviction as `mirrored`; a miss only costs a redundant rewrite.
+     * eviction as `packStates`; a miss only costs a redundant rewrite.
      */
     const lastManifestContent = new Map();
-    const rememberManifest = (sdkAgentId, content) => {
-        if (!lastManifestContent.has(sdkAgentId) &&
-            lastManifestContent.size >= MAX_TRACKED_CONVERSATIONS) {
-            const oldest = lastManifestContent.keys().next();
-            if (!oldest.done) {
-                lastManifestContent.delete(oldest.value);
-            }
-        }
-        lastManifestContent.set(sdkAgentId, content);
-    };
     /**
      * Per-conversation serialization so a persist cannot interleave with a
      * hydrate (or another persist) for the same conversation. Entries are
@@ -74,67 +68,61 @@ export function createConversationMirror(options) {
         chains.set(sdkAgentId, stored);
         return next;
     }
-    async function mirroredBlobIds(sdkAgentId) {
-        const cached = mirrored.get(sdkAgentId);
+    async function persistedPacks(sdkAgentId) {
+        const cached = packStates.get(sdkAgentId);
         if (cached !== undefined) {
             return cached;
         }
-        // Seed from the previous manifest so a new process does not re-upload the
-        // whole history on its first persist. A miss, an unusable manifest, or
-        // a failed read seeds empty — re-uploading is wasteful, never wrong.
-        const seeded = new Set();
+        // Seed from the previous manifest so a new process appends to it instead
+        // of re-packing the whole history. Anything but a usable v2 manifest
+        // seeds empty — re-packing from the local store is wasteful, never wrong.
+        let seeded = [];
         try {
             const read = await readManifest(sink, agentName, sdkAgentId);
-            if (read.outcome === "found") {
-                for (const blobId of read.manifest.blobIds) {
-                    seeded.add(blobId);
-                }
+            if (read.outcome === "found" && read.manifest.v === 2) {
+                seeded = read.manifest.packs;
             }
         }
         catch (error) {
-            logger(`[bdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-uploading blobs`);
+            logger(`[bdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-packing the conversation`);
         }
-        rememberMirrored(sdkAgentId, seeded);
+        rememberPacks(sdkAgentId, seeded);
         return seeded;
     }
-    async function uploadBlobs(store, sdkAgentId, blobIds, uploaded) {
-        const entries = [];
-        for (const blobId of blobIds) {
-            const body = await store.checkpoints.get({ agentId: sdkAgentId, blobId });
-            if (body !== null) {
-                entries.push({
-                    blobId,
-                    key: agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
-                    body,
-                });
-            }
-        }
-        if (entries.length === 0) {
-            return;
-        }
-        if (sink.putMany === undefined) {
-            for (const entry of entries) {
-                await sink.put(entry.key, entry.body);
-                uploaded.add(entry.blobId);
+    /**
+     * Read `blobIds` from the local store and upload them as packs of at most
+     * `packTargetBytes` (a larger blob gets a pack of its own). Packs upload
+     * one at a time so a re-pack never holds more than one pack in memory.
+     */
+    async function writePacks(store, sdkAgentId, blobIds) {
+        const written = [];
+        let entries = [];
+        let bytes = 0;
+        const flush = async () => {
+            if (entries.length === 0) {
+                return;
             }
-            return;
-        }
-        const settled = await sink.putMany(entries.map(({ key, body }) => ({ key, body })));
-        let failure;
-        for (const [index, entry] of entries.entries()) {
-            const outcome = settled[index];
-            if (outcome?.status === "fulfilled") {
-                uploaded.add(entry.blobId);
+            const { packId, body } = encodeConversationPack(entries);
+            await sink.put(agentSdkAgentStoreKeys.conversationPack(agentName, sdkAgentId, packId), body);
+            written.push({ id: packId, blobIds: entries.map((entry) => entry.blobId) });
+            entries = [];
+            bytes = 0;
+        };
+        for (const blobId of blobIds) {
+            const data = await store.checkpoints.get({ agentId: sdkAgentId, blobId });
+            if (data === null) {
+                continue;
             }
-            else if (failure === undefined) {
-                failure =
-                    outcome?.reason ??
-                        new Error(`conversation mirror: batched upload of "${entry.key}" returned no outcome`);
+            const entry = { blobId, data };
+            const size = conversationPackEntrySize(entry);
+            if (entries.length > 0 && bytes + size > packTargetBytes) {
+                await flush();
             }
+            entries.push(entry);
+            bytes += size;
         }
-        if (failure !== undefined) {
-            throw failure;
-        }
+        await flush();
+        return written;
     }
     return {
         persist(store, sdkAgentId) {
@@ -144,34 +132,53 @@ export function createConversationMirror(options) {
                     // Nothing restorable yet (no conversation, or no checkpoint).
                     return;
                 }
-                const uploaded = await mirroredBlobIds(sdkAgentId);
-                const blobIds = await listCheckpointBlobIds(store, sdkAgentId);
-                const pending = blobIds.filter((blobId) => !uploaded.has(blobId));
-                for (let start = 0; start < pending.length; start += PERSIST_UPLOAD_BATCH_SIZE) {
-                    await uploadBlobs(store, sdkAgentId, pending.slice(start, start + PERSIST_UPLOAD_BATCH_SIZE), uploaded);
+                const previous = await persistedPacks(sdkAgentId);
+                const packed = new Set(previous.flatMap((pack) => pack.blobIds));
+                const local = await listCheckpointBlobIds(store, sdkAgentId);
+                const pending = local.filter((blobId) => !packed.has(blobId));
+                let packs = previous;
+                if (pending.length > 0) {
+                    const localSet = new Set(local);
+                    const canRepack = [...packed].every((blobId) => localSet.has(blobId));
+                    if (previous.length + 1 > maxPacks && canRepack) {
+                        // The packs this replaces stay in the store: another process
+                        // holding an outdated pack list may still write a manifest that
+                        // references them, and that manifest must remain restorable.
+                        packs = await writePacks(store, sdkAgentId, local);
+                    }
+                    else {
+                        packs = [...previous, ...(await writePacks(store, sdkAgentId, pending))];
+                    }
                 }
                 const manifest = {
-                    v: 1,
+                    v: 2,
                     // The referenced run is process-local bookkeeping and is not mirrored;
                     // a hydrated store must not point at a run row it does not hold.
                     agent: { ...document, activeRunId: null },
-                    blobIds: blobIds.filter((blobId) => uploaded.has(blobId)),
+                    packs,
                     persistedAtMs: Date.now(),
                 };
                 // Skip the rewrite when nothing durable changed. `persistedAtMs`
                 // is excluded from the comparison — it differs on every call by
                 // construction and carries no restore semantics.
-                const content = JSON.stringify({
-                    agent: manifest.agent,
-                    blobIds: manifest.blobIds,
-                });
+                const content = JSON.stringify({ agent: manifest.agent, packs: manifest.packs });
                 if (lastManifestContent.get(sdkAgentId) === content) {
                     return;
                 }
                 lastManifestContent.delete(sdkAgentId);
-                // Manifest last: it only ever references blobs already uploaded.
-                await sink.put(agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId), new TextEncoder().encode(JSON.stringify(manifest)));
-                rememberManifest(sdkAgentId, content);
+                // Manifest last: it only ever references packs already uploaded.
+                try {
+                    await sink.put(agentSdkAgentStoreKeys.conversationManifest(agentName, sdkAgentId), new TextEncoder().encode(JSON.stringify(manifest)));
+                }
+                catch (error) {
+                    // A conflict means another process wrote the manifest. Re-read it
+                    // on the next persist and append to its packs rather than
+                    // overwriting them from this process's outdated list.
+                    packStates.delete(sdkAgentId);
+                    throw error;
+                }
+                rememberPacks(sdkAgentId, packs);
+                rememberBounded(lastManifestContent, sdkAgentId, content);
             });
         },
         hydrate(store, sdkAgentId) {
@@ -193,62 +200,114 @@ export function createConversationMirror(options) {
                     return false;
                 }
                 const manifest = read.manifest;
+                const listed = new Set(manifest.v === 2 ? manifest.packs.flatMap((pack) => pack.blobIds) : manifest.blobIds);
                 const rootBlobId = manifest.agent.latestCheckpoint?.rootBlobId;
-                if (rootBlobId === undefined || !manifest.blobIds.includes(rootBlobId)) {
+                if (rootBlobId === undefined || !listed.has(rootBlobId)) {
                     logger(`[bdk] conversation mirror: the manifest for ${sdkAgentId} does not list its root checkpoint blob; treating the conversation as unrestorable`);
                     return false;
                 }
-                // This sits on the resume critical path. Prefer a batched read and
-                // fall back to bounded parallel reads when the sink has no batch API.
-                const blobKeys = manifest.blobIds.map((blobId) => agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId));
-                const blobBodies = sink.getMany !== undefined
-                    ? await sink.getMany(blobKeys)
-                    : await mapBounded(blobKeys, HYDRATE_DOWNLOAD_CONCURRENCY, (key) => sink.get(key));
-                const bodies = manifest.blobIds.map((blobId, index) => ({
-                    blobId,
-                    body: blobBodies[index],
-                }));
-                const missing = bodies.filter((entry) => entry.body === undefined);
+                const blobs = manifest.v === 2
+                    ? await readPackedBlobs(sdkAgentId, manifest.packs)
+                    : await readLooseBlobs(sdkAgentId, manifest.blobIds);
+                if (blobs === undefined) {
+                    return false;
+                }
+                // The manifest lists exactly what a previous persist uploaded, so
+                // any definitive absence is store loss — and the checkpoint graph
+                // may reach any listed blob, not just the root. Restoring a partial
+                // graph would create an agent row whose resume succeeds and whose
+                // checkpoint walk then fails unrecoverably.
+                const missing = [...listed].filter((blobId) => !blobs.has(blobId));
                 if (missing.length > 0) {
-                    // The manifest lists exactly what a previous persist uploaded, so
-                    // any definitive absence is store loss — and the checkpoint graph
-                    // may reach any listed blob, not just the root. Restoring a
-                    // partial graph would create an agent row whose resume succeeds
-                    // and whose checkpoint walk then fails unrecoverably.
                     logger(`[bdk] conversation mirror: ${missing.length} checkpoint blob(s) for ${sdkAgentId} are missing from the sink; treating the conversation as unrestorable`);
                     return false;
                 }
-                const restored = new Set();
-                for (const entry of bodies) {
-                    const body = entry.body;
-                    const bytes = body instanceof Uint8Array ? body : body.body;
-                    if ((await store.checkpoints.get({
-                        agentId: sdkAgentId,
-                        blobId: entry.blobId,
-                    })) === null) {
-                        await store.checkpoints.create({
-                            agentId: sdkAgentId,
-                            blobId: entry.blobId,
-                            data: bytes,
-                        });
+                for (const [blobId, data] of blobs) {
+                    if ((await store.checkpoints.get({ agentId: sdkAgentId, blobId })) === null) {
+                        await store.checkpoints.create({ agentId: sdkAgentId, blobId, data });
                     }
-                    restored.add(entry.blobId);
                 }
                 await store.agents.create({
                     agent: { ...manifest.agent, activeRunId: null },
                 });
-                rememberMirrored(sdkAgentId, restored);
-                logger(`[bdk] conversation mirror: restored the conversation for ${sdkAgentId} (${restored.size} checkpoint blob(s))`);
+                if (manifest.v === 2) {
+                    rememberPacks(sdkAgentId, manifest.packs);
+                }
+                logger(`[bdk] conversation mirror: restored the conversation for ${sdkAgentId} (${blobs.size} checkpoint blob(s))`);
                 return true;
             });
         },
     };
+    /** This sits on the resume critical path: one batched read when the sink has one. */
+    async function readMany(keys) {
+        return sink.getMany !== undefined
+            ? await sink.getMany(keys)
+            : await mapBounded(keys, HYDRATE_DOWNLOAD_CONCURRENCY, (key) => sink.get(key));
+    }
+    /**
+     * Every blob in `packs`, or `undefined` when a pack is absent or damaged
+     * (definitive store loss: the conversation is unrestorable).
+     */
+    async function readPackedBlobs(sdkAgentId, packs) {
+        const bodies = await readMany(packs.map((pack) => agentSdkAgentStoreKeys.conversationPack(agentName, sdkAgentId, pack.id)));
+        const blobs = new Map();
+        for (const [index, pack] of packs.entries()) {
+            const body = bodies[index];
+            if (body === undefined) {
+                logger(`[bdk] conversation mirror: checkpoint pack ${pack.id} for ${sdkAgentId} is missing from the sink; treating the conversation as unrestorable`);
+                return undefined;
+            }
+            try {
+                for (const entry of decodeConversationPack(pack.id, bytesOf(body))) {
+                    blobs.set(entry.blobId, entry.data);
+                }
+            }
+            catch (error) {
+                logger(`[bdk] conversation mirror: checkpoint pack ${pack.id} for ${sdkAgentId} is unreadable (${describeError(error)}); treating the conversation as unrestorable`);
+                return undefined;
+            }
+        }
+        return blobs;
+    }
+    async function readLooseBlobs(sdkAgentId, blobIds) {
+        const bodies = await readMany(blobIds.map((blobId) => agentSdkAgentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId)));
+        const blobs = new Map();
+        for (const [index, blobId] of blobIds.entries()) {
+            const body = bodies[index];
+            if (body !== undefined) {
+                blobs.set(blobId, bytesOf(body));
+            }
+        }
+        return blobs;
+    }
 }
-/** Oldest-out cap on the per-conversation upload-dedupe cache. */
+/** Oldest-out cap on the per-conversation caches. */
 const MAX_TRACKED_CONVERSATIONS = 1_000;
-/** Parallel blob downloads during hydrate (resume critical path). */
+function rememberBounded(map, key, value) {
+    if (!map.has(key) && map.size >= MAX_TRACKED_CONVERSATIONS) {
+        const oldest = map.keys().next();
+        if (!oldest.done) {
+            map.delete(oldest.value);
+        }
+    }
+    map.set(key, value);
+}
+/** Parallel downloads during hydrate when the sink has no batched read. */
 const HYDRATE_DOWNLOAD_CONCURRENCY = 8;
-const PERSIST_UPLOAD_BATCH_SIZE = 50;
+/**
+ * Pack split size. Well under the store's single-part upload limit, and small
+ * enough that a re-pack holds little in memory at a time.
+ */
+const PACK_TARGET_BYTES = 8 * 1024 * 1024;
+/**
+ * Packs a manifest may list before the next persist re-packs the whole
+ * conversation. Bounds the reads a resume costs; a re-pack rewrites the
+ * conversation's bytes once per this many persists that add blobs.
+ */
+const MAX_PACKS = 32;
+function bytesOf(body) {
+    return body instanceof Uint8Array ? body : body.body;
+}
 /**
  * Read the persisted manifest. Sink transport failures propagate (an
  * outage must fail the follow-up, not fork the thread); everything the
@@ -259,26 +318,40 @@ async function readManifest(sink, agentName, sdkAgentId) {
     if (body === undefined) {
         return { outcome: "miss" };
     }
-    const bytes = body instanceof Uint8Array ? body : body.body;
     let parsed;
     try {
-        parsed = JSON.parse(new TextDecoder().decode(bytes));
+        parsed = JSON.parse(new TextDecoder().decode(bytesOf(body)));
     }
     catch {
         return { outcome: "unusable", reason: "not JSON" };
     }
-    if (parsed === null || typeof parsed !== "object" || parsed.v !== 1) {
+    if (parsed === null || typeof parsed !== "object") {
+        return { outcome: "unusable", reason: "malformed manifest" };
+    }
+    const version = parsed.v;
+    if (version !== 1 && version !== 2) {
         return { outcome: "unusable", reason: "unsupported manifest version" };
     }
     const manifest = parsed;
     if (manifest.agent === null ||
         typeof manifest.agent !== "object" ||
         manifest.agent.agentId !== sdkAgentId ||
-        !Array.isArray(manifest.blobIds)) {
+        !(manifest.v === 1 ? isStringArray(manifest.blobIds) : isPackRefArray(manifest.packs))) {
         return { outcome: "unusable", reason: "malformed manifest" };
     }
     return { outcome: "found", manifest };
 }
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isPackRefArray(value) {
+    return (Array.isArray(value) &&
+        value.every((item) => item !== null &&
+            typeof item === "object" &&
+            typeof item.id === "string" &&
+            /^[0-9a-f]{64}$/.test(item.id) &&
+            isStringArray(item.blobIds)));
+}
 async function listCheckpointBlobIds(store, sdkAgentId) {
     const blobIds = [];
     let cursor;

package/dist/internal/conversation-pack.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Wire format for a conversation checkpoint pack: many content-addressed
+ * checkpoint blobs in one durable object, so a turn's new blobs cost one
+ * store write instead of one per blob.
+ *
+ * Layout (big-endian): the 8-byte magic, a u32 entry count, then per entry a
+ * u16 blob-id length, the UTF-8 blob id, a u32 data length and the data. The
+ * pack id is the SHA-256 of the whole encoding, so a pack is immutable and
+ * a re-upload after a failed persist lands on the same key.
+ */
+export interface ConversationPackEntry {
+    blobId: string;
+    data: Uint8Array;
+}
+export interface EncodedConversationPack {
+    packId: string;
+    body: Uint8Array;
+}
+/** Bytes an entry adds to a pack; used to split packs before encoding. */
+export declare function conversationPackEntrySize(entry: ConversationPackEntry): number;
+export declare function conversationPackId(body: Uint8Array): string;
+export declare function encodeConversationPack(entries: readonly ConversationPackEntry[]): EncodedConversationPack;
+/**
+ * Decode a pack read back from the store. Throws on any structural damage or
+ * when the bytes do not hash to `packId`; the caller treats that exactly like
+ * a missing pack.
+ */
+export declare function decodeConversationPack(packId: string, body: Uint8Array): ConversationPackEntry[];
+//# sourceMappingURL=conversation-pack.d.ts.map

package/dist/internal/conversation-pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-pack.d.ts","sourceRoot":"","sources":["../../src/internal/conversation-pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;CAClB;AAMD,0EAA0E;AAC1E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAE9E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAE3D;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,SAAS,qBAAqB,EAAE,GACxC,uBAAuB,CAgCzB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,qBAAqB,EAAE,CAoChG"}

package/dist/internal/conversation-pack.js

@@ -0,0 +1,96 @@
+/**
+ * Wire format for a conversation checkpoint pack: many content-addressed
+ * checkpoint blobs in one durable object, so a turn's new blobs cost one
+ * store write instead of one per blob.
+ *
+ * Layout (big-endian): the 8-byte magic, a u32 entry count, then per entry a
+ * u16 blob-id length, the UTF-8 blob id, a u32 data length and the data. The
+ * pack id is the SHA-256 of the whole encoding, so a pack is immutable and
+ * a re-upload after a failed persist lands on the same key.
+ */
+import { createHash } from "node:crypto";
+const MAGIC = new TextEncoder().encode("BDKCPK1\n");
+const MAX_BLOB_ID_BYTES = 0xffff;
+const MAX_ENTRY_BYTES = 0xffffffff;
+/** Bytes an entry adds to a pack; used to split packs before encoding. */
+export function conversationPackEntrySize(entry) {
+    return 2 + new TextEncoder().encode(entry.blobId).length + 4 + entry.data.length;
+}
+export function conversationPackId(body) {
+    return createHash("sha256").update(body).digest("hex");
+}
+export function encodeConversationPack(entries) {
+    const encoder = new TextEncoder();
+    const ids = entries.map((entry) => encoder.encode(entry.blobId));
+    let size = MAGIC.length + 4;
+    for (const [index, entry] of entries.entries()) {
+        const id = ids[index];
+        if (id.length === 0 || id.length > MAX_BLOB_ID_BYTES) {
+            throw new Error(`conversation pack: blob id "${entry.blobId}" has an unencodable length`);
+        }
+        if (entry.data.length > MAX_ENTRY_BYTES) {
+            throw new Error(`conversation pack: blob "${entry.blobId}" is too large to pack`);
+        }
+        size += 2 + id.length + 4 + entry.data.length;
+    }
+    const body = new Uint8Array(size);
+    const view = new DataView(body.buffer);
+    body.set(MAGIC, 0);
+    let offset = MAGIC.length;
+    view.setUint32(offset, entries.length);
+    offset += 4;
+    for (const [index, entry] of entries.entries()) {
+        const id = ids[index];
+        view.setUint16(offset, id.length);
+        offset += 2;
+        body.set(id, offset);
+        offset += id.length;
+        view.setUint32(offset, entry.data.length);
+        offset += 4;
+        body.set(entry.data, offset);
+        offset += entry.data.length;
+    }
+    return { packId: conversationPackId(body), body };
+}
+/**
+ * Decode a pack read back from the store. Throws on any structural damage or
+ * when the bytes do not hash to `packId`; the caller treats that exactly like
+ * a missing pack.
+ */
+export function decodeConversationPack(packId, body) {
+    if (conversationPackId(body) !== packId) {
+        throw new Error("conversation pack: content does not match its id");
+    }
+    if (body.length < MAGIC.length + 4 || MAGIC.some((byte, index) => body[index] !== byte)) {
+        throw new Error("conversation pack: unrecognized format");
+    }
+    const view = new DataView(body.buffer, body.byteOffset, body.byteLength);
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let offset = MAGIC.length;
+    const count = view.getUint32(offset);
+    offset += 4;
+    const entries = [];
+    const need = (bytes) => {
+        if (offset + bytes > body.length) {
+            throw new Error("conversation pack: truncated");
+        }
+    };
+    for (let index = 0; index < count; index++) {
+        need(2);
+        const idLength = view.getUint16(offset);
+        offset += 2;
+        need(idLength);
+        const blobId = decoder.decode(body.subarray(offset, offset + idLength));
+        offset += idLength;
+        need(4);
+        const dataLength = view.getUint32(offset);
+        offset += 4;
+        need(dataLength);
+        entries.push({ blobId, data: body.slice(offset, offset + dataLength) });
+        offset += dataLength;
+    }
+    if (offset !== body.length) {
+        throw new Error("conversation pack: trailing bytes");
+    }
+    return entries;
+}

package/dist/internal/deploy-client.d.ts

@@ -355,6 +355,8 @@ export declare class AgentServeDeployClient {
         persistent?: boolean;
         /** Single-agent `hosting.image`; components carry their own. */
         image?: string;
+        /** `init --template` scaffold name, reported for deploy analytics. */
+        template?: string;
     }): Promise<AgentkitDeployAccepted>;
     getAgentkitDeploy(args: {
         teamId: number;