root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(FN-3737): add even realities integration research report

Browse Source 
Adds a new Even Realities integration research report to the documentation.

Fusion-Task-Id: FN-3737
This commit is contained in:
Fusion
2026-05-08 10:41:44 -07:00
committed by gsxdsm
parent cea0f6f6c0
commit c17aba7031
18 changed files with 308 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/README.md
View File

@@ -71,6 +71,7 @@ For a full walkthrough (installation, onboarding, first task, and daily workflow
| [Codebase Improvement Audit](./codebase-improvement-audit.md) | Evidence-based technical debt and reliability gap audit with prioritized recommendations |
| [Gap Analysis](./gap-analysis.md) | System completeness analysis comparing Fusion to Paperclip feature set |
| [Agent Sandbox Research](./agent-sandboxing-research.md) | Research on agent isolation, capability enforcement, and sandboxing approaches |
| [Even Realities Integration Research (FN-3737)](./even-realities-integration-research.md) | Research summary and recommended integration topology for Even Realities glasses + Fusion |
| [Agent Gap Analysis](./agent-paperclip-gap-analysis.md) | Gap analysis for agent Paperclip integration |
| [pi-autoresearch Analysis for Fusion Port](./research/pi-autoresearch-analysis.md) | Upstream architecture/license analysis and Fusion integration mapping for autoresearch capabilities |
| [Research Hardening Preflight Baseline](./research/research-hardening-preflight.md) | Verified research subsystem baseline, lifecycle contracts, and hardening pressure points |

140
docs/even-realities-integration-research.md Normal file
View File

@@ -0,0 +1,140 @@
# 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.
## 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).