Interfaces
Três consumidores do mesmo fluxo de AgentEvent, mais um shell de desktop em volta do terceiro. Adicionar cada um deles não exigiu nenhuma mudança no engine, e esse é justamente o objetivo da separação.
Terminal
oharness
Uma interface em tela cheia: histórico rolável, uma caixa de entrada fixa, uma linha de status e sobreposições para aprovações e para o seletor de modo. Escrita sem biblioteca de TUI, então algumas coisas tiveram de ser conquistadas em vez de presumidas:
- Largura CJK. Caracteres do leste asiático ocupam duas colunas. Medi-los como uma faz todas as linhas abaixo quebrarem no lugar errado.
- Restaurar o terminal. A falha que importa não é um quadro mal desenhado, e sim sair sem deixar o modo raw: o usuário fica sem eco e sem cursor e precisa digitar
resetàs cegas. A restauração está ligada a todos os caminhos de saída, incluindo exceções não capturadas, e é comprovada por um teste que derruba um processo real. - Bracketed paste. Sem ele, colar três linhas dispara três turnos.
Entrada por pipe, CI e terminais simples caem em um loop baseado em linhas que se comporta do mesmo jeito e continua scriptável.
Os artefatos aparecem aqui como uma linha cada — título, tipo, tamanho, revisão. Os tipos que um terminal consegue mostrar honestamente são mostrados; uma página, uma imagem ou um SVG avisa isso e indica a interface do navegador. Essa recusa é uma resposta declarada, não uma omissão: todo tipo tem uma entrada em uma tabela que cada interface precisa preencher, e um tipo adicionado ao engine sem ela faz um teste falhar em vez de aparecer como um espaço em branco silencioso em uma das três.
Headless
oharness-headless "a task"
echo "a task" | oharness-headless
O stdout carrega JSONL e nada mais, então vai direto por pipe para o jq. Os diagnósticos vão para o stderr. O código de saída é 1 se a execução falhou.
Não há ninguém presente para responder a um pedido de permissão, então tudo o que perguntaria é negado e informado como um evento. Aprovar em silêncio tornaria as execuções sem supervisão mais perigosas do que as supervisionadas, o que é o inverso do certo. Autorize o trabalho antecipadamente com regras ou passe --permission-mode.
Pelo mesmo motivo, ninguém responde a uma pergunta de ask_user. A ferramenta retorna na hora, dizendo ao modelo para escolher um padrão sensato e declarar a suposição, e o JSONL ainda carrega question_request e question_result para que um supervisor veja o que ele queria perguntar.
Navegador
oharness-web
Renderização de Markdown, cartões de ferramenta recolhíveis, diffs de arquivos, uma prateleira de artefatos, abas de sessão, um seletor de projeto, seletores de modelo e de permissão, anexos.
Onde uma sessão roda é definido no compositor, ao lado do modelo e do modo de permissão — as três coisas sob as quais esta mensagem está prestes a ser enviada. Ele começa no projeto já aberto, que é a resposta quase sempre, e o menu oferece todos os diretórios abertos aqui, além de uma caixa de diálogo de pasta para um que ainda não foi aberto. Isso só fica ali até a sessão dizer alguma coisa: uma transcrição pertence à árvore em que foi gravada, então mudar a pasta antes da primeira mensagem recomeça a sessão na nova pasta e descarta a original intocada em vez de arquivá-la na barra lateral.
Livrar-se de um projeto são dois atos diferentes, e eles ficam em dois lugares diferentes porque não têm nada em comum além da palavra. Remover da lista — o ✕ em uma linha do seletor de projeto — esquece um caminho: nada do que foi gravado é tocado, e o projeto mantém seu lugar na barra lateral enquanto tiver sessões ali, porque a barra lateral agrupa pela árvore em que uma transcrição foi gravada, e não por essa lista. O que remove um projeto da barra lateral é excluir as sessões dele, o que fica no menu do cabeçalho do projeto, pergunta uma vez e diz o que leva: transcrições, artefatos e o registro de permissões, aqui e em qualquer dispositivo com que você sincroniza. O diretório e os arquivos dele não são tocados em nenhum dos casos. Excluir o projeto em que você está move a janela para outro antes.
Uma sessão leva sua árvore consigo, e as abas já abertas levam as delas — começar a trabalhar em outro projeto as deixa rodando, e uma aba mostra o nome do seu projeto assim que duas delas divergem. Clicar na barra lateral em uma transcrição de outro projeto faz o mesmo: ela abre no harness daquele projeto, em vez de mudar tudo de lugar. O seletor no topo da barra lateral continua sendo a forma de dizer “agora estou trabalhando aqui”, e a última árvore em que uma sessão foi iniciada ou reaberta é a que a próxima execução abre.
O compositor direciona uma mensagem para as coisas de duas formas, separadas pelo lugar onde a coisa está.
+ alcança esta máquina. Anexar arquivos ou fotos e Anexar pastas abrem a caixa de diálogo da própria plataforma no host em que o agente roda, porque o input de arquivo do navegador omite o caminho de propósito, o que é certo para uma captura de tela colada e inútil para um log que o agente poderia simplesmente abrir. São duas linhas em vez de uma porque as caixas de diálogo por trás delas são duas: só o macOS tem um painel que aceita um arquivo e uma pasta na mesma passada, e uma linha prometendo os dois abriria, em outros sistemas, só um deles. Ao lado delas ficam os conectores MCP a que este harness está conectado, com a contagem de ferramentas em tempo real, os plugins que ele carregou e o upload que de fato envia bytes. Uma escolha vira um chip, e o servidor transforma os chips em um bloco curto acima do prompt: os caminhos são nomeados, não embutidos, então o agente lê o que precisa com as ferramentas que você pode vê-lo usar.
Em Conectores fica a lista dos que estão disponíveis — distribuída como dados em src/mcp/registry.json e complementada por ~/.oharness/connectors.json, então adicionar uma entrada ao menu nunca significa editar código. Escolher um faz as duas metades: o servidor é conectado agora, então as ferramentas dele podem ser usadas no próximo turno, e a declaração é gravada na configuração do usuário para voltar amanhã. Um que não consegue iniciar é removido de novo, em vez de ficar como uma linha morta com uma entrada em um arquivo de configuração por trás.
Um conector remoto responde à primeira requisição com um 401, e isso não é uma falha — é o início de um login, então a linha diz isso e o oferece em vez de um erro em vermelho. O que vem depois é descoberta, toda ela, nada configurado: o desafio nomeia o documento de recurso protegido do servidor, que nomeia um servidor de autorização, cujos metadados nomeiam os endpoints, e um cliente é registrado nele na hora. O navegador abre, o redirecionamento cai em um listener de loopback que este processo mantém durante o fluxo, e os tokens vão para o auth.json sob a mesma permissão 0600 que os provedores de modelos recebem. Nada nessa cadeia é específico de um fornecedor, e esse é o ponto: um servidor para o qual ninguém adicionou uma linha funciona tão bem quanto um que tem.
A lista continua curta porque é uma conveniência, não um limite. O que ela poupa é saber uma URL. O critério para uma linha é que o servidor seja publicado por quem é dono dos dados que ele expõe, fale Streamable HTTP em vez do transporte antigo de dois canais e possa ser usado depois de um clique ou de uma variável nomeada; npm run verify:connectors pergunta a cada remoto quem o autoriza e informa o que voltou, que é o que a data verified no registro significa.
Os tokens são resolvidos a cada requisição, e não capturados quando o transporte é construído — uma sessão longa dura mais que um token de acesso em cerca de uma hora, e um cabeçalho fotografado na conexão é uma sessão que morre em silêncio no meio. Uma renovação que falha também não é fatal: o token vencido é enviado, o servidor responde 401, e esse caminho já sabe pedir um novo login.
Cada linha leva a marca do seu fornecedor, e a página não busca nenhuma. Doze linhas seriam, caso contrário, doze requisições de imagem a terceiros, cada uma avisando a um fornecedor que este usuário abriu o menu antes de conectar qualquer coisa — em uma página cuja proposta inteira é não falar com ninguém. Por isso, quem resolve o ícone é o servidor: ele lê o que o site do fornecedor declara na própria marcação, recorre a /favicon.ico se preciso, confere se o que voltou é mesmo uma imagem, e não um app de página única respondendo 200 com ele mesmo, e guarda os bytes em disco. A página só faz requisições a esta origem. Um site sem ícone utilizável não custa nada — a linha desenha um bloco com uma letra e o conector funciona exatamente igual.
Um servidor que prefere uma chave de API simples usa ${env:NAME} — em um cabeçalho, um argumento, uma URL ou no ambiente de um processo filho. A referência é o que vai para o arquivo de configuração, e o valor é lido do ambiente quando o servidor inicia, então uma configuração compartilhada, sincronizada ou commitada nunca contém a chave. Uma variável não definida é apontada antes de se tentar a conexão, porque “MCP_TOKEN is not set” é uma frase sobre a qual dá para agir, e o que o servidor diz sobre uma credencial vazia não é.
Em Plugins fica o que este harness carregou, e a lista não é mais só o que alguém copiou à mão para ~/.oharness/plugins. Um plugin aqui é um manifesto mais uma pasta skills/ e uma agents/, e um plugin do Claude Code também é — a mesma ideia alcançada duas vezes, em dois layouts de arquivos. Ler os dois leva umas vinte linhas, e é a diferença entre um painel com um ecossistema por trás e um painel vazio em uma máquina que já tem vinte plugins instalados. Nada é importado: o diretório fica onde o instalador o colocou e é lido ali mesmo, então atualizá-lo lá o atualiza aqui.
O que é adotado depende de onde o plugin veio, e a linha divisória fica entre o que o agente lê e o que roda por conta própria. Skills e agentes são texto, consultados quando o agente decide que são relevantes. Um hook é uma linha de comando que dispara em um evento do ciclo de vida, e um servidor MCP é um processo iniciado na abertura. Esses dois são lidos e informados — a linha diz o que o plugin traz —, mas não ativados a partir do diretório de outro programa, porque o usuário que os instalou ali os direcionou para aquele programa. Um servidor vindo de um deles é adicionado do jeito normal, por Conectores, com a confirmação e o login que esse caminho já tem.
@ alcança o projeto. Ele faz uma busca aproximada na árvore a partir do cursor e solta o caminho na frase no ponto em que ele deveria ficar — “compare @a com @b” diz algo que dois chips acima da caixa não dizem. É também por isso que o + não traz um navegador de projeto: os arquivos que as pessoas mais citam estão no projeto, e o @ já os nomeia.
Alcançar esta porta equivale a ter um shell nesta máquina. O agente por trás dela grava arquivos e roda comandos, então o servidor escuta só no loopback e exige um token gerado do zero a cada execução e nunca persistido. A comparação é de tempo constante: um
!==simples vaza um token, um caractere de cada vez, para qualquer coisa capaz de medir a resposta.
A página é totalmente autocontida — sem CDN, sem fontes externas. Uma página capaz de controlar um shell não pode dar a um terceiro execução de script nesse contexto. Pelo mesmo motivo, o renderizador constrói nós do DOM e define textContent; ele nunca atribui innerHTML com conteúdo vindo de um modelo, do resultado de uma ferramenta ou de um arquivo.
Os artefatos são a única exceção, e são o motivo de a regra ser enunciada com tanta precisão. Todo o valor de um artefato HTML está em o navegador executá-lo, então ele não pode passar por esse renderizador — ele é servido por uma rota própria, dentro de um iframe com sandbox="allow-scripts" e sem allow-same-origin, sob uma Content-Security-Policy cujo connect-src 'none' é a parte que sustenta tudo: uma origem opaca impede que um frame leia uma resposta, não que envie uma requisição, e o servidor do outro lado controla um agente que roda comandos de shell. Essa rota é protegida por uma credencial própria, e não pelo token de sessão, porque um documento em sandbox consegue ler a própria URL.
Analytics
Desativado. Nada é enviado a lugar nenhum, a menos que o servidor seja iniciado com uma chave de projeto do PostHog, que é a única coisa que o ativa:
| Variável | Efeito |
|---|---|
OHARNESS_POSTHOG_KEY | Uma chave de projeto do PostHog. Definida, a página carrega o PostHog e informa o uso de recursos; não definida, nenhum código de analytics chega ao navegador |
OHARNESS_POSTHOG_HOST | O padrão é https://us.i.posthog.com. A nuvem da UE é https://eu.i.posthog.com; uma instância auto-hospedada é a sua própria origem |
Ativá-lo aceita a troca que o parágrafo acima recusa, então vale saber exatamente o que isso compra e quanto custa. O que é enviado: um evento por ação realizada — app_opened, panel_opened, prompt_sent, model_switched, permission_answered — apenas com propriedades enumeráveis, como qual painel ou qual modelo. O que não é enviado: prompts, caminhos de arquivo, diffs, transcrições, títulos de sessão ou a URL da página. O autocapture fica desativado, então nenhum clique é registrado pelo texto do botão; a gravação de sessão fica desativada; e as propriedades de URL são bloqueadas duas vezes, porque a URL carrega o token que equivale a um shell. Ninguém é identificado: nenhum perfil de pessoa é criado e identify nunca é chamado. src/analytics.ts é curto e é tudo o que existe.
Desktop
cd desktop && npm install && npm start
Uma janela Electron em volta da interface web. Ela inicia o servidor no mesmo processo, então há um processo para supervisionar em vez de um órfão segurando a porta, e entrega o token à página por um preload, e não pela barra de endereço — uma URL com um token acaba no histórico, no título da janela e em toda captura de tela de um relatório de bug.
O Electron fica em desktop/, um pacote separado, para que a biblioteca publicada mantenha sua única dependência de runtime. Um teste garante isso.
Sincronização
oharness-sync --port 4483 # serve
oharness-sync token alice # issue a token, printed once
A metade opcional. Nada aqui roda a menos que alguém o inicie: um harness sem bloco sync na configuração nunca abre um socket, e o armazenamento local é completo por si só. Ele existe porque duas máquinas não conseguem passar uma transcrição uma para a outra sem um lugar onde deixá-la — não porque o harness precise de um backend.
Ele é burro de propósito. Ordena blobs opacos e os devolve; não interpreta mensagens, não chama modelos nem sabe o que é uma ferramenta. É isso que o torna seguro para deixar rodando, e o que mantém o formato das mensagens livre para mudar sem deploy.
O TLS não é tratado aqui. Coloque-o atrás de um proxy reverso que termine o HTTPS: um bearer token em texto puro em uma rede não confiável é um token que qualquer pessoa nessa rede passa a ter.