@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/filesystem/merge.ts

@@ -1,192 +0,0 @@
-/**
- * K-way merge of already-sorted streams. Each source must be ordered
- * under the same `compare`; the merge does not re-sort a source.
- *
- * A binary heap of heads keeps the next yield O(log k) in the number of
- * sources. `unique` skips later copies of a key so an earlier source can
- * shadow a later one (the union rule).
- */
-
-export interface MergeSortedOptions<T> {
-  compare: (left: T, right: T) => number;
-  unique?: boolean;
-}
-
-type Head<T> = {
-  value: T;
-  iterator: AsyncIterator<T>;
-  source: number;
-};
-
-/**
- * Merge already-sorted iterables / async iterables under `compare`.
- * Equal keys (`compare === 0`) keep source order: earlier `sources`
- * index wins. With `unique`, those later copies are skipped.
- */
-export async function* mergeSorted<T>(
-  sources: Array<Iterable<T> | AsyncIterable<T>>,
-  options: MergeSortedOptions<T>,
-): AsyncGenerator<T> {
-  const { compare, unique = false } = options;
-  const heap = new MinHeap<Head<T>>((left, right) => {
-    const byValue = compare(left.value, right.value);
-    return byValue !== 0 ? byValue : left.source - right.source;
-  });
-
-  const iterators = sources.map((source, sourceIndex) => {
-    const iterator =
-      Symbol.asyncIterator in source
-        ? source[Symbol.asyncIterator]()
-        : (async function* () {
-            yield* source;
-          })();
-    return { iterator, sourceIndex };
-  });
-
-  await Promise.all(
-    iterators.map(async ({ iterator, sourceIndex }) => {
-      const next = await iterator.next();
-      if (!next.done) {
-        heap.push({ value: next.value, iterator, source: sourceIndex });
-      }
-    }),
-  );
-
-  while (heap.size > 0) {
-    const best = heap.pop();
-    if (best === undefined) {
-      return;
-    }
-    yield best.value;
-    if (unique) {
-      await advanceMatching(heap, best, compare);
-    } else {
-      await pushNext(heap, best);
-    }
-  }
-}
-
-async function pushNext<T>(heap: MinHeap<Head<T>>, head: Head<T>): Promise<void> {
-  const next = await head.iterator.next();
-  if (!next.done) {
-    heap.push({
-      value: next.value,
-      iterator: head.iterator,
-      source: head.source,
-    });
-  }
-}
-
-/** Advance every head whose key equals `best` (compare === 0). */
-async function advanceMatching<T>(
-  heap: MinHeap<Head<T>>,
-  best: Head<T>,
-  compare: (left: T, right: T) => number,
-): Promise<void> {
-  await pushNext(heap, best);
-  while (heap.size > 0) {
-    const peek = heap.peek();
-    if (peek === undefined || compare(peek.value, best.value) !== 0) {
-      return;
-    }
-    const duplicate = heap.pop();
-    if (duplicate === undefined) {
-      return;
-    }
-    await pushNext(heap, duplicate);
-  }
-}
-
-/**
- * Binary min-heap. `compare(a, b) < 0` means `a` is before `b`.
- * Exported for the invariant tests; composers use {@link mergeSorted}.
- */
-export class MinHeap<T> {
-  private readonly items: T[] = [];
-
-  constructor(private readonly compare: (left: T, right: T) => number) {}
-
-  get size(): number {
-    return this.items.length;
-  }
-
-  peek(): T | undefined {
-    return this.items[0];
-  }
-
-  push(item: T): void {
-    this.items.push(item);
-    this.bubbleUp(this.items.length - 1);
-  }
-
-  pop(): T | undefined {
-    const first = this.items[0];
-    if (first === undefined) {
-      return undefined;
-    }
-    const last = this.items.pop();
-    if (last === undefined || this.items.length === 0) {
-      return first;
-    }
-    this.items[0] = last;
-    this.bubbleDown(0);
-    return first;
-  }
-
-  private bubbleUp(index: number): void {
-    let current = index;
-    while (current > 0) {
-      const parent = Math.floor((current - 1) / 2);
-      const parentItem = this.items[parent];
-      const currentItem = this.items[current];
-      if (
-        parentItem === undefined ||
-        currentItem === undefined ||
-        this.compare(currentItem, parentItem) >= 0
-      ) {
-        return;
-      }
-      this.items[parent] = currentItem;
-      this.items[current] = parentItem;
-      current = parent;
-    }
-  }
-
-  private bubbleDown(index: number): void {
-    let current = index;
-    for (;;) {
-      const left = current * 2 + 1;
-      const right = left + 1;
-      let smallest = current;
-      const currentItem = this.items[smallest];
-      const leftItem = this.items[left];
-      if (
-        leftItem !== undefined &&
-        currentItem !== undefined &&
-        this.compare(leftItem, currentItem) < 0
-      ) {
-        smallest = left;
-      }
-      const smallestItem = this.items[smallest];
-      const rightItem = this.items[right];
-      if (
-        rightItem !== undefined &&
-        smallestItem !== undefined &&
-        this.compare(rightItem, smallestItem) < 0
-      ) {
-        smallest = right;
-      }
-      if (smallest === current) {
-        return;
-      }
-      const swapCurrent = this.items[current];
-      const swapSmallest = this.items[smallest];
-      if (swapCurrent === undefined || swapSmallest === undefined) {
-        return;
-      }
-      this.items[current] = swapSmallest;
-      this.items[smallest] = swapCurrent;
-      current = smallest;
-    }
-  }
-}

package/src/internal/filesystem/nearest.ts

@@ -1,112 +0,0 @@
-/**
- * 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

@@ -1,239 +0,0 @@
-/**
- * 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"
-  );
-}