Skip to main content

Turn Loop

Every turn through Paddles follows the same arc: understand the context, investigate the workspace, and synthesize a grounded answer. The architecture exists to give small local models the structured support they need to produce answers that rival much larger models.

The Three Acts​

Act 1: Interpretation​

Before any routing decision, the harness assembles the full picture.

It loads AGENTS.md operator memory from system, user, and workspace scopes. A model-derived guidance subgraph discovers relevant procedures, tool hints, and project knowledge. Recent turns, retained evidence, and prior tool state complete the context.

By the time the planner sees the prompt, it already knows the operator's priorities, the project's conventions, and the tools at its disposal.

Act 2: Recursive Planning​

The planner model evaluates the assembled context and selects its next bounded action: answer directly, search the workspace, read a file, inspect state, run a shell command, refine a query, branch into subqueries, or stop.

A controller validates each action against schema and budget contracts, executes it safely, appends the output back into context, and loops. Each pass adds real evidence grounding the eventual answer in workspace reality.

The retrieval actions are explicit:

  • search — gather ranked evidence for a query
  • refine — rerank and re-query based on the current planner loop state

Both actions use the search and retrieval subsystem and emit visible progress until either retained evidence is assembled or the gatherer stops.

The loop continues until the planner determines it has enough evidence, the budget is met, or an explicit stop is reached.

Act 3: Synthesis​

A separate synthesizer model takes the accumulated planner trace and evidence bundle and produces the final user-facing response. This is a distinct model call optimized for answer quality, grounded in the concrete evidence the planner gathered.

Why Separate Planning And Synthesis​

Three properties compound to raise effective model performance:

  1. Interpretation arrives first. Operator memory and project guidance shape the planner's priorities before it commits to any action.
  2. Recursive evidence gathering earns the answer. Instead of generating from memory alone, the planner iteratively reads, searches, and refines until it has concrete evidence.
  3. Planning and synthesis are separate workloads. The best recursive investigator may differ from the best answer composer. Separating them lets each be routed to the smallest capable model.

Visibility​

Every step of this process is surfaced through the TUI transcript or plain CLI output: interpretation assembly, planner action selection, gatherer work, tool calls, context strain, fallback decisions, and synthesis.

Paddles uses one shared verbosity contract across the TUI and web UI event stream:

  • 0 is the default operational view. It keeps the main action stream visible while suppressing low-value direct-response bookkeeping.
  • 1 adds info-tier planner and synthesis metadata.
  • 2 adds debug-tier routing, capability, and richer interpretation detail.
  • 3 adds trace diagnostics and the most verbose transport logging.

When a step takes longer than two seconds with no new event, the TUI inserts a contextual in-flight indicator — "Planning...", "Synthesizing...", "Searching..." — so the operator always sees forward motion. Those in-flight rows help long turns stay legible without forcing the default verbosity to show every routing and synthesis bookkeeping event.

Where Steering Signals Intervene​

Steering signals are the controller layer between the planner's proposed action and the next loop step.

interpretation assembled
   ↓
planner proposes next bounded action
   ↓
controller checks steering signals
   ├─ context strain: is the working set degraded?
   ├─ action bias: should this turn act on a likely file now?
   ├─ premise challenge: do the sources already justify refinement or stop?
   ├─ compaction cue: should active context be tightened?
   └─ budget boundary: have we hit a hard loop cap?
   ↓
execute action, refine context, or stop and synthesize

This is how the harness stays both model-directed and disciplined. The model chooses direction, but the controller can insist on acting, refining, or stopping when the trace already supports that choice better than another redundant step would.