@draht/coding-agent 2026.7.30 → 2026.9.5-1

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 (459) hide show
  1. package/CHANGELOG.md +154 -0
  2. package/README.md +46 -2
  3. package/agents/debugger.md +12 -1
  4. package/agents/git-committer.md +1 -0
  5. package/agents/implementer.md +20 -0
  6. package/agents/investigator.md +75 -0
  7. package/agents/reviewer.md +7 -0
  8. package/agents/spec-reviewer.md +66 -0
  9. package/agents/verifier.md +4 -3
  10. package/bin/draht-tools.cjs +472 -41
  11. package/dist/agents/debugger.md +12 -1
  12. package/dist/agents/git-committer.md +1 -0
  13. package/dist/agents/implementer.md +20 -0
  14. package/dist/agents/investigator.md +75 -0
  15. package/dist/agents/reviewer.md +7 -0
  16. package/dist/agents/spec-reviewer.md +66 -0
  17. package/dist/agents/verifier.md +4 -3
  18. package/dist/cli/args.d.ts +10 -0
  19. package/dist/cli/args.d.ts.map +1 -1
  20. package/dist/cli/args.js +69 -2
  21. package/dist/cli/args.js.map +1 -1
  22. package/dist/cli/attach-mode.d.ts +61 -0
  23. package/dist/cli/attach-mode.d.ts.map +1 -1
  24. package/dist/cli/attach-mode.js +243 -5
  25. package/dist/cli/attach-mode.js.map +1 -1
  26. package/dist/cli/credential-print.d.ts +1 -1
  27. package/dist/cli/credential-print.d.ts.map +1 -1
  28. package/dist/cli/credential-print.js +5 -4
  29. package/dist/cli/credential-print.js.map +1 -1
  30. package/dist/config.d.ts +9 -0
  31. package/dist/config.d.ts.map +1 -1
  32. package/dist/config.js +31 -4
  33. package/dist/config.js.map +1 -1
  34. package/dist/core/agent-session-runtime.d.ts +17 -1
  35. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  36. package/dist/core/agent-session-runtime.js +87 -30
  37. package/dist/core/agent-session-runtime.js.map +1 -1
  38. package/dist/core/agent-session-services.d.ts +1 -1
  39. package/dist/core/agent-session-services.d.ts.map +1 -1
  40. package/dist/core/agent-session-services.js +1 -0
  41. package/dist/core/agent-session-services.js.map +1 -1
  42. package/dist/core/agent-session.d.ts +35 -16
  43. package/dist/core/agent-session.d.ts.map +1 -1
  44. package/dist/core/agent-session.js +149 -64
  45. package/dist/core/agent-session.js.map +1 -1
  46. package/dist/core/auth-storage.d.ts +5 -1
  47. package/dist/core/auth-storage.d.ts.map +1 -1
  48. package/dist/core/auth-storage.js +72 -15
  49. package/dist/core/auth-storage.js.map +1 -1
  50. package/dist/core/builtins/checkpoints.d.ts +20 -0
  51. package/dist/core/builtins/checkpoints.d.ts.map +1 -0
  52. package/dist/core/builtins/checkpoints.js +161 -0
  53. package/dist/core/builtins/checkpoints.js.map +1 -0
  54. package/dist/core/builtins/duet.d.ts +26 -0
  55. package/dist/core/builtins/duet.d.ts.map +1 -0
  56. package/dist/core/builtins/duet.js +660 -0
  57. package/dist/core/builtins/duet.js.map +1 -0
  58. package/dist/core/builtins/index.d.ts.map +1 -1
  59. package/dist/core/builtins/index.js +7 -1
  60. package/dist/core/builtins/index.js.map +1 -1
  61. package/dist/core/builtins/subagent.d.ts +24 -4
  62. package/dist/core/builtins/subagent.d.ts.map +1 -1
  63. package/dist/core/builtins/subagent.js +278 -35
  64. package/dist/core/builtins/subagent.js.map +1 -1
  65. package/dist/core/checkpoints/checkpoint-cli.d.ts +17 -0
  66. package/dist/core/checkpoints/checkpoint-cli.d.ts.map +1 -0
  67. package/dist/core/checkpoints/checkpoint-cli.js +78 -0
  68. package/dist/core/checkpoints/checkpoint-cli.js.map +1 -0
  69. package/dist/core/checkpoints/checkpoint-manager.d.ts +294 -0
  70. package/dist/core/checkpoints/checkpoint-manager.d.ts.map +1 -0
  71. package/dist/core/checkpoints/checkpoint-manager.js +865 -0
  72. package/dist/core/checkpoints/checkpoint-manager.js.map +1 -0
  73. package/dist/core/checkpoints/rewind.d.ts +141 -0
  74. package/dist/core/checkpoints/rewind.d.ts.map +1 -0
  75. package/dist/core/checkpoints/rewind.js +246 -0
  76. package/dist/core/checkpoints/rewind.js.map +1 -0
  77. package/dist/core/compaction/branch-summarization.d.ts +1 -1
  78. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  79. package/dist/core/compaction/branch-summarization.js +9 -4
  80. package/dist/core/compaction/branch-summarization.js.map +1 -1
  81. package/dist/core/compaction/compaction.d.ts +5 -0
  82. package/dist/core/compaction/compaction.d.ts.map +1 -1
  83. package/dist/core/compaction/compaction.js +25 -4
  84. package/dist/core/compaction/compaction.js.map +1 -1
  85. package/dist/core/extensions/index.d.ts +1 -1
  86. package/dist/core/extensions/index.d.ts.map +1 -1
  87. package/dist/core/extensions/index.js.map +1 -1
  88. package/dist/core/extensions/loader.d.ts.map +1 -1
  89. package/dist/core/extensions/loader.js +83 -20
  90. package/dist/core/extensions/loader.js.map +1 -1
  91. package/dist/core/extensions/runner.d.ts +13 -2
  92. package/dist/core/extensions/runner.d.ts.map +1 -1
  93. package/dist/core/extensions/runner.js +37 -2
  94. package/dist/core/extensions/runner.js.map +1 -1
  95. package/dist/core/extensions/types.d.ts +189 -6
  96. package/dist/core/extensions/types.d.ts.map +1 -1
  97. package/dist/core/extensions/types.js.map +1 -1
  98. package/dist/core/http-dispatcher.d.ts.map +1 -1
  99. package/dist/core/http-dispatcher.js +7 -0
  100. package/dist/core/http-dispatcher.js.map +1 -1
  101. package/dist/core/index.d.ts +1 -1
  102. package/dist/core/index.d.ts.map +1 -1
  103. package/dist/core/index.js.map +1 -1
  104. package/dist/core/keybindings.d.ts +5 -0
  105. package/dist/core/keybindings.d.ts.map +1 -1
  106. package/dist/core/keybindings.js +1 -0
  107. package/dist/core/keybindings.js.map +1 -1
  108. package/dist/core/model-registry.d.ts +3 -2
  109. package/dist/core/model-registry.d.ts.map +1 -1
  110. package/dist/core/model-registry.js +8 -8
  111. package/dist/core/model-registry.js.map +1 -1
  112. package/dist/core/model-resolver.d.ts.map +1 -1
  113. package/dist/core/model-resolver.js +34 -7
  114. package/dist/core/model-resolver.js.map +1 -1
  115. package/dist/core/model-runtime.d.ts +7 -1
  116. package/dist/core/model-runtime.d.ts.map +1 -1
  117. package/dist/core/model-runtime.js +30 -10
  118. package/dist/core/model-runtime.js.map +1 -1
  119. package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
  120. package/dist/core/multi-agent/permission-gate.js +4 -3
  121. package/dist/core/multi-agent/permission-gate.js.map +1 -1
  122. package/dist/core/multi-agent/worktree.d.ts +2 -0
  123. package/dist/core/multi-agent/worktree.d.ts.map +1 -1
  124. package/dist/core/multi-agent/worktree.js +2 -2
  125. package/dist/core/multi-agent/worktree.js.map +1 -1
  126. package/dist/core/package-manager.d.ts +7 -1
  127. package/dist/core/package-manager.d.ts.map +1 -1
  128. package/dist/core/package-manager.js +21 -44
  129. package/dist/core/package-manager.js.map +1 -1
  130. package/dist/core/permission-relay/index.d.ts +19 -0
  131. package/dist/core/permission-relay/index.d.ts.map +1 -0
  132. package/dist/core/permission-relay/index.js +49 -0
  133. package/dist/core/permission-relay/index.js.map +1 -0
  134. package/dist/core/permission-relay/relay-ui-context.d.ts +39 -0
  135. package/dist/core/permission-relay/relay-ui-context.d.ts.map +1 -0
  136. package/dist/core/permission-relay/relay-ui-context.js +788 -0
  137. package/dist/core/permission-relay/relay-ui-context.js.map +1 -0
  138. package/dist/core/permission-relay/types.d.ts +222 -0
  139. package/dist/core/permission-relay/types.d.ts.map +1 -0
  140. package/dist/core/permission-relay/types.js +15 -0
  141. package/dist/core/permission-relay/types.js.map +1 -0
  142. package/dist/core/pi-manifest.d.ts +14 -0
  143. package/dist/core/pi-manifest.d.ts.map +1 -0
  144. package/dist/core/pi-manifest.js +35 -0
  145. package/dist/core/pi-manifest.js.map +1 -0
  146. package/dist/core/project-trust.js +2 -2
  147. package/dist/core/project-trust.js.map +1 -1
  148. package/dist/core/resource-loader.d.ts +21 -0
  149. package/dist/core/resource-loader.d.ts.map +1 -1
  150. package/dist/core/resource-loader.js +101 -24
  151. package/dist/core/resource-loader.js.map +1 -1
  152. package/dist/core/sandbox/bash-operations.d.ts +149 -0
  153. package/dist/core/sandbox/bash-operations.d.ts.map +1 -0
  154. package/dist/core/sandbox/bash-operations.js +163 -0
  155. package/dist/core/sandbox/bash-operations.js.map +1 -0
  156. package/dist/core/sandbox/env.d.ts +83 -0
  157. package/dist/core/sandbox/env.d.ts.map +1 -0
  158. package/dist/core/sandbox/env.js +123 -0
  159. package/dist/core/sandbox/env.js.map +1 -0
  160. package/dist/core/sandbox/executor.d.ts +104 -0
  161. package/dist/core/sandbox/executor.d.ts.map +1 -0
  162. package/dist/core/sandbox/executor.js +92 -0
  163. package/dist/core/sandbox/executor.js.map +1 -0
  164. package/dist/core/sandbox/index.d.ts +36 -0
  165. package/dist/core/sandbox/index.d.ts.map +1 -0
  166. package/dist/core/sandbox/index.js +36 -0
  167. package/dist/core/sandbox/index.js.map +1 -0
  168. package/dist/core/sandbox/linux.d.ts +121 -0
  169. package/dist/core/sandbox/linux.d.ts.map +1 -0
  170. package/dist/core/sandbox/linux.js +260 -0
  171. package/dist/core/sandbox/linux.js.map +1 -0
  172. package/dist/core/sandbox/policy.d.ts +142 -0
  173. package/dist/core/sandbox/policy.d.ts.map +1 -0
  174. package/dist/core/sandbox/policy.js +297 -0
  175. package/dist/core/sandbox/policy.js.map +1 -0
  176. package/dist/core/sandbox/real-path.d.ts +112 -0
  177. package/dist/core/sandbox/real-path.d.ts.map +1 -0
  178. package/dist/core/sandbox/real-path.js +158 -0
  179. package/dist/core/sandbox/real-path.js.map +1 -0
  180. package/dist/core/sandbox/seatbelt-profile.d.ts +95 -0
  181. package/dist/core/sandbox/seatbelt-profile.d.ts.map +1 -0
  182. package/dist/core/sandbox/seatbelt-profile.js +239 -0
  183. package/dist/core/sandbox/seatbelt-profile.js.map +1 -0
  184. package/dist/core/sandbox/seatbelt.d.ts +95 -0
  185. package/dist/core/sandbox/seatbelt.d.ts.map +1 -0
  186. package/dist/core/sandbox/seatbelt.js +154 -0
  187. package/dist/core/sandbox/seatbelt.js.map +1 -0
  188. package/dist/core/sandbox/self-test.d.ts +109 -0
  189. package/dist/core/sandbox/self-test.d.ts.map +1 -0
  190. package/dist/core/sandbox/self-test.js +369 -0
  191. package/dist/core/sandbox/self-test.js.map +1 -0
  192. package/dist/core/sandbox/spawn.d.ts +33 -0
  193. package/dist/core/sandbox/spawn.d.ts.map +1 -0
  194. package/dist/core/sandbox/spawn.js +87 -0
  195. package/dist/core/sandbox/spawn.js.map +1 -0
  196. package/dist/core/sdk.d.ts.map +1 -1
  197. package/dist/core/sdk.js +3 -1
  198. package/dist/core/sdk.js.map +1 -1
  199. package/dist/core/session-manager.d.ts +60 -1
  200. package/dist/core/session-manager.d.ts.map +1 -1
  201. package/dist/core/session-manager.js +53 -6
  202. package/dist/core/session-manager.js.map +1 -1
  203. package/dist/core/settings-manager.d.ts +21 -0
  204. package/dist/core/settings-manager.d.ts.map +1 -1
  205. package/dist/core/settings-manager.js +36 -16
  206. package/dist/core/settings-manager.js.map +1 -1
  207. package/dist/core/skills.d.ts +3 -1
  208. package/dist/core/skills.d.ts.map +1 -1
  209. package/dist/core/skills.js +19 -6
  210. package/dist/core/skills.js.map +1 -1
  211. package/dist/core/slash-commands.d.ts.map +1 -1
  212. package/dist/core/slash-commands.js +1 -0
  213. package/dist/core/slash-commands.js.map +1 -1
  214. package/dist/core/soak/soak-log.d.ts +298 -0
  215. package/dist/core/soak/soak-log.d.ts.map +1 -0
  216. package/dist/core/soak/soak-log.js +660 -0
  217. package/dist/core/soak/soak-log.js.map +1 -0
  218. package/dist/core/soak/soak-reader.d.ts +60 -0
  219. package/dist/core/soak/soak-reader.d.ts.map +1 -0
  220. package/dist/core/soak/soak-reader.js +106 -0
  221. package/dist/core/soak/soak-reader.js.map +1 -0
  222. package/dist/core/socket-server/discovery.d.ts +78 -1
  223. package/dist/core/socket-server/discovery.d.ts.map +1 -1
  224. package/dist/core/socket-server/discovery.js +356 -37
  225. package/dist/core/socket-server/discovery.js.map +1 -1
  226. package/dist/core/socket-server/index.d.ts +10 -4
  227. package/dist/core/socket-server/index.d.ts.map +1 -1
  228. package/dist/core/socket-server/index.js +6 -3
  229. package/dist/core/socket-server/index.js.map +1 -1
  230. package/dist/core/socket-server/permission-delivery.d.ts +125 -0
  231. package/dist/core/socket-server/permission-delivery.d.ts.map +1 -0
  232. package/dist/core/socket-server/permission-delivery.js +152 -0
  233. package/dist/core/socket-server/permission-delivery.js.map +1 -0
  234. package/dist/core/socket-server/permission-registry.d.ts +301 -0
  235. package/dist/core/socket-server/permission-registry.d.ts.map +1 -0
  236. package/dist/core/socket-server/permission-registry.js +410 -0
  237. package/dist/core/socket-server/permission-registry.js.map +1 -0
  238. package/dist/core/socket-server/permission-relay.d.ts +81 -0
  239. package/dist/core/socket-server/permission-relay.d.ts.map +1 -0
  240. package/dist/core/socket-server/permission-relay.js +528 -0
  241. package/dist/core/socket-server/permission-relay.js.map +1 -0
  242. package/dist/core/socket-server/safe-text.d.ts +83 -0
  243. package/dist/core/socket-server/safe-text.d.ts.map +1 -0
  244. package/dist/core/socket-server/safe-text.js +277 -0
  245. package/dist/core/socket-server/safe-text.js.map +1 -0
  246. package/dist/core/socket-server/session-integration.d.ts +65 -2
  247. package/dist/core/socket-server/session-integration.d.ts.map +1 -1
  248. package/dist/core/socket-server/session-integration.js +434 -32
  249. package/dist/core/socket-server/session-integration.js.map +1 -1
  250. package/dist/core/socket-server/socket-client.d.ts +21 -2
  251. package/dist/core/socket-server/socket-client.d.ts.map +1 -1
  252. package/dist/core/socket-server/socket-client.js +52 -1
  253. package/dist/core/socket-server/socket-client.js.map +1 -1
  254. package/dist/core/socket-server/socket-server.d.ts +152 -1
  255. package/dist/core/socket-server/socket-server.d.ts.map +1 -1
  256. package/dist/core/socket-server/socket-server.js +775 -26
  257. package/dist/core/socket-server/socket-server.js.map +1 -1
  258. package/dist/core/socket-server/types.d.ts +106 -2
  259. package/dist/core/socket-server/types.d.ts.map +1 -1
  260. package/dist/core/socket-server/types.js +13 -1
  261. package/dist/core/socket-server/types.js.map +1 -1
  262. package/dist/core/system-prompt.d.ts.map +1 -1
  263. package/dist/core/system-prompt.js +8 -9
  264. package/dist/core/system-prompt.js.map +1 -1
  265. package/dist/core/tools/bash.d.ts +1 -1
  266. package/dist/core/tools/bash.d.ts.map +1 -1
  267. package/dist/core/tools/bash.js +5 -2
  268. package/dist/core/tools/bash.js.map +1 -1
  269. package/dist/core/tools/edit.d.ts.map +1 -1
  270. package/dist/core/tools/edit.js +17 -2
  271. package/dist/core/tools/edit.js.map +1 -1
  272. package/dist/core/tools/find.d.ts +3 -0
  273. package/dist/core/tools/find.d.ts.map +1 -1
  274. package/dist/core/tools/find.js +11 -18
  275. package/dist/core/tools/find.js.map +1 -1
  276. package/dist/core/trust-manager.d.ts +6 -4
  277. package/dist/core/trust-manager.d.ts.map +1 -1
  278. package/dist/core/trust-manager.js +55 -21
  279. package/dist/core/trust-manager.js.map +1 -1
  280. package/dist/extensions/index.d.ts.map +1 -1
  281. package/dist/extensions/index.js +5 -1
  282. package/dist/extensions/index.js.map +1 -1
  283. package/dist/extensions/llama/provider.d.ts.map +1 -1
  284. package/dist/extensions/llama/provider.js +5 -1
  285. package/dist/extensions/llama/provider.js.map +1 -1
  286. package/dist/extensions/stub-provider/index.d.ts +9 -0
  287. package/dist/extensions/stub-provider/index.d.ts.map +1 -0
  288. package/dist/extensions/stub-provider/index.js +13 -0
  289. package/dist/extensions/stub-provider/index.js.map +1 -0
  290. package/dist/extensions/stub-provider/provider.d.ts +77 -0
  291. package/dist/extensions/stub-provider/provider.d.ts.map +1 -0
  292. package/dist/extensions/stub-provider/provider.js +193 -0
  293. package/dist/extensions/stub-provider/provider.js.map +1 -0
  294. package/dist/hooks/gsd/draht-quality-gate.js +3 -3
  295. package/dist/index.d.ts +1 -1
  296. package/dist/index.d.ts.map +1 -1
  297. package/dist/index.js.map +1 -1
  298. package/dist/main.d.ts.map +1 -1
  299. package/dist/main.js +242 -45
  300. package/dist/main.js.map +1 -1
  301. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  302. package/dist/modes/interactive/components/config-selector.js +3 -2
  303. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  304. package/dist/modes/interactive/components/extension-selector.d.ts +49 -0
  305. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  306. package/dist/modes/interactive/components/extension-selector.js +202 -5
  307. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  308. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  309. package/dist/modes/interactive/components/session-selector.js +10 -2
  310. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  311. package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
  312. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  313. package/dist/modes/interactive/components/settings-selector.js +10 -0
  314. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  315. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  316. package/dist/modes/interactive/components/tool-execution.js +10 -1
  317. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  318. package/dist/modes/interactive/components/tree-selector.d.ts +20 -2
  319. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  320. package/dist/modes/interactive/components/tree-selector.js +21 -5
  321. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  322. package/dist/modes/interactive/interactive-mode.d.ts +97 -3
  323. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  324. package/dist/modes/interactive/interactive-mode.js +394 -24
  325. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  326. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  327. package/dist/modes/rpc/rpc-mode.js +165 -7
  328. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  329. package/dist/modes/rpc/rpc-types.d.ts +68 -1
  330. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  331. package/dist/modes/rpc/rpc-types.js.map +1 -1
  332. package/dist/prompts/commands/atomic-commit.md +1 -12
  333. package/dist/prompts/commands/brainstorm.md +12 -15
  334. package/dist/prompts/commands/create-verification-skill.md +108 -0
  335. package/dist/prompts/commands/discuss-phase.md +3 -14
  336. package/dist/prompts/commands/execute-phase.md +3 -11
  337. package/dist/prompts/commands/fix.md +41 -18
  338. package/dist/prompts/commands/grill.md +66 -0
  339. package/dist/prompts/commands/init-project.md +5 -15
  340. package/dist/prompts/commands/map-codebase.md +1 -13
  341. package/dist/prompts/commands/new-project.md +5 -15
  342. package/dist/prompts/commands/next-milestone.md +1 -13
  343. package/dist/prompts/commands/orchestrate.md +1 -1
  344. package/dist/prompts/commands/pause-work.md +1 -13
  345. package/dist/prompts/commands/plan-phase.md +2 -11
  346. package/dist/prompts/commands/progress.md +0 -13
  347. package/dist/prompts/commands/quick.md +3 -11
  348. package/dist/prompts/commands/resolve-conflicts.md +71 -0
  349. package/dist/prompts/commands/resume-work.md +0 -13
  350. package/dist/prompts/commands/review.md +4 -13
  351. package/dist/prompts/commands/triage.md +159 -0
  352. package/dist/prompts/commands/verify-work.md +4 -14
  353. package/dist/prompts/commands/why.md +135 -0
  354. package/dist/skills/atomic-reasoning/SKILL.md +115 -0
  355. package/dist/skills/blast-radius/SKILL.md +55 -0
  356. package/dist/skills/epistemics/SKILL.md +99 -0
  357. package/dist/skills/hexagon-animation/SKILL.md +49 -0
  358. package/dist/skills/hexagon-animation/generate.mjs +81 -0
  359. package/dist/skills/hexagon-animation/template.html +361 -0
  360. package/dist/skills/typescript-discipline/SKILL.md +50 -0
  361. package/dist/skills/typescript-discipline/references/patterns.md +294 -0
  362. package/dist/skills/unslop/SKILL.md +101 -0
  363. package/dist/utils/canonical-path.d.ts +28 -0
  364. package/dist/utils/canonical-path.d.ts.map +1 -0
  365. package/dist/utils/canonical-path.js +90 -0
  366. package/dist/utils/canonical-path.js.map +1 -0
  367. package/dist/utils/child-process.d.ts +12 -1
  368. package/dist/utils/child-process.d.ts.map +1 -1
  369. package/dist/utils/child-process.js +25 -8
  370. package/dist/utils/child-process.js.map +1 -1
  371. package/dist/utils/clipboard.d.ts +1 -1
  372. package/dist/utils/clipboard.d.ts.map +1 -1
  373. package/dist/utils/clipboard.js +22 -2
  374. package/dist/utils/clipboard.js.map +1 -1
  375. package/dist/utils/exif-orientation.d.ts.map +1 -1
  376. package/dist/utils/exif-orientation.js +2 -3
  377. package/dist/utils/exif-orientation.js.map +1 -1
  378. package/dist/utils/paths.d.ts +2 -7
  379. package/dist/utils/paths.d.ts.map +1 -1
  380. package/dist/utils/paths.js +13 -15
  381. package/dist/utils/paths.js.map +1 -1
  382. package/dist/utils/shell.d.ts.map +1 -1
  383. package/dist/utils/shell.js +6 -4
  384. package/dist/utils/shell.js.map +1 -1
  385. package/dist/utils/tools-manager.d.ts.map +1 -1
  386. package/dist/utils/tools-manager.js +3 -5
  387. package/dist/utils/tools-manager.js.map +1 -1
  388. package/docs/attachable-sessions.md +79 -0
  389. package/docs/compaction.md +21 -21
  390. package/docs/containerization.md +23 -23
  391. package/docs/custom-provider.md +16 -16
  392. package/docs/development.md +9 -9
  393. package/docs/docs.json +6 -2
  394. package/docs/duet.md +42 -0
  395. package/docs/extensions.md +58 -58
  396. package/docs/index.md +10 -10
  397. package/docs/json.md +7 -7
  398. package/docs/keybindings.md +6 -5
  399. package/docs/llama-cpp.md +6 -6
  400. package/docs/models.md +6 -6
  401. package/docs/packages.md +43 -43
  402. package/docs/prompt-templates.md +4 -4
  403. package/docs/providers.md +12 -12
  404. package/docs/quickstart.md +32 -32
  405. package/docs/rpc.md +83 -12
  406. package/docs/sdk.md +15 -15
  407. package/docs/security.md +18 -18
  408. package/docs/session-format.md +35 -13
  409. package/docs/sessions.md +17 -14
  410. package/docs/settings.md +25 -18
  411. package/docs/shell-aliases.md +2 -2
  412. package/docs/skills.md +12 -11
  413. package/docs/terminal-setup.md +12 -12
  414. package/docs/termux.md +6 -6
  415. package/docs/themes.md +11 -11
  416. package/docs/tmux.md +4 -4
  417. package/docs/tui.md +5 -5
  418. package/docs/usage.md +50 -50
  419. package/docs/windows.md +2 -2
  420. package/examples/extensions/overlay-qa-tests.ts +3 -3
  421. package/hooks/gsd/draht-quality-gate.js +3 -3
  422. package/package.json +11 -10
  423. package/prompts/commands/atomic-commit.md +1 -12
  424. package/prompts/commands/brainstorm.md +12 -15
  425. package/prompts/commands/create-verification-skill.md +108 -0
  426. package/prompts/commands/discuss-phase.md +3 -14
  427. package/prompts/commands/execute-phase.md +3 -11
  428. package/prompts/commands/fix.md +41 -18
  429. package/prompts/commands/grill.md +66 -0
  430. package/prompts/commands/init-project.md +5 -15
  431. package/prompts/commands/map-codebase.md +1 -13
  432. package/prompts/commands/new-project.md +5 -15
  433. package/prompts/commands/next-milestone.md +1 -13
  434. package/prompts/commands/orchestrate.md +1 -1
  435. package/prompts/commands/pause-work.md +1 -13
  436. package/prompts/commands/plan-phase.md +2 -11
  437. package/prompts/commands/progress.md +0 -13
  438. package/prompts/commands/quick.md +3 -11
  439. package/prompts/commands/resolve-conflicts.md +71 -0
  440. package/prompts/commands/resume-work.md +0 -13
  441. package/prompts/commands/review.md +4 -13
  442. package/prompts/commands/triage.md +159 -0
  443. package/prompts/commands/verify-work.md +4 -14
  444. package/prompts/commands/why.md +135 -0
  445. package/skills/atomic-reasoning/SKILL.md +115 -0
  446. package/skills/blast-radius/SKILL.md +55 -0
  447. package/skills/epistemics/SKILL.md +99 -0
  448. package/skills/hexagon-animation/SKILL.md +49 -0
  449. package/skills/hexagon-animation/generate.mjs +81 -0
  450. package/skills/hexagon-animation/template.html +361 -0
  451. package/skills/typescript-discipline/SKILL.md +50 -0
  452. package/skills/typescript-discipline/references/patterns.md +294 -0
  453. package/skills/unslop/SKILL.md +101 -0
  454. package/dist/prompts/agents/build.md +0 -86
  455. package/dist/prompts/agents/plan.md +0 -79
  456. package/dist/prompts/agents/verify.md +0 -69
  457. package/prompts/agents/build.md +0 -86
  458. package/prompts/agents/plan.md +0 -79
  459. package/prompts/agents/verify.md +0 -69
@@ -0,0 +1,125 @@
1
+ /**
2
+ * permission-delivery — per-connection bookkeeping for asks that have been SHOWN to a client.
3
+ *
4
+ * THIS IS NOT STATE ABOUT THE ASK. It is state about a connection, and keeping the two apart is
5
+ * the whole reason this is a separate module rather than a field on the registry entry.
6
+ *
7
+ * The defect it exists to make unrepresentable: if delivering an ask (or acknowledging one)
8
+ * consumed it, a client that was shown the ask and then died would take it with it — the entry
9
+ * gone, no other surface ever told, and the agent still parked in `beforeToolCall` waiting for an
10
+ * answer that can no longer be given. Delivery is therefore idempotent and NEVER a state
11
+ * transition: an ask stays PENDING until somebody ANSWERS it, it expires, or it is cancelled.
12
+ *
13
+ * What it buys instead is "exactly once per connection": a client that attaches after an ask was
14
+ * raised is shown it once, on attach, right after `session_metadata` — and is not shown it again
15
+ * on every subsequent broadcast. When that client disconnects its record is dropped, so a
16
+ * reconnecting client (same id, new connection) is shown every still-pending ask again. It has to
17
+ * be: it may be a fresh process that has never seen any of them.
18
+ *
19
+ * WHAT "EXACTLY ONCE" MEANS HERE, PRECISELY, BECAUSE THE PHRASE IS OTHERWISE A PROMISE THIS WIRE
20
+ * CANNOT KEEP (R34-PERM.6). It means two things and no others:
21
+ *
22
+ * 1. EXACTLY ONE AUTHORITATIVE RESOLUTION per request. That is the registry's synchronous
23
+ * compare-and-swap in `permission-registry.ts`, not this file's business at all: however many
24
+ * copies of an ask were shown, however many answers come back, one of them settles it and
25
+ * every later one is refused with a tombstone.
26
+ * 2. EXACTLY ONE REPLAY per (reconnect, still-pending request). That is this file: one send per
27
+ * connection per ask, deduplicated CLIENT-SIDE by `requestId` — a renderer that already has a
28
+ * dialog open for an id must update it rather than open a second one.
29
+ *
30
+ * TRUE END-TO-END EXACTLY-ONCE IS IMPOSSIBLE OVER THIS TRANSPORT AND MUST NOT BE ATTEMPTED. A
31
+ * frame written to a socket that then dies may or may not have been rendered, and no acknowledgement
32
+ * can close that gap: an ack that arrives says the ask was seen, an ack that never arrives says
33
+ * nothing at all. The only two safe designs are "deliver at least once and dedupe by id" (this one)
34
+ * and "deliver at most once", which loses asks. Anything that tried to make delivery authoritative
35
+ * would have to make it a state transition — and that is precisely the wedge above.
36
+ */
37
+ /** The least this module needs to know about an ask. The registry's entry satisfies it. */
38
+ export interface DeliverableAsk {
39
+ readonly requestId: string;
40
+ /**
41
+ * Encoded size of the frame this ask will be replayed as, in bytes, when the ask knows it.
42
+ *
43
+ * `PermissionEntry` counts it once at insert and carries it, so in production it is always
44
+ * there. It is optional because this module's contract is "the least it needs to know", and an
45
+ * ask that does not state its size is bounded by the COUNT cap alone — see
46
+ * {@link PermissionDeliveryOptions.maxReplayBytes}.
47
+ */
48
+ readonly bytes?: number;
49
+ }
50
+ export interface PermissionDeliveryOptions<T extends DeliverableAsk> {
51
+ /** Live view of what is still pending. Called on every replay; never cached. */
52
+ pending: () => readonly T[];
53
+ /** How many client records to keep. Beyond this, the least recently touched is dropped. */
54
+ maxClients?: number;
55
+ /** How many delivered ids to remember per client. */
56
+ maxPerClient?: number;
57
+ /**
58
+ * How many still-pending asks one attach may push at a client.
59
+ *
60
+ * The replay burst is the one place where a single client action — attaching — makes the
61
+ * server write an unbounded amount at it. Without a cap, a session sitting at the registry's
62
+ * pending limit hands every reconnecting phone the whole backlog in one loop.
63
+ */
64
+ maxReplayAsks?: number;
65
+ /**
66
+ * Total encoded bytes one attach may push at a client.
67
+ *
68
+ * The count cap alone is not a byte bound: an ask may legitimately carry a 60 KB command, so
69
+ * "at most 16 of them" is still nearly a megabyte. Both caps apply, whichever binds first.
70
+ */
71
+ maxReplayBytes?: number;
72
+ }
73
+ /** Client records kept at once. Well above the socket server's own `maxClients` of 10. */
74
+ export declare const DEFAULT_MAX_DELIVERY_CLIENTS = 64;
75
+ /** Delivered ids remembered per client. Above the registry's pending bound, so it never binds first. */
76
+ export declare const DEFAULT_MAX_DELIVERED_PER_CLIENT = 256;
77
+ /**
78
+ * Pending asks pushed on ONE attach. Half the registry's own pending bound.
79
+ *
80
+ * It is a BACKSTOP, not a queue. Nothing is dropped when it binds: the asks it did not send are
81
+ * still pending, still answerable, and still counted down by the one clock. They are simply not
82
+ * written in the same burst as everything else the newly attached client is being sent.
83
+ *
84
+ * Oldest first, because insertion order is deadline order — the ask closest to expiring is the one
85
+ * a human has least time left to answer.
86
+ */
87
+ export declare const DEFAULT_MAX_REPLAY_ASKS = 16;
88
+ /**
89
+ * Total encoded bytes pushed on ONE attach: 256 KiB.
90
+ *
91
+ * Four full-sized asks at the registry's 60 KB per-entry ceiling, which is the realistic worst
92
+ * case, and far above the few hundred bytes a real tool-permission frame occupies.
93
+ */
94
+ export declare const DEFAULT_MAX_REPLAY_BYTES: number;
95
+ export declare class PermissionDelivery<T extends DeliverableAsk = DeliverableAsk> {
96
+ #private;
97
+ constructor(options: PermissionDeliveryOptions<T>);
98
+ /** Record that `clientId` has been sent `requestId`. Idempotent, and never a state transition. */
99
+ markDelivered(clientId: string, requestId: string): void;
100
+ hasDelivered(clientId: string, requestId: string): boolean;
101
+ /**
102
+ * The still-pending asks this client has not been shown on this connection — BOUNDED.
103
+ *
104
+ * Read straight off the registry each time: an ask that was answered while the client was
105
+ * connecting is no longer pending and must not be replayed as if it still needed an answer.
106
+ *
107
+ * Both caps are applied here rather than at the call site so that no caller can replay an
108
+ * unbounded burst by accident. Truncating is NOT dropping: an ask left out of this list is
109
+ * untouched, still PENDING, and still the only thing that can end it is an answer, the clock,
110
+ * or a cancellation. Nothing about being unsent is a decision.
111
+ */
112
+ pendingFor(clientId: string): T[];
113
+ /**
114
+ * Forget everything about a client, because its connection ended.
115
+ *
116
+ * A client that reconnects under the same id is a NEW connection with nothing on its screen,
117
+ * so it must be shown every pending ask again. Remembering across the gap would leave a phone
118
+ * that dropped its WebSocket staring at a session whose ask it can no longer see or answer.
119
+ */
120
+ forgetClient(clientId: string): void;
121
+ /** Drop an ask from every client's record, because it is over. */
122
+ forgetRequest(requestId: string): void;
123
+ clear(): void;
124
+ }
125
+ //# sourceMappingURL=permission-delivery.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"permission-delivery.d.ts","sourceRoot":"","sources":["../../../src/core/socket-server/permission-delivery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC,SAAS,cAAc;IAClE,gFAAgF;IAChF,OAAO,EAAE,MAAM,SAAS,CAAC,EAAE,CAAC;IAC5B,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0FAA0F;AAC1F,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAE/C,wGAAwG;AACxG,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAEnD,qBAAa,kBAAkB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc;;IASxE,YAAY,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,EAMhD;IAED,kGAAkG;IAClG,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAavD;IAED,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAEzD;IAED;;;;;;;;;;OAUG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,EAAE,CAmBhC;IAED;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEnC;IAED,kEAAkE;IAClE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAErC;IAED,KAAK,IAAI,IAAI,CAEZ;CASD"}
@@ -0,0 +1,152 @@
1
+ /**
2
+ * permission-delivery — per-connection bookkeeping for asks that have been SHOWN to a client.
3
+ *
4
+ * THIS IS NOT STATE ABOUT THE ASK. It is state about a connection, and keeping the two apart is
5
+ * the whole reason this is a separate module rather than a field on the registry entry.
6
+ *
7
+ * The defect it exists to make unrepresentable: if delivering an ask (or acknowledging one)
8
+ * consumed it, a client that was shown the ask and then died would take it with it — the entry
9
+ * gone, no other surface ever told, and the agent still parked in `beforeToolCall` waiting for an
10
+ * answer that can no longer be given. Delivery is therefore idempotent and NEVER a state
11
+ * transition: an ask stays PENDING until somebody ANSWERS it, it expires, or it is cancelled.
12
+ *
13
+ * What it buys instead is "exactly once per connection": a client that attaches after an ask was
14
+ * raised is shown it once, on attach, right after `session_metadata` — and is not shown it again
15
+ * on every subsequent broadcast. When that client disconnects its record is dropped, so a
16
+ * reconnecting client (same id, new connection) is shown every still-pending ask again. It has to
17
+ * be: it may be a fresh process that has never seen any of them.
18
+ *
19
+ * WHAT "EXACTLY ONCE" MEANS HERE, PRECISELY, BECAUSE THE PHRASE IS OTHERWISE A PROMISE THIS WIRE
20
+ * CANNOT KEEP (R34-PERM.6). It means two things and no others:
21
+ *
22
+ * 1. EXACTLY ONE AUTHORITATIVE RESOLUTION per request. That is the registry's synchronous
23
+ * compare-and-swap in `permission-registry.ts`, not this file's business at all: however many
24
+ * copies of an ask were shown, however many answers come back, one of them settles it and
25
+ * every later one is refused with a tombstone.
26
+ * 2. EXACTLY ONE REPLAY per (reconnect, still-pending request). That is this file: one send per
27
+ * connection per ask, deduplicated CLIENT-SIDE by `requestId` — a renderer that already has a
28
+ * dialog open for an id must update it rather than open a second one.
29
+ *
30
+ * TRUE END-TO-END EXACTLY-ONCE IS IMPOSSIBLE OVER THIS TRANSPORT AND MUST NOT BE ATTEMPTED. A
31
+ * frame written to a socket that then dies may or may not have been rendered, and no acknowledgement
32
+ * can close that gap: an ack that arrives says the ask was seen, an ack that never arrives says
33
+ * nothing at all. The only two safe designs are "deliver at least once and dedupe by id" (this one)
34
+ * and "deliver at most once", which loses asks. Anything that tried to make delivery authoritative
35
+ * would have to make it a state transition — and that is precisely the wedge above.
36
+ */
37
+ /** Client records kept at once. Well above the socket server's own `maxClients` of 10. */
38
+ export const DEFAULT_MAX_DELIVERY_CLIENTS = 64;
39
+ /** Delivered ids remembered per client. Above the registry's pending bound, so it never binds first. */
40
+ export const DEFAULT_MAX_DELIVERED_PER_CLIENT = 256;
41
+ /**
42
+ * Pending asks pushed on ONE attach. Half the registry's own pending bound.
43
+ *
44
+ * It is a BACKSTOP, not a queue. Nothing is dropped when it binds: the asks it did not send are
45
+ * still pending, still answerable, and still counted down by the one clock. They are simply not
46
+ * written in the same burst as everything else the newly attached client is being sent.
47
+ *
48
+ * Oldest first, because insertion order is deadline order — the ask closest to expiring is the one
49
+ * a human has least time left to answer.
50
+ */
51
+ export const DEFAULT_MAX_REPLAY_ASKS = 16;
52
+ /**
53
+ * Total encoded bytes pushed on ONE attach: 256 KiB.
54
+ *
55
+ * Four full-sized asks at the registry's 60 KB per-entry ceiling, which is the realistic worst
56
+ * case, and far above the few hundred bytes a real tool-permission frame occupies.
57
+ */
58
+ export const DEFAULT_MAX_REPLAY_BYTES = 256 * 1024;
59
+ export class PermissionDelivery {
60
+ #pending;
61
+ #maxClients;
62
+ #maxPerClient;
63
+ #maxReplayAsks;
64
+ #maxReplayBytes;
65
+ /** clientId → request ids that client has been sent on its CURRENT connection. */
66
+ #delivered = new Map();
67
+ constructor(options) {
68
+ this.#pending = options.pending;
69
+ this.#maxClients = options.maxClients ?? DEFAULT_MAX_DELIVERY_CLIENTS;
70
+ this.#maxPerClient = options.maxPerClient ?? DEFAULT_MAX_DELIVERED_PER_CLIENT;
71
+ this.#maxReplayAsks = options.maxReplayAsks ?? DEFAULT_MAX_REPLAY_ASKS;
72
+ this.#maxReplayBytes = options.maxReplayBytes ?? DEFAULT_MAX_REPLAY_BYTES;
73
+ }
74
+ /** Record that `clientId` has been sent `requestId`. Idempotent, and never a state transition. */
75
+ markDelivered(clientId, requestId) {
76
+ let seen = this.#delivered.get(clientId);
77
+ if (seen === undefined) {
78
+ seen = new Set();
79
+ this.#delivered.set(clientId, seen);
80
+ this.#evictOldestClients();
81
+ }
82
+ seen.add(requestId);
83
+ while (seen.size > this.#maxPerClient) {
84
+ const oldest = seen.values().next();
85
+ if (oldest.done === true)
86
+ break;
87
+ seen.delete(oldest.value);
88
+ }
89
+ }
90
+ hasDelivered(clientId, requestId) {
91
+ return this.#delivered.get(clientId)?.has(requestId) === true;
92
+ }
93
+ /**
94
+ * The still-pending asks this client has not been shown on this connection — BOUNDED.
95
+ *
96
+ * Read straight off the registry each time: an ask that was answered while the client was
97
+ * connecting is no longer pending and must not be replayed as if it still needed an answer.
98
+ *
99
+ * Both caps are applied here rather than at the call site so that no caller can replay an
100
+ * unbounded burst by accident. Truncating is NOT dropping: an ask left out of this list is
101
+ * untouched, still PENDING, and still the only thing that can end it is an answer, the clock,
102
+ * or a cancellation. Nothing about being unsent is a decision.
103
+ */
104
+ pendingFor(clientId) {
105
+ const seen = this.#delivered.get(clientId);
106
+ const undelivered = this.#pending().filter((ask) => seen?.has(ask.requestId) !== true);
107
+ const bounded = [];
108
+ let bytes = 0;
109
+ for (const ask of undelivered) {
110
+ if (bounded.length >= this.#maxReplayAsks)
111
+ break;
112
+ // An ask that does not state its size contributes nothing to the byte budget; the count
113
+ // cap is what bounds it. See DeliverableAsk.bytes.
114
+ const size = ask.bytes ?? 0;
115
+ // The FIRST ask is always sent, whatever it weighs: refusing to replay the only
116
+ // outstanding ask because it is large would leave the agent parked with no surface
117
+ // able to see why.
118
+ if (bounded.length > 0 && bytes + size > this.#maxReplayBytes)
119
+ break;
120
+ bounded.push(ask);
121
+ bytes += size;
122
+ }
123
+ return bounded;
124
+ }
125
+ /**
126
+ * Forget everything about a client, because its connection ended.
127
+ *
128
+ * A client that reconnects under the same id is a NEW connection with nothing on its screen,
129
+ * so it must be shown every pending ask again. Remembering across the gap would leave a phone
130
+ * that dropped its WebSocket staring at a session whose ask it can no longer see or answer.
131
+ */
132
+ forgetClient(clientId) {
133
+ this.#delivered.delete(clientId);
134
+ }
135
+ /** Drop an ask from every client's record, because it is over. */
136
+ forgetRequest(requestId) {
137
+ for (const seen of this.#delivered.values())
138
+ seen.delete(requestId);
139
+ }
140
+ clear() {
141
+ this.#delivered.clear();
142
+ }
143
+ #evictOldestClients() {
144
+ while (this.#delivered.size > this.#maxClients) {
145
+ const oldest = this.#delivered.keys().next();
146
+ if (oldest.done === true)
147
+ break;
148
+ this.#delivered.delete(oldest.value);
149
+ }
150
+ }
151
+ }
152
+ //# sourceMappingURL=permission-delivery.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"permission-delivery.js","sourceRoot":"","sources":["../../../src/core/socket-server/permission-delivery.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * permission-delivery — per-connection bookkeeping for asks that have been SHOWN to a client.\n *\n * THIS IS NOT STATE ABOUT THE ASK. It is state about a connection, and keeping the two apart is\n * the whole reason this is a separate module rather than a field on the registry entry.\n *\n * The defect it exists to make unrepresentable: if delivering an ask (or acknowledging one)\n * consumed it, a client that was shown the ask and then died would take it with it — the entry\n * gone, no other surface ever told, and the agent still parked in `beforeToolCall` waiting for an\n * answer that can no longer be given. Delivery is therefore idempotent and NEVER a state\n * transition: an ask stays PENDING until somebody ANSWERS it, it expires, or it is cancelled.\n *\n * What it buys instead is \"exactly once per connection\": a client that attaches after an ask was\n * raised is shown it once, on attach, right after `session_metadata` — and is not shown it again\n * on every subsequent broadcast. When that client disconnects its record is dropped, so a\n * reconnecting client (same id, new connection) is shown every still-pending ask again. It has to\n * be: it may be a fresh process that has never seen any of them.\n *\n * WHAT \"EXACTLY ONCE\" MEANS HERE, PRECISELY, BECAUSE THE PHRASE IS OTHERWISE A PROMISE THIS WIRE\n * CANNOT KEEP (R34-PERM.6). It means two things and no others:\n *\n * 1. EXACTLY ONE AUTHORITATIVE RESOLUTION per request. That is the registry's synchronous\n * compare-and-swap in `permission-registry.ts`, not this file's business at all: however many\n * copies of an ask were shown, however many answers come back, one of them settles it and\n * every later one is refused with a tombstone.\n * 2. EXACTLY ONE REPLAY per (reconnect, still-pending request). That is this file: one send per\n * connection per ask, deduplicated CLIENT-SIDE by `requestId` — a renderer that already has a\n * dialog open for an id must update it rather than open a second one.\n *\n * TRUE END-TO-END EXACTLY-ONCE IS IMPOSSIBLE OVER THIS TRANSPORT AND MUST NOT BE ATTEMPTED. A\n * frame written to a socket that then dies may or may not have been rendered, and no acknowledgement\n * can close that gap: an ack that arrives says the ask was seen, an ack that never arrives says\n * nothing at all. The only two safe designs are \"deliver at least once and dedupe by id\" (this one)\n * and \"deliver at most once\", which loses asks. Anything that tried to make delivery authoritative\n * would have to make it a state transition — and that is precisely the wedge above.\n */\n\n/** The least this module needs to know about an ask. The registry's entry satisfies it. */\nexport interface DeliverableAsk {\n\treadonly requestId: string;\n\t/**\n\t * Encoded size of the frame this ask will be replayed as, in bytes, when the ask knows it.\n\t *\n\t * `PermissionEntry` counts it once at insert and carries it, so in production it is always\n\t * there. It is optional because this module's contract is \"the least it needs to know\", and an\n\t * ask that does not state its size is bounded by the COUNT cap alone — see\n\t * {@link PermissionDeliveryOptions.maxReplayBytes}.\n\t */\n\treadonly bytes?: number;\n}\n\nexport interface PermissionDeliveryOptions<T extends DeliverableAsk> {\n\t/** Live view of what is still pending. Called on every replay; never cached. */\n\tpending: () => readonly T[];\n\t/** How many client records to keep. Beyond this, the least recently touched is dropped. */\n\tmaxClients?: number;\n\t/** How many delivered ids to remember per client. */\n\tmaxPerClient?: number;\n\t/**\n\t * How many still-pending asks one attach may push at a client.\n\t *\n\t * The replay burst is the one place where a single client action — attaching — makes the\n\t * server write an unbounded amount at it. Without a cap, a session sitting at the registry's\n\t * pending limit hands every reconnecting phone the whole backlog in one loop.\n\t */\n\tmaxReplayAsks?: number;\n\t/**\n\t * Total encoded bytes one attach may push at a client.\n\t *\n\t * The count cap alone is not a byte bound: an ask may legitimately carry a 60 KB command, so\n\t * \"at most 16 of them\" is still nearly a megabyte. Both caps apply, whichever binds first.\n\t */\n\tmaxReplayBytes?: number;\n}\n\n/** Client records kept at once. Well above the socket server's own `maxClients` of 10. */\nexport const DEFAULT_MAX_DELIVERY_CLIENTS = 64;\n\n/** Delivered ids remembered per client. Above the registry's pending bound, so it never binds first. */\nexport const DEFAULT_MAX_DELIVERED_PER_CLIENT = 256;\n\n/**\n * Pending asks pushed on ONE attach. Half the registry's own pending bound.\n *\n * It is a BACKSTOP, not a queue. Nothing is dropped when it binds: the asks it did not send are\n * still pending, still answerable, and still counted down by the one clock. They are simply not\n * written in the same burst as everything else the newly attached client is being sent.\n *\n * Oldest first, because insertion order is deadline order — the ask closest to expiring is the one\n * a human has least time left to answer.\n */\nexport const DEFAULT_MAX_REPLAY_ASKS = 16;\n\n/**\n * Total encoded bytes pushed on ONE attach: 256 KiB.\n *\n * Four full-sized asks at the registry's 60 KB per-entry ceiling, which is the realistic worst\n * case, and far above the few hundred bytes a real tool-permission frame occupies.\n */\nexport const DEFAULT_MAX_REPLAY_BYTES = 256 * 1024;\n\nexport class PermissionDelivery<T extends DeliverableAsk = DeliverableAsk> {\n\treadonly #pending: () => readonly T[];\n\treadonly #maxClients: number;\n\treadonly #maxPerClient: number;\n\treadonly #maxReplayAsks: number;\n\treadonly #maxReplayBytes: number;\n\t/** clientId → request ids that client has been sent on its CURRENT connection. */\n\treadonly #delivered = new Map<string, Set<string>>();\n\n\tconstructor(options: PermissionDeliveryOptions<T>) {\n\t\tthis.#pending = options.pending;\n\t\tthis.#maxClients = options.maxClients ?? DEFAULT_MAX_DELIVERY_CLIENTS;\n\t\tthis.#maxPerClient = options.maxPerClient ?? DEFAULT_MAX_DELIVERED_PER_CLIENT;\n\t\tthis.#maxReplayAsks = options.maxReplayAsks ?? DEFAULT_MAX_REPLAY_ASKS;\n\t\tthis.#maxReplayBytes = options.maxReplayBytes ?? DEFAULT_MAX_REPLAY_BYTES;\n\t}\n\n\t/** Record that `clientId` has been sent `requestId`. Idempotent, and never a state transition. */\n\tmarkDelivered(clientId: string, requestId: string): void {\n\t\tlet seen = this.#delivered.get(clientId);\n\t\tif (seen === undefined) {\n\t\t\tseen = new Set<string>();\n\t\t\tthis.#delivered.set(clientId, seen);\n\t\t\tthis.#evictOldestClients();\n\t\t}\n\t\tseen.add(requestId);\n\t\twhile (seen.size > this.#maxPerClient) {\n\t\t\tconst oldest = seen.values().next();\n\t\t\tif (oldest.done === true) break;\n\t\t\tseen.delete(oldest.value);\n\t\t}\n\t}\n\n\thasDelivered(clientId: string, requestId: string): boolean {\n\t\treturn this.#delivered.get(clientId)?.has(requestId) === true;\n\t}\n\n\t/**\n\t * The still-pending asks this client has not been shown on this connection — BOUNDED.\n\t *\n\t * Read straight off the registry each time: an ask that was answered while the client was\n\t * connecting is no longer pending and must not be replayed as if it still needed an answer.\n\t *\n\t * Both caps are applied here rather than at the call site so that no caller can replay an\n\t * unbounded burst by accident. Truncating is NOT dropping: an ask left out of this list is\n\t * untouched, still PENDING, and still the only thing that can end it is an answer, the clock,\n\t * or a cancellation. Nothing about being unsent is a decision.\n\t */\n\tpendingFor(clientId: string): T[] {\n\t\tconst seen = this.#delivered.get(clientId);\n\t\tconst undelivered = this.#pending().filter((ask) => seen?.has(ask.requestId) !== true);\n\n\t\tconst bounded: T[] = [];\n\t\tlet bytes = 0;\n\t\tfor (const ask of undelivered) {\n\t\t\tif (bounded.length >= this.#maxReplayAsks) break;\n\t\t\t// An ask that does not state its size contributes nothing to the byte budget; the count\n\t\t\t// cap is what bounds it. See DeliverableAsk.bytes.\n\t\t\tconst size = ask.bytes ?? 0;\n\t\t\t// The FIRST ask is always sent, whatever it weighs: refusing to replay the only\n\t\t\t// outstanding ask because it is large would leave the agent parked with no surface\n\t\t\t// able to see why.\n\t\t\tif (bounded.length > 0 && bytes + size > this.#maxReplayBytes) break;\n\t\t\tbounded.push(ask);\n\t\t\tbytes += size;\n\t\t}\n\t\treturn bounded;\n\t}\n\n\t/**\n\t * Forget everything about a client, because its connection ended.\n\t *\n\t * A client that reconnects under the same id is a NEW connection with nothing on its screen,\n\t * so it must be shown every pending ask again. Remembering across the gap would leave a phone\n\t * that dropped its WebSocket staring at a session whose ask it can no longer see or answer.\n\t */\n\tforgetClient(clientId: string): void {\n\t\tthis.#delivered.delete(clientId);\n\t}\n\n\t/** Drop an ask from every client's record, because it is over. */\n\tforgetRequest(requestId: string): void {\n\t\tfor (const seen of this.#delivered.values()) seen.delete(requestId);\n\t}\n\n\tclear(): void {\n\t\tthis.#delivered.clear();\n\t}\n\n\t#evictOldestClients(): void {\n\t\twhile (this.#delivered.size > this.#maxClients) {\n\t\t\tconst oldest = this.#delivered.keys().next();\n\t\t\tif (oldest.done === true) break;\n\t\t\tthis.#delivered.delete(oldest.value);\n\t\t}\n\t}\n}\n"]}
@@ -0,0 +1,301 @@
1
+ /**
2
+ * permission-registry — the session's bounded pending-ask registry, and the ONE clock.
3
+ *
4
+ * An ask raised by the agent parks the turn until somebody answers it. This module is what holds
5
+ * that ask while it is unanswered: what was offered, who may answer it, when it stops being
6
+ * answerable, and — once — who won.
7
+ *
8
+ * FOUR PROPERTIES ARE LOAD-BEARING, each paid for by a defect this file exists to make
9
+ * unrepresentable:
10
+ *
11
+ * 1. {@link PermissionRegistry.settle} is SYNCHRONOUS from the pending-check through the removal.
12
+ * One `await` between "is it still pending?" and "mark it resolved" lets two answers both pass
13
+ * validation; the second `resolve()` on the caller's promise is a silent no-op, so a denial
14
+ * and an approval both look accepted and only one of them happened.
15
+ * 2. AN ANSWER'S MEANING COMES FROM THE OFFERED OPTION'S OWN `decision`. Never from its position
16
+ * in the array, never from the shape of its id, never from a label. A vocabulary like
17
+ * `[allow, deny-once, deny-always]` has its denial in the middle and two of them.
18
+ * 3. A REFUSAL NEVER CONSUMES. An unknown id, an id from another session, an option nobody
19
+ * offered — each returns a refusal VALUE and leaves the entry pending and still answerable.
20
+ * A refusal that consumed the ask would let one malformed frame from any attached client
21
+ * silently deny a tool call the human never saw.
22
+ * 4. NOTHING IS FABRICATED. Every terminal state names a decider, and the only decider that is a
23
+ * person is one whose answer named an offered option. Expiry and cancellation are attributed
24
+ * to `system`, never to a surface that did not act.
25
+ *
26
+ * The registry is PURE: it performs no I/O, opens no socket, and touches no session. It imports
27
+ * types only. What it holds is state plus the caller's own resolver, handed BACK on settle so the
28
+ * caller runs it — the registry never calls out into the world by itself except through the expiry
29
+ * listener, which exists because a deadline has to fire from somewhere.
30
+ */
31
+ import type { PermissionAskDetail } from "../extensions/types.js";
32
+ import type { RelayAnswer, RelayAsk, RelayDecider, RelayEnded } from "../permission-relay/types.js";
33
+ import type { PermissionRequestMessage } from "./types.js";
34
+ /** Env var that overrides the fail-closed expiry. Milliseconds. */
35
+ export declare const PERMISSION_EXPIRY_ENV = "DRAHT_PERMISSION_EXPIRY_MS";
36
+ /**
37
+ * How long an unanswered ask stays answerable: ONE HOUR.
38
+ *
39
+ * The number is chosen for the job this phase exists to do — a human walks away from the terminal
40
+ * and answers from a phone. Every shorter candidate fails that job: 30s and 5m are shorter than a
41
+ * meeting, a commute or a lunch, and an ask that expires while the person who would have approved
42
+ * it is still walking back to their desk fails CLOSED, which reports to the model as a blocked tool
43
+ * call and wastes the whole turn. The archived R34-PERM.8 measurement is what makes an hour safe to
44
+ * pick: the agent core imposes NO deadline of its own (25 minutes parked in `beforeToolCall` with
45
+ * zero degradation), so "hold the turn" is the mechanism and this timer is only the backstop that
46
+ * stops a forgotten ask from parking a session forever.
47
+ *
48
+ * It is a BACKSTOP, not a policy: the expected end of an ask is a human answering it, and every
49
+ * expiry is a small failure. That is also why it is not infinite — an ask nobody will ever answer
50
+ * must eventually fail closed and say so, rather than leaving a session wedged with no diagnosis.
51
+ */
52
+ export declare const DEFAULT_PERMISSION_EXPIRY_MS: number;
53
+ /** Floor for a configured expiry: below this a human cannot answer at all. */
54
+ export declare const MIN_PERMISSION_EXPIRY_MS = 1000;
55
+ /**
56
+ * Ceiling for a configured expiry: 24 hours.
57
+ *
58
+ * A bound exists so a typo cannot produce an ask that never expires. `Infinity`, `NaN` and a
59
+ * negative number are all rejected in favour of the default rather than clamped, because each of
60
+ * them means "this value was not thought about" rather than "keep it forever".
61
+ */
62
+ export declare const MAX_PERMISSION_EXPIRY_MS: number;
63
+ /** How many asks may be pending at once before new ones are refused. */
64
+ export declare const DEFAULT_MAX_PENDING = 32;
65
+ /**
66
+ * Largest encoded ask the registry will hold, in bytes.
67
+ *
68
+ * Under the transport's 64 KiB frame cap with headroom: a frame larger than this could not be
69
+ * relayed anyway (the attach bridge refuses an oversized permission frame rather than splitting it,
70
+ * because half an ask is a dialog showing half a command with an Approve button under it), so it is
71
+ * refused here, before anything is written, rather than after a renderer has been dropped.
72
+ */
73
+ export declare const DEFAULT_MAX_ENTRY_BYTES = 60000;
74
+ /** Total encoded bytes across all pending asks. */
75
+ export declare const DEFAULT_MAX_TOTAL_BYTES: number;
76
+ /** How long a settled ask is remembered so a late answer is TOLD, rather than merely refused. */
77
+ export declare const DEFAULT_TOMBSTONE_TTL_MS = 120000;
78
+ /** How many tombstones are kept. Oldest first out. */
79
+ export declare const DEFAULT_MAX_TOMBSTONES = 128;
80
+ /**
81
+ * Every way an ask can end. Mirrors the wire's `permission_resolved.decision`
82
+ * member for member — `socket-server/types.ts`, and through it
83
+ * `geist-protocol`'s `PermissionResolvedFrameSchema`.
84
+ *
85
+ * `answered` is the NEUTRAL member, added with `geist/0.4`. It says an ask was
86
+ * ANSWERED and says nothing about permission, which is the only true thing to say
87
+ * about a `select` or an `input`: they offer no vocabulary that grants or refuses.
88
+ * It GRANTS NOTHING — read it fail-closed everywhere, exactly as `denied`.
89
+ */
90
+ export type TerminalDecision = "approved" | "denied" | "cancelled" | "expired" | "answered";
91
+ /**
92
+ * WHO ended an ask nobody answered, and WHAT that ending was — as ONE value.
93
+ *
94
+ * The two halves travel together because they are one fact and they were previously written down
95
+ * twice: this file's expiry timer laid the tombstone from its own `{surface: "system"}` /
96
+ * `"expired"` literals, and the relay's `onExpired` listener used a second, independent pair for
97
+ * the broadcast and the audit row. They agreed, so nothing noticed — until a verifier mutated one
98
+ * and the other carried on asserting the old word, which is a durable record and a live wire frame
99
+ * disagreeing about the same ending with no test in a position to see it.
100
+ */
101
+ export interface PermissionEnding {
102
+ readonly decidedBy: RelayDecider;
103
+ readonly decision: TerminalDecision;
104
+ }
105
+ /** Nobody decided. The only decider an unanswered ask may ever name. */
106
+ export declare const SYSTEM_DECIDER: RelayDecider;
107
+ /** THE expiry fact, stated once. The timer lays it and the listener is handed the very same value. */
108
+ export declare const EXPIRED_BY_SYSTEM: PermissionEnding;
109
+ /** THE cancellation fact, stated once, for a session that is being replaced or stopped. */
110
+ export declare const CANCELLED_BY_SYSTEM: PermissionEnding;
111
+ /**
112
+ * Read the configured expiry, falling back to {@link DEFAULT_PERMISSION_EXPIRY_MS}.
113
+ *
114
+ * Anything unusable — unset, empty, non-numeric, zero, negative, `Infinity`, out of range — yields
115
+ * the default. A permission deadline must never be `NaN`: `new Date(Date.now() + NaN)` throws a
116
+ * RangeError out of the ask itself, which the permission gate reports as a TOOL ERROR rather than
117
+ * as a denial, so the ask neither fails closed nor reaches anybody.
118
+ */
119
+ export declare function resolvePermissionExpiryMs(env?: NodeJS.ProcessEnv): number;
120
+ /** One offered option, exactly as it was offered. Frozen on insert; never rebuilt. */
121
+ export interface RegisteredOption {
122
+ readonly id: string;
123
+ readonly label: string;
124
+ /** What choosing this option MEANS, when the vocabulary declares it. Read, never inferred. */
125
+ readonly decision?: "approve" | "deny";
126
+ }
127
+ /** A pending ask. Everything here was fixed when the ask was raised. */
128
+ export interface PermissionEntry {
129
+ readonly sessionId: string;
130
+ readonly requestId: string;
131
+ readonly method: RelayAsk["method"];
132
+ /** The immutable offered set — the ONLY answerable set. Frozen. */
133
+ readonly options: readonly RegisteredOption[];
134
+ /** Canonical detail, when this ask gates a tool call. Absent for a plain extension dialog. */
135
+ readonly detail?: PermissionAskDetail;
136
+ /** The exact frame that was broadcast, replayed verbatim to a client that arrives later. */
137
+ readonly frame: PermissionRequestMessage;
138
+ readonly requestedAt: string;
139
+ /** Wall-clock instant this ask stops being answerable, in ms since the epoch. */
140
+ readonly deadlineAt: number;
141
+ /** Encoded size of {@link PermissionEntry.frame}, counted once at insert. */
142
+ readonly bytes: number;
143
+ /**
144
+ * The raiser's own resolver. The registry stores it and hands it back; it never calls it.
145
+ *
146
+ * It takes a {@link RelayEnded} as well as an answer because an ask that EXPIRED or was
147
+ * CANCELLED is over on every surface, and the raiser has to be told that rather than told the
148
+ * relay merely gave up — the two used to be the same `undefined`, and a decorator reading the
149
+ * second meaning kept a live Approve button on an ask already recorded as expired.
150
+ */
151
+ readonly resolve: (answer: RelayAnswer | RelayEnded | undefined) => void;
152
+ }
153
+ /** Why an insert was refused. Each is a bound, not a failure of the asker. */
154
+ export type InsertRefusal = "duplicate_request" | "too_many_pending" | "entry_too_large" | "total_too_large";
155
+ export type InsertResult = {
156
+ readonly ok: true;
157
+ readonly entry: PermissionEntry;
158
+ } | {
159
+ readonly ok: false;
160
+ readonly reason: InsertRefusal;
161
+ readonly message: string;
162
+ };
163
+ /** Why an answer was refused. In every case the entry, if there is one, is left untouched. */
164
+ export type SettleRefusal = "unknown_request" | "cross_session" | "invalid_option";
165
+ export type SettleResult = {
166
+ readonly status: "resolved";
167
+ readonly entry: PermissionEntry;
168
+ readonly answer: RelayAnswer;
169
+ readonly chosenOptionId: string;
170
+ readonly decision: TerminalDecision;
171
+ } | {
172
+ readonly status: "refused";
173
+ readonly reason: SettleRefusal;
174
+ readonly message: string;
175
+ } | {
176
+ readonly status: "already_resolved";
177
+ readonly decidedBy: RelayDecider;
178
+ readonly decision: TerminalDecision;
179
+ readonly message: string;
180
+ };
181
+ export interface PermissionRegistryOptions {
182
+ /** The session these asks belong to. An answer naming any other session is refused. */
183
+ sessionId: string;
184
+ expiryMs?: number;
185
+ maxPending?: number;
186
+ maxEntryBytes?: number;
187
+ maxTotalBytes?: number;
188
+ tombstoneTtlMs?: number;
189
+ maxTombstones?: number;
190
+ /** Injectable for tests. Defaults to `Date.now`. */
191
+ now?: () => number;
192
+ }
193
+ /** What {@link PermissionRegistry.insert} needs beyond the frame itself. */
194
+ export interface PermissionInsert {
195
+ readonly requestId: string;
196
+ readonly method: RelayAsk["method"];
197
+ readonly options: readonly RegisteredOption[];
198
+ readonly detail?: PermissionAskDetail;
199
+ readonly frame: PermissionRequestMessage;
200
+ readonly requestedAt: string;
201
+ readonly resolve: (answer: RelayAnswer | RelayEnded | undefined) => void;
202
+ }
203
+ /**
204
+ * The pending-ask registry for ONE session.
205
+ *
206
+ * Lifetime: it is built inside the attach bind closure, so it dies with the session and survives
207
+ * client churn. It is deliberately NOT built in the UI decorator — a new `ExtensionRunner`, and
208
+ * therefore a new decorator, is constructed on every extension reload, which would orphan every
209
+ * ask raised before the reload with the agent still parked on it.
210
+ */
211
+ export declare class PermissionRegistry {
212
+ #private;
213
+ constructor(options: PermissionRegistryOptions);
214
+ get sessionId(): string;
215
+ /** The one clock, in milliseconds. */
216
+ get expiryMs(): number;
217
+ get pendingCount(): number;
218
+ /**
219
+ * Called when an ask reaches its deadline with nobody having answered.
220
+ *
221
+ * The listener owns the fail-closed handling: end the raiser's ask, tell every surface, record
222
+ * it. The registry has already removed the entry by then, so a late answer sees a tombstone
223
+ * rather than a still-answerable ask.
224
+ *
225
+ * `ending` is THE SAME VALUE the tombstone was laid with — not a second copy of it. The
226
+ * listener must state the ending from this argument and never from a literal of its own; two
227
+ * literals for one fact is how a mutation to either survived every test in the suite.
228
+ */
229
+ onExpired(listener: (entry: PermissionEntry, ending: PermissionEnding) => void): void;
230
+ /** Every still-pending ask, oldest first (insertion order). */
231
+ pending(): readonly PermissionEntry[];
232
+ get(requestId: string): PermissionEntry | undefined;
233
+ /**
234
+ * Register an ask BEFORE the first socket write.
235
+ *
236
+ * Order matters and is not negotiable: a client can answer before the writer's loop has even
237
+ * finished fanning out, and an answer naming an id the registry has never seen is refused as
238
+ * unknown — which would refuse the very first, correct answer to a real ask.
239
+ */
240
+ insert(input: PermissionInsert): InsertResult;
241
+ /**
242
+ * Answer an ask. SYNCHRONOUS from the pending-check through the removal — see property (1).
243
+ *
244
+ * Returns the entry and its resolver on success; the caller runs the resolver. Every refusal
245
+ * leaves the entry exactly as it was, still pending and still answerable by somebody else.
246
+ */
247
+ settle(sessionId: string, requestId: string, optionId: string, decidedBy: RelayDecider): SettleResult;
248
+ /**
249
+ * End a pending ask that some OTHER surface decided.
250
+ *
251
+ * Returns the entry when this call is the one that ended it, and `undefined` when it was
252
+ * already over — which is the common case and must stay silent, because the relay decorator
253
+ * withdraws every ask it settles, including the ones a remote answer just settled here. A
254
+ * second broadcast and a second audit record would both be wrong.
255
+ */
256
+ withdraw(requestId: string, decidedBy: RelayDecider, decision: TerminalDecision): PermissionEntry | undefined;
257
+ /**
258
+ * End every pending ask, fail-closed.
259
+ *
260
+ * Used when the session is replaced or stopped: the asks belong to a session that is going
261
+ * away, so nothing they gate may proceed. Returns them so the caller can resolve, announce and
262
+ * record each one.
263
+ */
264
+ cancelAll(decidedBy?: RelayDecider): PermissionEntry[];
265
+ }
266
+ /**
267
+ * What answering `optionId` MEANS for this ask, or `undefined` when it means nothing at all.
268
+ *
269
+ * The whole rule, in one place:
270
+ *
271
+ * - `input` OFFERS NOTHING — it has no option ids and never had any — so EVERY string is a valid
272
+ * answer, carried verbatim as the answer itself. Refusing free text here would hang the agent on
273
+ * an ask the client rendered as fully answerable. The condition is the EMPTY OFFERED SET, not the
274
+ * method name: keying it on `method === "input"` alone made "an answer must name an offered
275
+ * option" depend on an invariant maintained in a different module (the decorator's
276
+ * `NO_OFFERED_OPTIONS`), and an `input` ask that ever carried a vocabulary would have accepted —
277
+ * and CONSUMED — an id nobody offered. Property (3) of this file holds for every method now,
278
+ * whoever builds the ask.
279
+ * - otherwise the id must be one of the ids that were OFFERED, and what it means is that option's
280
+ * OWN `decision` — read off the option, never derived from its index, its id or its label.
281
+ * - an offered option that declares no `decision` (a plain `select`, whose entries are choices
282
+ * rather than a permission vocabulary) ends the ask by being ANSWERED — `answered`, the wire's
283
+ * neutral word. The choice itself travels as `chosenOptionId`.
284
+ *
285
+ * GAP CLOSED (geist/0.4). This function used to say `approved` for those last two, because the wire
286
+ * union had no neutral member. That was a FABRICATED GRANT: `select` and `input` grant nothing and
287
+ * refuse nothing, so "approved" stated a decision that was never offered, let alone made. The
288
+ * containment argument that went with it — "no audit row is written for an ask with no
289
+ * `tool_permission` detail" — was false: nothing stops an extension attaching one, and a probe did,
290
+ * which put the fabricated word into the DURABLE record. `answered` now exists on
291
+ * `TerminalDecision`, on `socket-server/types.ts`, on `PermissionResolutionEntry.decision` and on
292
+ * `geist-protocol`'s `PermissionResolvedFrameSchema`, so the true thing is sayable and is said.
293
+ *
294
+ * `answered` GRANTS NOTHING. Anything downstream that branches on this value must treat it as it
295
+ * treats `denied`; only `approved` is permission. What was actually chosen is `chosenOptionId`.
296
+ *
297
+ * A `deny` option still yields `denied` and an `approve` option still yields `approved` — the words
298
+ * for a real permission vocabulary are unchanged, and only the case that HAD no true word moved.
299
+ */
300
+ export declare function decisionFor(entry: PermissionEntry, optionId: string): TerminalDecision | undefined;
301
+ //# sourceMappingURL=permission-registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"permission-registry.d.ts","sourceRoot":"","sources":["../../../src/core/socket-server/permission-registry.ts"],"names":[],"mappings":"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"}