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
[codex] Show bundled plugins in plugin manager (#6734)
Dottaf0ddd24d616a
diff --git a/server/src/__tests__/heartbeat-workspace-session.test.ts b/server/src/__tests__/heartbeat-workspace-session.test.tsindex 3c74475ec9..47282db0d1 100644--- a/server/src/__tests__/heartbeat-workspace-session.test.ts+++ b/server/src/__tests__/heartbeat-workspace-session.test.ts@@ -170,6 +170,8 @@ describe("mergeExecutionWorkspaceMetadataForPersistence", () => {provisionCommand: "bash ./scripts/provision.sh",},shouldReuseExisting: false,+ baseRef: null,+ baseRefSha: null,})).toEqual({source: "task_session",createdByRuntime: true,@@ -200,6 +202,8 @@ describe("mergeExecutionWorkspaceMetadataForPersistence", () => {provisionCommand: "bash ./scripts/new-provision.sh",},shouldReuseExisting: true,+ baseRef: null,+ baseRefSha: null,})).toEqual({config: {environmentId: "env-old",@@ -209,6 +213,25 @@ describe("mergeExecutionWorkspaceMetadataForPersistence", () => {createdByRuntime: false,});});++ it("records the resolved base ref SHA for newly realized workspaces", () => {+ expect(mergeExecutionWorkspaceMetadataForPersistence({+ existingMetadata: null,+ source: "task_session",+ createdByRuntime: true,+ configSnapshot: null,+ shouldReuseExisting: false,+ baseRef: "origin/main",+ baseRefSha: "abc1234567890",+ })).toEqual({+ source: "task_session",+ createdByRuntime: true,+ baseRefSnapshot: {+ baseRef: "origin/main",+ resolvedSha: "abc1234567890",+ },+ });+ });});describe("buildRealizedExecutionWorkspaceFromPersisted", () => {diff --git a/server/src/__tests__/plugin-routes-authz.test.ts b/server/src/__tests__/plugin-routes-authz.test.tsindex 272e20c357..9037199157 100644--- a/server/src/__tests__/plugin-routes-authz.test.ts+++ b/server/src/__tests__/plugin-routes-authz.test.ts@@ -139,6 +139,27 @@ describe.sequential("plugin install and upgrade authz", () => {vi.clearAllMocks();});+ it("lists bundled monorepo plugin packages", async () => {+ const { app } = await createApp(boardActor());++ const res = await request(app).get("/api/plugins/examples");++ 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]),+ );+ expect(packageNames).toContain("@paperclipai/plugin-workspace-diff");+ expect(packageNames).toContain("@paperclipai/plugin-llm-wiki");+ expect(packageNames).toContain("@paperclipai/plugin-modal");+ expect(packageNames).toContain("@paperclipai/plugin-authoring-smoke-example");+ expect(packageNames).not.toContain("@paperclipai/plugin-sdk");+ expect(byPackageName.get("@paperclipai/plugin-workspace-diff")?.experimental).toBe(true);+ 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);+ }, 20_000);+it("rejects plugin installation for non-admin board users", async () => {const { app, loader } = await createApp({type: "board",diff --git a/server/src/__tests__/workspace-runtime.test.ts b/server/src/__tests__/workspace-runtime.test.tsindex c605e45bbc..1423e1da1f 100644--- a/server/src/__tests__/workspace-runtime.test.ts+++ b/server/src/__tests__/workspace-runtime.test.ts@@ -62,6 +62,10 @@ async function runGit(cwd: string, args: string[]) {await execFileAsync("git", args, { cwd });}+async function readGit(cwd: string, args: string[]) {+ return (await execFileAsync("git", args, { cwd })).stdout.trim();+}+async function runPnpm(cwd: string, args: string[]) {await execFileAsync("pnpm", args, { cwd });}@@ -304,6 +308,57 @@ describe("ensureServerWorkspaceLinksCurrent", () => {});describe("realizeExecutionWorkspace", () => {+ it("defaults new git worktrees to freshly fetched origin/master", async () => {+ const sourceRepo = await createTempRepo("master");+ const remoteDir = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-remote-"));+ const remotePath = path.join(remoteDir, "paperclip.git");+ await execFileAsync("git", ["clone", "--bare", sourceRepo, remotePath]);++ const cloneRoot = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-clone-"));+ const repoRoot = path.join(cloneRoot, "paperclip");+ await execFileAsync("git", ["clone", remotePath, repoRoot]);+ await runGit(repoRoot, ["config", "user.email", "[email protected]"]);+ await runGit(repoRoot, ["config", "user.name", "Paperclip Test"]);++ await fs.writeFile(path.join(sourceRepo, "auth-fix.txt"), "cookie fix\n", "utf8");+ await runGit(sourceRepo, ["add", "auth-fix.txt"]);+ await runGit(sourceRepo, ["commit", "-m", "Add auth fix"]);+ await runGit(sourceRepo, ["push", remotePath, "master"]);+ const expectedRemoteHead = await readGit(sourceRepo, ["rev-parse", "master"]);+ expect(await readGit(repoRoot, ["rev-parse", "origin/master"])).not.toBe(expectedRemoteHead);++ const workspace = await realizeExecutionWorkspace({+ base: {+ baseCwd: repoRoot,+ source: "project_primary",+ projectId: "project-1",+ workspaceId: "workspace-1",+ repoUrl: null,+ repoRef: null,+ },+ config: {+ workspaceStrategy: {+ type: "git_worktree",+ branchTemplate: "{{issue.identifier}}-{{slug}}",+ },+ },+ issue: {+ id: "issue-1",+ identifier: "PAP-447",+ title: "Add Worktree Support",+ },+ agent: {+ id: "agent-1",+ name: "Codex Coder",+ companyId: "company-1",+ },+ });++ expect(workspace.baseRefSha).toBe(expectedRemoteHead);+ expect(await readGit(repoRoot, ["rev-parse", "origin/master"])).toBe(expectedRemoteHead);+ expect(await readGit(workspace.cwd, ["rev-parse", "HEAD"])).toBe(expectedRemoteHead);+ });+it("creates and reuses a git worktree for an issue-scoped branch", async () => {const repoRoot = await createTempRepo();@@ -372,6 +427,75 @@ describe("realizeExecutionWorkspace", () => {expect(second.branchName).toBe(first.branchName);});+ it("warns when reusing a git worktree whose base ref has advanced", async () => {+ const repoRoot = await createTempRepo();++ const initial = await realizeExecutionWorkspace({+ base: {+ baseCwd: repoRoot,+ source: "project_primary",+ projectId: "project-1",+ workspaceId: "workspace-1",+ repoUrl: null,+ repoRef: "main",+ },+ config: {+ workspaceStrategy: {+ type: "git_worktree",+ branchTemplate: "{{issue.identifier}}-{{slug}}",+ },+ },+ issue: {+ id: "issue-1",+ identifier: "PAP-447",+ title: "Add Worktree Support",+ },+ agent: {+ id: "agent-1",+ name: "Codex Coder",+ companyId: "company-1",+ },+ });+ expect(initial.baseRefSha).toMatch(/^[0-9a-f]{40}$/);++ await fs.writeFile(path.join(repoRoot, "server-auth-fix.txt"), "cookie fix\n", "utf8");+ await runGit(repoRoot, ["add", "server-auth-fix.txt"]);+ await runGit(repoRoot, ["commit", "-m", "Add auth runtime fix"]);++ const reused = await realizeExecutionWorkspace({+ base: {+ baseCwd: repoRoot,+ source: "project_primary",+ projectId: "project-1",+ workspaceId: "workspace-1",+ repoUrl: null,+ repoRef: "main",+ },+ config: {+ workspaceStrategy: {+ type: "git_worktree",+ branchTemplate: "{{issue.identifier}}-{{slug}}",+ },+ },+ issue: {+ id: "issue-1",+ identifier: "PAP-447",+ title: "Add Worktree Support",+ },+ agent: {+ id: "agent-1",+ name: "Codex Coder",+ companyId: "company-1",+ },+ });++ expect(reused.created).toBe(false);+ expect(reused.cwd).toBe(initial.cwd);+ expect(reused.warnings).toEqual([+ expect.stringContaining("is behind main by 1 commit"),+ ]);+ });+it("rejects reusing an empty directory that only looks like a worktree because it sits inside the repo", async () => {const repoRoot = await createTempRepo();const branchName = "PAP-447-add-worktree-support";@@ -1773,7 +1897,7 @@ describe("realizeExecutionWorkspace", () => {config: {workspaceStrategy: {type: "git_worktree",- // No baseRef configured — should auto-detect "master"+ // No baseRef configured — should default to origin/master.},},issue: {@@ -1791,25 +1915,23 @@ describe("realizeExecutionWorkspace", () => {expect(workspace.strategy).toBe("git_worktree");expect(workspace.created).toBe(true);- // The worktree should have been created successfully (baseRef resolved to "master")+ // The worktree should have been created successfully from the canonical remote base.const worktreeOp = operations.find(op => op.phase === "worktree_prepare" && op.metadata?.created);expect(worktreeOp).toBeDefined();- expect(worktreeOp!.metadata!.baseRef).toBe("master");+ expect(worktreeOp!.metadata!.baseRef).toBe("origin/master");}, 10_000);it("auto-detects the default branch via symbolic-ref when origin/HEAD is set", async () => {- // Create a repo with "master" as default branch- const repoRoot = await createTempRepo("master");+ const repoRoot = await createTempRepo("main");- // Set up a bare remote and pushconst bareRemote = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-worktree-bare-symref-"));await runGit(bareRemote, ["init", "--bare"]);await runGit(repoRoot, ["remote", "add", "origin", bareRemote]);- await runGit(repoRoot, ["push", "-u", "origin", "master"]);+ await runGit(repoRoot, ["push", "-u", "origin", "main", "master"]);await runGit(repoRoot, ["fetch", "origin"]);// Explicitly set refs/remotes/origin/HEAD to exercise the symbolic-ref path// (git remote set-head -a requires the remote to advertise HEAD, so we set it manually)- await runGit(repoRoot, ["remote", "set-head", "origin", "master"]);+ await runGit(repoRoot, ["remote", "set-head", "origin", "main"]);const { recorder, operations } = createWorkspaceOperationRecorderDouble();@@ -1825,7 +1947,7 @@ describe("realizeExecutionWorkspace", () => {config: {workspaceStrategy: {type: "git_worktree",- // No baseRef configured — should auto-detect "master" via symbolic-ref+ // No baseRef configured — origin/HEAD should win over fallback branches.},},issue: {@@ -1845,7 +1967,7 @@ describe("realizeExecutionWorkspace", () => {expect(workspace.created).toBe(true);const worktreeOp = operations.find(op => op.phase === "worktree_prepare" && op.metadata?.created);expect(worktreeOp).toBeDefined();- expect(worktreeOp!.metadata!.baseRef).toBe("master");+ expect(worktreeOp!.metadata!.baseRef).toBe("origin/main");}, 10_000);it("removes a created git worktree and branch during cleanup", async () => {diff --git a/server/src/routes/execution-workspaces.ts b/server/src/routes/execution-workspaces.tsindex ba2f9180f2..820b8fad30 100644--- a/server/src/routes/execution-workspaces.ts+++ b/server/src/routes/execution-workspaces.ts@@ -250,6 +250,7 @@ export function executionWorkspaceRoutes(db: Db) {repoUrl: existing.repoUrl,baseRef: existing.baseRef,branchName: existing.branchName,+ metadata: existing.metadata as Record<string, unknown> | null,config: {...existing.config,provisionCommand:diff --git a/server/src/routes/plugins.ts b/server/src/routes/plugins.tsindex d572c90d6f..c3f6265f0a 100644--- a/server/src/routes/plugins.ts+++ b/server/src/routes/plugins.ts@@ -18,7 +18,7 @@* @see doc/plugins/PLUGIN_SPEC.md for the full plugin specification*/-import { existsSync } from "node:fs";+import { access, readdir, readFile } from "node:fs/promises";import path from "node:path";import { randomUUID } from "node:crypto";import { fileURLToPath } from "node:url";@@ -114,13 +114,14 @@ interface PluginInstallRequest {isLocalPath?: boolean;}-interface AvailablePluginExample {+interface AvailableBundledPlugin {packageName: string;pluginKey: string;displayName: string;description: string;localPath: string;tag: "example" | "first-party";+ experimental: boolean;}/** Response body for GET /api/plugins/:pluginId/health */@@ -150,56 +151,164 @@ 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;++function titleCasePluginName(packageName: string): string {+ const localName = packageName.split("/").pop() ?? packageName;+ return localName+ .replace(/^paperclip-plugin-/, "")+ .replace(/^plugin-/, "")+ .split("-")+ .filter(Boolean)+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))+ .join(" ");+}++async function fileExists(filePath: string): Promise<boolean> {+ return access(filePath).then(() => true, () => false);+}++async function readJsonFile(filePath: string): Promise<Record<string, unknown> | null> {+ try {+ return JSON.parse(await readFile(filePath, "utf8")) as Record<string, unknown>;+ } catch {+ return null;+ }+}++async function findPackageJsonFiles(root: string, maxDepth = 4): Promise<string[]> {+ if (!(await fileExists(root))) return [];++ const packageJsonFiles: string[] = [];+ const walk = async (dir: string, depth: number): Promise<void> => {+ if (depth > maxDepth) return;++ const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);+ for (const entry of entries) {+ if (entry.name === "node_modules" || entry.name === "dist") continue;+ const entryPath = path.join(dir, entry.name);++ if (entry.isFile() && entry.name === "package.json") {+ packageJsonFiles.push(entryPath);+ } else if (entry.isDirectory()) {+ await walk(entryPath, depth + 1);+ }+ }+ };++ await walk(root, 0);+ return packageJsonFiles;+}++function manifestSourcePath(packageRoot: string, pkgJson: Record<string, unknown>): string | null {+ const paperclipPlugin = pkgJson.paperclipPlugin;+ if (+ !paperclipPlugin+ || typeof paperclipPlugin !== "object"+ || Array.isArray(paperclipPlugin)+ ) {+ return null;+ }++ const manifestPath = (paperclipPlugin as Record<string, unknown>).manifest;+ if (typeof manifestPath !== "string") return null;++ const sourcePath = manifestPath+ .replace(/^\.\/dist\//, "./src/")+ .replace(/\.js$/, ".ts");+ return path.resolve(packageRoot, sourcePath);+}++function firstStringLiteral(source: string, key: string): string | null {+ const match = source.match(+ new RegExp(`${key}:\\s*(?:"([^"]*)"|'([^']*)'|\`([^\`]*)\`)`, "s"),+ );+ return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;+}++async function bundledPluginMetadata(+ packageRoot: string,+ pkgJson: Record<string, unknown>,+): Promise<{ pluginKey?: string; displayName?: string; description?: string }> {+ const sourcePath = manifestSourcePath(packageRoot, pkgJson);+ if (!sourcePath || !(await fileExists(sourcePath))) return {};++ try {+ const source = await readFile(sourcePath, "utf8");+ const pluginId = source+ .match(/(?:export\s+)?const\s+PLUGIN_ID\s*=\s*(?:"([^"]*)"|'([^']*)'|`([^`]*)`)/)+ ?.slice(1)+ .find(Boolean)+ ?? firstStringLiteral(source, "id")+ ?? null;+ return {+ pluginKey: pluginId ?? undefined,+ displayName: firstStringLiteral(source, "displayName") ?? undefined,+ description: firstStringLiteral(source, "description") ?? undefined,+ };+ } catch {+ return {};+ }+}++function isExperimentalBundledPlugin(packageRoot: string, packageName: string): boolean {+ return (+ EXPERIMENTAL_BUNDLED_PLUGIN_PACKAGE_NAMES.has(packageName)+ || packageRoot.includes(`${path.sep}sandbox-providers${path.sep}`)+ || packageName.includes("sandbox")+ );+}++async function discoverBundledPlugins(): Promise<AvailableBundledPlugin[]> {+ const pluginRoot = path.resolve(REPO_ROOT, "packages/plugins");+ const bundledPlugins: AvailableBundledPlugin[] = [];+ for (const packageJsonPath of await findPackageJsonFiles(pluginRoot)) {+ const packageRoot = path.dirname(packageJsonPath);+ const pkgJson = await readJsonFile(packageJsonPath);+ const paperclipPlugin = pkgJson?.paperclipPlugin;+ if (+ !pkgJson+ || !paperclipPlugin+ || typeof paperclipPlugin !== "object"+ || Array.isArray(paperclipPlugin)+ ) {+ continue;+ }++ const packageName = pkgJson.name;+ if (typeof packageName !== "string" || packageName.length === 0) continue;++ 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),+ });+ }++ return bundledPlugins.sort((left, right) => {+ if (left.tag !== right.tag) return left.tag === "first-party" ? -1 : 1;+ return left.displayName.localeCompare(right.displayName);+ });+}-const BUNDLED_PLUGIN_EXAMPLES: AvailablePluginExample[] = [- {- packageName: "@paperclipai/plugin-workspace-diff",- pluginKey: "paperclip.workspace-diff",- displayName: "Workspace Changes",- description: "First-party workspace Changes tab backed by plugin-local Git diff computation.",- localPath: "packages/plugins/plugin-workspace-diff",- tag: "first-party",- },- {- packageName: "@paperclipai/plugin-hello-world-example",- pluginKey: "paperclip.hello-world-example",- displayName: "Hello World Widget (Example)",- description: "Reference UI plugin that adds a simple Hello World widget to the Paperclip dashboard.",- localPath: "packages/plugins/examples/plugin-hello-world-example",- tag: "example",- },- {- packageName: "@paperclipai/plugin-file-browser-example",- pluginKey: "paperclip-file-browser-example",- displayName: "File Browser (Example)",- description: "Example plugin that adds a Files link in project navigation plus a project detail file browser.",- localPath: "packages/plugins/examples/plugin-file-browser-example",- tag: "example",- },- {- packageName: "@paperclipai/plugin-kitchen-sink-example",- pluginKey: "paperclip-kitchen-sink-example",- displayName: "Kitchen Sink (Example)",- description: "Reference plugin that demonstrates the current Paperclip plugin API surface, bridge flows, UI extension surfaces, jobs, webhooks, tools, streams, and trusted local workspace/process demos.",- localPath: "packages/plugins/examples/plugin-kitchen-sink-example",- tag: "example",- },- {- packageName: "@paperclipai/plugin-orchestration-smoke-example",- pluginKey: "paperclipai.plugin-orchestration-smoke-example",- displayName: "Orchestration Smoke (Example)",- description: "Acceptance fixture for scoped plugin routes, restricted database namespaces, issue orchestration, documents, wakeups, summaries, and UI status surfaces.",- localPath: "packages/plugins/examples/plugin-orchestration-smoke-example",- tag: "example",- },-];--function listBundledPluginExamples(): AvailablePluginExample[] {- return BUNDLED_PLUGIN_EXAMPLES.flatMap((plugin) => {- const absoluteLocalPath = path.resolve(REPO_ROOT, plugin.localPath);- if (!existsSync(absoluteLocalPath)) return [];- return [{ ...plugin, localPath: absoluteLocalPath }];+async function listBundledPlugins(): Promise<AvailableBundledPlugin[]> {+ bundledPluginsCache ??= discoverBundledPlugins().catch((error: unknown) => {+ bundledPluginsCache = null;+ throw error;});+ return bundledPluginsCache;}/**@@ -677,12 +786,12 @@ export function pluginRoutes(/*** GET /api/plugins/examples*- * Return first-party example plugins bundled in this repo, if present.+ * Return plugin packages bundled in this repo, if present.* These can be installed through the normal local-path install flow.*/router.get("/plugins/examples", async (req, res) => {assertBoardOrgAccess(req);- res.json(listBundledPluginExamples());+ res.json(await listBundledPlugins());});// IMPORTANT: Static routes must come before parameterized routesdiff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex 8c34e99233..3464f833a2 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -87,6 +87,7 @@ import { logActivity, publishPluginDomainEvent, type LogActivityInput } from "./import {buildWorkspaceReadyComment,cleanupExecutionWorkspaceArtifacts,+ ensurePersistedExecutionWorkspaceAvailable,ensureRuntimeServicesForRun,persistAdapterManagedRuntimeServices,realizeExecutionWorkspace,@@ -594,6 +595,8 @@ export function mergeExecutionWorkspaceMetadataForPersistence(input: {createdByRuntime: boolean;configSnapshot: Record<string, unknown> | null;shouldReuseExisting: boolean;+ baseRef: string | null | undefined;+ baseRefSha: string | null | undefined;}) {const base = {...(input.existingMetadata ?? {}),@@ -601,6 +604,17 @@ export function mergeExecutionWorkspaceMetadataForPersistence(input: {createdByRuntime: input.createdByRuntime,} as Record<string, unknown>;+ const existingSnapshot = parseObject(base.baseRefSnapshot);+ if (+ typeof existingSnapshot.resolvedSha !== "string"+ && input.baseRefSha+ ) {+ base.baseRefSnapshot = {+ baseRef: input.baseRef ?? null,+ resolvedSha: input.baseRefSha,+ };+ }+if (input.shouldReuseExisting || !input.configSnapshot) {return base;}@@ -624,6 +638,8 @@ export function buildRealizedExecutionWorkspaceFromPersisted(input: {}const strategy = input.workspace.strategyType === "git_worktree" ? "git_worktree" : "project_primary";+ const baseRefSnapshot = parseObject(input.workspace.metadata?.baseRefSnapshot);+ const baseRefSha = typeof baseRefSnapshot.resolvedSha === "string" ? baseRefSnapshot.resolvedSha : null;return {baseCwd: input.base.baseCwd,source: input.workspace.mode === "shared_workspace" ? "project_primary" : "task_session",@@ -637,6 +653,7 @@ export function buildRealizedExecutionWorkspaceFromPersisted(input: {worktreePath: strategy === "git_worktree" ? (readNonEmptyString(input.workspace.providerRef) ?? cwd) : null,warnings: [],created: false,+ baseRefSha,};}@@ -7229,7 +7246,34 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})repoRef: resolvedWorkspace.repoRef,} satisfies ExecutionWorkspaceInput;const reusedExecutionWorkspace = shouldReuseExisting && existingExecutionWorkspace- ? buildRealizedExecutionWorkspaceFromPersisted({+ ? await ensurePersistedExecutionWorkspaceAvailable({+ base: executionWorkspaceBase,+ workspace: {+ mode: existingExecutionWorkspace.mode,+ strategyType: existingExecutionWorkspace.strategyType,+ cwd: existingExecutionWorkspace.cwd,+ providerRef: existingExecutionWorkspace.providerRef,+ projectId: existingExecutionWorkspace.projectId,+ projectWorkspaceId: existingExecutionWorkspace.projectWorkspaceId,+ repoUrl: existingExecutionWorkspace.repoUrl,+ baseRef: existingExecutionWorkspace.baseRef,+ branchName: existingExecutionWorkspace.branchName,+ metadata: existingExecutionWorkspace.metadata as Record<string, unknown> | null,+ config: {+ provisionCommand:+ existingExecutionWorkspace.config?.provisionCommand+ ?? projectExecutionWorkspacePolicy?.workspaceStrategy?.provisionCommand+ ?? null,+ },+ },+ issue: issueRef,+ agent: {+ id: agent.id,+ name: agent.name,+ companyId: agent.companyId,+ },+ recorder: workspaceOperationRecorder,+ }) ?? buildRealizedExecutionWorkspaceFromPersisted({base: executionWorkspaceBase,workspace: existingExecutionWorkspace,})@@ -7254,6 +7298,8 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})createdByRuntime: executionWorkspace.created,configSnapshot,shouldReuseExisting,+ baseRef: executionWorkspace.repoRef,+ baseRefSha: executionWorkspace.baseRefSha ?? null,});try {persistedExecutionWorkspace = shouldReuseExisting && existingExecutionWorkspacediff --git a/server/src/services/workspace-runtime.ts b/server/src/services/workspace-runtime.tsindex b601f495f5..4daf8523b0 100644--- a/server/src/services/workspace-runtime.ts+++ b/server/src/services/workspace-runtime.ts@@ -67,6 +67,7 @@ export interface RealizedExecutionWorkspace extends ExecutionWorkspaceInput {worktreePath: string | null;warnings: string[];created: boolean;+ baseRefSha?: string | null;}export interface RuntimeServiceRef {@@ -524,11 +525,110 @@ async function runGit(args: string[], cwd: string): Promise<string> {return proc.stdout.trim();}+function formatShortSha(value: string | null | undefined) {+ return value ? value.slice(0, 12) : "unknown";+}+function gitErrorIncludes(error: unknown, needle: string) {const message = error instanceof Error ? error.message : String(error);return message.toLowerCase().includes(needle.toLowerCase());}+function parseRemoteTrackingRef(ref: string): { remote: string; branch: string } | null {+ const trimmed = ref.trim();+ const refsRemotesPrefix = "refs/remotes/";+ const normalized = trimmed.startsWith(refsRemotesPrefix)+ ? trimmed.slice(refsRemotesPrefix.length)+ : trimmed;+ const slashIndex = normalized.indexOf("/");+ if (slashIndex <= 0 || slashIndex === normalized.length - 1) return null;+ const remote = normalized.slice(0, slashIndex);+ const branch = normalized.slice(slashIndex + 1);+ if (!/^[A-Za-z0-9._-]+$/.test(remote)) return null;+ return { remote, branch };+}++async function refreshRemoteTrackingBaseRef(repoRoot: string, baseRef: string): Promise<string[]> {+ const remoteTracking = parseRemoteTrackingRef(baseRef);+ if (!remoteTracking) return [];++ const remoteExists = await runGit(["remote", "get-url", remoteTracking.remote], repoRoot)+ .then(() => true)+ .catch(() => false);+ if (!remoteExists) return [];++ try {+ await runGit([+ "fetch",+ "--prune",+ remoteTracking.remote,+ `+refs/heads/${remoteTracking.branch}:refs/remotes/${remoteTracking.remote}/${remoteTracking.branch}`,+ ], repoRoot);+ return [];+ } catch (error) {+ const message = error instanceof Error ? error.message : String(error);+ return [`Could not refresh base ref ${baseRef} before preparing the execution workspace: ${message}`];+ }+}++async function resolveBaseRefSha(repoRoot: string, baseRef: string): Promise<string | null> {+ return await runGit(["rev-parse", "--verify", `${baseRef}^{commit}`], repoRoot).catch(() => null);+}++function readRecordedBaseRefSha(metadata: Record<string, unknown> | null | undefined): string | null {+ const snapshot = parseObject(metadata?.baseRefSnapshot);+ const resolvedSha = snapshot.resolvedSha;+ return typeof resolvedSha === "string" && resolvedSha.trim().length > 0 ? resolvedSha.trim() : null;+}++export async function inspectExecutionWorkspaceBaseDrift(input: {+ repoRoot: string;+ worktreePath: string;+ branchName: string | null;+ baseRef: string | null;+ recordedBaseRefSha?: string | null;+ skipRefresh?: boolean;+}): Promise<{+ warnings: string[];+ currentBaseRefSha: string | null;+ branchBaseRefSha: string | null;+}> {+ const baseRef = input.baseRef?.trim();+ if (!baseRef) {+ return { warnings: [], currentBaseRefSha: null, branchBaseRefSha: null };+ }++ const warnings = input.skipRefresh ? [] : await refreshRemoteTrackingBaseRef(input.repoRoot, baseRef);+ const currentBaseRefSha = await resolveBaseRefSha(input.repoRoot, baseRef);+ if (!currentBaseRefSha) {+ warnings.push(`Could not resolve base ref ${baseRef} while checking execution workspace freshness.`);+ return { warnings, currentBaseRefSha: null, branchBaseRefSha: null };+ }++ const branchBaseRefSha = await runGit(["merge-base", "HEAD", baseRef], input.worktreePath).catch(() => null);+ if (!branchBaseRefSha) {+ warnings.push(`Could not compare execution workspace ${input.branchName ?? "branch"} against base ref ${baseRef}.`);+ return { warnings, currentBaseRefSha, branchBaseRefSha: null };+ }++ if (branchBaseRefSha !== currentBaseRefSha) {+ const behindCountRaw = await runGit(["rev-list", "--count", `HEAD..${baseRef}`], input.worktreePath).catch(() => "");+ const behindCount = Number.parseInt(behindCountRaw, 10);+ const behindText = Number.isFinite(behindCount) && behindCount > 0+ ? `${behindCount} commit${behindCount === 1 ? "" : "s"}`+ : "newer commits";+ const recordedText = input.recordedBaseRefSha+ ? `recorded base ${formatShortSha(input.recordedBaseRefSha)}`+ : `merge-base ${formatShortSha(branchBaseRefSha)}`;+ warnings.push(+ `Execution workspace branch ${input.branchName ? `"${input.branchName}"` : "HEAD"} is behind ${baseRef} by ${behindText}: ${recordedText}, current base ${formatShortSha(currentBaseRefSha)}. Refresh or rebase the workspace before relying on recent base-branch fixes.`,+ );+ }++ return { warnings, currentBaseRefSha, branchBaseRefSha };+}++type GitWorktreeListEntry = {worktree: string;branch: string | null;@@ -597,16 +697,19 @@ async function detectDefaultBranch(repoRoot: string): Promise<string | null> {["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"],repoRoot,);- const branch = remoteHead?.startsWith("origin/") ? remoteHead.slice("origin/".length) : remoteHead;- if (branch) return branch;+ if (remoteHead) {+ await refreshRemoteTrackingBaseRef(repoRoot, remoteHead);+ if (await resolveBaseRefSha(repoRoot, remoteHead)) return remoteHead;+ }} catch {// Not set — fall through to heuristic}// Fallback: check for common default branch names on the remote- for (const candidate of ["main", "master"]) {+ for (const candidate of ["origin/master", "origin/main", "main", "master"]) {try {- await runGit(["rev-parse", "--verify", `refs/remotes/origin/${candidate}`], repoRoot);+ await refreshRemoteTrackingBaseRef(repoRoot, candidate);+ await runGit(["rev-parse", "--verify", `${candidate}^{commit}`], repoRoot);return candidate;} catch {// Not found — try next@@ -1003,6 +1106,7 @@ export async function realizeExecutionWorkspace(input: {worktreePath: null,warnings: [],created: false,+ baseRefSha: null,};}@@ -1026,10 +1130,20 @@ export async function realizeExecutionWorkspace(input: {const baseRef = configuredBaseRef?? await detectDefaultBranch(repoRoot)?? "HEAD";+ const baseRefreshWarnings = await refreshRemoteTrackingBaseRef(repoRoot, baseRef);+ const currentBaseRefSha = await resolveBaseRefSha(repoRoot, baseRef);await fs.mkdir(worktreeParentDir, { recursive: true });async function reuseExistingWorktree(reusablePath: string) {+ const baseDrift = await inspectExecutionWorkspaceBaseDrift({+ repoRoot,+ worktreePath: reusablePath,+ branchName,+ baseRef,+ recordedBaseRefSha: null,+ skipRefresh: true,+ });if (input.recorder) {await input.recorder.recordOperation({phase: "worktree_prepare",@@ -1039,6 +1153,8 @@ export async function realizeExecutionWorkspace(input: {worktreePath: reusablePath,branchName,baseRef,+ currentBaseRefSha: baseDrift.currentBaseRefSha,+ branchBaseRefSha: baseDrift.branchBaseRefSha,created: false,reused: true,},@@ -1066,8 +1182,9 @@ export async function realizeExecutionWorkspace(input: {cwd: reusablePath,branchName,worktreePath: reusablePath,- warnings: [],+ warnings: [...baseRefreshWarnings, ...baseDrift.warnings],created: false,+ baseRefSha: baseDrift.branchBaseRefSha ?? baseDrift.currentBaseRefSha,};}@@ -1109,6 +1226,7 @@ export async function realizeExecutionWorkspace(input: {worktreePath,branchName,baseRef,+ baseRefSha: currentBaseRefSha,created: true,},successMessage: `Created git worktree at ${worktreePath}\n`,@@ -1128,6 +1246,7 @@ export async function realizeExecutionWorkspace(input: {worktreePath,branchName,baseRef,+ baseRefSha: currentBaseRefSha,created: false,reusedExistingBranch: true,},@@ -1163,8 +1282,9 @@ export async function realizeExecutionWorkspace(input: {cwd: worktreePath,branchName,worktreePath,- warnings: [],+ warnings: baseRefreshWarnings,created: true,+ baseRefSha: currentBaseRefSha,};}@@ -1180,6 +1300,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {repoUrl: string | null | undefined;baseRef: string | null | undefined;branchName: string | null | undefined;+ metadata?: Record<string, unknown> | null;config?: {provisionCommand?: string | null;} | null;@@ -1205,15 +1326,26 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {worktreePath: strategy === "git_worktree" ? (input.workspace.providerRef ?? cwd) : null,warnings: [],created: false,+ baseRefSha: readRecordedBaseRefSha(input.workspace.metadata),};const provisionCommand = asString(input.workspace.config?.provisionCommand, "").trim();if (strategy !== "git_worktree") {return realized;}+ const repoRoot = await runGit(["rev-parse", "--show-toplevel"], input.base.baseCwd);+ const recordedBaseRefSha = readRecordedBaseRefSha(input.workspace.metadata);if (await directoryExists(cwd)) {+ const baseDrift = await inspectExecutionWorkspaceBaseDrift({+ repoRoot,+ worktreePath: realized.worktreePath ?? cwd,+ branchName: realized.branchName,+ baseRef: input.workspace.baseRef ?? input.base.repoRef ?? null,+ recordedBaseRefSha,+ });+ realized.warnings = baseDrift.warnings;+ realized.baseRefSha = recordedBaseRefSha ?? baseDrift.branchBaseRefSha ?? baseDrift.currentBaseRefSha;if (provisionCommand) {- const repoRoot = await runGit(["rev-parse", "--show-toplevel"], input.base.baseCwd);await provisionExecutionWorktree({strategy: {type: "git_worktree",@@ -1232,7 +1364,6 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {return realized;}- const repoRoot = await runGit(["rev-parse", "--show-toplevel"], input.base.baseCwd);const worktreePath = realized.worktreePath ?? cwd;const branchName = asString(input.workspace.branchName, "").trim();if (!branchName) {@@ -1241,6 +1372,9 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {await fs.mkdir(path.dirname(worktreePath), { recursive: true });await runGit(["worktree", "prune"], repoRoot).catch(() => {});+ const restoreBaseRef = input.workspace.baseRef ?? input.base.repoRef ?? null;+ const restoreRefreshWarnings = restoreBaseRef ? await refreshRemoteTrackingBaseRef(repoRoot, restoreBaseRef) : [];+ const restoreCurrentBaseRefSha = restoreBaseRef ? await resolveBaseRefSha(repoRoot, restoreBaseRef) : null;let created = false;try {@@ -1253,6 +1387,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {worktreePath,branchName,baseRef: input.workspace.baseRef ?? input.base.repoRef ?? null,+ currentBaseRefSha: restoreCurrentBaseRefSha,created: false,restored: true,},@@ -1268,6 +1403,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {throw error;}const baseRef = input.workspace.baseRef ?? await detectDefaultBranch(repoRoot) ?? "HEAD";+ const recreatedBaseRefSha = await resolveBaseRefSha(repoRoot, baseRef);await recordGitOperation(input.recorder, {phase: "worktree_prepare",args: ["worktree", "add", "-b", branchName, worktreePath, baseRef],@@ -1277,6 +1413,7 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {worktreePath,branchName,baseRef,+ baseRefSha: recreatedBaseRefSha,created: true,restored: true,},@@ -1286,6 +1423,15 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {created = true;}+ const baseDrift = await inspectExecutionWorkspaceBaseDrift({+ repoRoot,+ worktreePath,+ branchName,+ baseRef: input.workspace.baseRef ?? input.base.repoRef ?? null,+ recordedBaseRefSha,+ skipRefresh: true,+ });+await provisionExecutionWorktree({strategy: {type: "git_worktree",@@ -1305,7 +1451,12 @@ export async function ensurePersistedExecutionWorkspaceAvailable(input: {...realized,cwd: worktreePath,worktreePath,+ warnings: [...restoreRefreshWarnings, ...baseDrift.warnings],created,+ baseRefSha:+ recordedBaseRefSha+ ?? (created ? restoreCurrentBaseRefSha : baseDrift.branchBaseRefSha)+ ?? baseDrift.currentBaseRefSha,};}diff --git a/ui/src/api/plugins.ts b/ui/src/api/plugins.tsindex 9df0b93756..b018756091 100644--- a/ui/src/api/plugins.ts+++ b/ui/src/api/plugins.ts@@ -132,13 +132,14 @@ export interface PluginDashboardData {checkedAt: string;}-export interface AvailablePluginExample {+export interface AvailableBundledPlugin {packageName: string;pluginKey: string;displayName: string;description: string;localPath: string;tag: "example" | "first-party";+ experimental: boolean;}export interface PluginLocalFolderProblem {@@ -215,10 +216,10 @@ export const pluginsApi = {api.get<PluginRecord[]>(`/plugins${status ? `?status=${status}` : ""}`),/**- * List bundled example plugins available from the current repo checkout.+ * List bundled plugin packages available from the current repo checkout.*/- listExamples: () =>- api.get<AvailablePluginExample[]>("/plugins/examples"),+ listBundled: () =>+ api.get<AvailableBundledPlugin[]>("/plugins/examples"),/*** Fetch a single plugin record by its UUID or plugin key.diff --git a/ui/src/pages/PluginManager.tsx b/ui/src/pages/PluginManager.tsxindex ce73e25ca8..4293d76743 100644--- a/ui/src/pages/PluginManager.tsx+++ b/ui/src/pages/PluginManager.tsx@@ -43,6 +43,31 @@ function getPluginErrorSummary(plugin: PluginRecord): string {return firstNonEmptyLine(plugin.lastError) ?? "Plugin entered an error state without a stored error message.";}+function isExperimentalPluginIdentity(input: {+ packageName?: string | null;+ packagePath?: string | null;+ manifestJson?: PluginRecord["manifestJson"] | null;+ bundledExperimental?: boolean;+}) {+ if (input.bundledExperimental) return true;++ const packageName = input.packageName ?? "";+ const packagePath = input.packagePath ?? "";+ if (packageName.includes("sandbox") || packagePath.includes("sandbox")) return true;+ return input.manifestJson?.environmentDrivers?.some((driver) => driver.kind === "sandbox_provider") === true;+}++function ExperimentalBadge() {+ return (+ <Badge+ variant="outline"+ className="border-amber-500/30 bg-amber-500/10 text-amber-700 hover:bg-amber-500/10 dark:text-amber-200"+ >+ Experimental+ </Badge>+ );+}+/*** PluginManager page component.*@@ -85,9 +110,9 @@ export function PluginManager() {queryFn: () => pluginsApi.list(),});- const examplesQuery = useQuery({+ const bundledQuery = useQuery({queryKey: queryKeys.plugins.examples,- queryFn: () => pluginsApi.listExamples(),+ queryFn: () => pluginsApi.listBundled(),});const invalidatePluginQueries = () => {@@ -144,9 +169,9 @@ export function PluginManager() {});const installedPlugins = plugins ?? [];- const examples = examplesQuery.data ?? [];+ const bundledPlugins = bundledQuery.data ?? [];const installedByPackageName = new Map(installedPlugins.map((plugin) => [plugin.packageName, plugin]));- const examplePackageNames = new Set(examples.map((example) => example.packageName));+ const bundledByPackageName = new Map(bundledPlugins.map((plugin) => [plugin.packageName, plugin]));const errorSummaryByPluginId = useMemo(() =>new Map(@@ -223,30 +248,37 @@ export function PluginManager() {<Badge variant="outline">Bundled</Badge></div>- {examplesQuery.isLoading ? (+ {bundledQuery.isLoading ? (<div className="text-sm text-muted-foreground">Loading bundled plugins...</div>- ) : examplesQuery.error ? (+ ) : bundledQuery.error ? (<div className="text-sm text-destructive">Failed to load bundled plugins.</div>- ) : examples.length === 0 ? (+ ) : bundledPlugins.length === 0 ? (<div className="rounded-md border border-dashed px-4 py-3 text-sm text-muted-foreground">No bundled plugins were found in this checkout.</div>) : (<ul className="divide-y rounded-md border bg-card">- {examples.map((example) => {- const installedPlugin = installedByPackageName.get(example.packageName);+ {bundledPlugins.map((bundledPlugin) => {+ const installedPlugin = installedByPackageName.get(bundledPlugin.packageName);const installPending =installMutation.isPending &&installMutation.variables?.isLocalPath &&- installMutation.variables.packageName === example.localPath;+ installMutation.variables.packageName === bundledPlugin.localPath;return (- <li key={example.packageName}>+ <li key={bundledPlugin.packageName}><div className="flex items-center gap-4 px-4 py-3"><div className="min-w-0 flex-1"><div className="flex flex-wrap items-center gap-2">- <span className="font-medium">{example.displayName}</span>- <Badge variant="outline">{example.tag === "first-party" ? "First-party" : "Example"}</Badge>+ <span className="font-medium">{bundledPlugin.displayName}</span>+ <Badge variant="outline">+ {bundledPlugin.tag === "first-party" ? "First-party" : "Example"}+ </Badge>+ {isExperimentalPluginIdentity({+ packageName: bundledPlugin.packageName,+ packagePath: bundledPlugin.localPath,+ bundledExperimental: bundledPlugin.experimental,+ }) && <ExperimentalBadge />}{installedPlugin ? (<Badgevariant={installedPlugin.status === "ready" ? "default" : "secondary"}@@ -258,8 +290,8 @@ export function PluginManager() {<Badge variant="secondary">Not installed</Badge>)}</div>- <p className="mt-1 text-sm text-muted-foreground">{example.description}</p>- <p className="mt-1 text-xs text-muted-foreground">{example.packageName}</p>+ <p className="mt-1 text-sm text-muted-foreground">{bundledPlugin.description}</p>+ <p className="mt-1 text-xs text-muted-foreground">{bundledPlugin.packageName}</p></div><div className="flex items-center gap-2 shrink-0">{installedPlugin ? (@@ -286,12 +318,12 @@ export function PluginManager() {disabled={installPending || installMutation.isPending}onClick={() =>installMutation.mutate({- packageName: example.localPath,+ packageName: bundledPlugin.localPath,isLocalPath: true,})}>- {installPending ? "Installing..." : "Install Example"}+ {installPending ? "Installing..." : "Install"}</Button>)}</div>@@ -333,9 +365,19 @@ export function PluginManager() {>{plugin.manifestJson.displayName ?? plugin.packageName}</Link>- {examplePackageNames.has(plugin.packageName) && (- <Badge variant="outline">Example</Badge>+ {bundledByPackageName.has(plugin.packageName) && (+ <Badge variant="outline">+ {bundledByPackageName.get(plugin.packageName)?.tag === "first-party"+ ? "First-party"+ : "Example"}+ </Badge>)}+ {isExperimentalPluginIdentity({+ packageName: plugin.packageName,+ packagePath: plugin.packagePath,+ manifestJson: plugin.manifestJson,+ bundledExperimental: bundledByPackageName.get(plugin.packageName)?.experimental,+ }) && <ExperimentalBadge />}</div><div><p className="text-xs text-muted-foreground mt-0.5 truncate" title={plugin.packageName}>