mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 18:26:40 +01:00
## 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>
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, 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 => {
|
|
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" } });
|
|
});
|
|
});
|