yaml-flow 8.2.5 → 8.4.0

package/lib/chat-storage-lib-OX0Q_Ttf.d.cts

@@ -0,0 +1,53 @@
+import { J as JournalStorage, K as KVStorage } from './storage-interface-B-7pDHwD.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;
+
+export { type ChatRecord as C, type ChatReadAfterResult as a, type ChatConfig as b, type ChatStorage as c, createChatStorage as d, createInMemoryChatStorage as e };

package/lib/chat-store-public.cjs

@@ -0,0 +1,2 @@
+'use strict';function f(d){function o(r){return {status:"success",data:r}}function a(r){return {status:"fail",error:r}}function m(r){return {status:"error",error:r instanceof Error?r.message:String(r)}}function i(r,t="command envelope"){let n=typeof r.cardId=="string"?r.cardId:void 0;if(!r.command)return a(`chat-store: ${t} missing "command"`);if(!n)return a(`chat-store: ${t} missing "cardId"`);if(r.command==="append")return s.append({params:{cardId:n},body:{role:r.role,text:r.text,files:r.files}});if(r.command==="read-all")return s.readAll({params:{cardId:n}});if(r.command==="read-after")return s.readAfter({params:{cardId:n},body:{cursor:r.cursor??null}});if(r.command==="clear")return s.clear({params:{cardId:n}});if(r.command==="set-processing")return s.setProcessing({params:{cardId:n},body:{active:r.active}});if(r.command==="is-processing")return s.isProcessing({params:{cardId:n}});if(r.command==="get-config")return s.getConfig({params:{cardId:n}});if(r.command==="set-config"){let{command:e,cardId:u,...c}=r;return s.setConfig({params:{cardId:n},body:c})}return a(`chat-store: unknown command "${String(r.command)}"`)}function C(r){if(!Array.isArray(r.commands)||r.commands.length===0)return a('chat-store: command envelope must include a non-empty "commands" array');let t=[];for(let n=0;n<r.commands.length;n+=1){let e=r.commands[n];if(!e||typeof e!="object"||Array.isArray(e))return a(`chat-store: command envelope entry ${n} must be an object`);let u={cardId:r.cardId,...e},c=i(u,`command envelope entry ${n}`);if(c.status!=="success")return c;t.push({index:n,command:String(u.command),data:c.data});}return o({results:t})}let s={append(r){try{let t=r.params?.cardId;if(!t)return a("append requires params.cardId");let n=r.body??{},e=typeof n.role=="string"?n.role:"",u=typeof n.text=="string"?n.text:"",c=Array.isArray(n.files)?n.files:[];if(!e)return a("append requires body.role");let l=d.append(t,e,u,c);return o({id:l})}catch(t){return m(t)}},readAll(r){try{let t=r.params?.cardId;return t?o({records:d.readAll(t)}):a("readAll requires params.cardId")}catch(t){return m(t)}},readAfter(r){try{let t=r.params?.cardId;if(!t)return a("readAfter requires params.cardId");let e=(r.body??{}).cursor??null;return o(d.readAfter(t,e))}catch(t){return m(t)}},clear(r){try{let t=r.params?.cardId;return t?(d.clear(t),o({ok:!0})):a("clear requires params.cardId")}catch(t){return m(t)}},setProcessing(r){try{let t=r.params?.cardId;if(!t)return a("setProcessing requires params.cardId");let n=r.body??{};return typeof n.active!="boolean"?a("setProcessing requires body.active (boolean)"):(d.setProcessing(t,n.active),o({ok:!0}))}catch(t){return m(t)}},isProcessing(r){try{let t=r.params?.cardId;return t?o({active:d.isProcessing(t)}):a("isProcessing requires params.cardId")}catch(t){return m(t)}},getConfig(r){try{let t=r.params?.cardId;return t?o({config:d.getConfig(t)}):a("getConfig requires params.cardId")}catch(t){return m(t)}},setConfig(r){try{let t=r.params?.cardId;if(!t)return a("setConfig requires params.cardId");let n=r.body??{};return d.setConfig(t,n),o({ok:!0})}catch(t){return m(t)}},run:i,runBatch:C};return s}exports.createChatStorePublic=f;//# sourceMappingURL=chat-store-public.cjs.map
+//# sourceMappingURL=chat-store-public.cjs.map

package/lib/chat-store-public.d.cts

@@ -0,0 +1,128 @@
+import { C as CommandInput, a as CommandResult } from './board-live-cards-public-BM6jCEIa.cjs';
+import { C as ChatRecord, a as ChatReadAfterResult, b as ChatConfig, c as ChatStorage } from './chat-storage-lib-OX0Q_Ttf.cjs';
+import './storage-interface-B-7pDHwD.cjs';
+import './execution-refs.cjs';
+import './types-BBhqYGhE.cjs';
+
+/**
+ * chat-store-lib-public.ts
+ *
+ * Platform-free public API for ChatStorage operations.
+ *
+ * Follows the same CommandInput / CommandResult convention as
+ * card-store-lib-public.ts and artifacts-store-lib-public.ts.
+ * No platform code here — inject a ChatStorage built from your platform adapter.
+ *
+ * Usage:
+ *   import { createChatStorePublic } from './chat-store-lib-public.js';
+ *   import { createFsBoardChatStorage } from '../node/fs-board-adapter.js';
+ *
+ *   const store = createChatStorePublic(createFsBoardChatStorage(boardDir));
+ *   const result = store.append({ params: { cardId: 'c1' }, body: { role: 'user', text: 'hello' } });
+ *   const result = store.readAll({ params: { cardId: 'c1' } });
+ *   const result = store.readAfter({ params: { cardId: 'c1', cursor: '<id>' } });
+ *   const result = store.clear({ params: { cardId: 'c1' } });
+ *   const result = store.setProcessing({ params: { cardId: 'c1' }, body: { active: true } });
+ *   const result = store.isProcessing({ params: { cardId: 'c1' } });
+ *   const result = store.getConfig({ params: { cardId: 'c1' } });
+ *   const result = store.setConfig({ params: { cardId: 'c1' }, body: { systemPrompt: '...' } });
+ */
+
+type ChatStoreCommandName = 'append' | 'read-all' | 'read-after' | 'clear' | 'set-processing' | 'is-processing' | 'get-config' | 'set-config';
+type ChatStoreCommandEnvelope = {
+    command: ChatStoreCommandName;
+    cardId?: string;
+    role?: unknown;
+    text?: unknown;
+    files?: unknown;
+    cursor?: unknown;
+    active?: unknown;
+    [key: string]: unknown;
+};
+type ChatStoreCommandBatchEnvelope = {
+    cardId?: string;
+    commands: ChatStoreCommandEnvelope[];
+};
+type ChatStoreBatchResult = {
+    results: Array<{
+        index: number;
+        command: string;
+        data?: unknown;
+    }>;
+};
+interface ChatStorePublic {
+    /**
+     * Append a message to a card's chat history.
+     * params.cardId: string
+     * body.role: string
+     * body.text: string
+     * body.files?: unknown[]
+     */
+    append(input: CommandInput): CommandResult<{
+        id: string;
+    }>;
+    /**
+     * Read all messages for a card in insertion order.
+     * params.cardId: string
+     */
+    readAll(input: CommandInput): CommandResult<{
+        records: ChatRecord[];
+    }>;
+    /**
+     * Read messages appended after a cursor.
+     * params.cardId: string
+     * params.cursor?: string | null  (omit or null to read from the beginning)
+     */
+    readAfter(input: CommandInput): CommandResult<ChatReadAfterResult>;
+    /**
+     * Remove all messages for a card.
+     * params.cardId: string
+     */
+    clear(input: CommandInput): CommandResult<{
+        ok: true;
+    }>;
+    /**
+     * Set or clear the processing flag for a card.
+     * params.cardId: string
+     * body.active: boolean
+     */
+    setProcessing(input: CommandInput): CommandResult<{
+        ok: true;
+    }>;
+    /**
+     * Check whether a card is currently processing.
+     * params.cardId: string
+     */
+    isProcessing(input: CommandInput): CommandResult<{
+        active: boolean;
+    }>;
+    /**
+     * Read the chat config for a card.
+     * params.cardId: string
+     */
+    getConfig(input: CommandInput): CommandResult<{
+        config: ChatConfig;
+    }>;
+    /**
+     * Patch (merge) the chat config for a card.
+     * params.cardId: string
+     * body: Partial<ChatConfig>  e.g. { systemPrompt: '...' }
+     */
+    setConfig(input: CommandInput): CommandResult<{
+        ok: true;
+    }>;
+    /**
+     * Run a single command envelope against this store instance.
+     * The store is already bound to a backing adapter, so boardDir is not part
+     * of the public contract here.
+     */
+    run(envelope: ChatStoreCommandEnvelope, label?: string): CommandResult<unknown>;
+    /**
+     * Run a sequence of command envelopes with optional top-level cardId default.
+     * Stops on first non-success result and returns that failure/error.
+     */
+    runBatch(envelope: ChatStoreCommandBatchEnvelope): CommandResult<ChatStoreBatchResult>;
+}
+declare function createChatStorePublic(store: ChatStorage): ChatStorePublic;
+
+export { type ChatStoreBatchResult, type ChatStoreCommandBatchEnvelope, type ChatStoreCommandEnvelope, type ChatStoreCommandName, type ChatStorePublic, createChatStorePublic };

package/lib/chat-store-public.d.ts

@@ -0,0 +1,128 @@
+import { C as CommandInput, a as CommandResult } from './board-live-cards-public-Bz07XKRK.js';
+import { C as ChatRecord, a as ChatReadAfterResult, b as ChatConfig, c as ChatStorage } from './chat-storage-lib-DGaKrjVe.js';
+import './storage-interface-B-7pDHwD.js';
+import './execution-refs.js';
+import './types-BBhqYGhE.js';
+
+/**
+ * chat-store-lib-public.ts
+ *
+ * Platform-free public API for ChatStorage operations.
+ *
+ * Follows the same CommandInput / CommandResult convention as
+ * card-store-lib-public.ts and artifacts-store-lib-public.ts.
+ * No platform code here — inject a ChatStorage built from your platform adapter.
+ *
+ * Usage:
+ *   import { createChatStorePublic } from './chat-store-lib-public.js';
+ *   import { createFsBoardChatStorage } from '../node/fs-board-adapter.js';
+ *
+ *   const store = createChatStorePublic(createFsBoardChatStorage(boardDir));
+ *   const result = store.append({ params: { cardId: 'c1' }, body: { role: 'user', text: 'hello' } });
+ *   const result = store.readAll({ params: { cardId: 'c1' } });
+ *   const result = store.readAfter({ params: { cardId: 'c1', cursor: '<id>' } });
+ *   const result = store.clear({ params: { cardId: 'c1' } });
+ *   const result = store.setProcessing({ params: { cardId: 'c1' }, body: { active: true } });
+ *   const result = store.isProcessing({ params: { cardId: 'c1' } });
+ *   const result = store.getConfig({ params: { cardId: 'c1' } });
+ *   const result = store.setConfig({ params: { cardId: 'c1' }, body: { systemPrompt: '...' } });
+ */
+
+type ChatStoreCommandName = 'append' | 'read-all' | 'read-after' | 'clear' | 'set-processing' | 'is-processing' | 'get-config' | 'set-config';
+type ChatStoreCommandEnvelope = {
+    command: ChatStoreCommandName;
+    cardId?: string;
+    role?: unknown;
+    text?: unknown;
+    files?: unknown;
+    cursor?: unknown;
+    active?: unknown;
+    [key: string]: unknown;
+};
+type ChatStoreCommandBatchEnvelope = {
+    cardId?: string;
+    commands: ChatStoreCommandEnvelope[];
+};
+type ChatStoreBatchResult = {
+    results: Array<{
+        index: number;
+        command: string;
+        data?: unknown;
+    }>;
+};
+interface ChatStorePublic {
+    /**
+     * Append a message to a card's chat history.
+     * params.cardId: string
+     * body.role: string
+     * body.text: string
+     * body.files?: unknown[]
+     */
+    append(input: CommandInput): CommandResult<{
+        id: string;
+    }>;
+    /**
+     * Read all messages for a card in insertion order.
+     * params.cardId: string
+     */
+    readAll(input: CommandInput): CommandResult<{
+        records: ChatRecord[];
+    }>;
+    /**
+     * Read messages appended after a cursor.
+     * params.cardId: string
+     * params.cursor?: string | null  (omit or null to read from the beginning)
+     */
+    readAfter(input: CommandInput): CommandResult<ChatReadAfterResult>;
+    /**
+     * Remove all messages for a card.
+     * params.cardId: string
+     */
+    clear(input: CommandInput): CommandResult<{
+        ok: true;
+    }>;
+    /**
+     * Set or clear the processing flag for a card.
+     * params.cardId: string
+     * body.active: boolean
+     */
+    setProcessing(input: CommandInput): CommandResult<{
+        ok: true;
+    }>;
+    /**
+     * Check whether a card is currently processing.
+     * params.cardId: string
+     */
+    isProcessing(input: CommandInput): CommandResult<{
+        active: boolean;
+    }>;
+    /**
+     * Read the chat config for a card.
+     * params.cardId: string
+     */
+    getConfig(input: CommandInput): CommandResult<{
+        config: ChatConfig;
+    }>;
+    /**
+     * Patch (merge) the chat config for a card.
+     * params.cardId: string
+     * body: Partial<ChatConfig>  e.g. { systemPrompt: '...' }
+     */
+    setConfig(input: CommandInput): CommandResult<{
+        ok: true;
+    }>;
+    /**
+     * Run a single command envelope against this store instance.
+     * The store is already bound to a backing adapter, so boardDir is not part
+     * of the public contract here.
+     */
+    run(envelope: ChatStoreCommandEnvelope, label?: string): CommandResult<unknown>;
+    /**
+     * Run a sequence of command envelopes with optional top-level cardId default.
+     * Stops on first non-success result and returns that failure/error.
+     */
+    runBatch(envelope: ChatStoreCommandBatchEnvelope): CommandResult<ChatStoreBatchResult>;
+}
+declare function createChatStorePublic(store: ChatStorage): ChatStorePublic;
+
+export { type ChatStoreBatchResult, type ChatStoreCommandBatchEnvelope, type ChatStoreCommandEnvelope, type ChatStoreCommandName, type ChatStorePublic, createChatStorePublic };

package/lib/chat-store-public.js

@@ -0,0 +1,2 @@
+function f(d){function o(r){return {status:"success",data:r}}function a(r){return {status:"fail",error:r}}function m(r){return {status:"error",error:r instanceof Error?r.message:String(r)}}function i(r,t="command envelope"){let n=typeof r.cardId=="string"?r.cardId:void 0;if(!r.command)return a(`chat-store: ${t} missing "command"`);if(!n)return a(`chat-store: ${t} missing "cardId"`);if(r.command==="append")return s.append({params:{cardId:n},body:{role:r.role,text:r.text,files:r.files}});if(r.command==="read-all")return s.readAll({params:{cardId:n}});if(r.command==="read-after")return s.readAfter({params:{cardId:n},body:{cursor:r.cursor??null}});if(r.command==="clear")return s.clear({params:{cardId:n}});if(r.command==="set-processing")return s.setProcessing({params:{cardId:n},body:{active:r.active}});if(r.command==="is-processing")return s.isProcessing({params:{cardId:n}});if(r.command==="get-config")return s.getConfig({params:{cardId:n}});if(r.command==="set-config"){let{command:e,cardId:u,...c}=r;return s.setConfig({params:{cardId:n},body:c})}return a(`chat-store: unknown command "${String(r.command)}"`)}function C(r){if(!Array.isArray(r.commands)||r.commands.length===0)return a('chat-store: command envelope must include a non-empty "commands" array');let t=[];for(let n=0;n<r.commands.length;n+=1){let e=r.commands[n];if(!e||typeof e!="object"||Array.isArray(e))return a(`chat-store: command envelope entry ${n} must be an object`);let u={cardId:r.cardId,...e},c=i(u,`command envelope entry ${n}`);if(c.status!=="success")return c;t.push({index:n,command:String(u.command),data:c.data});}return o({results:t})}let s={append(r){try{let t=r.params?.cardId;if(!t)return a("append requires params.cardId");let n=r.body??{},e=typeof n.role=="string"?n.role:"",u=typeof n.text=="string"?n.text:"",c=Array.isArray(n.files)?n.files:[];if(!e)return a("append requires body.role");let l=d.append(t,e,u,c);return o({id:l})}catch(t){return m(t)}},readAll(r){try{let t=r.params?.cardId;return t?o({records:d.readAll(t)}):a("readAll requires params.cardId")}catch(t){return m(t)}},readAfter(r){try{let t=r.params?.cardId;if(!t)return a("readAfter requires params.cardId");let e=(r.body??{}).cursor??null;return o(d.readAfter(t,e))}catch(t){return m(t)}},clear(r){try{let t=r.params?.cardId;return t?(d.clear(t),o({ok:!0})):a("clear requires params.cardId")}catch(t){return m(t)}},setProcessing(r){try{let t=r.params?.cardId;if(!t)return a("setProcessing requires params.cardId");let n=r.body??{};return typeof n.active!="boolean"?a("setProcessing requires body.active (boolean)"):(d.setProcessing(t,n.active),o({ok:!0}))}catch(t){return m(t)}},isProcessing(r){try{let t=r.params?.cardId;return t?o({active:d.isProcessing(t)}):a("isProcessing requires params.cardId")}catch(t){return m(t)}},getConfig(r){try{let t=r.params?.cardId;return t?o({config:d.getConfig(t)}):a("getConfig requires params.cardId")}catch(t){return m(t)}},setConfig(r){try{let t=r.params?.cardId;if(!t)return a("setConfig requires params.cardId");let n=r.body??{};return d.setConfig(t,n),o({ok:!0})}catch(t){return m(t)}},run:i,runBatch:C};return s}export{f as createChatStorePublic};//# sourceMappingURL=chat-store-public.js.map
+//# sourceMappingURL=chat-store-public.js.map

package/lib/execution-refs.cjs

@@ -1,3 +1,3 @@
-'use strict';var s="b64:";function l(e){let r=new TextEncoder().encode(e),t=globalThis.Buffer,n;if(t)n=t.from(r).toString("base64");else if(typeof btoa=="function"){let o="";for(let a of r)o+=String.fromCharCode(a);n=btoa(o);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function i(e){return `${s}${l(JSON.stringify(e))}`}function c(e,r){let t;return /\.m?js$/i.test(e)?t="local-node":/\.py$/i.test(e)?t="local-python":t="local-process",{meta:"task-executor",howToRun:t,whatToRun:i({kind:"fs-path",value:e}),...r?{extra:r}:{}}}function f(e){return JSON.stringify(e)}function d(e){let r;try{r=JSON.parse(e);}catch{throw new Error(`parseExecutionRef: invalid JSON \u2014 ${e}`)}if(typeof r!="object"||r===null||typeof r.howToRun!="string"||typeof r.whatToRun!="string")throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun \u2014 ${e}`);return r}
+'use strict';var s="b64:";function l(e){let t=new TextEncoder().encode(e),r=globalThis.Buffer,n;if(r)n=r.from(t).toString("base64");else if(typeof btoa=="function"){let o="";for(let a of t)o+=String.fromCharCode(a);n=btoa(o);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function i(e){return `${s}${l(JSON.stringify(e))}`}function c(e,t){let r;return /\.m?js$/i.test(e)?r="local-node":/\.py$/i.test(e)?r="local-python":r="local-process",{meta:"task-executor",howToRun:r,whatToRun:i({kind:"fs-path",value:e}),...t?{extra:t}:{}}}function f(e){return JSON.stringify(e)}function d(e){let t;try{t=JSON.parse(e);}catch{throw new Error(`parseExecutionRef: invalid JSON \u2014 ${e}`)}if(typeof t!="object"||t===null||typeof t.howToRun!="string"||typeof t.whatToRun!="string")throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun \u2014 ${e}`);return t}
 exports.executionRefFromScriptPath=c;exports.parseExecutionRef=d;exports.serializeExecutionRef=f;//# sourceMappingURL=execution-refs.cjs.map
 //# sourceMappingURL=execution-refs.cjs.map

package/lib/execution-refs.d.cts

@@ -77,6 +77,13 @@
  *    whatToRun: 'b64:<base64url({"kind":"fs-path","value":"/path/to/my-executor.js"})>',
  *  };
  *
+ *  // Packaged yaml-flow CLI entrypoint resolved by the Node adapter:
+ *  const yamlFlowCli: ExecutionRef = {
+ *    meta: 'chat-handler',
+ *    howToRun: 'local-node',
+ *    whatToRun: 'b64:<base64url({"kind":"yaml-flow-cli","value":"chat-store-cli.js"})>',
+ *  };
+ *
  *  // Azure Function task executor with custom arg mapping:
  *  const azureFn: ExecutionRef = {
  *    meta: 'task-executor',
@@ -204,7 +211,9 @@ interface ExecutionRef {
       * Address of the artifact to run. Two valid forms:
       *   - string:  must be KindValueRef wire form `b64:<base64url(json)>` (programmatically generated via serializeRef)
       *   - object:  `{ kind: string; value: string }` plain object (human-authored flow files — normalized by the handler factory)
-      * @example 'b64:<base64url({"kind":"fs-path","value":"/dist/cli/source-cli-task-executor.js"})>'
+      * Prefer `kind: 'yaml-flow-cli'` when targeting a packaged public yaml-flow CLI entrypoint.
+      * Use `kind: 'fs-path'` for external scripts or non-packaged local executables.
+      * @example 'b64:<base64url({"kind":"yaml-flow-cli","value":"chat-store-cli.js"})>'
       * @example { kind: 'http-url', value: '/api/workiq/ask' }
       * @example { kind: 'fs-path', value: './my-handler.js' }
      */

package/lib/execution-refs.d.ts

@@ -77,6 +77,13 @@
  *    whatToRun: 'b64:<base64url({"kind":"fs-path","value":"/path/to/my-executor.js"})>',
  *  };
  *
+ *  // Packaged yaml-flow CLI entrypoint resolved by the Node adapter:
+ *  const yamlFlowCli: ExecutionRef = {
+ *    meta: 'chat-handler',
+ *    howToRun: 'local-node',
+ *    whatToRun: 'b64:<base64url({"kind":"yaml-flow-cli","value":"chat-store-cli.js"})>',
+ *  };
+ *
  *  // Azure Function task executor with custom arg mapping:
  *  const azureFn: ExecutionRef = {
  *    meta: 'task-executor',
@@ -204,7 +211,9 @@ interface ExecutionRef {
       * Address of the artifact to run. Two valid forms:
       *   - string:  must be KindValueRef wire form `b64:<base64url(json)>` (programmatically generated via serializeRef)
       *   - object:  `{ kind: string; value: string }` plain object (human-authored flow files — normalized by the handler factory)
-      * @example 'b64:<base64url({"kind":"fs-path","value":"/dist/cli/source-cli-task-executor.js"})>'
+      * Prefer `kind: 'yaml-flow-cli'` when targeting a packaged public yaml-flow CLI entrypoint.
+      * Use `kind: 'fs-path'` for external scripts or non-packaged local executables.
+      * @example 'b64:<base64url({"kind":"yaml-flow-cli","value":"chat-store-cli.js"})>'
       * @example { kind: 'http-url', value: '/api/workiq/ask' }
       * @example { kind: 'fs-path', value: './my-handler.js' }
      */

package/lib/execution-refs.js

@@ -1,3 +1,3 @@
-var s="b64:";function l(e){let r=new TextEncoder().encode(e),t=globalThis.Buffer,n;if(t)n=t.from(r).toString("base64");else if(typeof btoa=="function"){let o="";for(let a of r)o+=String.fromCharCode(a);n=btoa(o);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function i(e){return `${s}${l(JSON.stringify(e))}`}function c(e,r){let t;return /\.m?js$/i.test(e)?t="local-node":/\.py$/i.test(e)?t="local-python":t="local-process",{meta:"task-executor",howToRun:t,whatToRun:i({kind:"fs-path",value:e}),...r?{extra:r}:{}}}function f(e){return JSON.stringify(e)}function d(e){let r;try{r=JSON.parse(e);}catch{throw new Error(`parseExecutionRef: invalid JSON \u2014 ${e}`)}if(typeof r!="object"||r===null||typeof r.howToRun!="string"||typeof r.whatToRun!="string")throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun \u2014 ${e}`);return r}
+var s="b64:";function l(e){let t=new TextEncoder().encode(e),r=globalThis.Buffer,n;if(r)n=r.from(t).toString("base64");else if(typeof btoa=="function"){let o="";for(let a of t)o+=String.fromCharCode(a);n=btoa(o);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function i(e){return `${s}${l(JSON.stringify(e))}`}function c(e,t){let r;return /\.m?js$/i.test(e)?r="local-node":/\.py$/i.test(e)?r="local-python":r="local-process",{meta:"task-executor",howToRun:r,whatToRun:i({kind:"fs-path",value:e}),...t?{extra:t}:{}}}function f(e){return JSON.stringify(e)}function d(e){let t;try{t=JSON.parse(e);}catch{throw new Error(`parseExecutionRef: invalid JSON \u2014 ${e}`)}if(typeof t!="object"||t===null||typeof t.howToRun!="string"||typeof t.whatToRun!="string")throw new Error(`parseExecutionRef: missing required fields howToRun/whatToRun \u2014 ${e}`);return t}
 export{c as executionRefFromScriptPath,d as parseExecutionRef,f as serializeExecutionRef};//# sourceMappingURL=execution-refs.js.map
 //# sourceMappingURL=execution-refs.js.map

package/lib/index.d.cts

@@ -12,7 +12,7 @@ export { CommandSpec, GraphMutation, Journal, MemoryJournal, ProcessHandlerOptio
 export { B as BlockedTask, D as DownstreamResult, L as LiveBoard, a as LiveCard, b as LiveCardsToReactiveOptions, c as LiveCardsToReactiveResult, d as LiveGraph, e as LiveGraphHealth, f as LiveGraphSnapshot, N as NodeInfo, P as PendingTask, R as ReactiveGraph, g as ReactiveGraphOptions, S as ScheduleResult, T as TaskHandlerFn, h as TaskHandlerInput, i as TaskHandlerReturn, U as UnreachableNodesResult, j as UnreachableTokensResult, k as UnresolvedDependency, l as UpstreamResult, m as createReactiveGraph, n as liveCardsToReactiveGraph, s as schedule } from './live-cards-bridge-b25aAVvE.cjs';
 export { BoardLiveGraphRuntime, BoardLiveGraphRuntimeOptions, BoardLiveGraphRuntimeUpdate, BoardRuntimeView, BoardTaskExecutor, BoardTaskExecutorContext, BrowserSourceAdapter, BrowserSourceAdapterContext, LiveCardRuntimeModel, createBoardLiveGraphRuntime } from './board-livegraph-runtime/index.cjs';
 export { CardCompute, ComputeNode, ComputeStep, ValidationResult, validateLiveCard, validateLiveCardDefinition, validateLiveCardRuntimeExpressions, validateLiveCardSchema } from './card-compute/index.cjs';
-import './storage-interface-B6ecOulj.cjs';
+import './storage-interface-B-7pDHwD.cjs';
 
 /**
  * schema-validator — Full JSON Schema validation for published runtime artifacts.

package/lib/index.d.ts

@@ -12,7 +12,7 @@ export { CommandSpec, GraphMutation, Journal, MemoryJournal, ProcessHandlerOptio
 export { B as BlockedTask, D as DownstreamResult, L as LiveBoard, a as LiveCard, b as LiveCardsToReactiveOptions, c as LiveCardsToReactiveResult, d as LiveGraph, e as LiveGraphHealth, f as LiveGraphSnapshot, N as NodeInfo, P as PendingTask, R as ReactiveGraph, g as ReactiveGraphOptions, S as ScheduleResult, T as TaskHandlerFn, h as TaskHandlerInput, i as TaskHandlerReturn, U as UnreachableNodesResult, j as UnreachableTokensResult, k as UnresolvedDependency, l as UpstreamResult, m as createReactiveGraph, n as liveCardsToReactiveGraph, s as schedule } from './live-cards-bridge-DC_ZU0eS.js';
 export { BoardLiveGraphRuntime, BoardLiveGraphRuntimeOptions, BoardLiveGraphRuntimeUpdate, BoardRuntimeView, BoardTaskExecutor, BoardTaskExecutorContext, BrowserSourceAdapter, BrowserSourceAdapterContext, LiveCardRuntimeModel, createBoardLiveGraphRuntime } from './board-livegraph-runtime/index.js';
 export { CardCompute, ComputeNode, ComputeStep, ValidationResult, validateLiveCard, validateLiveCardDefinition, validateLiveCardRuntimeExpressions, validateLiveCardSchema } from './card-compute/index.js';
-import './storage-interface-B6ecOulj.js';
+import './storage-interface-B-7pDHwD.js';
 
 /**
  * schema-validator — Full JSON Schema validation for published runtime artifacts.