Modos de connector

RUNNER_CONNECTORS decide de dónde vienen las respuestas de las tools. Es la variable que más confusión causa durante la instalación, porque el modo por defecto responde algo, y algo parece que funciona.

synthetic: el modo por defecto

Un connector built-in determinista con un seed de 3 operaciones, cuyas formas no coinciden con las de los connectors reales. El catálogo real tiene unas 190 operaciones.

Sirve para un único propósito: probar el boot, el handshake y el dispatch sin credenciales.

No es un mock de las tools

Si estás viendo entries.map is not a function, un error de forma, o “op not implemented”, estás en synthetic. La solución no es abrir un bug: es elegir demo o real.

real: tus fuentes

Registra los connectors reales, con credenciales leídas del secret store, y habilita el redactor de PII completo.

RUNNER_CONNECTORS=real

Cada connector es lazy. Se instancia en el primer uso, leyendo sus propias claves. Una clave faltante solo hace que esas operaciones respondan auth_error. Todo lo demás sigue funcionando. No necesitas todas las credenciales para arrancar.

El served set es secret-aware: un connector cuyas claves obligatorias están ausentes sale del conjunto anunciado al control-plane, y la señal de eso es una línea connector not served en el log de boot.

demo: todo el catálogo, sin credenciales

RUNNER_CONNECTORS=demo

Levanta un entorno ficticio completo. Los manifests se derivan de los reales, con los mismos ids (aws, datadog, github, …), las mismas operaciones y secrets/egress en cero; los handlers resuelven desde un fixture store con time-shift, así que el incidente plantado siempre acaba de ocurrir.

Propiedades que vale la pena conocer:

• Una operación sin fixture responde vacía pero ok, nunca con error.
• healthCheck siempre está en verde.
• Los ids son los reales, no demo. Es deliberado: un id demo haría que el gate de connectors de la superficie de agente bloqueara todas las tools por estar fuera del served set.
• catalogHash queda intacto: un manifest no es un contrato de wire.

Es el modo que se usa para demos y para el CI de consistencia.

Comparación

	synthetic	demo	real
Credenciales	ninguna	ninguna	las tuyas
Operaciones	3 (seed)	todo el catálogo	todo el catálogo
Las formas coinciden con producción	no	sí	sí
Redacción de PII	solo por campo	solo por campo	completa
Para qué	boot y handshake	demos, CI	producción

Mecanismos de aislamiento

Ortogonal a lo anterior. RUNNER_CONNECTOR_MECHANISMS (CSV, por defecto native) elige cómo se ejecuta un connector:

• native: dentro del proceso del runner. Es el modo de los connectors que vienen con el producto.
• sidecar: un subproceso aislado por el sistema operativo, con secretos y egress mediados por host calls. Es el único mecanismo que de verdad aplica la allowlist de egress.
• wasm: un seam; un spike valida el modelo.

La limitación de egress de los connectors nativos

Los connectors nativos envuelven SDKs de terceros que hacen sus propias llamadas HTTP. La garantía de egress allowlist del runtime no los cubre. Las declaraciones de egress en los manifests son documentación. La redacción de PII en el borde sigue aplicándose normalmente.

Las cuatro garantías del runtime

Independientemente del modo, el ConnectorRuntime sostiene:

1. Secretos acotados: cada connector ve solo los suyos.
2. Allowlist de egress: real con sidecar, declarativa con native.
3. Conformidad: una suite que valida el connector contra el contrato de la operación.
4. Redacción por campo declarado: los sensitiveFields del manifest.

Una invariante que falla en el boot

Dos connectors no pueden declarar la misma operación. El runtime valida los manifests en el constructor y falla en el boot:

op "metrics.getServiceLatency" claimed by both datadog and grafana

Es deseable, no un bug: execute(op) tiene que saber de forma determinista a dónde despachar. El arbitraje ocurre antes del runtime. Ver Observabilidad.

Escribir tu propio connector

Empieza por packages/connector-sdk (defineConnector + runConformance). La suite de conformidad modelo es apps/runner/tests/connectors/grafana-conformance.test.ts, que cubre un escenario poblado y uno vacío.

Si tu connector sirve una capability que ya tiene dueño, tiene que pasar por el arbitraje, así que no lo agregues directamente al array de connectors reales.