Adaptive Harnesses

Most users can select an agent harness and use the normal run commands. Use the adaptive harness API when you want to compare or repair how an agent runs while proving exactly what changed between candidates.

Adaptive harness experiments separate three objects that are easy to blur together:

• the trusted code that may execute;
• the selected agent-harness configuration; and
• the program that schedules task attempts.

The API calls these objects K, Hx, and px:

Keeping these identities separate makes a comparison interpretable. Claims about learning or transfer require separate evidence.

Trusted execution code (K)

The fixed kernel (K) is the versioned code allowed to execute in an adaptive run. Its identity records the kernel version and a digest of that executable source.

If this code changes, the experiment records a new kernel identity. This prevents a harness candidate from quietly changing the machinery used to test it.

Harness configuration (Hx)

HarnessSpec is the declarative input for one harness. It describes runtime capabilities, bindings, contracts, recursion policy, and budgets. The artefact-task runner owns attempt branching, selection, and verification.

Compiling a HarnessSpec against one fixed kernel produces the compiled harness instance (Hx). This is the exact harness configuration used in the experiment. It selects the model, bindings, capabilities, and limits while the fixed execution code stays unchanged.

Typical fields include:

• the agent-harness kind, such as direct, tool loop, RLM, or Lambda-RLM;
• model and endpoint references;
• turn, token, subcall, cost, and concurrency limits;
• declared capabilities and output requirements; and
• the kernel reference against which the instance was validated.

An Hx change is therefore an explicit experimental treatment recorded separately from the incumbent run.

Execution plan (px)

The execution program (px) says which task operations to run and in what order. The library validates this plan and compiles it into a RunBundle for the adaptive execution path.

Ordinary artefact tasks use run_experiment() and run_trial(). Governed adaptive studies use the separate run_batch.v1 execution-program path.

A program can express bounded patterns such as:

• one task attempt;
• independent task fan-out;
• a declared stage graph;
• a coalesced batch operation; or
• a final output-commit step.

Each operation must come from the fixed kernel.

Compare one change at a time

Keeping the three identities separate makes comparisons interpretable:

fixed K
  + candidate Hx
  + candidate px
  + exact task snapshot
  -> validated RunBundle
  -> Harbor execution
  -> imported TrialRecord and receipts

Vary either Hx or px in one comparison while holding the other and K fixed. The task snapshot, verifier, seeds, repetitions, and shared budget must also remain explicit.

Use with the meta-harness API

K / Hx / px is one specialist candidate shape. The generic meta-harness API accepts other candidate shapes through their evaluator functions. Harness-program studies use run_harness_study() to compare candidates while keeping their normal compilation, Harbor execution, trial evidence, analysis, and reports.

The adaptive cycle uses run_meta_harness() for its bounded candidate selection and refinement shape. Repair still owns diagnosis and typed patch creation. Motif learning and promotion remain with their governance owners.

Other callers can compare different types of candidate through the same API. Each evaluator returns its normal TrialRecord evidence, and the caller defines how to compare it.

Compilation and execution

The compiler fails closed before execution when a candidate:

• names a primitive outside the fixed kernel;
• exceeds a declared budget;
• contains an invalid graph or unreachable node;
• refers to an incompatible task or harness profile; or
• cannot bind every execution dependency to the frozen identities.

Successful compilation produces an immutable run bundle, which Harbor executes. AEC-Bench still packages the task, isolates the workspace, runs the official verifier, collects outputs, and imports the trial.

Evidence and authority

The host owns acceptance; candidate code may propose a configuration or program. The host records:

• proposal and compilation identities;
• node and stage receipts;
• task, verifier, and output identities;
• actual budget usage;
• task outcomes and infrastructure failures; and
• the authority decision that allowed any promotion or repair.

Task failure and evidence-system failure remain distinct. Candidate comparison requires complete receipts, valid imports, and available infrastructure.

Repair and optimisation

Repair and optimisation are separate uses of the same contracts:

• repair starts from a typed failure attributed to Hx or px and permits only an authorised patch to that owner;
• optimisation compares a frozen proposal set even when the incumbent is already valid.

Claims about learned policies or transfer require separate, preregistered evidence beyond candidate selection, patching, or comparison.