mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-03 17:51:58 +01:00
DottaandPaperclip
82c033ed12
## Thinking Path > - Paperclip lets people assign work to agents and manage their tasks. > - Product E2E journeys verify the saved outcome through the browser and normal APIs. > - Uploaded input and personal inbox actions need repeatable coverage. > - An agent answer must match the input file, and an inbox action must retain its saved state. > - This change adds two journeys with independent evidence checks. > - A blocked fixture action must use the normal human-owned unblock contract. > - Registration stays separate from deployed qualification and daily admission. ## Linked Issues or Issue Description **What existing behavior does this improve?** Product E2E coverage for file attachments, saved task documents, and personal inbox read and archive actions. **Current behavior** The journey catalog lacks an uploaded-input calculation and a persisted personal inbox triage path. A successful agent run alone cannot prove either outcome. **Proposed behavior** Upload a generated CSV through the task composer. Require an exact saved answer and unchanged input bytes. Read and archive one owned task through the inbox, reload each state, and verify that a new Blocked event brings it back without agent work. ## What Changed - Add a file-input journey with a random reference held only in the uploaded CSV. - Check exact result values, document authorship, native run binding, original input bytes, and persistence after reload. - Add a browser inbox journey with an independently authenticated human author, saved read and archive state, unchanged work status, and activity resurfacing checks. - Reject wrong, missing, duplicate, and foreign evidence in assertion controls. - Register both cases and document their scope and privacy rules. - Supply a current-human unblock owner and action for the archived-task fixture. Test that exact payload through the production route and retain the bare-blocked422 negative control. - Include the fixture constructor in the source definition hash and both new cases in the exact catalog assertion. - Reject collected inbox receipts with unexpected runs, providers, models, or native/legacy execution modes. ## Verification - The frozen source is `cdb6659fb4e4b67e9321bc3fd963cf11e9b8b2f3`. It includes one fixed master integration at `fd0d61b8e329efc89ff541dc2cac44e7c7a37f78`. The single map conflict retains both coverage paragraphs. - The production HTTP route rejects the original bare blocked payload with422 and accepts the exact human-owned fixture payload with200. Neither control wakes an agent. The full related route file passes all200 tests. - The frozen current head passes recursive workspace typecheck, runner typecheck, full build, map checks, and diff checks. Its full related journey/catalog suite passes723 tests, the production route suite passes200, and the separate Node support suite passes347. The retained contract file passes all38 tests. Fresh Greptile review is 5/5 on the frozen current head. Current-head hosted CI passes after one authorized failed-jobs-only recheck. The original Runner close test failed; the unchanged, properly cargo-prepared focused local control passed in2.99s, and the hosted recheck then passed. The cause remains unknown; no Runner code, test timing, or assertion changed. The original hosted diagnostic and the initial invalid local invocation without required fake binaries remain recorded. The ordinary local full-test run is in progress. - The unrestricted local runner support run on the fixed-master integration is not green:5993 tests passed,12 failed,3 skipped. The unchanged failures cover onboarding cleanup expectations, Pi metadata, workflow-security expectations, and an expired test allowance. An untouched743 baseline reproduces the same non-PG failures; their source/test blobs also match pre-feature40b807. This change does not extend an allowance or alter paid admission. The original5983-pass/15-failure run remains recorded. Restoring the local Postgres package's own library aliases resolved its two startup failures. The feature-related catalog omission is corrected. - The uploaded-file case passed its first complete deployed QA attempt: one configured native run, all six independent checks, original evidence, complete cleanup, and no active operations. - The first inbox attempt stopped at the agent comment execution-context guard. That guard stays intact. The fixture uses an approved, independently authenticated QA human. - The next original inbox attempt verified protected-secret retrieval, human attribution, and session closure, then failed its unread prerequisite. The product unread defect was repaired in #18670. - The fresh deployed inbox attempt passed external-human activity, saved read state, archive persistence, and unchanged task status after the product rollout. It then stopped at the fixture's bare blocked PATCH before any resurfacing assertion. The response status was discarded;422 is an explicit contract inference independently reproduced through the production route. That failed attempt remains retained. A fresh full inbox qualification on the current frozen head now passes all six checks and all five phases; the normal human comment receipt, closed human session, zero agent work, complete cleanup, and absence of active operations are verified in the original evidence. Daily admission remains a separate coordinator action. - The retained-result review gap failed a negative receipt control before the repair. All38 retained journey contract tests now pass. The two old unread advisory threads are resolved only after the fresh full deployed inbox pass. - Original failures remain recorded, including the earlier unchanged environment-runtime assertion and unchanged runner/occupied-port startup failures. Closed operation codes and failure screenshots retain the failing step without raw browser errors. Actual retry qualification remains separate from source tests. ## Risks The target must supply the declared external-human fixture. Inbox control selectors may differ across deployed UI revisions. File processing depends on the configured native agent. Exact saved-state and source checks must remain required when those dependencies fail. The change adds test journeys and does not change production behavior or schemas. ## Model Used OpenAI GPT-6 through Codex, with reasoning, code execution, and browser tools. The runtime does not expose a more specific model identifier or context-window size. ## 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 (relevant suites; broader baseline failures are listed above) - [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 - [x] 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>
145 lines
9.4 KiB
Markdown
145 lines
9.4 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.
|
||
|
||
The deployment-targeted [uploaded-input journey](../../tests/runner-e2e/product-journeys/input-file-flow.ts)
|
||
adds composer upload, real agent consumption, independent calculation, attributed
|
||
saved output and reload checks. Registration and oracle controls do not establish
|
||
a live pass on a deployment.
|
||
|
||
[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.
|