Glossário

Entidades principais

Agente: Um trabalhador de IA com identidade, papel, 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. Dois são distribuídos: Control Center (built-in) — o harness em processo que conversa com os provedores de modelos — e Claude Code via claude -p. Cursor, Codex, Anthropic, OpenAI e o resto são provedores sobre o adaptador integrado, não CLIs separadas. Consulte Gerenciar adaptadores e modelos.

Espaço de trabalho: O tenant 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 seu próprio arquivo SQLite (<dataDir>/<workspaceId>/workspace.db), então uma leitura entre espaços de trabalho não compila. Toda rota dentro do app tem 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 é uma propriedade de cada repo, lida do seu remoto origin no registro, e seleciona 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) fazem fan-out por todos os hosts representados e mesclam os resultados, isolando falhas para que um host inacessível nunca esvazie os demais. Os hosts diferem no que suportam — consulte a tabela de capacidades em Conectar um host de código.

Repo: Um repositório Git registrado dentro de um espaço de trabalho. Com escopo de espaço de trabalho — o mesmo checkout registrado em dois espaços de trabalho são duas linhas independentes com dois ids; a identidade de um repo entre espaços de trabalho é pelo caminho no sistema de arquivos, nunca pelo id. O registro exige uma árvore de trabalho do git cujo remoto origin aponte para um host de código compatível. Cada repo carrega esse host (github / gitlab / bitbucket), que seleciona o adaptador de API e a credencial usados para ele.

Repo isolado: Um worktree com escopo de espaço de trabalho de um repo registrado. Copy-on-write via rift onde esse nativo é distribuído; git worktree no Windows. Provisionado por espaço — toda conversa desse espaço compartilha um checkout — de modo que os agentes nunca alteram a origem.

Espaço: Um contêiner de colaboração com escopo de espaço de trabalho, com participantes humanos e agentes, um Mode persistido, status de provisionamento e um SpaceKind (topic / agentPeer / system / pr / slack) que decide como ele é seccionado, silenciado, marcado com selo e coletado como lixo. Ele é dono dos worktrees isolados que suas conversas compartilham (copy-on-write via rift; git worktree no Windows).

Conversa: Um fluxo de mensagens dentro de um Espaço, com seu próprio id, histórico e contexto de execução do agente. As conversas de um espaço estão no mesmo nível — não há fluxo primário nem “principal”. Cada uma abre como uma aba do editor; o estado de não lidas de um espaço agrega todas elas.

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

Ticket: O agregado de unidade de trabalho. Neutro em relação ao fornecedor: local por padrão, com adaptadores de sincronização para Linear, GitHub Issues, Jira Cloud e ClickUp — embora nenhuma superfície dentro do app crie uma conexão de sincronização. Oferece suporte a hierarquia, vínculos e delegação. Atribuir a um agente registra a propriedade e não despacha nada; atribuir a uma equipe é a exceção (TeamRoutingService despacha o líder).

Pipeline: Um fluxo de trabalho baseado em DAG que encadeia etapas (despacho de agentes, scripts, condicionais). Definido por modelos; executado como execuções.

Objetos de valor

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

AgentSkills: Conjunto de identificadores de skills que não diferencia maiúsculas de minúsculas e injeta contexto relevante nos prompts no momento do despacho.

Origem de skill: Um repositório do GitHub registrado por espaço de trabalho como catálogo de skills. Não confiável por construção: os metadados do repositório são apenas para exibição e toda instalação passa pelo portão de varredura fail-closed antes que qualquer conteúdo chegue ao disco ou a um prompt. Consulte instalar e gerenciar skills.

skills-lock.json: O manifesto por espaço de trabalho das skills instaladas: para cada uma, seu repositório de origem, o caminho no repo, o commit ao qual ela está fixada e um hash de conteúdo acumulado. Instalações, atualizações e desinstalações o mantêm atualizado; verify_skills o confere com o disco.

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

Mode: chat, plan, review ou orchestrate. Armazenado por espaço, então um agente pode estar em modos diferentes em espaços diferentes; toda conversa de um espaço o compartilha. Condiciona o prompt de sistema, as regras de escrita do sandbox e a lista de permissões de ferramentas MCP. O compositor oferece apenas chat, plan e orchestrate; chat é rotulado como “Agente”.

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 na inicialização; o native é aplicado ao despacho de agentes quando 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 socat, então as execuções ali ficam sem envoltório; --sandbox off opta por não usá-lo deliberadamente.

Rig: Uma máquina descartável que um agente conduz em tempo real — um navegador ou desktop Linux em recinto, um emulador de Android ou Simulador de iOS gerenciado pelo host, ou um terminal em recinto. Assistido ao vivo pelo próprio canal em resolução total, com a tomada de controle imposta no servidor. Com escopo de uma conversa, de modo que a aba humana e as chamadas browser_use / computer_use / mobile_use / ios_use do agente apontem para uma máquina padrão. Consulte Rigs e recintos.

Recinto: A fronteira mais forte de um rig com VM — uma fronteira de kernel, disco de sobreposição descartável, portão de rede que nega por padrão e broker de credenciais. Os rigs de Android e iOS são descartáveis, mas usam rede gerenciada pelo host e não reivindicam essa fronteira. Conduzir qualquer rig usa a classe de barreira enclosureControl.

RunCost: A contagem de tokens e custo (tokens de entrada, tokens de saída, custo estimado em centavos) de uma única execução de agente.

WakeReason: Por que um agente foi despachado. Seis valores: mensagem do usuário, atribuição de ticket, novo despacho de recuperação após uma falha, ticket filho concluído, heartbeat de acompanhamento agendado e etapa de pipeline.

Portas

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

CredentialBrokerPort: Emite credenciais com escopo para iniciar o sandbox — somente leitura para o ambiente de um agente, de escrita só para o caminho de push no servidor — e as revoga ao desmontá-lo.

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 busca semântica.

NotificationPort: Mostra notificações nativas da área de trabalho respeitando o filtro por categoria e rota.

TicketProviderPort: Fronteira agnóstica de fornecedor com 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: Inicia execuções de agentes: provisiona repos isolados, monta prompts, cria logs de execução e devolve fluxos de eventos ao vivo.

TicketWorkflowService: Motor de ciclo de vida de tickets de domínio puro, com um ponto de estrangulamento de mutações sob concorrência otimista e imposição do isolamento de espaço de trabalho. O grafo de transições que ele impõe vincula apenas agentes e automação; alterações de UI feitas pelo usuário passam force: true e o contornam. Não existe despachante de tickets para um responsável agente — o AgentDispatchService é dono do despacho, e atribuir um ticket a um agente não inicia nenhuma execução. Atribuir um ticket a uma equipe é a exceção (TeamRoutingService despacha o líder).

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

PipelineTriggerDispatcher: Assina eventos de domínio e inicia automaticamente execuções de pipeline correspondentes para gatilhos habilitados.

MemoryAccessPolicy: Resolve e impõe as permissões de memória do papel do agente sobre domínios.

HarnessCostCalculator: Converte o uso de tokens do harness integrado em um RunCost com os preços do catálogo models.dev. O despacho persiste essa contagem no log de execução.

BudgetEnforcementService: Calcula o gasto mensal por agente e um bloqueio pré-despacho (checkInvocationBlock). Esse bloqueio é consultado apenas pelos reconciliadores de recuperação (OrphanRunReaper, StrandedTicketReconciler), nunca por um despacho comum de usuário ou de agente.

BudgetGovernanceService: Avalia o gasto mensal por agente depois de cada execução — cruzar o limite suave registra um incidente de aviso; esgotar o orçamento registra um incidente grave e muda o ciclo de vida do agente para paused.

Eventos

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

DomainEvent: Interface base. Todo evento tem 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. Captura o áudio do microfone e do sistema, transcreve no dispositivo com um modelo ASR selecionável (Parakeet TDT v3 por padrão; Parakeet TDT v2, Whisper large-v3-turbo e Whisper base.en são alternativas), faz a diarização de falantes e resume em notas, itens de ação e decisões. O modelo ASR selecionado é instalado à força na inicialização e as operações de gravação ficam disponíveis depois de um reinício. Com escopo de espaço de trabalho; permanece na máquina.

MeetingSegment: Uma janela transcrita de áudio, marcada por falante (me/them) com um rótulo de diarização e deslocamentos em milissegundos.

MeetingActionItem / MeetingDecision: Saídas estruturadas extraídas pelo pipeline de resumo e armazenadas como linhas distintas. Os itens de ação podem ser vinculados a um ticket.

CalendarEvent: Uma entrada sincronizada do Google Calendar com escopo de um espaço de trabalho e uma conta conectada. Diferente de uma Reunião: um evento é um compromisso agendado; uma Reunião é uma sessão gravada. Vinculado um a um por um MeetingCalendarLink.

CalendarAccount: Uma conta do Google conectada, por espaço de trabalho e e-mail. Os tokens de atualização do OAuth ficam no lado do servidor como chaves google_* em <dataDir>/secrets.json e nunca chegam a um cliente; o fluxo de código de dispositivo é concluído no servidor. Um sinalizador authExpiredAt controla o banner de reconexão.

Termos de arquitetura

Clean Architecture: Regra de dependências: Apresentação → Aplicação/Provedores → Domínio ← Infraestrutura. O domínio não tem nenhuma 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 os vincula.

Kernel compartilhado: Entidades, objetos de valor, portas e serviços de core/domain/ compartilhados por 3 ou mais features.

Orientado a features: O código é 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). Toda mensagem, ticket, revisão, plano e log de execução é atribuído por meio de um Principal.

Usuário: Uma identidade humana, armazenada em global.db e, portanto, global entre espaços de trabalho. O principal que cria um espaço de trabalho se torna seu proprietário — registrado em Workspace.ownerUserId com uma linha de associação com função de proprietário na mesma operação. Os demais entram por convite ou SSO.

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

ParticipantPresence: Conhecimento efêmero sobre um Principal (status, locus, cursor, digitação, status ao vivo do agente e custo em execução). Nunca é persistido; centralizado no servidor; filtrado por concessão de repo antes da distribuição.

Modo seguir: Clique em um avatar para acompanhar a viewport dele até você agir, e então se desvincular. Funciona para humanos e para agentes (“assistir a um agente trabalhar”).

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

ActionClass: Um conjunto fechado de 13 classes de efeito (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Toda ferramenta que muta declara suas classes; o motor de barreiras resolve allow / prompt / deny por escopo (espaço > agente > espaço de trabalho > predefinição de modo > padrão integrado).

WriteLedger / chave de idempotência: Toda mutação carrega uma chave de idempotência gerada pelo cliente (UUIDv7, por ação lógica). O ledger com escopo de espaço de trabalho deduplica antes que o manipulador seja executado; uma repetição devolve o resultado original idêntico byte a byte. Torna a reconexão e o uso de vários clientes seguros por construção.

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

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

Computação de revisão: A computação de revisão de PR no servidor (coortes derivadas do grafo, diagramas tipados, diffs visuais, diffs de contrato de API, portões multi-eixo) servida por review_studio.* e incorporada à aba Revisão.

Espaço de revisão: O único espaço que dá suporte a uma PR (modo review, tipo pr), criado de forma idempotente e vinculado à PR por uma ReviewSpaceAssociation. Todo revisor registra achados nele, e é isso que os torna comparáveis; seu worktree isolado tem a PR em checkout na sua ref de head.

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

Pronto para consenso: O status de um nó de revisão alcançado somente quando um revisor par confirma um achado — um agente não pode confirmar o seu próprio. O botão Publicar no GitHub da aba Revisão envia todo achado aberto restante (selection: all_open); a ferramenta MCP publish_review_to_github ainda usa por padrão apenas achados confirmados por pares.

Nível de revisão: Política do espaço de trabalho (light, balanced, thorough) que define quais revisores são acionados (apenas o engenheiro; +qa+arquiteto; +segurança+desempenho) e onde os achados abaixo do limite são exibidos. Nunca exclui um achado.

Eixo de revisão: Uma de cinco faixas de pontuação por revisão: correctness, security e testGap vêm dos achados dos revisores; visual e apiContract são determinísticos. Os eixos com portão entram no veredito e só podem torná-lo mais severo — um portão partial ou unavailable retém o veredito em vez de aprová-lo.

Veredito de revisão: ship, hold ou block. Qualquer achado 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 que falha força block e não pode ser derrotado por votos dos achados.

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 seu host, puxa tarefas em lease, as executa e transmite os eventos do processo de volta. Não guarda nenhum estado durável — um servidor autoritativo, N membros burros.

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

Suíte de avaliação: Uma definição de avaliação com escopo de espaço de trabalho (prompt, agente e modo de destino, avaliadores). Cinco iniciais são semeadas na criação do espaço de trabalho; Observabilidade → Qualidade as lista.

Implantação e clientes

Arquitetura de cliente leve: Nenhum cliente abre o banco de dados; um processo cc_server headless é dono dos dados e os serve por RPC sobre WebSocket. Todo cliente (desktop, web, celular) é um renderizador sobre essa única conexão RPC.

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

ServerConnectionMode: Como o desktop chega ao seu servidor — local (inicia um cc_server nesta máquina, o padrão) ou remote (conecta-se a um em outro lugar). O cliente web é sempre remote.

RemoteRpcClient: O cliente JSON-RPC agnóstico de transporte que todo cliente leve usa para conversar com seu servidor — por WSS, loopback ou pelo relay intermediado.

Escopo de espaço de trabalho por chamada: O servidor é sem estado — não há vínculo de espaço de trabalho por sessão, então vários clientes em um mesmo servidor nunca compartilham um “espaço de trabalho atual”. Todo repo/call e sub/subscribe com escopo de espaço de trabalho deve levar workspace_id nos seus argumentos; um id ausente ou não registrado é recusado antes que qualquer banco de dados seja aberto. O acesso é então condicionado pela associação ao espaço de trabalho e pela função, não pela sessão.

cc_remote: O cliente leve para celular — uma PWA web em Flutter que controla a frota remotamente pelo relay intermediado, com uma política de ferramentas que nega por padrão.

cc_signaling_server: Um broker de relay WebSocket sem estado que hospeda salas com acesso por convite — um relay deliberadamente burro que encaminha apenas frames selados de ponta a ponta, não guarda nenhum dado do app e nunca vê a PSK de pareamento.