Files
PaperClipAI/packages/plugins/sdk/src/workspace-provider.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

213 lines
8.2 KiB
TypeScript

import { z } from "zod";
import { workspaceProviderBindingSchema } from "@paperclipai/shared";
const recoveryFile = z.object({
path: z.string().min(1),
sha256: z.string().regex(/^[a-f0-9]{64}$/),
byteSize: z.number().int().positive(),
}).strict();
export const freshWorkspaceSchema = z.object({
attemptId: z.string().uuid(),
sourceRunId: z.string().uuid(),
previousWorkspaceId: z.string().uuid().nullable(),
recoverySnapshots: z.array(z.object({
operationId: z.string().uuid(), sourceRunId: z.string().uuid(),
archive: recoveryFile, manifest: recoveryFile,
}).strict()),
}).strict();
export type PluginFreshWorkspace = z.infer<typeof freshWorkspaceSchema>;
const sha = z.string().regex(/^[a-f0-9]{40,64}$/);
export const workspaceRecoveryPullRequestSchema = z.object({
number: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
headSha: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/),
}).strict();
export type PluginWorkspaceRecoveryPullRequest = z.infer<typeof workspaceRecoveryPullRequestSchema>;
const destinationRef = z.string().max(266).regex(/^refs\/heads\/[^\x00-\x20\x7f~^:?*\[\]\\]+$/)
.refine(ref => !ref.includes("..") && !ref.includes("@{") && !ref.endsWith(".") && !ref.endsWith("/")
&& ref.split("/").every(part => part && !part.startsWith(".") && !part.endsWith(".lock")));
export const workspaceProviderOperationSchema = z.discriminatedUnion("kind", [
z
.object({
kind: z.literal("prepare"),
source: z
.object({
id: z.string().uuid(),
revision: z.string().min(1).max(256),
repoUrl: z.string().url().nullable(),
repoRef: z.string().nullable(),
defaultRef: z.string().nullable(),
})
.strict(),
mode: z.enum([
"shared_workspace",
"isolated_workspace",
"operator_branch",
]),
strategy: z.enum(["project_primary", "git_worktree"]),
branchName: z.string().min(1).max(256).nullable(),
branchMode: z.enum(["create", "existing"]).optional(),
baseRef: z.string().nullable(),
existing: workspaceProviderBindingSchema.nullable(),
fresh: freshWorkspaceSchema.optional(),
verifyExisting: z.literal(true).optional(),
})
.strict(),
// Verify the retained workspace and flush run writes. This does not certify
// remote recoverability or authorize removal; dirty work is valid output.
z.object({ kind: z.literal("finalize"), binding: workspaceProviderBindingSchema }).strict(),
z
.object({
kind: z.literal("inspect"),
binding: workspaceProviderBindingSchema,
recoveryPullRequest: workspaceRecoveryPullRequestSchema.optional(),
})
.strict(),
z
.object({
kind: z.literal("remove"),
binding: workspaceProviderBindingSchema.nullable(),
expectedHeadSha: sha.nullable(),
recoveryPullRequest: workspaceRecoveryPullRequestSchema.optional(),
})
.strict(),
]);
export const workspaceProviderResultSchema = z.discriminatedUnion("kind", [
z
.object({
kind: z.literal("prepared"),
binding: workspaceProviderBindingSchema,
branchName: z.string().min(1).max(256).nullable(),
baseSha: sha.nullable(),
destinationRef: destinationRef.nullable().optional(),
created: z.boolean(),
branchCreatedByRuntime: z.boolean(),
})
.strict(),
z
.object({
kind: z.literal("inspection"),
headSha: sha.nullable(),
branchName: z.string().nullable(),
hasDirtyTrackedFiles: z.boolean(),
hasUntrackedFiles: z.boolean(),
hasLocalOnlyData: z.boolean(),
isMergedIntoBase: z.boolean().nullable(),
remotelyRecoverable: z.boolean().nullable(),
})
.strict(),
// Return only after retained files are durable and their identity is verified.
z.object({ kind: z.literal("finalized"), headSha: sha.nullable(), branchName: z.string().nullable() }).strict(),
// Return only after removal is confirmed. Busy, failed and uncertain operations must throw.
z.object({ kind: z.literal("removed") }).strict(),
]);
export type PluginWorkspaceOperation = z.infer<
typeof workspaceProviderOperationSchema
>;
export type PluginWorkspaceResult = z.infer<
typeof workspaceProviderResultSchema
>;
export const pluginWorkspaceParamsSchema = z
.object({
pluginId: z.string().uuid(),
companyId: z.string().uuid(),
projectId: z.string().uuid(),
executionWorkspaceId: z.string().uuid(),
/** Stable across ambiguous retries; reconcile before repeating effects. */
operationId: z.string().min(1).max(256),
generation: z.number().int().nonnegative(),
deadline: z.string().datetime(),
runId: z.string().uuid().nullable(),
agentId: z.string().uuid().nullable(),
/** Placement selected by Core for workspace work on the run's Launcher. */
taskLease: z.object({
environmentId: z.string().uuid(),
driverKey: z.string().min(1).max(128),
providerLeaseId: z.string().min(1).max(1024),
}).strict().optional(),
/**
* The run's selected environment, sent only when it is an environment driver
* of this same plugin and the provider declares
* `workspaceProvider.workspaceEnvironmentVersion: 1`. `config` is that
* environment's driver config, exactly as the driver's acquire receives it.
* It is not part of the operation identity.
*/
environment: z.object({
id: z.string().uuid(),
driverKey: z.string().min(1).max(128),
config: z.record(z.string(), z.unknown()),
}).strict().optional(),
operation: workspaceProviderOperationSchema,
})
.strict();
/** Finalization receives the originating run/agent context; maintenance remains agent-independent. */
export type PluginWorkspaceParams = z.infer<typeof pluginWorkspaceParamsSchema>;
export const pluginWorkspacePrepareParamsSchema = pluginWorkspaceParamsSchema.extend({
phase: z.enum(["submit", "poll"]),
}).refine((input) => input.operation.kind === "prepare");
export type PluginWorkspacePrepareParams = z.infer<typeof pluginWorkspacePrepareParamsSchema>;
export type PluginWorkspacePrepareResult =
| { kind: "unsupported" }
| { kind: "pending"; deadline: string }
| Extract<PluginWorkspaceResult, { kind: "prepared" }>;
export function parseWorkspacePrepareResult(
params: PluginWorkspacePrepareParams,
value: unknown,
): PluginWorkspacePrepareResult {
const result = z.discriminatedUnion("kind", [
z.object({ kind: z.literal("unsupported") }).strict(),
z.object({ kind: z.literal("pending"), deadline: z.string().datetime() }).strict(),
]).safeParse(value);
if (result.success) {
if (result.data.kind === "unsupported" && params.phase !== "submit")
throw new Error("Workspace provider withdrew asynchronous preparation");
return result.data;
}
const prepared = parseWorkspaceProviderResult(params, value);
if (prepared.kind !== "prepared") throw new Error("Workspace provider returned the wrong preparation result");
return prepared;
}
export function parseWorkspaceProviderResult(
params: PluginWorkspaceParams,
value: unknown,
): PluginWorkspaceResult {
const result = workspaceProviderResultSchema.parse(value);
const expected =
params.operation.kind === "prepare"
? "prepared"
: params.operation.kind === "inspect"
? "inspection"
: params.operation.kind === "finalize" ? "finalized" : "removed";
if (result.kind !== expected)
throw new Error("Workspace provider returned the wrong operation result");
if (
result.kind === "prepared" &&
(result.binding.pluginId !== params.pluginId ||
result.binding.executionWorkspaceId !== params.executionWorkspaceId ||
result.binding.projectId !== params.projectId ||
result.binding.projectWorkspaceId !==
(params.operation.kind === "prepare"
? params.operation.source.id
: undefined) ||
result.binding.sourceRevision !==
(params.operation.kind === "prepare"
? params.operation.source.revision
: undefined))
) {
throw new Error("Workspace provider returned a different source binding");
}
if (
result.kind === "prepared" &&
params.operation.kind === "prepare" &&
params.operation.branchName &&
result.branchName !== params.operation.branchName
) {
throw new Error("Workspace provider returned a different branch");
}
return result;
}