@draht/coding-agent 2026.7.13-1 → 2026.7.30
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 +87 -0
- package/README.md +1 -0
- package/dist/bun/cli.js +2 -0
- package/dist/bun/cli.js.map +1 -1
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +12 -2
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/config-selector.js +1 -1
- package/dist/cli/config-selector.js.map +1 -1
- package/dist/cli/credential-print.d.ts +23 -0
- package/dist/cli/credential-print.d.ts.map +1 -0
- package/dist/cli/credential-print.js +116 -0
- package/dist/cli/credential-print.js.map +1 -0
- package/dist/cli/list-models.d.ts +2 -2
- package/dist/cli/list-models.d.ts.map +1 -1
- package/dist/cli/list-models.js +3 -3
- package/dist/cli/list-models.js.map +1 -1
- package/dist/cli/startup-ui.js +1 -1
- package/dist/cli/startup-ui.js.map +1 -1
- package/dist/core/agent-session-runtime.d.ts.map +1 -1
- package/dist/core/agent-session-runtime.js +3 -0
- package/dist/core/agent-session-runtime.js.map +1 -1
- package/dist/core/agent-session-services.d.ts +3 -6
- package/dist/core/agent-session-services.d.ts.map +1 -1
- package/dist/core/agent-session-services.js +23 -9
- package/dist/core/agent-session-services.js.map +1 -1
- package/dist/core/agent-session.d.ts +52 -11
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +199 -101
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-storage.d.ts +15 -103
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +46 -259
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/cache-stats.d.ts +2 -2
- package/dist/core/cache-stats.d.ts.map +1 -1
- package/dist/core/cache-stats.js +1 -1
- package/dist/core/cache-stats.js.map +1 -1
- package/dist/core/compaction/branch-summarization.d.ts +8 -2
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +8 -11
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +19 -3
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +71 -26
- package/dist/core/compaction/compaction.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 +6 -17
- package/dist/core/compaction/utils.js.map +1 -1
- package/dist/core/context-windows.d.ts +7 -0
- package/dist/core/context-windows.d.ts.map +1 -0
- package/dist/core/context-windows.js +35 -0
- package/dist/core/context-windows.js.map +1 -0
- package/dist/core/extensions/index.d.ts +1 -1
- package/dist/core/extensions/index.d.ts.map +1 -1
- package/dist/core/extensions/index.js.map +1 -1
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +18 -3
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +6 -1
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +80 -0
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +48 -4
- 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 +22 -3
- package/dist/core/extensions/wrapper.js.map +1 -1
- package/dist/core/footer-data-provider.d.ts +10 -0
- package/dist/core/footer-data-provider.d.ts.map +1 -1
- package/dist/core/footer-data-provider.js +1 -1
- package/dist/core/footer-data-provider.js.map +1 -1
- package/dist/core/keybindings.d.ts +13 -3
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +11 -3
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-config.d.ts +542 -0
- package/dist/core/model-config.d.ts.map +1 -0
- package/dist/core/model-config.js +247 -0
- package/dist/core/model-config.js.map +1 -0
- package/dist/core/model-registry.d.ts +17 -123
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +59 -730
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts +7 -6
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +41 -21
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/model-runtime.d.ts +83 -0
- package/dist/core/model-runtime.d.ts.map +1 -0
- package/dist/core/model-runtime.js +431 -0
- package/dist/core/model-runtime.js.map +1 -0
- package/dist/core/models-store.d.ts +17 -0
- package/dist/core/models-store.d.ts.map +1 -0
- package/dist/core/models-store.js +46 -0
- package/dist/core/models-store.js.map +1 -0
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +31 -12
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/prompt-templates.d.ts +1 -0
- package/dist/core/prompt-templates.d.ts.map +1 -1
- package/dist/core/prompt-templates.js +4 -4
- package/dist/core/prompt-templates.js.map +1 -1
- package/dist/core/provider-composer.d.ts +55 -0
- package/dist/core/provider-composer.d.ts.map +1 -0
- package/dist/core/provider-composer.js +375 -0
- package/dist/core/provider-composer.js.map +1 -0
- package/dist/core/radius.d.ts +2 -0
- package/dist/core/radius.d.ts.map +1 -0
- package/dist/core/radius.js +2 -0
- package/dist/core/radius.js.map +1 -0
- package/dist/core/remote-catalog-provider.d.ts +5 -0
- package/dist/core/remote-catalog-provider.d.ts.map +1 -0
- package/dist/core/remote-catalog-provider.js +115 -0
- package/dist/core/remote-catalog-provider.js.map +1 -0
- package/dist/core/resource-loader.d.ts +15 -0
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +64 -9
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/runtime-credentials.d.ts +15 -0
- package/dist/core/runtime-credentials.d.ts.map +1 -0
- package/dist/core/runtime-credentials.js +35 -0
- package/dist/core/runtime-credentials.js.map +1 -0
- package/dist/core/sdk.d.ts +3 -6
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +22 -21
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-manager.d.ts +14 -6
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +116 -28
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +1 -1
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +2 -12
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/tools/bash.d.ts +2 -0
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +34 -5
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/read.js +1 -1
- package/dist/core/tools/read.js.map +1 -1
- package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
- package/dist/core/tools/tool-definition-wrapper.js +3 -1
- package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
- package/dist/core/usage-totals.d.ts +19 -0
- package/dist/core/usage-totals.d.ts.map +1 -0
- package/dist/core/usage-totals.js +52 -0
- package/dist/core/usage-totals.js.map +1 -0
- package/dist/extensions/index.d.ts +3 -0
- package/dist/extensions/index.d.ts.map +1 -0
- package/dist/extensions/index.js +3 -0
- package/dist/extensions/index.js.map +1 -0
- package/dist/extensions/llama/client.d.ts +61 -0
- package/dist/extensions/llama/client.d.ts.map +1 -0
- package/dist/extensions/llama/client.js +300 -0
- package/dist/extensions/llama/client.js.map +1 -0
- package/dist/extensions/llama/huggingface.d.ts +23 -0
- package/dist/extensions/llama/huggingface.d.ts.map +1 -0
- package/dist/extensions/llama/huggingface.js +139 -0
- package/dist/extensions/llama/huggingface.js.map +1 -0
- package/dist/extensions/llama/index.d.ts +3 -0
- package/dist/extensions/llama/index.d.ts.map +1 -0
- package/dist/extensions/llama/index.js +208 -0
- package/dist/extensions/llama/index.js.map +1 -0
- package/dist/extensions/llama/provider.d.ts +10 -0
- package/dist/extensions/llama/provider.d.ts.map +1 -0
- package/dist/extensions/llama/provider.js +107 -0
- package/dist/extensions/llama/provider.js.map +1 -0
- package/dist/extensions/llama/ui.d.ts +42 -0
- package/dist/extensions/llama/ui.d.ts.map +1 -0
- package/dist/extensions/llama/ui.js +400 -0
- package/dist/extensions/llama/ui.js.map +1 -0
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +63 -16
- package/dist/main.js.map +1 -1
- package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/assistant-message.js +22 -10
- package/dist/modes/interactive/components/assistant-message.js.map +1 -1
- package/dist/modes/interactive/components/custom-editor.js +1 -1
- package/dist/modes/interactive/components/custom-editor.js.map +1 -1
- package/dist/modes/interactive/components/custom-message.d.ts +3 -1
- package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
- package/dist/modes/interactive/components/custom-message.js +9 -2
- package/dist/modes/interactive/components/custom-message.js.map +1 -1
- package/dist/modes/interactive/components/extension-editor.d.ts +1 -2
- package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-editor.js +16 -46
- package/dist/modes/interactive/components/extension-editor.js.map +1 -1
- package/dist/modes/interactive/components/footer.d.ts.map +1 -1
- package/dist/modes/interactive/components/footer.js +24 -23
- package/dist/modes/interactive/components/footer.js.map +1 -1
- package/dist/modes/interactive/components/login-dialog.d.ts +5 -5
- package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
- package/dist/modes/interactive/components/login-dialog.js +17 -8
- package/dist/modes/interactive/components/login-dialog.js.map +1 -1
- package/dist/modes/interactive/components/model-selector.d.ts +11 -4
- package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/model-selector.js +74 -41
- package/dist/modes/interactive/components/model-selector.js.map +1 -1
- package/dist/modes/interactive/components/oauth-selector.d.ts +4 -4
- package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/oauth-selector.js +14 -25
- package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
- package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/scoped-models-selector.js +22 -13
- package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts +5 -0
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +47 -12
- package/dist/modes/interactive/components/tree-selector.js.map +1 -1
- package/dist/modes/interactive/external-editor.d.ts +12 -0
- package/dist/modes/interactive/external-editor.d.ts.map +1 -0
- package/dist/modes/interactive/external-editor.js +37 -0
- package/dist/modes/interactive/external-editor.js.map +1 -0
- package/dist/modes/interactive/interactive-mode.d.ts +10 -7
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +369 -261
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-client.d.ts +4 -0
- package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-client.js +7 -0
- package/dist/modes/rpc/rpc-client.js.map +1 -1
- package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-mode.js +20 -2
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +11 -0
- 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.map +1 -1
- package/dist/package-manager-cli.js +67 -5
- package/dist/package-manager-cli.js.map +1 -1
- package/dist/utils/clipboard-native.d.ts +1 -0
- package/dist/utils/clipboard-native.d.ts.map +1 -1
- package/dist/utils/clipboard-native.js.map +1 -1
- package/dist/utils/clipboard.d.ts +2 -0
- package/dist/utils/clipboard.d.ts.map +1 -1
- package/dist/utils/clipboard.js +32 -8
- package/dist/utils/clipboard.js.map +1 -1
- package/dist/utils/version-check.d.ts.map +1 -1
- package/dist/utils/version-check.js +3 -1
- package/dist/utils/version-check.js.map +1 -1
- package/docs/compaction.md +9 -4
- package/docs/custom-provider.md +50 -16
- package/docs/environment-variables.md +88 -0
- package/docs/extensions.md +228 -15
- package/docs/index.md +2 -0
- package/docs/json.md +5 -1
- package/docs/keybindings.md +2 -0
- package/docs/llama-cpp.md +99 -0
- package/docs/models.md +13 -2
- package/docs/packages.md +1 -0
- package/docs/prompt-templates.md +1 -0
- package/docs/providers.md +36 -2
- package/docs/quickstart.md +1 -1
- package/docs/rpc.md +107 -7
- package/docs/sdk.md +3 -0
- package/docs/session-format.md +19 -3
- package/docs/settings.md +1 -1
- package/docs/tui.md +41 -26
- package/docs/usage.md +4 -14
- package/examples/extensions/custom-compaction.ts +4 -0
- package/examples/extensions/custom-provider-anthropic/index.ts +9 -3
- package/examples/extensions/custom-provider-anthropic/package.json +1 -1
- package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
- package/examples/extensions/custom-provider-qwen-cli/package.json +1 -1
- package/examples/extensions/gondolin/package.json +2 -2
- package/examples/extensions/handoff.ts +9 -1
- package/examples/extensions/kimi-deferred-tools.ts +61 -0
- package/examples/extensions/message-renderer.ts +2 -2
- package/examples/extensions/sandbox/package.json +1 -1
- package/examples/extensions/summarize.ts +3 -0
- package/examples/extensions/with-deps/package.json +1 -1
- package/examples/sdk/02-custom-model.ts +5 -8
- package/examples/sdk/09-api-keys-and-oauth.ts +15 -31
- package/examples/sdk/12-full-control.ts +9 -12
- package/package.json +10 -8
- package/dist/core/provider-display-names.d.ts +0 -2
- package/dist/core/provider-display-names.d.ts.map +0 -1
- package/dist/core/provider-display-names.js +0 -36
- package/dist/core/provider-display-names.js.map +0 -1
package/docs/extensions.md
CHANGED
|
@@ -47,6 +47,7 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
|
|
|
47
47
|
- [ExtensionAPI Methods](#extensionapi-methods)
|
|
48
48
|
- [State Management](#state-management)
|
|
49
49
|
- [Custom Tools](#custom-tools)
|
|
50
|
+
- [Dynamic Tool Loading](#dynamic-tool-loading)
|
|
50
51
|
- [Custom UI](#custom-ui)
|
|
51
52
|
- [Error Handling](#error-handling)
|
|
52
53
|
- [Mode Behavior](#mode-behavior)
|
|
@@ -255,12 +256,14 @@ This pattern makes the fetched models available during normal startup and to `pi
|
|
|
255
256
|
"zod": "^3.0.0",
|
|
256
257
|
"chalk": "^5.0.0"
|
|
257
258
|
},
|
|
258
|
-
"
|
|
259
|
+
"draht": {
|
|
259
260
|
"extensions": ["./src/index.ts"]
|
|
260
261
|
}
|
|
261
262
|
}
|
|
262
263
|
```
|
|
263
264
|
|
|
265
|
+
The manifest key is `draht`. Upstream's `pi` key is still read as a fallback, so extension packages written for pi work unchanged.
|
|
266
|
+
|
|
264
267
|
Run `npm install` in the extension directory, then imports from `node_modules/` work automatically.
|
|
265
268
|
|
|
266
269
|
## Events
|
|
@@ -457,6 +460,7 @@ pi.on("session_before_compact", async (event, ctx) => {
|
|
|
457
460
|
summary: "...",
|
|
458
461
|
firstKeptEntryId: preparation.firstKeptEntryId,
|
|
459
462
|
tokensBefore: preparation.tokensBefore,
|
|
463
|
+
// usage: summaryResponse.usage, // Optional; included in session totals
|
|
460
464
|
}
|
|
461
465
|
};
|
|
462
466
|
});
|
|
@@ -476,7 +480,13 @@ pi.on("session_before_tree", async (event, ctx) => {
|
|
|
476
480
|
const { preparation, signal } = event;
|
|
477
481
|
return { cancel: true };
|
|
478
482
|
// OR provide custom summary:
|
|
479
|
-
return {
|
|
483
|
+
return {
|
|
484
|
+
summary: {
|
|
485
|
+
summary: "...",
|
|
486
|
+
// usage: summaryResponse.usage, // Optional; included in session totals
|
|
487
|
+
details: {},
|
|
488
|
+
},
|
|
489
|
+
};
|
|
480
490
|
});
|
|
481
491
|
|
|
482
492
|
pi.on("session_tree", async (event, ctx) => {
|
|
@@ -782,7 +792,7 @@ In parallel tool mode, `tool_result` and `tool_execution_end` may interleave in
|
|
|
782
792
|
`tool_result` handlers chain like middleware:
|
|
783
793
|
- Handlers run in extension load order
|
|
784
794
|
- Each handler sees the latest result after previous handler changes
|
|
785
|
-
- Handlers can return partial patches (`content`, `details`, or `
|
|
795
|
+
- Handlers can return partial patches (`content`, `details`, `isError`, or `usage`); omitted fields keep their current values
|
|
786
796
|
|
|
787
797
|
Use `ctx.signal` for nested async work inside the handler. This lets Esc cancel model calls, `fetch()`, and other abort-aware operations started by the extension.
|
|
788
798
|
|
|
@@ -791,7 +801,7 @@ import { isBashToolResult } from "@draht/coding-agent";
|
|
|
791
801
|
|
|
792
802
|
pi.on("tool_result", async (event, ctx) => {
|
|
793
803
|
// event.toolName, event.toolCallId, event.input
|
|
794
|
-
// event.content, event.details, event.isError
|
|
804
|
+
// event.content, event.details, event.isError, event.usage
|
|
795
805
|
|
|
796
806
|
if (isBashToolResult(event)) {
|
|
797
807
|
// event.details is typed as BashToolDetails
|
|
@@ -804,7 +814,7 @@ pi.on("tool_result", async (event, ctx) => {
|
|
|
804
814
|
});
|
|
805
815
|
|
|
806
816
|
// Modify result:
|
|
807
|
-
return { content: [...], details: {...}, isError: false };
|
|
817
|
+
return { content: [...], details: {...}, isError: false, usage: nestedModelUsage };
|
|
808
818
|
});
|
|
809
819
|
```
|
|
810
820
|
|
|
@@ -930,9 +940,11 @@ ctx.sessionManager.buildContextEntries() // Active branch entries with compac
|
|
|
930
940
|
ctx.sessionManager.getLeafId() // Current leaf entry ID
|
|
931
941
|
```
|
|
932
942
|
|
|
933
|
-
### ctx.modelRegistry / ctx.model
|
|
943
|
+
### ctx.modelRegistry / ctx.model / ctx.thinkingLevel / ctx.scopedModels
|
|
934
944
|
|
|
935
|
-
Access to models and API
|
|
945
|
+
Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective @draht/ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model, and `ctx.thinkingLevel` is its current effective thinking level.
|
|
946
|
+
|
|
947
|
+
`ctx.scopedModels` is the read-only list of models scoped to the current session — the same set the `/scoped-models` command shows. It is resolved at session start from the `--models` CLI flag and the `enabledModels` setting (matched against the available catalogue with minimatch on `provider/modelId` or a bare `modelId`). It is empty when no scoping is configured, meaning every available model is usable. Each entry is `{ model, thinkingLevel? }`, where `thinkingLevel` is set only when a pattern pinned it (e.g. `anthropic/*:high`). Use it to populate a model picker that mirrors the built-in one instead of enumerating the whole catalogue via `ctx.modelRegistry.getAvailable()`.
|
|
936
948
|
|
|
937
949
|
### ctx.signal
|
|
938
950
|
|
|
@@ -1632,9 +1644,39 @@ Register or override a model provider dynamically. Useful for proxies, custom en
|
|
|
1632
1644
|
|
|
1633
1645
|
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`.
|
|
1634
1646
|
|
|
1635
|
-
|
|
1647
|
+
Dynamic providers can implement `refreshModels`. Pi calls it during model refresh, publishes the returned list synchronously through the provider, and passes the canonical credential/store/network/signal context. The extension decides whether to persist the catalog through `context.store`; live servers such as llama.cpp can ignore it.
|
|
1648
|
+
|
|
1649
|
+
Extensions that need native provider auth, filtering, refresh, or stream behavior can register a complete `Provider` from `@draht/ai`. The provider becomes the composition base and `models.json` overrides still apply above it.
|
|
1636
1650
|
|
|
1637
1651
|
```typescript
|
|
1652
|
+
import { createProvider, openAICompletionsApi } from "@draht/ai";
|
|
1653
|
+
|
|
1654
|
+
const provider = createProvider({
|
|
1655
|
+
id: "local-server",
|
|
1656
|
+
name: "Local Server",
|
|
1657
|
+
baseUrl: "http://localhost:8080/v1",
|
|
1658
|
+
auth: {
|
|
1659
|
+
apiKey: {
|
|
1660
|
+
name: "Local server setup",
|
|
1661
|
+
async login(interaction) {
|
|
1662
|
+
return {
|
|
1663
|
+
type: "api_key",
|
|
1664
|
+
key: await interaction.prompt({ type: "secret", message: "API key" }),
|
|
1665
|
+
};
|
|
1666
|
+
},
|
|
1667
|
+
async resolve({ credential }) {
|
|
1668
|
+
return credential?.key
|
|
1669
|
+
? { auth: { apiKey: credential.key }, source: "stored API key" }
|
|
1670
|
+
: undefined;
|
|
1671
|
+
},
|
|
1672
|
+
},
|
|
1673
|
+
},
|
|
1674
|
+
models: [],
|
|
1675
|
+
api: openAICompletionsApi(),
|
|
1676
|
+
});
|
|
1677
|
+
|
|
1678
|
+
pi.registerProvider(provider);
|
|
1679
|
+
|
|
1638
1680
|
// Register a new provider with custom models
|
|
1639
1681
|
pi.registerProvider("my-proxy", {
|
|
1640
1682
|
name: "My Proxy",
|
|
@@ -1654,6 +1696,26 @@ pi.registerProvider("my-proxy", {
|
|
|
1654
1696
|
]
|
|
1655
1697
|
});
|
|
1656
1698
|
|
|
1699
|
+
// Register a live llama.cpp catalog without persisting discovered models
|
|
1700
|
+
pi.registerProvider("llama.cpp", {
|
|
1701
|
+
baseUrl: "http://localhost:8080/v1",
|
|
1702
|
+
apiKey: "local",
|
|
1703
|
+
api: "openai-completions",
|
|
1704
|
+
async refreshModels({ signal }) {
|
|
1705
|
+
const response = await fetch("http://localhost:8080/v1/models", { signal });
|
|
1706
|
+
const { data } = await response.json();
|
|
1707
|
+
return data.map(({ id }) => ({
|
|
1708
|
+
id,
|
|
1709
|
+
name: id,
|
|
1710
|
+
reasoning: false,
|
|
1711
|
+
input: ["text"],
|
|
1712
|
+
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
1713
|
+
contextWindow: 128000,
|
|
1714
|
+
maxTokens: 16384
|
|
1715
|
+
}));
|
|
1716
|
+
}
|
|
1717
|
+
});
|
|
1718
|
+
|
|
1657
1719
|
// Override baseUrl for an existing provider (keeps all models)
|
|
1658
1720
|
pi.registerProvider("anthropic", {
|
|
1659
1721
|
baseUrl: "https://proxy.example.com"
|
|
@@ -1683,7 +1745,9 @@ pi.registerProvider("corporate-ai", {
|
|
|
1683
1745
|
});
|
|
1684
1746
|
```
|
|
1685
1747
|
|
|
1686
|
-
|
|
1748
|
+
The object form accepts a complete `@draht/ai` `Provider`, including native `auth`, `getModels`, `refreshModels`, `filterModels`, `stream`, and `streamSimple` behavior.
|
|
1749
|
+
|
|
1750
|
+
**Legacy config options:**
|
|
1687
1751
|
- `name` - Display name for the provider in UI such as `/login`.
|
|
1688
1752
|
- `baseUrl` - API endpoint URL. Required when defining models.
|
|
1689
1753
|
- `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.
|
|
@@ -1691,6 +1755,7 @@ pi.registerProvider("corporate-ai", {
|
|
|
1691
1755
|
- `headers` - Custom headers to include in requests.
|
|
1692
1756
|
- `authHeader` - If true, adds `Authorization: Bearer` header automatically.
|
|
1693
1757
|
- `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.
|
|
1758
|
+
- `refreshModels` - Async dynamic discovery callback. Its returned models replace extension-provided models. Use the scoped `context.store` only when results should persist.
|
|
1694
1759
|
- `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
|
|
1695
1760
|
- `streamSimple` - Custom streaming implementation for non-standard APIs.
|
|
1696
1761
|
|
|
@@ -1834,6 +1899,7 @@ pi.registerTool({
|
|
|
1834
1899
|
return {
|
|
1835
1900
|
content: [{ type: "text", text: "Done" }], // Sent to LLM
|
|
1836
1901
|
details: { data: result }, // For rendering & state
|
|
1902
|
+
// usage: nestedModelResponse.usage, // Optional nested LLM usage
|
|
1837
1903
|
// Optional: stop after this tool batch when every finalized tool result
|
|
1838
1904
|
// in the batch also returns terminate: true.
|
|
1839
1905
|
terminate: true,
|
|
@@ -1846,6 +1912,8 @@ pi.registerTool({
|
|
|
1846
1912
|
});
|
|
1847
1913
|
```
|
|
1848
1914
|
|
|
1915
|
+
**Usage accounting:** If a tool makes nested LLM calls, return their combined `Usage` as `usage`. Pi persists it on the tool result and includes it in footer, `/session`, and RPC session totals. `tool_result` handlers can inspect or replace this value.
|
|
1916
|
+
|
|
1849
1917
|
**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.
|
|
1850
1918
|
|
|
1851
1919
|
**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.
|
|
@@ -1988,7 +2056,15 @@ const bashTool = createBashTool(cwd, {
|
|
|
1988
2056
|
});
|
|
1989
2057
|
```
|
|
1990
2058
|
|
|
1991
|
-
|
|
2059
|
+
`createBashTool()` exposes the current session to commands through `DRAHT_SESSION_ID`, `DRAHT_SESSION_FILE`, `DRAHT_PROVIDER`, `DRAHT_MODEL`, and `DRAHT_REASONING_LEVEL`. Injection happens before `spawnHook`, so hooks receive these values in `env` and preserve them when they spread the existing environment as above. Set `exposeSessionEnvironment: false` to disable them:
|
|
2060
|
+
|
|
2061
|
+
```typescript
|
|
2062
|
+
const bashTool = createBashTool(cwd, {
|
|
2063
|
+
exposeSessionEnvironment: false,
|
|
2064
|
+
});
|
|
2065
|
+
```
|
|
2066
|
+
|
|
2067
|
+
See [Bash tool session environment](environment-variables.md#bash-tool-session-environment) for variable semantics. See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
|
|
1992
2068
|
|
|
1993
2069
|
### Output Truncation
|
|
1994
2070
|
|
|
@@ -2185,6 +2261,143 @@ If a slot renderer is not defined or throws:
|
|
|
2185
2261
|
- `renderCall`: Shows the tool name
|
|
2186
2262
|
- `renderResult`: Shows raw text from `content`
|
|
2187
2263
|
|
|
2264
|
+
### Dynamic Tool Loading
|
|
2265
|
+
|
|
2266
|
+
Extensions can register many tools while keeping only a small initial set active. A tool can then add more tools with `pi.setActiveTools()` during execution. Pi detects purely additive changes, records the newly available tool names on that tool result, and applies the updated active set before the next model request.
|
|
2267
|
+
|
|
2268
|
+
This works with every model. Models with native deferred-loading support preserve the stable prompt prefix and load the new definitions at the tool-result position. Other models use the fallback described below.
|
|
2269
|
+
|
|
2270
|
+
The lifecycle is:
|
|
2271
|
+
|
|
2272
|
+
1. Register every tool with `pi.registerTool()` so it appears in `pi.getAllTools()`.
|
|
2273
|
+
2. Keep loader tools, such as `search_tools`, active and leave searchable tools inactive.
|
|
2274
|
+
3. During loader execution, call `pi.setActiveTools([...currentTools, ...matchingTools])`. The change must be additive: do not remove currently active tools in the same call.
|
|
2275
|
+
4. Pi records which tools were added on the loader's tool result.
|
|
2276
|
+
5. Before the next model response, Pi exposes the added definitions using native deferred loading when supported, or the normal active tool list otherwise.
|
|
2277
|
+
|
|
2278
|
+
You do not need to return provider-specific tool references or mark the loader as a special search tool. The active-tool change is the signal. Names passed to `pi.setActiveTools()` must already be registered; unknown names are ignored.
|
|
2279
|
+
|
|
2280
|
+
#### Models with native deferred loading
|
|
2281
|
+
|
|
2282
|
+
- **Anthropic**
|
|
2283
|
+
- **Models:** Sonnet, Opus, Fable version 4.5 or newer (without Haiku)
|
|
2284
|
+
- **Native representation:** Deferred definitions use `defer_loading`; the load point uses `tool_reference` content.
|
|
2285
|
+
- **OpenAI**
|
|
2286
|
+
- **Models:** `gpt-5.4` and newer family
|
|
2287
|
+
- **Native representation:** Pi adds completed client `tool_search_call` and `tool_search_output` items at the load point.
|
|
2288
|
+
|
|
2289
|
+
For a verified custom model or proxy, native handling can be enabled with `compat.supportsToolReferences: true` for `anthropic-messages`, or `compat.supportsToolSearch: true` for `openai-responses` and `openai-codex-responses`. Leave these disabled unless the endpoint and model accept the corresponding native protocol.
|
|
2290
|
+
|
|
2291
|
+
#### Fallback behavior
|
|
2292
|
+
|
|
2293
|
+
For all other models and providers, dynamic activation still works: Pi sends the complete current active tool list normally on the next request. The model can call the newly activated tools, but adding their definitions may invalidate the provider's cached prompt prefix.
|
|
2294
|
+
|
|
2295
|
+
Pi also uses this safe fallback when the active set is not purely additive, such as replacing one group of tools with another. Tool removals therefore work, but they do not use deferred loading.
|
|
2296
|
+
|
|
2297
|
+
For the best cache behavior, keep the loader tool active for the whole session and add tools instead of replacing the active set. Also note that activating a tool with `promptSnippet` or `promptGuidelines` rebuilds the system prompt; that system-prompt change can invalidate the prefix even when the provider supports deferred schemas. Lazily loaded tools should usually rely on their tool `description` and omit active-only prompt metadata.
|
|
2298
|
+
|
|
2299
|
+
#### Search tool example
|
|
2300
|
+
|
|
2301
|
+
The following extension registers two searchable tools, removes them from the initial active set, and keeps only `search_tools` as their loader. The example uses simple keyword matching, but the search implementation could use BM25, embeddings, a remote catalog, or project-specific routing.
|
|
2302
|
+
|
|
2303
|
+
```typescript
|
|
2304
|
+
import type { ExtensionAPI } from "@draht/coding-agent";
|
|
2305
|
+
import { Type } from "typebox";
|
|
2306
|
+
|
|
2307
|
+
const SEARCHABLE_TOOL_NAMES = new Set(["lookup_weather", "search_issues"]);
|
|
2308
|
+
|
|
2309
|
+
export default function (pi: ExtensionAPI) {
|
|
2310
|
+
pi.registerTool({
|
|
2311
|
+
name: "lookup_weather",
|
|
2312
|
+
label: "Lookup Weather",
|
|
2313
|
+
description: "Look up the current weather for a city",
|
|
2314
|
+
parameters: Type.Object({ city: Type.String() }),
|
|
2315
|
+
async execute(_toolCallId, params) {
|
|
2316
|
+
return {
|
|
2317
|
+
content: [{ type: "text", text: `Weather for ${params.city}: sunny` }],
|
|
2318
|
+
details: {},
|
|
2319
|
+
};
|
|
2320
|
+
},
|
|
2321
|
+
});
|
|
2322
|
+
|
|
2323
|
+
pi.registerTool({
|
|
2324
|
+
name: "search_issues",
|
|
2325
|
+
label: "Search Issues",
|
|
2326
|
+
description: "Search project issues by keyword",
|
|
2327
|
+
parameters: Type.Object({ query: Type.String() }),
|
|
2328
|
+
async execute(_toolCallId, params) {
|
|
2329
|
+
return {
|
|
2330
|
+
content: [{ type: "text", text: `No open issues matching ${params.query}` }],
|
|
2331
|
+
details: {},
|
|
2332
|
+
};
|
|
2333
|
+
},
|
|
2334
|
+
});
|
|
2335
|
+
|
|
2336
|
+
pi.registerTool({
|
|
2337
|
+
name: "search_tools",
|
|
2338
|
+
label: "Search Tools",
|
|
2339
|
+
description: "Search for and enable tools relevant to a task",
|
|
2340
|
+
promptSnippet: "Search for additional tools when the active tools cannot perform the task",
|
|
2341
|
+
promptGuidelines: [
|
|
2342
|
+
"Use search_tools when a task requires a capability that is not currently available.",
|
|
2343
|
+
],
|
|
2344
|
+
parameters: Type.Object({
|
|
2345
|
+
query: Type.String({ description: "Capability or task to search for" }),
|
|
2346
|
+
limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
|
|
2347
|
+
}),
|
|
2348
|
+
async execute(_toolCallId, params) {
|
|
2349
|
+
const terms = params.query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
|
|
2350
|
+
const matches = pi.getAllTools()
|
|
2351
|
+
.filter((tool) => SEARCHABLE_TOOL_NAMES.has(tool.name))
|
|
2352
|
+
.map((tool) => ({
|
|
2353
|
+
tool,
|
|
2354
|
+
score: terms.reduce(
|
|
2355
|
+
(score, term) =>
|
|
2356
|
+
score + (`${tool.name} ${tool.description}`.toLowerCase().includes(term) ? 1 : 0),
|
|
2357
|
+
0,
|
|
2358
|
+
),
|
|
2359
|
+
}))
|
|
2360
|
+
.filter((match) => match.score > 0)
|
|
2361
|
+
.sort((a, b) => b.score - a.score)
|
|
2362
|
+
.slice(0, params.limit ?? 3)
|
|
2363
|
+
.map((match) => match.tool.name);
|
|
2364
|
+
|
|
2365
|
+
if (matches.length === 0) {
|
|
2366
|
+
return {
|
|
2367
|
+
content: [{ type: "text", text: `No tools found for: ${params.query}` }],
|
|
2368
|
+
details: { matches: [] },
|
|
2369
|
+
};
|
|
2370
|
+
}
|
|
2371
|
+
|
|
2372
|
+
const active = pi.getActiveTools();
|
|
2373
|
+
const added = matches.filter((name) => !active.includes(name));
|
|
2374
|
+
pi.setActiveTools([...new Set([...active, ...added])]);
|
|
2375
|
+
|
|
2376
|
+
return {
|
|
2377
|
+
content: [{
|
|
2378
|
+
type: "text",
|
|
2379
|
+
text: added.length > 0
|
|
2380
|
+
? `Loaded tools: ${added.join(", ")}`
|
|
2381
|
+
: `Matching tools already active: ${matches.join(", ")}`,
|
|
2382
|
+
}],
|
|
2383
|
+
details: { matches, added },
|
|
2384
|
+
};
|
|
2385
|
+
},
|
|
2386
|
+
});
|
|
2387
|
+
|
|
2388
|
+
pi.on("session_start", () => {
|
|
2389
|
+
// Keep searchable tools registered but initially inactive. Preserve built-ins
|
|
2390
|
+
// and tools owned by other extensions, and keep the loader itself active.
|
|
2391
|
+
const initialTools = pi.getActiveTools().filter(
|
|
2392
|
+
(name) => !SEARCHABLE_TOOL_NAMES.has(name),
|
|
2393
|
+
);
|
|
2394
|
+
pi.setActiveTools([...new Set([...initialTools, "search_tools"])]);
|
|
2395
|
+
});
|
|
2396
|
+
}
|
|
2397
|
+
```
|
|
2398
|
+
|
|
2399
|
+
When `search_tools` adds a match, the model receives that definition on the immediately following request. On a native-capable model the definition is anchored after the search result without changing the initial tool-schema prefix. On other models it appears in the normal tool list on that same following request.
|
|
2400
|
+
|
|
2188
2401
|
## Custom UI
|
|
2189
2402
|
|
|
2190
2403
|
Extensions can interact with users via `ctx.ui` methods and customize how messages/tools render.
|
|
@@ -2505,8 +2718,8 @@ class VimEditor extends CustomEditor {
|
|
|
2505
2718
|
|
|
2506
2719
|
export default function (pi: ExtensionAPI) {
|
|
2507
2720
|
pi.on("session_start", (_event, ctx) => {
|
|
2508
|
-
ctx.ui.setEditorComponent((
|
|
2509
|
-
new VimEditor(theme, keybindings)
|
|
2721
|
+
ctx.ui.setEditorComponent((tui, theme, keybindings) =>
|
|
2722
|
+
new VimEditor(tui, theme, keybindings)
|
|
2510
2723
|
);
|
|
2511
2724
|
});
|
|
2512
2725
|
}
|
|
@@ -2515,7 +2728,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
2515
2728
|
**Key points:**
|
|
2516
2729
|
- Extend `CustomEditor` (not base `Editor`) to get app keybindings (escape to abort, ctrl+d, model switching)
|
|
2517
2730
|
- Call `super.handleInput(data)` for keys you don't handle
|
|
2518
|
-
- Factory receives `theme
|
|
2731
|
+
- Factory receives `tui`, `theme`, and `keybindings` from the app
|
|
2519
2732
|
- Use `ctx.ui.getEditorComponent()` before `setEditorComponent()` to wrap the previously configured custom editor
|
|
2520
2733
|
- Pass `undefined` to restore default: `ctx.ui.setEditorComponent(undefined)`
|
|
2521
2734
|
|
|
@@ -2538,7 +2751,7 @@ Register a custom renderer for messages with your `customType`. Use message rend
|
|
|
2538
2751
|
import { Text } from "@draht/tui";
|
|
2539
2752
|
|
|
2540
2753
|
pi.registerMessageRenderer("my-extension", (message, options, theme) => {
|
|
2541
|
-
const { expanded } = options;
|
|
2754
|
+
const { expanded, outputPad } = options;
|
|
2542
2755
|
let text = theme.fg("accent", `[${message.customType}] `);
|
|
2543
2756
|
text += message.content;
|
|
2544
2757
|
|
|
@@ -2546,7 +2759,7 @@ pi.registerMessageRenderer("my-extension", (message, options, theme) => {
|
|
|
2546
2759
|
text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
|
|
2547
2760
|
}
|
|
2548
2761
|
|
|
2549
|
-
return new Text(text,
|
|
2762
|
+
return new Text(text, outputPad, 0);
|
|
2550
2763
|
});
|
|
2551
2764
|
```
|
|
2552
2765
|
|
package/docs/index.md
CHANGED
|
@@ -41,6 +41,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
|
|
|
41
41
|
- [Quickstart](quickstart.md) - install, authenticate, and run a first session.
|
|
42
42
|
- [Using Pi](usage.md) - interactive mode, slash commands, context files, and CLI reference.
|
|
43
43
|
- [Providers](providers.md) - subscription and API-key setup for built-in providers.
|
|
44
|
+
- [llama.cpp](llama-cpp.md) - run a local router and manage models with `/llama`.
|
|
44
45
|
- [Security](security.md) - project trust, sandbox boundaries, and vulnerability reporting.
|
|
45
46
|
- [Containerization](containerization.md) - sandbox pi with OpenShell, Gondolin, or Docker.
|
|
46
47
|
- [Settings](settings.md) - global and project settings.
|
|
@@ -67,6 +68,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
|
|
|
67
68
|
|
|
68
69
|
## Reference
|
|
69
70
|
|
|
71
|
+
- [Environment variables](environment-variables.md) - draht process configuration and session metadata available to bash tools.
|
|
70
72
|
- [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
|
|
71
73
|
|
|
72
74
|
## Platform setup
|
package/docs/json.md
CHANGED
|
@@ -17,7 +17,11 @@ type AgentSessionEvent =
|
|
|
17
17
|
| { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
|
|
18
18
|
| { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
|
|
19
19
|
| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
|
|
20
|
-
| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
|
|
20
|
+
| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
|
|
21
|
+
| { type: "summarization_retry_scheduled"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
|
|
22
|
+
| { type: "summarization_retry_attempt_start"; source: "branchSummary" }
|
|
23
|
+
| { type: "summarization_retry_attempt_start"; source: "compaction"; reason: "manual" | "threshold" | "overflow" }
|
|
24
|
+
| { type: "summarization_retry_finished" };
|
|
21
25
|
```
|
|
22
26
|
|
|
23
27
|
`queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
|
package/docs/keybindings.md
CHANGED
|
@@ -112,6 +112,7 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
|
|
|
112
112
|
| `app.model.cycleForward` | `ctrl+p` | Cycle to next model |
|
|
113
113
|
| `app.model.cycleBackward` | `shift+ctrl+p` | Cycle to previous model |
|
|
114
114
|
| `app.thinking.cycle` | `shift+tab` | Cycle thinking level |
|
|
115
|
+
| `app.context.cycle` | `ctrl+shift+l` | Cycle supported context-window sizes for the current model |
|
|
115
116
|
| `app.thinking.toggle` | `ctrl+t` | Collapse or expand thinking blocks |
|
|
116
117
|
|
|
117
118
|
### Display and Message Queue
|
|
@@ -119,6 +120,7 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
|
|
|
119
120
|
| Keybinding id | Default | Description |
|
|
120
121
|
|--------|---------|-------------|
|
|
121
122
|
| `app.tools.expand` | `ctrl+o` | Collapse or expand tool output |
|
|
123
|
+
| `app.message.copy` | `ctrl+x` | Copy the last assistant message, or the selected message in `/tree` |
|
|
122
124
|
| `app.message.followUp` | `alt+enter` | Queue follow-up message |
|
|
123
125
|
| `app.message.dequeue` | `alt+up` | Restore queued messages to editor |
|
|
124
126
|
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# llama.cpp
|
|
2
|
+
|
|
3
|
+
Pi supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router discovers multiple GGUF models and loads or unloads them on demand.
|
|
4
|
+
|
|
5
|
+
Use a current llama.cpp build with router support. Follow the [build instructions](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md) or install a [prebuilt release](https://github.com/ggml-org/llama.cpp/releases) for your platform.
|
|
6
|
+
|
|
7
|
+
## Start the router
|
|
8
|
+
|
|
9
|
+
Start `llama-server` without `--model` or `-m`. Passing a model starts single-model mode instead of router mode.
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
llama-server \
|
|
13
|
+
--models-dir ~/models \
|
|
14
|
+
--no-models-autoload \
|
|
15
|
+
--jinja \
|
|
16
|
+
--host 127.0.0.1 \
|
|
17
|
+
--port 8080 \
|
|
18
|
+
-ngl 999 \
|
|
19
|
+
-c 32768
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Important options:
|
|
23
|
+
|
|
24
|
+
- `--models-dir ~/models` discovers local GGUF files.
|
|
25
|
+
- `--no-models-autoload` keeps loading explicit through `/llama`.
|
|
26
|
+
- `--jinja` enables compatible chat templates and tool calling.
|
|
27
|
+
- `-ngl 999` offloads as many layers as possible to the GPU.
|
|
28
|
+
- `-c 32768` sets the context window for each loaded model. Omit it to use the model's native context, which may require substantially more memory.
|
|
29
|
+
|
|
30
|
+
A single-file model can sit directly in the model directory. Put multimodal and multi-shard models in separate subdirectories:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
~/models/
|
|
34
|
+
├── llama-3.2-1b-Q4_K_M.gguf
|
|
35
|
+
├── gemma-3-4b-it-Q4_K_M/
|
|
36
|
+
│ ├── gemma-3-4b-it-Q4_K_M.gguf
|
|
37
|
+
│ └── mmproj-F16.gguf
|
|
38
|
+
└── large-model-Q4_K_M/
|
|
39
|
+
├── large-model-Q4_K_M-00001-of-00003.gguf
|
|
40
|
+
├── large-model-Q4_K_M-00002-of-00003.gguf
|
|
41
|
+
└── large-model-Q4_K_M-00003-of-00003.gguf
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Restart the router after manually adding files. For per-model context sizes and other options, use [llama.cpp model presets](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md#model-presets).
|
|
45
|
+
|
|
46
|
+
## Configure Pi
|
|
47
|
+
|
|
48
|
+
Start Pi and configure the provider:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
/login llama.cpp
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Enter the router URL and optional API key. The default URL is `http://127.0.0.1:8080`.
|
|
55
|
+
|
|
56
|
+
Environment variables can configure the same values without `/login`:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
export LLAMA_BASE_URL=http://127.0.0.1:8080
|
|
60
|
+
export LLAMA_API_KEY=optional-secret
|
|
61
|
+
draht
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
If the server uses an API key, start `llama-server` with the matching `--api-key` value. Keep `--host 127.0.0.1` for local-only access.
|
|
65
|
+
|
|
66
|
+
## Manage models
|
|
67
|
+
|
|
68
|
+
Run:
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
/llama
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- Select an unloaded model to load it.
|
|
75
|
+
- Select a loaded model to unload it.
|
|
76
|
+
- Select **Download model…**, search Hugging Face, then choose a repository and quantization. Exact `owner/repository[:quant]` values also work.
|
|
77
|
+
- Press Escape during a load or download to confirm cancellation.
|
|
78
|
+
|
|
79
|
+
Hugging Face search uses `HF_TOKEN` when set, then checks `$HF_TOKEN_PATH`, `$HF_HOME/token`, `$XDG_CACHE_HOME/huggingface/token`, and `~/.cache/huggingface/token`. Search also works without authentication, subject to lower rate limits. Pi warns before downloading gated repositories and links to their access page. The llama.cpp server performs the download, so its process must also have `HF_TOKEN` when the selected repository requires access.
|
|
80
|
+
|
|
81
|
+
If other models are loaded, Pi asks whether to unload them first or keep them loaded. Pi does not silently unload models and never deletes model files. The router may be shared with other clients, so `/llama` always displays the router's current state.
|
|
82
|
+
|
|
83
|
+
Only loaded models appear in `/model`. After loading a model, run `/model` to select it for the current Pi session.
|
|
84
|
+
|
|
85
|
+
If the router disconnects, `/llama` shows **Retry** and **Close**. Retry reconnects and refreshes model state without replaying the interrupted operation.
|
|
86
|
+
|
|
87
|
+
## Troubleshooting
|
|
88
|
+
|
|
89
|
+
Check that the router is reachable:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
curl http://127.0.0.1:8080/health
|
|
93
|
+
curl http://127.0.0.1:8080/models
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
- **No models in `/llama`:** Check `--models-dir`, the directory layout, and restart the router.
|
|
97
|
+
- **Model missing from `/model`:** Load it with `/llama` first.
|
|
98
|
+
- **Load fails or uses too much memory:** Lower `-c` or unload another model.
|
|
99
|
+
- **Server is not in router mode:** Start it without `--model`, `-m`, or `-hf`.
|
package/docs/models.md
CHANGED
|
@@ -357,6 +357,10 @@ Direct OpenAI GPT-5.6 Sol, Terra, and Luna default to a `272000` context window
|
|
|
357
357
|
|
|
358
358
|
The override preserves the built-in pricing metadata. Requests with more than 272K total input tokens use GPT-5.6's long-context rates for the entire request. Apply the same override to `gpt-5.6-terra` or `gpt-5.6-luna` when needed.
|
|
359
359
|
|
|
360
|
+
In interactive mode, direct OpenAI GPT-5.4, GPT-5.5, and GPT-5.6 Sol/Terra/Luna can switch between their 272K standard and 1.05M extended windows without editing `models.json`. OpenAI Codex GPT-5.6 Sol/Terra/Luna can switch between the 372K catalog default and 1.05M. Press Ctrl+Shift+L by default, or customize the `app.context.cycle` action in `~/.draht/agent/keybindings.json`.
|
|
361
|
+
|
|
362
|
+
The selected window is stored in the session. Switching to a smaller window prompts for compaction when the current context would not fit. Long-context pricing metadata remains active, and the interactive status message shows the input threshold where higher pricing begins.
|
|
363
|
+
|
|
360
364
|
Behavior notes:
|
|
361
365
|
- `modelOverrides` are applied to built-in provider models and matching extension-registered provider models.
|
|
362
366
|
- Unknown model IDs are ignored.
|
|
@@ -374,6 +378,8 @@ Some Anthropic models require adaptive thinking (`thinking.type: "adaptive"` plu
|
|
|
374
378
|
|
|
375
379
|
Some Anthropic-compatible providers emit thinking blocks with empty signatures and still expect them on replay. Set `allowEmptySignature` to `true` only for those providers; real Anthropic rejects empty thinking signatures.
|
|
376
380
|
|
|
381
|
+
Built-in Anthropic models enable `supportsStrictTools` in their model metadata. Custom Anthropic-compatible models must set it to `true` when their endpoint accepts strict JSON-schema tool definitions.
|
|
382
|
+
|
|
377
383
|
```json
|
|
378
384
|
{
|
|
379
385
|
"providers": {
|
|
@@ -407,6 +413,7 @@ Some Anthropic-compatible providers emit thinking blocks with empty signatures a
|
|
|
407
413
|
| `supportsCacheControlOnTools` | Whether the provider accepts Anthropic-style `cache_control` markers on tool definitions. Default: `true`. |
|
|
408
414
|
| `forceAdaptiveThinking` | Whether to send adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) for this model. Built-in adaptive models set this automatically. Default: `false`. |
|
|
409
415
|
| `allowEmptySignature` | Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: `false`. |
|
|
416
|
+
| `supportsStrictTools` | Whether the provider accepts strict JSON-schema tool definitions. Default: `false`; built-in Anthropic models enable it in generated metadata. |
|
|
410
417
|
|
|
411
418
|
## OpenAI Compatibility
|
|
412
419
|
|
|
@@ -443,8 +450,12 @@ For providers with partial OpenAI compatibility, use the `compat` field.
|
|
|
443
450
|
| `requiresThinkingAsText` | Convert thinking blocks to plain text |
|
|
444
451
|
| `requiresReasoningContentOnAssistantMessages` | Include empty `reasoning_content` on all replayed assistant messages when reasoning is enabled |
|
|
445
452
|
| `thinkingFormat` | Use `reasoning_effort`, `openrouter`, `deepseek`, `together`, `zai`, `qwen`, or `qwen-chat-template` thinking parameters |
|
|
446
|
-
| `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user
|
|
447
|
-
| `
|
|
453
|
+
| `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user, assistant, or tool-result text content. Currently only `anthropic` is supported. |
|
|
454
|
+
| `sendSessionAffinityHeaders` | For `openai-completions`, send session-affinity headers from the session id when caching is enabled. Default: `false`. |
|
|
455
|
+
| `sessionAffinityFormat` | For `openai-completions` and `openai-responses`, the session-affinity header format: `openai` sends `session_id`/`x-client-request-id` (completions also `x-session-affinity`), `openai-nosession` omits the underscore-containing `session_id` header, `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param. Default: auto-detected. |
|
|
456
|
+
| `supportsStrictMode` | Whether the provider accepts strict JSON-schema function tool definitions. Defaults depend on the API; built-in OpenAI models carry explicit capability metadata. |
|
|
457
|
+
| `supportsOpenAIGrammarTools` | Whether OpenAI-compatible APIs emit custom Lark/regex grammar tools. When `false`, grammar-constrained tools fall back to normal function tools. Default: `false`; the built-in model catalog enables it for GPT-5+ models on OpenAI, OpenAI Codex, Azure OpenAI, GitHub Copilot, opencode, and Cloudflare AI Gateway. |
|
|
458
|
+
| `deferredToolsMode` | Use provider-specific deferred tool serialization. Currently only `"kimi"` is supported for Kimi's OpenAI-compatible Chat Completions format. |
|
|
448
459
|
| `supportsLongCacheRetention` | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_retention: "24h"` for OpenAI prompt caching, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
|
|
449
460
|
| `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
|
|
450
461
|
| `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |
|
package/docs/packages.md
CHANGED
|
@@ -30,6 +30,7 @@ pi remove npm:@foo/bar
|
|
|
30
30
|
pi list # show installed packages from settings
|
|
31
31
|
pi update # update pi, update packages, and reconcile pinned git refs
|
|
32
32
|
pi update --extensions # update packages and reconcile pinned git refs only
|
|
33
|
+
pi update --models # refresh model catalogs only
|
|
33
34
|
pi update --self # update pi only
|
|
34
35
|
pi update --self --force # reinstall pi even if current
|
|
35
36
|
pi update npm:@foo/bar # update one package
|
package/docs/prompt-templates.md
CHANGED
|
@@ -69,6 +69,7 @@ Templates support positional arguments, defaults, and simple slicing:
|
|
|
69
69
|
- `$1`, `$2`, ... positional args
|
|
70
70
|
- `$@` or `$ARGUMENTS` for all args joined
|
|
71
71
|
- `${1:-default}` uses arg 1 when present/non-empty, otherwise `default`
|
|
72
|
+
- `${@:-default}` or `${ARGUMENTS:-default}` uses all arguments when present/non-empty, otherwise `default`
|
|
72
73
|
- `${@:N}` for args from the Nth position (1-indexed)
|
|
73
74
|
- `${@:N:L}` for `L` args starting at N
|
|
74
75
|
|