mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
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:
1 parent
3b03ac10e5
commit
5df1ada9c1
9 files changed
+57
-29
No files matched your search
@@ -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",
|
||||
|
||||
Reference in new issue
Block a user