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

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 +248 -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 +392 -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 +448 -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,642 @@
1
+ /**
2
+ * THE SESSION LAYER: one Pi session per Super Pi conversation, alive across turns.
3
+ *
4
+ * WHY THIS FILE EXISTS. Super Pi used to spawn a fresh `pi --mode rpc` process for every turn and kill
5
+ * it when the turn ended. That cost ~400ms of spawn plus ~380ms of handshake plus a full replay of the
6
+ * transcript on EVERY message, and it is why an interrupt had to kill a process and start another one:
7
+ * the turn and the process were the same thing. Pi's own `abort` takes 147ms and leaves the session
8
+ * usable, so the process churn was Super Pi's choice, not a property of interrupting.
9
+ *
10
+ * Pi's SDK (`@earendil-works/pi-coding-agent`) is the supported way to embed it - Pi's own RPC docs
11
+ * recommend it for Node applications. A session here is a Pi `AgentSession`: it keeps the conversation
12
+ * context in memory across turns, and `abort()` returns as soon as the agent is idle.
13
+ *
14
+ * WHAT THIS FILE IS NOT. It is not a second runtime. The one-shot paths (memory review, knowledge
15
+ * rerank, autotitle, tool LLM, catalog probe) keep spawning their own throwaway children, because their
16
+ * identity, tool set and lifecycle are deliberately different from the primary agent's and sharing a
17
+ * session with them would be a correctness bug, not an optimization. See `runtime.ts`.
18
+ *
19
+ * THE ONE HARD CONSTRAINT. Pi's agent prompt, its tool allowlist and the extensions it mounts are all
20
+ * decided when the session is CREATED. None of them can be changed on a live session. So a session carries
21
+ * a FINGERPRINT of everything that was decided at creation, and the caller compares fingerprints: a
22
+ * change means the session is stale and must be replaced. `revert` is the sharpest case - it truncates
23
+ * the transcript on disk while the live session still holds the old context in memory, and nothing in Pi
24
+ * would notice the difference.
25
+ */
26
+ import type { PiImageContent } from "./types.js";
27
+ import type { PiCacheWarmingMode } from "../shared/pi-cache-warming.js";
28
+ /**
29
+ * The Pi SDK, imported lazily.
30
+ *
31
+ * LAZY, and not for startup speed: Super Pi is also shipped as a package that runs against a Pi
32
+ * INSTALLED ON THE USER'S MACHINE, resolved by `pi-command.ts` (override -> PATH -> npm's global bin).
33
+ * That resolution finds a COMMAND; the SDK is a LIBRARY, and it has to come from somewhere specific.
34
+ * A static import would make the whole server fail to start when the library is absent, taking the
35
+ * terminal, the file panel and the git panel down with it - none of which need Pi.
36
+ *
37
+ * So the library is optional, and its absence is a REPORTED FACT rather than a crash. A Super Pi
38
+ * without the SDK cannot run a conversation, and says so in words; a Super Pi whose import throws at
39
+ * module scope cannot even start.
40
+ */
41
+ /**
42
+ * The parts of Pi's SDK this file uses, described structurally.
43
+ *
44
+ * NOT `typeof import("@earendil-works/pi-coding-agent")`, and that is deliberate. The SDK is an
45
+ * OPTIONAL dependency: a Super Pi installed without it still has to COMPILE, because the compiler runs
46
+ * before anything can report that the library is missing. A type-only import of an absent package is a
47
+ * compile error, so the shapes are declared here instead, and the compiler checks them against the
48
+ * installed SDK's own declarations when it is present (see `scripts/pi-session.test.mjs`).
49
+ */
50
+ interface PiSdk {
51
+ DefaultResourceLoader: new (options: {
52
+ cwd: string;
53
+ agentDir: string;
54
+ additionalExtensionPaths?: string[];
55
+ additionalSkillPaths?: string[];
56
+ systemPrompt?: string;
57
+ appendSystemPrompt?: string[];
58
+ extensionFactories?: unknown[];
59
+ }) => {
60
+ reload(): Promise<void>;
61
+ getPrompts?: () => {
62
+ prompts: Array<{
63
+ name: string;
64
+ description: string;
65
+ argumentHint?: string;
66
+ sourceInfo: {
67
+ scope: string;
68
+ };
69
+ content: string;
70
+ filePath: string;
71
+ }>;
72
+ };
73
+ };
74
+ SessionManager: {
75
+ create(cwd: string, sessionDir?: string, options?: {
76
+ id?: string;
77
+ }): unknown;
78
+ open(path: string, sessionDir?: string, cwdOverride?: string): unknown;
79
+ inMemory(cwd?: string, options?: {
80
+ id?: string;
81
+ }): unknown;
82
+ findById(cwd: string, id: string, sessionDir?: string): string | undefined;
83
+ };
84
+ ModelRuntime: {
85
+ create(options?: Record<string, unknown>): Promise<{
86
+ getModel?: (provider: string, modelId: string) => unknown;
87
+ getAvailable?: () => Promise<unknown[]>;
88
+ getModels?: () => unknown[];
89
+ /**
90
+ * Pi's own verdict on its model configuration - the schema error that empties every picker
91
+ * when one entry in `models.json` is refused.
92
+ */
93
+ getError?: () => string | undefined;
94
+ getProviders?: () => readonly {
95
+ id: string;
96
+ name?: string;
97
+ auth?: {
98
+ oauth?: {
99
+ name?: string;
100
+ isSubscription?: boolean;
101
+ loginLabel?: string;
102
+ };
103
+ };
104
+ }[];
105
+ checkAuth?: (providerId: string) => Promise<{
106
+ type: string;
107
+ } | undefined>;
108
+ login?: (providerId: string, type: "oauth", interaction: {
109
+ signal?: AbortSignal;
110
+ prompt(prompt: any): Promise<string>;
111
+ notify(event: any): void;
112
+ }, options?: {
113
+ agentName?: string;
114
+ }) => Promise<unknown>;
115
+ logout?: (providerId: string) => Promise<void>;
116
+ refresh?: () => Promise<unknown>;
117
+ }>;
118
+ };
119
+ AuthStorage?: {
120
+ create(path?: string): object;
121
+ };
122
+ SettingsManager: {
123
+ create(cwd: string, agentDir: string): {
124
+ getDefaultProvider?: () => string | undefined;
125
+ getDefaultModel?: () => string | undefined;
126
+ getDefaultThinkingLevel?: () => string | undefined;
127
+ getCacheWarmingMode(): PiCacheWarmingMode;
128
+ setCacheWarmingMode(mode: PiCacheWarmingMode): void;
129
+ flush(): Promise<void>;
130
+ drainErrors(): Array<{
131
+ error: Error;
132
+ }>;
133
+ };
134
+ };
135
+ createAgentSession(options: Record<string, unknown>): Promise<{
136
+ session: unknown;
137
+ }>;
138
+ }
139
+ /**
140
+ * Loads Pi's SDK while the server is still starting.
141
+ *
142
+ * Importing Pi costs about 1.5 seconds once and is free afterwards, and it used to be paid by whatever
143
+ * user action needed it FIRST - which for most people was opening the model picker and watching it stay
144
+ * grey. Paying it here, during startup, moves it off the path a person can see.
145
+ *
146
+ * Safe to call more than once, and safe to call on a server that never needs the SDK: it loads the
147
+ * module and returns, and the caller decides what to do with a failure.
148
+ */
149
+ export declare function warmPiSdk(): Promise<boolean>;
150
+ export declare function piCacheWarmingMode(mode?: PiCacheWarmingMode): Promise<PiCacheWarmingMode>;
151
+ /**
152
+ * A model catalog read from Pi's SDK, with NO PROCESS.
153
+ *
154
+ * THE PROBLEM THIS SOLVES. The model picker used to be answered by starting a `pi --mode rpc` child,
155
+ * asking it three questions and killing it. That is a process start - measured at 866ms on a fast
156
+ * machine, and seconds on a slow one - paid every time the cache missed, and the cache key is the
157
+ * SELECTED MODEL, so it missed again for every model a person picked. A user who opened the picker and
158
+ * then created a conversation waited for a process to start.
159
+ *
160
+ * WHY IT IS SAFE. Pi's SDK is the same code Pi's RPC mode is built on, so the answers are the same:
161
+ * `ModelRuntime.getAvailable()` returned exactly the model list a spawned Pi reports, and a session's
162
+ * `getAvailableThinkingLevels()` returned exactly the level list. Both are checked field by field in
163
+ * `scripts/probe-catalog-equivalence.mjs` and `scripts/probe-levels.mjs`.
164
+ *
165
+ * WHAT IS STILL NEEDED FROM PI ITSELF. The thinking levels are a property of the SELECTED model, and a
166
+ * model that is not running has no session to ask. So the levels come from a short-lived in-memory
167
+ * session rather than from the model list - which costs a session, not a process, and is only needed
168
+ * when the caller actually wants levels for a model.
169
+ */
170
+ export interface SdkCatalog {
171
+ /** Pi's own model objects, for the caller to reduce with the same helpers the RPC path used. */
172
+ models: unknown[];
173
+ /**
174
+ * THE MODEL PI WOULD RUN, resolved by PI ITSELF.
175
+ *
176
+ * NOT "the pair Pi's settings name". Pi's settings are a WISH, and a wish is not always granted:
177
+ * the pair may be absent (nobody ever chose a default), it may name a model Pi no longer offers,
178
+ * and it may name a model whose provider has no credential. Pi's own resolver checks all three
179
+ * and, when the wish cannot be granted, picks a model it CAN run. This is that model's identity.
180
+ *
181
+ * UNDEFINED MEANS "PI HAS NO MODEL TO RUN", which is an honest answer and not a gap to paper over.
182
+ */
183
+ defaultModel?: {
184
+ provider: string;
185
+ modelId: string;
186
+ };
187
+ /**
188
+ * The levels a model supports, AND the level in force for it, read from a session running that model.
189
+ *
190
+ * Separate from the models because it is the expensive half: it needs a session, so a caller that
191
+ * only wants the list does not pay for it.
192
+ *
193
+ * UNDEFINED MEANS "THIS RUNTIME DOES NOT KNOW THAT MODEL", and it is not the same answer as "that
194
+ * model has no levels but off". A caller that gets undefined asks whoever does know the model; a
195
+ * caller that got a list would be showing another model's levels.
196
+ *
197
+ * THE LEVEL IN FORCE COMES FROM THE SAME SESSION, because that is where Pi decides it: the
198
+ * per-model override, else the global default, CLAMPED to what this model actually offers.
199
+ * Reporting the unclamped preference would put a level on screen that the model does not have.
200
+ */
201
+ thinkingLevelsFor(model: {
202
+ provider: string;
203
+ modelId: string;
204
+ }): Promise<ModelThinking | undefined>;
205
+ /**
206
+ * WHAT PI SAYS IS WRONG WITH ITS OWN MODEL CONFIGURATION, verbatim.
207
+ *
208
+ * Pi validates the WHOLE `models.json` against a schema, and one entry it refuses takes every
209
+ * custom provider out of every picker - while a lenient reader of the same file still lists them
210
+ * all. Pi's own words are the only ones that name the offending field, so they are what the
211
+ * settings panel shows instead of a guess.
212
+ */
213
+ configError(): string | undefined;
214
+ oauthProviders(): Promise<{
215
+ id: string;
216
+ name: string;
217
+ isSubscription: boolean;
218
+ loginLabel?: string;
219
+ authenticated: boolean;
220
+ }[]>;
221
+ loginOAuth(providerId: string, interaction: {
222
+ signal?: AbortSignal;
223
+ prompt(prompt: any): Promise<string>;
224
+ notify(event: any): void;
225
+ }): Promise<void>;
226
+ logoutOAuth(providerId: string): Promise<void>;
227
+ }
228
+ /**
229
+ * What a session says about one model's thinking: the levels it offers, and the one in force.
230
+ *
231
+ * The level is Pi's own answer, already clamped to the model. A level that is not in `levels` is a
232
+ * level the model does not have, and putting it on screen would be a claim the model cannot back.
233
+ */
234
+ export type ModelThinking = {
235
+ levels: string[];
236
+ level?: string;
237
+ };
238
+ /**
239
+ * Builds a zero-process catalog reader.
240
+ *
241
+ * The ModelRuntime and the SettingsManager are created ONCE and reused: both read the auth store and
242
+ * the model store from disk, so a fresh one per call would put the same I/O back that this is here to
243
+ * remove. They are safe to share - they are read-mostly views of the same files.
244
+ *
245
+ * The MODEL LIST is read once, at build time, and the LEVELS are cached per model - both because
246
+ * re-reading them is the cost this exists to remove, and because the answer cannot change while the
247
+ * process runs: a person who edits `auth.json` or adds a model restarts Super Pi, exactly as they
248
+ * would for anything else in Pi's own configuration.
249
+ */
250
+ export declare function createSdkCatalog(cwd: string): Promise<SdkCatalog>;
251
+ /**
252
+ * The transcript file a conversation's session writes to, found WITHOUT starting a Pi process.
253
+ *
254
+ * THIS REPLACES A SPAWN. Revert and fork need to know which file holds a conversation's history, and
255
+ * they used to start a child purely to be told. Pi's SDK answers it from the session
256
+ * manager's own state - and it answers it the same way Pi's RPC mode does, which is the only reason
257
+ * this is safe: Pi looks a session up BY ID and by WORKING DIRECTORY, so asking the library that
258
+ * resolves the session gives the same file the child would have named.
259
+ *
260
+ * Returns undefined when there is no such session, which is the caller's cue to fall back rather than
261
+ * to guess: a wrong path here would truncate somebody else's conversation.
262
+ */
263
+ export declare function resolveTranscriptFile(cwd: string, conversationId: string, sessionDir: string): Promise<string | undefined>;
264
+ /** Whether the SDK could be loaded. Used by the server to report the reason instead of failing a turn. */
265
+ export declare function piSdkAvailable(): Promise<{
266
+ available: true;
267
+ } | {
268
+ available: false;
269
+ reason: string;
270
+ }>;
271
+ /**
272
+ * Everything that was DECIDED when a session was created and cannot be changed afterwards.
273
+ *
274
+ * A change in any of these means the live session is no longer the session the user asked for, and the
275
+ * only honest response is to throw it away and build the right one. The fingerprint exists so that
276
+ * decision is made in one place, by comparison, rather than by a human remembering to restart.
277
+ */
278
+ export interface SessionFingerprint {
279
+ /** The workspace directory. Pi resolves its session file by cwd, so a different cwd is a different file. */
280
+ cwd: string;
281
+ /** The agent's id, or null for Pi's own defaults. The prompt body is read from disk at creation. */
282
+ agentId: string | null;
283
+ /** The tool allowlist, exactly as it was passed to Pi. */
284
+ tools: string[] | undefined;
285
+ /** The denylist, exactly as it was passed to Pi. */
286
+ excludeTools: string[] | undefined;
287
+ /** Which of Super Pi's own extensions were mounted. */
288
+ extensions: string[];
289
+ /**
290
+ * How many times the set of models Pi knows about has changed.
291
+ *
292
+ * NOT THE MODEL, BUT THE WORLD THE MODEL LIVES IN. A session's `ModelRuntime` is built with it and
293
+ * does not learn about a provider added afterwards, so a session that keeps running on the old
294
+ * runtime cannot switch to a model that only exists in the new one - and Pi's refusal to switch is
295
+ * swallowed into a warning, which would leave the turn running a model the picker does not name.
296
+ * The counter makes such a session stale, and it is rebuilt at its next turn.
297
+ */
298
+ modelEpoch: number;
299
+ }
300
+ /**
301
+ * Fingerprints are compared by VALUE, and this is where that comparison is spelled out.
302
+ *
303
+ * The array fields are compared as SETS, not sequences: the tool allowlist is a set of names, and a
304
+ * caller that happens to list them in a different order is asking for the same session, not a new one.
305
+ * Getting this wrong in the strict direction would throw away a perfectly good session on every turn
306
+ * (a latency bug that looks like nothing at all), and getting it wrong in the loose direction would keep
307
+ * a session whose allowlist had genuinely changed (a permission bug). So: order-insensitive, and every
308
+ * element compared exactly.
309
+ */
310
+ export declare function sameFingerprint(a: SessionFingerprint, b: SessionFingerprint): boolean;
311
+ /**
312
+ * The values Super Pi's own extensions read out of their environment.
313
+ *
314
+ * Pi's extension model has no per-session environment: an extension reads `process.env` when it is
315
+ * LOADED. That is fine for a one-process-per-turn design (each turn was its own process) and it is a
316
+ * problem for a shared process, where two conversations would otherwise read each other's values.
317
+ *
318
+ * The resolution is the order of operations, and it is verified rather than assumed: the environment is
319
+ * set, the loader is RELOADED (which is when Pi calls the extension factory, and the factory is what
320
+ * captures the value), and only then is the environment cleared. Two sessions built in an interleaved
321
+ * order each captured their own value - see `scripts/pi-session-isolation.test.mjs`.
322
+ */
323
+ export interface ExtensionEnvironment {
324
+ /** The variable name to value pairs, in the order they should be applied. */
325
+ values: Record<string, string>;
326
+ }
327
+ /**
328
+ * Runs `work` with the given environment applied, and restores the previous values afterwards.
329
+ *
330
+ * The values are applied SYNCHRONOUSLY and the whole of `work` is awaited inside the window, because
331
+ * the extension factory runs during the loader's reload and reads the environment at that moment. A
332
+ * concurrent session's environment would otherwise land in the middle of this one.
333
+ */
334
+ export declare function withEnvironment<T>(values: Record<string, string>, work: () => Promise<T>): Promise<T>;
335
+ /**
336
+ * `withEnvironment` for one session's extension load, serialized across all session creations.
337
+ *
338
+ * The extension factories run inside `work` and capture the values into their closures; after the
339
+ * window closes they never read `process.env` again, so only the WINDOW needs to be exclusive.
340
+ */
341
+ export declare function withIsolatedSessionEnv<T>(values: Record<string, string>, work: () => Promise<T>): Promise<T>;
342
+ /**
343
+ * The live session for one conversation.
344
+ *
345
+ * The Pi types are structural rather than imported, so this file does not force the SDK to be installed
346
+ * for the type checker to work. The shapes here are the ones this code actually uses, and they are
347
+ * checked against the SDK at runtime by the session tests.
348
+ */
349
+ export interface PiSessionLike {
350
+ /** Runs one turn. Resolves when the agent settles. */
351
+ prompt(message: string, options?: {
352
+ images?: PiImageContent[];
353
+ streamingBehavior?: "steer" | "followUp";
354
+ preflightResult?: (result: "handled" | "started" | "queued") => void;
355
+ }): Promise<void>;
356
+ bindExtensions?(bindings: {
357
+ uiContext: unknown;
358
+ mode: "rpc";
359
+ onError: (error: {
360
+ extensionPath: string;
361
+ event: string;
362
+ }) => void;
363
+ }): Promise<void>;
364
+ setCacheWarmingMode?(mode: PiCacheWarmingMode): void;
365
+ readonly settingsManager?: {
366
+ flush(): Promise<void>;
367
+ drainErrors?(): unknown[];
368
+ };
369
+ readonly cacheWarmingStatus?: {
370
+ state: "inactive" | "scheduled" | "refreshing";
371
+ reason?: string;
372
+ nextWarmAt?: number;
373
+ };
374
+ /** True when no agent run or compaction remains; also true when an input hook handled the prompt. */
375
+ readonly isIdle?: boolean;
376
+ /**
377
+ * Queues a message to be answered AFTER the current run finishes its pending work.
378
+ *
379
+ * PI'S OWN FOLLOW-UP QUEUE, and the reason a queued message does not need a turn of its own. A
380
+ * `prompt()` runs `_prepareRun`, which emits `before_agent_start` - and Super Pi's memory extension
381
+ * answers that hook with an HTTP search whose result is patched into the system prompt. So a fresh
382
+ * prompt pays a round trip to the memory endpoint and a bigger prompt; a follow-up is delivered by
383
+ * the agent loop inside the run and pays neither.
384
+ *
385
+ * Optional because a test double has no queues; its absence means "this session cannot hold a
386
+ * message for later", and the caller falls back to answering it as a turn of its own.
387
+ */
388
+ followUp?(message: string, images?: PiImageContent[]): Promise<"queued" | "handled">;
389
+ sendCustomMessage?(message: {
390
+ customType: string;
391
+ content: unknown;
392
+ display?: string;
393
+ details?: unknown;
394
+ }, options?: {
395
+ triggerTurn?: boolean;
396
+ deliverAs?: "steer" | "followUp" | "nextTurn";
397
+ }): Promise<void>;
398
+ /**
399
+ * Removes every message Pi is holding in its steering and follow-up queues, and returns what was
400
+ * removed.
401
+ *
402
+ * PI CANNOT TAKE BACK ONE MESSAGE - `clear_queue` is the only queue command it has - so this is
403
+ * how a host says "none of these are wanted any more". The returned texts are the queue as it
404
+ * was, which is what lets a host put back the ones that should still be answered.
405
+ */
406
+ clearQueue?(): {
407
+ steering: string[];
408
+ followUp: string[];
409
+ };
410
+ /** Aborts the current operation and waits for the session to become idle. */
411
+ abort(): Promise<void>;
412
+ /** Subscribes to session events. Returns the unsubscribe function. */
413
+ subscribe(listener: (event: unknown) => void): () => void;
414
+ /** Releases the session's resources. */
415
+ dispose(): void;
416
+ /** The file Pi writes this session to, when it writes one. */
417
+ readonly sessionFile?: string | undefined;
418
+ /** The id of the session. */
419
+ readonly sessionId?: string | undefined;
420
+ /**
421
+ * The system prompt Pi will send with every turn.
422
+ *
423
+ * READ FOR ITS SIZE, not for its content. The time to first token is a function of how many bytes
424
+ * the provider has to receive before it can answer, so this number is what turns "the model was
425
+ * slow" into a fact. Pi builds the prompt from the agent directory, the skills, the extensions and
426
+ * the context files - none of which Super Pi controls.
427
+ */
428
+ readonly systemPrompt?: string | undefined;
429
+ /**
430
+ * The model the session is running on.
431
+ *
432
+ * READ TO COMPARE, not to set: a model is chosen when the session is created, and a LATER change goes
433
+ * through `setModel`.
434
+ */
435
+ readonly model?: {
436
+ provider?: string;
437
+ id?: string;
438
+ } | undefined;
439
+ /** Pi's estimate for the current context, including its post-compaction unknown state. */
440
+ getContextUsage?(): {
441
+ tokens: number | null;
442
+ contextWindow: number;
443
+ percent: number | null;
444
+ } | undefined;
445
+ /**
446
+ * Switches the model on a LIVE session.
447
+ *
448
+ * THIS IS WHY THE MODEL IS NOT PART OF THE CONFIGURATION FINGERPRINT. Pi can change the model of a
449
+ * running session, so a model change does not need a new session - and making one would cost a
450
+ * transcript replay, which is the most expensive thing this runtime does. A user who picks a different
451
+ * model in the picker would otherwise pay for the whole conversation's history to be re-read.
452
+ *
453
+ * THE ARGUMENT MUST BE A WHOLE MODEL. Pi's `setModel` puts it straight into the agent's state
454
+ * (`agent-session.ts:2514`), so a `{provider, id}` pair is not a shorthand for a model - it IS the
455
+ * model the agent will use, and it has no `api`, no `contextWindow` and no `maxTokens`. Measured:
456
+ * with a whole model the session reports `api=bedrock-converse-stream`,
457
+ * `contextWindow=1000000` and the thinking levels `[off, minimal, low, medium, high]`; with a pair
458
+ * the api and the context window are null and the levels collapse to `[off]`. `resolveModel` is how
459
+ * the whole model is obtained.
460
+ */
461
+ setModel?(model: {
462
+ provider: string;
463
+ id: string;
464
+ [key: string]: unknown;
465
+ }): Promise<void>;
466
+ /**
467
+ * The WHOLE model for a provider/id pair, the way Pi's own `set_model` gets it.
468
+ *
469
+ * Pi's RPC mode looks the pair up in the model runtime's snapshot and hands the FOUND MODEL to
470
+ * `session.setModel` (`rpc-mode.ts:470-477`); the pair alone is never what Pi takes. This is the same
471
+ * lookup, exposed so the caller does not have to own a second model runtime.
472
+ *
473
+ * Optional because a test double has no models; its absence means "this session cannot resolve a
474
+ * model", and the caller then falls back to the pair it has.
475
+ */
476
+ resolveModel?(provider: string, modelId: string): {
477
+ provider: string;
478
+ id: string;
479
+ [key: string]: unknown;
480
+ } | undefined;
481
+ /** The thinking levels the session's current model supports. Pi's own answer, not a derivation. */
482
+ getAvailableThinkingLevels?(): string[];
483
+ setThinkingLevel?(level: string): void;
484
+ /**
485
+ * The session's transcript, for naming a position in it.
486
+ *
487
+ * This is what makes a message a REVERT BOUNDARY on the session path: the one-shot path asked Pi over
488
+ * RPC (`get_entries`, then `get_entries(since: leaf)`); a live session already holds the same entries
489
+ * in memory, so the same question is two synchronous reads - `getLeafId` before the prompt, `getBranch`
490
+ * after it settles. Optional because a test double has no transcript; its absence means "this turn's
491
+ * message cannot be a revert boundary", reported in words, exactly as a failed RPC read was.
492
+ */
493
+ readonly sessionManager?: {
494
+ /** The id of the current leaf entry, or null when the session is still empty. */
495
+ getLeafId(): string | null;
496
+ /** The entries from the root to `fromId` (or the current leaf), in path order. */
497
+ getBranch(fromId?: string): unknown[];
498
+ getEntries?(): unknown[];
499
+ };
500
+ /**
501
+ * The session's extension runner, for binding a UI context AFTER creation.
502
+ *
503
+ * Pi's extensions reach `ctx.ui` through this runner, and the runner starts life with a no-op context
504
+ * that silently answers `undefined`/`false` to everything - which for `confirm` is a fabricated "no"
505
+ * the user never gave. The host binds a real bridging context the first time it runs a turn on the
506
+ * session. Optional for the same reason as `sessionManager`: a test double has no extensions.
507
+ */
508
+ readonly extensionRunner?: {
509
+ setUIContext(uiContext: unknown, mode?: string): void;
510
+ emit?(event: {
511
+ type: "session_shutdown";
512
+ reason: "quit";
513
+ }): Promise<unknown>;
514
+ };
515
+ }
516
+ /** How a session should be built. Everything here is decided once, at creation. */
517
+ export interface SessionCreation {
518
+ /** The workspace. Pi resolves tools and the session file against it. */
519
+ cwd: string;
520
+ /** The session id, which is the Super Pi conversation id. */
521
+ sessionId: string;
522
+ /** The directory Pi keeps its session files in. */
523
+ sessionDir: string;
524
+ /** Previously recorded locator. Its actual header must still match this id and workspace. */
525
+ sessionFile?: string;
526
+ /** Super Pi's extensions to mount, as absolute paths. */
527
+ extensionPaths: string[];
528
+ /** Super Pi's built-in skills to expose beside the user's and workspace's skills. */
529
+ skillPaths?: string[];
530
+ /** The environment those extensions read when they are loaded. */
531
+ extensionEnv: Record<string, string>;
532
+ /** The agent's system prompt file, or undefined for Pi's own defaults. */
533
+ systemPromptFile?: string;
534
+ /** Whether the agent prompt REPLACES Pi's own or is appended to it. */
535
+ systemPromptMode?: "replace" | "append";
536
+ /** The tool allowlist. */
537
+ tools?: string[];
538
+ /** The tool denylist. */
539
+ excludeTools?: string[];
540
+ /** The model to pin. */
541
+ model?: {
542
+ provider: string;
543
+ modelId: string;
544
+ };
545
+ /** The thinking level to pin. */
546
+ thinkingLevel?: string;
547
+ /** Pi's global configuration directory. Defaults to Pi's own resolution. */
548
+ agentDir?: string;
549
+ /** Whether the session writes a file at all. A memory review must not. */
550
+ persist?: boolean;
551
+ }
552
+ /**
553
+ * Builds one Pi session.
554
+ *
555
+ * The order of operations here IS the isolation mechanism, and each step is load-bearing:
556
+ *
557
+ * 1. The loader is created with Super Pi's extension paths, for PI to load - through its jiti
558
+ * transpiler and virtual modules, the same machinery the spawned CLI used. Nothing here imports a
559
+ * Super Pi extension file directly; see the comment at the loader below for why that must never
560
+ * come back.
561
+ * 2. The reload runs inside this session's env window (`withIsolatedSessionEnv`), which is when Pi
562
+ * calls the extension factories. The factories CAPTURE the values; they do not read them later.
563
+ * 3. The session is created with that loader.
564
+ *
565
+ * Step 2 happening outside its env window would give every session the same configuration, and the
566
+ * window would give every session no configuration at all if two creations could interleave - which
567
+ * the serialization in `withIsolatedSessionEnv` prevents.
568
+ *
569
+ * THE FACTORY IS INJECTABLE. A test needs to drive a session without a real Pi behind it - to check what
570
+ * a session was BUILT with (its working directory, its allowlist) rather than what it eventually
571
+ * produced. The factory is therefore a parameter rather than a hard-coded call, and production passes
572
+ * the real one.
573
+ */
574
+ export type PiSessionFactory = (creation: SessionCreation) => Promise<PiSessionLike>;
575
+ export declare function createPiSession(creation: SessionCreation): Promise<PiSessionLike>;
576
+ /**
577
+ * Resolves the session manager for a conversation: the EXISTING transcript if there is one, a new one
578
+ * otherwise.
579
+ *
580
+ * WHY THIS IS NOT JUST `SessionManager.create`. A conversation's transcript outlives its session - Pi
581
+ * writes it to a file, and a session that was evicted (idle, or thrown away by a revert) is rebuilt from
582
+ * that file. So building a session is "reopen the conversation's transcript", and the id is what says
583
+ * which transcript: Super Pi's conversation id IS the session id, which is what makes `revert` and
584
+ * `fork` able to find the file without guessing at a filename.
585
+ *
586
+ * The recorded locator avoids directory discovery altogether. Both paths verify the actual header's
587
+ * exact id and cwd; a stale path or a workspace change must never reopen somebody else's transcript.
588
+ */
589
+ export declare function resolveSessionManager(sdk: Pick<PiSdk, "SessionManager">, creation: SessionCreation): Promise<unknown>;
590
+ type TranscriptHeader = {
591
+ type: "session";
592
+ id: string;
593
+ cwd?: string;
594
+ };
595
+ /** Pi's bounded header discovery contract, using async reads instead of synchronous disk I/O. */
596
+ export declare function readTranscriptHeader(path: string): Promise<TranscriptHeader | undefined>;
597
+ /**
598
+ * Session headers are immutable under Pi's append/rewrite contract. Cache their identities, refresh
599
+ * filenames every lookup, and recheck the selected header before opening. A newly created file is
600
+ * discovered even if stopping/crashing prevented Super Pi from persisting its locator. Arbitrary
601
+ * legacy filenames still work; filenames are never treated as proof of session identity.
602
+ */
603
+ export declare class TranscriptFileIndex {
604
+ private readonly readHeader;
605
+ private readonly directories;
606
+ constructor(readHeader?: (path: string) => Promise<TranscriptHeader | undefined>);
607
+ find(cwd: string, id: string, sessionDir: string): Promise<string | undefined>;
608
+ }
609
+ /**
610
+ * Pi's own global configuration directory, when it can be worked out without importing the SDK.
611
+ *
612
+ * The SDK's `getAgentDir()` is the authority, but asking it would mean importing the SDK - which this
613
+ * file goes out of its way not to do for a path it can derive. The derivation is Pi's own default:
614
+ * `~/.pi/agent`, with the home directory taken from the environment rather than from `os.homedir()`,
615
+ * because on Windows the two disagree often enough to matter.
616
+ *
617
+ * `PI_CODING_AGENT_DIR` WINS, exactly as it wins in Pi (`core/config.ts:getAgentDir`). A person who
618
+ * set it expects Pi to read its whole configuration from there, and this function used to disagree
619
+ * with Pi about it: Pi's model runtime read `models.json` from that directory while the session's
620
+ * resource loader read the skills from `~/.pi/agent`. Two halves of one Pi pointed at two
621
+ * directories, and only one of them was the one the person had configured.
622
+ */
623
+ export declare function defaultAgentDir(): string;
624
+ /**
625
+ * The Super Pi extension files, as absolute paths.
626
+ *
627
+ * Resolved from the repository root, exactly as `runtime.ts` resolves the `--extension` argument it
628
+ * passes to a child process: Pi resolves a relative `--extension` against the CONVERSATION's workspace
629
+ * rather than against the server's directory, so a relative path would find a different file for every
630
+ * workspace. The SDK takes an absolute path, and this keeps the two paths of the same file.
631
+ */
632
+ export interface PromptTemplateSummary {
633
+ name: string;
634
+ description: string;
635
+ argumentHint?: string;
636
+ scope: "user" | "project";
637
+ }
638
+ export declare function loadPromptTemplateSummaries(cwd: string): Promise<PromptTemplateSummary[]>;
639
+ export declare function superPiExtensionPaths(repositoryRoot: string): string[];
640
+ /** Skills shipped by Super Pi itself. Paths are explicit so installed and development layouts agree. */
641
+ export declare function superPiSkillPaths(repositoryRoot: string): string[];
642
+ export {};