feat(plugins): send the claimant's credential on plugin task resume (#21335)

## 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
a warm follow-up run resumes a parked Runner through the `resume` task
operation
> - `resume` carries only the durable identity and a bootstrap ticket,
which is enough while the parked Runner process is still alive
> - A provider sometimes has to start the Runner again to resume the
session: after it moved the parked session to a new sandbox, or after
the computer rebooted
> - A Claude Runner cannot start without its credential, and today only
the portable handoff path (`handoffCredential`) delivers one
> - This pull request lets a provider opt in to receiving the claimant
run's harness credential on `resume`
> - The benefit is that a provider can continue a parked session on a
new computer without Core orchestrating a handoff

## Linked Issues or Issue Description

Refs #21289
Related: #21305

**What existing behavior does this improve?**
Warm resume for plugin task providers that restart the Runner to resume
a session.

**Subsystem affected**
Plugin SDK environment task schema, the server's plugin Runner task
owner, and the plugin environment task docs.

**Current behavior**
`submit` can carry the harness credential (`credential`), but `resume`
cannot. A provider that must start the Runner again on resume has no
credential for a Claude task.

**Proposed behavior**
A provider that returns `resumeCredentialVersion: 1` from `describe`
receives `credential` on `resume` whenever Core would send it on
`submit`, resolved for the claimant run. Other providers see no change.

**Reason and benefit**
Providers can restart a Claude Runner on resume without the Core-run
handoff protocol.

**Breaking changes**
None. The field is opt-in: the SDK worker parses operations strictly, so
Core sends it only to providers that advertise the capability.

## What Changed

- `resume` gains an optional `credential`, with the same schema and
validation as `submit`'s.
- `describe` gains an optional `resumeCredentialVersion: 1` capability.
- The plugin Runner task owner adds the credential on `resume` when the
provider advertised the capability and Core resolved a credential, using
the same resolution as `submit` (`preparePluginRunnerCredentials`).
After a warm rebind, the claimant run's credential is sent.
- `doc/plugins/PLUGIN_ENVIRONMENT_TASKS.md` documents the field and its
handling rules.
- The runner-e2e SDK public-input pin is updated.

`handoffCredential` on the session handoff path is unchanged.

## Verification

- SDK vitest `tests/environment-task-release-resume.test.ts` and
`tests/environment-tasks.test.ts` (68 passed): `resume` accepts and
rejects the same 11 credential cases as `submit`; the capability is
optional and rejects other versions; a resume credential reaches the
plugin through the serialized worker RPC.
- Server vitest `plugin-runner-task.test.ts` and
`environment-task-runtime.test.ts` (151 passed): credential sent with
the capability and a resolved credential; omitted without a credential
or without the capability; the rebound claimant's credential is sent;
the credential appears in no metadata write and not in the sanitized
error, even when the worker error echoes it.
- `native-session-executor.test.ts -t "uses a task-only"` (5 passed):
the executor forwards the capability to the owner.
- runner-e2e `source-sdk-evidence.test.ts` and
`source-sdk-public-type.test.ts` (46 passed).
- `tsc --noEmit` for `packages/plugins/sdk` and `server`.
- Not run locally: the full suite and `pnpm verify`; required CI covers
them.

## Risks

- No server-side provider check on resume, unlike `submit`: the lease
has no reliable harness at resume time. Protection relies on the owner,
whose rebind refuses a changed harness, account or credential identity.
- The credential is the claimant run's current one, which can be newer
than the one that started the parked Runner. That is intended.
- A provider must advertise the capability only after its SDK pin
includes this schema; roll Core out first.
- 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 08:40:46 +00:00
1 parent e063587edd
commit 41998d551c
9 files changed
+99 -3

No files matched your search

@@ -583,6 +583,25 @@ 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 () => {
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" } } };
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 failing = worker();
failing.call.mockRejectedValue(Object.assign(new Error("resume failed for never-leak-token"), { 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(error.cause).toBeUndefined();
});
it("rejects wrong task receipts and sanitizes worker errors", async () => {
await expect(executeEnvironmentTask(database().db, worker({ kind: "accepted", taskId: "other" }) as never, { companyId: "company", leaseId, operation: submit })).rejects.toThrow("reconcile the same task");
const workers = worker(); workers.call.mockRejectedValue(new Error("private-credential"));
@@ -18413,7 +18413,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, ...(kind === "codex" ? { workspaceFileReadVersion: 1 as const } : {}),
releaseResumeVersion: 1 as const, resumeCredentialVersion: 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);
@@ -18436,7 +18436,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 }));
credentialIdentity: undefined, releaseResumeVersion: 1, resumeCredentialVersion: 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];
@@ -16415,6 +16415,7 @@ async function createRunnerdBackendWithinSessionClaim(
configuredEnvironmentVersion: description.configuredEnvironmentVersion,
configuredEnvironment: taskConfiguredEnvironment,
releaseResumeVersion: description.releaseResumeVersion,
resumeCredentialVersion: description.resumeCredentialVersion,
authorityRunId: description.releaseResumeVersion === 1 ? input.execution.binding.runId : undefined,
releasedSource: input.remoteWarmRecovery?.releasedSource,
sessionHandoff: !!input.remoteWarmRecovery?.portableSourceTaskId,
@@ -584,6 +584,32 @@ describe("plugin Runner release/resume facade", () => {
}, { expectedTaskId: "task" });
});
it.each([
["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) => {
const task = lifecycleTask();
const owner = createPluginRunnerTaskOwner({ ...input("claude"), task, resumeCredentialVersion, ...(credential ? { credential } : {}) });
await expect(owner.resume(requirements.identity, "transient-ticket")).resolves.toBe("resumed");
expect(task).toHaveBeenCalledExactlyOnceWith({
kind: "resume", identity: requirements.identity, bootstrapTicket: "transient-ticket",
...(sent ? { credential } : {}),
}, { expectedTaskId: "task" });
});
it("resumes with the credential resolved for the rebound claimant run", async () => {
const task = lifecycleTask();
const owner = createPluginRunnerTaskOwner({ ...input("claude"), task, resumeCredentialVersion: 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 });
await expect(owner.resume(requirements.identity, "transient-ticket")).resolves.toBe("resumed");
expect(task).toHaveBeenCalledExactlyOnceWith({
kind: "resume", identity: requirements.identity, bootstrapTicket: "transient-ticket", credential: claimant,
}, { expectedTaskId: "task" });
});
it.each(["codex", "claude"])("quiesces %s before release and closes only after its ACK", async harness => {
const { task } = provider();
const perform = task.getMockImplementation()!;
@@ -49,6 +49,7 @@ export function createPluginRunnerTaskOwner(input: {
pollMs?: number;
warmTaskVersion?: 1;
releaseResumeVersion?: 1;
resumeCredentialVersion?: 1;
releasedSource?: DurableRecoveryIdentity;
sessionHandoff?: boolean;
onResumed?: (identity: DurableRecoveryIdentity) => Promise<void>;
@@ -433,6 +434,7 @@ export function createPluginRunnerTaskOwner(input: {
: undefined;
const result = await call(environmentTaskOperationSchema.parse({ kind: "resume", identity, bootstrapTicket,
...(handoffCredential ? { handoffCredential } : {}),
...(input.resumeCredentialVersion === 1 && input.credential ? { credential: input.credential } : {}),
...configuredEnvironmentFields(!!input.sessionHandoff),
}));
requireReleaseResume();