Support deep links for opening sessions directly in Electric Agents desktop & mobile apps

[agent-horton]

Summary

Support deep linking so users can open a session in the Electric Agents desktop or mobile app directly via a link (from email, docs, chat, etc). No dependence on a deployed web UI for routing or fallback in this initial implementation.

Scope

• Session Link Format:

  • Use a custom protocol scheme: electric://session/{id}
  • All shared links and documentation should use this format for now.

• Desktop (Electron):

  • Register the electric:// protocol handler at install/launch.
  • When a link is opened:
    • If app is running, bring to foreground and route to the requested session.
    • If app is not running, launch & route to the requested session.
    • Support deep linking for sessions only (future-proof path for other entity types).

• Mobile (Expo/React Native):

  • Register as handler for the electric:// protocol on iOS & Android (intent filters, URL types).
  • On link open:
    • If user is not signed in or server isn’t configured, show onboarding/setup, then navigate to target session.
    • If app is running, navigate directly to session screen.
  • Generate and handle only custom protocol links for now (no web fallback).

• Testing:

  • Validate functionality on all platforms (Windows, macOS, iOS, Android).
  • Test with app running, backgrounded, or closed.

Out of Scope

• No standard web session links or server-side redirects (as no deployed web UI exists yet).
• No fallback to opening a web browser if the app is not installed.

Acceptance Criteria

• Users can click/tap electric://session/{id} links anywhere (browser, email, chat, etc) and the agents app opens to the correct session on desktop or mobile.
• Appropriate routing for onboarding states (setup/sign-in first, then session).
• Documentation updated to guide users to share/consume electric:// links.

---

See thread discussion for additional details and related code context.