@cursor/bdk 0.2.1

package/dist/storage-backends/file-kv.js

@@ -0,0 +1,254 @@
+/**
+ * File-backed `defineStorage` helper: a file-per-key KV store plus a
+ * file-backed `evals` table.
+ *
+ * Implements the whole `defineStorage` surface with zero external
+ * dependencies: the four KV methods against a flat directory of JSON files
+ * (one file per key, filename = URI-encoded key), the `cas`
+ * group (single-process conditional writes — see the `cas` member below),
+ * and eval runs as `eval-runs/<agent>/<runId>.json`. KV keys carry the
+ * agent name inside the framework key scheme, but the evals table has no
+ * such scheme — the agent subdirectory keeps agents sharing one storage
+ * `dir` from mixing or overwriting each other's history. Swap this for a
+ * real backend (Postgres, S3, …) in production; the contracts are
+ * identical.
+ *
+ * Layout notes:
+ * - KV filenames encode the full key (`encodeURIComponent(key) + ".json"`),
+ *   so `list(prefix)` is a readdir + decode + filter, returned in key
+ *   order as the contract requires.
+ * - `put` writes via tmp + rename: the framework serializes writes, but a
+ *   restore-path `get`/`list` can run concurrently and must never see a
+ *   torn file.
+ * - `get` distinguishes a definitive miss (ENOENT → `undefined`) from a
+ *   real failure (anything else throws) — on the lazy-restore path a
+ *   throw correctly fails the follow-up instead of forking the session.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+/** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
+export function fileKv(options) {
+    const resolveDir = (ctx) => {
+        var _a;
+        const dir = (_a = options === null || options === void 0 ? void 0 : options.dir) !== null && _a !== void 0 ? _a : ".agent-serve/kv";
+        return isAbsolute(dir) ? dir : join(ctx.projectRoot, dir);
+    };
+    // The evals table is scoped per agent (KV keys already carry the agent
+    // name via the framework key scheme).
+    const evalRunsDir = (ctx) => join(resolveDir(ctx), "eval-runs", encodeURIComponent(ctx.agentName));
+    const filePath = (ctx, key) => join(resolveDir(ctx), `${encodeURIComponent(key)}.json`);
+    const readRaw = (ctx, key) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            return yield readFile(filePath(ctx, key), "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return undefined; // definitive miss — key was never written
+            }
+            throw error; // real failure: let lazy restore fail the follow-up
+        }
+    });
+    const readKey = (ctx, key) => __awaiter(this, void 0, void 0, function* () {
+        const text = yield readRaw(ctx, key);
+        return text === undefined ? undefined : JSON.parse(text);
+    });
+    const readVersioned = (ctx, key) => __awaiter(this, void 0, void 0, function* () {
+        const text = yield readRaw(ctx, key);
+        if (text === undefined) {
+            return undefined;
+        }
+        return { value: JSON.parse(text), version: versionOf(text) };
+    });
+    // In-process mutex: CAS check-then-write pairs queue on one promise
+    // chain so they cannot interleave with each other. Plain `put` stays
+    // outside the chain on purpose — it is unconditional LWW and always
+    // wins the key, like a SQL upsert would win the row.
+    let casChain = Promise.resolve();
+    const locked = (task) => {
+        const result = casChain.then(task, task);
+        casChain = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    return {
+        put(key, value, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield writeJsonAtomic({
+                    dir: resolveDir(ctx),
+                    fileName: `${encodeURIComponent(key)}.json`,
+                    value,
+                });
+            });
+        },
+        get(key, ctx) {
+            return readKey(ctx, key);
+        },
+        delete(key, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield rm(filePath(ctx, key), { force: true });
+            });
+        },
+        list(prefix, ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                let names;
+                try {
+                    names = yield readdir(resolveDir(ctx));
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        return []; // nothing stored yet
+                    }
+                    throw error;
+                }
+                const keys = names
+                    .filter(name => name.endsWith(".json"))
+                    .map(name => decodeURIComponent(name.slice(0, -".json".length)))
+                    .filter(key => key.startsWith(prefix))
+                    .sort();
+                const entries = [];
+                for (const key of keys) {
+                    const value = yield readKey(ctx, key);
+                    if (value !== undefined) {
+                        entries.push({ key, value });
+                    }
+                }
+                return entries;
+            });
+        },
+        // Conditional writes over the same raw value files — no on-disk format
+        // change, so data written before the CAS group existed stays readable
+        // and plain `put` stays byte-identical. The version token is a content
+        // hash of the stored JSON text: it changes whenever the value does,
+        // and the in-process mutex makes read-check-write atomic, so a token
+        // can never go stale between the check and the rename. The one caveat
+        // of hash versions — ABA when a value returns to identical bytes — is
+        // moot for coordination values that carry a monotonic counter. CAS
+        // correctness is **single-process only**: two pods sharing this
+        // directory would race between read and rename, so a file store is
+        // only safe for single-instance deployments.
+        cas: {
+            getWithVersion: (key, ctx) => readVersioned(ctx, key),
+            putIfAbsent: (key, value, ctx) => locked(() => __awaiter(this, void 0, void 0, function* () {
+                const current = yield readVersioned(ctx, key);
+                if (current !== undefined) {
+                    return { ok: false, current };
+                }
+                const text = JSON.stringify(value);
+                yield writeTextAtomic({
+                    dir: resolveDir(ctx),
+                    fileName: `${encodeURIComponent(key)}.json`,
+                    text,
+                });
+                return { ok: true, version: versionOf(text) };
+            })),
+            putIfVersion: (key, value, expectedVersion, ctx) => locked(() => __awaiter(this, void 0, void 0, function* () {
+                const current = yield readVersioned(ctx, key);
+                if (current === undefined || current.version !== expectedVersion) {
+                    return { ok: false, current };
+                }
+                const text = JSON.stringify(value);
+                yield writeTextAtomic({
+                    dir: resolveDir(ctx),
+                    fileName: `${encodeURIComponent(key)}.json`,
+                    text,
+                });
+                return { ok: true, version: versionOf(text) };
+            })),
+            listKeys(prefix, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    let names;
+                    try {
+                        names = yield readdir(resolveDir(ctx));
+                    }
+                    catch (error) {
+                        if (error.code === "ENOENT") {
+                            return [];
+                        }
+                        throw error;
+                    }
+                    return names
+                        .filter(name => name.endsWith(".json"))
+                        .map(name => decodeURIComponent(name.slice(0, -".json".length)))
+                        .filter(key => key.startsWith(prefix))
+                        .sort();
+                });
+            },
+        },
+        // Playground eval batches: one JSON file per run under eval-runs/<agent>/.
+        evals: {
+            put(run, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield writeJsonAtomic({
+                        dir: evalRunsDir(ctx),
+                        fileName: `${encodeURIComponent(run.runId)}.json`,
+                        value: run,
+                    });
+                });
+            },
+            delete(runId, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    yield rm(join(evalRunsDir(ctx), `${encodeURIComponent(runId)}.json`), {
+                        force: true,
+                    });
+                });
+            },
+            list(ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    const dir = evalRunsDir(ctx);
+                    let names;
+                    try {
+                        names = yield readdir(dir);
+                    }
+                    catch (error) {
+                        if (error.code === "ENOENT") {
+                            return [];
+                        }
+                        throw error;
+                    }
+                    const runs = [];
+                    for (const name of names.filter(n => n.endsWith(".json")).sort()) {
+                        // One unreadable/corrupt file must not wipe the whole history:
+                        // hydrate treats a throwing list() as "nothing saved".
+                        try {
+                            runs.push(JSON.parse(yield readFile(join(dir, name), "utf8")));
+                        }
+                        catch (_a) { }
+                    }
+                    return runs;
+                });
+            },
+        },
+    };
+}
+/** Content-hash version token for a stored JSON text. */
+function versionOf(text) {
+    return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+}
+/** tmp + rename write so concurrent readers never see a torn file. */
+function writeJsonAtomic(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield writeTextAtomic({
+            dir: args.dir,
+            fileName: args.fileName,
+            text: JSON.stringify(args.value),
+        });
+    });
+}
+/** tmp + rename write of exact text (CAS hashes the same bytes it wrote). */
+function writeTextAtomic(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield mkdir(args.dir, { recursive: true });
+        const tmp = join(args.dir, `.tmp-${randomUUID()}`);
+        yield writeFile(tmp, args.text, "utf8");
+        yield rename(tmp, join(args.dir, args.fileName));
+    });
+}

package/dist/storage-protocol.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Durable session KV contract: key families plus a tolerant SessionRecord
+ * decoder. Architecture v1 remains in lockstep with the Bugbot-backed control
+ * plane. Architecture v2 uses the same key shape under its AgentSDK root.
+ *
+ * Additive JSON only — unknown fields are ignored.
+ */
+/** Legacy architecture-v1 storage root. */
+export declare const STORAGE_KEY_ROOT: "agentkit/v1";
+/**
+ * Architecture-v2 storage root. Hard cutoff: v2 writes and reads this
+ * prefix only. Existing `agentkit/v1` v2 objects are not migrated.
+ */
+export declare const AGENTSDK_STORAGE_KEY_ROOT: "agentsdk/v1";
+/**
+ * Build the framework-owned key scheme under one versioned root. Channel ids
+ * and continuation tokens are URI-encoded, and oversized segments are
+ * replaced by a deterministic `sha256:…` digest.
+ *
+ * | Key | Value |
+ * | --- | --- |
+ * | `{root}/{agent}/session/{sessionId}` | `SessionRecord` |
+ * | `{root}/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `{root}/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
+ * | `{root}/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
+ * | `{root}/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `{root}/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
+ *
+ * The `eval-runs` family is minted only by the table `defineStorage`
+ * derives over the KV core; a backend that authors a dedicated
+ * `StorageConfig.evals` group never sees it.
+ */
+declare function createStorageKeys(root: string): {
+    readonly session: (agent: string, sessionId: string) => string;
+    readonly sessionPrefix: (agent: string) => string;
+    readonly sessionEvents: (agent: string, sessionId: string, firstIndex: number) => string;
+    readonly sessionEventsPrefix: (agent: string, sessionId: string) => string;
+    /**
+     * One session-level hosted-execution log (v2 only). `sessionPublicId` is
+     * the factory `ses_…` so a throw that never minted a July session still
+     * lands under a stable key. Per-execution rows live inside the document.
+     */
+    readonly sessionRun: (agent: string, sessionPublicId: string) => string;
+    readonly sessionRunsPrefix: (agent: string) => string;
+    /**
+     * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
+     * `logId` is the factory `ses_…` after a `send`, or
+     * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
+     * before a session exists. Skip/task admissions do not write this key.
+     * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
+     * objects, and this key is flushed in snapshots, not per line.
+     */
+    readonly log: (agent: string, logId: string) => string;
+    readonly logsPrefix: (agent: string) => string;
+    readonly continuation: (agent: string, channelId: string, continuationKey: string) => string;
+    /**
+     * Author-facing opaque JSON (see `HostContext.kv`). `key` is URI-encoded /
+     * digested like other caller-controlled segments.
+     */
+    readonly kv: (agent: string, key: string) => string;
+    readonly kvPrefix: (agent: string) => string;
+    /** One playground eval-run snapshot (derived `evals` table). */
+    readonly evalRun: (agent: string, runId: string) => string;
+    readonly evalRunsPrefix: (agent: string) => string;
+};
+export type StorageKeys = ReturnType<typeof createStorageKeys>;
+/** Architecture-v1 keys. Kept stable for existing deployments. */
+export declare const storageKeys: StorageKeys;
+/** Architecture-v2 keys. Hard cutoff onto {@link AGENTSDK_STORAGE_KEY_ROOT}. */
+export declare const agentSdkStorageKeys: StorageKeys;
+export declare function storageKeysForArchitecture(architecture: "v1" | "v2" | undefined): StorageKeys;
+/**
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
+ * Chosen so full keys stay well under common backend limits (Postgres btree
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
+ */
+export declare const MAX_KEY_SEGMENT_BYTES = 256;
+/**
+ * Stable start-log object id. A `send` attaches to the factory session
+ * so the factory/dashboard session-runs read can see it. Admission that
+ * fails before a session exists is keyed on the Temporal workflow run
+ * (`wf:{workflowId}` or `wf:{workflowId}/{runId}`) so the object joins
+ * the Temporal UI. A successful skip/task writes nothing — there is no
+ * customer log.
+ */
+export declare function frameworkStartLogId(args: {
+    sessionPublicId?: string | null;
+    workflowId?: string | null;
+    runId?: string | null;
+}): string | undefined;
+/**
+ * URI-encode one caller-controlled key segment, substituting a `sha256:…`
+ * digest of the raw value when the encoding exceeds
+ * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
+ * write path and the continuation-lookup path always agree.
+ */
+export declare function keySegment(raw: string): string;
+export declare function isDurableSessionRecordKey(key: string): boolean;
+/** List fields of a persisted `SessionRecord`. Unknown properties are dropped. */
+export type DurableSessionRecord = {
+    sessionId: string;
+    channelId: string;
+    mode: string;
+    continuationKey: string | null | undefined;
+    title: string | undefined;
+    turnCount: number;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * Session metadata for history UIs. `running` is omitted unless a live
+ * overlay (the engine process) supplies it — a KV-only reader must not
+ * claim a turn is in flight.
+ */
+export type DurableSessionSummary = {
+    sessionId: string;
+    channelId: string;
+    mode: string;
+    title: string | undefined;
+    turnCount: number;
+    createdAt: string;
+    updatedAt: string;
+    running: boolean | undefined;
+};
+/**
+ * Tolerant `SessionRecord` decoder. Extra fields (`auth`, `purpose`,
+ * future keys) are ignored. Returns undefined when required list
+ * fields are missing or the wrong type.
+ */
+export declare function parseDurableSessionRecord(value: unknown): DurableSessionRecord | undefined;
+export declare function summarizeDurableSessionRecord(args: {
+    record: DurableSessionRecord;
+    running?: boolean;
+}): DurableSessionSummary;
+/**
+ * Golden persisted record: required list fields plus extras a future engine
+ * might write. Both this package and the CP decoder must accept it.
+ */
+export declare const GOLDEN_DURABLE_SESSION_RECORD: Record<string, unknown>;
+export {};
+//# sourceMappingURL=storage-protocol.d.ts.map

package/dist/storage-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-protocol.d.ts","sourceRoot":"","sources":["../src/storage-protocol.ts"],"names":[],"mappings":"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"}

package/dist/storage-protocol.js

@@ -0,0 +1,201 @@
+/**
+ * Durable session KV contract: key families plus a tolerant SessionRecord
+ * decoder. Architecture v1 remains in lockstep with the Bugbot-backed control
+ * plane. Architecture v2 uses the same key shape under its AgentSDK root.
+ *
+ * Additive JSON only — unknown fields are ignored.
+ */
+import { createHash } from "node:crypto";
+import { isRecord } from "./internal/is-record.js";
+/** Legacy architecture-v1 storage root. */
+export const STORAGE_KEY_ROOT = "agentkit/v1";
+/**
+ * Architecture-v2 storage root. Hard cutoff: v2 writes and reads this
+ * prefix only. Existing `agentkit/v1` v2 objects are not migrated.
+ */
+export const AGENTSDK_STORAGE_KEY_ROOT = "agentsdk/v1";
+/**
+ * Exact session-record keys: `{agentkit|agentsdk}/v1/{agent}/session/{sessionId}`.
+ * Rejects `session-events/` and the CP-owned `_cp` agent name.
+ */
+const DURABLE_SESSION_RECORD_KEY_RE = /^(agentkit|agentsdk)\/v1\/([^/]+)\/session\/([^/]+)$/;
+/**
+ * Build the framework-owned key scheme under one versioned root. Channel ids
+ * and continuation tokens are URI-encoded, and oversized segments are
+ * replaced by a deterministic `sha256:…` digest.
+ *
+ * | Key | Value |
+ * | --- | --- |
+ * | `{root}/{agent}/session/{sessionId}` | `SessionRecord` |
+ * | `{root}/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `{root}/{agent}/session-runs/{sessionPublicId}` | One session-level hosted-execution log (executions[] + lastFailure) |
+ * | `{root}/{agent}/logs/{logId}` | Hosted engine stdout/stderr tee (on-disk `start.log`; `ses_…` after send, `wf:{workflowId}` on admission failure) |
+ * | `{root}/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `{root}/{agent}/kv/{key}` | Author JSON via `HostContext.kv` |
+ *
+ * The `eval-runs` family is minted only by the table `defineStorage`
+ * derives over the KV core; a backend that authors a dedicated
+ * `StorageConfig.evals` group never sees it.
+ */
+function createStorageKeys(root) {
+    return {
+        session: (agent, sessionId) => `${root}/${agent}/session/${sessionId}`,
+        sessionPrefix: (agent) => `${root}/${agent}/session/`,
+        sessionEvents: (agent, sessionId, firstIndex) => `${root}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
+        sessionEventsPrefix: (agent, sessionId) => `${root}/${agent}/session-events/${sessionId}/`,
+        /**
+         * One session-level hosted-execution log (v2 only). `sessionPublicId` is
+         * the factory `ses_…` so a throw that never minted a July session still
+         * lands under a stable key. Per-execution rows live inside the document.
+         */
+        sessionRun: (agent, sessionPublicId) => `${root}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
+        sessionRunsPrefix: (agent) => `${root}/${agent}/session-runs/`,
+        /**
+         * The v2 customer log: the engine stdout/stderr tee (on-disk `start.log`).
+         * `logId` is the factory `ses_…` after a `send`, or
+         * `wf:{workflowId}` / `wf:{workflowId}/{runId}` when admission fails
+         * before a session exists. Skip/task admissions do not write this key.
+         * Stored as raw UTF-8, not JSON — the file store accepts 64 MiB
+         * objects, and this key is flushed in snapshots, not per line.
+         */
+        log: (agent, logId) => `${root}/${agent}/logs/${keySegment(logId)}`,
+        logsPrefix: (agent) => `${root}/${agent}/logs/`,
+        continuation: (agent, channelId, continuationKey) => `${root}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
+        /**
+         * Author-facing opaque JSON (see `HostContext.kv`). `key` is URI-encoded /
+         * digested like other caller-controlled segments.
+         */
+        kv: (agent, key) => `${root}/${agent}/kv/${keySegment(key)}`,
+        kvPrefix: (agent) => `${root}/${agent}/kv/`,
+        /** One playground eval-run snapshot (derived `evals` table). */
+        evalRun: (agent, runId) => `${root}/${agent}/eval-runs/${keySegment(runId)}`,
+        evalRunsPrefix: (agent) => `${root}/${agent}/eval-runs/`,
+    };
+}
+/** Architecture-v1 keys. Kept stable for existing deployments. */
+export const storageKeys = createStorageKeys(STORAGE_KEY_ROOT);
+/** Architecture-v2 keys. Hard cutoff onto {@link AGENTSDK_STORAGE_KEY_ROOT}. */
+export const agentSdkStorageKeys = createStorageKeys(AGENTSDK_STORAGE_KEY_ROOT);
+export function storageKeysForArchitecture(architecture) {
+    return architecture === "v2" ? agentSdkStorageKeys : storageKeys;
+}
+/**
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
+ * Chosen so full keys stay well under common backend limits (Postgres btree
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
+ */
+export const MAX_KEY_SEGMENT_BYTES = 256;
+/**
+ * Stable start-log object id. A `send` attaches to the factory session
+ * so the factory/dashboard session-runs read can see it. Admission that
+ * fails before a session exists is keyed on the Temporal workflow run
+ * (`wf:{workflowId}` or `wf:{workflowId}/{runId}`) so the object joins
+ * the Temporal UI. A successful skip/task writes nothing — there is no
+ * customer log.
+ */
+export function frameworkStartLogId(args) {
+    var _a, _b, _c;
+    var _d, _e, _f;
+    const sessionPublicId = (_d = (_a = args.sessionPublicId) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _d !== void 0 ? _d : "";
+    if (sessionPublicId.length > 0) {
+        return sessionPublicId;
+    }
+    const workflowId = (_e = (_b = args.workflowId) === null || _b === void 0 ? void 0 : _b.trim()) !== null && _e !== void 0 ? _e : "";
+    if (workflowId.length === 0) {
+        return undefined;
+    }
+    const runId = (_f = (_c = args.runId) === null || _c === void 0 ? void 0 : _c.trim()) !== null && _f !== void 0 ? _f : "";
+    return runId.length > 0 ? `wf:${workflowId}/${runId}` : `wf:${workflowId}`;
+}
+/**
+ * URI-encode one caller-controlled key segment, substituting a `sha256:…`
+ * digest of the raw value when the encoding exceeds
+ * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
+ * write path and the continuation-lookup path always agree.
+ */
+export function keySegment(raw) {
+    const encoded = encodeURIComponent(raw);
+    if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
+        return encoded;
+    }
+    return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+}
+export function isDurableSessionRecordKey(key) {
+    const match = DURABLE_SESSION_RECORD_KEY_RE.exec(key);
+    return match !== null && match[2] !== "_cp";
+}
+function stringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * Tolerant `SessionRecord` decoder. Extra fields (`auth`, `purpose`,
+ * future keys) are ignored. Returns undefined when required list
+ * fields are missing or the wrong type.
+ */
+export function parseDurableSessionRecord(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const sessionId = stringValue(value.sessionId);
+    const channelId = stringValue(value.channelId);
+    const mode = stringValue(value.mode);
+    const turnCount = typeof value.turnCount === "number" ? value.turnCount : undefined;
+    const createdAt = stringValue(value.createdAt);
+    const updatedAt = stringValue(value.updatedAt);
+    if (sessionId === undefined ||
+        sessionId.length === 0 ||
+        channelId === undefined ||
+        mode === undefined ||
+        turnCount === undefined ||
+        createdAt === undefined ||
+        updatedAt === undefined) {
+        return undefined;
+    }
+    if (value.continuationKey !== undefined &&
+        value.continuationKey !== null &&
+        typeof value.continuationKey !== "string") {
+        return undefined;
+    }
+    const continuationKey = value.continuationKey;
+    return {
+        sessionId,
+        channelId,
+        mode,
+        continuationKey,
+        title: typeof value.title === "string" ? value.title : undefined,
+        turnCount,
+        createdAt,
+        updatedAt,
+    };
+}
+export function summarizeDurableSessionRecord(args) {
+    const { record, running } = args;
+    return {
+        sessionId: record.sessionId,
+        channelId: record.channelId,
+        mode: record.mode,
+        title: record.title,
+        turnCount: record.turnCount,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        running,
+    };
+}
+/**
+ * Golden persisted record: required list fields plus extras a future engine
+ * might write. Both this package and the CP decoder must accept it.
+ */
+export const GOLDEN_DURABLE_SESSION_RECORD = {
+    sessionId: "ses_aaaaaaaaaaaaaaaaaaaaaaaa",
+    channelId: "playground",
+    mode: "chat",
+    purpose: "live",
+    continuationKey: "cont_key_1",
+    auth: { kind: "user", userId: 42 },
+    title: "Weather in NYC",
+    turnCount: 3,
+    createdAt: "2026-08-01T12:00:00.000Z",
+    updatedAt: "2026-08-01T12:05:00.000Z",
+    extraUnknownField: { nested: true },
+};