@paperclipai/plugin-sdk 2026.1023.0 → 2026.1024.0-canary.1

package/dist/workspace-provider.js

@@ -0,0 +1,135 @@
+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();
+const sha = z.string().regex(/^[a-f0-9]{40,64}$/);
+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(),
+    })
+        .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,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("remove"),
+        binding: workspaceProviderBindingSchema,
+        expectedHeadSha: sha.nullable(),
+    })
+        .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(),
+        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 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(),
+    operation: workspaceProviderOperationSchema,
+})
+    .strict();
+export function parseWorkspaceProviderResult(params, value) {
+    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;
+}
+//# sourceMappingURL=workspace-provider.js.map

package/dist/workspace-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-provider.js","sourceRoot":"","sources":["../src/workspace-provider.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/plugin-sdk",
-  "version": "2026.1023.0",
+  "version": "2026.1024.0-canary.1",
   "description": "Stable public API for Paperclip plugins — worker-side context and UI bridge hooks",
   "license": "MIT",
   "homepage": "https://github.com/paperclipai/paperclip",
@@ -61,7 +61,7 @@
     "dist"
   ],
   "dependencies": {
-    "@paperclipai/shared": "2026.1023.0",
+    "@paperclipai/shared": "2026.1024.0-canary.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {