[AAASM-3017] 🚨 (python-sdk): Clear pre-existing mypy errors

[Chisanan232]

Description

Clears the pre-existing mypy errors carried on master so the local
pre-commit mypy hook passes and stops masking new regressions. The
configured mypy run goes from 326 errors (45 files) — or 319 under the
hook's --ignore-missing-imports — down to 0.

All changes are behaviour-preserving typing fixes only: added/repaired type
annotations (params, returns, dict/list type-args, context managers), explicit
import X as X re-exports, and scoped # type: ignore[code] comments with
short reasons where a real fix is not feasible (mypy method-reassignment
limitation on monkeypatch-style fakes, generated-stub gaps, runtime-imported
framework base classes, deliberate abstract-instantiation tests). No control
flow, values, or public runtime signatures were changed.

Two small infra fixes make the gate actually meaningful and reproducible:

• mypy.ini: skip the generated agent_assembly.proto.* stubs (drift-checked,
  must not be hand-edited).
• .pre-commit-config.yaml: run mypy via uv run mypy with
  pass_filenames: false so the hook resolves the project's real deps
  (pydantic/httpx/frameworks) and uses packages = discovery — making the hook
  byte-for-byte identical to the configured mypy invocation (previously it ran
  in an isolated dep-less venv and crashed on the proto .py/.pyi duplicate).

Fix categories: ~real annotation fixes across 10 source files + ~24 test files;
scoped ignores limited to unavoidable mypy/test-mock limitations, each with a
reason comment.

Type of Change

• 🔧 Bug fix (clears pre-existing type errors / repairs the mypy hook)

Breaking Changes

• No

Related Issues

• Related JIRA ticket: AAASM-3017

Testing

• Unit tests added/updated (annotations only)
• Integration tests added/updated (annotations only)
• Manual testing performed

Verification:

• mypy --ignore-missing-imports: 0 errors (was 319/326).
• pre-commit run mypy --all-files: Passed.
• pytest test/: 443 passed, 9 skipped (unchanged from master).
• ruff check .: 199 (== master baseline; no regression — repo lints via
  black/isort/autoflake, not ruff).

Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic (reasons on every new scoped ignore)
• Documentation updated if needed (n/a)
• All tests passing

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 52.63158% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
agent_assembly/client/gateway.py	44.44%	5 Missing ⚠️
agent_assembly/models/agent.py	0.00%	2 Missing ⚠️
agent_assembly/client/emitter.py	0.00%	1 Missing ⚠️
agent_assembly/types.py	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate failed

Failed conditions
55.6% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[Chisanan232]

🤖 Claude Code — PR review

Ticket: AAASM-3017 — Clear the pre-existing mypy debt on python-sdk master.

CI — 🟡 green except two coverage gates (ignored per policy)

All functional checks pass: CI Success ✅, unit/integration test runs (3.13) ✅, build-native-core ✅, Verify PEP 561 ✅, Test Type Imports ✅, Analyze (python) ✅, docs build ✅.

Two reds, both pure coverage acceptance gates (the SonarQube/coverage class we set aside):

• SonarCloud — Quality Gate failed on the single condition "55.6% Coverage on New Code (≥ 80% required)".
• codecov/patch — "52.63% of diff hit (target 90%)".

Why this is expected and not a real gap: this is a typing-only change (annotations, # type: ignore, two config files). The "new code" is annotations on already-existing, not-individually-executed lines + test-helper signatures — there is no new behaviour to cover, so the coverage-of-changed-lines metric drops mechanically. No functional regression. Not fixing per the coverage/Sonar-ignore rule.

Scope vs. acceptance criteria — ✅ complete

AC	Status	Evidence
mypy clean (0 errors)	✅	319 → 0 (the ticket's "~34" was only the agent_assembly/** subset; the hook also scopes test/, the bulk)
pre-commit mypy hook passes	✅	pre-commit run mypy --all-files → Passed
ruff still clean	✅	199 = master baseline, no regression (repo lints via black/isort/autoflake; no ruff config)
No runtime/behaviour change	✅	pytest 443 passed / 9 skipped — identical to master; annotations/imports/ignores only

20 granular commits; lane clean (agent_assembly/** + test/** + 2 config; no CONTRIBUTING.md, no native, no CI). Mostly real annotation fixes; ~50 scoped # type: ignore[code] with reasons (almost all unavoidable monkeypatch FakeX.method = stub reassignments).

Notes for reviewer (conscious-look items, non-blocking)

1. Two config changes beyond annotations — mypy.ini (ignore_errors for generated proto.*) and .pre-commit-config.yaml (mypy hook switched from mirrors-mypy to a local uv run mypy). These were necessary: the master hook was genuinely broken (isolated dep-less venv resolved pydantic/httpx to Any + crashed on the proto .py/.pyi duplicate). They're typing-config, not GitHub Actions CI, and make pre-commit run mypy byte-identical to the configured run — but they do change how the hook executes, so worth a deliberate look.
2. A few bare # type: ignore remain on overflow-length FakeX.method = stub lines (alongside their reasoned siblings) — a minor deviation from the always-scoped-and-reasoned standard.

Readiness

Ready to merge pending one Pioneer-team approval. Type-clean, behaviour-preserving (tests identical to master), and it un-breaks the local pre-commit mypy hook for everyone. The two reds are coverage-only and expected for a typing PR.

Recorded as a review note; no formal approval submitted.