Runs & Orchestration

The Cendriix Orchestrator is the engine that converts your intents (tickets, tasks, or free-form instructions) into coordinated agent executions. Every unit of work you trigger — from the Studio, a flow, or directly via API — becomes a Run. Monitor all runs from the Agents Window (G R) in the sidebar.

The orchestrator is built from four modules: orchestrator, model-router, agent-runtime, and mcp-gateway.

Run lifecycle

Every unit of work is a Run. A run’s status follows a strict finite-state machine with four phases plus approval gates:

Intake phase


intake-queued → triaged → scoped → plan-draft → [plan-approval] → planned

The orchestrator decomposes your input into a RunPlan — an ordered DAG of steps with agent roles, dependencies, and cost estimates.

Build phase


planned → routed → executing → testing

Steps are executed in topological order. Each step is dispatched to the appropriate agent via the model router.

Review phase


testing → review → pr-opened → [merge-approval] → merged

Code is reviewed, a PR is opened, and (if configured) a human approval gate pauses the run before merging.

Deploy & operate phase


merged → deploying → [deploy-approval] → deploy-verifying → operating → self-healing

After merge, the run can optionally deploy and monitor the change.

Terminal states

Any state can transition to failed or cancelled. Failed runs can be re-queued manually.

Approval gates (HITL)

States marked with [...] are Human-in-the-Loop gates. The workflow pauses at these points and surfaces an approval card in the Cendra chat interface. The run advances only after explicit human approval.

Task decomposer

When a run is created via POST /runs, the orchestrator invokes the Task Decomposer. It takes the input’s title and body, calls the model router, and generates a RunPlan: an ordered list of plan steps.

Each step has:

Field	Description
`id`	Stable identifier (e.g., `step-1`)
`name`	Human-readable name
`order`	Execution order (zero-indexed)
`dependsOn`	IDs of steps that must complete first
`agentRole`	`planner`, `coder`, `tester`, `reviewer`, `deployer`, or `analyst`
`capability`	`code_generation`, `code_review`, `test_generation`, `pr_management`, `deployment`, `analysis`, or `general`
`prompt`	Full context forwarded to the agent
`maxAttempts`	Retry limit before marking the step failed
`estimatedCostUsd`	Pre-flight cost estimate
`reversibilityTier`	`read-only`, `reversible`, `soft-reversible`, or `irreversible`
`confidenceScore`	0–1 confidence rating

Steps with reversibilityTier: "irreversible" automatically insert a mandatory approval gate before execution.

Preview without creating a run

Use POST /orchestrator/decompose to get an enriched plan without creating a run. This powers the intent-preview UI where you can review the plan and cost before committing.

Use POST /orchestrator/estimate to re-cost an edited plan.

Execution engine

Once a run is in planned state, the execution engine:

Transitions the run through planned → routed → executing
Performs a topological pass over the plan steps — finding all steps whose dependencies are satisfied and dispatching them in parallel
Retries failed steps up to maxAttempts times with exponential backoff
Detects dependency cycles and fails the run if no step can make progress
On successful completion, advances through testing → review → pr-opened → merged

Model router

The model router selects the best available model for each inference call, invokes it through the correct provider, and handles failures gracefully.

Model sources

Source	Description
Orchestrated	The `cendriix-orchestrated` meta-model — resolved per call to a concrete model
Bedrock	AWS Bedrock models (Claude, Gemma, GPT-OSS, Qwen, DeepSeek)
Custom	Cendriix fine-tuned models on SageMaker
Native BYO-key	Frontier APIs with your own key (Anthropic, OpenAI, Google)

Routing policy

Each task type (code_generation, reasoning, summarisation, classification, general) maps to an ordered candidate list. The router scores candidates by cost/latency and circuit-breaker state, then iterates until one succeeds.

Circuit breaker

Models that accumulate failures have their circuit breaker opened. Subsequent requests skip that model for a 30-second probe window. On success, the breaker resets.

MCP gateway

The MCP gateway connects agents to external tools via registered connectors. Each connector exposes a set of tools (e.g., “create Jira issue”, “read GitHub PR”) that agents can invoke during execution.

Tools are:

Discovered via GET /mcp/tools
Executed via POST /mcp/execute
Subject to guardrail policy evaluation before execution

Cost estimation

Every plan step carries a pre-flight estimatedCostUsd. The plan-level cost is the sum of all step estimates. You can:

Preview costs before dispatch via POST /orchestrator/decompose
Set per-run budget caps via PUT /metering/runs/:runId/budget
Monitor real-time costs via GET /metering/runs/:runId/costs

Runs that exceed their budget cap are paused and surfaced for human decision.

Agents Window

The Agents Window (/runs) is the fleet supervisor UI. It shows all active and recent runs with live status, cost, and duration. Filter by source (agent / workflow / orchestrator) using the tab strip.

From the Agents Window you can:

View the run DAG and current progress
Inspect individual step outputs and reasoning trails
Approve or reject HITL gates inline
Cancel or re-queue failed runs
Promote a successful run to a playbook

See also: Flows, Agents, The Studio, Cost Controls