@hotmeshio/long-tail 0.1.4 → 0.1.6

package/build/system/workflows/shared/discovery.js

@@ -0,0 +1,175 @@
+"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.findCompiledWorkflows = findCompiledWorkflows;
+exports.evaluateWorkflowMatch = evaluateWorkflowMatch;
+exports.extractWorkflowInputs = extractWorkflowInputs;
+const llm_1 = require("../../../services/llm");
+const defaults_1 = require("../../../modules/defaults");
+const logger_1 = require("../../../lib/logger");
+const yamlDb = __importStar(require("../../../services/yaml-workflow/db"));
+const prompts_1 = require("./prompts");
+/**
+ * Ranked discovery of compiled YAML workflows via FTS + tag overlap.
+ *
+ * Callers pass their own module-level caches so each pipeline keeps
+ * isolated cache instances.
+ */
+async function findCompiledWorkflows(prompt, caches, logPrefix = 'shared') {
+    const keywords = prompt
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !defaults_1.STOP_WORDS.has(w));
+    logger_1.loggerRegistry.debug(`[${logPrefix}:findCompiledWorkflows] keywords: [${keywords.join(',')}]`);
+    let workflows;
+    try {
+        workflows = await yamlDb.discoverWorkflows(prompt, keywords, undefined, 5);
+        logger_1.loggerRegistry.info(`[${logPrefix}:findCompiledWorkflows] ${workflows.length} candidate(s) found`);
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[${logPrefix}:findCompiledWorkflows] discovery failed: ${err.message}`);
+        return { inventory: '', toolIds: [], candidates: [] };
+    }
+    if (workflows.length === 0) {
+        return { inventory: '', toolIds: [], candidates: [] };
+    }
+    const toolIds = [];
+    const inventoryLines = [];
+    const candidates = [];
+    for (const wf of workflows) {
+        const qualifiedName = `yaml__${wf.name.replace(/[^a-zA-Z0-9]/g, '_')}`;
+        caches.yamlWorkflowMap.set(qualifiedName, wf.name);
+        caches.toolDefCache.set(qualifiedName, {
+            type: 'function',
+            function: {
+                name: qualifiedName,
+                description: `[COMPILED WORKFLOW] ${wf.description || wf.name} — deterministic, no LLM needed. ` +
+                    `Tags: ${wf.tags.join(', ')}`,
+                parameters: (wf.input_schema || { type: 'object', properties: {} }),
+            },
+        });
+        toolIds.push(qualifiedName);
+        const activityCount = wf.activity_manifest.filter((a) => a.type === 'worker').length;
+        inventoryLines.push(`★ ${wf.name} [compiled, ${activityCount} steps, tags: ${wf.tags.join(', ')}]: ${wf.description || 'deterministic workflow'}`);
+        candidates.push({
+            name: wf.name,
+            description: wf.description,
+            original_prompt: wf.original_prompt,
+            category: wf.category,
+            tags: wf.tags,
+            input_schema: wf.input_schema,
+            tool_names: wf.activity_manifest
+                .filter((a) => a.type === 'worker' && a.mcp_tool_name)
+                .map((a) => a.mcp_tool_name),
+            fts_rank: wf.fts_rank || 0,
+        });
+    }
+    return { inventory: inventoryLines.join('\n'), toolIds, candidates };
+}
+/**
+ * LLM-as-judge: does a compiled workflow match the user's intent?
+ * One cheap call (secondary model, ~200 tokens) to potentially skip
+ * the entire agentic loop.
+ */
+async function evaluateWorkflowMatch(prompt, candidates, logPrefix = 'shared') {
+    logger_1.loggerRegistry.debug(`[${logPrefix}:evaluateWorkflowMatch] ${candidates.length} candidate(s)`);
+    if (candidates.length === 0) {
+        return { matched: false, workflowName: null, confidence: 0 };
+    }
+    const candidateText = candidates.map((c, i) => `${i + 1}. **${c.name}** (category: ${c.category || 'general'})\n` +
+        `   Description: ${c.description || 'N/A'}\n` +
+        `   Original prompt: "${c.original_prompt || 'N/A'}"\n` +
+        `   Tools: ${c.tool_names.join(', ')}\n` +
+        `   Input: ${JSON.stringify(c.input_schema).slice(0, 300)}`).join('\n\n');
+    try {
+        const response = await (0, llm_1.callLLM)({
+            model: defaults_1.LLM_MODEL_SECONDARY,
+            max_tokens: 200,
+            temperature: 0,
+            messages: [
+                { role: 'system', content: prompts_1.WORKFLOW_MATCH_PROMPT },
+                { role: 'user', content: `## User Request\n${prompt}\n\n## Candidate Workflows\n${candidateText}` },
+            ],
+        });
+        const raw = response.content || '{}';
+        const cleaned = raw.replace(/^```(?:json)?\s*/m, '').replace(/\s*```$/m, '').trim();
+        const result = JSON.parse(cleaned);
+        if (result.match && result.confidence >= 0.7) {
+            logger_1.loggerRegistry.info(`[${logPrefix}:evaluateWorkflowMatch] MATCHED: ${result.workflow_name} (confidence: ${result.confidence})`);
+            return { matched: true, workflowName: result.workflow_name, confidence: result.confidence };
+        }
+        logger_1.loggerRegistry.info(`[${logPrefix}:evaluateWorkflowMatch] no match (confidence: ${result.confidence || 0})`);
+        return { matched: false, workflowName: null, confidence: result.confidence || 0 };
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[${logPrefix}:evaluateWorkflowMatch] error: ${err.message}`);
+        return { matched: false, workflowName: null, confidence: 0 };
+    }
+}
+/**
+ * Extract structured inputs from the user's prompt using the matched
+ * workflow's input_schema. Acts as a second confirmation gate — if the
+ * LLM can't map the prompt to the schema, the match is rejected.
+ */
+async function extractWorkflowInputs(prompt, inputSchema, workflowName) {
+    try {
+        const response = await (0, llm_1.callLLM)({
+            model: defaults_1.LLM_MODEL_SECONDARY,
+            max_tokens: 500,
+            temperature: 0,
+            messages: [
+                { role: 'system', content: prompts_1.EXTRACT_INPUTS_PROMPT },
+                {
+                    role: 'user',
+                    content: `## User Request\n${prompt}\n\n` +
+                        `## Workflow: ${workflowName}\n` +
+                        `## Input Schema\n${JSON.stringify(inputSchema, null, 2)}`,
+                },
+            ],
+        });
+        const raw = response.content || '{}';
+        const cleaned = raw.replace(/^```(?:json)?\s*/m, '').replace(/\s*```$/m, '').trim();
+        const result = JSON.parse(cleaned);
+        if (result._extraction_failed) {
+            return { inputs: null, extracted: false };
+        }
+        delete result._extraction_failed;
+        return { inputs: result, extracted: true };
+    }
+    catch {
+        return { inputs: null, extracted: false };
+    }
+}

package/build/system/workflows/shared/index.d.ts

@@ -0,0 +1,7 @@
+export { callWorkflowLLM } from './llm-caller';
+export { findCompiledWorkflows, evaluateWorkflowMatch, extractWorkflowInputs } from './discovery';
+export { loadToolsFromServers } from './tool-loader';
+export { callTool } from './tool-executor';
+export { generateStrategySection } from './strategy-advisors';
+export { WORKFLOW_MATCH_PROMPT, EXTRACT_INPUTS_PROMPT } from './prompts';
+export type { ServerInfo } from './types';

package/build/system/workflows/shared/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTRACT_INPUTS_PROMPT = exports.WORKFLOW_MATCH_PROMPT = exports.generateStrategySection = exports.callTool = exports.loadToolsFromServers = exports.extractWorkflowInputs = exports.evaluateWorkflowMatch = exports.findCompiledWorkflows = exports.callWorkflowLLM = void 0;
+var llm_caller_1 = require("./llm-caller");
+Object.defineProperty(exports, "callWorkflowLLM", { enumerable: true, get: function () { return llm_caller_1.callWorkflowLLM; } });
+var discovery_1 = require("./discovery");
+Object.defineProperty(exports, "findCompiledWorkflows", { enumerable: true, get: function () { return discovery_1.findCompiledWorkflows; } });
+Object.defineProperty(exports, "evaluateWorkflowMatch", { enumerable: true, get: function () { return discovery_1.evaluateWorkflowMatch; } });
+Object.defineProperty(exports, "extractWorkflowInputs", { enumerable: true, get: function () { return discovery_1.extractWorkflowInputs; } });
+var tool_loader_1 = require("./tool-loader");
+Object.defineProperty(exports, "loadToolsFromServers", { enumerable: true, get: function () { return tool_loader_1.loadToolsFromServers; } });
+var tool_executor_1 = require("./tool-executor");
+Object.defineProperty(exports, "callTool", { enumerable: true, get: function () { return tool_executor_1.callTool; } });
+var strategy_advisors_1 = require("./strategy-advisors");
+Object.defineProperty(exports, "generateStrategySection", { enumerable: true, get: function () { return strategy_advisors_1.generateStrategySection; } });
+var prompts_1 = require("./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; } });

package/build/system/workflows/shared/llm-caller.d.ts

@@ -0,0 +1,8 @@
+import { type ToolDefinition, type LLMResponse } from '../../../services/llm';
+/**
+ * Call the LLM with messages and optional tool IDs.
+ *
+ * Tool IDs are resolved from the caller's module-level toolDefCache so
+ * that only lightweight string arrays flow through the durable pipe.
+ */
+export declare function callWorkflowLLM(messages: any[], toolIds: string[] | undefined, toolDefCache: Map<string, ToolDefinition>, logPrefix: string): Promise<LLMResponse>;

package/build/system/workflows/shared/llm-caller.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callWorkflowLLM = callWorkflowLLM;
+const llm_1 = require("../../../services/llm");
+const defaults_1 = require("../../../modules/defaults");
+const logger_1 = require("../../../lib/logger");
+/**
+ * Call the LLM with messages and optional tool IDs.
+ *
+ * Tool IDs are resolved from the caller's module-level toolDefCache so
+ * that only lightweight string arrays flow through the durable pipe.
+ */
+async function callWorkflowLLM(messages, toolIds, toolDefCache, logPrefix) {
+    let tools;
+    if (toolIds?.length) {
+        tools = toolIds
+            .map((id) => toolDefCache.get(id))
+            .filter((t) => !!t);
+    }
+    const t0 = Date.now();
+    const response = await (0, llm_1.callLLM)({
+        model: defaults_1.LLM_MODEL_PRIMARY,
+        messages,
+        temperature: 0,
+        ...(tools?.length ? { tools } : {}),
+        ...(!tools?.length ? { max_tokens: defaults_1.LLM_MAX_TOKENS_DEFAULT } : {}),
+    });
+    const usage = response.usage;
+    logger_1.loggerRegistry.info(`[${logPrefix}:callLLM] ${Date.now() - t0}ms | in=${usage?.prompt_tokens} out=${usage?.completion_tokens} total=${usage?.total_tokens} | tool_calls=${response.tool_calls?.length || 0}`);
+    return response;
+}

package/build/system/workflows/shared/prompts.d.ts

@@ -0,0 +1,2 @@
+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.";

package/build/system/workflows/shared/prompts.js

@@ -0,0 +1,32 @@
+"use strict";
+// ── Shared prompts used by both mcpQuery and mcpTriage discovery pipelines ──
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXTRACT_INPUTS_PROMPT = exports.WORKFLOW_MATCH_PROMPT = void 0;
+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"
+}`;
+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.`;

package/build/system/workflows/shared/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/shared/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/shared/tool-executor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Call any tool by its qualified name — handles both YAML workflows
+ * (yaml__* prefix) and raw MCP tools (server_slug__tool_name).
+ *
+ * Callers pass their own module-level caches so each pipeline
+ * (mcpQuery, mcpTriage) keeps its own isolated cache instances.
+ */
+export declare function callTool(qualifiedName: string, args: Record<string, any>, caches: {
+    toolServerMap: Map<string, string>;
+    yamlWorkflowMap: Map<string, string>;
+}): Promise<any>;

package/build/system/workflows/shared/tool-executor.js

@@ -0,0 +1,111 @@
+"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.callTool = callTool;
+const context_1 = require("../../../services/iam/context");
+const ephemeral_1 = require("../../../services/iam/ephemeral");
+const mcpClient = __importStar(require("../../../services/mcp/client"));
+const mcpDbService = __importStar(require("../../../services/mcp/db"));
+const yamlDb = __importStar(require("../../../services/yaml-workflow/db"));
+const yamlDeployer = __importStar(require("../../../services/yaml-workflow/deployer"));
+/**
+ * Call any tool by its qualified name — handles both YAML workflows
+ * (yaml__* prefix) and raw MCP tools (server_slug__tool_name).
+ *
+ * Callers pass their own module-level caches so each pipeline
+ * (mcpQuery, mcpTriage) keeps its own isolated cache instances.
+ */
+async function callTool(qualifiedName, args, caches) {
+    // Check if this is a compiled YAML workflow
+    const yamlWorkflowName = caches.yamlWorkflowMap.get(qualifiedName);
+    if (yamlWorkflowName) {
+        try {
+            const wf = await yamlDb.getYamlWorkflowByName(yamlWorkflowName);
+            if (!wf || wf.status !== 'active') {
+                return { error: `Compiled workflow "${yamlWorkflowName}" is not active` };
+            }
+            const toolCtx = (0, context_1.getToolContext)();
+            const scopedArgs = toolCtx?.principal.id
+                ? {
+                    ...args,
+                    _scope: {
+                        principal: toolCtx.principal,
+                        ...(toolCtx.initiatingPrincipal ? { initiatingPrincipal: toolCtx.initiatingPrincipal } : {}),
+                        scopes: toolCtx.credentials.scopes,
+                    },
+                }
+                : args;
+            const { job_id, result } = await yamlDeployer.invokeYamlWorkflowSync(wf.app_id, wf.graph_topic, scopedArgs, undefined, wf.graph_topic);
+            return { job_id, workflow: yamlWorkflowName, status: 'completed', result };
+        }
+        catch (err) {
+            return { error: err.message, tool: qualifiedName, args };
+        }
+    }
+    // Exchange ephemeral credential tokens right before the MCP call
+    args = await (0, ephemeral_1.exchangeTokensInArgs)(args);
+    // Standard MCP tool routing
+    const serverName = caches.toolServerMap.get(qualifiedName);
+    const separatorIdx = qualifiedName.indexOf('__');
+    const toolName = separatorIdx >= 0
+        ? qualifiedName.slice(separatorIdx + 2)
+        : qualifiedName;
+    const toolCtx = (0, context_1.getToolContext)();
+    const authContext = toolCtx?.principal.id
+        ? { userId: toolCtx.principal.id, delegationToken: toolCtx.credentials.delegationToken }
+        : undefined;
+    if (serverName) {
+        try {
+            return await mcpClient.callServerTool(serverName, toolName, args, authContext);
+        }
+        catch (err) {
+            return { error: err.message, tool: qualifiedName, args };
+        }
+    }
+    // Fallback: scan all connected servers
+    const { servers } = await mcpDbService.listMcpServers({ limit: 100 });
+    for (const server of servers) {
+        const manifest = server.tool_manifest || [];
+        if (manifest.some((t) => t.name === toolName)) {
+            try {
+                return await mcpClient.callServerTool(server.name, toolName, args, authContext);
+            }
+            catch (err) {
+                return { error: err.message, tool: qualifiedName, args };
+            }
+        }
+    }
+    return { error: `Unknown tool: ${qualifiedName} (no server found)`, tool: qualifiedName };
+}

package/build/system/workflows/shared/tool-loader.d.ts

@@ -0,0 +1,19 @@
+import type { ToolDefinition } from '../../../services/llm';
+/**
+ * Discover MCP servers, cache tool definitions, and return a lightweight
+ * summary for the durable pipe.
+ *
+ * Callers pass their own module-level caches so each pipeline keeps
+ * isolated cache instances. Optional `baseTags` are merged before querying.
+ */
+export declare function loadToolsFromServers(tags: string[] | undefined, caches: {
+    toolServerMap: Map<string, string>;
+    toolDefCache: Map<string, ToolDefinition>;
+}, opts?: {
+    baseTags?: string[];
+    logPrefix?: string;
+}): Promise<{
+    toolIds: string[];
+    inventory: string;
+    strategy: string;
+}>;

package/build/system/workflows/shared/tool-loader.js

@@ -0,0 +1,97 @@
+"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.loadToolsFromServers = loadToolsFromServers;
+const logger_1 = require("../../../lib/logger");
+const mcpDbService = __importStar(require("../../../services/mcp/db"));
+const strategy_advisors_1 = require("./strategy-advisors");
+/**
+ * Discover MCP servers, cache tool definitions, and return a lightweight
+ * summary for the durable pipe.
+ *
+ * Callers pass their own module-level caches so each pipeline keeps
+ * isolated cache instances. Optional `baseTags` are merged before querying.
+ */
+async function loadToolsFromServers(tags, caches, opts) {
+    const prefix = opts?.logPrefix || 'shared';
+    let servers;
+    if (tags?.length || opts?.baseTags?.length) {
+        const combinedTags = [...new Set([...(opts?.baseTags || []), ...(tags || [])])];
+        servers = await mcpDbService.findServersByTags(combinedTags, 'any');
+    }
+    else {
+        const result = await mcpDbService.listMcpServers({ limit: 100 });
+        servers = result.servers;
+    }
+    const toolIds = [];
+    const inventoryLines = [];
+    const serverInfos = [];
+    for (const server of servers) {
+        const manifest = server.tool_manifest || [];
+        const slug = server.name.replace(/[^a-zA-Z0-9]/g, '_');
+        const serverTags = server.tags?.length ? server.tags.join(', ') : 'general';
+        const toolNames = [];
+        for (const t of manifest) {
+            const qualifiedName = `${slug}__${t.name}`;
+            caches.toolServerMap.set(qualifiedName, server.name);
+            caches.toolDefCache.set(qualifiedName, {
+                type: 'function',
+                function: {
+                    name: qualifiedName,
+                    description: `[${server.name}] ${t.description || ''}`,
+                    parameters: (t.inputSchema || { type: 'object', properties: {} }),
+                },
+            });
+            toolIds.push(qualifiedName);
+            toolNames.push(t.name);
+        }
+        inventoryLines.push(`• ${server.name} [${serverTags}] (${manifest.length} tools): ${toolNames.join(', ')}`);
+        if (server.compile_hints) {
+            inventoryLines.push(`  Hints: ${server.compile_hints}`);
+        }
+        serverInfos.push({
+            name: server.name,
+            description: server.description || null,
+            tags: server.tags || [],
+            metadata: server.metadata || null,
+            toolNames,
+            toolCount: manifest.length,
+            slug,
+        });
+    }
+    const strategy = (0, strategy_advisors_1.generateStrategySection)(serverInfos);
+    logger_1.loggerRegistry.info(`[${prefix}:loadTools] ${servers.length} servers, ${toolIds.length} tools loaded`);
+    return { toolIds, inventory: inventoryLines.join('\n'), strategy };
+}

package/build/system/workflows/shared/types.d.ts

@@ -0,0 +1,9 @@
+export interface ServerInfo {
+    name: string;
+    description: string | null;
+    tags: string[];
+    metadata: Record<string, any> | null;
+    toolNames: string[];
+    toolCount: number;
+    slug: string;
+}