[matej21]

Why

Hosts without an OS process table (for example an agent running inside an isolate over a virtual filesystem) could not process uploads: every built-in preprocessor reads a host path and shells out (pdftotext, markitdown, pandoc, unzip), and the upload routes buffer the whole body. This adds the seams such a host needs, while the default process-based path stays unchanged.

What

• Preprocessors read an UploadSource (stream(), range(), bytes(), optional localPath) instead of a path. The process-based built-ins require a local file and say so otherwise.
• bootstrap({ uploads }) takes host preprocessors (replacing the built-ins; builtins() keeps them available), an UploadBlobStore and processingTimeoutMs.
• uploads.registerStored / POST /sessions/:id/uploads/stored register an upload whose bytes the host already stores; processing reads them through the blob store.
• Artifacts and capability flags in the preprocessor result: artifacts may carry a host blobRef for full-fidelity bytes; flags (embeddedImages, ocr, truncated, assetOnly, …) make partial results explicit in the attachment message.
• Attachment block of a stored upload says the original is kept by the host and is not a file in the session, lists the derived files to read, and names the path a host tool takes to place the original. Local uploads render as before.
• Durability: an upload interrupted by a restart or a session close re-runs (≤3 runs). A re-run records its attempt, then clears the upload directory except meta.json and a local original. Run counts, sources and blob refs to release come from the event log, never from the agent-writable meta.json; open/release receive { sessionId, uploadId } so the store can verify ownership. Artifact paths must stay inside the upload directory.
• PDF documents for the model: a document content item (application/pdf) maps to an Anthropic document block and an OpenRouter file part. Before any event records it, the agent writes it to the session's .documents/<sha256>.pdf and keeps a session-relative reference, which the provider reads back on every inference (newest first, within a 16 MB request budget). The event log never holds the payload; a fork copies .documents/. An inline document passed straight to llmProvider.inference still works.

Compatibility

Release as 0.3.0:

• Preprocessor.process(source, mimeType, ctx) replaces process(filePath, …); read the bytes through source (source.localPath / requireLocalPath for a tool that needs a file). The context gains the required uploadId, sessionId, filename and attempt.
• The upload routes answer 400 only for a refused request: a closing session is 503; a storage or start failure, a missing blob store and an unknown plugin method are 500 (they were 400). 403, 404 and 409 pass through.
• preamble_added takes PreambleLLMMessage, which carries no document.
• UploadsState gains processing and blobRefs slices; stored meta.json stays readable (all new fields optional).

Verification

bun test in packages/sdk (1658 pass, 0 fail), tsc --noEmit, ts:build, biome on the touched files. Not verified: real providers accepting PDF documents; fs.cp of a fork on a non-disk platform.

🤖 Generated with Claude Code