Dissenyar dashboard operatiu amb GitHub OAuth per al bridge

[pilipilisbot]

Dashboard operatiu del GitHub Agent Bridge

Context

Els incidents recents amb github-agent-bridge han deixat clar que mirar només l'estat pending/running/blocked/done no és suficient. Un job pot estar running però no estar fent progrés útil, i l'usuari no hauria d'haver d'entrar a Telegram a preguntar què passa.

Volem un backend i dashboard operatiu per veure l'estat real dels agents, jobs, processos, mètriques i logs, amb autenticació GitHub OAuth.

Stack acordat

• Backend: FastAPI com a servei separat github-agent-bridge-dashboard.
• Frontend: React + Vite + TypeScript.
• UI: Tailwind + components estil shadcn/ui + lucide-react.
• Dades client: TanStack Query amb polling inicial.
• Gràfiques: Recharts.
• Logs/events live: SSE inicialment; WebSocket només si cal bidireccionalitat real.
• Producció: build estàtic servit pel mateix FastAPI.

Estat actual

Ja s'han integrat:

• feat: add read-only backend service #5: M1 backend read-only, GitHub OAuth, APIs inicials i lògica compartida de dashboard.
• feat: add React dashboard UI #6: M2 UI React read-only amb overview, taula de jobs, detall, filtres i gràfiques.
• docs: document dashboard GitHub OAuth setup #7: documentació de configuració GitHub OAuth.
• feat: expose dashboard process activity #8: M3 parcial amb snapshot live de processos /proc, API /api/processes i panell UI.
• feat: correlate dashboard jobs with OpenClaw sessions #9: M4 parcial amb correlació segura job -> sessió OpenClaw.

Norma de seguiment: cada PR futura que avanci aquesta issue ha de marcar els checkboxes corresponents en aquesta descripció.

Checklist

M0: Arquitectura i stack

• Definir objectius i no objectius del dashboard.
• Triar stack backend/frontend/UI.
• Decidir servei separat github-agent-bridge-dashboard.
• Mantenir la superfície inicial read-only, sense accions mutatives.

M1: Backend read-only i OAuth

• Crear app FastAPI del dashboard.
• Servir el dashboard com a servei separat de l'executor.
• Obrir SQLite en mode read-only per a consultes del dashboard.
• Reutilitzar lògica compartida de dades fora del backend perquè també serveixi CLI/monitor.
• Implementar GitHub OAuth login/callback.
• Signar sessions amb cookie httpOnly, secure i sameSite=lax.
• Autoritzar per GITHUB_AGENT_BRIDGE_DASHBOARD_ALLOWED_USERS.
• Autoritzar per GITHUB_AGENT_BRIDGE_DASHBOARD_ALLOWED_ORGS amb scope read:org només quan cal.
• Exposar GET /api/health.
• Exposar GET /api/status.
• Exposar GET /api/jobs amb filtres per status, repo, thread, action, intent, since, until, limit.
• Exposar GET /api/jobs/{id}.
• Exposar GET /api/jobs/{id}/logs.
• Exposar GET /api/metrics/summary amb counts i percentils.
• Afegir tests d'autorització, API i consultes.
• Afegir allowedTeams.
• Afegir repoScopes per limitar visibilitat per repos/thread.

M2: UI read-only

• Crear app React + Vite + TypeScript a dashboard/.
• Servir el build estàtic des de FastAPI a /.
• Afegir overview amb counts operatius.
• Afegir taula de jobs amb filtres.
• Afegir detall de job amb timeline/worklog i links GitHub.
• Mostrar mètriques de runtime i queue wait amb Recharts.
• Usar TanStack Query per polling/refetch.
• Mantenir UI sense accions mutatives.
• Millorar el layout responsive per a dispositius mòbils amb cards compactes i detall inline.
• Limitar el scroll de la llista de jobs en desktop i mantenir el detall visible.
• Afegir gràfica de jobs per dia.
• Mostrar l'avatar de l'usuari autenticat al header.
• Afegir vista/panell dedicat d'alertes quan hi hagi storage d'alertes persistent.
• Afegir lectura SSE per invalidar/refrescar dades en temps real.

M3: Runtime/proc observability i watchdog

• Afegir helper compartit de lectura /proc per cmd, estat, CPU ticks, I/O bytes i fills.
• Reutilitzar el helper en monitor/watchdog en comptes de duplicar lògica.
• Exposar snapshot live a GET /api/processes.
• Mostrar process activity a la UI.
• Documentar que el snapshot actual és live i no històric.
• Persistir samples curts a job_process_samples o taula equivalent.
• Afegir retenció configurable de samples/process logs.
• Separar explícitament a l'API procés viu, procés actiu, progrés semàntic i progrés visible.
• Registrar heartbeat semàntic/fase del job durant execució.
• Persistir alertes i accions del watchdog en una taula alerts o equivalent.
• Fer que el watchdog prengui decisions amb CPU/I/O/PID tree quiet i heartbeat semàntic recent, no només edat.

M4: Session/log correlation

• Assignar openclaw_session_id determinista github-agent-bridge-job-{id} quan es reclama un job.
• Passar --session-id a openclaw agent.
• Exposar metadades segures a GET /api/jobs/{id}/session.
• Mostrar la correlació de sessió al detall del job.
• Documentar que no s'exposen transcripts complets.
• Exposar activitat redacted bridge-side de sessió/agent amb events de claim, dispatch i finalització.
• Exposar entrades redacted i truncades del transcript OpenClaw per job/sessió.
• Integrar resum segur de sessió/últimes fases si OpenClaw exposa una API adequada.
• Definir política d'admin/redacció/truncament abans d'exposar qualsevol transcript.

M5: Admin actions guarded

• Retry job des del dashboard.
• Dismiss/ack de job blocked.
• Kill de child stale.
• Confirmacions explícites per accions mutatives.
• CSRF/session hardening específic per mutacions.
• Audit log per totes les accions mutatives.
• Política d'autorització admin separada de la lectura.

Documentació i operació

• Documentar configuració del servei dashboard.
• Documentar creació/configuració de GitHub OAuth App.
• Documentar callback URL, scopes, allowlists, reverse proxy/TLS i troubleshooting.
• Afegir variables del dashboard a systemd/env.example.
• Documentar com executar i compilar la UI.
• Afegir guia operativa específica per alertes persistides quan existeixin.
• Afegir notes de deploy/rollout del dashboard en producció real.

Seguretat

• No exposar env vars ni secrets en respostes API/UI.
• No servir fitxers arbitraris per path.
• Mantenir l'API inicial read-only.
• Usar cookies httpOnly, secure i sameSite=lax.
• OAuth state obligatori.
• Requerir autenticació per defecte.
• Tancar/definir CORS explícitament si el servei s'exposa fora de localhost.
• Afegir repo/team scopes abans d'obrir el dashboard a més operadors.
• Definir redacció/truncament per logs voluminosos o transcripts.

Proper pas recomanat

Amb M3 completat, el següent pas recomanat és tancar els controls d.accés pendents (allowedTeams i repoScopes) abans d.obrir el dashboard a més operadors o començar M5/admin actions.

[pilipilisbot]

Stack a utilitzar

Recomanació pragmàtica per implementar el dashboard ràpid i mantenible:

• Backend: FastAPI.

  • API REST per jobs, mètriques, logs i configuració visible.
  • GitHub OAuth per login.
  • RBAC simple per usuaris/orgs/teams autoritzats.
  • SSE inicialment per stream de logs/events; WebSocket només si realment cal interacció bidireccional.

• Frontend: React + Vite + TypeScript.

  • Separat en desenvolupament.
  • Build estàtic servit pel mateix FastAPI en producció.

• UI: Tailwind + shadcn/ui + lucide-react.

  • Bona velocitat per construir dashboards interns.
  • Components útils: taules, tabs, badges, dialogs, dropdowns, skeletons, cards, toasts.
  • Estètica sòbria i operacional, sense inventar design system propi.

• Dades client: TanStack Query.

  • Refetch/polling senzill per llistats i mètriques.
  • Integració posterior amb SSE per invalidar/refrescar dades quan hi hagi events nous.

• Taules: començar amb taules shadcn simples.

  • Passar a TanStack Table només si cal sorting/filtering/paginació avançada al client.

• Gràfiques: Recharts.

  • Suficient per runtime percentiles, durades per fase, jobs per estat, alertes i retries.

• Logs en viu: SSE + viewport virtualitzat si el volum creix.

  • Evitar WebSocket al principi: SSE cobreix bé el cas "servidor emet events/logs".

• Build/deploy: npm/pnpm per frontend, Python package extra per dashboard.

  • Exemple: github-agent-bridge[dashboard].
  • Servei separat: github-agent-bridge-dashboard.service.

Tecnologies descartades per ara:

• Next.js: massa pes per una eina interna sense SEO ni routing complex de servidor.
• HTMX-only: ràpid per CRUD, però queda curt per logs en viu, filtres rics, mètriques interactives i estat client.
• Django: massa framework per una eina que ja té domini i storage propis; FastAPI encaixa millor amb API + UI estàtica.

[ecarreras]

@pilipilisbot ara que ja s'ha integrat la #5 es pot avançar amb la part de UI? fes una nova pull-request per continuar el desenvolupament.

[pilipilisbot]

He obert la PR per continuar amb la part de UI: #6

Resum:

• afegeix una UI read-only a / dins del servei github-agent-bridge-dashboard;
• mostra counts operatius, filtres de jobs, taula de jobs i detall/timeline de worklog reutilitzant l'API existent;
• manté la superfície sense accions mutatives;
• actualitza docs d'operació i afegeix tests d'auth/rendering.

Validació: .venv/bin/python -m pytest -q -> 106 passed.

[ecarreras]

@pilipilisbot com que portarà integració amb Github pots documentar com es configura i quins passos s'han de fer a Gihtub també? Crea una pull-request per afegir aquesta documentació i segueix tot el que hi hagi en aquesta issue per entendre l'arquitectura

[pilipilisbot]

He obert la PR de documentació demanada: #7

Resum:

• nova guia docs/dashboard-github-oauth.md amb els passos per crear/configurar la GitHub OAuth App, callback URL, scopes read:user read:org, allowlists, notes de reverse proxy/TLS i troubleshooting;
• enllaços des de docs/README.md, docs/installation.md i docs/operations.md;
• variables OAuth del dashboard afegides a systemd/env.example.

Commit: 3250192 (docs: document dashboard GitHub OAuth setup).
Validació: git diff --check OK; checks GitHub pytest (3.11) i pytest (3.12) en verd.

[ecarreras]

@pilipilisbot repassa aquesta issue I El que tenim fet del repositori i avança cap el següent ítem de la issue. Tingués present sempre aquesta issue I els comentaris com a referencia d'arquitectura i stack tecnològic

[pilipilisbot]

He obert la següent PR de la issue cap a M3/runtime observability: #8

Resum:

• afegeix un helper compartit de lectura /proc per cmd, estat, CPU ticks, I/O bytes i arbre de fills;
• el monitor reutilitza aquest helper en lloc de tenir lògica pròpia de processos;
• GET /api/processes ara retorna una fotografia live de l'executor, PID principal, fills i alertes;
• la UI React mostra un panell de process activity amb executor, PID, running jobs i processos fills;
• actualitza la documentació d'operació per deixar clar que això és live snapshot, i que la retenció històrica de samples queda com a increment posterior de M3.

Validació:

• .venv/bin/python -m pytest -q -> 112 passed;
• cd dashboard && npm ci && npm run build OK;
• checks GitHub pytest (3.11) i pytest (3.12) en verd.

[ecarreras]

@pilipilisbot ja pots continuar amb la següent fase d'aquesta issue

[pilipilisbot]

He obert la següent PR per avançar M4/session correlation: #9

Resum:

• cada job reclamat guarda un openclaw_session_id determinista github-agent-bridge-job-{id} a metadata_json;
• el dispatcher passa aquest id a openclaw agent --session-id, de manera que els dispatches futurs queden correlacionats amb la sessió OpenClaw;
• /api/jobs/{id}/session deixa de ser un placeholder i exposa només metadades segures de correlació, sense transcript complet;
• la UI React mostra la sessió correlacionada al detall del job i la documentació d'operació reflecteix l'abast actual.

Commit: 5737678 (feat: correlate dashboard jobs with OpenClaw sessions).
Validació local: .venv/bin/python -m pytest -q -> 113 passed; cd dashboard && npm ci && npm run build OK; git diff --check OK.

[ecarreras]

@pilipilisbot revisa tot el que hi ah fet d'aquesta issue I canvia la descripció de la issue amb checkboxes per poder fer millor el seguiment. En futures pull request marxa com a fets els checkboxes