colibri/docs/wiki/sl/glasspane.md

title	description
Glasspane — nadzor stanja agentov	Colibrijeva plast za opazovanje agentov. Gleda podprocese agentov prek JSONL, zlaga tok v semantični avtomat stanj in izpostavlja API posnetkov.

← kazalo

Kaj je to

Glasspane je Colibrijeva plast za opazovanje agentov. Opazuje podprocese agentov prek njihovega stdout JSONL, zlaga tok v semantični avtomat stanj (Idle → Working → Done) in izpostavlja API posnetkov za nadzorne plošče in koordinacijo procesa v ozadju. Vsak zagnani agent — Pi, zot ali lokalni sample — se pretaka skozi isti vnosnik in konča v isti taksonomiji.

Odločitve

Stanje agenta kot avtomat stanj, ne surovi dnevnik dogodkov

Glasspane ne posreduje samo surovih agentskih dogodkov. Zaužije vrstice JSONL in prehaja poimenovano podokno skozi končno množico stanj:

Idle → Working → Blocked → Done
         ↳ Error

Enum AgentState (Idle, Working, Blocked, Done, Error) je namenoma majhen. Zajame tisto, kar nadzornik potrebuje vedeti — "ali agent dela? je blokiran? je končal?" — brez kodiranja agentsko-specifične semantike. Dogodki, ki ne spremenijo stanja (npr. poročilo o uporabi iz zot), so zabeleženi v metapodatkih podokna, vendar ne vplivajo na avtomat stanj.

Stalled ni šesta različica — je izpeljana zastavica: podokno je stalled, ko v DEFAULT_STALL_AFTER (4 ure) ni prispel noben dogodek. Izpeljano pozornost (Error / Blocked / Stalled) pokriva operator-attention.

Zakaj ne preprosto slediti dnevniku: surovi dnevniki dogodkov so agentsko-specifični in se sčasoma spreminjajo (zot dodaja nove vrste dogodkov). Avtomat stanj je stabilna pogodba, na katero se lahko zanesejo proces v ozadju, TUI in odjemalski CLI.

→ crates/colibri-glasspane/src/lib.rs

Pretakanje JSONL (ena vrstica = en dogodek)

Agenti oddajajo strukturirane dogodke kot JSON, ločen z novimi vrsticami, na stdout. Glasspane bere vrstico za vrstico z BufReader, deserializira vsako vrstico in jo poda v PiJsonlIngestor (ime je podedovano — obdeluje tudi zot dogodke).

Bralnik teče v eni sami nalogi ozadja na podokno (pane_reader_loop). Nikoli ne blokira glavne zanke procesa v ozadju — vnosnik je sinhrono zlaganje, ki posodablja stanje podokna v pomnilniku, API posnetkov pa bere iz Arc<RwLock<...>> brez sporov na vroči poti bralnika.

Napačno oblikovane vrstice so preskočene s povečanjem števca, ne kot napaka — izpadi v JSONL agenta ne smejo zrušiti opazovalca.

Zakaj JSONL, ne vtičnica ali gRPC: agent je podproces, ne storitev. stdout je univerzalni vmesnik — vsak jezik, vsaka vprega, brez nastavitve. JSONL je trivialno pisati iz bash, Go, Python, Rust. Strukturiran žični format bi dodal odvisnost in rokovanje vsakemu agentu.

→ crates/colibri-glasspane/src/lib.rs (PiJsonlIngestor, pane_reader_loop)

AgentRuntime { Pi, Zot, Local } — ena taksonomija za dve opremi

Pi in zot oddajata različne surove vrste dogodkov: Pi uporablja agent_start / turn_end, zot uporablja turn_start / done. Glasspane preslika oba v iste prehode AgentState prek zot_event_type(). Enum AgentRuntime označi vsako podokno z njegovo opremo, da funkcija preslikave ve, kateri besednjak dogodkov naj razčleni.

Polje session_id v strukturi Pane uporablja #[serde(alias = "pi_session_id")] za povratno združljivost s pred-nevtralnostnimi serializiranimi posnetki.

Zakaj ne dva ločena avtomata stanj: TUI, razporejevalnik procesa v ozadju in odjemalski CLI morajo vsi vprašati "v kakšnem stanju je ta agent?" — vseeno jim je, ali je zot ali Pi. Ena taksonomija, en API. Preslikava je ~50-vrstična funkcija, ne podsistem.

→ crates/colibri-glasspane/src/lib.rs (zot_event_type, AgentRuntime)

API posnetkov (bralno usmerjen, ne pisalno)

Glasspane izpostavlja objekt posnetka (celoten nabor podoken s trenutnim stanjem, ID seje, časovnim žigom in metapodatki) prek Arc<RwLock<...>>. Demon ga streže prek svoje Unix vtičnice bralcem odjemalcev. Pisanja se zgodijo enkrat na dogodek; branja so pogosta (pogledi TUI, statusna preverjanja CLI).

Zakaj RwLock, ne kanali: pisalna pot je nizkofrekvenčna (agentski JSONL s hitrostjo človeškega branja), bralna pot pa v običajnem primeru brez zaklepa. Zasnova, osnovana na kanalih, bi dodala medpomnjenje in semantiko dostave za problem, ki je v osnovi o trenutnem stanju, ne o dostavi dogodkov.

→ crates/colibri-glasspane/src/lib.rs (Supervisor, snapshot)

Načrt uporabnosti (TODO)

Pozornostna polovica tega načrta je dostavljena: izpeljan predikat pozornosti, pozornostna vrstica TUI / tipke za skok / filter / poudarjanje vrstic in robno sprožena opozorila zajema terminala. Glej operator-attention za dostavljen sistem. Kar ostaja tukaj, je resnično nezgrajena smer.

Potisna obvestila navzven, ne samo na zaslonu

Operater nadzoruje brezglave gostitelje prek Tailscale, ne z buljenjem v TUI. Ko podokno sproži pozornost (ali doseže Done), jo potisni navzven: namizno obvestilo na živi sliki (XFCE) in sporočilo Telegram (žeton je že pripravljen). Eksplicitna pot v slogu colibri notify — ali vrsta dogodka glasspane, ki jo sproži kljuka zot/Pi — omogoča agentu reči "blokiran sem", namesto da se zanašamo samo na izpeljano stanje. Največji učinek v resničnem svetu.

Bogatejše vrstice podoken (kontekst na prvi pogled)

Glasspane že shranjuje dogodke, ki ne spreminjajo stanja, v metapodatkih podokna. Prikaži jih v vrstici TUI: trenutni repo/veja, zadnja vrstica/povzetek naloge, ječa, v kateri agent teče, neobvezno vhodna vrata. Spremeni "Working" v "Working on fix/x v ječi cms, zadnje: running tests".

Ohrani zgodovino podoken med ponovnimi zagoni procesa v ozadju

Nadzornik je v pomnilniku (Arc<RwLock<...>>); ponovni zagon procesa v ozadju izgubi časovnico. Ohrani prehode/zgodovino podoken, da vrnitev po urah (ali ponovnem zagonu) ohrani "kaj se je zgodilo, ko me ni bilo". Lahka trajnost, ne nov podsistem.

Odgovori blokiranemu agentu z nadzorne plošče (večji dvig)

API posnetkov je namenoma bralno usmerjen. Prihodnja pisalna pot — "pošlji vnos v podokno N" prek vtičnice procesa v ozadju — bi operaterju omogočila odziv blokiranemu agentu iz colibri-tui, ne samo opazovanje/zagon/uboj. To je smer, ne hitra zmaga; spremeni vtičnico iz bralnega nadzora v interaktivno upravljanje in potrebuje lasten načrtovalski prehod.

Glej tudi

• agent-harness — razcep zot/Colibri, ki ga Glasspane opazuje
• operator-attention — dostavljena plast pozornosti/opozoril nad tem avtomatom stanj
• naming-decisions — pi_session_id → session_id, pi_type → event_type