@hotmeshio/long-tail 0.1.5 → 0.1.7

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

@@ -0,0 +1,253 @@
+"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, loadReferenceSection, 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;
+    const compositionContext = envelope.data?.composition_context;
+    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');
+    // 3. Load composition references if this workflow is part of a plan
+    const compositionSections = [];
+    if (compositionContext) {
+        if (compositionContext.requires_await) {
+            const awaitRef = await loadReferenceSection('await');
+            if (awaitRef)
+                compositionSections.push(awaitRef);
+        }
+        if (compositionContext.requires_signal) {
+            const signalRef = await loadReferenceSection('signal');
+            if (signalRef)
+                compositionSections.push(signalRef);
+        }
+        if (compositionContext.sibling_schemas?.length) {
+            const siblings = compositionContext.sibling_schemas
+                .map(s => `- **${s.name}** (topic: \`${s.graph_topic}\`)\n  Input: \`${JSON.stringify(s.input_schema)}\`\n  Output: \`${JSON.stringify(s.output_schema)}\``)
+                .join('\n');
+            compositionSections.push(`## Sibling Workflows in This Plan\n\nThis workflow is part of a multi-workflow set. The following sibling workflows exist in the same namespace and can be invoked using \`type: await\` activities:\n\n${siblings}`);
+        }
+    }
+    const fullInventory = compositionSections.length
+        ? `${serverSection}\n\n${compositionSections.join('\n\n')}`
+        : serverSection;
+    const messages = [
+        {
+            role: 'system',
+            content: (0, prompts_1.BUILDER_SYSTEM_PROMPT)(fullInventory),
+        },
+    ];
+    // 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,316 @@
+"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
+trigger_x8kf:
+  title: Trigger
+  type: trigger
+  output:
+    schema:
+      type: object
+\`\`\`
+
+### worker
+Executes an MCP tool. Receives data via input.maps, produces output. Same suffix as the trigger.
+\`\`\`yaml
+capture_x8kf:
+  title: Capture Page
+  type: worker
+  topic: <same as subscribes>
+  input:
+    schema:
+      type: object
+    maps:
+      url: '{trigger_x8kf.output.data.url}'
+      screenshot_path:
+        '@pipe':
+          - ['{trigger_x8kf.output.data.slug}', '.png']
+          - ['{@string.concat}']
+      workflowName: capture_page
+  output:
+    schema:
+      type: object
+\`\`\`
+
+### hook
+Durable pause point with three modes:
+- **Web hook**: Pauses until an external signal arrives. Define \`hook: { type: object, properties: {...} }\` for the expected signal schema. Receives signal data via \`{$self.hook.data.*}\`. Requires a matching entry in the graph-level \`hooks:\` section.
+- **Sleep**: Pauses for a duration. \`sleep: 5\` pauses 5 seconds. Supports @pipe expressions for dynamic delays.
+- **Cycle pivot**: When \`cycle: true\`, becomes an iteration anchor that a cycle activity can loop back to.
+- **Passthrough**: No hook/sleep config — acts as a data-mapping convergence point, executes immediately.
+
+### cycle
+Loop back to a hook ancestor marked \`cycle: true\`. Each iteration runs in isolated state, but \`job.maps\` accumulates across iterations.
+
+## Data Mapping Rules
+
+### Simple reference (wire one activity's output to another's input):
+\`\`\`yaml
+field_name: '{sourceActivity.output.data.fieldName}'
+\`\`\`
+
+### @pipe — Reverse Polish Notation (operands THEN operator)
+
+@pipe uses **stack-machine / RPN evaluation**: each row is evaluated top-to-bottom. A row is either OPERANDS (data for the next function) or an OPERATOR (a function that consumes the row above it). The rule is simple and absolute:
+
+> **ALL operands for a function must appear on the single row ABOVE the function row.**
+
+A function row contains ONLY the function reference: \`['{@string.substring}']\`. It receives its arguments from the row immediately above it. The first element on the operands row is typically a dynamic reference that resolves at runtime; the remaining elements are literal values.
+
+#### Simple pipe (no extra args):
+\`\`\`yaml
+field_name:
+  '@pipe':
+    - ['{source.output.data.value}', '-suffix']   # operands: value, suffix
+    - ['{@string.concat}']                         # operator: concat(value, suffix) → "hello-suffix"
+    - ['{@string.toLowerCase}']                    # operator: toLowerCase("hello-suffix")
+\`\`\`
+When a function takes only one argument (the result of the prior row), it needs no separate operands row — it just consumes what's above.
+
+#### Multi-arg function (THIS IS THE PATTERN LLMs GET WRONG):
+\`\`\`yaml
+date_substring:
+  '@pipe':
+    - ['{@date.now}']                              # operator: date.now() → 1713528000000
+    - ['{@date.toISOString}', 0, 10]               # operands: [isoString, 0, 10] for substring
+    - ['{@string.substring}']                       # operator: substring(isoString, 0, 10) → "2026-04-19"
+\`\`\`
+Row 2 is the OPERANDS row for substring. It contains THREE values:
+1. \`{@date.toISOString}\` — resolves dynamically (converts epoch → "2026-04-19T12:00:00.000Z")
+2. \`0\` — start index (literal)
+3. \`10\` — end index (literal)
+
+Row 3 is the OPERATOR row: \`substring\` consumes all three values from row 2.
+
+**COMMON MISTAKE** (NEVER DO THIS):
+\`\`\`yaml
+# WRONG — puts args on the operator row instead of the operands row above it
+  - ['{@date.toISOString}']
+  - ['{@string.substring}', 0, 10]     # ← BROKEN: 0, 10 must be on the row ABOVE
+\`\`\`
+\`\`\`yaml
+# ALSO WRONG — splits operands across two rows
+  - ['{@date.toISOString}']
+  - [0, 10]                            # ← BROKEN: operands separated from the dynamic value
+  - ['{@string.substring}']
+\`\`\`
+The ONLY correct form: all operands together on ONE row, operator alone on the NEXT row.
+
+**PREFERRED for dates**: Use \`{@date.yyyymmdd}\` which returns "YYYY-MM-DD" directly — no pipe needed:
+\`\`\`yaml
+today: '{@date.yyyymmdd}'
+\`\`\`
+
+### 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':
+      - ['{trigger_x8kf.output.data.slug}', '-']
+      - ['{@string.concat}']
+    - '@pipe':
+      - ['{@date.now}']
+      - ['{@date.toISOString}', 0, 10]
+      - ['{@string.substring}']
+    - ['{@string.concat}']
+\`\`\`
+This produces \`my-slug-2026-04-19\`. Sub-pipe 1: \`slug + "-"\`. Sub-pipe 2: today as YYYY-MM-DD (RPN: operands then operator). Final row: concat all sub-pipe 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_x8kf.output.data.domain}', '/', '{trigger_x8kf.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, endsWith, includes, indexOf, lastIndexOf, padEnd, padStart, repeat, replace, search, slice, split, startsWith, substring, toLowerCase, toUpperCase, trim, trimEnd, trimStart
+- **@date**: now, toISOString, toDateString, yyyymmdd (returns "YYYY-MM-DD" directly — preferred for date strings), getFullYear, getMonth, getDate, getDay, getHours, getMinutes, getSeconds, getTime, fromISOString, parse, UTC, toLocaleDateString, setFullYear, setMonth, setDate (full JS Date API)
+- **@math**: add, subtract, multiply, divide, abs, ceil, floor, round, trunc, pow, sqrt, max, min, random
+- **@number**: gt, gte, lt, lte, isFinite, isInteger, isEven, isOdd, isNaN, parseFloat, parseInt, toFixed, toExponential, toPrecision
+- **@array**: get, length, concat, indexOf, join, lastIndexOf, pop, push, reverse, shift, slice, sort, splice, unshift
+- **@object**: get, set, create, keys, values, entries, fromEntries, assign, hasOwnProperty, freeze
+- **@conditional**: ternary, equality, strict_equality, inequality, strict_inequality, greater_than, less_than, greater_than_or_equal, less_than_or_equal, nullish
+- **@json**: parse, stringify
+- **@logical**: and, or
+- **@bitwise**: and, or, xor, leftShift, rightShift
+
+### 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. **Collision-proof activity IDs**: Multiple workflows share the same app namespace. Activity IDs MUST be globally unique within the app. Use a descriptive name with a shared 4-char random suffix appended to every activity in the flow: \`trigger_x8kf\`, \`capture_x8kf\`, \`analyze_x8kf\`, \`store_x8kf\`. The suffix is the same for all activities in one workflow but unique across workflows. NEVER use bare names like \`trigger\`, \`capture\`, \`analyze\` — they WILL collide with other workflows in the same app.
+4. **workflowName**: Every worker MUST have \`workflowName: '<tool_name>'\` in its input.maps — this routes to the correct MCP tool handler
+5. **_scope threading**: Every worker MUST have \`_scope: '{trigger_x8kf.output.data._scope}'\` (using YOUR trigger's ID) for IAM context
+6. **Wire outputs forward**: Use \`{prevActivity.output.data.fieldName}\` to pass data between steps
+7. **Use @pipe for transforms**: When a value needs runtime computation (date stamp, string concat, slugify), use @pipe — never hardcode computed values
+8. **Simple fields stay simple**: If a field just passes a trigger value through (domain, key, url), use a plain reference like \`'{trigger_x8kf.output.data.domain}'\` — NEVER wrap it in @pipe. Only use @pipe when actual transformation is needed.
+9. **File extensions**: Screenshot paths MUST include .png extension. Use @pipe concat if deriving from a slug
+10. **job.maps on last activity**: The final activity should have job.maps to promote output fields to the workflow result
+11. **Linear transitions**: Chain activities with transitions unless branching or iteration is needed
+12. **Conditional transitions**: For branching, use multi-target transitions with conditions:
+\`\`\`yaml
+transitions:
+  check_x8kf:
+    - to: handle_error_x8kf
+      conditions:
+        code: 500
+    - to: proceed_x8kf
+\`\`\`
+Conditions can match on \`code\` (HTTP status) or \`match\` (field comparisons). The first matching condition wins; the last entry (no conditions) is the default.
+13. **Trigger stats for idempotency**: Use \`stats.id\` and \`stats.key\` on the trigger when the workflow needs custom job IDs or indexed lookups:
+\`\`\`yaml
+trigger_x8kf:
+  type: trigger
+  stats:
+    id: '{$self.input.data.workflowId}'
+    key: '{$self.input.data.entityId}'
+\`\`\`
+
+## Activity Manifest
+
+Along with the YAML, produce an activity_manifest array describing each activity. Note how all activity IDs share the same random suffix (\`_x8kf\`) for collision-proofing while remaining human-readable:
+\`\`\`json
+[
+  {
+    "activity_id": "trigger_x8kf",
+    "title": "Trigger",
+    "type": "trigger",
+    "tool_source": "trigger",
+    "topic": "<workflow-topic>",
+    "input_mappings": {},
+    "output_fields": ["url", "slug"]
+  },
+  {
+    "activity_id": "capture_x8kf",
+    "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": "{trigger_x8kf.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
+
+CRITICAL: The "name" field MUST match the "subscribes" topic in the YAML exactly. Use lowercase with dots as separators (e.g. "screenshot.analyze.store", "capture.page", "daily.report"). Dashes and underscores are also allowed but dots are preferred. The name and subscribes topic MUST be identical.
+
+Return a JSON object (no markdown fences):
+{
+  "name": "screenshot.analyze.store",
+  "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/mcp-workflow-planner/activities/analyze.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Analyze a specification to determine whether it requires plan mode.
+ * Returns structural signals extracted from the input.
+ */
+export interface SpecAnalysis {
+    requires_plan: boolean;
+    signal_count: number;
+    char_count: number;
+    signals_found: string[];
+}
+export declare function analyzeSpecification(specification: string): Promise<SpecAnalysis>;

package/build/system/workflows/mcp-workflow-planner/activities/analyze.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Analyze a specification to determine whether it requires plan mode.
+ * Returns structural signals extracted from the input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeSpecification = analyzeSpecification;
+const PLAN_SIGNALS = [
+    /\bworkflow[s]?\b/gi,
+    /\bstep\s+\d/gi,
+    /\bphase\s+\d/gi,
+    /\bfirst\b.*\bthen\b/gi,
+    /\bcompos/gi,
+    /\borchestrat/gi,
+    /\bpipeline/gi,
+    /\bsub-?process/gi,
+    /\bplan\b/gi,
+];
+const MIN_PLAN_LENGTH = 500;
+async function analyzeSpecification(specification) {
+    const charCount = specification.length;
+    const signalsFound = [];
+    for (const pattern of PLAN_SIGNALS) {
+        const matches = specification.match(pattern);
+        if (matches?.length) {
+            signalsFound.push(matches[0]);
+        }
+    }
+    const requiresPlan = charCount >= MIN_PLAN_LENGTH && signalsFound.length >= 2;
+    return {
+        requires_plan: requiresPlan,
+        signal_count: signalsFound.length,
+        char_count: charCount,
+        signals_found: signalsFound,
+    };
+}

package/build/system/workflows/mcp-workflow-planner/activities/index.d.ts

@@ -0,0 +1,3 @@
+export { analyzeSpecification } from './analyze';
+export { generatePlan } from './plan';
+export { persistPlan, persistBuiltWorkflow, updateSetStatus, deploySetNamespaces, } from './persist';

package/build/system/workflows/mcp-workflow-planner/activities/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deploySetNamespaces = exports.updateSetStatus = exports.persistBuiltWorkflow = exports.persistPlan = exports.generatePlan = exports.analyzeSpecification = void 0;
+var analyze_1 = require("./analyze");
+Object.defineProperty(exports, "analyzeSpecification", { enumerable: true, get: function () { return analyze_1.analyzeSpecification; } });
+var plan_1 = require("./plan");
+Object.defineProperty(exports, "generatePlan", { enumerable: true, get: function () { return plan_1.generatePlan; } });
+var persist_1 = require("./persist");
+Object.defineProperty(exports, "persistPlan", { enumerable: true, get: function () { return persist_1.persistPlan; } });
+Object.defineProperty(exports, "persistBuiltWorkflow", { enumerable: true, get: function () { return persist_1.persistBuiltWorkflow; } });
+Object.defineProperty(exports, "updateSetStatus", { enumerable: true, get: function () { return persist_1.updateSetStatus; } });
+Object.defineProperty(exports, "deploySetNamespaces", { enumerable: true, get: function () { return persist_1.deploySetNamespaces; } });

package/build/system/workflows/mcp-workflow-planner/activities/persist.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Persistence activities for the workflow planner.
+ * These are side-effect functions that update the database.
+ */
+import type { PlanItem, LTWorkflowSetStatus } from '../../../../types/workflow-set';
+export declare function persistPlan(setId: string, planItems: PlanItem[]): Promise<void>;
+export interface BuiltWorkflowData {
+    name: string;
+    description: string;
+    yaml_content: string;
+    input_schema: Record<string, unknown>;
+    output_schema: Record<string, unknown>;
+    activity_manifest: unknown[];
+    tags: string[];
+    graph_topic: string;
+}
+export declare function persistBuiltWorkflow(setId: string, planItem: PlanItem, builderOutput: BuiltWorkflowData): Promise<string>;
+export declare function updateSetStatus(setId: string, status: LTWorkflowSetStatus): Promise<void>;
+export declare function deploySetNamespaces(namespaces: string[]): Promise<void>;