mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
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:
1 parent
e063587edd
commit
41998d551c
9 files changed
+99
-3
No files matched your search
@@ -117,6 +117,21 @@ 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 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
|
||||
task state, lease metadata, journals, logs, results or durable replay records.
|
||||
|
||||
The `resume` result has a closed `outcome`:
|
||||
|
||||
- `resumed`: the same logical session is exclusively reserved for this claimant,
|
||||
|
||||
@@ -146,6 +146,7 @@ export const environmentTaskOperationSchema = z.discriminatedUnion("kind", [
|
||||
z.object({ kind: z.literal("release"), identity: durableIdentity }).strict(),
|
||||
z.object({ kind: z.literal("resume"), identity: durableIdentity, bootstrapTicket: credentialValue,
|
||||
handoffCredential: z.object({ accountIdentity: z.string().min(1).max(1024), environment: claudeCredentialEnvironment }).strict().optional(),
|
||||
credential: environmentTaskCredentialSchema.optional(),
|
||||
configuredEnvironment: environmentTaskConfiguredEnvironmentSchema.optional(),
|
||||
}).strict(),
|
||||
z.object({
|
||||
@@ -203,6 +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(),
|
||||
}).strict(),
|
||||
z.object({
|
||||
kind: z.literal("status"), taskId: providerId,
|
||||
|
||||
@@ -22,6 +22,21 @@ const ownership = {
|
||||
sourceTaskId: "source-task", sourceGeneration: "source-generation", targetGeneration: "target-generation", policy: "reclaim_if_needed",
|
||||
} as const;
|
||||
const description = { kind: "description", taskId: "task", runner: { version: "fixture", digest: `sha256:${"a".repeat(64)}` } };
|
||||
const submit = { kind: "submit", projectIds: [], bootstrapTicket: "fixture-ticket", runner: { harness: "claude", protocolMin: 1, protocolMax: 3,
|
||||
runnerId: "runner", leaseId: "lease", runId: "run", sessionId: "session", turnId: "turn", itemId: "item" } } as const;
|
||||
const credentials: [string, unknown, boolean][] = [
|
||||
["a Claude OAuth token", { type: "claude-env", environment: { CLAUDE_CODE_OAUTH_TOKEN: "fixture-oauth" } }, true],
|
||||
["a Claude API key", { type: "claude-env", environment: { ANTHROPIC_API_KEY: "fixture-key" } }, true],
|
||||
["a Codex auth file", { type: "codex-auth-json", authJson: "{\"tokens\":{}}" }, true],
|
||||
["two Claude credentials", { type: "claude-env", environment: { CLAUDE_CODE_OAUTH_TOKEN: "a", ANTHROPIC_API_KEY: "b" } }, false],
|
||||
["no Claude credential", { type: "claude-env", environment: {} }, false],
|
||||
["an unsupported Claude variable", { type: "claude-env", environment: { ANTHROPIC_BASE_URL: "https://example.test" } }, false],
|
||||
["an empty value", { type: "claude-env", environment: { CLAUDE_CODE_OAUTH_TOKEN: "" } }, false],
|
||||
["a NUL byte", { type: "claude-env", environment: { CLAUDE_CODE_OAUTH_TOKEN: "a\0b" } }, false],
|
||||
["an oversized value", { type: "codex-auth-json", authJson: "x".repeat(65_537) }, false],
|
||||
["an unknown type", { type: "gemini-env", environment: { GEMINI_API_KEY: "fixture" } }, false],
|
||||
["an extra field", { type: "codex-auth-json", authJson: "{}", path: "/home/agent/.codex" }, false],
|
||||
];
|
||||
|
||||
async function invoke(operation: unknown, handler: (params: PluginEnvironmentTaskParams) => Promise<PluginEnvironmentTaskResult>) {
|
||||
const stdin = new PassThrough(), stdout = new PassThrough(), lines = createInterface({ input: stdout });
|
||||
@@ -44,6 +59,22 @@ 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);
|
||||
});
|
||||
|
||||
it.each(credentials)("validates %s on resume as on submit", (_label, credential, valid) => {
|
||||
expect(environmentTaskOperationSchema.safeParse({ ...submit, credential }).success).toBe(valid);
|
||||
expect(environmentTaskOperationSchema.safeParse({ ...resume, credential }).success).toBe(valid);
|
||||
});
|
||||
|
||||
it("dispatches a resume credential through the serialized worker RPC", async () => {
|
||||
const operation = { ...resume, credential: { type: "claude-env", environment: { CLAUDE_CODE_OAUTH_TOKEN: "fixture-oauth" } } } as const;
|
||||
const result = { kind: "resume", taskId: "task", outcome: "resumed" } as const;
|
||||
expect(await invoke(operation, async params => {
|
||||
expect(params.operation).toEqual(operation);
|
||||
return result;
|
||||
})).toMatchObject({ result });
|
||||
});
|
||||
|
||||
it.each([release, resume])("requires the exact durable identity for $kind", operation => {
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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": "318915dd6f2f6c86e875bfcb3a87a52b21afba1d",
|
||||
"packages/plugins/sdk/src/environment-tasks.ts": "1534cca17be5b8c924b2b6be44339dc6faf493c1",
|
||||
"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",
|
||||
|
||||
Reference in new issue
Block a user