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.
- package/README.md +140 -0
- package/README.zh-CN.md +140 -0
- package/dist/patches/@strands-agents+sdk+1.16.0.patch +1443 -0
- package/dist/src/agent/background-delegation.d.ts +67 -0
- package/dist/src/agent/background-delegation.js +159 -0
- package/dist/src/agent/background-delegation.js.map +1 -0
- package/dist/src/agent/call-stats.d.ts +118 -0
- package/dist/src/agent/call-stats.js +128 -0
- package/dist/src/agent/call-stats.js.map +1 -0
- package/dist/src/agent/compact.d.ts +108 -0
- package/dist/src/agent/compact.js +192 -0
- package/dist/src/agent/compact.js.map +1 -0
- package/dist/src/agent/context-anchor.d.ts +64 -0
- package/dist/src/agent/context-anchor.js +43 -0
- package/dist/src/agent/context-anchor.js.map +1 -0
- package/dist/src/agent/cost.d.ts +56 -0
- package/dist/src/agent/cost.js +44 -0
- package/dist/src/agent/cost.js.map +1 -0
- package/dist/src/agent/diagnostics.d.ts +212 -0
- package/dist/src/agent/diagnostics.js +374 -0
- package/dist/src/agent/diagnostics.js.map +1 -0
- package/dist/src/agent/instructions.d.ts +54 -0
- package/dist/src/agent/instructions.js +118 -0
- package/dist/src/agent/instructions.js.map +1 -0
- package/dist/src/agent/max-tokens-recovery.d.ts +17 -0
- package/dist/src/agent/max-tokens-recovery.js +65 -0
- package/dist/src/agent/max-tokens-recovery.js.map +1 -0
- package/dist/src/agent/model-call-budget.d.ts +8 -0
- package/dist/src/agent/model-call-budget.js +24 -0
- package/dist/src/agent/model-call-budget.js.map +1 -0
- package/dist/src/agent/model-retry.d.ts +134 -0
- package/dist/src/agent/model-retry.js +256 -0
- package/dist/src/agent/model-retry.js.map +1 -0
- package/dist/src/agent/permission-rules.d.ts +47 -0
- package/dist/src/agent/permission-rules.js +260 -0
- package/dist/src/agent/permission-rules.js.map +1 -0
- package/dist/src/agent/permission.d.ts +361 -0
- package/dist/src/agent/permission.js +797 -0
- package/dist/src/agent/permission.js.map +1 -0
- package/dist/src/agent/prompt-cache.d.ts +66 -0
- package/dist/src/agent/prompt-cache.js +194 -0
- package/dist/src/agent/prompt-cache.js.map +1 -0
- package/dist/src/agent/refusal.d.ts +20 -0
- package/dist/src/agent/refusal.js +23 -0
- package/dist/src/agent/refusal.js.map +1 -0
- package/dist/src/agent/retry-guard.d.ts +26 -0
- package/dist/src/agent/retry-guard.js +193 -0
- package/dist/src/agent/retry-guard.js.map +1 -0
- package/dist/src/agent/rewind.d.ts +29 -0
- package/dist/src/agent/rewind.js +118 -0
- package/dist/src/agent/rewind.js.map +1 -0
- package/dist/src/agent/runtime.d.ts +814 -0
- package/dist/src/agent/runtime.js +1596 -0
- package/dist/src/agent/runtime.js.map +1 -0
- package/dist/src/agent/safety-classifier.d.ts +11 -0
- package/dist/src/agent/safety-classifier.js +0 -0
- package/dist/src/agent/safety-classifier.js.map +1 -0
- package/dist/src/agent/sdk-logging.d.ts +49 -0
- package/dist/src/agent/sdk-logging.js +110 -0
- package/dist/src/agent/sdk-logging.js.map +1 -0
- package/dist/src/agent/session.d.ts +102 -0
- package/dist/src/agent/session.js +244 -0
- package/dist/src/agent/session.js.map +1 -0
- package/dist/src/agent/stream-resumption.d.ts +16 -0
- package/dist/src/agent/stream-resumption.js +33 -0
- package/dist/src/agent/stream-resumption.js.map +1 -0
- package/dist/src/agent/system-prompt.d.ts +50 -0
- package/dist/src/agent/system-prompt.js +161 -0
- package/dist/src/agent/system-prompt.js.map +1 -0
- package/dist/src/agent/thinking.d.ts +99 -0
- package/dist/src/agent/thinking.js +145 -0
- package/dist/src/agent/thinking.js.map +1 -0
- package/dist/src/agent/usage.d.ts +132 -0
- package/dist/src/agent/usage.js +233 -0
- package/dist/src/agent/usage.js.map +1 -0
- package/dist/src/agent/working-context.d.ts +51 -0
- package/dist/src/agent/working-context.js +160 -0
- package/dist/src/agent/working-context.js.map +1 -0
- package/dist/src/agents/child-recipe.d.ts +33 -0
- package/dist/src/agents/child-recipe.js +98 -0
- package/dist/src/agents/child-recipe.js.map +1 -0
- package/dist/src/agents/concurrency-limit.d.ts +25 -0
- package/dist/src/agents/concurrency-limit.js +43 -0
- package/dist/src/agents/concurrency-limit.js.map +1 -0
- package/dist/src/agents/dispatch-registry.d.ts +180 -0
- package/dist/src/agents/dispatch-registry.js +289 -0
- package/dist/src/agents/dispatch-registry.js.map +1 -0
- package/dist/src/agents/failed-child-text.d.ts +44 -0
- package/dist/src/agents/failed-child-text.js +69 -0
- package/dist/src/agents/failed-child-text.js.map +1 -0
- package/dist/src/agents/loader.d.ts +26 -0
- package/dist/src/agents/loader.js +134 -0
- package/dist/src/agents/loader.js.map +1 -0
- package/dist/src/agents/report-projection.d.ts +31 -0
- package/dist/src/agents/report-projection.js +125 -0
- package/dist/src/agents/report-projection.js.map +1 -0
- package/dist/src/agents/subagent-tool.d.ts +61 -0
- package/dist/src/agents/subagent-tool.js +180 -0
- package/dist/src/agents/subagent-tool.js.map +1 -0
- package/dist/src/agents/workflow-tool.d.ts +85 -0
- package/dist/src/agents/workflow-tool.js +530 -0
- package/dist/src/agents/workflow-tool.js.map +1 -0
- package/dist/src/cli-args.d.ts +39 -0
- package/dist/src/cli-args.js +198 -0
- package/dist/src/cli-args.js.map +1 -0
- package/dist/src/cli-doctor.d.ts +26 -0
- package/dist/src/cli-doctor.js +398 -0
- package/dist/src/cli-doctor.js.map +1 -0
- package/dist/src/cli-main.d.ts +1 -0
- package/dist/src/cli-main.js +279 -0
- package/dist/src/cli-main.js.map +1 -0
- package/dist/src/cli-sessions.d.ts +17 -0
- package/dist/src/cli-sessions.js +136 -0
- package/dist/src/cli-sessions.js.map +1 -0
- package/dist/src/cli-trajectory.d.ts +37 -0
- package/dist/src/cli-trajectory.js +303 -0
- package/dist/src/cli-trajectory.js.map +1 -0
- package/dist/src/cli-usage.d.ts +18 -0
- package/dist/src/cli-usage.js +53 -0
- package/dist/src/cli-usage.js.map +1 -0
- package/dist/src/cli.d.ts +2 -0
- package/dist/src/cli.js +29 -0
- package/dist/src/cli.js.map +1 -0
- package/dist/src/commands/custom-commands.d.ts +43 -0
- package/dist/src/commands/custom-commands.js +155 -0
- package/dist/src/commands/custom-commands.js.map +1 -0
- package/dist/src/commands/workflow-command.d.ts +26 -0
- package/dist/src/commands/workflow-command.js +56 -0
- package/dist/src/commands/workflow-command.js.map +1 -0
- package/dist/src/config.d.ts +463 -0
- package/dist/src/config.js +1457 -0
- package/dist/src/config.js.map +1 -0
- package/dist/src/context-overflow-error.d.ts +7 -0
- package/dist/src/context-overflow-error.js +26 -0
- package/dist/src/context-overflow-error.js.map +1 -0
- package/dist/src/dev-repl.d.ts +1 -0
- package/dist/src/dev-repl.js +365 -0
- package/dist/src/dev-repl.js.map +1 -0
- package/dist/src/headless-protocol.d.ts +147 -0
- package/dist/src/headless-protocol.js +359 -0
- package/dist/src/headless-protocol.js.map +1 -0
- package/dist/src/headless-runner.d.ts +30 -0
- package/dist/src/headless-runner.js +405 -0
- package/dist/src/headless-runner.js.map +1 -0
- package/dist/src/headless-stdin.d.ts +28 -0
- package/dist/src/headless-stdin.js +78 -0
- package/dist/src/headless-stdin.js.map +1 -0
- package/dist/src/headless.d.ts +106 -0
- package/dist/src/headless.js +229 -0
- package/dist/src/headless.js.map +1 -0
- package/dist/src/hooks/codex-hook-runner.d.ts +92 -0
- package/dist/src/hooks/codex-hook-runner.js +446 -0
- package/dist/src/hooks/codex-hook-runner.js.map +1 -0
- package/dist/src/hooks/codex-hooks.d.ts +23 -0
- package/dist/src/hooks/codex-hooks.js +152 -0
- package/dist/src/hooks/codex-hooks.js.map +1 -0
- package/dist/src/hooks/hook-process.d.ts +23 -0
- package/dist/src/hooks/hook-process.js +241 -0
- package/dist/src/hooks/hook-process.js.map +1 -0
- package/dist/src/hooks/lifecycle-hooks.d.ts +37 -0
- package/dist/src/hooks/lifecycle-hooks.js +153 -0
- package/dist/src/hooks/lifecycle-hooks.js.map +1 -0
- package/dist/src/hooks/tool-hooks.d.ts +63 -0
- package/dist/src/hooks/tool-hooks.js +350 -0
- package/dist/src/hooks/tool-hooks.js.map +1 -0
- package/dist/src/mcp/codegraph-preflight.d.ts +29 -0
- package/dist/src/mcp/codegraph-preflight.js +232 -0
- package/dist/src/mcp/codegraph-preflight.js.map +1 -0
- package/dist/src/mcp/registry.d.ts +133 -0
- package/dist/src/mcp/registry.js +209 -0
- package/dist/src/mcp/registry.js.map +1 -0
- package/dist/src/mcp/web-search-empty-results.d.ts +14 -0
- package/dist/src/mcp/web-search-empty-results.js +94 -0
- package/dist/src/mcp/web-search-empty-results.js.map +1 -0
- package/dist/src/memory/command.d.ts +11 -0
- package/dist/src/memory/command.js +253 -0
- package/dist/src/memory/command.js.map +1 -0
- package/dist/src/memory/controller.d.ts +51 -0
- package/dist/src/memory/controller.js +316 -0
- package/dist/src/memory/controller.js.map +1 -0
- package/dist/src/memory/prompt.d.ts +4 -0
- package/dist/src/memory/prompt.js +22 -0
- package/dist/src/memory/prompt.js.map +1 -0
- package/dist/src/memory/scheduler.d.ts +33 -0
- package/dist/src/memory/scheduler.js +134 -0
- package/dist/src/memory/scheduler.js.map +1 -0
- package/dist/src/memory/state.d.ts +112 -0
- package/dist/src/memory/state.js +355 -0
- package/dist/src/memory/state.js.map +1 -0
- package/dist/src/memory/store.d.ts +19 -0
- package/dist/src/memory/store.js +130 -0
- package/dist/src/memory/store.js.map +1 -0
- package/dist/src/memory/tools.d.ts +29 -0
- package/dist/src/memory/tools.js +22 -0
- package/dist/src/memory/tools.js.map +1 -0
- package/dist/src/memory/validation.d.ts +33 -0
- package/dist/src/memory/validation.js +159 -0
- package/dist/src/memory/validation.js.map +1 -0
- package/dist/src/npm-package/generate-patch.d.ts +23 -0
- package/dist/src/npm-package/generate-patch.js +88 -0
- package/dist/src/npm-package/generate-patch.js.map +1 -0
- package/dist/src/npm-package/patch-package-format.d.ts +43 -0
- package/dist/src/npm-package/patch-package-format.js +66 -0
- package/dist/src/npm-package/patch-package-format.js.map +1 -0
- package/dist/src/paths.d.ts +39 -0
- package/dist/src/paths.js +105 -0
- package/dist/src/paths.js.map +1 -0
- package/dist/src/pricing/cost.d.ts +182 -0
- package/dist/src/pricing/cost.js +215 -0
- package/dist/src/pricing/cost.js.map +1 -0
- package/dist/src/pricing/model-prices.d.ts +112 -0
- package/dist/src/pricing/model-prices.js +320 -0
- package/dist/src/pricing/model-prices.js.map +1 -0
- package/dist/src/sdk-patch-preflight.d.ts +23 -0
- package/dist/src/sdk-patch-preflight.js +71 -0
- package/dist/src/sdk-patch-preflight.js.map +1 -0
- package/dist/src/skills/builtin/commit-message/SKILL.md +45 -0
- package/dist/src/skills/builtin/commit-message/references/types.md +8 -0
- package/dist/src/skills/builtin/developer/SKILL.md +107 -0
- package/dist/src/skills/builtin/self-evolution-research/SKILL.md +150 -0
- package/dist/src/skills/builtin/self-evolution-research/scripts/roll-research-path.mjs +208 -0
- package/dist/src/skills/builtin/self-reflection/SKILL.md +172 -0
- package/dist/src/skills/builtin/self-reflection/references/reflection-template.md +90 -0
- package/dist/src/skills/builtin/self-reflection/scripts/locate-trajectory.mjs +175 -0
- package/dist/src/skills/loader.d.ts +26 -0
- package/dist/src/skills/loader.js +186 -0
- package/dist/src/skills/loader.js.map +1 -0
- package/dist/src/skills/plugin.d.ts +34 -0
- package/dist/src/skills/plugin.js +137 -0
- package/dist/src/skills/plugin.js.map +1 -0
- package/dist/src/skills/prompt.d.ts +8 -0
- package/dist/src/skills/prompt.js +214 -0
- package/dist/src/skills/prompt.js.map +1 -0
- package/dist/src/skills/resource-safety.d.ts +15 -0
- package/dist/src/skills/resource-safety.js +149 -0
- package/dist/src/skills/resource-safety.js.map +1 -0
- package/dist/src/tools/background-bash.d.ts +95 -0
- package/dist/src/tools/background-bash.js +639 -0
- package/dist/src/tools/background-bash.js.map +1 -0
- package/dist/src/tools/background-tail.d.ts +28 -0
- package/dist/src/tools/background-tail.js +75 -0
- package/dist/src/tools/background-tail.js.map +1 -0
- package/dist/src/tools/background-wait-contract.d.ts +4 -0
- package/dist/src/tools/background-wait-contract.js +7 -0
- package/dist/src/tools/background-wait-contract.js.map +1 -0
- package/dist/src/tools/file-editor-serial.d.ts +24 -0
- package/dist/src/tools/file-editor-serial.js +99 -0
- package/dist/src/tools/file-editor-serial.js.map +1 -0
- package/dist/src/tools/image-viewer.d.ts +43 -0
- package/dist/src/tools/image-viewer.js +256 -0
- package/dist/src/tools/image-viewer.js.map +1 -0
- package/dist/src/tools/update-plan.d.ts +30 -0
- package/dist/src/tools/update-plan.js +65 -0
- package/dist/src/tools/update-plan.js.map +1 -0
- package/dist/src/tools/web-fetch.d.ts +70 -0
- package/dist/src/tools/web-fetch.js +667 -0
- package/dist/src/tools/web-fetch.js.map +1 -0
- package/dist/src/trajectory/export.d.ts +31 -0
- package/dist/src/trajectory/export.js +116 -0
- package/dist/src/trajectory/export.js.map +1 -0
- package/dist/src/trajectory/fork.d.ts +19 -0
- package/dist/src/trajectory/fork.js +110 -0
- package/dist/src/trajectory/fork.js.map +1 -0
- package/dist/src/trajectory/memory-tool.d.ts +20 -0
- package/dist/src/trajectory/memory-tool.js +98 -0
- package/dist/src/trajectory/memory-tool.js.map +1 -0
- package/dist/src/trajectory/prompt-history.d.ts +62 -0
- package/dist/src/trajectory/prompt-history.js +256 -0
- package/dist/src/trajectory/prompt-history.js.map +1 -0
- package/dist/src/trajectory/reader.d.ts +21 -0
- package/dist/src/trajectory/reader.js +62 -0
- package/dist/src/trajectory/reader.js.map +1 -0
- package/dist/src/trajectory/record.d.ts +417 -0
- package/dist/src/trajectory/record.js +394 -0
- package/dist/src/trajectory/record.js.map +1 -0
- package/dist/src/trajectory/replay.d.ts +74 -0
- package/dist/src/trajectory/replay.js +285 -0
- package/dist/src/trajectory/replay.js.map +1 -0
- package/dist/src/trajectory/resume-recap.d.ts +43 -0
- package/dist/src/trajectory/resume-recap.js +68 -0
- package/dist/src/trajectory/resume-recap.js.map +1 -0
- package/dist/src/trajectory/search.d.ts +40 -0
- package/dist/src/trajectory/search.js +127 -0
- package/dist/src/trajectory/search.js.map +1 -0
- package/dist/src/trajectory/spend.d.ts +157 -0
- package/dist/src/trajectory/spend.js +264 -0
- package/dist/src/trajectory/spend.js.map +1 -0
- package/dist/src/trajectory/stream.d.ts +30 -0
- package/dist/src/trajectory/stream.js +30 -0
- package/dist/src/trajectory/stream.js.map +1 -0
- package/dist/src/trajectory/writer.d.ts +310 -0
- package/dist/src/trajectory/writer.js +636 -0
- package/dist/src/trajectory/writer.js.map +1 -0
- package/dist/src/tui/App.d.ts +109 -0
- package/dist/src/tui/App.js +2660 -0
- package/dist/src/tui/App.js.map +1 -0
- package/dist/src/tui/InputBox.d.ts +90 -0
- package/dist/src/tui/InputBox.js +129 -0
- package/dist/src/tui/InputBox.js.map +1 -0
- package/dist/src/tui/MarkdownText.d.ts +16 -0
- package/dist/src/tui/MarkdownText.js +117 -0
- package/dist/src/tui/MarkdownText.js.map +1 -0
- package/dist/src/tui/MessageList.d.ts +27 -0
- package/dist/src/tui/MessageList.js +61 -0
- package/dist/src/tui/MessageList.js.map +1 -0
- package/dist/src/tui/PermissionPrompt.d.ts +18 -0
- package/dist/src/tui/PermissionPrompt.js +114 -0
- package/dist/src/tui/PermissionPrompt.js.map +1 -0
- package/dist/src/tui/PlanChecklist.d.ts +7 -0
- package/dist/src/tui/PlanChecklist.js +12 -0
- package/dist/src/tui/PlanChecklist.js.map +1 -0
- package/dist/src/tui/QueuedMessages.d.ts +8 -0
- package/dist/src/tui/QueuedMessages.js +24 -0
- package/dist/src/tui/QueuedMessages.js.map +1 -0
- package/dist/src/tui/StartupScreen.d.ts +25 -0
- package/dist/src/tui/StartupScreen.js +51 -0
- package/dist/src/tui/StartupScreen.js.map +1 -0
- package/dist/src/tui/ToolCallPanel.d.ts +33 -0
- package/dist/src/tui/ToolCallPanel.js +112 -0
- package/dist/src/tui/ToolCallPanel.js.map +1 -0
- package/dist/src/tui/WelcomeHeader.d.ts +30 -0
- package/dist/src/tui/WelcomeHeader.js +69 -0
- package/dist/src/tui/WelcomeHeader.js.map +1 -0
- package/dist/src/tui/background-tool-presentation.d.ts +22 -0
- package/dist/src/tui/background-tool-presentation.js +209 -0
- package/dist/src/tui/background-tool-presentation.js.map +1 -0
- package/dist/src/tui/busy-suffix.d.ts +37 -0
- package/dist/src/tui/busy-suffix.js +39 -0
- package/dist/src/tui/busy-suffix.js.map +1 -0
- package/dist/src/tui/clipboard-image.d.ts +18 -0
- package/dist/src/tui/clipboard-image.js +109 -0
- package/dist/src/tui/clipboard-image.js.map +1 -0
- package/dist/src/tui/context-format.d.ts +43 -0
- package/dist/src/tui/context-format.js +71 -0
- package/dist/src/tui/context-format.js.map +1 -0
- package/dist/src/tui/copy-command.d.ts +68 -0
- package/dist/src/tui/copy-command.js +182 -0
- package/dist/src/tui/copy-command.js.map +1 -0
- package/dist/src/tui/edit-diff.d.ts +135 -0
- package/dist/src/tui/edit-diff.js +356 -0
- package/dist/src/tui/edit-diff.js.map +1 -0
- package/dist/src/tui/frame-budget.d.ts +351 -0
- package/dist/src/tui/frame-budget.js +446 -0
- package/dist/src/tui/frame-budget.js.map +1 -0
- package/dist/src/tui/help-format.d.ts +17 -0
- package/dist/src/tui/help-format.js +38 -0
- package/dist/src/tui/help-format.js.map +1 -0
- package/dist/src/tui/live-text.d.ts +51 -0
- package/dist/src/tui/live-text.js +154 -0
- package/dist/src/tui/live-text.js.map +1 -0
- package/dist/src/tui/markdown.d.ts +62 -0
- package/dist/src/tui/markdown.js +244 -0
- package/dist/src/tui/markdown.js.map +1 -0
- package/dist/src/tui/mcp-format.d.ts +28 -0
- package/dist/src/tui/mcp-format.js +67 -0
- package/dist/src/tui/mcp-format.js.map +1 -0
- package/dist/src/tui/path-completion.d.ts +119 -0
- package/dist/src/tui/path-completion.js +305 -0
- package/dist/src/tui/path-completion.js.map +1 -0
- package/dist/src/tui/permission-queue.d.ts +61 -0
- package/dist/src/tui/permission-queue.js +129 -0
- package/dist/src/tui/permission-queue.js.map +1 -0
- package/dist/src/tui/plan-format.d.ts +9 -0
- package/dist/src/tui/plan-format.js +30 -0
- package/dist/src/tui/plan-format.js.map +1 -0
- package/dist/src/tui/prompt-completion.d.ts +22 -0
- package/dist/src/tui/prompt-completion.js +46 -0
- package/dist/src/tui/prompt-completion.js.map +1 -0
- package/dist/src/tui/prompt-editor.d.ts +102 -0
- package/dist/src/tui/prompt-editor.js +379 -0
- package/dist/src/tui/prompt-editor.js.map +1 -0
- package/dist/src/tui/prompt-history-search.d.ts +53 -0
- package/dist/src/tui/prompt-history-search.js +123 -0
- package/dist/src/tui/prompt-history-search.js.map +1 -0
- package/dist/src/tui/prompt-queue.d.ts +58 -0
- package/dist/src/tui/prompt-queue.js +74 -0
- package/dist/src/tui/prompt-queue.js.map +1 -0
- package/dist/src/tui/prompt-recall.d.ts +74 -0
- package/dist/src/tui/prompt-recall.js +90 -0
- package/dist/src/tui/prompt-recall.js.map +1 -0
- package/dist/src/tui/react-environment.d.ts +11 -0
- package/dist/src/tui/react-environment.js +24 -0
- package/dist/src/tui/react-environment.js.map +1 -0
- package/dist/src/tui/rewind-search.d.ts +34 -0
- package/dist/src/tui/rewind-search.js +68 -0
- package/dist/src/tui/rewind-search.js.map +1 -0
- package/dist/src/tui/shell-command.d.ts +114 -0
- package/dist/src/tui/shell-command.js +310 -0
- package/dist/src/tui/shell-command.js.map +1 -0
- package/dist/src/tui/spend-advisory.d.ts +52 -0
- package/dist/src/tui/spend-advisory.js +64 -0
- package/dist/src/tui/spend-advisory.js.map +1 -0
- package/dist/src/tui/status-format.d.ts +120 -0
- package/dist/src/tui/status-format.js +192 -0
- package/dist/src/tui/status-format.js.map +1 -0
- package/dist/src/tui/subagent-format.d.ts +49 -0
- package/dist/src/tui/subagent-format.js +146 -0
- package/dist/src/tui/subagent-format.js.map +1 -0
- package/dist/src/tui/task-format.d.ts +29 -0
- package/dist/src/tui/task-format.js +87 -0
- package/dist/src/tui/task-format.js.map +1 -0
- package/dist/src/tui/terminal-bell.d.ts +20 -0
- package/dist/src/tui/terminal-bell.js +33 -0
- package/dist/src/tui/terminal-bell.js.map +1 -0
- package/dist/src/tui/tool-detail-presentation.d.ts +60 -0
- package/dist/src/tui/tool-detail-presentation.js +206 -0
- package/dist/src/tui/tool-detail-presentation.js.map +1 -0
- package/dist/src/tui/turn-state.d.ts +195 -0
- package/dist/src/tui/turn-state.js +548 -0
- package/dist/src/tui/turn-state.js.map +1 -0
- package/dist/src/tui/visual-language.d.ts +45 -0
- package/dist/src/tui/visual-language.js +57 -0
- package/dist/src/tui/visual-language.js.map +1 -0
- package/dist/src/version.d.ts +7 -0
- package/dist/src/version.js +38 -0
- package/dist/src/version.js.map +1 -0
- 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":"AAkBA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,QAAQ,EAAoB,MAAM,YAAY,CAAC;AAE9F;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AA+BrC,2FAA2F;AAC3F,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,KAAK,EAAE,CAAC;QACR,YAAY,EAAE,CAAC;QACf,KAAK,EAAE,SAAS;QAChB,MAAM,EAAE,CAAC;QACT,UAAU,EAAE,CAAC;QACb,SAAS,EAAE,CAAC;QACZ,mBAAmB,EAAE,EAAE;KACxB,CAAC;AACJ,CAAC;AAiBD;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAuB,EACvB,IAAwB;IAExB,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACtD,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC;QACtB,YAAY,EAAE,KAAK,CAAC,YAAY,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChE,KAAK,EACH,KAAK,KAAK,SAAS;YACjB,CAAC,CAAC,KAAK,CAAC,KAAK;YACb,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS;gBACzB,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACtC,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,UAAU,EAAE,KAAK,CAAC,UAAU,GAAG,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,mBAAmB,EAAE,CAAC,GAAG,KAAK,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,kBAAkB,CAAC;KACzF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,CAAC;IACtC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,SAAS;QAC1D,MAAM,SAAS,GAAG,KAA8C,CAAC;QACjE,IAAI,SAAS,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,IAAI,SAAS,CAAC,OAAO,KAAK,SAAS,CAAC,EAAE,CAAC;YAC3G,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAuB,EACvB,MAAiB;IAEjB,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3E,MAAM,SAAS,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IAC1D,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAuB,EAAE,MAAiB;IAC/E,MAAM,OAAO,GAAG,gBAAgB,CAAC,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3E,OAAO,CACL,GAAG,KAAK,CAAC,KAAK,kCAAkC,OAAO,KAAK;QAC5D,kBAAkB,KAAK,CAAC,UAAU,aAAa,KAAK,CAAC,SAAS,YAAY,KAAK,CAAC,MAAM,OAAO,CAC9F,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,GAAG,KAGlF,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACpC,iFAAiF;IACjF,+DAA+D;IAC/D,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,IAAI,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,qBAAqB,CAAC,CAAC;IAC5C,OAAO;QACL,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,MAAM;QACpB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC;QAC7D,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,KAAK,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC"}
|
|
@@ -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>;
|