@evandu/super-pi-server 0.0.0-stage → 0.1.260

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 (370) hide show
  1. package/README.md +250 -3
  2. package/agents/code-auditor.md +64 -0
  3. package/agents/code-designer.md +64 -0
  4. package/agents/coder.md +24 -0
  5. package/agents/critic.md +24 -0
  6. package/agents/document-organizer.md +48 -0
  7. package/agents/patcher.md +27 -0
  8. package/agents/planner.md +30 -0
  9. package/agents/project-leader.md +28 -0
  10. package/agents/reviewer.md +27 -0
  11. package/agents/scout.md +27 -0
  12. package/agents/solution-designer.md +62 -0
  13. package/agents/super-pi-documents/index.ts +92 -0
  14. package/agents/super-pi-feishu/index.ts +88 -0
  15. package/agents/super-pi-knowledge/index.ts +70 -0
  16. package/agents/super-pi-managed-model/index.ts +9 -0
  17. package/agents/super-pi-memory/index.ts +75 -0
  18. package/agents/super-pi-native-tools/index.ts +1 -0
  19. package/agents/super-pi-task/core.ts +2262 -0
  20. package/agents/super-pi-task/index.ts +814 -0
  21. package/agents/super-pi-task/workflow-schema.ts +34 -0
  22. package/agents/super-pi-web/index.ts +32 -0
  23. package/agents/verifier.md +25 -0
  24. package/assets/fonts/LICENSE +92 -0
  25. package/assets/fonts/NotoSansSC-Bold.otf +0 -0
  26. package/assets/fonts/NotoSansSC-Regular.otf +0 -0
  27. package/assets/knowledge-model/README.md +37 -0
  28. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/config.json +31 -0
  29. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/onnx/model_quantized.onnx +0 -0
  30. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/special_tokens_map.json +7 -0
  31. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/tokenizer.json +21278 -0
  32. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/tokenizer_config.json +15 -0
  33. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/vocab.txt +21128 -0
  34. package/bin/npm-prefix.d.ts +1 -0
  35. package/bin/npm-prefix.js +10 -0
  36. package/bin/super-pi.js +349 -0
  37. package/dist/client/.super-pi-client-sources.json +82 -0
  38. package/dist/client/assets/CodeMirrorEditor-mi9rGUce.js +2 -0
  39. package/dist/client/assets/GitDiffEditor-CpoDDQrA.css +1 -0
  40. package/dist/client/assets/GitDiffEditor-FQBfGxOY.js +29 -0
  41. package/dist/client/assets/diff-ChtP43wD.js +1 -0
  42. package/dist/client/assets/dist-AW5lyI3I.js +1 -0
  43. package/dist/client/assets/dist-B3-a6uF0.js +7 -0
  44. package/dist/client/assets/dist-BGxkyh6e.js +1 -0
  45. package/dist/client/assets/dist-BJxfd7yb.js +11 -0
  46. package/dist/client/assets/dist-BRVQKlcp.js +1 -0
  47. package/dist/client/assets/dist-BV64A9Ji.js +1 -0
  48. package/dist/client/assets/dist-BXAOrsjq.js +1 -0
  49. package/dist/client/assets/dist-CKF2Jksy.js +1 -0
  50. package/dist/client/assets/dist-CX_Hm4GS.js +1 -0
  51. package/dist/client/assets/dist-Cus6_oaF.js +2 -0
  52. package/dist/client/assets/dist-Cx00EZKR.js +23 -0
  53. package/dist/client/assets/dist-D71y2EI1.js +1 -0
  54. package/dist/client/assets/dist-D978o95T.js +5 -0
  55. package/dist/client/assets/dist-Dc1MBGAG.js +1 -0
  56. package/dist/client/assets/dist-Dds-qLxY.js +9 -0
  57. package/dist/client/assets/dist-DeD9copn.js +1 -0
  58. package/dist/client/assets/dist-DuvGReu-.js +6 -0
  59. package/dist/client/assets/dist-Dvb0SqcK.js +2 -0
  60. package/dist/client/assets/dist-J6XWqRpB.js +3 -0
  61. package/dist/client/assets/dist-QzbOCAU6.js +1 -0
  62. package/dist/client/assets/dist-moiMRpw_.js +1 -0
  63. package/dist/client/assets/dist-scBkrwv-.js +2 -0
  64. package/dist/client/assets/dockerfile-BDePf5PZ.js +1 -0
  65. package/dist/client/assets/index-Cn7hdrDw.js +350 -0
  66. package/dist/client/assets/index-UfzqdECL.css +1 -0
  67. package/dist/client/assets/powershell-D8WpQPaX.js +1 -0
  68. package/dist/client/assets/properties-C357ku5U.js +1 -0
  69. package/dist/client/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  70. package/dist/client/assets/ruby-ChfNwlCY.js +1 -0
  71. package/dist/client/assets/shell-DwuoZtxw.js +1 -0
  72. package/dist/client/assets/swift-DKB6_1j6.js +1 -0
  73. package/dist/client/assets/toml-BPTmHmyx.js +1 -0
  74. package/dist/client/favicon.ico +0 -0
  75. package/dist/client/favicon.png +0 -0
  76. package/dist/client/favicon.svg +10 -0
  77. package/dist/client/index.html +18 -0
  78. package/dist/extension.d.ts +15 -0
  79. package/dist/extension.js +126 -0
  80. package/dist/server/active-memory.d.ts +247 -0
  81. package/dist/server/active-memory.js +669 -0
  82. package/dist/server/agents.d.ts +245 -0
  83. package/dist/server/agents.js +701 -0
  84. package/dist/server/application/catalog-service.d.ts +98 -0
  85. package/dist/server/application/catalog-service.js +245 -0
  86. package/dist/server/application/conversation-service.d.ts +245 -0
  87. package/dist/server/application/conversation-service.js +654 -0
  88. package/dist/server/application/document-service.d.ts +68 -0
  89. package/dist/server/application/document-service.js +120 -0
  90. package/dist/server/application/extension-ui-service.d.ts +44 -0
  91. package/dist/server/application/extension-ui-service.js +135 -0
  92. package/dist/server/application/feishu-service.d.ts +179 -0
  93. package/dist/server/application/feishu-service.js +358 -0
  94. package/dist/server/application/group-chat-service.d.ts +75 -0
  95. package/dist/server/application/group-chat-service.js +953 -0
  96. package/dist/server/application/group-execution.d.ts +15 -0
  97. package/dist/server/application/group-execution.js +77 -0
  98. package/dist/server/application/project-service.d.ts +464 -0
  99. package/dist/server/application/project-service.js +2523 -0
  100. package/dist/server/application/provider-service.d.ts +174 -0
  101. package/dist/server/application/provider-service.js +510 -0
  102. package/dist/server/application/run-service.d.ts +547 -0
  103. package/dist/server/application/run-service.js +2683 -0
  104. package/dist/server/application/scheduled-task-service.d.ts +184 -0
  105. package/dist/server/application/scheduled-task-service.js +391 -0
  106. package/dist/server/application/session-orchestrator-service.d.ts +388 -0
  107. package/dist/server/application/session-orchestrator-service.js +1146 -0
  108. package/dist/server/application/session-reminder-service.d.ts +59 -0
  109. package/dist/server/application/session-reminder-service.js +141 -0
  110. package/dist/server/application/session-watchdog.d.ts +171 -0
  111. package/dist/server/application/session-watchdog.js +284 -0
  112. package/dist/server/application/workspace-service.d.ts +52 -0
  113. package/dist/server/application/workspace-service.js +186 -0
  114. package/dist/server/application/worktree-service.d.ts +13 -0
  115. package/dist/server/application/worktree-service.js +76 -0
  116. package/dist/server/browser-access.d.ts +34 -0
  117. package/dist/server/browser-access.js +89 -0
  118. package/dist/server/capability.d.ts +105 -0
  119. package/dist/server/capability.js +170 -0
  120. package/dist/server/command-handler.d.ts +93 -0
  121. package/dist/server/command-handler.js +540 -0
  122. package/dist/server/content-search.d.ts +16 -0
  123. package/dist/server/content-search.js +235 -0
  124. package/dist/server/conversation-usage.d.ts +22 -0
  125. package/dist/server/conversation-usage.js +43 -0
  126. package/dist/server/documents.d.ts +152 -0
  127. package/dist/server/documents.js +998 -0
  128. package/dist/server/engineering-learning.d.ts +30 -0
  129. package/dist/server/engineering-learning.js +106 -0
  130. package/dist/server/exec-service.d.ts +45 -0
  131. package/dist/server/exec-service.js +167 -0
  132. package/dist/server/explicit-file-open.d.ts +34 -0
  133. package/dist/server/explicit-file-open.js +105 -0
  134. package/dist/server/failure-text.d.ts +18 -0
  135. package/dist/server/failure-text.js +44 -0
  136. package/dist/server/feishu-cli.d.ts +223 -0
  137. package/dist/server/feishu-cli.js +464 -0
  138. package/dist/server/file-changes.d.ts +119 -0
  139. package/dist/server/file-changes.js +280 -0
  140. package/dist/server/file-diff.d.ts +41 -0
  141. package/dist/server/file-diff.js +97 -0
  142. package/dist/server/file-index.d.ts +100 -0
  143. package/dist/server/file-index.js +296 -0
  144. package/dist/server/file-name-index.d.ts +160 -0
  145. package/dist/server/file-name-index.js +411 -0
  146. package/dist/server/files.d.ts +269 -0
  147. package/dist/server/files.js +748 -0
  148. package/dist/server/git.d.ts +245 -0
  149. package/dist/server/git.js +903 -0
  150. package/dist/server/http-server.d.ts +45 -0
  151. package/dist/server/http-server.js +3830 -0
  152. package/dist/server/index.d.ts +1 -0
  153. package/dist/server/index.js +485 -0
  154. package/dist/server/inline-thinking.d.ts +90 -0
  155. package/dist/server/inline-thinking.js +181 -0
  156. package/dist/server/json-comments.d.ts +14 -0
  157. package/dist/server/json-comments.js +71 -0
  158. package/dist/server/knowledge-embedding-worker.d.ts +1 -0
  159. package/dist/server/knowledge-embedding-worker.js +27 -0
  160. package/dist/server/knowledge-vectors.d.ts +150 -0
  161. package/dist/server/knowledge-vectors.js +385 -0
  162. package/dist/server/knowledge.d.ts +273 -0
  163. package/dist/server/knowledge.js +848 -0
  164. package/dist/server/length-continuation.d.ts +83 -0
  165. package/dist/server/length-continuation.js +118 -0
  166. package/dist/server/logging.d.ts +32 -0
  167. package/dist/server/logging.js +185 -0
  168. package/dist/server/managed-http-tunnel.d.ts +6 -0
  169. package/dist/server/managed-http-tunnel.js +85 -0
  170. package/dist/server/managed-http.d.ts +4 -0
  171. package/dist/server/managed-http.js +85 -0
  172. package/dist/server/managed-model-adapter.d.ts +17 -0
  173. package/dist/server/managed-model-adapter.js +75 -0
  174. package/dist/server/managed-model-gateway.d.ts +49 -0
  175. package/dist/server/managed-model-gateway.js +73 -0
  176. package/dist/server/managed-servers.d.ts +55 -0
  177. package/dist/server/managed-servers.js +396 -0
  178. package/dist/server/managed-ssh.d.ts +26 -0
  179. package/dist/server/managed-ssh.js +73 -0
  180. package/dist/server/manager-vault.d.ts +11 -0
  181. package/dist/server/manager-vault.js +67 -0
  182. package/dist/server/memory-recall.d.ts +25 -0
  183. package/dist/server/memory-recall.js +45 -0
  184. package/dist/server/memory.d.ts +67 -0
  185. package/dist/server/memory.js +216 -0
  186. package/dist/server/message-media.d.ts +7 -0
  187. package/dist/server/message-media.js +54 -0
  188. package/dist/server/model-context-window.d.ts +186 -0
  189. package/dist/server/model-context-window.js +444 -0
  190. package/dist/server/model-filter.d.ts +23 -0
  191. package/dist/server/model-filter.js +48 -0
  192. package/dist/server/models-store.d.ts +36 -0
  193. package/dist/server/models-store.js +132 -0
  194. package/dist/server/native-tool-settings.d.ts +25 -0
  195. package/dist/server/native-tool-settings.js +41 -0
  196. package/dist/server/native-tools-extension.d.ts +2 -0
  197. package/dist/server/native-tools-extension.js +39 -0
  198. package/dist/server/native-tools-service.d.ts +39 -0
  199. package/dist/server/native-tools-service.js +240 -0
  200. package/dist/server/persistence/app-state-repository.d.ts +65 -0
  201. package/dist/server/persistence/app-state-repository.js +1 -0
  202. package/dist/server/persistence/json-state-repository.d.ts +14 -0
  203. package/dist/server/persistence/json-state-repository.js +43 -0
  204. package/dist/server/persistence/open-state-store.d.ts +3 -0
  205. package/dist/server/persistence/open-state-store.js +35 -0
  206. package/dist/server/persistence/rename.d.ts +22 -0
  207. package/dist/server/persistence/rename.js +44 -0
  208. package/dist/server/persistence/sqlite-state-repository.d.ts +12 -0
  209. package/dist/server/persistence/sqlite-state-repository.js +264 -0
  210. package/dist/server/pi-command.d.ts +94 -0
  211. package/dist/server/pi-command.js +265 -0
  212. package/dist/server/pi-native.d.ts +12 -0
  213. package/dist/server/pi-native.js +16 -0
  214. package/dist/server/pi-session-events.d.ts +158 -0
  215. package/dist/server/pi-session-events.js +373 -0
  216. package/dist/server/pi-session-pool.d.ts +233 -0
  217. package/dist/server/pi-session-pool.js +382 -0
  218. package/dist/server/pi-session.d.ts +642 -0
  219. package/dist/server/pi-session.js +655 -0
  220. package/dist/server/presentations/schema.d.ts +120 -0
  221. package/dist/server/presentations/schema.js +128 -0
  222. package/dist/server/provider-network.d.ts +16 -0
  223. package/dist/server/provider-network.js +106 -0
  224. package/dist/server/provider-proxy.d.ts +18 -0
  225. package/dist/server/provider-proxy.js +200 -0
  226. package/dist/server/providers.d.ts +333 -0
  227. package/dist/server/providers.js +989 -0
  228. package/dist/server/remote-bootstrap.d.ts +17 -0
  229. package/dist/server/remote-bootstrap.js +119 -0
  230. package/dist/server/rpc-channel.d.ts +131 -0
  231. package/dist/server/rpc-channel.js +135 -0
  232. package/dist/server/runtime.d.ts +1393 -0
  233. package/dist/server/runtime.js +3286 -0
  234. package/dist/server/scheduled-tasks.d.ts +101 -0
  235. package/dist/server/scheduled-tasks.js +138 -0
  236. package/dist/server/server-context.d.ts +119 -0
  237. package/dist/server/server-context.js +1 -0
  238. package/dist/server/session-cwd.d.ts +19 -0
  239. package/dist/server/session-cwd.js +58 -0
  240. package/dist/server/session-ledger.d.ts +67 -0
  241. package/dist/server/session-ledger.js +76 -0
  242. package/dist/server/session-memory-scope.d.ts +4 -0
  243. package/dist/server/session-memory-scope.js +30 -0
  244. package/dist/server/session-repository.d.ts +100 -0
  245. package/dist/server/session-repository.js +246 -0
  246. package/dist/server/session-tree-scope.d.ts +125 -0
  247. package/dist/server/session-tree-scope.js +337 -0
  248. package/dist/server/skills.d.ts +23 -0
  249. package/dist/server/skills.js +190 -0
  250. package/dist/server/store.d.ts +1062 -0
  251. package/dist/server/store.js +3305 -0
  252. package/dist/server/subagent-runs.d.ts +185 -0
  253. package/dist/server/subagent-runs.js +383 -0
  254. package/dist/server/subagents.d.ts +200 -0
  255. package/dist/server/subagents.js +619 -0
  256. package/dist/server/task-tool.d.ts +282 -0
  257. package/dist/server/task-tool.js +507 -0
  258. package/dist/server/tavily.d.ts +32 -0
  259. package/dist/server/tavily.js +136 -0
  260. package/dist/server/team-context.d.ts +12 -0
  261. package/dist/server/team-context.js +180 -0
  262. package/dist/server/terminal.d.ts +163 -0
  263. package/dist/server/terminal.js +557 -0
  264. package/dist/server/thinking-level-discovery.d.ts +38 -0
  265. package/dist/server/thinking-level-discovery.js +183 -0
  266. package/dist/server/time-zone.d.ts +20 -0
  267. package/dist/server/time-zone.js +32 -0
  268. package/dist/server/tool-calls.d.ts +130 -0
  269. package/dist/server/tool-calls.js +341 -0
  270. package/dist/server/tool-llm.d.ts +72 -0
  271. package/dist/server/tool-llm.js +146 -0
  272. package/dist/server/tool-registry.d.ts +129 -0
  273. package/dist/server/tool-registry.js +249 -0
  274. package/dist/server/tool-runner.d.ts +112 -0
  275. package/dist/server/tool-runner.js +306 -0
  276. package/dist/server/turn-failure.d.ts +48 -0
  277. package/dist/server/turn-failure.js +148 -0
  278. package/dist/server/types.d.ts +2315 -0
  279. package/dist/server/types.js +11 -0
  280. package/dist/server/update-status.d.ts +14 -0
  281. package/dist/server/update-status.js +69 -0
  282. package/dist/server/update.d.ts +46 -0
  283. package/dist/server/update.js +104 -0
  284. package/dist/server/upload.d.ts +35 -0
  285. package/dist/server/upload.js +177 -0
  286. package/dist/server/version.d.ts +33 -0
  287. package/dist/server/version.js +111 -0
  288. package/dist/server/web.d.ts +27 -0
  289. package/dist/server/web.js +183 -0
  290. package/dist/server/workflow-engine.d.ts +47 -0
  291. package/dist/server/workflow-engine.js +255 -0
  292. package/dist/server/workflow.d.ts +329 -0
  293. package/dist/server/workflow.js +469 -0
  294. package/dist/server/workspace-file-indexes.d.ts +2 -0
  295. package/dist/server/workspace-file-indexes.js +61 -0
  296. package/dist/server/workspace-file-operations.d.ts +36 -0
  297. package/dist/server/workspace-file-operations.js +281 -0
  298. package/dist/server/workspace-file-response.d.ts +7 -0
  299. package/dist/server/workspace-file-response.js +79 -0
  300. package/dist/server/ws-server.d.ts +149 -0
  301. package/dist/server/ws-server.js +640 -0
  302. package/dist/shared/agent-order.d.ts +44 -0
  303. package/dist/shared/agent-order.js +50 -0
  304. package/dist/shared/archive-decisions.d.ts +44 -0
  305. package/dist/shared/archive-decisions.js +98 -0
  306. package/dist/shared/background-task.d.ts +25 -0
  307. package/dist/shared/background-task.js +183 -0
  308. package/dist/shared/child-session-lock.d.ts +37 -0
  309. package/dist/shared/child-session-lock.js +59 -0
  310. package/dist/shared/content-search.d.ts +22 -0
  311. package/dist/shared/content-search.js +1 -0
  312. package/dist/shared/conversation-title.d.ts +4 -0
  313. package/dist/shared/conversation-title.js +4 -0
  314. package/dist/shared/file-mentions.d.ts +17 -0
  315. package/dist/shared/file-mentions.js +91 -0
  316. package/dist/shared/git-commit.d.ts +11 -0
  317. package/dist/shared/git-commit.js +1 -0
  318. package/dist/shared/git-graph.d.ts +42 -0
  319. package/dist/shared/git-graph.js +30 -0
  320. package/dist/shared/group-chat.d.ts +132 -0
  321. package/dist/shared/group-chat.js +6 -0
  322. package/dist/shared/managed-servers.d.ts +36 -0
  323. package/dist/shared/managed-servers.js +1 -0
  324. package/dist/shared/message-media.d.ts +12 -0
  325. package/dist/shared/message-media.js +27 -0
  326. package/dist/shared/model-window-label.d.ts +39 -0
  327. package/dist/shared/model-window-label.js +55 -0
  328. package/dist/shared/native-tools.d.ts +43 -0
  329. package/dist/shared/native-tools.js +1 -0
  330. package/dist/shared/pi-cache-warming.d.ts +9 -0
  331. package/dist/shared/pi-cache-warming.js +4 -0
  332. package/dist/shared/project-overview.d.ts +107 -0
  333. package/dist/shared/project-overview.js +92 -0
  334. package/dist/shared/project-presentation.d.ts +55 -0
  335. package/dist/shared/project-presentation.js +111 -0
  336. package/dist/shared/provider-network.d.ts +30 -0
  337. package/dist/shared/provider-network.js +1 -0
  338. package/dist/shared/session-reporting.d.ts +40 -0
  339. package/dist/shared/session-reporting.js +97 -0
  340. package/dist/shared/session-search.d.ts +14 -0
  341. package/dist/shared/session-search.js +1 -0
  342. package/dist/shared/team-context-view.d.ts +33 -0
  343. package/dist/shared/team-context-view.js +49 -0
  344. package/dist/shared/team-context.d.ts +59 -0
  345. package/dist/shared/team-context.js +3 -0
  346. package/dist/shared/terminal-protocol.d.ts +71 -0
  347. package/dist/shared/terminal-protocol.js +1 -0
  348. package/dist/shared/thinking-levels.d.ts +53 -0
  349. package/dist/shared/thinking-levels.js +85 -0
  350. package/dist/shared/tool-glyph.d.ts +7 -0
  351. package/dist/shared/tool-glyph.js +19 -0
  352. package/dist/shared/transcript-order.d.ts +7 -0
  353. package/dist/shared/transcript-order.js +12 -0
  354. package/dist/shared/update-status.d.ts +28 -0
  355. package/dist/shared/update-status.js +1 -0
  356. package/dist/shared/workspace-file-preview.d.ts +4 -0
  357. package/dist/shared/workspace-file-preview.js +28 -0
  358. package/package.json +450 -4
  359. package/scripts/diagnose.mjs +603 -0
  360. package/scripts/patch-brace-expansion.mjs +260 -0
  361. package/scripts/restart-server.mjs +104 -0
  362. package/skills/presentation/SKILL.md +30 -0
  363. package/skills/presentation/references/data.md +10 -0
  364. package/skills/presentation/references/quality.md +12 -0
  365. package/skills/presentation/references/story.md +12 -0
  366. package/skills/presentation/references/templates-and-editing.md +11 -0
  367. package/skills/presentation/references/visual-system.md +10 -0
  368. package/skills/super-pi-agent-development/SKILL.md +25 -0
  369. package/skills/super-pi-development/SKILL.md +31 -0
  370. package/skills/super-pi-tool-development/SKILL.md +39 -0
@@ -0,0 +1,1393 @@
1
+ import { type ChildProcessWithoutNullStreams } from "node:child_process";
2
+ import { type RpcRecord } from "./rpc-channel.js";
3
+ export { RpcChannel, type RpcRecord } from "./rpc-channel.js";
4
+ import type { ActiveMemory } from "./active-memory.js";
5
+ import { type KnowledgeBase } from "./knowledge.js";
6
+ import { type TurnUsageReadout } from "./conversation-usage.js";
7
+ import { type PiCacheWarmingMode, type PiCacheWarmingSettings } from "../shared/pi-cache-warming.js";
8
+ export { forkSessionFile, truncateSessionFile } from "./session-repository.js";
9
+ export { describeDeliveredUserMessage, describePiQueue } from "./pi-session-events.js";
10
+ import { type PiSessionFactory } from "./pi-session.js";
11
+ import { type AgentDefinition, type Conversation, type ExtensionUiAnswer, type ExtensionUiRequest, type MessageImage, type ModelCatalog, type ModelOption, type ModelSelection, type PiQueueSnapshot, type ToolCallNotice, type ToolCallPreparing } from "./types.js";
12
+ /**
13
+ * Who answers Pi's Extension UI questions. The runtime never invents an answer: a blocking method
14
+ * either comes back from `ask`, or it is cancelled. That is the whole point of Pi's third response
15
+ * shape - `{ type: "extension_ui_response", id, cancelled: true }` means "no answer was collected",
16
+ * which Pi is entitled to fall back from, whereas a fabricated `options[0]` looks identical to a
17
+ * human choice and silently discards the question the user was supposed to see.
18
+ */
19
+ export interface ExtensionUiHost {
20
+ /** Blocking methods. Must settle only once a human answered, cancelled, or the run ended. */
21
+ ask(request: ExtensionUiRequest): Promise<ExtensionUiAnswer>;
22
+ /** One-way methods. Fire and forget: the host must not retain the request, and there is nothing to await. */
23
+ notify(request: ExtensionUiRequest): void;
24
+ }
25
+ export interface AnswerInput {
26
+ /** Internal isolated review: no built-in tools, delegation or user-session writes. */
27
+ memoryReview?: boolean;
28
+ memorySourceConversationId?: string;
29
+ /**
30
+ * Internal isolated one-shot: the knowledge reranker asking the model to order candidate passages.
31
+ *
32
+ * WHY IT IS A SEPARATE FLAG AND NOT A REUSE OF `memoryReview`. The two differ in what they must NOT
33
+ * have. A review legitimately needs the memory tools to write down what it finds; a reranker must
34
+ * have no tool surface at all - it only has to emit a JSON array, and any tool it reaches for is a
35
+ * wasted round trip inside somebody else's turn. Folding one into the other would hand the reranker
36
+ * the memory surface, which is exactly the wrong privilege for a read-only ranking task.
37
+ */
38
+ knowledgeRerank?: boolean;
39
+ conversation: Conversation;
40
+ prompt: string;
41
+ images?: MessageImage[];
42
+ signal: AbortSignal;
43
+ /**
44
+ * The directory the child process must run in: the conversation's workspace path, resolved by the
45
+ * caller (the runtime never sees the workspace map). Required with no fallback - every tool Pi runs
46
+ * resolves its paths against this directory, so a missing one must fail loudly rather than silently
47
+ * run in the server's directory.
48
+ */
49
+ cwd: string;
50
+ /** Absent in headless use, in which case blocking requests are cancelled rather than guessed at. */
51
+ host?: ExtensionUiHost;
52
+ /**
53
+ * Called for every `queue_update` the child pushes, which is Pi reporting its own in-memory queue.
54
+ *
55
+ * Optional and observational: nothing about the delivery contract depends on it. It exists because
56
+ * `queue_update` (`agent-session.ts:204-208`) is the ONLY proof that a steer was actually picked up -
57
+ * Pi removes the entry from its queue and emits this snapshot BEFORE it emits the delivered
58
+ * `message_start` (`agent-session.ts:1116-1136`), so a host that ignored it would have no way to tell
59
+ * "queued in Pi" from "delivered to the model". It is also why a record that used to be announced as
60
+ * unhandled and dropped is now read.
61
+ */
62
+ onPiQueue?(queue: PiQueueSnapshot): void;
63
+ /**
64
+ * Called when Pi STARTS A NEW USER MESSAGE of its own, mid-turn, carrying the text it is answering.
65
+ *
66
+ * This is the delivered-steer signal, and it is what makes a steered message visible in the
67
+ * transcript. Pi drains its steering queue at a turn boundary (`agent-loop.ts:295`) and announces the
68
+ * delivery by emitting `message_start` with the user message it just picked up
69
+ * (`agent-session.ts:1116-1136`) - so the boundary where a steer stops waiting and starts being
70
+ * answered is an EVENT, not something to infer.
71
+ *
72
+ * It used to be inferred, from a drop in `steering.length` on the `queue_update` above, and applied
73
+ * by deleting the oldest `sending` row. Two consequences, both bad: the message the user could no
74
+ * longer find in the queue was never written into the transcript at all, so the agent answered words
75
+ * that existed only in Pi's session file; and a count cannot say WHICH row, so an out-of-order
76
+ * snapshot could drop a row that had not been delivered. The text is passed so a host MAY match on
77
+ * it, but the honest primary key remains the oldest `sending` message, for the same reason Pi
78
+ * itself dequeues by `indexOf` on text and cannot tell two identical messages apart.
79
+ *
80
+ * Only fires for a steer this turn delivered, never for the prompt that started the turn: the prompt
81
+ * is not re-announced, and a caller's own state decides whether there was anything waiting at all.
82
+ */
83
+ onSteerDelivered?(text: string): void | Promise<void>;
84
+ /**
85
+ * Called ONCE per turn with the Pi entry id of the user message that started it, or never.
86
+ *
87
+ * This is the whole of Super Pi's ability to name a position inside Pi's transcript. The one-shot path
88
+ * reads it over RPC (`get_entries` before the prompt, `get_entries(since: leaf)` after the turn); the
89
+ * session path reads the same facts from the live session's own transcript (`getLeafId` before,
90
+ * `getBranch` after). Both read Pi's own entries rather than counting, because Pi writes entry types
91
+ * that are not messages (`model_change`, `thinking_level_change`, `compaction`, ...) and only Pi knows
92
+ * which line the user message is.
93
+ *
94
+ * Failing to produce one is NOT a turn failure - the answer has already streamed by then - so it is
95
+ * never awaited on the critical path and never thrown. A message with no entry id simply cannot be a
96
+ * revert boundary, which the revert handler reports in words.
97
+ */
98
+ onUserEntry?: (entryId: string) => void | Promise<void>;
99
+ /**
100
+ * The session file Pi resolved for this conversation. A host caches it as a locator for a later revert
101
+ * or fork. The one-shot path learns it from `get_state`; the session path reads it off the live session
102
+ * and reports it when it CHANGES - a session rebuild (revert, eviction, fingerprint change) is exactly
103
+ * when the cached locator needs refreshing.
104
+ */
105
+ onSessionFile?: (path: string) => void | Promise<void>;
106
+ /**
107
+ * Called once per `tool_execution_start`, with the tool's name and the bounded label naming what it was
108
+ * aimed at.
109
+ *
110
+ * ABSENT MEANS "DON'T BOTHER", and the record is still consumed rather than announced - see the drain
111
+ * loop. That is the whole point of this pair: until it existed the PRIMARY agent's tool calls were the
112
+ * one thing Pi emitted that nobody on this side looked at, so a `read` and a two-minute `bash` were the
113
+ * same silence on the transcript, and a reader had no way to tell "the agent did nothing" from "the agent
114
+ * did six things you cannot see".
115
+ *
116
+ * The same two facts the sub-agent supervisor already reports, through the same `describeToolCall`
117
+ * mapping, because the two surfaces are two windows onto one protocol and a `read` labelled by its path
118
+ * on a card but by its working directory on a call block would be worse than having neither.
119
+ */
120
+ onToolCall?(call: ToolCallNotice): void;
121
+ /**
122
+ * Called when a tool that WRITES A FILE is announced, with the path it is about to write.
123
+ *
124
+ * WHY A SEPARATE CALLBACK RATHER THAN A FIELD ON `onToolCall`. Two reasons, and the second is the
125
+ * load-bearing one.
126
+ *
127
+ * The first: this is a fact about the FILESYSTEM, not about the transcript. The transcript's row for
128
+ * an `edit` is a card; this is the server learning that a file on disk is about to change, and the
129
+ * listener for it has to act BEFORE the change - which is the only moment the old content is still on
130
+ * the disk. A card that arrives after the fact is too late to be a baseline.
131
+ *
132
+ * The second: the listener's job is to capture the file's previous content, which means reading the
133
+ * disk, and that must not happen on the path that draws a card. `onToolCall` is called synchronously
134
+ * in the drain loop, between yields, and a disk read there would put an I/O stall in the middle of
135
+ * the stream - the latency the streaming lane exists to avoid. So this callback is fired and FORGOTTEN:
136
+ * the listener does its work on its own time and the drain loop moves on.
137
+ *
138
+ * The path is the tool's own spelling, resolved against the workspace by the listener - the runtime
139
+ * does not know which workspace a call belongs to, and a path it cannot check is a path it does not
140
+ * vouch for.
141
+ */
142
+ onFileWrite?(path: string, toolName: string, toolCallId?: string): void;
143
+ /**
144
+ * Called on `tool_execution_end` for the same `id`, carrying how the call ended.
145
+ *
146
+ * A SEPARATE callback for the same reason the supervisor has one: "a tool started" and "a tool finished"
147
+ * are distinguishable events, and a caller that could not tell them apart would have to invent the second
148
+ * one - which would be a row claiming an outcome Pi never reported.
149
+ *
150
+ * ONLY `isError` AND `durationMs` CROSS OVER. `result` is deliberately never read, for the reason
151
+ * `RpcRecord` does not even declare it: for a `read` it is the file's contents, and this type is the one
152
+ * place a reader would reach for it.
153
+ */
154
+ onToolEnd?(call: ToolCallNotice): void;
155
+ /**
156
+ * Called on every tool_execution_update - which is DURING execution, and repeatedly. The companion to
157
+ * onToolCall and onToolEnd rather than a third thing: without it the entire span between a call being
158
+ * announced and a call being reported is silent, and a long-running call is on screen indistinguishable
159
+ * from a frozen agent.
160
+ */
161
+ onToolUpdate?(call: ToolCallNotice): void;
162
+ /**
163
+ * Called as the model BUILDS a tool call, before the host has been told anything about it. It is the
164
+ * difference between a transcript that is quiet for the seconds an 'edit' takes to write its
165
+ * replacement text, and one that shows the call arriving.
166
+ */
167
+ onToolPreparing?(call: ToolCallPreparing): void;
168
+ /** Called while the primary model is emitting reasoning, so the UI can show live progress. A call means
169
+ * the model is STILL THINKING - there is no separate flag, because Pi does not send one. */
170
+ /** Called while the primary model is emitting reasoning, so the UI can show live progress. A call means
171
+ * the model is STILL THINKING - there is no separate flag, because Pi does not send one.
172
+ * The handler may be async: the reasoning signal is the same "the model is producing" signal as
173
+ * a text delta, and the caller waits for it so the state it writes is ordered with the delta. */
174
+ onThinking?(delta: string): void | Promise<void>;
175
+ /** Called when the reasoning phase ends - the only signal that it has. */
176
+ onThinkingEnd?(): void;
177
+ /** One turn's completed-message usage and final context snapshot, also reported on abort/failure. */
178
+ onUsage?(readout: TurnUsageReadout): void | Promise<void>;
179
+ }
180
+ /**
181
+ * What Pi answered when a `steer` was written to it, from the `disposition` of that command's response
182
+ * (`rpc-mode.ts:416-419`).
183
+ *
184
+ * - `handled` - Pi delivered it immediately, because there was no turn to wait for. Super Pi can drop it
185
+ * from its own list right away.
186
+ * - `queued` - Pi is holding it and will take it at the next turn boundary. It stays in Super Pi's list
187
+ * as `sending` until `queue_update` reports it gone.
188
+ *
189
+ * This is a real distinction and not a detail: it is the difference between a message that is already
190
+ * in the model's context and one that is not, and the UI must not claim either without knowing which.
191
+ */
192
+ export type SteerDisposition = "handled" | "queued";
193
+ /** A steer that provably never reached Pi; the caller may safely use the next turn instead. */
194
+ export declare class SteerUnavailableError extends Error {
195
+ }
196
+ /**
197
+ * What a revert has to be told, and what it is told afterwards. Declared here rather than in `types.ts`
198
+ * because neither travels to the browser: this is the runtime's own account of a file it changed.
199
+ */
200
+ export type RevertRequest = {
201
+ /** The conversation being reverted. Its `id` is Pi's `--session-id`, and is what identifies the file. */
202
+ conversation: Conversation;
203
+ /**
204
+ * The directory the next turn would spawn Pi in - the conversation's workspace.
205
+ *
206
+ * NOT OPTIONAL and NOT DEFAULTED, because it decides WHICH FILE IS FOUND: Pi's own `findById`
207
+ * (`session-manager.ts:1874-1891`) only matches a session whose recorded `cwd` equals the one it is
208
+ * asked from, and probe B measured that: the same id opened from two different cwds resolved to two
209
+ * different files, one of which did not exist. Passing the server's own directory here would find no
210
+ * conversation at all, and passing the wrong workspace would find somebody else's.
211
+ */
212
+ cwd: string;
213
+ /** Pi's entry id of the last message that SURVIVES. Everything written after it is dropped. */
214
+ boundaryEntryId: string;
215
+ beforeBoundary?: boolean;
216
+ };
217
+ export type RevertOutcome = {
218
+ /** The file that was truncated, so a caller can log what was rewritten. */
219
+ sessionFile: string;
220
+ /** Lines kept, header included. The boundary line is the last of them. */
221
+ linesKept: number;
222
+ /** Entry lines dropped. Zero means the boundary was already the leaf. */
223
+ entriesDropped: number;
224
+ };
225
+ /** What a fork has to be told, and what it is told afterwards. See `RevertRequest` for why these are here
226
+ * rather than in `types.ts`: neither travels to the browser - this is the runtime's own account of a file
227
+ * it wrote. */
228
+ export type ForkRequest = {
229
+ /** The conversation being forked. Its `id` is Pi's `--session-id`, and is what identifies the file. */
230
+ conversation: Conversation;
231
+ /** The same directory the next turn would spawn Pi in - the conversation's workspace. Required for the
232
+ * same reason as `RevertRequest.cwd`: Pi's own lookup only matches a session whose recorded `cwd`
233
+ * equals the one it is asked from, so getting this wrong resolves to some other conversation's file. */
234
+ cwd: string;
235
+ /**
236
+ * The id the NEW conversation will have, minted by the store BEFORE the file is written.
237
+ *
238
+ * MINTED UP FRONT RATHER THAN BY THE RUNTIME, and the ordering is the safety property: this file's
239
+ * header `id` has to BE the new conversation's id, so the id must exist before a byte is written - but
240
+ * the conversation itself must not exist until the file is safely on disk. Minting here and creating
241
+ * after gives exactly that: a write failure leaves an unreferenced `.jsonl` (inert - Pi only ever opens
242
+ * a file by an id some conversation already claims), while the reverse order would leave a conversation
243
+ * whose model context is silently empty, which is the single worst outcome available here.
244
+ */
245
+ forkedConversationId: string;
246
+ };
247
+ export type ForkOutcome = {
248
+ /** The file that was written, so a caller can log it. Absent when the source had no Pi transcript at
249
+ * all - an empty conversation - and the fork is then a copy of `state.json` alone. */
250
+ sessionFile?: string;
251
+ /** Entry lines copied, header excluded. */
252
+ entriesCopied: number;
253
+ inheritedUsageEntryIds?: string[];
254
+ };
255
+ export type IsolatedExecutionEvent = {
256
+ kind: "thinking";
257
+ phase: "start" | "delta" | "end";
258
+ delta?: string;
259
+ } | {
260
+ kind: "tool";
261
+ phase: "start" | "update" | "end";
262
+ call: Pick<ToolCallNotice, "id" | "name" | "detail" | "status" | "durationMs">;
263
+ };
264
+ export type IsolatedCompletionInput = {
265
+ prompt: string;
266
+ timeoutMs: number;
267
+ cwd: string;
268
+ signal?: AbortSignal;
269
+ model?: ModelSelection;
270
+ agent?: AgentDefinition;
271
+ onText?: (text: string) => void;
272
+ onToolStart?: () => void;
273
+ onExecution?: (event: IsolatedExecutionEvent) => void;
274
+ };
275
+ export interface AgentRuntime {
276
+ answer(input: AnswerInput): AsyncIterable<string>;
277
+ cacheWarmingSettings?(): Promise<PiCacheWarmingSettings>;
278
+ setCacheWarming?(mode: PiCacheWarmingMode): Promise<PiCacheWarmingSettings>;
279
+ reloadNativeTools?(): void;
280
+ stop?(conversationId: string): Promise<void>;
281
+ /**
282
+ * Hands one message to the Pi process that is running RIGHT NOW, to be injected at its next turn
283
+ * boundary (`agent-loop.ts:295`) rather than after the whole task.
284
+ *
285
+ * Resolves with Pi's own answer, and REJECTS when there is no live child or Pi did not answer. Rejecting
286
+ * rather than silently succeeding is what lets the caller keep the message cancellable: a steer that
287
+ * never reached a Pi process provably reached no model, while a steer that was written but not
288
+ * confirmed is genuinely unknown and must not be reported as either delivered or failed.
289
+ *
290
+ * Absent on a runtime with no Pi behind it (the welcome runtime), which has nothing to steer.
291
+ */
292
+ steer?(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
293
+ canSteer?(conversationId: string): boolean;
294
+ /**
295
+ * Hands one message to the Pi that is running RIGHT NOW, to be answered after the current run
296
+ * finishes its pending work.
297
+ *
298
+ * PI'S OWN FOLLOW-UP QUEUE, and the difference from a steer is the difference in WHEN. A steer is
299
+ * injected at the next turn boundary of the running turn; a follow-up waits until the agent would
300
+ * otherwise stop. Both are delivered by the agent loop inside the same run, which is what makes
301
+ * them cheap: neither goes through `_prepareRun`, so neither re-emits `before_agent_start` and
302
+ * neither pays for the memory search and the system-prompt patch that hook does.
303
+ *
304
+ * A message handed over this way is still Super Pi's to cancel, because Super Pi keeps it in its
305
+ * own waiting list - Pi is holding a copy, not the only copy.
306
+ */
307
+ followUp?(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
308
+ sendCustomMessage?(conversationId: string, message: {
309
+ customType: string;
310
+ content: string;
311
+ display?: string;
312
+ details: Record<string, unknown>;
313
+ }): Promise<void>;
314
+ /**
315
+ * Empties Pi's steering and follow-up queues, and returns what was in them.
316
+ *
317
+ * WHY A HOST NEEDS THIS. Pi cannot take back a single queued message, and it will deliver whatever
318
+ * is left in those queues when the run ends. So whenever Super Pi takes a message back - the user
319
+ * withdrew it, or the user asked for it to be answered on its own - the queues have to be emptied,
320
+ * or Pi answers words the user believes they took back.
321
+ */
322
+ clearQueues?(conversationId: string): Promise<{
323
+ steering: string[];
324
+ followUp: string[];
325
+ }>;
326
+ /**
327
+ * ONE-SHOT TITLE GENERATION. Spawns its own short-lived Pi child rather than borrowing a running one.
328
+ *
329
+ * WHY ITS OWN CHILD. `this.runs` only holds a child while a turn is executing, and that child is the
330
+ * one reading the user's stream - writing a prompt at it would land in the conversation it is streaming,
331
+ * and killing it to make room would abort a run the user is watching. So this gets a separate process
332
+ * with its own throwaway session id, which is the only way to ask the model something without touching
333
+ * the run in flight.
334
+ *
335
+ * WHY IT THROWS RATHER THAN FALLS BACK. An earlier version returned `transcript.slice(0, 60)`, which
336
+ * renamed a conversation to a fragment of its own first message while reporting success. A title the
337
+ * user did not write, produced by string slicing, must never reach `conversation.rename`. Every failure
338
+ * here is an exception the caller reports as one.
339
+ *
340
+ * Absent on the welcome runtime, which has no Pi behind it.
341
+ */
342
+ summarizeConversation?(conversation: Conversation, cwd: string, signal?: AbortSignal): Promise<string>;
343
+ /**
344
+ * ONE-SHOT COMPLETION, FOR A MOUNTED TOOL. A throwaway Pi child, one prompt, one answer, then gone.
345
+ *
346
+ * WHY IT IS A SEPARATE CHILD, LIKE `summarizeConversation`: a turn's child is the one reading the
347
+ * user's stream. Writing a tool's prompt at it would land in the conversation the user is watching.
348
+ *
349
+ * WHY NOTHING IS ATTACHED BUT Pi ITSELF. `--no-extensions --no-skills --no-mcp --no-context-files
350
+ * --no-prompt-templates`, the same line the knowledge reranker uses: a tool asking the model a question
351
+ * must not be able to reach the user's files, the task tools, or a session history. A model that
352
+ * spends the turn on a tool call anyway gets no answer and the call times out - the same accepted
353
+ * failure mode the reranker documents.
354
+ *
355
+ * WHY IT CHOOSES NO MODEL. Pi's own default is the user's own default, and a sandboxed frame is the
356
+ * last place that should get to pick which model spends the user's quota.
357
+ *
358
+ * Absent on a runtime with no Pi behind it, which the caller reports as a refusal rather than
359
+ * pretending a model answered.
360
+ */
361
+ askOnce?(input: IsolatedCompletionInput): Promise<string>;
362
+ /**
363
+ * The agent a conversation runs as, read fresh from the agent directory. Absent on a runtime with
364
+ * no agents (the welcome runtime), where every conversation runs as Pi itself. Callers that need an
365
+ * agent's declared model - to apply it when one is selected - go through here rather than reading the
366
+ * directory themselves, so the picker and the spawn can never disagree about which definition is live.
367
+ */
368
+ agentFor?(conversation: Pick<Conversation, "id" | "agentId">): Promise<AgentDefinition | undefined>;
369
+ /**
370
+ * Throws away the live sessions this runtime holds.
371
+ *
372
+ * A runtime that keeps a session alive between turns has to be told, at shutdown, that those
373
+ * sessions should go: a stopped TURN is not a stopped SESSION, and a session nobody stops holds a
374
+ * model client and - on Windows - a lock on the conversation's working directory.
375
+ *
376
+ * Optional, because a runtime with no sessions behind it (the welcome runtime) has nothing to
377
+ * throw away.
378
+ */
379
+ disposeSessions?(conversationId?: string): Promise<void>;
380
+ /**
381
+ * The model/thinking catalog a picker lists. `selection` scopes the answer to one model's
382
+ * capabilities, because Pi's thinking levels are per model (`getSupportedThinkingLevels`,
383
+ * ai/src/models.ts:1224): a catalog taken from the default model would offer levels that the
384
+ * selected model silently clamps away.
385
+ */
386
+ catalog(selection?: ModelSelection): Promise<ModelCatalog>;
387
+ oauthProviders?(): Promise<{
388
+ id: string;
389
+ name: string;
390
+ isSubscription: boolean;
391
+ loginLabel?: string;
392
+ authenticated: boolean;
393
+ }[]>;
394
+ loginOAuth?(providerId: string, interaction: {
395
+ signal: AbortSignal;
396
+ prompt(prompt: any): Promise<string>;
397
+ notify(event: any): void;
398
+ }): Promise<void>;
399
+ logoutOAuth?(providerId: string): Promise<void>;
400
+ /**
401
+ * Throws away every cached answer about the models Pi offers.
402
+ *
403
+ * Optional, because a runtime with no Pi behind it has no cache to throw away - and because the
404
+ * only thing that changes the model list from outside is a person adding a provider, which is a
405
+ * thing a runtime with no Pi cannot have.
406
+ */
407
+ invalidateCatalog?(): void;
408
+ /**
409
+ * Makes the live sessions stale, so the next turn builds one that knows the current models.
410
+ *
411
+ * Optional for the same reason: only a runtime with sessions behind it has any.
412
+ */
413
+ bumpModelEpoch?(): void;
414
+ /**
415
+ * Reverts the conversation to the state right after `boundaryEntryId`, in Pi's own transcript.
416
+ *
417
+ * OPTIONAL on the interface, like `stop`, because a runtime with no Pi has no Pi transcript to cut -
418
+ * and the handler must not pretend otherwise. A runtime that cannot revert says so; it never silently
419
+ * does nothing, which would leave `state.json` and the model's context permanently disagreeing while
420
+ * the UI showed a perfectly successful revert.
421
+ */
422
+ revert?(request: RevertRequest): Promise<RevertOutcome>;
423
+ /**
424
+ * Writes a SECOND Pi transcript that starts as an exact copy of one conversation's, under a different
425
+ * session id.
426
+ *
427
+ * OPTIONAL on the interface for the same reason `revert` is: a runtime with no Pi behind it has no Pi
428
+ * transcript to copy. But the asymmetry matters - a revert that cannot happen is merely refused, whereas
429
+ * a fork that quietly produced only a `state.json` copy would hand the user a conversation that LOOKS
430
+ * complete and whose model has never heard any of it. So the absence of this method is reported as a
431
+ * refusal, exactly as `revert`'s absence is, rather than passed over.
432
+ */
433
+ fork?(request: ForkRequest): Promise<ForkOutcome>;
434
+ /** Updates the active agent directory or directories to search. */
435
+ setModelValidator?(validator: (conversationId: string, model: ModelSelection | undefined) => Promise<void>): void;
436
+ setAgentsDir?(dir: string | string[]): void;
437
+ }
438
+ /** Deterministic offline runtime used by tests and local UI development. */
439
+ export declare class WelcomeRuntime implements AgentRuntime {
440
+ answer({ prompt, signal }: AnswerInput): AsyncIterable<string>;
441
+ stop(): Promise<void>;
442
+ /**
443
+ * No Pi, so no models. `source` is what turns the picker into a visibly disabled control instead
444
+ * of an empty list, which would read as "you have no models".
445
+ */
446
+ catalog(): Promise<ModelCatalog>;
447
+ }
448
+ /**
449
+ * One record off Pi's JSONL stdout. Deliberately a loose shape with optional fields: Pi emits a wide,
450
+ * open-ended family of session events, and a type that enumerated all of them would break on the next
451
+ * Pi release rather than on the next behaviour change.
452
+ *
453
+ * Exported so another consumer of `RpcChannel` - the sub-agent supervisor - can read the same records
454
+ * through the same channel instead of writing a second JSONL reader. Every field below is optional, so
455
+ * a reader must check before using one.
456
+ */
457
+ /** A line to write back to Pi's stdin. Mirrors Pi's RpcExtensionUIResponse union (rpc-types.ts:294-297). */
458
+ export type ExtensionUiResponse = {
459
+ type: "extension_ui_response";
460
+ id: string;
461
+ value?: string;
462
+ confirmed?: boolean;
463
+ cancelled?: true;
464
+ };
465
+ /**
466
+ * Normalizes one `extension_ui_request` record, or returns undefined when the record is not something
467
+ * Pi's union can produce (wrong `type`, missing `id`, or a method outside the nine). Exports so the
468
+ * mapping can be tested without spawning Pi.
469
+ */
470
+ export declare function describeExtensionUiRequest(record: RpcRecord): ExtensionUiRequest | undefined;
471
+ /**
472
+ * Maps a human's answer onto the one response shape Pi's method accepts. The method decides the shape
473
+ * rather than the answer, so a client that sends `confirmed` for a `select` (or `value` for a `confirm`)
474
+ * cannot produce a response Pi would read as a missing field.
475
+ */
476
+ export declare function buildExtensionUiResponse(request: ExtensionUiRequest, answer: ExtensionUiAnswer): ExtensionUiResponse;
477
+ /**
478
+ * The commands a freshly spawned Pi must be told before it runs a conversation's turn.
479
+ *
480
+ * This is the whole mechanism behind the picker: PiRpcRuntime spawns one Pi process per turn and
481
+ * kills it afterwards, so there is no long-lived session to poke. Writing these commands onto that
482
+ * process's stdin before the prompt is what makes a selection REAL - Pi answers `set_model` with
483
+ * the model it switched to, and the prompt that follows runs on it.
484
+ *
485
+ * Model BEFORE level, and the order is load-bearing: `AgentSession.setModel` re-derives the thinking
486
+ * level for the new model (agent-session.ts:2493), so applying the level first would have Pi undo it
487
+ * on the very next line.
488
+ *
489
+ * A conversation with neither selection produces NO commands, which is what keeps every
490
+ * pre-picker conversation on Pi's own defaults.
491
+ */
492
+ export declare function sessionCommands(conversation: Pick<Conversation, "model" | "thinkingLevel">): {
493
+ id: string;
494
+ type: string;
495
+ }[];
496
+ /**
497
+ * Kills a whole process tree on Windows. Pi is launched through a .cmd shim (spawn with shell:true),
498
+ * so the spawned process is cmd.exe and the real Pi is its grandchild: killing the shim alone leaks
499
+ * Pi, which keeps holding its working directory and the RPC pipes. No-op on a pid that already died.
500
+ *
501
+ * Exported rather than reimplemented per spawner: a second copy is how one of the two ends up killing
502
+ * only the shim, which is the exact failure this function exists to prevent.
503
+ */
504
+ export declare function killTree(pid: number): Promise<void>;
505
+ /** Let Pi flush its extension shutdown hooks before using the process-tree backstop. */
506
+ export declare function closePiWorker(child: ChildProcessWithoutNullStreams): Promise<void>;
507
+ /**
508
+ * Reads Pi's `steer` disposition out of its response payload.
509
+ *
510
+ * Unknown and missing both become `queued`, which is the CONSERVATIVE default and not a convenience: a
511
+ * steer Pi could not categorise may or may not already be in the model's context, so it must keep being
512
+ * treated as "not yet delivered" until a `queue_update` says otherwise. Guessing `handled` would let the
513
+ * caller drop the message from the dock on the strength of a payload shape we did not recognise.
514
+ */
515
+ export declare function describeSteerDisposition(data: unknown): SteerDisposition | undefined;
516
+ /**
517
+ * Keys Pi's model answers by. Exported so the store and the tests agree with the runtime.
518
+ *
519
+ * THE MODEL LIST IS SHARED. The list of models Pi offers is the same answer whichever model a
520
+ * conversation has selected - it is not the list of models one conversation may use. So the list has
521
+ * ONE key, and every conversation shares it.
522
+ *
523
+ * THE THINKING LEVELS BELONG TO THE MODEL IN USE, so they get a key PER MODEL. This used to be one
524
+ * "levels" key for every model, on the assumption that the level list is the same whichever model is
525
+ * selected - and that assumption is wrong: Pi computes the levels from the model itself
526
+ * (`getSupportedThinkingLevels`: a model that cannot reason offers only "off", and a model whose
527
+ * thinking map says so offers fewer). Measured with one key: after reading the levels for a reasoning
528
+ * model, a NON-reasoning model was offered the reasoning model's levels, and the other way round - so
529
+ * the picker offered levels the model in force does not have, and hid the ones it does. Super Pi
530
+ * cannot compute the levels itself instead: Pi's rule is not exported, and a second implementation of
531
+ * it would drift from Pi's.
532
+ *
533
+ * THE COST OF A KEY PER MODEL, and why it is not what it used to be. An earlier version of this
534
+ * comment said that keying on the model "meant a cache miss for every model a person ever picked, and
535
+ * every miss was a process start - so the picker went grey again after every model change". That was
536
+ * true when the catalog ALWAYS answered by spawning a Pi, which is no longer how the ordinary path
537
+ * works: the SDK path reads the levels out of a session (measured ~30ms, no process at all) and caches
538
+ * them per model. The one-shot path - a Pi the person named explicitly - does pay a spawn for a model
539
+ * it has not read yet, and that is the price of asking Pi rather than guessing at its rule.
540
+ */
541
+ export declare const catalogKey: (selection?: ModelSelection) => string;
542
+ /**
543
+ * Where the `task` extension lives, as an ABSOLUTE path.
544
+ *
545
+ * Absolute because Pi requires it: `--extension` takes the path verbatim and resolves it against Pi's
546
+ * own working directory, which is the CONVERSATION's workspace, not this repository. A relative path
547
+ * would therefore resolve differently for every conversation and fail for all of them except the one
548
+ * whose workspace happens to be this repo.
549
+ *
550
+ * `import.meta.dirname` is the one thing stable across both ways this code runs - `dist/server/` after
551
+ * `tsc -b`, `src/server/` under `tsx watch` - so two `..` segments reach the repository root either way.
552
+ *
553
+ * Returned as a FUNCTION rather than a module constant so a test can assert on the resolution without
554
+ * this module's import-time filesystem state deciding it, and so the "does it exist" check below is a
555
+ * warning on a path that is genuinely optional rather than a startup crash on a build that skipped it.
556
+ */
557
+ export declare function taskExtensionPath(from?: string): string;
558
+ /**
559
+ * The document extension's file, resolved the same way the task extension's is: two `..` segments
560
+ * from `import.meta.dirname` reach the repository root both after `tsc -b` and under `tsx watch`.
561
+ */
562
+ export declare function documentExtensionPath(from?: string): string;
563
+ /**
564
+ * The Feishu extension's file, resolved the same way the document extension's is.
565
+ *
566
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one
567
+ * of these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by
568
+ * tsc, so a relative import across the two would resolve differently under each.
569
+ */
570
+ export declare function feishuExtensionPath(from?: string): string;
571
+ export declare class PiRpcRuntime implements AgentRuntime {
572
+ private readonly sessionDir;
573
+ /**
574
+ * Where agent definitions are read from and where their prompt bodies are written. A THIRD positional
575
+ * parameter rather than part of the second one, so every existing `new PiRpcRuntime(dir, launcher)`
576
+ * call site keeps its meaning - moving the agent directory into that slot would have silently fed a
577
+ * launcher's file path in as a directory of agent definitions.
578
+ */
579
+ private agents;
580
+ /**
581
+ * How the `task` extension reaches this server. A FOURTH positional parameter for the same reason as
582
+ * the third: an options bag in one of the earlier slots would silently change what an existing
583
+ * `new PiRpcRuntime(dir, launcher, { dir, promptDir })` call site means.
584
+ *
585
+ * `endpoint` is this server's own listening URL, supplied rather than derived. It is the fix for
586
+ * hardcoding a port: `SUPER_PI_PORT` is honoured by `index.ts` and by every test that boots on
587
+ * `freePort()`, so an extension that dialled a fixed number would reach nothing at all. When it is
588
+ * absent the extension is simply not mounted, and the reason is logged once per turn rather than
589
+ * swallowed - a task tool that is mysteriously missing is the single hardest failure here to
590
+ * diagnose from the outside.
591
+ *
592
+ * `todoEndpoint` is the `todowrite` endpoint, supplied the same way and for the same reason, and it
593
+ * is a SEPARATE field rather than a path derived from `endpoint`: the two tools are allowed to be
594
+ * available independently (a harness that only exercises dispatch does not want a todo writer, and an
595
+ * older checkout has no todo endpoint at all), and a derived path could not tell "not configured"
596
+ * from "configured wrong". When it is absent the tool still registers and the extension refuses in
597
+ * words, which is what `refuseTodo` in core.ts is for.
598
+ *
599
+ * `sessionFactory` is the TEST SEAM for the session path: the pool builds sessions through it instead
600
+ * of `createPiSession`, so a test can drive `answer()` against a fake `PiSessionLike` and assert on
601
+ * what the turn did with it - the same role the factory parameter plays in `PiSessionPool` itself.
602
+ */
603
+ private readonly options;
604
+ private memory?;
605
+ setMemory(memory: ActiveMemory): void;
606
+ /**
607
+ * The memory and knowledge credentials minted for each LIVE session, so they can be released when
608
+ * the session goes. A credential whose session is gone must not keep working - that is exactly the
609
+ * shape of a secret with no owner.
610
+ */
611
+ private readonly sessionExtensionTokens;
612
+ private knowledge?;
613
+ setKnowledge(knowledge: KnowledgeBase): void;
614
+ private readonly runs;
615
+ /**
616
+ * THE LIVE SESSIONS, one per conversation, alive across turns.
617
+ *
618
+ * `runs` is the OLD registry - a child that exists only while a turn is running - and it still
619
+ * describes the one-shot paths (memory review, knowledge rerank, catalog probe), which keep their
620
+ * own throwaway children. The main conversation path does NOT use it: a conversation's session lives
621
+ * in the pool, and a turn is a run ON that session rather than a process OF its own.
622
+ */
623
+ private readonly sessionPool;
624
+ /** Where Super Pi itself is installed, which is also where its own extensions are found. */
625
+ private readonly repositoryRoot;
626
+ /**
627
+ * The turn currently running on each conversation's session.
628
+ *
629
+ * This is the piece the old design did not need, because a turn WAS a process and the process
630
+ * registry said everything. With a session that outlives its turns, the host has to know which turn
631
+ * is on the session RIGHT NOW - that is what an abort targets, and what a steer is delivered into.
632
+ */
633
+ private readonly activeTurns;
634
+ /**
635
+ * THE CURRENT TURN'S EXTENSION-UI HOST, per conversation.
636
+ *
637
+ * Pi's blocking UI questions (`select`/`confirm`/`input`/`editor`) are answered by a host, and the
638
+ * host is a per-TURN thing - `run-service` builds one per `answer()` call - while the UI context the
639
+ * session's extensions talk to is bound ONCE per session. This map is the bridge between the two
640
+ * lifetimes: a turn registers its host here for exactly its own duration, and the session's bound
641
+ * context reads through it at call time. A question asked while no turn is registered gets the honest
642
+ * answer - `cancelled` - never a default, which is the same rule the RPC path's no-host branch follows.
643
+ */
644
+ private readonly sessionHosts;
645
+ /** The sessions whose extension runner already has the UI bridge bound. */
646
+ private readonly uiBoundSessions;
647
+ private readonly backgroundUsageObservers;
648
+ private backgroundUsageWrites;
649
+ private cacheWarmingWrites;
650
+ private cacheWarmingOverride?;
651
+ private cacheWarmingEpoch;
652
+ /**
653
+ * The session-file path last reported for a conversation, so `onSessionFile` fires when it CHANGES
654
+ * rather than once per turn. The path is stable for the life of a session; what changes it is a
655
+ * rebuild (a revert, an eviction, a fingerprint change), which is exactly when the cached locator
656
+ * needs refreshing.
657
+ */
658
+ private readonly reportedSessionFiles;
659
+ /**
660
+ * `steer` commands written to a child and not yet answered by Pi, keyed by the command id.
661
+ *
662
+ * A steer has to be correlated to a promise rather than fire-and-forget, because Pi's `steer` response
663
+ * carries a `disposition` that decides whether the message is already in the model's context or still
664
+ * waiting (`handled` vs `queued`, `rpc-mode.ts:416-419`). Without that answer Super Pi would have to
665
+ * guess, and both guesses are wrong: reporting a delivered steer as waiting would leave a message
666
+ * stranded in the dock forever, and reporting a waiting one as delivered would let the user cancel a
667
+ * message the model is about to act on.
668
+ */
669
+ private readonly pendingSteers;
670
+ /** Distinguishes steer command ids. Never reused, so a late response cannot settle a later steer. */
671
+ private steerSeq;
672
+ private readonly catalogs;
673
+ /**
674
+ * In-flight reads, so N clients asking at once cost ONE read rather than N.
675
+ *
676
+ * "One read", not "one Pi spawn": the catalog is answered out of Pi's SDK and no process is started
677
+ * at all. The wording here used to promise a shared spawn, which is what the old implementation did.
678
+ */
679
+ private readonly pendingCatalogs;
680
+ /**
681
+ * Pi's SDK catalog reader, built once and reused.
682
+ *
683
+ * The ModelRuntime and SettingsManager it holds read the auth store and the model store from disk, so
684
+ * building a new one per call would put back the I/O this exists to avoid. They are read-mostly
685
+ * views of files that change rarely, and Pi's own long-lived session holds the same objects for its
686
+ * whole life.
687
+ *
688
+ * A FAILED build is remembered as a failure rather than retried per call: a broken SDK would
689
+ * otherwise be re-imported on every picker open.
690
+ */
691
+ private sdkCatalogPromise?;
692
+ /**
693
+ * Bumped whenever the set of models Pi knows about changes.
694
+ *
695
+ * A live session holds its own `ModelRuntime`, built when the session was built, and that runtime
696
+ * does not know about a provider added afterwards. Pi's refusal to switch to a model its runtime
697
+ * does not have is swallowed by the session pool into a warning, so the turn would go on running
698
+ * the OLD model while the picker said the new one - a control that lies. The sessions are made
699
+ * STALE by this counter instead: each one is rebuilt at its next turn, which is a moment when
700
+ * throwing a session away costs nothing, and the new one is built with a runtime that knows.
701
+ */
702
+ private modelEpoch;
703
+ /** Latches the "no extension on disk" warning, so it is said once rather than once per turn. */
704
+ private warnedMissingExtension;
705
+ /** Latches the "the document extension is missing" warning, for the same reason. */
706
+ private warnedMissingDocumentExtension;
707
+ /** Latches the "the Feishu extension is missing" warning, for the same reason. */
708
+ private warnedMissingFeishuExtension;
709
+ /** Latches the "Pi's SDK is not installed" warning, for the same reason. */
710
+ private warnedMissingSdk;
711
+ /**
712
+ * How a CONVERSATION runs: on a persistent SDK session, or by spawning a Pi for every turn.
713
+ *
714
+ * is the slower one, and it exists for the test suite: those suites drive a fake Pi that
715
+ * speaks the RPC protocol over a pipe, and a program is not a library - the session path cannot run
716
+ * it. It is an explicit request rather than something inferred from which Pi happens to be named,
717
+ * because inferring it is what made the Pi extension start conversations on the slow path without
718
+ * saying why.
719
+ */
720
+ private readonly sessionMode;
721
+ /**
722
+ * Agent definitions are read from disk, never cached. A file is cheap to parse, and re-reading it
723
+ * per turn is the whole point: editing an agent's prompt or tool allowlist changes the NEXT message
724
+ * with no re-selection and no restart, which a cache would silently prevent.
725
+ *
726
+ * `command` is an override for tests and for a Pi installed somewhere unusual; with none given, Pi is
727
+ * resolved through `resolvePiCommand()` (override -> PATH -> npm's global bin directory), the same
728
+ * function scripts/probe-agent-real-pi.mjs uses. Resolved ONCE here because it is a filesystem
729
+ * lookup, and a resolution that could change mid-run would make a turn's spawn line depend on when
730
+ * it was started.
731
+ */
732
+ private readonly pi;
733
+ /**
734
+ * HOW MANY LIVE SESSIONS THIS CONVERSATION HAS, and whether it has one at all.
735
+ *
736
+ * A reader of this number learns whether a conversation's context is still in Pi's memory. That is
737
+ * the fact a revert has to change: it rewrites the transcript on disk, and a live session keeps the
738
+ * OLD context in memory, so a session that outlived the revert is a model that answers from
739
+ * history the person withdrew - with nothing saying so.
740
+ *
741
+ * It is here because that failure is invisible from the outside: the file is shorter, the state is
742
+ * clean, and only the model knows something the reader cannot see.
743
+ */
744
+ liveSessionCount(conversationId: string): number;
745
+ canSteer(conversationId: string): boolean;
746
+ constructor(sessionDir: string, command?: string,
747
+ /**
748
+ * Where agent definitions are read from and where their prompt bodies are written. A THIRD positional
749
+ * parameter rather than part of the second one, so every existing `new PiRpcRuntime(dir, launcher)`
750
+ * call site keeps its meaning - moving the agent directory into that slot would have silently fed a
751
+ * launcher's file path in as a directory of agent definitions.
752
+ */
753
+ agents?: {
754
+ dir: string | string[];
755
+ promptDir: string;
756
+ },
757
+ /**
758
+ * How the `task` extension reaches this server. A FOURTH positional parameter for the same reason as
759
+ * the third: an options bag in one of the earlier slots would silently change what an existing
760
+ * `new PiRpcRuntime(dir, launcher, { dir, promptDir })` call site means.
761
+ *
762
+ * `endpoint` is this server's own listening URL, supplied rather than derived. It is the fix for
763
+ * hardcoding a port: `SUPER_PI_PORT` is honoured by `index.ts` and by every test that boots on
764
+ * `freePort()`, so an extension that dialled a fixed number would reach nothing at all. When it is
765
+ * absent the extension is simply not mounted, and the reason is logged once per turn rather than
766
+ * swallowed - a task tool that is mysteriously missing is the single hardest failure here to
767
+ * diagnose from the outside.
768
+ *
769
+ * `todoEndpoint` is the `todowrite` endpoint, supplied the same way and for the same reason, and it
770
+ * is a SEPARATE field rather than a path derived from `endpoint`: the two tools are allowed to be
771
+ * available independently (a harness that only exercises dispatch does not want a todo writer, and an
772
+ * older checkout has no todo endpoint at all), and a derived path could not tell "not configured"
773
+ * from "configured wrong". When it is absent the tool still registers and the extension refuses in
774
+ * words, which is what `refuseTodo` in core.ts is for.
775
+ *
776
+ * `sessionFactory` is the TEST SEAM for the session path: the pool builds sessions through it instead
777
+ * of `createPiSession`, so a test can drive `answer()` against a fake `PiSessionLike` and assert on
778
+ * what the turn did with it - the same role the factory parameter plays in `PiSessionPool` itself.
779
+ */
780
+ options?: {
781
+ endpoint?: string;
782
+ execEndpoint?: string;
783
+ todoEndpoint?: string;
784
+ workflowEndpoint?: string;
785
+ questionEndpoint?: string;
786
+ toolsEndpoint?: string;
787
+ documentsEndpoint?: string;
788
+ scheduledTaskEndpoint?: string;
789
+ orchestratorEndpoint?: string;
790
+ uploadsDir?: string;
791
+ sessionFactory?: PiSessionFactory;
792
+ sessionMode?: "sdk" | "oneshot";
793
+ onBackgroundUsage?: (conversationId: string, readout: TurnUsageReadout) => Promise<void>;
794
+ });
795
+ /**
796
+ * The configuration of the session that was built for a conversation, for tests to inspect.
797
+ *
798
+ * WHY THIS EXISTS. The permission boundary - an agent's tool allowlist, its prompt file, the
799
+ * extensions it mounts - used to be proved by reading the ARGV of a spawned child. A session is not
800
+ * a child and has no argv, so the evidence moved: this is what the session was actually BUILT with,
801
+ * which is the same fact stated in the new architecture's terms.
802
+ *
803
+ * It is a RECORD, not a control channel: nothing in the runtime reads it back, and a test that
804
+ * asserts on it is asserting on the real decision the real code made.
805
+ */
806
+ private readonly builtSessions;
807
+ /** The configuration a conversation's session was built with, if one was built. */
808
+ builtSessionConfig(conversationId: string): {
809
+ tools?: string[];
810
+ excludeTools?: string[];
811
+ systemPromptFile?: string;
812
+ systemPromptMode?: "replace" | "append";
813
+ extensionPaths: string[];
814
+ extensionEnv: Record<string, string>;
815
+ model?: {
816
+ provider: string;
817
+ modelId: string;
818
+ };
819
+ thinkingLevel?: string;
820
+ } | undefined;
821
+ /**
822
+ * Which path a CONVERSATION on this runtime takes.
823
+ *
824
+ * Exposed so a test can assert it. The bug this exists to prevent was invisible from the outside:
825
+ * the version number said 0.1.95 while every conversation was still spawning a process per turn,
826
+ * and nothing said why. A test that can ask "would a conversation here spawn a Pi?" can catch that.
827
+ */
828
+ get conversationPath(): "sdk" | "oneshot";
829
+ /**
830
+ * Whether the SDK-backed session layer can be used at all.
831
+ *
832
+ * The SDK is a LIBRARY and it is optional: Super Pi also supports running against a Pi installed as a
833
+ * COMMAND, and a server that cannot load the library still has a working one-shot path for the
834
+ * conversations it can serve. The answer is reported rather than thrown, so the caller can say what is
835
+ * missing instead of failing a turn with a stack trace.
836
+ */
837
+ sessionSupport(): Promise<{
838
+ available: true;
839
+ } | {
840
+ available: false;
841
+ reason: string;
842
+ }>;
843
+ /**
844
+ * Throws away every live session.
845
+ *
846
+ * Called at shutdown, and after a `revert` - the transcript on disk changed, and a session holding
847
+ * the old context in memory would keep answering from history the user has withdrawn.
848
+ */
849
+ disposeSessions(conversationId?: string): Promise<void>;
850
+ cacheWarmingSettings(): Promise<PiCacheWarmingSettings>;
851
+ reloadNativeTools(): void;
852
+ setCacheWarming(mode: PiCacheWarmingMode): Promise<PiCacheWarmingSettings>;
853
+ private observeBackgroundUsage;
854
+ /** Throws away the sessions that have been idle for a while. */
855
+ evictIdleSessions(): Promise<void>;
856
+ /**
857
+ * The agent a conversation runs as, or undefined for Pi's own defaults.
858
+ *
859
+ * A selected role must remain valid. Missing or invalid definitions are refused before
860
+ * spawning Pi so their prompt and tool restrictions cannot silently disappear.
861
+ */
862
+ agentFor(conversation: Pick<Conversation, "id" | "agentId">): Promise<AgentDefinition | undefined>;
863
+ private modelValidator?;
864
+ setModelValidator(validator: (conversationId: string, model: ModelSelection | undefined) => Promise<void>): void;
865
+ setAgentsDir(dir: string | string[]): void;
866
+ /**
867
+ * The `--extension` argv for this turn, or `[]` when the task tool is not available.
868
+ *
869
+ * Empty in TWO different situations, and both are deliberate rather than merged:
870
+ *
871
+ * - No endpoint was configured, so there is nowhere for the extension to dispatch to. Mounting it
872
+ * anyway would give the model a tool whose every call fails with a network error.
873
+ * - The extension file is not on disk. That is a build or checkout problem, and it is warned about
874
+ * ONCE rather than every turn, because "your primary agent cannot delegate anything" is worth
875
+ * knowing and worth not repeating on every keystroke.
876
+ */
877
+ private taskExtensionArgs;
878
+ /**
879
+ * The document extension's spawn argument.
880
+ *
881
+ * IT IS MOUNTED UNCONDITIONALLY, unlike the knowledge extension. The knowledge extension is only
882
+ * worth mounting when the workspace HAS documents, because its tool returns nothing otherwise; the
883
+ * document tools are about the files in the workspace, and a workspace with no PDF in it is exactly
884
+ * the workspace where an agent might be asked to WRITE one.
885
+ *
886
+ * The endpoint is the gate: without it the extension returns without registering anything, so a
887
+ * runtime with no document endpoint mounts nothing rather than a tool whose every call fails.
888
+ */
889
+ private documentExtensionArgs;
890
+ /**
891
+ * The Feishu extension's spawn argument.
892
+ *
893
+ * MOUNTED UNCONDITIONALLY, for the same reason the document tools are: the endpoint is the gate,
894
+ * and the extension registers nothing without it. The credential is NOT the gate - a user who
895
+ * has not configured an application yet still gets the tools, because the error those tools
896
+ * return is the one that tells the user what to do, and a tool that is simply absent cannot say
897
+ * anything at all.
898
+ */
899
+ private feishuExtensionArgs;
900
+ /**
901
+ * The five values the extension reads out of its own environment. See `task-tool.ts` for why they are
902
+ * written out on both sides rather than imported.
903
+ *
904
+ * The ROSTER is read here, per turn, from the same `readAgents` the picker and the supervisor use -
905
+ * never from a list written into this file. A sub-agent added while the server is running is therefore
906
+ * dispatchable on the next message with no restart, which is the same freshness rule `agentFor`
907
+ * follows for agent files and for the same reason: a human edits those files while the server runs.
908
+ *
909
+ * `depth` is `0`, hardcoded, and that is not an oversight: this is the PRIMARY agent's spawn, so it is
910
+ * definitionally at the top of the tree. `SubagentSupervisor` never passes this function, which is why
911
+ * no sub-agent process is ever given this environment at all.
912
+ *
913
+ * The TODO ENDPOINT is the one value here that is NOT per-turn derived from disk: it is this server's
914
+ * own address, so it is the same string on every turn and is read once from the constructor's options.
915
+ */
916
+ /**
917
+ * THE MEMORY AND KNOWLEDGE CREDENTIALS FOR A NEW SESSION.
918
+ *
919
+ * Both extensions read their environment ONCE, when they are loaded, so these are minted where the
920
+ * session is born - the same place, and for the same reason, as the session's capability. The
921
+ * one-shot path has always minted them (per turn); the session path minted none, so the memory and
922
+ * knowledge extensions returned before registering a tool or injecting a prompt, and both features
923
+ * were missing in production - the SDK session path is the DEFAULT backend, and only the test
924
+ * scripts take the one-shot path (ledger TEST-039).
925
+ *
926
+ * The endpoints are published as global environment variables (index.ts), and they are repeated
927
+ * here so the extension's contract is stated in one place: an endpoint and a credential travel
928
+ * together, and the credential is what proves the caller.
929
+ */
930
+ private mintSessionExtensionTokens;
931
+ /**
932
+ * The environment Super Pi's extensions read when they are loaded.
933
+ *
934
+ * IT DOES NOT INCLUDE THE CREDENTIAL. The credential is minted by the session pool, when the session
935
+ * is created, and added there - because the credential belongs to the SESSION (the extension reads
936
+ * its environment once, when it is loaded) and a token minted per turn would be replaced before the
937
+ * second turn of the conversation, leaving the extension holding a value the server had forgotten.
938
+ */
939
+ private taskExtensionEnv;
940
+ /**
941
+ * The environment for a ONE-SHOT child, which is the same as the session's except that it carries
942
+ * the credential.
943
+ *
944
+ * THE DIFFERENCE IS THE LIFETIME. A one-shot child lives for one turn, so its credential is minted
945
+ * for that turn and dies with the child - which is the original rule, and it is still exactly right
946
+ * here. A session lives for many turns, so its credential is minted when the session is created (see
947
+ * `PiSessionPool.acquire`) and the server separately requires a running turn for it to be usable.
948
+ */
949
+ private oneShotExtensionEnv;
950
+ /**
951
+ * RUNS A TURN ON A PERSISTENT SESSION.
952
+ *
953
+ * This is the path every conversation takes now, and it is where the latency win comes from. There is
954
+ * no process to spawn and none to kill: the conversation's session already exists, its context is
955
+ * already in memory, and a turn is a `prompt()` on it. An interrupt is `abort()` on the same session -
956
+ * which is why an interrupt no longer costs a process teardown and a process startup.
957
+ *
958
+ * THE EVENT ROUTING. Pi pushes events through a subscription; this method pulls them, one at a time,
959
+ * through a queue. The generator yields text deltas to its caller, and every non-text event is
960
+ * delivered to the turn's callbacks as it arrives, so the transcript shows tool calls and reasoning
961
+ * WHILE the model is producing them rather than after the turn ends.
962
+ *
963
+ * THE ABORT. The caller's `signal` is the turn's abort. When it fires, the session is aborted - Pi
964
+ * stops the current operation and waits for the session to go idle - and the turn ends. The session
965
+ * ITSELF survives: it is the next turn's session, and it is the reason the next turn costs no startup.
966
+ */
967
+ /**
968
+ * The configuration a conversation's session is built with.
969
+ *
970
+ * SEPARATED FROM THE BUILD ON PURPOSE, because this is a decision and the build is its consequence.
971
+ * Everything that decides what Pi is allowed to do for a conversation - the agent's allowlist, its
972
+ * prompt file, the extensions it mounts, the model it runs on - is decided HERE, in one place, and
973
+ * the session is then built from it.
974
+ *
975
+ * Two things want that separation. The FIRST is the fingerprint: the decision is what the session is
976
+ * compared against, so a changed decision means the session is stale. The SECOND is the tests: the
977
+ * permission boundary is the most important thing this runtime does, and asserting on the decision
978
+ * is a DIRECT way to check it - a test that has to start a real Pi to learn what Pi was told is a
979
+ * test that only runs on a machine with a Pi.
980
+ */
981
+ sessionConfiguration(conversation: Conversation, cwd: string): Promise<{
982
+ tools?: string[];
983
+ excludeTools?: string[];
984
+ systemPromptFile?: string;
985
+ systemPromptMode?: "replace" | "append";
986
+ extensionPaths: string[];
987
+ extensionEnv: Record<string, string>;
988
+ model?: {
989
+ provider: string;
990
+ modelId: string;
991
+ };
992
+ thinkingLevel?: string;
993
+ }>;
994
+ private answerOnSession;
995
+ /**
996
+ * The Extension UI context a session's extensions talk to, bridged to the host of the turn that is
997
+ * running right now.
998
+ *
999
+ * THE SHAPES MIRROR PI'S OWN RPC UI CONTEXT (rpc-mode.ts), method for method, because the extensions
1000
+ * were written against that contract: `select`/`input`/`editor` resolve to the chosen text or
1001
+ * `undefined` on cancel, `confirm` resolves to a boolean with cancel reading as `false` (Pi's own
1002
+ * mapping, not an invention), and the one-way methods are fire-and-forget. The TUI-only methods
1003
+ * (`setWorkingMessage`, footers, headers, `custom`, ...) are the same no-ops they are in RPC mode.
1004
+ *
1005
+ * A BLOCKING CALL WITH NO HOST IS CANCELLED, NEVER DEFAULTED. The no-op context Pi starts with answers
1006
+ * `confirm` with `false`, which is indistinguishable from the user clicking "no" - the exact failure
1007
+ * the "cancelled, never a default" rule exists to prevent. So an idle session (no turn, no host) and a
1008
+ * failed host both answer `cancelled`, and the reason is logged.
1009
+ */
1010
+ private extensionUiBridge;
1011
+ /**
1012
+ * Records the id of the user message this turn wrote, read from the live session's own transcript.
1013
+ *
1014
+ * THE SAME CONTRACT AS `recordTurnEntryId` ON THE ONE-SHOT PATH, over memory instead of RPC: the
1015
+ * captured pre-turn leaf is what makes the read exact, because the entries written after it belong to
1016
+ * THIS turn, and the first USER message among them is the one Super Pi just pushed. The three outcomes
1017
+ * are the same three:
1018
+ *
1019
+ * - leaf `null` - the session was empty, so the whole branch is this turn's.
1020
+ * - leaf found in the branch - everything after it is this turn's.
1021
+ * - leaf NOT found - the transcript moved underneath us (a compaction rewrite, a branch switch), so
1022
+ * nothing can be attributed to this turn with certainty and nothing is recorded. Guessing here would
1023
+ * hand back an EARLIER turn's id, and a revert to it would silently cut more than the user asked for.
1024
+ *
1025
+ * Every failure is a warning, never a throw: the answer has already streamed by this point, and "this
1026
+ * message cannot be a revert boundary" is not "your message failed".
1027
+ */
1028
+ private recordSessionTurnEntryId;
1029
+ /**
1030
+ * The tool names Super Pi's own extensions contribute, for the agent's allowlist.
1031
+ *
1032
+ * The same list the spawn line used to carry, so an agent that declares `tools: {"*": false, "read":
1033
+ * true}` gets exactly the same tools it used to get - and an agent that says `task: false` still wins,
1034
+ * because `toolFlags` treats an explicit false as outranking a host extra.
1035
+ */
1036
+ private extensionToolNames;
1037
+ /**
1038
+ * A TURN, WITH THE REASONING TAKEN OUT OF THE ANSWER.
1039
+ *
1040
+ * This is the ONE place every turn passes through, whichever path it runs on - the persistent
1041
+ * session or a one-shot process - so it is where the model's own text is read once and read
1042
+ * properly.
1043
+ *
1044
+ * WHAT IT DOES. A model that has no reasoning channel answers in one stream of text and marks its
1045
+ * thinking up inside it with `<think>…</think>`. Pi's adapter passes that through as ordinary
1046
+ * text, because Pi only knows the four reasoning FIELDS a provider can use and a tag is not one
1047
+ * of them. Left alone, the reasoning would be drawn as part of the answer, unlabelled, with the
1048
+ * tags in it.
1049
+ *
1050
+ * WHY IT IS HERE AND NOT IN THE USER'S `models.json`. The alternative is to tell every reader to
1051
+ * go and set a vendor-specific switch in a file Super Pi owns but Pi reads. A user who never
1052
+ * hears of it sees a broken transcript and has no way to find out why. Super Pi reads the tags
1053
+ * itself, for every provider, so the transcript reads the same way whichever endpoint is behind
1054
+ * it - and the reasoning goes where the reasoning goes: into a thinking block, over the same
1055
+ * channel Pi's own reasoning events use, so the fold, the live indicator and the persisted
1056
+ * transcript all work without knowing where the reasoning came from.
1057
+ */
1058
+ answer(input: AnswerInput): AsyncIterable<string>;
1059
+ /**
1060
+ * THE TURN ITSELF, on whichever path it runs. See `answer`, which is the seam the reasoning is
1061
+ * separated at.
1062
+ */
1063
+ private answerTurn;
1064
+ /**
1065
+ * THE ONE-SHOT PATH, WITH THE INLINE THINKING SPLIT OUT OF IT.
1066
+ *
1067
+ * WHY THIS IS A SEPARATE FUNCTION AND NOT A LINE IN `answerTurn`. The reasoning of an inline-thinking
1068
+ * model is a `<think>…</think>` region INSIDE the answer text, so splitting it is not a formatting
1069
+ * step - it is a reading of the text, and the facts it produces ("the thinking started", "the thinking
1070
+ * ended") belong where the text is read.
1071
+ *
1072
+ * WHEN IT WAS FORGOTTEN, IT COST THE PRODUCT A BUG. The splitter used to live one layer up, in
1073
+ * `answer()`, where it covered EVERY path. It was moved down into the SDK session path to fix the
1074
+ * ordering of "the thinking ended" against a tool call (UX-008), and in that move the ONE-SHOT
1075
+ * CONVERSATION path - the path a server without the Pi SDK falls back to, and the path the whole test
1076
+ * suite drives - lost the splitting altogether: the `<think>` tags reached the answer verbatim.
1077
+ * `scripts/inline-thinking.test.mjs` caught it; the SDK path was fine, which is why it took a test
1078
+ * suite running the other path to notice.
1079
+ *
1080
+ * SO EVERY ONE-SHOT PATH GOES THROUGH HERE, and the session path keeps its own splitter inside the
1081
+ * queue's consumer, where the ORDER of "thinking ended" and a tool call is decided.
1082
+ */
1083
+ private answerOneShotWithInlineThinking;
1084
+ /**
1085
+ * The one-shot path: a fresh child process for a single turn.
1086
+ *
1087
+ * Still used for the memory review, the knowledge reranker, and as the fallback when Pi's SDK is not
1088
+ * installed. The main conversation path does NOT come here - see `answer`.
1089
+ */
1090
+ private answerOneShot;
1091
+ /**
1092
+ * Reads back the id of the user message this turn just created, and hands it to the caller.
1093
+ *
1094
+ * `head` is the already-answered pre-turn `get_entries`, whose `leafId` is what makes the second read
1095
+ * exact. Its three possible outcomes are handled differently ON PURPOSE, because they mean different
1096
+ * things and two of them must not produce an id:
1097
+ *
1098
+ * - `leafId: null` - the session was empty, so this IS the first turn and the whole entry list is this
1099
+ * turn's. Safe to take the first user message from it.
1100
+ * - `leafId: "..."` - read only what came after it. Safe, and the only correct answer for turn two onward.
1101
+ * - no usable answer - Pi never told us where the turn began, so NOTHING in the transcript can be
1102
+ * attributed to it. Reading everything and taking "the first user message" here would hand back a
1103
+ * PREVIOUS turn's id, and a revert to that id would silently cut more than the user asked for. So this
1104
+ * case records nothing and says why.
1105
+ *
1106
+ * Every failure is a warning, never a throw: the turn's answer has already streamed by this point, and
1107
+ * "this message cannot be a revert boundary" is not "your message failed".
1108
+ */
1109
+ private recordTurnEntryId;
1110
+ /**
1111
+ * Reverts Pi's own transcript to the state right after `boundaryEntryId`.
1112
+ *
1113
+ * ============================ WHAT THIS DESTROYS ============================
1114
+ * Every Pi entry after that boundary, permanently - including tool calls, compaction records, model and
1115
+ * thinking-level markers, and usage accounting, not just the messages Super Pi shows. A copy of the file
1116
+ * as it was is left beside it as `<file>.super-pi-revert-backup`, which Pi never lists because it does
1117
+ * not end in `.jsonl`. There is no undo in the application.
1118
+ *
1119
+ * No workspace file is read, written or restored. That is the whole point of not reaching for OpenCode's
1120
+ * `snapshot/` machinery: its revert rolls the working tree back (`snapshot/index.ts:382-406`), this one
1121
+ * must not, and Super Pi has no reason to build a second git shadow repository to do damage.
1122
+ * =============================================================================
1123
+ *
1124
+ * WHY PI IS ASKED WHICH FILE TO OPEN, rather than this code scanning the session directory.
1125
+ *
1126
+ * The obvious implementation - read the directory, find the `*.jsonl` whose header id matches - is
1127
+ * exactly the one that fails silently, and probe B measured why:
1128
+ *
1129
+ * 1. When Pi cannot find the requested id it does NOT fail. It prints a warning to stderr and opens a
1130
+ * brand-new session under that same id (`main.ts:436-448`), so a wrong lookup becomes "the history
1131
+ * has vanished" with no error anywhere in the UI. Measured:
1132
+ * `Warning: No project session found with id '...'; creating a new session with that id.`
1133
+ * 2. Pi's lookup is not "match the id". With an explicit `--session-dir` it ALSO requires the session's
1134
+ * recorded `cwd` to equal the one it was asked from (`session-manager.ts:1874-1891`), and probe B
1135
+ * measured the same id resolving to two different files from two different working directories -
1136
+ * one of which did not exist on disk.
1137
+ *
1138
+ * So the file is taken from Pi's own `get_state.sessionFile` (`rpc-mode.ts:448-464`), which is the
1139
+ * lookup Pi performed for a real spawn, and then THREE things are checked before a byte is written:
1140
+ * the file exists, its header is the session header, and that header's id is the conversation being
1141
+ * reverted. A miss on any of them refuses, in words, rather than truncating something it is not sure of.
1142
+ *
1143
+ * The cost is one extra Pi spawn, which is why this is a deliberate trade rather than an oversight:
1144
+ * revert is a rare, deliberate act, and a second Pi answers in well under a second. It buys the
1145
+ * elimination of an entire class of "we truncated the wrong file and nothing said so" failures.
1146
+ */
1147
+ /**
1148
+ * THE LIVE SESSION MUST GO WHEN A REVERT REWRITES THE TRANSCRIPT.
1149
+ *
1150
+ * A revert rewrites Pi's transcript on disk. A live Pi session holds the OLD context in memory, and
1151
+ * nothing in Pi would notice the difference: the model would keep answering from history the user
1152
+ * has just withdrawn, while `state.json` and the file on disk both said it was gone. Three views of
1153
+ * the conversation, two of them wrong, and no error anywhere. So the session is destroyed and the
1154
+ * next turn rebuilds it from the truncated file.
1155
+ *
1156
+ * THIS IS A CORRECTNESS REQUIREMENT, NOT AN OPTIMIZATION, and it is why it lives in one place
1157
+ * called by EVERY branch of `revert`. It used to be inline in two of the three, and the third -
1158
+ * the one taken when the transcript path was not cached - missed it, so a session reverted before
1159
+ * its path was ever learned kept talking about the withdrawn turn with nothing saying so.
1160
+ */
1161
+ private evictAfterRevert;
1162
+ revert({ conversation, cwd, boundaryEntryId, beforeBoundary }: RevertRequest): Promise<RevertOutcome>;
1163
+ /**
1164
+ * Copies Pi's own transcript for one conversation into a second, independent file under a new id.
1165
+ *
1166
+ * THE SAME THREE STEPS AS REVERT, IN THE SAME ORDER, AND FOR THE SAME REASONS: refuse a live turn, ask Pi
1167
+ * which file it uses rather than scanning the directory (probe B measured that a directory scan resolves
1168
+ * the wrong file or a nonexistent one with no error, and that Pi invents an empty session under an id it
1169
+ * cannot find), kill that Pi BEFORE touching anything on disk, and check the file's header against the
1170
+ * conversation being forked before a byte is written. Every one of those paragraphs above still applies
1171
+ * here word for word, because it is the same machinery pointed the other way: revert cuts a file in
1172
+ * place, fork copies a file beside it.
1173
+ *
1174
+ * ============================ WHAT A FORK COPIES ============================
1175
+ * The file, byte for byte, with two header fields changed (`id`, `parentSession` - see `forkSessionFile`).
1176
+ * Entry ids are NOT renumbered, so every message recorded on the source keeps a `piEntryId` that is valid
1177
+ * in the fork too, which is what keeps REVERT working inside a forked conversation.
1178
+ * =============================================================================
1179
+ *
1180
+ * WHAT A FORK DOES NOT COPY, and both omissions are deliberate:
1181
+ *
1182
+ * - **Sub-agent runs.** `SubagentRun.conversationId` points at the conversation that dispatched it, and
1183
+ * research pitfall 7 is that truncating or duplicating a transcript leaves those records orphaned. A
1184
+ * forked conversation shows the messages but no child cards from before the fork: the children belong to
1185
+ * the conversation that started them, they are not listed anywhere once their parent has copied their
1186
+ * words, and a card in the fork that could not be stopped from the fork would be worse than no card.
1187
+ * - **Queued messages.** Same argument, and narrower: a waiting message belongs to the run in progress,
1188
+ * and a run is not copied.
1189
+ *
1190
+ * THE EMPTY-CONVERSATION CASE IS NOT AN ERROR. A conversation with no messages has no Pi file at all -
1191
+ * `SessionManager._persist` only creates one once a session holds a message (`:1160-1170`) - so there is
1192
+ * nothing to copy and the fork is a copy of `state.json` alone. That is checked BEFORE any Pi is spawned,
1193
+ * so forking a fresh conversation costs nothing and cannot fail. The converse is refused rather than
1194
+ * tolerated: messages in `state.json` with no Pi file means the two histories were ALREADY out of step,
1195
+ * and copying that into a second conversation would make the disagreement permanent and multiply it.
1196
+ */
1197
+ fork({ conversation, cwd, forkedConversationId }: ForkRequest): Promise<ForkOutcome>;
1198
+ /**
1199
+ * Delivers one Extension UI request. One-way methods are pushed to the host and never replied to
1200
+ * (Pi holds no pending entry, so a response would resolve nothing). Blocking methods are handed to
1201
+ * the host and this call is awaited, so Pi stays blocked exactly as long as the human takes.
1202
+ */
1203
+ private handleExtensionUi;
1204
+ stop(conversationId: string): Promise<void>;
1205
+ /**
1206
+ * Injects one message into the Pi process that is running right now, at its next turn boundary.
1207
+ *
1208
+ * `steer` and NOT `follow_up`, and NOT `prompt` with a `streamingBehavior`. The three are not
1209
+ * interchangeable and the difference is the whole feature:
1210
+ *
1211
+ * - `steer` is drained at `agent-loop.ts:295`, after `turn_end` and therefore after the current
1212
+ * assistant message's WHOLE tool-call batch has finished, before the next LLM request. The agent
1213
+ * stops doing what it was doing at the next boundary instead of at the end of the task. That is
1214
+ * "插队", and its granularity is a tool BATCH - a long single tool call is not interruptible,
1215
+ * because Pi offers no preemption.
1216
+ * - `follow_up` is drained at `agent-loop.ts:302`, only once the agent has stopped on its own.
1217
+ * - `prompt` would start a turn, which is the thing that must NOT happen here: this conversation
1218
+ * already has a turn in flight, and starting a second one is the two-writers-one-session bug.
1219
+ *
1220
+ * NO `set_follow_up_mode` / `set_steering_mode` IS EVER SENT, and that is a hard rule rather than a
1221
+ * default. Both go through `AgentSession.set*Mode`, which mutates `SettingsManager`'s global scope and
1222
+ * calls `save()` (`settings-manager.ts:857-871`), writing to the user's Pi `settings.json`. A host that
1223
+ * merely wanted a different queue depth would permanently rewrite the user's Pi configuration. Pi's
1224
+ * default is already `one-at-a-time` (`agent.ts:247-248`), which is the semantics this wants: one
1225
+ * queued message consumed per boundary.
1226
+ *
1227
+ * REJECTS rather than reporting success when there is no live child, and when Pi does not answer in
1228
+ * time. The caller keeps the message cancellable in the first case because it provably reached no
1229
+ * model; in the second the outcome is genuinely unknown and a `sending` state says so.
1230
+ */
1231
+ summarizeConversation(conversation: Conversation, cwd: string, signal?: AbortSignal): Promise<string>;
1232
+ /**
1233
+ * A single completion for a mounted tool. See `AgentRuntime.askOnce` for why it is its own child,
1234
+ * why nothing is attached but Pi, and why it picks no model.
1235
+ */
1236
+ askOnce(input: IsolatedCompletionInput): Promise<string>;
1237
+ /**
1238
+ * The live session for a conversation, if there is one.
1239
+ *
1240
+ * Throws when there is none, because every caller wants a session it can act on - a steer that has
1241
+ * nowhere to go is a refusal the caller turns into "this message could not be delivered", not a
1242
+ * silent success.
1243
+ */
1244
+ private sessionFor;
1245
+ /**
1246
+ * Hands a message to Pi's FOLLOW-UP queue, to be answered when the current run finishes its work.
1247
+ *
1248
+ * WHY THIS EXISTS ALONGSIDE A STEER. Both put a message into a queue Pi drains inside the running
1249
+ * turn, and neither of them re-runs `_prepareRun` - so neither re-emits `before_agent_start`, and
1250
+ * neither pays for the memory search and the system-prompt patch that hook does. A queued message
1251
+ * that answered itself with a fresh `prompt()` paid for both, once per message, and the prompt it
1252
+ * sent was larger than the one before it.
1253
+ *
1254
+ * The difference between the two is WHEN Pi delivers the message: a steer lands at the next turn
1255
+ * boundary (in the middle of the answer, which is what 「插队」 means), and a follow-up lands when
1256
+ * the agent would otherwise stop (after the answer, which is what a message typed while the agent
1257
+ * was busy means).
1258
+ */
1259
+ followUp(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
1260
+ sendCustomMessage(conversationId: string, message: {
1261
+ customType: string;
1262
+ content: string;
1263
+ display?: string;
1264
+ details: Record<string, unknown>;
1265
+ }): Promise<void>;
1266
+ /**
1267
+ * Empties Pi's steering and follow-up queues and returns what was in them.
1268
+ *
1269
+ * The session path asks Pi directly (`session.clearQueue`). The one-shot path writes Pi's
1270
+ * `clear_queue` command, which answers with the text it removed.
1271
+ */
1272
+ clearQueues(conversationId: string): Promise<{
1273
+ steering: string[];
1274
+ followUp: string[];
1275
+ }>;
1276
+ steer(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
1277
+ /**
1278
+ * Throws away every cached answer about the models Pi offers.
1279
+ *
1280
+ * Called when the model list itself changes - which today means a person added a provider
1281
+ * through the settings window. The caches are three deep and all three have to go: the TTL map
1282
+ * (ten minutes), the in-flight map (a read that is already running would answer with the old
1283
+ * list), and the SDK catalog, which is remembered for the life of the process because it holds
1284
+ * objects that read the auth store and the model store from disk - and those files are exactly
1285
+ * what just changed.
1286
+ */
1287
+ invalidateCatalog(): void;
1288
+ oauthProviders(): Promise<never[] | {
1289
+ id: string;
1290
+ name: string;
1291
+ isSubscription: boolean;
1292
+ loginLabel?: string;
1293
+ authenticated: boolean;
1294
+ }[]>;
1295
+ loginOAuth(providerId: string, interaction: {
1296
+ signal: AbortSignal;
1297
+ prompt(prompt: any): Promise<string>;
1298
+ notify(event: any): void;
1299
+ }): Promise<void>;
1300
+ logoutOAuth(providerId: string): Promise<void>;
1301
+ /**
1302
+ * Makes every live session stale, so the next turn builds one that knows the current models.
1303
+ *
1304
+ * WHY A COUNTER AND NOT A REBUILD. Rebuilding a session means throwing it away and reading its
1305
+ * transcript back, and a turn may be RUNNING right now. The counter is read by the session pool
1306
+ * as part of the fingerprint, so each session notices at its next acquire - between turns, where
1307
+ * a rebuild is free.
1308
+ */
1309
+ bumpModelEpoch(): void;
1310
+ /**
1311
+ * The model/thinking catalog, from Pi, cached.
1312
+ *
1313
+ * Three layers, because a picker opens far more often than Pi can be asked: a TTL cache keyed by
1314
+ * the selection (10 minutes for a good answer, 30 seconds for a failure), an in-flight map so
1315
+ * concurrent callers share one spawn, and - because each read spawns a short-lived Pi that is
1316
+ * killed as soon as it has answered - no long-lived process to keep warm.
1317
+ */
1318
+ catalog(selection?: ModelSelection): Promise<ModelCatalog>;
1319
+ /**
1320
+ * THE CATALOG, WITH THE WINDOW EACH MODEL REALLY HAS.
1321
+ *
1322
+ * WHY THIS IS HERE AND NOT IN THE READ. There are two ways Super Pi can read the model list: Pi's
1323
+ * SDK hands over whole model objects (window included), while a spawned Pi in RPC mode answers
1324
+ * with a reduced list that has no window on it at all. So whether the reader is shown a model's
1325
+ * window depends on WHICH PATH the machine took - and the path that drops it is the one this
1326
+ * machine takes. The window is filled in here, on the way out, so both paths end up answering the
1327
+ * same way.
1328
+ *
1329
+ * The number is the one a session will really run on, because it comes from the same arbitration
1330
+ * the session's own resolver uses (`model-context-window.ts` explains the rule).
1331
+ */
1332
+ private withRealWindows;
1333
+ /**
1334
+ * Reads the model catalog WITHOUT starting a Pi process, and falls back to a spawned Pi only when
1335
+ * the SDK is not available.
1336
+ *
1337
+ * WHY THIS IS THE DEFAULT. The picker used to be answered by starting a `pi --mode rpc` child,
1338
+ * asking it three questions and killing it: a process start, measured at 866ms on a fast machine and
1339
+ * seconds on a slow one. And the cache key is the SELECTED MODEL, so it started again for every model
1340
+ * a person picked - which is why "the picker stays grey for ten seconds" followed choosing a model,
1341
+ * and not only the first time.
1342
+ *
1343
+ * Pi's SDK is the same code Pi's RPC mode is built on, so the answers are the same, and the two are
1344
+ * compared field by field in `scripts/probe-catalog-equivalence.mjs`.
1345
+ */
1346
+ private readCatalog;
1347
+ /**
1348
+ * The transcript file for a conversation, out of Pi's SDK, or undefined when the SDK cannot answer.
1349
+ *
1350
+ * Undefined means "ask someone else", not "no such file": a missing SDK and a missing transcript
1351
+ * are different facts, and only the first one should send the caller to the spawning path.
1352
+ *
1353
+ * For the same reason as the catalog, a NAMED Pi is not asked here: when something else will run the
1354
+ * conversation, it is also the only one that knows which file that conversation's transcript is in.
1355
+ */
1356
+ private resolveTranscriptFileWithoutSpawn;
1357
+ private sdkCatalog;
1358
+ /**
1359
+ * The catalog, out of Pi's SDK. Returns undefined when the SDK is not available, which is the only
1360
+ * case in which the spawning path is reached.
1361
+ */
1362
+ private readCatalogFromSdk;
1363
+ /**
1364
+ * Asks one throwaway Pi for its model list, its thinking levels and its own current selection.
1365
+ *
1366
+ * Only reached when Pi's SDK is not available - which is a broken installation, not a normal one.
1367
+ *
1368
+ * The three commands are written back to back and only then awaited, so Pi works on them in
1369
+ * parallel - measured at 394ms for all three, against 714ms for the slowest one alone. A Pi
1370
+ * scoped to one conversation's model needs `set_model` FIRST and alone, because thinking levels are
1371
+ * a property of the selected model, not of Pi's default.
1372
+ */
1373
+ private readCatalogBySpawningPi;
1374
+ }
1375
+ /**
1376
+ * Normalizes Pi's `Model[]`, keeping only entries that can actually be sent back as a `set_model`.
1377
+ * Exported so the mapping is testable without a Pi process.
1378
+ *
1379
+ * `imageInput` reads Pi's `input` array, which is where image support is actually declared -
1380
+ * `BaseModel.input: ("text" | "image")[]` at packages/ai/src/types.ts:1124, and Pi's own CLI prints
1381
+ * the very same test as its "images" column (cli/list-models.ts:71, `m.input.includes("image")`).
1382
+ * Copying Pi's predicate rather than inventing one is the point: if Pi ever renames the value or
1383
+ * adds a third modality, Pi's column and this badge change together.
1384
+ *
1385
+ * A MISSING OR MALFORMED `input` READS AS FALSE, and that direction is deliberate. The field's
1386
+ * failure mode is a silent one in both directions - Pi's RPC reader does no schema validation
1387
+ * (rpc-mode.ts:750-783) - so a model with no `input` at all could be a Pi too old to have the
1388
+ * concept, and answering "supports images" for it would invite a picture the model cannot see.
1389
+ * Announcing a capability that turns out to be absent costs the user a confusing turn; declining to
1390
+ * announce one that is present costs them an unlabelled model. Only the first is worth guessing on.
1391
+ */
1392
+ export declare function describeModel(value: unknown): ModelOption | undefined;
1393
+ export declare function describeModels(value: unknown): ModelOption[];