strands-darwin 0.0.33 → 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 (87) hide show
  1. package/README.md +3 -1
  2. package/README.zh-CN.md +3 -1
  3. package/dist/src/agent/cache-miss.d.ts +143 -0
  4. package/dist/src/agent/cache-miss.js +182 -0
  5. package/dist/src/agent/cache-miss.js.map +1 -0
  6. package/dist/src/agent/compact.d.ts +28 -0
  7. package/dist/src/agent/compact.js +34 -0
  8. package/dist/src/agent/compact.js.map +1 -1
  9. package/dist/src/agent/context-breakdown.d.ts +109 -0
  10. package/dist/src/agent/context-breakdown.js +116 -0
  11. package/dist/src/agent/context-breakdown.js.map +1 -0
  12. package/dist/src/agent/instructions.d.ts +1 -1
  13. package/dist/src/agent/instructions.js.map +1 -1
  14. package/dist/src/agent/permission-rules.d.ts +81 -2
  15. package/dist/src/agent/permission-rules.js +226 -6
  16. package/dist/src/agent/permission-rules.js.map +1 -1
  17. package/dist/src/agent/permission.d.ts +116 -2
  18. package/dist/src/agent/permission.js +201 -26
  19. package/dist/src/agent/permission.js.map +1 -1
  20. package/dist/src/agent/prompt-cache.d.ts +12 -3
  21. package/dist/src/agent/prompt-cache.js +12 -3
  22. package/dist/src/agent/prompt-cache.js.map +1 -1
  23. package/dist/src/agent/runtime.d.ts +87 -1
  24. package/dist/src/agent/runtime.js +175 -2
  25. package/dist/src/agent/runtime.js.map +1 -1
  26. package/dist/src/agents/child-recipe.d.ts +9 -1
  27. package/dist/src/agents/child-recipe.js +2 -0
  28. package/dist/src/agents/child-recipe.js.map +1 -1
  29. package/dist/src/agents/dispatch-registry.d.ts +18 -0
  30. package/dist/src/agents/dispatch-registry.js +2 -0
  31. package/dist/src/agents/dispatch-registry.js.map +1 -1
  32. package/dist/src/agents/retained-children.d.ts +101 -0
  33. package/dist/src/agents/retained-children.js +101 -0
  34. package/dist/src/agents/retained-children.js.map +1 -0
  35. package/dist/src/agents/subagent-tool.d.ts +50 -1
  36. package/dist/src/agents/subagent-tool.js +147 -9
  37. package/dist/src/agents/subagent-tool.js.map +1 -1
  38. package/dist/src/cli-doctor.js +3 -1
  39. package/dist/src/cli-doctor.js.map +1 -1
  40. package/dist/src/cli-main.js +9 -3
  41. package/dist/src/cli-main.js.map +1 -1
  42. package/dist/src/commands/custom-commands.js +5 -4
  43. package/dist/src/commands/custom-commands.js.map +1 -1
  44. package/dist/src/config.d.ts +44 -6
  45. package/dist/src/config.js +40 -16
  46. package/dist/src/config.js.map +1 -1
  47. package/dist/src/headless-protocol.d.ts +1 -1
  48. package/dist/src/headless-runner.js +7 -2
  49. package/dist/src/headless-runner.js.map +1 -1
  50. package/dist/src/hooks/tool-hooks.js +10 -6
  51. package/dist/src/hooks/tool-hooks.js.map +1 -1
  52. package/dist/src/skills/builtin/self-evolution-research/SKILL.md +14 -1
  53. package/dist/src/skills/prompt.d.ts +17 -0
  54. package/dist/src/skills/prompt.js +20 -0
  55. package/dist/src/skills/prompt.js.map +1 -1
  56. package/dist/src/trajectory/record.d.ts +169 -2
  57. package/dist/src/trajectory/record.js +135 -0
  58. package/dist/src/trajectory/record.js.map +1 -1
  59. package/dist/src/trajectory/replay.d.ts +34 -1
  60. package/dist/src/trajectory/replay.js +134 -4
  61. package/dist/src/trajectory/replay.js.map +1 -1
  62. package/dist/src/trajectory/resume-recap.js +10 -3
  63. package/dist/src/trajectory/resume-recap.js.map +1 -1
  64. package/dist/src/trajectory/spend.d.ts +14 -1
  65. package/dist/src/trajectory/spend.js +40 -6
  66. package/dist/src/trajectory/spend.js.map +1 -1
  67. package/dist/src/trajectory/writer.d.ts +45 -1
  68. package/dist/src/trajectory/writer.js +111 -3
  69. package/dist/src/trajectory/writer.js.map +1 -1
  70. package/dist/src/tui/App.d.ts +8 -4
  71. package/dist/src/tui/App.js +148 -32
  72. package/dist/src/tui/App.js.map +1 -1
  73. package/dist/src/tui/context-format.d.ts +16 -0
  74. package/dist/src/tui/context-format.js +41 -0
  75. package/dist/src/tui/context-format.js.map +1 -1
  76. package/dist/src/tui/status-format.d.ts +35 -16
  77. package/dist/src/tui/status-format.js +67 -8
  78. package/dist/src/tui/status-format.js.map +1 -1
  79. package/dist/src/tui/subagent-format.js +13 -1
  80. package/dist/src/tui/subagent-format.js.map +1 -1
  81. package/dist/src/tui/terminal-notify.d.ts +40 -0
  82. package/dist/src/tui/terminal-notify.js +136 -0
  83. package/dist/src/tui/terminal-notify.js.map +1 -0
  84. package/dist/src/tui/terminal-title.d.ts +94 -0
  85. package/dist/src/tui/terminal-title.js +121 -0
  86. package/dist/src/tui/terminal-title.js.map +1 -0
  87. package/package.json +1 -1
package/README.md CHANGED
@@ -37,7 +37,7 @@ This is a bounded workflow, not autonomous product authority. A dirty or unverif
37
37
  ## What it gives you
38
38
 
39
39
  - **A readable Ink TUI:** streaming Markdown answers, proposed file-edit diffs, elapsed time and token spend, slash/path completion, prompt recall and queueing, local `!` commands, and bounded reports.
40
- - **Safe approval modes:** `default`, classifier-assisted `auto`, read-only `plan`, and explicit `yolo`, with narrow project-scoped allow rules that can be revoked in-session.
40
+ - **Safe approval modes:** `default`, classifier-assisted `auto`, read-only `plan`, and explicit `yolo`, with narrow project-scoped allow rules that can be revoked in-session and deny rules that hold in every mode, `yolo` included.
41
41
  - **Durable work:** resumable project-scoped sessions, append-only trajectories, replay/search/fork/export, cost records, optional diagnostics, background jobs, and parent-managed on-demand project memory with exact evidence and durable-turn commit.
42
42
  - **Extension layers:** built-in and project/global skills, custom commands, child agents with workflow-DAG delegation, tool hooks, and stdio/HTTP MCP servers, with portable `.agents/` discovery.
43
43
  - **Automation:** one-shot text output or versioned JSON/JSONL, strict session selection, bounded model-call and context-offload controls, and nonzero cancellation/failure exits.
@@ -113,6 +113,8 @@ For multiple switchable models, provider-specific fields, Bedrock Mantle, cachin
113
113
 
114
114
  Use `Ctrl+R` to search this project's prompt history (type to filter, `Ctrl+R`/`Up`/`Down` to navigate, `Enter`/`Tab` to accept, `Escape` to cancel), `Ctrl+C` to cancel busy work, `Ctrl+B` to expand or compact tool details, and `/exit` or `Ctrl+D` to quit. In the composer, `Alt/Ctrl+Left/Right` or `Alt+B`/`Alt+F` moves by word, `Alt+Backspace`/`Alt+D` deletes the word before/after the cursor, and `Ctrl+_` (or `Ctrl+-`) undoes the last `Ctrl+K`/`Ctrl+U`, `Ctrl+W` or `Alt` word deletion. On an empty idle composer, `Esc` `Esc` (the second within 500 ms) opens the `/rewind` chooser — the same thing typing `/rewind` does; a single `Esc` there does nothing. Model tool calls still pass through the active permission mode; `!` commands are commands you authorize by typing them yourself.
115
115
 
116
+ To be called back when you have switched away, set `"terminalBell": true` (one BEL) and/or `"terminalNotify": true` (one OSC 9 desktop-notification sequence, shown by iTerm2, kitty, Ghostty, WezTerm and foot, silently ignored elsewhere) in `~/.darwin/config.json`; both fire when a permission prompt waits and when a turn completes, and both are off by default. iTerm2 needs "Send escape sequence-generated alerts" enabled; tmux needs `set -g allow-passthrough on`. Details in [Configuration and context](docs/user-guide/configuration.md).
117
+
116
118
  For non-interactive use:
117
119
 
118
120
  ```bash
package/README.zh-CN.md CHANGED
@@ -37,7 +37,7 @@ darwin 是一项自托管 AI 开发实验。[v0.0.1 基线版本](https://github
37
37
  ## 主要能力
38
38
 
39
39
  - **清晰的 Ink TUI:**流式 Markdown 回复、文件修改 diff、耗时与 token 消耗、斜杠命令与路径补全、提示词回看和排队、本地 `!` 命令,以及有长度上限的状态报告。
40
- - **安全审批模式:**`default`、带分类器的 `auto`、只读 `plan` 和显式开启的 `yolo`;项目级放行规则尽量收窄,并可在会话内撤销。
40
+ - **安全审批模式:**`default`、带分类器的 `auto`、只读 `plan` 和显式开启的 `yolo`;项目级放行规则尽量收窄,并可在会话内撤销;拒绝规则在所有模式下生效,包括 `yolo`。
41
41
  - **可持续的工作状态:**按项目保存的可恢复会话、只追加轨迹、回放/搜索/分叉/导出、费用记录、可选诊断日志、后台任务,以及由父 agent 按需管理、带精确证据并在回合持久化后提交的项目记忆。
42
42
  - **扩展机制:**内置及项目/全局 skills、自定义命令、子代理与 workflow DAG 委派、工具 hooks、stdio/HTTP MCP 服务器,并兼容 `.agents/` 目录。
43
43
  - **自动化接口:**单次文本输出或带版本的 JSON/JSONL;严格选择会话;可限制模型调用次数和上下文卸载;取消或失败时返回非零状态码。
@@ -113,6 +113,8 @@ Bedrock 使用标准 AWS 凭证链。模型 ID 必须是 `us.`、`eu.`、`apac.`
113
113
 
114
114
  按 `Ctrl+R` 可搜索当前项目的提示历史(输入文字筛选,按 `Ctrl+R`/`Up`/`Down` 切换结果,按 `Enter`/`Tab` 接受,按 `Escape` 取消);忙碌时按 `Ctrl+C` 取消,按 `Ctrl+B` 展开或收起工具详情,使用 `/exit` 或 `Ctrl+D` 退出。编辑输入时,`Alt/Ctrl+Left/Right` 或 `Alt+B`/`Alt+F` 按词移动光标,`Alt+Backspace`/`Alt+D` 删除光标前/后的一个词,`Ctrl+_`(或 `Ctrl+-`)可撤销最近一次 `Ctrl+K`/`Ctrl+U`、`Ctrl+W` 或 `Alt` 系列的删词操作。输入框为空且空闲时,连按两次 `Esc`(第二次在 500 ms 内)会打开 `/rewind` 选择器,效果与输入 `/rewind` 完全相同;此时单按一次 `Esc` 不做任何事。模型发起的工具调用仍会经过当前审批模式;`!` 命令由你亲自输入,因此不走模型工具审批。
115
115
 
116
+ 想在切到别处时被叫回来,可在 `~/.darwin/config.json` 中设置 `"terminalBell": true`(响一次终端铃)和/或 `"terminalNotify": true`(写一条 OSC 9 桌面通知序列,iTerm2、kitty、Ghostty、WezTerm 和 foot 会弹出通知,其他终端静默忽略);二者都在权限提示等待时和回合结束时触发,默认均为关闭。iTerm2 需开启 "Send escape sequence-generated alerts";tmux 需要 `set -g allow-passthrough on`。详见[配置与上下文](docs/user-guide/configuration.zh-CN.md)。
117
+
116
118
  无交互运行方式如下:
117
119
 
118
120
  ```bash
@@ -0,0 +1,143 @@
1
+ /**
2
+ * Why the prompt cache missed (SER-074): a derivation over facts darwin already
3
+ * holds, never a new measurement.
4
+ *
5
+ * `/usage` and `/status` have always shown cache read/write counts and a hit ratio,
6
+ * but a number alone does not say why a call re-read the conversation uncached.
7
+ * Every input needed to name a likely cause is already in the runtime: the per-call
8
+ * provider counters `observeCallStats` folds (`afterModelCallEvent`
9
+ * `stopData.message.metadata.usage`), the cache-invalidating events the session
10
+ * itself performed (`/model`, `/effort`, `/compact`), the configured TTL
11
+ * (`promptCacheTtl`: `1h` default, `5m`), the wall clock, and whether the session
12
+ * was resumed. This module is the pure arithmetic over those facts; the runtime
13
+ * feeds it through {@link CacheMissTracker} with the same synchronous,
14
+ * non-throwing, latch-on-failure discipline the call stats observe under.
15
+ *
16
+ * Advisory only, on the context-pressure row's terms: the verdict is printed on
17
+ * existing reports (`/usage`, `/status`) and as one transcript notice before a
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.
21
+ *
22
+ * Invalidators, and one deliberate non-invalidator. A model switch, an effective
23
+ * effort change and a compaction each change the request prefix (a different model
24
+ * keys a different cache; `output_config.effort` is part of the request; compaction
25
+ * rewrites the messages), and idling past the TTL lets the entries expire. `/rewind`
26
+ * is not marked: it restores an earlier prefix of the same conversation, whose cache
27
+ * entries are still valid if they have not expired — the same rule Claude Code's
28
+ * prompt-caching documentation states. File edits, permission-mode changes and skill
29
+ * loads change no cached section either.
30
+ *
31
+ * Claude-only by the gate `prompt-cache.ts` explains: OpenAI caches automatically
32
+ * at the provider with no darwin-placed cache points, so its counters describe a
33
+ * cache darwin did not configure — the tracker stays silent unless the live plan
34
+ * has Darwin-managed cache points.
35
+ */
36
+ import { type PromptCacheTtl } from './prompt-cache.js';
37
+ /** The one bounded verdict per missed call, in precedence order. */
38
+ export type CacheMissCause = 'model switched' | 'effort changed' | 'compacted' | 'idle past cache TTL' | 'first request of a resumed session' | 'unknown';
39
+ /** Session events that invalidate the prefix a cache read depends on. */
40
+ export type CacheInvalidatingEvent = 'model' | 'effort' | 'compact';
41
+ /**
42
+ * A call reading less than this share of its own request total from the cache is a
43
+ * miss. A warm call on a long conversation reads nearly all of it (the last user
44
+ * message is the only uncached part); one fifth leaves room for a large tool result
45
+ * or user message without calling an ordinary turn a miss.
46
+ */
47
+ export declare const CACHE_MISS_READ_FRACTION = 0.2;
48
+ /** One completed call's cache facts, as the tracker needs them. */
49
+ export interface CacheCallFacts {
50
+ /** When the call completed (epoch ms). */
51
+ at: number;
52
+ /** Tokens read from the cache, or undefined when the provider did not report it. */
53
+ cacheRead: number | undefined;
54
+ /** The request total (`requestInputTokens`: input + cache read + cache write), or undefined. */
55
+ requestInput: number | undefined;
56
+ }
57
+ export interface CacheMissInput {
58
+ /** The previous completed call, or undefined when this is the session's first. */
59
+ previous: CacheCallFacts | undefined;
60
+ current: CacheCallFacts;
61
+ /** Invalidating events the session performed since {@link previous} completed. */
62
+ events: ReadonlySet<CacheInvalidatingEvent>;
63
+ ttlMs: number;
64
+ /** True for the first call of a resumed session, whose cache the previous run wrote. */
65
+ firstCallAfterResume: boolean;
66
+ }
67
+ /** The TTL in milliseconds; an unset TTL is darwin's {@link DEFAULT_PROMPT_CACHE_TTL}. */
68
+ export declare function promptCacheTtlMs(ttl: PromptCacheTtl | undefined): number;
69
+ /**
70
+ * True when a call read less than {@link CACHE_MISS_READ_FRACTION} of its request
71
+ * from the cache. Unreported counters and an empty request are not misses: they are
72
+ * unknown, and unknown is never a verdict.
73
+ */
74
+ export declare function isCacheMiss(call: CacheCallFacts): boolean;
75
+ /**
76
+ * The likely cause of the current call's cache miss, or `undefined` for no verdict.
77
+ *
78
+ * No verdict when the current call's counters are unreported, when it is not a miss,
79
+ * when it is a fresh session's first call (expected cold: nothing has been written
80
+ * yet), or when the previous call was itself cold — a miss is only a miss relative
81
+ * to a cache that was demonstrably warm. When several causes apply, the one that
82
+ * certainly invalidated the prefix wins over the one that merely could have:
83
+ * `model switched` > `effort changed` > `compacted` > `idle past cache TTL` >
84
+ * `first request of a resumed session` > `unknown`.
85
+ */
86
+ export declare function cacheMissCause(input: CacheMissInput): CacheMissCause | undefined;
87
+ /** The cause as `/usage` and `/status` print it; the TTL cause names the configured TTL. */
88
+ export declare function describeCacheMissCause(cause: CacheMissCause, ttl: PromptCacheTtl | undefined): string;
89
+ /** What the reports read: the last observed miss, and how many there were. */
90
+ export interface CacheMissReport {
91
+ lastMiss: {
92
+ cause: CacheMissCause;
93
+ at: number;
94
+ cacheRead: number;
95
+ requestInput: number;
96
+ } | undefined;
97
+ misses: number;
98
+ }
99
+ /** Whether the last completed call's cache entries are still readable. */
100
+ export interface CacheWarmth {
101
+ /** True iff the last completed call read from the cache and finished less than the TTL ago. */
102
+ warm: boolean;
103
+ /** Milliseconds since the last completed call. */
104
+ ageMs: number;
105
+ /** What that call read from the cache. */
106
+ lastCacheRead: number;
107
+ }
108
+ /**
109
+ * The one bounded notice `/model <target>` and `/effort <level>` print before a
110
+ * switch on a warm cache — `undefined` when the cache is cold or nothing is known,
111
+ * so a cold switch prints nothing new. States the cost and lets the switch proceed;
112
+ * deliberately not a confirmation dialog.
113
+ */
114
+ export declare function warmCacheSwitchNotice(kind: 'model' | 'effort', warmth: CacheWarmth | undefined): string | undefined;
115
+ /**
116
+ * The per-runtime state behind {@link CacheMissReport} and {@link CacheWarmth}.
117
+ *
118
+ * Pure over what it is handed: the runtime passes each completed call's facts and
119
+ * the clock, marks the events it performed, and reads the two projections. Nothing
120
+ * here throws on ordinary data; the runtime wraps the calls in the observer latch
121
+ * anyway, so a surprise degrades to absence rather than to a dead turn. `/clear`'s
122
+ * successor runtime builds a new tracker, which is how the state stays session-scoped.
123
+ */
124
+ export declare class CacheMissTracker {
125
+ private readonly ttlMs;
126
+ private previous;
127
+ private readonly events;
128
+ private lastMiss;
129
+ private misses;
130
+ private firstCallAfterResume;
131
+ /**
132
+ * @param ttlMs the live TTL, read per call because `promptCacheTtl` is a model
133
+ * field and `/model` can change it mid-session.
134
+ */
135
+ constructor(ttlMs: () => number, resumed: boolean);
136
+ /** Records that the session performed one invalidating event since the last call. */
137
+ mark(event: CacheInvalidatingEvent): void;
138
+ /** Folds one completed call in; returns the verdict for that call, if any. */
139
+ observe(call: CacheCallFacts): CacheMissCause | undefined;
140
+ report(): CacheMissReport;
141
+ /** `undefined` until a call has completed. */
142
+ warmth(now: number): CacheWarmth | undefined;
143
+ }
@@ -0,0 +1,182 @@
1
+ /**
2
+ * Why the prompt cache missed (SER-074): a derivation over facts darwin already
3
+ * holds, never a new measurement.
4
+ *
5
+ * `/usage` and `/status` have always shown cache read/write counts and a hit ratio,
6
+ * but a number alone does not say why a call re-read the conversation uncached.
7
+ * Every input needed to name a likely cause is already in the runtime: the per-call
8
+ * provider counters `observeCallStats` folds (`afterModelCallEvent`
9
+ * `stopData.message.metadata.usage`), the cache-invalidating events the session
10
+ * itself performed (`/model`, `/effort`, `/compact`), the configured TTL
11
+ * (`promptCacheTtl`: `1h` default, `5m`), the wall clock, and whether the session
12
+ * was resumed. This module is the pure arithmetic over those facts; the runtime
13
+ * feeds it through {@link CacheMissTracker} with the same synchronous,
14
+ * non-throwing, latch-on-failure discipline the call stats observe under.
15
+ *
16
+ * Advisory only, on the context-pressure row's terms: the verdict is printed on
17
+ * existing reports (`/usage`, `/status`) and as one transcript notice before a
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.
21
+ *
22
+ * Invalidators, and one deliberate non-invalidator. A model switch, an effective
23
+ * effort change and a compaction each change the request prefix (a different model
24
+ * keys a different cache; `output_config.effort` is part of the request; compaction
25
+ * rewrites the messages), and idling past the TTL lets the entries expire. `/rewind`
26
+ * is not marked: it restores an earlier prefix of the same conversation, whose cache
27
+ * entries are still valid if they have not expired — the same rule Claude Code's
28
+ * prompt-caching documentation states. File edits, permission-mode changes and skill
29
+ * loads change no cached section either.
30
+ *
31
+ * Claude-only by the gate `prompt-cache.ts` explains: OpenAI caches automatically
32
+ * at the provider with no darwin-placed cache points, so its counters describe a
33
+ * cache darwin did not configure — the tracker stays silent unless the live plan
34
+ * has Darwin-managed cache points.
35
+ */
36
+ import { DEFAULT_PROMPT_CACHE_TTL } from './prompt-cache.js';
37
+ /**
38
+ * A call reading less than this share of its own request total from the cache is a
39
+ * miss. A warm call on a long conversation reads nearly all of it (the last user
40
+ * message is the only uncached part); one fifth leaves room for a large tool result
41
+ * or user message without calling an ordinary turn a miss.
42
+ */
43
+ export const CACHE_MISS_READ_FRACTION = 0.2;
44
+ /** The TTL in milliseconds; an unset TTL is darwin's {@link DEFAULT_PROMPT_CACHE_TTL}. */
45
+ export function promptCacheTtlMs(ttl) {
46
+ return (ttl ?? DEFAULT_PROMPT_CACHE_TTL) === '1h' ? 3_600_000 : 300_000;
47
+ }
48
+ /**
49
+ * True when a call read less than {@link CACHE_MISS_READ_FRACTION} of its request
50
+ * from the cache. Unreported counters and an empty request are not misses: they are
51
+ * unknown, and unknown is never a verdict.
52
+ */
53
+ export function isCacheMiss(call) {
54
+ if (call.cacheRead === undefined || call.requestInput === undefined)
55
+ return false;
56
+ if (!Number.isFinite(call.cacheRead) || !Number.isFinite(call.requestInput) || call.requestInput <= 0)
57
+ return false;
58
+ return call.cacheRead < call.requestInput * CACHE_MISS_READ_FRACTION;
59
+ }
60
+ /**
61
+ * The likely cause of the current call's cache miss, or `undefined` for no verdict.
62
+ *
63
+ * No verdict when the current call's counters are unreported, when it is not a miss,
64
+ * when it is a fresh session's first call (expected cold: nothing has been written
65
+ * yet), or when the previous call was itself cold — a miss is only a miss relative
66
+ * to a cache that was demonstrably warm. When several causes apply, the one that
67
+ * certainly invalidated the prefix wins over the one that merely could have:
68
+ * `model switched` > `effort changed` > `compacted` > `idle past cache TTL` >
69
+ * `first request of a resumed session` > `unknown`.
70
+ */
71
+ export function cacheMissCause(input) {
72
+ const { previous, current, events, ttlMs, firstCallAfterResume } = input;
73
+ if (!isCacheMiss(current))
74
+ return undefined;
75
+ if (previous === undefined) {
76
+ if (!firstCallAfterResume)
77
+ return undefined;
78
+ }
79
+ else if (previous.cacheRead === undefined || !(previous.cacheRead > 0)) {
80
+ return undefined;
81
+ }
82
+ if (events.has('model'))
83
+ return 'model switched';
84
+ if (events.has('effort'))
85
+ return 'effort changed';
86
+ if (events.has('compact'))
87
+ return 'compacted';
88
+ if (previous !== undefined && current.at - previous.at > ttlMs)
89
+ return 'idle past cache TTL';
90
+ if (firstCallAfterResume)
91
+ return 'first request of a resumed session';
92
+ return 'unknown';
93
+ }
94
+ /** The cause as `/usage` and `/status` print it; the TTL cause names the configured TTL. */
95
+ export function describeCacheMissCause(cause, ttl) {
96
+ return cause === 'idle past cache TTL' ? `${cause} (${ttl ?? DEFAULT_PROMPT_CACHE_TTL})` : cause;
97
+ }
98
+ /**
99
+ * The one bounded notice `/model <target>` and `/effort <level>` print before a
100
+ * switch on a warm cache — `undefined` when the cache is cold or nothing is known,
101
+ * so a cold switch prints nothing new. States the cost and lets the switch proceed;
102
+ * deliberately not a confirmation dialog.
103
+ */
104
+ export function warmCacheSwitchNotice(kind, warmth) {
105
+ if (warmth === undefined || !warmth.warm)
106
+ return undefined;
107
+ return (`cache is warm (${formatWarmthAge(warmth.ageMs)} ago, ${warmth.lastCacheRead.toLocaleString('en-US')} tokens read last call): ` +
108
+ `switching ${kind} re-reads the conversation uncached`);
109
+ }
110
+ /** `12s`, `3m 12s`, `1h 2m` — the `/tasks` duration vocabulary, without a TUI import. */
111
+ function formatWarmthAge(milliseconds) {
112
+ const seconds = Math.floor(Math.max(0, milliseconds) / 1000);
113
+ if (seconds < 60)
114
+ return `${seconds}s`;
115
+ const minutes = Math.floor(seconds / 60);
116
+ if (minutes < 60)
117
+ return `${minutes}m ${seconds % 60}s`;
118
+ const hours = Math.floor(minutes / 60);
119
+ return `${hours}h ${minutes % 60}m`;
120
+ }
121
+ /**
122
+ * The per-runtime state behind {@link CacheMissReport} and {@link CacheWarmth}.
123
+ *
124
+ * Pure over what it is handed: the runtime passes each completed call's facts and
125
+ * the clock, marks the events it performed, and reads the two projections. Nothing
126
+ * here throws on ordinary data; the runtime wraps the calls in the observer latch
127
+ * anyway, so a surprise degrades to absence rather than to a dead turn. `/clear`'s
128
+ * successor runtime builds a new tracker, which is how the state stays session-scoped.
129
+ */
130
+ export class CacheMissTracker {
131
+ ttlMs;
132
+ previous = undefined;
133
+ events = new Set();
134
+ lastMiss = undefined;
135
+ misses = 0;
136
+ firstCallAfterResume;
137
+ /**
138
+ * @param ttlMs the live TTL, read per call because `promptCacheTtl` is a model
139
+ * field and `/model` can change it mid-session.
140
+ */
141
+ constructor(ttlMs, resumed) {
142
+ this.ttlMs = ttlMs;
143
+ this.firstCallAfterResume = resumed;
144
+ }
145
+ /** Records that the session performed one invalidating event since the last call. */
146
+ mark(event) {
147
+ this.events.add(event);
148
+ }
149
+ /** Folds one completed call in; returns the verdict for that call, if any. */
150
+ observe(call) {
151
+ const cause = cacheMissCause({
152
+ previous: this.previous,
153
+ current: call,
154
+ events: this.events,
155
+ ttlMs: this.ttlMs(),
156
+ firstCallAfterResume: this.firstCallAfterResume,
157
+ });
158
+ if (cause !== undefined && call.cacheRead !== undefined && call.requestInput !== undefined) {
159
+ this.misses += 1;
160
+ this.lastMiss = { cause, at: call.at, cacheRead: call.cacheRead, requestInput: call.requestInput };
161
+ }
162
+ // Every completed call closes the "since last call" window and settles the
163
+ // resume question, verdict or not: the events have had their effect on this
164
+ // request whether or not the counters let us see it.
165
+ this.previous = call;
166
+ this.events.clear();
167
+ this.firstCallAfterResume = false;
168
+ return cause;
169
+ }
170
+ report() {
171
+ return { lastMiss: this.lastMiss, misses: this.misses };
172
+ }
173
+ /** `undefined` until a call has completed. */
174
+ warmth(now) {
175
+ if (this.previous === undefined)
176
+ return undefined;
177
+ const lastCacheRead = this.previous.cacheRead ?? 0;
178
+ const ageMs = Math.max(0, now - this.previous.at);
179
+ return { warm: lastCacheRead > 0 && ageMs < this.ttlMs(), ageMs, lastCacheRead };
180
+ }
181
+ }
182
+ //# sourceMappingURL=cache-miss.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cache-miss.js","sourceRoot":"","sources":["../../../src/agent/cache-miss.ts"],"names":[],"mappings":"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"}
@@ -7,6 +7,7 @@
7
7
  */
8
8
  import type { Agent, Message, Model, SummarizingConversationManagerConfig } from '@strands-agents/sdk';
9
9
  import { SummarizingConversationManager } from '@strands-agents/sdk';
10
+ import type { ContextCompactedEntry } from '../trajectory/record.js';
10
11
  /**
11
12
  * `/compact` collapses every reducible old message in one command, leaving one
12
13
  * summary plus the recent window. 0.8 is the SDK's maximum ratio and minimizes
@@ -85,6 +86,33 @@ export interface CompactConversationOptions {
85
86
  * Both rules apply to focused and unfocused managers alike.
86
87
  */
87
88
  export declare function compactConversation({ agent, model, manager, preserveRecentMessages, persist, }: CompactConversationOptions): Promise<CompactResult>;
89
+ /**
90
+ * What a driver needs from the runtime to run one `/compact` and record it: the
91
+ * structural slice of `AgentRuntime` the TUI and headless drivers already hold.
92
+ * Typed structurally so `spike/verify-compact.ts` can prove the recording rules with
93
+ * a scripted host and a real recorder, without an `Agent`.
94
+ */
95
+ export interface CompactionHost {
96
+ contextEstimate(): Promise<{
97
+ estimatedTokens: number;
98
+ }>;
99
+ compact(focus?: string): Promise<CompactResult>;
100
+ recordContextCompacted(entry: ContextCompactedEntry): void;
101
+ }
102
+ /**
103
+ * Runs one `/compact` through the host and appends the SRF-027 `contextCompacted`
104
+ * trajectory record when — and only when — the result says `compacted: true`.
105
+ *
106
+ * The one place that composes the record, shared by both drivers so the TUI and
107
+ * `--compact-before` cannot describe the same compaction two ways. The pre-compaction
108
+ * estimate is the host's own `contextEstimate()` read **before** the compaction (the
109
+ * anchor it rests on drops with the rewritten history), taken best-effort: a failed or
110
+ * non-positive read is absence, never 0, and never a reason not to compact. A
111
+ * no-shrink pass records nothing; a failure records nothing and rethrows untouched.
112
+ * `focused` is whether a non-empty focus was given — the focus text stays with the
113
+ * summarizer request and is not handed to the recorder.
114
+ */
115
+ export declare function compactAndRecord(host: CompactionHost, focus?: string): Promise<CompactResult>;
88
116
  /**
89
117
  * Repairs user-role messages that carry `reasoningBlock` content in place.
90
118
  *
@@ -151,6 +151,40 @@ export async function compactConversation({ agent, model, manager, preserveRecen
151
151
  throw error;
152
152
  }
153
153
  }
154
+ /**
155
+ * Runs one `/compact` through the host and appends the SRF-027 `contextCompacted`
156
+ * trajectory record when — and only when — the result says `compacted: true`.
157
+ *
158
+ * The one place that composes the record, shared by both drivers so the TUI and
159
+ * `--compact-before` cannot describe the same compaction two ways. The pre-compaction
160
+ * estimate is the host's own `contextEstimate()` read **before** the compaction (the
161
+ * anchor it rests on drops with the rewritten history), taken best-effort: a failed or
162
+ * non-positive read is absence, never 0, and never a reason not to compact. A
163
+ * no-shrink pass records nothing; a failure records nothing and rethrows untouched.
164
+ * `focused` is whether a non-empty focus was given — the focus text stays with the
165
+ * summarizer request and is not handed to the recorder.
166
+ */
167
+ export async function compactAndRecord(host, focus) {
168
+ let estimatedTokensBefore;
169
+ try {
170
+ const estimate = await host.contextEstimate();
171
+ const tokens = estimate.estimatedTokens;
172
+ estimatedTokensBefore = Number.isFinite(tokens) && tokens > 0 ? Math.round(tokens) : undefined;
173
+ }
174
+ catch {
175
+ estimatedTokensBefore = undefined;
176
+ }
177
+ const result = await host.compact(focus);
178
+ if (result.compacted) {
179
+ host.recordContextCompacted({
180
+ messagesBefore: result.messagesBefore,
181
+ messagesAfter: result.messagesAfter,
182
+ ...(estimatedTokensBefore === undefined ? {} : { estimatedTokensBefore }),
183
+ focused: normalizeCompactFocus(focus) !== undefined,
184
+ });
185
+ }
186
+ return result;
187
+ }
154
188
  /**
155
189
  * Repairs user-role messages that carry `reasoningBlock` content in place.
156
190
  *
@@ -1 +1 @@
1
- {"version":3,"file":"compact.js","sourceRoot":"","sources":["../../../src/agent/compact.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"compact.js","sourceRoot":"","sources":["../../../src/agent/compact.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,109 @@
1
+ /**
2
+ * The `/context` breakdown: what the next request is made of, component by component
3
+ * (SER-077).
4
+ *
5
+ * The total `/context` prints is one number — measured base plus a counted tail, or
6
+ * one whole-request count — and says nothing about *what* is large. This module
7
+ * counts the parts separately: the system prompt by section as Darwin composes it
8
+ * (base prompt, `<project-instructions>`, the official `<available_skills>`
9
+ * catalogue, `<working-context>`), the tool specs grouped by origin (darwin's own
10
+ * built-ins, then each MCP server by its configured name), and the conversation by
11
+ * role. Every component goes through the same `model.countTokens` the total already
12
+ * uses, so the parts are stated in the total's own units — but they are an
13
+ * *estimate over the current request shape*, never the anchor measurement, and the
14
+ * formatter labels them so. The measured total stays the authoritative line.
15
+ *
16
+ * Two rules from the rest of the runtime hold here. It is computed on demand only:
17
+ * `/context` asks for it, nothing else does — not the post-turn pressure advisory,
18
+ * not `/status` — because a provider-native `countTokens` may reach the provider's
19
+ * counting API and this makes several calls. And a component whose count fails is
20
+ * absent (`tokens: undefined`, rendered `not reported`), never 0: the `usageBuckets`
21
+ * honesty rule. Everything here is a pure function over injected inputs; the
22
+ * runtime supplies the live prompt, tools, servers, messages and the counter.
23
+ */
24
+ import type { CountTokensOptions, Message, SystemPrompt, ToolSpec } from '@strands-agents/sdk';
25
+ import type { McpServerStatus } from '../mcp/registry.js';
26
+ /** One counted component of the request. */
27
+ export interface ContextComponent {
28
+ /** Bounded label, rendered as written. */
29
+ label: string;
30
+ /** Estimated tokens; absent when the count failed — `not reported`, never 0. */
31
+ tokens: number | undefined;
32
+ /**
33
+ * A stated absence that is not a failed count — e.g. the skills catalogue before
34
+ * the plugin's first injection. Rendered instead of a count when present.
35
+ */
36
+ absent?: string;
37
+ }
38
+ /** The request, component by component. Row order is the rendering order. */
39
+ export interface ContextBreakdown {
40
+ /** System prompt sections in composition order. */
41
+ systemPrompt: ContextComponent[];
42
+ /** Darwin's own tools plus plugin tools — everything no MCP server registered. */
43
+ builtinTools: ContextComponent;
44
+ /** One row per configured MCP server, in configuration order; the formatter bounds them. */
45
+ mcpServers: ContextComponent[];
46
+ /** Conversation messages by role, whole messages only. */
47
+ conversation: ContextComponent[];
48
+ }
49
+ /** `model.countTokens`, injected so the runtime and an offline suite share one path. */
50
+ export type ComponentCounter = (messages: Message[], options: CountTokensOptions) => Promise<number>;
51
+ export interface BreakdownInputs {
52
+ /** The live `agent.systemPrompt`. */
53
+ systemPrompt: SystemPrompt | undefined;
54
+ /** The section strings the composition seam produced (`composeSystemPrompt`'s inputs). */
55
+ composed: {
56
+ base: string;
57
+ instructions: string | undefined;
58
+ };
59
+ /** The live `agent.tools`. */
60
+ tools: readonly {
61
+ name: string;
62
+ toolSpec: ToolSpec;
63
+ }[];
64
+ /** `mcpServerStatuses(...)` — names and registered tool names, never `listTools()`. */
65
+ servers: readonly McpServerStatus[];
66
+ /** The live `agent.messages`. */
67
+ messages: readonly Message[];
68
+ }
69
+ export declare const BASE_PROMPT_LABEL = "system prompt \u00B7 base";
70
+ export declare const PROJECT_INSTRUCTIONS_LABEL = "system prompt \u00B7 project instructions (AGENTS.md)";
71
+ /** A restored prompt whose base block no longer equals the current composition. */
72
+ export declare const RESTORED_PROMPT_LABEL = "system prompt \u00B7 base + project instructions (restored)";
73
+ /** A prompt array in a shape Darwin does not own: counted whole rather than guessed at. */
74
+ export declare const WHOLE_PROMPT_LABEL = "system prompt";
75
+ export declare const SKILLS_CATALOGUE_LABEL = "system prompt \u00B7 skills catalogue";
76
+ export declare const WORKING_CONTEXT_LABEL = "system prompt \u00B7 working context";
77
+ export declare const CATALOGUE_NOT_INJECTED = "not yet injected (added before the first model call)";
78
+ export declare const BUILTIN_TOOLS_LABEL = "tools \u00B7 darwin built-ins";
79
+ export declare const UNATTRIBUTED_TOOLS_LABEL = "tools \u00B7 darwin built-ins and unattributed";
80
+ export declare const MCP_TOOLS_LABEL_PREFIX = "tools \u00B7 mcp ";
81
+ export declare const USER_MESSAGES_LABEL = "conversation \u00B7 user prompts and tool results";
82
+ export declare const ASSISTANT_MESSAGES_LABEL = "conversation \u00B7 assistant replies and tool calls";
83
+ /**
84
+ * Counts every component with `countTokens`, one call per component, sequentially
85
+ * so a provider-backed counter is never fanned out. A failed count is recorded as
86
+ * absent and the rest are still counted: one gap costs one row, never the report.
87
+ */
88
+ export declare function measureContextBreakdown(inputs: BreakdownInputs, countTokens: ComponentCounter): Promise<ContextBreakdown>;
89
+ export interface ToolOriginGroups {
90
+ /** Names the built-in row honestly when a server's tool names could not be read. */
91
+ builtinLabel: string;
92
+ builtins: ToolSpec[];
93
+ /** `specs` is absent when the server's registered names are unavailable. */
94
+ servers: {
95
+ label: string;
96
+ specs: ToolSpec[] | undefined;
97
+ }[];
98
+ }
99
+ /**
100
+ * Attributes each live tool spec to the MCP server that registered it, by the
101
+ * names `mcpServerStatuses` already reads; whatever no server claims is darwin's
102
+ * own (built-ins, plugin tools, parent-only tools). A server whose names cannot be
103
+ * read gets a row with no specs — its tools then land in the built-in group, which
104
+ * says so in its label rather than passing them off as darwin's.
105
+ */
106
+ export declare function groupToolsByOrigin(tools: readonly {
107
+ name: string;
108
+ toolSpec: ToolSpec;
109
+ }[], servers: readonly McpServerStatus[]): ToolOriginGroups;