@hotmeshio/long-tail 0.4.24 → 0.5.1

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/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/lib/db/schemas/011_escalation_index_audit.sql

@@ -0,0 +1,50 @@
+-- ─── lt_escalations index audit ────────────────────────────────────────────
+--
+-- Motivation (hotmesh 0.20.0, PR perf/claim-path-hotspots):
+--   Each stream/queue row pays index maintenance on every INSERT and on every
+--   non-HOT UPDATE that touches an indexed column. The HITL claim path is
+--   UPDATE-heavy (claim/resolve/release touch status, assigned_to,
+--   assigned_until, claimed_at, priority, metadata, role — nearly all indexed),
+--   so every claim is a non-HOT update that maintains all 18 btree indexes plus
+--   the metadata GIN. 0.20.0 cut redundant stream-table indexes for exactly this
+--   reason; this migration applies the same discipline to lt_escalations.
+--
+-- Scope: only drop indexes that are PROVABLY redundant — a strict leading-prefix
+--   subset of another index whose partial predicate is no stricter. Anything that
+--   merely "looks" duplicative is left in place and flagged below for EXPLAIN-driven
+--   review against production data, not dropped speculatively.
+
+-- 1. idx_lt_escalations_role_type (role, status, type, created_at DESC)
+--    is an exact leading prefix of
+--    idx_lt_escalations_role_subtype (role, status, type, subtype, created_at DESC).
+--    Every query the former can serve (equality/range on role,status,type and the
+--    created_at ordering) is served by the latter scanning the same prefix.
+DROP INDEX IF EXISTS idx_lt_escalations_role_type;
+
+-- 2. idx_lt_escalations_origin_id (origin_id) WHERE origin_id IS NOT NULL
+--    is fully covered by idx_lt_escalations_origin (origin_id, created_at DESC):
+--    `origin_id = $1` implies `origin_id IS NOT NULL`, origin_id leads the composite,
+--    and the composite additionally serves the `ORDER BY created_at DESC` used by
+--    GET_ESCALATIONS_BY_ORIGIN_ID. The partial index adds no reachable plan.
+DROP INDEX IF EXISTS idx_lt_escalations_origin_id;
+
+-- ── Review candidates (NOT dropped — verify with EXPLAIN on production volume) ──
+--
+-- These overlap but are not provably redundant. Confirm with EXPLAIN (ANALYZE,
+-- BUFFERS) on representative data before removing any of them:
+--
+--   idx_lt_escalations_available (status, role, assigned_until, created_at DESC)
+--     vs idx_lt_escalations_available_v2 (role, priority, created_at DESC)
+--        WHERE status = 'pending'
+--     The "_v2" naming implies intent to supersede v1, but v1 is full-table and
+--     v1 alone positions assigned_until for the available-pool predicate. Confirm
+--     which (if either) the listAvailableEscalations plan actually uses.
+--
+--   idx_lt_escalations_status (status, created_at DESC)
+--     Partially overlaps status-leading composites, but is the only index that
+--     serves `status = $1 ORDER BY created_at DESC` index-ordered for non-pending
+--     statuses. Keep unless EXPLAIN shows it unused.
+--
+--   idx_lt_escalations_priority_desc (priority DESC, created_at DESC)
+--     Backs the user-selectable `sort_by=priority` dashboard sort (SORTABLE_COLUMNS).
+--     Keep while that sort is exposed.

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/escalation/sql.d.ts

@@ -26,7 +26,7 @@ export declare const FIND_BY_METADATA = "SELECT *, COUNT(*) OVER() AS _total\nFR
  * $1 = metadata filter (jsonb), $2 = userId, $3 = durationMinutes,
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
-export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT *,\n  (SELECT COUNT(*) FROM lt_escalations WHERE metadata @> $1::jsonb AND status = 'pending') AS candidates_exist\nFROM updated";
+export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS MATERIALIZED (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT *,\n  (SELECT COUNT(*) FROM lt_escalations WHERE metadata @> $1::jsonb AND status = 'pending') AS candidates_exist\nFROM updated";
 /**
  * Atomic resolve by metadata with signal guard.
  *
@@ -39,4 +39,4 @@ export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS (\n  SELECT id,
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS (\n  SELECT *\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE lt_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target\n  WHERE e.id = target.id\n    AND (target.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE lt_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE lt_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target\n  WHERE e.id = target.id\n    AND (target.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE lt_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";

package/build/services/escalation/sql.js

@@ -148,7 +148,7 @@ LIMIT $3 OFFSET $4`;
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
 exports.CLAIM_BY_METADATA_GUARDED = `\
-WITH target AS (
+WITH target AS MATERIALIZED (
   SELECT id, assigned_to
   FROM lt_escalations
   WHERE metadata @> $1::jsonb
@@ -188,7 +188,7 @@ FROM updated`;
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
 exports.RESOLVE_BY_METADATA_ATOMIC = `\
-WITH target AS (
+WITH target AS MATERIALIZED (
   SELECT *
   FROM lt_escalations
   WHERE metadata @> $1::jsonb

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