npm - @funkai/agents - Versions diffs - 0.1.0 - Mend

@funkai/agents 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (153) hide show

package/.generated/req.txt +1 -0
package/.turbo/turbo-build.log +21 -0
package/.turbo/turbo-test$colon$coverage.log +109 -0
package/.turbo/turbo-test.log +141 -0
package/.turbo/turbo-typecheck.log +4 -0
package/CHANGELOG.md +16 -0
package/ISSUES.md +540 -0
package/LICENSE +21 -0
package/README.md +128 -0
package/banner.svg +97 -0
package/coverage/lcov-report/base.css +224 -0
package/coverage/lcov-report/block-navigation.js +87 -0
package/coverage/lcov-report/core/agents/base/agent.ts.html +1705 -0
package/coverage/lcov-report/core/agents/base/index.html +146 -0
package/coverage/lcov-report/core/agents/base/output.ts.html +256 -0
package/coverage/lcov-report/core/agents/base/utils.ts.html +694 -0
package/coverage/lcov-report/core/agents/flow/engine.ts.html +928 -0
package/coverage/lcov-report/core/agents/flow/flow-agent.ts.html +1462 -0
package/coverage/lcov-report/core/agents/flow/index.html +146 -0
package/coverage/lcov-report/core/agents/flow/messages.ts.html +508 -0
package/coverage/lcov-report/core/agents/flow/steps/factory.ts.html +1975 -0
package/coverage/lcov-report/core/agents/flow/steps/index.html +116 -0
package/coverage/lcov-report/core/index.html +131 -0
package/coverage/lcov-report/core/logger.ts.html +541 -0
package/coverage/lcov-report/core/models/providers/index.html +116 -0
package/coverage/lcov-report/core/models/providers/openai.ts.html +337 -0
package/coverage/lcov-report/core/provider/index.html +131 -0
package/coverage/lcov-report/core/provider/provider.ts.html +346 -0
package/coverage/lcov-report/core/provider/usage.ts.html +376 -0
package/coverage/lcov-report/core/tool.ts.html +577 -0
package/coverage/lcov-report/favicon.png +0 -0
package/coverage/lcov-report/index.html +221 -0
package/coverage/lcov-report/lib/hooks.ts.html +262 -0
package/coverage/lcov-report/lib/index.html +161 -0
package/coverage/lcov-report/lib/middleware.ts.html +274 -0
package/coverage/lcov-report/lib/runnable.ts.html +151 -0
package/coverage/lcov-report/lib/trace.ts.html +520 -0
package/coverage/lcov-report/prettify.css +1 -0
package/coverage/lcov-report/prettify.js +2 -0
package/coverage/lcov-report/sort-arrow-sprite.png +0 -0
package/coverage/lcov-report/sorter.js +210 -0
package/coverage/lcov-report/utils/attempt.ts.html +199 -0
package/coverage/lcov-report/utils/error.ts.html +421 -0
package/coverage/lcov-report/utils/index.html +176 -0
package/coverage/lcov-report/utils/resolve.ts.html +208 -0
package/coverage/lcov-report/utils/result.ts.html +538 -0
package/coverage/lcov-report/utils/zod.ts.html +178 -0
package/coverage/lcov.info +1566 -0
package/dist/index.d.mts +2883 -0
package/dist/index.d.mts.map +1 -0
package/dist/index.mjs +2312 -0
package/dist/index.mjs.map +1 -0
package/docs/core/agent.md +231 -0
package/docs/core/hooks.md +95 -0
package/docs/core/overview.md +87 -0
package/docs/core/step.md +279 -0
package/docs/core/tools.md +98 -0
package/docs/core/workflow.md +235 -0
package/docs/guides/create-agent.md +224 -0
package/docs/guides/create-tool.md +137 -0
package/docs/guides/create-workflow.md +374 -0
package/docs/overview.md +244 -0
package/docs/provider/models.md +55 -0
package/docs/provider/overview.md +106 -0
package/docs/provider/usage.md +100 -0
package/docs/research/experimental-context.md +167 -0
package/docs/research/gap-analysis.md +86 -0
package/docs/research/prepare-step-and-active-tools.md +138 -0
package/docs/research/sub-agent-model.md +249 -0
package/docs/troubleshooting.md +60 -0
package/logo.svg +17 -0
package/models.config.json +18 -0
package/package.json +60 -0
package/scripts/generate-models.ts +324 -0
package/src/core/agents/base/agent.test.ts +1522 -0
package/src/core/agents/base/agent.ts +547 -0
package/src/core/agents/base/output.test.ts +93 -0
package/src/core/agents/base/output.ts +57 -0
package/src/core/agents/base/types.test-d.ts +69 -0
package/src/core/agents/base/types.ts +503 -0
package/src/core/agents/base/utils.test.ts +397 -0
package/src/core/agents/base/utils.ts +197 -0
package/src/core/agents/flow/engine.test.ts +452 -0
package/src/core/agents/flow/engine.ts +281 -0
package/src/core/agents/flow/flow-agent.test.ts +1027 -0
package/src/core/agents/flow/flow-agent.ts +473 -0
package/src/core/agents/flow/messages.test.ts +198 -0
package/src/core/agents/flow/messages.ts +141 -0
package/src/core/agents/flow/steps/agent.test.ts +280 -0
package/src/core/agents/flow/steps/agent.ts +87 -0
package/src/core/agents/flow/steps/all.test.ts +300 -0
package/src/core/agents/flow/steps/all.ts +73 -0
package/src/core/agents/flow/steps/builder.ts +124 -0
package/src/core/agents/flow/steps/each.test.ts +257 -0
package/src/core/agents/flow/steps/each.ts +61 -0
package/src/core/agents/flow/steps/factory.test-d.ts +50 -0
package/src/core/agents/flow/steps/factory.test.ts +1025 -0
package/src/core/agents/flow/steps/factory.ts +645 -0
package/src/core/agents/flow/steps/map.test.ts +273 -0
package/src/core/agents/flow/steps/map.ts +75 -0
package/src/core/agents/flow/steps/race.test.ts +290 -0
package/src/core/agents/flow/steps/race.ts +59 -0
package/src/core/agents/flow/steps/reduce.test.ts +310 -0
package/src/core/agents/flow/steps/reduce.ts +73 -0
package/src/core/agents/flow/steps/result.ts +27 -0
package/src/core/agents/flow/steps/step.test.ts +402 -0
package/src/core/agents/flow/steps/step.ts +51 -0
package/src/core/agents/flow/steps/while.test.ts +283 -0
package/src/core/agents/flow/steps/while.ts +75 -0
package/src/core/agents/flow/types.ts +348 -0
package/src/core/logger.test.ts +163 -0
package/src/core/logger.ts +152 -0
package/src/core/models/index.test.ts +137 -0
package/src/core/models/index.ts +152 -0
package/src/core/models/providers/openai.ts +84 -0
package/src/core/provider/provider.test.ts +128 -0
package/src/core/provider/provider.ts +99 -0
package/src/core/provider/types.ts +98 -0
package/src/core/provider/usage.test.ts +304 -0
package/src/core/provider/usage.ts +97 -0
package/src/core/tool.test.ts +65 -0
package/src/core/tool.ts +164 -0
package/src/core/types.ts +66 -0
package/src/index.ts +95 -0
package/src/lib/context.test.ts +86 -0
package/src/lib/context.ts +49 -0
package/src/lib/hooks.test.ts +102 -0
package/src/lib/hooks.ts +59 -0
package/src/lib/middleware.test.ts +122 -0
package/src/lib/middleware.ts +63 -0
package/src/lib/runnable.test.ts +41 -0
package/src/lib/runnable.ts +22 -0
package/src/lib/trace.test.ts +291 -0
package/src/lib/trace.ts +145 -0
package/src/models/index.ts +123 -0
package/src/models/providers/index.ts +15 -0
package/src/models/providers/openai.ts +84 -0
package/src/testing/context.ts +32 -0
package/src/testing/index.ts +2 -0
package/src/testing/logger.ts +19 -0
package/src/utils/attempt.test.ts +127 -0
package/src/utils/attempt.ts +38 -0
package/src/utils/error.test.ts +179 -0
package/src/utils/error.ts +112 -0
package/src/utils/resolve.test.ts +38 -0
package/src/utils/resolve.ts +41 -0
package/src/utils/result.test.ts +79 -0
package/src/utils/result.ts +151 -0
package/src/utils/zod.test.ts +69 -0
package/src/utils/zod.ts +31 -0
package/tsconfig.json +25 -0
package/tsdown.config.ts +15 -0
package/vitest.config.ts +46 -0

package/coverage/lcov-report/core/provider/usage.ts.html ADDED Viewed

@@ -0,0 +1,376 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <title>Code coverage report for core/provider/usage.ts</title>
+    <meta charset="utf-8" />
+    <link rel="stylesheet" href="../../prettify.css" />
+    <link rel="stylesheet" href="../../base.css" />
+    <link rel="shortcut icon" type="image/x-icon" href="../../favicon.png" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style type='text/css'>
+        .coverage-summary .sorter {
+            background-image: url(../../sort-arrow-sprite.png);
+        }
+    </style>
+</head>
+<body>
+<div class='wrapper'>
+    <div class='pad1'>
+        <h1><a href="../../index.html">All files</a> / <a href="index.html">core/provider</a> usage.ts</h1>
+        <div class='clearfix'>
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Statements</span>
+                <span class='fraction'>28/28</span>
+            </div>
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Branches</span>
+                <span class='fraction'>12/12</span>
+            </div>
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Functions</span>
+                <span class='fraction'>24/24</span>
+            </div>
+            <div class='fl pad1y space-right2'>
+                <span class="strong">100% </span>
+                <span class="quiet">Lines</span>
+                <span class='fraction'>26/26</span>
+            </div>
+        </div>
+        <p class="quiet">
+            Press <em>n</em> or <em>j</em> to go to the next uncovered block, <em>b</em>, <em>p</em> or <em>k</em> for the previous block.
+        </p>
+        <template id="filterTemplate">
+            <div class="quiet">
+                Filter:
+                <input type="search" id="fileSearch">
+            </div>
+        </template>
+    </div>
+    <div class='status-line high'></div>
+    <pre><table class="coverage">
+<tr><td class="line-count quiet"><a name='L1'></a><a href='#L1'>1</a>
+<a name='L2'></a><a href='#L2'>2</a>
+<a name='L3'></a><a href='#L3'>3</a>
+<a name='L4'></a><a href='#L4'>4</a>
+<a name='L5'></a><a href='#L5'>5</a>
+<a name='L6'></a><a href='#L6'>6</a>
+<a name='L7'></a><a href='#L7'>7</a>
+<a name='L8'></a><a href='#L8'>8</a>
+<a name='L9'></a><a href='#L9'>9</a>
+<a name='L10'></a><a href='#L10'>10</a>
+<a name='L11'></a><a href='#L11'>11</a>
+<a name='L12'></a><a href='#L12'>12</a>
+<a name='L13'></a><a href='#L13'>13</a>
+<a name='L14'></a><a href='#L14'>14</a>
+<a name='L15'></a><a href='#L15'>15</a>
+<a name='L16'></a><a href='#L16'>16</a>
+<a name='L17'></a><a href='#L17'>17</a>
+<a name='L18'></a><a href='#L18'>18</a>
+<a name='L19'></a><a href='#L19'>19</a>
+<a name='L20'></a><a href='#L20'>20</a>
+<a name='L21'></a><a href='#L21'>21</a>
+<a name='L22'></a><a href='#L22'>22</a>
+<a name='L23'></a><a href='#L23'>23</a>
+<a name='L24'></a><a href='#L24'>24</a>
+<a name='L25'></a><a href='#L25'>25</a>
+<a name='L26'></a><a href='#L26'>26</a>
+<a name='L27'></a><a href='#L27'>27</a>
+<a name='L28'></a><a href='#L28'>28</a>
+<a name='L29'></a><a href='#L29'>29</a>
+<a name='L30'></a><a href='#L30'>30</a>
+<a name='L31'></a><a href='#L31'>31</a>
+<a name='L32'></a><a href='#L32'>32</a>
+<a name='L33'></a><a href='#L33'>33</a>
+<a name='L34'></a><a href='#L34'>34</a>
+<a name='L35'></a><a href='#L35'>35</a>
+<a name='L36'></a><a href='#L36'>36</a>
+<a name='L37'></a><a href='#L37'>37</a>
+<a name='L38'></a><a href='#L38'>38</a>
+<a name='L39'></a><a href='#L39'>39</a>
+<a name='L40'></a><a href='#L40'>40</a>
+<a name='L41'></a><a href='#L41'>41</a>
+<a name='L42'></a><a href='#L42'>42</a>
+<a name='L43'></a><a href='#L43'>43</a>
+<a name='L44'></a><a href='#L44'>44</a>
+<a name='L45'></a><a href='#L45'>45</a>
+<a name='L46'></a><a href='#L46'>46</a>
+<a name='L47'></a><a href='#L47'>47</a>
+<a name='L48'></a><a href='#L48'>48</a>
+<a name='L49'></a><a href='#L49'>49</a>
+<a name='L50'></a><a href='#L50'>50</a>
+<a name='L51'></a><a href='#L51'>51</a>
+<a name='L52'></a><a href='#L52'>52</a>
+<a name='L53'></a><a href='#L53'>53</a>
+<a name='L54'></a><a href='#L54'>54</a>
+<a name='L55'></a><a href='#L55'>55</a>
+<a name='L56'></a><a href='#L56'>56</a>
+<a name='L57'></a><a href='#L57'>57</a>
+<a name='L58'></a><a href='#L58'>58</a>
+<a name='L59'></a><a href='#L59'>59</a>
+<a name='L60'></a><a href='#L60'>60</a>
+<a name='L61'></a><a href='#L61'>61</a>
+<a name='L62'></a><a href='#L62'>62</a>
+<a name='L63'></a><a href='#L63'>63</a>
+<a name='L64'></a><a href='#L64'>64</a>
+<a name='L65'></a><a href='#L65'>65</a>
+<a name='L66'></a><a href='#L66'>66</a>
+<a name='L67'></a><a href='#L67'>67</a>
+<a name='L68'></a><a href='#L68'>68</a>
+<a name='L69'></a><a href='#L69'>69</a>
+<a name='L70'></a><a href='#L70'>70</a>
+<a name='L71'></a><a href='#L71'>71</a>
+<a name='L72'></a><a href='#L72'>72</a>
+<a name='L73'></a><a href='#L73'>73</a>
+<a name='L74'></a><a href='#L74'>74</a>
+<a name='L75'></a><a href='#L75'>75</a>
+<a name='L76'></a><a href='#L76'>76</a>
+<a name='L77'></a><a href='#L77'>77</a>
+<a name='L78'></a><a href='#L78'>78</a>
+<a name='L79'></a><a href='#L79'>79</a>
+<a name='L80'></a><a href='#L80'>80</a>
+<a name='L81'></a><a href='#L81'>81</a>
+<a name='L82'></a><a href='#L82'>82</a>
+<a name='L83'></a><a href='#L83'>83</a>
+<a name='L84'></a><a href='#L84'>84</a>
+<a name='L85'></a><a href='#L85'>85</a>
+<a name='L86'></a><a href='#L86'>86</a>
+<a name='L87'></a><a href='#L87'>87</a>
+<a name='L88'></a><a href='#L88'>88</a>
+<a name='L89'></a><a href='#L89'>89</a>
+<a name='L90'></a><a href='#L90'>90</a>
+<a name='L91'></a><a href='#L91'>91</a>
+<a name='L92'></a><a href='#L92'>92</a>
+<a name='L93'></a><a href='#L93'>93</a>
+<a name='L94'></a><a href='#L94'>94</a>
+<a name='L95'></a><a href='#L95'>95</a>
+<a name='L96'></a><a href='#L96'>96</a>
+<a name='L97'></a><a href='#L97'>97</a>
+<a name='L98'></a><a href='#L98'>98</a></td><td class="line-coverage quiet"><span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">11x</span>
+<span class="cline-any cline-yes">16x</span>
+<span class="cline-any cline-yes">16x</span>
+<span class="cline-any cline-yes">16x</span>
+<span class="cline-any cline-yes">16x</span>
+<span class="cline-any cline-yes">16x</span>
+<span class="cline-any cline-yes">16x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">11x</span>
+<span class="cline-any cline-yes">8x</span>
+<span class="cline-any cline-yes">3x</span>
+<span class="cline-any cline-yes">11x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">11x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">8x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">6x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">5x</span>
+<span class="cline-any cline-yes">1x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">2x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">5x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">5x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-yes">52x</span>
+<span class="cline-any cline-yes">10x</span>
+<span class="cline-any cline-yes">10x</span>
+<span class="cline-any cline-yes">10x</span>
+<span class="cline-any cline-yes">10x</span>
+<span class="cline-any cline-yes">10x</span>
+<span class="cline-any cline-yes">10x</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span>
+<span class="cline-any cline-neutral">&nbsp;</span></td><td class="text"><pre class="prettyprint lang-js">import { groupBy, sumBy } from "es-toolkit";
+import { match, P } from "ts-pattern";
+&nbsp;
+import type {
+  TokenUsage,
+  TokenUsageRecord,
+  AgentTokenUsage,
+  FlowAgentTokenUsage,
+} from "@/core/provider/types.js";
+&nbsp;
+/**
+ * Aggregate token counts across multiple raw tracking records.
+ *
+ * Sums each field, treating `undefined` as `0`.
+ */
+function aggregateTokens(usages: TokenUsageRecord[]): TokenUsage {
+  return {
+    inputTokens: sumBy(usages, (u) =&gt; u.inputTokens ?? 0),
+    outputTokens: sumBy(usages, (u) =&gt; u.outputTokens ?? 0),
+    totalTokens: sumBy(usages, (u) =&gt; u.totalTokens ?? 0),
+    cacheReadTokens: sumBy(usages, (u) =&gt; u.cacheReadTokens ?? 0),
+    cacheWriteTokens: sumBy(usages, (u) =&gt; u.cacheWriteTokens ?? 0),
+    reasoningTokens: sumBy(usages, (u) =&gt; u.reasoningTokens ?? 0),
+  };
+}
+&nbsp;
+/**
+ * Compute final usage for a single agent call.
+ *
+ * Aggregates token counts from one or more raw tracking records.
+ * Returns a flat object with tokens + agentId.
+ *
+ * @param agentId - The agent that produced these records.
+ * @param records - Raw tracking records from the agent's execution.
+ * @returns Flat {@link AgentTokenUsage} with resolved token counts.
+ */
+export function agentUsage(
+  agentId: string,
+  records: TokenUsageRecord | TokenUsageRecord[],
+): AgentTokenUsage {
+  const arr = match(records)
+    .when(Array.isArray, (r) =&gt; r)
+    .otherwise((r) =&gt; [r]);
+  const tokens = aggregateTokens(arr);
+&nbsp;
+  return {
+    agentId,
+    ...tokens,
+  };
+}
+&nbsp;
+/**
+ * Compute final usage for a flow agent with multiple agent calls.
+ *
+ * Groups raw tracking records by `source.agentId`, computes per-agent
+ * usage via {@link agentUsage}.
+ *
+ * @param records - Raw tracking records from all agents in the flow.
+ * @returns {@link FlowAgentTokenUsage} with per-agent breakdown.
+ */
+export function flowAgentUsage(records: TokenUsageRecord[]): FlowAgentTokenUsage {
+  const grouped = groupBy(records, (r) =&gt;
+    match(r.source)
+      .with(P.nonNullable, (s) =&gt;
+        match(s.agentId)
+          .with(P.string, (id) =&gt; id)
+          .otherwise(() =&gt; "unknown"),
+      )
+      .otherwise(() =&gt; "unknown"),
+  );
+&nbsp;
+  const usages = Object.entries(grouped).map(([id, group]) =&gt; agentUsage(id, group));
+&nbsp;
+  return {
+    usages,
+  };
+}
+&nbsp;
+/**
+ * Sum multiple {@link TokenUsage} objects field-by-field.
+ *
+ * Pure function — returns a new object without mutating any input.
+ * Returns zero-valued usage when given an empty array.
+ *
+ * @param usages - Array of usage objects to sum.
+ * @returns A new `TokenUsage` with each field summed.
+ */
+export function sumTokenUsage(usages: TokenUsage[]): TokenUsage {
+  return {
+    inputTokens: sumBy(usages, (u) =&gt; u.inputTokens),
+    outputTokens: sumBy(usages, (u) =&gt; u.outputTokens),
+    totalTokens: sumBy(usages, (u) =&gt; u.totalTokens),
+    cacheReadTokens: sumBy(usages, (u) =&gt; u.cacheReadTokens),
+    cacheWriteTokens: sumBy(usages, (u) =&gt; u.cacheWriteTokens),
+    reasoningTokens: sumBy(usages, (u) =&gt; u.reasoningTokens),
+  };
+}
+&nbsp;</pre></td></tr></table></pre>
+                <div class='push'></div><!-- for sticky footer -->
+            </div><!-- /wrapper -->
+            <div class='footer quiet pad2 space-top1 center small'>
+                Code coverage generated by
+                <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
+                at 2026-03-13T01:02:17.231Z
+            </div>
+        <script src="../../prettify.js"></script>
+        <script>
+            window.onload = function () {
+                prettyPrint();
+            };
+        </script>
+        <script src="../../sorter.js"></script>
+        <script src="../../block-navigation.js"></script>
+    </body>
+</html>