Z Codex CLI na plnohodnotnú OS Layer capability

AI nástroje na programovanie sa dnes väčšinou používajú ako interaktívne terminálové aplikácie. Spustíš klienta, otvoríš mu repozitár, zadáš úlohu a čakáš, čo vykoná.

Pre človeka sediaceho pri termináli je to použiteľný model. Problém nastane vo chvíli, keď chceš takýto nástroj zapojiť do väčšieho systému:

• spúšťať ho programovo,

• obmedziť mu prístup k prostrediu,

• kontrolovať pracovný adresár,

• sledovať jeho priebeh,

• zaznamenať výsledok,

• ukončiť ho pri prekročení timeoutu,

• napojiť ho na ďalšie agentové alebo systémové komponenty.

Priamy subprocess nad CLI na toto nestačí.

Preto sme Codex nezabalili iba do ďalšieho shell skriptu. Spravili sme z neho samostatnú OS Layer capability.

Codex zostáva Codexom. OS Layer ho nenahrádza. Poskytuje mu však riadené prostredie, jednotný dispatch, izoláciu, observabilitu a životný cyklus vhodný pre automatizované agentové systémy.

Čo znamená capability v OS Layer

Capability je samostatná systémová jednotka, ktorá poskytuje konkrétnu skupinu funkcií.

Namiesto toho, aby orchestrátor poznal interné detaily každého programu, pracuje s jednotným modelom:

capability → entrypoint → function

V prípade Codexu môže dispatch vyzerať napríklad takto:

capability=codex
entrypoint=codex-worker
function=inspect

Orchestrátor teda nemusí vedieť, akým spôsobom sa zostavuje príkaz pre upstream Codex CLI, ako sa nastavuje provider, kde sa ukladá journal alebo ako sa ukončí proces pri timeoutoch.

Tieto zodpovednosti patria capability.

Takéto rozdelenie je dôležité. Z Codexu sa nestáva špeciálny prípad zabudovaný priamo do orchestrátora. Je iba ďalšou capability, ktorú možno volať rovnakým spôsobom ako AI, audio, mail, filesystem alebo inú časť systému.

Prečo nestačí obyčajný wrapper

Na prvý pohľad by stačilo spraviť niečo podobné:

codex exec "$PROMPT"

Takýto wrapper však nerieši zásadné otázky:

• Z ktorého adresára sa proces spustí?

• Aké premenné prostredia zdedí?

• Ku ktorým credentials má prístup?

• Aký model a provider použije?

• Ako dlho môže bežať?

• Čo sa stane s child procesmi po timeoutoch?

• Ako sa zachytí stdout a stderr?

• Ako ostatné časti systému zistia, že operácia začala alebo zlyhala?

• Kde zostane auditná stopa?

• Ako sa overí, že inspect operácia skutočne nič nezmenila?

Práve toto je rozdiel medzi CLI wrapperom a capability.

Wrapper iba spúšťa príkaz. Capability spravuje celý životný cyklus operácie.

Codex worker ako riadená execution vrstva

Hlavným runtime komponentom capability je codex-worker.

Worker prijme normalizované argumenty od OS Layer, pripraví execution context a až následne spustí upstream codex exec.

Typická operácia môže niesť napríklad:

cwd=/home/pihi/os_layer/codex
model=gpt-5.6-sol
function=inspect
prompt=Preskúmaj capability bez vykonania zmien...

Worker z týchto údajov vytvorí konkrétny beh.

Jeho úlohou nie je premýšľať namiesto Codexu. Jeho úlohou je zabezpečiť, aby Codex bežal predvídateľne a v hraniciach definovaných systémom.

Execution flow vyzerá približne takto:

Používateľ alebo agent
        │
        ▼
OS Layer dispatch
        │
        ▼
Codex capability
        │
        ▼
codex-worker
        │
        ├── validácia argumentov
        ├── príprava pracovného adresára
        ├── provider a environment izolácia
        ├── nastavenie sandboxu
        ├── vytvorenie journal záznamu
        ├── emitovanie udalosti started
        │
        ▼
upstream codex exec
        │
        ├── stdout
        ├── stderr
        ├── exit code
        └── timeout alebo signal
        │
        ▼
výsledok + journal + udalosti

Codex teda stále vykonáva samotnú agentovú prácu. OS Layer kontroluje podmienky, za ktorých ju vykonáva.

Funkcia inspect

Jednou z prvých praktických operácií je inspect.

Jej účelom je preskúmať projekt alebo capability bez vykonávania zmien. Dá sa použiť na analýzu architektúry, CLI rozhraní, testov, bezpečnostných hraníc alebo implementačných detailov.

Príklad zadania:

Bez úprav preskúmaj iba capability Codex v aktuálnom adresári.

Vysvetli:
- CLI príkazy,
- spúšťanie upstream codex exec,
- provider izoláciu,
- sandbox,
- journal,
- udalosti,
- timeout,
- testy.

Nevykonávaj build ani testy.
Každé tvrdenie podlož konkrétnou relatívnou cestou k súboru.

Tento typ operácie je užitočný pri code review, bezpečnostnom audite, dokumentovaní existujúceho systému alebo pred plánovanou refaktorizáciou.

Dôležité však je, že read-only správanie nemá zostať iba vetou v prompte.

Capability môže obmedzenie podporiť aj technicky:

• režimom sandboxu,

• zakázaním write oprávnení,

• obmedzením dostupných nástrojov,

• explicitnou policy pre danú funkciu,

• testami, ktoré overia, že operácia nemení pracovný strom.

Prompt vyjadruje zámer. Runtime hranice zabezpečujú jeho vynútenie.

Izolácia providerov a prostredia

Pri priamom spustení CLI proces často zdedí celé prostredie používateľa.

To je pohodlné, ale nebezpečné.

Proces môže získať prístup k premenným, tokenom a konfigurácii, ktoré s konkrétnou operáciou vôbec nesúvisia. V agentovom systéme je takýto model príliš široký.

Codex capability preto pristupuje k provider konfigurácii ako k explicitnej závislosti.

Worker pripraví iba prostredie potrebné pre zvolený beh. Provider, model, endpoint a credentials sa nemajú načítavať náhodne z globálneho shellu, ale z kontrolovanej vrstvy OS Layer.

Výsledkom je niekoľko praktických výhod:

1. Beh je reprodukovateľnejší.

2. Capability nevidí secrets iných providerov.

3. Možno presne zaznamenať, ktorý provider a model boli použité.

4. Testy môžu používať oddelenú alebo mock konfiguráciu.

5. Zmena providera nevyžaduje prerábať orchestrátor.

Provider izolácia teda nie je iba otázka konfigurácie. Je to bezpečnostná hranica.

Kontrolovaný pracovný adresár

Coding agent musí vedieť, nad ktorým repozitárom pracuje.

Spoliehať sa na aktuálny adresár procesu je krehké. Pri daemonoch, workeroch a automatizovaných joboch môže byť aktuálny adresár úplne iný, než očakáva používateľ.

Preto je cwd súčasťou kontraktu operácie.

Napríklad:

codex_inspect 
  --cwd /home/pihi/os_layer/codex 
  --model gpt-5.6-sol 
  "Bez úprav preskúmaj capability Codex..."

Worker musí cestu validovať ešte pred spustením upstream procesu.

Môže overiť napríklad:

• či cesta existuje,

• či ide o adresár,

• či patrí medzi povolené korene,

• či nie je mimo sandboxu,

• či je pre danú funkciu povolený zápis,

• či operácia nemá pracovať iba s konkrétnou capability.

Tým sa pracovný adresár mení z implicitného stavu shellu na explicitnú, kontrolovateľnú súčasť requestu.

Sandbox a hranice oprávnení

Coding agent je výkonný nástroj. Môže čítať zdrojový kód, spúšťať príkazy, meniť súbory a v niektorých režimoch komunikovať so sieťou.

Capability preto musí vedieť definovať hranice konkrétnej operácie.

Inspect môže mať inú policy ako implementácia alebo oprava.

Napríklad:

inspect:
  storage.read = allowed
  storage.write = denied
  network = podľa providera
  remote.exec = denied

Implementačná operácia môže vyžadovať:

storage.read = allowed
storage.write = guarded
remote.exec = guarded

Sandbox v tomto modeli nie je jedna globálna voľba typu zapnuté alebo vypnuté. Je súčasťou policy konkrétnej funkcie a konkrétneho behu.

To umožňuje používať rovnaký upstream Codex v rôznych bezpečnostných režimoch bez vytvárania samostatných klientov pre každý use case.

Udalosti a observabilita

Interaktívny terminál ukazuje používateľovi priebeh priamo. Automatizovaný systém túto výhodu nemá.

Ak Codex beží ako capability, ostatné komponenty potrebujú vedieť:

• že operácia bola prijatá,

• že worker začal,

• že upstream proces bol spustený,

• že prišiel prvý výstup,

• že operácia skončila,

• že nastal timeout,

• že proces zlyhal,

• že bol beh zrušený.

Capability preto emituje štruktúrované udalosti.

Napríklad:

codex.requested
codex.started
codex.output
codex.completed
codex.failed
codex.timeout
codex.cancelled

Takéto udalosti môže sledovať CLI, webové rozhranie, daemon, test runner alebo ďalší agent.

To je zásadný rozdiel oproti parsovaniu náhodného terminálového výstupu. Udalosť má definovaný typ, identifikátor behu, čas a štruktúrované dáta.

Journal ako auditná stopa

Každý beh by mal po sebe zanechať dostatok informácií na spätnú analýzu.

Journal môže obsahovať:

• identifikátor operácie,

• capability,

• entrypoint,

• function,

• pracovný adresár,

• použitý model a provider,

• čas začiatku a konca,

• timeout,

• exit code,

• dôvod ukončenia,

• zachytený výstup,

• emitované udalosti,

• aplikovanú policy.

Journal nie je iba debug log.

Je to odpoveď na otázku:

Čo presne systém spustil, v akom prostredí a s akým výsledkom?

Pri agentových operáciách je táto informácia kritická. Najmä keď sa beh vykonáva bez otvoreného terminálu alebo ako súčasť väčšieho automatizovaného workflow.

Timeout a ukončenie procesov

AI operácia môže zamrznúť, čakať na sieť, zablokovať sa na subprocessoch alebo pokračovať výrazne dlhšie, než má zmysel.

Preto timeout nemôže byť ponechaný iba na upstream nástroj.

Musí ho riadiť capability.

Pri prekročení limitu nestačí ukončiť iba rodičovský proces. Ak Codex spustil ďalšie child procesy, tie môžu pokračovať na pozadí.

Správna implementácia preto rieši celý process tree alebo process group:

1. Worker spustí upstream proces v samostatnej skupine.

2. Sleduje definovaný deadline.

3. Pri timeoutoch odošle kontrolovaný termination signal.

4. Po grace period použije nútené ukončenie.

5. Zachytí konečný stav.

6. Zapíše dôvod ukončenia do journalu.

7. Emituje udalosť codex.timeout.

Tým sa timeout stáva súčasťou garantovaného správania capability, nie iba najlepšou snahou wrappera.

Chyba ako štruktúrovaný výsledok

Počas prvého reálneho inspect behu sa napríklad dispatch vykonal správne:

capability=codex
entrypoint=codex-worker
function=inspect

Samotná operácia však približne po 2,2 sekundy skončila chybou.

Aj takýto výsledok je dôležitý.

V bežnom shell modeli by používateľ často dostal iba exit code a kus stderr. V capability modeli môžeme oddeliť jednotlivé vrstvy zlyhania:

• dispatch bol úspešný,

• worker bol nájdený,

• argumenty boli odovzdané,

• upstream proces sa pokúsil spustiť,

• operácia skončila chybou,

• nevykonal sa build ani testy,

• nevznikol úspešný výsledok inšpekcie.

Presné pomenovanie vrstvy, na ktorej nastala chyba, dramaticky zjednodušuje debugging.

A keď následné opravy spôsobia, že celý tok začne fungovať, máme zároveň konkrétny dôkaz, že capability model nie je iba návrh na papieri.

Testovanie capability

Capability musí byť testovateľná bez manuálneho klikania v termináli.

Testy by mali pokrývať minimálne:

• validáciu argumentov,

• chýbajúci alebo neplatný pracovný adresár,

• zostavenie upstream príkazu,

• výber modelu,

• izoláciu environment premenných,

• úspešný exit,

• nenulový exit code,

• timeout,

• ukončenie child procesov,

• zápis journalu,

• emitovanie udalostí,

• read-only režim pre inspect,

• správanie pri nedostupnom upstream Codex CLI.

Jednotkové testy môžu overiť parsery, konfiguráciu a tvorbu príkazov.

Integračné testy môžu používať fake Codex executable, ktorý simuluje:

• úspech,

• chybu,

• pomalý výstup,

• nekonečný beh,

• spawn child procesu,

• poškodený alebo neštandardný výstup.

End-to-end test následne overí celý tok:

OS Layer dispatch
→ codex-worker
→ upstream Codex
→ udalosti
→ journal
→ výsledok

Práve testovateľnosť ukazuje, že nejde o ad hoc shell integráciu.

Prečo je to viac než CLI wrapper

Codex capability nepridáva nový model ani sa nesnaží nahradiť schopnosti upstream Codexu.

Pridáva systémové vlastnosti, ktoré samotný interaktívny klient nemusí riešiť:

• jednotný dispatch,

• explicitný execution contract,

• provider izoláciu,

• kontrolovaný working directory,

• sandbox a policy,

• timeouty,

• správu process tree,

• štruktúrované udalosti,

• journal,

• testovateľnosť,

• integráciu s ďalšími capabilities.

To je presne úloha OS Layer.

Nie je to ďalší agent, ktorý sedí nad agentom. Je to runtime vrstva, ktorá z nástroja určeného pre človeka pri termináli robí spoľahlivú stavebnú jednotku väčšieho systému.

Čo sa tým otvára

Keď Codex funguje ako capability, možno ho kombinovať s ďalšími časťami OS Layer.

Planner môže pripraviť úlohu. Codex môže preskúmať alebo upraviť repozitár. Approval vrstva môže zastaviť rizikovú operáciu. Audio capability môže oznámiť, že systém čaká na schválenie. Test runner môže overiť výsledok. Journal uchová celý priebeh.

Z izolovaného CLI tak vzniká komponent agentového operačného prostredia.

A to je hlavná pointa celej implementácie:

Codex zostáva Codexom. OS Layer z neho robí komponovateľnú, pozorovateľnú a policy-riadenú capability.

Nie wrapper.

Nie shell hack.

Capability.