[AAASM-6154] ⬆️ (examples): Adopt SDK rc.7 via the sdk-versions.yaml source of truth

[Chisanan232]

DRAFT — release-deferred, not blocked on engineering and not blocked on this diff.
The SDK defect that used to block this (AAASM-6155) is fixed and merged on python-sdk
main as 0d9d83a02e84d41c369fb8627677cfdf0d13ea59. What remains is purely that no published
agent-assembly version carries that commit yet — PyPI latest is still 0.0.1rc7, uploaded five
days before the fix merged. The next package release will happen together with the normal product
release when the features currently in development are ready. That is a deliberate release
boundary, so this PR waits rather than being forced, closed, or relocked.

Scope correction: this is now the Python half only

When this PR was opened it carried both ecosystems. It no longer does. #576 merged on
2026-09-22 (merge commit 5ea1671d17a61c4b48cd6538537c746ec2cdd7f9), so node.version is already
0.0.1-rc.7 on main and the Node half of the rc.7 adoption is done and shipped. After merging
main back in, every node/ path dropped out of this diff.

	at open	now
files changed	79 across 31 directories	58
metadata/sdk-versions.yaml	two lines (Python and Node)	one line, Python 0.0.1rc6 → 0.0.1rc7
manifests + lockfiles	25 + 25	18 + 18, all Python
node/ paths in the diff	present	zero

The remaining 58: the source of truth, 18 pyproject.toml, 18 uv.lock, 19 README.md, one
Dockerfile, one verify-live.yml pin.

Go stays at v0.0.1-rc.6 deliberately — go-sdk has no v0.0.1-rc.7 tag and the module proxy
lists nothing past rc.6, which is also why Dependabot raised zero go-sdk PRs. Bumping it would break
the Go examples.

Current CI state and what it means

On head ea25972: 45 check runs — 28 pass, 16 fail, 1 pre-existing skip
(live: live-core-enforcement (real gateway)).

The install failure this PR used to have is gone. Every Python job now gets past dependency
resolution and reaches the smoke-test step, so the stale-lockfile problem recorded earlier is fixed
and the branch is MERGEABLE (mergeStateStatus: BLOCKED reflects required review only).

The 16 failures were not assumed to share a cause — all 16 logs were pulled and partitioned. Each
reports 1 failed, N passed, with 85 other tests passing, and zero of the 16 contain the
stale-lockfile error. All 16 fail on exactly one assertion:

FAILED tests/test_smoke.py::test_init_assembly_sdk_only_requires_no_gateway
agent_assembly.exceptions.ConfigurationError: Failed to initialize assembly runtime: gateway gRPC endpoint is unreachable for registration
.venv/lib/python3.12/site-packages/agent_assembly/core/assembly.py:327: ConfigurationError

That is AAASM-6155, reached after a successful install, in shipped SDK code. Nothing a relock can
move.

The failure surface is exactly predictable, which is why this is a product defect rather than
example drift. Two independent greps select the same 16 of 18 directories and exclude the same 2:

Signal	Matches
directories containing test_init_assembly_sdk_only_requires_no_gateway	16 of 18
directories whose src/main.py calls init_assembly	the same 16 of 18
scenarios/approval-gates/python and scenarios/policy-enforcement/python	0 of 2

Those two scenario examples pass at rc.7 on this very PR. Their only mention of init_assembly is
inside a module docstring describing production usage; no executed line calls it, so they never reach
the changed registration path. They would therefore work at rc.7 today, but they cannot be
shipped ahead of the fix: python.version is a single global pin with no per-directory override, so
regenerating moves all 18 or none.

Correction to an earlier claim in this description

A previous revision said the defect was Linux-only in effect, because on macOS
connect_runtime_client() returns None and registration takes an early warn-and-return path. That
is wrong and has been retracted. Re-verified on macOS from two fresh virtual environments installed
straight from PyPI, same interpreter, nothing listening on the gateway port: native_core_available
is True and connect_runtime_client(...) returns a RuntimeClient in both, rc.6 initialises
fine, and rc.7 raises the same ConfigurationError. The documented offline quick-start exits 0 on
rc.6 and 1 on rc.7 on this host too.

So macOS is a valid verification host for this defect, and the user-visible breakage is broader than
first recorded — it is the shipped program failing, not only a smoke test. Full evidence, including
the resolver trap that produced the original wrong reading, is on AAASM-6155.

Nothing was weakened to get green. The failing assertion's own name states the contract it
protects, and every example README advertises the offline demo as needing no gateway. No test was
edited, skipped, xfailed or deleted; no example's governance posture was changed; the SDK pin was not
reverted; no required check was relaxed. This PR is parked as a draft instead.

Why this is one PR rather than 25

Dependabot opened 25 PRs for this bump — 18 Python, 7 Node, one per example directory. None can be
merged on its own, for two independently verified reasons:

1. The pin is a single repo-wide source of truth. metadata/sdk-versions.yaml declares it and the
   generator rewrites every manifest, README block, Dockerfile and workflow pin to match. That script,
   by its own docstring, never bumps versions; it aligns drift. So a PR bumping one manifest is
   drift, and the metadata drift job reverts it. Verified on all 18: each one's drift job rewrites
   agent-assembly==0.0.1rc7 straight back to 0.0.1rc6.
2. Dependabot bumped manifests without relocking. The examples job runs
   uv sync --extra dev --locked --no-build, which resolves fine and then fails with
   The lockfile at uv.lock needs to be updated, but --locked was provided.

Neither is fixable inside a single Dependabot PR, because bumping the source of truth in any one PR
necessarily aligns all manifests in that same PR. This PR therefore follows the procedure the
source-of-truth file's own header prescribes: edit this file only on a new SDK release, then run the
generator.

The three commits

Commit	Parents	Concern
2c3fbcd	1	the SoT bump, the generator output, and the relocks
fcf23c2	1	keeps crewai-research-crew's mcp and json-repair patched
ea25972	2	merges origin/main in — a true merge commit, no squash, no rebase

ea25972 resolved the only two conflicting files, both under node/vercel-ai, both the same single
fact: main had already moved ai from ^7.0.101 to ^7.0.107. Main's side was taken verbatim, so
node/vercel-ai is byte-identical to main and drops out of the diff entirely.

fcf23c2 predates #612 landing. Now that #612 is merged, main itself carries the patched floors, and
this branch matches it: mcp 1.28.1 and json-repair 0.60.1, identical to main. The commit is kept
as history rather than rewritten; it is no longer load-bearing.

How to verify

Text-only evidence, per workstation data-handling policy — no screenshots attached.

Published-version check. The moved version is really published, not merely proposed:

Ecosystem	Version	Evidence
PyPI agent-assembly	0.0.1rc7	present, 13 files, none yanked
npm @agent-assembly/sdk	0.0.1-rc.7	already on main via #576
Go go-sdk	rc.7 absent	no git tag; module proxy stops at rc.6

Note what this table does and does not establish: rc.7 exists, so the bump target is real — the old
reading that these PRs targeted a nonexistent version was wrong. What does not yet exist is a
published version newer than rc.7 carrying 0d9d83a0.

Every gate CI runs, re-run locally on the current head:

Gate	Result
generate_example_metadata.py	"No changes — every example is already in sync with the SoT."
extract_snippets.py	"Extracted 26 snippet(s) across 3 SDK(s). No changes"
drift diff	PASS
generator audit in check mode	"every audited surface matches the SoT", exit 0
python -m unittest scripts.test_generate_example_metadata	39 tests OK
check_pnpm_overrides_parity.py	OK — 3 directories, 0 mismatches
uv lock --check across all 18 Python directories	0 mismatches

Anti-vacuity checks, so a relock that quietly did nothing would be caught:

• every one of the 18 uv.lock files carries 0.0.1rc7 — 18 of 18
• exactly 18 uv.lock and 18 pyproject.toml files changed, matching each other
• AAASM-6153 floors asserted present, not merely unchanged: mcp 1.28.1, json-repair 0.60.1

One pre-existing condition, deliberately left alone: python/crewai-research-crew resolves
build==1.5.1, which is yanked. It is byte-identical to what main already carries, the yank reason
is a breaking-change concern rather than a vulnerability, and it is unrelated to this bump — so it is
reported, not changed.

The exact condition that unblocks this

A published PyPI agent-assembly newer than 0.0.1rc7 whose wheel contains python-sdk commit
0d9d83a02e84d41c369fb8627677cfdf0d13ea59. No version number is being reserved or implied here, and
no release is being requested.

When it exists, the work is: set python.version in metadata/sdk-versions.yaml to it, re-run the
generator, relock the 18 Python directories. node.version needs no change. The 16 jobs above are
then expected green on the merits rather than hoped green, because AAASM-6156 is already on main,
so the public-seam mock is in place and the unpack failure that used to sit behind this one is gone.

Consequence for the 25 Dependabot PRs

The 7 Node ones are superseded — #576 landed their content. The 18 Python ones (571, 572, 574, 575,
577, 578, 580, 582, 584, 585, 587, 588, 590, 592, 593, 594, 595, 597) stay open. Each was re-read
individually rather than assumed to share a cause, and all 18 agree exactly:

Observation	Count
failing jobs inside the verify workflow	1 of 1 in each
that failure is the --locked stale-lockfile error	18 of 18
any other, unrelated failure present	0 of 18
drift job rewrites 0.0.1rc7 back to 0.0.1rc6	18 of 18

Each touches a single pyproject.toml, so there is no shared-lockfile family and no merge
serialisation to arrange.

They are deliberately not relocked — that could not reach green, it would only trade the lockfile
error for the AAASM-6155 assertion failure on 16 of them. They are deliberately not closed —
nothing about them is wrong, and Dependabot retires them automatically once adoption lands. They are
deliberately not merged — none can be genuinely validated today.

The right label for their state is release-deferred by an intentional product decision, not
unfixed engineering.

Related issues

refs AAASM-6154, AAASM-6153, AAASM-6155, AAASM-6156

[Chisanan232]

Held: rc.7 adoption is blocked by a real SDK behaviour change (AAASM-6155)

The 16 failing Verify Python Examples jobs on this PR are not billing refusals and not a flake. Every failing job ran on a real runner with 8–9 executed steps and failed at Run smoke tests on the same assertion:

FAILED tests/test_smoke.py::test_init_assembly_sdk_only_requires_no_gateway
agent_assembly.exceptions.ConfigurationError: Failed to initialize assembly runtime:
gateway gRPC endpoint is unreachable for registration

Baseline

Verify Python Examples is green on main at rc.6 (5 most recent runs on main: all success). So the failure is introduced by the rc.7 adoption in 2c3fbcd, not pre-existing.

Root cause (proved, not inferred)

_register_agent_with_gateway in agent_assembly/core/assembly.py decides whether a register failure propagates. rc.6 compared enforcement_mode for equality against the enforce literal; rc.7 calls _local_posture_is_enforce(...), which returns true when enforcement_mode is None or equals enforce. The examples call init_assembly with no enforcement_mode, so None used to fail open and now fails closed. That helper is deliberate and documented under AAASM-4130.

The unintended part is its interaction with mode="sdk-only": that function never receives mode, so the one mode whose purpose is running without a gateway is now the mode that hard-fails without one.

Controlled comparison in python:3.12-slim, nothing listening on the gateway port, only the SDK version differing:

SDK	native_core_available	connect_runtime_client	result
0.0.1rc6	True	OBJECT	warns, then init_assembly: OK network_mode=sdk-only
0.0.1rc7	True	OBJECT	ConfigurationError as above

This is not merely a stale test mock

Each example's src/main.py calls init_assembly with mode="sdk-only" and no enforcement_mode, and each README states the offline demo "needs no gateway". On Linux that documented command stops working under rc.7.

It still passes on macOS, because there connect_runtime_client returns None and registration takes its early warn-and-return path. A macOS-only check reports this as fine, which is why the Linux container comparison above was run.

There is a second, independent rc.7 change in the same try block: _register_adapters now returns a 2-tuple rather than a list, which these tests patch. That is why a local macOS run fails with not enough values to unpack (expected 2, got 0) while CI fails with the unreachable-gateway message — one upgrade, two distinct breakages.

Why nothing here was forced green

The failing assertion encodes a real product contract, and the only alternative fix edits 16 examples' runtime governance posture from the default to a dry-run mode. Neither belongs in a dependency bump, so this PR is held rather than adjusted to pass. No test was edited, skipped or deleted, and no gate was weakened.

What is unaffected

PR #612 (the crewai-research-crew security relock for the mcp and json-repair advisories) does not touch the SDK version and is green at 28/28. It stands on its own and does not depend on this PR.

Tracking: AAASM-6155 (High), with the two candidate resolutions written up there. Text-only evidence, per this workstation's data-handling policy.

[Chisanan232]

Update: AAASM-6155 is fixed; two things still gate this pull request

The SDK defect this was held on has a fix in review: ai-agent-assembly/python-sdk#343. _register_agent_with_gateway now receives mode, so a failed register under mode="sdk-only" with no enforcement_mode warns and init continues, while auto / proxy / ebpf and any explicit enforcement_mode="enforce" keep failing closed exactly as before. One cell of the mode × enforcement matrix changes.

Verified in python:3.12-slim on the released rc.7 wheel with nothing listening on the gateway port, preconditions printed and identical in every run:

Run	SDK	mode	enforcement_mode	Result
A	rc.7 as released	sdk-only	unset	raised ConfigurationError, gateway unreachable for registration
B	rc.7 + fix	sdk-only	unset	OK network_mode=sdk-only registered=False
C	rc.7 + fix	auto	unset	still raised
D	rc.7 + fix	sdk-only	enforce	still raised
E	rc.7 + fix	proxy	unset	still raised

Remaining gate 1 — a second, examples-side change is needed here

The SDK fix alone does not make these 16 jobs pass. Their smoke tests patch the private _register_adapters with return_value=[], and rc.7 changed that helper to return a 2-tuple. Past the registration fix they fail with not enough values to unpack (expected 2, got 0). Proven in the same container against patched rc.7:

Mock installed	Result
return_value=[] — current	raised ConfigurationError, not enough values to unpack
return_value=([], "absent")	PASS agent_id=test-crew network_mode=sdk-only

Tracked as AAASM-6156. It is a one-line correction per directory that leaves every assertion, every init_assembly argument and every example's governance posture unchanged, and it belongs on this branch rather than main — the current shape is correct for the rc.6 that main pins.

Remaining gate 2 — this branch cannot be revalidated until rc.8 is published

The lockfile here resolves agent-assembly to the published 0.0.1rc7 on PyPI. There is no way to exercise the AAASM-6155 fix through this pull request until a release containing it exists. Publishing a package to a registry is a deliberate decision for the repository owner, not something I do unattended.

So: staying draft, not merged. The two scenario examples that pass today are untouched and remain the controls. No assertion has been weakened and the lockfile discipline has not been bypassed to make anything green.

External evidence is text only, per this workstation's data-handling policy.

[Chisanan232]

Correction to my earlier comment on this branch

My earlier comment said the stale example mock fix "belongs on this branch rather than main", on the reasoning that the current mock shape is correct for the rc.6 that main pins. That was wrong, and I proved it wrong rather than leaving it standing.

What I actually measured

Six runs in python:3.12-slim, each printing its own preconditions (native_core_available=True, connect_runtime_client=OBJECT) so only the SDK version and the installed mock differ:

SDK	Mock installed	Result
rc.6	_register_adapters returns [] — what the 16 directories did	PASS, with the AAASM-4547 unregistered warning
rc.6	_register_adapters returns ([], AUDIT_SINK_ABSENT)	RAISED ModuleNotFoundError: No module named 'agent_assembly.core.audit_sink'
rc.6	AdapterRegistry.get_available_adapters_by_priority returns []	PASS, with the same warning
rc.7 as released	_register_adapters returns []	RAISED ConfigurationError: ... gateway gRPC endpoint is unreachable for registration
rc.7 as released	_register_adapters returns ([], AUDIT_SINK_ABSENT)	RAISED ConfigurationError (same)
rc.7 as released	AdapterRegistry.get_available_adapters_by_priority returns []	RAISED ConfigurationError (same)

Row 2 is what breaks the old plan: the rc.7 2-tuple shape cannot even be named on main, because agent_assembly.core.audit_sink does not exist in rc.6. So the "correct the shape on this branch" plan would have produced a change that could not be validated anywhere until an rc.8 existed.

Row 3 is the way out: patching the public AdapterRegistry.get_available_adapters_by_priority seam instead is green on rc.6 today. The real defect was never the tuple shape — it was that 16 examples were coupled to a private seam at all, so a helper with no contract could move and take all of them down at once.

Where it went instead

#614, on main, all 30 checks green. It moves the 16 examples onto the public seam, drops the _start_network_layer patch (under mode="sdk-only" the real function already returns byte-for-byte what the mock returned), preserves every assertion, and ships a drift guard so the next private-seam patch fails the build when it is introduced rather than when an SDK bump lands.

What that leaves for this branch

Once #614 is on main and rebased in, this pull request reduces to:

1. bump python.version in metadata/sdk-versions.yaml;
2. regenerate the per-directory metadata from that source of truth;
3. uv lock relock.

It still cannot be revalidated until an SDK release contains the AAASM-6155 fix (python-sdk#343) — the bottom three rows above show released rc.7 raises regardless of which mock is installed. This stays draft until then.

External evidence is text only, per this workstation's data-handling policy.

[Chisanan232]

Classification: BLOCKED_BY_UNRELEASED_UPSTREAM_VERSION

This PR stays draft and unmerged. No release will be created to unblock it — a Python SDK release is a separate product decision and is explicitly out of scope for the dependency/security sweep. Recording the exact blocker here so the state is unambiguous.

What released version this resolves to

agent-assembly==0.0.1rc7, uploaded to PyPI at 2026-09-17T02:41:54Z. That is the newest published version of the package; there is nothing newer to move to.

Why that released version cannot contain the fix it needs

The examples need AAASM-6155 — an sdk-only registration failure must not be fatal. That fix merged to python-sdk main as 0d9d83a (parents=2) at 2026-09-22T14:18:11Z, five days after rc.7 was uploaded. A published artifact cannot retroactively acquire a later commit.

Verified rather than assumed, in python:3.12-slim:

SDK under test	hasattr(_core, "_register_failure_is_fatal")
pip install agent-assembly==0.0.1rc7	False
same, after swapping in assembly.py from python-sdk main	True

The swap is a fair proxy because git diff v0.0.1-rc.7..main -- agent_assembly/core/assembly.py is 54 lines and matches that commit's own stat, so the file is the fix. The swap asserted sha256(before) != sha256(new) before copying and re-verified after.

What actually happens on released rc.7

Three mock shapes, one variable at a time:

SDK	Mock installed	Result
rc.7 as released	_register_adapters → []	ConfigurationError: ... gateway gRPC endpoint is unreachable for registration
rc.7 as released	_register_adapters → ([], AUDIT_SINK_ABSENT)	same ConfigurationError
rc.7 as released	AdapterRegistry.get_available_adapters_by_priority → []	same ConfigurationError
rc.7 + the merged fix	AdapterRegistry.get_available_adapters_by_priority → []	PASS registered=False

Row 3 is the important one: the seam correction from #614, now on main as 4b72549, does not rescue released rc.7. rc.7 raises before any mock shape is reached.

Why this cannot be split into "the two that work"

metadata/sdk-versions.yaml is the single source of truth, and its python.version is one global field. The generator rewrites every affected manifest from it, and the drift gate rejects any hand-edit of a generated pin — which is exactly what each individual Dependabot PR is.

Exactly 18 directories pin agent-assembly== (16 under python/, 2 scenario projects), and all 18 are governed by that single field. So:

• the 16 framework examples call init_assembly(mode="sdk-only") and therefore hit AAASM-6155 on released rc.7;
• the 2 scenario projects only import agent_assembly.exceptions.ToolExecutionBlockedError, never call init_assembly, and are unaffected by AAASM-6155;
• but the pin is global, so the 2 unaffected projects cannot adopt rc.7 without dragging the 16 broken ones with them.

Python rc.7 adoption here is all-or-nothing by design. That is why the 18 individual bot PRs each show two reds — metadata drift (hand-edited generated pin) and their own example job failing on error: The lockfile at uv.lock needs to be updated, but --locked was provided — and why repairing them one by one is not available.

What would make revalidation possible

The next Python SDK version that is naturally published from python-sdk main at or after 0d9d83a, whenever a release is independently decided on its own merits. That version is deliberately not being created now, and no version number is being reserved or implied here.

When such a release exists, the sequence is: bump python.version in metadata/sdk-versions.yaml to it, re-run python scripts/generate_example_metadata.py, relock, and revalidate. node.version stays at 0.0.1-rc.7 and go.version at v0.0.1-rc.6; neither is affected.

Meanwhile

• The 18 Dependabot PRs are left open and untouched as the bot's own queue. They are redundant with this PR rather than independently mergeable, and Dependabot closes them automatically once this adoption lands. Nothing is being closed merely to reduce the open-PR count.
• AAASM-6156 is closed independently: [AAASM-6156] ✅ (examples): Patch adapter discovery instead of a private SDK helper #614 merged to main as 4b72549, moving all 16 framework examples onto the public AdapterRegistry.get_available_adapters_by_priority seam and adding an AST gate so the private-seam coupling cannot return. It touched no lockfile and no version pin, so it carries no release implication.

External evidence is text only, per this workstation's data-handling policy.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud