@webmcp-auto-ui/agent 2.5.26 → 2.5.28

package/src/server/hawkProxy.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared Hawk proxy handler — used by apps' /api/hawk/+server.ts
+ * Hawk = OpenAI-compatible endpoint at https://hawk.hyperskills.net/v1
+ * Bearer token lives server-side in HAWK_API_KEY env var.
+ */
+function sanitizeId(id: string | undefined): string {
+  if (!id) return 'x';
+  const clean = id.replace(/[^a-zA-Z0-9]/g, '');
+  return clean || 'x';
+}
+
+/**
+ * Some llama-cpp chat templates (Qwen, Mistral family) enforce alphanumeric
+ * tool_call IDs via Jinja raise_exception. Gemma's template drops tool_use_id
+ * entirely (cf. gemma4-prompt-builder.ts:194) — safe passthrough.
+ * Mirrors the convention of sanitizeServerName (tool-layers.ts:24).
+ */
+function needsIdSanitize(model: string | null | undefined): boolean {
+  if (!model) return false;
+  return /^(qwen|mistral|ministral|devstral|codestral|bielik)/.test(model);
+}
+
+export async function hawkProxy(
+  body: Record<string, unknown>,
+  apiKey: string,
+  model?: string | null,
+): Promise<Response> {
+  if (!apiKey) {
+    return new Response('HAWK_API_KEY missing', { status: 500 });
+  }
+  const m = model ?? 'qwen35-4b';
+  const cloned = JSON.parse(JSON.stringify(body)) as Record<string, unknown>;
+  if (needsIdSanitize(m) && Array.isArray(cloned.messages)) {
+    for (const msg of cloned.messages as Array<Record<string, unknown>>) {
+      if (msg.role === 'assistant' && Array.isArray(msg.tool_calls)) {
+        for (const tc of msg.tool_calls as Array<Record<string, unknown>>) {
+          tc.id = sanitizeId(tc.id as string | undefined);
+        }
+      } else if (msg.role === 'tool' && typeof msg.tool_call_id === 'string') {
+        msg.tool_call_id = sanitizeId(msg.tool_call_id);
+      }
+    }
+  }
+  const res = await fetch('https://hawk.hyperskills.net/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ ...cloned, model: m }),
+  });
+  if (!res.ok) return new Response(await res.text(), { status: res.status });
+  return Response.json(await res.json());
+}

package/src/server/index.ts

@@ -0,0 +1,2 @@
+export { llmProxy } from './llmProxy.js';
+export { hawkProxy } from './hawkProxy.js';

package/src/tool-layers.ts

@@ -33,11 +33,7 @@ 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.`;
+// ── 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) =>
@@ -66,110 +62,10 @@ 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;
-}
+ *  - `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 {
@@ -465,300 +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.
- *
- * 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[],
-  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 ──
-  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)}_ui_`;
-    for (const t of l.tools) {
-      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 — 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)}_data_`;
-    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);
-      }
-
-      // 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
-    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)}_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));
-      }
-    }
-  }
-
-  // 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: ${reasoningRule}
-
-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')}
-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
-
-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
-
-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.`;
-  }
-
-  // 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 };
-}
-
-/** 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[], options?: { providerKind?: ProviderKind }): string {
-  const { prompt, aliasMap } = buildSystemPromptWithAliases(layers, options);
-
-  // 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 {