@webmcp-auto-ui/agent 2.5.25 → 2.5.27

package/src/recipes/canary-middle.md

@@ -0,0 +1,32 @@
+---
+id: canary-middle
+name: Canary test — middle level (verbose style)
+when: called from canary-display only
+servers: [autoui]
+---
+
+## Canary token
+CANARY-MIDDLE-M5392
+
+## Secret phrase (must be quoted verbatim)
+"Under the stone bridge, eleven minnows wait for the tide."
+
+## When to use
+
+Internal recipe. Called exclusively by `canary-display` at STEP 1. Do NOT invoke on its own. Do NOT render widgets.
+
+## How to use
+
+Return to the caller:
+- `middleToken`: `CANARY-MIDDLE-M5392`
+- `middleSecretPhrase`: `Under the stone bridge, eleven minnows wait for the tide.`
+
+### STEP 1 — Confirm in chat
+
+Reply exactly: `✅ canary-middle followed — M5392`
+
+## Forbidden
+
+- DO NOT render any widget.
+- DO NOT substitute the token or the secret phrase.
+- DO NOT invent additional fields.

package/src/recipes/hackathon-assemblee-nationale.md

@@ -0,0 +1,111 @@
+---
+id: hackathon-assemblee-nationale-mcp-webmcp
+name: Hackathon Assemblée Nationale · MCP & WebMCP starter
+components_used: [notebook-document, notebook-compact]
+when: the user mentions the Assemblée Nationale hackathon, wants to experiment with parliamentary data (Tricoteuses, Legifrance), or asks for a starter notebook to explore deputies, votes, amendments, or legislative texts in a hackathon context. Keywords include "hackathon Assemblée Nationale", "MCP WebMCP hackathon", "tricoteuses playbook", "parlement playground", "hackathon parlementaire".
+servers: [autoui, tricoteuses]
+layout:
+  type: single
+---
+
+## When to use
+
+The user is participating in (or preparing for) the Assemblée Nationale hackathon around MCP and WebMCP. They want a ready-to-fork notebook with:
+- A clear onboarding (what the hackathon is about, what data is available)
+- Seed queries against Tricoteuses (parliamentary database) that return meaningful results immediately
+- A visualization or transformation cell that the participant can iterate on
+- A closing "your turn" note inviting them to modify, run, and share
+
+This recipe is a **specialization** of the generic `notebook-playbook` recipe — pre-filled with parliamentary-specific seed cells and tailored to the hackathon narrative.
+
+## How to use
+
+### Step 1 — Pick the document layout
+
+Default to `notebook-document` for the hackathon. Reasons:
+- Participants expect to collaborate and leave traces for each other (avatars, comments)
+- The document layout reads naturally as "hackathon brief + starter code" rather than "dev tool"
+- Margin comments can be seeded to hint at directions to explore
+
+If the participant asks for a minimal dev-focused playground instead, fall back to `notebook-compact`.
+
+### Step 2 — Seed the cells
+
+The notebook should contain 5–7 cells covering:
+
+1. **Intro markdown** — title, one-line context of the hackathon, link to relevant docs
+2. **Challenge markdown** — a few axes of exploration suggested by the hackathon organizers (replace placeholders with actual challenges when known)
+3. **Starter SQL** — a safe, visibly meaningful query on Tricoteuses (e.g. recent votes, most active deputies, amendments on a specific text)
+4. **Transform JS** — a small JS cell that post-processes the SQL result (grouping, counting, chart prep)
+5. **Visualization hint** — a markdown cell pointing at available visualization widgets (`hemicycle`, `profile`, `timeline`)
+6. **Your turn** — a closing markdown inviting the participant to fork and edit
+
+Example template (to be refined with actual hackathon organizers' briefs):
+
+```
+widget_display({name: "notebook-document", params: {
+  title: "Hackathon Assemblée Nationale · starter",
+  cells: [
+    {
+      type: "md",
+      content: "### Bienvenue au hackathon IA de l'Assemblée Nationale\n\nCe notebook est votre point de départ. Les données parlementaires proviennent du serveur <mark>Tricoteuses</mark>. Forkez, éditez, partagez."
+    },
+    {
+      type: "md",
+      content: "### Pistes d'exploration\n\n- Profil d'un parlementaire et son activité\n- Cartographie des votes par groupe politique\n- Amendements sur un texte précis\n- Enrichissement Wikipedia des parlementaires\n- Croisement entre circonscription et données externes"
+    },
+    {
+      type: "sql",
+      content: "-- 10 scrutins les plus récents\nSELECT id, date, intitule, pour, contre, abstention\nFROM scrutins\nORDER BY date DESC\nLIMIT 10",
+      comment: {
+        who: "organizers",
+        when: "start",
+        body: "Remplacez par une requête sur un texte qui vous intéresse (LIMIT important)."
+      }
+    },
+    {
+      type: "js",
+      content: "// Regroupe les scrutins par mois\nconst byMonth = {};\nfor (const s of rows) {\n  const m = s.date.slice(0, 7);\n  byMonth[m] = (byMonth[m] || 0) + 1;\n}\nconsole.table(byMonth);"
+    },
+    {
+      type: "md",
+      content: "### Visualiser\n\nPour afficher un profil parlementaire : `widget_display({name: \"profile\", params: {...}})`.\nPour un hémicycle : `widget_display({name: \"hemicycle\", params: {groups, result}})`.\nPour une timeline de mandats : `widget_display({name: \"timeline\", params: {events}})`."
+    },
+    {
+      type: "md",
+      content: "### À vous\n\nAjoutez des cellules avec `+ sql / + code`, réarrangez, exécutez. Quand vous avez quelque chose d'intéressant, cliquez `share` pour partager le lien hyperskill avec votre équipe ou les organisateurs."
+    }
+  ]
+}})
+```
+
+### Step 3 — Adapt to what the user knows
+
+- If the user has no background in the Tricoteuses schema, mention they can use `list_tables` and `describe_table` on the Tricoteuses server to discover the data model before writing queries.
+- If the user already has a specific question ("I want to look at votes on the 2024 budget"), rewrite the starter SQL to target that question directly.
+- If the user asks for a minimal playground without the hackathon framing, fall back to the generic `notebook-playbook` recipe instead.
+
+### Step 4 — Share
+
+After creating the notebook, remind the user that they can:
+- Use `share` → `Hyperskill link` to generate a fork-friendly URL to paste into their team's channel
+- Switch to `view` mode when demoing to organizers
+- Consult `⟲ history` to see their iteration trace and restore cells deleted by mistake
+
+## Notes
+
+This recipe is intended as a **starting skeleton** — the concrete hackathon brief (dates, prizes, specific challenges, dataset access restrictions) will be refined in a dedicated session with the organizers. Placeholders in the example above (axes of exploration, comments) should be replaced with the actual material provided by the hackathon team when it is available.
+
+For parliamentary profile pages, vote results with hemicycles, and legislative file browsing, prefer the dedicated recipes:
+- `display-parliamentary-profile-with-hemicycle-and-votes`
+- `explorer-dossiers-legislatifs-parcours-texte`
+- `rechercher-textes-juridiques-legifrance`
+
+These recipes produce more specialized layouts than a generic notebook, and are better suited when the output is a single focused page rather than a multi-cell playbook.
+
+## Common mistakes
+
+- **Forgetting the hackathon framing**: without the "bienvenue" and "à vous" markdown cells, participants land on a bare notebook and lose the playbook feeling.
+- **SQL without LIMIT**: Tricoteuses queries without `LIMIT` can return thousands of rows and slow down the first impression.
+- **Inventing data**: do not seed with fake French parliamentary content (fake deputies, fake votes). If the actual data is not known at seed time, use generic queries (`SELECT * FROM scrutins LIMIT 5`) and let the user discover from there.
+- **Picking the wrong layout**: if the user is solo and wants to code fast, `notebook-compact` is better than `notebook-document`. Default to document for hackathon context because of the collaborative framing, not as a hard rule.

package/src/recipes/hummingbird-data.md

@@ -0,0 +1,32 @@
+---
+id: hummingbird-data
+name: Hummingbird test — data + JS (tight style)
+when: called from hummingbird-display
+servers: [autoui]
+---
+
+# Hummingbird data
+
+Token: HUMMINGBIRD-DATA-D7244
+Phrase: "The weaver counts backwards from seven."
+
+## JS
+
+```js
+document.getElementById('out').textContent = (function(){
+  const p = 'EXEC-HUMMINGBIRD-H2947';
+  const a = 23 * 2;
+  const b = a + 8;
+  const c = b % 10;
+  return `${p}-${c}${b}`;
+})();
+```
+
+Expected: `EXEC-HUMMINGBIRD-H2947-454`
+
+## Steps
+
+1. Return `{dataToken: "HUMMINGBIRD-DATA-D7244", dataPhrase: "The weaver counts backwards from seven.", jsCode: "<the JS block above verbatim>", expectedOutput: "EXEC-HUMMINGBIRD-H2947-454"}` to caller.
+2. Chat: `✅ hummingbird-data followed — D7244 + JS`
+
+Do NOT render any widget. Do NOT modify the JS.

package/src/recipes/hummingbird-display.md

@@ -0,0 +1,36 @@
+---
+id: hummingbird-display
+name: Hummingbird test — entry (tight style)
+when: user asks to "affiche le hummingbird", "show hummingbird", or "test hummingbird"
+components_used: [js-sandbox, kv]
+servers: [autoui]
+---
+
+# Hummingbird entry
+
+Token: HUMMINGBIRD-DISPLAY-C5619
+Phrase: "Nine moths circle the candle."
+
+## Steps
+
+1. `get_recipe("hummingbird-middle")` → extract `middleToken`, `middlePhrase`.
+2. `get_recipe("hummingbird-data")` → extract `dataToken`, `dataPhrase`, `jsCode`, `expectedOutput`.
+3. `widget_display({name: "js-sandbox", params: {title: "Hummingbird JS", code: "<jsCode from step 2 verbatim>", html: "<div id='out' style='font-family:monospace;padding:8px;'></div>", css: "body{margin:0;background:#fff;color:#000;font-size:14px;}"}})`
+4. `widget_display({name: "kv", params: {title: "🐦 Hummingbird Retex — tight style", rows: [
+     ["entry_id", "hummingbird-display"],
+     ["entry_token", "HUMMINGBIRD-DISPLAY-C5619"],
+     ["entry_phrase", "Nine moths circle the candle."],
+     ["middle_id", "hummingbird-middle"],
+     ["middle_token", "<step 1>"],
+     ["middle_phrase", "<step 1>"],
+     ["data_id", "hummingbird-data"],
+     ["data_token", "<step 2>"],
+     ["data_phrase", "<step 2>"],
+     ["js_code_verbatim", "<step 2>"],
+     ["js_expected_output", "<step 2>"],
+     ["steps", "1, 2, 3, 4, 5"],
+     ["style", "tight"]
+   ]}})`
+5. Chat: `✅ hummingbird chain followed — 3 recipes + JS exec`
+
+All tokens, phrases, and JS code MUST be verbatim.

package/src/recipes/hummingbird-middle.md

@@ -0,0 +1,18 @@
+---
+id: hummingbird-middle
+name: Hummingbird test — middle (tight style)
+when: called from hummingbird-display
+servers: [autoui]
+---
+
+# Hummingbird middle
+
+Token: HUMMINGBIRD-MIDDLE-N7614
+Phrase: "Salt crystals sing in the kettle at midnight."
+
+## Steps
+
+1. Return `{middleToken: "HUMMINGBIRD-MIDDLE-N7614", middlePhrase: "Salt crystals sing in the kettle at midnight."}` to caller.
+2. Chat: `✅ hummingbird-middle followed — N7614`
+
+Do NOT render any widget.

package/src/recipes/notebook-playbook.md

@@ -0,0 +1,129 @@
+---
+id: create-interactive-notebook-playbook
+name: Create an interactive notebook playbook
+components_used: [notebook-compact, notebook-workspace, notebook-document, notebook-editorial]
+when: the user wants to experiment with data, prototype a small analysis, share a reusable scenario, let others fork and try a dataset, or prepare a hackathon-ready playground. Keywords include "playground", "playbook", "experiment", "try", "prototype", "hackathon", "share a notebook", "template", "starter".
+servers: [autoui]
+layout:
+  type: single
+---
+
+## When to use
+
+The user asks for a **notebook-like interactive playground** that combines text, queries, and code cells. Typical triggers:
+- "Give me a playground for exploring X"
+- "Prepare a notebook I can share with my team"
+- "I want to prototype a small analysis"
+- "Set up a hackathon starter"
+- "Make a reusable template for exploring CSVs / this API / these tables"
+
+This recipe applies across domains (parliamentary data, biodiversity, news, business datasets, etc.) — it only prescribes the **shape** of the answer, not its content.
+
+## How to use
+
+### Step 1 — Pick the right notebook layout
+
+Choose one of the four `notebook-*` widgets based on the user's implicit intent:
+
+| Layout | Use when |
+|---|---|
+| `notebook-compact` | Quick data exploration, reactive dataflow with named outputs, minimal chrome. **Default for most "playground" and "hackathon" requests.** |
+| `notebook-workspace` | The user expects a multi-cell analyst workspace with sources, cell navigation, and a "publish" step. Use when they mention "dashboard", "app", "workspace". |
+| `notebook-document` | The user plans to share and discuss with a team. Use when "collaborate", "review", "comment" appear. |
+| `notebook-editorial` | The user wants a polished, article-like final deliverable mixing prose and code. Use for "memo", "report", "writeup", "blog-style". |
+
+When in doubt, pick `notebook-compact`.
+
+### Step 2 — Pre-fill the cells with context-aware seeds
+
+Never create an empty notebook. Always seed with 3–5 cells that give the user an immediate starting point:
+
+1. **First cell: markdown** — title + one-sentence context of what the notebook is for
+2. **Second cell: markdown or code** — if an MCP data source is connected, a starter query that returns something visible (e.g. `SELECT * FROM {table} LIMIT 10`). Otherwise a markdown cell describing the next step
+3. **Third cell: code** — a transformation or a visualization that uses the output of step 2. Use `varname` on the SQL cell (`varname: "rows"`) and reference it in the JS cell
+4. **Last cell: markdown** — a short "to you to play" note inviting the user to add cells, edit, or fork
+
+Example seed for a generic data playground:
+
+```
+widget_display({name: "notebook-compact", params: {
+  title: "Exploration playground",
+  cells: [
+    {type: "md", content: "### Exploration playground\n\nStart by running the first SQL cell, then iterate."},
+    {type: "sql", content: "select * from source limit 10", varname: "rows"},
+    {type: "js", content: "// explore rows here\nconsole.table(rows)"},
+    {type: "md", content: "### Your turn\n\nAdd cells with `+ sql` or `+ js`, reorder via the drag handle, and share via the header button."}
+  ]
+}})
+```
+
+### Step 3 — Adapt seeds to the connected MCP server
+
+If a specific MCP server is connected, replace the generic `source` and `select *` placeholders with actual tables and queries from that server:
+- For a parliamentary server (Tricoteuses): use actual tables like `acteurs`, `scrutins`, `amendements` with meaningful LIMIT
+- For a biodiversity server (iNaturalist): use the server's typical queries to return observations
+- For a generic SQL server: list tables first (`list_tables` or `describe_table`), then seed with a `SELECT * FROM {first_table} LIMIT 10`
+
+Always keep queries **short** and **limited** so the first run returns quickly and visually.
+
+### Step 4 — Share and fork
+
+After creating the notebook, mention to the user that they can:
+- Click `share` in the toolbar to open the export modal (hyperskill link for in-session sharing, markdown/png/json for external export)
+- Switch to `view` mode (read-only, no controls visible) when presenting to someone
+- Access the `⟲ history` panel to see the trace of edits, and restore deleted cells
+
+For hackathon contexts, prefer seeding a **document** layout (comments + avatars) so participants feel they are joining a shared space.
+
+## Examples
+
+### Generic CSV / table playground
+```
+// user: "I need a playground to play with this CSV"
+widget_display({name: "notebook-compact", params: {
+  title: "CSV playground",
+  cells: [
+    {type: "md", content: "### CSV playground\n\nRun the SQL cell to see the first rows, then iterate."},
+    {type: "sql", content: "select * from source limit 20", varname: "rows"},
+    {type: "js", content: "// summarize, chart, or filter rows here"}
+  ]
+}})
+```
+
+### Collaborative analysis
+```
+// user: "Set up a notebook my team can edit together"
+widget_display({name: "notebook-document", params: {
+  title: "Team analysis",
+  cells: [
+    {type: "md", content: "Kick-off: describe the question here."},
+    {type: "sql", content: "select * from source limit 10"},
+    {type: "md", content: "Your findings: add thoughts, highlights (<mark>key sentence</mark>), and comments on the code cells above."}
+  ]
+}})
+```
+
+### Final memo
+```
+// user: "Prepare a short memo of my findings"
+widget_display({name: "notebook-editorial", params: {
+  title: "Findings memo",
+  kicker: "memo",
+  cells: [
+    {type: "md", content: "Three observations from last week's data."},
+    {type: "md", content: "First, the volume is up. Here is the query:"},
+    {type: "sql", content: "select count(*) from source"},
+    {type: "md", content: "Second, the distribution has shifted."},
+    {type: "js", content: "// chart distribution"},
+    {type: "md", content: "We conclude that..."}
+  ]
+}})
+```
+
+## Common mistakes
+
+- **Empty notebook**: never call `widget_display` without at least 3 seed cells. The user expects something they can immediately run.
+- **Wrong layout for the intent**: do not use `notebook-editorial` for quick exploration — it signals "finished article" and intimidates. Use `notebook-compact` unless the user explicitly asks for a publication feel.
+- **Heavy initial queries**: always `LIMIT 10` or `LIMIT 20` in seed SQL cells. Users will expand later if needed.
+- **Missing `varname` on SQL cells** (in compact layout): the named output is what the compact layout showcases. Without it, the notebook loses half its reactive story.
+- **Inventing UUIDs or fork IDs**: leave `id` and `forkId` unset — the widget generates sensible defaults. Only pass `id` when restoring an existing notebook.

package/src/tool-layers.ts

@@ -8,9 +8,19 @@ import type { SchemaPatch } from '@webmcp-auto-ui/core';
 import { DiscoveryCache, type ServerCache } from './discovery-cache.js';
 import type { PipelineTrace } from './pipeline-trace.js';
 
+/** Map an internal protocol type to the token used in tool-name prefixes.
+ *  - `mcp`    (remote data sources) → `data`
+ *  - `webmcp` (local UI widgets)     → `ui`
+ *  Final tool names follow {server}_{token}_{tool} (e.g. `tricoteuses_data_search_recipes`,
+ *  `autoui_ui_widget_display`). Using neutral tokens avoids lexical confusion between
+ *  MCP and WebMCP for small LLMs. */
+export function protocolToken(protocol: 'mcp' | 'webmcp'): 'data' | 'ui' {
+  return protocol === 'mcp' ? 'data' : 'ui';
+}
+
 /** Sanitize a server name for use in tool name prefixes.
  *  Returns a clean underscore-separated identifier with no "mcp"/"server" noise.
- *  Final tool names follow {server}_{protocol}_{tool} convention. */
+ *  Final tool names follow {server}_{token}_{tool} convention. */
 export function sanitizeServerName(name: string): string {
   let result = name.toLowerCase()
     .replace(/[^a-z0-9]+/g, '_')       // all non-alphanumeric → underscore
@@ -23,6 +33,12 @@ export function sanitizeServerName(name: string): string {
   return result || 'mcp';
 }
 
+// ── Discovery pseudo-tool descriptions (long form, used in tool schemas) ──
+const longSearchToolsDesc = (serverName: string) =>
+  `Search tools by keyword on the ${serverName} server. Use this when you need to find a specific data-fetching or action tool but don't know its exact name. Pass a keyword related to the task (e.g. "weather", "search", "create") and get back matching tool names with descriptions and input schemas. This is more targeted than list_tools — prefer it when you have a clear idea of what you're looking for. Returns an array of {name, description, inputSchema} objects.`;
+const longListToolsDesc = (serverName: string) =>
+  `List ALL available tools on the ${serverName} server with their names, descriptions, and input schemas. Use this when search_tools returned no results, or when you want to browse the full capabilities of the server. Returns the complete tool catalog — useful when the user's request doesn't map to an obvious keyword. Does not accept any parameters.`;
+
 /** MCP data layer — tools and recipes from a connected MCP server */
 export interface McpLayer {
   protocol: 'mcp';
@@ -44,6 +60,13 @@ export interface WebMcpLayer {
 
 export type ToolLayer = McpLayer | WebMcpLayer;
 
+/** Which provider syntax to emit in the system prompt.
+ *  - `generic`: `tool_name()` / `tool_name(arg1, arg2)` — Claude, Ollama, most providers.
+ *  - `gemma`:   `<|tool_call>call:tool_name{}<tool_call|>` — Gemma 4 native format.
+ *  - `qwen`:    `<tool_call>\n{"name":...,"arguments":...}\n</tool_call>` — Qwen 3/3.5 ChatML.
+ *  - `mistral`: `[TOOL_CALLS][{"name":...,"arguments":...}]` — Mistral/Ministral. */
+export type ProviderKind = 'generic' | 'gemma' | 'qwen' | 'mistral';
+
 /** Options controlling how tool schemas are transformed before sending to the LLM */
 export interface SchemaTransformOptions {
   /** Strip oneOf/anyOf/allOf/not/if-then-else/$ref (default: true) */
@@ -289,7 +312,7 @@ export function buildToolsFromLayers(layers: ToolLayer[], schemaOptions?: Schema
   const tools: ProviderTool[] = [];
 
   for (const layer of layers) {
-    const prefix = `${sanitizeServerName(layer.serverName)}_${layer.protocol}_`;
+    const prefix = `${sanitizeServerName(layer.serverName)}_${protocolToken(layer.protocol)}_`;
 
     if (layer.protocol === 'mcp') {
       for (const tool of toProviderTools(layer.tools, schemaOptions, trace)) {
@@ -338,155 +361,8 @@ export function buildToolsFromLayers(layers: ToolLayer[], schemaOptions?: Schema
   return { tools: Array.from(seen.values()), pathMaps: localPathMaps };
 }
 
-/** Result of buildSystemPromptWithAliases — prompt text + per-call alias map */
-export interface SystemPromptResult {
-  prompt: string;
-  aliasMap: Map<string, string>;
-}
-
-/**
- * Build system prompt with a local alias map (parallel-safe).
- * Prefer this over buildSystemPrompt() when running multiple agent loops.
- */
-export function buildSystemPromptWithAliases(layers: ToolLayer[]): SystemPromptResult {
-  const mcpLayers = layers.filter((l): l is McpLayer => l.protocol === 'mcp');
-  const webmcpLayers = layers.filter((l): l is WebMcpLayer => l.protocol === 'webmcp');
-
-  const aliasMap = new Map<string, string>();
-
-  // ── Collect search_recipes / list_recipes / get_recipe from all layers ──
-  const searchRecipes: string[] = [];
-  const listRecipes: string[] = [];
-  const getRecipes: string[] = [];
-  const searchTools: string[] = [];
-  const listTools: string[] = [];
-
-  // WebMCP layers: always exact match (we control the naming)
-  for (const l of webmcpLayers) {
-    const prefix = `${sanitizeServerName(l.serverName)}_webmcp_`;
-    for (const t of l.tools) {
-      if (t.name === 'search_recipes') searchRecipes.push(`${prefix}search_recipes()`);
-      if (t.name === 'list_recipes') listRecipes.push(`${prefix}list_recipes()`);
-      if (t.name === 'get_recipe') getRecipes.push(`${prefix}get_recipe()`);
-    }
-    // Pseudo-tools for tool discovery on WebMCP servers
-    searchTools.push(`${prefix}search_tools(query)`);
-    listTools.push(`${prefix}list_tools()`);
-  }
-
-  // MCP layers: 4-layer matching + alias registration
-  for (const l of mcpLayers) {
-    const prefix = `${sanitizeServerName(l.serverName)}_mcp_`;
-    const matches = resolveCanonicalTools(l.tools);
-
-    for (const m of matches) {
-      const canonicalPrefixed = `${prefix}${m.role}`;
-      const realPrefixed = `${prefix}${m.realToolName}`;
-
-      // Register alias only if names differ
-      if (m.role !== m.realToolName) {
-        aliasMap.set(canonicalPrefixed, realPrefixed);
-      }
-
-      if (m.role === 'search_recipes') searchRecipes.push(`${canonicalPrefixed}()`);
-      if (m.role === 'list_recipes') listRecipes.push(`${canonicalPrefixed}()`);
-      if (m.role === 'get_recipe') getRecipes.push(`${canonicalPrefixed}()`);
-    }
-
-    // Pseudo-tools for tool discovery on all MCP servers
-    searchTools.push(`${prefix}search_tools(query)`);
-    listTools.push(`${prefix}list_tools()`);
-  }
-
-  // ── WebMCP action tools (widget_display, canvas, recall) ──
-  const actionTools: string[] = [];
-  const ACTION_NAMES = ['widget_display', 'canvas', 'recall'];
-  for (const l of webmcpLayers) {
-    const prefix = `${sanitizeServerName(l.serverName)}_webmcp_`;
-    for (const t of l.tools) {
-      if (ACTION_NAMES.includes(t.name)) actionTools.push(`${prefix}${t.name}`);
-    }
-  }
-
-  // ── Build prompt (cascade: list recipes → search recipes → list tools → search tools) ──
-  let prompt = `You are an AI assistant that helps users by answering their questions and completing tasks using recipes (also called skills). These are not cooking recipes but instructions for an AI agent with scripts, schemas, and information to help it. If you cannot find a relevant recipe or tool, you may fall back to a traditional chat without tool calling (STEP 5).
-
-You MUST NOT skip steps.
-
-CRITICAL RULE: You MUST execute all steps silently. Do NOT generate any internal reasoning, thinking, or intermediate text.
-
-STEP 1 — List all recipes
-
-Look for a relevant recipe among these:
-
-${listRecipes.join('\n')}
-
-If at least one relevant recipe is found → go to STEP 2.
-If no results → go to STEP 1b.
-
-STEP 1b — Search recipes
-
-No recipe found by listing. Search with keyword(s) extracted from the request:
-
-${searchRecipes.join('\n')}
-
-Pick the most relevant recipe for the request.
-If a recipe matches → go to STEP 2.
-If no recipe is available or relevant → go to STEP 1c.
-
-STEP 1c — List tools
-
-No applicable recipe. List a relevant tool:
-
-${listTools.join('\n')}
-
-If a relevant tool is found → use it directly to respond (go to STEP 3).
-If no results → go to STEP 1d.
-
-STEP 1d — Search tools
-
-${searchTools.join('\n')}
-
-Pick the most relevant tool(s) and use them to respond (go to STEP 3).
-
-STEP 2 — Read the recipe
-
-${getRecipes.join('\n')}
-
-Read the full instructions of the selected recipe.
-
-STEP 3 — Execute
-
-Follow the recipe instructions exactly if you have one. Otherwise use the tools directly. Produce ONLY the final result, a one-sentence summary of the action performed, and the result.
-
-STEP 4 — UI display
-
-Unless a recipe specifies otherwise, use these tools to display your responses on the canvas:
-
-${actionTools.join('\n')}
-
-widget_display may ONLY be called with data returned by a non-autoui DATA tool actually invoked in the current session. Fabricating IDs, URLs, names, dates, or any content not returned by a tool is a critical violation. If no DATA tool has been called yet, go back to STEP 1.
-
-STEP 5 — Fallback
-
-If previous steps failed, fall back to a classic chat without tool calling.`;
-
-  return { prompt, aliasMap };
-}
-
-/** Build system prompt — backward-compatible wrapper that returns a plain string.
- *  Also populates the deprecated global toolAliasMap for legacy consumers.
- *  For parallel-safe usage, use buildSystemPromptWithAliases() instead.
- */
-export function buildSystemPrompt(layers: ToolLayer[]): string {
-  const { prompt, aliasMap } = buildSystemPromptWithAliases(layers);
-
-  // Populate deprecated global singleton for backward compat
-  toolAliasMap.clear();
-  for (const [k, v] of aliasMap) toolAliasMap.set(k, v);
-
-  return prompt;
-}
+// buildSystemPromptWithAliases / buildSystemPrompt / SystemPromptResult now
+// live in ./prompts/index.ts and are re-exported from src/index.ts.
 
 /** Result of buildDiscoveryToolsWithAliases */
 export interface DiscoveryToolsResult {
@@ -503,7 +379,7 @@ export function buildDiscoveryToolsWithAliases(layers: ToolLayer[], schemaOption
   const aliasMap = new Map<string, string>();
 
   for (const layer of layers) {
-    const prefix = `${sanitizeServerName(layer.serverName)}_${layer.protocol}_`;
+    const prefix = `${sanitizeServerName(layer.serverName)}_${protocolToken(layer.protocol)}_`;
 
     if (layer.protocol === 'mcp') {
       const allProviderTools = toProviderTools(layer.tools, schemaOptions, trace);
@@ -527,12 +403,12 @@ export function buildDiscoveryToolsWithAliases(layers: ToolLayer[], schemaOption
       // Pseudo-tools for tool discovery on MCP servers
       tools.push({
         name: `${prefix}search_tools`,
-        description: `Search tools by keyword on the ${layer.serverName} server. Use this when you need to find a specific data-fetching or action tool but don't know its exact name. Pass a keyword related to the task (e.g. "weather", "search", "create") and get back matching tool names with descriptions and input schemas. This is more targeted than list_tools — prefer it when you have a clear idea of what you're looking for. Returns an array of {name, description, inputSchema} objects.`,
+        description: longSearchToolsDesc(layer.serverName),
         input_schema: { type: 'object', properties: { query: { type: 'string', description: 'Keyword to search for in tool names and descriptions, e.g. "weather", "user", "search". Case-insensitive.' } }, required: ['query'] },
       });
       tools.push({
         name: `${prefix}list_tools`,
-        description: `List ALL available tools on the ${layer.serverName} server with their names, descriptions, and input schemas. Use this when search_tools returned no results, or when you want to browse the full capabilities of the server. Returns the complete tool catalog — useful when the user's request doesn't map to an obvious keyword. Does not accept any parameters.`,
+        description: longListToolsDesc(layer.serverName),
         input_schema: { type: 'object', properties: {} },
       });
     } else {
@@ -547,12 +423,12 @@ export function buildDiscoveryToolsWithAliases(layers: ToolLayer[], schemaOption
       // Pseudo-tools for tool discovery on WebMCP servers
       tools.push({
         name: `${prefix}search_tools`,
-        description: `Search tools by keyword on the ${layer.serverName} server. Use this when you need to find a specific data-fetching or action tool but don't know its exact name. Pass a keyword related to the task (e.g. "weather", "search", "create") and get back matching tool names with descriptions and input schemas. This is more targeted than list_tools — prefer it when you have a clear idea of what you're looking for. Returns an array of {name, description, inputSchema} objects.`,
+        description: longSearchToolsDesc(layer.serverName),
         input_schema: { type: 'object', properties: { query: { type: 'string', description: 'Keyword to search for in tool names and descriptions, e.g. "weather", "user", "search". Case-insensitive.' } }, required: ['query'] },
       });
       tools.push({
         name: `${prefix}list_tools`,
-        description: `List ALL available tools on the ${layer.serverName} server with their names, descriptions, and input schemas. Use this when search_tools returned no results, or when you want to browse the full capabilities of the server. Returns the complete tool catalog — useful when the user's request doesn't map to an obvious keyword. Does not accept any parameters.`,
+        description: longListToolsDesc(layer.serverName),
         input_schema: { type: 'object', properties: {} },
       });
     }
@@ -590,7 +466,7 @@ export function activateServerTools(
   schemaOptions?: SchemaTransformOptions,
   trace?: PipelineTrace,
 ): ProviderTool[] {
-  const prefix = `${sanitizeServerName(layer.serverName)}_${layer.protocol}_`;
+  const prefix = `${sanitizeServerName(layer.serverName)}_${protocolToken(layer.protocol)}_`;
   const existing = new Set(currentTools.map(t => t.name));
   const newTools = [...currentTools];