orkeon-code 1.0.0-rc.1 → 1.0.0-rc.2

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 (440) hide show
  1. package/.orkeon-runtime +10 -0
  2. package/.orkeon-version +1 -1
  3. package/NOTICE.md +1 -1
  4. package/README.fr.md +16 -22
  5. package/README.md +16 -22
  6. package/config/appsettings.jev.example.json +4 -1
  7. package/config/appsettings.kev.example.json +4 -1
  8. package/config/appsettings.liquid.example.json +4 -1
  9. package/config/appsettings.ollama-whisper.example.json +1 -0
  10. package/config/appsettings.whisper.example.json +1 -0
  11. package/mcp/whisper/README.md +2 -1
  12. package/orkeon-code +206 -11
  13. package/orkeon-code.ps1 +109 -7
  14. package/package.json +2 -1
  15. package/src/commands/.orkeon/orkeon-cli.d.ts +1 -4
  16. package/src/commands/_lib/args.ts +5 -4
  17. package/src/commands/_lib/dev/dev-batches.ts +34 -36
  18. package/src/commands/_lib/dev/dev-implement.ts +11 -14
  19. package/src/commands/_lib/dev/dev-source.ts +7 -11
  20. package/src/commands/_lib/dev/dev.ts +34 -37
  21. package/src/commands/_lib/dev/markers.ts +7 -0
  22. package/src/commands/_lib/dev/messages.ts +112 -0
  23. package/src/commands/_lib/dev-step.ts +16 -13
  24. package/src/commands/_lib/dispatch.ts +62 -39
  25. package/src/commands/_lib/git/branch.ts +9 -10
  26. package/src/commands/_lib/git/commit.ts +9 -13
  27. package/src/commands/_lib/git/diff.ts +22 -12
  28. package/src/commands/_lib/git/messages.ts +54 -0
  29. package/src/commands/_lib/git/review.ts +9 -10
  30. package/src/commands/_lib/memory/memory-admit.ts +19 -21
  31. package/src/commands/_lib/memory/memory.ts +3 -2
  32. package/src/commands/_lib/memory/messages.ts +32 -0
  33. package/src/commands/_lib/messages.ts +48 -0
  34. package/src/commands/_lib/project/messages.ts +8 -0
  35. package/src/commands/_lib/session/export.ts +3 -2
  36. package/src/commands/_lib/session/messages.ts +87 -0
  37. package/src/commands/_lib/session/prompts.ts +4 -0
  38. package/src/commands/_lib/session/resume.ts +15 -24
  39. package/src/commands/_lib/session/tasks.ts +20 -23
  40. package/src/commands/_lib/settings/advisor.ts +11 -16
  41. package/src/commands/_lib/settings/agents.ts +18 -28
  42. package/src/commands/_lib/settings/choices.ts +8 -0
  43. package/src/commands/_lib/settings/config.ts +43 -43
  44. package/src/commands/_lib/settings/effort.ts +147 -0
  45. package/src/commands/_lib/settings/hooks.ts +12 -20
  46. package/src/commands/_lib/settings/messages.ts +408 -0
  47. package/src/commands/_lib/settings/mode.ts +33 -24
  48. package/src/commands/_lib/settings/model.ts +71 -36
  49. package/src/commands/_lib/settings/output-style.ts +39 -0
  50. package/src/commands/_lib/settings/permissions.ts +71 -93
  51. package/src/commands/_lib/settings/route.ts +63 -0
  52. package/src/commands/_lib/settings/skills.ts +53 -11
  53. package/src/commands/_lib/settings/theme.ts +42 -0
  54. package/src/commands/_lib/speech/messages.ts +58 -0
  55. package/src/commands/_lib/speech/prompts.ts +4 -0
  56. package/src/commands/_lib/speech/say.ts +9 -10
  57. package/src/commands/_lib/speech/transcribe.ts +14 -23
  58. package/src/commands/_lib/speech/voice.ts +14 -18
  59. package/src/commands/_lib/status/doctor.ts +47 -28
  60. package/src/commands/_lib/status/messages.ts +100 -0
  61. package/src/commands/_lib/status/meta.ts +3 -24
  62. package/src/commands/_lib/status/status.ts +10 -11
  63. package/src/commands/_lib/status/usage-tools.ts +2 -3
  64. package/src/commands/_lib/status/usage.ts +7 -18
  65. package/src/commands/_lib/view.ts +6 -1
  66. package/src/commands/dev/dev-batches.cmd.ts +4 -3
  67. package/src/commands/dev/dev-learn.cmd.ts +3 -3
  68. package/src/commands/dev/dev-plan.cmd.ts +6 -7
  69. package/src/commands/dev/dev-spec.cmd.ts +6 -7
  70. package/src/commands/git/commit.cmd.ts +3 -3
  71. package/src/commands/git/review.cmd.ts +3 -3
  72. package/src/commands/memory/memory.cmd.ts +2 -2
  73. package/src/commands/project/analyze.cmd.ts +3 -3
  74. package/src/commands/project/debug-tool-call.cmd.ts +4 -9
  75. package/src/commands/project/init-verifiers.cmd.ts +3 -3
  76. package/src/commands/project/init.cmd.ts +3 -3
  77. package/src/commands/project/verify.cmd.ts +2 -2
  78. package/src/commands/session/assistant.cmd.ts +2 -2
  79. package/src/commands/session/compact.cmd.ts +1 -1
  80. package/src/commands/session/copy.cmd.ts +8 -7
  81. package/src/commands/session/rename.cmd.ts +3 -2
  82. package/src/commands/session/rewind.cmd.ts +3 -4
  83. package/src/commands/session/summary.cmd.ts +3 -3
  84. package/src/commands/session/tasks.cmd.ts +4 -2
  85. package/src/commands/settings/config.cmd.ts +4 -2
  86. package/src/commands/settings/effort.cmd.ts +10 -31
  87. package/src/commands/settings/fast.cmd.ts +2 -1
  88. package/src/commands/settings/mode.cmd.ts +3 -3
  89. package/src/commands/settings/model.cmd.ts +3 -2
  90. package/src/commands/settings/output-style.cmd.ts +9 -38
  91. package/src/commands/settings/permissions.cmd.ts +2 -2
  92. package/src/commands/settings/proactive.cmd.ts +2 -1
  93. package/src/commands/settings/route.cmd.ts +16 -0
  94. package/src/commands/settings/skills.cmd.ts +3 -3
  95. package/src/commands/settings/theme.cmd.ts +14 -0
  96. package/src/commands/speech/say.cmd.ts +2 -2
  97. package/src/commands/speech/transcribe.cmd.ts +2 -2
  98. package/src/commands/status/release-notes.cmd.ts +1 -1
  99. package/src/crews/.orkeon/orkeon.d.ts +538 -93
  100. package/src/crews/_probe-shared-memory/domain/messages.ts +54 -0
  101. package/src/crews/_probe-shared-memory/domain/probe-verdict.ts +17 -12
  102. package/src/crews/_probe-shared-memory/domain/prompts.ts +5 -0
  103. package/src/crews/_probe-shared-memory/probe.ork.ts +5 -3
  104. package/src/crews/advisor/application/messages.ts +4 -0
  105. package/src/crews/advisor/application/prompts.ts +4 -0
  106. package/src/crews/advisor/application/run-advisor.ts +2 -1
  107. package/src/crews/advisor/crew.ork.ts +5 -4
  108. package/src/crews/advisor/domain/advice.ts +7 -23
  109. package/src/crews/advisor/domain/messages.ts +8 -0
  110. package/src/crews/advisor/domain/prompts.ts +26 -0
  111. package/src/crews/agent-run/application/messages.ts +18 -0
  112. package/src/crews/agent-run/application/run-agent-run.ts +5 -4
  113. package/src/crews/agent-run/crew.ork.ts +3 -3
  114. package/src/crews/analyze/application/messages.ts +27 -0
  115. package/src/crews/analyze/application/prompts.ts +4 -0
  116. package/src/crews/analyze/application/run-analyze.ts +16 -14
  117. package/src/crews/analyze/crew.ork.ts +5 -4
  118. package/src/crews/analyze/domain/harvest.ts +33 -65
  119. package/src/crews/analyze/domain/prompts.ts +86 -0
  120. package/src/crews/code-review/application/lens-material.ts +24 -0
  121. package/src/crews/code-review/application/messages.ts +17 -0
  122. package/src/crews/code-review/application/prompts.ts +10 -17
  123. package/src/crews/code-review/application/review.ts +4 -1
  124. package/src/crews/code-review/application/run-code-review.ts +13 -15
  125. package/src/crews/code-review/crew.ork.ts +5 -4
  126. package/src/crews/code-review/domain/lenses.ts +6 -45
  127. package/src/crews/code-review/domain/messages.ts +25 -0
  128. package/src/crews/code-review/domain/prompts.ts +58 -0
  129. package/src/crews/code-review/domain/report.ts +5 -6
  130. package/src/crews/code-review/domain/scope.ts +6 -12
  131. package/src/crews/dev-batches/application/messages.ts +127 -0
  132. package/src/crews/dev-batches/application/plan-close.ts +12 -12
  133. package/src/crews/dev-batches/application/prompts.ts +10 -0
  134. package/src/crews/dev-batches/application/run-dev-batches.ts +57 -50
  135. package/src/crews/dev-batches/application/run-wave.ts +24 -22
  136. package/src/crews/dev-batches/application/seed-harvest.ts +8 -7
  137. package/src/crews/dev-batches/crew.ork.ts +12 -9
  138. package/src/crews/dev-batches/domain/batches-log.ts +1 -3
  139. package/src/crews/dev-batches/domain/markers.ts +5 -0
  140. package/src/crews/dev-batches/domain/messages.ts +6 -0
  141. package/src/crews/dev-batches/domain/wave-order.ts +3 -2
  142. package/src/crews/dev-change/application/change-material.ts +44 -0
  143. package/src/crews/dev-change/application/evidence.ts +25 -22
  144. package/src/crews/dev-change/application/messages.ts +81 -0
  145. package/src/crews/dev-change/application/{change-prompt.ts → prompts.ts} +40 -43
  146. package/src/crews/dev-change/application/run-dev-change.ts +43 -34
  147. package/src/crews/dev-change/crew.ork.ts +11 -9
  148. package/src/crews/dev-change/domain/change-answer.ts +24 -20
  149. package/src/crews/dev-change/domain/change-render.ts +13 -15
  150. package/src/crews/dev-change/domain/markers.ts +28 -0
  151. package/src/crews/dev-change/domain/messages.ts +16 -0
  152. package/src/crews/dev-implement/application/close.ts +21 -18
  153. package/src/crews/dev-implement/application/locate-sheet.ts +7 -5
  154. package/src/crews/dev-implement/application/messages.ts +161 -0
  155. package/src/crews/dev-implement/application/observe.ts +4 -2
  156. package/src/crews/dev-implement/application/prompts.ts +9 -0
  157. package/src/crews/dev-implement/application/report-writes.ts +14 -9
  158. package/src/crews/dev-implement/application/run-dev-implement.ts +84 -73
  159. package/src/crews/dev-implement/application/suite-job.ts +15 -11
  160. package/src/crews/dev-implement/crew.ork.ts +2 -1
  161. package/src/crews/dev-implement/domain/contracts.ts +59 -60
  162. package/src/crews/dev-implement/domain/correction.ts +16 -15
  163. package/src/crews/dev-implement/domain/cycles.ts +2 -1
  164. package/src/crews/dev-implement/domain/markers.ts +23 -0
  165. package/src/crews/dev-implement/domain/messages.ts +58 -0
  166. package/src/crews/dev-implement/domain/prompts.ts +93 -0
  167. package/src/crews/dev-implement/domain/roles.ts +3 -7
  168. package/src/crews/dev-implement/domain/sheet-edits.ts +6 -5
  169. package/src/crews/dev-implement/domain/sheet-ticks.ts +5 -4
  170. package/src/crews/dev-implement/domain/step-checks.ts +17 -16
  171. package/src/crews/dev-implement/domain/step-section.ts +6 -4
  172. package/src/crews/dev-learn/application/learn-prompt-fit.ts +63 -0
  173. package/src/crews/dev-learn/application/messages.ts +51 -0
  174. package/src/crews/dev-learn/application/{learn-prompt.ts → prompts.ts} +24 -65
  175. package/src/crews/dev-learn/application/run-dev-learn.ts +37 -32
  176. package/src/crews/dev-learn/crew.ork.ts +4 -3
  177. package/src/crews/dev-learn/domain/learn-answer.ts +25 -27
  178. package/src/crews/dev-learn/domain/messages.ts +65 -0
  179. package/src/crews/dev-learn/domain/owner-lines.ts +12 -9
  180. package/src/crews/dev-learn/domain/proposals-render.ts +8 -9
  181. package/src/crews/dev-plan/application/anchor-paths.ts +57 -20
  182. package/src/crews/dev-plan/application/inventory.ts +17 -13
  183. package/src/crews/dev-plan/application/messages.ts +88 -0
  184. package/src/crews/dev-plan/application/plan-prompt-fit.ts +44 -0
  185. package/src/crews/dev-plan/application/{plan-prompt.ts → prompts.ts} +37 -55
  186. package/src/crews/dev-plan/application/run-dev-plan.ts +103 -75
  187. package/src/crews/dev-plan/crew.ork.ts +11 -8
  188. package/src/crews/dev-plan/domain/inventory-model.ts +3 -3
  189. package/src/crews/dev-plan/domain/markers.ts +18 -0
  190. package/src/crews/dev-plan/domain/messages.ts +118 -0
  191. package/src/crews/dev-plan/domain/plan-answer.ts +118 -103
  192. package/src/crews/dev-plan/domain/plan-render.ts +30 -31
  193. package/src/crews/dev-plan/domain/prompts.ts +44 -0
  194. package/src/crews/dev-spec/application/messages.ts +30 -0
  195. package/src/crews/dev-spec/application/{spec-prompt.ts → prompts.ts} +42 -47
  196. package/src/crews/dev-spec/application/run-dev-spec.ts +67 -36
  197. package/src/crews/dev-spec/application/spec-material.ts +42 -0
  198. package/src/crews/dev-spec/crew.ork.ts +11 -9
  199. package/src/crews/dev-spec/domain/markers.ts +30 -0
  200. package/src/crews/dev-spec/domain/messages.ts +39 -0
  201. package/src/crews/dev-spec/domain/spec-answer.ts +46 -47
  202. package/src/crews/dev-spec/domain/spec-render.ts +18 -18
  203. package/src/crews/dev-verify/application/audit-brief.ts +187 -0
  204. package/src/crews/dev-verify/application/audit.ts +38 -30
  205. package/src/crews/dev-verify/application/capture.ts +34 -26
  206. package/src/crews/dev-verify/application/messages.ts +119 -0
  207. package/src/crews/dev-verify/application/prompts.ts +209 -0
  208. package/src/crews/dev-verify/application/run-dev-verify.ts +60 -46
  209. package/src/crews/dev-verify/application/run-gate.ts +11 -9
  210. package/src/crews/dev-verify/crew.ork.ts +6 -6
  211. package/src/crews/dev-verify/domain/audit-answer.ts +16 -12
  212. package/src/crews/dev-verify/domain/capture-sections.ts +5 -4
  213. package/src/crews/dev-verify/domain/commands.ts +3 -3
  214. package/src/crews/dev-verify/domain/gate.ts +21 -16
  215. package/src/crews/dev-verify/domain/markers.ts +16 -0
  216. package/src/crews/dev-verify/domain/mechanical-table.ts +37 -44
  217. package/src/crews/dev-verify/domain/messages.ts +92 -0
  218. package/src/crews/dev-verify/domain/verdict.ts +4 -4
  219. package/src/crews/git-commit/application/draft.ts +16 -37
  220. package/src/crews/git-commit/application/messages.ts +15 -0
  221. package/src/crews/git-commit/application/prompts.ts +47 -0
  222. package/src/crews/git-commit/application/run-git-commit.ts +13 -12
  223. package/src/crews/git-commit/crew.ork.ts +5 -4
  224. package/src/crews/git-commit/domain/commit.ts +15 -35
  225. package/src/crews/git-commit/domain/markers.ts +4 -0
  226. package/src/crews/git-commit/domain/messages.ts +48 -0
  227. package/src/crews/init-verifiers/application/authoring.ts +2 -1
  228. package/src/crews/init-verifiers/application/messages.ts +13 -0
  229. package/src/crews/init-verifiers/application/prompts.ts +5 -1
  230. package/src/crews/init-verifiers/application/run-init-verifiers.ts +3 -2
  231. package/src/crews/init-verifiers/crew.ork.ts +5 -4
  232. package/src/crews/main-loop/application/auto-compact.ts +2 -1
  233. package/src/crews/main-loop/application/messages.ts +81 -0
  234. package/src/crews/main-loop/application/prompts.ts +12 -0
  235. package/src/crews/main-loop/application/run-main-loop.ts +63 -30
  236. package/src/crews/main-loop/application/{turn-prompt.ts → turn-context.ts} +7 -8
  237. package/src/crews/main-loop/crew.ork.ts +12 -7
  238. package/src/crews/main-loop/domain/prompt-assembly.ts +45 -228
  239. package/src/crews/main-loop/domain/prompts.ts +336 -0
  240. package/src/crews/main-loop/domain/turn-chains.ts +10 -9
  241. package/src/crews/project-init/application/detect.ts +5 -4
  242. package/src/crews/project-init/application/messages.ts +15 -0
  243. package/src/crews/project-init/application/prompts.ts +11 -7
  244. package/src/crews/project-init/crew.ork.ts +5 -4
  245. package/src/crews/project-init/domain/existing-files.ts +6 -4
  246. package/src/crews/project-init/domain/messages.ts +13 -0
  247. package/src/crews/project-init/domain/package-map.ts +3 -3
  248. package/src/crews/project-init/domain/prompts.ts +10 -0
  249. package/src/crews/session-compact/application/prompts.ts +5 -0
  250. package/src/crews/session-compact/crew.ork.ts +5 -4
  251. package/src/crews/shared-memory-admit/application/prompts.ts +5 -0
  252. package/src/crews/shared-memory-admit/crew.ork.ts +3 -2
  253. package/src/crews/speech/application/messages.ts +3 -0
  254. package/src/crews/speech/application/prompts.ts +3 -0
  255. package/src/crews/speech/application/run-speech.ts +2 -1
  256. package/src/crews/speech/crew.ork.ts +2 -1
  257. package/src/shared/application/agents/child-agent.ts +11 -7
  258. package/src/shared/application/agents/messages.ts +35 -0
  259. package/src/shared/application/agents/route-agent.ts +115 -0
  260. package/src/shared/application/agents/run-sub-agent.ts +31 -8
  261. package/src/shared/application/compaction/compact-session.ts +19 -14
  262. package/src/shared/application/compaction/messages.ts +20 -0
  263. package/src/shared/application/compaction/prune-context.ts +94 -0
  264. package/src/shared/application/compaction/pruned-llm.ts +35 -0
  265. package/src/shared/application/dev/brief-inventory.ts +6 -4
  266. package/src/shared/application/dev/close-batch.ts +9 -7
  267. package/src/shared/application/dev/find-repo-pack.ts +4 -3
  268. package/src/shared/application/dev/learn-decision.ts +20 -18
  269. package/src/shared/application/dev/load-dev-context.ts +7 -8
  270. package/src/shared/application/dev/measure-access-cost.ts +5 -4
  271. package/src/shared/application/dev/messages.ts +132 -0
  272. package/src/shared/application/dev/phase-timer.ts +54 -0
  273. package/src/shared/application/dev/plan-source.ts +12 -8
  274. package/src/shared/application/dev/preflight.ts +8 -8
  275. package/src/shared/application/dev/prompts.ts +34 -0
  276. package/src/shared/application/dev/question-round.ts +25 -17
  277. package/src/shared/application/dev/resolve-work-folder.ts +4 -3
  278. package/src/shared/application/dev/settle-questions.ts +4 -2
  279. package/src/shared/application/dev/source-review.ts +12 -8
  280. package/src/shared/application/dev/source-step.ts +12 -10
  281. package/src/shared/application/dev/spend.ts +17 -4
  282. package/src/shared/application/dev/step-precedents.ts +2 -1
  283. package/src/shared/application/dev/tool-call-policy.ts +9 -11
  284. package/src/shared/application/dev/tool-callbacks.ts +52 -5
  285. package/src/shared/application/dev/tool-trace-recorder.ts +2 -1
  286. package/src/shared/application/dev/verdict-sources.ts +5 -3
  287. package/src/shared/application/dev/wrapped-tools.ts +4 -2
  288. package/src/shared/application/extra-tools.ts +2 -1
  289. package/src/shared/application/git/batch-worktree.ts +22 -17
  290. package/src/shared/application/git/commit-files.ts +24 -19
  291. package/src/shared/application/git/merge-batch.ts +11 -7
  292. package/src/shared/application/git/messages.ts +75 -0
  293. package/src/shared/application/git/open-pull-request.ts +4 -3
  294. package/src/shared/application/host-context.ts +59 -0
  295. package/src/shared/application/host-layout-store.ts +45 -0
  296. package/src/shared/application/llm-profile.ts +4 -3
  297. package/src/shared/application/messages.ts +14 -0
  298. package/src/shared/application/permission-rules.ts +10 -0
  299. package/src/shared/application/ports/decision.ts +14 -0
  300. package/src/shared/application/ports/human.ts +25 -0
  301. package/src/shared/application/ports/llm.ts +32 -3
  302. package/src/shared/application/ports/memory.ts +1 -1
  303. package/src/shared/application/ports/theme.ts +11 -0
  304. package/src/shared/application/ports.ts +4 -2
  305. package/src/shared/application/session-io.ts +2 -1
  306. package/src/shared/application/shared-memory/admit-entries.ts +16 -14
  307. package/src/shared/application/shared-memory/harvest-after-gaps.ts +5 -8
  308. package/src/shared/application/shared-memory/harvest-mistakes.ts +3 -2
  309. package/src/shared/application/shared-memory/import-agent-memory.ts +9 -7
  310. package/src/shared/application/shared-memory/memory-files.ts +2 -1
  311. package/src/shared/application/shared-memory/memory-settings.ts +2 -1
  312. package/src/shared/application/shared-memory/messages.ts +63 -0
  313. package/src/shared/application/shared-memory/push-candidate.ts +14 -11
  314. package/src/shared/application/shared-memory/recall-precedents.ts +2 -1
  315. package/src/shared/application/skills/messages.ts +4 -0
  316. package/src/shared/application/skills/suggest-skills.ts +102 -0
  317. package/src/shared/application/workflow/messages.ts +8 -0
  318. package/src/shared/application/workflow/workflow-state.ts +7 -6
  319. package/src/shared/domain/agent-policy/behavior-flags.ts +4 -10
  320. package/src/shared/domain/agent-policy/extra-tools.ts +2 -4
  321. package/src/shared/domain/agent-policy/messages.ts +66 -0
  322. package/src/shared/domain/agent-policy/path-rules.ts +299 -0
  323. package/src/shared/domain/agent-policy/permission.ts +20 -18
  324. package/src/shared/domain/agent-policy/prompts.ts +17 -0
  325. package/src/shared/domain/agent-policy/reasoning.ts +59 -0
  326. package/src/shared/domain/agent-policy/rule-sets.ts +18 -14
  327. package/src/shared/domain/agent-policy/tool-access.ts +17 -3
  328. package/src/shared/domain/agent-registry.ts +6 -5
  329. package/src/shared/domain/agents/chain.ts +2 -2
  330. package/src/shared/domain/agents/charter.ts +8 -5
  331. package/src/shared/domain/agents/exclusive.ts +2 -1
  332. package/src/shared/domain/agents/instances.ts +18 -15
  333. package/src/shared/domain/agents/messages.ts +39 -0
  334. package/src/shared/domain/agents/model-route.ts +199 -0
  335. package/src/shared/domain/agents/prompts.ts +20 -0
  336. package/src/shared/domain/code-intel-contract.ts +5 -4
  337. package/src/shared/domain/code-intel-routing.ts +8 -61
  338. package/src/shared/domain/compact-outcome.ts +5 -3
  339. package/src/shared/domain/compaction-thresholds.ts +2 -1
  340. package/src/shared/domain/compaction.ts +22 -113
  341. package/src/shared/domain/config-schema.ts +94 -81
  342. package/src/shared/domain/context-prune.ts +176 -0
  343. package/src/shared/domain/decision/questions.ts +102 -0
  344. package/src/shared/domain/dev/access-cost.ts +19 -15
  345. package/src/shared/domain/dev/batches-concurrency.ts +5 -6
  346. package/src/shared/domain/dev/build-commands.ts +5 -4
  347. package/src/shared/domain/dev/call-guard.ts +29 -28
  348. package/src/shared/domain/dev/carried-text.ts +3 -5
  349. package/src/shared/domain/dev/learn-proposals.ts +5 -4
  350. package/src/shared/domain/dev/learn-state.ts +3 -2
  351. package/src/shared/domain/dev/markers.ts +107 -0
  352. package/src/shared/domain/dev/messages.ts +259 -0
  353. package/src/shared/domain/dev/phase-timing.ts +50 -0
  354. package/src/shared/domain/dev/plan-checks.ts +24 -23
  355. package/src/shared/domain/dev/plan-format.ts +14 -24
  356. package/src/shared/domain/dev/project-files.ts +1 -15
  357. package/src/shared/domain/dev/prompts/brief-blocks.ts +20 -0
  358. package/src/shared/domain/dev/{review-prompt.ts → prompts.ts} +91 -61
  359. package/src/shared/domain/dev/questions.ts +33 -15
  360. package/src/shared/domain/dev/repo-pack.ts +12 -9
  361. package/src/shared/domain/dev/review-answer.ts +40 -17
  362. package/src/shared/domain/dev/review-brief.ts +54 -0
  363. package/src/shared/domain/dev/reviewer-charter.ts +4 -0
  364. package/src/shared/domain/dev/sheet-facts.ts +2 -4
  365. package/src/shared/domain/dev/spec-format.ts +13 -14
  366. package/src/shared/domain/dev/step-budget.ts +4 -2
  367. package/src/shared/domain/dev/step-rules.ts +3 -4
  368. package/src/shared/domain/dev/test-commands.ts +14 -10
  369. package/src/shared/domain/dev/tool-guards.ts +4 -3
  370. package/src/shared/domain/dev/trait-pattern.ts +14 -10
  371. package/src/shared/domain/dev/verdict-format.ts +14 -21
  372. package/src/shared/domain/dev/whitespace.ts +3 -2
  373. package/src/shared/domain/dev/work-folder.ts +4 -3
  374. package/src/shared/domain/dev/yaml-subset.ts +8 -26
  375. package/src/shared/domain/error-text.ts +13 -0
  376. package/src/shared/domain/git/close.ts +5 -4
  377. package/src/shared/domain/git/messages.ts +20 -0
  378. package/src/shared/domain/git/pull-request.ts +5 -5
  379. package/src/shared/domain/host-layout.ts +147 -0
  380. package/src/shared/domain/host-paths.ts +399 -0
  381. package/src/shared/domain/llm-failure.ts +35 -7
  382. package/src/shared/domain/llm-profile.ts +22 -3
  383. package/src/shared/domain/marked-message.ts +1 -5
  384. package/src/shared/domain/markers.ts +30 -0
  385. package/src/shared/domain/messages.ts +291 -0
  386. package/src/shared/domain/model-catalog.ts +2 -9
  387. package/src/shared/domain/permission-modes.ts +4 -8
  388. package/src/shared/domain/prelude.ts +2 -2
  389. package/src/shared/domain/project-manifests.ts +3 -2
  390. package/src/shared/domain/prompts.ts +233 -0
  391. package/src/shared/domain/search-routing.ts +3 -11
  392. package/src/shared/domain/secret-patterns.ts +3 -2
  393. package/src/shared/domain/session-keys.ts +7 -0
  394. package/src/shared/domain/session-start.ts +3 -2
  395. package/src/shared/domain/shared-memory/agent-memory-import.ts +4 -2
  396. package/src/shared/domain/shared-memory/candidates.ts +3 -4
  397. package/src/shared/domain/shared-memory/entry.ts +26 -20
  398. package/src/shared/domain/shared-memory/front-matter.ts +17 -13
  399. package/src/shared/domain/shared-memory/gate.ts +4 -3
  400. package/src/shared/domain/shared-memory/harvest.ts +9 -6
  401. package/src/shared/domain/shared-memory/layout.ts +11 -8
  402. package/src/shared/domain/shared-memory/markers.ts +9 -0
  403. package/src/shared/domain/shared-memory/messages.ts +66 -0
  404. package/src/shared/domain/shared-memory/precedents-block.ts +4 -15
  405. package/src/shared/domain/shared-memory/prompts.ts +28 -0
  406. package/src/shared/domain/shared-memory/refused.ts +3 -3
  407. package/src/shared/domain/skills/prompts.ts +4 -0
  408. package/src/shared/domain/skills/shortlist.ts +149 -0
  409. package/src/shared/domain/snip-turns.ts +2 -14
  410. package/src/shared/domain/speech.ts +2 -1
  411. package/src/shared/domain/tool-trace.ts +5 -7
  412. package/src/shared/domain/verifiers.ts +7 -11
  413. package/src/shared/domain/vfs.ts +8 -1
  414. package/src/shared/domain/workflow/prompts.ts +15 -0
  415. package/src/shared/domain/workflow/state-file.ts +14 -12
  416. package/src/shared/infrastructure/globals.ts +7 -2
  417. package/src/shared/infrastructure/orkeon/child-agents.ts +11 -16
  418. package/src/shared/infrastructure/orkeon/chooser.ts +32 -0
  419. package/src/shared/infrastructure/orkeon/decision-model.ts +31 -0
  420. package/src/shared/infrastructure/orkeon/dev-deps.ts +21 -14
  421. package/src/shared/infrastructure/orkeon/files.ts +24 -6
  422. package/src/shared/infrastructure/orkeon/github-pull-requests.ts +3 -2
  423. package/src/shared/infrastructure/orkeon/host-context.ts +36 -0
  424. package/src/shared/infrastructure/orkeon/human-input.ts +1 -5
  425. package/src/shared/infrastructure/orkeon/llm-profile.ts +36 -16
  426. package/src/shared/infrastructure/orkeon/llm.ts +85 -30
  427. package/src/shared/infrastructure/orkeon/markers.ts +6 -0
  428. package/src/shared/infrastructure/orkeon/memory-store.ts +1 -1
  429. package/src/shared/infrastructure/orkeon/memory-tools.ts +18 -20
  430. package/src/shared/infrastructure/orkeon/messages.ts +15 -0
  431. package/src/shared/infrastructure/orkeon/prompts.ts +47 -0
  432. package/src/shared/infrastructure/orkeon/reasoning.ts +40 -0
  433. package/src/shared/infrastructure/orkeon/script-tools.ts +14 -19
  434. package/src/shared/infrastructure/orkeon/session-store.ts +7 -51
  435. package/src/shared/infrastructure/orkeon/shell-jobs.ts +13 -7
  436. package/src/shared/infrastructure/orkeon/shell.ts +13 -5
  437. package/src/shared/infrastructure/orkeon/tool-catalogue.ts +3 -2
  438. package/src/shared/infrastructure/orkeon/wiring.ts +68 -12
  439. package/src/crews/dev-verify/application/auditor-prompt.ts +0 -323
  440. package/src/shared/domain/session-summary.ts +0 -13
@@ -86,9 +86,13 @@ declare global {
86
86
  readonly clr?: unknown;
87
87
  }
88
88
 
89
- /** Thrown when an agent's execution budget is exhausted. */
89
+ /**
90
+ * Thrown when an agent's execution budget is exhausted, or when the host's budget
91
+ * (`Orkeon:CostTracking:DefaultCrewBudget`) is spent: `tokens` or `cost`, before the call that
92
+ * would go over it.
93
+ */
90
94
  class BudgetExhaustedError extends Error implements HostError {
91
- readonly dimension: "toolCalls" | "delegationDepth" | "wallTime" | "tokens" | "spawnedAgents";
95
+ readonly dimension: "toolCalls" | "delegationDepth" | "wallTime" | "tokens" | "spawnedAgents" | "cost";
92
96
  readonly clrType?: string;
93
97
  readonly clr?: unknown;
94
98
  }
@@ -130,6 +134,21 @@ declare global {
130
134
  readonly clr?: unknown;
131
135
  }
132
136
 
137
+ /**
138
+ * Thrown when the host refuses what the script asked of it (`clrType`
139
+ * `"InvalidScriptException"`): a builder method refusing its argument, a `build()` missing a
140
+ * field, a `stateMachine`/`stateGraph` literal it rejects, `llm.profile` naming a profile the
141
+ * host lacks, an `llm` option out of its domain — synchronous, or the rejection of an awaited
142
+ * `ctx.llm.*` call. A script that tries an optional setting tells it from other failures:
143
+ * `if (!(e instanceof InvalidScriptError)) throw e;`. A value over a domain limit
144
+ * (`"ArgumentException"`) and an out-of-range `ErrorAction.retry` delay
145
+ * (`"OverflowException"`) stay a plain `Error`.
146
+ */
147
+ class InvalidScriptError extends Error implements HostError {
148
+ readonly clrType?: string;
149
+ readonly clr?: unknown;
150
+ }
151
+
133
152
  /**
134
153
  * The code an `onError` handler reads on `err.code` — exactly the codes the runtime's
135
154
  * mapper produces (`ErrorCodeMapper`).
@@ -157,6 +176,11 @@ declare global {
157
176
  readonly role: string;
158
177
  }
159
178
 
179
+ /**
180
+ * A method that refuses its argument, and `build()` missing a field, throws an
181
+ * `InvalidScriptError` the script catches (`try … catch`) — a plain `Error`, its `clrType`
182
+ * `"ArgumentException"`, for a role or goal over the domain's length limit.
183
+ */
160
184
  interface AgentBuilder<TIn = unknown, TOut = unknown, TState = unknown> {
161
185
  name(value: string): this;
162
186
  role(value: string): this;
@@ -179,14 +203,21 @@ declare global {
179
203
  */
180
204
  withResponseSchema(name: string, schema: JsonSchema | string, strict?: boolean): this;
181
205
  allowDelegation(value: boolean): this;
182
- /** The turns the agent may take on a task. Default 20 — YAML parity `maxIter:`. Must be 1 or more. */
206
+ /**
207
+ * The turns the agent may take on a task. Default 20 — YAML parity `maxIter:`. Must be 1 or more.
208
+ * When they run out, the agent gets one tool-free turn to answer, and the task, still successful,
209
+ * is flagged `endedOnIterationCap`.
210
+ */
183
211
  maxIterations(value: number): this;
184
212
  /**
185
- * Turns the provider's thinking on at this effort. Anthropic takes the five levels; a provider whose field
186
- * knows fewer (three for OpenAI's `reasoning_effort` and Ollama's `think`; four, without `xhigh`, for DeepSeek and Z.ai; all five for OpenRouter) sends the highest it knows
187
- * below the one asked, and warns. Applies to the agent's `ctx.llm` calls too, unless a call sets its own.
213
+ * Turns the provider's thinking on at this effort. A provider whose field knows fewer levels (three, the
214
+ * default, for Ollama's `think`, Gemini, Azure OpenAI and Mistral; `low` to `xhigh` for OpenAI and Grok; `low`,
215
+ * `medium`, `high` and `max` for Z.ai; all five for Anthropic, OpenRouter, DeepSeek, Kimi, Qwen, Together AI,
216
+ * Hugging Face, MiniMax and Mammouth AI) sends the highest it knows below the one asked, and warns. The model's
217
+ * entry in the capability table narrows the levels further (GLM-5.3 takes `low`, `high` and `max` only).
218
+ * Applies to the agent's `ctx.llm` calls too, unless a call sets its own.
188
219
  */
189
- effort(level: "low" | "medium" | "high" | "xhigh" | "max"): this;
220
+ effort(level: EffortLevel): this;
190
221
  /**
191
222
  * YAML parity `cache:` — asks the provider's prompt cache to keep the system prompt and/or the
192
223
  * tool definitions. Only a provider whose cache is explicit (Anthropic) needs it; the others cache
@@ -218,6 +249,24 @@ declare global {
218
249
  * parent's, and so does each later `crew.send` to it. Left out, the run is unrooted.
219
250
  */
220
251
  workingRoot(path: string): this;
252
+ /**
253
+ * YAML parity `filesystem:` (#349) — the only virtual paths the agent's tools may touch, each a
254
+ * path or `{ path, access }` with `access` one of `"ro"`, `"rw"`, `"rwnd"` (left out: the
255
+ * mount's own rights). An entry selects and narrows the mount that holds it, never widens it:
256
+ * a path under no mount, or an access the mount does not grant, refuses the agent's run when it
257
+ * starts, never at build. Every other path is refused on every mount, by the file tools,
258
+ * `list_mounts`, the search and RAG tools and `shell_command` alike. A `.workingRoot(...)` must
259
+ * lie inside it. A child started by `spawn_agent` or `ctx.spawnBackground` runs under its
260
+ * parent's scope, which its own can only narrow. Left out, the run's mounts apply.
261
+ */
262
+ filesystem(entries: ReadonlyArray<string | { path: string; access?: "ro" | "rw" | "rwnd" }>): this;
263
+ /**
264
+ * YAML parity `announce_mounts:` (#348) — whether the agent's declarative turns list its
265
+ * virtual paths (its `.filesystem([...])`, else the run's mounts) and its working root in the
266
+ * system prompt, when it has a file-system tool. On by default. A body places that section itself,
267
+ * from `ctx.fileSystem.prompt`, which is `""` when this is off.
268
+ */
269
+ announceMounts(value: boolean): this;
221
270
  concurrency(n: number): this;
222
271
  withState<S>(factory: (() => S) | S): AgentBuilder<TIn, TOut, S>;
223
272
  /**
@@ -313,7 +362,8 @@ declare global {
313
362
  fallback(value: unknown): ErrorAction;
314
363
  /**
315
364
  * Run the body again. `delay` is milliseconds or a duration string ("250ms", "2s");
316
- * `max` caps the attempts, and reaching it rethrows the original error.
365
+ * `max` caps the attempts, and reaching it rethrows the original error. A `delay` that is
366
+ * not a finite number throws an `Error` the script catches.
317
367
  */
318
368
  retry(options?: { delay?: number | string; max?: number }): ErrorAction;
319
369
  };
@@ -364,7 +414,9 @@ declare global {
364
414
  /**
365
415
  * One prompt, the answer. A call a stage of the host's decision profile blocks rejects
366
416
  * with a `DecisionBlockedError`, as `chat`, `extract`, `decide`, `act` and a `stream`
367
- * iteration do; uncaught, it fails the run.
417
+ * iteration do; uncaught, it fails the run. A `llm: { profile }` the host does not offer,
418
+ * or an option it refuses, rejects with an `InvalidScriptError`,
419
+ * as `chat`, `extract` and `decide` do.
368
420
  */
369
421
  complete(prompt: string, opts?: LlmCallOptions): Promise<string>;
370
422
  /** A conversation, the answer. Takes a bare message array or `{ messages: [...] }`. */
@@ -382,6 +434,9 @@ declare global {
382
434
  * reasoning is COUNTED on the returned object, not yielded — it is not
383
435
  * part of the answer, and a caller writing chunks to a file must not
384
436
  * find it there.
437
+ *
438
+ * A `llm: { profile }` the host does not offer throws here, at the call, an `Error` the
439
+ * script catches.
385
440
  */
386
441
  stream(prompt: string, opts?: LlmCallOptions): LlmStream;
387
442
  /**
@@ -403,6 +458,10 @@ declare global {
403
458
  */
404
459
  extract<T>(prompt: string | readonly Message[] | MessageList, schema: JsonSchema, opts?: ExtractOptions): Promise<T>;
405
460
  decide<T extends string>(prompt: string, choices: readonly T[], opts?: LlmCallOptions): Promise<T>;
461
+ /**
462
+ * A deterministic local vector per text, for exercising the API without a model: no provider is
463
+ * called, so `opts` is read by nothing (an unknown `llm.profile` does not throw here).
464
+ */
406
465
  embed(text: string | readonly string[], opts?: LlmCallOptions): Promise<readonly number[][]>;
407
466
  /**
408
467
  * The LLM ⇄ tool-call loop over the agent's tools: `.tools([...])` built-ins and
@@ -410,7 +469,22 @@ declare global {
410
469
  * call, when `.tools([...])` names a tool the host does not offer.
411
470
  */
412
471
  act(prompt: string, opts?: ActOptions): Promise<ActResult>;
413
- /** Cancels the in-flight and future llm calls of this context; a running `act()` resolves with `{ interrupted: true }`. */
472
+ /**
473
+ * What the call these options name sends for the effort (#360), judged as that call is: on the
474
+ * agent's provider, model and effort, the options' own `effort` and `llm: { profile, model }`
475
+ * over them. The report `complete` and `extract` cannot carry, since they return the answer
476
+ * alone; `act`, `chat` and `stream` carry it as `reasoning`. `null` when no effort is asked or
477
+ * no provider answers. Places no call. A `llm: { profile }` the host does not offer throws an
478
+ * `Error` the script catches, listing the known profiles (`llm.profiles`).
479
+ */
480
+ reasoning(opts?: LlmCallOptions): LlmReasoning | null;
481
+ /**
482
+ * What the model of the call these options name takes for reasoning (#359), on the provider
483
+ * that call goes to. `null` when no provider answers. Places no call. A `llm: { profile }` the
484
+ * host does not offer throws an `Error` the script catches, listing the known profiles.
485
+ */
486
+ capabilities(opts?: LlmCallOptions): LlmCapabilities | null;
487
+ /** Cancels the in-flight and future llm calls of this context; a running `act()` resolves with `{ interrupted: true }`. Called after the agent's attempt ended (from a topic handler that outlives it), it does nothing. */
414
488
  interrupt(): void;
415
489
  /** Whether `interrupt()` was requested (or the host cancelled the run). */
416
490
  readonly isInterrupted: boolean;
@@ -429,17 +503,27 @@ declare global {
429
503
  }
430
504
 
431
505
  /**
432
- * The per-call options every `ctx.llm` method reads. Two settings, both PATCHING the host
433
- * provider's configuration for this call only: the response format, and the model. There is
434
- * no per-call provider, temperature or token cap (GAP-12: they were declared here and never
435
- * read), and no `signal` — the call already observes the context's.
506
+ * The per-call options of the `ctx.llm` methods that send a call (`embed`, a local stub, reads
507
+ * none of them). The call runs on the agent's provider, or
508
+ * on the host profile `llm.profile` names; the response format and the model PATCH that
509
+ * provider's configuration for this call only. There is no per-call vendor, temperature or
510
+ * token cap (GAP-12: they were declared here and never read), and no `signal` — the call
511
+ * already observes the context's.
436
512
  */
437
513
  interface LlmCallOptions {
438
514
  responseFormat?: ResponseFormatType;
439
- /** The per-call model: the host's provider keeps its credentials and endpoint. */
440
- llm?: { model?: string };
515
+ /**
516
+ * The per-call LLM. `profile` runs this call on the host profile of that name
517
+ * (`Llm:Profiles:<name>`), by the rule of `llm.profile(name)`: a name the host does not offer
518
+ * throws, listing the known ones; `"default"` is the host's own provider; a decision profile
519
+ * applies its stages to the call. `model` is the per-call model within the call's provider
520
+ * (the profile's when `profile` is set, else the agent's): the provider keeps its
521
+ * credentials and endpoint — `{ profile, model }` is `llm.profile(profile, { model })`. An
522
+ * `LlmConfig` is not accepted here (it throws): its temperature and token cap would not apply.
523
+ */
524
+ llm?: { profile?: string; model?: string; provider?: never };
441
525
  /** Turns the provider's thinking on at this effort for the call. */
442
- effort?: "low" | "medium" | "high" | "xhigh" | "max";
526
+ effort?: EffortLevel;
443
527
  /**
444
528
  * The prompt-cache request of the call, as `agentBuilder().cache(...)` takes it; it wins over the
445
529
  * agent's own. `{}` turns caching off for the call.
@@ -486,6 +570,8 @@ declare global {
486
570
  * also logs progress every 200 deltas.
487
571
  */
488
572
  readonly reasoningChunks: number;
573
+ /** The effort the call asks for and the one the provider sends; `null` when none is asked. Readable at once. */
574
+ readonly reasoning: LlmReasoning | null;
489
575
  }
490
576
 
491
577
  /** Terminal usage of one streamed call, on `LlmStream.usage`. */
@@ -539,24 +625,59 @@ declare global {
539
625
  */
540
626
  onDelta?: (delta: string) => void;
541
627
  /**
542
- * Called before each tool call, after the permission gate allowed it. Answers `"allow"`
543
- * (run it), `"ask"` (hand the call to the approval channel, as a default-mode edit
544
- * would; a refusal denies), `{ deny: reason }` (block, the model reads `DENIED: <reason>`),
545
- * `{ input }` (run with this input, gated again) or `{ context }`. A callback that throws
546
- * denies the call with the exception message. Any other return value (nothing, `null`, a
628
+ * Called with each fragment of a tool call the model is building (when the provider supports
629
+ * SSE streaming): `index` is the call's position in the turn, `id` and `name` come on the
630
+ * fragment that carries them, `argumentsDelta` is a piece of the JSON arguments. Ollama sends
631
+ * a call whole, as one fragment. When the host enforces DLP, the arguments of each call are held
632
+ * until the call ends and arrive in one fragment, redacted. Keep it cheap.
633
+ */
634
+ onToolCallDelta?: (fragment: { index: number; id?: string; name?: string; argumentsDelta: string }) => void;
635
+ /**
636
+ * Called before each tool call, before the permission gate judges it. Answers `"allow"`
637
+ * (hand the call to the gate), `"ask"` (once the mode admits the call, hand it to the
638
+ * approval channel, as a default-mode edit would; a refusal denies), `{ deny: reason }`
639
+ * (block; the gate is not consulted, the model reads `DENIED: <reason>`) or `{ input }` (the
640
+ * input the gate judges, once, then runs with). A callback that throws denies the call with
641
+ * the exception message. Any other return value (nothing, `null`, a
547
642
  * non-object `input`, an unknown shape) denies the call; `"ask"` without a registered
548
643
  * permission gate denies too. The `act` call never rejects because of a returned value.
549
644
  */
550
645
  onToolCall?: (call: { name: string; input: unknown }) =>
551
- "allow" | "ask" | { deny: string } | { input: unknown } | { context: string }
552
- | Promise<"allow" | "ask" | { deny: string } | { input: unknown } | { context: string }>;
646
+ "allow" | "ask" | { deny: string } | { input: unknown }
647
+ | Promise<"allow" | "ask" | { deny: string } | { input: unknown }>;
553
648
  /**
554
649
  * Runs after each tool call, with the call and its result (the tool's JSON parsed, else
555
650
  * its text). A returned `{ context }` replaces the line the model is shown for that
556
- * result; a void return leaves it. Runs on the script's thread.
651
+ * result; a void return leaves it. Runs on the script's thread. Through the host's
652
+ * invocation pipeline (the REPL, `orkeon run`) a call the guardian or the permission gate
653
+ * refused (an operator's refusal included) is a result too, `DENIED: …`; without it, and for
654
+ * a call `onToolCall` denied, a refused call never reaches this callback.
557
655
  */
558
656
  onToolResult?: (call: { name: string; input: unknown }, result: unknown) =>
559
657
  void | { context: string } | Promise<void | { context: string }>;
658
+ /**
659
+ * Runs before a model turn once the loop's messages pass `contextPressure.thresholdTokens`
660
+ * (estimated as characters / 4) and older tool results remain to judge (#327). It is handed
661
+ * the results of the read tools that ran (never a write, a command or a refused call; the last
662
+ * `contextPressure.keepRecent` messages are never offered, nor a result a verdict already
663
+ * settled) and answers by call id: `"keep"`, `"head"` (the result cut to its first
664
+ * `contextPressure.headChars` characters) or `"drop"` (the result replaced by a line naming
665
+ * the call). A pruned result always leaves a line that says what was removed and that the
666
+ * call can be run again. A call left out keeps its result. A callback that throws, or a
667
+ * return that is not an object, prunes nothing and the loop goes on. Runs on the script's
668
+ * thread.
669
+ */
670
+ onContextPressure?: (pressure: ContextPressure) =>
671
+ Record<string, ContextPressureVerdict> | void | Promise<Record<string, ContextPressureVerdict> | void>;
672
+ /** When `onContextPressure` runs, and what `"head"` keeps. */
673
+ contextPressure?: {
674
+ /** Estimated tokens of the loop's messages from which the callback runs. Default 100000. */
675
+ thresholdTokens?: number;
676
+ /** Most recent messages (not turns) whose tool results are never offered. Default 4. */
677
+ keepRecent?: number;
678
+ /** Characters a `"head"` verdict keeps. Default 1000. */
679
+ headChars?: number;
680
+ };
560
681
  /**
561
682
  * Subset of the agent's tools to offer the model for this call. A name the agent does
562
683
  * not hold throws `UnknownToolError` before the model is asked. Omitted: all its tools.
@@ -564,6 +685,30 @@ declare global {
564
685
  tools?: string[];
565
686
  }
566
687
 
688
+ /** What a verdict of `onContextPressure` does to one tool result. */
689
+ type ContextPressureVerdict = "keep" | "head" | "drop";
690
+
691
+ /** What `onContextPressure` is handed. */
692
+ interface ContextPressure {
693
+ /** Estimated tokens of the loop's messages (characters / 4). */
694
+ readonly usedTokens: number;
695
+ /** The `contextPressure.thresholdTokens` the loop passed. */
696
+ readonly thresholdTokens: number;
697
+ /** The share of `usedTokens` held by tool results. */
698
+ readonly usedTokensByKind: { readonly tool: number };
699
+ /** The tool calls whose result may be pruned, oldest first. */
700
+ readonly calls: ReadonlyArray<{
701
+ /** The key to answer with: `call-1`, `call-2`... in call order. */
702
+ readonly id: string;
703
+ readonly name: string;
704
+ readonly input: unknown;
705
+ /** Characters of the result the model is shown. */
706
+ readonly resultChars: number;
707
+ /** Model turns since the call ran. */
708
+ readonly age: number;
709
+ }>;
710
+ }
711
+
567
712
  /** What `act(...)` resolves to. */
568
713
  interface ActResult {
569
714
  /** The model's final answer — or a marker when the loop stopped first. */
@@ -582,6 +727,8 @@ declare global {
582
727
  * `BudgetExhaustedError` instead.
583
728
  */
584
729
  readonly budgetExhausted?: true;
730
+ /** The effort the loop's turns ask for and the one the provider sends; `null` when none is asked. */
731
+ readonly reasoning: LlmReasoning | null;
585
732
  }
586
733
 
587
734
  interface Message {
@@ -592,9 +739,12 @@ declare global {
592
739
 
593
740
  /** What `chat(...)` resolves to. A tool call is `act(...)`'s business: `chat` offers no tools. */
594
741
  interface ChatResponse {
742
+ /** The answer; a provider failure gives the `<undefined-llm:<the provider's error>>` marker, never an empty string, as `complete` does. */
595
743
  readonly content: string;
596
744
  readonly tokensUsed: number;
597
745
  readonly model: string;
746
+ /** The effort the call asks for and the one the provider sends; `null` when none is asked. */
747
+ readonly reasoning: LlmReasoning | null;
598
748
  }
599
749
 
600
750
  interface JsonSchema {
@@ -683,6 +833,29 @@ declare global {
683
833
  * refuses a call when they do not: call `ctx.tools` from a body that runs beside others.
684
834
  */
685
835
  readonly tools: OrkeonTools;
836
+ /**
837
+ * The `## File system` section a declarative turn of this agent holds in its system prompt, for the
838
+ * body to place in the prompt it gives `ctx.llm.act`: nothing is added to that prompt behind its back.
839
+ */
840
+ readonly fileSystem: AgentFileSystem;
841
+ }
842
+
843
+ /** `ctx.fileSystem`: the file-system section of an agent body (#378). */
844
+ interface AgentFileSystem {
845
+ /**
846
+ * The section, from its `## File system` heading to its last line, with no line break around it: the
847
+ * agent's `.filesystem([...])` scope, else the host's agent-facing mounts, sorted by virtual path, each
848
+ * with its rights; its working root, else the directory relative paths resolve against; the note on
849
+ * read-write paths. Read from the mounts at each access, so the same mounts give the same text. `""`
850
+ * when no path is visible, when none of the agent's `.tools([...])` and `withAutonomousTool(s)` uses
851
+ * the file system, or when the agent sets `announceMounts(false)`.
852
+ *
853
+ * ```ts
854
+ * const system = `${MY_PROMPT}\n\n${ctx.fileSystem.prompt}`;
855
+ * return (await ctx.llm.act(String(input), { system })).output;
856
+ * ```
857
+ */
858
+ readonly prompt: string;
686
859
  }
687
860
 
688
861
  /** `ctx.log`: extra arguments are joined to the message by a space, objects as JSON. */
@@ -752,8 +925,12 @@ declare global {
752
925
  * it was declared and always empty, so `result.artifacts.get("x")` compiled and threw.
753
926
  */
754
927
  interface CrewResult {
755
- /** The text of the last non-null agent output; `""` when no agent returned anything. */
756
- readonly output: string;
928
+ /**
929
+ * The last agent output that was not `null` (a body returning `undefined` gives `null`),
930
+ * as the body returned it — the same value as its `tasks[i].output`, an object staying an
931
+ * object, `false`, `0` and `""` counting; `""` when every output was `null`.
932
+ */
933
+ readonly output: unknown;
757
934
  /** One entry per agent run, in the order they ran. */
758
935
  readonly tasks: readonly TaskResult[];
759
936
  }
@@ -802,6 +979,11 @@ declare global {
802
979
  readonly at: number;
803
980
  }
804
981
 
982
+ /**
983
+ * A method that refuses its argument, and `build()` refusing the crew (two agents of one name:
984
+ * a `DuplicateAgentNameError`), throws an error the script catches (`try … catch`), an
985
+ * `InvalidScriptError` otherwise.
986
+ */
805
987
  interface CrewBuilder {
806
988
  name(value: string): this;
807
989
  /** The crew goal; when omitted, one is synthesized from the name. */
@@ -993,7 +1175,8 @@ declare global {
993
1175
  interface FsmTransition<TState extends string = string, TPayload = unknown> {
994
1176
  /**
995
1177
  * Where this event leads. Validated when the literal is built: a target that is not
996
- * a key of `states` throws `InvalidScriptException` before the machine ever runs.
1178
+ * a key of `states` throws an `InvalidScriptError` the script catches before the
1179
+ * machine ever runs.
997
1180
  */
998
1181
  target: TState;
999
1182
  /**
@@ -1037,7 +1220,8 @@ declare global {
1037
1220
  /**
1038
1221
  * Builds a state machine from a literal. Rejects at build time: a missing or non-string
1039
1222
  * `name`/`initial`, a `states` that is not an object, an `initial` that is not declared,
1040
- * a transition without a string `target`, and a `target` naming an undeclared state.
1223
+ * a transition without a string `target`, and a `target` naming an undeclared state. The
1224
+ * refusal is an `InvalidScriptError` the script catches.
1041
1225
  */
1042
1226
  function stateMachine<TState extends string, TPayload = unknown>(
1043
1227
  def: FsmDefinition<TState, TPayload>,
@@ -1076,8 +1260,8 @@ declare global {
1076
1260
  /**
1077
1261
  * What the runner reports as the run's result. Optional: the value of the last
1078
1262
  * expression is used when a script never assigns it. Whatever goes here is serialised
1079
- * to JSON, so assign a plain projection -- a `CrewResult` holds host objects and does
1080
- * not survive the trip.
1263
+ * to JSON: a `CrewResult` goes whole (`output` and `tasks`), a plain projection only
1264
+ * what it names.
1081
1265
  */
1082
1266
  var result: unknown;
1083
1267
  }
@@ -1167,7 +1351,8 @@ declare global {
1167
1351
  }
1168
1352
 
1169
1353
  /**
1170
- * Builds a graph from a literal.
1354
+ * Builds a graph from a literal. A literal it refuses (a bad shape, an invalid topology:
1355
+ * every fault in one message) throws an `InvalidScriptError` the script catches.
1171
1356
  *
1172
1357
  * `TState` cannot be inferred from the node bodies -- a node both takes and returns the
1173
1358
  * state, so inference is circular -- and falls back to `Record<string, unknown>`, which
@@ -1209,11 +1394,74 @@ declare global {
1209
1394
  readonly model: string;
1210
1395
  readonly temperature?: number;
1211
1396
  readonly maxTokens?: number;
1397
+ /**
1398
+ * What the provider and this configuration's model take for reasoning, read from the runtime's capability
1399
+ * table (the host's `Llm:ModelCapabilities` overrides included), by the rule every call is judged with.
1400
+ * `null` when the provider cannot tell (no provider, a test double).
1401
+ */
1402
+ readonly capabilities: LlmCapabilities | null;
1403
+ /**
1404
+ * The effort a call on this configuration asks for and the one the provider sends — the host's
1405
+ * `Llm:Thinking:Effort` included. `null` when no effort is asked or the provider cannot tell. Inside an
1406
+ * agent, `ctx.llm` calls run on the agent's provider, model and effort, which no configuration carries:
1407
+ * read `ctx.llm.reasoning(opts)` there, the report `extract` and `complete` cannot carry.
1408
+ */
1409
+ readonly reasoning: LlmReasoning | null;
1212
1410
 
1213
- /** Returns a copy with the given fields overridden. Any other key is refused. */
1411
+ /**
1412
+ * Returns a copy with the given fields overridden. Any other key, or a value out of its domain,
1413
+ * throws an `InvalidScriptError` the script catches.
1414
+ */
1214
1415
  with(overrides: LlmConfigOverrides): LlmConfig;
1215
1416
  }
1216
1417
 
1418
+ /** An effort level a script may ask for. */
1419
+ type EffortLevel = "low" | "medium" | "high" | "xhigh" | "max";
1420
+
1421
+ /** What a provider and one of its models take for reasoning, on `LlmConfig.capabilities`. */
1422
+ interface LlmCapabilities {
1423
+ /** The model judged: the configuration's, else the provider's own. */
1424
+ readonly model: string;
1425
+ /**
1426
+ * Whether the capability table knows the model. When it does not, the provider's levels rule and an effort
1427
+ * is sent unchecked.
1428
+ */
1429
+ readonly known: boolean;
1430
+ /**
1431
+ * The lower of the provider's and the model's support: `none` (no reasoning pass), `effortOnly` (an effort
1432
+ * hint, no off switch), `toggle` (on and off) or `budget` (a token budget as well).
1433
+ */
1434
+ readonly thinking: "none" | "effortOnly" | "toggle" | "budget";
1435
+ /**
1436
+ * The levels a call sees sent as asked, in order: the provider's, narrowed by the model's entry. Empty when the
1437
+ * model takes no effort or has no reasoning pass. Another level is lowered, or dropped (`LlmReasoning`).
1438
+ */
1439
+ readonly efforts: readonly EffortLevel[];
1440
+ }
1441
+
1442
+ /**
1443
+ * What the runtime does with the effort a call asks for: `reasoning` on `LlmConfig`, `ActResult`, `ChatResponse`
1444
+ * and `LlmStream`, and `ctx.llm.reasoning(opts)`. Judged before the call: a fallback profile answers for its
1445
+ * first link and a decision profile for its target, so a call that fails over, or that a decision routes to
1446
+ * another profile, may be judged otherwise.
1447
+ */
1448
+ interface LlmReasoning {
1449
+ /** The model the call goes to. */
1450
+ readonly model: string;
1451
+ /** The effort asked: the call's `effort`, the agent's, the configuration's, or the host's `Llm:Thinking:Effort`. */
1452
+ readonly asked: EffortLevel;
1453
+ /** The effort sent to the provider; `null` when none is. */
1454
+ readonly sent: EffortLevel | null;
1455
+ /**
1456
+ * `null` when `sent` is `asked` on a model the table knows. Otherwise: `lowered` (the level is not one the
1457
+ * provider and the model both take: the highest one below was sent, or the lowest one when none lies below),
1458
+ * `dropped` (`sent` is `null`: the model takes no effort, the model or the provider has no thinking control,
1459
+ * or the provider's field carries none of the model's levels), or `unchecked` (the table does not know the
1460
+ * model: the effort was sent as asked).
1461
+ */
1462
+ readonly notice: "lowered" | "dropped" | "unchecked" | null;
1463
+ }
1464
+
1217
1465
  /** What `LlmConfig.with(...)` and `llm.model(name, ...)` apply. */
1218
1466
  interface LlmConfigOverrides {
1219
1467
  model?: string;
@@ -1222,11 +1470,14 @@ declare global {
1222
1470
  maxTokens?: number;
1223
1471
  responseFormat?: ResponseFormatType;
1224
1472
  /**
1225
- * Turns thinking on at this level; anything else throws. Anthropic takes the five levels; a provider whose field
1226
- * knows fewer (three for OpenAI's `reasoning_effort` and Ollama's `think`; four, without `xhigh`, for DeepSeek and Z.ai; all five for OpenRouter) sends the highest it knows
1227
- * below the one asked, and warns.
1473
+ * Turns thinking on at this level; anything else throws. A provider whose field knows fewer levels (three, the
1474
+ * default, for Ollama's `think`, Gemini, Azure OpenAI and Mistral; `low` to `xhigh` for OpenAI and Grok; `low`,
1475
+ * `medium`, `high` and `max` for Z.ai; all five for Anthropic, OpenRouter, DeepSeek, Kimi, Qwen, Together AI,
1476
+ * Hugging Face, MiniMax and Mammouth AI) sends the highest it knows below the one asked, and warns. The model's
1477
+ * entry in the capability table narrows the levels further (GLM-5.3 takes `low`, `high` and `max` only):
1478
+ * `LlmConfig.capabilities` lists the levels of the model, `reasoning` says what the call sends.
1228
1479
  */
1229
- effort?: "low" | "medium" | "high" | "xhigh" | "max";
1480
+ effort?: EffortLevel;
1230
1481
  /**
1231
1482
  * The prompt-cache request, as `agentBuilder().cache(...)` takes it; an object that marks nothing
1232
1483
  * cacheable (`{}`) turns caching off, the host default `Llm:Cache` included.
@@ -1258,16 +1509,30 @@ declare global {
1258
1509
  */
1259
1510
  const default_: LlmConfig;
1260
1511
 
1261
- /** `llm.default_` on another model: `llm.default_.with({ model: name, ...overrides })`. */
1512
+ /**
1513
+ * `llm.default_` on another model: `llm.default_.with({ model: name, ...overrides })`. An empty
1514
+ * name or an override `with` refuses throws an `Error` the script catches.
1515
+ */
1262
1516
  function model(name: string, overrides?: Omit<LlmConfigOverrides, "model">): LlmConfig;
1263
1517
 
1264
1518
  /**
1265
1519
  * One of the host's named profiles (`Llm:Profiles:<name>`), on its own model unless
1266
1520
  * `overrides.model` names another. An agent configured with it runs on that profile's
1267
1521
  * provider — its turns and its `ctx.llm` calls. `"default"` is `llm.default_`. A name the
1268
- * host does not offer throws, listing the known profiles.
1522
+ * host does not offer throws an `InvalidScriptError` the script catches (`try … catch`),
1523
+ * listing the known profiles; `llm.profiles` tells beforehand
1524
+ * whether a name is one of them.
1269
1525
  */
1270
1526
  function profile(name: string, overrides?: LlmConfigOverrides): LlmConfig;
1527
+
1528
+ /**
1529
+ * The names `llm.profile(name)` takes (#364): `"default"` first, then the host's profiles
1530
+ * (`Llm:Profiles:<name>`) in the order and the spelling it declared them, those its
1531
+ * allow-list refuses left out. Names only: no endpoint, no key. A frozen array, the same at
1532
+ * every read; `["default"]` on a host that declares no profile. `llm.profile` compares a name
1533
+ * without case (and trims it): compare the same way before asking for one.
1534
+ */
1535
+ const profiles: readonly string[];
1271
1536
  }
1272
1537
  }
1273
1538
 
@@ -1432,6 +1697,22 @@ declare global {
1432
1697
  readonly expectedOutput: string;
1433
1698
  }
1434
1699
 
1700
+ /** The shape of `taskBuilder().retry(...)`, the twin of a YAML task's `retry:` block. */
1701
+ interface TaskRetrySpec {
1702
+ /** How many times the task may run, the first run included (1 or more). */
1703
+ attempts: number;
1704
+ /** The base wait before a new attempt, in milliseconds (default 0). */
1705
+ backoffMs?: number;
1706
+ /** How the wait grows: `"fixed"` (default) or `"exponential"`. */
1707
+ backoff?: "fixed" | "exponential";
1708
+ }
1709
+
1710
+ /**
1711
+ * A method that refuses its argument, and `build()` missing a field, throws an
1712
+ * `InvalidScriptError` the script catches (`try … catch`) — a plain `Error`, its `clrType`
1713
+ * `"ArgumentException"`, for a value the domain refuses (a description or expected output
1714
+ * over its length limit).
1715
+ */
1435
1716
  interface TaskBuilder<TIn = unknown, TOut = unknown> {
1436
1717
  name(value: string): this;
1437
1718
  description(value: string): this;
@@ -1471,6 +1752,17 @@ declare global {
1471
1752
  * once); the four other modes refuse the crew, naming the task.
1472
1753
  */
1473
1754
  asyncExecution(value?: boolean): this;
1755
+ /**
1756
+ * YAML parity `retry: {attempts, backoffMs, backoff}` — a failed attempt runs the WHOLE task
1757
+ * again, tool calls included (nothing deduplicates a call that already succeeded: keep the
1758
+ * task's tools idempotent), up to `attempts` runs in all, the first one included.
1759
+ * `attempts` is required and at least 1; `backoffMs` (default 0) is the wait between runs,
1760
+ * `backoff` how it grows: `"fixed"` (default) or `"exponential"` (doubling, capped at five
1761
+ * minutes). Never retried: a cancellation, a refusal of the guardian, an exhausted budget.
1762
+ * A decision task cannot have one. In `.process("graph")` it is the only retry: the mode has
1763
+ * no retry loop of its own.
1764
+ */
1765
+ retry(spec: TaskRetrySpec): this;
1474
1766
  /**
1475
1767
  * YAML parity task-level `tools:` — names, `toolBuilder()` instances, or an
1476
1768
  * array mixing both. They ADD to the assigned agent's own tools, for this task
@@ -1481,8 +1773,14 @@ declare global {
1481
1773
  tools(value: string | Tool<unknown, unknown> | readonly (string | Tool<unknown, unknown>)[]): this;
1482
1774
  /**
1483
1775
  * First-class deliverable contract — mirror of YAML's `deliverable: { ... }`
1484
- * block. The framework writes the produced output to `path` and (when the
1485
- * source is `structured_output`) validates against the inline `schema`.
1776
+ * block. With `source: "final_message"` the framework writes the final answer
1777
+ * as-is to `path`; with `"structured_output"` it writes the JSON, checked against
1778
+ * `schema`. With `"tool_call"` the agent writes the file itself, so an agent
1779
+ * that may run the task needs a tool that writes that format (`file_write` for a
1780
+ * text file, `docx_writer`, `xlsx_writer`, `image_generation`, `firefox` for
1781
+ * theirs): the load warns otherwise, and a task that
1782
+ * succeeds without writing it is flagged `deliverableMissing`. `"none"` declares
1783
+ * no file.
1486
1784
  */
1487
1785
  deliverable(spec: TaskDeliverableSpec): this;
1488
1786
  /**
@@ -1498,7 +1796,7 @@ declare global {
1498
1796
  /**
1499
1797
  * Runs this task only when the named decision task's answers match `clauses`, or
1500
1798
  * (`"otherwise"`) when no other task gated on that decision matches. A task takes one
1501
- * `.when()`: a second call throws an `InvalidScriptException` naming the task.
1799
+ * `.when()`: a second call throws an `Error` naming the task.
1502
1800
  */
1503
1801
  when(decisionTask: string, clauses: WhenClauses | "otherwise"): this;
1504
1802
  build(): Task<TIn, TOut>;
@@ -1536,6 +1834,11 @@ declare global {
1536
1834
  */
1537
1835
  interface TaskDeliverableSpec {
1538
1836
  path: string;
1837
+ /**
1838
+ * `tool_call`: the agent writes `path` with a writer tool; `final_message`: the
1839
+ * framework saves the final answer; `structured_output`: the framework saves the
1840
+ * schema-checked JSON; `none`: no file.
1841
+ */
1539
1842
  source: "final_message" | "structured_output" | "tool_call" | "none";
1540
1843
  format?: "markdown" | "json" | "text";
1541
1844
  sanitize?: boolean;
@@ -1547,6 +1850,94 @@ declare global {
1547
1850
  function taskBuilder<TIn = unknown, TOut = unknown>(): TaskBuilder<TIn, TOut>;
1548
1851
  }
1549
1852
 
1853
+ export { };
1854
+ // Orkeon Scripting DSL — the `test` namespace
1855
+ // Declares the mocks and assertions a script reads under `orkeon run --test`: `test.mockLlm`,
1856
+ // `test.mockTool(...)`, `test.assertLlmCalled(...)` and `test.assertToolCalled(...)`.
1857
+ //
1858
+ // The global exists ONLY under `orkeon run --test`. A script run without the flag has no `test`:
1859
+ // referencing it fails with a ReferenceError, so a mock never hides in a production run. Under
1860
+ // `--test` the host's configured LLM (or the `mock` profile of `--llm-mock`) stays behind the mock:
1861
+ // a prompt an expectation of `test.mockLlm` fits is answered by it, any other prompt goes to the
1862
+ // configured provider.
1863
+
1864
+ declare global {
1865
+ /** What a mocked tool or model answers for the calls an expectation matched. */
1866
+ interface MockLlmExpectation {
1867
+ /**
1868
+ * The answer: a string, an object carrying a `content` string, or any value (stringified as a
1869
+ * last resort).
1870
+ */
1871
+ respond(response: string | { readonly content: string } | unknown): void;
1872
+ }
1873
+
1874
+ /** `test.mockLlm`: opens expectations on the model the script runs on. */
1875
+ interface MockLlmHandle {
1876
+ /**
1877
+ * Starts an expectation for prompts that contain the string (case ignored), or match the regular
1878
+ * expression, of `{ prompt: ... }`. The first expectation that fits a prompt answers it. Complete
1879
+ * it with `.respond(...)`. A regular expression .NET cannot read (`/\u{41}/u`) throws at
1880
+ * `.respond(...)` an `Error` the script catches, its `clrType` `"RegexParseException"`.
1881
+ */
1882
+ when(matcher: string | { readonly prompt: string | RegExp }): MockLlmExpectation;
1883
+ }
1884
+
1885
+ /** What one mocked tool returns for the calls an expectation matched. */
1886
+ interface MockToolExpectation {
1887
+ /** The value the tool returns for the matched calls. */
1888
+ respond(response: unknown): void;
1889
+ }
1890
+
1891
+ /** `test.mockTool(name)`: one mocked tool, created on first use. */
1892
+ interface MockToolHandle {
1893
+ /**
1894
+ * Starts an expectation for calls whose parameters equal the object, key by key. Complete it with
1895
+ * `.respond(...)`.
1896
+ */
1897
+ when(matcher: Readonly<Record<string, unknown>>): MockToolExpectation;
1898
+
1899
+ /** The value the tool returns when no expectation matches. */
1900
+ respond(response: unknown): void;
1901
+ }
1902
+
1903
+ /** The options of `test.assertLlmCalled`. */
1904
+ interface AssertLlmCalledOptions {
1905
+ /** The exact number of calls; left out, at least one is required. */
1906
+ readonly times?: number;
1907
+ /** Count only the calls whose prompt contains this text (case ignored). */
1908
+ readonly with?: string;
1909
+ }
1910
+
1911
+ /** The options of `test.assertToolCalled`. */
1912
+ interface AssertToolCalledOptions {
1913
+ /** The exact number of calls; left out, at least one is required. */
1914
+ readonly times?: number;
1915
+ }
1916
+
1917
+ namespace test {
1918
+ /** Opens expectations on the model: `test.mockLlm.when("weather").respond("sunny")`. */
1919
+ const mockLlm: MockLlmHandle;
1920
+
1921
+ /**
1922
+ * The mocked tool named `name`, created on first use. An empty name throws an `Error` the
1923
+ * script catches, its `clrType` `"ArgumentException"`.
1924
+ */
1925
+ function mockTool(name: string): MockToolHandle;
1926
+
1927
+ /**
1928
+ * Throws when the model was not called as `options` says: an `Error` the script catches,
1929
+ * its `clrType` `"AssertionException"`.
1930
+ */
1931
+ function assertLlmCalled(options?: AssertLlmCalledOptions): void;
1932
+
1933
+ /**
1934
+ * Throws when the mocked tool `name` was not called as `options` says, or is unknown: an
1935
+ * `Error` the script catches, its `clrType` `"AssertionException"`.
1936
+ */
1937
+ function assertToolCalled(name: string, options?: AssertToolCalledOptions): void;
1938
+ }
1939
+ }
1940
+
1550
1941
  export { };
1551
1942
  // Orkeon Scripting DSL — Custom tool builder
1552
1943
  // Declares Tool, ToolBuilder, and the schema shapes a script-defined tool exposes to the LLM.
@@ -1571,6 +1962,10 @@ declare global {
1571
1962
  execute(input: TIn, ctx?: unknown): TOut | Promise<TOut>;
1572
1963
  }
1573
1964
 
1965
+ /**
1966
+ * A method that refuses its argument, and `build()` missing a field, throws an
1967
+ * `InvalidScriptError` the script catches (`try … catch`).
1968
+ */
1574
1969
  interface ToolBuilder<TIn = unknown, TOut = unknown> {
1575
1970
  name(value: string): this;
1576
1971
  description(value: string): this;
@@ -2302,7 +2697,7 @@ declare global {
2302
2697
  bolt_uri: string;
2303
2698
  /** Target database name in ArcadeDB */
2304
2699
  database: string;
2305
- /** Maximum number of result records to return */
2700
+ /** Maximum number of result records to return, at least 1 (default 1000) */
2306
2701
  max_results?: number;
2307
2702
  /** Query parameters as key-value pairs */
2308
2703
  parameters?: Record<string, unknown> | null;
@@ -2370,7 +2765,7 @@ declare global {
2370
2765
  include_metrics?: boolean;
2371
2766
  /** Level of the entries: L0_Monorepo, L1_Package (default), L2_Module or L3_Symbol. */
2372
2767
  level?: "L0_Monorepo" | "L1_Package" | "L2_Module" | "L3_Symbol" | "L4_Statement";
2373
- /** Most entries returned (default 200); truncated says when more exist. */
2768
+ /** Most entries returned, at least 1 (default 200); truncated says when more exist. */
2374
2769
  max_entries?: number;
2375
2770
  /** Keep only the entries at or under this node (a package or folder by path, a namespace by its files and name, a type by FQN); a node id, an FQN or a path. */
2376
2771
  root_fqn?: string | null;
@@ -2399,7 +2794,7 @@ declare global {
2399
2794
  mode?: "Hybrid" | "Vector" | "Lexical";
2400
2795
  /** A symbol name, or words describing what the code does. */
2401
2796
  query: string;
2402
- /** Most hits returned (default 10); truncated says when more match. */
2797
+ /** Most hits returned, at least 1 (default 10); truncated says when more match. */
2403
2798
  top_k?: number;
2404
2799
  }, ctx?: ExecutionContext): Promise<{
2405
2800
  readonly hits: readonly { readonly fqn: string; readonly match_origin: string; readonly score: number; readonly signature?: string; readonly summary_short?: string; }[];
@@ -2414,7 +2809,7 @@ declare global {
2414
2809
  metric?: "Cyclomatic" | "NestingDepth" | "FanOut" | "LoC" | "Callers";
2415
2810
  /** Keep only the symbols under this FQN. */
2416
2811
  root_fqn?: string | null;
2417
- /** How many symbols are listed, the highest first (default 20). */
2812
+ /** How many symbols are listed, the highest first, at least 1 (default 20). */
2418
2813
  top_n?: number;
2419
2814
  }, ctx?: ExecutionContext): Promise<{
2420
2815
  readonly evaluated_count: number;
@@ -2430,7 +2825,7 @@ declare global {
2430
2825
  distinct_matches?: boolean;
2431
2826
  /** Return the matched substrings themselves (capped by max_matches_returned) */
2432
2827
  include_matches?: boolean;
2433
- /** Cap on the returned matches list size (only applies when include_matches=true) */
2828
+ /** Cap on the returned matches list size, at least 1 (default: 200); read only when include_matches is true. To count without listing matches, leave include_matches false */
2434
2829
  max_matches_returned?: number | null;
2435
2830
  /** Apply RegexOptions.Multiline so ^/$ match line starts/ends */
2436
2831
  multiline?: boolean;
@@ -2450,7 +2845,7 @@ declare global {
2450
2845
  delimiter?: string;
2451
2846
  /** Whether the CSV file has a header row (default: true) */
2452
2847
  has_header?: boolean;
2453
- /** Maximum number of rows to read (default: no limit) */
2848
+ /** Maximum number of rows to read, at least 1 (default: no limit); truncated tells whether rows were left out */
2454
2849
  max_rows?: number | null;
2455
2850
  /** The file path of the CSV file to read */
2456
2851
  path: string;
@@ -2482,7 +2877,7 @@ declare global {
2482
2877
 
2483
2878
  /** `dependency_graph` - What depends on what at this scope? Returns the nodes and the edges of the given edge_kinds (imports by default) among the packages (L1_Package), modules (L2_Module) or symbols (L3_Symbol) of the scope, at most max_nodes nodes (200) selected by root_fqn and node_kinds, truncated when the scope holds more; cycles and cycle_count cover the whole scope, each cycle naming its members as FQNs. For every edge of a kind across the index, edge_list; for the neighbourhood of a symbol, sub_graph. */
2484
2879
  dependencyGraph(input?: {
2485
- /** Edge kinds to follow, by name: contains, calls, imports, inherits, tests, documents, project_depends. Legacy enum names (Imports, Extends, Implements...) are still accepted. */
2880
+ /** Edge kinds to follow, by name: contains, calls, imports, inherits, extends, implements, tests, documents, project_depends, case-insensitively; inherits is extends and implements together. */
2486
2881
  edge_kinds?: readonly string[];
2487
2882
  /** Add a Graphviz DOT rendering (dot). */
2488
2883
  include_dot?: boolean;
@@ -2490,11 +2885,11 @@ declare global {
2490
2885
  include_external?: boolean;
2491
2886
  /** Add a Mermaid flowchart of the nodes and edges (mermaid_flowchart), for a human reader; false by default: the data alone answers an agent. */
2492
2887
  include_mermaid?: boolean;
2493
- /** Most members returned per cycle. member_count keeps the full size. */
2888
+ /** Most members returned per cycle, at least 1 (default 50). member_count keeps the full size. */
2494
2889
  max_cycle_members?: number;
2495
- /** Most cycles returned, the largest first. cycle_count keeps the full count. */
2890
+ /** Most cycles returned, at least 0 (default 20), the largest first; 0 lists none. cycle_count keeps the full count. */
2496
2891
  max_cycles?: number;
2497
- /** Most nodes returned (default 200); truncated says when more exist. */
2892
+ /** Most nodes returned, at least 1 (default 200); truncated says when more exist. */
2498
2893
  max_nodes?: number;
2499
2894
  /** Restrict nodes to these kinds, by name: file, project, namespace, type, member, doc_section, test. Empty keeps every node of the scope. */
2500
2895
  node_kinds?: readonly string[];
@@ -2614,7 +3009,7 @@ declare global {
2614
3009
  edgeList(input: {
2615
3010
  /** The next_cursor of the previous page; omit it for the first page. */
2616
3011
  cursor?: string | null;
2617
- /** Edge kinds to list, by name: contains, calls, imports, inherits, tests, documents, project_depends. Legacy enum names (Imports, Extends, Implements...) are still accepted. inherits lists both extends and implements edges. */
3012
+ /** Edge kinds to list, by name: contains, calls, imports, inherits, extends, implements, tests, documents, project_depends, case-insensitively; inherits is extends and implements together. */
2618
3013
  edge_kinds: readonly string[];
2619
3014
  /** Edges per page, 1 to 1000 (default 200). */
2620
3015
  page_size?: number;
@@ -2664,7 +3059,7 @@ declare global {
2664
3059
  encoding?: "UTF-8" | "ASCII" | "Unicode" | "UTF-32";
2665
3060
  /** Maximum number of lines to return (default: up to the end of the file); max_length caps the result further */
2666
3061
  limit?: number | null;
2667
- /** Maximum number of characters to read (default: no limit). Applied after offset/limit: when it cuts a line range, only whole lines are kept and has_more is true, except that when the first line alone exceeds max_length it is cut by characters. */
3062
+ /** Maximum number of characters to read, at least 1 (default: no limit; omit it for no limit). Applied after offset/limit: when it cuts a line range, only whole lines are kept and has_more is true, except that when the first line alone exceeds max_length it is cut by characters. */
2668
3063
  max_length?: number | null;
2669
3064
  /** First line to return (1-based, default 1 when limit is given). With offset/limit the file is streamed and not read beyond the range; max_length then caps the range */
2670
3065
  offset?: number | null;
@@ -2702,19 +3097,68 @@ declare global {
2702
3097
  readonly success: boolean;
2703
3098
  }>;
2704
3099
 
3100
+ /** `firefox` - Drive a Firefox browser: open a page (navigate), read it as an outline of sections, links and controls (snapshot, find, read), find its sections by meaning (search), then act on a node by its id (click, type), press keys, run a script (evaluate) or save a screenshot. Tabs of its own are opened, listed, switched and closed (new_tab, tabs, switch_tab, close_tab). The browser stays open between calls of the same run, or from one run to the next when the host keeps it; close ends it. */
3101
+ firefox(input: {
3102
+ /** What to do: navigate (url), back, snapshot (the outline of the page: sections, links, controls, each with a node id), read (the text of the page, or of node_id), find (nodes by kind and name, under node_id), search (query: the sections of the page closest in meaning), click (node_id), type (node_id, text), press (key), evaluate (script), screenshot (save_to_path), tabs (the tabs of this agent), new_tab (url, optional), switch_tab (tab), close_tab (tab, the current one by default), close */
3103
+ action: "navigate" | "back" | "snapshot" | "read" | "find" | "search" | "click" | "type" | "press" | "evaluate" | "screenshot" | "tabs" | "new_tab" | "switch_tab" | "close_tab" | "close";
3104
+ /** press: a key or a chord on the focused element - Enter, Tab, Escape, ArrowDown, PageDown, a, Control+a, Shift+Tab */
3105
+ key?: string | null;
3106
+ /** find: only nodes of this kind */
3107
+ kind?: "section" | "link" | "control" | null;
3108
+ /** snapshot, find: the most nodes to return (the default is set by the host, 200 at most); search: the most hits (5 by default, 20 at most) */
3109
+ max_nodes?: number | null;
3110
+ /** find: only nodes whose name holds this text, whatever the case */
3111
+ name?: string | null;
3112
+ /** A node id returned by snapshot or find (p1#12). click, type: the element; read: the node to read; find: search under this node */
3113
+ node_id?: string | null;
3114
+ /** snapshot, find: nodes to skip, to read the next part of a listing; read: characters to skip */
3115
+ offset?: number | null;
3116
+ /** The profile the browser starts with, at the first action of a run: disposable, or a profile name the host allows; a browser already open keeps its profile */
3117
+ profile?: string | null;
3118
+ /** search: what to look for in the page, in plain words; the sections closest in meaning are returned */
3119
+ query?: string | null;
3120
+ /** screenshot: the virtual path the PNG image of the visible part of the page is written to (/output/page.png) */
3121
+ save_to_path?: string | null;
3122
+ /** evaluate: a JavaScript expression run in the page; its value is returned, a promise is awaited */
3123
+ script?: string | null;
3124
+ /** switch_tab, close_tab: the handle of a tab of this agent (t1, t2), as tabs lists them */
3125
+ tab?: string | null;
3126
+ /** type: the text that replaces what the element holds; a line feed presses Enter. Never a secret: the text goes through the conversation */
3127
+ text?: string | null;
3128
+ /** navigate, new_tab: the http or https address to open */
3129
+ url?: string | null;
3130
+ }, ctx?: ExecutionContext): Promise<{
3131
+ readonly action: string;
3132
+ readonly dialogs?: readonly string[];
3133
+ readonly error?: string;
3134
+ readonly hits?: readonly { readonly excerpt: string; readonly name: string; readonly node_id: string; readonly score: number; }[];
3135
+ readonly nodes?: readonly { readonly id: string; readonly kind: string; readonly name: string; readonly parent_id?: string; readonly role: string; readonly text: string; }[];
3136
+ readonly profile?: string;
3137
+ readonly saved_path?: string;
3138
+ readonly success: boolean;
3139
+ readonly tab?: string;
3140
+ readonly tabs?: readonly { readonly current: boolean; readonly id: string; readonly title: string; readonly url: string; }[];
3141
+ readonly text?: string;
3142
+ readonly title?: string;
3143
+ readonly total_nodes?: number;
3144
+ readonly truncated: boolean;
3145
+ readonly url?: string;
3146
+ readonly value?: string;
3147
+ }>;
3148
+
2705
3149
  /** `flow_trace` - How does control get from this symbol to that one? Returns the shortest call path from from to to, or with include_all_paths every path up to max_depth hops and max_paths paths (20), truncated when more exist; without to, the paths from from. edge_kinds takes calls by default. For the neighbourhood of one symbol, sub_graph. */
2706
3150
  flowTrace(input: {
2707
3151
  /** Forward follows calls out of from; Backward follows them into from; Both. */
2708
3152
  direction?: "Forward" | "Backward" | "Both";
2709
- /** Edge kinds to follow, by name: contains, calls, imports, inherits, tests, documents, project_depends. Legacy enum names (Imports, Extends, Implements...) are still accepted. Empty follows calls. */
3153
+ /** Edge kinds to follow, by name: contains, calls, imports, inherits, extends, implements, tests, documents, project_depends, case-insensitively; inherits is extends and implements together. Empty follows calls. */
2710
3154
  edge_kinds?: readonly string[];
2711
3155
  /** FQN the paths start from. */
2712
3156
  from: string;
2713
3157
  /** With to: every path up to max_paths instead of the shortest one. */
2714
3158
  include_all_paths?: boolean;
2715
- /** Most hops per path (default 4). */
3159
+ /** Most hops per path, at least 1 (default 4). */
2716
3160
  max_depth?: number;
2717
- /** Most paths returned (default 20); truncated says when more exist. */
3161
+ /** Most paths returned, at least 1 (default 20); truncated says when more exist. */
2718
3162
  max_paths?: number;
2719
3163
  /** FQN the paths must reach; omit it to list every path from the start. */
2720
3164
  to?: string | null;
@@ -2796,11 +3240,11 @@ declare global {
2796
3240
  readonly vertex_labels: readonly { readonly count_estimate?: number; readonly label: string; readonly properties: readonly string[]; }[];
2797
3241
  }>;
2798
3242
 
2799
- /** `grep` - Which files contain this text? Searches the lines of the text files under path with a regex, glob filtering the files relative to path, and returns path:line:text hits with total_matches and files_matched; output_mode "count" returns the counts alone, so a "how many" question takes one call. At most max_results hits (200) over max_files files (2000) within a 20 s budget; binary and over-1-MiB files are skipped; truncated and scan_complete say when the scan was cut. To find files by name, glob; to search code by structure, structural_search; to search by meaning, codebase_search. */
3243
+ /** `grep` - Which files contain this text? Searches the lines of the text files under path with a regex, glob filtering the files relative to path (a file as path is searched alone, without glob), and returns path:line:text hits with total_matches and files_matched; output_mode "count" returns the counts alone, so a "how many" question takes one call. At most max_results hits (200) over max_files files (2000) within a 20 s budget; binary and over-1-MiB files are skipped; truncated and scan_complete say when the scan was cut. To find files by name, glob; to search code by structure, structural_search; to search by meaning, codebase_search. */
2800
3244
  grep(input: {
2801
3245
  /** Case-insensitive matching */
2802
3246
  case_insensitive?: boolean;
2803
- /** Optional file filter relative to path (never absolute); all files when absent */
3247
+ /** Optional file filter relative to a folder path (never absolute, never with a file path); all files when absent */
2804
3248
  glob?: string | null;
2805
3249
  /** Maximum number of files scanned; binary or unreadable files are skipped and counted (default: 2000) */
2806
3250
  max_files?: number;
@@ -2808,7 +3252,7 @@ declare global {
2808
3252
  max_results?: number;
2809
3253
  /** hits: one path:line:text per match (default); the scan is not stopped by max_results, it reads up to max_files or the 20 s budget, so a wide search can come back timed_out or truncated. count: no hit lines, only total_matches, files_matched and the per-file counts (the max_results highest) */
2810
3254
  output_mode?: "hits" | "count";
2811
- /** Root directory searched (virtual path, a mounted directory inside the agent root) */
3255
+ /** Directory searched, or one file searched alone (then no glob); a virtual path inside the agent root */
2812
3256
  path: string;
2813
3257
  /** Regular expression searched in each line (per-match timeout; the scan stops and timed_out is set on a timeout) */
2814
3258
  pattern: string;
@@ -2893,9 +3337,9 @@ declare global {
2893
3337
  impactAnalysis(input: {
2894
3338
  /** Backward (default) lists what depends on target; Forward what target depends on; Both. */
2895
3339
  direction?: "Forward" | "Backward" | "Both";
2896
- /** Most hops followed for the transitive impact (default 3). */
3340
+ /** Most hops followed for the transitive impact, at least 1 (default 3). */
2897
3341
  max_depth?: number;
2898
- /** Most symbols visited (default 500); truncated says when the walk stopped early. */
3342
+ /** Most symbols visited, at least 1 (default 500); truncated says when the walk stopped early. */
2899
3343
  max_nodes?: number;
2900
3344
  /** FQN of the symbol about to change. */
2901
3345
  target: string;
@@ -2912,12 +3356,8 @@ declare global {
2912
3356
  incrementalReindex(input: {
2913
3357
  /** Virtual paths of the files to reindex; omit them to take the files changed between from_commit and to_commit. */
2914
3358
  changed_files?: readonly string[];
2915
- /** Ask the LLM for a summary of each symbol while reindexing (slow). */
2916
- enrich_with_llm?: boolean;
2917
3359
  /** Commit the diff starts from when changed_files is omitted. */
2918
3360
  from_commit?: string | null;
2919
- /** Languages reindexed; empty keeps every supported language. */
2920
- languages?: readonly string[];
2921
3361
  /** Virtual path of the indexed root. */
2922
3362
  root_path: string;
2923
3363
  /** Commit the diff ends at (default HEAD). */
@@ -2938,7 +3378,7 @@ declare global {
2938
3378
 
2939
3379
  /** `index_codebase` - Scan the codebase and build the full RaggableTree index, reusing the one saved by an earlier session when the host wires the cache. */
2940
3380
  indexCodebase(input: {
2941
- /** Identifier of the embedding model the host wires (default text-embedding-3-small). */
3381
+ /** Embedding model to record when the host's provider does not name its own (default text-embedding-3-small). */
2942
3382
  embedding_model?: string;
2943
3383
  /** Ask the LLM for a summary of each symbol while indexing (slow). */
2944
3384
  enrich_with_llm?: boolean;
@@ -2993,7 +3433,7 @@ declare global {
2993
3433
  bindings?: Record<string, unknown> | null;
2994
3434
  /** Gremlin WebSocket endpoint URI */
2995
3435
  gremlin_endpoint: string;
2996
- /** Maximum number of results to return */
3436
+ /** Maximum number of results to return, at least 1 (default 1000) */
2997
3437
  max_results?: number;
2998
3438
  /** Timeout in milliseconds for traversal execution */
2999
3439
  timeout_ms?: number;
@@ -3049,7 +3489,7 @@ declare global {
3049
3489
  mariadbQuery(input: {
3050
3490
  /** Database connection string */
3051
3491
  connection_string: string;
3052
- /** Maximum number of rows to return for SELECT queries */
3492
+ /** Maximum number of rows to return for SELECT queries, at least 1 and at most 100000 on a SELECT (default 1000); truncated tells whether rows were left out */
3053
3493
  max_rows?: number;
3054
3494
  /** Optional named parameters for parameterized queries (e.g. {"active": true}) */
3055
3495
  parameters?: Record<string, unknown> | null;
@@ -3059,7 +3499,7 @@ declare global {
3059
3499
  query: string;
3060
3500
  /** Type of query: Select (returns rows), Execute (returns affected rows count), or Scalar (returns single value) */
3061
3501
  query_type?: "Select" | "Execute" | "Scalar";
3062
- /** Query timeout in seconds */
3502
+ /** Query timeout in seconds, at least 1 (default 30) */
3063
3503
  timeout_seconds?: number;
3064
3504
  }, ctx?: ExecutionContext): Promise<{
3065
3505
  readonly affected_rows?: number;
@@ -3071,6 +3511,7 @@ declare global {
3071
3511
  readonly row_count?: number;
3072
3512
  readonly rows?: readonly Record<string, unknown>[];
3073
3513
  readonly scalar_result?: unknown;
3514
+ readonly truncated?: boolean;
3074
3515
  }>;
3075
3516
 
3076
3517
  /** `mdx_search` - Perform semantic search within Markdown (.md, .mdx) files using RAG embeddings. Strips frontmatter and JSX before searching. */
@@ -3125,7 +3566,7 @@ declare global {
3125
3566
  document?: string | null;
3126
3567
  /** JSON filter document for Find/Update/Delete/Count/Distinct operations */
3127
3568
  filter?: string | null;
3128
- /** Maximum number of documents to return (default 100) */
3569
+ /** Maximum number of documents to return for Find, at least 1 (default 100) */
3129
3570
  limit?: number;
3130
3571
  /** Operation to perform: Find, Aggregate, InsertOne, UpdateOne, DeleteOne, Count, Distinct */
3131
3572
  operation: "Find" | "Aggregate" | "InsertOne" | "UpdateOne" | "DeleteOne" | "Count" | "Distinct";
@@ -3133,7 +3574,7 @@ declare global {
3133
3574
  pipeline?: string | null;
3134
3575
  /** JSON projection document for Find operations */
3135
3576
  projection?: string | null;
3136
- /** Number of documents to skip */
3577
+ /** Number of documents to skip for Find, at least 0 (default 0) */
3137
3578
  skip?: number;
3138
3579
  /** JSON sort document for Find operations */
3139
3580
  sort?: string | null;
@@ -3169,7 +3610,7 @@ declare global {
3169
3610
  mysqlQuery(input: {
3170
3611
  /** Database connection string */
3171
3612
  connection_string: string;
3172
- /** Maximum number of rows to return for SELECT queries */
3613
+ /** Maximum number of rows to return for SELECT queries, at least 1 and at most 100000 on a SELECT (default 1000); truncated tells whether rows were left out */
3173
3614
  max_rows?: number;
3174
3615
  /** Optional named parameters for parameterized queries (e.g. {"active": true}) */
3175
3616
  parameters?: Record<string, unknown> | null;
@@ -3179,7 +3620,7 @@ declare global {
3179
3620
  query: string;
3180
3621
  /** Type of query: Select (returns rows), Execute (returns affected rows count), or Scalar (returns single value) */
3181
3622
  query_type?: "Select" | "Execute" | "Scalar";
3182
- /** Query timeout in seconds */
3623
+ /** Query timeout in seconds, at least 1 (default 30) */
3183
3624
  timeout_seconds?: number;
3184
3625
  }, ctx?: ExecutionContext): Promise<{
3185
3626
  readonly affected_rows?: number;
@@ -3191,6 +3632,7 @@ declare global {
3191
3632
  readonly row_count?: number;
3192
3633
  readonly rows?: readonly Record<string, unknown>[];
3193
3634
  readonly scalar_result?: unknown;
3635
+ readonly truncated?: boolean;
3194
3636
  }>;
3195
3637
 
3196
3638
  /** `node_ensure` - Applies one idempotent intent operation on one file: ensure_using / ensure_import (name, plus module for TypeScript or JavaScript) adds the using or import line in its place only when absent; ensure_field / ensure_member (selector of the type, text) adds a field, property or method next to its peers only when no member of that name exists. On Markdown: ensure_section (name = heading path, optional level) creates the missing headings; insert_under_heading (selector, text) appends at the end of a section; replace_mermaid (selector, index 0-based, text) replaces the body of the n-th mermaid fence of a section. Calling it again changes nothing and writes nothing: applied is false and range is the existing line or member. The insert is refused when it introduces a parse error that was not there before, the file is then untouched. */
@@ -3281,7 +3723,7 @@ declare global {
3281
3723
  include_dependencies?: boolean;
3282
3724
  /** Return the public exports of the package. */
3283
3725
  include_public_exports?: boolean;
3284
- /** Most exports returned (default 50); truncated says when more exist. */
3726
+ /** Most exports returned, at least 1 (default 50); truncated says when more exist. */
3285
3727
  max_exports?: number;
3286
3728
  }, ctx?: ExecutionContext): Promise<{
3287
3729
  readonly dependencies: readonly string[];
@@ -3338,7 +3780,7 @@ declare global {
3338
3780
  metadata?: Record<string, string> | null;
3339
3781
  /** JSON payload */
3340
3782
  payload?: unknown;
3341
- /** Mailbox URI (agent://, crew://, topic://, or client:// for an external client such as Studio) */
3783
+ /** Mailbox URI (agent://, crew://, topic://, or client:// for an external client) */
3342
3784
  target_mailbox: string;
3343
3785
  }, ctx?: ExecutionContext): Promise<{
3344
3786
  readonly message_id: string;
@@ -3349,7 +3791,7 @@ declare global {
3349
3791
  postgresQuery(input: {
3350
3792
  /** Database connection string */
3351
3793
  connection_string: string;
3352
- /** Maximum number of rows to return for SELECT queries */
3794
+ /** Maximum number of rows to return for SELECT queries, at least 1 and at most 100000 on a SELECT (default 1000); truncated tells whether rows were left out */
3353
3795
  max_rows?: number;
3354
3796
  /** Optional named parameters for parameterized queries (e.g. {"active": true}) */
3355
3797
  parameters?: Record<string, unknown> | null;
@@ -3359,7 +3801,7 @@ declare global {
3359
3801
  query: string;
3360
3802
  /** Type of query: Select (returns rows), Execute (returns affected rows count), or Scalar (returns single value) */
3361
3803
  query_type?: "Select" | "Execute" | "Scalar";
3362
- /** Query timeout in seconds */
3804
+ /** Query timeout in seconds, at least 1 (default 30) */
3363
3805
  timeout_seconds?: number;
3364
3806
  }, ctx?: ExecutionContext): Promise<{
3365
3807
  readonly affected_rows?: number;
@@ -3371,6 +3813,7 @@ declare global {
3371
3813
  readonly row_count?: number;
3372
3814
  readonly rows?: readonly Record<string, unknown>[];
3373
3815
  readonly scalar_result?: unknown;
3816
+ readonly truncated?: boolean;
3374
3817
  }>;
3375
3818
 
3376
3819
  /** `progress_report` - Report the progress of a long-running scripted operation (label, step/total or percent, message). */
@@ -3418,7 +3861,7 @@ declare global {
3418
3861
  compare?: string | null;
3419
3862
  /** Virtual path of the golden dataset YAML (e.g. '/workspace/examples/rag/eval/golden.yaml') */
3420
3863
  dataset: string;
3421
- /** Metric cutoff for recall@k / precision@k (default: 5) */
3864
+ /** Metric cutoff for recall@k / precision@k, at least 1 (default: 5) */
3422
3865
  k?: number;
3423
3866
  /** Profile to evaluate (default: 'default') */
3424
3867
  profile?: string | null;
@@ -3452,7 +3895,7 @@ declare global {
3452
3895
  collection?: string | null;
3453
3896
  /** The question to search for in knowledge bases */
3454
3897
  question: string;
3455
- /** Number of relevant chunks to retrieve (default: 3) */
3898
+ /** Number of relevant chunks to retrieve, at least 1 (default: 3) */
3456
3899
  top_k?: number;
3457
3900
  }, ctx?: ExecutionContext): Promise<{
3458
3901
  readonly answer: string;
@@ -3476,7 +3919,7 @@ declare global {
3476
3919
  relationalDatabaseQuery(input: {
3477
3920
  /** Database connection string */
3478
3921
  connection_string: string;
3479
- /** Maximum number of rows to return for SELECT queries */
3922
+ /** Maximum number of rows to return for SELECT queries, at least 1 and at most 100000 on a SELECT (default 1000); truncated tells whether rows were left out */
3480
3923
  max_rows?: number;
3481
3924
  /** Optional named parameters for parameterized queries (e.g. {"active": true}) */
3482
3925
  parameters?: Record<string, unknown> | null;
@@ -3486,7 +3929,7 @@ declare global {
3486
3929
  query: string;
3487
3930
  /** Type of query: Select (returns rows), Execute (returns affected rows count), or Scalar (returns single value) */
3488
3931
  query_type?: "Select" | "Execute" | "Scalar";
3489
- /** Query timeout in seconds */
3932
+ /** Query timeout in seconds, at least 1 (default 30) */
3490
3933
  timeout_seconds?: number;
3491
3934
  }, ctx?: ExecutionContext): Promise<{
3492
3935
  readonly affected_rows?: number;
@@ -3498,6 +3941,7 @@ declare global {
3498
3941
  readonly row_count?: number;
3499
3942
  readonly rows?: readonly Record<string, unknown>[];
3500
3943
  readonly scalar_result?: unknown;
3944
+ readonly truncated?: boolean;
3501
3945
  }>;
3502
3946
 
3503
3947
  /** `reply_to` - Reply to a pending request identified by correlation_id. */
@@ -3637,7 +4081,7 @@ declare global {
3637
4081
  sqlserverQuery(input: {
3638
4082
  /** Database connection string */
3639
4083
  connection_string: string;
3640
- /** Maximum number of rows to return for SELECT queries */
4084
+ /** Maximum number of rows to return for SELECT queries, at least 1 and at most 100000 on a SELECT (default 1000); truncated tells whether rows were left out */
3641
4085
  max_rows?: number;
3642
4086
  /** Optional named parameters for parameterized queries (e.g. {"active": true}) */
3643
4087
  parameters?: Record<string, unknown> | null;
@@ -3647,7 +4091,7 @@ declare global {
3647
4091
  query: string;
3648
4092
  /** Type of query: Select (returns rows), Execute (returns affected rows count), or Scalar (returns single value) */
3649
4093
  query_type?: "Select" | "Execute" | "Scalar";
3650
- /** Query timeout in seconds */
4094
+ /** Query timeout in seconds, at least 1 (default 30) */
3651
4095
  timeout_seconds?: number;
3652
4096
  }, ctx?: ExecutionContext): Promise<{
3653
4097
  readonly affected_rows?: number;
@@ -3659,6 +4103,7 @@ declare global {
3659
4103
  readonly row_count?: number;
3660
4104
  readonly rows?: readonly Record<string, unknown>[];
3661
4105
  readonly scalar_result?: unknown;
4106
+ readonly truncated?: boolean;
3662
4107
  }>;
3663
4108
 
3664
4109
  /** `statement_query` - Query L4 statements by kind, parent FQN, or semantic similarity. */
@@ -3669,7 +4114,7 @@ declare global {
3669
4114
  parent_fqns?: readonly string[];
3670
4115
  /** Words describing the statements wanted; ranks the hits by similarity. */
3671
4116
  semantic_query?: string | null;
3672
- /** Most hits returned (default 50); truncated says when more exist. */
4117
+ /** Most hits returned, at least 1 (default 50); truncated says when more exist. */
3673
4118
  top_k?: number;
3674
4119
  }, ctx?: ExecutionContext): Promise<{
3675
4120
  readonly hits: readonly { readonly condition?: string; readonly end_line?: number; readonly expression?: string; readonly kind: string; readonly parent_fqn: string; readonly score?: number; readonly start_line: number; readonly statement_id: string; }[];
@@ -3686,7 +4131,7 @@ declare global {
3686
4131
  glob?: string | null;
3687
4132
  /** Language of the pattern and of the files rewritten (csharp, typescript, python...). Required with pattern or rule; a rule_file names its own. */
3688
4133
  language?: string;
3689
- /** Most files scanned (default 500); truncated says when more were candidates. */
4134
+ /** Most files scanned, at least 1 (default 500); truncated says when more were candidates. */
3690
4135
  max_files?: number;
3691
4136
  /** Virtual paths of the files or folders rewritten; empty takes the mounted roots. */
3692
4137
  paths?: readonly string[];
@@ -3708,9 +4153,9 @@ declare global {
3708
4153
  glob?: string | null;
3709
4154
  /** Language of the pattern and of the files searched (csharp, typescript, python, markdown...). Required with pattern or rule; a rule_file names its own. */
3710
4155
  language?: string;
3711
- /** Most files scanned (default 500); truncated says when more were candidates. */
4156
+ /** Most files scanned, at least 1 (default 500); truncated says when more were candidates. */
3712
4157
  max_files?: number;
3713
- /** Most matches returned (default 100); truncated says when more exist. */
4158
+ /** Most matches returned, at least 1 (default 100); truncated says when more exist. */
3714
4159
  max_results?: number;
3715
4160
  /** Virtual paths of the files or folders searched; empty searches the mounted roots. */
3716
4161
  paths?: readonly string[];
@@ -3728,15 +4173,15 @@ declare global {
3728
4173
 
3729
4174
  /** `sub_graph` - What surrounds these symbols? Expands the graph from the seeds (FQNs) along edge_kinds, Forward (what they call or extend) or Backward (who calls or extends them), up to depth hops and max_nodes nodes (100); truncated says when the expansion stopped early. For the whole graph at a scope, dependency_graph; for the paths between two symbols, flow_trace. */
3730
4175
  subGraph(input: {
3731
- /** How many hops from the seeds (default 2). */
4176
+ /** How many hops from the seeds, at least 1 (default 2). */
3732
4177
  depth?: number;
3733
4178
  /** Forward follows the edges from the seeds (what X calls, what X extends); Backward follows them into the seeds (who calls X, who extends X); Both. */
3734
4179
  direction?: "Forward" | "Backward" | "Both";
3735
- /** Edge kinds to follow, by name: contains, calls, imports, inherits, tests, documents, project_depends. Legacy enum names (Imports, Extends, Implements...) are still accepted. */
4180
+ /** Edge kinds to follow, by name: contains, calls, imports, inherits, extends, implements, tests, documents, project_depends, case-insensitively; inherits is extends and implements together. */
3736
4181
  edge_kinds?: readonly string[];
3737
4182
  /** Add a Mermaid flowchart of the nodes and edges (mermaid_flowchart), for a human reader; false by default: the data alone answers an agent. */
3738
4183
  include_mermaid?: boolean;
3739
- /** Most nodes returned (default 100); truncated says when the expansion stopped before its depth. */
4184
+ /** Most nodes returned, at least 1 (default 100); truncated says when the expansion stopped before its depth. */
3740
4185
  max_nodes?: number;
3741
4186
  /** Keep only expanded nodes of these kinds, by name: file, project, namespace, type, member, doc_section, test. Empty keeps every node. */
3742
4187
  node_kinds?: readonly string[];
@@ -3761,7 +4206,7 @@ declare global {
3761
4206
  include_doc?: boolean;
3762
4207
  /** Return the signature. */
3763
4208
  include_signature?: boolean;
3764
- /** Most members returned under Members (default 50); truncated says when more exist. */
4209
+ /** Most members returned under Members, 1 to 200 (default 50); truncated says when more exist. */
3765
4210
  max_children?: number;
3766
4211
  }, ctx?: ExecutionContext): Promise<{
3767
4212
  readonly body?: { readonly await_count: number; readonly branch_count: number; readonly call_count: number; readonly closure_count: number; readonly cyclomatic_complexity: number; readonly early_return_count: number; readonly is_partial: boolean; readonly loop_count: number; readonly max_depth: number; readonly statement_count: number; readonly try_catch_count: number; };
@@ -3787,7 +4232,7 @@ declare global {
3787
4232
  symbolSource(input: {
3788
4233
  /** FQN of the symbol to cite. */
3789
4234
  fqn: string;
3790
- /** Most lines returned (default 40); truncated says when the span is longer. */
4235
+ /** Most lines returned, at least 1 (default 40); truncated says when the span is longer. */
3791
4236
  max_lines?: number;
3792
4237
  /** Span cited: SignatureOnly, SignatureAndDoc, SignatureAndBody (default), FullSpan, StatementSpan (with statement_id). */
3793
4238
  mode?: "SignatureOnly" | "SignatureAndDoc" | "SignatureAndBody" | "FullSpan" | "StatementSpan";