@hachej/boring-workspace 0.1.33 → 0.1.35

package/dist/server.js

@@ -1019,13 +1019,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");
 }
@@ -1227,6 +1233,14 @@ function resolveContainedPluginPath(rootDir, value, options = {}) {
 }
 
 // src/server/agentPlugins/scan.ts
+function normalizeBoringPluginSource(input) {
+  if (typeof input === "string") return { rootDir: resolve3(input), kind: "internal" };
+  return {
+    rootDir: resolve3(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;
@@ -1285,10 +1299,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 = resolve3(raw);
+    const source = normalizeBoringPluginSource(raw);
+    const dir = source.rootDir;
     if (!existsSync2(dir)) continue;
     const info = statSync(dir);
     if (!info.isDirectory()) continue;
@@ -1299,13 +1314,19 @@ function discoverBoringPluginDirs(pluginDirs) {
       const child = join3(dir, entry.name);
       if (existsSync2(join3(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 = [];
@@ -1315,7 +1336,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);
@@ -1353,15 +1375,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);
       }
@@ -1373,6 +1406,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 });
@@ -1385,11 +1419,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 };
@@ -1400,7 +1436,7 @@ function preflightBoringPlugins(pluginDirs) {
 }
 function readBoringPlugins(pluginDirs) {
   const scan = scanBoringPlugins(pluginDirs);
-  return scan.preflight.ok ? scan.plugins : [];
+  return scan.preflight.ok ? scan.plugins.filter((plugin) => plugin.hasBoring) : [];
 }
 
 // src/server/agentPlugins/signatureCache.ts
@@ -1564,10 +1600,11 @@ function frontSignatureRoot(plugin) {
   return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel) ? frontRoot : dirname6(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(join5(plugin.rootDir, "shared"))).update(plugin.serverPath ?? "").update(pluginFileSignature(plugin.serverPath)).update(directorySignature(plugin.serverPath ? dirname6(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(join5(plugin.rootDir, "shared"))).update(plugin.serverPath ?? "").update(pluginFileSignature(plugin.serverPath)).update(directorySignature(plugin.serverPath ? dirname6(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 [];
@@ -1613,8 +1650,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() {
@@ -1654,7 +1693,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) => resolve5(error.pluginDir)));
     const events = [];
@@ -1818,31 +1857,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) => {
@@ -1919,8 +1934,499 @@ function aggregatePluginPrompts(manager) {
 
 ${prompts.join("\n\n")}`;
 }
+
+// src/server/runtimeBackend/defineRuntimeServerPlugin.ts
+function defineRuntimeServerPlugin(plugin) {
+  return plugin;
+}
+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";
+}
+
+// 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/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 {
+    decodedPath = decodeURIComponent(path);
+  } catch {
+    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) {
+  if (warnedJitiMissing) return;
+  warnedJitiMissing = true;
+  console.warn(
+    `[boring-workspace] hotReload requested but jiti is unavailable (${reason}). Falling back to native import() for ${serverPath}; subsequent reloads will NOT pick up source changes because Node's module cache will return the same module. Install jiti or set hotReload: false.`
+  );
+}
+function jitiImport(serverPath) {
+  try {
+    const jitiModule = require3("jiti");
+    const create = jitiModule.createJiti;
+    if (!create) {
+      warnJitiUnavailable(serverPath, "createJiti not exported");
+      return null;
+    }
+    return create(import.meta.url, { moduleCache: false }).import(serverPath);
+  } catch (err) {
+    warnJitiUnavailable(serverPath, err instanceof Error ? err.message : String(err));
+    return null;
+  }
+}
+async function importServerModule(serverPath, hotReload) {
+  if (hotReload) {
+    const jiti = jitiImport(serverPath);
+    if (jiti) return await jiti;
+  }
+  const href = pathToFileURL(serverPath).href;
+  return await import(
+    /* @vite-ignore */
+    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);
+}
 export {
   BoringPluginAssetManager,
+  RuntimeBackendError,
+  RuntimeBackendRegistry,
   aggregatePluginPrompts,
   bootstrapServer,
   boringPluginRoutes,
@@ -1931,14 +2437,17 @@ export {
   createInMemoryBridge,
   createWorkspaceUiTools,
   definePluginAsset,
+  defineRuntimeServerPlugin,
   defineServerPlugin,
   pluginFileSignature,
   preflightBoringPlugins,
   readBoringPlugins,
   readPluginSignatureCache,
   resolvePluginAssetPath,
+  runtimeBackendGateway,
   scanBoringPlugins,
   uiRoutes,
+  validateRuntimeServerPlugin,
   validateServerPlugin,
   writePluginSignatureCache
 };