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.