fix(documents): a PDF added to a workflow never loaded

Three separate defects sat between picking a PDF and reading its bytes.

Every document node hand-rolled its own resolver: `resolvePdfBuffer` and
its siblings understood inline `data`, one exact storage key, and a local
path, then fell through to `fs.readFile(uri)`. An `asset://` ref, an https
signed URL (S3/Supabase), a `data:` URI or a `package://` example asset
died with a raw ENOENT. They now share `resolveDocumentBytes`, which
delegates to the runtime's `loadMediaRefBytes` — the resolver every other
media node already used.

`FileStorageAdapter.list()` in the runtime returned nothing unless called
with `delimiter: "/"`, which is not how `resolveAssetBytes` calls it. Its
extension-tolerant lookup (`asset://<id>` -> `<id>.pdf` on disk) therefore
always missed in CLI and DSL contexts. It now walks recursively, matching
the storage package's adapter.

`assets.createUpload` required a non-empty `parent_id`, but the property
dropzones upload with no folder — so every pick 400'd and the value never
reached the property. An empty parent now files under the caller's root,
as `POST /api/assets/` has always done.

Also: a graph opened before the node registry finished loading recorded
every one of its types as unknown, and that append-only set is spread over
the real node types — so known nodes kept rendering as "Missing Node" for
the rest of the session.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: georgi

packages/document-nodes/src/document-bytes.ts

@@ -0,0 +1,71 @@
+/**
+ * One byte resolver for every document node.
+ *
+ * Document refs arrive with whatever URI the surface that produced them uses:
+ * `asset://<id>` from the asset library and the chat composer, an
+ * `/api/storage/<key>` URL from the editor's dropzone, an https signed URL on
+ * S3/Supabase deployments, a `data:` URI, a `package://` example asset, or a
+ * plain file path. `loadMediaRefBytes` already knows all of them — routing
+ * every node through it keeps a PDF that opens in the editor from failing at
+ * run time.
+ */
+import { loadMediaRefBytes, type MediaRefValue } from "@nodetool-ai/runtime";
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type DocumentRefLike = MediaRefValue & {
+  data?: Uint8Array | string | null;
+};
+
+function expandUser(p: string): string {
+  if (!p) return p;
+  if (p === "~") return os.homedir();
+  if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+/**
+ * Resolve a document ref to bytes, or null when nothing behind it can be read.
+ * Falls back to the filesystem for relative and `~`-prefixed paths, which
+ * `loadMediaRefBytes` deliberately does not touch.
+ */
+export async function resolveDocumentBytes(
+  ref: DocumentRefLike,
+  context?: ProcessingContext
+): Promise<Buffer | null> {
+  const bytes = await loadMediaRefBytes(ref as MediaRefValue, context);
+  if (bytes) {
+    return Buffer.from(bytes);
+  }
+
+  const uri = typeof ref.uri === "string" ? ref.uri : "";
+  if (uri && !/^[a-z][a-z0-9+.-]*:\/\//i.test(uri) && !uri.startsWith("data:")) {
+    try {
+      return await fs.readFile(expandUser(uri));
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+/** Same as {@link resolveDocumentBytes}, but throws with the ref named. */
+export async function requireDocumentBytes(
+  ref: DocumentRefLike,
+  context: ProcessingContext | undefined,
+  label: string
+): Promise<Buffer> {
+  const bytes = await resolveDocumentBytes(ref, context);
+  if (!bytes) {
+    const where = ref?.uri || ref?.asset_id;
+    throw new Error(
+      where
+        ? `Could not read ${label} from "${where}"`
+        : `No ${label} data or URI provided`
+    );
+  }
+  return bytes;
+}

packages/document-nodes/src/nodes/document.ts

@@ -10,6 +10,10 @@ import {
   loadNodeFsPromises,
   loadNodePath
 } from "@nodetool-ai/nodes-utils";
+import {
+  resolveDocumentBytes,
+  type DocumentRefLike as DocumentBytesRef
+} from "../document-bytes.js";
 
 const NODE_ONLY: readonly Platform[] = ["node"];
 
@@ -79,30 +83,16 @@ function splitByChunk(
 
 async function readDocumentText(refOrPath: unknown, context?: ProcessingContext): Promise<string> {
   if (typeof refOrPath === "string" && refOrPath) {
-    if (context?.storage) {
-      const stored = await context.storage.retrieve(refOrPath);
-      if (stored !== null) return Buffer.from(stored).toString("utf8");
-    }
+    const bytes = await resolveDocumentBytes({ uri: refOrPath }, context);
+    if (bytes) return bytes.toString("utf8");
     const fs = await loadNodeFsPromises();
     return fs.readFile(toFilePath(refOrPath), "utf8");
   }
   if (refOrPath && typeof refOrPath === "object") {
     const ref = refOrPath as DocumentRefLike;
     if (typeof ref.text === "string") return ref.text;
-    if (ref.data) {
-      const bytes = asBytes(ref.data);
-      return Buffer.from(bytes).toString("utf8");
-    }
-    if (typeof ref.uri === "string" && ref.uri) {
-      if (context?.storage) {
-        const stored = await context.storage.retrieve(ref.uri);
-        if (stored !== null) return Buffer.from(stored).toString("utf8");
-      }
-      if (ref.uri.startsWith("file://") || !ref.uri.startsWith("http")) {
-        const fs = await loadNodeFsPromises();
-        return fs.readFile(toFilePath(ref.uri), "utf8");
-      }
-    }
+    const bytes = await resolveDocumentBytes(ref as DocumentBytesRef, context);
+    if (bytes) return bytes.toString("utf8");
   }
   return "";
 }

packages/document-nodes/src/nodes/lib-doc-convert.ts

@@ -6,6 +6,7 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { resolveDocumentBytes } from "../document-bytes.js";
 
 const execFile = promisify(execFileCb);
 
@@ -140,23 +141,6 @@ function refToBytes(ref: unknown): Buffer | null {
   return null;
 }
 
-async function loadFromUri(uri: string, context?: ProcessingContext): Promise<Buffer | null> {
-  if (!uri) return null;
-  if (context?.storage) {
-    const stored = await context.storage.retrieve(uri);
-    if (stored !== null) return Buffer.from(stored);
-  }
-  let filePath = uri;
-  if (filePath.startsWith("file://")) {
-    filePath = decodeURIComponent(new URL(filePath).pathname);
-  }
-  try {
-    return Buffer.from(await fs.readFile(filePath));
-  } catch {
-    return null;
-  }
-}
-
 async function pdfToText(inputBytes: Buffer): Promise<string> {
   const { LiteParse } = await import("@llamaindex/liteparse");
   const parser = new LiteParse({ ocrEnabled: false });
@@ -239,8 +223,8 @@ export class ConvertToMarkdownLibNode extends BaseNode {
     if (doc && typeof doc === "object") {
       const uri = typeof doc.uri === "string" ? doc.uri : "";
       let bytes = refToBytes(doc);
-      if ((!bytes || bytes.length === 0) && uri) {
-        bytes = await loadFromUri(uri, context);
+      if ((!bytes || bytes.length === 0) && (uri || doc.asset_id)) {
+        bytes = await resolveDocumentBytes({ uri, asset_id: doc.asset_id }, context);
       }
       if (bytes && bytes.length > 0) {
         return { output: await convertBytes(bytes, turndown) };

packages/document-nodes/src/nodes/lib-epub.ts

@@ -9,17 +9,11 @@ import type { ProcessingContext } from "@nodetool-ai/runtime";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-
-type DocumentRefLike = {
-  uri?: string;
-  data?: Uint8Array | string;
-};
-
-function asBytes(data: Uint8Array | string | undefined): Uint8Array {
-  if (!data) return new Uint8Array();
-  if (data instanceof Uint8Array) return data;
-  return Uint8Array.from(Buffer.from(data, "base64"));
-}
+import { fileURLToPath } from "node:url";
+import {
+  requireDocumentBytes,
+  type DocumentRefLike
+} from "../document-bytes.js";
 
 function expandUser(p: string): string {
   if (!p) return p;
@@ -28,34 +22,29 @@ function expandUser(p: string): string {
   return p;
 }
 
+/**
+ * epub2 reads from a path, so anything that isn't already a local file lands
+ * in a temp file the caller deletes afterwards.
+ */
 async function resolveEpubPath(
   doc: DocumentRefLike,
   context?: ProcessingContext
 ): Promise<{ filePath: string; cleanup?: () => Promise<void> }> {
-  if (doc.uri && !doc.data) {
-    const uri = doc.uri.startsWith("file://") ? doc.uri.slice(7) : doc.uri;
-    if (context?.storage) {
-      const stored = await context.storage.retrieve(doc.uri);
-      if (stored !== null) {
-        const tmp = path.join(
-          os.tmpdir(),
-          `nodetool-epub-${Date.now()}-${Math.random().toString(36).slice(2)}.epub`
-        );
-        await fs.writeFile(tmp, Buffer.from(stored));
-        return { filePath: tmp, cleanup: async () => fs.unlink(tmp).catch(() => {}) };
-      }
-    }
+  const uri = typeof doc.uri === "string" ? doc.uri : "";
+  if (uri && !doc.data && !/^[a-z][a-z0-9+.-]*:/i.test(uri)) {
     return { filePath: expandUser(uri) };
   }
-  if (doc.data) {
-    const tmp = path.join(
-      os.tmpdir(),
-      `nodetool-epub-${Date.now()}-${Math.random().toString(36).slice(2)}.epub`
-    );
-    await fs.writeFile(tmp, Buffer.from(asBytes(doc.data)));
-    return { filePath: tmp, cleanup: async () => fs.unlink(tmp).catch(() => {}) };
+  if (uri.startsWith("file://")) {
+    return { filePath: fileURLToPath(uri) };
   }
-  throw new Error("No EPUB data or URI provided");
+
+  const bytes = await requireDocumentBytes(doc, context, "EPUB");
+  const tmp = path.join(
+    os.tmpdir(),
+    `nodetool-epub-${Date.now()}-${Math.random().toString(36).slice(2)}.epub`
+  );
+  await fs.writeFile(tmp, bytes);
+  return { filePath: tmp, cleanup: async () => fs.unlink(tmp).catch(() => {}) };
 }
 
 async function loadEpub(

packages/document-nodes/src/nodes/lib-pdf.ts

@@ -9,33 +9,16 @@ import { BaseNode, prop } from "@nodetool-ai/node-sdk";
 import type { ProcessingContext } from "@nodetool-ai/runtime";
 import type { ParseResult } from "@llamaindex/liteparse";
 
-type DocumentRefLike = {
-  uri?: string;
-  data?: Uint8Array | string;
-};
-
-function asBytes(data: Uint8Array | string | undefined): Uint8Array {
-  if (!data) return new Uint8Array();
-  if (data instanceof Uint8Array) return data;
-  return Uint8Array.from(Buffer.from(data, "base64"));
-}
+import {
+  requireDocumentBytes,
+  type DocumentRefLike
+} from "../document-bytes.js";
 
 async function resolvePdfBuffer(
   pdf: DocumentRefLike,
   context?: ProcessingContext
 ): Promise<Buffer> {
-  if (pdf.data) {
-    return Buffer.from(asBytes(pdf.data));
-  } else if (pdf.uri) {
-    const uri = pdf.uri.startsWith("file://") ? pdf.uri.slice(7) : pdf.uri;
-    if (context?.storage) {
-      const stored = await context.storage.retrieve(pdf.uri);
-      if (stored !== null) return Buffer.from(stored);
-    }
-    const { promises: fs } = await import("node:fs");
-    return fs.readFile(uri);
-  }
-  throw new Error("No PDF data or URI provided");
+  return requireDocumentBytes(pdf, context, "PDF");
 }
 
 async function parsePdf(

packages/document-nodes/src/nodes/lib-pptx.ts

@@ -3,35 +3,16 @@
  */
 import { BaseNode, prop } from "@nodetool-ai/node-sdk";
 import type { ProcessingContext } from "@nodetool-ai/runtime";
-import { promises as fs } from "node:fs";
-
-type DocumentRefLike = {
-  uri?: string;
-  data?: Uint8Array | string;
-};
-
-function asBytes(data: Uint8Array | string | undefined): Uint8Array {
-  if (!data) return new Uint8Array();
-  if (data instanceof Uint8Array) return data;
-  return Uint8Array.from(Buffer.from(data, "base64"));
-}
+import {
+  requireDocumentBytes,
+  type DocumentRefLike
+} from "../document-bytes.js";
 
 async function resolvePptxBuffer(
   doc: DocumentRefLike,
   context?: ProcessingContext
 ): Promise<Buffer> {
-  if (doc.data) {
-    return Buffer.from(asBytes(doc.data));
-  }
-  if (doc.uri) {
-    const uri = doc.uri.startsWith("file://") ? doc.uri.slice(7) : doc.uri;
-    if (context?.storage) {
-      const stored = await context.storage.retrieve(doc.uri);
-      if (stored !== null) return Buffer.from(stored);
-    }
-    return fs.readFile(uri);
-  }
-  throw new Error("No PPTX data or URI provided");
+  return requireDocumentBytes(doc, context, "PPTX");
 }
 
 const PPTX_INPUT = {

packages/protocol/src/api-schemas/assets.ts

@@ -87,7 +87,8 @@ export type UploadTarget = z.infer<typeof uploadTarget>;
 export const createUploadInput = z.object({
   name: z.string().min(1),
   content_type: z.string().min(1),
-  parent_id: z.string().min(1),
+  /** Empty or omitted means the user's root folder, as on `POST /api/assets/`. */
+  parent_id: z.string().optional(),
   /** Declared byte size, checked against the upload cap before minting. */
   size: z.number().int().nonnegative(),
   workflow_id: z.string().nullable().optional(),

packages/runtime/src/context.ts

@@ -872,7 +872,49 @@ export class FileStorageAdapter implements StorageAdapter {
         commonPrefixes: [...commonPrefixes].sort()
       };
     }
-    return { entries: [], commonPrefixes: [] };
+
+    // No delimiter: flat listing of everything under the prefix, the shape S3
+    // returns. `resolveAssetBytes` relies on it for the extension-tolerant
+    // lookup that turns `asset://<id>` into `<id>.pdf` on disk.
+    const walk = async (dirAbs: string, keyPrefix: string): Promise<void> => {
+      let children: Array<{
+        name: string;
+        isDirectory: () => boolean;
+        isFile: () => boolean;
+      }>;
+      try {
+        children = (await rd(dirAbs, {
+          withFileTypes: true
+        })) as unknown as typeof children;
+      } catch {
+        return;
+      }
+      for (const child of children) {
+        const childAbs = join(dirAbs, child.name);
+        const childKey = keyPrefix ? `${keyPrefix}/${child.name}` : child.name;
+        if (child.isDirectory()) {
+          await walk(childAbs, childKey);
+          continue;
+        }
+        if (!child.isFile()) continue;
+        try {
+          const s = await st(childAbs);
+          entries.push({
+            key: childKey,
+            uri: pathToFileURL(childAbs).toString(),
+            size: s.size,
+            modifiedAt: s.mtimeMs
+          });
+        } catch {
+          // skip
+        }
+      }
+    };
+    await walk(baseAbs, isRoot ? "" : normalizeStorageKey(prefix));
+    return {
+      entries: entries.sort((a, b) => a.key.localeCompare(b.key)),
+      commonPrefixes: []
+    };
   }
 
   async delete(uri: string): Promise<boolean> {

packages/websocket/src/trpc/routers/assets.ts

@@ -350,7 +350,7 @@ export const assetsRouter = router({
         user_id: ctx.userId,
         name: input.name,
         content_type: input.content_type,
-        parent_id: input.parent_id,
+        parent_id: input.parent_id || ctx.userId,
         workflow_id: input.workflow_id ?? null,
         node_id: input.node_id ?? null,
         job_id: input.job_id ?? null,