mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 20:21:50 +01:00
DottaandPaperclip
09ad9adce2
## Thinking Path > - Paperclip must keep admitted remote work alive while its main server is replaced. > - Runner owns recovery mechanics and exposes opaque checkpoints through #17097. > - The server owns company scope, encryption, Stop, tool authority and execution ownership. > - A successor must prove current ownership before it adopts the original execution. > - Checkpoint bursts must also leave capacity for normal requests and lease renewal. > - This PR persists and adopts that authority through the existing runtime boundaries. ## Linked Issues or Issue Description **What existing behavior does this improve?** Remote agents retain the original execution during a bounded main-server outage. **Current behavior** A server restart can lose the controller's local state and connection. An unsafe replacement could repeat a turn or an uncertain mutation. Checkpoint writes in the request pool can also delay ordinary requests during an aligned burst. **Proposed behavior** Restore encrypted control records from Postgres and adopt the original runner under a fenced lease. Recover known tool receipts through current tool authority. Give control checkpoints a shared pool capped at two connections per database owner. Depends on #17097. Successors are #17455 and #17456. Qualification and presentation remain separate review slices. ## What Changed - Add company/run-bound encrypted checkpoint records and migration 0394. Keep the SQL idempotent after renumbering against current master. - Recover startup and expired ownership through native runtime and heartbeat. Preserve the sandbox lease, admitted runner artifact, harness configuration, native session and active turn. - Keep Stop, finalization, preparation ownership and stale-writer fencing transactional. Preserve graceful detach and natural crash takeover. - Recover committed tool receipts through the existing authority. Reauthorize reads and hold uncertain mutations. - Bound startup retention with the existing coordinator and preserve zero idle scans. - Share at most two checkpoint connections per database client. Keep application and liveness capacity separate. Close the checkpoint pool during shutdown; late writes cannot reopen it. - Count SQL across both application and checkpoint clients. Prove request/liveness progress, command recovery and failure after pool shutdown with real Postgres. ## Verification Project creation recovery now uses the existing project activity receipt owner. It retains authenticated input normalization, fingerprint checks and current run authority after the receipt lock. An absent receipt returns no result before mutation. The new lost-HTTP-response and no-effect regression uses real API routes and Postgres. The seven transport cases pass locally. This Mac skips all 20 database cases. On current source `5de803c2cd`, Linux [job 122593415890](https://github.com/paperclipai/paperclip/actions/runs/40620576702/job/122593415890) executes all 20 project-tool cases successfully (9.480 seconds), including the committed-project lost-response regression. Its shard passes 1,627 cases with three unrelated skips. Server typecheck passes. The transport regression initially has two failures; a subsequent incorrect expectation about schema defaults was corrected before the final pass. Ordinary execution adds no checkpoint writes or recurring work. Current candidate `5de803c2cd` includes the project-creation receipt recovery fix and master `2cd747d1b6`. Migration 0394 retains the prior idempotent checkpoint DDL. Every master SQL file and journal entry is preserved. Snapshots 0390–0394, migration checks and server typecheck pass. The ordinary warm-turn regression fails on its second turn before `a219ab51ad`. After correction, three completed warm turns select the correct prior checkpoint and preserve the original session. All 288 provider-wiring cases pass. The control plane, external persistence callback, identity rotation and filesystem are real; the backend and database-load seam are scripted. The 13 warm admission/configuration variants also pass after final master integration. This does not qualify an underlying harness. At current source `5de803c2cd`, Linux [job 122593415907](https://github.com/paperclipai/paperclip/actions/runs/40620576702/job/122593415907) passes all 940 native-session-executor cases (61.431 seconds), including the warm external-checkpoint behavior; the shard passes 2,358 cases with one skip. Current [Runner job 122593415475](https://github.com/paperclipai/paperclip/actions/runs/40620576702/job/122593415475) passes the native recovery lane: 115 passes and five container-only skips, including the encrypted restore guard, fresh preparation (63.189 seconds), blocked claim lock (1.226 seconds) and recovery beyond 101 blocked owners (3.897 seconds). The first lane passes 2,215 cases with one skip. The SQL cost test reports zero idle and streaming SQL for both output volumes; this is component evidence, not a production capacity claim. At prior candidate `1ff7bb44f4`, Linux job 122549307215 passes all 938 native-executor cases, including the three-turn external-checkpoint regression. Job 122549306469 passes the native recovery lane with 115 passes and five container-only skips, including the encrypted-restore session guard, fresh preparation (63.664 seconds), claim-lock contention (3.961 seconds), and 101-owner recovery (3.824 seconds). This Mac skips the real-Postgres suite. The earlier full local executor attempt has 921 passes and 16 failures during embedded-Postgres initialization before assertions. The original fixture collisions and their corrections remain recorded. At earlier candidate `8fbe62b41d`, server shard job 122535673841 has 3,876 passes, one failure and one skip in an unchanged expiry-worker retry/drain timing test. The same server/database tree on qualification source `b64cac6951` passes all 20 expiry cases and all 3,877 shard cases. The single diagnostic retry, job 122541891915, passes all 20 expiry cases and all 3,877 shard cases (one skip). No assertion was weakened. The original failure remains recorded and its exact timing race is not proven. All Actions checks and legacy status passed on `8fbe62b41d`, with completed Greptile 5/5 and no open feedback. The next candidate `1ff7bb44f4` also passed all Actions checks and Greptile 5/5. Its Paperclip Review remained queued before the new master conflict required integration. The new candidate needs fresh exact-head CI and reviews; old checks do not qualify it. Migration generation is checkpoint-only, all master SQL and journal entries remain unchanged, and migration checks, server typecheck and all 13 warm-owner variants pass after integration. The first migration check was blocked by TSX sandbox IPC; its permitted repeat passes. The first warm-test command used an incorrect path and ran no tests; the corrected command supplies the 13-case receipt. All 16 database pool-lifetime/options/teardown cases pass after granting loopback permission; the first batch had two EPERM failures and 14 passes. Earlier semantic-tool/HTTP recovery, adoption, encryption-batch, zero-streaming-write and idle-SQL receipts remain source-attributed in the [qualification record](https://github.com/paperclipai/paperclip/blob/2ff66f57da0da35bac1c19a2366ea4b84d87a986/doc/plans/2026-10-22-hot-upgrade-qualification.md). That record retains earlier assertion, setup and cleanup failures and their corrections. No failed gate is waived. The historical 300-session component campaign passes four after phases: steady read p99 is 107–108 ms at 500 reads/s and 100 writes/s; aligned-burst read p99 is 103–105 ms after the bounded pool, versus 584–689 ms before. This comparison isolates the persistence corrections. It does not measure the final stack's hosted active-agent capacity. The hosted zero-agent API pair leaves SQL and CPU essentially unchanged, but both arms fail absolute latency gates and candidate peak cgroup memory fails its gate. The active-agent/viewer matrix, different-artifact upgrade and rollback remain open. Run `PAPERCLIP_TEST_DATABASE_URL=<owned-disposable-postgres> pnpm --filter @paperclipai/server exec vitest run src/services/native-runtime/native-runner-restart-recovery.integration.test.ts`. Previous head `f2db8a6568` had one failed workspace setup gate: [job 122555672441](https://github.com/paperclipai/paperclip/actions/runs/40608984238/job/122555672441) passes all 4,169 UI tests and 285 CLI cases (one skip), but the company import/export suite reaches its 30-second health deadline during doctor startup. Its output does not reach the server-start step. The CLI, server, database, shared, adapter and plugin trees are identical on qualification source `a866619d7b`, whose [job 122555886663](https://github.com/paperclipai/paperclip/actions/runs/40609057937/job/122555886663) passes that fixture and all 286 CLI cases. The one diagnostic retry, [job 122561057225](https://github.com/paperclipai/paperclip/actions/runs/40608984238/job/122561057225), passes the formerly failing fixture and all 286 CLI cases. All Actions checks and legacy status on `f2db8a6568` pass. Its exact-head Greptile completed at 5/5 with no open feedback. The current integrated head requires fresh checks and a completed Paperclip Review before merge. The original failure remains recorded; its exact timing cause is unproven. A repeated failure requires investigation and repair rather than another retry. All current-head CI, legacy status, exact-head completed Greptile 5/5, resolved feedback and ordinary GitHub merge eligibility remain required before merge. The latest integration preserves master’s published Copilot v70 profiles and every published migration. Checkpoint migration `0394_conscious_whizzer.sql` was generated with `pnpm db:generate` and retains the prior idempotent DDL. The Runner vendor rebuild and replay parity checks pass. Server typecheck and all 13 warm-owner variants pass after that rebuild. The imported report-lock patch is byte-identical to master; its intentional patch-context whitespace is retained, and the feature delta passes whitespace checks. No hosted experiment was run. ## Risks The pool adds up to two active connections per instance, shared across agents. Checkpoint delivery can wait behind that bound; it still requires its commit. Steady component-test Postgres CPU rises by about 1.7 percentage points of a two-CPU allocation. These corrections do not remove the stack's control and renewal writes. The migration and key must survive replacement. Fresh-database tests and local load do not establish different-artifact hosted upgrade or rollback continuity. ## Model Used OpenAI GPT-6 through Codex, with reasoning, repository tools and code execution. The runtime does not expose a more specific model ID or context-window size. ## 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 - [ ] 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 - [ ] 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>
230 lines
11 KiB
Markdown
230 lines
11 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.
|
|
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](../../doc/plugins/PLUGIN_RUNNER_EXECUTION.md).
|
|
|
|
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](../../server/src/services/native-runtime/native-session-executor.test.ts)
|
|
checks checkpoint retrieval and identity/termination denials. The
|
|
[lease authority fixture](../../server/src/__tests__/environment-task-authority.integration.test.ts)
|
|
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](../../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.
|