yaml-flow 5.4.2 → 6.0.0

package/examples/cli/step-machine-cli/portfolio-tracker/portfolio-tracker.input.json

@@ -1,38 +1,44 @@
 {
   "runtime_root": "./runtime",
   "board_name": "portfolio-tracker-board",
-  "cards_template_dir": "./cards",
-  "completion_tasks": [
-    "portfolio-form",
-    "price-fetch",
-    "holdings-table",
-    "portfolio-value"
-  ],
-  "price_fetch_task": "price-fetch",
-  "prices_t1": {
-    "AAPL": 198.5,
-    "MSFT": 425.3,
-    "GOOG": 178.9,
-    "AMZN": 192.4,
-    "TSLA": 168.75
-  },
-  "holdings_t2": [
-    { "symbol": "AAPL", "qty": 50 },
-    { "symbol": "MSFT", "qty": 30 },
-    { "symbol": "GOOG", "qty": 100 }
-  ],
-  "prices_t2": {
-    "AAPL": 198.5,
-    "MSFT": 425.3,
-    "GOOG": 178.9,
-    "AMZN": 192.4,
-    "TSLA": 168.75
-  },
-  "prices_t3": {
-    "AAPL": 205,
-    "MSFT": 425.3,
-    "GOOG": 178.9,
-    "AMZN": 192.4,
-    "TSLA": 168.75
-  }
+  "expected_card_count": 3,
+  "cards": [
+    {
+      "id": "portfolio-form",
+      "meta": { "title": "Portfolio Holdings Form" },
+      "provides": [{ "bindTo": "holdings", "ref": "card_data.holdings" }],
+      "card_data": {
+        "holdings": [
+          { "symbol": "AAPL", "qty": 50 },
+          { "symbol": "MSFT", "qty": 30 },
+          { "symbol": "GOOG", "qty": 100 }
+        ]
+      }
+    },
+    {
+      "id": "prices-mock",
+      "meta": { "title": "Mock Market Prices" },
+      "provides": [{ "bindTo": "prices", "ref": "card_data.prices" }],
+      "card_data": {
+        "prices": {
+          "AAPL": 198.5,
+          "MSFT": 425.3,
+          "GOOG": 178.9
+        }
+      }
+    },
+    {
+      "id": "portfolio-value",
+      "meta": { "title": "Portfolio Total Value" },
+      "requires": ["holdings", "prices"],
+      "provides": [{ "bindTo": "totalValue", "ref": "computed_values.totalValue" }],
+      "card_data": {},
+      "compute": [
+        {
+          "bindTo": "totalValue",
+          "expr": "$sum($map(requires.holdings, function($h) { $h.qty * $lookup(requires.prices, $h.symbol) }))"
+        }
+      ]
+    }
+  ]
 }

package/examples/cli/step-machine-cli/portfolio-tracker/run-inline-python-demo-pycli.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    here = Path(__file__).resolve().parent
+    repo_root = here.parents[3]
+
+    pycli = repo_root / "pycli" / "main" / "step_machine_pycli.py"
+    flow = here / "inline-python-demo.flow.yaml"
+    handlers = here / "inline-python-handlers.py"
+
+    initial_data = {
+        "name": "Ada",
+        "a": 7,
+        "b": 5,
+    }
+
+    cmd = [
+        sys.executable,
+        str(pycli),
+        str(flow),
+        "--handlers",
+        str(handlers),
+        "--initial-data",
+        json.dumps(initial_data, ensure_ascii=True),
+        "--store",
+        "memory",
+    ]
+
+    proc = subprocess.run(
+        cmd,
+        cwd=str(here),
+        shell=False,
+        check=False,
+    )
+    return proc.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/cli/step-machine-cli/portfolio-tracker/run-portfolio-tracker-pycli.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Run the step-machine portfolio tracker example via step_machine_pycli.py",
+    )
+    parser.add_argument(
+        "action",
+        nargs="?",
+        choices=["run", "pause", "resume", "status"],
+        default="run",
+        help="Operation to perform (default: run)",
+    )
+    return parser
+
+
+def main() -> int:
+    args = _build_parser().parse_args()
+
+    here = Path(__file__).resolve().parent
+    repo_root = here.parents[3]
+    pycli = repo_root / "pycli" / "main" / "step_machine_pycli.py"
+    flow = here / "portfolio-tracker-pycli.flow.yaml"
+    input_json = here / "portfolio-tracker.input.json"
+
+    temp_root = Path(tempfile.gettempdir()) / "yaml-flow-step-machine-portfolio-tracker"
+    store_dir = temp_root / "store"
+    runtime_root = temp_root / "runtime"
+
+    cmd = [
+        sys.executable,
+        str(pycli),
+        "--store",
+        "file",
+        "--store-dir",
+        str(store_dir),
+    ]
+
+    if args.action in ("run", "resume"):
+        cmd.insert(2, str(flow))
+
+    if args.action == "run":
+        payload = json.loads(input_json.read_text(encoding="utf-8"))
+        payload["runtime_root"] = runtime_root.as_posix()
+        cmd.extend(["--initial-data", json.dumps(payload, ensure_ascii=True)])
+    elif args.action == "resume":
+        cmd.append("--resume")
+    elif args.action == "pause":
+        cmd.append("--pause")
+    elif args.action == "status":
+        cmd.append("--status")
+
+    proc = subprocess.run(
+        cmd,
+        cwd=str(here),
+        shell=False,
+        check=False,
+        env={
+            **os.environ,
+            "PATH": str(Path(sys.executable).parent) + os.pathsep + os.environ.get("PATH", ""),
+        },
+    )
+    return proc.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/examples/cli/step-machine-cli/portfolio-tracker/run-portfolio-tracker.bat

@@ -2,7 +2,6 @@
 setlocal
 cd /d "%~dp0"
 
-set "BOARD_LIVE_CARDS_NO_SPAWN=1"
 set "EXAMPLE_TEMP_ROOT=%TEMP%\yaml-flow-step-machine-portfolio-tracker"
 set "STORE_DIR=%EXAMPLE_TEMP_ROOT%\store"
 set "RUNTIME_ROOT=%EXAMPLE_TEMP_ROOT%\runtime"
@@ -25,5 +24,5 @@ node ..\..\..\..\step-machine-cli.js --store file --store-dir "%STORE_DIR%" --st
 exit /b %ERRORLEVEL%
 
 :run
-node -e "const fs=require('fs');const cp=require('child_process');const raw=JSON.parse(fs.readFileSync('portfolio-tracker.input.json','utf8'));raw.runtime_root=(process.env.RUNTIME_ROOT||'').replace(/\\/g,'/');const input=JSON.stringify(raw);const r=cp.spawnSync(process.execPath,['..\\..\\..\\..\\step-machine-cli.js','portfolio-tracker.flow.yaml','--store','file','--store-dir',process.env.STORE_DIR,'--initial-data',input],{stdio:'inherit',windowsHide:true,env:{...process.env,BOARD_LIVE_CARDS_NO_SPAWN:'1'}});process.exit(r.status??1);"
+node -e "const fs=require('fs');const cp=require('child_process');const raw=JSON.parse(fs.readFileSync('portfolio-tracker.input.json','utf8'));raw.runtime_root=(process.env.RUNTIME_ROOT||'').replace(/\\/g,'/');const r=cp.spawnSync(process.execPath,['..\\..\\..\\..\\step-machine-cli.js','portfolio-tracker.flow.yaml','--initial-data',JSON.stringify(raw)],{stdio:'inherit',windowsHide:true,cwd:__dirname});process.exit(r.status??1);"
 exit /b %ERRORLEVEL%

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/demo-chat-handler.js

@@ -10,6 +10,7 @@
  *   runtimeStatusDir— relative subdir: 'runtime-out'
  *   cardsDir        — relative subdir: 'surface/tmp-cards'
  *   chatDir         — absolute path to the card's chats directory
+ *   chatProcessingMarkerKey — relative marker key in chats artifacts store (e.g. 'card-portfolio/.processing')
  *   lastChatFile    — filename of the just-written user message, e.g. '001_user.txt'
  *   serverUrl       — base URL of hosting server (e.g. http://127.0.0.1:7799), optional
  *
@@ -37,13 +38,12 @@ function getArg(name) {
 const boardId     = getArg('--boardId') || '';
 const cardId      = getArg('--cardId') || '';
 const extraStr    = getArg('--extraEncJson') || '';
-const cleanOnExit = getArg('--cleanOnExit') || '';
 
 let extra = {};
 try { extra = JSON.parse(Buffer.from(extraStr, 'base64').toString('utf-8')); }
 catch { console.error('[demo-chat-handler] bad --extraEncJson'); process.exit(0); }
 
-const { boardSetupRoot, boardRuntimeDir, runtimeStatusDir, cardsDir, chatDir, lastChatFile, serverUrl } = extra;
+const { boardSetupRoot, boardRuntimeDir, runtimeStatusDir, cardsDir, chatDir, chatProcessingMarkerKey, lastChatFile, serverUrl } = extra;
 if (!boardSetupRoot || !chatDir || !lastChatFile) {
   console.error('[demo-chat-handler] missing boardSetupRoot/chatDir/lastChatFile');
   process.exit(0);
@@ -153,7 +153,17 @@ try {
 } catch (err) {
   console.error('[demo-chat-handler] wrapper failed: ' + (err?.message ?? err));
 } finally {
-  if (cleanOnExit) {
-    try { fs.unlinkSync(cleanOnExit); } catch {}
+  cleanupProcessingMarker();
+}
+function cleanupProcessingMarker() {
+  // Prefer artifacts-style marker key from extra payload so runtime/handler contract
+  // does not rely on passing an absolute file path argument.
+  if (chatProcessingMarkerKey) {
+    try {
+      const markerPath = path.join(cardsDirAbs, chatProcessingMarkerKey);
+      fs.unlinkSync(markerPath);
+      return;
+    } catch {}
   }
+  try { fs.unlinkSync(path.join(chatDirAbs, '.processing')); } catch {}
 }

package/examples/example-board/demo-server-config.json

@@ -1,5 +1,6 @@
 {
   "port": 7799,
+  "serverMetaStoreRef": "::fs-path::./.server-meta",
   "cardsDir": "./cards",
   "taskExecutorPath": "./demo-task-executor.js",
   "chatHandlerPath": "./demo-chat-handler.js",

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

@@ -27,7 +27,6 @@ function resolveYamlFlowDir() {
 }
 
 const _yamlFlowDir = resolveYamlFlowDir();
-const _pkgCliJs = _yamlFlowDir ? path.join(_yamlFlowDir, 'board-live-cards-cli.js') : null;
 const _pkgStepMachineCli = _yamlFlowDir ? path.join(_yamlFlowDir, 'step-machine-cli.js') : null;
 
 function loadServerConfig() {
@@ -47,8 +46,17 @@ function resolveFromConfig(configValue) {
   return path.resolve(__dirname, configValue);
 }
 
+function resolveKindRefFromConfig(configValue) {
+  if (typeof configValue !== 'string' || !configValue.trim()) return null;
+  const trimmed = configValue.trim();
+  if (!trimmed.startsWith('::fs-path::')) return trimmed;
+  const rawPath = trimmed.slice('::fs-path::'.length).trim();
+  if (!rawPath) return null;
+  const resolved = path.isAbsolute(rawPath) ? rawPath : path.resolve(__dirname, rawPath);
+  return `::fs-path::${resolved}`;
+}
+
 const serverConfig = loadServerConfig();
-const configuredCliJs = resolveFromConfig(serverConfig.boardLiveCardsCliJs) || _pkgCliJs;
 const configuredCardsDir = resolveFromConfig(serverConfig.cardsDir);
 const configuredTaskExecutorPath = resolveFromConfig(serverConfig.taskExecutorPath || serverConfig.demoTaskExecutorPath);
 const configuredStepMachineCliPath = resolveFromConfig(serverConfig.stepMachineCliPath) || _pkgStepMachineCli;
@@ -58,10 +66,8 @@ const configuredGandalfCardsDir = resolveFromConfig(serverConfig.gandalfCardsDir
 const configuredGandalfTaskExecutorPath = resolveFromConfig(serverConfig.gandalfTaskExecutorPath);
 const configuredGandalfChatHandlerPath = resolveFromConfig(serverConfig.gandalfChatHandlerPath);
 const configuredGandalfInferenceAdapterPath = resolveFromConfig(serverConfig.gandalfInferenceAdapterPath);
+const configuredServerMetaStoreRef = resolveKindRefFromConfig(serverConfig.serverMetaStoreRef);
 
-if (!process.env.BOARD_LIVE_CARDS_CLI_JS && configuredCliJs) {
-  process.env.BOARD_LIVE_CARDS_CLI_JS = configuredCliJs;
-}
 if (!process.env.DEMO_STEP_MACHINE_CLI_PATH && configuredStepMachineCliPath) {
   process.env.DEMO_STEP_MACHINE_CLI_PATH = configuredStepMachineCliPath;
 }
@@ -93,7 +99,7 @@ const runtime = createMultiBoardServerRuntime({
   defaultGandalfTaskExecutorPath: process.env.DEMO_GANDALF_TASK_EXECUTOR_PATH || configuredGandalfTaskExecutorPath || null,
   defaultGandalfChatHandlerPath: process.env.DEMO_GANDALF_CHAT_HANDLER_PATH || configuredGandalfChatHandlerPath || null,
   defaultGandalfInferenceAdapterPath: process.env.DEMO_GANDALF_INFERENCE_ADAPTER_PATH || configuredGandalfInferenceAdapterPath || null,
-  boardLiveCardsCliJs: process.env.BOARD_LIVE_CARDS_CLI_JS || configuredCliJs,
+  serverMetaStoreRef: process.env.DEMO_SERVER_META_STORE_REF || configuredServerMetaStoreRef || null,
 });
 
 function resetRuntime() {
@@ -267,7 +273,8 @@ const server = http.createServer((req, res) => {
 server.listen(PORT, '127.0.0.1', () => {
   console.log(`[demo-server] listening on http://127.0.0.1:${PORT}`);
   console.log(`[demo-server] setup dir: ${runtime.setupDir}`);
-  console.log(`[demo-server] boards config: ${runtime.setupDir}/boards-config.json`);
+  console.log(`[demo-server] server-meta store: ${runtime.serverMetaStoreRef}`);
+  console.log(`[demo-server] boards registry key: server-meta/${runtime.boardsRegistryKey}`);
   console.log('[demo-server] endpoints:');
   console.log(`  GET  ${runtime.apiBasePath}                          <- list boards`);
   console.log(`  POST ${runtime.apiBasePath}  {id, label?}            <- register board`);

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

@@ -6,9 +6,10 @@
   <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.4.2/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.2/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.2/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/leader-line/leader-line.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@6.0.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@6.0.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@6.0.0/browser/board-livegraph-engine.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">
@@ -398,7 +399,7 @@
       let board = null;
       let runtime = null;
       let runtimeUnsub = null;
-      let currentMode = 'board';
+      let currentMode = 'canvas';
       const nodesById = {};
 
       function setDebugPanelVisibility(isDevModeOn) {

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

@@ -16,10 +16,11 @@
   </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.4.2/browser/card-compute.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.2/browser/live-cards.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.2/browser/board-livegraph-engine.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@5.4.2/browser/board-livecards-runtime-client.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/leader-line/leader-line.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@6.0.0/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@6.0.0/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@6.0.0/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@6.0.0/browser/board-livecards-runtime-client.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">
@@ -68,7 +69,7 @@
   <script>
     (function () {
       const { buildLiveCardModelsFromArtifacts } = window.BoardLiveGraph || {};
-      let currentMode = 'board';
+      let currentMode = 'canvas';
       let bootstrapCompleted = false;
       let activeBoardId = 'default';
       let runtimeClient = null;