Agent Engine Paths

Stella has one agent engine and many doors into it. Whether you type into the Command Deck, script stella run in CI, or fan a fleet out across worktrees, the same core loop does the work: the step-driver in stella-core, driving the same tool stack, metered by the same budget, recorded into the same session store. The paths differ in how a turn is framed, verified, supervised, and persisted — and picking the right door is most of the craft.

This page is the map. For the user-level tour of the modes, see Agent Modes; for what happens inside a verified turn, see the Inference Pipeline.

What every path shares

Before the differences, the invariants — these hold no matter which door you came through:

• One step loop. The engine takes one model call per step, executes the proposed tool calls (read-only calls fan out in parallel), feeds results back, and repeats until the model stops, a budget trips, or a backstop fires. No hidden swarm, no coordinator process.
• One tool stack. Every path assembles the same layered tool executor: the native registry, wrapped by MCP-server tools, wrapped by custom script tools, wrapped by the interactive layer (ask_user, the skills-registry tools), wrapped by the discovery layer (tool_search, skill_search, mcp_search). What varies per path is only what gets layered on top (deck taps, read-only views — see below).
• Memory rides along. Relevant memories and skills are recalled per prompt and injected as a volatile block after the byte-stable system prefix, so prompt caching survives across turns.
• Budgets are enforced everywhere. --budget caps USD spend on every path; without it, spend is still metered for the cost summary.
• Everything is recorded. Each turn opens an execution record (files touched, tool use, memory citations, cost, outcome) in the workspace store, feeding telemetry, stella stats, and the deck's AGENT ENGINE tab. Sessions are durable and resumable (stella resume).
• Per-role model routing applies. The agent engine config pins models per role (worker, triage, judge), and every path that uses those roles honors the pins.

The map

One-shot: stella run

The scripting workhorse: one prompt in, verified work out, an exit code back.

Pipeline (default). The prompt runs the full staged pipeline — triage → recall → plan → scope review → witness → execute → verify → judge, with a bounded revise loop — with per-role model routing and circuit-breaker fallback. Pass --test-command "cargo test -p …" and verification gets a deterministic oracle: a change that flips a failing test to passing can submit without spending a judge call. Headless formats (--output-format json for one final object, stream-json for a line per agent event) make it automation-grade — see Scripting.

Raw (--no-pipeline). Skips the stages and drives one plain step-loop turn. No triage, no judge — the model works until it decides it's done. Cheapest and fastest; the right door for questions, small mechanical edits, and anything you'll eyeball anyway.

Use it when the task is well-defined and you don't need to watch. Prefer the pipeline default whenever the result must be provably right; drop to --no-pipeline when speed beats ceremony.

Interactive: the Command Deck and the plain REPL

Running stella on a real terminal opens the Command Deck — the tabbed TUI over the engine. Each prompt becomes a lead-agent turn; /pipeline toggles between staged turns (the default) and the raw step loop. The deck is more than a chat surface: prompts queue while a turn runs, ! lines run shell commands in their own lane, Esc cancels, and tabs expose the session's files, diff, code graph, skills, MCP servers, and the AGENT ENGINE panel with live executions and per-role model pickers.

Two things are unique to deck turns:

• Taps. The lead's tool stack is wrapped in a file-change tap (live FILES/DIFF tabs) and a task tap (the task board and sub-agent spawning).
• Cooperative claims. The lead claims files on first write, so parallel workers in the same tree never fight over a file.

stella --plain (or any non-TTY stdin/stdout, or STELLA_PLAIN=1) falls back to the plain REPL: the same per-prompt raw turns and the same session memory, in a line-based interface with slash commands. It's the low-dependency door — SSH sessions, minimal terminals, teaching demos.

Use the deck when you're exploring, iterating, or supervising real work interactively. Use the plain REPL when you want interactivity without a TUI.

Delegated: deck sub-agents

Inside a deck session, the lead agent can delegate: the task_assign tool queues a task, and a supervisor spawns a sub-agent with its own conversation and the same tool stack — running concurrently while the lead keeps working, its spend metered into the session's shared budget guard (child spend always reaches the parent's ledger; fleet children, by contrast, each run under their own slice of the cap). Results return to the lead for review; every sub-agent turn is recorded (deck-sub) and visible in the AGENT ENGINE tab. You don't invoke this path directly — you ask for work that warrants it, and the lead fans out.

Use it when (implicitly) a deck task decomposes into independent chunks — noisy searches, parallel investigations — that shouldn't bloat the lead's context.

Outcome-driven: stella goal

Goal mode inverts the contract: you state what must be true when done, not what to do. The engine works in rounds; after each round an independent judge — routed to a different model family than the worker whenever possible, and holding a read-only view of the same tool stack — assesses the goal from evidence (running tests, reading CI, inspecting files), never from the worker's claims. Rounds continue until the judge confirms the goal, or a backstop (round cap, --budget, worker abort) ends the run honestly as not met.

Each working round is a staged pipeline run by default; --no-pipeline makes rounds raw step-loop turns — double verification (pipeline judge and goal judge) is rigor you pay for, so drop the inner pipeline when the goal judge alone is enough.

Use it when you can state the outcome crisply but not the steps — "the suite passes and clippy is clean", "the flaky test is fixed, proven by 50 consecutive runs". See Goal mode in depth.

stella monitor: goal mode, specialized

Monitoring is a goal: the objective is pinned to "the latest CI run for target is fully green", assessed through the ci_status tool. The engine fixes failures, pushes, waits out the next run, and only a green board ends the loop. Same machinery, fixed objective.

Use it when the branch or PR must end up green and you don't want to babysit the CI cycle.

Parallel: stella fleet

When the work is many tasks rather than one, fleets fan a dependency-ordered task DAG out to parallel workers — in one shared tree coordinated by cooperative file claims, or in dedicated worktrees for tasks marked isolation = "isolated". Each worker drives the same engine per task (staged pipeline when available, raw step loop otherwise), and every attempt, commit, and dollar lands in .stella/fleet.db for review.

Use it when you have a backlog, not a task: migrations across many modules, a list of independent fixes, wide refactors.

How the tool stack varies

The tool catalog is shared, but each path decorates it differently:

Every path can also opt into the lean toolset — STELLA_LEAN_TOOLS advertises only a lean core plus the discovery tools; see Built-in Tools.

Two consequences worth knowing. First, ask_user degrades gracefully: headless paths (one-shot JSON formats, goal in CI) fail it loudly with guidance to proceed, rather than hanging on stdin. Second, because the discovery tools are read-only, even the judge can run tool_search, skill_search, and mcp_search — searching is never a side effect.

Choosing a path

• Watching and steering → the Command Deck (stella).
• Interactive, but minimal → the plain REPL (stella --plain).
• One defined task, unattended → stella run (add --test-command for the strongest verification; --no-pipeline for speed).
• A defined outcome, unknown steps → stella goal.
• CI must be green → stella monitor.
• A backlog of tasks → stella fleet.
• Continuing yesterday's session → stella resume.

For contributors: the code map

Every path is a thin stella-cli entry point over stella_core::Engine. If you're changing engine behavior, these are the seams:

The execution-kind strings in the map are what these paths stamp on their execution records — the same strings you'll see in stella stats, the exported dashboard, and the deck's AGENT ENGINE tab, so a telemetry row always traces back to the door the work came through.

Where to go next

• Agent Modes — the user-level guide to the same territory, with deck keybindings and examples.
• Inference Pipeline — inside a staged turn: triage → recall → plan → scope review → witness → execute → verify → judge, with a bounded revise loop.
• Agent Fleets — plan files, waves, claims in the shared tree, and opt-in isolated worktrees.
• Agent engine config — per-role model pins the paths share.
• Built-in Tools — the shared catalog, including the discovery tools.
• Scripting — headless output formats, exit codes, and automation patterns for the non-interactive paths.