orkeon-code 0.0.0-stage → 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (423) hide show
  1. package/.orkeon-version +1 -0
  2. package/LICENSE.md +21 -0
  3. package/NOTICE.md +17 -0
  4. package/README.fr.md +169 -0
  5. package/README.md +162 -2
  6. package/config/appsettings.anthropic.example.json +77 -0
  7. package/config/appsettings.example.json +71 -0
  8. package/config/appsettings.jev.example.json +128 -0
  9. package/config/appsettings.kev.example.json +130 -0
  10. package/config/appsettings.liquid.example.json +129 -0
  11. package/config/appsettings.ollama-whisper.example.json +92 -0
  12. package/config/appsettings.ollama.example.json +70 -0
  13. package/config/appsettings.whisper.example.json +31 -0
  14. package/mcp/whisper/README.md +293 -0
  15. package/mcp/whisper/pyproject.toml +32 -0
  16. package/mcp/whisper/uv.lock +1641 -0
  17. package/mcp/whisper/whisper_mcp.py +1053 -0
  18. package/orkeon-code +897 -0
  19. package/orkeon-code.mjs +71 -0
  20. package/orkeon-code.ps1 +837 -0
  21. package/package.json +57 -4
  22. package/scripts/install.ps1 +156 -0
  23. package/scripts/install.sh +148 -0
  24. package/scripts/session-start.ork.ts +90 -0
  25. package/scripts/session-start.sh +74 -0
  26. package/scripts/setup-fixture.sh +88 -0
  27. package/src/commands/.orkeon/orkeon-cli.d.ts +562 -0
  28. package/src/commands/_lib/args.ts +193 -0
  29. package/src/commands/_lib/dev/dev-batches.ts +368 -0
  30. package/src/commands/_lib/dev/dev-implement.ts +188 -0
  31. package/src/commands/_lib/dev/dev-source.ts +65 -0
  32. package/src/commands/_lib/dev/dev.ts +344 -0
  33. package/src/commands/_lib/dev-step.ts +142 -0
  34. package/src/commands/_lib/dispatch.ts +231 -0
  35. package/src/commands/_lib/effort.ts +15 -0
  36. package/src/commands/_lib/git/branch.ts +95 -0
  37. package/src/commands/_lib/git/commit.ts +94 -0
  38. package/src/commands/_lib/git/diff.ts +97 -0
  39. package/src/commands/_lib/git/review.ts +109 -0
  40. package/src/commands/_lib/memory/memory-admit.ts +150 -0
  41. package/src/commands/_lib/memory/memory.ts +51 -0
  42. package/src/commands/_lib/pr-context.ts +32 -0
  43. package/src/commands/_lib/project/analyze.ts +24 -0
  44. package/src/commands/_lib/session/export.ts +104 -0
  45. package/src/commands/_lib/session/resume.ts +160 -0
  46. package/src/commands/_lib/session/tasks.ts +184 -0
  47. package/src/commands/_lib/settings/advisor.ts +80 -0
  48. package/src/commands/_lib/settings/agents.ts +147 -0
  49. package/src/commands/_lib/settings/config.ts +141 -0
  50. package/src/commands/_lib/settings/hooks.ts +58 -0
  51. package/src/commands/_lib/settings/mode.ts +91 -0
  52. package/src/commands/_lib/settings/model.ts +146 -0
  53. package/src/commands/_lib/settings/permissions.ts +309 -0
  54. package/src/commands/_lib/settings/session-config.ts +49 -0
  55. package/src/commands/_lib/settings/skills.ts +51 -0
  56. package/src/commands/_lib/speech/say.ts +96 -0
  57. package/src/commands/_lib/speech/transcribe.ts +130 -0
  58. package/src/commands/_lib/speech/voice.ts +146 -0
  59. package/src/commands/_lib/status/cache.ts +31 -0
  60. package/src/commands/_lib/status/context.ts +57 -0
  61. package/src/commands/_lib/status/doctor.ts +186 -0
  62. package/src/commands/_lib/status/meta.ts +45 -0
  63. package/src/commands/_lib/status/status.ts +129 -0
  64. package/src/commands/_lib/status/usage-tools.ts +49 -0
  65. package/src/commands/_lib/status/usage.ts +139 -0
  66. package/src/commands/_lib/view.ts +29 -0
  67. package/src/commands/dev/dev-batches.cmd.ts +108 -0
  68. package/src/commands/dev/dev-learn.cmd.ts +29 -0
  69. package/src/commands/dev/dev-plan.cmd.ts +52 -0
  70. package/src/commands/dev/dev-spec.cmd.ts +55 -0
  71. package/src/commands/dev/dev-status.cmd.ts +16 -0
  72. package/src/commands/git/branch.cmd.ts +27 -0
  73. package/src/commands/git/commit.cmd.ts +48 -0
  74. package/src/commands/git/diff.cmd.ts +26 -0
  75. package/src/commands/git/review.cmd.ts +36 -0
  76. package/src/commands/memory/memory.cmd.ts +48 -0
  77. package/src/commands/project/analyze.cmd.ts +32 -0
  78. package/src/commands/project/debug-tool-call.cmd.ts +67 -0
  79. package/src/commands/project/files.cmd.ts +22 -0
  80. package/src/commands/project/init-verifiers.cmd.ts +14 -0
  81. package/src/commands/project/init.cmd.ts +14 -0
  82. package/src/commands/project/verify.cmd.ts +27 -0
  83. package/src/commands/session/assistant.cmd.ts +40 -0
  84. package/src/commands/session/btw.cmd.ts +18 -0
  85. package/src/commands/session/clear.cmd.ts +19 -0
  86. package/src/commands/session/compact.cmd.ts +16 -0
  87. package/src/commands/session/copy.cmd.ts +44 -0
  88. package/src/commands/session/exit.cmd.ts +9 -0
  89. package/src/commands/session/export.cmd.ts +28 -0
  90. package/src/commands/session/rename.cmd.ts +17 -0
  91. package/src/commands/session/resume.cmd.ts +19 -0
  92. package/src/commands/session/rewind.cmd.ts +26 -0
  93. package/src/commands/session/summary.cmd.ts +27 -0
  94. package/src/commands/session/tasks.cmd.ts +44 -0
  95. package/src/commands/settings/advisor.cmd.ts +38 -0
  96. package/src/commands/settings/agents.cmd.ts +19 -0
  97. package/src/commands/settings/config.cmd.ts +17 -0
  98. package/src/commands/settings/effort.cmd.ts +40 -0
  99. package/src/commands/settings/fast.cmd.ts +17 -0
  100. package/src/commands/settings/hooks.cmd.ts +17 -0
  101. package/src/commands/settings/mode.cmd.ts +20 -0
  102. package/src/commands/settings/model.cmd.ts +20 -0
  103. package/src/commands/settings/output-style.cmd.ts +48 -0
  104. package/src/commands/settings/permissions.cmd.ts +25 -0
  105. package/src/commands/settings/proactive.cmd.ts +15 -0
  106. package/src/commands/settings/skills.cmd.ts +17 -0
  107. package/src/commands/speech/say.cmd.ts +24 -0
  108. package/src/commands/speech/transcribe.cmd.ts +29 -0
  109. package/src/commands/speech/voice.cmd.ts +30 -0
  110. package/src/commands/status/context.cmd.ts +18 -0
  111. package/src/commands/status/doctor.cmd.ts +27 -0
  112. package/src/commands/status/release-notes.cmd.ts +9 -0
  113. package/src/commands/status/status.cmd.ts +25 -0
  114. package/src/commands/status/usage.cmd.ts +21 -0
  115. package/src/crews/.orkeon/orkeon.d.ts +3946 -0
  116. package/src/crews/_probe-shared-memory/domain/probe-verdict.ts +183 -0
  117. package/src/crews/_probe-shared-memory/probe.ork.ts +98 -0
  118. package/src/crews/advisor/application/run-advisor.ts +40 -0
  119. package/src/crews/advisor/crew.ork.ts +43 -0
  120. package/src/crews/advisor/domain/advice.ts +135 -0
  121. package/src/crews/agent-run/application/run-agent-run.ts +42 -0
  122. package/src/crews/agent-run/crew.ork.ts +67 -0
  123. package/src/crews/analyze/application/run-analyze.ts +118 -0
  124. package/src/crews/analyze/crew.ork.ts +40 -0
  125. package/src/crews/analyze/domain/harvest.ts +301 -0
  126. package/src/crews/code-review/application/prompts.ts +133 -0
  127. package/src/crews/code-review/application/review.ts +71 -0
  128. package/src/crews/code-review/application/run-code-review.ts +123 -0
  129. package/src/crews/code-review/crew.ork.ts +51 -0
  130. package/src/crews/code-review/domain/lenses.ts +193 -0
  131. package/src/crews/code-review/domain/report.ts +59 -0
  132. package/src/crews/code-review/domain/scope.ts +112 -0
  133. package/src/crews/dev-batches/application/plan-close.ts +181 -0
  134. package/src/crews/dev-batches/application/run-dev-batches.ts +669 -0
  135. package/src/crews/dev-batches/application/run-wave.ts +450 -0
  136. package/src/crews/dev-batches/application/seed-harvest.ts +162 -0
  137. package/src/crews/dev-batches/crew.ork.ts +143 -0
  138. package/src/crews/dev-batches/domain/batch-waves.ts +70 -0
  139. package/src/crews/dev-batches/domain/batches-budget.ts +52 -0
  140. package/src/crews/dev-batches/domain/batches-log.ts +54 -0
  141. package/src/crews/dev-batches/domain/wave-order.ts +43 -0
  142. package/src/crews/dev-change/application/change-prompt.ts +104 -0
  143. package/src/crews/dev-change/application/evidence.ts +169 -0
  144. package/src/crews/dev-change/application/run-dev-change.ts +315 -0
  145. package/src/crews/dev-change/crew.ork.ts +112 -0
  146. package/src/crews/dev-change/domain/change-answer.ts +159 -0
  147. package/src/crews/dev-change/domain/change-render.ts +79 -0
  148. package/src/crews/dev-implement/application/close.ts +183 -0
  149. package/src/crews/dev-implement/application/count-open-steps.ts +24 -0
  150. package/src/crews/dev-implement/application/locate-sheet.ts +80 -0
  151. package/src/crews/dev-implement/application/observe.ts +50 -0
  152. package/src/crews/dev-implement/application/report-writes.ts +41 -0
  153. package/src/crews/dev-implement/application/run-dev-implement.ts +811 -0
  154. package/src/crews/dev-implement/application/run-role.ts +27 -0
  155. package/src/crews/dev-implement/application/suite-job.ts +118 -0
  156. package/src/crews/dev-implement/application/touched.ts +74 -0
  157. package/src/crews/dev-implement/crew.ork.ts +68 -0
  158. package/src/crews/dev-implement/domain/contracts.ts +256 -0
  159. package/src/crews/dev-implement/domain/correction.ts +102 -0
  160. package/src/crews/dev-implement/domain/cycles.ts +35 -0
  161. package/src/crews/dev-implement/domain/implement-budget.ts +29 -0
  162. package/src/crews/dev-implement/domain/roles.ts +53 -0
  163. package/src/crews/dev-implement/domain/sheet-edits.ts +75 -0
  164. package/src/crews/dev-implement/domain/sheet-ticks.ts +22 -0
  165. package/src/crews/dev-implement/domain/step-checks.ts +136 -0
  166. package/src/crews/dev-implement/domain/step-section.ts +127 -0
  167. package/src/crews/dev-learn/application/learn-backlog.ts +58 -0
  168. package/src/crews/dev-learn/application/learn-prompt.ts +140 -0
  169. package/src/crews/dev-learn/application/run-dev-learn.ts +553 -0
  170. package/src/crews/dev-learn/crew.ork.ts +52 -0
  171. package/src/crews/dev-learn/domain/learn-answer.ts +235 -0
  172. package/src/crews/dev-learn/domain/owner-lines.ts +86 -0
  173. package/src/crews/dev-learn/domain/proposals-render.ts +96 -0
  174. package/src/crews/dev-plan/application/anchor-paths.ts +76 -0
  175. package/src/crews/dev-plan/application/inventory.ts +170 -0
  176. package/src/crews/dev-plan/application/plan-prompt.ts +159 -0
  177. package/src/crews/dev-plan/application/run-dev-plan.ts +455 -0
  178. package/src/crews/dev-plan/crew.ork.ts +109 -0
  179. package/src/crews/dev-plan/domain/inventory-model.ts +95 -0
  180. package/src/crews/dev-plan/domain/plan-answer.ts +738 -0
  181. package/src/crews/dev-plan/domain/plan-render.ts +307 -0
  182. package/src/crews/dev-spec/application/run-dev-spec.ts +206 -0
  183. package/src/crews/dev-spec/application/spec-prompt.ts +98 -0
  184. package/src/crews/dev-spec/crew.ork.ts +108 -0
  185. package/src/crews/dev-spec/domain/spec-answer.ts +253 -0
  186. package/src/crews/dev-spec/domain/spec-render.ts +76 -0
  187. package/src/crews/dev-verify/application/audit.ts +259 -0
  188. package/src/crews/dev-verify/application/auditor-prompt.ts +323 -0
  189. package/src/crews/dev-verify/application/capture.ts +303 -0
  190. package/src/crews/dev-verify/application/run-dev-verify.ts +409 -0
  191. package/src/crews/dev-verify/application/run-gate.ts +202 -0
  192. package/src/crews/dev-verify/crew.ork.ts +103 -0
  193. package/src/crews/dev-verify/domain/audit-answer.ts +150 -0
  194. package/src/crews/dev-verify/domain/auditor-charter.ts +21 -0
  195. package/src/crews/dev-verify/domain/capture-sections.ts +137 -0
  196. package/src/crews/dev-verify/domain/commands.ts +103 -0
  197. package/src/crews/dev-verify/domain/gate.ts +126 -0
  198. package/src/crews/dev-verify/domain/mechanical-table.ts +163 -0
  199. package/src/crews/dev-verify/domain/runtime-cut.ts +13 -0
  200. package/src/crews/dev-verify/domain/sheet-facts.ts +4 -0
  201. package/src/crews/dev-verify/domain/text.ts +20 -0
  202. package/src/crews/dev-verify/domain/verdict.ts +127 -0
  203. package/src/crews/git-commit/application/draft.ts +154 -0
  204. package/src/crews/git-commit/application/run-git-commit.ts +116 -0
  205. package/src/crews/git-commit/crew.ork.ts +52 -0
  206. package/src/crews/git-commit/domain/commit.ts +220 -0
  207. package/src/crews/init-verifiers/application/authoring.ts +89 -0
  208. package/src/crews/init-verifiers/application/prompts.ts +103 -0
  209. package/src/crews/init-verifiers/application/run-init-verifiers.ts +25 -0
  210. package/src/crews/init-verifiers/crew.ork.ts +34 -0
  211. package/src/crews/init-verifiers/domain/commands-section.ts +36 -0
  212. package/src/crews/init-verifiers/domain/readiness.ts +23 -0
  213. package/src/crews/main-loop/application/auto-compact.ts +77 -0
  214. package/src/crews/main-loop/application/context-gather.ts +133 -0
  215. package/src/crews/main-loop/application/run-main-loop.ts +350 -0
  216. package/src/crews/main-loop/application/turn-prompt.ts +112 -0
  217. package/src/crews/main-loop/crew.ork.ts +119 -0
  218. package/src/crews/main-loop/domain/autocompact.ts +27 -0
  219. package/src/crews/main-loop/domain/prompt-assembly.ts +521 -0
  220. package/src/crews/main-loop/domain/turn-chains.ts +129 -0
  221. package/src/crews/project-init/application/detect.ts +122 -0
  222. package/src/crews/project-init/application/prompts.ts +101 -0
  223. package/src/crews/project-init/application/run-project-init.ts +31 -0
  224. package/src/crews/project-init/crew.ork.ts +35 -0
  225. package/src/crews/project-init/domain/conventions.ts +36 -0
  226. package/src/crews/project-init/domain/existing-files.ts +63 -0
  227. package/src/crews/project-init/domain/package-map.ts +73 -0
  228. package/src/crews/session-compact/crew.ork.ts +55 -0
  229. package/src/crews/shared-memory-admit/crew.ork.ts +48 -0
  230. package/src/crews/speech/application/run-speech.ts +25 -0
  231. package/src/crews/speech/crew.ork.ts +37 -0
  232. package/src/shared/application/agents/child-agent.ts +255 -0
  233. package/src/shared/application/agents/run-sub-agent.ts +96 -0
  234. package/src/shared/application/answer-language.ts +14 -0
  235. package/src/shared/application/attached-skills.ts +36 -0
  236. package/src/shared/application/compaction/compact-session.ts +237 -0
  237. package/src/shared/application/compaction/extract-memories.ts +38 -0
  238. package/src/shared/application/compaction/restore-context.ts +78 -0
  239. package/src/shared/application/config-store.ts +123 -0
  240. package/src/shared/application/dev/brief-inventory.ts +113 -0
  241. package/src/shared/application/dev/close-batch.ts +83 -0
  242. package/src/shared/application/dev/find-repo-pack.ts +77 -0
  243. package/src/shared/application/dev/learn-decision.ts +252 -0
  244. package/src/shared/application/dev/load-dev-context.ts +266 -0
  245. package/src/shared/application/dev/measure-access-cost.ts +68 -0
  246. package/src/shared/application/dev/plan-source.ts +112 -0
  247. package/src/shared/application/dev/preflight.ts +71 -0
  248. package/src/shared/application/dev/project-files.ts +17 -0
  249. package/src/shared/application/dev/question-round.ts +52 -0
  250. package/src/shared/application/dev/resolve-work-folder.ts +133 -0
  251. package/src/shared/application/dev/script-tool-slot.ts +27 -0
  252. package/src/shared/application/dev/settle-questions.ts +55 -0
  253. package/src/shared/application/dev/source-review.ts +63 -0
  254. package/src/shared/application/dev/source-step.ts +150 -0
  255. package/src/shared/application/dev/spend.ts +42 -0
  256. package/src/shared/application/dev/step-precedents.ts +89 -0
  257. package/src/shared/application/dev/tool-call-policy.ts +89 -0
  258. package/src/shared/application/dev/tool-callbacks.ts +215 -0
  259. package/src/shared/application/dev/tool-trace-recorder.ts +45 -0
  260. package/src/shared/application/dev/verdict-sources.ts +48 -0
  261. package/src/shared/application/dev/wrapped-tools.ts +145 -0
  262. package/src/shared/application/extra-tools.ts +70 -0
  263. package/src/shared/application/git/batch-worktree.ts +97 -0
  264. package/src/shared/application/git/commit-files.ts +186 -0
  265. package/src/shared/application/git/merge-batch.ts +63 -0
  266. package/src/shared/application/git/open-pull-request.ts +51 -0
  267. package/src/shared/application/instructions-file.ts +19 -0
  268. package/src/shared/application/json-file.ts +34 -0
  269. package/src/shared/application/llm-profile.ts +35 -0
  270. package/src/shared/application/permission-rules.ts +159 -0
  271. package/src/shared/application/ports/approvals.ts +20 -0
  272. package/src/shared/application/ports/clock.ts +5 -0
  273. package/src/shared/application/ports/code-index.ts +93 -0
  274. package/src/shared/application/ports/crew.ts +60 -0
  275. package/src/shared/application/ports/files.ts +21 -0
  276. package/src/shared/application/ports/human.ts +13 -0
  277. package/src/shared/application/ports/llm.ts +54 -0
  278. package/src/shared/application/ports/memory.ts +30 -0
  279. package/src/shared/application/ports/progress.ts +23 -0
  280. package/src/shared/application/ports/runtime.ts +15 -0
  281. package/src/shared/application/ports/session.ts +74 -0
  282. package/src/shared/application/ports/shared-memory.ts +26 -0
  283. package/src/shared/application/ports/shell.ts +40 -0
  284. package/src/shared/application/ports/telemetry.ts +45 -0
  285. package/src/shared/application/ports/tools.ts +46 -0
  286. package/src/shared/application/ports/usage.ts +45 -0
  287. package/src/shared/application/ports.ts +27 -0
  288. package/src/shared/application/project-manifests.ts +106 -0
  289. package/src/shared/application/session-io.ts +84 -0
  290. package/src/shared/application/session-state.ts +36 -0
  291. package/src/shared/application/shared-memory/admit-entries.ts +177 -0
  292. package/src/shared/application/shared-memory/harvest-after-gaps.ts +72 -0
  293. package/src/shared/application/shared-memory/harvest-mistakes.ts +44 -0
  294. package/src/shared/application/shared-memory/import-agent-memory.ts +117 -0
  295. package/src/shared/application/shared-memory/memory-files.ts +110 -0
  296. package/src/shared/application/shared-memory/memory-settings.ts +93 -0
  297. package/src/shared/application/shared-memory/push-candidate.ts +146 -0
  298. package/src/shared/application/shared-memory/recall-precedents.ts +69 -0
  299. package/src/shared/application/state-snapshot.ts +38 -0
  300. package/src/shared/application/workflow/workflow-state.ts +135 -0
  301. package/src/shared/domain/agent-policy/behavior-flags.ts +168 -0
  302. package/src/shared/domain/agent-policy/extra-tools.ts +69 -0
  303. package/src/shared/domain/agent-policy/memory-categories.ts +6 -0
  304. package/src/shared/domain/agent-policy/mode-policy.ts +51 -0
  305. package/src/shared/domain/agent-policy/output-styles.ts +11 -0
  306. package/src/shared/domain/agent-policy/permission.ts +623 -0
  307. package/src/shared/domain/agent-policy/rule-sets.ts +412 -0
  308. package/src/shared/domain/agent-policy/tool-access.ts +77 -0
  309. package/src/shared/domain/agent-registry.ts +142 -0
  310. package/src/shared/domain/agents/built-in-charters.ts +43 -0
  311. package/src/shared/domain/agents/chain.ts +30 -0
  312. package/src/shared/domain/agents/charter.ts +61 -0
  313. package/src/shared/domain/agents/exclusive.ts +24 -0
  314. package/src/shared/domain/agents/instances.ts +249 -0
  315. package/src/shared/domain/code-intel-contract.ts +356 -0
  316. package/src/shared/domain/code-intel-routing.ts +113 -0
  317. package/src/shared/domain/compact-outcome.ts +44 -0
  318. package/src/shared/domain/compaction-thresholds.ts +161 -0
  319. package/src/shared/domain/compaction.ts +379 -0
  320. package/src/shared/domain/config-schema.ts +421 -0
  321. package/src/shared/domain/dev/access-cost.ts +226 -0
  322. package/src/shared/domain/dev/artefacts.ts +50 -0
  323. package/src/shared/domain/dev/batches-concurrency.ts +36 -0
  324. package/src/shared/domain/dev/batches-state.ts +49 -0
  325. package/src/shared/domain/dev/build-commands.ts +44 -0
  326. package/src/shared/domain/dev/call-guard.ts +341 -0
  327. package/src/shared/domain/dev/carried-text.ts +49 -0
  328. package/src/shared/domain/dev/design-rules.ts +100 -0
  329. package/src/shared/domain/dev/learn-proposals.ts +175 -0
  330. package/src/shared/domain/dev/learn-state.ts +93 -0
  331. package/src/shared/domain/dev/path-args.ts +42 -0
  332. package/src/shared/domain/dev/path-rebase.ts +93 -0
  333. package/src/shared/domain/dev/plan-checks.ts +190 -0
  334. package/src/shared/domain/dev/plan-format.ts +180 -0
  335. package/src/shared/domain/dev/project-files.ts +43 -0
  336. package/src/shared/domain/dev/questions.ts +249 -0
  337. package/src/shared/domain/dev/reading-rule.ts +41 -0
  338. package/src/shared/domain/dev/repo-pack.ts +237 -0
  339. package/src/shared/domain/dev/review-answer.ts +150 -0
  340. package/src/shared/domain/dev/review-prompt.ts +221 -0
  341. package/src/shared/domain/dev/reviewer-charter.ts +31 -0
  342. package/src/shared/domain/dev/sheet-facts.ts +83 -0
  343. package/src/shared/domain/dev/spec-format.ts +183 -0
  344. package/src/shared/domain/dev/step-budget.ts +72 -0
  345. package/src/shared/domain/dev/step-rules.ts +110 -0
  346. package/src/shared/domain/dev/test-commands.ts +90 -0
  347. package/src/shared/domain/dev/test-output.ts +33 -0
  348. package/src/shared/domain/dev/test-paths.ts +40 -0
  349. package/src/shared/domain/dev/tool-guards.ts +64 -0
  350. package/src/shared/domain/dev/trait-pattern.ts +83 -0
  351. package/src/shared/domain/dev/verdict-format.ts +169 -0
  352. package/src/shared/domain/dev/whitespace.ts +34 -0
  353. package/src/shared/domain/dev/work-folder.ts +67 -0
  354. package/src/shared/domain/dev/yaml-subset.ts +403 -0
  355. package/src/shared/domain/git/close.ts +273 -0
  356. package/src/shared/domain/git/pull-request.ts +96 -0
  357. package/src/shared/domain/git/worktree.ts +46 -0
  358. package/src/shared/domain/index-languages.ts +16 -0
  359. package/src/shared/domain/instructions-file.ts +18 -0
  360. package/src/shared/domain/iso-day.ts +4 -0
  361. package/src/shared/domain/llm-failure.ts +106 -0
  362. package/src/shared/domain/llm-profile.ts +25 -0
  363. package/src/shared/domain/marked-message.ts +33 -0
  364. package/src/shared/domain/model-catalog.ts +86 -0
  365. package/src/shared/domain/permission-modes.ts +103 -0
  366. package/src/shared/domain/prelude.ts +92 -0
  367. package/src/shared/domain/project-manifests.ts +83 -0
  368. package/src/shared/domain/search-routing.ts +85 -0
  369. package/src/shared/domain/secret-patterns.ts +45 -0
  370. package/src/shared/domain/session-keys.ts +85 -0
  371. package/src/shared/domain/session-start.ts +60 -0
  372. package/src/shared/domain/session-summary.ts +13 -0
  373. package/src/shared/domain/severity.ts +72 -0
  374. package/src/shared/domain/sha1.ts +61 -0
  375. package/src/shared/domain/shared-memory/agent-memory-import.ts +143 -0
  376. package/src/shared/domain/shared-memory/candidates.ts +41 -0
  377. package/src/shared/domain/shared-memory/entry.ts +145 -0
  378. package/src/shared/domain/shared-memory/front-matter.ts +183 -0
  379. package/src/shared/domain/shared-memory/gate.ts +44 -0
  380. package/src/shared/domain/shared-memory/harvest.ts +61 -0
  381. package/src/shared/domain/shared-memory/layout.ts +187 -0
  382. package/src/shared/domain/shared-memory/precedents-block.ts +93 -0
  383. package/src/shared/domain/shared-memory/refused.ts +84 -0
  384. package/src/shared/domain/shared-memory/verdict-rows.ts +134 -0
  385. package/src/shared/domain/snip-turns.ts +45 -0
  386. package/src/shared/domain/speech.ts +20 -0
  387. package/src/shared/domain/strip.ts +88 -0
  388. package/src/shared/domain/tool-trace.ts +122 -0
  389. package/src/shared/domain/types.ts +67 -0
  390. package/src/shared/domain/verifiers.ts +37 -0
  391. package/src/shared/domain/vfs.ts +9 -0
  392. package/src/shared/domain/workflow/state-file.ts +140 -0
  393. package/src/shared/infrastructure/globals.ts +52 -0
  394. package/src/shared/infrastructure/orkeon/approvals.ts +24 -0
  395. package/src/shared/infrastructure/orkeon/child-agents.ts +127 -0
  396. package/src/shared/infrastructure/orkeon/code-index.ts +120 -0
  397. package/src/shared/infrastructure/orkeon/crew-host.ts +27 -0
  398. package/src/shared/infrastructure/orkeon/crew-memory.ts +12 -0
  399. package/src/shared/infrastructure/orkeon/dev-deps.ts +172 -0
  400. package/src/shared/infrastructure/orkeon/files.ts +40 -0
  401. package/src/shared/infrastructure/orkeon/github-pull-requests.ts +29 -0
  402. package/src/shared/infrastructure/orkeon/host-provider.ts +22 -0
  403. package/src/shared/infrastructure/orkeon/human-input.ts +59 -0
  404. package/src/shared/infrastructure/orkeon/llm-profile.ts +38 -0
  405. package/src/shared/infrastructure/orkeon/llm.ts +109 -0
  406. package/src/shared/infrastructure/orkeon/memory-store.ts +41 -0
  407. package/src/shared/infrastructure/orkeon/memory-tools.ts +131 -0
  408. package/src/shared/infrastructure/orkeon/permission-rules.ts +42 -0
  409. package/src/shared/infrastructure/orkeon/progress.ts +24 -0
  410. package/src/shared/infrastructure/orkeon/run-state.ts +17 -0
  411. package/src/shared/infrastructure/orkeon/runtime-info.ts +30 -0
  412. package/src/shared/infrastructure/orkeon/runtime-tools.ts +60 -0
  413. package/src/shared/infrastructure/orkeon/script-tools.ts +134 -0
  414. package/src/shared/infrastructure/orkeon/session-store.ts +138 -0
  415. package/src/shared/infrastructure/orkeon/session-switch.ts +23 -0
  416. package/src/shared/infrastructure/orkeon/shared-memory.ts +61 -0
  417. package/src/shared/infrastructure/orkeon/shell-jobs.ts +75 -0
  418. package/src/shared/infrastructure/orkeon/shell.ts +31 -0
  419. package/src/shared/infrastructure/orkeon/telemetry.ts +63 -0
  420. package/src/shared/infrastructure/orkeon/tool-catalogue.ts +75 -0
  421. package/src/shared/infrastructure/orkeon/tool-results.ts +120 -0
  422. package/src/shared/infrastructure/orkeon/usage.ts +74 -0
  423. package/src/shared/infrastructure/orkeon/wiring.ts +118 -0
@@ -0,0 +1,293 @@
1
+ # Whisper MCP server
2
+
3
+ Speech for Orkeon Code: a small MCP server over stdio (or HTTP, for docker mode), on
4
+ [faster-whisper](https://github.com/SYSTRAN/faster-whisper) for speech-to-text and
5
+ [Piper](https://github.com/OHF-Voice/piper1-gpl) for speech output, that the REPL connects like any
6
+ server of `MCP:Servers`. Its tools:
7
+
8
+ | Tool | What it does |
9
+ |---|---|
10
+ | `transcribe_audio(path, language="", vocabulary="", vad_filter=true)` | Transcribes a file under the virtual folder `/audio`. The text comes back inline when it is short; otherwise it is written under `/transcripts` and the result says where. |
11
+ | `list_audio()` | The audio and video files under `/audio`, one virtual path per line, so the model never guesses a name. |
12
+ | `whisper_info()` | The transcription and speech backends, model and voice, whether they are already on disk, the folders in use, the microphone and the speaker. |
13
+ | `record_and_transcribe(max_seconds=60, silence_seconds=2, language="", vocabulary="")` | Records this machine's microphone until a silence and returns the text alone: Orkeon Code's `/voice`. Refused unless `WHISPER_MICROPHONE=1`. |
14
+ | `speak(text, voice="", wait=false)` | Reads a text aloud: the Markdown cleaned off (code blocks and tables are not read), synthesized, played on the speaker when `WHISPER_SPEAKER=1`, kept as `/transcripts/speech.wav`. Orkeon Code's `/say` and `voice.reply`. |
15
+ | `stop_speaking()` | Cuts the reading under way. |
16
+
17
+ It is the server of Orkeon's guide [Transcribe audio with Whisper through an MCP
18
+ server](https://github.com/Orkeon/orkeon/blob/main/docs/guides/whisper-mcp.md), hardened: the file
19
+ must stay under `/audio`, a container PyAV cannot read gives one line rather than a Python trace,
20
+ a long transcription is split into parts `file_read` can take one at a time, and two backends
21
+ besides the local model.
22
+
23
+ ## Install
24
+
25
+ [uv](https://docs.astral.sh/uv/) resolves `pyproject.toml` (and its `uv.lock`) into
26
+ `mcp/whisper/.venv` the first time it runs the server; nothing else to install. Python 3.11 or
27
+ later, no `ffmpeg`: PyAV, which faster-whisper embeds, decodes audio and the audio track of a video.
28
+
29
+ ```bash
30
+ curl -LsSf https://astral.sh/uv/install.sh | sh # once
31
+ bash scripts/whisper-mcp-smoke.sh # resolves the environment, downloads the tiny model, transcribes a 5 s fixture
32
+ ```
33
+
34
+ Run the smoke script before the first REPL, with the device the REPL will use (`WHISPER_DEVICE=cuda`
35
+ on a GPU) and `--tts` for speech output: Orkeon gives an MCP server 30 s to start and answer the handshake,
36
+ and the first `uv run` of this project resolves its environment first, one to two minutes, 2.5 GB more with
37
+ the `cuda` extra. Started by the REPL at that moment, the server misses the 30 s, the REPL goes on without
38
+ it (`MCP server 'whisper' could not be connected: no answer within 30 s`, then
39
+ `no registered tool 'whisper_info'`), and it misses them again at the next start. Once resolved, the
40
+ server starts in a few seconds.
41
+
42
+ The first transcription with a model downloads it (`small`: 462 MB, `medium`: 1.5 GB, from the
43
+ Hugging Face hub) and takes minutes; `whisper_info` says whether the model is on disk, and the smoke
44
+ script with `WHISPER_MODEL=small` pre-downloads it.
45
+
46
+ ## Settings
47
+
48
+ In the settings file the launcher passes to the REPL (`config/appsettings.local.json`), two
49
+ sections. The two folders appear twice and must match: as the physical side of a mount, and in `Env`.
50
+ The agents know `/audio` and `/transcripts`; the server knows the folders. Both must exist before the REPL
51
+ starts (`mkdir -p ~/audio ~/transcripts`): the launcher creates `<state>/transcripts` itself when it declares
52
+ the server, a declaration by hand creates nothing.
53
+
54
+ ```json
55
+ {
56
+ "Orkeon": {
57
+ "FileSystem": {
58
+ "Mounts": [ "/home/me/audio:/audio:ro", "/home/me/transcripts:/transcripts:ro" ]
59
+ }
60
+ },
61
+ "MCP": {
62
+ "Servers": {
63
+ "whisper": {
64
+ "Transport": "Stdio",
65
+ "TrustAnnotations": true,
66
+ "Command": "/home/me/.local/bin/uv",
67
+ "Args": [ "run", "--project", "/home/me/orkeon-code/mcp/whisper", "/home/me/orkeon-code/mcp/whisper/whisper_mcp.py" ],
68
+ "Env": {
69
+ "WHISPER_AUDIO_DIR": "/home/me/audio",
70
+ "WHISPER_OUT_DIR": "/home/me/transcripts",
71
+ "WHISPER_MODEL": "small"
72
+ }
73
+ }
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ `Command` is a program, not a shell line, found on the `PATH` of the REPL's process: a full path
80
+ is safer. `TrustAnnotations` lets the permission gate read the server's annotations (Orkeon #223): `transcribe_audio`,
81
+ `list_audio` and `whisper_info` are marked read-only, so they run in `dontAsk` without an allow rule; without the key
82
+ every tool of the server is a write. The launcher writes this declaration itself when `ORKEON_CODE_AUDIO_DIR` is set
83
+ ([configuration](../../docs/configuration.md#speech-to-text)). Then, in the REPL, `/transcribe <file>` calls the
84
+ server as the command; `/config set tools.extra transcribe_audio:read,list_audio:read,whisper_info:read` offers the
85
+ tools to the assistant; `/debug-tool-call whisper_info` checks the connection without a model.
86
+
87
+ | Variable | Meaning | Default |
88
+ |---|---|---|
89
+ | `WHISPER_AUDIO_DIR` | The folder mounted as `/audio` | required |
90
+ | `WHISPER_OUT_DIR` | The folder mounted as `/transcripts` | required |
91
+ | `WHISPER_BACKEND` | `local`, `openai` or `http` | `local` |
92
+ | `WHISPER_MODEL` | local: a faster-whisper model (`tiny`, `base`, `small`, `medium`, `large-v3`, `turbo`, …); openai: `whisper-1`; http: what the endpoint expects | `small` / `whisper-1` |
93
+ | `WHISPER_DEVICE` | local: `cpu` or `cuda` | `cpu` |
94
+ | `WHISPER_COMPUTE_TYPE` | local: `int8`, `float16` (GPU), `float32` | `int8` |
95
+ | `WHISPER_BASE_URL` | http: an OpenAI-compatible endpoint ([speaches](https://github.com/speaches-ai/speaches), whisper-server) | |
96
+ | `WHISPER_API_KEY_VAR` | The variable holding the key, exported in the shell that starts the REPL, never in a file; http: a key is sent only when this names its variable | openai: `OPENAI_API_KEY`; http: none |
97
+ | `WHISPER_MICROPHONE` | `1` lets `record_and_transcribe` open the microphone (the launcher sets it on `ORKEON_CODE_VOICE=1`) | off |
98
+ | `WHISPER_SILENCE_RMS` | The level under which a 0.1 s block counts as silence | `0.01` |
99
+ | `WHISPER_SPEAKER` | `1` lets `speak` play on the speaker (the launcher sets it on `ORKEON_CODE_VOICE=1`); off, `speak` only writes the file | off |
100
+ | `TTS_BACKEND` | `piper` (the `tts` extra), `openai` (OpenAI's speech API) or `http` (a compatible server, speaches): the last two need the `openai` extra | `piper` |
101
+ | `TTS_VOICE` | piper: a voice ([the list](https://huggingface.co/rhasspy/piper-voices)), downloaded at its first use (about 60 MB), or the path of a `.onnx` model; openai: `alloy`, `nova`...; http: what the server offers (Kokoro: `ff_siwis`) | `fr_FR-siwis-medium` / `alloy` / required |
102
+ | `TTS_MODEL` | openai: `gpt-4o-mini-tts`, `tts-1`; http: the server's model (`speaches-ai/Kokoro-82M-v1.0-ONNX`) | `gpt-4o-mini-tts` / required |
103
+ | `TTS_BASE_URL` | http: the server's endpoint (`http://<host>:8000/v1`) | required |
104
+ | `TTS_API_KEY_VAR` | As `WHISPER_API_KEY_VAR`, for speech output | openai: `OPENAI_API_KEY`; http: none |
105
+ | `TTS_VOICE_DIR` | Where the Piper voices are kept | `~/.cache/orkeon-code/piper` |
106
+ | `TTS_MAX_CHARS` | The longest text read aloud, cut at a sentence when one ends in its second half, else at the limit | `1200` |
107
+ | `WHISPER_TRANSPORT` | `stdio`, or `http` for [docker mode](#docker-mode-the-server-on-the-host) | `stdio` |
108
+ | `WHISPER_HTTP_HOST`, `WHISPER_HTTP_PORT` | http: where to listen; the endpoint is `/mcp` | `127.0.0.1`, `8765` |
109
+ | `WHISPER_HTTP_ALLOWED_HOSTS` | http: the `Host` headers accepted, comma-separated | `127.0.0.1:*,localhost:*,host.docker.internal:*` |
110
+
111
+ **Backends.** `local` runs on this machine and `openai` sends the audio to OpenAI's API, `http` to a compatible server
112
+ on another machine: both need the `openai` extra (`"Args": ["run", "--project", "…", "--extra", "openai",
113
+ "…/whisper_mcp.py"]`).
114
+
115
+ **GPU.** `WHISPER_DEVICE=cuda` with `WHISPER_COMPUTE_TYPE=float16` runs `local` on an NVIDIA GPU. The `cuda` extra
116
+ brings cuBLAS and cuDNN as wheels, which the server preloads before it builds the model, so neither the CUDA toolkit
117
+ nor `LD_LIBRARY_PATH` is needed, only the NVIDIA driver; the launchers add the extra themselves on
118
+ `WHISPER_DEVICE=cuda`. Measured on the 45-minute French recording of the validation:
119
+
120
+ | Model, device | 45 min of audio | Speed | Memory |
121
+ |---|---|---|---|
122
+ | `small`, 20-core CPU, int8 | 7 min 14 s | 6 × real time | |
123
+ | `small`, RTX 3070 Ti Laptop (8 GB, WSL2), float16 | 95 s | 28 × real time | 1.3 GB |
124
+ | `turbo` (large-v3-turbo), same GPU, float16 | 106 s | 25 × real time | |
125
+
126
+ `turbo` gets more names right without any vocabulary (Lilienthal, Ader, Wikipédia, where `small` wrote Lienthal,
127
+ Adair, bikipedia): on a GPU it is the better default, for a 1.6 GB download.
128
+
129
+ ### Or the server in a container of its own
130
+
131
+ With an NVIDIA GPU that Docker can use (`docker run --gpus all ...` sees it), the server needs no Python on the host
132
+ either: a stock Python image runs it, uv resolving its environment outside the checkout (`UV_PROJECT_ENVIRONMENT`), the
133
+ model and uv caches in folders that outlive the container. The port is published on the host's loopback, which the
134
+ REPL's container reaches as `host.docker.internal` on Docker Desktop (on Linux, publish on the bridge address
135
+ instead, `-p 172.17.0.1:8765:8765`, accept it with `-e WHISPER_HTTP_ALLOWED_HOSTS=172.17.0.1:*`, and use it in
136
+ `Url`):
137
+
138
+ ```bash
139
+ docker run -d --name whisper-mcp --gpus all -p 127.0.0.1:8765:8765 \
140
+ -v "$PWD/mcp/whisper:/srv/whisper:ro" -v "$PWD/.crew-output:/data" \
141
+ -v whisper-hf:/root/.cache/huggingface -v whisper-uv:/root/.cache/uv \
142
+ -e UV_PROJECT_ENVIRONMENT=/opt/venv -e WHISPER_TRANSPORT=http -e WHISPER_HTTP_HOST=0.0.0.0 \
143
+ -e WHISPER_AUDIO_DIR=/data/audio -e WHISPER_OUT_DIR=/data/transcripts \
144
+ -e WHISPER_DEVICE=cuda -e WHISPER_COMPUTE_TYPE=float16 -e WHISPER_MODEL=small \
145
+ python:3.11-slim-bookworm sh -c "pip install -q uv && uv run --frozen --project /srv/whisper --extra cuda /srv/whisper/whisper_mcp.py"
146
+ ```
147
+
148
+ The first start downloads the CUDA libraries (about 2.5 GB) and the model into the two volumes; the next ones start
149
+ in seconds. `WHISPER_HTTP_HOST=0.0.0.0` listens on every interface of the container, which the `-p 127.0.0.1:...`
150
+ mapping keeps off the network.
151
+
152
+ ## Dictation
153
+
154
+ `record_and_transcribe` reads the default input device through
155
+ [sounddevice](https://python-sounddevice.readthedocs.io/) (the `voice` extra: `uv run --project mcp/whisper --extra
156
+ voice ...`), at 16 kHz mono by blocks of 0.1 s. It stops after `silence_seconds` of quiet once speech was heard,
157
+ after 10 s without speech, or at `max_seconds`; nothing heard returns an empty text. The recording is kept as
158
+ `<WHISPER_OUT_DIR>/dictation.wav` and its text as `dictation.txt`, the text emptied and the audio removed when the
159
+ next recording starts (one that fails leaves no old text), then transcribed by the configured backend (with `openai`, the recording leaves the
160
+ machine). A reading of `speak` still playing is stopped first, so that the microphone does not record it. On Linux, sounddevice needs
161
+ the PortAudio library (`libportaudio2`); the macOS and Windows wheels carry it. No microphone in docker mode.
162
+
163
+ ## Docker mode: the server on the host
164
+
165
+ In docker mode a `Stdio` server would run inside the container, which has neither uv nor the model. The server can
166
+ run on the host instead, over HTTP, and the REPL in the container reach it: `WHISPER_TRANSPORT=http` serves
167
+ Streamable HTTP on `/mcp`, one JSON answer per request and no session, which Orkeon's `Sse` transport reads. Files
168
+ go through the state directory, which the launcher already mounts in the container as `/work/state`:
169
+
170
+ ```bash
171
+ mkdir -p .crew-output/audio .crew-output/transcripts # drop the audio files in .crew-output/audio
172
+ WHISPER_TRANSPORT=http WHISPER_HTTP_HOST=<address> \
173
+ WHISPER_AUDIO_DIR="$PWD/.crew-output/audio" WHISPER_OUT_DIR="$PWD/.crew-output/transcripts" \
174
+ uv run --project mcp/whisper mcp/whisper/whisper_mcp.py &
175
+ ./orkeon-code --mode docker -- --mount /work/state/audio:/audio:ro --mount /work/state/transcripts:/transcripts:ro
176
+ ```
177
+
178
+ with, in the settings file, `"MCP": { "Servers": { "whisper": { "Transport": "Sse", "Url": "http://<host>:8765/mcp" } } }`.
179
+ On Docker Desktop (macOS, Windows), `<host>` is `host.docker.internal` and the server may listen on `127.0.0.1`. On
180
+ Linux, the container reaches the host on the bridge address (`172.17.0.1` by default): listen there
181
+ (`WHISPER_HTTP_HOST=172.17.0.1`), add it to `WHISPER_HTTP_ALLOWED_HOSTS` (`172.17.0.1:*`), and use it as `<host>`.
182
+ Never listen on `0.0.0.0`: Orkeon's HTTP transport sends no credentials, so the server has none to check, and every
183
+ machine of the network could list and transcribe the audio folder.
184
+
185
+ Two limits of Orkeon's HTTP transport: a call that lasts more than 100 s fails on the REPL's side (its HTTP client's
186
+ default timeout), although the server finishes and writes the transcript, so files whose transcription takes longer
187
+ are for the stdio modes: about 10 minutes of audio on a CPU with `small`, about 35 minutes on a laptop GPU (45 minutes
188
+ took 92 s with the server in one container, 117 s in another); and the transport sends no
189
+ `Accept` header and probes with a protocol version the SDK does not know, which the server smooths over
190
+ (`orkeon_http_compat`). The microphone stays on the host: `/voice` is for the stdio modes.
191
+
192
+ ## Speech output
193
+
194
+ `speak` reads what is worth reading: code blocks, tables and rules are skipped, links keep their text and bare URLs
195
+ go, headings, bullets, bold and italics lose their marks, and a line without final punctuation gets a pause. A text
196
+ longer than `TTS_MAX_CHARS` is cut at a sentence when one ends in the second half of the limit, else at the limit
197
+ itself, and the result says which (`cut at a sentence`, `cut short`); a text with nothing to read (only code) gets a note, not an error,
198
+ and plays nothing. The audio is synthesized first (Piper on a CPU: about 4 s for a sentence of 100 characters, the
199
+ voice already downloaded; Kokoro through speaches on a GPU: 0.6 s), written to `<WHISPER_OUT_DIR>/speech.wav`, then
200
+ played in the background: `speak` returns as the reading starts, and a new `speak` cuts the one under way. With
201
+ `wait=true` it returns at the end of the reading, and the server answers no other call meanwhile, `stop_speaking`
202
+ included. A synthesis that fails leaves the last `speech.wav` as it was. Playback needs the `voice` extra
203
+ (sounddevice, PortAudio on Linux), Piper the `tts` extra:
204
+ `uv run --project mcp/whisper --extra voice --extra tts mcp/whisper/whisper_mcp.py`. The launchers add `tts`
205
+ whenever Piper is the backend, and `voice` on `ORKEON_CODE_VOICE=1`.
206
+
207
+ [Piper](https://github.com/OHF-Voice/piper1-gpl) (`piper-tts`) is GPL-3.0: the server runs it as a separate process
208
+ (`python -m piper`), never imports it, and it is an optional extra; the voices have licences of their own, listed with
209
+ each voice. In docker mode, the server on the host plays on the host's speaker.
210
+
211
+ **OpenAI's API, or Kokoro on a GPU through speaches.** `TTS_BACKEND=openai` sends the text to OpenAI (the key in
212
+ `OPENAI_API_KEY`, the text leaves the machine). `TTS_BACKEND=http` asks any server of the same API for a wav,
213
+ sending a key only when `TTS_API_KEY_VAR` names its variable;
214
+ [speaches](https://speaches.ai) serves [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M), a better voice than Piper,
215
+ on an NVIDIA GPU, in a container:
216
+
217
+ ```bash
218
+ docker run -d --name speaches --gpus all -p 127.0.0.1:8000:8000 -v speaches-hf:/home/ubuntu/.cache/huggingface \
219
+ ghcr.io/speaches-ai/speaches:latest-cuda
220
+ curl -X POST http://localhost:8000/v1/models/speaches-ai/Kokoro-82M-v1.0-ONNX # once: downloads the model
221
+ export TTS_BACKEND=http TTS_BASE_URL=http://localhost:8000/v1 \
222
+ TTS_MODEL=speaches-ai/Kokoro-82M-v1.0-ONNX TTS_VOICE=ff_siwis # ff_siwis: Kokoro's French voice
223
+ ```
224
+
225
+ The launchers add the `openai` extra themselves when `TTS_BACKEND` or `WHISPER_BACKEND` is `openai` or `http`.
226
+
227
+ ## Results
228
+
229
+ A transcription under 3 500 characters (about 3 minutes of speech) comes back inline, followed by
230
+ the language detected, the duration, the word count and the files written. A longer one is written
231
+ only: `/transcripts/<name>.txt` (the audio's path under `/audio`, suffix changed), with
232
+ `<name>.segments.json` (timestamps) beside it and, above 30 000 characters, `<name>.part-NN.txt`
233
+ files of at most 30 000 characters cut between segments (or at a space, in a segment longer than
234
+ that), which the assistant reads one at a time
235
+ with `file_read`. The result names them and quotes the first 500 characters. These numbers follow
236
+ Orkeon's caps: 4 000 characters for a tool result, 32 000 for `file_read`.
237
+
238
+ `vocabulary` takes the words the speech is likely to contain (module names, acronyms, people), and Whisper spells
239
+ them right instead of guessing homophones. The local backend hands them to faster-whisper as `hotwords`, which
240
+ conditions every 30-second window; Whisper's `initial_prompt` conditions only the first, and changed none of the
241
+ names of a 16-minute French recording that `hotwords` all fixed. The `openai` and `http` backends send them as the
242
+ API's `prompt`. `language` empty lets the model detect it; naming it (`fr`, `en`) is faster and safer on short files.
243
+
244
+ ## Why the server is written this way
245
+
246
+ | Orkeon's MCP client | Consequence here |
247
+ |---|---|
248
+ | The agents only know virtual paths; the client passes the arguments as they are | The server maps `/audio/x.m4a` to a file under `WHISPER_AUDIO_DIR`, and refuses anything that leaves it |
249
+ | A tool result is cut at 4 000 characters | Inline under 3 500; files above, in parts under `file_read`'s 32 000 |
250
+ | The handshake must answer within 30 s | The model is loaded at the first call, never at start |
251
+ | A command's awaited promise is bounded by Jint's 10 s `PromiseTimeout` | `/transcribe`, `/voice` and `/say` run the call in a crew (an async command), never in their handler |
252
+ | The `mcp` Python SDK 2.x renamed `FastMCP` and quits on stdin EOF before a running call answers | `mcp>=1.30,<2`, which speaks the protocol version Orkeon requires (2025-06-18) |
253
+ | In docker mode, a `Stdio` command runs inside the container | The server runs over stdio in `tool` and `source` modes, and on the host over HTTP for docker mode |
254
+ | Its HTTP transport sends no `Accept` header, probes with protocol `2026-07-28`, and gives up on an HTTP 400 | The http transport adds the header and drops a version the SDK does not know, so the probe falls back to the initialize handshake |
255
+
256
+ ## Tests
257
+
258
+ ```bash
259
+ uv run --project mcp/whisper pytest mcp/whisper # unit tests, a fake model, no network
260
+ bash scripts/whisper-mcp-smoke.sh # the real server over stdio, the tiny model, samples/fr-5s.wav
261
+ bash scripts/whisper-mcp-smoke.sh --tts # and speak: Piper writes a sentence, Whisper hears it back
262
+ ```
263
+
264
+ CI runs the unit tests with `mcp` and `pytest` only: `faster-whisper` is imported at the first
265
+ transcription (and by `whisper_info`, to name the model's repository), and the tests do without it. The fixture is CC0 ([samples/README.md](samples/README.md)).
266
+
267
+ ## Troubleshooting
268
+
269
+ - `No module named 'mcp.server.fastmcp'`: the server runs on `mcp` 2.x. Run it with `--project
270
+ mcp/whisper` (the lock pins 1.x), not with a bare `--with mcp`.
271
+ - `Failed to start MCP server process`: `Command` is not on the REPL's `PATH`: write the full path of
272
+ `uv`.
273
+ - `MCP server 'whisper' could not be connected: no answer within 30 s` at the REPL's start, then
274
+ `no registered tool 'whisper_info'`: the environment of `mcp/whisper` was not resolved yet, and its first
275
+ `uv run` takes minutes where Orkeon gives a server 30 s. Resolve it once outside the REPL:
276
+ `bash scripts/whisper-mcp-smoke.sh` with the same `WHISPER_DEVICE`, or the declared `Command` and `Args` run
277
+ by hand with `< /dev/null` (the server quits when its input closes). Then start the REPL again.
278
+ - `Library libcublas.so.12 is not found`: `WHISPER_DEVICE=cuda` without the `cuda` extra. The launchers
279
+ add it on `WHISPER_DEVICE=cuda`; a server declared by hand needs `--extra cuda` in its `Args`.
280
+ - `no microphone access (PortAudio library not found)`: the server runs without the `voice` extra, or Linux lacks
281
+ `libportaudio2`. `the microphone is off`: the server runs without `WHISPER_MICROPHONE=1` (`ORKEON_CODE_VOICE=1`).
282
+ - `/voice` never stops before its maximum: the room is louder than `WHISPER_SILENCE_RMS`; raise it (0.02, 0.05).
283
+ - `the openai package is missing`: `TTS_BACKEND` or `WHISPER_BACKEND` is `openai` or `http` and the server runs
284
+ without the `openai` extra (the launchers add it; a server declared by hand needs `--extra openai`).
285
+ - `cannot synthesize the text: ... model ... not found` with speaches: the model was not downloaded
286
+ (`curl -X POST <server>/v1/models/<model>`).
287
+ - `Piper is not installed`: the server runs without the `tts` extra (by hand: `--extra tts` in its `Args`). `no speaker access`: without the `voice` extra,
288
+ or Linux lacks `libportaudio2`. `not played: the speaker is off`: the server runs without `WHISPER_SPEAKER=1`.
289
+ - The first call is slow or seems stuck: the model is downloading. `whisper_info` reports
290
+ `model_cached: False` until it is on disk.
291
+ - `Error: Timeout of 00:00:10 reached` from `/debug-tool-call transcribe_audio …`: Jint's limit on a
292
+ synchronous command's promise, not the server's; the file is still written under `/transcripts`. Use
293
+ `/transcribe`, which waits in a crew.
@@ -0,0 +1,32 @@
1
+ # The speech MCP server of Orkeon Code (speech-to-text and speech output). Not a package: `uv run --project mcp/whisper`
2
+ # resolves these dependencies into mcp/whisper/.venv and runs the script.
3
+ [project]
4
+ name = "orkeon-code-whisper-mcp"
5
+ version = "0.1.0"
6
+ description = "Speech-to-text and speech output for Orkeon Code: an MCP server on faster-whisper and Piper"
7
+ readme = "README.md"
8
+ license = "MIT"
9
+ requires-python = ">=3.11"
10
+ dependencies = [
11
+ # mcp 2.x renamed FastMCP to MCPServer and quits on stdin EOF before a running call answers:
12
+ # the server is written against the 1.x API, which speaks the protocol Orkeon requires (2025-06-18).
13
+ "mcp>=1.30,<2",
14
+ "faster-whisper>=1.2",
15
+ ]
16
+
17
+ [project.optional-dependencies]
18
+ openai = ["openai>=1.50"] # the openai and http backends
19
+ cuda = ["nvidia-cublas-cu12", "nvidia-cudnn-cu12>=9"] # WHISPER_DEVICE=cuda on a machine without the CUDA toolkit
20
+ voice = ["sounddevice>=0.5"] # record_and_transcribe (/voice) and speak's playback: the microphone and the speaker, through PortAudio
21
+ # speak's synthesis. piper-tts is GPL-3.0: the server runs it as a subprocess (python -m piper), never imports it.
22
+ tts = ["piper-tts>=1.3"]
23
+
24
+ [dependency-groups]
25
+ dev = ["pytest>=8"]
26
+
27
+ [tool.uv]
28
+ package = false
29
+
30
+ [tool.pytest.ini_options]
31
+ testpaths = ["tests"]
32
+ pythonpath = ["."]