gateway-module-extraction

Skill: Extracting Modules from gateway/run.py

When to Use

When splitting GatewayRunner methods into separate modules under gateway/ and the extracted class needs to read/write the runner's many attributes (adapters, session_store, hooks, task_manager, _running_agents, etc.).

Three Things That Bite

1. stdlib name collision

Dispatcher clashes with asyncio.Dispatcher (or any stdlib symbol you forgot). Symptom: mysterious AttributeError or TypeError at import time, not at use time. Fix: prefix with the domain — MessageDispatcher, SessionLifecycle, CronRunner. Always grep stdlib before naming:

python3 -c "import asyncio; print(hasattr(asyncio, 'Dispatcher'))"

2. circular reference via runner

Extracted class needs self.adapters, self._running_agents_ts, etc. Two ways to give it access:

a) Pass runner in __init__ and store as self.runner:

class SentinelGuard:
    def __init__(self, runner):
        self.runner = runner  # NOT self.run_agent
    def is_sentinel(self, session_key):
        return self.runner._running_agents.get(session_key) is _SENTINEL

b) Pass the specific attributes the class needs (cleaner but verbose).

For {{AGENT_NAME}} gateway, use (a) — 51 attribute references would make (b) painful.

3. Mock fixture sync order

After extracting modules, tests fail because mock_gateway_runner (built via object.__new__(GatewayRunner)) doesn't have the new attributes. Order matters:

1. First: replace the original method body with self._new_module.method() delegate
2. Then: update mock fixture to set the new attributes
3. Then: run tests

Doing fixture first leaves the real runner working but the mock broken. Doing tests first leaves everything broken. Delegate-first means the wiring is provably correct before any test changes.

• references/pyc-staleness-pitfall.md — .pyc staleness masking extraction errors (stale bytecode loads instead of modified source). Always clear __pycache__ after modifying multiple Python files during extraction.