Files
PaperClipAI/packages/plugins/sdk/tests/workspace-provider.test.ts
T
Nicky LeachandClaude Opus 5.5 1140984b82 feat(plugins): tell an opted-in workspace provider the run's environment (#21512)
## 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>
2026-11-13 15:43:10 -08:00

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);
});
});