@hachej/boring-workspace 0.1.17 → 0.1.18

package/dist/server.js

@@ -460,19 +460,12 @@ function createWorkspaceUiTools(uiBridge, opts = {}) {
 // src/server/plugins/piPackages.ts
 import {
   compactPiPackages,
-  mergePiPackageSources,
-  piPackageSourceKey,
   PI_PACKAGE_RESOURCE_FILTERS
 } from "@hachej/boring-agent/server";
 
 // src/server/plugins/defineServerPlugin.ts
-var ServerPluginError = class extends Error {
-  constructor(message) {
-    super(message);
-  }
-};
 function fail(pluginId, message) {
-  throw new ServerPluginError(`server plugin "${pluginId}": ${message}`);
+  throw new Error(`server plugin "${pluginId}": ${message}`);
 }
 function isUrl(value) {
   return value instanceof URL;
@@ -547,6 +540,26 @@ function validateProvisioning(pluginId, provisioning) {
       }
     }
   }
+  if (provisioning.nodePackages !== void 0) {
+    if (!Array.isArray(provisioning.nodePackages)) {
+      fail(pluginId, "provisioning.nodePackages must be an array when provided");
+    }
+    for (let i = 0; i < provisioning.nodePackages.length; i++) {
+      const spec = provisioning.nodePackages[i];
+      if (!spec || typeof spec !== "object") {
+        fail(pluginId, `provisioning.nodePackages[${i}] must be an object`);
+      }
+      if (!spec.id || typeof spec.id !== "string") {
+        fail(pluginId, `provisioning.nodePackages[${i}].id must be a non-empty string`);
+      }
+      if (!spec.packageName || typeof spec.packageName !== "string") {
+        fail(pluginId, `provisioning.nodePackages[${i}].packageName must be a non-empty string`);
+      }
+      if (!isPathLike(spec.packageRoot)) {
+        fail(pluginId, `provisioning.nodePackages[${i}].packageRoot must be a string or URL`);
+      }
+    }
+  }
   if (provisioning.python !== void 0) {
     if (!Array.isArray(provisioning.python)) {
       fail(pluginId, "provisioning.python must be an array when provided");
@@ -594,6 +607,16 @@ function validateServerPlugin(plugin) {
     }
     validatePiPackages(plugin.id, plugin.piPackages);
   }
+  if (plugin.extensionPaths !== void 0) {
+    if (!Array.isArray(plugin.extensionPaths)) {
+      fail(plugin.id, "extensionPaths must be an array when provided");
+    }
+    plugin.extensionPaths.forEach((path, index) => {
+      if (typeof path !== "string" || path.length === 0) {
+        fail(plugin.id, `extensionPaths[${index}] must be a non-empty string`);
+      }
+    });
+  }
   if (plugin.agentTools !== void 0) {
     if (!Array.isArray(plugin.agentTools)) {
       fail(plugin.id, "agentTools must be an array when provided");
@@ -614,75 +637,10 @@ function validateServerPlugin(plugin) {
 }
 function defineServerPlugin(plugin) {
   validateServerPlugin(plugin);
-  return Object.assign({}, plugin);
-}
-
-// src/server/plugins/composeServerPlugins.ts
-function compactPrompts(prompts) {
-  const text = prompts.map((prompt) => prompt?.trim()).filter((prompt) => Boolean(prompt)).join("\n\n");
-  return text || void 0;
-}
-function mergeProvisioning(contributions) {
-  const templateDirs = contributions.flatMap((entry) => entry?.templateDirs ?? []);
-  const python = contributions.flatMap((entry) => entry?.python ?? []);
-  if (templateDirs.length === 0 && python.length === 0) return void 0;
-  return {
-    ...templateDirs.length > 0 ? { templateDirs } : {},
-    ...python.length > 0 ? { python } : {}
-  };
-}
-function composeRoutes(routes) {
-  const routePlugins = routes.filter(
-    (route) => Boolean(route)
-  );
-  if (routePlugins.length === 0) return void 0;
-  return async (app) => {
-    for (const routes2 of routePlugins) {
-      await app.register(routes2);
-    }
-  };
-}
-function composeServerPlugins(options) {
-  const piPackages = compactPiPackages([
-    ...options.plugins.flatMap((plugin) => plugin.piPackages ?? []),
-    ...options.piPackages ?? []
-  ]);
-  const agentTools = [
-    ...options.plugins.flatMap((plugin) => plugin.agentTools ?? []),
-    ...options.agentTools ?? []
-  ];
-  const systemPrompt = compactPrompts([
-    ...options.plugins.map((plugin) => plugin.systemPrompt),
-    options.systemPrompt
-  ]);
-  const provisioning = mergeProvisioning([
-    ...options.plugins.map((plugin) => plugin.provisioning),
-    options.provisioning
-  ]);
-  const routes = composeRoutes([
-    ...options.plugins.map((plugin) => plugin.routes),
-    options.routes
-  ]);
-  const preservedUiStateKeys = [.../* @__PURE__ */ new Set([
-    ...options.plugins.flatMap((plugin) => plugin.preservedUiStateKeys ?? []),
-    ...options.preservedUiStateKeys ?? []
-  ])];
-  return defineServerPlugin({
-    id: options.id,
-    ...options.label !== void 0 ? { label: options.label } : {},
-    ...piPackages.length > 0 ? { piPackages } : {},
-    ...systemPrompt ? { systemPrompt } : {},
-    ...agentTools.length > 0 ? { agentTools } : {},
-    ...provisioning ? { provisioning } : {},
-    ...routes ? { routes } : {},
-    ...preservedUiStateKeys.length > 0 ? { preservedUiStateKeys } : {}
-  });
+  return { ...plugin };
 }
 
 // src/server/plugins/bootstrapServer.ts
-function collectPiPackages(plugins) {
-  return compactPiPackages(plugins.flatMap((plugin) => plugin.piPackages ?? []));
-}
 function bootstrapServer(options) {
   const excludedDefaults = new Set(options.excludeDefaults ?? []);
   const finalPlugins = [
@@ -704,7 +662,8 @@ function bootstrapServer(options) {
     }
   }
   const systemPromptAppend = finalPlugins.filter((p) => p.systemPrompt && p.systemPrompt.trim()).map((p) => p.systemPrompt.trim()).join("\n\n");
-  const piPackages = collectPiPackages(finalPlugins);
+  const piPackages = compactPiPackages(finalPlugins.flatMap((plugin) => plugin.piPackages ?? []));
+  const extensionPaths = finalPlugins.flatMap((p) => p.extensionPaths ?? []);
   const provisioningContributions = finalPlugins.filter((p) => p.provisioning).map((p) => ({ id: p.id, provisioning: p.provisioning }));
   const routeContributions = finalPlugins.filter((p) => p.routes).map((p) => ({ id: p.id, routes: p.routes }));
   const preservedUiStateKeys = [...new Set(finalPlugins.flatMap((p) => p.preservedUiStateKeys ?? []))];
@@ -712,21 +671,885 @@ function bootstrapServer(options) {
     registered: finalPlugins.map((p) => p.id),
     systemPromptAppend,
     piPackages,
+    extensionPaths,
     agentTools,
     provisioningContributions,
     routeContributions,
     preservedUiStateKeys
   };
 }
+
+// src/server/boringSystemPrompt.ts
+import { createRequire } from "module";
+import { dirname, join } from "path";
+var require2 = createRequire(import.meta.url);
+function resolveBoringPiRoot(override) {
+  if (override === null) return null;
+  if (override) return override;
+  try {
+    return dirname(require2.resolve("@hachej/boring-pi/package.json"));
+  } catch {
+    return null;
+  }
+}
+function buildDocsRefs(boringPiRoot) {
+  return [
+    {
+      topic: "Workflow + how-to + full plugin authoring reference",
+      path: join(boringPiRoot, "skills/boring-plugin-authoring/SKILL.md")
+    },
+    {
+      topic: "Panels (registration, dockview, layout)",
+      path: join(boringPiRoot, "references/workspace/panels.md")
+    },
+    {
+      topic: "Bridge / UI control (get_ui_state, exec_ui)",
+      path: join(boringPiRoot, "references/workspace/bridge.md")
+    },
+    {
+      topic: "Server plugins (defineServerPlugin, routes, agent tools)",
+      path: join(boringPiRoot, "references/workspace/plugins.md")
+    }
+  ];
+}
+function buildBoringSystemPrompt(opts) {
+  const verify = opts.verifyCommand;
+  const boringPiRoot = resolveBoringPiRoot(opts.boringPiRootOverride);
+  const steps = [];
+  let n = 0;
+  if (opts.scaffoldCommand) {
+    n += 1;
+    steps.push(
+      `**${n}. Scaffold.** Bash \`${opts.scaffoldCommand} <kebab-name> "$BORING_AGENT_WORKSPACE_ROOT"\` \u2014 writes canonical files under \`$BORING_AGENT_WORKSPACE_ROOT/.pi/extensions/<kebab-name>/\`. Read the generated \`package.json\` + \`front/index.tsx\`. Do NOT skip this or write from memory. Never \`cd\` to a parent repo or write plugins outside \`$BORING_AGENT_WORKSPACE_ROOT/.pi/extensions/\`.`
+    );
+  } else {
+    n += 1;
+    steps.push(
+      `**${n}. Read the \`boring-plugin-authoring\` skill** from the \`<location>\` listed under \`<available_skills>\` for the canonical \`package.json\` + \`front/index.tsx\` shape.`
+    );
+  }
+  n += 1;
+  steps.push(
+    opts.scaffoldCommand ? `**${n}. Edit the generated files to implement the request.** Keep the scaffold imports, \`definePlugin\` shape, and manifest layout; replace only placeholder content/ids/labels with the real implementation.` : `**${n}. Create or edit the plugin files to implement what the user asked for.** Use the boring-plugin-authoring skill as the canonical source for imports, the \`definePlugin\` call shape, and the manifest layout.`
+  );
+  n += 1;
+  if (verify) {
+    steps.push(
+      `**${n}. Verify.** Bash \`${verify} <kebab-name> "$BORING_AGENT_WORKSPACE_ROOT"\`. If it warns about empty/missing dirs, your files went to the wrong cwd. Fix issues and re-run until \`OK\`. Use after EVERY edit.`
+    );
+  } else {
+    steps.push(
+      `**${n}. Verify.** The boring-ui CLI is not available in this host, so do not invent CLI commands. Validate by re-reading the manifest/front files against the boring-plugin-authoring skill, then ask the user to run \`/reload\` and inspect reload diagnostics.`
+    );
+  }
+  n += 1;
+  steps.push(`**${n}. Ask the user to run \`/reload\`** to publish the change.`);
+  const docsBlock = boringPiRoot ? [
+    "## boring-ui plugin authoring documentation",
+    "Read these only when the user asks to build, modify, or debug a workspace plugin. Use your `read` tool with the absolute path; the agent runtime guarantees these files exist on the host:",
+    ...buildDocsRefs(boringPiRoot).map((r) => `- ${r.topic}: ${r.path}`),
+    "Follow .md cross-references when present (e.g. SKILL.md may link to a reference doc \u2014 read both)."
+  ].join("\n") : [
+    "## boring-ui plugin authoring documentation",
+    "The `boring-plugin-authoring` skill listed under `<available_skills>` is the authoritative reference (read its `<location>`). Additional reference docs (`panels.md`, `bridge.md`, `plugins.md`) are unavailable on this host \u2014 `@hachej/boring-pi` is not installed."
+  ].join("\n");
+  return [
+    "You are operating inside boring-ui. Workspace root: `$BORING_AGENT_WORKSPACE_ROOT`; plugin files go under `$BORING_AGENT_WORKSPACE_ROOT/.pi/extensions/<name>/`.",
+    [
+      "## Plugin authoring \u2014 required workflow",
+      "",
+      ...steps,
+      "",
+      "**Common hallucinations** \u2014 these names DO NOT EXIST in boring-ui and will silently fail; do not write them:",
+      "- API factories: `createPlugin`, `defineFrontPlugin`, `defineComponent` \u2014 use `definePlugin({id, panels, commands, ...})` from `@hachej/boring-workspace/plugin`.",
+      "- Imperative method names: `registerComponent`, `addPanel`, `registerCommand` (no `Panel`), `registerTab` \u2014 the actual names are `registerPanel`, `registerPanelCommand`, `registerLeftTab`, `registerSurfaceResolver` (and you usually express these declaratively, not as method calls).",
+      "- Import paths: `@hachej/boring-pi` (it's a skills package, not for code), `@boring-ui/*`, `@hachej/pi-sdk` \u2014 use `@hachej/boring-workspace/plugin` for front and `@hachej/boring-workspace/server` for server.",
+      '- File visualizers: for `.csv`/file-tree opens, import `WORKSPACE_OPEN_PATH_SURFACE_KIND` (and `PaneProps`) from `@hachej/boring-workspace/plugin`, read `request.target`, and fetch `/api/v1/files/raw?path=${encodeURIComponent(request.target)}`. Never import these from the root package, use `/workspace/read`, or string kind `"WORKSPACE_OPEN_PATH_SURFACE_KIND"`.',
+      "- Pi extension tools: `defineTool` and `export const tools` do NOT exist. Export `default function (pi) { pi.registerTool({ name, description, execute }) }`.",
+      '- Server/Pi tool method: `handler` \u2014 use `execute`. Return shape: `{ content: [{ type: "text", text }] }` (NEVER a bare string).',
+      "- Manifest values: `boring.server: true` \u2014 use `false`/omit for hot-reload user plugins, or a relative path string only for advanced boot-time/static server integration.",
+      "- File layout: files at the package root, or `src/` / `dist/` / `lib/` subdirectories \u2014 the scaffold's hot-reload layout (`front/index.tsx`, optional `agent/index.ts` declared in `pi.extensions`) is the one the workspace refreshes on `/reload`.",
+      "- Hot-reload agent tools: do NOT put them in `.pi/extensions/<name>/server/index.ts`; use `pi.extensions` instead. `boring.server` requires static composition plus process restart."
+    ].join("\n"),
+    docsBlock
+  ].join("\n\n");
+}
+
+// src/server/agentPlugins/manager.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync4, lstatSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync as realpathSync2, rmSync as rmSync2, statSync as statSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname5, isAbsolute as isAbsolute3, join as join4, relative as relative3, resolve as resolve4 } from "path";
+
+// src/shared/plugins/manifest.ts
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+var PLUGIN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+function isValidBoringPluginId(id) {
+  return typeof id === "string" && id.length > 0 && PLUGIN_ID_RE.test(id);
+}
+function isSafePluginRelativePath(value) {
+  return typeof value === "string" && value.length > 0 && value !== "." && !value.includes("\0") && !value.includes("\\") && !value.startsWith("/") && !value.startsWith("//") && !/^[A-Za-z]:[\\/]/.test(value) && !value.split("/").includes("..");
+}
+function issue(code, field, message) {
+  return { code, field, message };
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function validateStringArray(issues, value, field, pathLike) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push(issue("INVALID_FIELD", field, `${field} must be an array`));
+    return;
+  }
+  value.forEach((entry, index) => {
+    const itemField = `${field}[${index}]`;
+    if (typeof entry !== "string" || entry.length === 0) {
+      issues.push(issue("INVALID_FIELD", itemField, `${itemField} must be a non-empty string`));
+      return;
+    }
+    if (pathLike && !isSafePluginRelativePath(entry)) {
+      issues.push(issue("INVALID_PATH", itemField, `${itemField} must be a safe relative path`));
+    }
+  });
+}
+var REMOVED_BORING_UI_FIELDS = ["outputs", "panels", "commands", "leftTabs", "surfaceResolvers", "providers", "bindings", "catalogs"];
+function validateBoringField(issues, boring) {
+  if (boring === void 0) return void 0;
+  if (!isRecord(boring)) {
+    issues.push(issue("INVALID_FIELD", "boring", "boring must be an object when provided"));
+    return void 0;
+  }
+  for (const field of REMOVED_BORING_UI_FIELDS) {
+    if (boring[field] !== void 0) {
+      issues.push(issue(
+        "INVALID_FIELD",
+        `boring.${field}`,
+        `boring.${field} is not supported; declare front contributions in boring.front via definePlugin({ ... })`
+      ));
+    }
+  }
+  if (boring.id !== void 0) {
+    issues.push(issue("INVALID_FIELD", "boring.id", "boring.id is not supported; package discovery identity comes from package.json#name"));
+  }
+  const front = boring.front;
+  if (front !== void 0 && (typeof front !== "string" || !isSafePluginRelativePath(front))) {
+    issues.push(issue("INVALID_PATH", "boring.front", "boring.front must be a safe relative path"));
+  }
+  const server = boring.server;
+  if (server !== void 0 && server !== false && (typeof server !== "string" || !isSafePluginRelativePath(server))) {
+    issues.push(issue("INVALID_PATH", "boring.server", "boring.server must be a safe relative path or false"));
+  }
+  if (boring.label !== void 0 && typeof boring.label !== "string") {
+    issues.push(issue("INVALID_FIELD", "boring.label", "boring.label must be a string when provided"));
+  }
+  return {
+    ...typeof boring.front === "string" ? { front: boring.front } : {},
+    ...typeof boring.server === "string" || boring.server === false ? { server: boring.server } : {},
+    ...typeof boring.label === "string" ? { label: boring.label } : {}
+  };
+}
+var REMOTE_PI_PACKAGE_PREFIXES = ["npm:", "git:", "github:", "http:", "https:", "ssh:"];
+function isRemotePiPackageSource(value) {
+  return REMOTE_PI_PACKAGE_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+function isSafePiPackageSource(value) {
+  if (value.length === 0) return false;
+  if (isRemotePiPackageSource(value)) return true;
+  const path = value.startsWith("file:") ? value.slice("file:".length) : value;
+  if (path === "." || path === "./") return true;
+  const normalized = path.startsWith("./") ? path.slice(2) : path;
+  return isSafePluginRelativePath(normalized);
+}
+function validatePiPackages2(issues, value) {
+  if (value === void 0) return;
+  if (!Array.isArray(value)) {
+    issues.push(issue("INVALID_FIELD", "pi.packages", "pi.packages must be an array when provided"));
+    return;
+  }
+  value.forEach((entry, index) => {
+    const field = `pi.packages[${index}]`;
+    if (typeof entry === "string") {
+      if (!isSafePiPackageSource(entry)) {
+        issues.push(issue("INVALID_PATH", field, `${field} must be a safe package source`));
+      }
+      return;
+    }
+    if (!isRecord(entry)) {
+      issues.push(issue("INVALID_FIELD", field, `${field} must be a string or package source object`));
+      return;
+    }
+    if (typeof entry.source !== "string" || entry.source.length === 0) {
+      issues.push(issue("INVALID_FIELD", `${field}.source`, `${field}.source must be a non-empty string`));
+    } else if (!isSafePiPackageSource(entry.source)) {
+      issues.push(issue("INVALID_PATH", `${field}.source`, `${field}.source must be a safe package source`));
+    }
+  });
+}
+function validatePiField(issues, pi) {
+  if (pi === void 0) return void 0;
+  if (!isRecord(pi)) {
+    issues.push(issue("INVALID_FIELD", "pi", "pi must be an object when provided"));
+    return void 0;
+  }
+  validateStringArray(issues, pi.extensions, "pi.extensions", true);
+  validateStringArray(issues, pi.skills, "pi.skills", true);
+  validatePiPackages2(issues, pi.packages);
+  if (pi.systemPrompt !== void 0 && typeof pi.systemPrompt !== "string") {
+    issues.push(issue("INVALID_FIELD", "pi.systemPrompt", "pi.systemPrompt must be a string when provided"));
+  }
+  return pi;
+}
+function validateBoringPluginManifest(raw) {
+  const issues = [];
+  if (!isRecord(raw)) {
+    return {
+      valid: false,
+      issues: [issue("INVALID_FIELD", "<root>", "package.json manifest must be an object")]
+    };
+  }
+  if (raw.name !== void 0 && typeof raw.name !== "string") {
+    issues.push(issue("INVALID_FIELD", "name", "name must be a string when provided"));
+  }
+  if (raw.version !== void 0 && typeof raw.version !== "string") {
+    issues.push(issue("INVALID_VERSION", "version", "version must be a string when provided"));
+  } else if (typeof raw.version === "string" && raw.version.length > 0 && !SEMVER_RE.test(raw.version)) {
+    issues.push(issue("INVALID_VERSION", "version", "version must be a valid semver string"));
+  }
+  const boring = validateBoringField(issues, raw.boring);
+  const pi = validatePiField(issues, raw.pi);
+  if (!boring && !pi) {
+    issues.push(issue("MISSING_REQUIRED_FIELD", "boring|pi", "package.json must include boring and/or pi plugin metadata"));
+  }
+  if (issues.length > 0) return { valid: false, issues };
+  return {
+    valid: true,
+    packageJson: {
+      ...typeof raw.name === "string" ? { name: raw.name } : {},
+      ...typeof raw.version === "string" ? { version: raw.version } : {},
+      ...boring ? { boring } : {},
+      ...pi ? { pi } : {}
+    }
+  };
+}
+
+// src/server/agentPlugins/scan.ts
+import { existsSync as existsSync2, readdirSync, readFileSync, statSync } from "fs";
+import { basename, dirname as dirname3, join as join2, resolve as resolve3 } from "path";
+
+// src/server/agentPlugins/pluginPaths.ts
+import { existsSync, realpathSync } from "fs";
+import { dirname as dirname2, isAbsolute as isAbsolute2, relative as relative2, resolve as resolve2 } from "path";
+function isInsideRoot(rootReal, targetReal) {
+  const rel = relative2(rootReal, targetReal);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+}
+function nearestExistingAncestor(path, rootDir) {
+  let current = path;
+  const root = resolve2(rootDir);
+  while (!existsSync(current)) {
+    const parent = dirname2(current);
+    if (parent === current) return void 0;
+    if (!isInsideRoot(root, parent) && parent !== root) return void 0;
+    current = parent;
+  }
+  return current;
+}
+function resolveContainedPluginPath(rootDir, value, options = {}) {
+  if (!value || !isSafePluginRelativePath(value)) return void 0;
+  if (!existsSync(rootDir)) return void 0;
+  const root = resolve2(rootDir);
+  const resolved = resolve2(root, value);
+  const rootReal = realpathSync(root);
+  const existing = nearestExistingAncestor(resolved, root);
+  if (!existing) return void 0;
+  const existingReal = realpathSync(existing);
+  if (!isInsideRoot(rootReal, existingReal)) return void 0;
+  if (!existsSync(resolved)) return options.mustExist ? void 0 : resolved;
+  const resolvedReal = realpathSync(resolved);
+  if (!isInsideRoot(rootReal, resolvedReal)) return void 0;
+  return resolvedReal;
+}
+
+// src/server/agentPlugins/scan.ts
+function pluginIdFromPackageJson(pkg, rootDir) {
+  const name = typeof pkg.name === "string" && pkg.name.trim() ? pkg.name.trim() : void 0;
+  return (name ?? rootDir.split(/[\\/]/).at(-1) ?? "plugin").replace(/^@/, "").replaceAll("/", "-");
+}
+function safePluginIdFromPackageJson(pkg, rootDir) {
+  const id = pluginIdFromPackageJson(pkg, rootDir);
+  return isValidBoringPluginId(id) ? id : void 0;
+}
+function parsePackageJson(rootDir) {
+  return JSON.parse(readFileSync(join2(rootDir, "package.json"), "utf8"));
+}
+function hasPluginMetadata(pkg) {
+  return pkg.boring !== void 0 || pkg.pi !== void 0;
+}
+function resolvePluginPath(rootDir, value, options = {}) {
+  return resolveContainedPluginPath(rootDir, value, options);
+}
+function resolvePluginPaths(rootDir, values) {
+  return (values ?? []).map((value) => resolvePluginPath(rootDir, value)).filter((value) => Boolean(value));
+}
+function pathPreflightIssue(rootDir, value, field, options = {}) {
+  if (!value || !isSafePluginRelativePath(value)) return void 0;
+  const containedPath = resolveContainedPluginPath(rootDir, value);
+  if (!containedPath) {
+    return {
+      pluginDir: rootDir,
+      code: "INVALID_PLUGIN_METADATA",
+      message: `${field}: resolved path escapes plugin root`
+    };
+  }
+  if (options.mustExist && !existsSync2(containedPath)) {
+    return {
+      pluginDir: rootDir,
+      code: "INVALID_PLUGIN_METADATA",
+      message: `${field}: declared path does not exist: ${value}`
+    };
+  }
+  return void 0;
+}
+function packagePathContainmentIssues(rootDir, pkg) {
+  const issues = [];
+  const boring = pkg.boring;
+  const pi = pkg.pi;
+  const pluginId = safePluginIdFromPackageJson(pkg, rootDir);
+  const push = (issue2) => {
+    if (issue2) issues.push({ ...issue2, ...pluginId ? { pluginId } : {} });
+  };
+  push(pathPreflightIssue(rootDir, boring?.front, "boring.front", { mustExist: true }));
+  if (boring?.server !== false && boring?.server !== void 0) {
+    push(pathPreflightIssue(rootDir, boring.server, "boring.server"));
+  }
+  pi?.extensions?.forEach((value, index) => push(pathPreflightIssue(rootDir, value, `pi.extensions[${index}]`)));
+  pi?.skills?.forEach((value, index) => push(pathPreflightIssue(rootDir, value, `pi.skills[${index}]`)));
+  return issues;
+}
+function discoverBoringPluginDirs(pluginDirs) {
+  const out = /* @__PURE__ */ new Set();
+  const missingPackageJson = [];
+  for (const raw of pluginDirs) {
+    const dir = resolve3(raw);
+    if (!existsSync2(dir)) continue;
+    const info = statSync(dir);
+    if (!info.isDirectory()) continue;
+    const hasPackageJson = existsSync2(join2(dir, "package.json"));
+    const childPackageDirs = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      const child = join2(dir, entry.name);
+      if (existsSync2(join2(child, "package.json"))) childPackageDirs.push(child);
+    }
+    if (hasPackageJson) out.add(dir);
+    for (const child of childPackageDirs) out.add(child);
+    if (!hasPackageJson && childPackageDirs.length === 0 && basename(dir) !== "extensions") {
+      missingPackageJson.push(dir);
+    }
+  }
+  return { dirs: [...out].sort(), missingPackageJson: [...new Set(missingPackageJson)].sort() };
+}
+function scanBoringPlugins(pluginDirs) {
+  const errors = [];
+  const plugins = [];
+  const seenIds = /* @__PURE__ */ new Map();
+  const discovered = discoverBoringPluginDirs(pluginDirs);
+  for (const pluginDir of discovered.missingPackageJson) {
+    errors.push({ pluginDir, code: "MISSING_PACKAGE_JSON", message: "package.json is missing" });
+  }
+  for (const rootDir of discovered.dirs) {
+    let raw;
+    try {
+      raw = parsePackageJson(rootDir);
+    } catch (error) {
+      errors.push({
+        pluginDir: rootDir,
+        code: "INVALID_PACKAGE_JSON",
+        message: error instanceof Error ? error.message : "invalid package.json"
+      });
+      continue;
+    }
+    if (!hasPluginMetadata(raw)) continue;
+    const result = validateBoringPluginManifest(raw);
+    if (!result.valid) {
+      const pluginId = safePluginIdFromPackageJson(raw, rootDir);
+      for (const issue2 of result.issues) {
+        errors.push({
+          pluginDir: rootDir,
+          ...pluginId ? { pluginId } : {},
+          code: "INVALID_PLUGIN_METADATA",
+          message: `${issue2.field}: ${issue2.message}`
+        });
+      }
+      continue;
+    }
+    const id = pluginIdFromPackageJson(result.packageJson, rootDir);
+    let canAddPlugin = true;
+    if (!isValidBoringPluginId(id)) {
+      errors.push({
+        pluginDir: rootDir,
+        code: "INVALID_PLUGIN_METADATA",
+        message: `effective plugin id "${id}" must start with a letter or number and use only letters, numbers, dot, underscore, colon, or dash`
+      });
+      canAddPlugin = false;
+    } else {
+      const previous = seenIds.get(id);
+      if (previous) {
+        errors.push({
+          pluginDir: rootDir,
+          pluginId: id,
+          code: "INVALID_PLUGIN_METADATA",
+          message: `duplicate plugin id "${id}" also declared by ${previous}`
+        });
+        const previousPluginIndex = plugins.findIndex((plugin) => plugin.id === id);
+        if (previousPluginIndex >= 0) plugins.splice(previousPluginIndex, 1);
+        canAddPlugin = false;
+      } else {
+        seenIds.set(id, rootDir);
+      }
+    }
+    const containmentIssues = packagePathContainmentIssues(rootDir, result.packageJson);
+    if (containmentIssues.length > 0) {
+      errors.push(...containmentIssues);
+      canAddPlugin = false;
+    }
+    if (!canAddPlugin) continue;
+    const pkg = result.packageJson;
+    const boring = pkg.boring ?? {};
+    const pi = pkg.pi;
+    const frontPath = resolvePluginPath(rootDir, boring.front, { mustExist: true });
+    const serverPath = typeof boring.server === "string" ? resolvePluginPath(rootDir, boring.server) : void 0;
+    const version = pkg.version ?? "0.0.0";
+    const extensionPaths = resolvePluginPaths(rootDir, pi?.extensions);
+    const skillPaths = resolvePluginPaths(rootDir, pi?.skills);
+    plugins.push({
+      id,
+      rootDir,
+      version,
+      boring,
+      ...pi ? { pi } : {},
+      ...frontPath ? { frontPath, frontUrl: `/@fs/${frontPath}` } : {},
+      ...serverPath ? { serverPath } : {},
+      ...extensionPaths.length > 0 ? { extensionPaths } : {},
+      ...skillPaths.length > 0 ? { skillPaths } : {}
+    });
+  }
+  const preflight = { ok: errors.length === 0, errors };
+  return { preflight, plugins };
+}
+function preflightBoringPlugins(pluginDirs) {
+  return scanBoringPlugins(pluginDirs).preflight;
+}
+function readBoringPlugins(pluginDirs) {
+  const scan = scanBoringPlugins(pluginDirs);
+  return scan.preflight.ok ? scan.plugins : [];
+}
+
+// src/server/agentPlugins/signatureCache.ts
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync2, rmSync, statSync as statSync2, writeFileSync } from "fs";
+import { dirname as dirname4, join as join3 } from "path";
+var PLUGIN_SIGNATURE_CACHE_FILE = ".boring-signature.json";
+function pluginFileSignature(path) {
+  if (!path || !existsSync3(path)) return "missing";
+  const stat = statSync2(path);
+  return `${stat.mtimeMs}:${stat.size}`;
+}
+function cachePath(pluginRootDir) {
+  return join3(pluginRootDir, PLUGIN_SIGNATURE_CACHE_FILE);
+}
+function writePluginSignatureCache(pluginRootDir, payload) {
+  const full = {
+    version: 1,
+    serverSignature: payload.serverSignature,
+    loadedAt: payload.loadedAt ?? Date.now()
+  };
+  const path = cachePath(pluginRootDir);
+  mkdirSync(dirname4(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(full, null, 2)}
+`, "utf8");
+}
+function readPluginSignatureCache(pluginRootDir) {
+  const path = cachePath(pluginRootDir);
+  if (!existsSync3(path)) return null;
+  let raw;
+  try {
+    raw = readFileSync2(path, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed;
+  if (obj.version !== 1) return null;
+  const sig = obj.serverSignature;
+  if (sig !== null && typeof sig !== "string") return null;
+  const loadedAt = typeof obj.loadedAt === "number" ? obj.loadedAt : 0;
+  return { version: 1, serverSignature: sig, loadedAt };
+}
+function clearPluginSignatureCache(pluginRootDir) {
+  const path = cachePath(pluginRootDir);
+  if (existsSync3(path)) rmSync(path, { force: true });
+}
+
+// src/server/agentPlugins/manager.ts
+function preflightErrorId(pluginDir) {
+  return `preflight-${createHash("sha256").update(pluginDir).digest("hex").slice(0, 12)}`;
+}
+function directorySignature(root) {
+  if (!root || !existsSync4(root)) return "missing";
+  const hash = createHash("sha256");
+  const visited = /* @__PURE__ */ new Set();
+  let rootReal;
+  try {
+    rootReal = realpathSync2(root);
+  } catch {
+    return "missing";
+  }
+  visited.add(rootReal);
+  let count = 0;
+  const visit = (dir, depth) => {
+    if (depth > 8 || count > 5e4) return;
+    const entries = readdirSync2(dir, { withFileTypes: true }).filter((entry) => !entry.name.startsWith(".") && entry.name !== "node_modules").sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      count++;
+      const path = join4(dir, entry.name);
+      const rel = relative3(root, path);
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) {
+        let target;
+        try {
+          target = realpathSync2(path);
+        } catch {
+          continue;
+        }
+        if (visited.has(target)) {
+          hash.update(rel);
+          hash.update("symlink-cycle");
+          continue;
+        }
+        visited.add(target);
+        const targetStat = statSync3(target);
+        hash.update(rel);
+        hash.update("symlink:");
+        hash.update(target);
+        if (targetStat.isDirectory()) visit(target, depth + 1);
+        else if (targetStat.isFile()) {
+          hash.update(String(targetStat.mtimeMs));
+          hash.update(String(targetStat.size));
+        }
+        continue;
+      }
+      hash.update(rel);
+      hash.update(String(stat.mtimeMs));
+      hash.update(String(stat.size));
+      if (stat.isDirectory()) {
+        visit(path, depth + 1);
+      }
+    }
+  };
+  visit(root, 0);
+  return hash.digest("hex");
+}
+function pluginSignature(plugin) {
+  return createHash("sha256").update(JSON.stringify(plugin.boring)).update(JSON.stringify(plugin.pi ?? {})).update(plugin.version).update(plugin.frontPath ?? "").update(pluginFileSignature(plugin.frontPath)).update(directorySignature(plugin.frontPath ? dirname5(plugin.frontPath) : void 0)).update(directorySignature(join4(plugin.rootDir, "shared"))).update(plugin.serverPath ?? "").update(pluginFileSignature(plugin.serverPath)).update(directorySignature(plugin.serverPath ? dirname5(plugin.serverPath) : void 0)).update((plugin.extensionPaths ?? []).join("\0")).update((plugin.skillPaths ?? []).join("\0")).digest("hex");
+}
+function computeRequiresRestart(previous, next) {
+  if (!previous) return [];
+  const prevHasServer = !!previous.serverPath;
+  const nextHasServer = !!next.serverPath;
+  if (!prevHasServer && !nextHasServer) return [];
+  if (prevHasServer !== nextHasServer) return ["routes", "agentTools"];
+  const nextSig = pluginFileSignature(next.serverPath);
+  if (previous.serverSignature === nextSig) return [];
+  return ["routes", "agentTools"];
+}
+var BoringPluginAssetManager = class {
+  pluginDirs;
+  errorRoot;
+  loaded = /* @__PURE__ */ new Map();
+  revisions = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  loading = null;
+  reloadQueued = false;
+  constructor(options) {
+    this.pluginDirs = options.pluginDirs;
+    this.errorRoot = options.errorRoot ?? join4(process.cwd(), ".pi", "extensions");
+  }
+  preflight() {
+    return preflightBoringPlugins(this.pluginDirs);
+  }
+  list() {
+    return [...this.loaded.values()].map((plugin) => ({
+      id: plugin.id,
+      boring: plugin.boring,
+      ...plugin.pi ? { pi: plugin.pi } : {},
+      version: plugin.version,
+      revision: plugin.revision,
+      ...plugin.frontUrl ? { frontUrl: plugin.frontUrl } : {}
+    }));
+  }
+  getError(pluginId) {
+    const path = this.errorPath(pluginId);
+    if (!path || !existsSync4(path)) return null;
+    return readFileSync3(path, "utf8");
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  async load() {
+    if (this.loading) {
+      this.reloadQueued = true;
+      return this.loading;
+    }
+    this.loading = this.drainLoads().finally(() => {
+      this.loading = null;
+    });
+    return this.loading;
+  }
+  async drainLoads() {
+    let result;
+    do {
+      this.reloadQueued = false;
+      result = await this.doLoadOnce();
+    } while (this.reloadQueued);
+    return result;
+  }
+  async doLoadOnce() {
+    const scan = scanBoringPlugins(this.pluginDirs);
+    const nextPlugins = scan.plugins;
+    const nextIds = new Set(nextPlugins.map((plugin) => plugin.id));
+    const invalidPluginDirs = new Set(scan.preflight.errors.map((error) => resolve4(error.pluginDir)));
+    const events = [];
+    const errors = [];
+    this.collectPreflightErrors(scan.preflight, events, errors);
+    for (const id of [...this.loaded.keys()]) {
+      if (nextIds.has(id)) continue;
+      const previous = this.loaded.get(id);
+      if (previous && invalidPluginDirs.has(resolve4(previous.rootDir))) continue;
+      const revision = this.bumpRevision(id);
+      this.loaded.delete(id);
+      if (previous) {
+        try {
+          clearPluginSignatureCache(previous.rootDir);
+        } catch {
+        }
+      }
+      const event = { type: "boring.plugin.unload", id, revision };
+      events.push(event);
+      this.emit(event);
+    }
+    for (const plugin of nextPlugins) {
+      try {
+        const signature = pluginSignature(plugin);
+        const previous = this.loaded.get(plugin.id);
+        if (previous?.signature === signature) continue;
+        const revision = this.bumpRevision(plugin.id);
+        const serverSignature = plugin.serverPath ? pluginFileSignature(plugin.serverPath) : null;
+        const record = { ...plugin, revision, signature, serverSignature };
+        this.loaded.set(plugin.id, record);
+        this.clearError(plugin.id);
+        try {
+          writePluginSignatureCache(plugin.rootDir, { serverSignature });
+        } catch {
+        }
+        const requiresRestart = computeRequiresRestart(previous, plugin);
+        const event = {
+          type: "boring.plugin.load",
+          id: plugin.id,
+          boring: plugin.boring,
+          version: plugin.version,
+          revision,
+          ...plugin.frontUrl ? { frontUrl: plugin.frontUrl } : {},
+          ...requiresRestart.length > 0 ? { requiresRestart } : {}
+        };
+        events.push(event);
+        this.emit(event);
+      } catch (error) {
+        const revision = this.bumpRevision(plugin.id);
+        const message = error instanceof Error ? error.stack ?? error.message : String(error);
+        this.writeError(plugin.id, message);
+        const event = { type: "boring.plugin.error", id: plugin.id, revision, message };
+        errors.push({ id: plugin.id, revision, message });
+        events.push(event);
+        this.emit(event);
+      }
+    }
+    return { loaded: this.list(), events, errors };
+  }
+  collectPreflightErrors(preflight, events, errors) {
+    for (const error of preflight.errors) {
+      const id = error.pluginId ?? preflightErrorId(error.pluginDir);
+      const revision = this.bumpRevision(id);
+      const message = `${error.code}: ${error.message}
+
+Plugin dir: ${error.pluginDir}`;
+      const loadError = { id, revision, message };
+      errors.push(loadError);
+      this.writeError(id, message);
+      const event = { type: "boring.plugin.error", id, revision, message };
+      events.push(event);
+      this.emit(event);
+    }
+  }
+  bumpRevision(id) {
+    const next = (this.revisions.get(id) ?? 0) + 1;
+    this.revisions.set(id, next);
+    return next;
+  }
+  emit(event) {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(event);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`[BoringPluginAssetManager] listener threw on ${event.type} for ${event.id}: ${message}`);
+      }
+    }
+  }
+  errorPath(pluginId) {
+    if (!isValidBoringPluginId(pluginId)) return null;
+    const root = resolve4(this.errorRoot);
+    const path = resolve4(root, pluginId, ".error");
+    const rel = relative3(root, path);
+    if (rel.startsWith("..") || isAbsolute3(rel)) return null;
+    return path;
+  }
+  writeError(pluginId, message) {
+    const path = this.errorPath(pluginId);
+    if (!path) return;
+    mkdirSync2(dirname5(path), { recursive: true });
+    writeFileSync2(path, message, "utf8");
+  }
+  clearError(pluginId) {
+    const path = this.errorPath(pluginId);
+    if (path && existsSync4(path)) rmSync2(path, { force: true });
+  }
+};
+
+// src/server/agentPlugins/routes.ts
+function collectRestartWarnings(events) {
+  const warnings = [];
+  for (const event of events) {
+    if (event.type !== "boring.plugin.load") continue;
+    const surfaces = event.requiresRestart;
+    if (!surfaces || surfaces.length === 0) continue;
+    warnings.push({
+      id: event.id,
+      surfaces: [...surfaces],
+      message: `${event.id} reloaded \u2014 front bundle is live, but server-side ${surfaces.join(" + ")} were wired at boot and still run the old code. Stop and restart the workspace process (Ctrl-C, then re-run your dev command) to pick up changes.`
+    });
+  }
+  return warnings;
+}
+async function boringPluginRoutes(app, opts) {
+  const { manager, rebuildPlugins, enableReloadRoute = true } = opts;
+  if (enableReloadRoute) {
+    app.post("/api/boring.reload", async (_request, reply) => {
+      const scan = await manager.load();
+      const rebuild = rebuildPlugins ? await rebuildPlugins() : { ok: true, diagnostics: [] };
+      const restart_warnings = collectRestartWarnings(scan.events);
+      const hasFailures = scan.errors.length > 0 || rebuild.diagnostics.length > 0;
+      if (hasFailures) {
+        return reply.status(422).send({
+          ok: false,
+          errors: scan.errors,
+          diagnostics: rebuild.diagnostics,
+          plugins: scan.loaded,
+          // Even on failure, emit warnings for plugins that DID reload
+          // — partial-failure tolerance means some loaded successfully.
+          ...restart_warnings.length > 0 ? { restart_warnings } : {}
+        });
+      }
+      return reply.send({
+        ok: true,
+        plugins: scan.loaded,
+        ...restart_warnings.length > 0 ? { restart_warnings } : {}
+      });
+    });
+  }
+  const listPlugins = async () => manager.list();
+  app.get("/api/v1/agent-plugins", listPlugins);
+  const getPluginError = async (request, reply) => {
+    const error = manager.getError(request.params.id);
+    if (error == null) return reply.status(404).send({ error: "not_found" });
+    return reply.type("text/plain").send(error);
+  };
+  app.get("/api/v1/agent-plugins/:id/error", getPluginError);
+  app.get("/api/v1/agent-plugins/events", async (request, reply) => {
+    reply.hijack();
+    const res = reply.raw;
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.flushHeaders?.();
+    const write = (event) => {
+      try {
+        res.write(`event: ${event.type}
+`);
+        res.write(`data: ${JSON.stringify(event)}
+
+`);
+      } catch {
+      }
+    };
+    for (const plugin of manager.list()) {
+      write({
+        type: "boring.plugin.load",
+        id: plugin.id,
+        boring: plugin.boring,
+        version: plugin.version,
+        revision: plugin.revision,
+        ...plugin.frontUrl ? { frontUrl: plugin.frontUrl } : {}
+      });
+    }
+    const unsubscribe = manager.subscribe(write);
+    const heartbeat = setInterval(() => {
+      try {
+        res.write(": heartbeat\n\n");
+      } catch {
+      }
+    }, 25e3);
+    request.raw.on("close", () => {
+      clearInterval(heartbeat);
+      unsubscribe();
+    });
+  });
+}
+
+// src/server/agentPlugins/aggregatePluginPrompts.ts
+function aggregatePluginPrompts(manager) {
+  const prompts = manager.list().map((plugin) => plugin.pi?.systemPrompt?.trim()).filter((prompt) => Boolean(prompt));
+  if (prompts.length === 0) return void 0;
+  return `# Loaded boring-ui plugin context
+
+${prompts.join("\n\n")}`;
+}
 export {
-  ServerPluginError,
+  BoringPluginAssetManager,
+  aggregatePluginPrompts,
   bootstrapServer,
-  composeServerPlugins,
+  boringPluginRoutes,
+  buildBoringSystemPrompt,
+  collectRestartWarnings,
   createExecUiTool,
   createGetUiStateTool,
   createInMemoryBridge,
   createWorkspaceUiTools,
   defineServerPlugin,
+  pluginFileSignature,
+  preflightBoringPlugins,
+  readBoringPlugins,
+  readPluginSignatureCache,
+  scanBoringPlugins,
   uiRoutes,
-  validateServerPlugin
+  validateServerPlugin,
+  writePluginSignatureCache
 };