Architecture

---
name: ravi-architecture
description: |
  Documentacao completa da arquitetura do Ravi. Use quando precisar:
  - Entender como o sistema funciona end-to-end
  - Modificar componentes existentes
  - Adicionar novos subsistemas
  - Debugar fluxos de mensagem
  - Onboarding no codebase
---

# Ravi - Arquitetura do Sistema

Ravi é um runtime multi-agent com canais via omni, coordenação interna por NATS JetStream,
estado em SQLite e execução por providers plugáveis atrás de um contrato único.

**Repositório:** `<ravi.bot repo>`
**Runtime:** Bun
**DB:** SQLite
**PubSub:** NATS JetStream

## Fluxo Principal de Mensagens

```text
WhatsApp/Discord/Telegram/Matrix
  -> omni API
  -> NATS JetStream MESSAGE
  -> OmniConsumer
  -> ravi.<session>.prompt
  -> RuntimePromptSubscription
  -> RuntimeSessionDispatcher
  -> RuntimeSessionLauncher
  -> RuntimeProvider.startSession(RuntimeStartRequest)
  -> RuntimeEvent stream
  -> RuntimeEventLoop
  -> ravi.session.<session>.runtime/tool/stream/response
  -> Gateway
  -> OmniSender
  -> canal
```

## Fronteira Ravi ↔ Omni

O Ravi decide comportamento operacional; o Omni transporta mensagens e presença para o canal.

Quando debugar sintomas que atravessam a fronteira:

- prove primeiro a última linha confiável no Ravi: routing, session, runtime event, target e payload outbound
- use logs do Omni para observar entrega/transporte, não para mover ownership automaticamente
- não corrija Omni para compensar lifecycle, routing, presence, task ou session state quebrado no Ravi
- só edite Omni ou outro repo externo quando a evidência apontar para contrato/adaptador de transporte e houver autorização explícita

Se o usuário delimitar "o problema é no Ravi", mantenha o patch no Ravi e trate o outro repo como evidência externa.

## Fronteiras Core

### `daemon.ts`

Composition root do processo:

- carrega env de `~/.ravi/.env`
- inicia NATS/JetStream
- inicia omni
- inicia RaviBot
- inicia OmniConsumer e Gateway
- inicia heartbeat, cron e triggers
- controla shutdown global

### `bot.ts`

Composition root do runtime de conversas.

Responsabilidades permitidas:

- construir `RuntimeSessionDispatcher`
- construir `RuntimePromptSubscription`
- construir `RuntimeHostSubscriptions`
- iniciar/parar subscriptions
- expor wrappers estreitos para testes/CLI

Responsabilidades proibidas:

- lógica específica de provider
- montagem de prompt/env/provider request
- autorização de tool/bash/session
- event loop de provider
- regra de fila/interrupção
- regra de task/profile/model

### `runtime/session-dispatcher.ts`

Decide o que fazer com um prompt:

- debounce
- sessão viva vs cold start
- troca de provider
- troca de modelo/effort/thinking
- queue, wake, interrupt
- delivery barrier
- after_task deferral
- limite de concorrência

### `runtime/session-launcher.ts`

Orquestra o start de uma sessão runtime.

Não deve virar saco de responsabilidades. Ele coordena:

- resolução de sessão/agent/provider via `session-resolver`
- resolução task/profile/model via `task-runtime-context`
- montagem do `RuntimeStartRequest` via `runtime-request-builder`
- persistência inicial de provider state
- aceite da task vinculada
- start do `RuntimeEventLoop`

### `runtime/runtime-request-builder.ts`

Compoe o `RuntimeStartRequest` final a partir dos modulos menores:

- `runtime-request-context.ts` — runtime context, tool context e env Ravi
- `runtime-provider-bootstrap.ts` — `prepareSession`, host services e plugins
- `runtime-session-continuity.ts` — resume/fork por provider state
- `runtime-host-attachments.ts` — hooks, spec server e remote spawn
- `runtime-request-builder.ts` — composicao final do start request

Regra: novo provider entra por adapter + capabilities. Nao adicionar branch por provider em
`bot.ts`, `session-launcher.ts` ou `runtime-request-builder.ts`.

### `runtime/host-services.ts`

Bridge de serviços do host:

- dynamic tools
- autorização de tool
- autorização de comando
- autorização de capability
- user input/poll
- session scope
- auditoria de denies

### `runtime/host-hooks.ts`

Bridge de hooks nativos quando o provider suporta:

- pre-tool permission
- bash permission
- sanitize bash
- pre-compact
- AskUserQuestion
- spec/exit plan hooks

### `runtime/host-event-loop.ts`

Traduz eventos do provider para eventos canônicos Ravi:

- `runtime`
- `tool`
- `stream`
- `response`

Também persiste provider session state em `turn.complete`.

## Runtime Provider Contract

O provider é adapter. O Ravi runtime é a fonte de verdade.

Providers built-in registrados em `src/runtime/provider-registry.ts`:

| Provider | Execução | Estado de sessão | Tool permissions | Controle runtime |
|----------|----------|------------------|------------------|------------------|
| `claude` | `sdk` | `provider-session-id` | `ravi-host` | sem `control` nativo |
| `codex` | `subprocess-rpc` | `thread-id` | `ravi-host` | `runtimeControl` habilitado |
| `pi` | `subprocess-rpc` | `file-backed` | `provider-native` | `runtimeControl` habilitado |

Regras de uso:

- Agent escolhe runtime por `agent.provider`; ausência usa o default do registry.
- Agent escolhe modelo por `agent.model`; o formato é provider-specific.
- Para `pi`, selectors que também são provider ids precisam vir como `provider/model`, por exemplo `kimi-coding/kimi-for-coding`.
- Novo runtime entra no registry e declara capabilities; não espalhe branch por provider fora do adapter, registry, model validation ou compatibilidade explícita.

Contrato canônico:

- provider recebe `RuntimeStartRequest`
- provider emite `RuntimeEvent`
- provider declara `RuntimeCapabilities`
- provider pode expor `interrupt`, `setModel` e `control`
- provider não muta task/session/canal diretamente

Documento canônico: `design/runtime-provider-contract.md`

Checklist para novo provider:

1. Implementar `RuntimeProvider` e declarar `RuntimeCapabilities`.
2. Usar `prepareSession` apenas para env/bootstrap/dynamic tools/approvals.
3. Normalizar output nativo para `RuntimeEvent`.
4. Cobrir capability matrix e prepare-session shape nos testes de contrato.
5. Criar testes especificos do provider para normalizacao de eventos.

## Capability Gates

Use `RuntimeCapabilities`, nunca branch solto por provider fora do registry/adapters.

Capabilities importantes:

- `supportsSessionResume`
- `supportsSessionFork`
- `supportsPartialText`
- `supportsToolHooks`
- `supportsHostSessionHooks`
- `supportsPlugins`
- `supportsMcpServers`
- `supportsRemoteSpawn`
- `toolAccessRequirement`
- `legacyEventTopicSuffix`

## Model Switching

A troca de modelo é estratégia runtime:

- `direct-set`: handle suporta `setModel`
- `restart-next-turn`: precisa reiniciar antes do próximo turno

Código: `runtime/model-switch.ts`

Não faça branch por provider para isso.

## Router / Sessions

Resolução de rota:

1. `thread:<id>`
2. grupo/contato
3. instance default agent
4. global default agent

Session key segue o formato:

```text
agent:<agentId>:main
agent:<agentId>:dm:<phone>
agent:<agentId>:whatsapp:group:<groupId>
agent:<agentId>:whatsapp:main:group:<groupId>:thread:<threadId>
```

O runtime autoritativo é a sessão no DB + provider state persistido.

## Tasks / Profiles / Workflow

Fronteira obrigatória:

- `task` executa
- `profile` define protocolo local da task
- `workflow` coordena nodes/edges/readiness/run state

Invariantes:

- `parentTaskId` não é scheduling
- `launch plan` fica na task
- profile não coordena workflow

## Plugins / Skills

Plugins internos ficam em `src/plugins/internal`.

Build:

```bash
bun run build
```

Em source/dev, o Ravi descobre `src/plugins/internal/**` direto do filesystem.
No pacote publicado, o build gera `dist/bundle/internal-plugins.json` para manter as skills internas autocontidas.
Não versionar registry gerado de skills no source.

Skills nativas de runtime podem ser sincronizadas para ambientes de provider quando suportado.

## Validação Recomendada Antes De Fechar Mudança Core

```bash
bun test src/runtime/model-switch.test.ts src/runtime/provider-contract.test.ts src/runtime/index.test.ts
bun test src/bot.runtime-guards.test.ts src/delivery-barriers.test.ts
bun run typecheck
bun run build
```

Se mexer em provider adapter, rode também o teste específico do provider alterado.