@punch-bot/cli 0.85.1 → 1.2.0

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 (1103) hide show
  1. package/CHANGELOG.md +572 -3
  2. package/README.md +82 -174
  3. package/dist/bun/cli.d.ts.map +1 -1
  4. package/dist/bun/restore-sandbox-env.d.ts.map +1 -1
  5. package/dist/bun/restore-sandbox-env.js.map +1 -1
  6. package/dist/bun/runtime-setup.d.ts.map +1 -1
  7. package/dist/bun/runtime-setup.js +4 -1
  8. package/dist/bun/runtime-setup.js.map +1 -1
  9. package/dist/bun/sandbox-env-setup.d.ts.map +1 -1
  10. package/dist/bundle/chunks/anthropic-messages-DA6M7CRN.js +6 -0
  11. package/dist/bundle/chunks/anthropic.js +2 -2
  12. package/dist/bundle/chunks/azure-openai-responses-IJO5RNR3.js +2 -0
  13. package/dist/bundle/chunks/bedrock-converse-stream.js +10 -2
  14. package/dist/bundle/chunks/chunk-22CYIUS4.js +2 -0
  15. package/dist/bundle/chunks/chunk-2M76JOVH.js +8 -0
  16. package/dist/bundle/chunks/chunk-5HTGPCR7.js +2 -0
  17. package/dist/bundle/chunks/chunk-5OD3Y36V.js +11 -0
  18. package/dist/bundle/chunks/chunk-6C5VKHGV.js +50 -0
  19. package/dist/bundle/chunks/chunk-F5ZABL6Z.js +20 -0
  20. package/dist/bundle/chunks/{chunk-3DNTDXPG.js → chunk-FJPXW4TE.js} +3 -3
  21. package/dist/bundle/chunks/chunk-FLX3SJDL.js +1156 -0
  22. package/dist/bundle/chunks/chunk-HACVPRBJ.js +11 -0
  23. package/dist/bundle/chunks/chunk-ITZNWD4K.js +2 -0
  24. package/dist/bundle/chunks/chunk-J7I2NFJ7.js +82 -0
  25. package/dist/bundle/chunks/chunk-JHYQSLCR.js +2 -0
  26. package/dist/bundle/chunks/chunk-LPXNMA2W.js +2 -0
  27. package/dist/bundle/chunks/chunk-OO6DJ3CL.js +31 -0
  28. package/dist/bundle/chunks/chunk-PMRZO46Y.js +2 -0
  29. package/dist/bundle/chunks/{chunk-TRDNDS6A.js → chunk-PYGXRV27.js} +5 -2
  30. package/dist/bundle/chunks/chunk-RDZVAGPR.js +2 -0
  31. package/dist/bundle/chunks/{chunk-XDUWOHPL.js → chunk-S3GGRYIO.js} +2 -2
  32. package/dist/bundle/chunks/chunk-UTB4DTYQ.js +2 -0
  33. package/dist/bundle/chunks/chunk-WUIPA42N.js +14 -0
  34. package/dist/bundle/chunks/chunk-XIX7LUWI.js +2 -0
  35. package/dist/bundle/chunks/chunk-YWHGLBPB.js +2 -0
  36. package/dist/bundle/chunks/chunk-ZBURYEWF.js +2 -0
  37. package/dist/bundle/chunks/cli-QAQLORRY.js +51 -0
  38. package/dist/bundle/chunks/cloudflare-workers-ai-system-one-UTBL2KOF.js +2 -0
  39. package/dist/bundle/chunks/codemode-worker.js +478 -0
  40. package/dist/bundle/chunks/execute-2Z6BN5R3.js +499 -0
  41. package/dist/bundle/chunks/github-copilot.js +1 -1
  42. package/dist/bundle/chunks/google-generative-ai-JSIIVUNP.js +2 -0
  43. package/dist/bundle/chunks/google-vertex-BZ3ID54S.js +2 -0
  44. package/dist/bundle/chunks/image-resize-worker.js +1 -1
  45. package/dist/bundle/chunks/jiti-loader-C3NU2SDH.js +21 -0
  46. package/dist/bundle/chunks/jiti-static-loader-E6ANQD5T.js +2 -0
  47. package/dist/bundle/chunks/{lib-HGQMNYVT.js → lib-TEDK3E5I.js} +2 -2
  48. package/dist/bundle/chunks/llama-cpp-classify-FYN623RH.js +22 -0
  49. package/dist/bundle/chunks/meta.js +2 -0
  50. package/dist/bundle/chunks/mistral-conversations-RMNTDYQK.js +5 -0
  51. package/dist/bundle/chunks/node-N5BSDOA5.js +16 -0
  52. package/dist/bundle/chunks/{node-4PXJTSWH.js → node-TWVVAGPO.js} +1 -1
  53. package/dist/bundle/chunks/openai-chatgpt.js +75 -0
  54. package/dist/bundle/chunks/openai-codex-responses-O3P3UWDP.js +10 -0
  55. package/dist/bundle/chunks/openai-codex.js +2 -2
  56. package/dist/bundle/chunks/openai-completions-G4BKSHGH.js +7 -0
  57. package/dist/bundle/chunks/openai-decisions-WVPMQ4JD.js +5 -0
  58. package/dist/bundle/chunks/openai-responses-377V6EDU.js +3 -0
  59. package/dist/bundle/chunks/{openrouter-images-N4XVVFSD.js → openrouter-images-YU24TD7D.js} +1 -1
  60. package/dist/bundle/chunks/openrouter.js +2 -2
  61. package/dist/bundle/chunks/{pi-messages-ZRYGTSON.js → pi-messages-V27DSLVC.js} +2 -2
  62. package/dist/bundle/chunks/radius.js +2 -2
  63. package/dist/bundle/chunks/runtime-R6O72Q4R.js +2 -0
  64. package/dist/bundle/chunks/typesafe-system-one-ZSK3RN4B.js +2 -0
  65. package/dist/bundle/chunks/virtual-modules-FOSN3OT2.js +2 -0
  66. package/dist/bundle/cli-runtime.js +3 -0
  67. package/dist/bundle/cli.js +4 -2
  68. package/dist/bundle/index.js +1 -1
  69. package/dist/bundle/rpc-entry.js +1 -1
  70. package/dist/cli/args.d.ts +1 -2
  71. package/dist/cli/args.d.ts.map +1 -1
  72. package/dist/cli/args.js +73 -53
  73. package/dist/cli/args.js.map +1 -1
  74. package/dist/cli/auth-check.d.ts.map +1 -1
  75. package/dist/cli/auth-check.js.map +1 -1
  76. package/dist/cli/auth-command.d.ts.map +1 -1
  77. package/dist/cli/auth-command.js.map +1 -1
  78. package/dist/cli/credential-print.d.ts.map +1 -1
  79. package/dist/cli/credential-print.js.map +1 -1
  80. package/dist/cli/experimental/transport-address.d.ts +21 -0
  81. package/dist/cli/experimental/transport-address.d.ts.map +1 -0
  82. package/dist/cli/experimental/transport-address.js +89 -0
  83. package/dist/cli/experimental/transport-address.js.map +1 -0
  84. package/dist/cli/file-processor.d.ts +1 -1
  85. package/dist/cli/file-processor.d.ts.map +1 -1
  86. package/dist/cli/file-processor.js.map +1 -1
  87. package/dist/cli/initial-message.d.ts +1 -1
  88. package/dist/cli/initial-message.d.ts.map +1 -1
  89. package/dist/cli/initial-message.js.map +1 -1
  90. package/dist/cli/list-models.d.ts.map +1 -1
  91. package/dist/cli/list-models.js +1 -1
  92. package/dist/cli/list-models.js.map +1 -1
  93. package/dist/cli/project-trust.d.ts.map +1 -1
  94. package/dist/cli/project-trust.js +5 -35
  95. package/dist/cli/project-trust.js.map +1 -1
  96. package/dist/cli/setup.d.ts.map +1 -1
  97. package/dist/cli/setup.js.map +1 -1
  98. package/dist/cli.d.ts.map +1 -1
  99. package/dist/config.d.ts +30 -11
  100. package/dist/config.d.ts.map +1 -1
  101. package/dist/config.js +72 -21
  102. package/dist/config.js.map +1 -1
  103. package/dist/core/agent-session-runtime.d.ts +4 -3
  104. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  105. package/dist/core/agent-session-runtime.js +37 -27
  106. package/dist/core/agent-session-runtime.js.map +1 -1
  107. package/dist/core/agent-session-services.d.ts +1 -0
  108. package/dist/core/agent-session-services.d.ts.map +1 -1
  109. package/dist/core/agent-session-services.js +14 -0
  110. package/dist/core/agent-session-services.js.map +1 -1
  111. package/dist/core/agent-session.d.ts +270 -22
  112. package/dist/core/agent-session.d.ts.map +1 -1
  113. package/dist/core/agent-session.js +1174 -410
  114. package/dist/core/agent-session.js.map +1 -1
  115. package/dist/core/auth-guidance.d.ts.map +1 -1
  116. package/dist/core/auth-guidance.js.map +1 -1
  117. package/dist/core/auth-storage.d.ts.map +1 -1
  118. package/dist/core/auth-storage.js +20 -13
  119. package/dist/core/auth-storage.js.map +1 -1
  120. package/dist/core/bash-executor.d.ts.map +1 -1
  121. package/dist/core/bash-executor.js +42 -52
  122. package/dist/core/bash-executor.js.map +1 -1
  123. package/dist/core/bug-report-upload.d.ts +12 -0
  124. package/dist/core/bug-report-upload.d.ts.map +1 -0
  125. package/dist/core/bug-report-upload.js +22 -0
  126. package/dist/core/bug-report-upload.js.map +1 -0
  127. package/dist/core/bug-report.d.ts +184 -0
  128. package/dist/core/bug-report.d.ts.map +1 -0
  129. package/dist/core/bug-report.js +292 -0
  130. package/dist/core/bug-report.js.map +1 -0
  131. package/dist/core/cache-stats.d.ts.map +1 -1
  132. package/dist/core/cache-stats.js +12 -1
  133. package/dist/core/cache-stats.js.map +1 -1
  134. package/dist/core/cache-warmer.d.ts +103 -0
  135. package/dist/core/cache-warmer.d.ts.map +1 -0
  136. package/dist/core/cache-warmer.js +356 -0
  137. package/dist/core/cache-warmer.js.map +1 -0
  138. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  139. package/dist/core/compaction/branch-summarization.js +2 -2
  140. package/dist/core/compaction/branch-summarization.js.map +1 -1
  141. package/dist/core/compaction/compaction.d.ts +5 -3
  142. package/dist/core/compaction/compaction.d.ts.map +1 -1
  143. package/dist/core/compaction/compaction.js +164 -88
  144. package/dist/core/compaction/compaction.js.map +1 -1
  145. package/dist/core/compaction/index.d.ts.map +1 -1
  146. package/dist/core/compaction/utils.d.ts +8 -1
  147. package/dist/core/compaction/utils.d.ts.map +1 -1
  148. package/dist/core/compaction/utils.js +32 -26
  149. package/dist/core/compaction/utils.js.map +1 -1
  150. package/dist/core/crash-log.d.ts +27 -0
  151. package/dist/core/crash-log.d.ts.map +1 -0
  152. package/dist/core/crash-log.js +140 -0
  153. package/dist/core/crash-log.js.map +1 -0
  154. package/dist/core/defaults.d.ts.map +1 -1
  155. package/dist/core/delivery.d.ts.map +1 -1
  156. package/dist/core/delivery.js.map +1 -1
  157. package/dist/core/diagnostics.d.ts.map +1 -1
  158. package/dist/core/event-bus.d.ts.map +1 -1
  159. package/dist/core/event-bus.js.map +1 -1
  160. package/dist/core/exec.d.ts.map +1 -1
  161. package/dist/core/exec.js.map +1 -1
  162. package/dist/core/experimental.d.ts.map +1 -1
  163. package/dist/core/experimental.js.map +1 -1
  164. package/dist/core/export-html/ansi-to-html.d.ts.map +1 -1
  165. package/dist/core/export-html/ansi-to-html.js.map +1 -1
  166. package/dist/core/export-html/index.d.ts.map +1 -1
  167. package/dist/core/export-html/index.js +1 -1
  168. package/dist/core/export-html/index.js.map +1 -1
  169. package/dist/core/export-html/template.css +10 -0
  170. package/dist/core/export-html/template.js +93 -34
  171. package/dist/core/export-html/tool-renderer.d.ts +5 -11
  172. package/dist/core/export-html/tool-renderer.d.ts.map +1 -1
  173. package/dist/core/export-html/tool-renderer.js +8 -99
  174. package/dist/core/export-html/tool-renderer.js.map +1 -1
  175. package/dist/core/extensions/index.d.ts +1 -1
  176. package/dist/core/extensions/index.d.ts.map +1 -1
  177. package/dist/core/extensions/index.js.map +1 -1
  178. package/dist/core/extensions/jiti-loader.d.ts +2 -0
  179. package/dist/core/extensions/jiti-loader.d.ts.map +1 -0
  180. package/dist/core/extensions/jiti-loader.js +4 -0
  181. package/dist/core/extensions/jiti-loader.js.map +1 -0
  182. package/dist/core/extensions/jiti-static-loader.d.ts +2 -0
  183. package/dist/core/extensions/jiti-static-loader.d.ts.map +1 -0
  184. package/dist/core/extensions/jiti-static-loader.js +4 -0
  185. package/dist/core/extensions/jiti-static-loader.js.map +1 -0
  186. package/dist/core/extensions/loader.d.ts.map +1 -1
  187. package/dist/core/extensions/loader.js +102 -74
  188. package/dist/core/extensions/loader.js.map +1 -1
  189. package/dist/core/extensions/runner.d.ts +44 -14
  190. package/dist/core/extensions/runner.d.ts.map +1 -1
  191. package/dist/core/extensions/runner.js +297 -169
  192. package/dist/core/extensions/runner.js.map +1 -1
  193. package/dist/core/extensions/types.d.ts +482 -238
  194. package/dist/core/extensions/types.d.ts.map +1 -1
  195. package/dist/core/extensions/types.js.map +1 -1
  196. package/dist/core/extensions/virtual-modules.d.ts +3 -0
  197. package/dist/core/extensions/virtual-modules.d.ts.map +1 -0
  198. package/dist/core/extensions/virtual-modules.js +35 -0
  199. package/dist/core/extensions/virtual-modules.js.map +1 -0
  200. package/dist/core/extensions/wrapper.d.ts +2 -2
  201. package/dist/core/extensions/wrapper.d.ts.map +1 -1
  202. package/dist/core/extensions/wrapper.js +3 -22
  203. package/dist/core/extensions/wrapper.js.map +1 -1
  204. package/dist/core/footer-data-provider.d.ts.map +1 -1
  205. package/dist/core/footer-data-provider.js.map +1 -1
  206. package/dist/core/http-dispatcher.d.ts +13 -0
  207. package/dist/core/http-dispatcher.d.ts.map +1 -1
  208. package/dist/core/http-dispatcher.js +13 -4
  209. package/dist/core/http-dispatcher.js.map +1 -1
  210. package/dist/core/index.d.ts +2 -1
  211. package/dist/core/index.d.ts.map +1 -1
  212. package/dist/core/index.js.map +1 -1
  213. package/dist/core/mcp-servers.d.ts +139 -0
  214. package/dist/core/mcp-servers.d.ts.map +1 -0
  215. package/dist/core/mcp-servers.js +232 -0
  216. package/dist/core/mcp-servers.js.map +1 -0
  217. package/dist/core/messages.d.ts.map +1 -1
  218. package/dist/core/messages.js +1 -0
  219. package/dist/core/messages.js.map +1 -1
  220. package/dist/{modes/interactive → core}/model-catalog-refresh.d.ts +2 -2
  221. package/dist/core/model-catalog-refresh.d.ts.map +1 -0
  222. package/dist/{modes/interactive → core}/model-catalog-refresh.js +2 -2
  223. package/dist/core/model-catalog-refresh.js.map +1 -0
  224. package/dist/core/model-config.d.ts +886 -80
  225. package/dist/core/model-config.d.ts.map +1 -1
  226. package/dist/core/model-config.js +33 -148
  227. package/dist/core/model-config.js.map +1 -1
  228. package/dist/core/model-registry.d.ts +15 -1
  229. package/dist/core/model-registry.d.ts.map +1 -1
  230. package/dist/core/model-registry.js +29 -0
  231. package/dist/core/model-registry.js.map +1 -1
  232. package/dist/core/model-resolver.d.ts +19 -46
  233. package/dist/core/model-resolver.d.ts.map +1 -1
  234. package/dist/core/model-resolver.js +149 -359
  235. package/dist/core/model-resolver.js.map +1 -1
  236. package/dist/core/model-runtime.d.ts +47 -3
  237. package/dist/core/model-runtime.d.ts.map +1 -1
  238. package/dist/core/model-runtime.js +205 -43
  239. package/dist/core/model-runtime.js.map +1 -1
  240. package/dist/core/models-store.d.ts.map +1 -1
  241. package/dist/core/models-store.js.map +1 -1
  242. package/dist/core/nested-tool-calls.d.ts +103 -0
  243. package/dist/core/nested-tool-calls.d.ts.map +1 -0
  244. package/dist/core/nested-tool-calls.js +179 -0
  245. package/dist/core/nested-tool-calls.js.map +1 -0
  246. package/dist/core/output-guard.d.ts.map +1 -1
  247. package/dist/core/output-guard.js.map +1 -1
  248. package/dist/core/package-manager.d.ts +4 -0
  249. package/dist/core/package-manager.d.ts.map +1 -1
  250. package/dist/core/package-manager.js +62 -15
  251. package/dist/core/package-manager.js.map +1 -1
  252. package/dist/core/pi-manifest.d.ts.map +1 -1
  253. package/dist/core/pi-manifest.js.map +1 -1
  254. package/dist/core/project-trust.d.ts.map +1 -1
  255. package/dist/core/project-trust.js +2 -1
  256. package/dist/core/project-trust.js.map +1 -1
  257. package/dist/core/prompt-templates.d.ts +6 -1
  258. package/dist/core/prompt-templates.d.ts.map +1 -1
  259. package/dist/core/prompt-templates.js +68 -37
  260. package/dist/core/prompt-templates.js.map +1 -1
  261. package/dist/core/provider-attribution.d.ts.map +1 -1
  262. package/dist/core/provider-attribution.js.map +1 -1
  263. package/dist/core/provider-composer.d.ts +42 -20
  264. package/dist/core/provider-composer.d.ts.map +1 -1
  265. package/dist/core/provider-composer.js +126 -40
  266. package/dist/core/provider-composer.js.map +1 -1
  267. package/dist/core/radius.d.ts +5 -0
  268. package/dist/core/radius.d.ts.map +1 -1
  269. package/dist/core/radius.js +8 -0
  270. package/dist/core/radius.js.map +1 -1
  271. package/dist/core/remote-catalog-provider.d.ts +19 -1
  272. package/dist/core/remote-catalog-provider.d.ts.map +1 -1
  273. package/dist/core/remote-catalog-provider.js +102 -34
  274. package/dist/core/remote-catalog-provider.js.map +1 -1
  275. package/dist/core/resolve-config-value.d.ts.map +1 -1
  276. package/dist/core/resolve-config-value.js.map +1 -1
  277. package/dist/core/resource-loader.d.ts +11 -2
  278. package/dist/core/resource-loader.d.ts.map +1 -1
  279. package/dist/core/resource-loader.js +170 -42
  280. package/dist/core/resource-loader.js.map +1 -1
  281. package/dist/core/runtime-credentials.d.ts.map +1 -1
  282. package/dist/core/runtime-credentials.js.map +1 -1
  283. package/dist/core/sdk.d.ts +16 -5
  284. package/dist/core/sdk.d.ts.map +1 -1
  285. package/dist/core/sdk.js +124 -52
  286. package/dist/core/sdk.js.map +1 -1
  287. package/dist/core/session-cwd.d.ts.map +1 -1
  288. package/dist/core/session-cwd.js.map +1 -1
  289. package/dist/core/session-export.d.ts +6 -2
  290. package/dist/core/session-export.d.ts.map +1 -1
  291. package/dist/core/session-export.js +14 -13
  292. package/dist/core/session-export.js.map +1 -1
  293. package/dist/core/session-manager.d.ts +72 -13
  294. package/dist/core/session-manager.d.ts.map +1 -1
  295. package/dist/core/session-manager.js +277 -124
  296. package/dist/core/session-manager.js.map +1 -1
  297. package/dist/core/settings-defaults.d.ts +65 -0
  298. package/dist/core/settings-defaults.d.ts.map +1 -0
  299. package/dist/core/settings-defaults.js +66 -0
  300. package/dist/core/settings-defaults.js.map +1 -0
  301. package/dist/core/settings-diagnostics.d.ts.map +1 -1
  302. package/dist/core/settings-diagnostics.js.map +1 -1
  303. package/dist/core/settings-manager.d.ts +41 -126
  304. package/dist/core/settings-manager.d.ts.map +1 -1
  305. package/dist/core/settings-manager.js +165 -52
  306. package/dist/core/settings-manager.js.map +1 -1
  307. package/dist/core/settings-schema.d.ts +224 -0
  308. package/dist/core/settings-schema.d.ts.map +1 -0
  309. package/dist/core/settings-schema.js +285 -0
  310. package/dist/core/settings-schema.js.map +1 -0
  311. package/dist/core/skills.d.ts +4 -1
  312. package/dist/core/skills.d.ts.map +1 -1
  313. package/dist/core/skills.js +6 -1
  314. package/dist/core/skills.js.map +1 -1
  315. package/dist/core/slash-commands.d.ts.map +1 -1
  316. package/dist/core/slash-commands.js +3 -2
  317. package/dist/core/slash-commands.js.map +1 -1
  318. package/dist/core/source-info.d.ts +8 -0
  319. package/dist/core/source-info.d.ts.map +1 -1
  320. package/dist/core/source-info.js +16 -0
  321. package/dist/core/source-info.js.map +1 -1
  322. package/dist/core/system-prompt.d.ts +55 -6
  323. package/dist/core/system-prompt.d.ts.map +1 -1
  324. package/dist/core/system-prompt.js +128 -93
  325. package/dist/core/system-prompt.js.map +1 -1
  326. package/dist/core/telemetry.d.ts +2 -0
  327. package/dist/core/telemetry.d.ts.map +1 -1
  328. package/dist/core/telemetry.js +45 -0
  329. package/dist/core/telemetry.js.map +1 -1
  330. package/dist/core/theme/dark.json +78 -0
  331. package/dist/core/theme/light.json +78 -0
  332. package/dist/core/theme/system-theme.d.ts +54 -0
  333. package/dist/core/theme/system-theme.d.ts.map +1 -0
  334. package/dist/core/theme/system-theme.js +547 -0
  335. package/dist/core/theme/system-theme.js.map +1 -0
  336. package/dist/core/theme/theme-schema.d.ts +28 -0
  337. package/dist/core/theme/theme-schema.d.ts.map +1 -0
  338. package/dist/core/theme/theme-schema.js +105 -0
  339. package/dist/core/theme/theme-schema.js.map +1 -0
  340. package/dist/core/theme/theme-tokens.d.ts +257 -0
  341. package/dist/core/theme/theme-tokens.d.ts.map +1 -0
  342. package/dist/core/theme/theme-tokens.js +94 -0
  343. package/dist/core/theme/theme-tokens.js.map +1 -0
  344. package/dist/core/theme/theme.d.ts +162 -0
  345. package/dist/core/theme/theme.d.ts.map +1 -0
  346. package/dist/{modes/interactive → core}/theme/theme.js +265 -402
  347. package/dist/core/theme/theme.js.map +1 -0
  348. package/dist/core/timings.d.ts.map +1 -1
  349. package/dist/core/timings.js.map +1 -1
  350. package/dist/core/tools/bash.d.ts +14 -1
  351. package/dist/core/tools/bash.d.ts.map +1 -1
  352. package/dist/core/tools/bash.js +43 -6
  353. package/dist/core/tools/bash.js.map +1 -1
  354. package/dist/core/tools/edit-diff.d.ts.map +1 -1
  355. package/dist/core/tools/edit-diff.js.map +1 -1
  356. package/dist/core/tools/edit.d.ts +1 -2
  357. package/dist/core/tools/edit.d.ts.map +1 -1
  358. package/dist/core/tools/edit.js +0 -3
  359. package/dist/core/tools/edit.js.map +1 -1
  360. package/dist/core/tools/file-mutation-queue.d.ts.map +1 -1
  361. package/dist/core/tools/file-mutation-queue.js.map +1 -1
  362. package/dist/core/tools/find.d.ts.map +1 -1
  363. package/dist/core/tools/find.js +0 -2
  364. package/dist/core/tools/find.js.map +1 -1
  365. package/dist/core/tools/grep.d.ts.map +1 -1
  366. package/dist/core/tools/grep.js +0 -2
  367. package/dist/core/tools/grep.js.map +1 -1
  368. package/dist/core/tools/index.d.ts.map +1 -1
  369. package/dist/core/tools/index.js.map +1 -1
  370. package/dist/core/tools/ls.d.ts.map +1 -1
  371. package/dist/core/tools/ls.js +0 -2
  372. package/dist/core/tools/ls.js.map +1 -1
  373. package/dist/core/tools/output-accumulator.d.ts +11 -0
  374. package/dist/core/tools/output-accumulator.d.ts.map +1 -1
  375. package/dist/core/tools/output-accumulator.js +40 -10
  376. package/dist/core/tools/output-accumulator.js.map +1 -1
  377. package/dist/core/tools/path-utils.d.ts.map +1 -1
  378. package/dist/core/tools/path-utils.js.map +1 -1
  379. package/dist/core/tools/powershell.d.ts.map +1 -1
  380. package/dist/core/tools/powershell.js.map +1 -1
  381. package/dist/core/tools/read.d.ts +17 -1
  382. package/dist/core/tools/read.d.ts.map +1 -1
  383. package/dist/core/tools/read.js +23 -4
  384. package/dist/core/tools/read.js.map +1 -1
  385. package/dist/core/tools/tool-definition-wrapper.d.ts +5 -3
  386. package/dist/core/tools/tool-definition-wrapper.d.ts.map +1 -1
  387. package/dist/core/tools/tool-definition-wrapper.js +3 -1
  388. package/dist/core/tools/tool-definition-wrapper.js.map +1 -1
  389. package/dist/core/tools/truncate.d.ts +14 -0
  390. package/dist/core/tools/truncate.d.ts.map +1 -1
  391. package/dist/core/tools/truncate.js +29 -0
  392. package/dist/core/tools/truncate.js.map +1 -1
  393. package/dist/core/tools/write.d.ts.map +1 -1
  394. package/dist/core/tools/write.js +0 -2
  395. package/dist/core/tools/write.js.map +1 -1
  396. package/dist/core/trust-manager.d.ts.map +1 -1
  397. package/dist/core/trust-manager.js +1 -0
  398. package/dist/core/trust-manager.js.map +1 -1
  399. package/dist/core/usage-totals.d.ts +3 -1
  400. package/dist/core/usage-totals.d.ts.map +1 -1
  401. package/dist/core/usage-totals.js +28 -1
  402. package/dist/core/usage-totals.js.map +1 -1
  403. package/dist/core/virtual-models.d.ts +117 -0
  404. package/dist/core/virtual-models.d.ts.map +1 -0
  405. package/dist/core/virtual-models.js +124 -0
  406. package/dist/core/virtual-models.js.map +1 -0
  407. package/dist/extensions/browser/index.d.ts.map +1 -1
  408. package/dist/extensions/browser/index.js.map +1 -1
  409. package/dist/extensions/codemode/execute.d.ts +16 -0
  410. package/dist/extensions/codemode/execute.d.ts.map +1 -0
  411. package/dist/extensions/codemode/execute.js +665 -0
  412. package/dist/extensions/codemode/execute.js.map +1 -0
  413. package/dist/extensions/codemode/execute.lazy.d.ts +3 -0
  414. package/dist/extensions/codemode/execute.lazy.d.ts.map +1 -0
  415. package/dist/extensions/codemode/execute.lazy.js +3 -0
  416. package/dist/extensions/codemode/execute.lazy.js.map +1 -0
  417. package/dist/extensions/codemode/index.d.ts +21 -0
  418. package/dist/extensions/codemode/index.d.ts.map +1 -0
  419. package/dist/extensions/codemode/index.js +33 -0
  420. package/dist/extensions/codemode/index.js.map +1 -0
  421. package/dist/extensions/codemode/tool.d.ts +124 -0
  422. package/dist/extensions/codemode/tool.d.ts.map +1 -0
  423. package/dist/extensions/codemode/tool.js +286 -0
  424. package/dist/extensions/codemode/tool.js.map +1 -0
  425. package/dist/extensions/codemode/worker.d.ts +7 -0
  426. package/dist/extensions/codemode/worker.d.ts.map +1 -0
  427. package/dist/extensions/codemode/worker.js +7 -0
  428. package/dist/extensions/codemode/worker.js.map +1 -0
  429. package/dist/extensions/context-pruning/compress_context.d.ts.map +1 -1
  430. package/dist/extensions/context-pruning/compress_context.js +1 -3
  431. package/dist/extensions/context-pruning/compress_context.js.map +1 -1
  432. package/dist/extensions/context-pruning/context-pruning-state.d.ts.map +1 -1
  433. package/dist/extensions/context-pruning/context-pruning-state.js.map +1 -1
  434. package/dist/extensions/index.d.ts.map +1 -1
  435. package/dist/extensions/index.js +6 -2
  436. package/dist/extensions/index.js.map +1 -1
  437. package/dist/extensions/llama/client.d.ts +2 -0
  438. package/dist/extensions/llama/client.d.ts.map +1 -1
  439. package/dist/extensions/llama/client.js +7 -3
  440. package/dist/extensions/llama/client.js.map +1 -1
  441. package/dist/extensions/llama/huggingface.d.ts.map +1 -1
  442. package/dist/extensions/llama/huggingface.js.map +1 -1
  443. package/dist/extensions/llama/index.d.ts.map +1 -1
  444. package/dist/extensions/llama/index.js +0 -4
  445. package/dist/extensions/llama/index.js.map +1 -1
  446. package/dist/extensions/llama/provider.d.ts +1 -1
  447. package/dist/extensions/llama/provider.d.ts.map +1 -1
  448. package/dist/extensions/llama/provider.js +103 -13
  449. package/dist/extensions/llama/provider.js.map +1 -1
  450. package/dist/extensions/llama/ui.d.ts +3 -2
  451. package/dist/extensions/llama/ui.d.ts.map +1 -1
  452. package/dist/extensions/llama/ui.js +106 -364
  453. package/dist/extensions/llama/ui.js.map +1 -1
  454. package/dist/extensions/mcp/cli.d.ts +21 -0
  455. package/dist/extensions/mcp/cli.d.ts.map +1 -0
  456. package/dist/extensions/mcp/cli.js +494 -0
  457. package/dist/extensions/mcp/cli.js.map +1 -0
  458. package/dist/extensions/mcp/cli.lazy.d.ts +3 -0
  459. package/dist/extensions/mcp/cli.lazy.d.ts.map +1 -0
  460. package/dist/extensions/mcp/cli.lazy.js +3 -0
  461. package/dist/extensions/mcp/cli.lazy.js.map +1 -0
  462. package/dist/extensions/mcp/config.d.ts +84 -0
  463. package/dist/extensions/mcp/config.d.ts.map +1 -0
  464. package/dist/extensions/mcp/config.js +196 -0
  465. package/dist/extensions/mcp/config.js.map +1 -0
  466. package/dist/extensions/mcp/index.d.ts +71 -2
  467. package/dist/extensions/mcp/index.d.ts.map +1 -1
  468. package/dist/extensions/mcp/index.js +839 -131
  469. package/dist/extensions/mcp/index.js.map +1 -1
  470. package/dist/extensions/mcp/log.d.ts +16 -0
  471. package/dist/extensions/mcp/log.d.ts.map +1 -0
  472. package/dist/extensions/mcp/log.js +66 -0
  473. package/dist/extensions/mcp/log.js.map +1 -0
  474. package/dist/extensions/mcp/oauth.d.ts +102 -0
  475. package/dist/extensions/mcp/oauth.d.ts.map +1 -0
  476. package/dist/extensions/mcp/oauth.js +428 -0
  477. package/dist/extensions/mcp/oauth.js.map +1 -0
  478. package/dist/extensions/mcp/resources.d.ts +36 -0
  479. package/dist/extensions/mcp/resources.d.ts.map +1 -0
  480. package/dist/extensions/mcp/resources.js +261 -0
  481. package/dist/extensions/mcp/resources.js.map +1 -0
  482. package/dist/extensions/mcp/runtime.d.ts +98 -0
  483. package/dist/extensions/mcp/runtime.d.ts.map +1 -0
  484. package/dist/extensions/mcp/runtime.js +378 -0
  485. package/dist/extensions/mcp/runtime.js.map +1 -0
  486. package/dist/extensions/mcp/runtime.lazy.d.ts +3 -0
  487. package/dist/extensions/mcp/runtime.lazy.d.ts.map +1 -0
  488. package/dist/extensions/mcp/runtime.lazy.js +3 -0
  489. package/dist/extensions/mcp/runtime.lazy.js.map +1 -0
  490. package/dist/extensions/mcp/tools.d.ts +84 -0
  491. package/dist/extensions/mcp/tools.d.ts.map +1 -0
  492. package/dist/extensions/mcp/tools.js +263 -0
  493. package/dist/extensions/mcp/tools.js.map +1 -0
  494. package/dist/extensions/punch/a2a-listen.d.ts +9 -0
  495. package/dist/extensions/punch/a2a-listen.d.ts.map +1 -0
  496. package/dist/extensions/punch/a2a-listen.js +88 -0
  497. package/dist/extensions/punch/a2a-listen.js.map +1 -0
  498. package/dist/extensions/punch/a2a.d.ts +12 -0
  499. package/dist/extensions/punch/a2a.d.ts.map +1 -0
  500. package/dist/extensions/punch/a2a.js +106 -0
  501. package/dist/extensions/punch/a2a.js.map +1 -0
  502. package/dist/extensions/punch/auth.d.ts.map +1 -1
  503. package/dist/extensions/punch/auth.js.map +1 -1
  504. package/dist/extensions/punch/collabs.d.ts.map +1 -1
  505. package/dist/extensions/punch/collabs.js.map +1 -1
  506. package/dist/extensions/punch/index.d.ts.map +1 -1
  507. package/dist/extensions/punch/index.js +9 -14
  508. package/dist/extensions/punch/index.js.map +1 -1
  509. package/dist/extensions/punch/routines.d.ts +1 -3
  510. package/dist/extensions/punch/routines.d.ts.map +1 -1
  511. package/dist/extensions/punch/routines.js +1 -121
  512. package/dist/extensions/punch/routines.js.map +1 -1
  513. package/dist/extensions/punch/server.d.ts.map +1 -1
  514. package/dist/extensions/punch/server.js.map +1 -1
  515. package/dist/extensions/punch/timezone.d.ts.map +1 -1
  516. package/dist/extensions/punch/timezone.js.map +1 -1
  517. package/dist/extensions/punch/todos.d.ts.map +1 -1
  518. package/dist/extensions/punch/todos.js.map +1 -1
  519. package/dist/extensions/report-progress/index.d.ts.map +1 -1
  520. package/dist/extensions/report-progress/index.js.map +1 -1
  521. package/dist/extensions/subagent/agents.d.ts.map +1 -1
  522. package/dist/extensions/subagent/agents.js.map +1 -1
  523. package/dist/extensions/subagent/index.d.ts.map +1 -1
  524. package/dist/extensions/subagent/index.js +0 -372
  525. package/dist/extensions/subagent/index.js.map +1 -1
  526. package/dist/extensions/tool-search/index.d.ts +12 -0
  527. package/dist/extensions/tool-search/index.d.ts.map +1 -0
  528. package/dist/extensions/tool-search/index.js +15 -0
  529. package/dist/extensions/tool-search/index.js.map +1 -0
  530. package/dist/extensions/tool-search/tool.d.ts +71 -0
  531. package/dist/extensions/tool-search/tool.d.ts.map +1 -0
  532. package/dist/extensions/tool-search/tool.js +187 -0
  533. package/dist/extensions/tool-search/tool.js.map +1 -0
  534. package/dist/extensions/webfetch/index.d.ts.map +1 -1
  535. package/dist/extensions/webfetch/index.js.map +1 -1
  536. package/dist/extensions/websearch/index.d.ts.map +1 -1
  537. package/dist/extensions/websearch/index.js.map +1 -1
  538. package/dist/index.d.ts +13 -6
  539. package/dist/index.d.ts.map +1 -1
  540. package/dist/index.js +9 -6
  541. package/dist/index.js.map +1 -1
  542. package/dist/main.d.ts +1 -1
  543. package/dist/main.d.ts.map +1 -1
  544. package/dist/main.js +139 -173
  545. package/dist/main.js.map +1 -1
  546. package/dist/migrations.d.ts.map +1 -1
  547. package/dist/migrations.js +0 -20
  548. package/dist/migrations.js.map +1 -1
  549. package/dist/modes/index.d.ts +0 -1
  550. package/dist/modes/index.d.ts.map +1 -1
  551. package/dist/modes/index.js +0 -1
  552. package/dist/modes/index.js.map +1 -1
  553. package/dist/modes/json-event.d.ts.map +1 -1
  554. package/dist/modes/json-event.js.map +1 -1
  555. package/dist/modes/print-mode.d.ts.map +1 -1
  556. package/dist/modes/print-mode.js +4 -0
  557. package/dist/modes/print-mode.js.map +1 -1
  558. package/dist/modes/rpc/jsonl.d.ts.map +1 -1
  559. package/dist/modes/rpc/jsonl.js.map +1 -1
  560. package/dist/modes/rpc/rpc-client.d.ts +6 -6
  561. package/dist/modes/rpc/rpc-client.d.ts.map +1 -1
  562. package/dist/modes/rpc/rpc-client.js +12 -8
  563. package/dist/modes/rpc/rpc-client.js.map +1 -1
  564. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  565. package/dist/modes/rpc/rpc-mode.js +16 -46
  566. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  567. package/dist/modes/rpc/rpc-types.d.ts +10 -1
  568. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  569. package/dist/modes/rpc/rpc-types.js.map +1 -1
  570. package/dist/package-manager-cli.d.ts.map +1 -1
  571. package/dist/package-manager-cli.js +43 -43
  572. package/dist/package-manager-cli.js.map +1 -1
  573. package/dist/rpc-entry.d.ts.map +1 -1
  574. package/dist/rpc-entry.js.map +1 -1
  575. package/dist/server/a2a/harness-runner.d.ts.map +1 -1
  576. package/dist/server/a2a/harness-runner.js.map +1 -1
  577. package/dist/server/a2a/run-server.d.ts.map +1 -1
  578. package/dist/server/a2a/run-server.js.map +1 -1
  579. package/dist/utils/abort.d.ts.map +1 -1
  580. package/dist/utils/abort.js.map +1 -1
  581. package/dist/utils/ansi.d.ts +8 -0
  582. package/dist/utils/ansi.d.ts.map +1 -1
  583. package/dist/utils/ansi.js +30 -11
  584. package/dist/utils/ansi.js.map +1 -1
  585. package/dist/utils/changelog.d.ts.map +1 -1
  586. package/dist/utils/changelog.js +5 -2
  587. package/dist/utils/changelog.js.map +1 -1
  588. package/dist/utils/child-process.d.ts.map +1 -1
  589. package/dist/utils/child-process.js.map +1 -1
  590. package/dist/utils/clipboard-command.d.ts.map +1 -1
  591. package/dist/utils/clipboard-command.js.map +1 -1
  592. package/dist/utils/clipboard-image.d.ts.map +1 -1
  593. package/dist/utils/clipboard-image.js +15 -41
  594. package/dist/utils/clipboard-image.js.map +1 -1
  595. package/dist/utils/clipboard.d.ts.map +1 -1
  596. package/dist/utils/clipboard.js +96 -38
  597. package/dist/utils/clipboard.js.map +1 -1
  598. package/dist/utils/colors.d.ts +73 -0
  599. package/dist/utils/colors.d.ts.map +1 -0
  600. package/dist/utils/colors.js +273 -0
  601. package/dist/utils/colors.js.map +1 -0
  602. package/dist/utils/deprecation.d.ts.map +1 -1
  603. package/dist/utils/deprecation.js.map +1 -1
  604. package/dist/utils/exif-orientation.d.ts.map +1 -1
  605. package/dist/utils/exif-orientation.js.map +1 -1
  606. package/dist/utils/frontmatter.d.ts.map +1 -1
  607. package/dist/utils/frontmatter.js.map +1 -1
  608. package/dist/utils/fs-watch.d.ts.map +1 -1
  609. package/dist/utils/fs-watch.js.map +1 -1
  610. package/dist/utils/fuzzy.d.ts +16 -0
  611. package/dist/utils/fuzzy.d.ts.map +1 -0
  612. package/dist/utils/fuzzy.js +111 -0
  613. package/dist/utils/fuzzy.js.map +1 -0
  614. package/dist/utils/git.d.ts.map +1 -1
  615. package/dist/utils/git.js.map +1 -1
  616. package/dist/utils/html.d.ts.map +1 -1
  617. package/dist/utils/html.js.map +1 -1
  618. package/dist/utils/image-convert.d.ts.map +1 -1
  619. package/dist/utils/image-convert.js.map +1 -1
  620. package/dist/utils/image-process.d.ts.map +1 -1
  621. package/dist/utils/image-process.js.map +1 -1
  622. package/dist/utils/image-resize-core.d.ts +12 -0
  623. package/dist/utils/image-resize-core.d.ts.map +1 -1
  624. package/dist/utils/image-resize-core.js +5 -0
  625. package/dist/utils/image-resize-core.js.map +1 -1
  626. package/dist/utils/image-resize-worker.d.ts.map +1 -1
  627. package/dist/utils/image-resize-worker.js +3 -2
  628. package/dist/utils/image-resize-worker.js.map +1 -1
  629. package/dist/utils/image-resize.d.ts.map +1 -1
  630. package/dist/utils/image-resize.js +9 -10
  631. package/dist/utils/image-resize.js.map +1 -1
  632. package/dist/utils/json.d.ts.map +1 -1
  633. package/dist/utils/json.js.map +1 -1
  634. package/dist/utils/management-http.d.ts.map +1 -1
  635. package/dist/utils/management-http.js.map +1 -1
  636. package/dist/utils/mime.d.ts.map +1 -1
  637. package/dist/utils/mime.js +1 -1
  638. package/dist/utils/mime.js.map +1 -1
  639. package/dist/utils/oklab.d.ts +43 -0
  640. package/dist/utils/oklab.d.ts.map +1 -0
  641. package/dist/utils/oklab.js +210 -0
  642. package/dist/utils/oklab.js.map +1 -0
  643. package/dist/utils/open-browser.d.ts.map +1 -1
  644. package/dist/utils/open-browser.js.map +1 -1
  645. package/dist/utils/output-files.d.ts +15 -0
  646. package/dist/utils/output-files.d.ts.map +1 -0
  647. package/dist/utils/output-files.js +30 -0
  648. package/dist/utils/output-files.js.map +1 -0
  649. package/dist/utils/paths.d.ts +3 -3
  650. package/dist/utils/paths.d.ts.map +1 -1
  651. package/dist/utils/paths.js +5 -4
  652. package/dist/utils/paths.js.map +1 -1
  653. package/dist/utils/photon.d.ts.map +1 -1
  654. package/dist/utils/photon.js.map +1 -1
  655. package/dist/utils/pi-user-agent.d.ts.map +1 -1
  656. package/dist/utils/pi-user-agent.js.map +1 -1
  657. package/dist/utils/shell.d.ts +1 -3
  658. package/dist/utils/shell.d.ts.map +1 -1
  659. package/dist/utils/shell.js +3 -30
  660. package/dist/utils/shell.js.map +1 -1
  661. package/dist/utils/sleep.d.ts.map +1 -1
  662. package/dist/utils/sleep.js.map +1 -1
  663. package/dist/utils/syntax-highlight.d.ts.map +1 -1
  664. package/dist/utils/syntax-highlight.js +8 -1
  665. package/dist/utils/syntax-highlight.js.map +1 -1
  666. package/dist/utils/text.d.ts.map +1 -1
  667. package/dist/utils/text.js.map +1 -1
  668. package/dist/utils/tool-result-images.d.ts +3 -1
  669. package/dist/utils/tool-result-images.d.ts.map +1 -1
  670. package/dist/utils/tool-result-images.js +4 -1
  671. package/dist/utils/tool-result-images.js.map +1 -1
  672. package/dist/utils/tools-manager.d.ts.map +1 -1
  673. package/dist/utils/tools-manager.js.map +1 -1
  674. package/dist/utils/version-check.d.ts.map +1 -1
  675. package/dist/utils/version-check.js.map +1 -1
  676. package/dist/utils/windows-self-update.d.ts.map +1 -1
  677. package/dist/utils/windows-self-update.js.map +1 -1
  678. package/dist/utils/wsl.d.ts +3 -0
  679. package/dist/utils/wsl.d.ts.map +1 -0
  680. package/dist/utils/wsl.js +15 -0
  681. package/dist/utils/wsl.js.map +1 -0
  682. package/dist/utils/zip.d.ts +7 -0
  683. package/dist/utils/zip.d.ts.map +1 -0
  684. package/dist/utils/zip.js +60 -0
  685. package/dist/utils/zip.js.map +1 -0
  686. package/docs/cli-integration.md +106 -0
  687. package/docs/cli.md +333 -0
  688. package/docs/codemode.md +230 -0
  689. package/docs/compaction.md +47 -28
  690. package/docs/configuration.md +47 -0
  691. package/docs/containerization.md +109 -82
  692. package/docs/custom-provider.md +109 -713
  693. package/docs/docs.json +148 -96
  694. package/docs/environment-variables.md +18 -3
  695. package/docs/extensions.md +284 -604
  696. package/docs/how-pi-works.md +49 -0
  697. package/docs/images/interactive-mode.png +0 -0
  698. package/docs/index.md +24 -69
  699. package/docs/json.md +193 -65
  700. package/docs/keybindings.md +58 -103
  701. package/docs/llama-cpp.md +24 -4
  702. package/docs/mcp.md +272 -0
  703. package/docs/message-types.md +279 -0
  704. package/docs/models.md +124 -489
  705. package/docs/nvidia-rtx-llama-cpp.md +96 -0
  706. package/docs/packages.md +67 -166
  707. package/docs/prompt-templates.md +31 -68
  708. package/docs/providers.md +158 -228
  709. package/docs/quickstart.md +61 -106
  710. package/docs/rpc-commands.md +860 -0
  711. package/docs/rpc-extension-ui.md +200 -0
  712. package/docs/rpc.md +131 -1554
  713. package/docs/sdk.md +79 -1158
  714. package/docs/security.md +72 -32
  715. package/docs/session-format.md +58 -215
  716. package/docs/sessions.md +35 -114
  717. package/docs/settings.md +98 -326
  718. package/docs/shell-aliases.md +85 -5
  719. package/docs/skills.md +51 -190
  720. package/docs/slash-commands.md +60 -0
  721. package/docs/subagents.md +2 -0
  722. package/docs/terminal-setup.md +7 -182
  723. package/docs/termux.md +74 -83
  724. package/docs/themes.md +89 -273
  725. package/docs/tmux.md +31 -39
  726. package/docs/tui.md +74 -910
  727. package/docs/usage.md +52 -129
  728. package/docs/virtual-models.md +114 -0
  729. package/docs/windows.md +45 -17
  730. package/examples/README.md +13 -5
  731. package/examples/extensions/README.md +4 -30
  732. package/examples/extensions/custom-provider-anthropic/index.ts +18 -12
  733. package/examples/extensions/custom-provider-anthropic/package-lock.json +2 -2
  734. package/examples/extensions/custom-provider-anthropic/package.json +17 -17
  735. package/examples/extensions/custom-provider-gitlab-duo/index.ts +2 -2
  736. package/examples/extensions/custom-provider-gitlab-duo/package.json +14 -14
  737. package/examples/extensions/custom-provider-gitlab-duo/test.ts +5 -5
  738. package/examples/extensions/debug-provider.ts +69 -0
  739. package/examples/extensions/dynamic-resources/dynamic.json +1 -1
  740. package/examples/extensions/gondolin/package-lock.json +5 -5
  741. package/examples/extensions/gondolin/package.json +1 -1
  742. package/examples/extensions/jev-router.ts +113 -0
  743. package/examples/extensions/prompt-customizer.ts +19 -67
  744. package/examples/extensions/sandbox/package-lock.json +2 -2
  745. package/examples/extensions/sandbox/package.json +1 -1
  746. package/examples/extensions/with-deps/package-lock.json +2 -2
  747. package/examples/extensions/with-deps/package.json +20 -20
  748. package/examples/rpc-client.ts +35 -0
  749. package/examples/sdk/14-codemode-mcp.ts +61 -0
  750. package/examples/sdk/README.md +3 -2
  751. package/npm-shrinkwrap.json +2425 -0
  752. package/package.json +20 -29
  753. package/schemas/models.schema.json +1157 -0
  754. package/schemas/settings.schema.json +734 -0
  755. package/schemas/theme.schema.json +365 -0
  756. package/dist/bundle/chunks/anthropic-messages-ASRU76PT.js +0 -6
  757. package/dist/bundle/chunks/azure-openai-responses-UGF6LMEX.js +0 -2
  758. package/dist/bundle/chunks/chunk-5PRUVL6W.js +0 -1770
  759. package/dist/bundle/chunks/chunk-6R7UI4IY.js +0 -2
  760. package/dist/bundle/chunks/chunk-A3JYRWB6.js +0 -2
  761. package/dist/bundle/chunks/chunk-CHB3CEFP.js +0 -2
  762. package/dist/bundle/chunks/chunk-ELBMWBDG.js +0 -11
  763. package/dist/bundle/chunks/chunk-GMWCTUPB.js +0 -2
  764. package/dist/bundle/chunks/chunk-GTBU4EAF.js +0 -2
  765. package/dist/bundle/chunks/chunk-NUHFSC37.js +0 -25
  766. package/dist/bundle/chunks/chunk-UIWY7TU5.js +0 -42
  767. package/dist/bundle/chunks/chunk-XNGRGP62.js +0 -2
  768. package/dist/bundle/chunks/google-generative-ai-VCD2PGIY.js +0 -2
  769. package/dist/bundle/chunks/google-vertex-L6U34ZRC.js +0 -2
  770. package/dist/bundle/chunks/mistral-conversations-IXWQ2YKN.js +0 -5
  771. package/dist/bundle/chunks/node-5YXRXMVN.js +0 -16
  772. package/dist/bundle/chunks/openai-codex-responses-P7HKQLIT.js +0 -10
  773. package/dist/bundle/chunks/openai-completions-O7BFLP3U.js +0 -7
  774. package/dist/bundle/chunks/openai-responses-QAKWAYVG.js +0 -2
  775. package/dist/cli/config-selector.d.ts +0 -16
  776. package/dist/cli/config-selector.d.ts.map +0 -1
  777. package/dist/cli/config-selector.js +0 -32
  778. package/dist/cli/config-selector.js.map +0 -1
  779. package/dist/cli/session-picker.d.ts +0 -10
  780. package/dist/cli/session-picker.d.ts.map +0 -1
  781. package/dist/cli/session-picker.js +0 -36
  782. package/dist/cli/session-picker.js.map +0 -1
  783. package/dist/cli/startup-ui.d.ts +0 -20
  784. package/dist/cli/startup-ui.d.ts.map +0 -1
  785. package/dist/cli/startup-ui.js +0 -185
  786. package/dist/cli/startup-ui.js.map +0 -1
  787. package/dist/core/keybindings.d.ts +0 -428
  788. package/dist/core/keybindings.d.ts.map +0 -1
  789. package/dist/core/keybindings.js +0 -321
  790. package/dist/core/keybindings.js.map +0 -1
  791. package/dist/core/tools/render-utils.d.ts +0 -24
  792. package/dist/core/tools/render-utils.d.ts.map +0 -1
  793. package/dist/core/tools/render-utils.js +0 -65
  794. package/dist/core/tools/render-utils.js.map +0 -1
  795. package/dist/core/tools/renderers/bash.d.ts +0 -12
  796. package/dist/core/tools/renderers/bash.d.ts.map +0 -1
  797. package/dist/core/tools/renderers/bash.js +0 -130
  798. package/dist/core/tools/renderers/bash.js.map +0 -1
  799. package/dist/core/tools/renderers/edit.d.ts +0 -23
  800. package/dist/core/tools/renderers/edit.d.ts.map +0 -1
  801. package/dist/core/tools/renderers/edit.js +0 -167
  802. package/dist/core/tools/renderers/edit.js.map +0 -1
  803. package/dist/core/tools/renderers/find.d.ts +0 -10
  804. package/dist/core/tools/renderers/find.d.ts.map +0 -1
  805. package/dist/core/tools/renderers/find.js +0 -64
  806. package/dist/core/tools/renderers/find.js.map +0 -1
  807. package/dist/core/tools/renderers/grep.d.ts +0 -10
  808. package/dist/core/tools/renderers/grep.d.ts.map +0 -1
  809. package/dist/core/tools/renderers/grep.js +0 -69
  810. package/dist/core/tools/renderers/grep.js.map +0 -1
  811. package/dist/core/tools/renderers/index.d.ts +0 -28
  812. package/dist/core/tools/renderers/index.d.ts.map +0 -1
  813. package/dist/core/tools/renderers/index.js +0 -47
  814. package/dist/core/tools/renderers/index.js.map +0 -1
  815. package/dist/core/tools/renderers/ls.d.ts +0 -10
  816. package/dist/core/tools/renderers/ls.d.ts.map +0 -1
  817. package/dist/core/tools/renderers/ls.js +0 -58
  818. package/dist/core/tools/renderers/ls.js.map +0 -1
  819. package/dist/core/tools/renderers/read.d.ts +0 -11
  820. package/dist/core/tools/renderers/read.d.ts.map +0 -1
  821. package/dist/core/tools/renderers/read.js +0 -129
  822. package/dist/core/tools/renderers/read.js.map +0 -1
  823. package/dist/core/tools/renderers/write.d.ts +0 -10
  824. package/dist/core/tools/renderers/write.d.ts.map +0 -1
  825. package/dist/core/tools/renderers/write.js +0 -153
  826. package/dist/core/tools/renderers/write.js.map +0 -1
  827. package/dist/extensions/mcp/mcp-client.d.ts +0 -31
  828. package/dist/extensions/mcp/mcp-client.d.ts.map +0 -1
  829. package/dist/extensions/mcp/mcp-client.js +0 -149
  830. package/dist/extensions/mcp/mcp-client.js.map +0 -1
  831. package/dist/extensions/mcp/mcp-config.d.ts +0 -47
  832. package/dist/extensions/mcp/mcp-config.d.ts.map +0 -1
  833. package/dist/extensions/mcp/mcp-config.js +0 -281
  834. package/dist/extensions/mcp/mcp-config.js.map +0 -1
  835. package/dist/extensions/mcp/mcp-transport.d.ts +0 -65
  836. package/dist/extensions/mcp/mcp-transport.d.ts.map +0 -1
  837. package/dist/extensions/mcp/mcp-transport.js +0 -278
  838. package/dist/extensions/mcp/mcp-transport.js.map +0 -1
  839. package/dist/modes/interactive/assets/clankolas.png +0 -0
  840. package/dist/modes/interactive/chat-viewport.d.ts +0 -20
  841. package/dist/modes/interactive/chat-viewport.d.ts.map +0 -1
  842. package/dist/modes/interactive/chat-viewport.js +0 -28
  843. package/dist/modes/interactive/chat-viewport.js.map +0 -1
  844. package/dist/modes/interactive/components/armin.d.ts +0 -34
  845. package/dist/modes/interactive/components/armin.d.ts.map +0 -1
  846. package/dist/modes/interactive/components/armin.js +0 -333
  847. package/dist/modes/interactive/components/armin.js.map +0 -1
  848. package/dist/modes/interactive/components/assistant-message.d.ts +0 -26
  849. package/dist/modes/interactive/components/assistant-message.d.ts.map +0 -1
  850. package/dist/modes/interactive/components/assistant-message.js +0 -158
  851. package/dist/modes/interactive/components/assistant-message.js.map +0 -1
  852. package/dist/modes/interactive/components/bash-execution.d.ts +0 -34
  853. package/dist/modes/interactive/components/bash-execution.d.ts.map +0 -1
  854. package/dist/modes/interactive/components/bash-execution.js +0 -175
  855. package/dist/modes/interactive/components/bash-execution.js.map +0 -1
  856. package/dist/modes/interactive/components/bordered-loader.d.ts +0 -16
  857. package/dist/modes/interactive/components/bordered-loader.d.ts.map +0 -1
  858. package/dist/modes/interactive/components/bordered-loader.js +0 -54
  859. package/dist/modes/interactive/components/bordered-loader.js.map +0 -1
  860. package/dist/modes/interactive/components/branch-summary-message.d.ts +0 -16
  861. package/dist/modes/interactive/components/branch-summary-message.d.ts.map +0 -1
  862. package/dist/modes/interactive/components/branch-summary-message.js +0 -44
  863. package/dist/modes/interactive/components/branch-summary-message.js.map +0 -1
  864. package/dist/modes/interactive/components/compaction-summary-message.d.ts +0 -16
  865. package/dist/modes/interactive/components/compaction-summary-message.d.ts.map +0 -1
  866. package/dist/modes/interactive/components/compaction-summary-message.js +0 -45
  867. package/dist/modes/interactive/components/compaction-summary-message.js.map +0 -1
  868. package/dist/modes/interactive/components/config-selector.d.ts +0 -102
  869. package/dist/modes/interactive/components/config-selector.d.ts.map +0 -1
  870. package/dist/modes/interactive/components/config-selector.js +0 -761
  871. package/dist/modes/interactive/components/config-selector.js.map +0 -1
  872. package/dist/modes/interactive/components/countdown-timer.d.ts +0 -14
  873. package/dist/modes/interactive/components/countdown-timer.d.ts.map +0 -1
  874. package/dist/modes/interactive/components/countdown-timer.js +0 -33
  875. package/dist/modes/interactive/components/countdown-timer.js.map +0 -1
  876. package/dist/modes/interactive/components/custom-editor.d.ts +0 -30
  877. package/dist/modes/interactive/components/custom-editor.d.ts.map +0 -1
  878. package/dist/modes/interactive/components/custom-editor.js +0 -115
  879. package/dist/modes/interactive/components/custom-editor.js.map +0 -1
  880. package/dist/modes/interactive/components/custom-entry.d.ts +0 -19
  881. package/dist/modes/interactive/components/custom-entry.d.ts.map +0 -1
  882. package/dist/modes/interactive/components/custom-entry.js +0 -52
  883. package/dist/modes/interactive/components/custom-entry.js.map +0 -1
  884. package/dist/modes/interactive/components/custom-message.d.ts +0 -22
  885. package/dist/modes/interactive/components/custom-message.d.ts.map +0 -1
  886. package/dist/modes/interactive/components/custom-message.js +0 -87
  887. package/dist/modes/interactive/components/custom-message.js.map +0 -1
  888. package/dist/modes/interactive/components/daxnuts.d.ts +0 -23
  889. package/dist/modes/interactive/components/daxnuts.d.ts.map +0 -1
  890. package/dist/modes/interactive/components/daxnuts.js +0 -140
  891. package/dist/modes/interactive/components/daxnuts.js.map +0 -1
  892. package/dist/modes/interactive/components/diff.d.ts +0 -12
  893. package/dist/modes/interactive/components/diff.d.ts.map +0 -1
  894. package/dist/modes/interactive/components/diff.js +0 -133
  895. package/dist/modes/interactive/components/diff.js.map +0 -1
  896. package/dist/modes/interactive/components/dynamic-border.d.ts +0 -15
  897. package/dist/modes/interactive/components/dynamic-border.d.ts.map +0 -1
  898. package/dist/modes/interactive/components/dynamic-border.js +0 -21
  899. package/dist/modes/interactive/components/dynamic-border.js.map +0 -1
  900. package/dist/modes/interactive/components/earendil-announcement.d.ts +0 -5
  901. package/dist/modes/interactive/components/earendil-announcement.d.ts.map +0 -1
  902. package/dist/modes/interactive/components/earendil-announcement.js +0 -40
  903. package/dist/modes/interactive/components/earendil-announcement.js.map +0 -1
  904. package/dist/modes/interactive/components/extension-editor.d.ts +0 -21
  905. package/dist/modes/interactive/components/extension-editor.d.ts.map +0 -1
  906. package/dist/modes/interactive/components/extension-editor.js +0 -98
  907. package/dist/modes/interactive/components/extension-editor.js.map +0 -1
  908. package/dist/modes/interactive/components/extension-input.d.ts +0 -23
  909. package/dist/modes/interactive/components/extension-input.d.ts.map +0 -1
  910. package/dist/modes/interactive/components/extension-input.js +0 -61
  911. package/dist/modes/interactive/components/extension-input.js.map +0 -1
  912. package/dist/modes/interactive/components/extension-selector.d.ts +0 -26
  913. package/dist/modes/interactive/components/extension-selector.d.ts.map +0 -1
  914. package/dist/modes/interactive/components/extension-selector.js +0 -83
  915. package/dist/modes/interactive/components/extension-selector.js.map +0 -1
  916. package/dist/modes/interactive/components/first-time-setup.d.ts +0 -25
  917. package/dist/modes/interactive/components/first-time-setup.d.ts.map +0 -1
  918. package/dist/modes/interactive/components/first-time-setup.js +0 -103
  919. package/dist/modes/interactive/components/first-time-setup.js.map +0 -1
  920. package/dist/modes/interactive/components/footer.d.ts +0 -32
  921. package/dist/modes/interactive/components/footer.d.ts.map +0 -1
  922. package/dist/modes/interactive/components/footer.js +0 -222
  923. package/dist/modes/interactive/components/footer.js.map +0 -1
  924. package/dist/modes/interactive/components/index.d.ts +0 -34
  925. package/dist/modes/interactive/components/index.d.ts.map +0 -1
  926. package/dist/modes/interactive/components/index.js +0 -35
  927. package/dist/modes/interactive/components/index.js.map +0 -1
  928. package/dist/modes/interactive/components/keybinding-hints.d.ts +0 -13
  929. package/dist/modes/interactive/components/keybinding-hints.d.ts.map +0 -1
  930. package/dist/modes/interactive/components/keybinding-hints.js +0 -36
  931. package/dist/modes/interactive/components/keybinding-hints.js.map +0 -1
  932. package/dist/modes/interactive/components/login-dialog.d.ts +0 -52
  933. package/dist/modes/interactive/components/login-dialog.d.ts.map +0 -1
  934. package/dist/modes/interactive/components/login-dialog.js +0 -188
  935. package/dist/modes/interactive/components/login-dialog.js.map +0 -1
  936. package/dist/modes/interactive/components/markdown-transform.d.ts +0 -3
  937. package/dist/modes/interactive/components/markdown-transform.d.ts.map +0 -1
  938. package/dist/modes/interactive/components/markdown-transform.js +0 -19
  939. package/dist/modes/interactive/components/markdown-transform.js.map +0 -1
  940. package/dist/modes/interactive/components/mermaid.d.ts +0 -11
  941. package/dist/modes/interactive/components/mermaid.d.ts.map +0 -1
  942. package/dist/modes/interactive/components/mermaid.js +0 -75
  943. package/dist/modes/interactive/components/mermaid.js.map +0 -1
  944. package/dist/modes/interactive/components/model-selector.d.ts +0 -60
  945. package/dist/modes/interactive/components/model-selector.d.ts.map +0 -1
  946. package/dist/modes/interactive/components/model-selector.js +0 -361
  947. package/dist/modes/interactive/components/model-selector.js.map +0 -1
  948. package/dist/modes/interactive/components/oauth-selector.d.ts +0 -33
  949. package/dist/modes/interactive/components/oauth-selector.d.ts.map +0 -1
  950. package/dist/modes/interactive/components/oauth-selector.js +0 -163
  951. package/dist/modes/interactive/components/oauth-selector.js.map +0 -1
  952. package/dist/modes/interactive/components/question-selector.d.ts +0 -24
  953. package/dist/modes/interactive/components/question-selector.d.ts.map +0 -1
  954. package/dist/modes/interactive/components/question-selector.js +0 -158
  955. package/dist/modes/interactive/components/question-selector.js.map +0 -1
  956. package/dist/modes/interactive/components/scoped-models-selector.d.ts +0 -46
  957. package/dist/modes/interactive/components/scoped-models-selector.d.ts.map +0 -1
  958. package/dist/modes/interactive/components/scoped-models-selector.js +0 -326
  959. package/dist/modes/interactive/components/scoped-models-selector.js.map +0 -1
  960. package/dist/modes/interactive/components/session-selector-search.d.ts +0 -23
  961. package/dist/modes/interactive/components/session-selector-search.d.ts.map +0 -1
  962. package/dist/modes/interactive/components/session-selector-search.js +0 -155
  963. package/dist/modes/interactive/components/session-selector-search.js.map +0 -1
  964. package/dist/modes/interactive/components/session-selector.d.ts +0 -95
  965. package/dist/modes/interactive/components/session-selector.d.ts.map +0 -1
  966. package/dist/modes/interactive/components/session-selector.js +0 -867
  967. package/dist/modes/interactive/components/session-selector.js.map +0 -1
  968. package/dist/modes/interactive/components/settings-selector.d.ts +0 -92
  969. package/dist/modes/interactive/components/settings-selector.d.ts.map +0 -1
  970. package/dist/modes/interactive/components/settings-selector.js +0 -709
  971. package/dist/modes/interactive/components/settings-selector.js.map +0 -1
  972. package/dist/modes/interactive/components/settings-submenu.d.ts +0 -72
  973. package/dist/modes/interactive/components/settings-submenu.d.ts.map +0 -1
  974. package/dist/modes/interactive/components/settings-submenu.js +0 -165
  975. package/dist/modes/interactive/components/settings-submenu.js.map +0 -1
  976. package/dist/modes/interactive/components/show-images-selector.d.ts +0 -10
  977. package/dist/modes/interactive/components/show-images-selector.d.ts.map +0 -1
  978. package/dist/modes/interactive/components/show-images-selector.js +0 -39
  979. package/dist/modes/interactive/components/show-images-selector.js.map +0 -1
  980. package/dist/modes/interactive/components/skill-invocation-message.d.ts +0 -17
  981. package/dist/modes/interactive/components/skill-invocation-message.d.ts.map +0 -1
  982. package/dist/modes/interactive/components/skill-invocation-message.js +0 -47
  983. package/dist/modes/interactive/components/skill-invocation-message.js.map +0 -1
  984. package/dist/modes/interactive/components/status-indicator.d.ts +0 -30
  985. package/dist/modes/interactive/components/status-indicator.d.ts.map +0 -1
  986. package/dist/modes/interactive/components/status-indicator.js +0 -67
  987. package/dist/modes/interactive/components/status-indicator.js.map +0 -1
  988. package/dist/modes/interactive/components/theme-selector.d.ts +0 -11
  989. package/dist/modes/interactive/components/theme-selector.d.ts.map +0 -1
  990. package/dist/modes/interactive/components/theme-selector.js +0 -50
  991. package/dist/modes/interactive/components/theme-selector.js.map +0 -1
  992. package/dist/modes/interactive/components/thinking-selector.d.ts +0 -23
  993. package/dist/modes/interactive/components/thinking-selector.d.ts.map +0 -1
  994. package/dist/modes/interactive/components/thinking-selector.js +0 -109
  995. package/dist/modes/interactive/components/thinking-selector.js.map +0 -1
  996. package/dist/modes/interactive/components/tool-execution.d.ts +0 -80
  997. package/dist/modes/interactive/components/tool-execution.d.ts.map +0 -1
  998. package/dist/modes/interactive/components/tool-execution.js +0 -328
  999. package/dist/modes/interactive/components/tool-execution.js.map +0 -1
  1000. package/dist/modes/interactive/components/tree-selector.d.ts +0 -94
  1001. package/dist/modes/interactive/components/tree-selector.d.ts.map +0 -1
  1002. package/dist/modes/interactive/components/tree-selector.js +0 -1245
  1003. package/dist/modes/interactive/components/tree-selector.js.map +0 -1
  1004. package/dist/modes/interactive/components/trust-selector.d.ts +0 -23
  1005. package/dist/modes/interactive/components/trust-selector.d.ts.map +0 -1
  1006. package/dist/modes/interactive/components/trust-selector.js +0 -91
  1007. package/dist/modes/interactive/components/trust-selector.js.map +0 -1
  1008. package/dist/modes/interactive/components/user-message-selector.d.ts +0 -30
  1009. package/dist/modes/interactive/components/user-message-selector.d.ts.map +0 -1
  1010. package/dist/modes/interactive/components/user-message-selector.js +0 -114
  1011. package/dist/modes/interactive/components/user-message-selector.js.map +0 -1
  1012. package/dist/modes/interactive/components/user-message.d.ts +0 -16
  1013. package/dist/modes/interactive/components/user-message.d.ts.map +0 -1
  1014. package/dist/modes/interactive/components/user-message.js +0 -49
  1015. package/dist/modes/interactive/components/user-message.js.map +0 -1
  1016. package/dist/modes/interactive/components/visual-truncate.d.ts +0 -24
  1017. package/dist/modes/interactive/components/visual-truncate.d.ts.map +0 -1
  1018. package/dist/modes/interactive/components/visual-truncate.js +0 -33
  1019. package/dist/modes/interactive/components/visual-truncate.js.map +0 -1
  1020. package/dist/modes/interactive/external-editor.d.ts +0 -12
  1021. package/dist/modes/interactive/external-editor.d.ts.map +0 -1
  1022. package/dist/modes/interactive/external-editor.js +0 -38
  1023. package/dist/modes/interactive/external-editor.js.map +0 -1
  1024. package/dist/modes/interactive/interactive-mode.d.ts +0 -443
  1025. package/dist/modes/interactive/interactive-mode.d.ts.map +0 -1
  1026. package/dist/modes/interactive/interactive-mode.js +0 -5604
  1027. package/dist/modes/interactive/interactive-mode.js.map +0 -1
  1028. package/dist/modes/interactive/model-catalog-refresh.d.ts.map +0 -1
  1029. package/dist/modes/interactive/model-catalog-refresh.js.map +0 -1
  1030. package/dist/modes/interactive/model-search.d.ts +0 -12
  1031. package/dist/modes/interactive/model-search.d.ts.map +0 -1
  1032. package/dist/modes/interactive/model-search.js +0 -15
  1033. package/dist/modes/interactive/model-search.js.map +0 -1
  1034. package/dist/modes/interactive/session-share.d.ts +0 -16
  1035. package/dist/modes/interactive/session-share.d.ts.map +0 -1
  1036. package/dist/modes/interactive/session-share.js +0 -184
  1037. package/dist/modes/interactive/session-share.js.map +0 -1
  1038. package/dist/modes/interactive/theme/dark.json +0 -91
  1039. package/dist/modes/interactive/theme/light.json +0 -90
  1040. package/dist/modes/interactive/theme/theme-controller.d.ts +0 -41
  1041. package/dist/modes/interactive/theme/theme-controller.d.ts.map +0 -1
  1042. package/dist/modes/interactive/theme/theme-controller.js +0 -130
  1043. package/dist/modes/interactive/theme/theme-controller.js.map +0 -1
  1044. package/dist/modes/interactive/theme/theme-json.d.ts +0 -84
  1045. package/dist/modes/interactive/theme/theme-json.d.ts.map +0 -1
  1046. package/dist/modes/interactive/theme/theme-json.js +0 -130
  1047. package/dist/modes/interactive/theme/theme-json.js.map +0 -1
  1048. package/dist/modes/interactive/theme/theme-schema.json +0 -356
  1049. package/dist/modes/interactive/theme/theme.d.ts +0 -131
  1050. package/dist/modes/interactive/theme/theme.d.ts.map +0 -1
  1051. package/dist/modes/interactive/theme/theme.js.map +0 -1
  1052. package/dist/modes/interactive/tui-renderer.d.ts +0 -21
  1053. package/dist/modes/interactive/tui-renderer.d.ts.map +0 -1
  1054. package/dist/modes/interactive/tui-renderer.js +0 -66
  1055. package/dist/modes/interactive/tui-renderer.js.map +0 -1
  1056. package/docs/development.md +0 -90
  1057. package/examples/extensions/border-status-editor.ts +0 -145
  1058. package/examples/extensions/built-in-tool-renderer.ts +0 -249
  1059. package/examples/extensions/custom-footer.ts +0 -64
  1060. package/examples/extensions/custom-header.ts +0 -73
  1061. package/examples/extensions/doom-overlay/README.md +0 -46
  1062. package/examples/extensions/doom-overlay/doom/build/doom.js +0 -21
  1063. package/examples/extensions/doom-overlay/doom/build/doom.wasm +0 -0
  1064. package/examples/extensions/doom-overlay/doom/build.sh +0 -152
  1065. package/examples/extensions/doom-overlay/doom/doomgeneric_pi.c +0 -72
  1066. package/examples/extensions/doom-overlay/doom-component.ts +0 -132
  1067. package/examples/extensions/doom-overlay/doom-engine.ts +0 -173
  1068. package/examples/extensions/doom-overlay/doom-keys.ts +0 -104
  1069. package/examples/extensions/doom-overlay/index.ts +0 -74
  1070. package/examples/extensions/doom-overlay/wad-finder.ts +0 -55
  1071. package/examples/extensions/entry-renderer.ts +0 -41
  1072. package/examples/extensions/github-issue-autocomplete.ts +0 -185
  1073. package/examples/extensions/handoff.ts +0 -190
  1074. package/examples/extensions/interactive-shell.ts +0 -196
  1075. package/examples/extensions/kimi-deferred-tools.ts +0 -61
  1076. package/examples/extensions/message-renderer.ts +0 -59
  1077. package/examples/extensions/minimal-mode.ts +0 -426
  1078. package/examples/extensions/modal-editor.ts +0 -85
  1079. package/examples/extensions/overlay-qa-tests.ts +0 -1450
  1080. package/examples/extensions/overlay-test.ts +0 -153
  1081. package/examples/extensions/plan-mode/README.md +0 -66
  1082. package/examples/extensions/plan-mode/index.ts +0 -390
  1083. package/examples/extensions/plan-mode/utils.ts +0 -168
  1084. package/examples/extensions/preset.ts +0 -436
  1085. package/examples/extensions/qna.ts +0 -118
  1086. package/examples/extensions/question.ts +0 -278
  1087. package/examples/extensions/questionnaire.ts +0 -440
  1088. package/examples/extensions/rainbow-editor.ts +0 -88
  1089. package/examples/extensions/snake.ts +0 -343
  1090. package/examples/extensions/space-invaders.ts +0 -560
  1091. package/examples/extensions/structured-output.ts +0 -65
  1092. package/examples/extensions/summarize.ts +0 -199
  1093. package/examples/extensions/tic-tac-toe.ts +0 -1008
  1094. package/examples/extensions/todo.ts +0 -297
  1095. package/examples/extensions/tools.ts +0 -146
  1096. package/examples/extensions/truncated-tool.ts +0 -195
  1097. package/examples/plugins/pi-example-plugin/README.md +0 -38
  1098. package/examples/plugins/pi-example-plugin/package.json +0 -10
  1099. package/examples/plugins/pi-example-plugin/src/contract.ts +0 -13
  1100. package/examples/plugins/pi-example-plugin/src/session.ts +0 -23
  1101. package/examples/plugins/pi-example-plugin/src/tui.ts +0 -31
  1102. package/examples/rpc-extension-ui.ts +0 -641
  1103. /package/dist/bundle/chunks/{chunk-PATAL4PO.js → chunk-7ZC4UXSL.js} +0 -0
package/docs/sdk.md CHANGED
@@ -1,1226 +1,147 @@
1
- > pi can help you use the SDK. Ask it to build an integration for your use case.
2
-
3
1
  # SDK
4
2
 
5
- The SDK provides programmatic access to pi's agent capabilities. Use it to embed pi in other applications, build custom interfaces, or integrate with automated workflows.
6
-
7
- **Example use cases:**
8
- - Build a custom UI (web, desktop, mobile)
9
- - Integrate agent capabilities into existing applications
10
- - Create automated pipelines with agent reasoning
11
- - Build custom tools that spawn sub-agents
12
- - Test agent behavior programmatically
13
-
14
- See [examples/sdk/](../examples/sdk/) for working examples from minimal to full control.
15
-
16
- ## Quick Start
17
-
18
- ```typescript
19
- import { createAgentSession, ModelRuntime, SessionManager } from "@punch-bot/cli";
20
-
21
- const modelRuntime = await ModelRuntime.create();
22
- const { session } = await createAgentSession({
23
- sessionManager: SessionManager.inMemory(),
24
- modelRuntime,
25
- });
26
-
27
- session.subscribe((event) => {
28
- if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
29
- process.stdout.write(event.assistantMessageEvent.delta);
30
- }
31
- });
32
-
33
- await session.prompt("What files are in the current directory?");
34
- ```
35
-
36
- ## Installation
37
-
38
- ```bash
39
- npm install @punch-bot/cli
40
- ```
41
-
42
- The SDK is included in the main package. No separate installation needed.
43
-
44
- ## Core Concepts
45
-
46
- ### createAgentSession()
3
+ `@punch-bot/cli` embeds Pi in a Node.js or Bun process. It provides direct TypeScript access to the agent, sessions, tools, models, and resources used by the command-line application.
47
4
 
48
- The main factory function for a single `AgentSession`.
49
-
50
- `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.
5
+ Use the SDK for in-process TypeScript integration. For a language-independent or isolated subprocess, see [CLI Integration](cli-integration.md).
51
6
 
52
7
  ```typescript
53
- import { createAgentSession, SessionManager } from "@punch-bot/cli";
8
+ import { createAgentSession } from "@punch-bot/cli";
54
9
 
55
- // Minimal: defaults with DefaultResourceLoader
56
10
  const { session } = await createAgentSession();
57
11
 
58
- // Custom: override specific options
59
- const { session } = await createAgentSession({
60
- model: myModel,
61
- tools: ["read", "bash"],
62
- sessionManager: SessionManager.inMemory(),
63
- });
64
- ```
65
-
66
- ### AgentSession
67
-
68
- The session manages agent lifecycle, message history, model state, compaction, and event streaming.
69
-
70
- ```typescript
71
- interface AgentSession {
72
- // Send a prompt and wait for completion
73
- prompt(text: string, options?: PromptOptions): Promise<void>;
74
-
75
- // Queue messages during streaming
76
- steer(text: string): Promise<void>;
77
- followUp(text: string): Promise<void>;
78
-
79
- // Subscribe to events (returns unsubscribe function)
80
- subscribe(listener: (event: AgentSessionEvent) => void): () => void;
81
-
82
- // Session info
83
- sessionFile: string | undefined;
84
- sessionId: string;
85
-
86
- // Model control
87
- setModel(model: Model): Promise<void>;
88
- setThinkingLevel(level: ThinkingLevel): void;
89
- cycleModel(): Promise<ModelCycleResult | undefined>;
90
- cycleThinkingLevel(): ThinkingLevel | undefined;
91
-
92
- // State access
93
- agent: Agent;
94
- model: Model | undefined;
95
- thinkingLevel: ThinkingLevel;
96
- messages: AgentMessage[];
97
- isStreaming: boolean;
98
-
99
- // In-place tree navigation within the current session file
100
- navigateTree(targetId: string, options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string }): Promise<{ editorText?: string; cancelled: boolean }>;
101
-
102
- // Compaction
103
- compact(customInstructions?: string): Promise<CompactionResult>;
104
- abortCompaction(): void;
105
-
106
- // Abort current operation
107
- abort(): Promise<void>;
108
-
109
- // Cleanup
110
- dispose(): void;
12
+ try {
13
+ await session.prompt("What files are in the current directory?");
14
+ console.log(session.getLastAssistantText());
15
+ } finally {
16
+ session.dispose();
111
17
  }
112
18
  ```
113
19
 
114
- `session.navigateTree()` rejects while an agent response, manual or automatic compaction, or another tree navigation is active, even with `summarize: false`. It does not queue navigation or return `{ cancelled: true }` for these conflicts. Wait for the active operation to finish (for example, with `await session.waitForIdle()`) and retry. Rejection leaves the active branch unchanged.
20
+ This uses the working directory, discovered resources, stored settings, and configured credentials. `prompt()` resolves when the run finishes.
115
21
 
116
- Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
22
+ The [complete minimal example](../examples/sdk/01-minimal.ts) also streams text events. All [SDK examples](../examples/sdk/) are typechecked with the repository.
117
23
 
118
- ### createAgentSessionRuntime() and AgentSessionRuntime
24
+ <a id="session-management"></a>
119
25
 
120
- Use the runtime API when you need to replace the active session and rebuild cwd-bound runtime state.
121
- This is the same layer used by the built-in interactive, print, and RPC modes.
26
+ ## Session lifecycle
122
27
 
123
- `createAgentSessionRuntime()` takes a runtime factory plus the initial cwd/session target. The factory closes over process-global fixed inputs, recreates cwd-bound services for the effective cwd, resolves session options against those services, and returns a full runtime result.
28
+ `createAgentSession()` creates an `AgentSession`. The session owns one conversation, its model and tools, queued messages, compaction state, and extension runtime.
124
29
 
125
- ```typescript
126
- import {
127
- type CreateAgentSessionRuntimeFactory,
128
- createAgentSessionFromServices,
129
- createAgentSessionRuntime,
130
- createAgentSessionServices,
131
- getAgentDir,
132
- SessionManager,
133
- } from "@punch-bot/cli";
30
+ Read current state through `session.messages`, `session.model`, `session.thinkingLevel`, `session.systemPrompt`, and `session.getActiveToolNames()`.
134
31
 
135
- const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
136
- const services = await createAgentSessionServices({ cwd });
137
- return {
138
- ...(await createAgentSessionFromServices({
139
- services,
140
- sessionManager,
141
- sessionStartEvent,
142
- })),
143
- services,
144
- diagnostics: services.diagnostics,
145
- };
146
- };
32
+ `session.systemPrompt` is read-only and returns the current effective system prompt, including changes that have not yet been sent to the model. Tool changes are declared to the model before the next request.
147
33
 
148
- const runtime = await createAgentSessionRuntime(createRuntime, {
149
- cwd: process.cwd(),
150
- agentDir: getAgentDir(),
151
- sessionManager: SessionManager.create(process.cwd()),
152
- });
153
- ```
34
+ <a id="sessionmanager-api"></a>
154
35
 
155
- `AgentSessionRuntime` owns replacement of the active runtime across:
36
+ ### Session storage
156
37
 
157
- - `newSession()`
158
- - `switchSession()`
159
- - `fork()`
160
- - clone flows via `fork(entryId, { position: "at" })`
161
- - `importFromJsonl()`
38
+ Sessions are persistent by default. `SessionManager` owns the persisted or in-memory entry tree and tracks its active leaf. Branching changes that leaf without deleting abandoned branches. When Pi reconstructs model context, the manager selects the active branch and applies compaction.
162
39
 
163
- Important behavior:
40
+ `SessionManager` is authoritative for finalized model context. Restore external history by constructing the session with a manager containing those entries. Assigning `session.agent.state.messages` does not replace persisted context.
164
41
 
165
- - `runtime.session` changes after those operations
166
- - event subscriptions are attached to a specific `AgentSession`, so re-subscribe after replacement
167
- - if you use extensions, call `runtime.session.bindExtensions(...)` again for the new session
168
- - creation returns diagnostics on `runtime.diagnostics`
169
- - if runtime creation or replacement fails, the method throws and the caller decides how to handle it
170
-
171
- ```typescript
172
- let session = runtime.session;
173
- let unsubscribe = session.subscribe(() => {});
174
-
175
- await runtime.newSession();
176
-
177
- unsubscribe();
178
- session = runtime.session;
179
- unsubscribe = session.subscribe(() => {});
180
- ```
181
-
182
- ### Prompting and Message Queueing
183
-
184
- `PromptOptions` controls prompt expansion, queueing behavior while streaming, and prompt preflight notifications:
185
-
186
- ```typescript
187
- interface PromptOptions {
188
- expandPromptTemplates?: boolean;
189
- images?: ImageContent[];
190
- streamingBehavior?: "steer" | "followUp";
191
- source?: InputSource;
192
- preflightResult?: (success: boolean) => void;
193
- }
194
- ```
195
-
196
- `preflightResult` is called once per `prompt()` invocation:
197
-
198
- - `true` when the prompt was accepted, queued, or handled immediately
199
- - `false` when prompt preflight rejected before acceptance
200
-
201
- 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)`.
202
-
203
- The `prompt()` method handles prompt templates, extension commands, and message sending:
204
-
205
- ```typescript
206
- // Basic prompt (when not streaming)
207
- await session.prompt("What files are here?");
208
-
209
- // With images
210
- await session.prompt("What's in this image?", {
211
- images: [{ type: "image", source: { type: "base64", mediaType: "image/png", data: "..." } }]
212
- });
213
-
214
- // During streaming: must specify how to queue the message
215
- await session.prompt("Stop and do this instead", { streamingBehavior: "steer" });
216
- await session.prompt("After you're done, also check X", { streamingBehavior: "followUp" });
217
- ```
218
-
219
- **Behavior:**
220
- - **Extension commands** (e.g., `/mycommand`): Execute immediately, even during streaming. They manage their own LLM interaction via `pi.sendMessage()`.
221
- - **File-based prompt templates** (from `.md` files): Expanded to their content before sending or queueing.
222
- - **During streaming without `streamingBehavior`**: Throws an error. Use `steer()` or `followUp()` directly, or specify the option.
223
- - **`preflightResult(true)`**: Means the prompt was accepted, queued, or handled immediately.
224
- - **`preflightResult(false)`**: Means preflight rejected before acceptance.
225
-
226
- For explicit queueing during streaming:
227
-
228
- ```typescript
229
- // Queue a steering message for delivery after the current assistant turn finishes its tool calls
230
- await session.steer("New instruction");
231
-
232
- // Wait for agent to finish (delivered only when agent stops)
233
- await session.followUp("After you're done, also do this");
234
- ```
235
-
236
- Both `steer()` and `followUp()` expand file-based prompt templates but error on extension commands (extension commands cannot be queued).
237
-
238
- ### Agent and AgentState
239
-
240
- The `Agent` class (from `@punch-bot/agent`) handles the core LLM interaction. Access it via `session.agent`.
241
-
242
- ```typescript
243
- // Access current state
244
- const state = session.agent.state;
245
-
246
- // state.messages: AgentMessage[] - conversation history
247
- // state.model: Model - current model
248
- // state.thinkingLevel: ThinkingLevel - current thinking level
249
- // state.systemPrompt: string - system prompt
250
- // state.tools: AgentTool[] - available tools
251
- // state.streamingMessage?: AgentMessage - current partial assistant message
252
- // state.errorMessage?: string - latest assistant error
253
-
254
- // Replace messages (useful for branching or restoration)
255
- session.agent.state.messages = messages; // copies the top-level array
256
-
257
- // Replace tools
258
- session.agent.state.tools = tools; // copies the top-level array
259
-
260
- // Wait for agent to finish processing
261
- await session.agent.waitForIdle();
262
- ```
263
-
264
- ### Events
265
-
266
- Subscribe to events to receive streaming output and lifecycle notifications.
267
-
268
- ```typescript
269
- session.subscribe((event) => {
270
- switch (event.type) {
271
- // Streaming text from assistant
272
- case "message_update":
273
- if (event.assistantMessageEvent.type === "text_delta") {
274
- process.stdout.write(event.assistantMessageEvent.delta);
275
- }
276
- if (event.assistantMessageEvent.type === "thinking_delta") {
277
- // Thinking output (if thinking enabled)
278
- }
279
- break;
280
-
281
- // Tool execution
282
- case "tool_execution_start":
283
- console.log(`Tool: ${event.toolName}`);
284
- break;
285
- case "tool_execution_update":
286
- // Streaming tool output
287
- break;
288
- case "tool_execution_end":
289
- console.log(`Result: ${event.isError ? "error" : "success"}`);
290
- break;
291
-
292
- // Message lifecycle
293
- case "message_start":
294
- // New message starting
295
- break;
296
- case "message_end":
297
- // Message complete
298
- break;
299
-
300
- // Agent lifecycle
301
- case "agent_start":
302
- // Agent started processing prompt
303
- break;
304
- case "agent_end":
305
- // Agent finished (event.messages contains new messages)
306
- break;
307
-
308
- // Turn lifecycle (one LLM response + tool calls)
309
- case "turn_start":
310
- break;
311
- case "turn_end":
312
- // event.message: assistant response
313
- // event.toolResults: tool results from this turn
314
- break;
315
-
316
- // Session events (queue, compaction, retry)
317
- case "queue_update":
318
- console.log(event.steering, event.followUp);
319
- break;
320
- case "compaction_start":
321
- case "compaction_end":
322
- case "auto_retry_start":
323
- case "auto_retry_end":
324
- case "summarization_retry_scheduled":
325
- case "summarization_retry_attempt_start":
326
- case "summarization_retry_finished":
327
- break;
328
- }
329
- });
330
- ```
331
-
332
- ## Options Reference
333
-
334
- ### Directories
335
-
336
- ```typescript
337
- const { session } = await createAgentSession({
338
- // Working directory for DefaultResourceLoader discovery
339
- cwd: process.cwd(), // default
340
-
341
- // Global config directory
342
- agentDir: "~/.pi/agent", // default (expands ~)
343
- });
344
- ```
345
-
346
- `cwd` is used by `DefaultResourceLoader` for:
347
- - Project extensions (`.pi/extensions/`)
348
- - Project skills:
349
- - `.pi/skills/`
350
- - `.agents/skills/` in `cwd` and ancestor directories (up to git repo root, or filesystem root when not in a repo)
351
- - Project prompts (`.pi/prompts/`)
352
- - Context files (`AGENTS.md` walking up from cwd)
353
- - Session directory naming
354
-
355
- `agentDir` is used by `DefaultResourceLoader` for:
356
- - Global extensions (`extensions/`)
357
- - Global skills:
358
- - `skills/` under `agentDir` (for example `~/.pi/agent/skills/`)
359
- - `~/.agents/skills/`
360
- - Global prompts (`prompts/`)
361
- - Global context file (`AGENTS.md`)
362
- - Settings (`settings.json`)
363
- - Custom models (`models.json`)
364
- - Credentials (`auth.json`)
365
- - Sessions (`sessions/`)
366
-
367
- When you pass a custom `ResourceLoader`, `cwd` and `agentDir` no longer control resource discovery. They still influence session naming and tool path resolution.
368
-
369
- ### Model
370
-
371
- ```typescript
372
- import { getModel } from "@punch-bot/ai";
373
- import { ModelRuntime } from "@punch-bot/cli";
374
-
375
- const modelRuntime = await ModelRuntime.create();
376
-
377
- // create() restores cached catalogs but does not refresh them from pi.dev by default.
378
- // Opt in to a create-time network refresh and bound how long it may take:
379
- const refreshedRuntime = await ModelRuntime.create({
380
- allowModelNetwork: true,
381
- modelRefreshTimeoutMs: 15_000,
382
- });
383
-
384
- // Find specific built-in model (doesn't check if API key exists)
385
- const opus = getModel("anthropic", "claude-opus-4-5");
386
- if (!opus) throw new Error("Model not found");
387
-
388
- // Find any model by provider/id, including custom models from models.json
389
- // (doesn't check if API key exists)
390
- const customModel = modelRuntime.getModel("my-provider", "my-model");
391
-
392
- // Get only models that have valid authentication configured
393
- const available = await modelRuntime.getAvailable();
394
-
395
- const { session } = await createAgentSession({
396
- model: opus,
397
- thinkingLevel: "medium", // off, minimal, low, medium, high, xhigh, max
398
-
399
- // Models for cycling (Ctrl+P in interactive mode)
400
- scopedModels: [
401
- { model: opus, thinkingLevel: "high" },
402
- { model: haiku, thinkingLevel: "off" },
403
- ],
404
-
405
- modelRuntime,
406
- });
407
- ```
408
-
409
- If no model is provided:
410
- 1. Tries to restore from session (if continuing)
411
- 2. Uses default from settings
412
- 3. Falls back to first available model
413
-
414
- Remote catalogs are persisted locally so later runtimes can restore them without a network request. The default file is `~/.pi/agent/models-store.json`; set `modelsStorePath` to choose another location, or inject `modelsStore` to control persistence. Network refreshes are throttled to once per provider every four hours unless forced. To force an immediate refresh, call `await modelRuntime.refresh({ allowNetwork: true, force: true, signal })`. Setting `PI_OFFLINE` disables model network access.
415
-
416
- To match CLI model parsing, use the exported resolver helpers:
417
-
418
- ```typescript
419
- import {
420
- resolveCliModel,
421
- resolveModelScopeWithDiagnostics,
422
- } from "@punch-bot/cli";
423
-
424
- const cliModel = resolveCliModel({
425
- cliModel: "anthropic/claude-opus-4-5:high",
426
- modelRuntime,
427
- });
428
- if (cliModel.error) throw new Error(cliModel.error);
429
- if (cliModel.warning) console.warn(cliModel.warning);
430
-
431
- const { scopedModels, diagnostics } = await resolveModelScopeWithDiagnostics(
432
- ["anthropic/*:high", "gpt-5"],
433
- modelRuntime,
434
- );
435
- for (const diagnostic of diagnostics) {
436
- console.warn(diagnostic.message);
437
- }
438
- ```
439
-
440
- `resolveCliModel()` uses all registered models so `--api-key` style first-time setup can resolve a model before stored auth exists. `resolveModelScopeWithDiagnostics()` matches `--models` and `enabledModels` semantics while returning warnings instead of printing them.
441
-
442
- > See [examples/sdk/02-custom-model.ts](../examples/sdk/02-custom-model.ts)
443
-
444
- ### API Keys and OAuth
445
-
446
- Authentication resolution priority (handled by `ModelRuntime`):
447
- 1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
448
- 2. Stored credentials in `auth.json` (API keys or OAuth tokens)
449
- 3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
450
- 4. Fallback resolver (for custom provider keys from `models.json`)
451
-
452
- ```typescript
453
- import { InMemoryCredentialStore } from "@punch-bot/ai";
454
- import { createAgentSession, ModelRuntime } from "@punch-bot/cli";
455
-
456
- // Default: uses ~/.pi/agent/auth.json and ~/.pi/agent/models.json
457
- const modelRuntime = await ModelRuntime.create();
458
-
459
- // Provider-owned auth methods and current status
460
- for (const provider of modelRuntime.getProviders()) {
461
- const status = await modelRuntime.checkAuth(provider.id);
462
- console.log(provider.name, provider.auth, status);
463
- }
464
-
465
- // Runtime API key override (not persisted to disk)
466
- await modelRuntime.setRuntimeApiKey("anthropic", "sk-my-temp-key");
467
-
468
- // Custom credential and model locations
469
- const customRuntime = await ModelRuntime.create({
470
- authPath: "/my/app/auth.json",
471
- modelsPath: "/my/app/models.json",
472
- });
473
-
474
- // Or inject any pi-ai CredentialStore
475
- const credentials = new InMemoryCredentialStore();
476
- const inMemoryRuntime = await ModelRuntime.create({ credentials });
477
-
478
- const { session } = await createAgentSession({
479
- modelRuntime: customRuntime,
480
- });
481
- ```
482
-
483
- `login()`, `logout()`, `setRuntimeApiKey()`, and `removeRuntimeApiKey()` resolve after the affected provider's cached/built-in catalog, composition, and availability snapshot are locally consistent. They do not wait for remote catalog freshness. If credentials were committed but local synchronization fails, they reject with the exported `CredentialSynchronizationError`; inspect its `providerId`, `operation`, `credential`, and `cause` fields instead of retrying the credential mutation blindly.
484
-
485
- Public model/auth operations and `ModelRuntime.create({ signal })` accept optional abort signals and are unbounded when omitted. SDK applications own deadline policy for remote catalog freshness:
486
-
487
- ```typescript
488
- const signal = AbortSignal.timeout(15_000);
489
- const result = await modelRuntime.refresh({
490
- providers: ["anthropic"],
491
- signal,
492
- });
493
- if (result.aborted) console.warn("Catalog refresh timed out; using cached models");
494
- for (const [providerId, error] of result.errors) {
495
- console.warn(`Could not refresh ${providerId}:`, error);
496
- }
497
- ```
498
-
499
- A failed or timed-out network refresh does not undo a successful credential operation. `refresh()` starts a new provider generation, so it does not wait behind an older stalled refresh and stale generations cannot publish afterward.
500
-
501
- > See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
502
-
503
- ### System Prompt
504
-
505
- Use a `ResourceLoader` to override the system prompt:
506
-
507
- ```typescript
508
- import { createAgentSession, DefaultResourceLoader } from "@punch-bot/cli";
509
-
510
- const loader = new DefaultResourceLoader({
511
- systemPromptOverride: () => "You are a helpful assistant.",
512
- });
513
- await loader.reload();
514
-
515
- const { session } = await createAgentSession({ resourceLoader: loader });
516
- ```
517
-
518
- > See [examples/sdk/03-custom-prompt.ts](../examples/sdk/03-custom-prompt.ts)
519
-
520
- ### Tools
521
-
522
- Specify which built-in tools to enable:
523
-
524
- - Built-in tool names: `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`
525
- - Default built-ins: `read`, `bash`, `edit`, `write`
526
- - `noTools: "all"` disables all tools
527
- - `noTools: "builtin"` disables default built-ins while keeping extension and custom tools enabled
528
- - `excludeTools` disables specific built-in, extension, or custom tool names after any `tools` allowlist is applied
529
-
530
- The `edit` tool returns `details.diff` for Pi's TUI display and `details.patch` as a standard unified patch for SDK consumers.
531
-
532
- ```typescript
533
- import { createAgentSession } from "@punch-bot/cli";
534
-
535
- // Read-only mode
536
- const { session } = await createAgentSession({
537
- tools: ["read", "grep", "find", "ls"],
538
- });
539
-
540
- // Pick specific tools
541
- const { session } = await createAgentSession({
542
- tools: ["read", "bash", "grep"],
543
- });
544
-
545
- // Use PowerShell instead of Bash on Windows
546
- const { session } = await createAgentSession({
547
- tools: ["read", "powershell", "edit", "write"],
548
- });
549
-
550
- // Disable one tool while keeping the rest available
551
- const { session } = await createAgentSession({
552
- excludeTools: ["ask_question"],
553
- });
554
- ```
555
-
556
- #### Tools with Custom cwd
557
-
558
- When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd.
42
+ Use an in-memory manager when the host does not want session files:
559
43
 
560
44
  ```typescript
561
45
  import { createAgentSession, SessionManager } from "@punch-bot/cli";
562
46
 
563
- const cwd = "/path/to/project";
564
-
565
- // Use default tools for custom cwd
566
47
  const { session } = await createAgentSession({
567
- cwd,
568
- sessionManager: SessionManager.inMemory(cwd),
569
- });
570
-
571
- // Or pick specific tools for custom cwd
572
- const { session } = await createAgentSession({
573
- cwd,
574
- tools: ["read", "bash", "grep"],
575
- sessionManager: SessionManager.inMemory(cwd),
576
- });
577
- ```
578
-
579
- > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
580
-
581
- ### Custom Tools
582
-
583
- ```typescript
584
- import { Type } from "typebox";
585
- import { createAgentSession, defineTool } from "@punch-bot/cli";
586
-
587
- // Inline custom tool
588
- const myTool = defineTool({
589
- name: "my_tool",
590
- label: "My Tool",
591
- description: "Does something useful",
592
- parameters: Type.Object({
593
- input: Type.String({ description: "Input value" }),
594
- }),
595
- execute: async (_toolCallId, params) => ({
596
- content: [{ type: "text", text: `Result: ${params.input}` }],
597
- details: {},
598
- }),
599
- });
600
-
601
- // Pass custom tools directly
602
- const { session } = await createAgentSession({
603
- customTools: [myTool],
604
- });
605
- ```
606
-
607
- Use `defineTool()` for standalone definitions and arrays like `customTools: [myTool]`. Inline `pi.registerTool({ ... })` already infers parameter types correctly.
608
-
609
- Custom tools passed via `customTools` are combined with extension-registered tools. Extensions loaded by the ResourceLoader can also register tools via `pi.registerTool()`.
610
-
611
- If you pass `tools`, include each custom or extension tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`.
612
-
613
- > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts)
614
-
615
- ### Extensions
616
-
617
- Extensions are loaded by the `ResourceLoader`. `DefaultResourceLoader` discovers extensions from `~/.pi/agent/extensions/`, `.pi/extensions/`, and settings.json extension sources.
618
-
619
- ```typescript
620
- import { createAgentSession, DefaultResourceLoader } from "@punch-bot/cli";
621
-
622
- const loader = new DefaultResourceLoader({
623
- additionalExtensionPaths: ["/path/to/my-extension.ts"],
624
- extensionFactories: [
625
- (pi) => {
626
- pi.on("agent_start", () => {
627
- console.log("[Inline Extension] Agent starting");
628
- });
629
- },
630
- ],
631
- });
632
- await loader.reload();
633
-
634
- const { session } = await createAgentSession({ resourceLoader: loader });
635
- ```
636
-
637
- Extensions can register tools, subscribe to events, add commands, and more. See [extensions.md](extensions.md) for the full API.
638
-
639
- **Named inline extensions:** By default, inline factories display as `<inline:1>`, `<inline:2>`, etc. in the startup Extensions list. To show a descriptive name instead, wrap the factory:
640
-
641
- ```typescript
642
- import type { InlineExtension } from "@punch-bot/cli";
643
-
644
- const myProvider: InlineExtension = {
645
- name: "my-provider",
646
- factory: (pi) => {
647
- pi.on("agent_start", () => {
648
- console.log("[my-provider] Agent starting");
649
- });
650
- },
651
- };
652
-
653
- const loader = new DefaultResourceLoader({
654
- extensionFactories: [myProvider],
655
- });
656
- ```
657
-
658
- This displays as `<inline:my-provider>` instead of `<inline:1>`. Bare factory functions are still accepted for backward compatibility.
659
-
660
- **Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `DefaultResourceLoader` if you need to emit or listen from outside:
661
-
662
- ```typescript
663
- import { createEventBus, DefaultResourceLoader } from "@punch-bot/cli";
664
-
665
- const eventBus = createEventBus();
666
- const loader = new DefaultResourceLoader({
667
- eventBus,
668
- });
669
- await loader.reload();
670
-
671
- eventBus.on("my-extension:status", (data) => console.log(data));
672
- ```
673
-
674
- > See [examples/sdk/06-extensions.ts](../examples/sdk/06-extensions.ts) and [docs/extensions.md](extensions.md)
675
-
676
- ### Skills
677
-
678
- ```typescript
679
- import {
680
- createAgentSession,
681
- DefaultResourceLoader,
682
- type Skill,
683
- } from "@punch-bot/cli";
684
-
685
- const customSkill: Skill = {
686
- name: "my-skill",
687
- description: "Custom instructions",
688
- filePath: "/path/to/SKILL.md",
689
- baseDir: "/path/to",
690
- source: "custom",
691
- };
692
-
693
- const loader = new DefaultResourceLoader({
694
- skillsOverride: (current) => ({
695
- skills: [...current.skills, customSkill],
696
- diagnostics: current.diagnostics,
697
- }),
698
- });
699
- await loader.reload();
700
-
701
- const { session } = await createAgentSession({ resourceLoader: loader });
702
- ```
703
-
704
- > See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
705
-
706
- ### Context Files
707
-
708
- ```typescript
709
- import { createAgentSession, DefaultResourceLoader } from "@punch-bot/cli";
710
-
711
- const loader = new DefaultResourceLoader({
712
- agentsFilesOverride: (current) => ({
713
- agentsFiles: [
714
- ...current.agentsFiles,
715
- { path: "/virtual/AGENTS.md", content: "# Guidelines\n\n- Be concise" },
716
- ],
717
- }),
718
- });
719
- await loader.reload();
720
-
721
- const { session } = await createAgentSession({ resourceLoader: loader });
722
- ```
723
-
724
- > See [examples/sdk/07-context-files.ts](../examples/sdk/07-context-files.ts)
725
-
726
- ### Slash Commands
727
-
728
- ```typescript
729
- import {
730
- createAgentSession,
731
- DefaultResourceLoader,
732
- type PromptTemplate,
733
- } from "@punch-bot/cli";
734
-
735
- const customCommand: PromptTemplate = {
736
- name: "deploy",
737
- description: "Deploy the application",
738
- source: "(custom)",
739
- content: "# Deploy\n\n1. Build\n2. Test\n3. Deploy",
740
- };
741
-
742
- const loader = new DefaultResourceLoader({
743
- promptsOverride: (current) => ({
744
- prompts: [...current.prompts, customCommand],
745
- diagnostics: current.diagnostics,
746
- }),
747
- });
748
- await loader.reload();
749
-
750
- const { session } = await createAgentSession({ resourceLoader: loader });
751
- ```
752
-
753
- > See [examples/sdk/08-prompt-templates.ts](../examples/sdk/08-prompt-templates.ts)
754
-
755
- ### Session Management
756
-
757
- Sessions use a tree structure with `id`/`parentId` linking, enabling in-place branching.
758
-
759
- ```typescript
760
- import {
761
- type CreateAgentSessionRuntimeFactory,
762
- createAgentSession,
763
- createAgentSessionFromServices,
764
- createAgentSessionRuntime,
765
- createAgentSessionServices,
766
- getAgentDir,
767
- SessionManager,
768
- } from "@punch-bot/cli";
769
-
770
- // In-memory (no persistence)
771
- const { session } = await createAgentSession({
772
- sessionManager: SessionManager.inMemory(),
773
- });
774
-
775
- // New persistent session
776
- const { session: persisted } = await createAgentSession({
777
- sessionManager: SessionManager.create(process.cwd()),
778
- });
779
-
780
- // Continue most recent
781
- const { session: continued, modelFallbackMessage } = await createAgentSession({
782
- sessionManager: SessionManager.continueRecent(process.cwd()),
783
- });
784
- if (modelFallbackMessage) {
785
- console.log("Note:", modelFallbackMessage);
786
- }
787
-
788
- // Open specific file
789
- const { session: opened } = await createAgentSession({
790
- sessionManager: SessionManager.open("/path/to/session.jsonl"),
791
- });
792
-
793
- // Resume a session kept outside the filesystem, e.g. in a database
794
- const { session: restored } = await createAgentSession({
795
- sessionManager: SessionManager.inMemory(process.cwd(), { id: sessionId }, entries),
796
- });
797
-
798
- // List sessions
799
- const currentProjectSessions = await SessionManager.list(process.cwd());
800
- const allSessions = await SessionManager.listAll(process.cwd());
801
-
802
- // Session replacement API for /new, /resume, /fork, /clone, and import flows.
803
- const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
804
- const services = await createAgentSessionServices({ cwd });
805
- return {
806
- ...(await createAgentSessionFromServices({
807
- services,
808
- sessionManager,
809
- sessionStartEvent,
810
- })),
811
- services,
812
- diagnostics: services.diagnostics,
813
- };
814
- };
815
-
816
- const runtime = await createAgentSessionRuntime(createRuntime, {
817
- cwd: process.cwd(),
818
- agentDir: getAgentDir(),
819
- sessionManager: SessionManager.create(process.cwd()),
820
- });
821
-
822
- // Replace the active session with a fresh one
823
- await runtime.newSession();
824
-
825
- // Replace the active session with another saved session
826
- await runtime.switchSession("/path/to/session.jsonl");
827
-
828
- // Replace the active session with a fork from a specific user entry
829
- await runtime.fork("entry-id");
830
-
831
- // Clone the active path through a specific entry
832
- await runtime.fork("entry-id", { position: "at" });
833
- ```
834
-
835
- **SessionManager tree API:**
836
-
837
- ```typescript
838
- const sm = SessionManager.open("/path/to/session.jsonl");
839
-
840
- // Session listing
841
- const currentProjectSessions = await SessionManager.list(process.cwd());
842
- const allSessions = await SessionManager.listAll(process.cwd());
843
-
844
- // Tree traversal
845
- const entries = sm.getEntries(); // All entries (excludes header)
846
- const tree = sm.getTree(); // Full tree structure
847
- const path = sm.getPath(); // Path from root to current leaf
848
- const leaf = sm.getLeafEntry(); // Current leaf entry
849
- const entry = sm.getEntry(id); // Get entry by ID
850
- const children = sm.getChildren(id); // Direct children of entry
851
-
852
- // Labels
853
- const label = sm.getLabel(id); // Get label for entry
854
- sm.appendLabelChange(id, "checkpoint"); // Set label
855
-
856
- // Branching
857
- sm.branch(entryId); // Move leaf to earlier entry
858
- sm.branchWithSummary(id, "Summary..."); // Branch with context summary
859
- sm.createBranchedSession(leafId); // Extract path to new file
860
- ```
861
-
862
- > See [examples/sdk/11-sessions.ts](../examples/sdk/11-sessions.ts) and [Session Format](session-format.md)
863
-
864
- ### Settings Management
865
-
866
- ```typescript
867
- import { createAgentSession, SettingsManager, SessionManager } from "@punch-bot/cli";
868
-
869
- // Default: loads from files (global + project merged)
870
- const { session } = await createAgentSession({
871
- settingsManager: SettingsManager.create(),
872
- });
873
-
874
- // With overrides
875
- const settingsManager = SettingsManager.create();
876
- settingsManager.applyOverrides({
877
- compaction: { enabled: false },
878
- retry: { enabled: true, maxRetries: 5 },
879
- });
880
- const { session } = await createAgentSession({ settingsManager });
881
-
882
- // In-memory (no file I/O, for testing)
883
- const { session } = await createAgentSession({
884
- settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
885
48
  sessionManager: SessionManager.inMemory(),
886
49
  });
887
-
888
- // Custom directories
889
- const { session } = await createAgentSession({
890
- settingsManager: SettingsManager.create("/custom/cwd", "/custom/agent"),
891
- });
892
50
  ```
893
51
 
894
- **Static factories:**
895
- - `SettingsManager.create(cwd?, agentDir?)` - Load from files
896
- - `SettingsManager.inMemory(settings?)` - No file I/O
897
-
898
- **Project-specific settings:**
52
+ See the checked [sessions example](../examples/sdk/11-sessions.ts) for creating, opening, continuing, listing, and forking sessions. [Session File Format](session-format.md) defines the persisted JSONL contract, and [Message Types](message-types.md) defines transcript values. For exact methods and signatures, use the exported TypeScript declarations or [`session-manager.ts`](../src/core/session-manager.ts).
899
53
 
900
- Settings load from two locations and merge:
901
- 1. Global: `~/.pi/agent/settings.json`
902
- 2. Project: `<cwd>/.pi/settings.json`
54
+ `cwd` selects the workspace used for project resource discovery, context files, session grouping, and built-in tool paths. Pass it explicitly when the target differs from `process.cwd()`.
903
55
 
904
- Project overrides global. Nested objects merge keys. Setters modify global settings by default.
56
+ `session.dispose()` aborts active work, invalidates extension contexts, disconnects from the agent, and removes event listeners. Call it when the session is no longer needed.
905
57
 
906
- **Persistence and error handling semantics:**
58
+ `AgentSessionRuntime` adds `newSession()`, `switchSession()`, `fork()`, and `importFromJsonl()`. Each operation replaces the active `AgentSession` and recreates services for the target working directory.
907
59
 
908
- - Settings getters/setters are synchronous for in-memory state.
909
- - Setters enqueue persistence writes asynchronously.
910
- - Call `await settingsManager.flush()` when you need a durability boundary (for example, before process exit or before asserting file contents in tests).
911
- - `SettingsManager` does not print settings I/O errors. Use `settingsManager.drainErrors()` and report them in your app layer.
912
-
913
- > See [examples/sdk/10-settings.ts](../examples/sdk/10-settings.ts)
914
-
915
- ## ResourceLoader
916
-
917
- Use `DefaultResourceLoader` to discover extensions, skills, prompts, themes, and context files.
918
-
919
- ```typescript
920
- import {
921
- DefaultResourceLoader,
922
- getAgentDir,
923
- } from "@punch-bot/cli";
60
+ After a runtime replacement, subscriptions belong to the old `AgentSession` and must be rebound. See the [session runtime example](../examples/sdk/13-session-runtime.ts).
924
61
 
925
- const loader = new DefaultResourceLoader({
926
- cwd,
927
- agentDir: getAgentDir(),
928
- });
929
- await loader.reload();
62
+ ## Prompting
930
63
 
931
- const extensions = loader.getExtensions();
932
- const skills = loader.getSkills();
933
- const prompts = loader.getPrompts();
934
- const themes = loader.getThemes();
935
- const contextFiles = loader.getAgentsFiles().agentsFiles;
936
- ```
64
+ `prompt()` handles extension commands and expands file-based prompt templates before ordinary user messages enter the agent. For an accepted agent run, it resolves after the run finishes, including automatic retries.
937
65
 
938
- ## Return Value
66
+ A prompt sent while the session is already streaming must specify whether it should steer the current run or follow it. Calling `prompt()` without that choice rejects rather than guessing.
939
67
 
940
- `createAgentSession()` returns:
68
+ A steering message enters after the current assistant turn and its tool calls. A follow-up enters after the current run finishes its pending work. `steer()` and `followUp()` expose those behaviors directly and return `"queued"` if the input was queued (including after an extension transformed it), or `"handled"` if an extension consumed it.
941
69
 
942
- ```typescript
943
- interface CreateAgentSessionResult {
944
- // The session
945
- session: AgentSession;
946
-
947
- // Extensions result (for runner setup)
948
- extensionsResult: LoadExtensionsResult;
949
-
950
- // Warning if session model couldn't be restored
951
- modelFallbackMessage?: string;
952
- }
70
+ `abort()` stops the active operation and waits for the session to become idle. `waitForIdle()` waits without aborting it.
953
71
 
954
- interface LoadExtensionsResult {
955
- extensions: Extension[];
956
- errors: Array<{ path: string; error: string }>;
957
- runtime: ExtensionRuntime;
958
- }
959
- ```
72
+ ## Subscribing to events
960
73
 
961
- ## Complete Example
74
+ Subscribe before prompting when the host needs streamed output:
962
75
 
963
76
  ```typescript
964
- import { getModel } from "@punch-bot/ai";
965
- import { Type } from "typebox";
966
- import {
967
- createAgentSession,
968
- DefaultResourceLoader,
969
- defineTool,
970
- ModelRuntime,
971
- SessionManager,
972
- SettingsManager,
973
- } from "@punch-bot/cli";
974
-
975
- const modelRuntime = await ModelRuntime.create({
976
- authPath: "/custom/agent/auth.json",
977
- modelsPath: "/custom/agent/models.json",
978
- });
979
- if (process.env.MY_KEY) {
980
- await modelRuntime.setRuntimeApiKey("anthropic", process.env.MY_KEY);
981
- }
982
-
983
- // Inline tool
984
- const statusTool = defineTool({
985
- name: "status",
986
- label: "Status",
987
- description: "Get system status",
988
- parameters: Type.Object({}),
989
- execute: async () => ({
990
- content: [{ type: "text", text: `Uptime: ${process.uptime()}s` }],
991
- details: {},
992
- }),
993
- });
994
-
995
- const model = getModel("anthropic", "claude-opus-4-5");
996
- if (!model) throw new Error("Model not found");
997
-
998
- // In-memory settings with overrides
999
- const settingsManager = SettingsManager.inMemory({
1000
- compaction: { enabled: false },
1001
- retry: { enabled: true, maxRetries: 2 },
1002
- });
1003
-
1004
- const loader = new DefaultResourceLoader({
1005
- cwd: process.cwd(),
1006
- agentDir: "/custom/agent",
1007
- settingsManager,
1008
- systemPromptOverride: () => "You are a minimal assistant. Be concise.",
1009
- });
1010
- await loader.reload();
1011
-
1012
- const { session } = await createAgentSession({
1013
- cwd: process.cwd(),
1014
- agentDir: "/custom/agent",
1015
-
1016
- model,
1017
- thinkingLevel: "off",
1018
- modelRuntime,
1019
-
1020
- tools: ["read", "bash", "status"],
1021
- customTools: [statusTool],
1022
- resourceLoader: loader,
1023
-
1024
- sessionManager: SessionManager.inMemory(),
1025
- settingsManager,
1026
- });
1027
-
1028
- session.subscribe((event) => {
77
+ const unsubscribe = session.subscribe((event) => {
1029
78
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
1030
79
  process.stdout.write(event.assistantMessageEvent.delta);
1031
80
  }
1032
81
  });
1033
82
 
1034
- await session.prompt("Get status and list files.");
1035
- ```
1036
-
1037
- ## Run Modes
1038
-
1039
- The SDK exports run mode utilities for building custom interfaces on top of `createAgentSession()`:
1040
-
1041
- ### InteractiveMode
1042
-
1043
- Full TUI interactive mode with editor, chat history, and all built-in commands:
1044
-
1045
- ```typescript
1046
- import {
1047
- type CreateAgentSessionRuntimeFactory,
1048
- createAgentSessionFromServices,
1049
- createAgentSessionRuntime,
1050
- createAgentSessionServices,
1051
- getAgentDir,
1052
- InteractiveMode,
1053
- SessionManager,
1054
- } from "@punch-bot/cli";
1055
-
1056
- const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
1057
- const services = await createAgentSessionServices({ cwd });
1058
- return {
1059
- ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
1060
- services,
1061
- diagnostics: services.diagnostics,
1062
- };
1063
- };
1064
- const runtime = await createAgentSessionRuntime(createRuntime, {
1065
- cwd: process.cwd(),
1066
- agentDir: getAgentDir(),
1067
- sessionManager: SessionManager.create(process.cwd()),
1068
- });
1069
-
1070
- const mode = new InteractiveMode(runtime, {
1071
- migratedProviders: [],
1072
- modelFallbackMessage: undefined,
1073
- initialMessage: "Hello",
1074
- initialImages: [],
1075
- initialMessages: [],
1076
- });
1077
-
1078
- await mode.run();
1079
- ```
1080
-
1081
- ### runPrintMode
1082
-
1083
- Single-shot mode: send prompts, output result, exit:
1084
-
1085
- ```typescript
1086
- import {
1087
- type CreateAgentSessionRuntimeFactory,
1088
- createAgentSessionFromServices,
1089
- createAgentSessionRuntime,
1090
- createAgentSessionServices,
1091
- getAgentDir,
1092
- runPrintMode,
1093
- SessionManager,
1094
- } from "@punch-bot/cli";
1095
-
1096
- const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
1097
- const services = await createAgentSessionServices({ cwd });
1098
- return {
1099
- ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
1100
- services,
1101
- diagnostics: services.diagnostics,
1102
- };
1103
- };
1104
- const runtime = await createAgentSessionRuntime(createRuntime, {
1105
- cwd: process.cwd(),
1106
- agentDir: getAgentDir(),
1107
- sessionManager: SessionManager.create(process.cwd()),
1108
- });
1109
-
1110
- await runPrintMode(runtime, {
1111
- mode: "text",
1112
- initialMessage: "Hello",
1113
- initialImages: [],
1114
- messages: ["Follow up"],
1115
- });
83
+ try {
84
+ await session.prompt("Explain this repository");
85
+ } finally {
86
+ unsubscribe();
87
+ }
1116
88
  ```
1117
89
 
1118
- ### runRpcMode
90
+ Session events report message updates, tool execution, queues, compaction, retries, and run lifecycle changes.
1119
91
 
1120
- JSON-RPC mode for subprocess integration:
92
+ `message_end` contains the authoritative completed message. `agent_end` marks the end of one low-level agent run, but automatic recovery or queued work can still follow.
1121
93
 
1122
- ```typescript
1123
- import {
1124
- type CreateAgentSessionRuntimeFactory,
1125
- createAgentSessionFromServices,
1126
- createAgentSessionRuntime,
1127
- createAgentSessionServices,
1128
- getAgentDir,
1129
- runRpcMode,
1130
- SessionManager,
1131
- } from "@punch-bot/cli";
94
+ Use `agent_settled` when the host needs to know that Pi will not continue automatically.
1132
95
 
1133
- const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, sessionManager, sessionStartEvent }) => {
1134
- const services = await createAgentSessionServices({ cwd });
1135
- return {
1136
- ...(await createAgentSessionFromServices({ services, sessionManager, sessionStartEvent })),
1137
- services,
1138
- diagnostics: services.diagnostics,
1139
- };
1140
- };
1141
- const runtime = await createAgentSessionRuntime(createRuntime, {
1142
- cwd: process.cwd(),
1143
- agentDir: getAgentDir(),
1144
- sessionManager: SessionManager.create(process.cwd()),
1145
- });
96
+ ## Configuring a session
1146
97
 
1147
- await runRpcMode(runtime);
1148
- ```
98
+ Without overrides, the factory creates a `ModelRuntime`, file-backed `SettingsManager`, persistent `SessionManager`, `DefaultResourceLoader`, and the configured default tools.
1149
99
 
1150
- See [RPC documentation](rpc.md) for the JSON protocol.
100
+ Each boundary can be supplied explicitly:
1151
101
 
1152
- ## RPC Mode Alternative
102
+ - `modelRuntime`, `model`, `thinkingLevel`, and `scopedModels` control model access and selection.
103
+ - `settingsManager` supplies merged settings or an in-memory configuration.
104
+ - `sessionManager` supplies persistent or in-memory conversation history.
105
+ - `resourceLoader` supplies extensions, skills, prompt templates, themes, and context files.
106
+ - `tools`, `noTools`, `excludeTools`, and `customTools` control the active tool set.
1153
107
 
1154
- For subprocess-based integration without building with the SDK, use the CLI directly:
108
+ Use `DefaultResourceLoader` when you want standard discovery with selected overrides. Supply a custom `ResourceLoader` when the host owns resource storage and discovery completely.
1155
109
 
1156
- ```bash
1157
- pi --mode rpc --no-session
1158
- ```
110
+ <a id="inlineextension"></a>
1159
111
 
1160
- See [RPC documentation](rpc.md) for the JSON protocol.
112
+ Inline extension factories can be supplied through `DefaultResourceLoader`. Give one an `InlineExtension` name only when it needs a stable name in diagnostics and startup output. A named inline extension with `replaceable: true` is left out when another extension registers a tool, command, or flag with a name it registers during loading, instead of both loading with a conflict. The CLI's built-in codemode, tool search, and MCP extensions are replaceable. A named entry with `builtin: true` is not an inline extension: it supplies the code of the `builtin:<name>` extension, which loads like a configured extension file. It loads by default, is listed in `pi config`, and is disabled by `-builtin:<name>` in the `extensions` setting or by `noExtensions`; `additionalExtensionPaths: ["builtin:<name>"]` loads it explicitly. It loads after project trust is resolved, so it cannot handle `project_trust`. The CLI's built-in extensions use it.
1161
113
 
1162
- The SDK is preferred when:
1163
- - You want type safety
1164
- - You're in the same Node.js process
1165
- - You need direct access to agent state
1166
- - You want to customize tools/extensions programmatically
114
+ <a id="codemode-mcp"></a>
1167
115
 
1168
- RPC mode is preferred when:
1169
- - You're integrating from another language
1170
- - You want process isolation
1171
- - You're building a language-agnostic client
116
+ The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions do not; add `createCodemodeExtension()`, `createToolSearchExtension()`, and `createMcpExtension()` to the `extensionFactories` of `DefaultResourceLoader`. `codemode` and `tool_search` are registered inactive: enable them through the `defaultTools` setting (`["+codemode", "+tool_search"]` keeps the other default tools), or let the MCP extension activate them: `codemode` for servers with `codemode` exposure, `tool_search` for servers with `deferred` exposure. The MCP extension connects its servers on `session_start`, so call `session.bindExtensions()`. See [Codemode and MCP](../examples/sdk/14-codemode-mcp.ts).
1172
117
 
1173
- ## Exports
118
+ See the focused examples for [models](../examples/sdk/02-custom-model.ts), [tools](../examples/sdk/05-tools.ts), [extensions](../examples/sdk/06-extensions.ts), and [full control](../examples/sdk/12-full-control.ts).
1174
119
 
1175
- The main entry point exports:
120
+ ## Examples
1176
121
 
1177
- ```typescript
1178
- // Factory
1179
- createAgentSession
1180
- createAgentSessionRuntime
1181
- AgentSessionRuntime
122
+ | Example | Purpose |
123
+ |---|---|
124
+ | [Minimal](../examples/sdk/01-minimal.ts) | Create, prompt, observe, and dispose a session |
125
+ | [Custom model](../examples/sdk/02-custom-model.ts) | Select a model and thinking level |
126
+ | [System prompt](../examples/sdk/03-custom-prompt.ts) | Replace or append to the system prompt |
127
+ | [Skills](../examples/sdk/04-skills.ts) | Discover, filter, and add skills |
128
+ | [Tools](../examples/sdk/05-tools.ts) | Select built-in tools and their working directory |
129
+ | [Extensions](../examples/sdk/06-extensions.ts) | Load file-based and inline extensions |
130
+ | [Context files](../examples/sdk/07-context-files.ts) | Add or replace project instructions |
131
+ | [Prompt templates](../examples/sdk/08-prompt-templates.ts) | Add file-style prompt templates |
132
+ | [Credentials](../examples/sdk/09-api-keys-and-oauth.ts) | Configure credential and model storage |
133
+ | [Settings](../examples/sdk/10-settings.ts) | Supply file-backed or in-memory settings |
134
+ | [Sessions](../examples/sdk/11-sessions.ts) | Control session persistence and restoration |
135
+ | [Full control](../examples/sdk/12-full-control.ts) | Replace default discovery and state services |
136
+ | [Session runtime](../examples/sdk/13-session-runtime.ts) | Replace the active session safely |
137
+ | [Codemode and MCP](../examples/sdk/14-codemode-mcp.ts) | Add the `codemode`, `tool_search`, and MCP extensions |
1182
138
 
1183
- // Auth and Models
1184
- ModelRuntime // implements pi-ai Models and owns credential storage
1185
- ModelRegistry // synchronous extension compatibility facade
1186
- CredentialSynchronizationError
1187
- resolveCliModel
1188
- resolveModelScopeWithDiagnostics
139
+ <a id="exports"></a>
1189
140
 
1190
- // Resource loading
1191
- DefaultResourceLoader
1192
- type ResourceLoader
1193
- createEventBus
1194
-
1195
- // Constants and helpers
1196
- CONFIG_DIR_NAME
1197
- defineTool
1198
- getAgentDir
1199
- getPackageDir
1200
- getReadmePath
1201
- getDocsPath
1202
- getExamplesPath
1203
-
1204
- // Session management
1205
- SessionManager
1206
- SettingsManager
1207
-
1208
- // Tool factories
1209
- createCodingTools
1210
- createReadOnlyTools
1211
- createReadTool, createBashTool, createPowerShellTool, createEditTool, createWriteTool
1212
- createGrepTool, createFindTool, createLsTool
1213
-
1214
- // Types
1215
- type CreateAgentSessionOptions
1216
- type CreateAgentSessionResult
1217
- type ExtensionFactory
1218
- type InlineExtension
1219
- type ExtensionAPI
1220
- type ToolDefinition
1221
- type Skill
1222
- type PromptTemplate
1223
- type Tool
1224
- ```
141
+ ## Resources
1225
142
 
1226
- For extension types, see [extensions.md](extensions.md) for the full API.
143
+ - [Choose a Model](models.md) covers model selection and compatible endpoints; [Providers](providers.md) covers credentials and provider-specific setup.
144
+ - [Configuration](configuration.md) explains normal discovery and settings; [Settings](settings.md) lists every setting.
145
+ - [Sessions and Context](sessions.md) explains session behavior; [Session Format](session-format.md) defines persisted entries; [Message Types](message-types.md) defines shared transcript values.
146
+ - [Extensions](extensions.md), [Skills](skills.md), and [Prompt Templates](prompt-templates.md) document resources supplied through a `ResourceLoader`.
147
+ - [CLI Integration](cli-integration.md) covers print, JSON, and RPC alternatives to an in-process SDK integration.