strands-darwin 0.0.3

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 (417) hide show
  1. package/README.md +140 -0
  2. package/README.zh-CN.md +140 -0
  3. package/dist/patches/@strands-agents+sdk+1.16.0.patch +1443 -0
  4. package/dist/src/agent/background-delegation.d.ts +67 -0
  5. package/dist/src/agent/background-delegation.js +159 -0
  6. package/dist/src/agent/background-delegation.js.map +1 -0
  7. package/dist/src/agent/call-stats.d.ts +118 -0
  8. package/dist/src/agent/call-stats.js +128 -0
  9. package/dist/src/agent/call-stats.js.map +1 -0
  10. package/dist/src/agent/compact.d.ts +108 -0
  11. package/dist/src/agent/compact.js +192 -0
  12. package/dist/src/agent/compact.js.map +1 -0
  13. package/dist/src/agent/context-anchor.d.ts +64 -0
  14. package/dist/src/agent/context-anchor.js +43 -0
  15. package/dist/src/agent/context-anchor.js.map +1 -0
  16. package/dist/src/agent/cost.d.ts +56 -0
  17. package/dist/src/agent/cost.js +44 -0
  18. package/dist/src/agent/cost.js.map +1 -0
  19. package/dist/src/agent/diagnostics.d.ts +212 -0
  20. package/dist/src/agent/diagnostics.js +374 -0
  21. package/dist/src/agent/diagnostics.js.map +1 -0
  22. package/dist/src/agent/instructions.d.ts +54 -0
  23. package/dist/src/agent/instructions.js +118 -0
  24. package/dist/src/agent/instructions.js.map +1 -0
  25. package/dist/src/agent/max-tokens-recovery.d.ts +17 -0
  26. package/dist/src/agent/max-tokens-recovery.js +65 -0
  27. package/dist/src/agent/max-tokens-recovery.js.map +1 -0
  28. package/dist/src/agent/model-call-budget.d.ts +8 -0
  29. package/dist/src/agent/model-call-budget.js +24 -0
  30. package/dist/src/agent/model-call-budget.js.map +1 -0
  31. package/dist/src/agent/model-retry.d.ts +134 -0
  32. package/dist/src/agent/model-retry.js +256 -0
  33. package/dist/src/agent/model-retry.js.map +1 -0
  34. package/dist/src/agent/permission-rules.d.ts +47 -0
  35. package/dist/src/agent/permission-rules.js +260 -0
  36. package/dist/src/agent/permission-rules.js.map +1 -0
  37. package/dist/src/agent/permission.d.ts +361 -0
  38. package/dist/src/agent/permission.js +797 -0
  39. package/dist/src/agent/permission.js.map +1 -0
  40. package/dist/src/agent/prompt-cache.d.ts +66 -0
  41. package/dist/src/agent/prompt-cache.js +194 -0
  42. package/dist/src/agent/prompt-cache.js.map +1 -0
  43. package/dist/src/agent/refusal.d.ts +20 -0
  44. package/dist/src/agent/refusal.js +23 -0
  45. package/dist/src/agent/refusal.js.map +1 -0
  46. package/dist/src/agent/retry-guard.d.ts +26 -0
  47. package/dist/src/agent/retry-guard.js +193 -0
  48. package/dist/src/agent/retry-guard.js.map +1 -0
  49. package/dist/src/agent/rewind.d.ts +29 -0
  50. package/dist/src/agent/rewind.js +118 -0
  51. package/dist/src/agent/rewind.js.map +1 -0
  52. package/dist/src/agent/runtime.d.ts +814 -0
  53. package/dist/src/agent/runtime.js +1596 -0
  54. package/dist/src/agent/runtime.js.map +1 -0
  55. package/dist/src/agent/safety-classifier.d.ts +11 -0
  56. package/dist/src/agent/safety-classifier.js +0 -0
  57. package/dist/src/agent/safety-classifier.js.map +1 -0
  58. package/dist/src/agent/sdk-logging.d.ts +49 -0
  59. package/dist/src/agent/sdk-logging.js +110 -0
  60. package/dist/src/agent/sdk-logging.js.map +1 -0
  61. package/dist/src/agent/session.d.ts +102 -0
  62. package/dist/src/agent/session.js +244 -0
  63. package/dist/src/agent/session.js.map +1 -0
  64. package/dist/src/agent/stream-resumption.d.ts +16 -0
  65. package/dist/src/agent/stream-resumption.js +33 -0
  66. package/dist/src/agent/stream-resumption.js.map +1 -0
  67. package/dist/src/agent/system-prompt.d.ts +50 -0
  68. package/dist/src/agent/system-prompt.js +161 -0
  69. package/dist/src/agent/system-prompt.js.map +1 -0
  70. package/dist/src/agent/thinking.d.ts +99 -0
  71. package/dist/src/agent/thinking.js +145 -0
  72. package/dist/src/agent/thinking.js.map +1 -0
  73. package/dist/src/agent/usage.d.ts +132 -0
  74. package/dist/src/agent/usage.js +233 -0
  75. package/dist/src/agent/usage.js.map +1 -0
  76. package/dist/src/agent/working-context.d.ts +51 -0
  77. package/dist/src/agent/working-context.js +160 -0
  78. package/dist/src/agent/working-context.js.map +1 -0
  79. package/dist/src/agents/child-recipe.d.ts +33 -0
  80. package/dist/src/agents/child-recipe.js +98 -0
  81. package/dist/src/agents/child-recipe.js.map +1 -0
  82. package/dist/src/agents/concurrency-limit.d.ts +25 -0
  83. package/dist/src/agents/concurrency-limit.js +43 -0
  84. package/dist/src/agents/concurrency-limit.js.map +1 -0
  85. package/dist/src/agents/dispatch-registry.d.ts +180 -0
  86. package/dist/src/agents/dispatch-registry.js +289 -0
  87. package/dist/src/agents/dispatch-registry.js.map +1 -0
  88. package/dist/src/agents/failed-child-text.d.ts +44 -0
  89. package/dist/src/agents/failed-child-text.js +69 -0
  90. package/dist/src/agents/failed-child-text.js.map +1 -0
  91. package/dist/src/agents/loader.d.ts +26 -0
  92. package/dist/src/agents/loader.js +134 -0
  93. package/dist/src/agents/loader.js.map +1 -0
  94. package/dist/src/agents/report-projection.d.ts +31 -0
  95. package/dist/src/agents/report-projection.js +125 -0
  96. package/dist/src/agents/report-projection.js.map +1 -0
  97. package/dist/src/agents/subagent-tool.d.ts +61 -0
  98. package/dist/src/agents/subagent-tool.js +180 -0
  99. package/dist/src/agents/subagent-tool.js.map +1 -0
  100. package/dist/src/agents/workflow-tool.d.ts +85 -0
  101. package/dist/src/agents/workflow-tool.js +530 -0
  102. package/dist/src/agents/workflow-tool.js.map +1 -0
  103. package/dist/src/cli-args.d.ts +39 -0
  104. package/dist/src/cli-args.js +198 -0
  105. package/dist/src/cli-args.js.map +1 -0
  106. package/dist/src/cli-doctor.d.ts +26 -0
  107. package/dist/src/cli-doctor.js +398 -0
  108. package/dist/src/cli-doctor.js.map +1 -0
  109. package/dist/src/cli-main.d.ts +1 -0
  110. package/dist/src/cli-main.js +279 -0
  111. package/dist/src/cli-main.js.map +1 -0
  112. package/dist/src/cli-sessions.d.ts +17 -0
  113. package/dist/src/cli-sessions.js +136 -0
  114. package/dist/src/cli-sessions.js.map +1 -0
  115. package/dist/src/cli-trajectory.d.ts +37 -0
  116. package/dist/src/cli-trajectory.js +303 -0
  117. package/dist/src/cli-trajectory.js.map +1 -0
  118. package/dist/src/cli-usage.d.ts +18 -0
  119. package/dist/src/cli-usage.js +53 -0
  120. package/dist/src/cli-usage.js.map +1 -0
  121. package/dist/src/cli.d.ts +2 -0
  122. package/dist/src/cli.js +29 -0
  123. package/dist/src/cli.js.map +1 -0
  124. package/dist/src/commands/custom-commands.d.ts +43 -0
  125. package/dist/src/commands/custom-commands.js +155 -0
  126. package/dist/src/commands/custom-commands.js.map +1 -0
  127. package/dist/src/commands/workflow-command.d.ts +26 -0
  128. package/dist/src/commands/workflow-command.js +56 -0
  129. package/dist/src/commands/workflow-command.js.map +1 -0
  130. package/dist/src/config.d.ts +463 -0
  131. package/dist/src/config.js +1457 -0
  132. package/dist/src/config.js.map +1 -0
  133. package/dist/src/context-overflow-error.d.ts +7 -0
  134. package/dist/src/context-overflow-error.js +26 -0
  135. package/dist/src/context-overflow-error.js.map +1 -0
  136. package/dist/src/dev-repl.d.ts +1 -0
  137. package/dist/src/dev-repl.js +365 -0
  138. package/dist/src/dev-repl.js.map +1 -0
  139. package/dist/src/headless-protocol.d.ts +147 -0
  140. package/dist/src/headless-protocol.js +359 -0
  141. package/dist/src/headless-protocol.js.map +1 -0
  142. package/dist/src/headless-runner.d.ts +30 -0
  143. package/dist/src/headless-runner.js +405 -0
  144. package/dist/src/headless-runner.js.map +1 -0
  145. package/dist/src/headless-stdin.d.ts +28 -0
  146. package/dist/src/headless-stdin.js +78 -0
  147. package/dist/src/headless-stdin.js.map +1 -0
  148. package/dist/src/headless.d.ts +106 -0
  149. package/dist/src/headless.js +229 -0
  150. package/dist/src/headless.js.map +1 -0
  151. package/dist/src/hooks/codex-hook-runner.d.ts +92 -0
  152. package/dist/src/hooks/codex-hook-runner.js +446 -0
  153. package/dist/src/hooks/codex-hook-runner.js.map +1 -0
  154. package/dist/src/hooks/codex-hooks.d.ts +23 -0
  155. package/dist/src/hooks/codex-hooks.js +152 -0
  156. package/dist/src/hooks/codex-hooks.js.map +1 -0
  157. package/dist/src/hooks/hook-process.d.ts +23 -0
  158. package/dist/src/hooks/hook-process.js +241 -0
  159. package/dist/src/hooks/hook-process.js.map +1 -0
  160. package/dist/src/hooks/lifecycle-hooks.d.ts +37 -0
  161. package/dist/src/hooks/lifecycle-hooks.js +153 -0
  162. package/dist/src/hooks/lifecycle-hooks.js.map +1 -0
  163. package/dist/src/hooks/tool-hooks.d.ts +63 -0
  164. package/dist/src/hooks/tool-hooks.js +350 -0
  165. package/dist/src/hooks/tool-hooks.js.map +1 -0
  166. package/dist/src/mcp/codegraph-preflight.d.ts +29 -0
  167. package/dist/src/mcp/codegraph-preflight.js +232 -0
  168. package/dist/src/mcp/codegraph-preflight.js.map +1 -0
  169. package/dist/src/mcp/registry.d.ts +133 -0
  170. package/dist/src/mcp/registry.js +209 -0
  171. package/dist/src/mcp/registry.js.map +1 -0
  172. package/dist/src/mcp/web-search-empty-results.d.ts +14 -0
  173. package/dist/src/mcp/web-search-empty-results.js +94 -0
  174. package/dist/src/mcp/web-search-empty-results.js.map +1 -0
  175. package/dist/src/memory/command.d.ts +11 -0
  176. package/dist/src/memory/command.js +253 -0
  177. package/dist/src/memory/command.js.map +1 -0
  178. package/dist/src/memory/controller.d.ts +51 -0
  179. package/dist/src/memory/controller.js +316 -0
  180. package/dist/src/memory/controller.js.map +1 -0
  181. package/dist/src/memory/prompt.d.ts +4 -0
  182. package/dist/src/memory/prompt.js +22 -0
  183. package/dist/src/memory/prompt.js.map +1 -0
  184. package/dist/src/memory/scheduler.d.ts +33 -0
  185. package/dist/src/memory/scheduler.js +134 -0
  186. package/dist/src/memory/scheduler.js.map +1 -0
  187. package/dist/src/memory/state.d.ts +112 -0
  188. package/dist/src/memory/state.js +355 -0
  189. package/dist/src/memory/state.js.map +1 -0
  190. package/dist/src/memory/store.d.ts +19 -0
  191. package/dist/src/memory/store.js +130 -0
  192. package/dist/src/memory/store.js.map +1 -0
  193. package/dist/src/memory/tools.d.ts +29 -0
  194. package/dist/src/memory/tools.js +22 -0
  195. package/dist/src/memory/tools.js.map +1 -0
  196. package/dist/src/memory/validation.d.ts +33 -0
  197. package/dist/src/memory/validation.js +159 -0
  198. package/dist/src/memory/validation.js.map +1 -0
  199. package/dist/src/npm-package/generate-patch.d.ts +23 -0
  200. package/dist/src/npm-package/generate-patch.js +88 -0
  201. package/dist/src/npm-package/generate-patch.js.map +1 -0
  202. package/dist/src/npm-package/patch-package-format.d.ts +43 -0
  203. package/dist/src/npm-package/patch-package-format.js +66 -0
  204. package/dist/src/npm-package/patch-package-format.js.map +1 -0
  205. package/dist/src/paths.d.ts +39 -0
  206. package/dist/src/paths.js +105 -0
  207. package/dist/src/paths.js.map +1 -0
  208. package/dist/src/pricing/cost.d.ts +182 -0
  209. package/dist/src/pricing/cost.js +215 -0
  210. package/dist/src/pricing/cost.js.map +1 -0
  211. package/dist/src/pricing/model-prices.d.ts +112 -0
  212. package/dist/src/pricing/model-prices.js +320 -0
  213. package/dist/src/pricing/model-prices.js.map +1 -0
  214. package/dist/src/sdk-patch-preflight.d.ts +23 -0
  215. package/dist/src/sdk-patch-preflight.js +71 -0
  216. package/dist/src/sdk-patch-preflight.js.map +1 -0
  217. package/dist/src/skills/builtin/commit-message/SKILL.md +45 -0
  218. package/dist/src/skills/builtin/commit-message/references/types.md +8 -0
  219. package/dist/src/skills/builtin/developer/SKILL.md +107 -0
  220. package/dist/src/skills/builtin/self-evolution-research/SKILL.md +150 -0
  221. package/dist/src/skills/builtin/self-evolution-research/scripts/roll-research-path.mjs +208 -0
  222. package/dist/src/skills/builtin/self-reflection/SKILL.md +172 -0
  223. package/dist/src/skills/builtin/self-reflection/references/reflection-template.md +90 -0
  224. package/dist/src/skills/builtin/self-reflection/scripts/locate-trajectory.mjs +175 -0
  225. package/dist/src/skills/loader.d.ts +26 -0
  226. package/dist/src/skills/loader.js +186 -0
  227. package/dist/src/skills/loader.js.map +1 -0
  228. package/dist/src/skills/plugin.d.ts +34 -0
  229. package/dist/src/skills/plugin.js +137 -0
  230. package/dist/src/skills/plugin.js.map +1 -0
  231. package/dist/src/skills/prompt.d.ts +8 -0
  232. package/dist/src/skills/prompt.js +214 -0
  233. package/dist/src/skills/prompt.js.map +1 -0
  234. package/dist/src/skills/resource-safety.d.ts +15 -0
  235. package/dist/src/skills/resource-safety.js +149 -0
  236. package/dist/src/skills/resource-safety.js.map +1 -0
  237. package/dist/src/tools/background-bash.d.ts +95 -0
  238. package/dist/src/tools/background-bash.js +639 -0
  239. package/dist/src/tools/background-bash.js.map +1 -0
  240. package/dist/src/tools/background-tail.d.ts +28 -0
  241. package/dist/src/tools/background-tail.js +75 -0
  242. package/dist/src/tools/background-tail.js.map +1 -0
  243. package/dist/src/tools/background-wait-contract.d.ts +4 -0
  244. package/dist/src/tools/background-wait-contract.js +7 -0
  245. package/dist/src/tools/background-wait-contract.js.map +1 -0
  246. package/dist/src/tools/file-editor-serial.d.ts +24 -0
  247. package/dist/src/tools/file-editor-serial.js +99 -0
  248. package/dist/src/tools/file-editor-serial.js.map +1 -0
  249. package/dist/src/tools/image-viewer.d.ts +43 -0
  250. package/dist/src/tools/image-viewer.js +256 -0
  251. package/dist/src/tools/image-viewer.js.map +1 -0
  252. package/dist/src/tools/update-plan.d.ts +30 -0
  253. package/dist/src/tools/update-plan.js +65 -0
  254. package/dist/src/tools/update-plan.js.map +1 -0
  255. package/dist/src/tools/web-fetch.d.ts +70 -0
  256. package/dist/src/tools/web-fetch.js +667 -0
  257. package/dist/src/tools/web-fetch.js.map +1 -0
  258. package/dist/src/trajectory/export.d.ts +31 -0
  259. package/dist/src/trajectory/export.js +116 -0
  260. package/dist/src/trajectory/export.js.map +1 -0
  261. package/dist/src/trajectory/fork.d.ts +19 -0
  262. package/dist/src/trajectory/fork.js +110 -0
  263. package/dist/src/trajectory/fork.js.map +1 -0
  264. package/dist/src/trajectory/memory-tool.d.ts +20 -0
  265. package/dist/src/trajectory/memory-tool.js +98 -0
  266. package/dist/src/trajectory/memory-tool.js.map +1 -0
  267. package/dist/src/trajectory/prompt-history.d.ts +62 -0
  268. package/dist/src/trajectory/prompt-history.js +256 -0
  269. package/dist/src/trajectory/prompt-history.js.map +1 -0
  270. package/dist/src/trajectory/reader.d.ts +21 -0
  271. package/dist/src/trajectory/reader.js +62 -0
  272. package/dist/src/trajectory/reader.js.map +1 -0
  273. package/dist/src/trajectory/record.d.ts +417 -0
  274. package/dist/src/trajectory/record.js +394 -0
  275. package/dist/src/trajectory/record.js.map +1 -0
  276. package/dist/src/trajectory/replay.d.ts +74 -0
  277. package/dist/src/trajectory/replay.js +285 -0
  278. package/dist/src/trajectory/replay.js.map +1 -0
  279. package/dist/src/trajectory/resume-recap.d.ts +43 -0
  280. package/dist/src/trajectory/resume-recap.js +68 -0
  281. package/dist/src/trajectory/resume-recap.js.map +1 -0
  282. package/dist/src/trajectory/search.d.ts +40 -0
  283. package/dist/src/trajectory/search.js +127 -0
  284. package/dist/src/trajectory/search.js.map +1 -0
  285. package/dist/src/trajectory/spend.d.ts +157 -0
  286. package/dist/src/trajectory/spend.js +264 -0
  287. package/dist/src/trajectory/spend.js.map +1 -0
  288. package/dist/src/trajectory/stream.d.ts +30 -0
  289. package/dist/src/trajectory/stream.js +30 -0
  290. package/dist/src/trajectory/stream.js.map +1 -0
  291. package/dist/src/trajectory/writer.d.ts +310 -0
  292. package/dist/src/trajectory/writer.js +636 -0
  293. package/dist/src/trajectory/writer.js.map +1 -0
  294. package/dist/src/tui/App.d.ts +109 -0
  295. package/dist/src/tui/App.js +2660 -0
  296. package/dist/src/tui/App.js.map +1 -0
  297. package/dist/src/tui/InputBox.d.ts +90 -0
  298. package/dist/src/tui/InputBox.js +129 -0
  299. package/dist/src/tui/InputBox.js.map +1 -0
  300. package/dist/src/tui/MarkdownText.d.ts +16 -0
  301. package/dist/src/tui/MarkdownText.js +117 -0
  302. package/dist/src/tui/MarkdownText.js.map +1 -0
  303. package/dist/src/tui/MessageList.d.ts +27 -0
  304. package/dist/src/tui/MessageList.js +61 -0
  305. package/dist/src/tui/MessageList.js.map +1 -0
  306. package/dist/src/tui/PermissionPrompt.d.ts +18 -0
  307. package/dist/src/tui/PermissionPrompt.js +114 -0
  308. package/dist/src/tui/PermissionPrompt.js.map +1 -0
  309. package/dist/src/tui/PlanChecklist.d.ts +7 -0
  310. package/dist/src/tui/PlanChecklist.js +12 -0
  311. package/dist/src/tui/PlanChecklist.js.map +1 -0
  312. package/dist/src/tui/QueuedMessages.d.ts +8 -0
  313. package/dist/src/tui/QueuedMessages.js +24 -0
  314. package/dist/src/tui/QueuedMessages.js.map +1 -0
  315. package/dist/src/tui/StartupScreen.d.ts +25 -0
  316. package/dist/src/tui/StartupScreen.js +51 -0
  317. package/dist/src/tui/StartupScreen.js.map +1 -0
  318. package/dist/src/tui/ToolCallPanel.d.ts +33 -0
  319. package/dist/src/tui/ToolCallPanel.js +112 -0
  320. package/dist/src/tui/ToolCallPanel.js.map +1 -0
  321. package/dist/src/tui/WelcomeHeader.d.ts +30 -0
  322. package/dist/src/tui/WelcomeHeader.js +69 -0
  323. package/dist/src/tui/WelcomeHeader.js.map +1 -0
  324. package/dist/src/tui/background-tool-presentation.d.ts +22 -0
  325. package/dist/src/tui/background-tool-presentation.js +209 -0
  326. package/dist/src/tui/background-tool-presentation.js.map +1 -0
  327. package/dist/src/tui/busy-suffix.d.ts +37 -0
  328. package/dist/src/tui/busy-suffix.js +39 -0
  329. package/dist/src/tui/busy-suffix.js.map +1 -0
  330. package/dist/src/tui/clipboard-image.d.ts +18 -0
  331. package/dist/src/tui/clipboard-image.js +109 -0
  332. package/dist/src/tui/clipboard-image.js.map +1 -0
  333. package/dist/src/tui/context-format.d.ts +43 -0
  334. package/dist/src/tui/context-format.js +71 -0
  335. package/dist/src/tui/context-format.js.map +1 -0
  336. package/dist/src/tui/copy-command.d.ts +68 -0
  337. package/dist/src/tui/copy-command.js +182 -0
  338. package/dist/src/tui/copy-command.js.map +1 -0
  339. package/dist/src/tui/edit-diff.d.ts +135 -0
  340. package/dist/src/tui/edit-diff.js +356 -0
  341. package/dist/src/tui/edit-diff.js.map +1 -0
  342. package/dist/src/tui/frame-budget.d.ts +351 -0
  343. package/dist/src/tui/frame-budget.js +446 -0
  344. package/dist/src/tui/frame-budget.js.map +1 -0
  345. package/dist/src/tui/help-format.d.ts +17 -0
  346. package/dist/src/tui/help-format.js +38 -0
  347. package/dist/src/tui/help-format.js.map +1 -0
  348. package/dist/src/tui/live-text.d.ts +51 -0
  349. package/dist/src/tui/live-text.js +154 -0
  350. package/dist/src/tui/live-text.js.map +1 -0
  351. package/dist/src/tui/markdown.d.ts +62 -0
  352. package/dist/src/tui/markdown.js +244 -0
  353. package/dist/src/tui/markdown.js.map +1 -0
  354. package/dist/src/tui/mcp-format.d.ts +28 -0
  355. package/dist/src/tui/mcp-format.js +67 -0
  356. package/dist/src/tui/mcp-format.js.map +1 -0
  357. package/dist/src/tui/path-completion.d.ts +119 -0
  358. package/dist/src/tui/path-completion.js +305 -0
  359. package/dist/src/tui/path-completion.js.map +1 -0
  360. package/dist/src/tui/permission-queue.d.ts +61 -0
  361. package/dist/src/tui/permission-queue.js +129 -0
  362. package/dist/src/tui/permission-queue.js.map +1 -0
  363. package/dist/src/tui/plan-format.d.ts +9 -0
  364. package/dist/src/tui/plan-format.js +30 -0
  365. package/dist/src/tui/plan-format.js.map +1 -0
  366. package/dist/src/tui/prompt-completion.d.ts +22 -0
  367. package/dist/src/tui/prompt-completion.js +46 -0
  368. package/dist/src/tui/prompt-completion.js.map +1 -0
  369. package/dist/src/tui/prompt-editor.d.ts +102 -0
  370. package/dist/src/tui/prompt-editor.js +379 -0
  371. package/dist/src/tui/prompt-editor.js.map +1 -0
  372. package/dist/src/tui/prompt-history-search.d.ts +53 -0
  373. package/dist/src/tui/prompt-history-search.js +123 -0
  374. package/dist/src/tui/prompt-history-search.js.map +1 -0
  375. package/dist/src/tui/prompt-queue.d.ts +58 -0
  376. package/dist/src/tui/prompt-queue.js +74 -0
  377. package/dist/src/tui/prompt-queue.js.map +1 -0
  378. package/dist/src/tui/prompt-recall.d.ts +74 -0
  379. package/dist/src/tui/prompt-recall.js +90 -0
  380. package/dist/src/tui/prompt-recall.js.map +1 -0
  381. package/dist/src/tui/react-environment.d.ts +11 -0
  382. package/dist/src/tui/react-environment.js +24 -0
  383. package/dist/src/tui/react-environment.js.map +1 -0
  384. package/dist/src/tui/rewind-search.d.ts +34 -0
  385. package/dist/src/tui/rewind-search.js +68 -0
  386. package/dist/src/tui/rewind-search.js.map +1 -0
  387. package/dist/src/tui/shell-command.d.ts +114 -0
  388. package/dist/src/tui/shell-command.js +310 -0
  389. package/dist/src/tui/shell-command.js.map +1 -0
  390. package/dist/src/tui/spend-advisory.d.ts +52 -0
  391. package/dist/src/tui/spend-advisory.js +64 -0
  392. package/dist/src/tui/spend-advisory.js.map +1 -0
  393. package/dist/src/tui/status-format.d.ts +120 -0
  394. package/dist/src/tui/status-format.js +192 -0
  395. package/dist/src/tui/status-format.js.map +1 -0
  396. package/dist/src/tui/subagent-format.d.ts +49 -0
  397. package/dist/src/tui/subagent-format.js +146 -0
  398. package/dist/src/tui/subagent-format.js.map +1 -0
  399. package/dist/src/tui/task-format.d.ts +29 -0
  400. package/dist/src/tui/task-format.js +87 -0
  401. package/dist/src/tui/task-format.js.map +1 -0
  402. package/dist/src/tui/terminal-bell.d.ts +20 -0
  403. package/dist/src/tui/terminal-bell.js +33 -0
  404. package/dist/src/tui/terminal-bell.js.map +1 -0
  405. package/dist/src/tui/tool-detail-presentation.d.ts +60 -0
  406. package/dist/src/tui/tool-detail-presentation.js +206 -0
  407. package/dist/src/tui/tool-detail-presentation.js.map +1 -0
  408. package/dist/src/tui/turn-state.d.ts +195 -0
  409. package/dist/src/tui/turn-state.js +548 -0
  410. package/dist/src/tui/turn-state.js.map +1 -0
  411. package/dist/src/tui/visual-language.d.ts +45 -0
  412. package/dist/src/tui/visual-language.js +57 -0
  413. package/dist/src/tui/visual-language.js.map +1 -0
  414. package/dist/src/version.d.ts +7 -0
  415. package/dist/src/version.js +38 -0
  416. package/dist/src/version.js.map +1 -0
  417. package/package.json +60 -0
@@ -0,0 +1,67 @@
1
+ import type { Agent, AgentStreamEvent, BackgroundTasksConfig } from '@strands-agents/sdk';
2
+ /** The per-call selector the SDK middleware adds to `agentic` tool specs. */
3
+ export declare const BACKGROUND_EXECUTION_FLAG = "_background_execution";
4
+ /** The SDK's own management tool; parent-only, classified in `permission.ts`. */
5
+ export declare const MANAGE_BACKGROUND_TASK_TOOL_NAME = "strands_manage_background_task";
6
+ /** The synthetic tool-use name the SDK uses when it delivers a finished task. */
7
+ export declare const BACKGROUND_TASK_RESULT_TOOL_NAME = "strands_background_task_result";
8
+ export interface BackgroundDelegationConfigInput {
9
+ /** The delegation tools the model may route to the background. */
10
+ readonly delegationTools: readonly string[];
11
+ /**
12
+ * Every other tool the parent registers up front. Tools discovered later (MCP,
13
+ * plugin tools) are covered by the wildcard the builder adds.
14
+ */
15
+ readonly ordinaryToolNames: readonly string[];
16
+ /** The SER-061 cap (`concurrencyCap(config)`); the SDK engine queues beyond it. */
17
+ readonly maxConcurrency: number;
18
+ }
19
+ /**
20
+ * The `backgroundTasks` option for the parent Agent.
21
+ *
22
+ * `never` names every ordinary tool explicitly and closes with `'*'`, so a tool that
23
+ * only exists after `initialize()` (MCP servers, the offloader's retrieval tool, the
24
+ * plugin's own manage tool) is `never` as well rather than falling back to the SDK's
25
+ * `agentic` default for unnamed tools. The SDK rejects a name listed under two modes,
26
+ * so a delegation tool is removed from `never` if a caller passes it in both lists.
27
+ */
28
+ export declare function backgroundDelegationConfig(input: BackgroundDelegationConfigInput): BackgroundTasksConfig;
29
+ /** True when a tool-use input asks for background execution (`_background_execution: true`). */
30
+ export declare function backgroundExecutionRequested(input: unknown): boolean;
31
+ /**
32
+ * The one sentence both delegation tool descriptions carry. The flag itself is
33
+ * added to the spec by the SDK middleware, so the description only has to say when
34
+ * to use it and when the result comes back.
35
+ */
36
+ export declare function backgroundDelegationDescriptionClause(): string;
37
+ /**
38
+ * The task id inside the SDK's dispatch acknowledgement, or `undefined` for any
39
+ * other tool result. Reads the ack's fixed text shape only; never a task registry.
40
+ */
41
+ export declare function backgroundAckTaskId(content: readonly unknown[]): string | undefined;
42
+ /**
43
+ * Forwards background runs' `AfterToolCallEvent`s into the parent's stream.
44
+ *
45
+ * One instance per parent Agent; {@link observe} wraps exactly one `Agent.stream()`
46
+ * at a time (the runtime serializes turns). Per turn it remembers which tool-use ids
47
+ * the stream showed as routed to the background — a `beforeToolCallEvent` for a
48
+ * delegation tool whose input carries the flag and which no hook cancelled — and
49
+ * yields the hook-observed `AfterToolCallEvent` for those ids in front of the next SDK
50
+ * event. Ids a stream `afterToolCallEvent` closes are dropped (a denied or
51
+ * foreground call). Anything left over when a turn ends — a task still cancelling
52
+ * after Ctrl+C — is discarded at the start of the next turn: the SDK delivers that
53
+ * task's result pair before the next model call itself, and the transcript already
54
+ * shows the cancelled turn.
55
+ */
56
+ export declare class BackgroundDelegationObserver {
57
+ private readonly delegationTools;
58
+ private readonly pending;
59
+ private ready;
60
+ constructor(delegationTools: readonly string[]);
61
+ /** Registers the hook on the parent; call once, after construction. */
62
+ install(agent: Agent): void;
63
+ /** Tool-use ids routed to the background in the current turn and not yet settled. */
64
+ get pendingCount(): number;
65
+ observe(events: AsyncIterable<AgentStreamEvent>): AsyncIterable<AgentStreamEvent>;
66
+ private drain;
67
+ }
@@ -0,0 +1,159 @@
1
+ /**
2
+ * SER-064: background delegation through the SDK's own `backgroundTasks` plugin.
3
+ *
4
+ * Darwin schedules nothing here. The SDK plugin (`@strands-agents/sdk`
5
+ * `dist/src/background-tasks/background-tasks.js`) does four things once the parent
6
+ * Agent is constructed with the option this module builds:
7
+ *
8
+ * - adds an optional boolean `_background_execution` to the spec of every
9
+ * `agentic` tool through `InvokeModelStage.Input` middleware, so the model can
10
+ * choose per call;
11
+ * - in the executor, *after* `BeforeToolCallEvent` and any hook `cancel` — so the
12
+ * permission gate, plan-mode denial and the retry guard have already run —
13
+ * `routeToolCall` strips the flag and `submitToolCall` returns an ack tool result
14
+ * carrying a task id (`executor.js`, the `route === true` branch);
15
+ * - with `waitForCompletion: true`, `AfterInvocationEvent` waits for every tracked
16
+ * task, then `_deliverReady` appends one synthetic
17
+ * `strands_background_task_result` tool-use/tool-result pair through
18
+ * `continuations.addInput` and the same invocation makes another model call — so a
19
+ * result never crosses into a later user turn;
20
+ * - registers `strands_manage_background_task` (`list`/`get`/`cancel`) on the parent.
21
+ *
22
+ * Two of its events do not travel down the parent's stream, and that is what the
23
+ * observer below exists for. The background run's real `AfterToolCallEvent` is
24
+ * delivered to hook callbacks only (`ToolExecutor.executeBackground` → the agent's
25
+ * `_invokeCallbacks`), never yielded; the delivered pair reaches the stream only as
26
+ * `messageAddedEvent`s. Darwin's transcript, headless drivers and trajectory all read
27
+ * `beforeToolCallEvent`/`afterToolCallEvent` pairs, so without forwarding, a
28
+ * background `subagent` row would never finish and its result would never be
29
+ * recorded. {@link BackgroundDelegationObserver} therefore hooks the parent's
30
+ * `AfterToolCallEvent` at `HookOrder.SDK_LAST` (after the context offloader and the
31
+ * interventions have had their say about `result`) and yields the event — the same
32
+ * SDK object, unmodified — into the stream `AgentRuntime.send()` hands to its
33
+ * consumers, ahead of the next SDK event. Only calls the stream itself showed as
34
+ * routed to the background are forwarded; every foreground `AfterToolCallEvent` is
35
+ * yielded by the SDK and left alone.
36
+ */
37
+ import { AfterToolCallEvent, HookOrder } from '@strands-agents/sdk';
38
+ /** The per-call selector the SDK middleware adds to `agentic` tool specs. */
39
+ export const BACKGROUND_EXECUTION_FLAG = '_background_execution';
40
+ /** The SDK's own management tool; parent-only, classified in `permission.ts`. */
41
+ export const MANAGE_BACKGROUND_TASK_TOOL_NAME = 'strands_manage_background_task';
42
+ /** The synthetic tool-use name the SDK uses when it delivers a finished task. */
43
+ export const BACKGROUND_TASK_RESULT_TOOL_NAME = 'strands_background_task_result';
44
+ /** First line of the SDK's dispatch acknowledgement (`submitToolCall`). */
45
+ const ACK_FIRST_LINE = 'Background task dispatched.';
46
+ const ACK_TASK_ID = /^Task ID: (\S+)$/mu;
47
+ /**
48
+ * The `backgroundTasks` option for the parent Agent.
49
+ *
50
+ * `never` names every ordinary tool explicitly and closes with `'*'`, so a tool that
51
+ * only exists after `initialize()` (MCP servers, the offloader's retrieval tool, the
52
+ * plugin's own manage tool) is `never` as well rather than falling back to the SDK's
53
+ * `agentic` default for unnamed tools. The SDK rejects a name listed under two modes,
54
+ * so a delegation tool is removed from `never` if a caller passes it in both lists.
55
+ */
56
+ export function backgroundDelegationConfig(input) {
57
+ const agentic = [...new Set(input.delegationTools)];
58
+ const never = [...new Set(input.ordinaryToolNames)].filter((name) => !agentic.includes(name));
59
+ return {
60
+ agentic,
61
+ never: [...never, '*'],
62
+ waitForCompletion: true,
63
+ maxConcurrency: input.maxConcurrency,
64
+ };
65
+ }
66
+ /** True when a tool-use input asks for background execution (`_background_execution: true`). */
67
+ export function backgroundExecutionRequested(input) {
68
+ return (typeof input === 'object' &&
69
+ input !== null &&
70
+ !Array.isArray(input) &&
71
+ input[BACKGROUND_EXECUTION_FLAG] === true);
72
+ }
73
+ /**
74
+ * The one sentence both delegation tool descriptions carry. The flag itself is
75
+ * added to the spec by the SDK middleware, so the description only has to say when
76
+ * to use it and when the result comes back.
77
+ */
78
+ export function backgroundDelegationDescriptionClause() {
79
+ return (`Set ${BACKGROUND_EXECUTION_FLAG}: true to run this call in the background when you do not ` +
80
+ 'need its result immediately (reads only): you get an acknowledgement at once and the ' +
81
+ 'final report is delivered before your next model call in this same turn.');
82
+ }
83
+ /**
84
+ * The task id inside the SDK's dispatch acknowledgement, or `undefined` for any
85
+ * other tool result. Reads the ack's fixed text shape only; never a task registry.
86
+ */
87
+ export function backgroundAckTaskId(content) {
88
+ for (const block of content) {
89
+ if (typeof block !== 'object' || block === null)
90
+ continue;
91
+ const typed = block;
92
+ if (typed.type !== 'textBlock' || typeof typed.text !== 'string')
93
+ continue;
94
+ if (!typed.text.startsWith(ACK_FIRST_LINE))
95
+ continue;
96
+ return ACK_TASK_ID.exec(typed.text)?.[1];
97
+ }
98
+ return undefined;
99
+ }
100
+ /**
101
+ * Forwards background runs' `AfterToolCallEvent`s into the parent's stream.
102
+ *
103
+ * One instance per parent Agent; {@link observe} wraps exactly one `Agent.stream()`
104
+ * at a time (the runtime serializes turns). Per turn it remembers which tool-use ids
105
+ * the stream showed as routed to the background — a `beforeToolCallEvent` for a
106
+ * delegation tool whose input carries the flag and which no hook cancelled — and
107
+ * yields the hook-observed `AfterToolCallEvent` for those ids in front of the next SDK
108
+ * event. Ids a stream `afterToolCallEvent` closes are dropped (a denied or
109
+ * foreground call). Anything left over when a turn ends — a task still cancelling
110
+ * after Ctrl+C — is discarded at the start of the next turn: the SDK delivers that
111
+ * task's result pair before the next model call itself, and the transcript already
112
+ * shows the cancelled turn.
113
+ */
114
+ export class BackgroundDelegationObserver {
115
+ delegationTools;
116
+ pending = new Set();
117
+ ready = [];
118
+ constructor(delegationTools) {
119
+ this.delegationTools = new Set(delegationTools);
120
+ }
121
+ /** Registers the hook on the parent; call once, after construction. */
122
+ install(agent) {
123
+ agent.addHook(AfterToolCallEvent, (event) => {
124
+ if (this.pending.delete(event.toolUse.toolUseId))
125
+ this.ready.push(event);
126
+ }, { order: HookOrder.SDK_LAST });
127
+ }
128
+ /** Tool-use ids routed to the background in the current turn and not yet settled. */
129
+ get pendingCount() {
130
+ return this.pending.size;
131
+ }
132
+ async *observe(events) {
133
+ this.pending.clear();
134
+ this.ready = [];
135
+ for await (const event of events) {
136
+ if (event.type === 'beforeToolCallEvent') {
137
+ if (!event.cancel &&
138
+ this.delegationTools.has(event.toolUse.name) &&
139
+ backgroundExecutionRequested(event.toolUse.input)) {
140
+ this.pending.add(event.toolUse.toolUseId);
141
+ }
142
+ }
143
+ else if (event.type === 'afterToolCallEvent') {
144
+ this.pending.delete(event.toolUse.toolUseId);
145
+ }
146
+ yield* this.drain();
147
+ yield event;
148
+ }
149
+ yield* this.drain();
150
+ }
151
+ *drain() {
152
+ if (this.ready.length === 0)
153
+ return;
154
+ const events = this.ready;
155
+ this.ready = [];
156
+ yield* events;
157
+ }
158
+ }
159
+ //# sourceMappingURL=background-delegation.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"background-delegation.js","sourceRoot":"","sources":["../../../src/agent/background-delegation.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Session-scoped per-model-call efficiency stats (issue #8 follow-up A).
3
+ *
4
+ * `AgentRuntime.send` already forwards every `afterModelCallEvent`; this module is
5
+ * the pure arithmetic over what those events carry — `stopData.message.metadata.usage`
6
+ * (the provider's counters for that one call) and `stopData.message.content` (whose
7
+ * toolUse blocks say how much work one round trip bought). Everything here is
8
+ * synchronous, allocation-only and non-throwing by construction: the runtime observes
9
+ * between `stream()` and `yield`, so a broken tally must degrade to absence, never
10
+ * become a second reason a turn dies.
11
+ *
12
+ * Parent-only by the same construction the trajectory relies on: child agents are
13
+ * private to their dispatch and never pass through `AgentRuntime.send`, so no child
14
+ * call can reach these counters (children are covered by the 9e39de5 childUsage
15
+ * aggregation instead). Session-scoped for free: `/clear` builds a successor runtime
16
+ * through `create()`, whose stats start empty.
17
+ */
18
+ import type { AppConfig } from '../config.js';
19
+ import { type UsageTotals } from './usage.js';
20
+ /**
21
+ * How many recent completed calls the advisory window keeps. Ten is enough to see
22
+ * the "repeated long-context single-tool round" pattern without remembering a
23
+ * session's whole history.
24
+ */
25
+ export declare const RECENT_CALL_WINDOW = 10;
26
+ /** What one session's completed model calls added up to, so far. */
27
+ export interface SessionCallStats {
28
+ /** Completed model calls observed (`afterModelCallEvent` with `stopData`). */
29
+ calls: number;
30
+ /**
31
+ * Calls whose provider reported usage — the denominator for per-call averages.
32
+ * Kept separately from {@link calls} so an unmetered call can never dilute an
33
+ * average into a number nobody measured.
34
+ */
35
+ meteredCalls: number;
36
+ /**
37
+ * Raw provider counters summed over the metered calls, `sumUsage` rules: a cache
38
+ * key is present only when at least one call reported it, so an unknown metric
39
+ * stays absent — never an invented 0. `undefined` until any call reports usage.
40
+ */
41
+ usage: UsageTotals | undefined;
42
+ /** Completed responses that requested no tool. */
43
+ noTool: number;
44
+ /** Completed responses that requested exactly one tool. */
45
+ singleTool: number;
46
+ /** Completed responses that requested two or more tools (parallel reads, ideally). */
47
+ multiTool: number;
48
+ /**
49
+ * toolUse counts of the last {@link RECENT_CALL_WINDOW} completed calls, oldest
50
+ * first — the advisory's evidence for "recent rounds each bought ≤1 tool".
51
+ */
52
+ recentToolUseCounts: readonly number[];
53
+ }
54
+ /** The zero state a session starts from. All-zero is honest here: nothing happened yet. */
55
+ export declare function emptyCallStats(): SessionCallStats;
56
+ /**
57
+ * The two facts one completed call contributes, in the shape
58
+ * `afterModelCallEvent.stopData.message` carries them. Typed structurally and read
59
+ * defensively so the update stays a pure function over data — no SDK import, and a
60
+ * malformed payload costs that call's contribution, not the session's counters.
61
+ */
62
+ export interface CompletedModelCall {
63
+ message?: {
64
+ /** `metadata.usage`: the provider's counters for this one call, when reported. */
65
+ metadata?: {
66
+ usage?: unknown;
67
+ };
68
+ /** The completed message's content blocks, for the tool-shape tallies. */
69
+ content?: unknown;
70
+ };
71
+ }
72
+ /**
73
+ * Folds one completed model call into the stats. Pure: returns a new value and
74
+ * touches neither argument, so a caller can hold snapshots without copying.
75
+ *
76
+ * A call with no usable usage still counts as a call and still shapes the tool
77
+ * tallies — the response happened whether or not the provider priced it — but adds
78
+ * nothing to the sums ({@link SessionCallStats.meteredCalls} keeps the averages
79
+ * honest about that).
80
+ */
81
+ export declare function recordCompletedCall(stats: SessionCallStats, call: CompletedModelCall): SessionCallStats;
82
+ /**
83
+ * toolUse blocks in one completed message's content.
84
+ *
85
+ * Matched on both shapes the payload legitimately has: the in-memory
86
+ * `type: 'toolUseBlock'` class discriminator (what the live stream carries) and the
87
+ * serialized `{ toolUse: … }` wire shape (`ToolUseBlock.toJSON()` drops the
88
+ * discriminator, exactly as `record.ts` documents for reasoning blocks). Anything
89
+ * else — including a non-array `content` — counts zero tools rather than throwing.
90
+ */
91
+ export declare function countToolUses(content: unknown): number;
92
+ /**
93
+ * Average request input per metered call, in tokens — how big the submitted context
94
+ * has been running, which is the number the efficiency question is really about.
95
+ *
96
+ * The request total follows the `cacheEffectivenessRows` convention over the same
97
+ * `usageBuckets` projection: OpenAI Responses reports cache activity as subsets of
98
+ * `input_tokens`, so its input *is* the request total; every other provider reports
99
+ * cache reads/writes beside uncached input, so the request is their sum, with an
100
+ * unreported cache counter contributing nothing rather than blocking the average.
101
+ * `undefined` when no call was metered or the buckets cannot split honestly —
102
+ * unknown, never 0.
103
+ */
104
+ export declare function averageRequestInputTokens(stats: SessionCallStats, config: AppConfig): number | undefined;
105
+ /**
106
+ * The one-line reading `/status` prints — shared here so `/status`, `/usage`'s
107
+ * efficiency section and any future surface derive the same numbers from the same
108
+ * arithmetic and cannot drift. An unknown average reads `not reported`
109
+ * ({@link formatUsageValue}), never 0.
110
+ */
111
+ export declare function describeCallEfficiency(stats: SessionCallStats, config: AppConfig): string;
112
+ /**
113
+ * One call's provider counters as `UsageTotals`, or `undefined` when unusable.
114
+ *
115
+ * Exported so the `/context` measurement anchor reads a completed call's usage
116
+ * through this same defensive reader instead of writing a second one.
117
+ */
118
+ export declare function readCallUsage(value: unknown): UsageTotals | undefined;
@@ -0,0 +1,128 @@
1
+ import { formatUsageValue, requestInputTokens, sumUsage } from './usage.js';
2
+ /**
3
+ * How many recent completed calls the advisory window keeps. Ten is enough to see
4
+ * the "repeated long-context single-tool round" pattern without remembering a
5
+ * session's whole history.
6
+ */
7
+ export const RECENT_CALL_WINDOW = 10;
8
+ /** The zero state a session starts from. All-zero is honest here: nothing happened yet. */
9
+ export function emptyCallStats() {
10
+ return {
11
+ calls: 0,
12
+ meteredCalls: 0,
13
+ usage: undefined,
14
+ noTool: 0,
15
+ singleTool: 0,
16
+ multiTool: 0,
17
+ recentToolUseCounts: [],
18
+ };
19
+ }
20
+ /**
21
+ * Folds one completed model call into the stats. Pure: returns a new value and
22
+ * touches neither argument, so a caller can hold snapshots without copying.
23
+ *
24
+ * A call with no usable usage still counts as a call and still shapes the tool
25
+ * tallies — the response happened whether or not the provider priced it — but adds
26
+ * nothing to the sums ({@link SessionCallStats.meteredCalls} keeps the averages
27
+ * honest about that).
28
+ */
29
+ export function recordCompletedCall(stats, call) {
30
+ const usage = readCallUsage(call.message?.metadata?.usage);
31
+ const toolUses = countToolUses(call.message?.content);
32
+ return {
33
+ calls: stats.calls + 1,
34
+ meteredCalls: stats.meteredCalls + (usage === undefined ? 0 : 1),
35
+ usage: usage === undefined
36
+ ? stats.usage
37
+ : stats.usage === undefined
38
+ ? usage
39
+ : sumUsage([stats.usage, usage]),
40
+ noTool: stats.noTool + (toolUses === 0 ? 1 : 0),
41
+ singleTool: stats.singleTool + (toolUses === 1 ? 1 : 0),
42
+ multiTool: stats.multiTool + (toolUses >= 2 ? 1 : 0),
43
+ recentToolUseCounts: [...stats.recentToolUseCounts, toolUses].slice(-RECENT_CALL_WINDOW),
44
+ };
45
+ }
46
+ /**
47
+ * toolUse blocks in one completed message's content.
48
+ *
49
+ * Matched on both shapes the payload legitimately has: the in-memory
50
+ * `type: 'toolUseBlock'` class discriminator (what the live stream carries) and the
51
+ * serialized `{ toolUse: … }` wire shape (`ToolUseBlock.toJSON()` drops the
52
+ * discriminator, exactly as `record.ts` documents for reasoning blocks). Anything
53
+ * else — including a non-array `content` — counts zero tools rather than throwing.
54
+ */
55
+ export function countToolUses(content) {
56
+ if (!Array.isArray(content))
57
+ return 0;
58
+ let count = 0;
59
+ for (const block of content) {
60
+ if (block === null || typeof block !== 'object')
61
+ continue;
62
+ const candidate = block;
63
+ if (candidate.type === 'toolUseBlock' || (candidate.type === undefined && candidate.toolUse !== undefined)) {
64
+ count += 1;
65
+ }
66
+ }
67
+ return count;
68
+ }
69
+ /**
70
+ * Average request input per metered call, in tokens — how big the submitted context
71
+ * has been running, which is the number the efficiency question is really about.
72
+ *
73
+ * The request total follows the `cacheEffectivenessRows` convention over the same
74
+ * `usageBuckets` projection: OpenAI Responses reports cache activity as subsets of
75
+ * `input_tokens`, so its input *is* the request total; every other provider reports
76
+ * cache reads/writes beside uncached input, so the request is their sum, with an
77
+ * unreported cache counter contributing nothing rather than blocking the average.
78
+ * `undefined` when no call was metered or the buckets cannot split honestly —
79
+ * unknown, never 0.
80
+ */
81
+ export function averageRequestInputTokens(stats, config) {
82
+ if (stats.usage === undefined || stats.meteredCalls <= 0)
83
+ return undefined;
84
+ const submitted = requestInputTokens(stats.usage, config);
85
+ if (submitted === undefined)
86
+ return undefined;
87
+ return Math.round(submitted / stats.meteredCalls);
88
+ }
89
+ /**
90
+ * The one-line reading `/status` prints — shared here so `/status`, `/usage`'s
91
+ * efficiency section and any future surface derive the same numbers from the same
92
+ * arithmetic and cannot drift. An unknown average reads `not reported`
93
+ * ({@link formatUsageValue}), never 0.
94
+ */
95
+ export function describeCallEfficiency(stats, config) {
96
+ const average = formatUsageValue(averageRequestInputTokens(stats, config));
97
+ return (`${stats.calls} completed · avg request input ${average} · ` +
98
+ `tool responses ${stats.singleTool} single / ${stats.multiTool} multi / ${stats.noTool} none`);
99
+ }
100
+ /**
101
+ * One call's provider counters as `UsageTotals`, or `undefined` when unusable.
102
+ *
103
+ * Exported so the `/context` measurement anchor reads a completed call's usage
104
+ * through this same defensive reader instead of writing a second one.
105
+ */
106
+ export function readCallUsage(value) {
107
+ if (value === null || typeof value !== 'object')
108
+ return undefined;
109
+ const { inputTokens, outputTokens, cacheReadInputTokens, cacheWriteInputTokens } = value;
110
+ const input = finite(inputTokens);
111
+ const output = finite(outputTokens);
112
+ // input/output are always reported by every provider the SDK supports; a payload
113
+ // missing either is not a measurement and contributes nothing.
114
+ if (input === undefined || output === undefined)
115
+ return undefined;
116
+ const read = finite(cacheReadInputTokens);
117
+ const write = finite(cacheWriteInputTokens);
118
+ return {
119
+ inputTokens: input,
120
+ outputTokens: output,
121
+ ...(read === undefined ? {} : { cacheReadInputTokens: read }),
122
+ ...(write === undefined ? {} : { cacheWriteInputTokens: write }),
123
+ };
124
+ }
125
+ function finite(value) {
126
+ return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
127
+ }
128
+ //# sourceMappingURL=call-stats.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"call-stats.js","sourceRoot":"","sources":["../../../src/agent/call-stats.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,108 @@
1
+ /**
2
+ * Explicit conversation compaction through the SDK's summarization extension.
3
+ *
4
+ * The runtime owns persistence; this module owns only the reversible message
5
+ * transformation and token accounting, which keeps it testable with a real SDK
6
+ * Agent and a deterministic model.
7
+ */
8
+ import type { Agent, Message, Model, SummarizingConversationManagerConfig } from '@strands-agents/sdk';
9
+ import { SummarizingConversationManager } from '@strands-agents/sdk';
10
+ /**
11
+ * `/compact` collapses every reducible old message in one command, leaving one
12
+ * summary plus the recent window. 0.8 is the SDK's maximum ratio and minimizes
13
+ * model calls; overflow recovery uses the configurable `summaryRatio` instead.
14
+ */
15
+ export declare const COMPACT_SUMMARY_RATIO = 0.8;
16
+ /** Upper bound on one `/compact <focus>` argument, in code points, after trimming. */
17
+ export declare const MAX_COMPACT_FOCUS_CODE_POINTS = 400;
18
+ /**
19
+ * The one fixed section appended after the SDK prompt when a focus is given. The
20
+ * focus is plain text under this heading — never parsed, never a command.
21
+ */
22
+ export declare const COMPACT_FOCUS_HEADING = "User's focus for this summary (keep what it names in detail):";
23
+ /**
24
+ * Trims a `/compact` argument; blank text means "no focus". Returns the trimmed
25
+ * text unbounded — {@link compactFocusRefusal} decides whether it may be used.
26
+ */
27
+ export declare function normalizeCompactFocus(text: string | undefined): string | undefined;
28
+ /** The notice for a focus over the cap, or undefined when the focus is acceptable. */
29
+ export declare function compactFocusRefusal(focus: string | undefined): string | undefined;
30
+ /**
31
+ * The summarizer system prompt: the SDK default verbatim, then — only with a
32
+ * focus — one blank line and the fixed focus section. Unfocused callers must not
33
+ * call this; they leave the manager's `summarizationSystemPrompt` unset so the
34
+ * SDK applies its own default and the request is identical to a plain `/compact`.
35
+ */
36
+ export declare function focusedSummarizationPrompt(focus: string): string;
37
+ /**
38
+ * Constructor config for one `/compact` manager. Without a focus the object has
39
+ * exactly the two keys the process-lifetime manager used to be built with, so the
40
+ * unfocused request cannot differ from before per-call construction existed.
41
+ *
42
+ * @throws When the focus is over the cap — refused before any manager, hook or
43
+ * model call exists.
44
+ */
45
+ export declare function compactionManagerConfig(preserveRecentMessages: number, focus?: string): SummarizingConversationManagerConfig;
46
+ /** One manager per `/compact` call: the focus is constructor-only in the SDK. */
47
+ export declare function createCompactionManager(preserveRecentMessages: number, focus?: string): SummarizingConversationManager;
48
+ export interface CompactResult {
49
+ messagesBefore: number;
50
+ messagesAfter: number;
51
+ estimatedTokensBefore: number;
52
+ estimatedTokensAfter: number;
53
+ estimatedTokensSaved: number;
54
+ /**
55
+ * True only when the message count really dropped. False when the recent
56
+ * window already contains the whole conversation, or when the one pass the
57
+ * SDK could make did not lower the count (undone; see `compactConversation`).
58
+ */
59
+ compacted: boolean;
60
+ }
61
+ /**
62
+ * The failure surfaced when the SDK's proactive `reduce()` swallows a summarization
63
+ * error and returns `false`. The SDK's own `proactive summarization failed` warning,
64
+ * routed through `routeSdkLogs`, carries the underlying cause right before this.
65
+ */
66
+ export declare const SWALLOWED_SUMMARIZATION_FAILURE = "the summarizer made no reduction; the preceding sdk warning names the cause";
67
+ export interface CompactConversationOptions {
68
+ agent: Agent;
69
+ model: Model;
70
+ manager: SummarizingConversationManager;
71
+ preserveRecentMessages: number;
72
+ persist: () => Promise<void>;
73
+ }
74
+ /**
75
+ * Summarizes every reducible old message, persists the result, and restores the
76
+ * original messages if summarization, counting, or persistence fails.
77
+ *
78
+ * Termination and honesty rules (SER-052):
79
+ * - a pass that returns `true` without lowering the message count is undone and
80
+ * ends the loop, so `compacted` / `messagesAfter` describe what really changed
81
+ * and the loop makes at most one summarizer call beyond the shrinking ones;
82
+ * - a pass that returns `false` is a summarization failure the SDK swallowed
83
+ * (proactive `reduce()` has no other `false` inside this loop) — it rejects and
84
+ * rolls back everything, never reports `compacted: true`.
85
+ * Both rules apply to focused and unfocused managers alike.
86
+ */
87
+ export declare function compactConversation({ agent, model, manager, preserveRecentMessages, persist, }: CompactConversationOptions): Promise<CompactResult>;
88
+ /**
89
+ * Repairs user-role messages that carry `reasoningBlock` content in place.
90
+ *
91
+ * The SDK's summarizer used to copy a thinking model's whole response —
92
+ * reasoning blocks included — into a user-role summary message; providers
93
+ * reject any later request containing it (`User messages cannot contain
94
+ * reasoning content`). A user message can never legally carry reasoning
95
+ * content on any provider, so dropping those blocks is always safe. Message
96
+ * object identity, order, and every non-reasoning block are preserved; the
97
+ * mutation is in-memory only, so the next ordinary save persists it.
98
+ *
99
+ * A message that would be left with zero blocks is left untouched and not
100
+ * counted: a poisoned summary always also carries its text block, so an
101
+ * all-reasoning user message is not the known poisoning — and an empty
102
+ * content array would itself be invalid, trading one rejection for another.
103
+ *
104
+ * @returns The number of messages repaired.
105
+ */
106
+ export declare function stripReasoningFromUserMessages(messages: Message[]): number;
107
+ /** Counts the complete assembled context the next model request will receive. */
108
+ export declare function countConversationTokens(model: Model, agent: Agent): Promise<number>;