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
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
@@ -15,6 +15,13 @@ export interface BackgroundDelegationConfigInput {
15
15
  readonly ordinaryToolNames: readonly string[];
16
16
  /** The SER-061 cap (`concurrencyCap(config)`); the SDK engine queues beyond it. */
17
17
  readonly maxConcurrency: number;
18
+ /**
19
+ * True only for a runtime whose driver drains completion wakes (the TUI with
20
+ * `backgroundTaskWake` on): the dispatching turn then ends after the ack and the
21
+ * report arrives in the next turn that runs. False keeps the SDK waiting inside the
22
+ * invocation, so a headless run's one cycle still contains the report.
23
+ */
24
+ readonly completionWakes: boolean;
18
25
  }
19
26
  /**
20
27
  * The `backgroundTasks` option for the parent Agent.
@@ -24,6 +31,8 @@ export interface BackgroundDelegationConfigInput {
24
31
  * plugin's own manage tool) is `never` as well rather than falling back to the SDK's
25
32
  * `agentic` default for unnamed tools. The SDK rejects a name listed under two modes,
26
33
  * so a delegation tool is removed from `never` if a caller passes it in both lists.
34
+ * `waitForCompletion` is the one per-runtime choice (SER-070): `false` when the driver
35
+ * wakes on settlement, `true` otherwise.
27
36
  */
28
37
  export declare function backgroundDelegationConfig(input: BackgroundDelegationConfigInput): BackgroundTasksConfig;
29
38
  /** True when a tool-use input asks for background execution (`_background_execution: true`). */
@@ -31,37 +40,86 @@ export declare function backgroundExecutionRequested(input: unknown): boolean;
31
40
  /**
32
41
  * The one sentence both delegation tool descriptions carry. The flag itself is
33
42
  * added to the spec by the SDK middleware, so the description only has to say when
34
- * to use it and when the result comes back.
43
+ * to use it and when the result comes back — which depends on the runtime
44
+ * (SER-070): a waking runtime lets the turn end and delivers the report in the next
45
+ * turn that runs; every other runtime delivers it before the next model call of the
46
+ * same turn, byte-identical to the pre-SER-070 sentence.
35
47
  */
36
- export declare function backgroundDelegationDescriptionClause(): string;
48
+ export declare function backgroundDelegationDescriptionClause(completionWakes?: boolean): string;
37
49
  /**
38
50
  * The task id inside the SDK's dispatch acknowledgement, or `undefined` for any
39
51
  * other tool result. Reads the ack's fixed text shape only; never a task registry.
40
52
  */
41
53
  export declare function backgroundAckTaskId(content: readonly unknown[]): string | undefined;
54
+ /** How far one background delegation has come; `running` until its run's body returns. */
55
+ export type BackgroundDelegationState = 'running' | 'succeeded' | 'failed';
56
+ /**
57
+ * One background delegation the SDK still tracks: dispatched (the ack named a task)
58
+ * and not yet delivered to the model as its result pair. Everything here came down
59
+ * the parent's own stream or hook — no SDK internals, no task registry.
60
+ */
61
+ export interface BackgroundDelegationStatus {
62
+ /** The SDK task id from the ack; the pair's tool-use id when it is delivered. */
63
+ readonly taskId: string;
64
+ /** The model's tool-use id for the dispatching call. */
65
+ readonly toolUseId: string;
66
+ /** `subagent` or `workflow`. */
67
+ readonly toolName: string;
68
+ /** The tool-use input as the stream showed it (the SDK strips the flag later). */
69
+ readonly input: unknown;
70
+ /** ISO time of the `beforeToolCallEvent`. */
71
+ readonly startedAt: string;
72
+ /** ISO time of the run's `AfterToolCallEvent`; `null` while running. */
73
+ readonly settledAt: string | null;
74
+ readonly state: BackgroundDelegationState;
75
+ }
76
+ export type BackgroundDelegationListener = (status: BackgroundDelegationStatus) => void;
77
+ /** The first eight characters of an SDK task id (a UUID) — enough to tell tasks apart in a row. */
78
+ export declare function shortBackgroundTaskId(taskId: string): string;
79
+ /**
80
+ * The one refusal `/clear` and `/rewind` give while a background delegation is
81
+ * tracked (SER-070): the live task ids and the two ways out. Never a partial restore,
82
+ * never a silent cancel of minutes of child work — the same rule as the SER-027 busy
83
+ * refusal. Shared by the TUI's local check and the runtime's own guard, so the two
84
+ * cannot word it differently.
85
+ */
86
+ export declare function liveBackgroundDelegationRefusal(command: '/clear' | '/rewind', tasks: readonly BackgroundDelegationStatus[]): string;
42
87
  /**
43
- * Forwards background runs' `AfterToolCallEvent`s into the parent's stream.
88
+ * Forwards background runs' `AfterToolCallEvent`s into the parent's stream and keeps
89
+ * the parent-side ledger of tracked delegations (SER-064, SER-070).
44
90
  *
45
91
  * One instance per parent Agent; {@link observe} wraps exactly one `Agent.stream()`
46
- * at a time (the runtime serializes turns). Per turn it remembers which tool-use ids
47
- * the stream showed as routed to the background — a `beforeToolCallEvent` for a
92
+ * at a time (the runtime serializes turns). It remembers which tool-use ids the
93
+ * stream showed as routed to the background — a `beforeToolCallEvent` for a
48
94
  * delegation tool whose input carries the flag and which no hook cancelled — and
49
95
  * yields the hook-observed `AfterToolCallEvent` for those ids in front of the next SDK
50
- * event. Ids a stream `afterToolCallEvent` closes are dropped (a denied or
51
- * foreground call). Anything left over when a turn ends — a task still cancelling
52
- * after Ctrl+C — is discarded at the start of the next turn: the SDK delivers that
53
- * task's result pair before the next model call itself, and the transcript already
54
- * shows the cancelled turn.
96
+ * event. Ids a stream `afterToolCallEvent` closes are dropped (a denied or foreground
97
+ * call); so is an id whose `toolResultEvent` is not an ack (admission failed: no run
98
+ * follows). The ledger is **not** reset per stream: with `waitForCompletion: false` a
99
+ * child outlives the turn that dispatched it, so an id stays pending across turns, an
100
+ * `AfterToolCallEvent` that arrives between turns is buffered and yielded at the next
101
+ * stream's start, and the recorder and every driver still see exactly one
102
+ * before/after pair per delegation. An entry leaves the ledger when the SDK delivers
103
+ * its result pair — the `messageAddedEvent` whose tool result carries the task id —
104
+ * which is also the moment the SDK stops tracking the task, so {@link list} is what
105
+ * `/clear` and `/rewind` consult before the SDK's `assertCanLoadSnapshot` would throw.
106
+ * Settlement listeners fire once per task, from the hook, with the terminal snapshot.
55
107
  */
56
108
  export declare class BackgroundDelegationObserver {
57
109
  private readonly delegationTools;
58
110
  private readonly pending;
111
+ private readonly listeners;
59
112
  private ready;
60
113
  constructor(delegationTools: readonly string[]);
61
114
  /** Registers the hook on the parent; call once, after construction. */
62
115
  install(agent: Agent): void;
63
- /** Tool-use ids routed to the background in the current turn and not yet settled. */
116
+ private publish;
117
+ /** Tool-use ids routed to the background and not yet settled. */
64
118
  get pendingCount(): number;
119
+ /** Every delegation the SDK still tracks, running or settled-undelivered, in dispatch order. */
120
+ list(): BackgroundDelegationStatus[];
121
+ /** Publishes each task's one terminal snapshot until the returned closure is called. */
122
+ subscribe(listener: BackgroundDelegationListener): () => void;
65
123
  observe(events: AsyncIterable<AgentStreamEvent>): AsyncIterable<AgentStreamEvent>;
66
124
  private drain;
67
125
  }
@@ -12,13 +12,24 @@
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
- * - with `waitForCompletion: true`, `AfterInvocationEvent` waits for every tracked
16
- * task, then `_deliverReady` appends one synthetic
17
- * `strands_background_task_result` tool-use/tool-result pair through
18
- * `continuations.addInput` and the same invocation makes another model call — so a
19
- * result never crosses into a later user turn;
15
+ * - delivers a finished task as one synthetic `strands_background_task_result`
16
+ * tool-use/tool-result pair through `continuations.addInput`, from two hooks: at
17
+ * every `BeforeModelCallEvent` (`_deliverReady`, so a task that settled since the
18
+ * last call rides the next request) and at `AfterInvocationEvent` — where, with
19
+ * `waitForCompletion: true`, it first waits for every tracked task so the same
20
+ * invocation makes another model call, and with `false` it delivers only what is
21
+ * already terminal and lets the invocation end;
20
22
  * - registers `strands_manage_background_task` (`list`/`get`/`cancel`) on the parent.
21
23
  *
24
+ * SER-070 chooses the mode per runtime: a driver that drains completion wakes (the
25
+ * TUI, `RuntimeOptions.backgroundCompletionWakes`) passes `false`, so the dispatching
26
+ * turn ends after the ack and the user keeps prompting; the child's settlement then
27
+ * starts one wake turn when the session is idle, and the SDK's own before-model-call
28
+ * delivery attaches the report to that turn's request. Headless runs have no later
29
+ * turn for a report to arrive in, so they keep `true` and the result stays inside the
30
+ * one `run.*` cycle. In both modes the report reaches the model through the SDK only —
31
+ * darwin never copies it.
32
+ *
22
33
  * Two of its events do not travel down the parent's stream, and that is what the
23
34
  * observer below exists for. The background run's real `AfterToolCallEvent` is
24
35
  * delivered to hook callbacks only (`ToolExecutor.executeBackground` → the agent's
@@ -32,9 +43,13 @@
32
43
  * SDK object, unmodified — into the stream `AgentRuntime.send()` hands to its
33
44
  * consumers, ahead of the next SDK event. Only calls the stream itself showed as
34
45
  * routed to the background are forwarded; every foreground `AfterToolCallEvent` is
35
- * yielded by the SDK and left alone.
46
+ * yielded by the SDK and left alone. The same hook is the settlement trigger for the
47
+ * wake: it fires once per background run, exactly when the run's body returns (the
48
+ * dispatch registry's listener fires per *child*, so a `workflow` of several nodes
49
+ * would fire several times for one task, and it knows dispatch ids, not task ids).
36
50
  */
37
51
  import { AfterToolCallEvent, HookOrder } from '@strands-agents/sdk';
52
+ import { shortDispatchId } from '../agents/dispatch-registry.js';
38
53
  /** The per-call selector the SDK middleware adds to `agentic` tool specs. */
39
54
  export const BACKGROUND_EXECUTION_FLAG = '_background_execution';
40
55
  /** The SDK's own management tool; parent-only, classified in `permission.ts`. */
@@ -52,6 +67,8 @@ const ACK_TASK_ID = /^Task ID: (\S+)$/mu;
52
67
  * plugin's own manage tool) is `never` as well rather than falling back to the SDK's
53
68
  * `agentic` default for unnamed tools. The SDK rejects a name listed under two modes,
54
69
  * so a delegation tool is removed from `never` if a caller passes it in both lists.
70
+ * `waitForCompletion` is the one per-runtime choice (SER-070): `false` when the driver
71
+ * wakes on settlement, `true` otherwise.
55
72
  */
56
73
  export function backgroundDelegationConfig(input) {
57
74
  const agentic = [...new Set(input.delegationTools)];
@@ -59,7 +76,7 @@ export function backgroundDelegationConfig(input) {
59
76
  return {
60
77
  agentic,
61
78
  never: [...never, '*'],
62
- waitForCompletion: true,
79
+ waitForCompletion: !input.completionWakes,
63
80
  maxConcurrency: input.maxConcurrency,
64
81
  };
65
82
  }
@@ -73,12 +90,20 @@ export function backgroundExecutionRequested(input) {
73
90
  /**
74
91
  * The one sentence both delegation tool descriptions carry. The flag itself is
75
92
  * added to the spec by the SDK middleware, so the description only has to say when
76
- * to use it and when the result comes back.
93
+ * to use it and when the result comes back — which depends on the runtime
94
+ * (SER-070): a waking runtime lets the turn end and delivers the report in the next
95
+ * turn that runs; every other runtime delivers it before the next model call of the
96
+ * same turn, byte-identical to the pre-SER-070 sentence.
77
97
  */
78
- export function backgroundDelegationDescriptionClause() {
79
- return (`Set ${BACKGROUND_EXECUTION_FLAG}: true to run this call in the background when you do not ` +
80
- 'need its result immediately (reads only): you get an acknowledgement at once and the ' +
81
- 'final report is delivered before your next model call in this same turn.');
98
+ export function backgroundDelegationDescriptionClause(completionWakes = false) {
99
+ const lead = `Set ${BACKGROUND_EXECUTION_FLAG}: true to run this call in the background when you do not ` +
100
+ 'need its result immediately (reads only): you get an acknowledgement at once and the ';
101
+ return completionWakes
102
+ ? lead +
103
+ 'final report arrives as a strands_background_task_result tool result in the next turn ' +
104
+ 'that runs — you may end this turn; once the session is idle, one <task-notification> ' +
105
+ 'turn starts with the report attached.'
106
+ : lead + 'final report is delivered before your next model call in this same turn.';
82
107
  }
83
108
  /**
84
109
  * The task id inside the SDK's dispatch acknowledgement, or `undefined` for any
@@ -97,23 +122,62 @@ export function backgroundAckTaskId(content) {
97
122
  }
98
123
  return undefined;
99
124
  }
125
+ /** The first eight characters of an SDK task id (a UUID) — enough to tell tasks apart in a row. */
126
+ export function shortBackgroundTaskId(taskId) {
127
+ return taskId.length > 8 ? taskId.slice(0, 8) : taskId;
128
+ }
100
129
  /**
101
- * Forwards background runs' `AfterToolCallEvent`s into the parent's stream.
130
+ * The one refusal `/clear` and `/rewind` give while a background delegation is
131
+ * tracked (SER-070): the live task ids and the two ways out. Never a partial restore,
132
+ * never a silent cancel of minutes of child work — the same rule as the SER-027 busy
133
+ * refusal. Shared by the TUI's local check and the runtime's own guard, so the two
134
+ * cannot word it differently.
135
+ */
136
+ export function liveBackgroundDelegationRefusal(command, tasks) {
137
+ const named = tasks
138
+ .map((task) => task.toolName === 'subagent'
139
+ ? `subagent #${shortDispatchId(task.toolUseId)} (task ${task.taskId}, ${task.state})`
140
+ : `${task.toolName} (task ${task.taskId}, ${task.state}; /agents lists its node ids)`)
141
+ .join(', ');
142
+ return (`${command} refused — ${tasks.length === 1 ? 'a background delegation is' : `${tasks.length} background delegations are`} ` +
143
+ `still tracked: ${named}. Cancel with /agents cancel <id>, or wait for the completion wake to deliver the report; then retry.`);
144
+ }
145
+ function snapshot(entry) {
146
+ return {
147
+ taskId: entry.taskId,
148
+ toolUseId: entry.toolUseId,
149
+ toolName: entry.toolName,
150
+ input: entry.input,
151
+ startedAt: entry.startedAt,
152
+ settledAt: entry.settledAt,
153
+ state: entry.state,
154
+ };
155
+ }
156
+ /**
157
+ * Forwards background runs' `AfterToolCallEvent`s into the parent's stream and keeps
158
+ * the parent-side ledger of tracked delegations (SER-064, SER-070).
102
159
  *
103
160
  * One instance per parent Agent; {@link observe} wraps exactly one `Agent.stream()`
104
- * at a time (the runtime serializes turns). Per turn it remembers which tool-use ids
105
- * the stream showed as routed to the background — a `beforeToolCallEvent` for a
161
+ * at a time (the runtime serializes turns). It remembers which tool-use ids the
162
+ * stream showed as routed to the background — a `beforeToolCallEvent` for a
106
163
  * delegation tool whose input carries the flag and which no hook cancelled — and
107
164
  * yields the hook-observed `AfterToolCallEvent` for those ids in front of the next SDK
108
- * event. Ids a stream `afterToolCallEvent` closes are dropped (a denied or
109
- * foreground call). Anything left over when a turn ends — a task still cancelling
110
- * after Ctrl+C — is discarded at the start of the next turn: the SDK delivers that
111
- * task's result pair before the next model call itself, and the transcript already
112
- * shows the cancelled turn.
165
+ * event. Ids a stream `afterToolCallEvent` closes are dropped (a denied or foreground
166
+ * call); so is an id whose `toolResultEvent` is not an ack (admission failed: no run
167
+ * follows). The ledger is **not** reset per stream: with `waitForCompletion: false` a
168
+ * child outlives the turn that dispatched it, so an id stays pending across turns, an
169
+ * `AfterToolCallEvent` that arrives between turns is buffered and yielded at the next
170
+ * stream's start, and the recorder and every driver still see exactly one
171
+ * before/after pair per delegation. An entry leaves the ledger when the SDK delivers
172
+ * its result pair — the `messageAddedEvent` whose tool result carries the task id —
173
+ * which is also the moment the SDK stops tracking the task, so {@link list} is what
174
+ * `/clear` and `/rewind` consult before the SDK's `assertCanLoadSnapshot` would throw.
175
+ * Settlement listeners fire once per task, from the hook, with the terminal snapshot.
113
176
  */
114
177
  export class BackgroundDelegationObserver {
115
178
  delegationTools;
116
- pending = new Set();
179
+ pending = new Map();
180
+ listeners = new Set();
117
181
  ready = [];
118
182
  constructor(delegationTools) {
119
183
  this.delegationTools = new Set(delegationTools);
@@ -121,28 +185,92 @@ export class BackgroundDelegationObserver {
121
185
  /** Registers the hook on the parent; call once, after construction. */
122
186
  install(agent) {
123
187
  agent.addHook(AfterToolCallEvent, (event) => {
124
- if (this.pending.delete(event.toolUse.toolUseId))
125
- this.ready.push(event);
188
+ const entry = this.pending.get(event.toolUse.toolUseId);
189
+ if (entry === undefined)
190
+ return;
191
+ this.ready.push(event);
192
+ entry.settledAt = new Date().toISOString();
193
+ entry.state = event.result.status === 'error' ? 'failed' : 'succeeded';
194
+ // A run so short that its body returned before the stream yielded the ack
195
+ // is published when the ack names the task (see `toolResultEvent` below).
196
+ if (entry.taskId !== undefined)
197
+ this.publish(snapshot({ ...entry, taskId: entry.taskId }));
126
198
  }, { order: HookOrder.SDK_LAST });
127
199
  }
128
- /** Tool-use ids routed to the background in the current turn and not yet settled. */
200
+ publish(status) {
201
+ for (const listener of this.listeners)
202
+ listener(status);
203
+ }
204
+ /** Tool-use ids routed to the background and not yet settled. */
129
205
  get pendingCount() {
130
- return this.pending.size;
206
+ let count = 0;
207
+ for (const entry of this.pending.values())
208
+ if (entry.state === 'running')
209
+ count += 1;
210
+ return count;
211
+ }
212
+ /** Every delegation the SDK still tracks, running or settled-undelivered, in dispatch order. */
213
+ list() {
214
+ const tracked = [];
215
+ for (const entry of this.pending.values()) {
216
+ if (entry.taskId !== undefined)
217
+ tracked.push(snapshot({ ...entry, taskId: entry.taskId }));
218
+ }
219
+ return tracked;
220
+ }
221
+ /** Publishes each task's one terminal snapshot until the returned closure is called. */
222
+ subscribe(listener) {
223
+ this.listeners.add(listener);
224
+ return () => {
225
+ this.listeners.delete(listener);
226
+ };
131
227
  }
132
228
  async *observe(events) {
133
- this.pending.clear();
134
- this.ready = [];
229
+ // A settlement that arrived between turns is the first thing the new stream shows.
230
+ yield* this.drain();
135
231
  for await (const event of events) {
136
232
  if (event.type === 'beforeToolCallEvent') {
137
233
  if (!event.cancel &&
138
234
  this.delegationTools.has(event.toolUse.name) &&
139
235
  backgroundExecutionRequested(event.toolUse.input)) {
140
- this.pending.add(event.toolUse.toolUseId);
236
+ this.pending.set(event.toolUse.toolUseId, {
237
+ taskId: undefined,
238
+ toolUseId: event.toolUse.toolUseId,
239
+ toolName: event.toolUse.name,
240
+ input: event.toolUse.input,
241
+ startedAt: new Date().toISOString(),
242
+ settledAt: null,
243
+ state: 'running',
244
+ });
141
245
  }
142
246
  }
143
247
  else if (event.type === 'afterToolCallEvent') {
144
248
  this.pending.delete(event.toolUse.toolUseId);
145
249
  }
250
+ else if (event.type === 'toolResultEvent') {
251
+ const entry = this.pending.get(event.result.toolUseId);
252
+ if (entry !== undefined && entry.taskId === undefined) {
253
+ const taskId = event.result.status === 'error' ? undefined : backgroundAckTaskId(event.result.content);
254
+ if (taskId === undefined) {
255
+ this.pending.delete(entry.toolUseId);
256
+ }
257
+ else {
258
+ entry.taskId = taskId;
259
+ if (entry.state !== 'running')
260
+ this.publish(snapshot({ ...entry, taskId }));
261
+ }
262
+ }
263
+ }
264
+ else if (event.type === 'messageAddedEvent' && event.message.role === 'user') {
265
+ for (const block of event.message.content) {
266
+ if (block.type !== 'toolResultBlock')
267
+ continue;
268
+ for (const entry of this.pending.values()) {
269
+ if (entry.taskId === block.toolUseId)
270
+ this.pending.delete(entry.toolUseId);
271
+ }
272
+ }
273
+ }
146
274
  yield* this.drain();
147
275
  yield event;
148
276
  }
@@ -1 +1 @@
1
- {"version":3,"file":"background-delegation.js","sourceRoot":"","sources":["../../../src/agent/background-delegation.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"background-delegation.js","sourceRoot":"","sources":["../../../src/agent/background-delegation.ts"],"names":[],"mappings":"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"}
@@ -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
+ }