flowneer 0.2.0 → 0.3.0

package/dist/plugins/index.d.ts

@@ -3,5 +3,5 @@ export { CircuitBreakerOptions, withCircuitBreaker, withCycles, withFallback, wi
 export { AuditEntry, AuditLogStore, CheckpointStore, VersionedCheckpointEntry, VersionedCheckpointStore, withAuditLog, withCheckpoint, withReplay, withVersionedCheckpoint } from './persistence/index.js';
 export { RateLimitOptions, withCostTracker, withRateLimit, withTokenBudget } from './llm/index.js';
 export { withAtomicUpdates, withDryRun, withMocks, withStepLimit } from './dev/index.js';
-export { peekChannel, receiveFrom, sendTo, withChannels } from './messaging/index.js';
+export { StreamSubscriber, emit, peekChannel, receiveFrom, sendTo, withChannels, withStream } from './messaging/index.js';
 import '../index.js';

package/dist/plugins/index.js

@@ -77,10 +77,16 @@ var withInterrupts = {
 var withFallback = {
   withFallback(fn) {
     this._setHooks({
-      wrapStep: async (_meta, next, shared, params) => {
+      wrapStep: async (meta, next, shared, params) => {
         try {
           await next();
-        } catch {
+        } catch (e) {
+          shared.__fallbackError = {
+            stepIndex: meta.index,
+            stepType: meta.type,
+            message: e instanceof Error ? e.message : String(e),
+            stack: e instanceof Error ? e.stack : void 0
+          };
           await fn(shared, params);
         }
       }
@@ -126,15 +132,20 @@ var withCircuitBreaker = {
 var withTimeout = {
   withTimeout(ms) {
     this._setHooks({
-      wrapStep: (meta, next) => Promise.race([
-        next(),
-        new Promise(
-          (_, reject) => setTimeout(
-            () => reject(new Error(`step ${meta.index} timed out after ${ms}ms`)),
-            ms
+      wrapStep: (meta, next) => {
+        let handle;
+        return Promise.race([
+          next().finally(() => clearTimeout(handle)),
+          new Promise(
+            (_, reject) => handle = setTimeout(
+              () => reject(
+                new Error(`step ${meta.index} timed out after ${ms}ms`)
+              ),
+              ms
+            )
           )
-        )
-      ])
+        ]);
+      }
     });
     return this;
   }
@@ -415,7 +426,23 @@ var withChannels = {
     return this;
   }
 };
+
+// plugins/messaging/withStream.ts
+var withStream = {
+  withStream(subscriber) {
+    this._setHooks({
+      beforeFlow: (shared) => {
+        shared.__stream = subscriber;
+      }
+    });
+    return this;
+  }
+};
+function emit(shared, chunk) {
+  shared.__stream?.(chunk);
+}
 export {
+  emit,
   peekChannel,
   receiveFrom,
   sendTo,
@@ -434,6 +461,7 @@ export {
   withRateLimit,
   withReplay,
   withStepLimit,
+  withStream,
   withTimeout,
   withTiming,
   withTokenBudget,

package/dist/plugins/messaging/index.d.ts

@@ -17,4 +17,40 @@ declare module "../../Flowneer" {
 }
 declare const withChannels: FlowneerPlugin;
 
-export { peekChannel, receiveFrom, sendTo, withChannels };
+/** Callback invoked each time a step calls `emit()`. */
+type StreamSubscriber<T = unknown> = (chunk: T) => void;
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Registers a streaming subscriber for this flow.
+         * Steps call `emit(shared, chunk)` to push data to the subscriber in real-time.
+         * The subscriber is stored on `shared.__stream` before the first step runs
+         * so it is automatically inherited by sub-flows (loop, batch, etc.).
+         *
+         * @example
+         * const flow = new FlowBuilder<MyState>()
+         *   .withStream((chunk) => console.log("[stream]", chunk))
+         *   // ...
+         *
+         * // Inside a step:
+         * emit(s, { type: "draft", content: s.draft });
+         */
+        withStream<T = unknown>(subscriber: StreamSubscriber<T>): this;
+    }
+}
+declare const withStream: FlowneerPlugin;
+/**
+ * Push a chunk to the subscriber registered via `.withStream()`.
+ * Safe to call unconditionally — silently no-ops when no subscriber is registered.
+ *
+ * @example
+ * async function refineDraft(s: MyState) {
+ *   // ... produce s.draft ...
+ *   emit(s, { type: "draft", round: s.round, content: s.draft });
+ * }
+ */
+declare function emit<T = unknown>(shared: {
+    __stream?: StreamSubscriber<T>;
+}, chunk: T): void;
+
+export { type StreamSubscriber, emit, peekChannel, receiveFrom, sendTo, withChannels, withStream };

package/dist/plugins/messaging/index.js

@@ -32,9 +32,26 @@ var withChannels = {
     return this;
   }
 };
+
+// plugins/messaging/withStream.ts
+var withStream = {
+  withStream(subscriber) {
+    this._setHooks({
+      beforeFlow: (shared) => {
+        shared.__stream = subscriber;
+      }
+    });
+    return this;
+  }
+};
+function emit(shared, chunk) {
+  shared.__stream?.(chunk);
+}
 export {
+  emit,
   peekChannel,
   receiveFrom,
   sendTo,
-  withChannels
+  withChannels,
+  withStream
 };

package/dist/plugins/resilience/index.js

@@ -2,10 +2,16 @@
 var withFallback = {
   withFallback(fn) {
     this._setHooks({
-      wrapStep: async (_meta, next, shared, params) => {
+      wrapStep: async (meta, next, shared, params) => {
         try {
           await next();
-        } catch {
+        } catch (e) {
+          shared.__fallbackError = {
+            stepIndex: meta.index,
+            stepType: meta.type,
+            message: e instanceof Error ? e.message : String(e),
+            stack: e instanceof Error ? e.stack : void 0
+          };
           await fn(shared, params);
         }
       }
@@ -51,15 +57,20 @@ var withCircuitBreaker = {
 var withTimeout = {
   withTimeout(ms) {
     this._setHooks({
-      wrapStep: (meta, next) => Promise.race([
-        next(),
-        new Promise(
-          (_, reject) => setTimeout(
-            () => reject(new Error(`step ${meta.index} timed out after ${ms}ms`)),
-            ms
+      wrapStep: (meta, next) => {
+        let handle;
+        return Promise.race([
+          next().finally(() => clearTimeout(handle)),
+          new Promise(
+            (_, reject) => handle = setTimeout(
+              () => reject(
+                new Error(`step ${meta.index} timed out after ${ms}ms`)
+              ),
+              ms
+            )
           )
-        )
-      ])
+        ]);
+      }
     });
     return this;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowneer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Zero-dependency fluent flow builder for AI agents",
   "license": "MIT",
   "type": "module",