@hotmeshio/long-tail 0.1.4 → 0.1.6

package/build/system/workflows/mcp-workflow-builder/index.js

@@ -0,0 +1,229 @@
+"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.mcpWorkflowBuilder = mcpWorkflowBuilder;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const activities = __importStar(require("./activities"));
+const prompts_1 = require("./prompts");
+const { loadBuilderTools, callBuilderLLM, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+    retry: {
+        maximumAttempts: 3,
+        backoffCoefficient: 2,
+        maximumInterval: '10 seconds',
+    },
+});
+const MAX_BUILD_ATTEMPTS = 3;
+const MAX_CLARIFICATION_ROUNDS = 3;
+/**
+ * Fix known @pipe anti-patterns in generated YAML.
+ *
+ * LLMs consistently produce two broken patterns:
+ * 1. ['{@date.toISOString}'] then [0, 10] then ['{@string.substring}']
+ *    → should be ['{@date.toISOString}', 0, 10] then ['{@string.substring}']
+ * 2. Bare static rows like ['.png'] after sub-pipes
+ *    → should be wrapped in '@pipe': [['.png']]
+ *
+ * This runs deterministically on the YAML string before deployment.
+ */
+function fixPipePatterns(yaml) {
+    // Fix pattern 1: function row followed by bare args row followed by another function
+    // ['{@date.toISOString}']  →  ['{@date.toISOString}', 0, 10]
+    // [0, 10]                     ['{@string.substring}']
+    // ['{@string.substring}']
+    yaml = yaml.replace(/(\['\{@date\.toISOString\}'\])\s*\n(\s*)- \[0, 10\]\s*\n(\s*)- \['\{@string\.substring\}'\]/g, "['{@date.toISOString}', 0, 10]\n$2- ['{@string.substring}']");
+    // Fix field name mismatches the LLM consistently gets wrong
+    // Vision: image_path → image (the tool parameter name)
+    yaml = yaml.replace(/(\s+)image_path: /g, '$1image: ');
+    // Knowledge: content: '{...}' → data: '{...}' (store_knowledge field)
+    yaml = yaml.replace(/(\s+)content: '(\{[^}]+\.output\.data\.[^}]+\})'/g, "$1data: '$2'");
+    // Vision output: .analysis} → .description} (analyze_image returns description)
+    yaml = yaml.replace(/\.analysis\}/g, '.description}');
+    return yaml;
+}
+/**
+ * MCP Workflow Builder — constructs HotMesh YAML DAGs directly.
+ *
+ * Unlike mcpQuery (which executes tools then compiles traces), this workflow
+ * reasons about tool schemas and builds the YAML declaratively. The LLM
+ * knows HotMesh's activity types, mapping syntax, and @pipe operators.
+ *
+ * Supports conversational clarification: when the prompt is ambiguous,
+ * the LLM returns questions instead of YAML. The user answers, and the
+ * exchange continues until the LLM has enough to build.
+ *
+ * Returns the generated YAML, input schema, and activity manifest —
+ * ready for deployment via the existing yaml-workflow infrastructure.
+ */
+async function mcpWorkflowBuilder(envelope) {
+    const prompt = (envelope.data?.prompt || envelope.data?.question);
+    const tags = envelope.data?.tags;
+    const feedback = envelope.data?.feedback;
+    const priorYaml = envelope.data?.prior_yaml;
+    const answers = envelope.data?.answers;
+    const priorQuestions = envelope.data?.prior_questions;
+    if (!prompt) {
+        return {
+            type: 'return',
+            data: {
+                title: 'No prompt provided',
+                summary: 'Describe the workflow you want to build.',
+                result: null,
+            },
+        };
+    }
+    // 1. Discover available MCP tools
+    const raw = await loadBuilderTools(tags);
+    // 2. Build system prompt with HotMesh spec + tool inventory
+    const serverSection = [
+        raw.strategy ? `${raw.strategy}\n` : '',
+        `## Available MCP Servers & Tools\n\n${raw.inventory}`,
+    ].filter(Boolean).join('\n');
+    const messages = [
+        {
+            role: 'system',
+            content: (0, prompts_1.BUILDER_SYSTEM_PROMPT)(serverSection),
+        },
+    ];
+    // If refining a prior attempt, inject context
+    if (feedback && priorYaml) {
+        messages.push({
+            role: 'user',
+            content: `Build a workflow for: ${prompt}`,
+        });
+        messages.push({
+            role: 'assistant',
+            content: `Here is the prior YAML that needs fixing:\n\`\`\`yaml\n${priorYaml.slice(0, 3000)}\n\`\`\``,
+        });
+        messages.push({
+            role: 'user',
+            content: `${prompts_1.REFINE_PROMPT}\n\nExecution feedback:\n${feedback}`,
+        });
+    }
+    else if (answers && priorQuestions?.length) {
+        // Continuing a clarification conversation
+        messages.push({
+            role: 'user',
+            content: `Build a workflow for: ${prompt}`,
+        });
+        messages.push({
+            role: 'assistant',
+            content: JSON.stringify({ clarification_needed: true, questions: priorQuestions }),
+        });
+        messages.push({
+            role: 'user',
+            content: `Here are my answers:\n${answers}\n\nNow build the workflow YAML.`,
+        });
+    }
+    else {
+        messages.push({
+            role: 'user',
+            content: `Build a workflow for: ${prompt}`,
+        });
+    }
+    // 3. Ask the LLM to construct the YAML (with retry on parse failure)
+    for (let attempt = 0; attempt < MAX_BUILD_ATTEMPTS; attempt++) {
+        const response = await callBuilderLLM(messages, undefined);
+        const content = response.content || '';
+        // Parse the JSON response
+        const cleaned = content
+            .replace(/^```(?:json)?\s*/m, '')
+            .replace(/\s*```$/m, '')
+            .trim();
+        try {
+            const result = JSON.parse(cleaned);
+            // Clarification response — LLM needs more info before building
+            if (result.clarification_needed && Array.isArray(result.questions)) {
+                return {
+                    type: 'return',
+                    data: {
+                        title: 'Clarification Needed',
+                        summary: 'The builder needs more information before constructing the workflow.',
+                        clarification_needed: true,
+                        questions: result.questions,
+                        tools_identified: result.tools_identified || [],
+                    },
+                    milestones: [
+                        { name: 'workflow_builder', value: 'clarification' },
+                    ],
+                };
+            }
+            if (!result.yaml || !result.name) {
+                messages.push({ role: 'assistant', content });
+                messages.push({
+                    role: 'user',
+                    content: 'Response is missing required fields. Return a JSON object with: name, description, yaml, input_schema, activity_manifest, tags, sample_inputs. Or if you need more information, return { "clarification_needed": true, "questions": ["..."] }.',
+                });
+                continue;
+            }
+            // Fix known @pipe anti-patterns before returning
+            const fixedYaml = fixPipePatterns(result.yaml);
+            return {
+                type: 'return',
+                data: {
+                    title: `Workflow: ${result.name}`,
+                    summary: result.description || 'Workflow built successfully.',
+                    name: result.name,
+                    description: result.description,
+                    yaml: fixedYaml,
+                    input_schema: result.input_schema,
+                    activity_manifest: result.activity_manifest,
+                    tags: result.tags,
+                    sample_inputs: result.sample_inputs,
+                    build_attempts: attempt + 1,
+                },
+                milestones: [
+                    { name: 'workflow_builder', value: 'completed' },
+                    { name: 'build_attempts', value: String(attempt + 1) },
+                ],
+            };
+        }
+        catch {
+            messages.push({ role: 'assistant', content });
+            messages.push({
+                role: 'user',
+                content: 'Invalid JSON. Return a single JSON object (no markdown fences) with: name, description, yaml, input_schema, activity_manifest, tags, sample_inputs.',
+            });
+        }
+    }
+    return {
+        type: 'return',
+        data: {
+            title: 'Build Failed',
+            summary: 'Could not generate valid workflow YAML after multiple attempts.',
+            result: null,
+        },
+    };
+}

package/build/system/workflows/mcp-workflow-builder/prompts.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Externalized prompts for the workflow builder.
+ *
+ * The system prompt teaches the LLM how to construct HotMesh YAML DAGs
+ * directly from tool schemas — no execution trace needed.
+ */
+export declare function BUILDER_SYSTEM_PROMPT(toolInventory: string): string;
+export declare const REFINE_PROMPT = "The workflow was tested and produced errors or incorrect results. Review the execution trace below and fix the YAML.\n\nCommon issues:\n- Missing .png extension on screenshot paths\n- Field name mismatch between output and input (e.g., producer outputs \"path\" but consumer expects \"image\")\n- Missing _scope or workflowName in input.maps\n- Wrong activity ID references in mappings\n- Missing job.maps on the final activity\n\nReturn the same JSON format as before with corrected yaml, activity_manifest, etc.";

package/build/system/workflows/mcp-workflow-builder/prompts.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Externalized prompts for the workflow builder.
+ *
+ * The system prompt teaches the LLM how to construct HotMesh YAML DAGs
+ * directly from tool schemas — no execution trace needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REFINE_PROMPT = void 0;
+exports.BUILDER_SYSTEM_PROMPT = BUILDER_SYSTEM_PROMPT;
+function BUILDER_SYSTEM_PROMPT(toolInventory) {
+    return `You are a HotMesh workflow builder. Given a natural language description and a set of available MCP tools, you construct a deterministic YAML DAG workflow.
+
+You do NOT execute tools. You reason about their input/output schemas and build the YAML declaratively.
+
+## HotMesh YAML Structure
+
+A workflow is a YAML document with this shape:
+
+\`\`\`yaml
+app:
+  id: longtail
+  version: '1'
+  graphs:
+    - subscribes: <workflow-topic>
+      expire: 300
+      input:
+        schema:
+          type: object
+          properties:
+            <trigger inputs the user provides at runtime>
+          required: [<required input keys>]
+      output:
+        schema:
+          type: object
+      activities:
+        <activity definitions>
+      transitions:
+        <activity-id>:
+          - to: <next-activity-id>
+\`\`\`
+
+## Activity Types
+
+### trigger
+Entry point. Receives user input. Always the first activity.
+\`\`\`yaml
+my_trigger:
+  title: Trigger
+  type: trigger
+  output:
+    schema:
+      type: object
+\`\`\`
+
+### worker
+Executes an MCP tool. Receives data via input.maps, produces output.
+\`\`\`yaml
+my_worker:
+  title: Capture Page
+  type: worker
+  topic: <same as subscribes>
+  input:
+    schema:
+      type: object
+    maps:
+      url: '{my_trigger.output.data.url}'
+      screenshot_path:
+        '@pipe':
+          - ['{my_trigger.output.data.slug}', '.png']
+          - ['{@string.concat}']
+      workflowName: capture_page
+  output:
+    schema:
+      type: object
+\`\`\`
+
+### hook
+Durable pause point — used for human-in-the-loop signals and iteration anchors.
+
+### cycle
+Loop back to a hook ancestor for iteration patterns.
+
+## Data Mapping Rules
+
+### Simple reference (wire one activity's output to another's input):
+\`\`\`yaml
+field_name: '{sourceActivity.output.data.fieldName}'
+\`\`\`
+
+### @pipe (sequential transformation — array of arrays):
+Each row's output becomes input to the next row's function.
+\`\`\`yaml
+field_name:
+  '@pipe':
+    - ['{source.output.data.value}', '-suffix']
+    - ['{@string.concat}']
+    - ['{@string.toLowerCase}']
+\`\`\`
+
+### Nested @pipe (fan-out/fan-in):
+Sub-pipes must be ROW-LEVEL entries in the parent pipe array — each is a separate row, NOT an element inside another row's array. Sub-pipes resolve first, then their results become args to the final function row.
+\`\`\`yaml
+dated_key:
+  '@pipe':
+    - '@pipe':
+      - ['{my_trigger.output.data.slug}', '-']
+      - ['{@string.concat}']
+    - '@pipe':
+      - ['{@date.now}']
+      - ['{@date.toISOString}', 0, 10]
+      - ['{@string.substring}']
+    - ['{@string.concat}']
+\`\`\`
+This produces \`my-slug-2026-04-19\`. Row 1 sub-pipe: \`slug + "-"\`. Row 2 sub-pipe: today's date. Row 3: concat all results.
+
+CRITICAL RULES for nested @pipe:
+1. Never put a nested \`@pipe\` object INSIDE an array row. Each sub-pipe must be its own row in the parent.
+2. Maximum nesting depth is 2 levels (parent @pipe containing sub-pipe rows). Never nest a @pipe inside a @pipe inside a @pipe.
+3. For multi-part string building (e.g., domain/key/date.png), use a SINGLE flat @pipe with multiple sub-pipe rows — one per part — then a final \`['{@string.concat}']\` row. EVERY row must be either a sub-pipe object OR a function call array. Static values MUST be wrapped in a sub-pipe:
+\`\`\`yaml
+path:
+  '@pipe':
+    - '@pipe':
+      - ['{trigger.output.data.domain}', '/', '{trigger.output.data.key}', '/']
+      - ['{@string.concat}']
+    - '@pipe':
+      - ['{@date.now}']
+      - ['{@date.toISOString}', 0, 10]
+      - ['{@string.substring}']
+    - '@pipe':
+      - ['.png']
+    - ['{@string.concat}']
+\`\`\`
+This resolves: sub-pipe1 → "research/google/", sub-pipe2 → "2026-04-19", sub-pipe3 → ".png", then concat all → "research/google/2026-04-19.png".
+
+IMPORTANT: A bare array like \`['.png']\` as a row after sub-pipes will CRASH — HotMesh interprets it as a function call. Always wrap static values in \`'@pipe': - [value]\`.
+
+### Available @pipe operators (every JS method is exposed):
+- **@string**: charAt, concat, includes, indexOf, replace, slice, split, startsWith, substring, toLowerCase, toUpperCase, trim
+- **@date**: now, toISOString, toDateString, getFullYear, getMonth, getDate, getHours, getMinutes, getSeconds, fromISOString, parse (full JS Date API)
+- **@math**: add, subtract, multiply, divide
+- **@number**: gte, lte, gt, lt
+- **@array**: get, length
+- **@object**: get, keys, values
+- **@conditional**: ternary, less_than, greater_than
+- **@json**: parse, stringify
+
+### Three mapping directions per activity:
+- **input.maps**: Wire data INTO this activity from trigger or upstream activities
+- **output.maps**: Transform this activity's own output before downstream consumption
+- **job.maps**: Promote data to shared workflow state (use on LAST activity for workflow result)
+
+## Construction Rules
+
+1. **Trigger first**: Every workflow starts with a trigger activity
+2. **Worker per tool**: Each MCP tool call is a worker activity
+3. **workflowName**: Every worker MUST have \`workflowName: '<tool_name>'\` in its input.maps — this routes to the correct MCP tool handler
+4. **_scope threading**: Every worker MUST have \`_scope: '{trigger.output.data._scope}'\` for IAM context
+5. **Wire outputs forward**: Use \`{prevActivity.output.data.fieldName}\` to pass data between steps
+6. **Use @pipe for transforms**: When a value needs runtime computation (date stamp, string concat, slugify), use @pipe — never hardcode computed values
+7. **Simple fields stay simple**: If a field just passes a trigger value through (domain, key, url), use a plain reference like \`'{trigger.output.data.domain}'\` — NEVER wrap it in @pipe. Only use @pipe when actual transformation is needed.
+8. **File extensions**: Screenshot paths MUST include .png extension. Use @pipe concat if deriving from a slug
+8. **job.maps on last activity**: The final activity should have job.maps to promote output fields to the workflow result
+9. **Linear transitions**: Chain activities with transitions unless iteration is needed
+
+## Activity Manifest
+
+Along with the YAML, produce an activity_manifest array describing each activity:
+\`\`\`json
+[
+  {
+    "activity_id": "my_trigger",
+    "title": "Trigger",
+    "type": "trigger",
+    "tool_source": "trigger",
+    "topic": "<workflow-topic>",
+    "input_mappings": {},
+    "output_fields": ["url", "slug"]
+  },
+  {
+    "activity_id": "my_a1",
+    "title": "Capture Page",
+    "type": "worker",
+    "tool_source": "mcp",
+    "topic": "<workflow-topic>",
+    "workflow_name": "capture_page",
+    "mcp_server_id": "long-tail-playwright-cli",
+    "mcp_tool_name": "capture_page",
+    "tool_arguments": {},
+    "input_mappings": { "url": "{my_trigger.output.data.url}" },
+    "output_fields": ["page_id", "path", "url", "title"]
+  }
+]
+\`\`\`
+
+## Clarification Protocol
+
+If the user's description is ambiguous or missing critical details, ask clarifying questions BEFORE building. Return:
+{
+  "clarification_needed": true,
+  "questions": [
+    "Which tools should capture the screenshot — capture_page (simple URL+screenshot) or login_and_capture (authenticated)?",
+    "What fields should the user provide at runtime? (e.g., URL, domain, key)",
+    "Should the analysis description be stored as-is or with additional metadata?"
+  ],
+  "tools_identified": ["capture_page", "analyze_image", "store_knowledge"]
+}
+
+Ask for clarification when:
+- The prompt doesn't specify which tools to use and multiple options exist
+- Input/output expectations are unclear (what does the user provide vs what is derived?)
+- The data flow between steps is ambiguous (e.g., should the screenshot path be user-provided or auto-derived?)
+- File naming conventions aren't specified (date-stamped? slugified?)
+
+Do NOT ask for clarification when:
+- The prompt is specific enough to build (mentions tools, inputs, and expected behavior)
+- The user has already answered prior questions (answers are provided)
+- Only one reasonable tool choice exists for each step
+
+When the user provides answers to your questions, build the workflow immediately.
+
+## Output Format
+
+Return a JSON object (no markdown fences):
+{
+  "name": "kebab-case-workflow-name",
+  "description": "What this workflow does",
+  "yaml": "<the complete YAML string>",
+  "input_schema": { <JSON Schema for trigger inputs> },
+  "activity_manifest": [ <manifest entries> ],
+  "tags": ["relevant", "tags"],
+  "sample_inputs": { <example trigger values for testing> }
+}
+
+${toolInventory}`;
+}
+exports.REFINE_PROMPT = `The workflow was tested and produced errors or incorrect results. Review the execution trace below and fix the YAML.
+
+Common issues:
+- Missing .png extension on screenshot paths
+- Field name mismatch between output and input (e.g., producer outputs "path" but consumer expects "image")
+- Missing _scope or workflowName in input.maps
+- Wrong activity ID references in mappings
+- Missing job.maps on the final activity
+
+Return the same JSON format as before with corrected yaml, activity_manifest, etc.`;

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

@@ -0,0 +1,35 @@
+import type { ToolDefinition } from '../../../services/llm';
+import type { WorkflowCandidate } from '../../../types/discovery';
+/**
+ * Ranked discovery of compiled YAML workflows via FTS + tag overlap.
+ *
+ * Callers pass their own module-level caches so each pipeline keeps
+ * isolated cache instances.
+ */
+export declare function findCompiledWorkflows(prompt: string, caches: {
+    yamlWorkflowMap: Map<string, string>;
+    toolDefCache: Map<string, ToolDefinition>;
+}, logPrefix?: string): Promise<{
+    inventory: string;
+    toolIds: string[];
+    candidates: WorkflowCandidate[];
+}>;
+/**
+ * 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.
+ */
+export declare function evaluateWorkflowMatch(prompt: string, candidates: WorkflowCandidate[], logPrefix?: string): Promise<{
+    matched: boolean;
+    workflowName: string | null;
+    confidence: number;
+}>;
+/**
+ * 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.
+ */
+export declare function extractWorkflowInputs(prompt: string, inputSchema: Record<string, unknown>, workflowName: string): Promise<{
+    inputs: Record<string, any> | null;
+    extracted: boolean;
+}>;