drupal-mcp-connector 2.20.0 → 2.22.0

package/src/lib/server-tools.js

@@ -13,7 +13,8 @@
  * call site performs the MCP session handshake — `initialize` (read the
  * `Mcp-Session-Id` response header) → `notifications/initialized` → `tools/call`
  * carrying that session id. The session is cached per site and transparently
- * re-initialised when the server expires it.
+ * re-initialised when the server expires it. `prompts/list` and `prompts/get`
+ * reuse the same session.
  *
  * Config (per site):
  *   "serverTools": { "url": "/mcp" }   // path is resolved against site.baseUrl
@@ -139,6 +140,12 @@ export async function callGovernedServerTool(site, binding, args = {}) {
 /** MCP protocol version advertised on the handshake and every subsequent POST. */
 const MCP_PROTOCOL_VERSION = "2025-06-18";
 
+/** MCP server-tool POST timeout. Handshake, catalog, and tools/call share this. */
+export const SERVER_TOOL_TIMEOUT_MS = 15_000;
+
+/** Default MCP response body cap (bytes). Caller `maxBytes` overrides. */
+export const SERVER_TOOL_MAX_BYTES = 262_144;
+
 // Monotonic JSON-RPC request id. A simple counter keeps ids unique per process
 // without relying on Math.random()/Date.now().
 let rpcId = 0;
@@ -327,7 +334,7 @@ async function initializeSession(site, endpoint, key) {
     method: "initialize",
     params: {
       protocolVersion: MCP_PROTOCOL_VERSION,
-      capabilities: {},
+      capabilities: { prompts: {} },
       clientInfo: { name: CLIENT_NAME, version: CLIENT_VERSION },
     },
   };
@@ -337,8 +344,8 @@ async function initializeSession(site, endpoint, key) {
       method: "POST",
       headers: await baseHeaders(site, null),
       body: JSON.stringify(payload),
-      size: 262144,
-      signal: AbortSignal.timeout(15000),
+      size: SERVER_TOOL_MAX_BYTES,
+      signal: AbortSignal.timeout(SERVER_TOOL_TIMEOUT_MS),
     });
 
   let res = await post();
@@ -374,8 +381,8 @@ async function initializeSession(site, endpoint, key) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
-      size: 262144,
-      signal: AbortSignal.timeout(15000),
+      size: SERVER_TOOL_MAX_BYTES,
+      signal: AbortSignal.timeout(SERVER_TOOL_TIMEOUT_MS),
     });
   } catch {
     // Notification is advisory; proceed with the established session.
@@ -432,11 +439,79 @@ export async function callServerTool(site, toolName, args = {}, options = {}) {
 /** Fetch one page of the authenticated module tool catalog. */
 export async function listServerTools(site, cursor) {
   return requestServerTool(site, "tools/list", cursor === undefined ? {} : { cursor }, {
-    maxBytes: 262144, preserveErrors: true,
+    maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
+  });
+}
+
+/** Fetch one page of Drupal `McpPromptConfig` prompts. */
+export async function listServerPrompts(site, cursor) {
+  return requestServerTool(site, "prompts/list", cursor === undefined ? {} : { cursor }, {
+    maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
+  });
+}
+
+/**
+ * Fetch one Drupal prompt body. Pass no arguments so `{{token}}` placeholders
+ * stay intact for the connector's workflow renderer.
+ */
+export async function getServerPrompt(site, name) {
+  return requestServerTool(site, "prompts/get", { name, arguments: {} }, {
+    maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
   });
 }
 
-/** Shared bounded MCP request transport; retries only explicit auth/session rejection. */
+/**
+ * Page `prompts/list` the same way as `tools/list`.
+ * @param {object} site Resolved site config.
+ * @param {Function} [list] Catalog page reader.
+ * @returns {Promise<object[]>} Prompt descriptors.
+ */
+export async function advertisedServerPrompts(site, list = listServerPrompts) {
+  const prompts = [];
+  const seen = new Set();
+  let cursor;
+  for (let page = 0; page < MAX_CATALOG_PAGES; page++) {
+    const result = await list(site, cursor);
+    if (!Array.isArray(result?.prompts)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" is malformed: prompts/list returned no prompts array.`);
+    }
+    for (const prompt of result.prompts) {
+      if (prompt && typeof prompt.name === "string") prompts.push(prompt);
+    }
+    if (result.nextCursor === undefined || result.nextCursor === null) return prompts;
+    if (typeof result.nextCursor !== "string" || seen.has(result.nextCursor)) {
+      throw new Error(`Server-tool catalog for site "${site._name}" returned an invalid or repeated prompts cursor.`);
+    }
+    cursor = result.nextCursor;
+    seen.add(cursor);
+  }
+  throw new Error(`Server-tool catalog for site "${site._name}" exceeds ${MAX_CATALOG_PAGES} prompt pages.`);
+}
+
+/**
+ * Load listed prompt descriptors plus `prompts/get` bodies for the named ids.
+ * A get failure omits that id; the caller fail-closes rather than widening.
+ * @param {object} site Resolved site config.
+ * @param {string[]} names Workflow ids to fetch.
+ * @param {{list?: Function, get?: Function}} [deps]
+ * @returns {Promise<{list: object[], bodies: Map<string, object>}>}
+ */
+export async function fetchSiteWorkflowPrompts(site, names, { list = listServerPrompts, get = getServerPrompt } = {}) {
+  const listed = await advertisedServerPrompts(site, list);
+  const want = new Set(names ?? []);
+  const bodies = new Map();
+  for (const prompt of listed) {
+    if (!want.has(prompt.name)) continue;
+    try {
+      bodies.set(prompt.name, await get(site, prompt.name));
+    } catch {
+      // Fail closed for this id: no body, so the merge will not list it.
+    }
+  }
+  return { list: listed, bodies };
+}
+
+/** Shared bounded MCP request transport; size + abort are always attached. */
 async function requestServerTool(site, method, params, options) {
   const toolName = params.name ?? method;
   const endpoint = resolveEndpoint(site);
@@ -463,7 +538,8 @@ async function requestServerTool(site, method, params, options) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify(payload),
-      ...(options.maxBytes ? { size: options.maxBytes, signal: AbortSignal.timeout(15000) } : {}),
+      size: options.maxBytes ?? SERVER_TOOL_MAX_BYTES,
+      signal: AbortSignal.timeout(SERVER_TOOL_TIMEOUT_MS),
     });
     const { body, rawText } = await readBody(res);
 

package/src/lib/tool-prompts.js

@@ -239,10 +239,15 @@ export function getToolPromptMessages(promptName, args = {}, definitionsByName)
  * @param {Set<string>} options.workflowNames - Names of the hand-authored workflow prompts.
  * @param {(name: string, args: object) => Array<object>} options.workflowMessages
  * @param {Map<string,object>} options.definitionsByName - Built-in tool name → definition.
+ * @param {(tools: Array<object>, taken: Set<string>) => object[]|Promise<object[]>} [options.extraWorkflows]
+ *   Module-owned workflows visible for this request. Each item has name,
+ *   description, arguments, and is renderable by extraWorkflowMessages.
+ * @param {(workflow: object, args: object) => Array<object>} [options.extraWorkflowMessages]
  * @returns {{definitions: Array<object>, list: Function, describe: Function, get: Function}}
  */
 export function createPromptSurface({
   staticPrompts, discover, filter, workflowNames, workflowMessages, definitionsByName,
+  extraWorkflows, extraWorkflowMessages,
 }) {
   const get = (name, args) => workflowNames.has(name)
     ? workflowMessages(name, args)
@@ -251,11 +256,22 @@ export function createPromptSurface({
   async function visible() {
     const tools = await discover();
     const taken = new Set(staticPrompts.map((prompt) => prompt.name));
+    const extra = extraWorkflows ? await extraWorkflows(tools, taken) : [];
+    for (const workflow of extra) taken.add(workflow.name);
     // A reserved module name cannot match a built-in, but never let a remote
     // catalog shadow a static prompt if that invariant is ever broken.
     const moduleDefs = tools.filter((tool) =>
       isModuleDefinition(tool) && !taken.has(toolNameToPromptName(tool.name)));
-    return { prompts: [...filter(staticPrompts, tools), ...buildToolPrompts(moduleDefs)], moduleDefs };
+    const extraPrompts = extra.map((workflow) => ({
+      name: workflow.name,
+      description: workflow.description,
+      arguments: workflow.arguments,
+    }));
+    return {
+      prompts: [...filter([...staticPrompts, ...extraPrompts], tools), ...buildToolPrompts(moduleDefs)],
+      moduleDefs,
+      extra,
+    };
   }
 
   return {
@@ -264,14 +280,21 @@ export function createPromptSurface({
     list: async () => (await visible()).prompts,
     /** Resolve one prompt, or null when it is not visible to this request. */
     async describe(name, args = {}) {
-      const { prompts, moduleDefs } = await visible();
+      const { prompts, moduleDefs, extra } = await visible();
       const known = prompts.find((prompt) => prompt.name === name);
       if (!known) return null;
       const live = moduleDefs.find((def) => toolNameToPromptName(def.name) === name);
-      const messages = live
-        ? getToolPromptMessages(name, args, new Map([[live.name, live]]))
-        : get(name, args);
-      return { description: known.description, messages };
+      if (live) {
+        return {
+          description: known.description,
+          messages: getToolPromptMessages(name, args, new Map([[live.name, live]])),
+        };
+      }
+      const workflow = extra.find((item) => item.name === name);
+      if (workflow && extraWorkflowMessages) {
+        return { description: known.description, messages: extraWorkflowMessages(workflow, args) };
+      }
+      return { description: known.description, messages: get(name, args) };
     },
   };
 }

package/src/lib/workflow-prompts.js

@@ -0,0 +1,490 @@
+/**
+ * Module-owned and built-in workflow prompts (#333).
+ *
+ * A workflow is a definition (id, tools, instructions) from a provider. The
+ * loader validates, bounds, and filters. It does not call tools. See
+ * docs/module-workflows.md.
+ */
+
+import { sourceText, toolNameToPromptName } from "./tool-prompts.js";
+
+const ID_RE = /^[a-z][a-z0-9_]{0,47}$/;
+const ARG_RE = /^[a-z][a-z0-9_]{0,47}$/;
+const MAX_DESCRIPTION = 1024;
+const MAX_INSTRUCTIONS = 8192;
+const MAX_ARG_VALUE = 200;
+const MAX_WORKFLOWS = 64;
+const MAX_TOOLS = 32;
+const MAX_ARGUMENTS = 16;
+const WRITE_EPILOGUE = "Module writes are not retried.";
+
+/**
+ * Public MCP prompt name for a module workflow.
+ *
+ * @param {string} namespace
+ * @param {string} id
+ * @returns {string}
+ */
+export function workflowPromptName(namespace, id) {
+  return `drupal-${String(namespace).replace(/_/g, "-")}-${String(id).replace(/_/g, "-")}`;
+}
+
+/**
+ * Instruction text safe to hand to a model: no heading, no system: prefix.
+ *
+ * @param {*} value
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function sanitizeInstructions(value, limit = MAX_INSTRUCTIONS) {
+  return String(value ?? "")
+    .replace(/\r/g, "")
+    .replace(/^\s*#{1,6}\s+/gm, "")
+    .replace(/^\s*system\s*:/gim, "")
+    .trim()
+    .slice(0, limit);
+}
+
+function sanitizeArgValue(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_ARG_VALUE);
+}
+
+/**
+ * Validate one definition. Throws if it cannot be loaded.
+ *
+ * @param {object} raw
+ * @returns {object}
+ */
+export function normalizeWorkflow(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("Workflow definition must be an object.");
+  }
+  if (!ID_RE.test(raw.id ?? "")) throw new Error("Invalid workflow id.");
+  if (typeof raw.description !== "string" || !raw.description.trim()) {
+    throw new Error("Workflow description is required.");
+  }
+  if (typeof raw.readOnly !== "boolean") throw new Error("Workflow readOnly is required.");
+  if (!Array.isArray(raw.tools) || raw.tools.length < 1 || raw.tools.length > MAX_TOOLS) {
+    throw new Error("Workflow tools must be a non-empty list.");
+  }
+  if (raw.tools.some((alias) => !ID_RE.test(alias ?? ""))) {
+    throw new Error("Invalid workflow tool alias.");
+  }
+  if (new Set(raw.tools).size !== raw.tools.length) {
+    throw new Error("Workflow tools must be unique.");
+  }
+  if (typeof raw.instructions !== "string" || !raw.instructions.trim()) {
+    throw new Error("Workflow instructions are required.");
+  }
+  const args = Array.isArray(raw.arguments) ? raw.arguments : [];
+  if (args.length > MAX_ARGUMENTS) throw new Error("Too many workflow arguments.");
+  const arguments_ = [];
+  for (const arg of args) {
+    if (!arg || !ARG_RE.test(arg.name ?? "") || typeof arg.description !== "string") {
+      throw new Error("Invalid workflow argument.");
+    }
+    arguments_.push({
+      name: arg.name,
+      description: sourceText(arg.description),
+      required: Boolean(arg.required),
+    });
+  }
+  const placeholders = [...raw.instructions.matchAll(/\{tool:([a-z][a-z0-9_]{0,47})\}/g)].map((m) => m[1]);
+  for (const alias of placeholders) {
+    if (!raw.tools.includes(alias)) {
+      throw new Error("Workflow instructions name a tool that is not in tools.");
+    }
+  }
+  return {
+    id: raw.id,
+    description: sourceText(raw.description),
+    readOnly: raw.readOnly,
+    tools: [...raw.tools],
+    arguments: arguments_,
+    instructions: sanitizeInstructions(raw.instructions),
+    name: typeof raw.name === "string" && raw.name ? raw.name : undefined,
+  };
+}
+
+/**
+ * @param {object} def
+ * @param {string} namespace
+ * @returns {string}
+ */
+export function resolvedName(def, namespace) {
+  return def.name || workflowPromptName(namespace, def.id);
+}
+
+/**
+ * Map a local alias to the public module tool name using the live tool list.
+ *
+ * @param {string} namespace
+ * @param {string} alias
+ * @param {Array<{name: string}>} tools
+ * @returns {string|null}
+ */
+export function publicToolName(namespace, alias, tools) {
+  const suffix = `_${namespace}__${alias}`;
+  const found = (tools ?? []).filter((tool) =>
+    typeof tool?.name === "string" &&
+    tool.name.startsWith("drupal_module_") &&
+    tool.name.endsWith(suffix));
+  return found.length === 1 ? found[0].name : null;
+}
+
+/**
+ * Whether every named tool is visible. Built-in public names must match
+ * exactly; module aliases resolve through {@link publicToolName}.
+ *
+ * @param {object} def
+ * @param {string} namespace
+ * @param {Array<{name: string}>} tools
+ * @param {{builtin?: boolean}} [opts]
+ * @returns {string[]|null} Public names, or null when any tool is missing.
+ */
+export function resolveToolNames(def, namespace, tools, opts = {}) {
+  const visible = new Set((tools ?? []).map((tool) => tool.name));
+  const names = [];
+  for (const alias of def.tools) {
+    const publicName = opts.builtin
+      ? (visible.has(alias) ? alias : null)
+      : publicToolName(namespace, alias, tools);
+    if (!publicName) return null;
+    names.push(publicName);
+  }
+  return names;
+}
+
+/**
+ * Load workflows from providers. Each provider is
+ * `{ id, namespace, builtin?, workflows }` or a function returning that.
+ *
+ * Two unrelated providers are the intended test shape: a CRM-like catalog and
+ * an intake-like catalog must not leak into each other.
+ *
+ * @param {Array<object|Function>} providers
+ * @param {object} [context]
+ * @param {Array<{name: string}>} [context.tools]
+ * @param {Set<string>} [context.taken]
+ * @returns {object[]} Loaded, visible workflows.
+ */
+export function loadWorkflows(providers, context = {}) {
+  const tools = context.tools ?? [];
+  const taken = new Set(context.taken ?? []);
+  const out = [];
+  for (const rawProvider of providers) {
+    const provider = typeof rawProvider === "function" ? rawProvider() : rawProvider;
+    if (!provider || typeof provider.namespace !== "string") continue;
+    if (!provider.builtin && !/^[a-z][a-z0-9_]{0,23}$/.test(provider.namespace ?? "")) {
+      continue;
+    }
+    const list = Array.isArray(provider.workflows) ? provider.workflows : [];
+    let n = 0;
+    for (const raw of list) {
+      if (n >= MAX_WORKFLOWS) break;
+      let def;
+      try {
+        def = normalizeWorkflow(raw);
+      } catch {
+        continue;
+      }
+      n += 1;
+      const name = resolvedName(def, provider.namespace);
+      if (taken.has(name) || (!provider.builtin && name !== workflowPromptName(provider.namespace, def.id))) {
+        continue;
+      }
+      const publicNames = resolveToolNames(def, provider.namespace, tools, { builtin: Boolean(provider.builtin) });
+      if (!publicNames) continue;
+      taken.add(name);
+      out.push({
+        ...def,
+        name,
+        namespace: provider.namespace,
+        builtin: Boolean(provider.builtin),
+        publicTools: publicNames,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * MCP prompt descriptor (no internal fields).
+ *
+ * @param {object} workflow
+ * @returns {object}
+ */
+export function toPromptDescriptor(workflow) {
+  return {
+    name: workflow.name,
+    description: workflow.description,
+    arguments: workflow.arguments.map((arg) => ({
+      name: arg.name,
+      description: arg.description,
+      required: arg.required,
+    })),
+  };
+}
+
+function builtinArgValues(args) {
+  const site = sanitizeArgValue(args?.site);
+  return {
+    site_phrase: site ? `on the "${site}" site` : "on the default site",
+    type: sanitizeArgValue(args?.type) || "article",
+    topic: sanitizeArgValue(args?.topic) || "the requested topic",
+    site,
+  };
+}
+
+/**
+ * Render MCP messages for a loaded workflow.
+ *
+ * @param {object} workflow
+ * @param {object} [args]
+ * @returns {Array<object>}
+ */
+export function renderWorkflowMessages(workflow, args = {}) {
+  const publicTools = [...(workflow.publicTools ?? [])];
+  const toolMap = new Map();
+  workflow.tools.forEach((alias, index) => {
+    toolMap.set(alias, publicTools.at(index));
+  });
+  const argMap = new Map(Object.entries(builtinArgValues(args)));
+  for (const arg of workflow.arguments) {
+    if (arg.name !== "site_phrase" && Object.hasOwn(args, arg.name)) {
+      argMap.set(arg.name, sanitizeArgValue(args[arg.name]));
+    }
+  }
+  let text = workflow.instructions.replace(/\{tool:([a-z][a-z0-9_]{0,47})\}/g, (_, alias) => {
+    return toolMap.get(alias) || `{tool:${alias}}`;
+  });
+  text = text.replace(/\{arg:([a-z][a-z0-9_]{0,47})\}/g, (_, name) => argMap.get(name) ?? "");
+  if (!workflow.readOnly) {
+    text = `${text}\n${WRITE_EPILOGUE}`;
+  }
+  return [{ role: "user", content: { type: "text", text } }];
+}
+
+/**
+ * Unique `{tool:alias}` names in instruction text, first-seen order.
+ *
+ * @param {string} instructions
+ * @returns {string[]}
+ */
+export function toolAliasesInInstructions(instructions) {
+  const aliases = [];
+  const seen = new Set();
+  for (const match of String(instructions ?? "").matchAll(/\{tool:([a-z][a-z0-9_]{0,47})\}/g)) {
+    if (seen.has(match[1])) continue;
+    seen.add(match[1]);
+    aliases.push(match[1]);
+  }
+  return aliases;
+}
+
+/**
+ * Join user-role text from a Drupal `prompts/get` result.
+ *
+ * @param {object} got
+ * @returns {string}
+ */
+export function instructionTextFromDrupalPrompt(got) {
+  const messages = Array.isArray(got?.messages) ? got.messages : [];
+  const parts = [];
+  for (const message of messages) {
+    if (message?.role !== "user") continue;
+    const content = message.content;
+    if (typeof content?.text === "string") {
+      parts.push(content.text);
+      continue;
+    }
+    if (Array.isArray(content)) {
+      for (const item of content) {
+        if (item?.type === "text" && typeof item.text === "string") parts.push(item.text);
+      }
+    }
+  }
+  return parts.join("\n").replace(/\{\{\s*([a-z][a-z0-9_]{0,47})\s*\}\}/g, "{arg:$1}");
+}
+
+/**
+ * `readOnly` is false when any named alias is a local write or delete.
+ *
+ * @param {string[]} aliases
+ * @param {object} toolsMap `serverTools.modules.tools`
+ * @returns {boolean}
+ */
+export function inferReadOnly(aliases, toolsMap) {
+  for (const alias of aliases) {
+    const operation = toolsMap?.[alias]?.operation;
+    if (operation === "write" || operation === "delete") return false;
+  }
+  return true;
+}
+
+/**
+ * Map a Drupal prompt list item + get body onto the v1 workflow definition.
+ * Returns null when the prompt cannot be a workflow (no `{tool:alias}`, an
+ * alias missing from the local tools map, or an unusable description).
+ *
+ * @param {string} id
+ * @param {object} listed
+ * @param {object} got
+ * @param {object} toolsMap
+ * @returns {object|null}
+ */
+export function workflowFromDrupalPrompt(id, listed, got, toolsMap) {
+  const instructions = instructionTextFromDrupalPrompt(got);
+  if (!instructions.trim()) return null;
+  const tools = toolAliasesInInstructions(instructions);
+  if (tools.length < 1) return null;
+  for (const alias of tools) {
+    if (!toolsMap?.[alias] || typeof toolsMap[alias] !== "object") return null;
+  }
+  const rawArgs = Array.isArray(listed?.arguments) ? listed.arguments : [];
+  const arguments_ = rawArgs.map((arg) => ({
+    name: arg?.name ?? arg?.machine_name,
+    description: arg?.description ?? "",
+    required: Boolean(arg?.required),
+  }));
+  const description = String(listed?.description ?? got?.description ?? "").trim() || "Module workflow.";
+  return {
+    id,
+    description,
+    readOnly: inferReadOnly(tools, toolsMap),
+    tools,
+    arguments: arguments_,
+    instructions,
+  };
+}
+
+/**
+ * Provider from site `serverTools.modules.workflows` maps, optionally merged
+ * with Drupal `prompts/list` + `prompts/get`. Local keys enable; remote bodies
+ * replace a local body when the catalog returns that id. A remote prompt that
+ * is not named locally is ignored. Fetch failures keep the v1 local bodies.
+ *
+ * @param {Array<object>} sites
+ * @param {{fetch?: Function}} [deps]
+ * @returns {Promise<object[]>}
+ */
+export async function moduleWorkflowProvidersWithRemote(sites, { fetch } = {}) {
+  const { fetchSiteWorkflowPrompts } = await import("./server-tools.js");
+  const load = fetch ?? fetchSiteWorkflowPrompts;
+  const providers = [];
+  for (const site of sites ?? []) {
+    const modules = site.serverTools?.modules;
+    if (!modules?.namespace || !modules.workflows || typeof modules.workflows !== "object") continue;
+    const enabled = [];
+    for (const [id, body] of Object.entries(modules.workflows)) {
+      if (id.startsWith("_") || !body || typeof body !== "object") continue;
+      enabled.push({ id: body.id ?? id, body });
+    }
+    let catalog;
+    try {
+      catalog = await load(site, enabled.map((item) => item.id));
+    } catch {
+      catalog = { list: [], bodies: new Map() };
+    }
+    const listedByName = new Map((catalog.list ?? []).map((prompt) => [prompt.name, prompt]));
+    const workflows = [];
+    for (const item of enabled) {
+      const listed = listedByName.get(item.id);
+      const got = catalog.bodies?.get(item.id);
+      if (listed && got) {
+        const mapped = workflowFromDrupalPrompt(item.id, listed, got, modules.tools ?? {});
+        if (mapped) workflows.push(mapped);
+        continue;
+      }
+      workflows.push({ ...item.body, id: item.id });
+    }
+    providers.push({
+      id: `config:${modules.namespace}`,
+      namespace: modules.namespace,
+      workflows,
+    });
+  }
+  return providers;
+}
+
+/**
+ * Provider from site `serverTools.modules.workflows` maps.
+ *
+ * @param {Array<object>} sites
+ * @returns {Array<object>}
+ */
+export function moduleWorkflowProviders(sites) {
+  const providers = [];
+  for (const site of sites ?? []) {
+    const modules = site.serverTools?.modules;
+    if (!modules?.namespace || !modules.workflows || typeof modules.workflows !== "object") continue;
+    const workflows = [];
+    for (const [id, body] of Object.entries(modules.workflows)) {
+      if (id.startsWith("_") || !body || typeof body !== "object") continue;
+      workflows.push({ ...body, id: body.id ?? id });
+    }
+    providers.push({
+      id: `config:${modules.namespace}`,
+      namespace: modules.namespace,
+      workflows,
+    });
+  }
+  return providers;
+}
+
+const INDEX = new Map();
+const MODULE_KEYS = new Set();
+
+/**
+ * Register built-in workflows for principal filtering.
+ *
+ * @param {object[]} workflows
+ */
+export function registerBuiltinWorkflows(workflows) {
+  for (const wf of workflows ?? []) INDEX.set(wf.name, wf);
+}
+
+/**
+ * Replace the module-owned slice of the workflow index (per request).
+ *
+ * @param {object[]} workflows
+ */
+export function replaceModuleWorkflows(workflows) {
+  for (const key of MODULE_KEYS) INDEX.delete(key);
+  MODULE_KEYS.clear();
+  for (const wf of workflows ?? []) {
+    INDEX.set(wf.name, wf);
+    MODULE_KEYS.add(wf.name);
+  }
+}
+
+/**
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function lookupWorkflow(name) {
+  return INDEX.get(name);
+}
+
+/**
+ * Index used by tests.
+ *
+ * @param {object[]} workflows
+ * @returns {Map<string, {readOnly: boolean, builtin: boolean, publicTools: string[]}>}
+ */
+export function workflowIndex(workflows) {
+  return new Map((workflows ?? []).map((wf) => [wf.name, {
+    readOnly: wf.readOnly,
+    builtin: wf.builtin,
+    publicTools: wf.publicTools,
+  }]));
+}
+
+export const WORKFLOW_LIMITS = {
+  MAX_DESCRIPTION,
+  MAX_INSTRUCTIONS,
+  MAX_WORKFLOWS,
+};
+
+// Re-export for callers that already import tool prompt hyphenation.
+export { toolNameToPromptName };