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.
- package/README.md +3 -1
- package/README.zh-CN.md +3 -1
- package/dist/src/agent/background-delegation.d.ts +69 -11
- package/dist/src/agent/background-delegation.js +156 -28
- package/dist/src/agent/background-delegation.js.map +1 -1
- package/dist/src/agent/cache-miss.d.ts +143 -0
- package/dist/src/agent/cache-miss.js +182 -0
- package/dist/src/agent/cache-miss.js.map +1 -0
- package/dist/src/agent/compact.d.ts +28 -0
- package/dist/src/agent/compact.js +34 -0
- package/dist/src/agent/compact.js.map +1 -1
- package/dist/src/agent/context-breakdown.d.ts +109 -0
- package/dist/src/agent/context-breakdown.js +116 -0
- package/dist/src/agent/context-breakdown.js.map +1 -0
- package/dist/src/agent/instructions.d.ts +1 -1
- package/dist/src/agent/instructions.js.map +1 -1
- package/dist/src/agent/permission-rules.d.ts +81 -2
- package/dist/src/agent/permission-rules.js +226 -6
- package/dist/src/agent/permission-rules.js.map +1 -1
- package/dist/src/agent/permission.d.ts +116 -2
- package/dist/src/agent/permission.js +201 -26
- package/dist/src/agent/permission.js.map +1 -1
- package/dist/src/agent/prompt-cache.d.ts +12 -3
- package/dist/src/agent/prompt-cache.js +12 -3
- package/dist/src/agent/prompt-cache.js.map +1 -1
- package/dist/src/agent/runtime.d.ts +141 -1
- package/dist/src/agent/runtime.js +259 -13
- package/dist/src/agent/runtime.js.map +1 -1
- package/dist/src/agent/task-terminal-delivery.d.ts +43 -0
- package/dist/src/agent/task-terminal-delivery.js +115 -0
- package/dist/src/agent/task-terminal-delivery.js.map +1 -0
- package/dist/src/agents/child-recipe.d.ts +9 -1
- package/dist/src/agents/child-recipe.js +2 -0
- package/dist/src/agents/child-recipe.js.map +1 -1
- package/dist/src/agents/dispatch-registry.d.ts +18 -0
- package/dist/src/agents/dispatch-registry.js +2 -0
- package/dist/src/agents/dispatch-registry.js.map +1 -1
- package/dist/src/agents/retained-children.d.ts +101 -0
- package/dist/src/agents/retained-children.js +101 -0
- package/dist/src/agents/retained-children.js.map +1 -0
- package/dist/src/agents/subagent-tool.d.ts +56 -1
- package/dist/src/agents/subagent-tool.js +148 -10
- package/dist/src/agents/subagent-tool.js.map +1 -1
- package/dist/src/agents/workflow-tool.d.ts +2 -0
- package/dist/src/agents/workflow-tool.js +1 -1
- package/dist/src/agents/workflow-tool.js.map +1 -1
- package/dist/src/cli-doctor.js +3 -1
- package/dist/src/cli-doctor.js.map +1 -1
- package/dist/src/cli-main.js +14 -3
- package/dist/src/cli-main.js.map +1 -1
- package/dist/src/commands/custom-commands.js +5 -4
- package/dist/src/commands/custom-commands.js.map +1 -1
- package/dist/src/config.d.ts +57 -6
- package/dist/src/config.js +43 -16
- package/dist/src/config.js.map +1 -1
- package/dist/src/headless-protocol.d.ts +1 -1
- package/dist/src/headless-runner.js +7 -2
- package/dist/src/headless-runner.js.map +1 -1
- package/dist/src/hooks/tool-hooks.js +10 -6
- package/dist/src/hooks/tool-hooks.js.map +1 -1
- package/dist/src/skills/builtin/self-evolution-research/SKILL.md +14 -1
- package/dist/src/skills/prompt.d.ts +17 -0
- package/dist/src/skills/prompt.js +20 -0
- package/dist/src/skills/prompt.js.map +1 -1
- package/dist/src/tools/background-bash.d.ts +11 -2
- package/dist/src/tools/background-bash.js +11 -5
- package/dist/src/tools/background-bash.js.map +1 -1
- package/dist/src/tools/background-tail.d.ts +1 -0
- package/dist/src/tools/background-tail.js +2 -1
- package/dist/src/tools/background-tail.js.map +1 -1
- package/dist/src/tools/background-wait-contract.d.ts +7 -0
- package/dist/src/tools/background-wait-contract.js +17 -0
- package/dist/src/tools/background-wait-contract.js.map +1 -1
- package/dist/src/trajectory/record.d.ts +212 -2
- package/dist/src/trajectory/record.js +138 -0
- package/dist/src/trajectory/record.js.map +1 -1
- package/dist/src/trajectory/replay.d.ts +34 -1
- package/dist/src/trajectory/replay.js +148 -4
- package/dist/src/trajectory/replay.js.map +1 -1
- package/dist/src/trajectory/resume-recap.js +10 -3
- package/dist/src/trajectory/resume-recap.js.map +1 -1
- package/dist/src/trajectory/spend.d.ts +14 -1
- package/dist/src/trajectory/spend.js +40 -6
- package/dist/src/trajectory/spend.js.map +1 -1
- package/dist/src/trajectory/writer.d.ts +57 -6
- package/dist/src/trajectory/writer.js +141 -9
- package/dist/src/trajectory/writer.js.map +1 -1
- package/dist/src/tui/App.d.ts +8 -4
- package/dist/src/tui/App.js +302 -55
- package/dist/src/tui/App.js.map +1 -1
- package/dist/src/tui/background-tool-presentation.js +2 -2
- package/dist/src/tui/background-tool-presentation.js.map +1 -1
- package/dist/src/tui/context-format.d.ts +16 -0
- package/dist/src/tui/context-format.js +41 -0
- package/dist/src/tui/context-format.js.map +1 -1
- package/dist/src/tui/prompt-queue.d.ts +52 -8
- package/dist/src/tui/prompt-queue.js +68 -8
- package/dist/src/tui/prompt-queue.js.map +1 -1
- package/dist/src/tui/status-format.d.ts +35 -16
- package/dist/src/tui/status-format.js +67 -8
- package/dist/src/tui/status-format.js.map +1 -1
- package/dist/src/tui/subagent-format.d.ts +8 -0
- package/dist/src/tui/subagent-format.js +24 -1
- package/dist/src/tui/subagent-format.js.map +1 -1
- package/dist/src/tui/task-wake.d.ts +75 -0
- package/dist/src/tui/task-wake.js +201 -0
- package/dist/src/tui/task-wake.js.map +1 -0
- package/dist/src/tui/terminal-notify.d.ts +40 -0
- package/dist/src/tui/terminal-notify.js +136 -0
- package/dist/src/tui/terminal-notify.js.map +1 -0
- package/dist/src/tui/terminal-title.d.ts +94 -0
- package/dist/src/tui/terminal-title.js +121 -0
- package/dist/src/tui/terminal-title.js.map +1 -0
- package/dist/src/tui/turn-state.d.ts +10 -1
- package/dist/src/tui/turn-state.js +17 -1
- package/dist/src/tui/turn-state.js.map +1 -1
- 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).
|
|
47
|
-
*
|
|
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
|
-
*
|
|
52
|
-
*
|
|
53
|
-
*
|
|
54
|
-
*
|
|
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
|
-
|
|
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
|
-
* -
|
|
16
|
-
*
|
|
17
|
-
* `
|
|
18
|
-
*
|
|
19
|
-
*
|
|
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:
|
|
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
|
-
|
|
80
|
-
'need its result immediately (reads only): you get an acknowledgement at once and the '
|
|
81
|
-
|
|
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
|
-
*
|
|
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).
|
|
105
|
-
*
|
|
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
|
-
*
|
|
110
|
-
*
|
|
111
|
-
*
|
|
112
|
-
*
|
|
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
|
|
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
|
-
|
|
125
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
134
|
-
this.
|
|
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.
|
|
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":"AAAA
|
|
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
|
+
}
|