0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-23 17:33:51 +02:00

Files

T

Nicky LeachandPaperclip 00331e0254 Connect native Runner admission to plugin-owned workspaces (#16978 )

## 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>

2026-10-21 08:22:48 -07:00

6.9 KiB

Raw Blame History

Plugin Runner execution

Core can run paperclip_runner tasks in a plugin environment. The plugin owns the execution host and its files. Core owns run identity, selected policy, assigned tools, and the PRP journal.

Required hooks

Set supportsTasks: true on the environment driver. Declare the environment.drivers.register capability. Implement these hooks:

onEnvironmentAcquireLease
onEnvironmentTask
onEnvironmentReleaseLease
onEnvironmentDestroyLease

Task execution does not require onEnvironmentExecute or onEnvironmentRealizeWorkspace. The task API has no shell or file transfer operation. Use a separate workflow to install and save agent files.

Core supports per-turn workspace sessions with Codex, OpenCode, and ACPX. OpenCode and ACPX require the existing qualified provider profiles. Workspace-free providers and warm process retention are not supported here. The plugin owns project workspace preparation. Core does not prepare or reuse a Core Git worktree for a task-only environment. For plugin-backed project storage, Core uses the workspace provider contract. The storage plugin must also provide the selected execution environment. Its declared workspace modes and strategies remain in effect. Core passes the pinned workspace binding with each task operation. Core rejects configured workspace services for task-only environments. Fresh retries that import retained files are not supported for plugin storage. An agent-owned workspace cannot move to another agent or environment. Core also rejects reuse of a local workspace in a task-only environment. Keep its original owner, or use the workspace storage provider contract.

Prepare and launch

Return an opaque task ID from lease acquisition as providerLeaseId.
Return the installed Runner version and SHA-256 digest from describe.
Return launchPreparationVersion: 1 from describe.
Handle prepare with the launch preparation contract.
Save the result under its configuration ID.
Handle submit with that ID in preparedLaunchId.
Return an authenticated WSS endpoint from connection.

Preparation must not start a process. It must preserve Core's provider, model, policy, instructions, and resource assignment identities. Resolve assigned resources to execution-host paths. Use bindRunnerLaunchResources and createRunnerProviderLaunch when the built-in descriptor builder is suitable.

Core checks the returned requirements digest and descriptor before it registers PRP or submits the task. A failed check does not enable a fallback launch. Recovery within the same run must return the exact saved configuration.

The plugin supplies executable paths and the provider workspace in the descriptor. It owns the process environment and account installation. For example, a persistent computer can use these locations:

HOME=/home/agent
AGENT_HOME=/home/agent/.agents
CODEX_HOME=/home/agent/.codex
instructions=/home/agent/.agents/AGENTS.md
skills=/home/agent/.agents/skills/<name>/SKILL.md

These are execution-host locations. Core does not copy the home for each run. The plugin must declare projectAuthCheckVersion: 1 for all native tasks. Core requires check_project_auth to allow the exact prepared configuration before it sends credentials. The plugin must reject conflicting project or parent authentication settings. It must keep the checked configuration fixed until submission. See managed account validation.

Core sends authorized project IDs, the PRP identity, launch limits, and the bootstrap ticket through submit. It does not send a process command. The plugin must submit each task at most once. A lost reply requires status reconciliation for the same task.

Credentials and tools

Core can transfer a selected Codex account or a direct Claude credential. Other managed routes fail closed until they have a typed credential contract. Do not put credentials in task metadata, journals, logs, or errors.

Assigned MCP tools run through the Core gateway over PRP. The gateway credentials stay on Core. The plugin must preserve the MCP binding identity in the prepared context.

Core records credential writeback authority before dispatch. After process termination, Core saves refreshed credentials before it completes the task. A failed save retains the task grants for cleanup.

Stop and recovery

A terminal phase does not prove process termination. Return executionStopped: true only after the task and its descendants stop. Return sessionStateAvailable: true only when the suspended state remains usable. Keep retained state when Core completes the task. Core checks managed plugin workspaces through their storage provider before completion, including after a restart. Core does not inspect these folders locally. If this check fails, Core defers the run and continues recovery for other runs. Core keeps known branch and owner error codes with the repair instructions.

The task contract exposes two checkpoint operations:

read_state returns the exact Runner durable state for the supplied identity.
archive_state moves a suspended Runner authority checkpoint under the supplied archive key. It returns the same state on retry. It keeps provider session files.

These operations do not accept paths. Core checks the active lease and retained source task before it calls the plugin. The existing Runner transport validates state identity and suspension before it rotates authority.

Core checks company, agent, environment, workspace, driver, and termination receipts before it supplies resumeFrom. For same-run controller recovery, Core first stops and releases the old task. A failed stop prevents replacement. A new run prepares its current assignments. Provider compatibility checks remain in the existing backends. Missing or incompatible retained state fails closed.

Setup verification

Core creates a private probe lease with an expiry. It runs the same describe, prepare, submit, and WSS/PRP path. The probe checks provider authentication and the selected model with tools denied. Core bounds Runner lifetime to the remaining probe time. It then requires suspension, confirmed termination, and task cleanup. For a new agent-owned computer, the saved-agent lifecycle runs verification after it saves the agent. Core does not require a computer before this save.

Verification

The Runner fixture uses a synthetic Codex provider and local sockets. It does not qualify a deployed plugin, live account, or production WSS proxy.

6.9 KiB Raw Blame History