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çãoPor quê
O engine não importa nenhuma interfaceUma dependência invertida acaba com a possibilidade de embutir o engine e impede que uma segunda interface seja adicionada
O engine nunca escreve no stdoutO stdout pertence a quem estiver renderizando
Só o logger escreve no stderrDiagnósticos no canal convencional, por um único ponto que a interface pode redirecionar
O engine nunca mexe no stdin nem no readlineEm uma execução agendada não há ninguém no teclado
O ponto de entrada da biblioteca não exporta nenhuma interfaceUm 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.