ADR · ADR-0006 · v1.0.0

TEK Agent Bridge — Transport Layer

accepted v1.0.0 Authors: david.sorf, claude-sonnet-4-6 Created: 2026-04-10 Updated: 2026-04-10

tek bridge amqp rabbitmq transport multi-repo ep21

TEK Agent Bridge používá RabbitMQ (AMQP) jako primary transport s TCP fallback: downstream projekty posílají task events do master controlleru v podpora21, master posílá commands zpět. Bridge je součástí TEK distribuce.

Related docs:

Kontext

TEK v1.3.0 běží v 9 repozitářích EP21 ekosystému v izolaci — bez cross-repo viditelnosti nebo centrálního řízení. Cílem je Master TEK Controller v podpora21 který:

Přijímá živý stream events ze všech downstream projektů
Udržuje repliku každé fronty v PostgreSQL (task mirror)
Může posílat commands dolů (set_status, add_note)

Uvažované transporty:

A) RabbitMQ (AMQP) — persistent buffering, management UI, škáluje

B) Čistý TCP/Unix socket — bez buffering, přímá síťová dostupnost nutná

C) HTTP polling — jednoduché, ale latence a overhead

Rozhodnutí

✓ Chosen: A — RabbitMQ (AMQP) s TCP fallback pro dev

RabbitMQ zvolen protože:

1. Persistent buffering: zprávy přežijí výpadek bridge i master consumeru (TTL 7 dní)

2. RabbitMQ Management UI (:15672) dává operační viditelnost bez debugování kódu

3. AMQP infra existuje v docker-compose.yml podpora21

4. Škáluje na N downstream projektů bez změny master strany

TCP fallback pro dev prostředí bez Dockeru.

B (čistý TCP) zamítnut: zprávy se ztrácí při výpadku mastera, nutná přímá síťová dostupnost.

C (HTTP polling) zamítnut: latence, zbytečný overhead pro event-driven model.

Bridge deployment: tek_agent_bridge.py + .agents/bridge.json jsou součástí TEK distribuce a distribuují se přes tek_sync.py.

RabbitMQ topologie

Exchanges:

tek.events type=topic durable=true downstream → master

tek.commands type=direct durable=true master → downstream

Queues (auto-declare při startu bridge):

tek.events.<repo_key> — binding: tek.events / tek.event.<repo_key>.#

tek.events.master — binding: tek.events / tek.event.# (master konzumuje vše)

tek.cmd.<repo_key> — direct, consumed by bridge v daném repo

tek.dlq — dead-letter

Routing key konvence:

events: tek.event.<repo_key>.<event_type>

commands: tek.cmd.<repo_key>

MVP commands: cmd.task.set_status, cmd.task.add_note

Event types: task.created, task.status_changed, task.updated, task.note_added, agent.started, agent.heartbeat, sync.full_state, cmd.ack

Failure modes

RabbitMQ nedostupný při startu → retry 5× exp. backoff (1s→16s), pak TCP fallback

RabbitMQ vypadne za běhu → aio-pika robust reconnect; events v letu se ztratí (bez offline bufferu)

Master consumer vypadne → RabbitMQ drží zprávy (TTL 7 dní), doručí po restartu

Bridge vypadne → master označí agenta inactive po >5 min bez heartbeat

Duplicate events → event_id UUID, master ignoruje duplicity (idempotentní upsert)

Command nedoručen → retry 3×, pak failed + DLQ

Důsledky

Pozitivní:

Cross-repo viditelnost tasků v reálném čase
Centrální task mirror v PostgreSQL (podpora21)
Master může posílat commands downstream
RabbitMQ buffering zajišťuje odolnost při výpadcích

Negativní / rizika:

Guest/guest credentials, localhost only — mTLS/HMAC je future work
Bez offline bufferu v bridge: events v letu se ztratí při výpadku RabbitMQ
Akceptovatelné pro single-developer prostředí

Implementováno v TASK-0208, TASK-0209, TASK-0210.

Changelog

Version	Date	Author	Note
1.0.0	2026-04-10	david.sorf	Migrováno z docs/adr/ADR-011-TEK-Agent-Bridge-Transport.md (původní datum: 2026-04-04). Provozní poznatky zachovány v source MD souboru.