@draht/coding-agent 2026.4.5 → 2026.4.25-1

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 (234) hide show
  1. package/CHANGELOG.md +804 -625
  2. package/README.md +24 -15
  3. package/dist/cli/args.d.ts +7 -10
  4. package/dist/cli/args.d.ts.map +1 -1
  5. package/dist/cli/args.js +44 -46
  6. package/dist/cli/args.js.map +1 -1
  7. package/dist/cli.d.ts.map +1 -1
  8. package/dist/cli.js +1 -0
  9. package/dist/cli.js.map +1 -1
  10. package/dist/config.d.ts +9 -0
  11. package/dist/config.d.ts.map +1 -1
  12. package/dist/config.js +18 -0
  13. package/dist/config.js.map +1 -1
  14. package/dist/core/agent-session-runtime.d.ts +53 -106
  15. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  16. package/dist/core/agent-session-runtime.js +116 -147
  17. package/dist/core/agent-session-runtime.js.map +1 -1
  18. package/dist/core/agent-session-services.d.ts +86 -0
  19. package/dist/core/agent-session-services.d.ts.map +1 -0
  20. package/dist/core/agent-session-services.js +116 -0
  21. package/dist/core/agent-session-services.js.map +1 -0
  22. package/dist/core/agent-session.d.ts +8 -12
  23. package/dist/core/agent-session.d.ts.map +1 -1
  24. package/dist/core/agent-session.js +134 -45
  25. package/dist/core/agent-session.js.map +1 -1
  26. package/dist/core/bash-executor.d.ts.map +1 -1
  27. package/dist/core/bash-executor.js +19 -7
  28. package/dist/core/bash-executor.js.map +1 -1
  29. package/dist/core/compaction/compaction.d.ts +1 -1
  30. package/dist/core/compaction/compaction.d.ts.map +1 -1
  31. package/dist/core/compaction/compaction.js +18 -17
  32. package/dist/core/compaction/compaction.js.map +1 -1
  33. package/dist/core/extensions/index.d.ts +1 -1
  34. package/dist/core/extensions/index.d.ts.map +1 -1
  35. package/dist/core/extensions/index.js.map +1 -1
  36. package/dist/core/extensions/loader.d.ts.map +1 -1
  37. package/dist/core/extensions/loader.js +7 -7
  38. package/dist/core/extensions/loader.js.map +1 -1
  39. package/dist/core/extensions/runner.d.ts +1 -0
  40. package/dist/core/extensions/runner.d.ts.map +1 -1
  41. package/dist/core/extensions/runner.js +4 -0
  42. package/dist/core/extensions/runner.js.map +1 -1
  43. package/dist/core/extensions/types.d.ts +15 -14
  44. package/dist/core/extensions/types.d.ts.map +1 -1
  45. package/dist/core/extensions/types.js.map +1 -1
  46. package/dist/core/index.d.ts +2 -1
  47. package/dist/core/index.d.ts.map +1 -1
  48. package/dist/core/index.js +2 -1
  49. package/dist/core/index.js.map +1 -1
  50. package/dist/core/keybindings.d.ts +14 -1
  51. package/dist/core/keybindings.d.ts.map +1 -1
  52. package/dist/core/keybindings.js +13 -14
  53. package/dist/core/keybindings.js.map +1 -1
  54. package/dist/core/model-registry.d.ts.map +1 -1
  55. package/dist/core/model-registry.js +31 -1
  56. package/dist/core/model-registry.js.map +1 -1
  57. package/dist/core/package-manager.d.ts +21 -1
  58. package/dist/core/package-manager.d.ts.map +1 -1
  59. package/dist/core/package-manager.js +108 -43
  60. package/dist/core/package-manager.js.map +1 -1
  61. package/dist/core/prompt-templates.d.ts.map +1 -1
  62. package/dist/core/prompt-templates.js +22 -21
  63. package/dist/core/prompt-templates.js.map +1 -1
  64. package/dist/core/resource-loader.d.ts +0 -2
  65. package/dist/core/resource-loader.d.ts.map +1 -1
  66. package/dist/core/resource-loader.js +26 -8
  67. package/dist/core/resource-loader.js.map +1 -1
  68. package/dist/core/sdk.d.ts +2 -2
  69. package/dist/core/sdk.d.ts.map +1 -1
  70. package/dist/core/sdk.js +2 -2
  71. package/dist/core/sdk.js.map +1 -1
  72. package/dist/core/session-cwd.d.ts +19 -0
  73. package/dist/core/session-cwd.d.ts.map +1 -0
  74. package/dist/core/session-cwd.js +38 -0
  75. package/dist/core/session-cwd.js.map +1 -0
  76. package/dist/core/session-manager.d.ts +5 -1
  77. package/dist/core/session-manager.d.ts.map +1 -1
  78. package/dist/core/session-manager.js +16 -8
  79. package/dist/core/session-manager.js.map +1 -1
  80. package/dist/core/settings-manager.d.ts +6 -4
  81. package/dist/core/settings-manager.d.ts.map +1 -1
  82. package/dist/core/settings-manager.js +5 -1
  83. package/dist/core/settings-manager.js.map +1 -1
  84. package/dist/core/skills.d.ts +1 -1
  85. package/dist/core/skills.d.ts.map +1 -1
  86. package/dist/core/skills.js +3 -3
  87. package/dist/core/skills.js.map +1 -1
  88. package/dist/core/system-prompt.d.ts.map +1 -1
  89. package/dist/core/system-prompt.js +6 -6
  90. package/dist/core/system-prompt.js.map +1 -1
  91. package/dist/core/timings.d.ts +1 -0
  92. package/dist/core/timings.d.ts.map +1 -1
  93. package/dist/core/timings.js +6 -0
  94. package/dist/core/timings.js.map +1 -1
  95. package/dist/core/tools/bash.d.ts.map +1 -1
  96. package/dist/core/tools/bash.js +19 -9
  97. package/dist/core/tools/bash.js.map +1 -1
  98. package/dist/core/tools/edit-diff.d.ts +23 -1
  99. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  100. package/dist/core/tools/edit-diff.js +150 -57
  101. package/dist/core/tools/edit-diff.js.map +1 -1
  102. package/dist/core/tools/edit.d.ts +13 -11
  103. package/dist/core/tools/edit.d.ts.map +1 -1
  104. package/dist/core/tools/edit.js +55 -77
  105. package/dist/core/tools/edit.js.map +1 -1
  106. package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
  107. package/dist/core/tools/file-mutation-queue.js +4 -4
  108. package/dist/core/tools/file-mutation-queue.js.map +1 -1
  109. package/dist/core/tools/index.d.ts +9 -6
  110. package/dist/core/tools/index.d.ts.map +1 -1
  111. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  112. package/dist/core/tools/tool-definition-wrapper.js +2 -0
  113. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  114. package/dist/index.d.ts +4 -4
  115. package/dist/index.d.ts.map +1 -1
  116. package/dist/index.js +4 -5
  117. package/dist/index.js.map +1 -1
  118. package/dist/main.d.ts.map +1 -1
  119. package/dist/main.js +252 -451
  120. package/dist/main.js.map +1 -1
  121. package/dist/migrations.d.ts +3 -3
  122. package/dist/migrations.d.ts.map +1 -1
  123. package/dist/migrations.js +25 -5
  124. package/dist/migrations.js.map +1 -1
  125. package/dist/modes/interactive/components/assistant-message.d.ts +3 -1
  126. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  127. package/dist/modes/interactive/components/assistant-message.js +14 -3
  128. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  129. package/dist/modes/interactive/components/earendil-announcement.d.ts +5 -0
  130. package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -0
  131. package/dist/modes/interactive/components/earendil-announcement.js +40 -0
  132. package/dist/modes/interactive/components/earendil-announcement.js.map +1 -0
  133. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  134. package/dist/modes/interactive/components/settings-selector.js +1 -0
  135. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  136. package/dist/modes/interactive/components/thinking-selector.d.ts.map +1 -1
  137. package/dist/modes/interactive/components/thinking-selector.js +1 -0
  138. package/dist/modes/interactive/components/thinking-selector.js.map +1 -1
  139. package/dist/modes/interactive/components/tool-execution.d.ts +0 -1
  140. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  141. package/dist/modes/interactive/components/tool-execution.js +2 -7
  142. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  143. package/dist/modes/interactive/components/tree-selector.d.ts +4 -2
  144. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  145. package/dist/modes/interactive/components/tree-selector.js +48 -15
  146. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  147. package/dist/modes/interactive/interactive-mode.d.ts +12 -3
  148. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  149. package/dist/modes/interactive/interactive-mode.js +237 -125
  150. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  151. package/dist/modes/interactive/theme/dark.json +8 -5
  152. package/dist/modes/interactive/theme/light.json +8 -5
  153. package/dist/modes/interactive/theme/theme-schema.json +6 -1
  154. package/dist/modes/interactive/theme/theme.d.ts +2 -2
  155. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  156. package/dist/modes/interactive/theme/theme.js +13 -1
  157. package/dist/modes/interactive/theme/theme.js.map +1 -1
  158. package/dist/modes/print-mode.d.ts +4 -4
  159. package/dist/modes/print-mode.d.ts.map +1 -1
  160. package/dist/modes/print-mode.js +6 -2
  161. package/dist/modes/print-mode.js.map +1 -1
  162. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  163. package/dist/modes/rpc/rpc-client.js +1 -0
  164. package/dist/modes/rpc/rpc-client.js.map +1 -1
  165. package/dist/modes/rpc/rpc-mode.d.ts +2 -2
  166. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  167. package/dist/modes/rpc/rpc-mode.js +26 -15
  168. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  169. package/dist/package-manager-cli.d.ts +4 -0
  170. package/dist/package-manager-cli.d.ts.map +1 -0
  171. package/dist/package-manager-cli.js +234 -0
  172. package/dist/package-manager-cli.js.map +1 -0
  173. package/dist/prompts/commands/atomic-commit.md +17 -0
  174. package/dist/prompts/commands/discuss-phase.md +15 -0
  175. package/dist/prompts/commands/execute-phase.md +14 -0
  176. package/dist/prompts/commands/fix.md +14 -0
  177. package/dist/prompts/commands/init-project.md +16 -0
  178. package/dist/prompts/commands/map-codebase.md +16 -0
  179. package/dist/prompts/commands/new-project.md +16 -0
  180. package/dist/prompts/commands/next-milestone.md +16 -0
  181. package/dist/prompts/commands/orchestrate.md +57 -0
  182. package/dist/prompts/commands/pause-work.md +13 -0
  183. package/dist/prompts/commands/plan-phase.md +15 -0
  184. package/dist/prompts/commands/progress.md +13 -0
  185. package/dist/prompts/commands/quick.md +14 -0
  186. package/dist/prompts/commands/resume-work.md +13 -0
  187. package/dist/prompts/commands/review.md +15 -0
  188. package/dist/prompts/commands/verify-work.md +15 -0
  189. package/dist/utils/paths.d.ts +7 -0
  190. package/dist/utils/paths.d.ts.map +1 -0
  191. package/dist/utils/paths.js +19 -0
  192. package/dist/utils/paths.js.map +1 -0
  193. package/docs/compaction.md +5 -3
  194. package/docs/custom-provider.md +1 -1
  195. package/docs/development.md +3 -1
  196. package/docs/extensions.md +150 -54
  197. package/docs/json.md +5 -2
  198. package/docs/keybindings.md +2 -0
  199. package/docs/models.md +55 -4
  200. package/docs/rpc.md +21 -7
  201. package/docs/sdk.md +116 -48
  202. package/docs/session.md +3 -3
  203. package/docs/settings.md +12 -0
  204. package/docs/skills.md +3 -2
  205. package/docs/tree.md +5 -2
  206. package/examples/README.md +1 -1
  207. package/examples/extensions/README.md +1 -0
  208. package/examples/extensions/antigravity-image-gen.ts +1 -1
  209. package/examples/extensions/custom-provider-gitlab-duo/index.ts +1 -1
  210. package/examples/extensions/doom-overlay/doom/build.sh +2 -2
  211. package/examples/extensions/hidden-thinking-label.ts +53 -0
  212. package/examples/extensions/overlay-qa-tests.ts +2 -2
  213. package/examples/extensions/sandbox/index.ts +8 -4
  214. package/examples/extensions/subagent/index.ts +5 -5
  215. package/examples/extensions/trigger-compact.ts +11 -1
  216. package/examples/sdk/13-session-runtime.ts +30 -12
  217. package/examples/sdk/README.md +4 -2
  218. package/package.json +7 -8
  219. package/prompts/commands/atomic-commit.md +17 -0
  220. package/prompts/commands/discuss-phase.md +15 -0
  221. package/prompts/commands/execute-phase.md +14 -0
  222. package/prompts/commands/fix.md +14 -0
  223. package/prompts/commands/init-project.md +16 -0
  224. package/prompts/commands/map-codebase.md +16 -0
  225. package/prompts/commands/new-project.md +16 -0
  226. package/prompts/commands/next-milestone.md +16 -0
  227. package/prompts/commands/orchestrate.md +57 -0
  228. package/prompts/commands/pause-work.md +13 -0
  229. package/prompts/commands/plan-phase.md +15 -0
  230. package/prompts/commands/progress.md +13 -0
  231. package/prompts/commands/quick.md +14 -0
  232. package/prompts/commands/resume-work.md +13 -0
  233. package/prompts/commands/review.md +15 -0
  234. package/prompts/commands/verify-work.md +15 -0
@@ -13,6 +13,21 @@ Walk through acceptance testing of completed phase work, using subagents for par
13
13
 
14
14
  Phase: $1
15
15
 
16
+ ## Atomic Reasoning
17
+
18
+ Before verifying, decompose phase acceptance into atomic reasoning units:
19
+
20
+ **For each deliverable:**
21
+ 1. **State the logical component** — What was this deliverable meant to produce? What user value does it provide?
22
+ 2. **Validate independence** — Can this deliverable be tested independently? What are its dependencies?
23
+ 3. **Verify correctness** — What tests prove it works? What edge cases must pass? What security concerns exist?
24
+
25
+ **Synthesize verification strategy:**
26
+ - Group parallel verification tasks (test suite, security audit, code review, domain compliance)
27
+ - Map each deliverable to specific test scenarios and acceptance criteria
28
+ - Identify critical vs optional checks
29
+ - Plan fix strategies for potential failures
30
+
16
31
  ## Steps
17
32
  1. Run `draht-tools extract-deliverables $1` to get testable items
18
33
  2. **Run parallel verification via subagents:**
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Returns true if the value is NOT a package source (npm:, git:, etc.)
3
+ * or a URL protocol. Bare names and relative paths without ./ prefix
4
+ * are considered local.
5
+ */
6
+ export declare function isLocalPath(value: string): boolean;
7
+ //# sourceMappingURL=paths.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAclD","sourcesContent":["/**\n * Returns true if the value is NOT a package source (npm:, git:, etc.)\n * or a URL protocol. Bare names and relative paths without ./ prefix\n * are considered local.\n */\nexport function isLocalPath(value: string): boolean {\n\tconst trimmed = value.trim();\n\t// Known non-local prefixes\n\tif (\n\t\ttrimmed.startsWith(\"npm:\") ||\n\t\ttrimmed.startsWith(\"git:\") ||\n\t\ttrimmed.startsWith(\"github:\") ||\n\t\ttrimmed.startsWith(\"http:\") ||\n\t\ttrimmed.startsWith(\"https:\") ||\n\t\ttrimmed.startsWith(\"ssh:\")\n\t) {\n\t\treturn false;\n\t}\n\treturn true;\n}\n"]}
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Returns true if the value is NOT a package source (npm:, git:, etc.)
3
+ * or a URL protocol. Bare names and relative paths without ./ prefix
4
+ * are considered local.
5
+ */
6
+ export function isLocalPath(value) {
7
+ const trimmed = value.trim();
8
+ // Known non-local prefixes
9
+ if (trimmed.startsWith("npm:") ||
10
+ trimmed.startsWith("git:") ||
11
+ trimmed.startsWith("github:") ||
12
+ trimmed.startsWith("http:") ||
13
+ trimmed.startsWith("https:") ||
14
+ trimmed.startsWith("ssh:")) {
15
+ return false;
16
+ }
17
+ return true;
18
+ }
19
+ //# sourceMappingURL=paths.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAW;IACnD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,2BAA2B;IAC3B,IACC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;QAC1B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;QAC1B,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC;QAC7B,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;QAC3B,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC;QAC5B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EACzB,CAAC;QACF,OAAO,KAAK,CAAC;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AAAA,CACZ","sourcesContent":["/**\n * Returns true if the value is NOT a package source (npm:, git:, etc.)\n * or a URL protocol. Bare names and relative paths without ./ prefix\n * are considered local.\n */\nexport function isLocalPath(value: string): boolean {\n\tconst trimmed = value.trim();\n\t// Known non-local prefixes\n\tif (\n\t\ttrimmed.startsWith(\"npm:\") ||\n\t\ttrimmed.startsWith(\"git:\") ||\n\t\ttrimmed.startsWith(\"github:\") ||\n\t\ttrimmed.startsWith(\"http:\") ||\n\t\ttrimmed.startsWith(\"https:\") ||\n\t\ttrimmed.startsWith(\"ssh:\")\n\t) {\n\t\treturn false;\n\t}\n\treturn true;\n}\n"]}
@@ -2,7 +2,7 @@
2
2
 
3
3
  LLMs have limited context windows. When conversations grow too long, pi uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
4
4
 
5
- **Source files** ([pi-mono](https://github.com/draht-dev/draht)):
5
+ **Source files** ([draht-mono](https://github.com/draht-dev/draht)):
6
6
  - [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Auto-compaction logic
7
7
  - [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
8
8
  - [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
@@ -39,8 +39,8 @@ You can also trigger manually with `/compact [instructions]`, where optional ins
39
39
  ### How It Works
40
40
 
41
41
  1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`) is reached
42
- 2. **Extract messages**: Collect messages from previous compaction (or start) up to cut point
43
- 3. **Generate summary**: Call LLM to summarize with structured format
42
+ 2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
43
+ 3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
44
44
  4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
45
45
  5. **Reload**: Session reloads, using summary + messages from `firstKeptEntryId` onwards
46
46
 
@@ -76,6 +76,8 @@ What the LLM sees:
76
76
  prompt from cmp messages from firstKeptEntryId
77
77
  ```
78
78
 
79
+ On repeated compactions, the summarized span starts at the previous compaction's kept boundary (`firstKeptEntryId`), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Pi also recalculates `tokensBefore` from the rebuilt session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced.
80
+
79
81
  ### Split Turns
80
82
 
81
83
  A "turn" starts with a user message and includes all assistant responses and tool calls until the next user message. Normally, compaction cuts at turn boundaries.
@@ -174,7 +174,7 @@ models: [{
174
174
  compat: {
175
175
  supportsDeveloperRole: false, // use "system" instead of "developer"
176
176
  supportsReasoningEffort: true,
177
- reasoningEffortMap: { // map pi-ai levels to provider values
177
+ reasoningEffortMap: { // map draht-ai levels to provider values
178
178
  minimal: "default",
179
179
  low: "default",
180
180
  medium: "default",
@@ -14,9 +14,11 @@ npm run build
14
14
  Run from source:
15
15
 
16
16
  ```bash
17
- ./pi-test.sh
17
+ /path/to/draht-mono/pi-test.sh
18
18
  ```
19
19
 
20
+ The script can be run from any directory. Pi keeps the caller's current working directory.
21
+
20
22
  ## Forking / Rebranding
21
23
 
22
24
  Configure via `package.json`:
@@ -226,9 +226,8 @@ Run `npm install` in the extension directory, then imports from `node_modules/`
226
226
  ### Lifecycle Overview
227
227
 
228
228
  ```
229
- pi starts (CLI only)
229
+ pi starts
230
230
  │
231
- ├─► session_directory (CLI startup only, no ctx)
232
231
  ├─► session_start { reason: "startup" }
233
232
  └─► resources_discover { reason: "startup" }
234
233
  │
@@ -311,26 +310,6 @@ pi.on("resources_discover", async (event, _ctx) => {
311
310
 
312
311
  See [session.md](session.md) for session storage internals and the SessionManager API.
313
312
 
314
- #### session_directory
315
-
316
- Fired by the `pi` CLI during startup session resolution, before the initial session manager is created.
317
-
318
- This event is:
319
- - CLI-only. It is not emitted in SDK mode.
320
- - Startup-only. It is not emitted for later interactive `/new` or `/resume` actions.
321
- - Bypassed when `--session-dir` is provided.
322
- - Special-cased to receive no `ctx` argument.
323
-
324
- If multiple extensions return `sessionDir`, the last one wins.
325
-
326
- ```typescript
327
- pi.on("session_directory", async (event) => {
328
- return {
329
- sessionDir: `/tmp/pi-sessions/${encodeURIComponent(event.cwd)}`,
330
- };
331
- });
332
- ```
333
-
334
313
  #### session_start
335
314
 
336
315
  Fired when a session is started, loaded, or reloaded.
@@ -359,7 +338,7 @@ pi.on("session_before_switch", async (event, ctx) => {
359
338
  });
360
339
  ```
361
340
 
362
- After a successful switch or new-session action, draht emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "new" | "resume"` and `previousSessionFile`.
341
+ After a successful switch or new-session action, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "new" | "resume"` and `previousSessionFile`.
363
342
  Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
364
343
 
365
344
  #### session_before_fork
@@ -375,7 +354,7 @@ pi.on("session_before_fork", async (event, ctx) => {
375
354
  });
376
355
  ```
377
356
 
378
- After a successful fork, draht emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "fork"` and `previousSessionFile`.
357
+ After a successful fork, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "fork"` and `previousSessionFile`.
379
358
  Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
380
359
 
381
360
  #### session_before_compact / session_compact
@@ -588,17 +567,27 @@ Before `tool_call` runs, pi waits for previously emitted Agent events to finish
588
567
 
589
568
  In the default parallel tool execution mode, sibling tool calls from the same assistant message are preflighted sequentially, then executed concurrently. `tool_call` is not guaranteed to see sibling tool results from that same assistant message in `ctx.sessionManager`.
590
569
 
570
+ `event.input` is mutable. Mutate it in place to patch tool arguments before execution.
571
+
572
+ Behavior guarantees:
573
+ - Mutations to `event.input` affect the actual tool execution
574
+ - Later `tool_call` handlers see mutations made by earlier handlers
575
+ - No re-validation is performed after your mutation
576
+ - Return values from `tool_call` only control blocking via `{ block: true, reason?: string }`
577
+
591
578
  ```typescript
592
579
  import { isToolCallEventType } from "@draht/coding-agent";
593
580
 
594
581
  pi.on("tool_call", async (event, ctx) => {
595
582
  // event.toolName - "bash", "read", "write", "edit", etc.
596
583
  // event.toolCallId
597
- // event.input - tool parameters
584
+ // event.input - tool parameters (mutable)
598
585
 
599
586
  // Built-in tools: no type params needed
600
587
  if (isToolCallEventType("bash", event)) {
601
588
  // event.input is { command: string; timeout?: number }
589
+ event.input.command = `source ~/.profile\n${event.input.command}`;
590
+
602
591
  if (event.input.command.includes("rm -rf")) {
603
592
  return { block: true, reason: "Dangerous command" };
604
593
  }
@@ -642,6 +631,8 @@ Fired after tool execution finishes and before `tool_execution_end` plus the fin
642
631
  - Each handler sees the latest result after previous handler changes
643
632
  - Handlers can return partial patches (`content`, `details`, or `isError`); omitted fields keep their current values
644
633
 
634
+ Use `ctx.signal` for nested async work inside the handler. This lets Esc cancel model calls, `fetch()`, and other abort-aware operations started by the extension.
635
+
645
636
  ```typescript
646
637
  import { isBashToolResult } from "@draht/coding-agent";
647
638
 
@@ -653,6 +644,12 @@ pi.on("tool_result", async (event, ctx) => {
653
644
  // event.details is typed as BashToolDetails
654
645
  }
655
646
 
647
+ const response = await fetch("https://example.com/summarize", {
648
+ method: "POST",
649
+ body: JSON.stringify({ content: event.content }),
650
+ signal: ctx.signal,
651
+ });
652
+
656
653
  // Modify result:
657
654
  return { content: [...], details: {...}, isError: false };
658
655
  });
@@ -740,9 +737,7 @@ Transforms chain across handlers. See [input-transform.ts](../examples/extension
740
737
 
741
738
  ## ExtensionContext
742
739
 
743
- All handlers except `session_directory` receive `ctx: ExtensionContext`.
744
-
745
- `session_directory` is a CLI startup hook and receives only the event.
740
+ All handlers receive `ctx: ExtensionContext`.
746
741
 
747
742
  ### ctx.ui
748
743
 
@@ -772,6 +767,31 @@ ctx.sessionManager.getLeafId() // Current leaf entry ID
772
767
 
773
768
  Access to models and API keys.
774
769
 
770
+ ### ctx.signal
771
+
772
+ The current agent abort signal, or `undefined` when no agent turn is active.
773
+
774
+ Use this for abort-aware nested work started by extension handlers, for example:
775
+ - `fetch(..., { signal: ctx.signal })`
776
+ - model calls that accept `signal`
777
+ - file or process helpers that accept `AbortSignal`
778
+
779
+ `ctx.signal` is typically defined during active turn events such as `tool_call`, `tool_result`, `message_update`, and `turn_end`.
780
+ It is usually `undefined` in idle or non-turn contexts such as session events, extension commands, and shortcuts fired while pi is idle.
781
+
782
+ ```typescript
783
+ pi.on("tool_result", async (event, ctx) => {
784
+ const response = await fetch("https://example.com/api", {
785
+ method: "POST",
786
+ body: JSON.stringify(event),
787
+ signal: ctx.signal,
788
+ });
789
+
790
+ const data = await response.json();
791
+ return { details: data };
792
+ });
793
+ ```
794
+
775
795
  ### ctx.isIdle() / ctx.abort() / ctx.hasPendingMessages()
776
796
 
777
797
  Control flow helpers.
@@ -1020,6 +1040,12 @@ pi.registerTool({
1020
1040
  action: StringEnum(["list", "add"] as const),
1021
1041
  text: Type.Optional(Type.String()),
1022
1042
  }),
1043
+ prepareArguments(args) {
1044
+ // Optional compatibility shim. Runs before schema validation.
1045
+ // Return the current schema shape, for example to fold legacy fields
1046
+ // into the modern parameter object.
1047
+ return args;
1048
+ },
1023
1049
 
1024
1050
  async execute(toolCallId, params, signal, onUpdate, ctx) {
1025
1051
  // Stream progress
@@ -1032,8 +1058,8 @@ pi.registerTool({
1032
1058
  },
1033
1059
 
1034
1060
  // Optional: Custom rendering
1035
- renderCall(args, theme) { ... },
1036
- renderResult(result, options, theme) { ... },
1061
+ renderCall(args, theme, context) { ... },
1062
+ renderResult(result, options, theme, context) { ... },
1037
1063
  });
1038
1064
  ```
1039
1065
 
@@ -1484,6 +1510,14 @@ pi.registerTool({
1484
1510
  action: StringEnum(["list", "add"] as const), // Use StringEnum for Google compatibility
1485
1511
  text: Type.Optional(Type.String()),
1486
1512
  }),
1513
+ prepareArguments(args) {
1514
+ if (!args || typeof args !== "object") return args;
1515
+ const input = args as { action?: string; oldAction?: string };
1516
+ if (typeof input.oldAction === "string" && input.action === undefined) {
1517
+ return { ...input, action: input.oldAction };
1518
+ }
1519
+ return args;
1520
+ },
1487
1521
 
1488
1522
  async execute(toolCallId, params, signal, onUpdate, ctx) {
1489
1523
  // Check for cancellation
@@ -1508,8 +1542,8 @@ pi.registerTool({
1508
1542
  },
1509
1543
 
1510
1544
  // Optional: Custom rendering
1511
- renderCall(args, theme) { ... },
1512
- renderResult(result, options, theme) { ... },
1545
+ renderCall(args, theme, context) { ... },
1546
+ renderResult(result, options, theme, context) { ... },
1513
1547
  });
1514
1548
  ```
1515
1549
 
@@ -1527,6 +1561,53 @@ async execute(toolCallId, params) {
1527
1561
 
1528
1562
  **Important:** Use `StringEnum` from `@draht/ai` for string enums. `Type.Union`/`Type.Literal` doesn't work with Google's API.
1529
1563
 
1564
+ **Argument preparation:** `prepareArguments(args)` is optional. If defined, it runs before schema validation and before `execute()`. Use it to mimic an older accepted input shape when pi resumes an older session whose stored tool call arguments no longer match the current schema. Return the object you want validated against `parameters`. Keep the public schema strict. Do not add deprecated compatibility fields to `parameters` just to keep old resumed sessions working.
1565
+
1566
+ Example: an older session may contain an `edit` tool call with top-level `oldText` and `newText`, while the current schema only accepts `edits: [{ oldText, newText }]`.
1567
+
1568
+ ```typescript
1569
+ pi.registerTool({
1570
+ name: "edit",
1571
+ label: "Edit",
1572
+ description: "Edit a single file using exact text replacement",
1573
+ parameters: Type.Object({
1574
+ path: Type.String(),
1575
+ edits: Type.Array(
1576
+ Type.Object({
1577
+ oldText: Type.String(),
1578
+ newText: Type.String(),
1579
+ }),
1580
+ ),
1581
+ }),
1582
+ prepareArguments(args) {
1583
+ if (!args || typeof args !== "object") return args;
1584
+
1585
+ const input = args as {
1586
+ path?: string;
1587
+ edits?: Array<{ oldText: string; newText: string }>;
1588
+ oldText?: unknown;
1589
+ newText?: unknown;
1590
+ };
1591
+
1592
+ if (typeof input.oldText !== "string" || typeof input.newText !== "string") {
1593
+ return args;
1594
+ }
1595
+
1596
+ return {
1597
+ ...input,
1598
+ edits: [...(input.edits ?? []), { oldText: input.oldText, newText: input.newText }],
1599
+ };
1600
+ },
1601
+ async execute(toolCallId, params, signal, onUpdate, ctx) {
1602
+ // params now matches the current schema
1603
+ return {
1604
+ content: [{ type: "text", text: `Applying ${params.edits.length} edit block(s)` }],
1605
+ details: {},
1606
+ };
1607
+ },
1608
+ });
1609
+ ```
1610
+
1530
1611
  ### Overriding Built-in Tools
1531
1612
 
1532
1613
  Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) by registering a tool with the same name. Interactive mode displays a warning when this happens.
@@ -1544,7 +1625,9 @@ pi --no-tools -e ./my-extension.ts
1544
1625
 
1545
1626
  See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.ts) for a complete example that overrides `read` with logging and access control.
1546
1627
 
1547
- **Rendering:** If your override doesn't provide custom `renderCall`/`renderResult` functions, the built-in renderer is used automatically (syntax highlighting, diffs, etc.). This lets you wrap built-in tools for logging or access control without reimplementing the UI.
1628
+ **Rendering:** Built-in renderer inheritance is resolved per slot. Execution override and rendering override are independent. If your override omits `renderCall`, the built-in `renderCall` is used. If your override omits `renderResult`, the built-in `renderResult` is used. If your override omits both, the built-in renderer is used automatically (syntax highlighting, diffs, etc.). This lets you wrap built-in tools for logging or access control without reimplementing the UI.
1629
+
1630
+ **Prompt metadata:** `promptSnippet` and `promptGuidelines` are not inherited from the built-in tool. If your override should keep those prompt instructions, define them on the override explicitly.
1548
1631
 
1549
1632
  **Your implementation must match the exact result shape**, including the `details` type. The UI and session logic depend on these shapes for rendering and state tracking.
1550
1633
 
@@ -1678,44 +1761,52 @@ export default function (pi: ExtensionAPI) {
1678
1761
 
1679
1762
  ### Custom Rendering
1680
1763
 
1681
- Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how built-in tools render.
1764
+ Tools can provide `renderCall` and `renderResult` for custom TUI display. See [tui.md](tui.md) for the full component API and [tool-execution.ts](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how tool rows are composed.
1765
+
1766
+ Tool output is wrapped in a `Box` that handles padding and background. A defined `renderCall` or `renderResult` must return a `Component`. If a slot renderer is not defined, `tool-execution.ts` uses fallback rendering for that slot.
1682
1767
 
1683
- Tool output is wrapped in a `Box` that handles padding and background. Your render methods return `Component` instances (typically `Text`).
1768
+ `renderCall` and `renderResult` each receive a `context` object with:
1769
+ - `args` - the current tool call arguments
1770
+ - `state` - shared row-local state across `renderCall` and `renderResult`
1771
+ - `lastComponent` - the previously returned component for that slot, if any
1772
+ - `invalidate()` - request a rerender of this tool row
1773
+ - `toolCallId`, `cwd`, `executionStarted`, `argsComplete`, `isPartial`, `expanded`, `showImages`, `isError`
1774
+
1775
+ Use `context.state` for cross-slot shared state. Keep slot-local caches on the returned component instance when you want to reuse and mutate the same component across renders.
1684
1776
 
1685
1777
  #### renderCall
1686
1778
 
1687
- Renders the tool call (before/during execution):
1779
+ Renders the tool call or header:
1688
1780
 
1689
1781
  ```typescript
1690
1782
  import { Text } from "@draht/tui";
1691
1783
 
1692
- renderCall(args, theme) {
1693
- let text = theme.fg("toolTitle", theme.bold("my_tool "));
1694
- text += theme.fg("muted", args.action);
1784
+ renderCall(args, theme, context) {
1785
+ const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
1786
+ let content = theme.fg("toolTitle", theme.bold("my_tool "));
1787
+ content += theme.fg("muted", args.action);
1695
1788
  if (args.text) {
1696
- text += " " + theme.fg("dim", `"${args.text}"`);
1789
+ content += " " + theme.fg("dim", `"${args.text}"`);
1697
1790
  }
1698
- return new Text(text, 0, 0); // 0,0 padding - Box handles it
1791
+ text.setText(content);
1792
+ return text;
1699
1793
  }
1700
1794
  ```
1701
1795
 
1702
1796
  #### renderResult
1703
1797
 
1704
- Renders the tool result:
1798
+ Renders the tool result or output:
1705
1799
 
1706
1800
  ```typescript
1707
- renderResult(result, { expanded, isPartial }, theme) {
1708
- // Handle streaming
1801
+ renderResult(result, { expanded, isPartial }, theme, context) {
1709
1802
  if (isPartial) {
1710
1803
  return new Text(theme.fg("warning", "Processing..."), 0, 0);
1711
1804
  }
1712
1805
 
1713
- // Handle errors
1714
1806
  if (result.details?.error) {
1715
1807
  return new Text(theme.fg("error", `Error: ${result.details.error}`), 0, 0);
1716
1808
  }
1717
1809
 
1718
- // Normal result - support expanded view (Ctrl+O)
1719
1810
  let text = theme.fg("success", "✓ Done");
1720
1811
  if (expanded && result.details?.items) {
1721
1812
  for (const item of result.details.items) {
@@ -1726,6 +1817,8 @@ renderResult(result, { expanded, isPartial }, theme) {
1726
1817
  }
1727
1818
  ```
1728
1819
 
1820
+ If a slot intentionally has no visible content, return an empty `Component` such as an empty `Container`.
1821
+
1729
1822
  #### Keybinding Hints
1730
1823
 
1731
1824
  Use `keyHint()` to display keybinding hints that respect the active keybinding configuration:
@@ -1733,7 +1826,7 @@ Use `keyHint()` to display keybinding hints that respect the active keybinding c
1733
1826
  ```typescript
1734
1827
  import { keyHint } from "@draht/coding-agent";
1735
1828
 
1736
- renderResult(result, { expanded }, theme) {
1829
+ renderResult(result, { expanded }, theme, context) {
1737
1830
  let text = theme.fg("success", "✓ Done");
1738
1831
  if (!expanded) {
1739
1832
  text += ` (${keyHint("app.tools.expand", "to expand")})`;
@@ -1757,16 +1850,19 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
1757
1850
 
1758
1851
  #### Best Practices
1759
1852
 
1760
- - Use `Text` with padding `(0, 0)` - the Box handles padding
1761
- - Use `\n` for multi-line content
1762
- - Handle `isPartial` for streaming progress
1763
- - Support `expanded` for detail on demand
1764
- - Keep default view compact
1853
+ - Use `Text` with padding `(0, 0)`. The Box handles padding.
1854
+ - Use `\n` for multi-line content.
1855
+ - Handle `isPartial` for streaming progress.
1856
+ - Support `expanded` for detail on demand.
1857
+ - Keep default view compact.
1858
+ - Read `context.args` in `renderResult` instead of copying args into `context.state`.
1859
+ - Use `context.state` only for data that must be shared across call and result slots.
1860
+ - Reuse `context.lastComponent` when the same component instance can be updated in place.
1765
1861
 
1766
1862
  #### Fallback
1767
1863
 
1768
- If `renderCall`/`renderResult` is not defined or throws:
1769
- - `renderCall`: Shows tool name
1864
+ If a slot renderer is not defined or throws:
1865
+ - `renderCall`: Shows the tool name
1770
1866
  - `renderResult`: Shows raw text from `content`
1771
1867
 
1772
1868
  ## Custom UI
package/docs/json.md CHANGED
@@ -13,12 +13,15 @@ Events are defined in [`AgentSessionEvent`](https://github.com/draht-dev/draht/b
13
13
  ```typescript
14
14
  type AgentSessionEvent =
15
15
  | AgentEvent
16
- | { type: "auto_compaction_start"; reason: "threshold" | "overflow" }
17
- | { type: "auto_compaction_end"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
16
+ | { type: "queue_update"; steering: readonly string[]; followUp: readonly string[] }
17
+ | { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
18
+ | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
18
19
  | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
19
20
  | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string };
20
21
  ```
21
22
 
23
+ `queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
24
+
22
25
  Base events from [`AgentEvent`](https://github.com/draht-dev/draht/blob/main/packages/agent/src/types.ts#L179):
23
26
 
24
27
  ```typescript
@@ -128,6 +128,8 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
128
128
  |--------|---------|-------------|
129
129
  | `app.tree.foldOrUp` | `ctrl+left`, `alt+left` | Fold current branch segment, or jump to the previous segment start |
130
130
  | `app.tree.unfoldOrDown` | `ctrl+right`, `alt+right` | Unfold current branch segment, or jump to the next segment start or branch end |
131
+ | `app.tree.editLabel` | `shift+l` | Edit the label on the selected tree node |
132
+ | `app.tree.toggleLabelTimestamp` | `shift+t` | Toggle label timestamps in the tree |
131
133
 
132
134
  ## Custom Configuration
133
135
 
package/docs/models.md CHANGED
@@ -90,6 +90,33 @@ Override defaults when you need specific values:
90
90
 
91
91
  The file reloads each time you open `/model`. Edit during session; no restart needed.
92
92
 
93
+ ## Google AI Studio Example
94
+
95
+ Use `google-generative-ai` with a `baseUrl` to add models from Google AI Studio, including custom Gemma 4 entries:
96
+
97
+ ```json
98
+ {
99
+ "providers": {
100
+ "my-google": {
101
+ "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
102
+ "api": "google-generative-ai",
103
+ "apiKey": "GEMINI_API_KEY",
104
+ "models": [
105
+ {
106
+ "id": "gemma-4-31b-it",
107
+ "name": "Gemma 4 31B",
108
+ "input": ["text", "image"],
109
+ "contextWindow": 262144,
110
+ "reasoning": true
111
+ }
112
+ ]
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ The `baseUrl` is required when adding custom models to the `google-generative-ai` API type.
119
+
93
120
  ## Supported APIs
94
121
 
95
122
  | API | Description |
@@ -131,7 +158,7 @@ The `apiKey` and `headers` fields support three formats:
131
158
  "apiKey": "sk-..."
132
159
  ```
133
160
 
134
- For `models.json`, shell commands are resolved at request time. draht intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and draht cannot infer the right one.
161
+ For `models.json`, shell commands are resolved at request time. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
135
162
 
136
163
  If your command is slow, expensive, rate-limited, or should keep using a previous value on transient failures, wrap it in your own script or command that implements the caching or TTL behavior you want.
137
164
 
@@ -278,7 +305,7 @@ For providers with partial OpenAI compatibility, use the `compat` field.
278
305
  | `requiresThinkingAsText` | Convert thinking blocks to plain text |
279
306
  | `thinkingFormat` | Use `reasoning_effort`, `zai`, `qwen`, or `qwen-chat-template` thinking parameters |
280
307
  | `supportsStrictMode` | Include the `strict` field in tool definitions |
281
- | `openRouterRouting` | OpenRouter routing config passed to OpenRouter for model/provider selection |
308
+ | `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
282
309
  | `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |
283
310
 
284
311
  `qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking`.
@@ -298,8 +325,32 @@ Example:
298
325
  "name": "OpenRouter Claude 3.5 Sonnet",
299
326
  "compat": {
300
327
  "openRouterRouting": {
301
- "order": ["anthropic"],
302
- "fallbacks": ["openai"]
328
+ "allow_fallbacks": true,
329
+ "require_parameters": false,
330
+ "data_collection": "deny",
331
+ "zdr": true,
332
+ "enforce_distillable_text": false,
333
+ "order": ["anthropic", "amazon-bedrock", "google-vertex"],
334
+ "only": ["anthropic", "amazon-bedrock"],
335
+ "ignore": ["gmicloud", "friendli"],
336
+ "quantizations": ["fp16", "bf16"],
337
+ "sort": {
338
+ "by": "price",
339
+ "partition": "model"
340
+ },
341
+ "max_price": {
342
+ "prompt": 10,
343
+ "completion": 20
344
+ },
345
+ "preferred_min_throughput": {
346
+ "p50": 100,
347
+ "p90": 50
348
+ },
349
+ "preferred_max_latency": {
350
+ "p50": 1,
351
+ "p90": 3,
352
+ "p99": 5
353
+ }
303
354
  }
304
355
  }
305
356
  }
package/docs/rpc.md CHANGED
@@ -725,8 +725,9 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
725
725
  | `tool_execution_start` | Tool begins execution |
726
726
  | `tool_execution_update` | Tool execution progress (streaming output) |
727
727
  | `tool_execution_end` | Tool completes |
728
- | `auto_compaction_start` | Auto-compaction begins |
729
- | `auto_compaction_end` | Auto-compaction completes |
728
+ | `queue_update` | Pending steering/follow-up queue changed |
729
+ | `compaction_start` | Compaction begins |
730
+ | `compaction_end` | Compaction completes |
730
731
  | `auto_retry_start` | Auto-retry begins (after transient error) |
731
732
  | `auto_retry_end` | Auto-retry completes (success or final failure) |
732
733
  | `extension_error` | Extension threw an error |
@@ -862,19 +863,32 @@ When complete:
862
863
 
863
864
  Use `toolCallId` to correlate events. The `partialResult` in `tool_execution_update` contains the accumulated output so far (not just the delta), allowing clients to simply replace their display on each update.
864
865
 
865
- ### auto_compaction_start / auto_compaction_end
866
+ ### queue_update
866
867
 
867
- Emitted when automatic compaction runs (when context is nearly full).
868
+ Emitted whenever the pending steering or follow-up queue changes.
868
869
 
869
870
  ```json
870
- {"type": "auto_compaction_start", "reason": "threshold"}
871
+ {
872
+ "type": "queue_update",
873
+ "steering": ["Focus on error handling"],
874
+ "followUp": ["After that, summarize the result"]
875
+ }
876
+ ```
877
+
878
+ ### compaction_start / compaction_end
879
+
880
+ Emitted when compaction runs, whether manual or automatic.
881
+
882
+ ```json
883
+ {"type": "compaction_start", "reason": "threshold"}
871
884
  ```
872
885
 
873
- The `reason` field is `"threshold"` (context getting large) or `"overflow"` (context exceeded limit).
886
+ The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.
874
887
 
875
888
  ```json
876
889
  {
877
- "type": "auto_compaction_end",
890
+ "type": "compaction_end",
891
+ "reason": "threshold",
878
892
  "result": {
879
893
  "summary": "Summary of conversation...",
880
894
  "firstKeptEntryId": "abc123",