mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-03 17:51:58 +01:00
DottaandPaperclip
cd12432947
## Thinking Path > - Paperclip manages AI agents and keeps their results attached to tasks. > - Native tools return links to saved task documents. > - Completion feedback asks agents to include those links. > - The file-delivery validator treated every such relative link as a workspace path. > - A valid document and CSV result could therefore fail completion when it cited the supplied document link. > - This change derives document links from the same verified publication projection for guidance and validation. > - Requested files still need their own verified delivery evidence. ## Linked Issues or Issue Description **What happened?** The native document tool and completion feedback produce a link such as `/EX/issues/EX-1#document-output`. When a task also requests a downloadable CSV, citing that link causes completion to reject it as a workspace-only file. This occurs even when the document is published and the file has a valid current-run delivery receipt. **Expected behavior** Accept a server-derived document link only when it names the current company/task and a currently attached revision with a matching native publication receipt. Keep the separate requested-file requirement and all foreign, stale, missing, and workspace-file guards. **Steps to reproduce** 1. Save a task document through the native `write_document` tool. 2. Publish a CSV through `register_deliverable`. 3. Ask completion feedback for the final-response guidance. 4. Cite its returned document link alongside the file receipt in the next completion report. 5. The old validator rejects the valid document link as a workspace-only file. **Paperclip version or commit** Current source checkout. The regression exercises the real native document producer and completion validator. **Deployment mode** Local source verification on macOS arm64 with Node 24.22.1, pinned pnpm 9.15.4, locked dependencies, temporary PostgreSQL, and a controlled remote file-reader boundary. No live provider or hosted deployment is included. ## What Changed - Derive the canonical document href in the existing company/task/current-revision publication query. - Use that same verified href in completion guidance and reference validation. - Keep file registration and hash/size receipt requirements separate from document evidence. - Cover evidence, artifact, and criterion references; foreign companies/tasks; bogus keys; local paths; and lost current-revision publication proof. - Exercise actual native document writes and CSV registration, including attachment download query and fragment links. - Update the execution contract and the document feature/access maps. ## Verification - Red before the production edit: native completion generated a real saved-document link, then rejected the same link alongside a valid published file. The failure was the workspace-only-file guard. - Green: 210 tests across native completion feedback, explicit output validation, and the existing native file-handoff suite pass. These use real PostgreSQL and native tool receipts; the remote file reader is controlled. - A saved document link alone still fails the explicit CSV requirement. A document whose current revision lacks its publication receipt is rejected. Foreign task/company links, missing keys, malformed links, and workspace paths remain rejected. - Full workspace typecheck, server typecheck, and production build pass. - `node scripts/check-maps.mjs`, `node scripts/check-module-boundaries.mjs`, and `git diff --check` pass. Map checks establish structure only. - Full `pnpm test:run` is running separately. There is no full-suite verdict yet. CI and review are pending. - Hosted acceptance and any recovery of existing tasks remain separate steps. This PR does not change final-response recovery or scheduling. ## Risks - An overly broad URL exception could admit foreign or unpublished output. The validator accepts only exact hrefs from the authenticated publication projection. - Document evidence could hide a missing requested file. A separate regression keeps that delivery gate effective. - The shared projection adds current task/company joins. Existing document feedback and publication tests cover those consumers. ## Model Used OpenAI `gpt-6.1-sol` through Codex, with reasoning, code editing, shell execution, and automated tests. The context-window size is not exposed in this session. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing>
140 lines
9.1 KiB
Markdown
140 lines
9.1 KiB
Markdown
---
|
||
navigation: {"section":"Tasks and conversations","sectionOrder":20,"order":70}
|
||
---
|
||
|
||
# Documents, attachments, and work products
|
||
|
||
People read and revise task documents, annotate specific content, open attached files, and inspect the outputs an agent hands back. The artifact library provides another route to the same work.
|
||
|
||
Feature ID: `documents-artifacts`.
|
||
|
||
Implementation: [task documents](../../ui/src/components/IssueDocumentsSection.tsx), [artifact library](../../ui/src/pages/Artifacts.tsx), [document panel](../../ui/src/components/task-side-panel/TaskDocumentPanel.tsx).
|
||
|
||
Agent access: [companion](../agent-access-map/documents-artifacts.md).
|
||
|
||
## Sub-features
|
||
|
||
- `documents`: `documents-artifacts/documents` — edit versioned task documents and inspect or restore revisions.
|
||
- `annotations`: `documents-artifacts/annotations` — attach feedback to document content and inspect resolution state.
|
||
- `attachments`: `documents-artifacts/attachments` — upload, preview, and download allowed files with company access checks.
|
||
- `work-products`: `documents-artifacts/work-products` — link deliverables to their source task, resource, and review context.
|
||
- `library`: `documents-artifacts/library` — search, filter, group, and open artifact stacks.
|
||
|
||
## How to get to it (user POV)
|
||
|
||
### `task-document`
|
||
|
||
Open a document from the task thread or document side panel.
|
||
|
||
To create or edit a general task document, open **Open a new tab → Artifacts**
|
||
in the task side panel, then **New document** or **Document actions → Edit
|
||
document**. Edits use the shared versioned editor and autosave. Classic mode
|
||
keeps that editor in the task body. Plans retain their conversation and approval
|
||
flow and cannot be created through the general document editor.
|
||
Unfinished new documents, including a body typed before its key, survive a tab
|
||
switch or reload within the same account and task. Cancel removes the backup;
|
||
a confirmed creation clears it.
|
||
|
||
Select an inline image to open the document's image gallery. Use the left and
|
||
right arrow keys or the Previous and Next buttons to move through images in
|
||
reading order. The URL retains the document and adds a one-based `image` position,
|
||
such as `#document-report&image=2`. Share or reload that URL to open the same image.
|
||
Revision and maximized-view parameters remain in the link. Escape, Close, or the
|
||
backdrop closes the gallery and returns focus to the image.
|
||
|
||
Coordinator decision receipts also open a pinned reviewed revision alongside
|
||
the matching task interaction. Historical tabs retain their revision identity
|
||
independently of the current document tab. Missing revisions are explicit and
|
||
never silently replaced with the latest document.
|
||
When a decision in one task reviews another task's document, the center pane
|
||
keeps the originating conversation while the sidebar opens the document owner's
|
||
exact revision. An inaccessible owner never falls back to the origin task's document.
|
||
|
||
### `task-output`
|
||
|
||
Open an attachment, output card, or file link from a task.
|
||
For direct uploads, use the task side panel's **Open a new tab → Artifacts →
|
||
Upload files** or drop files anywhere in that panel. On mobile, open
|
||
**More actions → Properties** first. Agent conversations do not expose this upload path.
|
||
|
||
### `artifact-library`
|
||
|
||
Open `/artifacts` and its grouping, search, and media controls.
|
||
|
||
## Driving it with Playwright and the Paperclip CLI
|
||
|
||
The explicit `build-revise` [Product journey](../../tests/runner-e2e/PRODUCT-JOURNEYS.md) covers `documents-artifacts/attachments`: browser downloads of two ZIP versions, an independent content oracle, and preservation of the original. Its shared source is not proof of a pass on any deployed target.
|
||
|
||
The explicit `task-document-persistence` journey covers `documents-artifacts/documents`:
|
||
browser creation and editing, task reopen/reload, exact saved title/body and
|
||
independent original/latest revision reads, board-user authorship and zero agent
|
||
runs. The setup owns a backlog task but does not seed a document. Calibration
|
||
rejects stale content, lost history and foreign ownership. A target needs a fresh
|
||
live pass before adding this journey to its scheduled checks.
|
||
|
||
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use a task with a text document, a small attachment, and a generated work product. Use nonsensitive fixture files.
|
||
|
||
### `task-document`
|
||
|
||
Automated: [documents service](../../server/src/__tests__/documents-service.test.ts), [annotations](../../server/src/__tests__/document-annotations-service.test.ts), and [revision restore](../../server/src/__tests__/issue-document-restore-routes.test.ts) cover server contracts.
|
||
|
||
[Document image galleries](../../tests/e2e/document-image-gallery.spec.ts) checks
|
||
desktop, mobile, and Classic document views with real uploaded images and saved
|
||
document revisions. It covers keyboard/button navigation, image URLs and reload,
|
||
focus return, focus containment, scroll locking, dismissal, and revision links.
|
||
|
||
[Exact revision panel](../../ui/src/components/task-side-panel/TaskDocumentPanel.test.tsx)
|
||
checks pinned content and missing-revision behavior; this component test does not
|
||
prove end-to-end conversation scrolling. Open a resolved receipt after making a
|
||
new revision and verify the earlier body plus matching interaction in the browser.
|
||
|
||
Manual: Edit a paragraph, save, reload, and compare revisions. Add an annotation to a specific selection and inspect it after another edit. Resolve it through the supported action. Restore a disposable revision and confirm the new current document and history agree.
|
||
|
||
### `task-output`
|
||
|
||
Automated: [attachment routes](../../server/src/__tests__/issue-attachment-routes.test.ts) and [work products](../../server/src/__tests__/work-products.test.ts) cover data/access behavior; [artifact arrival browser suite](../../tests/e2e/artifact-tab-arrival.spec.ts) targets arrival. [Artifact uploads](../../tests/e2e/artifact-uploads.spec.ts) drives file selection/drop, filename collisions, retry, and preservation of paused/unassigned tasks.
|
||
|
||
[Native completion feedback](../../server/src/services/native-runtime/native-completion-feedback.test.ts)
|
||
checks a real saved-document link alongside a verified CSV attachment, including
|
||
attachment download query and fragment links. It rejects foreign task/company
|
||
links, missing documents, unproven current revisions, and workspace files. The
|
||
document alone cannot satisfy the requested file. These local tool/Postgres
|
||
checks do not establish hosted delivery or browser rendering.
|
||
|
||
Manual: Upload a small Markdown file and CSV through Artifacts. Markdown becomes
|
||
a versioned task document; other files become attachments. Read the document,
|
||
download the CSV and compare bytes, then reload. Upload the same Markdown filename
|
||
again and verify a separate suffixed document without overwriting the original.
|
||
On a paused unassigned task, confirm upload does not start work or add comments.
|
||
Verify agent-produced work products separately using an eligible test run.
|
||
Test an inaccessible user/company and explicit missing workspace-only resources.
|
||
|
||
### `artifact-library`
|
||
|
||
Automated: [artifact page](../../ui/src/pages/Artifacts.test.tsx) covers grouping, search requests, and pagination using mocks.
|
||
|
||
Manual: Find the task’s output through search and grouping, open its stack, page through results, and reload a direct stack link. Confirm the same file/content appears as from the task.
|
||
|
||
## Gotchas
|
||
|
||
- In Coordinator, saved plan cards use document chronology, so a plan written before its output appears first even when both writes share one native run. Authored issue-document links use the same compact sidebar-link surface and retain revision/annotation targets. Classic run embedding is unchanged. The UI does not remove or deduplicate canonical plan content.
|
||
|
||
- A local path is not automatically an uploaded artifact accessible to another user.
|
||
- A preview screenshot is not proof that download bytes or revision references are correct.
|
||
- Version conflicts and stale annotations must stay visible rather than silently targeting different content.
|
||
|
||
### Storybook verification
|
||
|
||
#### `documents`
|
||
|
||
Capability ID: `documents-artifacts/documents`.
|
||
|
||
Scope: ui
|
||
Storybook: Writable/read-only document, save pending/failure/conflict, revision history/historical preview and restore confirmation.
|
||
Production: Persist edited body and reload; append-only restore creates new revision; reject stale writes and inaccessible company/task.
|
||
Sources: Source: [IssueDocumentsSection.tsx](../../ui/src/components/IssueDocumentsSection.tsx), [TaskDocumentPanel.tsx](../../ui/src/components/task-side-panel/TaskDocumentPanel.tsx), [documents.ts](../../server/src/services/documents.ts). Tests: [IssueDocumentsSection.test.tsx](../../ui/src/components/IssueDocumentsSection.test.tsx), [document-revisions.test.ts](../../ui/src/lib/document-revisions.test.ts), [documents-service.test.ts](../../server/src/__tests__/documents-service.test.ts), [issue-document-restore-routes.test.ts](../../server/src/__tests__/issue-document-restore-routes.test.ts)
|
||
|
||
### Documentation scope: Artifacts and work products
|
||
|
||
Document/attachment/library/work-product journeys are mapped; every media preview type, storage backend, annotation conflict, and runtime-resource lifecycle variant remains separate.
|