@hachej/boring-workspace 0.1.33 → 0.1.35

package/dist/app-server.js

@@ -9,7 +9,8 @@ import {
   VERCEL_SANDBOX_WORKSPACE_ROOT
 } from "@hachej/boring-agent/server";
 import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname7, join as join7 } from "path";
+import { dirname as dirname7, isAbsolute as isAbsolute5, join as join7, resolve as resolve7 } from "path";
+import { homedir } from "os";
 import { createRequire as createRequire4 } from "module";
 import { fileURLToPath } from "url";
 
@@ -103,13 +104,19 @@ function buildBoringSystemPrompt(opts) {
       "- 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: import `WORKSPACE_OPEN_PATH_SURFACE_KIND`/`PaneProps` from `@hachej/boring-workspace/plugin`; import `useApiBaseUrl`/`useWorkspaceRequestId` from `@hachej/boring-workspace`; read `request.target`; fetch `${apiBaseUrl}/api/v1/files/raw?...` with `credentials: "include"` and `x-boring-workspace-id` when present. Never 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 }) }`.",
+      '- Pi extension tools: `defineTool` and `export const tools` do NOT exist. Export `default function (pi) { pi.registerTool({ name, description, parameters: { type: "object", properties: {} }, execute }) }`. `parameters` is mandatory even for no-arg tools; omitting it breaks tool execution.',
       '- 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`.",
       "- Dependency installs: do NOT install plugin UI dependencies at the workspace root. Install them inside `.pi/extensions/<name>/` and keep React/workspace/boring-ui-kit imports as host singletons, not plugin dependencies.",
       "- 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"),
+    [
+      "## Installing an existing or published plugin",
+      "To ADD an existing or published plugin (not author a new one), use `boring-ui-plugin install <source>` via bash \u2014 `<source>` is `npm:<package>`, `git:<repo>`, `github:<owner>/<repo>`, an `http(s)` git URL, or a local path; add `--global` for all workspaces (default is this workspace).",
+      "A bare `npm install <package>` does NOT register it as a plugin (no `.pi/settings.json` package source), so it will NOT load \u2014 always use `boring-ui-plugin install`, then ask the user to `/reload` (a `boring.server` backend also needs a process restart).",
+      "Inspect with `boring-ui-plugin list [--json]`; remove with `boring-ui-plugin remove <id-or-source>`."
+    ].join("\n"),
     docsBlock
   ].join("\n\n");
 }
@@ -348,6 +355,14 @@ function resolveSafePluginEntryPath({
 }
 
 // src/server/agentPlugins/scan.ts
+function normalizeBoringPluginSource(input) {
+  if (typeof input === "string") return { rootDir: resolve2(input), kind: "internal" };
+  return {
+    rootDir: resolve2(input.rootDir),
+    kind: input.kind,
+    ...input.workspaceId ? { workspaceId: input.workspaceId } : {}
+  };
+}
 function pluginIdFromPackageJson(pkg, rootDir) {
   const explicitId = typeof pkg.boring?.id === "string" && pkg.boring.id.trim() ? pkg.boring.id.trim() : void 0;
   if (explicitId) return explicitId;
@@ -406,10 +421,11 @@ function packagePathContainmentIssues(rootDir, pkg) {
   return issues;
 }
 function discoverBoringPluginDirs(pluginDirs) {
-  const out = /* @__PURE__ */ new Set();
+  const out = /* @__PURE__ */ new Map();
   const missingPackageJson = [];
   for (const raw of pluginDirs) {
-    const dir = resolve2(raw);
+    const source = normalizeBoringPluginSource(raw);
+    const dir = source.rootDir;
     if (!existsSync2(dir)) continue;
     const info = statSync(dir);
     if (!info.isDirectory()) continue;
@@ -420,13 +436,19 @@ function discoverBoringPluginDirs(pluginDirs) {
       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") {
+    if (hasPackageJson && !out.has(dir)) out.set(dir, source);
+    for (const child of childPackageDirs) {
+      if (!out.has(child)) out.set(child, { ...source, rootDir: child });
+    }
+    const collectionDirNames = /* @__PURE__ */ new Set(["extensions", "npm", "git"]);
+    if (!hasPackageJson && childPackageDirs.length === 0 && !collectionDirNames.has(basename(dir))) {
       missingPackageJson.push(dir);
     }
   }
-  return { dirs: [...out].sort(), missingPackageJson: [...new Set(missingPackageJson)].sort() };
+  return {
+    sources: [...out.values()].sort((a, b) => a.rootDir.localeCompare(b.rootDir)),
+    missingPackageJson: [...new Set(missingPackageJson)].sort()
+  };
 }
 function scanBoringPlugins(pluginDirs) {
   const errors = [];
@@ -436,7 +458,8 @@ function scanBoringPlugins(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) {
+  for (const source of discovered.sources) {
+    const rootDir = source.rootDir;
     let raw;
     try {
       raw = parsePackageJson(rootDir);
@@ -474,15 +497,26 @@ function scanBoringPlugins(pluginDirs) {
     } 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;
+        const previousPlugin = previousPluginIndex >= 0 ? plugins[previousPluginIndex] : void 0;
+        const currentIsWorkspaceLocal = Boolean(source.workspaceId);
+        const previousIsWorkspaceLocal = Boolean(previousPlugin?.source.workspaceId);
+        const currentMayShadowPrevious = source.kind === "external" && currentIsWorkspaceLocal && previousPlugin?.source.kind === "external" && !previousIsWorkspaceLocal;
+        if (currentMayShadowPrevious) {
+          if (previousPluginIndex >= 0) plugins.splice(previousPluginIndex, 1);
+          seenIds.set(id, rootDir);
+        } else if (!currentIsWorkspaceLocal && previousIsWorkspaceLocal) {
+          canAddPlugin = false;
+        } else {
+          errors.push({
+            pluginDir: rootDir,
+            pluginId: id,
+            code: "INVALID_PLUGIN_METADATA",
+            message: `duplicate plugin id "${id}" also declared by ${previous}`
+          });
+          if (previousPluginIndex >= 0) plugins.splice(previousPluginIndex, 1);
+          canAddPlugin = false;
+        }
       } else {
         seenIds.set(id, rootDir);
       }
@@ -494,6 +528,7 @@ function scanBoringPlugins(pluginDirs) {
     }
     if (!canAddPlugin) continue;
     const pkg = result.packageJson;
+    const hasBoring = pkg.boring !== void 0;
     const boring = pkg.boring ?? {};
     const pi = pkg.pi;
     const frontPath = resolvePluginPath(rootDir, boring.front, { mustExist: true });
@@ -506,11 +541,13 @@ function scanBoringPlugins(pluginDirs) {
       rootDir,
       version,
       boring,
+      hasBoring,
       ...pi ? { pi } : {},
       ...frontPath ? { frontPath, frontUrl: `/@fs/${frontPath}` } : {},
       ...serverPath ? { serverPath } : {},
       ...extensionPaths.length > 0 ? { extensionPaths } : {},
-      ...skillPaths.length > 0 ? { skillPaths } : {}
+      ...skillPaths.length > 0 ? { skillPaths } : {},
+      source
     });
   }
   const preflight = { ok: errors.length === 0, errors };
@@ -933,10 +970,11 @@ function frontSignatureRoot(plugin) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel) ? frontRoot : dirname5(plugin.frontPath);
 }
 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(frontSignatureRoot(plugin))).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");
+  return createHash("sha256").update(JSON.stringify(plugin.boring)).update(JSON.stringify(plugin.pi ?? {})).update(plugin.version).update(JSON.stringify(plugin.source)).update(plugin.frontPath ?? "").update(pluginFileSignature(plugin.frontPath)).update(directorySignature(frontSignatureRoot(plugin))).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 [];
+  if (previous.source.kind === "external" && next.source.kind === "external") return [];
   const prevHasServer = !!previous.serverPath;
   const nextHasServer = !!next.serverPath;
   if (!prevHasServer && !nextHasServer) return [];
@@ -982,8 +1020,10 @@ var BoringPluginAssetManager = class {
       version: plugin.version,
       revision: plugin.revision,
       rootDir: plugin.rootDir,
+      source: plugin.source,
       ...plugin.frontPath ? { frontPath: plugin.frontPath } : {},
-      ...plugin.frontTarget ? { frontTarget: plugin.frontTarget } : {}
+      ...plugin.frontTarget ? { frontTarget: plugin.frontTarget } : {},
+      ...plugin.serverPath ? { serverPath: plugin.serverPath } : {}
     }));
   }
   inspectLoadedPiSnapshot() {
@@ -1023,7 +1063,7 @@ ${prompts.join("\n\n")}` } : {}
   async doLoadOnce() {
     this.lastErrors.clear();
     const scan = scanBoringPlugins(this.pluginDirs);
-    const nextPlugins = scan.plugins;
+    const nextPlugins = scan.plugins.filter((plugin) => plugin.hasBoring);
     const nextIds = new Set(nextPlugins.map((plugin) => plugin.id));
     const invalidPluginDirs = new Set(scan.preflight.errors.map((error) => resolve4(error.pluginDir)));
     const events = [];
@@ -1187,31 +1227,7 @@ function collectRestartWarnings(events) {
   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 { manager } = opts;
   const listPlugins = async () => manager.list();
   app.get("/api/v1/agent-plugins", listPlugins);
   const getPluginError = async (request, reply) => {
@@ -1280,29 +1296,106 @@ async function boringPluginRoutes(app, opts) {
   });
 }
 
-// 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
+// src/server/runtimeBackend/defineRuntimeServerPlugin.ts
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function validateRuntimeServerPlugin(value) {
+  if (!isPlainObject(value)) {
+    throw new Error("runtime server plugin default export must be a plain object");
+  }
+  if ("id" in value) {
+    throw new Error("runtime server plugin must not declare id; the host supplies plugin id from package metadata");
+  }
+  if (typeof value.routes !== "function") {
+    throw new Error("runtime server plugin default export must define routes(router)");
+  }
+  if (value.dispose !== void 0 && typeof value.dispose !== "function") {
+    throw new Error("runtime server plugin dispose must be a function when provided");
+  }
+  return value;
+}
+function isRuntimePluginResponse(value) {
+  return isPlainObject(value) && value.kind === "response";
+}
 
-${prompts.join("\n\n")}`;
+// src/server/runtimeBackend/runtimePathSegments.ts
+function findUnsafeRuntimePathSegment(path) {
+  if (path.includes("\\")) return "\\";
+  for (const segment of path.split("/")) {
+    if (segment === "." || segment === "..") return segment;
+  }
+  return null;
+}
+function describeUnsafeRuntimePathSegment(segment) {
+  if (segment === "\\") return "backslashes";
+  return `${segment} segments`;
 }
 
-// src/app/server/pluginEntryResolver.ts
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
-import { join as join5, resolve as resolve5 } from "path";
-import { createRequire as createRequire2 } from "module";
-import { pathToFileURL } from "url";
-function readPluginPackageJson(dir) {
-  const pkgPath = resolve5(dir, "package.json");
-  if (!existsSync5(pkgPath)) return null;
+// src/server/runtimeBackend/routerCapture.ts
+var METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "ALL"];
+function routeKey(method, path) {
+  return `${method} ${path}`;
+}
+function runtimeRouteKey(method, path) {
+  return routeKey(method.toUpperCase(), path);
+}
+function validateRuntimeRoutePath(path) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw new Error("runtime route path must be a non-empty string");
+  }
+  if (!path.startsWith("/")) {
+    throw new Error(`runtime route path must start with /: ${path}`);
+  }
+  if (path.includes("?") || path.includes("#")) {
+    throw new Error(`runtime route path must not include query strings or fragments: ${path}`);
+  }
+  let decodedPath;
   try {
-    return JSON.parse(readFileSync4(pkgPath, "utf8"));
+    decodedPath = decodeURIComponent(path);
   } catch {
-    return null;
+    throw new Error(`runtime route path must be valid percent-encoding: ${path}`);
+  }
+  const unsafeSegment = findUnsafeRuntimePathSegment(decodedPath);
+  if (unsafeSegment) {
+    throw new Error(`runtime route path must not contain ${describeUnsafeRuntimePathSegment(unsafeSegment)}: ${path}`);
+  }
+  if (path.includes(":")) {
+    throw new Error(`runtime route path must be exact and must not contain params: ${path}`);
   }
+  if (path.includes("*")) {
+    throw new Error(`runtime route path must be exact and must not contain wildcards: ${path}`);
+  }
+  return path;
+}
+async function captureRuntimeRoutes(register) {
+  const routes = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (method, path, handler) => {
+    if (typeof handler !== "function") {
+      throw new Error(`runtime route ${method} ${path} handler must be a function`);
+    }
+    const normalizedPath = validateRuntimeRoutePath(path);
+    const key = routeKey(method, normalizedPath);
+    if (seen.has(key)) throw new Error(`duplicate runtime route: ${key}`);
+    seen.add(key);
+    routes.push({ method, path: normalizedPath, handler });
+  };
+  const router = Object.fromEntries(
+    METHODS.map((method) => [method.toLowerCase(), (path, handler) => add(method, path, handler)])
+  );
+  await register(router);
+  return routes;
 }
+
+// src/server/runtimeBackend/runtimeBackendRegistry.ts
+import { ErrorCode } from "@hachej/boring-agent/shared";
+
+// src/server/pluginImports/importServerModule.ts
+import { createRequire as createRequire2 } from "module";
+import { pathToFileURL } from "url";
 var require3 = createRequire2(import.meta.url);
 var warnedJitiMissing = false;
 function warnJitiUnavailable(serverPath, reason) {
@@ -1337,6 +1430,379 @@ async function importServerModule(serverPath, hotReload) {
     href
   );
 }
+
+// src/server/runtimeBackend/runtimeBackendRegistry.ts
+var RuntimeBackendError = class extends Error {
+  constructor(code, statusCode, message, details) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "RuntimeBackendError";
+  }
+  code;
+  statusCode;
+  details;
+};
+function errorMessage(error) {
+  return error instanceof Error ? error.stack ?? error.message : String(error);
+}
+function moduleValue(mod) {
+  return typeof mod === "object" && mod !== null && "default" in mod ? mod.default : mod;
+}
+function toRouteMap(routes) {
+  const map = /* @__PURE__ */ new Map();
+  for (const route of routes) map.set(runtimeRouteKey(route.method, route.path), route);
+  return map;
+}
+function assertJsonSerializable(value) {
+  if (value === void 0 || value === null) return;
+  if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint") {
+    throw new RuntimeBackendError(
+      ErrorCode.enum.RUNTIME_PLUGIN_RESPONSE_UNSUPPORTED,
+      500,
+      "runtime plugin response is not JSON-serializable"
+    );
+  }
+  try {
+    JSON.stringify(value);
+  } catch (error) {
+    throw new RuntimeBackendError(
+      ErrorCode.enum.RUNTIME_PLUGIN_RESPONSE_UNSUPPORTED,
+      500,
+      `runtime plugin response is not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function normalizeResponse(value) {
+  if (value === void 0 || value === null) return { status: 204, headers: {} };
+  if (isRuntimePluginResponse(value)) return normalizeExplicitResponse(value);
+  assertJsonSerializable(value);
+  return { status: 200, headers: { "content-type": "application/json; charset=utf-8" }, body: value };
+}
+function normalizeExplicitResponse(value) {
+  const status = value.status ?? (value.body === void 0 || value.body === null ? 204 : 200);
+  if (!Number.isInteger(status) || status < 100 || status > 599) {
+    throw new RuntimeBackendError(
+      ErrorCode.enum.RUNTIME_PLUGIN_RESPONSE_UNSUPPORTED,
+      500,
+      "runtime plugin response status must be an integer HTTP status code"
+    );
+  }
+  const headers = {};
+  if (value.headers !== void 0) {
+    for (const [name, headerValue] of Object.entries(value.headers)) {
+      if (typeof headerValue !== "string") {
+        throw new RuntimeBackendError(
+          ErrorCode.enum.RUNTIME_PLUGIN_RESPONSE_UNSUPPORTED,
+          500,
+          "runtime plugin response headers must be strings"
+        );
+      }
+      headers[name] = headerValue;
+    }
+  }
+  if (value.body === void 0 || value.body === null) return { status, headers };
+  assertJsonSerializable(value.body);
+  if (!Object.keys(headers).some((name) => name.toLowerCase() === "content-type")) {
+    headers["content-type"] = "application/json; charset=utf-8";
+  }
+  return { status, headers, body: value.body };
+}
+async function disposeSnapshot(snapshot) {
+  if (!snapshot.module.dispose) return [];
+  try {
+    await snapshot.module.dispose();
+    return [];
+  } catch (error) {
+    return [{
+      pluginId: snapshot.pluginId,
+      source: `runtime backend dispose (${snapshot.pluginId})`,
+      code: ErrorCode.enum.RUNTIME_PLUGIN_LOAD_FAILED,
+      message: errorMessage(error)
+    }];
+  }
+}
+var RuntimeBackendRegistry = class {
+  snapshots = /* @__PURE__ */ new Map();
+  lastDiagnostics = [];
+  reloadQueue = Promise.resolve({ ok: true, diagnostics: [] });
+  getDiagnostics() {
+    return [...this.lastDiagnostics];
+  }
+  listPluginIds() {
+    return [...this.snapshots.keys()].sort();
+  }
+  async reloadFromLoadedPlugins(plugins) {
+    const run = this.reloadQueue.then(() => this.reloadOnce(plugins), () => this.reloadOnce(plugins));
+    this.reloadQueue = run.then(() => ({ ok: true, diagnostics: [] }), () => ({ ok: false, diagnostics: [] }));
+    return run;
+  }
+  async close() {
+    const run = this.reloadQueue.then(() => this.closeOnce(), () => this.closeOnce());
+    this.reloadQueue = run.then(() => ({ ok: true, diagnostics: [] }), () => ({ ok: false, diagnostics: [] }));
+    return run;
+  }
+  async dispatch(request) {
+    const snapshot = this.snapshots.get(request.pluginId);
+    if (!snapshot) {
+      throw new RuntimeBackendError(
+        ErrorCode.enum.RUNTIME_PLUGIN_NOT_FOUND,
+        404,
+        `runtime backend plugin not found: ${request.pluginId}`
+      );
+    }
+    if (snapshot.source.workspaceId && snapshot.source.workspaceId !== request.workspaceId) {
+      throw new RuntimeBackendError(
+        ErrorCode.enum.RUNTIME_PLUGIN_NOT_FOUND,
+        404,
+        `runtime backend plugin not found in workspace: ${request.pluginId}`
+      );
+    }
+    const route = snapshot.routes.get(runtimeRouteKey(request.method, request.path)) ?? snapshot.routes.get(runtimeRouteKey("ALL", request.path));
+    if (!route) {
+      throw new RuntimeBackendError(
+        ErrorCode.enum.RUNTIME_PLUGIN_ROUTE_NOT_FOUND,
+        404,
+        `runtime backend route not found: ${request.method.toUpperCase()} ${request.path}`
+      );
+    }
+    const ctx = {
+      pluginId: request.pluginId,
+      method: request.method.toUpperCase(),
+      path: request.path,
+      query: request.query,
+      headers: request.headers,
+      signal: request.signal,
+      body: request.body,
+      logger: request.logger
+    };
+    try {
+      return normalizeResponse(await route.handler(ctx));
+    } catch (error) {
+      if (error instanceof RuntimeBackendError) throw error;
+      throw new RuntimeBackendError(
+        ErrorCode.enum.RUNTIME_PLUGIN_HANDLER_FAILED,
+        500,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  async reloadOnce(plugins) {
+    const diagnostics = [];
+    const externalRuntimePlugins = plugins.filter((plugin) => plugin.source.kind === "external" && plugin.serverPath);
+    const nextIds = new Set(externalRuntimePlugins.map((plugin) => plugin.id));
+    for (const id of [...this.snapshots.keys()]) {
+      if (nextIds.has(id)) continue;
+      const previous = this.snapshots.get(id);
+      if (!previous) continue;
+      this.snapshots.delete(id);
+      diagnostics.push(...await disposeSnapshot(previous));
+    }
+    for (const plugin of externalRuntimePlugins) {
+      const serverPath = plugin.serverPath;
+      if (!serverPath) continue;
+      try {
+        const mod = await importServerModule(serverPath, true);
+        const runtimePlugin = validateRuntimeServerPlugin(moduleValue(mod));
+        const routes = await captureRuntimeRoutes((router) => runtimePlugin.routes(router));
+        const nextSnapshot = {
+          pluginId: plugin.id,
+          source: plugin.source,
+          module: runtimePlugin,
+          routes: toRouteMap(routes)
+        };
+        const previous = this.snapshots.get(plugin.id);
+        this.snapshots.set(plugin.id, nextSnapshot);
+        if (previous) diagnostics.push(...await disposeSnapshot(previous));
+      } catch (error) {
+        diagnostics.push({
+          pluginId: plugin.id,
+          source: `runtime backend (${plugin.id})`,
+          code: ErrorCode.enum.RUNTIME_PLUGIN_LOAD_FAILED,
+          message: errorMessage(error)
+        });
+      }
+    }
+    this.lastDiagnostics = diagnostics;
+    return { ok: diagnostics.length === 0, diagnostics };
+  }
+  async closeOnce() {
+    const diagnostics = [];
+    for (const snapshot of this.snapshots.values()) {
+      diagnostics.push(...await disposeSnapshot(snapshot));
+    }
+    this.snapshots.clear();
+    this.lastDiagnostics = diagnostics;
+    return { ok: diagnostics.length === 0, diagnostics };
+  }
+};
+
+// src/server/runtimeBackend/runtimeBackendGateway.ts
+import { ErrorCode as ErrorCode2 } from "@hachej/boring-agent/shared";
+var GATEWAY_PREFIX = "/api/v1/plugins/";
+function rawPathFromRequest(request) {
+  const url = request.raw.url ?? request.url;
+  const queryIndex = url.indexOf("?");
+  return queryIndex === -1 ? url : url.slice(0, queryIndex);
+}
+function rawGatewayTail(request, pluginId) {
+  const rawPath = rawPathFromRequest(request);
+  const prefix = `${GATEWAY_PREFIX}${pluginId}`;
+  if (rawPath === prefix || rawPath === `${prefix}/`) return "/";
+  if (!rawPath.startsWith(`${prefix}/`)) {
+    throw new RuntimeBackendError(
+      ErrorCode2.enum.RUNTIME_PLUGIN_ROUTE_NOT_FOUND,
+      404,
+      "runtime backend route not found"
+    );
+  }
+  return rawPath.slice(prefix.length);
+}
+function normalizeGatewayPath(rawTail) {
+  let path;
+  try {
+    path = decodeURIComponent(rawTail);
+  } catch {
+    throw new RuntimeBackendError(
+      ErrorCode2.enum.RUNTIME_PLUGIN_ROUTE_NOT_FOUND,
+      404,
+      "runtime backend route path is not valid percent-encoding"
+    );
+  }
+  if (path.length === 0) path = "/";
+  const unsafeSegment = findUnsafeRuntimePathSegment(path);
+  if (unsafeSegment) {
+    throw new RuntimeBackendError(
+      ErrorCode2.enum.RUNTIME_PLUGIN_ROUTE_NOT_FOUND,
+      404,
+      `runtime backend route path must not contain ${describeUnsafeRuntimePathSegment(unsafeSegment)}`
+    );
+  }
+  return path;
+}
+function firstString(value) {
+  if (Array.isArray(value)) return value[0];
+  return value;
+}
+function headersFromRequest(request) {
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(name, item);
+    } else {
+      headers.set(name, String(value));
+    }
+  }
+  return headers;
+}
+function loggerFromRequest(request) {
+  return {
+    debug: (arg, message) => {
+      if (message === void 0) request.log.debug(arg);
+      else request.log.debug(arg, message);
+    },
+    info: (arg, message) => {
+      if (message === void 0) request.log.info(arg);
+      else request.log.info(arg, message);
+    },
+    warn: (arg, message) => {
+      if (message === void 0) request.log.warn(arg);
+      else request.log.warn(arg, message);
+    },
+    error: (arg, message) => {
+      if (message === void 0) request.log.error(arg);
+      else request.log.error(arg, message);
+    }
+  };
+}
+function sendDispatchResponse(reply, response) {
+  reply.status(response.status);
+  for (const [name, value] of Object.entries(response.headers)) reply.header(name, value);
+  if (response.body === void 0 || response.body === null) return reply.send();
+  return reply.send(response.body);
+}
+function sendError(reply, error) {
+  if (error instanceof RuntimeBackendError) {
+    return reply.status(error.statusCode).send({
+      error: {
+        code: error.code,
+        message: error.message,
+        ...error.details ? { details: error.details } : {}
+      }
+    });
+  }
+  return reply.status(500).send({
+    error: {
+      code: ErrorCode2.enum.INTERNAL_ERROR,
+      message: error instanceof Error ? error.message : String(error)
+    }
+  });
+}
+async function runtimeBackendGateway(app, opts) {
+  const handle = async (request, reply) => {
+    const { pluginId } = request.params;
+    if (!isValidBoringPluginId(pluginId)) {
+      return sendError(reply, new RuntimeBackendError(
+        ErrorCode2.enum.RUNTIME_PLUGIN_NOT_FOUND,
+        404,
+        "runtime backend plugin not found"
+      ));
+    }
+    let path;
+    try {
+      path = normalizeGatewayPath(rawGatewayTail(request, pluginId));
+    } catch (error) {
+      return sendError(reply, error);
+    }
+    const abort = new AbortController();
+    const close = () => abort.abort();
+    request.raw.on("close", close);
+    try {
+      const response = await opts.registry.dispatch({
+        pluginId,
+        method: request.method,
+        path,
+        query: new URLSearchParams(request.query),
+        headers: headersFromRequest(request),
+        signal: abort.signal,
+        body: request.body,
+        logger: loggerFromRequest(request),
+        ...firstString(request.headers["x-boring-workspace-id"]) ?? opts.defaultWorkspaceId ? { workspaceId: firstString(request.headers["x-boring-workspace-id"]) ?? opts.defaultWorkspaceId } : {}
+      });
+      return sendDispatchResponse(reply, response);
+    } catch (error) {
+      return sendError(reply, error);
+    } finally {
+      request.raw.off("close", close);
+    }
+  };
+  app.all("/api/v1/plugins/:pluginId", handle);
+  app.all("/api/v1/plugins/:pluginId/*", handle);
+}
+
+// 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")}`;
+}
+
+// src/app/server/pluginEntryResolver.ts
+import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
+import { join as join5, resolve as resolve5 } from "path";
+function readPluginPackageJson(dir) {
+  const pkgPath = resolve5(dir, "package.json");
+  if (!existsSync5(pkgPath)) return null;
+  try {
+    return JSON.parse(readFileSync4(pkgPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
 function resolveDirServerEntryPath(dir) {
   const rootDir = resolve5(dir);
   const pkg = readPluginPackageJson(rootDir);
@@ -2283,7 +2749,50 @@ async function provisionWorkspaceAgentServer(opts) {
     force: opts.force
   });
 }
-function collectBoringPluginDirs(workspaceRoot, pluginCollection, additionalPluginDirs = []) {
+function uniquePluginSources(sources) {
+  const byRoot = /* @__PURE__ */ new Map();
+  for (const source of sources) {
+    const existing = byRoot.get(source.rootDir);
+    if (!existing || !existing.workspaceId && source.workspaceId) byRoot.set(source.rootDir, source);
+  }
+  return [...byRoot.values()];
+}
+var REMOTE_PI_PACKAGE_SOURCE_PREFIXES = ["npm:", "git:", "github:", "http:", "https:", "ssh:"];
+function piPackageSourceValue(entry) {
+  if (typeof entry === "string") return entry;
+  if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+    const source = entry.source;
+    return typeof source === "string" ? source : void 0;
+  }
+  return void 0;
+}
+function resolveLocalPiPackageSource(settingsDir, source) {
+  const path = source.startsWith("file:") ? source.slice("file:".length) : source;
+  if (!path) return void 0;
+  if (REMOTE_PI_PACKAGE_SOURCE_PREFIXES.some((prefix) => path.startsWith(prefix))) return void 0;
+  if (!isAbsolute5(path) && path !== "." && path !== "./" && !path.startsWith("./") && !path.startsWith("../")) return void 0;
+  return resolve7(settingsDir, path);
+}
+function readPiSettingsBoringPluginSources(settingsPath, workspaceId) {
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync6(settingsPath, "utf8"));
+  } catch {
+    return [];
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return [];
+  const packages = raw.packages;
+  if (!Array.isArray(packages)) return [];
+  const settingsDir = dirname7(settingsPath);
+  return uniquePluginSources(
+    packages.map(piPackageSourceValue).map((source) => source ? resolveLocalPiPackageSource(settingsDir, source) : void 0).filter((rootDir) => Boolean(rootDir)).map((rootDir) => ({
+      rootDir,
+      kind: "external",
+      ...workspaceId ? { workspaceId } : {}
+    }))
+  );
+}
+function collectBoringPluginSources(workspaceRoot, pluginCollection, additionalPluginDirs = []) {
   const extensionPaths = pluginCollection.agentOptions.pi?.extensionPaths ?? [];
   const pluginRoots = extensionPaths.flatMap((path) => {
     try {
@@ -2292,11 +2801,16 @@ function collectBoringPluginDirs(workspaceRoot, pluginCollection, additionalPlug
       return [];
     }
   });
-  return [.../* @__PURE__ */ new Set([
-    join7(workspaceRoot, ".pi", "extensions"),
-    ...pluginRoots,
-    ...additionalPluginDirs
-  ])];
+  return uniquePluginSources([
+    { rootDir: join7(workspaceRoot, ".pi", "extensions"), kind: "external", workspaceId: workspaceRoot },
+    { rootDir: join7(workspaceRoot, ".pi", "npm"), kind: "external", workspaceId: workspaceRoot },
+    { rootDir: join7(workspaceRoot, ".pi", "git"), kind: "external", workspaceId: workspaceRoot },
+    { rootDir: join7(homedir(), ".pi", "agent", "extensions"), kind: "external" },
+    ...readPiSettingsBoringPluginSources(join7(workspaceRoot, ".pi", "settings.json"), workspaceRoot),
+    ...readPiSettingsBoringPluginSources(join7(homedir(), ".pi", "agent", "settings.json")),
+    ...pluginRoots.map((rootDir) => ({ rootDir, kind: "internal" })),
+    ...additionalPluginDirs.map((entry) => typeof entry === "string" ? { rootDir: entry, kind: "internal" } : entry)
+  ]);
 }
 function mergeRuntimeProvisioningInputs(plugins) {
   const byId = /* @__PURE__ */ new Map();
@@ -2409,11 +2923,17 @@ async function createWorkspaceAgentServer(opts = {}) {
     ...pluginCollection.agentOptions.pi?.packages ?? []
   ];
   const baseStaticPiExtensionPaths = pluginCollection.agentOptions.pi?.extensionPaths ?? [];
-  const boringPluginDirs = [
-    ...collectBoringPluginDirs(workspaceRoot, pluginCollection, opts.additionalBoringPluginDirs),
-    ...defaultPluginPackagePaths
-  ];
-  const staticPluginPackagePiSnapshot = pluginHotReload ? emptyPackageJsonPiSnapshot() : readWorkspacePluginPackagePiSnapshot(boringPluginDirs);
+  const boringPluginDirs = [];
+  const refreshBoringPluginDirs = () => {
+    const next = uniquePluginSources([
+      ...defaultPluginPackagePaths.map((rootDir) => ({ rootDir, kind: "internal" })),
+      ...collectBoringPluginSources(workspaceRoot, pluginCollection, opts.additionalBoringPluginDirs)
+    ]);
+    boringPluginDirs.splice(0, boringPluginDirs.length, ...next);
+    return boringPluginDirs;
+  };
+  refreshBoringPluginDirs();
+  const staticPluginPackagePiSnapshot = pluginHotReload ? emptyPackageJsonPiSnapshot() : readWorkspacePluginPackagePiSnapshot(refreshBoringPluginDirs());
   const staticPiSkillPaths = [
     ...baseStaticPiSkillPaths,
     ...staticPluginPackagePiSnapshot.additionalSkillPaths
@@ -2426,17 +2946,18 @@ async function createWorkspaceAgentServer(opts = {}) {
     ...baseStaticPiExtensionPaths,
     ...staticPluginPackagePiSnapshot.extensionPaths
   ];
-  const getHotReloadablePiResources = pluginHotReload ? () => readWorkspacePluginPackagePiSnapshot(boringPluginDirs) : void 0;
+  const getHotReloadablePiResources = pluginHotReload ? () => readWorkspacePluginPackagePiSnapshot(refreshBoringPluginDirs()) : void 0;
   const boringAssetManager = new BoringPluginAssetManager({
     pluginDirs: boringPluginDirs,
     errorRoot: join7(workspaceRoot, ".pi", "extensions"),
     frontTargetResolver: opts.boringPluginFrontTargetResolver,
     includeLegacyFrontUrl: opts.boringPluginIncludeLegacyFrontUrl
   });
+  const runtimeBackendRegistry = new RuntimeBackendRegistry();
   const buildRuntimeProvisioningInputs = () => {
     const inputs = mergeRuntimeProvisioningInputs([
       ...pluginCollection.runtimePlugins,
-      ...readWorkspacePluginPackageRuntimePlugins(boringPluginDirs)
+      ...readWorkspacePluginPackageRuntimePlugins(refreshBoringPluginDirs())
     ]);
     if (resolvedMode === "direct") return omitPluginAuthoringProvisioning(inputs);
     return inputs;
@@ -2499,7 +3020,9 @@ async function createWorkspaceAgentServer(opts = {}) {
       let restart_warnings = [];
       let diagnostics = [];
       if (pluginHotReload) {
+        refreshBoringPluginDirs();
         const scan = await boringAssetManager.load();
+        const backendReload = await runtimeBackendRegistry.reloadFromLoadedPlugins(boringAssetManager.inspectLoaded());
         restart_warnings = collectRestartWarnings(scan.events);
         const scanDiagnostics = scan.errors.map((error) => ({
           source: `boring plugin asset scan (${error.id})`,
@@ -2507,7 +3030,7 @@ async function createWorkspaceAgentServer(opts = {}) {
           pluginId: error.id
         }));
         const rebuild = await rebuildPlugins();
-        diagnostics = [...scanDiagnostics, ...rebuild.diagnostics];
+        diagnostics = [...scanDiagnostics, ...backendReload.diagnostics, ...rebuild.diagnostics];
       }
       await runRuntimeProvisioning();
       const callerResult = await opts.beforeReload?.();
@@ -2533,19 +3056,26 @@ async function createWorkspaceAgentServer(opts = {}) {
     },
     systemPromptDynamic: pluginHotReload ? () => aggregatePluginPrompts(boringAssetManager) : void 0
   });
+  refreshBoringPluginDirs();
   await boringAssetManager.load();
+  await runtimeBackendRegistry.reloadFromLoadedPlugins(boringAssetManager.inspectLoaded());
+  if (typeof app.addHook === "function") {
+    app.addHook("onClose", async () => {
+      await runtimeBackendRegistry.close();
+    });
+  }
   await app.register(uiRoutes, { bridge, preserveStateKeys: pluginCollection.preservedUiStateKeys });
   await app.register(boringPluginRoutes, {
-    manager: boringAssetManager,
-    rebuildPlugins,
-    enableReloadRoute: pluginHotReload
+    manager: boringAssetManager
   });
+  await app.register(runtimeBackendGateway, { registry: runtimeBackendRegistry, defaultWorkspaceId: workspaceRoot });
   for (const { routes } of pluginCollection.routeContributions) {
     await app.register(routes);
   }
   ;
   app.__boringRebuildPlugins = rebuildPlugins;
   app.__boringAssetManager = boringAssetManager;
+  app.__boringRuntimeBackendRegistry = runtimeBackendRegistry;
   return app;
 }
 export {