stack-RFC-020 — Operator Plane, Apex Root e o Kode Agent Service

Status: Accepted — ratificado pelo owner (Rodrigo) em 2026-06-25. Origem: deliberação /k-arch de 2026-06-25 (transcrito nesta sessão). Veredicto-keystone e sub-decisões fundamentados em architecture-quality.kmd (D1D2D3D5D7D8D9D10D12) + stack-principles.kmd §2 (Quality > Speed absoluto) + reuse-first.kmd (plumbing compartilhado × substância de produto).

1. Contexto e objetivo (north-star)

O owner quer deixar de depender do notebook para trabalhar com a IA, usando Kode como surface primária, com uma experiência que supere o notebook: mídia rica (arquivosáudiovídeoimagensemojis/stickers), voz live com escolha de timbre, conectores a todos os serviços da Koder Stack + GoogleMicrosoft GitHub/Apple, todos os repositórios do KVS, Kortex, CI, deploys, gestão de DNS (conta pessoal rodrigo@koder.dev + orgs onde é owner), correção de bugs, geração de releases, inventário de outros chats, acesso ao celular via Kiris, publicação de sites/landings, análises, relatórios e gráficos.

Esta RFC fixa a fundação que torna isso possível sem "bagunçar" a arquitetura da Stack e considerando expansão internacional / escala global desde o dia um.

1.1 Vocabulário fechado: "Kode"

Kode é a marca de IA da Koder, abrangendo três camadas — análogo de "Claude + Claude app" na Anthropic:

Isto resolve o item antes em aberto de "nomear o agente": o agente é o Kode.

2. Modelo de dois planos

A árvore de poderes da Stack tem dois planos ortogonais, com uma parede entre eles. Esta é a decisão estrutural central.

2.1 Plano Operador — quem constrói e opera a Stack (toca dev + infra)

• Apex Root — o owner, principal único e não-delegável (ver §4).
• Agentes de IA — o Kode-agente como service identity do plano operador.
• Devs contratados (futuro) — escopo por repo/componente no KVS.
• Infra ops contratados (futuro) — escopo de infraestrutura.

2.2 Plano Tenant — quem usa os produtos da Stack (isolado do plano operador)

É a multi-tenancy já ratificada em id-RFC-017 (Org → Workspace → Project + RBAC + RLS). Esta RFC não a redesenha — adota. A empresa Koder é a org tenant #1 (dogfooding); seu pessoal de RHjurídicocontábil são membros tenant sem nenhum acesso a dev ou infra. Usuários e orgs públicas entram aqui.

2.3 Invariante da parede

Ter conta no plano tenant NUNCA concede acesso ao plano operador. O owner habita ambos os planos como principais distintos e transita por autenticação explícita, jamais por herança. Não há caminho de escalada do tenant para o operador.

O Momento 5 do rollout (§7) é a prova viva desta parede: um funcionário do RH, promovido dentro da org-empresa, estruturalmente não alcança a infra.

3. O Kode Agent service (cérebro único, surface-agnóstico)

Veredicto-keystone (/k-arch 2026-06-25 — opção b): o cérebro agêntico é extraído num serviço único surface-agnóstico — o Kode Agent service, generalização do koder-root-bot (krb) — e todas as surfaces são clientes finos sobre um contrato explícito.

Emenda 2026-06-27 — placement resolvido (kode#055): o "Kode Agent service" não é greenfield — é o services/ai/agents já existente, o *runtime de agente canônico* da Stack, formalizado em services/ai/agents/docs/RFC-001-engine-of-kode.kmd (Engine+Product; multi-tenant; REST/WS :7804; "no third agent runtime") e já em produção (LXC aiagents 10.0.1.130). RFC-020 não cria serviço novo: adiciona o tier operador (root) sobre esse engine. A "generalização do krb" realiza-se como o krb virar cliente fino do services/ai/agents (hoje roda claude/codex local), não como extração de um serviço novo. Liga-se à RFC-001 (§12).

                       ┌─────────────────────────────┐
   Kode app (PRIMÁRIA) │                             │
   Koder Chat ─────────┤   Kode Agent service        │
   Koder Talk ─────────┤   (cérebro, contrato único) ├── Kode Relay (roteamento
   Telegram (bootstrap)│   ├ tier operador (root)    │    multimodelo) ATRÁS
                       │   └ tier tenant (sandboxed) │
                       └──────────────┬──────────────┘
                                      │ chokepoint de autorização (§5)
                         ┌────────────┴────────────┐
                   conectores Koder Stack    conectores externos
                   (KVS, CI, deploy, DNS,    (Google/MS/GitHub/Apple)
                    Kortex, Kiris, …)

3.1 Por que serviço, não motor embutido no app

Rejeitadas no /k-arch:

• (a) backend do Kode absorve o krb — funde substância de produto

  (assistente de consumo) com plumbing crítico de root no mesmo codebase; viola a parede dos planos e piora D2D7D9. Rejeitada.

• (c) dois agentes distintos (Kode produto × krb cockpit) — dois runtimes,

  conectores duplicados, drift, marca fragmentada; fere #1 (Meta First) e D10. Rejeitada.

A opção b vence porque o cérebro agêntico (Claude Code/multimodelo + toolset + conectores + tiers) é plumbing cross-surface com ≥3 consumidores → por reuse-first pertence a um serviço compartilhado, escrito uma vez. Ganha em D1/D2 (contrato + desacoplamento), D7 (root isolado num só enclave), D9 (surfaces descartáveistrocáveis), D10#1 (reuso). Trade-off aceito: mais integração agora (definir contrato + refatorar krb em serviço + ligar o Kode-app como cliente) em troca de um único cérebro hardenizado, multi-surface e reversível.

3.2 Tiers do serviço (mapeiam os dois planos)

• Tier operador (root) — linhagem do koder-root-bot. Acesso root à Stack;

  único owner; exige elevação (§4, §5).

• Tier tenant (sandboxed) — linhagem do koder_kode_bot. Sandbox por-tenant;

  jamais com credenciais operador. É o vetor de escala global (multi-tenant).

3.3 Topologia de surfaces

Conectores e Apex Root vivem no serviço — adicionar um conector novo aparece em todas as surfaces sem release de app.

4. Apex Root

O único bloco genuinamente novo. Hoje a Stack tem system_admin (admin do control-plane dos tenants) e koder_admin (bypass de RLS no storage), mas nenhum é o ápice único provisionador. O root legado do Flow (id=1) está desativado. O Apex Root é definido como extensão de id-RFC-017/007, não como subsistema paralelo.

Provisionamento por root: como ápice, o owner-root pode criar e gerir contas em qualquer nó abaixo da árvore tenant (orgs, owners, membros, usuários) — incluindo criar a org-empresa Koder do Momento 5. O caminho inverso (tenant → operador) não existe.

5. Invariante de segurança 1 — o agente como portador de poder + injeção

No instante em que um agente carrega root e lê conteúdo não-confiável (emails, outros chats, arquivos, web, repos de terceiros), cria-se a maior superfície de ataque da Stack. Mitigação obrigatória: um chokepoint de autorização único entre o agente e todo conector, dentro do Kode Agent service, que enforça de forma uniforme:

1. Proveniência (instrução × dados). Só o *anal de comando autenticado do

   owner vira instrução. Todo conteúdo lido do mundo é dado inerte*— nunca pode escalar a comando. (Generaliza o padrão instrução(DM)×dados(histórico) do krb.)

2. Gates de confirmação em ações irreversíveis/alto-impacto, mesmo em root.
3. Elevação escopada/temporária (de A3/A4) — root nunca é ambiente.
4. Auditoria + reversibilidade — log append-only; preferir operações

   reversíveis + checkpoint/snapshot.

Mecanismo recomendado: expressar essas regras de gate de forma declarativa em Kanon (stack-RFC-015, motor já entregue), num chokepoint único, em vez de checks ad-hoc por conector (Meta First + D7). Liga-se ao Governance Plane (stack-RFC-016).

6. Invariante de segurança 2 — onde o cérebro roda (E2E × IA)

Enclave dedicado e hardenizado por plano.

• Cérebro operador (root) roda num enclave isolado (modelo do LXC do krb

  hoje em s.khost1), egress restrito, sem co-tenancy com infra que serve tenants. É a joia da coroa (detém o caminho de elevação + credenciais de conector). Aplica stack-RFC-009 (mTLS interno) e security.kmd.

  • *opologia do tier root (emenda 2026-06-27, kode#055 — decisão /k-go, opção

    (ii)): como o services/ai/agents é multi-tenant, o cérebro operador não co-habita a instância tenant — roda como deployment separado e hardenizado do mesmo binário services/ai/agents*num enclave dedicado (modelo do LXC do krb), egress restrito, sem co-tenancy; o multi-tenant tenant roda noutra instância. Fiel a este §6 (vs (i) tier meramente lógico na mesma instância, rejeitado por co-tenancy).

• Cérebro tenant (sandboxed) roda em sandboxes por-tenant, jamais com

  credenciais operador.

• E2E: no Talk a IA é necessariamente endpoint de texto-claro (precisa

  decifrar para agir). Portanto trabalho privilegiado/auditável é roteado para Kode app / Koder Chat (server-side, auditável), não para o Talk; no Talk só interação pessoal não-privilegiada, e o host-como-ponto-de-decifração herda o mesmo hardening de enclave.

7. Rollout — os 9 Momentos

Momentos 0–4 constroem o plano operador; 5 dogfooda o tenant; 6–9 abrem o tenant progressivamente (a expansão internacional roda nos trilhos de id-RFC-017, que já é multi-tenant/hyperscale por design).

8. Marcos de implementação

9. Non-goals

• Não redesenha a multi-tenancy (adota id-RFC-017).
• Não cria um app Koder novo (Kode app já existe; Chat/Talk já existem).
• Não define o modelo de negócio/billing do tier produto (Momento 6+).
• Não decide a UX de multi-IA (várias IAs como participantes) — o backend já

  é multimodelo; a UX fica para depois.

10. Reversibilidade e migração (D9)

• Surfaces são clientes finos sobre um contrato → trocáveis sem reescrever o

  cérebro. Porta de mão dupla.

• O koder-root-bot em Telegram permanece operante durante a transição; o

  contrato do serviço é versionado.

• Apex Root é extensão aditiva de id-RFC-017/007 (não quebra o modelo tenant).

11. Itens estacionados (não bloqueiam)

• KPC ("Kode Personal Computer") — em andamento; relacionar ao cockpit.
• Agent Console (Kli) — avaliar como manifestação-produto do tier tenant no

  Momento 6+, para a versão pública não nascer paralela.

• Multi-IA — UX deferida.

12. Relação com RFCs existentes

• id-RFC-017 (tenancy hierarchy, Accepted) — base do plano tenant.
• id-RFC-007 (admin service/CLI) + id-RFC-016 (RLS) — Apex Root estende.
• stack-RFC-007 (credential ownership / BYO keys) — conectores externos.
• stack-RFC-009 (mTLS interno) — hardening do enclave.
• stack-RFC-015 (Kanon) — chokepoint declarativo de autorização.
• stack-RFC-016 (Governance Plane) — onde os gates se inserem.
• services/ai/agents RFC-001-engine-of-kode (proposed) — *efine o serviço deste

  RFC* ai/agents é o runtime canônico ("engine of Kode"); RFC-020 é a mesma decisão pelo ângulo dos planos (adiciona tier root + invariantes de segurança). A RFC-001 deve subir a accepted alinhada ao modelo de tiers (kode#055).

13. Ratificação

Ratificado pelo owner em 2026-06-25. Sub-decisões a confirmar na ratificação: o veredicto-keystone (b, §3) e as quatro de Apex Root (A1–A4, §4). Ao ratificar, mudar status: draft → accepted com data e assinatura do owner, e abrir os tickets de M1 no backlog do Kode Agent service.