yaml-flow 5.4.2 → 7.0.0

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: "::fs-path::./step2-double-cli.js"
     transitions:
       success: success_state
       failure: failed_state

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

@@ -780,10 +780,15 @@ node <handler.js> --boardId <id> --cardId <id> --extraEncJson <base64json>
 
 - **`--boardId`** — board identifier
 - **`--cardId`** — the specific card where the user clicked the chat button
-- **`--extraEncJson`** — base64-encoded JSON: `{ chatDir, boardDir, lastChatFile }`
+- **`--extraEncJson`** — base64-encoded JSON: `{ boardSetupRoot, boardRuntimeDir, runtimeStatusDir, cardsDir, chatDir, chatProcessingMarkerKey, lastChatFile, serverUrl? }`
+  - `boardSetupRoot` — absolute board setup root (parent of runtime/surface/runtime-out)
+  - `boardRuntimeDir` — relative runtime path (for example `runtime`)
+  - `runtimeStatusDir` — relative runtime-out path
+  - `cardsDir` — relative cards root path (for example `surface/tmp-cards`)
   - `chatDir` — absolute path to the directory holding all chat message files for this card
-  - `boardDir` — absolute path to the board runtime directory
+  - `chatProcessingMarkerKey` — relative key for `.processing` marker under cardsDir (for example `card-portfolio/.processing`)
   - `lastChatFile` — filename of the user message just written (e.g. `007_user.txt`)
+  - `serverUrl` — optional base URL of the hosting server
 
 ### Chat message files
 
@@ -795,8 +800,9 @@ Messages are stored as serial-numbered `.txt` files in `chatDir`:
 
 1. Read all `*_user.txt` / `*-assistant.txt` files from `chatDir` (sorted) → conversation history
 2. Build a system prompt scoped to `cardId` / `boardId` as grounding context
-3. Call the LLM directly (e.g. Copilot CLI) with `cwd: boardDir` — running from `boardDir` gives the LLM natural file context
+3. Call the LLM directly (e.g. Copilot CLI) with `cwd: boardSetupRoot` — running from board setup root gives natural file context for runtime, cards, and outputs
 4. Write the response to `<nextSerial>-assistant.txt` in `chatDir`
+5. Remove `.processing` marker using `chatProcessingMarkerKey` (fallback: `chatDir/.processing`)
 
 ### System prompt guidance
 
@@ -815,12 +821,12 @@ Be concise. Ground answers in the card's data context.`
 
 ### LLM invocation
 
-Call Copilot CLI directly from `boardDir` — same pattern as `demo-task-executor.js`:
+Call Copilot CLI directly from `boardSetupRoot` — same pattern as `demo-task-executor.js`:
 ```javascript
 execFileSync(copilotBin, ['--allow-all'], {
   input: fullPrompt,
   encoding: 'utf-8',
-  cwd: boardDir,         // ← run from boardDir for natural file context
+  cwd: boardSetupRoot,   // ← run from setup root for natural file context
   stdio: ['pipe', 'pipe', 'pipe'],
 });
 ```

package/examples/example-board/cards/_index.json

@@ -0,0 +1,47 @@
+{
+  "card-portfolio-intelligence": {
+    "key": "card-portfolio-intelligence",
+    "checksum": "card-portfolio-intelligence",
+    "updatedAt": "2026-05-10T09:38:02.181Z"
+  },
+  "card-market-prices": {
+    "key": "card-market-prices",
+    "checksum": "card-market-prices",
+    "updatedAt": "2026-05-10T09:38:02.161Z"
+  },
+  "card-my-identity": {
+    "key": "card-my-identity",
+    "checksum": "card-my-identity",
+    "updatedAt": "2026-05-10T09:38:02.168Z"
+  },
+  "card-portfolio-action": {
+    "key": "card-portfolio-action",
+    "checksum": "card-portfolio-action",
+    "updatedAt": "2026-05-10T09:38:02.174Z"
+  },
+  "card-portfolio-risks": {
+    "key": "card-portfolio-risks",
+    "checksum": "card-portfolio-risks",
+    "updatedAt": "2026-05-10T09:38:02.187Z"
+  },
+  "card-portfolio-value": {
+    "key": "card-portfolio-value",
+    "checksum": "card-portfolio-value",
+    "updatedAt": "2026-05-10T09:38:02.195Z"
+  },
+  "card-portfolio": {
+    "key": "card-portfolio",
+    "checksum": "card-portfolio",
+    "updatedAt": "2026-05-10T09:38:02.201Z"
+  },
+  "card-rebalance-impact": {
+    "key": "card-rebalance-impact",
+    "checksum": "card-rebalance-impact",
+    "updatedAt": "2026-05-10T09:38:02.208Z"
+  },
+  "card-rebalance-sim": {
+    "key": "card-rebalance-sim",
+    "checksum": "card-rebalance-sim",
+    "updatedAt": "2026-05-10T09:38:02.214Z"
+  }
+}

package/examples/example-board/cards/card-market-prices.json

@@ -2,10 +2,15 @@
   "id": "card-market-prices",
   "meta": {
     "title": "Market Prices",
-    "tags": ["prices", "market"],
+    "tags": [
+      "prices",
+      "market"
+    ],
     "desc": "Fetches live prices for portfolio tickers. Publishes enriched quote data for downstream portfolio value calculations."
   },
-  "requires": ["holdings"],
+  "requires": [
+    "holdings"
+  ],
   "source_defs": [
     {
       "bindTo": "quotes",
@@ -24,7 +29,7 @@
   "compute": [
     {
       "bindTo": "normalizedQuotes",
-      "expr": "{ \"quoteResponse\": { \"result\": $map(fetched_sources.quotes, function($r) { $r.chart.result[0].meta.{ \"symbol\": symbol, \"shortName\": longName, \"regularMarketPrice\": regularMarketPrice, \"regularMarketChange\": regularMarketChange, \"regularMarketChangePercent\": regularMarketChangePercent } }), \"error\": null } }"
+      "expr": "{ \"quoteResponse\": { \"result\": $map(fetched_sources.quotes, function($r) { ($m := $r.chart.result[0].meta; $prev := $m.chartPreviousClose; $chg := $m.regularMarketPrice - $prev; { \"symbol\": $m.symbol, \"shortName\": $m.shortName ? $m.shortName : $m.longName, \"regularMarketPrice\": $m.regularMarketPrice, \"regularMarketChange\": $chg, \"regularMarketChangePercent\": $chg / $prev * 100 }) }), \"error\": null } }"
     },
     {
       "bindTo": "prices",
@@ -32,7 +37,10 @@
     }
   ],
   "provides": [
-    { "bindTo": "quotes", "ref": "computed_values.normalizedQuotes" }
+    {
+      "bindTo": "quotes",
+      "ref": "computed_values.normalizedQuotes"
+    }
   ],
   "view": {
     "elements": [
@@ -41,16 +49,32 @@
         "label": "Prices",
         "data": {
           "bind": "computed_values.prices",
-          "columns": ["ticker", "name", "price", "change", "chg_pct"],
+          "columns": [
+            "ticker",
+            "name",
+            "price",
+            "change",
+            "chg_pct"
+          ],
           "sortable": true
         }
       }
     ],
     "layout": {
-      "board": { "col": 4, "order": 2 },
-      "canvas": { "x": 400, "y": 50, "w": 400, "h": 340 }
+      "board": {
+        "col": 4,
+        "order": 2
+      },
+      "canvas": {
+        "x": 400,
+        "y": 50,
+        "w": 400,
+        "h": 340
+      }
     },
-    "features": { "refresh": true }
+    "features": {
+      "refresh": true
+    }
   },
   "card_data": {}
-}
+}

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-portfolio-value.json

@@ -2,12 +2,21 @@
   "id": "card-portfolio-value",
   "meta": {
     "title": "Portfolio Value",
-    "tags": ["portfolio", "value"],
+    "tags": [
+      "portfolio",
+      "value"
+    ],
     "desc": "Computes total portfolio value, gainers/losers summary, and per-position P&L from holdings and live market quotes."
   },
-  "requires": ["holdings", "quotes"],
+  "requires": [
+    "holdings",
+    "quotes"
+  ],
   "provides": [
-    { "bindTo": "positions", "ref": "computed_values.positions" }
+    {
+      "bindTo": "positions",
+      "ref": "computed_values.positions"
+    }
   ],
   "compute": [
     {
@@ -36,27 +45,46 @@
       {
         "kind": "metric",
         "label": "Portfolio Value ($)",
-        "data": { "bind": "computed_values.totalValue" }
+        "data": {
+          "bind": "computed_values.totalValue"
+        }
       },
       {
         "kind": "text",
-        "data": { "bind": "computed_values.gainersLosers" }
+        "data": {
+          "bind": "computed_values.gainersLosers"
+        }
       },
       {
         "kind": "table",
         "label": "Positions",
         "data": {
           "bind": "computed_values.positions",
-          "columns": ["ticker", "value", "gain_$", "gain_%"],
+          "columns": [
+            "ticker",
+            "value",
+            "gain_$",
+            "gain_%"
+          ],
           "sortable": true
         }
       }
     ],
     "layout": {
-      "board": { "col": 4, "order": 3 },
-      "canvas": { "x": 840, "y": 50, "w": 420, "h": 380 }
+      "board": {
+        "col": 4,
+        "order": 3
+      },
+      "canvas": {
+        "x": 840,
+        "y": 50,
+        "w": 420,
+        "h": 380
+      }
     },
-    "features": { "chat": true }
+    "features": {
+      "chat": true
+    }
   },
   "card_data": {}
-}
+}