DottaandPaperclip
60b8089a44
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Cloud selects and updates the sandbox image used by its agents. > - Runner admission also required saved qualification for the exact snapshot and configuration. > - An image update left the old record stale and stopped work before runtime startup. > - This pull request trusts the image selected by Cloud and uses the real runtime startup check. > - Agents can continue after an image update without an operator running a separate qualification test. ## Linked Issues or Issue Description **What happened?** A managed Cloud image update could cause `sandbox_snapshot_qualification_required` before provider work began. Runner discovery also fell back to Legacy when saved platform qualification was absent. The agent Test action could require a separate qualification request even when discovery already offered Paperclip Runner. **Expected behavior** A managed Cloud image can start without a saved qualification record. Runtime startup and the handshake report actual compatibility failures. Custom images keep their existing qualification rules. **Steps to reproduce** 1. Use Paperclip Runner on a Paperclip-managed Cloud sandbox. 2. Save qualification for its current snapshot. 3. Update the platform-selected snapshot and leave the old record in place. 4. Start a task. Before this fix, admission rejects the stale record before starting the provider. Related work: Refs #17445, Refs #17724, Refs #17448. These changes cover saved-computer qualification and setup tests. This fix removes the qualification prerequisite only for managed Cloud images. ## What Changed - Use one managed-image policy in runner selection and lease admission. Require the active Cloud configuration to provision the provider. Active captured custom images are excluded. - Use the current Cloud image and ignore missing, stale, revoked or valid saved qualification records for that image. - Reuse the existing provisioned-runner selection path. Keep adapter availability checks and the Legacy choice for managed sandboxes. - Read custom-image metadata directly during discovery without resolving provider credentials. - Use the existing template-matching rule for captured images. Ignore outdated captures, preserve qualification for matching custom captures, and fall back to Legacy discovery for malformed saved capture config. - Skip the separate qualification request when discovery already offers Paperclip Runner as the default. Test checks the actual runtime. - Add regressions for image updates, provider failures, custom images, self-hosted environments and company access. Update the development and verification guides. ## Verification - Before the fix, managed-image discovery regressions returned Legacy, and the rendered Test action called the separate qualification endpoint. - The original runtime source fails four of the five managed-image regression cases. The fixed runtime passes all five, including provider startup error propagation. The baseline check uses the original module source through a temporary Vitest transform and the same database-backed tests. - All 603 focused tests pass: 231 runner selection, 185 environment runtime, 10 snapshot qualification, 168 rendered agent form and nine form source controls. Discovery controls cover unavailable credentials, stale managed markers without an active provisioner, outdated captures, matching custom captures and malformed saved config. The outdated-capture regression fails before the fix and passes afterward. - `node scripts/check-maps.mjs` and `pnpm check:token-gates` pass. - Full `pnpm -r typecheck` and `pnpm build` pass. All five focused files passed together on `8275bbe72bb4d91fb3a02fb0658f0846b2abc966` (`codex/simplify-managed-runner-readiness`, Node 24.19.0, macOS ARM64). - The full local `pnpm test:run` suite is still in progress. Hosted CI is waiting at `ci / gate / Select trusted runner`; the separate `review` workflow is queued. Greptile is 5/5 on the current head, and both review threads are resolved. This PR is not yet verified by full CI. - Live fixed-source Daytona acceptance is not verified. This workspace has no Daytona API key or image configuration. The earlier deployed recovery is not evidence for this source change. ## Risks - Managed Cloud now trusts its selected image. A bad image can fail at real runtime startup instead of a saved qualification gate. - Company access, credentials, runtime integrity and handshake checks still apply. Self-hosted sandboxes, custom environments and active captured custom images keep their qualification and immutable snapshot binding. - No schema change or data migration is required. Existing qualification records can remain in place. ## Model Used - OpenAI Codex, GPT-6 family, with reasoning, tool use and code execution. The exact model ID and context window are 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>
11 KiB
Local, SSH, and sandbox environments — agent access
Product map: Local, SSH, and sandbox environments.
Feature ID: execution-environments.
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.
Scoped immutable-platform source review: 2026-10-12 at
d16eccf109b524778ceb896f79ccb3881bc61a9b, limited to saved sandbox probing,
server-owned qualification metadata and read/invalidation behavior. The original
baseline commit and review depth remain for unrelated operations; no live agent
or provider qualification is claimed by this update.
configuration
Capability ID: execution-environments/configuration.
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/environments.POST /api/companies/{companyId}/environments.
Agent access: restricted — Board read/admin management REST / CLI environment.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: API exists; an agent cannot use instance environment management as an ordinary company actor.
Scoped source review: environment routes require board organization access for reads and local-implicit board or instance administrator for management. Create/PATCH reject client-supplied platform-proof metadata; service updates discard supplied proof, preserve current server proof atomically for metadata-only edits, and invalidate it when the target configuration or driver changes. Public row responses hide the private record. This is source-only at the scoped commit. Verify forged metadata rejection, concurrent probe/update preservation, target invalidation and restricted-reader redaction; actual agent-denial proof remains not run. Company/team packages do not import or export environment rows, so those packages do not transfer platform qualification.
capabilities
Capability ID: execution-environments/capabilities.
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/environments/capabilities.
Agent access: partial — Board environment capabilities endpoint; native run gets
server-selected runtime context.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
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: Endpoint discovery and already-bound run capabilities differ; decide whether a safe agent-readable capability listing is desired.
probe
Capability ID: execution-environments/probe.
Review: baseline.
API: present — representative operation IDs:
POST /api/environments/{id}/probe.POST /api/companies/{companyId}/environments/probe-config.
Agent access: restricted — Board/admin probes / CLI environment.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Both probe endpoints require a board actor that is local-implicit or an instance administrator; ordinary agent identity and company membership alone are denied. The saved sandbox probe also resolves company/environment and secret access before allocating a fresh lease. Its measurement is company-bound to an immutable image digest or verified Daytona snapshot ID, effective provider configuration and active custom-image identity; only confirmed cleanup permits recording it. A draft probe does not record saved qualification. Reading stored qualification does not lease/provision a target and does not grant an agent permission to probe or manage that target.
Managed Cloud images do not require saved qualification for runner discovery or execution. The server checks company access before applying this policy. Execution uses the platform-selected image and keeps runtime startup checks. Self-hosted environments and active captured custom images keep qualification. This exception does not grant access to the probe endpoints. The active Cloud provisioner configuration must cover the provider; a leftover metadata marker is insufficient. Discovery does not resolve provider secrets.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: Reachability probes are not granted by an agent's right to execute assigned work.
Scoped Evidence: source-only — probe authorization,
immutable binding, measurement and read,
private metadata writes and
custom-image binding
at the scoped commit. A connection-only success or a fixture cannot certify
native compatibility, account authentication or agent access.
Scoped Verification: not-run — on one authorized owned target, compare pinned
image and provider snapshot-ID proof with mutable-image, unverified-snapshot
and changed-config/account controls; require independent
cleanup evidence before recording proof. Assert agent/non-admin board denial,
secret-context denial where the actor lacks access and forged-proof rejection.
Verify API reads hide the private record and metadata-only updates cannot overwrite it. Then use
runtime validation for account/model/native startup.
There is no new delegated agent probe binding or client proof-write API. Any human-action request/result handoff requires its own admitted path and verification; an accepted interaction does not turn the caller into a board administrator.
assignment
Capability ID: execution-environments/assignment.
Review: baseline.
API: present — representative operation IDs:
PATCH /api/agents/{id}.PATCH /api/projects/{id}.
Agent access: partial — Permitted agent/project REST / native fallback, subject to
protected configuration policy.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
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: Choosing among permitted targets differs from creating/configuring host targets; test authorized and denied selection.
Scoped plugin execution update: paperclip_runner supports a saved plugin
environment through the server-selected lease and the SDK environmentTask RPC.
This is an execution path, not a new agent-callable management endpoint. Host
company/project checks and native PRP authorization remain required; declaring a
plugin capability does not authorize the agent to change its environment.
The integration fixture
exercises the host and SDK with synthetic tasks and a mocked WebSocket.
The task API does not transfer files or reveal guest filesystem paths.
Controller replacement preserves the original task lease and run identity.
Current company, agent, workspace, and lease checks still gate state reads and
connection acquisition. Reconnection adds no agent management permission or
replacement task submission. The integration covers this with synthetic tasks;
it does not establish deployed plugin recovery.
This source update does not qualify live agent access, warm retention, or a provider.
See the execution contract.
Same-run checkpoint recovery also uses the saved lease path after a turn omits its completion result. It requires verified prior termination, retained session state, and matching company, agent, workspace, and complete Runner identity. The executor regression checks checkpoint retrieval and identity/termination denials. The lease authority fixture checks the same-run read through the database-backed task API. These are controlled regressions; live provider acceptance remains separate.
images
Capability ID: execution-environments/images.
Review: baseline.
API: present — representative operation IDs:
POST /api/environments/{environmentId}/custom-image-setup-sessions.
Agent access: restricted — Board/admin image APIs and existing terminal protocol.
Policy: Environment management is instance administrator/board; permitted assignment uses agent/project policy.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — assert the documented agent denial with an owned test fixture;
verify any listed agent request/result path separately. A delegated operation needs its
own policy and access review.
Gaps: No default agent custom-image administration/terminal path; this is a policy decision before adding a tool.
The task-only setup path uses a Core-issued expiring probe identity and a real, read-only Runner hello. The plugin checks project authentication before provider startup. Setup probe coverage uses the real Runner and a synthetic Codex provider through loopback PRP; TLS termination is replaced by the fixture. It does not qualify a live plugin provider.
The plugin prepares execution-host resources and the provider descriptor. Core validates the result, then supplies task identity and PRP launch limits.
Managed account transfer requires projectAuthCheckVersion: 1 and a successful
check_project_auth result for the exact prepared configuration, provider, and
project set. New preparation removes old validation. Core checks the saved
validation again in the dispatch update.