Harness

Una sessione esegue un harness per agenti, harness standard o harness sperimentale. In questa pagina trovi come un progetto ne seleziona uno e le funzionalità supportate da ciascuno.

Un harness è il runtime dell’agente all’interno della sandbox di una sessione. Esegue il ciclo del modello, chiama gli strumenti e produce la trascrizione. Beeuni ne offre due: harness standard (predefinito) e harness sperimentale. Ogni sessione ne esegue esattamente uno.

Entrambi gli harness leggono lo stesso progetto: beeuni.yaml, i file dell’agente in agents/, le skill in skills/, il AGENTS.md radice e memory/. I client (web, CLI, TUI, dispositivi mobili, SDK) li leggono entrambi tramite la stessa API di sessione. Le differenze riguardano le funzionalità di sessione nella matrice qui sotto e i file che ciascun harness legge per la propria configurazione.

Come una sessione seleziona il proprio harness

Beeuni decide quando una sessione viene avviata, riavviata o ripresa. Una sessione in esecuzione mantiene il proprio harness fino a quel momento.

Regola, in ordine	Harness
Il flag `llm_gateway` del progetto è disattivato	harness standard
Il flag `pi_harness` del progetto è attivato	harness sperimentale
`beeuni.yaml` imposta `runtime: pi`	harness sperimentale
Qualsiasi altro caso	harness standard

harness sperimentale chiama i modelli solo tramite il gateway LLM di Beeuni. Un progetto con llm_gateway disattivato avvia harness standard, indipendentemente dal flag o da quanto indicato nel manifest. Vedi Modelli.
runtime è una chiave del manifest beeuni_version: 2. Un progetto legacy beeuni.toml non può impostarla. Vedi il riferimento del manifest.
pi_harness è un flag di funzionalità per progetto, disattivato per impostazione predefinita. Vedi Flag di funzionalità.

Per sapere quale harness esegue una sessione, leggi harness.id nella risposta GET /beeuni/health del daemon della sandbox: opencode o pi.

Funzionalità supportate da ciascun harness

Un harness elenca le funzionalità di sessione opzionali che fornisce nell’array capabilities di GET /beeuni/health. Un client nasconde un controllo quando capabilities della sessione non contiene l’id. Il controllo dell’SDK è runtimeSupports.

Entrambi gli harness

Funzionalità	harness standard	harness sperimentale
Turni di chat, streaming, interruzione	Sì	Sì
`.md` dell’agente: prompt, `model`, `variant`, `mode`, `permission`, `temperature`, `top_p`, `steps`	Sì	Sì. harness sperimentale non applica `options` (opzioni del provider).
Accesso agli strumenti per agente (`agents.<name>.tools` in `beeuni.yaml`: `all`, `none`, un elenco, `exclude`)	Sì	Sì
Regole `permission` per agente e richieste di autorizzazione	Sì	Sì
Domande (strumento `question`)	Sì	Sì
Il file delle regole `AGENTS.md` nella radice del progetto, oppure `CLAUDE.md` se la radice non contiene `AGENTS.md`	Sì. harness standard legge anche il file nelle directory genitrici di `/workspace` e legge `/workspace` mentre applica una release di configurazione.	Sì, solo il file radice. Fa parte del prompt di sistema della sessione e di ogni subagente. Con le release di configurazione attive, harness sperimentale legge la copia della release.
Subagenti (strumento `task`), `session.subagents`	Sì	Sì: `general`, `explore` (sola lettura) e ogni agente del progetto con `mode: subagent` o `all`. Un subagente non può avviare un altro subagente.
Skill (`skills/` e le skill gestite di `beeuni-*`), con l’autorizzazione `skills` dell’agente	Sì. L’agente carica una skill con lo strumento `skill`.	Sì. Il prompt di sistema elenca ogni skill autorizzata; l’agente legge il file.
Strumenti Beeuni: `web_search`, `image_search`, `scrape_webpage`, `memory`, `show`. Tutti e cinque se in `beeuni.yaml` non è presente la chiave `tools:`; se è presente, quelli indicati come `beeuni:<name>`	Sì	Sì
Strumenti di progetto (`tools:` in `beeuni.yaml`)	Sì	Sì
Release di configurazione, `config.release.v1`	Sì	Sì
Compattare (riepilogare) la conversazione, su richiesta e automaticamente quando si avvicina alla finestra di contesto del modello, `session.compact`	Sì	Sì. Una richiesta al modello che supera la finestra compatta la conversazione e viene ritentata una volta.
Comandi slash del progetto, `session.commands`	Sì, da `commands/` nella directory di configurazione di harness standard.	Sì, dai modelli di prompt in `prompts/` nella directory di configurazione di harness sperimentale e nei pacchetti harness sperimentale. harness sperimentale non legge `commands/` di harness standard.
Terminale nella sandbox (PTY)	Sì	Sì
Strumenti `bash`, `read`, `write`, `edit`, `glob`, `grep`; segreti nella shell; CLI `beeuni`	Sì	Sì

Gli strumenti Beeuni e gli strumenti di progetto sono indipendenti dall’harness: il daemon della sandbox esegue un modulo per ogni strumento, per entrambi gli harness, con gli stessi nomi, argomenti e output. harness sperimentale li chiama nel processo del daemon; harness standard li chiama tramite un plugin scritto dal daemon. Entrambi gli harness ricevono lo stesso elenco: uno strumento Beeuni non incluso nella chiave tools: del progetto non è disponibile in nessuno dei due. Un progetto che conserva copie degli strumenti Beeuni in harnesses/opencode/tools/ mantiene le proprie copie in harness standard finché non le elimina.

Gli strumenti web seguono le chiavi di autorizzazione websearch (web_search, image_search) e webfetch (scrape_webpage) in entrambi gli harness. In harness standard questi strumenti non possono chiedere: una regola ask li nega. In harness sperimentale una regola ask genera una richiesta di autorizzazione. In harness sperimentale, un comando memory che modifica un file segue edit e view segue read; in harness standard lo strumento è regolato solo da una regola memory.

`AGENTS.md` su harness sperimentale

harness sperimentale inserisce AGENTS.md del progetto nella radice del prompt di sistema come un’unica sezione, <project_instructions path="AGENTS.md">, dopo il prompt dell’agente. Se la radice non contiene AGENTS.md, usa CLAUDE.md, come in harness standard. harness sperimentale non legge alcun AGENTS.md in una sottodirectory o directory genitrice.

Origine. Con le release di configurazione disattivate, harness sperimentale legge /workspace/AGENTS.md. Quando sono attive, harness sperimentale legge la copia nella release e non quella in /workspace: una modifica in /workspace raggiunge la sessione dopo l’unione nel ramo di base. Se sono attive e non c’è una release disponibile (config.source: image-default), harness sperimentale non legge alcun AGENTS.md, così come non legge alcuna skill di progetto.
Quando. harness sperimentale legge il file all’avvio del runtime, quando la configurazione viene ricaricata (una nuova release, un push di /beeuni/env) e dopo un aggiornamento del repository. Non lo legge prima di ogni turno. Una nuova release diventa disponibile al turno successivo senza riavvio; un turno già in corso mantiene il file precedente.
Esclusioni. Un file vuoto, un file che non è un file regolare e un collegamento simbolico che rimanda al di fuori del repository non aggiungono nulla. Gli ultimi due casi generano un avviso nel log del daemon.
Verifica. harness.details.agentsMd nella risposta GET /beeuni/health del daemon indica il file caricato da harness sperimentale: source (release o workspace), path, bytes e sha (i primi 12 caratteri esadecimali del suo sha256). Vale null quando harness sperimentale non ha caricato alcun file.

Funzionalità disponibili oggi solo in harness standard

Funzionalità	Capacità	harness standard	harness sperimentale
Tornare a un messaggio e ripristinarlo. Modifica e nuovo invio usa il riavvolgimento.	`session.rewind`	Sì	No
Server MCP (`mcp` in `opencode.jsonc`)	`session.mcp`	Sì	Nessun client MCP. I connettori funzionano su entrambi gli harness tramite la CLI `beeuni connectors`.
Elenco delle attività (strumento `todowrite`) e scheda del piano	`session.todo`	Sì	No. La scheda del piano rimane vuota.
Collegare il client terminale dell’harness (`beeuni connect`, TUI `Alt+o`)	`session.attach`	Sì	No. Vedi TUI.
Documento di configurazione runtime (`/global/config`)	`session.config`	Sì	No. Agenti e modelli provengono dal progetto in entrambi gli harness.
Creare un fork di una sessione a un messaggio	`session.fork`	Sì	No
Eseguire un comando shell come turno	`session.shell`	Sì	No
Provider di modelli senza il gateway LLM	—	Sì	No. harness sperimentale richiede `llm_gateway` attivo.

Una sessione harness sperimentale risponde a una richiesta per una funzionalità che non offre con 501 feature_not_supported, oppure con 404 per un documento che non ha (/global/config). Non ignora la richiesta.

File di configurazione degli harness

Ogni harness ha una directory dedicata ai file letti solo da quell’harness.

	harness standard	harness sperimentale
Directory	`harnesses/opencode/`, oppure `opencode.config_dir`	`harnesses/pi/`, oppure `pi.config_dir`
Directory legacy	`.beeuni/opencode/`	`.beeuni/pi/`
Contenuti	`opencode.jsonc`, `plugins/`, `tools/`, `commands/`	`settings.json`, `extensions/`, `skills/`, `prompts/`
Estensioni	Plugin e strumenti esclusivi di harness standard in quella directory	Pacchetti harness sperimentale in `harnesses.pi.packages` e file di estensione in `extensions/`

Una sessione harness sperimentale non legge opencode.jsonc, plugins/, tools/ o commands/. Una sessione harness standard non legge la directory di harness sperimentale. Uno strumento necessario a entrambi gli harness è uno strumento di progetto, dichiarato in beeuni.yaml, non un file presente in una delle due directory.

I pacchetti harness sperimentale provengono da packages. Un pacchetto può aggiungere strumenti non disponibili in harness sperimentale, ad esempio un adattatore MCP o uno strumento per le attività. Beeuni carica il pacchetto, ma non verifica i pacchetti di terze parti.