diff --git a/docs/wiki/sl/agent-events-reference.md b/docs/wiki/sl/agent-events-reference.md new file mode 100644 index 0000000..1fc9a56 --- /dev/null +++ b/docs/wiki/sl/agent-events-reference.md @@ -0,0 +1,63 @@ +--- +title: Referenca agentskih dogodkov +description: Referenca dogodkov po opremi za zot in pi, preslikave Glasspane in preverjena polja prepisa. +--- + +← [kazalo](./index.md) + +Ta stran je kanonična referenca za vse vrste dogodkov JSONL, ki jih oddajata +zot in pi. Vsaka vrstica je en dogodek; vsak dogodek ima znano shemo. Glasspane +uporablja te preslikave za pretvorbo surovih dogodkov v prehode `AgentState`. + +## Skupna polja (vsi dogodki) + +Vsak agentski dogodek JSONL vsebuje ta polja: + +| Polje | Tip | Opis | +| ------------ | --- | ---------------------------------------------- | +| `event` | niz | Vrsta dogodka (npr. `agent_start`, `turn_end`) | +| `timestamp` | niz | Časovni žig ISO 8601 | +| `session_id` | niz | ID seje agenta | + +## Dogodki zot + +| Dogodek | Sprožilec | Preslikava Glasspane | +| ------------- | ------------------------------ | --------------------------------- | +| `turn_start` | Agent začne obdelovati korak | `Working` | +| `tool_call` | Agent pokliče orodje | (metapodatki, ne spremeni stanja) | +| `tool_result` | Orodje vrne rezultat | (metapodatki) | +| `done` | Agent konča korak uspešno | `Done` | +| `error` | Agent naleti na napako | `Error` | +| `blocked` | Agent čaka na operaterski vnos | `Blocked` | +| `agent_start` | Zagon agenta | `Working` | +| `usage` | Poročilo o uporabi žetonov | (metapodatki) | + +## Dogodki pi + +| Dogodek | Sprožilec | Preslikava Glasspane | +| -------------- | ------------------------------ | -------------------- | +| `agent_start` | Zagon agenta | `Working` | +| `turn_end` | Agent konča korak | `Done` | +| `agent_error` | Agent naleti na napako | `Error` | +| `blocked` | Agent čaka na operaterski vnos | `Blocked` | +| `usage_report` | Poročilo o uporabi žetonov | (metapodatki) | + +## Preverjena polja prepisa + +Ta polja so se pojavila v resničnem izhodu zot in so potrjena kot prisotna: + +| Polje | Vir | Opomba | +| ------------ | --- | ------------------------------------- | +| `turn_id` | zot | Enolični ID koraka | +| `model` | zot | Ime modela, uporabljenega za ta korak | +| `tokens_in` | zot | Število vhodnih žetonov | +| `tokens_out` | zot | Število izhodnih žetonov | +| `tool_name` | oba | Ime orodja, ki ga je agent poklical | + +→ `crates/colibri-glasspane/src/lib.rs` (`zot_event_type`, `PiJsonlIngestor`) +→ `crates/colibri-daemon/tests/zot_rpc_smoke.rs` + +## Glej tudi + +- [glasspane](./glasspane.md) — kako se dogodki preslikajo v stanja +- [agent-harness](./agent-harness.md) — razcep zot/Colibri diff --git a/docs/wiki/sl/external-mcp.md b/docs/wiki/sl/external-mcp.md new file mode 100644 index 0000000..0a9cc39 --- /dev/null +++ b/docs/wiki/sl/external-mcp.md @@ -0,0 +1,69 @@ +--- +title: Zunanji MCP +description: Most MCP za urejevalnike in zunanje gostitelje — branje, pisanje in vrata za zunanje klice prek Colibrijeve implementacije MCP. +--- + +← [kazalo](./index.md) + +Colibri izpostavlja podmnožico svoje krmilne ravnine kot strežnik MCP +(Model Context Protocol), tako da lahko zunanji urejevalniki (VS Code, +Zed), agentski okviri (Claude Code, Hermes) in skripte komunicirajo z +Colibrijem prek standardiziranega protokola. + +→ `crates/colibri-mcp/src/lib.rs` + +## Odločitve + +### stdio, ne HTTP + +Strežnik MCP komunicira prek standardnega vhoda/izhoda (stdio), ne prek +HTTP ali WebSocket. To je standardni prenos MCP — vsak odjemalec MCP ga +podpira. Prav tako se izogne potrebi po odprtju drugega omrežnega vmesnika. + +### Tri orodja, ne celoten API + +Strežnik MCP izpostavlja tri orodja: + +| Orodje | Ukaz demona | Namen | +| ------------------ | -------------------- | ----------------------------------------------- | +| `colibri_status` | `status` | Stanje demona (agenti, opravila, predpomnilnik) | +| `colibri_snapshot` | `glasspane-snapshot` | Trenutni posnetek podoken Glasspane | +| `colibri_spawn` | `spawn-agent` | Zaženi novega agenta | + +Ta tri orodja pokrivajo 90 % zunanjih interakcij. Celoten API vtičnice je na +voljo neposrednim odjemalcem vtičnice; MCP je priročna podmnožica. + +### Ovoj Bash, ne vgrajeni proces + +`colibri-mcp` je skripta Bash, ki se poveže na vtičnico demona, pošlje ukaz +JSON in vrne odgovor JSON. Ni dolgotrajen proces — vsak klic zažene novo +skripto. To pomeni, da je ničelna konfiguracija za odjemalce MCP (samo +registrirajte pot skripte) in ničelno vzdrževanje stanja. + +→ `packaging/freebsd/colibri-mcp` + +### Vrata za branje/pisanje in zunanje klice + +Implementacija MCP ločuje tri skrbi: + +- **Branje**: `status`, `snapshot` — samo za branje, vedno na voljo. +- **Pisanje**: `spawn` — spremeni stanje demona. Zaščiteno z zastavico + `allow_write` v konfiguraciji MCP. +- **Zunanji klic**: katerokoli orodje lahko sproži verigo MCP, ki sega + navzven do drugega strežnika MCP. Zaščiteno z zastavico `allow_external_call`. + +→ `crates/colibri-mcp/src/config.rs` + +### Inicializacijski manifest ob zagonu + +Vsak strežnik MCP mora ob zagonu vrniti manifest `initialize`. Colibrijev +manifest deklarira svoja tri orodja, zmogljivost `tools` in prazno +zmogljivost `resources`. Odjemalci, ki ne pokličejo `initialize`, dobijo +napako protokola. + +→ `crates/colibri-mcp/src/protocol.rs` (`initialize`) + +## Glej tudi + +- [mother-hive](./mother-hive.md) — MCP prek SSH za matično vozlišče +- [operator-cli](./operator-cli.md) — neposreden dostop do vtičnice diff --git a/docs/wiki/sl/jail-confinement.md b/docs/wiki/sl/jail-confinement.md new file mode 100644 index 0000000..7bfd6ce --- /dev/null +++ b/docs/wiki/sl/jail-confinement.md @@ -0,0 +1,44 @@ +--- +title: Omejitev ječ +description: Trajne proti prehodnim ječam, pravilnik načina priv in ponovna uporaba omejitve zaganjalnika za strežnike MCP. +--- + +← [kazalo](./index.md) + +Colibrijevi agenti tečejo znotraj ječ FreeBSD Bastille. Model omejitve je +zasnovan tako, da so vse agentske interakcije privzeto zaprte, izrecne +priklopne točke pa namerne. + +→ `packaging/freebsd/bastille/` + +## Odločitve + +### Trajne ječe za agente, prehodne za MCP + +Agenti tečejo v **trajnih** ječah (eni na agenta), ki preživijo ponovne +zagone. Te ječe imajo stanje: nameščene pakete, konfiguracijske datoteke, +klonirane repozitorije. Strežniki MCP tečejo v **prehodnih** ječah, ustvarjenih +iz iste predloge, a uničenih, ko se seja MCP konča. Prehodne ječe se začnejo +sveže — brez stanja, brez ostankov. + +→ `crates/colibri-daemon/src/spawner.rs` + +### Pravilnik načina priv — `enforce_statfs=1`, brez `allow.mount` + +Vse ječe delijo privzeti pravilnik, ki prepoveduje priklope, surova vtičnice, +spreminjanje lastništva in dostop do naprav. Vsaka priklopna točka, ki jo +agent potrebuje (repozitoriji, vtičnica demona, imeniki stanja), je izrecno +navedena v konfiguraciji Bastille. + +### Ista omejitev zaganjalnika za MCP kot za agente + +Ko se zažene strežnik MCP, uporabi isti mehanizem spawnanja v ječi kot +agenti. Predloga ječe (`clawdie-mcp`), konfiguracija Bastille, pravilnik +načina priv in uporabnik so enaki. Edina razlika: ječa ni trajna. + +→ `crates/colibri-mcp/src/lib.rs` + +## Glej tudi + +- [deployment](./deployment.md) — postavitev ZFS za ječe +- [vault-provision](./vault-provision.md) — oskrba okolja znotraj ječ diff --git a/docs/wiki/sl/runtime-inventory.md b/docs/wiki/sl/runtime-inventory.md new file mode 100644 index 0000000..825dfeb --- /dev/null +++ b/docs/wiki/sl/runtime-inventory.md @@ -0,0 +1,48 @@ +--- +title: Popis izvajalnega okolja +description: Bralnik stanja gostitelja — aditivne, bralne integracije, ki zbirajo različice OS, paketov in izvajalnega okolja. +--- + +← [kazalo](./index.md) + +Bralnik popisa izvajalnega okolja je aditivna, bralna plast: bere dejstva o +gostitelju, ne da bi karkoli spremenil. Je vhod za razporejevalnik (ali lahko +ta gostitelj izvede opravilo?) in za matični register (kaj ta gostitelj je?). + +→ `crates/colibri-runtime-inventory/src/lib.rs` + +## Odločitve + +### Aditivno, ne konfiguracijsko + +Bralnik odkrije dejstva, ne uveljavlja stanja. Če manjka `pi` ali `zot`, to +zabeleži — ne namesti. Če je prisotnih več različic Node.js, jih navede vse. +Če je ZFS odklopljen, to zabeleži — ne uvozi bazena. Operater se odloči, kaj +storiti s popisom. + +### Bralni vmesnik, specifičen za platformo + +`HostInfo` je skupen struct. Vsaka platforma implementira `HostReader` trait. +FreeBSD-jev bralnik uporablja `pkg`, `sysctl`, `zfs`, `kldstat` in `pciconf`. +Linuxov bralnik uporablja `uname`, `/proc`, `lsblk` in `lspci`. Skupna +struktura pomeni, da razporejevalnik in mati vidita isto obliko ne glede na +OS. + +→ `crates/colibri-runtime-inventory/src/platform.rs` + +### Rezultat je JSON, konzumirajo ga trije porabniki + +Popis se serializira v `clawdie.runtime-version-inventory.v1`. Trije porabniki: + +- **Razporejevalnik**: ujemanje zmožnosti (`"can_run_local_llm": true`). +- **Mati**: register hive (`"hostname": "domedog"`, `"os": "linux"`). +- **Operater**: ukaz `colibri runtime-inventory`. + +### Brez pisanja — integracije so samo za branje + +Bralnik ne piše v podatkovno zbirko, ne spreminja konfiguracije in ne +spreminja stanja demona. Je čista funkcija `HostReader::read() → HostInfo`. +To pomeni, da je varno zagnati ga v cronu, ob zagonu ali ročno brez stranskih +učinkov. + +→ [contracts](./contracts.md) (shema) | [mother-hive](./mother-hive.md) diff --git a/docs/wiki/sl/skills-catalog.md b/docs/wiki/sl/skills-catalog.md new file mode 100644 index 0000000..151c5b3 --- /dev/null +++ b/docs/wiki/sl/skills-catalog.md @@ -0,0 +1,45 @@ +--- +title: Katalog veščin +description: Bralni izvajalni porabnik za pregledane artefakte veščin Clawdie-AI — uvozi SKILL.md v Colibrijevo tabelo skills. +--- + +← [kazalo](./index.md) + +Katalog veščin je Colibrijev bralni izvajalni porabnik za veščine, +pregledane v repozitoriju `clawdie-ai`. Veščine se uvozijo v tabelo +`skills` v shrambi SQLite, kjer jih agenti poizvedujejo med izvajanjem. + +→ `scripts/import-clawdie-skills.sh` + +## Odločitve + +### Bralni porabnik, ne vir resnice + +Colibri bere veščine iz repozitorija `clawdie-ai` — ta je vir. Uvozna +skripta je idempotentna (`INSERT OR IGNORE`), zato je varno večkrat +zagnati. Spremembe veščin se zgodijo v izvornem repozitoriju, nato se +ponovno uvozijo. + +→ [layered-soul](./layered-soul.md) (enaka smer) + +### Ena tabela, ploščata + +Vse veščine si delijo eno tabelo `skills` s stolpci `name`, `description`, +`category` in `created_at`. Kategorija je prosta besedilna oznaka +(`"soul"`, `"agent"`, `"channel"`). Brez gnezdenja, brez različic, brez +odvisnosti med veščinami. To ustreza trenutnemu obsegu (~50 veščin). + +→ `crates/colibri-store/src/schema.rs` + +### Uvoz ob zagonu, ne sproti + +Veščine se uvozijo ob zagonu demona, ne med izvajanjem. Če operater doda +veščino, ponovno zažene demona (ali ročno zažene uvozno skripto). Nobena pot +izvajalne kode ne piše v tabelo `skills`. + +→ `scripts/import-clawdie-skills.sh` + +## Glej tudi + +- [layered-soul](./layered-soul.md) — veščine iz layered-soul +- [store-schema](./store-schema.md) — shema tabele skills diff --git a/docs/wiki/sl/vault-provision.md b/docs/wiki/sl/vault-provision.md new file mode 100644 index 0000000..51429b7 --- /dev/null +++ b/docs/wiki/sl/vault-provision.md @@ -0,0 +1,49 @@ +--- +title: Oskrba trezorja +description: Oskrba datotek env, gnana z Vaultwarden, v ječe po zagonu agenta — preslikava najemnik → ječa → zbirka. +--- + +← [kazalo](./index.md) + +`colibri-vault` bere skrivnosti iz Vaultwarden in jih zapiše kot datoteke +okolja (`.env`) znotraj ječ, preden se agent zažene. Vsak najemnik dobi +svojo datoteko `.env` s točno tistimi poverilnicami, ki jih potrebuje — +nič več. + +→ `crates/colibri-vault/src/lib.rs` + +## Odločitve + +### 1:1:1 preslikava — najemnik = ječa = zbirka + +Preslikava `tenant_id → ime ječe → zbirka Vaultwarden` je nespremenljiva. +Ukaz `colibri vault-provision ` poišče vrstico najemnika v SQLite, +pridobi vse skrivnosti iz imenovane zbirke Vaultwarden in jih zapiše v +`/tmp/.env` znotraj ječe. + +### CLI Vaultwarden (`bw`), ne API + +Oskrbnik uporablja `bw` (uradni CLI Vaultwarden/Bitwarden). seja `bw` se +odpre s ključem API, ki je shranjen kot skrivnost v `bw_session`, in zapre +po vsakem zagonu oskrbe. Brez trajnih sej, brez predpomnjenih žetonov. + +→ `crates/colibri-vault/src/vaultwarden.rs` + +### Skrivnosti so začasne znotraj ječe + +Datoteka `.env` je zapisana v `/tmp/.env` — obstojna samo toliko časa, +kolikor živi ječa. Če je ječa uničena in ponovno ustvarjena, oskrbnik +znova zažene. Skrivnosti niso nikoli shranjene na gostitelju. + +### Oskrba ob zagonu agenta, ne periodično + +Oskrba teče enkrat, tik preden se agent zažene znotraj ječe. Brez cron +osveževanj, brez rotacije skrivnosti med izvajanjem. Če se skrivnost spremeni, +operater ustavi in znova zažene agenta. + +→ `crates/colibri-daemon/src/socket.rs` (`cmd_spawn_agent`) + +## Glej tudi + +- [store-schema](./store-schema.md) — preslikava `tenants` +- [jail-confinement](./jail-confinement.md) — kako so ječe ustvarjene