fusion/docs/even-realities-integration-research.md

Even Realities Integration Research (FN-3737)

1. Summary & Recommendation

Recommend Option A for v1: a Fusion plugin + Even companion app bridge. The companion app (or Even Hub-hosted webview app) handles device/app bridge APIs and forwards minimal HTTP calls to Fusion (fn serve/dashboard API). This aligns with currently visible Even SDK positioning (WebView ↔ Even App bridge, not direct glasses→LAN HTTP) and lets Fusion reuse existing task/agent REST APIs and plugin route hosting.

Implementation status (FN-3970)

• Implemented in Fusion plugin: canonical fusion-plugin-even-realities-glasses route surface now includes board/task card endpoints, quick capture, actions, notifications, and transport status/reconnect routes.
• Production transport path now uses webhook-based WebhookGlassesTransport (companionWebhookUrl) instead of a stub transport.
• Companion app delivery remains out of scope for this document/task chain; this doc still defines the recommended topology and open ecosystem questions.

2. Even Realities Platform Overview

2.1 Developer surface (SDKs, docs, supported hosts)

• Public package: @evenrealities/even_hub_sdk (TypeScript SDK).
• SDK describes itself as a WebView developer bridge to Even App and EvenHub protocol APIs.
• Available evidence indicates app/webview-hosted integration (phone-hosted app shell), not direct firmware SDK for arbitrary host networking.
• Official web property reachable: https://www.evenrealities.com/.
• Unverified (open): canonical developer portal URL/subdomain (common guesses like developer.*/docs.* were not resolvable in this environment).

2.2 On-device UI/card capabilities and limits

From @evenrealities/even_hub_sdk README/API docs:

• Must call createStartUpPageContainer before other custom UI operations.
• containerTotalNum: 1–12.
• textObject: up to 8 items.
• imageObject: max 4 (per changelog note).
• ListContainerProperty.itemCount: 1–20.
• Exactly one container can have isEventCapture=1 in a page. These are effectively the card/container budget constraints for v1 payload shaping.

2.3 Input modalities

Evidence in SDK API surface:

• List/text/system events via onEvenHubEvent.
• Audio path via audioControl(true/false) and audioEvent PCM stream delivery.
• IMU feed via imuControl and sysEvent.imuData stream.
• Launch source signal (appMenu vs glassesMenu). Unverified (open): production gesture taxonomy, physical buttons, and official STT API availability/quality guarantees.

2.4 Connectivity, pairing, and auth model

• SDK framing is WebView ↔ Even App bridge, implying glasses traffic is mediated by the Even App host runtime.
• No authoritative evidence found for direct glasses-to-LAN HTTP sessions; treat direct host HTTP as unsupported until confirmed.
• For Fusion integration, assume companion runtime holds Fusion endpoint + API key/session token and performs authenticated API calls.

2.5 Notification & background-execution model

• SDK changelog references “enhanced WebView background keepalive,” suggesting background execution exists but is constrained by host mobile OS policies.
• No authoritative wake/push SLA found for third-party apps; v1 should assume polling is required.
• Unverified (open): hard background cadence caps on iOS/Android for the Even host container.

2.6 Distribution & policy considerations

• SDK is npm-distributed (@evenrealities/even_hub_sdk) and appears web-app oriented.
• v1 likely ships as companion app/web bundle rather than Fusion-only plugin.
• App-store compliance, sideload policy, and Even-specific review constraints are currently unverified.

3. Fusion Side: Existing APIs & Plugin Surface

3.1 REST endpoints reusable for v1 capabilities (table: capability → endpoint)

Capability	Existing Fusion endpoint(s)
Board/task read	GET /api/tasks, GET /api/tasks/:id
Create task	POST /api/tasks
Update status	POST /api/tasks/:id/move
Task comments/quick notes	POST /api/tasks/:id/comments
Trigger agent action	POST /api/agents/:id/runs, POST /api/agents/:id/heartbeat
Poll run status	GET /api/agents/:id/runs, GET /api/agents/:id/runs/:runId
Task docs/summary fetch	GET /api/tasks/:id/documents/:key

(Endpoints confirmed from packages/dashboard/src/routes/register-task-workflow-routes.ts and packages/dashboard/src/routes/register-agent-runtime-routes.ts.)

3.2 Plugin SDK capabilities relevant here (onSchemaInit, routes, views, createAiSession)

From docs/PLUGIN_AUTHORING.md and plugin SDK exports:

• onSchemaInit for plugin-local schema/data setup.
• Plugin routes for custom endpoints (mounted under plugin namespace via plugin route registration flow).
• Dashboard view/slot registration for pairing/config UI.
• AI/session-related context APIs are available in plugin context surface (for orchestrating Fusion-side flows rather than device-side BLE logic).

3.3 Auth: API key / session model reuse

Reuse existing Fusion auth model:

• Dashboard/serve API auth + daemon token model (docs/settings-reference.md).
• Remote/tokenized login patterns (docs/remote-access.md) for off-device entry links. No new auth mechanism should be introduced for v1.

4. Capability Mapping (MVP)

MVP capability	Fusion endpoint(s)	Glasses UI/card pattern	Constraints
Read board/task status	GET /api/tasks, GET /api/tasks/:id	paged list container + short detail text cards	list item limits (1–20 per container), text budget/legibility
Create task	POST /api/tasks	quick-capture text card + confirm action	likely needs phone text/voice assist; validation/latency feedback
Update task (move)	POST /api/tasks/:id/move	action card (Done/In Review/etc.)	avoid dense workflow options on-device
Quick capture note/comment	POST /api/tasks/:id/comments	single-input capture card	STT availability uncertain; fallback to templated snippets
Poll notifications	GET /api/tasks?limit=... + GET /api/agents/:id/runs	inbox/alert card with unread counters	background polling limits on host platform
Trigger agent actions	POST /api/agents/:id/runs	confirm card (“Run now”) + status follow-up	require explicit confirmation and run-state polling

5. Integration Topology Options

5.1 Option A / B / C with pros/cons

• A) Fusion plugin + companion bridge app (recommended)
  • Pros: matches observed Even SDK app-bridge model; keeps Fusion extensibility in-plugin; minimal core-server change.
  • Cons: requires companion app ownership and release workflow.
• B) Fusion plugin + direct glasses→host HTTP
  • Pros: simpler architecture if supported.
  • Cons: currently unsupported/unverified by available SDK evidence; high risk.
• C) External companion service only (no plugin)
  • Pros: decoupled deployment.
  • Cons: weaker Fusion-native UX/config surface; harder multi-project/operator setup.

5.2 Recommendation and rationale

Choose Option A. It is the only approach consistent with currently visible Even developer surface and allows Fusion-side pairing/config, auth reuse, and optional plugin-scoped helper routes without modifying core transport/auth.

Companion app ownership for v1: the companion app implementation is out of scope for this FN-3738→FN-3747 Fusion chain; the chain should deliver Fusion plugin/API-side integration points that a companion owner can consume.

Polling cadence recommendation (v1):

• Task/board refresh: 30–60s via GET /api/tasks (or filtered variants).
• Active agent-run refresh: 10–20s while run is active via GET /api/agents/:id/runs and GET /api/agents/:id/runs/:runId.
• Idle/background mode: degrade to 60–120s to respect mobile/background constraints.

6. Constraints, Risks, and v1 Scope Guards

• Keep v1 strictly to task read/create/update, quick capture, polling alerts, and basic agent triggers.
• Do not include missions/roadmaps/search/multi-project interaction on-device in v1.
• Major risk: unresolved official documentation on direct networking/background wake; mitigate via conservative polling model.
• Payload-shaping risk: container/list/text limits require terse card design and pagination.

7. API/Server Gaps to Address in FN-3745

• Potential thin endpoint needed for notification aggregation (single compact payload for glasses) to reduce multi-call polling overhead.
• Potential plugin-scoped endpoint for quick-capture normalization (e.g., text template expansion, source tagging).
• If existing endpoints suffice after prototype latency tests, FN-3745 can explicitly close with “none required.”

8. Open Questions

1. What is the canonical official Even developer portal/docs URL for G2 app developers?
2. Is direct device/network HTTP officially supported, or only app-bridge mediated calls?
3. What are hard background polling/wake limits on iOS/Android Even host environments?
4. Is first-party STT officially exposed to third-party Even Hub apps, or must PCM be sent to external STT?
5. Are there formal payload size/rate limits for bridge messages and UI refresh frequency?
6. Who owns companion app delivery in FN-3738+ (Fusion team vs separate mobile team)?

9. Sources

• Even official site: https://www.evenrealities.com/
• npm package metadata: https://www.npmjs.com/package/@evenrealities/even_hub_sdk
• SDK README/API details (via npm package readme): https://www.npmjs.com/package/@evenrealities/even_hub_sdk?activeTab=readme
• Fusion plugin authoring: docs/PLUGIN_AUTHORING.md
• Fusion plugin lifecycle/management: docs/plugin-management.md
• Fusion architecture/API context: docs/architecture.md
• Fusion remote/auth model: docs/remote-access.md, docs/settings-reference.md
• Fusion task routes source: packages/dashboard/src/routes/register-task-workflow-routes.ts
• Fusion agent runtime routes source: packages/dashboard/src/routes/register-agent-runtime-routes.ts
• Community ecosystem signal (non-authoritative): GitHub search results for “even realities sdk” (example repos surfaced via GitHub Search API).