bug(onboarding): Composio GMAIL_FETCH_EMAILS returns 400 — profile building always fails

[graycyrus]

Bug

The "Building your profile" step in onboarding always fails with a 400 Bad Request from the Composio backend, even when Gmail is connected. Users see the "Almost there!" error screen and can never get a profile built during onboarding.

Error

[onboarding:context] gmail stage failed
Error: composio execute_tool failed: Backend returned 400 Bad Request
  for POST https://staging-api.alphahuman.xyz/agent-integrations/composio/execute

The pipeline never gets past Stage 1 (Gmail search), so LinkedIn scrape and profile build are always skipped.

Reproduction

1. Start fresh onboarding with Gmail connected via Composio
2. Reach the "Building your profile..." step (ContextGatheringStep)
3. Pipeline immediately fails → "Almost there!" error screen

Call trace

ContextGatheringStep.tsx:107  →  callCoreRpc({ method: 'openhuman.tools_composio_execute', params: { action: 'GMAIL_FETCH_EMAILS', params: { query: 'from:linkedin.com', max_results: 10 } } })
  ↓
src/openhuman/tools/schemas.rs:165  →  handle_composio_execute()  →  client.execute_tool(&action, action_args)
  ↓
src/openhuman/composio/client.rs:136  →  POST /agent-integrations/composio/execute  →  { "tool": "GMAIL_FETCH_EMAILS", "arguments": { "query": "from:linkedin.com", "max_results": 10 } }
  ↓
src/openhuman/integrations/client.rs:95  →  400 Bad Request

Likely causes

1. Backend validation changed — the /agent-integrations/composio/execute endpoint may have updated its expected request schema without a corresponding core update
2. Composio auth/connection expired — the connected Gmail account's OAuth token may have expired or been revoked
3. Argument format mismatch — backend may now expect a different shape for arguments (e.g. rejecting certain param names or types)

Impact

• Every new user going through onboarding with Gmail connected hits this
• Profile is never built automatically — users must manually update later
• The graceful fallback ("Almost there!") masks the issue, so users don't know something broke

Files involved

File	Role
app/src/pages/onboarding/steps/ContextGatheringStep.tsx:107	Frontend RPC call
src/openhuman/tools/schemas.rs:165	RPC handler handle_composio_execute
src/openhuman/composio/client.rs:125-140	HTTP client building POST body
src/openhuman/integrations/client.rs:82-96	Error reporting (Sentry tags)

Next steps

• Check Sentry for tagged errors from integrations/client.rs with path=/agent-integrations/composio/execute
• Inspect backend logs for the 400 response body (validation error details)
• Verify Composio OAuth connection health

[oxoxDev]

Status update — diagnostic phase landing first

Picked this up. Backend executeTool.ts (backend-openhuman/src/controllers/agentIntegrations/composio/executeTool.ts) raises BadRequestError from exactly three sites:

1. tool is required (empty slug — N/A here, the frontend always sends GMAIL_FETCH_EMAILS)
2. Toolkit "<name>" is not enabled — toolkit not in COMPOSIO_ENABLED_TOOLKITS env override
3. Insufficient balance — balanceService.canAfford returns false

Composio SDK throws are caught and returned as HTTP 200 with successful=false, so the 400 is always one of the three above. Cannot pin which without surfacing the response body.

Pre-fix, IntegrationClient::post (src/openhuman/integrations/client.rs:82-96) read the body then discarded it (let _body_text = …), so all three reasons collapsed to the same opaque Backend returned 400 … message. Same anti-pattern in IntegrationClient::get and ComposioClient::raw_delete.

Phase A — diagnostic propagation (PR coming)

• New helper extract_error_detail: reads the {success:false, error:"<msg>"} envelope when present, falls back to the first 500 bytes of raw body at a UTF-8 char boundary.
• post / get / raw_delete non-2xx branches now include the detail in both the report_error payload and the anyhow::bail! message.
• 10 unit + axum-mock HTTP tests covering envelope parsing, raw fallback, UTF-8 truncation, and the post 400 / post 500 / get 403 / raw_delete 4xx propagation paths.
• Diagnostic-only — no happy-path or UX behavior change. Onboarding still dead-ends at "Almost there!" for the same users.

Phase B — staging Sentry repro (after Phase A merges + deploys)

Once Phase A is on staging, the next composio execute_tool failed: Backend returned 4xx … event in Sentry will name the actual cause. That gates Phase C.

Phase C — fix the user-visible failure (cause-dependent)

Depending on Phase B's signal:

• If "Insufficient balance" → most likely cause given fresh users with DEFAULT_PROMO_BALANCE_USD=0 on staging or the weekly signup-credit cap exhausted. Two parallel paths: (a) backend PR on tinyhumansai/backend to grant baseline onboarding credits OR exempt onboarding-context-gathering calls from balance check; (b) openhuman frontend follow-up — on 400 in ContextGatheringStep, mark gmail stage failed and advance the pipeline to the LinkedIn stage instead of dead-ending. (b) is small (~30 LoC) and ships independent of (a).
• If "Toolkit not enabled" → staging env config drift; backend infra fix + a guard on the openhuman side that fails the gmail stage loudly (don't auto-skip — that would mask config regressions).
• Both are possible; the diagnostic message will tell us within hours of staging traffic.

Why diagnostic-first instead of bundling Phase C now

• Three plausible causes; the right UX response is different for each (silent skip is correct only for "expected balance gap", wrong for "config regression").
• Issue body itself flags integrations/client.rs:82-96 as the diagnostic site to fix — this matches the author's request.
• Splits review concerns: Phase A is a small, safe, behavior-preserving change reviewable in minutes; Phase C is UX policy that benefits from real-cause data.

PR will reference this issue with Refs #1296 (not Closes) — the close keyword lives on whichever Phase C PR(s) make Building your profile succeed for fresh users.

Will update here once the PR is open and again after Phase B yields the first staging signal.