# Pipelines - Obserwowalność agentów AI

> Obserwuj pracę agentów AI jako pipeline'y - w czasie rzeczywistym

Moduł Pipelines modeluje pracę agentów AI jako obserwowalność (nie wykonanie). Hierarchia Pipeline -> PipelineStep -> PipelineJob w PostgreSQL pozwala śledzić każdy etap pracy agenta: od researchu, przez kodowanie, po podsumowanie. Logi jobów przechowywane są jako strony wiki, status propaguje się w górę - nieudany job pociąga za sobą nieudany step i pipeline. Dashboard odświeża się co 15 sekund, a is_stale() flaguje pipeline'y stuck > 6h.

## Funkcje

- **Hierarchia Pipeline -> Step -> Job**: Każdy pipeline składa się ze stepów (research, coding, wrap-up), a każdy step z jobów. Status propaguje się w górę - nieudany job -> nieudany step -> nieudany pipeline.
- **Logi jobów jako strony wiki**: Każdy job ma własną stronę wiki z pełnym logiem (content w MinIO). Strony grupowane pod rodzicem 'pipeline-logi', wykluczone z RAG - nie zaśmiecają wyników wyszukiwania.
- **Live polling 15s**: Lista pipeline'ów i widok detalu odświeżają się co 15 sekund przez HTMX. Czasy trwania liczone w locie (finished_at - started_at lub now() - started_at dla aktywnych).
- **Detekcja stuck pipeline'ów**: is_stale() flaguje pipeline'y w statusie running bez aktualizacji przez ponad 6 godzin. Obliczane przy odczycie, bez crona.
- **Read-only UI - kontrola przez MCP**: Dashboard jest read-only - pipeline'y tworzone przez skille przez MCP, nie z interfejsu. Agenci AI mają pełną kontrolę przez 9 dedykowanych narzędzi MCP.
- **Integracja z wiki-log**: Przy włączonym LLM Wiki, zakończenie pipeline'u dodaje wpis do wiki-log. Najlepszy wysiłek - błąd MCP pipeline'u nie zatrzymuje pracy agenta.

## Jak to działa

1. **Agent tworzy pipeline**: Skill wywołuje create_pipeline przez MCP - pipeline ticket_work automatycznie dostaje 3 stepy: research, coding, wrap-up.
2. **Agent raportuje start jobów**: create_pipeline_job rejestruje nowy job w stepie (np. 'Analiza kodu źródłowego' w stepie coding). Status: pending -> running.
3. **Agent dopisuje logi**: append_job_log dołącza markdown do strony wiki jobu. Każde wywołanie dodaje kolejny akapit - pełna historia pracy agenta.
4. **Agent raportuje wynik**: update_pipeline_job(status='success'/'failure') zamyka job, ustawia finished_at i propaguje status w górę do stepa i pipeline'u.
5. **Dashboard pokazuje postęp**: Widok pipeline'u z kolumnami stepów i kartami jobów. Statusy, czasy trwania i linki do logów wiki - wszystko w czasie rzeczywistym.
6. **finish_pipeline zamyka całość**: Agent wywołuje finish_pipeline po zakończeniu pracy. Status finalny agregowany ze stepów jeśli nie podany. Opcjonalnie wpis do wiki-log.

## AI i MCP

9 narzędzi MCP do pełnej obserwacji pracy agentów - tworzenie pipeline'ów, raportowanie jobów, dopisywanie logów i zamykanie. Wszystkie operacje best-effort - błąd pipeline'u nie blokuje pracy agenta.

- `create_pipeline`: Utwórz pipeline (ticket_work: automatyczne stepy research/coding/wrap-up).
- `create_pipeline_job`: Dodaj job do stepa z nazwą, opisem i statusem startowym.
- `update_pipeline_job`: Aktualizuj status i summary jobu. Propagacja w górę: job -> step -> pipeline.
- `append_job_log`: Dołącz markdown do strony wiki jobu. Tworzy stronę przy pierwszym wywołaniu.
- `finish_pipeline`: Zamknij pipeline z finalnym statusem (agregowany ze stepów jeśli nie podany).
- `list_pipelines`: Lista pipeline'ów projektu z filtrami statusu i typu oraz paginacją.
- `get_pipeline`: Pełne drzewo pipeline'u: stepy, joby, czasy, statusy i linki do logów.
- `get_pipeline_job_log`: Pobierz pełny log jobu jako markdown z powiązanej strony wiki.
- `clean_pipeline_logs`: Usuń strony wiki z logami jobów pipeline'ów danego sprintu (sprzątanie po zamknięciu).

## Szczegóły techniczne

- **Model danych**: Pipeline -> PipelineStep -> PipelineJob w PostgreSQL. UUID klucze, timestamps (created_at, started_at, finished_at). pipeline_type: ticket_work | sprint_close.
- **Propagacja statusu**: _update_step_status() i _update_pipeline_status() w services/pipelines.py. Job failed -> step failed -> pipeline failed. Agregacja przez min() statusów.
- **Logi wiki**: PipelineJob.wiki_page_id linkuje do WikiPage. exclude_from_embeddings=True - logi nie trafiają do RAG. Rodzic 'pipeline-logi' tworzony idempotentnie.
- **Live polling**: HTMX hx-trigger='load delay:15s' na listRow i treePartial. Czasy liczone w locie - brak kolumny duration w bazie.
- **is_stale()**: Funkcja przy odczycie: pipeline running + last update > 6h temu. Obliczana w serwisie, bez crona. Flaguje stuck agentów.
- **Wzorzec GitLab CI/CD**: Architektura pipeline/step/job wzorowana na GitLab CI/CD. Obserwowalność (nie wykonanie) - agenci sami raportują postęp przez MCP.