@webmcp-auto-ui/agent 2.5.25 → 2.5.27

package/src/notebook-widgets/workspace.ts

@@ -0,0 +1,328 @@
+// @ts-nocheck
+// ---------------------------------------------------------------------------
+// notebook-workspace — dense analyst workspace (hex-like)
+// Header bar + sidebar (sources + cells nav) + main cells area.
+// ---------------------------------------------------------------------------
+
+import {
+  createState, injectStyles, mountRunControls, mountHistoryPanel,
+  setupDnD, deleteCellWithConfirm, restoreCellFromSnapshot, addCell,
+  autosize, openShareModal, registerHistoryObserver,
+  buildServersButton,
+  type NotebookState, type NotebookCell,
+} from './shared.js';
+
+export async function render(container: HTMLElement, data: Record<string, unknown>): Promise<() => void> {
+  injectStyles();
+  injectLayoutStyles();
+
+  const state: NotebookState = createState({
+    id: data.id as string,
+    title: data.title as string ?? 'Untitled notebook',
+    mode: (data.mode as any) ?? 'edit',
+    cells: data.cells as any,
+  });
+  let activeCellId: string | null = state.cells.find((c) => c.type !== 'md')?.id ?? state.cells[0]?.id ?? null;
+
+  container.classList.add('nb-root');
+  container.classList.toggle('nb-view-mode', state.mode === 'view');
+
+  container.innerHTML = `
+    <div class="nbw-shell">
+      <div class="nbw-header">
+        <div class="nbw-logo"></div>
+        <input class="nbw-title-edit nb-title-edit" value="${escapeAttr(state.title)}">
+        <span class="nbw-tag">draft</span>
+        <div class="nbw-ctx">
+          <span class="nbw-source">no source connected</span>
+          <div class="nb-mode-switch">
+            <button class="nb-mode-edit nb-on">edit</button>
+            <button class="nb-mode-view">view</button>
+          </div>
+          <button class="nb-btn nbw-history-btn">⟲ history</button>
+          <span class="nbw-servers-slot"></span>
+          <button class="nb-btn">run all</button>
+          <button class="nb-btn nbw-share-btn">share</button>
+          <button class="nb-btn nb-btn-primary">publish</button>
+        </div>
+      </div>
+      <div class="nb-history-panel nbw-history-panel"></div>
+      <div class="nbw-body">
+        <aside class="nbw-sidebar">
+          <div class="nbw-section">sources</div>
+          <div class="nbw-item">◉ no source</div>
+          <div class="nbw-item nbw-indent nbw-dim">connect via mcp…</div>
+          <div class="nbw-section">cells</div>
+          <div class="nbw-cells-nav"></div>
+          <div class="nbw-add">
+            <button class="nb-btn nb-add-cell" data-add="md">+ md</button>
+            <button class="nb-btn nb-add-cell" data-add="sql">+ sql</button>
+            <button class="nb-btn nb-add-cell" data-add="js">+ js</button>
+          </div>
+        </aside>
+        <div class="nbw-cells"></div>
+      </div>
+    </div>`;
+
+  const shell = container.querySelector('.nbw-shell') as HTMLElement;
+  const cellsEl = shell.querySelector('.nbw-cells') as HTMLElement;
+  const navEl = shell.querySelector('.nbw-cells-nav') as HTMLElement;
+  const historyPanel = shell.querySelector('.nbw-history-panel') as HTMLElement;
+
+  function renderCells() {
+    cellsEl.innerHTML = '';
+    navEl.innerHTML = '';
+    state.cells.forEach((cell, idx) => {
+      const navItem = document.createElement('div');
+      navItem.className = 'nbw-item' + (cell.id === activeCellId ? ' nbw-active' : '');
+      navItem.textContent = `${idx + 1} · ${cell.name || cell.type}`;
+      navItem.addEventListener('click', () => { activeCellId = cell.id; rerender(); });
+      navEl.appendChild(navItem);
+
+      cellsEl.appendChild(renderCell(cell, idx, state, rerender));
+    });
+  }
+
+  function rerender() {
+    mountHistoryPanel(historyPanel, state, (snap) => { restoreCellFromSnapshot(state, snap); rerender(); });
+    renderCells();
+  }
+
+  shell.querySelectorAll<HTMLElement>('[data-add]').forEach((btn) => {
+    btn.addEventListener('click', () => {
+      const type = btn.dataset.add as any;
+      const name = type === 'md' ? 'note' : type === 'sql' ? 'query_' + (state.cells.length + 1) : 'cell_' + (state.cells.length + 1);
+      const cell = addCell(state, type, { name });
+      activeCellId = cell.id;
+      rerender();
+    });
+  });
+  (shell.querySelector('.nbw-history-btn') as HTMLElement).addEventListener('click', () => {
+    historyPanel.classList.toggle('nb-open');
+  });
+  (shell.querySelector('.nbw-share-btn') as HTMLElement).addEventListener('click', () => {
+    openShareModal(state, (fmt) => console.log('[notebook-workspace] share as', fmt, state));
+  });
+  (shell.querySelector('.nbw-title-edit') as HTMLInputElement).addEventListener('input', (e) => {
+    state.title = (e.target as HTMLInputElement).value;
+  });
+  const editBtn = shell.querySelector('.nb-mode-edit') as HTMLElement;
+  const viewBtn = shell.querySelector('.nb-mode-view') as HTMLElement;
+  editBtn.addEventListener('click', () => {
+    state.mode = 'edit';
+    container.classList.remove('nb-view-mode');
+    editBtn.classList.add('nb-on'); viewBtn.classList.remove('nb-on');
+  });
+  viewBtn.addEventListener('click', () => {
+    state.mode = 'view';
+    container.classList.add('nb-view-mode');
+    viewBtn.classList.add('nb-on'); editBtn.classList.remove('nb-on');
+  });
+
+  buildServersButton(state, shell.querySelector('.nbw-servers-slot') as HTMLElement, data, rerender);
+
+  setupDnD(cellsEl, state, rerender);
+  const unsubHistory = registerHistoryObserver(() => mountHistoryPanel(historyPanel, state, (snap) => { restoreCellFromSnapshot(state, snap); rerender(); }));
+
+  rerender();
+  return () => { unsubHistory(); };
+}
+
+function renderCell(cell: NotebookCell, idx: number, state: NotebookState, rerender: () => void): HTMLElement {
+  const wrap = document.createElement('div');
+  wrap.className = 'nb-cell-wrapper nbw-cell';
+  wrap.dataset.id = cell.id;
+
+  const inner = document.createElement('div');
+  inner.className = 'nb-cell';
+
+  const head = document.createElement('div');
+  head.className = 'nbw-cell-head';
+  const isCode = cell.type !== 'md';
+  head.innerHTML = `
+    <span class="nb-drag-handle" draggable="true" title="drag">⋮⋮</span>
+    ${isCode ? '<span class="nbw-run-controls"></span>' : ''}
+    <span class="nbw-type nbw-type-${cell.type}">${cell.type}</span>
+    <input class="nbw-cell-name-edit" value="${idx + 1} · ${escapeAttr(cell.name || '')}">
+    <div class="nbw-meta">
+      ${isCode ? `<span class="nbw-meta-info">${cell.lastMs != null ? cell.lastMs + 'ms' : '—'} · 4 rows</span>` : ''}
+      <button class="nb-icon-btn nb-toggle-src">${cell.hideSource ? '▸ src' : '◂ src'}</button>
+      ${isCode ? `<button class="nb-icon-btn nb-toggle-res">${cell.hideResult ? '▸ res' : '◂ res'}</button>` : ''}
+      <button class="nb-icon-btn nb-danger nbw-del">✕</button>
+    </div>`;
+  inner.appendChild(head);
+
+  if (isCode) {
+    mountRunControls(head.querySelector('.nbw-run-controls') as HTMLElement, cell, wrap, rerender);
+  }
+
+  const body = document.createElement('div');
+  body.className = 'nbw-cell-body' + (isCode ? ' nbw-code' : '') + (cell.hideSource ? ' nbw-hidden' : '');
+  const ta = document.createElement('textarea');
+  ta.className = isCode ? 'nb-code-edit' : 'nb-md-edit';
+  ta.value = cell.content;
+  ta.rows = 1;
+  ta.spellcheck = false;
+  ta.addEventListener('input', () => { cell.content = ta.value; autosize(ta); cell.status = 'stale'; });
+  body.appendChild(ta);
+  inner.appendChild(body);
+  setTimeout(() => autosize(ta), 0);
+
+  if (cell.type === 'sql' && !cell.hideResult) {
+    const resWrap = document.createElement('div');
+    resWrap.innerHTML = `
+      <table class="nbw-result-table">
+        <thead><tr><th>col_a</th><th>col_b</th><th>share</th></tr></thead>
+        <tbody>
+          <tr><td>row_1</td><td>42</td><td><div class="nbw-share-bar" style="width:100%"></div></td></tr>
+          <tr><td>row_2</td><td>29</td><td><div class="nbw-share-bar" style="width:69%"></div></td></tr>
+          <tr><td>row_3</td><td>22</td><td><div class="nbw-share-bar" style="width:52%"></div></td></tr>
+          <tr><td>row_4</td><td>9</td><td><div class="nbw-share-bar" style="width:22%"></div></td></tr>
+        </tbody>
+      </table>`;
+    inner.appendChild(resWrap);
+  } else if (cell.type === 'js' && !cell.hideResult) {
+    const chart = document.createElement('div');
+    chart.className = 'nbw-chart';
+    chart.innerHTML = `
+      <div class="nbw-bar" style="height:100%"></div>
+      <div class="nbw-bar" style="height:68%"></div>
+      <div class="nbw-bar" style="height:52%"></div>
+      <div class="nbw-bar" style="height:22%"></div>`;
+    inner.appendChild(chart);
+  }
+
+  (head.querySelector('.nb-toggle-src') as HTMLElement).addEventListener('click', () => { cell.hideSource = !cell.hideSource; rerender(); });
+  const togRes = head.querySelector('.nb-toggle-res') as HTMLElement | null;
+  if (togRes) togRes.addEventListener('click', () => { cell.hideResult = !cell.hideResult; rerender(); });
+  (head.querySelector('.nbw-del') as HTMLElement).addEventListener('click', () =>
+    deleteCellWithConfirm(state, cell, (c) => `${c.type} cell "${c.name}"`, rerender)
+  );
+  (head.querySelector('.nbw-cell-name-edit') as HTMLInputElement).addEventListener('input', (e) => {
+    const v = (e.target as HTMLInputElement).value;
+    const m = v.match(/^\d+\s*·\s*(.+)$/);
+    cell.name = m ? m[1] : v;
+  });
+
+  wrap.appendChild(inner);
+  return wrap;
+}
+
+function escapeAttr(s: string): string {
+  return (s ?? '').replace(/"/g, '&quot;');
+}
+
+function injectLayoutStyles(): void {
+  if (document.getElementById('nbw-styles')) return;
+  const style = document.createElement('style');
+  style.id = 'nbw-styles';
+  style.textContent = `
+.nbw-shell {
+  background: var(--color-surface); border: 1px solid var(--color-border);
+  border-radius: 12px; overflow: hidden;
+}
+.nbw-header {
+  display: flex; align-items: center; padding: 10px 14px; gap: 12px;
+  border-bottom: 1px solid var(--color-border); background: var(--color-surface2);
+}
+.nbw-logo { width: 14px; height: 14px; background: var(--color-accent); border-radius: 3px; }
+.nbw-title-edit {
+  font-size: 13px; font-weight: 500; color: var(--color-text1);
+  background: transparent; border: none; outline: none;
+  font-family: var(--font-sans, 'Syne', sans-serif);
+  width: 260px; padding: 2px 4px; border-radius: 3px;
+}
+.nbw-title-edit:focus { background: var(--color-bg); }
+.nbw-tag {
+  font-family: var(--font-mono, 'IBM Plex Mono', monospace);
+  font-size: 10px; color: var(--color-text2);
+  background: var(--color-bg); padding: 2px 7px; border-radius: 3px;
+  border: 1px solid var(--color-border);
+}
+.nbw-ctx {
+  font-family: var(--font-mono, 'IBM Plex Mono', monospace);
+  font-size: 11px; color: var(--color-text2);
+  margin-left: auto; display: flex; gap: 8px; align-items: center;
+}
+.nbw-history-panel { margin: 0 14px; }
+.nbw-body { display: grid; grid-template-columns: 180px 1fr; min-height: 380px; }
+.nbw-sidebar {
+  border-right: 1px solid var(--color-border);
+  background: var(--color-surface2); padding: 14px 12px; font-size: 12px;
+}
+.nbw-section {
+  color: var(--color-text2);
+  font-family: var(--font-mono, 'IBM Plex Mono', monospace);
+  font-size: 10px; letter-spacing: 0.1em;
+  margin: 0 0 8px; text-transform: uppercase;
+}
+.nbw-section:not(:first-child) { margin-top: 16px; }
+.nbw-item {
+  padding: 4px 6px; color: var(--color-text2);
+  border-radius: 4px; cursor: pointer;
+  display: flex; align-items: center; gap: 6px;
+}
+.nbw-item:hover { background: var(--color-surface); color: var(--color-text1); }
+.nbw-item.nbw-indent { padding-left: 18px; }
+.nbw-item.nbw-dim { opacity: 0.5; }
+.nbw-item.nbw-active {
+  background: var(--color-surface); color: var(--color-text1);
+  border-left: 2px solid var(--color-accent); border-radius: 0 4px 4px 0;
+}
+.nbw-add { margin-top: 10px; display: flex; gap: 4px; flex-wrap: wrap; }
+.nbw-add .nb-btn { flex: 1; font-size: 10px; padding: 3px 4px; }
+
+.nbw-cells { display: flex; flex-direction: column; }
+.nbw-cell .nb-cell { border-bottom: 1px solid var(--color-border); position: relative; }
+.nbw-cell:last-child .nb-cell { border-bottom: none; }
+.nbw-cell-head {
+  padding: 8px 16px;
+  display: flex; align-items: center; gap: 8px;
+  background: var(--color-surface2);
+  font-family: var(--font-mono, 'IBM Plex Mono', monospace);
+  font-size: 10px; color: var(--color-text2);
+  letter-spacing: 0.06em;
+}
+.nbw-type {
+  padding: 1px 7px; border-radius: 3px; font-weight: 500;
+  text-transform: uppercase; letter-spacing: 0.08em; font-size: 9.5px;
+}
+.nbw-type-md { background: rgba(160,160,184,0.15); color: var(--color-text2); }
+.nbw-type-sql { background: rgba(124,109,250,0.18); color: var(--color-accent); }
+.nbw-type-js { background: rgba(62,207,178,0.15); color: var(--color-teal); }
+.nbw-cell-name-edit {
+  background: transparent; border: none; outline: none;
+  color: var(--color-text1);
+  font-family: var(--font-mono, 'IBM Plex Mono', monospace);
+  font-size: 10px; width: 140px;
+}
+.nbw-meta { margin-left: auto; display: flex; gap: 8px; align-items: center; }
+.nbw-cell-body { padding: 14px 16px; font-size: 13.5px; line-height: 1.6; }
+.nbw-cell-body.nbw-code {
+  font-family: var(--font-mono, 'IBM Plex Mono', monospace);
+  font-size: 12.5px; line-height: 1.65;
+}
+.nbw-hidden { display: none !important; }
+
+.nbw-result-table { width: 100%; border-collapse: collapse; font-size: 12px; }
+.nbw-result-table thead tr { background: var(--color-surface2); }
+.nbw-result-table th {
+  text-align: left; padding: 7px 16px; font-weight: 500;
+  color: var(--color-text2);
+  font-family: var(--font-mono, 'IBM Plex Mono', monospace);
+  font-size: 10px; letter-spacing: 0.08em; text-transform: uppercase;
+  border-top: 1px solid var(--color-border);
+  border-bottom: 1px solid var(--color-border);
+}
+.nbw-result-table td {
+  padding: 6px 16px; border-bottom: 1px solid var(--color-border);
+  font-variant-numeric: tabular-nums;
+}
+.nbw-result-table td:first-child { color: var(--color-text1); font-variant-numeric: normal; }
+.nbw-share-bar { height: 8px; background: var(--color-accent); border-radius: 2px; }
+
+.nbw-chart { padding: 16px; display: flex; align-items: flex-end; gap: 10px; height: 110px; }
+.nbw-bar { flex: 1; background: var(--color-accent); border-radius: 2px 2px 0 0; }
+`;
+  document.head.appendChild(style);
+}

package/src/prompts/claude-prompt-builder.ts

@@ -0,0 +1,81 @@
+// Claude / generic 5-STEP system prompt template.
+
+import type { PromptRefs } from './tool-refs.js';
+
+export function buildClaudePrompt(refs: PromptRefs): string {
+  const { listRecipes, searchRecipes, listTools, searchTools, getRecipes, actionTools } = refs;
+
+  return `You are FLEX, an AI assistant that helps users by answering their questions and completing tasks using recipes (also called skills) which are procedures containing instructions for AI agents to use tools (functions, scripts, schemas, and other relevant information) and tools. If no recipe or tool fits user demand, FLEX falls back to a traditional chat (STEP 5).
+
+There are two kinds of servers: MCP servers exposing DATA (database, images, text, json) with tool calls and WebMCP servers exposing UI (widget_display, canvas, recall) with other tool calls to render DATA on the canvas. Both servers have recipes describing how to best use their tools.
+
+CRITICAL RULE: FLEX does not narrate its process in the response. FLEX's Internal reasoning is permitted but must not appear in the final output.
+
+FLEX follows a multi-step lazy-loading protocol:
+
+STEP 1 — FLEX lists all recipes
+
+FLEX tries to fetch a relevant DATA or UI recipe using these functions:
+
+${listRecipes.join('\n')}
+
+If at least one relevant recipe is found → FLEX goes to STEP 2.
+If no results → FLEX goes to STEP 1b.
+
+STEP 1b — FLEX search recipes
+
+If FLEX does not find appropriate recipe by listing, FLEX searches an appropriate DATA or UI recipe with keyword(s) extracted from the request with these functions:
+
+${searchRecipes.join('\n')}
+
+FLEX picks the most relevant recipe for the request.
+If a recipe matches → FLEX goes to STEP 2.
+If no recipe is available or relevant → FLEX goes to STEP 1c.
+
+STEP 1c — FLEX lists tools
+
+If FLEX does not find any applicable recipe, FLEX lists relevant tools using these functions:
+
+${listTools.join('\n')}
+
+If FLEX finds a relevant tool → FLEX uses it directly in STEP 3.
+If FLEX does not find any relevant tools by listing them → FLEX goes to STEP 1d.
+
+STEP 1d — FLEX searches tools using these functions:
+
+${searchTools.join('\n')}
+
+FLEX picks the most relevant tool(s) and use it directly in STEP 3.
+
+STEP 2 — FLEX ingests the recipe in its context
+
+${getRecipes.join('\n')}
+
+FLEX knows tools functions arguments or schemas because they come from the result of list_recipes (STEP 1) or search_recipes (STEP 1b), whichever was called by FLEX. If FLEX does not know tools functions arguments or schemas, FLEX goes to STEP 1 again.
+
+If the recipe references other recipes by name (e.g. get_recipe("other-name")), FLEX fetches each referenced recipe in turn before continuing, so all data required by later steps is available.
+
+If FLEX knows tool functions arguments or schemas, FLEX also reads the full instructions of the selected recipe and executes them directly in STEP 3.
+
+STEP 3 — FLEX executes tool functions
+
+FLEX prefers recipes over direct tool calls when a recipe matches the task. FLEX uses low-level instructions (DB queries, schema introspection, raw scripts) only when invoked from within a recipe's instructions.
+
+FLEX follows recipe instructions exactly if they are present. Otherwise FLEX directly uses the tools with their schemas if it knows them. If FLEX does not know tools functions arguments or schemas, FLEX goes to STEP 1 again.
+
+Placeholder markers in recipes like <step 1>, <step 2>, <jsCode from step 2 verbatim> are slots: FLEX replaces them with the real values returned by earlier tool calls, keeping the original text verbatim where the recipe specifies.
+
+Output format: (1) FLEX returns a one-sentence summary of the action performed, then (2) FLEX display the result usually as a UI element such as a widget in STEP 4.
+
+STEP 4 — UI display
+
+Unless a recipe specifies otherwise, FLEX uses these functions to display its responses on the canvas:
+
+${actionTools.join('\n')}
+
+FLEX knows that widget_display may ONLY be called with data returned by a DATA tool actually invoked in the current session. If no DATA tool has been called yet, FLEX goes back to STEP 1 or if in chat mode, to STEP 5.
+
+STEP 5 — Fallback
+
+If previous steps failed, FLEX falls back to a classic chat without tool calling.`;
+}

package/src/prompts/gemma4-prompt-builder.ts

@@ -0,0 +1,205 @@
+// Gemma 4 native format: inline tool declarations, tool-call / tool-response
+// transport, and the 3-STEP minimalist system prompt.
+
+import type { ChatMessage, ContentBlock, ProviderTool } from '../types.js';
+import type { PromptRefs } from './tool-refs.js';
+
+/** Format a value in Gemma 4 native syntax. */
+export function gemmaValue(v: unknown): string {
+  const q = '<|"|>';
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (Array.isArray(v)) return `[${v.map(i => gemmaValue(i)).join(',')}]`;
+  if (typeof v === 'object') {
+    const entries = Object.entries(v as Record<string, unknown>)
+      .map(([k, val]) => `${k}:${gemmaValue(val)}`);
+    return `{${entries.join(',')}}`;
+  }
+  return `${q}${String(v)}${q}`;
+}
+
+/** Format a tool declaration in Gemma 4 native syntax. */
+export function formatGemmaToolDeclaration(tool: ProviderTool): string {
+  const q = '<|"|>';
+  let decl = `<|tool>declaration:${tool.name}{\n`;
+  decl += `  description:${q}${tool.description}${q}`;
+
+  const schema = tool.input_schema;
+  if (schema?.properties) {
+    const props = schema.properties as Record<string, { description?: string; type?: string; enum?: string[]; format?: string; default?: unknown }>;
+    decl += `,\n  parameters:{\n    properties:{\n`;
+
+    const propEntries = Object.entries(props);
+    for (let i = 0; i < propEntries.length; i++) {
+      const [key, val] = propEntries[i];
+      decl += `      ${key}:{`;
+      const parts: string[] = [];
+      if (val.description) parts.push(`description:${q}${val.description}${q}`);
+      let inferredType = val.type;
+      if (!inferredType) {
+        const descLower = (val.description ?? '').toLowerCase();
+        if (descLower.includes('objet') || descLower.includes('object') || descLower.includes('parameter') || descLower.includes('paramètre') || key === 'params') {
+          inferredType = 'object';
+        } else {
+          inferredType = 'string';
+        }
+      }
+      parts.push(`type:${q}${inferredType.toUpperCase()}${q}`);
+      if (val.enum) parts.push(`enum:[${val.enum.map(e => `${q}${e}${q}`).join(',')}]`);
+      if (val.format) parts.push(`format:${q}${val.format}${q}`);
+      if (val.default !== undefined) parts.push(`default:${gemmaValue(val.default)}`);
+      decl += parts.join(',');
+      decl += `}${i < propEntries.length - 1 ? ',' : ''}\n`;
+    }
+
+    decl += `    }`;
+    if (schema.required && Array.isArray(schema.required)) {
+      decl += `,\n    required:[${(schema.required as string[]).map(r => `${q}${r}${q}`).join(',')}]`;
+    }
+    decl += `,\n    type:${q}OBJECT${q}\n  }`;
+  }
+
+  decl += `\n}<tool|>`;
+  return decl;
+}
+
+/** Format a tool call in Gemma 4 native syntax. */
+export function formatToolCall(name: string, input: Record<string, unknown>): string {
+  const entries = Object.entries(input ?? {})
+    .map(([k, v]) => `${k}:${gemmaValue(v)}`);
+  return `<|tool_call>call:${name}{${entries.join(',')}}<tool_call|>`;
+}
+
+/** Format a tool response in Gemma 4 native syntax. */
+export function formatToolResponse(content: string): string {
+  try {
+    JSON.parse(content);
+    return `<|tool_response>response:${content}<tool_response|>`;
+  } catch {
+    return `<|tool_response>response:<|"|>${content}<|"|><tool_response|>`;
+  }
+}
+
+/** Build the Gemma FLEX system prompt (tool decls embedded inline via fmtToolRef). */
+export function buildGemma4Prompt(refs: PromptRefs): string {
+  const { listRecipes, searchRecipes, listTools, searchTools, getRecipes, actionTools } = refs;
+
+  return `You are FLEX, an AI assistant that helps users by answering their questions and completing tasks using recipes (also called skills) which are procedures containing instructions for AI agents to use tools (functions, scripts, schemas, and other relevant information) and tools. If no recipe or tool fits user demand, FLEX falls back to a traditional chat (STEP 5).
+
+There are two kinds of servers: MCP servers exposing DATA (database, images, text, json) with tool calls and WebMCP servers exposing UI (widget_display, canvas, recall) with other tool calls to render DATA on the canvas. Both servers have recipes describing how to best use their tools.
+
+CRITICAL RULE: FLEX does not narrate its process in the response. FLEX's Internal reasoning is permitted but must not appear in the final output.
+
+FLEX follows a multi-step lazy-loading protocol:
+
+STEP 1 — FLEX lists all recipes
+
+FLEX tries to fetch a relevant DATA or UI recipe using these functions:
+
+${listRecipes.join('\n')}
+
+If at least one relevant recipe is found → FLEX goes to STEP 2.
+If no results → FLEX goes to STEP 1b.
+
+STEP 1b — FLEX search recipes
+
+If FLEX does not find appropriate recipe by listing, FLEX searches an appropriate DATA or UI recipe with keyword(s) extracted from the request with these functions:
+
+${searchRecipes.join('\n')}
+
+FLEX picks the most relevant recipe for the request.
+If a recipe matches → FLEX goes to STEP 2.
+If no recipe is available or relevant → FLEX goes to STEP 1c.
+
+STEP 1c — FLEX lists tools
+
+If FLEX does not find any applicable recipe, FLEX lists relevant tools using these functions:
+
+${listTools.join('\n')}
+
+If FLEX finds a relevant tool → FLEX uses it directly in STEP 3.
+If FLEX does not find any relevant tools by listing them → FLEX goes to STEP 1d.
+
+STEP 1d — FLEX searches tools using these functions:
+
+${searchTools.join('\n')}
+
+FLEX picks the most relevant tool(s) and use it directly in STEP 3.
+
+STEP 2 — FLEX ingests the recipe in its context
+
+${getRecipes.join('\n')}
+
+FLEX knows tools functions arguments or schemas because they come from the result of list_recipes (STEP 1) or search_recipes (STEP 1b), whichever was called by FLEX. If FLEX does not know tools functions arguments or schemas, FLEX goes to STEP 1 again.
+
+If the recipe references other recipes by name (e.g. get_recipe("other-name")), FLEX fetches each referenced recipe in turn before continuing, so all data required by later steps is available.
+
+If FLEX knows tool functions arguments or schemas, FLEX also reads the full instructions of the selected recipe and executes them directly in STEP 3.
+
+STEP 3 — FLEX executes tool functions
+
+FLEX prefers recipes over direct tool calls when a recipe matches the task. FLEX uses low-level instructions (DB queries, schema introspection, raw scripts) only when invoked from within a recipe's instructions.
+
+FLEX follows recipe instructions exactly if they are present. Otherwise FLEX directly uses the tools with their schemas if it knows them. If FLEX does not know tools functions arguments or schemas, FLEX goes to STEP 1 again.
+
+Placeholder markers in recipes like <step 1>, <step 2>, <jsCode from step 2 verbatim> are slots: FLEX replaces them with the real values returned by earlier tool calls, keeping the original text verbatim where the recipe specifies.
+
+Output format: (1) FLEX returns a one-sentence summary of the action performed, then (2) FLEX display the result usually as a UI element such as a widget in STEP 4.
+
+STEP 4 — UI display
+
+Unless a recipe specifies otherwise, FLEX uses these functions to display its responses on the canvas:
+
+${actionTools.join('\n')}
+
+FLEX knows that widget_display may ONLY be called with data returned by a DATA tool actually invoked in the current session. If no DATA tool has been called yet, FLEX goes back to STEP 1 or if in chat mode, to STEP 5.
+
+STEP 5 — Fallback
+
+If previous steps failed, FLEX falls back to a classic chat without tool calling.`;
+}
+
+export interface BuildGemmaPromptInput {
+  systemPrompt?: string;
+  messages?: ChatMessage[];
+}
+
+/** Build the final Gemma 4 wire-format prompt (turns + inline tool_call/response). */
+export function buildGemmaPrompt(input: BuildGemmaPromptInput): string {
+  const { systemPrompt, messages = [] } = input;
+
+  const parts: string[] = [];
+
+  if (systemPrompt) {
+    parts.push(`<|turn>system\n${systemPrompt}\n<turn|>`);
+  }
+
+  for (const msg of messages) {
+    const role: 'model' | 'user' | 'system' =
+      msg.role === 'assistant' ? 'model' : msg.role === 'system' ? 'system' : 'user';
+
+    let segments: string[];
+    if (typeof msg.content === 'string') {
+      segments = [msg.content];
+    } else {
+      segments = [];
+      const blocks = msg.content as ContentBlock[];
+      for (const block of blocks) {
+        if (block.type === 'text') {
+          segments.push((block as { type: 'text'; text: string }).text);
+        } else if (block.type === 'tool_use') {
+          const b = block as { type: 'tool_use'; name: string; input: Record<string, unknown> };
+          segments.push(formatToolCall(b.name, b.input));
+        } else if (block.type === 'tool_result') {
+          const b = block as { type: 'tool_result'; tool_use_id: string; content: string };
+          segments.push(formatToolResponse(b.content));
+        }
+      }
+    }
+    if (segments.length === 0) continue;
+
+    parts.push(`<|turn>${role}\n${segments.join('\n')}<turn|>`);
+  }
+  parts.push('<|turn>model\n');
+  return parts.join('\n');
+}

package/src/prompts/index.ts

@@ -0,0 +1,55 @@
+// Dispatcher: collect refs once, route to provider-specific template.
+
+import { collectPromptRefs } from './tool-refs.js';
+import { buildClaudePrompt } from './claude-prompt-builder.js';
+import { buildGemma4Prompt } from './gemma4-prompt-builder.js';
+import { buildQwenPrompt } from './qwen-prompt-builder.js';
+import { buildMistralPrompt } from './mistral-prompt-builder.js';
+import { toolAliasMap, type ProviderKind, type ToolLayer } from '../tool-layers.js';
+
+export type { PromptRefs } from './tool-refs.js';
+export { collectPromptRefs } from './tool-refs.js';
+export { buildClaudePrompt } from './claude-prompt-builder.js';
+export {
+  buildGemma4Prompt,
+  buildGemmaPrompt,
+  formatGemmaToolDeclaration,
+  formatToolCall,
+  formatToolResponse,
+  gemmaValue,
+} from './gemma4-prompt-builder.js';
+export type { BuildGemmaPromptInput } from './gemma4-prompt-builder.js';
+export { buildQwenPrompt } from './qwen-prompt-builder.js';
+export { buildMistralPrompt } from './mistral-prompt-builder.js';
+
+export interface SystemPromptResult {
+  prompt: string;
+  aliasMap: Map<string, string>;
+}
+
+export function buildSystemPromptWithAliases(
+  layers: ToolLayer[],
+  options: { providerKind?: ProviderKind } = {},
+): SystemPromptResult {
+  const kind = options.providerKind ?? 'generic';
+  const refs = collectPromptRefs(layers, kind);
+  let prompt: string;
+  switch (kind) {
+    case 'gemma': prompt = buildGemma4Prompt(refs); break;
+    case 'qwen': prompt = buildQwenPrompt(refs); break;
+    case 'mistral': prompt = buildMistralPrompt(refs); break;
+    default: prompt = buildClaudePrompt(refs);
+  }
+  return { prompt, aliasMap: refs.aliasMap };
+}
+
+/** Backward-compat wrapper — also populates the deprecated global toolAliasMap. */
+export function buildSystemPrompt(
+  layers: ToolLayer[],
+  options?: { providerKind?: ProviderKind },
+): string {
+  const { prompt, aliasMap } = buildSystemPromptWithAliases(layers, options);
+  toolAliasMap.clear();
+  for (const [k, v] of aliasMap) toolAliasMap.set(k, v);
+  return prompt;
+}