Slovník

Základní entity

Agent: AI pracovník s identitou, rolí, skilly a adaptérem. Patří právě jednomu pracovnímu prostoru. Hlavní aktér v systému.

Adaptér: Runner, který provede tah agenta. Dodávají se dva: Control Center (built-in), harness v procesu, který mluví s poskytovateli modelů, a Claude Code přes claude -p. Cursor, Codex, Anthropic, OpenAI a ostatní jsou poskytovatelé na vestavěném adaptéru, ne samostatná CLI. Viz Spravujte adaptéry a modely.

Pracovní prostor: Nejvyšší tenant izolace. Sdružuje agenty, repozitáře, prostory, tickety, paměť a pipeline. Izolace je strukturální, ne jen dohodou: každý pracovní prostor má vlastní soubor SQLite (<dataDir>/<workspaceId>/workspace.db), takže čtení napříč pracovními prostory se nepřeloží. Každá trasa v aplikaci začíná /workspaces/:workspaceId. Viz mapa tras.

Hostitel kódu: GitHub, GitLab nebo Bitbucket Cloud. Je to vlastnost každého repozitáře, přečtená z remote origin při registraci, a vybere adaptér API a pověření toho repozitáře. Jeden pracovní prostor může držet repozitáře na všech třech; agregační plochy (doručená pošta, fronta PR) se rozběhnou přes každou zastoupenou forge a výsledky složí, přičemž selhání izolují, takže nedosažitelná forge nevyprázdní ostatní. Hostitelé se liší v tom, co umějí. Tabulka schopností je v Připojte hostitele kódu.

Repozitář: Git repozitář registrovaný v jednom pracovním prostoru. V rozsahu pracovního prostoru: stejný checkout registrovaný ve dvou pracovních prostorech jsou dva nezávislé řádky se dvěma id; identita repozitáře napříč pracovními prostory je cesta na souborovém systému, nikdy id. Registrace vyžaduje pracovní strom gitu, jehož remote origin míří na podporovaného hostitele kódu. Každý repozitář nese tu forge (github / gitlab / bitbucket), která vybere adaptér API a pověření použité pro něj.

Izolovaný repozitář: Worktree registrovaného repozitáře v rozsahu pracovního prostoru. Copy-on-write přes rift všude, kde se ta nativní knihovna dodává; git worktree na Windows. Připravuje se na prostor: všechny konverzace toho prostoru sdílejí jeden checkout, takže agenti zdroj nikdy nemění.

Prostor: Kontejner spolupráce v rozsahu pracovního prostoru, s lidskými i agentními účastníky, uloženým Mode, stavem přípravy a SpaceKind (topic / agentPeer / system / pr / slack), který rozhoduje, jak se řadí do sekcí, ztlumuje, označuje odznakem a uklízí. Vlastní izolované worktree, které jeho konverzace sdílejí (copy-on-write přes rift; git worktree na Windows).

Konverzace: Jeden proud zpráv uvnitř prostoru, s vlastním id, historií a kontextem běhu agenta. Konverzace v prostoru jsou si rovné: žádný primární ani „hlavní“ proud není. Každá se otevře jako záložka editoru; stav nepřečteného prostoru se sčítá přes všechny.

Vlákno: Konverzace, která má nastavené anchorMessageId: ukotvená k jedné zprávě sousední konverzace ve stejném prostoru, s čerstvým kontextem agenta nasazeným tou kotevní zprávou. Jen jedna úroveň: vlákno se nikdy neukotví k vláknu.

Ticket: Agregát jednotky práce. Nezávislý na dodavateli: ve výchozím stavu local, s adaptéry synchronizace pro Linear, GitHub Issues, Jira Cloud a ClickUp, třebaže žádná plocha v aplikaci spojení synchronizace nezaloží. Umí hierarchii, vazby a delegování. Přiřazení agentovi zapíše vlastnictví a nic neodešle; výjimkou je přiřazení týmu (TeamRoutingService odešle vedoucího).

Pipeline: Workflow na DAG, které řetězí kroky (odeslání agenta, skripty, podmínky). Definuje se šablonami a provádí se jako běhy.

Hodnotové objekty

AgentRole: Výčtová role (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Určuje personu, přístup k paměti a hierarchii.

AgentSkills: Množina identifikátorů skillů bez rozlišení velikosti písmen, která při odeslání vloží do promptů příslušný kontext.

Zdroj skillů: Repozitář na GitHubu registrovaný v pracovním prostoru jako katalog skillů. Nedůvěryhodný už z konstrukce: metadata repozitáře jsou jen k zobrazení a každá instalace projde bránou skenu, která se při selhání uzavře, než se jakýkoli obsah dostane na disk nebo do promptu. Viz Instalujte a spravujte skilly.

skills-lock.json: Manifest nainstalovaných skillů v pracovním prostoru: u každého zdrojový repozitář, cesta v repozitáři, commit, ke kterému je připnutý, a souhrnný hash obsahu. Instalace, aktualizace a odinstalace ho udržují aktuální; verify_skills ho porovná s diskem.

Brána běhů agentů: Loopback endpoint na cc_server, který uplatňuje politiku akcí uvnitř sandboxu agenta. Každý push agenta na GitHub se přesměruje na ni, zkontroluje proti pravidlu Odeslat na remote a předá se zapisovacím tokenem, který agent nikdy nedrží; příkazy Bash v Claude Code se kontrolují přes hook na stejném endpointu. Viz Sandbox a zabezpečení.

Režim: chat, plan, review nebo orchestrate. Ukládá se na prostor, takže jeden agent může být v různých prostorech v různých režimech; všechny konverzace prostoru ho sdílejí. Rozhoduje o systémovém promptu, pravidlech zápisu sandboxu a seznamu povolených nástrojů MCP. Composer nabízí jen chat, plan a orchestrate; chat má popisek „Agent“.

SandboxBackend: microvm (uzavřený virtuální stroj, jediný backend s hranicí jádra, použitý na interaktivní terminály), native (Seatbelt na macOS, bubblewrap na Linuxu a WSL2) nebo none. Při startu se osondá jednou; native se nasadí na odeslání agenta, když je k dispozici, a obalí CLI Claude Code i nástroj bash harnessu. Windows nativní backend nemá a Linux potřebuje bwrap a socat, takže tam běhy jdou bez obalu; --sandbox off ho vypne schválně.

Stanice: Jednorázový stroj, který agent řídí v reálném čase: uzavřený prohlížeč nebo linuxová plocha, emulátor Androidu nebo simulátor iOS spravovaný hostitelem, nebo uzavřený terminál. Sleduje se živě po vlastním kanálu v plném rozlišení a převzetí vynucuje server. V rozsahu konverzace, takže záložka člověka a volání browser_use / computer_use / mobile_use / ios_use míří na jeden výchozí stroj. Viz Stanice a izolovaná prostředí.

Izolované prostředí: Silnější hranice stanice na virtuálním stroji: hranice jádra, jednorázový překryvový disk, síťová brána s výchozím odmítnutím a broker přihlašovacích údajů. Stanice pro Android a iOS jsou jednorázové, ale síť jim spravuje hostitel a tuhle hranici nenárokují. Řízení jakékoli stanice používá třídu guardrailu enclosureControl.

RunCost: Součet tokenů a nákladů (vstupní tokeny, výstupní tokeny, odhadovaný náklad v centech) jednoho běhu agenta.

WakeReason: Proč se agent odeslal. Šest hodnot: zpráva uživatele, přiřazení ticketu, opětovné odeslání při obnově po selhání, dokončení dceřiného ticketu, naplánovaný kontrolní tep a krok pipeline.

Porty

SandboxPort: Řídí životní cyklus sandboxu (probe, launch, events, exec, destroy).

CredentialBrokerPort: Vystavuje vymezená pověření pro spuštění sandboxu — jen pro čtení do prostředí agenta, se zápisem jen pro cestu pushe na serveru — a při úklidu je odvolá.

GitRepoInspectorPort: Z cesty k místnímu Git repozitáři vytáhne metadata (vlastník, repozitář, větev).

EmbeddingPort: Vyrábí textové vektory embeddingu s jednotkovou normou pro sémantické vyhledávání.

NotificationPort: Ukazuje nativní oznámení na ploše a respektuje bránu podle kategorie a trasy.

TicketProviderPort: Hranice k backendu ticketů nezávislá na dodavateli (create, get, list, update, transition, assign).

PipelineEnginePort: Spustí běh pipeline ze šablony a volající se tím odpoutají od konkrétního enginu.

Doménové služby

AgentDispatchService: Spouští běhy agentů: připraví izolované repozitáře, složí prompty, založí záznamy běhů a vrátí živé streamy událostí.

TicketWorkflowService: Čistě doménový engine životního cyklu ticketu s úzkým místem mutací s optimistickou souběžností a vynucením izolace pracovního prostoru. Jeho graf přechodů váže jen agenty a automatizaci; změny z rozhraní, které řídí uživatel, předají force: true a obejdou ho. Dispečer ticketů pro agenta jako příjemce není: odeslání vlastní AgentDispatchService a přiřazení ticketu agentovi žádný běh nespustí. Výjimkou je přiřazení ticketu týmu (TeamRoutingService odešle vedoucího).

PipelineEngine: Řídí provedení běhu: běhy spouští, kroky plánuje, stav ukládá, obstarává routery, joiny a continue-on-fail a po restartu obnoví běhy, které byly v pohybu.

PipelineTriggerDispatcher: Odebírá doménové události a u zapnutých spouštěčů sám spustí odpovídající běhy pipeline.

MemoryAccessPolicy: Vyřeší a vynutí oprávnění role agenta k doménám paměti.

HarnessCostCalculator: Ocení spotřebu tokenů vestavěného harnessu na RunCost podle katalogu models.dev. Odeslání ten součet zapíše do záznamu běhu.

BudgetEnforcementService: Spočítá měsíční útratu agenta a blok před odesláním (checkInvocationBlock). Na ten blok sahají jen rekoncilery obnovy (OrphanRunReaper, StrandedTicketReconciler), nikdy běžné odeslání uživatelem nebo agentem.

BudgetGovernanceService: Po každém běhu vyhodnotí měsíční útratu agenta: měkký práh zapíše varovný incident; vyčerpání zapíše tvrdý incident a přepne životní cyklus agenta na paused.

Události

DomainEventBus: Procesní broadcastová sběrnice publish/subscribe pro komunikaci napříč doménami. Události jsou typované; odběratelé čtou streamy on<T>().

DomainEvent: Základní rozhraní. Každá událost má occurredAt. Hlavní kategorie: pracovní prostor/agent, PR/kontrola, zprávy, tickety, pipeline, schůzky/kalendář, identita, stanice, observabilita.

Schůzky a kalendář

Schůzka: Místně nahraná a přepsaná schůzka. Zachytí mikrofon i systémový zvuk, na zařízení ho přepíše volitelným modelem ASR (ve výchozím stavu Parakeet TDT v3; alternativy jsou Parakeet TDT v2, Whisper large-v3-turbo a Whisper base.en), diarizuje řečníky a shrne to do poznámek, akčních položek a rozhodnutí. Vybraný model ASR se při startu natvrdo doinstaluje a operace nahrávání se rozsvítí po jednom restartu. V rozsahu pracovního prostoru; zůstane na stroji.

MeetingSegment: Jedno přepsané okno zvuku, se značkou řečníka (me/them), štítkem diarizace a offsety v milisekundách.

MeetingActionItem / MeetingDecision: Strukturované výstupy, které vytáhne pipeline shrnutí a uloží je jako samostatné řádky. Akční položky se dají navázat na ticket.

CalendarEvent: Synchronizovaná položka Google Calendar v rozsahu pracovního prostoru a připojeného účtu. Od schůzky se liší: událost je naplánovaný závazek, schůzka je nahraná relace. Propojené jedna ku jedné přes MeetingCalendarLink.

CalendarAccount: Připojený účet Google, na pracovní prostor a e-mail. Obnovovací tokeny OAuth se ukládají na serveru jako klíče google_* v <dataDir>/secrets.json a ke klientovi se nikdy nedostanou; tok device code doběhne na serveru. Příznak authExpiredAt řídí banner Znovu připojit.

Architektonické pojmy

Clean Architecture: Pravidlo závislostí: Presentation → Application/Providers → Domain ← Infrastructure. Doména nemá žádné importy infrastruktury.

Porty a adaptéry: Doména definuje abstraktní rozhraní (porty); infrastruktura dodá konkrétní implementace (adaptéry). Sváže je kořen kompozice.

Sdílené jádro: Entity, hodnotové objekty, porty a služby v core/domain/ sdílené napříč třemi a více doménami.

Uspořádání podle domén: Kód je uspořádaný podle obchodní domény (agenti, pipeline, zprávy), ne podle technické vrstvy.

Multiplayer, identita a tempo

Principál: Zapečetěná hodnota, která sjednocuje lidi a agenty do jediné abstrakce aktéra: UserPrincipal(userId) nebo AgentPrincipal(agentId). Každá zpráva, ticket, kontrola, plán a záznam běhu se připisuje přes principála.

Uživatel: Lidská identita, uložená v global.db, a proto globální napříč pracovními prostory. Principál, který pracovní prostor založí, se stane jeho vlastníkem, zapsaným do Workspace.ownerUserId s řádkem členství v roli vlastníka v téže operaci. Ostatní se připojí pozvánkou nebo přes SSO.

WorkspaceMember / WorkspaceRole: Řádek členství, který váže uživatele k pracovnímu prostoru v roli (owner / admin / member / viewer / guest). Hranice přístupu je členství, ne párovací klíč. Oprávnění na repozitář drží členství v mezích forge.

ParticipantPresence: Pomíjivé povědomí o principálovi (stav, lokus, kurzor, psaní, živý stav agenta a běžící náklad). Nikdy se neukládá; soustředí ho server; před rozesláním se filtruje podle oprávnění k repozitáři.

Režim sledování: Klikni na avatar a jeď po jeho zobrazení, dokud nezasáhneš, a pak se sledování odpojí. Funguje pro lidi i pro agenty („sledovat, jak agent pracuje“).

Volič autonomie: Ovládání na prostor a na agenta, propose-only / act-with-approval / act-freely, pojmenovaný profil nad úložištěm guardrailů akcí.

ActionClass: Uzavřená sada 13 tříd účinku (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Každý mutující nástroj deklaruje své třídy; engine guardrailů vyřeší allow / prompt / deny podle rozsahu (prostor > agent > pracovní prostor > předvolba režimu > vestavěný výchozí).

WriteLedger / klíč idempotence: Každá mutace nese klíč idempotence, který vygeneruje klient (UUIDv7, na logickou akci). Kniha v rozsahu pracovního prostoru odstraní duplicitu dřív, než doběhne handler; opakování vrátí bajtově shodný původní výsledek. Znovupřipojení a víc klientů jsou tím bezpečné už z konstrukce.

Doručená pošta: Fronta napříč pilíři s přísným pravidlem: položka se objeví jen tehdy, když něco blokuje (agenta, sloučení, synchronizaci) nebo výslovně žádá operátora.

Plan Studio: Interaktivní plocha plánování: upravitelné plány jako typovaný DAG, s nákladem, časem a rizikem na krok a s částečným schválením.

Výpočet kontroly: Výpočet kontroly PR na serveru (kohorty odvozené z grafu, typované diagramy, vizuální diffy, diffy kontraktu API, brány po více osách), podávaný přes review_studio.* a složený do záložky Kontrola.

Prostor kontroly: Jediný podkladový prostor PR (režim review, druh pr), založený idempotentně a s PR svázaný přes ReviewSpaceAssociation. Každý recenzent do něj zapisuje zjištění, a právě proto jsou srovnatelná; jeho izolovaný worktree má PR vycheckoutovaný na jeho head.

Uzel kontroly: Strukturovaná jednotka zjištění AI kontroly: druh (bug, suggestion, recommendation, question, ticket), priorita P0–P3, trojice třídění kategorie, závažnost a úsilí, kotva na soubor a řádek, volitelná navržená oprava a skóre jistoty. Zapisuje se přes add_review_node; verdikt se počítá z uzlů, ne z textu.

Consensus-ready: Stav uzlu kontroly, ke kterému se dojde jen tehdy, když zjištění potvrdí jiný recenzent. Agent vlastní zjištění potvrdit nemůže. Tlačítko Zveřejnit na GitHub na záložce Kontrola odešle každé zbývající otevřené zjištění (selection: all_open); nástroj MCP publish_review_to_github má pořád výchozí jen zjištění potvrzená kolegou.

Úroveň kontroly: Politika pracovního prostoru (light, balanced, thorough), která nastavuje, kteří recenzenti se rozešlou (jen engineer; +qa+architect; +security+perf) a kde se vykreslí zjištění pod prahem. Zjištění nikdy nesmaže.

Osa kontroly: Jedna z pěti hodnoticích drah jedné kontroly: correctness, security a testGap ze zjištění recenzentů; visual a apiContract deterministicky. Osy s bránou se složí do verdiktu a umějí ho jen zpřísnit. Brána partial nebo unavailable verdikt podrží a dál ho nepustí.

Verdikt kontroly: ship, hold nebo block. Jakékoli zjištění P0 s jistotou ≥ 0.7 znamená Block; jakékoli jiné P0 nebo jakékoli P1 znamená Hold; jinak Ship. Selhání osy s bránou vynutí Block a zjištění ho nepřehlasují.

Flotila a evaly

cc_worker: Bezhlavá binárka vykonavatele flotily v čistém Dartu. Spáruje se s cc_server, ohlásí schopnosti hostitele, stahuje zapůjčené úlohy, provede je a streamuje události procesu zpátky. Nedrží žádný trvalý stav: jeden autoritativní server, N hloupých končetin.

JobSpec: Typovaná specifikace všeho, co se dá spustit (běh agenta, krok pipeline, index kódu, golden-render, benchmark, dávka eval).

Sada eval: Definice vyhodnocení v rozsahu pracovního prostoru (prompt, cílový agent a režim, hodnotitelé). Pět startovních sad se založí při vytvoření pracovního prostoru; vypíše je Observabilita → Kvalita.

Nasazení a klienti

Architektura tenkého klienta: Žádný klient neotevírá databázi; bezhlavý proces cc_server vlastní data a podává je přes WebSocket RPC. Každý klient (počítač, web, telefon) je vykreslovač nad tím jedním spojením RPC.

cc_server: Bezhlavá serverová binárka (čistý Dart, bez enginu Flutter). Vlastní databázi Drift/SQLite, podává repo-RPC přes WebSocket a běží v ní služby na pozadí (pipeline, MCP, rekoncilery).

ServerConnectionMode: Jak se počítač dostane ke svému serveru: local (na tomhle stroji spustí cc_server, to je výchozí) nebo remote (připojí se k serveru jinde). Webový klient je vždy remote.

RemoteRpcClient: Klient JSON-RPC nezávislý na transportu, kterým každý tenký klient mluví se svým serverem, přes WSS, loopback nebo zprostředkované relé.

Rozsah pracovního prostoru u každého volání: Server je bezstavový. Žádná vazba pracovního prostoru na relaci není, takže víc klientů na jednom serveru nikdy nesdílí „aktuální pracovní prostor“. Každé repo/call a sub/subscribe v rozsahu pracovního prostoru musí v argumentech nést workspace_id; chybějící nebo neregistrované id se odmítne dřív, než se otevře jakákoli databáze. Přístup pak hlídá členství a role v pracovním prostoru, ne relace.

cc_remote: Telefonní tenký klient, Flutter webová PWA, která na dálku ovládá flotilu přes zprostředkované relé, s politikou nástrojů s výchozím zákazem.

cc_signaling_server: Bezstavový zprostředkovatel WebSocket relé, který hostuje místnosti otevřené jen na pozvánku. Hloupé relé, které přeposílá jen rámce zapečetěné od konce ke konci, nedrží data aplikace a párovací PSK nikdy neuvidí.