Modos de connector

RUNNER_CONNECTORS decide de onde vêm as respostas das ferramentas. É a variável que mais causa confusão na instalação, porque o default responde alguma coisa, e alguma coisa parece funcionamento.

synthetic: o default

Um connector built-in determinístico com um seed de 3 operações, cujos formatos não batem com os connectors reais. O catálogo real tem cerca de 190 operações.

Serve para uma coisa só: provar boot, handshake e dispatch sem credencial.

Não é um mock das ferramentas

Se você está vendo entries.map is not a function, erro de formato, ou “op não implementada”, você está em synthetic. A correção não é abrir um bug: é escolher demo ou real.

real: as suas fontes

Registra os connectors reais, com credenciais lidas do secret store, e liga o redator de PII completo.

RUNNER_CONNECTORS=real

Cada connector é lazy. Ele é instanciado no primeiro uso, lendo as próprias chaves. Faltar uma chave só faz aquelas operações responderem auth_error. O resto continua funcionando. Você não precisa de todas as credenciais para subir.

O served-set é secret-aware: um connector cujas chaves obrigatórias não estão presentes sai do conjunto anunciado ao control-plane, e o sinal disso é um connector not served no log de boot.

demo: o catálogo inteiro, sem credencial

RUNNER_CONNECTORS=demo

Sobe um ambiente fictício completo. Os manifests são derivados dos reais, com os mesmos ids (aws, datadog, github, …), as mesmas operações e secrets/egress zerados; os handlers resolvem de um fixture store com time-shift, de modo que o incidente plantado sempre acabou de acontecer.

Propriedades que valem conhecer:

• Operação sem fixture responde vazio mas ok, nunca erro.
• O healthCheck é sempre verde.
• Os ids são os reais, e não demo. Isso é deliberado: um id demo faria o gate de connector da superfície de agente bloquear todas as ferramentas por elas estarem fora do served-set.
• O catalogHash permanece intacto: manifest não é contrato de wire.

É o modo usado para demonstração e para o CI de consistência.

Comparação

	synthetic	demo	real
Credenciais	nenhuma	nenhuma	as suas
Operações	3 (seed)	catálogo inteiro	catálogo inteiro
Formatos batem com o real	não	sim	sim
Redação de PII	field-only	field-only	completa
Para quê	boot e handshake	demonstração, CI	produção

Mecanismos de isolamento

Ortogonal ao acima. RUNNER_CONNECTOR_MECHANISMS (CSV, default native) escolhe como o connector executa:

• native: dentro do processo do runner. É o modo dos connectors que acompanham o produto.
• sidecar: subprocesso isolado pelo sistema operacional, com secret e egress mediados por host-call. É o único mecanismo que de fato aplica a allowlist de egress.
• wasm: seam; existe um spike que valida o modelo.

A limitação de egress dos connectors nativos

Os connectors nativos embrulham SDKs de terceiros que fazem HTTP por conta própria. A garantia de egress-allowlist do runtime não os cobre. As declarações de egress no manifest são documentação. A redação de PII na borda continua valendo normalmente.

As quatro garantias do runtime

Independentes do modo, o ConnectorRuntime sustenta:

1. Secret escopado: cada connector só enxerga os próprios segredos.
2. Allowlist de egress: real no mecanismo sidecar, declaratória no native.
3. Conformância: suíte que valida o connector contra o contrato da operação.
4. Redação por campo declarado: os sensitiveFields do manifest.

Uma invariante que falha no boot

Dois connectors não podem declarar a mesma operação. O runtime valida os manifests no construtor e falha no boot:

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

Isso é desejável, não um bug: execute(op) precisa saber deterministicamente para quem despachar. A arbitragem acontece antes do runtime. Veja Observabilidade.

Escrever o seu próprio connector

Comece por packages/connector-sdk (defineConnector + runConformance). O modelo de suíte de conformância é apps/runner/tests/connectors/grafana-conformance.test.ts, que cobre cenário populado e vazio.

Se o seu connector serve uma capability que já tem dono, ele precisa passar pela arbitragem. Não entre direto no array de connectors reais.