@hotmeshio/long-tail 0.1.13 → 0.1.15

package/build/system/seed/tool-manifests-knowledge.d.ts

@@ -12,10 +12,13 @@ export declare const KNOWLEDGE_TOOLS: ({
                 type: string;
                 description: string;
             };
-            data: {
+            field: {
                 type: string;
                 description: string;
             };
+            data: {
+                description: string;
+            };
             tags: {
                 type: string;
                 items: {
@@ -45,6 +48,7 @@ export declare const KNOWLEDGE_TOOLS: ({
                 type: string;
                 description: string;
             };
+            field?: undefined;
             data?: undefined;
             tags?: undefined;
             query?: undefined;
@@ -81,6 +85,7 @@ export declare const KNOWLEDGE_TOOLS: ({
                 description: string;
             };
             key?: undefined;
+            field?: undefined;
             data?: undefined;
             offset?: undefined;
             path?: undefined;
@@ -114,6 +119,7 @@ export declare const KNOWLEDGE_TOOLS: ({
                 description: string;
             };
             key?: undefined;
+            field?: undefined;
             data?: undefined;
             query?: undefined;
             path?: undefined;
@@ -129,6 +135,7 @@ export declare const KNOWLEDGE_TOOLS: ({
         properties: {
             domain?: undefined;
             key?: undefined;
+            field?: undefined;
             data?: undefined;
             tags?: undefined;
             query?: undefined;
@@ -160,6 +167,7 @@ export declare const KNOWLEDGE_TOOLS: ({
             value: {
                 description: string;
             };
+            field?: undefined;
             data?: undefined;
             tags?: undefined;
             query?: undefined;

package/build/system/seed/tool-manifests-knowledge.js

@@ -5,14 +5,15 @@ exports.KNOWLEDGE_TOOLS = void 0;
 exports.KNOWLEDGE_TOOLS = [
     {
         name: 'store_knowledge',
-        description: 'Store or update a knowledge entry. Upserts by domain+key: merges data and unions tags if the entry already exists.',
+        description: 'Store a value in a 3-level additive hierarchy: domain > key > field. Upserts by domain+key — fields accumulate across calls. Same domain+key+field overwrites that field. When field is provided, data can be any type. When omitted, data must be an object.',
         inputSchema: {
             type: 'object',
             properties: {
-                domain: { type: 'string', description: 'Knowledge domain (namespace)' },
-                key: { type: 'string', description: 'Unique key within domain' },
-                data: { type: 'object', description: 'JSONB payload to store' },
-                tags: { type: 'array', items: { type: 'string' }, description: 'Categorization tags' },
+                domain: { type: 'string', description: 'Top level — groups entries by namespace (e.g. "screenshots", "config")' },
+                key: { type: 'string', description: 'Second level — unique identifier within domain (e.g. "homepage")' },
+                field: { type: 'string', description: 'Third level (leaf) — names a specific field. Different fields accumulate; same field overwrites.' },
+                data: { description: 'The value to store. Any type when field is provided; must be an object when field is omitted.' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'Categorization tags (unioned on upsert)' },
             },
             required: ['domain', 'key', 'data'],
         },

package/build/system/workflows/mcp-triage/activities-proxy.d.ts

@@ -0,0 +1,21 @@
+import type { TriageResponseDeps } from './types';
+declare const getUpstreamTasks: (originId: string) => Promise<import("../../..").LTTaskRecord[]>, getEscalationHistory: (originId: string) => Promise<import("../../..").LTEscalationRecord[]>, getToolTags: (workflowType: string) => Promise<string[]>, loadTriageTools: (tags?: string[] | undefined) => Promise<{
+    toolIds: string[];
+    inventory: string;
+    strategy: string;
+}>, callTriageTool: (qualifiedName: string, args: Record<string, any>) => Promise<any>, callTriageLLM: (messages: any[], toolIds?: string[] | undefined) => Promise<import("../../../services/llm").LLMResponse>;
+declare const ltEnrichEscalationRouting: (input: {
+    escalationId: string;
+    signalRouting: {
+        taskQueue: string;
+        workflowType: string;
+        workflowId: string;
+        signalId: string;
+    };
+    taskId?: string;
+    claimForUserId?: string;
+}) => Promise<void>;
+export declare const MAX_TOOL_ROUNDS: number;
+/** Proxied activity refs passed to response handlers */
+export declare const responseDeps: TriageResponseDeps;
+export { getUpstreamTasks, getEscalationHistory, getToolTags, loadTriageTools, callTriageTool, callTriageLLM, ltEnrichEscalationRouting, };

package/build/system/workflows/mcp-triage/activities-proxy.js

@@ -0,0 +1,70 @@
+"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.ltEnrichEscalationRouting = exports.callTriageLLM = exports.callTriageTool = exports.loadTriageTools = exports.getToolTags = exports.getEscalationHistory = exports.getUpstreamTasks = exports.responseDeps = exports.MAX_TOOL_ROUNDS = void 0;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const defaults_1 = require("../../../modules/defaults");
+const activities = __importStar(require("../../activities/triage"));
+const interceptorActivities = __importStar(require("../../../services/interceptor/activities"));
+const { getUpstreamTasks, getEscalationHistory, getToolTags, loadTriageTools, callTriageTool, callTriageLLM, notifyEngineering, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities,
+    retry: {
+        maximumAttempts: 3,
+        backoffCoefficient: 2,
+        maximumInterval: '10 seconds',
+    },
+});
+exports.getUpstreamTasks = getUpstreamTasks;
+exports.getEscalationHistory = getEscalationHistory;
+exports.getToolTags = getToolTags;
+exports.loadTriageTools = loadTriageTools;
+exports.callTriageTool = callTriageTool;
+exports.callTriageLLM = callTriageLLM;
+const { ltCreateEscalation, ltCreateTask, ltGetTask, ltGetWorkflowConfig, ltStartWorkflow, ltEnrichEscalationRouting, } = hotmesh_1.Durable.workflow.proxyActivities({
+    activities: interceptorActivities,
+    taskQueue: 'lt-interceptor',
+    retry: { maximumAttempts: 3 },
+});
+exports.ltEnrichEscalationRouting = ltEnrichEscalationRouting;
+exports.MAX_TOOL_ROUNDS = defaults_1.TOOL_ROUNDS_TRIAGE;
+/** Proxied activity refs passed to response handlers */
+exports.responseDeps = {
+    ltCreateEscalation,
+    ltCreateTask,
+    ltGetTask,
+    ltGetWorkflowConfig,
+    ltStartWorkflow,
+    notifyEngineering,
+};

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

@@ -1,69 +1,11 @@
 "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.mcpTriage = mcpTriage;
 const hotmesh_1 = require("@hotmeshio/hotmesh");
-const defaults_1 = require("../../../modules/defaults");
-const activities = __importStar(require("../../activities/triage"));
-const interceptorActivities = __importStar(require("../../../services/interceptor/activities"));
 const prompts_1 = require("./prompts");
 const response_1 = require("./response");
 const tool_result_guard_1 = require("../tool-result-guard");
-const { getUpstreamTasks, getEscalationHistory, getToolTags, loadTriageTools, callTriageTool, callTriageLLM, notifyEngineering, } = hotmesh_1.Durable.workflow.proxyActivities({
-    activities,
-    retry: {
-        maximumAttempts: 3,
-        backoffCoefficient: 2,
-        maximumInterval: '10 seconds',
-    },
-});
-const { ltCreateEscalation, ltCreateTask, ltGetTask, ltGetWorkflowConfig, ltStartWorkflow, ltEnrichEscalationRouting, } = hotmesh_1.Durable.workflow.proxyActivities({
-    activities: interceptorActivities,
-    taskQueue: 'lt-interceptor',
-    retry: { maximumAttempts: 3 },
-});
-const MAX_TOOL_ROUNDS = defaults_1.TOOL_ROUNDS_TRIAGE;
-/** Proxied activity refs passed to response handlers */
-const responseDeps = {
-    ltCreateEscalation,
-    ltCreateTask,
-    ltGetTask,
-    ltGetWorkflowConfig,
-    ltStartWorkflow,
-    notifyEngineering,
-};
+const activities_proxy_1 = require("./activities-proxy");
 // ── Workflow ─────────────────────────────────────────────────
 /**
  * MCP Triage workflow (leaf).
@@ -95,7 +37,7 @@ const responseDeps = {
  *   3. Returns `{ correctedData }` or re-escalates
  */
 async function mcpTriage(envelope) {
-    const { originId, originalWorkflowType, originalTaskQueue, escalationPayload, resolverPayload, } = envelope.data;
+    const { originId, } = envelope.data;
     // ── Re-entry: engineer responded to our escalation ──
     if (envelope.resolver) {
         const resolver = envelope.resolver;
@@ -104,8 +46,8 @@ async function mcpTriage(envelope) {
         });
     }
     // ── First entry: gather context and let LLM diagnose + fix ──
-    const upstreamTasks = await getUpstreamTasks(originId);
-    const escalationHistory = await getEscalationHistory(originId);
+    const upstreamTasks = await (0, activities_proxy_1.getUpstreamTasks)(originId);
+    const escalationHistory = await (0, activities_proxy_1.getEscalationHistory)(originId);
     const context = buildTriageContext(envelope.data, upstreamTasks, escalationHistory);
     return runTriageLLM(envelope, { additionalContext: context });
 }
@@ -113,11 +55,11 @@ async function mcpTriage(envelope) {
 async function runTriageLLM(envelope, opts) {
     const { originalWorkflowType } = envelope.data;
     // 1. Infer tool tags from the original workflow type (from config cache, no DB hit)
-    const workflowTags = await getToolTags(originalWorkflowType);
+    const workflowTags = await (0, activities_proxy_1.getToolTags)(originalWorkflowType);
     // 2. Load scoped tools with strategy advisor
     //    (Compiled workflow discovery happens in mcpTriageRouter, not here —
     //    this leaf only runs when no compiled match was found.)
-    const raw = await loadTriageTools(workflowTags.length > 0 ? workflowTags : undefined);
+    const raw = await (0, activities_proxy_1.loadTriageTools)(workflowTags.length > 0 ? workflowTags : undefined);
     // 3. Build system prompt with tool inventory
     const toolIds = raw.toolIds;
     const inventoryParts = [
@@ -138,20 +80,20 @@ async function runTriageLLM(envelope, opts) {
     let lastErrorKey = '';
     let repeatedErrorCount = 0;
     const BUDGET_WARNING_THRESHOLD = 3;
-    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
-        const remaining = MAX_TOOL_ROUNDS - round;
+    for (let round = 0; round < activities_proxy_1.MAX_TOOL_ROUNDS; round++) {
+        const remaining = activities_proxy_1.MAX_TOOL_ROUNDS - round;
         // Inject budget warning when approaching the limit
-        if (remaining <= BUDGET_WARNING_THRESHOLD && remaining < MAX_TOOL_ROUNDS) {
+        if (remaining <= BUDGET_WARNING_THRESHOLD && remaining < activities_proxy_1.MAX_TOOL_ROUNDS) {
             messages.push({
                 role: 'user',
                 content: `[Rounds: ${remaining} remaining] Wrap up: consolidate your diagnosis and return your final JSON response.`,
             });
         }
         // Only lightweight toolIds (string[]) flow through the durable pipe
-        const response = await callTriageLLM(messages, toolIds);
+        const response = await (0, activities_proxy_1.callTriageLLM)(messages, toolIds);
         // No tool calls — LLM has produced its final answer
         if (!response.tool_calls?.length) {
-            return (0, response_1.handleFinalResponse)(response.content || '', envelope, toolCallCount, responseDeps);
+            return (0, response_1.handleFinalResponse)(response.content || '', envelope, toolCallCount, activities_proxy_1.responseDeps);
         }
         // Execute each tool call
         const fnCalls = response.tool_calls.filter((tc) => tc.type === 'function');
@@ -171,12 +113,12 @@ async function runTriageLLM(envelope, opts) {
                 args = {};
             }
             // callTool returns errors as data so the LLM can adapt
-            const result = await callTriageTool(toolCall.function.name, args);
+            const result = await (0, activities_proxy_1.callTriageTool)(toolCall.function.name, args);
             // Durable waitFor: if the tool returns a signal, pause until human responds
             if (result?.type === 'waitFor' && result?.signalId) {
                 const ctx = hotmesh_1.Durable.workflow.workflowInfo();
                 const workflowType = ctx.workflowTopic.replace(`${ctx.taskQueue}-`, '');
-                await ltEnrichEscalationRouting({
+                await (0, activities_proxy_1.ltEnrichEscalationRouting)({
                     escalationId: result.escalationId,
                     signalRouting: {
                         taskQueue: ctx.taskQueue,
@@ -217,8 +159,8 @@ async function runTriageLLM(envelope, opts) {
                         role: 'user',
                         content: `[CIRCUIT BREAKER] The tool "${toolCall.function.name}" has returned the same error ${repeatedErrorCount} times. Stop retrying this tool. Summarize your diagnosis and what failed.`,
                     });
-                    const bailResponse = await callTriageLLM(messages, undefined);
-                    return (0, response_1.handleFinalResponse)(bailResponse.content || '', envelope, toolCallCount, responseDeps);
+                    const bailResponse = await (0, activities_proxy_1.callTriageLLM)(messages, undefined);
+                    return (0, response_1.handleFinalResponse)(bailResponse.content || '', envelope, toolCallCount, activities_proxy_1.responseDeps);
                 }
             }
         }
@@ -232,8 +174,8 @@ async function runTriageLLM(envelope, opts) {
         role: 'user',
         content: prompts_1.TRIAGE_EXHAUSTED_ROUNDS,
     });
-    const finalResponse = await callTriageLLM(messages, undefined);
-    return (0, response_1.handleFinalResponse)(finalResponse.content || '', envelope, toolCallCount, responseDeps);
+    const finalResponse = await (0, activities_proxy_1.callTriageLLM)(messages, undefined);
+    return (0, response_1.handleFinalResponse)(finalResponse.content || '', envelope, toolCallCount, activities_proxy_1.responseDeps);
 }
 // ── Context builders ─────────────────────────────────────────────
 /** Assemble the triage context string from workflow lineage and history. */

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

@@ -4,5 +4,5 @@
  * 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 function BUILDER_SYSTEM_PROMPT(toolInventory: string, activitySuffix?: 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

@@ -8,7 +8,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.REFINE_PROMPT = void 0;
 exports.BUILDER_SYSTEM_PROMPT = BUILDER_SYSTEM_PROMPT;
-function BUILDER_SYSTEM_PROMPT(toolInventory) {
+function BUILDER_SYSTEM_PROMPT(toolInventory, activitySuffix) {
+    const suffix = activitySuffix || Math.random().toString(36).slice(2, 6);
     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.
@@ -45,7 +46,7 @@ app:
 ### trigger
 Entry point. Receives user input. Always the first activity.
 \`\`\`yaml
-trigger_x8kf:
+trigger_${suffix}:
   title: Trigger
   type: trigger
   output:
@@ -56,7 +57,7 @@ trigger_x8kf:
 ### worker
 Executes an MCP tool. Receives data via input.maps, produces output. Same suffix as the trigger.
 \`\`\`yaml
-capture_x8kf:
+capture_${suffix}:
   title: Capture Page
   type: worker
   topic: <same as subscribes>
@@ -64,10 +65,10 @@ capture_x8kf:
     schema:
       type: object
     maps:
-      url: '{trigger_x8kf.output.data.url}'
+      url: '{trigger_${suffix}.output.data.url}'
       screenshot_path:
         '@pipe':
-          - ['{trigger_x8kf.output.data.slug}', '.png']
+          - ['{trigger_${suffix}.output.data.slug}', '.png']
           - ['{@string.concat}']
       workflowName: capture_page
   output:
@@ -150,7 +151,7 @@ Sub-pipes must be ROW-LEVEL entries in the parent pipe array — each is a separ
 dated_key:
   '@pipe':
     - '@pipe':
-      - ['{trigger_x8kf.output.data.slug}', '-']
+      - ['{trigger_${suffix}.output.data.slug}', '-']
       - ['{@string.concat}']
     - '@pipe':
       - ['{@date.now}']
@@ -168,7 +169,7 @@ CRITICAL RULES for nested @pipe:
 path:
   '@pipe':
     - '@pipe':
-      - ['{trigger_x8kf.output.data.domain}', '/', '{trigger_x8kf.output.data.key}', '/']
+      - ['{trigger_${suffix}.output.data.domain}', '/', '{trigger_${suffix}.output.data.key}', '/']
       - ['{@string.concat}']
     - '@pipe':
       - ['{@date.now}']
@@ -203,29 +204,29 @@ 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. **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.
+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_${suffix}\`, \`capture_${suffix}\`, \`analyze_${suffix}\`, \`store_${suffix}\`. 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. **mcp_server_id**: In the activity_manifest, use the exact hyphenated server name from the inventory (e.g., "long-tail-vision"), NOT the underscored tool prefix (e.g., "long_tail_vision")
-6. **_scope threading**: Every worker MUST have \`_scope: '{trigger_x8kf.output.data._scope}'\` (using YOUR trigger's ID) for IAM context
+6. **_scope threading**: Every worker MUST have \`_scope: '{trigger_${suffix}.output.data._scope}'\` (using YOUR trigger's ID) for IAM context
 7. **Wire outputs forward**: Use \`{prevActivity.output.data.fieldName}\` to pass data between steps
 8. **Use @pipe for transforms**: When a value needs runtime computation (date stamp, string concat, slugify), use @pipe — never hardcode computed values
-9. **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. **Simple fields stay simple**: If a field just passes a trigger value through (domain, key, url), use a plain reference like \`'{trigger_${suffix}.output.data.domain}'\` — NEVER wrap it in @pipe. Only use @pipe when actual transformation is needed.
 10. **File extensions**: Screenshot paths MUST include .png extension. Use @pipe concat if deriving from a slug
 11. **job.maps on last activity**: The final activity should have job.maps to promote output fields to the workflow result
 12. **Linear transitions**: Chain activities with transitions unless branching or iteration is needed
 13. **Conditional transitions**: For branching, use multi-target transitions with conditions:
 \`\`\`yaml
 transitions:
-  check_x8kf:
-    - to: handle_error_x8kf
+  check_${suffix}:
+    - to: handle_error_${suffix}
       conditions:
         code: 500
-    - to: proceed_x8kf
+    - to: proceed_${suffix}
 \`\`\`
 Conditions can match on \`code\` (HTTP status) or \`match\` (field comparisons). The first matching condition wins; the last entry (no conditions) is the default.
 14. **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:
+trigger_${suffix}:
   type: trigger
   stats:
     id: '{$self.input.data.workflowId}'
@@ -234,11 +235,11 @@ trigger_x8kf:
 
 ## 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:
+Along with the YAML, produce an activity_manifest array describing each activity. Note how all activity IDs share the same random suffix (\`_${suffix}\`) for collision-proofing while remaining human-readable:
 \`\`\`json
 [
   {
-    "activity_id": "trigger_x8kf",
+    "activity_id": "trigger_${suffix}",
     "title": "Trigger",
     "type": "trigger",
     "tool_source": "trigger",
@@ -247,7 +248,7 @@ Along with the YAML, produce an activity_manifest array describing each activity
     "output_fields": ["url", "slug"]
   },
   {
-    "activity_id": "capture_x8kf",
+    "activity_id": "capture_${suffix}",
     "title": "Capture Page",
     "type": "worker",
     "tool_source": "mcp",
@@ -256,7 +257,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": "{trigger_x8kf.output.data.url}" },
+    "input_mappings": { "url": "{trigger_${suffix}.output.data.url}" },
     "output_fields": ["page_id", "path", "url", "title"]
   }
 ]
@@ -290,11 +291,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.
+CRITICAL: The "name" field MUST match the "subscribes" topic in the YAML exactly. Use snake_case (e.g. "screenshot_analyze_store", "capture_page", "daily_report"). Only lowercase letters, digits, and underscores. The name and subscribes topic MUST be identical.
 
 Return a JSON object (no markdown fences):
 {
-  "name": "screenshot.analyze.store",
+  "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/persist.d.ts

@@ -3,7 +3,7 @@
  * 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 declare function persistPlan(setId: string, planItems: PlanItem[], namespaces?: string[]): Promise<void>;
 export interface BuiltWorkflowData {
     name: string;
     description: string;
@@ -13,6 +13,7 @@ export interface BuiltWorkflowData {
     activity_manifest: unknown[];
     tags: string[];
     graph_topic: string;
+    original_prompt?: string;
 }
 export declare function persistBuiltWorkflow(setId: string, planItem: PlanItem, builderOutput: BuiltWorkflowData): Promise<string>;
 export declare function updateSetStatus(setId: string, status: LTWorkflowSetStatus): Promise<void>;

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

@@ -12,9 +12,9 @@ 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 persistPlan(setId, planItems, namespaces) {
+    const ns = namespaces || [...new Set(planItems.map(w => w.namespace))];
+    await (0, workflow_sets_1.updateWorkflowSetPlan)(setId, planItems, ns);
 }
 async function persistBuiltWorkflow(setId, planItem, builderOutput) {
     const input = {
@@ -28,6 +28,7 @@ async function persistBuiltWorkflow(setId, planItem, builderOutput) {
         activity_manifest: builderOutput.activity_manifest,
         tags: builderOutput.tags || [],
         source_workflow_type: 'mcpWorkflowPlanner',
+        original_prompt: builderOutput.original_prompt,
         set_id: setId,
         set_role: planItem.role,
         set_build_order: planItem.build_order,

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

@@ -51,14 +51,48 @@ const { generatePlan, persistPlan, persistBuiltWorkflow, updateSetStatus, deploy
  * and deploys the resulting set.
  */
 async function mcpWorkflowPlanner(envelope) {
-    const { specification, setId } = envelope.data;
+    const { specification, setId, existingPlan, existingSchemas, } = envelope.data;
+    const isAddition = !!existingPlan?.length;
     // 1. Generate plan from specification
-    const planResult = await generatePlan(specification);
-    // 2. Persist the plan to the workflow set
-    await persistPlan(setId, planResult.workflows);
+    // When adding to an existing set, tell the planner what already exists
+    let planSpec = specification;
+    if (isAddition) {
+        const existingNames = existingPlan.map(p => `- ${p.name} [${p.namespace}]: ${p.description}`).join('\n');
+        const namespaces = [...new Set(existingPlan.map(p => p.namespace))];
+        planSpec = `${specification}\n\n## Existing workflows in this set (do NOT recreate these):\n${existingNames}\n\n## Namespace constraint\nNew workflows MUST use namespace "${namespaces[0]}". This set already uses this namespace and all tools must be co-located.`;
+    }
+    const planResult = await generatePlan(planSpec);
+    // 2. Offset build_order for additions so new items sort after existing ones
+    const buildOrderOffset = isAddition
+        ? Math.max(...existingPlan.map((_, i) => i), 0) + 1
+        : 0;
+    if (isAddition) {
+        for (const item of planResult.workflows) {
+            item.build_order += buildOrderOffset;
+        }
+    }
+    // 2b. Persist plan — append to existing plan for additions
+    if (isAddition) {
+        // Fetch current plan from the set and merge
+        const { getWorkflowSet } = await Promise.resolve().then(() => __importStar(require('../../../services/workflow-sets')));
+        const currentSet = await getWorkflowSet(setId);
+        const mergedPlan = [...(currentSet?.plan || []), ...planResult.workflows];
+        const mergedNamespaces = [...new Set([
+                ...(currentSet?.namespaces || []),
+                ...planResult.workflows.map(w => w.namespace),
+            ])];
+        await persistPlan(setId, mergedPlan, mergedNamespaces);
+    }
+    else {
+        await persistPlan(setId, planResult.workflows);
+    }
     // 3. Build each workflow in dependency order (leaf-first)
     await updateSetStatus(setId, 'building');
-    const builtWorkflows = [];
+    // Seed sibling schemas with existing workflows when adding to a set
+    const builtWorkflows = (existingSchemas || []).map(s => ({
+        ...s,
+        id: '',
+    }));
     for (const planItem of planResult.workflows) {
         // Build context for the builder: sibling schemas for composition wiring
         const siblingSchemas = builtWorkflows.map(w => ({
@@ -87,6 +121,7 @@ async function mcpWorkflowPlanner(envelope) {
             taskQueue: 'long-tail-system',
         });
         const builderData = builderResult.data;
+        const builderPrompt = buildPromptForPlanItem(planItem, siblingSchemas);
         // Persist the built workflow with set membership
         const yamlId = await persistBuiltWorkflow(setId, planItem, {
             name: builderData.name || planItem.name,
@@ -97,6 +132,7 @@ async function mcpWorkflowPlanner(envelope) {
             activity_manifest: builderData.activity_manifest || [],
             tags: builderData.tags || [],
             graph_topic: builderData.name || planItem.name,
+            original_prompt: builderPrompt,
         });
         builtWorkflows.push({
             name: planItem.name,

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

@@ -4,4 +4,4 @@
  * 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)";
+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\": \"snake_case_plan_name\",\n  \"plan_description\": \"What this set of workflows accomplishes\",\n  \"workflows\": [\n    {\n      \"name\": \"snake_case_workflow_name\",\n      \"description\": \"What this workflow does \u2014 specific enough to build from\",\n      \"namespace\": \"appnamespace\",\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)";

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

@@ -40,13 +40,13 @@ Each workflow has a typed input and output contract (JSON Schema). Composition w
 
 Return a JSON object (no markdown fences):
 {
-  "plan_name": "kebab-case-plan-name",
+  "plan_name": "snake_case_plan_name",
   "plan_description": "What this set of workflows accomplishes",
   "workflows": [
     {
-      "name": "kebab-case-workflow-name",
+      "name": "snake_case_workflow_name",
       "description": "What this workflow does — specific enough to build from",
-      "namespace": "the-app-namespace",
+      "namespace": "appnamespace",
       "role": "leaf" | "composition" | "router",
       "dependencies": ["name-of-workflow-this-depends-on"],
       "build_order": 0,