mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-21 02:43:25 +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>
213 lines
8.2 KiB
TypeScript
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;
|
|
}
|