From c145475cae537dd202eac878b0864fce4fcfcad4 Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Mon, 19 Oct 2026 16:27:05 -0500 Subject: [PATCH] fix: admit documented sandbox task context routes (#16892) ## 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 --- maps/agent-access-map/documents-artifacts.md | 4 ++ maps/agent-access-map/skills.md | 5 ++- maps/agent-access-map/tasks.md | 5 +++ .../src/sandbox-callback-bridge.ts | 5 +++ .../sandbox-callback-context-routes.test.ts | 42 +++++++++++++++++++ skills/paperclip/references/api-reference.md | 12 ++++++ 6 files changed, 72 insertions(+), 1 deletion(-) create mode 100644 packages/adapter-utils/src/sandbox-callback-context-routes.test.ts diff --git a/maps/agent-access-map/documents-artifacts.md b/maps/agent-access-map/documents-artifacts.md index afa3297a1dc..f1ad428f8e4 100644 --- a/maps/agent-access-map/documents-artifacts.md +++ b/maps/agent-access-map/documents-artifacts.md @@ -85,6 +85,10 @@ credentials/run context; inspect its result and applicable persistence/attributi 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. diff --git a/maps/agent-access-map/skills.md b/maps/agent-access-map/skills.md index 6106b0eb541..4aa6298bf3b 100644 --- a/maps/agent-access-map/skills.md +++ b/maps/agent-access-map/skills.md @@ -20,7 +20,10 @@ API: `present` — representative operation IDs: - `GET /api/companies/{companyId}/skills`. - `POST /api/companies/{companyId}/skills/import`. -Agent access: `available` — REST / native call_api / CLI skills and sources. +Agent access: `available` — REST / native call_api / CLI skills and sources. Queue +and HTTP/2 sandbox callbacks also admit company skill detail and file reads; +file paths travel in the existing `path` query parameter. Skill mutations stay +subject to the existing bridge restrictions. Policy: Company skill policy by action/resource plus platform invariants; test execution additionally requires task-assignment authority. diff --git a/maps/agent-access-map/tasks.md b/maps/agent-access-map/tasks.md index ce8ec6f181c..bf7d4b76aa1 100644 --- a/maps/agent-access-map/tasks.md +++ b/maps/agent-access-map/tasks.md @@ -120,6 +120,11 @@ regressions in [ownership tests](../../server/src/__tests__/issue-agent-mutation cover a human handoff and stop enforcement for other actors, runtimes and targets; they use mocked services and do not claim live execution proof. +Queue and HTTP/2 sandbox callbacks admit `GET /api/issues/{id}/diagnostics/wakes` +and `POST /api/issues/{id}/monitor/check-now`. The controller still checks task +read access or monitor-management permission and assignment ownership. Recovery +resolution and scheduled-retry controls remain outside this bridge surface. + Monitor verification: submit flat scheduling fields, observe the schema rejection and unchanged task, then retry with the nested `monitor` object and the same idempotency key. Inspect the saved schedule and audit, yield, and verify exactly diff --git a/packages/adapter-utils/src/sandbox-callback-bridge.ts b/packages/adapter-utils/src/sandbox-callback-bridge.ts index 4cf624599e2..4c932b11e16 100644 --- a/packages/adapter-utils/src/sandbox-callback-bridge.ts +++ b/packages/adapter-utils/src/sandbox-callback-bridge.ts @@ -151,6 +151,8 @@ export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCa { method: "GET", path: /^\/api\/companies\/[^/]+\/approvals$/ }, { method: "GET", path: /^\/api\/companies\/[^/]+\/routines$/ }, { method: "GET", path: /^\/api\/companies\/[^/]+\/skills$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/skills\/[^/]+$/ }, + { method: "GET", path: /^\/api\/companies\/[^/]+\/skills\/[^/]+\/files$/ }, { method: "GET", path: /^\/api\/projects\/[^/]+$/ }, { method: "GET", path: /^\/api\/goals\/[^/]+$/ }, @@ -170,6 +172,8 @@ export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCa // Issue lifecycle: read context, checkout, update, comment, document, release { method: "GET", path: /^\/api\/issues\/[^/]+$/ }, { method: "GET", path: /^\/api\/issues\/[^/]+\/heartbeat-context$/ }, + { method: "GET", path: /^\/api\/issues\/[^/]+\/diagnostics\/wakes$/ }, + { method: "POST", path: /^\/api\/issues\/[^/]+\/monitor\/check-now$/ }, // The controller still checks company membership and issue read authority. { method: "GET", path: /^\/api\/issues\/[^/]+\/activity$/ }, { method: "GET", path: /^\/api\/issues\/[^/]+\/comments(?:\/[^/]+)?$/ }, @@ -186,6 +190,7 @@ export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCa { method: "GET", path: /^\/api\/issues\/[^/]+\/attachments$/ }, { method: "POST", path: /^\/api\/companies\/[^/]+\/issues\/[^/]+\/attachments$/ }, { method: "GET", path: /^\/api\/attachments\/[^/]+\/content$/ }, + { method: "GET", path: /^\/api\/assets\/[^/]+\/content$/ }, // Work products: publish branch/commit/artifact metadata for completed work. { method: "GET", path: /^\/api\/issues\/[^/]+\/work-products$/ }, diff --git a/packages/adapter-utils/src/sandbox-callback-context-routes.test.ts b/packages/adapter-utils/src/sandbox-callback-context-routes.test.ts new file mode 100644 index 00000000000..02644a2f944 --- /dev/null +++ b/packages/adapter-utils/src/sandbox-callback-context-routes.test.ts @@ -0,0 +1,42 @@ +import { describe, expect, it } from "vitest"; +import { + authorizeSandboxCallbackBridgeRequestWithRoutes, + HTTP2_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST, +} from "./sandbox-callback-bridge.js"; + +const contextRequests = [ + { method: "GET", path: "/api/assets/screenshot-1/content" }, + { method: "GET", path: "/api/companies/company-1/skills/skill-1" }, + { method: "GET", path: "/api/companies/company-1/skills/skill-1/files", query: "?path=references%2Fworkflow.md" }, + { method: "GET", path: "/api/issues/task-1/diagnostics/wakes" }, + { method: "POST", path: "/api/issues/task-1/monitor/check-now" }, +]; + +const deniedRequests = [ + { method: "POST", path: "/api/assets/screenshot-1/content" }, + { method: "DELETE", path: "/api/assets/screenshot-1/content" }, + { method: "GET", path: "/api/assets/screenshot-1/content/extra" }, + { method: "PATCH", path: "/api/companies/company-1/skills/skill-1" }, + { method: "PATCH", path: "/api/companies/company-1/skills/skill-1/files" }, + { method: "DELETE", path: "/api/companies/company-1/skills/skill-1/files" }, + { method: "GET", path: "/api/companies/company-1/skills/skill-1/files/extra" }, + { method: "POST", path: "/api/issues/task-1/diagnostics/wakes" }, + { method: "GET", path: "/api/issues/task-1/diagnostics/wakes/extra" }, + { method: "GET", path: "/api/issues/task-1/monitor/check-now" }, + { method: "POST", path: "/api/issues/task-1/monitor/check-now/extra" }, + { method: "POST", path: "/api/issues/task-1/recovery-actions/resolve" }, +]; + +describe.each([ + ["queue", undefined], + ["HTTP/2", HTTP2_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST], +] as const)("sandbox task context over %s", (_transport, routes) => { + it.each(contextRequests)("admits documented context request $method $path", request => { + expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request, routes)).toBeNull(); + }); + + it.each(deniedRequests)("keeps unrelated operations denied: $method $path", request => { + expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request, routes)) + .toBe(`Route not allowed: ${request.method} ${request.path}`); + }); +}); diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.md index 46cdbd73f4b..30a06b8e4ed 100644 --- a/skills/paperclip/references/api-reference.md +++ b/skills/paperclip/references/api-reference.md @@ -1699,3 +1699,15 @@ identity, or a closed task receive 409; unrelated connections receive 404. No credentials or provider authorization URL appear in the card payload. For sandbox run inspection, see [Run diagnostics from a sandbox](run-diagnostics.md). + +**Sandbox task context routes.** + +The queue and HTTP/2 callback bridges admit company skill detail and file reads, +`GET /api/assets/{assetId}/content`, `GET /api/issues/{id}/diagnostics/wakes`, +and `POST /api/issues/{id}/monitor/check-now`. Use the asset URL embedded in the +task to read its screenshot. Use the skill files route with a `path` query +parameter to read a referenced script or instruction file. + +Bridge admission does not grant resource access. The controller rechecks company, +task and skill visibility, and monitor-management permission. Asset mutations, +skill-file mutations and recovery-action resolution remain restricted.