@cursor/july 0.1.111 → 0.1.113

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
@@ -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,24 +1657,29 @@ 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);
@@ -1682,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
-      );
     },
   };
 }
@@ -1789,14 +1875,17 @@ export function overlayFs(layers: readonly FileSystem[]): FileSystem {
   };
 
   return {
-    async *list(prefix) {
+    async *list(prefix, options) {
       const { streams, failure, served } = await walkLayers(layer =>
-        layer.list(prefix)
+        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;
@@ -1817,14 +1906,17 @@ export function overlayFs(layers: readonly FileSystem[]): FileSystem {
       }
       return { kind: "missing" } as const;
     },
-    async *glob(pattern, dir) {
+    async *glob(pattern, dir, options) {
       const { streams, failure, served } = await walkLayers(layer =>
-        layer.glob(pattern, dir)
+        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;
@@ -1902,14 +1994,15 @@ 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 => ({
           path: normalizeFsPath(entry.path),
           size: entry.size,
         })),
-        prefix
+        prefix,
+        options
       );
     },
     async stat(path: string) {
@@ -1979,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);
@@ -2010,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),
@@ -2018,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 &&
@@ -2036,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) {
@@ -2062,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

@@ -69,8 +69,10 @@ export type {
   EditResult,
   FileInfo,
   FileSystem,
+  GlobOptions,
   GrepQuery,
   GrepResult,
+  ListOptions,
   SearchQuery,
   SearchResult,
 } from "./filesystem.js";
@@ -78,6 +80,7 @@ export {
   DeleteNotSupportedError,
   EditError,
   emptyFs,
+  FILE_SYSTEM_SCAN_LIMIT,
   FileNotFoundError,
   hostFs,
   InvalidGrepPatternError,

package/src/internal/advertise-tools.ts

@@ -163,6 +163,9 @@ export async function resolveAdvertisedTools(args: {
         args.onConnectionError(connection.name, listing.error);
         continue;
       }
+      if (connection.optional === true) {
+        continue;
+      }
       throw new Error(
         `Failed to list tools on advertised connection "${connection.name}": ${describeError(listing.error)}`,
         { cause: listing.error }
@@ -181,6 +184,9 @@ export async function resolveAdvertisedTools(args: {
         args.onConnectionError(connection.name, error);
         continue;
       }
+      if (connection.optional === true) {
+        continue;
+      }
       throw error;
     }
     const intended = listed.filter(

package/src/internal/cli-ax.ts

@@ -790,6 +790,41 @@ async function cmdHostedSession(
   }
 }
 
+/**
+ * Shared deterministic-route fetch (`call`, `skill`): engine headers,
+ * bearer auth, and JSON. The payload is `undefined` when the body does
+ * not decode; callers print `invalid_response` and fail.
+ */
+async function fetchAgentJson(
+  target: ResolvedAgentTarget,
+  path: string,
+  args: { method?: string; body?: string; bearerToken?: string } = {}
+): Promise<{ response: Response; payload: unknown }> {
+  const headers: Record<string, string> = {};
+  if (target.headers !== undefined) {
+    Object.assign(headers, target.headers);
+  }
+  if (args.body !== undefined) {
+    headers["content-type"] = "application/json";
+  }
+  if (args.bearerToken !== undefined) {
+    headers.authorization = `Bearer ${args.bearerToken}`;
+  }
+  const response = await fetch(`${target.agentUrl}${path}`, {
+    method: args.method,
+    headers,
+    body: args.body,
+  });
+  const payload: unknown = await response.json().catch(() => undefined);
+  return { response, payload };
+}
+
+function printInvalidResponse(): void {
+  console.log(
+    JSON.stringify({ ok: false, error: "invalid_response" }, null, 2)
+  );
+}
+
 /**
  * `agent-sdk call <tool>` — deterministic tool invocation over
  * `POST /v1/tools/:toolName` (ephemeral local server unless --url).
@@ -816,30 +851,23 @@ export async function cmdCall(options: AxCliOptions): Promise<number> {
 
   const target = await resolveTarget(options);
   try {
-    const headers: Record<string, string> = {
-      "content-type": "application/json",
-    };
-    if (target.headers !== undefined) {
-      Object.assign(headers, target.headers);
-    }
-    if (options.bearerToken !== undefined) {
-      headers.authorization = `Bearer ${options.bearerToken}`;
-    }
     const body: { input: unknown; sessionId?: string } = { input };
     if (options.sessionId !== undefined) {
       body.sessionId = options.sessionId;
     }
-    const response = await fetch(
-      `${target.agentUrl}/v1/tools/${encodeURIComponent(toolName)}`,
+    const { response, payload } = await fetchAgentJson(
+      target,
+      `/v1/tools/${encodeURIComponent(toolName)}`,
       {
         method: "POST",
-        headers,
         body: JSON.stringify(body),
+        bearerToken: options.bearerToken,
       }
     );
-    const payload: unknown = await response
-      .json()
-      .catch(() => ({ ok: false, error: "invalid_response" }));
+    if (payload === undefined) {
+      printInvalidResponse();
+      return 1;
+    }
     console.log(JSON.stringify(payload, null, 2));
     const ok =
       response.ok &&
@@ -854,6 +882,51 @@ export async function cmdCall(options: AxCliOptions): Promise<number> {
   }
 }
 
+/**
+ * `agent-sdk skill <name>` — deterministic skill read over
+ * `GET /v1/skills/:skillName` (ephemeral local server unless --url).
+ * `--text` prints the rendered SKILL.md instead of JSON.
+ */
+export async function cmdSkill(
+  skillName: string | undefined,
+  options: AxCliOptions
+): Promise<number> {
+  if (skillName === undefined || skillName === "") {
+    process.stderr.write(
+      `Usage: ${CLI_COMMAND_NAME} skill <name> [--dir <path> | --url <baseUrl> | --prod]\n`
+    );
+    return 2;
+  }
+
+  const target = await resolveTarget(options);
+  try {
+    const { response, payload } = await fetchAgentJson(
+      target,
+      `/v1/skills/${encodeURIComponent(skillName)}`,
+      { bearerToken: options.bearerToken }
+    );
+    if (payload === undefined) {
+      printInvalidResponse();
+      return 1;
+    }
+    if (options.text === true && response.ok) {
+      const skillMd = (payload as { skillMd?: unknown }).skillMd;
+      if (typeof skillMd !== "string") {
+        printInvalidResponse();
+        return 1;
+      }
+      process.stdout.write(skillMd.endsWith("\n") ? skillMd : `${skillMd}\n`);
+      return 0;
+    }
+    console.log(JSON.stringify(payload, null, 2));
+    return response.ok ? 0 : 1;
+  } finally {
+    if (target.close !== undefined) {
+      await target.close();
+    }
+  }
+}
+
 export async function cmdTrajectory(options: AxCliOptions): Promise<number> {
   if (typeof options.events !== "string") {
     die(

package/src/internal/continuation-identity.ts

@@ -139,6 +139,7 @@ export const BUILTINS: readonly ContinuationBuiltin[] = [
       "pull_request.head_ref.pushed",
       "pull_request.base_ref.updated",
       "pull_request.closed",
+      "pull_request.reopened",
       "pull_request.merged",
       "pull_request.comment.created",
       "pull_request.review.submitted",

package/src/internal/cursor-agent-template.ts

@@ -11,6 +11,8 @@ const TEMPLATE_NAMES = [
   "pr-autofixer",
   "security-help",
   "security-reviewer",
+  "thermo-quality-review",
+  "thermo-review",
   "triage-linear",
   "triage-jira",
 ] as const;

package/src/internal/discovery/connections.ts

@@ -311,6 +311,26 @@ export async function compileConnection(
     });
     return undefined;
   }
+  if (
+    connection.optional !== undefined &&
+    typeof connection.optional !== "boolean"
+  ) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message: "MCP connection `optional` must be a boolean.",
+    });
+    return undefined;
+  }
+  if (connection.optional === true && connection.advertiseTools !== true) {
+    ctx.diagnostics.push({
+      severity: "error",
+      path: displayPath(ctx, entryPath),
+      message:
+        "MCP connection `optional` skips advertised listing failures; set `advertiseTools: true` or drop `optional`.",
+    });
+    return undefined;
+  }
   const parsedEffects = parseConnectionEffects(connection.effects);
   if (!parsedEffects.ok) {
     ctx.diagnostics.push({
@@ -471,6 +491,7 @@ export async function compileConnection(
     description: connection.description,
     auth: connection.auth,
     advertiseTools: connection.advertiseTools,
+    optional: connection.optional,
     effects: parsedEffects.value,
     tools: parsedTools.value,
     disallowedTools: parsedDisallowed.value,