summono: Instructions file for Codex

Project Overview (for AI Agent)

Goal

Summono is the installer and launcher for AI harnesses — a desktop app that installs and starts an AI agent in one click, for people who never open a terminal. Free and open source forever (MIT).

Two shapes of harness, two treatments:

• Harnesses with their own desktop GUI (Codex app, Claude Desktop): install only, never wrap — download and install the official app plus whatever it needs, then launch it from the panel.
• Harnesses with no desktop form (DeepSeek Harness): Summono supplies an invisible runtime, hosts the process on a dedicated port, and embeds the web UI inside its own window.

Technical Approach

• Three processes, one hard boundary. All real work lives in a resident engine process (utilityProcess); the Electron main process only manages windows, supervises the engine, and relays IPC. Engine ↔ GUI is pure JSON-RPC ({id,method,params} / {id,result|error}, events as {event,payload}), so the engine can be swapped out wholesale without touching the app shell.
• Vendor passthrough, never replacement. Whatever a vendor already ships — official installers, desktop apps, state-directory conventions (dsh's ~/.dsh) — is used as-is. Summono only fills the gaps vendors don't cover.
• Hosted instances are process-isolated but state-shared. The hosted dsh runs on its own port (34517) but reuses the vendor's default state directory, so hand-installed copies coexist and every online tutorial still applies.
• Private runtime supply. Node.js is downloaded into Summono's own directory and never touches the user's system; all platform differences converge in runtime.ts.
• Organized by business domain, not by type. A new capability starts with "which domain does this belong to?" — never a handlers/ or utils/ directory.

Code Organization

src/
├── main/       # Electron main process: window management, engine supervision, IPC relay — no business logic
├── engine/     # resident engine process, one file per business domain
│   ├── runtime.ts   # private Node.js supply, all platform differences
│   ├── sources.ts   # artifact fetch: official + mirror fallback, stall, sha256
│   ├── dsh.ts       # dsh: install, launch, probe, supervise
│   └── apps.ts      # desktop apps: detect and launch
├── preload/    # contextBridge — wiring only
└── renderer/   # the React launchpad