yaml-flow 8.1.1 → 8.2.1

package/lib/step-machine-public/index.d.ts

@@ -1,16 +1,9 @@
 export { c as createStepMachine, l as loadStepFlow } from '../loader-Zborm2pq.js';
-export { l as StepMachineStore } from '../types-DQ1bKuB1.js';
+import { l as StepMachineStore } from '../types-DQ1bKuB1.js';
 export { MemoryStore } from '../stores/memory.js';
 export { KVStorageStore } from '../stores/kv.js';
 import { ExecutionRef } from '../execution-refs.js';
-import '../storage-interface-BhAON-gW.js';
-
-/**
- * step-machine-public — types
- *
- * Platform-free types for the declarative handler model.
- * No Node imports. Safe for any runtime (Node, browser, Python via codegen, etc.).
- */
+import '../storage-interface-B6ecOulj.js';
 
 /**
  * The single normalized shape the engine consumes.
@@ -74,6 +67,17 @@ type HandlerSpec = ComputeJsonataSpec | RefSpec;
  * The framework awaits regardless.
  */
 type InvokeRefFn = (ref: ExecutionRef, args: Record<string, unknown>) => NormalizedHandlerResult | Promise<NormalizedHandlerResult>;
+interface CreateStepMachineChatFlowRunnerOptions$1 {
+    invokeRef: InvokeRefFn;
+    storeFactory?: () => StepMachineStore;
+}
+interface StepMachineChatFlowRunnerResult$1 {
+    dispatched: boolean;
+    error?: string;
+}
+interface StepMachineChatFlowRunner$1 {
+    run(flow: unknown, args: Record<string, unknown>): Promise<StepMachineChatFlowRunnerResult$1>;
+}
 /**
  * Handler signature consumed by the existing pure step machine.
  *
@@ -176,4 +180,17 @@ type JsonataExpression = {
 };
 declare const jsonata: (expr: string) => JsonataExpression;
 
-export { type BuildStepHandlersOptions, type ComputeJsonataSpec, type HandlerSpec, type InvokeRefFn, type JsonataExpression, type NormalizedHandlerResult, type RefSpec, type ResolveStepHandlerOptions, type StepConfigForFactory, type StepHandler, buildStepHandlersForFlow, createComputeJsonataHandler, createPassthroughHandler, createRefStepHandler, filterProducedData, isComputeJsonataSpec, isRefSpec, jsonata, normalizeHandlerResult, resolveStepHandler, runInputValidations, wrapWithInputValidations, wrapWithOutputFiltering };
+interface CreateStepMachineChatFlowRunnerOptions {
+    invokeRef: InvokeRefFn;
+    storeFactory?: () => StepMachineStore;
+}
+interface StepMachineChatFlowRunnerResult {
+    dispatched: boolean;
+    error?: string;
+}
+interface StepMachineChatFlowRunner {
+    run(flow: unknown, args: Record<string, unknown>): Promise<StepMachineChatFlowRunnerResult>;
+}
+declare function createStepMachineChatFlowRunner(options: CreateStepMachineChatFlowRunnerOptions): StepMachineChatFlowRunner;
+
+export { type BuildStepHandlersOptions, type ComputeJsonataSpec, type CreateStepMachineChatFlowRunnerOptions$1 as CreateStepMachineChatFlowRunnerOptions, type HandlerSpec, type InvokeRefFn, type JsonataExpression, type NormalizedHandlerResult, type RefSpec, type ResolveStepHandlerOptions, type StepConfigForFactory, type StepHandler, type StepMachineChatFlowRunner$1 as StepMachineChatFlowRunner, type StepMachineChatFlowRunnerResult$1 as StepMachineChatFlowRunnerResult, StepMachineStore, buildStepHandlersForFlow, createComputeJsonataHandler, createPassthroughHandler, createRefStepHandler, createStepMachineChatFlowRunner, filterProducedData, isComputeJsonataSpec, isRefSpec, jsonata, normalizeHandlerResult, resolveStepHandler, runInputValidations, wrapWithInputValidations, wrapWithOutputFiltering };

package/lib/step-machine-public/index.js

@@ -1,5 +1,5 @@
-import'ajv-formats';import {createRequire}from'module';import {fileURLToPath}from'url';import {dirname,resolve}from'path';import {existsSync}from'fs';function R(r,t,e,n){let s=r.steps[e];if(!s)throw new Error(`Step "${e}" not found in flow configuration`);if(n.result==="failure"&&s.retry){let a=t.retryCounts[e]??0;if(a<s.retry.max_attempts)return {newState:{...t,retryCounts:{...t.retryCounts,[e]:a+1},updatedAt:Date.now()},nextStep:e,isTerminal:false,isCircuitBroken:false,shouldRetry:true}}let o=s.failure_transitions?.[n.result]??s.transitions[n.result];if(!o)throw new Error(`No transition defined for result "${n.result}" in step "${e}"`);let i=!!r.terminal_states[o];return {newState:{...t,currentStep:o,stepHistory:[...t.stepHistory,e],retryCounts:{...t.retryCounts,[e]:0},updatedAt:Date.now()},nextStep:o,isTerminal:i,isCircuitBroken:false,shouldRetry:false}}function b(r,t,e){let n=r.steps[e];if(!n?.circuit_breaker)return {broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:(t.iterationCounts[e]??0)+1},updatedAt:Date.now()}};let s=t.iterationCounts[e]??0;return s>=n.circuit_breaker.max_iterations?{broken:true,redirectStep:n.circuit_breaker.on_open,newState:{...t,currentStep:n.circuit_breaker.on_open,updatedAt:Date.now()}}:{broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:s+1},updatedAt:Date.now()}}}function j(r,t,e){let n=r.steps[t];if(!n)throw new Error(`Step "${t}" not found`);if(n.expects_data){let s={};for(let o of n.expects_data)s[o]=e[o];return s}return {...e}}function E(r,t){if(r===false||r===void 0)return {};if(typeof r=="string")return {[r]:t[r]};if(Array.isArray(r)){let e={};for(let n of r)e[n]=t[n];return e}return {}}function $(r,t){let e=Date.now();return {runId:t,flowId:r.id??"unnamed",currentStep:r.settings.start_step,status:"running",stepHistory:[],iterationCounts:{},retryCounts:{},startedAt:e,updatedAt:e}}var S=class{runs=new Map;data=new Map;async saveRunState(t,e){this.runs.set(t,{...e});}async loadRunState(t){let e=this.runs.get(t);return e?{...e}:null}async deleteRunState(t){this.runs.delete(t),this.data.delete(t);}async setData(t,e,n){this.data.has(t)||this.data.set(t,{});let s=this.data.get(t);s[e]=n;}async getData(t,e){return this.data.get(t)?.[e]}async getAllData(t){return {...this.data.get(t)??{}}}async clearData(t){this.data.delete(t);}async listRuns(){return Array.from(this.runs.keys())}clear(){this.runs.clear(),this.data.clear();}};function tt(){return typeof crypto<"u"&&crypto.randomUUID?crypto.randomUUID():"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,r=>{let t=Math.random()*16|0;return (r==="x"?t:t&3|8).toString(16)})}var x=class{flow;handlers;store;components;options;listeners=new Map;aborted=false;constructor(t,e,n={}){this.flow=t,this.handlers=new Map(Object.entries(e)),this.store=n.store??new S,this.components=n.components??{},this.options=n,n.signal&&n.signal.addEventListener("abort",()=>{this.aborted=true;}),this.validateFlow();}validateFlow(){let{settings:t,steps:e,terminal_states:n}=this.flow;if(!t?.start_step)throw new Error("Flow must have settings.start_step defined");if(!e||Object.keys(e).length===0)throw new Error("Flow must have at least one step defined");if(!n||Object.keys(n).length===0)throw new Error("Flow must have at least one terminal_state defined");if(!e[t.start_step]&&!n[t.start_step])throw new Error(`Start step "${t.start_step}" not found`);for(let[s,o]of Object.entries(e)){for(let[i,a]of Object.entries(o.transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" transition "${i}" points to unknown step "${a}"`);if(o.failure_transitions){for(let[i,a]of Object.entries(o.failure_transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" failure_transition "${i}" points to unknown step "${a}"`)}}}on(t,e){this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(e);}off(t,e){this.listeners.get(t)?.delete(e);}emit(t){let e=this.listeners.get(t.type);if(e)for(let n of e)try{n(t);}catch{}}sleep(t){return new Promise(e=>setTimeout(e,t))}async run(t){let e=tt(),n=$(this.flow,e);if(await this.store.saveRunState(e,n),t)for(let[s,o]of Object.entries(t))await this.store.setData(e,s,o);this.emit({type:"flow:start",runId:e,timestamp:n.startedAt,data:{initialData:t??{}}});try{return await this.executeLoop(e,n)}catch(s){let o=s instanceof Error?s:new Error(String(s));return this.emit({type:"flow:error",runId:e,timestamp:Date.now(),data:{error:o.message}}),this.options.onError?.(o),n={...n,status:"failed",updatedAt:Date.now()},await this.store.saveRunState(e,n),{runId:e,status:"failed",data:await this.store.getAllData(e),finalStep:n.currentStep,stepHistory:n.stepHistory,durationMs:Date.now()-n.startedAt,error:o}}}async resume(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);if(e.status==="completed"||e.status==="failed")throw new Error(`Cannot resume a ${e.status} run`);let n={...e,status:"running",pausedAt:void 0,updatedAt:Date.now()};return await this.store.saveRunState(t,n),this.emit({type:"flow:resumed",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}}),this.executeLoop(t,n)}async pause(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);let n={...e,status:"paused",pausedAt:Date.now(),updatedAt:Date.now()};await this.store.saveRunState(t,n),this.emit({type:"flow:paused",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}});}async executeLoop(t,e){let n=this.flow.settings.max_total_steps??100,s=this.flow.settings.timeout_ms,o=e,i=0;for(;i<n;){if(this.aborted)return o={...o,status:"cancelled",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"cancelled",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};if(s&&Date.now()-o.startedAt>s)return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"timeout",intent:"timeout",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};let a=o.currentStep,c=this.flow.terminal_states[a];if(c){o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o);let p=await this.store.getAllData(t),u={runId:t,status:"completed",intent:c.return_intent,data:E(c.return_artifacts,p),finalStep:a,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};return this.emit({type:"flow:complete",runId:t,timestamp:Date.now(),data:{...u}}),this.options.onComplete?.(u),u}let d=b(this.flow,o,a);if(d.broken){o=d.newState,await this.store.saveRunState(t,o),i++;continue}o=d.newState;let f=await this.store.getAllData(t),l=j(this.flow,a,f),m={runId:t,stepName:a,components:this.components,store:this.store,signal:this.options.signal,emit:(p,u)=>{this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{event:p,payload:u}});}};this.emit({type:"step:start",runId:t,timestamp:Date.now(),data:{step:a,input:l}});let g;try{let p=this.handlers.get(a);if(!p)throw new Error(`No handler registered for step "${a}"`);g=await p(l,m);}catch(p){let u=p instanceof Error?p:new Error(String(p));this.emit({type:"step:error",runId:t,timestamp:Date.now(),data:{step:a,error:u.message}}),g={result:"failure",data:{error:u.message}};}if(g.data)for(let[p,u]of Object.entries(g.data))await this.store.setData(t,p,u);this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{step:a,result:g.result}}),this.options.onStep?.(a,g);let w=R(this.flow,o,a,g);if(o=w.newState,w.shouldRetry){await this.store.saveRunState(t,o);let p=this.flow.steps[a];if(p.retry?.delay_ms){let u=o.retryCounts[a]??0,h=p.retry.backoff_multiplier?p.retry.delay_ms*Math.pow(p.retry.backoff_multiplier,u-1):p.retry.delay_ms;await this.sleep(h);}i++;continue}await this.store.saveRunState(t,o),this.emit({type:"transition",runId:t,timestamp:Date.now(),data:{from:a,to:o.currentStep,result:g.result}}),this.options.onTransition?.(a,o.currentStep),i++;}return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"max_iterations",intent:"max_iterations",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt}}};function H(r,t,e){return new x(r,t,e)}async function C(r){return (await import('yaml')).parse(r)}async function et(r){let t=await fetch(r);if(!t.ok)throw new Error(`Failed to load flow from ${r}: ${t.statusText}`);let e=t.headers.get("content-type")??"",n=await t.text();return e.includes("json")||r.endsWith(".json")?JSON.parse(n):C(n)}async function rt(r){let e=await(await import('fs/promises')).readFile(r,"utf-8");return r.endsWith(".json")?JSON.parse(e):C(e)}function M(r){let t=[];if(!r||typeof r!="object")return ["Flow must be an object"];let e=r;if(!e.settings||typeof e.settings!="object"?t.push('Flow must have a "settings" object'):typeof e.settings.start_step!="string"&&t.push("settings.start_step must be a string"),!e.steps||typeof e.steps!="object")t.push('Flow must have a "steps" object');else {let n=e.steps;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Step "${s}" must be an object`);continue}let i=o;(!i.transitions||typeof i.transitions!="object")&&t.push(`Step "${s}" must have a "transitions" object`),i.failure_transitions!==void 0&&typeof i.failure_transitions!="object"&&t.push(`Step "${s}" failure_transitions must be an object when provided`);}}if(!e.terminal_states||typeof e.terminal_states!="object")t.push('Flow must have a "terminal_states" object');else {let n=e.terminal_states;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Terminal state "${s}" must be an object`);continue}typeof o.return_intent!="string"&&t.push(`Terminal state "${s}" must have a "return_intent" string`);}}return t}async function D(r){let t;typeof r=="string"?r.startsWith("http://")||r.startsWith("https://")?t=await et(r):r.includes("{")?t=JSON.parse(r):t=await rt(r):t=r;let e=M(t);if(e.length>0)throw new Error(`Invalid step flow configuration:
+import'ajv-formats';import {createRequire}from'module';import {fileURLToPath}from'url';import {dirname,resolve}from'path';import {existsSync}from'fs';function b(r,t,e,n){let s=r.steps[e];if(!s)throw new Error(`Step "${e}" not found in flow configuration`);if(n.result==="failure"&&s.retry){let a=t.retryCounts[e]??0;if(a<s.retry.max_attempts)return {newState:{...t,retryCounts:{...t.retryCounts,[e]:a+1},updatedAt:Date.now()},nextStep:e,isTerminal:false,isCircuitBroken:false,shouldRetry:true}}let o=s.failure_transitions?.[n.result]??s.transitions[n.result];if(!o)throw new Error(`No transition defined for result "${n.result}" in step "${e}"`);let i=!!r.terminal_states[o];return {newState:{...t,currentStep:o,stepHistory:[...t.stepHistory,e],retryCounts:{...t.retryCounts,[e]:0},updatedAt:Date.now()},nextStep:o,isTerminal:i,isCircuitBroken:false,shouldRetry:false}}function j(r,t,e){let n=r.steps[e];if(!n?.circuit_breaker)return {broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:(t.iterationCounts[e]??0)+1},updatedAt:Date.now()}};let s=t.iterationCounts[e]??0;return s>=n.circuit_breaker.max_iterations?{broken:true,redirectStep:n.circuit_breaker.on_open,newState:{...t,currentStep:n.circuit_breaker.on_open,updatedAt:Date.now()}}:{broken:false,newState:{...t,iterationCounts:{...t.iterationCounts,[e]:s+1},updatedAt:Date.now()}}}function F(r,t,e){let n=r.steps[t];if(!n)throw new Error(`Step "${t}" not found`);if(n.expects_data){let s={};for(let o of n.expects_data)s[o]=e[o];return s}return {...e}}function C(r,t){if(r===false||r===void 0)return {};if(typeof r=="string")return {[r]:t[r]};if(Array.isArray(r)){let e={};for(let n of r)e[n]=t[n];return e}return {}}function E(r,t){let e=Date.now();return {runId:t,flowId:r.id??"unnamed",currentStep:r.settings.start_step,status:"running",stepHistory:[],iterationCounts:{},retryCounts:{},startedAt:e,updatedAt:e}}var h=class{runs=new Map;data=new Map;async saveRunState(t,e){this.runs.set(t,{...e});}async loadRunState(t){let e=this.runs.get(t);return e?{...e}:null}async deleteRunState(t){this.runs.delete(t),this.data.delete(t);}async setData(t,e,n){this.data.has(t)||this.data.set(t,{});let s=this.data.get(t);s[e]=n;}async getData(t,e){return this.data.get(t)?.[e]}async getAllData(t){return {...this.data.get(t)??{}}}async clearData(t){this.data.delete(t);}async listRuns(){return Array.from(this.runs.keys())}clear(){this.runs.clear(),this.data.clear();}};function et(){return typeof crypto<"u"&&crypto.randomUUID?crypto.randomUUID():"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g,r=>{let t=Math.random()*16|0;return (r==="x"?t:t&3|8).toString(16)})}var k=class{flow;handlers;store;components;options;listeners=new Map;aborted=false;constructor(t,e,n={}){this.flow=t,this.handlers=new Map(Object.entries(e)),this.store=n.store??new h,this.components=n.components??{},this.options=n,n.signal&&n.signal.addEventListener("abort",()=>{this.aborted=true;}),this.validateFlow();}validateFlow(){let{settings:t,steps:e,terminal_states:n}=this.flow;if(!t?.start_step)throw new Error("Flow must have settings.start_step defined");if(!e||Object.keys(e).length===0)throw new Error("Flow must have at least one step defined");if(!n||Object.keys(n).length===0)throw new Error("Flow must have at least one terminal_state defined");if(!e[t.start_step]&&!n[t.start_step])throw new Error(`Start step "${t.start_step}" not found`);for(let[s,o]of Object.entries(e)){for(let[i,a]of Object.entries(o.transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" transition "${i}" points to unknown step "${a}"`);if(o.failure_transitions){for(let[i,a]of Object.entries(o.failure_transitions))if(!e[a]&&!n[a])throw new Error(`Step "${s}" failure_transition "${i}" points to unknown step "${a}"`)}}}on(t,e){this.listeners.has(t)||this.listeners.set(t,new Set),this.listeners.get(t).add(e);}off(t,e){this.listeners.get(t)?.delete(e);}emit(t){let e=this.listeners.get(t.type);if(e)for(let n of e)try{n(t);}catch{}}sleep(t){return new Promise(e=>setTimeout(e,t))}async run(t){let e=et(),n=E(this.flow,e);if(await this.store.saveRunState(e,n),t)for(let[s,o]of Object.entries(t))await this.store.setData(e,s,o);this.emit({type:"flow:start",runId:e,timestamp:n.startedAt,data:{initialData:t??{}}});try{return await this.executeLoop(e,n)}catch(s){let o=s instanceof Error?s:new Error(String(s));return this.emit({type:"flow:error",runId:e,timestamp:Date.now(),data:{error:o.message}}),this.options.onError?.(o),n={...n,status:"failed",updatedAt:Date.now()},await this.store.saveRunState(e,n),{runId:e,status:"failed",data:await this.store.getAllData(e),finalStep:n.currentStep,stepHistory:n.stepHistory,durationMs:Date.now()-n.startedAt,error:o}}}async resume(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);if(e.status==="completed"||e.status==="failed")throw new Error(`Cannot resume a ${e.status} run`);let n={...e,status:"running",pausedAt:void 0,updatedAt:Date.now()};return await this.store.saveRunState(t,n),this.emit({type:"flow:resumed",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}}),this.executeLoop(t,n)}async pause(t){let e=await this.store.loadRunState(t);if(!e)throw new Error(`No run found with ID: ${t}`);let n={...e,status:"paused",pausedAt:Date.now(),updatedAt:Date.now()};await this.store.saveRunState(t,n),this.emit({type:"flow:paused",runId:t,timestamp:Date.now(),data:{currentStep:n.currentStep}});}async executeLoop(t,e){let n=this.flow.settings.max_total_steps??100,s=this.flow.settings.timeout_ms,o=e,i=0;for(;i<n;){if(this.aborted)return o={...o,status:"cancelled",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"cancelled",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};if(s&&Date.now()-o.startedAt>s)return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"timeout",intent:"timeout",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};let a=o.currentStep,c=this.flow.terminal_states[a];if(c){o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o);let p=await this.store.getAllData(t),l={runId:t,status:"completed",intent:c.return_intent,data:C(c.return_artifacts,p),finalStep:a,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt};return this.emit({type:"flow:complete",runId:t,timestamp:Date.now(),data:{...l}}),this.options.onComplete?.(l),l}let d=j(this.flow,o,a);if(d.broken){o=d.newState,await this.store.saveRunState(t,o),i++;continue}o=d.newState;let f=await this.store.getAllData(t),u=F(this.flow,a,f),m={runId:t,stepName:a,components:this.components,store:this.store,signal:this.options.signal,emit:(p,l)=>{this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{event:p,payload:l}});}};this.emit({type:"step:start",runId:t,timestamp:Date.now(),data:{step:a,input:u}});let g;try{let p=this.handlers.get(a);if(!p)throw new Error(`No handler registered for step "${a}"`);g=await p(u,m);}catch(p){let l=p instanceof Error?p:new Error(String(p));this.emit({type:"step:error",runId:t,timestamp:Date.now(),data:{step:a,error:l.message}}),g={result:"failure",data:{error:l.message}};}if(g.data)for(let[p,l]of Object.entries(g.data))await this.store.setData(t,p,l);this.emit({type:"step:complete",runId:t,timestamp:Date.now(),data:{step:a,result:g.result}}),this.options.onStep?.(a,g);let w=b(this.flow,o,a,g);if(o=w.newState,w.shouldRetry){await this.store.saveRunState(t,o);let p=this.flow.steps[a];if(p.retry?.delay_ms){let l=o.retryCounts[a]??0,S=p.retry.backoff_multiplier?p.retry.delay_ms*Math.pow(p.retry.backoff_multiplier,l-1):p.retry.delay_ms;await this.sleep(S);}i++;continue}await this.store.saveRunState(t,o),this.emit({type:"transition",runId:t,timestamp:Date.now(),data:{from:a,to:o.currentStep,result:g.result}}),this.options.onTransition?.(a,o.currentStep),i++;}return o={...o,status:"completed",updatedAt:Date.now()},await this.store.saveRunState(t,o),{runId:t,status:"max_iterations",intent:"max_iterations",data:await this.store.getAllData(t),finalStep:o.currentStep,stepHistory:o.stepHistory,durationMs:Date.now()-o.startedAt}}};function v(r,t,e){return new k(r,t,e)}async function $(r){return (await import('yaml')).parse(r)}async function rt(r){let t=await fetch(r);if(!t.ok)throw new Error(`Failed to load flow from ${r}: ${t.statusText}`);let e=t.headers.get("content-type")??"",n=await t.text();return e.includes("json")||r.endsWith(".json")?JSON.parse(n):$(n)}async function nt(r){let e=await(await import('fs/promises')).readFile(r,"utf-8");return r.endsWith(".json")?JSON.parse(e):$(e)}function D(r){let t=[];if(!r||typeof r!="object")return ["Flow must be an object"];let e=r;if(!e.settings||typeof e.settings!="object"?t.push('Flow must have a "settings" object'):typeof e.settings.start_step!="string"&&t.push("settings.start_step must be a string"),!e.steps||typeof e.steps!="object")t.push('Flow must have a "steps" object');else {let n=e.steps;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Step "${s}" must be an object`);continue}let i=o;(!i.transitions||typeof i.transitions!="object")&&t.push(`Step "${s}" must have a "transitions" object`),i.failure_transitions!==void 0&&typeof i.failure_transitions!="object"&&t.push(`Step "${s}" failure_transitions must be an object when provided`);}}if(!e.terminal_states||typeof e.terminal_states!="object")t.push('Flow must have a "terminal_states" object');else {let n=e.terminal_states;for(let[s,o]of Object.entries(n)){if(!o||typeof o!="object"){t.push(`Terminal state "${s}" must be an object`);continue}typeof o.return_intent!="string"&&t.push(`Terminal state "${s}" must have a "return_intent" string`);}}return t}async function P(r){let t;typeof r=="string"?r.startsWith("http://")||r.startsWith("https://")?t=await rt(r):r.includes("{")?t=JSON.parse(r):t=await nt(r):t=r;let e=D(t);if(e.length>0)throw new Error(`Invalid step flow configuration:
 - ${e.join(`
-- `)}`);return t}function A(r){return btoa(r).replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}function P(r){return atob(r.replace(/-/g,"+").replace(/_/g,"/"))}var F=class{constructor(t){this.kv=t;}kv;stateKey(t){return `state_${A(t)}`}dataPrefix(t){return `data_${A(t)}_`}dataKey(t,e){return `${this.dataPrefix(t)}${A(e)}`}async saveRunState(t,e){this.kv.write(this.stateKey(t),e);}async loadRunState(t){let e=this.kv.read(this.stateKey(t));return e!=null&&typeof e=="object"?e:null}async deleteRunState(t){this.kv.delete(this.stateKey(t));for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async setData(t,e,n){this.kv.write(this.dataKey(t,e),n);}async getData(t,e){return this.kv.read(this.dataKey(t,e))}async getAllData(t){let e=this.dataPrefix(t),n={};for(let s of this.kv.listKeys(e))n[P(s.slice(e.length))]=this.kv.read(s);return n}async clearData(t){for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async listRuns(){return this.kv.listKeys("state_").map(t=>P(t.slice(6)))}};var J=dirname(fileURLToPath(import.meta.url)),it=createRequire(import.meta.url);function pt(){let r=resolve(J,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(J,"../card-compute/jsonata-sync.cjs")}var v=it(pt());function K(r,t){if(!r||typeof r!="object")throw new Error(`[step-machine-public] Step "${t}" returned a non-object result.`);let e=r,n=e.result??e.status;if(typeof n=="string"&&n.trim().length>0){let s=e.data&&typeof e.data=="object"&&!Array.isArray(e.data)?{...e.data}:{},o=typeof e.error=="string"?e.error:void 0;return o&&!("error"in s)&&(s.error=o),{result:n,data:s,...o?{error:o}:{}}}return {result:"success",data:{...e}}}function B(r,t){if(!t||t.length===0)return r;let e={};for(let n of t)Object.prototype.hasOwnProperty.call(r,n)&&(e[n]=r[n]);return e}function _(r,t){return async(e,n)=>{let s=await r(e,n),o=K(s,n?.stepName??"unknown");return {result:o.result,data:B(o.data,t),...o.error?{error:o.error}:{}}}}function z(r,t,e){if(!t||t.length===0)return null;for(let n of t)try{if(!v(n).evaluate(r))return {result:"failure",data:{error:`[${e}] input validation failed: ${n}`}}}catch(s){let o=s instanceof Error?s.message:String(s);return {result:"failure",data:{error:`[${e}] input validation error on "${n}": ${o}`}}}return null}function T(r,t,e){return !t||t.length===0?r:async(n,s)=>{let o=z(n,t,e);return o||r(n,s)}}var L=dirname(fileURLToPath(import.meta.url)),dt=createRequire(import.meta.url);function gt(){let r=resolve(L,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(L,"../../card-compute/jsonata-sync.cjs")}var k=dt(gt());function N(r,t,e){if(!r||typeof r!="object")return t;let n={output:t},s=t.result,o=t.data,i=t.error;if(typeof r.resultExpr=="string")try{let a=k(r.resultExpr).evaluate(n);if(typeof a!="string"||!a.trim())throw new Error(`resultExpr did not produce a non-empty string (got ${JSON.stringify(a)})`);s=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.resultExpr failed: ${c}`)}if(typeof r.dataTemplate=="string")try{let a=k(r.dataTemplate).evaluate(n);if(!a||typeof a!="object"||Array.isArray(a))throw new Error(`dataTemplate did not produce an object (got ${JSON.stringify(a)})`);o=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.dataTemplate failed: ${c}`)}if(typeof r.errorExpr=="string")try{let a=k(r.errorExpr).evaluate(n);i=a!=null?String(a):void 0;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.errorExpr failed: ${c}`)}return i!==void 0?{result:s,data:o,error:i}:{result:s,data:o}}var mt="b64:";function wt(r){let t=new TextEncoder().encode(r),e=globalThis.Buffer,n;if(e)n=e.from(t).toString("base64");else if(typeof btoa=="function"){let s="";for(let o of t)s+=String.fromCharCode(o);n=btoa(s);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function U(r){return `${mt}${wt(JSON.stringify(r))}`}function W(r){return !!r&&typeof r=="object"&&r.type==="compute-jsonata"&&Array.isArray(r.expr)&&r.expr.length>0}function q(r){if(!r||typeof r!="object")return  false;let t=r;if(t.type!=="ref"||typeof t.howToRun!="string")return  false;if(typeof t.whatToRun=="string")return  true;if(t.whatToRun&&typeof t.whatToRun=="object"){let e=t.whatToRun;return typeof e.kind=="string"&&typeof e.value=="string"}return  false}function ht(r){if(typeof r=="string"){let t=r.indexOf("=");if(t<1)throw new Error(`[step-machine-public] Invalid compute expression (missing "="): "${r}"`);return {bindTo:r.slice(0,t).trim(),expr:r.slice(t+1).trim()}}if(r&&typeof r=="object"&&typeof r.bindTo=="string"&&typeof r.expr=="string")return r;throw new Error(`[step-machine-public] Invalid compute step: ${JSON.stringify(r)}`)}function yt(r,t,e){let n=t.split("."),s=r;for(let o=0;o<n.length-1;o++){let i=n[o];(s[i]==null||typeof s[i]!="object")&&(s[i]={}),s=s[i];}s[n[n.length-1]]=e;}function I(r,t,e){let n=r.expr.map(ht);return async s=>{let o=s&&typeof s=="object"&&!Array.isArray(s)?{...s}:{},i={},a={expects_data:o,data:i,...e?{config:e}:{}},c,d;for(let f of n)try{let l=v(f.expr).evaluate(a);if(f.bindTo==="result")c=l!=null?String(l):"success";else if(f.bindTo==="error")d=l!=null?String(l):void 0;else if(f.bindTo.startsWith("data."))yt(i,f.bindTo.slice(5),l);else return {result:"failure",data:{},error:`[${t}] invalid bindTo "${f.bindTo}": must be "result", "error", or start with "data."`}}catch(l){let m=l instanceof Error?l.message:String(l);return {result:"failure",data:{},error:`[${t}] compute "${f.bindTo}" failed: ${m}`}}return c===void 0?{result:"failure",data:{},error:`[${t}] compute-jsonata: no "result" binding declared \u2014 add '- result = "success"' to expr`}:d?{result:c,data:i,error:d}:{result:c,data:i}}}function Y(r,t,e,n){let{type:s,...o}=r,i={...o,whatToRun:typeof o.whatToRun=="object"?U(o.whatToRun):o.whatToRun};return async a=>{let c=a&&typeof a=="object"&&!Array.isArray(a)?{...a}:{};n&&(c.config=n);try{let d=await e(i,c);if(!r.outputTransforms)return d;try{return N(r.outputTransforms,d,t)}catch(f){let l=f instanceof Error?f.message:String(f);return {result:"failure",data:{},error:l}}}catch(d){let f=d instanceof Error?d.message:String(d);return {result:"failure",data:{error:`[step-machine-public] step "${t}" invoke threw: ${f}`}}}}}function X(){return async r=>({result:"success",data:r&&typeof r=="object"&&!Array.isArray(r)?r:{}})}function St(r,t,e){return async(n,s)=>{let o=n?.[t.items];if(!Array.isArray(o))return {result:"failure",data:{},error:`[${e}] forEach: "${t.items}" is not an array (got ${typeof o})`};let i=o,a=t.collectAs??`${t.items}_results`;if(i.length===0)return {result:"success",data:{[a]:[]}};let{[t.items]:c,...d}=n,f=Math.max(1,t.concurrency??1),l=new Array(i.length),m=0,g=0,w=0;return await new Promise(p=>{function u(){for(;m<f&&g<i.length;){let h=g++;m++;let Q={...d,[t.as]:i[h]};r(Q,s).then(y=>{l[h]=y;}).catch(y=>{let Z=y instanceof Error?y.message:String(y);l[h]={result:"failure",data:{},error:Z};}).finally(()=>{m--,l[h]?.result==="failure"&&w++,g>=i.length&&m===0?p():u();});}m===0&&g>=i.length&&p();}u();}),w>0?{result:"failure",data:{errors:l.filter(u=>u.result==="failure").map(u=>u.error)},error:`[${e}] forEach: ${w}/${i.length} items failed`}:{result:"success",data:{[a]:l.map(p=>p.data)}}}}function G(r,t,e){let n=Array.isArray(t?.produces_data)?t?.produces_data:void 0,s=Array.isArray(t?.input_validations)?t?.input_validations:void 0,o=t?.config??void 0,i=t?.handler,a;return W(i)?a=I(i,r,o):q(i)?a=Y(i,r,e.invoke,o):a=X(),t?.forEach&&(a=St(a,t.forEach,r)),T(_(a,n),s,r)}function vt(r,t){let e={};for(let[n,s]of Object.entries(r.steps??{}))e[n]=G(n,s,t);return e}
-export{F as KVStorageStore,S as MemoryStore,vt as buildStepHandlersForFlow,I as createComputeJsonataHandler,X as createPassthroughHandler,Y as createRefStepHandler,H as createStepMachine,B as filterProducedData,W as isComputeJsonataSpec,q as isRefSpec,v as jsonata,D as loadStepFlow,K as normalizeHandlerResult,G as resolveStepHandler,z as runInputValidations,T as wrapWithInputValidations,_ as wrapWithOutputFiltering};//# sourceMappingURL=index.js.map
+- `)}`);return t}function M(r){return btoa(r).replace(/\+/g,"-").replace(/\//g,"_").replace(/=/g,"")}function O(r){return atob(r.replace(/-/g,"+").replace(/_/g,"/"))}var A=class{constructor(t){this.kv=t;}kv;stateKey(t){return `state_${M(t)}`}dataPrefix(t){return `data_${M(t)}_`}dataKey(t,e){return `${this.dataPrefix(t)}${M(e)}`}async saveRunState(t,e){this.kv.write(this.stateKey(t),e);}async loadRunState(t){let e=this.kv.read(this.stateKey(t));return e!=null&&typeof e=="object"?e:null}async deleteRunState(t){this.kv.delete(this.stateKey(t));for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async setData(t,e,n){this.kv.write(this.dataKey(t,e),n);}async getData(t,e){return this.kv.read(this.dataKey(t,e))}async getAllData(t){let e=this.dataPrefix(t),n={};for(let s of this.kv.listKeys(e))n[O(s.slice(e.length))]=this.kv.read(s);return n}async clearData(t){for(let e of this.kv.listKeys(this.dataPrefix(t)))this.kv.delete(e);}async listRuns(){return this.kv.listKeys("state_").map(t=>O(t.slice(6)))}};var K=dirname(fileURLToPath(import.meta.url)),pt=createRequire(import.meta.url);function ut(){let r=resolve(K,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(K,"../card-compute/jsonata-sync.cjs")}var R=pt(ut());function B(r,t){if(!r||typeof r!="object")throw new Error(`[step-machine-public] Step "${t}" returned a non-object result.`);let e=r,n=e.result??e.status;if(typeof n=="string"&&n.trim().length>0){let s=e.data&&typeof e.data=="object"&&!Array.isArray(e.data)?{...e.data}:{},o=typeof e.error=="string"?e.error:void 0;return o&&!("error"in s)&&(s.error=o),{result:n,data:s,...o?{error:o}:{}}}return {result:"success",data:{...e}}}function z(r,t){if(!t||t.length===0)return r;let e={};for(let n of t)Object.prototype.hasOwnProperty.call(r,n)&&(e[n]=r[n]);return e}function _(r,t){return async(e,n)=>{let s=await r(e,n),o=B(s,n?.stepName??"unknown");return {result:o.result,data:z(o.data,t),...o.error?{error:o.error}:{}}}}function V(r,t,e){if(!t||t.length===0)return null;for(let n of t)try{if(!R(n).evaluate(r))return {result:"failure",data:{error:`[${e}] input validation failed: ${n}`}}}catch(s){let o=s instanceof Error?s.message:String(s);return {result:"failure",data:{error:`[${e}] input validation error on "${n}": ${o}`}}}return null}function T(r,t,e){return !t||t.length===0?r:async(n,s)=>{let o=V(n,t,e);return o||r(n,s)}}var N=dirname(fileURLToPath(import.meta.url)),gt=createRequire(import.meta.url);function mt(){let r=resolve(N,"./jsonata-sync.cjs");return existsSync(r)?r:resolve(N,"../../card-compute/jsonata-sync.cjs")}var x=gt(mt());function U(r,t,e){if(!r||typeof r!="object")return t;let n={output:t},s=t.result,o=t.data,i=t.error;if(typeof r.resultExpr=="string")try{let a=x(r.resultExpr).evaluate(n);if(typeof a!="string"||!a.trim())throw new Error(`resultExpr did not produce a non-empty string (got ${JSON.stringify(a)})`);s=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.resultExpr failed: ${c}`)}if(typeof r.dataTemplate=="string")try{let a=x(r.dataTemplate).evaluate(n);if(!a||typeof a!="object"||Array.isArray(a))throw new Error(`dataTemplate did not produce an object (got ${JSON.stringify(a)})`);o=a;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.dataTemplate failed: ${c}`)}if(typeof r.errorExpr=="string")try{let a=x(r.errorExpr).evaluate(n);i=a!=null?String(a):void 0;}catch(a){let c=a instanceof Error?a.message:String(a);throw new Error(`[${e}] outputTransforms.errorExpr failed: ${c}`)}return i!==void 0?{result:s,data:o,error:i}:{result:s,data:o}}var ht="b64:";function wt(r){let t=new TextEncoder().encode(r),e=globalThis.Buffer,n;if(e)n=e.from(t).toString("base64");else if(typeof btoa=="function"){let s="";for(let o of t)s+=String.fromCharCode(o);n=btoa(s);}else throw new Error("No base64 encoder available in this runtime");return n.replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/g,"")}function W(r){return `${ht}${wt(JSON.stringify(r))}`}function q(r){return !!r&&typeof r=="object"&&r.type==="compute-jsonata"&&Array.isArray(r.expr)&&r.expr.length>0}function I(r){if(!r||typeof r!="object")return  false;let t=r;if(t.type!=="ref"||typeof t.howToRun!="string")return  false;if(typeof t.whatToRun=="string")return  true;if(t.whatToRun&&typeof t.whatToRun=="object"){let e=t.whatToRun;return typeof e.kind=="string"&&typeof e.value=="string"}return  false}function St(r){if(typeof r=="string"){let t=r.indexOf("=");if(t<1)throw new Error(`[step-machine-public] Invalid compute expression (missing "="): "${r}"`);return {bindTo:r.slice(0,t).trim(),expr:r.slice(t+1).trim()}}if(r&&typeof r=="object"&&typeof r.bindTo=="string"&&typeof r.expr=="string")return r;throw new Error(`[step-machine-public] Invalid compute step: ${JSON.stringify(r)}`)}function yt(r,t,e){let n=t.split("."),s=r;for(let o=0;o<n.length-1;o++){let i=n[o];(s[i]==null||typeof s[i]!="object")&&(s[i]={}),s=s[i];}s[n[n.length-1]]=e;}function Y(r,t,e){let n=r.expr.map(St);return async s=>{let o=s&&typeof s=="object"&&!Array.isArray(s)?{...s}:{},i={},a={expects_data:o,data:i,...e?{config:e}:{}},c,d;for(let f of n)try{let u=R(f.expr).evaluate(a);if(f.bindTo==="result")c=u!=null?String(u):"success";else if(f.bindTo==="error")d=u!=null?String(u):void 0;else if(f.bindTo.startsWith("data."))yt(i,f.bindTo.slice(5),u);else return {result:"failure",data:{},error:`[${t}] invalid bindTo "${f.bindTo}": must be "result", "error", or start with "data."`}}catch(u){let m=u instanceof Error?u.message:String(u);return {result:"failure",data:{},error:`[${t}] compute "${f.bindTo}" failed: ${m}`}}return c===void 0?{result:"failure",data:{},error:`[${t}] compute-jsonata: no "result" binding declared \u2014 add '- result = "success"' to expr`}:d?{result:c,data:i,error:d}:{result:c,data:i}}}function X(r,t,e,n){let{type:s,...o}=r,i={...o,whatToRun:typeof o.whatToRun=="object"?W(o.whatToRun):o.whatToRun};return async a=>{let c=a&&typeof a=="object"&&!Array.isArray(a)?{...a}:{};n&&(c.config=n);try{let d=await e(i,c);if(!r.outputTransforms)return d;try{return U(r.outputTransforms,d,t)}catch(f){let u=f instanceof Error?f.message:String(f);return {result:"failure",data:{},error:u}}}catch(d){let f=d instanceof Error?d.message:String(d);return {result:"failure",data:{error:`[step-machine-public] step "${t}" invoke threw: ${f}`}}}}}function G(){return async r=>({result:"success",data:r&&typeof r=="object"&&!Array.isArray(r)?r:{}})}function Rt(r,t,e){return async(n,s)=>{let o=n?.[t.items];if(!Array.isArray(o))return {result:"failure",data:{},error:`[${e}] forEach: "${t.items}" is not an array (got ${typeof o})`};let i=o,a=t.collectAs??`${t.items}_results`;if(i.length===0)return {result:"success",data:{[a]:[]}};let{[t.items]:c,...d}=n,f=Math.max(1,t.concurrency??1),u=new Array(i.length),m=0,g=0,w=0;return await new Promise(p=>{function l(){for(;m<f&&g<i.length;){let S=g++;m++;let Z={...d,[t.as]:i[S]};r(Z,s).then(y=>{u[S]=y;}).catch(y=>{let tt=y instanceof Error?y.message:String(y);u[S]={result:"failure",data:{},error:tt};}).finally(()=>{m--,u[S]?.result==="failure"&&w++,g>=i.length&&m===0?p():l();});}m===0&&g>=i.length&&p();}l();}),w>0?{result:"failure",data:{errors:u.filter(l=>l.result==="failure").map(l=>l.error)},error:`[${e}] forEach: ${w}/${i.length} items failed`}:{result:"success",data:{[a]:u.map(p=>p.data)}}}}function Q(r,t,e){let n=Array.isArray(t?.produces_data)?t?.produces_data:void 0,s=Array.isArray(t?.input_validations)?t?.input_validations:void 0,o=t?.config??void 0,i=t?.handler,a;return q(i)?a=Y(i,r,o):I(i)?a=X(i,r,e.invoke,o):a=G(),t?.forEach&&(a=Rt(a,t.forEach,r)),T(_(a,n),s,r)}function H(r,t){let e={};for(let[n,s]of Object.entries(r.steps??{}))e[n]=Q(n,s,t);return e}function kt(r){let t=r.storeFactory||(()=>new h);return {async run(e,n){try{let s=H(e,{invoke:r.invokeRef}),i=await v(e,s,{store:t()}).run(n);return i.status!=="completed"?{dispatched:!1,error:i.error?.message||i.status}:{dispatched:!0}}catch(s){return {dispatched:false,error:s instanceof Error?s.message:String(s)}}}}}
+export{A as KVStorageStore,h as MemoryStore,H as buildStepHandlersForFlow,Y as createComputeJsonataHandler,G as createPassthroughHandler,X as createRefStepHandler,v as createStepMachine,kt as createStepMachineChatFlowRunner,z as filterProducedData,q as isComputeJsonataSpec,I as isRefSpec,R as jsonata,P as loadStepFlow,B as normalizeHandlerResult,Q as resolveStepHandler,V as runInputValidations,T as wrapWithInputValidations,_ as wrapWithOutputFiltering};//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/lib/{storage-interface-BhAON-gW.d.ts → storage-interface-B6ecOulj.d.cts}

@@ -46,8 +46,8 @@ interface BlobStorage {
     readBytes?(key: string): Uint8Array | null;
     /** Optional binary write for file-like artifacts. */
     writeBytes?(key: string, content: Uint8Array): void;
-    /** Optional key listing by prefix. */
-    listKeys?(prefix?: string): string[];
+    /** List all keys that start with the given prefix. */
+    listKeys(prefix?: string): string[];
     /** Optional metadata lookup. */
     stat?(key: string): BlobStat | null;
 }
@@ -59,6 +59,28 @@ interface KindValueRef {
 declare function serializeRef(ref: KindValueRef): string;
 /** Parse a wire-format ref string (b64:<base64url(json)>) into a KindValueRef. */
 declare function parseRef(s: string): KindValueRef;
+interface JournalEntry {
+    id: string;
+    payload: unknown;
+}
+interface JournalReadResult {
+    entries: JournalEntry[];
+    /** The id of the last entry returned, suitable for use as the next cursor. */
+    newCursor: string | null;
+}
+interface JournalStorage {
+    /** Append an entry. The storage layer assigns the id. */
+    append(payload: unknown): JournalEntry;
+    /** Read ALL entries (for index rebuilds, full replay). */
+    readAll(): JournalEntry[];
+    /**
+     * Read entries appended after the given cursor id.
+     * If cursor is null/empty, returns all entries from the beginning.
+     */
+    readAfter(cursor: string | null): JournalReadResult;
+    /** Truncate all entries. Optional — not all backends support it. */
+    clear?(): void;
+}
 interface KVStorage {
     /** Returns the stored value, or null if the key does not exist. */
     read(key: string): unknown | null;
@@ -81,4 +103,4 @@ interface AtomicRelayLock {
     tryAcquire(): (() => void) | null;
 }
 
-export { type AtomicRelayLock as A, type BlobStorage as B, type KVStorage as K, type KindValueRef as a, parseRef as p, serializeRef as s };
+export { type AtomicRelayLock as A, type BlobStorage as B, type JournalStorage as J, type KVStorage as K, type KindValueRef as a, parseRef as p, serializeRef as s };

package/lib/{storage-interface-BhAON-gW.d.cts → storage-interface-B6ecOulj.d.ts}

@@ -46,8 +46,8 @@ interface BlobStorage {
     readBytes?(key: string): Uint8Array | null;
     /** Optional binary write for file-like artifacts. */
     writeBytes?(key: string, content: Uint8Array): void;
-    /** Optional key listing by prefix. */
-    listKeys?(prefix?: string): string[];
+    /** List all keys that start with the given prefix. */
+    listKeys(prefix?: string): string[];
     /** Optional metadata lookup. */
     stat?(key: string): BlobStat | null;
 }
@@ -59,6 +59,28 @@ interface KindValueRef {
 declare function serializeRef(ref: KindValueRef): string;
 /** Parse a wire-format ref string (b64:<base64url(json)>) into a KindValueRef. */
 declare function parseRef(s: string): KindValueRef;
+interface JournalEntry {
+    id: string;
+    payload: unknown;
+}
+interface JournalReadResult {
+    entries: JournalEntry[];
+    /** The id of the last entry returned, suitable for use as the next cursor. */
+    newCursor: string | null;
+}
+interface JournalStorage {
+    /** Append an entry. The storage layer assigns the id. */
+    append(payload: unknown): JournalEntry;
+    /** Read ALL entries (for index rebuilds, full replay). */
+    readAll(): JournalEntry[];
+    /**
+     * Read entries appended after the given cursor id.
+     * If cursor is null/empty, returns all entries from the beginning.
+     */
+    readAfter(cursor: string | null): JournalReadResult;
+    /** Truncate all entries. Optional — not all backends support it. */
+    clear?(): void;
+}
 interface KVStorage {
     /** Returns the stored value, or null if the key does not exist. */
     read(key: string): unknown | null;
@@ -81,4 +103,4 @@ interface AtomicRelayLock {
     tryAcquire(): (() => void) | null;
 }
 
-export { type AtomicRelayLock as A, type BlobStorage as B, type KVStorage as K, type KindValueRef as a, parseRef as p, serializeRef as s };
+export { type AtomicRelayLock as A, type BlobStorage as B, type JournalStorage as J, type KVStorage as K, type KindValueRef as a, parseRef as p, serializeRef as s };

package/lib/stores/index.d.cts

@@ -1,4 +1,4 @@
 export { MemoryStore } from './memory.cjs';
 export { KVStorageStore } from './kv.cjs';
 import '../types-DQ1bKuB1.cjs';
-import '../storage-interface-BhAON-gW.cjs';
+import '../storage-interface-B6ecOulj.cjs';

package/lib/stores/index.d.ts

@@ -1,4 +1,4 @@
 export { MemoryStore } from './memory.js';
 export { KVStorageStore } from './kv.js';
 import '../types-DQ1bKuB1.js';
-import '../storage-interface-BhAON-gW.js';
+import '../storage-interface-B6ecOulj.js';

package/lib/stores/kv.d.cts

@@ -1,5 +1,5 @@
 import { l as StepMachineStore, k as StepMachineState } from '../types-DQ1bKuB1.cjs';
-import { K as KVStorage } from '../storage-interface-BhAON-gW.cjs';
+import { K as KVStorage } from '../storage-interface-B6ecOulj.cjs';
 
 /**
  * yaml-flow - KVStorageStore

package/lib/stores/kv.d.ts

@@ -1,5 +1,5 @@
 import { l as StepMachineStore, k as StepMachineState } from '../types-DQ1bKuB1.js';
-import { K as KVStorage } from '../storage-interface-BhAON-gW.js';
+import { K as KVStorage } from '../storage-interface-B6ecOulj.js';
 
 /**
  * yaml-flow - KVStorageStore

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

@@ -1,6 +1,56 @@
-import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-BF9FP0mL.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
@@ -31,6 +81,23 @@ interface InvocationAdapter {
      */
     describe?(ref: ExecutionRef): Promise<DescribeEnvelope | null>;
 }
+interface ChatHandlerFlowRunner {
+    /**
+     * Execute a stored chat-handler flow using host-defined step-machine bindings.
+     * The runtime stays platform-free and delegates actual execution to the host.
+     */
+    run(flow: unknown, args: Record<string, unknown>, context: {
+        boardId: string;
+        cardId: string;
+        label: string;
+        logger: RuntimeLogger;
+        serverUrl?: string | null;
+        executionExtra?: Record<string, unknown>;
+    }): Promise<{
+        dispatched: boolean;
+        error?: string;
+    }>;
+}
 interface NotificationTransport {
     /**
      * Start listening for events on a notification endpoint identified by a kind-ref.
@@ -65,7 +132,9 @@ interface BoardContextConfig {
     /** Notification endpoint ref — e.g. ::named-pipe::<path> or ::firestore-watch::<path> */
     notifyRef?: KindValueRef;
     taskExecutorRef?: ExecutionRef;
+    /** Internal fallback only; public board config now uses chatHandlerFlow. */
     chatHandlerRef?: ExecutionRef;
+    chatHandlerFlow?: unknown;
     inferenceAdapterRef?: ExecutionRef;
 }
 interface SingleBoardRuntimeOptions {
@@ -75,6 +144,9 @@ interface SingleBoardRuntimeOptions {
     /** One or more board layers composing this board surface (e.g. base cards + admin cards). */
     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;
@@ -145,4 +217,4 @@ interface RuntimeResponse {
     end(data?: string | Buffer): void;
 }
 
-export type { BoardContextConfig as B, 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-D48hpnTR.d.ts → types-D-xVWPdY.d.ts}

@@ -1,6 +1,56 @@
-import { d as BoardPlatformAdapter, a as CommandResult } from './board-live-cards-public-dJAl5IL-.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
@@ -31,6 +81,23 @@ interface InvocationAdapter {
      */
     describe?(ref: ExecutionRef): Promise<DescribeEnvelope | null>;
 }
+interface ChatHandlerFlowRunner {
+    /**
+     * Execute a stored chat-handler flow using host-defined step-machine bindings.
+     * The runtime stays platform-free and delegates actual execution to the host.
+     */
+    run(flow: unknown, args: Record<string, unknown>, context: {
+        boardId: string;
+        cardId: string;
+        label: string;
+        logger: RuntimeLogger;
+        serverUrl?: string | null;
+        executionExtra?: Record<string, unknown>;
+    }): Promise<{
+        dispatched: boolean;
+        error?: string;
+    }>;
+}
 interface NotificationTransport {
     /**
      * Start listening for events on a notification endpoint identified by a kind-ref.
@@ -65,7 +132,9 @@ interface BoardContextConfig {
     /** Notification endpoint ref — e.g. ::named-pipe::<path> or ::firestore-watch::<path> */
     notifyRef?: KindValueRef;
     taskExecutorRef?: ExecutionRef;
+    /** Internal fallback only; public board config now uses chatHandlerFlow. */
     chatHandlerRef?: ExecutionRef;
+    chatHandlerFlow?: unknown;
     inferenceAdapterRef?: ExecutionRef;
 }
 interface SingleBoardRuntimeOptions {
@@ -75,6 +144,9 @@ interface SingleBoardRuntimeOptions {
     /** One or more board layers composing this board surface (e.g. base cards + admin cards). */
     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;
@@ -145,4 +217,4 @@ interface RuntimeResponse {
     end(data?: string | Buffer): void;
 }
 
-export type { BoardContextConfig as B, 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.1.1",
+  "version": "8.2.1",
   "description": "Unified workflow engine: step-machine (sequential) + event-graph (stateless DAG) with pluggable storage",
   "author": "",
   "license": "MIT",