fix(composio): surface Gmail scope errors as permissions

[aqilaziz]

Summary - Keeps Gmail insufficient-scope failures distinct from disconnected/auth failures. - Points missing Gmail permissions to Settings -> Connections -> gmail instead of Settings -> Skills. - Updates integrations/orchestrator prompts so connected-but-missing-scope errors are not collapsed into the generic disconnected flow. - Adds focused regression assertions for prompt wording and Composio error mapping. - Serializes app-state cache tests that mutate global test caches so unrelated CI jobs do not fail nondeterministically. ## Problem When Gmail is connected but a send action fails due to missing permissions/scopes, the agent can treat the failure like a disconnected integration and tell the user to reconnect generically. That makes a connected account look broken and hides the real missing-scope issue. ## Solution - Format insufficient_scope Composio errors as missing permissions on a connected account. - Route the user to Settings -> Connections -> gmail for reconnect/scope grant. - Teach integrations_agent to report scope/permission failures plainly instead of returning Connection error, try to authenticate. - Teach the orchestrator not to apply the disconnected-service rule to [composio:error:insufficient_scope] / missing-permission messages. ## Submission Checklist - [x] Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy - [x] Diff coverage >= 80% - focused Rust prompt/error-mapping tests added; CI coverage gate will enforce merged diff coverage. - [x] Coverage matrix updated - N/A: connector error/prompt behavior only, no feature row added/removed/renamed - [x] All affected feature IDs from the matrix are listed in the PR description under ## Related - N/A: no matrix feature ID changed - [x] No new external network dependencies introduced (mock/pure prompt and mapping coverage only) - [x] Manual smoke checklist updated if this touches release-cut surfaces - N/A: no release-cut smoke surface changed - [x] Linked issue closed via Closes #NNN in the ## Related section ## Impact - User-facing copy changes when a connected Gmail account lacks send permissions. - True disconnected/auth failures still use the existing authenticate handoff. - No migration or dependency change. ## Related - Closes #2365 - Related tracking issue: #2305 - Follow-up PR(s)/TODOs: N/A --- ## AI Authored PR Metadata (required for Codex/Linear PRs) ### Linear Issue - Key: N/A - URL: N/A ### Commit & Branch - Branch: codex/2365-gmail-scope-error - Commit SHA: 4156d29 ### Validation Run - [x] cargo fmt -- --check - [x] git diff --check - [x] Focused tests attempted locally: cargo test -p openhuman openhuman::composio::error_mapping::tests --lib (blocked by missing Windows libclang; see below) - [x] Focused prompt tests attempted locally: cargo test -p openhuman openhuman::agent::agents::integrations_agent::prompt::tests --lib (blocked by missing Windows libclang; see below) - [x] Focused app-state cache test attempted locally: cargo test --lib openhuman::app_state::ops::tests::runtime_snapshot_cache_hit_within_ttl -- --nocapture (blocked by missing Windows libclang; see below) - [x] Rust fmt/check (if changed): cargo fmt -- --check - [x] Tauri fmt/check (if changed): N/A ### Validation Blocked - command: cargo test -p openhuman openhuman::composio::error_mapping::tests --lib - error: Unable to find libclang: could not find clang.dll/libclang.dll; set LIBCLANG_PATH - impact: Local Windows Rust test run blocked before executing tests; CI Linux Rust jobs should validate the added tests. ### Behavior Changes - Intended behavior change: connected Gmail insufficient-scope failures surface as missing permissions, not as disconnected-account copy. - User-visible effect: users are pointed to Connections to reconnect/grant Gmail scopes instead of being told Gmail is simply disconnected. ### Parity Contract - Legacy behavior preserved: true auth/connection failures still bubble up as Connection error, try to authenticate for the orchestrator settings handoff. - Guard/fallback/dispatch parity checks: Composio error classification prefix remains [composio:error:insufficient_scope]. ### Duplicate / Superseded PR Handling - Duplicate PR(s): N/A - Canonical PR: this PR - Resolution (closed/superseded/updated): N/A

Summary by CodeRabbit

• Bug Fixes

  • Refined error handling to distinguish scope/permission failures from authentication/connection errors.
  • Updated user guidance to direct users to Settings → Connections when additional scopes/permissions are required.
  • Clarified error messaging so users receive accurate instructions for resolving authorization issues.

• Tests

  • Added unit tests to verify prompts and error formatting distinguish insufficient-scope cases from disconnected accounts.
  • Serialized cache-related tests to prevent interference from shared test state.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 402f60ec-ee90-42de-9973-62d47182efa6

📥 Commits

Reviewing files that changed from the base of the PR and between a0f954f and 4156d29.

📒 Files selected for processing (1)

• src/openhuman/app_state/ops_tests.rs

---

📝 Walkthrough

Walkthrough

Distinguishes insufficient-scope/permission errors from true auth/connection failures: Composio error formatting, integrations and orchestrator prompts now instruct users to grant missing scopes via Settings → Connections when appropriate, and only show the exact "Connection error, try to authenticate" message for genuine connection/auth failures.

Changes

Scope vs. Disconnection Error Handling

Layer / File(s)	Summary
Composio error classification and user messaging src/openhuman/composio/error_mapping.rs, src/openhuman/composio/error_mapping_tests.rs	format_insufficient_scope_message now directs users to Settings → Connections → {toolkit} for granting requested scopes. Tests assert Gmail HTTP 403 insufficient-scope is classified/formatted as missing-permissions and excludes false "not connected" / "Settings → Skills" text.
Integrations agent scope vs. disconnection decision-making src/openhuman/agent/agents/integrations_agent/prompt.md, src/openhuman/agent/agents/integrations_agent/prompt.rs	Agent prompt adds a branch for composio insufficient-scope errors (no disconnected-account messaging; instructs Settings → Connections to enable scopes) and restricts the exact "Connection error, try to authenticate" reply to true auth/connection failures. New unit test verifies prompt content.
Orchestrator routing of scope errors src/openhuman/agent/agents/orchestrator/prompt.md, src/openhuman/agent/agents/orchestrator/prompt.rs	Orchestrator prompt clarifies insufficient-scope errors should be handled as existing connections needing added permissions in Settings → Connections. New test asserts the prompt contains composio insufficient-scope marker and connection/permissions guidance.
Test synchronization for cache tests src/openhuman/app_state/ops_tests.rs	Adds a process-wide test mutex (APP_STATE_CACHE_TEST_LOCK) using once_cell::sync::Lazy and parking_lot::Mutex, and acquires it at the start of several cache-related tests to prevent interference from concurrent tests.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Agent as Integrations Agent
  participant ErrorSignal as Error Classification
  User->>Agent: Request action (e.g., send email via Gmail)
  Agent->>ErrorSignal: Action fails, classify error
  alt Insufficient OAuth scopes
    ErrorSignal-->>Agent: composio:error:insufficient_scope
    Agent->>User: Go to Settings → Connections → Gmail\nto grant required scopes
  else True disconnection
    ErrorSignal-->>Agent: auth/connection failure
    Agent->>User: Connection error, try to authenticate
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• tinyhumansai/openhuman#1795: Overlaps on insufficient-scope error handling and classification as ProviderUserState/insufficient-scope.

Suggested reviewers

• senamakel
• graycyrus

Poem

🐰 When scopes are missing, do not cry "disconnected" loud—
Point paws to Settings → Connections, where permissions live proud.
Grant the OAuth scopes, then the tools can play,
No false disconnects, just a bunny-approved way. 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(composio): surface Gmail scope errors as permissions' directly and specifically describes the main change across the changeset: distinguishing Gmail insufficient-scope errors from disconnected authentication failures and routing users to the correct permissions pathway.
Docstring Coverage	✅ Passed	Docstring coverage is 82.35% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[oxoxDev]

New commit 4156d29 from @aqilaziz adds global cache test serialization — looks good. Still needs review from maintainers. @senamakel assigned.

[graycyrus]

Looks good, nice work!