@hotmeshio/long-tail 0.1.6 → 0.1.7

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

@@ -45,7 +45,7 @@ app:
 ### trigger
 Entry point. Receives user input. Always the first activity.
 \`\`\`yaml
-my_trigger:
+trigger_x8kf:
   title: Trigger
   type: trigger
   output:
@@ -54,9 +54,9 @@ my_trigger:
 \`\`\`
 
 ### worker
-Executes an MCP tool. Receives data via input.maps, produces output.
+Executes an MCP tool. Receives data via input.maps, produces output. Same suffix as the trigger.
 \`\`\`yaml
-my_worker:
+capture_x8kf:
   title: Capture Page
   type: worker
   topic: <same as subscribes>
@@ -64,10 +64,10 @@ my_worker:
     schema:
       type: object
     maps:
-      url: '{my_trigger.output.data.url}'
+      url: '{trigger_x8kf.output.data.url}'
       screenshot_path:
         '@pipe':
-          - ['{my_trigger.output.data.slug}', '.png']
+          - ['{trigger_x8kf.output.data.slug}', '.png']
           - ['{@string.concat}']
       workflowName: capture_page
   output:
@@ -76,10 +76,14 @@ my_worker:
 \`\`\`
 
 ### hook
-Durable pause point — used for human-in-the-loop signals and iteration anchors.
+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 for iteration patterns.
+Loop back to a hook ancestor marked \`cycle: true\`. Each iteration runs in isolated state, but \`job.maps\` accumulates across iterations.
 
 ## Data Mapping Rules
 
@@ -88,14 +92,56 @@ Loop back to a hook ancestor for iteration patterns.
 field_name: '{sourceActivity.output.data.fieldName}'
 \`\`\`
 
-### @pipe (sequential transformation — array of arrays):
-Each row's output becomes input to the next row's function.
+### @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']
-    - ['{@string.concat}']
-    - ['{@string.toLowerCase}']
+    - ['{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):
@@ -104,7 +150,7 @@ Sub-pipes must be ROW-LEVEL entries in the parent pipe array — each is a separ
 dated_key:
   '@pipe':
     - '@pipe':
-      - ['{my_trigger.output.data.slug}', '-']
+      - ['{trigger_x8kf.output.data.slug}', '-']
       - ['{@string.concat}']
     - '@pipe':
       - ['{@date.now}']
@@ -112,7 +158,7 @@ dated_key:
       - ['{@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.
+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.
@@ -122,7 +168,7 @@ CRITICAL RULES for nested @pipe:
 path:
   '@pipe':
     - '@pipe':
-      - ['{trigger.output.data.domain}', '/', '{trigger.output.data.key}', '/']
+      - ['{trigger_x8kf.output.data.domain}', '/', '{trigger_x8kf.output.data.key}', '/']
       - ['{@string.concat}']
     - '@pipe':
       - ['{@date.now}']
@@ -137,14 +183,16 @@ This resolves: sub-pipe1 → "research/google/", sub-pipe2 → "2026-04-19", sub
 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
+- **@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
@@ -155,22 +203,41 @@ IMPORTANT: A bare array like \`['.png']\` as a row after sub-pipes will CRASH
 
 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
+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:
+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": "my_trigger",
+    "activity_id": "trigger_x8kf",
     "title": "Trigger",
     "type": "trigger",
     "tool_source": "trigger",
@@ -179,7 +246,7 @@ Along with the YAML, produce an activity_manifest array describing each activity
     "output_fields": ["url", "slug"]
   },
   {
-    "activity_id": "my_a1",
+    "activity_id": "capture_x8kf",
     "title": "Capture Page",
     "type": "worker",
     "tool_source": "mcp",
@@ -188,7 +255,7 @@ Along with the YAML, produce an activity_manifest array describing each activity
     "mcp_server_id": "long-tail-playwright-cli",
     "mcp_tool_name": "capture_page",
     "tool_arguments": {},
-    "input_mappings": { "url": "{my_trigger.output.data.url}" },
+    "input_mappings": { "url": "{trigger_x8kf.output.data.url}" },
     "output_fields": ["page_id", "path", "url", "title"]
   }
 ]
@@ -222,9 +289,11 @@ 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": "kebab-case-workflow-name",
+  "name": "screenshot.analyze.store",
   "description": "What this workflow does",
   "yaml": "<the complete YAML string>",
   "input_schema": { <JSON Schema for trigger inputs> },

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>;

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

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Persistence activities for the workflow planner.
+ * These are side-effect functions that update the database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.persistPlan = persistPlan;
+exports.persistBuiltWorkflow = persistBuiltWorkflow;
+exports.updateSetStatus = updateSetStatus;
+exports.deploySetNamespaces = deploySetNamespaces;
+const workflow_sets_1 = require("../../../../services/workflow-sets");
+const db_1 = require("../../../../services/yaml-workflow/db");
+const deployer_1 = require("../../../../services/yaml-workflow/deployer");
+const workers_1 = require("../../../../services/yaml-workflow/workers");
+async function persistPlan(setId, planItems) {
+    const namespaces = [...new Set(planItems.map(w => w.namespace))];
+    await (0, workflow_sets_1.updateWorkflowSetPlan)(setId, planItems, namespaces);
+}
+async function persistBuiltWorkflow(setId, planItem, builderOutput) {
+    const input = {
+        name: builderOutput.name,
+        description: builderOutput.description,
+        app_id: planItem.namespace,
+        yaml_content: builderOutput.yaml_content,
+        graph_topic: builderOutput.graph_topic || builderOutput.name,
+        input_schema: builderOutput.input_schema,
+        output_schema: builderOutput.output_schema,
+        activity_manifest: builderOutput.activity_manifest,
+        tags: builderOutput.tags || [],
+        source_workflow_type: 'mcpWorkflowPlanner',
+        set_id: setId,
+        set_role: planItem.role,
+        set_build_order: planItem.build_order,
+    };
+    const record = await (0, db_1.createYamlWorkflow)(input);
+    return record.id;
+}
+async function updateSetStatus(setId, status) {
+    await (0, workflow_sets_1.updateWorkflowSetStatus)(setId, status);
+}
+async function deploySetNamespaces(namespaces) {
+    for (const namespace of namespaces) {
+        await (0, deployer_1.deployAppId)(namespace, '1');
+        // Register workers and activate all workflows in this namespace
+        const siblings = await (0, db_1.listYamlWorkflowsByAppId)(namespace);
+        for (const sibling of siblings) {
+            await (0, db_1.updateYamlWorkflowVersion)(sibling.id, '1');
+            await (0, workers_1.registerWorkersForWorkflow)(sibling);
+            if (sibling.status === 'draft' || sibling.status === 'deployed') {
+                await (0, db_1.updateYamlWorkflowStatus)(sibling.id, 'active');
+            }
+        }
+        await (0, db_1.markAppIdContentDeployed)(namespace);
+    }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Generate a decomposition plan from a specification using an LLM.
+ */
+import type { PlanItem } from '../../../../types/workflow-set';
+export interface PlanResult {
+    plan_name: string;
+    plan_description: string;
+    workflows: PlanItem[];
+}
+export declare function generatePlan(specification: string): Promise<PlanResult>;

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

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Generate a decomposition plan from a specification using an LLM.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePlan = generatePlan;
+const llm_1 = require("../../../../services/llm");
+const defaults_1 = require("../../../../modules/defaults");
+const prompts_1 = require("../prompts");
+async function generatePlan(specification) {
+    const response = await (0, llm_1.callLLM)({
+        model: defaults_1.LLM_MODEL_PRIMARY,
+        max_tokens: 4096,
+        temperature: 0,
+        messages: [
+            { role: 'system', content: prompts_1.PLANNER_SYSTEM_PROMPT },
+            { role: 'user', content: specification },
+        ],
+    });
+    const raw = response.content || '{}';
+    const cleaned = raw.replace(/^```(?:json)?\s*/m, '').replace(/\s*```$/m, '').trim();
+    const parsed = JSON.parse(cleaned);
+    if (!Array.isArray(parsed.workflows) || parsed.workflows.length === 0) {
+        throw new Error('Planner produced empty workflow list');
+    }
+    // Sort by build_order (leaf-first)
+    parsed.workflows.sort((a, b) => a.build_order - b.build_order);
+    // Extract unique namespaces
+    const namespaces = [...new Set(parsed.workflows.map(w => w.namespace))];
+    return {
+        plan_name: parsed.plan_name || 'unnamed-plan',
+        plan_description: parsed.plan_description || '',
+        workflows: parsed.workflows.map(w => ({
+            name: w.name,
+            description: w.description,
+            namespace: w.namespace,
+            role: w.role || 'leaf',
+            dependencies: w.dependencies || [],
+            build_order: w.build_order ?? 0,
+            io_contract: w.io_contract || { input_schema: {}, output_schema: {} },
+        })),
+    };
+}

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

@@ -0,0 +1,7 @@
+import type { LTEnvelope, LTReturn } from '../../../types';
+/**
+ * Plan mode workflow — decomposes a specification into N workflows,
+ * builds them leaf-first by delegating to mcpWorkflowBuilder,
+ * and deploys the resulting set.
+ */
+export declare function mcpWorkflowPlanner(envelope: LTEnvelope): Promise<LTReturn>;

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

@@ -0,0 +1,152 @@
+"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.mcpWorkflowPlanner = mcpWorkflowPlanner;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const orchestrator_1 = require("../../../services/orchestrator");
+const activities = __importStar(require("./activities"));
+const { generatePlan, persistPlan, persistBuiltWorkflow, updateSetStatus, deploySetNamespaces, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+    retry: {
+        maximumAttempts: 3,
+        backoffCoefficient: 2,
+        maximumInterval: '10 seconds',
+    },
+});
+/**
+ * Plan mode workflow — decomposes a specification into N workflows,
+ * builds them leaf-first by delegating to mcpWorkflowBuilder,
+ * and deploys the resulting set.
+ */
+async function mcpWorkflowPlanner(envelope) {
+    const { specification, setId } = envelope.data;
+    // 1. Generate plan from specification
+    const planResult = await generatePlan(specification);
+    // 2. Persist the plan to the workflow set
+    await persistPlan(setId, planResult.workflows);
+    // 3. Build each workflow in dependency order (leaf-first)
+    await updateSetStatus(setId, 'building');
+    const builtWorkflows = [];
+    for (const planItem of planResult.workflows) {
+        // Build context for the builder: sibling schemas for composition wiring
+        const siblingSchemas = builtWorkflows.map(w => ({
+            name: w.name,
+            input_schema: w.input_schema,
+            output_schema: w.output_schema,
+            graph_topic: w.graph_topic,
+        }));
+        // Delegate to the existing builder workflow
+        const builderResult = await (0, orchestrator_1.executeLT)({
+            workflowName: 'mcpWorkflowBuilder',
+            args: [{
+                    data: {
+                        prompt: buildPromptForPlanItem(planItem, siblingSchemas),
+                        tags: [],
+                        composition_context: {
+                            sibling_schemas: siblingSchemas,
+                            dependencies: planItem.dependencies,
+                            namespace: planItem.namespace,
+                            requires_await: planItem.dependencies.some(dep => planResult.workflows.find(w => w.name === dep)?.namespace === planItem.namespace),
+                        },
+                    },
+                    metadata: envelope.metadata,
+                    lt: envelope.lt,
+                }],
+            taskQueue: 'long-tail-system',
+        });
+        const builderData = builderResult.data;
+        // Persist the built workflow with set membership
+        const yamlId = await persistBuiltWorkflow(setId, planItem, {
+            name: builderData.name || planItem.name,
+            description: builderData.description || planItem.description,
+            yaml_content: builderData.yaml,
+            input_schema: builderData.input_schema || {},
+            output_schema: planItem.io_contract.output_schema || {},
+            activity_manifest: builderData.activity_manifest || [],
+            tags: builderData.tags || [],
+            graph_topic: builderData.name || planItem.name,
+        });
+        builtWorkflows.push({
+            name: planItem.name,
+            id: yamlId,
+            input_schema: builderData.input_schema || {},
+            output_schema: planItem.io_contract.output_schema || {},
+            graph_topic: builderData.name || planItem.name,
+        });
+    }
+    // 4. Deploy all namespaces
+    await updateSetStatus(setId, 'deploying');
+    const namespaces = [...new Set(planResult.workflows.map(w => w.namespace))];
+    await deploySetNamespaces(namespaces);
+    // 5. Mark complete
+    await updateSetStatus(setId, 'completed');
+    return {
+        type: 'return',
+        data: {
+            title: planResult.plan_name,
+            summary: `Built ${builtWorkflows.length} workflows across ${namespaces.length} namespace(s)`,
+            set_id: setId,
+            workflows: builtWorkflows,
+            namespaces,
+        },
+    };
+}
+/**
+ * Build a detailed prompt for the builder from a plan item.
+ * Includes the workflow description, I/O contract, and dependency context.
+ */
+function buildPromptForPlanItem(planItem, siblingSchemas) {
+    const parts = [planItem.description];
+    // Add I/O contract
+    if (planItem.io_contract.input_schema?.properties) {
+        parts.push(`\nInputs: ${JSON.stringify(planItem.io_contract.input_schema, null, 2)}`);
+    }
+    if (planItem.io_contract.output_schema?.properties) {
+        parts.push(`\nOutputs: ${JSON.stringify(planItem.io_contract.output_schema, null, 2)}`);
+    }
+    // Add dependency context
+    if (planItem.dependencies.length > 0) {
+        const depSchemas = siblingSchemas.filter(s => planItem.dependencies.includes(s.name));
+        if (depSchemas.length > 0) {
+            parts.push('\nThis workflow depends on the following sibling workflows:');
+            for (const dep of depSchemas) {
+                parts.push(`- ${dep.name} (topic: ${dep.graph_topic})`);
+                parts.push(`  Input: ${JSON.stringify(dep.input_schema)}`);
+                parts.push(`  Output: ${JSON.stringify(dep.output_schema)}`);
+            }
+        }
+    }
+    return parts.join('\n');
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Externalized prompts for the workflow planner.
+ *
+ * The planner prompt teaches the LLM how to decompose a specification
+ * into a set of related workflows with dependency ordering.
+ */
+export declare const PLANNER_SYSTEM_PROMPT = "You are a workflow planner. Given a specification (PRD, TDD, or natural language description of a multi-step process), you decompose it into a set of standalone workflows that together implement the complete system.\n\n## Your Task\n\nAnalyze the specification and produce a structured plan: an array of workflow items, each with a name, description, namespace, role, dependencies, and input/output contract.\n\n## Workflow Roles\n\n- **leaf**: A standalone workflow that calls MCP tools directly. No dependencies on other custom workflows in the plan.\n- **composition**: A workflow that orchestrates other workflows in the plan. It calls them using HotMesh await activities (same namespace) or MCP tool calls (different namespace).\n- **router**: A workflow that routes to different workflows based on input conditions.\n\n## Namespace Rules\n\nWorkflows in the **same namespace** are deployed together as one HotMesh application. They can invoke each other using await activities (synchronous composition within the same execution engine).\n\nWorkflows in **different namespaces** are independent. They invoke each other as MCP tools (discovered by tag, invoked through the tool protocol).\n\n**Same namespace when:** tightly coupled, shared data context, always deployed together, phases of the same process.\n**Different namespace when:** independently reusable, different versioning cycles, different teams/domains.\n\n## Build Order\n\nLeaf workflows are built first (build_order = 0). Composition workflows that depend on leaves come next (build_order = 1). Workflows that compose those compositions come after (build_order = 2). The tree builds from leaves up.\n\n## Input/Output Contracts\n\nEach workflow has a typed input and output contract (JSON Schema). Composition workflows wire their inputs to child workflow inputs, and child outputs back to their own outputs. These contracts are how the builder knows what to wire.\n\n## Output Format\n\nReturn a JSON object (no markdown fences):\n{\n  \"plan_name\": \"kebab-case-plan-name\",\n  \"plan_description\": \"What this set of workflows accomplishes\",\n  \"workflows\": [\n    {\n      \"name\": \"kebab-case-workflow-name\",\n      \"description\": \"What this workflow does \u2014 specific enough to build from\",\n      \"namespace\": \"the-app-namespace\",\n      \"role\": \"leaf\" | \"composition\" | \"router\",\n      \"dependencies\": [\"name-of-workflow-this-depends-on\"],\n      \"build_order\": 0,\n      \"io_contract\": {\n        \"input_schema\": {\n          \"type\": \"object\",\n          \"properties\": { ... },\n          \"required\": [...]\n        },\n        \"output_schema\": {\n          \"type\": \"object\",\n          \"properties\": { ... }\n        }\n      }\n    }\n  ]\n}\n\n## Rules\n\n1. Every workflow must be independently testable with sample inputs\n2. Leaf workflows should be fine-grained: one responsibility per workflow\n3. Composition workflows encode sequencing, branching, and escalation gates\n4. Do not create a workflow for something a single MCP tool call can handle \u2014 use a leaf workflow only when there are multiple steps or conditional logic\n5. Keep the number of workflows minimal \u2014 prefer fewer, well-scoped workflows over many trivial ones\n6. Names must be globally unique within the plan\n7. Dependencies reference other workflow names in the plan (not external tools)\n8. If the specification mentions human review, approval, or escalation, the relevant workflow should include a signal/hook step (describe this in the workflow description)";