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
> - A plugin can be a project workspace provider and also an environment
driver for the agent runs that use those workspaces
> - Core asks the workspace provider to prepare the project workspace
before the run acquires its environment lease
> - The provider knows the run, agent, project, and execution workspace,
but not the environment that the run selected
> - A provider whose compute exists per run (for example, a sandbox that
it creates from the environment's driver config) cannot start or find
the run's compute for the workspace work
> - This pull request lets a provider opt in to receive the run's
selected environment, when that environment is one of the provider's own
drivers
> - The benefit is that such a provider can prepare the workspace on the
run's own compute, with no change to the order of operations in Core
## Linked Issues or Issue Description
**What existing behavior does this improve?**
Plugin workspace preparation for runs whose environment is a driver of
the same plugin.
**Subsystem affected**
Plugin SDK workspace provider params, the plugin manifest workspace
provider declaration, and `callWorkspaceProvider` /
`preparePluginWorkspace` in the server.
**Current behavior**
`prepare` params carry `runId`, `agentId`, `projectId`, and
`executionWorkspaceId`. They carry `taskLease` only when Core acquired
the lease first. They never name the run's environment.
**Proposed behavior**
A provider that declares `workspaceProvider.workspaceEnvironmentVersion:
1` receives `environment: { id, driverKey, config }` when the run's
selected environment is a plugin environment of that same provider.
`config` is the environment's `driverConfig`, the value that the
driver's acquire receives.
## What Changed
- SDK: optional strict `environment` field on
`pluginWorkspaceParamsSchema`.
- Manifest: optional `workspaceProvider.workspaceEnvironmentVersion: 1`,
next to the sibling version fields. Core sends the new field only to
providers that declare it, because providers parse the params with the
strict schema.
- Server: `callWorkspaceProvider` adds `environment` only when the
provider opted in, the environment driver is `plugin`, its `pluginKey`
is this provider, and it names a `driverKey`. The field is not part of
the operation ID.
- Server: `preparePluginWorkspace` passes the run's environment to its
prepare call. This covers normal, verify-existing, fresh, and
replacement prepares.
- Calls that do not have the run's environment do not send it: finalize,
inspect, remove, reservation reconciliation, and the retry-candidate
verification in `fresh-workspace-continuation.ts`.
- Lease acquisition, the `sessionHandoffVersion` gate, and the order of
operations do not change.
- Docs: `doc/plugins/PLUGIN_RUNNER_EXECUTION.md` describes the
capability and its exceptions.
## Verification
- `packages/plugins/sdk/tests/workspace-provider.test.ts`: 11 passed.
The schema accepts the field and rejects malformed values.
- `packages/shared/src/validators/plugin.test.ts`: 65 passed. The
manifest accepts only version 1.
- `server`: `plugin-workspaces.integration`,
`plugin-fresh-workspaces.integration`, `project-environments`, and
`heartbeat/workspace-preparation`: 226 passed, against embedded
Postgres. The new integration test checks the exact shape, an unchanged
operation ID, verification prepares, and omission for an undeclared
provider, another plugin's environment, non-plugin drivers, a missing
`driverKey`, and no environment. It fails when the server stops passing
the environment.
- `pnpm typecheck` passes in `packages/shared`, `packages/plugins/sdk`,
and `server`.
- The full suite was not run locally. CI runs it.
## Risks
- Low risk. Providers that do not declare the capability get the same
params as before.
- `config` is the stored `driverConfig`, in the same form that the
driver's acquire gets. Secret references in it reach the provider in
that same form.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, code search, test execution).
## 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)
- [ ] 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
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
216 lines
10 KiB
TypeScript
216 lines
10 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import {
|
|
workspaceProviderOperationSchema,
|
|
parseWorkspaceProviderResult,
|
|
parseWorkspacePrepareResult,
|
|
pluginWorkspaceParamsSchema,
|
|
pluginWorkspacePrepareParamsSchema,
|
|
type PluginWorkspaceParams,
|
|
} from "../src/workspace-provider.js";
|
|
import { createWorkspaceProviderHarness } from "../src/testing.js";
|
|
import { pluginManifestV1Schema } from "@paperclipai/shared";
|
|
const id = (n: number) =>
|
|
`10000000-0000-4000-8000-${String(n).padStart(12, "0")}`;
|
|
const params: PluginWorkspaceParams = {
|
|
pluginId: id(1),
|
|
companyId: id(2),
|
|
projectId: id(3),
|
|
executionWorkspaceId: id(4),
|
|
operationId: "stable",
|
|
generation: 0,
|
|
deadline: "2099-01-01T00:00:00Z",
|
|
runId: null,
|
|
agentId: null,
|
|
operation: {
|
|
kind: "prepare",
|
|
source: {
|
|
id: id(5),
|
|
revision: "source-v1",
|
|
repoUrl: "https://github.com/example/repo.git",
|
|
repoRef: null,
|
|
defaultRef: "main",
|
|
},
|
|
mode: "isolated_workspace",
|
|
strategy: "git_worktree",
|
|
branchName: "task",
|
|
baseRef: "main",
|
|
existing: null,
|
|
},
|
|
};
|
|
const result = {
|
|
kind: "prepared" as const,
|
|
binding: {
|
|
pluginId: id(1),
|
|
projectId: id(3),
|
|
executionWorkspaceId: id(4),
|
|
projectWorkspaceId: id(5),
|
|
sourceRevision: "source-v1",
|
|
workspaceRef: "opaque",
|
|
},
|
|
branchName: "task",
|
|
baseSha: "a".repeat(40),
|
|
created: true,
|
|
branchCreatedByRuntime: true,
|
|
};
|
|
describe("workspace provider SDK", () => {
|
|
it("accepts the run's own-driver environment and rejects malformed ones", () => {
|
|
const environment = { id: id(30), driverKey: "tasks", config: { snapshot: "base", nested: { size: 2 } } };
|
|
expect(pluginWorkspaceParamsSchema.parse({ ...params, environment }).environment).toEqual(environment);
|
|
expect(pluginWorkspaceParamsSchema.parse({ ...params, environment: { ...environment, config: {} } }).environment?.config).toEqual({});
|
|
expect(pluginWorkspaceParamsSchema.parse(params)).not.toHaveProperty("environment");
|
|
for (const bad of [
|
|
{ ...environment, id: "not-a-uuid" },
|
|
{ ...environment, driverKey: "" },
|
|
{ ...environment, driverKey: "x".repeat(129) },
|
|
{ ...environment, config: null },
|
|
{ ...environment, config: ["snapshot"] },
|
|
{ id: environment.id, driverKey: environment.driverKey },
|
|
{ ...environment, pluginKey: "other.plugin" },
|
|
]) {
|
|
expect(pluginWorkspaceParamsSchema.safeParse({ ...params, environment: bad }).success).toBe(false);
|
|
}
|
|
});
|
|
|
|
it("validates asynchronous preparation receipts and preserves result scope", () => {
|
|
const submit = pluginWorkspacePrepareParamsSchema.parse({ ...params, phase: "submit" });
|
|
const poll = { ...submit, phase: "poll" as const };
|
|
const pending = { kind: "pending", deadline: "2099-01-01T00:01:00Z" };
|
|
expect(parseWorkspacePrepareResult(submit, pending)).toEqual(pending);
|
|
expect(parseWorkspacePrepareResult(poll, result)).toEqual(result);
|
|
expect(() => parseWorkspacePrepareResult(poll, { kind: "unsupported" })).toThrow();
|
|
expect(() => parseWorkspacePrepareResult(poll, { ...pending, deadline: "whenever" })).toThrow();
|
|
expect(() => parseWorkspacePrepareResult(poll, { ...result, binding: { ...result.binding, projectId: id(20) } })).toThrow();
|
|
});
|
|
|
|
it("bounds recovery hints to an exact PR number and commit", () => {
|
|
for (const kind of ["inspect", "remove"] as const) {
|
|
const operation = { kind, binding: result.binding, ...(kind === "remove" ? { expectedHeadSha: "a".repeat(40) } : {}) };
|
|
const recoveryPullRequest = { number: 42, headSha: "a".repeat(40) };
|
|
expect(workspaceProviderOperationSchema.parse({ ...operation, recoveryPullRequest })).toMatchObject({ recoveryPullRequest });
|
|
for (const bad of [{ ...recoveryPullRequest, number: 0 }, { ...recoveryPullRequest, number: 1.5 },
|
|
{ ...recoveryPullRequest, headSha: "a".repeat(41) }, { ...recoveryPullRequest, ref: "refs/heads/main" }]) {
|
|
expect(() => workspaceProviderOperationSchema.parse({ ...operation, recoveryPullRequest: bad })).toThrow();
|
|
}
|
|
}
|
|
});
|
|
it("accepts an unbound reservation removal but requires a binding elsewhere", () => {
|
|
expect(workspaceProviderOperationSchema.parse({ kind: "remove", binding: null, expectedHeadSha: null }))
|
|
.toEqual({ kind: "remove", binding: null, expectedHeadSha: null });
|
|
expect(() => workspaceProviderOperationSchema.parse({ kind: "inspect", binding: null })).toThrow();
|
|
});
|
|
it("accepts only canonical optional preparation destinations", () => {
|
|
for (const destinationRef of [undefined, null, "refs/heads/main", "refs/heads/release/one"]) {
|
|
expect(parseWorkspaceProviderResult(params, { ...result, ...(destinationRef !== undefined ? { destinationRef } : {}) }))
|
|
.toMatchObject(result);
|
|
}
|
|
for (const destinationRef of ["main", "refs/tags/main", "refs/heads/main..other", "refs/heads/main/", "refs/heads/.hidden", "refs/heads/main.lock"]) {
|
|
expect(() => parseWorkspaceProviderResult(params, { ...result, destinationRef })).toThrow();
|
|
}
|
|
});
|
|
it("preserves a 255-character destination branch through preparation and restoration", () => {
|
|
const destinationRef = `refs/heads/release/${"a".repeat(247)}`;
|
|
expect(destinationRef).toHaveLength(266);
|
|
for (const input of [params, { ...params, operation: { ...params.operation, branchMode: "existing" as const, existing: result.binding } }]) {
|
|
expect(parseWorkspaceProviderResult(input as PluginWorkspaceParams, { ...result, destinationRef }))
|
|
.toMatchObject({ destinationRef });
|
|
expect(() => parseWorkspaceProviderResult(input as PluginWorkspaceParams, { ...result, destinationRef: `${destinationRef}a` })).toThrow();
|
|
}
|
|
});
|
|
it("separates completion acknowledgement from removal safety", () => {
|
|
const input: PluginWorkspaceParams = { ...params, agentId: id(6), runId: id(7),
|
|
operation: { kind: "finalize", binding: result.binding } };
|
|
expect(workspaceProviderOperationSchema.parse(input.operation)).toEqual(input.operation);
|
|
expect(parseWorkspaceProviderResult(input, { kind: "finalized", headSha: "a".repeat(40), branchName: "task" }))
|
|
.toEqual({ kind: "finalized", headSha: "a".repeat(40), branchName: "task" });
|
|
expect(() => parseWorkspaceProviderResult(input, { kind: "removed" })).toThrow();
|
|
expect(() => parseWorkspaceProviderResult(input, { kind: "finalized", headSha: "bad", branchName: "task" })).toThrow();
|
|
expect(() => workspaceProviderOperationSchema.parse({ ...input.operation, localPath: "/untrusted" })).toThrow();
|
|
});
|
|
it("prepares without a VM, lease, or host path", async () => {
|
|
const harness = createWorkspaceProviderHarness(async (input) => {
|
|
expect(input.agentId).toBeNull();
|
|
expect(input).not.toHaveProperty("lease");
|
|
expect(input.operation).not.toHaveProperty("localPath");
|
|
return result;
|
|
});
|
|
expect(await harness.operation(params)).toEqual(result);
|
|
});
|
|
it("rejects unrelated operation results and changed source revisions", () => {
|
|
expect(() =>
|
|
parseWorkspaceProviderResult(params, { kind: "removed" }),
|
|
).toThrow();
|
|
expect(() =>
|
|
parseWorkspaceProviderResult(params, {
|
|
...result,
|
|
binding: { ...result.binding, sourceRevision: "other" },
|
|
}),
|
|
).toThrow();
|
|
expect(() =>
|
|
parseWorkspaceProviderResult(params, {
|
|
...result,
|
|
binding: { ...result.binding, executionWorkspaceId: id(99) },
|
|
}),
|
|
).toThrow();
|
|
expect(() =>
|
|
parseWorkspaceProviderResult(params, { ...result, branchName: "wrong" }),
|
|
).toThrow();
|
|
expect(() =>
|
|
workspaceProviderOperationSchema.parse({
|
|
...params.operation,
|
|
shell: "arbitrary",
|
|
}),
|
|
).toThrow();
|
|
});
|
|
it("expresses fresh outcomes without imposing Git storage layout", () => {
|
|
const fresh = { attemptId: id(6), sourceRunId: id(7), previousWorkspaceId: id(8),
|
|
recoverySnapshots: [{ operationId: id(9), sourceRunId: id(7),
|
|
archive: { path: "/controller/recovery/archive.tar", sha256: "a".repeat(64), byteSize: 1024 },
|
|
manifest: { path: "/controller/recovery/manifest.jsonl", sha256: "b".repeat(64), byteSize: 128 } }] };
|
|
expect(workspaceProviderOperationSchema.parse({ ...params.operation, fresh })).toMatchObject({ fresh });
|
|
expect(() => workspaceProviderOperationSchema.parse({ ...params.operation, fresh: { ...fresh, independentGitStorage: true } })).toThrow();
|
|
expect(() => workspaceProviderOperationSchema.parse({ ...params.operation, fresh: { ...fresh, recoverySnapshots: [{ ...fresh.recoverySnapshots[0], archive: { ...fresh.recoverySnapshots[0].archive, sha256: "invalid" } }] } })).toThrow();
|
|
});
|
|
it("requires project lifecycle and storage management as one contract", () => {
|
|
const manifest = {
|
|
id: "test.storage",
|
|
apiVersion: 1,
|
|
version: "1.0.0",
|
|
displayName: "Storage",
|
|
description: "Storage",
|
|
author: "Test",
|
|
categories: ["workspace"],
|
|
entrypoints: { worker: "./worker.js" },
|
|
workspaceProvider: {
|
|
modes: ["isolated_workspace", "operator_branch"],
|
|
strategies: ["git_worktree"],
|
|
},
|
|
capabilities: ["workspaces.manage", "events.subscribe"],
|
|
resourceLifecycle: ["project"],
|
|
};
|
|
expect(pluginManifestV1Schema.safeParse(manifest).success).toBe(true);
|
|
expect(pluginManifestV1Schema.parse({ ...manifest, workspaceProvider: { ...manifest.workspaceProvider,
|
|
recoveryPullRequestVersion: 1 } }).workspaceProvider?.recoveryPullRequestVersion).toBe(1);
|
|
expect(pluginManifestV1Schema.safeParse({ ...manifest, workspaceProvider: { ...manifest.workspaceProvider,
|
|
recoveryPullRequestVersion: 2 } }).success).toBe(false);
|
|
const withDefault = { ...manifest, workspaceProvider: { ...manifest.workspaceProvider,
|
|
defaultForProjects: { mode: "isolated_workspace", strategy: "git_worktree" } } };
|
|
expect(pluginManifestV1Schema.parse(withDefault).workspaceProvider?.defaultForProjects).toEqual({
|
|
mode: "isolated_workspace", strategy: "git_worktree",
|
|
});
|
|
expect(pluginManifestV1Schema.safeParse({ ...withDefault, workspaceProvider: { ...withDefault.workspaceProvider,
|
|
defaultForProjects: { mode: "shared_workspace", strategy: "git_worktree" } } }).success).toBe(false);
|
|
expect(
|
|
pluginManifestV1Schema.safeParse({
|
|
...manifest,
|
|
resourceLifecycle: ["agent"],
|
|
}).success,
|
|
).toBe(false);
|
|
expect(
|
|
pluginManifestV1Schema.safeParse({
|
|
...manifest,
|
|
capabilities: ["events.subscribe"],
|
|
}).success,
|
|
).toBe(false);
|
|
});
|
|
});
|