yaml-flow 5.2.8 → 5.3.0

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

@@ -26,3 +26,31 @@
 - `board.col` — Bootstrap 12-column span: `3`=quarter, `4`=third, `6`=half, `8`=two-thirds, `12`=full
 - `board.order` — ascending integer, controls vertical sort in board view
 - `canvas` — pixel coordinates/size for drag-layout (canvas mode). `h` must be tall enough for all rendered content — a card with metrics + a 4-row table typically needs 400–500px. Too small a height causes an in-card scrollbar; when in doubt, size generously.
+
+---
+
+## LLM View-Type Guidance (for `kind: "ref"`)
+
+When a source uses Copilot/LLM and the card renders via a `ref` element, the model should emit a `_view` hint alongside the data.
+
+- Keep `_view.kind` within the renderer whitelist only:
+  `table`, `editable-table`, `chart`, `metric`, `list`, `badge`, `text`, `narrative`, `markdown`, `form`, `filter`, `todo`, `alert`
+- Default to `table` when uncertain.
+- Use `editable-table` for user-adjustable tabular rows and include `data.writeTo` to a `card_data` path.
+- Use `chart` only when one clear category/value mapping exists; include `data.chartType` and `data.columns: [labelField, valueField]`.
+- Keep `_view.data` minimal. Static card JSON may override it for safety.
+
+Recommended response shape:
+
+```json
+{
+  "<data_key>": [ ... ],
+  "_view": {
+    "kind": "editable-table",
+    "data": {
+      "writeTo": "card_data.<key>",
+      "columns": ["field1", "field2"]
+    }
+  }
+}
+```

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

@@ -19,7 +19,7 @@
         "portfolio_action": "requires.portfolio_action"
       },
       "copilot": {
-        "prompt_template": "You are a portfolio rebalance advisor. Using the intelligence analysis and current holdings below, propose specific trades.\n\nCurrent holdings:\n{{holdings}}\nFields: ticker, quantity, cost_basis ($).\n\nPositions (with live prices):\n{{positions}}\nFields: ticker, quantity, cost_basis, price ($), value ($), gain_$, gain_%, chg_$, chg_pct.\n\nPortfolio intelligence:\n- Mix: {{portfolio_mix}}\n- Risks: {{portfolio_risks}}\n- Action signal: {{portfolio_action}}\n\nIMPORTANT OUTPUT RULES:\n- Return ONLY a valid JSON object. No markdown, no preamble, no trailing text.\n- Start with { and end with }.\n- proposed_trades must be an array of objects with EXACTLY these fields per entry:\n  ticker (string), direction (\"reduce\" or \"increase\"), current_qty (number, current shares held), change (number, shares to trade), proposed_qty (number, resulting shares after trade), price (number, current price per share), trade_value (number, change * price rounded to 2 decimals), reason (string, one short sentence).\n- Include one entry per ticker you recommend changing. Do not include tickers with no change.\n\n{\n  \"proposed_trades\": [\n    {\"ticker\": \"AAPL\", \"direction\": \"reduce\", \"current_qty\": 15, \"change\": 5, \"proposed_qty\": 10, \"price\": 210.50, \"trade_value\": 1052.50, \"reason\": \"overweight at 41%, trim before earnings\"}\n  ]\n}"
+        "prompt_template": "You are a portfolio rebalance advisor. Using the intelligence analysis and current holdings below, propose specific trades.\n\nCurrent holdings:\n{{holdings}}\nFields: ticker, quantity, cost_basis ($).\n\nPositions (with live prices):\n{{positions}}\nFields: ticker, quantity, cost_basis, price ($), value ($), gain_$, gain_%, chg_$, chg_pct.\n\nPortfolio intelligence:\n- Mix: {{portfolio_mix}}\n- Risks: {{portfolio_risks}}\n- Action signal: {{portfolio_action}}\n\n{{view_kind_guidance}}\n\n{{card_layout_guidance}}\n\nIMPORTANT OUTPUT RULES:\n- Return ONLY a valid JSON object. No markdown, no preamble, no trailing text.\n- Start with { and end with }.\n- proposed_trades must be an array of objects with EXACTLY these fields per entry:\n  ticker (string), direction (\"reduce\" or \"increase\"), current_qty (number, current shares held), change (number, shares to trade), proposed_qty (number, resulting shares after trade), price (number, current price per share), trade_value (number, change * price rounded to 2 decimals), reason (string, one short sentence).\n- Include one entry per ticker you recommend changing. Do not include tickers with no change.\n- Include a top-level _view object for a ref element with this shape:\n  { \"kind\": \"editable-table\"|\"table\"|\"chart\", \"data\": { ... } }\n- If kind is editable-table or table, include data.columns with the exact proposed_trades fields in desired order.\n- If kind is editable-table, also include data.writeTo = \"card_data.proposed_trades\".\n- If kind is chart, include data.chartType and data.columns as [\"ticker\", \"trade_value\"].\n- If unsure, choose editable-table.\n\n{\n  \"proposed_trades\": [\n    {\"ticker\": \"AAPL\", \"direction\": \"reduce\", \"current_qty\": 15, \"change\": 5, \"proposed_qty\": 10, \"price\": 210.50, \"trade_value\": 1052.50, \"reason\": \"overweight at 41%, trim before earnings\"}\n  ],\n  \"_view\": {\n    \"kind\": \"editable-table\",\n    \"data\": {\n      \"writeTo\": \"card_data.proposed_trades\",\n      \"columns\": [\"ticker\", \"direction\", \"current_qty\", \"change\", \"proposed_qty\", \"price\", \"trade_value\", \"reason\"]\n    }\n  }\n}"
       }
     }
   ],
@@ -29,10 +29,12 @@
   "view": {
     "elements": [
       {
-        "kind": "editable-table",
+        "kind": "ref",
         "label": "Proposed Trades",
         "data": {
           "bind": "fetched_sources.rebalance.proposed_trades",
+          "viewBind": "fetched_sources.rebalance._view",
+          "fallbackKind": "editable-table",
           "writeTo": "card_data.proposed_trades",
           "columns": ["ticker", "direction", "current_qty", "change", "proposed_qty", "price", "trade_value", "reason"],
           "schema": {
@@ -45,13 +47,21 @@
             }
           }
         }
+      },
+      {
+        "kind": "notes",
+        "label": "Notes",
+        "data": {
+          "bind": "card_data.notes",
+          "writeTo": "card_data.notes"
+        }
       }
     ],
     "layout": {
       "board": { "col": 6, "order": 7 },
       "canvas": { "x": 840, "y": 480, "w": 500, "h": 280 }
     },
-    "features": { "refresh": true, "notes": true }
+    "features": { "refresh": true }
   },
   "card_data": {}
 }

package/examples/example-board/demo-server.js

@@ -168,26 +168,38 @@ async function handleWorkiqAsk(req, res) {
   await new Promise((resolve) => {
     let stdout = '';
     let stderr = '';
+    let responded = false;
     const child = spawn(process.execPath, [workiqJs, 'ask', '-q', query], {
       stdio: ['inherit', 'pipe', 'pipe'],
     });
     child.stdout.on('data', chunk => { stdout += chunk; });
     child.stderr.on('data', chunk => { stderr += chunk; });
     child.on('error', (err) => {
-      jsonReply(res, 500, { error: `workiq spawn error: ${err.message}` });
+      if (!responded) {
+        responded = true;
+        clearTimeout(timeoutId);
+        jsonReply(res, 500, { error: `workiq spawn error: ${err.message}` });
+      }
       resolve();
     });
     child.on('close', (code) => {
-      if (code !== 0) {
-        jsonReply(res, 500, { error: `workiq exited ${code}`, stderr });
-      } else {
-        jsonReply(res, 200, { response: stdout });
+      if (!responded) {
+        responded = true;
+        clearTimeout(timeoutId);
+        if (code !== 0) {
+          jsonReply(res, 500, { error: `workiq exited ${code}`, stderr });
+        } else {
+          jsonReply(res, 200, { response: stdout });
+        }
       }
       resolve();
     });
-    setTimeout(() => {
-      child.kill();
-      jsonReply(res, 504, { error: 'workiq timed out after 60s' });
+    const timeoutId = setTimeout(() => {
+      if (!responded) {
+        responded = true;
+        child.kill();
+        jsonReply(res, 504, { error: 'workiq timed out after 60s' });
+      }
       resolve();
     }, 60_000);
   });

package/examples/example-board/demo-shell-browser.html

@@ -6,9 +6,9 @@
   <title>Example Board Demo (Browser Runtime)</title>
   <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
   <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/board-livegraph-engine.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

package/examples/example-board/demo-shell-with-server.html

@@ -16,10 +16,10 @@
   </style>
   <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/board-livegraph-engine.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.2.8/browser/board-livecards-runtime-client.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.3.0/browser/board-livecards-runtime-client.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">

package/examples/example-board/demo-task-executor.js

@@ -137,6 +137,26 @@ function interpolatePrompt(template, args) {
   });
 }
 
+// Reusable prompt fragments available to all copilot source templates.
+// Source definitions can interpolate them with {{view_kind_guidance}} and {{card_layout_guidance}}.
+const COPILOT_PROMPT_CONTEXT = {
+  view_kind_guidance: [
+    'VIEW KIND GUIDANCE (for dynamic ref rendering):',
+    '- Return a _view object whenever your output data is meant for a ref element.',
+    '- Allowed _view.kind values only: table, editable-table, chart, metric, list, badge, text, narrative, markdown, form, filter, todo, alert.',
+    '- If uncertain, use "table".',
+    '- For array rows that users should edit, prefer "editable-table" and set _view.data.writeTo to a card_data path.',
+    '- For chart, set _view.data.chartType and _view.data.columns with [labelField, valueField].',
+    '- Keep _view.data minimal and valid JSON (no comments, no trailing text).',
+  ].join('\n'),
+  card_layout_guidance: [
+    'CARD LAYOUT GUIDANCE:',
+    '- Prefer compact outputs that fit a card: one primary structure plus concise rationale text.',
+    '- Avoid repeating values already present in upstream inputs.',
+    '- If you produce both machine-readable and human-readable content, keep machine-readable fields top-level and concise prose in a separate field.',
+  ].join('\n'),
+};
+
 /**
  * Fetch a URL using the system curl binary (synchronous, no Node event-loop handles).
  * Throws if curl exits non-zero (e.g. HTTP 4xx/5xx with -f, or network error).
@@ -167,6 +187,7 @@ function resolveCopilotPrompt(sourceDef) {
   // evaluated by the engine from card_data/requires before invoking this executor.
   // Explicit args defined on the source take highest precedence.
   const interpolationContext = {
+    ...COPILOT_PROMPT_CONTEXT,
     ...sourceDef._projections,
     ...args,
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "5.2.8",
+  "version": "5.3.0",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",

package/schema/live-cards.schema.json

@@ -126,7 +126,7 @@
         "kind":      {
           "enum": ["metric", "table", "editable-table", "chart", "form", "filter", "list",
                    "notes", "todo", "alert", "narrative", "badge", "text",
-                   "markdown", "custom", "actions"]
+                   "markdown", "ref", "custom", "actions"]
         },
         "label":     { "type": "string", "description": "Heading above this element" },
         "className": { "type": "string", "description": "Bootstrap grid class, e.g. 'col-12 col-md-6'" },