🌐 Idioma / Language / Sprache: 🇬🇧 English | 🇩🇪 Deutsch | Português

🛰️ BDB AOrchestrator (ao)

Planeje, execute e supervisione 27 agentes de código em Git worktrees isolados, a partir de um único daemon local.

Dê a cada tarefa de código seu próprio agente, workspace e ciclo de feedback. Um orchestrator ciente do projeto planeja e delega resultados maiores; um Kanban ao vivo acompanha cada worker, pull request, execução de CI e review.

npx -y @hybridlabor-api/aos@latest

Após a instalação você tem:

• a CLI ao e um daemon local na porta 3101
• um serviço de inicialização automática (ao service install; LaunchAgent do macOS com.bdb.ao.daemon)
• adapters para 27 harnesses de agentes de código
• scaffolding de projetos AOS (ao project init --aos) e workers baseados em papéis (ao spawn --role)
• o observador de transcripts brainwatch e a interface BDB Board v3

[!IMPORTANT] Todo o estado do app fica em ~/.ao (substituível com AO_DATA_DIR, AO_RUN_FILE, AO_PORT). O app nunca grava nos locais padrão de dados de aplicativos do sistema operacional.

🧭 Arquitetura

flowchart TB
    subgraph UI["Clients"]
        EL["Electron desktop app<br/>userData: ~/.ao/electron"]
        CLI["ao CLI / bin/ao.js"]
        WEB["Web UI (webui/dist)"]
    end

    subgraph D["ao daemon  (port 3101 · state ~/.ao)"]
        API["HTTP API + SSE"]
        SM["Session manager<br/>spawn / lifecycle"]
        DB[("SQLite + CDC<br/>AO_DATA_DIR")]
        BW["brainwatch<br/>transcript observer"]
        SVC["serviceinstall<br/>LaunchAgent com.bdb.ao.daemon"]
    end

    subgraph ORCH["Orchestration layers"]
        MO["Main Orchestrator<br/>(scratch workspace)"]
        PO["Project orchestrators<br/>(AOS dispatcher, --aos)"]
        W["Workers<br/>ao spawn --role"]
    end

    subgraph AD["Harness adapters (27)"]
        A1["claudecode"]
        A2["codex"]
        A3["opencode"]
        A4["agy · cursor · aider · ..."]
    end

    subgraph WT["Isolated workspaces"]
        G1["git worktree: feature"]
        G2["git worktree: refactor"]
        G3["scratch dir (branchless)"]
    end

    EL --> API
    CLI --> API
    WEB --> API
    API --> SM
    SM --> DB
    BW --> DB
    SVC -. keeps alive .-> D

    MO -->|supervises state.json| PO
    PO -->|delegates| W
    SM --> MO & PO & W

    W --> A1 & A2 & A3 & A4
    A1 & A2 & A3 & A4 --> G1 & G2 & G3
    A1 & A2 & A3 & A4 -. transcripts .-> BW

    G1 & G2 --> PR["PR / CI / review feedback"]
    PR -.-> SM

• O Daemon serve a API HTTP e o stream SSE, persiste em SQLite em AO_DATA_DIR e controla o ciclo de vida das sessões.
• Os adapters de harness iniciam cada agente em sua TUI nativa ou via ACP dentro de seu próprio workspace.
• Worktrees isolam cada worker baseado em Git em seu próprio branch; workers Scratch recebem um diretório gerenciado pelo AO, sem branch.
• O Main Orchestrator supervisiona o production_artifacts/state.json de outros projetos a partir de um workspace scratch; os orchestrators de projeto planejam e delegam para workers.

Aprofundamento: docs/architecture.md.

📦 Instalação

| Caminho | Comando | Notas | |---|---|---| | Instalador AOS (principal) | npx -y @hybridlabor-api/aos@latest | Coloca o ao em ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\ao) e executa ao service install para registrar o serviço de inicialização automática. | | Pacote npm | npx @hybridlabor-api/bdb-agent-orchestrator | Inicia o binário ao encontrado no pacote, em ~/.local/bin/ao ou no diretório de instalação do Windows; exibe uma dica de build se nenhum existir. | | Build a partir do código-fonte | veja abaixo | Requer Go e Node. | | Apenas inicialização automática | ao service install | Também uninstall, status, logs. Log: ~/.ao/daemon.log. |

Requisitos: Node >=20.19.0 (veja engines), git e pelo menos uma CLI de agente.

git clone https://github.com/hybridlabor-api/bdb-agent-orchestrator.git
cd bdb-agent-orchestrator/backend
go build -o ./bin/ao ./cmd/ao

Pré-requisitos, configuração do frontend e testes: docs/development.md.

| Variável | Padrão | Finalidade | |---|---|---| | AO_PORT | 3101 | Porta de bind do daemon | | AO_DATA_DIR | ~/.ao/data | Diretório de estado persistente | | AO_RUN_FILE | ~/.ao/running.json | Arquivo de handshake do daemon |

Detalhes: docs/daemon-environment.md.

[!NOTE] ao start é um bootstrapper do upstream que baixa o app desktop do upstream. Neste fork, use ao service install (ou o instalador AOS) para executar o daemon.

🔌 Harnesses suportados

27 agentes de código em um único fluxo supervisionado, via Chat estruturado (ACP) ou a interface de terminal nativa do agente.

[!NOTE] O mapeamento de harness por papel (RoleHarnesses) é uma adição do BDB: cada papel AOS pode rodar em um harness diferente.

🧩 O que o BDB adiciona ao upstream

• brainwatch - observa os diretórios de transcripts dos agentes para sessões ativas e históricas, incluindo vínculos entre subagent e pai.
• Ciclo de vida do serviço - ao service install|uninstall|status|logs para LaunchAgent do macOS, inicialização do Windows e unidade de usuário systemd do Linux.
• Main Orchestrator - um orchestrator em workspace scratch que supervisiona o production_artifacts/state.json de outros projetos.
• Projetos e papéis AOS - ao project init --aos, ao spawn --role, assistente AOS e pipeline board.
• BDB Board v3 - layout Kanban/atenção, barra lateral agrupada por harness, lista de subagents, rebaixamento de sessões ativas obsoletas após 15 minutos.
• Provider de sandbox BDB (experimental) - provider do AO Cloud contra o gateway BDB que expõe sandboxes Incus.
• Disciplina de merge do fork - BDB_CUSTOMIZATIONS.md registra cada arquivo do upstream modificado; UPSTREAM_SYNC.md descreve o fluxo de sincronização.

🧱 Projetos e pipelines AOS

ao project init --aos      # scaffold an AOS workspace (production_artifacts/state.json, .agents/AGENTS.md)
ao spawn --name plan --role architect

O dispatcher AOS executa um ciclo de vida de seis fases: plan, gate, build, review, ship, done. Papéis de worker: architect, techlead, ui_ux, engineering, media_eventtech, reviewer, shipping. O assistente AOS do app desktop oferece seis pipelines e um gate do Plan Canvas.

👁️ Brainwatch e ciclo de vida do serviço

O daemon inicia o brainwatch na inicialização; ele varre os diretórios raiz de transcripts, acompanha subagents e ignora transcripts inalterados por tamanho e mtime. O próprio daemon é mantido ativo pelo serviço da plataforma:

ao service install
ao service status
ao service logs

| Sistema operacional | Backend | |---|---| | macOS | LaunchAgent, label com.bdb.ao.daemon | | Windows | Pasta Inicializar (Startup\ao-daemon.vbs) | | Linux | unidade de usuário systemd |

🖥️ Workers, orchestrator, Kanban

Um worker é uma tarefa, um agente de código e um workspace isolado. O orchestrator de projeto planeja em todo o repositório e inicia ou redireciona workers. O Kanban deriva a coluna de cada card a partir de fatos de sessão, PR, CI e review: Working, Needs you, In review, Ready to merge.

☁️ AO Cloud e sandbox BDB (opcional, experimental)

cloud/ contém os serviços do AO Cloud. O provider de sandbox BDB conversa com o gateway BDB e está fixado ao perfil Incus profile-ao-sandbox; o contrato do gateway é provisório. Stack local: npm run cloud:local (parar com npm run cloud:local:down). Veja docs/cloud-development.md.

🔗 Ecossistema BDB

| Módulo | Função | |---|---| | AOS | Instalador do Agent OS: skills, servidores MCP, gate hooks; instala o ao e seu serviço | | memB (@hybridlabor-api/memb) | Memória vetorial local e offline com servidor MCP e WebUI | | Synapse (@hybridlabor-api/bdb-synapse) | Cidade de código 3D que reproduz sessões de agentes | | Heimdall Token Saver (@hybridlabor-api/heimdall-token-saver) | Comprime saídas repetidas de CLI via ambient hooks |

As descrições dos módulos e opções de instalação são mantidas no README do AOS.

🛠️ Desenvolvimento

npm run lint        # go test + golangci-lint
npm run api         # regenerate OpenAPI spec and TS client

Leia AGENTS.md (layout, comandos, regras rígidas), DESIGN.md e docs/development.md. Execute ao preview <url> para mostrar alterações do frontend no painel de navegador do app desktop.

⚙️ CI/CD e releases

| Workflow | Finalidade | |---|---| | go.yml | Build, testes e lint do backend | | frontend.yml | Typecheck, testes e verificações de empacotamento do frontend | | mobile.yml | Verificações do app mobile complementar | | cli-e2e.yml | Testes end-to-end da CLI (nativo e contêiner de instalação limpa) | | e2e-gate-tests.yml | Testes de contrato de veredito | | gitleaks.yml | Varredura de segredos | | release-please.yml | PRs de release e npm publish |

Fluxo de release: Conventional Commits no main -> release-please abre um PR de release (manifesto .release-please-manifest.json) -> merge -> o workflow verifica npm view e executa npm publish --access public.

📚 Documentação

| Documento | Comece aqui quando precisar de | |---|---| | docs/architecture.md | Modelo mental do backend, ciclo de vida, persistência, CDC | | docs/backend-code-structure.md | Responsabilidade por pacote | | docs/cli/README.md | Comportamento da CLI e mapeamento de rotas do daemon | | docs/development.md | Pré-requisitos, build, testes | | docs/daemon-environment.md | Ambiente do daemon | | docs/STATUS.md | O que é entregue no main e o que está em andamento | | docs/documentation-map.md | Quais documentos são contratos e quais são prosa |

🤝 Contribuindo

Abra issues e PRs em https://github.com/hybridlabor-api/bdb-agent-orchestrator/issues. Use Conventional Commits (o release-please deriva as versões deles). Leia antes o CONTRIBUTING.md.

🔗 Links

• npm: @hybridlabor-api/bdb-agent-orchestrator
• Código-fonte e issues: https://github.com/hybridlabor-api/bdb-agent-orchestrator
• AOS: hybridlabor-api/aos
• Reportar um bug: abrir uma issue

[!NOTE] O AO inclui telemetria de produto. O comportamento e o opt-out pelas variáveis de ambiente AO_TELEMETRY_* estão descritos em docs/telemetry.md.

📜 Licença

Apache License 2.0. Fork de Untrivial-ai/agent-orchestrator.