LLMOrchestrator betalicense: Apache-2.0

Every multi-agent system needs to launch and talk to CLI agents reliably. Re-solving spawning, framing, parsing, and failure-handling per project is wasteful and error-prone. LLMOrchestrator centralizes it into one decoupled, reusable module whose specialised responsibility makes it reusable — and that reusability is destroyed the moment any consumer's specifics leak in.

It turns "run an army of heterogeneous CLI agents" from a bespoke per-project engineering slog into a single library import — pooling, circuit breaking, lifecycle management, and pluggable routing already solved and hardened. And because its anti-bluff tests exercise the real system end-to-end rather than settling for "it compiles," you get an abstraction you can actually trust to work under concurrency and failure, not one that merely looks right in a diagram.

• Hybrid pipe+file protocol — interactive speed (JSON-lines over stdin/stdout, read deadlines, response caps) *and* durable file-based exchange (inbox/outbox/shared) for large artifacts, so you never trade latency for durability or vice versa.
• Multi-provider pool with pluggable selectors — one facade over many CLI providers, with round-robin or preference-ordered routing chosen as policy rather than baked in.
• Per-agent circuit breaker + background health monitor — automatic degradation *and* recovery (3 failures → 60s open → half-open probe), so a flaky agent is isolated and then quietly brought back without manual intervention.
• Non-busy-wait pooling — Acquire blocks on sync.Cond until a matching, healthy agent frees up or the context is cancelled, so waiting costs no CPU.
• Strict decoupling + anti-bluff i18n — the NoopTranslator returns message IDs verbatim so a missing translation is impossible to miss instead of silently blank.
• Security-by-default — a binary-path allowlist means no shell interpolation and therefore no command-injection surface, backed by path-traversal protection, a 1 MiB response cap against runaway output, and API-key masking in logs.
• Anti-bluff Challenge harness — real disk/JSON/parser round-trips across five locales, with a paired mutation gate that must exit non-zero when the feature is broken — a test that proves it can actually fail.

• Reliable agent process I/O. Talking to a spawned CLI process is deceptively hard; solved with a hybrid pipe+file transport, a defined message/parser contract so both sides agree on the wire format, and a BaseAdapter that centralizes the whole process lifecycle including a graceful SIGTERM timeout that escalates to a SIGKILL fallback.
• Concurrency without busy-waiting. Solved with a mutex + condition-variable AgentPool where Acquire sleeps until a capability-matched agent actually frees up, paired with a stateless, side-effect-free parser that is safe to call from many goroutines at once.
• Provider failure isolation. Solved so one bad provider can't drag down the rest: per-agent circuit breakers contain the blast radius, and a health-monitor goroutine drives recovery even when no requests are arriving to trigger it.
• Proving correctness, not just compilation. Solved with a Challenge runner: dozens of invariants across en/sr/ja/es/de that exercise the real system, plus a paired mutation gate (LLMORCH_MUTATE_RUNNER=1 must fail → wrapper exit 99) that deliberately breaks the feature to prove the gate itself isn't a bluff.
• Localization without silent failure. Solved with the verbatim-id NoopTranslator seam and per-consumer translator injection, so a gap in translations is always visible rather than papered over.

• Go (1.25) — chosen for first-class concurrency and clean process control, which is exactly what orchestrating live agent processes demands; it implements the module, its agent adapters, transports, and parser.
• Go stdlib only (+ testify, yaml.v3) — a deliberate choice to keep the dependency surface minimal and pull in *no* LLM SDKs, so the module stays lightweight and embeddable inside any consumer without dragging vendor baggage along.
• Pipe transport (JSON-lines over stdio) — chosen for fast interactive messaging, hardened with read deadlines and response-length limits so a hung or runaway agent can't stall the caller.
• File transport (inbox/outbox/shared) — chosen for durable, large-artifact exchange per session, where a pipe would be the wrong tool.
• sync.Mutex/sync.Cond — chosen to implement blocking, fair agent-pool acquisition without busy-waiting.
• Circuit breaker + HealthMonitor — chosen together to deliver per-agent resilience *and* active recovery, not just failure detection.
• pkg/i18n Translator — chosen as the decoupled localization seam that keeps consumer-specific strings out of the core.
• Challenge harness (challenges/runner) + Makefile (test -race, fuzz, cover) — chosen for anti-bluff, evidence-backed verification, including race detection and parser fuzzing so correctness is demonstrated under adversarial conditions, not assumed.

• Status: beta. A decoupled reusable module, consumed as a submodule by multiple Helix/vasic projects. License: Apache-2.0; the GitHub repo is public.
• Model metadata comes from LLMsVerifier bridged via HelixQA; this module does not import LLMsVerifier/VisionEngine/DocProcessor directly. Stacks referenced in the parent app's CLAUDE.md (Gin/PostgreSQL/etc.) describe helix_code, not this module.

Priority tier: Helix-primary (LLM-infrastructure cluster — decoupled reusable module). Ranks after HelixTrack.