@draht/coding-agent 2026.4.5 → 2026.4.25-1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +804 -625
- package/README.md +24 -15
- package/dist/cli/args.d.ts +7 -10
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +44 -46
- 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 +8 -12
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +134 -45
- 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 +31 -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 +22 -21
- 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 +6 -4
- 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 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -5
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +252 -451
- 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/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +1 -0
- package/dist/modes/interactive/components/settings-selector.js.map +1 -1
- package/dist/modes/interactive/components/thinking-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/thinking-selector.js +1 -0
- package/dist/modes/interactive/components/thinking-selector.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 +12 -3
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +237 -125
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/interactive/theme/dark.json +8 -5
- package/dist/modes/interactive/theme/light.json +8 -5
- package/dist/modes/interactive/theme/theme-schema.json +6 -1
- package/dist/modes/interactive/theme/theme.d.ts +2 -2
- package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
- package/dist/modes/interactive/theme/theme.js +13 -1
- 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/orchestrate.md +57 -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/orchestrate.md +57 -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,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
|
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
|
|
package/docs/models.md
CHANGED
|
@@ -90,6 +90,33 @@ Override defaults when you need specific values:
|
|
|
90
90
|
|
|
91
91
|
The file reloads each time you open `/model`. Edit during session; no restart needed.
|
|
92
92
|
|
|
93
|
+
## Google AI Studio Example
|
|
94
|
+
|
|
95
|
+
Use `google-generative-ai` with a `baseUrl` to add models from Google AI Studio, including custom Gemma 4 entries:
|
|
96
|
+
|
|
97
|
+
```json
|
|
98
|
+
{
|
|
99
|
+
"providers": {
|
|
100
|
+
"my-google": {
|
|
101
|
+
"baseUrl": "https://generativelanguage.googleapis.com/v1beta",
|
|
102
|
+
"api": "google-generative-ai",
|
|
103
|
+
"apiKey": "GEMINI_API_KEY",
|
|
104
|
+
"models": [
|
|
105
|
+
{
|
|
106
|
+
"id": "gemma-4-31b-it",
|
|
107
|
+
"name": "Gemma 4 31B",
|
|
108
|
+
"input": ["text", "image"],
|
|
109
|
+
"contextWindow": 262144,
|
|
110
|
+
"reasoning": true
|
|
111
|
+
}
|
|
112
|
+
]
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The `baseUrl` is required when adding custom models to the `google-generative-ai` API type.
|
|
119
|
+
|
|
93
120
|
## Supported APIs
|
|
94
121
|
|
|
95
122
|
| API | Description |
|
|
@@ -131,7 +158,7 @@ The `apiKey` and `headers` fields support three formats:
|
|
|
131
158
|
"apiKey": "sk-..."
|
|
132
159
|
```
|
|
133
160
|
|
|
134
|
-
For `models.json`, shell commands are resolved at request time.
|
|
161
|
+
For `models.json`, shell commands are resolved at request time. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
|
|
135
162
|
|
|
136
163
|
If your command is slow, expensive, rate-limited, or should keep using a previous value on transient failures, wrap it in your own script or command that implements the caching or TTL behavior you want.
|
|
137
164
|
|
|
@@ -278,7 +305,7 @@ For providers with partial OpenAI compatibility, use the `compat` field.
|
|
|
278
305
|
| `requiresThinkingAsText` | Convert thinking blocks to plain text |
|
|
279
306
|
| `thinkingFormat` | Use `reasoning_effort`, `zai`, `qwen`, or `qwen-chat-template` thinking parameters |
|
|
280
307
|
| `supportsStrictMode` | Include the `strict` field in tool definitions |
|
|
281
|
-
| `openRouterRouting` | OpenRouter routing
|
|
308
|
+
| `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
|
|
282
309
|
| `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |
|
|
283
310
|
|
|
284
311
|
`qwen` uses top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that require `chat_template_kwargs.enable_thinking`.
|
|
@@ -298,8 +325,32 @@ Example:
|
|
|
298
325
|
"name": "OpenRouter Claude 3.5 Sonnet",
|
|
299
326
|
"compat": {
|
|
300
327
|
"openRouterRouting": {
|
|
301
|
-
"
|
|
302
|
-
"
|
|
328
|
+
"allow_fallbacks": true,
|
|
329
|
+
"require_parameters": false,
|
|
330
|
+
"data_collection": "deny",
|
|
331
|
+
"zdr": true,
|
|
332
|
+
"enforce_distillable_text": false,
|
|
333
|
+
"order": ["anthropic", "amazon-bedrock", "google-vertex"],
|
|
334
|
+
"only": ["anthropic", "amazon-bedrock"],
|
|
335
|
+
"ignore": ["gmicloud", "friendli"],
|
|
336
|
+
"quantizations": ["fp16", "bf16"],
|
|
337
|
+
"sort": {
|
|
338
|
+
"by": "price",
|
|
339
|
+
"partition": "model"
|
|
340
|
+
},
|
|
341
|
+
"max_price": {
|
|
342
|
+
"prompt": 10,
|
|
343
|
+
"completion": 20
|
|
344
|
+
},
|
|
345
|
+
"preferred_min_throughput": {
|
|
346
|
+
"p50": 100,
|
|
347
|
+
"p90": 50
|
|
348
|
+
},
|
|
349
|
+
"preferred_max_latency": {
|
|
350
|
+
"p50": 1,
|
|
351
|
+
"p90": 3,
|
|
352
|
+
"p99": 5
|
|
353
|
+
}
|
|
303
354
|
}
|
|
304
355
|
}
|
|
305
356
|
}
|
package/docs/rpc.md
CHANGED
|
@@ -725,8 +725,9 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
|
|
|
725
725
|
| `tool_execution_start` | Tool begins execution |
|
|
726
726
|
| `tool_execution_update` | Tool execution progress (streaming output) |
|
|
727
727
|
| `tool_execution_end` | Tool completes |
|
|
728
|
-
| `
|
|
729
|
-
| `
|
|
728
|
+
| `queue_update` | Pending steering/follow-up queue changed |
|
|
729
|
+
| `compaction_start` | Compaction begins |
|
|
730
|
+
| `compaction_end` | Compaction completes |
|
|
730
731
|
| `auto_retry_start` | Auto-retry begins (after transient error) |
|
|
731
732
|
| `auto_retry_end` | Auto-retry completes (success or final failure) |
|
|
732
733
|
| `extension_error` | Extension threw an error |
|
|
@@ -862,19 +863,32 @@ When complete:
|
|
|
862
863
|
|
|
863
864
|
Use `toolCallId` to correlate events. The `partialResult` in `tool_execution_update` contains the accumulated output so far (not just the delta), allowing clients to simply replace their display on each update.
|
|
864
865
|
|
|
865
|
-
###
|
|
866
|
+
### queue_update
|
|
866
867
|
|
|
867
|
-
Emitted
|
|
868
|
+
Emitted whenever the pending steering or follow-up queue changes.
|
|
868
869
|
|
|
869
870
|
```json
|
|
870
|
-
{
|
|
871
|
+
{
|
|
872
|
+
"type": "queue_update",
|
|
873
|
+
"steering": ["Focus on error handling"],
|
|
874
|
+
"followUp": ["After that, summarize the result"]
|
|
875
|
+
}
|
|
876
|
+
```
|
|
877
|
+
|
|
878
|
+
### compaction_start / compaction_end
|
|
879
|
+
|
|
880
|
+
Emitted when compaction runs, whether manual or automatic.
|
|
881
|
+
|
|
882
|
+
```json
|
|
883
|
+
{"type": "compaction_start", "reason": "threshold"}
|
|
871
884
|
```
|
|
872
885
|
|
|
873
|
-
The `reason` field is `"threshold"
|
|
886
|
+
The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.
|
|
874
887
|
|
|
875
888
|
```json
|
|
876
889
|
{
|
|
877
|
-
"type": "
|
|
890
|
+
"type": "compaction_end",
|
|
891
|
+
"reason": "threshold",
|
|
878
892
|
"result": {
|
|
879
893
|
"summary": "Summary of conversation...",
|
|
880
894
|
"firstKeptEntryId": "abc123",
|