Conectores na nuvem

connector-cloud é um plugin de arquitetura do OHarness, não MCP. O Cloud detém a chave de projeto do Composio e a configuração aprovada de apps e ferramentas. Os clientes usam o login do OHarness; as credenciais OAuth do Gmail ficam com o Composio, vinculadas ao ID de usuário do OHarness verificado pelo servidor. Nenhuma nova tabela do Supabase é necessária.

Configuração

• Segredo de runtime do site do Cloud: COMPOSIO_API_KEY. Nunca NEXT_PUBLIC_ e nunca no config.json, no plugins.json, no bundle do navegador ou no contexto do modelo do usuário.
• Os apps habilitados são derivados das Auth Configs do projeto no Composio, e não de um arquivo. Uma Auth Config com restrição de ferramentas é um app habilitado, e essa restrição é a sua lista de permissões; assim, uma nova integração é uma ação no painel, e não um deploy. A derivação recusa em vez de presumir: uma config que não restringe nenhuma ferramenta é ignorada (o Composio interpreta a ausência de restrição como todas as ferramentas do toolkit), duas configs habilitadas para o mesmo toolkit não habilitam nenhuma, e configs desabilitadas, ids inutilizáveis ou nomes de ferramenta malformados descartam aquele app. Os tetos de 20 apps e 40 ferramentas não mudaram. O conjunto é resolvido uma vez por processo, então reinicie o Cloud depois de uma alteração no painel.
• O website/connectors.json do Cloud agora é opcional e só pode restringir: {"disabled": ["slug"]} retira um app sem mexer no Composio. Um arquivo que ainda tenha toolkits mantém o comportamento explícito antigo. O deploy pode, em vez disso, apontar OHARNESS_CONNECTORS_FILE para um caminho absoluto montado. Ele fica no gitignore de propósito, então inclua/monte o arquivo só se for usá-lo.
• O ambiente Supabase já existente do site valida os tokens de login do OHarness.
• cloud.json do cliente: { "siteUrl": "http://localhost:4000" } opcional para desenvolvimento local; o padrão é o endereço público do Cloud. Mudar a origem do Cloud pode exigir entrar de novo. OHARNESS_SITE_URL é uma alternativa para sobrescrever.
• plugins.json do cliente: o plugin padrão não exige nenhuma entrada. Para desativá-lo: { "runtimePlugins": [{ "id": "connector-cloud", "enabled": false }] }.

Crie a Auth Config OAuth do Gmail no painel do Composio, no mesmo projeto da chave de API. Revise os escopos e use acesso somente leitura ao Gmail para tarefas de leitura; a lista de permissões de execução não substitui escopos OAuth de privilégio mínimo. A config de exemplo contém placeholders, não credenciais que funcionem.

Ao usar OHarness_Cloud/dev.sh, defina as variáveis do Cloud no processo do website (o Next carrega website/.env.development.local). O harness não precisa da chave do Composio. Aponte-o para o site local antes de iniciá-lo, por exemplo OHARNESS_SITE_URL=http://localhost:4000 ./dev.sh up harness. O up não reinicia processos que já estão rodando; use restart website harness depois de salvar o trabalho. Uma edição no Cloud em localhost não faz deploy da API no site público.

Fluxo da conversa

1. O agente chama cloud_app_tools para listar apps ou descobrir os schemas e a versão exatos das ferramentas de um app. Ela fica disponível mesmo antes de uma conta do app ser conectada.
2. A política de permissões normal do OHarness roda primeiro. Se aprovada e sem vínculo, a ferramenta atual espera e o chat Web exibe Connect / Cancel.
3. Só o clique do usuário em Connect solicita um link hospedado do Composio. O Cloud define user_id a partir do login validado, nunca a partir da entrada do modelo.
4. A interface abre a página de autorização. O broker local consulta o Cloud; o Cloud verifica no Composio o dono da conta, a Auth Config, o toolkit e o estado ativo/não desabilitado.
5. Um sucesso verificado resolve a ferramenta que estava esperando no mesmo turno do Agent. Ela descobre o schema e depois invoca cloud_app_execute pelo portão de permissões normal. Nenhum pedido duplicado ao usuário nem nova tarefa autônoma é criado.

Uma conta gratuita pode conectar e usar dois apps; qualquer plano pago — o Plus incluído, pessoal ou de uma equipe, lido da claim ent do token de sessão — não tem limite. A cota vai para os apps conectados primeiro: vincular um terceiro, ou executar uma ferramenta em um app além dos dois primeiros (por exemplo, depois que um plano expira), é recusado com 402 plan_required, que o harness transforma em uma mensagem indicando a página de preços. Listar apps e verificar uma conexão nunca são limitados. O site define o número com OHARNESS_FREE_CONNECTOR_APPS; um site auto-hospedado define OHARNESS_CONNECTORS_FREE=1 para remover o limite para toda conta logada.

Se uma conta conectada anteriormente for revogada, a execução retorna uma recusa explícita connection_required antes de executar, o que aciona este mesmo fluxo. Timeouts, erros do fornecedor ou falhas de execução incertas nunca são repetidos automaticamente. Recarregar a página Web restaura o estado dos cartões pendentes enquanto o processo estiver vivo.

Segurança e limites da V1

• Só quatro endpoints POST de cliente nativo: catálogo, status, link e execução. Os links de autenticação ficam nas respostas da interface, fora da saída do modelo e do armazenamento de transcrições.
• Interações pendentes fixam o usuário verificado e a origem do Cloud. Trocar de login não permite retomar a tarefa de autorização de um usuário antigo em outra conta.
• Os metadados e a execução usam a mesma versão concreta da ferramenta. Se latest for resolvido de outro jeito depois de reiniciar o servidor, descubra de novo em vez de executar um schema desatualizado. Use versões datadas para deploys reproduzíveis.
• Cancelar, abortar o Agent, o timeout de dez minutos e o desligamento interrompem a chamada em espera. Uma tarefa cancelada não desfaz uma concessão OAuth concluída de forma independente.
• Não há continuação após reinício do processo nem repetição de jobs em segundo plano. Depois de reiniciar, comece um novo turno; um vínculo do Composio já concluído continua podendo ser descoberto.
• A V1 presume uma conta ativa por app/Auth Config/usuário. Várias contas ativas falham fechado até que um admin escolha. Sem contas compartilhadas nem interface de ACL.
• Os cartões hoje aparecem no chat Web (incluindo a superfície Web do desktop), não nas interfaces de terminal/headless. Essas não têm interface de cartões; use a Web para o primeiro vínculo ou desative este plugin em execuções sem supervisão/headless.
• Cada processo tem um limite de requisições básico. Em produção é preciso adicionar limites compartilhados na borda, uma política de auditoria/retenção e configurar Auth Configs OAuth com escopo adequado.

Verificação

npm run test:cloud-connectors cobre o cancelamento do broker, concorrência, timeout, negação de permissão e um Agent real que continua após uma autorização simulada. O npm run test:composio do Cloud cobre posse, lista de permissões, versão, revogação e o comportamento sem nova tentativa. node --conditions=oharness-source script/cloud-connector-ui-demo.ts inicia uma demo Web isolada e offline; ela nunca acessa o Gmail real. O OAuth de verdade ainda exige o consentimento do usuário no navegador.