@draht/coding-agent 2026.5.12 → 2026.6.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (605) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/bin/draht-tools.cjs +3756 -1
  3. package/dist/bun/cli.d.ts.map +1 -1
  4. package/dist/bun/cli.js +4 -2
  5. package/dist/bun/cli.js.map +1 -1
  6. package/dist/bun/restore-sandbox-env.d.ts +13 -0
  7. package/dist/bun/restore-sandbox-env.d.ts.map +1 -0
  8. package/dist/bun/restore-sandbox-env.js +32 -0
  9. package/dist/bun/restore-sandbox-env.js.map +1 -0
  10. package/dist/cli/args.d.ts +9 -4
  11. package/dist/cli/args.d.ts.map +1 -1
  12. package/dist/cli/args.js +88 -35
  13. package/dist/cli/args.js.map +1 -1
  14. package/dist/cli/config-selector.d.ts +2 -2
  15. package/dist/cli/config-selector.d.ts.map +1 -1
  16. package/dist/cli/config-selector.js +1 -1
  17. package/dist/cli/config-selector.js.map +1 -1
  18. package/dist/cli/file-processor.d.ts.map +1 -1
  19. package/dist/cli/file-processor.js +2 -3
  20. package/dist/cli/file-processor.js.map +1 -1
  21. package/dist/cli/initial-message.d.ts +1 -1
  22. package/dist/cli/initial-message.d.ts.map +1 -1
  23. package/dist/cli/initial-message.js.map +1 -1
  24. package/dist/cli/list-models.d.ts +1 -1
  25. package/dist/cli/list-models.d.ts.map +1 -1
  26. package/dist/cli/list-models.js +7 -1
  27. package/dist/cli/list-models.js.map +1 -1
  28. package/dist/cli/project-trust.d.ts +10 -0
  29. package/dist/cli/project-trust.d.ts.map +1 -0
  30. package/dist/cli/project-trust.js +48 -0
  31. package/dist/cli/project-trust.js.map +1 -0
  32. package/dist/cli/session-picker.d.ts +1 -1
  33. package/dist/cli/session-picker.d.ts.map +1 -1
  34. package/dist/cli/session-picker.js.map +1 -1
  35. package/dist/cli/startup-ui.d.ts +16 -0
  36. package/dist/cli/startup-ui.d.ts.map +1 -0
  37. package/dist/cli/startup-ui.js +112 -0
  38. package/dist/cli/startup-ui.js.map +1 -0
  39. package/dist/cli.d.ts.map +1 -1
  40. package/dist/cli.js +7 -4
  41. package/dist/cli.js.map +1 -1
  42. package/dist/config.d.ts +23 -13
  43. package/dist/config.d.ts.map +1 -1
  44. package/dist/config.js +264 -62
  45. package/dist/config.js.map +1 -1
  46. package/dist/core/agent-session-runtime.d.ts +45 -9
  47. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  48. package/dist/core/agent-session-runtime.js +100 -33
  49. package/dist/core/agent-session-runtime.js.map +1 -1
  50. package/dist/core/agent-session-services.d.ts +6 -4
  51. package/dist/core/agent-session-services.d.ts.map +1 -1
  52. package/dist/core/agent-session-services.js +7 -4
  53. package/dist/core/agent-session-services.js.map +1 -1
  54. package/dist/core/agent-session.d.ts +47 -31
  55. package/dist/core/agent-session.d.ts.map +1 -1
  56. package/dist/core/agent-session.js +470 -443
  57. package/dist/core/agent-session.js.map +1 -1
  58. package/dist/core/auth-guidance.d.ts +5 -0
  59. package/dist/core/auth-guidance.d.ts.map +1 -0
  60. package/dist/core/auth-guidance.js +21 -0
  61. package/dist/core/auth-guidance.js.map +1 -0
  62. package/dist/core/auth-storage.d.ts +10 -1
  63. package/dist/core/auth-storage.d.ts.map +1 -1
  64. package/dist/core/auth-storage.js +27 -6
  65. package/dist/core/auth-storage.js.map +1 -1
  66. package/dist/core/bash-executor.d.ts +1 -15
  67. package/dist/core/bash-executor.d.ts.map +1 -1
  68. package/dist/core/bash-executor.js +10 -24
  69. package/dist/core/bash-executor.js.map +1 -1
  70. package/dist/core/builtins/subagent.d.ts.map +1 -1
  71. package/dist/core/builtins/subagent.js +1 -2
  72. package/dist/core/builtins/subagent.js.map +1 -1
  73. package/dist/core/compaction/branch-summarization.d.ts +6 -4
  74. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  75. package/dist/core/compaction/branch-summarization.js +9 -3
  76. package/dist/core/compaction/branch-summarization.js.map +1 -1
  77. package/dist/core/compaction/compaction.d.ts +5 -5
  78. package/dist/core/compaction/compaction.d.ts.map +1 -1
  79. package/dist/core/compaction/compaction.js +43 -37
  80. package/dist/core/compaction/compaction.js.map +1 -1
  81. package/dist/core/compaction/index.d.ts +3 -3
  82. package/dist/core/compaction/index.d.ts.map +1 -1
  83. package/dist/core/compaction/index.js.map +1 -1
  84. package/dist/core/compaction/utils.d.ts +1 -1
  85. package/dist/core/compaction/utils.d.ts.map +1 -1
  86. package/dist/core/compaction/utils.js +1 -1
  87. package/dist/core/compaction/utils.js.map +1 -1
  88. package/dist/core/exec.d.ts.map +1 -1
  89. package/dist/core/exec.js.map +1 -1
  90. package/dist/core/experimental.d.ts +2 -0
  91. package/dist/core/experimental.d.ts.map +1 -0
  92. package/dist/core/experimental.js +4 -0
  93. package/dist/core/experimental.js.map +1 -0
  94. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  95. package/dist/core/export-html/ansi-to-html.js +1 -1
  96. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  97. package/dist/core/export-html/index.d.ts +1 -1
  98. package/dist/core/export-html/index.d.ts.map +1 -1
  99. package/dist/core/export-html/index.js +13 -11
  100. package/dist/core/export-html/index.js.map +1 -1
  101. package/dist/core/export-html/template.css +69 -4
  102. package/dist/core/export-html/template.js +231 -57
  103. package/dist/core/export-html/tool-renderer.d.ts +0 -6
  104. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  105. package/dist/core/export-html/tool-renderer.js +15 -2
  106. package/dist/core/export-html/tool-renderer.js.map +1 -1
  107. package/dist/core/extensions/index.d.ts +8 -8
  108. package/dist/core/extensions/index.d.ts.map +1 -1
  109. package/dist/core/extensions/index.js.map +1 -1
  110. package/dist/core/extensions/loader.d.ts +3 -3
  111. package/dist/core/extensions/loader.d.ts.map +1 -1
  112. package/dist/core/extensions/loader.js +27 -35
  113. package/dist/core/extensions/loader.js.map +1 -1
  114. package/dist/core/extensions/runner.d.ts +30 -12
  115. package/dist/core/extensions/runner.d.ts.map +1 -1
  116. package/dist/core/extensions/runner.js +215 -32
  117. package/dist/core/extensions/runner.js.map +1 -1
  118. package/dist/core/extensions/types.d.ts +163 -35
  119. package/dist/core/extensions/types.d.ts.map +1 -1
  120. package/dist/core/extensions/types.js.map +1 -1
  121. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  122. package/dist/core/extensions/wrapper.js +2 -2
  123. package/dist/core/extensions/wrapper.js.map +1 -1
  124. package/dist/core/footer-data-provider.d.ts +7 -1
  125. package/dist/core/footer-data-provider.d.ts.map +1 -1
  126. package/dist/core/footer-data-provider.js +78 -54
  127. package/dist/core/footer-data-provider.js.map +1 -1
  128. package/dist/core/http-dispatcher.d.ts +21 -0
  129. package/dist/core/http-dispatcher.d.ts.map +1 -0
  130. package/dist/core/http-dispatcher.js +48 -0
  131. package/dist/core/http-dispatcher.js.map +1 -0
  132. package/dist/core/index.d.ts +9 -8
  133. package/dist/core/index.d.ts.map +1 -1
  134. package/dist/core/index.js +2 -1
  135. package/dist/core/index.js.map +1 -1
  136. package/dist/core/keybindings.d.ts +66 -1
  137. package/dist/core/keybindings.d.ts.map +1 -1
  138. package/dist/core/keybindings.js +56 -1
  139. package/dist/core/keybindings.js.map +1 -1
  140. package/dist/core/model-registry.d.ts +22 -4
  141. package/dist/core/model-registry.d.ts.map +1 -1
  142. package/dist/core/model-registry.js +216 -44
  143. package/dist/core/model-registry.js.map +1 -1
  144. package/dist/core/model-resolver.d.ts +2 -1
  145. package/dist/core/model-resolver.d.ts.map +1 -1
  146. package/dist/core/model-resolver.js +48 -21
  147. package/dist/core/model-resolver.js.map +1 -1
  148. package/dist/core/output-guard.d.ts +1 -0
  149. package/dist/core/output-guard.d.ts.map +1 -1
  150. package/dist/core/output-guard.js +52 -22
  151. package/dist/core/output-guard.js.map +1 -1
  152. package/dist/core/package-manager.d.ts +17 -2
  153. package/dist/core/package-manager.d.ts.map +1 -1
  154. package/dist/core/package-manager.js +363 -121
  155. package/dist/core/package-manager.js.map +1 -1
  156. package/dist/core/project-trust.d.ts +15 -0
  157. package/dist/core/project-trust.d.ts.map +1 -0
  158. package/dist/core/project-trust.js +58 -0
  159. package/dist/core/project-trust.js.map +1 -0
  160. package/dist/core/prompt-templates.d.ts +13 -11
  161. package/dist/core/prompt-templates.d.ts.map +1 -1
  162. package/dist/core/prompt-templates.js +67 -76
  163. package/dist/core/prompt-templates.js.map +1 -1
  164. package/dist/core/provider-attribution.d.ts +4 -0
  165. package/dist/core/provider-attribution.d.ts.map +1 -0
  166. package/dist/core/provider-attribution.js +72 -0
  167. package/dist/core/provider-attribution.js.map +1 -0
  168. package/dist/core/provider-display-names.d.ts +2 -0
  169. package/dist/core/provider-display-names.d.ts.map +1 -0
  170. package/dist/core/provider-display-names.js +36 -0
  171. package/dist/core/provider-display-names.js.map +1 -0
  172. package/dist/core/resolve-config-value.d.ts +9 -1
  173. package/dist/core/resolve-config-value.d.ts.map +1 -1
  174. package/dist/core/resolve-config-value.js +134 -11
  175. package/dist/core/resolve-config-value.js.map +1 -1
  176. package/dist/core/resource-loader.d.ts +34 -14
  177. package/dist/core/resource-loader.d.ts.map +1 -1
  178. package/dist/core/resource-loader.js +165 -76
  179. package/dist/core/resource-loader.js.map +1 -1
  180. package/dist/core/sdk.d.ts +26 -10
  181. package/dist/core/sdk.d.ts.map +1 -1
  182. package/dist/core/sdk.js +45 -16
  183. package/dist/core/sdk.js.map +1 -1
  184. package/dist/core/session-manager.d.ts +11 -12
  185. package/dist/core/session-manager.d.ts.map +1 -1
  186. package/dist/core/session-manager.js +245 -132
  187. package/dist/core/session-manager.js.map +1 -1
  188. package/dist/core/settings-manager.d.ts +52 -5
  189. package/dist/core/settings-manager.d.ts.map +1 -1
  190. package/dist/core/settings-manager.js +202 -38
  191. package/dist/core/settings-manager.js.map +1 -1
  192. package/dist/core/skills.d.ts +10 -10
  193. package/dist/core/skills.d.ts.map +1 -1
  194. package/dist/core/skills.js +13 -35
  195. package/dist/core/skills.js.map +1 -1
  196. package/dist/core/slash-commands.d.ts +1 -1
  197. package/dist/core/slash-commands.d.ts.map +1 -1
  198. package/dist/core/slash-commands.js +7 -4
  199. package/dist/core/slash-commands.js.map +1 -1
  200. package/dist/core/source-info.d.ts +1 -1
  201. package/dist/core/source-info.d.ts.map +1 -1
  202. package/dist/core/source-info.js.map +1 -1
  203. package/dist/core/system-prompt.d.ts +4 -4
  204. package/dist/core/system-prompt.d.ts.map +1 -1
  205. package/dist/core/system-prompt.js +14 -10
  206. package/dist/core/system-prompt.js.map +1 -1
  207. package/dist/core/telemetry.d.ts +3 -0
  208. package/dist/core/telemetry.d.ts.map +1 -0
  209. package/dist/core/telemetry.js +9 -0
  210. package/dist/core/telemetry.js.map +1 -0
  211. package/dist/core/tools/bash.d.ts +11 -16
  212. package/dist/core/tools/bash.d.ts.map +1 -1
  213. package/dist/core/tools/bash.js +162 -177
  214. package/dist/core/tools/bash.js.map +1 -1
  215. package/dist/core/tools/edit-diff.d.ts +3 -1
  216. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  217. package/dist/core/tools/edit-diff.js +11 -3
  218. package/dist/core/tools/edit-diff.js.map +1 -1
  219. package/dist/core/tools/edit.d.ts +22 -24
  220. package/dist/core/tools/edit.d.ts.map +1 -1
  221. package/dist/core/tools/edit.js +199 -111
  222. package/dist/core/tools/edit.js.map +1 -1
  223. package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
  224. package/dist/core/tools/file-mutation-queue.js +27 -12
  225. package/dist/core/tools/file-mutation-queue.js.map +1 -1
  226. package/dist/core/tools/find.d.ts +7 -18
  227. package/dist/core/tools/find.d.ts.map +1 -1
  228. package/dist/core/tools/find.js +134 -95
  229. package/dist/core/tools/find.js.map +1 -1
  230. package/dist/core/tools/grep.d.ts +11 -30
  231. package/dist/core/tools/grep.d.ts.map +1 -1
  232. package/dist/core/tools/grep.js +23 -12
  233. package/dist/core/tools/grep.js.map +1 -1
  234. package/dist/core/tools/index.d.ts +26 -101
  235. package/dist/core/tools/index.d.ts.map +1 -1
  236. package/dist/core/tools/index.js +78 -52
  237. package/dist/core/tools/index.js.map +1 -1
  238. package/dist/core/tools/ls.d.ts +6 -15
  239. package/dist/core/tools/ls.d.ts.map +1 -1
  240. package/dist/core/tools/ls.js +12 -17
  241. package/dist/core/tools/ls.js.map +1 -1
  242. package/dist/core/tools/output-accumulator.d.ts +52 -0
  243. package/dist/core/tools/output-accumulator.d.ts.map +1 -0
  244. package/dist/core/tools/output-accumulator.js +184 -0
  245. package/dist/core/tools/output-accumulator.js.map +1 -0
  246. package/dist/core/tools/path-utils.d.ts +2 -0
  247. package/dist/core/tools/path-utils.d.ts.map +1 -1
  248. package/dist/core/tools/path-utils.js +40 -22
  249. package/dist/core/tools/path-utils.js.map +1 -1
  250. package/dist/core/tools/read.d.ts +7 -18
  251. package/dist/core/tools/read.d.ts.map +1 -1
  252. package/dist/core/tools/read.js +100 -36
  253. package/dist/core/tools/read.js.map +1 -1
  254. package/dist/core/tools/render-utils.d.ts +5 -2
  255. package/dist/core/tools/render-utils.d.ts.map +1 -1
  256. package/dist/core/tools/render-utils.js +18 -2
  257. package/dist/core/tools/render-utils.js.map +1 -1
  258. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  259. package/dist/core/tools/tool-definition-wrapper.js +2 -0
  260. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  261. package/dist/core/tools/truncate.d.ts.map +1 -1
  262. package/dist/core/tools/truncate.js +12 -2
  263. package/dist/core/tools/truncate.js.map +1 -1
  264. package/dist/core/tools/write.d.ts +5 -14
  265. package/dist/core/tools/write.d.ts.map +1 -1
  266. package/dist/core/tools/write.js +27 -46
  267. package/dist/core/tools/write.js.map +1 -1
  268. package/dist/core/trust-manager.d.ts +31 -0
  269. package/dist/core/trust-manager.d.ts.map +1 -0
  270. package/dist/core/trust-manager.js +187 -0
  271. package/dist/core/trust-manager.js.map +1 -0
  272. package/dist/index.d.ts +31 -29
  273. package/dist/index.d.ts.map +1 -1
  274. package/dist/index.js +9 -8
  275. package/dist/index.js.map +1 -1
  276. package/dist/main.d.ts +5 -1
  277. package/dist/main.d.ts.map +1 -1
  278. package/dist/main.js +170 -87
  279. package/dist/main.js.map +1 -1
  280. package/dist/migrations.d.ts +2 -2
  281. package/dist/migrations.d.ts.map +1 -1
  282. package/dist/migrations.js +127 -5
  283. package/dist/migrations.js.map +1 -1
  284. package/dist/modes/index.d.ts +5 -5
  285. package/dist/modes/index.d.ts.map +1 -1
  286. package/dist/modes/index.js.map +1 -1
  287. package/dist/modes/interactive/components/assistant-message.d.ts +2 -0
  288. package/dist/modes/interactive/components/assistant-message.d.ts.map +1 -1
  289. package/dist/modes/interactive/components/assistant-message.js +14 -0
  290. package/dist/modes/interactive/components/assistant-message.js.map +1 -1
  291. package/dist/modes/interactive/components/bash-execution.d.ts +1 -1
  292. package/dist/modes/interactive/components/bash-execution.d.ts.map +1 -1
  293. package/dist/modes/interactive/components/bash-execution.js +3 -3
  294. package/dist/modes/interactive/components/bash-execution.js.map +1 -1
  295. package/dist/modes/interactive/components/bordered-loader.d.ts.map +1 -1
  296. package/dist/modes/interactive/components/bordered-loader.js +3 -0
  297. package/dist/modes/interactive/components/bordered-loader.js.map +1 -1
  298. package/dist/modes/interactive/components/config-selector.d.ts +4 -4
  299. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  300. package/dist/modes/interactive/components/config-selector.js +38 -11
  301. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  302. package/dist/modes/interactive/components/countdown-timer.d.ts +2 -2
  303. package/dist/modes/interactive/components/countdown-timer.d.ts.map +1 -1
  304. package/dist/modes/interactive/components/countdown-timer.js +2 -2
  305. package/dist/modes/interactive/components/countdown-timer.js.map +1 -1
  306. package/dist/modes/interactive/components/custom-editor.d.ts +1 -1
  307. package/dist/modes/interactive/components/custom-editor.d.ts.map +1 -1
  308. package/dist/modes/interactive/components/custom-editor.js.map +1 -1
  309. package/dist/modes/interactive/components/custom-message.d.ts +2 -2
  310. package/dist/modes/interactive/components/custom-message.d.ts.map +1 -1
  311. package/dist/modes/interactive/components/custom-message.js.map +1 -1
  312. package/dist/modes/interactive/components/diff.d.ts.map +1 -1
  313. package/dist/modes/interactive/components/diff.js.map +1 -1
  314. package/dist/modes/interactive/components/earendil-announcement.d.ts.map +1 -1
  315. package/dist/modes/interactive/components/earendil-announcement.js.map +1 -1
  316. package/dist/modes/interactive/components/extension-editor.d.ts.map +1 -1
  317. package/dist/modes/interactive/components/extension-editor.js +14 -6
  318. package/dist/modes/interactive/components/extension-editor.js.map +1 -1
  319. package/dist/modes/interactive/components/extension-input.d.ts.map +1 -1
  320. package/dist/modes/interactive/components/extension-input.js.map +1 -1
  321. package/dist/modes/interactive/components/extension-selector.d.ts +2 -0
  322. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  323. package/dist/modes/interactive/components/extension-selector.js +8 -3
  324. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  325. package/dist/modes/interactive/components/first-time-setup.d.ts +25 -0
  326. package/dist/modes/interactive/components/first-time-setup.d.ts.map +1 -0
  327. package/dist/modes/interactive/components/first-time-setup.js +103 -0
  328. package/dist/modes/interactive/components/first-time-setup.js.map +1 -0
  329. package/dist/modes/interactive/components/footer.d.ts +2 -1
  330. package/dist/modes/interactive/components/footer.d.ts.map +1 -1
  331. package/dist/modes/interactive/components/footer.js +23 -7
  332. package/dist/modes/interactive/components/footer.js.map +1 -1
  333. package/dist/modes/interactive/components/index.d.ts +33 -31
  334. package/dist/modes/interactive/components/index.d.ts.map +1 -1
  335. package/dist/modes/interactive/components/index.js +2 -0
  336. package/dist/modes/interactive/components/index.js.map +1 -1
  337. package/dist/modes/interactive/components/keybinding-hints.d.ts +5 -0
  338. package/dist/modes/interactive/components/keybinding-hints.d.ts.map +1 -1
  339. package/dist/modes/interactive/components/keybinding-hints.js +19 -5
  340. package/dist/modes/interactive/components/keybinding-hints.js.map +1 -1
  341. package/dist/modes/interactive/components/login-dialog.d.ts +12 -2
  342. package/dist/modes/interactive/components/login-dialog.d.ts.map +1 -1
  343. package/dist/modes/interactive/components/login-dialog.js +46 -11
  344. package/dist/modes/interactive/components/login-dialog.js.map +1 -1
  345. package/dist/modes/interactive/components/model-selector.d.ts +2 -2
  346. package/dist/modes/interactive/components/model-selector.d.ts.map +1 -1
  347. package/dist/modes/interactive/components/model-selector.js +8 -5
  348. package/dist/modes/interactive/components/model-selector.js.map +1 -1
  349. package/dist/modes/interactive/components/oauth-selector.d.ts +18 -6
  350. package/dist/modes/interactive/components/oauth-selector.d.ts.map +1 -1
  351. package/dist/modes/interactive/components/oauth-selector.js +93 -25
  352. package/dist/modes/interactive/components/oauth-selector.js.map +1 -1
  353. package/dist/modes/interactive/components/scoped-models-selector.d.ts +5 -12
  354. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +1 -1
  355. package/dist/modes/interactive/components/scoped-models-selector.js +45 -30
  356. package/dist/modes/interactive/components/scoped-models-selector.js.map +1 -1
  357. package/dist/modes/interactive/components/session-selector.d.ts +2 -1
  358. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  359. package/dist/modes/interactive/components/session-selector.js +20 -7
  360. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  361. package/dist/modes/interactive/components/settings-selector.d.ts +13 -0
  362. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  363. package/dist/modes/interactive/components/settings-selector.js +113 -4
  364. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  365. package/dist/modes/interactive/components/skill-invocation-message.d.ts +1 -1
  366. package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +1 -1
  367. package/dist/modes/interactive/components/skill-invocation-message.js.map +1 -1
  368. package/dist/modes/interactive/components/thinking-selector.d.ts.map +1 -1
  369. package/dist/modes/interactive/components/thinking-selector.js +1 -1
  370. package/dist/modes/interactive/components/thinking-selector.js.map +1 -1
  371. package/dist/modes/interactive/components/tool-execution.d.ts +6 -1
  372. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  373. package/dist/modes/interactive/components/tool-execution.js +57 -14
  374. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  375. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  376. package/dist/modes/interactive/components/tree-selector.js +18 -9
  377. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  378. package/dist/modes/interactive/components/trust-selector.d.ts +23 -0
  379. package/dist/modes/interactive/components/trust-selector.d.ts.map +1 -0
  380. package/dist/modes/interactive/components/trust-selector.js +91 -0
  381. package/dist/modes/interactive/components/trust-selector.js.map +1 -0
  382. package/dist/modes/interactive/components/user-message-selector.d.ts +2 -2
  383. package/dist/modes/interactive/components/user-message-selector.d.ts.map +1 -1
  384. package/dist/modes/interactive/components/user-message-selector.js +8 -7
  385. package/dist/modes/interactive/components/user-message-selector.js.map +1 -1
  386. package/dist/modes/interactive/components/user-message.d.ts +1 -0
  387. package/dist/modes/interactive/components/user-message.d.ts.map +1 -1
  388. package/dist/modes/interactive/components/user-message.js +8 -7
  389. package/dist/modes/interactive/components/user-message.js.map +1 -1
  390. package/dist/modes/interactive/interactive-mode.d.ts +68 -13
  391. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  392. package/dist/modes/interactive/interactive-mode.js +1100 -319
  393. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  394. package/dist/modes/interactive/theme/dark.json +5 -4
  395. package/dist/modes/interactive/theme/light.json +5 -4
  396. package/dist/modes/interactive/theme/theme.d.ts +22 -3
  397. package/dist/modes/interactive/theme/theme.d.ts.map +1 -1
  398. package/dist/modes/interactive/theme/theme.js +160 -105
  399. package/dist/modes/interactive/theme/theme.js.map +1 -1
  400. package/dist/modes/print-mode.d.ts.map +1 -1
  401. package/dist/modes/print-mode.js +40 -20
  402. package/dist/modes/print-mode.js.map +1 -1
  403. package/dist/modes/rpc/rpc-client.d.ts +11 -1
  404. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  405. package/dist/modes/rpc/rpc-client.js +73 -8
  406. package/dist/modes/rpc/rpc-client.js.map +1 -1
  407. package/dist/modes/rpc/rpc-mode.d.ts +2 -2
  408. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  409. package/dist/modes/rpc/rpc-mode.js +96 -30
  410. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  411. package/dist/modes/rpc/rpc-types.d.ts +16 -4
  412. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  413. package/dist/modes/rpc/rpc-types.js.map +1 -1
  414. package/dist/package-manager-cli.d.ts +6 -2
  415. package/dist/package-manager-cli.d.ts.map +1 -1
  416. package/dist/package-manager-cli.js +396 -21
  417. package/dist/package-manager-cli.js.map +1 -1
  418. package/dist/prompts/commands/map-codebase.md +14 -0
  419. package/dist/utils/ansi.d.ts +2 -0
  420. package/dist/utils/ansi.d.ts.map +1 -0
  421. package/dist/utils/ansi.js +52 -0
  422. package/dist/utils/ansi.js.map +1 -0
  423. package/dist/utils/changelog.d.ts +2 -1
  424. package/dist/utils/changelog.d.ts.map +1 -1
  425. package/dist/utils/changelog.js +78 -0
  426. package/dist/utils/changelog.js.map +1 -1
  427. package/dist/utils/child-process.d.ts +5 -1
  428. package/dist/utils/child-process.d.ts.map +1 -1
  429. package/dist/utils/child-process.js +10 -0
  430. package/dist/utils/child-process.js.map +1 -1
  431. package/dist/utils/clipboard-image.d.ts.map +1 -1
  432. package/dist/utils/clipboard-image.js +2 -2
  433. package/dist/utils/clipboard-image.js.map +1 -1
  434. package/dist/utils/clipboard-native.d.ts +3 -1
  435. package/dist/utils/clipboard-native.d.ts.map +1 -1
  436. package/dist/utils/clipboard-native.js +14 -8
  437. package/dist/utils/clipboard-native.js.map +1 -1
  438. package/dist/utils/clipboard.d.ts.map +1 -1
  439. package/dist/utils/clipboard.js +84 -45
  440. package/dist/utils/clipboard.js.map +1 -1
  441. package/dist/utils/deprecation.d.ts +4 -0
  442. package/dist/utils/deprecation.d.ts.map +1 -0
  443. package/dist/utils/deprecation.js +13 -0
  444. package/dist/utils/deprecation.js.map +1 -0
  445. package/dist/utils/exif-orientation.d.ts +1 -1
  446. package/dist/utils/exif-orientation.d.ts.map +1 -1
  447. package/dist/utils/exif-orientation.js.map +1 -1
  448. package/dist/utils/fs-watch.d.ts +5 -0
  449. package/dist/utils/fs-watch.d.ts.map +1 -0
  450. package/dist/utils/fs-watch.js +25 -0
  451. package/dist/utils/fs-watch.js.map +1 -0
  452. package/dist/utils/git.d.ts.map +1 -1
  453. package/dist/utils/git.js +54 -22
  454. package/dist/utils/git.js.map +1 -1
  455. package/dist/utils/html.d.ts +7 -0
  456. package/dist/utils/html.d.ts.map +1 -0
  457. package/dist/utils/html.js +40 -0
  458. package/dist/utils/html.js.map +1 -0
  459. package/dist/utils/image-convert.d.ts.map +1 -1
  460. package/dist/utils/image-convert.js.map +1 -1
  461. package/dist/utils/image-resize-core.d.ts +30 -0
  462. package/dist/utils/image-resize-core.d.ts.map +1 -0
  463. package/dist/utils/image-resize-core.js +124 -0
  464. package/dist/utils/image-resize-core.js.map +1 -0
  465. package/dist/utils/image-resize-worker.d.ts +2 -0
  466. package/dist/utils/image-resize-worker.d.ts.map +1 -0
  467. package/dist/utils/image-resize-worker.js +31 -0
  468. package/dist/utils/image-resize-worker.js.map +1 -0
  469. package/dist/utils/image-resize.d.ts +7 -27
  470. package/dist/utils/image-resize.d.ts.map +1 -1
  471. package/dist/utils/image-resize.js +75 -115
  472. package/dist/utils/image-resize.js.map +1 -1
  473. package/dist/utils/json.d.ts +3 -0
  474. package/dist/utils/json.d.ts.map +1 -0
  475. package/dist/utils/json.js +7 -0
  476. package/dist/utils/json.js.map +1 -0
  477. package/dist/utils/mime.d.ts +1 -0
  478. package/dist/utils/mime.d.ts.map +1 -1
  479. package/dist/utils/mime.js +59 -16
  480. package/dist/utils/mime.js.map +1 -1
  481. package/dist/utils/open-browser.d.ts +9 -0
  482. package/dist/utils/open-browser.d.ts.map +1 -0
  483. package/dist/utils/open-browser.js +22 -0
  484. package/dist/utils/open-browser.js.map +1 -0
  485. package/dist/utils/paths.d.ts +25 -1
  486. package/dist/utils/paths.d.ts.map +1 -1
  487. package/dist/utils/paths.js +75 -2
  488. package/dist/utils/paths.js.map +1 -1
  489. package/dist/utils/pi-user-agent.d.ts +2 -0
  490. package/dist/utils/pi-user-agent.d.ts.map +1 -0
  491. package/dist/utils/pi-user-agent.js +5 -0
  492. package/dist/utils/pi-user-agent.js.map +1 -0
  493. package/dist/utils/shell.d.ts +10 -6
  494. package/dist/utils/shell.d.ts.map +1 -1
  495. package/dist/utils/shell.js +35 -26
  496. package/dist/utils/shell.js.map +1 -1
  497. package/dist/utils/syntax-highlight.d.ts +12 -0
  498. package/dist/utils/syntax-highlight.d.ts.map +1 -0
  499. package/dist/utils/syntax-highlight.js +118 -0
  500. package/dist/utils/syntax-highlight.js.map +1 -0
  501. package/dist/utils/tools-manager.d.ts.map +1 -1
  502. package/dist/utils/tools-manager.js +86 -10
  503. package/dist/utils/tools-manager.js.map +1 -1
  504. package/dist/utils/version-check.d.ts +15 -0
  505. package/dist/utils/version-check.d.ts.map +1 -0
  506. package/dist/utils/version-check.js +82 -0
  507. package/dist/utils/version-check.js.map +1 -0
  508. package/dist/utils/windows-self-update.d.ts +3 -0
  509. package/dist/utils/windows-self-update.d.ts.map +1 -0
  510. package/dist/utils/windows-self-update.js +77 -0
  511. package/dist/utils/windows-self-update.js.map +1 -0
  512. package/docs/compaction.md +12 -12
  513. package/docs/containerization.md +111 -0
  514. package/docs/custom-provider.md +187 -47
  515. package/docs/development.md +5 -5
  516. package/docs/docs.json +156 -0
  517. package/docs/extensions.md +465 -71
  518. package/docs/index.md +82 -0
  519. package/docs/json.md +4 -4
  520. package/docs/keybindings.md +23 -1
  521. package/docs/models.md +119 -17
  522. package/docs/packages.md +17 -9
  523. package/docs/prompt-templates.md +30 -2
  524. package/docs/providers.md +83 -22
  525. package/docs/quickstart.md +165 -0
  526. package/docs/rpc.md +41 -10
  527. package/docs/sdk.md +68 -50
  528. package/docs/security.md +55 -0
  529. package/docs/{session.md → session-format.md} +11 -11
  530. package/docs/sessions.md +145 -0
  531. package/docs/settings.md +61 -11
  532. package/docs/skills.md +16 -17
  533. package/docs/terminal-setup.md +44 -2
  534. package/docs/termux.md +4 -4
  535. package/docs/themes.md +3 -3
  536. package/docs/tmux.md +4 -2
  537. package/docs/tui.md +44 -4
  538. package/docs/usage.md +305 -0
  539. package/examples/extensions/border-status-editor.ts +145 -0
  540. package/examples/extensions/built-in-tool-renderer.ts +3 -0
  541. package/examples/extensions/custom-header.ts +1 -1
  542. package/examples/extensions/custom-provider-anthropic/index.ts +1 -1
  543. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  544. package/examples/extensions/custom-provider-anthropic/package.json +2 -2
  545. package/examples/extensions/custom-provider-gitlab-duo/index.ts +55 -4
  546. package/examples/extensions/custom-provider-gitlab-duo/package.json +1 -1
  547. package/examples/extensions/custom-provider-gitlab-duo/test.ts +1 -1
  548. package/examples/extensions/doom-overlay/doom-component.ts +2 -2
  549. package/examples/extensions/doom-overlay/index.ts +1 -1
  550. package/examples/extensions/dynamic-resources/dynamic.json +1 -1
  551. package/examples/extensions/dynamic-tools.ts +2 -2
  552. package/examples/extensions/git-merge-and-resolve.ts +115 -0
  553. package/examples/extensions/github-issue-autocomplete.ts +185 -0
  554. package/examples/extensions/gondolin/index.ts +531 -0
  555. package/examples/extensions/gondolin/package-lock.json +185 -0
  556. package/examples/extensions/gondolin/package.json +19 -0
  557. package/examples/extensions/handoff.ts +50 -12
  558. package/examples/extensions/input-transform-streaming.ts +39 -0
  559. package/examples/extensions/interactive-shell.ts +1 -1
  560. package/examples/extensions/notify.ts +2 -9
  561. package/examples/extensions/overlay-qa-tests.ts +240 -138
  562. package/examples/extensions/overlay-test.ts +7 -4
  563. package/examples/extensions/plan-mode/utils.ts +1 -1
  564. package/examples/extensions/preset.ts +36 -3
  565. package/examples/extensions/project-trust.ts +64 -0
  566. package/examples/extensions/prompt-customizer.ts +97 -0
  567. package/examples/extensions/provider-payload.ts +4 -0
  568. package/examples/extensions/qna.ts +1 -1
  569. package/examples/extensions/question.ts +2 -2
  570. package/examples/extensions/questionnaire.ts +2 -2
  571. package/examples/extensions/reload-runtime.ts +1 -1
  572. package/examples/extensions/sandbox/index.ts +4 -4
  573. package/examples/extensions/sandbox/package-lock.json +5 -5
  574. package/examples/extensions/sandbox/package.json +2 -2
  575. package/examples/extensions/shutdown-command.ts +1 -1
  576. package/examples/extensions/snake.ts +1 -1
  577. package/examples/extensions/space-invaders.ts +1 -1
  578. package/examples/extensions/structured-output.ts +65 -0
  579. package/examples/extensions/subagent/index.ts +51 -28
  580. package/examples/extensions/summarize.ts +1 -1
  581. package/examples/extensions/tic-tac-toe.ts +1008 -0
  582. package/examples/extensions/titlebar-spinner.ts +2 -2
  583. package/examples/extensions/todo.ts +2 -2
  584. package/examples/extensions/tool-override.ts +1 -1
  585. package/examples/extensions/tools.ts +5 -0
  586. package/examples/extensions/truncated-tool.ts +1 -1
  587. package/examples/extensions/with-deps/index.ts +1 -1
  588. package/examples/extensions/with-deps/package-lock.json +2 -2
  589. package/examples/extensions/with-deps/package.json +3 -3
  590. package/examples/extensions/working-indicator.ts +123 -0
  591. package/examples/extensions/working-message-test.ts +25 -0
  592. package/examples/sdk/01-minimal.ts +14 -10
  593. package/examples/sdk/02-custom-model.ts +12 -8
  594. package/examples/sdk/03-custom-prompt.ts +32 -17
  595. package/examples/sdk/04-skills.ts +5 -2
  596. package/examples/sdk/05-tools.ts +23 -31
  597. package/examples/sdk/06-extensions.ts +14 -8
  598. package/examples/sdk/07-context-files.ts +5 -3
  599. package/examples/sdk/08-prompt-templates.ts +5 -2
  600. package/examples/sdk/09-api-keys-and-oauth.ts +8 -4
  601. package/examples/sdk/10-settings.ts +8 -6
  602. package/examples/sdk/11-sessions.ts +4 -0
  603. package/examples/sdk/12-full-control.ts +13 -17
  604. package/package.json +13 -6
  605. package/prompts/commands/map-codebase.md +14 -0
package/docs/sdk.md CHANGED
@@ -54,7 +54,7 @@ The main factory function for a single `AgentSession`.
54
54
  `createAgentSession()` uses a `ResourceLoader` to supply extensions, skills, prompt templates, themes, and context files. If you do not provide one, it uses `DefaultResourceLoader` with standard discovery.
55
55
 
56
56
  ```typescript
57
- import { createAgentSession } from "@draht/coding-agent";
57
+ import { createAgentSession, SessionManager } from "@draht/coding-agent";
58
58
 
59
59
  // Minimal: defaults with DefaultResourceLoader
60
60
  const { session } = await createAgentSession();
@@ -62,7 +62,7 @@ const { session } = await createAgentSession();
62
62
  // Custom: override specific options
63
63
  const { session } = await createAgentSession({
64
64
  model: myModel,
65
- tools: [readTool, bashTool],
65
+ tools: ["read", "bash"],
66
66
  sessionManager: SessionManager.inMemory(),
67
67
  });
68
68
  ```
@@ -159,6 +159,7 @@ const runtime = await createAgentSessionRuntime(createRuntime, {
159
159
  - `newSession()`
160
160
  - `switchSession()`
161
161
  - `fork()`
162
+ - clone flows via `fork(entryId, { position: "at" })`
162
163
  - `importFromJsonl()`
163
164
 
164
165
  Important behavior:
@@ -182,6 +183,25 @@ unsubscribe = session.subscribe(() => {});
182
183
 
183
184
  ### Prompting and Message Queueing
184
185
 
186
+ `PromptOptions` controls prompt expansion, queueing behavior while streaming, and prompt preflight notifications:
187
+
188
+ ```typescript
189
+ interface PromptOptions {
190
+ expandPromptTemplates?: boolean;
191
+ images?: ImageContent[];
192
+ streamingBehavior?: "steer" | "followUp";
193
+ source?: InputSource;
194
+ preflightResult?: (success: boolean) => void;
195
+ }
196
+ ```
197
+
198
+ `preflightResult` is called once per `prompt()` invocation:
199
+
200
+ - `true` when the prompt was accepted, queued, or handled immediately
201
+ - `false` when prompt preflight rejected before acceptance
202
+
203
+ It fires before `prompt()` resolves. `prompt()` still resolves only after the full accepted run finishes, including retries. Failures after acceptance are reported through the normal event and message stream, not through `preflightResult(false)`.
204
+
185
205
  The `prompt()` method handles prompt templates, extension commands, and message sending:
186
206
 
187
207
  ```typescript
@@ -200,8 +220,10 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo
200
220
 
201
221
  **Behavior:**
202
222
  - **Extension commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `pi.sendMessage()`.
203
- - **File-based prompt templates** (from `.md` files): Expanded to their content before sending/queueing.
223
+ - **File-based prompt templates** (from `.md` files): Expanded to their content before sending or queueing.
204
224
  - **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
225
+ - **`preflightResult(true)`**: Means the prompt was accepted, queued, or handled immediately.
226
+ - **`preflightResult(false)`**: Means preflight rejected before acceptance.
205
227
 
206
228
  For explicit queueing during streaming:
207
229
 
@@ -444,70 +466,64 @@ const { session } = await createAgentSession({ resourceLoader: loader });
444
466
 
445
467
  ### Tools
446
468
 
469
+ Specify which built-in tools to enable:
470
+
471
+ - Built-in tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
472
+ - Default built-ins: `read`, `bash`, `edit`, `write`
473
+ - `noTools: "all"` disables all tools
474
+ - `noTools: "builtin"` disables default built-ins while keeping extension and custom tools enabled
475
+ - `excludeTools` disables specific built-in, extension, or custom tool names after any `tools` allowlist is applied
476
+
477
+ The `edit` tool returns `details.diff` for Pi's TUI display and `details.patch` as a standard unified patch for SDK consumers.
478
+
447
479
  ```typescript
448
- import {
449
- codingTools, // read, bash, edit, write (default)
450
- readOnlyTools, // read, grep, find, ls
451
- readTool, bashTool, editTool, writeTool,
452
- grepTool, findTool, lsTool,
453
- } from "@draht/coding-agent";
480
+ import { createAgentSession } from "@draht/coding-agent";
454
481
 
455
- // Use built-in tool set
482
+ // Read-only mode
456
483
  const { session } = await createAgentSession({
457
- tools: readOnlyTools,
484
+ tools: ["read", "grep", "find", "ls"],
458
485
  });
459
486
 
460
487
  // Pick specific tools
461
488
  const { session } = await createAgentSession({
462
- tools: [readTool, bashTool, grepTool],
489
+ tools: ["read", "bash", "grep"],
490
+ });
491
+
492
+ // Disable one tool while keeping the rest available
493
+ const { session } = await createAgentSession({
494
+ excludeTools: ["ask_question"],
463
495
  });
464
496
  ```
465
497
 
466
498
  #### Tools with Custom cwd
467
499
 
468
- **Important:** The pre-built tool instances (`readTool`, `bashTool`, etc.) use `process.cwd()` for path resolution. When you specify a custom `cwd` AND provide explicit `tools`, you must use the tool factory functions to ensure paths resolve correctly:
500
+ When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd.
469
501
 
470
502
  ```typescript
471
- import {
472
- createCodingTools, // Creates [read, bash, edit, write] for specific cwd
473
- createReadOnlyTools, // Creates [read, grep, find, ls] for specific cwd
474
- createReadTool,
475
- createBashTool,
476
- createEditTool,
477
- createWriteTool,
478
- createGrepTool,
479
- createFindTool,
480
- createLsTool,
481
- } from "@draht/coding-agent";
503
+ import { createAgentSession, SessionManager } from "@draht/coding-agent";
482
504
 
483
505
  const cwd = "/path/to/project";
484
506
 
485
- // Use factory for tool sets
507
+ // Use default tools for custom cwd
486
508
  const { session } = await createAgentSession({
487
509
  cwd,
488
- tools: createCodingTools(cwd), // Tools resolve paths relative to cwd
510
+ sessionManager: SessionManager.inMemory(cwd),
489
511
  });
490
512
 
491
- // Or pick specific tools
513
+ // Or pick specific tools for custom cwd
492
514
  const { session } = await createAgentSession({
493
515
  cwd,
494
- tools: [createReadTool(cwd), createBashTool(cwd), createGrepTool(cwd)],
516
+ tools: ["read", "bash", "grep"],
517
+ sessionManager: SessionManager.inMemory(cwd),
495
518
  });
496
519
  ```
497
520
 
498
- **When you don't need factories:**
499
- - If you omit `tools`, pi automatically creates them with the correct `cwd`
500
- - If you use `process.cwd()` as your `cwd`, the pre-built instances work fine
501
-
502
- **When you must use factories:**
503
- - When you specify both `cwd` (different from `process.cwd()`) AND `tools`
504
-
505
521
  > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
506
522
 
507
523
  ### Custom Tools
508
524
 
509
525
  ```typescript
510
- import { Type } from "@sinclair/typebox";
526
+ import { Type } from "typebox";
511
527
  import { createAgentSession, defineTool } from "@draht/coding-agent";
512
528
 
513
529
  // Inline custom tool
@@ -534,6 +550,8 @@ Use `defineTool()` for standalone definitions and arrays like `customTools: [myT
534
550
 
535
551
  Custom tools passed via `customTools` are combined with extension-registered tools. Extensions loaded by the ResourceLoader can also register tools via `pi.registerTool()`.
536
552
 
553
+ If you pass `tools`, include each custom or extension tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`.
554
+
537
555
  > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
538
556
 
539
557
  ### Extensions
@@ -697,7 +715,7 @@ const { session: opened } = await createAgentSession({
697
715
  const currentProjectSessions = await SessionManager.list(process.cwd());
698
716
  const allSessions = await SessionManager.listAll(process.cwd());
699
717
 
700
- // Session replacement API for /new, /resume, /fork, and import flows.
718
+ // Session replacement API for /new, /resume, /fork, /clone, and import flows.
701
719
  const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
702
720
  const services = await createAgentSessionServices({ cwd });
703
721
  return {
@@ -723,8 +741,11 @@ await runtime.newSession();
723
741
  // Replace the active session with another saved session
724
742
  await runtime.switchSession("/path/to/session.jsonl");
725
743
 
726
- // Replace the active session with a fork from a specific entry
744
+ // Replace the active session with a fork from a specific user entry
727
745
  await runtime.fork("entry-id");
746
+
747
+ // Clone the active path through a specific entry
748
+ await runtime.fork("entry-id", { position: "at" });
728
749
  ```
729
750
 
730
751
  **SessionManager tree API:**
@@ -754,7 +775,7 @@ sm.branchWithSummary(id, "Summary..."); // Branch with context summary
754
775
  sm.createBranchedSession(leafId); // Extract path to new file
755
776
  ```
756
777
 
757
- > See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [docs/session.md](session.md)
778
+ > See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [Session Format](session-format.md)
758
779
 
759
780
  ### Settings Management
760
781
 
@@ -857,15 +878,13 @@ interface LoadExtensionsResult {
857
878
 
858
879
  ```typescript
859
880
  import { getModel } from "@draht/ai";
860
- import { Type } from "@sinclair/typebox";
881
+ import { Type } from "typebox";
861
882
  import {
862
883
  AuthStorage,
863
- bashTool,
864
884
  createAgentSession,
865
885
  DefaultResourceLoader,
866
886
  defineTool,
867
887
  ModelRegistry,
868
- readTool,
869
888
  SessionManager,
870
889
  SettingsManager,
871
890
  } from "@draht/coding-agent";
@@ -919,7 +938,7 @@ const { session } = await createAgentSession({
919
938
  authStorage,
920
939
  modelRegistry,
921
940
 
922
- tools: [readTool, bashTool],
941
+ tools: ["read", "bash", "status"],
923
942
  customTools: [statusTool],
924
943
  resourceLoader: loader,
925
944
 
@@ -1093,18 +1112,17 @@ createEventBus
1093
1112
 
1094
1113
  // Helpers
1095
1114
  defineTool
1115
+ getAgentDir
1116
+ getPackageDir
1117
+ getReadmePath
1118
+ getDocsPath
1119
+ getExamplesPath
1096
1120
 
1097
1121
  // Session management
1098
1122
  SessionManager
1099
1123
  SettingsManager
1100
1124
 
1101
- // Built-in tools (use process.cwd())
1102
- codingTools
1103
- readOnlyTools
1104
- readTool, bashTool, editTool, writeTool
1105
- grepTool, findTool, lsTool
1106
-
1107
- // Tool factories (for custom cwd)
1125
+ // Tool factories
1108
1126
  createCodingTools
1109
1127
  createReadOnlyTools
1110
1128
  createReadTool, createBashTool, createEditTool, createWriteTool
@@ -0,0 +1,55 @@
1
+ # Security
2
+
3
+ Pi is a local coding agent. It runs with the permissions of the user account that starts it, and it treats files writable by that user as inside the same local trust boundary.
4
+
5
+ ## Project Trust
6
+
7
+ Project trust controls whether pi loads project-local settings, resources, packages, and extensions. It is not a sandbox and it does not restrict what the model can ask tools to do after you start working in a directory.
8
+
9
+ Pi considers a project to have trust inputs when it finds any of these from the current working directory:
10
+
11
+ - `.pi/` in the current directory
12
+ - `.agents/skills` in the current directory or an ancestor directory
13
+
14
+ When an interactive session starts in a project with configs in `.pi` or `.agents/skills` and no saved decision for the current directory or a parent directory, pi follows `defaultProjectTrust` from global settings. The default value is `"ask"`, which asks whether to trust the project when UI is available. Saved decisions are stored by canonical directory in `~/.pi/agent/trust.json`, and the closest saved decision on the current or parent path applies before the global default.
15
+
16
+ Trusting a project allows pi to load trust-gated project inputs, including:
17
+
18
+ - `.pi/settings.json`
19
+ - `.pi` resources such as extensions, skills, prompt templates, themes, and system prompt files
20
+ - missing project packages configured through project settings
21
+ - project-local extensions and project package-managed extensions
22
+
23
+ Declining trust skips protected resources. `AGENTS.md` and `CLAUDE.md` context files are loaded regardless of project trust unless context loading is disabled. Before trust is resolved, pi only loads context files, user/global extensions, and CLI `-e` extensions. User/global and CLI extensions can handle the `project_trust` event; the first extension that returns a yes/no decision owns the decision.
24
+
25
+ Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, `defaultProjectTrust: "ask"` and `"never"` ignore such resources, while `"always"` trusts them. Use `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
26
+
27
+ ## No Built-in Sandbox
28
+
29
+ Pi does not include a built-in sandbox. Built-in tools can read files, write files, edit files, and run shell commands with the permissions of the pi process. Extensions are TypeScript modules that run with the same permissions. Package installs, shell commands, language servers, test commands, and other developer tools behave as ordinary local processes.
30
+
31
+ This is intentional. Pi is designed to operate on local source trees, invoke project toolchains, and integrate with the user's existing development environment. A partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, package managers, credentials, and extension code. Real isolation needs to come from the operating system or a virtualization/container boundary.
32
+
33
+ Project trust is only an input-loading guard. It prevents a repository from silently changing pi's settings or extensions before you approve it. It does not make untrusted code, untrusted prompts, or untrusted model output safe. Prompt injection from repository files, comments, documentation, context files, or build output is expected local-agent risk and cannot be reliably prevented by pi.
34
+
35
+ ## Running Untrusted or Unmonitored Work
36
+
37
+ For untrusted repositories, generated code you do not intend to monitor closely, or unattended automation, run pi in a contained environment. Use a container, VM, micro-VM, remote sandbox, or policy-controlled sandbox with only the files and credentials required for the task.
38
+
39
+ Common patterns are documented in [Containerization](containerization.md):
40
+
41
+ - run the whole `pi` process inside OpenShell or Docker
42
+ - run host pi while routing built-in tool execution into a Gondolin micro-VM
43
+ - mount only the workspace paths the agent should access
44
+ - avoid mounting host `~/.pi/agent` unless the container should access host sessions, settings, and credentials
45
+ - pass the minimum required API keys or use short-lived credentials
46
+ - restrict network access when the task does not need it
47
+ - review diffs and outputs before copying results back to trusted systems
48
+
49
+ If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
50
+
51
+ ## Reporting Security Issues
52
+
53
+ To report a security issue, follow the repository [Security Policy](https://github.com/earendil-works/pi-mono/blob/main/SECURITY.md). Do not open a public issue for security-sensitive reports.
54
+
55
+ Expected local-agent behavior, lack of a built-in sandbox, prompt injection from untrusted content, and behavior of user-installed extensions or skills are generally outside the security boundary unless the report demonstrates a real privilege-boundary bypass or shows how pi grants access that the local user did not already have.
@@ -5,14 +5,14 @@ Sessions are stored as JSONL (JSON Lines) files. Each line is a JSON object with
5
5
  ## File Location
6
6
 
7
7
  ```
8
- ~/.draht/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
8
+ ~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
9
9
  ```
10
10
 
11
11
  Where `<path>` is the working directory with `/` replaced by `-`.
12
12
 
13
13
  ## Deleting Sessions
14
14
 
15
- Sessions can be removed by deleting their `.jsonl` files under `~/.draht/agent/sessions/`.
15
+ Sessions can be removed by deleting their `.jsonl` files under `~/.pi/agent/sessions/`.
16
16
 
17
17
  Pi also supports deleting sessions interactively from `/resume` (select a session and press `Ctrl+D`, then confirm). When available, pi uses the `trash` CLI to avoid permanent deletion.
18
18
 
@@ -28,11 +28,11 @@ Existing sessions are automatically migrated to the current version (v3) when lo
28
28
 
29
29
  ## Source Files
30
30
 
31
- Source on GitHub ([draht-mono](https://github.com/draht-dev/draht)):
32
- - [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
33
- - [`packages/coding-agent/src/core/messages.ts`](https://github.com/draht-dev/draht/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
34
- - [`packages/ai/src/types.ts`](https://github.com/draht-dev/draht/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
35
- - [`packages/agent/src/types.ts`](https://github.com/draht-dev/draht/blob/main/packages/agent/src/types.ts) - AgentMessage union type
31
+ Source on GitHub ([pi-mono](https://github.com/earendil-works/pi-mono)):
32
+ - [`packages/coding-agent/src/core/session-manager.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/session-manager.ts) - Session entry types and SessionManager
33
+ - [`packages/coding-agent/src/core/messages.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/src/core/messages.ts) - Extended message types (BashExecutionMessage, CustomMessage, etc.)
34
+ - [`packages/ai/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/types.ts) - Base message types (UserMessage, AssistantMessage, ToolResultMessage)
35
+ - [`packages/agent/src/types.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/agent/src/types.ts) - AgentMessage union type
36
36
 
37
37
  For TypeScript definitions in your project, inspect `node_modules/@draht/coding-agent/dist/` and `node_modules/@draht/ai/dist/`.
38
38
 
@@ -69,7 +69,7 @@ interface ToolCall {
69
69
  }
70
70
  ```
71
71
 
72
- ### Base Message Types (from draht-ai)
72
+ ### Base Message Types (from pi-ai)
73
73
 
74
74
  ```typescript
75
75
  interface UserMessage {
@@ -116,7 +116,7 @@ interface Usage {
116
116
  }
117
117
  ```
118
118
 
119
- ### Extended Message Types (from draht coding agent)
119
+ ### Extended Message Types (from pi-coding-agent)
120
120
 
121
121
  ```typescript
122
122
  interface BashExecutionMessage {
@@ -191,7 +191,7 @@ First line of the file. Metadata only, not part of the tree (no `id`/`parentId`)
191
191
  {"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
192
192
  ```
193
193
 
194
- For sessions with a parent (created via `/fork` or `newSession({ parentSession })`):
194
+ For sessions with a parent (created via `/fork`, `/clone`, or `newSession({ parentSession })`):
195
195
 
196
196
  ```json
197
197
  {"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
@@ -282,7 +282,7 @@ Set `label` to `undefined` to clear a label.
282
282
 
283
283
  ### SessionInfoEntry
284
284
 
285
- Session metadata (e.g., user-defined display name). Set via `/name` command or `pi.setSessionName()` in extensions.
285
+ Session metadata (e.g., user-defined display name). Set via `/name`, `--name` / `-n`, or `pi.setSessionName()` in extensions.
286
286
 
287
287
  ```json
288
288
  {"type":"session_info","id":"k1l2m3n4","parentId":"j0k1l2m3","timestamp":"2024-12-03T14:35:00.000Z","name":"Refactor auth module"}
@@ -0,0 +1,145 @@
1
+ # Sessions
2
+
3
+ Pi saves conversations as sessions so you can continue work, branch from earlier turns, and revisit previous paths.
4
+
5
+ ## Session Storage
6
+
7
+ Sessions auto-save to `~/.pi/agent/sessions/`, organized by working directory. Each session is a JSONL file with a tree structure.
8
+
9
+ ```bash
10
+ pi -c # Continue most recent session
11
+ pi -r # Browse and select from past sessions
12
+ pi --no-session # Ephemeral mode; do not save
13
+ pi --name "my task" # Set session display name at startup
14
+ pi --session <path|id> # Use a specific session file or partial session ID
15
+ pi --fork <path|id> # Fork a session file or partial session ID into a new session
16
+ ```
17
+
18
+ Use `/session` in interactive mode to see the current session file, session ID, message count, tokens, and cost.
19
+
20
+ For the JSONL file format and SessionManager API, see [Session Format](session-format.md).
21
+
22
+ ## Session Commands
23
+
24
+ | Command | Description |
25
+ |---------|-------------|
26
+ | `/resume` | Browse and select previous sessions |
27
+ | `/new` | Start a new session |
28
+ | `/name <name>` | Set the current session display name |
29
+ | `/session` | Show session info |
30
+ | `/tree` | Navigate the current session tree |
31
+ | `/fork` | Create a new session from a previous user message |
32
+ | `/clone` | Duplicate the current active branch into a new session |
33
+ | `/compact [prompt]` | Summarize older context; see [Compaction](compaction.md) |
34
+ | `/export [file]` | Export session to HTML |
35
+ | `/share` | Upload as private GitHub gist with shareable HTML link |
36
+
37
+ ## Resuming and Deleting Sessions
38
+
39
+ `/resume` opens an interactive session picker for the current project. `pi -r` opens the same picker at startup.
40
+
41
+ In the picker you can:
42
+
43
+ - search by typing
44
+ - toggle path display with Ctrl+P
45
+ - toggle sort mode with Ctrl+S
46
+ - filter to named sessions with Ctrl+N
47
+ - rename with Ctrl+R
48
+ - delete with Ctrl+D, then confirm
49
+
50
+ When available, pi uses the `trash` CLI for deletion instead of permanently removing files.
51
+
52
+ ## Naming Sessions
53
+
54
+ Use `/name <name>` to set a human-readable session name:
55
+
56
+ ```text
57
+ /name Refactor auth module
58
+ ```
59
+
60
+ Set the name at startup with `--name` or `-n`:
61
+
62
+ ```bash
63
+ pi --name "Refactor auth module"
64
+ pi --name "CI audit" -p "Review this build failure"
65
+ ```
66
+
67
+ Named sessions are easier to find in `/resume` and `pi -r`.
68
+
69
+ ## Branching with `/tree`
70
+
71
+ Sessions are stored as trees. Every entry has an `id` and `parentId`, and the current position is the active leaf. `/tree` lets you jump to any previous point and continue from there without creating a new file.
72
+
73
+ <p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>
74
+
75
+ Example shape:
76
+
77
+ ```text
78
+ ├─ user: "Hello, can you help..."
79
+ │ └─ assistant: "Of course! I can..."
80
+ │ ├─ user: "Let's try approach A..."
81
+ │ │ └─ assistant: "For approach A..."
82
+ │ │ └─ user: "That worked..." ← active
83
+ │ └─ user: "Actually, approach B..."
84
+ │ └─ assistant: "For approach B..."
85
+ ```
86
+
87
+ ### Tree Controls
88
+
89
+ | Key | Action |
90
+ |-----|--------|
91
+ | ↑/↓ | Navigate visible entries |
92
+ | ←/→ | Page up/down |
93
+ | Ctrl+←/Ctrl+→ or Alt+←/Alt+→ | Fold/unfold or jump between branch segments |
94
+ | Shift+L | Set or clear a label on the selected entry |
95
+ | Shift+T | Toggle label timestamps |
96
+ | Enter | Select entry |
97
+ | Escape/Ctrl+C | Cancel |
98
+ | Ctrl+O | Cycle filter mode |
99
+
100
+ Filter modes are: default, no-tools, user-only, labeled-only, and all. Configure the default with `treeFilterMode` in [Settings](settings.md).
101
+
102
+ ### Selection Behavior
103
+
104
+ Selecting a user or custom message:
105
+
106
+ 1. Moves the leaf to the selected message's parent.
107
+ 2. Places the selected message text in the editor.
108
+ 3. Lets you edit and resubmit, creating a new branch.
109
+
110
+ Selecting an assistant, tool, compaction, or other non-user entry:
111
+
112
+ 1. Moves the leaf to that entry.
113
+ 2. Leaves the editor empty.
114
+ 3. Lets you continue from that point.
115
+
116
+ Selecting the root user message resets the leaf to an empty conversation and places the original prompt in the editor.
117
+
118
+ ## `/tree`, `/fork`, and `/clone`
119
+
120
+ | Feature | `/tree` | `/fork` | `/clone` |
121
+ |---------|---------|---------|----------|
122
+ | Output | Same session file | New session file | New session file |
123
+ | View | Full tree | User-message selector | Current active branch |
124
+ | Typical use | Explore alternatives in place | Start a new session from an earlier prompt | Duplicate current work before continuing |
125
+ | Summary | Optional branch summary | None | None |
126
+
127
+ Use `/tree` when you want to keep alternatives together. Use `/fork` or `/clone` when you want a separate session file.
128
+
129
+ ## Branch Summaries
130
+
131
+ When `/tree` switches away from one branch to another, pi can summarize the abandoned branch and attach that summary at the new position. This preserves important context from the path you left without replaying the whole branch.
132
+
133
+ When prompted, choose one of:
134
+
135
+ 1. no summary
136
+ 2. summarize with the default prompt
137
+ 3. summarize with custom focus instructions
138
+
139
+ See [Compaction](compaction.md) for branch summarization internals and extension hooks.
140
+
141
+ ## Session Format
142
+
143
+ Session files are JSONL and contain message entries, model changes, thinking-level changes, labels, compactions, branch summaries, and extension entries.
144
+
145
+ For parsers, extensions, SDK usage, and the full SessionManager API, see [Session Format](session-format.md).
package/docs/settings.md CHANGED
@@ -9,6 +9,18 @@ Pi uses JSON settings files with project settings overriding global settings.
9
9
 
10
10
  Edit directly or use `/settings` for common options.
11
11
 
12
+ ## Project Trust
13
+
14
+ On interactive startup, pi asks before trusting a project folder that contains trust-gated project inputs and has no saved decision for the folder or a parent folder in `~/.pi/agent/trust.json`. Trusting a project allows pi to load `.pi/settings.json` and `.pi` resources, install missing project packages, and execute project extensions.
15
+
16
+ Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore trust-gated project inputs, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
17
+
18
+ If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.pi/agent/settings.json`, or change it with `/settings`.
19
+
20
+ `pi config` and package commands use the same project trust flow. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
21
+
22
+ Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.pi/agent/trust.json` only; the current session is not reloaded, so restart pi for changes to take effect.
23
+
12
24
  ## All Settings
13
25
 
14
26
  ### Model & Thinking
@@ -40,12 +52,36 @@ Edit directly or use `/settings` for common options.
40
52
  |---------|------|---------|-------------|
41
53
  | `theme` | string | `"dark"` | Theme name (`"dark"`, `"light"`, or custom) |
42
54
  | `quietStartup` | boolean | `false` | Hide startup header |
55
+ | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
43
56
  | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
57
+ | `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
58
+ | `enableAnalytics` | boolean | `false` | Opt-in analytics data sharing. Currently only asked for during the experimental first-time setup (`PI_EXPERIMENTAL=1`) |
59
+ | `trackingId` | string | - | Analytics tracking identifier, generated when `enableAnalytics` is turned on |
44
60
  | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
45
61
  | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
46
62
  | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |
47
63
  | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
48
- | `showHardwareCursor` | boolean | `false` | Show terminal cursor |
64
+ | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
65
+
66
+ ### Telemetry and update checks
67
+
68
+ `enableInstallTelemetry` only controls the anonymous install/update ping to `https://pi.dev/api/report-install`. Opting out of telemetry does not disable update checks; Pi can still fetch `https://pi.dev/api/latest-version` to look for the latest version.
69
+
70
+ Set `PI_SKIP_VERSION_CHECK=1` to disable the Pi version update check. Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
71
+
72
+ ### Warnings
73
+
74
+ | Setting | Type | Default | Description |
75
+ |---------|------|---------|-------------|
76
+ | `warnings.anthropicExtraUsage` | boolean | `true` | Show a warning when Anthropic subscription auth may use paid extra usage |
77
+
78
+ ```json
79
+ {
80
+ "warnings": {
81
+ "anthropicExtraUsage": false
82
+ }
83
+ }
84
+ ```
49
85
 
50
86
  ### Compaction
51
87
 
@@ -76,12 +112,16 @@ Edit directly or use `/settings` for common options.
76
112
 
77
113
  | Setting | Type | Default | Description |
78
114
  |---------|------|---------|-------------|
79
- | `retry.enabled` | boolean | `true` | Enable automatic retry on transient errors |
80
- | `retry.maxRetries` | number | `3` | Maximum retry attempts |
81
- | `retry.baseDelayMs` | number | `2000` | Base delay for exponential backoff (2s, 4s, 8s) |
82
- | `retry.maxDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
115
+ | `retry.enabled` | boolean | `true` | Enable automatic agent-level retry on transient errors |
116
+ | `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts |
117
+ | `retry.baseDelayMs` | number | `2000` | Base delay for agent-level exponential backoff (2s, 4s, 8s) |
118
+ | `retry.provider.timeoutMs` | number | SDK default | Provider/SDK request timeout in milliseconds |
119
+ | `retry.provider.maxRetries` | number | `0` | Provider/SDK retry attempts |
120
+ | `retry.provider.maxRetryDelayMs` | number | `60000` | Max server-requested delay before failing (60s) |
121
+
122
+ When a provider requests a retry delay longer than `retry.provider.maxRetryDelayMs` (e.g., Google's "quota will reset after 5h"), the request fails immediately with an informative error instead of waiting silently. Set to `0` to disable the cap.
83
123
 
84
- When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's "quota will reset after 5h"), the request fails immediately with an informative error instead of waiting silently. Set to `0` to disable the cap.
124
+ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explicitly needed. Setting it above `0` can make SDK/provider retries handle out-of-usage-limit errors before Pi sees them, which may block the agent until the provider quota resets in some circumstances.
85
125
 
86
126
  ```json
87
127
  {
@@ -89,7 +129,11 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
89
129
  "enabled": true,
90
130
  "maxRetries": 3,
91
131
  "baseDelayMs": 2000,
92
- "maxDelayMs": 60000
132
+ "provider": {
133
+ "timeoutMs": 3600000,
134
+ "maxRetries": 0,
135
+ "maxRetryDelayMs": 60000
136
+ }
93
137
  }
94
138
  }
95
139
  ```
@@ -100,13 +144,16 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
100
144
  |---------|------|---------|-------------|
101
145
  | `steeringMode` | string | `"one-at-a-time"` | How steering messages are sent: `"all"` or `"one-at-a-time"` |
102
146
  | `followUpMode` | string | `"one-at-a-time"` | How follow-up messages are sent: `"all"` or `"one-at-a-time"` |
103
- | `transport` | string | `"sse"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, or `"auto"` |
147
+ | `transport` | string | `"auto"` | Preferred transport for providers that support multiple transports: `"sse"`, `"websocket"`, `"websocket-cached"`, or `"auto"` |
148
+ | `httpIdleTimeoutMs` | number | `300000` | HTTP header/body idle timeout in milliseconds, also used by providers with explicit stream idle timeouts. Set to `0` to disable. |
149
+ | `websocketConnectTimeoutMs` | number | `15000` | WebSocket connect/open handshake timeout in milliseconds for providers that support WebSocket transports. Set to `0` to disable. |
104
150
 
105
151
  ### Terminal & Images
106
152
 
107
153
  | Setting | Type | Default | Description |
108
154
  |---------|------|---------|-------------|
109
155
  | `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
156
+ | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
110
157
  | `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
111
158
  | `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max |
112
159
  | `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
@@ -125,19 +172,19 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
125
172
  }
126
173
  ```
127
174
 
128
- `npmCommand` is used for all npm package-manager operations, including `npm root -g`, installs, uninstalls, and `npm install` inside git packages. Use argv-style entries exactly as the process should be launched.
175
+ `npmCommand` is used for all npm package-manager operations, including installs, uninstalls, and dependency installs inside git packages. User-scoped npm packages install under `~/.pi/agent/npm/`; project-scoped npm packages install under `.pi/npm/`. Use argv-style entries exactly as the process should be launched. When `npmCommand` is configured, git package dependency installs use plain `install` to avoid npm-specific flags in wrappers or alternate package managers.
129
176
 
130
177
  ### Sessions
131
178
 
132
179
  | Setting | Type | Default | Description |
133
180
  |---------|------|---------|-------------|
134
- | `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths. |
181
+ | `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths, plus `~`. |
135
182
 
136
183
  ```json
137
184
  { "sessionDir": ".pi/sessions" }
138
185
  ```
139
186
 
140
- When multiple sources specify a session directory, `--session-dir` CLI flag takes precedence over `sessionDir` in settings.json.
187
+ When multiple sources specify a session directory, precedence is `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, then `sessionDir` in settings.json.
141
188
 
142
189
  ### Model Cycling
143
190
 
@@ -218,6 +265,9 @@ See [packages.md](packages.md) for package management details.
218
265
  "maxRetries": 3
219
266
  },
220
267
  "enabledModels": ["claude-*", "gpt-4o"],
268
+ "warnings": {
269
+ "anthropicExtraUsage": true
270
+ },
221
271
  "packages": ["pi-skills"]
222
272
  }
223
273
  ```