@illuma-ai/agents 1.5.1 → 2.1.1

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 (319) hide show
  1. package/README.md +0 -62
  2. package/dist/cjs/agents/AgentContext.cjs +160 -259
  3. package/dist/cjs/agents/AgentContext.cjs.map +1 -1
  4. package/dist/cjs/common/enum.cjs +12 -12
  5. package/dist/cjs/common/enum.cjs.map +1 -1
  6. package/dist/cjs/graphs/Graph.cjs +30 -13
  7. package/dist/cjs/graphs/Graph.cjs.map +1 -1
  8. package/dist/cjs/graphs/MultiAgentGraph.cjs +1 -1
  9. package/dist/cjs/graphs/MultiAgentGraph.cjs.map +1 -1
  10. package/dist/cjs/graphs/phases/memoryFlushPhase.cjs +1 -1
  11. package/dist/cjs/graphs/phases/memoryFlushPhase.cjs.map +1 -1
  12. package/dist/cjs/hooks/HookRegistry.cjs +1 -1
  13. package/dist/cjs/hooks/HookRegistry.cjs.map +1 -1
  14. package/dist/cjs/hooks/matchers.cjs +2 -2
  15. package/dist/cjs/hooks/matchers.cjs.map +1 -1
  16. package/dist/cjs/hooks/types.cjs +1 -1
  17. package/dist/cjs/hooks/types.cjs.map +1 -1
  18. package/dist/cjs/llm/anthropic/utils/message_inputs.cjs +1 -5
  19. package/dist/cjs/llm/anthropic/utils/message_inputs.cjs.map +1 -1
  20. package/dist/cjs/llm/bedrock/index.cjs +33 -61
  21. package/dist/cjs/llm/bedrock/index.cjs.map +1 -1
  22. package/dist/cjs/llm/openai/index.cjs +1 -1
  23. package/dist/cjs/llm/openai/index.cjs.map +1 -1
  24. package/dist/cjs/llm/openai/utils/index.cjs +10 -27
  25. package/dist/cjs/llm/openai/utils/index.cjs.map +1 -1
  26. package/dist/cjs/main.cjs +3 -84
  27. package/dist/cjs/main.cjs.map +1 -1
  28. package/dist/cjs/memory/citations.cjs +4 -4
  29. package/dist/cjs/memory/citations.cjs.map +1 -1
  30. package/dist/cjs/memory/constants.cjs +17 -17
  31. package/dist/cjs/memory/constants.cjs.map +1 -1
  32. package/dist/cjs/memory/mmr.cjs +1 -1
  33. package/dist/cjs/memory/mmr.cjs.map +1 -1
  34. package/dist/cjs/memory/paths.cjs +1 -1
  35. package/dist/cjs/memory/paths.cjs.map +1 -1
  36. package/dist/cjs/memory/recallTracking.cjs +3 -3
  37. package/dist/cjs/memory/recallTracking.cjs.map +1 -1
  38. package/dist/cjs/memory/temporalDecay.cjs +2 -2
  39. package/dist/cjs/memory/temporalDecay.cjs.map +1 -1
  40. package/dist/cjs/messages/cache.cjs +0 -89
  41. package/dist/cjs/messages/cache.cjs.map +1 -1
  42. package/dist/cjs/messages/format.cjs +13 -71
  43. package/dist/cjs/messages/format.cjs.map +1 -1
  44. package/dist/cjs/tools/BashExecutor.cjs +11 -21
  45. package/dist/cjs/tools/BashExecutor.cjs.map +1 -1
  46. package/dist/cjs/tools/CodeExecutor.cjs +13 -41
  47. package/dist/cjs/tools/CodeExecutor.cjs.map +1 -1
  48. package/dist/cjs/tools/ProgrammaticToolCalling.cjs +11 -16
  49. package/dist/cjs/tools/ProgrammaticToolCalling.cjs.map +1 -1
  50. package/dist/cjs/tools/ToolNode.cjs +78 -13
  51. package/dist/cjs/tools/ToolNode.cjs.map +1 -1
  52. package/dist/cjs/tools/memory/memoryAppendTool.cjs +1 -1
  53. package/dist/cjs/tools/memory/memoryAppendTool.cjs.map +1 -1
  54. package/dist/cjs/tools/memory/memoryGetTool.cjs +2 -2
  55. package/dist/cjs/tools/memory/memoryGetTool.cjs.map +1 -1
  56. package/dist/cjs/tools/memory/memorySearchTool.cjs +3 -3
  57. package/dist/cjs/tools/memory/memorySearchTool.cjs.map +1 -1
  58. package/dist/cjs/tools/memory/shared.cjs +1 -1
  59. package/dist/cjs/tools/memory/shared.cjs.map +1 -1
  60. package/dist/cjs/tools/search/search.cjs +3 -11
  61. package/dist/cjs/tools/search/search.cjs.map +1 -1
  62. package/dist/cjs/tools/search/tool.cjs +4 -28
  63. package/dist/cjs/tools/search/tool.cjs.map +1 -1
  64. package/dist/cjs/tools/search/utils.cjs +3 -10
  65. package/dist/cjs/tools/search/utils.cjs.map +1 -1
  66. package/dist/cjs/tools/subagent/SubagentExecutor.cjs +48 -0
  67. package/dist/cjs/tools/subagent/SubagentExecutor.cjs.map +1 -1
  68. package/dist/cjs/types/graph.cjs.map +1 -1
  69. package/dist/esm/agents/AgentContext.mjs +160 -259
  70. package/dist/esm/agents/AgentContext.mjs.map +1 -1
  71. package/dist/esm/common/enum.mjs +12 -12
  72. package/dist/esm/common/enum.mjs.map +1 -1
  73. package/dist/esm/graphs/Graph.mjs +30 -13
  74. package/dist/esm/graphs/Graph.mjs.map +1 -1
  75. package/dist/esm/graphs/MultiAgentGraph.mjs +1 -1
  76. package/dist/esm/graphs/MultiAgentGraph.mjs.map +1 -1
  77. package/dist/esm/graphs/phases/memoryFlushPhase.mjs +1 -1
  78. package/dist/esm/graphs/phases/memoryFlushPhase.mjs.map +1 -1
  79. package/dist/esm/hooks/HookRegistry.mjs +1 -1
  80. package/dist/esm/hooks/HookRegistry.mjs.map +1 -1
  81. package/dist/esm/hooks/matchers.mjs +2 -2
  82. package/dist/esm/hooks/matchers.mjs.map +1 -1
  83. package/dist/esm/hooks/types.mjs +1 -1
  84. package/dist/esm/hooks/types.mjs.map +1 -1
  85. package/dist/esm/llm/anthropic/utils/message_inputs.mjs +1 -5
  86. package/dist/esm/llm/anthropic/utils/message_inputs.mjs.map +1 -1
  87. package/dist/esm/llm/bedrock/index.mjs +34 -61
  88. package/dist/esm/llm/bedrock/index.mjs.map +1 -1
  89. package/dist/esm/llm/openai/index.mjs +1 -1
  90. package/dist/esm/llm/openai/index.mjs.map +1 -1
  91. package/dist/esm/llm/openai/utils/index.mjs +10 -27
  92. package/dist/esm/llm/openai/utils/index.mjs.map +1 -1
  93. package/dist/esm/main.mjs +1 -5
  94. package/dist/esm/main.mjs.map +1 -1
  95. package/dist/esm/memory/citations.mjs +4 -4
  96. package/dist/esm/memory/citations.mjs.map +1 -1
  97. package/dist/esm/memory/constants.mjs +17 -17
  98. package/dist/esm/memory/constants.mjs.map +1 -1
  99. package/dist/esm/memory/mmr.mjs +1 -1
  100. package/dist/esm/memory/mmr.mjs.map +1 -1
  101. package/dist/esm/memory/paths.mjs +1 -1
  102. package/dist/esm/memory/paths.mjs.map +1 -1
  103. package/dist/esm/memory/recallTracking.mjs +3 -3
  104. package/dist/esm/memory/recallTracking.mjs.map +1 -1
  105. package/dist/esm/memory/temporalDecay.mjs +2 -2
  106. package/dist/esm/memory/temporalDecay.mjs.map +1 -1
  107. package/dist/esm/messages/cache.mjs +0 -89
  108. package/dist/esm/messages/cache.mjs.map +1 -1
  109. package/dist/esm/messages/format.mjs +13 -71
  110. package/dist/esm/messages/format.mjs.map +1 -1
  111. package/dist/esm/tools/BashExecutor.mjs +12 -22
  112. package/dist/esm/tools/BashExecutor.mjs.map +1 -1
  113. package/dist/esm/tools/CodeExecutor.mjs +14 -41
  114. package/dist/esm/tools/CodeExecutor.mjs.map +1 -1
  115. package/dist/esm/tools/ProgrammaticToolCalling.mjs +12 -17
  116. package/dist/esm/tools/ProgrammaticToolCalling.mjs.map +1 -1
  117. package/dist/esm/tools/ToolNode.mjs +78 -13
  118. package/dist/esm/tools/ToolNode.mjs.map +1 -1
  119. package/dist/esm/tools/memory/memoryAppendTool.mjs +1 -1
  120. package/dist/esm/tools/memory/memoryAppendTool.mjs.map +1 -1
  121. package/dist/esm/tools/memory/memoryGetTool.mjs +2 -2
  122. package/dist/esm/tools/memory/memoryGetTool.mjs.map +1 -1
  123. package/dist/esm/tools/memory/memorySearchTool.mjs +3 -3
  124. package/dist/esm/tools/memory/memorySearchTool.mjs.map +1 -1
  125. package/dist/esm/tools/memory/shared.mjs +1 -1
  126. package/dist/esm/tools/memory/shared.mjs.map +1 -1
  127. package/dist/esm/tools/search/search.mjs +3 -11
  128. package/dist/esm/tools/search/search.mjs.map +1 -1
  129. package/dist/esm/tools/search/tool.mjs +4 -28
  130. package/dist/esm/tools/search/tool.mjs.map +1 -1
  131. package/dist/esm/tools/search/utils.mjs +3 -10
  132. package/dist/esm/tools/search/utils.mjs.map +1 -1
  133. package/dist/esm/tools/subagent/SubagentExecutor.mjs +48 -0
  134. package/dist/esm/tools/subagent/SubagentExecutor.mjs.map +1 -1
  135. package/dist/esm/types/graph.mjs.map +1 -1
  136. package/dist/types/agents/AgentContext.d.ts +25 -95
  137. package/dist/types/common/enum.d.ts +12 -12
  138. package/dist/types/graphs/Graph.d.ts +2 -2
  139. package/dist/types/graphs/phases/memoryFlushPhase.d.ts +2 -2
  140. package/dist/types/hooks/HookRegistry.d.ts +1 -1
  141. package/dist/types/hooks/matchers.d.ts +2 -2
  142. package/dist/types/hooks/types.d.ts +1 -1
  143. package/dist/types/index.d.ts +0 -1
  144. package/dist/types/llm/bedrock/index.d.ts +1 -54
  145. package/dist/types/llm/openai/index.d.ts +1 -1
  146. package/dist/types/memory/citations.d.ts +4 -4
  147. package/dist/types/memory/constants.d.ts +17 -17
  148. package/dist/types/memory/mmr.d.ts +3 -3
  149. package/dist/types/memory/paths.d.ts +1 -1
  150. package/dist/types/memory/temporalDecay.d.ts +2 -2
  151. package/dist/types/memory/types.d.ts +3 -3
  152. package/dist/types/messages/format.d.ts +2 -5
  153. package/dist/types/tools/CodeExecutor.d.ts +0 -6
  154. package/dist/types/tools/ToolNode.d.ts +3 -3
  155. package/dist/types/tools/memory/shared.d.ts +1 -1
  156. package/dist/types/tools/search/test.d.ts +1 -0
  157. package/dist/types/tools/search/types.d.ts +5 -99
  158. package/dist/types/tools/search/utils.d.ts +2 -2
  159. package/dist/types/tools/subagent/SubagentExecutor.d.ts +29 -0
  160. package/dist/types/types/graph.d.ts +30 -34
  161. package/dist/types/types/index.d.ts +0 -1
  162. package/dist/types/types/messages.d.ts +1 -1
  163. package/dist/types/types/run.d.ts +1 -3
  164. package/dist/types/types/tools.d.ts +5 -14
  165. package/package.json +1 -61
  166. package/src/agents/AgentContext.test.ts +176 -0
  167. package/src/agents/AgentContext.ts +179 -305
  168. package/src/agents/__tests__/AgentContext.test.ts +0 -632
  169. package/src/common/__tests__/enum.test.ts +1 -1
  170. package/src/common/enum.ts +12 -12
  171. package/src/graphs/Graph.ts +32 -13
  172. package/src/graphs/MultiAgentGraph.ts +1 -1
  173. package/src/graphs/gapFeatures.test.ts +1 -1
  174. package/src/graphs/phases/__tests__/memoryFlushPhase.test.ts +1 -1
  175. package/src/graphs/phases/memoryFlushPhase.ts +2 -2
  176. package/src/hooks/HookRegistry.ts +1 -1
  177. package/src/hooks/index.ts +1 -1
  178. package/src/hooks/matchers.ts +2 -2
  179. package/src/hooks/types.ts +1 -1
  180. package/src/index.ts +0 -6
  181. package/src/llm/anthropic/utils/message_inputs.ts +1 -10
  182. package/src/llm/bedrock/__tests__/bedrock-caching.test.ts +18 -166
  183. package/src/llm/bedrock/index.ts +41 -116
  184. package/src/llm/openai/index.ts +2 -2
  185. package/src/llm/openai/utils/index.ts +14 -31
  186. package/src/memory/citations.ts +4 -4
  187. package/src/memory/constants.ts +17 -17
  188. package/src/memory/mmr.ts +3 -3
  189. package/src/memory/paths.ts +1 -1
  190. package/src/memory/recallTracking.ts +3 -3
  191. package/src/memory/temporalDecay.ts +2 -2
  192. package/src/memory/types.ts +3 -3
  193. package/src/messages/cache.test.ts +24 -62
  194. package/src/messages/cache.ts +0 -112
  195. package/src/messages/ensureThinkingBlock.test.ts +1 -1
  196. package/src/messages/format.ts +13 -92
  197. package/src/messages/formatAgentMessages.test.ts +1 -1
  198. package/src/scripts/subagent-configurable-inheritance.ts +263 -0
  199. package/src/scripts/subagent-event-driven-debug.ts +2 -2
  200. package/src/specs/anthropic.simple.test.ts +0 -61
  201. package/src/specs/prune.orphans.test.ts +1 -1
  202. package/src/tools/BashExecutor.ts +13 -37
  203. package/src/tools/CodeExecutor.ts +14 -59
  204. package/src/tools/ProgrammaticToolCalling.ts +14 -29
  205. package/src/tools/ToolNode.ts +75 -14
  206. package/src/tools/__tests__/CodeExecutor.test.ts +3 -3
  207. package/src/tools/__tests__/ProgrammaticToolCalling.test.ts +0 -60
  208. package/src/tools/__tests__/SubagentExecutor.test.ts +157 -0
  209. package/src/tools/memory/memoryAppendTool.ts +1 -1
  210. package/src/tools/memory/memoryGetTool.ts +2 -2
  211. package/src/tools/memory/memorySearchTool.ts +3 -3
  212. package/src/tools/memory/shared.ts +1 -1
  213. package/src/tools/search/output.md +2775 -0
  214. package/src/tools/search/search.ts +2 -12
  215. package/src/tools/search/test.html +884 -0
  216. package/src/tools/search/test.md +643 -0
  217. package/src/tools/search/test.ts +159 -0
  218. package/src/tools/search/tool.ts +2 -36
  219. package/src/tools/search/types.ts +8 -133
  220. package/src/tools/search/utils.ts +5 -13
  221. package/src/tools/subagent/SubagentExecutor.ts +78 -0
  222. package/src/types/graph.ts +27 -34
  223. package/src/types/index.ts +0 -1
  224. package/src/types/messages.ts +1 -1
  225. package/src/types/run.ts +1 -3
  226. package/src/types/tools.ts +5 -14
  227. package/dist/cjs/langchain/google-common.cjs +0 -3
  228. package/dist/cjs/langchain/google-common.cjs.map +0 -1
  229. package/dist/cjs/langchain/index.cjs +0 -86
  230. package/dist/cjs/langchain/index.cjs.map +0 -1
  231. package/dist/cjs/langchain/language_models/chat_models.cjs +0 -3
  232. package/dist/cjs/langchain/language_models/chat_models.cjs.map +0 -1
  233. package/dist/cjs/langchain/messages/tool.cjs +0 -3
  234. package/dist/cjs/langchain/messages/tool.cjs.map +0 -1
  235. package/dist/cjs/langchain/messages.cjs +0 -51
  236. package/dist/cjs/langchain/messages.cjs.map +0 -1
  237. package/dist/cjs/langchain/openai.cjs +0 -3
  238. package/dist/cjs/langchain/openai.cjs.map +0 -1
  239. package/dist/cjs/langchain/prompts.cjs +0 -11
  240. package/dist/cjs/langchain/prompts.cjs.map +0 -1
  241. package/dist/cjs/langchain/runnables.cjs +0 -19
  242. package/dist/cjs/langchain/runnables.cjs.map +0 -1
  243. package/dist/cjs/langchain/tools.cjs +0 -23
  244. package/dist/cjs/langchain/tools.cjs.map +0 -1
  245. package/dist/cjs/langchain/utils/env.cjs +0 -11
  246. package/dist/cjs/langchain/utils/env.cjs.map +0 -1
  247. package/dist/cjs/llm/bedrock/cacheSupport.cjs +0 -55
  248. package/dist/cjs/llm/bedrock/cacheSupport.cjs.map +0 -1
  249. package/dist/cjs/tools/search/tavily-scraper.cjs +0 -189
  250. package/dist/cjs/tools/search/tavily-scraper.cjs.map +0 -1
  251. package/dist/cjs/tools/search/tavily-search.cjs +0 -372
  252. package/dist/cjs/tools/search/tavily-search.cjs.map +0 -1
  253. package/dist/cjs/types/agent-cache.cjs +0 -54
  254. package/dist/cjs/types/agent-cache.cjs.map +0 -1
  255. package/dist/esm/langchain/google-common.mjs +0 -2
  256. package/dist/esm/langchain/google-common.mjs.map +0 -1
  257. package/dist/esm/langchain/index.mjs +0 -5
  258. package/dist/esm/langchain/index.mjs.map +0 -1
  259. package/dist/esm/langchain/language_models/chat_models.mjs +0 -2
  260. package/dist/esm/langchain/language_models/chat_models.mjs.map +0 -1
  261. package/dist/esm/langchain/messages/tool.mjs +0 -2
  262. package/dist/esm/langchain/messages/tool.mjs.map +0 -1
  263. package/dist/esm/langchain/messages.mjs +0 -2
  264. package/dist/esm/langchain/messages.mjs.map +0 -1
  265. package/dist/esm/langchain/openai.mjs +0 -2
  266. package/dist/esm/langchain/openai.mjs.map +0 -1
  267. package/dist/esm/langchain/prompts.mjs +0 -2
  268. package/dist/esm/langchain/prompts.mjs.map +0 -1
  269. package/dist/esm/langchain/runnables.mjs +0 -2
  270. package/dist/esm/langchain/runnables.mjs.map +0 -1
  271. package/dist/esm/langchain/tools.mjs +0 -2
  272. package/dist/esm/langchain/tools.mjs.map +0 -1
  273. package/dist/esm/langchain/utils/env.mjs +0 -2
  274. package/dist/esm/langchain/utils/env.mjs.map +0 -1
  275. package/dist/esm/llm/bedrock/cacheSupport.mjs +0 -52
  276. package/dist/esm/llm/bedrock/cacheSupport.mjs.map +0 -1
  277. package/dist/esm/tools/search/tavily-scraper.mjs +0 -186
  278. package/dist/esm/tools/search/tavily-scraper.mjs.map +0 -1
  279. package/dist/esm/tools/search/tavily-search.mjs +0 -370
  280. package/dist/esm/tools/search/tavily-search.mjs.map +0 -1
  281. package/dist/esm/types/agent-cache.mjs +0 -52
  282. package/dist/esm/types/agent-cache.mjs.map +0 -1
  283. package/dist/types/langchain/google-common.d.ts +0 -1
  284. package/dist/types/langchain/index.d.ts +0 -8
  285. package/dist/types/langchain/language_models/chat_models.d.ts +0 -1
  286. package/dist/types/langchain/messages/tool.d.ts +0 -1
  287. package/dist/types/langchain/messages.d.ts +0 -2
  288. package/dist/types/langchain/openai.d.ts +0 -1
  289. package/dist/types/langchain/prompts.d.ts +0 -1
  290. package/dist/types/langchain/runnables.d.ts +0 -2
  291. package/dist/types/langchain/tools.d.ts +0 -2
  292. package/dist/types/langchain/utils/env.d.ts +0 -1
  293. package/dist/types/llm/bedrock/cacheSupport.d.ts +0 -35
  294. package/dist/types/tools/search/tavily-scraper.d.ts +0 -19
  295. package/dist/types/tools/search/tavily-search.d.ts +0 -4
  296. package/dist/types/tools/subagent/types.d.ts +0 -84
  297. package/dist/types/types/agent-cache.d.ts +0 -71
  298. package/src/agents/__tests__/AgentContext.cacheTtl.live.test.ts +0 -259
  299. package/src/agents/__tests__/AgentContext.crossAgentTier1.live.test.ts +0 -266
  300. package/src/agents/__tests__/AgentContext.crossUserCache.live.test.ts +0 -342
  301. package/src/langchain/google-common.ts +0 -1
  302. package/src/langchain/index.ts +0 -8
  303. package/src/langchain/language_models/chat_models.ts +0 -1
  304. package/src/langchain/messages/tool.ts +0 -5
  305. package/src/langchain/messages.ts +0 -21
  306. package/src/langchain/openai.ts +0 -1
  307. package/src/langchain/prompts.ts +0 -1
  308. package/src/langchain/runnables.ts +0 -7
  309. package/src/langchain/tools.ts +0 -8
  310. package/src/langchain/utils/env.ts +0 -1
  311. package/src/llm/anthropic/utils/server-tool-inputs.test.ts +0 -436
  312. package/src/llm/bedrock/cacheSupport.test.ts +0 -99
  313. package/src/llm/bedrock/cacheSupport.ts +0 -53
  314. package/src/tools/search/tavily-scraper.ts +0 -235
  315. package/src/tools/search/tavily-search.ts +0 -424
  316. package/src/tools/search/tavily.test.ts +0 -965
  317. package/src/tools/subagent/types.test.ts +0 -70
  318. package/src/tools/subagent/types.ts +0 -115
  319. package/src/types/agent-cache.ts +0 -74
@@ -36,7 +36,6 @@ import type {
36
36
  ReasoningDeltaEvent,
37
37
  } from '@/types/stream';
38
38
  import type { TokenCounter } from '@/types/run';
39
- import type { SystemCacheBlock, AgentCacheTTL } from '@/types/agent-cache';
40
39
 
41
40
  /** Interface for bound model with stream and invoke methods */
42
41
  export interface ChatModel {
@@ -389,11 +388,10 @@ export type GraphEdge = {
389
388
  /**
390
389
  * EdgeType.HANDOFF — one-way routing: parent emits an `lc_transfer_to_*`
391
390
  * tool call and exits, child takes over and responds directly to the
392
- * user. Aligns with the standard handoff semantics.
391
+ * user. Aligns with upstream's handoff semantics.
393
392
  * EdgeType.DIRECT — fixed graph edges for automatic sequential / parallel
394
- * transitions. Downstream consumers may layer additional wiring on top
395
- * (fan-in with prompt, parallel groups, approval-gate nodes,
396
- * excludeResults / agentMessages).
393
+ * transitions. Ranger preserves its enriched wiring (fan-in with prompt,
394
+ * parallel groups, ApprovalGateNode, excludeResults / agentMessages).
397
395
  */
398
396
  edgeType?: import('@/common').EdgeType;
399
397
  /**
@@ -618,7 +616,7 @@ export interface SummarizationConfig {
618
616
  initialSummary?: string;
619
617
 
620
618
  /**
621
- * optional fields. When the host wants the summarization
619
+ * Upstream-aligned optional fields. When the host wants the summarization
622
620
  * pass to run on a different LLM than the agent's own (e.g. a cheaper
623
621
  * model for compaction), these provider/model overrides flow through to
624
622
  * the summarize callback.
@@ -740,36 +738,10 @@ export interface AgentInputs {
740
738
  toolMap?: ToolMap;
741
739
  tools?: GraphTools;
742
740
  provider: Providers;
743
- /**
744
- * Ordered list of cacheable system content blocks emitted BEFORE
745
- * `instructions` in the system message. Each block gets its own cache
746
- * marker (cachePoint on Bedrock, cache_control on Anthropic) so the
747
- * cache key for each block includes only the bytes up to and including
748
- * its own marker. Entries are emitted in array order — earlier =
749
- * stabler = wider cache key (best for cross-tenant sharing).
750
- *
751
- * See `src/types/agent-cache.ts` for full semantics. Capped at
752
- * `MAX_SYSTEM_CACHE_BLOCKS` (2) entries to stay within Bedrock's
753
- * 4-cachePoint budget after the tools array consumes 2.
754
- */
755
- system_cache_blocks?: SystemCacheBlock[];
756
- /**
757
- * Stable/cacheable system instructions for this agent. Always emitted
758
- * with its own trailing cache marker (when caching is supported by
759
- * the provider/model). Use `instructions_cache_ttl` to override the
760
- * default '5m' TTL.
761
- */
762
741
  instructions?: string;
763
- /** TTL for the trailing `instructions` cache marker. Defaults to '5m'. */
764
- instructions_cache_ttl?: AgentCacheTTL;
765
742
  streamBuffer?: number;
766
743
  maxContextTokens?: number;
767
744
  clientOptions?: ClientOptions;
768
- /**
769
- * Dynamic system tail appended after the cacheable instructions
770
- * without any cache marker. Per-user / per-message context belongs
771
- * here so it does not invalidate the cacheable prefix.
772
- */
773
745
  additional_instructions?: string;
774
746
  reasoningKey?: 'reasoning_content' | 'reasoning';
775
747
  /**
@@ -791,9 +763,9 @@ export interface AgentInputs {
791
763
  */
792
764
  initialSummary?: { text: string; tokenCount: number };
793
765
  /**
794
- * opt-in for summarization. When false, the agent never
766
+ * Upstream-aligned opt-in for summarization. When false, the agent never
795
767
  * invokes the summarize callback regardless of context utilization.
796
- * Defaults to undefined (treated as enabled by default to preserve prior
768
+ * Defaults to undefined (treated as enabled in Ranger to preserve prior
797
769
  * behaviour); hosts that want strict opt-in semantics should set it
798
770
  * explicitly.
799
771
  */
@@ -859,6 +831,27 @@ export interface AgentInputs {
859
831
  * @see SummarizationConfig
860
832
  */
861
833
  summarizationConfig?: SummarizationConfig;
834
+ /**
835
+ * Workspace-shared system-message tiers. Each entry becomes a separate
836
+ * text block in the SystemMessage with its own cachePoint / cache_control
837
+ * marker, allowing the platform-tier bytes (e.g. shared branding, tool
838
+ * routing rules, code-executor instructions) to be hashed independently
839
+ * from the per-agent `instructions` block. Hosts that don't use tiered
840
+ * caching can leave this undefined; behavior falls back to the legacy
841
+ * single SystemMessage.
842
+ *
843
+ * Anthropic / Bedrock prompt-cache lookups are forward-prefix-hash, so
844
+ * blocks are emitted in array order BEFORE `instructions`. Up to 4 blocks
845
+ * are supported (the LLM cap on cache breakpoints).
846
+ */
847
+ system_cache_blocks?: Array<{ text: string; ttl?: '5m' | '1h' }>;
848
+ /**
849
+ * TTL hint for the per-agent `instructions` block's cache marker.
850
+ * Defaults to '5m' (matching addCacheControl message-level behavior).
851
+ * Only consulted when `system_cache_blocks` is set; otherwise the
852
+ * legacy SystemMessage path is unchanged.
853
+ */
854
+ instructions_cache_ttl?: '5m' | '1h';
862
855
  /**
863
856
  * Lightweight file manifest for the conversation.
864
857
  * Contains file IDs, names, and metadata — NOT full content.
@@ -1,5 +1,4 @@
1
1
  // src/types/index.ts
2
- export * from './agent-cache';
3
2
  export * from './graph';
4
3
  export * from './llm';
5
4
  export * from './messages';
@@ -5,7 +5,7 @@ export type AnthropicMessage = Anthropic.MessageParam;
5
5
 
6
6
  /**
7
7
  * Per-message ref metadata stamped onto a `ToolMessage` at execution time
8
- * (PR #117). Read by `annotateMessagesForLLM` to apply transient
8
+ * (upstream PR #117). Read by `annotateMessagesForLLM` to apply transient
9
9
  * annotation to a copy of the message right before it goes on the wire to
10
10
  * the provider. Never read after the run-scoped registry has been cleared.
11
11
  *
package/src/types/run.ts CHANGED
@@ -74,9 +74,7 @@ export interface AgentStateChannels {
74
74
  messages: BaseMessage[];
75
75
  next: string;
76
76
  [key: string]: unknown;
77
- /** Stable/cacheable system instructions for this agent. */
78
77
  instructions?: string;
79
- /** Dynamic system tail appended after stable instructions. */
80
78
  additional_instructions?: string;
81
79
  }
82
80
 
@@ -133,7 +131,7 @@ export type RunConfig = {
133
131
  */
134
132
  hooks?: HookRegistry;
135
133
  /**
136
- * Tool output reference configuration (PRs #114 / #117).
134
+ * Tool output reference configuration (upstream PRs #114 / #117).
137
135
  * When `enabled` is true, the Run constructs a single
138
136
  * ToolOutputReferenceRegistry and threads it to every ToolNode built by
139
137
  * the graph so `{{tool<i>turn<n>}}` placeholders resolve across agents.
@@ -70,13 +70,13 @@ export type ToolNodeOptions = {
70
70
  /**
71
71
  * Maximum characters for a single tool result (head+tail truncation).
72
72
  * When omitted, derived from the agent's `maxContextTokens` (30%
73
- * heuristic), capped at HARD_MAX_TOOL_RESULT_CHARS. —
74
- * downstream consumers may drive truncation through other knobs;
75
- * accepting this option keeps the test surface portable.
73
+ * heuristic), capped at HARD_MAX_TOOL_RESULT_CHARS. Upstream-aligned
74
+ * Ranger's truncation today is driven by other knobs, but accepting
75
+ * this option keeps the test surface portable.
76
76
  */
77
77
  maxToolResultChars?: number;
78
78
  /**
79
- * Run-scoped tool output reference configuration (PR #114).
79
+ * Run-scoped tool output reference configuration (upstream PR #114).
80
80
  * When `enabled` is true, ToolNode registers successful outputs and
81
81
  * substitutes `{{tool<i>turn<n>}}` placeholders found in string args.
82
82
  * Ignored when `toolOutputRegistry` is also provided (the host-supplied
@@ -144,15 +144,6 @@ export type FileRef = {
144
144
  path?: string;
145
145
  /** Session ID this file belongs to (for multi-session file tracking) */
146
146
  session_id?: string;
147
- /**
148
- * `true` when the codeapi sandbox echoed this entry as an unchanged
149
- * passthrough of an input the caller already owns (skill files,
150
- * downloaded inputs whose hash matched the baseline, inherited
151
- * `.dirkeep` markers). The tool-result formatter renders these as
152
- * "Available files" rather than "Generated files" so the LLM doesn't
153
- * conflate infrastructure inputs with newly-produced outputs.
154
- */
155
- inherited?: true;
156
147
  };
157
148
 
158
149
  export type FileRefs = FileRef[];
@@ -294,7 +285,7 @@ export type ToolExecuteResult = {
294
285
  export type LCToolRegistry = Map<string, LCTool>;
295
286
 
296
287
  /**
297
- * Configuration for the tool output reference feature (PR #114).
288
+ * Configuration for the tool output reference feature (upstream PR #114).
298
289
  *
299
290
  * When `enabled: true`, ToolNode stores each successful tool output under
300
291
  * a stable key `tool<idx>turn<turn>` and the LLM can pipe a previous output
@@ -1,3 +0,0 @@
1
- 'use strict';
2
-
3
- //# sourceMappingURL=google-common.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"google-common.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
@@ -1,86 +0,0 @@
1
- 'use strict';
2
-
3
- var messages = require('@langchain/core/messages');
4
- var prompts = require('@langchain/core/prompts');
5
- var runnables = require('@langchain/core/runnables');
6
- var tools = require('@langchain/core/tools');
7
-
8
-
9
-
10
- Object.defineProperty(exports, "AIMessage", {
11
- enumerable: true,
12
- get: function () { return messages.AIMessage; }
13
- });
14
- Object.defineProperty(exports, "AIMessageChunk", {
15
- enumerable: true,
16
- get: function () { return messages.AIMessageChunk; }
17
- });
18
- Object.defineProperty(exports, "BaseMessage", {
19
- enumerable: true,
20
- get: function () { return messages.BaseMessage; }
21
- });
22
- Object.defineProperty(exports, "BaseMessageChunk", {
23
- enumerable: true,
24
- get: function () { return messages.BaseMessageChunk; }
25
- });
26
- Object.defineProperty(exports, "HumanMessage", {
27
- enumerable: true,
28
- get: function () { return messages.HumanMessage; }
29
- });
30
- Object.defineProperty(exports, "SystemMessage", {
31
- enumerable: true,
32
- get: function () { return messages.SystemMessage; }
33
- });
34
- Object.defineProperty(exports, "ToolMessage", {
35
- enumerable: true,
36
- get: function () { return messages.ToolMessage; }
37
- });
38
- Object.defineProperty(exports, "getBufferString", {
39
- enumerable: true,
40
- get: function () { return messages.getBufferString; }
41
- });
42
- Object.defineProperty(exports, "isAIMessage", {
43
- enumerable: true,
44
- get: function () { return messages.isAIMessage; }
45
- });
46
- Object.defineProperty(exports, "isBaseMessage", {
47
- enumerable: true,
48
- get: function () { return messages.isBaseMessage; }
49
- });
50
- Object.defineProperty(exports, "isToolMessage", {
51
- enumerable: true,
52
- get: function () { return messages.isToolMessage; }
53
- });
54
- Object.defineProperty(exports, "PromptTemplate", {
55
- enumerable: true,
56
- get: function () { return prompts.PromptTemplate; }
57
- });
58
- Object.defineProperty(exports, "Runnable", {
59
- enumerable: true,
60
- get: function () { return runnables.Runnable; }
61
- });
62
- Object.defineProperty(exports, "RunnableLambda", {
63
- enumerable: true,
64
- get: function () { return runnables.RunnableLambda; }
65
- });
66
- Object.defineProperty(exports, "RunnableSequence", {
67
- enumerable: true,
68
- get: function () { return runnables.RunnableSequence; }
69
- });
70
- Object.defineProperty(exports, "DynamicStructuredTool", {
71
- enumerable: true,
72
- get: function () { return tools.DynamicStructuredTool; }
73
- });
74
- Object.defineProperty(exports, "StructuredTool", {
75
- enumerable: true,
76
- get: function () { return tools.StructuredTool; }
77
- });
78
- Object.defineProperty(exports, "Tool", {
79
- enumerable: true,
80
- get: function () { return tools.Tool; }
81
- });
82
- Object.defineProperty(exports, "tool", {
83
- enumerable: true,
84
- get: function () { return tools.tool; }
85
- });
86
- //# sourceMappingURL=index.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
@@ -1,3 +0,0 @@
1
- 'use strict';
2
-
3
- //# sourceMappingURL=chat_models.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"chat_models.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
@@ -1,3 +0,0 @@
1
- 'use strict';
2
-
3
- //# sourceMappingURL=tool.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"tool.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
@@ -1,51 +0,0 @@
1
- 'use strict';
2
-
3
- var messages = require('@langchain/core/messages');
4
-
5
-
6
-
7
- Object.defineProperty(exports, "AIMessage", {
8
- enumerable: true,
9
- get: function () { return messages.AIMessage; }
10
- });
11
- Object.defineProperty(exports, "AIMessageChunk", {
12
- enumerable: true,
13
- get: function () { return messages.AIMessageChunk; }
14
- });
15
- Object.defineProperty(exports, "BaseMessage", {
16
- enumerable: true,
17
- get: function () { return messages.BaseMessage; }
18
- });
19
- Object.defineProperty(exports, "BaseMessageChunk", {
20
- enumerable: true,
21
- get: function () { return messages.BaseMessageChunk; }
22
- });
23
- Object.defineProperty(exports, "HumanMessage", {
24
- enumerable: true,
25
- get: function () { return messages.HumanMessage; }
26
- });
27
- Object.defineProperty(exports, "SystemMessage", {
28
- enumerable: true,
29
- get: function () { return messages.SystemMessage; }
30
- });
31
- Object.defineProperty(exports, "ToolMessage", {
32
- enumerable: true,
33
- get: function () { return messages.ToolMessage; }
34
- });
35
- Object.defineProperty(exports, "getBufferString", {
36
- enumerable: true,
37
- get: function () { return messages.getBufferString; }
38
- });
39
- Object.defineProperty(exports, "isAIMessage", {
40
- enumerable: true,
41
- get: function () { return messages.isAIMessage; }
42
- });
43
- Object.defineProperty(exports, "isBaseMessage", {
44
- enumerable: true,
45
- get: function () { return messages.isBaseMessage; }
46
- });
47
- Object.defineProperty(exports, "isToolMessage", {
48
- enumerable: true,
49
- get: function () { return messages.isToolMessage; }
50
- });
51
- //# sourceMappingURL=messages.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"messages.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
@@ -1,3 +0,0 @@
1
- 'use strict';
2
-
3
- //# sourceMappingURL=openai.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"openai.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}
@@ -1,11 +0,0 @@
1
- 'use strict';
2
-
3
- var prompts = require('@langchain/core/prompts');
4
-
5
-
6
-
7
- Object.defineProperty(exports, "PromptTemplate", {
8
- enumerable: true,
9
- get: function () { return prompts.PromptTemplate; }
10
- });
11
- //# sourceMappingURL=prompts.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"prompts.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}
@@ -1,19 +0,0 @@
1
- 'use strict';
2
-
3
- var runnables = require('@langchain/core/runnables');
4
-
5
-
6
-
7
- Object.defineProperty(exports, "Runnable", {
8
- enumerable: true,
9
- get: function () { return runnables.Runnable; }
10
- });
11
- Object.defineProperty(exports, "RunnableLambda", {
12
- enumerable: true,
13
- get: function () { return runnables.RunnableLambda; }
14
- });
15
- Object.defineProperty(exports, "RunnableSequence", {
16
- enumerable: true,
17
- get: function () { return runnables.RunnableSequence; }
18
- });
19
- //# sourceMappingURL=runnables.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"runnables.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;"}
@@ -1,23 +0,0 @@
1
- 'use strict';
2
-
3
- var tools = require('@langchain/core/tools');
4
-
5
-
6
-
7
- Object.defineProperty(exports, "DynamicStructuredTool", {
8
- enumerable: true,
9
- get: function () { return tools.DynamicStructuredTool; }
10
- });
11
- Object.defineProperty(exports, "StructuredTool", {
12
- enumerable: true,
13
- get: function () { return tools.StructuredTool; }
14
- });
15
- Object.defineProperty(exports, "Tool", {
16
- enumerable: true,
17
- get: function () { return tools.Tool; }
18
- });
19
- Object.defineProperty(exports, "tool", {
20
- enumerable: true,
21
- get: function () { return tools.tool; }
22
- });
23
- //# sourceMappingURL=tools.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"tools.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;"}
@@ -1,11 +0,0 @@
1
- 'use strict';
2
-
3
- var env = require('@langchain/core/utils/env');
4
-
5
-
6
-
7
- Object.defineProperty(exports, "getEnvironmentVariable", {
8
- enumerable: true,
9
- get: function () { return env.getEnvironmentVariable; }
10
- });
11
- //# sourceMappingURL=env.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"env.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}
@@ -1,55 +0,0 @@
1
- 'use strict';
2
-
3
- /**
4
- * Bedrock prompt-cache model support detection.
5
- * ===============================================
6
- *
7
- * Bedrock prompt caching (via `cachePoint` blocks) is only supported on
8
- * specific model families. Other families silently reject or ignore the
9
- * markers. We maintain an allowlist instead of a substring heuristic so
10
- * a future model with an unfortunate name (e.g. `llama-claude-killer`)
11
- * doesn't accidentally match.
12
- *
13
- * Consumers can extend the allowlist with `bedrockCacheModelPatterns` in
14
- * `clientOptions` for proprietary or pre-release model IDs not yet in
15
- * the reference library.
16
- */
17
- /**
18
- * Default allowlist of Bedrock model ID patterns that support cachePoint.
19
- * Sourced from AWS Bedrock documentation (verified against us-east-1
20
- * 2026-05).
21
- *
22
- * Adding a new model: append a RegExp here AND add a regression test in
23
- * `cacheSupport.test.ts` covering at least one full model ID for that
24
- * family. Removing a model: do not remove without operator confirmation
25
- * — silent removal would suddenly stop emitting cachePoint markers and
26
- * regress cost savings.
27
- */
28
- const DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS = [
29
- // Anthropic Claude family (anthropic.claude-* and us.anthropic.claude-*)
30
- /(?:^|[/.])anthropic\.claude-/i,
31
- /(?:^|\.)us\.anthropic\.claude-/i,
32
- // Amazon Nova family (nova-pro, nova-lite, nova-canvas, etc.)
33
- /(?:^|[/.])amazon\.nova-/i,
34
- /(?:^|\.)us\.amazon\.nova-/i,
35
- ];
36
- /**
37
- * Returns true when the given Bedrock model ID belongs to a family that
38
- * supports cachePoint blocks. `additionalPatterns` lets consumers extend
39
- * the allowlist for models the library doesn't know about yet.
40
- *
41
- * @param modelId Bedrock model ID (e.g. `us.anthropic.claude-sonnet-4-5-20250929-v1:0`)
42
- * @param additionalPatterns Extra patterns from consumer config
43
- */
44
- function isBedrockCacheSupported(modelId, additionalPatterns) {
45
- if (!modelId)
46
- return false;
47
- const allPatterns = additionalPatterns
48
- ? [...DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS, ...additionalPatterns]
49
- : DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS;
50
- return allPatterns.some((p) => p.test(modelId));
51
- }
52
-
53
- exports.DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS = DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS;
54
- exports.isBedrockCacheSupported = isBedrockCacheSupported;
55
- //# sourceMappingURL=cacheSupport.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"cacheSupport.cjs","sources":["../../../../src/llm/bedrock/cacheSupport.ts"],"sourcesContent":["/**\n * Bedrock prompt-cache model support detection.\n * ===============================================\n *\n * Bedrock prompt caching (via `cachePoint` blocks) is only supported on\n * specific model families. Other families silently reject or ignore the\n * markers. We maintain an allowlist instead of a substring heuristic so\n * a future model with an unfortunate name (e.g. `llama-claude-killer`)\n * doesn't accidentally match.\n *\n * Consumers can extend the allowlist with `bedrockCacheModelPatterns` in\n * `clientOptions` for proprietary or pre-release model IDs not yet in\n * the reference library.\n */\n\n/**\n * Default allowlist of Bedrock model ID patterns that support cachePoint.\n * Sourced from AWS Bedrock documentation (verified against us-east-1\n * 2026-05).\n *\n * Adding a new model: append a RegExp here AND add a regression test in\n * `cacheSupport.test.ts` covering at least one full model ID for that\n * family. Removing a model: do not remove without operator confirmation\n * — silent removal would suddenly stop emitting cachePoint markers and\n * regress cost savings.\n */\nexport const DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS: readonly RegExp[] = [\n // Anthropic Claude family (anthropic.claude-* and us.anthropic.claude-*)\n /(?:^|[/.])anthropic\\.claude-/i,\n /(?:^|\\.)us\\.anthropic\\.claude-/i,\n // Amazon Nova family (nova-pro, nova-lite, nova-canvas, etc.)\n /(?:^|[/.])amazon\\.nova-/i,\n /(?:^|\\.)us\\.amazon\\.nova-/i,\n];\n\n/**\n * Returns true when the given Bedrock model ID belongs to a family that\n * supports cachePoint blocks. `additionalPatterns` lets consumers extend\n * the allowlist for models the library doesn't know about yet.\n *\n * @param modelId Bedrock model ID (e.g. `us.anthropic.claude-sonnet-4-5-20250929-v1:0`)\n * @param additionalPatterns Extra patterns from consumer config\n */\nexport function isBedrockCacheSupported(\n modelId: string | undefined,\n additionalPatterns?: readonly RegExp[],\n): boolean {\n if (!modelId) return false;\n const allPatterns = additionalPatterns\n ? [...DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS, ...additionalPatterns]\n : DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS;\n return allPatterns.some((p) => p.test(modelId));\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;AAaG;AAEH;;;;;;;;;;AAUG;AACI,MAAM,oCAAoC,GAAsB;;IAErE,+BAA+B;IAC/B,iCAAiC;;IAEjC,0BAA0B;IAC1B,4BAA4B;;AAG9B;;;;;;;AAOG;AACG,SAAU,uBAAuB,CACrC,OAA2B,EAC3B,kBAAsC,EAAA;AAEtC,IAAA,IAAI,CAAC,OAAO;AAAE,QAAA,OAAO,KAAK;IAC1B,MAAM,WAAW,GAAG;AAClB,UAAE,CAAC,GAAG,oCAAoC,EAAE,GAAG,kBAAkB;UAC/D,oCAAoC;AACxC,IAAA,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACjD;;;;;"}