[AAASM-4710] 📝 (python-sdk): README CLI docs + remove dead async callbacks

[Chisanan232]

Description

Three small, hand-verified fixes for AAASM-4710:

1. README — document aasm --version. The version check was only documented in docs/guides/container-base-image.md. Added a short "confirm the aasm CLI is on your PATH" snippet to the Installation section (aasm --version → aasm 0.0.1rc5).
2. README — accuracy caveat in Error Handling. The existing example correctly says an empty gateway_url triggers localhost auto-discovery and raises GatewayError after ~5s. Added a caveat noting the sub-case: when aasm is not on PATH, discovery can't auto-start a gateway and raises ConfigurationError immediately instead (see gateway_resolver._auto_start_gateway).
3. LangChain callback handler — remove dead async callbacks + fix false async coverage. The aon_tool_start/aon_tool_end/aon_llm_start/aon_llm_end methods were dead: LangChain selects sync-vs-async dispatch by testing inspect.iscoroutinefunction on the looked-up on_* name, and this handler defines every on_* sync, so the async manager runs the sync methods in an executor — the aon_* variants were never reached. The async test called those dead methods directly, giving false async coverage. Removed the unused methods (and the now-unused import inspect) and rewrote the async test to drive the real async manager via ahandle_event, proving governance deny/enforce still blocks across the async dispatch path.

Type of Change

• ♻️ Refactoring (dead-code removal + test fidelity)
• 📚 Documentation update

Breaking Changes

• No

The removed aon_* methods were never reached by LangChain dispatch and had no references outside the async test (confirmed by repo-wide grep), so removing them changes no runtime behavior.

Related Issues

• Related JIRA ticket: AAASM-4710

Closes AAASM-4710

Testing

• Unit tests added/updated
• Manual testing performed

Ran the impacted test only (not the full suite):

• .venv/bin/python -m pytest test/unit/adapters/langchain/test_callback_handler_async.py -v → 13 passed (now genuinely exercises the async callback manager via ahandle_event).
• .venv/bin/python -c "import agent_assembly.adapters.langchain.callback_handler" → import OK (no breakage after removal).
• .venv/bin/ruff check + ruff format --check on both changed files → clean.
• .venv/bin/mypy agent_assembly/adapters/langchain/callback_handler.py → Success, no issues.

Checklist

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

[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

[Chisanan232]

Review (AAASM-4710) — READY.

• Scope: all three items — aasm --version documented in the README; the aasm-not-on-PATH -> ConfigurationError sub-case caveated (confirmed in gateway_resolver.py); the dead aon_* async callbacks removed and the async test rewritten to drive LangChain's real ahandle_event manager.
• Side effects: the aon_* methods had no callers outside the (misleading) test — removal is safe. This branch was rebased onto the latest master (a test-refactor wave had touched the same async test file); the one conflict was resolved to the ahandle_event-driven version, since master's side still referenced the now-removed aon_* methods. 13 impacted tests pass; mypy/ruff/pre-commit green.

---

CI: all required checks green. Front-end: no FE/dashboard code touched — Playwright validation N/A. Merge state: BLOCKED only on the required ≥1 Pioneer approval (branch protection), not on any failure.

— Reviewed by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!