@draht/coding-agent 2026.4.5 → 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 +790 -625
- package/README.md +105 -96
- 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 +53 -106
- package/dist/core/agent-session-runtime.d.ts.map +1 -1
- package/dist/core/agent-session-runtime.js +116 -147
- package/dist/core/agent-session-runtime.js.map +1 -1
- 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 +4 -12
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +122 -43
- package/dist/core/agent-session.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/compaction.d.ts +1 -1
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +18 -17
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/extensions/index.d.ts +1 -1
- package/dist/core/extensions/index.d.ts.map +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 +15 -14
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/index.d.ts +2 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js +2 -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.map +1 -1
- package/dist/core/model-registry.js +30 -1
- package/dist/core/model-registry.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/resource-loader.d.ts +0 -2
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +26 -8
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sdk.d.ts +2 -2
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +2 -2
- 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 +2 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -5
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +248 -450
- 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/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 +12 -3
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +220 -124
- 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 +9 -0
- package/dist/modes/interactive/theme/theme.js.map +1 -1
- package/dist/modes/print-mode.d.ts +4 -4
- package/dist/modes/print-mode.d.ts.map +1 -1
- package/dist/modes/print-mode.js +6 -2
- 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 +26 -15
- 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 +3 -1
- package/docs/extensions.md +150 -54
- package/docs/json.md +5 -2
- package/docs/keybindings.md +2 -0
- package/docs/models.md +55 -4
- package/docs/rpc.md +21 -7
- package/docs/sdk.md +116 -48
- package/docs/session.md +3 -3
- package/docs/settings.md +12 -0
- package/docs/skills.md +3 -2
- package/docs/tree.md +5 -2
- 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-provider-gitlab-duo/index.ts +1 -1
- package/examples/extensions/doom-overlay/doom/build.sh +2 -2
- package/examples/extensions/hidden-thinking-label.ts +53 -0
- package/examples/extensions/overlay-qa-tests.ts +2 -2
- package/examples/extensions/sandbox/index.ts +8 -4
- package/examples/extensions/subagent/index.ts +5 -5
- package/examples/extensions/trigger-compact.ts +11 -1
- package/examples/sdk/13-session-runtime.ts +30 -12
- package/examples/sdk/README.md +4 -2
- 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
|
@@ -13,6 +13,22 @@ Initialize a new project: questioning → research → requirements → roadmap.
|
|
|
13
13
|
|
|
14
14
|
Description: $ARGUMENTS
|
|
15
15
|
|
|
16
|
+
## Atomic Reasoning
|
|
17
|
+
|
|
18
|
+
Before questioning, decompose project vision into atomic reasoning units:
|
|
19
|
+
|
|
20
|
+
**For each aspect of the new project:**
|
|
21
|
+
1. **State the logical component** — What problem does this solve? Who are the users? What is core vs peripheral?
|
|
22
|
+
2. **Validate independence** — What bounded contexts will exist? What domain concepts are central? Can features be built independently?
|
|
23
|
+
3. **Verify correctness** — What defines MVP success? What constraints exist (time, tech, team)? What is explicitly out of scope?
|
|
24
|
+
|
|
25
|
+
**Synthesize project strategy:**
|
|
26
|
+
- Define bounded contexts and ubiquitous language upfront
|
|
27
|
+
- Establish test strategy before writing code
|
|
28
|
+
- Create requirements mapped to domain contexts
|
|
29
|
+
- Build roadmap with testable phase goals
|
|
30
|
+
- Ensure each phase delivers verifiable user value
|
|
31
|
+
|
|
16
32
|
## Steps
|
|
17
33
|
1. Run `draht-tools init` to check preconditions
|
|
18
34
|
2. If existing code detected, run `draht-tools map-codebase` first
|
|
@@ -11,6 +11,22 @@ Plan the next milestone after ALL phases in the current one are complete.
|
|
|
11
11
|
/next-milestone
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
+
## Atomic Reasoning
|
|
15
|
+
|
|
16
|
+
Before planning the next milestone, decompose progress into atomic reasoning units:
|
|
17
|
+
|
|
18
|
+
**For each completed phase:**
|
|
19
|
+
1. **State the logical component** — What was built? What user value was delivered? What requirements were satisfied?
|
|
20
|
+
2. **Validate independence** — What worked well? What had issues? What assumptions proved wrong?
|
|
21
|
+
3. **Verify correctness** — What tests passed? What domain model evolved? What new knowledge emerged?
|
|
22
|
+
|
|
23
|
+
**Synthesize next milestone:**
|
|
24
|
+
- Assess which v1 requirements remain vs are complete
|
|
25
|
+
- Identify requirements that should be promoted or descoped based on learning
|
|
26
|
+
- Define 3-5 new phases with clear, testable goals
|
|
27
|
+
- Order phases by dependency and risk
|
|
28
|
+
- Map each phase to specific requirements and domain contexts
|
|
29
|
+
|
|
14
30
|
## Prerequisites
|
|
15
31
|
- `.planning/ROADMAP.md` must exist
|
|
16
32
|
- ALL phases in the current milestone must be complete (verified via /verify-work)
|
|
@@ -11,6 +11,19 @@ Create a handoff document for session continuity.
|
|
|
11
11
|
/pause-work
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
+
## Atomic Reasoning
|
|
15
|
+
|
|
16
|
+
Before pausing, decompose session state into atomic reasoning units:
|
|
17
|
+
|
|
18
|
+
1. **State the logical component** — What was accomplished this session? What is in-progress? What is the current phase/task?
|
|
19
|
+
2. **Validate independence** — Are there uncommitted changes? Are there blockers? What decisions were made?
|
|
20
|
+
3. **Verify correctness** — Is the current state stable? Can work resume cleanly? What context needs to be captured?
|
|
21
|
+
|
|
22
|
+
**Synthesize handoff document:**
|
|
23
|
+
- Capture current phase and status
|
|
24
|
+
- Document decisions and blockers
|
|
25
|
+
- Note next steps for resumption
|
|
26
|
+
|
|
14
27
|
## Steps
|
|
15
28
|
1. Run `draht-tools pause` — creates CONTINUE-HERE.md
|
|
16
29
|
2. Commit: `draht-tools commit-docs "pause work"`
|
|
@@ -13,6 +13,21 @@ Create atomic execution plans for a roadmap phase, using subagents for parallel
|
|
|
13
13
|
|
|
14
14
|
Phase: $1
|
|
15
15
|
|
|
16
|
+
## Atomic Reasoning
|
|
17
|
+
|
|
18
|
+
Before creating plans, decompose this phase goal into atomic reasoning units:
|
|
19
|
+
|
|
20
|
+
**For each observable truth (user-visible outcome):**
|
|
21
|
+
1. **State the logical component** — What must be true for the user? What can they do/see/verify?
|
|
22
|
+
2. **Validate independence** — Which artifacts (files, endpoints, schemas) prove this truth exists? Can it be built independently?
|
|
23
|
+
3. **Verify correctness** — What test scenarios would prove this observable truth? What are the specific inputs → expected outputs?
|
|
24
|
+
|
|
25
|
+
**Synthesize planning strategy:**
|
|
26
|
+
- Group related observable truths into cohesive plans (2-5 tasks each)
|
|
27
|
+
- Identify which plans can be created in parallel vs sequentially
|
|
28
|
+
- Map each plan to specific bounded contexts and domain concepts
|
|
29
|
+
- Ensure each plan produces testable, verifiable outcomes
|
|
30
|
+
|
|
16
31
|
## Steps
|
|
17
32
|
1. Run `draht-tools load-phase-context $1` to gather all context
|
|
18
33
|
2. Optional: `draht-tools research-phase $1` for domain research
|
|
@@ -11,6 +11,19 @@ Show current project status.
|
|
|
11
11
|
/progress
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
+
## Atomic Reasoning
|
|
15
|
+
|
|
16
|
+
Before checking progress, decompose project state into atomic reasoning units:
|
|
17
|
+
|
|
18
|
+
1. **State the logical component** — What milestone are we in? What phase is active? What work is complete vs in-progress?
|
|
19
|
+
2. **Validate independence** — Are there blockers? Are phases in the correct sequence? Is anything waiting on external input?
|
|
20
|
+
3. **Verify correctness** — Does the reported state match reality? Are all verified phases truly complete? Are there unreported issues?
|
|
21
|
+
|
|
22
|
+
**Synthesize status understanding:**
|
|
23
|
+
- Identify where we are in the roadmap
|
|
24
|
+
- Assess momentum and blockers
|
|
25
|
+
- Determine next action
|
|
26
|
+
|
|
14
27
|
## Steps
|
|
15
28
|
1. Run `draht-tools progress` — outputs formatted status
|
|
16
29
|
2. Display the result as-is
|
|
@@ -13,6 +13,20 @@ Execute a small ad-hoc task with tracking.
|
|
|
13
13
|
|
|
14
14
|
Task: $ARGUMENTS
|
|
15
15
|
|
|
16
|
+
## Atomic Reasoning
|
|
17
|
+
|
|
18
|
+
Before executing, decompose this task into atomic reasoning units:
|
|
19
|
+
|
|
20
|
+
1. **State the logical component** — What is the single, concrete outcome? What files need to change? What behavior needs to work?
|
|
21
|
+
2. **Validate independence** — Can this be done without touching other features? What dependencies exist? What could break?
|
|
22
|
+
3. **Verify correctness** — What test proves this works? What edge cases matter? Is this testable behavior or pure config?
|
|
23
|
+
|
|
24
|
+
**Synthesize execution plan:**
|
|
25
|
+
- Define specific files to modify
|
|
26
|
+
- Write failing test (if testable behavior)
|
|
27
|
+
- Implement minimal solution
|
|
28
|
+
- Verify and document
|
|
29
|
+
|
|
16
30
|
## Steps
|
|
17
31
|
1. Run `draht-tools next-quick-number` to get task number
|
|
18
32
|
2. Analyze the task and write a concrete plan with actual task details (files, actions, verification). Pipe it into `draht-tools create-quick-plan`:
|
|
@@ -11,6 +11,19 @@ Resume from last session state.
|
|
|
11
11
|
/resume-work
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
+
## Atomic Reasoning
|
|
15
|
+
|
|
16
|
+
Before resuming, decompose handoff context into atomic reasoning units:
|
|
17
|
+
|
|
18
|
+
1. **State the logical component** — What phase/task was active? What was the last accomplishment? What decisions were made?
|
|
19
|
+
2. **Validate independence** — Are there blockers? What changed since the pause? Is the codebase in the expected state?
|
|
20
|
+
3. **Verify correctness** — Is the handoff document complete? Does the current state match what was documented? Can work continue safely?
|
|
21
|
+
|
|
22
|
+
**Synthesize resumption plan:**
|
|
23
|
+
- Understand current context
|
|
24
|
+
- Identify next action
|
|
25
|
+
- Confirm no conflicts or state drift
|
|
26
|
+
|
|
14
27
|
## Steps
|
|
15
28
|
1. Run `draht-tools resume` — loads CONTINUE-HERE.md or STATE.md
|
|
16
29
|
2. Display context and ask to continue
|
|
@@ -15,6 +15,21 @@ Scope: $ARGUMENTS
|
|
|
15
15
|
|
|
16
16
|
If no scope given, reviews all recent uncommitted changes.
|
|
17
17
|
|
|
18
|
+
## Atomic Reasoning
|
|
19
|
+
|
|
20
|
+
Before reviewing, decompose code changes into atomic reasoning units:
|
|
21
|
+
|
|
22
|
+
**For each changed file:**
|
|
23
|
+
1. **State the logical component** — What does this change do? What problem does it solve? What behavior does it add/modify?
|
|
24
|
+
2. **Validate independence** — Does this change have side effects? Does it affect other modules? Are there hidden dependencies?
|
|
25
|
+
3. **Verify correctness** — Is this change correct? Type-safe? Secure? Does it follow conventions? What could go wrong?
|
|
26
|
+
|
|
27
|
+
**Synthesize review strategy:**
|
|
28
|
+
- Group changes by concern (correctness, security, style)
|
|
29
|
+
- Prioritize findings (critical, important, minor)
|
|
30
|
+
- Identify patterns across multiple files
|
|
31
|
+
- Check domain language compliance and bounded context boundaries
|
|
32
|
+
|
|
18
33
|
## Steps
|
|
19
34
|
1. Identify the scope:
|
|
20
35
|
- If argument given: use those files/directories/description as scope
|
|
@@ -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"]}
|
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
|
@@ -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`:
|
package/docs/extensions.md
CHANGED
|
@@ -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
|
|
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,
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
1694
|
-
|
|
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
|
-
|
|
1789
|
+
content += " " + theme.fg("dim", `"${args.text}"`);
|
|
1697
1790
|
}
|
|
1698
|
-
|
|
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)
|
|
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
|
|
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
|