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.
- package/.orkeon-version +1 -0
- package/LICENSE.md +21 -0
- package/NOTICE.md +17 -0
- package/README.fr.md +169 -0
- package/README.md +162 -2
- package/config/appsettings.anthropic.example.json +77 -0
- package/config/appsettings.example.json +71 -0
- package/config/appsettings.jev.example.json +128 -0
- package/config/appsettings.kev.example.json +130 -0
- package/config/appsettings.liquid.example.json +129 -0
- package/config/appsettings.ollama-whisper.example.json +92 -0
- package/config/appsettings.ollama.example.json +70 -0
- package/config/appsettings.whisper.example.json +31 -0
- package/mcp/whisper/README.md +293 -0
- package/mcp/whisper/pyproject.toml +32 -0
- package/mcp/whisper/uv.lock +1641 -0
- package/mcp/whisper/whisper_mcp.py +1053 -0
- package/orkeon-code +897 -0
- package/orkeon-code.mjs +71 -0
- package/orkeon-code.ps1 +837 -0
- package/package.json +57 -4
- package/scripts/install.ps1 +156 -0
- package/scripts/install.sh +148 -0
- package/scripts/session-start.ork.ts +90 -0
- package/scripts/session-start.sh +74 -0
- package/scripts/setup-fixture.sh +88 -0
- package/src/commands/.orkeon/orkeon-cli.d.ts +562 -0
- package/src/commands/_lib/args.ts +193 -0
- package/src/commands/_lib/dev/dev-batches.ts +368 -0
- package/src/commands/_lib/dev/dev-implement.ts +188 -0
- package/src/commands/_lib/dev/dev-source.ts +65 -0
- package/src/commands/_lib/dev/dev.ts +344 -0
- package/src/commands/_lib/dev-step.ts +142 -0
- package/src/commands/_lib/dispatch.ts +231 -0
- package/src/commands/_lib/effort.ts +15 -0
- package/src/commands/_lib/git/branch.ts +95 -0
- package/src/commands/_lib/git/commit.ts +94 -0
- package/src/commands/_lib/git/diff.ts +97 -0
- package/src/commands/_lib/git/review.ts +109 -0
- package/src/commands/_lib/memory/memory-admit.ts +150 -0
- package/src/commands/_lib/memory/memory.ts +51 -0
- package/src/commands/_lib/pr-context.ts +32 -0
- package/src/commands/_lib/project/analyze.ts +24 -0
- package/src/commands/_lib/session/export.ts +104 -0
- package/src/commands/_lib/session/resume.ts +160 -0
- package/src/commands/_lib/session/tasks.ts +184 -0
- package/src/commands/_lib/settings/advisor.ts +80 -0
- package/src/commands/_lib/settings/agents.ts +147 -0
- package/src/commands/_lib/settings/config.ts +141 -0
- package/src/commands/_lib/settings/hooks.ts +58 -0
- package/src/commands/_lib/settings/mode.ts +91 -0
- package/src/commands/_lib/settings/model.ts +146 -0
- package/src/commands/_lib/settings/permissions.ts +309 -0
- package/src/commands/_lib/settings/session-config.ts +49 -0
- package/src/commands/_lib/settings/skills.ts +51 -0
- package/src/commands/_lib/speech/say.ts +96 -0
- package/src/commands/_lib/speech/transcribe.ts +130 -0
- package/src/commands/_lib/speech/voice.ts +146 -0
- package/src/commands/_lib/status/cache.ts +31 -0
- package/src/commands/_lib/status/context.ts +57 -0
- package/src/commands/_lib/status/doctor.ts +186 -0
- package/src/commands/_lib/status/meta.ts +45 -0
- package/src/commands/_lib/status/status.ts +129 -0
- package/src/commands/_lib/status/usage-tools.ts +49 -0
- package/src/commands/_lib/status/usage.ts +139 -0
- package/src/commands/_lib/view.ts +29 -0
- package/src/commands/dev/dev-batches.cmd.ts +108 -0
- package/src/commands/dev/dev-learn.cmd.ts +29 -0
- package/src/commands/dev/dev-plan.cmd.ts +52 -0
- package/src/commands/dev/dev-spec.cmd.ts +55 -0
- package/src/commands/dev/dev-status.cmd.ts +16 -0
- package/src/commands/git/branch.cmd.ts +27 -0
- package/src/commands/git/commit.cmd.ts +48 -0
- package/src/commands/git/diff.cmd.ts +26 -0
- package/src/commands/git/review.cmd.ts +36 -0
- package/src/commands/memory/memory.cmd.ts +48 -0
- package/src/commands/project/analyze.cmd.ts +32 -0
- package/src/commands/project/debug-tool-call.cmd.ts +67 -0
- package/src/commands/project/files.cmd.ts +22 -0
- package/src/commands/project/init-verifiers.cmd.ts +14 -0
- package/src/commands/project/init.cmd.ts +14 -0
- package/src/commands/project/verify.cmd.ts +27 -0
- package/src/commands/session/assistant.cmd.ts +40 -0
- package/src/commands/session/btw.cmd.ts +18 -0
- package/src/commands/session/clear.cmd.ts +19 -0
- package/src/commands/session/compact.cmd.ts +16 -0
- package/src/commands/session/copy.cmd.ts +44 -0
- package/src/commands/session/exit.cmd.ts +9 -0
- package/src/commands/session/export.cmd.ts +28 -0
- package/src/commands/session/rename.cmd.ts +17 -0
- package/src/commands/session/resume.cmd.ts +19 -0
- package/src/commands/session/rewind.cmd.ts +26 -0
- package/src/commands/session/summary.cmd.ts +27 -0
- package/src/commands/session/tasks.cmd.ts +44 -0
- package/src/commands/settings/advisor.cmd.ts +38 -0
- package/src/commands/settings/agents.cmd.ts +19 -0
- package/src/commands/settings/config.cmd.ts +17 -0
- package/src/commands/settings/effort.cmd.ts +40 -0
- package/src/commands/settings/fast.cmd.ts +17 -0
- package/src/commands/settings/hooks.cmd.ts +17 -0
- package/src/commands/settings/mode.cmd.ts +20 -0
- package/src/commands/settings/model.cmd.ts +20 -0
- package/src/commands/settings/output-style.cmd.ts +48 -0
- package/src/commands/settings/permissions.cmd.ts +25 -0
- package/src/commands/settings/proactive.cmd.ts +15 -0
- package/src/commands/settings/skills.cmd.ts +17 -0
- package/src/commands/speech/say.cmd.ts +24 -0
- package/src/commands/speech/transcribe.cmd.ts +29 -0
- package/src/commands/speech/voice.cmd.ts +30 -0
- package/src/commands/status/context.cmd.ts +18 -0
- package/src/commands/status/doctor.cmd.ts +27 -0
- package/src/commands/status/release-notes.cmd.ts +9 -0
- package/src/commands/status/status.cmd.ts +25 -0
- package/src/commands/status/usage.cmd.ts +21 -0
- package/src/crews/.orkeon/orkeon.d.ts +3946 -0
- package/src/crews/_probe-shared-memory/domain/probe-verdict.ts +183 -0
- package/src/crews/_probe-shared-memory/probe.ork.ts +98 -0
- package/src/crews/advisor/application/run-advisor.ts +40 -0
- package/src/crews/advisor/crew.ork.ts +43 -0
- package/src/crews/advisor/domain/advice.ts +135 -0
- package/src/crews/agent-run/application/run-agent-run.ts +42 -0
- package/src/crews/agent-run/crew.ork.ts +67 -0
- package/src/crews/analyze/application/run-analyze.ts +118 -0
- package/src/crews/analyze/crew.ork.ts +40 -0
- package/src/crews/analyze/domain/harvest.ts +301 -0
- package/src/crews/code-review/application/prompts.ts +133 -0
- package/src/crews/code-review/application/review.ts +71 -0
- package/src/crews/code-review/application/run-code-review.ts +123 -0
- package/src/crews/code-review/crew.ork.ts +51 -0
- package/src/crews/code-review/domain/lenses.ts +193 -0
- package/src/crews/code-review/domain/report.ts +59 -0
- package/src/crews/code-review/domain/scope.ts +112 -0
- package/src/crews/dev-batches/application/plan-close.ts +181 -0
- package/src/crews/dev-batches/application/run-dev-batches.ts +669 -0
- package/src/crews/dev-batches/application/run-wave.ts +450 -0
- package/src/crews/dev-batches/application/seed-harvest.ts +162 -0
- package/src/crews/dev-batches/crew.ork.ts +143 -0
- package/src/crews/dev-batches/domain/batch-waves.ts +70 -0
- package/src/crews/dev-batches/domain/batches-budget.ts +52 -0
- package/src/crews/dev-batches/domain/batches-log.ts +54 -0
- package/src/crews/dev-batches/domain/wave-order.ts +43 -0
- package/src/crews/dev-change/application/change-prompt.ts +104 -0
- package/src/crews/dev-change/application/evidence.ts +169 -0
- package/src/crews/dev-change/application/run-dev-change.ts +315 -0
- package/src/crews/dev-change/crew.ork.ts +112 -0
- package/src/crews/dev-change/domain/change-answer.ts +159 -0
- package/src/crews/dev-change/domain/change-render.ts +79 -0
- package/src/crews/dev-implement/application/close.ts +183 -0
- package/src/crews/dev-implement/application/count-open-steps.ts +24 -0
- package/src/crews/dev-implement/application/locate-sheet.ts +80 -0
- package/src/crews/dev-implement/application/observe.ts +50 -0
- package/src/crews/dev-implement/application/report-writes.ts +41 -0
- package/src/crews/dev-implement/application/run-dev-implement.ts +811 -0
- package/src/crews/dev-implement/application/run-role.ts +27 -0
- package/src/crews/dev-implement/application/suite-job.ts +118 -0
- package/src/crews/dev-implement/application/touched.ts +74 -0
- package/src/crews/dev-implement/crew.ork.ts +68 -0
- package/src/crews/dev-implement/domain/contracts.ts +256 -0
- package/src/crews/dev-implement/domain/correction.ts +102 -0
- package/src/crews/dev-implement/domain/cycles.ts +35 -0
- package/src/crews/dev-implement/domain/implement-budget.ts +29 -0
- package/src/crews/dev-implement/domain/roles.ts +53 -0
- package/src/crews/dev-implement/domain/sheet-edits.ts +75 -0
- package/src/crews/dev-implement/domain/sheet-ticks.ts +22 -0
- package/src/crews/dev-implement/domain/step-checks.ts +136 -0
- package/src/crews/dev-implement/domain/step-section.ts +127 -0
- package/src/crews/dev-learn/application/learn-backlog.ts +58 -0
- package/src/crews/dev-learn/application/learn-prompt.ts +140 -0
- package/src/crews/dev-learn/application/run-dev-learn.ts +553 -0
- package/src/crews/dev-learn/crew.ork.ts +52 -0
- package/src/crews/dev-learn/domain/learn-answer.ts +235 -0
- package/src/crews/dev-learn/domain/owner-lines.ts +86 -0
- package/src/crews/dev-learn/domain/proposals-render.ts +96 -0
- package/src/crews/dev-plan/application/anchor-paths.ts +76 -0
- package/src/crews/dev-plan/application/inventory.ts +170 -0
- package/src/crews/dev-plan/application/plan-prompt.ts +159 -0
- package/src/crews/dev-plan/application/run-dev-plan.ts +455 -0
- package/src/crews/dev-plan/crew.ork.ts +109 -0
- package/src/crews/dev-plan/domain/inventory-model.ts +95 -0
- package/src/crews/dev-plan/domain/plan-answer.ts +738 -0
- package/src/crews/dev-plan/domain/plan-render.ts +307 -0
- package/src/crews/dev-spec/application/run-dev-spec.ts +206 -0
- package/src/crews/dev-spec/application/spec-prompt.ts +98 -0
- package/src/crews/dev-spec/crew.ork.ts +108 -0
- package/src/crews/dev-spec/domain/spec-answer.ts +253 -0
- package/src/crews/dev-spec/domain/spec-render.ts +76 -0
- package/src/crews/dev-verify/application/audit.ts +259 -0
- package/src/crews/dev-verify/application/auditor-prompt.ts +323 -0
- package/src/crews/dev-verify/application/capture.ts +303 -0
- package/src/crews/dev-verify/application/run-dev-verify.ts +409 -0
- package/src/crews/dev-verify/application/run-gate.ts +202 -0
- package/src/crews/dev-verify/crew.ork.ts +103 -0
- package/src/crews/dev-verify/domain/audit-answer.ts +150 -0
- package/src/crews/dev-verify/domain/auditor-charter.ts +21 -0
- package/src/crews/dev-verify/domain/capture-sections.ts +137 -0
- package/src/crews/dev-verify/domain/commands.ts +103 -0
- package/src/crews/dev-verify/domain/gate.ts +126 -0
- package/src/crews/dev-verify/domain/mechanical-table.ts +163 -0
- package/src/crews/dev-verify/domain/runtime-cut.ts +13 -0
- package/src/crews/dev-verify/domain/sheet-facts.ts +4 -0
- package/src/crews/dev-verify/domain/text.ts +20 -0
- package/src/crews/dev-verify/domain/verdict.ts +127 -0
- package/src/crews/git-commit/application/draft.ts +154 -0
- package/src/crews/git-commit/application/run-git-commit.ts +116 -0
- package/src/crews/git-commit/crew.ork.ts +52 -0
- package/src/crews/git-commit/domain/commit.ts +220 -0
- package/src/crews/init-verifiers/application/authoring.ts +89 -0
- package/src/crews/init-verifiers/application/prompts.ts +103 -0
- package/src/crews/init-verifiers/application/run-init-verifiers.ts +25 -0
- package/src/crews/init-verifiers/crew.ork.ts +34 -0
- package/src/crews/init-verifiers/domain/commands-section.ts +36 -0
- package/src/crews/init-verifiers/domain/readiness.ts +23 -0
- package/src/crews/main-loop/application/auto-compact.ts +77 -0
- package/src/crews/main-loop/application/context-gather.ts +133 -0
- package/src/crews/main-loop/application/run-main-loop.ts +350 -0
- package/src/crews/main-loop/application/turn-prompt.ts +112 -0
- package/src/crews/main-loop/crew.ork.ts +119 -0
- package/src/crews/main-loop/domain/autocompact.ts +27 -0
- package/src/crews/main-loop/domain/prompt-assembly.ts +521 -0
- package/src/crews/main-loop/domain/turn-chains.ts +129 -0
- package/src/crews/project-init/application/detect.ts +122 -0
- package/src/crews/project-init/application/prompts.ts +101 -0
- package/src/crews/project-init/application/run-project-init.ts +31 -0
- package/src/crews/project-init/crew.ork.ts +35 -0
- package/src/crews/project-init/domain/conventions.ts +36 -0
- package/src/crews/project-init/domain/existing-files.ts +63 -0
- package/src/crews/project-init/domain/package-map.ts +73 -0
- package/src/crews/session-compact/crew.ork.ts +55 -0
- package/src/crews/shared-memory-admit/crew.ork.ts +48 -0
- package/src/crews/speech/application/run-speech.ts +25 -0
- package/src/crews/speech/crew.ork.ts +37 -0
- package/src/shared/application/agents/child-agent.ts +255 -0
- package/src/shared/application/agents/run-sub-agent.ts +96 -0
- package/src/shared/application/answer-language.ts +14 -0
- package/src/shared/application/attached-skills.ts +36 -0
- package/src/shared/application/compaction/compact-session.ts +237 -0
- package/src/shared/application/compaction/extract-memories.ts +38 -0
- package/src/shared/application/compaction/restore-context.ts +78 -0
- package/src/shared/application/config-store.ts +123 -0
- package/src/shared/application/dev/brief-inventory.ts +113 -0
- package/src/shared/application/dev/close-batch.ts +83 -0
- package/src/shared/application/dev/find-repo-pack.ts +77 -0
- package/src/shared/application/dev/learn-decision.ts +252 -0
- package/src/shared/application/dev/load-dev-context.ts +266 -0
- package/src/shared/application/dev/measure-access-cost.ts +68 -0
- package/src/shared/application/dev/plan-source.ts +112 -0
- package/src/shared/application/dev/preflight.ts +71 -0
- package/src/shared/application/dev/project-files.ts +17 -0
- package/src/shared/application/dev/question-round.ts +52 -0
- package/src/shared/application/dev/resolve-work-folder.ts +133 -0
- package/src/shared/application/dev/script-tool-slot.ts +27 -0
- package/src/shared/application/dev/settle-questions.ts +55 -0
- package/src/shared/application/dev/source-review.ts +63 -0
- package/src/shared/application/dev/source-step.ts +150 -0
- package/src/shared/application/dev/spend.ts +42 -0
- package/src/shared/application/dev/step-precedents.ts +89 -0
- package/src/shared/application/dev/tool-call-policy.ts +89 -0
- package/src/shared/application/dev/tool-callbacks.ts +215 -0
- package/src/shared/application/dev/tool-trace-recorder.ts +45 -0
- package/src/shared/application/dev/verdict-sources.ts +48 -0
- package/src/shared/application/dev/wrapped-tools.ts +145 -0
- package/src/shared/application/extra-tools.ts +70 -0
- package/src/shared/application/git/batch-worktree.ts +97 -0
- package/src/shared/application/git/commit-files.ts +186 -0
- package/src/shared/application/git/merge-batch.ts +63 -0
- package/src/shared/application/git/open-pull-request.ts +51 -0
- package/src/shared/application/instructions-file.ts +19 -0
- package/src/shared/application/json-file.ts +34 -0
- package/src/shared/application/llm-profile.ts +35 -0
- package/src/shared/application/permission-rules.ts +159 -0
- package/src/shared/application/ports/approvals.ts +20 -0
- package/src/shared/application/ports/clock.ts +5 -0
- package/src/shared/application/ports/code-index.ts +93 -0
- package/src/shared/application/ports/crew.ts +60 -0
- package/src/shared/application/ports/files.ts +21 -0
- package/src/shared/application/ports/human.ts +13 -0
- package/src/shared/application/ports/llm.ts +54 -0
- package/src/shared/application/ports/memory.ts +30 -0
- package/src/shared/application/ports/progress.ts +23 -0
- package/src/shared/application/ports/runtime.ts +15 -0
- package/src/shared/application/ports/session.ts +74 -0
- package/src/shared/application/ports/shared-memory.ts +26 -0
- package/src/shared/application/ports/shell.ts +40 -0
- package/src/shared/application/ports/telemetry.ts +45 -0
- package/src/shared/application/ports/tools.ts +46 -0
- package/src/shared/application/ports/usage.ts +45 -0
- package/src/shared/application/ports.ts +27 -0
- package/src/shared/application/project-manifests.ts +106 -0
- package/src/shared/application/session-io.ts +84 -0
- package/src/shared/application/session-state.ts +36 -0
- package/src/shared/application/shared-memory/admit-entries.ts +177 -0
- package/src/shared/application/shared-memory/harvest-after-gaps.ts +72 -0
- package/src/shared/application/shared-memory/harvest-mistakes.ts +44 -0
- package/src/shared/application/shared-memory/import-agent-memory.ts +117 -0
- package/src/shared/application/shared-memory/memory-files.ts +110 -0
- package/src/shared/application/shared-memory/memory-settings.ts +93 -0
- package/src/shared/application/shared-memory/push-candidate.ts +146 -0
- package/src/shared/application/shared-memory/recall-precedents.ts +69 -0
- package/src/shared/application/state-snapshot.ts +38 -0
- package/src/shared/application/workflow/workflow-state.ts +135 -0
- package/src/shared/domain/agent-policy/behavior-flags.ts +168 -0
- package/src/shared/domain/agent-policy/extra-tools.ts +69 -0
- package/src/shared/domain/agent-policy/memory-categories.ts +6 -0
- package/src/shared/domain/agent-policy/mode-policy.ts +51 -0
- package/src/shared/domain/agent-policy/output-styles.ts +11 -0
- package/src/shared/domain/agent-policy/permission.ts +623 -0
- package/src/shared/domain/agent-policy/rule-sets.ts +412 -0
- package/src/shared/domain/agent-policy/tool-access.ts +77 -0
- package/src/shared/domain/agent-registry.ts +142 -0
- package/src/shared/domain/agents/built-in-charters.ts +43 -0
- package/src/shared/domain/agents/chain.ts +30 -0
- package/src/shared/domain/agents/charter.ts +61 -0
- package/src/shared/domain/agents/exclusive.ts +24 -0
- package/src/shared/domain/agents/instances.ts +249 -0
- package/src/shared/domain/code-intel-contract.ts +356 -0
- package/src/shared/domain/code-intel-routing.ts +113 -0
- package/src/shared/domain/compact-outcome.ts +44 -0
- package/src/shared/domain/compaction-thresholds.ts +161 -0
- package/src/shared/domain/compaction.ts +379 -0
- package/src/shared/domain/config-schema.ts +421 -0
- package/src/shared/domain/dev/access-cost.ts +226 -0
- package/src/shared/domain/dev/artefacts.ts +50 -0
- package/src/shared/domain/dev/batches-concurrency.ts +36 -0
- package/src/shared/domain/dev/batches-state.ts +49 -0
- package/src/shared/domain/dev/build-commands.ts +44 -0
- package/src/shared/domain/dev/call-guard.ts +341 -0
- package/src/shared/domain/dev/carried-text.ts +49 -0
- package/src/shared/domain/dev/design-rules.ts +100 -0
- package/src/shared/domain/dev/learn-proposals.ts +175 -0
- package/src/shared/domain/dev/learn-state.ts +93 -0
- package/src/shared/domain/dev/path-args.ts +42 -0
- package/src/shared/domain/dev/path-rebase.ts +93 -0
- package/src/shared/domain/dev/plan-checks.ts +190 -0
- package/src/shared/domain/dev/plan-format.ts +180 -0
- package/src/shared/domain/dev/project-files.ts +43 -0
- package/src/shared/domain/dev/questions.ts +249 -0
- package/src/shared/domain/dev/reading-rule.ts +41 -0
- package/src/shared/domain/dev/repo-pack.ts +237 -0
- package/src/shared/domain/dev/review-answer.ts +150 -0
- package/src/shared/domain/dev/review-prompt.ts +221 -0
- package/src/shared/domain/dev/reviewer-charter.ts +31 -0
- package/src/shared/domain/dev/sheet-facts.ts +83 -0
- package/src/shared/domain/dev/spec-format.ts +183 -0
- package/src/shared/domain/dev/step-budget.ts +72 -0
- package/src/shared/domain/dev/step-rules.ts +110 -0
- package/src/shared/domain/dev/test-commands.ts +90 -0
- package/src/shared/domain/dev/test-output.ts +33 -0
- package/src/shared/domain/dev/test-paths.ts +40 -0
- package/src/shared/domain/dev/tool-guards.ts +64 -0
- package/src/shared/domain/dev/trait-pattern.ts +83 -0
- package/src/shared/domain/dev/verdict-format.ts +169 -0
- package/src/shared/domain/dev/whitespace.ts +34 -0
- package/src/shared/domain/dev/work-folder.ts +67 -0
- package/src/shared/domain/dev/yaml-subset.ts +403 -0
- package/src/shared/domain/git/close.ts +273 -0
- package/src/shared/domain/git/pull-request.ts +96 -0
- package/src/shared/domain/git/worktree.ts +46 -0
- package/src/shared/domain/index-languages.ts +16 -0
- package/src/shared/domain/instructions-file.ts +18 -0
- package/src/shared/domain/iso-day.ts +4 -0
- package/src/shared/domain/llm-failure.ts +106 -0
- package/src/shared/domain/llm-profile.ts +25 -0
- package/src/shared/domain/marked-message.ts +33 -0
- package/src/shared/domain/model-catalog.ts +86 -0
- package/src/shared/domain/permission-modes.ts +103 -0
- package/src/shared/domain/prelude.ts +92 -0
- package/src/shared/domain/project-manifests.ts +83 -0
- package/src/shared/domain/search-routing.ts +85 -0
- package/src/shared/domain/secret-patterns.ts +45 -0
- package/src/shared/domain/session-keys.ts +85 -0
- package/src/shared/domain/session-start.ts +60 -0
- package/src/shared/domain/session-summary.ts +13 -0
- package/src/shared/domain/severity.ts +72 -0
- package/src/shared/domain/sha1.ts +61 -0
- package/src/shared/domain/shared-memory/agent-memory-import.ts +143 -0
- package/src/shared/domain/shared-memory/candidates.ts +41 -0
- package/src/shared/domain/shared-memory/entry.ts +145 -0
- package/src/shared/domain/shared-memory/front-matter.ts +183 -0
- package/src/shared/domain/shared-memory/gate.ts +44 -0
- package/src/shared/domain/shared-memory/harvest.ts +61 -0
- package/src/shared/domain/shared-memory/layout.ts +187 -0
- package/src/shared/domain/shared-memory/precedents-block.ts +93 -0
- package/src/shared/domain/shared-memory/refused.ts +84 -0
- package/src/shared/domain/shared-memory/verdict-rows.ts +134 -0
- package/src/shared/domain/snip-turns.ts +45 -0
- package/src/shared/domain/speech.ts +20 -0
- package/src/shared/domain/strip.ts +88 -0
- package/src/shared/domain/tool-trace.ts +122 -0
- package/src/shared/domain/types.ts +67 -0
- package/src/shared/domain/verifiers.ts +37 -0
- package/src/shared/domain/vfs.ts +9 -0
- package/src/shared/domain/workflow/state-file.ts +140 -0
- package/src/shared/infrastructure/globals.ts +52 -0
- package/src/shared/infrastructure/orkeon/approvals.ts +24 -0
- package/src/shared/infrastructure/orkeon/child-agents.ts +127 -0
- package/src/shared/infrastructure/orkeon/code-index.ts +120 -0
- package/src/shared/infrastructure/orkeon/crew-host.ts +27 -0
- package/src/shared/infrastructure/orkeon/crew-memory.ts +12 -0
- package/src/shared/infrastructure/orkeon/dev-deps.ts +172 -0
- package/src/shared/infrastructure/orkeon/files.ts +40 -0
- package/src/shared/infrastructure/orkeon/github-pull-requests.ts +29 -0
- package/src/shared/infrastructure/orkeon/host-provider.ts +22 -0
- package/src/shared/infrastructure/orkeon/human-input.ts +59 -0
- package/src/shared/infrastructure/orkeon/llm-profile.ts +38 -0
- package/src/shared/infrastructure/orkeon/llm.ts +109 -0
- package/src/shared/infrastructure/orkeon/memory-store.ts +41 -0
- package/src/shared/infrastructure/orkeon/memory-tools.ts +131 -0
- package/src/shared/infrastructure/orkeon/permission-rules.ts +42 -0
- package/src/shared/infrastructure/orkeon/progress.ts +24 -0
- package/src/shared/infrastructure/orkeon/run-state.ts +17 -0
- package/src/shared/infrastructure/orkeon/runtime-info.ts +30 -0
- package/src/shared/infrastructure/orkeon/runtime-tools.ts +60 -0
- package/src/shared/infrastructure/orkeon/script-tools.ts +134 -0
- package/src/shared/infrastructure/orkeon/session-store.ts +138 -0
- package/src/shared/infrastructure/orkeon/session-switch.ts +23 -0
- package/src/shared/infrastructure/orkeon/shared-memory.ts +61 -0
- package/src/shared/infrastructure/orkeon/shell-jobs.ts +75 -0
- package/src/shared/infrastructure/orkeon/shell.ts +31 -0
- package/src/shared/infrastructure/orkeon/telemetry.ts +63 -0
- package/src/shared/infrastructure/orkeon/tool-catalogue.ts +75 -0
- package/src/shared/infrastructure/orkeon/tool-results.ts +120 -0
- package/src/shared/infrastructure/orkeon/usage.ts +74 -0
- 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 = ["."]
|