@webmcp-auto-ui/agent 2.5.25 → 2.5.26

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,16 @@ export function sanitizeServerName(name: string): string {
   return result || 'mcp';
 }
 
+// ── Discovery pseudo-tool descriptions (shared between prompt and tool schemas) ──
+const shortSearchToolsDesc = (serverName: string) =>
+  `Search tools by keyword on the ${serverName} server.`;
+const shortListToolsDesc = (serverName: string) =>
+  `List ALL tools on the ${serverName} server.`;
+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 +64,113 @@ 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. */
+export type ProviderKind = 'generic' | 'gemma';
+
+/** Extract the first parameter name from a ProviderTool's input_schema.
+ *  Priority: first required field > first property > fallback.
+ *  Used to emit real parameter names in tool references for better prompting. */
+function firstParamName(tool?: ProviderTool, fallback = 'query'): string {
+  if (!tool?.input_schema) return fallback;
+  const schema = tool.input_schema as Record<string, unknown>;
+  const required = (schema.required as string[] | undefined) ?? [];
+  if (required.length > 0) return required[0];
+  const props = (schema.properties as Record<string, unknown> | undefined) ?? {};
+  return Object.keys(props)[0] ?? fallback;
+}
+
+/** Format a tool reference for inclusion in the system prompt.
+ *  Generic (Claude/Ollama/etc): `name()` or `name(arg1, arg2)`.
+ *  Gemma: emits the full `<|tool>declaration:...<tool|>` block inline when a tool is provided,
+ *         so declarations appear in context at each step of the workflow (no appendix).
+ *         Falls back to a plain backtick reference if no tool is provided.
+ */
+function fmtToolRef(
+  prefixedName: string,
+  args: string[] = [],
+  kind: ProviderKind = 'generic',
+  tool?: ProviderTool,
+): string {
+  if (kind === 'gemma' && tool) {
+    // Inline: full Gemma declaration with canonical prefixed name but real schema
+    return formatGemmaToolDeclaration({ ...tool, name: prefixedName });
+  }
+  if (kind === 'gemma') {
+    return args.length ? `\`${prefixedName}(${args.join(', ')})\`` : `\`${prefixedName}\``;
+  }
+  return args.length ? `${prefixedName}(${args.join(', ')})` : `${prefixedName}()`;
+}
+
+/**
+ * Format a value for Gemma 4 native tool syntax.
+ * Strings use <|"|> delimiters, numbers/booleans/null are bare.
+ */
+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.
+ * Emitted in the system prompt tail so Gemma sees tool schemas alongside the
+ * STEP-by-STEP instructions.
+ */
+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}`);
+      // If no type specified, infer OBJECT for params-like fields to avoid
+      // Gemma wrapping the value in <|"|>...<|"|> (treating it as a string)
+      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;
+}
+
 /** 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 +416,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)) {
@@ -347,11 +474,30 @@ export interface SystemPromptResult {
 /**
  * Build system prompt with a local alias map (parallel-safe).
  * Prefer this over buildSystemPrompt() when running multiple agent loops.
+ *
+ * The `providerKind` option controls the syntax of tool references in the prompt:
+ *  - `'generic'` (default): `tool_name()` / `tool_name(arg)` — for Claude, Ollama, etc.
+ *  - `'gemma'`: `<|tool_call>call:tool_name{}<tool_call|>` — Gemma 4 native format.
  */
-export function buildSystemPromptWithAliases(layers: ToolLayer[]): SystemPromptResult {
+export function buildSystemPromptWithAliases(
+  layers: ToolLayer[],
+  options: { providerKind?: ProviderKind } = {},
+): SystemPromptResult {
+  const kind = options.providerKind ?? 'generic';
   const mcpLayers = layers.filter((l): l is McpLayer => l.protocol === 'mcp');
   const webmcpLayers = layers.filter((l): l is WebMcpLayer => l.protocol === 'webmcp');
 
+  // DISPLAY servers = WebMCP layers that expose widget_display (can render on canvas).
+  // DATA servers = everything else (MCP servers + WebMCP without widget_display).
+  const displayLayers = webmcpLayers.filter(l => l.tools.some(t => t.name === 'widget_display'));
+  const dataLayers = layers.filter(l => !displayLayers.includes(l as WebMcpLayer));
+
+  // Pre-build an index of prefixed tool name → ProviderTool so we can emit
+  // real param names (and, for Gemma, inline declarations) at each call site.
+  const providerToolsByName = new Map<string, ProviderTool>(
+    buildToolsFromLayers(layers, { sanitize: true }).tools.map(t => [t.name, t]),
+  );
+
   const aliasMap = new Map<string, string>();
 
   // ── Collect search_recipes / list_recipes / get_recipe from all layers ──
@@ -363,20 +509,43 @@ export function buildSystemPromptWithAliases(layers: ToolLayer[]): SystemPromptR
 
   // WebMCP layers: always exact match (we control the naming)
   for (const l of webmcpLayers) {
-    const prefix = `${sanitizeServerName(l.serverName)}_webmcp_`;
+    const prefix = `${sanitizeServerName(l.serverName)}_ui_`;
     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()`);
+      if (t.name === 'search_recipes') {
+        const name = `${prefix}search_recipes`;
+        const toolDef = providerToolsByName.get(name);
+        searchRecipes.push(fmtToolRef(name, [firstParamName(toolDef, 'query')], kind, toolDef));
+      }
+      if (t.name === 'list_recipes') {
+        const name = `${prefix}list_recipes`;
+        const toolDef = providerToolsByName.get(name);
+        listRecipes.push(fmtToolRef(name, [], kind, toolDef));
+      }
+      if (t.name === 'get_recipe') {
+        const name = `${prefix}get_recipe`;
+        const toolDef = providerToolsByName.get(name);
+        getRecipes.push(fmtToolRef(name, [firstParamName(toolDef, 'id')], kind, toolDef));
+      }
     }
-    // Pseudo-tools for tool discovery on WebMCP servers
-    searchTools.push(`${prefix}search_tools(query)`);
-    listTools.push(`${prefix}list_tools()`);
+    // Pseudo-tools for tool discovery on WebMCP servers — not in providerToolsByName,
+    // so we build synthetic ProviderTools for inline declarations.
+    const searchToolsPseudo: ProviderTool = {
+      name: `${prefix}search_tools`,
+      description: shortSearchToolsDesc(l.serverName),
+      input_schema: { type: 'object', properties: { query: { type: 'string', description: 'Keyword to search for.' } }, required: ['query'] },
+    };
+    searchTools.push(fmtToolRef(`${prefix}search_tools`, ['query'], kind, searchToolsPseudo));
+    const listToolsPseudo: ProviderTool = {
+      name: `${prefix}list_tools`,
+      description: shortListToolsDesc(l.serverName),
+      input_schema: { type: 'object', properties: {} },
+    };
+    listTools.push(fmtToolRef(`${prefix}list_tools`, [], kind, listToolsPseudo));
   }
 
   // MCP layers: 4-layer matching + alias registration
   for (const l of mcpLayers) {
-    const prefix = `${sanitizeServerName(l.serverName)}_mcp_`;
+    const prefix = `${sanitizeServerName(l.serverName)}_data_`;
     const matches = resolveCanonicalTools(l.tools);
 
     for (const m of matches) {
@@ -388,32 +557,126 @@ export function buildSystemPromptWithAliases(layers: ToolLayer[]): SystemPromptR
         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}()`);
+      // Look up the REAL tool (by real prefixed name) to get the actual schema
+      const realToolDef = providerToolsByName.get(realPrefixed);
+
+      if (m.role === 'search_recipes') {
+        searchRecipes.push(fmtToolRef(canonicalPrefixed, [firstParamName(realToolDef, 'query')], kind, realToolDef));
+      }
+      if (m.role === 'list_recipes') {
+        listRecipes.push(fmtToolRef(canonicalPrefixed, [], kind, realToolDef));
+      }
+      if (m.role === 'get_recipe') {
+        getRecipes.push(fmtToolRef(canonicalPrefixed, [firstParamName(realToolDef, 'id')], kind, realToolDef));
+      }
     }
 
     // Pseudo-tools for tool discovery on all MCP servers
-    searchTools.push(`${prefix}search_tools(query)`);
-    listTools.push(`${prefix}list_tools()`);
+    const searchToolsPseudo: ProviderTool = {
+      name: `${prefix}search_tools`,
+      description: shortSearchToolsDesc(l.serverName),
+      input_schema: { type: 'object', properties: { query: { type: 'string', description: 'Keyword to search for.' } }, required: ['query'] },
+    };
+    searchTools.push(fmtToolRef(`${prefix}search_tools`, ['query'], kind, searchToolsPseudo));
+    const listToolsPseudo: ProviderTool = {
+      name: `${prefix}list_tools`,
+      description: shortListToolsDesc(l.serverName),
+      input_schema: { type: 'object', properties: {} },
+    };
+    listTools.push(fmtToolRef(`${prefix}list_tools`, [], kind, listToolsPseudo));
   }
 
   // ── WebMCP action tools (widget_display, canvas, recall) ──
+  // Iterate in canonical order (widget_display, canvas, recall) so the prompt
+  // always lists them in the same sequence regardless of tool definition order.
   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}`);
+    const prefix = `${sanitizeServerName(l.serverName)}_ui_`;
+    for (const actionName of ACTION_NAMES) {
+      if (l.tools.some(t => t.name === actionName)) {
+        const prefixedName = `${prefix}${actionName}`;
+        const toolDef = providerToolsByName.get(prefixedName);
+        const args = actionName === 'widget_display' ? ['name', 'params'] : [];
+        actionTools.push(fmtToolRef(prefixedName, args, kind, toolDef));
+      }
     }
   }
 
-  // ── 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).
+  // Same refs, grouped by DATA vs DISPLAY category, for the gemma-minimalist template.
+  const dataPrefixes = new Set(dataLayers.map(l => `${sanitizeServerName(l.serverName)}_${protocolToken(l.protocol)}_`));
+  const displayPrefixes = new Set(displayLayers.map(l => `${sanitizeServerName(l.serverName)}_ui_`));
+
+  function splitByCategory(refs: string[]): { data: string[]; display: string[] } {
+    // Refs may be backticked names, full declarations, or tool_name(arg) — in all cases,
+    // the prefixed name (e.g. `tricoteuses_data_search_recipes`) is detectable by substring match.
+    const data: string[] = [];
+    const display: string[] = [];
+    for (const ref of refs) {
+      const isDisplay = [...displayPrefixes].some(p => ref.includes(p));
+      if (isDisplay) display.push(ref);
+      else data.push(ref);
+    }
+    return { data, display };
+  }
+
+  const listRecipesByCat = splitByCategory(listRecipes);
+  const searchRecipesByCat = splitByCategory(searchRecipes);
+  const getRecipesByCat = splitByCategory(getRecipes);
+  // Suppress unused-variable warnings — dataPrefixes is referenced indirectly via dataLayers.
+  void dataPrefixes;
+
+  // ── Build prompt ──
+  let prompt: string;
+
+  if (kind === 'gemma') {
+    // ── Minimalist template for Gemma (4B/E4B), inline declarations included ──
+    const dataListSearch = [
+      ...listRecipesByCat.data,
+      ...searchRecipesByCat.data,
+    ].join('\n');
+    const displayListSearch = [
+      ...listRecipesByCat.display,
+      ...searchRecipesByCat.display,
+    ].join('\n');
+    const allGetRecipes = [
+      ...getRecipesByCat.data,
+      ...getRecipesByCat.display,
+    ].join('\n');
+
+    prompt = `Route: DATA (fetch) or DISPLAY (render). Greetings → chat.
+
+STEP 1 — List or search a recipe.
+DATA:
+${dataListSearch}
+DISPLAY:
+${displayListSearch}
+The tool results are for you, not for the user. Pick the best match and go to STEP 2. Never ask the user to choose.
+
+STEP 2 — Fetch the recipe.
+${allGetRecipes}
+
+STEP 3 — Execute using the schema from STEP 2.
+- Data: follow the recipe (SQL / FTS / script).
+- Display: call widget_display(name, params).
+${actionTools.join('\n')}
+If no recipe fits, use a tool directly:
+${listTools.join('\n')}
+${searchTools.join('\n')}
+Only use data returned by tools or given by the user. Never fabricate.
+
+Reply: one-line summary + result.`;
+  } else {
+    // ── Existing generic template for Claude/remote — DO NOT MODIFY ──
+    const reasoningRule = 'Do not narrate your process in the response. Internal reasoning is permitted but must not appear in the final output. For trivial conversational messages such as greetings or small talk, skip directly to STEP 5.';
+
+    prompt = `You are an AI assistant that helps users by answering their questions and completing tasks using recipes (also called skills) — instructions for an AI agent with scripts, schemas, and information. If no recipe or tool fits, fall back to a traditional chat (STEP 5).
+
+There are two kinds of servers: MCP servers expose DATA (recipes, instructions, tools) AND WebMCP servers expose UI tools (widget_display, canvas, recall) to render DATA on the canvas.
 
 You MUST NOT skip steps.
 
-CRITICAL RULE: You MUST execute all steps silently. Do NOT generate any internal reasoning, thinking, or intermediate text.
+CRITICAL RULE: ${reasoningRule}
 
 STEP 1 — List all recipes
 
@@ -452,12 +715,17 @@ Pick the most relevant tool(s) and use them to respond (go to STEP 3).
 STEP 2 — Read the recipe
 
 ${getRecipes.join('\n')}
+The id comes from the result of list_recipes (STEP 1) or search_recipes (STEP 1b), whichever was called.
 
 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.
+Prefer recipes over direct tool calls when a recipe matches the task. Use low-level instructions (DB queries, schema introspection, raw scripts) only when invoked from within a recipe's instructions.
+
+Follow the recipe instructions exactly if you have one. Otherwise use the tools with their schemas.
+
+Output format: (1) a one-sentence summary of the action performed, then (2) the result. Nothing else.
 
 STEP 4 — UI display
 
@@ -470,6 +738,10 @@ widget_display may ONLY be called with data returned by a non-autoui DATA tool a
 STEP 5 — Fallback
 
 If previous steps failed, fall back to a classic chat without tool calling.`;
+  }
+
+  // Note: for Gemma (kind === 'gemma'), tool declarations are emitted INLINE at each
+  // STEP via `fmtToolRef(..., kind, tool)` — no appendix is appended here.
 
   return { prompt, aliasMap };
 }
@@ -478,8 +750,8 @@ If previous steps failed, fall back to a classic chat without tool calling.`;
  *  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);
+export function buildSystemPrompt(layers: ToolLayer[], options?: { providerKind?: ProviderKind }): string {
+  const { prompt, aliasMap } = buildSystemPromptWithAliases(layers, options);
 
   // Populate deprecated global singleton for backward compat
   toolAliasMap.clear();
@@ -503,7 +775,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 +799,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 +819,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 +862,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];
 

package/src/types.ts

@@ -48,10 +48,15 @@ export interface LLMResponse {
 export interface LLMProvider {
   readonly name: string;
   readonly model: string;
+  /** Hint for system prompt builders: which syntax this provider expects for tool
+   *  references. `undefined` → treated as `'generic'`. Providers using a non-standard
+   *  native call syntax (e.g. Gemma) should set this so the agent loop can build
+   *  the prompt with the correct formatting. */
+  readonly promptKind?: 'generic' | 'gemma';
   chat(
     messages: ChatMessage[],
     tools: ProviderTool[],
-    options?: { signal?: AbortSignal; cacheEnabled?: boolean; system?: string; maxTokens?: number; temperature?: number; topK?: number; onToken?: (token: string) => void; maxTools?: number; maxMessages?: number }
+    options?: { signal?: AbortSignal; cacheEnabled?: boolean; system?: string; maxTokens?: number; temperature?: number; topK?: number; onToken?: (token: string) => void }
   ): Promise<LLMResponse>;
 }
 

package/tests/loop.test.ts

@@ -77,7 +77,7 @@ describe('runAgentLoop', () => {
       name: 'mock', model: 'claude-haiku',
       // Always returns a tool call — never end_turn (using prefixed tool name)
       chat: vi.fn().mockResolvedValue({
-        content: [{ type: 'tool_use', id: 'tc1', name: 'test_mcp_search', input: { q: 'x' } }],
+        content: [{ type: 'tool_use', id: 'tc1', name: 'test_data_search', input: { q: 'x' } }],
         stopReason: 'tool_use',
       } satisfies LLMResponse),
     };
@@ -100,7 +100,7 @@ describe('runAgentLoop', () => {
       name: 'mock', model: 'claude-haiku',
       chat: vi.fn()
         .mockImplementationOnce(async () => {
-          return { content: [{ type: 'tool_use', id: 'tc1', name: 'test_mcp_search', input: { q: 'x' } }], stopReason: 'tool_use' } satisfies LLMResponse;
+          return { content: [{ type: 'tool_use', id: 'tc1', name: 'test_data_search', input: { q: 'x' } }], stopReason: 'tool_use' } satisfies LLMResponse;
         })
         .mockImplementationOnce(async () => {
           ac.abort();

package/src/providers/gemma.worker.legacy.ts

@@ -1,123 +0,0 @@
-/**
- * Gemma 4 Web Worker
- * Uses @huggingface/transformers v3+ with WebGPU
- * Requires COOP/COEP headers for SharedArrayBuffer
- *
- * Messages IN:  { type: 'init', model?: string }
- *               { type: 'chat', id: string, prompt: string, maxTokens?: number }
- *               { type: 'abort', id: string }
- * Messages OUT: { type: 'progress', progress: number, status: string }
- *               { type: 'ready' }
- *               { type: 'token', id: string, token: string }
- *               { type: 'done', id: string, text: string }
- *               { type: 'error', id: string | null, message: string }
- */
-
-import { AutoProcessor, Gemma4ForConditionalGeneration, TextStreamer, env } from '@huggingface/transformers';
-
-env.allowLocalModels = false;
-
-const WASM_MODEL_REGISTRY: Record<string, { repo: string; dtype: string }> = {
-  'gemma-e2b': { repo: 'onnx-community/gemma-4-E2B-it-ONNX', dtype: 'q4f16' },
-  'gemma-e4b': { repo: 'onnx-community/gemma-4-E4B-it-ONNX', dtype: 'q4f16' },
-};
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let processor: any = null;
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let model: any = null;
-const abortControllers = new Map<string, AbortController>();
-
-self.onmessage = async (e: MessageEvent) => {
-  const { type, id, model: modelId, prompt } = e.data as {
-    type: string; id?: string; model?: string; prompt?: string;
-  };
-
-  if (type === 'init') {
-    try {
-      const key = modelId ?? 'gemma-e2b';
-      const { repo, dtype } = WASM_MODEL_REGISTRY[key] ?? WASM_MODEL_REGISTRY['gemma-e2b'];
-      const device = typeof navigator !== 'undefined' && 'gpu' in navigator ? 'webgpu' : 'wasm';
-
-      const progress_callback = (p: { status: string; progress?: number; loaded?: number; total?: number; name?: string }) => {
-        self.postMessage({
-          type: 'progress',
-          progress: p.progress ?? 0,
-          status: p.status,
-          name: p.name ?? '',
-          loaded: p.loaded,
-          total: p.total,
-        });
-      };
-
-      processor = await AutoProcessor.from_pretrained(repo, { progress_callback });
-      model = await Gemma4ForConditionalGeneration.from_pretrained(repo, {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        dtype: dtype as any,
-        device,
-        progress_callback,
-      });
-
-      self.postMessage({ type: 'ready' });
-    } catch (err) {
-      self.postMessage({ type: 'error', id: null, message: String(err) });
-    }
-    return;
-  }
-
-  const maxTokens = (e.data as { maxTokens?: number }).maxTokens;
-
-  if (type === 'chat' && id && prompt) {
-    if (!model || !processor) {
-      self.postMessage({ type: 'error', id, message: 'Model not initialized' });
-      return;
-    }
-
-    const ac = new AbortController();
-    abortControllers.set(id, ac);
-    let fullText = '';
-
-    try {
-      const conversation = [{ role: 'user', content: [{ type: 'text', text: prompt }] }];
-      const inputs = await processor.apply_chat_template(conversation, {
-        tokenize: true,
-        add_generation_prompt: true,
-        return_dict: true,
-      });
-
-      const streamer = new TextStreamer(processor.tokenizer, {
-        skip_prompt: true,
-        callback_function: (token: string) => {
-          fullText += token;
-          self.postMessage({ type: 'token', id, token });
-        },
-      });
-
-      await model.generate({
-        ...inputs,
-        max_new_tokens: maxTokens ?? 8192,
-        do_sample: true,
-        temperature: 0.7,
-        streamer,
-      });
-
-      abortControllers.delete(id);
-      self.postMessage({ type: 'done', id, text: fullText });
-    } catch (err) {
-      abortControllers.delete(id);
-      const msg = String(err);
-      if (msg.includes('AbortError') || msg.includes('aborted')) {
-        self.postMessage({ type: 'done', id, text: fullText });
-      } else {
-        self.postMessage({ type: 'error', id, message: msg });
-      }
-    }
-    return;
-  }
-
-  if (type === 'abort' && id) {
-    abortControllers.get(id)?.abort();
-    abortControllers.delete(id);
-    return;
-  }
-};