@draht/coding-agent 2026.5.12 → 2026.7.7-1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +47 -0
- package/README.md +1 -4
- 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/register-bedrock.d.ts.map +1 -1
- package/dist/bun/register-bedrock.js +1 -1
- package/dist/bun/register-bedrock.js.map +1 -1
- package/dist/bun/restore-sandbox-env.d.ts +17 -0
- package/dist/bun/restore-sandbox-env.d.ts.map +1 -0
- package/dist/bun/restore-sandbox-env.js +36 -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 +91 -38
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/config-selector.d.ts +5 -3
- 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 +13 -26
- 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 +3 -2
- package/dist/cli/session-picker.d.ts.map +1 -1
- package/dist/cli/session-picker.js +5 -4
- package/dist/cli/session-picker.js.map +1 -1
- package/dist/cli/startup-ui.d.ts +20 -0
- package/dist/cli/startup-ui.d.ts.map +1 -0
- package/dist/cli/startup-ui.js +184 -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 +27 -13
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +284 -63
- 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 +55 -33
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +560 -492
- 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 +21 -13
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +48 -28
- 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 +9 -5
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +10 -4
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +8 -7
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +56 -47
- 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/export-html/vendor/marked.min.js +75 -3
- 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 +5 -6
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +98 -43
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +31 -12
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +248 -33
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +191 -36
- 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 +22 -0
- package/dist/core/http-dispatcher.d.ts.map +1 -0
- package/dist/core/http-dispatcher.js +91 -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 +67 -2
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +59 -7
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-registry.d.ts +24 -5
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +188 -51
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts +12 -1
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +84 -39
- 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 +22 -4
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +455 -157
- 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 +59 -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 +13 -6
- package/dist/core/resolve-config-value.d.ts.map +1 -1
- package/dist/core/resolve-config-value.js +143 -22
- package/dist/core/resolve-config-value.js.map +1 -1
- package/dist/core/resource-loader.d.ts +36 -15
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +178 -79
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sdk.d.ts +34 -18
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +47 -16
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-manager.d.ts +32 -14
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +366 -209
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +62 -6
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +230 -40
- 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 +20 -16
- 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/timings.d.ts +4 -2
- package/dist/core/timings.d.ts.map +1 -1
- package/dist/core/timings.js +24 -14
- package/dist/core/timings.js.map +1 -1
- 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 +187 -178
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit-diff.d.ts +26 -5
- package/dist/core/tools/edit-diff.d.ts.map +1 -1
- package/dist/core/tools/edit-diff.js +110 -23
- 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 +201 -113
- 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 +148 -101
- 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 +103 -52
- 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 +36 -0
- package/dist/core/trust-manager.d.ts.map +1 -0
- package/dist/core/trust-manager.js +202 -0
- package/dist/core/trust-manager.js.map +1 -0
- package/dist/index.d.ts +33 -29
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +12 -9
- 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 +208 -93
- 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 +4 -4
- 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/assets/clankolas.png +0 -0
- package/dist/modes/interactive/components/assistant-message.d.ts +5 -1
- package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/assistant-message.js +37 -15
- 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 +36 -5
- package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/config-selector.js +318 -36
- 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-entry.d.ts +19 -0
- package/dist/modes/interactive/components/custom-entry.d.ts.map +1 -0
- package/dist/modes/interactive/components/custom-entry.js +52 -0
- package/dist/modes/interactive/components/custom-entry.js.map +1 -0
- 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 +3 -1
- package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-editor.js +26 -9
- 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 +4 -3
- package/dist/modes/interactive/components/footer.d.ts.map +1 -1
- package/dist/modes/interactive/components/footer.js +27 -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 +45 -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 +10 -6
- 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 +49 -31
- package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
- package/dist/modes/interactive/components/session-selector.d.ts +2 -2
- package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/session-selector.js +33 -14
- package/dist/modes/interactive/components/session-selector.js.map +1 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +17 -0
- package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +301 -20
- 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/status-indicator.d.ts +28 -0
- package/dist/modes/interactive/components/status-indicator.d.ts.map +1 -0
- package/dist/modes/interactive/components/status-indicator.js +60 -0
- package/dist/modes/interactive/components/status-indicator.js.map +1 -0
- 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 +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +137 -13
- 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 +6 -1
- package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/user-message.js +22 -8
- package/dist/modes/interactive/components/user-message.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +76 -19
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +1294 -494
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/interactive/model-search.d.ts +12 -0
- package/dist/modes/interactive/model-search.d.ts.map +1 -0
- package/dist/modes/interactive/model-search.js +15 -0
- package/dist/modes/interactive/model-search.js.map +1 -0
- package/dist/modes/interactive/theme/dark.json +5 -4
- package/dist/modes/interactive/theme/light.json +5 -4
- package/dist/modes/interactive/theme/theme-controller.d.ts +29 -0
- package/dist/modes/interactive/theme/theme-controller.d.ts.map +1 -0
- package/dist/modes/interactive/theme/theme-controller.js +102 -0
- package/dist/modes/interactive/theme/theme-controller.js.map +1 -0
- package/dist/modes/interactive/theme/theme-schema.json +2 -1
- package/dist/modes/interactive/theme/theme.d.ts +41 -3
- package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
- package/dist/modes/interactive/theme/theme.js +183 -106
- 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 +30 -5
- package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-client.js +87 -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 +113 -31
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +42 -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 +504 -25
- package/dist/package-manager-cli.js.map +1 -1
- package/dist/prompts/agents/build.md +38 -0
- package/dist/prompts/agents/plan.md +36 -0
- package/dist/prompts/agents/verify.md +36 -4
- package/dist/prompts/commands/brainstorm.md +162 -0
- package/dist/prompts/commands/discuss-phase.md +1 -1
- package/dist/prompts/commands/execute-phase.md +4 -1
- package/dist/prompts/commands/fix.md +12 -0
- package/dist/prompts/commands/init-project.md +1 -0
- package/dist/prompts/commands/map-codebase.md +15 -1
- package/dist/prompts/commands/new-project.md +1 -0
- package/dist/prompts/commands/next-milestone.md +2 -0
- package/dist/prompts/commands/orchestrate.md +4 -4
- package/dist/prompts/commands/plan-phase.md +5 -0
- package/dist/prompts/commands/quick.md +4 -0
- package/dist/prompts/commands/review.md +4 -1
- package/dist/prompts/commands/verify-work.md +10 -8
- package/dist/rpc-entry.d.ts +3 -0
- package/dist/rpc-entry.d.ts.map +1 -0
- package/dist/rpc-entry.js +10 -0
- package/dist/rpc-entry.js.map +1 -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 +12 -5
- package/dist/utils/child-process.d.ts.map +1 -1
- package/dist/utils/child-process.js +33 -5
- 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 +1 -0
- package/dist/utils/image-convert.d.ts.map +1 -1
- package/dist/utils/image-convert.js +21 -15
- package/dist/utils/image-convert.js.map +1 -1
- package/dist/utils/image-process.d.ts +18 -0
- package/dist/utils/image-process.d.ts.map +1 -0
- package/dist/utils/image-process.js +83 -0
- package/dist/utils/image-process.js.map +1 -0
- 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 +100 -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 +11 -6
- package/dist/utils/shell.d.ts.map +1 -1
- package/dist/utils/shell.js +42 -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 +59 -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 +520 -79
- package/docs/index.md +82 -0
- package/docs/json.md +4 -4
- package/docs/keybindings.md +24 -2
- package/docs/models.md +119 -17
- package/docs/packages.md +19 -11
- package/docs/prompt-templates.md +30 -2
- package/docs/providers.md +85 -23
- package/docs/quickstart.md +165 -0
- package/docs/rpc.md +99 -10
- package/docs/sdk.md +118 -50
- package/docs/security.md +55 -0
- package/docs/{session.md → session-format.md} +29 -19
- package/docs/sessions.md +145 -0
- package/docs/settings.md +71 -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/README.md +1 -0
- package/examples/extensions/border-status-editor.ts +145 -0
- package/examples/extensions/built-in-tool-renderer.ts +3 -0
- package/examples/extensions/custom-compaction.ts +2 -1
- package/examples/extensions/custom-header.ts +1 -1
- package/examples/extensions/custom-provider-anthropic/index.ts +2 -2
- 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 +63 -8
- package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
- package/examples/extensions/custom-provider-gitlab-duo/test.ts +2 -2
- 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/entry-renderer.ts +41 -0
- 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 +52 -14
- 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/index.ts +87 -37
- package/examples/extensions/plan-mode/utils.ts +1 -1
- package/examples/extensions/preset.ts +46 -7
- package/examples/extensions/project-trust.ts +64 -0
- package/examples/extensions/prompt-customizer.ts +97 -0
- package/examples/extensions/provider-payload.ts +8 -4
- package/examples/extensions/qna.ts +3 -3
- package/examples/extensions/question.ts +34 -20
- package/examples/extensions/questionnaire.ts +43 -30
- package/examples/extensions/reload-runtime.ts +1 -1
- package/examples/extensions/sandbox/index.ts +6 -6
- 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/agents.ts +2 -2
- package/examples/extensions/subagent/index.ts +58 -29
- package/examples/extensions/summarize.ts +3 -2
- 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 +13 -9
- 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 +15 -19
- package/package.json +22 -16
- package/prompts/agents/build.md +38 -0
- package/prompts/agents/plan.md +36 -0
- package/prompts/agents/verify.md +36 -4
- package/prompts/commands/brainstorm.md +162 -0
- package/prompts/commands/discuss-phase.md +1 -1
- package/prompts/commands/execute-phase.md +4 -1
- package/prompts/commands/fix.md +12 -0
- package/prompts/commands/init-project.md +1 -0
- package/prompts/commands/map-codebase.md +15 -1
- package/prompts/commands/new-project.md +1 -0
- package/prompts/commands/next-milestone.md +2 -0
- package/prompts/commands/orchestrate.md +4 -4
- package/prompts/commands/plan-phase.md +5 -0
- package/prompts/commands/quick.md +4 -0
- package/prompts/commands/review.md +4 -1
- package/prompts/commands/verify-work.md +10 -8
package/docs/sdk.md
CHANGED
|
@@ -54,7 +54,7 @@ The main factory function for a single `AgentSession`.
|
|
|
54
54
|
`createAgentSession()` uses a `ResourceLoader` to supply extensions, skills, prompt templates, themes, and context files. If you do not provide one, it uses `DefaultResourceLoader` with standard discovery.
|
|
55
55
|
|
|
56
56
|
```typescript
|
|
57
|
-
import { createAgentSession } from "@draht/coding-agent";
|
|
57
|
+
import { createAgentSession, SessionManager } from "@draht/coding-agent";
|
|
58
58
|
|
|
59
59
|
// Minimal: defaults with DefaultResourceLoader
|
|
60
60
|
const { session } = await createAgentSession();
|
|
@@ -62,7 +62,7 @@ const { session } = await createAgentSession();
|
|
|
62
62
|
// Custom: override specific options
|
|
63
63
|
const { session } = await createAgentSession({
|
|
64
64
|
model: myModel,
|
|
65
|
-
tools: [
|
|
65
|
+
tools: ["read", "bash"],
|
|
66
66
|
sessionManager: SessionManager.inMemory(),
|
|
67
67
|
});
|
|
68
68
|
```
|
|
@@ -159,6 +159,7 @@ const runtime = await createAgentSessionRuntime(createRuntime, {
|
|
|
159
159
|
- `newSession()`
|
|
160
160
|
- `switchSession()`
|
|
161
161
|
- `fork()`
|
|
162
|
+
- clone flows via `fork(entryId, { position: "at" })`
|
|
162
163
|
- `importFromJsonl()`
|
|
163
164
|
|
|
164
165
|
Important behavior:
|
|
@@ -182,6 +183,25 @@ unsubscribe = session.subscribe(() => {});
|
|
|
182
183
|
|
|
183
184
|
### Prompting and Message Queueing
|
|
184
185
|
|
|
186
|
+
`PromptOptions` controls prompt expansion, queueing behavior while streaming, and prompt preflight notifications:
|
|
187
|
+
|
|
188
|
+
```typescript
|
|
189
|
+
interface PromptOptions {
|
|
190
|
+
expandPromptTemplates?: boolean;
|
|
191
|
+
images?: ImageContent[];
|
|
192
|
+
streamingBehavior?: "steer" | "followUp";
|
|
193
|
+
source?: InputSource;
|
|
194
|
+
preflightResult?: (success: boolean) => void;
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`preflightResult` is called once per `prompt()` invocation:
|
|
199
|
+
|
|
200
|
+
- `true` when the prompt was accepted, queued, or handled immediately
|
|
201
|
+
- `false` when prompt preflight rejected before acceptance
|
|
202
|
+
|
|
203
|
+
It fires before `prompt()` resolves. `prompt()` still resolves only after the full accepted run finishes, including retries. Failures after acceptance are reported through the normal event and message stream, not through `preflightResult(false)`.
|
|
204
|
+
|
|
185
205
|
The `prompt()` method handles prompt templates, extension commands, and message sending:
|
|
186
206
|
|
|
187
207
|
```typescript
|
|
@@ -200,8 +220,10 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo
|
|
|
200
220
|
|
|
201
221
|
**Behavior:**
|
|
202
222
|
- **Extension commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `pi.sendMessage()`.
|
|
203
|
-
- **File-based prompt templates** (from `.md` files): Expanded to their content before sending
|
|
223
|
+
- **File-based prompt templates** (from `.md` files): Expanded to their content before sending or queueing.
|
|
204
224
|
- **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
|
|
225
|
+
- **`preflightResult(true)`**: Means the prompt was accepted, queued, or handled immediately.
|
|
226
|
+
- **`preflightResult(false)`**: Means preflight rejected before acceptance.
|
|
205
227
|
|
|
206
228
|
For explicit queueing during streaming:
|
|
207
229
|
|
|
@@ -383,6 +405,32 @@ If no model is provided:
|
|
|
383
405
|
2. Uses default from settings
|
|
384
406
|
3. Falls back to first available model
|
|
385
407
|
|
|
408
|
+
To match CLI model parsing, use the exported resolver helpers:
|
|
409
|
+
|
|
410
|
+
```typescript
|
|
411
|
+
import {
|
|
412
|
+
resolveCliModel,
|
|
413
|
+
resolveModelScopeWithDiagnostics,
|
|
414
|
+
} from "@draht/coding-agent";
|
|
415
|
+
|
|
416
|
+
const cliModel = resolveCliModel({
|
|
417
|
+
cliModel: "anthropic/claude-opus-4-5:high",
|
|
418
|
+
modelRegistry,
|
|
419
|
+
});
|
|
420
|
+
if (cliModel.error) throw new Error(cliModel.error);
|
|
421
|
+
if (cliModel.warning) console.warn(cliModel.warning);
|
|
422
|
+
|
|
423
|
+
const { scopedModels, diagnostics } = await resolveModelScopeWithDiagnostics(
|
|
424
|
+
["anthropic/*:high", "gpt-5"],
|
|
425
|
+
modelRegistry,
|
|
426
|
+
);
|
|
427
|
+
for (const diagnostic of diagnostics) {
|
|
428
|
+
console.warn(diagnostic.message);
|
|
429
|
+
}
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
`resolveCliModel()` uses all registered models so `--api-key` style first-time setup can resolve a model before stored auth exists. `resolveModelScopeWithDiagnostics()` matches `--models` and `enabledModels` semantics while returning warnings instead of printing them.
|
|
433
|
+
|
|
386
434
|
> See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
|
|
387
435
|
|
|
388
436
|
### API Keys and OAuth
|
|
@@ -444,70 +492,64 @@ const { session } = await createAgentSession({ resourceLoader: loader });
|
|
|
444
492
|
|
|
445
493
|
### Tools
|
|
446
494
|
|
|
495
|
+
Specify which built-in tools to enable:
|
|
496
|
+
|
|
497
|
+
- Built-in tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
|
|
498
|
+
- Default built-ins: `read`, `bash`, `edit`, `write`
|
|
499
|
+
- `noTools: "all"` disables all tools
|
|
500
|
+
- `noTools: "builtin"` disables default built-ins while keeping extension and custom tools enabled
|
|
501
|
+
- `excludeTools` disables specific built-in, extension, or custom tool names after any `tools` allowlist is applied
|
|
502
|
+
|
|
503
|
+
The `edit` tool returns `details.diff` for Pi's TUI display and `details.patch` as a standard unified patch for SDK consumers.
|
|
504
|
+
|
|
447
505
|
```typescript
|
|
448
|
-
import {
|
|
449
|
-
codingTools, // read, bash, edit, write (default)
|
|
450
|
-
readOnlyTools, // read, grep, find, ls
|
|
451
|
-
readTool, bashTool, editTool, writeTool,
|
|
452
|
-
grepTool, findTool, lsTool,
|
|
453
|
-
} from "@draht/coding-agent";
|
|
506
|
+
import { createAgentSession } from "@draht/coding-agent";
|
|
454
507
|
|
|
455
|
-
//
|
|
508
|
+
// Read-only mode
|
|
456
509
|
const { session } = await createAgentSession({
|
|
457
|
-
tools:
|
|
510
|
+
tools: ["read", "grep", "find", "ls"],
|
|
458
511
|
});
|
|
459
512
|
|
|
460
513
|
// Pick specific tools
|
|
461
514
|
const { session } = await createAgentSession({
|
|
462
|
-
tools: [
|
|
515
|
+
tools: ["read", "bash", "grep"],
|
|
516
|
+
});
|
|
517
|
+
|
|
518
|
+
// Disable one tool while keeping the rest available
|
|
519
|
+
const { session } = await createAgentSession({
|
|
520
|
+
excludeTools: ["ask_question"],
|
|
463
521
|
});
|
|
464
522
|
```
|
|
465
523
|
|
|
466
524
|
#### Tools with Custom cwd
|
|
467
525
|
|
|
468
|
-
|
|
526
|
+
When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd.
|
|
469
527
|
|
|
470
528
|
```typescript
|
|
471
|
-
import {
|
|
472
|
-
createCodingTools, // Creates [read, bash, edit, write] for specific cwd
|
|
473
|
-
createReadOnlyTools, // Creates [read, grep, find, ls] for specific cwd
|
|
474
|
-
createReadTool,
|
|
475
|
-
createBashTool,
|
|
476
|
-
createEditTool,
|
|
477
|
-
createWriteTool,
|
|
478
|
-
createGrepTool,
|
|
479
|
-
createFindTool,
|
|
480
|
-
createLsTool,
|
|
481
|
-
} from "@draht/coding-agent";
|
|
529
|
+
import { createAgentSession, SessionManager } from "@draht/coding-agent";
|
|
482
530
|
|
|
483
531
|
const cwd = "/path/to/project";
|
|
484
532
|
|
|
485
|
-
// Use
|
|
533
|
+
// Use default tools for custom cwd
|
|
486
534
|
const { session } = await createAgentSession({
|
|
487
535
|
cwd,
|
|
488
|
-
|
|
536
|
+
sessionManager: SessionManager.inMemory(cwd),
|
|
489
537
|
});
|
|
490
538
|
|
|
491
|
-
// Or pick specific tools
|
|
539
|
+
// Or pick specific tools for custom cwd
|
|
492
540
|
const { session } = await createAgentSession({
|
|
493
541
|
cwd,
|
|
494
|
-
tools: [
|
|
542
|
+
tools: ["read", "bash", "grep"],
|
|
543
|
+
sessionManager: SessionManager.inMemory(cwd),
|
|
495
544
|
});
|
|
496
545
|
```
|
|
497
546
|
|
|
498
|
-
**When you don't need factories:**
|
|
499
|
-
- If you omit `tools`, pi automatically creates them with the correct `cwd`
|
|
500
|
-
- If you use `process.cwd()` as your `cwd`, the pre-built instances work fine
|
|
501
|
-
|
|
502
|
-
**When you must use factories:**
|
|
503
|
-
- When you specify both `cwd` (different from `process.cwd()`) AND `tools`
|
|
504
|
-
|
|
505
547
|
> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
|
|
506
548
|
|
|
507
549
|
### Custom Tools
|
|
508
550
|
|
|
509
551
|
```typescript
|
|
510
|
-
import { Type } from "
|
|
552
|
+
import { Type } from "typebox";
|
|
511
553
|
import { createAgentSession, defineTool } from "@draht/coding-agent";
|
|
512
554
|
|
|
513
555
|
// Inline custom tool
|
|
@@ -534,6 +576,8 @@ Use `defineTool()` for standalone definitions and arrays like `customTools: [myT
|
|
|
534
576
|
|
|
535
577
|
Custom tools passed via `customTools` are combined with extension-registered tools. Extensions loaded by the ResourceLoader can also register tools via `pi.registerTool()`.
|
|
536
578
|
|
|
579
|
+
If you pass `tools`, include each custom or extension tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`.
|
|
580
|
+
|
|
537
581
|
> See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
|
|
538
582
|
|
|
539
583
|
### Extensions
|
|
@@ -560,6 +604,27 @@ const { session } = await createAgentSession({ resourceLoader: loader });
|
|
|
560
604
|
|
|
561
605
|
Extensions can register tools, subscribe to events, add commands, and more. See [extensions.md](extensions.md) for the full API.
|
|
562
606
|
|
|
607
|
+
**Named inline extensions:** By default, inline factories display as `<inline:1>`, `<inline:2>`, etc. in the startup Extensions list. To show a descriptive name instead, wrap the factory:
|
|
608
|
+
|
|
609
|
+
```typescript
|
|
610
|
+
import type { InlineExtension } from "@draht/coding-agent";
|
|
611
|
+
|
|
612
|
+
const myProvider: InlineExtension = {
|
|
613
|
+
name: "my-provider",
|
|
614
|
+
factory: (pi) => {
|
|
615
|
+
pi.on("agent_start", () => {
|
|
616
|
+
console.log("[my-provider] Agent starting");
|
|
617
|
+
});
|
|
618
|
+
},
|
|
619
|
+
};
|
|
620
|
+
|
|
621
|
+
const loader = new DefaultResourceLoader({
|
|
622
|
+
extensionFactories: [myProvider],
|
|
623
|
+
});
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
This displays as `<inline:my-provider>` instead of `<inline:1>`. Bare factory functions are still accepted for backward compatibility.
|
|
627
|
+
|
|
563
628
|
**Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `DefaultResourceLoader` if you need to emit or listen from outside:
|
|
564
629
|
|
|
565
630
|
```typescript
|
|
@@ -697,7 +762,7 @@ const { session: opened } = await createAgentSession({
|
|
|
697
762
|
const currentProjectSessions = await SessionManager.list(process.cwd());
|
|
698
763
|
const allSessions = await SessionManager.listAll(process.cwd());
|
|
699
764
|
|
|
700
|
-
// Session replacement API for /new, /resume, /fork, and import flows.
|
|
765
|
+
// Session replacement API for /new, /resume, /fork, /clone, and import flows.
|
|
701
766
|
const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
|
|
702
767
|
const services = await createAgentSessionServices({ cwd });
|
|
703
768
|
return {
|
|
@@ -723,8 +788,11 @@ await runtime.newSession();
|
|
|
723
788
|
// Replace the active session with another saved session
|
|
724
789
|
await runtime.switchSession("/path/to/session.jsonl");
|
|
725
790
|
|
|
726
|
-
// Replace the active session with a fork from a specific entry
|
|
791
|
+
// Replace the active session with a fork from a specific user entry
|
|
727
792
|
await runtime.fork("entry-id");
|
|
793
|
+
|
|
794
|
+
// Clone the active path through a specific entry
|
|
795
|
+
await runtime.fork("entry-id", { position: "at" });
|
|
728
796
|
```
|
|
729
797
|
|
|
730
798
|
**SessionManager tree API:**
|
|
@@ -754,7 +822,7 @@ sm.branchWithSummary(id, "Summary..."); // Branch with context summary
|
|
|
754
822
|
sm.createBranchedSession(leafId); // Extract path to new file
|
|
755
823
|
```
|
|
756
824
|
|
|
757
|
-
> See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [
|
|
825
|
+
> See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [Session Format](session-format.md)
|
|
758
826
|
|
|
759
827
|
### Settings Management
|
|
760
828
|
|
|
@@ -857,15 +925,13 @@ interface LoadExtensionsResult {
|
|
|
857
925
|
|
|
858
926
|
```typescript
|
|
859
927
|
import { getModel } from "@draht/ai";
|
|
860
|
-
import { Type } from "
|
|
928
|
+
import { Type } from "typebox";
|
|
861
929
|
import {
|
|
862
930
|
AuthStorage,
|
|
863
|
-
bashTool,
|
|
864
931
|
createAgentSession,
|
|
865
932
|
DefaultResourceLoader,
|
|
866
933
|
defineTool,
|
|
867
934
|
ModelRegistry,
|
|
868
|
-
readTool,
|
|
869
935
|
SessionManager,
|
|
870
936
|
SettingsManager,
|
|
871
937
|
} from "@draht/coding-agent";
|
|
@@ -919,7 +985,7 @@ const { session } = await createAgentSession({
|
|
|
919
985
|
authStorage,
|
|
920
986
|
modelRegistry,
|
|
921
987
|
|
|
922
|
-
tools: [
|
|
988
|
+
tools: ["read", "bash", "status"],
|
|
923
989
|
customTools: [statusTool],
|
|
924
990
|
resourceLoader: loader,
|
|
925
991
|
|
|
@@ -1085,6 +1151,8 @@ AgentSessionRuntime
|
|
|
1085
1151
|
// Auth and Models
|
|
1086
1152
|
AuthStorage
|
|
1087
1153
|
ModelRegistry
|
|
1154
|
+
resolveCliModel
|
|
1155
|
+
resolveModelScopeWithDiagnostics
|
|
1088
1156
|
|
|
1089
1157
|
// Resource loading
|
|
1090
1158
|
DefaultResourceLoader
|
|
@@ -1093,18 +1161,17 @@ createEventBus
|
|
|
1093
1161
|
|
|
1094
1162
|
// Helpers
|
|
1095
1163
|
defineTool
|
|
1164
|
+
getAgentDir
|
|
1165
|
+
getPackageDir
|
|
1166
|
+
getReadmePath
|
|
1167
|
+
getDocsPath
|
|
1168
|
+
getExamplesPath
|
|
1096
1169
|
|
|
1097
1170
|
// Session management
|
|
1098
1171
|
SessionManager
|
|
1099
1172
|
SettingsManager
|
|
1100
1173
|
|
|
1101
|
-
//
|
|
1102
|
-
codingTools
|
|
1103
|
-
readOnlyTools
|
|
1104
|
-
readTool, bashTool, editTool, writeTool
|
|
1105
|
-
grepTool, findTool, lsTool
|
|
1106
|
-
|
|
1107
|
-
// Tool factories (for custom cwd)
|
|
1174
|
+
// Tool factories
|
|
1108
1175
|
createCodingTools
|
|
1109
1176
|
createReadOnlyTools
|
|
1110
1177
|
createReadTool, createBashTool, createEditTool, createWriteTool
|
|
@@ -1114,6 +1181,7 @@ createGrepTool, createFindTool, createLsTool
|
|
|
1114
1181
|
type CreateAgentSessionOptions
|
|
1115
1182
|
type CreateAgentSessionResult
|
|
1116
1183
|
type ExtensionFactory
|
|
1184
|
+
type InlineExtension
|
|
1117
1185
|
type ExtensionAPI
|
|
1118
1186
|
type ToolDefinition
|
|
1119
1187
|
type Skill
|
package/docs/security.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
Pi is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
|
|
4
|
+
|
|
5
|
+
## Project Trust
|
|
6
|
+
|
|
7
|
+
Project trust controls whether pi loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
|
|
8
|
+
|
|
9
|
+
Pi considers a project to have trust inputs when it finds any of these from the current working directory:
|
|
10
|
+
|
|
11
|
+
- `.pi/` in the current directory
|
|
12
|
+
- `.agents/skills` in the current directory or an ancestor directory
|
|
13
|
+
|
|
14
|
+
When an interactive session starts in a project with configs in `.pi` or `.agents/skills` and no saved decision for the current directory or a parent directory, pi follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in `~/.pi/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
|
|
15
|
+
|
|
16
|
+
Trusting a project allows pi to load trust-gated project inputs, including:
|
|
17
|
+
|
|
18
|
+
- `.pi/settings.json`
|
|
19
|
+
- `.pi` resources such as extensions, skills, prompt templates, themes, and system prompt files
|
|
20
|
+
- missing project packages configured through project settings
|
|
21
|
+
- project-local extensions and project package-managed extensions
|
|
22
|
+
|
|
23
|
+
Declining trust skips protected resources. `AGENTS.md` and `CLAUDE.md` context files are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, pi only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
|
|
24
|
+
|
|
25
|
+
Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
|
|
26
|
+
|
|
27
|
+
## No Built-in Sandbox
|
|
28
|
+
|
|
29
|
+
Pi does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the pi process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
|
|
30
|
+
|
|
31
|
+
This is intentional. Pi is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
|
|
32
|
+
|
|
33
|
+
Project trust is only an input-loading guard. It prevents a repository from silently changing pi's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by pi.
|
|
34
|
+
|
|
35
|
+
## Running Untrusted or Unmonitored Work
|
|
36
|
+
|
|
37
|
+
For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run pi in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
|
|
38
|
+
|
|
39
|
+
Common patterns are documented in [Containerization](containerization.md):
|
|
40
|
+
|
|
41
|
+
- run the whole `pi` process inside OpenShell or Docker
|
|
42
|
+
- run host pi while routing built-in tool execution into a Gondolin micro-VM
|
|
43
|
+
- mount only the workspace paths the agent should access
|
|
44
|
+
- avoid mounting host `~/.pi/agent` unless the container should access host sessions, settings, and credentials
|
|
45
|
+
- pass the minimum required API keys or use short-lived credentials
|
|
46
|
+
- restrict network access when the task does not need it
|
|
47
|
+
- review diffs and outputs before copying results back to trusted systems
|
|
48
|
+
|
|
49
|
+
If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
|
|
50
|
+
|
|
51
|
+
## Reporting Security Issues
|
|
52
|
+
|
|
53
|
+
To report a security issue, follow the repository [Security Policy](https://github.com/earendil-works/pi-mono/blob/main/SECURITY.md). Do not open a public issue for security-sensitive reports.
|
|
54
|
+
|
|
55
|
+
Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how pi grants access that the local user did not already have.
|
|
@@ -5,14 +5,14 @@ Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with
|
|
|
5
5
|
## File Location
|
|
6
6
|
|
|
7
7
|
```
|
|
8
|
-
~/.
|
|
8
|
+
~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
Where `<path>` is the working directory with `/` replaced by `-`.
|
|
12
12
|
|
|
13
13
|
## Deleting Sessions
|
|
14
14
|
|
|
15
|
-
Sessions can be removed by deleting their `.jsonl` files under `~/.
|
|
15
|
+
Sessions can be removed by deleting their `.jsonl` files under `~/.pi/agent/sessions/`.
|
|
16
16
|
|
|
17
17
|
Pi also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, pi uses the `trash` CLI to avoid permanent deletion.
|
|
18
18
|
|
|
@@ -28,11 +28,11 @@ Existing sessions are automatically migrated to the current version (v3) when lo
|
|
|
28
28
|
|
|
29
29
|
## Source Files
|
|
30
30
|
|
|
31
|
-
Source on GitHub ([
|
|
32
|
-
- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/
|
|
33
|
-
- [`packages/coding-agent/src/core/messages.ts`](https://github.com/
|
|
34
|
-
- [`packages/ai/src/types.ts`](https://github.com/
|
|
35
|
-
- [`packages/agent/src/types.ts`](https://github.com/
|
|
31
|
+
Source on GitHub ([pi-mono](https://github.com/earendil-works/pi-mono)):
|
|
32
|
+
- [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
|
|
33
|
+
- [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
|
|
34
|
+
- [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
|
|
35
|
+
- [`packages/agent/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
|
|
36
36
|
|
|
37
37
|
For TypeScript definitions in your project, inspect `node_modules/@draht/coding-agent/dist/` and `node_modules/@draht/ai/dist/`.
|
|
38
38
|
|
|
@@ -69,7 +69,7 @@ interface ToolCall {
|
|
|
69
69
|
}
|
|
70
70
|
```
|
|
71
71
|
|
|
72
|
-
### Base Message Types (from
|
|
72
|
+
### Base Message Types (from pi-ai)
|
|
73
73
|
|
|
74
74
|
```typescript
|
|
75
75
|
interface UserMessage {
|
|
@@ -116,7 +116,7 @@ interface Usage {
|
|
|
116
116
|
}
|
|
117
117
|
```
|
|
118
118
|
|
|
119
|
-
### Extended Message Types (from
|
|
119
|
+
### Extended Message Types (from pi-coding-agent)
|
|
120
120
|
|
|
121
121
|
```typescript
|
|
122
122
|
interface BashExecutionMessage {
|
|
@@ -191,7 +191,7 @@ First line of the file. Metadata only, not part of the tree (no `id`/`parentId`)
|
|
|
191
191
|
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
|
|
192
192
|
```
|
|
193
193
|
|
|
194
|
-
For sessions with a parent (created via `/fork
|
|
194
|
+
For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ parentSession })`):
|
|
195
195
|
|
|
196
196
|
```json
|
|
197
197
|
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
|
|
@@ -255,7 +255,7 @@ Extension state persistence. Does NOT participate in LLM context.
|
|
|
255
255
|
{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
|
|
256
256
|
```
|
|
257
257
|
|
|
258
|
-
Use `customType` to identify your extension's entries on reload.
|
|
258
|
+
Use `customType` to identify your extension's entries on reload. Interactive mode can render custom entries via `pi.registerEntryRenderer(customType, renderer)`, but they still do not participate in LLM context.
|
|
259
259
|
|
|
260
260
|
### CustomMessageEntry
|
|
261
261
|
|
|
@@ -282,7 +282,7 @@ Set `label` to `undefined` to clear a label.
|
|
|
282
282
|
|
|
283
283
|
### SessionInfoEntry
|
|
284
284
|
|
|
285
|
-
Session metadata (e.g., user-defined display name). Set via `/name`
|
|
285
|
+
Session metadata (e.g., user-defined display name). Set via `/name`, `--name` / `-n`, or `pi.setSessionName()` in extensions.
|
|
286
286
|
|
|
287
287
|
```json
|
|
288
288
|
{"type":"session_info","id":"k1l2m3n4","parentId":"j0k1l2m3","timestamp":"2024-12-03T14:35:00.000Z","name":"Refactor auth module"}
|
|
@@ -306,15 +306,24 @@ Entries form a tree:
|
|
|
306
306
|
|
|
307
307
|
## Context Building
|
|
308
308
|
|
|
309
|
-
`
|
|
309
|
+
`buildContextEntries()` walks from the current leaf to the root, producing the active entry list while honoring compaction:
|
|
310
310
|
|
|
311
311
|
1. Collects all entries on the path
|
|
312
|
-
2.
|
|
313
|
-
|
|
314
|
-
-
|
|
315
|
-
- Then
|
|
316
|
-
|
|
317
|
-
|
|
312
|
+
2. If a `CompactionEntry` is on the path:
|
|
313
|
+
- Includes the compaction entry first
|
|
314
|
+
- Then entries from `firstKeptEntryId` to compaction
|
|
315
|
+
- Then entries after compaction
|
|
316
|
+
3. Preserves non-message entries in the selected range so interactive mode can render them
|
|
317
|
+
|
|
318
|
+
`buildSessionContext()` builds on that entry list to produce the message list for the LLM:
|
|
319
|
+
|
|
320
|
+
1. Extracts current model and thinking level settings from the full path
|
|
321
|
+
2. Converts selected entries to messages:
|
|
322
|
+
- `message` -> stored `AgentMessage`
|
|
323
|
+
- `compaction` -> `compactionSummary`
|
|
324
|
+
- `branch_summary` -> `branchSummary`
|
|
325
|
+
- `custom_message` -> `CustomMessage`
|
|
326
|
+
- `custom` -> no context message
|
|
318
327
|
|
|
319
328
|
## Parsing Example
|
|
320
329
|
|
|
@@ -401,6 +410,7 @@ Key methods for working with sessions programmatically.
|
|
|
401
410
|
- `branchWithSummary(entryId, summary, details?, fromHook?)` - Branch with context summary
|
|
402
411
|
|
|
403
412
|
### Instance Methods - Context & Info
|
|
413
|
+
- `buildContextEntries()` - Get active branch entries with compaction applied
|
|
404
414
|
- `buildSessionContext()` - Get messages, thinkingLevel, and model for LLM
|
|
405
415
|
- `getEntries()` - All entries (excluding header)
|
|
406
416
|
- `getHeader()` - Session header metadata
|
package/docs/sessions.md
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Sessions
|
|
2
|
+
|
|
3
|
+
Pi saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
|
|
4
|
+
|
|
5
|
+
## Session Storage
|
|
6
|
+
|
|
7
|
+
Sessions auto-save to `~/.pi/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pi -c # Continue most recent session
|
|
11
|
+
pi -r # Browse and select from past sessions
|
|
12
|
+
pi --no-session # Ephemeral mode; do not save
|
|
13
|
+
pi --name "my task" # Set session display name at startup
|
|
14
|
+
pi --session <path|id> # Use a specific session file or partial session ID
|
|
15
|
+
pi --fork <path|id> # Fork a session file or partial session ID into a new session
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
|
|
19
|
+
|
|
20
|
+
For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
|
|
21
|
+
|
|
22
|
+
## Session Commands
|
|
23
|
+
|
|
24
|
+
| Command | Description |
|
|
25
|
+
|---------|-------------|
|
|
26
|
+
| `/resume` | Browse and select previous sessions |
|
|
27
|
+
| `/new` | Start a new session |
|
|
28
|
+
| `/name <name>` | Set the current session display name |
|
|
29
|
+
| `/session` | Show session info |
|
|
30
|
+
| `/tree` | Navigate the current session tree |
|
|
31
|
+
| `/fork` | Create a new session from a previous user message |
|
|
32
|
+
| `/clone` | Duplicate the current active branch into a new session |
|
|
33
|
+
| `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
|
|
34
|
+
| `/export [file]` | Export session to HTML |
|
|
35
|
+
| `/share` | Upload as private GitHub gist with shareable HTML link |
|
|
36
|
+
|
|
37
|
+
## Resuming and Deleting Sessions
|
|
38
|
+
|
|
39
|
+
`/resume` opens an interactive session picker for the current project. `pi -r` opens the same picker at startup.
|
|
40
|
+
|
|
41
|
+
In the picker you can:
|
|
42
|
+
|
|
43
|
+
- search by typing
|
|
44
|
+
- toggle path display with Ctrl+P
|
|
45
|
+
- toggle sort mode with Ctrl+S
|
|
46
|
+
- filter to named sessions with Ctrl+N
|
|
47
|
+
- rename with Ctrl+R
|
|
48
|
+
- delete with Ctrl+D, then confirm
|
|
49
|
+
|
|
50
|
+
When available, pi uses the `trash` CLI for deletion instead of permanently removing files.
|
|
51
|
+
|
|
52
|
+
## Naming Sessions
|
|
53
|
+
|
|
54
|
+
Use `/name <name>` to set a human-readable session name:
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
/name Refactor auth module
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Set the name at startup with `--name` or `-n`:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pi --name "Refactor auth module"
|
|
64
|
+
pi --name "CI audit" -p "Review this build failure"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Named sessions are easier to find in `/resume` and `pi -r`.
|
|
68
|
+
|
|
69
|
+
## Branching with `/tree`
|
|
70
|
+
|
|
71
|
+
Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
|
|
72
|
+
|
|
73
|
+
<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
|
|
74
|
+
|
|
75
|
+
Example shape:
|
|
76
|
+
|
|
77
|
+
```text
|
|
78
|
+
├─ user: "Hello, can you help..."
|
|
79
|
+
│ └─ assistant: "Of course! I can..."
|
|
80
|
+
│ ├─ user: "Let's try approach A..."
|
|
81
|
+
│ │ └─ assistant: "For approach A..."
|
|
82
|
+
│ │ └─ user: "That worked..." ← active
|
|
83
|
+
│ └─ user: "Actually, approach B..."
|
|
84
|
+
│ └─ assistant: "For approach B..."
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Tree Controls
|
|
88
|
+
|
|
89
|
+
| Key | Action |
|
|
90
|
+
|-----|--------|
|
|
91
|
+
| ↑/↓ | Navigate visible entries |
|
|
92
|
+
| ←/→ | Page up/down |
|
|
93
|
+
| Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
|
|
94
|
+
| Shift+L | Set or clear a label on the selected entry |
|
|
95
|
+
| Shift+T | Toggle label timestamps |
|
|
96
|
+
| Enter | Select entry |
|
|
97
|
+
| Escape/Ctrl+C | Cancel |
|
|
98
|
+
| Ctrl+O | Cycle filter mode |
|
|
99
|
+
|
|
100
|
+
Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with `treeFilterMode` in [Settings](settings.md).
|
|
101
|
+
|
|
102
|
+
### Selection Behavior
|
|
103
|
+
|
|
104
|
+
Selecting a user or custom message:
|
|
105
|
+
|
|
106
|
+
1. Moves the leaf to the selected message's parent.
|
|
107
|
+
2. Places the selected message text in the editor.
|
|
108
|
+
3. Lets you edit and resubmit, creating a new branch.
|
|
109
|
+
|
|
110
|
+
Selecting an assistant, tool, compaction, or other non-user entry:
|
|
111
|
+
|
|
112
|
+
1. Moves the leaf to that entry.
|
|
113
|
+
2. Leaves the editor empty.
|
|
114
|
+
3. Lets you continue from that point.
|
|
115
|
+
|
|
116
|
+
Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
|
|
117
|
+
|
|
118
|
+
## `/tree`, `/fork`, and `/clone`
|
|
119
|
+
|
|
120
|
+
| Feature | `/tree` | `/fork` | `/clone` |
|
|
121
|
+
|---------|---------|---------|----------|
|
|
122
|
+
| Output | Same session file | New session file | New session file |
|
|
123
|
+
| View | Full tree | User-message selector | Current active branch |
|
|
124
|
+
| Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
|
|
125
|
+
| Summary | Optional branch summary | None | None |
|
|
126
|
+
|
|
127
|
+
Use `/tree` when you want to keep alternatives together. Use `/fork` or `/clone` when you want a separate session file.
|
|
128
|
+
|
|
129
|
+
## Branch Summaries
|
|
130
|
+
|
|
131
|
+
When `/tree` switches away from one branch to another, pi can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
|
|
132
|
+
|
|
133
|
+
When prompted, choose one of:
|
|
134
|
+
|
|
135
|
+
1. no summary
|
|
136
|
+
2. summarize with the default prompt
|
|
137
|
+
3. summarize with custom focus instructions
|
|
138
|
+
|
|
139
|
+
See [Compaction](compaction.md) for branch summarization internals and extension hooks.
|
|
140
|
+
|
|
141
|
+
## Session Format
|
|
142
|
+
|
|
143
|
+
Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
|
|
144
|
+
|
|
145
|
+
For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](session-format.md).
|