Architettura
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
Le dipendenze vanno in un solo senso: un'interfaccia consuma il motore, mai il contrario. Dalla suddivisione in pacchetti, il resolver fa rispettare da solo gran parte di questa regola — un import non dichiarato semplicemente fallisce — ma un percorso relativo che esce da un pacchetto per entrare in un altro verrebbe comunque risolto, quindi il test di stratificazione controlla anche questo. Il motore non contiene console.* né process.stdout, e non tocca mai il TTY. Quando deve chiedere qualcosa all'utente chiama un permissionPrompt iniettato; quando ha avanzamenti da comunicare emette un AgentEvent. Chi visualizza è affare dell'interfaccia.
Il confine è garantito
Una convenzione di stratificazione che vive solo in un documento dura fino alla prima persona che ha fretta. test/layering.test.ts legge il codice sorgente reale:
| Asserzione | Perché |
|---|---|
| Il motore non importa alcuna interfaccia | Una dipendenza inversa mette fine all'incorporabilità e impedisce di aggiungere una seconda interfaccia |
| Il motore non scrive mai su stdout | stdout appartiene a chiunque stia visualizzando |
| Solo il logger scrive su stderr | Diagnostica sul canale convenzionale, attraverso un unico punto che un'interfaccia può reindirizzare |
| Il motore non tocca mai stdin né readline | In un'esecuzione pianificata non c'è nessuno alla tastiera |
| L'entry della libreria non esporta alcuna interfaccia | Un'app che incorpora il motore non dovrebbe ritrovarsi trascinata in una UI da terminale |
Cronologia neutrale
Le trascrizioni delle sessioni vengono salvate nella forma definita in packages/engine/src/core/types.ts, non nel formato di un fornitore. Un dettaglio si guadagna il suo posto: un risultato di strumento porta toolName oltre a toolCallId, perché Gemini indicizza i risultati degli strumenti per nome di funzione anziché per id di chiamata.
I flag di capacità sono portanti
I modelli non concordano sui parametri di ragionamento, e inviare la forma sbagliata produce un 400, non un degrado. Le differenze sono quindi dati su ModelSpec: thinkingMode, effortLevels, thinkingLevelMap, maxEffortWithThinkingDisabled, supportsSampling. L'adattatore li usa per decidere a ogni richiesta. Un elenco /models può dire che un modello ragiona ma non quali livelli accetta, quindi i modelli rilevati ricevono i loro livelli dai dati per modello di pi-ai ovunque pi-ai conosca il modello.
La compattazione non distrugge
Quando la trascrizione viene riassunta, ciò che è stato scartato viene aggiunto a un archivio accanto alla sessione. Lo strumento recall lo consulta, così un dettaglio compattato resta recuperabile invece di andare perso. La compattazione inoltre non separa mai una chiamata di strumento dal suo risultato — una trascrizione che lo fa viene rifiutata da ogni fornitore.