strands-darwin 0.0.32 → 0.0.34

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 (117) hide show
  1. package/README.md +3 -1
  2. package/README.zh-CN.md +3 -1
  3. package/dist/src/agent/background-delegation.d.ts +69 -11
  4. package/dist/src/agent/background-delegation.js +156 -28
  5. package/dist/src/agent/background-delegation.js.map +1 -1
  6. package/dist/src/agent/cache-miss.d.ts +143 -0
  7. package/dist/src/agent/cache-miss.js +182 -0
  8. package/dist/src/agent/cache-miss.js.map +1 -0
  9. package/dist/src/agent/compact.d.ts +28 -0
  10. package/dist/src/agent/compact.js +34 -0
  11. package/dist/src/agent/compact.js.map +1 -1
  12. package/dist/src/agent/context-breakdown.d.ts +109 -0
  13. package/dist/src/agent/context-breakdown.js +116 -0
  14. package/dist/src/agent/context-breakdown.js.map +1 -0
  15. package/dist/src/agent/instructions.d.ts +1 -1
  16. package/dist/src/agent/instructions.js.map +1 -1
  17. package/dist/src/agent/permission-rules.d.ts +81 -2
  18. package/dist/src/agent/permission-rules.js +226 -6
  19. package/dist/src/agent/permission-rules.js.map +1 -1
  20. package/dist/src/agent/permission.d.ts +116 -2
  21. package/dist/src/agent/permission.js +201 -26
  22. package/dist/src/agent/permission.js.map +1 -1
  23. package/dist/src/agent/prompt-cache.d.ts +12 -3
  24. package/dist/src/agent/prompt-cache.js +12 -3
  25. package/dist/src/agent/prompt-cache.js.map +1 -1
  26. package/dist/src/agent/runtime.d.ts +141 -1
  27. package/dist/src/agent/runtime.js +259 -13
  28. package/dist/src/agent/runtime.js.map +1 -1
  29. package/dist/src/agent/task-terminal-delivery.d.ts +43 -0
  30. package/dist/src/agent/task-terminal-delivery.js +115 -0
  31. package/dist/src/agent/task-terminal-delivery.js.map +1 -0
  32. package/dist/src/agents/child-recipe.d.ts +9 -1
  33. package/dist/src/agents/child-recipe.js +2 -0
  34. package/dist/src/agents/child-recipe.js.map +1 -1
  35. package/dist/src/agents/dispatch-registry.d.ts +18 -0
  36. package/dist/src/agents/dispatch-registry.js +2 -0
  37. package/dist/src/agents/dispatch-registry.js.map +1 -1
  38. package/dist/src/agents/retained-children.d.ts +101 -0
  39. package/dist/src/agents/retained-children.js +101 -0
  40. package/dist/src/agents/retained-children.js.map +1 -0
  41. package/dist/src/agents/subagent-tool.d.ts +56 -1
  42. package/dist/src/agents/subagent-tool.js +148 -10
  43. package/dist/src/agents/subagent-tool.js.map +1 -1
  44. package/dist/src/agents/workflow-tool.d.ts +2 -0
  45. package/dist/src/agents/workflow-tool.js +1 -1
  46. package/dist/src/agents/workflow-tool.js.map +1 -1
  47. package/dist/src/cli-doctor.js +3 -1
  48. package/dist/src/cli-doctor.js.map +1 -1
  49. package/dist/src/cli-main.js +14 -3
  50. package/dist/src/cli-main.js.map +1 -1
  51. package/dist/src/commands/custom-commands.js +5 -4
  52. package/dist/src/commands/custom-commands.js.map +1 -1
  53. package/dist/src/config.d.ts +57 -6
  54. package/dist/src/config.js +43 -16
  55. package/dist/src/config.js.map +1 -1
  56. package/dist/src/headless-protocol.d.ts +1 -1
  57. package/dist/src/headless-runner.js +7 -2
  58. package/dist/src/headless-runner.js.map +1 -1
  59. package/dist/src/hooks/tool-hooks.js +10 -6
  60. package/dist/src/hooks/tool-hooks.js.map +1 -1
  61. package/dist/src/skills/builtin/self-evolution-research/SKILL.md +14 -1
  62. package/dist/src/skills/prompt.d.ts +17 -0
  63. package/dist/src/skills/prompt.js +20 -0
  64. package/dist/src/skills/prompt.js.map +1 -1
  65. package/dist/src/tools/background-bash.d.ts +11 -2
  66. package/dist/src/tools/background-bash.js +11 -5
  67. package/dist/src/tools/background-bash.js.map +1 -1
  68. package/dist/src/tools/background-tail.d.ts +1 -0
  69. package/dist/src/tools/background-tail.js +2 -1
  70. package/dist/src/tools/background-tail.js.map +1 -1
  71. package/dist/src/tools/background-wait-contract.d.ts +7 -0
  72. package/dist/src/tools/background-wait-contract.js +17 -0
  73. package/dist/src/tools/background-wait-contract.js.map +1 -1
  74. package/dist/src/trajectory/record.d.ts +212 -2
  75. package/dist/src/trajectory/record.js +138 -0
  76. package/dist/src/trajectory/record.js.map +1 -1
  77. package/dist/src/trajectory/replay.d.ts +34 -1
  78. package/dist/src/trajectory/replay.js +148 -4
  79. package/dist/src/trajectory/replay.js.map +1 -1
  80. package/dist/src/trajectory/resume-recap.js +10 -3
  81. package/dist/src/trajectory/resume-recap.js.map +1 -1
  82. package/dist/src/trajectory/spend.d.ts +14 -1
  83. package/dist/src/trajectory/spend.js +40 -6
  84. package/dist/src/trajectory/spend.js.map +1 -1
  85. package/dist/src/trajectory/writer.d.ts +57 -6
  86. package/dist/src/trajectory/writer.js +141 -9
  87. package/dist/src/trajectory/writer.js.map +1 -1
  88. package/dist/src/tui/App.d.ts +8 -4
  89. package/dist/src/tui/App.js +302 -55
  90. package/dist/src/tui/App.js.map +1 -1
  91. package/dist/src/tui/background-tool-presentation.js +2 -2
  92. package/dist/src/tui/background-tool-presentation.js.map +1 -1
  93. package/dist/src/tui/context-format.d.ts +16 -0
  94. package/dist/src/tui/context-format.js +41 -0
  95. package/dist/src/tui/context-format.js.map +1 -1
  96. package/dist/src/tui/prompt-queue.d.ts +52 -8
  97. package/dist/src/tui/prompt-queue.js +68 -8
  98. package/dist/src/tui/prompt-queue.js.map +1 -1
  99. package/dist/src/tui/status-format.d.ts +35 -16
  100. package/dist/src/tui/status-format.js +67 -8
  101. package/dist/src/tui/status-format.js.map +1 -1
  102. package/dist/src/tui/subagent-format.d.ts +8 -0
  103. package/dist/src/tui/subagent-format.js +24 -1
  104. package/dist/src/tui/subagent-format.js.map +1 -1
  105. package/dist/src/tui/task-wake.d.ts +75 -0
  106. package/dist/src/tui/task-wake.js +201 -0
  107. package/dist/src/tui/task-wake.js.map +1 -0
  108. package/dist/src/tui/terminal-notify.d.ts +40 -0
  109. package/dist/src/tui/terminal-notify.js +136 -0
  110. package/dist/src/tui/terminal-notify.js.map +1 -0
  111. package/dist/src/tui/terminal-title.d.ts +94 -0
  112. package/dist/src/tui/terminal-title.js +121 -0
  113. package/dist/src/tui/terminal-title.js.map +1 -0
  114. package/dist/src/tui/turn-state.d.ts +10 -1
  115. package/dist/src/tui/turn-state.js +17 -1
  116. package/dist/src/tui/turn-state.js.map +1 -1
  117. package/package.json +1 -1
@@ -1,6 +1,7 @@
1
1
  import type { AgentStreamEvent, ImageBlock, McpClient } from '@strands-agents/sdk';
2
2
  import { type CompactResult } from './compact.js';
3
3
  import { DiagnosticsLog, type DiagnosticsStatus } from './diagnostics.js';
4
+ import { type BackgroundDelegationListener, type BackgroundDelegationStatus } from './background-delegation.js';
4
5
  import { type ModelRetryOutcome, type RetryWaitState } from './model-retry.js';
5
6
  import { type SubagentCancelResult, type SubagentDispatchListener, type SubagentDispatchProgressListener, type SubagentDispatchStatus } from '../agents/dispatch-registry.js';
6
7
  import { type ExpandedCustomCommand } from '../commands/custom-commands.js';
@@ -13,7 +14,9 @@ import { type ExpandedSkillCommand } from '../skills/plugin.js';
13
14
  import { type MemoryCommandResult } from '../memory/command.js';
14
15
  import { MemoryToolController } from '../memory/controller.js';
15
16
  import type { MemoryStatus } from '../memory/store.js';
17
+ import type { ContextCompactedEntry, TaskNotificationFields } from '../trajectory/record.js';
16
18
  import { type RecorderOptions, type TrajectoryStatus } from '../trajectory/writer.js';
19
+ import { type ContextBreakdown } from './context-breakdown.js';
17
20
  import { type ProjectInstructionsSummary } from './instructions.js';
18
21
  import { type AllowRuleEntry, type ApprovalMode, type PermissionBridge, type PermissionModeChange } from './permission.js';
19
22
  import { type PromptCachePlan } from './prompt-cache.js';
@@ -23,6 +26,7 @@ import { type ThinkingEffort, type ThinkingPlan } from './thinking.js';
23
26
  import { type RewindCatalogue, type RewindCheckpoint } from './rewind.js';
24
27
  import { type UsageTotals } from './usage.js';
25
28
  import { type SessionCallStats } from './call-stats.js';
29
+ import { type CacheMissReport, type CacheWarmth } from './cache-miss.js';
26
30
  import type { ModelPriceLookup, ModelUsageShare } from './cost.js';
27
31
  /** Test seam for proving startup unwind after resources have been acquired. */
28
32
  type RuntimeCreateCheckpoint = 'after-initialize';
@@ -44,6 +48,18 @@ export interface RuntimeOptions {
44
48
  permissionModeOverride?: ApprovalMode;
45
49
  /** Process-local force-on override for ContextOffloader; never persisted. */
46
50
  contextOffloadOverride?: true;
51
+ /**
52
+ * The driver drains SER-069 task wakes at idle (the interactive TUI). The `bash` tool
53
+ * then tells the model, truthfully, that ending the turn is followed by one
54
+ * `<task-notification>` turn — effective only with config `backgroundTaskWake !== false`.
55
+ * The same promise switches background delegation to non-blocking (SER-070): the
56
+ * SDK `backgroundTasks` option gets `waitForCompletion: false`, the dispatching turn
57
+ * ends after the ack, and the child's settlement is delivered by a wake turn.
58
+ * Headless drivers have no queue and leave this unset, so their one run keeps the
59
+ * SDK waiting and the report inside it. Children never wake, so their catalogue keeps
60
+ * the no-wake wording whatever the parent says.
61
+ */
62
+ backgroundCompletionWakes?: boolean;
47
63
  /** Refuses the next parent-Agent SDK model call after this many in the process. */
48
64
  maxModelCalls?: number;
49
65
  /**
@@ -102,6 +118,12 @@ export type { UsageTotals } from './usage.js';
102
118
  export interface ThinkingChangeResult {
103
119
  plan: ThinkingPlan;
104
120
  saved: Promise<void>;
121
+ /**
122
+ * True when the level actually sent changed — the only case that invalidates the
123
+ * conversation cache (a clamped or repeated level leaves the request as it was).
124
+ * The runtime marks its cache-miss tracker on the same fact (SER-074).
125
+ */
126
+ effectiveChanged: boolean;
105
127
  }
106
128
  /**
107
129
  * The outcome of a `/model` change: which configuration is now live, what it can
@@ -190,6 +212,17 @@ export interface RuntimeInfo {
190
212
  systemPromptPath: string | undefined;
191
213
  /** Why a present system prompt override was skipped; undefined when there is none. */
192
214
  systemPromptProblem: string | undefined;
215
+ /**
216
+ * The section strings `composeSystemPrompt` joined for this run — the base prompt
217
+ * (suffix included) and the `<project-instructions>` fragment. Kept from the
218
+ * composition seam so `/context` can count each section as composed instead of
219
+ * re-splitting the joined text; a restored prompt that no longer matches them is
220
+ * counted whole. Read by nothing else.
221
+ */
222
+ promptSections: {
223
+ readonly base: string;
224
+ readonly instructions: string | undefined;
225
+ };
193
226
  /**
194
227
  * Why the working context carries no directory listing. Undefined in the normal
195
228
  * case: the rest of the block (directory, platform, date) is always sent.
@@ -326,6 +359,25 @@ export declare class AgentRuntime {
326
359
  * `/context` to the plain heuristic line rather than to a wrong number.
327
360
  */
328
361
  private contextAnchorBroken;
362
+ /**
363
+ * Why the prompt cache missed, per completed call (SER-074): the same
364
+ * `afterModelCallEvent` counters the call stats fold, joined with the invalidating
365
+ * events this runtime performed (`/model`, `/effort`, `/compact`) and the TTL.
366
+ * Parent-only and session-scoped like the two observers above; built in the
367
+ * constructor so `/clear`'s successor starts empty. Read through
368
+ * {@link cacheMissReport} and {@link cacheWarmth}, both silent unless the live
369
+ * cache plan has Darwin-managed cache points.
370
+ */
371
+ private cacheMisses;
372
+ /** Latched on the first tracker failure — its own latch, so it cannot break the others. */
373
+ private cacheMissesBroken;
374
+ /**
375
+ * Which background jobs' terminal states completed turns already carried to the
376
+ * model through `wait`/`status` results (SER-069): the interactive drain asks it
377
+ * before sending a wake, so a job the model already saw finish never starts a
378
+ * duplicate turn. Session-scoped like the anchor; a `/clear` successor starts empty.
379
+ */
380
+ private readonly terminalDelivery;
329
381
  /** Serializes the bounded list/save/list critical section across concurrent callers. */
330
382
  private rewindCaptureTail;
331
383
  /**
@@ -366,8 +418,15 @@ export declare class AgentRuntime {
366
418
  *
367
419
  * One `before` snapshot feeds both the meter and `lastTurnDelta`, so what the record
368
420
  * says a turn cost and what `/usage` says it cost cannot be two different readings.
421
+ *
422
+ * `origin` marks a turn the session started rather than the user (SER-069, a
423
+ * background-task wake): the opening record is then a `taskNotification` carrying
424
+ * the literal `userInput` text, no `userInput` line is written, no rewind
425
+ * checkpoint is catalogued (the chooser lists the user's prompts) and memory gets
426
+ * no user quote to anchor to. Everything else — hooks, gate, recording, delivery
427
+ * ledger — is the ordinary turn.
369
428
  */
370
- send(input: string, userInput?: string, image?: ImageBlock): AsyncIterable<AgentStreamEvent>;
429
+ send(input: string, userInput?: string, image?: ImageBlock, origin?: TaskNotificationFields): AsyncIterable<AgentStreamEvent>;
371
430
  /**
372
431
  * Adds one completed turn's delta to its model's share. Runs in `send`'s `finally`,
373
432
  * so it cannot throw: a tally that failed would replace the provider's error with
@@ -400,6 +459,15 @@ export declare class AgentRuntime {
400
459
  durationMs: number;
401
460
  output: string;
402
461
  }): void;
462
+ /**
463
+ * Records one successful `/compact` (SRF-027) in the session's trajectory.
464
+ *
465
+ * A passthrough on {@link recordShellCommand}'s terms: the driver that ran the
466
+ * compaction reports what it already knows (the `CompactResult` counts, its own
467
+ * pre-compaction estimate, whether a focus was given) and nothing else — never the
468
+ * summary, never the focus text. No-op when recording is off or has latched off.
469
+ */
470
+ recordContextCompacted(entry: ContextCompactedEntry): void;
403
471
  /**
404
472
  * The diagnostics log, or `undefined` when nobody asked for one.
405
473
  *
@@ -461,6 +529,18 @@ export declare class AgentRuntime {
461
529
  * `undefined` when unknown.
462
530
  */
463
531
  contextEstimate(): Promise<ContextEstimate>;
532
+ /**
533
+ * What the next request is made of, component by component — the `/context`
534
+ * breakdown (SER-077, `src/agent/context-breakdown.ts`).
535
+ *
536
+ * Deliberately a separate accessor rather than an option on
537
+ * {@link contextEstimate}: the estimate is read after every turn by the pressure
538
+ * advisory and by `/status`, and must stay one `countTokens` call at most. This one
539
+ * makes one call per component through the same `model.countTokens`, so it runs only
540
+ * when the user asks — `/context` is its sole caller. Reads live state, mutates
541
+ * nothing, and never throws for a component: a failed count is an absent row.
542
+ */
543
+ contextBreakdown(): Promise<ContextBreakdown>;
464
544
  /**
465
545
  * How many wildcard allow-rules are in effect right now — config plus anything
466
546
  * accepted this session. Read live from the gate rather than snapshotted into
@@ -480,6 +560,15 @@ export declare class AgentRuntime {
480
560
  * {@link allowRuleCount}.
481
561
  */
482
562
  listAllowRules(): readonly AllowRuleEntry[];
563
+ /**
564
+ * The configured deny-rules (SER-076), for `/permissions` and `/status`. Read
565
+ * from the gate like {@link listAllowRules}; the gate's list is frozen and the
566
+ * session has no grant or revoke path for a deny, so this is exactly what the
567
+ * rules file said at startup.
568
+ */
569
+ listDenyRules(): readonly string[];
570
+ /** How many deny-rules are in force — counted apart from allow-rules. */
571
+ get denyRuleCount(): number;
483
572
  /**
484
573
  * The configured MCP servers with their live connection state and registered
485
574
  * tool names, for the `/mcp` report. A read-only projection — names, states and
@@ -640,6 +729,31 @@ export declare class AgentRuntime {
640
729
  * downgrading `/context` to a pure heuristic mid-session.
641
730
  */
642
731
  private observeContextAnchor;
732
+ /**
733
+ * Folds one completed call into the cache-miss tracker (SER-074): the call's cache
734
+ * read and request total through the same `usageBuckets`/`requestInputTokens`
735
+ * arithmetic `/usage` and `/context` use, stamped with the wall clock. Same
736
+ * observer discipline and its own latch, like the two above. Unreported counters
737
+ * are passed as unknown — the tracker returns no verdict for them.
738
+ */
739
+ private observeCacheMiss;
740
+ /** One invalidating event since the last completed call; a broken tracker ignores it. */
741
+ private markCacheInvalidated;
742
+ /**
743
+ * The likely causes of this session's prompt-cache misses, for `/usage` and
744
+ * `/status` — empty (`misses: 0`, no last miss) until one is observed, after a
745
+ * tracker failure, and whenever the live plan places no Darwin-managed cache
746
+ * point (caching off, an unsupported model, or OpenAI's provider-managed cache),
747
+ * so those reports stay byte-identical to before the feature existed.
748
+ */
749
+ cacheMissReport(): CacheMissReport;
750
+ /**
751
+ * Whether the last completed call's cache entries are still readable at `now` —
752
+ * warm iff that call read from the cache and finished less than the TTL ago. What
753
+ * `/model` and `/effort` consult before a switch. `undefined` until a call has
754
+ * completed, and under the same silence rule as {@link cacheMissReport}.
755
+ */
756
+ cacheWarmth(now: number): CacheWarmth | undefined;
643
757
  /**
644
758
  * Per-model-call efficiency stats for this session's parent agent, or
645
759
  * `undefined` until a completed call has been observed — so every surface that
@@ -675,6 +789,14 @@ export declare class AgentRuntime {
675
789
  listBackgroundTasks(): Promise<BackgroundTaskStatus[]>;
676
790
  /** Publishes future terminal task snapshots until the returned closure is called. */
677
791
  subscribeToBackgroundTasks(listener: BackgroundTaskListener): () => void;
792
+ /**
793
+ * True once a *completed* turn of this session carried the task's terminal state
794
+ * to the model through a `wait`/`status`/`stop`/`list` result (SER-069). The
795
+ * interactive drain drops a queued wake for such a task instead of sending it: the
796
+ * conversation already knows, and a second turn about it would be the duplicate
797
+ * the peer design produces. Synchronous, no I/O.
798
+ */
799
+ terminalStateDelivered(taskId: string): boolean;
678
800
  /**
679
801
  * Every subagent dispatch of this run, in start order, running and finished
680
802
  * alike. Synchronous — unlike {@link listBackgroundTasks}, which snapshots live
@@ -694,6 +816,19 @@ export declare class AgentRuntime {
694
816
  subscribeToSubagentProgress(listener: SubagentDispatchProgressListener): () => void;
695
817
  /** User-only exact-id cancellation; no agent tool exposes this operation. */
696
818
  cancelSubagentDispatch(dispatchId: string): SubagentCancelResult;
819
+ /**
820
+ * Every background delegation the SDK still tracks (SER-070): dispatched with
821
+ * `_background_execution` and not yet delivered to the model as its result pair —
822
+ * running, or settled and waiting for the next model call. Synchronous, no I/O: the
823
+ * observer's ledger, fed by the parent's own stream and hook. Non-empty means
824
+ * `/clear` and `/rewind` must refuse (the SDK's `assertCanLoadSnapshot` would throw,
825
+ * and a successor would orphan the children).
826
+ */
827
+ listBackgroundDelegations(): BackgroundDelegationStatus[];
828
+ /** Publishes each background delegation's one settlement snapshot until the closure is called. */
829
+ subscribeToBackgroundDelegations(listener: BackgroundDelegationListener): () => void;
830
+ /** Synchronous, before any release: the same sentence the TUI's local check prints. */
831
+ private refuseWhileDelegationsTracked;
697
832
  /**
698
833
  * Asks the agent to stop the current turn at its next safe point. The stream
699
834
  * ends with `stopReason: 'cancelled'` rather than throwing.
@@ -752,6 +887,11 @@ export declare class AgentRuntime {
752
887
  * If assembling the successor fails, this runtime stays fully usable: nothing it owns
753
888
  * has been released yet, and the diagnostics tap it installed at startup is put back
754
889
  * (the failed successor's unwind clears the process-global sink).
890
+ *
891
+ * Refused while a background delegation is tracked (SER-070): `retire()` would cancel
892
+ * the children through `subagents.shutdown()`, destroying their work silently, and
893
+ * the result pair the SDK still owes would be orphaned. The user decided the exits are
894
+ * `/agents cancel <id>` or waiting for the completion wake — never an implicit cancel.
755
895
  */
756
896
  startNewSession(): Promise<AgentRuntime>;
757
897
  /**