Glossário

Entidades principais

Agente: Um trabalhador de IA com uma identidade, uma função, skills e um adaptador. Pertence a exatamente um espaço de trabalho. O ator principal do sistema.

Adaptador: O executor que executa um turno de agente. São distribuídos dois: Control Center (built-in) — o harness em processo que fala com os fornecedores de modelos — e Claude Code através de claude -p. Cursor, Codex, Anthropic, OpenAI e os restantes são fornecedores do adaptador integrado, e não CLIs separadas. Ver Gerir adaptadores e modelos.

Espaço de trabalho: O inquilino de isolamento de nível superior. Agrupa agentes, repos, espaços, tickets, memória e pipelines. O isolamento é estrutural, não convencional: cada espaço de trabalho tem o seu próprio ficheiro SQLite (<dataDir>/<workspaceId>/workspace.db), pelo que uma leitura entre espaços de trabalho não compila. Todas as rotas da aplicação têm o prefixo /workspaces/:workspaceId — consulte o mapa de rotas.

Host de código: Um host de código — GitHub, GitLab ou Bitbucket Cloud. O host de código é uma propriedade de cada repo, lida do seu remoto origin no momento do registo, e determina o adaptador de API e a credencial desse repo. Um espaço de trabalho pode conter repos nos três; as superfícies agregadoras (a caixa de entrada, a fila de PRs) distribuem-se por todos os hosts representados e combinam os resultados, isolando as falhas para que um host inacessível nunca esvazie os outros. Os hosts de código diferem naquilo que suportam — consulte a tabela de capacidades em Ligar um host de código.

Repo: Um repositório Git registado dentro de um espaço de trabalho. Com âmbito de espaço de trabalho — o mesmo checkout registado em dois espaços de trabalho são duas linhas independentes com dois ids; a identidade de um repo entre espaços de trabalho faz-se pelo caminho no sistema de ficheiros, nunca pelo id. O registo exige uma árvore de trabalho git cujo remoto origin aponte para um host de código suportado. Cada repo transporta o seu host de código (github / gitlab / bitbucket), que determina o adaptador de API e a credencial usados para ele.

Repo isolado: Uma árvore de trabalho de um repo registado, com âmbito de espaço de trabalho. Copy-on-write através do rift onde esse nativo é distribuído; git worktree no Windows. Aprovisionado por espaço — todas as conversas desse espaço partilham um único checkout — para que os agentes nunca alterem a origem.

Espaço: Um contentor de colaboração com âmbito de espaço de trabalho, com participantes humanos e agentes, um Mode persistido, um estado de aprovisionamento e um SpaceKind (topic / agentPeer / system / pr / slack) que decide como é dividido em secções, silenciado, assinalado com um distintivo e sujeito a recolha de lixo. É dono das árvores de trabalho isoladas que as suas conversas partilham (copy-on-write através do rift; git worktree no Windows).

Conversa: Um fluxo de mensagens dentro de um espaço, com o seu próprio id, histórico e contexto de execução de agente. As conversas de um espaço são pares ao mesmo nível — não existe nenhum fluxo primário ou “principal”. Cada uma abre num separador do editor; o estado não lido de um espaço agrega-se em todas elas.

Thread: Uma conversa cujo anchorMessageId está definido: ancorada numa mensagem de uma conversa irmã do mesmo espaço, com um contexto de agente novo semeado por essa mensagem de âncora. Um único nível de profundidade — as threads nunca se ancoram a threads.

Ticket: O agregado de unidade de trabalho. Neutro quanto ao fornecedor: local por predefinição, com adaptadores de sincronização para Linear, GitHub Issues, Jira Cloud e ClickUp — embora nenhuma superfície da aplicação crie uma ligação de sincronização. Suporta hierarquia, ligações e delegação. A atribuição a um agente regista a propriedade e não despacha nada; a atribuição a uma equipa é a exceção (o TeamRoutingService despacha o líder).

Pipeline: Um fluxo de trabalho baseado num DAG que encadeia passos (despacho de agentes, scripts, condições). Definido por modelos; executado na forma de execuções.

Objetos de valor

AgentRole: Função enumerada (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Determina a persona, o acesso à memória e a hierarquia.

AgentSkills: Conjunto insensível a maiúsculas e minúsculas de identificadores de skills que injeta contexto relevante nos prompts no momento do despacho.

Fonte de skills: Um repositório GitHub registado por espaço de trabalho como catálogo de skills. Não fidedigno por construção: os metadados do repositório servem apenas para apresentação e cada instalação passa pelo portão de análise de falha segura antes de qualquer conteúdo chegar ao disco ou a um prompt. Ver Instalar e gerir skills.

skills-lock.json: O manifesto por espaço de trabalho das skills instaladas: para cada uma, o repositório de origem, o caminho no repo, o commit a que está fixada e um hash de conteúdo agregado. As instalações, atualizações e desinstalações mantêm-no atual; verify_skills verifica-o em relação ao disco.

Gateway de execuções de agentes: Um endpoint de loopback no cc_server que aplica a política de ações dentro da sandbox de um agente. Cada push para o GitHub feito por um agente é desviado para ele, verificado com a regra Fazer push para um remoto e reencaminhado com um token de escrita que o agente nunca detém; os comandos Bash do Claude Code são verificados através de um hook no mesmo endpoint. Consulte Sandbox e segurança.

Mode: chat, plan, review ou orchestrate. Guardado por espaço, pelo que um agente pode estar em modos diferentes em espaços diferentes; todas as conversas de um espaço o partilham. Condiciona o prompt de sistema, as regras de escrita da sandbox e a lista de permissões de ferramentas MCP. O compositor oferece apenas chat, plan e orchestrate; chat é apresentado como “Agent”.

SandboxBackend: microvm (uma VM em recinto — o único backend com uma fronteira de kernel, aplicado a terminais interativos), native (Seatbelt no macOS, bubblewrap no Linux e no WSL2) ou none. Sondado uma vez no arranque; o native é aplicado ao despacho de agentes quando está disponível, envolvendo a CLI do Claude Code e a ferramenta bash do harness. O Windows não tem backend nativo e o Linux precisa de bwrap e de socat, pelo que as execuções aí ficam sem envolvente; --sandbox off prescinde dele deliberadamente.

Rig: Uma máquina descartável que um agente conduz em tempo real — um navegador ou desktop Linux em recinto, um emulador Android ou Simulator iOS gerido pelo anfitrião, ou um terminal em recinto. Observada em direto através do seu próprio canal de resolução total, com a assunção de controlo imposta no servidor. Com âmbito de uma conversa, para que o separador humano e as chamadas browser_use / computer_use / mobile_use / ios_use do agente se dirijam a uma única máquina predefinida. Ver Rigs e recintos.

Recinto: A fronteira mais forte dos rigs suportados por VM — uma fronteira de kernel, um disco sobreposto descartável, um portão de rede que nega por predefinição e um broker de credenciais. Os rigs Android e iOS são descartáveis, mas usam a rede gerida pelo anfitrião e não reivindicam esta fronteira. Conduzir qualquer rig usa a classe de barreira enclosureControl.

RunCost: Contagem de tokens e de custo (tokens de entrada, tokens de saída, custo estimado em cêntimos) de uma única execução de agente.

WakeReason: Porque é que um agente foi despachado. Seis valores: mensagem do utilizador, atribuição de ticket, novo despacho de recuperação após uma falha, ticket filho concluído, heartbeat de acompanhamento agendado e passo de pipeline.

Portas

SandboxPort: Gere o ciclo de vida da sandbox (probe, launch, events, exec, destroy).

CredentialBrokerPort: Emite credenciais com âmbito limitado para o arranque da sandbox — só de leitura para o ambiente de um agente, de escrita apenas para o caminho de push no servidor — e revoga-as ao desmontar.

GitRepoInspectorPort: Extrai metadados (proprietário, repo, branch) do caminho de um repo Git local.

EmbeddingPort: Produz vetores de embedding de texto com norma unitária para pesquisa semântica.

NotificationPort: Mostra notificações nativas do ambiente de trabalho respeitando o condicionamento por categoria/rota.

TicketProviderPort: Fronteira agnóstica de fornecedor para um backend de tickets (create, get, list, update, transition, assign).

PipelineEnginePort: Inicia uma execução de pipeline a partir de um modelo, desacoplando os chamadores do motor concreto.

Serviços de domínio

AgentDispatchService: Lança execuções de agentes: aprovisiona repos isolados, constrói prompts, cria registos de execução e devolve fluxos de eventos em direto.

TicketWorkflowService: Motor de ciclo de vida de tickets em domínio puro, com um ponto de estrangulamento de mutações sob concorrência otimista e aplicação do isolamento entre espaços de trabalho. O grafo de transições que impõe vincula apenas agentes e automatização; as alterações feitas pelo utilizador na interface passam force: true e contornam-no. Não existe nenhum despachante de tickets para um agente atribuído — o AgentDispatchService é dono do despacho, e atribuir um ticket a um agente não inicia nenhuma execução. Atribuir um ticket a uma equipa é a exceção (o TeamRoutingService despacha o líder).

PipelineEngine: Orquestra a execução: inicia execuções, agenda passos, persiste o estado, trata de routers/joins/continue-on-fail e retoma execuções em curso após um reinício.

PipelineTriggerDispatcher: Subscreve eventos de domínio e inicia automaticamente as execuções de pipeline correspondentes aos disparadores ativados.

MemoryAccessPolicy: Resolve e aplica as permissões de memória da função do agente nos domínios.

HarnessCostCalculator: Calcula o preço da utilização de tokens do harness integrado num RunCost a partir do catálogo models.dev. O despacho persiste essa contagem no registo de execução.

BudgetEnforcementService: Calcula a despesa mensal por agente e um bloqueio pré-despacho (checkInvocationBlock). Esse bloqueio só é consultado pelos reconciliadores de recuperação (OrphanRunReaper, StrandedTicketReconciler), nunca por um despacho normal de utilizador ou de agente.

BudgetGovernanceService: Avalia a despesa mensal por agente depois de cada execução — um limiar flexível regista um incidente de aviso; o esgotamento regista um incidente grave e coloca o ciclo de vida do agente em paused.

Eventos

DomainEventBus: Barramento de publicação/subscrição com difusão, em processo, para a comunicação entre funcionalidades. Os eventos são tipados; os subscritores consomem fluxos on<T>().

DomainEvent: Interface base. Todos os eventos têm occurredAt. Categorias principais: espaço de trabalho/agente, PR/revisão, mensagens, tickets, pipeline, reuniões/calendário, identidade, rigs, observabilidade.

Reuniões e calendário

Reunião: Uma sessão de reunião gravada e transcrita localmente. Capta o microfone e o áudio do sistema, transcreve no dispositivo com um modelo ASR à escolha (Parakeet TDT v3 por predefinição; Parakeet TDT v2, Whisper large-v3-turbo e Whisper base.en são alternativas), faz a diarização dos oradores e resume tudo em notas, tarefas e decisões. O modelo ASR escolhido é instalado à força no arranque e as operações de gravação ficam disponíveis após um reinício. Com âmbito de espaço de trabalho; fica na máquina.

MeetingSegment: Uma janela transcrita de áudio, etiquetada por orador (me/them), com uma etiqueta de diarização e deslocamentos em milissegundos.

MeetingActionItem / MeetingDecision: Resultados estruturados extraídos pelo pipeline de resumo e guardados como linhas discretas. As tarefas podem estar ligadas a um ticket.

CalendarEvent: Uma entrada do Google Calendar sincronizada, com âmbito de um espaço de trabalho e de uma conta ligada. Distinta de uma Reunião: um evento é um compromisso agendado; uma Reunião é uma sessão gravada. Ligada um para um através de um MeetingCalendarLink.

CalendarAccount: Uma conta Google ligada, por espaço de trabalho e e-mail. Os tokens de atualização OAuth são guardados no servidor como chaves google_* em <dataDir>/secrets.json e nunca chegam a um cliente; o fluxo device-code conclui-se no servidor. Um indicador authExpiredAt alimenta a faixa de reconexão.

Termos de arquitetura

Clean Architecture: Regra de dependências: Presentation → Application/Providers → Domain ← Infrastructure. O domínio não tem qualquer importação de infraestrutura.

Portas e adaptadores: O domínio define interfaces abstratas (portas); a infraestrutura fornece implementações concretas (adaptadores). A raiz de composição liga-as.

Kernel partilhado: Entidades, objetos de valor, portas e serviços de core/domain/ partilhados por 3 ou mais funcionalidades.

Orientado a funcionalidades: O código está organizado por domínio de negócio (agentes, pipelines, mensagens) e não por camada técnica.

Multijogador, identidade e velocidade

Principal: Um valor selado que unifica humanos e agentes como a única abstração de ator — UserPrincipal(userId) ou AgentPrincipal(agentId). Todas as mensagens, tickets, revisões, planos e registos de execução são atribuídos através de um Principal.

Utilizador: Uma identidade humana, guardada em global.db e, por isso, global entre espaços de trabalho. O principal que cria um espaço de trabalho torna-se o seu proprietário — marcado em Workspace.ownerUserId com uma linha de pertença com a função de proprietário na mesma operação. Os restantes entram por convite ou SSO.

WorkspaceMember / WorkspaceRole: Uma linha de pertença que vincula um Utilizador a um Espaço de trabalho com uma função (owner / admin / member / viewer / guest). A pertença — e não uma chave de emparelhamento — é a fronteira de acesso. As concessões por repo impedem que a pertença conceda mais privilégios do que o host de código.

ParticipantPresence: Conhecimento efémero sobre um Principal (estado, local, cursor, a escrever, o estado em direto de um agente e o custo em curso). Nunca é persistido; encaminhado pelo servidor; filtrado pelas concessões de repo antes da difusão.

Modo de seguimento: Clique num avatar para acompanhar a sua viewport até agir e, em seguida, desligue-se. Funciona para humanos e para agentes (“ver um agente a trabalhar”).

Dial de autonomia: Um controlo por espaço e por agente — propose-only / act-with-approval / act-freely — implementado como um perfil com nome sobre o armazenamento de barreiras de ação.

ActionClass: Um conjunto fechado de 13 classes de efeito (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Todas as ferramentas que mutam o estado declaram as suas classes; o motor de barreiras resolve allow / prompt / deny por âmbito (espaço > agente > espaço de trabalho > predefinição de modo > predefinição integrada).

WriteLedger / chave de idempotência: Todas as mutações transportam uma chave de idempotência gerada pelo cliente (UUIDv7, por ação lógica). O registo com âmbito de espaço de trabalho deduplica antes de o manipulador ser executado; uma repetição devolve o resultado original idêntico byte a byte. Torna a reconexão e a utilização de vários clientes seguras por construção.

Caixa de entrada: Uma fila transversal a todos os pilares com uma regra estrita — um item só aparece se bloquear algo (um agente, um merge, uma sincronização) ou se pedir explicitamente o operador.

Plan Studio: A superfície de planeamento interativa — planos em DAG tipado editáveis, com custo, tempo e risco por passo, e aprovação parcial.

Computação de revisão: Computação de revisão de PR do lado do servidor (coortes derivadas do grafo, diagramas tipados, diffs visuais, diffs de contrato de API, portões por eixo) disponibilizada através de review_studio.* e integrada no separador Revisão.

Espaço de revisão: O único espaço de suporte de uma PR (modo review, tipo pr), criado de forma idempotente e ligado à PR por uma ReviewSpaceAssociation. Todos os revisores registam nele as suas constatações, e é isso que as torna comparáveis; a sua worktree isolada tem a PR em checkout na cabeça.

Nó de revisão: A unidade estruturada de uma constatação de revisão por IA: tipo (bug, suggestion, recommendation, question, ticket), prioridade P0–P3, um triplo de triagem categoria/severidade/esforço, uma âncora de ficheiro e linha, uma correção sugerida opcional e uma pontuação de confiança. Registada com add_review_node; o veredicto é calculado a partir dos nós, e não da prosa.

Pronto para consenso: O estado de um nó de revisão alcançado apenas quando um revisor par confirma uma constatação — um agente não pode confirmar a sua própria. O botão Publicar no GitHub do separador Revisão envia todas as constatações abertas restantes (selection: all_open); a ferramenta MCP publish_review_to_github continua a usar por predefinição apenas as constatações confirmadas por pares.

Nível de revisão: Política do espaço de trabalho (light, balanced, thorough) que define quais revisores são despachados (apenas engenheiro; +qa+arquiteto; +segurança+desempenho) e onde são apresentadas as constatações abaixo do limiar. Nunca elimina uma constatação.

Eixo de revisão: Uma de cinco faixas de pontuação por revisão: correctness, security e testGap retirados das constatações dos revisores; visual e apiContract determinísticos. Os eixos com portão integram-se no veredicto e só o podem tornar mais severo — um portão partial ou unavailable retém o veredicto em vez de o aprovar.

Veredicto de revisão: ship, hold ou block. Qualquer constatação P0 com confiança ≥ 0.7 dá block; qualquer outro P0 ou qualquer P1 dá hold; caso contrário, ship. Um eixo com portão em falha força block e não pode ser derrotado por votos das constatações.

Frota e avaliações

cc_worker: Um binário executor de frota headless em Dart puro. Emparelha com um cc_server, declara as capacidades do anfitrião, recolhe trabalhos em lease, executa-os e transmite de volta os eventos de processo. Não detém qualquer estado durável — um servidor com autoridade e N executores sem estado.

JobSpec: A especificação tipada de tudo o que é executável (execução de agente, passo de pipeline, índice de código, golden-render, benchmark, lote de avaliação).

Suíte de avaliação: Uma definição de avaliação com âmbito de espaço de trabalho (prompt, agente e modo alvo, avaliadores). Cinco suítes iniciais são instaladas quando o espaço de trabalho é criado; Observabilidade → Qualidade lista-as.

Implementação e clientes

Arquitetura de cliente fino: Nenhum cliente abre a base de dados; um processo cc_server headless é dono dos dados e serve-os por RPC sobre WebSocket. Todos os clientes (computador, web, telemóvel) são um renderizador sobre essa única ligação RPC.

cc_server: O binário de servidor headless (Dart puro, sem motor Flutter). É dono da base de dados Drift/SQLite, serve repo-RPC por WebSocket e executa os serviços de segundo plano (pipelines, MCP, reconciliadores).

ServerConnectionMode: Como o ambiente de trabalho alcança o seu servidor — local (inicia um cc_server nesta máquina, a predefinição) ou remote (liga-se a um noutro local). O cliente web é sempre remote.

RemoteRpcClient: O cliente JSON-RPC agnóstico de transporte que todos os clientes finos usam para falar com o seu servidor — por WSS, loopback ou o relay intermediado.

Âmbito de espaço de trabalho por chamada: O servidor não tem estado — não existe qualquer vínculo de espaço de trabalho por sessão, pelo que vários clientes num servidor nunca partilham um “espaço de trabalho atual”. Todas as chamadas repo/call e sub/subscribe com âmbito de espaço de trabalho têm de transportar workspace_id nos seus argumentos; um id em falta ou não registado é recusado antes de qualquer base de dados ser aberta. O acesso é depois condicionado pela pertença e pela função no espaço de trabalho, e não pela sessão.

cc_remote: O cliente fino para telemóvel — uma PWA web em Flutter que controla a frota remotamente através do relay intermediado, com uma política de ferramentas de negação por predefinição.

cc_signaling_server: Um broker de relay WebSocket sem estado que aloja salas com acesso restrito por convite — um relay simples que só reencaminha frames selados ponto a ponto, não guarda dados da aplicação e nunca vê a PSK de emparelhamento.