Cloud connectors

connector-cloud is an OHarness architecture plugin, not MCP. Cloud owns the Composio project key and approved app/tool configuration. Clients use their OHarness login; Gmail OAuth credentials remain with Composio, scoped to the server-verified OHarness user ID. No new Supabase tables are required.

Configuration

• Cloud website runtime secret: COMPOSIO_API_KEY. Never NEXT_PUBLIC_ and never the user's config.json, plugins.json, browser bundle or model context.
• Enabled apps are derived from the Auth Configs in the Composio project, not from a file. An Auth Config carrying a tool restriction is an enabled app and that restriction is its allowlist, so a new integration is a dashboard action rather than a deploy. Derivation refuses rather than assumes: a config that restricts no tools is skipped (Composio reads an absent restriction as every tool the toolkit has), two enabled configs for one toolkit enable neither, and disabled configs, unusable ids or malformed tool names drop that app. The 20-app and 40-tool ceilings are unchanged. The set resolves once per process, so restart Cloud after a dashboard change.
• Cloud website/connectors.json is now optional and can only narrow: {"disabled": ["slug"]} withholds an app without touching Composio. A file still carrying toolkits keeps the older explicit behaviour. The deployment can point OHARNESS_CONNECTORS_FILE at an absolute mounted path instead. It is intentionally gitignored, so include/mount it only if you use it.
• The existing website Supabase environment validates OHarness login tokens.
• Client cloud.json: optional { "siteUrl": "http://localhost:4000" } for local development; default is the public Cloud address. Changing Cloud origin can require signing in again. OHARNESS_SITE_URL is an alternative override.
• Client plugins.json: default plugin requires no entry. To disable: { "runtimePlugins": [{ "id": "connector-cloud", "enabled": false }] }.

Create the Gmail OAuth Auth Config in the Composio dashboard for the same project as the API key. Review its scopes and use read-only Gmail access for reading tasks; the execution allowlist is not a substitute for least-privilege OAuth scopes. The example config contains placeholders, not working credentials.

When using OHarness_Cloud/dev.sh, set the Cloud variables on the website process (Next loads website/.env.development.local). The harness does not need the Composio key. Point it at the local website before starting it, for example OHARNESS_SITE_URL=http://localhost:4000 ./dev.sh up harness. up does not restart running processes; use restart website harness after saving work. A localhost Cloud edit does not deploy the API to the public site.

Conversation flow

1. Agent calls cloud_app_tools to list apps or discover an app's exact tool schemas/version. It is available even before an app account is connected.
2. Normal OHarness permission policy runs first. If approved and unbound, the current tool waits and Web chat displays Connect / Cancel.
3. Only the user's Connect click requests a Composio hosted link. Cloud sets user_id from validated login, never from model input.
4. UI opens the authorization page. The local broker polls Cloud; Cloud checks account owner, Auth Config, toolkit and active/not-disabled state at Composio.
5. Verified success resolves the waiting tool in the same Agent turn. It discovers the schema, then invokes cloud_app_execute through the normal permission gate. No duplicate user prompt or new autonomous task is created.

If a previously connected account is revoked, execute returns an explicit pre-execution connection_required refusal, enabling this same flow. Timeouts, vendor errors or uncertain execution failures are never automatically replayed. Refreshing the Web page replays pending card state while the process is alive.

Safety and V1 boundaries

• Only four native-client POST endpoints: catalog, status, link and execute. Auth links stay in UI responses, outside model output and transcript storage.
• Pending interactions pin the verified user and Cloud origin. Switching login cannot resume an old user's authorization task against another account.
• Metadata and execution use the same concrete tool version. If latest resolves differently after server restart, rediscover rather than executing a stale schema. Use dated versions for reproducible deployments.
• Cancel, Agent abort, ten-minute timeout and shutdown stop the waiting call. A cancelled task does not undo an OAuth grant completed independently.
• No process-restart continuation or background job replay. After restarting, start a new turn; an already-completed Composio binding remains discoverable.
• V1 assumes one active account per app/Auth Config/user. Multiple active accounts fail closed pending admin selection. No shared accounts or ACL UI.
• Cards currently render in the Web chat (including desktop's Web surface), not terminal/headless interfaces. Those have no card UI; use Web for first binding, or disable this plugin for unattended/headless runs.
• Each process has basic rate limiting. Production must add shared edge limits, audit/retention policy and configure appropriately scoped OAuth Auth Configs.

Verification

npm run test:cloud-connectors covers broker cancellation, concurrency, timeout, permission denial and a real Agent continuing after mocked authorization. Cloud's npm run test:composio covers ownership, allowlist, version, revocation and no-retry behavior. node --conditions=oharness-source script/cloud-connector-ui-demo.ts starts an isolated offline Web demo; it never accesses real Gmail. Live OAuth still requires the user's consent in the browser.