@draht/coding-agent 2026.3.25 → 2026.4.23
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/CHANGELOG.md +896 -624
- package/README.md +110 -97
- package/dist/cli/args.d.ts +7 -10
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +42 -44
- package/dist/cli/args.js.map +1 -1
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +1 -0
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts +9 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +18 -0
- package/dist/config.js.map +1 -1
- package/dist/core/agent-session-runtime.d.ts +83 -0
- package/dist/core/agent-session-runtime.d.ts.map +1 -0
- package/dist/core/agent-session-runtime.js +236 -0
- package/dist/core/agent-session-runtime.js.map +1 -0
- package/dist/core/agent-session-services.d.ts +86 -0
- package/dist/core/agent-session-services.d.ts.map +1 -0
- package/dist/core/agent-session-services.js +116 -0
- package/dist/core/agent-session-services.js.map +1 -0
- package/dist/core/agent-session.d.ts +17 -47
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +166 -291
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-storage.d.ts +3 -1
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +5 -2
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/bash-executor.d.ts.map +1 -1
- package/dist/core/bash-executor.js +19 -7
- package/dist/core/bash-executor.js.map +1 -1
- package/dist/core/compaction/branch-summarization.d.ts +2 -0
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +2 -2
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +3 -3
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +27 -26
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/export-html/tool-renderer.d.ts +2 -0
- package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
- package/dist/core/export-html/tool-renderer.js +2 -2
- package/dist/core/export-html/tool-renderer.js.map +1 -1
- package/dist/core/extensions/index.d.ts +2 -2
- package/dist/core/extensions/index.d.ts.map +1 -1
- package/dist/core/extensions/index.js +1 -1
- package/dist/core/extensions/index.js.map +1 -1
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +7 -7
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +1 -0
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +4 -0
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +30 -29
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js +10 -0
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/footer-data-provider.d.ts +5 -1
- package/dist/core/footer-data-provider.d.ts.map +1 -1
- package/dist/core/footer-data-provider.js +70 -8
- package/dist/core/footer-data-provider.js.map +1 -1
- package/dist/core/index.d.ts +3 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +3 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/keybindings.d.ts +14 -1
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +13 -14
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-registry.d.ts +21 -3
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +120 -71
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +4 -4
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/package-manager.d.ts +21 -1
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +108 -43
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/prompt-templates.d.ts.map +1 -1
- package/dist/core/prompt-templates.js +1 -22
- package/dist/core/prompt-templates.js.map +1 -1
- package/dist/core/resolve-config-value.d.ts +6 -0
- package/dist/core/resolve-config-value.d.ts.map +1 -1
- package/dist/core/resolve-config-value.js +37 -5
- package/dist/core/resolve-config-value.js.map +1 -1
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +25 -3
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sdk.d.ts +7 -4
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +18 -24
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-cwd.d.ts +19 -0
- package/dist/core/session-cwd.d.ts.map +1 -0
- package/dist/core/session-cwd.js +38 -0
- package/dist/core/session-cwd.js.map +1 -0
- package/dist/core/session-manager.d.ts +5 -1
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +16 -8
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +3 -1
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +5 -1
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/skills.d.ts +1 -1
- package/dist/core/skills.d.ts.map +1 -1
- package/dist/core/skills.js +3 -3
- package/dist/core/skills.js.map +1 -1
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +6 -6
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/timings.d.ts +1 -0
- package/dist/core/timings.d.ts.map +1 -1
- package/dist/core/timings.js +6 -0
- package/dist/core/timings.js.map +1 -1
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +19 -9
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit-diff.d.ts +23 -1
- package/dist/core/tools/edit-diff.d.ts.map +1 -1
- package/dist/core/tools/edit-diff.js +150 -57
- package/dist/core/tools/edit-diff.js.map +1 -1
- package/dist/core/tools/edit.d.ts +13 -11
- package/dist/core/tools/edit.d.ts.map +1 -1
- package/dist/core/tools/edit.js +55 -77
- package/dist/core/tools/edit.js.map +1 -1
- package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
- package/dist/core/tools/file-mutation-queue.js +4 -4
- package/dist/core/tools/file-mutation-queue.js.map +1 -1
- package/dist/core/tools/index.d.ts +9 -6
- package/dist/core/tools/index.d.ts.map +1 -1
- package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
- package/dist/core/tools/tool-definition-wrapper.js +2 -0
- package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
- package/dist/index.d.ts +4 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -6
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +259 -422
- package/dist/main.js.map +1 -1
- package/dist/migrations.d.ts +3 -3
- package/dist/migrations.d.ts.map +1 -1
- package/dist/migrations.js +25 -5
- package/dist/migrations.js.map +1 -1
- package/dist/modes/interactive/components/assistant-message.d.ts +3 -1
- package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/assistant-message.js +14 -3
- package/dist/modes/interactive/components/assistant-message.js.map +1 -1
- package/dist/modes/interactive/components/earendil-announcement.d.ts +5 -0
- package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -0
- package/dist/modes/interactive/components/earendil-announcement.js +40 -0
- package/dist/modes/interactive/components/earendil-announcement.js.map +1 -0
- package/dist/modes/interactive/components/footer.d.ts +1 -0
- package/dist/modes/interactive/components/footer.d.ts.map +1 -1
- package/dist/modes/interactive/components/footer.js +4 -1
- package/dist/modes/interactive/components/footer.js.map +1 -1
- package/dist/modes/interactive/components/tool-execution.d.ts +0 -1
- package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
- package/dist/modes/interactive/components/tool-execution.js +2 -7
- package/dist/modes/interactive/components/tool-execution.js.map +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts +4 -2
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +48 -15
- package/dist/modes/interactive/components/tree-selector.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +18 -5
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +287 -188
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
- package/dist/modes/interactive/theme/theme.js +15 -11
- package/dist/modes/interactive/theme/theme.js.map +1 -1
- package/dist/modes/print-mode.d.ts +2 -2
- package/dist/modes/print-mode.d.ts.map +1 -1
- package/dist/modes/print-mode.js +89 -72
- package/dist/modes/print-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-client.js +1 -0
- package/dist/modes/rpc/rpc-client.js.map +1 -1
- package/dist/modes/rpc/rpc-mode.d.ts +2 -2
- package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-mode.js +95 -64
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/package-manager-cli.d.ts +4 -0
- package/dist/package-manager-cli.d.ts.map +1 -0
- package/dist/package-manager-cli.js +234 -0
- package/dist/package-manager-cli.js.map +1 -0
- package/dist/prompts/commands/atomic-commit.md +17 -0
- package/dist/prompts/commands/discuss-phase.md +15 -0
- package/dist/prompts/commands/execute-phase.md +14 -0
- package/dist/prompts/commands/fix.md +14 -0
- package/dist/prompts/commands/init-project.md +16 -0
- package/dist/prompts/commands/map-codebase.md +16 -0
- package/dist/prompts/commands/new-project.md +16 -0
- package/dist/prompts/commands/next-milestone.md +16 -0
- package/dist/prompts/commands/pause-work.md +13 -0
- package/dist/prompts/commands/plan-phase.md +15 -0
- package/dist/prompts/commands/progress.md +13 -0
- package/dist/prompts/commands/quick.md +14 -0
- package/dist/prompts/commands/resume-work.md +13 -0
- package/dist/prompts/commands/review.md +15 -0
- package/dist/prompts/commands/verify-work.md +15 -0
- package/dist/utils/paths.d.ts +7 -0
- package/dist/utils/paths.d.ts.map +1 -0
- package/dist/utils/paths.js +19 -0
- package/dist/utils/paths.js.map +1 -0
- package/docs/compaction.md +5 -3
- package/docs/custom-provider.md +1 -1
- package/docs/development.md +5 -3
- package/docs/extensions.md +221 -69
- package/docs/json.md +5 -2
- package/docs/keybindings.md +2 -0
- package/docs/models.md +60 -3
- package/docs/packages.md +3 -3
- package/docs/rpc.md +23 -9
- package/docs/sdk.md +240 -84
- package/docs/session.md +3 -3
- package/docs/settings.md +12 -0
- package/docs/skills.md +3 -2
- package/docs/tree.md +6 -3
- package/examples/README.md +1 -1
- package/examples/extensions/README.md +1 -0
- package/examples/extensions/antigravity-image-gen.ts +1 -1
- package/examples/extensions/custom-compaction.ts +17 -4
- package/examples/extensions/custom-provider-gitlab-duo/index.ts +1 -1
- package/examples/extensions/doom-overlay/doom/build.sh +2 -2
- package/examples/extensions/handoff.ts +5 -2
- package/examples/extensions/hello.ts +18 -17
- package/examples/extensions/hidden-thinking-label.ts +53 -0
- package/examples/extensions/overlay-qa-tests.ts +2 -2
- package/examples/extensions/qna.ts +5 -2
- package/examples/extensions/rpc-demo.ts +3 -9
- package/examples/extensions/sandbox/index.ts +8 -4
- package/examples/extensions/status-line.ts +0 -8
- package/examples/extensions/subagent/index.ts +6 -6
- package/examples/extensions/summarize.ts +15 -4
- package/examples/extensions/todo.ts +0 -2
- package/examples/extensions/tools.ts +0 -5
- package/examples/extensions/trigger-compact.ts +11 -1
- package/examples/extensions/widget-placement.ts +4 -12
- package/examples/sdk/02-custom-model.ts +1 -1
- package/examples/sdk/09-api-keys-and-oauth.ts +3 -3
- package/examples/sdk/12-full-control.ts +1 -1
- package/examples/sdk/13-session-runtime.ts +67 -0
- package/examples/sdk/README.md +8 -5
- package/package.json +7 -8
- package/prompts/commands/atomic-commit.md +17 -0
- package/prompts/commands/discuss-phase.md +15 -0
- package/prompts/commands/execute-phase.md +14 -0
- package/prompts/commands/fix.md +14 -0
- package/prompts/commands/init-project.md +16 -0
- package/prompts/commands/map-codebase.md +16 -0
- package/prompts/commands/new-project.md +16 -0
- package/prompts/commands/next-milestone.md +16 -0
- package/prompts/commands/pause-work.md +13 -0
- package/prompts/commands/plan-phase.md +15 -0
- package/prompts/commands/progress.md +13 -0
- package/prompts/commands/quick.md +14 -0
- package/prompts/commands/resume-work.md +13 -0
- package/prompts/commands/review.md +15 -0
- package/prompts/commands/verify-work.md +15 -0
package/docs/compaction.md
CHANGED
|
@@ -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** ([
|
|
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
|
|
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.
|
package/docs/custom-provider.md
CHANGED
|
@@ -174,7 +174,7 @@ models: [{
|
|
|
174
174
|
compat: {
|
|
175
175
|
supportsDeveloperRole: false, // use "system" instead of "developer"
|
|
176
176
|
supportsReasoningEffort: true,
|
|
177
|
-
reasoningEffortMap: { // map
|
|
177
|
+
reasoningEffortMap: { // map draht-ai levels to provider values
|
|
178
178
|
minimal: "default",
|
|
179
179
|
low: "default",
|
|
180
180
|
medium: "default",
|
package/docs/development.md
CHANGED
|
@@ -6,7 +6,7 @@ See [AGENTS.md](../../../AGENTS.md) for additional guidelines.
|
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
git clone https://github.com/draht-dev/draht
|
|
9
|
-
cd
|
|
9
|
+
cd draht-mono
|
|
10
10
|
npm install
|
|
11
11
|
npm run build
|
|
12
12
|
```
|
|
@@ -14,9 +14,11 @@ npm run build
|
|
|
14
14
|
Run from source:
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
|
-
|
|
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`:
|
|
@@ -24,7 +26,7 @@ Configure via `package.json`:
|
|
|
24
26
|
```json
|
|
25
27
|
{
|
|
26
28
|
"piConfig": {
|
|
27
|
-
"name": "
|
|
29
|
+
"name": "draht",
|
|
28
30
|
"configDir": ".pi"
|
|
29
31
|
}
|
|
30
32
|
}
|
package/docs/extensions.md
CHANGED
|
@@ -37,6 +37,7 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
|
|
|
37
37
|
- [Extension Styles](#extension-styles)
|
|
38
38
|
- [Events](#events)
|
|
39
39
|
- [Lifecycle Overview](#lifecycle-overview)
|
|
40
|
+
- [Resource Events](#resource-events)
|
|
40
41
|
- [Session Events](#session-events)
|
|
41
42
|
- [Agent Events](#agent-events)
|
|
42
43
|
- [Tool Events](#tool-events)
|
|
@@ -212,7 +213,7 @@ Extensions are loaded via [jiti](https://github.com/unjs/jiti), so TypeScript wo
|
|
|
212
213
|
"zod": "^3.0.0",
|
|
213
214
|
"chalk": "^5.0.0"
|
|
214
215
|
},
|
|
215
|
-
"
|
|
216
|
+
"draht": {
|
|
216
217
|
"extensions": ["./src/index.ts"]
|
|
217
218
|
}
|
|
218
219
|
}
|
|
@@ -225,10 +226,10 @@ Run `npm install` in the extension directory, then imports from `node_modules/`
|
|
|
225
226
|
### Lifecycle Overview
|
|
226
227
|
|
|
227
228
|
```
|
|
228
|
-
pi starts
|
|
229
|
+
pi starts
|
|
229
230
|
│
|
|
230
|
-
├─►
|
|
231
|
-
└─►
|
|
231
|
+
├─► session_start { reason: "startup" }
|
|
232
|
+
└─► resources_discover { reason: "startup" }
|
|
232
233
|
│
|
|
233
234
|
▼
|
|
234
235
|
user sends prompt ─────────────────────────────────────────┐
|
|
@@ -261,11 +262,15 @@ user sends another prompt ◄─────────────────
|
|
|
261
262
|
|
|
262
263
|
/new (new session) or /resume (switch session)
|
|
263
264
|
├─► session_before_switch (can cancel)
|
|
264
|
-
|
|
265
|
+
├─► session_shutdown
|
|
266
|
+
├─► session_start { reason: "new" | "resume", previousSessionFile? }
|
|
267
|
+
└─► resources_discover { reason: "startup" }
|
|
265
268
|
|
|
266
269
|
/fork
|
|
267
270
|
├─► session_before_fork (can cancel)
|
|
268
|
-
|
|
271
|
+
├─► session_shutdown
|
|
272
|
+
├─► session_start { reason: "fork", previousSessionFile }
|
|
273
|
+
└─► resources_discover { reason: "startup" }
|
|
269
274
|
|
|
270
275
|
/compact or auto-compaction
|
|
271
276
|
├─► session_before_compact (can cancel or customize)
|
|
@@ -282,43 +287,44 @@ exit (Ctrl+C, Ctrl+D)
|
|
|
282
287
|
└─► session_shutdown
|
|
283
288
|
```
|
|
284
289
|
|
|
285
|
-
###
|
|
286
|
-
|
|
287
|
-
See [session.md](session.md) for session storage internals and the SessionManager API.
|
|
290
|
+
### Resource Events
|
|
288
291
|
|
|
289
|
-
####
|
|
292
|
+
#### resources_discover
|
|
290
293
|
|
|
291
|
-
Fired
|
|
292
|
-
|
|
293
|
-
This event is:
|
|
294
|
-
- CLI-only. It is not emitted in SDK mode.
|
|
295
|
-
- Startup-only. It is not emitted for later interactive `/new` or `/resume` actions.
|
|
296
|
-
- Bypassed when `--session-dir` is provided.
|
|
297
|
-
- Special-cased to receive no `ctx` argument.
|
|
298
|
-
|
|
299
|
-
If multiple extensions return `sessionDir`, the last one wins.
|
|
294
|
+
Fired after `session_start` so extensions can contribute additional skill, prompt, and theme paths.
|
|
295
|
+
The startup path uses `reason: "startup"`. Reload uses `reason: "reload"`.
|
|
300
296
|
|
|
301
297
|
```typescript
|
|
302
|
-
pi.on("
|
|
298
|
+
pi.on("resources_discover", async (event, _ctx) => {
|
|
299
|
+
// event.cwd - current working directory
|
|
300
|
+
// event.reason - "startup" | "reload"
|
|
303
301
|
return {
|
|
304
|
-
|
|
302
|
+
skillPaths: ["/path/to/skills"],
|
|
303
|
+
promptPaths: ["/path/to/prompts"],
|
|
304
|
+
themePaths: ["/path/to/themes"],
|
|
305
305
|
};
|
|
306
306
|
});
|
|
307
307
|
```
|
|
308
308
|
|
|
309
|
+
### Session Events
|
|
310
|
+
|
|
311
|
+
See [session.md](session.md) for session storage internals and the SessionManager API.
|
|
312
|
+
|
|
309
313
|
#### session_start
|
|
310
314
|
|
|
311
|
-
Fired
|
|
315
|
+
Fired when a session is started, loaded, or reloaded.
|
|
312
316
|
|
|
313
317
|
```typescript
|
|
314
|
-
pi.on("session_start", async (
|
|
318
|
+
pi.on("session_start", async (event, ctx) => {
|
|
319
|
+
// event.reason - "startup" | "reload" | "new" | "resume" | "fork"
|
|
320
|
+
// event.previousSessionFile - present for "new", "resume", and "fork"
|
|
315
321
|
ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionFile() ?? "ephemeral"}`, "info");
|
|
316
322
|
});
|
|
317
323
|
```
|
|
318
324
|
|
|
319
|
-
#### session_before_switch
|
|
325
|
+
#### session_before_switch
|
|
320
326
|
|
|
321
|
-
Fired
|
|
327
|
+
Fired before starting a new session (`/new`) or switching sessions (`/resume`).
|
|
322
328
|
|
|
323
329
|
```typescript
|
|
324
330
|
pi.on("session_before_switch", async (event, ctx) => {
|
|
@@ -330,14 +336,12 @@ pi.on("session_before_switch", async (event, ctx) => {
|
|
|
330
336
|
if (!ok) return { cancel: true };
|
|
331
337
|
}
|
|
332
338
|
});
|
|
333
|
-
|
|
334
|
-
pi.on("session_switch", async (event, ctx) => {
|
|
335
|
-
// event.reason - "new" or "resume"
|
|
336
|
-
// event.previousSessionFile - session we came from
|
|
337
|
-
});
|
|
338
339
|
```
|
|
339
340
|
|
|
340
|
-
|
|
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`.
|
|
342
|
+
Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
|
|
343
|
+
|
|
344
|
+
#### session_before_fork
|
|
341
345
|
|
|
342
346
|
Fired when forking via `/fork`.
|
|
343
347
|
|
|
@@ -348,12 +352,11 @@ pi.on("session_before_fork", async (event, ctx) => {
|
|
|
348
352
|
// OR
|
|
349
353
|
return { skipConversationRestore: true }; // Fork but don't rewind messages
|
|
350
354
|
});
|
|
351
|
-
|
|
352
|
-
pi.on("session_fork", async (event, ctx) => {
|
|
353
|
-
// event.previousSessionFile - previous session file
|
|
354
|
-
});
|
|
355
355
|
```
|
|
356
356
|
|
|
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`.
|
|
358
|
+
Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
|
|
359
|
+
|
|
357
360
|
#### session_before_compact / session_compact
|
|
358
361
|
|
|
359
362
|
Fired on compaction. See [compaction.md](compaction.md) for details.
|
|
@@ -564,17 +567,27 @@ Before `tool_call` runs, pi waits for previously emitted Agent events to finish
|
|
|
564
567
|
|
|
565
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`.
|
|
566
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
|
+
|
|
567
578
|
```typescript
|
|
568
579
|
import { isToolCallEventType } from "@draht/coding-agent";
|
|
569
580
|
|
|
570
581
|
pi.on("tool_call", async (event, ctx) => {
|
|
571
582
|
// event.toolName - "bash", "read", "write", "edit", etc.
|
|
572
583
|
// event.toolCallId
|
|
573
|
-
// event.input - tool parameters
|
|
584
|
+
// event.input - tool parameters (mutable)
|
|
574
585
|
|
|
575
586
|
// Built-in tools: no type params needed
|
|
576
587
|
if (isToolCallEventType("bash", event)) {
|
|
577
588
|
// event.input is { command: string; timeout?: number }
|
|
589
|
+
event.input.command = `source ~/.profile\n${event.input.command}`;
|
|
590
|
+
|
|
578
591
|
if (event.input.command.includes("rm -rf")) {
|
|
579
592
|
return { block: true, reason: "Dangerous command" };
|
|
580
593
|
}
|
|
@@ -618,6 +631,8 @@ Fired after tool execution finishes and before `tool_execution_end` plus the fin
|
|
|
618
631
|
- Each handler sees the latest result after previous handler changes
|
|
619
632
|
- Handlers can return partial patches (`content`, `details`, or `isError`); omitted fields keep their current values
|
|
620
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
|
+
|
|
621
636
|
```typescript
|
|
622
637
|
import { isBashToolResult } from "@draht/coding-agent";
|
|
623
638
|
|
|
@@ -629,6 +644,12 @@ pi.on("tool_result", async (event, ctx) => {
|
|
|
629
644
|
// event.details is typed as BashToolDetails
|
|
630
645
|
}
|
|
631
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
|
+
|
|
632
653
|
// Modify result:
|
|
633
654
|
return { content: [...], details: {...}, isError: false };
|
|
634
655
|
});
|
|
@@ -641,7 +662,7 @@ pi.on("tool_result", async (event, ctx) => {
|
|
|
641
662
|
Fired when user executes `!` or `!!` commands. **Can intercept.**
|
|
642
663
|
|
|
643
664
|
```typescript
|
|
644
|
-
import { createLocalBashOperations } from "@
|
|
665
|
+
import { createLocalBashOperations } from "@draht/coding-agent";
|
|
645
666
|
|
|
646
667
|
pi.on("user_bash", (event, ctx) => {
|
|
647
668
|
// event.command - the bash command
|
|
@@ -716,9 +737,7 @@ Transforms chain across handlers. See [input-transform.ts](../examples/extension
|
|
|
716
737
|
|
|
717
738
|
## ExtensionContext
|
|
718
739
|
|
|
719
|
-
All handlers
|
|
720
|
-
|
|
721
|
-
`session_directory` is a CLI startup hook and receives only the event.
|
|
740
|
+
All handlers receive `ctx: ExtensionContext`.
|
|
722
741
|
|
|
723
742
|
### ctx.ui
|
|
724
743
|
|
|
@@ -748,6 +767,31 @@ ctx.sessionManager.getLeafId() // Current leaf entry ID
|
|
|
748
767
|
|
|
749
768
|
Access to models and API keys.
|
|
750
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
|
+
|
|
751
795
|
### ctx.isIdle() / ctx.abort() / ctx.hasPendingMessages()
|
|
752
796
|
|
|
753
797
|
Control flow helpers.
|
|
@@ -876,6 +920,38 @@ Options:
|
|
|
876
920
|
- `replaceInstructions`: If true, `customInstructions` replaces the default prompt instead of being appended
|
|
877
921
|
- `label`: Label to attach to the branch summary entry (or target entry if not summarizing)
|
|
878
922
|
|
|
923
|
+
### ctx.switchSession(sessionPath)
|
|
924
|
+
|
|
925
|
+
Switch to a different session file:
|
|
926
|
+
|
|
927
|
+
```typescript
|
|
928
|
+
const result = await ctx.switchSession("/path/to/session.jsonl");
|
|
929
|
+
if (result.cancelled) {
|
|
930
|
+
// An extension cancelled the switch via session_before_switch
|
|
931
|
+
}
|
|
932
|
+
```
|
|
933
|
+
|
|
934
|
+
To discover available sessions, use the static `SessionManager.list()` or `SessionManager.listAll()` methods:
|
|
935
|
+
|
|
936
|
+
```typescript
|
|
937
|
+
import { SessionManager } from "@draht/coding-agent";
|
|
938
|
+
|
|
939
|
+
pi.registerCommand("switch", {
|
|
940
|
+
description: "Switch to another session",
|
|
941
|
+
handler: async (args, ctx) => {
|
|
942
|
+
const sessions = await SessionManager.list(ctx.cwd);
|
|
943
|
+
if (sessions.length === 0) return;
|
|
944
|
+
const choice = await ctx.ui.select(
|
|
945
|
+
"Pick session:",
|
|
946
|
+
sessions.map(s => s.file),
|
|
947
|
+
);
|
|
948
|
+
if (choice) {
|
|
949
|
+
await ctx.switchSession(choice);
|
|
950
|
+
}
|
|
951
|
+
},
|
|
952
|
+
});
|
|
953
|
+
```
|
|
954
|
+
|
|
879
955
|
### ctx.reload()
|
|
880
956
|
|
|
881
957
|
Run the same reload flow as `/reload`.
|
|
@@ -892,7 +968,7 @@ pi.registerCommand("reload-runtime", {
|
|
|
892
968
|
|
|
893
969
|
Important behavior:
|
|
894
970
|
- `await ctx.reload()` emits `session_shutdown` for the current extension runtime
|
|
895
|
-
- It then reloads resources and emits `session_start`
|
|
971
|
+
- It then reloads resources and emits `session_start` with `reason: "reload"` and `resources_discover` with reason `"reload"`
|
|
896
972
|
- The currently running command handler still continues in the old call frame
|
|
897
973
|
- Code after `await ctx.reload()` still runs from the pre-reload version
|
|
898
974
|
- Code after `await ctx.reload()` must not assume old in-memory extension state is still valid
|
|
@@ -964,6 +1040,12 @@ pi.registerTool({
|
|
|
964
1040
|
action: StringEnum(["list", "add"] as const),
|
|
965
1041
|
text: Type.Optional(Type.String()),
|
|
966
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
|
+
},
|
|
967
1049
|
|
|
968
1050
|
async execute(toolCallId, params, signal, onUpdate, ctx) {
|
|
969
1051
|
// Stream progress
|
|
@@ -976,8 +1058,8 @@ pi.registerTool({
|
|
|
976
1058
|
},
|
|
977
1059
|
|
|
978
1060
|
// Optional: Custom rendering
|
|
979
|
-
renderCall(args, theme) { ... },
|
|
980
|
-
renderResult(result, options, theme) { ... },
|
|
1061
|
+
renderCall(args, theme, context) { ... },
|
|
1062
|
+
renderResult(result, options, theme, context) { ... },
|
|
981
1063
|
});
|
|
982
1064
|
```
|
|
983
1065
|
|
|
@@ -1388,7 +1470,7 @@ Pass the real target file path to `withFileMutationQueue()`, not the raw user ar
|
|
|
1388
1470
|
Queue the entire mutation window on that target path. That includes read-modify-write logic, not just the final write.
|
|
1389
1471
|
|
|
1390
1472
|
```typescript
|
|
1391
|
-
import { withFileMutationQueue } from "@
|
|
1473
|
+
import { withFileMutationQueue } from "@draht/coding-agent";
|
|
1392
1474
|
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
1393
1475
|
import { dirname, resolve } from "node:path";
|
|
1394
1476
|
|
|
@@ -1428,6 +1510,14 @@ pi.registerTool({
|
|
|
1428
1510
|
action: StringEnum(["list", "add"] as const), // Use StringEnum for Google compatibility
|
|
1429
1511
|
text: Type.Optional(Type.String()),
|
|
1430
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
|
+
},
|
|
1431
1521
|
|
|
1432
1522
|
async execute(toolCallId, params, signal, onUpdate, ctx) {
|
|
1433
1523
|
// Check for cancellation
|
|
@@ -1452,8 +1542,8 @@ pi.registerTool({
|
|
|
1452
1542
|
},
|
|
1453
1543
|
|
|
1454
1544
|
// Optional: Custom rendering
|
|
1455
|
-
renderCall(args, theme) { ... },
|
|
1456
|
-
renderResult(result, options, theme) { ... },
|
|
1545
|
+
renderCall(args, theme, context) { ... },
|
|
1546
|
+
renderResult(result, options, theme, context) { ... },
|
|
1457
1547
|
});
|
|
1458
1548
|
```
|
|
1459
1549
|
|
|
@@ -1471,6 +1561,53 @@ async execute(toolCallId, params) {
|
|
|
1471
1561
|
|
|
1472
1562
|
**Important:** Use `StringEnum` from `@draht/ai` for string enums. `Type.Union`/`Type.Literal` doesn't work with Google's API.
|
|
1473
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
|
+
|
|
1474
1611
|
### Overriding Built-in Tools
|
|
1475
1612
|
|
|
1476
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.
|
|
@@ -1488,7 +1625,9 @@ pi --no-tools -e ./my-extension.ts
|
|
|
1488
1625
|
|
|
1489
1626
|
See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.ts) for a complete example that overrides `read` with logging and access control.
|
|
1490
1627
|
|
|
1491
|
-
**Rendering:** If your override
|
|
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.
|
|
1492
1631
|
|
|
1493
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.
|
|
1494
1633
|
|
|
@@ -1622,44 +1761,52 @@ export default function (pi: ExtensionAPI) {
|
|
|
1622
1761
|
|
|
1623
1762
|
### Custom Rendering
|
|
1624
1763
|
|
|
1625
|
-
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
|
|
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.
|
|
1767
|
+
|
|
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`
|
|
1626
1774
|
|
|
1627
|
-
|
|
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.
|
|
1628
1776
|
|
|
1629
1777
|
#### renderCall
|
|
1630
1778
|
|
|
1631
|
-
Renders the tool call
|
|
1779
|
+
Renders the tool call or header:
|
|
1632
1780
|
|
|
1633
1781
|
```typescript
|
|
1634
1782
|
import { Text } from "@draht/tui";
|
|
1635
1783
|
|
|
1636
|
-
renderCall(args, theme) {
|
|
1637
|
-
|
|
1638
|
-
|
|
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);
|
|
1639
1788
|
if (args.text) {
|
|
1640
|
-
|
|
1789
|
+
content += " " + theme.fg("dim", `"${args.text}"`);
|
|
1641
1790
|
}
|
|
1642
|
-
|
|
1791
|
+
text.setText(content);
|
|
1792
|
+
return text;
|
|
1643
1793
|
}
|
|
1644
1794
|
```
|
|
1645
1795
|
|
|
1646
1796
|
#### renderResult
|
|
1647
1797
|
|
|
1648
|
-
Renders the tool result:
|
|
1798
|
+
Renders the tool result or output:
|
|
1649
1799
|
|
|
1650
1800
|
```typescript
|
|
1651
|
-
renderResult(result, { expanded, isPartial }, theme) {
|
|
1652
|
-
// Handle streaming
|
|
1801
|
+
renderResult(result, { expanded, isPartial }, theme, context) {
|
|
1653
1802
|
if (isPartial) {
|
|
1654
1803
|
return new Text(theme.fg("warning", "Processing..."), 0, 0);
|
|
1655
1804
|
}
|
|
1656
1805
|
|
|
1657
|
-
// Handle errors
|
|
1658
1806
|
if (result.details?.error) {
|
|
1659
1807
|
return new Text(theme.fg("error", `Error: ${result.details.error}`), 0, 0);
|
|
1660
1808
|
}
|
|
1661
1809
|
|
|
1662
|
-
// Normal result - support expanded view (Ctrl+O)
|
|
1663
1810
|
let text = theme.fg("success", "✓ Done");
|
|
1664
1811
|
if (expanded && result.details?.items) {
|
|
1665
1812
|
for (const item of result.details.items) {
|
|
@@ -1670,6 +1817,8 @@ renderResult(result, { expanded, isPartial }, theme) {
|
|
|
1670
1817
|
}
|
|
1671
1818
|
```
|
|
1672
1819
|
|
|
1820
|
+
If a slot intentionally has no visible content, return an empty `Component` such as an empty `Container`.
|
|
1821
|
+
|
|
1673
1822
|
#### Keybinding Hints
|
|
1674
1823
|
|
|
1675
1824
|
Use `keyHint()` to display keybinding hints that respect the active keybinding configuration:
|
|
@@ -1677,7 +1826,7 @@ Use `keyHint()` to display keybinding hints that respect the active keybinding c
|
|
|
1677
1826
|
```typescript
|
|
1678
1827
|
import { keyHint } from "@draht/coding-agent";
|
|
1679
1828
|
|
|
1680
|
-
renderResult(result, { expanded }, theme) {
|
|
1829
|
+
renderResult(result, { expanded }, theme, context) {
|
|
1681
1830
|
let text = theme.fg("success", "✓ Done");
|
|
1682
1831
|
if (!expanded) {
|
|
1683
1832
|
text += ` (${keyHint("app.tools.expand", "to expand")})`;
|
|
@@ -1701,16 +1850,19 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
|
|
|
1701
1850
|
|
|
1702
1851
|
#### Best Practices
|
|
1703
1852
|
|
|
1704
|
-
- Use `Text` with padding `(0, 0)
|
|
1705
|
-
- Use `\n` for multi-line content
|
|
1706
|
-
- Handle `isPartial` for streaming progress
|
|
1707
|
-
- Support `expanded` for detail on demand
|
|
1708
|
-
- 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.
|
|
1709
1861
|
|
|
1710
1862
|
#### Fallback
|
|
1711
1863
|
|
|
1712
|
-
If
|
|
1713
|
-
- `renderCall`: Shows tool name
|
|
1864
|
+
If a slot renderer is not defined or throws:
|
|
1865
|
+
- `renderCall`: Shows the tool name
|
|
1714
1866
|
- `renderResult`: Shows raw text from `content`
|
|
1715
1867
|
|
|
1716
1868
|
## Custom UI
|
|
@@ -2067,7 +2219,7 @@ All examples in [examples/extensions/](../examples/extensions/).
|
|
|
2067
2219
|
| **Compaction & Sessions** |||
|
|
2068
2220
|
| `custom-compaction.ts` | Custom compaction summary | `on("session_before_compact")` |
|
|
2069
2221
|
| `trigger-compact.ts` | Trigger compaction manually | `compact()` |
|
|
2070
|
-
| `git-checkpoint.ts` | Git stash on turns | `on("
|
|
2222
|
+
| `git-checkpoint.ts` | Git stash on turns | `on("turn_start")`, `on("session_before_fork")`, `exec` |
|
|
2071
2223
|
| `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |
|
|
2072
2224
|
| **UI Components** |||
|
|
2073
2225
|
| `status-line.ts` | Footer status indicator | `setStatus`, session events |
|
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: "
|
|
17
|
-
| { type: "
|
|
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
|
package/docs/keybindings.md
CHANGED
|
@@ -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
|
|