fix(artifacts): use file-backed sandbox transport (#174)

## Why

Real research reports can produce document binaries large enough to make
stdout an unreliable artifact transport. The sandbox renderer previously
base64-encoded the entire binary into stdout and the host reparsed that
stream as JSON, which caused production research PDF generation to fail
with invalid artifact metadata.

## What changed

- write generated document bytes to a bounded project-local staging file
- emit only a small, marker-delimited metadata record over stdout
- require the reported path to exactly match the host-selected staging
path
- read artifact bytes through the sandbox file API before workspace and
R2 persistence
- delete both staged input and output in `finally`
- remove the old stdout/base64 compatibility path entirely
- document the file-backed renderer protocol

## Architecture / migration effects

- No database or migration changes
- No new dependency or deployment configuration
- The document renderer control channel and binary data channel are now
separated

## Verification

- `pnpm lint`
- `pnpm typecheck`
- `pnpm turbo build --force`
- `pnpm deadcode` (passes; four existing Knip configuration hints
remain)
- `pnpm architecture:check`
- `pnpm turbo skills:build`
- Live Daytona sandbox: rendered a 16-page research-style Markdown PDF
(77,026 bytes)
- Live Daytona sandbox: rendered and identified DOCX, PDF, PPTX, and
XLSX outputs
- Confirmed renderer stdout contains only path-bound metadata
- Confirmed exact input and output staging files are deleted after
rendering

Local verification used Node 26.4.0 while the repository pins Node
24.18.0; pnpm emitted the existing engine warning, and all checks
passed.

Author: iamjr15

packages/agent-core/README.md

@@ -79,12 +79,14 @@ and PDF therefore preserve the same headings, prose, lists, tables, links, citat
 and ordering; only print-safe pagination and document chrome differ. The project
 workspace is resolved only after remote research succeeds;
 the PDF is then stored both in the live project files and the durable
-generated-output store. Sandbox renderers delimit their final artifact metadata with
-an internal stdout marker so bounded library diagnostics cannot corrupt the payload.
-Document generators stage their bounded structured input
-in a hidden, project-local temporary file instead of embedding it in the sandbox
-command line, then delete that input after rendering; this keeps large reports
-within the sandbox process contract without retaining source payloads.
+generated-output store. Sandbox renderers write binary output to a bounded staging
+file and delimit only its small metadata object with an internal stdout marker. The
+host validates that path, reads the bytes through the sandbox file boundary, uploads
+the durable artifact, and removes both staging files. Document generators stage
+their bounded structured input in a hidden, project-local temporary file instead of
+embedding it in the sandbox command line, then delete that input after rendering;
+this keeps large reports within the sandbox process contract without retaining
+source payloads.
 
 Composio REST tool discovery and execution responses are byte-bounded before
 parsing, then projected into bounded, valid JSON before entering model context.

packages/agent-core/src/tools/docs/execute.ts

@@ -34,18 +34,28 @@ import {
   buildXlsxScript,
 } from "./scripts";
 
-const SandboxArtifactSchema = z.strictObject({
-  base64: z.string().min(1),
+const SandboxArtifactMetadataSchema = z.strictObject({
   filename: z.string().min(1),
   mimeType: z.string().min(1),
+  path: z.string().min(1),
 });
 
-type SandboxArtifact = z.infer<typeof SandboxArtifactSchema>;
+type SandboxArtifactMetadata = z.infer<typeof SandboxArtifactMetadataSchema>;
+
+interface SandboxArtifact extends Omit<SandboxArtifactMetadata, "path"> {
+  base64: string;
+}
+
+interface ArtifactStaging {
+  content: string;
+  inputPath: string;
+  outputPath: string;
+}
 
 const MAX_WORKSPACE_ARTIFACT_BASE64_CHARS = 2_000_000;
 const MAX_STAGED_INPUT_CHARACTERS = 1_900_000;
 const WORKSPACE_ROOT = "/workspace";
-const ARTIFACT_STAGING_DIRECTORY = ".cheatcode/artifact-inputs";
+const ARTIFACT_STAGING_DIRECTORY = ".cheatcode/artifact-staging";
 const ARTIFACT_STDOUT_MARKER = "__CHEATCODE_ARTIFACT__";
 
 export async function executeGenerateSlides(
@@ -54,8 +64,11 @@ export async function executeGenerateSlides(
 ): Promise<GenerateSlidesOutput> {
   const parsed = GenerateSlidesInputSchema.parse(input);
   const filename = normalizeFilename(parsed.filename ?? parsed.title, "pptx");
-  const artifact = await runArtifactScript(parsed, runtimeContext, "slide", (inputPath) =>
-    buildSlidesScript(inputPath, filename),
+  const artifact = await runArtifactScript(
+    parsed,
+    runtimeContext,
+    "slide",
+    (inputPath, outputPath) => buildSlidesScript(inputPath, outputPath, filename),
   );
   return GenerateSlidesOutputSchema.parse({
     ...artifact,
@@ -70,8 +83,11 @@ export async function executeGenerateDocx(
 ): Promise<GenerateDocxOutput> {
   const parsed = GenerateDocumentInputSchema.parse(input);
   const filename = normalizeFilename(parsed.filename ?? parsed.title, "docx");
-  const artifact = await runArtifactScript(parsed, runtimeContext, "docx", (inputPath) =>
-    buildDocxScript(inputPath, filename),
+  const artifact = await runArtifactScript(
+    parsed,
+    runtimeContext,
+    "docx",
+    (inputPath, outputPath) => buildDocxScript(inputPath, outputPath, filename),
   );
   return GenerateDocxOutputSchema.parse({
     ...artifact,
@@ -86,8 +102,8 @@ export async function executeGeneratePdf(
 ): Promise<GeneratePdfOutput> {
   const parsed = GenerateDocumentInputSchema.parse(input);
   const filename = normalizeFilename(parsed.filename ?? parsed.title, "pdf");
-  const artifact = await runArtifactScript(parsed, runtimeContext, "pdf", (inputPath) =>
-    buildPdfScript(inputPath, filename),
+  const artifact = await runArtifactScript(parsed, runtimeContext, "pdf", (inputPath, outputPath) =>
+    buildPdfScript(inputPath, outputPath, filename),
   );
   return GeneratePdfOutputSchema.parse({
     ...artifact,
@@ -107,7 +123,7 @@ export async function executeGenerateMarkdownPdf(
     { markdown: parsed.markdown, title: parsed.title, tokens },
     runtimeContext,
     "pdf",
-    (inputPath) => buildMarkdownPdfScript(inputPath, filename),
+    (inputPath, outputPath) => buildMarkdownPdfScript(inputPath, outputPath, filename),
   );
   return GenerateMarkdownPdfOutputSchema.parse({
     ...artifact,
@@ -122,8 +138,11 @@ export async function executeGenerateXlsx(
 ): Promise<GenerateXlsxOutput> {
   const parsed = GenerateSpreadsheetInputSchema.parse(input);
   const filename = normalizeFilename(parsed.filename ?? parsed.title, "xlsx");
-  const artifact = await runArtifactScript(parsed, runtimeContext, "xlsx", (inputPath) =>
-    buildXlsxScript(inputPath, filename),
+  const artifact = await runArtifactScript(
+    parsed,
+    runtimeContext,
+    "xlsx",
+    (inputPath, outputPath) => buildXlsxScript(inputPath, outputPath, filename),
   );
   return GenerateXlsxOutputSchema.parse({
     ...artifact,
@@ -136,19 +155,22 @@ async function runArtifactScript(
   input: unknown,
   runtimeContext: CodeRuntimeContext,
   kind: ArtifactKind,
-  buildScript: (inputPath: string) => string,
+  buildScript: (inputPath: string, outputPath: string) => string,
 ): Promise<ArtifactUploadResult> {
   if (!runtimeContext.artifacts) {
     throw new APIError(500, "internal_service_error", "Artifact storage is unavailable", {
       retriable: true,
     });
   }
 
-  const staging = stagedArtifactInput(input, runtimeContext.workspaceDir ?? WORKSPACE_ROOT);
+  const staging = createArtifactStaging(input, runtimeContext.workspaceDir ?? WORKSPACE_ROOT);
   try {
-    await runtimeContext.sandbox.writeFile({ content: staging.content, path: staging.path });
+    await runtimeContext.sandbox.writeFile({
+      content: staging.content,
+      path: staging.inputPath,
+    });
     const result = await runtimeContext.sandbox.runCode({
-      code: buildScript(staging.path),
+      code: buildScript(staging.inputPath, staging.outputPath),
       cwd: runtimeContext.workspaceDir ?? WORKSPACE_ROOT,
       language: "javascript",
     });
@@ -163,7 +185,8 @@ async function runArtifactScript(
       });
     }
 
-    const generated = parseSandboxArtifact(result.stdout);
+    const metadata = parseSandboxArtifact(result.stdout, staging.outputPath);
+    const generated = await readSandboxArtifact(runtimeContext, metadata);
     await writeWorkspaceArtifact(runtimeContext, generated);
     return await runtimeContext.artifacts.put({
       contentType: generated.mimeType,
@@ -172,24 +195,36 @@ async function runArtifactScript(
       kind,
     });
   } finally {
-    await runtimeContext.sandbox.deleteFile({ path: staging.path }).catch(() => undefined);
+    await runtimeContext.sandbox.deleteFile({ path: staging.inputPath }).catch(() => undefined);
+    await runtimeContext.sandbox.deleteFile({ path: staging.outputPath }).catch(() => undefined);
   }
 }
 
-function stagedArtifactInput(
-  input: unknown,
-  workspaceDir: string,
-): { content: string; path: string } {
+async function readSandboxArtifact(
+  runtimeContext: CodeRuntimeContext,
+  metadata: SandboxArtifactMetadata,
+): Promise<SandboxArtifact> {
+  const file = await runtimeContext.sandbox.readFile({ encoding: "base64", path: metadata.path });
+  return {
+    base64: z.string().min(1).parse(file.content),
+    filename: metadata.filename,
+    mimeType: metadata.mimeType,
+  };
+}
+
+function createArtifactStaging(input: unknown, workspaceDir: string): ArtifactStaging {
   const content = JSON.stringify(input);
   if (content.length > MAX_STAGED_INPUT_CHARACTERS) {
     throw new APIError(422, "tool_validation_failed", "Document input is too large", {
       details: { inputCharacters: content.length },
       retriable: false,
     });
   }
+  const stagingId = crypto.randomUUID();
   return {
     content,
-    path: `${workspaceDir}/${ARTIFACT_STAGING_DIRECTORY}/${crypto.randomUUID()}.json`,
+    inputPath: `${workspaceDir}/${ARTIFACT_STAGING_DIRECTORY}/${stagingId}.json`,
+    outputPath: `${workspaceDir}/${ARTIFACT_STAGING_DIRECTORY}/${stagingId}.bin`,
   };
 }
 
@@ -218,14 +253,19 @@ async function writeWorkspaceArtifact(
   }
 }
 
-function parseSandboxArtifact(stdout: string): SandboxArtifact {
+function parseSandboxArtifact(stdout: string, expectedPath: string): SandboxArtifactMetadata {
   try {
     const markerIndex = stdout.lastIndexOf(ARTIFACT_STDOUT_MARKER);
-    const payload =
-      markerIndex === -1
-        ? stdout.trim()
-        : stdout.slice(markerIndex + ARTIFACT_STDOUT_MARKER.length).trim();
-    return SandboxArtifactSchema.parse(JSON.parse(payload));
+    if (markerIndex === -1) {
+      throw new Error("Artifact metadata marker is missing.");
+    }
+    const payload = stdout.slice(markerIndex + ARTIFACT_STDOUT_MARKER.length).trim();
+    const metadataLine = payload.split(/\r?\n/u, 1)[0] ?? "";
+    const metadata = SandboxArtifactMetadataSchema.parse(JSON.parse(metadataLine));
+    if (metadata.path !== expectedPath) {
+      throw new Error("Artifact metadata path did not match the staged output path.");
+    }
+    return metadata;
   } catch (error) {
     throw new APIError(
       502,

packages/agent-core/src/tools/docs/scripts.ts

@@ -12,25 +12,29 @@ function loadInput(inputPath: string): string {
   ].join("\n");
 }
 
-function emitArtifact(filename: string, mimeType: string): string {
+function emitArtifact(filename: string, mimeType: string, outputPath: string): string {
   return [
-    "function emit(base64) {",
+    "async function emit(data) {",
+    '  const { writeFile } = await import("node:fs/promises");',
+    '  const buffer = typeof data === "string" ? Buffer.from(data, "base64") : Buffer.from(data);',
+    `  await writeFile(${JSON.stringify(outputPath)}, buffer);`,
     `  process.stdout.write("\\n${ARTIFACT_STDOUT_MARKER}" + JSON.stringify({`,
     `    filename: ${JSON.stringify(filename)},`,
     `    mimeType: ${JSON.stringify(mimeType)},`,
-    "    base64,",
+    `    path: ${JSON.stringify(outputPath)},`,
     "  }));",
     "}",
   ].join("\n");
 }
 
-export function buildSlidesScript(inputPath: string, filename: string): string {
+export function buildSlidesScript(inputPath: string, outputPath: string, filename: string): string {
   return [
     RUNTIME_REQUIRE,
     loadInput(inputPath),
     emitArtifact(
       filename,
       "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      outputPath,
     ),
     'const PptxGenJS = require("pptxgenjs");',
     "const pptx = new PptxGenJS();",
@@ -57,17 +61,18 @@ export function buildSlidesScript(inputPath: string, filename: string): string {
     "  if (item.notes) { slide.addNotes(item.notes); }",
     "}",
     'const base64 = await pptx.write({ outputType: "base64" });',
-    "emit(base64);",
+    "await emit(base64);",
   ].join("\n");
 }
 
-export function buildDocxScript(inputPath: string, filename: string): string {
+export function buildDocxScript(inputPath: string, outputPath: string, filename: string): string {
   return [
     RUNTIME_REQUIRE,
     loadInput(inputPath),
     emitArtifact(
       filename,
       "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      outputPath,
     ),
     'const { Document, HeadingLevel, Packer, Paragraph, TextRun } = require("docx");',
     "const children = [",
@@ -88,15 +93,19 @@ export function buildDocxScript(inputPath: string, filename: string): string {
     "  sections: [{ children }],",
     "});",
     "const buffer = await Packer.toBuffer(doc);",
-    'emit(Buffer.from(buffer).toString("base64"));',
+    "await emit(buffer);",
   ].join("\n");
 }
 
-export function buildXlsxScript(inputPath: string, filename: string): string {
+export function buildXlsxScript(inputPath: string, outputPath: string, filename: string): string {
   return [
     RUNTIME_REQUIRE,
     loadInput(inputPath),
-    emitArtifact(filename, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"),
+    emitArtifact(
+      filename,
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      outputPath,
+    ),
     'const ExcelJS = require("exceljs");',
     "const workbook = new ExcelJS.Workbook();",
     'workbook.creator = "Cheatcode";',
@@ -114,15 +123,15 @@ export function buildXlsxScript(inputPath: string, filename: string): string {
     "  worksheet.views = [{ state: 'frozen', ySplit: 1 }];",
     "}",
     "const buffer = await workbook.xlsx.writeBuffer();",
-    'emit(Buffer.from(buffer).toString("base64"));',
+    "await emit(buffer);",
   ].join("\n");
 }
 
-export function buildPdfScript(inputPath: string, filename: string): string {
+export function buildPdfScript(inputPath: string, outputPath: string, filename: string): string {
   return [
     RUNTIME_REQUIRE,
     loadInput(inputPath),
-    emitArtifact(filename, "application/pdf"),
+    emitArtifact(filename, "application/pdf", outputPath),
     'const ReactModule = await import(require.resolve("react"));',
     "const React = ReactModule.default ?? ReactModule;",
     'const renderer = await import(require.resolve("@react-pdf/renderer"));',
@@ -143,7 +152,7 @@ export function buildPdfScript(inputPath: string, filename: string): string {
     "});",
     "const document = h(Document, null, h(Page, { size: 'A4', style: styles.page }, children));",
     "const buffer = await renderToBuffer(document);",
-    'emit(Buffer.from(buffer).toString("base64"));',
+    "await emit(buffer);",
   ].join("\n");
 }
 
@@ -276,14 +285,18 @@ const MARKDOWN_PDF_DOCUMENT = [
   "  ),",
   ");",
   "const buffer = await renderToBuffer(document);",
-  'emit(Buffer.from(buffer).toString("base64"));',
+  "await emit(buffer);",
 ].join("\n");
 
-export function buildMarkdownPdfScript(inputPath: string, filename: string): string {
+export function buildMarkdownPdfScript(
+  inputPath: string,
+  outputPath: string,
+  filename: string,
+): string {
   return [
     RUNTIME_REQUIRE,
     loadInput(inputPath),
-    emitArtifact(filename, "application/pdf"),
+    emitArtifact(filename, "application/pdf", outputPath),
     MARKDOWN_PDF_SETUP,
     MARKDOWN_PDF_STYLES,
     MARKDOWN_PDF_INLINE_RENDERER,