feat(knowledge): multipart knowledge document uploads

[TheodoreSpeaks]

Summary

• Add multipart upload sessions for knowledge documents — create, part URLs, complete, abort — on both the public v2 API and a session-authenticated internal API the UI uses
• Extend the shared multipart layer with a knowledge_document purpose: knowledge-base storage keys, KB-scoped quota checks, and a 100MB cap in MAX_KNOWLEDGE_DOCUMENT_FILE_SIZE
• Bind knowledgeBaseId and purpose into the signed upload token, and reject any token whose purpose doesn't match its storage context or key prefix. getOwnedUploadSession now requires purpose, so a workspace-file or table-import token can't be replayed against a knowledge endpoint
• Carry document tags and processing options through the session metadata, so completion creates a fully-formed document with no follow-up call
• Rewrite the KB upload UI onto the session flow, dropping the presigned-batch path, the server-proxied fallback, the hand-rolled retry loop, and the separate bulk-processing POST (net −300 lines in the hook)
• Make completion idempotent: the session id is the document id, so retries return the already-bound document instead of duplicating work, and a lost insert race converges on the existing row
• Share one finalizeKnowledgeDocumentUpload between both complete routes. A retry is answered from the bound document before any work that can fail independently of the upload, and cleanup is gated on the upload still being unbound — uploaded bytes are never deleted out from under a live document row

Type of Change

• New feature

Testing

• bun run lint — clean
• Full audit suite (boundaries, api-validation:strict, utils, zustand-v5, react-query, client-boundary, bare-icons, icon-paths, realtime-prune, skills, agent-stream-docs, openapi) — all pass
• Vitest: 50 tests across the upload routes, the shared finalizer, knowledge orchestration, the multipart session service, and the client session helper
• type-check reports only errors that are pre-existing on improvement/v2-endpoints (providers/*, workspace-file-manager.ts, contracts/v2/credentials.ts) — the clean base worktree at the same commit reports the identical set. Same for the 7 failures in track-chat-upload.test.ts

Note: CI's Lint and Test job does not run on this PR — ci.yml triggers pull_request only on main/staging/dev, and this targets improvement/v2-endpoints. The checks above were run locally in their place.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 4, 2026 5:40pm

[cursor]

PR Summary

Medium Risk
Touches billing admission, signed upload authorization, and storage/orchestration ordering for large files; changes are well-tested but span auth, quota, and idempotent document binding.

Overview
Adds multipart upload sessions for knowledge-base documents on the public v2 API and session-authenticated internal routes (create, signed part URLs, complete, abort), with OpenAPI coverage.

The shared multipart layer gains a knowledge_document purpose: knowledge-base storage keys, KB-scoped quota at session creation, a 100MB cap via MAX_KNOWLEDGE_DOCUMENT_FILE_SIZE, and knowledgeBaseId / purpose bound into the signed token. getOwnedUploadSession now requires purpose, so workspace-file or table-import tokens cannot be replayed on knowledge endpoints.

Completion is idempotent (upload id = document id): retries return the bound document; finalizeKnowledgeDocumentUpload is shared between v2 and UI routes. Tags and processing options ride in session metadata so completion queues processing without a separate bulk POST. Abort refuses once a document is bound; Azure multipart abort no longer deletes the blob key.

The workspace knowledge upload hook switches to uploadKnowledgeDocumentSession, replacing presigned batch upload, server-proxied fallback, and the follow-up processing call.

^{Reviewed by Cursor Bugbot for commit 09c27a4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR adds multipart knowledge-document uploads to the public and session-authenticated APIs, migrates the knowledge upload UI to the session flow, and hardens token scoping and idempotent completion.

• Adds create, part-URL, complete, and abort endpoints with shared contracts and OpenAPI documentation.
• Binds upload purpose, knowledge-base identity, metadata, tags, and processing options into signed session state.
• Records storage ownership before returning the token and retains retriable state after failed completion.
• Finalizes both API surfaces through one deterministic document-binding path.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the prior billing-ordering, retry-idempotency, and storage-cleanup findings are addressed by bound-document-first finalization, admission-only usage enforcement, non-destructive failure handling, and delayed orphan cleanup.

Important Files Changed

Filename	Overview
apps/sim/app/api/v2/knowledge/[id]/documents/uploads/utils.ts	Centralizes knowledge upload creation, ownership binding, abort protection, and idempotent finalization; the latest cleanup-race fix retains uploaded state for safe retries.
apps/sim/lib/uploads/multipart-session/service.ts	Extends the shared multipart service with knowledge-document scoping, key validation, quota checks, and purpose-bound ownership verification.
apps/sim/app/workspace/[workspaceId]/knowledge/hooks/use-knowledge-upload.ts	Replaces legacy presigned and proxied upload paths with the shared multipart session client.
apps/sim/lib/knowledge/orchestration/documents.ts	Adds deterministic document binding and retry convergence around upload-backed knowledge-document creation.
apps/sim/background/cleanup-soft-deletes.ts	Extends delayed orphan-binding cleanup to cover abandoned multipart knowledge uploads while excluding keys referenced by documents.
apps/docs/openapi-v2-knowledge.json	Documents the multipart knowledge-document upload lifecycle, request contracts, and response schemas.

Sequence Diagram

sequenceDiagram
  participant Client
  participant API as Knowledge Upload API
  participant Store as Object Storage
  participant DB as Ownership and Document DB
  participant Queue as Processing Queue

  Client->>API: Create upload session
  API->>Store: Initiate multipart upload
  API->>DB: Record KB ownership binding
  API-->>Client: Signed upload token
  Client->>API: Request part URLs
  API-->>Client: Signed part URLs
  Client->>Store: Upload parts
  Client->>API: Complete upload
  API->>Store: Assemble and verify object
  API->>DB: Look up deterministic document ID
  alt Document already bound
    DB-->>API: Existing document
  else First completion
    API->>DB: Create pending document
    API->>Queue: Queue document processing
  end
  API-->>Client: Completed upload and document

Loading

_{Reviews (5): Last reviewed commit: "fix(uploads): prevent multipart cleanup ..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 09c27a4. Configure here.}