@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,2315 @@
1
+ export type ModelFilterRule = {
2
+ id: string;
3
+ workspacePattern: string;
4
+ modelPattern: string;
5
+ label?: string;
6
+ };
7
+ import type { WorkflowRun } from "./workflow.js";
8
+ import type { BackgroundTaskDetails } from "../shared/background-task.js";
9
+ import type { GroupActivityUpdate } from "../shared/group-chat.js";
10
+ import type { ScheduledTask } from "./scheduled-tasks.js";
11
+ import type { ThinkingLevelMap } from "../shared/thinking-levels.js";
12
+ import type { TerminalCommand, TerminalEvent } from "../shared/terminal-protocol.js";
13
+ /**
14
+ * The lifecycle states a `Conversation.status` moves through while a turn is in flight. `waiting` is the
15
+ * gap between "prompt handed to the LLM" and "the first response token arrived" - holding it apart from
16
+ * `running` is what lets the reader tell a slow or broken LLM endpoint (still waiting) apart from a
17
+ * streaming turn that is just slow (already running, just no new tokens in the last second). Without
18
+ * the gap the two states look the same on screen for as long as the model is silent, and the reader has
19
+ * no signal to debug from.
20
+ *
21
+ * `completed` / `stopped` / `failed` are the three settled states. `stopped` is what `run.stop` lands;
22
+ * `failed` is what any unhandled throw lands (with `Conversation.error` carrying the translated reason);
23
+ * `completed` is the clean path.
24
+ */
25
+ export type RunStatus = "idle" | "waiting" | "running" | "awaiting_background" | "completed" | "stopped" | "failed";
26
+ export type MessageRole = "user" | "assistant" | "tool" | "system";
27
+ /**
28
+ * One message in `state.json`.
29
+ *
30
+ * `piEntryId` is Pi's own id for the entry this message became, recorded while Pi was still alive.
31
+ *
32
+ * WHY A SUPER Pi MESSAGE NEEDS A PI ID AT ALL. The two histories are separate files in separate formats
33
+ * - `state.json` here, Pi's session JSONL in the session directory - and they share nothing but the
34
+ * conversation id (research §3.2). A revert has to cut BOTH at the same place, and Pi's file can only be
35
+ * cut at one of its own entry ids: `SessionManager` refuses to delete entries (`:1516-1519`), and the
36
+ * research' pitfall 6 rules out guessing a line number, because Pi writes far more entry types than
37
+ * messages and a "the Nth user message" boundary would slice a compaction record in half.
38
+ *
39
+ * So the id is captured per turn, from Pi's own `get_entries` (`rpc-mode.ts:636-647`), in the only window
40
+ * where it is available: Super Pi spawns one Pi per turn and kills it in a `finally`
41
+ * (`runtime.ts:429-435`), so the answer has to be taken before that. A message recorded before this
42
+ * field existed has no id, and is therefore not a valid revert boundary - which the handler says out
43
+ * loud rather than reverting to a guessed line.
44
+ *
45
+ * Optional on purpose: a `state.json` written before revert existed has no such key, and absent reads as
46
+ * "Pi never told us", needing no migration.
47
+ *
48
+ * `toolCalls` is the OTHER optional field, and it lives ON THE MESSAGE rather than in a separate top-level
49
+ * array. That is a claim about where a call happens: Pi executes a tool call after the assistant message
50
+ * that requested it and before the next one, so the calls belong to the turn the message belongs to and to
51
+ * nothing else. Attaching them there makes the transcript's ordering free - a block renders under its own
52
+ * message, and a reload rebuilds it from the same `state` snapshot the text came from, with no second source
53
+ * of truth to fall out of sync.
54
+ *
55
+ * A FOLLOW-UP ROUND GETS ITS OWN, because each one calls `beginAssistantMessage` and therefore opens a
56
+ * fresh message: the chain in `index.ts` sends a queued message as a new prompt, and Pi's calls for that
57
+ * prompt cannot be filed under the answer to the previous one.
58
+ *
59
+ * Also optional, so a `state.json` written before either field existed reads as "this turn used no tools",
60
+ * which is what such a turn genuinely is.
61
+ */
62
+ /**
63
+ * One image attached to a message or queue item.
64
+ * Stored as a reference (file ID + metadata), NEVER base64 bytes in state.json,
65
+ * to prevent massive state bloat during streaming broadcast.
66
+ */
67
+ export type MessageImage = {
68
+ id: string;
69
+ name?: string;
70
+ mimeType: string;
71
+ bytes: number;
72
+ width?: number;
73
+ height?: number;
74
+ };
75
+ /**
76
+ * Base64 image payload passed to Pi's session/RPC APIs (never persisted in state.json).
77
+ * Kept distinct from `MessageImage` so file references cannot be handed to Pi unhydrated.
78
+ */
79
+ export type PiImageContent = {
80
+ type: "image";
81
+ data: string;
82
+ mimeType: string;
83
+ };
84
+ /** ONE QUESTION AS THE TOOL ASKED IT, before any answer exists.
85
+ * Mirrors OpenCode's `QuestionV2.Prompt`: a stable id so the answer pairs by identity rather than by
86
+ * position, a short header for a dock, and options with their own text. */
87
+ export type QuestionItem = {
88
+ id: string;
89
+ header?: string;
90
+ question: string;
91
+ options: string[];
92
+ multiple: boolean;
93
+ extraNote: boolean;
94
+ };
95
+ /** WHAT THE PERSON CHOSE, paired to a `QuestionItem` by id. */
96
+ export type QuestionAnswer = {
97
+ id: string;
98
+ selected: string[];
99
+ note?: string;
100
+ };
101
+ /**
102
+ * A QUESTION IS A TOOL CALL, NOT A SECOND KIND OF BLOCK.
103
+ *
104
+ * It used to be a `questionBlocks` array hung off the message, which meant the question had no place
105
+ * in the answer: it rendered after everything the model said, so the text streamed in response to the
106
+ * answer appeared ABOVE the card it was answering. The tool-call row already carries an `at` offset, is
107
+ * already persisted, already reloads, and already expands - so the question lives there too, and the
108
+ * ordering, the persistence and the replay all come from the mechanism that was already correct.
109
+ */
110
+ export type ToolCallQuestion = {
111
+ items: QuestionItem[];
112
+ status: "pending" | "answered" | "cancelled";
113
+ answers?: QuestionAnswer[];
114
+ };
115
+ export type Message = {
116
+ backgroundTask?: BackgroundTaskSummary;
117
+ id: string;
118
+ role: MessageRole;
119
+ source?: "session-reminder";
120
+ content: string;
121
+ createdAt: string;
122
+ piEntryId?: string;
123
+ toolCalls?: ToolCallBlock[];
124
+ thinking?: string;
125
+ thinkingBlocks?: {
126
+ at: number;
127
+ text: string;
128
+ }[];
129
+ thinkingActive?: boolean;
130
+ images?: MessageImage[];
131
+ attachments?: MessageAttachments;
132
+ agentIdentity?: {
133
+ id?: string;
134
+ name: string;
135
+ };
136
+ delivery?: MessageDelivery;
137
+ };
138
+ /**
139
+ * WHERE A USER MESSAGE IS IN ITS OWN DELIVERY, or `undefined` for every message that is not waiting.
140
+ *
141
+ * A user message is written into the transcript the instant it is sent, BEFORE any turn has started,
142
+ * and it stays in that exact position until the agent has answered it. What changes meanwhile is this
143
+ * field and nothing else - see `docs/QUEUE-UX.md` for why the message must never move.
144
+ *
145
+ * ABSENT means "not waiting": a message the agent is answering right now, one it already answered, one
146
+ * withdrawn, and every `assistant` / `tool` message. Only `role: "user"` ever carries it.
147
+ *
148
+ * - `waiting` - said, not yet handed to the agent. CANCELLED freely, EDITED freely, and REORDERED
149
+ * freely. This is where essentially every waiting message lives, because a message is only given to
150
+ * Pi at the moment it is about to be delivered.
151
+ * - `sending` - written to a live Pi child's stdin as a `steer` and not yet confirmed delivered. NOT
152
+ * cancellable and NOT editable: Pi has no single-item retract (its only queue command is
153
+ * `clear_queue`, which clears everything), so a UI offering either would be a promise the transport
154
+ * cannot keep. It returns to `waiting` exactly when we can prove Pi never delivered it - the turn
155
+ * ended - and stays here when Pi simply has not answered yet.
156
+ *
157
+ * WHY A FIELD AND NOT A SEPARATE LIST. The waiting list used to be its own array of content copies
158
+ * (`QueuedMessage`), and that is what made two bugs structural rather than accidental: a queued entry
159
+ * was not a message, so promoting one to a turn had to CREATE a message - which is why a steered
160
+ * message reached Pi and the model and never reached the transcript at all - and "delivered" could only
161
+ * be expressed by DELETING a row, so every delivery was an opportunity to lose the user's words. A
162
+ * message with a state has an identity to transition and nothing to delete.
163
+ *
164
+ * ORDER IS THE QUEUE. There is no `priority` flag and no second source of truth: the waiting messages
165
+ * are the trailing `role: "user"` messages of the array, and "put this one first" is a move within
166
+ * that block.
167
+ */
168
+ export type MessageDelivery = "waiting" | "sending";
169
+ /**
170
+ * A piece of context attached to a user message that is shown as its OWN block under the bubble, rather
171
+ * than flattened into the prompt. Today: a skill the person picked from the slash menu - the model gets
172
+ * the skill text inlined into the prompt for execution, and the transcript shows the user that the
173
+ * skill they asked for is the one that was loaded. Collapsed by default because skill bodies can be
174
+ * hundreds of lines and the user already chose the skill by name.
175
+ */
176
+ export type MessageAttachment = {
177
+ kind: "skill";
178
+ id: string;
179
+ name: string;
180
+ content: string;
181
+ };
182
+ export type MessageAttachments = MessageAttachment[];
183
+ export interface SkillSummary {
184
+ id: string;
185
+ name: string;
186
+ description: string;
187
+ scope?: "workspace" | "global" | "memory";
188
+ filePath?: string;
189
+ }
190
+ /**
191
+ * ONE PARAMETER OF A TOOL CALL, as a call block lists it, and the boundary that keeps Pi's arguments out
192
+ * of `state.json`.
193
+ *
194
+ * `value` is DERIVED, never the raw argument: a string is whitespace-collapsed and hard-capped, and
195
+ * anything that is not a string, a number or a boolean becomes a bare type word (`(对象)`,
196
+ * `(数组 3 项)`). That second half is the load-bearing part - an `edit`'s arguments routinely carry a
197
+ * replacement block for a whole file, so rendering such a value even truncated would put file contents
198
+ * into a field that is persisted in `state.json` and broadcast to every browser. See `describeToolCallArgs`.
199
+ */
200
+ export type ToolCallArg = {
201
+ key: string;
202
+ value: string;
203
+ };
204
+ /**
205
+ * ONE TOOL CALL THE PRIMARY AGENT MADE, as a block in the transcript.
206
+ *
207
+ * SAME FOUR FACTS AS `SubagentToolCall`, and deliberately the same granularity: `label` is the tool name,
208
+ * `detail` is the one bounded line naming what it was aimed at (the file it read, the pattern it searched
209
+ * for, the command it ran), `status` and `durationMs` come from Pi's own `tool_execution_end`. A call block
210
+ * that showed MORE than a sub-agent card row would answer a question the brief does not ask and would make
211
+ * the two surfaces disagree about what a tool call is.
212
+ *
213
+ * `args` and `result` are the two additions, and they are what makes a block worth expanding: a card row
214
+ * answers "what was this aimed at", while a block also answers "what else was it given" AND "what came
215
+ * back". `args` is bounded to six entries by `TOOL_ARG_CAP`; `result` is bounded by `TOOL_RESULT_CAP` and
216
+ * keeps the TAIL of the output, because a tool's answer ends in what it just found.
217
+ *
218
+ * `result` IS HERE NOW, AND ITS ARRIVAL OVERRULED A STANDING DECISION. It used to be written off in this
219
+ * very comment — "`result` on `tool_execution_end` is, for a `read`, the file's contents" — and
220
+ * `scripts/agent-vis-records.test.mjs` asserted the boundary from the outside, failing on the raw bytes of
221
+ * `state.json` if a result ever survived into it. Both said the same thing: a call block describes a call,
222
+ * it does not carry its output. That was right until it wasn't: expanding a `bash` block showed the command
223
+ * a second time and nothing of what the command found, which is the one thing the reader opened it for.
224
+ *
225
+ * What made it safe to reverse is that the bound was always the hard part and it is still enforced:
226
+ * `extractToolResultText` drops images rather than carrying base64, truncates on a line boundary, and is
227
+ * the ONLY path from Pi's result to anything downstream — the raw object never travels. And `result` is
228
+ * OPTIONAL for the same reason `status` is: absent means this call's output was never recorded, which is a
229
+ * different fact from "recorded, and it was empty", and a default of `""` would state the second while
230
+ * meaning the first.
231
+ *
232
+ * Pi's `toolCallId` is still not here, and is still right not to be: it is an identity only Pi can resolve,
233
+ * which is why the record is addressed by position (the caller holds a `toolCallId` → row map for the
234
+ * length of a turn, exactly as `SubagentRunRecorder` does) rather than by a field persisted forever.
235
+ *
236
+ * `status` is OPTIONAL, not defaulted to `"ok"`, for the same reason it is on `SubagentToolCall`: a default
237
+ * would claim an outcome nobody observed. Absent means the call is still in flight, which is the state a
238
+ * block is in for most of a long tool call.
239
+ */
240
+ export type ToolCallBlock = {
241
+ label: string;
242
+ detail?: string;
243
+ status?: "ok" | "error";
244
+ durationMs?: number;
245
+ args?: ToolCallArg[];
246
+ result?: ToolResultSummary;
247
+ /**
248
+ * OUTPUT AS IT IS ARRIVING, while the call is still running. Replaced by `result` the moment the call
249
+ * ends, and absent before the first update - so it is never mistaken for the final answer, which is the
250
+ * distinction that matters when a reader copies it.
251
+ */
252
+ live?: string;
253
+ /** The model is still GENERATING this call's arguments. Nothing has reached the host yet, so this is
254
+ * the only thing on screen during a long parameter stream - an 'edit' block carries a whole file's
255
+ * replacement text, and without this the screen is blank until the last token arrives. */
256
+ preparing?: boolean;
257
+ /**
258
+ * WHERE IN THE ANSWER the call happened, as a character offset into `content` - and WHERE IN THE
259
+ * REASONING, as an offset into `thinking`.
260
+ *
261
+ * A TURN HAS TWO STREAMS, and a call belongs to a position in each. `at` places it among the words the
262
+ * agent spoke; `thinkingAt` places it inside the reasoning it did before speaking, which is what lets a
263
+ * call that happened mid-thought render INSIDE the thinking block rather than beside it. Without the
264
+ * second offset a tool call can only be stacked after the reasoning, which reads as "the model thought,
265
+ * and then, separately, called a tool" - the order the events did not have.
266
+ *
267
+ * OPTIONAL, and absent means "this call's place in the reasoning was never recorded" - a message written
268
+ * before the field existed. A reader that guesses a position for such a call would be re-ordering a turn
269
+ * on no evidence, so it must fall back to `at` alone, which is exactly what those blocks were written to
270
+ * be read by.
271
+ */
272
+ at?: number;
273
+ thinkingAt?: number;
274
+ /** Index into the message's thinkingBlocks, captured when this call was first announced.
275
+ * null means outside reasoning; absence is an older record with offsets only. */
276
+ thinkingBlock?: number | null;
277
+ /** A background command keeps its dispatch position and settled output after the active task is removed. */
278
+ backgroundTask?: BackgroundTaskDetails;
279
+ question?: ToolCallQuestion;
280
+ };
281
+ /**
282
+ * ONE TOOL CALL'S OUTPUT, reduced to the part a person reads and bounded so it cannot become the
283
+ * transcript. The shape is closed on purpose: `text` is what to show, and the three optional fields are
284
+ * what it would be dishonest to omit once the text is known to be short.
285
+ */
286
+ export type ToolResultSummary = {
287
+ text: string;
288
+ /** The output was cut. Never inferred from length alone — only set when Pi said so. */
289
+ truncated?: boolean;
290
+ /** Lines Pi dropped, when it said how many. */
291
+ droppedLines?: number;
292
+ /** Where Pi put the full output, when it was large enough to warrant a file. */
293
+ fullOutputPath?: string;
294
+ };
295
+ /**
296
+ * WHAT THE RUNTIME HANDS A CALLER WHEN PI ANNOUNCES OR FINISHES A TOOL CALL.
297
+ *
298
+ * Mirrors `SubagentToolCall` and is declared here rather than in `runtime.ts` because `runtime.ts` cannot
299
+ * import `subagents.ts` (that module imports the runtime), so a type living beside the supervisor would be
300
+ * unreachable from the only file that produces the primary agent's calls. It carries Pi's `id` because the
301
+ * CALLER needs it to match an end back to its start - the persisted `ToolCallBlock` deliberately does not.
302
+ */
303
+ export type ToolCallNotice = {
304
+ id: string;
305
+ name: string;
306
+ detail?: string;
307
+ args?: ToolCallArg[];
308
+ status?: "ok" | "error";
309
+ durationMs?: number;
310
+ question?: ToolCallQuestion;
311
+ result?: ToolResultSummary;
312
+ live?: string;
313
+ preparing?: boolean;
314
+ };
315
+ /** WHAT THE RUNTIME HANDS A CALLER WHEN THE MODEL STARTS, OR CONTINUES, BUILDING A TOOL CALL. *
316
+ *
317
+ * `detail` is the line naming what the call is aimed at - the file for a `read`, the command for a `bash`
318
+ * - read out of the arguments as far as they have arrived. It is `undefined` when nothing identifying has
319
+ * been written yet, which is a different fact from an empty one: the caller has a placeholder word for the
320
+ * second case and must not invent one for the first.
321
+ *
322
+ * `live` is the arguments AS THEY STAND - the whole text written so far, never the newest fragment alone.
323
+ * It shares its meaning with `tool_execution_update`'s output (which Pi sends already accumulated), so one
324
+ * field with two meanings would make the caller store one kind of text by appending and the other by
325
+ * replacing - which is a flicker and a duplication at once. Pi sends argument fragments raw; accumulating
326
+ * them is the runtime's job, where the fragments already are.
327
+ *
328
+ * `args` arrives ONLY at `toolcall_end`, where Pi hands over the finished argument object. Nothing before
329
+ * that point can produce it: `live` is raw JSON text, and a half-written document is not one. It is what
330
+ * gives a row its parameters before `tool_execution_start` announces the call, so a call the turn cut off
331
+ * mid-flight shows what it was going to do instead of 「(这次调用没有可显示的参数)」. Bounded by the same
332
+ * `describeToolCallArgs` derivation as every other arguments field, so it adds no new way for raw arguments
333
+ * to reach `state.json`.
334
+ *
335
+ * `final` says these are the FINISHED arguments, and it exists so that one cannot create a row. Pi emits
336
+ * `toolcall_end` whenever the argument document closes, which on a live probe is before the call runs -
337
+ * but a turn can also close a document after the call has already been announced and settled, and a
338
+ * notice that arrives then describes a row that is already on screen. A caller that treated it as an
339
+ * announcement would append a second, empty block for a call the reader is already looking at.
340
+ */
341
+ export interface ToolCallPreparing {
342
+ contentIndex: number;
343
+ name: string;
344
+ live?: string;
345
+ detail?: string;
346
+ args?: ToolCallArg[];
347
+ final?: boolean;
348
+ }
349
+ /**
350
+ * `archivedAt` is the whole archive mechanism: a state MARKER, not a move. The conversation object never
351
+ * changes workspace or position, so archiving and restoring are a stamp and a clear of one optional field.
352
+ *
353
+ * It is optional on purpose. A `state.json` written before archiving existed simply has no such key, so
354
+ * `undefined` means "not archived" and old state loads as live with no migration step and no data rewrite.
355
+ * An ISO-8601 string also carries when the conversation was archived, which the sidebar shows in place of
356
+ * the live timestamp.
357
+ */
358
+ /**
359
+ * The model a conversation runs on. Provider and id are ONE optional field, never two, because Pi's
360
+ * `set_model` command takes both (rpc-mode.ts:470) and a half-updated pair - an id without its
361
+ * provider, or a provider whose id no longer exists - is a selection Pi rejects at the start of the
362
+ * next turn. Nesting them makes that state unrepresentable.
363
+ *
364
+ * `label` is the display name Pi itself reported, kept so a conversation opened without a catalog
365
+ * fetch still renders something a human recognises instead of a bare model id.
366
+ */
367
+ export type ModelSelection = {
368
+ provider: string;
369
+ modelId: string;
370
+ label: string;
371
+ };
372
+ /**
373
+ * One entry of Pi's `get_available_models` answer, narrowed to what a picker needs. Pi's `Model`
374
+ * objects also carry baseUrl, cost tables and compat maps (17KB for the 28 models this build sees);
375
+ * keeping them would put provider URLs in the browser's state for no gain. `detail` is
376
+ * `provider/modelId`, the pair Pi needs back in `set_model`, shown so two same-named models from
377
+ * different providers are distinguishable.
378
+ *
379
+ * `imageInput` is derived from Pi's own `input` array rather than carried raw, so the browser holds
380
+ * one boolean instead of a modality list it would have to interpret. It is CATALOG state, never
381
+ * conversation state: a copy frozen onto a conversation would be wrong the moment Pi changed a
382
+ * model, and nothing reads one - see the note on `setConversationModel`.
383
+ * `thinkingLevels` is the similarly small, derived list for a model-specific settings picker; the
384
+ * active session's levels cannot stand in for a different model selected as a workspace default.
385
+ */
386
+ export type ModelOption = ModelSelection & {
387
+ detail: string;
388
+ reasoning: boolean;
389
+ contextWindow: number;
390
+ maxTokens: number;
391
+ imageInput: boolean;
392
+ thinkingLevels?: string[];
393
+ };
394
+ /**
395
+ * What the picker lists, read from Pi and cached by the runtime.
396
+ *
397
+ * `source` is "unavailable" when Pi could not be asked, which the UI renders as a disabled control
398
+ * rather than an empty list: an empty list is indistinguishable from "you have no models", and the
399
+ * honest answer is "the list could not be read". `fetchedAt` travels with the value so a stale
400
+ * cache is visible rather than silent.
401
+ */
402
+ /**
403
+ * A provider a person added through the settings window, as the BROWSER sees it.
404
+ *
405
+ * The API key is a FACT here and not a value: `hasKey` says whether one is stored, and the key
406
+ * itself never leaves the server. It is in Super Pi's own registry and in Pi's `auth.json`, both of
407
+ * them files with restrictive permissions, and in neither the state snapshot nor any event.
408
+ */
409
+ export type PublicProviderModel = {
410
+ id: string;
411
+ name: string;
412
+ reasoning: boolean;
413
+ imageInput: boolean;
414
+ contextWindow: number;
415
+ maxTokens: number;
416
+ /**
417
+ * The thinking levels this model really offers, and what each one is sent as.
418
+ *
419
+ * ABSENT means "nobody said" - the map was never written, so Pi's own defaults apply. It is not
420
+ * the same as an empty map, because Pi reads a level the map does not mention as "the model has
421
+ * it".
422
+ */
423
+ thinkingLevelMap?: ThinkingLevelMap;
424
+ };
425
+ export type PublicProvider = {
426
+ id: string;
427
+ name: string;
428
+ baseUrl: string;
429
+ api: string;
430
+ hasKey: boolean;
431
+ authType?: "api_key" | "oauth";
432
+ oauthSubscription?: boolean;
433
+ oauthLoginLabel?: string;
434
+ authenticated?: boolean;
435
+ /**
436
+ * TRUE when the key lives in `models.json` itself (Pi's `"apiKey": "$MY_KEY"` form) rather than
437
+ * in `auth.json`. It is a credential all the same, so the panel must not report it as missing.
438
+ */
439
+ keyInModelsJson?: boolean;
440
+ /**
441
+ * The fields of this provider's `models.json` entry that Pi's schema refuses (an empty string
442
+ * where Pi asks for at least one character). Pi rejects the WHOLE file over one of them, so every
443
+ * custom provider leaves the picker at once.
444
+ */
445
+ invalidFields?: string[];
446
+ /**
447
+ * TRUE when the provider is one of Pi's own, with no entry in `models.json`.
448
+ *
449
+ * Its models come from Pi's catalogue rather than from a file, so the panel can show it and switch
450
+ * it off but cannot offer an address to edit: there is no file field to edit.
451
+ */
452
+ builtin?: boolean;
453
+ /**
454
+ * TRUE when the provider is currently switched OFF: Pi does not offer it, and switching it back on
455
+ * restores the `models.json` entry and the credential exactly as they were.
456
+ */
457
+ disabled?: boolean;
458
+ models: PublicProviderModel[];
459
+ };
460
+ export type DiscoveredModel = {
461
+ id: string;
462
+ name: string;
463
+ reasoning: boolean;
464
+ imageInput: boolean;
465
+ contextWindow: number;
466
+ maxTokens: number;
467
+ /**
468
+ * The thinking levels the provider PUBLISHED for this model, and what each one is sent as.
469
+ *
470
+ * ABSENT when nobody published them, and that is the common case: a provider that lists a model
471
+ * without saying which effort levels it accepts has said nothing, and this must not pretend
472
+ * otherwise. The map names all seven levels, with `null` for the ones the model does not have.
473
+ */
474
+ thinkingLevelMap?: ThinkingLevelMap;
475
+ };
476
+ export type ModelCatalog = {
477
+ source: "pi" | "unavailable";
478
+ models: ModelOption[];
479
+ /** Exactly what `get_available_thinking_levels` returned, in Pi's own order. Never hardcoded. */
480
+ levels: string[];
481
+ defaultModel?: ModelSelection;
482
+ defaultThinkingLevel?: string;
483
+ fetchedAt: string;
484
+ error?: string;
485
+ /**
486
+ * What Pi says is wrong with its own model configuration, in Pi's own words.
487
+ *
488
+ * Pi validates the whole `models.json`, so one entry it refuses empties every picker of custom
489
+ * providers. This is the only place that says which field is at fault.
490
+ */
491
+ configError?: string;
492
+ };
493
+ export type Conversation = {
494
+ id: string;
495
+ title: string;
496
+ workspaceId: string;
497
+ updatedAt: string;
498
+ status: RunStatus;
499
+ messages: Message[];
500
+ archivedAt?: string;
501
+ followedWorktreeId?: string;
502
+ /** Private receipts retained even when a message is withdrawn or cut from history. */
503
+ acceptedSendIds?: string[];
504
+ warmSession?: true;
505
+ /**
506
+ * Cumulative usage observed for this conversation: its OWN assistant messages AND the one-shot
507
+ * (sub-agent) calls it dispatched.
508
+ *
509
+ * THE SUB-AGENT'S USAGE IS IN HERE ON PURPOSE. A child Pi spends real money, and a budget that
510
+ * only counts the parent's own turns is a budget that can be multiplied past its own cap by
511
+ * dispatching children instead of answering - which is exactly what design §5 forbids, because
512
+ * "写预算的人必须能自己算出这个数是多少钱" is only true if the number includes every call the
513
+ * conversation made. The child's final accumulated usage is folded in ONCE, when the run settles
514
+ * (see `Store.accountSubagentUsage`), so the sum here equals what was really spent.
515
+ */
516
+ usage?: SubagentUsage;
517
+ /** False means cost is only a sum of reported costs, not a complete price (zero is not "free"). */
518
+ usageCostKnown?: boolean;
519
+ /** Persisted Pi cache-warming entry ids, for replay-safe background accounting. */
520
+ accountedPiUsageEntries?: string[];
521
+ contextUsage?: ConversationContextUsage;
522
+ usageUpdatedAt?: string;
523
+ /** Transport projection only: false means messages were omitted, rather than an empty transcript. */
524
+ messagesLoaded?: boolean;
525
+ /** Pending question summary, retained when a focused snapshot omits this conversation's messages. */
526
+ hasPendingQuestion?: boolean;
527
+ /** Pi's own resolved transcript path, observed from this conversation's live worker. It is only a
528
+ * locator: revert still verifies the file header and every retained boundary before writing. */
529
+ piSessionFile?: string;
530
+ /** Set when the user explicitly names the session; automatic first-message titles must not overwrite it. */
531
+ titleLocked?: boolean;
532
+ /**
533
+ * Why this conversation is not `running`, in WORDS A PERSON READS - the same role `SubagentRun.error`
534
+ * plays for a card, one level up.
535
+ *
536
+ * Set by startup reconciliation, and ONLY by it: a conversation the previous server left `running` is
537
+ * failed here with this reason, and `addUserMessage` deletes the key the moment the user retries, so
538
+ * the field can never describe a run other than the one that most recently failed to finish. A value
539
+ * that outlived its run would be worse than no value at all, because the reader would take it for the
540
+ * current turn's outcome.
541
+ *
542
+ * Prose rather than a code because this is the ONE string from state.json that a human is expected to
543
+ * read on purpose; the chat pane renders it verbatim under the header. An internal error code here
544
+ * would answer "what happened" with something the reader has to go and decode.
545
+ */
546
+ error?: string;
547
+ /**
548
+ * WHY THIS CONVERSATION'S LAST ANSWER IS INCOMPLETE - in words a person reads.
549
+ *
550
+ * A WARNING, not a failure. The model filled its single-response output budget and stopped
551
+ * mid-answer; everything it said is on screen, and the conversation is still usable. It is a
552
+ * separate field from `error` because the two mean different things to the reader: `error` says
553
+ * "this run broke, here is why", this says "this answer was cut short, and here is what to do
554
+ * about it". Collapsing them would paint a recoverable truncation as a crash - which is exactly
555
+ * what made an orchestrated child session die.
556
+ *
557
+ * Cleared by the next turn, the same way `error` is: it describes the turn that just ended and
558
+ * must never outlive it.
559
+ */
560
+ warning?: string;
561
+ /**
562
+ * WHY THIS CONVERSATION IS NOT ON THE MODEL THE USER SET FOR IT - in words a person reads.
563
+ *
564
+ * A default model can stop being usable between one session and the next: Pi may drop the model
565
+ * from its list, or the workspace's own model rules may forbid it. The conversation then starts on
566
+ * Pi's own default, which is the right behaviour - but doing it SILENTLY is not: the user set a
567
+ * default, they set a rule, and nobody told them the two contradicted each other (TEST-062).
568
+ *
569
+ * It lives on the conversation rather than on the workspace because that is where the decision
570
+ * was made: a default can be usable for one workspace and unusable for another, and two
571
+ * conversations of the same workspace can disagree if the rules changed in between. It is set
572
+ * ONCE, at birth, and never rewritten afterwards - it describes how this conversation came to be,
573
+ * not what is true right now.
574
+ */
575
+ modelNotice?: string;
576
+ /** Why this conversation started on Pi's default agent instead of the workspace's deleted default.
577
+ * Written once at birth, like modelNotice, and rendered verbatim. */
578
+ agentNotice?: string;
579
+ /** Absent means "Pi's own default", which is why a conversation created before the picker existed still works. */
580
+ model?: ModelSelection;
581
+ thinkingLevel?: string;
582
+ /**
583
+ * The agent whose role, tool allowlist and prompt apply to this conversation's turns. Absent means
584
+ * "Pi's own defaults", exactly as for `model` - so a state.json written before agents existed needs
585
+ * no migration and reads as a conversation with no role.
586
+ *
587
+ * It holds only the ID, never a copy of the agent. The definition is re-read from disk on every turn,
588
+ * so editing an agent's prompt or tools takes effect on the next message with no re-selection, and a
589
+ * deleted agent degrades to "no role" instead of leaving a stale snapshot in state.json.
590
+ */
591
+ agentId?: string;
592
+ /** Relative to the workspace root. Absent or empty preserves the original workspace-root cwd. */
593
+ cwd?: string;
594
+ /**
595
+ * The conversation that opened this one, when an orchestrator agent created it. Absent for a
596
+ * conversation the user started. This is the session tree's edge, and it PERSISTS: the sidebar
597
+ * draws the hierarchy from it after a restart, which a server-side in-memory ledger cannot do.
598
+ * Absence also reads correctly on every state.json written before this field existed - no parent
599
+ * recorded simply means "top level", which is what those conversations genuinely are.
600
+ */
601
+ parentConversationId?: string;
602
+ /**
603
+ * 上次向父会话汇报的时间戳(ISO 字符串)。仅子会话有意义。
604
+ * 初始为空;父会话通过工具/转述/完成读取该子会话后写入。
605
+ * 只要本字段存在,子会话就在汇报轴上算「已汇报」。
606
+ */
607
+ reportedToParentAt?: string;
608
+ /** 该会话是否存在未决的例外升级(等待上级处理)。 */
609
+ hasOpenEscalation?: boolean;
610
+ /**
611
+ * 这条未决例外该谁拍板:`supervisor` = 团队内部(直属上级),`boss` = 到了顶层。
612
+ * 与 `hasOpenEscalation` 一样是只读投影,不落盘;客户端靠它区分「内部升级」和
613
+ * 「真的需要用户决定的事」——只有后者才配出现在用户面前。
614
+ */
615
+ escalationAudience?: "supervisor" | "boss";
616
+ /** Read-only projection: whether this child session still has an undelivered result in its parent's waiting queue. */
617
+ hasPendingResult?: boolean;
618
+ /**
619
+ * 用户上次点击阅读该会话的时间戳(ISO 字符串)。
620
+ * 顶层会话退回到根据这个判断未读;子会话不看这个。
621
+ */
622
+ /** Stable memory-sharing identity, inherited at birth; forks start a new tree. */
623
+ treeId?: string;
624
+ /**
625
+ * Who opened this conversation. "user" for one the user started, "orchestrator" for one an agent
626
+ * created. Kept beside the parent id because a conversation can be an orchestrator's without
627
+ * having a parent (the top-level orchestrator), and because the context menu's "stop the session
628
+ * AND its queue" needs to know a queue exists without polling the orchestrator's ledger.
629
+ */
630
+ origin?: "user" | "orchestrator";
631
+ };
632
+ /**
633
+ * One parsed agent definition, as read from an `agents/*.md` file. `prompt` is the file body and is the
634
+ * system prompt; the frontmatter fields are borrowed from OpenCode's agent format.
635
+ *
636
+ * `toolFlags` is the TRANSLATED Pi command line, not the raw map: `tools: {"*": false, read: true}`
637
+ * becomes `["--tools", "read"]`. Keeping the translation next to the definition means the runtime
638
+ * cannot pick a different one, and a test can assert the exact flags without spawning Pi.
639
+ */
640
+ export type AgentDefinition = {
641
+ /** The file's base name. Stable, human-chosen, and the id a conversation stores. */
642
+ id: string;
643
+ name: string;
644
+ mode: "primary" | "subagent";
645
+ description: string;
646
+ color?: string;
647
+ hidden: boolean;
648
+ /** `provider/modelId` from frontmatter, split into the pair Pi's `set_model` requires. */
649
+ model?: {
650
+ provider: string;
651
+ modelId: string;
652
+ };
653
+ thinkingLevel?: string;
654
+ /** `append` adds the body to Pi's baseline prompt; `replace` makes it the whole system prompt. */
655
+ promptMode: "append" | "replace";
656
+ toolFlags: string[];
657
+ taskPolicy?: Record<string, unknown>;
658
+ /** For display only. Empty means "Pi's own default tool set" or "every tool denied". */
659
+ toolNames: string[];
660
+ /**
661
+ * The `tools:` frontmatter MAP, kept alongside the flags it was translated into.
662
+ *
663
+ * `toolFlags` is the answer to "what does Pi get"; this is the question behind it. Keeping the source
664
+ * next to the translation is what lets a caller's constraint be applied to an agent that is about to be
665
+ * spawned - a child whose allowlist must lose the tools its parent denied
666
+ * (`agentSpawnArgs(..., { denyTools })`) cannot be expressed by editing a flag list that has already
667
+ * been flattened into two argv strings. Kept optional so a hand-built definition in a test does not
668
+ * have to invent one.
669
+ */
670
+ tools?: Record<string, unknown>;
671
+ prompt: string;
672
+ /** The directory this agent definition was discovered from. */
673
+ sourceDir?: string;
674
+ /**
675
+ * Whether this definition came from the PACKAGE'S OWN agents directory - the ones Super Pi ships -
676
+ * rather than from a directory the user pointed the app at.
677
+ *
678
+ * WHY IT IS DECIDED BY THE SERVER AND NOT BY THE CLIENT. The picker used to interleave the two
679
+ * kinds alphabetically, so the built-in agents - the ones with a colour dot - were scattered among
680
+ * the user's own. The client cannot work that out on its own: it is told where each definition came
681
+ * from, but "is this directory the package's own" is a question about the app's installation, and
682
+ * only the server knows where it is installed. So the server answers it here, at read time, and the
683
+ * client just orders by the answer.
684
+ *
685
+ * It describes the definition that WON, not the id: when a user's directory shadows a built-in
686
+ * agent of the same id, the user's file is the one that is listed, and it is the user's.
687
+ */
688
+ builtin?: boolean;
689
+ };
690
+ /**
691
+ * What the picker receives. The prompt body is deliberately NOT sent: it is a whole system prompt,
692
+ * the browser has no use for it, and state.json plus the agent catalog stay small.
693
+ */
694
+ export type AgentSummary = Omit<AgentDefinition, "prompt" | "toolFlags" | "tools"> & {
695
+ toolSummary: string;
696
+ sourceDir?: string;
697
+ };
698
+ export type PromptTemplateSummary = {
699
+ name: string;
700
+ description: string;
701
+ argumentHint?: string;
702
+ scope: "user" | "project";
703
+ };
704
+ export type PromptCatalog = {
705
+ source: "sdk" | "unavailable";
706
+ prompts: PromptTemplateSummary[];
707
+ workspaceId: string;
708
+ fetchedAt: string;
709
+ error?: string;
710
+ };
711
+ export type AgentCatalog = {
712
+ source: "directory" | "unavailable";
713
+ agents: AgentSummary[];
714
+ /** Files that exist but are not usable agents, so a typo is visible instead of silently absent. */
715
+ problems: {
716
+ file: string;
717
+ message: string;
718
+ }[];
719
+ directory: string;
720
+ /** All searched agent directories in priority order. */
721
+ directories?: string[];
722
+ fetchedAt: string;
723
+ error?: string;
724
+ };
725
+ /**
726
+ * Workspace-level DEFAULTS for conversations not yet created. Both fields are optional for the same
727
+ * reason Conversation's are: a state.json written before workspace settings existed has no such keys,
728
+ * and absent means "Pi's own default" with no migration step.
729
+ *
730
+ * These are copied INTO a conversation at creation time (store.createConversation) and never read
731
+ * afterwards. That copy is the whole "default vs override" semantics: the session picker's value is
732
+ * the conversation's own field, an existing conversation is therefore immune to later workspace
733
+ * edits, and deleting the workspace default cannot reach back into sessions already born.
734
+ */
735
+ /**
736
+ * `closedAt` marks a workspace that was REMOVED FROM THE SIDEBAR but is not gone: its conversations
737
+ * are still on disk and still belong to it. The removal is a soft unmount, exactly like a session's
738
+ * `archivedAt` - a state marker, never a deletion - and the marker is what lets the same physical
739
+ * directory be added again later and come back with its history instead of with an empty list.
740
+ */
741
+ export type Workspace = {
742
+ id: string;
743
+ name: string;
744
+ path: string;
745
+ updatedAt: string;
746
+ defaultModel?: ModelSelection;
747
+ defaultThinkingLevel?: string;
748
+ defaultAgentId?: string;
749
+ closedAt?: string;
750
+ worktreeOf?: string;
751
+ worktreeProjectPath?: string;
752
+ };
753
+ /**
754
+ * Usage accumulated across one sub-agent run. `turns` is the number of finished assistant messages,
755
+ * not a token total: it is what tells a human whether a sub-agent did one pass or twenty.
756
+ *
757
+ * Declared HERE rather than in `subagents.ts` because this is a persisted shape - it is copied into
758
+ * `state.json` and back out - and a type that lives next to the code that produced it cannot be
759
+ * checked by the one that consumes it.
760
+ */
761
+ export type SubagentUsage = {
762
+ input: number;
763
+ output: number;
764
+ cacheRead: number;
765
+ cacheWrite: number;
766
+ cost: number;
767
+ turns: number;
768
+ };
769
+ /** Current context occupancy, distinct from cumulative billed tokens; null means unknown after compaction. */
770
+ export type ConversationContextUsage = {
771
+ tokens: number | null;
772
+ contextWindow: number;
773
+ percent: number | null;
774
+ };
775
+ /**
776
+ * ONE TOOL CALL, as the card shows it, and the boundary that keeps a child's turn out of `state.json`.
777
+ *
778
+ * `detail` is a SHORT LABEL of what the call was aimed at - the file it read, the pattern it searched
779
+ * for, the command it ran - and it is the only part of the child's arguments Super Pi keeps. That is a
780
+ * deliberate line, not an oversight, and it is drawn in three places at once:
781
+ *
782
+ * 1. **It is derived, never copied.** `describeToolCall` reads named argument fields and renders ONE
783
+ * capped line; the argument object itself is dropped. A `read` whose result is a whole file still
784
+ * contributes nothing but its path.
785
+ * 2. **It is bounded.** 120 characters, whitespace collapsed, no newlines - so the label cannot grow
786
+ * into a transcript, and a `state.json` serialized on every broadcast stays small by construction
787
+ * rather than by hope.
788
+ * 3. **The RESULT never lands here at all.** `tool_execution_end` carries `result`, which for a `read`
789
+ * is the file's contents; only its `isError` and its `durationMs` are kept, because both are
790
+ * numbers rather than text. This is the guard `scripts/agent-vis-records.test.mjs` pins down.
791
+ *
792
+ * `status` is OPTIONAL rather than defaulted to `"ok"` for a reason that is now historical: when this
793
+ * type was declared, the protocol surface announced tools and never reported how they ended, so a
794
+ * default would have claimed an outcome nobody observed. Pi does send `tool_execution_end`, the
795
+ * supervisor consumes it, and a call that has not ended yet still has no `status` - which is exactly
796
+ * what makes an in-flight row distinguishable from a finished one.
797
+ *
798
+ * `durationMs` is Pi's own measurement off a monotonic clock, not this project's clock, and it is the
799
+ * one outcome number that is true for EVERY tool rather than only the shapes this code recognises.
800
+ */
801
+ export type SubagentToolCall = {
802
+ label: string;
803
+ output?: string;
804
+ outputTruncated?: boolean;
805
+ status?: "ok" | "error";
806
+ detail?: string;
807
+ durationMs?: number;
808
+ };
809
+ /**
810
+ * WHAT THE CHILD WAS DOING AT THE MOMENT THE BROWSER LAST HEARD FROM IT.
811
+ *
812
+ * A run that spends its whole life inside one long tool call emits no `text_delta`, so without this the
813
+ * card freezes mid-run and a frozen card is indistinguishable from a dead one. `kind` is a WORD rather
814
+ * than a colour, because "is it still working?" has to be answerable by someone who cannot see the
815
+ * green tint. `at` lets the card say how stale this is, which is the difference between "working" and
816
+ * "stopped answering without saying so".
817
+ *
818
+ * Optional on purpose, and cleared rather than left stale at the settle: on a finished run the last
819
+ * thing the child did is history, and a card that kept claiming to be 正在调用 read after the run
820
+ * ended would be lying.
821
+ */
822
+ export type SubagentActivity = {
823
+ kind: "thinking" | "tool";
824
+ label?: string;
825
+ at: string;
826
+ };
827
+ /**
828
+ * WHICH PHASE A RUN DIED IN, so a failure card answers 「卡在哪」 and not only 「错了」.
829
+ *
830
+ * `error` already says what went wrong and is the older, better field; this says where. A model that
831
+ * cannot open its output file and one that crashed two tool calls in are both 「失败」 without it, and
832
+ * those have completely different fixes. Five phases, because those are the five the supervisor can
833
+ * actually observe - it changes this value as the drain loop meets each record family, so it cannot
834
+ * claim a phase it never saw.
835
+ *
836
+ * Absent means "the failure was not observed while the run was in flight" - an orphan reconciled at the
837
+ * next startup, for instance, whose process was gone before anything could report a phase. Inventing
838
+ * one there would be the exact lie this type exists to prevent.
839
+ */
840
+ export type SubagentFailure = {
841
+ stage: "dispatch" | "prompt" | "turn" | "tool" | "settle";
842
+ };
843
+ /**
844
+ * `SubagentRun`'s lifecycle, which is NOT `RunStatus`: there is no "idle", because a run exists only
845
+ * between its dispatch and its settle. `stopped` is separate from `failed` for the same reason
846
+ * `RunStatus` keeps them apart - "the user pressed stop" and "the child broke" are different facts
847
+ * for whoever reads the record later, and collapsing them forces that decision back out of message
848
+ * matching. A fourth value is deliberately absent: a run cannot be cancelled while it has not started.
849
+ */
850
+ export type SubagentRunStatus = "running" | "completed" | "failed" | "stopped";
851
+ /**
852
+ * One sub-agent run, exactly as [docs/SUBAGENT-DESIGN.md](../../docs/SUBAGENT-DESIGN.md) §5 fixes it.
853
+ *
854
+ * THE RECORD, NEVER THE TRANSCRIPT. `state.json` is serialized on every broadcast and cloned into the
855
+ * browser on every snapshot, so a sub-agent's full conversation - arbitrarily long, and belonging to a
856
+ * different process with its own context window - must not go in here. What goes in is the LAST
857
+ * ASSISTANT MESSAGE (`output`), which is also what the parent model is told, and nothing else about the
858
+ * child's turn. Pi keeps the real transcript in its own `--session-dir`, and `sessionId` is the handle
859
+ * that gets it back (`switch_session`, or `export_html`): Super Pi records where the child's words are
860
+ * rather than copying them.
861
+ *
862
+ * `outputTruncated` exists because `output` may be cut: the 50 KB cap in §6 applies to the MODEL's copy
863
+ * only, since a human reading a sub-agent is debugging it and does not want it trimmed to fit somebody
864
+ * else's context window. So the browser gets the whole thing through `subagent.event` while the flag
865
+ * says the stored copy is less.
866
+ */
867
+ export type SubagentRun = {
868
+ /** `sub_<uuid>`. Also Pi's `--session-id`, which is why the two are one value today. */
869
+ id: string;
870
+ /** The conversation that dispatched this run, so its card can live under the right message. */
871
+ conversationId: string;
872
+ /** The `agents/*.md` file's base name - the `mode: subagent` definition that was run. */
873
+ agentId: string;
874
+ /** What the child was asked to do, as Super Pi sent it. The dispatcher's own text, not the child's reply. */
875
+ task: string;
876
+ /**
877
+ * Who decided to run this: a person pressed the dispatch button, or the primary agent called the
878
+ * `task` tool on its own. The two are indistinguishable on the record otherwise - same agent, same
879
+ * task, same card - so the browser would show a model's own decision as if a person had asked for it.
880
+ * Absent means `human`, which is what every record written before this field existed was.
881
+ */
882
+ dispatchedBy?: "human" | "model";
883
+ /**
884
+ * WHERE THIS RUN WAS ASKED FOR, as a position in the dispatching assistant message: the message id, and
885
+ * the index of the tool call inside its `toolCalls`.
886
+ *
887
+ * This exists because a card anchored to nothing is anchored to a CLOCK. `startedAt` is when the child
888
+ * was spawned, and the message that dispatched it goes on streaming for seconds afterwards, so sorting
889
+ * cards against messages by time dropped every card below every message still being written - which is
890
+ * why sub-agent cards appeared at the bottom of the transcript instead of at the call that asked for
891
+ * them. Ordering by call position fixes that in the only direction a reader means: later call, later
892
+ * card, regardless of which child finishes first.
893
+ *
894
+ * ABSENT IS NORMAL AND MEANS "no anchor", never "row zero": a person pressing 派子智能体 has no tool
895
+ * call, and neither does a record written before this field existed. Both render as they always did.
896
+ */
897
+ originMessageId?: string;
898
+ originCallRow?: number;
899
+ /** Authoritative dispatch ancestry, assigned by the server. */
900
+ parentRunId?: string;
901
+ depth: number;
902
+ loopId?: string;
903
+ /** Optional orchestration label; interpretation belongs to the workflow, not the dispatcher. */
904
+ role?: string;
905
+ status: SubagentRunStatus;
906
+ startedAt: string;
907
+ finishedAt?: string;
908
+ /** The last assistant message. Absent while running is only for a run that has produced none yet. */
909
+ output?: string;
910
+ partialOutput?: string;
911
+ /**
912
+ * Every tool the child started, oldest first, appended as the run streams. Same rule as `output`:
913
+ * short labels go here and to the card, the child's full turn stays in Pi's session directory.
914
+ *
915
+ * Optional on purpose. It was added to the design AFTER part 2 shipped, so a `state.json` written
916
+ * by an older build has no such key and an absent one reads as "this child used no tools", which is
917
+ * what a run with none genuinely means.
918
+ */
919
+ toolCalls?: SubagentToolCall[];
920
+ /** True when `output` was cut for the model's benefit; the browser still saw all of it. */
921
+ outputTruncated?: boolean;
922
+ usage?: SubagentUsage;
923
+ /**
924
+ * TRUE once this run's usage has been folded into the usage ledger of the conversation that
925
+ * dispatched it.
926
+ *
927
+ * IT IS THE FLAG THAT MAKES THE FOLD HAPPEN EXACTLY ONCE. The child's money is added to the
928
+ * parent conversation's `usage` when the run settles, and a project budget reads that ledger -
929
+ * so a run whose usage were folded twice would be billed twice, and a run whose usage were never
930
+ * folded would be free. The flag says which side of that line this run is on, and it is written
931
+ * in the SAME store write as the ledger entry, so there is no window in which the two disagree.
932
+ *
933
+ * ABSENT means "not accounted for yet", which is what a `state.json` written before this feature
934
+ * existed says about every run in it - and what the startup sweep repairs, once, on the next boot.
935
+ */
936
+ usageAccounted?: boolean;
937
+ error?: string;
938
+ /**
939
+ * How long the run took, measured by THIS server between writing the `running` row and settling it.
940
+ *
941
+ * Added because of a measurement, not a preference: a real sub-agent reading three files finished in
942
+ * 2.5 seconds, so a user glancing at the transcript afterwards could not tell whether the card had
943
+ * ever been anything but 已完成. A run that leaves a DURATION behind turns "I never saw it run" into
944
+ * "it ran for 2.5s", which is a fact, and it is the fact that makes the invisible run observable
945
+ * after the fact rather than only during a window nobody was looking at.
946
+ *
947
+ * Written at the settle only. While the card is live the elapsed time is the browser's own arithmetic
948
+ * on `startedAt`, so a client clock that disagrees with this one cannot change what was recorded.
949
+ */
950
+ durationMs?: number;
951
+ /** What the child was doing last. Live only: absent once the run has settled. */
952
+ activity?: SubagentActivity;
953
+ /** Which phase it died in. Absent on a run that finished normally, and on an unreconciled orphan. */
954
+ failure?: SubagentFailure;
955
+ /** Pi's own session id for the child. Its transcript lives there and is never parsed by Super Pi. */
956
+ sessionId: string;
957
+ };
958
+ /**
959
+ * What may change on a run that has already been recorded.
960
+ *
961
+ * A named list rather than `Partial<SubagentRun>` because the fields a run must NEVER change are the
962
+ * point: `id` is the key startup reconciliation looks orphans up by, and `conversationId`/`agentId`/
963
+ * `task`/`startedAt` are the facts the run was DISPATCHED with. A patch that could rewrite any of them
964
+ * could produce a record whose id matches nothing that ran - unreconcilable, and unattributable.
965
+ * `sessionId` is the one identity field allowed to move, and only because a run's id and Pi's session id
966
+ * happen to coincide today rather than by definition.
967
+ */
968
+ export type SubagentRunUpdate = Partial<Pick<SubagentRun, "status" | "output" | "partialOutput" | "outputTruncated" | "toolCalls" | "usage" | "error" | "finishedAt" | "sessionId" | "durationMs" | "activity" | "failure">>;
969
+ export type BackgroundTaskSummary = BackgroundTaskDetails & {
970
+ conversationId: string;
971
+ title: string;
972
+ agentId: string;
973
+ startedAt: string;
974
+ finishedAt?: string;
975
+ resultBlockId: string;
976
+ /** The same call-position anchor a `SubagentRun` carries, and for the same reason: a background command
977
+ * asked for inside a turn belongs at that call, not wherever its output happened to land. Absent when
978
+ * the task was not started by a tool call. */
979
+ originMessageId?: string;
980
+ originCallRow?: number;
981
+ };
982
+ /**
983
+ * Orchestrated plans, optional for the same reason `todos` is: a `state.json` written before this
984
+ * feature existed has no `workflows` key, and must read correctly rather than looking like an install
985
+ * that has considered a plan and found none. Absence and an empty list mean the same thing to every
986
+ * reader, so the store deletes the key rather than storing `[]`.
987
+ *
988
+ * The workflow's own types live in `workflow.ts` next to the rules that build them. This is a type-only
989
+ * import and is erased at compile time, so it does not close a runtime cycle with the rules that
990
+ * construct them - the same relationship `SubagentRun` already has with `subagent-runs.ts`.
991
+ */
992
+ /**
993
+ * `defaultModel` is the app-wide fallback model: the `provider/modelId` pair a NEW conversation gets
994
+ * when its workspace has no default of its own. It sits BELOW the workspace default and ABOVE Pi's own
995
+ * default, so the precedence at birth is workspace > app > Pi.
996
+ *
997
+ * It is a PAIR, never a provider and a model apart, for the same reason `ModelSelection` is a pair:
998
+ * Pi's `set_model` needs both halves, and half a selection is a selection Pi refuses. There is no
999
+ * separate "default provider" anywhere in this state: a provider is not a thing this app can be
1000
+ * configured with, it is only the first half of a model id.
1001
+ */
1002
+ export type TerminalShell = {
1003
+ file: string;
1004
+ args: string[];
1005
+ };
1006
+ export type ProjectStatus = "planning" | "awaiting_start" | "active" | "blocked" | "awaiting_approval" | "awaiting_review" | "failed" | "cancelled";
1007
+ /**
1008
+ * THE STATES A TASK CAN BE IN.
1009
+ *
1010
+ * `interrupted` is the one that says the EXECUTION IS GONE: the session that was supposed to be
1011
+ * running this task is no longer there - it failed, it was stopped, or its record disappeared with
1012
+ * the process that held it. It is NOT `failed` (that is the executor reporting its own failure, in
1013
+ * its own words, with its own evidence) and it is NOT `ready` (a ready task is one that has never
1014
+ * been started, or that was sent back for rework and is waiting to be picked up again).
1015
+ *
1016
+ * A task in `interrupted` cannot advance on its own: nobody will ever report back on it. That is
1017
+ * exactly why it needs its own state - the Boss has to be able to see it AND be able to send it
1018
+ * back out again, and neither "failed" nor "ready" says both.
1019
+ */
1020
+ export type ProjectTaskStatus = "pending" | "ready" | "in_progress" | "interrupted" | "blocked" | "awaiting_review" | "completed" | "failed" | "cancelled";
1021
+ export type ProjectRisk = "low" | "medium" | "high";
1022
+ /**
1023
+ * HOW A PROJECT RUNS.
1024
+ *
1025
+ * "standard" is the shape the project flow has always had: the leader dispatches worker sessions
1026
+ * and every delivery is checked by an independent reviewer session. "lightweight" is the small
1027
+ * project's shape: the leader session does the work itself, and a delivery is accepted on the
1028
+ * executor's own evidence. Every guardrail is the same in both - what a lightweight project gives
1029
+ * up is the number of sessions, never the guardrails.
1030
+ */
1031
+ export type ProjectMode = "standard" | "lightweight";
1032
+ export type SessionProfile = {
1033
+ /** Employee agent file id under agents directory (primary agent name). */
1034
+ agentId?: string;
1035
+ /** Working directory relative to workspace root. */
1036
+ cwd?: string;
1037
+ /** Explicit model override. */
1038
+ model?: {
1039
+ provider: string;
1040
+ modelId: string;
1041
+ };
1042
+ /** Thinking level override. */
1043
+ thinkingLevel?: string;
1044
+ /** Silence watchdog timeout in seconds. */
1045
+ watchdogTimeoutSeconds?: number;
1046
+ };
1047
+ export type ProjectTask = {
1048
+ activity?: import("../shared/project-presentation.js").ProjectActivity;
1049
+ handoffNote?: string;
1050
+ ownedPaths?: string[];
1051
+ readOnly?: boolean;
1052
+ handoff?: import("../shared/team-context.js").TeamHandoff;
1053
+ parentTaskId?: string;
1054
+ role?: "leader" | "executor";
1055
+ id: string;
1056
+ projectId: string;
1057
+ title: string;
1058
+ objective: string;
1059
+ status: ProjectTaskStatus;
1060
+ ownerConversationId?: string;
1061
+ accountableConversationId?: string;
1062
+ reviewerConversationId?: string;
1063
+ executorProfile?: SessionProfile;
1064
+ reviewerProfile?: SessionProfile;
1065
+ effectiveExecutorProfile?: SessionProfile;
1066
+ effectiveReviewerProfile?: SessionProfile;
1067
+ dependencies: string[];
1068
+ deliverables: string[];
1069
+ acceptanceCriteria: string[];
1070
+ priority: "low" | "medium" | "high" | "urgent";
1071
+ dueAt?: string;
1072
+ blockedReason?: string;
1073
+ blockedReportedByConversationId?: string;
1074
+ /** WHY THIS TASK IS INTERRUPTED, in one sentence, for the reader. It says what happened to the
1075
+ * execution session - the fact that makes the task's own state impossible to keep. */
1076
+ interruptedReason?: string;
1077
+ /** WHEN THIS TASK WAS LAST DISPATCHED. It is what tells a session that died BEFORE the dispatch
1078
+ * from one that died AFTER it: only the second one interrupted the task. Absent on a task that
1079
+ * was registered before dispatch times were written down. */
1080
+ dispatchedAt?: string;
1081
+ output?: string;
1082
+ evidenceRefs?: string[];
1083
+ /** The acceptance of this task. `lightweight: true` means the executor accepted its own
1084
+ * delivery: there was no independent reviewer session behind it. */
1085
+ review?: {
1086
+ verdict: "accepted" | "changes_requested";
1087
+ summary: string;
1088
+ evidenceRefs: string[];
1089
+ reviewerConversationId?: string;
1090
+ createdAt: string;
1091
+ lightweight?: boolean;
1092
+ };
1093
+ createdAt: string;
1094
+ updatedAt: string;
1095
+ };
1096
+ export type ProjectReport = {
1097
+ id: string;
1098
+ projectId: string;
1099
+ taskId?: string;
1100
+ acceptedTaskIds?: string[];
1101
+ authorConversationId?: string;
1102
+ kind: "progress" | "blocked" | "delivery" | "decision_request" | "review";
1103
+ progress: string;
1104
+ summary?: string;
1105
+ variance?: string;
1106
+ nextStep?: string;
1107
+ risks?: string[];
1108
+ decisionNeeded?: string;
1109
+ evidenceRefs?: string[];
1110
+ createdAt: string;
1111
+ };
1112
+ export type ProjectEscalation = {
1113
+ id: string;
1114
+ projectId: string;
1115
+ taskId?: string;
1116
+ reason: string; /** THE QUESTION, IN ONE SENTENCE. What the Boss has to decide - as opposed to `reason`,
1117
+ * which is the case for it. The reader decides in a glance, and reads the case only if the
1118
+ * question is not obvious; an escalation without a title falls back to the reason. */
1119
+ title?: string;
1120
+ severity: ProjectRisk;
1121
+ status: "open" | "resolved" | "dismissed" | "returned";
1122
+ requestedByConversationId?: string;
1123
+ decision?: string;
1124
+ createdAt: string;
1125
+ resolvedAt?: string;
1126
+ audience?: "supervisor" | "boss";
1127
+ targetConversationId?: string;
1128
+ resolvedByConversationId?: string;
1129
+ };
1130
+ export type ProjectEvent = {
1131
+ id: string;
1132
+ kind: string;
1133
+ summary: string;
1134
+ taskId?: string;
1135
+ actorConversationId?: string;
1136
+ createdAt: string;
1137
+ };
1138
+ export type Project = {
1139
+ activity?: import("../shared/project-presentation.js").ProjectActivity;
1140
+ sharedContext?: import("../shared/team-context.js").TeamContextEntry[];
1141
+ contextRevision?: number;
1142
+ id: string;
1143
+ workspaceId: string;
1144
+ title: string;
1145
+ objective: string;
1146
+ /** HOW THE PROJECT RUNS. Absent means "standard": the leader dispatches worker sessions and
1147
+ * every delivery is checked by an independent reviewer session. "lightweight" is the small
1148
+ * project's shape: the leader session does the work itself, and a delivery is accepted on the
1149
+ * executor's own evidence. Every guardrail is the same in both modes. */
1150
+ mode?: ProjectMode;
1151
+ deliverables: string[];
1152
+ acceptanceCriteria: string[];
1153
+ constraints: string[];
1154
+ risk: ProjectRisk;
1155
+ status: ProjectStatus;
1156
+ ownerConversationId?: string;
1157
+ /** IS THE OWNER SESSION IN THE ARCHIVE? A project whose leader was archived has nobody left to
1158
+ * run it, so it is history with its records intact - not work in progress. The server computes
1159
+ * it (it is the one that knows what is archived) and the client re-applies the same rule, so
1160
+ * both ends agree on which view a project belongs to. */
1161
+ ownerArchived?: boolean;
1162
+ /** The session that created the project - the Boss's own conversation, which may register the
1163
+ * top-level tasks and is the one the project answers to. */
1164
+ initiatorConversationId?: string;
1165
+ defaultLeaderProfile?: SessionProfile;
1166
+ defaultExecutorProfile?: SessionProfile;
1167
+ defaultReviewerProfile?: SessionProfile;
1168
+ events?: ProjectEvent[];
1169
+ /**
1170
+ * The project's live sessions, with the tree skeleton attached.
1171
+ *
1172
+ * `parentConversationId` is what lets the client draw a TREE rather than a flat list: a
1173
+ * session whose parent is not in this collection is a ROOT of the tree (the project leader,
1174
+ * and any orphan left behind by an older layout). Without it the panel can only show a row
1175
+ * per session, and the hierarchy - who reported to whom - stays invisible.
1176
+ */
1177
+ /**
1178
+ * The project's live sessions, with the tree skeleton and the memory scope attached.
1179
+ *
1180
+ * `parentConversationId` is what lets the client draw a TREE rather than a flat list: a
1181
+ * session whose parent is not in this collection is a ROOT of the tree (the project leader,
1182
+ * and any orphan left behind by an older layout). Without it the panel can only show a row
1183
+ * per session, and the hierarchy - who reported to whom - stays invisible.
1184
+ *
1185
+ * `memoryScope` says whose memory a session works from: "project" for the sessions that live
1186
+ * in the PROJECT'S OWN memory tree (the leader, and every worker that inherited it), "shared"
1187
+ * for a session that still reads the initiator's chat memory. The panel shows it as a small
1188
+ * mark on every agent, because a reader who cannot tell the two apart cannot tell what a
1189
+ * session remembers.
1190
+ */
1191
+ resources?: {
1192
+ tokens: number;
1193
+ usageKnown: boolean;
1194
+ activeWorkers: number;
1195
+ ownerCwd?: string;
1196
+ memoryTreeId?: string;
1197
+ usage?: {
1198
+ input: number;
1199
+ output: number;
1200
+ cacheRead: number;
1201
+ cacheWrite: number;
1202
+ };
1203
+ rawTokens?: number;
1204
+ sessions: {
1205
+ id: string;
1206
+ title: string;
1207
+ role: string;
1208
+ status: RunStatus;
1209
+ displayStatus?: string;
1210
+ displayWord?: string;
1211
+ reportingState?: string | null;
1212
+ hasOpenEscalation?: boolean;
1213
+ reportedToParentAt?: string;
1214
+ tokens: number;
1215
+ contextPercent?: number | null;
1216
+ parentConversationId?: string;
1217
+ memoryTreeId?: string;
1218
+ memoryScope?: "project" | "shared";
1219
+ cwd?: string;
1220
+ }[];
1221
+ };
1222
+ tasks: ProjectTask[];
1223
+ reports: ProjectReport[];
1224
+ escalations: ProjectEscalation[];
1225
+ createdAt: string;
1226
+ updatedAt: string;
1227
+ closedAt?: string;
1228
+ };
1229
+ export type ProjectSummary = {
1230
+ activity?: import("../shared/project-presentation.js").ProjectActivity;
1231
+ id: string;
1232
+ name: string;
1233
+ status: string;
1234
+ mode: "standard" | "lightweight";
1235
+ headline: string;
1236
+ /** `interrupted` counts the tasks whose execution session is gone: they are not running, and
1237
+ * they are not done either - they are waiting to be sent out again. */
1238
+ tasks: {
1239
+ total: number;
1240
+ completed: number;
1241
+ inProgress: number;
1242
+ blocked: number;
1243
+ interrupted?: number;
1244
+ };
1245
+ activeWorkers: number;
1246
+ tokens: number;
1247
+ updatedAt: string;
1248
+ };
1249
+ export type AppState = {
1250
+ extensionUi?: {
1251
+ conversationId: string;
1252
+ request: ExtensionUiRequest;
1253
+ }[];
1254
+ stoppingConversationIds?: string[];
1255
+ sendReceipts?: true;
1256
+ modelFilterRules?: ModelFilterRule[];
1257
+ defaultModel?: ModelSelection;
1258
+ terminalShell?: TerminalShell;
1259
+ workspaces: Workspace[];
1260
+ conversations: Conversation[];
1261
+ subagentRuns: SubagentRun[];
1262
+ backgroundTasks: BackgroundTaskSummary[];
1263
+ todosByConversation?: Record<string, TodoItem[]>;
1264
+ workflows?: WorkflowRun[];
1265
+ scheduledTasks?: ScheduledTask[];
1266
+ projects?: Project[];
1267
+ customAgentDirs?: string[]; /**
1268
+ * Which conversations the reader has collapsed in the sidebar's session tree, by conversation id.
1269
+ * Server-side so the tree looks the same after a restart and on another machine - the sidebar is a
1270
+ * view of the PRODUCT's state, not of one browser's session. Absent (older state.json) means
1271
+ * "nothing collapsed", which is the correct reading of a preference that did not exist yet.
1272
+ */
1273
+ collapsedConversationIds?: string[];
1274
+ /**
1275
+ * WHICH CHILD SESSIONS THE READER HAS UNLOCKED, by conversation id.
1276
+ *
1277
+ * A child session's composer is locked by default (the reporting line only runs upwards, so the
1278
+ * reader does not talk to a child session directly), and the reader may open ONE of them when
1279
+ * there is a real reason to. The server owns that state: it is the server that refuses the
1280
+ * message, so it has to be the server that knows whether the door is open - otherwise the
1281
+ * browser and the server would be two authorities for one fact.
1282
+ *
1283
+ * Absent (an older state.json) means "nothing unlocked", which is the correct reading of a
1284
+ * decision nobody has made yet.
1285
+ */
1286
+ unlockedChildConversationIds?: string[];
1287
+ warmSessions?: Array<{
1288
+ id: string;
1289
+ title: string;
1290
+ workspaceId: string;
1291
+ cwd?: string;
1292
+ savedAt: string;
1293
+ }>;
1294
+ /**
1295
+ * HOW MANY DECISIONS THE READER STILL OWES ON EACH SESSION, by conversation id.
1296
+ *
1297
+ * The projects themselves are not broadcast (`clientState` drops them), but the archive
1298
+ * confirmation needs to know: **how many decisions does archiving this tree throw away**.
1299
+ * The server counts them - the predicate lives in `src/shared/archive-decisions.ts` and both
1300
+ * ends call it - and the client only adds up the tree before writing it into that one
1301
+ * confirmation box.
1302
+ *
1303
+ * The key is the **OWNER SESSION**: the pending decisions on a project are counted on the
1304
+ * session that leads it, because that session is the project's leader. Without this number the
1305
+ * client could only say 「something might be thrown away」 instead of 「there are 3 left」.
1306
+ */
1307
+ pendingUserDecisionsByConversation?: Record<string, number>;
1308
+ /**
1309
+ * THE CLOCK THIS SERVER SCHEDULES BY. A scheduled task's 「每天 09:00」 is the SERVER's wall clock,
1310
+ * and the panel has to say so, because browser rendering 「下次」 may be on a different clock
1311
+ * entirely. Without this the two lines in one row quietly mean two different things.
1312
+ */
1313
+ serverTimeZone?: string;
1314
+ };
1315
+ export type TodoItem = {
1316
+ id?: string;
1317
+ content: string;
1318
+ status: "pending" | "in_progress" | "completed";
1319
+ priority?: "high" | "medium" | "low";
1320
+ };
1321
+ /** Summary of an orchestrated sibling session, returned by orchestrator queries. */
1322
+ export type OrchestratorSessionSummary = {
1323
+ conversationId: string;
1324
+ workspaceId: string;
1325
+ title: string;
1326
+ status: RunStatus;
1327
+ origin: "user" | "orchestrator";
1328
+ parentConversationId?: string;
1329
+ task?: string;
1330
+ messageCount: number;
1331
+ turnCount: number;
1332
+ lastAssistantSnippet?: string;
1333
+ lastUserSnippet?: string;
1334
+ hasPendingQuestion: boolean;
1335
+ activeTool?: {
1336
+ label: string;
1337
+ detail?: string;
1338
+ };
1339
+ error?: string;
1340
+ updatedAt: string;
1341
+ createdAt?: number;
1342
+ lastProgress?: string;
1343
+ output?: string;
1344
+ outputPath?: string;
1345
+ outputTruncated?: boolean;
1346
+ };
1347
+ /**
1348
+ * What Pi reports about ITS OWN queue, forwarded to the browser as it arrives.
1349
+ *
1350
+ * `steering` and `followUp` are Pi's in-memory arrays as of this event (`agent-session.ts:204-208`).
1351
+ * They are NOT what the user sees: the authoritative list is the trailing `delivery`-bearing messages
1352
+ * of the conversation itself (`MessageDelivery`), and this is Pi's own view of the at most one steer
1353
+ * that is currently in flight inside the child process. It is forwarded because it is the only signal
1354
+ * that proves a steer was really picked up, and because a `followUp` array that is ever non-empty means
1355
+ * something outside this server sent a `follow_up` - worth being able to see rather than infer.
1356
+ *
1357
+ * It no longer decides anything. A delivery used to be inferred from a DROP in `steering.length` and
1358
+ * applied by DELETING the oldest `sending` row, which is how a steered message could reach the model
1359
+ * and never reach the transcript. Delivery is now announced directly, by the `message_start` Pi emits
1360
+ * when it hands the text to the agent loop, and applied by moving a state on a message that was already
1361
+ * on screen the whole time.
1362
+ */
1363
+ export type PiQueueSnapshot = {
1364
+ steering: string[];
1365
+ followUp: string[];
1366
+ };
1367
+ /**
1368
+ * The nine methods Pi's `RpcExtensionUIRequest` union defines (rpc-types.ts:252-287), split by whether
1369
+ * Pi waits for a reply. `blocking` is the only field the transport needs in order to decide, and it
1370
+ * is derived here rather than at each call site so the two halves can never drift apart.
1371
+ */
1372
+ export declare const EXTENSION_UI_METHODS: readonly ["select", "confirm", "input", "editor", "notify", "setStatus", "setWidget", "setTitle", "set_editor_text"];
1373
+ export type ExtensionUiMethod = (typeof EXTENSION_UI_METHODS)[number];
1374
+ /** Pi registers exactly these four in `pendingExtensionRequests`; the other five are fire-and-forget. */
1375
+ export declare const BLOCKING_UI_METHODS: ReadonlySet<string>;
1376
+ export type ExtensionUiNotifyType = "info" | "warning" | "error";
1377
+ export type ExtensionUiPlacement = "aboveEditor" | "belowEditor";
1378
+ /** One normalized `extension_ui_request`. The method-specific fields are only present for methods that send them. */
1379
+ export type ExtensionUiRequest = {
1380
+ deadlineAt?: number;
1381
+ requestId: string;
1382
+ method: ExtensionUiMethod;
1383
+ /** True when Pi is blocked until the host answers. False means "display it, never ask the user to reply". */
1384
+ blocking: boolean;
1385
+ /** Pi omits `title` on notify/setStatus/setWidget/set_editor_text, so this is "" for those. */
1386
+ title: string;
1387
+ options?: string[];
1388
+ /** confirm body, and the notify body. */
1389
+ message?: string;
1390
+ placeholder?: string;
1391
+ prefill?: string;
1392
+ /** Pi's own deadline in ms. `editor` never has one, which is why an unanswered editor waits forever. */
1393
+ timeoutMs?: number;
1394
+ notifyType?: ExtensionUiNotifyType;
1395
+ statusKey?: string;
1396
+ statusText?: string;
1397
+ widgetKey?: string;
1398
+ widgetLines?: string[];
1399
+ widgetPlacement?: ExtensionUiPlacement;
1400
+ text?: string;
1401
+ };
1402
+ export type ExtensionUiCloseReason = "answered" | "cancelled" | "timeout" | "aborted" | "expired";
1403
+ /** The answer a human gave. `cancelled` is Pi's third response shape: no answer was collected. */
1404
+ export type ExtensionUiAnswer = {
1405
+ value?: string;
1406
+ confirmed?: boolean;
1407
+ cancelled?: true;
1408
+ };
1409
+ export type MessageDeliveryMode = "queue" | "steer";
1410
+ export type ClientCommand = ClientCommandBody & {
1411
+ operationRequestId?: string;
1412
+ };
1413
+ export type ClientCommandBody =
1414
+ /**
1415
+ * THE ANSWER TO A `question` CALL, ADDRESSED BY THE CALL'S ROW.
1416
+ *
1417
+ * It used to name a `questionId` on a block hung off the message. It now names `callIndex` - the same
1418
+ * index every other tool update uses - because the question IS that call, and the row being rendered is
1419
+ * the only place the browser can learn the index from. Answers pair to questions by `id`, not position,
1420
+ * so a person answering the second of two is not recorded as answering the first.
1421
+ */
1422
+ {
1423
+ type: "question.answer";
1424
+ conversationId: string;
1425
+ messageId: string;
1426
+ callIndex: number;
1427
+ answers?: QuestionAnswer[];
1428
+ cancelled?: boolean;
1429
+ } | TerminalCommand | {
1430
+ type: "terminal.shell.set";
1431
+ command: string | null;
1432
+ } | {
1433
+ type: "model.rules.set";
1434
+ rules: ModelFilterRule[];
1435
+ }
1436
+ /**
1437
+ * Adds a provider, or adds a model to one, or updates one.
1438
+ *
1439
+ * The key is OPTIONAL and its absence means "keep the stored one": the key is never shown again
1440
+ * once it is saved, so an empty field is the normal state of the form for a provider that already
1441
+ * has one. `clearKey` is how a person asks for it to be removed.
1442
+ */
1443
+ | {
1444
+ type: "providers.set";
1445
+ provider: {
1446
+ id: string;
1447
+ name?: string;
1448
+ baseUrl: string;
1449
+ api: string;
1450
+ apiKey?: string;
1451
+ clearKey?: boolean;
1452
+ models: {
1453
+ id: string;
1454
+ name?: string;
1455
+ reasoning?: boolean;
1456
+ imageInput?: boolean;
1457
+ contextWindow?: number;
1458
+ maxTokens?: number;
1459
+ supportsDeveloperRole?: boolean;
1460
+ supportsReasoningEffort?: boolean;
1461
+ /**
1462
+ * The thinking levels to write for this model.
1463
+ *
1464
+ * THE SAME THREE STATES THE FORM MEANS BY THEM: absent means "the form knows nothing", so
1465
+ * the saved levels stay; `null` means "this model has no levels", so the saved ones go; a
1466
+ * map means "these are the levels", and every one of Pi's seven is named.
1467
+ */
1468
+ thinkingLevelMap?: ThinkingLevelMap | null;
1469
+ }[];
1470
+ };
1471
+ }
1472
+ /** Removes a provider Super Pi manages. One it does not manage is refused. */
1473
+ | {
1474
+ type: "providers.remove";
1475
+ providerId: string;
1476
+ }
1477
+ /**
1478
+ * Turns a provider OFF: takes its `models.json` entry and its `auth.json` credential out of Pi's
1479
+ * configuration, remembering both so `providers.enable` can put them back.
1480
+ *
1481
+ * THE ONLY THING PI HONOURS. A provider's models are offered exactly when its auth is configured
1482
+ * (`ModelRuntime.getAvailable()` filters on that), and a built-in provider such as `kimi-coding`
1483
+ * has no `models.json` entry to remove at all - so the credential is the lever for every kind of
1484
+ * provider, and taking it out is what "off" means for Pi itself, not just for this app.
1485
+ */
1486
+ | {
1487
+ type: "providers.disable";
1488
+ providerId: string;
1489
+ }
1490
+ /** Turns a previously disabled provider back on, restoring exactly what `disable` removed. */
1491
+ | {
1492
+ type: "providers.enable";
1493
+ providerId: string;
1494
+ }
1495
+ /**
1496
+ * Removes ONE model from a provider, leaving the provider and its other models alone.
1497
+ *
1498
+ * Separate from `providers.remove` because a provider is a GROUP of models sharing one address
1499
+ * and one key: taking one model out must not cost the others their credential.
1500
+ */
1501
+ | {
1502
+ type: "providers.removeModel";
1503
+ providerId: string;
1504
+ modelId: string;
1505
+ }
1506
+ /** Asks for the providers Super Pi manages. The answer carries no key. */
1507
+ /**
1508
+ * Repairs Pi's model configuration: the empty fields Pi's schema refuses are dropped from
1509
+ * `models.json`, and nothing else in the file is touched.
1510
+ *
1511
+ * Pi validates the whole file, so one refused entry takes every custom provider out of every
1512
+ * picker. This is the way back.
1513
+ */
1514
+ | {
1515
+ type: "providers.repair";
1516
+ } | {
1517
+ type: "providers.fetch";
1518
+ }
1519
+ /**
1520
+ * Stops and removes an active background task (spawned process or background subagent).
1521
+ *
1522
+ * If the task has a live pty child process, it is killed. If it originated from a tool call in
1523
+ * a conversation, that call is marked as stopped/failed in the transcript so the user sees a
1524
+ * settled outcome instead of a permanent spinner. The task is then removed from `backgroundTasks`.
1525
+ */
1526
+ | {
1527
+ type: "backgroundTask.stop";
1528
+ taskId: string;
1529
+ }
1530
+ /**
1531
+ * Sets the app-wide default model. `null` clears it back to "Pi's own default" - the same
1532
+ * "absence, not a frozen copy" convention the workspace defaults use, so removing the default
1533
+ * really removes it instead of pinning whatever Pi's default happened to be when it was saved.
1534
+ */
1535
+ | {
1536
+ type: "settings.defaultModel";
1537
+ model: {
1538
+ provider: string;
1539
+ modelId: string;
1540
+ } | null;
1541
+ }
1542
+ /**
1543
+ * Asks for the model catalog WITHOUT a conversation, so the settings window can list every model Pi
1544
+ * offers. A separate command from `catalog.fetch` because that one is scoped to a conversation and
1545
+ * filtered by that workspace's model rules: reusing it here would either hide the models the panel
1546
+ * must offer, or - worse - leak them into the composer picker, which is filtered for a reason.
1547
+ */
1548
+ | {
1549
+ type: "catalog.fetchAll";
1550
+ } | {
1551
+ type: "workspace.create";
1552
+ name: string;
1553
+ path?: string;
1554
+ } | {
1555
+ type: "workspace.rename";
1556
+ workspaceId: string;
1557
+ name: string;
1558
+ } | {
1559
+ type: "workspace.delete";
1560
+ workspaceId: string;
1561
+ }
1562
+ /**
1563
+ * Replaces BOTH workspace defaults in one shot, because the settings dialog saves them together.
1564
+ * `null` clears a default back to "Pi's own" - a default the user removed must not persist as a
1565
+ * value, or a new conversation would keep inheriting a choice the dialog no longer shows.
1566
+ */
1567
+ | {
1568
+ type: "workspace.settings";
1569
+ workspaceId: string;
1570
+ model: {
1571
+ provider: string;
1572
+ modelId: string;
1573
+ } | null;
1574
+ thinkingLevel: string | null;
1575
+ agentId?: string | null;
1576
+ } | {
1577
+ type: "workspaces.settings.bulk";
1578
+ model: {
1579
+ provider: string;
1580
+ modelId: string;
1581
+ } | null;
1582
+ thinkingLevel: string | null;
1583
+ } | {
1584
+ type: "conversation.create";
1585
+ workspaceId: string;
1586
+ cwd?: string;
1587
+ } | {
1588
+ type: "conversation.select";
1589
+ conversationId: string;
1590
+ } | {
1591
+ type: "conversation.archive";
1592
+ conversationId: string;
1593
+ } | {
1594
+ type: "conversation.warm.save";
1595
+ conversationId: string;
1596
+ title: string;
1597
+ } | {
1598
+ type: "conversation.warm.delete";
1599
+ conversationId: string;
1600
+ } | {
1601
+ type: "conversation.unarchive";
1602
+ conversationId: string;
1603
+ }
1604
+ /**
1605
+ * Collapses or expands one conversation's whole subtree in the sidebar's session tree. The state
1606
+ * lives SERVER-SIDE (`AppState.collapsedConversationIds`), not in the browser: the tree must look
1607
+ * the same after a restart and on another machine, and a bare WS client must not be able to leave
1608
+ * the server's truth and the screen's truth disagreeing about a preference the product owns.
1609
+ */
1610
+ | {
1611
+ type: "conversation.collapse";
1612
+ conversationId: string;
1613
+ collapsed: boolean;
1614
+ }
1615
+ /**
1616
+ * OPENS (OR RE-CLOSES) ONE CHILD SESSION'S COMPOSER.
1617
+ *
1618
+ * The state lives SERVER-SIDE (`AppState.unlockedChildConversationIds`), not in the browser: the
1619
+ * server is what refuses the message, so the server is what has to know whether the door is
1620
+ * open. A browser that kept the only copy would be a browser that could unlock a session the
1621
+ * server still refuses - and the reader would be told 「发送失败」 for a message that was never
1622
+ * allowed to be sent in the first place.
1623
+ *
1624
+ * `unlocked: false` is the way back. A lock that could only be opened would not be a lock.
1625
+ */
1626
+ | {
1627
+ type: "conversation.childLock";
1628
+ conversationId: string;
1629
+ unlocked: boolean;
1630
+ } | {
1631
+ type: "conversation.rename";
1632
+ conversationId: string;
1633
+ name: string;
1634
+ }
1635
+ /**
1636
+ * ASK THE MODEL TO NAME THIS CONVERSATION. Separate from conversation.rename on purpose: rename moves a
1637
+ * name a person chose, this one is a request whose ANSWER comes back later and may fail - so it cannot
1638
+ * ride the optimistic command path, which resolves the moment the socket accepts the write and has no
1639
+ * room for an answer that arrives ten seconds later. The result arrives as conversation.autoRename.result.
1640
+ */
1641
+ | {
1642
+ type: "conversation.autoRename";
1643
+ conversationId: string;
1644
+ }
1645
+ /**
1646
+ * FORKS A WHOLE SESSION: a second conversation that starts from this one's complete history, in Pi's own
1647
+ * transcript as well as in `state.json`.
1648
+ *
1649
+ * WHOLE SESSION, NOT A MESSAGE. Pi's own `fork` takes an `entryId` and branches from one message
1650
+ * (`rpc-types.ts:62-66`, `agent-session-runtime.ts:279-287`); this takes no message id because the thing
1651
+ * being asked for is a copy of the conversation as it stands, to be taken in another direction.
1652
+ *
1653
+ * WHY PI'S OWN `fork` IS NOT USED, which is the whole reason this command exists rather than a passthrough.
1654
+ * Three separate reasons, and the first is not negotiable:
1655
+ *
1656
+ * 1. It TEARS THE RUNTIME DOWN AND SWITCHES TO THE NEW SESSION (`agent-session-runtime.ts:299-307`:
1657
+ * `teardownCurrent("fork", ...)` then `apply(createRuntime(...))`). Super Pi's "runtime" is one short-lived
1658
+ * Pi per turn (`runtime.ts:840` spawns, `:429-435` kills), so there is no runtime to hand across; there is
1659
+ * only a turn. Anything reached for here would have to be undone immediately.
1660
+ * 2. It requires a long-lived child to fork FROM, which Super Pi deliberately does not have. Every piece of
1661
+ * Super Pi's session state is a durable file, and the process that used it is gone by the next turn.
1662
+ * 3. Even given a live child, its result is only reachable through that child's runtime - the new session's
1663
+ * file is a side effect of the swap, not something a caller receives. Super Pi needs the file written
1664
+ * BEFORE the conversation exists, and needs to be told if it failed.
1665
+ *
1666
+ * So the fork is performed the same way a revert is: by asking Pi which file it uses for this id
1667
+ * (`get_state.sessionFile`), checking that file belongs to the conversation being forked, and then writing a
1668
+ * second file. See `runtime.ts` `fork()`.
1669
+ */
1670
+ | {
1671
+ type: "conversation.fork";
1672
+ conversationId: string;
1673
+ }
1674
+ /** Chooses the model for a conversation. Both fields are required because Pi's set_model needs both. */
1675
+ | {
1676
+ type: "conversation.model";
1677
+ conversationId: string;
1678
+ provider: string;
1679
+ modelId: string;
1680
+ } | {
1681
+ type: "conversation.thinking";
1682
+ conversationId: string;
1683
+ level: string;
1684
+ }
1685
+ /**
1686
+ * Applies an agent to a conversation. `agentId: null` clears it back to Pi's own defaults, the same
1687
+ * "absence means no value" rule the model and thinking selections follow.
1688
+ *
1689
+ * An agent that specifies a model or a thinking level does NOT set them here - it cannot, without
1690
+ * knowing what the user has already chosen. It resolves them in the handler, where a user override
1691
+ * that already exists is left alone, which is what makes the user's pick win over the agent's.
1692
+ */
1693
+ | {
1694
+ type: "conversation.agent";
1695
+ conversationId: string;
1696
+ agentId: string | null;
1697
+ }
1698
+ /** Asks for the model/thinking catalog. Answered by `model.catalog`, never by an `error`. */
1699
+ | {
1700
+ type: "catalog.fetch";
1701
+ conversationId?: string;
1702
+ }
1703
+ /** Enables bounded transport coalescing for high-frequency streaming events on this socket. */
1704
+ | {
1705
+ type: "stream.configure";
1706
+ coalesce: boolean;
1707
+ }
1708
+ /** Selects this socket's transcript; omitted conversationId requests sidebar summaries only. */
1709
+ | {
1710
+ type: "files.index.subscribe";
1711
+ workspaceId?: string;
1712
+ cwd?: string;
1713
+ } | {
1714
+ type: "state.subscribe";
1715
+ conversationId?: string;
1716
+ }
1717
+ /** Asks for the agent catalog read from disk. Answered by `agent.catalog`. */
1718
+ | {
1719
+ type: "agent.catalog.fetch";
1720
+ }
1721
+ /** Asks for prompt templates loaded by Pi for a workspace. */
1722
+ | {
1723
+ type: "prompt.catalog.fetch";
1724
+ workspaceId: string;
1725
+ }
1726
+ /**
1727
+ * Sends a message to a conversation, and THAT IS ALL IT CLAIMS.
1728
+ *
1729
+ * Whether the message starts a turn or joins the waiting queue is the SERVER's decision, made from
1730
+ * the run guard in `index.ts`: a conversation with a turn in flight gets the message queued, an idle
1731
+ * one gets a turn. The browser never picks, which is what makes the guard un-bypassable - the old
1732
+ * arrangement had the browser decide by disabling itself, and a second WebSocket client (or a stale
1733
+ * tab) walked straight past it into two Pi processes writing one session.
1734
+ *
1735
+ * `clientId` is how the browser's copy and the server's copy become THE SAME MESSAGE instead of two
1736
+ * that have to be matched up afterwards. The browser mints the id, renders the message with it in the
1737
+ * same frame it pressed send, and sends it here; the store uses it as the message id when it is well
1738
+ * formed and not already taken. So when the broadcast arrives there is nothing to reconcile - no
1739
+ * content matching, no `knownIds` set, no window in which the same sentence exists twice. It used to
1740
+ * be matched by `content === content.trim()`, which cannot tell two identical messages apart and made
1741
+ * the tests assert ordinals instead of messages. Omitted means "server, mint one".
1742
+ */
1743
+ | {
1744
+ type: "message.send";
1745
+ conversationId: string;
1746
+ content: string;
1747
+ images?: MessageImage[];
1748
+ attachments?: MessageAttachments;
1749
+ clientId?: string;
1750
+ mode?: MessageDeliveryMode;
1751
+ }
1752
+ /**
1753
+ * Revert the conversation to the state right AFTER one message: every message after it is removed from
1754
+ * BOTH histories, and no code file is touched.
1755
+ *
1756
+ * `messageId` names the message that SURVIVES. That is the same boundary OpenCode's revert draws
1757
+ * (`DELETE FROM session_message WHERE seq > boundary.seq`, `packages/core/src/session/projector.ts:427-432`)
1758
+ * and it is why this command takes no "how many messages" and no session id: the boundary is a thing the
1759
+ * user can see and point at, and everything after it goes.
1760
+ *
1761
+ * No new conversation is created, ever. That is the user's hard requirement, and the reason it is worth
1762
+ * stating here rather than only in the handler: Pi's own `fork()` cannot honour it (`fork()` always
1763
+ * tears the runtime down and opens a new session file, `agent-session-runtime.ts:299-307`), so any
1764
+ * implementation that reached for fork would break the promise without any type complaining.
1765
+ */
1766
+ | {
1767
+ type: "message.revert";
1768
+ conversationId: string;
1769
+ messageId: string;
1770
+ withdraw?: boolean;
1771
+ }
1772
+ /**
1773
+ * Withdraws ONE waiting message, by its message id.
1774
+ *
1775
+ * Addressed by `messageId` rather than by text or by index because two waiting messages can be the
1776
+ * same string. Refused for a message already in `sending` - Pi holds that text now and cannot be told
1777
+ * to forget one item - and an unknown or already-removed id is a no-op rather than an error, exactly
1778
+ * as `subagent.stop` treats a run that has already settled.
1779
+ */
1780
+ | {
1781
+ type: "message.cancel";
1782
+ conversationId: string;
1783
+ messageId: string;
1784
+ }
1785
+ /**
1786
+ * Withdraws a specific set of waiting messages by id while leaving remaining queued and steered
1787
+ * messages intact.
1788
+ */
1789
+ | {
1790
+ type: "message.cancelMany";
1791
+ conversationId: string;
1792
+ messageIds: string[];
1793
+ }
1794
+ /**
1795
+ * Rewrites the text of ONE waiting message that has not been given to Pi yet.
1796
+ *
1797
+ * The one mutation the old waiting list could not express: a row there was a content copy in an array
1798
+ * with no way to say "the user changed their mind about these words", so changing your mind meant
1799
+ * cancelling and retyping. Now the message itself is edited, in place, and it stays exactly where it
1800
+ * is. Refused for `sending`, for the same reason `cancel` is.
1801
+ */
1802
+ | {
1803
+ type: "message.edit";
1804
+ conversationId: string;
1805
+ messageId: string;
1806
+ content: string;
1807
+ }
1808
+ /**
1809
+ * Moves ONE waiting message to a new position among the waiting messages.
1810
+ *
1811
+ * This is the whole of what the old `priority` boolean meant, expressed as a position instead of a
1812
+ * flag. `toIndex` is counted over the WAITING messages only (`0` is the next one the agent will
1813
+ * start), so moving something to the front does not depend on how many answered messages sit above
1814
+ * it, and moving it back is the same command rather than a separate "un-prioritise" that would be a
1815
+ * second source of truth for one idea.
1816
+ */
1817
+ | {
1818
+ type: "message.reorder";
1819
+ conversationId: string;
1820
+ messageId: string;
1821
+ toIndex: number;
1822
+ }
1823
+ /**
1824
+ * Promotes one waiting message to a `steer`: Pi takes it at the next turn boundary instead of waiting
1825
+ * for the whole task to finish.
1826
+ *
1827
+ * The timing is Pi's and cannot be finer: `agent-loop.ts:295` polls steering after `turn_end`, which
1828
+ * is after the WHOLE tool-call batch of one assistant message has finished (`agent-loop.ts:270`). So
1829
+ * this means "after the tools currently running finish", and during a long single tool call there is
1830
+ * nothing to interrupt - Pi offers no preemption. The UI says so in words rather than implying
1831
+ * instant delivery.
1832
+ *
1833
+ * What this USED TO DO that it no longer does: it also set a `priority` flag, and on failure it fell
1834
+ * back to setting that flag, so "make this the next one" and "hand this to Pi right now" were one
1835
+ * button and one code path. They are still one button - both move the message to the front of the
1836
+ * waiting block - but the flag is gone, so the fallback is now the same move rather than a second
1837
+ * mechanism that had to be kept in agreement with the first.
1838
+ */
1839
+ | {
1840
+ type: "message.steer";
1841
+ conversationId: string;
1842
+ messageId: string;
1843
+ }
1844
+ /** Stops the active turn, then starts this waiting message as a fresh turn. */
1845
+ | {
1846
+ type: "message.interrupt";
1847
+ conversationId: string;
1848
+ messageId: string;
1849
+ }
1850
+ /** Starts this waiting message as the next turn, only after the current turn has ended. */
1851
+ | {
1852
+ type: "message.sendQueued";
1853
+ conversationId: string;
1854
+ messageId: string;
1855
+ } | {
1856
+ type: "run.stop";
1857
+ conversationId: string;
1858
+ }
1859
+ /**
1860
+ * A HUMAN dispatches a sub-agent, with no model in the loop (design doc §3, entry 1).
1861
+ *
1862
+ * The three fields are the whole contract and none of them is optional: `conversationId` decides
1863
+ * whose workspace the child runs in and whose transcript its card appears under, `agentId` must
1864
+ * name a `mode: subagent` definition (the handler resolves it that way, so a primary agent is
1865
+ * refused rather than quietly run as one), and `task` is what the child is asked to do. `task` has
1866
+ * no maximum here because the cap in design §6 applies to what a MODEL is handed back, not to what
1867
+ * a human may type; `SubagentSupervisor.run` refuses an empty one.
1868
+ */
1869
+ | {
1870
+ type: "subagent.run";
1871
+ conversationId: string;
1872
+ agentId: string;
1873
+ task: string;
1874
+ }
1875
+ /**
1876
+ * Stops ONE sub-agent run, by id rather than by conversation.
1877
+ *
1878
+ * Id-keyed because a conversation may have several runs in flight at once and "stop" that kills
1879
+ * every child of a conversation is a different, larger claim than the button on one card makes. A
1880
+ * run id that is unknown, or already settled, is a no-op rather than an error: the card that sent
1881
+ * this has usually just been told the run ended, and a stop that arrives late must not look like
1882
+ * a failure.
1883
+ */
1884
+ | {
1885
+ type: "subagent.stop";
1886
+ runId: string;
1887
+ }
1888
+ /** Stops one orchestrated plan. Distinct from `subagent.stop` because the engine holds the loop and
1889
+ * the signal, and stopping only the run would leave the plan marching on to the next step. */
1890
+ | {
1891
+ type: "workflow.stop";
1892
+ workflowId: string;
1893
+ }
1894
+ /** Asks for the `mode: subagent` half of the agent directory. Answered by `subagent.catalog`. */
1895
+ | {
1896
+ type: "subagent.catalog.fetch";
1897
+ } | {
1898
+ type: "agents.setCustomDirs";
1899
+ dirs: string[];
1900
+ } | {
1901
+ type: "agents.rescan";
1902
+ }
1903
+ /** Opens the browser at the Super Pi web UI, starting the server if it is not running. */
1904
+ | {
1905
+ type: "super_pi.start";
1906
+ }
1907
+ /** Runs `pi self-update` to update Super Pi. */
1908
+ | {
1909
+ type: "super_pi.update";
1910
+ }
1911
+ /** Restarts the Super Pi server by spawning the same restart script used by the auto-updater. */
1912
+ | {
1913
+ type: "super_pi.restart";
1914
+ }
1915
+ /**
1916
+ * A scheduled task is created.
1917
+ *
1918
+ * The schedule arrives as an opaque value and is validated on the SERVER, in the one place that owns
1919
+ * what a schedule means. The browser cannot send a half-valid schedule, because it does not know
1920
+ * what a half-valid schedule is; it sends the fields the panel collected and the server decides
1921
+ * whether they describe a schedule.
1922
+ */
1923
+ | {
1924
+ type: "scheduledTask.create";
1925
+ name?: string;
1926
+ prompt: string;
1927
+ schedule: unknown;
1928
+ workspaceId: string;
1929
+ model?: ModelSelection | null;
1930
+ agentId?: string | null;
1931
+ }
1932
+ /**
1933
+ * A scheduled task is changed. Every field is optional, and the ones that are absent are the ones
1934
+ * that do not change - a panel that sends the whole task back would fight the scheduler's own
1935
+ * bookkeeping over `nextRunAt`, which is not the panel's to write.
1936
+ */
1937
+ | {
1938
+ type: "scheduledTask.update";
1939
+ id: string;
1940
+ name?: string;
1941
+ prompt?: string;
1942
+ schedule?: unknown;
1943
+ model?: ModelSelection | null;
1944
+ agentId?: string | null;
1945
+ }
1946
+ /** A scheduled task is removed. Its conversation and the answers it produced stay. */
1947
+ | {
1948
+ type: "scheduledTask.delete";
1949
+ id: string;
1950
+ }
1951
+ /**
1952
+ * A scheduled task runs NOW, once, without touching its schedule.
1953
+ *
1954
+ * It is a separate command rather than a flag on `update` because it is a different act: `update`
1955
+ * changes what the task IS, and this changes what the task DID. The one thing it shares with the
1956
+ * clock is the run itself - it goes through the same path, so a manual run and a scheduled run
1957
+ * behave identically.
1958
+ */
1959
+ | {
1960
+ type: "scheduledTask.trigger";
1961
+ id: string;
1962
+ }
1963
+ /** A scheduled task is turned on or off. */
1964
+ | {
1965
+ type: "scheduledTask.toggle";
1966
+ id: string;
1967
+ enabled: boolean;
1968
+ } | ({
1969
+ type: "extension.ui.answer";
1970
+ conversationId: string;
1971
+ requestId: string;
1972
+ } & ExtensionUiAnswer);
1973
+ export type ServerVersionInfo = {
1974
+ runningVersion: string;
1975
+ diskVersion: string;
1976
+ needsRestart: boolean;
1977
+ latestVersion?: string;
1978
+ updateAvailable?: boolean;
1979
+ };
1980
+ export type MountedToolSummary = {
1981
+ id: string;
1982
+ name: string;
1983
+ description?: string;
1984
+ enabled: boolean;
1985
+ };
1986
+ /**
1987
+ * A file the agent changed, as the Files panel learns about it.
1988
+ *
1989
+ * `path` is workspace-relative and `/`-separated, the same spelling every other file path uses on the
1990
+ * wire. `baseline` is the content BEFORE the agent's write, or `null` when there was none - which is
1991
+ * how a NEW file is told from an EDITED one, and the two are different things to a reader.
1992
+ *
1993
+ * `baselineUnknown` says the "before" could not be read, as opposed to not existing. A diff view that
1994
+ * shows an empty "before" for a file that existed is a lie, and this flag is what keeps it from being
1995
+ * one.
1996
+ */
1997
+ export type ChangedFile = {
1998
+ path: string;
1999
+ /** The content before the agent wrote it, or `null` when the file did not exist then. */
2000
+ baseline: string | null;
2001
+ /** True when the baseline is missing because it could not be read, not because the file was new. */
2002
+ baselineUnknown?: boolean;
2003
+ /** The conversation the change belongs to, so a workspace's changes can be attributed to a session. */
2004
+ conversationId?: string;
2005
+ /** When it happened, so the panel can order a turn's changes the way they happened. */
2006
+ at: number;
2007
+ };
2008
+ export type ServerEvent = {
2009
+ type: "message.accepted";
2010
+ conversationId: string;
2011
+ clientId: string;
2012
+ } | ({
2013
+ type: "group.activity";
2014
+ } & GroupActivityUpdate) | {
2015
+ type: "run.stopping";
2016
+ conversationId: string;
2017
+ } | {
2018
+ type: "tools.updated";
2019
+ tools: MountedToolSummary[];
2020
+ }
2021
+ /**
2022
+ * THE AGENT CHANGED THESE FILES.
2023
+ *
2024
+ * WHY THIS EXISTS. The Files panel could browse the workspace but could not show a CHANGE, and a panel
2025
+ * that cannot show a change is a browser rather than a workbench: the user asked for the opposite - being
2026
+ * able to see the files is what makes the agent's edits reviewable. The server already knew which files
2027
+ * the agent wrote (the tool call names the path) and the knowledge went no further than one line on a
2028
+ * card, so a file the agent had rewritten looked exactly like a file it had never touched.
2029
+ *
2030
+ * A SNAPSHOT rather than a delta, like every other state-bearing event here: the client replaces its
2031
+ * list with this one, so a browser that missed an event rebuilds the list from the next one rather than
2032
+ * accumulating a partial truth.
2033
+ *
2034
+ * `dropped` says how many baselines were evicted because the per-workspace cap was reached. It is
2035
+ * reported rather than hidden, because a list that is shorter than the agent's actual work - with no
2036
+ * explanation - reads as "the agent only changed these" and is wrong.
2037
+ */
2038
+ | {
2039
+ type: "files.changed";
2040
+ workspaceId: string;
2041
+ changes: ChangedFile[];
2042
+ dropped: number;
2043
+ } | {
2044
+ type: "files.invalidated";
2045
+ workspaceId: string;
2046
+ paths?: string[];
2047
+ } | {
2048
+ type: "files.index";
2049
+ workspaceId: string;
2050
+ cwd?: string;
2051
+ version: number;
2052
+ changed: {
2053
+ path: string;
2054
+ kind: "file" | "directory";
2055
+ size: number | null;
2056
+ mtimeMs: number | null;
2057
+ etag: string | null;
2058
+ text: boolean | null;
2059
+ }[];
2060
+ removed: string[];
2061
+ complete: boolean;
2062
+ skipped: string[];
2063
+ } | {
2064
+ type: "operation.result";
2065
+ requestId: string;
2066
+ ok: boolean;
2067
+ message?: string;
2068
+ entityId?: string;
2069
+ } | {
2070
+ type: "server.version";
2071
+ version: ServerVersionInfo;
2072
+ } | {
2073
+ type: "state";
2074
+ state: AppState;
2075
+ } | {
2076
+ type: "message.delta";
2077
+ conversationId: string;
2078
+ messageId: string;
2079
+ delta: string;
2080
+ } | {
2081
+ type: "message.thinking";
2082
+ conversationId: string;
2083
+ messageId: string;
2084
+ delta: string;
2085
+ active: boolean;
2086
+ at?: number;
2087
+ blockIndex?: number;
2088
+ }
2089
+ /**
2090
+ * THE ANSWER TO `conversation.fork`, as ONE event with an `ok` discriminant rather than two events or a
2091
+ * bare `error`.
2092
+ *
2093
+ * WHY THIS EXISTS RATHER THAN REUSING `error`. The generic `error` event carries a message and nothing
2094
+ * else, and the client's handler turns one into a banner over the whole pane. A fork that failed is a
2095
+ * fact about ONE row of the sidebar, and the reader needs to know WHICH row: 「分叉失败:…」 with no
2096
+ * conversation named leaves the user looking at a button that did nothing, which is the exact failure
2097
+ * the requirement names. Two consequences, both load-bearing:
2098
+ *
2099
+ * - `conversationId` is on BOTH arms, so the browser can clear that row's pending state and re-enable
2100
+ * exactly the button that was pressed. Nothing else in the protocol can be correlated to the press.
2101
+ * - The failure arm is a SENTENCE (`message`), produced by the same code that produced the refusal, so
2102
+ * the reason the server refused is the reason shown. A boolean would be a dead click.
2103
+ *
2104
+ * It is ALSO why the handler catches instead of letting a fork throw: a thrown command becomes a
2105
+ * broadcast `error` to every connected browser, which would blame an unrelated pane in another tab.
2106
+ *
2107
+ * The success arm reports `messagesCopied` because "the fork happened" and "the fork happened completely"
2108
+ * are different claims, and a whole-session fork of a conversation whose Pi transcript could not be
2109
+ * located is a copy of the visible half only.
2110
+ */
2111
+ | ({
2112
+ type: "conversation.fork.result";
2113
+ conversationId: string;
2114
+ } & ({
2115
+ ok: true;
2116
+ forkedId: string;
2117
+ title: string;
2118
+ messagesCopied: number;
2119
+ piSessionFile?: string;
2120
+ } | {
2121
+ ok: false;
2122
+ message: string;
2123
+ }))
2124
+ /**
2125
+ * Every tool call made while filling one message, as a whole SNAPSHOT.
2126
+ *
2127
+ * A snapshot for the same reason `subagent.event` is one and `message.delta` is a delta: `state` carries
2128
+ * the same array, so a reload or a reconnect rebuilds every block from the file, and a browser that missed
2129
+ * an event must not be left holding a half-built row. The difference from `message.delta` is that this one
2130
+ * CANNOT be a delta - the fields change on a row rather than append to a string, and "apply this patch"
2131
+ * is an instruction the client has to be trusted to apply correctly.
2132
+ *
2133
+ * Sent on `tool_execution_start` and again on `tool_execution_end`, so a block appears the moment a call
2134
+ * begins rather than when the whole turn ends. That is what makes a long tool call visible while it is
2135
+ * running - and a call that starts and never ends leaves a row with no `status`, which is exactly how a
2136
+ * block says "still in flight" instead of claiming an outcome nobody reported.
2137
+ */
2138
+ | {
2139
+ type: "message.tools";
2140
+ conversationId: string;
2141
+ messageId: string;
2142
+ toolCalls: ToolCallBlock[];
2143
+ } | {
2144
+ type: "error";
2145
+ message: string;
2146
+ } | {
2147
+ type: "extension.ui";
2148
+ conversationId: string;
2149
+ request: ExtensionUiRequest;
2150
+ } | {
2151
+ type: "extension.ui.closed";
2152
+ conversationId: string;
2153
+ requestId: string;
2154
+ reason: ExtensionUiCloseReason;
2155
+ } | {
2156
+ type: "message.revert.result";
2157
+ conversationId: string;
2158
+ ok: boolean;
2159
+ message?: string;
2160
+ withdrawn?: {
2161
+ content: string;
2162
+ images?: MessageImage[];
2163
+ };
2164
+ } | {
2165
+ type: "model.catalog";
2166
+ catalog: ModelCatalog;
2167
+ conversationId?: string;
2168
+ }
2169
+ /**
2170
+ * The UNFILTERED catalog, for the settings window's model panel. A different event type from
2171
+ * `model.catalog` on purpose: that one is scoped to a conversation and filtered by that
2172
+ * workspace's model rules, and the settings panel must be able to offer the models the rules
2173
+ * hide - while the composer picker must keep hiding them. One event carrying both would force
2174
+ * one of the two to be wrong.
2175
+ */
2176
+ | {
2177
+ type: "model.catalog.all";
2178
+ catalog: ModelCatalog;
2179
+ }
2180
+ /**
2181
+ * The providers Super Pi manages. Sent when they change, and when a client connects.
2182
+ *
2183
+ * `apis` travels with them so the form's API-type list has ONE source of truth: the list of
2184
+ * adapters Pi ships is a fact about the Pi that is installed, and a copy of it in the browser
2185
+ * would be a copy that goes stale.
2186
+ */
2187
+ | {
2188
+ type: "providers.list";
2189
+ providers: PublicProvider[];
2190
+ apis: string[];
2191
+ }
2192
+ /**
2193
+ * The answer to conversation.autoRename. Carries a title OR an error and never both, because the client
2194
+ * has exactly two things to say about it: here is the new name, or here is why there isnt one.
2195
+ */
2196
+ | {
2197
+ type: "conversation.autoRename.result";
2198
+ conversationId: string;
2199
+ ok: true;
2200
+ title: string;
2201
+ } | {
2202
+ type: "conversation.autoRename.result";
2203
+ conversationId: string;
2204
+ ok: false;
2205
+ error: string;
2206
+ } | {
2207
+ type: "agent.catalog";
2208
+ catalog: AgentCatalog;
2209
+ } | {
2210
+ type: "prompt.catalog";
2211
+ catalog: PromptCatalog;
2212
+ }
2213
+ /**
2214
+ * The `mode: subagent` half of the same directory, as its OWN event rather than an extra key on
2215
+ * `agent.catalog`.
2216
+ *
2217
+ * Split because the two rosters are kept apart everywhere else - `readAgents` filters by mode, the
2218
+ * primary picker never sees a sub-agent and vice versa - and folding them into one payload would
2219
+ * hand the browser a list it must then filter correctly, which is precisely the invariant that has
2220
+ * to hold. Two catalogs, each already filtered at the source, cannot leak across.
2221
+ */
2222
+ | {
2223
+ type: "subagent.catalog";
2224
+ catalog: AgentCatalog;
2225
+ }
2226
+ /**
2227
+ * The current SNAPSHOT of one sub-agent run, sent on every text delta rather than once at the end.
2228
+ *
2229
+ * A snapshot rather than a delta for the same reason `state` is one: a card that assembles itself
2230
+ * from a missed event is a card that can be wrong, and this event has to survive a reconnect race and
2231
+ * an out-of-order drop. The price is that each one serializes the run so far, which is exactly why
2232
+ * `SubagentRun` holds the last assistant message and not the transcript.
2233
+ */
2234
+ | {
2235
+ type: "subagent.event";
2236
+ run: SubagentRun;
2237
+ }
2238
+ /**
2239
+ * The current SNAPSHOT of one orchestrated plan, sent on every step transition and nothing else.
2240
+ *
2241
+ * WHOLE SNAPSHOT, like `subagent.event`, for the same reason: a timeline assembled from missed events
2242
+ * is a timeline that can be wrong, and this one has to survive a reload and a reconnect race.
2243
+ *
2244
+ * ON TRANSITIONS ONLY, never on a stream delta, and that asymmetry is deliberate rather than an
2245
+ * oversight. A step's own progress already arrives as `subagent.event` for the run it is executing, so
2246
+ * a workflow event on every delta would broadcast the whole plan - every step's output, accumulated -
2247
+ * once per TOKEN of one child. That is the one way this feature could make the app feel broken. Two
2248
+ * events per step (begin, settle) is what a timeline actually needs; the rest is the run card's job.
2249
+ */
2250
+ | {
2251
+ type: "workflow.event";
2252
+ workflow: WorkflowRun;
2253
+ }
2254
+ /**
2255
+ * Pi's own queue snapshot, forwarded the moment `queue_update` arrives on the child's stdout.
2256
+ *
2257
+ * A new event rather than another key on `state` because it is a different thing with a different
2258
+ * lifetime: `state` carries the durable waiting list, this carries what the live child process is
2259
+ * holding right now and changes many times within a single turn. Keeping them apart is also what stops
2260
+ * the two from being confused for one source of truth - the browser renders the dock from `state` and
2261
+ * only annotates it with this.
2262
+ */
2263
+ | ({
2264
+ type: "pi.queue";
2265
+ conversationId: string;
2266
+ } & PiQueueSnapshot)
2267
+ /**
2268
+ * Announces that one or more queued messages were withdrawn, along with their ids and text previews,
2269
+ * so both user-initiated and agent-initiated withdrawals remain visible rather than silent.
2270
+ */
2271
+ | {
2272
+ type: "queue.withdrawn";
2273
+ conversationId: string;
2274
+ withdrawn: {
2275
+ id: string;
2276
+ content: string;
2277
+ role: "user" | "tool";
2278
+ }[];
2279
+ actor: "user" | "agent";
2280
+ } | TerminalEvent
2281
+ /**
2282
+ * Output from a background exec session. Forwarded to the browser so it can stream to the terminal panel
2283
+ * if that session is visible, and collected by the exec service for the final result.
2284
+ */
2285
+ | {
2286
+ type: "exec.output";
2287
+ sessionId: string;
2288
+ conversationId?: string;
2289
+ data: string;
2290
+ replace?: boolean;
2291
+ offset?: number;
2292
+ truncated?: boolean;
2293
+ }
2294
+ /**
2295
+ * A background exec session ended. `stdout` and `stderr` are the collected output; the exec service
2296
+ * handles injecting the result into the conversation.
2297
+ */
2298
+ | {
2299
+ type: "exec.exit";
2300
+ sessionId: string;
2301
+ conversationId?: string;
2302
+ exitCode?: number;
2303
+ stdout: string;
2304
+ stderr: string;
2305
+ }
2306
+ /** Whether the exec service is available. Sent on a refused command. */
2307
+ | {
2308
+ type: "exec.status";
2309
+ enabled: boolean;
2310
+ reason?: string;
2311
+ };
2312
+ /** Events emitted by the background exec service. */
2313
+ export type ExecEvent = Extract<ServerEvent, {
2314
+ type: `exec.${string}`;
2315
+ }>;