Connettori cloud

connector-cloud è un plugin di architettura di OHarness, non MCP. Cloud detiene la chiave del progetto Composio e la configurazione approvata di app e strumenti. I client usano il proprio accesso OHarness; le credenziali OAuth di Gmail restano presso Composio, limitate all'ID utente OHarness verificato dal server. Non servono nuove tabelle Supabase.

Configurazione

Segreto di runtime del sito Cloud: COMPOSIO_API_KEY. Mai NEXT_PUBLIC_ e mai nel config.json dell'utente, in plugins.json, nel bundle del browser o nel contesto del modello.
Le app abilitate derivano dalle Auth Config del progetto Composio, non da un file. Una Auth Config con una restrizione sugli strumenti è un'app abilitata e quella restrizione è la sua allowlist, quindi una nuova integrazione è un'azione nella dashboard e non un deploy. La derivazione rifiuta invece di presumere: una configurazione che non limita alcuno strumento viene saltata (Composio interpreta l'assenza di restrizioni come tutti gli strumenti del toolkit), due configurazioni abilitate per lo stesso toolkit non ne abilitano nessuna, e configurazioni disabilitate, id inutilizzabili o nomi di strumenti malformati escludono quell'app. I tetti di 20 app e 40 strumenti restano invariati. L'insieme viene risolto una volta per processo, quindi riavvia Cloud dopo una modifica nella dashboard.
Il file Cloud website/connectors.json ora è opzionale e può solo restringere: {"disabled": ["slug"]} esclude un'app senza toccare Composio. Un file che contiene ancora toolkits mantiene il vecchio comportamento esplicito. Il deployment può invece far puntare OHARNESS_CONNECTORS_FILE a un percorso assoluto montato. È volutamente in gitignore, quindi includilo o montalo solo se lo usi.
L'ambiente Supabase esistente del sito convalida i token di accesso OHarness.
cloud.json del client: { "siteUrl": "http://localhost:4000" } opzionale per lo sviluppo locale; il valore predefinito è l'indirizzo pubblico di Cloud. Cambiare l'origine Cloud può richiedere un nuovo accesso. OHARNESS_SITE_URL è una sostituzione alternativa.
plugins.json del client: il plugin predefinito non richiede alcuna voce. Per disattivarlo: { "runtimePlugins": [{ "id": "connector-cloud", "enabled": false }] }.

Crea la Auth Config OAuth di Gmail nella dashboard di Composio per lo stesso progetto della chiave API. Controllane gli scope e usa l'accesso Gmail in sola lettura per le attività di lettura; l'allowlist di esecuzione non sostituisce scope OAuth con il privilegio minimo. La configurazione di esempio contiene segnaposto, non credenziali funzionanti.

Quando usi OHarness_Cloud/dev.sh, imposta le variabili Cloud sul processo website (Next carica website/.env.development.local). L'harness non ha bisogno della chiave Composio. Fallo puntare al sito locale prima di avviarlo, per esempio OHARNESS_SITE_URL=http://localhost:4000 ./dev.sh up harness. up non riavvia i processi in esecuzione; usa restart website harness dopo aver salvato il lavoro. Una modifica a Cloud su localhost non distribuisce l'API sul sito pubblico.

Flusso della conversazione

L'agente chiama cloud_app_tools per elencare le app o scoprire gli schemi e la versione esatti degli strumenti di un'app. È disponibile anche prima che sia connesso un account dell'app.
Viene applicata prima la normale policy dei permessi di OHarness. Se approvato e non collegato, lo strumento corrente resta in attesa e la chat Web mostra Connect / Cancel.
Solo il clic dell'utente su Connect richiede un link ospitato da Composio. Cloud imposta user_id dall'accesso convalidato, mai dall'input del modello.
L'interfaccia apre la pagina di autorizzazione. Il broker locale interroga Cloud; Cloud verifica presso Composio il proprietario dell'account, la Auth Config, il toolkit e lo stato attivo/non disabilitato.
Un esito positivo verificato sblocca lo strumento in attesa nello stesso turno dell'agente. Questo scopre lo schema, poi invoca cloud_app_execute attraverso il normale filtro dei permessi. Non vengono create richieste duplicate all'utente né nuove attività autonome.

Un account gratuito può connettere e usare due app; qualsiasi piano a pagamento, Plus incluso, personale o di un team, letto dal claim ent del token di sessione, non ha limiti. La quota va alle app connesse per prime: collegarne una terza, o eseguire uno strumento su un'app oltre le prime due (per esempio dopo la scadenza di un piano), viene rifiutato con 402 plan_required, che l'harness trasforma in un messaggio che rimanda alla pagina dei prezzi. Elencare le app e verificare una connessione non sono mai limitati. Il sito imposta il numero con OHARNESS_FREE_CONNECTOR_APPS; un sito self-hosted imposta OHARNESS_CONNECTORS_FREE=1 per eliminarlo per ogni account che ha effettuato l'accesso.

Se un account connesso in precedenza viene revocato, l'esecuzione restituisce un rifiuto esplicito connection_required prima dell'esecuzione, che attiva questo stesso flusso. Timeout, errori del fornitore o esiti di esecuzione incerti non vengono mai ripetuti automaticamente. Ricaricare la pagina Web ripristina lo stato delle schede in sospeso finché il processo è attivo.

Sicurezza e limiti della V1

Solo quattro endpoint POST per client nativi: catalog, status, link ed execute. I link di autorizzazione restano nelle risposte dell'interfaccia, fuori dall'output del modello e dall'archiviazione delle trascrizioni.
Le interazioni in sospeso fissano l'utente verificato e l'origine Cloud. Cambiare accesso non può riprendere l'attività di autorizzazione di un vecchio utente su un altro account.
Metadati ed esecuzione usano la stessa versione concreta dello strumento. Se latest si risolve diversamente dopo un riavvio del server, riscopri lo schema invece di eseguirne uno obsoleto. Usa versioni datate per deployment riproducibili.
Annullamento, interruzione dell'agente, timeout di dieci minuti e arresto fermano la chiamata in attesa. Un'attività annullata non revoca una concessione OAuth completata in modo indipendente.
Nessuna continuazione dopo il riavvio del processo né ripetizione di job in background. Dopo un riavvio, inizia un nuovo turno; un collegamento Composio già completato resta individuabile.
La V1 presuppone un solo account attivo per app/Auth Config/utente. Più account attivi falliscono in modo chiuso in attesa della scelta di un amministratore. Niente account condivisi né interfaccia ACL.
Le schede al momento vengono mostrate nella chat Web (compresa la superficie Web dell'app desktop), non nelle interfacce terminale/headless. Queste non hanno un'interfaccia a schede; usa il Web per il primo collegamento, oppure disattiva questo plugin per le esecuzioni non presidiate/headless.
Ogni processo ha una limitazione di frequenza di base. In produzione vanno aggiunti limiti condivisi all'edge, una policy di audit/conservazione e Auth Config OAuth con scope adeguati.

Verifica

npm run test:cloud-connectors copre annullamento del broker, concorrenza, timeout, rifiuto del permesso e un vero agente che prosegue dopo un'autorizzazione simulata. npm run test:composio di Cloud copre proprietà, allowlist, versione, revoca e assenza di nuovi tentativi. node --conditions=oharness-source script/cloud-connector-ui-demo.ts avvia una demo Web isolata e offline; non accede mai al vero Gmail. L'OAuth reale richiede comunque il consenso dell'utente nel browser.

← Plugin Composio Memoria e sincronizzazione →