The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Auto-build bundled plugins on install (#8254)
Devin Foleyd47b4da655d5
diff --git a/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.mdindex 3bf7b00945..715baaeb95 100644--- a/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md+++ b/doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md@@ -116,7 +116,7 @@ What that means in practice:- **Without `pnpm dev`:** the watcher only fires on `dist/*` changes. If you stop the watch build, source edits do not reach Paperclip. Restart `pnpm dev` (or run `pnpm build` once) before expecting changes.- **`node_modules`, `.git`, `.paperclip-sdk`, and other dotfolders are ignored.** Adding a dependency requires the new code to actually be imported and rebuilt before the worker sees it.-The server never compiles plugin source for you. The package's own build scripts own that step.+The package's own build scripts still own compilation. Paperclip does not compile arbitrary local-path plugins for you. The exceptions are bundled plugins inside the Paperclip repo under `packages/plugins/`: workspace packages auto-build once with `pnpm --filter <package> build`, and standalone sandbox-provider packages under `packages/plugins/sandbox-providers/` first bootstrap package-local dependencies with `pnpm install --ignore-workspace ...` and then run `pnpm build` in place. Set `PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD=1` in the server environment to disable those fallbacks.## Local path plugins vs npm packages@@ -136,7 +136,7 @@ When you are done iterating locally, publish the package and reinstall the npm-p## Troubleshooting-- **`Plugin install returned no plugin record` or `error` status.** Run `paperclipai plugin inspect <key>` for the last error. The most common causes are (1) the plugin has not built yet — run `pnpm dev` or `pnpm build` first, (2) the `paperclipPlugin` entries in `package.json` point at files that do not exist on disk, or (3) the manifest failed validation. The Paperclip server log has the full validation error.+- **`Plugin install returned no plugin record` or `error` status.** Run `paperclipai plugin inspect <key>` for the last error. The most common causes are (1) the plugin has not built yet — run `pnpm dev` or `pnpm build` first, (2) the `paperclipPlugin` entries in `package.json` point at files that do not exist on disk, or (3) the manifest failed validation. Bundled repo plugins may auto-build once during install, but external local-path plugins still require you to build them yourself. The Paperclip server log has the full validation error.- **Edits do not seem to reload.** Confirm `pnpm dev` is still running and writing to `dist/`. If you renamed entry files, update the `paperclipPlugin.manifest` / `paperclipPlugin.worker` / `paperclipPlugin.ui` fields in `package.json` so the watcher targets them.- **Worker restarts but UI is stale.** Hard-reload the page. If you want HMR, run `pnpm dev:ui` and set `devUiUrl` in your manifest to `http://127.0.0.1:4177` during development.- **Path arguments fail on Windows.** Quote paths that contain spaces, and prefer absolute paths over `~`-prefixed paths in non-bash shells.diff --git a/server/src/__tests__/plugin-install-autobuild.test.ts b/server/src/__tests__/plugin-install-autobuild.test.tsnew file mode 100644index 0000000000..732ddff3d8--- /dev/null+++ b/server/src/__tests__/plugin-install-autobuild.test.ts@@ -0,0 +1,402 @@+import express from "express";+import { randomUUID } from "node:crypto";+import { existsSync } from "node:fs";+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import request from "supertest";+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";+import { createDb, plugins } from "@paperclipai/db";+import {+ ensureLocalPluginBuilt,+ pluginLoader,+ REPO_ROOT,+} from "../services/plugin-loader.js";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.js";++const mockLifecycle = vi.hoisted(() => ({+ load: vi.fn(),+ upgrade: vi.fn(),+ unload: vi.fn(),+ enable: vi.fn(),+ disable: vi.fn(),+}));++vi.mock("../services/plugin-lifecycle.js", () => ({+ pluginLifecycleManager: () => mockLifecycle,+}));++vi.mock("../services/activity-log.js", () => ({+ logActivity: vi.fn(),+}));++vi.mock("../services/live-events.js", () => ({+ publishGlobalLiveEvent: vi.fn(),+}));++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe.sequential : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping plugin install auto-build tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}++type FixturePlugin = {+ packageName: string;+ pluginKey: string;+ packageRoot: string;+ distDir: string;+};++const repoPluginRoot = path.join(REPO_ROOT, "packages", "plugins");+const standaloneRepoPluginRoot = path.join(repoPluginRoot, "sandbox-providers");++async function createBundledPluginFixture(+ nameSuffix: string,+ options: { rootDir?: string; buildDistImmediately?: boolean } = {},+): Promise<FixturePlugin> {+ const slug = `plugin-autobuild-${nameSuffix}-${randomUUID().slice(0, 8)}`;+ const packageName = `@paperclipai/${slug}`;+ const pluginKey = `paperclip.${slug.replace(/^plugin-/, "").replace(/-/g, "_")}`;+ const packageRoot = path.join(options.rootDir ?? repoPluginRoot, slug);+ const distDir = path.join(packageRoot, "dist");+ const isStandaloneFixture = (options.rootDir ?? repoPluginRoot) === standaloneRepoPluginRoot;+ const postinstallScript = isStandaloneFixture+ ? `node ${path.relative(packageRoot, path.join(REPO_ROOT, "scripts", "link-plugin-dev-sdk.mjs"))}`+ : null;++ await mkdir(path.join(packageRoot, "scripts"), { recursive: true });+ await writeFile(+ path.join(packageRoot, "package.json"),+ JSON.stringify({+ name: packageName,+ version: "0.1.0",+ private: true,+ type: "module",+ scripts: {+ ...(postinstallScript ? { postinstall: postinstallScript } : {}),+ build: "node ./scripts/build.mjs",+ },+ paperclipPlugin: {+ manifest: "./dist/manifest.js",+ worker: "./dist/worker.js",+ ui: "./dist/ui/",+ },+ }, null, 2),+ "utf8",+ );++ const manifest = {+ id: pluginKey,+ apiVersion: 1,+ version: "0.1.0",+ displayName: "Autobuild Fixture",+ description: "Bundled plugin fixture for install-time auto-build coverage.",+ author: "Paperclip",+ categories: ["automation"],+ capabilities: ["companies.read"],+ entrypoints: {+ worker: "./dist/worker.js",+ },+ };++ await writeFile(+ path.join(packageRoot, "scripts", "build.mjs"),+ [+ "import { mkdir, writeFile } from \"node:fs/promises\";",+ "import path from \"node:path\";",+ "import { fileURLToPath } from \"node:url\";",+ "",+ "const scriptDir = path.dirname(fileURLToPath(import.meta.url));",+ "const packageRoot = path.resolve(scriptDir, \"..\");",+ "const distDir = path.join(packageRoot, \"dist\");",+ "const uiDir = path.join(distDir, \"ui\");",+ `const manifest = ${JSON.stringify(manifest, null, 2)};`,+ "",+ "await mkdir(uiDir, { recursive: true });",+ "await writeFile(path.join(distDir, \"manifest.js\"), `export default ${JSON.stringify(manifest, null, 2)};\\n`, \"utf8\");",+ "await writeFile(path.join(distDir, \"worker.js\"), \"export {};\\n\", \"utf8\");",+ "await writeFile(path.join(uiDir, \"index.js\"), \"export default {};\\n\", \"utf8\");",+ ].join("\n"),+ "utf8",+ );++ if (options.buildDistImmediately) {+ await mkdir(path.join(distDir, "ui"), { recursive: true });+ await writeFile(path.join(distDir, "manifest.js"), `export default ${JSON.stringify(manifest, null, 2)};\n`, "utf8");+ await writeFile(path.join(distDir, "worker.js"), "export {};\n", "utf8");+ await writeFile(path.join(distDir, "ui", "index.js"), "export default {};\n", "utf8");+ }++ return { packageName, pluginKey, packageRoot, distDir };+}++async function createInstallApp(db: ReturnType<typeof createDb>) {+ const [{ pluginRoutes }, { errorHandler }] = await Promise.all([+ import("../routes/plugins.js"),+ import("../middleware/index.js"),+ ]);++ const loader = pluginLoader(db, {+ enableLocalFilesystem: false,+ enableNpmDiscovery: false,+ });++ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ req.actor = {+ type: "board",+ userId: "admin-1",+ source: "session",+ isInstanceAdmin: true,+ companyIds: [],+ } as typeof req.actor;+ next();+ });+ app.use("/api", pluginRoutes(db as never, loader as never, {} as never, undefined, {} as never, {} as never));+ app.use(errorHandler);+ return app;+}++describe("ensureLocalPluginBuilt", () => {+ const cleanupPaths = new Set<string>();++ afterEach(async () => {+ for (const cleanupPath of cleanupPaths) {+ await rm(cleanupPath, { recursive: true, force: true });+ }+ cleanupPaths.clear();+ });++ it("skips auto-build for local plugin paths outside the repo", async () => {+ const tempRoot = await mkdtemp(path.join(os.tmpdir(), "paperclip-plugin-outside-"));+ const packageRoot = path.join(tempRoot, "plugin-outside");+ cleanupPaths.add(path.dirname(packageRoot));+ await mkdir(packageRoot, { recursive: true });++ const execStub = vi.fn().mockResolvedValue({ stdout: "", stderr: "" });+ await ensureLocalPluginBuilt(+ packageRoot,+ {+ name: "@paperclipai/plugin-outside",+ paperclipPlugin: {+ manifest: "./dist/manifest.js",+ worker: "./dist/worker.js",+ },+ },+ { execFileAsyncImpl: execStub },+ );++ expect(execStub).not.toHaveBeenCalled();+ });++ it("skips auto-build when PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD=1", async () => {+ const fixture = await createBundledPluginFixture("skip");+ cleanupPaths.add(fixture.packageRoot);++ const execStub = vi.fn().mockResolvedValue({ stdout: "", stderr: "" });+ await ensureLocalPluginBuilt(+ fixture.packageRoot,+ JSON.parse(await readFile(path.join(fixture.packageRoot, "package.json"), "utf8")) as Record<string, unknown>,+ {+ processEnv: { PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD: "1" },+ execFileAsyncImpl: execStub,+ },+ );++ expect(execStub).not.toHaveBeenCalled();+ });++ it("bootstraps standalone bundled plugins before building them", async () => {+ const fixture = await createBundledPluginFixture("standalone", { rootDir: standaloneRepoPluginRoot });+ cleanupPaths.add(fixture.packageRoot);++ const execStub = vi.fn(async (_file: string, args: readonly string[]) => {+ if (args.join(" ") === "install --ignore-workspace --no-lockfile") {+ await mkdir(path.join(fixture.packageRoot, "node_modules", "@paperclipai", "plugin-sdk"), { recursive: true });+ }+ if (args.join(" ") === "build") {+ await mkdir(path.join(fixture.distDir, "ui"), { recursive: true });+ await writeFile(path.join(fixture.distDir, "manifest.js"), "export default {};\n", "utf8");+ await writeFile(path.join(fixture.distDir, "worker.js"), "export {};\n", "utf8");+ await writeFile(path.join(fixture.distDir, "ui", "index.js"), "export default {};\n", "utf8");+ }+ return { stdout: "", stderr: "" };+ });+ await ensureLocalPluginBuilt(+ fixture.packageRoot,+ JSON.parse(await readFile(path.join(fixture.packageRoot, "package.json"), "utf8")) as Record<string, unknown>,+ { execFileAsyncImpl: execStub },+ );++ expect(execStub).toHaveBeenCalledTimes(2);+ expect(execStub).toHaveBeenNthCalledWith(+ 1,+ "pnpm",+ ["install", "--ignore-workspace", "--no-lockfile"],+ { cwd: fixture.packageRoot, timeout: 120_000 },+ );+ expect(execStub).toHaveBeenNthCalledWith(+ 2,+ "pnpm",+ ["build"],+ { cwd: fixture.packageRoot, timeout: 120_000 },+ );+ });++ it("bootstraps standalone bundled plugin runtime dependencies when dist already exists", async () => {+ const fixture = await createBundledPluginFixture("standalone-runtime", {+ rootDir: standaloneRepoPluginRoot,+ buildDistImmediately: true,+ });+ cleanupPaths.add(fixture.packageRoot);++ const execStub = vi.fn(async () => {+ await mkdir(path.join(fixture.packageRoot, "node_modules", "@paperclipai", "plugin-sdk"), { recursive: true });+ return { stdout: "", stderr: "" };+ });+ await ensureLocalPluginBuilt(+ fixture.packageRoot,+ JSON.parse(await readFile(path.join(fixture.packageRoot, "package.json"), "utf8")) as Record<string, unknown>,+ { execFileAsyncImpl: execStub },+ );++ expect(execStub).toHaveBeenCalledTimes(1);+ expect(execStub).toHaveBeenNthCalledWith(+ 1,+ "pnpm",+ ["install", "--ignore-workspace", "--no-lockfile"],+ { cwd: fixture.packageRoot, timeout: 120_000 },+ );+ });+});++describeEmbeddedPostgres("plugin install auto-build route", () => {+ let db!: ReturnType<typeof createDb>;+ let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;+ const cleanupPaths = new Set<string>();++ beforeAll(async () => {+ tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-autobuild-");+ db = createDb(tempDb.connectionString);+ }, 20_000);++ afterEach(async () => {+ vi.clearAllMocks();+ await db.delete(plugins);+ for (const cleanupPath of cleanupPaths) {+ await rm(cleanupPath, { recursive: true, force: true });+ }+ cleanupPaths.clear();+ delete process.env["PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD"];+ });++ afterAll(async () => {+ await tempDb?.cleanup();+ });++ it("auto-builds bundled local plugins during POST /api/plugins/install when dist is missing", async () => {+ const fixture = await createBundledPluginFixture("success");+ cleanupPaths.add(fixture.packageRoot);+ const app = await createInstallApp(db);++ expect(existsSync(path.join(fixture.distDir, "manifest.js"))).toBe(false);++ const res = await request(app)+ .post("/api/plugins/install")+ .send({ packageName: fixture.packageRoot, isLocalPath: true });++ expect(res.status).toBe(200);+ expect(res.body.packageName).toBe(fixture.packageName);+ expect(res.body.pluginKey).toBe(fixture.pluginKey);+ expect(existsSync(path.join(fixture.distDir, "manifest.js"))).toBe(true);+ expect(existsSync(path.join(fixture.distDir, "worker.js"))).toBe(true);+ expect(existsSync(path.join(fixture.distDir, "ui", "index.js"))).toBe(true);+ expect(mockLifecycle.load).toHaveBeenCalledTimes(1);+ }, 60_000);++ it("auto-builds standalone bundled local plugins outside the root pnpm workspace", async () => {+ const fixture = await createBundledPluginFixture("standalone-success", { rootDir: standaloneRepoPluginRoot });+ cleanupPaths.add(fixture.packageRoot);+ const app = await createInstallApp(db);++ expect(existsSync(path.join(fixture.distDir, "manifest.js"))).toBe(false);+ expect(existsSync(path.join(fixture.packageRoot, "node_modules"))).toBe(false);++ const res = await request(app)+ .post("/api/plugins/install")+ .send({ packageName: fixture.packageRoot, isLocalPath: true });++ expect(res.status).toBe(200);+ expect(res.body.packageName).toBe(fixture.packageName);+ expect(res.body.pluginKey).toBe(fixture.pluginKey);+ expect(existsSync(path.join(fixture.distDir, "manifest.js"))).toBe(true);+ expect(existsSync(path.join(fixture.distDir, "worker.js"))).toBe(true);+ expect(existsSync(path.join(fixture.distDir, "ui", "index.js"))).toBe(true);+ expect(existsSync(path.join(fixture.packageRoot, "node_modules", "@paperclipai", "plugin-sdk"))).toBe(true);+ expect(mockLifecycle.load).toHaveBeenCalledTimes(1);+ }, 60_000);++ it("bootstraps standalone bundled local plugin runtime dependencies when dist already exists", async () => {+ const fixture = await createBundledPluginFixture("standalone-runtime-success", {+ rootDir: standaloneRepoPluginRoot,+ buildDistImmediately: true,+ });+ cleanupPaths.add(fixture.packageRoot);+ const app = await createInstallApp(db);++ expect(existsSync(path.join(fixture.distDir, "manifest.js"))).toBe(true);+ expect(existsSync(path.join(fixture.packageRoot, "node_modules", "@paperclipai", "plugin-sdk"))).toBe(false);++ const res = await request(app)+ .post("/api/plugins/install")+ .send({ packageName: fixture.packageRoot, isLocalPath: true });++ expect(res.status).toBe(200);+ expect(res.body.packageName).toBe(fixture.packageName);+ expect(res.body.pluginKey).toBe(fixture.pluginKey);+ expect(existsSync(path.join(fixture.packageRoot, "node_modules", "@paperclipai", "plugin-sdk"))).toBe(true);+ expect(mockLifecycle.load).toHaveBeenCalledTimes(1);+ }, 60_000);++ it("returns the manual build command when auto-build is disabled and dist is missing", async () => {+ process.env["PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD"] = "1";+ const fixture = await createBundledPluginFixture("disabled");+ cleanupPaths.add(fixture.packageRoot);+ const app = await createInstallApp(db);++ const res = await request(app)+ .post("/api/plugins/install")+ .send({ packageName: fixture.packageRoot, isLocalPath: true });++ expect(res.status).toBe(400);+ expect(res.body.error).toContain("does not appear to be a Paperclip plugin (no manifest found)");+ expect(res.body.error).toContain(`pnpm --filter ${fixture.packageName} build`);+ expect(existsSync(path.join(fixture.distDir, "manifest.js"))).toBe(false);+ expect(mockLifecycle.load).not.toHaveBeenCalled();+ }, 20_000);++ it("returns the standalone bootstrap command when auto-build is disabled for sandbox-provider plugins", async () => {+ process.env["PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD"] = "1";+ const fixture = await createBundledPluginFixture("standalone-disabled", { rootDir: standaloneRepoPluginRoot });+ cleanupPaths.add(fixture.packageRoot);+ const app = await createInstallApp(db);++ const res = await request(app)+ .post("/api/plugins/install")+ .send({ packageName: fixture.packageRoot, isLocalPath: true });++ expect(res.status).toBe(400);+ expect(res.body.error).toContain("does not appear to be a Paperclip plugin (no manifest found)");+ expect(res.body.error).toContain(path.relative(REPO_ROOT, fixture.packageRoot));+ expect(res.body.error).toContain("pnpm install --ignore-workspace --no-lockfile && pnpm build");+ expect(existsSync(path.join(fixture.distDir, "manifest.js"))).toBe(false);+ expect(mockLifecycle.load).not.toHaveBeenCalled();+ }, 20_000);+});diff --git a/server/src/__tests__/plugin-routes-authz.test.ts b/server/src/__tests__/plugin-routes-authz.test.tsindex 460d1e4529..2f74a1aaa4 100644--- a/server/src/__tests__/plugin-routes-authz.test.ts+++ b/server/src/__tests__/plugin-routes-authz.test.ts@@ -147,7 +147,7 @@ describe.sequential("plugin install and upgrade authz", () => {expect(res.status).toBe(200);const packageNames = res.body.map((plugin: { packageName: string }) => plugin.packageName);const byPackageName = new Map(- res.body.map((plugin: { packageName: string; experimental: boolean }) => [plugin.packageName, plugin]),+ res.body.map((plugin: { packageName: string; experimental: boolean; hasBuiltEntrypoints: boolean }) => [plugin.packageName, plugin]),);expect(packageNames).toContain("@paperclipai/plugin-workspace-diff");expect(packageNames).toContain("@paperclipai/plugin-llm-wiki");@@ -158,6 +158,7 @@ describe.sequential("plugin install and upgrade authz", () => {expect(byPackageName.get("@paperclipai/plugin-llm-wiki")?.experimental).toBe(true);expect(byPackageName.get("@paperclipai/plugin-modal")?.experimental).toBe(true);expect(byPackageName.get("@paperclipai/plugin-authoring-smoke-example")?.experimental).toBe(false);+ expect(typeof byPackageName.get("@paperclipai/plugin-workspace-diff")?.hasBuiltEntrypoints).toBe("boolean");}, 20_000);it("rejects plugin installation for non-admin board users", async () => {diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.tsindex 1c01bbba89..ed0f71a124 100644--- a/server/src/routes/plugins.ts+++ b/server/src/routes/plugins.ts@@ -47,7 +47,12 @@ import {} from "@paperclipai/shared";import { pluginRegistryService } from "../services/plugin-registry.js";import { pluginLifecycleManager } from "../services/plugin-lifecycle.js";-import { getPluginUiContributionMetadata, pluginLoader } from "../services/plugin-loader.js";+import {+ getPluginUiContributionMetadata,+ listMissingDeclaredPluginEntrypoints,+ pluginLoader,+ REPO_ROOT,+} from "../services/plugin-loader.js";import { logActivity } from "../services/activity-log.js";import { publishGlobalLiveEvent } from "../services/live-events.js";import { issueService } from "../services/issues.js";@@ -124,6 +129,7 @@ interface AvailableBundledPlugin {localPath: string;tag: "example" | "first-party";experimental: boolean;+ hasBuiltEntrypoints: boolean;}/** Response body for GET /api/plugins/:pluginId/health */@@ -152,13 +158,24 @@ const PLUGIN_SCOPED_API_RESPONSE_HEADER_ALLOWLIST = new Set([]);const __dirname = path.dirname(fileURLToPath(import.meta.url));-const REPO_ROOT = path.resolve(__dirname, "../../..");const EXPERIMENTAL_BUNDLED_PLUGIN_PACKAGE_NAMES = new Set(["@paperclipai/plugin-llm-wiki","@paperclipai/plugin-modal","@paperclipai/plugin-workspace-diff",]);-let bundledPluginsCache: Promise<AvailableBundledPlugin[]> | null = null;+/**+ * Cached bundled-plugin discovery. Static metadata (name, key, display, paths)+ * is expensive to compute and never changes at runtime, so it is cached. The+ * `hasBuiltEntrypoints` flag is filesystem state that flips when a plugin is+ * auto-built on install, so it is recomputed per request in `listBundledPlugins`+ * rather than cached.+ */+type DiscoveredBundledPlugin = {+ entry: Omit<AvailableBundledPlugin, "hasBuiltEntrypoints">;+ packageRoot: string;+ pkgJson: Record<string, unknown>;+};+let bundledPluginsCache: Promise<DiscoveredBundledPlugin[]> | null = null;function titleCasePluginName(packageName: string): string {const localName = packageName.split("/").pop() ?? packageName;@@ -266,9 +283,9 @@ function isExperimentalBundledPlugin(packageRoot: string, packageName: string):);}-async function discoverBundledPlugins(): Promise<AvailableBundledPlugin[]> {+async function discoverBundledPlugins(): Promise<DiscoveredBundledPlugin[]> {const pluginRoot = path.resolve(REPO_ROOT, "packages/plugins");- const bundledPlugins: AvailableBundledPlugin[] = [];+ const bundledPlugins: DiscoveredBundledPlugin[] = [];for (const packageJsonPath of await findPackageJsonFiles(pluginRoot)) {const packageRoot = path.dirname(packageJsonPath);const pkgJson = await readJsonFile(packageJsonPath);@@ -288,20 +305,24 @@ async function discoverBundledPlugins(): Promise<AvailableBundledPlugin[]> {const metadata = await bundledPluginMetadata(packageRoot, pkgJson);const tag = packageRoot.includes(`${path.sep}examples${path.sep}`) ? "example" : "first-party";bundledPlugins.push({- packageName,- pluginKey: metadata.pluginKey ?? packageName,- displayName: metadata.displayName ?? titleCasePluginName(packageName),- description: metadata.description- ?? `Bundled Paperclip plugin from ${path.relative(REPO_ROOT, packageRoot)}.`,- localPath: packageRoot,- tag,- experimental: isExperimentalBundledPlugin(packageRoot, packageName),+ entry: {+ packageName,+ pluginKey: metadata.pluginKey ?? packageName,+ displayName: metadata.displayName ?? titleCasePluginName(packageName),+ description: metadata.description+ ?? `Bundled Paperclip plugin from ${path.relative(REPO_ROOT, packageRoot)}.`,+ localPath: packageRoot,+ tag,+ experimental: isExperimentalBundledPlugin(packageRoot, packageName),+ },+ packageRoot,+ pkgJson,});}return bundledPlugins.sort((left, right) => {- if (left.tag !== right.tag) return left.tag === "first-party" ? -1 : 1;- return left.displayName.localeCompare(right.displayName);+ if (left.entry.tag !== right.entry.tag) return left.entry.tag === "first-party" ? -1 : 1;+ return left.entry.displayName.localeCompare(right.entry.displayName);});}@@ -310,7 +331,13 @@ async function listBundledPlugins(): Promise<AvailableBundledPlugin[]> {bundledPluginsCache = null;throw error;});- return bundledPluginsCache;+ const discovered = await bundledPluginsCache;+ // Recompute the filesystem-dependent flag per request so a plugin auto-built+ // during install is no longer reported as missing its entrypoints.+ return discovered.map(({ entry, packageRoot, pkgJson }) => ({+ ...entry,+ hasBuiltEntrypoints: listMissingDeclaredPluginEntrypoints(packageRoot, pkgJson).length === 0,+ }));}/**diff --git a/server/src/services/plugin-loader.ts b/server/src/services/plugin-loader.tsindex 0424f0b18e..d074af0408 100644--- a/server/src/services/plugin-loader.ts+++ b/server/src/services/plugin-loader.ts@@ -52,6 +52,11 @@ import { pluginDatabaseService } from "./plugin-database.js";const execFileAsync = promisify(execFile);const __dirname = path.dirname(fileURLToPath(import.meta.url));+export const REPO_ROOT = path.resolve(__dirname, "../../..");+export const BUNDLED_LOCAL_PLUGIN_ROOT = path.join(REPO_ROOT, "packages", "plugins");+export const STANDALONE_BUNDLED_PLUGIN_ROOT = path.join(BUNDLED_LOCAL_PLUGIN_ROOT, "sandbox-providers");+export const LOCAL_PLUGIN_AUTOBUILD_TIMEOUT_MS = 120_000;+const STANDALONE_BUNDLED_PLUGIN_SDK_PACKAGE = "@paperclipai/plugin-sdk";// ---------------------------------------------------------------------------// Constants@@ -184,6 +189,19 @@ export interface PluginDiscoveryResult {sources: PluginSource[];}+type PluginEntrypointKey = "manifest" | "worker" | "ui";++type PluginEntrypointPath = {+ key: PluginEntrypointKey;+ absolutePath: string;+};++type LocalPluginBuildCommand = {+ file: string;+ args: string[];+ cwd: string;+};+function getDeclaredPageRoutePaths(manifest: PaperclipPluginManifestV1): string[] {return (manifest.ui?.slots ?? []).filter((slot): slot is PluginUiSlotDeclaration => slot.type === "page" && typeof slot.routePath === "string" && slot.routePath.length > 0)@@ -595,6 +613,263 @@ async function readPackageJson(}}+function buildLocalPluginBuildCommand(pkgJson: Record<string, unknown>): string | null {+ const packageName = pkgJson["name"];+ if (typeof packageName !== "string" || packageName.trim().length === 0) return null;+ return `pnpm --filter ${packageName} build`;+}++function readPackageDependencyNames(+ pkgJson: Record<string, unknown>,+ field: "dependencies" | "optionalDependencies",+): string[] {+ const deps = pkgJson[field];+ if (deps === null || typeof deps !== "object" || Array.isArray(deps)) return [];+ return Object.keys(deps as Record<string, unknown>);+}++function resolvePackageInstallPath(packageRoot: string, packageName: string): string {+ return path.join(packageRoot, "node_modules", ...packageName.split("/"));+}++function isPathWithin(root: string, target: string): boolean {+ const relativePath = path.relative(root, target);+ return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));+}++export function isRepoBundledPluginPath(+ packageRoot: string,+ options: { repoRoot?: string } = {},+): boolean {+ const repoPluginsRoot = path.join(options.repoRoot ?? REPO_ROOT, "packages", "plugins");+ return isPathWithin(repoPluginsRoot, packageRoot);+}++export function isStandaloneBundledPluginPath(+ packageRoot: string,+ options: { repoRoot?: string } = {},+): boolean {+ const repoRoot = options.repoRoot ?? REPO_ROOT;+ return isPathWithin(path.join(repoRoot, "packages", "plugins", "sandbox-providers"), packageRoot);+}++export function resolveDeclaredPluginEntrypoints(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+): PluginEntrypointPath[] {+ const paperclipPlugin = pkgJson["paperclipPlugin"];+ if (+ paperclipPlugin === null+ || typeof paperclipPlugin !== "object"+ || Array.isArray(paperclipPlugin)+ ) {+ return [];+ }++ const entrypoints: PluginEntrypointPath[] = [];+ for (const key of ["manifest", "worker", "ui"] as const) {+ const relativePath = (paperclipPlugin as Record<string, unknown>)[key];+ if (typeof relativePath === "string" && relativePath.length > 0) {+ entrypoints.push({+ key,+ absolutePath: path.resolve(packageRoot, relativePath),+ });+ }+ }++ return entrypoints;+}++export function listMissingDeclaredPluginEntrypoints(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+): PluginEntrypointPath[] {+ return resolveDeclaredPluginEntrypoints(packageRoot, pkgJson).filter(+ (entrypoint) => !existsSync(entrypoint.absolutePath),+ );+}++function listMissingStandaloneBundledPluginRuntimeDependencies(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+): string[] {+ // optionalDependencies are intentionally allowed to be absent (e.g.+ // platform-specific packages), so they must not be treated as required here —+ // otherwise post-build verification fails even when install/build succeeded.+ const dependencyNames = new Set<string>([+ STANDALONE_BUNDLED_PLUGIN_SDK_PACKAGE,+ ...readPackageDependencyNames(pkgJson, "dependencies"),+ ]);++ return [...dependencyNames].filter(+ (packageName) => !existsSync(resolvePackageInstallPath(packageRoot, packageName)),+ );+}++function formatLocalPluginManualBuildHint(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+ options: { processEnv?: NodeJS.ProcessEnv; repoRoot?: string } = {},+): string {+ if (!isRepoBundledPluginPath(packageRoot, { repoRoot: options.repoRoot })) return "";++ const manualBuildCommand = buildLocalPluginRecoveryCommand(packageRoot, pkgJson, { repoRoot: options.repoRoot });+ if (!manualBuildCommand) return "";++ const autoBuildDisabled = (options.processEnv ?? process.env)["PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD"] === "1"+ ? " Auto-build is disabled by PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD=1."+ : "";++ return `${autoBuildDisabled} Run \`${manualBuildCommand}\` from the repo root and retry.`;+}++function buildStandaloneBundledPluginInstallArgs(+ packageRoot: string,+): string[] {+ const packageLockfilePath = path.join(packageRoot, "pnpm-lock.yaml");+ return existsSync(packageLockfilePath)+ ? ["install", "--ignore-workspace", "--frozen-lockfile"]+ : ["install", "--ignore-workspace", "--no-lockfile"];+}++function buildStandaloneBundledPluginInstallCommand(+ packageRoot: string,+): string {+ return `pnpm ${buildStandaloneBundledPluginInstallArgs(packageRoot).join(" ")}`;+}++function buildLocalPluginRecoveryCommand(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+ options: { repoRoot?: string } = {},+): string | null {+ if (isStandaloneBundledPluginPath(packageRoot, { repoRoot: options.repoRoot })) {+ const repoRoot = options.repoRoot ?? REPO_ROOT;+ const relativePath = path.relative(repoRoot, packageRoot) || ".";+ const installCommand = buildStandaloneBundledPluginInstallCommand(packageRoot);+ return `cd ${relativePath} && ${installCommand} && pnpm build`;+ }++ return buildLocalPluginBuildCommand(pkgJson);+}++function buildLocalPluginBuildCommands(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+ options: {+ repoRoot?: string;+ needsBuild?: boolean;+ needsStandaloneRuntimeBootstrap?: boolean;+ } = {},+): LocalPluginBuildCommand[] {+ if (isStandaloneBundledPluginPath(packageRoot, { repoRoot: options.repoRoot })) {+ const commands: LocalPluginBuildCommand[] = [];+ const shouldInstallStandaloneRuntime =+ options.needsStandaloneRuntimeBootstrap === true+ || (!existsSync(path.join(packageRoot, "node_modules")) && options.needsBuild !== false);++ if (shouldInstallStandaloneRuntime) {+ commands.push({+ file: "pnpm",+ args: buildStandaloneBundledPluginInstallArgs(packageRoot),+ cwd: packageRoot,+ });+ }++ if (options.needsBuild !== false) {+ commands.push({+ file: "pnpm",+ args: ["build"],+ cwd: packageRoot,+ });+ }+ return commands;+ }++ const packageName = pkgJson["name"];+ if (typeof packageName !== "string" || packageName.trim().length === 0) return [];+ return [{+ file: "pnpm",+ args: ["--filter", packageName, "build"],+ cwd: options.repoRoot ?? REPO_ROOT,+ }];+}++export async function ensureLocalPluginBuilt(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+ options: {+ processEnv?: NodeJS.ProcessEnv;+ repoRoot?: string;+ execFileAsyncImpl?: (+ file: string,+ args: readonly string[],+ options: { cwd: string; timeout: number },+ ) => Promise<{ stdout: string; stderr: string }>;+ } = {},+): Promise<void> {+ const processEnv = options.processEnv ?? process.env;+ if (processEnv["PAPERCLIP_DISABLE_PLUGIN_AUTOBUILD"] === "1") return;+ if (!isRepoBundledPluginPath(packageRoot, { repoRoot: options.repoRoot })) return;++ const missingEntrypoints = listMissingDeclaredPluginEntrypoints(packageRoot, pkgJson);+ const missingStandaloneRuntimeDeps = isStandaloneBundledPluginPath(packageRoot, { repoRoot: options.repoRoot })+ ? listMissingStandaloneBundledPluginRuntimeDependencies(packageRoot, pkgJson)+ : [];+ if (missingEntrypoints.length === 0 && missingStandaloneRuntimeDeps.length === 0) return;++ const packageName = pkgJson["name"];+ const manualBuildCommand = buildLocalPluginRecoveryCommand(packageRoot, pkgJson, { repoRoot: options.repoRoot });+ if (typeof packageName !== "string" || packageName.trim().length === 0 || !manualBuildCommand) return;++ const runExecFileAsync = options.execFileAsyncImpl ?? execFileAsync;+ const buildCommands = buildLocalPluginBuildCommands(packageRoot, pkgJson, {+ repoRoot: options.repoRoot,+ needsBuild: missingEntrypoints.length > 0,+ needsStandaloneRuntimeBootstrap: missingStandaloneRuntimeDeps.length > 0,+ });++ try {+ for (const command of buildCommands) {+ await runExecFileAsync(+ command.file,+ command.args,+ { cwd: command.cwd, timeout: LOCAL_PLUGIN_AUTOBUILD_TIMEOUT_MS },+ );+ }+ } catch (error) {+ const stderr = typeof (error as { stderr?: unknown }).stderr === "string"+ ? (error as { stderr: string }).stderr.trim()+ : "";+ const timeoutMessage = (error as { killed?: unknown }).killed === true+ ? ` after timing out at ${LOCAL_PLUGIN_AUTOBUILD_TIMEOUT_MS}ms`+ : "";+ const stderrMessage = stderr.length > 0 ? ` stderr: ${stderr}` : "";+ throw new Error(+ `Failed to auto-build bundled local plugin ${packageName}${timeoutMessage}. ` ++ `Run \`${manualBuildCommand}\` from the repo root and retry.${stderrMessage}`,+ );+ }++ const stillMissingEntrypoints = listMissingDeclaredPluginEntrypoints(packageRoot, pkgJson);+ const stillMissingStandaloneRuntimeDeps = isStandaloneBundledPluginPath(packageRoot, { repoRoot: options.repoRoot })+ ? listMissingStandaloneBundledPluginRuntimeDependencies(packageRoot, pkgJson)+ : [];+ if (stillMissingEntrypoints.length > 0 || stillMissingStandaloneRuntimeDeps.length > 0) {+ const missingDetails: string[] = [];+ if (stillMissingEntrypoints.length > 0) {+ missingDetails.push(`built entrypoints: ${stillMissingEntrypoints.map((entrypoint) => entrypoint.key).join(", ")}`);+ }+ if (stillMissingStandaloneRuntimeDeps.length > 0) {+ missingDetails.push(`runtime dependencies: ${stillMissingStandaloneRuntimeDeps.join(", ")}`);+ }+ throw new Error(+ `Bundled local plugin ${packageName} is still missing ${missingDetails.join("; ")} after auto-build. ` ++ `Run \`${manualBuildCommand}\` from the repo root and retry.`,+ );+ }+}+/*** Resolve the manifest entrypoint from a package.json and package root.*@@ -928,10 +1203,17 @@ export function pluginLoader(const pkgJson = await readPackageJson(resolvedPackagePath);if (!pkgJson) throw new Error(`Missing package.json at ${resolvedPackagePath}`);+ if (localPath) {+ await ensureLocalPluginBuilt(resolvedPackagePath, pkgJson);+ }+const manifestPath = resolveManifestPath(resolvedPackagePath, pkgJson);if (!manifestPath || !existsSync(manifestPath)) {+ const manualBuildHint = localPath+ ? formatLocalPluginManualBuildHint(resolvedPackagePath, pkgJson)+ : "";throw new Error(- `Package ${resolvedPackageName} at ${resolvedPackagePath} does not appear to be a Paperclip plugin (no manifest found).`,+ `Package ${resolvedPackageName} at ${resolvedPackagePath} does not appear to be a Paperclip plugin (no manifest found).${manualBuildHint}`,);}diff --git a/ui/src/api/plugins.ts b/ui/src/api/plugins.tsindex b018756091..0b32cfd845 100644--- a/ui/src/api/plugins.ts+++ b/ui/src/api/plugins.ts@@ -140,6 +140,7 @@ export interface AvailableBundledPlugin {localPath: string;tag: "example" | "first-party";experimental: boolean;+ hasBuiltEntrypoints: boolean;}export interface PluginLocalFolderProblem {diff --git a/ui/src/pages/PluginManager.tsx b/ui/src/pages/PluginManager.tsxindex 8f919e14da..3a89318614 100644--- a/ui/src/pages/PluginManager.tsx+++ b/ui/src/pages/PluginManager.tsx@@ -173,6 +173,11 @@ export function PluginManager() {const bundledPlugins = bundledQuery.data ?? [];const installedByPackageName = new Map(installedPlugins.map((plugin) => [plugin.packageName, plugin]));const bundledByPackageName = new Map(bundledPlugins.map((plugin) => [plugin.packageName, plugin]));+ // Scope the in-section banner to bundled (local-path) installs so an npm-dialog+ // install failure does not surface its error in the bundled-plugins section.+ const installErrorMessage = installMutation.variables?.isLocalPath+ ? installMutation.error?.message ?? null+ : null;const errorSummaryByPluginId = useMemo(() =>new Map(@@ -249,6 +254,12 @@ export function PluginManager() {<Badge variant="outline">Bundled</Badge></div>+ {installErrorMessage && (+ <div className="rounded-md border border-destructive/25 bg-destructive/[0.06] px-4 py-3 text-sm text-destructive whitespace-pre-wrap break-words">+ {installErrorMessage}+ </div>+ )}+{bundledQuery.isLoading ? (<div className="text-sm text-muted-foreground">Loading bundled plugins...</div>) : bundledQuery.error ? (@@ -293,6 +304,9 @@ export function PluginManager() {</div><p className="mt-1 text-sm text-muted-foreground">{bundledPlugin.description}</p><p className="mt-1 text-xs text-muted-foreground">{bundledPlugin.packageName}</p>+ {installPending && !bundledPlugin.hasBuiltEntrypoints && (+ <p className="mt-2 text-xs text-muted-foreground">Building plugin...</p>+ )}</div><div className="flex items-center gap-2 shrink-0">{installedPlugin ? (