@ricsam/r5d-worker 0.0.30 → 0.0.31

package/dist/cjs/main.cjs

@@ -31,11 +31,17 @@ var main_exports = {};
 __export(main_exports, {
   ensureVisibleGitCheckout: () => ensureVisibleGitCheckout,
   findRepositorySyncBlockers: () => findRepositorySyncBlockers,
+  findWorkerFiles: () => findWorkerFiles,
+  grepWorkerFiles: () => grepWorkerFiles,
   isArtifactEnvPath: () => isArtifactEnvPath,
+  listWorkerDirectory: () => listWorkerDirectory,
   prepareArtifactEnvForShell: () => prepareArtifactEnvForShell,
   preparePlanEnvForShell: () => preparePlanEnvForShell,
+  readWorkerImageFile: () => readWorkerImageFile,
+  readWorkerTextFile: () => readWorkerTextFile,
   resolveHostShell: () => resolveHostShell,
   resolveProjectFilePath: () => resolveProjectFilePath,
+  resolveWorkerFilePath: () => resolveWorkerFilePath,
   syncManifestProjectsFromInternal: () => syncManifestProjectsFromInternal,
   syncProjectPlans: () => syncProjectPlans,
   syncSessionArtifacts: () => syncSessionArtifacts
@@ -706,36 +712,69 @@ function isInsideBranchPath(branchPath, filePath) {
   const relative = import_node_path.default.relative(import_node_path.default.resolve(branchPath), import_node_path.default.resolve(filePath));
   return relative === "" || relative !== ".." && !relative.startsWith(`..${import_node_path.default.sep}`) && !import_node_path.default.isAbsolute(relative);
 }
-function assertInsideBranch(branchPath, filePath) {
-  if (!isInsideBranchPath(branchPath, filePath)) {
-    throw new Error("File path escapes the project branch");
+function toProjectDisplayPath(branchPath, absolutePath) {
+  const relative = import_node_path.default.relative(import_node_path.default.resolve(branchPath), import_node_path.default.resolve(absolutePath)).split(import_node_path.default.sep).join(import_node_path.default.posix.sep);
+  return relative || ".";
+}
+function assertAllowedProjectPath(repoRelativePath, inputPath) {
+  if (repoRelativePath === ".git" || repoRelativePath.startsWith(".git/")) {
+    throw new Error("Refusing to access .git through worker file tools");
+  }
+  if (repoRelativePath.split("/").includes("..")) {
+    throw new Error(`Invalid project file path: ${inputPath}`);
   }
 }
-function resolveProjectFilePath(branchPath, virtualPath) {
-  if (typeof virtualPath !== "string" || !virtualPath.startsWith("/") || virtualPath.includes("\0")) {
-    throw new Error(`File path must be an absolute project path starting with /. Got: ${JSON.stringify(virtualPath)}`);
+function resolveWorkerFilePath(branchPath, inputPath) {
+  if (typeof inputPath !== "string" || inputPath.length === 0 || inputPath.includes("\0")) {
+    throw new Error(`File path must be a non-empty string. Got: ${JSON.stringify(inputPath)}`);
   }
-  const checkoutAbsolutePath = import_node_path.default.resolve(virtualPath);
-  if (isInsideBranchPath(branchPath, checkoutAbsolutePath)) {
-    const checkoutVirtualPath = toVirtualPath(import_node_path.default.resolve(branchPath), checkoutAbsolutePath);
-    if (checkoutVirtualPath !== virtualPath) {
-      return resolveProjectFilePath(branchPath, checkoutVirtualPath);
+  const resolvedBranchPath = import_node_path.default.resolve(branchPath);
+  if (import_node_path.default.isAbsolute(inputPath)) {
+    const absolutePath2 = import_node_path.default.resolve(inputPath);
+    if (!isInsideBranchPath(resolvedBranchPath, absolutePath2)) {
+      return {
+        absolutePath: absolutePath2,
+        displayPath: absolutePath2,
+        repoRelativePath: null,
+        scope: "host"
+      };
     }
+    const displayPath = toProjectDisplayPath(resolvedBranchPath, absolutePath2);
+    const repoRelativePath2 = displayPath === "." ? "" : displayPath;
+    assertAllowedProjectPath(repoRelativePath2, inputPath);
+    return {
+      absolutePath: absolutePath2,
+      displayPath,
+      repoRelativePath: repoRelativePath2,
+      scope: "project"
+    };
   }
-  if (virtualPath.split("/").includes("..")) {
-    throw new Error(`Invalid project file path: ${virtualPath}`);
+  const normalizedInputPath = inputPath.replace(/\\/g, "/");
+  if (normalizedInputPath.split("/").includes("..")) {
+    throw new Error(`Invalid project file path: ${inputPath}`);
   }
-  const normalized = import_node_path.default.posix.normalize(virtualPath);
-  if (normalized.startsWith("/../")) {
-    throw new Error(`Invalid project file path: ${virtualPath}`);
+  const normalized = import_node_path.default.posix.normalize(normalizedInputPath);
+  const repoRelativePath = normalized === "." ? "" : normalized.replace(/^\.\/+/, "");
+  assertAllowedProjectPath(repoRelativePath, inputPath);
+  const absolutePath = repoRelativePath ? import_node_path.default.resolve(resolvedBranchPath, ...repoRelativePath.split("/")) : resolvedBranchPath;
+  if (!isInsideBranchPath(resolvedBranchPath, absolutePath)) {
+    throw new Error(`Invalid project file path: ${inputPath}`);
   }
-  const repoRelativePath = normalized === "/" ? "" : normalized.slice(1);
-  if (repoRelativePath === ".git" || repoRelativePath.startsWith(".git/")) {
-    throw new Error("Refusing to access .git through worker file tools");
+  return {
+    absolutePath,
+    displayPath: repoRelativePath || ".",
+    repoRelativePath,
+    scope: "project"
+  };
+}
+function resolveProjectFilePath(branchPath, inputPath) {
+  const resolved = resolveWorkerFilePath(branchPath, inputPath);
+  if (resolved.scope === "host") {
+    throw new Error(
+      `Project file writes must use a checkout-relative path. Absolute host paths are read-only in file tools: ${inputPath}`
+    );
   }
-  const absolutePath = repoRelativePath ? import_node_path.default.resolve(branchPath, ...repoRelativePath.split("/")) : import_node_path.default.resolve(branchPath);
-  assertInsideBranch(branchPath, absolutePath);
-  return { absolutePath, virtualPath: repoRelativePath ? `/${repoRelativePath}` : "/", repoRelativePath };
+  return resolved;
 }
 function resolveRemoteUrl(baseUrl, remoteUrl) {
   if (/^https?:\/\//i.test(remoteUrl)) {
@@ -1349,6 +1388,21 @@ async function withFileMutationQueue(key, operation) {
 function mutationQueueKey(projectId, branchName, filePath) {
   return `${projectId}:${branchName}:${import_node_path.default.posix.normalize(filePath)}`;
 }
+function readWorkerTextFile(branchPath, filePath, offset, limit) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath);
+  if (!import_node_fs.default.existsSync(resolved.absolutePath) || !import_node_fs.default.statSync(resolved.absolutePath).isFile()) {
+    throw new Error(`File not found: ${resolved.displayPath}`);
+  }
+  const buffer = import_node_fs.default.readFileSync(resolved.absolutePath);
+  const formatted = formatLineNumberedContent(buffer.toString("utf8"), offset, limit);
+  return {
+    type: "read",
+    kind: "text",
+    file: resolved.displayPath,
+    gitBlobHash: getGitBlobHashForContent(buffer),
+    ...formatted
+  };
+}
 async function executeReadFileOperation(input) {
   const artifact = await resolveArtifactEnvFilePath({
     filePath: input.message.filePath,
@@ -1363,55 +1417,43 @@ async function executeReadFileOperation(input) {
     if (!import_node_fs.default.existsSync(artifact.absolutePath) || !import_node_fs.default.statSync(artifact.absolutePath).isFile()) {
       throw new Error(`File not found: ${artifact.virtualPath}`);
     }
-    const buffer2 = import_node_fs.default.readFileSync(artifact.absolutePath);
-    const formatted2 = formatLineNumberedContent(buffer2.toString("utf8"), input.message.offset, input.message.limit);
+    const buffer = import_node_fs.default.readFileSync(artifact.absolutePath);
+    const formatted = formatLineNumberedContent(buffer.toString("utf8"), input.message.offset, input.message.limit);
     return {
       type: "read",
       kind: "text",
       file: artifact.virtualPath,
-      gitBlobHash: getGitBlobHashForContent(buffer2),
-      ...formatted2
+      gitBlobHash: getGitBlobHashForContent(buffer),
+      ...formatted
     };
   }
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
-  if (!import_node_fs.default.existsSync(resolved.absolutePath) || !import_node_fs.default.statSync(resolved.absolutePath).isFile()) {
-    throw new Error(`File not found: ${resolved.virtualPath}`);
-  }
-  const buffer = import_node_fs.default.readFileSync(resolved.absolutePath);
-  const formatted = formatLineNumberedContent(buffer.toString("utf8"), input.message.offset, input.message.limit);
-  return {
-    type: "read",
-    kind: "text",
-    file: resolved.virtualPath,
-    gitBlobHash: getGitBlobHashForContent(buffer),
-    ...formatted
-  };
+  return readWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.offset, input.message.limit);
 }
 async function executeWriteFileOperation(input) {
   rejectArtifactWritePath(input.message.filePath);
-  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, input.message.filePath), async () => {
-    const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-    const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, resolved.repoRelativePath), async () => {
     import_node_fs.default.mkdirSync(import_node_path.default.dirname(resolved.absolutePath), { recursive: true });
     import_node_fs.default.writeFileSync(resolved.absolutePath, input.message.content, "utf8");
     return {
       type: "write",
-      file: resolved.virtualPath,
+      file: resolved.displayPath,
       gitBlobHash: getGitBlobHashForContent(input.message.content)
     };
   });
 }
 async function executeEditFileOperation(input) {
   rejectArtifactWritePath(input.message.filePath);
-  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, input.message.filePath), async () => {
-    const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-    const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, resolved.repoRelativePath), async () => {
     if (!Array.isArray(input.message.edits) || input.message.edits.length === 0) {
       throw new Error("edit requires at least one replacement");
     }
     if (!import_node_fs.default.existsSync(resolved.absolutePath) || !import_node_fs.default.statSync(resolved.absolutePath).isFile()) {
-      throw new Error(`File not found: ${resolved.virtualPath}`);
+      throw new Error(`File not found: ${resolved.displayPath}`);
     }
     const originalContent = import_node_fs.default.readFileSync(resolved.absolutePath, "utf8");
     const ranges = input.message.edits.map((edit, index) => {
@@ -1446,7 +1488,7 @@ async function executeEditFileOperation(input) {
     import_node_fs.default.writeFileSync(resolved.absolutePath, nextContent, "utf8");
     return {
       type: "edit",
-      file: resolved.virtualPath,
+      file: resolved.displayPath,
       edits: input.message.edits.length
     };
   });
@@ -1466,47 +1508,70 @@ function wildcardToRegex(pattern) {
 function normalizeFindPattern(pattern) {
   return /[*?]/.test(pattern) ? pattern : `*${pattern}*`;
 }
-function toVirtualPath(branchPath, absolutePath) {
-  const relative = import_node_path.default.relative(branchPath, absolutePath).split(import_node_path.default.sep).join(import_node_path.default.posix.sep);
-  return relative ? `/${relative}` : "/";
-}
-function walkProjectEntries(branchPath, startPath) {
+function walkWorkerEntries(branchPath, start) {
   const entries = [];
-  const visit = (absolutePath) => {
-    const stat = import_node_fs.default.statSync(absolutePath);
-    const virtualPath = toVirtualPath(branchPath, absolutePath);
-    entries.push({ absolutePath, virtualPath, stat });
+  const visitedDirectories = /* @__PURE__ */ new Set();
+  const visit = (absolutePath, isRoot) => {
+    let stat;
+    try {
+      stat = import_node_fs.default.statSync(absolutePath);
+    } catch (error) {
+      if (isRoot) throw error;
+      return;
+    }
+    const displayPath = start.scope === "project" ? toProjectDisplayPath(branchPath, absolutePath) : import_node_path.default.resolve(absolutePath);
+    const hostRelativePath = import_node_path.default.relative(start.absolutePath, absolutePath).split(import_node_path.default.sep).join(import_node_path.default.posix.sep);
+    const matchPath = start.scope === "project" ? displayPath : hostRelativePath || import_node_path.default.basename(start.absolutePath);
+    entries.push({ absolutePath, displayPath, matchPath, stat });
     if (!stat.isDirectory()) return;
-    const children = import_node_fs.default.readdirSync(absolutePath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    let realDirectoryPath;
+    try {
+      realDirectoryPath = import_node_fs.default.realpathSync(absolutePath);
+    } catch (error) {
+      if (isRoot) throw error;
+      return;
+    }
+    if (visitedDirectories.has(realDirectoryPath)) return;
+    visitedDirectories.add(realDirectoryPath);
+    let children;
+    try {
+      children = import_node_fs.default.readdirSync(absolutePath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch (error) {
+      if (isRoot) throw error;
+      return;
+    }
     for (const child of children) {
       if (IGNORED_ENTRY_NAMES.has(child.name)) continue;
-      visit(import_node_path.default.join(absolutePath, child.name));
+      visit(import_node_path.default.join(absolutePath, child.name), false);
     }
   };
-  visit(startPath);
+  visit(start.absolutePath, true);
   return entries;
 }
 function isProbablyText(bytes) {
   return !bytes.subarray(0, Math.min(bytes.length, 4096)).includes(0);
 }
-async function executeGrepOperation(input) {
-  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const start = resolveProjectFilePath(workspace.branchPath, input.message.path ?? "/");
+function grepWorkerFiles(branchPath, input) {
+  const start = resolveWorkerFilePath(branchPath, input.path ?? ".");
   if (!import_node_fs.default.existsSync(start.absolutePath)) {
-    throw new Error(`Path not found: ${start.virtualPath}`);
+    throw new Error(`Path not found: ${start.displayPath}`);
   }
-  const limit = normalizeToolLimit(input.message.limit, 100, 1e3);
-  const flags = input.message.caseSensitive === false ? "i" : "";
-  const regex = new RegExp(input.message.pattern, flags);
-  const globRegex = input.message.glob ? wildcardToRegex(input.message.glob) : null;
+  const limit = normalizeToolLimit(input.limit, 100, 1e3);
+  const flags = input.caseSensitive === false ? "i" : "";
+  const regex = new RegExp(input.pattern, flags);
+  const globRegex = input.glob ? wildcardToRegex(input.glob) : null;
   const lines = [];
   let matchCount = 0;
   let truncated = false;
-  for (const entry of walkProjectEntries(workspace.branchPath, start.absolutePath)) {
+  for (const entry of walkWorkerEntries(branchPath, start)) {
     if (!entry.stat.isFile()) continue;
-    const repoRelative = entry.virtualPath.slice(1);
-    if (globRegex && !globRegex.test(repoRelative)) continue;
-    const bytes = import_node_fs.default.readFileSync(entry.absolutePath);
+    if (globRegex && !globRegex.test(entry.matchPath)) continue;
+    let bytes;
+    try {
+      bytes = import_node_fs.default.readFileSync(entry.absolutePath);
+    } catch {
+      continue;
+    }
     if (!isProbablyText(bytes)) continue;
     const fileLines = bytes.toString("utf8").split(/\r?\n/);
     for (let index = 0; index < fileLines.length; index += 1) {
@@ -1517,7 +1582,7 @@ async function executeGrepOperation(input) {
       matchCount += 1;
       if (lines.length < limit) {
         const column = Math.max(1, (match.index ?? 0) + 1);
-        lines.push(`${entry.virtualPath}:${index + 1}:${column}: ${line.slice(0, MAX_LINE_LENGTH)}`);
+        lines.push(`${entry.displayPath}:${index + 1}:${column}: ${line.slice(0, MAX_LINE_LENGTH)}`);
       } else {
         truncated = true;
       }
@@ -1532,26 +1597,35 @@ async function executeGrepOperation(input) {
     truncated
   };
 }
-async function executeFindOperation(input) {
+async function executeGrepOperation(input) {
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const start = resolveProjectFilePath(workspace.branchPath, input.message.path ?? "/");
+  return grepWorkerFiles(workspace.branchPath, {
+    pattern: input.message.pattern,
+    path: input.message.path,
+    glob: input.message.glob,
+    caseSensitive: input.message.caseSensitive,
+    limit: input.message.limit
+  });
+}
+function findWorkerFiles(branchPath, input) {
+  const start = resolveWorkerFilePath(branchPath, input.path ?? ".");
   if (!import_node_fs.default.existsSync(start.absolutePath) || !import_node_fs.default.statSync(start.absolutePath).isDirectory()) {
-    throw new Error(`Directory not found: ${start.virtualPath}`);
+    throw new Error(`Directory not found: ${start.displayPath}`);
   }
-  const pattern = normalizeFindPattern(input.message.pattern ?? "*");
+  const pattern = normalizeFindPattern(input.pattern ?? "*");
   const matcher = wildcardToRegex(pattern);
-  const entryType = input.message.entryType ?? "file";
-  const limit = normalizeToolLimit(input.message.limit, 200, 1e3);
+  const entryType = input.entryType ?? "file";
+  const limit = normalizeToolLimit(input.limit, 200, 1e3);
   const matches = [];
   let count = 0;
   let truncated = false;
-  for (const entry of walkProjectEntries(workspace.branchPath, start.absolutePath)) {
-    if (entry.virtualPath === start.virtualPath) continue;
+  for (const entry of walkWorkerEntries(branchPath, start)) {
+    if (entry.absolutePath === start.absolutePath) continue;
     const isDirectory = entry.stat.isDirectory();
     if (entryType === "file" && !entry.stat.isFile()) continue;
     if (entryType === "directory" && !isDirectory) continue;
-    const label = isDirectory ? `${entry.virtualPath}/` : entry.virtualPath;
-    if (!matcher.test(import_node_path.default.posix.basename(entry.virtualPath)) && !matcher.test(entry.virtualPath.slice(1))) continue;
+    const label = isDirectory ? `${entry.displayPath}${start.scope === "host" ? import_node_path.default.sep : "/"}` : entry.displayPath;
+    if (!matcher.test(import_node_path.default.basename(entry.absolutePath)) && !matcher.test(entry.matchPath)) continue;
     count += 1;
     if (matches.length < limit) {
       matches.push(label);
@@ -1567,25 +1641,59 @@ async function executeFindOperation(input) {
     truncated
   };
 }
-async function executeLsOperation(input) {
+async function executeFindOperation(input) {
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.path ?? "/");
+  return findWorkerFiles(workspace.branchPath, {
+    pattern: input.message.pattern,
+    path: input.message.path,
+    entryType: input.message.entryType,
+    limit: input.message.limit
+  });
+}
+function listWorkerDirectory(branchPath, inputPath = ".", inputLimit) {
+  const resolved = resolveWorkerFilePath(branchPath, inputPath);
   if (!import_node_fs.default.existsSync(resolved.absolutePath) || !import_node_fs.default.statSync(resolved.absolutePath).isDirectory()) {
-    throw new Error(`Directory not found: ${resolved.virtualPath}`);
+    throw new Error(`Directory not found: ${resolved.displayPath}`);
   }
-  const limit = normalizeToolLimit(input.message.limit, 200, 1e3);
+  const limit = normalizeToolLimit(inputLimit, 200, 1e3);
   const entries = import_node_fs.default.readdirSync(resolved.absolutePath, { withFileTypes: true }).filter((entry) => !IGNORED_ENTRY_NAMES.has(entry.name)).sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
   const displayed = entries.slice(0, limit).map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`);
   const truncated = entries.length > displayed.length;
   const hint = truncated ? "\n... truncated. Increase limit to continue." : "";
   return {
     type: "ls",
-    path: resolved.virtualPath,
+    path: resolved.displayPath,
     content: displayed.length > 0 ? `${displayed.join("\n")}${hint}` : "(empty directory)",
     count: entries.length,
     truncated
   };
 }
+async function executeLsOperation(input) {
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  return listWorkerDirectory(workspace.branchPath, input.message.path, input.message.limit);
+}
+function readWorkerImageFile(branchPath, filePath) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath);
+  if (!import_node_fs.default.existsSync(resolved.absolutePath) || !import_node_fs.default.statSync(resolved.absolutePath).isFile()) {
+    throw new Error(`File not found: ${resolved.displayPath}`);
+  }
+  const extension = import_node_path.default.extname(resolved.absolutePath).toLowerCase();
+  const mediaType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".png" ? "image/png" : null;
+  if (!mediaType) {
+    throw new Error("read supports PNG and JPEG image inputs only");
+  }
+  const bytes = import_node_fs.default.readFileSync(resolved.absolutePath);
+  const dimensions = readImageDimensions(bytes, mediaType);
+  return {
+    type: "view_file_bytes",
+    filePath: resolved.displayPath,
+    mediaType,
+    base64: bytes.toString("base64"),
+    fileSizeBytes: bytes.length,
+    width: dimensions.width,
+    height: dimensions.height
+  };
+}
 async function executeViewFileBytesOperation(input) {
   const artifact = await resolveArtifactEnvFilePath({
     filePath: input.message.filePath,
@@ -1600,44 +1708,25 @@ async function executeViewFileBytesOperation(input) {
     if (!import_node_fs.default.existsSync(artifact.absolutePath) || !import_node_fs.default.statSync(artifact.absolutePath).isFile()) {
       throw new Error(`File not found: ${artifact.virtualPath}`);
     }
-    const extension2 = import_node_path.default.extname(artifact.absolutePath).toLowerCase();
-    const mediaType2 = extension2 === ".jpg" || extension2 === ".jpeg" ? "image/jpeg" : extension2 === ".png" ? "image/png" : null;
-    if (!mediaType2) {
+    const extension = import_node_path.default.extname(artifact.absolutePath).toLowerCase();
+    const mediaType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".png" ? "image/png" : null;
+    if (!mediaType) {
       throw new Error("read supports PNG and JPEG image inputs only");
     }
-    const bytes2 = import_node_fs.default.readFileSync(artifact.absolutePath);
-    const dimensions2 = readImageDimensions(bytes2, mediaType2);
+    const bytes = import_node_fs.default.readFileSync(artifact.absolutePath);
+    const dimensions = readImageDimensions(bytes, mediaType);
     return {
       type: "view_file_bytes",
       filePath: artifact.virtualPath,
-      mediaType: mediaType2,
-      base64: bytes2.toString("base64"),
-      fileSizeBytes: bytes2.length,
-      width: dimensions2.width,
-      height: dimensions2.height
+      mediaType,
+      base64: bytes.toString("base64"),
+      fileSizeBytes: bytes.length,
+      width: dimensions.width,
+      height: dimensions.height
     };
   }
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
-  if (!import_node_fs.default.existsSync(resolved.absolutePath) || !import_node_fs.default.statSync(resolved.absolutePath).isFile()) {
-    throw new Error(`File not found: ${resolved.virtualPath}`);
-  }
-  const extension = import_node_path.default.extname(resolved.absolutePath).toLowerCase();
-  const mediaType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".png" ? "image/png" : null;
-  if (!mediaType) {
-    throw new Error("read supports PNG and JPEG image inputs only");
-  }
-  const bytes = import_node_fs.default.readFileSync(resolved.absolutePath);
-  const dimensions = readImageDimensions(bytes, mediaType);
-  return {
-    type: "view_file_bytes",
-    filePath: resolved.virtualPath,
-    mediaType,
-    base64: bytes.toString("base64"),
-    fileSizeBytes: bytes.length,
-    width: dimensions.width,
-    height: dimensions.height
-  };
+  return readWorkerImageFile(workspace.branchPath, input.message.filePath);
 }
 function stagedBlobSizeBytes(context) {
   const names = runInternalGit(context, ["diff", "--cached", "--name-only", "-z", "--", ".", ":(exclude).git"]).split("\0").filter(Boolean);
@@ -2830,11 +2919,17 @@ if (isCliEntrypoint()) {
 0 && (module.exports = {
   ensureVisibleGitCheckout,
   findRepositorySyncBlockers,
+  findWorkerFiles,
+  grepWorkerFiles,
   isArtifactEnvPath,
+  listWorkerDirectory,
   prepareArtifactEnvForShell,
   preparePlanEnvForShell,
+  readWorkerImageFile,
+  readWorkerTextFile,
   resolveHostShell,
   resolveProjectFilePath,
+  resolveWorkerFilePath,
   syncManifestProjectsFromInternal,
   syncProjectPlans,
   syncSessionArtifacts

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "type": "commonjs"
 }

package/dist/mjs/main.mjs

@@ -663,36 +663,69 @@ function isInsideBranchPath(branchPath, filePath) {
   const relative = path.relative(path.resolve(branchPath), path.resolve(filePath));
   return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
-function assertInsideBranch(branchPath, filePath) {
-  if (!isInsideBranchPath(branchPath, filePath)) {
-    throw new Error("File path escapes the project branch");
+function toProjectDisplayPath(branchPath, absolutePath) {
+  const relative = path.relative(path.resolve(branchPath), path.resolve(absolutePath)).split(path.sep).join(path.posix.sep);
+  return relative || ".";
+}
+function assertAllowedProjectPath(repoRelativePath, inputPath) {
+  if (repoRelativePath === ".git" || repoRelativePath.startsWith(".git/")) {
+    throw new Error("Refusing to access .git through worker file tools");
+  }
+  if (repoRelativePath.split("/").includes("..")) {
+    throw new Error(`Invalid project file path: ${inputPath}`);
   }
 }
-function resolveProjectFilePath(branchPath, virtualPath) {
-  if (typeof virtualPath !== "string" || !virtualPath.startsWith("/") || virtualPath.includes("\0")) {
-    throw new Error(`File path must be an absolute project path starting with /. Got: ${JSON.stringify(virtualPath)}`);
+function resolveWorkerFilePath(branchPath, inputPath) {
+  if (typeof inputPath !== "string" || inputPath.length === 0 || inputPath.includes("\0")) {
+    throw new Error(`File path must be a non-empty string. Got: ${JSON.stringify(inputPath)}`);
   }
-  const checkoutAbsolutePath = path.resolve(virtualPath);
-  if (isInsideBranchPath(branchPath, checkoutAbsolutePath)) {
-    const checkoutVirtualPath = toVirtualPath(path.resolve(branchPath), checkoutAbsolutePath);
-    if (checkoutVirtualPath !== virtualPath) {
-      return resolveProjectFilePath(branchPath, checkoutVirtualPath);
+  const resolvedBranchPath = path.resolve(branchPath);
+  if (path.isAbsolute(inputPath)) {
+    const absolutePath2 = path.resolve(inputPath);
+    if (!isInsideBranchPath(resolvedBranchPath, absolutePath2)) {
+      return {
+        absolutePath: absolutePath2,
+        displayPath: absolutePath2,
+        repoRelativePath: null,
+        scope: "host"
+      };
     }
+    const displayPath = toProjectDisplayPath(resolvedBranchPath, absolutePath2);
+    const repoRelativePath2 = displayPath === "." ? "" : displayPath;
+    assertAllowedProjectPath(repoRelativePath2, inputPath);
+    return {
+      absolutePath: absolutePath2,
+      displayPath,
+      repoRelativePath: repoRelativePath2,
+      scope: "project"
+    };
   }
-  if (virtualPath.split("/").includes("..")) {
-    throw new Error(`Invalid project file path: ${virtualPath}`);
+  const normalizedInputPath = inputPath.replace(/\\/g, "/");
+  if (normalizedInputPath.split("/").includes("..")) {
+    throw new Error(`Invalid project file path: ${inputPath}`);
   }
-  const normalized = path.posix.normalize(virtualPath);
-  if (normalized.startsWith("/../")) {
-    throw new Error(`Invalid project file path: ${virtualPath}`);
+  const normalized = path.posix.normalize(normalizedInputPath);
+  const repoRelativePath = normalized === "." ? "" : normalized.replace(/^\.\/+/, "");
+  assertAllowedProjectPath(repoRelativePath, inputPath);
+  const absolutePath = repoRelativePath ? path.resolve(resolvedBranchPath, ...repoRelativePath.split("/")) : resolvedBranchPath;
+  if (!isInsideBranchPath(resolvedBranchPath, absolutePath)) {
+    throw new Error(`Invalid project file path: ${inputPath}`);
   }
-  const repoRelativePath = normalized === "/" ? "" : normalized.slice(1);
-  if (repoRelativePath === ".git" || repoRelativePath.startsWith(".git/")) {
-    throw new Error("Refusing to access .git through worker file tools");
+  return {
+    absolutePath,
+    displayPath: repoRelativePath || ".",
+    repoRelativePath,
+    scope: "project"
+  };
+}
+function resolveProjectFilePath(branchPath, inputPath) {
+  const resolved = resolveWorkerFilePath(branchPath, inputPath);
+  if (resolved.scope === "host") {
+    throw new Error(
+      `Project file writes must use a checkout-relative path. Absolute host paths are read-only in file tools: ${inputPath}`
+    );
   }
-  const absolutePath = repoRelativePath ? path.resolve(branchPath, ...repoRelativePath.split("/")) : path.resolve(branchPath);
-  assertInsideBranch(branchPath, absolutePath);
-  return { absolutePath, virtualPath: repoRelativePath ? `/${repoRelativePath}` : "/", repoRelativePath };
+  return resolved;
 }
 function resolveRemoteUrl(baseUrl, remoteUrl) {
   if (/^https?:\/\//i.test(remoteUrl)) {
@@ -1306,6 +1339,21 @@ async function withFileMutationQueue(key, operation) {
 function mutationQueueKey(projectId, branchName, filePath) {
   return `${projectId}:${branchName}:${path.posix.normalize(filePath)}`;
 }
+function readWorkerTextFile(branchPath, filePath, offset, limit) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath);
+  if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isFile()) {
+    throw new Error(`File not found: ${resolved.displayPath}`);
+  }
+  const buffer = fs.readFileSync(resolved.absolutePath);
+  const formatted = formatLineNumberedContent(buffer.toString("utf8"), offset, limit);
+  return {
+    type: "read",
+    kind: "text",
+    file: resolved.displayPath,
+    gitBlobHash: getGitBlobHashForContent(buffer),
+    ...formatted
+  };
+}
 async function executeReadFileOperation(input) {
   const artifact = await resolveArtifactEnvFilePath({
     filePath: input.message.filePath,
@@ -1320,55 +1368,43 @@ async function executeReadFileOperation(input) {
     if (!fs.existsSync(artifact.absolutePath) || !fs.statSync(artifact.absolutePath).isFile()) {
       throw new Error(`File not found: ${artifact.virtualPath}`);
     }
-    const buffer2 = fs.readFileSync(artifact.absolutePath);
-    const formatted2 = formatLineNumberedContent(buffer2.toString("utf8"), input.message.offset, input.message.limit);
+    const buffer = fs.readFileSync(artifact.absolutePath);
+    const formatted = formatLineNumberedContent(buffer.toString("utf8"), input.message.offset, input.message.limit);
     return {
       type: "read",
       kind: "text",
       file: artifact.virtualPath,
-      gitBlobHash: getGitBlobHashForContent(buffer2),
-      ...formatted2
+      gitBlobHash: getGitBlobHashForContent(buffer),
+      ...formatted
     };
   }
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
-  if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isFile()) {
-    throw new Error(`File not found: ${resolved.virtualPath}`);
-  }
-  const buffer = fs.readFileSync(resolved.absolutePath);
-  const formatted = formatLineNumberedContent(buffer.toString("utf8"), input.message.offset, input.message.limit);
-  return {
-    type: "read",
-    kind: "text",
-    file: resolved.virtualPath,
-    gitBlobHash: getGitBlobHashForContent(buffer),
-    ...formatted
-  };
+  return readWorkerTextFile(workspace.branchPath, input.message.filePath, input.message.offset, input.message.limit);
 }
 async function executeWriteFileOperation(input) {
   rejectArtifactWritePath(input.message.filePath);
-  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, input.message.filePath), async () => {
-    const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-    const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, resolved.repoRelativePath), async () => {
     fs.mkdirSync(path.dirname(resolved.absolutePath), { recursive: true });
     fs.writeFileSync(resolved.absolutePath, input.message.content, "utf8");
     return {
       type: "write",
-      file: resolved.virtualPath,
+      file: resolved.displayPath,
       gitBlobHash: getGitBlobHashForContent(input.message.content)
     };
   });
 }
 async function executeEditFileOperation(input) {
   rejectArtifactWritePath(input.message.filePath);
-  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, input.message.filePath), async () => {
-    const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-    const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
+  return withFileMutationQueue(mutationQueueKey(input.projectId, input.message.branchName, resolved.repoRelativePath), async () => {
     if (!Array.isArray(input.message.edits) || input.message.edits.length === 0) {
       throw new Error("edit requires at least one replacement");
     }
     if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isFile()) {
-      throw new Error(`File not found: ${resolved.virtualPath}`);
+      throw new Error(`File not found: ${resolved.displayPath}`);
     }
     const originalContent = fs.readFileSync(resolved.absolutePath, "utf8");
     const ranges = input.message.edits.map((edit, index) => {
@@ -1403,7 +1439,7 @@ async function executeEditFileOperation(input) {
     fs.writeFileSync(resolved.absolutePath, nextContent, "utf8");
     return {
       type: "edit",
-      file: resolved.virtualPath,
+      file: resolved.displayPath,
       edits: input.message.edits.length
     };
   });
@@ -1423,47 +1459,70 @@ function wildcardToRegex(pattern) {
 function normalizeFindPattern(pattern) {
   return /[*?]/.test(pattern) ? pattern : `*${pattern}*`;
 }
-function toVirtualPath(branchPath, absolutePath) {
-  const relative = path.relative(branchPath, absolutePath).split(path.sep).join(path.posix.sep);
-  return relative ? `/${relative}` : "/";
-}
-function walkProjectEntries(branchPath, startPath) {
+function walkWorkerEntries(branchPath, start) {
   const entries = [];
-  const visit = (absolutePath) => {
-    const stat = fs.statSync(absolutePath);
-    const virtualPath = toVirtualPath(branchPath, absolutePath);
-    entries.push({ absolutePath, virtualPath, stat });
+  const visitedDirectories = /* @__PURE__ */ new Set();
+  const visit = (absolutePath, isRoot) => {
+    let stat;
+    try {
+      stat = fs.statSync(absolutePath);
+    } catch (error) {
+      if (isRoot) throw error;
+      return;
+    }
+    const displayPath = start.scope === "project" ? toProjectDisplayPath(branchPath, absolutePath) : path.resolve(absolutePath);
+    const hostRelativePath = path.relative(start.absolutePath, absolutePath).split(path.sep).join(path.posix.sep);
+    const matchPath = start.scope === "project" ? displayPath : hostRelativePath || path.basename(start.absolutePath);
+    entries.push({ absolutePath, displayPath, matchPath, stat });
     if (!stat.isDirectory()) return;
-    const children = fs.readdirSync(absolutePath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    let realDirectoryPath;
+    try {
+      realDirectoryPath = fs.realpathSync(absolutePath);
+    } catch (error) {
+      if (isRoot) throw error;
+      return;
+    }
+    if (visitedDirectories.has(realDirectoryPath)) return;
+    visitedDirectories.add(realDirectoryPath);
+    let children;
+    try {
+      children = fs.readdirSync(absolutePath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    } catch (error) {
+      if (isRoot) throw error;
+      return;
+    }
     for (const child of children) {
       if (IGNORED_ENTRY_NAMES.has(child.name)) continue;
-      visit(path.join(absolutePath, child.name));
+      visit(path.join(absolutePath, child.name), false);
     }
   };
-  visit(startPath);
+  visit(start.absolutePath, true);
   return entries;
 }
 function isProbablyText(bytes) {
   return !bytes.subarray(0, Math.min(bytes.length, 4096)).includes(0);
 }
-async function executeGrepOperation(input) {
-  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const start = resolveProjectFilePath(workspace.branchPath, input.message.path ?? "/");
+function grepWorkerFiles(branchPath, input) {
+  const start = resolveWorkerFilePath(branchPath, input.path ?? ".");
   if (!fs.existsSync(start.absolutePath)) {
-    throw new Error(`Path not found: ${start.virtualPath}`);
+    throw new Error(`Path not found: ${start.displayPath}`);
   }
-  const limit = normalizeToolLimit(input.message.limit, 100, 1e3);
-  const flags = input.message.caseSensitive === false ? "i" : "";
-  const regex = new RegExp(input.message.pattern, flags);
-  const globRegex = input.message.glob ? wildcardToRegex(input.message.glob) : null;
+  const limit = normalizeToolLimit(input.limit, 100, 1e3);
+  const flags = input.caseSensitive === false ? "i" : "";
+  const regex = new RegExp(input.pattern, flags);
+  const globRegex = input.glob ? wildcardToRegex(input.glob) : null;
   const lines = [];
   let matchCount = 0;
   let truncated = false;
-  for (const entry of walkProjectEntries(workspace.branchPath, start.absolutePath)) {
+  for (const entry of walkWorkerEntries(branchPath, start)) {
     if (!entry.stat.isFile()) continue;
-    const repoRelative = entry.virtualPath.slice(1);
-    if (globRegex && !globRegex.test(repoRelative)) continue;
-    const bytes = fs.readFileSync(entry.absolutePath);
+    if (globRegex && !globRegex.test(entry.matchPath)) continue;
+    let bytes;
+    try {
+      bytes = fs.readFileSync(entry.absolutePath);
+    } catch {
+      continue;
+    }
     if (!isProbablyText(bytes)) continue;
     const fileLines = bytes.toString("utf8").split(/\r?\n/);
     for (let index = 0; index < fileLines.length; index += 1) {
@@ -1474,7 +1533,7 @@ async function executeGrepOperation(input) {
       matchCount += 1;
       if (lines.length < limit) {
         const column = Math.max(1, (match.index ?? 0) + 1);
-        lines.push(`${entry.virtualPath}:${index + 1}:${column}: ${line.slice(0, MAX_LINE_LENGTH)}`);
+        lines.push(`${entry.displayPath}:${index + 1}:${column}: ${line.slice(0, MAX_LINE_LENGTH)}`);
       } else {
         truncated = true;
       }
@@ -1489,26 +1548,35 @@ async function executeGrepOperation(input) {
     truncated
   };
 }
-async function executeFindOperation(input) {
+async function executeGrepOperation(input) {
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const start = resolveProjectFilePath(workspace.branchPath, input.message.path ?? "/");
+  return grepWorkerFiles(workspace.branchPath, {
+    pattern: input.message.pattern,
+    path: input.message.path,
+    glob: input.message.glob,
+    caseSensitive: input.message.caseSensitive,
+    limit: input.message.limit
+  });
+}
+function findWorkerFiles(branchPath, input) {
+  const start = resolveWorkerFilePath(branchPath, input.path ?? ".");
   if (!fs.existsSync(start.absolutePath) || !fs.statSync(start.absolutePath).isDirectory()) {
-    throw new Error(`Directory not found: ${start.virtualPath}`);
+    throw new Error(`Directory not found: ${start.displayPath}`);
   }
-  const pattern = normalizeFindPattern(input.message.pattern ?? "*");
+  const pattern = normalizeFindPattern(input.pattern ?? "*");
   const matcher = wildcardToRegex(pattern);
-  const entryType = input.message.entryType ?? "file";
-  const limit = normalizeToolLimit(input.message.limit, 200, 1e3);
+  const entryType = input.entryType ?? "file";
+  const limit = normalizeToolLimit(input.limit, 200, 1e3);
   const matches = [];
   let count = 0;
   let truncated = false;
-  for (const entry of walkProjectEntries(workspace.branchPath, start.absolutePath)) {
-    if (entry.virtualPath === start.virtualPath) continue;
+  for (const entry of walkWorkerEntries(branchPath, start)) {
+    if (entry.absolutePath === start.absolutePath) continue;
     const isDirectory = entry.stat.isDirectory();
     if (entryType === "file" && !entry.stat.isFile()) continue;
     if (entryType === "directory" && !isDirectory) continue;
-    const label = isDirectory ? `${entry.virtualPath}/` : entry.virtualPath;
-    if (!matcher.test(path.posix.basename(entry.virtualPath)) && !matcher.test(entry.virtualPath.slice(1))) continue;
+    const label = isDirectory ? `${entry.displayPath}${start.scope === "host" ? path.sep : "/"}` : entry.displayPath;
+    if (!matcher.test(path.basename(entry.absolutePath)) && !matcher.test(entry.matchPath)) continue;
     count += 1;
     if (matches.length < limit) {
       matches.push(label);
@@ -1524,25 +1592,59 @@ async function executeFindOperation(input) {
     truncated
   };
 }
-async function executeLsOperation(input) {
+async function executeFindOperation(input) {
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.path ?? "/");
+  return findWorkerFiles(workspace.branchPath, {
+    pattern: input.message.pattern,
+    path: input.message.path,
+    entryType: input.message.entryType,
+    limit: input.message.limit
+  });
+}
+function listWorkerDirectory(branchPath, inputPath = ".", inputLimit) {
+  const resolved = resolveWorkerFilePath(branchPath, inputPath);
   if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isDirectory()) {
-    throw new Error(`Directory not found: ${resolved.virtualPath}`);
+    throw new Error(`Directory not found: ${resolved.displayPath}`);
   }
-  const limit = normalizeToolLimit(input.message.limit, 200, 1e3);
+  const limit = normalizeToolLimit(inputLimit, 200, 1e3);
   const entries = fs.readdirSync(resolved.absolutePath, { withFileTypes: true }).filter((entry) => !IGNORED_ENTRY_NAMES.has(entry.name)).sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
   const displayed = entries.slice(0, limit).map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`);
   const truncated = entries.length > displayed.length;
   const hint = truncated ? "\n... truncated. Increase limit to continue." : "";
   return {
     type: "ls",
-    path: resolved.virtualPath,
+    path: resolved.displayPath,
     content: displayed.length > 0 ? `${displayed.join("\n")}${hint}` : "(empty directory)",
     count: entries.length,
     truncated
   };
 }
+async function executeLsOperation(input) {
+  const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
+  return listWorkerDirectory(workspace.branchPath, input.message.path, input.message.limit);
+}
+function readWorkerImageFile(branchPath, filePath) {
+  const resolved = resolveWorkerFilePath(branchPath, filePath);
+  if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isFile()) {
+    throw new Error(`File not found: ${resolved.displayPath}`);
+  }
+  const extension = path.extname(resolved.absolutePath).toLowerCase();
+  const mediaType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".png" ? "image/png" : null;
+  if (!mediaType) {
+    throw new Error("read supports PNG and JPEG image inputs only");
+  }
+  const bytes = fs.readFileSync(resolved.absolutePath);
+  const dimensions = readImageDimensions(bytes, mediaType);
+  return {
+    type: "view_file_bytes",
+    filePath: resolved.displayPath,
+    mediaType,
+    base64: bytes.toString("base64"),
+    fileSizeBytes: bytes.length,
+    width: dimensions.width,
+    height: dimensions.height
+  };
+}
 async function executeViewFileBytesOperation(input) {
   const artifact = await resolveArtifactEnvFilePath({
     filePath: input.message.filePath,
@@ -1557,44 +1659,25 @@ async function executeViewFileBytesOperation(input) {
     if (!fs.existsSync(artifact.absolutePath) || !fs.statSync(artifact.absolutePath).isFile()) {
       throw new Error(`File not found: ${artifact.virtualPath}`);
     }
-    const extension2 = path.extname(artifact.absolutePath).toLowerCase();
-    const mediaType2 = extension2 === ".jpg" || extension2 === ".jpeg" ? "image/jpeg" : extension2 === ".png" ? "image/png" : null;
-    if (!mediaType2) {
+    const extension = path.extname(artifact.absolutePath).toLowerCase();
+    const mediaType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".png" ? "image/png" : null;
+    if (!mediaType) {
       throw new Error("read supports PNG and JPEG image inputs only");
     }
-    const bytes2 = fs.readFileSync(artifact.absolutePath);
-    const dimensions2 = readImageDimensions(bytes2, mediaType2);
+    const bytes = fs.readFileSync(artifact.absolutePath);
+    const dimensions = readImageDimensions(bytes, mediaType);
     return {
       type: "view_file_bytes",
       filePath: artifact.virtualPath,
-      mediaType: mediaType2,
-      base64: bytes2.toString("base64"),
-      fileSizeBytes: bytes2.length,
-      width: dimensions2.width,
-      height: dimensions2.height
+      mediaType,
+      base64: bytes.toString("base64"),
+      fileSizeBytes: bytes.length,
+      width: dimensions.width,
+      height: dimensions.height
     };
   }
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
-  const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
-  if (!fs.existsSync(resolved.absolutePath) || !fs.statSync(resolved.absolutePath).isFile()) {
-    throw new Error(`File not found: ${resolved.virtualPath}`);
-  }
-  const extension = path.extname(resolved.absolutePath).toLowerCase();
-  const mediaType = extension === ".jpg" || extension === ".jpeg" ? "image/jpeg" : extension === ".png" ? "image/png" : null;
-  if (!mediaType) {
-    throw new Error("read supports PNG and JPEG image inputs only");
-  }
-  const bytes = fs.readFileSync(resolved.absolutePath);
-  const dimensions = readImageDimensions(bytes, mediaType);
-  return {
-    type: "view_file_bytes",
-    filePath: resolved.virtualPath,
-    mediaType,
-    base64: bytes.toString("base64"),
-    fileSizeBytes: bytes.length,
-    width: dimensions.width,
-    height: dimensions.height
-  };
+  return readWorkerImageFile(workspace.branchPath, input.message.filePath);
 }
 function stagedBlobSizeBytes(context) {
   const names = runInternalGit(context, ["diff", "--cached", "--name-only", "-z", "--", ".", ":(exclude).git"]).split("\0").filter(Boolean);
@@ -2786,11 +2869,17 @@ if (isCliEntrypoint()) {
 export {
   ensureVisibleGitCheckout,
   findRepositorySyncBlockers,
+  findWorkerFiles,
+  grepWorkerFiles,
   isArtifactEnvPath,
+  listWorkerDirectory,
   prepareArtifactEnvForShell,
   preparePlanEnvForShell,
+  readWorkerImageFile,
+  readWorkerTextFile,
   resolveHostShell,
   resolveProjectFilePath,
+  resolveWorkerFilePath,
   syncManifestProjectsFromInternal,
   syncProjectPlans,
   syncSessionArtifacts

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "type": "module"
 }

package/dist/types/main.d.ts

@@ -1,4 +1,16 @@
 #!/usr/bin/env bun
+type WorkerReadFileResult = {
+    type: "read";
+    kind: "text";
+    file: string;
+    gitBlobHash?: string;
+    content: string;
+    totalLines: number;
+    startLine: number;
+    endLine: number;
+    truncated: boolean;
+    continuation?: string;
+};
 type WorkerProjectManifestEntry = {
     projectId: string;
     repoSlug: string;
@@ -28,6 +40,34 @@ type WorkerRepositorySyncResult = {
         id: string;
     }>;
 };
+type WorkerGrepResult = {
+    type: "grep";
+    content: string;
+    matchCount: number;
+    truncated: boolean;
+};
+type WorkerFindResult = {
+    type: "find";
+    content: string;
+    count: number;
+    truncated: boolean;
+};
+type WorkerLsResult = {
+    type: "ls";
+    path: string;
+    content: string;
+    count: number;
+    truncated: boolean;
+};
+type WorkerViewFileBytesResult = {
+    type: "view_file_bytes";
+    filePath: string;
+    mediaType: "image/png" | "image/jpeg";
+    base64: string;
+    fileSizeBytes: number;
+    width: number;
+    height: number;
+};
 export declare function isArtifactEnvPath(filePath: string): boolean;
 export declare function syncSessionArtifacts(input: {
     baseUrl: string;
@@ -64,11 +104,21 @@ type GitAuth = {
     extraHeaderUrl: string;
     header: string;
 };
-export declare function resolveProjectFilePath(branchPath: string, virtualPath: string): {
+type ResolvedWorkerFilePath = {
     absolutePath: string;
-    virtualPath: string;
+    displayPath: string;
     repoRelativePath: string;
+    scope: "project";
+} | {
+    absolutePath: string;
+    displayPath: string;
+    repoRelativePath: null;
+    scope: "host";
 };
+export declare function resolveWorkerFilePath(branchPath: string, inputPath: string): ResolvedWorkerFilePath;
+export declare function resolveProjectFilePath(branchPath: string, inputPath: string): Extract<ResolvedWorkerFilePath, {
+    scope: "project";
+}>;
 export declare function ensureVisibleGitCheckout(input: {
     projectRoot: string;
     branchName: string;
@@ -99,6 +149,22 @@ export declare function syncManifestProjectsFromInternal(input: {
     manifests: WorkerProjectManifestEntry[];
     projectIds?: string[];
 }): Promise<WorkerRepositorySyncResult>;
+export declare function readWorkerTextFile(branchPath: string, filePath: string, offset?: number, limit?: number): WorkerReadFileResult;
+export declare function grepWorkerFiles(branchPath: string, input: {
+    pattern: string;
+    path?: string;
+    glob?: string;
+    caseSensitive?: boolean;
+    limit?: number;
+}): WorkerGrepResult;
+export declare function findWorkerFiles(branchPath: string, input: {
+    pattern?: string;
+    path?: string;
+    entryType?: string;
+    limit?: number;
+}): WorkerFindResult;
+export declare function listWorkerDirectory(branchPath: string, inputPath?: string, inputLimit?: number): WorkerLsResult;
+export declare function readWorkerImageFile(branchPath: string, filePath: string): WorkerViewFileBytesResult;
 export declare function resolveHostShell(command?: string, platform?: NodeJS.Platform): {
     file: string;
     args: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",