100 lines
4.8 KiB
Markdown
100 lines
4.8 KiB
Markdown
# Phase 2: ResearchAnalyst Findings
|
|
|
|
## Sources
|
|
|
|
- Electron security checklist: https://www.electronjs.org/docs/latest/tutorial/security
|
|
- Electron safeStorage API: https://www.electronjs.org/docs/latest/api/safe-storage
|
|
- Electron utilityProcess API: https://www.electronjs.org/docs/latest/api/utility-process
|
|
- electron-builder auto-update: https://www.electron.build/auto-update
|
|
- electron-builder code signing: https://www.electron.build/code-signing
|
|
- Electron releases schedule: https://releases.electronjs.org/schedule
|
|
- Electron releases index: https://releases.electronjs.org/release
|
|
- Kimi Code official product/docs entry:
|
|
- https://www.kimi.com/code
|
|
- https://www.kimi.com/code/docs/en/
|
|
|
|
## Electron Security Requirements
|
|
|
|
From current Electron guidance, AgentCompany must treat desktop privilege as a first-order security boundary:
|
|
|
|
- load only local packaged content in the main renderer
|
|
- keep `nodeIntegration` disabled
|
|
- keep `contextIsolation` enabled
|
|
- keep renderer sandboxing enabled where feasible
|
|
- expose a minimal preload API through `contextBridge`
|
|
- validate IPC sender and payloads
|
|
- restrict navigation and new window creation
|
|
- avoid `file://` in production and prefer a custom protocol
|
|
- define a restrictive CSP
|
|
- never expose shell or filesystem primitives wholesale to renderer code
|
|
|
|
## Runtime Version Decision
|
|
|
|
- Initial architecture research targeted Electron `41.0.0`.
|
|
- Build verification on March 12, 2026 found `better-sqlite3@12.6.2` failing native rebuild against Electron `41.0.0` / Node `24.14.0`.
|
|
- The implementation baseline is therefore pinned to Electron `39.8.0` for now.
|
|
|
|
Why this downgrade is deliberate:
|
|
|
|
- Electron `39.8.0` is still a stable release line as of March 12, 2026.
|
|
- It preserves the existing SQLite storage implementation without forcing a same-phase storage rewrite.
|
|
- The downgrade is narrower in scope than replacing persistence with a different driver while the product shell, IPC, and orchestration layers are still being completed.
|
|
|
|
Upgrade condition:
|
|
|
|
- Revisit Electron `41.x` after the SQLite layer is migrated to a compatible runtime path or the upstream native module supports the newer V8 ABI cleanly.
|
|
|
|
## Secret Storage Findings
|
|
|
|
- `safeStorage` is main-process only and uses OS-backed cryptography semantics.
|
|
- macOS: keychain-backed, app-specific protection
|
|
- Windows: DPAPI-backed, user-scope protection
|
|
- Linux: backend varies; it can degrade to `basic_text`
|
|
|
|
Product implication:
|
|
|
|
- AgentCompany should use `safeStorage` when encryption is available.
|
|
- On Linux, the app must surface the selected backend and explicitly fall back to an app-local encrypted vault when the selected backend is `basic_text` or unavailable.
|
|
|
|
## Background Processing Findings
|
|
|
|
- `utilityProcess.fork()` provides a Chromium-managed child process with Node enabled and message ports available.
|
|
- It is appropriate for orchestration work that should not block the renderer and should stay separate from window lifecycle concerns.
|
|
|
|
Product implication:
|
|
|
|
- Use a utility process for the orchestration core, run queue, workspace locks, and connector process supervision.
|
|
- Keep UI projection in renderer, privileged OS coordination in main, and long-running execution in the utility process.
|
|
|
|
## Packaging And Updater Findings
|
|
|
|
- electron-builder supports cross-platform packaging with:
|
|
- macOS: `dmg` plus `zip`
|
|
- Windows: `nsis`
|
|
- Linux: `AppImage` and optional deb/rpm variants
|
|
- Auto-update via `electron-updater` relies on generated metadata files such as `latest.yml`.
|
|
- macOS auto-update requires a signed app.
|
|
- Windows signing is also supported and should be treated as a release requirement.
|
|
|
|
Product implication:
|
|
|
|
- Package targets should default to DMG/ZIP, NSIS, and AppImage.
|
|
- Update checks must be opt-in/disableable by user setting, as required by the PRD.
|
|
- Signing configuration should be environment-driven and absent values must not block local development.
|
|
|
|
## Desktop UX Research Conclusions
|
|
|
|
- Desktop-first operators need split-pane information density, not a marketing-site layout.
|
|
- Keyboard navigation, command surfaces, and context-preserving utility drawers matter more than route purity.
|
|
- File reveal, open folder, drag/drop, and copy path are standard desktop affordances and should be first-class actions.
|
|
|
|
## Connector Research Conclusions
|
|
|
|
- The current Paperclip repo already contains strong local connector patterns for Codex, Claude Code, Gemini CLI, and OpenCode.
|
|
- Kimi Code is a real official CLI offering, but its desktop integration contract requires explicit treatment instead of assuming parity with the existing adapters.
|
|
|
|
Implementation decision:
|
|
|
|
- Reuse the established adapter contract ideas from current Paperclip for supported local connectors.
|
|
- Represent advanced capability differences explicitly in the connector registry and task/run UX.
|