yaml-flow 6.0.0 → 7.1.0

package/examples/cli/step-machine-demo/jsonata-init-board.flow.yaml

@@ -1,21 +1,45 @@
 id: jsonata-init-board-demo
 settings:
-  start_step: t0_init_board
+  start_step: t0_prepare
   max_total_steps: 10
   timeout_ms: 30000
 
 steps:
-  t0_init_board:
-    description: Build board path with JSONata and invoke CLI with command templating
+  t0_prepare:
+    description: Build board path from runtime_root and board_name
     expects_data: [runtime_root, board_name]
+    produces_data: [BOARD_DIR]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.BOARD_DIR = expects_data.runtime_root & "/" & expects_data.board_name
+        - result = "success"
+    transitions:
+      success: t1_init_board
+      failure: failed_state
+
+  t1_init_board:
+    description: Invoke init-board CLI with BOARD_DIR
+    expects_data: [BOARD_DIR]
+    produces_data: [board_dir, message]
+    handler:
+      type: ref
+      howToRun: local-node
+      whatToRun: {kind: fs-path, value: ./jsonata-init-board-cli.js}
+    transitions:
+      success: t2_map_output
+      failure: failed_state
+
+  t2_map_output:
+    description: Map CLI output to final field names
+    expects_data: [BOARD_DIR, message]
     produces_data: [board_dir, init_message]
     handler:
-      cli: node ./jsonata-init-board-cli.js "%%BOARD_DIR%%"
-      input-transforms:
-        BOARD_DIR: runtime_root & "/" & board_name
-      output-transforms:
-        board_dir: BOARD_DIR
-        init_message: data.message
+      type: compute-jsonata
+      expr:
+        - data.board_dir = expects_data.BOARD_DIR
+        - data.init_message = expects_data.message
+        - result = "success"
     transitions:
       success: success_state
       failure: failed_state

package/examples/cli/step-machine-demo/one-step-cli-only.flow.yaml

@@ -6,7 +6,9 @@ steps:
     expects_data: [x]
     produces_data: [y]
     handler:
-      cli: node ./step-cli-echo-y.js
+      type: ref
+      howToRun: local-node
+      whatToRun: {kind: fs-path, value: ./step-cli-echo-y.js}
     transitions:
       success: success_state
       failure: failed_state

package/examples/cli/step-machine-demo/step2-double-cli.js

@@ -13,26 +13,20 @@ process.stdin.on('end', () => {
     const c = Number(input.c);
 
     if (!Number.isFinite(c)) {
-      process.stdout.write(JSON.stringify({
-        result: 'failure',
-        error: 'step2_double requires numeric c',
-      }));
-      process.exit(0);
+      process.stderr.write('step2_double requires numeric c');
+      process.exit(1);
       return;
     }
 
     const d = c * 2;
     process.stdout.write(JSON.stringify({
-      status: 'success',
-      data: {
-        a: 123,
-        d,
-      },
+      a: 123,
+      d,
     }));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    process.stdout.write(JSON.stringify({ result: 'failure', error: message }));
-    process.exit(0);
+    process.stderr.write(message);
+    process.exit(1);
   }
 });
 

package/examples/cli/step-machine-demo/two-step-math.flow.yaml

@@ -4,19 +4,81 @@ settings:
   max_total_steps: 10
   timeout_ms: 10000
 
+# Demonstrates three compute-jsonata techniques:
+#   1. Basic arithmetic with data.* output and explicit result=
+#   2. Chained ternary with local $var binding ($c :=) — range classification and conditional routing
+#   3. $lookup object-switch — route result directly from a map (see switch test in step-machine-cli.test.ts)
+# NOTE: expr items containing ': ' or '{key: value}' must be single-quoted in YAML.
+
 steps:
   step1_add:
     description: Compute c = a + b
     expects_data: [a, b]
     produces_data: [c]
+    input_validations:
+      - $type(a) = "number"
+      - $type(b) = "number"
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.c = expects_data.a + expects_data.b
+        - result = "success"
+    transitions:
+      success: step2_classify
+      failure: failed_state
+
+  step2_classify:
+    description: |
+      Classify c using an object-lookup switch.
+      Routes to low_track / mid_track / high_track based on magnitude.
+    expects_data: [c]
+    produces_data: [band]
+    handler:
+      type: compute-jsonata
+      expr:
+        - 'data.band = ($c := expects_data.c; $c < 10 ? "low" : $c < 100 ? "mid" : "high")'
+        - result = data.band
     transitions:
-      success: step2_double
+      low:  low_track
+      mid:  mid_track
+      high: high_track
+      failure: failed_state
+
+  low_track:
+    description: Small result — multiply by 3
+    expects_data: [c]
+    produces_data: [d]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.d = expects_data.c * 3
+        - result = "success"
+    transitions:
+      success: success_state
+      failure: failed_state
+
+  mid_track:
+    description: Medium result — multiply by 2
+    expects_data: [c]
+    produces_data: [d]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.d = expects_data.c * 2
+        - result = "success"
+    transitions:
+      success: success_state
       failure: failed_state
 
-  step2_double:
-    description: Compute d = c * 2
+  high_track:
+    description: Large result — keep as-is (already big enough)
     expects_data: [c]
     produces_data: [d]
+    handler:
+      type: compute-jsonata
+      expr:
+        - data.d = expects_data.c
+        - result = "success"
     transitions:
       success: success_state
       failure: failed_state
@@ -24,7 +86,7 @@ steps:
 terminal_states:
   success_state:
     return_intent: success
-    return_artifacts: [a, b, c, d]
+    return_artifacts: [a, b, c, band, d]
 
   failed_state:
     return_intent: failure

package/examples/cli/step-machine-demo/two-step-mixed.flow.yaml

@@ -6,21 +6,29 @@ settings:
 
 steps:
   step1_add:
-    description: Inline handler computes c = a + b
+    description: Compute step computes c = a + b
     expects_data: [a, b]
-    produces_data: [c, e]
+    produces_data: [c]
+    input_validations:
+      - $type(a) = "number"
+      - $type(b) = "number"
     handler:
-      inline: step1_add
+      type: compute-jsonata
+      expr:
+        - data.c = expects_data.a + expects_data.b
+        - result = "success"
     transitions:
       success: step2_double
       failure: failed_state
 
   step2_double:
-    description: CLI handler computes d = c * 2
+    description: Ref handler computes d = c * 2
     expects_data: [c]
     produces_data: [d, e]
     handler:
-      cli: node ./step2-double-cli.js
+      type: ref
+      howToRun: local-node
+      whatToRun: {kind: fs-path, value: ./step2-double-cli.js}
     transitions:
       success: success_state
       failure: failed_state

package/examples/example-board/agent-instructions.md

@@ -706,7 +706,7 @@ Before adding a card to a running board, agents should validate that each source
 
 ```bash
 node board-live-cards-cli.js probe-source \
-  --card cards/card-market-prices.json \
+  --card cards/cardT-market-prices.json \
   --source-idx 0 \
   --rg <boardRuntimeDir> \
   --mock-projections '{"holdings":[{"ticker":"AAPL","quantity":10},{"ticker":"MSFT","quantity":5}]}'

package/examples/example-board/cards/card-my-identity.json

@@ -2,7 +2,10 @@
   "id": "card-my-identity",
   "meta": {
     "title": "My Identity",
-    "tags": ["m365", "workiq"],
+    "tags": [
+      "m365",
+      "workiq"
+    ],
     "desc": "Displays your M365 display name via WorkIQ (Microsoft 365 Copilot)."
   },
   "source_defs": [
@@ -14,15 +17,36 @@
       }
     }
   ],
+  "compute": [
+    {
+      "bindTo": "identity",
+      "expr": "fetched_sources.identity"
+    }
+  ],
   "view": {
     "elements": [
-      { "kind": "markdown", "data": { "bind": "fetched_sources.identity" } }
+      {
+        "kind": "markdown",
+        "data": {
+          "bind": "computed_values.identity"
+        }
+      }
     ],
     "layout": {
-      "board": { "col": 4, "order": 10 },
-      "canvas": { "x": 50, "y": 450, "w": 420, "h": 260 }
+      "board": {
+        "col": 4,
+        "order": 10
+      },
+      "canvas": {
+        "x": 50,
+        "y": 450,
+        "w": 420,
+        "h": 260
+      }
     },
-    "features": { "refresh": true }
+    "features": {
+      "refresh": true
+    }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-portfolio-action.json

@@ -2,18 +2,36 @@
   "id": "card-portfolio-action",
   "meta": {
     "title": "Action Signal",
-    "tags": ["portfolio", "action"],
+    "tags": [
+      "portfolio",
+      "action"
+    ],
     "desc": "Actionable recommendation sourced from Portfolio Intelligence."
   },
-  "requires": ["portfolio_action"],
+  "requires": [
+    "portfolio_action"
+  ],
   "view": {
     "elements": [
-      { "kind": "markdown", "data": { "bind": "requires.portfolio_action" } }
+      {
+        "kind": "markdown",
+        "data": {
+          "bind": "requires.portfolio_action"
+        }
+      }
     ],
     "layout": {
-      "board": { "col": 4, "order": 6 },
-      "canvas": { "x": 1660, "y": 50, "w": 300, "h": 160 }
+      "board": {
+        "col": 4,
+        "order": 6
+      },
+      "canvas": {
+        "x": 1660,
+        "y": 50,
+        "w": 300,
+        "h": 160
+      }
     }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-portfolio-intelligence.json

@@ -0,0 +1,97 @@
+{
+  "id": "card-portfolio-intelligence",
+  "meta": {
+    "title": "Portfolio Intelligence",
+    "tags": [
+      "portfolio",
+      "analysis"
+    ],
+    "desc": "AI analysis of portfolio mix and P&L. Publishes structured insights as tokens for downstream risk and action cards."
+  },
+  "requires": [
+    "positions"
+  ],
+  "source_defs": [
+    {
+      "bindTo": "analysis",
+      "outputFile": "card-concentration-analysis.json",
+      "projections": {
+        "positions": "requires.positions"
+      },
+      "copilot": {
+        "prompt_template": "You are a concise equity analyst. Use web search to get today's news and upcoming events for each ticker before answering.\n\nPortfolio positions:\n{{positions}}\n\nFields: ticker, quantity, cost_basis ($), price ($), value ($), gain_$ (unrealised P&L), gain_% (unrealised return), chg_$ (today's position P&L $), chg_pct (today's % move).\n\nIMPORTANT OUTPUT RULES:\n- Return ONLY a valid JSON object. No markdown code fences, no preamble, no trailing text.\n- Start your response with { and end with }.\n- No emojis anywhere.\n- Each value is a Markdown string using - bullet points. No sub-headings inside values.\n- Maximum 40 words per section.\n\n{\n  \"mix\": \"- <dominant holding ticker, % of total, and whether that is a risk>\\n- <sector clustering in one line>\",\n  \"pnl\": \"- Best: <ticker> +X% (+$Y)\\n- Worst: <ticker> +X% (+$Y)\",\n  \"risks\": \"- <TICKER>: <one specific current risk with event name or date>\\n- <TICKER>: ...\\n- (one bullet per position from today's news)\",\n  \"action\": \"- <one sentence: specific action and reason grounded in today's market>\"\n}"
+      }
+    }
+  ],
+  "compute": [
+    {
+      "bindTo": "mix",
+      "expr": "fetched_sources.analysis.mix"
+    },
+    {
+      "bindTo": "pnl",
+      "expr": "fetched_sources.analysis.pnl"
+    },
+    {
+      "bindTo": "risks",
+      "expr": "fetched_sources.analysis.risks"
+    },
+    {
+      "bindTo": "action",
+      "expr": "fetched_sources.analysis.action"
+    }
+  ],
+  "provides": [
+    {
+      "bindTo": "portfolio_mix",
+      "ref": "computed_values.mix"
+    },
+    {
+      "bindTo": "portfolio_pnl",
+      "ref": "computed_values.pnl"
+    },
+    {
+      "bindTo": "portfolio_risks",
+      "ref": "computed_values.risks"
+    },
+    {
+      "bindTo": "portfolio_action",
+      "ref": "computed_values.action"
+    }
+  ],
+  "view": {
+    "elements": [
+      {
+        "kind": "markdown",
+        "label": "Mix",
+        "data": {
+          "bind": "computed_values.mix"
+        }
+      },
+      {
+        "kind": "markdown",
+        "label": "P&L",
+        "data": {
+          "bind": "computed_values.pnl"
+        }
+      }
+    ],
+    "layout": {
+      "board": {
+        "col": 3,
+        "order": 4
+      },
+      "canvas": {
+        "x": 1300,
+        "y": 50,
+        "w": 340,
+        "h": 200
+      }
+    },
+    "features": {
+      "refresh": true,
+      "chat": true
+    }
+  },
+  "card_data": {}
+}

package/examples/example-board/cards/card-portfolio-risks.json

@@ -2,18 +2,36 @@
   "id": "card-portfolio-risks",
   "meta": {
     "title": "Risk Watch",
-    "tags": ["portfolio", "risk"],
+    "tags": [
+      "portfolio",
+      "risk"
+    ],
     "desc": "Per-ticker risk signals sourced from Portfolio Intelligence."
   },
-  "requires": ["portfolio_risks"],
+  "requires": [
+    "portfolio_risks"
+  ],
   "view": {
     "elements": [
-      { "kind": "markdown", "data": { "bind": "requires.portfolio_risks" } }
+      {
+        "kind": "markdown",
+        "data": {
+          "bind": "requires.portfolio_risks"
+        }
+      }
     ],
     "layout": {
-      "board": { "col": 3, "order": 5 },
-      "canvas": { "x": 1300, "y": 270, "w": 340, "h": 220 }
+      "board": {
+        "col": 3,
+        "order": 5
+      },
+      "canvas": {
+        "x": 1300,
+        "y": 270,
+        "w": 340,
+        "h": 220
+      }
     }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-rebalance-impact.json

@@ -2,11 +2,17 @@
   "id": "card-rebalance-impact",
   "meta": {
     "title": "Rebalance Impact",
-    "tags": ["portfolio", "simulation"],
+    "tags": [
+      "portfolio",
+      "simulation"
+    ],
     "simulation": true,
     "desc": "Before/after impact summary of the proposed rebalance scenario."
   },
-  "requires": ["positions", "proposed_trades"],
+  "requires": [
+    "positions",
+    "proposed_trades"
+  ],
   "compute": [
     {
       "bindTo": "total_current_value",
@@ -53,13 +59,23 @@
     "elements": [
       {
         "kind": "markdown",
-        "data": { "bind": "computed_values.summary_md" }
+        "data": {
+          "bind": "computed_values.summary_md"
+        }
       }
     ],
     "layout": {
-      "board": { "col": 6, "order": 8 },
-      "canvas": { "x": 1360, "y": 480, "w": 400, "h": 280 }
+      "board": {
+        "col": 6,
+        "order": 8
+      },
+      "canvas": {
+        "x": 1360,
+        "y": 480,
+        "w": 400,
+        "h": 280
+      }
     }
   },
   "card_data": {}
-}
+}

package/examples/example-board/cards/card-rebalance-sim.json

@@ -2,11 +2,20 @@
   "id": "card-rebalance-sim",
   "meta": {
     "title": "Rebalance Proposal",
-    "tags": ["portfolio", "simulation"],
+    "tags": [
+      "portfolio",
+      "simulation"
+    ],
     "simulation": true,
     "desc": "AI-proposed rebalance trades based on portfolio intelligence. Edit quantities before pinning."
   },
-  "requires": ["holdings", "portfolio_mix", "portfolio_risks", "portfolio_action", "positions"],
+  "requires": [
+    "holdings",
+    "portfolio_mix",
+    "portfolio_risks",
+    "portfolio_action",
+    "positions"
+  ],
   "source_defs": [
     {
       "bindTo": "rebalance",
@@ -24,7 +33,20 @@
     }
   ],
   "provides": [
-    { "bindTo": "proposed_trades", "ref": "fetched_sources.rebalance.proposed_trades" }
+    {
+      "bindTo": "proposed_trades",
+      "ref": "fetched_sources.rebalance.proposed_trades"
+    }
+  ],
+  "compute": [
+    {
+      "bindTo": "proposed_trades",
+      "expr": "fetched_sources.rebalance.proposed_trades"
+    },
+    {
+      "bindTo": "_view",
+      "expr": "fetched_sources.rebalance._view"
+    }
   ],
   "view": {
     "elements": [
@@ -32,18 +54,37 @@
         "kind": "ref",
         "label": "Proposed Trades",
         "data": {
-          "bind": "fetched_sources.rebalance.proposed_trades",
-          "viewBind": "fetched_sources.rebalance._view",
+          "bind": "computed_values.proposed_trades",
+          "viewBind": "computed_values._view",
           "fallbackKind": "editable-table",
           "writeTo": "card_data.proposed_trades",
-          "columns": ["ticker", "direction", "current_qty", "change", "proposed_qty", "price", "trade_value", "reason"],
+          "columns": [
+            "ticker",
+            "direction",
+            "current_qty",
+            "change",
+            "proposed_qty",
+            "price",
+            "trade_value",
+            "reason"
+          ],
           "schema": {
             "properties": {
-              "current_qty": { "type": "number" },
-              "change": { "type": "number" },
-              "proposed_qty": { "type": "number" },
-              "price": { "type": "number" },
-              "trade_value": { "type": "number" }
+              "current_qty": {
+                "type": "number"
+              },
+              "change": {
+                "type": "number"
+              },
+              "proposed_qty": {
+                "type": "number"
+              },
+              "price": {
+                "type": "number"
+              },
+              "trade_value": {
+                "type": "number"
+              }
             }
           }
         }
@@ -58,10 +99,20 @@
       }
     ],
     "layout": {
-      "board": { "col": 6, "order": 7 },
-      "canvas": { "x": 840, "y": 480, "w": 500, "h": 280 }
+      "board": {
+        "col": 6,
+        "order": 7
+      },
+      "canvas": {
+        "x": 840,
+        "y": 480,
+        "w": 500,
+        "h": 280
+      }
     },
-    "features": { "refresh": true }
+    "features": {
+      "refresh": true
+    }
   },
   "card_data": {}
-}
+}