@hachej/boring-workspace 0.1.0

package/dist/server.js

@@ -0,0 +1,811 @@
+// src/server/bridge/createInMemoryBridge.ts
+var MAX_PENDING_COMMANDS = 1e3;
+function createInMemoryBridge() {
+  let state = null;
+  let nextSeq = 1;
+  const subscribers = /* @__PURE__ */ new Set();
+  const pendingCommands = [];
+  function enqueuePending(command) {
+    pendingCommands.push(command);
+    if (pendingCommands.length > MAX_PENDING_COMMANDS) {
+      pendingCommands.splice(0, pendingCommands.length - MAX_PENDING_COMMANDS);
+    }
+  }
+  return {
+    async getState() {
+      return state;
+    },
+    async setState(s) {
+      state = s;
+    },
+    async postCommand(cmd) {
+      const seq = nextSeq++;
+      const annotated = { ...cmd, seq };
+      if (subscribers.size === 0) enqueuePending(annotated);
+      for (const handler of subscribers) {
+        handler(annotated);
+      }
+      return { seq, status: "ok" };
+    },
+    subscribeCommands(handler) {
+      subscribers.add(handler);
+      return () => {
+        subscribers.delete(handler);
+      };
+    },
+    async drainCommands() {
+      if (pendingCommands.length === 0) return [];
+      return pendingCommands.splice(0, pendingCommands.length);
+    }
+  };
+}
+
+// src/server/ui-control/http/uiRoutes.ts
+import { z } from "zod";
+var UI_BRIDGE_PROTOCOL_VERSION = 1;
+var HEARTBEAT_MS = 15e3;
+var setStateBodySchema = z.object({
+  state: z.record(z.unknown()),
+  causedBy: z.enum(["user", "agent", "restore"]).optional()
+});
+var postCommandBodySchema = z.object({
+  kind: z.string().min(1),
+  params: z.record(z.unknown()).default({})
+});
+function createBodyValidator(schema) {
+  return async function validateBody(request, reply) {
+    const parsed = schema.safeParse(request.body);
+    if (!parsed.success) {
+      const firstIssue = parsed.error.issues[0];
+      const fieldName = firstIssue?.path?.map((segment) => String(segment)).join(".");
+      reply.code(400).send({
+        error: "validation_error",
+        message: firstIssue?.message ?? "Invalid request body",
+        field: fieldName || void 0
+      });
+      return;
+    }
+    request.body = parsed.data;
+  };
+}
+function uiRoutes(app, opts, done) {
+  const fallbackBridge = opts.bridge;
+  const validateSetState = createBodyValidator(setStateBodySchema);
+  const validatePostCommand = createBodyValidator(postCommandBodySchema);
+  const resolveBridge = async (request) => {
+    if (opts.getBridge) return await opts.getBridge(request);
+    if (fallbackBridge) return fallbackBridge;
+    throw new Error("uiRoutes requires bridge or getBridge");
+  };
+  const encodeCommand = (cmd) => ({
+    v: UI_BRIDGE_PROTOCOL_VERSION,
+    seq: cmd.seq,
+    kind: cmd.kind,
+    params: cmd.params
+  });
+  app.get("/api/v1/ui/state", async (request) => {
+    const bridge = await resolveBridge(request);
+    return await bridge.getState() ?? {};
+  });
+  app.put(
+    "/api/v1/ui/state",
+    { preHandler: validateSetState },
+    async (request, reply) => {
+      const body = request.body;
+      const bridge = await resolveBridge(request);
+      await bridge.setState(body.state);
+      return reply.code(204).send();
+    }
+  );
+  app.post(
+    "/api/v1/ui/commands",
+    { preHandler: validatePostCommand },
+    async (request) => {
+      const body = request.body;
+      const bridge = await resolveBridge(request);
+      const cmd = { kind: body.kind, params: body.params };
+      return await bridge.postCommand(cmd);
+    }
+  );
+  app.get("/api/v1/ui/commands/next", async (request, reply) => {
+    const bridge = await resolveBridge(request);
+    const query = request.query;
+    if (query.poll === "true") {
+      const batch = bridge.drainCommands ? await bridge.drainCommands() : [];
+      return batch.map(encodeCommand);
+    }
+    reply.raw.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive"
+    });
+    reply.raw.write(
+      `event: init
+data: ${JSON.stringify({ v: UI_BRIDGE_PROTOCOL_VERSION })}
+
+`
+    );
+    if (bridge.drainCommands) {
+      const queued = await bridge.drainCommands();
+      for (const cmd of queued) {
+        reply.raw.write(
+          `event: command
+data: ${JSON.stringify(encodeCommand(cmd))}
+
+`
+        );
+      }
+    }
+    const unsub = bridge.subscribeCommands((cmd) => {
+      reply.raw.write(`event: command
+data: ${JSON.stringify(encodeCommand(cmd))}
+
+`);
+    });
+    const heartbeat = setInterval(() => {
+      if (reply.raw.writableEnded) return;
+      reply.raw.write(
+        `event: heartbeat
+data: ${JSON.stringify({ v: UI_BRIDGE_PROTOCOL_VERSION })}
+
+`
+      );
+    }, HEARTBEAT_MS);
+    request.raw.on("close", () => {
+      clearInterval(heartbeat);
+      unsub();
+    });
+    reply.hijack();
+  });
+  done();
+}
+
+// src/server/ui-control/tools/uiTools.ts
+import { access } from "fs/promises";
+import { resolve, isAbsolute, relative } from "path";
+function makeError(message) {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true
+  };
+}
+var PATH_BEARING_KINDS = /* @__PURE__ */ new Set(["openFile", "expandToFile", "navigateToLine"]);
+function getPathParam(kind, params) {
+  const raw = kind === "navigateToLine" ? params.file : params.path;
+  return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+async function validatePath(workspaceRoot, relPath) {
+  if (isAbsolute(relPath)) {
+    return {
+      ok: false,
+      reason: `path "${relPath}" is absolute \u2014 pass a path relative to the workspace root (${workspaceRoot}).`
+    };
+  }
+  const resolved = resolve(workspaceRoot, relPath);
+  const rel = relative(workspaceRoot, resolved);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return {
+      ok: false,
+      reason: `path "${relPath}" escapes the workspace root (${workspaceRoot}).`
+    };
+  }
+  try {
+    await access(resolved);
+    return { ok: true };
+  } catch {
+    return {
+      ok: false,
+      reason: `file not found at "${relPath}" (relative to workspace root ${workspaceRoot}). Try find or grep to locate the file before retrying openFile.`
+    };
+  }
+}
+function createGetUiStateTool(uiBridge) {
+  return {
+    name: "get_ui_state",
+    description: [
+      "Read the current workspace UI state. Returns a JSON object with:",
+      "- workbenchOpen (boolean): is the right-side workbench pane visible?",
+      "- drawerOpen (boolean): is the left-side sessions drawer visible?",
+      "- openTabs (array): tabs currently open in the workbench, each with",
+      "  { id, title, params }. params.path is the file path for file tabs.",
+      "- activeTab (string|null): id of the currently focused tab.",
+      "- activeFile (string|null): convenience \u2014 params.path of activeTab.",
+      "- availablePanels (array of strings): every panel component the host",
+      "  has registered. Use these names with exec_ui openPanel below.",
+      "",
+      "Call this BEFORE exec_ui openPanel to learn which `component` ids",
+      "are valid for this app. Common built-ins: code-editor, markdown-editor,",
+      "csv-viewer. Apps may register more (e.g. chart-canvas, series-viewer)."
+    ].join("\n"),
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    async execute() {
+      try {
+        const state = await uiBridge.getState();
+        return {
+          content: [{ type: "text", text: JSON.stringify(state ?? {}) }],
+          details: state
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "get_ui_state failed";
+        return makeError(message);
+      }
+    }
+  };
+}
+var VERIFIABLE_KINDS = /* @__PURE__ */ new Set(["openFile", "openPanel", "openSurface", "closePanel"]);
+function isVerified(kind, params, state) {
+  if (!state) return false;
+  const tabs = state.openTabs ?? [];
+  if (kind === "openFile") {
+    const path = typeof params.path === "string" ? params.path : null;
+    return path !== null && tabs.some((t) => t.params?.path === path);
+  }
+  if (kind === "openPanel") {
+    const id = typeof params.id === "string" ? params.id : null;
+    return id !== null && tabs.some((t) => t.id === id);
+  }
+  if (kind === "closePanel") {
+    const id = typeof params.id === "string" ? params.id : null;
+    return id !== null && !tabs.some((t) => t.id === id);
+  }
+  return true;
+}
+function createExecUiTool(uiBridge, opts = {}) {
+  const { workspaceRoot } = opts;
+  const verifyDelayMs = opts.verifyDelayMs ?? 200;
+  const verifyRetries = opts.verifyRetries ?? 2;
+  const verifyIntervalMs = opts.verifyIntervalMs ?? 200;
+  return {
+    name: "exec_ui",
+    description: [
+      "Execute a UI command in the workspace. Use this to open files, panels,",
+      "navigate to lines, or show notifications.",
+      "",
+      "CRITICAL: When the user asks for a concrete UI action (open/show/",
+      "focus/navigate), execute it immediately via exec_ui. Do not ask a",
+      "confirmation question first unless the target is genuinely ambiguous",
+      "or unsafe.",
+      "",
+      "CRITICAL: When the user asks to open / show / display / navigate to a",
+      "file, ALWAYS call exec_ui openFile. Never skip the call based on",
+      "conversation history OR get_ui_state output \u2014 even if openTabs already",
+      "lists the file. State can drift (the user may have closed the tab,",
+      "the persisted state may be stale, the tab may not be focused). Calling",
+      "openFile when the file is already open is idempotent: it focuses the",
+      'tab. Saying "already opened" without calling the tool is a bug \u2014 the',
+      "user explicitly requested an action; honor it.",
+      "",
+      "Supported `kind` values:",
+      "",
+      "  openFile     params: { path: string, mode?: 'view'|'edit'|'diff' }",
+      "               \u2014 Open a file in the workbench. The workbench pane",
+      "                 auto-opens if collapsed. Path must be relative to the",
+      "                 workspace root (e.g. `src/foo.ts`, not `foo.ts` if it",
+      "                 lives under src/).",
+      "                 Recovery on file-not-found: this tool stat-checks the",
+      "                 path server-side and returns an error if it doesn't",
+      "                 exist. On that error, immediately call find (or",
+      "                 grep) to locate the file, then call exec_ui",
+      "                 openFile AGAIN using the EXACT path returned \u2014 don't",
+      "                 give up and don't switch to the read tool. Repeat",
+      "                 until openFile succeeds or no candidate is found.",
+      "                 Example: {kind:'openFile', params:{path:'README.md'}}",
+      "",
+      "  openPanel    params: { id: string, component: string,",
+      "                         title?: string, params?: object }",
+      "               \u2014 Open an app-specific panel. `component` MUST be one",
+      "                 of the ids returned by get_ui_state's availablePanels.",
+      "                 `id` is the tab instance id (re-use the same id to",
+      "                 re-activate an existing tab; pick a unique id per",
+      "                 distinct artifact). `params` is forwarded to the",
+      "                 panel component.",
+      "                 Example: {kind:'openPanel', params:{id:'chart:GDPC1',",
+      "                          component:'chart-canvas',",
+      "                          params:{seriesId:'GDPC1'}}}",
+      "",
+      "  openSurface  params: { kind: string, target: string, meta?: object }",
+      "               \u2014 Open a plugin-owned target through the workspace",
+      "                 surface resolver registry. Use this when a plugin",
+      "                 defines the mapping from domain target to panel",
+      "                 component, for example a data catalog row.",
+      "                 Example: {kind:'openSurface', params:{",
+      "                          kind:'data-catalog.open-row',",
+      "                          target:'orders_daily',",
+      "                          meta:{catalogId:'data-catalog'}}}",
+      "",
+      "  closePanel   params: { id: string }",
+      "  closeWorkbenchLeftPane params: {}",
+      "               \u2014 Hide the workbench's left sources/files pane while",
+      "                 keeping the workbench itself open.",
+      "  navigateToLine params: { file: string, line: number }",
+      "  expandToFile params: { path: string }",
+      "  showNotification params: { msg: string, level?: 'info'|'warn'|'error' }",
+      "",
+      "Returns { seq, status, uiState? }. For openFile / openPanel / openSurface /",
+      "closePanel the response includes a `uiState` snapshot taken ~400ms after",
+      "dispatch \u2014 check uiState.openTabs to confirm the action took effect.",
+      "If the expected tab is missing from openTabs the frontend silently",
+      "rejected the command (unknown panel component, unregistered surface",
+      "resolver, or surface not yet ready). For other kinds only { seq, status }",
+      "is returned. To open a FILE prefer openFile (path-aware) over openPanel",
+      "(which is for non-file panes like charts)."
+    ].join("\n"),
+    parameters: {
+      type: "object",
+      properties: {
+        kind: {
+          type: "string",
+          enum: [
+            "openFile",
+            "openPanel",
+            "openSurface",
+            "closePanel",
+            "closeWorkbenchLeftPane",
+            "navigateToLine",
+            "expandToFile",
+            "showNotification"
+          ]
+        },
+        params: { type: "object" }
+      },
+      required: ["kind"],
+      additionalProperties: false
+    },
+    async execute(input) {
+      const kind = input.kind;
+      if (typeof kind !== "string" || kind.length === 0) {
+        return makeError("kind is required");
+      }
+      const params = input.params;
+      if (params !== void 0 && (typeof params !== "object" || params === null || Array.isArray(params))) {
+        return makeError("params must be an object when provided");
+      }
+      const cmdParams = params ?? {};
+      if (kind === "openSurface") {
+        if (typeof cmdParams.kind !== "string" || cmdParams.kind.length === 0) {
+          return makeError("openSurface: kind param is required");
+        }
+        if (typeof cmdParams.target !== "string" || cmdParams.target.length === 0) {
+          return makeError("openSurface: target param is required");
+        }
+        if (cmdParams.meta !== void 0 && (typeof cmdParams.meta !== "object" || cmdParams.meta === null || Array.isArray(cmdParams.meta))) {
+          return makeError("openSurface: meta must be an object when provided");
+        }
+      }
+      if (workspaceRoot && PATH_BEARING_KINDS.has(kind)) {
+        const relPath = getPathParam(kind, cmdParams);
+        if (!relPath) {
+          return makeError(
+            `${kind}: ${kind === "navigateToLine" ? "file" : "path"} param is required`
+          );
+        }
+        const check = await validatePath(workspaceRoot, relPath);
+        if (!check.ok) {
+          return makeError(check.reason);
+        }
+      }
+      try {
+        const command = { kind, params: cmdParams };
+        const result = await uiBridge.postCommand(command);
+        if (result.status === "error") {
+          return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+            isError: true,
+            details: result
+          };
+        }
+        if (verifyDelayMs > 0 && VERIFIABLE_KINDS.has(kind)) {
+          await new Promise((r) => setTimeout(r, verifyDelayMs));
+          let uiState = await uiBridge.getState();
+          for (let i = 0; i < verifyRetries; i++) {
+            if (isVerified(kind, cmdParams, uiState)) break;
+            await new Promise((r) => setTimeout(r, verifyIntervalMs));
+            uiState = await uiBridge.getState();
+          }
+          const combined = { ...result, uiState };
+          return {
+            content: [{ type: "text", text: JSON.stringify(combined) }],
+            details: combined
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(result) }],
+          details: result
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "exec_ui failed";
+        return makeError(message);
+      }
+    }
+  };
+}
+function createWorkspaceUiTools(uiBridge, opts = {}) {
+  return [createGetUiStateTool(uiBridge), createExecUiTool(uiBridge, opts)];
+}
+
+// src/server/plugins/piPackages.ts
+import {
+  compactPiPackages,
+  mergePiPackageSources,
+  piPackageSourceKey,
+  PI_PACKAGE_RESOURCE_FILTERS
+} from "@hachej/boring-agent/server";
+
+// src/server/plugins/defineServerPlugin.ts
+var ServerPluginError = class extends Error {
+  constructor(message) {
+    super(message);
+  }
+};
+function fail(pluginId, message) {
+  throw new ServerPluginError(`server plugin "${pluginId}": ${message}`);
+}
+function isUrl(value) {
+  return value instanceof URL;
+}
+function isPathLike(value) {
+  return typeof value === "string" && value.length > 0 || isUrl(value);
+}
+function validateAgentTool(pluginId, tool, index) {
+  if (!tool || typeof tool !== "object") {
+    fail(pluginId, `agentTools[${index}] must be an object`);
+  }
+  const candidate = tool;
+  if (!candidate.name || typeof candidate.name !== "string") {
+    fail(pluginId, `agentTools[${index}].name must be a non-empty string`);
+  }
+  if (typeof candidate.description !== "string") {
+    fail(pluginId, `agentTools[${index}].description must be a string`);
+  }
+  if (!candidate.parameters || typeof candidate.parameters !== "object") {
+    fail(pluginId, `agentTools[${index}].parameters must be an object`);
+  }
+  if (typeof candidate.execute !== "function") {
+    fail(pluginId, `agentTools[${index}].execute must be a function`);
+  }
+}
+function validatePiPackages(pluginId, piPackages) {
+  for (let i = 0; i < piPackages.length; i++) {
+    const source = piPackages[i];
+    if (typeof source === "string") {
+      if (source.length === 0) {
+        fail(pluginId, `piPackages[${i}] must be a non-empty string`);
+      }
+      continue;
+    }
+    if (!source || typeof source !== "object" || Array.isArray(source)) {
+      fail(pluginId, `piPackages[${i}] must be a string or package source object`);
+    }
+    const candidate = source;
+    if (typeof candidate.source !== "string" || candidate.source.length === 0) {
+      fail(pluginId, `piPackages[${i}].source must be a non-empty string`);
+    }
+    for (const key of PI_PACKAGE_RESOURCE_FILTERS) {
+      const value = candidate[key];
+      if (value === void 0) continue;
+      if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string" || entry.length === 0)) {
+        fail(pluginId, `piPackages[${i}].${key} must be a string array when provided`);
+      }
+    }
+  }
+}
+function validateProvisioning(pluginId, provisioning) {
+  if (!provisioning || typeof provisioning !== "object") {
+    fail(pluginId, "provisioning must be an object");
+  }
+  if (provisioning.templateDirs !== void 0) {
+    if (!Array.isArray(provisioning.templateDirs)) {
+      fail(pluginId, "provisioning.templateDirs must be an array when provided");
+    }
+    for (let i = 0; i < provisioning.templateDirs.length; i++) {
+      const contribution = provisioning.templateDirs[i];
+      if (!contribution || typeof contribution !== "object") {
+        fail(pluginId, `provisioning.templateDirs[${i}] must be an object`);
+      }
+      if (!contribution.id || typeof contribution.id !== "string") {
+        fail(pluginId, `provisioning.templateDirs[${i}].id must be a non-empty string`);
+      }
+      if (!isPathLike(contribution.path)) {
+        fail(pluginId, `provisioning.templateDirs[${i}].path must be a string or URL`);
+      }
+      if (contribution.target !== void 0 && typeof contribution.target !== "string") {
+        fail(pluginId, `provisioning.templateDirs[${i}].target must be a string when provided`);
+      }
+    }
+  }
+  if (provisioning.python !== void 0) {
+    if (!Array.isArray(provisioning.python)) {
+      fail(pluginId, "provisioning.python must be an array when provided");
+    }
+    for (let i = 0; i < provisioning.python.length; i++) {
+      const spec = provisioning.python[i];
+      if (!spec || typeof spec !== "object") {
+        fail(pluginId, `provisioning.python[${i}] must be an object`);
+      }
+      if (!spec.id || typeof spec.id !== "string") {
+        fail(pluginId, `provisioning.python[${i}].id must be a non-empty string`);
+      }
+      if (!isPathLike(spec.projectFile)) {
+        fail(pluginId, `provisioning.python[${i}].projectFile must be a string or URL`);
+      }
+      if (spec.extraLibs !== void 0 && (!Array.isArray(spec.extraLibs) || spec.extraLibs.some((item) => typeof item !== "string"))) {
+        fail(pluginId, `provisioning.python[${i}].extraLibs must be a string array when provided`);
+      }
+      if (spec.env !== void 0) {
+        if (!spec.env || typeof spec.env !== "object" || Array.isArray(spec.env)) {
+          fail(pluginId, `provisioning.python[${i}].env must be an object when provided`);
+        }
+        for (const [key, value] of Object.entries(spec.env)) {
+          if (!key || !isPathLike(value)) {
+            fail(pluginId, `provisioning.python[${i}].env values must be strings or URLs`);
+          }
+        }
+      }
+    }
+  }
+}
+function validateServerPlugin(plugin) {
+  if (!plugin.id || typeof plugin.id !== "string") {
+    fail(plugin.id ?? "<unknown>", "id must be a non-empty string");
+  }
+  if (plugin.label !== void 0 && typeof plugin.label !== "string") {
+    fail(plugin.id, "label must be a string when provided");
+  }
+  if (plugin.systemPrompt !== void 0 && typeof plugin.systemPrompt !== "string") {
+    fail(plugin.id, "systemPrompt must be a string when provided");
+  }
+  if (plugin.piPackages !== void 0) {
+    if (!Array.isArray(plugin.piPackages)) {
+      fail(plugin.id, "piPackages must be an array when provided");
+    }
+    validatePiPackages(plugin.id, plugin.piPackages);
+  }
+  if (plugin.agentTools !== void 0) {
+    if (!Array.isArray(plugin.agentTools)) {
+      fail(plugin.id, "agentTools must be an array when provided");
+    }
+    plugin.agentTools.forEach((tool, index) => validateAgentTool(plugin.id, tool, index));
+  }
+  if (plugin.routes !== void 0 && typeof plugin.routes !== "function") {
+    fail(plugin.id, "routes must be a Fastify plugin function when provided");
+  }
+  if (plugin.provisioning !== void 0) {
+    validateProvisioning(plugin.id, plugin.provisioning);
+  }
+}
+function defineServerPlugin(plugin) {
+  validateServerPlugin(plugin);
+  return Object.assign({}, plugin);
+}
+
+// src/server/plugins/composeServerPlugins.ts
+function compactPrompts(prompts) {
+  const text = prompts.map((prompt) => prompt?.trim()).filter((prompt) => Boolean(prompt)).join("\n\n");
+  return text || void 0;
+}
+function mergeProvisioning(contributions) {
+  const templateDirs = contributions.flatMap((entry) => entry?.templateDirs ?? []);
+  const python = contributions.flatMap((entry) => entry?.python ?? []);
+  if (templateDirs.length === 0 && python.length === 0) return void 0;
+  return {
+    ...templateDirs.length > 0 ? { templateDirs } : {},
+    ...python.length > 0 ? { python } : {}
+  };
+}
+function composeRoutes(routes) {
+  const routePlugins = routes.filter(
+    (route) => Boolean(route)
+  );
+  if (routePlugins.length === 0) return void 0;
+  return async (app) => {
+    for (const routes2 of routePlugins) {
+      await app.register(routes2);
+    }
+  };
+}
+function composeServerPlugins(options) {
+  const piPackages = compactPiPackages([
+    ...options.plugins.flatMap((plugin) => plugin.piPackages ?? []),
+    ...options.piPackages ?? []
+  ]);
+  const agentTools = [
+    ...options.plugins.flatMap((plugin) => plugin.agentTools ?? []),
+    ...options.agentTools ?? []
+  ];
+  const systemPrompt = compactPrompts([
+    ...options.plugins.map((plugin) => plugin.systemPrompt),
+    options.systemPrompt
+  ]);
+  const provisioning = mergeProvisioning([
+    ...options.plugins.map((plugin) => plugin.provisioning),
+    options.provisioning
+  ]);
+  const routes = composeRoutes([
+    ...options.plugins.map((plugin) => plugin.routes),
+    options.routes
+  ]);
+  return defineServerPlugin({
+    id: options.id,
+    ...options.label !== void 0 ? { label: options.label } : {},
+    ...piPackages.length > 0 ? { piPackages } : {},
+    ...systemPrompt ? { systemPrompt } : {},
+    ...agentTools.length > 0 ? { agentTools } : {},
+    ...provisioning ? { provisioning } : {},
+    ...routes ? { routes } : {}
+  });
+}
+
+// src/server/plugins/bootstrapServer.ts
+function collectPiPackages(plugins) {
+  return compactPiPackages(plugins.flatMap((plugin) => plugin.piPackages ?? []));
+}
+function bootstrapServer(options) {
+  const excludedDefaults = new Set(options.excludeDefaults ?? []);
+  const finalPlugins = [
+    ...(options.defaults ?? []).filter((p) => !excludedDefaults.has(p.id)),
+    ...options.plugins ?? []
+  ];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const plugin of finalPlugins) {
+    validateServerPlugin(plugin);
+    if (seenIds.has(plugin.id)) {
+      throw new Error(`plugin "${plugin.id}" registered twice`);
+    }
+    seenIds.add(plugin.id);
+  }
+  const agentTools = [];
+  for (const plugin of finalPlugins) {
+    for (const tool of plugin.agentTools ?? []) {
+      agentTools.push(tool);
+    }
+  }
+  const systemPromptAppend = finalPlugins.filter((p) => p.systemPrompt && p.systemPrompt.trim()).map((p) => p.systemPrompt.trim()).join("\n\n");
+  const piPackages = collectPiPackages(finalPlugins);
+  const provisioningContributions = finalPlugins.filter((p) => p.provisioning).map((p) => ({ id: p.id, provisioning: p.provisioning }));
+  const routeContributions = finalPlugins.filter((p) => p.routes).map((p) => ({ id: p.id, routes: p.routes }));
+  return {
+    registered: finalPlugins.map((p) => p.id),
+    systemPromptAppend,
+    piPackages,
+    agentTools,
+    provisioningContributions,
+    routeContributions
+  };
+}
+
+// src/plugins/dataCatalogPlugin/shared/constants.ts
+var DATA_CATALOG_PLUGIN_ID = "data-catalog";
+var DATA_CATALOG_DEFAULT_TOOL_NAME = "query_data_catalog";
+var DATA_CATALOG_ROW_SURFACE_KIND = "data-catalog.open-row";
+
+// src/plugins/dataCatalogPlugin/server/index.ts
+function textResult(text, details) {
+  return { content: [{ type: "text", text }], details };
+}
+function errorResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function clampLimit(value, fallback, max) {
+  const numeric = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(1, Math.min(max, Math.floor(numeric)));
+}
+function normalizeLimitOptions(options) {
+  const rawMax = options.maxLimit ?? 50;
+  const maxLimit = typeof rawMax === "number" && Number.isFinite(rawMax) ? Math.max(1, Math.floor(rawMax)) : 50;
+  const rawDefault = options.defaultLimit ?? 20;
+  const defaultLimit = typeof rawDefault === "number" && Number.isFinite(rawDefault) ? Math.max(1, Math.min(maxLimit, Math.floor(rawDefault))) : Math.min(20, maxLimit);
+  return { defaultLimit, maxLimit };
+}
+function formatBadge(row) {
+  const parts = [
+    row.leading?.code,
+    ...(row.trailing ?? []).map((badge) => badge.code),
+    row.meta
+  ].filter(Boolean);
+  return parts.length > 0 ? ` [${parts.join(", ")}]` : "";
+}
+function formatDataCatalogSearchResult(query, result) {
+  if (result.items.length === 0) {
+    return `No ${query ? `results for "${query}"` : "catalog results"}.`;
+  }
+  const lines = result.items.map((row) => {
+    const subtitle = row.subtitle ? ` \u2014 ${row.subtitle}` : "";
+    return `${row.id}: ${row.title}${subtitle}${formatBadge(row)}`;
+  });
+  const total = Number.isFinite(result.total) ? result.total : result.items.length;
+  return `Found ${total} results (showing ${result.items.length}):
+
+${lines.join("\n")}`;
+}
+function createDataCatalogAgentTool(options) {
+  const name = options.name ?? DATA_CATALOG_DEFAULT_TOOL_NAME;
+  const label = options.label ?? "data catalog";
+  const { defaultLimit, maxLimit } = normalizeLimitOptions(options);
+  return {
+    name,
+    description: `Search the ${label}. Use this before opening data visualizations or asking for a specific dataset.`,
+    parameters: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "Search keywords for datasets, series, tables, or metrics."
+        },
+        limit: {
+          type: "number",
+          description: `Maximum number of results. Default ${defaultLimit}, max ${maxLimit}.`,
+          minimum: 1,
+          maximum: maxLimit
+        }
+      },
+      required: ["query"],
+      additionalProperties: false
+    },
+    async execute(params, ctx) {
+      const query = String(params.query ?? "").trim();
+      if (!query) return errorResult("query is required");
+      const limit = clampLimit(params.limit, defaultLimit, maxLimit);
+      try {
+        const result = await options.adapter.search({
+          query,
+          filters: {},
+          limit,
+          offset: 0,
+          signal: ctx.abortSignal
+        });
+        return textResult(formatDataCatalogSearchResult(query, result), result);
+      } catch (error) {
+        return errorResult(error instanceof Error ? error.message : String(error));
+      }
+    }
+  };
+}
+function createDataCatalogSkillPrompt(options = {}) {
+  const label = options.label ?? "data catalog";
+  const toolName = options.toolName ?? DATA_CATALOG_DEFAULT_TOOL_NAME;
+  const surfaceKind = options.surfaceKind ?? DATA_CATALOG_ROW_SURFACE_KIND;
+  const guidance = options.guidance?.trim();
+  return [
+    "## Data Catalog Plugin",
+    "",
+    `Use \`${toolName}\` to search the ${label} before referencing datasets, series, tables, or metrics.`,
+    `When you need to show a catalog row to the user, use the workspace UI bridge \`openSurface\` command with \`{ kind: '${surfaceKind}', target: row.id, meta: { catalogId, row } }\` so the client plugin resolver chooses the panel.`,
+    guidance ? "" : void 0,
+    guidance || void 0
+  ].filter((line) => line !== void 0).join("\n");
+}
+function createDataCatalogServerPlugin(options) {
+  const tool = createDataCatalogAgentTool(options);
+  return defineServerPlugin({
+    id: options.id ?? DATA_CATALOG_PLUGIN_ID,
+    label: options.label ?? "Data Catalog",
+    agentTools: [tool],
+    systemPrompt: createDataCatalogSkillPrompt({
+      label: options.label,
+      toolName: tool.name,
+      surfaceKind: options.surfaceKind,
+      guidance: options.guidance
+    })
+  });
+}
+export {
+  ServerPluginError,
+  bootstrapServer,
+  composeServerPlugins,
+  createDataCatalogAgentTool,
+  createDataCatalogServerPlugin,
+  createDataCatalogSkillPrompt,
+  createExecUiTool,
+  createGetUiStateTool,
+  createInMemoryBridge,
+  createWorkspaceUiTools,
+  defineServerPlugin,
+  formatDataCatalogSearchResult,
+  uiRoutes,
+  validateServerPlugin
+};