@cursor/bdk 0.2.1

package/src/internal/filesystem/nearest.ts

@@ -0,0 +1,112 @@
+/**
+ * Parent-listing neighbors for a Read / LS miss. FileSystem has no
+ * catalog API; `list(dirname(path))` is the sibling set. Immediate
+ * children only — a recursive mount must not dump its whole subtree.
+ */
+
+import { posix } from "node:path";
+import type { FileSystem } from "../../filesystem.js";
+import { FILE_SYSTEM_SCAN_LIMIT, normalizeFsPath } from "../../filesystem.js";
+import { collectList } from "./walk.js";
+
+const NEIGHBOR_LIMIT = 5;
+
+export function nearestListedNames(
+  query: string,
+  names: readonly string[],
+  limit: number = NEIGHBOR_LIMIT,
+): string[] {
+  const queryKey = rankKey(query);
+  return [...names]
+    .sort((left, right) => {
+      const leftKey = rankKey(left);
+      const rightKey = rankKey(right);
+      const leftPrefix = isPrefixRelated(queryKey, leftKey) ? 0 : 1;
+      const rightPrefix = isPrefixRelated(queryKey, rightKey) ? 0 : 1;
+      if (leftPrefix !== rightPrefix) {
+        return leftPrefix - rightPrefix;
+      }
+      const distance = editDistance(queryKey, leftKey) - editDistance(queryKey, rightKey);
+      return distance !== 0 ? distance : left.localeCompare(right);
+    })
+    .slice(0, limit);
+}
+
+export function formatMissNeighborHint(
+  path: string,
+  neighbors: readonly string[],
+): string | undefined {
+  if (neighbors.length === 0) {
+    return undefined;
+  }
+  return `not found: ${path}. nearest: ${neighbors.join(", ")}. do not retry.`;
+}
+
+/**
+ * One-line miss hint when the parent directory listed siblings.
+ * `undefined` leaves the caller to throw the ordinary miss.
+ */
+export async function nearestNeighborMissHint(
+  root: Pick<FileSystem, "list">,
+  path: string,
+): Promise<string | undefined> {
+  const missed = normalizeFsPath(path);
+  const parent = parentDir(missed);
+  const files = await collectList(root, parent, {
+    limit: FILE_SYSTEM_SCAN_LIMIT,
+  });
+  const names = [
+    ...new Set(
+      files
+        .map(file => relativeToParent(file.path, parent))
+        .filter(name => name.length > 0 && !name.includes("/")),
+    ),
+  ].filter(name => name !== posix.basename(missed));
+  return formatMissNeighborHint(missed, nearestListedNames(posix.basename(missed), names));
+}
+
+function rankKey(name: string): string {
+  const base = posix.basename(name);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+function isPrefixRelated(left: string, right: string): boolean {
+  return left.startsWith(right) || right.startsWith(left);
+}
+
+function editDistance(left: string, right: string): number {
+  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let i = 0; i < left.length; i += 1) {
+    let diagonal = i;
+    previous[0] = i + 1;
+    for (let j = 0; j < right.length; j += 1) {
+      const insertion = (previous[j + 1] ?? 0) + 1;
+      const deletion = (previous[j] ?? 0) + 1;
+      const substitution = diagonal + (left[i] === right[j] ? 0 : 1);
+      diagonal = previous[j + 1] ?? 0;
+      previous[j + 1] = Math.min(insertion, deletion, substitution);
+    }
+  }
+  return previous[right.length] ?? right.length;
+}
+
+function parentDir(path: string): string {
+  const dir = posix.dirname(path);
+  return dir === "." || dir === path ? "/" : dir;
+}
+
+function relativeToParent(filePath: string, parent: string): string {
+  const file = normalizeFsPath(filePath);
+  const root = parent === "/" || parent === "" ? "/" : normalizeFsPath(parent);
+  if (root === "/") {
+    return file.startsWith("/") ? file.slice(1) : file;
+  }
+  if (file === root) {
+    return posix.basename(file);
+  }
+  if (file.startsWith(`${root}/`)) {
+    return file.slice(root.length + 1);
+  }
+  return posix.basename(file);
+}

package/src/internal/filesystem/scratch.ts

@@ -0,0 +1,239 @@
+/**
+ * Host `{cwd}/agent-tools/{uuid}.txt` → `/tmp/{uuid}.txt`.
+ *
+ * Native WebSearch / WebFetch still scratch large output on the host.
+ * The session engine mounts `tempFs()` at `/tmp` with `unionFs` and
+ * copies only those files onto that tree. This module is the host-path
+ * translation, not a FileSystem type.
+ */
+
+import { readdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import type { FileSystem } from "../../filesystem.js";
+
+export const TMP_SCRATCH_PREFIX = "/tmp";
+export const HOST_AGENT_TOOLS_DIR = "agent-tools";
+export const WEB_SCRATCH_TOOLS = ["webSearch", "webFetch"] as const;
+
+export function isWebScratchTool(name: string | undefined): boolean {
+  return name === "webSearch" || name === "webFetch";
+}
+
+const UUID_TXT = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.txt$/i;
+
+const HOST_FOLLOW_UP = /Use shell \/ grep \/ read_file on this path to inspect the page/g;
+const OVERLAY_FOLLOW_UP = "Use Read / Grep on this path to inspect the page";
+
+const PATH_KEYS = ["path", "dir", "targetDirectory", "target_directory"] as const;
+
+export function tmpScratchPath(fileName: string): string {
+  return `${TMP_SCRATCH_PREFIX}/${fileName}`;
+}
+
+export function hostAgentToolsDir(cwd: string): string {
+  return path.resolve(cwd, HOST_AGENT_TOOLS_DIR);
+}
+
+/**
+ * Basename of `{cwd}/agent-tools/{uuid}.txt`, or undefined. Other
+ * paths in a result are ignored.
+ */
+export function hostAgentToolsFileName(args: {
+  cwd: string;
+  candidate: string;
+}): string | undefined {
+  if (args.candidate === "") {
+    return undefined;
+  }
+  const resolved = path.resolve(args.candidate);
+  if (path.dirname(resolved) !== hostAgentToolsDir(args.cwd)) {
+    return undefined;
+  }
+  const base = path.basename(resolved);
+  return UUID_TXT.test(base) ? base : undefined;
+}
+
+export function remapScratchPath(args: { cwd: string; path: string }): string {
+  const fileName = hostAgentToolsFileName({
+    cwd: args.cwd,
+    candidate: args.path,
+  });
+  return fileName === undefined ? args.path : tmpScratchPath(fileName);
+}
+
+export function remapScratchPaths(
+  input: Record<string, unknown>,
+  cwd: string,
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...input };
+  for (const key of PATH_KEYS) {
+    const value = next[key];
+    if (typeof value === "string") {
+      next[key] = remapScratchPath({ cwd, path: value });
+    }
+  }
+  return next;
+}
+
+export function rewriteWebScratchText(args: { cwd: string; text: string }): string {
+  const dir = hostAgentToolsDir(args.cwd);
+  const escaped = dir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(
+    `${escaped}[/\\\\]([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\.txt)`,
+    "gi",
+  );
+  return args.text
+    .replace(pattern, (_match, fileName: string) => tmpScratchPath(fileName))
+    .replace(HOST_FOLLOW_UP, OVERLAY_FOLLOW_UP);
+}
+
+/** Rewrite host agent-tools paths in a string or a structured tool result. */
+export function rewriteWebScratchValue(args: { cwd: string; value: unknown }): unknown {
+  const { cwd, value } = args;
+  if (typeof value === "string") {
+    return rewriteWebScratchText({ cwd, text: value });
+  }
+  if (Array.isArray(value)) {
+    return value.map(item => rewriteWebScratchValue({ cwd, value: item }));
+  }
+  if (value !== null && typeof value === "object") {
+    const next: Record<string, unknown> = {};
+    for (const [key, item] of Object.entries(value)) {
+      next[key] = rewriteWebScratchValue({ cwd, value: item });
+    }
+    return next;
+  }
+  return value;
+}
+
+/**
+ * WebSearch / WebFetch result. Ingest the host spill and rewrite
+ * paths onto `/tmp`. Other tools are a no-op.
+ */
+export async function finishWebScratchTool(args: {
+  toolName: string | undefined;
+  result: unknown;
+  cwd: string;
+  root: FileSystem;
+}): Promise<unknown> {
+  if (!isWebScratchTool(args.toolName)) {
+    return args.result;
+  }
+  await ingestHostAgentToolsScratch({ cwd: args.cwd, root: args.root });
+  return rewriteWebScratchValue({ cwd: args.cwd, value: args.result });
+}
+
+type ToolCallLike = { type?: string; result?: unknown };
+
+function completedWebToolCall(update: unknown): ToolCallLike | undefined {
+  if (update === null || typeof update !== "object") {
+    return undefined;
+  }
+  const rec = update as {
+    type?: string;
+    toolCall?: ToolCallLike;
+    taskUpdate?: { type?: string; toolCall?: ToolCallLike };
+  };
+  const call =
+    rec.type === "tool-call-completed"
+      ? rec.toolCall
+      : rec.type === "tool-call-delta" && rec.taskUpdate?.type === "tool-call-completed"
+        ? rec.taskUpdate.toolCall
+        : undefined;
+  if (call === undefined || !isWebScratchTool(call.type)) {
+    return undefined;
+  }
+  return call;
+}
+
+/** Finish a native web tool on the SDK update that carried its result. */
+export async function applyWebScratchUpdate<T>(args: {
+  cwd: string;
+  root: FileSystem;
+  update: T;
+}): Promise<T> {
+  const call = completedWebToolCall(args.update);
+  if (call === undefined) {
+    return args.update;
+  }
+  call.result = await finishWebScratchTool({
+    toolName: call.type,
+    result: call.result,
+    cwd: args.cwd,
+    root: args.root,
+  });
+  return args.update;
+}
+
+export async function ingestHostAgentToolsScratch(args: {
+  cwd: string;
+  root: FileSystem;
+  hostPath?: string;
+}): Promise<string[]> {
+  const written: string[] = [];
+  const names =
+    args.hostPath === undefined ? await listHostAgentToolsFiles(args.cwd) : [args.hostPath];
+  for (const hostPath of names) {
+    const dest = await copyHostAgentToolsFile({
+      cwd: args.cwd,
+      root: args.root,
+      hostPath,
+    });
+    if (dest !== undefined) {
+      written.push(dest);
+    }
+  }
+  return written;
+}
+
+async function listHostAgentToolsFiles(cwd: string): Promise<string[]> {
+  const dir = hostAgentToolsDir(cwd);
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter(entry => entry.isFile() && UUID_TXT.test(entry.name))
+      .map(entry => path.join(dir, entry.name));
+  } catch (error) {
+    if (isEnoent(error)) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+async function copyHostAgentToolsFile(args: {
+  cwd: string;
+  root: FileSystem;
+  hostPath: string;
+}): Promise<string | undefined> {
+  const fileName = hostAgentToolsFileName({
+    cwd: args.cwd,
+    candidate: args.hostPath,
+  });
+  if (fileName === undefined) {
+    return undefined;
+  }
+  const dest = tmpScratchPath(fileName);
+  const hostPath = path.resolve(args.hostPath);
+  let bytes: Buffer;
+  try {
+    bytes = await readFile(hostPath);
+  } catch (error) {
+    if (isEnoent(error)) {
+      return undefined;
+    }
+    throw error;
+  }
+  await args.root.write(dest, bytes.toString("utf8"));
+  await rm(hostPath, { force: true });
+  return dest;
+}
+
+function isEnoent(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code: unknown }).code === "ENOENT"
+  );
+}

package/src/internal/filesystem/sdk-schemas.ts

@@ -0,0 +1,204 @@
+/**
+ * Advertised native-tool schemas. These are the `@cursor/sdk`
+ * tool-call types (`@anysphere/cursor-sdk-shared/tool-call-types`)
+ * reconstructed here so `@cursor/bdk` does not take an unpublished
+ * workspace dependency. The contract test pins JSON-schema equality
+ * against the SDK originals.
+ *
+ * Runtime aliases (`contents` → `fileText`, `old_string` → `oldText`)
+ * live on the `defineTool` input schema, not on these objects.
+ */
+
+import { z } from "zod";
+
+const simpleError: z.ZodTypeAny = z.object({
+  message: z.string(),
+});
+
+function resultSchema(success: z.ZodTypeAny): z.ZodTypeAny {
+  return z.discriminatedUnion("status", [
+    z.object({
+      status: z.literal("success"),
+      value: success,
+    }),
+    z.object({
+      status: z.literal("error"),
+      error: simpleError,
+    }),
+  ]);
+}
+
+export const sdkReadArgs: z.ZodTypeAny = z.object({
+  path: z.string(),
+});
+
+export const sdkReadResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    content: z.string(),
+    totalLines: z.number(),
+    fileSize: z.number(),
+  }),
+);
+
+export const sdkWriteArgs: z.ZodTypeAny = z.object({
+  path: z.string(),
+  fileText: z.string(),
+  returnFileContentAfterWrite: z.boolean().optional(),
+});
+
+export const sdkWriteResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    path: z.string(),
+    linesCreated: z.number(),
+    fileSize: z.number(),
+    fileContentAfterWrite: z.string().optional(),
+  }),
+);
+
+export const sdkDeleteArgs: z.ZodTypeAny = z.object({
+  path: z.string(),
+});
+
+export const sdkDeleteResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    fileSize: z.number(),
+  }),
+);
+
+export const sdkGlobArgs: z.ZodTypeAny = z.object({
+  targetDirectory: z.string().optional(),
+  globPattern: z.string(),
+});
+
+export const sdkGlobResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    files: z.array(z.string()),
+    totalFiles: z.number(),
+    clientTruncated: z.boolean(),
+    ripgrepTruncated: z.boolean(),
+  }),
+);
+
+export const sdkGrepArgs: z.ZodTypeAny = z.object({
+  pattern: z.string(),
+  path: z.string().optional(),
+  glob: z.string().optional(),
+  outputMode: z.string().optional(),
+  contextBefore: z.number().optional(),
+  contextAfter: z.number().optional(),
+  context: z.number().optional(),
+  caseInsensitive: z.boolean().optional(),
+  type: z.string().optional(),
+  headLimit: z.number().optional(),
+  offset: z.number().optional(),
+  multiline: z.boolean().optional(),
+  sort: z.string().optional(),
+  sortAscending: z.boolean().optional(),
+});
+
+const grepContentMatch = z.object({
+  file: z.string(),
+  lineNumber: z.number().optional(),
+  line: z.string(),
+  beforeContext: z.array(z.string()).optional(),
+  afterContext: z.array(z.string()).optional(),
+});
+
+const grepFileCount = z.object({
+  file: z.string(),
+  count: z.number(),
+});
+
+const grepUnion = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("content"),
+    output: z.object({
+      matches: z.array(grepContentMatch),
+      totalMatches: z.number(),
+    }),
+  }),
+  z.object({
+    type: z.literal("files"),
+    output: z.object({
+      files: z.array(z.string()),
+      count: z.number(),
+    }),
+  }),
+  z.object({
+    type: z.literal("count"),
+    output: z.object({
+      counts: z.array(grepFileCount),
+      total: z.number(),
+    }),
+  }),
+]);
+
+export const sdkGrepResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    workspaceResults: z.record(grepUnion).optional(),
+    activeEditorResult: grepUnion.optional(),
+  }),
+);
+
+export const sdkLsArgs: z.ZodTypeAny = z.object({
+  path: z.string(),
+  ignore: z.array(z.string()).optional(),
+});
+
+const lsDirectoryTreeNodeFile = z.object({
+  name: z.string(),
+});
+
+type LsDirectoryTreeNode = {
+  absPath: string;
+  childrenDirs: LsDirectoryTreeNode[];
+  childrenFiles: z.infer<typeof lsDirectoryTreeNodeFile>[];
+  childrenWereProcessed: boolean;
+  fullSubtreeExtensionCounts: Record<string, number>;
+  numFiles: number;
+};
+
+const lsDirectoryTreeNode: z.ZodType<LsDirectoryTreeNode> = z.lazy(() =>
+  z.object({
+    absPath: z.string(),
+    childrenDirs: z.array(lsDirectoryTreeNode),
+    childrenFiles: z.array(lsDirectoryTreeNodeFile),
+    childrenWereProcessed: z.boolean(),
+    fullSubtreeExtensionCounts: z.record(z.number()),
+    numFiles: z.number(),
+  }),
+);
+
+export const sdkLsResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    directoryTreeRoot: lsDirectoryTreeNode,
+  }),
+);
+
+/** StrReplace is SDK `edit` plus the str-replace args the model actually sends. */
+export const sdkStrReplaceArgs: z.ZodTypeAny = z.object({
+  path: z.string(),
+  oldText: z.string(),
+  newText: z.string(),
+  replaceAll: z.boolean().optional(),
+});
+
+export const sdkEditResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    linesAdded: z.number().optional(),
+    linesRemoved: z.number().optional(),
+    diffString: z.string().optional(),
+  }),
+);
+
+export const sdkSemSearchArgs: z.ZodTypeAny = z.object({
+  query: z.string(),
+  targetDirectories: z.array(z.string()).optional(),
+  explanation: z.string().optional(),
+});
+
+export const sdkSemSearchResult: z.ZodTypeAny = resultSchema(
+  z.object({
+    results: z.string(),
+  }),
+);