yaml-flow 8.2.0 → 8.2.1

package/lib/{types-seTI8zta.d.cts → types-Bztd1KoK.d.cts}

@@ -1,6 +1,56 @@
-import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-W2zK59m0.cjs';
+import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-BLXbcBNk.cjs';
 import { ExecutionRef } from './execution-refs.cjs';
-import { a as KindValueRef } from './storage-interface-BhAON-gW.cjs';
+import { J as JournalStorage, K as KVStorage, a as KindValueRef } from './storage-interface-B6ecOulj.cjs';
+
+/**
+ * chat-storage-lib.ts
+ *
+ * ChatStorage interface + factories backed by JournalStorage (history) and
+ * KVStorage (processing state and config).
+ *
+ * Platform-free — no node:fs or node:crypto imports.
+ */
+
+interface ChatRecord {
+    /** Journal entry id — also used as SSE cursor. */
+    id: string;
+    role: string;
+    text: string;
+    files: unknown[];
+    updated_at: string;
+}
+interface ChatConfig {
+    systemPrompt?: string;
+}
+interface ChatReadAfterResult {
+    records: ChatRecord[];
+    /** Pass as cursor on the next call. Null when the journal is empty. */
+    cursor: string | null;
+}
+interface ChatStorage {
+    /** Append a message; returns the new entry id (usable as a cursor). */
+    append(cardId: string, role: string, text: string, files?: unknown[]): string;
+    /** Read all messages in insertion order. */
+    readAll(cardId: string): ChatRecord[];
+    /**
+     * Read messages appended after cursor.
+     * Pass null to read from the beginning.
+     */
+    readAfter(cardId: string, cursor: string | null): ChatReadAfterResult;
+    /** Remove all messages for this card. */
+    clear(cardId: string): void;
+    setProcessing(cardId: string, active: boolean): void;
+    isProcessing(cardId: string): boolean;
+    getConfig(cardId: string): ChatConfig;
+    setConfig(cardId: string, patch: Partial<ChatConfig>): void;
+}
+/**
+ * Create a ChatStorage backed by:
+ *  - journalFactory(cardId) → JournalStorage  (one per-card journal for history)
+ *  - kv                     → KVStorage       (shared processing flags + config)
+ */
+declare function createChatStorage(journalFactory: (cardId: string) => JournalStorage, kv: KVStorage): ChatStorage;
+declare function createInMemoryChatStorage(): ChatStorage;
 
 /**
  * server-runtime/types.ts
@@ -95,6 +145,8 @@ interface SingleBoardRuntimeOptions {
     boards: BoardContextConfig[];
     invocationAdapter: InvocationAdapter;
     chatFlowRunner?: ChatHandlerFlowRunner;
+    /** Chat storage backend. Defaults to an in-memory store when omitted. */
+    chatStorage?: ChatStorage;
     notificationTransport?: NotificationTransport;
     logger?: RuntimeLogger;
     serverUrl?: string;
@@ -165,4 +217,4 @@ interface RuntimeResponse {
     end(data?: string | Buffer): void;
 }
 
-export type { BoardContextConfig as B, ChatHandlerFlowRunner as C, DescribeEnvelope as D, InvocationAdapter as I, MultiBoardRuntimeOptions as M, NotificationTransport as N, RuntimeLogger as R, SingleBoardRuntimeOptions as S, MultiBoardRuntime as a, SingleBoardRuntime as b, RuntimeRequest as c, RuntimeResponse as d };
+export { type BoardContextConfig as B, type ChatHandlerFlowRunner as C, type DescribeEnvelope as D, type InvocationAdapter as I, type MultiBoardRuntimeOptions as M, type NotificationTransport as N, type RuntimeLogger as R, type SingleBoardRuntimeOptions as S, type MultiBoardRuntime as a, type SingleBoardRuntime as b, type ChatStorage as c, type RuntimeRequest as d, type RuntimeResponse as e, type ChatConfig as f, type ChatRecord as g, createChatStorage as h, createInMemoryChatStorage as i };

package/lib/{types-Bm7IFD7r.d.ts → types-D-xVWPdY.d.ts}

@@ -1,6 +1,56 @@
-import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-B8b_0k_j.js';
+import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-BZaNb2mi.js';
 import { ExecutionRef } from './execution-refs.js';
-import { a as KindValueRef } from './storage-interface-BhAON-gW.js';
+import { J as JournalStorage, K as KVStorage, a as KindValueRef } from './storage-interface-B6ecOulj.js';
+
+/**
+ * chat-storage-lib.ts
+ *
+ * ChatStorage interface + factories backed by JournalStorage (history) and
+ * KVStorage (processing state and config).
+ *
+ * Platform-free — no node:fs or node:crypto imports.
+ */
+
+interface ChatRecord {
+    /** Journal entry id — also used as SSE cursor. */
+    id: string;
+    role: string;
+    text: string;
+    files: unknown[];
+    updated_at: string;
+}
+interface ChatConfig {
+    systemPrompt?: string;
+}
+interface ChatReadAfterResult {
+    records: ChatRecord[];
+    /** Pass as cursor on the next call. Null when the journal is empty. */
+    cursor: string | null;
+}
+interface ChatStorage {
+    /** Append a message; returns the new entry id (usable as a cursor). */
+    append(cardId: string, role: string, text: string, files?: unknown[]): string;
+    /** Read all messages in insertion order. */
+    readAll(cardId: string): ChatRecord[];
+    /**
+     * Read messages appended after cursor.
+     * Pass null to read from the beginning.
+     */
+    readAfter(cardId: string, cursor: string | null): ChatReadAfterResult;
+    /** Remove all messages for this card. */
+    clear(cardId: string): void;
+    setProcessing(cardId: string, active: boolean): void;
+    isProcessing(cardId: string): boolean;
+    getConfig(cardId: string): ChatConfig;
+    setConfig(cardId: string, patch: Partial<ChatConfig>): void;
+}
+/**
+ * Create a ChatStorage backed by:
+ *  - journalFactory(cardId) → JournalStorage  (one per-card journal for history)
+ *  - kv                     → KVStorage       (shared processing flags + config)
+ */
+declare function createChatStorage(journalFactory: (cardId: string) => JournalStorage, kv: KVStorage): ChatStorage;
+declare function createInMemoryChatStorage(): ChatStorage;
 
 /**
  * server-runtime/types.ts
@@ -95,6 +145,8 @@ interface SingleBoardRuntimeOptions {
     boards: BoardContextConfig[];
     invocationAdapter: InvocationAdapter;
     chatFlowRunner?: ChatHandlerFlowRunner;
+    /** Chat storage backend. Defaults to an in-memory store when omitted. */
+    chatStorage?: ChatStorage;
     notificationTransport?: NotificationTransport;
     logger?: RuntimeLogger;
     serverUrl?: string;
@@ -165,4 +217,4 @@ interface RuntimeResponse {
     end(data?: string | Buffer): void;
 }
 
-export type { BoardContextConfig as B, ChatHandlerFlowRunner as C, DescribeEnvelope as D, InvocationAdapter as I, MultiBoardRuntimeOptions as M, NotificationTransport as N, RuntimeLogger as R, SingleBoardRuntimeOptions as S, MultiBoardRuntime as a, SingleBoardRuntime as b, RuntimeRequest as c, RuntimeResponse as d };
+export { type BoardContextConfig as B, type ChatHandlerFlowRunner as C, type DescribeEnvelope as D, type InvocationAdapter as I, type MultiBoardRuntimeOptions as M, type NotificationTransport as N, type RuntimeLogger as R, type SingleBoardRuntimeOptions as S, type MultiBoardRuntime as a, type SingleBoardRuntime as b, type ChatStorage as c, type RuntimeRequest as d, type RuntimeResponse as e, type ChatConfig as f, type ChatRecord as g, createChatStorage as h, createInMemoryChatStorage as i };

package/package.json

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

package/examples/board/demo-chat-copilot.flow.json

@@ -1,38 +0,0 @@
-{
-  "id": "demo-chat-copilot",
-  "settings": {
-    "start_step": "respond",
-    "max_total_steps": 5,
-    "timeout_ms": 120000
-  },
-  "steps": {
-    "respond": {
-      "description": "Run the Copilot-backed chat responder example",
-      "handler": {
-        "type": "ref",
-        "howToRun": "local-node",
-        "whatToRun": {
-          "kind": "fs-path",
-          "value": "./demo-chat-copilot.js"
-        },
-        "meta": "chat-handler"
-      },
-      "transitions": {
-        "success": "completed",
-        "failure": "failed"
-      }
-    }
-  },
-  "terminal_states": {
-    "completed": {
-      "description": "Copilot chat response completed",
-      "return_intent": "success",
-      "return_artifacts": false
-    },
-    "failed": {
-      "description": "Copilot chat response failed",
-      "return_intent": "failure",
-      "return_artifacts": false
-    }
-  }
-}

package/examples/board/demo-chat-copilot.js

@@ -1,185 +0,0 @@
-/**
- * demo-chat-copilot.js - Copilot-backed chat handler example for example-board.
- *
- * Invoked by reusable-server-runtime after a user message is persisted:
- *   node demo-chat-copilot.js --boardId <id> --cardId <id> --extraEncJson <base64json>
- *
- * extraEncJson decodes to:
- *   boardSetupRoot  — absolute path to board root (parent of runtime/, surface/, runtime-out/)
- *   boardRuntimeDir — relative subdir: 'runtime'
- *   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
- *
- * Invokes copilot_wrapper.bat with a prompt built from conversation history.
- * Session dir is per-card: os.tmpdir()/demo-chat-copilot-sessions/<boardId>_<cardId>
- */
-
-import * as fs   from 'node:fs';
-import * as path from 'node:path';
-import * as os   from 'node:os';
-import { spawnSync }     from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-
-const args = process.argv.slice(2);
-function getArg(name) {
-  const idx = args.indexOf(name);
-  return idx !== -1 && args[idx + 1] !== undefined ? args[idx + 1] : null;
-}
-
-const boardId     = getArg('--boardId') || '';
-const cardId      = getArg('--cardId') || '';
-const extraStr    = getArg('--extraEncJson') || '';
-
-function readJsonStdin() {
-  try {
-    const raw = fs.readFileSync(0, 'utf-8').trim();
-    if (!raw) return {};
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === 'object' ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-let extra = {};
-if (extraStr) {
-  try { extra = JSON.parse(Buffer.from(extraStr, 'base64').toString('utf-8')); }
-  catch { console.error('[demo-chat-copilot] bad --extraEncJson'); process.exit(0); }
-} else {
-  extra = readJsonStdin();
-}
-
-const {
-  boardSetupRoot,
-  boardRuntimeDir,
-  runtimeStatusDir,
-  cardsDir,
-  chatDir,
-  chatsBlobBasePath,
-  chatsKeyPrefix,
-  chatProcessingMarkerKey,
-  lastChatFile,
-  serverUrl,
-} = extra;
-
-const chatDirAbs = chatDir || (
-  chatsBlobBasePath && chatsKeyPrefix
-    ? path.join(String(chatsBlobBasePath), String(chatsKeyPrefix).split('/')[0])
-    : null
-);
-
-if (!boardSetupRoot || !chatDirAbs || !lastChatFile) {
-  console.error('[demo-chat-copilot] missing boardSetupRoot/chatDir/lastChatFile');
-  process.exit(0);
-}
-
-const boardRuntimeDirAbs  = path.join(boardSetupRoot, boardRuntimeDir  || 'runtime');
-const runtimeStatusDirAbs = path.join(boardSetupRoot, runtimeStatusDir || 'runtime-out');
-const cardsDirAbs         = path.join(boardSetupRoot, cardsDir         || path.join('surface', 'tmp-cards'));
-
-function readHistory(dir) {
-  try {
-    return fs.readdirSync(dir)
-      .filter(f => /^\d+[-_](user|assistant)\.txt$/i.test(f))
-      .sort()
-      .map(f => {
-        const role = /user/i.test(f) ? 'User' : 'Assistant';
-        let text = '';
-        try { text = fs.readFileSync(path.join(dir, f), 'utf-8').trim(); } catch {}
-        return role + ': ' + text;
-      });
-  } catch { return []; }
-}
-
-function buildPrompt(cId, bId, history, responseFileRel) {
-  const cardSetupDirRel  = path.join(cardsDir, cId).replace(/\\/g, '/');
-  const runtimeDirRel    = boardRuntimeDir  || 'runtime';
-  const statusDirRel     = runtimeStatusDir || 'runtime-out';
-  const chatDirRel       = path.relative(boardSetupRoot, chatDirAbs).replace(/\\/g, '/');
-  const lastQueryFileRel = path.join(chatDirRel, lastChatFile).replace(/\\/g, '/');
-
-  const contextBlock = [
-    'We are currently doing a three way orchestration.',
-    'You are the responder who has context of the cards in ' + cardSetupDirRel + ',',
-    'card runtime statuses in ' + runtimeDirRel + ',',
-    'and computed outputs in ' + statusDirRel + '.',
-    'I am just a mediator passing on the query.',
-    'The user sees the data available in cards which is rendered, and the status from ' + statusDirRel + '.',
-    'Everything else is internal detail not to be exposed to the user.',
-    'The conversation history can be found in ' + chatDirRel + ' and the last query is in ' + lastQueryFileRel + '.',
-    'Write your response to the user in ' + responseFileRel + ' (relative to your working directory).',
-    'Give me only a bare minimum log line on what you did — the response in ' + responseFileRel + ' is what the user will see.',
-    serverUrl ? 'The host server is available at ' + serverUrl + '.' : '',
-  ].join(' ');
-
-  return [
-    contextBlock,
-    '',
-    ...history,
-    'Assistant:',
-  ].join('\n');
-}
-
-function runWrapper(prompt, sessionDir, workingDir) {
-  const wrapperPath = path.join(__dirname, 'scripts', 'copilot_wrapper.bat');
-  const tmpBase     = os.tmpdir();
-  const ts          = Date.now();
-  const outFile     = path.join(tmpBase, 'dcc-out-' + cardId + '-' + ts + '.txt');
-  const promptFile  = path.join(tmpBase, 'dcc-prompt-' + cardId + '-' + ts + '.txt');
-
-  fs.mkdirSync(sessionDir, { recursive: true });
-  fs.writeFileSync(promptFile, prompt, 'utf-8');
-
-  try {
-    spawnSync('cmd.exe', [
-      '/c', wrapperPath,
-      outFile,
-      sessionDir,
-      workingDir,
-      '@' + promptFile,
-      'raw',
-      'demo-chat-copilot',
-    ], { stdio: 'inherit', timeout: 120000 });
-
-    return fs.existsSync(outFile) ? fs.readFileSync(outFile, 'utf-8').trim() : '';
-  } finally {
-    try { fs.unlinkSync(promptFile); } catch {}
-    try { fs.unlinkSync(outFile);    } catch {}
-  }
-}
-
-const serialMatch     = String(lastChatFile).match(/^(\d+)/);
-const nextSerial      = serialMatch ? parseInt(serialMatch[1], 10) + 1 : 1;
-const nextName        = String(nextSerial).padStart(3, '0') + '-assistant.txt';
-const responseFileRel = path.relative(boardSetupRoot, path.join(chatDirAbs, nextName)).replace(/\\/g, '/');
-
-const history    = readHistory(chatDirAbs);
-const sessionDir = path.join(os.tmpdir(), 'demo-chat-copilot-sessions', boardId + '_' + cardId);
-const workingDir = boardSetupRoot;
-const prompt     = buildPrompt(cardId, boardId, history, responseFileRel);
-
-try {
-  runWrapper(prompt, sessionDir, workingDir);
-  console.log('[demo-chat-copilot] cardId="' + cardId + '" copilot invoked, response expected at ' + responseFileRel);
-} catch (err) {
-  console.error('[demo-chat-copilot] wrapper failed: ' + (err?.message ?? err));
-} finally {
-  cleanupProcessingMarker();
-}
-
-function cleanupProcessingMarker() {
-  if (chatProcessingMarkerKey) {
-    try {
-      const markerPath = path.join(cardsDirAbs, chatProcessingMarkerKey);
-      fs.unlinkSync(markerPath);
-      return;
-    } catch {}
-  }
-  try { fs.unlinkSync(path.join(chatDirAbs, '.processing')); } catch {}
-}

package/examples/board/demo-chat-echo.flow.json

@@ -1,38 +0,0 @@
-{
-  "id": "demo-chat-echo",
-  "settings": {
-    "start_step": "respond",
-    "max_total_steps": 5,
-    "timeout_ms": 10000
-  },
-  "steps": {
-    "respond": {
-      "description": "Echo the latest chat message back into the card chat log",
-      "handler": {
-        "type": "ref",
-        "howToRun": "local-node",
-        "whatToRun": {
-          "kind": "fs-path",
-          "value": "./demo-chat-echo.js"
-        },
-        "meta": "chat-handler"
-      },
-      "transitions": {
-        "success": "completed",
-        "failure": "failed"
-      }
-    }
-  },
-  "terminal_states": {
-    "completed": {
-      "description": "Echo chat response written",
-      "return_intent": "success",
-      "return_artifacts": false
-    },
-    "failed": {
-      "description": "Echo chat response failed",
-      "return_intent": "failure",
-      "return_artifacts": false
-    }
-  }
-}

package/examples/board/demo-chat-echo.js

@@ -1,92 +0,0 @@
-#!/usr/bin/env node
-
-import fs from 'node:fs';
-import path from 'node:path';
-import {
-  createArtifactsStore,
-  createChatArtifactsStore,
-  createFsBoardPlatformAdapter,
-  parseRef,
-  serializeRef,
-} from 'yaml-flow/board-live-cards-node';
-
-function readJsonStdin() {
-  try {
-    const raw = fs.readFileSync(0, 'utf-8').trim();
-    if (!raw) return {};
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === 'object' ? parsed : {};
-  } catch {
-    return {};
-  }
-}
-
-function resolveChatDir(extra) {
-  if (typeof extra.chatDir === 'string' && extra.chatDir.trim()) return extra.chatDir;
-  if (typeof extra.chatsBlobBasePath === 'string' && typeof extra.chatsKeyPrefix === 'string') {
-    const cardPart = String(extra.chatsKeyPrefix).split('/')[0];
-    return path.join(extra.chatsBlobBasePath, cardPart);
-  }
-  return '';
-}
-
-function resolveChatStoreContext(extra, chatDir) {
-  if (typeof extra.chatsBlobBasePath === 'string' && typeof extra.chatsKeyPrefix === 'string') {
-    return {
-      chatsRoot: extra.chatsBlobBasePath,
-      cardPrefix: String(extra.chatsKeyPrefix).split('/')[0],
-    };
-  }
-  if (chatDir) {
-    return {
-      chatsRoot: path.dirname(chatDir),
-      cardPrefix: path.basename(chatDir),
-    };
-  }
-  return { chatsRoot: '', cardPrefix: '' };
-}
-
-const extra = readJsonStdin();
-const chatDir = resolveChatDir(extra);
-const { chatsRoot, cardPrefix } = resolveChatStoreContext(extra, chatDir);
-const lastChatFile = typeof extra.lastChatFile === 'string' ? extra.lastChatFile : '';
-
-if (!chatDir || !lastChatFile || !chatsRoot || !cardPrefix) {
-  console.log(JSON.stringify({ result: 'failure', data: {}, error: 'missing chatDir/lastChatFile' }));
-  process.exit(0);
-}
-
-const lastChatPath = path.join(chatDir, lastChatFile);
-let userText = '';
-try {
-  userText = fs.readFileSync(lastChatPath, 'utf-8').trim();
-} catch {
-  console.log(JSON.stringify({ result: 'failure', data: {}, error: 'could not read last chat file' }));
-  process.exit(0);
-}
-
-const replyText = `Echo: ${userText}`;
-
-try {
-  const baseRef = parseRef(serializeRef({ kind: 'fs-path', value: chatsRoot }));
-  const adapter = createFsBoardPlatformAdapter(baseRef, { suppressSpawn: true });
-  const artifacts = createArtifactsStore(adapter.blobStorage(''));
-  const chats = createChatArtifactsStore(artifacts, { indexFileName: '.index.json' });
-  const serial = chats.nextSerial(cardPrefix);
-  const storedName = `${String(serial).padStart(3, '0')}_assistant.txt`;
-
-  artifacts.putText(`${cardPrefix}/${storedName}`, replyText + '\n', 'text/plain; charset=utf-8');
-  chats.appendIndexRecord(cardPrefix, {
-    serial,
-    role: 'assistant',
-    stored_name: storedName,
-    path: `${cardPrefix}/chats/${storedName}`,
-    updated_at: new Date().toISOString(),
-  });
-  if (typeof extra.chatProcessingMarkerKey === 'string' && extra.chatProcessingMarkerKey.trim()) {
-    artifacts.remove(extra.chatProcessingMarkerKey.trim());
-  }
-  console.log(JSON.stringify({ result: 'success', data: { replyFile: storedName, replyText } }));
-} catch (err) {
-  console.log(JSON.stringify({ result: 'failure', data: {}, error: err instanceof Error ? err.message : String(err) }));
-}

package/examples/board/demo-server-config.copilot-chat.json

@@ -1,10 +0,0 @@
-{
-  "port": 7799,
-  "cardsDir": "./cards",
-  "taskExecutorPath": "./demo-task-executor.js",
-  "chatHandlerFlowPath": "./demo-chat-copilot.flow.json",
-  "chatSessionsDir": "",
-  "gandalfCardsDir": "./gandalf-cards",
-  "gandalfTaskExecutorPath": "./demo-task-executor.js",
-  "gandalfChatHandlerFlowPath": "./demo-chat-copilot.flow.json"
-}

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

@@ -1,10 +0,0 @@
-{
-  "port": 7799,
-  "cardsDir": "./cards",
-  "taskExecutorPath": "./demo-task-executor.js",
-  "chatHandlerFlowPath": "./demo-chat-echo.flow.json",
-  "chatSessionsDir": "",
-  "gandalfCardsDir": "./gandalf-cards",
-  "gandalfTaskExecutorPath": "./demo-task-executor.js",
-  "gandalfChatHandlerFlowPath": "./demo-chat-echo.flow.json"
-}