Arquitetura
packages/
engine/ @oharness/engine — the harness; does not know what drives it
server/ @oharness/server — browser frontend, HTTP + SSE; deployable alone
sync/ @oharness/sync — optional transcript sync server
cli/ oharness — terminal and headless frontends, all four bins
As dependências seguem um único sentido: uma interface consome o engine, nunca o contrário. Desde a divisão em pacotes, o resolvedor garante a maior parte disso sozinho — um import não declarado simplesmente falha —, mas um caminho relativo que sobe de um pacote para dentro de outro ainda seria resolvido, então o teste de camadas também verifica isso. O engine não contém nenhum console.*, nenhum process.stdout, e nunca mexe no TTY. Quando precisa perguntar algo ao usuário, ele chama um permissionPrompt injetado; quando tem progresso a relatar, emite um AgentEvent. Quem renderiza é problema da interface.
A fronteira é garantida
Uma convenção de camadas que só existe em um documento dura até a primeira pessoa com pressa. test/layering.test.ts lê o código-fonte real:
| Verificação | Por quê |
|---|---|
| O engine não importa nenhuma interface | Uma dependência invertida acaba com a possibilidade de embutir o engine e impede que uma segunda interface seja adicionada |
| O engine nunca escreve no stdout | O stdout pertence a quem estiver renderizando |
| Só o logger escreve no stderr | Diagnósticos no canal convencional, por um único ponto que a interface pode redirecionar |
| O engine nunca mexe no stdin nem no readline | Em uma execução agendada não há ninguém no teclado |
| O ponto de entrada da biblioteca não exporta nenhuma interface | Um app que embute o engine não deveria ser arrastado para uma interface de terminal |
Histórico neutro
As transcrições de sessão são armazenadas no formato definido em packages/engine/src/core/types.ts, e não no formato de nenhum fornecedor. Um detalhe merece destaque: o resultado de uma ferramenta carrega toolName além de toolCallId, porque o Gemini identifica resultados de ferramentas pelo nome da função, e não pelo id da chamada.
As flags de capacidade são essenciais
Os modelos divergem quanto aos parâmetros de raciocínio, e enviar o formato errado resulta em um 400, não em uma degradação. Por isso as diferenças são dados em ModelSpec: thinkingMode, effortLevels, thinkingLevelMap, maxEffortWithThinkingDisabled, supportsSampling. O adaptador decide com base nelas a cada requisição. Uma listagem de /models pode dizer que um modelo raciocina, mas não quais níveis ele aceita, então os modelos descobertos recebem seus níveis dos dados por modelo do pi-ai sempre que ele conhece o modelo.
A compactação não destrói
Quando a transcrição é resumida, o que foi descartado é acrescentado a um arquivo morto ao lado da sessão. A ferramenta recall faz buscas nele, então um detalhe compactado pode ser recuperado em vez de se perder. A compactação também nunca separa uma chamada de ferramenta do seu resultado — uma transcrição em que isso acontece é rejeitada por todos os provedores.