MAGO Voice

Plataforma de reunioes de trabalho por voz entre humanos (PO/dev) e subagents Claude reais com papeis (PO, Dev, QA). O Gemini Live API modera a conversa (STT+TTS bidirecional); quando precisa de analise especializada, delega via function call pra subagents Claude spawnados via CLI (usa sua subscription, sem API key). O mago-board (127.0.0.1:5008) e source-of-truth das tasks/sprints.

Arquitetura

Clean Architecture + DDD + alchemy-first (@tecnomancy/alchemy Result/Option/pipe). 4 camadas:

presentation/  --> composition root + WS gateway + web UI (HTML+JS vanilla)
application/   --> use cases + ports (MeetingRepo, AgentBridge, VoiceSession, BoardGateway, EventBus)
domain/        --> Meeting aggregate, AgentPersona, errors (zero IO, tacit)
infrastructure/ --> adapters: Gemini Live, Claude CLI spawn, mago-board REST, in-memory repo/bus
modules/       --> bounded contexts (meetings, osint) plugaveis

Ver CONSTITUTION.md, ARCHITECTURE.md, docs/adrs/, docs/specs/.

Setup

Requer Bun >= 1.3.

bun install
cp .env.example .env
# preenche GEMINI_API_KEY (obrigatorio)
# demais envs tem default sensato

Desenvolvimento

bun run dev         # --watch, TS direto
bun run typecheck   # tsc --noEmit
bun test            # unit + contract
bun run lint        # eslint (rejeita try/catch fora de infra)
bun run build       # bundle pra dist/
bun run start       # roda o build

Endpoints

• GET / — UI HTML
• GET /health — {ok:true, tools:N}
• WS /ws/voice — protocolo JSON bidirecional (ver docs/specs/003-voice-gateway.spec.md)

Tools expostos pro Gemini Live

Meetings module

• query_sprint({project?, status?}) — lista items do board
• get_item_detail({issue_number}) — detalhes
• update_item_status({issue_number, status}) — move card
• create_board_item({title, body?, size?, priority?, type?}) — cria card
• ask_agent({role, question}) — dispara subagent (po/dev/qa) via claude CLI

OSINT module (legacy preservado)

run_scan, run_full_recon, get_job_status, list_recent_jobs, lookup_threat_intel, get_entity_info

Fluxo de reuniao

 mic -> WS -> VoiceGateway -> GeminiLiveSession
                                      |
                            function_call: ask_agent(role, question)
                                      |
                           application.dispatchToAgent
                                      |
                           ClaudeCliAgentBridge (spawn claude -p)
                                      |
                           subagent usa mago-board MCP tools
                                      |
                           AgentResponse -> Gemini -> audio -> browser

Variaveis de ambiente

Var	Default	Descricao
GEMINI_API_KEY	obrigatorio	Gemini Live API key
MAGO_BOARD_URL	http://127.0.0.1:5008	Board REST base
MAGO_API_URL	https://mago.team/mancer/api	OSINT mancer
MAGO_API_TOKEN	(opcional)	OSINT auth
CLAUDE_BIN	claude	path do CLI
CLAUDE_MODEL	sonnet	sonnet/opus/haiku
CLAUDE_TIMEOUT_MS	60000	timeout do dispatch
PORT	5009	HTTP+WS port
LOG_LEVEL	info	debug/info/warn/error

Estrutura do repo

src/
  domain/           -- Meeting, Participant, Turn, AgendaItem, AgentPersona
  application/      -- use cases + ports (interfaces)
  infrastructure/   -- Gemini, Board, ClaudeCLI, repo, bus, WS gateway
  modules/          -- meetings/, osint/ (bounded contexts)
  presentation/     -- server.ts composition root + web/ static UI
  shared/           -- alchemy, logger, config, ids
tests/
  unit/             -- domain + application (pure)
  contract/         -- adapters mocked
docs/
  adrs/             -- ADR-000[1-5]
  specs/            -- 001-003

Testando sem credenciais

bun test roda local sem tocar Gemini/Claude. Os adapters tem contract tests com fetch mock e spawn falso.

Pra smoke boot do servidor sem Gemini real:

GEMINI_API_KEY=fake PORT=5200 bun run dev
curl http://localhost:5200/health   # {"ok":true,"tools":11}

O handshake do WebSocket falha sem key real, mas a estrutura (HTML, health, fluxo de ports) sobe.