mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 13:01:05 +01:00
## 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>
162 lines
9.9 KiB
TypeScript
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" } });
|
|
});
|
|
});
|