Glossario

Entità principali

Agente: Un lavoratore IA con un’identità, un ruolo, delle skill e un adattatore. Appartiene esattamente a uno spazio di lavoro. L’attore principale del sistema.

Adattatore: L’esecutore che esegue un turno di un agente. Ne vengono forniti due: Control Center (built-in) — l’harness in-process che parla con i fornitori di modelli — e Claude Code tramite claude -p. Cursor, Codex, Anthropic, OpenAI e gli altri sono fornitori sull’adattatore integrato, non CLI separate. Vedi Gestisci adapter e modelli.

Spazio di lavoro: Il tenant di isolamento di primo livello. Raggruppa agenti, repository, spazi, ticket, memoria e pipeline. L’isolamento è strutturale, non convenzionale: ogni spazio di lavoro ha il proprio file SQLite (<dataDir>/<workspaceId>/workspace.db), quindi una lettura tra spazi di lavoro non compila. Ogni route dell’app è prefissata con /workspaces/:workspaceId — vedi la mappa delle route.

Forge: Un host di codice — GitHub, GitLab o Bitbucket Cloud. La forge è una proprietà di ogni repository, letta dal suo remote origin al momento della registrazione, e seleziona l’adattatore API e la credenziale di quel repository. Uno spazio di lavoro può contenere repository su tutte e tre; le superfici aggregate (la posta in arrivo, la coda delle PR) si distribuiscono su ogni forge rappresentata e fondono i risultati, isolando i guasti così che una forge irraggiungibile non svuoti mai le altre. Le forge differiscono per ciò che supportano — vedi la tabella delle capacità in Collega un host di codice.

Repository: Un repository Git registrato dentro uno spazio di lavoro. Con ambito di spazio di lavoro — lo stesso checkout registrato in due spazi di lavoro sono due righe indipendenti con due id; l’identità di un repository tra spazi di lavoro è data dal percorso nel filesystem, mai dall’id. La registrazione richiede un git work tree il cui remote origin punti a una forge supportata. Ogni repository porta con sé quella forge (github / gitlab / bitbucket), che seleziona l’adattatore API e la credenziale usati per esso.

Repository isolato: Un worktree con ambito di spazio di lavoro di un repository registrato. Copy-on-write tramite rift ovunque quel native sia fornito; git worktree su Windows. Predisposto per spazio — ogni conversazione di quello spazio condivide un solo checkout — così gli agenti non modificano mai la sorgente.

Spazio: Un contenitore di collaborazione con ambito di spazio di lavoro, con partecipanti umani e agenti, una Mode memorizzata, lo stato di predisposizione e uno SpaceKind (topic / agentPeer / system / pr / slack) che decide come viene suddiviso in sezioni, silenziato, etichettato con un badge e sottoposto a garbage collection. Possiede i worktree isolati che le sue conversazioni condividono (copy-on-write tramite rift; git worktree su Windows).

Conversazione: Un flusso di messaggi dentro uno Spazio, con id, cronologia e contesto di esecuzione dell’agente propri. Le conversazioni di uno spazio sono pari e appiattite — non esiste un flusso primario o «principale». Ognuna si apre come scheda dell’editor; lo stato non letto di uno spazio le aggrega tutte.

Thread: Una conversazione il cui anchorMessageId è impostato: ancorata a un messaggio di una conversazione sorella nello stesso Spazio, con un contesto agente nuovo seminato da quel messaggio di ancoraggio. Un solo livello di profondità — i thread non si ancorano mai ad altri thread.

Ticket: L’aggregato dell’unità di lavoro. Neutro rispetto al fornitore: local per impostazione predefinita, con adattatori di sincronizzazione per Linear, GitHub Issues, Jira Cloud e ClickUp — anche se nessuna superficie dell’app crea una connessione di sincronizzazione. Supporta gerarchia, collegamenti e delega. L’assegnazione a un agente registra la proprietà e non avvia alcun invio; l’assegnazione a un team è l’eccezione (TeamRoutingService invia il leader).

Pipeline: Un flusso di lavoro basato su DAG che concatena passaggi (invio di agenti, script, condizioni). Definito da modelli; eseguito come esecuzioni.

Value object

AgentRole: Ruolo enumerato (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Determina la persona, l’accesso alla memoria e la gerarchia.

AgentSkills: Insieme di identificatori di skill, insensibile alle maiuscole e minuscole, che iniettano il contesto pertinente nei prompt al momento dell’invio.

Sorgente di skill: Un repository GitHub registrato per spazio di lavoro come catalogo di skill. Non attendibile per costruzione: i metadati del repository servono solo alla visualizzazione e ogni installazione supera il gate di scansione fail-closed prima che qualsiasi contenuto raggiunga il disco o un prompt. Vedi Installa e gestisci le skill.

skills-lock.json: Il manifest per spazio di lavoro delle skill installate: per ognuna, il repository di origine, il percorso nel repo, il commit a cui è fissata e un hash dei contenuti aggregato. Installazioni, aggiornamenti e disinstallazioni lo tengono aggiornato; verify_skills lo verifica rispetto al disco.

Gateway delle esecuzioni degli agenti: Un endpoint di loopback su cc_server che applica la policy delle azioni dentro il sandbox di un agente. Ogni push GitHub di un agente viene instradato lì, verificato con la regola Eseguire il push a un remoto e inoltrato con un token di scrittura che l’agente non possiede mai; i comandi Bash di Claude Code vengono verificati tramite un hook sullo stesso endpoint. Vedi Sandbox e sicurezza.

Modalità: chat, plan, review o orchestrate. Memorizzata per spazio, quindi un agente può trovarsi in modalità diverse in spazi diversi; ogni conversazione di uno spazio la condivide. Vincola il prompt di sistema, le regole di scrittura del sandbox e la lista di autorizzazione degli strumenti MCP. Il composer offre solo chat, plan e orchestrate; chat è etichettata «Agente».

SandboxBackend: microvm (una VM racchiusa — l’unico backend con un confine a livello di kernel, applicato ai terminali interattivi), native (Seatbelt su macOS, bubblewrap su Linux e WSL2) o none. Sondato una volta all’avvio; native viene applicato all’invio degli agenti quando è disponibile, avvolgendo la CLI di Claude Code e lo strumento bash dell’harness. Windows non ha un backend nativo e Linux richiede bwrap più socat, quindi le esecuzioni lì sono senza involucro; --sandbox off rinuncia deliberatamente.

Rig: Una macchina usa e getta che un agente pilota in tempo reale — un browser o un desktop Linux racchiuso, un emulatore Android o un simulatore iOS gestito dall’host, oppure un terminale racchiuso. Osservata dal vivo su una corsia dedicata a piena risoluzione, con la presa di controllo imposta lato server. Con ambito di conversazione, così la scheda umana e le chiamate browser_use / computer_use / mobile_use / ios_use dell’agente si rivolgono a un’unica macchina predefinita. Vedi Rig e recinti.

Recinto: Il confine più forte per i rig supportati da VM — un confine a livello di kernel, un disco overlay usa e getta, un gate di rete che nega per impostazione predefinita e un broker delle credenziali. I rig Android e iOS sono usa e getta ma usano la rete gestita dall’host e non rivendicano questo confine. Pilotare un rig usa la classe di guardrail enclosureControl.

RunCost: Il conteggio di token e costi (token di input, token di output, costo stimato in centesimi) per una singola esecuzione di agente.

WakeReason: Perché un agente è stato inviato. Sei valori: messaggio dell’utente, assegnazione di un ticket, reinvio di ripristino dopo un errore, ticket figlio completato, heartbeat di follow-up pianificato e passaggio di pipeline.

Porte

SandboxPort: Gestisce il ciclo di vita del sandbox (probe, launch, events, exec, destroy).

CredentialBrokerPort: Conia credenziali con ambito limitato per l’avvio del sandbox — di sola lettura per l’ambiente di un agente, di scrittura solo per il percorso di push lato server — e le revoca allo smontaggio.

GitRepoInspectorPort: Estrae i metadati (owner, repo, branch) dal percorso di un repository Git locale.

EmbeddingPort: Produce vettori di embedding testuale a norma unitaria per la ricerca semantica.

NotificationPort: Mostra notifiche desktop native rispettando il gating per categoria e route.

TicketProviderPort: Confine agnostico rispetto al fornitore verso un backend di ticketing (create, get, list, update, transition, assign).

PipelineEnginePort: Avvia un’esecuzione di pipeline da un modello, disaccoppiando i chiamanti dal motore concreto.

Servizi di dominio

AgentDispatchService: Avvia le esecuzioni degli agenti: prepara i repository isolati, costruisce i prompt, crea i log di esecuzione e restituisce flussi di eventi dal vivo.

TicketWorkflowService: Motore di ciclo di vita dei ticket puramente di dominio, con un punto di strozzatura per le mutazioni in concorrenza ottimistica e l’applicazione dell’isolamento tra spazi di lavoro. Il grafo di transizioni che applica vincola solo agenti e automazione; le modifiche guidate dall’utente tramite interfaccia passano force: true e lo aggirano. Non esiste alcun dispatcher di ticket per un assegnatario agente — l’invio è di competenza di AgentDispatchService, e assegnare un ticket a un agente non avvia alcuna esecuzione. Assegnare un ticket a un team è l’eccezione (TeamRoutingService invia il leader).

PipelineEngine: Orchestra l’esecuzione delle esecuzioni: avvia le esecuzioni, pianifica i passaggi, persiste lo stato, gestisce router, join e continue-on-fail, riprende le esecuzioni in corso dopo un riavvio.

PipelineTriggerDispatcher: Si sottoscrive agli eventi di dominio e avvia automaticamente le esecuzioni di pipeline corrispondenti per i trigger abilitati.

MemoryAccessPolicy: Risolve e applica i permessi di memoria del ruolo di un agente sui domini.

HarnessCostCalculator: Calcola il prezzo dell’uso di token dell’harness integrato in un RunCost a partire dal catalogo models.dev. L’invio persiste quel conteggio nel log di esecuzione.

BudgetEnforcementService: Calcola la spesa mensile per agente e un blocco pre-invio (checkInvocationBlock). Quel blocco viene consultato solo dai riconciliatori di ripristino (OrphanRunReaper, StrandedTicketReconciler), mai da un invio ordinario di un utente o di un agente.

BudgetGovernanceService: Valuta la spesa mensile per agente dopo ogni esecuzione — una soglia morbida registra un incidente di avviso; l’esaurimento registra un incidente grave e porta il ciclo di vita dell’agente a paused.

Eventi

DomainEventBus: Bus publish/subscribe in-process con broadcast per la comunicazione tra feature. Gli eventi sono tipizzati; gli abbonati consumano flussi on<T>().

DomainEvent: Interfaccia di base. Ogni evento ha occurredAt. Categorie principali: spazio di lavoro/agente, PR/revisione, messaggistica, ticketing, pipeline, riunioni/calendario, identità, rig, osservabilità.

Riunioni e calendario

Riunione: Una sessione di riunione registrata e trascritta localmente. Cattura il microfono e l’audio di sistema, trascrive sul dispositivo con un modello ASR selezionabile (Parakeet TDT v3 per impostazione predefinita; Parakeet TDT v2, Whisper large-v3-turbo e Whisper base.en sono alternative), separa i parlanti e riassume in note, attività e decisioni. Il modello ASR selezionato viene installato forzatamente all’avvio e le operazioni di registrazione si attivano dopo un riavvio. Con ambito di spazio di lavoro; resta sulla macchina.

MeetingSegment: Una finestra di audio trascritta, etichettata per parlante (me/them) con un’etichetta di diarizzazione e offset in millisecondi.

MeetingActionItem / MeetingDecision: Output strutturati estratti dalla pipeline di riepilogo e memorizzati come righe distinte. Le attività possono essere collegate a un ticket.

CalendarEvent: Una voce di Google Calendar sincronizzata, con ambito di spazio di lavoro e account collegato. Diversa da una Riunione: un evento è un impegno programmato; una Riunione è una sessione registrata. Collegata uno a uno tramite un MeetingCalendarLink.

CalendarAccount: Un account Google collegato, per spazio di lavoro e indirizzo email. I token di aggiornamento OAuth sono conservati lato server come chiavi google_* in <dataDir>/secrets.json e non raggiungono mai un client; il flusso con codice dispositivo si completa sul server. Un flag authExpiredAt pilota il banner di riconnessione.

Termini di architettura

Clean Architecture: Regola delle dipendenze: Presentation → Application/Providers → Domain ← Infrastructure. Il dominio non ha alcun import dall’infrastruttura.

Porte e adattatori: Il dominio definisce interfacce astratte (le porte); l’infrastruttura fornisce implementazioni concrete (gli adattatori). La composition root le collega.

Kernel condiviso: Entità, value object, porte e servizi di core/domain/ condivisi da 3 o più feature.

Feature-first: Il codice è organizzato per dominio di business (agenti, pipeline, messaggistica) anziché per livello tecnico.

Multigiocatore, identità e velocità

Principal: Un valore sealed che unifica esseri umani e agenti nell’unica astrazione di attore — UserPrincipal(userId) o AgentPrincipal(agentId). Ogni messaggio, ticket, revisione, piano e log di esecuzione viene attribuito attraverso un Principal.

Utente: Un’identità umana, conservata in global.db e quindi globale tra gli spazi di lavoro. Il principal che crea uno spazio di lavoro ne diventa il proprietario — registrato su Workspace.ownerUserId con una riga di appartenenza con ruolo di proprietario nella stessa operazione. Gli altri si uniscono per invito o tramite SSO.

WorkspaceMember / WorkspaceRole: Una riga di appartenenza che lega un Utente a uno Spazio di lavoro con un ruolo (owner / admin / member / viewer / guest). Il confine di accesso è l’appartenenza — non una chiave di associazione. Le concessioni per repository impediscono all’appartenenza di dare più privilegi di quanti ne conceda la forge.

ParticipantPresence: Consapevolezza effimera per un Principal (stato, posizione, cursore, digitazione, lo stato dal vivo di un agente e il costo in corso). Mai persistita; concentrata sul server; filtrata per concessione di repository prima della diffusione.

Modalità Segui: Clicca su un avatar per seguire la sua visuale finché non compi un’azione, poi staccati. Vale per gli esseri umani e per gli agenti («guarda un agente al lavoro»).

Quadrante dell’autonomia: Un controllo per spazio e per agente — propose-only / act-with-approval / act-freely — implementato come profilo con nome sopra l’archivio dei guardrail delle azioni.

ActionClass: Un insieme chiuso di 13 classi di effetto (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Ogni strumento che modifica lo stato dichiara le proprie classi; il motore dei guardrail risolve allow / prompt / deny per ambito (spazio > agente > spazio di lavoro > preset di modalità > valore predefinito integrato).

WriteLedger / chiave di idempotenza: Ogni mutazione porta con sé una chiave di idempotenza generata dal client (UUIDv7, per azione logica). Il registro con ambito di spazio di lavoro deduplica prima che il gestore venga eseguito; un replay restituisce il risultato originale identico byte per byte. Rende la riconnessione e il lavoro con più client sicuri per costruzione.

Posta in arrivo «Needs me»: Una coda trasversale a tutti i pilastri con una regola ferrea — una voce compare solo se blocca qualcosa (un agente, una fusione, una sincronizzazione) o chiede esplicitamente l’intervento dell’operatore.

Plan Studio: La superficie di pianificazione interattiva — piani in DAG tipizzato e modificabili, con costo, tempo e rischio per ogni passaggio, e approvazione parziale.

Calcolo della revisione: Il calcolo della revisione lato server per una PR (coorti derivate dal grafo, diagrammi tipizzati, diff visivi, diff dei contratti API, gate multi-asse) servito tramite review_studio.* e integrato nella scheda Revisione.

Spazio di revisione: L’unico spazio di supporto di una PR (modalità review, tipo pr), creato in modo idempotente e collegato alla PR da una ReviewSpaceAssociation. Ogni revisore vi deposita i propri rilievi, ed è ciò che li rende confrontabili; il suo worktree isolato contiene la PR estratta alla sua head.

Nodo di revisione: L’unità strutturata di un rilievo di revisione IA: tipo (bug, suggestion, recommendation, question, ticket), priorità da P0 a P3, una terna di triage categoria/gravità/impegno, un’ancora di file e riga, una correzione suggerita facoltativa e un punteggio di confidenza. Depositato con add_review_node; il verdetto si calcola dai nodi, non dalla prosa.

Consensus-ready: Lo stato di un nodo di revisione che si raggiunge solo quando un revisore pari conferma un rilievo — un agente non può confermare il proprio. Il pulsante Pubblica su GitHub della scheda Revisione invia ogni rilievo aperto rimanente (selection: all_open); lo strumento MCP publish_review_to_github continua a limitarsi per impostazione predefinita ai soli rilievi confermati da un pari.

Livello di revisione: Policy dello spazio di lavoro (light, balanced, thorough) che regola quali revisori vengono inviati (solo engineer; +qa+architect; +security+perf) e dove vengono mostrati i rilievi sotto la soglia. Non elimina mai un rilievo.

Asse di revisione: Una delle cinque corsie di punteggio per revisione: correctness, security e testGap tratti dai rilievi dei revisori; visual e apiContract deterministici. Gli assi con gate confluiscono nel verdetto e possono solo renderlo più severo — un gate partial o unavailable trattiene il verdetto invece di farlo passare.

Verdetto di revisione: ship, hold o block. Qualunque rilievo P0 con confidenza ≥ 0.7 blocca; qualunque altro P0 o qualunque P1 trattiene; altrimenti ship. Un asse con gate in errore forza block e non può essere messo in minoranza dai rilievi.

Flotta ed eval

cc_worker: Un binario esecutore di flotta headless in Dart puro. Si associa a un cc_server, dichiara le capacità del proprio host, preleva i lavori in lease, li esegue e rinvia in streaming gli eventi dei processi. Non detiene alcuno stato durevole — un server autorevole, N arti senza cervello.

JobSpec: La specifica tipizzata di tutto ciò che è eseguibile (esecuzione di agente, passaggio di pipeline, code-index, golden-render, benchmark, lotto di eval).

Suite di eval: Una definizione di valutazione con ambito di spazio di lavoro (prompt, agente e modalità di destinazione, valutatori). Cinque suite iniziali vengono create alla creazione di uno spazio di lavoro; Osservabilità → Qualità le elenca.

Deployment e client

Architettura a client leggero: Nessun client apre il database; un processo cc_server headless possiede i dati e li serve via RPC su WebSocket. Ogni client (desktop, web, telefono) è un renderer su quell’unica connessione RPC.

cc_server: Il binario server headless (Dart puro, senza motore Flutter). Possiede il database Drift/SQLite, serve il repo-RPC su WebSocket ed esegue i servizi in background (pipeline, MCP, riconciliatori).

ServerConnectionMode: Come il desktop raggiunge il proprio server — local (avvia un cc_server su questa macchina, il valore predefinito) o remote (ne contatta uno altrove). Il client web è sempre remote.

RemoteRpcClient: Il client JSON-RPC indipendente dal trasporto che ogni client leggero usa per parlare con il proprio server — su WSS, loopback o tramite il relay con broker.

Ambito di spazio di lavoro per ogni chiamata: Il server è stateless — non esiste alcun binding di spazio di lavoro per sessione, quindi più client su un server non condividono mai uno «spazio di lavoro corrente». Ogni repo/call e sub/subscribe con ambito di spazio di lavoro deve portare workspace_id nei propri argomenti; un id mancante o non registrato viene rifiutato prima che si apra qualsiasi database. L’accesso è poi filtrato dall’appartenenza allo spazio di lavoro e dal ruolo, non dalla sessione.

cc_remote: Il client leggero per il telefono — una PWA web Flutter che controlla la flotta da remoto tramite il relay con broker, con una policy degli strumenti che nega per impostazione predefinita.

cc_signaling_server: Un broker relay WebSocket stateless che ospita stanze ad accesso su invito — un relay semplice che inoltra solo frame sigillati end-to-end, non detiene alcun dato dell’applicazione e non vede mai la PSK di associazione.