agentfootprint 1.17.4 → 1.19.0

package/README.md

@@ -16,7 +16,7 @@
   <a href="https://footprintjs.github.io/footPrint/"><img src="https://img.shields.io/badge/Built_on-footprintjs-ca8a04?style=flat" alt="Built on footprintjs"></a>
 </p>
 
-> **Most agent frameworks give you execution. agentfootprint gives you connected evidence** — grounded, auditable, LLM-readable. The LLM can explain its own decisions. You can verify it wasn't hallucinating.
+> **Most agent frameworks invent new class names for every paper. agentfootprint gives you 2 primitives, 3 compositions, and makes every other "feature" explicit about what it injects into the Agent's prompt.** Context engineering, visible. Students and engineers can read any agent paper and see it in agentfootprint terms.
 
 ```bash
 npm install agentfootprint
@@ -35,9 +35,9 @@ import { SSEFormatter } from 'agentfootprint/stream';            // Real-time ev
 
 ---
 
-## Start Simple, Compose Up
+## The Mental Model — 2 Primitives + 3 Compositions + N Patterns
 
-Six concepts. Start with a single LLM call, compose up to multi-agent. No upfront graph DSL.
+Everything in agentfootprint is expressible in five building blocks. Named patterns (ReAct, Swarm, Reflexion, Tree-of-Thoughts, Plan-Execute...) are recipes that combine them — not new classes.
 
 ```typescript
 import { Agent, defineTool } from 'agentfootprint';
@@ -56,23 +56,47 @@ console.log(result.content);              // LLM response
 console.log(obs.explain().iterations);    // per-iteration evaluation data ← the differentiator
 ```
 
-**Single LLM** (one agent, one task):
+**Primitives — atomic invocation units:**
 
-| Concept | What it adds | Use case |
-|---------|-------------|----------|
-| **LLMCall** | Single LLM invocation | Summarization, classification |
-| **Agent** | + Tool use loop (ReAct) | Research, code generation |
-| **RAG** | + Retrieval | Q&A over documents |
+| # | Primitive | What it is | Use case |
+|---|-----------|------------|----------|
+| 1 | **LLM** | One call in, one response out | Summarization, classification, extraction |
+| 2 | **Agent** | A loop of (think → tool → think) — **Agent = ReAct** | Research, code generation, anything iterative |
 
-**Multi-Agent** (compose agents):
+**Compositions — how primitives arrange:**
 
-| Concept | What it adds | Use case |
-|---------|-------------|----------|
-| **FlowChart** | Sequential pipeline | Approval flows, ETL — output of one feeds the next |
-| **Parallel** | Concurrent execution | Analysis from multiple perspectives — merged by LLM |
-| **Swarm** | LLM-driven routing | Customer support — orchestrator delegates to specialists |
+| # | Composition | What it is | Use case |
+|---|-------------|------------|----------|
+| 1 | **Sequence** | One after another | Approval flows, ETL — output of one feeds the next |
+| 2 | **Parallel** | At the same time | Analysis from multiple perspectives — merged by LLM |
+| 3 | **Conditional** | Branch on a decider | Triage flows, deterministic routing |
 
-All six share one interface: `.build()` → `.run()`, `.getNarrative()`, `.getSnapshot()`.
+**Patterns — named configurations of the above:**
+
+| Pattern | Built from | Source |
+|---------|-----------|--------|
+| **ReAct** | Agent (default) | Yao 2022 |
+| **Dynamic ReAct** | Agent with per-iteration context re-evaluation | agentfootprint extension |
+| **Hierarchy (Swarm)** | Agent routing to specialist-Agents via tools | OpenAI 2024 |
+| **Reflexion** | Sequence(Agent, LLM-critique, Agent) | Shinn 2023 |
+| **Tree-of-Thoughts** | Parallel(Agent × N) + LLM-rank | Yao 2023 |
+| **Plan-Execute** | LLM-plan + Sequence(Agent per step) | Wang 2023 |
+| **Map-Reduce** | Parallel(Agent × N) + LLM-merge | Dean 2004 applied to LLMs |
+
+**Context Engineering — cross-cutting, applies to any Agent:**
+
+What you inject into the Agent's slots. This is the library's teaching thesis — every "new agent feature" that competing frameworks wrap in new classes is just **content flowing into one of three slots**.
+
+| Mechanism | Target slot | What it does |
+|-----------|-------------|--------------|
+| **RAG** | messages | Retrieved chunks injected into the prompt |
+| **Memory** | messages | Prior-turn context re-injected |
+| **Skills** | system-prompt (+ tools) | Activate a skill → its prompt + tools become visible |
+| **Instructions** | system-prompt | Per-tool guidance injected after specific tool results |
+| **Tools** | tools slot | Available functions the LLM can call |
+| **Grounding** | system-prompt | Style guides, rules, non-negotiables |
+
+**Every runner** (LLMCall, Agent, Sequence/FlowChart, Parallel, Conditional, Swarm) shares one interface: `.build()` → `.run()`, `.observe(h)`, `.getNarrativeEntries()`, `.getSnapshot()`, `.getSpec()`.
 
 ---
 

package/dist/compositions/withCircuitBreaker.js

@@ -75,7 +75,7 @@ function withCircuitBreaker(runner, options = {}) {
                 throw err;
             }
         },
-        getNarrative: runner.getNarrative?.bind(runner),
+        getNarrativeEntries: runner.getNarrativeEntries?.bind(runner),
         getSnapshot: runner.getSnapshot?.bind(runner),
     };
     return wrapped;

package/dist/compositions/withCircuitBreaker.js.map

@@ -1 +1 @@
-{"version":3,"file":"withCircuitBreaker.js","sourceRoot":"","sources":["../../src/compositions/withCircuitBreaker.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAaH,MAAa,cAAc;IACjB,KAAK,GAAiB,QAAQ,CAAC;IAC/B,QAAQ,GAAG,CAAC,CAAC;IACb,eAAe,GAAG,CAAC,CAAC;IACX,SAAS,CAAS;IAClB,YAAY,CAAS;IAEtC,YAAY,UAAiC,EAAE;QAC7C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,MAAM,CAAC;IACrD,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBAC3D,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;IACxB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACtB,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF;AAvCD,wCAuCC;AAED,SAAgB,kBAAkB,CAChC,MAAkB,EAClB,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IAE5C,MAAM,OAAO,GAA6C;QACxD,OAAO;QACP,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YAEjC,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC7C,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBACrD,OAAO,CAAC,aAAa,EAAE,CAAC;gBACxB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,aAAa,EAAE,CAAC;gBACxB,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC;QAC/C,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AA7BD,gDA6BC"}
+{"version":3,"file":"withCircuitBreaker.js","sourceRoot":"","sources":["../../src/compositions/withCircuitBreaker.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAaH,MAAa,cAAc;IACjB,KAAK,GAAiB,QAAQ,CAAC;IAC/B,QAAQ,GAAG,CAAC,CAAC;IACb,eAAe,GAAG,CAAC,CAAC;IACX,SAAS,CAAS;IAClB,YAAY,CAAS;IAEtC,YAAY,UAAiC,EAAE;QAC7C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,MAAM,CAAC;IACrD,CAAC;IAED,QAAQ;QACN,IAAI,IAAI,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC1B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBAC3D,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;YAC3B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;IACxB,CAAC;IAED,aAAa;QACX,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACtB,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;IAC3B,CAAC;CACF;AAvCD,wCAuCC;AAED,SAAgB,kBAAkB,CAChC,MAAkB,EAClB,UAAiC,EAAE;IAEnC,MAAM,OAAO,GAAG,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;IAE5C,MAAM,OAAO,GAA6C;QACxD,OAAO;QACP,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;YAEjC,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;gBACrB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAC7C,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBACrD,OAAO,CAAC,aAAa,EAAE,CAAC;gBACxB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,aAAa,EAAE,CAAC;gBACxB,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC;QAC7D,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC;AA7BD,gDA6BC"}

package/dist/compositions/withFallback.js

@@ -25,7 +25,7 @@ function withFallback(primary, fallback, options = {}) {
             }
         },
         // Narrative/snapshot from whichever runner succeeded
-        getNarrative: () => primary.getNarrative?.() ?? fallback.getNarrative?.() ?? [],
+        getNarrativeEntries: () => primary.getNarrativeEntries?.() ?? fallback.getNarrativeEntries?.() ?? [],
         getSnapshot: () => primary.getSnapshot?.() ?? fallback.getSnapshot?.(),
     };
 }

package/dist/compositions/withFallback.js.map

@@ -1 +1 @@
-{"version":3,"file":"withFallback.js","sourceRoot":"","sources":["../../src/compositions/withFallback.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AASH,SAAgB,YAAY,CAC1B,OAAmB,EACnB,QAAoB,EACpB,UAA2B,EAAE;IAE7B,MAAM,EAAE,cAAc,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC;IAEhD,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;oBAAE,MAAM,GAAG,CAAC;gBACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,qDAAqD;QACrD,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,QAAQ,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE;QAC/E,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE;KACvE,CAAC;AACJ,CAAC;AApBD,oCAoBC"}
+{"version":3,"file":"withFallback.js","sourceRoot":"","sources":["../../src/compositions/withFallback.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AASH,SAAgB,YAAY,CAC1B,OAAmB,EACnB,QAAoB,EACpB,UAA2B,EAAE;IAE7B,MAAM,EAAE,cAAc,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC;IAEhD,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;oBAAE,MAAM,GAAG,CAAC;gBACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,qDAAqD;QACrD,mBAAmB,EAAE,GAAG,EAAE,CACxB,OAAO,CAAC,mBAAmB,EAAE,EAAE,IAAI,QAAQ,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE;QAC3E,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE;KACvE,CAAC;AACJ,CAAC;AArBD,oCAqBC"}

package/dist/compositions/withRetry.js

@@ -38,7 +38,7 @@ function withRetry(runner, options = {}) {
             }
             throw lastError;
         },
-        getNarrative: runner.getNarrative?.bind(runner),
+        getNarrativeEntries: runner.getNarrativeEntries?.bind(runner),
         getSnapshot: runner.getSnapshot?.bind(runner),
     };
 }

package/dist/compositions/withRetry.js.map

@@ -1 +1 @@
-{"version":3,"file":"withRetry.js","sourceRoot":"","sources":["../../src/compositions/withRetry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAeH,SAAgB,SAAS,CAAC,MAAkB,EAAE,UAAwB,EAAE;IACtE,MAAM,EACJ,UAAU,GAAG,CAAC,EACd,SAAS,GAAG,CAAC,EACb,iBAAiB,GAAG,CAAC,EACrB,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,GACzB,GAAG,OAAO,CAAC;IAEZ,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,SAAkB,CAAC;YACvB,IAAI,KAAK,GAAG,SAAS,CAAC;YAEtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;gBACvD,IAAI,CAAC;oBACH,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAC/C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,SAAS,GAAG,GAAG,CAAC;oBAEhB,IAAI,OAAO,IAAI,UAAU,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC/C,MAAM;oBACR,CAAC;oBAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;wBACd,MAAM,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;wBACvC,KAAK,IAAI,iBAAiB,CAAC;oBAC7B,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,SAAS,CAAC;QAClB,CAAC;QACD,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC;QAC/C,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;AACJ,CAAC;AAnCD,8BAmCC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,gBAAgB,CACtB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAChD,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"withRetry.js","sourceRoot":"","sources":["../../src/compositions/withRetry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAeH,SAAgB,SAAS,CAAC,MAAkB,EAAE,UAAwB,EAAE;IACtE,MAAM,EACJ,UAAU,GAAG,CAAC,EACd,SAAS,GAAG,CAAC,EACb,iBAAiB,GAAG,CAAC,EACrB,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,GACzB,GAAG,OAAO,CAAC;IAEZ,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,SAAkB,CAAC;YACvB,IAAI,KAAK,GAAG,SAAS,CAAC;YAEtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;gBACvD,IAAI,CAAC;oBACH,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAC/C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,SAAS,GAAG,GAAG,CAAC;oBAEhB,IAAI,OAAO,IAAI,UAAU,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC/C,MAAM;oBACR,CAAC;oBAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;wBACd,MAAM,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;wBACvC,KAAK,IAAI,iBAAiB,CAAC;oBAC7B,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,SAAS,CAAC;QAClB,CAAC;QACD,mBAAmB,EAAE,MAAM,CAAC,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC;QAC7D,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;AACJ,CAAC;AAnCD,8BAmCC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,gBAAgB,CACtB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAChD,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/concepts/Conditional.js

@@ -43,6 +43,8 @@ const runnerAsStage_1 = require("../stages/runnerAsStage");
 const RecorderBridge_1 = require("../recorders/RecorderBridge");
 const specIcons_1 = require("./specIcons");
 const narrative_1 = require("../lib/narrative");
+const streaming_1 = require("../streaming");
+const forwardEmitRecorders_1 = require("../recorders/forwardEmitRecorders");
 /** True iff the runner exposes `toFlowChart()` for subflow composition. */
 function hasFlowChart(runner) {
     return typeof runner.toFlowChart === 'function';
@@ -111,6 +113,7 @@ class Conditional {
             this.defaultName = options.name;
         return this;
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     recorder(rec) {
         this.recorders.push(rec);
         return this;
@@ -143,17 +146,39 @@ class ConditionalRunner {
     lastExecutor;
     lastSpec;
     narrativeRenderer = (0, narrative_1.createAgentRenderer)();
+    /** Persistent observer list — see AgentRunner.dispatcher. */
+    dispatcher = new streaming_1.EventDispatcher();
     constructor(opts) {
         this.opts = opts;
     }
     async run(message, options) {
         const startTime = Date.now();
         const bridge = this.opts.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge([...this.opts.recorders]) : null;
+        const dispatcher = this.dispatcher;
+        const perRun = options?.onEvent;
+        const onStreamEvent = dispatcher.size > 0 || perRun
+            ? (e) => {
+                dispatcher.dispatch(e);
+                if (perRun) {
+                    try {
+                        perRun(e);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                }
+            }
+            : undefined;
+        onStreamEvent?.({ type: 'turn_start', userMessage: message });
         bridge?.dispatchTurnStart(message);
         const chart = this.buildChart();
         const executor = new footprintjs_1.FlowChartExecutor(chart, { enrichSnapshots: true });
         executor.enableNarrative({ renderer: this.narrativeRenderer });
         executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        (0, forwardEmitRecorders_1.forwardEmitRecorders)(executor, this.opts.recorders);
+        if (onStreamEvent) {
+            executor.attachEmitRecorder((0, streaming_1.createStreamEventRecorder)(onStreamEvent));
+        }
         try {
             await executor.run({
                 input: { message },
@@ -170,12 +195,17 @@ class ConditionalRunner {
         const state = snapshot?.sharedState ?? {};
         const content = state.result ?? '';
         bridge?.dispatchTurnComplete(content, 0);
+        onStreamEvent?.({ type: 'turn_end', content, iterations: 1 });
         return {
             content,
             agents: [],
             totalLatencyMs: Date.now() - startTime,
         };
     }
+    /** Subscribe to the runner's live stream of events. See AgentRunner.observe(). */
+    observe(handler) {
+        return this.dispatcher.observe(handler);
+    }
     buildChart() {
         // Seed stage: store pipeline input so runner stages can read it.
         const seedStage = (scope) => {
@@ -253,10 +283,6 @@ class ConditionalRunner {
     toFlowChart() {
         return this.buildChart();
     }
-    /** Get the narrative from the last run. */
-    getNarrative() {
-        return this.lastExecutor?.getNarrative() ?? [];
-    }
     /** Get structured narrative entries from the last run. */
     getNarrativeEntries() {
         return this.lastExecutor?.getNarrativeEntries() ?? [];

package/dist/concepts/Conditional.js.map

@@ -1 +1 @@
-{"version":3,"file":"Conditional.js","sourceRoot":"","sources":["../../src/concepts/Conditional.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Conditional.js","sourceRoot":"","sources":["../../src/concepts/Conditional.ts"],"names":[],"mappings":"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"}

package/dist/concepts/FlowChart.js

@@ -19,6 +19,8 @@ const footprintjs_1 = require("footprintjs");
 const specIcons_1 = require("./specIcons");
 const runnerAsStage_1 = require("../stages/runnerAsStage");
 const RecorderBridge_1 = require("../recorders/RecorderBridge");
+const forwardEmitRecorders_1 = require("../recorders/forwardEmitRecorders");
+const streaming_1 = require("../streaming");
 /**
  * Check if a runner exposes its internal flowChart for subflow composition.
  * Runners with `toFlowChart()` are mounted as subflows (enables UI drill-down).
@@ -45,7 +47,8 @@ class FlowChart {
         });
         return this;
     }
-    /** Attach an AgentRecorder to observe execution events. */
+    /** Attach a recorder. AgentRecorder OR EmitRecorder (e.g. contextEngineering). */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     recorder(rec) {
         this.recorders.push(rec);
         return this;
@@ -64,6 +67,8 @@ class FlowChartRunner {
     recorders;
     lastExecutor;
     lastSpec;
+    /** Persistent observer list — see AgentRunner.dispatcher. */
+    dispatcher = new streaming_1.EventDispatcher();
     constructor(agents, recorders = []) {
         this.agents = agents;
         this.recorders = recorders;
@@ -71,6 +76,22 @@ class FlowChartRunner {
     async run(message, options) {
         const startTime = Date.now();
         const bridge = this.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge(this.recorders) : null;
+        const dispatcher = this.dispatcher;
+        const perRun = options?.onEvent;
+        const onStreamEvent = dispatcher.size > 0 || perRun
+            ? (e) => {
+                dispatcher.dispatch(e);
+                if (perRun) {
+                    try {
+                        perRun(e);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                }
+            }
+            : undefined;
+        onStreamEvent?.({ type: 'turn_start', userMessage: message });
         bridge?.dispatchTurnStart(message);
         // Seed stage: set input and initialize agent results.
         // Signal/timeout are passed via executor.run({ signal, timeoutMs }) and
@@ -107,6 +128,10 @@ class FlowChartRunner {
         const executor = new footprintjs_1.FlowChartExecutor(chart, { enrichSnapshots: true });
         executor.enableNarrative();
         executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        (0, forwardEmitRecorders_1.forwardEmitRecorders)(executor, this.recorders);
+        if (onStreamEvent) {
+            executor.attachEmitRecorder((0, streaming_1.createStreamEventRecorder)(onStreamEvent));
+        }
         try {
             await executor.run({
                 input: { message },
@@ -149,12 +174,17 @@ class FlowChartRunner {
             lastSubflowContent ??
             (flatAgentResults.length > 0 ? flatAgentResults[flatAgentResults.length - 1].content : '');
         bridge?.dispatchTurnComplete(content, 0);
+        onStreamEvent?.({ type: 'turn_end', content, iterations: 1 });
         return {
             content,
             agents: allAgentResults,
             totalLatencyMs: Date.now() - startTime,
         };
     }
+    /** Subscribe to the runner's live stream of events. See AgentRunner.observe(). */
+    observe(handler) {
+        return this.dispatcher.observe(handler);
+    }
     /** Get the flowchart spec (stage graph metadata). */
     getSpec() {
         if (!this.lastSpec) {
@@ -184,10 +214,6 @@ class FlowChartRunner {
         }
         return this.lastSpec;
     }
-    /** Get the narrative from the last run. */
-    getNarrative() {
-        return this.lastExecutor?.getNarrative() ?? [];
-    }
     /** Get structured narrative entries from the last run. */
     getNarrativeEntries() {
         return this.lastExecutor?.getNarrativeEntries() ?? [];

package/dist/concepts/FlowChart.js.map

@@ -1 +1 @@
-{"version":3,"file":"FlowChart.js","sourceRoot":"","sources":["../../src/concepts/FlowChart.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,6CAA6F;AAE7F,2CAAgD;AAGhD,2DAAwD;AAGxD,gEAA6D;AAG7D;;;;GAIG;AACH,SAAS,cAAc,CACrB,MAAkB;IAElB,OAAO,OAAQ,MAAc,CAAC,WAAW,KAAK,UAAU,CAAC;AAC3D,CAAC;AAED,MAAa,SAAS;IACH,MAAM,GAAuB,EAAE,CAAC;IAChC,SAAS,GAAoB,EAAE,CAAC;IAEjD,gBAAuB,CAAC;IAExB,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,SAAS,EAAE,CAAC;IACzB,CAAC;IAED,yEAAyE;IACzE,KAAK,CACH,EAAU,EACV,IAAY,EACZ,MAAkB,EAClB,OAGC;QAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,EAAE;YACF,IAAI;YACJ,MAAM;YACN,WAAW,EAAE,OAAO,EAAE,WAAW;YACjC,YAAY,EAAE,OAAO,EAAE,YAAY;SACpC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2DAA2D;IAC3D,QAAQ,CAAC,GAAkB;QACzB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wDAAwD;IACxD,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,IAAI,eAAe,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,CAAC;CACF;AA3CD,8BA2CC;AAED,MAAa,eAAe;IACT,MAAM,CAA8B;IACpC,SAAS,CAAkB;IACpC,YAAY,CAAqB;IACjC,QAAQ,CAAW;IAE3B,YAAY,MAAmC,EAAE,YAA6B,EAAE;QAC9E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CACP,OAAe,EACf,OAAsD;QAEtD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,+BAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAErF,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAEnC,sDAAsD;QACtD,wEAAwE;QACxE,iFAAiF;QACjF,MAAM,SAAS,GAAG,CAAC,KAAkC,EAAE,EAAE;YACvD,KAAK,CAAC,aAAa,GAAG,OAAO,CAAC;YAC9B,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC;QAC1B,CAAC,CAAC;QAEF,4DAA4D;QAC5D,sEAAsE;QACtE,+DAA+D;QAC/D,IAAI,OAAO,GAAG,IAAA,uBAAc,EAAkB,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;QAEzE,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,IAAI,cAAc,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvC,yEAAyE;gBACzE,+EAA+E;gBAC/E,OAAO,GAAG,OAAO,CAAC,mBAAmB,CACnC,WAAW,CAAC,EAAE,EACd,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,EAChC,WAAW,CAAC,IAAI,EAChB;oBACE,WAAW,EAAE,CAAC,WAAoC,EAAE,EAAE;wBACpD,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW;4BACnC,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC;4BACtC,CAAC,CAAE,WAAW,CAAC,MAAiB,IAAK,WAAW,CAAC,aAAwB,IAAI,EAAE,CAAC;wBAClF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;oBAC5B,CAAC;iBACF,CACF,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,qCAAqC;gBACrC,MAAM,KAAK,GAAG,IAAA,6BAAa,EAAC,WAAW,CAAC,CAAC;gBACzC,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC;QAED,IAAI,CAAC,QAAQ,GAAG,IAAA,6BAAiB,EAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;QAE9B,MAAM,QAAQ,GAAG,IAAI,+BAAiB,CAAC,KAAK,EAAE,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;QACzE,QAAQ,CAAC,eAAe,EAAE,CAAC;QAC3B,QAAQ,CAAC,cAAc,CAAC,IAAI,4BAAc,CAAC,SAAS,CAAC,CAAC,CAAC;QAEvD,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,GAAG,CAAC;gBACjB,KAAK,EAAE,EAAE,OAAO,EAAE;gBAClB,MAAM,EAAE,OAAO,EAAE,MAAM;gBACvB,SAAS,EAAE,OAAO,EAAE,SAAS;aAC9B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAClC,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;QAE7B,iCAAiC;QACjC,6EAA6E;QAC7E,0DAA0D;QAC1D,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,QAAQ,EAAE,WAAW,IAAI,EAAE,CAAC;QAC1C,MAAM,cAAc,GAAG,QAAQ,EAAE,cAAc,IAAI,EAAE,CAAC;QAEtD,MAAM,gBAAgB,GAAI,KAAK,CAAC,YAAmC,IAAI,EAAE,CAAC;QAC1E,MAAM,mBAAmB,GAAuB,EAAE,CAAC;QAEnD,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,CAAC,EAAE,CAAwC,CAAC;YACvF,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,UAAU,GAAI,QAAQ,CAAC,WAAmD;oBAC9E,EAAE,aAAoD,CAAC;gBACzD,MAAM,YAAY,GAAG,UAAU,CAAC,CAAC,CAAE,UAAU,CAAC,MAAiB,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3E,mBAAmB,CAAC,IAAI,CAAC;oBACvB,EAAE,EAAE,WAAW,CAAC,EAAE;oBAClB,IAAI,EAAE,WAAW,CAAC,IAAI;oBACtB,OAAO,EAAE,YAAY;oBACrB,SAAS,EAAE,CAAC,EAAE,6DAA6D;iBAC5E,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,MAAM,eAAe,GAAG,CAAC,GAAG,gBAAgB,EAAE,GAAG,mBAAmB,CAAC,CAAC;QAEtE,MAAM,kBAAkB,GACtB,mBAAmB,CAAC,MAAM,GAAG,CAAC;YAC5B,CAAC,CAAC,mBAAmB,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO;YAC7D,CAAC,CAAC,SAAS,CAAC;QAEhB,MAAM,OAAO,GACV,KAAK,CAAC,MAAiB;YACxB,kBAAkB;YAClB,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAE7F,MAAM,EAAE,oBAAoB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAEzC,OAAO;YACL,OAAO;YACP,MAAM,EAAE,eAAe;YACvB,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;SACvC,CAAC;IACJ,CAAC;IAED,qDAAqD;IACrD,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,0DAA0D;YAC1D,MAAM,SAAS,GAAG,CAAC,KAAkC,EAAE,EAAE;gBACvD,KAAK,CAAC,aAAa,GAAG,EAAE,CAAC;gBACzB,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC;YAC1B,CAAC,CAAC;YACF,IAAI,OAAO,GAAG,IAAA,uBAAc,EAAkB,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;YACzE,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBACtC,IAAI,cAAc,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;oBACvC,OAAO,GAAG,OAAO,CAAC,mBAAmB,CACnC,WAAW,CAAC,EAAE,EACd,WAAW,CAAC,MAAM,CAAC,WAAW,EAAE,EAChC,WAAW,CAAC,IAAI,EAChB;wBACE,WAAW,EAAE,CAAC,WAAoC,EAAE,EAAE;4BACpD,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW;gCACnC,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC;gCACtC,CAAC,CAAE,WAAW,CAAC,MAAiB,IAAK,WAAW,CAAC,aAAwB,IAAI,EAAE,CAAC;4BAClF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;wBAC5B,CAAC;qBACF,CACF,CAAC;gBACJ,CAAC;qBAAM,CAAC;oBACN,MAAM,KAAK,GAAG,IAAA,6BAAa,EAAC,WAAW,CAAC,CAAC;oBACzC,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;gBACzE,CAAC;YACH,CAAC;YACD,IAAI,CAAC,QAAQ,GAAG,IAAA,6BAAiB,EAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,2CAA2C;IAC3C,YAAY;QACV,OAAO,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,0DAA0D;IAC1D,mBAAmB;QACjB,OAAO,IAAI,CAAC,YAAY,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC;IACxD,CAAC;IAED,yDAAyD;IACzD,WAAW;QACT,OAAO,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC1C,CAAC;CACF;AA3KD,0CA2KC"}
+{"version":3,"file":"FlowChart.js","sourceRoot":"","sources":["../../src/concepts/FlowChart.ts"],"names":[],"mappings":"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"}

package/dist/concepts/LLMCall.js

@@ -17,12 +17,14 @@ const trace_1 = require("footprintjs/trace");
 const specIcons_1 = require("./specIcons");
 const content_1 = require("../types/content");
 const types_1 = require("../types");
-const callLLM_1 = require("../stages/callLLM");
+const callLLMStage_1 = require("../lib/call/callLLMStage");
 const parseResponse_1 = require("../stages/parseResponse");
 const finalize_1 = require("../stages/finalize");
 const memory_1 = require("../memory");
 const RecorderBridge_1 = require("../recorders/RecorderBridge");
+const forwardEmitRecorders_1 = require("../recorders/forwardEmitRecorders");
 const createProvider_1 = require("../adapters/createProvider");
+const streaming_1 = require("../streaming");
 class LLMCall {
     provider;
     sysPrompt;
@@ -42,7 +44,10 @@ class LLMCall {
         this.enableStreaming = enabled;
         return this;
     }
-    /** Attach an AgentRecorder to observe execution events. */
+    /** Attach a recorder. Accepts AgentRecorder OR EmitRecorder shape;
+     *  shape auto-detected at run-time so `contextEngineering()` works
+     *  here too (see RAG.recorder for the full rationale). */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     recorder(rec) {
         this.recorders.push(rec);
         return this;
@@ -59,6 +64,8 @@ class LLMCallRunner {
     streamingEnabled;
     lastExecutor;
     lastSpec;
+    /** Persistent observer list — same pattern as AgentRunner.dispatcher. */
+    dispatcher = new streaming_1.EventDispatcher();
     constructor(provider, sysPrompt, recorders = [], streaming = false) {
         this.provider = provider;
         this.sysPrompt = sysPrompt;
@@ -72,6 +79,23 @@ class LLMCallRunner {
     async run(message, options) {
         const chart = this.buildChart(message);
         const bridge = this.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge(this.recorders) : null;
+        // Merge persistent observers with per-run callback — same pattern as AgentRunner.
+        const dispatcher = this.dispatcher;
+        const perRun = options?.onEvent;
+        const onStreamEvent = dispatcher.size > 0 || perRun
+            ? (e) => {
+                dispatcher.dispatch(e);
+                if (perRun) {
+                    try {
+                        perRun(e);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                }
+            }
+            : undefined;
+        onStreamEvent?.({ type: 'turn_start', userMessage: message });
         bridge?.dispatchTurnStart(message);
         const executorOpts = { enrichSnapshots: true };
         if (options?.onToken && this.streamingEnabled) {
@@ -84,6 +108,13 @@ class LLMCallRunner {
         const executor = new footprintjs_1.FlowChartExecutor(chart, executorOpts);
         executor.enableNarrative();
         executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        (0, forwardEmitRecorders_1.forwardEmitRecorders)(executor, this.recorders);
+        // Bridge the footprintjs emit channel to our unified dispatcher —
+        // callLLMStage fires `agentfootprint.stream.*` emits, and the
+        // recorder forwards them to every observer + per-run handler.
+        if (onStreamEvent) {
+            executor.attachEmitRecorder((0, streaming_1.createStreamEventRecorder)(onStreamEvent));
+        }
         const startMs = Date.now();
         try {
             await executor.run({
@@ -119,8 +150,16 @@ class LLMCallRunner {
             }
             bridge.dispatchTurnComplete(content, messages.length);
         }
+        onStreamEvent?.({ type: 'turn_end', content, iterations: 1 });
         return { content, messages };
     }
+    /**
+     * Subscribe to the runner's live stream of events. Returns an
+     * unsubscribe function. Matches `AgentRunner.observe()`.
+     */
+    observe(handler) {
+        return this.dispatcher.observe(handler);
+    }
     buildChart(message) {
         const sysPrompt = this.sysPrompt;
         // API slot: SystemPrompt — set the system instruction
@@ -138,7 +177,13 @@ class LLMCallRunner {
             msgs.push((0, types_1.userMessage)(message));
             scope.messages = msgs;
         };
-        const callLLM = (0, callLLM_1.createCallLLMStage)(this.provider);
+        // Cast: the shared callLLMStage is typed for AgentLoopState (which has
+        // loopCount / tool fields we don't use here), but the stage only reads
+        // messages / toolDescriptions and writes adapterResult / adapterRawResponse
+        // / llmCall — all of which RAGState provides. Cast keeps the call site
+        // clean; the runtime read/write shape is compatible.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const callLLM = (0, callLLMStage_1.createCallLLMStage)(this.provider);
         let builder = (0, footprintjs_1.flowChart)('SystemPrompt', systemPromptStage, 'system-prompt').addFunction('Messages', messagesStage, 'messages');
         if (this.streamingEnabled) {
             builder = builder.addStreamingFunction('CallLLM', callLLM, 'call-llm', 'llm-stream');
@@ -158,12 +203,12 @@ class LLMCallRunner {
         }
         return this.lastSpec;
     }
-    getNarrative() {
-        return this.lastExecutor?.getNarrative() ?? [];
-    }
     getSnapshot() {
         return this.lastExecutor?.getSnapshot();
     }
+    getNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
 }
 exports.LLMCallRunner = LLMCallRunner;
 //# sourceMappingURL=LLMCall.js.map

package/dist/concepts/LLMCall.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMCall.js","sourceRoot":"","sources":["../../src/concepts/LLMCall.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LLMCall.js","sourceRoot":"","sources":["../../src/concepts/LLMCall.ts"],"names":[],"mappings":"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"}

package/dist/concepts/Parallel.js

@@ -29,9 +29,11 @@ const footprintjs_1 = require("footprintjs");
 const types_1 = require("../types");
 const RecorderBridge_1 = require("../recorders/RecorderBridge");
 const createProvider_1 = require("../adapters/createProvider");
+const streaming_1 = require("../streaming");
+const forwardEmitRecorders_1 = require("../recorders/forwardEmitRecorders");
 const narrative_1 = require("../lib/narrative");
 const specIcons_1 = require("./specIcons");
-const callLLM_1 = require("../stages/callLLM");
+const callLLMStage_1 = require("../lib/call/callLLMStage");
 const MAX_BRANCHES = 10;
 // ── Builder ──────────────────────────────────────────────────
 class Parallel {
@@ -81,6 +83,7 @@ class Parallel {
         this.streamingEnabled = enabled;
         return this;
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     recorder(rec) {
         this.recorders.push(rec);
         return this;
@@ -109,6 +112,8 @@ class ParallelRunner {
     lastExecutor;
     lastSpec;
     narrativeRenderer = (0, narrative_1.createAgentRenderer)();
+    /** Persistent observer list — see AgentRunner.dispatcher. */
+    dispatcher = new streaming_1.EventDispatcher();
     constructor(options) {
         this.opts = options;
     }
@@ -145,7 +150,9 @@ class ParallelRunner {
         // Merge stage — after all branches complete
         if (mergePrompt) {
             // LLM merge: feed all branch results to LLM
-            const callLLM = (0, callLLM_1.createCallLLMStage)(provider);
+            // Cast — see LLMCall.ts for rationale (shared stage typed for AgentLoopState).
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const callLLM = (0, callLLMStage_1.createCallLLMStage)(provider);
             builder = builder
                 .addFunction('FormatMerge', (scope) => {
                 const results = scope.branchResults ?? {};
@@ -199,6 +206,22 @@ class ParallelRunner {
     async run(message, options) {
         const chart = this.buildChart(message);
         const bridge = this.opts.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge(this.opts.recorders) : null;
+        const dispatcher = this.dispatcher;
+        const perRun = options?.onEvent;
+        const onStreamEvent = dispatcher.size > 0 || perRun
+            ? (e) => {
+                dispatcher.dispatch(e);
+                if (perRun) {
+                    try {
+                        perRun(e);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                }
+            }
+            : undefined;
+        onStreamEvent?.({ type: 'turn_start', userMessage: message });
         bridge?.dispatchTurnStart(message);
         const executorOpts = { enrichSnapshots: true };
         if (options?.onToken && this.opts.streaming) {
@@ -211,6 +234,10 @@ class ParallelRunner {
         const executor = new footprintjs_1.FlowChartExecutor(chart, executorOpts);
         executor.enableNarrative({ renderer: this.narrativeRenderer });
         executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        (0, forwardEmitRecorders_1.forwardEmitRecorders)(executor, this.opts.recorders);
+        if (onStreamEvent) {
+            executor.attachEmitRecorder((0, streaming_1.createStreamEventRecorder)(onStreamEvent));
+        }
         try {
             await executor.run({
                 signal: options?.signal,
@@ -228,14 +255,16 @@ class ParallelRunner {
         const branchResults = (state.branchResults ?? {});
         const messages = state.messages ?? [];
         bridge?.dispatchTurnComplete(result, messages.length);
+        onStreamEvent?.({ type: 'turn_end', content: result, iterations: 1 });
         return {
             content: result,
             branches: Object.values(branchResults),
             messages,
         };
     }
-    getNarrative() {
-        return this.lastExecutor?.getNarrative() ?? [];
+    /** Subscribe to the runner's live stream of events. See AgentRunner.observe(). */
+    observe(handler) {
+        return this.dispatcher.observe(handler);
     }
     getNarrativeEntries() {
         return this.lastExecutor?.getNarrativeEntries() ?? [];