tracer-cloud--opensre/gateway/AGENTS.md

Gateway Package Guidance

Gateway tests live in gateway/tests/, not the repo-wide tests/ tree.

This package is a bounded messaging surface with its own app entrypoint, platform adapters, storage, security, sinks, and process runner. Keeping its tests package-local makes gateway refactors easier to review and keeps the gateway implementation and regressions together. New gateway unit tests should be added under gateway/tests/.

Pytest discovers these tests through pytest.ini; scoped CI maps changes under gateway/ to gateway/tests/ through .github/ci/test_scope_rules.py.

Layout

• manager.py — process composition root: builds the turn handler, starts the Telegram worker, owns signals and shutdown.
• turn_handler.py — transport-agnostic turn callback: GatewayTurnHandler (a (text, session, sink, logger) -> None callable) builds a fresh HeadlessAgent per turn and calls agent.dispatch(text).
• telegram_gateway.py — wires the handler into the Telegram polling worker.
• storage/session/resolver.py — per-chat session binding; delegates create / resolve / rotate to SessionManager.

Gateway turn dispatch

• No persistent gateway Agent instance. Each inbound message gets a per-chat Session from SessionResolver and is handled by the shared headless dispatch path (core.agent_harness.turns.headless_dispatch).
• The turn handler callback signature is exactly four arguments: text, session, sink, and logger. Do not reintroduce chat_id into this contract; the sink owns chat transport details.
• Resolve action tools from the live per-chat Session each turn via DefaultToolProvider(session, console) — same as the interactive shell. Do not precompute tools at process start; chat sessions carry their own integration context after SessionResolver.resolve.
• Per-chat session lifecycle (create / resolve / rotate / restore) is owned by SessionResolver → SessionManager, not by GatewayManager.

Testing

Gateway E2E regression tests should drive a normalized polled Telegram message into handle_polled_inbound_telegram_message(...) and let it invoke the turn handler. Do not test this path by swapping in fake LLM clients when validating dispatch wiring; prefer explicit registered commands such as /status when the test only needs to validate providers and callback plumbing.