feat(environments): forward the warm idle window to plugin lease acquisition (#21305)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Plugin environment drivers run agent tasks on remote computers, and
warm leases keep a parked Runner between runs for an idle window that
Core records
> - Some providers stop an idle computer on their own schedule (for
example a sandbox auto-stop interval)
> - If that provider timer is longer than the Runner idle window, the
provider keeps paying for a computer whose Runner is already gone; if it
is shorter, a warm resume can find the computer stopped
> - The plugin cannot align the two because it never sees the idle
window at acquire
> - This pull request forwards the warm idle window to
`environmentAcquireLease` as `runnerLifecyclePolicy`
> - The benefit is that a provider can stop its computer just after the
Runner idle window, without Core knowing anything about the provider's
placement

## Linked Issues or Issue Description

Refs #21289
Refs #21066

**What existing behavior does this improve?**
Warm lease setup for plugin environment drivers.

**Subsystem affected**
Server environment runtime (`createPluginEnvironmentDriver`) and the
plugin SDK acquire parameters.

**Current behavior**
Core records the warm lifecycle policy (`runnerTaskLifecyclePolicy`,
including `idleTimeoutMs`) on the lease, but `environmentAcquireLease`
does not receive it, so a provider with its own idle shutdown has to
guess.

**Proposed behavior**
For a warm lease, `environmentAcquireLease` receives
`runnerLifecyclePolicy: { mode: "warm", idleTimeoutMs }`, the same value
Core records. Other lifecycle modes do not receive the field.

**Reason and benefit**
A provider can align its idle shutdown with the Runner idle window.

**Breaking changes**
None. The field is optional and additive.

## What Changed

- `PluginEnvironmentAcquireLeaseParams` has a new optional
`runnerLifecyclePolicy`.
- Core sends it only for warm leases.
- `doc/plugins/PLUGIN_RUNNER_EXECUTION.md` documents the field.
- The runner-e2e SDK public-input pin is updated for the SDK change.

An earlier revision of this PR also made Core try
`environmentResumeLease` before a session handoff. That part is removed:
placement is the plugin's decision, so Core should not decide to retry
the same computer before moving the session. The plugin will own that
inside its own resume instead.

## Verification

- `pnpm typecheck` in `server/` (builds shared and plugin-sdk) passed.
- `vitest run src/__tests__/environment-runtime.test.ts -t "portable
task placement|delegates plugin environment leases with acquisition
budget"` passed (5 cases). The portable test asserts the first warm
acquire receives `runnerLifecyclePolicy` and the lease records
`runnerTaskLifecyclePolicy`; the non-warm delegation test asserts the
field is absent. Making the forwarding unconditional fails both
delegation cases.
- The full suite was not run locally; required CI covers it.

## Risks

- A plugin that does not know the field ignores it.
- Rollback: revert this pull request. No migration.

Note: the branch name still reflects the earlier scope (resume before
handoff).

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, test runs).

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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Nicky LeachandClaude Opus 5.5 authored and GitHub committed 2026-11-12 23:45:31 -08:00
1 parent 86f9555695
commit 4f4d823cfc
5 files changed
+14 -2

No files matched your search

+5
View File
@@ -370,6 +370,11 @@ a Core-managed credential identity before lease acquisition. The saved warm
preference does not bypass account ownership checks. Drivers without warm
capability and setup probes remain ephemeral.
For a warm lease, `onEnvironmentAcquireLease` receives `runnerLifecyclePolicy`
with the idle window that Core records for the Runner. A provider with its own
idle shutdown can use it to stop only after that window. Core does not send
the field for other lifecycle modes.
Plugin task execution uses the public, run-scoped GitHub credential broker
when the provider advertises its versioned contract. Warm preparation updates
the command capability before admitting the new run. Restart recovery retains
+1
View File
@@ -693,6 +693,7 @@ export interface PluginEnvironmentAcquireLeaseParams extends PluginEnvironmentDr
* lifetime.
*/
requestedExpiresAt?: string | null;
runnerLifecyclePolicy?: { mode: "warm"; idleTimeoutMs: number };
}
export interface PluginEnvironmentResumeLeaseParams extends PluginEnvironmentDriverBaseParams {
@@ -1316,7 +1316,7 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
await db.insert(issues).values({ id: issueId, companyId: seeded.companyId, title: "Portable session", status: "in_progress" });
await db.insert(heartbeatRuns).values({ id: nextRunId, companyId: seeded.companyId, agentId: seeded.agentId, status: "running" });
let acquisitions = 0;
const call = vi.fn(async (_plugin: string, method: string) => {
const call = vi.fn(async (_plugin: string, method: string, _params?: unknown) => {
if (method === "environmentAcquireLease") return { providerLeaseId: `sandbox-${++acquisitions}`,
metadata: { ownershipGeneration: `generation-${acquisitions}` } };
if (method === "environmentResumeLease") return { providerLeaseId: "sandbox-1", metadata: {} };
@@ -1332,6 +1332,9 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
const acquisitionInput = { ...input, selectedEnvironmentId: seeded.environment.id, localEnvironmentId: randomUUID(),
admittedLifecycleMode: "warm" as const, executionWorkspaceSettings: null };
const first = await orchestrator.acquireForRun({ ...acquisitionInput, heartbeatRunId: seeded.runId });
expect(call.mock.calls.find(([, method]) => method === "environmentAcquireLease")?.[2])
.toMatchObject({ runnerLifecyclePolicy: { mode: "warm", idleTimeoutMs: 300_000 } });
expect(first.lease.metadata?.runnerTaskLifecyclePolicy).toEqual({ mode: "warm", idleTimeoutMs: 300_000 });
await db.update(environmentLeases).set({ status: "retained", metadata: {
...first.lease.metadata, runnerTaskIdentity: { sessionId },
...(mode === "legacy resume" ? {} : { runnerTaskAccountIdentity: "test-account" }),
@@ -6447,6 +6450,8 @@ describeEmbeddedPostgres("environmentRuntimeService", () => {
runId,
workspaceMode: undefined,
}, ...(defaultAcquireTimeoutMs === undefined ? [] : [330_000]));
expect(vi.mocked(workerManager.call).mock.calls.find(([, method]) => method === "environmentAcquireLease")?.[2])
.not.toHaveProperty("runnerLifecyclePolicy");
expect(acquired.lease.providerLeaseId).toBe("plugin-lease-1");
expect(acquired.lease.expiresAt?.toISOString()).toBe(expiresAt);
expect(acquired.lease.metadata).toMatchObject({
@@ -3617,6 +3617,7 @@ function createPluginEnvironmentDriver(
executionWorkspaceId: input.executionWorkspaceId ?? undefined,
adapterType: input.adapterType ?? undefined,
executionWorkspaceSettings: input.executionWorkspaceSettings,
...(lifecyclePolicy.mode === "warm" ? { runnerLifecyclePolicy: lifecyclePolicy } : {}),
// Forward a caller deadline so the provider configures a provider-side
// expiry at or before it and returns the real provider expiry.
...(requestedExpiresAtParam(input.requestedExpiresAt) !== undefined
@@ -20,7 +20,7 @@
"packages/plugins/sdk/src/index.ts": "4e573c181198ea98442321cc136341741e856ff7",
"packages/plugins/sdk/src/invocation-tracer.ts": "b28ac4aa4bc3e82658abac4a8081ed4508008696",
"packages/plugins/sdk/src/protocol.duplex-channel.test.ts": "18255eb3d63038dc459240c111cbcb29fcba25cc",
"packages/plugins/sdk/src/protocol.ts": "97ee5337227e3a1ede6801fe5b7586cc6785edad",
"packages/plugins/sdk/src/protocol.ts": "6cbc642412650a511c60b23f5625ac018d189f9d",
"packages/plugins/sdk/src/testing.ts": "fa99065efa867d8f8a9372cb4a448b8f9d687883",
"packages/plugins/sdk/src/types.ts": "80375e46504f96c7c0c1f156319dfb81275d16cc",
"packages/plugins/sdk/src/ui/clipboard.ts": "1f42069c97d731e636a6ad5481dad22d20c0ed63",