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>
162 lines
11 KiB
Markdown
162 lines
11 KiB
Markdown
---
|
|
navigation: {"section":"Projects and execution","sectionOrder":40,"order":40}
|
|
---
|
|
|
|
# Execution environments
|
|
|
|
Operators configure where agents execute, probe readiness, select an environment for work, and inspect remote provisioning or custom-image state when the installed provider supports it.
|
|
|
|
Feature ID: `execution-environments`.
|
|
|
|
Implementation: [environment settings](../../ui/src/pages/CompanyEnvironments.tsx), [environment runtime](../../server/src/services/environment-runtime.ts).
|
|
|
|
Agent access: [companion](../agent-access-map/execution-environments.md).
|
|
|
|
## Sub-features
|
|
|
|
- `configuration`: `execution-environments/configuration` — inspect local environments and configure available SSH/sandbox targets.
|
|
- `capabilities`: `execution-environments/capabilities` — select only drivers/providers that advertise the required execution capability.
|
|
- `probe`: `execution-environments/probe` — test reachability and runtime prerequisites in the actual target.
|
|
- `assignment`: `execution-environments/assignment` — bind the intended agent/project/workspace to its execution target.
|
|
- `images`: `execution-environments/images` — inspect supported sandbox custom-image preparation and terminal workflows.
|
|
|
|
## How to get to it (user POV)
|
|
|
|
### `environment-settings`
|
|
|
|
Open Settings → Environments, then create/edit a supported target.
|
|
The canonical URL is `/company/settings/instance/environments`. Enable
|
|
`enableEnvironments` first; keep `enableManagedSandboxOnly` off to inspect local
|
|
targets. The catalog is instance-scoped and mutation requires a local operator
|
|
or instance administrator.
|
|
|
|
### `remote-execution`
|
|
|
|
Choose the environment in agent/project/workspace configuration, then inspect the resulting task/run and workspace.
|
|
|
|
## Driving it with Playwright and the Paperclip CLI
|
|
|
|
Preconditions: follow the [baseline](./README.md#before-driving-a-journey). Use an owned disposable target and a supported provider plugin. Record provider, target identity, account, and spending constraints before a live remote run.
|
|
|
|
### `environment-settings`
|
|
|
|
Automated: [environment UI](../../ui/src/pages/CompanyEnvironments.test.tsx), [driver configuration UI](../../ui/src/pages/CompanySettings.test.tsx), and [environment service](../../server/src/__tests__/environment-service.test.ts) cover configuration behavior.
|
|
|
|
Manual: Save a disposable target, reload it, and run its available probe. Verify both success and missing-credential/reachability errors identify the target. Confirm unavailable providers are not offered as working run targets.
|
|
|
|
For an immutable sandbox image, pin the OCI image with `@sha256`, or select
|
|
a Daytona snapshot whose provider ID can be verified, and explicitly probe the saved environment in the intended company. The existing connection
|
|
probe allocates a fresh lease and can measure its OS, architecture and libc.
|
|
Qualification is recorded only when the selected image/configuration matches
|
|
the live lease and cleanup is confirmed. Inspect `platformQualificationRecorded`
|
|
and its diagnostic in the probe result: connection success alone does not mean
|
|
the image has native runtime qualification.
|
|
|
|
The measured record is server-owned, company-bound and tied to the effective
|
|
configuration and active custom-image identity. Mutable tags, provider defaults
|
|
and snapshots without verified provider identities do not qualify. Daytona
|
|
qualification creates by provider ID and binds native execution to that same ID;
|
|
a deleted ID fails instead of resolving a replacement name. Changing the target,
|
|
account, image or active captured template invalidates
|
|
the record; normal metadata edits cannot forge or overwrite it, and API reads
|
|
omit the private metadata. Reading this evidence for discovery or creation does
|
|
not allocate a sandbox. The draft `probe-config` checks are not a saved-image
|
|
qualification operation. See the [runtime contract](../../packages/paperclip-runner/README.md)
|
|
and [adapter validation recipe](./runs-adapters.md#adapter-setup) for native
|
|
binary/provider readiness after platform qualification.
|
|
|
|
Verification recipe: probe a pinned owned image, record its company/config/image
|
|
identity and cleanup result, then change the image or target and verify its old
|
|
qualification is not reused. A mutable-image connection can succeed while
|
|
qualification remains absent. Assert ordinary agent and non-admin board probe
|
|
requests are denied, and environment create/PATCH payloads cannot supply
|
|
qualification metadata.
|
|
This recipe and its [probe controls](../../server/src/__tests__/environment-probe.test.ts)
|
|
are not claims that a live provider or agent-access journey ran for this map update.
|
|
|
|
The local row has no UI Test button. Its API/CLI probe reports host/cwd
|
|
availability only; it does not validate an adapter binary, workspace, or task
|
|
execution. Remote-driver probes and a real bounded run need their own evidence.
|
|
|
|
### `remote-execution`
|
|
|
|
For `paperclip_runner`, a saved plugin environment can provide per-turn Runner
|
|
execution when its manifest and worker expose the Runner task API. The task
|
|
contract starts a provider-owned Runner without shell or workspace hooks. Core
|
|
resolves the saved lease, connects through PRP, and verifies stop before lease
|
|
cleanup. The provider owns the installed agent home and retained session files;
|
|
data transfer is outside task execution. See the
|
|
[plugin contract](../../doc/plugins/PLUGIN_RUNNER_EXECUTION.md).
|
|
The [fake-provider integration](../../server/src/__tests__/plugin-runner-task.integration.test.ts)
|
|
checks acquisition, SDK dispatch, scope denial, stop proof and deletion recovery.
|
|
Its WebSocket is mocked; it does not qualify a live provider or a real Runner handshake.
|
|
|
|
Automated: [execution target](../../server/src/__tests__/environment-execution-target.test.ts) and [custom images](../../server/src/__tests__/environment-custom-images-service.test.ts) cover contracts; [SSH live test](../../server/src/__tests__/environment-live-ssh.test.ts) requires its own external setup.
|
|
|
|
The [environment runtime regression](../../server/src/__tests__/environment-runtime.test.ts)
|
|
also covers sandbox reuse after a start longer than one minute. Acquisition
|
|
uses the configured or provider-declared startup budget for resume and shares
|
|
one deadline across retries. Failure preserves the recorded sandbox. This
|
|
controlled timing check does not establish live provider acceptance.
|
|
|
|
Manual: Run a bounded command in the intended target, inspect its output and workspace, and verify execution did not silently fall back to the server host. For custom-image changes, build/probe the disposable image before assigning it. Inspect cleanup and shutdown after the run.
|
|
|
|
## Gotchas
|
|
|
|
- A probe is narrower evidence than a complete task with tools, files, and resumption.
|
|
- Platform qualification does not authenticate a model account or qualify every
|
|
harness; the selected native runtime still needs its own setup and useful-task proof.
|
|
- The local option may appear only when editing an existing local environment; availability follows current UI/provider capabilities.
|
|
- Workspace service reachability and environment reachability are separate checks.
|
|
|
|
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.
|
|
|
|
### Storybook verification
|
|
|
|
#### `configuration`
|
|
|
|
Capability ID: `execution-environments/configuration`.
|
|
|
|
Scope: ui
|
|
Storybook: Local/SSH/sandbox editors; unavailable providers, missing credentials, save pending/error and restricted operator.
|
|
Production: Persist target configuration and enforce instance-admin/local-operator mutation boundary; target catalog is instance-scoped.
|
|
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environments.ts](../../server/src/routes/environments.ts). Tests: [CompanyEnvironments.test.tsx](../../ui/src/pages/CompanyEnvironments.test.tsx), [environment-service.test.ts](../../server/src/__tests__/environment-service.test.ts)
|
|
|
|
#### `capabilities`
|
|
|
|
Capability ID: `execution-environments/capabilities`.
|
|
|
|
Scope: ui
|
|
Storybook: Supported versus unavailable driver/provider controls and interactive-setup/template-capture limitations.
|
|
Production: Verify advertised driver/plugin capabilities match operations; unavailable provider cannot become working target; capability discovery must not allocate sandbox.
|
|
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environments.ts](../../ui/src/api/environments.ts). Tests: [environment-capability-contract.test.ts](../../server/src/__tests__/environment-capability-contract.test.ts), [environment-execution-target-capabilities.test.ts](../../server/src/__tests__/environment-execution-target-capabilities.test.ts), [plugin-environment-driver-sandbox-capabilities.test.ts](../../server/src/__tests__/plugin-environment-driver-sandbox-capabilities.test.ts)
|
|
|
|
#### `probe`
|
|
|
|
Capability ID: `execution-environments/probe`.
|
|
|
|
Scope: ui
|
|
Storybook: Remote Test pending, success, reachability/auth failure and platform qualification absent/invalidated notice.
|
|
Production: Probe actual owned target; verify selected saved immutable config/image/company qualification plus lease cleanup; local API probe proves host/cwd only and has no UI Test button.
|
|
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environment-probe.ts](../../server/src/services/environment-probe.ts). Tests: [CompanyEnvironments.test.tsx](../../ui/src/pages/CompanyEnvironments.test.tsx), [environment-probe.test.ts](../../server/src/__tests__/environment-probe.test.ts), [environment-live-ssh.test.ts](../../server/src/__tests__/environment-live-ssh.test.ts)
|
|
|
|
#### `images`
|
|
|
|
Capability ID: `execution-environments/images`.
|
|
|
|
Scope: ui
|
|
Storybook: Custom-image setup/capture/progress, terminal connect/disconnect/failure, unsupported capability and active-image drift.
|
|
Production: Execute owned provider setup/capture/probe/terminal transport with correct saved image identity, authority, cleanup and shutdown; terminal screenshot cannot prove operation.
|
|
Sources: Source: [CompanyEnvironments.tsx](../../ui/src/pages/CompanyEnvironments.tsx), [environment-custom-images.ts](../../server/src/services/environment-custom-images.ts). Tests: [CompanyEnvironments.test.tsx](../../ui/src/pages/CompanyEnvironments.test.tsx), [environment-custom-images-service.test.ts](../../server/src/__tests__/environment-custom-images-service.test.ts)
|
|
|
|
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.
|