fix(analyse): select the chained ABCI skill deterministically + release 0.21.28

[OjusWiZard]

Proposed changes

autonomy analyse service picked the chained ABCI skill non-deterministically.

_get_chained_abci_skill iterated AgentConfig.skills — a Set[PublicId] — and returned the first non-abstract skill declaring abstract_round_abci as a dependency. With more than one qualifying skill the winner was decided by set iteration order, so the command's answer changed with PYTHONHASHSEED.

On valory-xyz/trader both trader_abci and funds_manager qualify (each is_abstract: false, each declaring abstract_round_abci):

PYTHONHASHSEED	selected skill
0, 1	funds_manager
2, 3	trader_abci

That coin flip is why trader carries analyse-service commented out of its common_checks workflow with the note that it "is checking funds manager skill which is not an ABCI skill" — a description of one face of the coin rather than a stable property.

The fix

Collect every qualifying candidate, then pick the one nothing else in the agent declares as a dependency — the root of the dependency DAG, which is what "chained app" means. trader_abci lists funds_manager among its skills, so it is the unique root. Where there is no single root, the command raises a named ClickException listing the candidates instead of silently picking one.

The code this replaces documented the assumption it was breaking:

This statement makes an assumption skills other than the chained/main abci are defined as abstract

Three details are load-bearing, each covered by a test:

• Edges come from every skill the agent overrides, not just the candidates. Abstract skills are filtered out before candidacy, so reading edges off candidates alone misses composition through an abstract intermediate: for A → B → C with B abstract, the B → C edge is invisible, A and C both look like roots, and a chain with one obvious root is rejected as ambiguous.
• Candidates are keyed on the versioned identifier, so two versions of one skill stay two candidates and get reported rather than one silently overwriting the other.
• The edge comparison is version-insensitive, so a dependency pinned to a different version than the agent's skill list still registers as the same skill. A version-sensitive comparison would see no edge and abort as ambiguous.

The pattern in all three: a hole in the edge model turns into a spurious hard error on a valid config, which is a worse failure than the coin flip being fixed.

Why not just sorted()

Sorting alone is deterministic but wrong: in trader it would consistently select funds_manager, which is worse than the coin flip because it looks stable. The regression test's fixtures are therefore named aaa_dependency / zzz_chained, so the dependency sorts before the root exactly as funds_manager does before trader_abci. Stripping the dependency logic fails the test with assert 'aaa_dependency' == 'zzz_chained'; please keep that naming.

Note for reviewers: the single-candidate fast path is load-bearing

if len(candidates) > 1: guards the DAG logic, and the lone-candidate case returns directly. That looks redundant — a single candidate cannot depend on itself — but it is not, because the dependency set now includes edges from non-candidate skills. Collapsing the two paths would mean a single candidate that any abstract skill happens to declare resolves to zero roots and raises: a spurious hard failure on the most common configuration there is. Please don't merge the branches.

Release

Also cuts 0.21.28, bumping the version across all eight pin sites. The open-aea-test-autonomy pin in transaction_settlement_abci/skill.yaml cascades through autonomy packages lock into eight dependent package hashes and on into docs/package_list.md. abstract_round_abci does not depend on the bumped package, so ABSTRACT_ROUND_ABCI_SKILL_WITH_HASH in autonomy/constants.py stays in sync without edit.

The two poetry.lock version fields are updated in place rather than regenerated: poetry lock --regenerate rewrites ~2200 lines of unrelated dependency metadata and still records the stale plugin version, because Poetry reads installed dist-info for develop path dependencies. poetry check --lock passes.

Fixes

Unblocks analyse-service in trader and optimus (separate downstream PRs). optimus's basius service, previously blocked by this bug, now reports its real findings.

Types of changes

• Non-breaking fix (non-breaking change which fixes an issue)
• Breaking fix (breaking change which fixes an issue)
• Non-breaking feature (non-breaking change which adds functionality)
• Breaking feature (breaking change which adds functionality)
• Refactor (non-breaking change which changes implementation)
• Messy (mixture of the above - requires explanation!)

One operator-visible behaviour change, documented in docs/upgrading.md: an agent with several non-abstract skills depending on abstract_round_abci and no dependency relating them now fails with a named error instead of returning an arbitrary skill. That is the intended trade, but it can surface as a new error on a service that previously "passed" by luck.

Checklist

• I have read the CONTRIBUTING doc
• I am making a pull request against the main branch (left side). Also you should start your branch off our main.
• Lint and unit tests pass locally with my changes — with two pre-existing exceptions, see below
• I have added tests that prove my fix is effective or that my feature works
• I have locally run AI agents that could be impacted and they do not present failures derived from my changes
• Public-facing documentation has been updated with the changes affected by this PR.
• Any backwards-incompatible/breaking change has been clearly documented in the upgrading document.

Further comments

Verification. Deterministic across six PYTHONHASHSEED values against trader's real packages, and across all four services in trader and optimus. Six new tests; all five behaviours above are mutation-verified — each dies without at least one test. mypy, pylint (10.00/10), flake8, black, isort, vulture, check-hash, check-packages, check-dependencies, check-doc-links-hashes, check-third-party-hashes, check-abci-docstrings, check-abciapp-specs, check-handlers, check-dialogues, liccheck, bandit and poetry check --lock all pass. Full framework unit suite: 633 passed.

Two pre-existing local failures, neither caused by this PR:

• tox -e darglint exits 129 on six files in autonomy/, plugins/ and packages/valory/ that this PR does not touch. darglint 1.8.1 breaks on Python 3.14, which is why main_workflow.yml:109 pins that job to 3.13 with the comment "use 3.14 after darglint2 issue chore(deps-dev): bump tox from 3.23.1 to 3.24.3 #44 is fixed". The two changed files pass darglint cleanly.
• The docker-image tests (test_build_image.py, test_images/) fail locally without the images built; they are unrelated to this change.

Unrelated loose end spotted while working, not addressed here: tox -e check-api-docs regenerates an untracked docs/api/data/, which f21680f99 ("skip data packages from generate api documentation script") deliberately deleted. The generator still emits it and the check does not catch it, so the fix looks incomplete.

[DIvyaNautiyal07]

All five previous review findings addressed cleanly in ec2926ef. Bonus mutation test pins the split-branches invariant. LGTM.