feat(desktop): configure the preview User-Agent per profile

[TheLoroXD]

The desktop preview exposes Electron in its User-Agent, which sends the Teams Web entry point to the retired Classic Teams page in a fresh macOS reproduction. Removing the app/Electron tokens reaches the Microsoft sign-in form. Profiles currently offer no way to choose that identity without changing T3's native default globally.

Add an optional native / chrome identity mode to custom browser profiles. The desktop profile menu offers Native (default) and Chrome compatibility. The override is applied when the Electron webview attaches, so the menu tells users to reopen tabs. The running Chromium version and platform stay intact; the setting changes neither the browser engine nor User-Agent Client Hints. Returning to Native restores the exact original string. Existing settings and built-in profiles keep their native behavior.

Closes #16616.

Scope

This uses the focused configuration exception in CONTRIBUTING.md: it controls the identity of the existing desktop preview within existing browser profiles. It adds no browser-host workflow and changes no product default. The control is desktop-only; web/mobile retain the optional profile field without offering an Electron control, and server-rendered tabs are unaffected. Existing agents/providers continue to use the same preview tabs.

#7110 and #5002 established why the native default must stay. The Chrome mode is opt-in and reversible per custom profile. It does not claim to resolve embedded-browser account policies such as #14815.

Review status

CodeRabbit reported no actionable code comments and passed the title, description, linked-issue, and scope checks. Its Approvability rule requires maintainer review because this adds a per-profile user control; Macroscope also requires human review on eligibility grounds. The focused configuration exception makes the proposal eligible for submission, but does not remove those review requirements. The implementation and commit remain unchanged.

Verification

• vp test run packages/contracts/src/browserProfile.test.ts apps/desktop/src/settings/DesktopClientSettings.test.ts apps/desktop/src/preview/BrowserSession.test.ts apps/web/src/browser/HostedBrowserWebview.test.tsx: 38 tests passed in four files. These cover legacy settings, allowed modes, current Chromium/platform tokens, exact Native restoration, default/profile isolation, disk persistence, native session permissions, and settings hydration before webview attachment.
• Mutation check: returning the native string for Chrome made four identity assertions fail; restoring the helper passed the focused suite.
• Focused typecheck for @t3tools/contracts, @t3tools/web, and @t3tools/desktop: passed. File-scoped lint/format checks passed; four existing warnings remain in unchanged lines.
• Built and used an isolated desktop client from this worktree. Selected Chrome in the actual Teams profile menu, verified the persisted field on disk, and reopened the client with the selection retained.
• Electron 44.4.2 / Chromium 152.0.7977.130, macOS arm64, real <webview> guests using the helper bundled from this branch: all seven checks passed. Request-header and navigator.userAgent identities matched, default Native stayed intact, Native/Chrome switching after reopening retained a fictional cookie, and a different profile stayed isolated. Native results.
• Teams entry point, fresh Electron storage, no credentials: Native reached /error/eoa and displayed “Classic Teams is no longer available”; Chrome compatibility reached the Microsoft sign-in form. Sanitized results. An authenticated Teams session, other desktop platforms, and live Turnstile challenges were not validated. The original report's external-app launch was not reproduced in these isolated runs.

Before / after

Before: upstream profile menu has no User-Agent control.

After: explicit per-profile identity and reopen guidance; Chrome remains selected after client restart.

Native remains available for reverting the profile.

Evidence is hosted as release assets in the contributor fork and is not committed to this PR. The images show a fictional Teams profile in isolated test state.

Prepared with GPT-6.1-Sol using Codex in T3 Code.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds a new per-profile User-Agent capability and changes the runtime identity of Electron preview tabs when users select Chrome compatibility. Existing defaults remain intact and the option is tested and reversible, but the production implementation spans files primarily maintained by other contributors, so human review is warranted.

Notes:

• Code review disabled. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

Pre-merge checks failed. Please resolve the failing checks before merging.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4ad5874a-12ba-4b69-87b4-3c7087051a15

📥 Commits

Reviewing files that changed from the base of the PR and between f4f148e and 8cb4d6f.

📒 Files selected for processing (5)

• apps/desktop/src/settings/DesktopClientSettings.test.ts
• apps/web/src/browser/HostedBrowserWebview.tsx
• apps/web/src/components/settings/IntegrationsSettings.tsx
• packages/contracts/src/browserProfile.test.ts
• packages/contracts/src/browserProfile.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Browser profiles now support an optional Native or Chrome User-Agent mode. Settings expose the choices for eligible profiles, and hosted webviews apply the selected mode to the browser’s current User-Agent.

Changes

Per-profile User-Agent modes

Layer / File(s)	Summary
Profile mode contract and User-Agent transformation packages/contracts/src/browserProfile.ts, packages/contracts/src/browserProfile.test.ts	The profile schema accepts an optional Native or Chrome mode. The helper returns the original User-Agent for Native mode and removes Electron-specific tokens for Chrome mode. Tests cover the helper and schema.
Profile mode settings apps/web/src/components/settings/IntegrationsSettings.tsx, apps/desktop/src/settings/DesktopClientSettings.test.ts	The profile options menu offers Native and Chrome choices for eligible profiles. The updater saves the choice when settings are hydrated and no import is in flight. The desktop settings fixture specifies Chrome mode.
Apply profile mode to hosted webviews apps/web/src/browser/HostedBrowserWebview.tsx	The hosted webview reads the selected profile’s mode and sets its useragent attribute using the browser’s current User-Agent.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant IntegrationsSettings
  participant ClientSettings
  participant HostedBrowserWebview
  participant browserProfileUserAgent
  participant Webview
  User->>IntegrationsSettings: Select a profile User-Agent mode
  IntegrationsSettings->>ClientSettings: Update the profile mode
  HostedBrowserWebview->>ClientSettings: Read the selected profile mode
  HostedBrowserWebview->>browserProfileUserAgent: Pass current User-Agent and mode
  browserProfileUserAgent-->>HostedBrowserWebview: Return resolved User-Agent
  HostedBrowserWebview->>Webview: Set useragent attribute

Loading

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 8cb4d

The per-profile choice appears mergeable after normal checks. The reported Teams result covers fresh sign-in only, not authenticated sessions or other desktop platforms.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 8cb4d

The change is opt-in for custom profiles and preserves existing defaults. It changes how websites identify the preview without changing its session selection or local privileges. No introduced security concern was identified in the inspected paths, but external sign-in behavior and interruption scenarios were not runtime-validated.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The directly changed exposure is website behavior for hosted guests attached under an opted-in custom profile. The choice follows that profile across its hosted tabs rather than a global default. It does not select a different session or grant additional local preview authority.

Security Findings and Attack Paths

• inferred — The inspected flow is a profile-setting choice transformed into an attachment-time User-Agent attribute. No introduced path from external page content to profile mutation or increased local authority was identified. Different website routing is intentional, but source inspection does not establish how external authentication policies respond to the changed identity.

Trust Boundaries and Controls

• observed — The mode has two schema-supported values rather than accepting an arbitrary User-Agent. Existing normalization prevents stored profiles from shadowing built-ins or presenting duplicate IDs as separate identities. The hosted guest is not rendered until settings hydration and preview configuration are available.

Resilience and Maintainability Implications

• observed — Crash recovery increments the guest generation and reattaches with the currently selected mode. Registration waits for the tab lease and rejects disposed or replaced guests; cleanup cancels pending recovery and removes listeners. These existing lifecycle controls remain in place around the new identity attribute.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore (reviewers only)

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Approvability	❌ Error	This PR adds a user workflow: IntegrationsSettings.tsx adds per-profile Native/Chrome User-Agent selection, and browserProfile.ts stores the selected mode. This matches the Approvability rule “Add…	A maintainer must review the new per-profile User-Agent selection workflow before CodeRabbit approves the pull request.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR meets the coding requirements in [#16616]. BrowserProfile adds an optional native / chrome mode. Built-in profiles and legacy profiles omit the mode, so they keep Electron's native User-A…
Out of Scope Changes check	✅ Passed	The reported changes support [#16616]: profile schema and identity helper, profile-specific desktop settings, webview integration, and tests. The settings UI limits the control to custom profiles when…
Title check	✅ Passed	The title clearly and concisely describes the main change: per-profile configuration of the desktop preview User-Agent.
Description check	✅ Passed	The description explains the problem, change, scope, and verification results. It links the issue, explains the focused-configuration exception, includes test details and UI screenshots, and names the…

Full details: Approvability

Explanation

This PR adds a user workflow: IntegrationsSettings.tsx adds per-profile Native/Chrome User-Agent selection, and browserProfile.ts stores the selected mode. This matches the Approvability rule “Adds a subsystem or user workflow.” The pull request needs a maintainer's review.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[TheLoroXD]

The Approvability requirement is acknowledged. This adds an opt-in per-profile control and therefore needs maintainer review under the repository review policy. The focused configuration exception in CONTRIBUTING.md concerns submission eligibility; it does not waive that review.

CodeRabbit reported no actionable code comments and passed the linked-issue and scope checks. I kept the implementation at 8cb4d6fa0f09baaac9e5dc0187f59cc8e2340258, preserved the native default established by #7110 / #5002, and updated the PR description to make the human-review requirement explicit.

The existing verification remains attached: 38 focused tests, affected-package typechecks, real Electron webview identity/session checks, and the isolated Teams entry-point reproduction without credentials. Authenticated Teams sessions, other desktop platforms, and live Turnstile challenges remain untested.

[TheLoroXD]

The five action_required reports on 8cb4d6fa0f09baaac9e5dc0187f59cc8e2340258 are awaiting GitHub Actions approval. I checked each run: all have zero jobs, and each run page says it is awaiting approval from a maintainer. No CI test or Cursor forwarding job has executed.

• Mobile Fingerprint Check, edited event
• Mobile EAS Preview
• CI
• Forward to Cursor hygiene
• Mobile Fingerprint Check, opened event

Could a maintainer with write access approve the pending workflows for this fork PR? GitHub's approval procedure explains the required action. My contributor account has read access to the upstream repository and cannot grant that approval.

The local verification and Electron/Teams evidence remain attached to the PR description. Upstream CI remains unverified until it runs. This workflow approval is separate from the maintainer code review required by CodeRabbit and Macroscope's Approvability checks.