@cursor/bdk 0.2.2 → 0.2.4

package/src/storage-backends/file-kv.ts

@@ -1,276 +0,0 @@
-/**
- * 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.
- */
-
-import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { isAbsolute, join } from "node:path";
-import type { EvalRunSnapshot } from "../evals.js";
-import type {
-  StorageCasTable,
-  StorageConfig,
-  StorageContext,
-  StorageEntry,
-  StorageEvalsTable,
-} from "../storage.js";
-import type { JsonValue, KvVersionedEntry } from "../types.js";
-
-export interface FileKvOptions {
-  /**
-   * Directory holding the storage files, relative to the agent project root
-   * (default `".agent-serve/kv"`). Absolute paths are used as-is.
-   */
-  dir?: string;
-}
-
-type FileKvMethods = Required<Pick<StorageConfig, "put" | "get" | "delete" | "list">> & {
-  cas: StorageCasTable;
-  evals: StorageEvalsTable;
-};
-
-/** File-backed `defineStorage` methods, ready to spread into `defineStorage({...})`. */
-export function fileKv(options?: FileKvOptions): FileKvMethods {
-  const resolveDir = (ctx: StorageContext): string => {
-    const dir = options?.dir ?? ".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: StorageContext): string =>
-    join(resolveDir(ctx), "eval-runs", encodeURIComponent(ctx.agentName));
-  const filePath = (ctx: StorageContext, key: string): string =>
-    join(resolveDir(ctx), `${encodeURIComponent(key)}.json`);
-  const readRaw = async (ctx: StorageContext, key: string): Promise<string | undefined> => {
-    try {
-      return await readFile(filePath(ctx, key), "utf8");
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return undefined; // definitive miss — key was never written
-      }
-      throw error; // real failure: let lazy restore fail the follow-up
-    }
-  };
-  const readKey = async (ctx: StorageContext, key: string): Promise<JsonValue | undefined> => {
-    const text = await readRaw(ctx, key);
-    return text === undefined ? undefined : (JSON.parse(text) as JsonValue);
-  };
-  const readVersioned = async (
-    ctx: StorageContext,
-    key: string,
-  ): Promise<KvVersionedEntry | undefined> => {
-    const text = await readRaw(ctx, key);
-    if (text === undefined) {
-      return undefined;
-    }
-    return { value: JSON.parse(text) as JsonValue, 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<unknown> = Promise.resolve();
-  const locked = <T>(task: () => Promise<T>): Promise<T> => {
-    const result = casChain.then(task, task);
-    casChain = result.then(
-      () => undefined,
-      () => undefined,
-    );
-    return result;
-  };
-
-  return {
-    async put(key, value, ctx): Promise<void> {
-      await writeJsonAtomic({
-        dir: resolveDir(ctx),
-        fileName: `${encodeURIComponent(key)}.json`,
-        value,
-      });
-    },
-
-    get(key, ctx): Promise<JsonValue | undefined> {
-      return readKey(ctx, key);
-    },
-
-    async delete(key, ctx): Promise<void> {
-      await rm(filePath(ctx, key), { force: true });
-    },
-
-    async list(prefix, ctx): Promise<StorageEntry[]> {
-      let names: string[];
-      try {
-        names = await readdir(resolveDir(ctx));
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).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: StorageEntry[] = [];
-      for (const key of keys) {
-        const value = await 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): Promise<KvVersionedEntry | undefined> => readVersioned(ctx, key),
-
-      putIfAbsent: (key, value, ctx) =>
-        locked(async () => {
-          const current = await readVersioned(ctx, key);
-          if (current !== undefined) {
-            return { ok: false, current };
-          }
-          const text = JSON.stringify(value);
-          await writeTextAtomic({
-            dir: resolveDir(ctx),
-            fileName: `${encodeURIComponent(key)}.json`,
-            text,
-          });
-          return { ok: true, version: versionOf(text) };
-        }),
-
-      putIfVersion: (key, value, expectedVersion, ctx) =>
-        locked(async () => {
-          const current = await readVersioned(ctx, key);
-          if (current === undefined || current.version !== expectedVersion) {
-            return { ok: false, current };
-          }
-          const text = JSON.stringify(value);
-          await writeTextAtomic({
-            dir: resolveDir(ctx),
-            fileName: `${encodeURIComponent(key)}.json`,
-            text,
-          });
-          return { ok: true, version: versionOf(text) };
-        }),
-
-      async listKeys(prefix, ctx): Promise<string[]> {
-        let names: string[];
-        try {
-          names = await readdir(resolveDir(ctx));
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).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: {
-      async put(run, ctx): Promise<void> {
-        await writeJsonAtomic({
-          dir: evalRunsDir(ctx),
-          fileName: `${encodeURIComponent(run.runId)}.json`,
-          value: run,
-        });
-      },
-      async delete(runId, ctx): Promise<void> {
-        await rm(join(evalRunsDir(ctx), `${encodeURIComponent(runId)}.json`), {
-          force: true,
-        });
-      },
-      async list(ctx): Promise<EvalRunSnapshot[]> {
-        const dir = evalRunsDir(ctx);
-        let names: string[];
-        try {
-          names = await readdir(dir);
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-            return [];
-          }
-          throw error;
-        }
-        const runs: EvalRunSnapshot[] = [];
-        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(await readFile(join(dir, name), "utf8")) as EvalRunSnapshot);
-          } catch {}
-        }
-        return runs;
-      },
-    },
-  };
-}
-
-/** Content-hash version token for a stored JSON text. */
-function versionOf(text: string): string {
-  return `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
-}
-
-/** tmp + rename write so concurrent readers never see a torn file. */
-async function writeJsonAtomic(args: {
-  dir: string;
-  fileName: string;
-  value: unknown;
-}): Promise<void> {
-  await 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). */
-async function writeTextAtomic(args: {
-  dir: string;
-  fileName: string;
-  text: string;
-}): Promise<void> {
-  await mkdir(args.dir, { recursive: true });
-  const tmp = join(args.dir, `.tmp-${randomUUID()}`);
-  await writeFile(tmp, args.text, "utf8");
-  await rename(tmp, join(args.dir, args.fileName));
-}

package/src/storage-protocol.ts

@@ -1,261 +0,0 @@
-/**
- * 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" as const;
-
-/**
- * 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" as const;
-
-/**
- * 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: string) {
-  return {
-    session: (agent: string, sessionId: string): string => `${root}/${agent}/session/${sessionId}`,
-    sessionPrefix: (agent: string): string => `${root}/${agent}/session/`,
-    sessionEvents: (agent: string, sessionId: string, firstIndex: number): string =>
-      `${root}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
-    sessionEventsPrefix: (agent: string, sessionId: string): string =>
-      `${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: string, sessionPublicId: string): string =>
-      `${root}/${agent}/session-runs/${keySegment(sessionPublicId)}`,
-    sessionRunsPrefix: (agent: string): string => `${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: string, logId: string): string => `${root}/${agent}/logs/${keySegment(logId)}`,
-    logsPrefix: (agent: string): string => `${root}/${agent}/logs/`,
-    continuation: (agent: string, channelId: string, continuationKey: string): string =>
-      `${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: string, key: string): string => `${root}/${agent}/kv/${keySegment(key)}`,
-    kvPrefix: (agent: string): string => `${root}/${agent}/kv/`,
-    /** One playground eval-run snapshot (derived `evals` table). */
-    evalRun: (agent: string, runId: string): string =>
-      `${root}/${agent}/eval-runs/${keySegment(runId)}`,
-    evalRunsPrefix: (agent: string): string => `${root}/${agent}/eval-runs/`,
-  } as const;
-}
-
-export type StorageKeys = ReturnType<typeof createStorageKeys>;
-
-/** Architecture-v1 keys. Kept stable for existing deployments. */
-export const storageKeys: StorageKeys = createStorageKeys(STORAGE_KEY_ROOT);
-
-/** Architecture-v2 keys. Hard cutoff onto {@link AGENTSDK_STORAGE_KEY_ROOT}. */
-export const agentSdkStorageKeys: StorageKeys = createStorageKeys(AGENTSDK_STORAGE_KEY_ROOT);
-
-export function storageKeysForArchitecture(architecture: "v1" | "v2" | undefined): StorageKeys {
-  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: {
-  sessionPublicId?: string | null;
-  workflowId?: string | null;
-  runId?: string | null;
-}): string | undefined {
-  const sessionPublicId = args.sessionPublicId?.trim() ?? "";
-  if (sessionPublicId.length > 0) {
-    return sessionPublicId;
-  }
-  const workflowId = args.workflowId?.trim() ?? "";
-  if (workflowId.length === 0) {
-    return undefined;
-  }
-  const runId = args.runId?.trim() ?? "";
-  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: string): string {
-  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: string): boolean {
-  const match = DURABLE_SESSION_RECORD_KEY_RE.exec(key);
-  return match !== null && match[2] !== "_cp";
-}
-
-/** 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;
-};
-
-function stringValue(value: unknown): string | undefined {
-  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: unknown): DurableSessionRecord | undefined {
-  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: {
-  record: DurableSessionRecord;
-  running?: boolean;
-}): DurableSessionSummary {
-  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: Record<string, unknown> = {
-  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 },
-};