Merge pull request #37 from BjornMelin/feat/ai-chat-attachments

feat: ai chat attachments and file uploads + Vercel blob handling

Author: BjornMelin

AGENTS.md

@@ -71,6 +71,14 @@ bun run fetch:models           # Update AI model catalog (requires AI_GATEWAY_AP
 - OpenAI-compatible base URL is `https://ai-gateway.vercel.sh/v1` (used for OpenAI SDK compatibility and `GET /models`).
 - `bun run fetch:models` writes a model catalog JSON (default: `docs/ai-gateway-models.json`).
 
+## Project Chat Attachments
+
+- Project chat supports **document attachments** (PDF/DOCX/PPTX/XLSX/TXT/MD) rendered using vendored AI Elements `attachments` (inline variant).
+- The UI uses **upload-before-send** via `POST /api/upload` (sync ingest by default) and sends hosted Blob URLs as AI SDK `FileUIPart` values.
+- The composer enforces `maxFileSize = budgets.maxUploadBytes` (default 25 MB) and `maxFiles = 5` per message.
+- Follow-ups during active durable chat sessions use `POST /api/chat/:runId` and accept optional `files` alongside `message` (`messageId` required).
+- Document file parts are persisted in UI message history; not passed to the model directly; grounding relies on ingestion + retrieval (see `docs/architecture/spec/SPEC-0029-chat-attachments.md`).
+
 ## Documentation standards
 
 - Product requirements: `PRD.md` is the canonical PRD; keep it aligned with `docs/specs/requirements.md`.

PRD.md

@@ -1,7 +1,7 @@
 # Product Requirements Document (PRD) — ai-agent-builder
 
-**Version**: 0.2.1  
-**Date**: 2026-02-06  
+**Version**: 0.2.2  
+**Date**: 2026-02-10  
 **Owner**: Bjorn Melin
 
 ## Executive summary
@@ -62,14 +62,16 @@ plan” without redoing analysis.
 3. User uploads files (PDF/DOCX/PPTX/XLSX/TXT/MD).
 4. System extracts text and structure, chunks content, and indexes it for
    retrieval.
-5. User chats with the project knowledge base (streaming responses).
+5. User chats with the project knowledge base (streaming responses) and can
+   attach additional documents directly in chat (docs-only scope).
 6. User starts a durable run that performs research and generates artifacts
    (PRD/specs/ADRs/security/roadmap/prompts).
 7. User exports the latest artifacts and citations as a deterministic zip.
 
 ### Journey B: Iterate on an existing project
 
-1. User uploads additional material and/or adds instructions in chat.
+1. User uploads additional material, attaches documents, and adds instructions
+   in chat.
 2. User regenerates or refines a subset of artifacts.
 3. System versions artifacts and updates export output deterministically.
 
@@ -127,6 +129,7 @@ Primary spec/ADR references:
 ### Epic 4: Chat with retrieval augmentation
 
 - Project-scoped chat with streaming UI. (FR-008, PR-001)
+- Chat messages can include document attachments (uploaded/ingested before send) and render as part of chat history. (FR-003, FR-008, FR-019)
 - Retrieval-augmented responses using project KB. (FR-019)
 - Agent mode selection per chat. (FR-009)
 

README.md

@@ -16,6 +16,7 @@ trail).
 ## What it does
 
 - Ingests source material: PDFs, slides, docs, markdown, spreadsheets.
+- Project chat supports attaching documents directly in the composer (upload-before-send via `POST /api/upload`) and in follow-ups during active durable sessions.
 - Supports project and global search across projects, uploads, chunks, artifacts, and runs.
 - Enforces per-user project ownership for all project-scoped reads/writes.
 - Applies server-side search guardrails (strict query validation + rate limiting).
@@ -66,6 +67,7 @@ flowchart LR
 - Provisioning + deploy automation: [`docs/architecture/spec/SPEC-0018-infrastructure-provisioning-and-secrets-for-target-apps.md`](./docs/architecture/spec/SPEC-0018-infrastructure-provisioning-and-secrets-for-target-apps.md)
 - Sandbox verification jobs: [`docs/architecture/spec/SPEC-0019-sandbox-build-test-and-ci-execution.md`](./docs/architecture/spec/SPEC-0019-sandbox-build-test-and-ci-execution.md)
 - Workspace + search UX: [`docs/architecture/spec/SPEC-0020-project-workspace-and-search.md`](./docs/architecture/spec/SPEC-0020-project-workspace-and-search.md)
+- Project chat attachments: [`docs/architecture/spec/SPEC-0029-chat-attachments.md`](./docs/architecture/spec/SPEC-0029-chat-attachments.md)
 - Agent Skills (progressive disclosure): [`docs/architecture/spec/SPEC-0027-agent-skills-runtime-integration.md`](./docs/architecture/spec/SPEC-0027-agent-skills-runtime-integration.md)
 - Skills registry installs: [`docs/architecture/spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md`](./docs/architecture/spec/SPEC-0028-skills-registry-ui-and-bundled-installs.md)
 - GitOps + deploy ADRs:

docs/architecture/adr/ADR-0026-orchestration-vercel-workflow-devkit-for-interactive-runs.md

@@ -6,7 +6,7 @@ Version: 0.1
 Date: 2026-02-03
 Supersedes: []
 Superseded-by: []
-Related: [ADR-0005, ADR-0006, ADR-0011, ADR-0021]
+Related: [ADR-0005, ADR-0006, ADR-0011, ADR-0021, ADR-0030]
 Tags: [architecture, reliability, workflows]
 References:
   - [Vercel Workflow](https://vercel.com/docs/workflow)
@@ -168,7 +168,8 @@ flowchart LR
   WF --> VECTOR[(Upstash Vector)]
   WF --> REDIS[(Upstash Redis)]
 
-  Upload[POST /api/upload<br/>enqueue to QStash] --> Q[QStash<br/>POST /api/jobs/ingest-file]
+  UploadToken[POST /api/upload<br/>Blob token exchange] --> Register[POST /api/upload/register<br/>register + ingest (or enqueue)]
+  Register --> Q[QStash<br/>POST /api/jobs/ingest-file]
   Q --> Ingest[POST /api/jobs/ingest-file]
   Ingest --> DB
   Ingest --> VECTOR

docs/architecture/adr/ADR-0030-chat-attachments-reuse-upload-pipeline.md

@@ -0,0 +1,150 @@
+---
+ADR: 0030
+Title: Chat attachments via Vercel Blob client uploads + /api/upload/register (hosted URLs + inline AI Elements)
+Status: Implemented
+Version: 0.1
+Date: 2026-02-10
+Supersedes: []
+Superseded-by: []
+Related: [ADR-0011, ADR-0009, ADR-0006, ADR-0026]
+Tags: [chat, attachments, ai-elements, ai-sdk, upload, ingestion, workflow]
+Related-Requirements: [FR-003, FR-008, FR-019, PR-001, NFR-008, NFR-010, IR-006]
+References:
+  - [AI Elements attachments](https://elements.ai-sdk.dev/components/attachments.md)
+  - [AI SDK useChat attachments](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot#attachments)
+  - [AI SDK FileUIPart](https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#fileuipart)
+---
+
+## Status
+
+Implemented — 2026-02-10.
+
+## Context
+
+Project Chat is the primary UX for interacting with a project knowledge base.
+We already support:
+
+- uploading documents to a project (stored in Blob, ingested, indexed)
+- multi-turn durable chat sessions (Workflow DevKit)
+- AI Elements primitives for chat UI
+
+We need first-class **document attachments** in chat so users can:
+
+1. attach a file in the chat composer
+2. have it ingested for RAG grounding
+3. see the attachment in message history
+4. attach files in follow-up messages during an active durable chat run
+
+## Decision Drivers
+
+- Reuse the existing, validated upload + ingestion pipeline:
+  - `POST /api/upload` for Vercel Blob client upload token exchange
+  - `POST /api/upload/register` for registration, dedupe, and ingestion
+- Avoid base64/data URL message payloads for performance and reliability.
+- Preserve resume-safe chat history (stream markers + persisted UI messages).
+- Keep model prompts clean; rely on ingestion + retrieval for documents.
+- Minimize new endpoints and contracts; strict TypeScript + Zod validation.
+
+## Alternatives Considered
+
+### A. Embed attachments directly as data URLs in chat requests
+
+Pros:
+
+- Single request; no separate upload call.
+
+Cons:
+
+- Large payloads, memory pressure, and brittle streaming on non-trivial docs.
+- Harder to persist and replay reliably.
+
+### B. Create a dedicated chat upload endpoint (`/api/chat/upload`)
+
+Pros:
+
+- Chat-specific contract could include `messageId`, status, etc.
+
+Cons:
+
+- Duplicates the existing allowlist/ingest/dedupe pipeline.
+- Adds long-term maintenance surface area for minimal value.
+
+### C. Use Vercel Blob client uploads + `POST /api/upload/register` and send hosted file URLs as `FileUIPart` (**Chosen**)
+
+Pros:
+
+- One canonical ingestion path for the whole app.
+- Hosted URLs keep chat payloads small; `FileUIPart.url` supports hosted URLs.[^ai-sdk-fileuipart]
+- Clean separation: upload/ingest first, then chat.
+- Works for follow-ups by extending `POST /api/chat/:runId` contract.
+
+Cons:
+
+- Sync ingest can add latency; may need a hybrid/async ingest UX later.
+- Blob URLs are public; requires care around lifecycle/cleanup (future).
+
+### D. Stream multipart upload through the chat streaming endpoint
+
+Pros:
+
+- Single action; can stream progress inline.
+
+Cons:
+
+- High complexity (multipart streaming + retries + partial failure handling).
+- Not needed for docs-only scope.
+
+## Decision Framework (must be ≥ 9.0)
+
+Weights:
+
+- Solution leverage: 35%
+- Application value: 30%
+- Maintenance and cognitive load: 25%
+- Architectural adaptability: 10%
+
+| Option | Leverage | Value | Maintenance | Adaptability | Weighted total |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| A. Data URLs in chat | 6.8 | 7.4 | 5.8 | 7.2 | 6.79 |
+| B. Dedicated chat upload endpoint | 7.2 | 8.1 | 7.0 | 8.0 | 7.46 |
+| C. Blob client uploads + `/api/upload/register` + hosted URLs | 9.4 | 9.2 | 8.9 | 9.0 | **9.19** |
+| D. Multipart streaming upload | 6.4 | 8.0 | 4.2 | 8.6 | 6.63 |
+
+## Decision
+
+Implement chat attachments as:
+
+1. Composer uses vendored AI Elements `PromptInput` attachments + `Attachments` inline UI.[^ai-elements-attachments]
+2. Client uploads attachment bytes via `@vercel/blob/client upload()` using `POST /api/upload` as the token exchange endpoint.
+3. Client registers and ingests the uploaded blobs via `POST /api/upload/register` (sync ingest by default).
+4. Client sends the chat message using hosted file URLs (no data URLs) as `FileUIPart[]` alongside text.
+5. Extend durable follow-ups: `POST /api/chat/:runId` accepts `files?: FileUIPart[]` and resumes the workflow hook with attachments.
+6. Persist file parts in UI message history and include them in `data-workflow` user-message markers for resume-safe replay.
+7. Do not pass document file parts to the model directly; strip file parts when building model messages and append a filename note, relying on ingestion + retrieval (SPEC-0004).
+
+Implementation details and contracts are specified in:
+
+- [SPEC-0029](../spec/SPEC-0029-chat-attachments.md)
+
+## Consequences
+
+### Positive outcomes
+
+- Users can attach documents in chat and see them in history.
+- Attachments in follow-ups work during active durable sessions.
+- Upload/ingestion remains canonical and deduped.
+- Chat payloads remain small and stream-resume-safe.
+
+### Negative outcomes / risks
+
+- Sync ingest can add noticeable latency for large docs.
+  - Mitigation: keep strict upload budgets; consider a hybrid or async ingest UX if needed.
+- Public blob URLs can be shared out-of-band.
+  - Mitigation: keep app access private; consider signed URLs or authenticated proxying in a future hardening pass.
+- Orphaned uploads if the user abandons mid-flow.
+  - Mitigation (future): add cleanup/GC for unattached uploads or reference counting by project.
+
+## References
+
+[^ai-elements-attachments]: <https://elements.ai-sdk.dev/components/attachments.md>
+[^ai-sdk-fileuipart]: <https://ai-sdk.dev/docs/reference/ai-sdk-core/ui-message#fileuipart>

docs/architecture/adr/index.md

@@ -27,6 +27,7 @@
 - [ADR-0027](./ADR-0027-preview-resource-governance-for-bot-branches-vercel-neon.md) — Preview resource governance for bot branches (Vercel + Neon) (Implemented)
 - [ADR-0028](./ADR-0028-agent-skills-progressive-disclosure-hybrid-fs-db.md) — Agent Skills progressive disclosure (hybrid filesystem + DB) (Implemented)
 - [ADR-0029](./ADR-0029-skills-registry-integration-ui-installs-and-bundled-db-files.md) — Skills registry integration (skills.sh) with UI installs + bundled DB skill files (Implemented)
+- [ADR-0030](./ADR-0030-chat-attachments-reuse-upload-pipeline.md) — Chat attachments reuse /api/upload pipeline (hosted URLs + inline AI Elements) (Implemented)
 
 ## Implementation & deployment automation
 

docs/architecture/api.md

@@ -22,9 +22,12 @@ See:
 ## Upload & ingestion (background jobs via QStash)
 
 - `POST /api/upload`
-  - stores originals in Vercel Blob
-  - writes metadata in Neon Postgres
-  - may enqueue async ingestion jobs via Upstash QStash (`async=true`)
+  - Vercel Blob client upload token exchange (`@vercel/blob/client upload()` `handleUploadUrl`)
+  - issues scoped client tokens after authenticating and authorizing the project
+- `POST /api/upload/register`
+  - registers already-uploaded blobs for a project
+  - writes metadata in Neon Postgres (idempotent by sha256)
+  - ingests inline by default; may enqueue async ingestion jobs via Upstash QStash (`async=true`)
 - `POST /api/jobs/ingest-file` (QStash-signed)
   - executes extract → chunk → embed → index asynchronously
   - validates `storageKey` is an HTTPS Vercel Blob URL under

docs/architecture/data-model.md

@@ -146,6 +146,32 @@ Stores non-secret resource identity + metadata.
 - `started_at`, `ended_at`
 - `metadata` (JSON; promotion info, commit SHA)
 
+### `chat_threads`
+
+Project-scoped chat threads backed by Workflow DevKit run IDs.
+
+- `id`
+- `project_id`
+- `mode` (agent mode id)
+- `title`
+- `status` (running/waiting/succeeded/failed/canceled)
+- `workflow_run_id` (unique; used for resumable stream + follow-ups)
+- `last_activity_at`
+- `ended_at` (nullable)
+- `created_at`, `updated_at`
+
+### `chat_messages`
+
+Persisted UI messages for a thread.
+
+- `id` (AI SDK UI message id; stable across replay)
+- `thread_id`
+- `role` (user/assistant/system)
+- `parts` (JSON array)
+  - Stores AI SDK UI parts (text, tool parts, reasoning, etc.).
+  - May include document attachments as `FileUIPart` parts (hosted Blob URLs).
+- `created_at`
+
 ## Vector indexing
 
 Namespaces:

docs/architecture/spec/SPEC-0003-upload-ingestion-pipeline.md

@@ -1,8 +1,8 @@
 ---
 spec: SPEC-0003
 title: Upload + ingestion pipeline
-version: 0.4.0
-date: 2026-02-03
+version: 0.4.1
+date: 2026-02-10
 owners: ["Bjorn Melin"]
 status: Implemented
 related_requirements: ["FR-003", "FR-004", "FR-005", "FR-006", "FR-007", "PR-003", "IR-006", "IR-005", "IR-001"]
@@ -18,6 +18,10 @@ See [SPEC-0021](./SPEC-0021-full-stack-finalization-fluid-compute-neon-upstash-a
 for the cross-cutting “finalization” plan that integrates ingestion with
 durable runs, retrieval, and the workspace UI.
 
+See [SPEC-0029](./SPEC-0029-chat-attachments.md) for the Project Chat document
+attachments flow that uses Vercel Blob client uploads and registers/ingests via
+`POST /api/upload/register`.
+
 ## Context
 
 Users upload pitch decks, PDFs, docs, and spreadsheets. The system must preserve originals, extract text reliably, and build a vector index to support grounded reasoning.
@@ -89,8 +93,9 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 
 ### Architecture overview
 
-- Upload route stores file in Blob and writes metadata in Neon.
-- Upload route processes independent files in parallel; async ingestion enqueues
+- Upload registration route writes metadata in Neon and ingests from Blob.
+- Upload registration processes independent files sequentially (bounded memory);
+  async ingestion enqueues
   QStash jobs with per-file deduplication ids and labels.
   ([QStash deduplication](https://upstash.com/docs/qstash/features/deduplication),
   [QStash publish API](https://upstash.com/docs/qstash/api-refence/messages/publish-a-message))
@@ -105,7 +110,9 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 
 ### File-level contracts
 
-- `src/app/api/upload/route.ts`: accepts uploads, stores originals, writes DB metadata.
+- `src/app/api/upload/route.ts`: Vercel Blob client upload token exchange (scoped client tokens).
+- `src/app/api/upload/register/route.ts`: registers uploaded blobs, writes DB metadata, and ingests (or enqueues async ingest).
+- `src/app/(app)/projects/[projectId]/chat/chat-client.tsx`: uploads chat attachments via Vercel Blob client uploads + `POST /api/upload/register` (see SPEC-0029).
 - `src/app/api/jobs/ingest-file/route.ts`: QStash-signed async ingestion worker (optional; used for larger inputs).
 - `src/lib/ingest/extract/*`: extraction adapters per file type; must preserve stable refs.
 - `src/lib/ingest/chunk/*`: deterministic chunking rules (stable chunk ids).
@@ -130,7 +137,7 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 ## Testing
 
 - Unit: chunking determinism and hashing
-- Unit: request-level route handler tests for `/api/upload` and
+- Unit: request-level route handler tests for `/api/upload`, `/api/upload/register`, and
   `/api/jobs/ingest-file` error handling and async ingestion fallbacks.
 - Integration: upload → extract → index → query
 
@@ -147,6 +154,7 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 ## Key files
 
 - `src/app/api/upload/route.ts`
+- `src/app/api/upload/register/route.ts`
 - `src/app/api/jobs/ingest-file/route.ts`
 - `src/lib/ingest/extract`
 - `src/lib/ingest/chunk`

docs/architecture/spec/SPEC-0004-chat-retrieval-augmentation.md

@@ -1,8 +1,8 @@
 ---
 spec: SPEC-0004
 title: Chat + retrieval augmentation
-version: 0.4.0
-date: 2026-02-07
+version: 0.4.1
+date: 2026-02-10
 owners: ["Bjorn Melin"]
 status: Implemented
 related_requirements: ["FR-008", "FR-009", "FR-019", "PR-001", "PR-002"]
@@ -24,6 +24,9 @@ for the canonical streaming + resumption API contracts and Workflow DevKit integ
 See [SPEC-0023](./SPEC-0023-ai-elements-workspace-ui-and-interaction-model.md)
 for the AI Elements-based workspace UI interaction model.
 
+See [SPEC-0029](./SPEC-0029-chat-attachments.md) for the Project Chat document
+attachments UX and contracts.
+
 ## Context
 
 Users iterate on specs and artifacts via chat. Chat must stream, persist, and use RAG to ground answers in uploads and generated artifacts.
@@ -106,7 +109,7 @@ Requirement IDs are defined in [docs/specs/requirements.md](/docs/specs/requirem
 
 - `src/app/(app)/projects/[projectId]/chat/page.tsx`: UI for streaming chat and message history.
 - `src/app/api/chat/route.ts`: server streaming endpoint; must persist messages/tool calls.
-- `src/app/api/chat/[runId]/route.ts`: resume endpoint for durable chat sessions.
+- `src/app/api/chat/[runId]/route.ts`: resume endpoint for durable chat sessions (supports follow-up attachments).
 - `src/lib/data/chat.server.ts`: chat threads + messages DAL (Neon + Drizzle).
 - `src/workflows/chat/project-chat.workflow.ts`: durable chat workflow orchestration and persistence.
 - `src/lib/ai/tools/retrieval.server.ts`: retrieval tools (uploads + artifacts);