feat(worker): home-scoped box file tree/read/write with realpath containment

apps/agent-worker/src/box.ts

@@ -1,6 +1,8 @@
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { env } from './env';
+import { assertContainedRealPath } from './path-containment';
 import {
   ensureUserContainer,
   inspectUserBoxStatus,
@@ -9,6 +11,14 @@ import {
 } from './runtime/docker';
 import { resetBox } from './user-container';
 
+// Matches FileTreeNode in apps/next/src/components/agent-workspace/types.ts.
+type FileTreeNode = {
+  name: string;
+  path: string;
+  type: 'file' | 'directory';
+  children?: FileTreeNode[];
+};
+
 // Per-user box home layout, shared by the HTTP routes and the terminal WS bridge
 // so path derivation lives in exactly one place (must match worker.ts).
 export const boxHomePaths = (username: string) => ({
@@ -43,3 +53,101 @@ export const restartBox = async (username: string): Promise<void> => {
   await stopBox(username);
   await startBox(username);
 };
+
+// Directories never surfaced in the box file tree — VCS internals, package
+// caches and build output that would bloat (or hang) the walk.
+const BOX_TREE_IGNORE = new Set([
+  '.git',
+  'node_modules',
+  '.cache',
+  '.npm',
+  '.bun',
+  '.cargo',
+  'dist',
+  'build',
+  '.next',
+]);
+
+// Home-relative paths (POSIX) that are always skipped regardless of depth.
+const BOX_TREE_IGNORE_PATHS = new Set(['.local/share/Trash']);
+
+// Guard against a huge home hanging the request; stop descending past this.
+const BOX_TREE_MAX_NODES = 5000;
+
+// Realpath-checked absolute path inside the user's home. Rejects lexical `..`
+// escapes and symlinks that resolve outside home (reuses the Phase-1
+// containment helper); for writes, also rejects a symlinked final target.
+const safeHomePath = (
+  homeDir: string,
+  relPath: string,
+  opts: { forWrite?: boolean } = {},
+): Promise<string> =>
+  assertContainedRealPath(homeDir, relPath, { ...opts, label: 'home' });
+
+export const listBoxTree = async (username: string): Promise<FileTreeNode> => {
+  const { homeDir } = boxHomePaths(username);
+  let count = 0;
+
+  const buildChildren = async (
+    absoluteDir: string,
+    relativeDir: string,
+  ): Promise<FileTreeNode[]> => {
+    const entries = await readdir(absoluteDir);
+    const nodes = await Promise.all(
+      entries
+        .sort((a, b) => a.localeCompare(b))
+        .map(async (entry): Promise<FileTreeNode | null> => {
+          const relativePath = relativeDir ? `${relativeDir}/${entry}` : entry;
+          if (
+            BOX_TREE_IGNORE.has(entry) ||
+            BOX_TREE_IGNORE_PATHS.has(relativePath)
+          ) {
+            return null;
+          }
+          if (count >= BOX_TREE_MAX_NODES) return null;
+          count += 1;
+          const absolutePath = path.join(absoluteDir, entry);
+          const stats = await stat(absolutePath).catch(() => null);
+          if (!stats) return null;
+          if (stats.isDirectory()) {
+            return {
+              name: entry,
+              path: relativePath,
+              type: 'directory',
+              children: await buildChildren(absolutePath, relativePath),
+            };
+          }
+          return { name: entry, path: relativePath, type: 'file' };
+        }),
+    );
+    return nodes.filter((node): node is FileTreeNode => Boolean(node));
+  };
+
+  return {
+    name: '~',
+    path: '',
+    type: 'directory',
+    children: await buildChildren(homeDir, ''),
+  };
+};
+
+export const readBoxFile = async (
+  username: string,
+  relPath: string,
+): Promise<string> => {
+  const { homeDir } = boxHomePaths(username);
+  const target = await safeHomePath(homeDir, relPath);
+  return await readFile(target, 'utf8');
+};
+
+export const writeBoxFile = async (
+  username: string,
+  relPath: string,
+  content: string,
+): Promise<{ success: true }> => {
+  const { homeDir } = boxHomePaths(username);
+  const target = await safeHomePath(homeDir, relPath, { forWrite: true });
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, content);
+  return { success: true };
+};

apps/agent-worker/src/path-containment.ts

@@ -21,13 +21,15 @@ const realpathOrDeepestExisting = async (target: string): Promise<string> => {
 export const assertContainedRealPath = async (
   root: string,
   requested: string,
-  opts: { forWrite?: boolean } = {},
+  opts: { forWrite?: boolean; label?: string } = {},
 ): Promise<string> => {
   const lexical = path.resolve(root, requested);
   const realRoot = await realpath(root);
   const resolved = await realpathOrDeepestExisting(lexical);
   if (resolved !== realRoot && !resolved.startsWith(`${realRoot}${path.sep}`)) {
-    throw new Error(`Refusing to access path outside root: ${requested}`);
+    throw new Error(
+      `Refusing to access path outside ${opts.label ?? 'root'}: ${requested}`,
+    );
   }
   if (opts.forWrite) {
     const info = await lstat(lexical).catch(() => null);