computer: Paginate ls results

Return file size and modification time from ls, and expose limit,
offset, and nextOffset so large directories can be read in stable pages.

Author: aron-cf

packages/computer/src/tools/ai.test.ts

@@ -289,7 +289,17 @@ describe("createAITools filesystem tools", () => {
     );
     await expect(executeTool(tools.ls, { path: "/workspace/notes" })).resolves.toEqual({
       path: "/workspace/notes",
-      entries: [{ name: "todo.txt", isFile: true, isDirectory: false }],
+      count: 1,
+      entries: [
+        {
+          name: "todo.txt",
+          size: 8,
+          mtime: 1_700_000_000_000,
+          isFile: true,
+          isDirectory: false,
+          isSymbolicLink: false,
+        },
+      ],
     });
     await expect(
       executeTool(tools.read, { path: "/workspace/notes/todo.txt", limit: 1 }),
@@ -313,6 +323,32 @@ describe("createAITools filesystem tools", () => {
     );
   });
 
+  it("paginates ls results and reports a continuation offset", async () => {
+    const workspace = makeWorkspace();
+    await workspace.fs.mkdir("/workspace", { recursive: true });
+    for (const name of ["a", "b", "c"]) {
+      await workspace.fs.writeFile(`/workspace/${name}`, name);
+    }
+    const tools = createAITools({ workspace });
+
+    await expect(
+      executeTool(tools.ls, { path: "/workspace", limit: 2, offset: 0 }),
+    ).resolves.toMatchObject({
+      count: 2,
+      entries: [
+        { name: "a", size: 1 },
+        { name: "b", size: 1 },
+      ],
+      nextOffset: 2,
+    });
+    await expect(
+      executeTool(tools.ls, { path: "/workspace", limit: 2, offset: 2 }),
+    ).resolves.toMatchObject({
+      count: 1,
+      entries: [{ name: "c", size: 1 }],
+    });
+  });
+
   it("preserves file mode when write overwrites an existing file", async () => {
     const writes: Array<{ path: string; content: string; mode?: number }> = [];
     const tool = createWriteTool({

packages/computer/src/tools/fs/list.ts

@@ -3,34 +3,75 @@ import { z } from "zod";
 
 export interface ListWorkspaceLike {
   fs: {
-    readdir(path: string): Promise<Array<{ name: string; isFile: boolean; isDirectory: boolean }>>;
+    readdir(
+      path: string,
+      options?: { limit?: number; offset?: number },
+    ): Promise<
+      Array<{
+        name: string;
+        size: number;
+        mtime: number;
+        isFile: boolean;
+        isDirectory: boolean;
+        isSymbolicLink: boolean;
+      }>
+    >;
   };
 }
 
 export interface ListToolOptions {
   workspace: ListWorkspaceLike;
 }
 
+const DEFAULT_LIMIT = 200;
+const MAX_LIMIT = 1000;
+
 const inputSchema = z.object({
   path: z.string().describe("Absolute directory path to list, e.g. /workspace/src."),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_LIMIT)
+    .optional()
+    .describe(`Maximum entries to return. Defaults to ${DEFAULT_LIMIT}.`),
+  offset: z.number().int().min(0).optional().describe("Number of entries to skip in name order."),
 });
 
 export function createListTool(options: ListToolOptions): Tool<z.infer<typeof inputSchema>> {
   return tool({
     description:
-      "List entries in a workspace directory. Returns each entry name and whether it is a file or directory.",
+      "List entries in a workspace directory with file sizes and modification times. Use limit and offset to page through large directories.",
     inputSchema,
-    execute: async ({ path }) => {
+    execute: async ({ path, limit, offset }) => {
       try {
-        const entries = await options.workspace.fs.readdir(path);
-        return {
+        const pageSize = limit ?? DEFAULT_LIMIT;
+        const pageOffset = offset ?? 0;
+        const entries = await options.workspace.fs.readdir(path, {
+          limit: pageSize + 1,
+          offset: pageOffset,
+        });
+        const truncated = entries.length > pageSize;
+        const page = (truncated ? entries.slice(0, pageSize) : entries).map((entry) => ({
+          name: entry.name,
+          size: entry.size,
+          mtime: entry.mtime,
+          isFile: entry.isFile,
+          isDirectory: entry.isDirectory,
+          isSymbolicLink: entry.isSymbolicLink,
+        }));
+        const result: {
+          path: string;
+          count: number;
+          entries: typeof page;
+          nextOffset?: number;
+        } = {
           path,
-          entries: entries.map((entry) => ({
-            name: entry.name,
-            isFile: entry.isFile,
-            isDirectory: entry.isDirectory,
-          })),
+          count: page.length,
+          entries: page,
         };
+        if (truncated) result.nextOffset = pageOffset + pageSize;
+        return result;
       } catch (err) {
         return { error: err instanceof Error ? err.message : String(err) };
       }