@cursor/july 0.1.109 → 0.1.112

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

@@ -88,7 +88,7 @@ export function localFiles(options: LocalFilesOptions): FileSink {
   return {
     capabilities: { materialized: true },
 
-    materializedPath: (key) => pathForKey(key),
+    materializedPath: key => pathForKey(key),
 
     async put(key, body): Promise<void> {
       const target = pathForKey(key);

package/src/files.ts

@@ -88,6 +88,21 @@ export interface FileSink {
     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>;
   /** Remove one key. No-op when missing. */

package/src/filesystem.ts

@@ -40,6 +40,7 @@ export {
 
 import { mergeSorted } from "./internal/filesystem/merge.js";
 import {
+  isExcludedPath,
   listFilesFromPaths,
   mergeSortedByPath,
   statFromFilePaths,
@@ -115,6 +116,41 @@ export interface GrepResult {
   line: string;
 }
 
+/**
+ * Optional filters for {@link FileSystem.list}.
+ *
+ * `excludes` are ignore globs in the same language as native LS
+ * `ignore`: a slash-free pattern matches at any depth, and a
+ * directory match drops that tree. Implementations that can push
+ * them to a backend should; others filter the yielded files.
+ * Native LS still applies `ignore` after `list` so a mount that
+ * ignores this argument still honors it.
+ */
+export interface ListOptions {
+  excludes?: readonly string[];
+  /**
+   * Optional result cap, lexicographic. Omitted means no
+   * FileSystem-level cap. `0` yields nothing.
+   */
+  limit?: number;
+}
+
+/**
+ * Optional filters for {@link FileSystem.glob}.
+ *
+ * `limit` is the same lexicographic cap as {@link ListOptions.limit}.
+ */
+export interface GlobOptions {
+  limit?: number;
+}
+
+/**
+ * Default scan cap for synthesized LS / Glob and for Origin
+ * `ListRepoPaths` from `/repo`. Smaller than Origin's 10k default
+ * so a recursive listing does not materialize a huge response.
+ */
+export const FILE_SYSTEM_SCAN_LIMIT = 1_000;
+
 /**
  * Content-search query. No `output_mode` or `offset` (those
  * belong to the native Grep tool).
@@ -126,6 +162,11 @@ export interface GrepResult {
  * only. A slash-free `glob` (`*.ts`) matches the basename at any
  * depth under `path`.
  *
+ * `excludes` are optional ignore globs (same language as
+ * {@link ListOptions.excludes}). Implementations that can push
+ * them to a backend should; others skip matching files. Native
+ * Grep has no ignore field; this is FileSystem-only pushdown.
+ *
  * `maxResults` is optional predicate pushdown: stop after this
  * many hits so a remote or large tree does not materialize a
  * full scan. Native Grep still applies `head_limit` / `offset`
@@ -135,6 +176,7 @@ export interface GrepQuery {
   pattern: string;
   path?: string;
   glob?: string;
+  excludes?: readonly string[];
   caseInsensitive?: boolean;
   maxResults?: number;
 }
@@ -240,8 +282,11 @@ export interface FileSystem {
    *
    * Errors: none. A missing or file-path prefix yields an empty
    * iterator. Do not throw.
+   *
+   * `options.excludes` / `options.limit` are optional pushdown.
+   * See {@link ListOptions}.
    */
-  list(prefix?: string): AsyncIterable<DirEntry>;
+  list(prefix?: string, options?: ListOptions): AsyncIterable<DirEntry>;
   /**
    * Existence probe: exact file, a prefix that has files, or
    * missing. Does not throw. Native LS lists first and calls
@@ -260,8 +305,15 @@ export interface FileSystem {
    * Errors: none. A missing `dir` or a pattern that matches
    * nothing yields an empty iterator. Do not throw for a bad
    * glob (it matches nothing).
+   *
+   * `options.limit` is optional result-cap pushdown. See
+   * {@link GlobOptions}.
    */
-  glob(pattern: string, dir?: string): AsyncIterable<DirEntry>;
+  glob(
+    pattern: string,
+    dir?: string,
+    options?: GlobOptions
+  ): AsyncIterable<DirEntry>;
   /**
    * Read the whole file. Text files return a string. Image
    * bytes (`jpeg` / `png` / `gif` / `webp`) return a
@@ -449,7 +501,7 @@ export class FileSystemConfigError extends Error {
 }
 
 function allowlistHas(tools: readonly ToolName[], ...names: string[]): boolean {
-  return tools.some((name) => names.includes(name));
+  return tools.some(name => names.includes(name));
 }
 
 export function resolveRootHarnessAllowlist(
@@ -481,7 +533,7 @@ export function resolveRootHarnessAllowlist(
         "verb, so the host language service would run against the real workspace."
     );
   }
-  const extras = tools.filter((name) => !isFileSystemToolAlias(name));
+  const extras = tools.filter(name => !isFileSystemToolAlias(name));
   return withMcpGrant(extras);
 }
 
@@ -545,7 +597,7 @@ export function resolveHostHarnessToolOptions(tools?: readonly ToolName[]): {
     return { tools: [] };
   }
   return {
-    tools: withMcpGrant(tools.filter((name) => !isReplacedHostFileAlias(name))),
+    tools: withMcpGrant(tools.filter(name => !isReplacedHostFileAlias(name))),
   };
 }
 
@@ -798,7 +850,7 @@ export function shapeGrepUnion(
   outputMode: GrepOutputMode
 ): GrepUnionResult {
   if (outputMode === "files_with_matches") {
-    const files = [...new Set(matches.map((match) => match.path))];
+    const files = [...new Set(matches.map(match => match.path))];
     return { type: "files", output: { files, count: files.length } };
   }
   if (outputMode === "count") {
@@ -817,7 +869,7 @@ export function shapeGrepUnion(
   return {
     type: "content",
     output: {
-      matches: matches.map((match) => ({
+      matches: matches.map(match => ({
         file: match.path,
         lineNumber: match.lineNumber,
         line: match.line,
@@ -1141,14 +1193,15 @@ export function tempFs(
   }
 
   const listed = {
-    list(prefix?: string) {
+    list(prefix?: string, options?: ListOptions) {
       return listFilesFromPaths(
         [...store.entries()].map(([filePath, content]) => ({
           path: filePath,
           size:
             typeof content === "string" ? content.length : content.byteLength,
         })),
-        prefix
+        prefix,
+        options
       );
     },
     async stat(path: string) {
@@ -1157,8 +1210,8 @@ export function tempFs(
   };
 
   return {
-    list(prefix) {
-      return listed.list(prefix);
+    list(prefix, options) {
+      return listed.list(prefix, options);
     },
     async stat(path) {
       return listed.stat(path);
@@ -1195,6 +1248,9 @@ export function tempFs(
           ) {
             return;
           }
+          if (isExcludedPath(scope, query.excludes)) {
+            return;
+          }
           yield* grepFileContent({
             path: scope,
             content: fileSystemText(exact),
@@ -1203,7 +1259,10 @@ export function tempFs(
           return;
         }
         for await (const entry of listed.list(
-          scope === "/" ? undefined : scope
+          scope === "/" ? undefined : scope,
+          query.excludes === undefined
+            ? undefined
+            : { excludes: query.excludes }
         )) {
           if (
             query.glob !== undefined &&
@@ -1225,12 +1284,13 @@ export function tempFs(
         }
       }
     },
-    async *glob(pattern, dir) {
+    async *glob(pattern, dir, options) {
       const scope =
         dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
       yield* globFromList(listed.list(scope === "/" ? undefined : scope), {
         pattern,
         dir: scope,
+        ...(options?.limit === undefined ? {} : { limit: options.limit }),
       });
     },
     async write(inputPath, contents) {
@@ -1319,12 +1379,19 @@ export function localFileSystem(options: { cwd: string }): FileSystem {
     path.isAbsolute(input) ? path.resolve(input) : path.resolve(cwd, input);
 
   return {
-    async *list(prefix) {
-      const dirPath =
-        prefix === undefined || prefix === "" || prefix === "."
-          ? cwd
-          : resolvePath(prefix);
-      yield* listLocalFiles(dirPath);
+    async *list(prefix, options) {
+      yield* limitResults(uncapped(), options?.limit);
+      async function* uncapped() {
+        const dirPath =
+          prefix === undefined || prefix === "" || prefix === "."
+            ? cwd
+            : resolvePath(prefix);
+        for await (const entry of listLocalFiles(dirPath)) {
+          if (!isExcludedPath(entry.path, options?.excludes)) {
+            yield entry;
+          }
+        }
+      }
     },
     async stat(probePath) {
       const filePath = resolvePath(probePath);
@@ -1374,6 +1441,9 @@ export function localFileSystem(options: { cwd: string }): FileSystem {
           ) {
             continue;
           }
+          if (isExcludedPath(filePath, query.excludes)) {
+            continue;
+          }
           let content: string;
           try {
             content = await readFile(filePath, "utf8");
@@ -1384,12 +1454,13 @@ export function localFileSystem(options: { cwd: string }): FileSystem {
         }
       }
     },
-    async *glob(pattern, dir) {
+    async *glob(pattern, dir, options) {
       const dirPath =
         dir === undefined || dir === "" || dir === "." ? cwd : resolvePath(dir);
       yield* globFromList(listLocalFiles(dirPath), {
         pattern,
         dir: dirPath,
+        ...(options?.limit === undefined ? {} : { limit: options.limit }),
       });
     },
     async write(inputPath, contents) {
@@ -1586,33 +1657,36 @@ export function unionFs(mounts: Record<string, FileSystem>): FileSystem {
     value === undefined || value === "" || value === "/";
 
   return {
-    async *list(prefix) {
-      if (isRootPath(prefix)) {
-        yield* mergeSortedByPath(
-          entries.map((mount) =>
-            mapMountEntries(mount.fs.list(), mount.prefix)
-          ),
-          { unique: true }
+    async *list(prefix, options) {
+      yield* limitResults(uncapped(), options?.limit);
+      async function* uncapped() {
+        if (isRootPath(prefix)) {
+          yield* mergeSortedByPath(
+            entries.map(mount =>
+              mapMountEntries(mount.fs.list(undefined, options), mount.prefix)
+            ),
+            { unique: true }
+          );
+          return;
+        }
+        const path = normalizeFsPath(prefix ?? "/");
+        const mount = longestMount(path, entries);
+        if (mount === undefined) {
+          return;
+        }
+        const childPath = toChildPath(path, mount.prefix);
+        yield* mapMountEntries(
+          mount.fs.list(childPath === "/" ? undefined : childPath, options),
+          mount.prefix
         );
-        return;
-      }
-      const path = normalizeFsPath(prefix ?? "/");
-      const mount = longestMount(path, entries);
-      if (mount === undefined) {
-        return;
       }
-      const childPath = toChildPath(path, mount.prefix);
-      yield* mapMountEntries(
-        mount.fs.list(childPath === "/" ? undefined : childPath),
-        mount.prefix
-      );
     },
     async stat(path) {
       const normalized = normalizeFsPath(path);
       if (normalized === "/") {
         return { kind: "directory" } as const;
       }
-      if (entries.some((entry) => entry.prefix === normalized)) {
+      if (entries.some(entry => entry.prefix === normalized)) {
         return { kind: "directory" } as const;
       }
       const mount = longestMount(normalized, entries);
@@ -1644,7 +1718,7 @@ export function unionFs(mounts: Record<string, FileSystem>): FileSystem {
             : normalizeFsPath(query.path);
         if (scope === "/") {
           yield* mergeSorted(
-            entries.map((mount) =>
+            entries.map(mount =>
               mapMountGrep(
                 mount.fs.grep({ ...query, path: undefined }),
                 mount.prefix
@@ -1684,27 +1758,37 @@ export function unionFs(mounts: Record<string, FileSystem>): FileSystem {
         yield* mergeSorted(sources, { compare: compareSearchResult });
       }
     },
-    async *glob(pattern, dir) {
-      const scope =
-        dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
-      if (scope === "/") {
-        yield* mergeSortedByPath(
-          entries.map((mount) =>
-            mapMountEntries(mount.fs.glob(pattern), mount.prefix)
+    async *glob(pattern, dir, options) {
+      yield* limitResults(uncapped(), options?.limit);
+      async function* uncapped() {
+        const scope =
+          dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
+        if (scope === "/") {
+          yield* mergeSortedByPath(
+            entries.map(mount =>
+              mapMountEntries(
+                mount.fs.glob(pattern, undefined, options),
+                mount.prefix
+              )
+            ),
+            { unique: true }
+          );
+          return;
+        }
+        const mount = longestMount(scope, entries);
+        if (mount === undefined) {
+          return;
+        }
+        const childPath = toChildPath(scope, mount.prefix);
+        yield* mapMountEntries(
+          mount.fs.glob(
+            pattern,
+            childPath === "/" ? undefined : childPath,
+            options
           ),
-          { unique: true }
+          mount.prefix
         );
-        return;
-      }
-      const mount = longestMount(scope, entries);
-      if (mount === undefined) {
-        return;
       }
-      const childPath = toChildPath(scope, mount.prefix);
-      yield* mapMountEntries(
-        mount.fs.glob(pattern, childPath === "/" ? undefined : childPath),
-        mount.prefix
-      );
     },
   };
 }
@@ -1791,14 +1875,17 @@ export function overlayFs(layers: readonly FileSystem[]): FileSystem {
   };
 
   return {
-    async *list(prefix) {
-      const { streams, failure, served } = await walkLayers((layer) =>
-        layer.list(prefix)
+    async *list(prefix, options) {
+      const { streams, failure, served } = await walkLayers(layer =>
+        layer.list(prefix, options)
       );
       if (!served && failure !== undefined) {
         throw failure;
       }
-      yield* mergeSortedByPath(streams, { unique: true });
+      yield* limitResults(
+        mergeSortedByPath(streams, { unique: true }),
+        options?.limit
+      );
     },
     async stat(path) {
       let failure: unknown;
@@ -1819,14 +1906,17 @@ export function overlayFs(layers: readonly FileSystem[]): FileSystem {
       }
       return { kind: "missing" } as const;
     },
-    async *glob(pattern, dir) {
-      const { streams, failure, served } = await walkLayers((layer) =>
-        layer.glob(pattern, dir)
+    async *glob(pattern, dir, options) {
+      const { streams, failure, served } = await walkLayers(layer =>
+        layer.glob(pattern, dir, options)
       );
       if (!served && failure !== undefined) {
         throw failure;
       }
-      yield* mergeSortedByPath(streams, { unique: true });
+      yield* limitResults(
+        mergeSortedByPath(streams, { unique: true }),
+        options?.limit
+      );
     },
     async read(path) {
       let failure: unknown;
@@ -1850,8 +1940,8 @@ export function overlayFs(layers: readonly FileSystem[]): FileSystem {
       yield* limitResults(
         mergeSorted(
           await collectOverlayHits(
-            (layer) => layer.grep(uncappedQuery),
-            (error) => isInvalidGrepPatternError(error)
+            layer => layer.grep(uncappedQuery),
+            error => isInvalidGrepPatternError(error)
           ),
           { compare: compareGrepResult }
         ),
@@ -1868,7 +1958,7 @@ export function overlayFs(layers: readonly FileSystem[]): FileSystem {
       const { maxResults, ...uncappedQuery } = query;
       yield* limitResults(
         mergeSorted(
-          await collectOverlayHits((layer) => layer.search(uncappedQuery)),
+          await collectOverlayHits(layer => layer.search(uncappedQuery)),
           { compare: compareSearchResult }
         ),
         maxResults
@@ -1904,20 +1994,21 @@ export function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem {
   const readEtags = new Map<string, string>();
 
   const listed = {
-    async *list(prefix?: string) {
+    async *list(prefix?: string, options?: ListOptions) {
       const entries = await files.list(undefined, callOptions);
       yield* listFilesFromPaths(
-        entries.map((entry) => ({
+        entries.map(entry => ({
           path: normalizeFsPath(entry.path),
           size: entry.size,
         })),
-        prefix
+        prefix,
+        options
       );
     },
     async stat(path: string) {
       const entries = await files.list(undefined, callOptions);
       return statFromFilePaths(
-        entries.map((entry) => normalizeFsPath(entry.path)),
+        entries.map(entry => normalizeFsPath(entry.path)),
         path
       );
     },
@@ -1981,8 +2072,8 @@ export function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem {
   };
 
   return {
-    list(prefix) {
-      return listed.list(prefix);
+    list(prefix, options) {
+      return listed.list(prefix, options);
     },
     async stat(path) {
       return listed.stat(path);
@@ -2012,6 +2103,9 @@ export function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem {
           ) {
             return;
           }
+          if (isExcludedPath(scopePath, query.excludes)) {
+            return;
+          }
           yield* grepFileContent({
             path: scopePath,
             content: await readText(scopePath),
@@ -2020,7 +2114,10 @@ export function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem {
           return;
         }
         for await (const entry of listed.list(
-          scopePath === "/" ? undefined : scopePath
+          scopePath === "/" ? undefined : scopePath,
+          query.excludes === undefined
+            ? undefined
+            : { excludes: query.excludes }
         )) {
           if (
             query.glob !== undefined &&
@@ -2038,12 +2135,13 @@ export function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem {
         }
       }
     },
-    async *glob(pattern, dir) {
+    async *glob(pattern, dir, options) {
       const dirPath =
         dir === undefined || dir === "" ? "/" : normalizeFsPath(dir);
       yield* globFromList(listed.list(dirPath === "/" ? undefined : dirPath), {
         pattern,
         dir: dirPath,
+        ...(options?.limit === undefined ? {} : { limit: options.limit }),
       });
     },
     async write(inputPath, contents) {
@@ -2064,11 +2162,14 @@ export function hostFs(files: HostFilesApi, scope: HostFilesScope): FileSystem {
 
 async function* globFromList(
   source: AsyncIterable<DirEntry>,
-  options: { pattern: string; dir: string }
+  options: { pattern: string; dir: string; limit?: number }
 ): AsyncGenerator<DirEntry> {
-  for await (const entry of source) {
-    if (pathMatchesGlob(entry.path, options.dir, options.pattern)) {
-      yield entry;
+  yield* limitResults(uncapped(), options.limit);
+  async function* uncapped() {
+    for await (const entry of source) {
+      if (pathMatchesGlob(entry.path, options.dir, options.pattern)) {
+        yield entry;
+      }
     }
   }
 }

package/src/index.ts

@@ -39,7 +39,6 @@ export {
   DELETE,
   defineChannel,
   GET,
-  httpChannel,
   localDev,
   localDevStrict,
   loopbackGitHubDev,
@@ -70,8 +69,10 @@ export type {
   EditResult,
   FileInfo,
   FileSystem,
+  GlobOptions,
   GrepQuery,
   GrepResult,
+  ListOptions,
   SearchQuery,
   SearchResult,
 } from "./filesystem.js";
@@ -79,6 +80,7 @@ export {
   DeleteNotSupportedError,
   EditError,
   emptyFs,
+  FILE_SYSTEM_SCAN_LIMIT,
   FileNotFoundError,
   hostFs,
   InvalidGrepPatternError,
@@ -93,10 +95,7 @@ export {
   WriteFailedError,
 } from "./filesystem.js";
 export { defineHook } from "./hooks.js";
-export {
-  InvalidAsOfError,
-  VacuousTimeArgsError,
-} from "./internal/as-of.js";
+export { InvalidAsOfError, VacuousTimeArgsError } from "./internal/as-of.js";
 export type {
   ContinuationBuiltin,
   ContinuationClaim,
@@ -106,6 +105,7 @@ export type {
   MailboxContinuation,
   ParsedContinuation,
 } from "./internal/continuation-identity.js";
+export { mintClaim } from "./internal/continuation-identity.js";
 export type { LoadAgentProjectOptions } from "./internal/discovery.js";
 export {
   formatDiagnostics,
@@ -151,19 +151,13 @@ export {
   UnknownSessionError,
   UnknownToolError,
 } from "./internal/session-engine.js";
-export { createMemoryKv, memoryCasTable } from "./kv/memory-kv.js";
 export type { MemoryBackend, TurnMemoryRecord } from "./memory.js";
 export {
   agentStoreMemoryBackend,
   fileMemoryBackend,
   memoryHook,
 } from "./memory.js";
-export type {
-  OtelConfig,
-  OtelDefinition,
-  OtelExporterConfig,
-} from "./otel.js";
-export { defineOtel, resolveOtelDefinition } from "./otel.js";
+export type { OtelConfig, OtelDefinition, OtelExporterConfig } from "./otel.js";
 export type { PromptTag } from "./prompt.js";
 export { prompt } from "./prompt.js";
 export type {
@@ -185,36 +179,13 @@ export { defineReminder } from "./reminders.js";
 export { defineResult } from "./result.js";
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
-export type {
-  DurableSessionRecord,
-  DurableSessionSummary,
-  StorageCasTable,
-  StorageConfig,
-  StorageContext,
-  StorageDefinition,
-  StorageEntry,
-  StorageEvalsTable,
-  StorageKeys,
-  StoragePolicy,
-  StorageRestorePolicy,
-} from "./storage.js";
-export {
-  AGENTSDK_STORAGE_KEY_ROOT,
-  agentSdkStorageKeys,
-  defineStorage,
-  isDurableSessionRecordKey,
-  parseDurableSessionRecord,
-  STORAGE_KEY_ROOT,
-  storageKeys,
-  storageKeysForArchitecture,
-  summarizeDurableSessionRecord,
-} from "./storage.js";
 export { defineTool } from "./tools.js";
 export type * from "./types.js";
 export {
   cursorAccountServersHasMixedWildcard,
   DEFAULT_MODEL,
   DIRECT_TOOL_CALL_CHANNEL_ID,
+  HttpSessionAdmitError,
   isCursorAccountTransport,
   isPeerConnectionTransport,
   isSymbolicConnectionTransport,