@hotmeshio/long-tail 0.1.0

package/build/system/workflows/mcp-query/index.js

@@ -0,0 +1,227 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpQuery = mcpQuery;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const defaults_1 = require("../../../modules/defaults");
+const activities = __importStar(require("./activities"));
+const interceptorActivities = __importStar(require("../../../services/interceptor/activities"));
+const prompts_1 = require("./prompts");
+const { loadTools, callMcpTool, callQueryLLM, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+    retryPolicy: {
+        maximumAttempts: 3,
+        backoffCoefficient: 2,
+        maximumInterval: '10 seconds',
+    },
+});
+const { ltEnrichEscalationRouting, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities: interceptorActivities,
+    taskQueue: 'lt-interceptor',
+    retryPolicy: { maximumAttempts: 3 },
+});
+const MAX_TOOL_ROUNDS = defaults_1.TOOL_ROUNDS_MCP_QUERY;
+/**
+ * MCP Query workflow (leaf).
+ *
+ * Dynamic MCP tool orchestration via LLM agentic loop.
+ * Discovers available MCP tools by tag and uses an LLM to
+ * fulfill arbitrary requests. This workflow ONLY handles
+ * dynamic execution — compiled workflow matching is done
+ * by the mcpQueryRouter parent.
+ *
+ * Clean execution traces from this workflow are what get
+ * compiled into deterministic YAML workflows.
+ */
+async function mcpQuery(envelope) {
+    const prompt = (envelope.data?.prompt || envelope.data?.question);
+    const tags = envelope.data?.tags;
+    if (!prompt) {
+        return {
+            type: 'return',
+            data: {
+                title: 'No prompt provided',
+                summary: 'Please provide a prompt describing what you want to accomplish.',
+                result: null,
+                tool_calls_made: 0,
+            },
+        };
+    }
+    // Load raw MCP tools (no compiled workflow discovery — router handles that)
+    const raw = await loadTools(tags);
+    const toolIds = raw.toolIds;
+    // Build system prompt: strategy first, then tool inventory
+    let serverSection = '';
+    if (raw.strategy) {
+        serverSection += `${raw.strategy}\n\n`;
+    }
+    serverSection += `## Available MCP Servers\n\n${raw.inventory}`;
+    const messages = [
+        {
+            role: 'system',
+            content: prompts_1.MCP_QUERY_SYSTEM_PROMPT + `\n\n${serverSection}`,
+        },
+    ];
+    // If this is a re-run after triage, inject triage learnings as context
+    const triageContext = envelope.resolver?._triageContext;
+    if (triageContext) {
+        const triageHints = [
+            `This is a re-run after a previous attempt failed and was triaged.`,
+            triageContext.diagnosis ? `Previous diagnosis: ${triageContext.diagnosis}` : '',
+            triageContext.actions_taken?.length ? `Actions already taken: ${triageContext.actions_taken.join('; ')}` : '',
+            triageContext.recommendation ? `Recommendation: ${triageContext.recommendation}` : '',
+        ].filter(Boolean).join('\n');
+        messages.push({ role: 'user', content: triageHints });
+        messages.push({ role: 'assistant', content: 'Understood. I will use these learnings to take a more targeted approach this time.' });
+    }
+    messages.push({ role: 'user', content: prompt });
+    let toolCallCount = 0;
+    // Agentic loop: LLM decides → execute tools → feed back → repeat
+    const BUDGET_WARNING_THRESHOLD = 3;
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+        const remaining = MAX_TOOL_ROUNDS - round;
+        // Inject budget warning when approaching the limit
+        if (remaining <= BUDGET_WARNING_THRESHOLD && remaining < MAX_TOOL_ROUNDS) {
+            messages.push({
+                role: 'user',
+                content: `[Rounds: ${remaining} remaining] Wrap up: consolidate results and return your final JSON response. Do not start new multi-step work.`,
+            });
+        }
+        const response = await callQueryLLM(messages, toolIds);
+        if (!response.tool_calls?.length) {
+            return buildQueryReturn(response.content || '', toolCallCount);
+        }
+        const fnCalls = response.tool_calls.filter((tc) => tc.type === 'function');
+        messages.push({
+            role: 'assistant',
+            content: response.content,
+            tool_calls: fnCalls,
+        });
+        for (const toolCall of fnCalls) {
+            toolCallCount++;
+            let args = {};
+            try {
+                args = JSON.parse(toolCall.function.arguments || '{}');
+            }
+            catch {
+                args = {};
+            }
+            const result = await callMcpTool(toolCall.function.name, args);
+            // Durable waitFor: if the tool returns a signal, pause until human responds
+            if (result?.type === 'waitFor' && result?.signalId) {
+                const ctx = hotmesh_1.Durable.workflow.getContext();
+                const workflowType = ctx.workflowTopic.replace(`${ctx.taskQueue}-`, '');
+                await ltEnrichEscalationRouting({
+                    escalationId: result.escalationId,
+                    signalRouting: {
+                        taskQueue: ctx.taskQueue,
+                        workflowType,
+                        workflowId: ctx.workflowId,
+                        signalId: result.signalId,
+                    },
+                    claimForUserId: envelope.lt?.userId,
+                });
+                const signalData = await hotmesh_1.Durable.workflow.waitFor(result.signalId);
+                messages.push({
+                    role: 'tool',
+                    tool_call_id: toolCall.id,
+                    content: JSON.stringify(signalData),
+                });
+                continue;
+            }
+            messages.push({
+                role: 'tool',
+                tool_call_id: toolCall.id,
+                content: JSON.stringify(result),
+            });
+        }
+    }
+    // Exhausted rounds — ask LLM for diagnostic summary
+    messages.push({
+        role: 'user',
+        content: prompts_1.ROUNDS_EXHAUSTED_DIAGNOSTIC_PROMPT,
+    });
+    const finalResponse = await callQueryLLM(messages, undefined);
+    const parsed = parseJsonResponse(finalResponse.content || '');
+    return {
+        type: 'return',
+        data: {
+            ...parsed,
+            tool_calls_made: toolCallCount,
+            rounds_exhausted: true,
+        },
+        milestones: [
+            { name: 'mcp_query', value: 'completed' },
+            { name: 'tool_calls', value: String(toolCallCount) },
+            { name: 'rounds_exhausted', value: 'true' },
+        ],
+    };
+}
+/** Build the LTReturn for a completed query, with standard + enriched milestones. */
+function buildQueryReturn(content, toolCallCount, extraMilestones = []) {
+    const parsed = parseJsonResponse(content);
+    const milestones = [
+        { name: 'mcp_query', value: 'completed' },
+        { name: 'tool_calls', value: String(toolCallCount) },
+    ];
+    if (parsed.knowledge_updated?.length) {
+        milestones.push({ name: 'knowledge_updated', value: String(parsed.knowledge_updated.length) });
+    }
+    if (parsed.compilation_candidate) {
+        milestones.push({ name: 'compilation_candidate', value: 'true' });
+    }
+    milestones.push(...extraMilestones);
+    return {
+        type: 'return',
+        data: { ...parsed, tool_calls_made: toolCallCount },
+        milestones,
+    };
+}
+function parseJsonResponse(content) {
+    const cleaned = content
+        .replace(/^```(?:json)?\s*/m, '')
+        .replace(/\s*```$/m, '')
+        .trim();
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch {
+        return {
+            title: 'Query Complete',
+            summary: cleaned || 'No response generated.',
+            result: null,
+        };
+    }
+}

package/build/system/workflows/mcp-query/prompts.d.ts

@@ -0,0 +1,4 @@
+export declare const MCP_QUERY_SYSTEM_PROMPT = "You are a general-purpose AI assistant for Long Tail \u2014 a durable workflow system with MCP tool integration.\n\nYou have access to **MCP tools** from registered servers. Your job is to fulfill the user's request using these tools.\n\n## Tool Selection \u2014 CRITICAL, READ CAREFULLY:\n- A \"Tool Selection Strategy\" section appears before the tool inventory. It tells you EXACTLY which tools to use and which to NEVER use. **Follow it strictly \u2014 violations cause failures.**\n- **Minimize total tool calls.** Before making a call, ask: \"Is there a single tool that does all of this?\" If yes, use it. If you find yourself chaining 3+ calls to accomplish what one composite tool could do, stop and switch.\n- **For multi-item tasks, look for batch tools.** If you need to perform the same operation on many items, check if a tool accepts a list/array input. One batch call is always better than N individual calls.\n\n**Principles for dynamic execution:**\n- **Chain tools logically.** If a task requires multiple steps, chain tool calls in the natural order. Pass outputs from one step as inputs to the next.\n- **Handle sessions and handles.** Some tools return session identifiers (page_id, _handle, session_id). Pass these to ALL subsequent calls that need to operate within that session. Session handles maintain authentication and state \u2014 losing them means starting over. NEVER open a new session when you already have one.\n- **Discover before acting.** When you need to understand structure, content, or available options, use discovery/extraction tools first. Then pass discovered values to subsequent tools. NEVER guess input values.\n- **Iterate when needed.** If you need to perform the same action on multiple items and no batch tool exists, call the tool for each item. The system will detect this pattern when compiling the workflow later.\n- **Use credentials from the prompt.** The user provides credentials in their request. NEVER persist credentials to the filesystem.\n- **Trust tool defaults.** Tools define default values for optional parameters. Only override defaults when the user provides a specific value or you've discovered the correct one via a prior tool call.\n- **When a tool call fails, adapt.** Use discovery tools to learn the correct structure, then retry with discovered values. Don't retry with the same wrong parameters.\n- **Fulfill the complete request.** If the user asks to process N items, process all N items. Don't stop early or summarize partway through.\n- **Budget your tool rounds.** You have a limited number of tool rounds. A budget indicator (e.g., \"[Rounds: 3 remaining]\") may appear in the conversation. When you see 3 or fewer rounds remaining, wrap up: consolidate partial results, write any pending output, and return your final response. Prefer batch/composite tools to conserve rounds.\n\n### 3. Mark for Compilation\nIf you completed a multi-step task that seems reusable, set `compilation_candidate: true` in your response. The execution trace can then be compiled into a deterministic YAML workflow \u2014 turning this dynamic run into a fast, repeatable tool for next time.\n\n## Escalation\n\nEscalate only when truly stuck \u2014 retry with alternatives first.\n\n- **For input you need before continuing** (credentials, approvals, missing data):\n  Use escalate_and_wait. Specify a form_schema describing what fields you need. The workflow pauses until the human responds \u2014 no polling needed.\n- **For fire-and-forget notifications** (advisory, FYI):\n  Use escalate_to_human.\n- **Escalate to 'engineer' role** \u2014 when you need human judgment or infrastructure help\n- **Escalate to 'mcp' role** \u2014 when you need tool capabilities not in the current inventory\n\nWhen escalating, provide specific context: what you tried, what failed, what you need.\n\n## Credential Tokens\nValues formatted as `eph:v1:<label>:<id>` are opaque credential tokens provided by human operators.\nNEVER modify, decode, split, or log these values. Pass them exactly as received into tool arguments.\nThey are automatically resolved at execution time.\n\n## Response Format\n\nReturn ONLY a JSON object (no markdown fences):\n{\n  \"title\": \"Short headline (under 60 chars)\",\n  \"summary\": \"1-3 sentence overview of what was accomplished\",\n  \"result\": { ... },\n  \"compilation_candidate\": false,\n  \"tool_calls_made\": 0\n}";
+export declare const WORKFLOW_MATCH_PROMPT = "You are a strict workflow matching evaluator. Given a user request and a list of compiled workflows, determine if any workflow is a PRECISE match for the request.\n\nA workflow matches ONLY if:\n1. **Scope alignment**: The workflow does approximately what the user asked \u2014 not significantly more, not significantly less.\n2. **Intent alignment**: The workflow's purpose (description, original prompt) closely matches the user's goal \u2014 not just the same topic or domain.\n3. **Input compatibility**: The user's request provides enough information to populate the workflow's required inputs.\n\nBe CONSERVATIVE. If the user's request is a subset or superset of what the workflow does, it is NOT a match. When in doubt, return match: false \u2014 the system will fall back to a dynamic execution that handles the exact request.\n\nRespond with ONLY a JSON object:\n{\n  \"match\": true or false,\n  \"workflow_name\": \"name-of-best-match\" or null,\n  \"confidence\": 0.0 to 1.0,\n  \"reasoning\": \"Brief explanation of why this is or isn't a scope match\"\n}";
+export declare const EXTRACT_INPUTS_PROMPT = "You are an input extraction engine. Given a user's natural-language request and a workflow's input schema, extract the structured inputs the workflow needs.\n\nRules:\n- Extract ONLY values explicitly stated or clearly implied in the user's request.\n- Match each extracted value to the correct field in the input schema, paying attention to the field's **description** \u2014 not just its name.\n- Use the field descriptions to understand what each input represents and extract the semantically correct value from the request.\n- If a required field cannot be populated from the request, set \"_extraction_failed\" to true.\n- Do NOT invent, guess, or use default values for fields the user didn't mention.\n- Return ONLY a JSON object whose keys match the input schema's property names.\n- Include \"_extraction_failed\": true if any required field is missing, or \"_extraction_failed\": false if all required fields are satisfied.";
+export declare const ROUNDS_EXHAUSTED_DIAGNOSTIC_PROMPT = "You have run out of allowed tool rounds. Summarize:\n(1) what you accomplished,\n(2) what you were unable to complete, and\n(3) what steps remain.\n\nReturn a JSON object with keys:\n- title: short title for the execution\n- summary: brief narrative of what happened\n- result: partial data collected (if any), or null\n- diagnosis: string explaining what went wrong and what remains to be done";

package/build/system/workflows/mcp-query/prompts.js

@@ -0,0 +1,101 @@
+"use strict";
+// ── MCP Query prompts ───────────────────────────────────────────────────────
+// All LLM prompt text for the mcp-query workflow lives here.
+// Keep prompts generic — never reference specific tool names or selectors.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUNDS_EXHAUSTED_DIAGNOSTIC_PROMPT = exports.EXTRACT_INPUTS_PROMPT = exports.WORKFLOW_MATCH_PROMPT = exports.MCP_QUERY_SYSTEM_PROMPT = void 0;
+// ── Agentic loop system prompt ──────────────────────────────────────────────
+exports.MCP_QUERY_SYSTEM_PROMPT = `\
+You are a general-purpose AI assistant for Long Tail — a durable workflow system with MCP tool integration.
+
+You have access to **MCP tools** from registered servers. Your job is to fulfill the user's request using these tools.
+
+## Tool Selection — CRITICAL, READ CAREFULLY:
+- A "Tool Selection Strategy" section appears before the tool inventory. It tells you EXACTLY which tools to use and which to NEVER use. **Follow it strictly — violations cause failures.**
+- **Minimize total tool calls.** Before making a call, ask: "Is there a single tool that does all of this?" If yes, use it. If you find yourself chaining 3+ calls to accomplish what one composite tool could do, stop and switch.
+- **For multi-item tasks, look for batch tools.** If you need to perform the same operation on many items, check if a tool accepts a list/array input. One batch call is always better than N individual calls.
+
+**Principles for dynamic execution:**
+- **Chain tools logically.** If a task requires multiple steps, chain tool calls in the natural order. Pass outputs from one step as inputs to the next.
+- **Handle sessions and handles.** Some tools return session identifiers (page_id, _handle, session_id). Pass these to ALL subsequent calls that need to operate within that session. Session handles maintain authentication and state — losing them means starting over. NEVER open a new session when you already have one.
+- **Discover before acting.** When you need to understand structure, content, or available options, use discovery/extraction tools first. Then pass discovered values to subsequent tools. NEVER guess input values.
+- **Iterate when needed.** If you need to perform the same action on multiple items and no batch tool exists, call the tool for each item. The system will detect this pattern when compiling the workflow later.
+- **Use credentials from the prompt.** The user provides credentials in their request. NEVER persist credentials to the filesystem.
+- **Trust tool defaults.** Tools define default values for optional parameters. Only override defaults when the user provides a specific value or you've discovered the correct one via a prior tool call.
+- **When a tool call fails, adapt.** Use discovery tools to learn the correct structure, then retry with discovered values. Don't retry with the same wrong parameters.
+- **Fulfill the complete request.** If the user asks to process N items, process all N items. Don't stop early or summarize partway through.
+- **Budget your tool rounds.** You have a limited number of tool rounds. A budget indicator (e.g., "[Rounds: 3 remaining]") may appear in the conversation. When you see 3 or fewer rounds remaining, wrap up: consolidate partial results, write any pending output, and return your final response. Prefer batch/composite tools to conserve rounds.
+
+### 3. Mark for Compilation
+If you completed a multi-step task that seems reusable, set \`compilation_candidate: true\` in your response. The execution trace can then be compiled into a deterministic YAML workflow — turning this dynamic run into a fast, repeatable tool for next time.
+
+## Escalation
+
+Escalate only when truly stuck — retry with alternatives first.
+
+- **For input you need before continuing** (credentials, approvals, missing data):
+  Use escalate_and_wait. Specify a form_schema describing what fields you need. The workflow pauses until the human responds — no polling needed.
+- **For fire-and-forget notifications** (advisory, FYI):
+  Use escalate_to_human.
+- **Escalate to 'engineer' role** — when you need human judgment or infrastructure help
+- **Escalate to 'mcp' role** — when you need tool capabilities not in the current inventory
+
+When escalating, provide specific context: what you tried, what failed, what you need.
+
+## Credential Tokens
+Values formatted as \`eph:v1:<label>:<id>\` are opaque credential tokens provided by human operators.
+NEVER modify, decode, split, or log these values. Pass them exactly as received into tool arguments.
+They are automatically resolved at execution time.
+
+## Response Format
+
+Return ONLY a JSON object (no markdown fences):
+{
+  "title": "Short headline (under 60 chars)",
+  "summary": "1-3 sentence overview of what was accomplished",
+  "result": { ... },
+  "compilation_candidate": false,
+  "tool_calls_made": 0
+}`;
+// ── Workflow matching prompt (Phase 2) ──────────────────────────────────────
+exports.WORKFLOW_MATCH_PROMPT = `\
+You are a strict workflow matching evaluator. Given a user request and a list of compiled workflows, determine if any workflow is a PRECISE match for the request.
+
+A workflow matches ONLY if:
+1. **Scope alignment**: The workflow does approximately what the user asked — not significantly more, not significantly less.
+2. **Intent alignment**: The workflow's purpose (description, original prompt) closely matches the user's goal — not just the same topic or domain.
+3. **Input compatibility**: The user's request provides enough information to populate the workflow's required inputs.
+
+Be CONSERVATIVE. If the user's request is a subset or superset of what the workflow does, it is NOT a match. When in doubt, return match: false — the system will fall back to a dynamic execution that handles the exact request.
+
+Respond with ONLY a JSON object:
+{
+  "match": true or false,
+  "workflow_name": "name-of-best-match" or null,
+  "confidence": 0.0 to 1.0,
+  "reasoning": "Brief explanation of why this is or isn't a scope match"
+}`;
+// ── Input extraction prompt (Phase 2b) ──────────────────────────────────────
+exports.EXTRACT_INPUTS_PROMPT = `\
+You are an input extraction engine. Given a user's natural-language request and a workflow's input schema, extract the structured inputs the workflow needs.
+
+Rules:
+- Extract ONLY values explicitly stated or clearly implied in the user's request.
+- Match each extracted value to the correct field in the input schema, paying attention to the field's **description** — not just its name.
+- Use the field descriptions to understand what each input represents and extract the semantically correct value from the request.
+- If a required field cannot be populated from the request, set "_extraction_failed" to true.
+- Do NOT invent, guess, or use default values for fields the user didn't mention.
+- Return ONLY a JSON object whose keys match the input schema's property names.
+- Include "_extraction_failed": true if any required field is missing, or "_extraction_failed": false if all required fields are satisfied.`;
+// ── Rounds-exhausted diagnostic prompt ──────────────────────────────────────
+exports.ROUNDS_EXHAUSTED_DIAGNOSTIC_PROMPT = `\
+You have run out of allowed tool rounds. Summarize:
+(1) what you accomplished,
+(2) what you were unable to complete, and
+(3) what steps remain.
+
+Return a JSON object with keys:
+- title: short title for the execution
+- summary: brief narrative of what happened
+- result: partial data collected (if any), or null
+- diagnosis: string explaining what went wrong and what remains to be done`;

package/build/system/workflows/mcp-query/strategy-advisors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Strategy advisors — inspect loaded tool inventory and emit concrete,
+ * tool-name-specific prompt sections so the LLM makes optimal tool choices.
+ *
+ * No tool names are hardcoded in the generic system prompt. Instead,
+ * advisors run at tool-loading time and produce guidance referencing
+ * the actual qualified names the LLM will see.
+ */
+import type { ServerInfo } from './types';
+/**
+ * Run all strategy advisors against the loaded server inventory
+ * and return a combined strategy section for the LLM prompt.
+ */
+export declare function generateStrategySection(servers: ServerInfo[]): string;

package/build/system/workflows/mcp-query/strategy-advisors.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Strategy advisors — inspect loaded tool inventory and emit concrete,
+ * tool-name-specific prompt sections so the LLM makes optimal tool choices.
+ *
+ * No tool names are hardcoded in the generic system prompt. Instead,
+ * advisors run at tool-loading time and produce guidance referencing
+ * the actual qualified names the LLM will see.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateStrategySection = generateStrategySection;
+// ── Advisors ────────────────────────────────────────────────────────────────
+/**
+ * Detects overlapping server categories (e.g., two browser-automation servers)
+ * and emits concrete "USE THIS / AVOID THAT" guidance with actual tool names.
+ */
+function overlappingCategoryAdvisor(servers) {
+    // Group by category
+    const byCategory = new Map();
+    for (const s of servers) {
+        const category = s.metadata?.category;
+        if (!category)
+            continue;
+        const group = byCategory.get(category) || [];
+        group.push(s);
+        byCategory.set(category, group);
+    }
+    const sections = [];
+    for (const [category, group] of byCategory) {
+        if (group.length < 2)
+            continue;
+        // Determine high vs low level: explicit metadata.level, then tool-count heuristic
+        let highLevel = null;
+        let lowLevel = null;
+        const withLevel = group.filter(s => s.metadata?.level);
+        if (withLevel.length >= 2) {
+            highLevel = withLevel.find(s => s.metadata?.level === 'high') || null;
+            lowLevel = withLevel.find(s => s.metadata?.level === 'low') || null;
+        }
+        if (!highLevel || !lowLevel) {
+            // Heuristic: fewer tools = higher-level (composite)
+            const sorted = [...group].sort((a, b) => a.toolCount - b.toolCount);
+            highLevel = highLevel || sorted[0];
+            lowLevel = lowLevel || sorted[sorted.length - 1];
+        }
+        if (highLevel === lowLevel)
+            continue;
+        const categoryLabel = category.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+        const hiSlug = highLevel.slug;
+        const loSlug = lowLevel.slug;
+        const hiTools = highLevel.toolNames.map(t => `${hiSlug}__${t}`);
+        const loTools = lowLevel.toolNames.map(t => `${loSlug}__${t}`);
+        sections.push(`## ${categoryLabel} — Tool Selection (CRITICAL)
+
+You have TWO ${categoryLabel.toLowerCase()} servers. One is high-level (composite), the other low-level (primitives).
+
+**USE: ${highLevel.name}** (${highLevel.toolCount} composite tools)
+Tools: ${hiTools.join(', ')}
+${highLevel.description ? `> ${highLevel.description}` : ''}
+Each tool handles a complete workflow in ONE call. Session management is automatic.
+
+**AVOID: ${lowLevel.name}** (${lowLevel.toolCount} primitive tools)
+Tools: ${loTools.join(', ')}
+These are individual primitives requiring manual session management. Using these when the composite tools can do the job causes 5-10x more calls and session failures.
+
+**RULE: ALWAYS use ${hiSlug}__* tools. NEVER use ${loSlug}__* tools unless no ${hiSlug}__* tool can accomplish the task.**`);
+    }
+    return sections.join('\n\n');
+}
+/**
+ * Detects the human-queue server and emits guidance to use escalate_and_wait
+ * instead of escalate_to_human + check_resolution polling.
+ */
+function humanQueueAdvisor(servers) {
+    const hq = servers.find((s) => s.toolNames.includes('escalate_and_wait') && s.toolNames.includes('escalate_to_human'));
+    if (!hq)
+        return '';
+    const slug = hq.slug;
+    return (`## Human Queue — Tool Selection
+When you need input from a human before continuing (credentials, approval, data):
+USE: ${slug}__escalate_and_wait — pauses the workflow until the human responds. Specify a form_schema describing what fields you need (use format:"password" for sensitive values).
+AVOID: ${slug}__escalate_to_human + ${slug}__check_resolution polling loop — burns tool rounds and may exhaust your budget.`);
+}
+/**
+ * Scans for batch-capable tools (accepting array inputs) and notes them
+ * as preferred over repeated single-item calls.
+ */
+function batchPreferenceAdvisor(servers) {
+    // This advisor is lightweight — it just identifies tools with array params
+    // from their names/descriptions. The overlapping category advisor handles
+    // the primary use case. This catches additional patterns.
+    return '';
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+const advisors = [
+    overlappingCategoryAdvisor,
+    humanQueueAdvisor,
+    batchPreferenceAdvisor,
+];
+/**
+ * Run all strategy advisors against the loaded server inventory
+ * and return a combined strategy section for the LLM prompt.
+ */
+function generateStrategySection(servers) {
+    const sections = advisors
+        .map(advisor => advisor(servers))
+        .filter(s => s.length > 0);
+    return sections.join('\n\n');
+}

package/build/system/workflows/mcp-query/types.d.ts

@@ -0,0 +1,10 @@
+/** Type definitions for the mcp-query workflow. */
+export interface ServerInfo {
+    name: string;
+    description: string | null;
+    tags: string[];
+    metadata: Record<string, any> | null;
+    toolNames: string[];
+    toolCount: number;
+    slug: string;
+}

package/build/system/workflows/mcp-query/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/** Type definitions for the mcp-query workflow. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/system/workflows/mcp-query-router/activities.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Router activities — discovery, matching, and input extraction.
+ * These run in the router workflow, NOT in the dynamic mcpQuery workflow,
+ * so they don't pollute the execution trace that gets compiled to YAML.
+ */
+export { findCompiledWorkflows, evaluateWorkflowMatch, extractWorkflowInputs, } from '../mcp-query/activities';

package/build/system/workflows/mcp-query-router/activities.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractWorkflowInputs = exports.evaluateWorkflowMatch = exports.findCompiledWorkflows = void 0;
+/**
+ * Router activities — discovery, matching, and input extraction.
+ * These run in the router workflow, NOT in the dynamic mcpQuery workflow,
+ * so they don't pollute the execution trace that gets compiled to YAML.
+ */
+var activities_1 = require("../mcp-query/activities");
+Object.defineProperty(exports, "findCompiledWorkflows", { enumerable: true, get: function () { return activities_1.findCompiledWorkflows; } });
+Object.defineProperty(exports, "evaluateWorkflowMatch", { enumerable: true, get: function () { return activities_1.evaluateWorkflowMatch; } });
+Object.defineProperty(exports, "extractWorkflowInputs", { enumerable: true, get: function () { return activities_1.extractWorkflowInputs; } });

package/build/system/workflows/mcp-query-router/index.d.ts

@@ -0,0 +1,13 @@
+import type { LTEnvelope, LTReturn, LTEscalation } from '../../../types';
+/**
+ * MCP Query Router (orchestrator/container).
+ *
+ * Entry point for all MCP queries. Determines whether a compiled
+ * deterministic YAML workflow can handle the request or whether
+ * dynamic MCP orchestration is needed.
+ *
+ * Phase 1: FTS + tag discovery of compiled workflows
+ * Phase 2: LLM-as-judge matching + input extraction
+ * Route: mcpDeterministic (compiled match) OR mcpQuery (dynamic)
+ */
+export declare function mcpQueryRouter(envelope: LTEnvelope): Promise<LTReturn | LTEscalation>;

package/build/system/workflows/mcp-query-router/index.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpQueryRouter = mcpQueryRouter;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const orchestrator_1 = require("../../../services/orchestrator");
+const activities = __importStar(require("./activities"));
+const { findCompiledWorkflows, evaluateWorkflowMatch, extractWorkflowInputs, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+    retryPolicy: {
+        maximumAttempts: 3,
+        backoffCoefficient: 2,
+        maximumInterval: '10 seconds',
+    },
+});
+/**
+ * MCP Query Router (orchestrator/container).
+ *
+ * Entry point for all MCP queries. Determines whether a compiled
+ * deterministic YAML workflow can handle the request or whether
+ * dynamic MCP orchestration is needed.
+ *
+ * Phase 1: FTS + tag discovery of compiled workflows
+ * Phase 2: LLM-as-judge matching + input extraction
+ * Route: mcpDeterministic (compiled match) OR mcpQuery (dynamic)
+ */
+async function mcpQueryRouter(envelope) {
+    const prompt = (envelope.data?.prompt || envelope.data?.question);
+    const tags = envelope.data?.tags;
+    if (!prompt) {
+        return {
+            type: 'return',
+            data: {
+                title: 'No prompt provided',
+                summary: 'Please provide a prompt describing what you want to accomplish.',
+                result: null,
+                tool_calls_made: 0,
+            },
+        };
+    }
+    // Phase 1: Ranked discovery of compiled YAML workflows
+    const compiled = await findCompiledWorkflows(prompt);
+    // Phase 2: LLM-as-judge — does a compiled workflow match?
+    if (compiled.candidates.length > 0) {
+        const match = await evaluateWorkflowMatch(prompt, compiled.candidates);
+        if (match.matched && match.workflowName) {
+            // Phase 2b: Extract structured inputs from the prompt
+            const candidate = compiled.candidates.find((c) => c.name === match.workflowName);
+            const inputSchema = candidate?.input_schema || { type: 'object', properties: {} };
+            const extraction = await extractWorkflowInputs(prompt, inputSchema, match.workflowName);
+            if (extraction.extracted && extraction.inputs) {
+                // Route to mcpDeterministic — compiled workflow handles this
+                return await (0, orchestrator_1.executeLT)({
+                    workflowName: 'mcpDeterministic',
+                    args: [{
+                            data: {
+                                workflowName: match.workflowName,
+                                inputs: extraction.inputs,
+                                confidence: match.confidence,
+                            },
+                            metadata: envelope.metadata,
+                        }],
+                    taskQueue: 'long-tail-system',
+                });
+            }
+            // Input extraction failed — fall through to dynamic
+        }
+    }
+    // No compiled match — route to mcpQuery for dynamic MCP orchestration
+    return await (0, orchestrator_1.executeLT)({
+        workflowName: 'mcpQuery',
+        args: [{ data: { prompt, tags }, metadata: envelope.metadata }],
+        taskQueue: 'long-tail-system',
+    });
+}

package/build/system/workflows/mcp-query-router/prompts.d.ts

@@ -0,0 +1 @@
+export { WORKFLOW_MATCH_PROMPT, EXTRACT_INPUTS_PROMPT } from '../mcp-query/prompts';

package/build/system/workflows/mcp-query-router/prompts.js

@@ -0,0 +1,8 @@
+"use strict";
+// ── MCP Query Router prompts ────────────────────────────────────────────────
+// Prompts for the matching/extraction phase of the router.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTRACT_INPUTS_PROMPT = exports.WORKFLOW_MATCH_PROMPT = void 0;
+var prompts_1 = require("../mcp-query/prompts");
+Object.defineProperty(exports, "WORKFLOW_MATCH_PROMPT", { enumerable: true, get: function () { return prompts_1.WORKFLOW_MATCH_PROMPT; } });
+Object.defineProperty(exports, "EXTRACT_INPUTS_PROMPT", { enumerable: true, get: function () { return prompts_1.EXTRACT_INPUTS_PROMPT; } });