@cursor/bdk 0.2.3 → 0.2.5

package/src/files-backends/local-fs.ts

@@ -1,163 +0,0 @@
-/**
- * Local-disk file sink: one file per key under a directory you own.
- *
- * The default off Cursor-managed hosting. Paths are real, so the harness can
- * open a file with its ordinary tools — that is why this reports
- * `materialized` — and there are no etags, so `conflictDetection` is honestly
- * false and concurrent writers are last-writer-wins.
- */
-
-import { randomUUID } from "node:crypto";
-import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { join, relative, resolve, sep } from "node:path";
-import {
-  FilePathRejectedError,
-  type FileSink,
-  type FileSinkBody,
-  type FileSinkEntry,
-} from "../files.js";
-
-export interface LocalFilesOptions {
-  /** Directory the sink owns. */
-  filesRoot: string;
-  /**
-   * Prefix trimmed off each key before building the on-disk path, so the tree
-   * reads `deployment/notes.md` instead of repeating the framework key root.
-   *
-   * Framework-supplied. Authors should omit it: the value has to match the
-   * internal key scheme exactly, and a near-miss would silently nest files
-   * under a redundant path instead of failing. Omitted, keys are stored
-   * verbatim, which is always correct and lets two agents share one root.
-   */
-  stripKeyPrefix?: string;
-}
-
-/**
- * Default sink: one file per key under the state root, written atomically.
- *
- * Reports `materialized` because the paths are real — that is what lets the
- * harness read a file with its ordinary tools — and reports no `etags`, so
- * `host.files.capabilities.conflictDetection` is honestly false and concurrent
- * writers are last-writer-wins.
- */
-export function localFiles(options: LocalFilesOptions): FileSink {
-  const root = resolve(options.filesRoot);
-
-  const stripPrefix = options.stripKeyPrefix ?? "";
-  const pathForKey = (key: string): string => {
-    const rel =
-      stripPrefix !== "" && key.startsWith(stripPrefix) ? key.slice(stripPrefix.length) : key;
-    const candidate = resolve(root, rel);
-    const within = relative(root, candidate);
-    if (within === "" || within === ".." || within.startsWith(`..${sep}`)) {
-      throw new FilePathRejectedError(
-        `host.files key does not resolve under the state root: ${key}`,
-      );
-    }
-    return candidate;
-  };
-
-  const entryFor = async (key: string, absPath: string): Promise<FileSinkEntry | undefined> => {
-    try {
-      const info = await stat(absPath);
-      if (!info.isFile()) {
-        return undefined;
-      }
-      return { key, size: info.size, mtimeMs: info.mtimeMs };
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-        return undefined;
-      }
-      throw error;
-    }
-  };
-
-  return {
-    capabilities: { materialized: true },
-
-    materializedPath: key => pathForKey(key),
-
-    async put(key, body): Promise<void> {
-      const target = pathForKey(key);
-      await mkdir(join(target, ".."), { recursive: true });
-      // Same-directory temp + rename: a reader either sees the previous value
-      // or the whole new one, never a half-written file.
-      const tmp = join(target, "..", `.tmp-${randomUUID()}`);
-      try {
-        await writeFile(tmp, body);
-        await rename(tmp, target);
-      } catch (error) {
-        await rm(tmp, { force: true });
-        throw error;
-      }
-    },
-
-    async get(key): Promise<FileSinkBody | undefined> {
-      try {
-        return { body: new Uint8Array(await readFile(pathForKey(key))) };
-      } catch (error) {
-        const code = (error as NodeJS.ErrnoException).code;
-        if (code === "ENOENT" || code === "EISDIR") {
-          return undefined;
-        }
-        throw error;
-      }
-    },
-
-    async delete(key): Promise<void> {
-      await rm(pathForKey(key), { force: true });
-    },
-
-    async stat(key): Promise<FileSinkEntry | undefined> {
-      return await entryFor(key, pathForKey(key));
-    },
-
-    async list(prefix): Promise<FileSinkEntry[]> {
-      // Walk the deepest existing directory at or above the prefix, then keep
-      // the keys that actually start with it — `prefix` is a key prefix, not a
-      // directory, so `notes/sum` must match `notes/summary.md`.
-      const prefixPath = pathForKey(prefix);
-      const searchRoot = (await isDirectory(prefixPath)) ? prefixPath : join(prefixPath, "..");
-      const out: FileSinkEntry[] = [];
-      for await (const absPath of walkFiles(searchRoot)) {
-        const key = `${stripPrefix}${relative(root, absPath).split(sep).join("/")}`;
-        if (!key.startsWith(prefix)) {
-          continue;
-        }
-        const entry = await entryFor(key, absPath);
-        if (entry !== undefined) {
-          out.push(entry);
-        }
-      }
-      return out.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
-    },
-  };
-}
-
-async function isDirectory(absPath: string): Promise<boolean> {
-  try {
-    return (await stat(absPath)).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-async function* walkFiles(dir: string): AsyncGenerator<string> {
-  let entries: Awaited<ReturnType<typeof readdir>>;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      return;
-    }
-    throw error;
-  }
-  for (const entry of entries) {
-    const abs = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      yield* walkFiles(abs);
-    } else if (entry.isFile() && !entry.name.startsWith(".tmp-")) {
-      yield abs;
-    }
-  }
-}

package/src/files.ts

@@ -1,293 +0,0 @@
-/**
- * The internal sink contract behind `ctx.host.files` — durable, file-shaped
- * state that must outlive the engine process.
- *
- * Deliberately **not a filesystem**: no file descriptors, no seeking, no
- * rename, no directories as first-class objects, and no POSIX errno contract
- * — a sink that is an HTTP API can implement all of it. The framework
- * **mints every key** from a stable, versioned scheme (see {@link fileKeys});
- * sinks see opaque strings and never learn which deployment or session a key
- * belongs to, which is what keeps one deployment's files unreachable from
- * another's.
- *
- * Internal for now: the authored plug-in surface (`agent/files.ts` with a
- * `defineFiles`, mirroring `defineStorage`) is deliberately deferred so this
- * ships as exactly the hosted connector plus the local default. When it
- * lands, {@link FileSink} is the contract authored sinks implement.
- *
- * Delivery semantics differ from {@link import("./storage.js").defineStorage}
- * on purpose. Storage is a fire-and-forget mirror of framework state, so a
- * throwing `put` is logged and dropped. Files are author data the next turn
- * may depend on, so {@link HostFilesApi} writes are **awaited and surface
- * their failure** — an author who writes evidence and then delegates has to
- * know the write did not land.
- */
-
-import { AGENTSDK_STORAGE_KEY_ROOT, STORAGE_KEY_ROOT } from "./storage.js";
-
-// ============================================================================
-// Sink interface
-// ============================================================================
-
-/** One entry returned by {@link FileSink.list}. */
-export interface FileSinkEntry {
-  /** Framework-minted key, as passed to {@link FileSink.put}. */
-  key: string;
-  size: number;
-  /** Last-modified epoch ms, when the sink tracks one. */
-  mtimeMs?: number;
-  /** Opaque version tag; required for `ifMatch` to be usable. */
-  etag?: string;
-}
-
-/** One stored value plus the version it was read at. */
-export interface FileSinkBody {
-  body: Uint8Array;
-  etag?: string;
-}
-
-/** Outcome of {@link FileSink.put}. */
-export interface FileSinkPutResult {
-  /** Version tag after the write, when the sink issues one. */
-  etag?: string;
-}
-
-/**
- * What a sink can do beyond the four required calls. Absent flags are false,
- * so the narrowest possible sink — four functions over an HTTP API — is valid
- * and the framework degrades visibly rather than assuming.
- */
-export interface FileSinkCapabilities {
-  /**
-   * `put` honors `ifMatch` and rejects a stale write. Required for
-   * {@link HostFilesApi} to report `conflictDetection`.
-   */
-  etags?: boolean;
-  /**
-   * The sink keeps a local copy at {@link FileSink.materializedPath} that the
-   * harness can read with ordinary file tools.
-   */
-  materialized?: boolean;
-  /** Largest value the sink accepts, in bytes. */
-  maxBytes?: number;
-}
-
-/**
- * The pluggable file store. Keys are framework-minted opaque strings; a sink
- * may treat them as flat keys or split on `/` to build a hierarchy.
- */
-export interface FileSink {
-  /**
-   * Write or replace one value. When `ifMatch` is set and the sink reports
-   * {@link FileSinkCapabilities.etags}, the write must fail unless the stored
-   * version matches — throw {@link FileConflictError} to say so precisely.
-   * `ifMatch: null` means "must not already exist".
-   */
-  put(
-    key: string,
-    body: Uint8Array,
-    options?: { ifMatch?: string | null },
-  ): Promise<FileSinkPutResult | void>;
-  /**
-   * Write several values in one round trip where the backend can (one
-   * presign call instead of one per key). Optional — callers fall back to
-   * sequential {@link put}. Outcomes are settled per entry, index-aligned
-   * with the input: one key's conflict or failure never rejects its batch
-   * siblings. Per-key semantics (preconditions, conflict errors, etag
-   * bookkeeping) match {@link put} exactly.
-   */
-  putMany?(
-    entries: Array<{
-      key: string;
-      body: Uint8Array;
-      options?: { ifMatch?: string | null };
-    }>,
-  ): Promise<Array<PromiseSettledResult<FileSinkPutResult | void>>>;
-  /** Read one value. Miss → `undefined`. */
-  get(key: string): Promise<FileSinkBody | Uint8Array | undefined>;
-  /**
-   * Read several values in few round trips where the backend can (one
-   * presign call per batch instead of one per key). Optional — callers fall
-   * back to bounded per-key {@link get}. The result is index-aligned with
-   * `keys`; a miss is `undefined`, matching {@link get}. Any transport or
-   * download failure rejects the whole call — a partial result is never
-   * returned, so a caller cannot mistake a failed batch for absence.
-   */
-  getMany?(keys: readonly string[]): Promise<Array<FileSinkBody | Uint8Array | undefined>>;
-  /** Remove one key. No-op when missing. */
-  delete(key: string): Promise<void>;
-  /** Entries whose key starts with `prefix`, in key order. */
-  list(prefix: string): Promise<FileSinkEntry[]>;
-  /** Per-key metadata without transferring the body. Optional; `list` is the fallback. */
-  stat?(key: string): Promise<FileSinkEntry | undefined>;
-  /**
-   * Absolute path of the sink's local copy of `key`, or `undefined` when it
-   * keeps none. Only consulted when
-   * {@link FileSinkCapabilities.materialized} is set.
-   */
-  materializedPath?(key: string): string | undefined;
-  capabilities?: FileSinkCapabilities;
-}
-
-// ============================================================================
-// Key scheme
-// ============================================================================
-
-/**
- * The framework-owned file key scheme, a stable versioned contract under
- * {@link STORAGE_KEY_ROOT}. Sinks may treat these as opaque, or route on
- * prefixes.
- *
- * | Key | Holds |
- * | --- | --- |
- * | `agentkit/v1/{agent}/files/deployment/{path}` | Deployment-scoped file, shared by every session and surviving redeploys |
- * | `agentkit/v1/{agent}/files/deployment/{partition}/{path}` | Deployment-scoped file under an author partition (a PR, a customer, a branch) |
- * | `agentkit/v1/{agent}/files/sessions/{sessionId}/{path}` | Session-scoped file |
- *
- * Scoping lives here, above the sink, so a sink cannot be handed a key for a
- * deployment or session other than its own.
- */
-export const fileKeys = {
-  deployment: (agent: string, path: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/files/deployment/${path}`,
-  deploymentPartition: (agent: string, partition: string, path: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/files/deployment/${partition}/${path}`,
-  session: (agent: string, sessionId: string, path: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/files/sessions/${sessionId}/${path}`,
-  deploymentPrefix: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/files/deployment/`,
-  sessionPrefix: (agent: string, sessionId: string): string =>
-    `${STORAGE_KEY_ROOT}/${agent}/files/sessions/${sessionId}/`,
-} as const;
-
-/**
- * Public `/v0/agent-serve-files/:sourceId` alias for the caller's USER store.
- * Mirrors `AGENT_SERVE_USER_STORE_FILES_SOURCE_ID` in `@anysphere/constants`
- * (not a dependency of this published package).
- */
-export const AGENT_SERVE_USER_STORE_FILES_SOURCE_ID = "user";
-
-/**
- * Store-root prefix for Agent Serve data on a USER store. Mirrors
- * `AGENT_SERVE_USER_STORE_KEY_PREFIX` in `@anysphere/constants`.
- */
-export const AGENT_SERVE_USER_STORE_KEY_PREFIX = "agent-serve";
-
-/**
- * Framework-owned keys for state that lives on the deployment's Agent Store
- * but is not author `host.files` data: artifact rows and payloads, authored
- * skills and workspace seeds synced for cloud turns, and the cross-session
- * memory journal. Kept out of `files/` so author listings never see
- * framework rows.
- *
- * Skills sit at store-root `skills/<name>/…` so exec-daemon's
- * `--agent-store-skills-dir` walk finds them the same way it finds user-store
- * skills. Workspace seeds sit at store-root `workspace/…` so the mount path
- * the first cloud prompt names stays short. Per-turn `workspaceFiles` sit at
- * `sessions/<sessionId>/workspace/…` on that same shared mount. Memory and
- * artifacts stay under {@link STORAGE_KEY_ROOT}.
- */
-function createAgentStoreKeys(root: string) {
-  return {
-    artifactRow: (agent: string, id: string): string =>
-      `${root}/${agent}/artifacts/rows/${encodeURIComponent(id)}.json`,
-    artifactRowPrefix: (agent: string): string => `${root}/${agent}/artifacts/rows/`,
-    artifactContent: (agent: string, id: string): string =>
-      `${root}/${agent}/artifacts/content/${encodeURIComponent(id)}`,
-    skillFile: (skillName: string, relPath: string, skillsPrefix: string = "skills/"): string =>
-      `${skillsPrefix}${skillName}/${relPath}`,
-    skillsPrefix: (): string => "skills/",
-    /** Personal-key cloud agents: namespaced so they cannot collide with the user's own `skills/`. */
-    userSkillsPrefix: (agent: string): string =>
-      `${AGENT_SERVE_USER_STORE_KEY_PREFIX}/${agent}/skills/`,
-    workspaceFile: (relPath: string, workspacePrefix: string = "workspace/"): string =>
-      `${workspacePrefix}${relPath}`,
-    workspacePrefix: (): string => "workspace/",
-    /** Personal-key cloud agents: namespaced like {@link userSkillsPrefix}. */
-    userWorkspacePrefix: (agent: string): string =>
-      `${AGENT_SERVE_USER_STORE_KEY_PREFIX}/${agent}/workspace/`,
-    sessionWorkspacePrefix: (sessionId: string): string => `sessions/${sessionId}/workspace/`,
-    /** Personal-key cloud agents: namespaced like {@link sessionWorkspacePrefix}. */
-    userSessionWorkspacePrefix: (agent: string, sessionId: string): string =>
-      `${AGENT_SERVE_USER_STORE_KEY_PREFIX}/${agent}/sessions/${sessionId}/workspace/`,
-    memoryDir: (agent: string): string => `${root}/${agent}/memory`,
-    memoryJournal: (agent: string): string => `${root}/${agent}/memory/journal.jsonl`,
-    memoryJournalRotated: (agent: string, stamp: string): string =>
-      `${root}/${agent}/memory/journal-${stamp}.jsonl`,
-    // SDK conversation mirror (the runner's SQLite store, exported through the
-    // store APIs): one manifest per SDK agent id plus its content-addressed
-    // checkpoint blobs. See internal/conversation-mirror.ts.
-    conversationManifest: (agent: string, sdkAgentId: string): string =>
-      `${root}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/manifest.json`,
-    conversationBlob: (agent: string, sdkAgentId: string, blobId: string): string =>
-      `${root}/${agent}/conversations/${encodeURIComponent(sdkAgentId)}/blobs/${encodeURIComponent(blobId)}`,
-  } as const;
-}
-
-export type AgentStoreKeys = ReturnType<typeof createAgentStoreKeys>;
-export const agentStoreKeys: AgentStoreKeys = createAgentStoreKeys(STORAGE_KEY_ROOT);
-export const agentSdkAgentStoreKeys: AgentStoreKeys =
-  createAgentStoreKeys(AGENTSDK_STORAGE_KEY_ROOT);
-
-/**
- * Deployment store FUSE mount on cloud-runtime VMs. Mirrors
- * `AGENT_STORE_MOUNT_ROOT` / `AGENT_SERVE_DEPLOYMENT_STORE_MOUNT_NAME` in
- * `@anysphere/constants` (not a dependency of this published package).
- */
-export const DEPLOYMENT_STORE_MOUNT_PATH = "/cursor/stores/deployment";
-
-/**
- * USER store FUSE mount on personal-key cloud-runtime VMs. Mirrors
- * `AGENT_STORE_MOUNT_ROOT` / `AGENT_STORE_USER_MOUNT_NAME` in
- * `@anysphere/constants`.
- */
-export const USER_STORE_MOUNT_PATH = "/cursor/stores/user";
-
-/** Errors raised by the file surface. Thrown by sinks and by the framework. */
-export class FileConflictError extends Error {
-  constructor(
-    readonly key: string,
-    options?: { cause?: unknown; storedEtag?: string },
-  ) {
-    super(
-      `host.files write for "${key}" lost a race with another writer${
-        options?.storedEtag === undefined ? "" : ` (stored version ${options.storedEtag})`
-      }`,
-    );
-    this.name = "FileConflictError";
-    if (options?.cause !== undefined) {
-      this.cause = options.cause;
-    }
-    if (options?.storedEtag !== undefined) {
-      this.storedEtag = options.storedEtag;
-    }
-  }
-  storedEtag?: string;
-}
-
-/** A path the framework refuses to mint a key for. */
-export class FilePathRejectedError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "FilePathRejectedError";
-  }
-}
-
-/** A session-scoped call with no session in scope. */
-export class FileSessionRequiredError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "FileSessionRequiredError";
-  }
-}
-
-/** A value larger than the sink accepts. */
-export class FileTooLargeError extends Error {
-  constructor(
-    readonly key: string,
-    readonly size: number,
-    readonly maxBytes: number,
-  ) {
-    super(`host.files value for "${key}" is ${size} bytes, over the sink's ${maxBytes}-byte limit`);
-    this.name = "FileTooLargeError";
-  }
-}