[AAASM-4338] 🐛 (core): Add --pre/prerelease to SDK-emitted install hints

[Chisanan232]

Description

Completes AAASM-4332. That ticket added --pre to the README/docs pip install
commands, but three residual install surfaces still emitted the broken bare command.
Because every live PyPI release of agent-assembly is a pre-release (and 0.0.2 is
yanked), any install that does not opt into pre-releases fails with
"No matching distribution found". This PR fixes the remaining surfaces:

• SDK-emitted runtime install hints (agent_assembly/runtime.py,
  agent_assembly/_install.py) — the runtime-not-found error strings now say
  pip install --pre agent-assembly[runtime]. A user following the SDK's own error
  message now gets a command that resolves.
• uv add (README) — uv refuses pre-releases without an opt-in, so
  uv add agent-assembly failed while the SDK is pre-release only. Changed to
  uv add --prerelease=allow agent-assembly with a note mirroring the existing
  --pre note (drop the flag once a stable release exists).
• install_uv docs macro (docs_macros.py) — still emitted a bare
  uv add agent-assembly while install_pip/install_pip_runtime already carried
  --pre; aligned it.

Grep-sweep (pip install agent-assembly / uv add agent-assembly across
agent_assembly/, README.md, docs/, plus a broader uv add sweep):

• Found & changed (4): runtime.py, _install.py, README.md uv line,
  docs_macros.py install_uv.
• Left intentionally: docs/release/RUNBOOK.md pinned historical
  pip install agent-assembly==0.0.1a8.post1 (a pin, resolves fine); all
  pip install --pre … lines already fixed by AAASM-4332; pip install agent-framework
  (different package); pip install -e . / git+https://… (not version-resolved installs).

uv flag verified via uv add --help → --prerelease=allow (possible values:
disallow, allow, if-necessary, explicit, if-necessary-or-explicit).

Type of Change

• 🔧 Bug fix
• 📚 Documentation update

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-4338 (completes AAASM-4332)

Testing

• Manual testing performed
• No new tests required (existing test/unit/test_runtime.py asserts
  "pip install" in <hint>, which still holds; hint-string content is not otherwise
  asserted)

Validation: uv sync; ruff check on changed files clean; pytest -k "install or macro or runtime"
→ 86 passed, 10 skipped.

Checklist

• Code follows project style guidelines
• Self-review completed
• Documentation updated if needed
• All tests passing

🤖 Generated with Claude Code

https://claude.ai/code/session_01R7vqjjo5nrebYNt8WnCNbz

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Chisanan232]

Claude Code review — AAASM-4338

Verdict: changes-needed (one missed code-emitted install hint)

CI: ✅ green — 19/19 checks passed.

Scope (the 4 changed surfaces are all correct):

• runtime.py + _install.py hints → pip install --pre agent-assembly[runtime], [runtime] extra preserved ✅
• README.md uv add → uv add --prerelease=allow agent-assembly + a clear "drop the flag once stable" note ✅
• docs_macros.py install_uv macro → --prerelease=allow (pip macros already carried --pre) ✅

Gap — a third code-emitted install hint was missed:
agent_assembly/core/gateway_resolver.py:185 raises, when aasm is not on PATH:

raise ConfigurationError(
    f"No gateway found at {base_url} and 'aasm' is not on PATH. "
    "Install it with: pip install 'agent-assembly[runtime]'"   # <-- no --pre
)

This is the same runtime-not-found class as the two hints you fixed, and it is user-facing (raised at runtime). A user following it verbatim on a clean env hits "No matching distribution found" while the SDK is pre-release — exactly the failure this ticket exists to close. AC step 3 ("grep-sweep for any other user-facing install instruction... fix all") is not satisfied until this line also gets --pre.

Suggest: pip install --pre 'agent-assembly[runtime]'.

Correctly left untouched (verified by grep-sweep): verification-reports/* (historical), .claude/skills/sdk-only-release/REFERENCE.md bare pip install ... --dry-run (release-runbook resolution check, not a user install instruction), README/docs prose that describes the failing bare command.

Side-effects: clean. Hint-asserting tests green (test/unit/test_runtime.py + test_init_registration.py, 28 passed) — they assert the INSTALL_HINT constant + "pip install" substring, so --pre doesn't break them. [runtime] extra intact; no behavior change beyond hint strings.

Add --pre to gateway_resolver.py:185 and this is approve-ready.

— Claude Code review

[Chisanan232]

Claude Code review — follow-up: gap fixed on-branch

The review found a third code-emitted install hint that the original diff missed: agent_assembly/core/gateway_resolver.py:185 (ConfigurationError raised when the aasm binary isn't on PATH) still suggested a bare pip install 'agent-assembly[runtime]', which fails on a clean pre-release environment — the exact class AAASM-4338 targets.

Fixed + pushed (commit ab2b576): line 185 → pip install --pre 'agent-assembly[runtime]'. Pre-commit hooks (autoflake/black/mypy) passed. Repo-wide grep of agent_assembly/ now shows zero code-emitted pip install agent-assembly hints without --pre — the AC's 'fix all code-emitted install instructions' is now satisfied (runtime.py:40, _install.py:33, gateway_resolver.py:185 all carry --pre; README + install_uv macro carry --prerelease=allow).

Verdict: now approve-ready (CI was already green 19/19; this was a scope-completeness gap, not a CI break). Historical/pinned lines (RUNBOOK, verification-reports, --dry-run runbook) correctly left. — Claude Code review

[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