DottaandPaperclip
cd5f930558
<!-- entire-trail-link-start --> https://entire.com/gh/paperclipai/-/trails/247/changes/paperclip/247 <!-- entire-trail-link-end --> ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Task documents hold plans, reports, and image evidence. > - Task attachments already have an image gallery. > - Inline document images had no gallery navigation or image links. > - This change gives each document a gallery that uses the existing modal. > - People can review the image sequence and share a link to one image. ## Linked Issues or Issue Description **What existing behavior does this improve?** Image review in task documents, including the side panel and Classic interface. **Current behavior** Inline document images do not open a gallery. People cannot move through them with arrow keys or share a link to one image. **Proposed behavior** Select an image to open the gallery. Use arrow keys or Previous and Next. The URL records its one-based position, for example `#document-report&image=2`. Reloading that URL opens the selected image. Revision links keep their exact saved content. **Reason and benefit** People can inspect a document's image evidence in reading order and share the exact view. No matching issue was found. The latest 300 open PR titles were checked for related document gallery work. ## What Changed - Add a document renderer that collects rendered images in reading order, including reference-style and repeated images. - Reuse the gallery modal with optional index-change and focus-return controls. - Keep the document owner in the saved tab identity when people switch between local and other-task documents. - Match explicit current-task document owners with local document tabs. Keep review and viewer parameters during gallery navigation. - Treat another Classic review receipt as a new request while image navigation retains the selected revision. - Make inline image controls work with a keyboard. Keep focus in the modal and restore focus on close. - Keep document, revision, review, and maximized-view link parameters during image navigation. - Fix a Classic revision-cache race found by the browser test. Recheck a pinned revision when the saved document head changes. - Update the feature and agent access maps. No new server API or permission is needed. ## Verification - Passed 119 focused tests for document galleries, the shared gallery, document rendering, the revision panel, and hash routing. - Passed all 3 Chromium journeys: desktop, mobile, and Classic. These use real uploads and saved document revisions. - The browser journeys also check explicit current-task owners, review parameters after reopening, other-task links after tab switches, and a second Classic review link after Return to latest. - Browser checks cover keyboard and button navigation, wraparound, shared-link reload, exact historical content, invalid positions, focus return and containment, scroll locking, and Escape, Close, and backdrop dismissal. - UI typecheck, token gates, map checks, and diff whitespace checks passed. - The UI production build passed in the browser harness. - Earlier browser runs found and then verified the Classic revision-cache fix. A later build exited 137 while the full test suite ran. The browser run passed after that suite stopped. - Full repository typecheck and build could not complete because Cargo is absent. The full repository test run did not complete within this sandbox. These checks remain subject to CI. ## Risks - Image positions follow document reading order. Editing an unpinned document can change those positions. A revision link retains the saved sequence. - The shared modal now uses Radix Escape handling. The existing gallery tests and nested mobile dialog journey pass. - No schema change or migration. ## Model Used OpenAI GPT-6 through Codex. The runtime did not expose a more specific model ID or context window size. Used reasoning, code editing, shell commands, and browser automation. ## 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 - [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>
6.5 KiB
Documents, attachments, and work products — agent access
Product map: Documents, attachments, and work products.
Feature ID: documents-artifacts.
Review date: 2026-10-12. Source commit: f981fa3cc10cb8663a87dec60345fbff46d54d0a.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
documents
Capability ID: documents-artifacts/documents.
Document image selection is browser presentation state. It needs no new API or
agent permission. Agents can share #document-<key>&image=<one-based-position>
links with optional revision and viewer=full parameters. Existing task,
document, revision, and image resource read permissions still apply.
Coordinator receipt reads add GET /api/issues/{id}/documents/{key}/revisions/{revisionId}.
It applies the same task-read authorization as document revision history and
queries exactly one revision under that task/document key. It does not fall back
to current content. Cross-task receipts retain both the originating interaction
and document owner; sidebar reads use the owner's existing authorization boundary.
The document service regression
checks exact identity and cross-key/task misses against temporary PostgreSQL;
route and live caller authorization remain separately verified.
Review: baseline.
API: present — representative operation IDs:
GET /api/issues/{id}/documents.PUT /api/issues/{id}/documents/{key}.POST /api/issues/{id}/documents/{key}/revisions/{revisionId}/restore.
Agent access: available — Native list/read/write documents; other-task bridge; REST /
CLI / MCP.
Policy: Task/resource visibility, mutation/checkout ownership, revision/lock guards and permitted deliverable context.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Supported. Native helpers focus on the active task; generic API or explicit other-task tools cover additional scope.
annotations
Capability ID: documents-artifacts/annotations.
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/documents/{key}/annotations.PATCH /api/issues/{id}/documents/{key}/annotations/{threadId}.
Agent access: available — REST / native call_api.
Policy: Task/resource visibility, mutation/checkout ownership, revision/lock guards and permitted deliverable context.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Annotation operations exist without a special annotation tool; check revision anchors and resolver authority.
attachments
Capability ID: documents-artifacts/attachments.
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/issues/{issueId}/attachments.GET /api/assets/{assetId}/content.
Agent access: available — Native register_deliverable and API multipart/binary
support; REST / CLI / MCP transfers.
Policy: Task/resource visibility, mutation/checkout ownership, revision/lock guards and permitted deliverable context.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Queue and HTTP/2 sandbox callbacks admit GET /api/assets/{assetId}/content,
including screenshot references in task descriptions. The controller still checks
company and task visibility before opening storage.
Gaps: Native API uploads are bounded; attachment reading has target/provider and permission conditions.
work-products
Capability ID: documents-artifacts/work-products.
Review: baseline.
API: present — representative operation IDs:
POST /api/issues/{id}/work-products.PATCH /api/work-products/{id}.
Agent access: available — Native register_deliverable for file outputs; REST / native
call_api for metadata.
Policy: Task/resource visibility, mutation/checkout ownership, revision/lock guards and permitted deliverable context.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: A registered reference does not prove uploaded bytes, external delivery, or accepted review.
library
Capability ID: documents-artifacts/library.
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/artifacts.
Agent access: available — REST / native call_api.
Policy: Task/resource visibility, mutation/checkout ownership, revision/lock guards and permitted deliverable context.
Evidence: source-only — implementation at
the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Library search/filter uses the artifact API; no new tool needed merely to mirror the UI.