Files
PaperClipAI/packages/plugins/sdk/tests/environment-task-release-resume.test.ts
T
Nicky LeachandClaude Opus 5.5 5df1ada9c1 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>
2026-11-13 13:46:37 -08:00

162 lines
9.9 KiB
TypeScript

import { createInterface } from "node:readline";
import { PassThrough } from "node:stream";
import { describe, expect, it } from "vitest";
import { definePlugin } from "../src/define-plugin.js";
import {
environmentTaskOperationSchema,
environmentTaskResultSchema,
parseEnvironmentTaskResult,
type PluginEnvironmentTaskOperation,
type PluginEnvironmentTaskParams,
type PluginEnvironmentTaskResult,
} from "../src/environment-tasks.js";
import { createRequest, isJsonRpcResponse, parseMessage, serializeMessage, type JsonRpcResponse } from "../src/protocol.js";
import { startWorkerRpcHost } from "../src/worker-rpc-host.js";
const identity = { runnerInstanceId: "runner", environmentLeaseId: "lease", runId: "source-run",
normalizedSessionId: "session", turnId: "turn", itemId: "item" };
const release = { kind: "release", identity } as const;
const resume = { kind: "resume", identity, bootstrapTicket: "fixture-ticket" } as const;
const ownership = {
kind: "ensure_ownership", operationId: "9df4526f-36c5-4fba-9cf6-3c4fd317f531", identity,
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 });
const worker = startWorkerRpcHost({ stdin, stdout, plugin: definePlugin({ async setup() {}, onEnvironmentTask: handler }) });
try {
const response = new Promise<JsonRpcResponse>(resolve => lines.on("line", line => {
const message = parseMessage(line);
if (isJsonRpcResponse(message)) resolve(message);
}));
stdin.write(serializeMessage(createRequest("environmentTask", { companyId: "company", taskId: "task",
runId: "claimant-run", lease: { providerLeaseId: "task" }, operation }, "lifecycle")));
return await response;
} finally { worker.stop(); lines.close(); stdin.destroy(); stdout.destroy(); }
}
describe("release and resume task contract", () => {
it("keeps the capability optional and independent of warm and source recovery support", () => {
for (const capabilities of [{}, { releaseResumeVersion: 1 }, { warmTaskVersion: 1 },
{ codexSourceRecoveryVersion: 1 }, { acpxSourceRecoveryVersion: 1 }]) {
expect(environmentTaskResultSchema.parse({ ...description, ...capabilities })).toEqual({ ...description, ...capabilities });
}
expect(environmentTaskResultSchema.safeParse({ ...description, releaseResumeVersion: 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) => {
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 => {
expect(environmentTaskOperationSchema.parse(operation)).toEqual(operation);
for (const field of Object.keys(identity)) {
expect(environmentTaskOperationSchema.safeParse({ ...operation, identity: { ...identity, [field]: undefined } }).success).toBe(false);
}
expect(environmentTaskOperationSchema.safeParse({ ...operation, identity: { ...identity, targetRunId: "other" } }).success).toBe(false);
expect(environmentTaskOperationSchema.safeParse({ ...operation, cancelActiveWork: true }).success).toBe(false);
});
it.each([undefined, "", "\0", "x".repeat(65_537)])("rejects a missing or invalid resume ticket", bootstrapTicket => {
expect(environmentTaskOperationSchema.safeParse({ ...resume, bootstrapTicket }).success).toBe(false);
});
it("matches each operation to its own closed result and task", () => {
const released = { kind: "released", taskId: "task" };
expect(parseEnvironmentTaskResult(release, "task", released)).toEqual(released);
for (const outcome of ["resumed", "unavailable"]) {
const result = { kind: "resume", taskId: "task", outcome };
expect(parseEnvironmentTaskResult(resume, "task", result)).toEqual(result);
expect(() => parseEnvironmentTaskResult(release, "task", result)).toThrow();
}
for (const operation of [release, resume]) {
expect(() => parseEnvironmentTaskResult(operation, "task", { kind: "accepted", taskId: "task" })).toThrow();
const result = operation.kind === "release" ? released : { kind: "resume", taskId: "task", outcome: "resumed" };
expect(() => parseEnvironmentTaskResult(operation, "other-task", result)).toThrow();
}
expect(() => parseEnvironmentTaskResult(resume, "task", { kind: "resume", taskId: "task", outcome: "unknown" })).toThrow();
expect(environmentTaskResultSchema.safeParse({ ...released, retained: true }).success).toBe(false);
expect(environmentTaskResultSchema.safeParse({ kind: "resume", taskId: "task", outcome: "resumed", bootstrapTicket: "fixture-ticket" }).success).toBe(false);
});
it.each([release, resume])("dispatches $kind through the serialized worker RPC", async operation => {
const result: PluginEnvironmentTaskResult = operation.kind === "release" ? { kind: "released", taskId: "task" }
: { kind: "resume", taskId: "task", outcome: "resumed" };
const response = await invoke(operation, async params => {
expect(params.operation).toEqual(operation);
expect(params.runId).toBe("claimant-run");
return result;
});
expect(response).toMatchObject({ result });
});
it("passes known absence through RPC without treating it as a successful reservation", async () => {
expect(await invoke(resume, async () => ({ kind: "resume", taskId: "task", outcome: "unavailable" })))
.toMatchObject({ result: { kind: "resume", taskId: "task", outcome: "unavailable" } });
});
it("binds a declarative ownership response to the exact worker request", async () => {
for (const status of ["pending", "ready"] as const) {
const result = { kind: "ownership", status, taskId: "task", operationId: ownership.operationId,
targetGeneration: ownership.targetGeneration } as const;
expect(await invoke(ownership, async params => {
expect(params.operation).toEqual(ownership);
return result;
})).toMatchObject({ result });
for (const changes of [
{ taskId: "another-task" },
{ operationId: "1f083ad0-a357-4f14-ad46-e9df981845b5" },
{ targetGeneration: "stale-generation" },
]) {
expect(await invoke(ownership, async () => ({ ...result, ...changes }))).toHaveProperty("error");
}
}
});
it.each(["source mismatch", "claim conflict", "authentication failed", "transport timeout"])("keeps %s as an RPC error", async message => {
expect(await invoke(resume, async () => { throw new Error(message); })).toHaveProperty("error");
});
it("rejects cross-task and wrong-kind replies at the worker boundary", async () => {
for (const result of [{ kind: "resume", taskId: "other", outcome: "resumed" }, { kind: "accepted", taskId: "task" }] as PluginEnvironmentTaskResult[]) {
expect(await invoke(resume, async () => result)).toHaveProperty("error");
}
});
it("preserves legacy describe and stop replies through RPC", async () => {
expect(await invoke({ kind: "describe" }, async () => description as PluginEnvironmentTaskResult)).toMatchObject({ result: description });
const operation: PluginEnvironmentTaskOperation = { kind: "stop" };
expect(await invoke(operation, async () => ({ kind: "accepted", taskId: "task" })))
.toMatchObject({ result: { kind: "accepted", taskId: "task" } });
});
});