@draht/coding-agent 2026.5.12 → 2026.6.11
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 +26 -0
- package/bin/draht-tools.cjs +3756 -1
- package/dist/bun/cli.d.ts.map +1 -1
- package/dist/bun/cli.js +4 -2
- package/dist/bun/cli.js.map +1 -1
- package/dist/bun/restore-sandbox-env.d.ts +13 -0
- package/dist/bun/restore-sandbox-env.d.ts.map +1 -0
- package/dist/bun/restore-sandbox-env.js +32 -0
- package/dist/bun/restore-sandbox-env.js.map +1 -0
- package/dist/cli/args.d.ts +9 -4
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +88 -35
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/config-selector.d.ts +2 -2
- package/dist/cli/config-selector.d.ts.map +1 -1
- package/dist/cli/config-selector.js +1 -1
- package/dist/cli/config-selector.js.map +1 -1
- package/dist/cli/file-processor.d.ts.map +1 -1
- package/dist/cli/file-processor.js +2 -3
- package/dist/cli/file-processor.js.map +1 -1
- package/dist/cli/initial-message.d.ts +1 -1
- package/dist/cli/initial-message.d.ts.map +1 -1
- package/dist/cli/initial-message.js.map +1 -1
- package/dist/cli/list-models.d.ts +1 -1
- package/dist/cli/list-models.d.ts.map +1 -1
- package/dist/cli/list-models.js +7 -1
- package/dist/cli/list-models.js.map +1 -1
- package/dist/cli/project-trust.d.ts +10 -0
- package/dist/cli/project-trust.d.ts.map +1 -0
- package/dist/cli/project-trust.js +48 -0
- package/dist/cli/project-trust.js.map +1 -0
- package/dist/cli/session-picker.d.ts +1 -1
- package/dist/cli/session-picker.d.ts.map +1 -1
- package/dist/cli/session-picker.js.map +1 -1
- package/dist/cli/startup-ui.d.ts +16 -0
- package/dist/cli/startup-ui.d.ts.map +1 -0
- package/dist/cli/startup-ui.js +112 -0
- package/dist/cli/startup-ui.js.map +1 -0
- package/dist/cli.d.ts.map +1 -1
- package/dist/cli.js +7 -4
- package/dist/cli.js.map +1 -1
- package/dist/config.d.ts +23 -13
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +264 -62
- package/dist/config.js.map +1 -1
- package/dist/core/agent-session-runtime.d.ts +45 -9
- package/dist/core/agent-session-runtime.d.ts.map +1 -1
- package/dist/core/agent-session-runtime.js +100 -33
- package/dist/core/agent-session-runtime.js.map +1 -1
- package/dist/core/agent-session-services.d.ts +6 -4
- package/dist/core/agent-session-services.d.ts.map +1 -1
- package/dist/core/agent-session-services.js +7 -4
- package/dist/core/agent-session-services.js.map +1 -1
- package/dist/core/agent-session.d.ts +47 -31
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +470 -443
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-guidance.d.ts +5 -0
- package/dist/core/auth-guidance.d.ts.map +1 -0
- package/dist/core/auth-guidance.js +21 -0
- package/dist/core/auth-guidance.js.map +1 -0
- package/dist/core/auth-storage.d.ts +10 -1
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +27 -6
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/bash-executor.d.ts +1 -15
- package/dist/core/bash-executor.d.ts.map +1 -1
- package/dist/core/bash-executor.js +10 -24
- package/dist/core/bash-executor.js.map +1 -1
- package/dist/core/builtins/subagent.d.ts.map +1 -1
- package/dist/core/builtins/subagent.js +1 -2
- package/dist/core/builtins/subagent.js.map +1 -1
- package/dist/core/compaction/branch-summarization.d.ts +6 -4
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +9 -3
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +5 -5
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +43 -37
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/compaction/index.d.ts +3 -3
- package/dist/core/compaction/index.d.ts.map +1 -1
- package/dist/core/compaction/index.js.map +1 -1
- package/dist/core/compaction/utils.d.ts +1 -1
- package/dist/core/compaction/utils.d.ts.map +1 -1
- package/dist/core/compaction/utils.js +1 -1
- package/dist/core/compaction/utils.js.map +1 -1
- package/dist/core/exec.d.ts.map +1 -1
- package/dist/core/exec.js.map +1 -1
- package/dist/core/experimental.d.ts +2 -0
- package/dist/core/experimental.d.ts.map +1 -0
- package/dist/core/experimental.js +4 -0
- package/dist/core/experimental.js.map +1 -0
- package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
- package/dist/core/export-html/ansi-to-html.js +1 -1
- package/dist/core/export-html/ansi-to-html.js.map +1 -1
- package/dist/core/export-html/index.d.ts +1 -1
- package/dist/core/export-html/index.d.ts.map +1 -1
- package/dist/core/export-html/index.js +13 -11
- package/dist/core/export-html/index.js.map +1 -1
- package/dist/core/export-html/template.css +69 -4
- package/dist/core/export-html/template.js +231 -57
- package/dist/core/export-html/tool-renderer.d.ts +0 -6
- package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
- package/dist/core/export-html/tool-renderer.js +15 -2
- package/dist/core/export-html/tool-renderer.js.map +1 -1
- package/dist/core/extensions/index.d.ts +8 -8
- 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 +3 -3
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +27 -35
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +30 -12
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +215 -32
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +163 -35
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/extensions/wrapper.d.ts.map +1 -1
- package/dist/core/extensions/wrapper.js +2 -2
- package/dist/core/extensions/wrapper.js.map +1 -1
- package/dist/core/footer-data-provider.d.ts +7 -1
- package/dist/core/footer-data-provider.d.ts.map +1 -1
- package/dist/core/footer-data-provider.js +78 -54
- package/dist/core/footer-data-provider.js.map +1 -1
- package/dist/core/http-dispatcher.d.ts +21 -0
- package/dist/core/http-dispatcher.d.ts.map +1 -0
- package/dist/core/http-dispatcher.js +48 -0
- package/dist/core/http-dispatcher.js.map +1 -0
- package/dist/core/index.d.ts +9 -8
- 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 +66 -1
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +56 -1
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-registry.d.ts +22 -4
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +216 -44
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts +2 -1
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +48 -21
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/output-guard.d.ts +1 -0
- package/dist/core/output-guard.d.ts.map +1 -1
- package/dist/core/output-guard.js +52 -22
- package/dist/core/output-guard.js.map +1 -1
- package/dist/core/package-manager.d.ts +17 -2
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +363 -121
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/project-trust.d.ts +15 -0
- package/dist/core/project-trust.d.ts.map +1 -0
- package/dist/core/project-trust.js +58 -0
- package/dist/core/project-trust.js.map +1 -0
- package/dist/core/prompt-templates.d.ts +13 -11
- package/dist/core/prompt-templates.d.ts.map +1 -1
- package/dist/core/prompt-templates.js +67 -76
- package/dist/core/prompt-templates.js.map +1 -1
- package/dist/core/provider-attribution.d.ts +4 -0
- package/dist/core/provider-attribution.d.ts.map +1 -0
- package/dist/core/provider-attribution.js +72 -0
- package/dist/core/provider-attribution.js.map +1 -0
- package/dist/core/provider-display-names.d.ts +2 -0
- package/dist/core/provider-display-names.d.ts.map +1 -0
- package/dist/core/provider-display-names.js +36 -0
- package/dist/core/provider-display-names.js.map +1 -0
- package/dist/core/resolve-config-value.d.ts +9 -1
- package/dist/core/resolve-config-value.d.ts.map +1 -1
- package/dist/core/resolve-config-value.js +134 -11
- package/dist/core/resolve-config-value.js.map +1 -1
- package/dist/core/resource-loader.d.ts +34 -14
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +165 -76
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sdk.d.ts +26 -10
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +45 -16
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-manager.d.ts +11 -12
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +245 -132
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +52 -5
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +202 -38
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/skills.d.ts +10 -10
- package/dist/core/skills.d.ts.map +1 -1
- package/dist/core/skills.js +13 -35
- package/dist/core/skills.js.map +1 -1
- package/dist/core/slash-commands.d.ts +1 -1
- package/dist/core/slash-commands.d.ts.map +1 -1
- package/dist/core/slash-commands.js +7 -4
- package/dist/core/slash-commands.js.map +1 -1
- package/dist/core/source-info.d.ts +1 -1
- package/dist/core/source-info.d.ts.map +1 -1
- package/dist/core/source-info.js.map +1 -1
- package/dist/core/system-prompt.d.ts +4 -4
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +14 -10
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/telemetry.d.ts +3 -0
- package/dist/core/telemetry.d.ts.map +1 -0
- package/dist/core/telemetry.js +9 -0
- package/dist/core/telemetry.js.map +1 -0
- package/dist/core/tools/bash.d.ts +11 -16
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +162 -177
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit-diff.d.ts +3 -1
- package/dist/core/tools/edit-diff.d.ts.map +1 -1
- package/dist/core/tools/edit-diff.js +11 -3
- package/dist/core/tools/edit-diff.js.map +1 -1
- package/dist/core/tools/edit.d.ts +22 -24
- package/dist/core/tools/edit.d.ts.map +1 -1
- package/dist/core/tools/edit.js +199 -111
- 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 +27 -12
- package/dist/core/tools/file-mutation-queue.js.map +1 -1
- package/dist/core/tools/find.d.ts +7 -18
- package/dist/core/tools/find.d.ts.map +1 -1
- package/dist/core/tools/find.js +134 -95
- package/dist/core/tools/find.js.map +1 -1
- package/dist/core/tools/grep.d.ts +11 -30
- package/dist/core/tools/grep.d.ts.map +1 -1
- package/dist/core/tools/grep.js +23 -12
- package/dist/core/tools/grep.js.map +1 -1
- package/dist/core/tools/index.d.ts +26 -101
- package/dist/core/tools/index.d.ts.map +1 -1
- package/dist/core/tools/index.js +78 -52
- package/dist/core/tools/index.js.map +1 -1
- package/dist/core/tools/ls.d.ts +6 -15
- package/dist/core/tools/ls.d.ts.map +1 -1
- package/dist/core/tools/ls.js +12 -17
- package/dist/core/tools/ls.js.map +1 -1
- package/dist/core/tools/output-accumulator.d.ts +52 -0
- package/dist/core/tools/output-accumulator.d.ts.map +1 -0
- package/dist/core/tools/output-accumulator.js +184 -0
- package/dist/core/tools/output-accumulator.js.map +1 -0
- package/dist/core/tools/path-utils.d.ts +2 -0
- package/dist/core/tools/path-utils.d.ts.map +1 -1
- package/dist/core/tools/path-utils.js +40 -22
- package/dist/core/tools/path-utils.js.map +1 -1
- package/dist/core/tools/read.d.ts +7 -18
- package/dist/core/tools/read.d.ts.map +1 -1
- package/dist/core/tools/read.js +100 -36
- package/dist/core/tools/read.js.map +1 -1
- package/dist/core/tools/render-utils.d.ts +5 -2
- package/dist/core/tools/render-utils.d.ts.map +1 -1
- package/dist/core/tools/render-utils.js +18 -2
- package/dist/core/tools/render-utils.js.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/core/tools/truncate.d.ts.map +1 -1
- package/dist/core/tools/truncate.js +12 -2
- package/dist/core/tools/truncate.js.map +1 -1
- package/dist/core/tools/write.d.ts +5 -14
- package/dist/core/tools/write.d.ts.map +1 -1
- package/dist/core/tools/write.js +27 -46
- package/dist/core/tools/write.js.map +1 -1
- package/dist/core/trust-manager.d.ts +31 -0
- package/dist/core/trust-manager.d.ts.map +1 -0
- package/dist/core/trust-manager.js +187 -0
- package/dist/core/trust-manager.js.map +1 -0
- package/dist/index.d.ts +31 -29
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -8
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts +5 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +170 -87
- package/dist/main.js.map +1 -1
- package/dist/migrations.d.ts +2 -2
- package/dist/migrations.d.ts.map +1 -1
- package/dist/migrations.js +127 -5
- package/dist/migrations.js.map +1 -1
- package/dist/modes/index.d.ts +5 -5
- package/dist/modes/index.d.ts.map +1 -1
- package/dist/modes/index.js.map +1 -1
- package/dist/modes/interactive/components/assistant-message.d.ts +2 -0
- package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/assistant-message.js +14 -0
- package/dist/modes/interactive/components/assistant-message.js.map +1 -1
- package/dist/modes/interactive/components/bash-execution.d.ts +1 -1
- package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
- package/dist/modes/interactive/components/bash-execution.js +3 -3
- package/dist/modes/interactive/components/bash-execution.js.map +1 -1
- package/dist/modes/interactive/components/bordered-loader.d.ts.map +1 -1
- package/dist/modes/interactive/components/bordered-loader.js +3 -0
- package/dist/modes/interactive/components/bordered-loader.js.map +1 -1
- package/dist/modes/interactive/components/config-selector.d.ts +4 -4
- package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/config-selector.js +38 -11
- package/dist/modes/interactive/components/config-selector.js.map +1 -1
- package/dist/modes/interactive/components/countdown-timer.d.ts +2 -2
- package/dist/modes/interactive/components/countdown-timer.d.ts.map +1 -1
- package/dist/modes/interactive/components/countdown-timer.js +2 -2
- package/dist/modes/interactive/components/countdown-timer.js.map +1 -1
- package/dist/modes/interactive/components/custom-editor.d.ts +1 -1
- package/dist/modes/interactive/components/custom-editor.d.ts.map +1 -1
- package/dist/modes/interactive/components/custom-editor.js.map +1 -1
- package/dist/modes/interactive/components/custom-message.d.ts +2 -2
- package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/custom-message.js.map +1 -1
- package/dist/modes/interactive/components/diff.d.ts.map +1 -1
- package/dist/modes/interactive/components/diff.js.map +1 -1
- package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -1
- package/dist/modes/interactive/components/earendil-announcement.js.map +1 -1
- package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-editor.js +14 -6
- package/dist/modes/interactive/components/extension-editor.js.map +1 -1
- package/dist/modes/interactive/components/extension-input.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-input.js.map +1 -1
- package/dist/modes/interactive/components/extension-selector.d.ts +2 -0
- package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-selector.js +8 -3
- package/dist/modes/interactive/components/extension-selector.js.map +1 -1
- package/dist/modes/interactive/components/first-time-setup.d.ts +25 -0
- package/dist/modes/interactive/components/first-time-setup.d.ts.map +1 -0
- package/dist/modes/interactive/components/first-time-setup.js +103 -0
- package/dist/modes/interactive/components/first-time-setup.js.map +1 -0
- package/dist/modes/interactive/components/footer.d.ts +2 -1
- package/dist/modes/interactive/components/footer.d.ts.map +1 -1
- package/dist/modes/interactive/components/footer.js +23 -7
- package/dist/modes/interactive/components/footer.js.map +1 -1
- package/dist/modes/interactive/components/index.d.ts +33 -31
- package/dist/modes/interactive/components/index.d.ts.map +1 -1
- package/dist/modes/interactive/components/index.js +2 -0
- package/dist/modes/interactive/components/index.js.map +1 -1
- package/dist/modes/interactive/components/keybinding-hints.d.ts +5 -0
- package/dist/modes/interactive/components/keybinding-hints.d.ts.map +1 -1
- package/dist/modes/interactive/components/keybinding-hints.js +19 -5
- package/dist/modes/interactive/components/keybinding-hints.js.map +1 -1
- package/dist/modes/interactive/components/login-dialog.d.ts +12 -2
- package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
- package/dist/modes/interactive/components/login-dialog.js +46 -11
- package/dist/modes/interactive/components/login-dialog.js.map +1 -1
- package/dist/modes/interactive/components/model-selector.d.ts +2 -2
- package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/model-selector.js +8 -5
- package/dist/modes/interactive/components/model-selector.js.map +1 -1
- package/dist/modes/interactive/components/oauth-selector.d.ts +18 -6
- package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/oauth-selector.js +93 -25
- package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
- package/dist/modes/interactive/components/scoped-models-selector.d.ts +5 -12
- package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/scoped-models-selector.js +45 -30
- package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
- package/dist/modes/interactive/components/session-selector.d.ts +2 -1
- package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/session-selector.js +20 -7
- package/dist/modes/interactive/components/session-selector.js.map +1 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +13 -0
- package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +113 -4
- package/dist/modes/interactive/components/settings-selector.js.map +1 -1
- package/dist/modes/interactive/components/skill-invocation-message.d.ts +1 -1
- package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/skill-invocation-message.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 -1
- package/dist/modes/interactive/components/thinking-selector.js.map +1 -1
- package/dist/modes/interactive/components/tool-execution.d.ts +6 -1
- package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
- package/dist/modes/interactive/components/tool-execution.js +57 -14
- package/dist/modes/interactive/components/tool-execution.js.map +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +18 -9
- package/dist/modes/interactive/components/tree-selector.js.map +1 -1
- package/dist/modes/interactive/components/trust-selector.d.ts +23 -0
- package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -0
- package/dist/modes/interactive/components/trust-selector.js +91 -0
- package/dist/modes/interactive/components/trust-selector.js.map +1 -0
- package/dist/modes/interactive/components/user-message-selector.d.ts +2 -2
- package/dist/modes/interactive/components/user-message-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/user-message-selector.js +8 -7
- package/dist/modes/interactive/components/user-message-selector.js.map +1 -1
- package/dist/modes/interactive/components/user-message.d.ts +1 -0
- package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/user-message.js +8 -7
- package/dist/modes/interactive/components/user-message.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +68 -13
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +1100 -319
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/interactive/theme/dark.json +5 -4
- package/dist/modes/interactive/theme/light.json +5 -4
- package/dist/modes/interactive/theme/theme.d.ts +22 -3
- package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
- package/dist/modes/interactive/theme/theme.js +160 -105
- package/dist/modes/interactive/theme/theme.js.map +1 -1
- package/dist/modes/print-mode.d.ts.map +1 -1
- package/dist/modes/print-mode.js +40 -20
- package/dist/modes/print-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-client.d.ts +11 -1
- package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-client.js +73 -8
- 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 +96 -30
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +16 -4
- package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-types.js.map +1 -1
- package/dist/package-manager-cli.d.ts +6 -2
- package/dist/package-manager-cli.d.ts.map +1 -1
- package/dist/package-manager-cli.js +396 -21
- package/dist/package-manager-cli.js.map +1 -1
- package/dist/prompts/commands/map-codebase.md +14 -0
- package/dist/utils/ansi.d.ts +2 -0
- package/dist/utils/ansi.d.ts.map +1 -0
- package/dist/utils/ansi.js +52 -0
- package/dist/utils/ansi.js.map +1 -0
- package/dist/utils/changelog.d.ts +2 -1
- package/dist/utils/changelog.d.ts.map +1 -1
- package/dist/utils/changelog.js +78 -0
- package/dist/utils/changelog.js.map +1 -1
- package/dist/utils/child-process.d.ts +5 -1
- package/dist/utils/child-process.d.ts.map +1 -1
- package/dist/utils/child-process.js +10 -0
- package/dist/utils/child-process.js.map +1 -1
- package/dist/utils/clipboard-image.d.ts.map +1 -1
- package/dist/utils/clipboard-image.js +2 -2
- package/dist/utils/clipboard-image.js.map +1 -1
- package/dist/utils/clipboard-native.d.ts +3 -1
- package/dist/utils/clipboard-native.d.ts.map +1 -1
- package/dist/utils/clipboard-native.js +14 -8
- package/dist/utils/clipboard-native.js.map +1 -1
- package/dist/utils/clipboard.d.ts.map +1 -1
- package/dist/utils/clipboard.js +84 -45
- package/dist/utils/clipboard.js.map +1 -1
- package/dist/utils/deprecation.d.ts +4 -0
- package/dist/utils/deprecation.d.ts.map +1 -0
- package/dist/utils/deprecation.js +13 -0
- package/dist/utils/deprecation.js.map +1 -0
- package/dist/utils/exif-orientation.d.ts +1 -1
- package/dist/utils/exif-orientation.d.ts.map +1 -1
- package/dist/utils/exif-orientation.js.map +1 -1
- package/dist/utils/fs-watch.d.ts +5 -0
- package/dist/utils/fs-watch.d.ts.map +1 -0
- package/dist/utils/fs-watch.js +25 -0
- package/dist/utils/fs-watch.js.map +1 -0
- package/dist/utils/git.d.ts.map +1 -1
- package/dist/utils/git.js +54 -22
- package/dist/utils/git.js.map +1 -1
- package/dist/utils/html.d.ts +7 -0
- package/dist/utils/html.d.ts.map +1 -0
- package/dist/utils/html.js +40 -0
- package/dist/utils/html.js.map +1 -0
- package/dist/utils/image-convert.d.ts.map +1 -1
- package/dist/utils/image-convert.js.map +1 -1
- package/dist/utils/image-resize-core.d.ts +30 -0
- package/dist/utils/image-resize-core.d.ts.map +1 -0
- package/dist/utils/image-resize-core.js +124 -0
- package/dist/utils/image-resize-core.js.map +1 -0
- package/dist/utils/image-resize-worker.d.ts +2 -0
- package/dist/utils/image-resize-worker.d.ts.map +1 -0
- package/dist/utils/image-resize-worker.js +31 -0
- package/dist/utils/image-resize-worker.js.map +1 -0
- package/dist/utils/image-resize.d.ts +7 -27
- package/dist/utils/image-resize.d.ts.map +1 -1
- package/dist/utils/image-resize.js +75 -115
- package/dist/utils/image-resize.js.map +1 -1
- package/dist/utils/json.d.ts +3 -0
- package/dist/utils/json.d.ts.map +1 -0
- package/dist/utils/json.js +7 -0
- package/dist/utils/json.js.map +1 -0
- package/dist/utils/mime.d.ts +1 -0
- package/dist/utils/mime.d.ts.map +1 -1
- package/dist/utils/mime.js +59 -16
- package/dist/utils/mime.js.map +1 -1
- package/dist/utils/open-browser.d.ts +9 -0
- package/dist/utils/open-browser.d.ts.map +1 -0
- package/dist/utils/open-browser.js +22 -0
- package/dist/utils/open-browser.js.map +1 -0
- package/dist/utils/paths.d.ts +25 -1
- package/dist/utils/paths.d.ts.map +1 -1
- package/dist/utils/paths.js +75 -2
- package/dist/utils/paths.js.map +1 -1
- package/dist/utils/pi-user-agent.d.ts +2 -0
- package/dist/utils/pi-user-agent.d.ts.map +1 -0
- package/dist/utils/pi-user-agent.js +5 -0
- package/dist/utils/pi-user-agent.js.map +1 -0
- package/dist/utils/shell.d.ts +10 -6
- package/dist/utils/shell.d.ts.map +1 -1
- package/dist/utils/shell.js +35 -26
- package/dist/utils/shell.js.map +1 -1
- package/dist/utils/syntax-highlight.d.ts +12 -0
- package/dist/utils/syntax-highlight.d.ts.map +1 -0
- package/dist/utils/syntax-highlight.js +118 -0
- package/dist/utils/syntax-highlight.js.map +1 -0
- package/dist/utils/tools-manager.d.ts.map +1 -1
- package/dist/utils/tools-manager.js +86 -10
- package/dist/utils/tools-manager.js.map +1 -1
- package/dist/utils/version-check.d.ts +15 -0
- package/dist/utils/version-check.d.ts.map +1 -0
- package/dist/utils/version-check.js +82 -0
- package/dist/utils/version-check.js.map +1 -0
- package/dist/utils/windows-self-update.d.ts +3 -0
- package/dist/utils/windows-self-update.d.ts.map +1 -0
- package/dist/utils/windows-self-update.js +77 -0
- package/dist/utils/windows-self-update.js.map +1 -0
- package/docs/compaction.md +12 -12
- package/docs/containerization.md +111 -0
- package/docs/custom-provider.md +187 -47
- package/docs/development.md +5 -5
- package/docs/docs.json +156 -0
- package/docs/extensions.md +465 -71
- package/docs/index.md +82 -0
- package/docs/json.md +4 -4
- package/docs/keybindings.md +23 -1
- package/docs/models.md +119 -17
- package/docs/packages.md +17 -9
- package/docs/prompt-templates.md +30 -2
- package/docs/providers.md +83 -22
- package/docs/quickstart.md +165 -0
- package/docs/rpc.md +41 -10
- package/docs/sdk.md +68 -50
- package/docs/security.md +55 -0
- package/docs/{session.md → session-format.md} +11 -11
- package/docs/sessions.md +145 -0
- package/docs/settings.md +61 -11
- package/docs/skills.md +16 -17
- package/docs/terminal-setup.md +44 -2
- package/docs/termux.md +4 -4
- package/docs/themes.md +3 -3
- package/docs/tmux.md +4 -2
- package/docs/tui.md +44 -4
- package/docs/usage.md +305 -0
- package/examples/extensions/border-status-editor.ts +145 -0
- package/examples/extensions/built-in-tool-renderer.ts +3 -0
- package/examples/extensions/custom-header.ts +1 -1
- package/examples/extensions/custom-provider-anthropic/index.ts +1 -1
- package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
- package/examples/extensions/custom-provider-anthropic/package.json +2 -2
- package/examples/extensions/custom-provider-gitlab-duo/index.ts +55 -4
- package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
- package/examples/extensions/custom-provider-gitlab-duo/test.ts +1 -1
- package/examples/extensions/doom-overlay/doom-component.ts +2 -2
- package/examples/extensions/doom-overlay/index.ts +1 -1
- package/examples/extensions/dynamic-resources/dynamic.json +1 -1
- package/examples/extensions/dynamic-tools.ts +2 -2
- package/examples/extensions/git-merge-and-resolve.ts +115 -0
- package/examples/extensions/github-issue-autocomplete.ts +185 -0
- package/examples/extensions/gondolin/index.ts +531 -0
- package/examples/extensions/gondolin/package-lock.json +185 -0
- package/examples/extensions/gondolin/package.json +19 -0
- package/examples/extensions/handoff.ts +50 -12
- package/examples/extensions/input-transform-streaming.ts +39 -0
- package/examples/extensions/interactive-shell.ts +1 -1
- package/examples/extensions/notify.ts +2 -9
- package/examples/extensions/overlay-qa-tests.ts +240 -138
- package/examples/extensions/overlay-test.ts +7 -4
- package/examples/extensions/plan-mode/utils.ts +1 -1
- package/examples/extensions/preset.ts +36 -3
- package/examples/extensions/project-trust.ts +64 -0
- package/examples/extensions/prompt-customizer.ts +97 -0
- package/examples/extensions/provider-payload.ts +4 -0
- package/examples/extensions/qna.ts +1 -1
- package/examples/extensions/question.ts +2 -2
- package/examples/extensions/questionnaire.ts +2 -2
- package/examples/extensions/reload-runtime.ts +1 -1
- package/examples/extensions/sandbox/index.ts +4 -4
- package/examples/extensions/sandbox/package-lock.json +5 -5
- package/examples/extensions/sandbox/package.json +2 -2
- package/examples/extensions/shutdown-command.ts +1 -1
- package/examples/extensions/snake.ts +1 -1
- package/examples/extensions/space-invaders.ts +1 -1
- package/examples/extensions/structured-output.ts +65 -0
- package/examples/extensions/subagent/index.ts +51 -28
- package/examples/extensions/summarize.ts +1 -1
- package/examples/extensions/tic-tac-toe.ts +1008 -0
- package/examples/extensions/titlebar-spinner.ts +2 -2
- package/examples/extensions/todo.ts +2 -2
- package/examples/extensions/tool-override.ts +1 -1
- package/examples/extensions/tools.ts +5 -0
- package/examples/extensions/truncated-tool.ts +1 -1
- package/examples/extensions/with-deps/index.ts +1 -1
- package/examples/extensions/with-deps/package-lock.json +2 -2
- package/examples/extensions/with-deps/package.json +3 -3
- package/examples/extensions/working-indicator.ts +123 -0
- package/examples/extensions/working-message-test.ts +25 -0
- package/examples/sdk/01-minimal.ts +14 -10
- package/examples/sdk/02-custom-model.ts +12 -8
- package/examples/sdk/03-custom-prompt.ts +32 -17
- package/examples/sdk/04-skills.ts +5 -2
- package/examples/sdk/05-tools.ts +23 -31
- package/examples/sdk/06-extensions.ts +14 -8
- package/examples/sdk/07-context-files.ts +5 -3
- package/examples/sdk/08-prompt-templates.ts +5 -2
- package/examples/sdk/09-api-keys-and-oauth.ts +8 -4
- package/examples/sdk/10-settings.ts +8 -6
- package/examples/sdk/11-sessions.ts +4 -0
- package/examples/sdk/12-full-control.ts +13 -17
- package/package.json +13 -6
- package/prompts/commands/map-codebase.md +14 -0
package/docs/extensions.md
CHANGED
|
@@ -40,6 +40,7 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
|
|
|
40
40
|
- [Resource Events](#resource-events)
|
|
41
41
|
- [Session Events](#session-events)
|
|
42
42
|
- [Agent Events](#agent-events)
|
|
43
|
+
- [Model Events](#model-events)
|
|
43
44
|
- [Tool Events](#tool-events)
|
|
44
45
|
- [ExtensionContext](#extensioncontext)
|
|
45
46
|
- [ExtensionCommandContext](#extensioncommandcontext)
|
|
@@ -57,7 +58,7 @@ Create `~/.pi/agent/extensions/my-extension.ts`:
|
|
|
57
58
|
|
|
58
59
|
```typescript
|
|
59
60
|
import type { ExtensionAPI } from "@draht/coding-agent";
|
|
60
|
-
import { Type } from "
|
|
61
|
+
import { Type } from "typebox";
|
|
61
62
|
|
|
62
63
|
export default function (pi: ExtensionAPI) {
|
|
63
64
|
// React to events
|
|
@@ -108,7 +109,7 @@ pi -e ./my-extension.ts
|
|
|
108
109
|
|
|
109
110
|
> **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
|
|
110
111
|
|
|
111
|
-
Extensions are auto-discovered from
|
|
112
|
+
Extensions are auto-discovered from trusted locations. Project-local `.pi/extensions` entries load only after the project is trusted.
|
|
112
113
|
|
|
113
114
|
| Location | Scope |
|
|
114
115
|
|----------|-------|
|
|
@@ -139,17 +140,19 @@ To share extensions via npm or git as pi packages, see [packages.md](packages.md
|
|
|
139
140
|
| Package | Purpose |
|
|
140
141
|
|---------|---------|
|
|
141
142
|
| `@draht/coding-agent` | Extension types (`ExtensionAPI`, `ExtensionContext`, events) |
|
|
142
|
-
|
|
|
143
|
+
| `typebox` | Schema definitions for tool parameters |
|
|
143
144
|
| `@draht/ai` | AI utilities (`StringEnum` for Google-compatible enums) |
|
|
144
145
|
| `@draht/tui` | TUI components for custom rendering |
|
|
145
146
|
|
|
146
147
|
npm dependencies work too. Add a `package.json` next to your extension (or in a parent directory), run `npm install`, and imports from `node_modules/` are resolved automatically.
|
|
147
148
|
|
|
149
|
+
For distributed pi packages installed with `pi install` (npm or git), runtime deps must be in `dependencies`. Package installation uses production installs (`npm install --omit=dev`) by default, so `devDependencies` are not available at runtime; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers.
|
|
150
|
+
|
|
148
151
|
Node.js built-ins (`node:fs`, `node:path`, etc.) are also available.
|
|
149
152
|
|
|
150
153
|
## Writing an Extension
|
|
151
154
|
|
|
152
|
-
An extension exports a default function that receives `ExtensionAPI
|
|
155
|
+
An extension exports a default factory function that receives `ExtensionAPI`. The factory can be synchronous or asynchronous:
|
|
153
156
|
|
|
154
157
|
```typescript
|
|
155
158
|
import type { ExtensionAPI } from "@draht/coding-agent";
|
|
@@ -159,7 +162,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
159
162
|
pi.on("event_name", async (event, ctx) => {
|
|
160
163
|
// ctx.ui for user interaction
|
|
161
164
|
const ok = await ctx.ui.confirm("Title", "Are you sure?");
|
|
162
|
-
ctx.ui.notify("Done!", "
|
|
165
|
+
ctx.ui.notify("Done!", "info");
|
|
163
166
|
ctx.ui.setStatus("my-ext", "Processing..."); // Footer status
|
|
164
167
|
ctx.ui.setWidget("my-ext", ["Line 1", "Line 2"]); // Widget above editor (default)
|
|
165
168
|
});
|
|
@@ -174,6 +177,45 @@ export default function (pi: ExtensionAPI) {
|
|
|
174
177
|
|
|
175
178
|
Extensions are loaded via [jiti](https://github.com/unjs/jiti), so TypeScript works without compilation.
|
|
176
179
|
|
|
180
|
+
If the factory returns a `Promise`, pi awaits it before continuing startup. That means async initialization completes before `session_start`, before `resources_discover`, and before provider registrations queued via `pi.registerProvider()` are flushed.
|
|
181
|
+
|
|
182
|
+
### Async factory functions
|
|
183
|
+
|
|
184
|
+
Use an async factory for one-time startup work such as fetching remote configuration or dynamically discovering available models.
|
|
185
|
+
|
|
186
|
+
```typescript
|
|
187
|
+
import type { ExtensionAPI } from "@draht/coding-agent";
|
|
188
|
+
|
|
189
|
+
export default async function (pi: ExtensionAPI) {
|
|
190
|
+
const response = await fetch("http://localhost:1234/v1/models");
|
|
191
|
+
const payload = (await response.json()) as {
|
|
192
|
+
data: Array<{
|
|
193
|
+
id: string;
|
|
194
|
+
name?: string;
|
|
195
|
+
context_window?: number;
|
|
196
|
+
max_tokens?: number;
|
|
197
|
+
}>;
|
|
198
|
+
};
|
|
199
|
+
|
|
200
|
+
pi.registerProvider("local-openai", {
|
|
201
|
+
baseUrl: "http://localhost:1234/v1",
|
|
202
|
+
apiKey: "$LOCAL_OPENAI_API_KEY",
|
|
203
|
+
api: "openai-completions",
|
|
204
|
+
models: payload.data.map((model) => ({
|
|
205
|
+
id: model.id,
|
|
206
|
+
name: model.name ?? model.id,
|
|
207
|
+
reasoning: false,
|
|
208
|
+
input: ["text"],
|
|
209
|
+
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
210
|
+
contextWindow: model.context_window ?? 128000,
|
|
211
|
+
maxTokens: model.max_tokens ?? 4096,
|
|
212
|
+
})),
|
|
213
|
+
});
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
This pattern makes the fetched models available during normal startup and to `pi --list-models`.
|
|
218
|
+
|
|
177
219
|
### Extension Styles
|
|
178
220
|
|
|
179
221
|
**Single file** - simplest, for small extensions:
|
|
@@ -213,7 +255,7 @@ Extensions are loaded via [jiti](https://github.com/unjs/jiti), so TypeScript wo
|
|
|
213
255
|
"zod": "^3.0.0",
|
|
214
256
|
"chalk": "^5.0.0"
|
|
215
257
|
},
|
|
216
|
-
"
|
|
258
|
+
"pi": {
|
|
217
259
|
"extensions": ["./src/index.ts"]
|
|
218
260
|
}
|
|
219
261
|
}
|
|
@@ -228,6 +270,7 @@ Run `npm install` in the extension directory, then imports from `node_modules/`
|
|
|
228
270
|
```
|
|
229
271
|
pi starts
|
|
230
272
|
│
|
|
273
|
+
├─► project_trust (user/global and CLI extensions only, before project resources load)
|
|
231
274
|
├─► session_start { reason: "startup" }
|
|
232
275
|
└─► resources_discover { reason: "startup" }
|
|
233
276
|
│
|
|
@@ -246,6 +289,7 @@ user sends prompt ────────────────────
|
|
|
246
289
|
│ ├─► turn_start │ │
|
|
247
290
|
│ ├─► context (can modify messages) │ │
|
|
248
291
|
│ ├─► before_provider_request (can inspect or replace payload)
|
|
292
|
+
│ ├─► after_provider_response (status + headers, before stream consume)
|
|
249
293
|
│ │ │ │
|
|
250
294
|
│ │ LLM responds, may call tools: │ │
|
|
251
295
|
│ │ ├─► tool_execution_start │ │
|
|
@@ -266,7 +310,7 @@ user sends another prompt ◄─────────────────
|
|
|
266
310
|
├─► session_start { reason: "new" | "resume", previousSessionFile? }
|
|
267
311
|
└─► resources_discover { reason: "startup" }
|
|
268
312
|
|
|
269
|
-
/fork
|
|
313
|
+
/fork or /clone
|
|
270
314
|
├─► session_before_fork (can cancel)
|
|
271
315
|
├─► session_shutdown
|
|
272
316
|
├─► session_start { reason: "fork", previousSessionFile }
|
|
@@ -281,12 +325,35 @@ user sends another prompt ◄─────────────────
|
|
|
281
325
|
└─► session_tree
|
|
282
326
|
|
|
283
327
|
/model or Ctrl+P (model selection/cycling)
|
|
328
|
+
├─► thinking_level_select (if model change changes/clamps thinking level)
|
|
284
329
|
└─► model_select
|
|
285
330
|
|
|
286
|
-
|
|
331
|
+
thinking level changes (settings, keybinding, pi.setThinkingLevel())
|
|
332
|
+
└─► thinking_level_select
|
|
333
|
+
|
|
334
|
+
exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
|
|
287
335
|
└─► session_shutdown
|
|
288
336
|
```
|
|
289
337
|
|
|
338
|
+
### Startup Events
|
|
339
|
+
|
|
340
|
+
#### project_trust
|
|
341
|
+
|
|
342
|
+
Fired before pi decides whether to trust a project with dynamic configs (`.pi` or `.agents/skills`). It runs during startup and when session replacement (for example `/resume`) enters a cwd whose trust has not been resolved in the current process. Only user/global extensions and CLI `-e` extensions participate; project-local extensions are not loaded until after trust is resolved.
|
|
343
|
+
|
|
344
|
+
```typescript
|
|
345
|
+
pi.on("project_trust", async (event, ctx) => {
|
|
346
|
+
// event.cwd - current working directory
|
|
347
|
+
// ctx has a limited trust context: cwd, mode, hasUI, and select/confirm/input/notify UI helpers
|
|
348
|
+
if (await ctx.ui.confirm("Trust project?", event.cwd)) {
|
|
349
|
+
return { trusted: "yes", remember: true };
|
|
350
|
+
}
|
|
351
|
+
return { trusted: "undecided" };
|
|
352
|
+
});
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
A `project_trust` handler must return `{ trusted: "yes" | "no" | "undecided" }`. A user/global or CLI extension that returns `"yes"` or `"no"` owns the decision; the first yes/no decision wins and suppresses the built-in trust prompt. Use `remember: true` to persist a yes/no decision; otherwise it applies only to the current process. Return `"undecided"` to let later handlers or the built-in trust flow decide. Check `ctx.hasUI` before prompting. If no handler returns yes/no, normal trust resolution continues: saved `trust.json` decisions apply first, then `defaultProjectTrust` controls whether pi asks, trusts, or declines by default.
|
|
356
|
+
|
|
290
357
|
### Resource Events
|
|
291
358
|
|
|
292
359
|
#### resources_discover
|
|
@@ -308,7 +375,7 @@ pi.on("resources_discover", async (event, _ctx) => {
|
|
|
308
375
|
|
|
309
376
|
### Session Events
|
|
310
377
|
|
|
311
|
-
See [
|
|
378
|
+
See [Session Format](session-format.md) for session storage internals and the SessionManager API.
|
|
312
379
|
|
|
313
380
|
#### session_start
|
|
314
381
|
|
|
@@ -343,18 +410,19 @@ Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `
|
|
|
343
410
|
|
|
344
411
|
#### session_before_fork
|
|
345
412
|
|
|
346
|
-
Fired when forking via `/fork`.
|
|
413
|
+
Fired when forking via `/fork` or cloning via `/clone`.
|
|
347
414
|
|
|
348
415
|
```typescript
|
|
349
416
|
pi.on("session_before_fork", async (event, ctx) => {
|
|
350
|
-
// event.entryId - ID of the entry
|
|
351
|
-
|
|
417
|
+
// event.entryId - ID of the selected entry
|
|
418
|
+
// event.position - "before" for /fork, "at" for /clone
|
|
419
|
+
return { cancel: true }; // Cancel fork/clone
|
|
352
420
|
// OR
|
|
353
|
-
return { skipConversationRestore: true }; //
|
|
421
|
+
return { skipConversationRestore: true }; // Reserved for future conversation restore control
|
|
354
422
|
});
|
|
355
423
|
```
|
|
356
424
|
|
|
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`.
|
|
425
|
+
After a successful fork or clone, pi emits `session_shutdown` for the old extension instance, reloads and rebinds extensions for the new session, then emits `session_start` with `reason: "fork"` and `previousSessionFile`.
|
|
358
426
|
Do cleanup work in `session_shutdown`, then reestablish any in-memory state in `session_start`.
|
|
359
427
|
|
|
360
428
|
#### session_before_compact / session_compact
|
|
@@ -386,7 +454,7 @@ pi.on("session_compact", async (event, ctx) => {
|
|
|
386
454
|
|
|
387
455
|
#### session_before_tree / session_tree
|
|
388
456
|
|
|
389
|
-
Fired on `/tree` navigation. See [
|
|
457
|
+
Fired on `/tree` navigation. See [Sessions](sessions.md) for tree navigation concepts.
|
|
390
458
|
|
|
391
459
|
```typescript
|
|
392
460
|
pi.on("session_before_tree", async (event, ctx) => {
|
|
@@ -403,10 +471,12 @@ pi.on("session_tree", async (event, ctx) => {
|
|
|
403
471
|
|
|
404
472
|
#### session_shutdown
|
|
405
473
|
|
|
406
|
-
Fired
|
|
474
|
+
Fired before an extension runtime is torn down.
|
|
407
475
|
|
|
408
476
|
```typescript
|
|
409
|
-
pi.on("session_shutdown", async (
|
|
477
|
+
pi.on("session_shutdown", async (event, ctx) => {
|
|
478
|
+
// event.reason - "quit" | "reload" | "new" | "resume" | "fork"
|
|
479
|
+
// event.targetSessionFile - destination session for session replacement flows
|
|
410
480
|
// Cleanup, save state, etc.
|
|
411
481
|
});
|
|
412
482
|
```
|
|
@@ -421,7 +491,17 @@ Fired after user submits prompt, before agent loop. Can inject a message and/or
|
|
|
421
491
|
pi.on("before_agent_start", async (event, ctx) => {
|
|
422
492
|
// event.prompt - user's prompt text
|
|
423
493
|
// event.images - attached images (if any)
|
|
424
|
-
// event.systemPrompt - current system prompt
|
|
494
|
+
// event.systemPrompt - current chained system prompt for this handler
|
|
495
|
+
// (includes changes from earlier before_agent_start handlers)
|
|
496
|
+
// event.systemPromptOptions - structured options used to build the system prompt
|
|
497
|
+
// .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
|
|
498
|
+
// .selectedTools - tools currently active in the prompt
|
|
499
|
+
// .toolSnippets - one-line descriptions for each tool
|
|
500
|
+
// .promptGuidelines - custom guideline bullets
|
|
501
|
+
// .appendSystemPrompt - text from --append-system-prompt flags
|
|
502
|
+
// .cwd - working directory
|
|
503
|
+
// .contextFiles - AGENTS.md files and other loaded context files
|
|
504
|
+
// .skills - loaded skills
|
|
425
505
|
|
|
426
506
|
return {
|
|
427
507
|
// Inject a persistent message (stored in session, sent to LLM)
|
|
@@ -436,6 +516,10 @@ pi.on("before_agent_start", async (event, ctx) => {
|
|
|
436
516
|
});
|
|
437
517
|
```
|
|
438
518
|
|
|
519
|
+
The `systemPromptOptions` field gives extensions access to the same structured data Pi uses to build the system prompt. This lets you inspect what Pi has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
|
|
520
|
+
|
|
521
|
+
Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
|
|
522
|
+
|
|
439
523
|
#### agent_start / agent_end
|
|
440
524
|
|
|
441
525
|
Fired once per user prompt.
|
|
@@ -468,6 +552,7 @@ Fired for message lifecycle updates.
|
|
|
468
552
|
|
|
469
553
|
- `message_start` and `message_end` fire for user, assistant, and toolResult messages.
|
|
470
554
|
- `message_update` fires for assistant streaming updates.
|
|
555
|
+
- `message_end` handlers can return `{ message }` to replace the finalized message. The replacement must keep the same `role`.
|
|
471
556
|
|
|
472
557
|
```typescript
|
|
473
558
|
pi.on("message_start", async (event, ctx) => {
|
|
@@ -480,7 +565,20 @@ pi.on("message_update", async (event, ctx) => {
|
|
|
480
565
|
});
|
|
481
566
|
|
|
482
567
|
pi.on("message_end", async (event, ctx) => {
|
|
483
|
-
|
|
568
|
+
if (event.message.role !== "assistant") return;
|
|
569
|
+
|
|
570
|
+
return {
|
|
571
|
+
message: {
|
|
572
|
+
...event.message,
|
|
573
|
+
usage: {
|
|
574
|
+
...event.message.usage,
|
|
575
|
+
cost: {
|
|
576
|
+
...event.message.usage.cost,
|
|
577
|
+
total: 0.123,
|
|
578
|
+
},
|
|
579
|
+
},
|
|
580
|
+
},
|
|
581
|
+
};
|
|
484
582
|
});
|
|
485
583
|
```
|
|
486
584
|
|
|
@@ -491,7 +589,8 @@ Fired for tool execution lifecycle updates.
|
|
|
491
589
|
In parallel tool mode:
|
|
492
590
|
- `tool_execution_start` is emitted in assistant source order during the preflight phase
|
|
493
591
|
- `tool_execution_update` events may interleave across tools
|
|
494
|
-
- `tool_execution_end` is emitted in
|
|
592
|
+
- `tool_execution_end` is emitted in tool completion order after each tool is finalized
|
|
593
|
+
- final `toolResult` message events are still emitted later in assistant source order
|
|
495
594
|
|
|
496
595
|
```typescript
|
|
497
596
|
pi.on("tool_execution_start", async (event, ctx) => {
|
|
@@ -509,7 +608,7 @@ pi.on("tool_execution_end", async (event, ctx) => {
|
|
|
509
608
|
|
|
510
609
|
#### context
|
|
511
610
|
|
|
512
|
-
Fired before each LLM call. Modify messages non-destructively. See [
|
|
611
|
+
Fired before each LLM call. Modify messages non-destructively. See [Session Format](session-format.md) for message types.
|
|
513
612
|
|
|
514
613
|
```typescript
|
|
515
614
|
pi.on("context", async (event, ctx) => {
|
|
@@ -523,6 +622,8 @@ pi.on("context", async (event, ctx) => {
|
|
|
523
622
|
|
|
524
623
|
Fired after the provider-specific payload is built, right before the request is sent. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
|
|
525
624
|
|
|
625
|
+
This hook can rewrite provider-level system instructions or remove them entirely. Those payload-level changes are not reflected by `ctx.getSystemPrompt()`, which reports Pi's system prompt string rather than the final serialized provider payload.
|
|
626
|
+
|
|
526
627
|
```typescript
|
|
527
628
|
pi.on("before_provider_request", (event, ctx) => {
|
|
528
629
|
console.log(JSON.stringify(event.payload, null, 2));
|
|
@@ -534,6 +635,22 @@ pi.on("before_provider_request", (event, ctx) => {
|
|
|
534
635
|
|
|
535
636
|
This is mainly useful for debugging provider serialization and cache behavior.
|
|
536
637
|
|
|
638
|
+
#### after_provider_response
|
|
639
|
+
|
|
640
|
+
Fired after an HTTP response is received and before its stream body is consumed. Handlers run in extension load order.
|
|
641
|
+
|
|
642
|
+
```typescript
|
|
643
|
+
pi.on("after_provider_response", (event, ctx) => {
|
|
644
|
+
// event.status - HTTP status code
|
|
645
|
+
// event.headers - normalized response headers
|
|
646
|
+
if (event.status === 429) {
|
|
647
|
+
console.log("rate limited", event.headers["retry-after"]);
|
|
648
|
+
}
|
|
649
|
+
});
|
|
650
|
+
```
|
|
651
|
+
|
|
652
|
+
Header availability depends on provider and transport. Providers that abstract HTTP responses may not expose headers.
|
|
653
|
+
|
|
537
654
|
### Model Events
|
|
538
655
|
|
|
539
656
|
#### model_select
|
|
@@ -557,6 +674,21 @@ pi.on("model_select", async (event, ctx) => {
|
|
|
557
674
|
|
|
558
675
|
Use this to update UI elements (status bars, footers) or perform model-specific initialization when the active model changes.
|
|
559
676
|
|
|
677
|
+
#### thinking_level_select
|
|
678
|
+
|
|
679
|
+
Fired when the thinking level changes. This is notification-only; handler return values are ignored.
|
|
680
|
+
|
|
681
|
+
```typescript
|
|
682
|
+
pi.on("thinking_level_select", async (event, ctx) => {
|
|
683
|
+
// event.level - newly selected thinking level
|
|
684
|
+
// event.previousLevel - previous thinking level
|
|
685
|
+
|
|
686
|
+
ctx.ui.setStatus("thinking", `thinking: ${event.level}`);
|
|
687
|
+
});
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
Use this to update extension UI when `pi.setThinkingLevel()`, model changes, or built-in thinking-level controls change the active thinking level.
|
|
691
|
+
|
|
560
692
|
### Tool Events
|
|
561
693
|
|
|
562
694
|
#### tool_call
|
|
@@ -626,6 +758,8 @@ pi.on("tool_call", (event) => {
|
|
|
626
758
|
|
|
627
759
|
Fired after tool execution finishes and before `tool_execution_end` plus the final tool result message events are emitted. **Can modify result.**
|
|
628
760
|
|
|
761
|
+
In parallel tool mode, `tool_result` and `tool_execution_end` may interleave in tool completion order, while final `toolResult` message events are still emitted later in assistant source order.
|
|
762
|
+
|
|
629
763
|
`tool_result` handlers chain like middleware:
|
|
630
764
|
- Handlers run in extension load order
|
|
631
765
|
- Each handler sees the latest result after previous handler changes
|
|
@@ -705,6 +839,9 @@ pi.on("input", async (event, ctx) => {
|
|
|
705
839
|
// event.text - raw input (before skill/template expansion)
|
|
706
840
|
// event.images - attached images, if any
|
|
707
841
|
// event.source - "interactive" (typed), "rpc" (API), or "extension" (via sendUserMessage)
|
|
842
|
+
// event.streamingBehavior - "steer" | "followUp" | undefined
|
|
843
|
+
// undefined when idle, "steer" for mid-stream interrupts,
|
|
844
|
+
// "followUp" for messages queued until the agent finishes
|
|
708
845
|
|
|
709
846
|
// Transform: rewrite input before expansion
|
|
710
847
|
if (event.text.startsWith("?quick "))
|
|
@@ -733,7 +870,7 @@ pi.on("input", async (event, ctx) => {
|
|
|
733
870
|
- `transform` - modify text/images, then continue to expansion
|
|
734
871
|
- `handled` - skip agent entirely (first handler to return this wins)
|
|
735
872
|
|
|
736
|
-
Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts).
|
|
873
|
+
Transforms chain across handlers. See [input-transform.ts](../examples/extensions/input-transform.ts) and [input-transform-streaming.ts](../examples/extensions/input-transform-streaming.ts) for `streamingBehavior`-aware routing.
|
|
737
874
|
|
|
738
875
|
## ExtensionContext
|
|
739
876
|
|
|
@@ -743,17 +880,27 @@ All handlers receive `ctx: ExtensionContext`.
|
|
|
743
880
|
|
|
744
881
|
UI methods for user interaction. See [Custom UI](#custom-ui) for full details.
|
|
745
882
|
|
|
883
|
+
### ctx.mode
|
|
884
|
+
|
|
885
|
+
Current run mode: `"tui"`, `"rpc"`, `"json"`, or `"print"`. Use `ctx.mode === "tui"` to guard terminal-only features such as `custom()`, component factories, terminal input, and direct TUI rendering.
|
|
886
|
+
|
|
746
887
|
### ctx.hasUI
|
|
747
888
|
|
|
748
|
-
`false` in print mode (`-p`) and JSON mode.
|
|
889
|
+
`true` in TUI and RPC modes. `false` in print mode (`-p`) and JSON mode. Use this to guard dialog methods (`select`, `confirm`, `input`, `editor`) and fire-and-forget methods (`notify`, `setStatus`, `setWidget`, `setTitle`, `setEditorText`) that work in both TUI and RPC modes. In RPC mode, some TUI-specific methods are no-ops or return defaults (see [rpc.md](rpc.md#extension-ui-protocol)).
|
|
749
890
|
|
|
750
891
|
### ctx.cwd
|
|
751
892
|
|
|
752
893
|
Current working directory.
|
|
753
894
|
|
|
895
|
+
### ctx.isProjectTrusted()
|
|
896
|
+
|
|
897
|
+
Returns whether project-local trust is active for the current session context. This includes temporary trust decisions and CLI trust overrides, not just saved decisions in the global trust store.
|
|
898
|
+
|
|
899
|
+
Use this before reading project-local extension configuration that should only be honored for trusted projects.
|
|
900
|
+
|
|
754
901
|
### ctx.sessionManager
|
|
755
902
|
|
|
756
|
-
Read-only access to session state. See [
|
|
903
|
+
Read-only access to session state. See [Session Format](session-format.md) for the full SessionManager API and entry types.
|
|
757
904
|
|
|
758
905
|
For `tool_call`, this state is synchronized through the current assistant message before handlers run. In parallel tool execution mode it is still not guaranteed to include sibling tool results from the same assistant message.
|
|
759
906
|
|
|
@@ -843,7 +990,12 @@ ctx.compact({
|
|
|
843
990
|
|
|
844
991
|
### ctx.getSystemPrompt()
|
|
845
992
|
|
|
846
|
-
Returns
|
|
993
|
+
Returns Pi's current system prompt string.
|
|
994
|
+
|
|
995
|
+
- During `before_agent_start`, this reflects chained system-prompt changes made so far for the current turn.
|
|
996
|
+
- It does not include later `context` message mutations.
|
|
997
|
+
- It does not include `before_provider_request` payload rewrites.
|
|
998
|
+
- If later-loaded extensions run after yours, they can still change what is ultimately sent.
|
|
847
999
|
|
|
848
1000
|
```typescript
|
|
849
1001
|
pi.on("before_agent_start", (event, ctx) => {
|
|
@@ -856,6 +1008,19 @@ pi.on("before_agent_start", (event, ctx) => {
|
|
|
856
1008
|
|
|
857
1009
|
Command handlers receive `ExtensionCommandContext`, which extends `ExtensionContext` with session control methods. These are only available in commands because they can deadlock if called from event handlers.
|
|
858
1010
|
|
|
1011
|
+
### ctx.getSystemPromptOptions()
|
|
1012
|
+
|
|
1013
|
+
Returns the base inputs Pi currently uses to build the system prompt.
|
|
1014
|
+
|
|
1015
|
+
```typescript
|
|
1016
|
+
const options = ctx.getSystemPromptOptions();
|
|
1017
|
+
const contextPaths = options.contextFiles?.map((file) => file.path) ?? [];
|
|
1018
|
+
```
|
|
1019
|
+
|
|
1020
|
+
This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom prompt, active tools, tool snippets, prompt guidelines, appended system prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
|
|
1021
|
+
|
|
1022
|
+
This reports the current base prompt inputs. It does not include per-turn `before_agent_start` chained system-prompt changes, later `context` event message mutations, or `before_provider_request` payload rewrites.
|
|
1023
|
+
|
|
859
1024
|
### ctx.waitForIdle()
|
|
860
1025
|
|
|
861
1026
|
Wait for the agent to finish streaming:
|
|
@@ -874,8 +1039,11 @@ pi.registerCommand("my-cmd", {
|
|
|
874
1039
|
Create a new session:
|
|
875
1040
|
|
|
876
1041
|
```typescript
|
|
1042
|
+
const parentSession = ctx.sessionManager.getSessionFile();
|
|
1043
|
+
const kickoff = "Continue in the replacement session";
|
|
1044
|
+
|
|
877
1045
|
const result = await ctx.newSession({
|
|
878
|
-
parentSession
|
|
1046
|
+
parentSession,
|
|
879
1047
|
setup: async (sm) => {
|
|
880
1048
|
sm.appendMessage({
|
|
881
1049
|
role: "user",
|
|
@@ -883,6 +1051,10 @@ const result = await ctx.newSession({
|
|
|
883
1051
|
timestamp: Date.now(),
|
|
884
1052
|
});
|
|
885
1053
|
},
|
|
1054
|
+
withSession: async (ctx) => {
|
|
1055
|
+
// Use only the replacement-session ctx here.
|
|
1056
|
+
await ctx.sendUserMessage(kickoff);
|
|
1057
|
+
},
|
|
886
1058
|
});
|
|
887
1059
|
|
|
888
1060
|
if (result.cancelled) {
|
|
@@ -890,17 +1062,37 @@ if (result.cancelled) {
|
|
|
890
1062
|
}
|
|
891
1063
|
```
|
|
892
1064
|
|
|
893
|
-
|
|
1065
|
+
Options:
|
|
1066
|
+
- `parentSession`: parent session file to record in the new session header
|
|
1067
|
+
- `setup`: mutate the new session's `SessionManager` before `withSession` runs
|
|
1068
|
+
- `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
|
|
1069
|
+
|
|
1070
|
+
### ctx.fork(entryId, options?)
|
|
894
1071
|
|
|
895
1072
|
Fork from a specific entry, creating a new session file:
|
|
896
1073
|
|
|
897
1074
|
```typescript
|
|
898
|
-
const result = await ctx.fork("entry-id-123"
|
|
899
|
-
|
|
900
|
-
|
|
1075
|
+
const result = await ctx.fork("entry-id-123", {
|
|
1076
|
+
withSession: async (ctx) => {
|
|
1077
|
+
// Use only the replacement-session ctx here.
|
|
1078
|
+
ctx.ui.notify("Now in the forked session", "info");
|
|
1079
|
+
},
|
|
1080
|
+
});
|
|
1081
|
+
if (result.cancelled) {
|
|
1082
|
+
// An extension cancelled the fork
|
|
1083
|
+
}
|
|
1084
|
+
|
|
1085
|
+
const cloneResult = await ctx.fork("entry-id-456", { position: "at" });
|
|
1086
|
+
if (cloneResult.cancelled) {
|
|
1087
|
+
// An extension cancelled the clone
|
|
901
1088
|
}
|
|
902
1089
|
```
|
|
903
1090
|
|
|
1091
|
+
Options:
|
|
1092
|
+
- `position`: `"before"` (default) forks before the selected user message, restoring that prompt into the editor
|
|
1093
|
+
- `position`: `"at"` duplicates the active path through the selected entry without restoring editor text
|
|
1094
|
+
- `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
|
|
1095
|
+
|
|
904
1096
|
### ctx.navigateTree(targetId, options?)
|
|
905
1097
|
|
|
906
1098
|
Navigate to a different point in the session tree:
|
|
@@ -920,17 +1112,24 @@ Options:
|
|
|
920
1112
|
- `replaceInstructions`: If true, `customInstructions` replaces the default prompt instead of being appended
|
|
921
1113
|
- `label`: Label to attach to the branch summary entry (or target entry if not summarizing)
|
|
922
1114
|
|
|
923
|
-
### ctx.switchSession(sessionPath)
|
|
1115
|
+
### ctx.switchSession(sessionPath, options?)
|
|
924
1116
|
|
|
925
1117
|
Switch to a different session file:
|
|
926
1118
|
|
|
927
1119
|
```typescript
|
|
928
|
-
const result = await ctx.switchSession("/path/to/session.jsonl"
|
|
1120
|
+
const result = await ctx.switchSession("/path/to/session.jsonl", {
|
|
1121
|
+
withSession: async (ctx) => {
|
|
1122
|
+
await ctx.sendUserMessage("Resume work in the replacement session");
|
|
1123
|
+
},
|
|
1124
|
+
});
|
|
929
1125
|
if (result.cancelled) {
|
|
930
1126
|
// An extension cancelled the switch via session_before_switch
|
|
931
1127
|
}
|
|
932
1128
|
```
|
|
933
1129
|
|
|
1130
|
+
Options:
|
|
1131
|
+
- `withSession`: run post-switch work against a fresh replacement-session context. Do not use captured old `pi` / command `ctx`; see [Session replacement lifecycle and footguns](#session-replacement-lifecycle-and-footguns).
|
|
1132
|
+
|
|
934
1133
|
To discover available sessions, use the static `SessionManager.list()` or `SessionManager.listAll()` methods:
|
|
935
1134
|
|
|
936
1135
|
```typescript
|
|
@@ -946,12 +1145,59 @@ pi.registerCommand("switch", {
|
|
|
946
1145
|
sessions.map(s => s.file),
|
|
947
1146
|
);
|
|
948
1147
|
if (choice) {
|
|
949
|
-
await ctx.switchSession(choice
|
|
1148
|
+
await ctx.switchSession(choice, {
|
|
1149
|
+
withSession: async (ctx) => {
|
|
1150
|
+
ctx.ui.notify("Switched session", "info");
|
|
1151
|
+
},
|
|
1152
|
+
});
|
|
950
1153
|
}
|
|
951
1154
|
},
|
|
952
1155
|
});
|
|
953
1156
|
```
|
|
954
1157
|
|
|
1158
|
+
### Session replacement lifecycle and footguns
|
|
1159
|
+
|
|
1160
|
+
`withSession` receives a fresh `ReplacedSessionContext`, which extends `ExtensionCommandContext` with async `sendMessage()` and `sendUserMessage()` helpers bound to the replacement session.
|
|
1161
|
+
|
|
1162
|
+
Lifecycle and footguns:
|
|
1163
|
+
- `withSession` runs only after the old session has emitted `session_shutdown`, the old runtime has been torn down, the replacement session has been rebound, and the new extension instance has already received `session_start`.
|
|
1164
|
+
- The callback still executes in the original closure, not inside the new extension instance. That means your old extension instance may already have run its shutdown cleanup before `withSession` starts.
|
|
1165
|
+
- Captured old `pi` / old command `ctx` session-bound objects are stale after replacement and will throw if used. Use only the `ctx` passed to `withSession` for session-bound work.
|
|
1166
|
+
- Previously extracted raw objects are still your responsibility. For example, if you capture `const sm = ctx.sessionManager` before replacement, `sm` is still the old `SessionManager` object. Do not reuse it after replacement.
|
|
1167
|
+
- Code in `withSession` should assume any state invalidated by your `session_shutdown` handler is already gone. Only capture plain data that survives shutdown cleanly, such as strings, ids, and serialized config.
|
|
1168
|
+
|
|
1169
|
+
Safe pattern:
|
|
1170
|
+
|
|
1171
|
+
```typescript
|
|
1172
|
+
pi.registerCommand("handoff", {
|
|
1173
|
+
handler: async (_args, ctx) => {
|
|
1174
|
+
const kickoff = "Continue from the replacement session";
|
|
1175
|
+
await ctx.newSession({
|
|
1176
|
+
withSession: async (ctx) => {
|
|
1177
|
+
await ctx.sendUserMessage(kickoff);
|
|
1178
|
+
},
|
|
1179
|
+
});
|
|
1180
|
+
},
|
|
1181
|
+
});
|
|
1182
|
+
```
|
|
1183
|
+
|
|
1184
|
+
Unsafe pattern:
|
|
1185
|
+
|
|
1186
|
+
```typescript
|
|
1187
|
+
pi.registerCommand("handoff", {
|
|
1188
|
+
handler: async (_args, ctx) => {
|
|
1189
|
+
const oldSessionManager = ctx.sessionManager;
|
|
1190
|
+
await ctx.newSession({
|
|
1191
|
+
withSession: async (_ctx) => {
|
|
1192
|
+
// stale old objects: do not do this
|
|
1193
|
+
oldSessionManager.getSessionFile();
|
|
1194
|
+
pi.sendUserMessage("wrong");
|
|
1195
|
+
},
|
|
1196
|
+
});
|
|
1197
|
+
},
|
|
1198
|
+
});
|
|
1199
|
+
```
|
|
1200
|
+
|
|
955
1201
|
### ctx.reload()
|
|
956
1202
|
|
|
957
1203
|
Run the same reload flow as `/reload`.
|
|
@@ -982,7 +1228,7 @@ Example tool the LLM can call to trigger reload:
|
|
|
982
1228
|
|
|
983
1229
|
```typescript
|
|
984
1230
|
import type { ExtensionAPI } from "@draht/coding-agent";
|
|
985
|
-
import { Type } from "
|
|
1231
|
+
import { Type } from "typebox";
|
|
986
1232
|
|
|
987
1233
|
export default function (pi: ExtensionAPI) {
|
|
988
1234
|
pi.registerCommand("reload-runtime", {
|
|
@@ -1024,10 +1270,12 @@ Use `pi.setActiveTools()` to enable or disable tools (including dynamically adde
|
|
|
1024
1270
|
|
|
1025
1271
|
Use `promptSnippet` to opt a custom tool into a one-line entry in `Available tools`, and `promptGuidelines` to append tool-specific bullets to the default `Guidelines` section when the tool is active.
|
|
1026
1272
|
|
|
1273
|
+
**Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
|
|
1274
|
+
|
|
1027
1275
|
See [dynamic-tools.ts](../examples/extensions/dynamic-tools.ts) for a full example.
|
|
1028
1276
|
|
|
1029
1277
|
```typescript
|
|
1030
|
-
import { Type } from "
|
|
1278
|
+
import { Type } from "typebox";
|
|
1031
1279
|
import { StringEnum } from "@draht/ai";
|
|
1032
1280
|
|
|
1033
1281
|
pi.registerTool({
|
|
@@ -1035,7 +1283,7 @@ pi.registerTool({
|
|
|
1035
1283
|
label: "My Tool",
|
|
1036
1284
|
description: "What this tool does",
|
|
1037
1285
|
promptSnippet: "Summarize or transform text according to action",
|
|
1038
|
-
promptGuidelines: ["Use
|
|
1286
|
+
promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
|
|
1039
1287
|
parameters: Type.Object({
|
|
1040
1288
|
action: StringEnum(["list", "add"] as const),
|
|
1041
1289
|
text: Type.Optional(Type.String()),
|
|
@@ -1264,7 +1512,7 @@ pi.registerFlag("plan", {
|
|
|
1264
1512
|
});
|
|
1265
1513
|
|
|
1266
1514
|
// Check value
|
|
1267
|
-
if (pi.getFlag("
|
|
1515
|
+
if (pi.getFlag("plan")) {
|
|
1268
1516
|
// Plan mode enabled
|
|
1269
1517
|
}
|
|
1270
1518
|
```
|
|
@@ -1288,7 +1536,8 @@ const all = pi.getAllTools();
|
|
|
1288
1536
|
// [{
|
|
1289
1537
|
// name: "read",
|
|
1290
1538
|
// description: "Read file contents...",
|
|
1291
|
-
// parameters: ...,
|
|
1539
|
+
// parameters: ...,
|
|
1540
|
+
// promptGuidelines: ["Use read to examine files instead of cat or sed."],
|
|
1292
1541
|
// sourceInfo: { path: "<builtin:read>", source: "builtin", scope: "temporary", origin: "top-level" }
|
|
1293
1542
|
// }, ...]
|
|
1294
1543
|
const names = all.map(t => t.name);
|
|
@@ -1297,7 +1546,7 @@ const extensionTools = all.filter((t) => t.sourceInfo.source !== "builtin" && t.
|
|
|
1297
1546
|
pi.setActiveTools(["read", "bash"]); // Switch to read-only
|
|
1298
1547
|
```
|
|
1299
1548
|
|
|
1300
|
-
`pi.getAllTools()` returns `name`, `description`, `parameters`, and `sourceInfo`.
|
|
1549
|
+
`pi.getAllTools()` returns `name`, `description`, `parameters`, `promptGuidelines`, and `sourceInfo`.
|
|
1301
1550
|
|
|
1302
1551
|
Typical `sourceInfo.source` values:
|
|
1303
1552
|
- `builtin` for built-in tools
|
|
@@ -1320,7 +1569,7 @@ if (model) {
|
|
|
1320
1569
|
|
|
1321
1570
|
### pi.getThinkingLevel() / pi.setThinkingLevel(level)
|
|
1322
1571
|
|
|
1323
|
-
Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off").
|
|
1572
|
+
Get or set the thinking level. Level is clamped to model capabilities (non-reasoning models always use "off"). Changes emit `thinking_level_select`.
|
|
1324
1573
|
|
|
1325
1574
|
```typescript
|
|
1326
1575
|
const current = pi.getThinkingLevel(); // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
|
|
@@ -1342,11 +1591,14 @@ Register or override a model provider dynamically. Useful for proxies, custom en
|
|
|
1342
1591
|
|
|
1343
1592
|
Calls made during the extension factory function are queued and applied once the runner initialises. Calls made after that — for example from a command handler following a user setup flow — take effect immediately without requiring a `/reload`.
|
|
1344
1593
|
|
|
1594
|
+
If you need to discover models from a remote endpoint, prefer an async extension factory over deferring the fetch to `session_start`. pi waits for the factory before startup continues, so the registered models are available immediately, including to `pi --list-models`.
|
|
1595
|
+
|
|
1345
1596
|
```typescript
|
|
1346
1597
|
// Register a new provider with custom models
|
|
1347
1598
|
pi.registerProvider("my-proxy", {
|
|
1599
|
+
name: "My Proxy",
|
|
1348
1600
|
baseUrl: "https://proxy.example.com",
|
|
1349
|
-
apiKey: "PROXY_API_KEY", // env var
|
|
1601
|
+
apiKey: "$PROXY_API_KEY", // env var reference
|
|
1350
1602
|
api: "anthropic-messages",
|
|
1351
1603
|
models: [
|
|
1352
1604
|
{
|
|
@@ -1391,12 +1643,13 @@ pi.registerProvider("corporate-ai", {
|
|
|
1391
1643
|
```
|
|
1392
1644
|
|
|
1393
1645
|
**Config options:**
|
|
1646
|
+
- `name` - Display name for the provider in UI such as `/login`.
|
|
1394
1647
|
- `baseUrl` - API endpoint URL. Required when defining models.
|
|
1395
|
-
- `apiKey` - API key
|
|
1648
|
+
- `apiKey` - API key literal, environment interpolation (`$ENV_VAR` or `${ENV_VAR}`), or leading `!command`. Required when defining models (unless `oauth` provided). `$$` escapes `$`, and `$!` escapes a literal `!` without triggering command execution.
|
|
1396
1649
|
- `api` - API type: `"anthropic-messages"`, `"openai-completions"`, `"openai-responses"`, etc.
|
|
1397
1650
|
- `headers` - Custom headers to include in requests.
|
|
1398
1651
|
- `authHeader` - If true, adds `Authorization: Bearer` header automatically.
|
|
1399
|
-
- `models` - Array of model definitions. If provided, replaces all existing models for this provider.
|
|
1652
|
+
- `models` - Array of model definitions. If provided, replaces all existing models for this provider. Model definitions can set `baseUrl` to override the provider endpoint for that model.
|
|
1400
1653
|
- `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
|
|
1401
1654
|
- `streamSimple` - Custom streaming implementation for non-standard APIs.
|
|
1402
1655
|
|
|
@@ -1459,6 +1712,8 @@ Use `promptSnippet` for a short one-line entry in the `Available tools` section
|
|
|
1459
1712
|
|
|
1460
1713
|
Use `promptGuidelines` to add tool-specific bullets to the default system prompt `Guidelines` section. These bullets are included only while the tool is active (for example, after `pi.setActiveTools([...])`).
|
|
1461
1714
|
|
|
1715
|
+
**Important:** `promptGuidelines` bullets are appended flat to the `Guidelines` section with no tool name prefix or grouping. Each guideline must name the tool it refers to — avoid "Use this tool when..." because the LLM cannot tell which tool "this" means. Write "Use my_tool when..." instead.
|
|
1716
|
+
|
|
1462
1717
|
Note: Some models are idiots and include the @ prefix in tool path arguments. Built-in tools strip a leading @ before resolving paths. If your custom tool accepts a path, normalize a leading @ as well.
|
|
1463
1718
|
|
|
1464
1719
|
If your custom tool mutates files, use `withFileMutationQueue()` so it participates in the same per-file queue as built-in `edit` and `write`. This matters because tool calls run in parallel by default. Without the queue, two tools can read the same old file contents, compute different updates, and then whichever write lands last overwrites the other.
|
|
@@ -1494,7 +1749,7 @@ async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
|
|
|
1494
1749
|
### Tool Definition
|
|
1495
1750
|
|
|
1496
1751
|
```typescript
|
|
1497
|
-
import { Type } from "
|
|
1752
|
+
import { Type } from "typebox";
|
|
1498
1753
|
import { StringEnum } from "@draht/ai";
|
|
1499
1754
|
import { Text } from "@draht/tui";
|
|
1500
1755
|
|
|
@@ -1504,7 +1759,7 @@ pi.registerTool({
|
|
|
1504
1759
|
description: "What this tool does (shown to LLM)",
|
|
1505
1760
|
promptSnippet: "List or add items in the project todo list",
|
|
1506
1761
|
promptGuidelines: [
|
|
1507
|
-
"Use
|
|
1762
|
+
"Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
|
|
1508
1763
|
],
|
|
1509
1764
|
parameters: Type.Object({
|
|
1510
1765
|
action: StringEnum(["list", "add"] as const), // Use StringEnum for Google compatibility
|
|
@@ -1538,6 +1793,9 @@ pi.registerTool({
|
|
|
1538
1793
|
return {
|
|
1539
1794
|
content: [{ type: "text", text: "Done" }], // Sent to LLM
|
|
1540
1795
|
details: { data: result }, // For rendering & state
|
|
1796
|
+
// Optional: stop after this tool batch when every finalized tool result
|
|
1797
|
+
// in the batch also returns terminate: true.
|
|
1798
|
+
terminate: true,
|
|
1541
1799
|
};
|
|
1542
1800
|
},
|
|
1543
1801
|
|
|
@@ -1549,6 +1807,8 @@ pi.registerTool({
|
|
|
1549
1807
|
|
|
1550
1808
|
**Signaling errors:** To mark a tool execution as failed (sets `isError: true` on the result and reports it to the LLM), throw an error from `execute`. Returning a value never sets the error flag regardless of what properties you include in the return object.
|
|
1551
1809
|
|
|
1810
|
+
**Early termination:** Return `terminate: true` from `execute()` to hint that the automatic follow-up LLM call should be skipped after the current tool batch. This only takes effect when every finalized tool result in that batch is terminating. See [examples/extensions/structured-output.ts](../examples/extensions/structured-output.ts) for a minimal example where the agent ends on a final structured-output tool call.
|
|
1811
|
+
|
|
1552
1812
|
```typescript
|
|
1553
1813
|
// Correct: throw to signal an error
|
|
1554
1814
|
async execute(toolCallId, params) {
|
|
@@ -1617,10 +1877,10 @@ Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`,
|
|
|
1617
1877
|
pi -e ./tool-override.ts
|
|
1618
1878
|
```
|
|
1619
1879
|
|
|
1620
|
-
Alternatively, use `--no-tools` to start without any built-in tools:
|
|
1880
|
+
Alternatively, use `--no-builtin-tools` to start without any built-in tools while keeping extension tools enabled:
|
|
1621
1881
|
```bash
|
|
1622
1882
|
# No built-in tools, only extension tools
|
|
1623
|
-
pi --no-tools -e ./my-extension.ts
|
|
1883
|
+
pi --no-builtin-tools -e ./my-extension.ts
|
|
1624
1884
|
```
|
|
1625
1885
|
|
|
1626
1886
|
See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.ts) for a complete example that overrides `read` with logging and access control.
|
|
@@ -1632,13 +1892,13 @@ See [examples/extensions/tool-override.ts](../examples/extensions/tool-override.
|
|
|
1632
1892
|
**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.
|
|
1633
1893
|
|
|
1634
1894
|
Built-in tool implementations:
|
|
1635
|
-
- [read.ts](https://github.com/
|
|
1636
|
-
- [bash.ts](https://github.com/
|
|
1637
|
-
- [edit.ts](https://github.com/
|
|
1638
|
-
- [write.ts](https://github.com/
|
|
1639
|
-
- [grep.ts](https://github.com/
|
|
1640
|
-
- [find.ts](https://github.com/
|
|
1641
|
-
- [ls.ts](https://github.com/
|
|
1895
|
+
- [read.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/read.ts) - `ReadToolDetails`
|
|
1896
|
+
- [bash.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/bash.ts) - `BashToolDetails`
|
|
1897
|
+
- [edit.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/edit.ts)
|
|
1898
|
+
- [write.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/write.ts)
|
|
1899
|
+
- [grep.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/grep.ts) - `GrepToolDetails`
|
|
1900
|
+
- [find.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/find.ts) - `FindToolDetails`
|
|
1901
|
+
- [ls.ts](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/tools/ls.ts) - `LsToolDetails`
|
|
1642
1902
|
|
|
1643
1903
|
### Remote Execution
|
|
1644
1904
|
|
|
@@ -1761,9 +2021,27 @@ export default function (pi: ExtensionAPI) {
|
|
|
1761
2021
|
|
|
1762
2022
|
### Custom Rendering
|
|
1763
2023
|
|
|
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/
|
|
2024
|
+
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/earendil-works/pi-mono/blob/main/packages/coding-agent/src/modes/interactive/components/tool-execution.ts) for how tool rows are composed.
|
|
2025
|
+
|
|
2026
|
+
By default, 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.
|
|
1765
2027
|
|
|
1766
|
-
|
|
2028
|
+
Set `renderShell: "self"` when the tool should render its own shell instead of using the default `Box`. This is useful for tools that need complete control over framing or background behavior, for example large previews that must stay visually stable after the tool settles.
|
|
2029
|
+
|
|
2030
|
+
```typescript
|
|
2031
|
+
pi.registerTool({
|
|
2032
|
+
name: "my_tool",
|
|
2033
|
+
label: "My Tool",
|
|
2034
|
+
description: "Custom shell example",
|
|
2035
|
+
parameters: Type.Object({}),
|
|
2036
|
+
renderShell: "self",
|
|
2037
|
+
async execute() {
|
|
2038
|
+
return { content: [{ type: "text", text: "ok" }], details: undefined };
|
|
2039
|
+
},
|
|
2040
|
+
renderCall(args, theme, context) {
|
|
2041
|
+
return new Text(theme.fg("accent", "my custom shell"), 0, 0);
|
|
2042
|
+
},
|
|
2043
|
+
});
|
|
2044
|
+
```
|
|
1767
2045
|
|
|
1768
2046
|
`renderCall` and `renderResult` each receive a `context` object with:
|
|
1769
2047
|
- `args` - the current tool call arguments
|
|
@@ -1850,7 +2128,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
|
|
|
1850
2128
|
|
|
1851
2129
|
#### Best Practices
|
|
1852
2130
|
|
|
1853
|
-
- Use `Text` with padding `(0, 0)`. The Box handles padding.
|
|
2131
|
+
- Use `Text` with padding `(0, 0)`. The default Box handles padding.
|
|
1854
2132
|
- Use `\n` for multi-line content.
|
|
1855
2133
|
- Handle `isPartial` for streaming progress.
|
|
1856
2134
|
- Support `expanded` for detail on demand.
|
|
@@ -1858,6 +2136,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
|
|
|
1858
2136
|
- Read `context.args` in `renderResult` instead of copying args into `context.state`.
|
|
1859
2137
|
- Use `context.state` only for data that must be shared across call and result slots.
|
|
1860
2138
|
- Reuse `context.lastComponent` when the same component instance can be updated in place.
|
|
2139
|
+
- Use `renderShell: "self"` only when the default boxed shell gets in the way. In self-shell mode the tool is responsible for its own framing, padding, and background.
|
|
1861
2140
|
|
|
1862
2141
|
#### Fallback
|
|
1863
2142
|
|
|
@@ -1874,8 +2153,9 @@ Extensions can interact with users via `ctx.ui` methods and customize how messag
|
|
|
1874
2153
|
- Async operations with cancel (BorderedLoader)
|
|
1875
2154
|
- Settings toggles (SettingsList)
|
|
1876
2155
|
- Status indicators (setStatus)
|
|
1877
|
-
- Working message during streaming (setWorkingMessage)
|
|
2156
|
+
- Working message, visibility, and indicator during streaming (`setWorkingMessage`, `setWorkingVisible`, `setWorkingIndicator`)
|
|
1878
2157
|
- Widgets above/below editor (setWidget)
|
|
2158
|
+
- Autocomplete providers layered on top of built-in slash/path completion (addAutocompleteProvider)
|
|
1879
2159
|
- Custom footers (setFooter)
|
|
1880
2160
|
|
|
1881
2161
|
### Dialogs
|
|
@@ -1955,9 +2235,25 @@ See [examples/extensions/timed-confirm.ts](../examples/extensions/timed-confirm.
|
|
|
1955
2235
|
ctx.ui.setStatus("my-ext", "Processing...");
|
|
1956
2236
|
ctx.ui.setStatus("my-ext", undefined); // Clear
|
|
1957
2237
|
|
|
1958
|
-
// Working
|
|
2238
|
+
// Working loader (shown during streaming)
|
|
1959
2239
|
ctx.ui.setWorkingMessage("Thinking deeply...");
|
|
1960
2240
|
ctx.ui.setWorkingMessage(); // Restore default
|
|
2241
|
+
ctx.ui.setWorkingVisible(false); // Hide the built-in working loader row entirely
|
|
2242
|
+
ctx.ui.setWorkingVisible(true); // Show the built-in working loader row
|
|
2243
|
+
|
|
2244
|
+
// Working indicator (shown during streaming)
|
|
2245
|
+
ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] }); // Static dot
|
|
2246
|
+
ctx.ui.setWorkingIndicator({
|
|
2247
|
+
frames: [
|
|
2248
|
+
ctx.ui.theme.fg("dim", "·"),
|
|
2249
|
+
ctx.ui.theme.fg("muted", "•"),
|
|
2250
|
+
ctx.ui.theme.fg("accent", "●"),
|
|
2251
|
+
ctx.ui.theme.fg("muted", "•"),
|
|
2252
|
+
],
|
|
2253
|
+
intervalMs: 120,
|
|
2254
|
+
});
|
|
2255
|
+
ctx.ui.setWorkingIndicator({ frames: [] }); // Hide indicator
|
|
2256
|
+
ctx.ui.setWorkingIndicator(); // Restore default spinner
|
|
1961
2257
|
|
|
1962
2258
|
// Widget above editor (default)
|
|
1963
2259
|
ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
|
|
@@ -1983,6 +2279,29 @@ const current = ctx.ui.getEditorText();
|
|
|
1983
2279
|
// Paste into editor (triggers paste handling, including collapse for large content)
|
|
1984
2280
|
ctx.ui.pasteToEditor("pasted content");
|
|
1985
2281
|
|
|
2282
|
+
// Stack custom autocomplete behavior on top of the built-in provider
|
|
2283
|
+
ctx.ui.addAutocompleteProvider((current) => ({
|
|
2284
|
+
triggerCharacters: ["#"],
|
|
2285
|
+
async getSuggestions(lines, line, col, options) {
|
|
2286
|
+
const beforeCursor = (lines[line] ?? "").slice(0, col);
|
|
2287
|
+
const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
|
|
2288
|
+
if (!match) {
|
|
2289
|
+
return current.getSuggestions(lines, line, col, options);
|
|
2290
|
+
}
|
|
2291
|
+
|
|
2292
|
+
return {
|
|
2293
|
+
prefix: `#${match[1] ?? ""}`,
|
|
2294
|
+
items: [{ value: "#2983", label: "#2983", description: "Extension API for autocomplete" }],
|
|
2295
|
+
};
|
|
2296
|
+
},
|
|
2297
|
+
applyCompletion(lines, line, col, item, prefix) {
|
|
2298
|
+
return current.applyCompletion(lines, line, col, item, prefix);
|
|
2299
|
+
},
|
|
2300
|
+
shouldTriggerFileCompletion(lines, line, col) {
|
|
2301
|
+
return current.shouldTriggerFileCompletion?.(lines, line, col) ?? true;
|
|
2302
|
+
},
|
|
2303
|
+
}));
|
|
2304
|
+
|
|
1986
2305
|
// Tool output expansion
|
|
1987
2306
|
const wasExpanded = ctx.ui.getToolsExpanded();
|
|
1988
2307
|
ctx.ui.setToolsExpanded(true);
|
|
@@ -1990,6 +2309,10 @@ ctx.ui.setToolsExpanded(wasExpanded);
|
|
|
1990
2309
|
|
|
1991
2310
|
// Custom editor (vim mode, emacs mode, etc.)
|
|
1992
2311
|
ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
|
|
2312
|
+
const currentEditor = ctx.ui.getEditorComponent();
|
|
2313
|
+
ctx.ui.setEditorComponent((tui, theme, keybindings) =>
|
|
2314
|
+
new WrappedEditor(tui, theme, keybindings, currentEditor?.(tui, theme, keybindings))
|
|
2315
|
+
);
|
|
1993
2316
|
ctx.ui.setEditorComponent(undefined); // Restore default editor
|
|
1994
2317
|
|
|
1995
2318
|
// Theme management (see themes.md for creating themes)
|
|
@@ -2003,6 +2326,53 @@ ctx.ui.setTheme(lightTheme!); // Or switch by Theme object
|
|
|
2003
2326
|
ctx.ui.theme.fg("accent", "styled text"); // Access current theme
|
|
2004
2327
|
```
|
|
2005
2328
|
|
|
2329
|
+
Custom working-indicator frames are rendered verbatim. If you want colors, add them to the frame strings yourself, for example with `ctx.ui.theme.fg(...)`.
|
|
2330
|
+
|
|
2331
|
+
### Autocomplete Providers
|
|
2332
|
+
|
|
2333
|
+
Use `ctx.ui.addAutocompleteProvider()` to stack custom autocomplete logic on top of the built-in slash-command and path provider. Set `triggerCharacters` for custom natural triggers such as `$`.
|
|
2334
|
+
|
|
2335
|
+
Typical pattern:
|
|
2336
|
+
|
|
2337
|
+
- inspect the text before the cursor
|
|
2338
|
+
- return your own suggestions when your extension-specific syntax matches
|
|
2339
|
+
- otherwise delegate to `current.getSuggestions(...)`
|
|
2340
|
+
- delegate `applyCompletion(...)` unless you need custom insertion behavior
|
|
2341
|
+
|
|
2342
|
+
```typescript
|
|
2343
|
+
pi.on("session_start", (_event, ctx) => {
|
|
2344
|
+
ctx.ui.addAutocompleteProvider((current) => ({
|
|
2345
|
+
triggerCharacters: ["#"],
|
|
2346
|
+
async getSuggestions(lines, cursorLine, cursorCol, options) {
|
|
2347
|
+
const line = lines[cursorLine] ?? "";
|
|
2348
|
+
const beforeCursor = line.slice(0, cursorCol);
|
|
2349
|
+
const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
|
|
2350
|
+
if (!match) {
|
|
2351
|
+
return current.getSuggestions(lines, cursorLine, cursorCol, options);
|
|
2352
|
+
}
|
|
2353
|
+
|
|
2354
|
+
return {
|
|
2355
|
+
prefix: `#${match[1] ?? ""}`,
|
|
2356
|
+
items: [
|
|
2357
|
+
{ value: "#2983", label: "#2983", description: "Extension API for registering custom @ autocomplete providers" },
|
|
2358
|
+
{ value: "#2753", label: "#2753", description: "Reload stale resource settings" },
|
|
2359
|
+
],
|
|
2360
|
+
};
|
|
2361
|
+
},
|
|
2362
|
+
|
|
2363
|
+
applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
|
|
2364
|
+
return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
|
|
2365
|
+
},
|
|
2366
|
+
|
|
2367
|
+
shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
|
|
2368
|
+
return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
|
|
2369
|
+
},
|
|
2370
|
+
}));
|
|
2371
|
+
});
|
|
2372
|
+
```
|
|
2373
|
+
|
|
2374
|
+
See [github-issue-autocomplete.ts](../examples/extensions/github-issue-autocomplete.ts) for a complete example that preloads the latest open GitHub issues with `gh issue list` and filters them locally for fast `#...` completion. It requires GitHub CLI (`gh`) and a GitHub repository checkout.
|
|
2375
|
+
|
|
2006
2376
|
### Custom Components
|
|
2007
2377
|
|
|
2008
2378
|
For complex UI, use `ctx.ui.custom()`. This temporarily replaces the editor with your component until `done()` is called:
|
|
@@ -2046,7 +2416,7 @@ const result = await ctx.ui.custom<string | null>(
|
|
|
2046
2416
|
);
|
|
2047
2417
|
```
|
|
2048
2418
|
|
|
2049
|
-
For advanced positioning (anchors, margins, percentages, responsive visibility), pass `overlayOptions`. Use `onHandle` to control visibility programmatically:
|
|
2419
|
+
For advanced positioning (anchors, margins, percentages, responsive visibility), pass `overlayOptions`. Use `onHandle` to control focus or visibility programmatically:
|
|
2050
2420
|
|
|
2051
2421
|
```typescript
|
|
2052
2422
|
const result = await ctx.ui.custom<string | null>(
|
|
@@ -2054,12 +2424,19 @@ const result = await ctx.ui.custom<string | null>(
|
|
|
2054
2424
|
{
|
|
2055
2425
|
overlay: true,
|
|
2056
2426
|
overlayOptions: { anchor: "top-right", width: "50%", margin: 2 },
|
|
2057
|
-
onHandle: (handle) => {
|
|
2427
|
+
onHandle: (handle) => {
|
|
2428
|
+
handle.focus(); // focus this overlay and bring it to the visual front
|
|
2429
|
+
// handle.unfocus({ target: editorComponent }); // release input to a specific component
|
|
2430
|
+
// handle.setHidden(true/false); // toggle visibility
|
|
2431
|
+
// handle.hide(); // permanently remove
|
|
2432
|
+
}
|
|
2058
2433
|
}
|
|
2059
2434
|
);
|
|
2060
2435
|
```
|
|
2061
2436
|
|
|
2062
|
-
|
|
2437
|
+
A focused visible overlay can reclaim input after temporary non-overlay custom UI closes. If you intentionally want another component to keep input while the overlay stays visible, call `handle.unfocus({ target })`. Passing `{ target: null }` releases the overlay without focusing another component.
|
|
2438
|
+
|
|
2439
|
+
See [tui.md](tui.md) for the full `OverlayOptions` and `OverlayHandle` API and [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for examples.
|
|
2063
2440
|
|
|
2064
2441
|
### Custom Editor
|
|
2065
2442
|
|
|
@@ -2098,8 +2475,18 @@ export default function (pi: ExtensionAPI) {
|
|
|
2098
2475
|
- Extend `CustomEditor` (not base `Editor`) to get app keybindings (escape to abort, ctrl+d, model switching)
|
|
2099
2476
|
- Call `super.handleInput(data)` for keys you don't handle
|
|
2100
2477
|
- Factory receives `theme` and `keybindings` from the app
|
|
2478
|
+
- Use `ctx.ui.getEditorComponent()` before `setEditorComponent()` to wrap the previously configured custom editor
|
|
2101
2479
|
- Pass `undefined` to restore default: `ctx.ui.setEditorComponent(undefined)`
|
|
2102
2480
|
|
|
2481
|
+
To compose with another extension that already replaced the editor, capture the previous factory before setting yours:
|
|
2482
|
+
|
|
2483
|
+
```typescript
|
|
2484
|
+
const previous = ctx.ui.getEditorComponent();
|
|
2485
|
+
ctx.ui.setEditorComponent((tui, theme, keybindings) =>
|
|
2486
|
+
new MyEditor(tui, theme, keybindings, { base: previous?.(tui, theme, keybindings) })
|
|
2487
|
+
);
|
|
2488
|
+
```
|
|
2489
|
+
|
|
2103
2490
|
See [tui.md](tui.md) Pattern 7 for a complete example with mode indicator.
|
|
2104
2491
|
|
|
2105
2492
|
### Message Rendering
|
|
@@ -2174,14 +2561,14 @@ const highlighted = highlightCode(code, lang, theme);
|
|
|
2174
2561
|
|
|
2175
2562
|
## Mode Behavior
|
|
2176
2563
|
|
|
2177
|
-
| Mode |
|
|
2178
|
-
|
|
2179
|
-
| Interactive | Full TUI
|
|
2180
|
-
| RPC (`--mode rpc`) | JSON protocol
|
|
2181
|
-
| JSON (`--mode json`) |
|
|
2182
|
-
| Print (`-p`) |
|
|
2564
|
+
| Mode | `ctx.mode` | `ctx.hasUI` | Notes |
|
|
2565
|
+
|------|------------|-------------|-------|
|
|
2566
|
+
| Interactive | `"tui"` | `true` | Full TUI with terminal rendering |
|
|
2567
|
+
| RPC (`--mode rpc`) | `"rpc"` | `true` | Dialogs and notifications via JSON protocol; `custom()` returns `undefined`. See [rpc.md](rpc.md) |
|
|
2568
|
+
| JSON (`--mode json`) | `"json"` | `false` | Event stream to stdout; UI methods are no-ops |
|
|
2569
|
+
| Print (`-p`) | `"print"` | `false` | Extensions run but can't prompt |
|
|
2183
2570
|
|
|
2184
|
-
|
|
2571
|
+
Use `ctx.mode === "tui"` before TUI-specific features (`custom()`, component factories, terminal input). Use `ctx.hasUI` before dialog and notification methods that work in both TUI and RPC modes.
|
|
2185
2572
|
|
|
2186
2573
|
## Examples Reference
|
|
2187
2574
|
|
|
@@ -2195,6 +2582,7 @@ All examples in [examples/extensions/](../examples/extensions/).
|
|
|
2195
2582
|
| `questionnaire.ts` | Multi-step wizard tool | `registerTool`, `ui.custom` |
|
|
2196
2583
|
| `todo.ts` | Stateful tool with persistence | `registerTool`, `appendEntry`, `renderResult`, session events |
|
|
2197
2584
|
| `dynamic-tools.ts` | Register tools after startup and during commands | `registerTool`, `session_start`, `registerCommand` |
|
|
2585
|
+
| `structured-output.ts` | Final structured-output tool with `terminate: true` | `registerTool`, terminating tool results |
|
|
2198
2586
|
| `truncated-tool.ts` | Output truncation example | `registerTool`, `truncateHead` |
|
|
2199
2587
|
| `tool-override.ts` | Override built-in read tool | `registerTool` (same name as built-in) |
|
|
2200
2588
|
| **Commands** |||
|
|
@@ -2207,22 +2595,28 @@ All examples in [examples/extensions/](../examples/extensions/).
|
|
|
2207
2595
|
| `shutdown-command.ts` | Graceful shutdown command | `registerCommand`, `shutdown()` |
|
|
2208
2596
|
| **Events & Gates** |||
|
|
2209
2597
|
| `permission-gate.ts` | Block dangerous commands | `on("tool_call")`, `ui.confirm` |
|
|
2598
|
+
| `project-trust.ts` | Decide or defer project trust from a user/global or CLI extension | `on("project_trust")`, trust UI, required trust result |
|
|
2210
2599
|
| `protected-paths.ts` | Block writes to specific paths | `on("tool_call")` |
|
|
2211
2600
|
| `confirm-destructive.ts` | Confirm session changes | `on("session_before_switch")`, `on("session_before_fork")` |
|
|
2212
2601
|
| `dirty-repo-guard.ts` | Warn on dirty git repo | `on("session_before_*")`, `exec` |
|
|
2213
2602
|
| `input-transform.ts` | Transform user input | `on("input")` |
|
|
2603
|
+
| `input-transform-streaming.ts` | Streaming-aware input transform | `on("input")`, `streamingBehavior` |
|
|
2214
2604
|
| `model-status.ts` | React to model changes | `on("model_select")`, `setStatus` |
|
|
2215
|
-
| `provider-payload.ts` | Inspect
|
|
2605
|
+
| `provider-payload.ts` | Inspect payloads and provider response headers | `on("before_provider_request")`, `on("after_provider_response")` |
|
|
2216
2606
|
| `system-prompt-header.ts` | Display system prompt info | `on("agent_start")`, `getSystemPrompt` |
|
|
2217
2607
|
| `claude-rules.ts` | Load rules from files | `on("session_start")`, `on("before_agent_start")` |
|
|
2608
|
+
| `prompt-customizer.ts` | Add context-aware tool guidance using `systemPromptOptions` | `on("before_agent_start")`, `BuildSystemPromptOptions` |
|
|
2218
2609
|
| `file-trigger.ts` | File watcher triggers messages | `sendMessage` |
|
|
2219
2610
|
| **Compaction & Sessions** |||
|
|
2220
2611
|
| `custom-compaction.ts` | Custom compaction summary | `on("session_before_compact")` |
|
|
2221
2612
|
| `trigger-compact.ts` | Trigger compaction manually | `compact()` |
|
|
2222
2613
|
| `git-checkpoint.ts` | Git stash on turns | `on("turn_start")`, `on("session_before_fork")`, `exec` |
|
|
2614
|
+
| `git-merge-and-resolve.ts` | Fetch, merge, and resolve conflicts | `on("agent_end")`, `exec`, `sendUserMessage` |
|
|
2223
2615
|
| `auto-commit-on-exit.ts` | Commit on shutdown | `on("session_shutdown")`, `exec` |
|
|
2224
2616
|
| **UI Components** |||
|
|
2225
2617
|
| `status-line.ts` | Footer status indicator | `setStatus`, session events |
|
|
2618
|
+
| `working-indicator.ts` | Customize the streaming working indicator | `setWorkingIndicator`, `registerCommand` |
|
|
2619
|
+
| `github-issue-autocomplete.ts` | Add `#1234` issue completions on top of built-in autocomplete by preloading recent open issues from `gh issue list` | `addAutocompleteProvider`, `on("session_start")`, `exec` |
|
|
2226
2620
|
| `custom-footer.ts` | Replace footer entirely | `registerCommand`, `setFooter` |
|
|
2227
2621
|
| `custom-header.ts` | Replace startup header | `on("session_start")`, `setHeader` |
|
|
2228
2622
|
| `modal-editor.ts` | Vim-style modal editor | `setEditorComponent`, `CustomEditor` |
|
|
@@ -2241,6 +2635,7 @@ All examples in [examples/extensions/](../examples/extensions/).
|
|
|
2241
2635
|
| `ssh.ts` | SSH remote execution | `registerFlag`, `on("user_bash")`, `on("before_agent_start")`, tool operations |
|
|
2242
2636
|
| `interactive-shell.ts` | Persistent shell session | `on("user_bash")` |
|
|
2243
2637
|
| `sandbox/` | Sandboxed tool execution | Tool operations |
|
|
2638
|
+
| `gondolin/` | Route built-in tools and `!` commands into a Gondolin micro-VM | Tool operations, built-in tool overrides, `on("user_bash")` |
|
|
2244
2639
|
| `subagent/` | Spawn sub-agents | `registerTool`, `exec` |
|
|
2245
2640
|
| **Games** |||
|
|
2246
2641
|
| `snake.ts` | Snake game | `registerCommand`, `ui.custom`, keyboard handling |
|
|
@@ -2256,7 +2651,6 @@ All examples in [examples/extensions/](../examples/extensions/).
|
|
|
2256
2651
|
| `session-name.ts` | Name sessions for selector | `setSessionName`, `getSessionName` |
|
|
2257
2652
|
| `bookmark.ts` | Bookmark entries for /tree | `setLabel` |
|
|
2258
2653
|
| **Misc** |||
|
|
2259
|
-
| `antigravity-image-gen.ts` | Image generation tool | `registerTool`, Google Antigravity |
|
|
2260
2654
|
| `inline-bash.ts` | Inline bash in tool calls | `on("tool_call")` |
|
|
2261
2655
|
| `bash-spawn-hook.ts` | Adjust bash command, cwd, and env before execution | `createBashTool`, `spawnHook` |
|
|
2262
2656
|
| `with-deps/` | Extension with npm dependencies | Package structure with `package.json` |
|