@hotmeshio/long-tail 0.5.0 → 0.5.2

package/README.md

@@ -74,10 +74,12 @@ curl -X PUT http://localhost:3000/api/workflows/reviewContent/config \
 
 **Step 3 — React to events.** Workflows publish topics. Agents subscribe. When `activity.failed` fires, an automation can re-run the step, notify a team, or trigger a different workflow. The choreography is dynamic — add subscribers through the dashboard without changing code.
 
-**Step 4 — Compile what repeats.** The Pipeline Designer takes a working execution and compiles it into a deterministic YAML DAG. No LLM at runtime, no replay overhead, typed inputs and outputs. It deploys as a reusable tool that any workflow or API call can invoke.
+**Step 4 — Compile what repeats.** The same workflow has two forms. What you wrote in Step 1 is the *procedural* form — readable, Temporal-like, emulated atop the graph: cheap to maintain, heavier to run. The Designer compiles a working execution into the *graph* form — the same durable workflow as a deterministic DAG: no LLM at runtime, no replay overhead, typed in and out, roughly 3x faster. Every procedural pattern has a graph equivalent and the reverse; you pick readability or speed without giving up durability, escalation, or transactional guarantees. It deploys as a reusable tool that any workflow or API call can invoke.
 
 Over time, the system accumulates compiled tools. Problems that once required a human, then required AI reasoning, eventually require neither.
 
+These four steps map to how the dashboard is organized. **React** is the reactive side (Step 3) — topics, subscriptions, automations. **Orchestrate** is the orchestrated side (Steps 1 and 4) — procedural and graph flows side by side, both durable and pull-based under the hood. **Design** is the optional bridge: with an `ANTHROPIC_API_KEY` it turns a description or a tool run into a graph flow; without one, choreography and orchestration stand on their own, no tradeoff.
+
 ## Register MCP tools
 
 Long Tail connects to any MCP server. Registered tools become durable activities and are available to the Pipeline Designer.
@@ -145,6 +147,43 @@ npx ltc compile workflows/
 
 The source is the spec. The compiled YAML is the optimized execution. Both live in the repo. See the [Compiler Guide](docs/compiler.md).
 
+## Register a graph flow by hand
+
+`graphWorkflows` is the graph-form peer of `workers`: hand-author the HotMesh YAML and it's created, deployed, and activated at startup. This hello-world assembles a greeting from the input with a single trigger mapping:
+
+```typescript
+const lt = await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  graphWorkflows: [{
+    name: 'hello_world',
+    namespace: 'graph',
+    inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+    yaml: `
+app:
+  id: graph
+  version: '1'
+  graphs:
+    - subscribes: hello_world
+      publishes: hello_world.done
+      input:  { schema: { type: object, properties: { name: { type: string } } } }
+      output: { schema: { type: object, properties: { greeting: { type: string } } } }
+      activities:
+        trigger:
+          type: trigger
+          job:
+            maps:
+              greeting:
+                '@pipe':
+                  - ['Hello, ', '{$self.input.data.name}', '!']
+                  - ['{@string.concat}']
+      transitions: {}
+`,
+  }],
+});
+```
+
+It appears under **Orchestrate › Graph** and runs the same way a procedural workflow does — durable, transactional, invocable from the dashboard or API.
+
 ## Full configuration
 
 ```typescript
@@ -153,6 +192,7 @@ const lt = await start({
   workers: [{ taskQueue: 'default', workflow: reviewContent }],
 
   // Everything below is optional
+  graphWorkflows: [{ name: 'hello_world', namespace: 'graph', yaml: helloWorldYaml }],
   seed: { admin: { externalId: 'admin', password: process.env.ADMIN_PASSWORD } },
   mcp: { server: { enabled: true }, serverFactories: { 'my-tools': createMyToolsServer } },
   escalation: { strategy: 'mcp' },

package/build/adapters/express.d.ts

@@ -59,6 +59,7 @@ export declare class LTExpressAdapter {
     /**
      * Return a self-contained Express Router that serves:
      * - `/api/*` — Long Tail API routes (auth, tasks, escalations, etc.)
+     * - `/mcp` — MCP streamable-HTTP transport (Claude Desktop, Cursor, agents)
      * - `/health` — health check
      * - Static dashboard assets
      * - SPA fallback with injected `<base href>` and `window.__LT_BASE__`

package/build/adapters/express.js

@@ -41,6 +41,7 @@ const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
 const express_1 = __importStar(require("express"));
 const routes_1 = __importDefault(require("../routes"));
+const mcp_endpoint_1 = __importDefault(require("../routes/mcp-endpoint"));
 const events_1 = require("../lib/events");
 const socketio_1 = require("../lib/events/socketio");
 const nats_1 = require("../lib/events/nats");
@@ -134,6 +135,7 @@ class LTExpressAdapter {
     /**
      * Return a self-contained Express Router that serves:
      * - `/api/*` — Long Tail API routes (auth, tasks, escalations, etc.)
+     * - `/mcp` — MCP streamable-HTTP transport (Claude Desktop, Cursor, agents)
      * - `/health` — health check
      * - Static dashboard assets
      * - SPA fallback with injected `<base href>` and `window.__LT_BASE__`
@@ -147,6 +149,8 @@ class LTExpressAdapter {
         });
         // API routes — internal routes handle their own JWT auth
         router.use('/api', routes_1.default);
+        // MCP streamable-HTTP transport — same endpoint as standalone server
+        router.use('/mcp', mcp_endpoint_1.default);
         // Dashboard static assets
         const dashboardDist = this.resolveDashboardDist();
         if (dashboardDist) {

package/build/api/yaml-workflows/crud.d.ts

@@ -76,6 +76,7 @@ export declare function createYamlWorkflowDirect(input: {
     description?: string;
     yaml_content: string;
     input_schema?: any;
+    output_schema?: any;
     activity_manifest?: any[];
     tags?: string[];
     app_id?: string;

package/build/api/yaml-workflows/crud.js

@@ -216,7 +216,7 @@ async function createYamlWorkflow(input) {
  */
 async function createYamlWorkflowDirect(input) {
     try {
-        const { name, description, yaml_content, input_schema, activity_manifest, tags, app_id, graph_topic } = input;
+        const { name, description, yaml_content, input_schema, output_schema, activity_manifest, tags, app_id, graph_topic } = input;
         if (!name || !yaml_content) {
             return { status: 400, error: 'name and yaml_content are required' };
         }
@@ -258,7 +258,7 @@ async function createYamlWorkflowDirect(input) {
             yaml_content: finalYaml,
             graph_topic: graphTopic,
             input_schema: input_schema || {},
-            output_schema: {},
+            output_schema: output_schema || {},
             activity_manifest: normalizeManifestToolNames(activity_manifest) || [],
             tags: tags || [],
             original_prompt: description,

package/build/routes/mcp-endpoint.js

@@ -22,10 +22,8 @@ const logger_1 = require("../lib/logger");
 const external_server_1 = require("../services/mcp/external-server");
 const exposure_1 = require("../services/mcp/exposure");
 const router = (0, express_1.Router)();
-// All MCP endpoint requests require authentication
-router.use(auth_1.requireAuth);
 // POST /mcp — JSON-RPC messages
-router.post('/', async (req, res) => {
+router.post('/', auth_1.requireAuth, async (req, res) => {
     try {
         const exposure = (0, exposure_1.getExposureConfig)();
         const callerScopes = req.auth?.scopes;
@@ -52,7 +50,7 @@ router.post('/', async (req, res) => {
     }
 });
 // GET /mcp — SSE stream (not supported in stateless mode)
-router.get('/', (_req, res) => {
+router.get('/', auth_1.requireAuth, (_req, res) => {
     res.status(405).json({
         jsonrpc: '2.0',
         error: { code: -32000, message: 'Method not allowed. Use POST for stateless requests.' },
@@ -60,7 +58,7 @@ router.get('/', (_req, res) => {
     });
 });
 // DELETE /mcp — session close (not supported in stateless mode)
-router.delete('/', (_req, res) => {
+router.delete('/', auth_1.requireAuth, (_req, res) => {
     res.status(405).json({
         jsonrpc: '2.0',
         error: { code: -32000, message: 'Method not allowed. Stateless mode has no sessions.' },

package/build/services/topics/system-topics.js

@@ -20,7 +20,7 @@ const SYSTEM_TOPICS = [
     // Task lifecycle
     {
         topic: 'system.task.*.created',
-        description: 'A new task has been created and queued for execution.',
+        description: 'A new task has been queued.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string', description: 'Task ID' }, status: STATUS_FIELD, data: { type: 'object', description: 'Task input data' } }),
         example_payload: { taskId: 'tsk-001', status: 'pending', workflowName: 'processOrder' },
@@ -28,7 +28,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.task.*.started',
-        description: 'A task has begun execution.',
+        description: 'A task has started.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD }),
         example_payload: { taskId: 'tsk-001', status: 'running', workflowName: 'processOrder' },
@@ -36,7 +36,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.task.*.completed',
-        description: 'A task has finished successfully.',
+        description: 'A task has finished.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, milestones: { type: 'array', items: { type: 'object' }, description: 'Milestones reported' }, data: { type: 'object', description: 'Task result data' } }),
         example_payload: { taskId: 'tsk-001', status: 'completed', workflowName: 'processOrder' },
@@ -44,7 +44,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.task.*.escalated',
-        description: 'A task has been escalated for human review.',
+        description: 'A task has been escalated.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
         example_payload: { taskId: 'tsk-001', status: 'escalated', workflowName: 'processOrder' },
@@ -52,7 +52,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.task.*.failed',
-        description: 'A task has failed execution.',
+        description: 'A task has failed.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object', description: 'Error details' } }),
         example_payload: { taskId: 'tsk-001', status: 'failed', workflowName: 'processOrder' },
@@ -61,7 +61,7 @@ const SYSTEM_TOPICS = [
     // Workflow lifecycle
     {
         topic: 'system.workflow.*.started',
-        description: 'A workflow execution has started.',
+        description: 'A workflow has started.',
         category: 'workflow',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD }),
         example_payload: { workflowId: 'wf-abc', workflowName: 'processOrder', status: 'running' },
@@ -69,7 +69,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.workflow.*.completed',
-        description: 'A workflow execution has completed successfully.',
+        description: 'A workflow has completed.',
         category: 'workflow',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
         example_payload: { workflowId: 'wf-abc', workflowName: 'processOrder', status: 'completed' },
@@ -77,7 +77,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.workflow.*.failed',
-        description: 'A workflow execution has failed.',
+        description: 'A workflow has failed.',
         category: 'workflow',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object', description: 'Error details' } }),
         example_payload: { workflowId: 'wf-abc', workflowName: 'processOrder', status: 'failed' },
@@ -86,7 +86,7 @@ const SYSTEM_TOPICS = [
     // Escalation lifecycle
     {
         topic: 'system.escalation.*.created',
-        description: 'A new escalation has been created for human review.',
+        description: 'An escalation has been created.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
         example_payload: { escalationId: 'esc-001', status: 'pending', workflowName: 'processOrder' },
@@ -94,7 +94,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.escalation.*.resolved',
-        description: 'An escalation has been resolved by a human operator.',
+        description: 'An escalation has been resolved.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
         example_payload: { escalationId: 'esc-001', status: 'resolved', workflowName: 'processOrder' },
@@ -102,7 +102,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.escalation.*.claimed',
-        description: 'An escalation has been claimed by an operator.',
+        description: 'An escalation has been claimed.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
         example_payload: { escalationId: 'esc-001', status: 'claimed' },
@@ -110,7 +110,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.escalation.*.released',
-        description: 'An escalation has been released back to the queue.',
+        description: 'An escalation has been returned to the queue.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
         example_payload: { escalationId: 'esc-001', status: 'pending' },
@@ -119,32 +119,32 @@ const SYSTEM_TOPICS = [
     // Activity lifecycle
     {
         topic: 'system.activity.*.*.started',
-        description: 'A YAML workflow activity step has started.',
+        description: 'A workflow activity has started.',
         category: 'activity',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, activityName: { type: 'string', description: 'Activity step name' } }),
         example_payload: { workflowId: 'wf-abc', activityName: 'fetchOrder', workflowName: 'processOrder' },
-        tags: ['lifecycle', 'yaml'],
+        tags: ['lifecycle', 'graph'],
     },
     {
         topic: 'system.activity.*.*.completed',
-        description: 'A YAML workflow activity step has completed.',
+        description: 'A workflow activity has completed.',
         category: 'activity',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, activityName: { type: 'string' }, data: { type: 'object' } }),
         example_payload: { workflowId: 'wf-abc', activityName: 'fetchOrder', workflowName: 'processOrder' },
-        tags: ['lifecycle', 'yaml'],
+        tags: ['lifecycle', 'graph'],
     },
     {
         topic: 'system.activity.*.*.failed',
-        description: 'A YAML workflow activity step has failed.',
+        description: 'A workflow activity has failed.',
         category: 'activity',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, activityName: { type: 'string' }, data: { type: 'object', description: 'Error details' } }),
         example_payload: { workflowId: 'wf-abc', activityName: 'fetchOrder', workflowName: 'processOrder' },
-        tags: ['lifecycle', 'yaml', 'error'],
+        tags: ['lifecycle', 'graph', 'error'],
     },
     // Knowledge lifecycle
     {
         topic: 'system.knowledge.*.stored',
-        description: 'A knowledge entry has been written to the knowledge store.',
+        description: 'A knowledge entry has been saved.',
         category: 'knowledge',
         payload_schema: objectSchema({ domain: { type: 'string', description: 'Knowledge domain' }, key: { type: 'string', description: 'Knowledge entry key' } }),
         example_payload: { domain: 'orders', key: 'order-12345' },
@@ -152,7 +152,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.knowledge.*.deleted',
-        description: 'A knowledge entry has been removed from the knowledge store.',
+        description: 'A knowledge entry has been deleted.',
         category: 'knowledge',
         payload_schema: objectSchema({ domain: { type: 'string', description: 'Knowledge domain' }, key: { type: 'string', description: 'Knowledge entry key' } }),
         example_payload: { domain: 'orders', key: 'order-12345' },
@@ -161,7 +161,7 @@ const SYSTEM_TOPICS = [
     // File storage
     {
         topic: 'system.file.stored',
-        description: 'A file has been written to storage.',
+        description: 'A file has been saved to storage.',
         category: 'file',
         payload_schema: objectSchema({
             path: { type: 'string', description: 'File path in storage' },
@@ -176,7 +176,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.file.deleted',
-        description: 'A file has been removed from storage.',
+        description: 'A file has been deleted from storage.',
         category: 'file',
         payload_schema: objectSchema({
             path: { type: 'string', description: 'File path in storage' },
@@ -190,7 +190,7 @@ const SYSTEM_TOPICS = [
     // Agent lifecycle
     {
         topic: 'system.agent.*.started',
-        description: 'An agent reaction workflow has started in response to an event.',
+        description: 'An agent automation has started in response to an event.',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string', description: 'Agent ID' }, agentName: { type: 'string', description: 'Agent name' }, status: STATUS_FIELD, data: { type: 'object', description: 'Trigger context' } }),
         example_payload: { agentId: 'agt-001', agentName: 'error-handler', status: 'running' },
@@ -198,7 +198,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.agent.*.completed',
-        description: 'An agent reaction workflow has completed successfully.',
+        description: 'An agent automation has completed.',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string' }, agentName: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
         example_payload: { agentId: 'agt-001', agentName: 'error-handler', status: 'completed' },
@@ -206,7 +206,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.agent.*.failed',
-        description: 'An agent reaction workflow has failed.',
+        description: 'An agent automation has failed.',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string' }, agentName: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object', description: 'Error details' } }),
         example_payload: { agentId: 'agt-001', agentName: 'error-handler', status: 'failed' },
@@ -214,7 +214,7 @@ const SYSTEM_TOPICS = [
     },
     {
         topic: 'system.agent.*.status_changed',
-        description: 'An agent\'s status has changed (activated, paused, errored).',
+        description: 'An agent automation\'s status has changed.',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string' }, agentName: { type: 'string' }, status: STATUS_FIELD }),
         example_payload: { agentId: 'agt-001', agentName: 'error-handler', status: 'active' },
@@ -223,7 +223,7 @@ const SYSTEM_TOPICS = [
     // Milestone
     {
         topic: 'system.milestone.*',
-        description: 'A workflow or activity has reported progress milestones.',
+        description: 'A workflow or workflow activity has reported progress.',
         category: 'milestone',
         payload_schema: objectSchema({
             ...WORKFLOW_CONTEXT_PROPS,

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

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.invokeYamlWorkflow = invokeYamlWorkflow;
 const yamlDeployer = __importStar(require("./deployer"));
 const principal_1 = require("../iam/principal");
+const publish_1 = require("../../lib/events/publish");
 /**
  * Invoke a YAML workflow with scope injection.
  * Shared by HTTP route and cron callback.
@@ -71,14 +72,84 @@ async function invokeYamlWorkflow(wf, options = {}) {
             data._metadata = {};
         data._metadata.source = options.source;
     }
-    // Build context with deterministic job ID when provided (agent subscriptions)
-    const context = options.jobId
-        ? { metadata: { jid: options.jobId } }
-        : undefined;
+    const wfMeta = {
+        workflowName: wf.graph_topic,
+        taskQueue: wf.app_id,
+    };
     if (options.sync) {
-        const { job_id, result } = await yamlDeployer.invokeYamlWorkflowSync(wf.app_id, wf.graph_topic, data, options.timeout, wf.graph_topic);
-        return { job_id, result };
+        (0, publish_1.publishWorkflowEvent)({
+            type: 'workflow.started',
+            source: 'graph',
+            workflowId: options.jobId || wf.graph_topic,
+            ...wfMeta,
+            status: 'running',
+        });
+        try {
+            const { job_id, result } = await yamlDeployer.invokeYamlWorkflowSync(wf.app_id, wf.graph_topic, data, options.timeout, wf.graph_topic);
+            (0, publish_1.publishWorkflowEvent)({
+                type: 'workflow.completed',
+                source: 'graph',
+                workflowId: job_id,
+                ...wfMeta,
+                status: 'completed',
+                data: typeof result === 'object' && result !== null ? result : undefined,
+            });
+            return { job_id, result };
+        }
+        catch (err) {
+            (0, publish_1.publishWorkflowEvent)({
+                type: 'workflow.failed',
+                source: 'graph',
+                workflowId: options.jobId || wf.graph_topic,
+                ...wfMeta,
+                status: 'failed',
+                data: { error: err?.message ?? String(err) },
+            });
+            throw err;
+        }
     }
+    // Async path — include ngn so HotMesh routes the completion reply back to
+    // this engine instance, enabling fire-and-forget lifecycle event tracking.
+    const engine = await yamlDeployer.getEngine(wf.app_id);
+    const internalEngine = engine.engine;
+    const ngn = internalEngine?.guid;
+    const context = (options.jobId || ngn)
+        ? {
+            metadata: {
+                ...(options.jobId ? { jid: options.jobId } : {}),
+                ...(ngn ? { ngn } : {}),
+            },
+        }
+        : undefined;
     const jobId = await yamlDeployer.invokeYamlWorkflow(wf.app_id, wf.graph_topic, data, wf.graph_topic, context);
+    (0, publish_1.publishWorkflowEvent)({
+        type: 'workflow.started',
+        source: 'graph',
+        workflowId: jobId,
+        ...wfMeta,
+        status: 'running',
+    });
+    // Register a best-effort completion callback. Fires when HotMesh routes the
+    // job reply back to this engine (requires ngn set above). Cleans itself up
+    // after 5 minutes regardless so there is no unbounded callback accumulation.
+    if (ngn && internalEngine?.registerJobCallback) {
+        const timeoutMs = 5 * 60_000;
+        const timer = setTimeout(() => internalEngine.delistJobCallback?.(jobId), timeoutMs);
+        internalEngine.registerJobCallback(jobId, (_topic, output) => {
+            clearTimeout(timer);
+            internalEngine.delistJobCallback?.(jobId);
+            const failed = !!output?.metadata?.err;
+            (0, publish_1.publishWorkflowEvent)({
+                type: failed ? 'workflow.failed' : 'workflow.completed',
+                source: 'graph',
+                workflowId: jobId,
+                ...wfMeta,
+                status: failed ? 'failed' : 'completed',
+                data: failed
+                    ? { error: output.metadata.err }
+                    : (output?.data && typeof output.data === 'object' ? output.data : undefined),
+            });
+        });
+    }
     return { job_id: jobId };
 }

package/build/start/graph-workflows.d.ts

@@ -0,0 +1,14 @@
+import type { LTGraphWorkflowConfig } from '../types/startup';
+/**
+ * Register declarative graph (YAML/DAG) workflows at startup — the graph-form
+ * peer of durable `workers`. Each flow is created insert-if-absent, then
+ * deployed + activated through the same path the dashboard uses.
+ *
+ * On a re-boot where the flow already exists:
+ *   - description and output_schema are synced if stale
+ *   - when the YAML version bumps, yaml_content is updated and the flow is redeployed
+ *
+ * Per-flow failures are logged and skipped so a single malformed flow can never
+ * block boot.
+ */
+export declare function seedGraphWorkflows(configs: LTGraphWorkflowConfig[]): Promise<void>;

package/build/start/graph-workflows.js

@@ -0,0 +1,126 @@
+"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.seedGraphWorkflows = seedGraphWorkflows;
+const logger_1 = require("../lib/logger");
+const utils_1 = require("../modules/utils");
+function extractYamlVersion(yaml) {
+    const m = yaml.match(/^\s*version:\s*['"]?(\S+?)['"]?\s*$/m);
+    return m?.[1] ?? '0';
+}
+/**
+ * Register declarative graph (YAML/DAG) workflows at startup — the graph-form
+ * peer of durable `workers`. Each flow is created insert-if-absent, then
+ * deployed + activated through the same path the dashboard uses.
+ *
+ * On a re-boot where the flow already exists:
+ *   - description and output_schema are synced if stale
+ *   - when the YAML version bumps, yaml_content is updated and the flow is redeployed
+ *
+ * Per-flow failures are logged and skipped so a single malformed flow can never
+ * block boot.
+ */
+async function seedGraphWorkflows(configs) {
+    const { createYamlWorkflowDirect, listYamlWorkflows, updateYamlWorkflow } = await Promise.resolve().then(() => __importStar(require('../api/yaml-workflows/crud')));
+    const { deployYamlWorkflow } = await Promise.resolve().then(() => __importStar(require('../api/yaml-workflows/deploy')));
+    for (const gf of configs) {
+        const namespace = (0, utils_1.sanitizeServerName)(gf.namespace ?? 'graph');
+        const graphTopic = (0, utils_1.sanitizeToolName)(gf.name);
+        try {
+            const created = await createYamlWorkflowDirect({
+                name: gf.name,
+                description: gf.description,
+                yaml_content: gf.yaml,
+                input_schema: gf.inputSchema,
+                output_schema: gf.outputSchema,
+                app_id: namespace,
+                tags: gf.tags,
+            });
+            if (created.status === 409) {
+                // Flow already exists — sync stale fields and redeploy if YAML version bumped.
+                const listing = await listYamlWorkflows({ app_id: namespace, graph_topic: graphTopic, limit: 1 });
+                const match = listing.data?.workflows?.[0];
+                if (match) {
+                    const updates = {};
+                    if (gf.description && match.description !== gf.description)
+                        updates.description = gf.description;
+                    if (gf.outputSchema)
+                        updates.output_schema = gf.outputSchema;
+                    if (gf.inputSchema)
+                        updates.input_schema = gf.inputSchema;
+                    const storedVersion = extractYamlVersion(match.yaml_content ?? '');
+                    const newVersion = extractYamlVersion(gf.yaml);
+                    const yamlChanged = newVersion !== storedVersion;
+                    if (yamlChanged) {
+                        updates.yaml_content = gf.yaml;
+                    }
+                    if (Object.keys(updates).length > 0) {
+                        await updateYamlWorkflow({ id: match.id, ...updates });
+                        logger_1.loggerRegistry.info(`[long-tail] graph flow updated: ${gf.name}`);
+                    }
+                    if (yamlChanged) {
+                        const deployed = await deployYamlWorkflow({ id: match.id });
+                        if (deployed.status !== 200) {
+                            logger_1.loggerRegistry.warn(`[long-tail] graph flow redeploy failed for ${gf.name}: ${deployed.error ?? 'unknown error'}`);
+                        }
+                        else {
+                            logger_1.loggerRegistry.info(`[long-tail] graph flow redeployed: ${gf.name} (v${newVersion})`);
+                        }
+                    }
+                    else {
+                        logger_1.loggerRegistry.info(`[long-tail] graph flow already registered: ${gf.name}`);
+                    }
+                }
+                else {
+                    logger_1.loggerRegistry.info(`[long-tail] graph flow already registered: ${gf.name}`);
+                }
+                continue;
+            }
+            if (created.status !== 200 || !created.data?.id) {
+                logger_1.loggerRegistry.warn(`[long-tail] graph flow create failed for ${gf.name}: ${created.error ?? 'unknown error'}`);
+                continue;
+            }
+            const deployed = await deployYamlWorkflow({ id: created.data.id });
+            if (deployed.status !== 200) {
+                logger_1.loggerRegistry.warn(`[long-tail] graph flow deploy failed for ${gf.name}: ${deployed.error ?? 'unknown error'}`);
+                continue;
+            }
+            logger_1.loggerRegistry.info(`[long-tail] graph flow registered + deployed: ${gf.name} (namespace: ${namespace})`);
+        }
+        catch (err) {
+            logger_1.loggerRegistry.warn(`[long-tail] graph flow seed error for ${gf.name}: ${err.message}`);
+        }
+    }
+}

package/build/start/workers.js

@@ -238,6 +238,20 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
         }
         // 3. Clean stale builtin servers no longer in factory list
         await cleanStaleBuiltinServers(Object.keys(allFactories));
+        // Seed static graph (YAML/DAG) workflows — the graph-form peer of `workers`.
+        // Hand-authored flows from config, plus the hello-world example when enabled.
+        // Runs before worker registration so newly-deployed flows are picked up.
+        if (!isReadonly) {
+            const graphFlows = [...(startConfig.graphWorkflows ?? [])];
+            if (startConfig.examples) {
+                const { EXAMPLE_GRAPH_WORKFLOWS } = await Promise.resolve().then(() => __importStar(require('../examples')));
+                graphFlows.push(...EXAMPLE_GRAPH_WORKFLOWS);
+            }
+            if (graphFlows.length) {
+                const { seedGraphWorkflows } = await Promise.resolve().then(() => __importStar(require('./graph-workflows')));
+                await seedGraphWorkflows(graphFlows);
+            }
+        }
         // Register workers for active YAML (deterministic) workflows
         await yamlWorkflowWorkers.registerAllActiveWorkers();
     }