@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/runtime/routes/workspace-routes.ts

@@ -30,24 +30,15 @@ import {
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { RouteResponse } from "./types.js";
+import { walkWorkspaceTree } from "./workspace-tree-walk.js";
 import {
   isTextMimeType,
   MAX_INLINE_TEXT_SIZE,
   resolveWorkspacePath,
+  workspaceEntrySchema,
   writeWorkspaceFile,
 } from "./workspace-utils.js";
 
-const workspaceTreeEntrySchema = z.object({
-  name: z.string(),
-  path: z.string(),
-  type: z.enum(["file", "directory"]),
-  size: z.number().nullable(),
-  mimeType: z.string().nullable(),
-  modifiedAt: z.string(),
-});
-
-type TreeEntry = z.infer<typeof workspaceTreeEntrySchema>;
-
 // Recursive directory sizing walks the filesystem synchronously, so it is
 // bounded by two caps that work together:
 //
@@ -175,10 +166,11 @@ function publishSoundsConfigUpdatedForPaths(
 // GET /v1/workspace/tree — list directory contents
 // ---------------------------------------------------------------------------
 
-function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
+async function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
   const requestedPath = queryParams?.path ?? "";
   const showHidden = queryParams?.showHidden === "true";
   const includeDirSizes = queryParams?.includeDirSizes === "true";
+  const recursive = queryParams?.recursive === "true";
   const resolved = resolveWorkspacePath(requestedPath, {
     allowHidden: showHidden,
   });
@@ -186,62 +178,36 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
     throw new BadRequestError("Invalid path");
   }
 
-  try {
-    const dirents = readdirSync(resolved, { withFileTypes: true });
-    const workspaceDir = getWorkspaceDir();
-
-    // Listing-wide budget, only constructed when sizes are requested. Each
-    // directory draws a per-directory allotment from it so one oversized
-    // subtree can't starve its siblings, while the shared remainder still caps
-    // total synchronous traversal for the whole listing.
-    const listingBudget: DirSizeBudget | undefined = includeDirSizes
+  // Listing-wide budget, only constructed when sizes are requested. Each
+  // directory draws a per-directory allotment from it so one oversized
+  // subtree can't starve its siblings, while the shared remainder still caps
+  // total synchronous traversal for the whole listing.
+  const listingBudget: DirSizeBudget | undefined =
+    includeDirSizes && !recursive
       ? { remaining: DIR_SIZE_TOTAL_ENTRY_BUDGET }
       : undefined;
 
-    const entries: TreeEntry[] = [];
-    for (const entry of dirents) {
-      if (!showHidden && entry.name.startsWith(".")) {
-        continue;
-      }
-
-      const fullPath = join(resolved, entry.name);
-
-      let stats: ReturnType<typeof statSync>;
-      try {
-        stats = statSync(fullPath);
-      } catch {
-        continue;
-      }
-
-      const isDir = stats.isDirectory();
-      const relativePath = fullPath.slice(workspaceDir.length + 1);
-
-      const dirSize =
-        isDir && listingBudget
-          ? computeDirSizeWithinListing(fullPath, listingBudget)
-          : null;
-
-      entries.push({
-        name: entry.name,
-        path: relativePath,
-        type: isDir ? "directory" : "file",
-        size: isDir ? dirSize : stats.size,
-        mimeType: isDir ? null : Bun.file(fullPath).type,
-        modifiedAt: stats.mtime.toISOString(),
-      });
-    }
-
-    entries.sort((a, b) => {
-      if (a.type !== b.type) {
-        return a.type === "directory" ? -1 : 1;
-      }
-      return a.name.localeCompare(b.name);
+  let walk: Awaited<ReturnType<typeof walkWorkspaceTree>>;
+  try {
+    walk = await walkWorkspaceTree({
+      rootPath: resolved,
+      workspaceDir: getWorkspaceDir(),
+      showHidden,
+      recursive,
+      directorySize: listingBudget
+        ? (absPath) => computeDirSizeWithinListing(absPath, listingBudget)
+        : undefined,
     });
-
-    return { path: requestedPath, entries };
   } catch {
     throw new NotFoundError("Directory not found");
   }
+
+  return {
+    path: requestedPath,
+    entries: walk.entries,
+    truncated: walk.truncated,
+    skipped: walk.skipped,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -569,14 +535,31 @@ export const ROUTES: RouteDefinition[] = [
       {
         name: "includeDirSizes",
         description:
-          "Compute recursive byte size for each directory entry (true/false). Budget-bounded — large subtrees may return size: null.",
+          "Compute recursive byte size for each directory entry (true/false). Budget-bounded: large subtrees may return size: null. Not applied to a recursive listing, which carries every file for the client to sum.",
+      },
+      {
+        name: "recursive",
+        description:
+          "List the whole subtree in one response (true/false). Depth-first, each directory's entries in listing order, so grouping by parent path recovers per-directory listings. Bounded: sets truncated when the entry cap or deadline stops the walk, and does not enter directories the workspace gitignore rules exclude, which are named in skipped.",
       },
     ],
     responseBody: z.object({
       path: z.string(),
       entries: z
-        .array(workspaceTreeEntrySchema)
+        .array(workspaceEntrySchema)
         .describe("Directory entry objects"),
+      truncated: z
+        .boolean()
+        .optional()
+        .describe(
+          "A recursive walk stopped at its entry cap or deadline, so deeper entries are missing. Absent from assistants that predate recursive listings.",
+        ),
+      skipped: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Directories a recursive walk listed but did not enter, whether because a workspace gitignore rule excludes them, they are symlinks, or they could not be read. Each can still be listed on its own. Absent from assistants that predate recursive listings.",
+        ),
     }),
     handler: handleWorkspaceTree,
   },

package/src/runtime/routes/workspace-tree-walk.test.ts

@@ -0,0 +1,244 @@
+/**
+ * The recursive workspace walk: what it enters, what it lists without
+ * entering, the order it reports, and the bounds that stop it.
+ */
+import {
+  chmodSync,
+  mkdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { beforeAll, describe, expect, test } from "bun:test";
+
+import { walkWorkspaceTree } from "./workspace-tree-walk.js";
+
+const workspaceDir = process.env.VELLUM_WORKSPACE_DIR!;
+const root = join(workspaceDir, "walk-fixture");
+
+function write(relative: string, content = "x") {
+  const abs = join(root, relative);
+  mkdirSync(join(abs, ".."), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+beforeAll(() => {
+  mkdirSync(root, { recursive: true });
+  write("b-dir/deep/leaf.md");
+  write("b-dir/file-in-b.md");
+  write("a-dir/file-in-a.md");
+  write("top.md");
+  write(".secret/inside-hidden.md");
+  write("node_modules/dep/index.js");
+  // Rules with an inner slash (data/db/) anchor to the workspace root, so
+  // these live there rather than under the fixture directory.
+  mkdirSync(join(workspaceDir, "data", "db"), { recursive: true });
+  writeFileSync(join(workspaceDir, "data", "db", "state.sqlite"), "x");
+  mkdirSync(join(workspaceDir, "data", "avatar"), { recursive: true });
+  writeFileSync(join(workspaceDir, "data", "avatar", "face.png"), "x");
+  mkdirSync(join(workspaceDir, "walk-link-target"), { recursive: true });
+  writeFileSync(join(workspaceDir, "walk-link-target", "behind.md"), "x");
+  try {
+    symlinkSync(
+      join(workspaceDir, "walk-link-target"),
+      join(root, "linked"),
+      "dir",
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") {
+      throw err;
+    }
+  }
+});
+
+function walk(
+  overrides: Partial<Parameters<typeof walkWorkspaceTree>[0]> = {},
+) {
+  return walkWorkspaceTree({
+    rootPath: root,
+    workspaceDir,
+    showHidden: false,
+    recursive: true,
+    ...overrides,
+  });
+}
+
+describe("walkWorkspaceTree recursive", () => {
+  test("a non-recursive walk lists one level and reports nothing skipped", async () => {
+    const result = await walk({ recursive: false });
+    expect(result.entries.map((e) => e.path)).not.toContain(
+      "walk-fixture/a-dir/file-in-a.md",
+    );
+    expect(result.entries.map((e) => e.name)).toContain("a-dir");
+    expect(result).toMatchObject({ truncated: false, skipped: [] });
+  });
+
+  test("lists every level, depth-first, each directory in listing order", async () => {
+    const { entries } = await walk();
+    const paths = entries.map((e) => e.path.replace(/^walk-fixture\//, ""));
+    const indexOf = (p: string) => paths.indexOf(p);
+    expect(indexOf("a-dir/file-in-a.md")).toBeGreaterThan(-1);
+    expect(indexOf("b-dir/deep/leaf.md")).toBeGreaterThan(-1);
+    // Root listing first (directories before files), then a-dir's contents
+    // before b-dir's, and b-dir's subdirectory before its file.
+    expect(indexOf("a-dir")).toBeLessThan(indexOf("top.md"));
+    expect(indexOf("top.md")).toBeLessThan(indexOf("a-dir/file-in-a.md"));
+    expect(indexOf("a-dir/file-in-a.md")).toBeLessThan(indexOf("b-dir/deep"));
+    expect(indexOf("b-dir/deep")).toBeLessThan(indexOf("b-dir/file-in-b.md"));
+    expect(indexOf("b-dir/file-in-b.md")).toBeLessThan(
+      indexOf("b-dir/deep/leaf.md"),
+    );
+  });
+
+  test("grouping by parent recovers each directory's own listing", async () => {
+    const { entries } = await walk();
+    const shallow = await walkWorkspaceTree({
+      rootPath: join(root, "b-dir"),
+      workspaceDir,
+      showHidden: false,
+      recursive: false,
+    });
+    const underB = entries.filter(
+      (e) =>
+        e.path.startsWith("walk-fixture/b-dir/") &&
+        !e.path.slice("walk-fixture/b-dir/".length).includes("/"),
+    );
+    expect(underB.map((e) => e.path)).toEqual(
+      shallow.entries.map((e) => e.path),
+    );
+  });
+
+  test("paths use forward slashes", async () => {
+    const { entries } = await walk();
+    expect(entries.every((e) => !e.path.includes("\\"))).toBe(true);
+    expect(entries.map((e) => e.path)).toContain(
+      "walk-fixture/b-dir/deep/leaf.md",
+    );
+  });
+
+  test("hidden directories are neither listed nor entered unless asked", async () => {
+    const hidden = (await walk()).entries.map((e) => e.path);
+    expect(hidden).not.toContain("walk-fixture/.secret");
+    expect(hidden).not.toContain("walk-fixture/.secret/inside-hidden.md");
+    const shown = (await walk({ showHidden: true })).entries.map((e) => e.path);
+    expect(shown).toContain("walk-fixture/.secret/inside-hidden.md");
+  });
+
+  test("a dependency directory is listed at any depth but not entered", async () => {
+    const { entries, skipped } = await walk();
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("walk-fixture/node_modules");
+    expect(paths).not.toContain("walk-fixture/node_modules/dep");
+    expect(skipped).toContain("walk-fixture/node_modules");
+  });
+
+  test("root-anchored runtime state is listed, not entered, and named", async () => {
+    const { entries, skipped } = await walk({ rootPath: workspaceDir });
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("data/db");
+    expect(paths).not.toContain("data/db/state.sqlite");
+    // A directory the rules do not exclude is entered, and a file the rules
+    // match (*.png) is still listed: only descent is decided by them.
+    expect(paths).toContain("data/avatar/face.png");
+    expect(skipped).toContain("data/db");
+    expect(skipped).not.toContain("data/avatar");
+  });
+
+  test("a symlinked directory is listed, not entered, and reported skipped", async () => {
+    const { entries, skipped } = await walk();
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("walk-fixture/linked");
+    expect(paths).not.toContain("walk-fixture/linked/behind.md");
+    expect(skipped).toContain("walk-fixture/linked");
+  });
+
+  test("an unreadable directory is listed, not entered, and reported skipped", async () => {
+    // Root bypasses permission bits, so the check proves nothing there.
+    if (process.getuid?.() === 0) {
+      return;
+    }
+    const locked = join(root, "locked");
+    mkdirSync(locked, { recursive: true });
+    writeFileSync(join(locked, "inside.md"), "x");
+    chmodSync(locked, 0o000);
+    try {
+      const { entries, skipped, truncated } = await walk();
+      const paths = entries.map((e) => e.path);
+      expect(paths).toContain("walk-fixture/locked");
+      expect(paths).not.toContain("walk-fixture/locked/inside.md");
+      expect(skipped).toContain("walk-fixture/locked");
+      expect(truncated).toBe(false);
+    } finally {
+      chmodSync(locked, 0o755);
+      rmSync(locked, { recursive: true, force: true });
+    }
+  });
+
+  test("a directory wider than the remaining room is not scanned", async () => {
+    // Root (5) leaves one slot at a cap of 6; a-dir (1) fits and b-dir (2)
+    // does not. Nothing under b-dir is stat'd: its walk-time stat would
+    // otherwise show up as a listed entry.
+    const wide = join(root, "wide");
+    mkdirSync(wide, { recursive: true });
+    for (let i = 0; i < 50; i++) {
+      writeFileSync(join(wide, `w${i}.md`), "x");
+    }
+    try {
+      const result = await walk({ maxEntries: 7 });
+      const paths = result.entries.map((e) => e.path);
+      expect(paths).toContain("walk-fixture/wide");
+      expect(paths.some((p) => p.startsWith("walk-fixture/wide/"))).toBe(false);
+      expect(result.truncated).toBe(true);
+    } finally {
+      rmSync(wide, { recursive: true, force: true });
+    }
+  });
+
+  test("the deadline is honored inside a directory, not only between them", async () => {
+    // A clock that advances one second per read: the deadline is set at 0,
+    // the check before the first nested directory reads 1000 and passes,
+    // and the first entry inside it reads 2000 and stops the listing. Were
+    // the deadline checked only between directories, that one-entry
+    // directory would be carried and the walk would stop one step later.
+    let reads = 0;
+    const result = await walk({ maxWalkMs: 1500, now: () => reads++ * 1000 });
+    expect(result.truncated).toBe(true);
+    expect(result.entries.length).toBe(5);
+  });
+
+  test("the entry cap stops descent and reports truncated", async () => {
+    // The fixture root lists five entries and holds nine in all.
+    const result = await walk({ maxEntries: 6 });
+    expect(result.entries.length).toBeLessThanOrEqual(6);
+    expect(result.entries.length).toBeGreaterThanOrEqual(5);
+    expect(result.truncated).toBe(true);
+  });
+
+  test("a directory is carried whole or not at all", async () => {
+    // Root (5) plus a-dir (1) fit in 6; b-dir's two entries do not, so
+    // neither of them appears rather than one of them.
+    const { entries } = await walk({ maxEntries: 6 });
+    const paths = entries.map((e) => e.path);
+    expect(paths).toContain("walk-fixture/a-dir/file-in-a.md");
+    expect(paths).not.toContain("walk-fixture/b-dir/deep");
+    expect(paths).not.toContain("walk-fixture/b-dir/file-in-b.md");
+  });
+
+  test("the root listing is whole even under a cap smaller than it", async () => {
+    const result = await walk({ maxEntries: 1 });
+    expect(result.entries.map((e) => e.name)).toContain("top.md");
+    expect(result.truncated).toBe(true);
+  });
+
+  test("the deadline stops the walk and reports truncated", async () => {
+    const result = await walk({ maxWalkMs: -1 });
+    expect(result.truncated).toBe(true);
+  });
+
+  test("directory sizes are null in a recursive walk even when a sizer is given", async () => {
+    const { entries } = await walk({ directorySize: () => 42 });
+    const dir = entries.find((e) => e.type === "directory");
+    expect(dir?.size).toBeNull();
+  });
+});

package/src/runtime/routes/workspace-tree-walk.ts

@@ -0,0 +1,240 @@
+/**
+ * The directory walk behind GET /v1/workspace/tree.
+ *
+ * One directory by default. With `recursive`, the whole subtree in one
+ * response, so a client can search or expand without a request per folder.
+ * The walk yields the event loop between directories and is bounded by an
+ * entry cap and a deadline; it does not descend into the runtime-state
+ * directories the workspace's own gitignore rules name.
+ */
+import type { Dirent, Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join, sep } from "node:path";
+
+import ignore from "ignore";
+
+import { WORKSPACE_GITIGNORE_RULES } from "../../workspace/git-service.js";
+import type { WorkspaceEntry } from "./workspace-utils.js";
+
+/**
+ * Entries a recursive listing returns before it stops descending and
+ * reports `truncated`. The root's own listing is always whole, so the
+ * answer is never worse than a non-recursive one.
+ */
+export const MAX_RECURSIVE_ENTRIES = 20_000;
+
+/** Wall-clock budget for one recursive walk. */
+export const MAX_RECURSIVE_WALK_MS = 3_000;
+
+/**
+ * Directories the recursive walk lists but does not enter: whatever the
+ * workspace's own gitignore rules exclude (databases, caches, dependency
+ * trees, logs), which is the one maintained statement of what in a
+ * workspace is runtime state rather than the user's files. Files those rules
+ * match are still listed; only descent is decided here.
+ */
+const descentRules = ignore().add(WORKSPACE_GITIGNORE_RULES);
+
+/** git never lists its own metadata directory, and neither does this walk. */
+const GIT_DIR = ".git";
+
+function isDescentSkipped(relativeDirPath: string, name: string): boolean {
+  return name === GIT_DIR || descentRules.ignores(`${relativeDirPath}/`);
+}
+
+export interface WorkspaceTreeWalk {
+  entries: WorkspaceEntry[];
+  /** The entry cap or the deadline stopped a recursive walk early. */
+  truncated: boolean;
+  /**
+   * Workspace-relative directories the walk listed but did not enter, for
+   * any reason: a gitignore rule, a symlink, or a directory that could not
+   * be read. A client that wants their contents asks for them one at a time.
+   */
+  skipped: string[];
+}
+
+export interface WorkspaceTreeWalkOptions {
+  /** Absolute directory to list. */
+  rootPath: string;
+  /** Absolute workspace root; entry paths are relative to it. */
+  workspaceDir: string;
+  showHidden: boolean;
+  recursive: boolean;
+  /**
+   * Per-directory size for directory entries in a non-recursive listing.
+   * Ignored when `recursive`, where directories report `size: null`.
+   */
+  directorySize?: (absPath: string) => number | null;
+  maxEntries?: number;
+  maxWalkMs?: number;
+  /** Clock for the deadline. Tests hand in a scripted one. */
+  now?: () => number;
+}
+
+function byDirectoriesThenName(a: WorkspaceEntry, b: WorkspaceEntry): number {
+  if (a.type !== b.type) {
+    return a.type === "directory" ? -1 : 1;
+  }
+  return a.name.localeCompare(b.name);
+}
+
+interface ListedDirectory {
+  entries: WorkspaceEntry[];
+  /** Directory entries in listing order, with whether each is a symlink. */
+  subdirectories: Array<{
+    absPath: string;
+    relativePath: string;
+    name: string;
+    isSymlink: boolean;
+  }>;
+}
+
+/**
+ * What a nested directory may cost a recursive walk. The listing stops
+ * before any stat work when the directory has more entries than the
+ * response has room for, and between stats once the deadline passes, so a
+ * single wide or slow directory cannot carry the walk past its bound.
+ */
+interface ListingBudget {
+  room: number;
+  deadline: number;
+}
+
+/**
+ * One directory's entries, sorted directories first then by name. Types
+ * follow `stat`, so a symlinked directory reads as a directory; the caller
+ * decides whether to enter it. Returns `null` when a budget stops the
+ * listing, in which case none of it is reported.
+ */
+async function listDirectory(
+  absDir: string,
+  {
+    workspaceDir,
+    showHidden,
+    directorySize,
+    now = Date.now,
+  }: WorkspaceTreeWalkOptions,
+  budget?: ListingBudget,
+): Promise<ListedDirectory | null> {
+  const dirents: Dirent[] = (
+    await readdir(absDir, { withFileTypes: true })
+  ).filter((dirent) => showHidden || !dirent.name.startsWith("."));
+  if (budget && dirents.length > budget.room) {
+    return null;
+  }
+  const entries: WorkspaceEntry[] = [];
+  const subdirectories: ListedDirectory["subdirectories"] = [];
+
+  for (const dirent of dirents) {
+    if (budget && now() > budget.deadline) {
+      return null;
+    }
+    const absPath = join(absDir, dirent.name);
+    let stats: Stats;
+    try {
+      stats = await stat(absPath);
+    } catch {
+      continue;
+    }
+    const isDir = stats.isDirectory();
+    // Wire paths use "/" on every host; clients key expansion and
+    // ancestry on them and never see the daemon's own separator.
+    const relativePath = absPath
+      .slice(workspaceDir.length + 1)
+      .split(sep)
+      .join("/");
+    entries.push({
+      name: dirent.name,
+      path: relativePath,
+      type: isDir ? "directory" : "file",
+      size: isDir ? (directorySize?.(absPath) ?? null) : stats.size,
+      mimeType: isDir ? null : Bun.file(absPath).type,
+      modifiedAt: stats.mtime.toISOString(),
+    });
+    if (isDir) {
+      subdirectories.push({
+        absPath,
+        relativePath,
+        name: dirent.name,
+        isSymlink: dirent.isSymbolicLink(),
+      });
+    }
+  }
+
+  entries.sort(byDirectoriesThenName);
+  subdirectories.sort((a, b) => a.name.localeCompare(b.name));
+  return { entries, subdirectories };
+}
+
+/**
+ * List `rootPath`. A recursive walk is depth-first with each directory's
+ * entries in listing order and never part of a directory, so grouping the
+ * result by parent path gives every directory's listing exactly as a
+ * non-recursive request would, or nothing for it at all.
+ *
+ * Symlinked directories are listed but never entered, so a link cannot make
+ * the walk cycle or leave the workspace; they are reported in `skipped`, as
+ * is a directory found mid-walk that cannot be read. The root's own read
+ * error is the caller's to report.
+ */
+export async function walkWorkspaceTree(
+  options: WorkspaceTreeWalkOptions,
+): Promise<WorkspaceTreeWalk> {
+  const {
+    rootPath,
+    recursive,
+    maxEntries = MAX_RECURSIVE_ENTRIES,
+    maxWalkMs = MAX_RECURSIVE_WALK_MS,
+    now = Date.now,
+  } = options;
+  // A recursive listing carries every file, so a client sums directory
+  // sizes itself and no per-directory sizer runs.
+  const listOptions = recursive
+    ? { ...options, directorySize: undefined }
+    : options;
+  // The root is listed without a budget: its listing is always whole.
+  const root = (await listDirectory(rootPath, listOptions))!;
+  if (!recursive) {
+    return { entries: root.entries, truncated: false, skipped: [] };
+  }
+
+  const deadline = now() + maxWalkMs;
+  const entries: WorkspaceEntry[] = [...root.entries];
+  const skipped: string[] = [];
+  // Reversed so the stack pops subdirectories in listing order.
+  const stack = root.subdirectories.slice().reverse();
+
+  while (stack.length > 0) {
+    const dir = stack.pop()!;
+    if (dir.isSymlink || isDescentSkipped(dir.relativePath, dir.name)) {
+      skipped.push(dir.relativePath);
+      continue;
+    }
+    if (entries.length >= maxEntries || now() > deadline) {
+      return { entries, truncated: true, skipped };
+    }
+
+    let listed: ListedDirectory | null;
+    try {
+      listed = await listDirectory(dir.absPath, listOptions, {
+        room: maxEntries - entries.length,
+        deadline,
+      });
+    } catch {
+      skipped.push(dir.relativePath);
+      continue;
+    }
+    // A directory is carried whole or not at all, so a client grouping the
+    // result by parent never mistakes part of a listing for all of it.
+    if (listed === null) {
+      return { entries, truncated: true, skipped };
+    }
+    entries.push(...listed.entries);
+    for (let i = listed.subdirectories.length - 1; i >= 0; i--) {
+      stack.push(listed.subdirectories[i]);
+    }
+  }
+
+  return { entries, truncated: false, skipped };
+}

package/src/runtime/routes/workspace-utils.ts

@@ -8,9 +8,26 @@ import {
 } from "node:fs";
 import { dirname, resolve, sep } from "node:path";
 
+import { z } from "zod";
+
 import { getWorkspaceDir } from "../../util/platform.js";
 import { BadRequestError, ConflictError } from "./errors.js";
 
+/**
+ * One workspace entry as the tree endpoint reports it. `size` is null for a
+ * directory whose recursive size was not computed.
+ */
+export const workspaceEntrySchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  type: z.enum(["file", "directory"]),
+  size: z.number().nullable(),
+  mimeType: z.string().nullable(),
+  modifiedAt: z.string(),
+});
+
+export type WorkspaceEntry = z.infer<typeof workspaceEntrySchema>;
+
 /**
  * Resolves a user-provided relative path to an absolute path within the workspace.
  * Returns the resolved absolute path, or undefined if the path escapes the workspace root.