Engine Reference¶

Parameter catalogs for the engine classes in lionhub.orchestration.engines. All engines inherit from Engine (base parameters documented first).

Engine (base)¶

Stateless event-driven engine base.

Parameter	Default	Description
`model`	`None`	Default model string for every stage.
`max_tokens`	`None`	Output-token limit for every Anthropic agent model the engine builds; a call to `make_agent` can name its own. `None` leaves the provider's default (the Anthropic endpoint sends 8192). A CLI agent has no such limit and any other API provider has no tested mapping for one; the build refuses both.
`models`	`None`	Optional per-stage model overrides: `{"stage": "provider/model", ...}`. The constructor copies a provided mapping and normalizes `None` or an empty mapping to an internal `{}`.
`max_depth`	`3`	Maximum recursion depth or cycle generation.
`max_concurrent`	`5`	Concurrency semaphore width (simultaneous agent slots).
`max_agents`	`50`	Hard cap on total agents the run may create.
`deadline_s`	`None`	Wall-clock cap in seconds; `None` = unbounded.
`emission_reply_text`	`False`	Put the failed reply's text (capped at `RAW_RESPONSE_TEXT_CAP` characters) on `emission_repair` and `emission_missing` events. Off, those events carry the scalar facts only: stop reason, usage, model, block types, `text_chars` and `max_tokens_configured` (the output-token limit the leg's model was built with, `None` when none was set).
`fallback_deadline_s`	`None`	Seconds allowed for the one fallback leg that retries a silent stage on `models["review_fallback"]`. A leg still running at the limit is abandoned (`emission_fallback_timeout`) and the emission stays missing unless it had already arrived. `None` = unbounded.
`judge_model`	`None`	If set, a cheap gate agent runs at expansion points. `None` = no gate (fail-open).
`judge_role`	`"critic"`	Casts role for the judge agent.
`cancel_timeout_s`	`30.0`	Seconds to wait for spawned tasks to settle after cancellation. Tasks still pending at the deadline are warned about and abandoned after one final cancellation request. CLI process-group cleanup starts immediately after task cancellation and has its own bounded TERM-to-KILL grace.

When a judge denies an expansion, an ordinary failure of the gated event callback is logged by type with its message redacted, and the denial still stands. A containment refusal or an agent-configuration error in the callback's exception chain is raised. If the chain is unreadable or exceeds 100 distinct nodes or 100 exception-group members, the original callback exception is raised. Interrupts and cancellations are not suppressed.

Emission events carry these fields. emission_repair has repair_index, the number of repair prompts sent to the leg so far (its operate call number is repair_index + 1), and emission_recovered has operate_call, the operate call number within the fallback leg that produced the emission. emission_missing has attempts, the operate calls made across both legs, a call cut short by fallback_deadline_s included. emission_fallback_timeout has limit_s, the deadline that ended the fallback leg. If the emission had already arrived when that deadline fired, emission_recovered follows the timeout event. emission_repair and emission_recovered also keep attempt, with the same value as repair_index and operate_call.

On budget exhaustion Engine.run() calls _partial_export() (override in subclasses to return a partial result) instead of raising. Caller-initiated cancellation still propagates as CancelledError.

Every CLI process started under an engine run through the shared provider spawn helper, which every built-in CLI provider uses, is registered with that run. EngineRun.cancel_active() asks tasks to cancel, independently reaps any still-live registered process groups, and appends a CancellationRecord to run.cancellation_records. The record keeps four counts separate: tasks_cancelled, tasks_abandoned, processes_reaped, and processes_abandoned — a reap that raised, so the child is still running. Read processes_abandoned rather than inferring from processes_reaped == 0, which a run with nothing to reap also produces. A reap counts under processes_reaped once the direct child is ended; when nothing proves the child's process group is still the spawn's own, the rest of that group is not signalled. A normally completed CLI worker is not signalled, and a run with no CLI workers does no process cleanup. The tracked group is the child's initial process group, not a containment boundary: a descendant that deliberately creates another session is outside this guarantee.

CodingEngine¶

Gated implement/test/fix-loop engine (lionhub.orchestration.engines.coding).

Extends Engine with:

Parameter	Default	Description
`plan_role`	`"analyst"`	Casts role that writes the implementation plan (`WorkPlanned`).
`implement_role`	`"implementer"`	Casts role that writes code using `coding_tools`.
`verify_role`	`"critic"`	Casts role that issues the `VerifyResult` verdict.
`coding_tools`	`("coding",)`	Tool names granted to the implementer agent.
`implement_permissions`	`"safe"`	Permission preset for the implementer.
`max_fix_rounds`	`3`	Maximum test-fail re-prompt rounds before concluding.
`test_timeout_s`	`600.0`	Wall-clock cap for each subprocess test run.
`repair_retries`	`1`	Emission-repair turns per stage when the model emits no valid event.
`turn_timeout_s`	`600.0`	Wall-clock cap for each implementer model turn, including fix turns. A timeout records `turn_timeout` and drives the emission-repair path; `None` disables the cap.
`strict_spec`	`False`	Raise `ValueError` on the first spec-lint warning before creating an agent. When `False`, warnings are emitted and execution continues.
`heartbeat_interval_s`	`30.0`	Seconds between implement-stage `WorkerHeartbeat` checks; file mtime changes also emit `WorkerActivity`. `None` disables heartbeats.
`stage_timeout_s`	`None`	Optional wall-clock cap applied to every model stage. A timeout always emits `WorkAborted` (with a `hard` flag). Implement and fix timeouts are hard: the run aborts and concludes failed. Plan and verify timeouts are soft: the stage is bounded but the run recovers — a timed-out planner degrades to the raw task text, and a timed-out verifier omits its advisory verdict while the test result still decides pass/fail.
`worker_extra_tools`	`()`	Additional tool names granted only to the implementer, appended to `coding_tools`.
`worker_mcp_servers`	`None`	Optional MCP server names granted only to the implementer.
`worker_extra_prompt`	`None`	Optional extra prompt text passed only to the implementer.
`auto_repair_cmds`	`None`	Optional commands run in sequence before each authoritative full test gate. Successful commands emit `AutoRepairApplied`; failed commands are reported without aborting the run. Internally normalized to `[]`.
`fast_test_cmd`	`None`	Optional string or argument-list command used as an incremental gate on intermediate substantive fix rounds; the declared `test_cmd` remains the final ground-truth gate.

Per-stage model routing keys: "plan", "implement", "verify".

Pipeline shape: plan → implement → test → [fix loop, up to max_fix_rounds] → verify → CodeResultRecorded.

HypothesisEngine¶

Evidence-chain engine for hypothesis-driven development (lionhub.orchestration.engines.hypothesis).

Extends Engine with one casts role per stage:

Parameter	Default	Description
`question_role`	`"analyst"`	Extracts `QuestionRaised` events from findings.
`research_role`	`"researcher"`	Gathers `EvidenceCollected` for a question.
`hypothesis_role`	`"analyst"`	Forms `HypothesisFormed` or direct `ConclusionDrawn` from evidence.
`design_role`	`"evaluator"`	Designs the decisive `ExperimentDesigned`.
`validate_role`	`"analyst"`	Executes experiments and records `ResultRecorded`.
`conclude_role`	`"critic"`	Draws `ConclusionDrawn` from a result.
`apply_role`	`"architect"`	Maps conclusions onto decisions as `ApplicationMapped`.
`synthesis_role`	`"synthesizer"`	Writes the final evidence report.
`executable_methods`	`("analysis", "comparison", "proof")`	Experiment methods the validator runs inline. Others queue on `run.pending`.
`validate_tools`	`()`	Tool names granted to the validator agent for real measurements.
`validate_cwd`	`None`	Workspace the validator is path-guarded to.
`validate_permissions`	`"safe"`	Permission preset for the validator.
`max_questions`	`8`	Per-extraction cap threaded into the prompt (soft; judge and budget are the hard bounds).
`repair_retries`	`1`	Re-prompt turns when an expected emission did not arrive.

max_depth (from Engine) bounds back-edge cycles: follow-up questions and findings raised at gen > max_depth are recorded but not expanded.

Per-stage model routing keys: "extract", "research", "hypothesize", "design", "validate", "conclude", "apply", "synthesize".

Pipeline shape: seed findings → extract questions → gather evidence → form hypotheses → design experiments → validate → draw conclusions → apply to decisions → synthesize report.

PlanningEngine¶

Plan-then-execute engine over the reactive DAG executor (lionhub.orchestration.engines.planning).

This is the engine li o flow uses as its CLI front-end.

Extends Engine with:

Parameter	Default	Description
`orchestrator_role`	`"orchestrator"`	Casts role that decomposes the prompt into a `list[TaskAssignment]`.
`roles`	`("researcher", "analyst", "critic", "architect", "synthesizer")`	Roster the orchestrator may assign workers to.
`synthesis_role`	`"synthesizer"`	Casts role that writes the final deliverable from worker outputs.
`reactive`	`True`	When `True`, every worker is granted `SpawnRequest` so the live DAG self-expands. `False` runs a flat, fully-planned DAG.

Worker roles use the shared engine agent builder, so model, effort, yolo, agent_cwd, agent_extra_prompt, agent_mcp_config_path, and khive_injection apply to workers as well as the planning and synthesis stages. Engine settings override role-profile defaults; injection receives the run's namespace unless the caller pins one. Planned and reactively spawned worker clones retain context providers, with separate registry budgets and statistics, along with their role name and SpawnRequest grant, so a clone still records recalls and writebacks under its role and still grows the live DAG. A clone that starts from a role template still recalls on its first turn: planned workers, role-targeted spawns, and an independent spawn with no assignee all take that path. A dependent spawn with no assignee instead continues its emitter's conversation, so under the default first_turn cadence it adds no recall of its own.

Each distinct worker role template triggers on_branch_created; task clones do not. Role templates are exempt from max_agents, like synthesis: they are the scaffolding the plan already fixed, so a budget at or below the assignee count still runs every planned task. An independent spawn with no assignee runs on a clone of its emitter's role template, so it carries the engine's worker settings without inheriting the emitter's conversation. agent_env and contain_account_integrations=True remain unsupported: managed-DAG worker clones do not yet have verified environment/containment provenance.

Pipeline shape: orchestrate (produce DAG) → execute reactively → synthesize outputs into deliverable.

ResearchEngine¶

Recursive, reaction-driven research engine (lionhub.orchestration.engines.research).

Extends Engine with:

Parameter	Default	Description
`novelty_threshold`	`0.7`	A `FindingEmitted` above this novelty spawns a deeper exploration node.
`roles`	`("researcher", "analyst", "critic")`	Casts roles forming each exploration team (run in sequence, sharing output). Each is granted the research emissions.
`synthesis_role`	`"synthesizer"`	Casts role that writes the final synthesis from the emission store.
`repair_retries`	`1`	Re-prompt turns when an exploration node's whole team emitted no finding.

max_depth (from Engine) bounds recursive depth; max_agents and deadline_s bound cost.

Pipeline shape: explore topic (team of agents) → spawn deeper nodes on high-novelty findings → quiesce → synthesize.

ReviewEngine¶

Dimensional review engine (lionhub.orchestration.engines.review).

Extends Engine with:

Parameter	Default	Description
`dimensions`	`("correctness", "security", "performance", "maintainability")`	Review lenses; each runs one reviewer agent in parallel.
`reviewer_role`	`"critic"`	Casts role for dimension reviewers.
`verifier_role`	`"critic"`	Casts role for adversarial verifiers.
`synthesis_role`	`"synthesizer"`	Casts role that issues the terminal `ReviewVerdict`.
`verify_severities`	`("critical", "major")`	Issue severities that reactively spawn an adversarial verifier.
`verify_clean`	`True`	When a run reaches quiescence with zero `VerifyResult` (clean or minor-only review), spawn one adversarial audit of the clean verdict itself.
`repair_retries`	`1`	Re-prompt turns when a reviewer or verifier emits no valid event.
`stage_max_tokens`	`None`	Per-stage output-token limit over `max_tokens`: `{"review": 16384, "review_fallback": 16384}`. The stages are `review`, `review_fallback`, `verify` and `verdict`; any other name is refused. An unset stage uses `max_tokens`, then the provider's default.

Pipeline shape: fan-out (one reviewer per dimension, parallel) → adversarial verify high-severity issues → quiesce → clean-verdict audit if no verification ran → ReviewVerdict.

Every dimension emits affirmatively: issues arrive as IssueFound, a clean dimension arrives as DimensionClean (dimension + one-sentence rationale). A dimension that emits nothing is therefore a transport failure, never an implicit all-clear — the verdict instruction lists affirmed-clean dimensions separately so downstream consumers can distinguish "reviewed, clean" from "reviewer never reported". Verifier arrival keys on a short engine-assigned ref token echoed back in the VerifyResult, so a paraphrased issue description does not burn repair rounds.

MCP connection failures are isolated only after the originating client gets a bounded liveness probe. This distinguishes the SDK's own closed-session signal from a server that returns the same bare -32000 / Connection closed error while its transport remains usable. If every configured dimension fails before producing evidence, synthesis is skipped and no ReviewVerdict is emitted.

A clean or minor-only review spawns no issue verifiers, so it would otherwise terminate with zero VerifyResult — indistinguishable, by evidence, from a run whose verification never happened. With verify_clean on, such runs get one adversarial verifier auditing the clean verdict: it must execute a concrete check against the artifact and name what it executed in its rationale, and it emits a VerifyResult carrying the run's clean ref. In the verdict instruction these audits are listed apart from issue verifications because their polarity is inverted: holds=false there refutes the review's clean verdict and weighs against approval.