agents 0.21.0 → 0.23.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 (258) hide show
  1. package/README.md +21 -1
  2. package/dist/{agent-tool-types-CzGGB-20.d.ts → agent-routing-DE5zmCQ8.d.ts} +1844 -1336
  3. package/dist/agent-routing.d.ts +14 -0
  4. package/dist/agent-routing.js +187 -0
  5. package/dist/agent-routing.js.map +1 -0
  6. package/dist/agent-tool-types.d.ts +26 -26
  7. package/dist/{agent-tools-zR2d5uij.d.ts → agent-tools-DtXMTDGM.d.ts} +7 -7
  8. package/dist/agent-tools.d.ts +21 -21
  9. package/dist/agent-tools.js +2 -1
  10. package/dist/agent-tools.js.map +1 -1
  11. package/dist/browser/ai.js +6 -2
  12. package/dist/browser/ai.js.map +1 -1
  13. package/dist/browser/tanstack-ai.js.map +1 -1
  14. package/dist/callable-decorator-DP__HhBA.d.ts +72 -0
  15. package/dist/callable-decorator.d.ts +18 -0
  16. package/dist/callable-decorator.js +71 -0
  17. package/dist/callable-decorator.js.map +1 -0
  18. package/dist/capability-BjSKYpzg.js +42 -0
  19. package/dist/capability-BjSKYpzg.js.map +1 -0
  20. package/dist/capability-runner-Be_-PLR1.d.ts +459 -0
  21. package/dist/channel-Bnm4S7T2.d.ts +491 -0
  22. package/dist/channels/ai-sdk.d.ts +46 -0
  23. package/dist/channels/ai-sdk.js +120 -0
  24. package/dist/channels/ai-sdk.js.map +1 -0
  25. package/dist/channels/email.d.ts +95 -0
  26. package/dist/channels/email.js +323 -0
  27. package/dist/channels/email.js.map +1 -0
  28. package/dist/channels/index.d.ts +233 -0
  29. package/dist/channels/index.js +608 -0
  30. package/dist/channels/index.js.map +1 -0
  31. package/dist/channels/slack.d.ts +140 -0
  32. package/dist/channels/slack.js +614 -0
  33. package/dist/channels/slack.js.map +1 -0
  34. package/dist/channels/tanstack-ai.d.ts +39 -0
  35. package/dist/channels/tanstack-ai.js +17 -0
  36. package/dist/channels/tanstack-ai.js.map +1 -0
  37. package/dist/channels/telegram.d.ts +106 -0
  38. package/dist/channels/telegram.js +427 -0
  39. package/dist/channels/telegram.js.map +1 -0
  40. package/dist/channels/voice.d.ts +45 -0
  41. package/dist/channels/voice.js +122 -0
  42. package/dist/channels/voice.js.map +1 -0
  43. package/dist/chat/index.d.ts +2328 -2015
  44. package/dist/chat/index.js +891 -521
  45. package/dist/chat/index.js.map +1 -1
  46. package/dist/chat/react.d.ts +14 -1
  47. package/dist/chat/react.js +82 -52
  48. package/dist/chat/react.js.map +1 -1
  49. package/dist/chat/transport.js +1 -1
  50. package/dist/chat-sdk/index.d.ts +7 -7
  51. package/dist/chat-sdk/index.js +1 -1
  52. package/dist/{client-zqKcsyFa.js → client-jagG8a9_.js} +129 -37
  53. package/dist/client-jagG8a9_.js.map +1 -0
  54. package/dist/client.d.ts +1 -1
  55. package/dist/client.js +1 -1
  56. package/dist/{cloudflare-BduZwmYK.js → cloudflare-Dzvc7V2N.js} +10 -3
  57. package/dist/{cloudflare-BduZwmYK.js.map → cloudflare-Dzvc7V2N.js.map} +1 -1
  58. package/dist/context/index.d.ts +216 -0
  59. package/dist/context/index.js +454 -0
  60. package/dist/context/index.js.map +1 -0
  61. package/dist/current-agent-Da_C9a3b.d.ts +266 -0
  62. package/dist/current-agent-DhoDkSnH.js +51 -0
  63. package/dist/current-agent-DhoDkSnH.js.map +1 -0
  64. package/dist/diagnostics-BzvaX2UT.js +45 -0
  65. package/dist/diagnostics-BzvaX2UT.js.map +1 -0
  66. package/dist/diagnostics-C4jcz3VK.js +360 -0
  67. package/dist/diagnostics-C4jcz3VK.js.map +1 -0
  68. package/dist/{do-oauth-client-provider-VTZj2VtM.d.ts → do-oauth-client-provider-Tmf1vgKz.d.ts} +2 -2
  69. package/dist/{email-CL27preh.d.ts → email-7TatiTnl.d.ts} +38 -9
  70. package/dist/email-send.d.ts +15 -0
  71. package/dist/email-send.js +32 -0
  72. package/dist/email-send.js.map +1 -0
  73. package/dist/email.d.ts +14 -10
  74. package/dist/email.js.map +1 -1
  75. package/dist/{handler-stateless-C_bo-Ytq.d.ts → handler-stateless-DxYpJ_XF.d.ts} +3 -3
  76. package/dist/{handler-stateless-CIkKPETH.js → handler-stateless-VvrWSAVA.js} +5 -5
  77. package/dist/handler-stateless-VvrWSAVA.js.map +1 -0
  78. package/dist/index-BB0kqhIz.d.ts +101 -0
  79. package/dist/index-XDkuQ7zm.d.ts +89 -0
  80. package/dist/{index-BRnybD6X.d.ts → index-YSKgfgg9.d.ts} +21 -31
  81. package/dist/index.d.ts +113 -101
  82. package/dist/index.js +11 -7234
  83. package/dist/ingress-BfetZbMO.js +83 -0
  84. package/dist/ingress-BfetZbMO.js.map +1 -0
  85. package/dist/internal-CYlgHl1l.js +59 -0
  86. package/dist/internal-CYlgHl1l.js.map +1 -0
  87. package/dist/internal_context-BlxFEWfn.d.ts +19 -0
  88. package/dist/internal_context.d.ts +10 -4
  89. package/dist/internal_context.js +1 -10
  90. package/dist/{client-invoker-BNSZxAkv.d.ts → invoker-CG0_p_Wq.d.ts} +2 -2
  91. package/dist/{client-invoker-VNZ7X0nn.js → invoker-CHMnoxIA.js} +2 -2
  92. package/dist/invoker-CHMnoxIA.js.map +1 -0
  93. package/dist/lifecycle/index.d.ts +66 -0
  94. package/dist/lifecycle/index.js +4 -0
  95. package/dist/lifecycle-CMRGjZdw.js +1299 -0
  96. package/dist/lifecycle-CMRGjZdw.js.map +1 -0
  97. package/dist/mcp/{do-oauth-client-provider.d.ts → client/do-oauth-client-provider.d.ts} +1 -1
  98. package/dist/mcp/{do-oauth-client-provider.js → client/do-oauth-client-provider.js} +1 -1
  99. package/dist/mcp/client/do-oauth-client-provider.js.map +1 -0
  100. package/dist/mcp/client/index.d.ts +42 -0
  101. package/dist/mcp/{client.js → client/index.js} +1 -1
  102. package/dist/mcp/{x402.d.ts → client/x402.d.ts} +2 -2
  103. package/dist/mcp/{x402.js → client/x402.js} +2 -2
  104. package/dist/mcp/client/x402.js.map +1 -0
  105. package/dist/mcp/index.d.ts +36 -36
  106. package/dist/mcp/index.js +14 -16
  107. package/dist/mcp/index.js.map +1 -1
  108. package/dist/mcp/{server.d.ts → server/index.d.ts} +1 -1
  109. package/dist/mcp/{server.js → server/index.js} +1 -1
  110. package/dist/observability/ai/index.js +50 -35
  111. package/dist/observability/ai/index.js.map +1 -1
  112. package/dist/observability/index.d.ts +4 -4
  113. package/dist/observability/index.js +3 -50
  114. package/dist/observability/index.js.map +1 -1
  115. package/dist/{protocol-Dqc2MQxo.js → protocol-B0nh6KNf.js} +19 -21
  116. package/dist/protocol-B0nh6KNf.js.map +1 -0
  117. package/dist/react.d.ts +4 -4
  118. package/dist/react.js +1 -1
  119. package/dist/{retries-CAvxtG9d.d.ts → retries-D9Ds-1lz.d.ts} +17 -6
  120. package/dist/retries.d.ts +8 -6
  121. package/dist/retries.js +13 -1
  122. package/dist/retries.js.map +1 -1
  123. package/dist/routing/index.d.ts +137 -0
  124. package/dist/routing/index.js +244 -0
  125. package/dist/routing/index.js.map +1 -0
  126. package/dist/sanitize-D9TujEK8.js +79 -0
  127. package/dist/sanitize-D9TujEK8.js.map +1 -0
  128. package/dist/schedule.d.ts +25 -94
  129. package/dist/schedule.js +1 -98
  130. package/dist/schedule.js.map +1 -1
  131. package/dist/scheduler-DD9NdYbF.js +665 -0
  132. package/dist/scheduler-DD9NdYbF.js.map +1 -0
  133. package/dist/scheduler-Dwh85ZGl.d.ts +223 -0
  134. package/dist/schedules/index.d.ts +22 -0
  135. package/dist/schedules/index.js +2 -0
  136. package/dist/schedules/parser.d.ts +79 -0
  137. package/dist/schedules/parser.js +103 -0
  138. package/dist/schedules/parser.js.map +1 -0
  139. package/dist/sentence-chunker-BAidJ4DA.d.ts +68 -0
  140. package/dist/serializable.d.ts +1 -1
  141. package/dist/sessions/index.d.ts +441 -0
  142. package/dist/sessions/index.js +2063 -0
  143. package/dist/sessions/index.js.map +1 -0
  144. package/dist/skills/index.d.ts +99 -0
  145. package/dist/skills/index.js +254 -5
  146. package/dist/skills/index.js.map +1 -1
  147. package/dist/sql-error-CPY-GXyI.d.ts +12 -0
  148. package/dist/sql-error.d.ts +2 -0
  149. package/dist/sql-error.js +16 -0
  150. package/dist/sql-error.js.map +1 -0
  151. package/dist/src-DlSHshb2.js +6963 -0
  152. package/dist/src-DlSHshb2.js.map +1 -0
  153. package/dist/streams/index.d.ts +120 -0
  154. package/dist/streams/index.js +107 -0
  155. package/dist/streams/index.js.map +1 -0
  156. package/dist/streams-D6tJ0NN9.d.ts +370 -0
  157. package/dist/streams-DZKgAj9b.js +709 -0
  158. package/dist/streams-DZKgAj9b.js.map +1 -0
  159. package/dist/sub-routing.d.ts +12 -12
  160. package/dist/surface-bZZJqBka.js +17 -0
  161. package/dist/surface-bZZJqBka.js.map +1 -0
  162. package/dist/tasks/index.d.ts +64 -0
  163. package/dist/tasks/index.js +2 -0
  164. package/dist/tasks-BRJ5zgya.d.ts +517 -0
  165. package/dist/tasks-ylZgBjhj.js +1656 -0
  166. package/dist/tasks-ylZgBjhj.js.map +1 -0
  167. package/dist/text-segment-joiner-BtAFQSA_.js +57 -0
  168. package/dist/text-segment-joiner-BtAFQSA_.js.map +1 -0
  169. package/dist/text-stream-CpdiKrJB.js +272 -0
  170. package/dist/text-stream-CpdiKrJB.js.map +1 -0
  171. package/dist/tokens-nHAKcN6M.js +52 -0
  172. package/dist/tokens-nHAKcN6M.js.map +1 -0
  173. package/dist/tool-schema-CBjGPrsQ.js +31 -0
  174. package/dist/tool-schema-CBjGPrsQ.js.map +1 -0
  175. package/dist/types-B7LojTe4.d.ts +202 -0
  176. package/dist/types-_Faxb570.d.ts +439 -0
  177. package/dist/voice/client.d.ts +226 -0
  178. package/dist/voice/client.js +932 -0
  179. package/dist/voice/client.js.map +1 -0
  180. package/dist/voice/errors.d.ts +43 -0
  181. package/dist/voice/errors.js +41 -0
  182. package/dist/voice/errors.js.map +1 -0
  183. package/dist/voice/index.d.ts +271 -0
  184. package/dist/voice/index.js +1812 -0
  185. package/dist/voice/index.js.map +1 -0
  186. package/dist/voice/react.d.ts +167 -0
  187. package/dist/voice/react.js +234 -0
  188. package/dist/voice/react.js.map +1 -0
  189. package/dist/voice/sfu.d.ts +71 -0
  190. package/dist/voice/sfu.js +157 -0
  191. package/dist/voice/sfu.js.map +1 -0
  192. package/dist/voice/text.d.ts +6 -0
  193. package/dist/voice/text.js +2 -0
  194. package/dist/voice/types.d.ts +58 -0
  195. package/dist/voice/types.js +18 -0
  196. package/dist/voice/types.js.map +1 -0
  197. package/dist/voice/workers-ai.d.ts +136 -0
  198. package/dist/voice/workers-ai.js +568 -0
  199. package/dist/voice/workers-ai.js.map +1 -0
  200. package/dist/websockets/index.d.ts +192 -0
  201. package/dist/websockets/index.js +2 -0
  202. package/dist/websockets-DUfRHPRq.js +502 -0
  203. package/dist/websockets-DUfRHPRq.js.map +1 -0
  204. package/dist/workflow-types.d.ts +25 -25
  205. package/dist/workflows.d.ts +22 -22
  206. package/dist/workflows.js +2 -1
  207. package/dist/workflows.js.map +1 -1
  208. package/dist/{ws-chat-transport-CIoOBbO7.js → ws-chat-transport-rWwta645.js} +152 -15
  209. package/dist/ws-chat-transport-rWwta645.js.map +1 -0
  210. package/docs/agent-class.md +29 -87
  211. package/docs/agent-tools.md +2 -1
  212. package/docs/channels.md +323 -0
  213. package/docs/chat-agents.md +19 -25
  214. package/docs/context.md +131 -0
  215. package/docs/durable-execution.md +1 -1
  216. package/docs/http-websockets.md +1 -11
  217. package/docs/human-in-the-loop.md +1 -1
  218. package/docs/index.md +16 -12
  219. package/docs/lifecycle.md +370 -0
  220. package/docs/long-running-agents.md +4 -6
  221. package/docs/mcp-client.md +55 -0
  222. package/docs/mcp-servers.md +5 -1
  223. package/docs/observability.md +11 -11
  224. package/docs/resumable-streaming.md +2 -2
  225. package/docs/routing.md +105 -0
  226. package/docs/scheduling.md +175 -15
  227. package/docs/server-driven-messages.md +1 -1
  228. package/docs/sessions.md +237 -871
  229. package/docs/streams.md +213 -0
  230. package/docs/sub-agents.md +185 -125
  231. package/docs/tasks.md +246 -0
  232. package/docs/voice.md +745 -0
  233. package/package.json +144 -33
  234. package/dist/cli/index.js +0 -26
  235. package/dist/cli/index.js.map +0 -1
  236. package/dist/client-invoker-VNZ7X0nn.js.map +0 -1
  237. package/dist/client-zqKcsyFa.js.map +0 -1
  238. package/dist/compaction-helpers-iiKMr2TQ.js +0 -340
  239. package/dist/compaction-helpers-iiKMr2TQ.js.map +0 -1
  240. package/dist/compaction-helpers-wUz6M3us.d.ts +0 -621
  241. package/dist/experimental/memory/session/index.d.ts +0 -670
  242. package/dist/experimental/memory/session/index.js +0 -2374
  243. package/dist/experimental/memory/session/index.js.map +0 -1
  244. package/dist/experimental/memory/utils/index.d.ts +0 -96
  245. package/dist/experimental/memory/utils/index.js +0 -79
  246. package/dist/experimental/memory/utils/index.js.map +0 -1
  247. package/dist/handler-stateless-CIkKPETH.js.map +0 -1
  248. package/dist/index.js.map +0 -1
  249. package/dist/internal_context-Dg4Cgjcu.d.ts +0 -37
  250. package/dist/internal_context.js.map +0 -1
  251. package/dist/mcp/client.d.ts +0 -42
  252. package/dist/mcp/do-oauth-client-provider.js.map +0 -1
  253. package/dist/mcp/x402.js.map +0 -1
  254. package/dist/protocol-Dqc2MQxo.js.map +0 -1
  255. package/dist/tool-output-truncation-CNnnGZQ3.js +0 -98
  256. package/dist/tool-output-truncation-CNnnGZQ3.js.map +0 -1
  257. package/dist/ws-chat-transport-CIoOBbO7.js.map +0 -1
  258. /package/dist/{cli/index.d.ts → index-BVVgDSdq.d.ts} +0 -0
@@ -1,340 +0,0 @@
1
- //#region src/experimental/memory/utils/tokens.ts
2
- /** Approximate characters per token for English text */
3
- const CHARS_PER_TOKEN = 4;
4
- /** Approximate token multiplier per whitespace-separated word */
5
- const WORDS_TOKEN_MULTIPLIER = 1.3;
6
- /** Approximate overhead tokens per message (role, framing) */
7
- const TOKENS_PER_MESSAGE = 4;
8
- /**
9
- * Estimate token count for a string using a hybrid heuristic.
10
- *
11
- * Takes the max of two estimates:
12
- * - Character-based: `length / 4` — better for dense content (JSON, code, URLs)
13
- * - Word-based: `words * 1.3` — better for natural language prose
14
- *
15
- * This is a heuristic. Do not use where exact counts are required.
16
- */
17
- function estimateStringTokens(text) {
18
- if (!text) return 0;
19
- const charEstimate = text.length / 4;
20
- const wordEstimate = text.split(/\s+/).filter(Boolean).length * WORDS_TOKEN_MULTIPLIER;
21
- return Math.ceil(Math.max(charEstimate, wordEstimate));
22
- }
23
- function estimateUnknownTokens(value) {
24
- if (value === null || value === void 0) return 0;
25
- if (typeof value === "string") return estimateStringTokens(value);
26
- try {
27
- return estimateStringTokens(JSON.stringify(value));
28
- } catch {
29
- return estimateStringTokens(String(value));
30
- }
31
- }
32
- /**
33
- * Estimate total token count for an array of UIMessages.
34
- *
35
- * Walks each message's parts (text, reasoning, tool invocations, tool results)
36
- * and applies per-message overhead.
37
- *
38
- * This is a heuristic. Do not use where exact counts are required.
39
- */
40
- function estimateMessageTokens(messages) {
41
- let tokens = 0;
42
- for (const msg of messages) {
43
- tokens += 4;
44
- for (const part of msg.parts) if (part.type === "text" || part.type === "reasoning") tokens += estimateUnknownTokens(part.text ?? part.reasoning);
45
- else if (part.type.startsWith("tool-") || part.type === "dynamic-tool") {
46
- tokens += estimateUnknownTokens(part.input);
47
- tokens += estimateUnknownTokens(part.output ?? part.result);
48
- } else if (part.text !== void 0) tokens += estimateUnknownTokens(part.text);
49
- else if (part.result !== void 0) tokens += estimateUnknownTokens(part.result);
50
- }
51
- return tokens;
52
- }
53
- //#endregion
54
- //#region src/experimental/memory/utils/compaction-helpers.ts
55
- /** Prefix for all compaction messages (overlays and summaries) */
56
- const COMPACTION_PREFIX = "compaction_";
57
- /** Check if a message is a compaction message */
58
- function isCompactionMessage(msg) {
59
- return msg.id.startsWith(COMPACTION_PREFIX);
60
- }
61
- /**
62
- * Check if a message contains tool invocations.
63
- */
64
- function hasToolCalls(msg) {
65
- return msg.parts.some((p) => p.type.startsWith("tool-") || p.type === "dynamic-tool");
66
- }
67
- /**
68
- * Get tool call IDs from a message's parts.
69
- */
70
- function getToolCallIds(msg) {
71
- const ids = /* @__PURE__ */ new Set();
72
- for (const part of msg.parts) if ((part.type.startsWith("tool-") || part.type === "dynamic-tool") && "toolCallId" in part) ids.add(part.toolCallId);
73
- return ids;
74
- }
75
- /**
76
- * Check if a message is a tool result referencing a specific call ID.
77
- */
78
- function isToolResultFor(msg, callIds) {
79
- return msg.parts.some((p) => (p.type.startsWith("tool-") || p.type === "dynamic-tool") && "toolCallId" in p && callIds.has(p.toolCallId));
80
- }
81
- /**
82
- * Align a boundary index forward to avoid splitting tool call/result groups.
83
- * If the boundary falls between an assistant message with tool calls and its
84
- * tool results, move it forward past the results.
85
- */
86
- function alignBoundaryForward(messages, idx) {
87
- if (idx <= 0 || idx >= messages.length) return idx;
88
- const prev = messages[idx - 1];
89
- if (prev.role === "assistant" && hasToolCalls(prev)) {
90
- const callIds = getToolCallIds(prev);
91
- while (idx < messages.length && isToolResultFor(messages[idx], callIds)) idx++;
92
- }
93
- return idx;
94
- }
95
- /**
96
- * Align a boundary index backward to avoid splitting tool call/result groups.
97
- * If the boundary falls in the middle of tool results, move it backward to
98
- * include the assistant message that made the calls.
99
- */
100
- function alignBoundaryBackward(messages, idx) {
101
- if (idx <= 0 || idx >= messages.length) return idx;
102
- while (idx > 0) {
103
- const msg = messages[idx];
104
- if (msg.role === "assistant" && hasToolCalls(msg)) break;
105
- const prev = messages[idx - 1];
106
- if (prev.role === "assistant" && hasToolCalls(prev)) {
107
- if (isToolResultFor(msg, getToolCallIds(prev))) {
108
- idx--;
109
- continue;
110
- }
111
- }
112
- break;
113
- }
114
- return idx;
115
- }
116
- /**
117
- * Find the compression end boundary using a token budget for the tail.
118
- * Walks backward from the end, accumulating tokens until budget is reached.
119
- * Returns the index where compression should stop (everything from this
120
- * index onward is protected).
121
- *
122
- * @param messages All messages
123
- * @param headEnd Index where the protected head ends (compression starts here)
124
- * @param tailTokenBudget Maximum tokens to keep in the tail
125
- * @param minTailMessages Minimum messages to protect in the tail (fallback)
126
- */
127
- function findTailCutByTokens(messages, headEnd, tailTokenBudget = 2e4, minTailMessages = 2) {
128
- const n = messages.length;
129
- let accumulated = 0;
130
- let tokenCut = n;
131
- for (let i = n - 1; i >= headEnd; i--) {
132
- const msgTokens = estimateMessageTokens([messages[i]]);
133
- if (accumulated + msgTokens > tailTokenBudget && tokenCut < n) break;
134
- accumulated += msgTokens;
135
- tokenCut = i;
136
- }
137
- const minCut = n - minTailMessages;
138
- return alignBoundaryBackward(messages, minCut >= headEnd ? Math.min(tokenCut, minCut) : tokenCut);
139
- }
140
- async function findTailCutByTokensWithCounter(messages, headEnd, tokenCounter, tailTokenBudget = 2e4, minTailMessages = 2) {
141
- const n = messages.length;
142
- let accumulated = 0;
143
- let tokenCut = n;
144
- for (let i = n - 1; i >= headEnd; i--) {
145
- const msgTokens = await tokenCounter([messages[i]]);
146
- if (accumulated + msgTokens > tailTokenBudget && tokenCut < n) break;
147
- accumulated += msgTokens;
148
- tokenCut = i;
149
- }
150
- const minCut = n - minTailMessages;
151
- return alignBoundaryBackward(messages, minCut >= headEnd ? Math.min(tokenCut, minCut) : tokenCut);
152
- }
153
- /**
154
- * Fix orphaned tool call/result pairs after compaction.
155
- *
156
- * Two failure modes:
157
- * 1. Tool result references a call_id whose assistant tool_call was removed
158
- * → Remove the orphaned result
159
- * 2. Assistant has tool_calls whose results were dropped
160
- * → Add stub results so the API doesn't error
161
- *
162
- * @param messages Messages after compaction
163
- * @returns Sanitized messages with no orphaned pairs
164
- */
165
- function sanitizeToolPairs(messages) {
166
- const survivingCallIds = /* @__PURE__ */ new Set();
167
- for (const msg of messages) if (msg.role === "assistant") for (const id of getToolCallIds(msg)) survivingCallIds.add(id);
168
- const resultCallIds = /* @__PURE__ */ new Set();
169
- for (const msg of messages) for (const part of msg.parts) if ((part.type.startsWith("tool-") || part.type === "dynamic-tool") && "toolCallId" in part && "output" in part) resultCallIds.add(part.toolCallId);
170
- const orphanedResults = /* @__PURE__ */ new Set();
171
- for (const id of resultCallIds) if (!survivingCallIds.has(id)) orphanedResults.add(id);
172
- let result = messages;
173
- if (orphanedResults.size > 0) result = result.map((msg) => {
174
- const filteredParts = msg.parts.filter((part) => {
175
- if ((part.type.startsWith("tool-") || part.type === "dynamic-tool") && "toolCallId" in part && "output" in part) return !orphanedResults.has(part.toolCallId);
176
- return true;
177
- });
178
- if (filteredParts.length !== msg.parts.length) return {
179
- ...msg,
180
- parts: filteredParts
181
- };
182
- return msg;
183
- });
184
- const missingResults = /* @__PURE__ */ new Set();
185
- for (const id of survivingCallIds) if (!resultCallIds.has(id) && !orphanedResults.has(id)) missingResults.add(id);
186
- if (missingResults.size > 0) {
187
- const patched = [];
188
- for (const msg of result) {
189
- patched.push(msg);
190
- if (msg.role === "assistant") {
191
- for (const id of getToolCallIds(msg)) if (missingResults.has(id)) {
192
- const callPart = msg.parts.find((p) => "toolCallId" in p && p.toolCallId === id);
193
- patched.push({
194
- id: `stub-${id}`,
195
- role: "assistant",
196
- parts: [{
197
- type: "tool-result",
198
- toolCallId: id,
199
- toolName: callPart?.toolName ?? "unknown",
200
- result: "[Result from earlier conversation — see context summary above]"
201
- }],
202
- createdAt: /* @__PURE__ */ new Date()
203
- });
204
- }
205
- }
206
- }
207
- result = patched;
208
- }
209
- return result.filter((msg) => msg.parts.length > 0);
210
- }
211
- /**
212
- * Compute a summary token budget based on the content being compressed.
213
- * 20% of the compressed content, clamped to 2K-8K tokens.
214
- */
215
- function computeSummaryBudget(messages) {
216
- const contentTokens = estimateMessageTokens(messages);
217
- const budget = Math.floor(contentTokens * .2);
218
- return Math.max(100, budget);
219
- }
220
- /**
221
- * Build a prompt for LLM summarization of compressed messages.
222
- *
223
- * @param messages Messages to summarize
224
- * @param previousSummary Previous summary for iterative updates (or null for first compaction)
225
- * @param budget Target token count for the summary
226
- */
227
- function buildSummaryPrompt(messages, previousSummary, budget) {
228
- const content = messages.map((msg) => {
229
- const textParts = msg.parts.filter((p) => p.type === "text").map((p) => p.text).join("\n");
230
- const toolParts = msg.parts.filter((p) => p.type.startsWith("tool-") || p.type === "dynamic-tool").map((p) => {
231
- const tp = p;
232
- const parts = [`[Tool: ${tp.toolName ?? "unknown"}]`];
233
- if (tp.input) parts.push(`Input: ${JSON.stringify(tp.input).slice(0, 500)}`);
234
- if (tp.output) parts.push(`Output: ${String(tp.output).slice(0, 500)}`);
235
- return parts.join("\n");
236
- }).join("\n");
237
- return `[${msg.role}]\n${textParts}${toolParts ? "\n" + toolParts : ""}`;
238
- }).join("\n\n---\n\n");
239
- if (previousSummary) return `You are updating a conversation summary. A previous summary exists below. New conversation turns have occurred since then and need to be incorporated.
240
-
241
- PREVIOUS SUMMARY:
242
- ${previousSummary}
243
-
244
- NEW TURNS TO INCORPORATE:
245
- ${content}
246
-
247
- Update the summary. PRESERVE existing information that is still relevant. ADD new information. Remove information only if it is clearly obsolete.
248
-
249
- ## Topic
250
- [What the conversation is about]
251
-
252
- ## Key Points
253
- [Important information, decisions, and conclusions from the conversation]
254
-
255
- ## Current State
256
- [Where things stand now — what has been done, what is in progress]
257
-
258
- ## Open Items
259
- [Unresolved questions, pending tasks, or next steps discussed]
260
-
261
- Target ~${budget} tokens. Be factual — only include information that was explicitly discussed in the conversation. Do NOT invent file paths, commands, or details that were not mentioned. Write only the summary body.`;
262
- return `Create a concise summary of this conversation that preserves the important information for future context.
263
-
264
- CONVERSATION TO SUMMARIZE:
265
- ${content}
266
-
267
- Use this structure:
268
-
269
- ## Topic
270
- [What the conversation is about]
271
-
272
- ## Key Points
273
- [Important information, decisions, and conclusions from the conversation]
274
-
275
- ## Current State
276
- [Where things stand now — what has been done, what is in progress]
277
-
278
- ## Open Items
279
- [Unresolved questions, pending tasks, or next steps discussed]
280
-
281
- Target ~${budget} tokens. Be factual — only include information that was explicitly discussed in the conversation. Do NOT invent file paths, commands, or details that were not mentioned. Write only the summary body.`;
282
- }
283
- /**
284
- * Reference compaction implementation.
285
- *
286
- * Implements the full hermes-style compaction algorithm:
287
- * 1. Protect head messages (first N)
288
- * 2. Protect tail by token budget (walk backward)
289
- * 3. Align boundaries to tool call groups
290
- * 4. Summarize middle section with LLM (structured format)
291
- * 5. Sanitize orphaned tool pairs
292
- * 6. Iterative summary updates on subsequent compactions
293
- *
294
- * @example
295
- * ```typescript
296
- * import { createCompactFunction } from "agents/experimental/memory/utils";
297
- *
298
- * const session = new Session(provider, {
299
- * compaction: {
300
- * tokenThreshold: 100000,
301
- * fn: createCompactFunction({
302
- * summarize: (prompt) => generateText({ model, prompt }).then(r => r.text)
303
- * })
304
- * }
305
- * });
306
- * ```
307
- */
308
- function createCompactFunction(opts) {
309
- const protectHead = opts.protectHead ?? 3;
310
- const tailTokenBudget = opts.tailTokenBudget ?? 2e4;
311
- const minTailMessages = opts.minTailMessages ?? 2;
312
- return async (messages, context) => {
313
- if (messages.length <= protectHead + minTailMessages) return null;
314
- const sessionCounter = context?.tokenCounter;
315
- const tailCounter = opts.tokenCounter ?? (sessionCounter ? (msgs) => sessionCounter({
316
- messages: msgs,
317
- systemPrompt: "",
318
- contextBlocks: []
319
- }) : void 0);
320
- let compressStart = protectHead;
321
- compressStart = alignBoundaryForward(messages, compressStart);
322
- let compressEnd = tailCounter ? await findTailCutByTokensWithCounter(messages, compressStart, tailCounter, tailTokenBudget, minTailMessages) : findTailCutByTokens(messages, compressStart, tailTokenBudget, minTailMessages);
323
- if (compressEnd <= compressStart) return null;
324
- const middleMessages = messages.slice(compressStart, compressEnd).filter((m) => !isCompactionMessage(m));
325
- if (middleMessages.length === 0) return null;
326
- const existingCompaction = messages.find(isCompactionMessage);
327
- const prompt = buildSummaryPrompt(middleMessages, existingCompaction ? existingCompaction.parts.filter((p) => p.type === "text").map((p) => p.text).join("\n") : null, computeSummaryBudget(middleMessages));
328
- const summary = await opts.summarize(prompt);
329
- if (!summary.trim()) return null;
330
- return {
331
- fromMessageId: middleMessages[0].id,
332
- toMessageId: middleMessages[middleMessages.length - 1].id,
333
- summary
334
- };
335
- };
336
- }
337
- //#endregion
338
- export { computeSummaryBudget as a, isCompactionMessage as c, TOKENS_PER_MESSAGE as d, WORDS_TOKEN_MULTIPLIER as f, buildSummaryPrompt as i, sanitizeToolPairs as l, estimateStringTokens as m, alignBoundaryBackward as n, createCompactFunction as o, estimateMessageTokens as p, alignBoundaryForward as r, findTailCutByTokens as s, COMPACTION_PREFIX as t, CHARS_PER_TOKEN as u };
339
-
340
- //# sourceMappingURL=compaction-helpers-iiKMr2TQ.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"compaction-helpers-iiKMr2TQ.js","names":[],"sources":["../src/experimental/memory/utils/tokens.ts","../src/experimental/memory/utils/compaction-helpers.ts"],"sourcesContent":["/**\n * Token Estimation Utilities\n *\n * IMPORTANT: These are heuristic estimates, not actual tokenizer counts.\n *\n * We intentionally avoid real tokenizers (e.g. tiktoken, sentencepiece) because:\n * - A single tiktoken instance costs ~80-120MB of heap\n * - Cloudflare Workers have tight memory limits (128MB)\n * - For compaction thresholds, a conservative estimate is sufficient\n *\n * The hybrid approach (max of character-based and word-based estimates) handles\n * both dense token content (JSON, code) and natural language reasonably well.\n *\n * Calibration notes:\n * - Character-based: ~4 chars per token (conservative, from OpenAI guidance)\n * - Word-based: ~1.3 tokens per word (empirical, from Mastra's memory system)\n * - Per-message overhead: ~4 tokens for role/framing (empirical)\n *\n * These ratios are tuned for English. CJK, emoji-heavy, or highly technical\n * content may have different ratios. The conservative estimates help ensure\n * compaction triggers before context windows are actually exceeded.\n */\n\nimport type { SessionMessage } from \"../session/types\";\n\n/** Approximate characters per token for English text */\nexport const CHARS_PER_TOKEN = 4;\n\n/** Approximate token multiplier per whitespace-separated word */\nexport const WORDS_TOKEN_MULTIPLIER = 1.3;\n\n/** Approximate overhead tokens per message (role, framing) */\nexport const TOKENS_PER_MESSAGE = 4;\n\n/**\n * Estimate token count for a string using a hybrid heuristic.\n *\n * Takes the max of two estimates:\n * - Character-based: `length / 4` — better for dense content (JSON, code, URLs)\n * - Word-based: `words * 1.3` — better for natural language prose\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateStringTokens(text: string): number {\n if (!text) return 0;\n const charEstimate = text.length / CHARS_PER_TOKEN;\n const wordEstimate =\n text.split(/\\s+/).filter(Boolean).length * WORDS_TOKEN_MULTIPLIER;\n return Math.ceil(Math.max(charEstimate, wordEstimate));\n}\n\nfunction estimateUnknownTokens(value: unknown): number {\n if (value === null || value === undefined) return 0;\n if (typeof value === \"string\") return estimateStringTokens(value);\n\n try {\n return estimateStringTokens(JSON.stringify(value));\n } catch {\n return estimateStringTokens(String(value));\n }\n}\n\n/**\n * Estimate total token count for an array of UIMessages.\n *\n * Walks each message's parts (text, reasoning, tool invocations, tool results)\n * and applies per-message overhead.\n *\n * This is a heuristic. Do not use where exact counts are required.\n */\nexport function estimateMessageTokens(messages: SessionMessage[]): number {\n let tokens = 0;\n for (const msg of messages) {\n tokens += TOKENS_PER_MESSAGE;\n for (const part of msg.parts) {\n if (part.type === \"text\" || part.type === \"reasoning\") {\n tokens += estimateUnknownTokens(part.text ?? part.reasoning);\n } else if (\n part.type.startsWith(\"tool-\") ||\n part.type === \"dynamic-tool\"\n ) {\n tokens += estimateUnknownTokens(part.input);\n tokens += estimateUnknownTokens(part.output ?? part.result);\n } else if (part.text !== undefined) {\n tokens += estimateUnknownTokens(part.text);\n } else if (part.result !== undefined) {\n tokens += estimateUnknownTokens(part.result);\n }\n }\n }\n return tokens;\n}\n","/**\n * Compaction Helpers\n *\n * Utilities for full compaction (LLM-based summarization).\n * Used by the reference compaction implementation and available\n * for custom CompactFunction implementations.\n */\n\nimport type { CompactContext, SessionMessage } from \"../session/types\";\nimport { estimateMessageTokens } from \"./tokens\";\n\nexport type CompactTokenCounter = (\n messages: SessionMessage[]\n) => number | Promise<number>;\n\n// ── Compaction ID constants ─────────────────────────────────────────\n\n/** Prefix for all compaction messages (overlays and summaries) */\nexport const COMPACTION_PREFIX = \"compaction_\";\n\n/** Check if a message is a compaction message */\nexport function isCompactionMessage(msg: SessionMessage): boolean {\n return msg.id.startsWith(COMPACTION_PREFIX);\n}\n\n// ── Tool Pair Alignment ──────────────────────────────────────────────\n\n/**\n * Check if a message contains tool invocations.\n */\nfunction hasToolCalls(msg: SessionMessage): boolean {\n return msg.parts.some(\n (p) => p.type.startsWith(\"tool-\") || p.type === \"dynamic-tool\"\n );\n}\n\n/**\n * Get tool call IDs from a message's parts.\n */\nfunction getToolCallIds(msg: SessionMessage): Set<string> {\n const ids = new Set<string>();\n for (const part of msg.parts) {\n if (\n (part.type.startsWith(\"tool-\") || part.type === \"dynamic-tool\") &&\n \"toolCallId\" in part\n ) {\n ids.add((part as { toolCallId: string }).toolCallId);\n }\n }\n return ids;\n}\n\n/**\n * Check if a message is a tool result referencing a specific call ID.\n */\nfunction isToolResultFor(msg: SessionMessage, callIds: Set<string>): boolean {\n return msg.parts.some(\n (p) =>\n (p.type.startsWith(\"tool-\") || p.type === \"dynamic-tool\") &&\n \"toolCallId\" in p &&\n callIds.has((p as { toolCallId: string }).toolCallId)\n );\n}\n\n/**\n * Align a boundary index forward to avoid splitting tool call/result groups.\n * If the boundary falls between an assistant message with tool calls and its\n * tool results, move it forward past the results.\n */\nexport function alignBoundaryForward(\n messages: SessionMessage[],\n idx: number\n): number {\n if (idx <= 0 || idx >= messages.length) return idx;\n\n // Check if the message before the boundary has tool calls\n const prev = messages[idx - 1];\n if (prev.role === \"assistant\" && hasToolCalls(prev)) {\n const callIds = getToolCallIds(prev);\n // Skip forward past any tool results for these calls\n while (idx < messages.length && isToolResultFor(messages[idx], callIds)) {\n idx++;\n }\n }\n\n return idx;\n}\n\n/**\n * Align a boundary index backward to avoid splitting tool call/result groups.\n * If the boundary falls in the middle of tool results, move it backward to\n * include the assistant message that made the calls.\n */\nexport function alignBoundaryBackward(\n messages: SessionMessage[],\n idx: number\n): number {\n if (idx <= 0 || idx >= messages.length) return idx;\n\n // If the message at idx is a tool result, walk backward to find the call\n while (idx > 0) {\n const msg = messages[idx];\n if (msg.role === \"assistant\" && hasToolCalls(msg)) {\n break; // This is a tool call message — include it\n }\n // Check if this looks like a tool result (assistant message following another)\n const prev = messages[idx - 1];\n if (prev.role === \"assistant\" && hasToolCalls(prev)) {\n const callIds = getToolCallIds(prev);\n if (isToolResultFor(msg, callIds)) {\n idx--; // Move back to include the call\n continue;\n }\n }\n break;\n }\n\n return idx;\n}\n\n// ── Token-Budget Tail Protection ─────────────────────────────────────\n\n/**\n * Find the compression end boundary using a token budget for the tail.\n * Walks backward from the end, accumulating tokens until budget is reached.\n * Returns the index where compression should stop (everything from this\n * index onward is protected).\n *\n * @param messages All messages\n * @param headEnd Index where the protected head ends (compression starts here)\n * @param tailTokenBudget Maximum tokens to keep in the tail\n * @param minTailMessages Minimum messages to protect in the tail (fallback)\n */\nexport function findTailCutByTokens(\n messages: SessionMessage[],\n headEnd: number,\n tailTokenBudget = 20000,\n minTailMessages = 2\n): number {\n const n = messages.length;\n let accumulated = 0;\n let tokenCut = n;\n\n for (let i = n - 1; i >= headEnd; i--) {\n const msgTokens = estimateMessageTokens([messages[i]]);\n\n if (accumulated + msgTokens > tailTokenBudget && tokenCut < n) {\n // Budget exceeded and we already have at least one tail message\n break;\n }\n accumulated += msgTokens;\n tokenCut = i;\n }\n\n // Protect whichever is larger: token-based tail or minTailMessages\n const minCut = n - minTailMessages;\n const cutIdx = minCut >= headEnd ? Math.min(tokenCut, minCut) : tokenCut;\n\n // Align to avoid splitting tool groups\n return alignBoundaryBackward(messages, cutIdx);\n}\n\nasync function findTailCutByTokensWithCounter(\n messages: SessionMessage[],\n headEnd: number,\n tokenCounter: CompactTokenCounter,\n tailTokenBudget = 20000,\n minTailMessages = 2\n): Promise<number> {\n const n = messages.length;\n let accumulated = 0;\n let tokenCut = n;\n\n for (let i = n - 1; i >= headEnd; i--) {\n const msgTokens = await tokenCounter([messages[i]]);\n\n if (accumulated + msgTokens > tailTokenBudget && tokenCut < n) {\n break;\n }\n accumulated += msgTokens;\n tokenCut = i;\n }\n\n const minCut = n - minTailMessages;\n const cutIdx = minCut >= headEnd ? Math.min(tokenCut, minCut) : tokenCut;\n return alignBoundaryBackward(messages, cutIdx);\n}\n\n// ── Tool Pair Sanitization ───────────────────────────────────────────\n\n/**\n * Fix orphaned tool call/result pairs after compaction.\n *\n * Two failure modes:\n * 1. Tool result references a call_id whose assistant tool_call was removed\n * → Remove the orphaned result\n * 2. Assistant has tool_calls whose results were dropped\n * → Add stub results so the API doesn't error\n *\n * @param messages Messages after compaction\n * @returns Sanitized messages with no orphaned pairs\n */\nexport function sanitizeToolPairs(\n messages: SessionMessage[]\n): SessionMessage[] {\n // Build set of surviving tool call IDs (from assistant messages)\n const survivingCallIds = new Set<string>();\n for (const msg of messages) {\n if (msg.role === \"assistant\") {\n for (const id of getToolCallIds(msg)) {\n survivingCallIds.add(id);\n }\n }\n }\n\n // Build set of tool result IDs\n const resultCallIds = new Set<string>();\n for (const msg of messages) {\n for (const part of msg.parts) {\n if (\n (part.type.startsWith(\"tool-\") || part.type === \"dynamic-tool\") &&\n \"toolCallId\" in part &&\n \"output\" in part\n ) {\n resultCallIds.add((part as { toolCallId: string }).toolCallId);\n }\n }\n }\n\n // Remove orphaned results (results whose calls were dropped)\n const orphanedResults = new Set<string>();\n for (const id of resultCallIds) {\n if (!survivingCallIds.has(id)) {\n orphanedResults.add(id);\n }\n }\n\n let result = messages;\n if (orphanedResults.size > 0) {\n result = result.map((msg) => {\n const filteredParts = msg.parts.filter((part) => {\n if (\n (part.type.startsWith(\"tool-\") || part.type === \"dynamic-tool\") &&\n \"toolCallId\" in part &&\n \"output\" in part\n ) {\n return !orphanedResults.has(\n (part as { toolCallId: string }).toolCallId\n );\n }\n return true;\n });\n if (filteredParts.length !== msg.parts.length) {\n return { ...msg, parts: filteredParts } as SessionMessage;\n }\n return msg;\n });\n }\n\n // Add stub results for calls whose results were dropped\n const missingResults = new Set<string>();\n for (const id of survivingCallIds) {\n if (!resultCallIds.has(id) && !orphanedResults.has(id)) {\n missingResults.add(id);\n }\n }\n\n if (missingResults.size > 0) {\n const patched: SessionMessage[] = [];\n for (const msg of result) {\n patched.push(msg);\n if (msg.role === \"assistant\") {\n for (const id of getToolCallIds(msg)) {\n if (missingResults.has(id)) {\n // Find the tool name from the call\n const callPart = msg.parts.find(\n (p) =>\n \"toolCallId\" in p &&\n (p as { toolCallId: string }).toolCallId === id\n ) as { toolName?: string } | undefined;\n\n patched.push({\n id: `stub-${id}`,\n role: \"assistant\",\n parts: [\n {\n type: \"tool-result\" as const,\n toolCallId: id,\n toolName: callPart?.toolName ?? \"unknown\",\n result:\n \"[Result from earlier conversation — see context summary above]\"\n } as unknown as SessionMessage[\"parts\"][number]\n ],\n createdAt: new Date()\n } as SessionMessage);\n }\n }\n }\n }\n result = patched;\n }\n\n // Remove empty messages (all parts filtered out)\n return result.filter((msg) => msg.parts.length > 0);\n}\n\n// ── Summary Budget ───────────────────────────────────────────────────\n\n/**\n * Compute a summary token budget based on the content being compressed.\n * 20% of the compressed content, clamped to 2K-8K tokens.\n */\nexport function computeSummaryBudget(messages: SessionMessage[]): number {\n const contentTokens = estimateMessageTokens(messages);\n // Summary is ~20% of the content being compressed.\n // The summary replaces the compressed middle, so it's sized relative\n // to what it's replacing — not the tail budget (they occupy different\n // slots in the context window).\n const budget = Math.floor(contentTokens * 0.2);\n return Math.max(100, budget);\n}\n\n// ── Structured Summary Prompt ────────────────────────────────────────\n\n/**\n * Build a prompt for LLM summarization of compressed messages.\n *\n * @param messages Messages to summarize\n * @param previousSummary Previous summary for iterative updates (or null for first compaction)\n * @param budget Target token count for the summary\n */\nexport function buildSummaryPrompt(\n messages: SessionMessage[],\n previousSummary: string | null,\n budget: number\n): string {\n const content = messages\n .map((msg) => {\n const textParts = msg.parts\n .filter((p) => p.type === \"text\")\n .map((p) => (p as { text: string }).text)\n .join(\"\\n\");\n\n const toolParts = msg.parts\n .filter((p) => p.type.startsWith(\"tool-\") || p.type === \"dynamic-tool\")\n .map((p) => {\n const tp = p as {\n toolName?: string;\n input?: unknown;\n output?: unknown;\n };\n const parts = [`[Tool: ${tp.toolName ?? \"unknown\"}]`];\n if (tp.input)\n parts.push(`Input: ${JSON.stringify(tp.input).slice(0, 500)}`);\n if (tp.output)\n parts.push(`Output: ${String(tp.output).slice(0, 500)}`);\n return parts.join(\"\\n\");\n })\n .join(\"\\n\");\n\n return `[${msg.role}]\\n${textParts}${toolParts ? \"\\n\" + toolParts : \"\"}`;\n })\n .join(\"\\n\\n---\\n\\n\");\n\n if (previousSummary) {\n return `You are updating a conversation summary. A previous summary exists below. New conversation turns have occurred since then and need to be incorporated.\n\nPREVIOUS SUMMARY:\n${previousSummary}\n\nNEW TURNS TO INCORPORATE:\n${content}\n\nUpdate the summary. PRESERVE existing information that is still relevant. ADD new information. Remove information only if it is clearly obsolete.\n\n## Topic\n[What the conversation is about]\n\n## Key Points\n[Important information, decisions, and conclusions from the conversation]\n\n## Current State\n[Where things stand now — what has been done, what is in progress]\n\n## Open Items\n[Unresolved questions, pending tasks, or next steps discussed]\n\nTarget ~${budget} tokens. Be factual — only include information that was explicitly discussed in the conversation. Do NOT invent file paths, commands, or details that were not mentioned. Write only the summary body.`;\n }\n\n return `Create a concise summary of this conversation that preserves the important information for future context.\n\nCONVERSATION TO SUMMARIZE:\n${content}\n\nUse this structure:\n\n## Topic\n[What the conversation is about]\n\n## Key Points\n[Important information, decisions, and conclusions from the conversation]\n\n## Current State\n[Where things stand now — what has been done, what is in progress]\n\n## Open Items\n[Unresolved questions, pending tasks, or next steps discussed]\n\nTarget ~${budget} tokens. Be factual — only include information that was explicitly discussed in the conversation. Do NOT invent file paths, commands, or details that were not mentioned. Write only the summary body.`;\n}\n\n// ── Reference Compaction Implementation ──────────────────────────────\n\n/**\n * Result of a compaction function — describes the overlay to store.\n */\nexport interface CompactResult {\n /** First message ID in the compacted range */\n fromMessageId: string;\n /** Last message ID in the compacted range */\n toMessageId: string;\n /** Summary text to store as the overlay */\n summary: string;\n}\n\nexport interface CompactOptions {\n /**\n * Function to call the LLM for summarization.\n * Takes a user prompt string, returns the LLM's text response.\n */\n summarize: (prompt: string) => Promise<string>;\n\n /** Number of head messages to protect (default: 2) */\n protectHead?: number;\n\n /** Token budget for tail protection (default: 20000) */\n tailTokenBudget?: number;\n\n /** Minimum tail messages to protect (default: 2) */\n minTailMessages?: number;\n\n /**\n * Optional counter for tail-budget decisions. Use this when a tokenizer or\n * model-reported accounting is available; otherwise the Workers-safe\n * heuristic is used.\n */\n tokenCounter?: CompactTokenCounter;\n}\n\n/**\n * Reference compaction implementation.\n *\n * Implements the full hermes-style compaction algorithm:\n * 1. Protect head messages (first N)\n * 2. Protect tail by token budget (walk backward)\n * 3. Align boundaries to tool call groups\n * 4. Summarize middle section with LLM (structured format)\n * 5. Sanitize orphaned tool pairs\n * 6. Iterative summary updates on subsequent compactions\n *\n * @example\n * ```typescript\n * import { createCompactFunction } from \"agents/experimental/memory/utils\";\n *\n * const session = new Session(provider, {\n * compaction: {\n * tokenThreshold: 100000,\n * fn: createCompactFunction({\n * summarize: (prompt) => generateText({ model, prompt }).then(r => r.text)\n * })\n * }\n * });\n * ```\n */\nexport function createCompactFunction(opts: CompactOptions) {\n const protectHead = opts.protectHead ?? 3;\n const tailTokenBudget = opts.tailTokenBudget ?? 20000;\n const minTailMessages = opts.minTailMessages ?? 2;\n\n return async (\n messages: SessionMessage[],\n context?: CompactContext\n ): Promise<CompactResult | null> => {\n if (messages.length <= protectHead + minTailMessages) {\n return null;\n }\n\n // Prefer an explicit counter; otherwise adapt the Session's counter (flowed\n // via CompactContext) so a single `tokenCounter` on `compactAfter` drives\n // the boundary cut too — without it, a fire counter + the default heuristic\n // under-counting a tool-heavy history makes compaction fire every turn but\n // never shorten anything. The session counter is whole-prompt shaped; for\n // the tail walk we feed it individual messages with empty system/context.\n //\n // Caveat: this counter is invoked once PER MESSAGE. A tokenizer-style\n // counter yields accurate per-message tokens; a counter that returns a\n // fixed whole-prompt total (e.g. `usage.inputTokens`) returns the same\n // value for every message, which degrades `tailTokenBudget` to\n // `minTailMessages` — compaction still runs and context stays bounded, but\n // the byte budget is effectively ignored. It is also called O(n) times per\n // compaction, so an async/remote counter (e.g. a `count_tokens` API) will\n // be slow. For precise tail budgeting with such counters, pass an explicit\n // per-message `CompactOptions.tokenCounter` instead.\n const sessionCounter = context?.tokenCounter;\n const tailCounter: CompactTokenCounter | undefined =\n opts.tokenCounter ??\n (sessionCounter\n ? (msgs) =>\n sessionCounter({\n messages: msgs,\n systemPrompt: \"\",\n contextBlocks: []\n })\n : undefined);\n\n // 1. Find compression boundaries\n let compressStart = protectHead;\n compressStart = alignBoundaryForward(messages, compressStart);\n\n let compressEnd = tailCounter\n ? await findTailCutByTokensWithCounter(\n messages,\n compressStart,\n tailCounter,\n tailTokenBudget,\n minTailMessages\n )\n : findTailCutByTokens(\n messages,\n compressStart,\n tailTokenBudget,\n minTailMessages\n );\n\n if (compressEnd <= compressStart) {\n return null;\n }\n\n // Filter out compaction overlay messages — they have virtual IDs\n // and should not be included in the summary prompt or used as range IDs\n const middleMessages = messages\n .slice(compressStart, compressEnd)\n .filter((m) => !isCompactionMessage(m));\n\n if (middleMessages.length === 0) return null;\n\n // 2. Generate summary — extract previous summary from compaction overlays\n const existingCompaction = messages.find(isCompactionMessage);\n const previousSummary = existingCompaction\n ? existingCompaction.parts\n .filter((p) => p.type === \"text\")\n .map((p) => (p as { text: string }).text)\n .join(\"\\n\")\n : null;\n\n const budget = computeSummaryBudget(middleMessages);\n const prompt = buildSummaryPrompt(middleMessages, previousSummary, budget);\n const summary = await opts.summarize(prompt);\n\n if (!summary.trim()) return null;\n\n return {\n fromMessageId: middleMessages[0].id,\n toMessageId: middleMessages[middleMessages.length - 1].id,\n summary\n };\n };\n}\n"],"mappings":"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"}