@cursor/july 0.1.103 → 0.1.105

package/src/internal/filesystem/scratch.ts

@@ -0,0 +1,255 @@
+/**
+ * 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/july` 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(),
+  })
+);