---
title: Model-Harness Interface Contract
url: https://www.emergentmind.com/topics/model-harness-interface-contract
type: topic
---

# Model-Harness Interface Contract

Searching arXiv for the cited papers to ground the article in current literature.
{"query":"arXiv:2605.24220 Polar Agentic RL on Any Harness at Scale", "max_results": 5}
The **Model–Harness Interface Contract** is the explicit specification of the boundary between a model and the harness that mediates prompts, tools, memory, state, verification, and resource control. In recent agent systems, the contract is no longer treated as an implicit implementation detail. It appears instead as a formally specified runtime layer: Polar describes it as “a small, stable, and asynchronous four-call protocol, underpinned by a token-faithful proxy and a set of MDP-style abstractions” [2605.24220]; Natural-Language Agent Harnesses describe it as “a small design-by-contract layer on top of ordinary LLM and tool calls” [2603.25723]; and work on Physical AI defines it as a deploy-time declaration of output region, inference budget, and operating regime, enforced end-to-end by robot middleware [2606.09416]. Across these formulations, the contract serves the same function: it makes the model–environment boundary inspectable, enforceable, and, in principle, portable across runtimes and training stacks.

## 1. Conceptual emergence and scope

A useful compact expression of the modern view is the identity **Agent = Model + Harness** [2605.27922]. In that formulation, the harness is the system layer that constructs every prompt to the model, parses every model response into a discrete action, invokes tools or mutates workspace state, enforces constraints and permissions, traces every step, and recovers from errors. The contract is therefore not merely an API surface. It is the formal account of what the harness must expose to the model, what the model may emit back, what side effects are allowed, and what evidence must be retained.

A parallel formulation in software-engineering agents treats the end-to-end system as **Model \(M\)**, **Harness \(H\)**, and **Environment \(E\)** working on task \(T\), with the harness responsible for task specification, context selection, tool access, project memory, task state, observability, failure attribution, verification, permissions, entropy auditing, and intervention recording [2605.13357]. This broadens the contract from a message schema into an operational substrate. The harness does not only ferry requests and responses; it curates context, mediates execution, and produces the evidence by which completion, safety, and maintainability are judged.

The theoretical motivation for making this boundary explicit is sharpened by the notion of **Interface Volatility**, defined as behavioral degradation that appears when model and harness are integrated even though each layer “works” in isolation [2606.04017]. That work argues that Agent Epistemic Integrity requires an explicit contract preserving belief, capability, and goal commitments across session boundaries and independent layer upgrades. Earlier contract-based systems work supplies a related antecedent: the enriched SysML/OCL Contract pattern represents a contract as a septuple \(C = (S, s_0, \Sigma^I, \Sigma^O, \Sigma^H, Pre, Post, T)\), then checks compatibility through interface-automata composition and reachability of illegal states [1703.07037]. The contemporary model–harness contract inherits this design instinct: compatibility is a property of the boundary, not of either constituent alone.

## 2. Formalizations of the contract

Different research programs formalize the contract in different mathematical objects, but the recurring structure is a constrained interface between model outputs, harness mediation, and environment transitions.

| Paper | Formal object | Core elements |
|---|---|---|
| Polar [2605.24220] | Four-call protocol + MDP | `prewarm`, `execute`, `reconstruct_trajectory`, `evaluate`; Trajectory; \(M=(S,A,P,R,\gamma)\) |
| NLAH / IHR [2603.25723] | Contract \(\kappa\) + `AgentCall` | `RequiredOutputs`, `Budget`, `Perms`, `CompletionCond`, `RetryRule` |
| Categorical Architecture [2605.12239] | Architecture \(A=(G,\mathrm{Know},\Phi)\) | protocol wiring, structural certificates, deployment map |
| HarnessBridge [2606.12882] | Bidirectional projections | observation projection \(P_{\mathrm{obs}}\), action projection \(P_{\mathrm{act}}\) |
| Life-Harness [2605.22166] | Four lifecycle layers | environment contract, procedural skill, action realization, trajectory regulation |

Polar’s contract is unusually explicit. Each Gateway exposes **exactly four RPC-style methods**—`prewarm`, `execute`, `reconstruct_trajectory`, and `evaluate`—and all methods are non-blocking on the client side and return a `session` identifier that can be used to poll or to chain the next call [2605.24220]. The trainer sees only `Trajectory { prompt_tokens, response_tokens, logprobs, loss_mask, reward, metadata }`, while all harness internals remain behind the endpoint boundary. Polar also formalizes the resulting rollout as a partially observed MDP
\[
M = (S, A, P, R, \gamma),
\]
with \(S\) as “internal harness state” plus “token-history so far,” \(A\) as the next assistant token ID, and \(R\) computed by the evaluator at POSTRUN [2605.24220].

Natural-Language Agent Harnesses instead specify a single core interface
\[
\mathsf{AgentCall}:(p,F_{\mathrm{in}},\kappa,\Omega_{\mathrm{in}})\longrightarrow (\Delta\Omega,y),
\]
where the contract \(\kappa\) contains `RequiredOutputs`, `Budget`, `Perms`, `CompletionCond`, `RetryRule`, and `OutputLocations` [2603.25723]. Preconditions \(\Phi\) enforce input existence, nonnegative budget, and path permissions; postconditions \(\Psi\) require completion, required outputs, and bounded call count on declared success. Here the contract is explicitly design-by-contract: each step must satisfy \(\Phi \to \Psi\), and violations are surfaced as `MissingInput`, `PermissionDenied`, `BudgetExceeded`, `ContractViolation`, `VerifierMismatch`, `ToolError`, or `Timeout` [2603.25723].

A third formal line replaces API-centric views with algebraic structure. “Harness Engineering as Categorical Architecture” identifies the harness with the Architecture triple
\[
A = (G,\mathrm{Know},\Phi),
\]
where \(G\) is the typed wiring diagram, \(\mathrm{Know}\) is the set of replayable structural certificates, and \(\Phi\) maps stages to concrete models [2605.12239]. Under this view, the contract is not primarily a call interface; it is the preservation law governing protocol wiring, certificates, and model-parametric deployment under compiler functors.

HarnessBridge provides a learnable formulation. It assigns the harness two projections: an observation projection
\[
\widetilde H_t = P_{\mathrm{obs}}(s,q,H_t)
\]
and an action projection
\[
(d_t,\rho_t)=P_{\mathrm{act}}(s,q,H_t,a_t),
\]
where \(d_t \in \{\mathrm{Pass},\mathrm{Reject}\}\) and a rejection produces a trajectory-grounded record \(\rho_t=(\textit{concern},\textit{evidence},\textit{suggestion})\) [2606.12882]. Life-Harness offers another decomposition, treating runtime-interface adaptation as four layers: environment contract, procedural skill, action realization, and trajectory regulation [2605.22166]. Taken together, these papers suggest that the contract can be rendered as an RPC boundary, a design-by-contract schema, an algebraic architecture, or a learnable controller, without losing its core mediating role.

## 3. Runtime protocol, messages, and trajectories

At runtime, the contract typically defines three things: what the harness sends to the model, what the model may return, and how the resulting interaction is recorded as stateful evidence.

Polar centers the contract on **token-faithful proxying**. Its `ModelProxy` sits directly in front of the LLM inference endpoint, detects provider format, normalizes requests to a canonical ChatCompletions shape with `logprobs=true`, forwards upstream, records a `CompletionRecord`, and repackages the HTTP response into the shape the harness expects [2605.24220]. The recorded object contains `prompt_messages`, `response_messages`, `prompt_token_ids`, `response_token_ids`, `response_logprobs`, and `finish_reason`. Polar then reconstructs trajectories from the ordered list of completions. Two invariants are central: for each sampled assistant token \(a_i\), `policy_seen_token_id = a_i exactly`; and tokens that were part of the prompt or harness-generated context inside a new request are recorded but masked out from training loss with `loss_mask=0` [2605.24220].

Guava provides a more conventional agent-loop contract for embodied manipulation. At each timestep, the harness returns an
\[
\mathrm{Observation}_t = \bigl(I^{(t)}_{\mathrm{RGB}}, I^{(t)}_{\mathrm{Depth}}, M^{(t)}_{\mathrm{Mask}}, \mathrm{State}^{(t)}_{\mathrm{Text}}, \mathrm{Tools}\bigr),
\]
the model returns a single JSON tool invocation
\[
\mathrm{Action} = (\mathrm{name}\in\mathsf{ToolName},\ \mathrm{args}:\mathsf{Dict}),
\]
and the harness returns an `ExecutionResult` with `"success" | "failure" | "timeout"` plus an optional diagnostic message [2606.18363]. The control loop is explicitly iterative and ReAct-style: observations are refreshed after every tool execution, failures trigger re-planning, and loop exit is controlled by “Task complete” or “Task failed” tokens or by timeout and max steps. The paper states a **Real-time requirement** of **\(\le 200\) ms average** for `MODEL.step + parse + harness.call_tool` and a **Maximum steps per episode** of typically **100** [2606.18363].

Harness-Bench presents the contract stepwise as
\[
R = \mathrm{Run}(M,H,E,T), \qquad \mathrm{TaskScore}=\mathrm{Eval}(R;J),
\]
where the harness builds a prompt \(P_t\), the model returns \(O_t\), the harness parses it into action \(a_t\), validates constraints and permissions, applies the transition \(S_t = U(S_{t-1},a_t)\), logs \((P_t,O_t,a_t,S_t)\), and invokes recovery when needed [2605.27922]. “Code as Agent Harness” describes the same boundary in code-execution terms: the model emits either code \(c\) or a tool invocation \(a\), and the harness executes it in a sandbox, updates persistent state \(E_0 \to E_1\), and returns observations \(O\) that reflect side effects precisely [2605.18747]. In both cases, the contract is operational only when tracing, parsing, and execution are defined together.

## 4. Invariants, enforcement, and verification

A model–harness contract is substantive only when it specifies what must never be violated. Much of the recent literature is therefore concerned less with expressivity than with enforcement.

In IHR, the harness compiles natural-language harness text into structured contracts, enforces preconditions before `spawn_agent()`, validates postconditions after each child process, snapshots the relevant portion of the environment before each launch, and rolls back on a child crash or contract violation [2603.25723]. Durable artifacts are logged in `state/task_history.jsonl`; a manifest at `artifacts/manifest.json` records promoted outputs; and every child call must itself satisfy the same contract schema, so the contract composes inductively [2603.25723].

ClawVM shifts the enforcement point to memory management. It models state as typed pages with precomputed `Full`, `Compressed`, `Structured`, and `Pointer` representations, assigns each page type a `min_fidelity`, and enforces both a budget constraint
\[
\sum_{p\in\mathcal P}\mathrm{size}(p,\mathrm{f}(p)) \le B
\]
and a minimum-fidelity constraint
\[
\forall p:\ \mathrm{f}(p)\succeq \mathrm{min\_fidelity}(\mathrm{type}(p)).
\]
At lifecycle boundaries—`on_compaction`, `on_flush`, `on_reset`, and `on_prune`—it performs **Structured Staging**, **Deterministic Validation**, and **Scoped Commit**, while logging `RefetchFault`, `DuplicateToolFault`, `PinnedInvariantMiss`, `PostCompactionBootstrapFault`, `SilentRecallFault`, and `FlushMissFault` [2604.10352]. The contract here governs residency and durability rather than tool invocation.

For Physical AI, enforcement is organized as **Projection**, **Isolation**, and **Transfer**. The learned model declares an output region \(R\subseteq \mathbb{R}^n\), an inference budget \(B=(C,f)\), and an operating regime \(\Omega=(S,\theta)\); the middleware then admits a message only if it lies within \(R\), meets a freshness bound, remains schedulable, and is deliverable on the network within the reserved window [2606.09416]. Projection gates the output, Isolation reserves and polices compute and communication, and Transfer activates a verified fallback controller when Projection, Isolation, or the safety signal exceeds threshold. This is one of the clearest cases in which the contract is a deployment artifact rather than a prompt-time convention.

Verification-oriented harnesses extend the same logic to reliability control. Maestro Order’s per-request state requires `calls_used ≤ max_calls`, posterior `confidence ∈ [0,1]`, monotonic `log_odds`, and **fail-closed** behavior: if any `error` appears, `accept=false` [2606.23983]. Meta-Engineering formalizes a contract as \(C=(Pre,Post,Inv,Err)\), partitions failures into **Bug**, **SpecGap**, **Noise**, and **Ambiguity**, and routes outcomes through an adversarial verification workflow and a Four-Way Arbiter [2605.25665]. The common pattern is that the harness does not merely expose tools; it is the place where schema validation, permission checks, rollback, memory durability, verifier replay, and fallback policies become mandatory rather than advisory.

## 5. Domain-specific realizations and adaptations

The same contractual idea appears across several application regimes, but each regime emphasizes a different slice of the boundary.

In scalable RL for agents, Polar makes the integration boundary the LLM API proxy. Any harness that already talks to OpenAI/Anthropic/Google-style endpoints can be bootstrapped without code change by pointing its `MODEL_URL` at the Gateway, while trainers remain completely agnostic to the harness and receive only trajectories plus rewards [2605.24220]. The paper validates this on software-engineering tasks: using simple GRPO, Polar improves **Qwen3.5-4B by 22.6, 4.8, 0.6 and 6.2 points on SWE-Bench Verified with the Codex, Claude Code, Qwen Code and Pi harnesses, respectively**, and reports **up to 5× speedups in trainer-GPU utilization when using prefix-merging versus naively emitting every API call as a separate transition** [2605.24220].

In embodied manipulation, Guava defines the contract around iterative perception–reasoning–action loops, semantic action abstractions, and multimodal observations [2606.18363]. The harness exposes **9 high-level tools**, including `grasp`, `align`, `get_position`, `move`, `rotate`, `close_gripper`, `release`, and `home_pose`; invalid calls immediately return `"failure"` because detailed pre-/post-conditions are encoded in the harness [2606.18363]. The work further reports an end-to-end training pipeline that distills embodied manipulation capabilities into a **4B open-source model using fewer than 2K trajectories collected entirely in simulation** [2606.18363]. Here the contract is a compact action language that separates high-level reasoning from low-level control.

In deterministic environments, Life-Harness keeps the model fixed and evolves the interface. Across seven deterministic environments from \( \tau \)-bench, \( \tau^2 \)-bench, and AgentBench, it improves **116 out of 126 model–environment settings across 18 model backbones, with an average relative improvement of 88.5%**, and harnesses evolved only from Qwen3-4B-Instruct trajectories still improve **92%** of settings on the other 17 models [2605.22166]. Self-Harness pushes this idea further by letting an LLM-based agent improve its own operating harness through Weakness Mining, Harness Proposal, and Proposal Validation; held-out pass rates increase from **40.5% to 61.9%**, **23.8% to 38.1%**, and **42.9% to 57.1%** for MiniMax M2.5, Qwen3.5-35B-A3B, and GLM-5, respectively [2606.09498]. In both cases, the contract becomes an editable object subject to regression tests.

Learnable and compositional contracts extend the same trend. HarnessBridge learns observation and action projection, achieving **33.7%** on Terminal-Bench 2.0 versus a **30.3%** baseline while reducing tokens from **2.31 M** to **1.23 M**, and achieving a comparable **60.2%** on SWE-bench Verified versus **61.6%** baseline while reducing tokens from **1.47 M** to **1.13 M** [2606.12882]. HarnessX treats the harness as a composable typed value updated by symbolic edits, and reports an **average gain of +14.5% (up to +44.0%)** across ALFWorld, GAIA, WebShop, \( \tau^3 \)-Bench, and SWE-bench Verified [2606.14249]. A plausible implication is that the contract is increasingly being treated not as fixed plumbing but as a trainable or evolvable component of the agent system.

## 6. Evaluation, compatibility, and unresolved questions

Recent work increasingly evaluates the contract itself rather than only final task success. Harness-Bench is designed precisely to isolate harness effects while preserving native execution behavior. It contains **106 sandboxed offline tasks** and records **5,194 execution trajectories**; across these runs, it reports recurring failure modes with rates of **36.4%** for **Contract / format**, **24.6%** for **Tool / recovery**, **14.6%** for **Evidence / grounding**, **11.1%** for **Artifact commitment**, and **9.3%** for **State / continuation** [2605.27922]. Its central conclusion is that agent capability should be reported at the **model-harness configuration level** rather than attributed to the base model alone.

Software-engineering work reaches a similar conclusion through richer runtime evidence. AI Harness Engineering defines a trace-based **episode package** containing `ActionTrace`, `ToolTrace`, `ContextTrace`, `VerificationTrace`, `FailureAttributionLog`, `InterventionLog`, `EntropyAudit`, `OutcomeRecord`, `Patch`, and `VerificationReport`, and organizes harness support in a monotone ladder from **H₀** to **H₃** [2605.13357]. The contract is therefore measurable not only by completion but by whether the system can reproduce, attribute, verify, and report its own behavior.

Compatibility questions remain central. The interface-automata line checks compatibility by synchronous product and absence of reachable illegal states [1703.07037]. The AEI line argues that evaluation and training should derive from the contract itself, using cross-session testing of belief commitments, tool commitments, and goal commitments under layer upgrades [2606.04017]. The survey “Code as Agent Harness” identifies open challenges that fit naturally into the same frame: evaluation beyond final task success, verification under incomplete feedback, regression-free harness improvement, consistent shared state across multiple agents, human oversight for safety-critical actions, and extensions to multimodal environments [2605.18747].

Taken together, these results suggest a stable research direction. The model–harness interface contract is becoming the unit at which portability, verifiability, trainer decoupling, runtime safety, and adaptation are specified. What varies across papers is not whether a contract is needed, but which invariants are treated as first-class: token faithfulness and asynchronous rollout in Polar, durable artifacts and rollback in IHR, minimum-fidelity memory in ClawVM, middleware-enforced budgets in Physical AI, certificate replay in categorical architectures, or learned projection in HarnessBridge. The contract has thus emerged as a common abstraction for making agent systems executable, auditable, and evolvable across software, robotics, RL, and embodied settings.

Source: https://www.emergentmind.com/topics/model-harness-interface-contract