Glosario

Entidades principales

Agente: Un trabajador de IA con identidad, rol, skills y un adaptador. Pertenece a exactamente un espacio de trabajo. El actor principal del sistema.

Adaptador: El runner que ejecuta un turno de agente. Se distribuyen dos: Control Center (built-in) — el arnés en proceso que habla con los proveedores de modelos — y Claude Code, mediante claude -p. Cursor, Codex, Anthropic, OpenAI y el resto son proveedores sobre el adaptador integrado, no CLIs aparte. Consulta Gestionar adaptadores y modelos.

Espacio de trabajo: El inquilino de aislamiento de nivel superior. Agrupa agentes, repos, espacios, tickets, memoria y pipelines. El aislamiento es estructural, no convencional: cada espacio de trabajo tiene su propio archivo SQLite (<dataDir>/<workspaceId>/workspace.db), así que una lectura entre espacios de trabajo no compila. Toda ruta dentro de la aplicación lleva el prefijo /workspaces/:workspaceId; consulta el mapa de rutas.

Host de código: Un host de código: GitHub, GitLab o Bitbucket Cloud. Es una propiedad de cada repo: se lee de su remoto origin al registrarlo y determina el adaptador de API y la credencial de ese repo. Un espacio de trabajo puede contener repos en los tres; las superficies de agregación (la bandeja de entrada, la cola de PR) se despliegan por todos los hosts de código representados y fusionan los resultados, aislando las fallas de modo que un host de código inaccesible nunca vacíe los demás. Los hosts de código difieren en lo que admiten; consulta la tabla de capacidades en Conectar un host de código.

Repo: Un repositorio Git registrado dentro de un espacio de trabajo. Con ámbito de espacio de trabajo: el mismo checkout registrado en dos espacios de trabajo son dos filas independientes con dos identificadores; la identidad de un repo entre espacios de trabajo es por ruta del sistema de archivos, nunca por identificador. El registro exige un árbol de trabajo de git cuyo remoto origin apunte a un host de código compatible. Cada repo lleva ese host de código (github / gitlab / bitbucket), que determina el adaptador de API y la credencial que se usan para él.

Repo aislado: Un worktree con ámbito de espacio de trabajo de un repo registrado. Copia en escritura mediante rift allí donde se distribuya ese nativo; git worktree en Windows. Se aprovisiona por espacio (cada conversación de ese espacio comparte un único checkout), así que los agentes nunca modifican el origen.

Espacio: Un contenedor de colaboración con ámbito de espacio de trabajo, con participantes humanos y agentes, un Mode persistido, un estado de aprovisionamiento y un SpaceKind (topic / agentPeer / system / pr / slack) que decide cómo se secciona, se silencia, se marca con insignia y se recolecta como basura. Es dueño de los worktrees aislados que comparten sus conversaciones (copia en escritura mediante rift; git worktree en Windows).

Conversación: Un flujo de mensajes dentro de un Espacio, con su propio id, historial y contexto de ejecución del agente. Las conversaciones de un espacio están al mismo nivel: no hay ningún flujo primario ni «principal». Cada una se abre como pestaña del editor; el estado de no leídos de un espacio las agrega a todas.

Hilo: Una Conversación cuyo anchorMessageId está definido: anclada a un mensaje de una conversación hermana del mismo Espacio, con un contexto de agente nuevo sembrado por ese mensaje ancla. Un solo nivel de profundidad: los hilos nunca se anclan a hilos.

Ticket: El agregado de unidad de trabajo. Neutral respecto al proveedor: local de forma predeterminada, con adaptadores de sincronización para Linear, GitHub Issues, Jira Cloud y ClickUp, aunque ninguna superficie dentro de la aplicación crea una conexión de sincronización. Admite jerarquía, vínculos y delegación. Asignarlo a un agente registra la propiedad y no despacha nada; asignarlo a un equipo es la excepción (TeamRoutingService despacha al líder).

Pipeline: Un flujo de trabajo basado en DAG que encadena pasos (despacho de agentes, scripts, condicionales). Lo definen las plantillas; se ejecuta como ejecuciones.

Objetos de valor

AgentRole: Rol enumerado (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Determina la persona, el acceso a la memoria y la jerarquía.

AgentSkills: Conjunto de identificadores de skills que no distingue mayúsculas de minúsculas y que inyecta contexto relevante en los prompts en el momento del despacho.

Origen de skill: Un repositorio de GitHub registrado por espacio de trabajo como catálogo de skills. No es de confianza por construcción: los metadatos del repositorio solo se muestran y toda instalación pasa por la compuerta de análisis fail-closed antes de que ningún contenido llegue al disco o a un prompt. Consulta Instalar y gestionar skills.

skills-lock.json: El manifiesto por espacio de trabajo de las skills instaladas: para cada una, su repositorio de origen, la ruta en el repo, el commit al que está fijada y un hash de contenido agregado. Las instalaciones, actualizaciones y desinstalaciones lo mantienen al día; verify_skills lo contrasta con el disco.

Pasarela de ejecuciones de agentes: Un endpoint de loopback en cc_server que aplica la política de acciones dentro del sandbox de un agente. Cada push a GitHub que hace un agente se desvía hacia ella, se comprueba con la regla Enviar a un remoto y se reenvía con un token de escritura que el agente nunca tiene; los comandos Bash de Claude Code se comprueban mediante un hook en el mismo endpoint. Consulta Sandbox y seguridad.

Modo: chat, plan, review u orchestrate. Se almacena por espacio, así que un agente puede estar en modos distintos en espacios distintos; cada conversación de un espacio lo comparte. Condiciona el prompt del sistema, las reglas de escritura del sandbox y la lista de herramientas MCP permitidas. El compositor solo ofrece chat, plan y orchestrate; chat se muestra como «Agente».

SandboxBackend: microvm (una VM con recinto — el único backend con frontera de kernel, aplicado a los terminales interactivos), native (Seatbelt en macOS, bubblewrap en Linux y WSL2) o none. Se sondea una vez al arrancar; cuando está disponible, native se aplica al despacho de agentes y envuelve la CLI de Claude Code y la herramienta bash del arnés. Windows no tiene backend nativo y Linux necesita bwrap y socat, así que allí las ejecuciones van sin envolver; --sandbox off opta por no usarlo de forma deliberada.

Rig: Una máquina desechable que un agente dirige en tiempo real — un navegador o escritorio Linux con recinto, un emulador de Android o simulador de iOS gestionado por el host, o un terminal con recinto. Se observa en directo por su propio canal a resolución completa, con la toma de control impuesta en el servidor. Tiene el ámbito de una conversación, de modo que la pestaña humana y las llamadas browser_use / computer_use / mobile_use / ios_use del agente apuntan a una única máquina predeterminada. Consulta Rigs y recintos.

Recinto: La frontera más fuerte de un rig respaldado por VM — una frontera de kernel, un disco de superposición desechable, una compuerta de red que deniega por defecto y un bróker de credenciales. Los rigs de Android y iOS son desechables, pero usan red gestionada por el host y no reclaman esta frontera. Dirigir cualquier rig usa la clase de barandilla enclosureControl.

RunCost: La cuenta de tokens y costo (tokens de entrada, tokens de salida, costo estimado en centavos) de una única ejecución de agente.

WakeReason: Por qué se despachó a un agente. Seis valores: mensaje del usuario, asignación de un ticket, nuevo despacho de recuperación tras una falla, ticket hijo completado, latido de seguimiento programado y paso de pipeline.

Puertos

SandboxPort: Gestiona el ciclo de vida del sandbox (probe, launch, events, exec, destroy).

CredentialBrokerPort: Emite credenciales con ámbito para lanzar el sandbox —de solo lectura para el entorno de un agente, de escritura solo para la ruta de push del servidor— y las revoca al desmontarlo.

GitRepoInspectorPort: Extrae metadatos (propietario, repo, rama) de la ruta de un repo Git local.

EmbeddingPort: Produce vectores de embedding de texto con norma unitaria para la búsqueda semántica.

NotificationPort: Muestra notificaciones nativas de escritorio y respeta el filtrado por categoría y ruta.

TicketProviderPort: Frontera agnóstica del proveedor con un backend de tickets (create, get, list, update, transition, assign).

PipelineEnginePort: Inicia una ejecución de pipeline a partir de una plantilla y desacopla a quien llama del motor concreto.

Servicios de dominio

AgentDispatchService: Lanza ejecuciones de agentes: aprovisiona repos aislados, construye prompts, crea registros de ejecución y devuelve flujos de eventos en vivo.

TicketWorkflowService: Motor de ciclo de vida de tickets de dominio puro, con un punto de control para mutaciones bajo concurrencia optimista y con imposición del aislamiento de espacios de trabajo. El grafo de transiciones que impone solo vincula a agentes y automatización; los cambios de la interfaz que impulsa el usuario pasan force: true y lo eluden. No hay ningún despachador de tickets para un agente asignado: el despacho es de AgentDispatchService, y asignar un ticket a un agente no inicia ninguna ejecución. Asignar un ticket a un equipo es la excepción (TeamRoutingService despacha al líder).

PipelineEngine: Orquesta la ejecución de las ejecuciones: inicia ejecuciones, programa pasos, persiste el estado, gestiona routers, joins y continue-on-fail, y reanuda las ejecuciones en curso tras un reinicio.

PipelineTriggerDispatcher: Se suscribe a los eventos de dominio e inicia automáticamente las ejecuciones de pipeline que coinciden con los disparadores habilitados.

MemoryAccessPolicy: Resuelve e impone los permisos de memoria del rol del agente sobre los dominios.

HarnessCostCalculator: Convierte el uso de tokens del arnés integrado en un RunCost con los precios del catálogo de models.dev. El despacho persiste esa cuenta en el registro de ejecución.

BudgetEnforcementService: Calcula el gasto mensual por agente y un bloqueo previo al despacho (checkInvocationBlock). Ese bloqueo solo lo consultan los reconciliadores de recuperación (OrphanRunReaper, StrandedTicketReconciler), nunca un despacho normal de un usuario o un agente.

BudgetGovernanceService: Evalúa el gasto mensual por agente después de cada ejecución — cruzar el umbral suave registra un incidente de advertencia; agotar el presupuesto registra un incidente grave y cambia el ciclo de vida del agente a paused.

Eventos

DomainEventBus: Bus de publicación/suscripción con difusión, en proceso, para la comunicación entre funcionalidades. Los eventos están tipados; los suscriptores consumen flujos on<T>().

DomainEvent: Interfaz base. Todos los eventos tienen occurredAt. Categorías principales: espacio de trabajo/agente, PR/revisión, mensajería, tickets, pipeline, reuniones/calendario, identidad, rigs y observabilidad.

Reuniones y calendario

Reunión: Una sesión de reunión grabada y transcrita localmente. Captura el audio del micrófono y del sistema, transcribe en el dispositivo con un modelo ASR seleccionable (Parakeet TDT v3 de forma predeterminada; Parakeet TDT v2, Whisper large-v3-turbo y Whisper base.en son alternativas), diariza a los hablantes y resume en notas, tareas y decisiones. El modelo ASR seleccionado se instala a la fuerza al arrancar y las operaciones de grabación se activan tras un reinicio. Con ámbito de espacio de trabajo; no sale de la máquina.

MeetingSegment: Una ventana transcrita de audio, etiquetada por hablante (me/them) con una etiqueta de diarización y desplazamientos en milisegundos.

MeetingActionItem / MeetingDecision: Salidas estructuradas que extrae el pipeline de resumen y que se guardan como filas independientes. Las tareas pueden vincularse a un ticket.

CalendarEvent: Una entrada de Google Calendar sincronizada, con el ámbito de un espacio de trabajo y una cuenta conectada. Distinta de una Reunión: un evento es un compromiso programado; una Reunión es una sesión grabada. Se vincula uno a uno mediante un MeetingCalendarLink.

CalendarAccount: Una cuenta de Google conectada, por espacio de trabajo y correo electrónico. Los tokens de refresco de OAuth se guardan en el servidor como claves google_* en <dataDir>/secrets.json y nunca llegan a un cliente; el flujo de código de dispositivo termina en el servidor. Un indicador authExpiredAt controla el banner de reconexión.

Términos de arquitectura

Clean Architecture: Regla de dependencias: Presentación → Aplicación/Proveedores → Dominio ← Infraestructura. El dominio no importa nada de infraestructura.

Puertos y adaptadores: El dominio define interfaces abstractas (puertos); la infraestructura aporta implementaciones concretas (adaptadores). La raíz de composición los vincula.

Kernel compartido: Entidades, objetos de valor, puertos y servicios de core/domain/ compartidos por 3 o más funcionalidades.

Centrado en funcionalidades: El código se organiza por dominio de negocio (agentes, pipelines, mensajería) y no por capa técnica.

Multijugador, identidad y velocidad

Principal: Un valor sellado que unifica a personas y agentes como la única abstracción de actor: UserPrincipal(userId) o AgentPrincipal(agentId). Cada mensaje, ticket, revisión, plan y registro de ejecución se atribuye a través de un Principal.

Usuario: Una identidad humana, almacenada en global.db y, por tanto, global en todos los espacios de trabajo. El principal que crea un espacio de trabajo se convierte en su propietario, marcado en Workspace.ownerUserId con una fila de pertenencia con rol de propietario en la misma operación. Los demás se incorporan por invitación o por SSO.

WorkspaceMember / WorkspaceRole: Una fila de pertenencia que vincula a un Usuario con un Espacio de trabajo con un rol (owner / admin / member / viewer / guest). La pertenencia, y no la clave de emparejamiento, es la frontera de acceso. Las concesiones por repo evitan que la pertenencia otorgue más privilegios que el host de código.

ParticipantPresence: Conocimiento efímero sobre un Principal (estado, locus, cursor, escritura, estado en vivo de un agente y costo en curso). Nunca se persiste; lo centraliza el servidor; se filtra por concesión de repo antes de distribuirse.

Modo Seguir: Haz clic en un avatar para seguir su viewport hasta que actúes, y después te desenganchas. Funciona con personas y con agentes («ver trabajar a un agente»).

Dial de autonomía: Un control por espacio y por agente — propose-only / act-with-approval / act-freely — implementado como un perfil con nombre sobre el almacén de barandillas de acciones.

ActionClass: Un conjunto cerrado de 13 clases de efecto (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Cada herramienta que muta declara sus clases; el motor de barandillas resuelve allow / prompt / deny por ámbito (espacio > agente > espacio de trabajo > preajuste de modo > valor predeterminado integrado).

WriteLedger / clave de idempotencia: Cada mutación lleva una clave de idempotencia generada por el cliente (UUIDv7, por acción lógica). El ledger con ámbito de espacio de trabajo deduplica antes de ejecutar el manejador; una repetición devuelve el resultado original byte a byte. Hace seguros por construcción la reconexión y el uso de varios clientes.

Bandeja de entrada: Una cola que cruza todos los pilares con una regla estricta: un elemento solo aparece si bloquea algo (un agente, una fusión, una sincronización) o si solicita explícitamente al operador.

Plan Studio: La superficie de planificación interactiva: planes editables como DAG tipado, con costo, tiempo y riesgo por paso, y aprobación parcial.

Cómputo de revisión: El cómputo de revisión de una PR en el servidor (cohortes derivadas del grafo, diagramas tipados, diffs visuales, diffs del contrato de API, compuertas por varios ejes) servido sobre review_studio.* y sumado a la pestaña Revisar.

Espacio de revisión: El único espacio que respalda una PR (modo review, tipo pr), creado de forma idempotente y vinculado a la PR por una ReviewSpaceAssociation. Cada revisor registra hallazgos en él, y eso es lo que los hace comparables; su worktree aislado tiene la PR en checkout en su ref head.

Nodo de revisión: La unidad estructurada de un hallazgo de revisión con IA: tipo (bug, suggestion, recommendation, question, ticket), prioridad P0–P3, una tripleta de triaje de categoría, gravedad y esfuerzo, un ancla de archivo y línea, una corrección sugerida opcional y una puntuación de confianza. Se registra con add_review_node; el veredicto se calcula a partir de los nodos, no de la prosa.

Consensus-ready: El estado de un nodo de revisión al que solo se llega cuando un revisor par confirma un hallazgo: un agente no puede confirmar el suyo. El botón Publicar en GitHub de la pestaña Revisar envía todos los hallazgos abiertos que queden (selection: all_open); la herramienta MCP publish_review_to_github sigue usando de forma predeterminada solo los hallazgos confirmados por pares.

Nivel de revisión: Política del espacio de trabajo (light, balanced, thorough) que decide qué revisores se despliegan (solo el ingeniero; +qa+arquitecto; +seguridad+rendimiento) y dónde se muestran los hallazgos por debajo del umbral. Nunca elimina un hallazgo.

Eje de revisión: Una de las cinco sendas de puntuación por revisión: correctness, security y testGap se obtienen de los hallazgos de los revisores; visual y apiContract son deterministas. Los ejes con compuerta se incorporan al veredicto y solo pueden hacerlo más grave: una compuerta partial o unavailable retiene el veredicto en lugar de aprobarlo.

Veredicto de revisión: ship, hold o block. Cualquier hallazgo P0 con confianza ≥ 0,7 da block; cualquier otro P0 o cualquier P1 da hold; si no, ship. Un eje con compuerta que falla fuerza block y los hallazgos no pueden ganarle por votos.

Flota y evaluaciones

cc_worker: Un binario ejecutor de flota headless en Dart puro. Se empareja con un cc_server, declara las capacidades de su host, recoge trabajos con lease, los ejecuta y devuelve los eventos del proceso en streaming. No guarda ningún estado duradero: un servidor autoritativo, N extremidades tontas.

JobSpec: La especificación tipada de todo lo ejecutable (ejecución de agente, paso de pipeline, índice de código, render golden, benchmark, lote de evaluación).

Suite de evaluación: Una definición de evaluación con ámbito de espacio de trabajo (prompt, agente y modo de destino, evaluadores). Cinco iniciales se siembran al crear un espacio de trabajo; Observabilidad → Calidad las lista.

Despliegue y clientes

Arquitectura de cliente ligero: Ningún cliente abre la base de datos; un proceso cc_server headless posee los datos y los sirve por RPC sobre WebSocket. Todos los clientes (escritorio, web, teléfono) son un renderizador sobre esa única conexión RPC.

cc_server: El binario de servidor headless (Dart puro, sin motor de Flutter). Posee la base de datos Drift/SQLite, sirve repo-RPC por WebSocket y ejecuta los servicios en segundo plano (pipelines, MCP, reconciliadores).

ServerConnectionMode: Cómo llega el escritorio a su servidor: local (lanza un cc_server en esta máquina, el valor predeterminado) o remote (marca uno en otro sitio). El cliente web es siempre remote.

RemoteRpcClient: El cliente JSON-RPC independiente del transporte que usa todo cliente ligero para hablar con su servidor: por WSS, por loopback o por el relé intermediado.

Ámbito de espacio de trabajo por llamada: El servidor no tiene estado: no hay ninguna vinculación de espacio de trabajo por sesión, así que varios clientes en un mismo servidor nunca comparten un «espacio de trabajo actual». Cada repo/call y sub/subscribe con ámbito de espacio de trabajo debe llevar workspace_id en sus argumentos; un identificador ausente o no registrado se rechaza antes de que se abra ninguna base de datos. El acceso queda entonces condicionado por la pertenencia y el rol en el espacio de trabajo, no por la sesión.

cc_remote: El cliente ligero para el teléfono: una PWA web de Flutter que controla la flota en remoto por el relé intermediado, con una política de herramientas que deniega por defecto.

cc_signaling_server: Un bróker de retransmisión WebSocket sin estado que aloja salas con acceso por invitación: un relé tonto que solo reenvía tramas selladas de extremo a extremo, no guarda datos de la aplicación y nunca ve la PSK de emparejamiento.