mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-23 09:07:46 +02:00
Nicky LeachandPaperclip
00331e0254
## Thinking Path > - Paperclip manages work for AI agents. > - A plugin can own an execution environment and its files. > - #17029 supplies the task driver and bounded setup verification. > - Heartbeat still prepares workspace files on Core and expects a shell transport. > - This PR gives the selected plugin ownership of workspace preparation and native task execution. > - Core keeps admission, tool authority, and recovery checks. ## Linked Issues or Issue Description **Subsystem affected** Heartbeat workspace admission and native Runner execution. **Problem or motivation** A task-only plugin cannot run through Core filesystem staging or shell execution. Native admission and recovery must use the same lease and workspace ownership. **Proposed solution** Use the task driver from #17029. Resolve workspace and project identities without Core file operations. Connect native dispatch and restart recovery to that driver. **Alternatives considered** Keep workspace admission and dispatch in one change. A workspace change alone would leave dispatch on the previous transport. An execution change alone would leave Core staging files for the wrong host. ## What Changed - Enable plugin environment selection for native workspace sessions. - Resolve workspace metadata and authorized project references without Core checkout, copy, or provision operations. - Preserve agent-default and primary workspace policies. Use the pinned workspace provider for plugin-backed project storage. Reject unsupported Core service commands and cross-owner reuse. - Connect native execution to the prepared task driver. Keep assigned MCP authority on Core. - Save exact checkpoint identity, transfer selected account refreshes, and require termination proof before replacement or cleanup. - Complete managed plugin workspaces through their storage provider. Use the same check after a restart. Keep branch validation and leave task-owned files on the plugin. - Include default instruction content in runtime synchronization when no instruction directory exists. - Defer new-agent Copilot verification until the saved-agent lifecycle can acquire the agent-owned computer. ## Verification - Rebased onto `origin/master` at `898144f4b3`. Master advanced once during verification. Both manual conflicts joined import blocks: one in `native-session-executor.ts`, and one in `heartbeat/runtime-execution.ts`. The seven patches retain their logic. The first rebased head passed repository typecheck, build, all 862 focused execution/finalizer cases, and all CI gates. The latest head `93e5a72892` passes server typecheck and all 880 focused execution, finalization, and execution-control notification tests. All 54 CI/review checks pass, with two expected skips. Greptile ran automatically and scored this head 5/5 with no unresolved findings. No new review or Apex request was made for these import-only resolutions. - The successful CI workflow initially left three stale job-check reports. Targeted policy and summary reruns cleared the reports. No source change or test fix was needed. - Repository typecheck and build pass: `pnpm -r typecheck` and `pnpm build`. - Focused native execution and restart tests pass: 795 cases. The account and harness suites pass: 159 cases. Workspace admission passes: 48 cases. The SDK task lifecycle, workspace API, runtime-hook, and instruction checks also pass. - The heartbeat integration case uses the merged workspace provider contract and reaches native dispatch with no project files on Core. The new-agent case confirms that creation leaves the agent in `preparing` until lifecycle verification. - Map validation and the Copilot source-identity check pass. No Runner implementation or source-identity bump is in this PR. - The first rebased workspace run found two stale path assertions and a recovery guard that did not recognize task-owned targets. These are fixed. The storage integration fixture also needed its persisted source binding; the production authorization check stays in place. - Two prior review findings required rejection of Core service startup and cross-owner workspace reuse. The existing admission fixtures now check both failures. The installed-account authentication finding was fixed in merged #17029. - Tests reuse the current fixtures. No new provider test matrix or live Runner process is added for these fixes. - The prior head `2db273ec12` passed CI on its first attempt and reached standard Greptile 5/5. Apex scored 4/5 and found local-folder checks during plugin completion and recovery. - The completion fix reproduces both failures. It passes all 110 cases in the runtime execution, workspace finalizer, and workspace provider integration suites. Server typecheck and map checks pass. CI passed on `62d8335b4e` on its first attempt, and standard Greptile scored 5/5. The next Apex review scored 4/5. It found that a failed plugin inspection could abort restart recovery. - The restart fix records a failed workspace receipt and uses the current run retry policy. A regression first reproduced the aborted pass. It now checks retry state, retained results, and completion of another workspace in the same pass. All 68 finalizer cases and server typecheck pass. CI passed on `7d4016323b` on its first attempt. Standard Greptile and Apex both scored 5/5. Apex left one P2 about lost failure codes. - The diagnostic fix keeps the known branch and owner mismatch codes in receipts and run recovery state. It gives repair guidance for those codes and keeps unknown plugin errors generic. All 96 affected finalizer cases and server typecheck pass. Before the rebase, required CI passed on `c2fa61c6c8` on its first attempt. Standard Greptile and Apex both scored 5/5 on that head, with no unresolved findings. The new head retains these reviewed patches. - The earlier Superagent scan on `c2fa61c6c8` was inconclusive after a pinned merge-base checkout failed or timed out. The current scan on `93e5a72892` passes. - The exact rebased head passes all 48 workspace cases and server typecheck. The first local test launch could not bind PostgreSQL inside the sandbox. The authorized local-server run passed. - The prior head reached standard Greptile 5/5. Its first CI run hit an unchanged Runner cleanup timeout and an external build-runner shutdown. Both jobs passed on the single retry. The timeout cause is not established. - A local regression check found that a retained Core workspace could also enter a plugin task without file transfer. Core now rejects this move before provider work. The existing ledger test covers both directions and confirms that the source files stay intact. - The first active standard review scored 4/5. It found that a fresh plugin retry could enter Core Git preparation. This mode now uses the existing unsupported-storage error before workspace resolution or acquisition. Both unsupported-mode cases pass, and server typecheck passes. - No live Cloud or provider validation was run. ## Risks - The prerequisite #17029 is merged. This PR targets master. - Native plugin tasks support per-turn workspace sessions. Core service commands and fresh retries that import retained files remain unsupported. A workspace storage plugin can use the modes and strategies it declares. - Core-managed credentials support Codex and direct Claude accounts. Other managed credential routes fail closed. Other harnesses can use an installed account. - A provider must preserve its prepared configuration and report process termination correctly. Uncertain termination keeps the task pending cleanup. - Cloud deployment and live provider validation remain separate. ## Model Used OpenAI Codex, GPT-6. The exact model ID and context window are not exposed in this session. Tool use includes code editing, local tests, and the GitHub CLI. ## 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 described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links - [x] My branch name describes the change and contains no internal issue details - [x] I have run focused 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>
216 lines
9.7 KiB
Markdown
216 lines
9.7 KiB
Markdown
# Local, SSH, and sandbox environments — agent access
|
|
|
|
Product map: [Local, SSH, and sandbox
|
|
environments](../feature-map/execution-environments.md).
|
|
|
|
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](../README.md)
|
|
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](../../server/src/routes/environments.ts#L353)
|
|
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](../../server/src/routes/environments.ts)
|
|
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](../../server/src/services/environments.ts) 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](../../server/src/routes/environments.ts#L353)
|
|
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.
|
|
|
|
Evidence: `source-only` — [implementation](../../server/src/routes/environments.ts#L353)
|
|
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](../../server/src/routes/environments.ts),
|
|
[immutable binding, measurement and read](../../server/src/services/environment-probe.ts),
|
|
[private metadata writes](../../server/src/services/environments.ts) and
|
|
[custom-image binding](../../server/src/services/environment-custom-image-runtime.ts)
|
|
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](./runs-adapters.md#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](../../server/src/routes/environments.ts#L353)
|
|
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](../../server/src/__tests__/plugin-runner-task.integration.test.ts)
|
|
exercises the host and SDK with synthetic tasks and a mocked WebSocket.
|
|
The task API does not transfer files or reveal guest filesystem paths.
|
|
This source update does not qualify live agent access, warm retention, or a provider.
|
|
See the [execution contract](../../doc/plugins/PLUGIN_RUNNER_EXECUTION.md).
|
|
|
|
## `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](../../server/src/routes/environments.ts#L353)
|
|
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](../../server/src/services/native-runtime/plugin-runner-probe.test.ts)
|
|
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.
|