strands-darwin 0.0.48 → 0.0.49

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 (49) hide show
  1. package/README.md +1 -1
  2. package/README.zh-CN.md +1 -1
  3. package/dist/patches/{@strands-agents+sdk+1.18.0.patch → @strands-agents+sdk+1.20.0.patch} +28 -52
  4. package/dist/src/agent/background-delegation.d.ts +1 -1
  5. package/dist/src/agent/background-delegation.js +3 -3
  6. package/dist/src/agent/cache-miss.d.ts +3 -3
  7. package/dist/src/agent/cache-miss.js +6 -3
  8. package/dist/src/agent/cache-miss.js.map +1 -1
  9. package/dist/src/agent/compact.js +1 -1
  10. package/dist/src/agent/cost.d.ts +1 -1
  11. package/dist/src/agent/runtime.d.ts +22 -5
  12. package/dist/src/agent/runtime.js +124 -7
  13. package/dist/src/agent/runtime.js.map +1 -1
  14. package/dist/src/agent/usage-state.d.ts +29 -0
  15. package/dist/src/agent/usage-state.js +131 -0
  16. package/dist/src/agent/usage-state.js.map +1 -0
  17. package/dist/src/agent/usage.d.ts +1 -1
  18. package/dist/src/headless-runner.js +10 -7
  19. package/dist/src/headless-runner.js.map +1 -1
  20. package/dist/src/headless.d.ts +1 -1
  21. package/dist/src/headless.js +1 -1
  22. package/dist/src/mcp/codegraph-preflight.js +8 -4
  23. package/dist/src/mcp/codegraph-preflight.js.map +1 -1
  24. package/dist/src/mcp/oauth-login.js +1 -1
  25. package/dist/src/mcp/oauth-login.js.map +1 -1
  26. package/dist/src/mcp/oauth-provider.d.ts +1 -2
  27. package/dist/src/mcp/oauth-provider.js +9 -0
  28. package/dist/src/mcp/oauth-provider.js.map +1 -1
  29. package/dist/src/mcp/oauth-store.d.ts +1 -2
  30. package/dist/src/mcp/oauth-store.js +9 -2
  31. package/dist/src/mcp/oauth-store.js.map +1 -1
  32. package/dist/src/mcp/prompts.d.ts +0 -18
  33. package/dist/src/mcp/prompts.js +25 -4
  34. package/dist/src/mcp/prompts.js.map +1 -1
  35. package/dist/src/mcp/web-search-empty-results.js +8 -4
  36. package/dist/src/mcp/web-search-empty-results.js.map +1 -1
  37. package/dist/src/npm-package/patch-package-format.d.ts +5 -5
  38. package/dist/src/npm-package/patch-package-format.js +4 -4
  39. package/dist/src/sdk-patch-preflight.js +1 -1
  40. package/dist/src/trajectory/record.d.ts +1 -1
  41. package/dist/src/tui/App.d.ts +1 -1
  42. package/dist/src/tui/App.js +7 -7
  43. package/dist/src/tui/App.js.map +1 -1
  44. package/dist/src/tui/task-wake.d.ts +1 -1
  45. package/dist/src/tui/task-wake.js +1 -1
  46. package/dist/src/tui/turn-state.d.ts +1 -1
  47. package/dist/src/tui/turn-state.js +10 -2
  48. package/dist/src/tui/turn-state.js.map +1 -1
  49. package/package.json +3 -2
package/README.md CHANGED
@@ -5,7 +5,7 @@
5
5
  <p>
6
6
  <a href="https://nodejs.org/"><img alt="Node.js >=22.0.0" src="https://img.shields.io/badge/Node.js-%3E%3D22.0.0-339933?logo=nodedotjs&amp;logoColor=white"></a>
7
7
  <a href="https://www.typescriptlang.org/"><img alt="TypeScript 7.0.2" src="https://img.shields.io/badge/TypeScript-7.0.2-3178C6?logo=typescript&amp;logoColor=white"></a>
8
- <a href="https://www.npmjs.com/package/@strands-agents/sdk"><img alt="Strands Agents SDK 1.18.0" src="https://img.shields.io/badge/Strands_Agents_SDK-1.18.0-5E4AE3"></a>
8
+ <a href="https://www.npmjs.com/package/@strands-agents/sdk"><img alt="Strands Agents SDK 1.20.0" src="https://img.shields.io/badge/Strands_Agents_SDK-1.20.0-5E4AE3"></a>
9
9
  <a href="https://spdx.org/licenses/ISC.html"><img alt="ISC License" src="https://img.shields.io/badge/License-ISC-blue.svg"></a>
10
10
  </p>
11
11
  <img src="docs/images/welcome.png" alt="darwin terminal welcome screen" width="100%">
package/README.zh-CN.md CHANGED
@@ -5,7 +5,7 @@
5
5
  <p>
6
6
  <a href="https://nodejs.org/"><img alt="Node.js >=22.0.0" src="https://img.shields.io/badge/Node.js-%3E%3D22.0.0-339933?logo=nodedotjs&amp;logoColor=white"></a>
7
7
  <a href="https://www.typescriptlang.org/"><img alt="TypeScript 7.0.2" src="https://img.shields.io/badge/TypeScript-7.0.2-3178C6?logo=typescript&amp;logoColor=white"></a>
8
- <a href="https://www.npmjs.com/package/@strands-agents/sdk"><img alt="Strands Agents SDK 1.18.0" src="https://img.shields.io/badge/Strands_Agents_SDK-1.18.0-5E4AE3"></a>
8
+ <a href="https://www.npmjs.com/package/@strands-agents/sdk"><img alt="Strands Agents SDK 1.20.0" src="https://img.shields.io/badge/Strands_Agents_SDK-1.20.0-5E4AE3"></a>
9
9
  <a href="https://spdx.org/licenses/ISC.html"><img alt="ISC License" src="https://img.shields.io/badge/License-ISC-blue.svg"></a>
10
10
  </p>
11
11
  <img src="docs/images/welcome.png" alt="darwin 终端欢迎界面" width="100%">
@@ -1,42 +1,20 @@
1
- diff --git a/node_modules/@strands-agents/sdk/dist/src/conversation-manager/compression/context-compression.js b/node_modules/@strands-agents/sdk/dist/src/conversation-manager/compression/context-compression.js
2
- index 84e3d1bb0bcd499d3dd2cd07c08baa79807ca79c..7e1c407bb04714309226c40b5daa00827799f477 100644
3
- --- a/node_modules/@strands-agents/sdk/dist/src/conversation-manager/compression/context-compression.js
4
- +++ b/node_modules/@strands-agents/sdk/dist/src/conversation-manager/compression/context-compression.js
5
- @@ -126,9 +126,16 @@ export async function generateSummary(messagesToSummarize, model, systemPrompt)
6
- if (!result?.done || !result.value) {
7
- throw new Error('Failed to generate summary: no response from model');
8
- }
9
- + // Thinking models include reasoning blocks in the summary response; a
10
- + // user-role message must never carry reasoning content (providers reject
11
- + // the request), so keep only the non-reasoning blocks.
12
- + const summaryContent = result.value.message.content.filter((block) => block.type !== 'reasoningBlock');
13
- + if (summaryContent.length === 0) {
14
- + throw new Error('Failed to generate summary: response contained no non-reasoning content');
15
- + }
16
- return new Message({
17
- role: 'user',
18
- - content: result.value.message.content,
19
- + content: summaryContent,
20
- });
21
- }
22
- /**
23
1
  diff --git a/node_modules/@strands-agents/sdk/dist/src/index.d.ts b/node_modules/@strands-agents/sdk/dist/src/index.d.ts
24
- index 416fa4a6d2a29417506588e05f95562bc7f3aa79..62e02b408b78ef5ade04ecd24478031331b6b1e4 100644
2
+ index 7595798e7151f873e43eddd9ccfdba0dd383b28e..23b5c61f9836ae4bb9af2716ad533b3000e18af7 100644
25
3
  --- a/node_modules/@strands-agents/sdk/dist/src/index.d.ts
26
4
  +++ b/node_modules/@strands-agents/sdk/dist/src/index.d.ts
27
- @@ -64,6 +64,7 @@ export { ConversationManager, type ProactiveCompressionConfig, type Conversation
5
+ @@ -65,6 +65,7 @@ export { ConversationManager, type ProactiveCompressionConfig, type Conversation
28
6
  export { NullConversationManager } from './conversation-manager/null-conversation-manager.js';
29
7
  export { SlidingWindowConversationManager, type SlidingWindowConversationManagerConfig, } from './conversation-manager/sliding-window-conversation-manager.js';
30
8
  export { SummarizingConversationManager, type SummarizingConversationManagerConfig, } from './conversation-manager/summarizing-conversation-manager.js';
31
9
  +export { DEFAULT_SUMMARIZATION_PROMPT } from './conversation-manager/compression/context-compression.js';
32
10
  export { configureLogging } from './logging/logger.js';
33
11
  export type { Logger } from './logging/types.js';
34
- export { type McpClientOptions, type McpListToolsOptions, type McpToolFilterCallback, type McpToolFilters, type McpToolMatcher, type McpClientConfig, type McpClientCredentials, type McpTransport, type McpCallToolOptions, type TasksConfig, type McpConnectionState, type McpLoadServersOptions, type McpServerConfig, type SerializableMcpToolFilters, McpClient, } from './mcp/index.js';
12
+ export { type McpClientOptions, type McpListToolsOptions, type McpToolFilterCallback, type McpToolFilters, type McpToolMatcher, type McpClientConfig, type McpClientCredentials, type McpTransport, type McpCallToolOptions, type TasksConfig, type McpConnectionState, type McpLoadServersOptions, type McpServerConfig, type SerializableMcpToolFilters, McpClient, McpTaskCancelledError, McpTaskFailedError, } from './mcp/index.js';
35
13
  diff --git a/node_modules/@strands-agents/sdk/dist/src/index.js b/node_modules/@strands-agents/sdk/dist/src/index.js
36
- index 1ffe683b6944318f8524c231674eabcf8428f89f..ea8dfa7ae5d5cfb3166a6e23afe3042d59b8973f 100644
14
+ index 29310747d3224a66b2f09607ce8f84122aebda70..05e66c2edd18e8c763d0885538bbfbe705a83be2 100644
37
15
  --- a/node_modules/@strands-agents/sdk/dist/src/index.js
38
16
  +++ b/node_modules/@strands-agents/sdk/dist/src/index.js
39
- @@ -53,6 +53,7 @@ export { ConversationManager, } from './conversation-manager/conversation-manage
17
+ @@ -55,6 +55,7 @@ export { ConversationManager, } from './conversation-manager/conversation-manage
40
18
  export { NullConversationManager } from './conversation-manager/null-conversation-manager.js';
41
19
  export { SlidingWindowConversationManager, } from './conversation-manager/sliding-window-conversation-manager.js';
42
20
  export { SummarizingConversationManager, } from './conversation-manager/summarizing-conversation-manager.js';
@@ -45,10 +23,10 @@ index 1ffe683b6944318f8524c231674eabcf8428f89f..ea8dfa7ae5d5cfb3166a6e23afe3042d
45
23
  export { configureLogging } from './logging/logger.js';
46
24
  // MCP Client types and implementations
47
25
  diff --git a/node_modules/@strands-agents/sdk/dist/src/models/anthropic.js b/node_modules/@strands-agents/sdk/dist/src/models/anthropic.js
48
- index ffbbb3d5d8a29ac0e21ffd2409658e1f69850492..ff1f3cac332a260fef809d318c11062de78ce3d8 100644
26
+ index d3b97dfe1f49f9c8251f4d74a2640b7684691f98..e747a7ac319ba38ce340aec08800dc751f10c4ee 100644
49
27
  --- a/node_modules/@strands-agents/sdk/dist/src/models/anthropic.js
50
28
  +++ b/node_modules/@strands-agents/sdk/dist/src/models/anthropic.js
51
- @@ -560,6 +560,11 @@ export class AnthropicModel extends Model {
29
+ @@ -682,6 +682,11 @@ export class AnthropicModel extends Model {
52
30
  };
53
31
  }
54
32
  case 'reasoningBlock':
@@ -61,7 +39,7 @@ index ffbbb3d5d8a29ac0e21ffd2409658e1f69850492..ff1f3cac332a260fef809d318c11062d
61
39
  return {
62
40
  type: 'thinking',
63
41
  diff --git a/node_modules/@strands-agents/sdk/dist/src/models/bedrock.js b/node_modules/@strands-agents/sdk/dist/src/models/bedrock.js
64
- index e9efcc8ba832b878ec4b1ec0350e8ce6bf5b0e5b..0ff2da8f0256a9a6fa0a1153e868cfa53c9104a8 100644
42
+ index a0077cfe424d3d67a90207b52f114162d743d2b5..ca209b98dc687402b4e13b8eef700812b3b7c63a 100644
65
43
  --- a/node_modules/@strands-agents/sdk/dist/src/models/bedrock.js
66
44
  +++ b/node_modules/@strands-agents/sdk/dist/src/models/bedrock.js
67
45
  @@ -944,6 +944,19 @@ export class BedrockModel extends Model {
@@ -114,10 +92,10 @@ index 17a473fe3bcdcc02e17cd95283c832d9021634c1..6e5cda23f672684b3926450322459279
114
92
  /**
115
93
  * Error patterns that indicate rate limiting.
116
94
  diff --git a/node_modules/@strands-agents/sdk/dist/src/models/openai/model.js b/node_modules/@strands-agents/sdk/dist/src/models/openai/model.js
117
- index e7db2ccc3d5d8cff7b27dbb5b5f46cdaf9a4de1b..d9881fb1d81a3cbd9e092591d8757023817ef6c7 100644
95
+ index 37291c025ed65317d80d5fa092621b7b678bafde..ba44c9120133ad75d1307b9684ffa82c0a0ef8cd 100644
118
96
  --- a/node_modules/@strands-agents/sdk/dist/src/models/openai/model.js
119
97
  +++ b/node_modules/@strands-agents/sdk/dist/src/models/openai/model.js
120
- @@ -196,7 +196,7 @@ export class OpenAIModel extends Model {
98
+ @@ -203,7 +203,7 @@ export class OpenAIModel extends Model {
121
99
  try {
122
100
  const request = formatResponsesRequest(this._config, messages, options, this.stateful);
123
101
  const stream = await this._client.responses.create(request, { signal: options?.cancelSignal });
@@ -127,14 +105,11 @@ index e7db2ccc3d5d8cff7b27dbb5b5f46cdaf9a4de1b..d9881fb1d81a3cbd9e092591d8757023
127
105
  for (const sdkEvent of mapResponsesEventToSDK(event, state, this.stateful, options?.modelState)) {
128
106
  yield sdkEvent;
129
107
  diff --git a/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.d.ts b/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.d.ts
130
- index e17f00ac284c1e3357d55205c57b431061141b55..655e065df9823e8897759978a46cac8b2bee9d79 100644
108
+ index a7b4edd12a5ac33277a5ad2c4bcea4c4d8c1ea7d..655e065df9823e8897759978a46cac8b2bee9d79 100644
131
109
  --- a/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.d.ts
132
110
  +++ b/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.d.ts
133
- @@ -52,15 +52,35 @@ export interface ResponsesStreamState {
134
- outputTokens: number;
135
- totalTokens: number;
136
- cacheReadInputTokens?: number;
137
- + cacheWriteInputTokens?: number;
111
+ @@ -55,13 +55,32 @@ export interface ResponsesStreamState {
112
+ cacheWriteInputTokens?: number;
138
113
  } | null;
139
114
  stopReason: StopReason;
140
115
  + /** darwin patch (SER-101): request model id that tags captured reasoning. */
@@ -168,7 +143,7 @@ index e17f00ac284c1e3357d55205c57b431061141b55..655e065df9823e8897759978a46cac8b
168
143
  * Maps a single Responses API stream event to zero or more SDK events. Mutates
169
144
  * `state` and, when `stateful` is `true`, writes `responseId` into `modelState`.
170
145
  diff --git a/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.js b/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.js
171
- index 9605eb256daa6aebf7dddea2f745d44bdf6f6970..76fb886e50ccbe1faa4bfb5208b82d64cbe84510 100644
146
+ index ddf156fe33b08dfb6a1dc265eb86f2fac31d9c53..c4cd19b5064de07722f88bb71874567061ed74ed 100644
172
147
  --- a/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.js
173
148
  +++ b/node_modules/@strands-agents/sdk/dist/src/models/openai/responses-adapter.js
174
149
  @@ -21,6 +21,72 @@ import { formatImageDataUrl, warnManagedParams as warnManagedParamsShared } from
@@ -308,7 +283,7 @@ index 9605eb256daa6aebf7dddea2f745d44bdf6f6970..76fb886e50ccbe1faa4bfb5208b82d64
308
283
  };
309
284
  }
310
285
  /**
311
- @@ -328,9 +408,13 @@ function mapResponsesUsage(usage) {
286
+ @@ -329,13 +409,13 @@ function mapResponsesUsage(usage) {
312
287
  totalTokens: usage.total_tokens,
313
288
  };
314
289
  const cached = usage.input_tokens_details?.cached_tokens;
@@ -316,14 +291,15 @@ index 9605eb256daa6aebf7dddea2f745d44bdf6f6970..76fb886e50ccbe1faa4bfb5208b82d64
316
291
  + if (typeof cached === 'number' && cached >= 0) {
317
292
  mapped.cacheReadInputTokens = cached;
318
293
  }
319
- + const cacheWrite = usage.input_tokens_details?.cache_write_tokens;
294
+ // GPT-5.6 reports cache writes here; the openai package's InputTokensDetails
295
+ // does not type the field yet, so read it through a narrow cast.
296
+ const cacheWrite = usage.input_tokens_details?.cache_write_tokens;
297
+ - if (typeof cacheWrite === 'number' && cacheWrite > 0) {
320
298
  + if (typeof cacheWrite === 'number' && cacheWrite >= 0) {
321
- + mapped.cacheWriteInputTokens = cacheWrite;
322
- + }
299
+ mapped.cacheWriteInputTokens = cacheWrite;
300
+ }
323
301
  return mapped;
324
- }
325
- function createResponsesStreamError(message, code) {
326
- @@ -359,22 +443,66 @@ export function mapResponsesEventToSDK(event, state, stateful, modelState) {
302
+ @@ -366,22 +446,66 @@ export function mapResponsesEventToSDK(event, state, stateful, modelState) {
327
303
  case 'response.output_text.delta': {
328
304
  events.push(...switchContent('text', state.dataType));
329
305
  state.dataType = 'text';
@@ -390,7 +366,7 @@ index 9605eb256daa6aebf7dddea2f745d44bdf6f6970..76fb886e50ccbe1faa4bfb5208b82d64
390
366
  case 'response.output_text.annotation.added': {
391
367
  // The SDK types `event.annotation` as `unknown` and doesn't export a
392
368
  // named annotation union, so we narrow structurally on the fields we use.
393
- @@ -388,6 +516,7 @@ export function mapResponsesEventToSDK(event, state, stateful, modelState) {
369
+ @@ -395,6 +519,7 @@ export function mapResponsesEventToSDK(event, state, stateful, modelState) {
394
370
  // a fresh TextBlock.
395
371
  events.push(...switchContent('citations', state.dataType));
396
372
  state.dataType = 'citations';
@@ -433,7 +409,7 @@ index b0223555c1f0410441546be860dbae824ac9857c..92ab47f4c8c1f5225c13dfd8a5e37324
433
409
  //# sourceMappingURL=plugin.d.ts.map
434
410
 
435
411
  diff --git a/node_modules/@strands-agents/sdk/dist/src/vended-plugins/context-offloader/plugin.js b/node_modules/@strands-agents/sdk/dist/src/vended-plugins/context-offloader/plugin.js
436
- index 69b6549df8bf55b39e34aaf2940cac2a7fbf0714..440965bdc2879f7c2755ace3cda9ab70b17c53e6 100644
412
+ index f1f7304b55d39dafb79b4e0a6796d29b9e795842..3170931a27b37d683e2c4f86c20c135a88df8447 100644
437
413
  --- a/node_modules/@strands-agents/sdk/dist/src/vended-plugins/context-offloader/plugin.js
438
414
  +++ b/node_modules/@strands-agents/sdk/dist/src/vended-plugins/context-offloader/plugin.js
439
415
  @@ -1,5 +1,5 @@
@@ -597,7 +573,7 @@ index 69b6549df8bf55b39e34aaf2940cac2a7fbf0714..440965bdc2879f7c2755ace3cda9ab70
597
573
  const contextLines = input.context_lines ?? 5;
598
574
  const lineRange = input.line_range ?? (!input.pattern ? { start: 1, end: Math.max(1, contextLines) } : undefined);
599
575
  return searchContent(text, { pattern: input.pattern, line_range: lineRange, context_lines: contextLines }, maxChars);
600
- @@ -339,40 +432,135 @@ export class ContextOffloader {
576
+ @@ -343,40 +436,135 @@ export class ContextOffloader {
601
577
  .filter((r) => r.ref)
602
578
  .map((r) => ` ${r.ref} (${r.description})`)
603
579
  .join('\n');
@@ -614,7 +590,7 @@ index 69b6549df8bf55b39e34aaf2940cac2a7fbf0714..440965bdc2879f7c2755ace3cda9ab70
614
590
  - guidance += 'If you need more detail, use your available tools to access specific data.';
615
591
  - }
616
592
  + const guidance = offloadGuidance(this._includeRetrievalTool);
617
- return (`[Offloaded: ${content.length} blocks, ~${tokenCount.toLocaleString()} tokens]\n` +
593
+ return (`[Offloaded: ${content.length} blocks, ~${tokenCount.toLocaleString('en-US')} tokens]\n` +
618
594
  `${guidance}\n\n` +
619
595
  `${preview}\n\n` +
620
596
  `[Stored references:]\n${refLines}`);
@@ -760,7 +736,7 @@ index 69b6549df8bf55b39e34aaf2940cac2a7fbf0714..440965bdc2879f7c2755ace3cda9ab70
760
736
  // Extract text preview from text/JSON blocks
761
737
  const textParts = [];
762
738
  for (const block of content) {
763
- @@ -382,22 +570,28 @@ export class ContextOffloader {
739
+ @@ -386,22 +574,28 @@ export class ContextOffloader {
764
740
  textParts.push(JSON.stringify(block.json, null, 2));
765
741
  }
766
742
  const fullText = textParts.join('\n');
@@ -801,7 +777,7 @@ index 69b6549df8bf55b39e34aaf2940cac2a7fbf0714..440965bdc2879f7c2755ace3cda9ab70
801
777
  }
802
778
  logger.debug(`tool_use_id=<${toolUseId}>, blocks=<${references.length}>, tokens=<${tokenCount}> | tool result offloaded`);
803
779
  // Build replacement content: preview text + media placeholders
804
- @@ -422,11 +616,32 @@ export class ContextOffloader {
780
+ @@ -426,11 +620,32 @@ export class ContextOffloader {
805
781
  newContent.push(new TextBlock(`[${label}, ${size} bytes${ref ? ` | ref: ${ref}` : ''}]`));
806
782
  }
807
783
  }
@@ -4,7 +4,7 @@ export declare const BACKGROUND_EXECUTION_FLAG = "_background_execution";
4
4
  /** The SDK's own management tool; parent-only, classified in `permission.ts`. */
5
5
  export declare const MANAGE_BACKGROUND_TASK_TOOL_NAME = "strands_manage_background_task";
6
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";
7
+ export declare const BACKGROUND_TASK_RESULT_TOOL_NAME = "strands_manage_background_task";
8
8
  export interface BackgroundDelegationConfigInput {
9
9
  /** The delegation tools the model may route to the background. */
10
10
  readonly delegationTools: readonly string[];
@@ -12,7 +12,7 @@
12
12
  * permission gate, plan-mode denial and the retry guard have already run —
13
13
  * `routeToolCall` strips the flag and `submitToolCall` returns an ack tool result
14
14
  * carrying a task id (`executor.js`, the `route === true` branch);
15
- * - delivers a finished task as one synthetic `strands_background_task_result`
15
+ * - delivers a finished task as one synthetic `strands_manage_background_task`
16
16
  * tool-use/tool-result pair through `continuations.addInput`, from two hooks: at
17
17
  * every `BeforeModelCallEvent` (`_deliverReady`, so a task that settled since the
18
18
  * last call rides the next request) and at `AfterInvocationEvent` — where, with
@@ -55,7 +55,7 @@ export const BACKGROUND_EXECUTION_FLAG = '_background_execution';
55
55
  /** The SDK's own management tool; parent-only, classified in `permission.ts`. */
56
56
  export const MANAGE_BACKGROUND_TASK_TOOL_NAME = 'strands_manage_background_task';
57
57
  /** The synthetic tool-use name the SDK uses when it delivers a finished task. */
58
- export const BACKGROUND_TASK_RESULT_TOOL_NAME = 'strands_background_task_result';
58
+ export const BACKGROUND_TASK_RESULT_TOOL_NAME = MANAGE_BACKGROUND_TASK_TOOL_NAME;
59
59
  /** First line of the SDK's dispatch acknowledgement (`submitToolCall`). */
60
60
  const ACK_FIRST_LINE = 'Background task dispatched.';
61
61
  const ACK_TASK_ID = /^Task ID: (\S+)$/mu;
@@ -100,7 +100,7 @@ export function backgroundDelegationDescriptionClause(completionWakes = false) {
100
100
  'need its result immediately (reads only): you get an acknowledgement at once and the ';
101
101
  return completionWakes
102
102
  ? lead +
103
- 'final report arrives as a strands_background_task_result tool result in the next turn ' +
103
+ 'final report arrives as a strands_manage_background_task tool result in the next turn ' +
104
104
  'that runs — you may end this turn; once the session is idle, one <task-notification> ' +
105
105
  'turn starts with the report attached.'
106
106
  : lead + 'final report is delivered before your next model call in this same turn.';
@@ -16,8 +16,8 @@
16
16
  * Advisory only, on the context-pressure row's terms: the verdict is printed on
17
17
  * existing reports (`/usage`, `/status`) and as one transcript notice before a
18
18
  * `/model` or `/effort` switch on a warm cache. Nothing is compacted, no second
19
- * threshold exists, no frame row, tick or channel is added, nothing is persisted or
20
- * recorded in the trajectory.
19
+ * threshold exists, no frame row, tick or channel is added. Historical verdicts
20
+ * are saved with session usage; cache warmth stays process-local, never in the trajectory.
21
21
  *
22
22
  * Invalidators, and one deliberate non-invalidator. A model switch, an effective
23
23
  * effort change and a compaction each change the request prefix (a different model
@@ -132,7 +132,7 @@ export declare class CacheMissTracker {
132
132
  * @param ttlMs the live TTL, read per call because `promptCacheTtl` is a model
133
133
  * field and `/model` can change it mid-session.
134
134
  */
135
- constructor(ttlMs: () => number, resumed: boolean);
135
+ constructor(ttlMs: () => number, resumed: boolean, restored?: CacheMissReport);
136
136
  /** Records that the session performed one invalidating event since the last call. */
137
137
  mark(event: CacheInvalidatingEvent): void;
138
138
  /** Folds one completed call in; returns the verdict for that call, if any. */
@@ -16,8 +16,8 @@
16
16
  * Advisory only, on the context-pressure row's terms: the verdict is printed on
17
17
  * existing reports (`/usage`, `/status`) and as one transcript notice before a
18
18
  * `/model` or `/effort` switch on a warm cache. Nothing is compacted, no second
19
- * threshold exists, no frame row, tick or channel is added, nothing is persisted or
20
- * recorded in the trajectory.
19
+ * threshold exists, no frame row, tick or channel is added. Historical verdicts
20
+ * are saved with session usage; cache warmth stays process-local, never in the trajectory.
21
21
  *
22
22
  * Invalidators, and one deliberate non-invalidator. A model switch, an effective
23
23
  * effort change and a compaction each change the request prefix (a different model
@@ -138,9 +138,12 @@ export class CacheMissTracker {
138
138
  * @param ttlMs the live TTL, read per call because `promptCacheTtl` is a model
139
139
  * field and `/model` can change it mid-session.
140
140
  */
141
- constructor(ttlMs, resumed) {
141
+ constructor(ttlMs, resumed, restored) {
142
142
  this.ttlMs = ttlMs;
143
143
  this.firstCallAfterResume = resumed;
144
+ // Keep historical verdicts, not a stale cache-warmth claim across processes.
145
+ this.misses = restored?.misses ?? 0;
146
+ this.lastMiss = restored?.lastMiss;
144
147
  }
145
148
  /** Records that the session performed one invalidating event since the last call. */
146
149
  mark(event) {
@@ -1 +1 @@
1
- {"version":3,"file":"cache-miss.js","sourceRoot":"","sources":["../../../src/agent/cache-miss.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"cache-miss.js","sourceRoot":"","sources":["../../../src/agent/cache-miss.ts"],"names":[],"mappings":"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"}
@@ -1,5 +1,5 @@
1
1
  // `DEFAULT_SUMMARIZATION_PROMPT` reaches the package root only through the pinned
2
- // SDK patch (`patches/@strands-agents__sdk@1.18.0.patch`, `dist/src/index.*`
2
+ // SDK patch (`patches/@strands-agents__sdk@1.20.0.patch`, `dist/src/index.*`
3
3
  // hunks): the SDK declares it in a module its `exports` map does not expose.
4
4
  // Never copy the string here — a copy would drift from what the SDK sends when
5
5
  // no focus is given.
@@ -20,7 +20,7 @@ import { type CostBucket, type CostShare, type ModelPriceLookup } from '../prici
20
20
  import { type UsageTotals } from './usage.js';
21
21
  export { COST_BASIS_LABEL, describePricingSource, describeSessionCost, estimateCost, formatModelList, formatUsd, formatUsdNumber, MAX_COST_MODEL_CHARS, sessionCost, sessionCostFields, type CostBucket, type CostBuckets, type CostEstimate, type CostShare, type MissingCostBucket, type MissingModelBucket, type ModelPriceLookup, type ModelRates, type SessionCost, type UnpricedModel, } from '../pricing/cost.js';
22
22
  /**
23
- * One model's share of this process's meter: the counters it incurred, the config
23
+ * One model's share of the session's meter: the counters it incurred, the config
24
24
  * that projects them into buckets (provider/API decide the split), and what the
25
25
  * price cache says about it. `runtime.modelShares` is a list of these.
26
26
  */
@@ -417,6 +417,15 @@ export declare class AgentRuntime {
417
417
  /** What the live model can cache. Recomputed on `/model`, like the plan above. */
418
418
  private promptCachePlan;
419
419
  private lastTurnDelta;
420
+ /** The resumed prefix; the SDK's untouched meter counts only this Agent's lifetime. */
421
+ private restoredUsage;
422
+ private restoredChildUsage;
423
+ private restoredAccounting;
424
+ /** Headless receipts remain process-scoped, even when /usage restores session totals. */
425
+ private runCallStatsState;
426
+ private activeTurnBefore;
427
+ /** False for legacy/damaged snapshots whose earlier spend cannot be recovered exactly. */
428
+ private usageHistoryComplete;
420
429
  /**
421
430
  * Completed turns' meter deltas, tallied under the config in effect for each turn —
422
431
  * the same `before` snapshot and config the trajectory's turn meter reads, so the
@@ -748,7 +757,7 @@ export declare class AgentRuntime {
748
757
  */
749
758
  get modelPrice(): ModelPriceLookup;
750
759
  /**
751
- * This process's meter split per model, each share with the config that projects
760
+ * This session's meter split per model, each share with the config that projects
752
761
  * it and what the price cache says about it — what `/status`, `/usage` and the
753
762
  * headless `cost:` record price, each model at its own rates.
754
763
  *
@@ -788,6 +797,13 @@ export declare class AgentRuntime {
788
797
  * describe a model that is no longer there.
789
798
  */
790
799
  changeModel(target: ModelChoice): Promise<ModelChangeResult>;
800
+ /** Whether the session prefix is accounted for, rather than a legacy/damaged gap. */
801
+ get hasCompleteUsageHistory(): boolean;
802
+ /** A read-only projection for run-scoped headless receipts, not lifetime totals. */
803
+ get runAccounting(): Pick<AgentRuntime, 'usage' | 'childUsage' | 'sessionUsage' | 'modelShares' | 'callStats'>;
804
+ private restoreSessionUsage;
805
+ /** Stages counters before the SDK's normal invocation snapshot, never its loop or meter. */
806
+ private stageSessionUsage;
791
807
  /**
792
808
  * Token totals for every model call this agent has made so far.
793
809
  *
@@ -797,11 +813,12 @@ export declare class AgentRuntime {
797
813
  * running total and is readable between turns, including after a cancelled one
798
814
  * that never produced an `agentResultEvent`.
799
815
  *
800
- * Counts this process only. Sessions persist messages, not metrics, so a
801
- * `--resume`d session starts from zero however much it spent before — callers
802
- * that show these numbers should say so.
816
+ * The persisted session prefix is added to this Agent's lifetime meter on
817
+ * resume. The SDK meter itself is never changed, so per-turn subtraction and
818
+ * repeated resumes cannot count the restored prefix twice.
803
819
  */
804
820
  get usage(): UsageTotals;
821
+ private get runUsage();
805
822
  /**
806
823
  * Token delta for the most recently completed turn, or `undefined` before any
807
824
  * turn has finished. A cancelled turn still produces a delta covering whatever
@@ -876,7 +893,7 @@ export declare class AgentRuntime {
876
893
  */
877
894
  get callStats(): SessionCallStats | undefined;
878
895
  /**
879
- * Token totals for this run's child agents (subagent dispatches and workflow
896
+ * Token totals for this session's child agents (subagent dispatches and workflow
880
897
  * nodes), summed over the dispatch registry — running children read live,
881
898
  * finished ones report their frozen terminal reading, and a cancelled or
882
899
  * failed child still counts what it spent. `dispatches` counts only the
@@ -5,7 +5,7 @@
5
5
  * raw event stream to whatever is driving it. Callers (the dev REPL now, Ink
6
6
  * later) decide how to render.
7
7
  */
8
- import { Agent, AfterToolCallEvent, BeforeToolCallEvent, BeforeToolsEvent, ToolResultEvent, HookOrder, BeforeInvocationEvent, SummarizingConversationManager, TextBlock } from '@strands-agents/sdk';
8
+ import { Agent, AfterInvocationEvent, AfterToolCallEvent, BeforeToolCallEvent, BeforeToolsEvent, ToolResultEvent, HookOrder, BeforeInvocationEvent, SummarizingConversationManager, TextBlock } from '@strands-agents/sdk';
9
9
  import { makeFileEditor } from '@strands-agents/sdk/vended-tools/file-editor';
10
10
  import { httpRequest } from '@strands-agents/sdk/vended-tools/http-request';
11
11
  import { ContextOffloader } from '@strands-agents/sdk/vended-plugins/context-offloader';
@@ -66,6 +66,7 @@ import { readSessionLabel } from './session-label.js';
66
66
  import { writeSessionLabel } from './session-label-write.js';
67
67
  import { createModelClassifier } from './safety-classifier.js';
68
68
  import { createSessionManager, diagnosticsPath, resolveSession, sessionPaths, trajectoryPath, writePointer, } from './session.js';
69
+ import { emptySessionUsageState, readSessionUsageState, SESSION_USAGE_KEY } from './usage-state.js';
69
70
  import { setSdkVerboseSink } from './sdk-logging.js';
70
71
  import { loadSystemPrompt } from './system-prompt.js';
71
72
  import { applyWorkingContext, buildWorkingContext } from './working-context.js';
@@ -197,6 +198,15 @@ export class AgentRuntime {
197
198
  /** What the live model can cache. Recomputed on `/model`, like the plan above. */
198
199
  promptCachePlan;
199
200
  lastTurnDelta = undefined;
201
+ /** The resumed prefix; the SDK's untouched meter counts only this Agent's lifetime. */
202
+ restoredUsage = { inputTokens: 0, outputTokens: 0 };
203
+ restoredChildUsage;
204
+ restoredAccounting;
205
+ /** Headless receipts remain process-scoped, even when /usage restores session totals. */
206
+ runCallStatsState = emptyCallStats();
207
+ activeTurnBefore;
208
+ /** False for legacy/damaged snapshots whose earlier spend cannot be recovered exactly. */
209
+ usageHistoryComplete = true;
200
210
  /**
201
211
  * Completed turns' meter deltas, tallied under the config in effect for each turn —
202
212
  * the same `before` snapshot and config the trajectory's turn meter reads, so the
@@ -638,6 +648,8 @@ export class AgentRuntime {
638
648
  });
639
649
  if (!restored)
640
650
  throw new Error('The selected rewind checkpoint no longer exists.');
651
+ // A branch is a new accounting session, not a refund of its source's spend.
652
+ agent.appState.set(SESSION_USAGE_KEY, JSON.parse(JSON.stringify(emptySessionUsageState())));
641
653
  }
642
654
  // Older summarizer versions copied reasoning blocks into the user-role
643
655
  // summary message; providers reject any request containing it. Repair the
@@ -850,6 +862,11 @@ export class AgentRuntime {
850
862
  trajectoryFile: trajectory?.status.file,
851
863
  diagnosticsFile: diagnosticsLog?.path,
852
864
  }, options);
865
+ if (session.restoreRequested && options.rewindRestore === undefined)
866
+ runtime.restoreSessionUsage();
867
+ // Counter-only appState is captured by the ordinary SDK autosave. Lower priority
868
+ // runs first even for After hooks, before SessionManager's default-order save.
869
+ agent.addHook(AfterInvocationEvent, () => runtime.stageSessionUsage(), { order: HookOrder.SDK_FIRST });
853
870
  runtime.label = await readSessionLabel(options.projectRoot, session.sessionId);
854
871
  runtime.mcpPromptDiscovery = mcpPromptDiscovery;
855
872
  runtime.mcpPrompts = mcpPrompts;
@@ -938,6 +955,7 @@ export class AgentRuntime {
938
955
  let naturallyCompleted = false;
939
956
  let uploadTurn;
940
957
  let streamStarted = false;
958
+ this.activeTurnBefore = before;
941
959
  try {
942
960
  // A multimodal turn's durable text is the literal submitted prompt. Expanded
943
961
  // command text and held shell reports still reach the model, but image bytes
@@ -1024,6 +1042,7 @@ export class AgentRuntime {
1024
1042
  this.terminalDelivery.closeTurn(sealed && completed);
1025
1043
  this.lastTurnDelta = deltaUsage(before, this.usage);
1026
1044
  this.tallyTurnUsage(turnConfig, this.lastTurnDelta);
1045
+ this.activeTurnBefore = undefined;
1027
1046
  }
1028
1047
  }
1029
1048
  /**
@@ -1434,7 +1453,7 @@ export class AgentRuntime {
1434
1453
  return this.modelPrices.lookup(this.liveConfig);
1435
1454
  }
1436
1455
  /**
1437
- * This process's meter split per model, each share with the config that projects
1456
+ * This session's meter split per model, each share with the config that projects
1438
1457
  * it and what the price cache says about it — what `/status`, `/usage` and the
1439
1458
  * headless `cost:` record price, each model at its own rates.
1440
1459
  *
@@ -1541,6 +1560,94 @@ export class AgentRuntime {
1541
1560
  saved: saveEnabledModel(this.projectRoot, target.index),
1542
1561
  };
1543
1562
  }
1563
+ /** Whether the session prefix is accounted for, rather than a legacy/damaged gap. */
1564
+ get hasCompleteUsageHistory() {
1565
+ return this.usageHistoryComplete;
1566
+ }
1567
+ /** A read-only projection for run-scoped headless receipts, not lifetime totals. */
1568
+ get runAccounting() {
1569
+ const usage = this.runUsage;
1570
+ const childUsage = this.subagentDispatches.totalUsage();
1571
+ const prefix = this.restoredAccounting?.models;
1572
+ const shares = prefix === undefined ? this.modelShares : this.modelShares.flatMap((share) => {
1573
+ const before = prefix.find((entry) => entry.provider === share.config.provider && entry.model === share.config.model)?.usage;
1574
+ const delta = deltaUsage(before ?? { inputTokens: 0, outputTokens: 0 }, share.usage);
1575
+ // A historical cache counter is not evidence this process reported that metric.
1576
+ if (usage.cacheReadInputTokens === undefined)
1577
+ delete delta.cacheReadInputTokens;
1578
+ if (usage.cacheWriteInputTokens === undefined)
1579
+ delete delta.cacheWriteInputTokens;
1580
+ if (delta.inputTokens === 0 && delta.outputTokens === 0 &&
1581
+ (delta.cacheReadInputTokens ?? 0) === 0 && (delta.cacheWriteInputTokens ?? 0) === 0)
1582
+ return [];
1583
+ return [{ ...share, usage: delta }];
1584
+ });
1585
+ return {
1586
+ usage, childUsage,
1587
+ sessionUsage: childUsage === undefined ? usage : sumUsage([usage, childUsage.usage]),
1588
+ modelShares: shares.length === 0 ? [{ config: this.liveConfig, usage, lookup: this.modelPrice }] : shares,
1589
+ callStats: this.callStatsBroken || this.runCallStatsState.calls === 0 ? undefined : this.runCallStatsState,
1590
+ };
1591
+ }
1592
+ restoreSessionUsage() {
1593
+ const saved = readSessionUsageState(this.agent.appState.get(SESSION_USAGE_KEY));
1594
+ if (saved === undefined) {
1595
+ this.usageHistoryComplete = false;
1596
+ return;
1597
+ }
1598
+ this.restoredAccounting = saved;
1599
+ this.usageHistoryComplete = saved.historyComplete;
1600
+ this.restoredUsage = saved.usage;
1601
+ this.lastTurnDelta = saved.lastTurn;
1602
+ this.restoredChildUsage = saved.children;
1603
+ for (const entry of saved.models) {
1604
+ // Save only projection identity, never credentials or the old full config.
1605
+ const config = { ...this.liveConfig, provider: entry.provider, model: entry.model };
1606
+ delete config.openaiApi;
1607
+ if (entry.openaiApi !== undefined)
1608
+ config.openaiApi = entry.openaiApi;
1609
+ this.turnUsageByModel.push({ config, usage: entry.usage });
1610
+ }
1611
+ if (saved.callStats === null)
1612
+ this.callStatsBroken = true;
1613
+ else
1614
+ this.callStatsState = saved.callStats;
1615
+ if (saved.cacheMisses === null)
1616
+ this.cacheMissesBroken = true;
1617
+ else
1618
+ this.cacheMisses = new CacheMissTracker(() => promptCacheTtlMs(this.promptCachePlan.ttl), true, saved.cacheMisses);
1619
+ }
1620
+ /** Stages counters before the SDK's normal invocation snapshot, never its loop or meter. */
1621
+ stageSessionUsage() {
1622
+ try {
1623
+ const lastTurn = this.activeTurnBefore === undefined
1624
+ ? this.lastTurnDelta : deltaUsage(this.activeTurnBefore, this.usage);
1625
+ const children = this.childUsage;
1626
+ const value = {
1627
+ version: 1,
1628
+ historyComplete: this.usageHistoryComplete,
1629
+ usage: this.usage,
1630
+ ...(lastTurn === undefined ? {} : { lastTurn }),
1631
+ models: this.modelShares.map(({ config, usage }) => ({
1632
+ provider: config.provider, model: config.model, usage,
1633
+ ...(config.openaiApi === undefined ? {} : { openaiApi: config.openaiApi }),
1634
+ })),
1635
+ callStats: this.callStatsBroken ? null : this.callStatsState,
1636
+ cacheMisses: this.cacheMissesBroken ? null : this.cacheMisses.report(),
1637
+ ...(children === undefined ? {} : { children }),
1638
+ };
1639
+ const bounded = readSessionUsageState(value);
1640
+ if (bounded === undefined)
1641
+ throw new Error('Session usage exceeded its bounded counter schema.');
1642
+ // StateStore rejects explicit undefined; JSON omission preserves unknown metrics.
1643
+ this.agent.appState.set(SESSION_USAGE_KEY, JSON.parse(JSON.stringify(bounded)));
1644
+ }
1645
+ catch {
1646
+ // Do not save stale totals or replace an invocation's original failure.
1647
+ this.agent.appState.delete(SESSION_USAGE_KEY);
1648
+ this.diagnosticsLog?.notice('session usage checkpoint unavailable', 'warn');
1649
+ }
1650
+ }
1544
1651
  /**
1545
1652
  * Token totals for every model call this agent has made so far.
1546
1653
  *
@@ -1550,11 +1657,14 @@ export class AgentRuntime {
1550
1657
  * running total and is readable between turns, including after a cancelled one
1551
1658
  * that never produced an `agentResultEvent`.
1552
1659
  *
1553
- * Counts this process only. Sessions persist messages, not metrics, so a
1554
- * `--resume`d session starts from zero however much it spent before — callers
1555
- * that show these numbers should say so.
1660
+ * The persisted session prefix is added to this Agent's lifetime meter on
1661
+ * resume. The SDK meter itself is never changed, so per-turn subtraction and
1662
+ * repeated resumes cannot count the restored prefix twice.
1556
1663
  */
1557
1664
  get usage() {
1665
+ return sumUsage([this.restoredUsage, this.runUsage]);
1666
+ }
1667
+ get runUsage() {
1558
1668
  const usage = this.agent.metrics.accumulatedUsage;
1559
1669
  return {
1560
1670
  inputTokens: usage.inputTokens,
@@ -1610,6 +1720,7 @@ export class AgentRuntime {
1610
1720
  if (stopData === undefined)
1611
1721
  return;
1612
1722
  this.callStatsState = recordCompletedCall(this.callStatsState, stopData);
1723
+ this.runCallStatsState = recordCompletedCall(this.runCallStatsState, stopData);
1613
1724
  }
1614
1725
  catch {
1615
1726
  this.callStatsBroken = true;
@@ -1714,7 +1825,7 @@ export class AgentRuntime {
1714
1825
  return this.callStatsState;
1715
1826
  }
1716
1827
  /**
1717
- * Token totals for this run's child agents (subagent dispatches and workflow
1828
+ * Token totals for this session's child agents (subagent dispatches and workflow
1718
1829
  * nodes), summed over the dispatch registry — running children read live,
1719
1830
  * finished ones report their frozen terminal reading, and a cancelled or
1720
1831
  * failed child still counts what it spent. `dispatches` counts only the
@@ -1723,7 +1834,13 @@ export class AgentRuntime {
1723
1834
  * indistinguishable from before children were counted at all.
1724
1835
  */
1725
1836
  get childUsage() {
1726
- return this.subagentDispatches.totalUsage();
1837
+ const current = this.subagentDispatches.totalUsage();
1838
+ const restored = this.restoredChildUsage;
1839
+ if (restored === undefined)
1840
+ return current;
1841
+ if (current === undefined)
1842
+ return restored;
1843
+ return { dispatches: restored.dispatches + current.dispatches, usage: sumUsage([restored.usage, current.usage]) };
1727
1844
  }
1728
1845
  /**
1729
1846
  * Everything this session has spent: the parent meter ({@link usage}) plus