yaml-flow 5.1.0 → 5.2.0

package/examples/browser/boards/portfolio-tracker/portfolio-tracker-inference-adapter.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function parseArgs(argv) {
+  const inIdx = argv.indexOf('--in');
+  const outIdx = argv.indexOf('--out');
+  const errIdx = argv.indexOf('--err');
+  const inFile = inIdx !== -1 ? argv[inIdx + 1] : undefined;
+  const outFile = outIdx !== -1 ? argv[outIdx + 1] : undefined;
+  const errFile = errIdx !== -1 ? argv[errIdx + 1] : undefined;
+  if (!inFile || !outFile || !errFile) {
+    console.error('Usage: <adapter> run-inference --in <input.json> --out <output.json> --err <error.txt>');
+    process.exit(1);
+  }
+  return { inFile, outFile, errFile };
+}
+
+const envBoardDir = (process.env.BOARD_DIR ?? '').trim();
+
+function resolveSyncTmpFileCandidates(payload) {
+  const fileName = payload?.context?.card_data?.llm_task_completion_inference?.sync_tmp_file;
+  if (typeof fileName !== 'string' || !fileName.trim()) return [];
+
+  const cleaned = fileName.trim();
+  if (path.isAbsolute(cleaned)) {
+    return [cleaned];
+  }
+
+  return [
+    envBoardDir ? path.join(envBoardDir, cleaned) : '',
+    path.join(process.cwd(), cleaned),
+    path.join(process.cwd(), 'board-runtime', cleaned),
+    path.join(process.cwd(), '..', 'board-runtime', cleaned),
+  ].filter(Boolean);
+}
+
+function getReadableTmpFile(tmpCandidates) {
+  for (const tmpFile of tmpCandidates) {
+    if (!fs.existsSync(tmpFile)) continue;
+    const content = fs.readFileSync(tmpFile, 'utf-8').trim();
+    if (content) return { tmpFile, content };
+  }
+  return undefined;
+}
+
+function waitForTmpSyncInput(tmpCandidates, timeoutMs = 120000) {
+  const started = Date.now();
+
+  return new Promise((resolve, reject) => {
+    const interval = setInterval(() => {
+      if (Date.now() - started > timeoutMs) {
+        clearInterval(interval);
+        reject(new Error('Timed out waiting for sync tmp input'));
+      }
+
+      const ready = getReadableTmpFile(tmpCandidates);
+      if (!ready) return;
+
+      clearInterval(interval);
+      fs.writeFileSync(ready.tmpFile, '', 'utf-8');
+      resolve(ready);
+    }, 250);
+  });
+}
+
+function toNumber(value) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+function buildRiskAssessment(table, totalValue) {
+  const rows = Array.isArray(table) ? table : [];
+  const total = toNumber(totalValue);
+  const withWeights = rows.map((row) => {
+    const v = toNumber(row?.value);
+    return { symbol: String(row?.symbol ?? ''), value: v, weight: total > 0 ? v / total : 0 };
+  });
+  withWeights.sort((a, b) => b.weight - a.weight);
+  const largest = withWeights[0] ?? { symbol: 'N/A', weight: 0, value: 0 };
+  const concentrationPct = Math.round(largest.weight * 1000) / 10;
+  const concentrationFlag = largest.weight > 0.6;
+  const breadthFlag = withWeights.length < 3;
+
+  const statusText = concentrationFlag
+    ? `High concentration risk: ${largest.symbol} at ${concentrationPct}% of portfolio value.`
+    : `Risk appears moderate: largest position ${largest.symbol} at ${concentrationPct}% of portfolio value.`;
+
+  const evidence = [
+    `positions=${withWeights.length}`,
+    `largest=${largest.symbol}`,
+    `largest_weight=${concentrationPct}%`,
+    `total_value=${Math.round(total * 100) / 100}`,
+    `breadth_ok=${withWeights.length >= 3}`,
+    `concentration_ok=${largest.weight <= 0.6}`,
+    `risk_flag=${breadthFlag || concentrationFlag}`,
+  ].join('; ');
+
+  return { isTaskCompleted: true, reason: statusText, evidence };
+}
+
+function buildRebalancingPlan(table, totalValue, riskAssessment) {
+  const rows = Array.isArray(table) ? table : [];
+  const total = toNumber(totalValue);
+  const targetWeight = rows.length > 0 ? 1 / rows.length : 0;
+  const moves = rows
+    .map((row) => {
+      const symbol = String(row?.symbol ?? 'UNKNOWN');
+      const currentValue = toNumber(row?.value);
+      const currentWeight = total > 0 ? currentValue / total : 0;
+      const deltaWeight = targetWeight - currentWeight;
+      return {
+        symbol,
+        currentWeight,
+        deltaWeight,
+        action: deltaWeight > 0.03 ? 'BUY' : (deltaWeight < -0.03 ? 'SELL' : 'HOLD'),
+      };
+    })
+    .sort((a, b) => Math.abs(b.deltaWeight) - Math.abs(a.deltaWeight));
+
+  const topMoves = moves
+    .filter((m) => m.action !== 'HOLD')
+    .slice(0, 3)
+    .map((m) => `${m.action} ${m.symbol} (${Math.round(m.deltaWeight * 1000) / 10}pp)`);
+
+  const summary = topMoves.length > 0
+    ? `Rebalance toward equal-weight profile: ${topMoves.join(', ')}.`
+    : 'Current allocations are close to equal-weight; no major rebalance needed.';
+
+  const evidence = [
+    `positions=${rows.length}`,
+    `target_weight=${Math.round(targetWeight * 1000) / 10}%`,
+    `risk_assessment=${typeof riskAssessment === 'string' ? riskAssessment : 'n/a'}`,
+  ].join('; ');
+
+  return { isTaskCompleted: true, reason: summary, evidence };
+}
+
+async function main() {
+  const command = process.argv[2];
+  if (command !== 'run-inference') {
+    console.error(`Unknown command: ${command ?? '(none)'}`);
+    process.exit(1);
+  }
+
+  const { inFile, outFile, errFile } = parseArgs(process.argv.slice(3));
+
+  try {
+    const payload = JSON.parse(fs.readFileSync(inFile, 'utf-8'));
+    const tmpCandidates = resolveSyncTmpFileCandidates(payload);
+    if (tmpCandidates.length > 0) {
+      await waitForTmpSyncInput(tmpCandidates);
+    }
+
+    const taskName = String(payload?.taskName ?? '');
+    const context = payload?.context ?? {};
+    // Inputs arrive under context.requires (the card's declared dependencies)
+    const requires = context?.requires ?? {};
+    const table = requires?.table?.rows ?? requires?.table;
+    const totalValue = requires?.totalValue;
+    const riskAssessment = requires?.riskAssessment;
+
+    let result;
+    if (taskName === 'portfolio-risk-assessment') {
+      result = buildRiskAssessment(table, totalValue);
+    } else if (taskName === 'rebalancing-strategy') {
+      result = buildRebalancingPlan(table, totalValue, riskAssessment);
+    } else {
+      result = {
+        isTaskCompleted: true,
+        reason: `Inference completed for ${taskName || 'unknown-task'}`,
+        evidence: 'deterministic-demo-adapter',
+      };
+    }
+
+    fs.writeFileSync(outFile, JSON.stringify(result), 'utf-8');
+    fs.writeFileSync(errFile, '', 'utf-8');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    fs.writeFileSync(errFile, message, 'utf-8');
+    fs.writeFileSync(outFile, JSON.stringify({ isTaskCompleted: false, reason: message, evidence: '' }), 'utf-8');
+    process.exit(1);
+  }
+}
+
+void main();

package/examples/browser/boards/portfolio-tracker/portfolio-tracker.js

@@ -31,6 +31,9 @@ const RUNTIME_ROOT = fs.mkdtempSync(path.join(os.tmpdir(), 'portfolio-tracker-')
 const BOARD = path.join(RUNTIME_ROOT, 'board-runtime');
 const CARDS = path.join(RUNTIME_ROOT, 'cards');
 const TMP_FILE = path.join(BOARD, 'tmp_file1');
+const INFERENCE_TMP_FILE_2 = path.join(BOARD, 'tmp_file2');
+const INFERENCE_TMP_FILE_3 = path.join(BOARD, 'tmp_file3');
+const INFERENCE_ADAPTER = path.join(RUNTIME_ROOT, 'portfolio-tracker-inference-adapter.js');
 
 function parseArgs(argv) {
   let taskExecutor;
@@ -112,14 +115,24 @@ function statusText() {
 
 async function waitForAllCompleted(label, timeoutMs = 30000, pollMs = 500) {
   const start = Date.now();
+  const includeInferenceCards = fs.existsSync(path.join(CARDS, 'portfolio-risk-assessment.json'))
+    && fs.existsSync(path.join(CARDS, 'rebalancing-strategy.json'));
+
   while (Date.now() - start < timeoutMs) {
     const out = statusText();
-    const completed = [
+    const requiredCards = [
       /\bcompleted\s+portfolio-form\b/.test(out),
       /\bcompleted\s+price-fetch\b/.test(out),
       /\bcompleted\s+holdings-table\b/.test(out),
       /\bcompleted\s+portfolio-value\b/.test(out),
-    ].every(Boolean);
+    ];
+    if (includeInferenceCards) {
+      requiredCards.push(
+        /\bcompleted\s+portfolio-risk-assessment\b/.test(out),
+        /\bcompleted\s+rebalancing-strategy\b/.test(out),
+      );
+    }
+    const completed = requiredCards.every(Boolean);
 
     if (completed) {
       console.log(`${label}: all cards completed.`);
@@ -142,11 +155,39 @@ function writePrices(prices) {
   console.log(`Wrote prices: ${JSON.stringify(prices)}`);
 }
 
+function releaseInferenceAdapters(label) {
+  if (!fs.existsSync(BOARD)) {
+    fs.mkdirSync(BOARD, { recursive: true });
+  }
+  const signal = JSON.stringify({ stage: label, releasedAt: new Date().toISOString() });
+  fs.writeFileSync(INFERENCE_TMP_FILE_2, signal, 'utf-8');
+  fs.writeFileSync(INFERENCE_TMP_FILE_3, signal, 'utf-8');
+  console.log(`Released inference adapters for ${label}`);
+}
+
 function setupRuntimeCards() {
   fs.rmSync(CARDS, { recursive: true, force: true });
   fs.mkdirSync(RUNTIME_ROOT, { recursive: true });
   fs.cpSync(CARDS_TEMPLATE, CARDS, { recursive: true });
   fs.copyFileSync(path.join(__dirname, 'fetch-prices.js'), path.join(RUNTIME_ROOT, 'fetch-prices.js'));
+  fs.copyFileSync(path.join(__dirname, 'portfolio-tracker-inference-adapter.js'), INFERENCE_ADAPTER);
+}
+
+function printTaskExecutorLog() {
+  console.log('\n=== Task Executor Log (board-dir) ===');
+  const candidates = fs
+    .readdirSync(BOARD, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.jsonl') && entry.name.includes('executor'))
+    .map(entry => path.join(BOARD, entry.name));
+  const taskExecutorLog = candidates.find(p => path.basename(p) === 'task-executor.jsonl') ?? candidates[0];
+  if (!taskExecutorLog) {
+    console.log(`No task executor log found in board-dir: ${BOARD}`);
+    return;
+  }
+
+  console.log(`Log file: ${taskExecutorLog}`);
+  const content = fs.readFileSync(taskExecutorLog, 'utf-8');
+  process.stdout.write(content || '(empty)\n');
 }
 
 (async () => {
@@ -156,9 +197,9 @@ function setupRuntimeCards() {
   fs.rmSync(BOARD, { recursive: true, force: true });
 
   if (options.taskExecutor) {
-    cli('init', BOARD, '--task-executor', options.taskExecutor);
+    cli('init', BOARD, '--task-executor', options.taskExecutor, '--inference-adapter', INFERENCE_ADAPTER);
   } else {
-    cli('init', BOARD);
+    cli('init', BOARD, '--inference-adapter', INFERENCE_ADAPTER);
   }
   cli('add-cards', '--rg', BOARD, '--card-glob', path.join(CARDS, '*.json'));
 
@@ -167,6 +208,7 @@ function setupRuntimeCards() {
 
   console.log('\n=== T1: Writing market prices ===');
   writePrices({ AAPL: 198.50, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40, TSLA: 168.75 });
+  releaseInferenceAdapters('T1');
   await waitForAllCompleted('T1');
 
   console.log('\n--- T1 Status ---');
@@ -196,6 +238,7 @@ function setupRuntimeCards() {
   cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
   await sleep(500);
   writePrices({ AAPL: 198.50, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40, TSLA: 168.75 });
+  releaseInferenceAdapters('T2');
   await waitForAllCompleted('T2');
 
   console.log('\n--- T2 Status ---');
@@ -205,13 +248,104 @@ function setupRuntimeCards() {
   cli('retrigger', '--rg', BOARD, '--task', 'price-fetch');
   await sleep(500);
   writePrices({ AAPL: 205.00, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40, TSLA: 168.75 });
+  releaseInferenceAdapters('T3');
   await waitForAllCompleted('T3');
 
   console.log('\n--- T3 Status ---');
   process.stdout.write(statusText());
 
-  console.log('\n=== T4: Final board status ===');
+  console.log('\n=== T4: Rapid successive portfolio updates (3x queue stress) ===');
+  fs.writeFileSync(TMP_FILE, '', 'utf-8');
+
+  const portfolioFormV3 = {
+    id: 'portfolio-form',
+    meta: { title: 'Portfolio Holdings Form' },
+    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    card_data: {
+      holdings: [
+        { symbol: 'AAPL', qty: 50 },
+        { symbol: 'MSFT', qty: 30 },
+        { symbol: 'GOOG', qty: 100 },
+        { symbol: 'AMZN', qty: 40 },
+      ],
+    },
+    view: {
+      elements: [
+        { kind: 'table', label: 'Holdings', data: { bind: 'card_data.holdings', columns: ['symbol', 'qty'] } },
+      ],
+    },
+  };
+
+  const portfolioFormV4 = {
+    id: 'portfolio-form',
+    meta: { title: 'Portfolio Holdings Form' },
+    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    card_data: {
+      holdings: [
+        { symbol: 'AAPL', qty: 45 },
+        { symbol: 'MSFT', qty: 30 },
+        { symbol: 'GOOG', qty: 110 },
+        { symbol: 'TSLA', qty: 60 },
+      ],
+    },
+    view: {
+      elements: [
+        { kind: 'table', label: 'Holdings', data: { bind: 'card_data.holdings', columns: ['symbol', 'qty'] } },
+      ],
+    },
+  };
+
+  const portfolioFormV5 = {
+    id: 'portfolio-form',
+    meta: { title: 'Portfolio Holdings Form' },
+    provides: [{ bindTo: 'holdings', src: 'card_data.holdings' }],
+    card_data: {
+      holdings: [
+        { symbol: 'AAPL', qty: 40 },
+        { symbol: 'MSFT', qty: 35 },
+        { symbol: 'GOOG', qty: 120 },
+        { symbol: 'TSLA', qty: 70 },
+      ],
+    },
+    view: {
+      elements: [
+        { kind: 'table', label: 'Holdings', data: { bind: 'card_data.holdings', columns: ['symbol', 'qty'] } },
+      ],
+    },
+  };
+
+  // First update starts a source fetch request.
+  fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV3, null, 2));
+  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+
+  // Immediate second update should queue a newer checksum while the first request is in-flight.
+  fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV4, null, 2));
+  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+
+  // Immediate third update should overwrite queued checksum (latest-state wins).
+  fs.writeFileSync(portfolioFormPath, JSON.stringify(portfolioFormV5, null, 2));
+  cli('update-card', '--rg', BOARD, '--card-id', 'portfolio-form', '--restart');
+
+  // 7) wait for first request, then 8) write response prices for update #1 tickers.
+  // await readFetchRequest('T4 first fetch', ['AAPL', 'MSFT', 'GOOG', 'AMZN']);
+  writePrices({ AAPL: 205.00, MSFT: 425.30, GOOG: 178.90, AMZN: 192.40 });
+  releaseInferenceAdapters('T4-first');
+  await sleep(5000);
+
+  // 9) wait for second request, then 10) write response prices for update #5 tickers.
+  // await readFetchRequest('T4 second fetch', ['AAPL', 'MSFT', 'GOOG', 'TSLA']);
+  writePrices({ AAPL: 206.00, MSFT: 426.00, GOOG: 179.50, TSLA: 169.20 });
+  releaseInferenceAdapters('T4-second');
+
+  await waitForAllCompleted('T4');
+
+  console.log('\n--- T4 Status ---');
+  process.stdout.write(statusText());
+
+  console.log('\n=== T5: Final board status ===');
   process.stdout.write(statusText());
 
+  printTaskExecutorLog();
+
   console.log('\nPortfolio tracker completed successfully');
 })();

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

@@ -0,0 +1,28 @@
+# Card Design Principles & Layout Guide
+
+---
+
+## Card Design Principles
+
+- **Cards are not pages** — think post-it notes, not dashboards. The primary content (table, editable data) should be immediately visible, not buried below stacked metrics. Use at most one hero `metric`; collapse secondary summary figures into a single `text` line rather than multiple `metric` blocks.
+- **Single responsibility** — each card answers one question. If the title needs "and", split it.
+- **No redundancy across cards** — each column on a board should appear on exactly one card. If a value is already visible elsewhere, omit it; the user's eye can join cards mentally.
+- **Aggregations are distinct** — a metric that summarises data from another card (total, count, average) is not redundant — it is new information. Keep it.
+- **Separate input from output** — cards with editable elements (`editable-table`, `form`, `filter`) should stay lean; put heavy compute and display in a separate downstream card that `requires` the published token.
+- **Propagate data, not display** — use `provides` to pass data between cards; never duplicate a `sources[]` fetch for data another card already provides.
+- **KISS** — if you are unsure whether a field adds value, leave it out. A sparse card that is immediately readable is better than a dense card that requires study.
+
+---
+
+## Layout
+
+```json
+"layout": {
+  "board":  { "col": 4, "order": 5 },
+  "canvas": { "x": 300, "y": 400, "w": 280, "h": 180 }
+}
+```
+
+- `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.