mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 16:27:18 +02:00
DottaandPaperclip
c145475cae
## Thinking Path > - Paperclip agents use task context to complete assigned work. > - Sandboxed agents reach the controller through a bounded callback bridge. > - The bridge rejects several documented context routes before controller authorization runs. > - An authorized agent cannot read a task screenshot or referenced skill file, or inspect a missed monitor wake. > - This pull request admits only the exact context routes and supported methods. > - The controller continues to enforce company, resource, task and monitor authority. ## Linked Issues or Issue Description **What happened?** Both callback transports return `Route not allowed` for task asset content, company skill detail and files, wake diagnostics, and the monitor check-now action. These operations already exist in the controller. **Expected behavior** A sandboxed agent can use these documented operations when the controller authorizes its request. Other methods, deeper paths, skill mutations, and recovery resolution remain restricted. **Steps to reproduce** Use a sandbox callback to read an asset URL from a task description, read a company skill's referenced file, or inspect a task's wake diagnostics. The baseline bridge rejects each request. The new regression matrix runs all five operations against both transport allowlists. Related: #16772 documents refused callback routes. This PR fixes the context routes listed above; it does not add company-wide activity or labels access. ## What Changed - Admit asset content, skill detail/files, and wake diagnostic reads. - Admit the existing monitor check-now action with controller authorization. - Add a focused allow/deny matrix for both transports. - Update the operational API reference and access maps. ## Verification - With the pre-fix bridge rules, all 10 allowed-request cases fail with `Route not allowed` across the two transports; all 24 deny controls still pass. - With the fix restored, all 34 route cases pass. The matrix plus existing callback suite passes 119 tests across two files. - Local `pnpm -r typecheck` and `pnpm build` pass. - The access-map checker, capability contract generation check, and capability inventory check pass. - Full repository CI passes on `97f9f06b2c`: typecheck/release registry, all test shards, build, Docker context, canary dry run, and aggregate verify. - The duplicate local full-suite run was stopped after 24 minutes once full CI passed; it is not claimed as a completed local pass. - Greptile is 5/5 on the current head with no inline findings. Independent source review checked asset, skill, wake-diagnostic, and monitor controller authorization and found no actionable issues. - The secondary Paperclip automated review is neutral/incomplete. Independent review covered its missing controller checks; the real Vitest cases and full CI provide execution evidence. ## Risks This widens transport admission for five existing operations. It does not change controller authorization. Asset reads still check company/task visibility; skill reads keep source policy; monitor checks keep ownership and management permission. No schema or UI change is required. ## Model Used OpenAI Codex, GPT-6 family, with tool use and code execution. The session does not expose the exact serving model ID or context window. The work used failing-before and passing-after regression tests. ## 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>
144 lines
5.3 KiB
Markdown
144 lines
5.3 KiB
Markdown
# Documents, attachments, and work products — agent access
|
|
|
|
Product map: [Documents, attachments, and work
|
|
products](../feature-map/documents-artifacts.md).
|
|
|
|
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](../README.md)
|
|
for format, permission checks, evidence and maintenance.
|
|
|
|
## `documents`
|
|
|
|
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](../../server/src/routes/issues.ts#L10299) 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`
|
|
|
|
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](../../server/src/routes/issues.ts#L10299) 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`
|
|
|
|
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](../../server/src/routes/issues.ts#L10299) 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`
|
|
|
|
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](../../server/src/routes/issues.ts#L10299) 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`
|
|
|
|
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](../../server/src/routes/issues.ts#L10299) 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.
|