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>
7.1 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.
Native completion evidence accepts the server's relative link only for a document attached to the current company/task with a matching current-revision publication receipt. It can accompany a separately verified requested file; it cannot replace that file. The native feedback regression exercises the native write/register/finish boundary with local PostgreSQL and a controlled remote file reader. It does not qualify the whole document API or a live provider run.
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.