yaml-flow 8.7.0 → 8.8.0

package/examples/board/test/server-http-test.js

@@ -6,7 +6,7 @@
  * Targets the 'live' board with --cards-pattern cardT* to load only the 3
  * test cards (cardT-portfolio, cardT-market-prices, cardT-portfolio-value).
  *
- * T0: init-board → SSE initial payload → wait for all cards to complete
+ * T0: /sse?one-shot bootstrap → SSE initial payload → wait for all cards to complete
  * T1: PATCH holdings (+1 row) → verify recomputation (holdings +1, positions +1)
  *
  * Usage:
@@ -14,7 +14,6 @@
  */
 
 import { spawn, spawnSync } from 'node:child_process';
-import { Worker } from 'node:worker_threads';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import http from 'node:http';
@@ -51,8 +50,17 @@ const RUN_ID = `run-${Date.now()}-${process.pid}-${Math.random().toString(36).sl
 const BOARD_ID = 'live';
 const BOARD_DIR = path.resolve(__dirname, '..');
 const SERVER_SCRIPT = path.resolve(BOARD_DIR, 'server', 'board-server.js');
-const SSE_WORKER_SCRIPT = path.join(__dirname, 'sse-worker.js');
-const CARD_PATTERN = 'cardT*';
+// Force the board server to start with zero cards; the test upserts the
+// three cardT-* fixtures itself in T0 so the SSE upsert/delta path is
+// exercised end-to-end.
+const CARD_PATTERN = '__none__*';
+const CARDS_DIR = path.resolve(BOARD_DIR, 'cards');
+const T0_CARD_FILES = [
+  'cardT-portfolio.json',
+  'cardT-market-prices.json',
+  'cardT-portfolio-value.json',
+];
+const T0_EXPECTED_CARD_IDS = ['card-market-prices', 'card-portfolio', 'card-portfolio-value'];
 const T2_FILE_CARD_ID = 'card-market-prices';
 const CHAT_CARD_ID = 'card-portfolio';
 
@@ -92,7 +100,6 @@ if (fs.existsSync(SETUP_DIR)) {
 // ---------------------------------------------------------------------------
 
 const NS = {
-  initialPayload: null,
   statusSummary: null,
   statusGeneration: 0,
   computedValues: {},
@@ -102,9 +109,6 @@ const NS = {
 
 function applyFrame(payload) {
   if (payload && Array.isArray(payload.cardDefinitions)) {
-    if (!NS.initialPayload && payload.cardDefinitions.length > 0) {
-      NS.initialPayload = payload;
-    }
     const summary = payload.statusSnapshot && payload.statusSnapshot.summary;
     if (summary) {
       NS.statusSummary = summary;
@@ -267,9 +271,6 @@ async function stopChildProcess(proc, label) {
   }
 }
 
-const waitForInitialPayload = (ms = 15_000) =>
-  waitUntil(() => NS.initialPayload || false, ms, 'initial SSE payload');
-
 const waitForAllCompleted = (ms = 60_000, label = 'all completed') =>
   waitUntil(() => {
     const s = NS.statusSummary;
@@ -502,12 +503,12 @@ console.log(`target: ${BASE}`);
 console.log(`card pattern: ${CARD_PATTERN}`);
 
 const serverProc = await startServer(PORT);
-let sseWorker = null;
+let boardSseClient = null;
 let chatSseClient = null;
 let chatSseClientId = '';
 
 try {
-  // ── T0: init-board, SSE connect, wait for initial completion ──
+  // ── T0: one-shot bootstrap, SSE connect, wait for initial completion ──
 
   // Register the 'live' board via POST (v8 runtime requires explicit registration)
   const regRes = await httpJson('POST', `http://127.0.0.1:${PORT}/api/boards`, { id: BOARD_ID, label: 'Live' });
@@ -515,51 +516,47 @@ try {
     `POST /api/boards returned ${regRes.status}: ${JSON.stringify(regRes.data)}`);
   console.log(`[setup] board '${BOARD_ID}' registered (${regRes.status})`);
 
-  console.log('\n=== T0 Step 1: init-board ===');
-  const initRes = await httpGet(`${BASE}/init-board`);
-  assert(initRes.status === 200, `init-board returned ${initRes.status}`);
-  console.log('[T0.1] init-board ok');
-
-  console.log('\n=== T0 Step 2: start SSE worker ===');
+  console.log('\n=== T0 Step 1: start SSE client (board expected empty) ===');
   const sseClientId = `server-http-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
   const sseUrl = `${BASE}/sse?clientId=${encodeURIComponent(sseClientId)}`;
-  sseWorker = new Worker(SSE_WORKER_SCRIPT, {
-    workerData: { sseUrl },
-  });
-  sseWorker.on('message', (msg) => {
-    if (msg.type === 'frame') applyFrame(msg.payload);
-    else if (msg.type === 'error') console.error(`[sse-worker] ${msg.message}`);
-  });
-  sseWorker.on('error', (err) => console.error(`[sse-worker] uncaught: ${err.message}`));
-
-  const initialPayload = await waitForInitialPayload();
-  const cardCount = Array.isArray(initialPayload.cardDefinitions) ? initialPayload.cardDefinitions.length : 0;
-  assert(cardCount === 3, `expected 3 cards (cardT*), got ${cardCount}`);
-  const cardIds = initialPayload.cardDefinitions.map(c => c.id).sort();
-  console.log(`[T0.2] SSE initial payload received (${cardCount} cards: ${cardIds.join(', ')})`);
+  boardSseClient = startSseClient(sseUrl, applyFrame);
+  // Give the streaming endpoint a moment to deliver the initial (empty) snapshot.
+  await wait(500);
+  console.log('[T0.1] SSE client connected');
+
+  console.log('\n=== T0 Step 2: upsert 3 cardT-* fixtures ===');
+  for (const fileName of T0_CARD_FILES) {
+    const cardJson = JSON.parse(fs.readFileSync(path.join(CARDS_DIR, fileName), 'utf-8'));
+    const cardId = cardJson?.id;
+    assert(typeof cardId === 'string' && cardId.length > 0, `fixture ${fileName} missing id`);
+    const upsertRes = await httpMcp('manage.upsert-card', {
+      card_id: cardId,
+      candidate_card_content: cardJson,
+    });
+    assert(upsertRes.status === 200, `manage.upsert-card(${cardId}) returned ${upsertRes.status}: ${JSON.stringify(upsertRes.data)}`);
+    assert(upsertRes.data?.status === 'success', `manage.upsert-card(${cardId}) failed: ${JSON.stringify(upsertRes.data)}`);
+    console.log(`[T0.2] upserted ${cardId}`);
+  }
 
-  console.log('\n=== T0 Step 3: wait for all cards to complete ===');
-  const t0Summary = await waitForAllCompleted(30_000, 'T0 initial completion');
+  console.log('\n=== T0 Step 3: wait for all 3 cards to complete via SSE ===');
+  const t0Summary = await waitUntil(() => {
+    const s = NS.statusSummary;
+    if (s && s.card_count === 3 && s.completed === 3) return s;
+    return false;
+  }, 60_000, 'T0 initial completion (3 cards)');
   assert(t0Summary.failed === 0, `T0 expected failed=0, got ${t0Summary.failed}`);
   console.log(`[T0.3] completed: ${JSON.stringify(t0Summary)}`);
 
   console.log('\n=== T0 Step 4: board-status cross-check ===');
-  const statusRes = await httpGet(`${BASE}/board-status`);
-  assert(statusRes.status === 200, `board-status returned ${statusRes.status}`);
-  const httpSummary = statusRes.data?.statusSnapshot?.summary;
-  assert(httpSummary, 'statusSnapshot.summary missing from board-status');
   const statusMcpRes = await httpMcp('inspect.board-runtime-status', {});
   assert(statusMcpRes.status === 200, `inspect.board-runtime-status returned ${statusMcpRes.status}`);
   assert(statusMcpRes.data?.status === 'success', `inspect.board-runtime-status failed: ${JSON.stringify(statusMcpRes.data)}`);
   const mcpSummary = statusMcpRes.data?.data?.summary;
   assert(mcpSummary, 'summary missing from inspect.board-runtime-status');
-  const comparableStatusKeys = ['card_count', 'completed', 'eligible', 'pending', 'blocked', 'in_progress', 'failed', 'unresolved'];
-  const httpComparableSummary = Object.fromEntries(comparableStatusKeys.map((key) => [key, httpSummary[key]]));
-  const mcpComparableSummary = Object.fromEntries(comparableStatusKeys.map((key) => [key, mcpSummary[key]]));
-  assert(JSON.stringify(httpComparableSummary) === JSON.stringify(mcpComparableSummary),
-    `HTTP board-status summary mismatch vs MCP summary: http=${JSON.stringify(httpComparableSummary)} mcp=${JSON.stringify(mcpComparableSummary)}`);
-  assert(httpSummary.completed === httpSummary.card_count, `not all complete: ${JSON.stringify(httpSummary)}`);
-  console.log(`[T0.4] board-status: ${JSON.stringify(httpSummary)}`);
+  assert(mcpSummary.card_count === T0_EXPECTED_CARD_IDS.length,
+    `expected card_count=${T0_EXPECTED_CARD_IDS.length}, got ${mcpSummary.card_count}`);
+  assert(mcpSummary.completed === mcpSummary.card_count, `not all complete: ${JSON.stringify(mcpSummary)}`);
+  console.log(`[T0.4] board-status: ${JSON.stringify(mcpSummary)}`);
 
   // Verify computed_values arrived for portfolio-value card
   const t0Positions = NS.computedValues['card-portfolio-value']?.positions;
@@ -634,30 +631,32 @@ try {
   if (skipT2) {
     console.log('\n=== T2: skipped (--skip-t2) ===');
   } else {
-    console.log('\n=== T2: plain file upload -> card_data.files -> download ===');
-    const t2CardBefore = await httpGet(`${BASE}/cards/${T2_FILE_CARD_ID}`);
+    console.log('\n=== T2: MCP file upload -> card_data.files -> download ===');
+    const t2CardBefore = await httpMcp('manage.read-card', { card_id: T2_FILE_CARD_ID });
     assert(t2CardBefore.status === 200, `T2 pre card read returned ${t2CardBefore.status}`);
-    const t2FilesBefore = Array.isArray(t2CardBefore.data?.card_data?.files)
-      ? t2CardBefore.data.card_data.files
+    const t2FilesBefore = Array.isArray(t2CardBefore.data?.data?.[0]?.card_data?.files)
+      ? t2CardBefore.data.data[0].card_data.files
       : [];
     const t2BeforeCount = t2FilesBefore.length;
 
     const t2UploadText = `plain-file-upload-${Date.now()}`;
     const t2UploadName = 't2-upload.txt';
-    const t2UploadRes = await httpUploadChatFile(
-      `${BASE}/cards/${T2_FILE_CARD_ID}/files`,
-      t2UploadName,
-      t2UploadText,
-    );
+    const t2UploadRes = await httpMcpControlplane('manage.upload-card-file', {
+      board_id: BOARD_ID,
+      card_id: T2_FILE_CARD_ID,
+      file_name: t2UploadName,
+      content_type: 'text/plain; charset=utf-8',
+      base64: Buffer.from(t2UploadText, 'utf-8').toString('base64'),
+    });
     assert(t2UploadRes.status === 200, `T2 file upload returned ${t2UploadRes.status}`);
-    const t2UploadedFile = t2UploadRes.data?.file;
+    const t2UploadedFile = t2UploadRes.data?.data?.file;
     assert(t2UploadedFile && typeof t2UploadedFile === 'object', 'T2 upload response missing file metadata');
     assert(String(t2UploadedFile?.name || '') === t2UploadName, 'T2 uploaded file name mismatch');
 
-    const t2CardAfter = await httpGet(`${BASE}/cards/${T2_FILE_CARD_ID}`);
+    const t2CardAfter = await httpMcp('manage.read-card', { card_id: T2_FILE_CARD_ID });
     assert(t2CardAfter.status === 200, `T2 post card read returned ${t2CardAfter.status}`);
-    const t2FilesAfter = Array.isArray(t2CardAfter.data?.card_data?.files)
-      ? t2CardAfter.data.card_data.files
+    const t2FilesAfter = Array.isArray(t2CardAfter.data?.data?.[0]?.card_data?.files)
+      ? t2CardAfter.data.data[0].card_data.files
       : [];
     assert(t2FilesAfter.length === t2BeforeCount + 1, `T2 expected files +1 (before=${t2BeforeCount}, after=${t2FilesAfter.length})`);
 
@@ -736,10 +735,10 @@ try {
       assert(subRes.status === 200, `chat subscribe returned ${subRes.status}`);
 
       t3Dbg('step 3: fetching pre-chat transcript');
-      const t2Before = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+      const t2Before = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
       t3Dbg(`step 3: pre-chat fetch returned status=${t2Before.status}`);
       assert(t2Before.status === 200, `T3 pre chats returned ${t2Before.status}`);
-      const t2BeforeMessages = Array.isArray(t2Before.data?.messages) ? t2Before.data.messages : [];
+      const t2BeforeMessages = Array.isArray(t2Before.data?.data?.messages) ? t2Before.data.data.messages : [];
       const t2BeforeCount = t2BeforeMessages.length;
       const t2EventStart = NS.chatEvents.length;
       const t2ProbePrompt = `Probe protocol validation ${Date.now()}`;
@@ -747,33 +746,42 @@ try {
 
       const t3TurnId = randomTurnId();
       t3Dbg(`step 4: posting probe chat-send (turn-id=${t3TurnId})`);
-      const t2SendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
-        actionType: 'chat-send',
-        payload: {
-          text: `${ECHO_PROBE_MARKER}${t2ProbePrompt}${ECHO_PROBE_MARKER}`,
-          'turn-id': t3TurnId,
+      const t2SendRes = await httpJson('POST', `${BASE}/mcp-actions`, {
+        tool: 'chat-send',
+        args: {
+          card_id: CHAT_CARD_ID,
+          payload: {
+            text: `${ECHO_PROBE_MARKER}${t2ProbePrompt}${ECHO_PROBE_MARKER}`,
+            'turn-id': t3TurnId,
+          },
         },
       });
       t3Dbg(`step 4: chat-send returned status=${t2SendRes.status}`);
       assert(t2SendRes.status === 200, `T3 chat-send returned ${t2SendRes.status}`);
 
       t3Dbg('step 5: waiting for ordered probe lifecycle on chat SSE');
-      const t2Lifecycle = await waitForChatPredicate((events) => {
-        return matchOrderedProbeLifecycle(events.slice(t2EventStart), {
-          beforeCount: t2BeforeCount,
-          beforeProcessing: false,
-          prompt: t2ProbePrompt,
-          inProgressText: PROBE_IN_PROGRESS_TEXT,
-        });
-      }, 45_000, 'T3 ordered lifecycle');
+      let t2Lifecycle;
+      try {
+        t2Lifecycle = await waitForChatPredicate((events) => {
+          return matchOrderedProbeLifecycle(events.slice(t2EventStart), {
+            beforeCount: t2BeforeCount,
+            beforeProcessing: false,
+            prompt: t2ProbePrompt,
+            inProgressText: PROBE_IN_PROGRESS_TEXT,
+          });
+        }, 45_000, 'T3 ordered lifecycle');
+      } catch (error) {
+        t3Dbg(`step 5: lifecycle timeout; events=${JSON.stringify(NS.chatEvents.slice(t2EventStart), null, 2)}`);
+        throw error;
+      }
       t3Dbg('step 5: ordered lifecycle observed');
       assert(!!t2Lifecycle, 'T3 ordered lifecycle not observed');
 
       t3Dbg('step 6: fetching post-chat transcript');
-      const t2After = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+      const t2After = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
       t3Dbg(`step 6: post-chat fetch returned status=${t2After.status}`);
       assert(t2After.status === 200, `T3 post chats returned ${t2After.status}`);
-      const t2AfterMessages = Array.isArray(t2After.data?.messages) ? t2After.data.messages : [];
+      const t2AfterMessages = Array.isArray(t2After.data?.data?.messages) ? t2After.data.data.messages : [];
       const t2NewMessages = t2AfterMessages.slice(t2BeforeCount);
       t3Dbg(`step 6: validating ${t2NewMessages.length} new messages`);
       assert(t2NewMessages.length >= 3, `T3 expected at least 3 new chat messages, got ${t2NewMessages.length}`);
@@ -815,24 +823,27 @@ try {
     console.log('\n=== T3a: non-probe chat protocol (expect paris) ===');
     const t3aDbg = (msg) => console.log(`[T3a.DBG ${new Date().toISOString()}] ${msg}`);
     t3aDbg('step 1: fetching pre-chat transcript');
-    const t2aBefore = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    const t2aBefore = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
     t3aDbg(`step 1: pre-chat fetch returned status=${t2aBefore.status}`);
     assert(t2aBefore.status === 200, `T3a pre chats returned ${t2aBefore.status}`);
-    const t2aBeforeMessages = Array.isArray(t2aBefore.data?.messages) ? t2aBefore.data.messages : [];
+    const t2aBeforeMessages = Array.isArray(t2aBefore.data?.data?.messages) ? t2aBefore.data.data.messages : [];
     const t2aBeforeCount = t2aBeforeMessages.length;
     const t2aPrompt = 'Just answer what is the capital of France. No Fluff. No COmmentary.  No Markup Respond in lower case in one word.';
     t3aDbg(`step 1: beforeCount=${t2aBeforeCount}`);
 
     const t3aTurnId = randomTurnId();
     t3aDbg(`step 2: posting non-probe chat-send (turn-id=${t3aTurnId})`);
-    const t2aSendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
-      actionType: 'chat-send',
-      payload: {
-        text: JSON.stringify({
-          prompt: t2aPrompt,
-          chatTimeoutMs: 180000,
-        }),
-        'turn-id': t3aTurnId,
+    const t2aSendRes = await httpJson('POST', `${BASE}/mcp-actions`, {
+      tool: 'chat-send',
+      args: {
+        card_id: CHAT_CARD_ID,
+        payload: {
+          text: JSON.stringify({
+            prompt: t2aPrompt,
+            chatTimeoutMs: 180000,
+          }),
+          'turn-id': t3aTurnId,
+        },
       },
     });
     t3aDbg(`step 2: chat-send returned status=${t2aSendRes.status}`);
@@ -854,10 +865,10 @@ try {
     t3aDbg(`step 3: assistant SSE text=${JSON.stringify(String(t2aSseLast?.text || '').slice(0, 400))}`);
 
     t3aDbg('step 4: fetching post-chat transcript');
-    const t2aAfter = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    const t2aAfter = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
     t3aDbg(`step 4: post-chat fetch returned status=${t2aAfter.status}`);
     assert(t2aAfter.status === 200, `T3a post chats returned ${t2aAfter.status}`);
-    const t2aAfterMessages = Array.isArray(t2aAfter.data?.messages) ? t2aAfter.data.messages : [];
+    const t2aAfterMessages = Array.isArray(t2aAfter.data?.data?.messages) ? t2aAfter.data.data.messages : [];
     const t2aNewMessages = t2aAfterMessages.slice(t2aBeforeCount);
     t3aDbg(`step 4: validating ${t2aNewMessages.length} new messages`);
     assert(t2aNewMessages.length >= 2, `T3a expected at least 2 new chat messages, got ${t2aNewMessages.length}`);
@@ -873,33 +884,36 @@ try {
     console.log('\n=== T3b: skipped (--skip-t3b) ===');
   } else {
     console.log('\n=== T3b: probe-echo chat with file upload protocol ===');
-    const t2bBefore = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    const t2bBefore = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
     assert(t2bBefore.status === 200, `T3b pre chats returned ${t2bBefore.status}`);
-    const t2bBeforeMessages = Array.isArray(t2bBefore.data?.messages) ? t2bBefore.data.messages : [];
+    const t2bBeforeMessages = Array.isArray(t2bBefore.data?.data?.messages) ? t2bBefore.data.data.messages : [];
     const t2bBeforeCount = t2bBeforeMessages.length;
 
     const t3bTurnId = randomTurnId();
-    const t2bUploadRes = await httpUploadChatFile(
-      `${BASE}/cards/${CHAT_CARD_ID}/files?inChat=true&turn-id=${encodeURIComponent(t3bTurnId)}`,
-      'q1.txt',
-      'tokyo',
-    );
+    const t2bUploadRes = await httpMcpControlplane('manage.add-chat-attachment', {
+      board_id: BOARD_ID,
+      card_id: CHAT_CARD_ID,
+      turn_id: t3bTurnId,
+      file_name: 'q1.txt',
+      content_type: 'text/plain; charset=utf-8',
+      base64: Buffer.from('tokyo', 'utf-8').toString('base64'),
+    });
     assert(t2bUploadRes.status === 200, `T3b file upload returned ${t2bUploadRes.status}`);
-    const uploadedFile = t2bUploadRes.data?.file;
+    const uploadedFile = t2bUploadRes.data?.data?.files?.[0];
     assert(uploadedFile && typeof uploadedFile === 'object', 'T3b upload response missing file metadata');
 
-    const t2bAfterUpload = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    const t2bAfterUpload = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
     assert(t2bAfterUpload.status === 200, `T3b chats after upload returned ${t2bAfterUpload.status}`);
-    const t2bUploadMessages = Array.isArray(t2bAfterUpload.data?.messages) ? t2bAfterUpload.data.messages : [];
+    const t2bUploadMessages = Array.isArray(t2bAfterUpload.data?.data?.messages) ? t2bAfterUpload.data.data.messages : [];
     const t2bUploadNewMessages = t2bUploadMessages.slice(t2bBeforeCount);
     const t2bUploadSystem = t2bUploadNewMessages.find((m) => m?.role === 'system');
     assert(!!t2bUploadSystem, 'T3b upload protocol missing system chat file');
     assert(String(t2bUploadSystem?.text || '').toLowerCase().includes('file uploaded:'), 'T3b upload system message does not describe uploaded file');
 
-    const t2bCardAfterUpload = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}`);
+    const t2bCardAfterUpload = await httpMcp('manage.read-card', { card_id: CHAT_CARD_ID });
     assert(t2bCardAfterUpload.status === 200, `T3b card read after upload returned ${t2bCardAfterUpload.status}`);
-    const t2bFilesAfterUpload = Array.isArray(t2bCardAfterUpload.data?.card_data?.files)
-      ? t2bCardAfterUpload.data.card_data.files
+    const t2bFilesAfterUpload = Array.isArray(t2bCardAfterUpload.data?.data?.[0]?.card_data?.files)
+      ? t2bCardAfterUpload.data.data[0].card_data.files
       : [];
     const t2bFileIndex = t2bFilesAfterUpload.findIndex((f) => String(f?.stored_name || '') === String(uploadedFile?.stored_name || ''));
     assert(t2bFileIndex >= 0, 'T3b uploaded file metadata not found in card_data.files');
@@ -914,12 +928,14 @@ try {
     const t2bEventStart = NS.chatEvents.length;
 
     const t2bPrompt = `probe echo file-upload validation ${Date.now()}`;
-    const t2bSendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
-      actionType: 'chat-send',
-      payload: {
-        text: `${ECHO_PROBE_MARKER}${t2bPrompt}${ECHO_PROBE_MARKER}`,
-        files: [uploadedFile],
-        'turn-id': t3bTurnId,
+    const t2bSendRes = await httpJson('POST', `${BASE}/mcp-actions`, {
+      tool: 'chat-send',
+      args: {
+        card_id: CHAT_CARD_ID,
+        payload: {
+          text: `${ECHO_PROBE_MARKER}${t2bPrompt}${ECHO_PROBE_MARKER}`,
+          'turn-id': t3bTurnId,
+        },
       },
     });
     assert(t2bSendRes.status === 200, `T3b chat-send returned ${t2bSendRes.status}`);
@@ -929,15 +945,27 @@ try {
         beforeCount: t2bSendBaseline,
         beforeProcessing: false,
         prompt: t2bPrompt,
-        assistantText: 'tokyo',
         inProgressText: PROBE_IN_PROGRESS_TEXT,
       });
-    }, 60_000, 'T3b ordered lifecycle');
+    }, 60_000, 'T3b ordered lifecycle').catch(async (err) => {
+      const t2bEvents = NS.chatEvents.slice(t2bEventStart);
+      const t2bMilestones = deriveProbeLifecycleMilestones(t2bEvents, {
+        beforeCount: t2bSendBaseline,
+        beforeProcessing: false,
+        prompt: t2bPrompt,
+        inProgressText: PROBE_IN_PROGRESS_TEXT,
+      });
+      const t2bCurrent = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
+      console.error('[T3b.DBG timeout] milestones=', JSON.stringify(t2bMilestones));
+      console.error('[T3b.DBG timeout] events=', JSON.stringify(t2bEvents));
+      console.error('[T3b.DBG timeout] inspect=', JSON.stringify(t2bCurrent?.data ?? null));
+      throw err;
+    });
     assert(!!t2bLifecycle, 'T3b ordered lifecycle not observed');
 
-    const t2bAfter = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    const t2bAfter = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
     assert(t2bAfter.status === 200, `T3b post chats returned ${t2bAfter.status}`);
-    const t2bAfterMessages = Array.isArray(t2bAfter.data?.messages) ? t2bAfter.data.messages : [];
+    const t2bAfterMessages = Array.isArray(t2bAfter.data?.data?.messages) ? t2bAfter.data.data.messages : [];
     const t2bNewMessages = t2bAfterMessages.slice(t2bSendBaseline);
     assert(t2bNewMessages.length >= 3, `T3b expected at least 3 chat messages after send, got ${t2bNewMessages.length}`);
 
@@ -948,9 +976,9 @@ try {
     assert(!!t2bUser && typeof t2bUser.id === 'string', 'T3b missing user chat message notification');
     assert(!!t2bInProgress && typeof t2bInProgress.id === 'string', 'T3b missing in-progress system chat message');
     assert(!!t2bAssistantMsg && typeof t2bAssistantMsg.id === 'string', 'T3b missing assistant chat message notification');
-    assert(Array.isArray(t2bUser?.files) && t2bUser.files.length === 1, 'T3b user chat message missing uploaded file metadata');
-    assert(String(t2bAssistantMsg?.text || '').trim() === 'tokyo', 'T3b assistant attachment content mismatch');
-    console.log('[T3b] ok: upload protocol and ordered probe lifecycle observed with attachment-derived assistant reply');
+    assert(!Array.isArray(t2bUser?.files) || t2bUser.files.length === 0, 'T3b user chat message should remain text-only after add-chat-attachment upload');
+    assert(String(t2bAssistantMsg?.text || '').includes(`Echo: ${t2bPrompt}`), 'T3b assistant probe echo mismatch');
+    console.log('[T3b] ok: add-chat-attachment upload plus text-only chat-send preserved the normal probe lifecycle');
   }
 
   // ── T3d: probe-echo chat with one AI-generated attachment ──
@@ -972,25 +1000,28 @@ try {
       t3dOwnedSseClient = true;
     }
 
-    const t2dBeforeChats = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    const t2dBeforeChats = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
     assert(t2dBeforeChats.status === 200, `T3d pre chats returned ${t2dBeforeChats.status}`);
-    const t2dBeforeMessages = Array.isArray(t2dBeforeChats.data?.messages) ? t2dBeforeChats.data.messages : [];
+    const t2dBeforeMessages = Array.isArray(t2dBeforeChats.data?.data?.messages) ? t2dBeforeChats.data.data.messages : [];
     const t2dBeforeCount = t2dBeforeMessages.length;
 
-    const t2dBeforeCard = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}`);
+    const t2dBeforeCard = await httpMcp('manage.read-card', { card_id: CHAT_CARD_ID });
     assert(t2dBeforeCard.status === 200, `T3d pre card returned ${t2dBeforeCard.status}`);
-    const t2dBeforeFiles = Array.isArray(t2dBeforeCard.data?.card_data?.files)
-      ? t2dBeforeCard.data.card_data.files
+    const t2dBeforeFiles = Array.isArray(t2dBeforeCard.data?.data?.[0]?.card_data?.files)
+      ? t2dBeforeCard.data.data[0].card_data.files
       : [];
 
     const t3dTurnId = randomTurnId();
     const t2dPrompt = `probe generated attachment validation ${Date.now()}`;
     const t2dEventStart = NS.chatEvents.length;
-    const t2dSendRes = await httpJson('POST', `${BASE}/cards/${CHAT_CARD_ID}/actions`, {
-      actionType: 'chat-send',
-      payload: {
-        text: `${ECHO_PROBE_MARKER}[attach] ${t2dPrompt}${ECHO_PROBE_MARKER}`,
-        'turn-id': t3dTurnId,
+    const t2dSendRes = await httpJson('POST', `${BASE}/mcp-actions`, {
+      tool: 'chat-send',
+      args: {
+        card_id: CHAT_CARD_ID,
+        payload: {
+          text: `${ECHO_PROBE_MARKER}[attach] ${t2dPrompt}${ECHO_PROBE_MARKER}`,
+          'turn-id': t3dTurnId,
+        },
       },
     });
     assert(t2dSendRes.status === 200, `T3d chat-send returned ${t2dSendRes.status}`);
@@ -1006,9 +1037,9 @@ try {
     }, 60_000, 'T3d ordered lifecycle');
     assert(!!t2dLifecycle, 'T3d ordered lifecycle not observed');
 
-    const t2dAfter = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}/chats?all-turns=true`);
+    const t2dAfter = await httpMcp('inspect.chat-messages-on-cards', { card_id: CHAT_CARD_ID, all_turns: true });
     assert(t2dAfter.status === 200, `T3d post chats returned ${t2dAfter.status}`);
-    const t2dAfterMessages = Array.isArray(t2dAfter.data?.messages) ? t2dAfter.data.messages : [];
+    const t2dAfterMessages = Array.isArray(t2dAfter.data?.data?.messages) ? t2dAfter.data.data.messages : [];
     const t2dNewMessages = t2dAfterMessages.slice(t2dBeforeCount);
     assert(t2dNewMessages.length >= 4, `T3d expected at least 4 chat messages after send, got ${t2dNewMessages.length}`);
 
@@ -1031,10 +1062,10 @@ try {
     const t2dFileIndex = Number.parseInt(t2dFileIndexMatch[1], 10);
     assert(Number.isInteger(t2dFileIndex) && t2dFileIndex >= 0, 'T3d AI-generated message file index should be non-negative');
 
-    const t2dAfterCard = await httpGet(`${BASE}/cards/${CHAT_CARD_ID}`);
+    const t2dAfterCard = await httpMcp('manage.read-card', { card_id: CHAT_CARD_ID });
     assert(t2dAfterCard.status === 200, `T3d post card returned ${t2dAfterCard.status}`);
-    const t2dAfterFiles = Array.isArray(t2dAfterCard.data?.card_data?.files)
-      ? t2dAfterCard.data.card_data.files
+    const t2dAfterFiles = Array.isArray(t2dAfterCard.data?.data?.[0]?.card_data?.files)
+      ? t2dAfterCard.data.data[0].card_data.files
       : [];
     assert(t2dAfterFiles.length === t2dBeforeFiles.length + 1, `T3d expected exactly one new stored file, got ${t2dAfterFiles.length - t2dBeforeFiles.length}`);
     const t2dStoredFile = t2dAfterFiles[t2dFileIndex];
@@ -1551,28 +1582,28 @@ try {
 
     const t5ThreadId = `thread-t5-${Date.now()}`;
     expectMcpSuccess(
-      await httpMcpControlplane('setstate.card-meta', { board_id: BOARD_ID, card_id: T5_CARD_ID, key: 'chat.foundry_thread_id', value: t5ThreadId }),
-      'T5 setstate.card-meta',
+      await httpMcpControlplane('setstate.card-private', { board_id: BOARD_ID, card_id: T5_CARD_ID, key: 'chat.foundry_thread_id', value: t5ThreadId }),
+      'T5 setstate.card-private',
     );
     const t5GetMeta = expectMcpSuccess(
-      await httpMcpControlplane('getstate.card-meta', { board_id: BOARD_ID, card_id: T5_CARD_ID, key: 'chat.foundry_thread_id' }),
-      'T5 getstate.card-meta',
+      await httpMcpControlplane('getstate.card-private', { board_id: BOARD_ID, card_id: T5_CARD_ID, key: 'chat.foundry_thread_id' }),
+      'T5 getstate.card-private',
     );
-    assert(t5GetMeta?.exists === true && t5GetMeta?.value === t5ThreadId, `T5 getstate.card-meta mismatch: ${JSON.stringify(t5GetMeta)}`);
+    assert(t5GetMeta?.exists === true && t5GetMeta?.value === t5ThreadId, `T5 getstate.card-private mismatch: ${JSON.stringify(t5GetMeta)}`);
 
     const t5ReadCards = expectMcpSuccess(
       await httpMcp('manage.read-card', { card_id: T5_CARD_ID }),
       'T5 manage.read-card meta-redaction',
     );
     const t5ReadCard = Array.isArray(t5ReadCards) ? t5ReadCards[0] : null;
-    assert(t5ReadCard && t5ReadCard.meta === undefined, 'T5 expected manage.read-card to redact top-level meta');
+    assert(t5ReadCard && t5ReadCard.__private === undefined, 'T5 expected manage.read-card to redact __private');
 
     const t5Inspect = expectMcpSuccess(
       await httpMcp('inspect.card-definition-and-runtime', { card_id: T5_CARD_ID }),
       'T5 inspect.card-definition-and-runtime meta-redaction',
     );
-    assert(t5Inspect?.card_definition_and_static_data?.meta === undefined, 'T5 expected inspect to redact card_definition_and_static_data.meta');
-    console.log('[T5] ok: regular /mcp surfaces redact card meta');
+    assert(t5Inspect?.card_definition_and_static_data?.__private === undefined, 'T5 expected inspect to redact card_definition_and_static_data.__private');
+    console.log('[T5] ok: regular /mcp surfaces redact __private');
 
     // ── T5: admin-only card round-trip ──────────────────────────────────────
     // 1. Read the existing card definition via the normal read-card path.
@@ -1610,34 +1641,32 @@ try {
     );
     const t5AdminCards = Array.isArray(t5AdminRead?.cards) ? t5AdminRead.cards : [];
     assert(t5AdminCards.length > 0, 'T5 expected admin-read-card to return the card');
-    assert(t5AdminCards[0]?.meta?.__visible_controlplane_only === true, `T5 expected meta.__visible_controlplane_only=true, got: ${JSON.stringify(t5AdminCards[0]?.meta)}`);
-    console.log('[T5] ok: manage.admin-read-card returns card with __visible_controlplane_only=true');
+    assert(t5AdminCards[0]?.__private?.visible_controlplane_only === true, `T5 expected __private.visible_controlplane_only=true, got: ${JSON.stringify(t5AdminCards[0]?.__private)}`);
+    console.log('[T5] ok: manage.admin-read-card returns card with __private.visible_controlplane_only=true');
 
-    // 5. Guard: setstate.card-meta must block changing the flag to a different value.
-    // key = 'chat.__visible_controlplane_only' passes the chat.* format check but contains
-    // the reserved segment, so it reaches the guard.
-    const t5MetaGuard = await httpMcpControlplane('setstate.card-meta', {
+    // 5. Guard: setstate.card-private must block changing the flag to a different value.
+    const t5MetaGuard = await httpMcpControlplane('setstate.card-private', {
       board_id: BOARD_ID,
       card_id: t5AdminCardId,
-      key: 'chat.__visible_controlplane_only',
+      key: 'chat.visible_controlplane_only',
       value: false,  // differs from current flag value (true) → must be rejected
     });
     assert(t5MetaGuard?.status !== 200,
-      `T5 expected setstate.card-meta to reject changing __visible_controlplane_only, got: ${JSON.stringify(t5MetaGuard)}`);
-    console.log('[T5] ok: setstate.card-meta blocked flag mutation (false != true)');
+      `T5 expected setstate.card-private to reject changing visible_controlplane_only, got: ${JSON.stringify(t5MetaGuard)}`);
+    console.log('[T5] ok: setstate.card-private blocked flag mutation (false != true)');
 
     // 6. Guard: same key with value matching the current flag (true) must pass (idempotent).
     const t5MetaIdempotent = expectMcpSuccess(
-      await httpMcpControlplane('setstate.card-meta', {
+      await httpMcpControlplane('setstate.card-private', {
         board_id: BOARD_ID,
         card_id: t5AdminCardId,
-        key: 'chat.__visible_controlplane_only',
+        key: 'chat.visible_controlplane_only',
         value: true,  // matches current flag value → idempotent, allowed
       }),
-      'T5 setstate.card-meta idempotent same-value',
+      'T5 setstate.card-private idempotent same-value',
     );
-    assert(t5MetaIdempotent, 'T5 expected setstate.card-meta to succeed with matching flag value');
-    console.log('[T5] ok: setstate.card-meta idempotent same-value allowed');
+    assert(t5MetaIdempotent, 'T5 expected setstate.card-private to succeed with matching flag value');
+    console.log('[T5] ok: setstate.card-private idempotent same-value allowed');
   }
   }
 
@@ -1649,8 +1678,8 @@ try {
     } catch { /* ignore */ }
   }
   if (chatSseClient) chatSseClient.close();
+  if (boardSseClient) boardSseClient.close();
   await stopChildProcess(serverProc, 'demo board server');
-  if (sseWorker) await sseWorker.terminate();
 
   // Clean up the test setup directory
   if (fs.existsSync(SETUP_DIR)) {

package/examples/board-firestore/server/worker.js

@@ -18,7 +18,7 @@
 
 import http from 'node:http';
 import { Buffer } from 'node:buffer';
-import { createSingleBoardServerRuntime } from 'yaml-flow/server-runtime-controlface';
+import { createSingleBoardServerRuntime } from 'yaml-flow/board-live-cards-server-runtime';
 import { createHostedBoardQueueLaneRegistry } from 'yaml-flow/server-jobs-queue-runner';
 import { startQueueLaneRunners } from 'yaml-flow/board-live-cards-node';
 import { initializeApp, cert, getApps } from 'firebase-admin/app';
@@ -55,8 +55,15 @@ const runtime = createSingleBoardServerRuntime({
       label: `Board — ${BOARD_ID}`,
       boardAdapter,
       baseRef: { kind: 'firestore', value: `boards/${BOARD_ID}` },
+      boardRuntimeStoreRef: makeRef('firestore', `boards/${BOARD_ID}/runtime-board`),
       cardStoreRef: makeRef('firestore', `boards/${BOARD_ID}/cards`),
       outputsStoreRef: makeRef('firestore', `boards/${BOARD_ID}/runtime-out`),
+      queueStoreRef: makeRef('firestore', `boards/${BOARD_ID}/runtime`),
+      fetchedSourcesStoreRef: makeRef('firestore', `boards/${BOARD_ID}/sources`),
+      chatStoreRef: makeRef('firestore', `boards/${BOARD_ID}/chat`),
+      artifactsStoreRef: makeRef('firestore', `boards/${BOARD_ID}/files`),
+      scratchStoreRef: makeRef('firestore', `boards/${BOARD_ID}/scratch`),
+      archiveStoreRef: makeRef('firestore', `boards/${BOARD_ID}/archive`),
     },
   ],
   invocationAdapter: {
@@ -80,6 +87,7 @@ const runtime = createSingleBoardServerRuntime({
 const stopRunners = startQueueLaneRunners(
   createHostedBoardQueueLaneRegistry({
     boardId: BOARD_ID,
+    queueStoreRef: makeRef('firestore', `boards/${BOARD_ID}/runtime`),
     runtime,
     boardAdapter,
     logger: {