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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (370) hide show
  1. package/README.md +248 -3
  2. package/agents/code-auditor.md +64 -0
  3. package/agents/code-designer.md +64 -0
  4. package/agents/coder.md +24 -0
  5. package/agents/critic.md +24 -0
  6. package/agents/document-organizer.md +48 -0
  7. package/agents/patcher.md +27 -0
  8. package/agents/planner.md +30 -0
  9. package/agents/project-leader.md +28 -0
  10. package/agents/reviewer.md +27 -0
  11. package/agents/scout.md +27 -0
  12. package/agents/solution-designer.md +62 -0
  13. package/agents/super-pi-documents/index.ts +92 -0
  14. package/agents/super-pi-feishu/index.ts +88 -0
  15. package/agents/super-pi-knowledge/index.ts +70 -0
  16. package/agents/super-pi-managed-model/index.ts +9 -0
  17. package/agents/super-pi-memory/index.ts +75 -0
  18. package/agents/super-pi-native-tools/index.ts +1 -0
  19. package/agents/super-pi-task/core.ts +2262 -0
  20. package/agents/super-pi-task/index.ts +814 -0
  21. package/agents/super-pi-task/workflow-schema.ts +34 -0
  22. package/agents/super-pi-web/index.ts +32 -0
  23. package/agents/verifier.md +25 -0
  24. package/assets/fonts/LICENSE +92 -0
  25. package/assets/fonts/NotoSansSC-Bold.otf +0 -0
  26. package/assets/fonts/NotoSansSC-Regular.otf +0 -0
  27. package/assets/knowledge-model/README.md +37 -0
  28. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/config.json +31 -0
  29. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/onnx/model_quantized.onnx +0 -0
  30. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/special_tokens_map.json +7 -0
  31. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/tokenizer.json +21278 -0
  32. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/tokenizer_config.json +15 -0
  33. package/assets/knowledge-model/Xenova/bge-small-zh-v1.5/vocab.txt +21128 -0
  34. package/bin/npm-prefix.d.ts +1 -0
  35. package/bin/npm-prefix.js +10 -0
  36. package/bin/super-pi.js +349 -0
  37. package/dist/client/.super-pi-client-sources.json +82 -0
  38. package/dist/client/assets/CodeMirrorEditor-mi9rGUce.js +2 -0
  39. package/dist/client/assets/GitDiffEditor-CpoDDQrA.css +1 -0
  40. package/dist/client/assets/GitDiffEditor-FQBfGxOY.js +29 -0
  41. package/dist/client/assets/diff-ChtP43wD.js +1 -0
  42. package/dist/client/assets/dist-AW5lyI3I.js +1 -0
  43. package/dist/client/assets/dist-B3-a6uF0.js +7 -0
  44. package/dist/client/assets/dist-BGxkyh6e.js +1 -0
  45. package/dist/client/assets/dist-BJxfd7yb.js +11 -0
  46. package/dist/client/assets/dist-BRVQKlcp.js +1 -0
  47. package/dist/client/assets/dist-BV64A9Ji.js +1 -0
  48. package/dist/client/assets/dist-BXAOrsjq.js +1 -0
  49. package/dist/client/assets/dist-CKF2Jksy.js +1 -0
  50. package/dist/client/assets/dist-CX_Hm4GS.js +1 -0
  51. package/dist/client/assets/dist-Cus6_oaF.js +2 -0
  52. package/dist/client/assets/dist-Cx00EZKR.js +23 -0
  53. package/dist/client/assets/dist-D71y2EI1.js +1 -0
  54. package/dist/client/assets/dist-D978o95T.js +5 -0
  55. package/dist/client/assets/dist-Dc1MBGAG.js +1 -0
  56. package/dist/client/assets/dist-Dds-qLxY.js +9 -0
  57. package/dist/client/assets/dist-DeD9copn.js +1 -0
  58. package/dist/client/assets/dist-DuvGReu-.js +6 -0
  59. package/dist/client/assets/dist-Dvb0SqcK.js +2 -0
  60. package/dist/client/assets/dist-J6XWqRpB.js +3 -0
  61. package/dist/client/assets/dist-QzbOCAU6.js +1 -0
  62. package/dist/client/assets/dist-moiMRpw_.js +1 -0
  63. package/dist/client/assets/dist-scBkrwv-.js +2 -0
  64. package/dist/client/assets/dockerfile-BDePf5PZ.js +1 -0
  65. package/dist/client/assets/index-Cn7hdrDw.js +350 -0
  66. package/dist/client/assets/index-UfzqdECL.css +1 -0
  67. package/dist/client/assets/powershell-D8WpQPaX.js +1 -0
  68. package/dist/client/assets/properties-C357ku5U.js +1 -0
  69. package/dist/client/assets/rolldown-runtime-XKyaHtl9.js +1 -0
  70. package/dist/client/assets/ruby-ChfNwlCY.js +1 -0
  71. package/dist/client/assets/shell-DwuoZtxw.js +1 -0
  72. package/dist/client/assets/swift-DKB6_1j6.js +1 -0
  73. package/dist/client/assets/toml-BPTmHmyx.js +1 -0
  74. package/dist/client/favicon.ico +0 -0
  75. package/dist/client/favicon.png +0 -0
  76. package/dist/client/favicon.svg +10 -0
  77. package/dist/client/index.html +18 -0
  78. package/dist/extension.d.ts +15 -0
  79. package/dist/extension.js +126 -0
  80. package/dist/server/active-memory.d.ts +247 -0
  81. package/dist/server/active-memory.js +669 -0
  82. package/dist/server/agents.d.ts +245 -0
  83. package/dist/server/agents.js +701 -0
  84. package/dist/server/application/catalog-service.d.ts +98 -0
  85. package/dist/server/application/catalog-service.js +245 -0
  86. package/dist/server/application/conversation-service.d.ts +245 -0
  87. package/dist/server/application/conversation-service.js +654 -0
  88. package/dist/server/application/document-service.d.ts +68 -0
  89. package/dist/server/application/document-service.js +120 -0
  90. package/dist/server/application/extension-ui-service.d.ts +44 -0
  91. package/dist/server/application/extension-ui-service.js +135 -0
  92. package/dist/server/application/feishu-service.d.ts +179 -0
  93. package/dist/server/application/feishu-service.js +358 -0
  94. package/dist/server/application/group-chat-service.d.ts +75 -0
  95. package/dist/server/application/group-chat-service.js +953 -0
  96. package/dist/server/application/group-execution.d.ts +15 -0
  97. package/dist/server/application/group-execution.js +77 -0
  98. package/dist/server/application/project-service.d.ts +464 -0
  99. package/dist/server/application/project-service.js +2523 -0
  100. package/dist/server/application/provider-service.d.ts +174 -0
  101. package/dist/server/application/provider-service.js +510 -0
  102. package/dist/server/application/run-service.d.ts +547 -0
  103. package/dist/server/application/run-service.js +2683 -0
  104. package/dist/server/application/scheduled-task-service.d.ts +184 -0
  105. package/dist/server/application/scheduled-task-service.js +391 -0
  106. package/dist/server/application/session-orchestrator-service.d.ts +388 -0
  107. package/dist/server/application/session-orchestrator-service.js +1146 -0
  108. package/dist/server/application/session-reminder-service.d.ts +59 -0
  109. package/dist/server/application/session-reminder-service.js +141 -0
  110. package/dist/server/application/session-watchdog.d.ts +171 -0
  111. package/dist/server/application/session-watchdog.js +284 -0
  112. package/dist/server/application/workspace-service.d.ts +52 -0
  113. package/dist/server/application/workspace-service.js +186 -0
  114. package/dist/server/application/worktree-service.d.ts +13 -0
  115. package/dist/server/application/worktree-service.js +76 -0
  116. package/dist/server/browser-access.d.ts +34 -0
  117. package/dist/server/browser-access.js +89 -0
  118. package/dist/server/capability.d.ts +105 -0
  119. package/dist/server/capability.js +170 -0
  120. package/dist/server/command-handler.d.ts +93 -0
  121. package/dist/server/command-handler.js +540 -0
  122. package/dist/server/content-search.d.ts +16 -0
  123. package/dist/server/content-search.js +235 -0
  124. package/dist/server/conversation-usage.d.ts +22 -0
  125. package/dist/server/conversation-usage.js +43 -0
  126. package/dist/server/documents.d.ts +152 -0
  127. package/dist/server/documents.js +998 -0
  128. package/dist/server/engineering-learning.d.ts +30 -0
  129. package/dist/server/engineering-learning.js +106 -0
  130. package/dist/server/exec-service.d.ts +45 -0
  131. package/dist/server/exec-service.js +167 -0
  132. package/dist/server/explicit-file-open.d.ts +34 -0
  133. package/dist/server/explicit-file-open.js +105 -0
  134. package/dist/server/failure-text.d.ts +18 -0
  135. package/dist/server/failure-text.js +44 -0
  136. package/dist/server/feishu-cli.d.ts +223 -0
  137. package/dist/server/feishu-cli.js +464 -0
  138. package/dist/server/file-changes.d.ts +119 -0
  139. package/dist/server/file-changes.js +280 -0
  140. package/dist/server/file-diff.d.ts +41 -0
  141. package/dist/server/file-diff.js +97 -0
  142. package/dist/server/file-index.d.ts +100 -0
  143. package/dist/server/file-index.js +296 -0
  144. package/dist/server/file-name-index.d.ts +160 -0
  145. package/dist/server/file-name-index.js +411 -0
  146. package/dist/server/files.d.ts +269 -0
  147. package/dist/server/files.js +748 -0
  148. package/dist/server/git.d.ts +245 -0
  149. package/dist/server/git.js +903 -0
  150. package/dist/server/http-server.d.ts +45 -0
  151. package/dist/server/http-server.js +3830 -0
  152. package/dist/server/index.d.ts +1 -0
  153. package/dist/server/index.js +485 -0
  154. package/dist/server/inline-thinking.d.ts +90 -0
  155. package/dist/server/inline-thinking.js +181 -0
  156. package/dist/server/json-comments.d.ts +14 -0
  157. package/dist/server/json-comments.js +71 -0
  158. package/dist/server/knowledge-embedding-worker.d.ts +1 -0
  159. package/dist/server/knowledge-embedding-worker.js +27 -0
  160. package/dist/server/knowledge-vectors.d.ts +150 -0
  161. package/dist/server/knowledge-vectors.js +385 -0
  162. package/dist/server/knowledge.d.ts +273 -0
  163. package/dist/server/knowledge.js +848 -0
  164. package/dist/server/length-continuation.d.ts +83 -0
  165. package/dist/server/length-continuation.js +118 -0
  166. package/dist/server/logging.d.ts +32 -0
  167. package/dist/server/logging.js +185 -0
  168. package/dist/server/managed-http-tunnel.d.ts +6 -0
  169. package/dist/server/managed-http-tunnel.js +85 -0
  170. package/dist/server/managed-http.d.ts +4 -0
  171. package/dist/server/managed-http.js +85 -0
  172. package/dist/server/managed-model-adapter.d.ts +17 -0
  173. package/dist/server/managed-model-adapter.js +75 -0
  174. package/dist/server/managed-model-gateway.d.ts +49 -0
  175. package/dist/server/managed-model-gateway.js +73 -0
  176. package/dist/server/managed-servers.d.ts +55 -0
  177. package/dist/server/managed-servers.js +392 -0
  178. package/dist/server/managed-ssh.d.ts +26 -0
  179. package/dist/server/managed-ssh.js +73 -0
  180. package/dist/server/manager-vault.d.ts +11 -0
  181. package/dist/server/manager-vault.js +67 -0
  182. package/dist/server/memory-recall.d.ts +25 -0
  183. package/dist/server/memory-recall.js +45 -0
  184. package/dist/server/memory.d.ts +67 -0
  185. package/dist/server/memory.js +216 -0
  186. package/dist/server/message-media.d.ts +7 -0
  187. package/dist/server/message-media.js +54 -0
  188. package/dist/server/model-context-window.d.ts +186 -0
  189. package/dist/server/model-context-window.js +444 -0
  190. package/dist/server/model-filter.d.ts +23 -0
  191. package/dist/server/model-filter.js +48 -0
  192. package/dist/server/models-store.d.ts +36 -0
  193. package/dist/server/models-store.js +132 -0
  194. package/dist/server/native-tool-settings.d.ts +25 -0
  195. package/dist/server/native-tool-settings.js +41 -0
  196. package/dist/server/native-tools-extension.d.ts +2 -0
  197. package/dist/server/native-tools-extension.js +39 -0
  198. package/dist/server/native-tools-service.d.ts +39 -0
  199. package/dist/server/native-tools-service.js +240 -0
  200. package/dist/server/persistence/app-state-repository.d.ts +65 -0
  201. package/dist/server/persistence/app-state-repository.js +1 -0
  202. package/dist/server/persistence/json-state-repository.d.ts +14 -0
  203. package/dist/server/persistence/json-state-repository.js +43 -0
  204. package/dist/server/persistence/open-state-store.d.ts +3 -0
  205. package/dist/server/persistence/open-state-store.js +35 -0
  206. package/dist/server/persistence/rename.d.ts +22 -0
  207. package/dist/server/persistence/rename.js +44 -0
  208. package/dist/server/persistence/sqlite-state-repository.d.ts +12 -0
  209. package/dist/server/persistence/sqlite-state-repository.js +264 -0
  210. package/dist/server/pi-command.d.ts +94 -0
  211. package/dist/server/pi-command.js +265 -0
  212. package/dist/server/pi-native.d.ts +12 -0
  213. package/dist/server/pi-native.js +16 -0
  214. package/dist/server/pi-session-events.d.ts +158 -0
  215. package/dist/server/pi-session-events.js +373 -0
  216. package/dist/server/pi-session-pool.d.ts +233 -0
  217. package/dist/server/pi-session-pool.js +382 -0
  218. package/dist/server/pi-session.d.ts +642 -0
  219. package/dist/server/pi-session.js +655 -0
  220. package/dist/server/presentations/schema.d.ts +120 -0
  221. package/dist/server/presentations/schema.js +128 -0
  222. package/dist/server/provider-network.d.ts +16 -0
  223. package/dist/server/provider-network.js +106 -0
  224. package/dist/server/provider-proxy.d.ts +18 -0
  225. package/dist/server/provider-proxy.js +200 -0
  226. package/dist/server/providers.d.ts +333 -0
  227. package/dist/server/providers.js +989 -0
  228. package/dist/server/remote-bootstrap.d.ts +17 -0
  229. package/dist/server/remote-bootstrap.js +119 -0
  230. package/dist/server/rpc-channel.d.ts +131 -0
  231. package/dist/server/rpc-channel.js +135 -0
  232. package/dist/server/runtime.d.ts +1393 -0
  233. package/dist/server/runtime.js +3286 -0
  234. package/dist/server/scheduled-tasks.d.ts +101 -0
  235. package/dist/server/scheduled-tasks.js +138 -0
  236. package/dist/server/server-context.d.ts +119 -0
  237. package/dist/server/server-context.js +1 -0
  238. package/dist/server/session-cwd.d.ts +19 -0
  239. package/dist/server/session-cwd.js +58 -0
  240. package/dist/server/session-ledger.d.ts +67 -0
  241. package/dist/server/session-ledger.js +76 -0
  242. package/dist/server/session-memory-scope.d.ts +4 -0
  243. package/dist/server/session-memory-scope.js +30 -0
  244. package/dist/server/session-repository.d.ts +100 -0
  245. package/dist/server/session-repository.js +246 -0
  246. package/dist/server/session-tree-scope.d.ts +125 -0
  247. package/dist/server/session-tree-scope.js +337 -0
  248. package/dist/server/skills.d.ts +23 -0
  249. package/dist/server/skills.js +190 -0
  250. package/dist/server/store.d.ts +1062 -0
  251. package/dist/server/store.js +3305 -0
  252. package/dist/server/subagent-runs.d.ts +185 -0
  253. package/dist/server/subagent-runs.js +383 -0
  254. package/dist/server/subagents.d.ts +200 -0
  255. package/dist/server/subagents.js +619 -0
  256. package/dist/server/task-tool.d.ts +282 -0
  257. package/dist/server/task-tool.js +507 -0
  258. package/dist/server/tavily.d.ts +32 -0
  259. package/dist/server/tavily.js +136 -0
  260. package/dist/server/team-context.d.ts +12 -0
  261. package/dist/server/team-context.js +180 -0
  262. package/dist/server/terminal.d.ts +163 -0
  263. package/dist/server/terminal.js +557 -0
  264. package/dist/server/thinking-level-discovery.d.ts +38 -0
  265. package/dist/server/thinking-level-discovery.js +183 -0
  266. package/dist/server/time-zone.d.ts +20 -0
  267. package/dist/server/time-zone.js +32 -0
  268. package/dist/server/tool-calls.d.ts +130 -0
  269. package/dist/server/tool-calls.js +341 -0
  270. package/dist/server/tool-llm.d.ts +72 -0
  271. package/dist/server/tool-llm.js +146 -0
  272. package/dist/server/tool-registry.d.ts +129 -0
  273. package/dist/server/tool-registry.js +249 -0
  274. package/dist/server/tool-runner.d.ts +112 -0
  275. package/dist/server/tool-runner.js +306 -0
  276. package/dist/server/turn-failure.d.ts +48 -0
  277. package/dist/server/turn-failure.js +148 -0
  278. package/dist/server/types.d.ts +2315 -0
  279. package/dist/server/types.js +11 -0
  280. package/dist/server/update-status.d.ts +14 -0
  281. package/dist/server/update-status.js +69 -0
  282. package/dist/server/update.d.ts +46 -0
  283. package/dist/server/update.js +104 -0
  284. package/dist/server/upload.d.ts +35 -0
  285. package/dist/server/upload.js +177 -0
  286. package/dist/server/version.d.ts +33 -0
  287. package/dist/server/version.js +111 -0
  288. package/dist/server/web.d.ts +27 -0
  289. package/dist/server/web.js +183 -0
  290. package/dist/server/workflow-engine.d.ts +47 -0
  291. package/dist/server/workflow-engine.js +255 -0
  292. package/dist/server/workflow.d.ts +329 -0
  293. package/dist/server/workflow.js +469 -0
  294. package/dist/server/workspace-file-indexes.d.ts +2 -0
  295. package/dist/server/workspace-file-indexes.js +61 -0
  296. package/dist/server/workspace-file-operations.d.ts +36 -0
  297. package/dist/server/workspace-file-operations.js +281 -0
  298. package/dist/server/workspace-file-response.d.ts +7 -0
  299. package/dist/server/workspace-file-response.js +79 -0
  300. package/dist/server/ws-server.d.ts +149 -0
  301. package/dist/server/ws-server.js +640 -0
  302. package/dist/shared/agent-order.d.ts +44 -0
  303. package/dist/shared/agent-order.js +50 -0
  304. package/dist/shared/archive-decisions.d.ts +44 -0
  305. package/dist/shared/archive-decisions.js +98 -0
  306. package/dist/shared/background-task.d.ts +25 -0
  307. package/dist/shared/background-task.js +183 -0
  308. package/dist/shared/child-session-lock.d.ts +37 -0
  309. package/dist/shared/child-session-lock.js +59 -0
  310. package/dist/shared/content-search.d.ts +22 -0
  311. package/dist/shared/content-search.js +1 -0
  312. package/dist/shared/conversation-title.d.ts +4 -0
  313. package/dist/shared/conversation-title.js +4 -0
  314. package/dist/shared/file-mentions.d.ts +17 -0
  315. package/dist/shared/file-mentions.js +91 -0
  316. package/dist/shared/git-commit.d.ts +11 -0
  317. package/dist/shared/git-commit.js +1 -0
  318. package/dist/shared/git-graph.d.ts +42 -0
  319. package/dist/shared/git-graph.js +30 -0
  320. package/dist/shared/group-chat.d.ts +132 -0
  321. package/dist/shared/group-chat.js +6 -0
  322. package/dist/shared/managed-servers.d.ts +36 -0
  323. package/dist/shared/managed-servers.js +1 -0
  324. package/dist/shared/message-media.d.ts +12 -0
  325. package/dist/shared/message-media.js +27 -0
  326. package/dist/shared/model-window-label.d.ts +39 -0
  327. package/dist/shared/model-window-label.js +55 -0
  328. package/dist/shared/native-tools.d.ts +43 -0
  329. package/dist/shared/native-tools.js +1 -0
  330. package/dist/shared/pi-cache-warming.d.ts +9 -0
  331. package/dist/shared/pi-cache-warming.js +4 -0
  332. package/dist/shared/project-overview.d.ts +107 -0
  333. package/dist/shared/project-overview.js +92 -0
  334. package/dist/shared/project-presentation.d.ts +55 -0
  335. package/dist/shared/project-presentation.js +111 -0
  336. package/dist/shared/provider-network.d.ts +30 -0
  337. package/dist/shared/provider-network.js +1 -0
  338. package/dist/shared/session-reporting.d.ts +40 -0
  339. package/dist/shared/session-reporting.js +97 -0
  340. package/dist/shared/session-search.d.ts +14 -0
  341. package/dist/shared/session-search.js +1 -0
  342. package/dist/shared/team-context-view.d.ts +33 -0
  343. package/dist/shared/team-context-view.js +49 -0
  344. package/dist/shared/team-context.d.ts +59 -0
  345. package/dist/shared/team-context.js +3 -0
  346. package/dist/shared/terminal-protocol.d.ts +71 -0
  347. package/dist/shared/terminal-protocol.js +1 -0
  348. package/dist/shared/thinking-levels.d.ts +53 -0
  349. package/dist/shared/thinking-levels.js +85 -0
  350. package/dist/shared/tool-glyph.d.ts +7 -0
  351. package/dist/shared/tool-glyph.js +19 -0
  352. package/dist/shared/transcript-order.d.ts +7 -0
  353. package/dist/shared/transcript-order.js +12 -0
  354. package/dist/shared/update-status.d.ts +28 -0
  355. package/dist/shared/update-status.js +1 -0
  356. package/dist/shared/workspace-file-preview.d.ts +4 -0
  357. package/dist/shared/workspace-file-preview.js +28 -0
  358. package/package.json +448 -4
  359. package/scripts/diagnose.mjs +603 -0
  360. package/scripts/patch-brace-expansion.mjs +260 -0
  361. package/scripts/restart-server.mjs +104 -0
  362. package/skills/presentation/SKILL.md +30 -0
  363. package/skills/presentation/references/data.md +10 -0
  364. package/skills/presentation/references/quality.md +12 -0
  365. package/skills/presentation/references/story.md +12 -0
  366. package/skills/presentation/references/templates-and-editing.md +11 -0
  367. package/skills/presentation/references/visual-system.md +10 -0
  368. package/skills/super-pi-agent-development/SKILL.md +25 -0
  369. package/skills/super-pi-development/SKILL.md +31 -0
  370. package/skills/super-pi-tool-development/SKILL.md +39 -0
@@ -0,0 +1,170 @@
1
+ import { randomUUID, timingSafeEqual } from "node:crypto";
2
+ /**
3
+ * Proving that a dispatch request came from THIS server's primary agent, rather than from anything else on
4
+ * the machine that can open a socket to localhost.
5
+ *
6
+ * WHY THIS EXISTS, since the dispatch endpoint already looks like it authenticates. It does not. It
7
+ * validates ANCESTRY - that a claimed `parentRunId` names a real run belonging to the right conversation -
8
+ * and `docs/AGENT_LOOP_DESIGN.md` states the limit in as many words: "The current HTTP boundary validates
9
+ * supplied ancestry, not caller identity. A local process that omits both parentRunId and depth is
10
+ * indistinguishable from a primary caller." That is true, and it was tolerable while the only reachable
11
+ * primitive was a single dispatch. It stops being tolerable the moment an endpoint can trigger a SEQUENCE
12
+ * of dispatches: one unauthenticated POST becomes an unattended pipeline of sub-agents writing to the
13
+ * user's workspace, which is a far larger lever for the same missing check.
14
+ *
15
+ * WHY A CAPABILITY RATHER THAN A SHARED SECRET. `SUPER_PI_ACCESS_TOKEN` already exists and every endpoint
16
+ * already checks it - but it is SERVER-WIDE and optional: unset is the default, and when unset the whole
17
+ * server runs open on loopback, which is a reasonable choice for an app meant to be run by the person
18
+ * sitting at the machine. A dispatch capability is narrower and non-optional in the way that matters: it
19
+ * exists only for the duration of one turn, for one conversation, and only the primary agent's environment
20
+ * ever holds it. `SubagentSupervisor` passes no `env` to a child at all (`subagents.ts:371-380`), so a
21
+ * sub-agent - whose whole threat is that a model controls its inputs and therefore its shell commands -
22
+ * structurally cannot read it back out of its own environment and post it.
23
+ *
24
+ * WHAT THIS DOES NOT CLAIM. It is not defence against a compromised primary agent, which can read its own
25
+ * environment and would simply forward the capability. It is defence against the two neighbours of the
26
+ * primary that are NOT it: an unrelated local process, and a sub-agent that escaped its read-only
27
+ * allowlist. Neither is the primary, and neither is handed the token.
28
+ */
29
+ /**
30
+ * The environment variable the capability travels in.
31
+ *
32
+ * Named on both sides of the wire rather than imported by the extension, for the reason every one of
33
+ * these names is written out twice: `agents/` is loaded by Pi's module loader and `src/` by tsc, so a
34
+ * relative import across the two would resolve differently under each. `scripts/task-tool.test.mjs`
35
+ * asserts the two copies agree, because a rename on one side would otherwise fail at dispatch time with a
36
+ * message nobody reads.
37
+ */
38
+ export const TASK_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
39
+ /**
40
+ * The live capability per conversation, while that conversation's primary session is alive.
41
+ *
42
+ * Keyed by CONVERSATION rather than being one global token, so two conversations being driven at once
43
+ * cannot dispatch as each other and so releasing one session's capability cannot revoke another's. The
44
+ * value is replaced rather than accumulated: a conversation has one primary session, and rebuilding it
45
+ * supersedes the first.
46
+ */
47
+ const live = new Map();
48
+ /** A fixed capability, for tests. See `seededCapability` for why this does not weaken anything. */
49
+ const SEED = process.env.SUPER_PI_TASK_CAPABILITY_SEED;
50
+ /** Announced once, because a capability that silently stopped rotating is a security change nobody agreed to. */
51
+ let warnedSeed = false;
52
+ /**
53
+ * Mints the capability for one conversation's primary session, and returns it for the extension's
54
+ * environment.
55
+ *
56
+ * CALLED WHEN THE SESSION IS CREATED, so the value is decided before the session exists and cannot be
57
+ * changed underneath it. A session that is never created mints nothing, which is correct: there is
58
+ * nothing to hand it to.
59
+ *
60
+ * ROTATED EVERY SESSION, and that is the property the duration would not give on its own. A token valid
61
+ * for the whole server lifetime would still be a token an unrelated process could not guess - but a token
62
+ * valid only while its holder is alive is a token that stops being a credential the moment the session
63
+ * ends, so there is no window in which a leaked value is still live.
64
+ *
65
+ * WHY IT IS THE SESSION AND NOT THE TURN. The capability travels in the extension's ENVIRONMENT, and an
66
+ * extension reads its environment when it is LOADED. A session that outlives its turns loads its
67
+ * extension once, so a per-turn token would have to be re-read from an environment that cannot change -
68
+ * and the second turn of a conversation would carry the FIRST turn's token, which the server would
69
+ * (correctly) refuse. The session is therefore the unit the credential belongs to, and the server
70
+ * enforces the turn separately. The application service owns the authoritative active-turn map, and
71
+ * passes that fact to `verifyCapability` at each protected endpoint. A stolen token is therefore worth
72
+ * nothing to a caller that cannot also start a turn.
73
+ */
74
+ export function mintCapability(conversationId) {
75
+ if (SEED) {
76
+ if (!warnedSeed) {
77
+ warnedSeed = true;
78
+ console.warn(`Super Pi: SUPER_PI_TASK_CAPABILITY_SEED is set, so every dispatch capability is the same fixed value instead of being minted per session. This is for tests - set it only on a server nothing else can reach.`);
79
+ }
80
+ live.set(conversationId, SEED);
81
+ return SEED;
82
+ }
83
+ const token = randomUUID();
84
+ live.set(conversationId, token);
85
+ return token;
86
+ }
87
+ /**
88
+ * Forgets a conversation's capability, when its session ends.
89
+ *
90
+ * CALLED WHEN THE SESSION IS DESTROYED, so it runs on every exit - a session that was evicted as idle, a
91
+ * session that was thrown away by a revert, a session that was replaced because the conversation's
92
+ * configuration changed, and a session that was disposed at shutdown. A capability that outlived its
93
+ * session would keep working for a session that no longer exists, which is precisely the shape of a
94
+ * credential with no owner.
95
+ */
96
+ export function releaseCapability(conversationId) {
97
+ live.delete(conversationId);
98
+ }
99
+ /** Forgets every capability. Called on shutdown, so nothing survives the process that minted it. */
100
+ export function releaseAllCapabilities() {
101
+ live.clear();
102
+ }
103
+ /**
104
+ /**
105
+ * The capability currently valid for a conversation, or `undefined` when no primary turn is running.
106
+ *
107
+ * Exported for the endpoint's own diagnostics and for a test that needs to assert the lifecycle without
108
+ * reading a primary turn's environment. Not exported as a way to READ a conversation's capability and use
109
+ * it - a caller in this process is already inside the trust boundary it protects.
110
+ */
111
+ export function capabilityFor(conversationId) {
112
+ return live.get(conversationId);
113
+ }
114
+ /**
115
+ * Checks a presented capability against the one this conversation's turn was given.
116
+ *
117
+ * `timingSafeEqual` rather than `===`, because `===` on a token short-circuits at the first differing byte
118
+ * and turns the comparison into a timing oracle for the value itself. The length check runs first because
119
+ * `timingSafeEqual` throws on mismatched lengths rather than returning false.
120
+ *
121
+ * THE MESSAGE NAMES BOTH HALVES OF THE PROBLEM, because the reader is a model about to retry and there
122
+ * are two genuinely different failures here. A conversation with no live capability is being dispatched
123
+ * from OUTSIDE a turn - the request never came from a primary agent. A conversation with one, and the
124
+ * presented value does not match it, is a turn whose value was not carried through. An extension that
125
+ * silently omitted the header would otherwise be indistinguishable from an attacker, and would keep
126
+ * retrying forever.
127
+ */
128
+ export function verifyCapability(conversationId, presented, options = {}) {
129
+ // A seeded server accepts its fixed value for EVERY conversation, including one with no session.
130
+ // That relaxation is exactly the test affordance and nothing else: `SEED` is documented as test-only,
131
+ // and a process that can set it could set `SUPER_PI_ACCESS_TOKEN` instead and already have full control.
132
+ // The comparison below is still real - a wrong value is still refused - so a seeded server still catches
133
+ // a request that simply forgot the capability, which is the mistake a real extension is most likely to make.
134
+ const expected = live.get(conversationId) ?? SEED;
135
+ if (!expected) {
136
+ return {
137
+ ok: false,
138
+ message: `No primary session is running for conversation ${conversationId}, so there is nothing that could have dispatched this. Dispatch happens from inside a turn: send the tool call during a turn rather than posting to the server directly.`,
139
+ };
140
+ }
141
+ if (typeof presented !== "string" || !presented) {
142
+ return { ok: false, message: `This dispatch carries no ${TASK_CAPABILITY_ENV}. The capability is passed from the primary agent's own environment; a request without it did not come from one. Do not retry the same call - it is not a transient failure.` };
143
+ }
144
+ const left = Buffer.from(expected);
145
+ const right = Buffer.from(presented);
146
+ if (left.length !== right.length || !timingSafeEqual(left, right)) {
147
+ return { ok: false, message: `The ${TASK_CAPABILITY_ENV} presented does not match the one this session was given. It is minted per session, so a value from an earlier session - or from another conversation - is not accepted. Do not retry the same call.` };
148
+ }
149
+ // THE SECOND HALF. The token proves the caller holds this session's credential; this proves the
150
+ // session is actually doing something. A dispatch is accepted only while a turn is running, which is
151
+ // what a session-scoped token would otherwise have lost: the value is now good for the whole life of
152
+ // the session rather than for one turn, and a live turn is the difference between "the right
153
+ // credential" and "the right credential being used at the right time".
154
+ //
155
+ // A conversation that has a session but is idle has nothing to dispatch FOR: there is no turn, no
156
+ // model, no transcript being written. A caller presenting a valid token for an idle conversation is
157
+ // not the primary agent of a running turn - it is something replaying a value it read earlier.
158
+ //
159
+ // A SEEDED SERVER IS EXEMPT, and that is the same relaxation the seeded value itself gets: a seeded
160
+ // server already accepts its fixed token for a conversation with no session at all, and the seed is a
161
+ // documented test-only affordance. A process able to set the seed could set
162
+ // `SUPER_PI_ACCESS_TOKEN` instead and already have full control.
163
+ if (!SEED && options.running !== true) {
164
+ return {
165
+ ok: false,
166
+ message: `Conversation ${conversationId} is not running a turn, so there is no primary agent to dispatch for. Dispatch happens from inside a turn: send the tool call during a turn rather than posting to the server directly.`,
167
+ };
168
+ }
169
+ return { ok: true };
170
+ }
@@ -0,0 +1,93 @@
1
+ import type { ClientCommand, ServerEvent } from "./types.js";
2
+ import type { WorkspaceService } from "./application/workspace-service.js";
3
+ import type { ConversationService } from "./application/conversation-service.js";
4
+ import type { RunService } from "./application/run-service.js";
5
+ import type { ExtensionUiService } from "./application/extension-ui-service.js";
6
+ import type { CatalogService } from "./application/catalog-service.js";
7
+ import type { ProviderService } from "./application/provider-service.js";
8
+ import type { ScheduledTaskService } from "./application/scheduled-task-service.js";
9
+ import type { SessionOrchestratorService } from "./application/session-orchestrator-service.js";
10
+ import type { TerminalService } from "./terminal.js";
11
+ export type SocketSender = (event: ServerEvent) => void;
12
+ /**
13
+ * Routes client commands to appropriate application services and converts results or errors.
14
+ */
15
+ export declare class CommandHandler {
16
+ private readonly workspaceService;
17
+ private readonly conversationService;
18
+ private readonly runService;
19
+ private readonly extensionUiService;
20
+ private readonly catalogService;
21
+ /** Path to the Super Pi repository root, used to spawn the restart script. */
22
+ private readonly rootDir?;
23
+ /**
24
+ * The providers a person added through the settings window.
25
+ *
26
+ * Optional because the command handler is constructed by tests that do not care about providers,
27
+ * and a missing service has to say so rather than take the whole handler down.
28
+ */
29
+ private readonly providerService?;
30
+ /**
31
+ * The scheduled tasks, and the clock behind them.
32
+ *
33
+ * Optional because the handler is constructed by tests that have no clock to give it, and a missing
34
+ * service has to say so rather than take the whole handler down - the same rule `providerService`
35
+ * follows.
36
+ */
37
+ private readonly scheduledTaskService?;
38
+ private readonly sessionOrchestratorService?;
39
+ /**
40
+ * The built-in terminal service.
41
+ *
42
+ * The service still refuses commands when node-pty is unavailable or the peer is not trusted.
43
+ */
44
+ private readonly terminalService?;
45
+ constructor(workspaceService: WorkspaceService, conversationService: ConversationService, runService: RunService, extensionUiService: ExtensionUiService, catalogService: CatalogService, terminalService?: TerminalService,
46
+ /** Path to the Super Pi repository root, used to spawn the restart script. */
47
+ rootDir?: string | undefined,
48
+ /**
49
+ * The providers a person added through the settings window.
50
+ *
51
+ * Optional because the command handler is constructed by tests that do not care about providers,
52
+ * and a missing service has to say so rather than take the whole handler down.
53
+ */
54
+ providerService?: ProviderService | undefined,
55
+ /**
56
+ * The scheduled tasks, and the clock behind them.
57
+ *
58
+ * Optional because the handler is constructed by tests that have no clock to give it, and a missing
59
+ * service has to say so rather than take the whole handler down - the same rule `providerService`
60
+ * follows.
61
+ */
62
+ scheduledTaskService?: ScheduledTaskService | undefined, sessionOrchestratorService?: SessionOrchestratorService | undefined);
63
+ /**
64
+ * Processes a client command.
65
+ *
66
+ * `remoteAddress` is passed for the terminal alone. Every other command is authorised by the socket
67
+ * itself, which was already admitted at upgrade; the terminal additionally needs to know WHERE the
68
+ * connection came from, because it is the one command family whose blast radius is the whole machine
69
+ * rather than one workspace. See `TerminalService.handle`.
70
+ */
71
+ /**
72
+ * Takes the reverting claim for a conversation from the moment the command is RECEIVED.
73
+ *
74
+ * A `message.send` runs outside this socket's command queue - deliberately, so a follow-up can be
75
+ * admitted while a turn streams - so it can be handled before a queued `message.revert` has started
76
+ * cutting anything. Calling `isReverting` from the send path then answers "no" to a send that is
77
+ * racing a cut in every sense that matters, and the message lands on a transcript the model still
78
+ * reads in full. The socket layer calls this the moment it parses the revert, which is the only point
79
+ * on this side of the service that is early enough; `releaseRevert` gives the claim back when the
80
+ * command finishes, so a revert that never reaches the service cannot hold the conversation shut.
81
+ */
82
+ claimRevert(conversationId: string): void;
83
+ /** The other half of `claimRevert`. Safe to call for a conversation nothing claimed. */
84
+ releaseRevert(conversationId: string): void;
85
+ handleCommand(command: ClientCommand, sendToSocket?: SocketSender, remoteAddress?: string, browserAuthorized?: boolean): Promise<string | void>;
86
+ /**
87
+ * The scheduled-task service, or a refusal.
88
+ *
89
+ * A refusal in the client's own words rather than a crash: the panel that sent the command shows
90
+ * the message, and a handler that threw a TypeError would show nothing but a failed operation.
91
+ */
92
+ private requireScheduledTasks;
93
+ }