Glosar

Entități principale

Agent: Un lucrător IA cu identitate, rol, skill-uri și un adaptor. Aparține exact unui singur spațiu de lucru. Actorul principal al sistemului.

Adaptor: Runner-ul care execută un tur de agent. Două sunt livrate: Control Center (built-in) — harness-ul în proces care vorbește cu furnizorii de modele — și Claude Code prin claude -p. Cursor, Codex, Anthropic, OpenAI și restul sunt furnizori pe adaptorul integrat, nu CLI-uri separate. Vezi Gestionează adaptoarele și modelele.

Spațiu de lucru: Chiriașul de izolare de nivel superior. Grupează agenți, repo-uri, spații, tichete, memorie și pipeline-uri. Izolarea este structurală, nu convențională: fiecare spațiu de lucru are propriul fișier SQLite (<dataDir>/<workspaceId>/workspace.db), așa că o citire între spații de lucru nu se compilează. Fiecare rută din aplicație este prefixată cu /workspaces/:workspaceId — vezi harta de rute.

Forge: Un host de cod — GitHub, GitLab sau Bitbucket Cloud. Forge-ul este o proprietate a fiecărui repo, citită din remote-ul origin la înregistrare, și selectează adaptorul de API și credențialul acelui repo. Un spațiu de lucru poate găzdui repo-uri pe toate cele trei; suprafețele de agregare (inbox-ul, coada de PR-uri) se distribuie către fiecare forge reprezentat și îmbină rezultatele, izolând eșecurile, astfel încât un forge inaccesibil nu le golește niciodată pe celelalte. Forge-urile diferă prin ce acceptă — vezi tabelul de capabilități din Conectează un host de cod.

Repo: Un depozit Git înregistrat într-un singur spațiu de lucru. Limitat la spațiul de lucru — același checkout înregistrat în două spații de lucru înseamnă două rânduri independente cu două id-uri; identitatea unui repo între spații de lucru se stabilește după calea din sistemul de fișiere, niciodată după id. Înregistrarea cere un arbore de lucru git al cărui remote origin indică spre un forge acceptat. Fiecare repo poartă acel forge (github / gitlab / bitbucket), care selectează adaptorul de API și credențialul folosite pentru el.

Repo izolat: Un worktree limitat la spațiul de lucru, derivat dintr-un repo înregistrat. Copy-on-write prin rift oriunde este livrat acel nativ; git worktree pe Windows. Provisionat per spațiu — fiecare conversație din acel spațiu partajează un singur checkout — așa că agenții nu modifică niciodată sursa.

Spațiu: Un container de colaborare limitat la spațiul de lucru, cu participanți umani și agenți, un Mode persistat, stare de provisionare și un SpaceKind (topic / agentPeer / system / pr / slack) care decide cum este secționat, pus pe mut, marcat cu insignă și colectat de gunoi. Deține worktree-urile izolate pe care le partajează conversațiile lui (copy-on-write prin rift; git worktree pe Windows).

Conversație: Un flux de mesaje în interiorul unui Spațiu, cu id, istoric și context de rulare a agentului proprii. Conversațiile dintr-un spațiu sunt egale și plate — nu există un flux primar sau „main”. Fiecare se deschide ca filă de editor; starea de necitit a unui spațiu le agregă pe toate.

Fir: O Conversație al cărei anchorMessageId este setat: ancorată la un mesaj al unei conversații surori din același Spațiu, cu un context de agent nou, inițializat de acel mesaj de ancorare. Un singur nivel de adâncime — firele nu se ancorează niciodată în fire.

Tichet: Agregatul unității de muncă. Neutru față de furnizor: local implicit, cu adaptoare de sincronizare pentru Linear, GitHub Issues, Jira Cloud și ClickUp — deși nicio suprafață din aplicație nu creează o conexiune de sincronizare. Acceptă ierarhie, legături și delegare. Atribuirea către un agent consemnează proprietatea și nu trimite nimic; atribuirea către o echipă este excepția (TeamRoutingService îl trimite pe lider).

Pipeline: Un flux de lucru bazat pe DAG care înlănțuie pași (trimitere de agent, scripturi, condiții). Definit prin șabloane; executat sub formă de rulări.

Obiecte-valoare

AgentRole: Rol enumerat (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Determină persona, accesul la memorie și ierarhia.

AgentSkills: Set de identificatori de skill-uri, insensibil la majuscule, care injectează contextul relevant în prompturi în momentul trimiterii.

Sursă de skill-uri: Un depozit GitHub înregistrat per spațiu de lucru ca catalog de skill-uri. Considerat nefiabil prin construcție: metadatele depozitului sunt doar pentru afișare, iar fiecare instalare trece poarta de scanare cu refuz implicit înainte ca vreun conținut să ajungă pe disc sau într-un prompt. Vezi instalează și gestionează skill-uri.

skills-lock.json: Manifestul per spațiu de lucru al skill-urilor instalate: pentru fiecare, depozitul sursă, calea în depozit, commit-ul la care este fixat și un hash de conținut cumulat. Instalările, actualizările și dezinstalările îl țin la curent; verify_skills îl verifică față de disc.

Gateway-ul rulărilor de agenți: Un punct final de loopback pe cc_server care aplică politica de acțiuni în interiorul sandbox-ului unui agent. Fiecare push GitHub făcut de un agent este redirecționat către el, verificat cu regula Push către un remote și transmis cu un token de scriere pe care agentul nu îl deține niciodată; comenzile Bash ale Claude Code sunt verificate printr-un hook pe același punct final. Vezi Sandbox și securitate.

Mode: chat, plan, review sau orchestrate. Stocat per spațiu, așa că un agent poate fi în moduri diferite în spații diferite; fiecare conversație dintr-un spațiu îl partajează. Controlează promptul de sistem, regulile de scriere ale sandbox-ului și lista de instrumente MCP permise. Compozitorul oferă doar chat, plan și orchestrate; chat este etichetat „Agent”.

SandboxBackend: microvm (o VM închisă — singurul backend cu graniță de kernel, aplicat terminalelor interactive), native (Seatbelt pe macOS, bubblewrap pe Linux și WSL2) sau none. Detectat o singură dată la pornire; native este aplicat la trimiterea agenților când este disponibil, înfășurând CLI-ul Claude Code și instrumentul bash al harness-ului. Windows nu are backend nativ, iar Linux are nevoie de bwrap plus socat, așa că rulările de acolo rămân neînfășurate; --sandbox off renunță deliberat.

Stație: O mașină de unică folosință pe care un agent o conduce în timp real — un browser sau un desktop Linux închis, un emulator Android ori un simulator iOS administrat de gazdă, sau un terminal închis. Urmărită live prin propria bandă la rezoluție completă, cu preluarea controlului impusă pe server. Limitată la o conversație, așa că fila umană și apelurile browser_use / computer_use / mobile_use / ios_use ale agentului vizează o singură mașină implicită. Vezi Stații și medii izolate.

Mediu izolat: Granița mai puternică a stațiilor sprijinite de VM — o graniță de kernel, disc suprapus de unică folosință, poartă de rețea cu refuz implicit și broker de credențiale. Stațiile Android și iOS sunt de unică folosință, dar folosesc rețeaua administrată de gazdă și nu revendică această graniță. Conducerea oricărei stații folosește clasa de guardrail enclosureControl.

RunCost: Total de tokeni/cost (tokeni de intrare, tokeni de ieșire, cost estimat în cenți) pentru o singură rulare de agent.

WakeReason: Motivul pentru care a fost trimis un agent. Șase valori: mesaj de la utilizator, atribuire de tichet, retrimitere de recuperare după un eșec, tichet copil finalizat, semnal periodic de continuare programat și pas de pipeline.

Porturi

SandboxPort: Gestionează ciclul de viață al sandbox-ului (detectare, lansare, evenimente, exec, distrugere).

CredentialBrokerPort: Emite credențiale limitate pentru lansarea sandbox-ului — doar pentru citire în mediul unui agent, cu scriere doar pentru calea de push de pe server — și le revocă la demolarea lui.

GitRepoInspectorPort: Extrage metadate (proprietar, repo, ramură) dintr-o cale locală de repo Git.

EmbeddingPort: Produce vectori de embedding de text cu normă unitară pentru căutarea semantică.

NotificationPort: Afișează notificări native de desktop, respectând filtrarea pe categorii și rute.

TicketProviderPort: Graniță independentă de furnizor către un backend de tichete (creare, citire, listare, actualizare, tranziție, atribuire).

PipelineEnginePort: Pornește o rulare de pipeline dintr-un șablon, decuplând apelanții de motorul concret.

Servicii de domeniu

AgentDispatchService: Lansează rulări de agent: provisionează repo-uri izolate, construiește prompturi, creează jurnale de rulare, returnează fluxuri de evenimente live.

TicketWorkflowService: Motor de ciclu de viață al tichetelor, pur de domeniu, cu un punct unic de trecere pentru mutații cu concurență optimistă și cu impunerea izolării spațiilor de lucru. Graful de tranziții pe care îl impune leagă doar agenții și automatizarea; modificările din interfață făcute de utilizator trec force: true și îl ocolesc. Nu există niciun dispecer de tichete pentru un agent desemnat — AgentDispatchService deține trimiterea, iar atribuirea unui tichet unui agent nu pornește nicio rulare. Atribuirea unui tichet unei echipe este excepția (TeamRoutingService îl trimite pe lider).

PipelineEngine: Orchestrează execuția rulărilor: pornește rulări, programează pași, persistă starea, gestionează routere, îmbinări și continuarea la eșec, reia rulările în curs după repornire.

PipelineTriggerDispatcher: Se abonează la evenimente de domeniu și pornește automat rulările de pipeline corespunzătoare pentru trigger-ele activate.

MemoryAccessPolicy: Rezolvă și impune permisiunile de memorie ale rolului de agent pe domenii.

HarnessCostCalculator: Evaluează costul utilizării de tokeni a harness-ului integrat într-un RunCost, pe baza catalogului models.dev. Trimiterea persistă acel total în jurnalul rulării.

BudgetEnforcementService: Calculează cheltuiala lunară per agent și un blocaj pre-trimitere (checkInvocationBlock). Acel blocaj este consultat doar de reconciliatorii de recuperare (OrphanRunReaper, StrandedTicketReconciler), niciodată de o trimitere obișnuită a unui utilizator sau a unui agent.

BudgetGovernanceService: Evaluează cheltuiala lunară per agent după fiecare rulare — un prag soft înregistrează un incident de avertizare; epuizarea înregistrează un incident sever și comută ciclul de viață al agentului în paused.

Evenimente

DomainEventBus: Magistrală de publicare/abonare cu difuzare în proces, pentru comunicarea între funcționalități. Evenimentele sunt tipizate; abonații consumă fluxuri on<T>().

DomainEvent: Interfața de bază. Fiecare eveniment are occurredAt. Categorii principale: spațiu de lucru/agent, PR/revizuire, mesagerie, tichete, pipeline, întâlniri/calendar, identitate, stații, observabilitate.

Întâlniri și calendar

Întâlnire: O sesiune de întâlnire înregistrată și transcrisă local. Capturează microfonul și audio-ul de sistem, transcrie pe dispozitiv cu un model ASR selectabil (Parakeet TDT v3 implicit; Parakeet TDT v2, Whisper large-v3-turbo și Whisper base.en sunt alternative), diarizează vorbitorii și rezumă în notițe, elemente de acțiune și decizii. Modelul ASR selectat este instalat forțat la pornire, iar operațiile de înregistrare devin active după o repornire. Limitat la spațiul de lucru; rămâne pe mașină.

MeetingSegment: O fereastră transcrisă de audio, etichetată după vorbitor (me/them), cu o etichetă de diarizare și decalaje în milisecunde.

MeetingActionItem / MeetingDecision: Rezultate structurate extrase de pipeline-ul de rezumare și stocate ca rânduri distincte. Elementele de acțiune se pot lega de un tichet.

CalendarEvent: O intrare sincronizată din Google Calendar, limitată la un spațiu de lucru și un cont conectat. Diferită de o Întâlnire: un eveniment este o obligație programată; o Întâlnire este o sesiune înregistrată. Legate unu-la-unu printr-un MeetingCalendarLink.

CalendarAccount: Un cont Google conectat, per spațiu de lucru și e-mail. Tokenurile de reîmprospătare OAuth sunt stocate pe server ca chei google_* în <dataDir>/secrets.json și nu ajung niciodată la un client; fluxul de cod de dispozitiv se încheie pe server. Un indicator authExpiredAt declanșează bannerul de reconectare.

Termeni de arhitectură

Clean Architecture: Regula dependențelor: Presentation → Application/Providers → Domain ← Infrastructure. Domeniul nu are nicio importare din infrastructură.

Porturi și adaptoare: Domeniul definește interfețe abstracte (porturi); infrastructura oferă implementări concrete (adaptoare). Rădăcina de compunere le leagă.

Kernel partajat: Entități, obiecte-valoare, porturi și servicii din core/domain/, partajate de 3+ funcționalități.

Feature-first: Codul este organizat pe domenii de business (agenți, pipeline-uri, mesagerie), nu pe straturi tehnice.

Multiplayer, identitate și viteză

Principal: O valoare sigilată care unifică oamenii și agenții într-o singură abstracție de actor — UserPrincipal(userId) sau AgentPrincipal(agentId). Fiecare mesaj, tichet, revizuire, plan și jurnal de rulare se atribuie printr-un Principal.

Utilizator: O identitate umană, stocată în global.db și deci globală între spațiile de lucru. Principalul care creează un spațiu de lucru devine proprietarul lui — marcat pe Workspace.ownerUserId cu un rând de apartenență cu rol de proprietar, în aceeași operațiune. Ceilalți se alătură prin invitație sau SSO.

WorkspaceMember / WorkspaceRole: Un rând de apartenență care leagă un Utilizator de un Spațiu de lucru la un rol (owner / admin / member / viewer / guest). Apartenența — nu o cheie de asociere — este granița de acces. Acordările per repo împiedică apartenența să acorde mai multe privilegii decât forge-ul.

ParticipantPresence: Prezență efemeră pentru un Principal (stare, loc, cursor, tastare, starea live și costul de rulare ale unui agent). Niciodată persistată; găzduită pe server; filtrată după acordările per repo înainte de difuzare.

Mod urmărire: Dă clic pe un avatar ca să îi urmărești viewportul până când acționezi, apoi te detașezi. Funcționează pentru oameni și pentru agenți („urmărește un agent la lucru”).

Cadran de autonomie: Un control per spațiu și per agent — propose-only / act-with-approval / act-freely — implementat ca profil numit peste depozitul de guardrail-uri de acțiune.

ActionClass: Un set închis de 13 clase de efecte (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Fiecare instrument care modifică ceva își declară clasele; motorul de guardrail-uri rezolvă allow / prompt / deny per domeniu de aplicare (space > agent > workspace > mode preset > built-in default).

WriteLedger / cheie de idempotență: Fiecare mutație poartă o cheie de idempotență generată de client (UUIDv7, per acțiune logică). Registrul limitat la spațiul de lucru deduplică înainte de a rula handlerul; o reluare returnează rezultatul original, identic octet cu octet. Face reconectarea și lucrul cu mai mulți clienți sigur prin construcție.

Inbox „Needs me”: O coadă transversală, cu o regulă strictă — un element apare doar dacă blochează ceva (un agent, o îmbinare, o sincronizare) sau cere explicit operatorul.

Plan Studio: Suprafața interactivă de planificare — planuri DAG tipizate și editabile, cu cost, timp și risc per pas, și aprobare parțială.

Calculul revizuirii: Calcul de revizuire pe server pentru un PR (cohorte derivate din graf, diagrame tipizate, diff-uri vizuale, diff-uri de contract API, porți pe mai multe axe) servit prin review_studio.* și inclus în tab-ul Revizuire.

Spațiu de revizuire: Singurul spațiu suport al unui PR (mod review, tip pr), creat idempotent și legat de PR printr-un ReviewSpaceAssociation. Fiecare recenzent își depune constatările acolo, ceea ce le face comparabile; worktree-ul lui izolat are PR-ul verificat la vârful lui.

Nod de revizuire: Unitatea structurată a unei constatări din revizuirea IA: tip (bug, suggestion, recommendation, question, ticket), prioritate P0–P3, un triplu de triaj categorie/severitate/efort, o ancoră pe fișier și linie, o corecție sugerată opțională și un scor de încredere. Depus cu add_review_node; verdictul se calculează din noduri, nu din proză.

Consensus-ready: Starea unui nod de revizuire atinsă doar când un recenzent coleg confirmă o constatare — un agent nu se poate confirma singur. Butonul Publică pe GitHub din tab-ul Revizuire trimite toate constatările deschise rămase (selection: all_open); instrumentul MCP publish_review_to_github încă trimite implicit doar constatările confirmate de colegi.

Nivel de revizuire: Politică la nivel de spațiu de lucru (light, balanced, thorough) care reglează ce recenzenți sunt distribuiți (doar inginer; +qa+arhitect; +securitate+performanță) și unde apar constatările sub prag. Nu șterge niciodată o constatare.

Axă de revizuire: Una dintre cele cinci benzi de punctaj per revizuire: correctness, security și testGap provin din constatările recenzenților; visual și apiContract sunt deterministe. Axele cu poartă se includ în verdict și îl pot face doar mai sever — o poartă partial sau unavailable ține verdictul în loc să îl aprobe.

Verdict de revizuire: ship, hold sau block. Orice constatare P0 cu încredere ≥ 0,7 blochează; orice altă P0 sau orice P1 ține; în rest, ship. O axă cu poartă care eșuează forțează block și nu poate fi contrazisă la vot de constatări.

Flotă și eval-uri

cc_worker: Un binar executant de flotă, headless, în Dart pur. Se asociază cu un cc_server, își declară capabilitățile gazdei, preia joburi închiriate, le execută și transmite înapoi evenimente de proces. Nu deține nicio stare durabilă — un server autoritar, N membre simple.

JobSpec: Specificația tipizată pentru tot ce este executabil (rulare de agent, pas de pipeline, index de cod, randare de referință, benchmark, lot de eval-uri).

Suită eval: O definiție de evaluare limitată la spațiul de lucru (prompt, agent și mod țintă, evaluatori). Cinci suite de pornire sunt inserate la crearea spațiului de lucru; Observabilitate → Calitate le listează.

Implementare și clienți

Arhitectură cu client subțire: Niciun client nu deschide baza de date; un proces cc_server headless deține datele și le servește prin RPC pe WebSocket. Fiecare client (desktop, web, telefon) este un renderer peste acea singură conexiune RPC.

cc_server: Binarul de server headless (Dart pur, fără motor Flutter). Deține baza de date Drift/SQLite, servește repo-RPC prin WebSocket și rulează serviciile din fundal (pipeline-uri, MCP, reconciliatori).

ServerConnectionMode: Cum ajunge desktopul la serverul lui — local (pornește un cc_server pe această mașină, implicit) sau remote (conectează-te la unul de altundeva). Clientul web este mereu remote.

RemoteRpcClient: Clientul JSON-RPC independent de transport pe care îl folosește fiecare client subțire pentru a vorbi cu serverul — prin WSS, loopback sau releul intermediat.

Delimitare per apel pe spațiul de lucru: Serverul este fără stare — nu există o legătură de spațiu de lucru per sesiune, așa că mai mulți clienți de pe un server nu partajează niciodată un „spațiu de lucru curent”. Fiecare repo/call și sub/subscribe limitat la spațiul de lucru trebuie să poarte workspace_id în argumentele lui; un id lipsă sau neînregistrat este refuzat înainte de a se deschide vreo bază de date. Accesul este apoi filtrat după apartenența la spațiul de lucru și după rol, nu după sesiune.

cc_remote: Clientul subțire de telefon — o PWA Flutter web care controlează de la distanță flota prin releul intermediat, cu o politică de instrumente cu refuz implicit.

cc_signaling_server: Un broker releu WebSocket fără stare, care găzduiește camere cu acces pe bază de invitație — un releu simplu: transmite doar cadre sigilate end-to-end, nu deține date de aplicație și nu vede niciodată PSK-ul de asociere.