@ricsam/r5d-worker 0.0.10 → 0.0.11

package/dist/cjs/main.cjs

@@ -29,7 +29,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var main_exports = {};
 __export(main_exports, {
-  ensureVisibleGitCheckout: () => ensureVisibleGitCheckout
+  ensureVisibleGitCheckout: () => ensureVisibleGitCheckout,
+  isArtifactEnvPath: () => isArtifactEnvPath,
+  syncSessionArtifacts: () => syncSessionArtifacts
 });
 module.exports = __toCommonJS(main_exports);
 var import_node_fs = __toESM(require("node:fs"), 1);
@@ -64,6 +66,9 @@ function defaultProjectsRoot() {
 function defaultSyncRoot() {
   return import_node_path.default.join(import_node_os.default.homedir(), ".r5d", "sync");
 }
+function defaultArtifactRoot() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".r5d", "artifacts");
+}
 function printHelp() {
   process.stdout.write(`Usage:
   r5d-worker start --label <label> [--base-url <url>] [--token <token>] [--api-key <key>]
@@ -77,6 +82,7 @@ Options:
   --config <path>       Config path (default ~/.config/r5d/r5dctl/config.json)
   --project-root <dir>  Override projects checkout root (default ~/.r5d/projects)
   --sync-root <dir>     Override r5d internal sync git root (default ~/.r5d/sync)
+  --artifact-root <dir> Override session artifact root (default from R5D_ARTIFACTS_ROOT or ~/.r5d/artifacts)
   -v, --version         Show r5d-worker version
   -h, --help            Show this help
 `);
@@ -193,6 +199,11 @@ function parseArgs(argv) {
       options.syncRoot = syncRoot;
       continue;
     }
+    const artifactRoot = readOption("--artifact-root");
+    if (artifactRoot !== void 0) {
+      options.artifactRoot = artifactRoot;
+      continue;
+    }
     rest.push(arg);
   }
   if (options.version) {
@@ -235,6 +246,170 @@ async function readResponseText(response) {
     return "";
   }
 }
+const R5D_ARTIFACTS_DIR_REF = "$R5D_ARTIFACTS_DIR";
+function validateArtifactSessionId(sessionId) {
+  if (!/^(migration-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId)) {
+    throw new Error(`Invalid artifact session id: ${sessionId}`);
+  }
+}
+function assertInsideRoot(rootPath, candidatePath, label) {
+  const relative = import_node_path.default.relative(rootPath, candidatePath);
+  if (relative === ".." || relative.startsWith(`..${import_node_path.default.sep}`) || import_node_path.default.isAbsolute(relative)) {
+    throw new Error(`${label} escapes the artifact directory`);
+  }
+}
+function sessionArtifactDir(artifactRoot, sessionId) {
+  validateArtifactSessionId(sessionId);
+  return import_node_path.default.join(artifactRoot, sessionId);
+}
+function artifactEnv(artifactRoot, sessionId) {
+  if (!sessionId) {
+    return {};
+  }
+  return {
+    R5D_ARTIFACTS_DIR: sessionArtifactDir(artifactRoot, sessionId)
+  };
+}
+function isArtifactEnvPath(filePath) {
+  return filePath === R5D_ARTIFACTS_DIR_REF || filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`);
+}
+function artifactApiBasePath(projectId, branchName, sessionId) {
+  return `/preview-api/${encodeURIComponent(projectId)}/${encodeURIComponent(branchName)}/artifacts/${encodeURIComponent(sessionId)}`;
+}
+function artifactManifestUrl(baseUrl, projectId, branchName, sessionId) {
+  return new URL(artifactApiBasePath(projectId, branchName, sessionId), baseUrl);
+}
+function artifactDownloadUrl(baseUrl, projectId, branchName, sessionId, filename) {
+  return new URL(`${artifactApiBasePath(projectId, branchName, sessionId)}/${encodeURIComponent(filename)}`, baseUrl);
+}
+function sha256Path(filePath) {
+  return (0, import_node_crypto.createHash)("sha256").update(import_node_fs.default.readFileSync(filePath)).digest("hex");
+}
+function parseSessionArtifactManifest(value) {
+  if (!value || typeof value !== "object" || !Array.isArray(value.artifacts)) {
+    throw new Error("Artifact manifest response is invalid");
+  }
+  return value.artifacts.map((entry) => {
+    if (!entry || typeof entry !== "object") {
+      throw new Error("Artifact manifest entry is invalid");
+    }
+    const artifact = entry;
+    if (typeof artifact.filename !== "string" || artifact.filename.includes("/") || artifact.filename.includes("\\")) {
+      throw new Error("Artifact manifest entry has an invalid filename");
+    }
+    if (typeof artifact.size !== "number" || !Number.isFinite(artifact.size) || artifact.size < 0) {
+      throw new Error(`Artifact manifest entry has an invalid size: ${artifact.filename}`);
+    }
+    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(artifact.sha256)) {
+      throw new Error(`Artifact manifest entry has an invalid sha256: ${artifact.filename}`);
+    }
+    return {
+      filename: artifact.filename,
+      size: artifact.size,
+      sha256: artifact.sha256.toLowerCase()
+    };
+  });
+}
+async function fetchSessionArtifactManifest(input) {
+  const response = await fetch(artifactManifestUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId), {
+    headers: {
+      Authorization: `Bearer ${input.token}`
+    }
+  });
+  if (!response.ok) {
+    const detail = (await readResponseText(response)).trim();
+    throw new Error(`Failed to fetch artifact manifest (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+  return parseSessionArtifactManifest(await response.json());
+}
+async function downloadSessionArtifact(input) {
+  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
+  const targetPath = import_node_path.default.join(targetDir, input.artifact.filename);
+  assertInsideRoot(targetDir, targetPath, "Artifact path");
+  const response = await fetch(
+    artifactDownloadUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId, input.artifact.filename),
+    {
+      headers: {
+        Authorization: `Bearer ${input.token}`
+      }
+    }
+  );
+  if (!response.ok) {
+    const detail = (await readResponseText(response)).trim();
+    throw new Error(`Failed to download artifact ${input.artifact.filename} (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  const receivedHash = (0, import_node_crypto.createHash)("sha256").update(buffer).digest("hex");
+  if (receivedHash !== input.artifact.sha256) {
+    throw new Error(`Downloaded artifact ${input.artifact.filename} failed sha256 verification`);
+  }
+  if (buffer.length !== input.artifact.size) {
+    throw new Error(`Downloaded artifact ${input.artifact.filename} has unexpected size`);
+  }
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  import_node_fs.default.writeFileSync(tempPath, buffer);
+  import_node_fs.default.renameSync(tempPath, targetPath);
+}
+async function syncSessionArtifacts(input) {
+  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
+  import_node_fs.default.mkdirSync(targetDir, { recursive: true });
+  const artifacts = await fetchSessionArtifactManifest(input);
+  const manifestNames = new Set(artifacts.map((artifact) => artifact.filename));
+  for (const artifact of artifacts) {
+    const localPath = import_node_path.default.join(targetDir, artifact.filename);
+    assertInsideRoot(targetDir, localPath, "Artifact path");
+    if (import_node_fs.default.existsSync(localPath)) {
+      const stats = import_node_fs.default.statSync(localPath);
+      if (stats.isFile() && stats.size === artifact.size && sha256Path(localPath) === artifact.sha256) {
+        continue;
+      }
+      import_node_fs.default.rmSync(localPath, { recursive: true, force: true });
+    }
+    await downloadSessionArtifact({ ...input, artifact });
+  }
+  for (const localName of import_node_fs.default.readdirSync(targetDir)) {
+    if (!manifestNames.has(localName)) {
+      const localPath = import_node_path.default.join(targetDir, localName);
+      assertInsideRoot(targetDir, localPath, "Artifact path");
+      import_node_fs.default.rmSync(localPath, { recursive: true, force: true });
+    }
+  }
+  return targetDir;
+}
+async function resolveArtifactEnvFilePath(input) {
+  if (!isArtifactEnvPath(input.filePath)) {
+    return null;
+  }
+  if (!input.sessionId) {
+    throw new Error(`${R5D_ARTIFACTS_DIR_REF} paths require an active chat session`);
+  }
+  if (!input.filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`)) {
+    throw new Error(`Artifact path must reference a file under ${R5D_ARTIFACTS_DIR_REF}/`);
+  }
+  const targetDir = await syncSessionArtifacts({
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.branchName,
+    sessionId: input.sessionId,
+    artifactRoot: input.artifactRoot
+  });
+  const relativePath = import_node_path.default.posix.normalize(input.filePath.slice(`${R5D_ARTIFACTS_DIR_REF}/`.length));
+  if (!relativePath || relativePath === "." || relativePath.startsWith("../") || relativePath.includes("\0")) {
+    throw new Error(`Invalid artifact path: ${input.filePath}`);
+  }
+  const absolutePath = import_node_path.default.resolve(targetDir, ...relativePath.split("/"));
+  assertInsideRoot(targetDir, absolutePath, "Artifact path");
+  return {
+    absolutePath,
+    virtualPath: `${R5D_ARTIFACTS_DIR_REF}/${relativePath}`
+  };
+}
+function rejectArtifactWritePath(filePath) {
+  if (isArtifactEnvPath(filePath)) {
+    throw new Error(`${R5D_ARTIFACTS_DIR_REF} attachments are read-only. Copy them into a project path before editing or creating files.`);
+  }
+}
 async function verifyR5dctlAuth(baseUrl, token) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
   let response;
@@ -823,6 +998,28 @@ function readImageDimensions(bytes, mediaType) {
   return dimensions;
 }
 async function executeReadFileOperation(input) {
+  const artifact = await resolveArtifactEnvFilePath({
+    filePath: input.message.filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    artifactRoot: input.artifactRoot
+  });
+  if (artifact) {
+    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);
+    return {
+      type: "read_file",
+      file: artifact.virtualPath,
+      gitBlobHash: getGitBlobHashForContent(buffer2),
+      ...formatted2
+    };
+  }
   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()) {
@@ -838,6 +1035,7 @@ async function executeReadFileOperation(input) {
   };
 }
 async function executeCreateFileOperation(input) {
+  rejectArtifactWritePath(input.message.filePath);
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
   const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
   if (import_node_fs.default.existsSync(resolved.absolutePath)) {
@@ -852,6 +1050,7 @@ async function executeCreateFileOperation(input) {
   };
 }
 async function executeEditFileOperation(input) {
+  rejectArtifactWritePath(input.message.filePath);
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
   const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
   if (input.message.oldString === input.message.newString) {
@@ -901,6 +1100,7 @@ function normalizePatchPath(rawPath) {
   if (patchPath.startsWith("a/") || patchPath.startsWith("b/")) {
     patchPath = patchPath.slice(2);
   }
+  rejectArtifactWritePath(patchPath);
   if (!patchPath || import_node_path.default.isAbsolute(patchPath)) {
     throw new Error(`Invalid patch path: ${rawPath}`);
   }
@@ -1047,6 +1247,36 @@ async function executeApplyPatchOperation(input) {
   };
 }
 async function executeViewFileBytesOperation(input) {
+  const artifact = await resolveArtifactEnvFilePath({
+    filePath: input.message.filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    artifactRoot: input.artifactRoot
+  });
+  if (artifact) {
+    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) {
+      throw new Error("view_image supports PNG and JPEG files only");
+    }
+    const bytes2 = import_node_fs.default.readFileSync(artifact.absolutePath);
+    const dimensions2 = readImageDimensions(bytes2, mediaType2);
+    return {
+      type: "view_file_bytes",
+      filePath: artifact.virtualPath,
+      mediaType: mediaType2,
+      base64: bytes2.toString("base64"),
+      fileSizeBytes: bytes2.length,
+      width: dimensions2.width,
+      height: dimensions2.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()) {
@@ -1223,6 +1453,18 @@ async function executeCommand(input) {
       branchName: input.message.branchName,
       manifest: input.manifest
     });
+    let artifactProcessEnv = {};
+    if (input.message.sessionId) {
+      await syncSessionArtifacts({
+        baseUrl: input.baseUrl,
+        token: input.token,
+        projectId: input.projectId,
+        branchName: input.message.branchName,
+        sessionId: input.message.sessionId,
+        artifactRoot: input.artifactRoot
+      });
+      artifactProcessEnv = artifactEnv(input.artifactRoot, input.message.sessionId);
+    }
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1232,7 +1474,8 @@ async function executeCommand(input) {
         ...process.env,
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
-        ...internalGitProcessEnv(workspace, input.message.env)
+        ...internalGitProcessEnv(workspace, input.message.env),
+        ...artifactProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1295,6 +1538,15 @@ async function executeStreamingCommand(input) {
       branchName: input.message.branchName,
       manifest: input.manifest
     });
+    await syncSessionArtifacts({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      sessionId: input.message.sessionId,
+      artifactRoot: input.artifactRoot
+    });
+    const artifactProcessEnv = artifactEnv(input.artifactRoot, input.message.sessionId);
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1304,7 +1556,8 @@ async function executeStreamingCommand(input) {
         ...process.env,
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
-        ...internalGitProcessEnv(workspace, input.message.env)
+        ...internalGitProcessEnv(workspace, input.message.env),
+        ...artifactProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1679,11 +1932,14 @@ async function startWorker(options) {
   validateLabel(label);
   const projectsRoot = import_node_path.default.resolve(options.projectRoot ?? defaultProjectsRoot());
   const syncRoot = import_node_path.default.resolve(options.syncRoot ?? process.env.R5D_SYNC_ROOT ?? defaultSyncRoot());
+  const artifactRoot = import_node_path.default.resolve(options.artifactRoot ?? process.env.R5D_ARTIFACTS_ROOT ?? defaultArtifactRoot());
   process.stdout.write(`[r5d-worker] label: ${label}
 `);
   process.stdout.write(`[r5d-worker] projects root: ${projectsRoot}
 `);
   process.stdout.write(`[r5d-worker] sync root: ${syncRoot}
+`);
+  process.stdout.write(`[r5d-worker] artifact root: ${artifactRoot}
 `);
   process.stdout.write(`[r5d-worker] server: ${baseUrl}
 `);
@@ -1691,6 +1947,7 @@ async function startWorker(options) {
   await verifyR5dctlAuth(baseUrl, token);
   import_node_fs.default.mkdirSync(projectsRoot, { recursive: true });
   import_node_fs.default.mkdirSync(syncRoot, { recursive: true });
+  import_node_fs.default.mkdirSync(artifactRoot, { recursive: true });
   const manifestByProjectId = /* @__PURE__ */ new Map();
   const ws = new WebSocket(websocketUrl(baseUrl, label), {
     headers: {
@@ -1706,7 +1963,8 @@ async function startWorker(options) {
         arch: process.arch,
         pid: process.pid,
         version: getWorkerVersion(),
-        projectRoot: projectsRoot
+        projectRoot: projectsRoot,
+        artifactRoot
       }
     };
     ws.send(JSON.stringify(hello));
@@ -1803,7 +2061,7 @@ async function startWorker(options) {
         const result = await withBranchLock(
           message.projectId,
           message.branchName,
-          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest })
+          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
         );
         ws.send(JSON.stringify(result));
         return;
@@ -1822,7 +2080,7 @@ async function startWorker(options) {
           void withBranchLock(
             message.projectId,
             message.branchName,
-            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest })
+            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
           ).catch((error) => {
             sendWorkerMessage(ws, {
               type: "exec_start_error",
@@ -1848,7 +2106,7 @@ async function startWorker(options) {
           const result = await withBranchLock(
             message.projectId,
             message.branchName,
-            () => executeOperation({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest })
+            () => executeOperation({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
           );
           ws.send(
             JSON.stringify({
@@ -1925,5 +2183,7 @@ if (isCliEntrypoint()) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ensureVisibleGitCheckout
+  ensureVisibleGitCheckout,
+  isArtifactEnvPath,
+  syncSessionArtifacts
 });

package/dist/cjs/package.json

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

package/dist/mjs/main.mjs

@@ -30,6 +30,9 @@ function defaultProjectsRoot() {
 function defaultSyncRoot() {
   return path.join(os.homedir(), ".r5d", "sync");
 }
+function defaultArtifactRoot() {
+  return path.join(os.homedir(), ".r5d", "artifacts");
+}
 function printHelp() {
   process.stdout.write(`Usage:
   r5d-worker start --label <label> [--base-url <url>] [--token <token>] [--api-key <key>]
@@ -43,6 +46,7 @@ Options:
   --config <path>       Config path (default ~/.config/r5d/r5dctl/config.json)
   --project-root <dir>  Override projects checkout root (default ~/.r5d/projects)
   --sync-root <dir>     Override r5d internal sync git root (default ~/.r5d/sync)
+  --artifact-root <dir> Override session artifact root (default from R5D_ARTIFACTS_ROOT or ~/.r5d/artifacts)
   -v, --version         Show r5d-worker version
   -h, --help            Show this help
 `);
@@ -159,6 +163,11 @@ function parseArgs(argv) {
       options.syncRoot = syncRoot;
       continue;
     }
+    const artifactRoot = readOption("--artifact-root");
+    if (artifactRoot !== void 0) {
+      options.artifactRoot = artifactRoot;
+      continue;
+    }
     rest.push(arg);
   }
   if (options.version) {
@@ -201,6 +210,170 @@ async function readResponseText(response) {
     return "";
   }
 }
+const R5D_ARTIFACTS_DIR_REF = "$R5D_ARTIFACTS_DIR";
+function validateArtifactSessionId(sessionId) {
+  if (!/^(migration-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(sessionId)) {
+    throw new Error(`Invalid artifact session id: ${sessionId}`);
+  }
+}
+function assertInsideRoot(rootPath, candidatePath, label) {
+  const relative = path.relative(rootPath, candidatePath);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`${label} escapes the artifact directory`);
+  }
+}
+function sessionArtifactDir(artifactRoot, sessionId) {
+  validateArtifactSessionId(sessionId);
+  return path.join(artifactRoot, sessionId);
+}
+function artifactEnv(artifactRoot, sessionId) {
+  if (!sessionId) {
+    return {};
+  }
+  return {
+    R5D_ARTIFACTS_DIR: sessionArtifactDir(artifactRoot, sessionId)
+  };
+}
+function isArtifactEnvPath(filePath) {
+  return filePath === R5D_ARTIFACTS_DIR_REF || filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`);
+}
+function artifactApiBasePath(projectId, branchName, sessionId) {
+  return `/preview-api/${encodeURIComponent(projectId)}/${encodeURIComponent(branchName)}/artifacts/${encodeURIComponent(sessionId)}`;
+}
+function artifactManifestUrl(baseUrl, projectId, branchName, sessionId) {
+  return new URL(artifactApiBasePath(projectId, branchName, sessionId), baseUrl);
+}
+function artifactDownloadUrl(baseUrl, projectId, branchName, sessionId, filename) {
+  return new URL(`${artifactApiBasePath(projectId, branchName, sessionId)}/${encodeURIComponent(filename)}`, baseUrl);
+}
+function sha256Path(filePath) {
+  return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+function parseSessionArtifactManifest(value) {
+  if (!value || typeof value !== "object" || !Array.isArray(value.artifacts)) {
+    throw new Error("Artifact manifest response is invalid");
+  }
+  return value.artifacts.map((entry) => {
+    if (!entry || typeof entry !== "object") {
+      throw new Error("Artifact manifest entry is invalid");
+    }
+    const artifact = entry;
+    if (typeof artifact.filename !== "string" || artifact.filename.includes("/") || artifact.filename.includes("\\")) {
+      throw new Error("Artifact manifest entry has an invalid filename");
+    }
+    if (typeof artifact.size !== "number" || !Number.isFinite(artifact.size) || artifact.size < 0) {
+      throw new Error(`Artifact manifest entry has an invalid size: ${artifact.filename}`);
+    }
+    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(artifact.sha256)) {
+      throw new Error(`Artifact manifest entry has an invalid sha256: ${artifact.filename}`);
+    }
+    return {
+      filename: artifact.filename,
+      size: artifact.size,
+      sha256: artifact.sha256.toLowerCase()
+    };
+  });
+}
+async function fetchSessionArtifactManifest(input) {
+  const response = await fetch(artifactManifestUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId), {
+    headers: {
+      Authorization: `Bearer ${input.token}`
+    }
+  });
+  if (!response.ok) {
+    const detail = (await readResponseText(response)).trim();
+    throw new Error(`Failed to fetch artifact manifest (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+  return parseSessionArtifactManifest(await response.json());
+}
+async function downloadSessionArtifact(input) {
+  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
+  const targetPath = path.join(targetDir, input.artifact.filename);
+  assertInsideRoot(targetDir, targetPath, "Artifact path");
+  const response = await fetch(
+    artifactDownloadUrl(input.baseUrl, input.projectId, input.branchName, input.sessionId, input.artifact.filename),
+    {
+      headers: {
+        Authorization: `Bearer ${input.token}`
+      }
+    }
+  );
+  if (!response.ok) {
+    const detail = (await readResponseText(response)).trim();
+    throw new Error(`Failed to download artifact ${input.artifact.filename} (${response.status})${detail ? `: ${detail}` : ""}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  const receivedHash = createHash("sha256").update(buffer).digest("hex");
+  if (receivedHash !== input.artifact.sha256) {
+    throw new Error(`Downloaded artifact ${input.artifact.filename} failed sha256 verification`);
+  }
+  if (buffer.length !== input.artifact.size) {
+    throw new Error(`Downloaded artifact ${input.artifact.filename} has unexpected size`);
+  }
+  const tempPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, buffer);
+  fs.renameSync(tempPath, targetPath);
+}
+async function syncSessionArtifacts(input) {
+  const targetDir = sessionArtifactDir(input.artifactRoot, input.sessionId);
+  fs.mkdirSync(targetDir, { recursive: true });
+  const artifacts = await fetchSessionArtifactManifest(input);
+  const manifestNames = new Set(artifacts.map((artifact) => artifact.filename));
+  for (const artifact of artifacts) {
+    const localPath = path.join(targetDir, artifact.filename);
+    assertInsideRoot(targetDir, localPath, "Artifact path");
+    if (fs.existsSync(localPath)) {
+      const stats = fs.statSync(localPath);
+      if (stats.isFile() && stats.size === artifact.size && sha256Path(localPath) === artifact.sha256) {
+        continue;
+      }
+      fs.rmSync(localPath, { recursive: true, force: true });
+    }
+    await downloadSessionArtifact({ ...input, artifact });
+  }
+  for (const localName of fs.readdirSync(targetDir)) {
+    if (!manifestNames.has(localName)) {
+      const localPath = path.join(targetDir, localName);
+      assertInsideRoot(targetDir, localPath, "Artifact path");
+      fs.rmSync(localPath, { recursive: true, force: true });
+    }
+  }
+  return targetDir;
+}
+async function resolveArtifactEnvFilePath(input) {
+  if (!isArtifactEnvPath(input.filePath)) {
+    return null;
+  }
+  if (!input.sessionId) {
+    throw new Error(`${R5D_ARTIFACTS_DIR_REF} paths require an active chat session`);
+  }
+  if (!input.filePath.startsWith(`${R5D_ARTIFACTS_DIR_REF}/`)) {
+    throw new Error(`Artifact path must reference a file under ${R5D_ARTIFACTS_DIR_REF}/`);
+  }
+  const targetDir = await syncSessionArtifacts({
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.branchName,
+    sessionId: input.sessionId,
+    artifactRoot: input.artifactRoot
+  });
+  const relativePath = path.posix.normalize(input.filePath.slice(`${R5D_ARTIFACTS_DIR_REF}/`.length));
+  if (!relativePath || relativePath === "." || relativePath.startsWith("../") || relativePath.includes("\0")) {
+    throw new Error(`Invalid artifact path: ${input.filePath}`);
+  }
+  const absolutePath = path.resolve(targetDir, ...relativePath.split("/"));
+  assertInsideRoot(targetDir, absolutePath, "Artifact path");
+  return {
+    absolutePath,
+    virtualPath: `${R5D_ARTIFACTS_DIR_REF}/${relativePath}`
+  };
+}
+function rejectArtifactWritePath(filePath) {
+  if (isArtifactEnvPath(filePath)) {
+    throw new Error(`${R5D_ARTIFACTS_DIR_REF} attachments are read-only. Copy them into a project path before editing or creating files.`);
+  }
+}
 async function verifyR5dctlAuth(baseUrl, token) {
   const statusUrl = new URL("/api/r5dctl/auth/status", baseUrl);
   let response;
@@ -789,6 +962,28 @@ function readImageDimensions(bytes, mediaType) {
   return dimensions;
 }
 async function executeReadFileOperation(input) {
+  const artifact = await resolveArtifactEnvFilePath({
+    filePath: input.message.filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    artifactRoot: input.artifactRoot
+  });
+  if (artifact) {
+    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);
+    return {
+      type: "read_file",
+      file: artifact.virtualPath,
+      gitBlobHash: getGitBlobHashForContent(buffer2),
+      ...formatted2
+    };
+  }
   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()) {
@@ -804,6 +999,7 @@ async function executeReadFileOperation(input) {
   };
 }
 async function executeCreateFileOperation(input) {
+  rejectArtifactWritePath(input.message.filePath);
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
   const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
   if (fs.existsSync(resolved.absolutePath)) {
@@ -818,6 +1014,7 @@ async function executeCreateFileOperation(input) {
   };
 }
 async function executeEditFileOperation(input) {
+  rejectArtifactWritePath(input.message.filePath);
   const workspace = ensureOperationBranch({ ...input, branchName: input.message.branchName });
   const resolved = resolveProjectFilePath(workspace.branchPath, input.message.filePath);
   if (input.message.oldString === input.message.newString) {
@@ -867,6 +1064,7 @@ function normalizePatchPath(rawPath) {
   if (patchPath.startsWith("a/") || patchPath.startsWith("b/")) {
     patchPath = patchPath.slice(2);
   }
+  rejectArtifactWritePath(patchPath);
   if (!patchPath || path.isAbsolute(patchPath)) {
     throw new Error(`Invalid patch path: ${rawPath}`);
   }
@@ -1013,6 +1211,36 @@ async function executeApplyPatchOperation(input) {
   };
 }
 async function executeViewFileBytesOperation(input) {
+  const artifact = await resolveArtifactEnvFilePath({
+    filePath: input.message.filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    projectId: input.projectId,
+    branchName: input.message.branchName,
+    sessionId: input.message.sessionId,
+    artifactRoot: input.artifactRoot
+  });
+  if (artifact) {
+    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) {
+      throw new Error("view_image supports PNG and JPEG files only");
+    }
+    const bytes2 = fs.readFileSync(artifact.absolutePath);
+    const dimensions2 = readImageDimensions(bytes2, mediaType2);
+    return {
+      type: "view_file_bytes",
+      filePath: artifact.virtualPath,
+      mediaType: mediaType2,
+      base64: bytes2.toString("base64"),
+      fileSizeBytes: bytes2.length,
+      width: dimensions2.width,
+      height: dimensions2.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()) {
@@ -1189,6 +1417,18 @@ async function executeCommand(input) {
       branchName: input.message.branchName,
       manifest: input.manifest
     });
+    let artifactProcessEnv = {};
+    if (input.message.sessionId) {
+      await syncSessionArtifacts({
+        baseUrl: input.baseUrl,
+        token: input.token,
+        projectId: input.projectId,
+        branchName: input.message.branchName,
+        sessionId: input.message.sessionId,
+        artifactRoot: input.artifactRoot
+      });
+      artifactProcessEnv = artifactEnv(input.artifactRoot, input.message.sessionId);
+    }
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1198,7 +1438,8 @@ async function executeCommand(input) {
         ...process.env,
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
-        ...internalGitProcessEnv(workspace, input.message.env)
+        ...internalGitProcessEnv(workspace, input.message.env),
+        ...artifactProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1261,6 +1502,15 @@ async function executeStreamingCommand(input) {
       branchName: input.message.branchName,
       manifest: input.manifest
     });
+    await syncSessionArtifacts({
+      baseUrl: input.baseUrl,
+      token: input.token,
+      projectId: input.projectId,
+      branchName: input.message.branchName,
+      sessionId: input.message.sessionId,
+      artifactRoot: input.artifactRoot
+    });
+    const artifactProcessEnv = artifactEnv(input.artifactRoot, input.message.sessionId);
     const cwd = resolveCommandCwd(workspace.branchPath, input.message.cwd);
     const subprocess = Bun.spawn(input.message.argv, {
       cwd,
@@ -1270,7 +1520,8 @@ async function executeStreamingCommand(input) {
         ...process.env,
         ...containerRegistryEnv(),
         ...input.message.env ?? {},
-        ...internalGitProcessEnv(workspace, input.message.env)
+        ...internalGitProcessEnv(workspace, input.message.env),
+        ...artifactProcessEnv
       }
     });
     activeProcesses.set(input.message.runId, { process: subprocess, command: input.message.argv });
@@ -1645,11 +1896,14 @@ async function startWorker(options) {
   validateLabel(label);
   const projectsRoot = path.resolve(options.projectRoot ?? defaultProjectsRoot());
   const syncRoot = path.resolve(options.syncRoot ?? process.env.R5D_SYNC_ROOT ?? defaultSyncRoot());
+  const artifactRoot = path.resolve(options.artifactRoot ?? process.env.R5D_ARTIFACTS_ROOT ?? defaultArtifactRoot());
   process.stdout.write(`[r5d-worker] label: ${label}
 `);
   process.stdout.write(`[r5d-worker] projects root: ${projectsRoot}
 `);
   process.stdout.write(`[r5d-worker] sync root: ${syncRoot}
+`);
+  process.stdout.write(`[r5d-worker] artifact root: ${artifactRoot}
 `);
   process.stdout.write(`[r5d-worker] server: ${baseUrl}
 `);
@@ -1657,6 +1911,7 @@ async function startWorker(options) {
   await verifyR5dctlAuth(baseUrl, token);
   fs.mkdirSync(projectsRoot, { recursive: true });
   fs.mkdirSync(syncRoot, { recursive: true });
+  fs.mkdirSync(artifactRoot, { recursive: true });
   const manifestByProjectId = /* @__PURE__ */ new Map();
   const ws = new WebSocket(websocketUrl(baseUrl, label), {
     headers: {
@@ -1672,7 +1927,8 @@ async function startWorker(options) {
         arch: process.arch,
         pid: process.pid,
         version: getWorkerVersion(),
-        projectRoot: projectsRoot
+        projectRoot: projectsRoot,
+        artifactRoot
       }
     };
     ws.send(JSON.stringify(hello));
@@ -1769,7 +2025,7 @@ async function startWorker(options) {
         const result = await withBranchLock(
           message.projectId,
           message.branchName,
-          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest })
+          () => executeCommand({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
         );
         ws.send(JSON.stringify(result));
         return;
@@ -1788,7 +2044,7 @@ async function startWorker(options) {
           void withBranchLock(
             message.projectId,
             message.branchName,
-            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest })
+            () => executeStreamingCommand({ ws, message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
           ).catch((error) => {
             sendWorkerMessage(ws, {
               type: "exec_start_error",
@@ -1814,7 +2070,7 @@ async function startWorker(options) {
           const result = await withBranchLock(
             message.projectId,
             message.branchName,
-            () => executeOperation({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, manifest })
+            () => executeOperation({ message, projectId: message.projectId, baseUrl, token, projectRoot, syncRoot, artifactRoot, manifest })
           );
           ws.send(
             JSON.stringify({
@@ -1890,5 +2146,7 @@ if (isCliEntrypoint()) {
   });
 }
 export {
-  ensureVisibleGitCheckout
+  ensureVisibleGitCheckout,
+  isArtifactEnvPath,
+  syncSessionArtifacts
 };

package/dist/mjs/package.json

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

package/dist/types/main.d.ts

@@ -1,4 +1,13 @@
 #!/usr/bin/env bun
+export declare function isArtifactEnvPath(filePath: string): boolean;
+export declare function syncSessionArtifacts(input: {
+    baseUrl: string;
+    token: string;
+    projectId: string;
+    branchName: string;
+    sessionId: string;
+    artifactRoot: string;
+}): Promise<string>;
 type GitAuth = {
     extraHeaderUrl: string;
     header: string;

package/package.json

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