feat(plugins): send configured environment on plugin task resume (#21352)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - #21335 lets a plugin task provider that restarts the Runner on
`resume` opt in (`resumeCredentialVersion: 1`) to receive the claimant
run's harness credential
> - A provider restarting the Runner also needs the agent's configured
environment, which Core sends on `resume` only during a session handoff
> - Without it, a Runner a provider moves to a new computer starts
without the agent's configured environment variables
> - This pull request widens that opt-in to both launch inputs, under a
name that says so, before any provider adopts the old name
> - The benefit is that a provider can restart a parked Runner on resume
with the same credential and environment a `submit` would carry

## Linked Issues or Issue Description

Refs #21289
Follows: #21335

**What existing behavior does this improve?**
The opt-in resume launch inputs added in #21335.

**Subsystem affected**
Plugin SDK environment task schema (`describe` capability), the plugin
Runner task owner's `resume`, and the plugin environment task docs.

**Current behavior**
With `resumeCredentialVersion: 1`, `resume` carries `credential`.
`configuredEnvironment` is sent on `resume` only for a session handoff.

**Proposed behavior**
The capability is renamed `resumeLaunchInputsVersion: 1`. With it,
`resume` carries `credential` as before and also `configuredEnvironment`
(same builder as `submit`) when the provider advertises
`configuredEnvironmentVersion: 1`. Session handoff is unchanged.

**Reason and benefit**
A provider that restarts the Runner on resume gets both launch inputs it
needs.

**Breaking changes**
The capability name changes from `resumeCredentialVersion` to
`resumeLaunchInputsVersion`. No provider advertises the old name yet (it
merged in #21335 and has no adopter), so nothing changes behavior.

## What Changed

- Rename `resumeCredentialVersion` → `resumeLaunchInputsVersion` in the
SDK `describe` result schema, executor plumbing, owner input, docs and
tests.
- With the capability, `resume` also adds `configuredEnvironment` when
the provider advertises `configuredEnvironmentVersion: 1`. A normal
resume does not mark the variables as delivered, since a live Runner
keeps the environment it started with.
- Docs: the "Release and resume" section describes both fields; the
"Configured environment" section points to it.
- The runner-e2e SDK public-input pin is updated.

## Verification

- SDK vitest `tests/environment-task-release-resume.test.ts` and
`tests/environment-tasks.test.ts`: 68 passed.
- Server vitest `plugin-runner-task.test.ts` and
`environment-task-runtime.test.ts`: 153 passed, including a normal
resume with the capability (credential sent, variables added only with
`configuredEnvironmentVersion: 1`, delivered flag unset) and redaction
of both fields from metadata writes and sanitized errors.
- `native-session-executor.test.ts -t "uses a task-only"`: 5 passed.
- runner-e2e `source-sdk-evidence.test.ts` and
`source-sdk-public-type.test.ts`: 46 passed.
- `pnpm typecheck` in `server/` (builds shared and plugin-sdk) passed.
- Not run locally: the full suite and `pnpm verify`; required CI covers
them.

## Risks

- A provider restarting the Runner gets the claimant run's current
variables, which can differ from the ones the parked Runner started
with. That is intended.
- Rollback: revert this pull request. No migration.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, test runs), implemented by a sub-agent and reviewed
before opening.

## 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-13 13:46:37 -08:00
1 parent 3b03ac10e5
commit 5df1ada9c1
9 files changed
+57 -29

No files matched your search

+20 -11
View File
@@ -90,6 +90,8 @@ run log line that names the variables it did not set.
task. It does not resume the retained Runner.
- A session handoff starts a new Runner, so its `resume` has
`configuredEnvironment`.
- A provider that also returns `resumeLaunchInputsVersion: 1` gets
`configuredEnvironment` on every `resume`. See "Release and resume".
A driver can declare `protectedEnvironmentKeys` in the manifest. These are the
variables that the driver always sets on its tasks. Core rejects a protected
@@ -117,19 +119,26 @@ workspace and current authority before installing the ticket or reserving reuse.
The ticket is bounded transient authentication input, as on submission. Never
copy its bytes into status, metadata, logs, results or durable replay records.
A provider can return `resumeCredentialVersion: 1` from `describe`. Core then
adds `credential` to `resume` when it would add `credential` to `submit` for the
claimant run. The field has the same shape and validation as on `submit`. Core
resolves it for the claimant run's selected account, so the value can be newer
than the credential that started the Runner. When Core has no credential for the
task, `resume` has no `credential`. An older provider gets no new field.
A provider can return `resumeLaunchInputsVersion: 1` from `describe`. Core then
adds the launch inputs of `submit` to every `resume`, with the same values and
rules as on `submit` for the claimant run:
- `credential`, when Core would add `credential` to `submit`. Core resolves it
for the claimant run's selected account, so the value can be newer than the
credential that started the Runner. When Core has no credential for the task,
`resume` has no `credential`.
- `configuredEnvironment`, when the provider also returns
`configuredEnvironmentVersion: 1`.
An older provider gets no new fields. A session handoff keeps its existing
fields.
- A provider that must start the Runner again to resume the session, for example
after it moved the session to a new sandbox or after a reboot, can use this
credential to start the Runner.
- A provider with a live Runner ignores the field. The running Runner keeps its
own credential.
- The credential is transient secret input, as on `submit`. Do not save it in
after it moved the session to a new sandbox or after a reboot, starts the
Runner with these inputs, as on `submit`.
- A provider with a live Runner ignores the fields. The running Runner keeps the
credential and environment that it started with.
- The values are transient secret input, as on `submit`. Do not save them in
task state, lease metadata, journals, logs, results or durable replay records.
The `resume` result has a closed `outcome`:
@@ -204,7 +204,7 @@ export const environmentTaskResultSchema = z.discriminatedUnion("kind", [
workspaceFileReadVersion: z.literal(1).optional(),
githubCredentialBrokerVersion: z.literal(1).optional(),
configuredEnvironmentVersion: z.literal(1).optional(),
resumeCredentialVersion: z.literal(1).optional(),
resumeLaunchInputsVersion: z.literal(1).optional(),
}).strict(),
z.object({
kind: z.literal("status"), taskId: providerId,
@@ -59,8 +59,8 @@ describe("release and resume task contract", () => {
expect(environmentTaskResultSchema.parse({ ...description, ...capabilities })).toEqual({ ...description, ...capabilities });
}
expect(environmentTaskResultSchema.safeParse({ ...description, releaseResumeVersion: 2 }).success).toBe(false);
expect(environmentTaskResultSchema.parse({ ...description, resumeCredentialVersion: 1 })).toEqual({ ...description, resumeCredentialVersion: 1 });
expect(environmentTaskResultSchema.safeParse({ ...description, resumeCredentialVersion: 2 }).success).toBe(false);
expect(environmentTaskResultSchema.parse({ ...description, resumeLaunchInputsVersion: 1 })).toEqual({ ...description, resumeLaunchInputsVersion: 1 });
expect(environmentTaskResultSchema.safeParse({ ...description, resumeLaunchInputsVersion: 2 }).success).toBe(false);
});
it.each(credentials)("validates %s on resume as on submit", (_label, credential, valid) => {
@@ -583,23 +583,27 @@ describe("plugin-provided Runner execution", () => {
await expect(executeEnvironmentTask(database().db, workers as never, { companyId: "company", leaseId, operation: submit })).rejects.toThrow("provider unavailable");
expect(workers.call).not.toHaveBeenCalled();
});
it("forwards a resume credential without persisting it or exposing it in worker errors", async () => {
it("forwards resume launch inputs without persisting them or exposing them in worker errors", async () => {
const identity = { runnerInstanceId: "runner", environmentLeaseId: leaseId, runId: "run", normalizedSessionId: "session", turnId: "turn", itemId: "item" };
const operation = { kind: "resume" as const, identity, bootstrapTicket: "transient-test-ticket",
credential: { type: "claude-env" as const, environment: { CLAUDE_CODE_OAUTH_TOKEN: "never-leak-token" } } };
credential: { type: "claude-env" as const, environment: { CLAUDE_CODE_OAUTH_TOKEN: "never-leak-token" } },
configuredEnvironment: { STRIPE_SECRET_KEY: "never-leak-variable" } };
const result = { kind: "resume", taskId: "attempt-1", outcome: "resumed" };
const retained = () => { const value = row(); value.lease.status = "retained"; value.run!.status = "succeeded"; return value; };
const store = database(retained());
const workers = worker(result);
await expect(executeEnvironmentTask(store.db, workers as never, { companyId: "company", leaseId, operation })).resolves.toEqual(result);
expect(workers.call).toHaveBeenCalledWith("original", "environmentTask", expect.objectContaining({ operation }), 15_000);
expect(JSON.stringify(store.sets.map(set => new PgDialect().sqlToQuery(set.metadata as never).params))).not.toContain("never-leak-token");
const persisted = JSON.stringify(store.sets.map(set => new PgDialect().sqlToQuery(set.metadata as never).params));
expect(persisted).not.toContain("never-leak-token");
expect(persisted).not.toContain("never-leak-variable");
const failing = worker();
failing.call.mockRejectedValue(Object.assign(new Error("resume failed for never-leak-token"), { data: operation }));
failing.call.mockRejectedValue(Object.assign(new Error("resume failed for never-leak-token and never-leak-variable"), { data: operation }));
const error = await executeEnvironmentTask(database(retained()).db, failing as never, { companyId: "company", leaseId, operation }).catch(caught => caught);
expect(error.message).toBe("Plugin-provided Runner execution operation unavailable; reconcile the same task before retrying");
expect(JSON.stringify({ ...error, message: error.message })).not.toContain("never-leak-token");
expect(JSON.stringify({ ...error, message: error.message })).not.toContain("never-leak-variable");
expect(error.cause).toBeUndefined();
});
it("rejects wrong task receipts and sanitizes worker errors", async () => {
@@ -18616,7 +18616,7 @@ describe("runnerd provider runtime wiring", () => {
const release = vi.fn(async () => {}), resume = vi.fn(async () => "resumed" as const);
const owner = vi.spyOn(pluginTaskRuntime, "createPluginRunnerTaskOwner").mockReturnValue({ launcher, registration, driver, readWorkspaceFile, release, resume, isRetired: () => false, retireSupersededTask: async () => false, retiredBeforeClaim: () => false, configuredEnvironmentDelivered: () => false, credentialsUpdated: vi.fn(), rebind:vi.fn() });
const description = { kind: "description" as const, launchPreparationVersion: 1 as const, projectAuthCheckVersion: 1 as const,
releaseResumeVersion: 1 as const, resumeCredentialVersion: 1 as const, ...(kind === "codex" ? { workspaceFileReadVersion: 1 as const } : {}),
releaseResumeVersion: 1 as const, resumeLaunchInputsVersion: 1 as const, ...(kind === "codex" ? { workspaceFileReadVersion: 1 as const } : {}),
taskId: "task", runner: { version: "fixture", digest: `sha256:${"a".repeat(64)}` } };
const task = vi.fn(async (operation: unknown) => {
environmentTaskOperationSchema.parse(operation);
@@ -18639,7 +18639,7 @@ describe("runnerd provider runtime wiring", () => {
expect(state.toolAuthorityDefinitions).toHaveBeenCalledWith(expect.objectContaining({ assignedMcpTools }));
expect(state.createAssignedMcpTools).toHaveBeenCalledWith(expect.objectContaining({ gatewayPublicId: "assigned-test", bearerToken: "fixture-mcp-secret" }));
expect(owner).toHaveBeenCalledWith(expect.objectContaining({ task, projectIds: target.runnerTaskProjectIds,
credentialIdentity: undefined, releaseResumeVersion: 1, resumeCredentialVersion: 1 }));
credentialIdentity: undefined, releaseResumeVersion: 1, resumeLaunchInputsVersion: 1 }));
expect(state.createBackend.mock.calls.at(-1)![1]).toMatchObject({ workingDirectoryAuthority: "runner_prepared_launch", environment: {} });
state.createBackend.mock.calls.at(-1)![1].codexTransportFactory!();
const options = state.createTransport.mock.calls.at(-1)![0];
@@ -16472,7 +16472,7 @@ async function createRunnerdBackendWithinSessionClaim(
configuredEnvironmentVersion: description.configuredEnvironmentVersion,
configuredEnvironment: taskConfiguredEnvironment,
releaseResumeVersion: description.releaseResumeVersion,
resumeCredentialVersion: description.resumeCredentialVersion,
resumeLaunchInputsVersion: description.resumeLaunchInputsVersion,
authorityRunId: description.releaseResumeVersion === 1 ? input.execution.binding.runId : undefined,
releasedSource: input.remoteWarmRecovery?.releasedSource,
sessionHandoff: !!input.remoteWarmRecovery?.portableSourceTaskId,
@@ -588,9 +588,9 @@ describe("plugin Runner release/resume facade", () => {
["sends the claimant's Claude credential to a supporting provider", { type: "claude-env" as const, environment: { CLAUDE_CODE_OAUTH_TOKEN: "fixture-current-token" } }, 1 as const, true],
["omits the credential when submit would omit it", undefined, 1 as const, false],
["omits the credential for a provider without support", { type: "claude-env" as const, environment: { ANTHROPIC_API_KEY: "fixture-current-key" } }, undefined, false],
])("%s on resume", async (_label, credential, resumeCredentialVersion, sent) => {
])("%s on resume", async (_label, credential, resumeLaunchInputsVersion, sent) => {
const task = lifecycleTask();
const owner = createPluginRunnerTaskOwner({ ...input("claude"), task, resumeCredentialVersion, ...(credential ? { credential } : {}) });
const owner = createPluginRunnerTaskOwner({ ...input("claude"), task, resumeLaunchInputsVersion, ...(credential ? { credential } : {}) });
await expect(owner.resume(requirements.identity, "transient-ticket")).resolves.toBe("resumed");
expect(task).toHaveBeenCalledExactlyOnceWith({
kind: "resume", identity: requirements.identity, bootstrapTicket: "transient-ticket",
@@ -600,10 +600,10 @@ describe("plugin Runner release/resume facade", () => {
it("resumes with the credential resolved for the rebound claimant run", async () => {
const task = lifecycleTask();
const owner = createPluginRunnerTaskOwner({ ...input("claude"), task, resumeCredentialVersion: 1,
const owner = createPluginRunnerTaskOwner({ ...input("claude"), task, resumeLaunchInputsVersion: 1,
credential: { type: "claude-env", environment: { CLAUDE_CODE_OAUTH_TOKEN: "fixture-source-token" } } });
const claimant = { type: "claude-env" as const, environment: { CLAUDE_CODE_OAUTH_TOKEN: "fixture-claimant-token" } };
owner.rebind({ ...input("claude"), task, resumeCredentialVersion: 1, authorityRunId: "claimant-run", credential: claimant });
owner.rebind({ ...input("claude"), task, resumeLaunchInputsVersion: 1, authorityRunId: "claimant-run", credential: claimant });
await expect(owner.resume(requirements.identity, "transient-ticket")).resolves.toBe("resumed");
expect(task).toHaveBeenCalledExactlyOnceWith({
kind: "resume", identity: requirements.identity, bootstrapTicket: "transient-ticket", credential: claimant,
@@ -974,4 +974,18 @@ describe("plugin task configured environment", () => {
}, { expectedTaskId: "task" });
expect(owner.configuredEnvironmentDelivered()).toBe(sessionHandoff ? true : undefined);
});
it.each([1, undefined] as const)("sends the launch inputs on every resume to a provider that supports them (%s)", async configuredEnvironmentVersion => {
const task = vi.fn(async (_operation: any): Promise<unknown> => ({ kind: "resume", taskId: "task", outcome: "resumed" }));
const credential = { type: "claude-env" as const, environment: { CLAUDE_CODE_OAUTH_TOKEN: "fixture-claimant-token" } };
const owner = createPluginRunnerTaskOwner({ taskId: "task", projectIds: ["project"], harness: "claude", task,
warmTaskVersion: 1, releaseResumeVersion: 1, resumeLaunchInputsVersion: 1, accountIdentity: "selected-account", adoptIdentity: requirements.identity,
authorityRunId: "run", credential, configuredEnvironmentVersion, configuredEnvironment });
await expect(owner.resume(requirements.identity, "transient-ticket")).resolves.toBe("resumed");
expect(task).toHaveBeenCalledExactlyOnceWith({
kind: "resume", identity: requirements.identity, bootstrapTicket: "transient-ticket", credential,
...(configuredEnvironmentVersion === 1 ? { configuredEnvironment } : {}),
}, { expectedTaskId: "task" });
expect(owner.configuredEnvironmentDelivered()).toBeUndefined();
});
});
@@ -49,7 +49,7 @@ export function createPluginRunnerTaskOwner(input: {
pollMs?: number;
warmTaskVersion?: 1;
releaseResumeVersion?: 1;
resumeCredentialVersion?: 1;
resumeLaunchInputsVersion?: 1;
releasedSource?: DurableRecoveryIdentity;
sessionHandoff?: boolean;
onResumed?: (identity: DurableRecoveryIdentity) => Promise<void>;
@@ -432,10 +432,11 @@ export function createPluginRunnerTaskOwner(input: {
const handoffCredential = input.sessionHandoff && input.credential?.type === "claude-env"
? { accountIdentity: input.accountIdentity, environment: input.credential.environment }
: undefined;
const launchInputs = input.resumeLaunchInputsVersion === 1;
const result = await call(environmentTaskOperationSchema.parse({ kind: "resume", identity, bootstrapTicket,
...(handoffCredential ? { handoffCredential } : {}),
...(input.resumeCredentialVersion === 1 && input.credential ? { credential: input.credential } : {}),
...configuredEnvironmentFields(!!input.sessionHandoff),
...(launchInputs && input.credential ? { credential: input.credential } : {}),
...configuredEnvironmentFields(!!input.sessionHandoff || launchInputs),
}));
requireReleaseResume();
if (result.kind !== "resume") throw new Error("Plugin Runner resume result unavailable");
@@ -13,7 +13,7 @@
"packages/plugins/sdk/src/environment-stop-error.ts": "b0e03f8aa2b2170ba095da5c7138050fced3f3cb",
"packages/plugins/sdk/src/environment-sync-error.ts": "7d6a51a95da49a7da4525aebbab6382dc5c44ae8",
"packages/plugins/sdk/src/environment-task-error.ts": "98aae8a06743b38884b68cb9a3ec44c57b34c0e4",
"packages/plugins/sdk/src/environment-tasks.ts": "1534cca17be5b8c924b2b6be44339dc6faf493c1",
"packages/plugins/sdk/src/environment-tasks.ts": "0e99adb15123cee99c979642a5d93efa48c46d09",
"packages/plugins/sdk/src/host-client-factory.ts": "e0301c390ea13f2340b669383f07af2455e48c8a",
"packages/plugins/sdk/src/idle-drain.test.ts": "cc59f7881e7d46c89395a1d93d74f6c6b9b0a64a",
"packages/plugins/sdk/src/idle-drain.ts": "ae6e4c6be4657a3d541396922b3bc551b8db557f",