@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.
Files changed (288) hide show
  1. package/CHANGELOG.md +87 -0
  2. package/README.md +1 -0
  3. package/dist/bun/cli.js +2 -0
  4. package/dist/bun/cli.js.map +1 -1
  5. package/dist/cli/args.d.ts.map +1 -1
  6. package/dist/cli/args.js +12 -2
  7. package/dist/cli/args.js.map +1 -1
  8. package/dist/cli/config-selector.js +1 -1
  9. package/dist/cli/config-selector.js.map +1 -1
  10. package/dist/cli/credential-print.d.ts +23 -0
  11. package/dist/cli/credential-print.d.ts.map +1 -0
  12. package/dist/cli/credential-print.js +116 -0
  13. package/dist/cli/credential-print.js.map +1 -0
  14. package/dist/cli/list-models.d.ts +2 -2
  15. package/dist/cli/list-models.d.ts.map +1 -1
  16. package/dist/cli/list-models.js +3 -3
  17. package/dist/cli/list-models.js.map +1 -1
  18. package/dist/cli/startup-ui.js +1 -1
  19. package/dist/cli/startup-ui.js.map +1 -1
  20. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  21. package/dist/core/agent-session-runtime.js +3 -0
  22. package/dist/core/agent-session-runtime.js.map +1 -1
  23. package/dist/core/agent-session-services.d.ts +3 -6
  24. package/dist/core/agent-session-services.d.ts.map +1 -1
  25. package/dist/core/agent-session-services.js +23 -9
  26. package/dist/core/agent-session-services.js.map +1 -1
  27. package/dist/core/agent-session.d.ts +52 -11
  28. package/dist/core/agent-session.d.ts.map +1 -1
  29. package/dist/core/agent-session.js +199 -101
  30. package/dist/core/agent-session.js.map +1 -1
  31. package/dist/core/auth-storage.d.ts +15 -103
  32. package/dist/core/auth-storage.d.ts.map +1 -1
  33. package/dist/core/auth-storage.js +46 -259
  34. package/dist/core/auth-storage.js.map +1 -1
  35. package/dist/core/cache-stats.d.ts +2 -2
  36. package/dist/core/cache-stats.d.ts.map +1 -1
  37. package/dist/core/cache-stats.js +1 -1
  38. package/dist/core/cache-stats.js.map +1 -1
  39. package/dist/core/compaction/branch-summarization.d.ts +8 -2
  40. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  41. package/dist/core/compaction/branch-summarization.js +8 -11
  42. package/dist/core/compaction/branch-summarization.js.map +1 -1
  43. package/dist/core/compaction/compaction.d.ts +19 -3
  44. package/dist/core/compaction/compaction.d.ts.map +1 -1
  45. package/dist/core/compaction/compaction.js +71 -26
  46. package/dist/core/compaction/compaction.js.map +1 -1
  47. package/dist/core/compaction/utils.d.ts +1 -1
  48. package/dist/core/compaction/utils.d.ts.map +1 -1
  49. package/dist/core/compaction/utils.js +6 -17
  50. package/dist/core/compaction/utils.js.map +1 -1
  51. package/dist/core/context-windows.d.ts +7 -0
  52. package/dist/core/context-windows.d.ts.map +1 -0
  53. package/dist/core/context-windows.js +35 -0
  54. package/dist/core/context-windows.js.map +1 -0
  55. package/dist/core/extensions/index.d.ts +1 -1
  56. package/dist/core/extensions/index.d.ts.map +1 -1
  57. package/dist/core/extensions/index.js.map +1 -1
  58. package/dist/core/extensions/loader.d.ts.map +1 -1
  59. package/dist/core/extensions/loader.js +18 -3
  60. package/dist/core/extensions/loader.js.map +1 -1
  61. package/dist/core/extensions/runner.d.ts +6 -1
  62. package/dist/core/extensions/runner.d.ts.map +1 -1
  63. package/dist/core/extensions/runner.js +80 -0
  64. package/dist/core/extensions/runner.js.map +1 -1
  65. package/dist/core/extensions/types.d.ts +48 -4
  66. package/dist/core/extensions/types.d.ts.map +1 -1
  67. package/dist/core/extensions/types.js.map +1 -1
  68. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  69. package/dist/core/extensions/wrapper.js +22 -3
  70. package/dist/core/extensions/wrapper.js.map +1 -1
  71. package/dist/core/footer-data-provider.d.ts +10 -0
  72. package/dist/core/footer-data-provider.d.ts.map +1 -1
  73. package/dist/core/footer-data-provider.js +1 -1
  74. package/dist/core/footer-data-provider.js.map +1 -1
  75. package/dist/core/keybindings.d.ts +13 -3
  76. package/dist/core/keybindings.d.ts.map +1 -1
  77. package/dist/core/keybindings.js +11 -3
  78. package/dist/core/keybindings.js.map +1 -1
  79. package/dist/core/model-config.d.ts +542 -0
  80. package/dist/core/model-config.d.ts.map +1 -0
  81. package/dist/core/model-config.js +247 -0
  82. package/dist/core/model-config.js.map +1 -0
  83. package/dist/core/model-registry.d.ts +17 -123
  84. package/dist/core/model-registry.d.ts.map +1 -1
  85. package/dist/core/model-registry.js +59 -730
  86. package/dist/core/model-registry.js.map +1 -1
  87. package/dist/core/model-resolver.d.ts +7 -6
  88. package/dist/core/model-resolver.d.ts.map +1 -1
  89. package/dist/core/model-resolver.js +41 -21
  90. package/dist/core/model-resolver.js.map +1 -1
  91. package/dist/core/model-runtime.d.ts +83 -0
  92. package/dist/core/model-runtime.d.ts.map +1 -0
  93. package/dist/core/model-runtime.js +431 -0
  94. package/dist/core/model-runtime.js.map +1 -0
  95. package/dist/core/models-store.d.ts +17 -0
  96. package/dist/core/models-store.d.ts.map +1 -0
  97. package/dist/core/models-store.js +46 -0
  98. package/dist/core/models-store.js.map +1 -0
  99. package/dist/core/package-manager.d.ts.map +1 -1
  100. package/dist/core/package-manager.js +31 -12
  101. package/dist/core/package-manager.js.map +1 -1
  102. package/dist/core/prompt-templates.d.ts +1 -0
  103. package/dist/core/prompt-templates.d.ts.map +1 -1
  104. package/dist/core/prompt-templates.js +4 -4
  105. package/dist/core/prompt-templates.js.map +1 -1
  106. package/dist/core/provider-composer.d.ts +55 -0
  107. package/dist/core/provider-composer.d.ts.map +1 -0
  108. package/dist/core/provider-composer.js +375 -0
  109. package/dist/core/provider-composer.js.map +1 -0
  110. package/dist/core/radius.d.ts +2 -0
  111. package/dist/core/radius.d.ts.map +1 -0
  112. package/dist/core/radius.js +2 -0
  113. package/dist/core/radius.js.map +1 -0
  114. package/dist/core/remote-catalog-provider.d.ts +5 -0
  115. package/dist/core/remote-catalog-provider.d.ts.map +1 -0
  116. package/dist/core/remote-catalog-provider.js +115 -0
  117. package/dist/core/remote-catalog-provider.js.map +1 -0
  118. package/dist/core/resource-loader.d.ts +15 -0
  119. package/dist/core/resource-loader.d.ts.map +1 -1
  120. package/dist/core/resource-loader.js +64 -9
  121. package/dist/core/resource-loader.js.map +1 -1
  122. package/dist/core/runtime-credentials.d.ts +15 -0
  123. package/dist/core/runtime-credentials.d.ts.map +1 -0
  124. package/dist/core/runtime-credentials.js +35 -0
  125. package/dist/core/runtime-credentials.js.map +1 -0
  126. package/dist/core/sdk.d.ts +3 -6
  127. package/dist/core/sdk.d.ts.map +1 -1
  128. package/dist/core/sdk.js +22 -21
  129. package/dist/core/sdk.js.map +1 -1
  130. package/dist/core/session-manager.d.ts +14 -6
  131. package/dist/core/session-manager.d.ts.map +1 -1
  132. package/dist/core/session-manager.js +116 -28
  133. package/dist/core/session-manager.js.map +1 -1
  134. package/dist/core/settings-manager.d.ts +1 -1
  135. package/dist/core/settings-manager.d.ts.map +1 -1
  136. package/dist/core/settings-manager.js.map +1 -1
  137. package/dist/core/system-prompt.d.ts.map +1 -1
  138. package/dist/core/system-prompt.js +2 -12
  139. package/dist/core/system-prompt.js.map +1 -1
  140. package/dist/core/tools/bash.d.ts +2 -0
  141. package/dist/core/tools/bash.d.ts.map +1 -1
  142. package/dist/core/tools/bash.js +34 -5
  143. package/dist/core/tools/bash.js.map +1 -1
  144. package/dist/core/tools/read.js +1 -1
  145. package/dist/core/tools/read.js.map +1 -1
  146. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  147. package/dist/core/tools/tool-definition-wrapper.js +3 -1
  148. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  149. package/dist/core/usage-totals.d.ts +19 -0
  150. package/dist/core/usage-totals.d.ts.map +1 -0
  151. package/dist/core/usage-totals.js +52 -0
  152. package/dist/core/usage-totals.js.map +1 -0
  153. package/dist/extensions/index.d.ts +3 -0
  154. package/dist/extensions/index.d.ts.map +1 -0
  155. package/dist/extensions/index.js +3 -0
  156. package/dist/extensions/index.js.map +1 -0
  157. package/dist/extensions/llama/client.d.ts +61 -0
  158. package/dist/extensions/llama/client.d.ts.map +1 -0
  159. package/dist/extensions/llama/client.js +300 -0
  160. package/dist/extensions/llama/client.js.map +1 -0
  161. package/dist/extensions/llama/huggingface.d.ts +23 -0
  162. package/dist/extensions/llama/huggingface.d.ts.map +1 -0
  163. package/dist/extensions/llama/huggingface.js +139 -0
  164. package/dist/extensions/llama/huggingface.js.map +1 -0
  165. package/dist/extensions/llama/index.d.ts +3 -0
  166. package/dist/extensions/llama/index.d.ts.map +1 -0
  167. package/dist/extensions/llama/index.js +208 -0
  168. package/dist/extensions/llama/index.js.map +1 -0
  169. package/dist/extensions/llama/provider.d.ts +10 -0
  170. package/dist/extensions/llama/provider.d.ts.map +1 -0
  171. package/dist/extensions/llama/provider.js +107 -0
  172. package/dist/extensions/llama/provider.js.map +1 -0
  173. package/dist/extensions/llama/ui.d.ts +42 -0
  174. package/dist/extensions/llama/ui.d.ts.map +1 -0
  175. package/dist/extensions/llama/ui.js +400 -0
  176. package/dist/extensions/llama/ui.js.map +1 -0
  177. package/dist/index.d.ts +4 -3
  178. package/dist/index.d.ts.map +1 -1
  179. package/dist/index.js +3 -3
  180. package/dist/index.js.map +1 -1
  181. package/dist/main.d.ts.map +1 -1
  182. package/dist/main.js +63 -16
  183. package/dist/main.js.map +1 -1
  184. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  185. package/dist/modes/interactive/components/assistant-message.js +22 -10
  186. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  187. package/dist/modes/interactive/components/custom-editor.js +1 -1
  188. package/dist/modes/interactive/components/custom-editor.js.map +1 -1
  189. package/dist/modes/interactive/components/custom-message.d.ts +3 -1
  190. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  191. package/dist/modes/interactive/components/custom-message.js +9 -2
  192. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  193. package/dist/modes/interactive/components/extension-editor.d.ts +1 -2
  194. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  195. package/dist/modes/interactive/components/extension-editor.js +16 -46
  196. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  197. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  198. package/dist/modes/interactive/components/footer.js +24 -23
  199. package/dist/modes/interactive/components/footer.js.map +1 -1
  200. package/dist/modes/interactive/components/login-dialog.d.ts +5 -5
  201. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  202. package/dist/modes/interactive/components/login-dialog.js +17 -8
  203. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  204. package/dist/modes/interactive/components/model-selector.d.ts +11 -4
  205. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  206. package/dist/modes/interactive/components/model-selector.js +74 -41
  207. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  208. package/dist/modes/interactive/components/oauth-selector.d.ts +4 -4
  209. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  210. package/dist/modes/interactive/components/oauth-selector.js +14 -25
  211. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  212. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  213. package/dist/modes/interactive/components/scoped-models-selector.js +22 -13
  214. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  215. package/dist/modes/interactive/components/tree-selector.d.ts +5 -0
  216. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  217. package/dist/modes/interactive/components/tree-selector.js +47 -12
  218. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  219. package/dist/modes/interactive/external-editor.d.ts +12 -0
  220. package/dist/modes/interactive/external-editor.d.ts.map +1 -0
  221. package/dist/modes/interactive/external-editor.js +37 -0
  222. package/dist/modes/interactive/external-editor.js.map +1 -0
  223. package/dist/modes/interactive/interactive-mode.d.ts +10 -7
  224. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  225. package/dist/modes/interactive/interactive-mode.js +369 -261
  226. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  227. package/dist/modes/rpc/rpc-client.d.ts +4 -0
  228. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  229. package/dist/modes/rpc/rpc-client.js +7 -0
  230. package/dist/modes/rpc/rpc-client.js.map +1 -1
  231. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  232. package/dist/modes/rpc/rpc-mode.js +20 -2
  233. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  234. package/dist/modes/rpc/rpc-types.d.ts +11 -0
  235. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  236. package/dist/modes/rpc/rpc-types.js.map +1 -1
  237. package/dist/package-manager-cli.d.ts.map +1 -1
  238. package/dist/package-manager-cli.js +67 -5
  239. package/dist/package-manager-cli.js.map +1 -1
  240. package/dist/utils/clipboard-native.d.ts +1 -0
  241. package/dist/utils/clipboard-native.d.ts.map +1 -1
  242. package/dist/utils/clipboard-native.js.map +1 -1
  243. package/dist/utils/clipboard.d.ts +2 -0
  244. package/dist/utils/clipboard.d.ts.map +1 -1
  245. package/dist/utils/clipboard.js +32 -8
  246. package/dist/utils/clipboard.js.map +1 -1
  247. package/dist/utils/version-check.d.ts.map +1 -1
  248. package/dist/utils/version-check.js +3 -1
  249. package/dist/utils/version-check.js.map +1 -1
  250. package/docs/compaction.md +9 -4
  251. package/docs/custom-provider.md +50 -16
  252. package/docs/environment-variables.md +88 -0
  253. package/docs/extensions.md +228 -15
  254. package/docs/index.md +2 -0
  255. package/docs/json.md +5 -1
  256. package/docs/keybindings.md +2 -0
  257. package/docs/llama-cpp.md +99 -0
  258. package/docs/models.md +13 -2
  259. package/docs/packages.md +1 -0
  260. package/docs/prompt-templates.md +1 -0
  261. package/docs/providers.md +36 -2
  262. package/docs/quickstart.md +1 -1
  263. package/docs/rpc.md +107 -7
  264. package/docs/sdk.md +3 -0
  265. package/docs/session-format.md +19 -3
  266. package/docs/settings.md +1 -1
  267. package/docs/tui.md +41 -26
  268. package/docs/usage.md +4 -14
  269. package/examples/extensions/custom-compaction.ts +4 -0
  270. package/examples/extensions/custom-provider-anthropic/index.ts +9 -3
  271. package/examples/extensions/custom-provider-anthropic/package.json +1 -1
  272. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  273. package/examples/extensions/custom-provider-qwen-cli/package.json +1 -1
  274. package/examples/extensions/gondolin/package.json +2 -2
  275. package/examples/extensions/handoff.ts +9 -1
  276. package/examples/extensions/kimi-deferred-tools.ts +61 -0
  277. package/examples/extensions/message-renderer.ts +2 -2
  278. package/examples/extensions/sandbox/package.json +1 -1
  279. package/examples/extensions/summarize.ts +3 -0
  280. package/examples/extensions/with-deps/package.json +1 -1
  281. package/examples/sdk/02-custom-model.ts +5 -8
  282. package/examples/sdk/09-api-keys-and-oauth.ts +15 -31
  283. package/examples/sdk/12-full-control.ts +9 -12
  284. package/package.json +10 -8
  285. package/dist/core/provider-display-names.d.ts +0 -2
  286. package/dist/core/provider-display-names.d.ts.map +0 -1
  287. package/dist/core/provider-display-names.js +0 -36
  288. package/dist/core/provider-display-names.js.map +0 -1
@@ -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
- "pi": {
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 { summary: { summary: "...", details: {} } };
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 `isError`); omitted fields keep their current values
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 keys.
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
- If you need to discover models from a remote endpoint, prefer an async extension factory over deferring the fetch to `session_start`. pi waits for the factory before startup continues, so the registered models are available immediately, including to `pi --list-models`.
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
- **Config options:**
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
- See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
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((_tui, theme, keybindings) =>
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` and `keybindings` from the app
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, 0, 0);
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.
@@ -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/assistant text content. Currently only `anthropic` is supported. |
447
- | `supportsStrictMode` | Include the `strict` field in tool definitions |
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
@@ -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