@hachej/boring-ui-cli 0.1.24 → 0.1.26

package/dist/server/cli.js

@@ -15,6 +15,11 @@ import { basename, dirname, isAbsolute, join, relative, resolve } from "node:pat
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { createLocalWorkspaceRegistry } from "./localWorkspaces.js";
+import {
+  createCliPluginAssetManager,
+  getGlobalPiExtensionsRoot,
+  resolveCliBoringPluginDirs
+} from "./pluginDiscovery.js";
 const MODE_MAP = {
   "local": "direct",
   // no sandbox, full network access
@@ -98,11 +103,18 @@ async function provisionCliWorkspaceRuntime(opts) {
   if (!adapter) {
     throw new Error(`runtime mode ${opts.mode} does not support workspace provisioning`);
   }
-  return await agent.provisionWorkspaceRuntime({
+  const result = await agent.provisionWorkspaceRuntime({
     plugins: [createBoringUiCliRuntimePlugin(), ...opts.plugins ?? []],
     adapter,
     runtimeLayout
   });
+  return {
+    ...result,
+    env: {
+      ...result.env,
+      BORING_AGENT_WORKSPACE_LOCAL_PLUGIN_ROOTS: opts.mode === "direct" || opts.mode === "local" ? "1" : "0"
+    }
+  };
 }
 function ensureFrontendBuilt(publicDir) {
   if (existsSync(join(publicDir, "index.html"))) return;
@@ -138,7 +150,7 @@ const HELP_TEXT = [
   "Options:",
   "  -p, --port <port>       HTTP port (default: 5200)",
   "      --host <host>       Listen host (default: 0.0.0.0)",
-  "  -m, --mode <mode>       local-sandbox or local (default: local-sandbox)",
+  "  -m, --mode <mode>       local-sandbox or local (default: local)",
   "  -h, --help              Show this help"
 ].join("\n");
 const AUTH_GUIDE = [
@@ -162,10 +174,174 @@ async function checkAuth() {
   const registry = ModelRegistry.create(authStorage);
   return registry.getAvailable().length;
 }
+const FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID = "folder";
+const RUNTIME_PLUGIN_TRUST_LABEL = "Trusted local runtime plugins";
+const RUNTIME_PLUGIN_TRUST_DESCRIPTION = "Loads plugin UI code from trusted local Pi extension roots through the CLI-owned runtime module host.";
+function createRuntimePluginDiagnosticsStore() {
+  const byWorkspace = /* @__PURE__ */ new Map();
+  function upsert(workspaceId, pluginId) {
+    const workspace = byWorkspace.get(workspaceId) ?? /* @__PURE__ */ new Map();
+    byWorkspace.set(workspaceId, workspace);
+    const existing = workspace.get(pluginId) ?? {
+      workspaceId,
+      pluginId,
+      recent: []
+    };
+    workspace.set(pluginId, existing);
+    return existing;
+  }
+  return {
+    record(diagnostic) {
+      if (!diagnostic.workspaceId || !diagnostic.pluginId) return;
+      const entry = upsert(diagnostic.workspaceId, diagnostic.pluginId);
+      const now = Date.now();
+      entry.lastDiagnostic = diagnostic;
+      entry.recent = [...entry.recent, diagnostic].slice(-12);
+      if (diagnostic.revision !== void 0) entry.revision = diagnostic.revision;
+      if (diagnostic.requestedPath) entry.lastRequestedPath = diagnostic.requestedPath;
+      if (diagnostic.resolvedPath) entry.lastResolvedPath = diagnostic.resolvedPath;
+      const details = diagnostic.details ?? {};
+      if (typeof details.rootDir === "string") entry.rootDir = details.rootDir;
+      if (typeof details.entryUrl === "string") entry.entryUrl = details.entryUrl;
+      if (typeof diagnostic.requestedPath === "string") entry.frontEntrySubpath = diagnostic.requestedPath;
+      if (diagnostic.stage === "track" && diagnostic.outcome === "tracked") {
+        entry.lastErrorCode = void 0;
+        entry.lastErrorMessage = void 0;
+        entry.lastErrorStage = void 0;
+      }
+      if (diagnostic.stage === "cache") entry.lastRequestAt = now;
+      if (diagnostic.stage === "transform" && diagnostic.outcome === "served") {
+        entry.lastTransformAt = now;
+        entry.lastTransformDurationMs = diagnostic.durationMs;
+      }
+      if (diagnostic.stage === "serve" && diagnostic.outcome === "served") {
+        entry.lastServeAt = now;
+        entry.lastServeDurationMs = diagnostic.durationMs;
+        entry.lastErrorCode = void 0;
+        entry.lastErrorMessage = void 0;
+        entry.lastErrorStage = void 0;
+      }
+      if (diagnostic.outcome === "rejected") {
+        entry.lastRejectedAt = now;
+        entry.lastErrorCode = diagnostic.code;
+        entry.lastErrorMessage = diagnostic.msg;
+        entry.lastErrorStage = diagnostic.stage;
+      }
+      if (diagnostic.stage === "cleanup" && diagnostic.outcome === "disposed") {
+        entry.lastDisposedAt = now;
+      }
+    },
+    snapshot(workspaceId) {
+      return [...byWorkspace.get(workspaceId)?.values() ?? []].map((entry) => ({ ...entry, recent: [...entry.recent] })).sort((a, b) => a.pluginId.localeCompare(b.pluginId));
+    },
+    disposeWorkspace(workspaceId) {
+      byWorkspace.delete(workspaceId);
+    }
+  };
+}
+function syncRuntimeHostFromPluginEvents(runtimeHost, workspaceId, events) {
+  for (const event of events) {
+    if (event.type === "boring.plugin.unload" || event.type === "boring.plugin.load" && !event.frontTarget) {
+      runtimeHost.untrackPlugin(workspaceId, event.id);
+    }
+  }
+}
+function buildRuntimePluginDiagnosticsResponse(args) {
+  const byPlugin = /* @__PURE__ */ new Map();
+  for (const plugin of args.loaded) {
+    byPlugin.set(plugin.id, {
+      id: plugin.id,
+      ...plugin.version ? { version: plugin.version } : {},
+      ...plugin.rootDir ? { rootDir: plugin.rootDir } : {},
+      ...plugin.frontPath ? { frontPath: plugin.frontPath } : {},
+      ...plugin.frontTarget ? { frontTarget: plugin.frontTarget } : {},
+      ...plugin.revision !== void 0 ? { serverLoadedRevision: plugin.revision } : {}
+    });
+  }
+  for (const error of args.errors) {
+    const current = byPlugin.get(error.id) ?? { id: error.id };
+    byPlugin.set(error.id, {
+      ...current,
+      serverError: error.message
+    });
+  }
+  for (const hostEntry of args.host) {
+    const current = byPlugin.get(hostEntry.pluginId) ?? { id: hostEntry.pluginId };
+    byPlugin.set(hostEntry.pluginId, {
+      ...current,
+      ...current.rootDir ? {} : hostEntry.rootDir ? { rootDir: hostEntry.rootDir } : {},
+      ...current.frontPath ? {} : hostEntry.frontEntrySubpath ? { frontPath: hostEntry.frontEntrySubpath } : {},
+      ...current.frontTarget ? {} : hostEntry.entryUrl ? { frontTarget: { kind: "native", entryUrl: hostEntry.entryUrl, revision: hostEntry.revision ?? 0, trust: "local-trusted-native" } } : {},
+      host: hostEntry
+    });
+  }
+  return {
+    workspaceId: args.workspaceId,
+    plugins: [...byPlugin.values()].sort((a, b) => a.id.localeCompare(b.id))
+  };
+}
+async function createFolderModeApp(opts) {
+  const workspaceRoot = resolve(opts.workspaceRoot);
+  const projectName = opts.projectName ?? (basename(workspaceRoot) || "workspace");
+  const [{ createWorkspaceAgentServer, readWorkspacePluginPackageRuntimePlugins }, { createPluginFrontRuntimeHost }] = await Promise.all([
+    import("@hachej/boring-workspace/app/server"),
+    import("./pluginFrontRuntime.js")
+  ]);
+  const diagnosticsStore = createRuntimePluginDiagnosticsStore();
+  const runtimeHost = await createPluginFrontRuntimeHost({
+    onDiagnostic: (diagnostic) => diagnosticsStore.record(diagnostic)
+  });
+  const runtimeProvisioning = await provisionCliWorkspaceRuntime({
+    workspaceRoot,
+    mode: opts.mode,
+    provisionWorkspace: opts.provisionWorkspace,
+    plugins: readWorkspacePluginPackageRuntimePlugins(resolveCliBoringPluginDirs(workspaceRoot))
+  });
+  const app = await createWorkspaceAgentServer({
+    workspaceRoot,
+    mode: opts.mode,
+    logger: false,
+    provisionWorkspace: false,
+    runtimeProvisioning,
+    additionalBoringPluginDirs: [getGlobalPiExtensionsRoot()],
+    boringPluginFrontTargetResolver: runtimeHost.createFrontTargetResolver(FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID),
+    boringPluginIncludeLegacyFrontUrl: false
+  });
+  await runtimeHost.registerRoutes(app);
+  const folderAssetManager = app.__boringAssetManager;
+  const closeFolderRuntimeCleanup = folderAssetManager?.subscribe((event) => {
+    syncRuntimeHostFromPluginEvents(runtimeHost, FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID, [event]);
+  });
+  if (closeFolderRuntimeCleanup) {
+    app.addHook("onClose", async () => {
+      closeFolderRuntimeCleanup();
+    });
+  }
+  app.get("/api/v1/runtime-plugin-diagnostics", async () => {
+    const manager = app.__boringAssetManager;
+    return buildRuntimePluginDiagnosticsResponse({
+      workspaceId: FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID,
+      loaded: manager?.inspectLoaded() ?? [],
+      errors: manager?.getErrors() ?? [],
+      host: diagnosticsStore.snapshot(FOLDER_RUNTIME_PLUGIN_WORKSPACE_ID)
+    });
+  });
+  app.get("/api/v1/workspace/meta", async () => ({
+    workspaceRoot,
+    projectName,
+    version: CLI_VERSION,
+    runtimePluginFrontLoadingEnabled: true,
+    runtimePluginTrustLabel: RUNTIME_PLUGIN_TRUST_LABEL,
+    runtimePluginTrustDescription: RUNTIME_PLUGIN_TRUST_DESCRIPTION,
+    runtimePluginDiagnosticsEnabled: true
+  }));
+  return app;
+}
 async function startFolderMode(opts) {
   const workspaceRoot = process.env.BORING_AGENT_WORKSPACE_ROOT ?? resolve(opts.folderArg ?? process.cwd());
   const projectName = basename(resolve(workspaceRoot)) || "workspace";
   const modelCount = await checkAuth();
+  const url = `http://localhost:${opts.port}`;
   console.log(`
 ${projectName}`);
   console.log(`  workspace  ${workspaceRoot}`);
@@ -173,40 +349,39 @@ ${projectName}`);
   console.log(`  port       ${opts.port}`);
   console.log(`  host       ${opts.host}`);
   if (modelCount === 0) console.log(AUTH_GUIDE);
-  const runtimeProvisioning = await provisionCliWorkspaceRuntime({
-    workspaceRoot,
-    mode: opts.mode
-  });
-  const { createWorkspaceAgentServer } = await import("@hachej/boring-workspace/app/server");
-  const app = await createWorkspaceAgentServer({
+  console.log(`
+  starting ${url} \u2026`);
+  const app = await createFolderModeApp({
     workspaceRoot,
     mode: opts.mode,
-    logger: false,
-    provisionWorkspace: false,
-    runtimeProvisioning
+    projectName
   });
-  app.get("/api/v1/workspace/meta", async () => ({
-    workspaceRoot,
-    projectName,
-    version: CLI_VERSION
-  }));
   await registerStatic(app, opts.publicDir);
   await app.listen({ port: opts.port, host: opts.host });
-  console.log(`
-  http://localhost:${opts.port}
+  console.log(`  ${url}  ready
 `);
-  openBrowser(`http://localhost:${opts.port}`);
+  openBrowser(url);
 }
-async function startWorkspacesMode(opts) {
-  const [workspaceAppServer, workspaceServer, agentServer, fastifyModule] = await Promise.all([
+async function createWorkspacesModeApp(opts) {
+  const [workspaceAppServer, workspaceServer, agentServer, fastifyModule, { createPluginFrontRuntimeHost }] = await Promise.all([
     import("@hachej/boring-workspace/app/server"),
     import("@hachej/boring-workspace/server"),
     import("@hachej/boring-agent/server"),
-    import("fastify")
+    import("fastify"),
+    import("./pluginFrontRuntime.js")
   ]);
-  const registry = createLocalWorkspaceRegistry();
+  const registry = createLocalWorkspaceRegistry(opts.registryPath);
   const app = fastifyModule.default({ logger: false, bodyLimit: 16 * 1024 * 1024 });
+  const diagnosticsStore = createRuntimePluginDiagnosticsStore();
+  const runtimeHost = await createPluginFrontRuntimeHost({
+    onDiagnostic: (diagnostic) => diagnosticsStore.record(diagnostic)
+  });
+  await runtimeHost.registerRoutes(app);
   const bridges = /* @__PURE__ */ new Map();
+  const workspaceEventClosers = /* @__PURE__ */ new Map();
+  const pluginRuntimes = /* @__PURE__ */ new Map();
+  const pluginPiSnapshots = /* @__PURE__ */ new Map();
+  const runtimeProvisioningByWorkspace = /* @__PURE__ */ new Map();
   function getBridge(workspaceId) {
     let bridge = bridges.get(workspaceId);
     if (!bridge) {
@@ -224,6 +399,65 @@ async function startWorkspacesMode(opts) {
   async function workspaceFromRequest(request) {
     return await requireWorkspace(resolveWorkspaceIdFromRequest(request));
   }
+  function pluginRuntimeKey(workspace) {
+    return `${workspace.id}:${workspace.path}`;
+  }
+  function syncLoadedPluginPiSnapshot(workspace, manager) {
+    pluginPiSnapshots.set(pluginRuntimeKey(workspace), manager.inspectLoadedPiSnapshot());
+  }
+  function getOrCreatePluginRuntime(workspace) {
+    const key = pluginRuntimeKey(workspace);
+    let runtime = pluginRuntimes.get(key);
+    if (!runtime) {
+      const manager = createCliPluginAssetManager(workspace.path, {
+        frontTargetResolver: runtimeHost.createFrontTargetResolver(workspace.id),
+        includeLegacyFrontUrl: false
+      });
+      runtime = {
+        manager,
+        ensureLoaded: manager.load().then(() => {
+          syncLoadedPluginPiSnapshot(workspace, manager);
+        })
+      };
+      pluginRuntimes.set(key, runtime);
+    }
+    return runtime;
+  }
+  async function getLoadedPluginRuntime(workspace) {
+    const runtime = getOrCreatePluginRuntime(workspace);
+    await runtime.ensureLoaded;
+    return runtime;
+  }
+  function getLoadedPluginPiSnapshot(workspace) {
+    return pluginPiSnapshots.get(pluginRuntimeKey(workspace)) ?? {
+      additionalSkillPaths: [],
+      packages: [],
+      extensionPaths: []
+    };
+  }
+  async function disposeWorkspaceRuntime(workspace) {
+    for (const close of workspaceEventClosers.get(workspace.id) ?? []) {
+      try {
+        close();
+      } catch {
+      }
+    }
+    workspaceEventClosers.delete(workspace.id);
+    const runtimeKey = pluginRuntimeKey(workspace);
+    pluginRuntimes.delete(runtimeKey);
+    pluginPiSnapshots.delete(runtimeKey);
+    runtimeProvisioningByWorkspace.delete(workspace.id);
+    bridges.delete(workspace.id);
+    diagnosticsStore.disposeWorkspace(workspace.id);
+    await runtimeHost.disposeWorkspace(workspace.id);
+  }
+  function reloadDiagnostics(scan) {
+    return scan.errors.map((error) => ({
+      source: "workspaces-plugin-manager",
+      message: error.message,
+      pluginId: error.id
+    }));
+  }
   app.get("/api/v1/local-workspaces", async () => ({
     workspaces: await registry.list()
   }));
@@ -243,10 +477,12 @@ async function startWorkspacesMode(opts) {
       });
     }
   });
-  app.delete("/api/v1/local-workspaces/:id", async (request) => {
+  app.delete("/api/v1/local-workspaces/:id", async (request, reply) => {
     const { id } = request.params;
+    const workspace = await registry.get(id);
     await registry.remove(id);
-    return { ok: true };
+    if (workspace) await disposeWorkspaceRuntime(workspace);
+    return reply.send({ ok: true });
   });
   app.get("/api/v1/workspaces", async () => ({
     workspaces: (await registry.list()).map(toCoreWorkspace)
@@ -260,20 +496,50 @@ async function startWorkspacesMode(opts) {
   await app.register(agentServer.registerAgentRoutes, {
     mode: opts.mode,
     systemPromptAppend: workspaceAppServer.buildWorkspaceContextPrompt(),
+    getSystemPromptDynamic: async ({ workspaceId }) => {
+      const workspace = await requireWorkspace(workspaceId);
+      await getLoadedPluginRuntime(workspace);
+      return getLoadedPluginPiSnapshot(workspace).systemPromptAppend;
+    },
     getWorkspaceId: async (request) => (await workspaceFromRequest(request)).id,
     getWorkspaceRoot: async (workspaceId) => (await requireWorkspace(workspaceId)).path,
     getSessionNamespace: async ({ workspaceId }) => `local-workspace-${workspaceId}`,
-    provisionRuntime: async ({ workspaceRoot, runtimeMode, runtimeLayout, provisioningAdapter }) => {
-      return await provisionCliWorkspaceRuntime({
+    provisionRuntime: async ({ workspaceId, workspaceRoot, runtimeMode, runtimeLayout, provisioningAdapter }) => {
+      if (runtimeProvisioningByWorkspace.has(workspaceId)) {
+        return runtimeProvisioningByWorkspace.get(workspaceId);
+      }
+      const provisioned = await provisionCliWorkspaceRuntime({
         workspaceRoot,
         mode: runtimeMode,
+        provisionWorkspace: opts.provisionWorkspace,
         adapter: provisioningAdapter,
-        runtimeLayout
+        runtimeLayout,
+        plugins: workspaceAppServer.readWorkspacePluginPackageRuntimePlugins(resolveCliBoringPluginDirs(workspaceRoot))
       });
+      runtimeProvisioningByWorkspace.set(workspaceId, provisioned);
+      return provisioned;
+    },
+    beforeReload: async ({ workspaceId }) => {
+      const workspace = await requireWorkspace(workspaceId);
+      const runtime = await getLoadedPluginRuntime(workspace);
+      const scan = await runtime.manager.load();
+      syncLoadedPluginPiSnapshot(workspace, runtime.manager);
+      syncRuntimeHostFromPluginEvents(runtimeHost, workspaceId, scan.events);
+      return {
+        restart_warnings: workspaceServer.collectRestartWarnings(scan.events),
+        diagnostics: reloadDiagnostics(scan)
+      };
+    },
+    getPi: async ({ workspaceId, workspaceRoot }) => {
+      const workspace = await requireWorkspace(workspaceId);
+      await getLoadedPluginRuntime(workspace);
+      return {
+        additionalSkillPaths: [join(workspaceRoot, ".agents", "skills")],
+        packages: [],
+        extensionPaths: [],
+        getHotReloadableResources: () => getLoadedPluginPiSnapshot(workspace)
+      };
     },
-    getPi: async ({ workspaceRoot }) => ({
-      additionalSkillPaths: [join(workspaceRoot, ".agents", "skills")]
-    }),
     getExtraTools: async ({ workspaceId, workspaceRoot, workspaceFsCapability }) => [
       ...workspaceServer.createWorkspaceUiTools(getBridge(workspaceId), {
         workspaceRoot: workspaceFsCapability === "strong" ? workspaceRoot : void 0
@@ -283,23 +549,127 @@ async function startWorkspacesMode(opts) {
   await app.register(workspaceServer.uiRoutes, {
     getBridge: async (request) => getBridge((await workspaceFromRequest(request)).id)
   });
+  app.get("/api/v1/runtime-plugin-diagnostics", async (request) => {
+    const workspace = await workspaceFromRequest(request);
+    const runtime = await getLoadedPluginRuntime(workspace);
+    return buildRuntimePluginDiagnosticsResponse({
+      workspaceId: workspace.id,
+      loaded: runtime.manager.inspectLoaded(),
+      errors: runtime.manager.getErrors(),
+      host: diagnosticsStore.snapshot(workspace.id)
+    });
+  });
+  app.get("/api/v1/agent-plugins", async (request) => {
+    const workspace = await workspaceFromRequest(request);
+    const runtime = await getLoadedPluginRuntime(workspace);
+    return runtime.manager.list();
+  });
+  app.get("/api/v1/agent-plugins/:id/error", async (request, reply) => {
+    const workspace = await workspaceFromRequest(request);
+    const runtime = await getLoadedPluginRuntime(workspace);
+    const { id } = request.params;
+    const error = runtime.manager.getError(id);
+    if (error == null) return reply.code(404).send({ error: "not_found" });
+    return reply.type("text/plain").send(error);
+  });
+  app.get("/api/v1/agent-plugins/events", async (request, reply) => {
+    const workspace = await workspaceFromRequest(request);
+    const runtime = await getLoadedPluginRuntime(workspace);
+    const manager = runtime.manager;
+    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 = (eventName, payload) => {
+      try {
+        res.write(`event: ${eventName}
+`);
+        res.write(`data: ${JSON.stringify(payload)}
+
+`);
+      } catch {
+      }
+    };
+    const liveQueue = [];
+    let replaying = true;
+    const unsubscribe = manager.subscribe((event) => {
+      if (event.type === "boring.plugin.unload" || event.type === "boring.plugin.load" && !event.frontTarget) {
+        runtimeHost.untrackPlugin(workspace.id, event.id);
+      }
+      const payload = {
+        ...event,
+        workspaceId: workspace.id,
+        replay: false
+      };
+      if (replaying) {
+        liveQueue.push({ eventName: event.type, payload });
+        return;
+      }
+      write(event.type, payload);
+    });
+    for (const plugin of manager.list()) {
+      write("boring.plugin.load", {
+        type: "boring.plugin.load",
+        id: plugin.id,
+        boring: plugin.boring,
+        version: plugin.version,
+        revision: plugin.revision,
+        ...plugin.frontTarget ? { frontTarget: plugin.frontTarget } : {},
+        workspaceId: workspace.id,
+        replay: true
+      });
+    }
+    write("boring.plugin.replay-complete", {
+      type: "boring.plugin.replay-complete",
+      workspaceId: workspace.id,
+      replay: true
+    });
+    replaying = false;
+    for (const event of liveQueue) write(event.eventName, event.payload);
+    const heartbeat = setInterval(() => {
+      try {
+        res.write(": heartbeat\n\n");
+      } catch {
+      }
+    }, 25e3);
+    const closeStream = () => {
+      clearInterval(heartbeat);
+      unsubscribe();
+      workspaceEventClosers.get(workspace.id)?.delete(closeStream);
+      try {
+        res.end();
+      } catch {
+      }
+    };
+    const closers = workspaceEventClosers.get(workspace.id) ?? /* @__PURE__ */ new Set();
+    closers.add(closeStream);
+    workspaceEventClosers.set(workspace.id, closers);
+    request.raw.on("close", closeStream);
+  });
   app.get("/api/v1/workspace/meta", async () => ({
     projectName: "Boring UI",
     workspacesMode: true,
-    version: CLI_VERSION
+    version: CLI_VERSION,
+    runtimePluginFrontLoadingEnabled: true,
+    runtimePluginTrustLabel: RUNTIME_PLUGIN_TRUST_LABEL,
+    runtimePluginTrustDescription: RUNTIME_PLUGIN_TRUST_DESCRIPTION,
+    runtimePluginDiagnosticsEnabled: true
   }));
+  return app;
+}
+async function startWorkspacesMode(opts) {
+  const app = await createWorkspacesModeApp({ mode: opts.mode });
+  const registry = createLocalWorkspaceRegistry();
   await registerStatic(app, opts.publicDir);
   await app.listen({ port: opts.port, host: opts.host });
   const initialWorkspace = (await registry.list()).find((workspace) => workspace.available);
   const initialUrl = initialWorkspace ? `http://localhost:${opts.port}/workspace/${encodeURIComponent(initialWorkspace.id)}` : `http://localhost:${opts.port}`;
-  console.log(`
-Boring UI`);
   console.log(`  workspaces ${registry.path}`);
-  console.log(`  mode       ${opts.cliMode}`);
-  console.log(`  port       ${opts.port}`);
-  console.log(`  host       ${opts.host}`);
-  console.log(`
-  ${initialUrl}
+  console.log(`  ${initialUrl}  ready
 `);
   if (await checkAuth() === 0) console.log(AUTH_GUIDE);
   openBrowser(initialUrl);
@@ -457,6 +827,7 @@ async function runCli(options) {
       mode: { type: "string", short: "m" },
       name: { type: "string", short: "n" },
       path: { type: "string" },
+      json: { type: "boolean" },
       help: { type: "boolean", short: "h" }
     },
     allowPositionals: true,
@@ -468,12 +839,26 @@ async function runCli(options) {
   }
   const port = Number(args.port ?? process.env.PORT) || 5200;
   const host = args.host ?? process.env.HOST ?? "0.0.0.0";
-  const rawMode = args.mode ?? process.env.BORING_MODE ?? "local-sandbox";
-  if (!(rawMode in MODE_MAP)) {
-    throw new Error(`invalid --mode "${rawMode}". Valid options: ${Object.keys(MODE_MAP).join(", ")}`);
+  const rawMode = args.mode ?? process.env.BORING_MODE;
+  let cliMode;
+  let mode;
+  if (rawMode) {
+    if (!(rawMode in MODE_MAP)) {
+      throw new Error(`invalid --mode "${rawMode}". Valid options: ${Object.keys(MODE_MAP).join(", ")}`);
+    }
+    cliMode = rawMode;
+    mode = MODE_MAP[cliMode];
+  } else {
+    const agent = await import("@hachej/boring-agent/server");
+    const detected = agent.autoDetectMode();
+    if (detected === "local") {
+      cliMode = "local-sandbox";
+      mode = "local";
+    } else {
+      cliMode = "local";
+      mode = "direct";
+    }
   }
-  const cliMode = rawMode;
-  const mode = MODE_MAP[cliMode];
   const base = {
     publicDir: options.publicDir,
     port,
@@ -496,6 +881,10 @@ async function runCli(options) {
     });
     return;
   }
+  if (positionals[0] === "plugin-status") {
+    handlePluginStatusCommand({ json: args.json === true });
+    return;
+  }
   if (positionals[0] === "scaffold-plugin") {
     await handleScaffoldPluginCommand({ positionals });
     return;
@@ -512,6 +901,32 @@ async function runCli(options) {
 function defaultWorkspaceRoot() {
   return process.env.BORING_AGENT_WORKSPACE_ROOT ?? process.cwd();
 }
+function workspaceLocalPluginRootsEnabled() {
+  const raw = process.env.BORING_AGENT_WORKSPACE_LOCAL_PLUGIN_ROOTS;
+  if (raw == null || raw.trim() === "") return true;
+  return !["0", "false", "no", "off"].includes(raw.trim().toLowerCase());
+}
+function buildPluginStatus() {
+  const workspaceRoot = resolve(defaultWorkspaceRoot());
+  const enabled = workspaceLocalPluginRootsEnabled();
+  return {
+    workspaceLocalPluginRoots: enabled,
+    workspaceRoot,
+    extensionsDir: join(workspaceRoot, ".pi", "extensions"),
+    reloadSupported: enabled,
+    ...enabled ? {} : {
+      reason: "This runtime writes to a remote sandbox; host-side plugin discovery cannot load .pi/extensions from there."
+    }
+  };
+}
+function handlePluginStatusCommand(opts) {
+  const status = buildPluginStatus();
+  if (opts.json) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+  console.log(status.workspaceLocalPluginRoots ? `workspace-local plugin roots enabled: ${status.extensionsDir}` : `workspace-local plugin roots disabled: ${status.reason}`);
+}
 async function handleVerifyPluginCommand(opts) {
   const maybeName = opts.positionals[1];
   const maybeWorkspace = opts.positionals[2];
@@ -542,6 +957,10 @@ async function handleScaffoldPluginCommand(opts) {
   if (!name) {
     throw new Error("usage: boring-ui scaffold-plugin <name> [workspace]");
   }
+  const status = buildPluginStatus();
+  if (!status.workspaceLocalPluginRoots) {
+    throw new Error(`${status.reason} Do not scaffold into .pi/extensions in this runtime.`);
+  }
   const workspaceRoot = resolve(opts.positionals[2] ?? defaultWorkspaceRoot());
   const { scaffoldPlugin } = await import("./scaffoldPlugin.js");
   const result = scaffoldPlugin({ name, workspaceRoot });
@@ -563,6 +982,8 @@ async function handleScaffoldPluginCommand(opts) {
 }
 export {
   createBoringUiCliRuntimePlugin,
+  createFolderModeApp,
+  createWorkspacesModeApp,
   provisionCliWorkspaceRuntime,
   registerStatic,
   resolveBoringUiCliPackageRoot,

package/dist/server/pluginDiscovery.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import {
+  BoringPluginAssetManager
+} from "@hachej/boring-workspace/server";
+import {
+  readWorkspacePluginPackagePiSnapshot
+} from "@hachej/boring-workspace/app/server";
+function getGlobalPiExtensionsRoot(options = {}) {
+  return resolve(options.globalRoot ?? join(homedir(), ".pi", "agent", "extensions"));
+}
+function resolveCliBoringPluginDirs(workspaceRoot, options = {}) {
+  const roots = [
+    getGlobalPiExtensionsRoot(options),
+    resolve(workspaceRoot, ".pi", "extensions")
+  ];
+  return [...new Set(roots)];
+}
+function readCliPluginPiSnapshot(workspaceRoot, options = {}) {
+  return readWorkspacePluginPackagePiSnapshot(resolveCliBoringPluginDirs(workspaceRoot, options));
+}
+function createCliPluginAssetManager(workspaceRoot, options = {}) {
+  return new BoringPluginAssetManager({
+    pluginDirs: resolveCliBoringPluginDirs(workspaceRoot, options),
+    errorRoot: resolve(workspaceRoot, ".boring-agent", "plugin-errors"),
+    frontTargetResolver: options.frontTargetResolver,
+    includeLegacyFrontUrl: options.includeLegacyFrontUrl
+  });
+}
+export {
+  createCliPluginAssetManager,
+  getGlobalPiExtensionsRoot,
+  readCliPluginPiSnapshot,
+  resolveCliBoringPluginDirs
+};