npm - yaml-flow - Versions diffs - 5.1.0 → 5.2.0 - Mend

yaml-flow 5.1.0 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (105) hide show

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

@@ -5,11 +5,21 @@
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>Example Board Demo (Server Runtime)</title>
   <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" />
+  <style>
+    /* Scale down markdown headings inside cards to stay in proportion with card body text */
+    .lc-result h1 { font-size: 1rem;   font-weight: 700; margin: 0.5rem 0 0.25rem; }
+    .lc-result h2 { font-size: 0.9rem; font-weight: 700; margin: 0.5rem 0 0.25rem; border-bottom: 1px solid #dee2e6; padding-bottom: 0.1rem; }
+    .lc-result h3 { font-size: 0.85rem; font-weight: 600; margin: 0.4rem 0 0.2rem; }
+    .lc-result p  { font-size: 0.8rem; margin: 0 0 0.25rem; }
+    .lc-result ul, .lc-result ol { font-size: 0.8rem; margin: 0 0 0.25rem; padding-left: 1.2rem; }
+    .lc-result li { margin-bottom: 0.15rem; }
+  </style>
   <script src="https://cdn.jsdelivr.net/npm/jsonata/jsonata.min.js"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/card-compute.js" onerror="this.onerror=null;this.src='../../browser/card-compute.js';"></script>
-  <script src="https://cdn.jsdelivr.net/npm/yaml-flow@latest/browser/live-cards.js" onerror="this.onerror=null;this.src='../../browser/live-cards.js';"></script>
-  <script src="./reusable-runtime-artifacts-adapter.js"></script>
-  <script src="./reusable-board-runtime-client.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow/browser/card-compute.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow/browser/live-cards.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow/browser/board-livegraph-engine.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/yaml-flow/browser/board-livecards-runtime-client.js"></script>
 </head>
 <body class="bg-light">
   <div class="container-fluid py-3">
@@ -19,7 +29,6 @@
         <div class="small text-muted" id="boardDesc"></div>
       </div>
       <div class="d-flex align-items-center gap-2">
-        <a class="btn btn-sm btn-outline-secondary" href="demo-shell-browser.html">Open Browser Runtime Shell</a>
         <select class="form-select form-select-sm" id="boardSelector" style="max-width:180px" title="Active board"></select>
         <button class="btn btn-sm btn-outline-success" id="addBoardBtn">+ Board</button>
         <div id="addBoardForm" class="d-flex align-items-center gap-1" style="display:none!important">
@@ -44,10 +53,6 @@
       Source execution and event processing happen on the server side.
     </div>
-    <div class="alert alert-secondary small py-2 mb-3">
-      Contract and decision notes live in <a href="./demo-shell.html#assumptions-and-tradeoffs">Assumptions and Tradeoffs</a>.
-    </div>
     <div id="boardRoot">
       <div class="d-flex align-items-center justify-content-center" style="height: 72vh;">
         <div class="text-center">

package/examples/example-board/demo-shell.html CHANGED Viewed

@@ -17,7 +17,7 @@
           <div class="card-body">
             <h2 class="h5">Browser Runtime</h2>
             <p class="small text-muted mb-3">
-              Uses <code>board-livegraph-runtime.js</code> directly in-browser.
+              Uses <code>board-livegraph-engine.js</code> directly in-browser.
               Source definitions remain opaque and are executed by an in-page task executor shim.
             </p>
             <a class="btn btn-primary" href="./demo-shell-browser.html">Open Browser Runtime Shell</a>

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

@@ -6,23 +6,89 @@
  * Protocol (invoked by board-live-cards-cli):
  *   node demo-task-executor.js run-source-fetch --in <source.json> --out <result.json> [--err <error.txt>]
  *
- * Expected source definition:
- *   { "bindTo": "...", "outputFile": "...", "mock": "keyName" }
+ * Expected source definition (--in payload):
+ *   {
+ *     "bindTo": "...",
+ *     "outputFile": "...",
+ *     // custom fields authored on the source entry (e.g. mock, copilot, http, prompt_template, etc.)
+ *     "cwd": "<card directory>",
+ *     "boardDir": "<board runtime directory>",
+ *     "_requires": { },            // upstream token data (from card requires[])
+ *     "_sourcesData": { },         // already-fetched sources on this card
+ *     "_computed_values": { }      // computed_values from the card's compute stage
+ *   }
  *
- * Behavior:
- *   1. Read mock.db (JSON file next to this script)
- *   2. Look up source.mock value as a key in mock.db
- *   3. Write corresponding value to --out file (as JSON)
- *   4. Exit 0 on success, exit 1 on error
+ * Supported source kinds (based on custom fields):
+ *   - { mock: "key" }              → look up key in MOCK_DB (hardcoded below)
+ *   - { copilot: { prompt_template, args? } }  → call Copilot CLI with interpolated prompt
+ *   - { prompt_template: "..." }   → shorthand copilot call (top-level template)
+ *   - { http: { url, method?, headers?, args? }, tickersFrom? }  → HTTP fetch (Node 18+ fetch)
+ *   - { chartApi: { url, headers? }, tickersFrom }  → Yahoo Finance chart API, one request per ticker;
+ *     returns { quoteResponse: { result: [...] } } compatible with the quote API shape
+ *   A real executor can also handle: graphapi, teams, mail, incidentdb, script, etc.
+ *
+ * http / chartApi source notes:
+ *   - URL supports {{key}} interpolation (http) or {{ticker}} (chartApi)
+ *   - tickersFrom: "tokenName.fieldName" extracts tickers from a _requires array
+ *   - http and chartApi results are cached in os.tmpdir()/demo-executor-cache/ for 1 hour
+ *     so Yahoo Finance is not hammered on every card refresh during demos
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const MOCK_DB_PATH = path.join(__dirname, 'mock.db');
+// ---------------------------------------------------------------------------
+// Mock data — used when a source has { mock: "key" }.
+// Edit these values to change the demo data without needing a mock.db file.
+// ---------------------------------------------------------------------------
+const MOCK_DB = {
+  quotes: {
+    quoteResponse: {
+      result: [
+        { symbol: 'AAPL',  shortName: 'Apple Inc.',      regularMarketPrice: 198.15, regularMarketChange:  2.15, regularMarketChangePercent:  1.10 },
+        { symbol: 'MSFT',  shortName: 'Microsoft Corp.', regularMarketPrice: 415.32, regularMarketChange: -1.23, regularMarketChangePercent: -0.30 },
+        { symbol: 'GOOGL', shortName: 'Alphabet Inc.',   regularMarketPrice: 174.89, regularMarketChange:  0.89, regularMarketChangePercent:  0.51 },
+        { symbol: 'TSLA',  shortName: 'Tesla Inc.',      regularMarketPrice: 247.12, regularMarketChange:  5.43, regularMarketChangePercent:  2.25 },
+      ],
+      error: null,
+    },
+  },
+};
+// ---------------------------------------------------------------------------
+// Simple 1-hour file cache for HTTP / chartApi results.
+// Stored in os.tmpdir()/demo-executor-cache/<hash>.json
+// ---------------------------------------------------------------------------
+const CACHE_DIR = path.join(os.tmpdir(), 'demo-executor-cache');
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+function cacheKey(str) {
+  return crypto.createHash('sha1').update(str).digest('hex');
+}
+function readCache(key) {
+  const file = path.join(CACHE_DIR, `${key}.json`);
+  try {
+    const stat = fs.statSync(file);
+    if (Date.now() - stat.mtimeMs < CACHE_TTL_MS) {
+      return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+  } catch {}
+  return null;
+}
+function writeCache(key, value) {
+  try {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(path.join(CACHE_DIR, `${key}.json`), JSON.stringify(value));
+  } catch {}
+}
 function readJson(filePath) {
   return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
@@ -37,24 +103,57 @@ function interpolatePrompt(template, args) {
   });
 }
+/**
+ * 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).
+ */
+function curlFetchJson(url, method, headers) {
+  const bin = process.platform === 'win32' ? 'curl.exe' : 'curl';
+  // -s  : silent (no progress bar)
+  // -S  : show errors despite -s
+  // -f  : fail (non-zero exit) on HTTP 4xx/5xx
+  // -L  : follow redirects
+  // --max-time 10 : hard timeout
+  const args = ['-s', '-S', '-f', '-L', '--max-time', '10', '-X', method];
+  for (const [k, v] of Object.entries(headers)) {
+    args.push('-H', `${k}: ${v}`);
+  }
+  args.push(url);
+  const raw = execFileSync(bin, args, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+  return JSON.parse(raw);
+}
 function stripCopilotFooter(rawText) {
   const lines = String(rawText ?? '').split(/\r?\n/);
-  // Remove trailing blank lines first.
-  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
+  // Strip CLI-level tool-call telemetry lines emitted by the copilot binary when
+  // --allow-all activates MCP tools. These are NOT model output — the prompt cannot
+  // suppress them. They look like:
+  //   ● Web Search (MCP: github-mcp-server) · ...
+  //   └ {"type":"output_text",...}
+  const filtered = lines.filter(line => {
+    const t = line.trimStart();
+    return !(
+      /^[●•]\s+/.test(t) ||  // tool invocation lines
+      /^└\s+/.test(t)         // tool result lines
+    );
+  });
+  // Remove trailing blank lines.
+  while (filtered.length > 0 && filtered[filtered.length - 1].trim() === '') filtered.pop();
   // Remove the standard trailing Copilot metadata footer, if present.
   if (
-    lines.length >= 3 &&
-    /^Changes\b/i.test(lines[lines.length - 3]) &&
-    /^Requests\b/i.test(lines[lines.length - 2]) &&
-    /^Tokens\b/i.test(lines[lines.length - 1])
+    filtered.length >= 3 &&
+    /^Changes\b/i.test(filtered[filtered.length - 3]) &&
+    /^Requests\b/i.test(filtered[filtered.length - 2]) &&
+    /^Tokens\b/i.test(filtered[filtered.length - 1])
   ) {
-    lines.splice(lines.length - 3, 3);
+    filtered.splice(filtered.length - 3, 3);
   }
-  while (lines.length > 0 && lines[lines.length - 1].trim() === '') lines.pop();
-  return lines.join('\n');
+  while (filtered.length > 0 && filtered[filtered.length - 1].trim() === '') filtered.pop();
+  return filtered.join('\n');
 }
 function resolveCopilotPrompt(sourceDef) {
@@ -62,8 +161,16 @@ function resolveCopilotPrompt(sourceDef) {
   const template = cfg.prompt_template ?? sourceDef.prompt_template;
   const args = cfg.args ?? cfg.prompt_args ?? sourceDef.prompt_args ?? sourceDef.args ?? {};
-  // Merge explicit args with context from card-handler (_requires includes card-level computed values)
-  const interpolationContext = { ...sourceDef._requires, ...args };
+  // Merge all injected context for template interpolation.
+  // _requires = upstream token data, _computed_values = card compute stage outputs,
+  // _sourcesData = already-fetched sources on this card.
+  // Explicit args defined on the source take highest precedence.
+  const interpolationContext = {
+    ...sourceDef._requires,
+    ...sourceDef._sourcesData,
+    ...sourceDef._computed_values,
+    ...args,
+  };
   if (!template || typeof template !== 'string') return null;
   return interpolatePrompt(template, interpolationContext);
@@ -193,7 +300,121 @@ function runSourceFetchSubcommand(argv) {
   let resultValue;
-  if (sourceDef.copilot || sourceDef.prompt_template) {
+  if (sourceDef.chartApi) {
+    // ---------------------------------------------------------------------------
+    // chartApi source kind — Yahoo Finance v8/finance/chart (free, per-ticker)
+    // Uses curl (synchronous subprocess) to avoid Node.js libuv handle issues.
+    // ---------------------------------------------------------------------------
+    const chartCfg = sourceDef.chartApi;
+    const headers = { ...(chartCfg.headers || {}) };
+    // Extract tickers array from _requires via tickersFrom
+    let tickers = [];
+    if (sourceDef.tickersFrom) {
+      const dotIdx = sourceDef.tickersFrom.indexOf('.');
+      if (dotIdx > 0) {
+        const tokenName = sourceDef.tickersFrom.slice(0, dotIdx);
+        const fieldName = sourceDef.tickersFrom.slice(dotIdx + 1);
+        const arr = sourceDef._requires?.[tokenName];
+        if (Array.isArray(arr)) {
+          tickers = arr.map(h => h[fieldName]).filter(Boolean);
+        }
+      }
+    }
+    if (tickers.length === 0) {
+      console.warn('[demo-task-executor] chartApi: tickersFrom resolved to empty list — falling back to mock');
+    } else {
+      const chartCacheKey = cacheKey('chartApi:' + tickers.sort().join(',') + chartCfg.url);
+      const cached = readCache(chartCacheKey);
+      if (cached) {
+        console.warn(`[demo-task-executor] chartApi: cache hit for [${tickers.join(', ')}]`);
+        resultValue = cached;
+      } else {
+        try {
+          const results = [];
+          for (const ticker of tickers) {
+            const url = interpolatePrompt(chartCfg.url, { ticker });
+            const data = curlFetchJson(url, 'GET', headers);
+            const meta = data?.chart?.result?.[0]?.meta;
+            if (!meta) throw new Error(`No chart meta for ${ticker}`);
+            // Map to quote-compatible shape; compute change from chartPreviousClose
+            const price = meta.regularMarketPrice ?? 0;
+            const prevClose = meta.chartPreviousClose ?? price;
+            const change = price - prevClose;
+            const changePct = prevClose !== 0 ? (change / prevClose) * 100 : 0;
+            results.push({
+              symbol: meta.symbol ?? ticker,
+              shortName: meta.shortName ?? meta.longName ?? ticker,
+              regularMarketPrice: price,
+              regularMarketChange: change,
+              regularMarketChangePercent: changePct,
+            });
+          }
+          resultValue = { quoteResponse: { result: results, error: null } };
+          writeCache(chartCacheKey, resultValue);
+        } catch (chartErr) {
+          fail(`chartApi fetch failed: ${chartErr.message}`, errFile);
+        }
+      }
+    }
+    if (resultValue === undefined) {
+      fail('chartApi: no tickers resolved — cannot fetch', errFile);
+    }
+  } else if (sourceDef.http) {
+    // ---------------------------------------------------------------------------
+    // HTTP source kind — uses curl (synchronous subprocess)
+    // ---------------------------------------------------------------------------
+    const httpCfg = sourceDef.http;
+    // Build tickers string if tickersFrom is specified on the source
+    // e.g. tickersFrom: "holdings.ticker" → joins _requires.holdings[*].ticker with ','
+    const httpArgs = { ...(httpCfg.args || {}) };
+    if (sourceDef.tickersFrom) {
+      const dotIdx = sourceDef.tickersFrom.indexOf('.');
+      if (dotIdx > 0) {
+        const tokenName = sourceDef.tickersFrom.slice(0, dotIdx);
+        const fieldName = sourceDef.tickersFrom.slice(dotIdx + 1);
+        const arr = sourceDef._requires?.[tokenName];
+        if (Array.isArray(arr)) {
+          httpArgs.tickers = arr.map(h => h[fieldName]).filter(Boolean).join(',');
+        }
+      }
+    }
+    // Interpolate URL template with all available context
+    const urlContext = {
+      ...(sourceDef._requires || {}),
+      ...(sourceDef._computed_values || {}),
+      ...httpArgs,
+    };
+    const url = interpolatePrompt(httpCfg.url, urlContext);
+    const method = (httpCfg.method || 'GET').toUpperCase();
+    const headers = { ...(httpCfg.headers || {}) };
+    // Skip fetch entirely if tickers ended up empty (guard against empty ?symbols=)
+    const httpFetchSkipped = sourceDef.tickersFrom && !httpArgs.tickers;
+    const httpCacheKey = cacheKey(`http:${method}:${url}`);
+    const httpCached = readCache(httpCacheKey);
+    if (httpCached && !httpFetchSkipped) {
+      console.warn(`[demo-task-executor] http: cache hit for ${url}`);
+      resultValue = httpCached;
+    } else {
+      try {
+        if (httpFetchSkipped) {
+          throw new Error('tickersFrom resolved to empty list — skipping fetch');
+        }
+        resultValue = curlFetchJson(url, method, headers);
+        writeCache(httpCacheKey, resultValue);
+      } catch (httpErr) {
+        fail(`HTTP fetch failed: ${httpErr.message}`, errFile);
+      }
+    }
+  } else if (sourceDef.copilot || sourceDef.prompt_template) {
     const prompt = resolveCopilotPrompt(sourceDef);
     if (!prompt) {
       fail('Source definition missing copilot.prompt_template (or prompt_template)', errFile);
@@ -207,28 +428,23 @@ function runSourceFetchSubcommand(argv) {
       fail(`copilot invocation failed: ${msg}`, errFile);
     }
-    resultValue = stripCopilotFooter(rawOutput);
-  } else {
-    // Default mode: mockdb lookup
-    let mockDb;
+    const cleaned = stripCopilotFooter(rawOutput);
+    // If the response is a JSON object/array, parse it so downstream compute
+    // can reference fields directly (e.g. fetched_sources.analysis.mix).
     try {
-      if (!fs.existsSync(MOCK_DB_PATH)) {
-        fail(`mock.db not found at ${MOCK_DB_PATH}`, errFile);
-      }
-      mockDb = readJson(MOCK_DB_PATH);
-    } catch (err) {
-      fail(`Cannot parse mock.db: ${String(err && err.message || err)}`, errFile);
-    }
-    const mockKey = sourceDef.mock;
-    if (!mockKey) {
-      fail('Source definition missing "mock" field (key to lookup)', errFile);
+      const parsed = JSON.parse(cleaned);
+      resultValue = (parsed && typeof parsed === 'object') ? parsed : cleaned;
+    } catch {
+      resultValue = cleaned;
     }
-    resultValue = mockDb[mockKey];
+  } else if (sourceDef.mock) {
+    // MOCK_DB lookup — data hardcoded at the top of this file
+    resultValue = MOCK_DB[sourceDef.mock];
     if (resultValue === undefined) {
-      fail(`Key "${mockKey}" not found in mock.db`, errFile);
+      fail(`Key "${sourceDef.mock}" not found in MOCK_DB`, errFile);
     }
+  } else {
+    fail('Source definition has no recognised kind (copilot, http, chartApi, mock)', errFile);
   }
   // Write result to --out as JSON payload, same contract as current mock mode.
@@ -238,10 +454,9 @@ function runSourceFetchSubcommand(argv) {
     fail(`Cannot write output file: ${String(err && err.message || err)}`, errFile);
   }
-  process.exit(0);
 }
-function main() {
+async function main() {
   const sub = process.argv[2];
   if (sub === 'run-source-fetch') {
     runSourceFetchSubcommand(process.argv.slice(3));
@@ -252,4 +467,7 @@ function main() {
   process.exit(0);
 }
-main();
+main().catch(err => {
+  console.error(`[demo-task-executor] fatal: ${err && err.message || err}`);
+  process.exit(1);
+});

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "yaml-flow",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",
@@ -82,7 +82,9 @@
       "types": "./dist/runtime-artifacts/index.d.ts",
       "import": "./dist/runtime-artifacts/index.js",
       "require": "./dist/runtime-artifacts/index.cjs"
-    }
+    },
+    "./board-livecards-server-runtime": "./board-livecards-server-runtime.js",
+    "./package.json": "./package.json"
   },
   "browser": {
     "./stores/file": false
@@ -90,6 +92,7 @@
   "files": [
     "board-live-cards-cli.js",
     "step-machine-cli.js",
+    "board-livecards-server-runtime.js",
     "dist",
     "schema",
     "browser",
@@ -98,6 +101,7 @@
   "scripts": {
     "build": "tsup",
     "build:browser": "tsup --config tsup.browser.config.ts",
+    "build:example": "node example-board-src/build.js",
     "dev": "tsup --watch",
     "test": "vitest",
     "test:run": "vitest run",

package/schema/live-cards.schema.json CHANGED Viewed

@@ -100,9 +100,9 @@
     },
     "source_def": {
-      "description": "One source entry. The engine only cares about 'bindTo' (compute namespace key) and 'outputFile' (delivery signal). Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
+      "description": "One source entry. The engine requires 'bindTo' (compute namespace key) and 'outputFile' (delivery signal path). bindTo and outputFile must be unique across all sources in a card. Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
       "type": "object",
-      "required": ["bindTo"],
+      "required": ["bindTo", "outputFile"],
       "additionalProperties": true,
       "properties": {
         "bindTo":     { "type": "string",  "description": "Key under fetched_sources.* available in compute expressions" },
@@ -119,7 +119,7 @@
       "properties": {
         "id":        { "type": "string", "description": "Optional element ID for targeted updates" },
         "kind":      {
-          "enum": ["metric", "table", "chart", "form", "filter", "list",
+          "enum": ["metric", "table", "editable-table", "chart", "form", "filter", "list",
                    "notes", "todo", "alert", "narrative", "badge", "text",
                    "markdown", "custom", "actions"]
         },
@@ -227,7 +227,7 @@
     "view":     { "$ref": "#/definitions/view" },
     "card_data": {
       "type": "object",
-      "description": "Authored card data supplied in the card definition",
+      "description": "Authored card data and runtime metadata. Includes uploaded-file metadata maintained by host handlers and inference evaluation results.",
       "properties": {
         "files": {
           "type": "array",
@@ -255,6 +255,18 @@
             },
             "additionalProperties": false
           }
+        },
+        "llm_task_completion_inference": {
+          "type": "object",
+          "description": "Runtime state written by the inference adapter (advanced/undocumented). Prefer the standard sources → compute → provides pattern for LLM-based signals.",
+          "properties": {
+            "inferenceRequested": { "type": "string", "format": "date-time", "description": "Timestamp when the latest inference request was initiated" },
+            "inferenceCompletedAt": { "type": "string", "format": "date-time", "description": "Timestamp when the latest inference request completed" },
+            "isTaskCompleted": { "type": "boolean", "description": "Whether the task is considered complete by the adapter" },
+            "reasoning": { "type": "string", "description": "Explanation of completion decision" },
+            "evidence": { "type": "array", "description": "Supporting evidence from sources/compute" }
+          },
+          "additionalProperties": true
         }
       },
       "additionalProperties": true
@@ -268,6 +280,10 @@
       "type": "array",
       "description": "Ordered array of compute steps. Each reads card_data.*/requires.*/fetched_sources.*/computed_values.* and writes to ephemeral computed_values[bindTo].",
       "items": { "$ref": "#/definitions/compute_step" }
+    },
+    "when_is_task_completed": {
+      "type": "string",
+      "description": "Advanced/undocumented: invokes a registered inference adapter instead of the default source-delivery completion gate. Prefer the standard pattern: use an LLM-backed source, compute a verdict token, and publish it via provides."
     }
   }
 }