@hotmeshio/long-tail 0.1.6 → 0.1.8

package/build/services/yaml-workflow/sql.js

@@ -1,15 +1,20 @@
 "use strict";
 // ─── YAML workflow CRUD ─────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FIND_BY_TAGS_ALL = exports.FIND_BY_TAGS_ANY = exports.GET_CRON_SCHEDULED_WORKFLOWS = exports.CLEAR_CRON_SCHEDULE = exports.UPDATE_CRON_SCHEDULE = exports.UPDATE_STATUS_SUFFIX = exports.UPDATE_STATUS_BASE = exports.GET_VERSION_SNAPSHOT = exports.DISCOVER_WORKFLOWS = exports.LIST_VERSIONS = exports.COUNT_VERSIONS = exports.CREATE_VERSION_SNAPSHOT = exports.MARK_APP_ID_CONTENT_DEPLOYED = exports.MARK_CONTENT_DEPLOYED = exports.GET_DISTINCT_APP_IDS = exports.LIST_BY_APP_ID = exports.GET_ACTIVE_YAML_WORKFLOWS = exports.DELETE_YAML_WORKFLOW = exports.UPDATE_YAML_WORKFLOW_VERSION = exports.GET_YAML_WORKFLOW_BY_NAME = exports.GET_YAML_WORKFLOW = exports.CREATE_YAML_WORKFLOW = void 0;
+exports.FIND_BY_TAGS_ALL = exports.FIND_BY_TAGS_ANY = exports.GET_CRON_SCHEDULED_WORKFLOWS = exports.CLEAR_CRON_SCHEDULE = exports.UPDATE_CRON_SCHEDULE = exports.UPDATE_STATUS_SUFFIX = exports.UPDATE_STATUS_BASE = exports.GET_VERSION_SNAPSHOT = exports.DISCOVER_WORKFLOWS = exports.LIST_VERSIONS = exports.COUNT_VERSIONS = exports.CREATE_VERSION_SNAPSHOT = exports.MARK_APP_ID_CONTENT_DEPLOYED = exports.MARK_CONTENT_DEPLOYED = exports.GET_DISTINCT_APP_IDS = exports.LIST_BY_APP_ID = exports.GET_ACTIVE_YAML_WORKFLOWS = exports.DELETE_YAML_WORKFLOW = exports.UPDATE_YAML_WORKFLOW_VERSION = exports.GET_YAML_WORKFLOW_BY_NAME = exports.GET_YAML_WORKFLOW = exports.CHECK_TOPIC_UNIQUE = exports.CREATE_YAML_WORKFLOW = void 0;
 exports.CREATE_YAML_WORKFLOW = `
   INSERT INTO lt_yaml_workflows
     (name, description, app_id, app_version, source_workflow_id,
      source_workflow_type, yaml_content, graph_topic,
      input_schema, output_schema, activity_manifest, input_field_meta,
-     original_prompt, category, tags, metadata, content_version)
-  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, 1)
+     original_prompt, category, tags, metadata, content_version,
+     set_id, set_role, set_build_order)
+  VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, 1, $17, $18, $19)
   RETURNING *`;
+exports.CHECK_TOPIC_UNIQUE = `
+  SELECT id, name FROM lt_yaml_workflows
+  WHERE app_id = $1 AND graph_topic = $2 AND status != 'archived'
+  LIMIT 1`;
 exports.GET_YAML_WORKFLOW = `
   SELECT * FROM lt_yaml_workflows WHERE id = $1`;
 exports.GET_YAML_WORKFLOW_BY_NAME = `

package/build/services/yaml-workflow/types.d.ts

@@ -24,6 +24,9 @@ export interface CreateYamlWorkflowInput {
     category?: string;
     tags?: string[];
     metadata?: Record<string, unknown>;
+    set_id?: string;
+    set_role?: 'leaf' | 'composition' | 'router';
+    set_build_order?: number;
 }
 /** Mutable state accumulated while building the YAML DAG. */
 export interface DagBuilder {

package/build/services/yaml-workflow/workers/callbacks.js

@@ -47,6 +47,8 @@ function compactForLlm(input) {
  */
 function buildLlmCallback(activity) {
     return async (data) => {
+        const wfName = data.data?.workflowName || activity.workflow_name || activity.activity_id;
+        logger_1.loggerRegistry.debug(`[yaml-workflow:worker] entering llm wf=${wfName} argKeys=[${Object.keys(data.data || {}).join(',')}]`);
         const rawInput = (data.data || {});
         const input = compactForLlm(rawInput);
         const template = activity.prompt_template || '';
@@ -98,7 +100,7 @@ function buildLlmCallback(activity) {
         catch {
             result = { response: content };
         }
-        logger_1.loggerRegistry.info(`[yaml-workflow] LLM step completed (model: ${model}, topic: ${activity.topic})`);
+        logger_1.loggerRegistry.debug(`[yaml-workflow:worker] leaving llm wf=${wfName} resultType=${typeof result}`);
         return {
             metadata: { ...data.metadata },
             data: result,
@@ -154,9 +156,12 @@ function buildTransformCallback(activity) {
     if (!spec)
         throw new Error(`Transform activity ${activity.activity_id} missing transform_spec`);
     return async (data) => {
+        const wfName = data.data?.workflowName || activity.workflow_name || activity.activity_id;
+        logger_1.loggerRegistry.debug(`[yaml-workflow:worker] entering transform wf=${wfName} source=${spec.sourceField} target=${spec.targetField} argKeys=[${Object.keys(data.data || {}).join(',')}]`);
         const input = (data.data || {});
         const sourceData = input[spec.sourceField];
         if (!Array.isArray(sourceData)) {
+            logger_1.loggerRegistry.debug(`[yaml-workflow:worker] leaving transform wf=${wfName} passthrough (source not array)`);
             // Pass through non-array data unchanged
             return {
                 metadata: { ...data.metadata },
@@ -194,6 +199,7 @@ function buildTransformCallback(activity) {
         });
         // Return reshaped data alongside any other input fields (session handles, etc.)
         const result = { ...input, [spec.targetField]: reshaped };
+        logger_1.loggerRegistry.debug(`[yaml-workflow:worker] leaving transform wf=${wfName} reshapedCount=${reshaped.length} resultKeys=[${Object.keys(result).join(',')}]`);
         return {
             metadata: { ...data.metadata },
             data: result,

package/build/services/yaml-workflow/workers/register.js

@@ -125,12 +125,15 @@ async function registerWorkersForWorkflow(workflow) {
                 connection: (0, db_1.getConnection)(),
                 retry: defaultRetry,
                 callback: wrap(async (data) => {
+                    const wfName = data.data?.workflowName || activity.workflow_name || toolName;
+                    logger_1.loggerRegistry.debug(`[yaml-workflow:worker] entering db/${toolName} wf=${wfName} argKeys=[${Object.keys(data.data || {}).join(',')}]`);
                     const args = (data.data || {});
                     let mergedArgs = toolArgs ? { ...toolArgs, ...args } : args;
                     delete mergedArgs._scope;
                     delete mergedArgs.workflowName;
                     mergedArgs = await (0, ephemeral_1.exchangeTokensInArgs)(mergedArgs);
                     const result = await mcpClient.callServerTool(dbServerId, toolName, mergedArgs);
+                    logger_1.loggerRegistry.debug(`[yaml-workflow:worker] leaving db/${toolName} wf=${wfName} resultKeys=[${Object.keys(result || {}).join(',')}]`);
                     return { metadata: { ...data.metadata }, data: result };
                 }),
             });
@@ -158,6 +161,8 @@ async function registerWorkersForWorkflow(workflow) {
                 connection: (0, db_1.getConnection)(),
                 retry: defaultRetry,
                 callback: wrap(async (data) => {
+                    const wfName = data.data?.workflowName || activity.workflow_name || toolName;
+                    logger_1.loggerRegistry.debug(`[yaml-workflow:worker] entering mcp/${toolName} wf=${wfName} server=${serverId} argKeys=[${Object.keys(data.data || {}).join(',')}]`);
                     const args = (data.data || {});
                     // Start from stored defaults, then strip any wired keys that
                     // didn't arrive (upstream failure) so stale defaults don't leak.
@@ -173,6 +178,7 @@ async function registerWorkersForWorkflow(workflow) {
                             mergedArgs[key] = value;
                         }
                     }
+                    logger_1.loggerRegistry.debug(`[yaml-workflow:worker] merged mcp/${toolName} wf=${wfName} mergedKeys=[${Object.keys(mergedArgs).join(',')}]`);
                     // For escalate_and_wait: inject YAML signal routing so the MCP tool
                     // stores engine:'yaml' + hookTopic + jobId in the escalation metadata
                     if (yamlHookTopic) {
@@ -195,6 +201,7 @@ async function registerWorkersForWorkflow(workflow) {
                     if (result == null) {
                         logger_1.loggerRegistry.warn(`[yaml-workflow:worker] ${toolName} returned null/undefined`);
                     }
+                    logger_1.loggerRegistry.debug(`[yaml-workflow:worker] leaving mcp/${toolName} wf=${wfName} resultKeys=[${Object.keys(result || {}).join(',')}]`);
                     return { metadata: { ...data.metadata }, data: result };
                 }),
             });

package/build/start/adapters.js

@@ -8,6 +8,7 @@ const honeycomb_1 = require("../lib/telemetry/honeycomb");
 const events_1 = require("../lib/events");
 const nats_1 = require("../lib/events/nats");
 const socketio_1 = require("../lib/events/socketio");
+const callback_1 = require("../lib/events/callback");
 const maintenance_1 = require("../services/maintenance");
 const maintenance_2 = require("../modules/maintenance");
 const mcp_1 = require("../services/mcp");
@@ -47,6 +48,9 @@ function registerAdapters(startConfig) {
         }
         events_1.eventRegistry.register(new socketio_1.SocketIOEventAdapter());
     }
+    // Always register the callback adapter for SDK event subscriptions.
+    // Zero-cost when no listeners are registered.
+    events_1.eventRegistry.register(new callback_1.CallbackEventAdapter());
     // Maintenance
     if (startConfig.maintenance === false) {
         // Disabled

package/build/system/index.js

@@ -83,6 +83,12 @@ function getSystemWorkers() {
             workers.push({ taskQueue: 'long-tail-system', workflow: mcpWorkflowBuilder });
         }
         catch { /* not available */ }
+        // ── Workflow planner (multi-workflow plan mode) ──
+        try {
+            const { mcpWorkflowPlanner } = require('./workflows/mcp-workflow-planner');
+            workers.push({ taskQueue: 'long-tail-system', workflow: mcpWorkflowPlanner });
+        }
+        catch { /* not available */ }
     }
     return workers;
 }

package/build/system/mcp-servers/knowledge.js

@@ -41,7 +41,7 @@ const knowledge = __importStar(require("../activities/knowledge"));
 const storeSchema = zod_1.z.object({
     domain: zod_1.z.string().describe('Knowledge domain (namespace)'),
     key: zod_1.z.string().describe('Unique key within domain'),
-    data: zod_1.z.record(zod_1.z.any()).describe('JSONB payload to store'),
+    data: zod_1.z.record(zod_1.z.any()).describe('JSONB object payload to store (must be an object, not a string — wrap text as { "description": "..." })'),
     tags: zod_1.z.array(zod_1.z.string()).optional().describe('Categorization tags'),
 });
 const getSchema = zod_1.z.object({

package/build/system/seed/server-definitions.js

@@ -183,7 +183,8 @@ exports.SEED_MCP_SERVERS = [
         tool_manifest: tool_manifests_knowledge_1.KNOWLEDGE_TOOLS,
         metadata: { builtin: true, category: 'knowledge' },
         tags: ['knowledge', 'memory', 'state', 'storage'],
-        compile_hints: 'store_knowledge arguments: domain (string), key (string), data (the content to store — NOT "content"), data_key (optional sub-key). ' +
+        compile_hints: 'store_knowledge arguments: domain (string), key (string), data (object — MUST be a JSON object, never a string), tags (optional string[]). ' +
+            'The data field is a JSONB object. When storing text content, wrap it: { "description": "the text" }. NEVER pass a bare string as data. ' +
             'store_knowledge upserts by domain+key — it merges data if the entry exists. ' +
             'Use a consistent domain name across related workflows to build shared context. ' +
             'search_knowledge uses JSONB containment (@>) — the query object must be a subset of the stored data. ' +

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

@@ -1,2 +1,2 @@
-export { loadBuilderTools } from './tool-loader';
+export { loadBuilderTools, loadReferenceSection } from './tool-loader';
 export { callBuilderLLM } from './llm';

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

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.callBuilderLLM = exports.loadBuilderTools = void 0;
+exports.callBuilderLLM = exports.loadReferenceSection = exports.loadBuilderTools = void 0;
 var tool_loader_1 = require("./tool-loader");
 Object.defineProperty(exports, "loadBuilderTools", { enumerable: true, get: function () { return tool_loader_1.loadBuilderTools; } });
+Object.defineProperty(exports, "loadReferenceSection", { enumerable: true, get: function () { return tool_loader_1.loadReferenceSection; } });
 var llm_1 = require("./llm");
 Object.defineProperty(exports, "callBuilderLLM", { enumerable: true, get: function () { return llm_1.callBuilderLLM; } });

package/build/system/workflows/mcp-workflow-builder/activities/tool-loader.d.ts

@@ -3,3 +3,9 @@ export declare function loadBuilderTools(tags?: string[]): Promise<{
     inventory: string;
     strategy: string;
 }>;
+/**
+ * Load a specific section from the activity-types reference file.
+ * Returns the markdown for the requested activity type (await, signal, interrupt).
+ * Returns empty string if the section or file is not found.
+ */
+export declare function loadReferenceSection(section: 'await' | 'signal' | 'interrupt'): Promise<string>;

package/build/system/workflows/mcp-workflow-builder/activities/tool-loader.js

@@ -1,8 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadBuilderTools = loadBuilderTools;
+exports.loadReferenceSection = loadReferenceSection;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
 const tool_loader_1 = require("../../shared/tool-loader");
 const caches_1 = require("./caches");
 async function loadBuilderTools(tags) {
     return (0, tool_loader_1.loadToolsFromServers)(tags, { toolServerMap: caches_1.toolServerMap, toolDefCache: caches_1.toolDefCache }, { logPrefix: 'workflowBuilder' });
 }
+/**
+ * Load a specific section from the activity-types reference file.
+ * Returns the markdown for the requested activity type (await, signal, interrupt).
+ * Returns empty string if the section or file is not found.
+ */
+async function loadReferenceSection(section) {
+    try {
+        const refPath = (0, path_1.join)(__dirname, '..', 'reference', 'activity-types.md');
+        const content = await (0, promises_1.readFile)(refPath, 'utf-8');
+        // Extract the section between ## <name> and the next ## or end of file
+        const sectionHeader = `## ${section}`;
+        const startIdx = content.indexOf(sectionHeader);
+        if (startIdx === -1)
+            return '';
+        const afterHeader = content.indexOf('\n', startIdx);
+        const nextSection = content.indexOf('\n## ', afterHeader + 1);
+        const endIdx = nextSection === -1 ? content.length : nextSection;
+        return content.slice(startIdx, endIdx).trim();
+    }
+    catch {
+        return '';
+    }
+}

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

@@ -37,7 +37,7 @@ exports.mcpWorkflowBuilder = mcpWorkflowBuilder;
 const hotmesh_1 = require("@hotmeshio/hotmesh");
 const activities = __importStar(require("./activities"));
 const prompts_1 = require("./prompts");
-const { loadBuilderTools, callBuilderLLM, } = hotmesh_1.Durable.workflow.proxyActivities({
+const { loadBuilderTools, loadReferenceSection, callBuilderLLM, } = hotmesh_1.Durable.workflow.proxyActivities({
     activities,
     retry: {
         maximumAttempts: 3,
@@ -94,6 +94,7 @@ async function mcpWorkflowBuilder(envelope) {
     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',
@@ -111,10 +112,33 @@ async function mcpWorkflowBuilder(envelope) {
         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)(serverSection),
+            content: (0, prompts_1.BUILDER_SYSTEM_PROMPT)(fullInventory),
         },
     ];
     // If refining a prior attempt, inject context

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