A local-first multi-agent app development platform, built on PenguinHarness
/**
* Desktop shell main process.
*
* HMR LAYER — MECHANISM ONLY (see packages/hmr/README.md). The
* shell boots and hosts; it does not implement product behavior. It is also
* the least updatable code in the system — a change here reaches users only
* through a new installer — so a capability that could instead be delivered
* by a platform push must be. A rejected example: adding a preload bridge so
* the web UI could open DevTools, when the shell's own View menu already
* does it.
*
* One window over the embedded server: fork penguin-server as a utilityProcess on the
* shared data root (PENGUIN_HOME or ~/.penguin/data), learn its port (last launch's when
* still free, so origin-scoped localStorage preferences survive restarts), and load
* `http://localhost:<port>/api/auth/claim?token=…` — the one-shot token lands
* the window signed in as admin. The window is a plain browser environment (no preload,
* no node integration); every capability flows through the server's HTTP API.
*
* Attach mode: when a live server (e.g. `penguin web`) already owns the data root, the
* window loads that instance instead. The one-shot token buys nothing there, so the shell
* signs the window in the other way it is entitled to — a session minted straight into the
* data root it owns (see attach-session.ts) — and the same move answers any later arrival at
* the sign-in page, which has no password anyone could type. Signing out is the exception:
* it is a decision rather than a failure, so it is left to stand until the next sign-in or
* the next launch.
*
* Tray: a system-tray icon is shown for as long as the app runs, and by default closing the
* window only hides it, so the server and its background tasks keep running (see tray.ts;
* both preferences live in userData/tray.json and Quit still goes through the graceful
* stop). Settings › Appearance turns the icon off and on, reaching the shell over the same
* utilityProcess relay the client updater uses.
*
* Desktop pet: a small frameless, transparent, always-on-top window showing the Web App's own
* `/pet` route — the Adelie penguin, which announces schedule firings, tool calls waiting for
* approval and budget warnings, and reports the model balance and the client-update state when
* clicked (see pet-window.ts and pet-prefs.ts; the preference lives in userData/pet.json and
* defaults to off). Settings › Appearance turns it on and off over that same relay. Being a page
* of this same origin, it is a plain browser with no IPC bridge of its own — the whole reason it
* can be delivered by the platform rather than the shell.
*
* Login item (Windows): Settings › Appearance can register the installed app to start when the
* user signs in — off by default, and offered only where there is an entry to manage (see
* login-item.ts). Windows keeps that record itself, in the user's own Run key: the shell reads it
* back out of the operating system rather than storing it, and reports what it finds, so an entry
* the user disabled in Task Manager shows here as off. The launch the entry itself starts carries
* a flag, and that launch opens no visible window — it waits in the tray, which is where every
* other path back to the app already is.
*
* Built-in browser: the main window (and no other) may host <webview> guests in the
* `persist:penguin-browser` partition, and builtin-browser.ts relays raw CDP and cookie writes
* for them over that same port. That relay is the only part of the browser the shell carries,
* and it lives here because it has to: a guest's `webContents.debugger` and the partition's
* session are main-process APIs that neither the page nor the server process can reach. The
* tab registry, the page scripts, scan / exec / click, import and history are the server
* platform's, delivered by push like any other product behavior.
*
* Folder access (macOS): on the Workspace picker's request, relayed over the same port, the
* main process reads a protected folder once and opens System Settings at a privacy pane (see
* folder-access.ts). It lives here because it has to: macOS asks about Desktop, Documents and
* Downloads only on behalf of the app it holds responsible, and the app is this process. What
* to tell the user about the outcome is the Web App's.
*
* Dev isolation: the dev profile — an unpackaged run, or any build launched with `--dev`
* — takes a dev-suffixed identity (own userData, and with it the single-instance lock and
* sticky port) and defaults to the ~/.penguin/dev-data root, so it runs beside an
* installed release build (see app-identity.ts). Updating and the per-launch CLI link
* repair stay with the release profile: both touch the one installation the two
* instances share.
*
* Smoke hook (PENGUIN_DESKTOP_SMOKE=1): after the first load settles, print a
* `DESKTOP-SMOKE-RESULT {json}` line (+ screenshot when PENGUIN_DESKTOP_SMOKE_SHOT is
* set) and quit through the regular quit path, exercising the graceful server stop.
*/
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { app, BrowserWindow, dialog, screen, session, shell } from "electron";
import type { WindowOpenHandlerResponse } from "electron";
import { resolveRoot } from "@adelie/core";
import type { DesktopLoginItemStatus } from "@adelie/server/api";
import { mintApiToken } from "@adelie/server/auth-token";
import { liveServerLock } from "@adelie/server/lock";
import type { ServerLock } from "@adelie/server/lock";
import { appIdentity, desktopDataRoot, resolveProfile } from "./app-identity.js";
import { grantsPermission } from "./app-permissions.js";
import {
createSignInGuard,
isLoginPageUrl,
planSignIn,
signInFailureDialog,
} from "./attach-session.js";
import type { SignInFailure } from "./attach-session.js";
import { embeddedCliEntry } from "./launcher.js";
import { webDistEntry, webDistFor } from "./web-dist.js";
import { resolveTrayIcon, resolveWindowIcon } from "./app-icon.js";
import { createBuiltinBrowserShell } from "./builtin-browser.js";
import { installCliCommand, ensureCliCommand, currentCliInstallKind } from "./cli-install.js";
import { logLine, logServerOutput, startDesktopLog, stopDesktopLog } from "./desktop-log.js";
import { handleFolderAccessFrame } from "./folder-access.js";
import type { FolderAccessFrameDeps } from "./folder-access.js";
import { applyLoginShellEnv } from "./login-shell-env.js";
import {
loginItemStatusMessage,
loginItemStatusOf,
loginItemWrite,
parseLoginItemCommand,
startedAtLogin,
supportsLoginItem,
} from "./login-item.js";
import { installAppMenu } from "./menu.js";
import { startEmbeddedServer, stopEmbeddedServer } from "./server-process.js";
import type { EmbeddedServer } from "./server-process.js";
import { resolveTrayLocale } from "./tray-menu.js";
import type { TrayLocale } from "./tray-menu.js";
import { installTray } from "./tray.js";
import type { TrayHandle } from "./tray.js";
import {
parseTrayCommand,
readTrayPrefs,
trayStatusMessage,
updateTrayPrefs,
} from "./tray-prefs.js";
import { parsePetCommand, petStatusMessage, readPetPrefs, updatePetPrefs } from "./pet-prefs.js";
import { PET_WINDOW_OPTIONS, petShotPath, petWindowPosition, petWindowUrl } from "./pet-window.js";
import { getUpdaterStatus, handleUpdaterCommand, initUpdater, onUpdaterStatus } from "./updater.js";
import { parseUpdaterCommand, updaterStatusMessage } from "./updater-status.js";
import {
APP_WINDOW_OPTIONS,
childGoneLine,
classifyWindowOpen,
desktopLoginUrl,
hidesOnClose,
isAppUrl,
isExternalScheme,
isLocalSurfaceUrl,
MAX_SERVER_RESTARTS,
RENDERER_HEALTHY_MS,
rendererGoneLine,
rendererReloadDelayMs,
restartDelayMs,
urlForLog,
} from "./util.js";
// Identity first: the name decides the userData directory, which also keys the
// single-instance lock requested below — the dev profile takes a dev-suffixed identity
// so it runs beside an installed release build instead of quitting into its window
// (#292; see app-identity.ts).
const profile = resolveProfile({ argv: process.argv, isPackaged: app.isPackaged });
const identity = appIdentity(profile);
app.setName(identity.name);
// Windows toasts (the web app's task-completion notifications) need the AppUserModelID
// of the installed shortcuts; electron-builder stamps them with the appId. Keep the
// release value in sync with electron-builder.yml. Dev runs stamp the dev-suffixed id
// so their taskbar/toast identity never claims the installed app's.
if (process.platform === "win32") app.setAppUserModelId(identity.appUserModelId);
let win: BrowserWindow | null = null;
let tray: TrayHandle | null = null;
/** The Appearance switch's value; the tray exists exactly while this is true and one could be created. */
let showTrayIcon = true;
/**
* The pet window, and the Appearance switch's value for it. The window exists exactly while the
* preference is on and the app origin is known (see openPet).
*/
let petWin: BrowserWindow | null = null;
let showPet = false;
/**
* The language the tray menu is drawn in. Seeded from the stored report, or from the device
* when there is none, so the first menu of a fresh launch is already right — the Web App's
* own report arrives only once a window has loaded far enough to send it.
*/
let trayLocale: TrayLocale = "en";
/**
* Whether this launch was started by Windows' own login item (see login-item.ts). Read from
* process.argv rather than anywhere near Electron, for the same reason `profile` is.
*/
const launchedAtLogin = startedAtLogin(process.argv);
/**
* Whether this launch keeps its window hidden: the login item started it AND there is a tray icon
* to bring the window back from. A hidden app with no icon would be a window nobody can reopen
* except by launching the app again, which is why the tray is part of the condition — the same
* reasoning `hidesOnClose` (util.ts) applies to close-to-tray. Resolved before boot, once the
* tray's own preference has been read and the install attempted.
*/
let startHidden = false;
let server: EmbeddedServer | null = null;
/** The live server child, for pushes that are not answers to one of its messages. */
let relayChild: EmbeddedServer["child"] | null = null;
/**
* The built-in browser's guests and their relay (see the header). Frames for the server go to
* whichever child is live; with none, a push is dropped and the next server asks for the tabs.
*/
const builtinBrowser = createBuiltinBrowserShell({
post: (message) => relayChild?.postMessage(message),
locale: () => trayLocale,
log: (line) => logLine(`[shell] ${line}`),
});
/** The Workspace picker's macOS folder access (see the header); replies go to whichever child is live. */
const folderAccess: FolderAccessFrameDeps = {
platform: process.platform,
isPackaged: app.isPackaged,
readdir: (dir) => fs.promises.readdir(dir),
openExternal: (url) => shell.openExternal(url),
post: (reply) => relayChild?.postMessage(reply),
log: (line) => logLine(`[shell] ${line}`),
};
/** App origin (embedded or attached); null until boot resolves. */
let appOrigin: string | null = null;
let quitting = false;
let stopPromise: Promise<void> | null = null;
let restartAttempts = 0;
/** The main window's page died this many times in a row; a page that stays up resets it. */
let rendererDeaths = 0;
let rendererHealthyTimer: NodeJS.Timeout | null = null;
// app.name, not a literal: a dev run raises this box while the installed build may be
// running beside it, and a dialog titled "Adelie" cannot be attributed to either.
function fatal(context: string, err: unknown): void {
const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
dialog.showErrorBox(app.name, `${context}\n\n${detail}`);
app.exit(1);
}
/**
* Installs the App window's permission handlers on the default session (see app-permissions.ts
* for why notifications need one at all).
*
* Called once, before the window exists, and before boot() resolves an origin: both handlers
* read `appOrigin` at every check, so they answer for whatever origin this launch ended up on.
* `requestingUrl` is the page that asked; the check handler's `requestingOrigin` is already an
* origin, which is the same comparison isAppUrl makes.
*/
function allowAppNotifications(): void {
session.defaultSession.setPermissionCheckHandler((_contents, permission, requestingOrigin) =>
grantsPermission(permission, requestingOrigin, appOrigin),
);
session.defaultSession.setPermissionRequestHandler((contents, permission, callback, details) => {
const asked = details.requestingUrl ?? contents?.getURL() ?? "";
callback(grantsPermission(permission, asked, appOrigin));
});
}
function createWindow(url: string): void {
// Linux window/taskbar icon (and Windows dev runs); packaged Windows uses the exe
// resources and macOS its bundle icns, so those ignore it (see app-icon.ts).
const iconPath = resolveWindowIcon(app.getAppPath(), process.platform);
win = new BrowserWindow({
width: 1280,
height: 860,
show: false,
autoHideMenuBar: true,
...(iconPath !== null ? { icon: iconPath } : {}),
webPreferences: {
// The window is a plain browser: no Node, no preload — the minimal attack surface.
contextIsolation: true,
nodeIntegration: false,
sandbox: true,
// The built-in browser's tabs are <webview> guests of this page. This window only:
// windows it opens are built from their own preferences, which leave the tag off.
webviewTag: true,
},
});
builtinBrowser.host(win);
// Shown when it has painted — unless it was Windows' login item that started this launch, in
// which case the window is built and loaded but stays hidden: the tray is where the app waits,
// and every other way back to it (the tray menu, a second launch, the Dock) calls
// showMainWindow. Built rather than skipped, because a launch with no window at all is a shape
// nothing else in this file has: the pet waits on this window's first load, and the sign-in
// token that a fresh launch redeems arrives with it.
win.once("ready-to-show", () => {
if (!startHidden) win?.show();
});
// Close-to-tray: the window goes away, the app and its embedded server stay, and the tray
// icon is the way back. Every real exit — the tray's Quit, the app menu's, an OS logout —
// passes through before-quit first, which is what `quitting` reports.
win.on("close", (event) => {
const hide = hidesOnClose({
quitting,
trayShown: tray !== null,
closeToTray: tray?.closeToTray() ?? false,
});
if (!hide) return;
event.preventDefault();
win?.hide();
});
win.on("closed", () => {
win = null;
// The pet is chrome of this app, and chrome does not keep it alive: `window-all-closed` is
// what quits on Windows and Linux, and a floating penguin that held that back would leave a
// running server behind a window nobody can get back to. Only where closing the last window
// really does end the app — macOS keeps it in the Dock, and keeps the pet with it.
if (process.platform !== "darwin") closePet();
});
// The pet window waits for this: its page signs in with the same cookie this load is what
// establishes (see openPet). Idempotent, and it re-checks the preference, so a later load of
// the main window is where a pet that was switched on before boot finally appears.
win.webContents.on("did-finish-load", () => openPet());
// New windows, from this window and from every window it opens, go through one rule
// (classifyWindowOpen): only the Workspace preview hand-off, a preview page and a detached
// terminal get a window of this app; other sites go to the system browser; anything else
// on this instance is refused, since every other app path boots a second copy of the App.
// This window gets no exception of its own: the handler is not told which frame asked, and
// the Files panel previews Agent-written HTML in an iframe that allows popups, so any window
// allowed here is one that HTML can open too — a hidden one, it could own outright.
win.webContents.setWindowOpenHandler(({ url: target }) => openWindowFor(target, iconPath));
win.webContents.on("did-create-window", (child) => guardOpenedWindow(child, iconPath));
win.webContents.on("will-navigate", (event, target) => {
if (!isAppUrl(target, appOrigin)) {
event.preventDefault();
openInSystem(target);
}
});
// The catch-all for every route to the sign-in page — an attached instance that never saw
// this shell's token, a session that lapsed, a claim that failed. The page asks for a
// password this installation does not have, so the shell answers it the way it answers
// attach mode (see signInFromDataRoot). Both events are needed: the App routes to the
// sign-in page within the loaded page, and the server redirects to it across a load.
win.webContents.on("did-navigate", (_event, url) => onMainWindowNavigated(url));
win.webContents.on("did-navigate-in-page", (_event, url, isMainFrame) => {
if (isMainFrame) onMainWindowNavigated(url);
});
watchForSignOut(win);
// The page's renderer died (the app-level handler below logs why): reload it, after a pause
// that grows while it keeps dying, so a page that crashes as it loads cannot spin.
const target = win;
target.webContents.on("render-process-gone", () => reloadAfterRendererDeath(target));
target.webContents.on("unresponsive", () => logLine("[shell] the window stopped responding"));
target.webContents.on("responsive", () => logLine("[shell] the window responds again"));
armSmokeProbe(win);
void win.loadURL(url);
}
/**
* Reloads the main window's page after its renderer died: at once the first time, then after
* a growing pause (rendererReloadDelayMs) while it keeps dying. A page that then stays up for
* RENDERER_HEALTHY_MS starts the ladder over.
*/
function reloadAfterRendererDeath(target: BrowserWindow): void {
if (rendererHealthyTimer !== null) clearTimeout(rendererHealthyTimer);
rendererHealthyTimer = null;
const wait = rendererReloadDelayMs(rendererDeaths);
rendererDeaths += 1;
if (wait > 0) logLine(`[shell] the window's page keeps dying; reloading it in ${wait} ms`);
setTimeout(() => {
if (quitting || target.isDestroyed()) return;
target.webContents.reload();
rendererHealthyTimer = setTimeout(() => {
rendererDeaths = 0;
rendererHealthyTimer = null;
}, RENDERER_HEALTHY_MS);
}, wait);
}
/**
* Answers a window-open request from any window of this app (see classifyWindowOpen in
* util.ts). A refusal is logged, by origin and path only: the user clicked something, and
* this line is the one trace of why nothing opened.
*/
function openWindowFor(target: string, iconPath: string | null): WindowOpenHandlerResponse {
switch (classifyWindowOpen(target, appOrigin)) {
case "window":
return {
action: "allow",
// Electron merges the page's `window.open` feature string under this override, so
// every key a page could use to hide the window is pinned here (APP_WINDOW_OPTIONS).
overrideBrowserWindowOptions: {
...(iconPath !== null ? { icon: iconPath } : {}),
// Same hardening as the main window: a preview is Agent-written, untrusted HTML
// and must never get Node. Nor <webview>, the main window's alone: Electron copies
// an opener's preference only when it is the safe one, so without this line the
// main window's `webviewTag: true` leaves a features string (`webviewTag=yes`) in
// charge.
webPreferences: {
contextIsolation: true,
nodeIntegration: false,
sandbox: true,
webviewTag: false,
},
...APP_WINDOW_OPTIONS,
},
};
case "external":
void shell.openExternal(target);
return { action: "deny" };
case "deny":
logLine(`[shell] refused to open a window for ${urlForLog(target)}`);
return { action: "deny" };
}
}
/**
* The rules a window opened by this app lives under — and, in turn, every window that one
* opens: a window-open handler belongs to one window, so a window opened from a preview page
* would otherwise open anything at all. Its navigation policy is "stay within this instance's
* loopback surface": a child lands on the preview host after the redirect, and the main
* window's stricter app-origin-only rule would bounce the preview itself out. A window stays
* open when one of its links opens externally.
*
* The window is also kept where the user can see it. APP_WINDOW_OPTIONS pins what the page's
* feature string could hide, but a position is not an option to pin — `left`/`top` arrive as
* `x`/`y` — so the window is centered here instead, and the page's own `moveTo`/`resizeTo`,
* which Electron would otherwise apply, is refused: off-screen is hidden too.
*/
function guardOpenedWindow(child: BrowserWindow, iconPath: string | null): void {
child.center();
child.webContents.on("content-bounds-updated", (event) => event.preventDefault());
child.webContents.setWindowOpenHandler(({ url: target }) => openWindowFor(target, iconPath));
child.webContents.on("did-create-window", (next) => guardOpenedWindow(next, iconPath));
// A session that dies while a child window is open sends that window to the sign-in page
// too — the App's guard redirects on the first 401, wherever it is rendered. A sign-in form
// is of no use in a subordinate surface: there is no password to type, and signing back in
// is the main window's business, which it now does by itself. So the child closes instead,
// which for a detached terminal returns its tab to the dock in the main window rather than
// stranding it behind a form. A preview window never reaches this page: an unauthorized
// preview hand-off answers with an API error, not the App.
const closeOnSignInPage = (url: string): void => {
if (isLoginPageUrl(url, appOrigin)) child.close();
};
child.webContents.on("did-navigate", (_event, url) => closeOnSignInPage(url));
child.webContents.on("did-navigate-in-page", (_event, url, isMainFrame) => {
if (isMainFrame) closeOnSignInPage(url);
});
child.webContents.on("will-navigate", (event, target) => {
if (!isLocalSurfaceUrl(target, appOrigin)) {
event.preventDefault();
openInSystem(target);
}
});
}
/** A navigation that leaves the app: a web or mail link goes to the system; any other scheme is refused. */
function openInSystem(target: string): void {
if (isExternalScheme(target)) void shell.openExternal(target);
else logLine(`[shell] refused to hand ${urlForLog(target)} to the system`);
}
/**
* Bring the main window forward, whatever state it is in: hidden by close-to-tray, minimized,
* or gone entirely (a closed window with close-to-tray off). Used by the tray icon, a second
* launch, and the macOS Dock.
*/
function showMainWindow(): void {
if (win === null) {
if (appOrigin !== null) createWindow(`${appOrigin}/`);
return;
}
if (win.isMinimized()) win.restore();
win.show();
win.focus();
}
/**
* Tray navigation. The window is a plain browser, so a destination is just a URL to load —
* no IPC channel into the Web App. Before boot resolves an origin there is nowhere to go, and
* showing the window is the whole action. A window that has to be created starts on the
* destination rather than on the app root: loading `/` first would boot the whole Web App
* only to abort it a tick later, with the aborted load's rejection going unhandled.
*/
function navigateMainWindow(target: string): void {
if (appOrigin === null) {
showMainWindow();
return;
}
const url = `${appOrigin}${target}`;
if (win === null) {
createWindow(url);
return;
}
showMainWindow();
void win.loadURL(url);
}
// --- signing the window in -------------------------------------------------
/** The data root this shell owns; null until boot resolves it. */
let shellDataRoot: string | null = null;
/**
* The lock of the server this shell attached to instead of starting its own, so a failure
* can name the process holding the data root; null while the server is this shell's.
*/
let attachedServer: ServerLock | null = null;
/**
* Which arrivals at the sign-in page the shell answers with a session — one attempt per
* stay, and none at all after a sign-out. It starts fresh with the process, which is what
* makes a launch the way back in after signing out (see attach-session.ts).
*/
const signInGuard = createSignInGuard();
/**
* Puts a session cookie for the current origin into the window's cookie store, by minting a
* session row in the data root this shell owns. False means it could not and the dialog
* explaining that is up; the caller then lets the window reach the sign-in page, which is at
* least a page with an explanation behind it rather than a dead end.
*/
async function signInFromDataRoot(): Promise<boolean> {
const root = shellDataRoot;
if (root === null || appOrigin === null) return false;
const plan = planSignIn({ root, origin: appOrigin, mint: mintApiToken });
if (plan.outcome === "failed") {
showSignInFailure(root, plan.failure);
return false;
}
try {
await session.defaultSession.cookies.set(plan.cookie);
return true;
} catch (err) {
// The row exists and the cookie store refused it. Rare enough to have no handling of its
// own, and identical from where the user sits, so it takes the same explanation.
showSignInFailure(root, { reason: "failed", detail: String(err) });
return false;
}
}
/** Reports a failed sign-in: one line in the log, and the dialog the user acts on. */
function showSignInFailure(dataRoot: string, failure: SignInFailure): void {
logLine(`[shell] the window could not be signed in: ${failure.detail}`);
const opts = {
type: "warning" as const,
title: app.name,
...signInFailureDialog({ dataRoot, other: attachedServer, failure }),
};
void (win !== null ? dialog.showMessageBox(win, opts) : dialog.showMessageBox(opts));
}
/** The App's sign-out, as a request pattern: the one intent a navigation cannot express. */
const SIGN_OUT_REQUEST = "*://*/api/auth/logout";
/**
* Watches for the App ending the session on purpose, which the catch-all must not undo.
* A sign-out leads to the same page as an expired session and needs the opposite answer, and
* the page never tells the shell which it is — so the intent is read off the request the App
* makes to end the session. The listener belongs to the session rather than to one window, so
* a sign-out from any window of this app counts, and registering it again replaces it.
*/
function watchForSignOut(target: BrowserWindow): void {
target.webContents.session.webRequest.onCompleted({ urls: [SIGN_OUT_REQUEST] }, (details) => {
// A refused sign-out leaves the session alive, so the window never reaches the sign-in
// page, and there is nothing to suppress.
if (details.statusCode < 400 && isAppUrl(details.url, appOrigin)) signInGuard.signedOut();
});
}
/** Runs the guard's decision for wherever the main window has just landed. */
function onMainWindowNavigated(url: string): void {
if (signInGuard.arrived(url, appOrigin) !== "rescue") return;
void signInFromDataRoot().then((signedIn) => {
// The app root, not a reload: the page underneath IS the sign-in page, and reloading it
// shows it for a beat before the App redirects a signed-in window away from it. A failed
// attempt loads nothing — the window is already going where it would be sent.
const landing = signedIn && appOrigin !== null ? `${appOrigin}/` : null;
signInGuard.tried(landing);
if (landing !== null) void win?.loadURL(landing);
});
}
// --- tray -----------------------------------------------------------------
/**
* Creates the tray icon if the preference asks for one and there is none. Idempotent: the
* app installs exactly one tray, and a platform that cannot host one (a Linux desktop
* without a tray, a headless run) simply leaves `tray` null — see installTray.
*/
function openTray(): void {
// `quitting`: before-quit takes the icon down, and a frame still in flight from the
// page must not put one back for the seconds the graceful server stop takes.
if (quitting || !showTrayIcon || tray !== null) return;
tray = installTray({
userDataDir: app.getPath("userData"),
iconPath: resolveTrayIcon(app.getAppPath(), process.platform),
appName: app.name,
locale: trayLocale,
onShowWindow: showMainWindow,
onNavigate: navigateMainWindow,
onQuit: () => app.quit(),
log: (line) => logLine(`[shell] ${line}`),
});
}
/**
* Applies Settings › Appearance's tray switch: the icon appears or goes at once, no
* restart, and the choice is stored for the next launch. Turning it off also turns off
* close-to-tray in effect — with no icon the window's close handler stops intercepting
* (see hidesOnClose), so the window can never hide where nothing could bring it back.
*/
function setShowTrayIcon(next: boolean): void {
showTrayIcon = next;
try {
updateTrayPrefs(app.getPath("userData"), { showTrayIcon: next });
} catch (err) {
logLine(`[shell] the tray preference could not be saved: ${String(err)}`);
}
if (next) {
openTray();
} else {
tray?.dispose();
tray = null;
}
pushTrayStatus();
}
/** Tells the page what the tray is actually doing, which is what its switch renders. */
function pushTrayStatus(): void {
relayChild?.postMessage(trayStatusMessage(showTrayIcon, trayLocale));
}
/**
* Applies the Web App's UI language to the tray menu. The menu is built per popup, so a
* change costs nothing until the next one is opened — except on Linux, where the menu is
* attached to the icon and has to be rebuilt in place; the tray handle does that itself.
*/
function setTrayLocale(next: TrayLocale): void {
if (next === trayLocale) return;
trayLocale = next;
try {
updateTrayPrefs(app.getPath("userData"), { locale: next });
} catch (err) {
logLine(`[shell] the tray language could not be saved: ${String(err)}`);
}
tray?.setLocale(next);
pushTrayStatus();
}
// --- the desktop pet -------------------------------------------------------
/**
* Creates the pet window if the preference asks for one, the app origin is known and there is
* none. Idempotent, and called from three places: app boot has finished, the main window has
* finished a load (its cookie is what the pet page signs in with — see below), and the
* Appearance switch has just been turned on.
*
* The window is a second plain browser on this app's own origin, showing `/pet`, so it needs
* nothing the main window does not already have: no preload, no IPC bridge, no separately served
* page. That is also why it waits for the main window's first load — the session cookie arrives
* with it, and a pet page that asked too early would render its "not signed in" nothing and never
* ask again.
*/
function openPet(): void {
if (quitting || !showPet || petWin !== null || appOrigin === null) return;
const origin = appOrigin;
// On the display the app window is on, beside its bottom-right corner: the pet is a companion
// to the window the user is working in, not to whichever monitor the cursor happens to be on.
const display =
win !== null && !win.isDestroyed()
? screen.getDisplayMatching(win.getBounds())
: screen.getPrimaryDisplay();
const pet = new BrowserWindow({
...PET_WINDOW_OPTIONS,
...petWindowPosition(display.workArea),
});
petWin = pet;
// Chrome, not a browsing surface: it opens no window, and a navigation that leaves the app
// goes to the system browser like any other (the pet page itself has no links).
pet.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
pet.webContents.on("will-navigate", (event, target) => {
if (!isAppUrl(target, appOrigin)) {
event.preventDefault();
openInSystem(target);
}
});
// Shown only once it has painted: a transparent window that has drawn nothing is a flash of
// the desktop showing through. showInactive, because the pet appearing must not take the focus
// away from whatever the user is typing into.
pet.once("ready-to-show", () => {
if (!pet.isDestroyed()) pet.showInactive();
});
pet.on("closed", () => {
petWin = null;
});
void pet.loadURL(petWindowUrl(origin));
}
/**
* Closes the pet window, now. `destroy` rather than `close`: switching the pet off is a decision
* about chrome, nothing in it can be unsaved, and a renderer that is wedged must not be able to
* keep a window on screen after the user asked for it to go.
*/
function closePet(): void {
petWin?.destroy();
petWin = null;
}
/**
* Applies Settings › Appearance's pet switch (or the pet's own "hide me" row, which writes the
* same field through the same route): the window appears or goes at once, no restart.
*/
function setShowPet(next: boolean): void {
showPet = next;
try {
updatePetPrefs(app.getPath("userData"), { showPet: next });
} catch (err) {
logLine(`[shell] the pet preference could not be saved: ${String(err)}`);
}
if (next) openPet();
else closePet();
pushPetStatus();
}
/** Tells the page what the pet window is actually doing, which is what its switch renders. */
function pushPetStatus(): void {
relayChild?.postMessage(petStatusMessage(showPet));
}
// --- the Windows login item -------------------------------------------------
/**
* Whether this build has a sign-in entry to manage at all (see supportsLoginItem in
* login-item.ts): the installed app, on Windows. Every other form answers the page with
* `supported: false`, and the page draws no row for that rather than a switch that writes nothing.
*/
const loginItemSupported = supportsLoginItem({ platform: process.platform, profile });
/**
* Reads Windows' own record of the sign-in entry, straight from the operating system. Nothing is
* cached and nothing is stored: the user can disable the entry from Task Manager without the app
* being told, so every push and every read is a fresh look (which is also why there is no
* userData file beside the tray's and the pet's — see login-item.ts).
*/
function loginItemStatus(): DesktopLoginItemStatus {
return loginItemStatusOf({
supported: loginItemSupported,
executableWillLaunchAtLogin:
loginItemSupported && app.getLoginItemSettings().executableWillLaunchAtLogin,
});
}
/**
* Applies Settings › Appearance's sign-in switch: the Run entry is written or deleted now, and
* what Windows says afterwards is pushed back to the page. `enabled: true` is what makes turning
* the switch back on take effect after the entry was disabled in Task Manager (see
* loginItemWrite).
*/
function setLoginItem(openAtLogin: boolean): void {
if (loginItemSupported) {
try {
app.setLoginItemSettings(
loginItemWrite({ name: identity.name, execPath: process.execPath, openAtLogin }),
);
} catch (err) {
logLine(`[shell] the sign-in entry could not be written: ${String(err)}`);
}
}
pushLoginItemStatus();
}
/** Tells the page what Windows says about starting at sign-in, which is what its row renders. */
function pushLoginItemStatus(): void {
relayChild?.postMessage(loginItemStatusMessage(loginItemStatus()));
}
/**
* Shell relay over the utilityProcess port: forward the account-menu row's check/install
* frames to the updater, the Appearance switch's frames to the tray, to the pet window and to
* Windows' login item, the built-in browser's commands to its guests and the Workspace picker's
* folder-access requests to folder-access.ts, push every updater status fold back, and push all
* four current states now — the fresh child, restarts included, must not start blind. The
* subscription dies with the child; the next start wires the next one.
*/
function wireShellRelay(child: EmbeddedServer["child"]): void {
relayChild = child;
child.on("message", (message: unknown) => {
if (builtinBrowser.handle(message)) return;
if (handleFolderAccessFrame(message, folderAccess)) return;
const action = parseUpdaterCommand(message);
if (action !== null) {
handleUpdaterCommand(action);
return;
}
const command = parseTrayCommand(message);
if (command !== null) {
if (command.locale !== undefined) setTrayLocale(command.locale);
if (command.showTrayIcon !== undefined) setShowTrayIcon(command.showTrayIcon);
return;
}
const pet = parsePetCommand(message);
if (pet !== null && pet.showPet !== undefined) setShowPet(pet.showPet);
const loginItem = parseLoginItemCommand(message);
if (loginItem !== null && loginItem.openAtLogin !== undefined) {
setLoginItem(loginItem.openAtLogin);
}
});
const unsubscribe = onUpdaterStatus((status) => child.postMessage(updaterStatusMessage(status)));
child.on("exit", () => {
unsubscribe();
if (relayChild === child) relayChild = null;
});
child.postMessage(updaterStatusMessage(getUpdaterStatus()));
pushTrayStatus();
pushPetStatus();
pushLoginItemStatus();
}
/** Starts (or restarts) the embedded server and points the window at the claim link. */
async function startServerAndWindow(dataRoot: string): Promise<void> {
const webDist = webDistFor({
isPackaged: app.isPackaged,
appPath: app.getAppPath(),
env: process.env,
});
// Checked here, not left to the server: a server with nothing to serve still starts,
// and the window would open on a 404 with no line in the log naming the directory.
if (webDist !== null && !fs.existsSync(webDistEntry(webDist))) {
throw new Error(
`The Web App is missing: ${webDistEntry(webDist)} does not exist. ` +
`This build was packed without the web assets, or PENGUIN_WEB_DIST points elsewhere.`,
);
}
const started = await startEmbeddedServer({
dataRoot,
webDist,
cliEntry: embeddedCliEntry({
isPackaged: app.isPackaged,
appPath: app.getAppPath(),
env: process.env,
}),
profile,
portFile: path.join(app.getPath("userData"), "server-port"),
preferredPortFile: path.join(app.getPath("userData"), "preferred-port"),
log: (chunk, stream) => logServerOutput(stream, chunk),
});
server = started;
appOrigin = started.origin;
wireShellRelay(started.child);
// A run that stays up for a minute is healthy: reset the restart budget so a crash
// days later starts a fresh 1s/2s/4s ladder instead of hitting the cap immediately.
const healthyTimer = setTimeout(() => {
restartAttempts = 0;
}, 60_000);
started.child.on("exit", (code) => {
clearTimeout(healthyTimer);
void handleServerExit(dataRoot, code);
});
const url = desktopLoginUrl(started.origin, started.token);
if (win === null) createWindow(url);
else void win.loadURL(url);
}
/** Unexpected server death: restart with backoff; give up with an error dialog at the cap. */
async function handleServerExit(dataRoot: string, code: number): Promise<void> {
if (quitting) {
logLine(`[shell] server exited (code ${code})`);
return;
}
server = null;
if (restartAttempts >= MAX_SERVER_RESTARTS) {
fatal(`The embedded server keeps exiting (last exit code ${code}).`, "Giving up.");
return;
}
const wait = restartDelayMs(restartAttempts);
restartAttempts += 1;
logLine(`[shell] server exited (code ${code}); restarting in ${wait}ms`);
await new Promise((resolve) => setTimeout(resolve, wait));
if (quitting) return;
try {
await startServerAndWindow(dataRoot);
} catch (err) {
fatal("The embedded server could not be restarted.", err);
}
}
async function boot(): Promise<void> {
// Explicit PENGUIN_HOME wins; otherwise the release profile shares the CLI's data root
// and the dev profile takes the repo's dev root (the rule, and why, live in app-identity.ts).
const dataRoot = desktopDataRoot({
envHome: process.env.PENGUIN_HOME,
profile,
homedir: os.homedir(),
releaseRoot: resolveRoot,
});
shellDataRoot = dataRoot;
if (profile === "dev") {
logLine(`[shell] dev instance '${app.name}' on data root ${dataRoot}`);
}
const existing = await liveServerLock(dataRoot);
if (existing !== null) {
// Attach mode: another server — a `penguin web` run, an older app still up — holds this
// data root, and the one-shot token only works against a server this shell spawned. The
// window is signed in the other way the product recognizes instead: a session minted
// straight into the root this shell owns, which is the same authority the CLI mints on.
attachedServer = existing;
appOrigin = `http://localhost:${existing.port}`;
logLine(`[shell] attaching to the running server at ${appOrigin} (pid ${existing.pid})`);
await signInFromDataRoot();
// Either way the window opens on the app root: signed in it goes straight into the App,
// and otherwise the App sends it to the sign-in page the dialog has just explained. The
// attempt is recorded with that URL, so arriving there does not buy a second one.
const landing = `${appOrigin}/`;
signInGuard.tried(landing);
createWindow(landing);
return;
}
await startServerAndWindow(dataRoot);
}
// --- app lifecycle ---------------------------------------------------------
if (!app.requestSingleInstanceLock()) {
app.quit();
} else {
// The log file is this instance's from here: a second launch quits above without touching it.
const logFile = startDesktopLog(path.join(app.getPath("userData"), "logs", "desktop.log"));
logLine(
`[shell] ${app.name} ${app.getVersion()} starting (Electron ${process.versions.electron}, ` +
`${process.platform} ${process.arch}, ${Math.round(os.totalmem() / 2 ** 30)} GB memory); log ${logFile}`,
);
app.on("second-instance", () => showMainWindow());
// Every renderer and child process that dies says so in the log: the app window's page (which
// the window then reloads), a browser tab's, DevTools', the GPU process, the embedded server.
app.on("render-process-gone", (_event, contents, details) => {
logLine(
`[shell] ${rendererGoneLine({
type: contents.getType(),
id: contents.id,
url: contents.getURL(),
reason: details.reason,
exitCode: details.exitCode,
})}`,
);
});
app.on("child-process-gone", (_event, details) => {
logLine(
`[shell] ${childGoneLine({
type: details.type,
reason: details.reason,
exitCode: details.exitCode,
...(details.serviceName !== undefined ? { serviceName: details.serviceName } : {}),
...(details.name !== undefined ? { name: details.name } : {}),
})}`,
);
});
app.on("will-quit", () => stopDesktopLog());
app.on("window-all-closed", () => {
// macOS keeps the app alive in the Dock; elsewhere closing the window quits.
if (process.platform !== "darwin") app.quit();
});
// Dock click: the window may be hidden in the tray rather than gone, so show before recreate.
app.on("activate", () => showMainWindow());
// Quit path: stop the embedded server gracefully first (shutdown endpoint → kill),
// then let the quit proceed. Attach mode has no child to stop.
app.on("before-quit", (event) => {
quitting = true;
// The icon goes as soon as the app is on its way out, rather than lingering through the
// graceful server stop; nulling it keeps the second pass (after the stop) from destroying
// an already destroyed tray.
tray?.dispose();
tray = null;
if (server !== null && stopPromise === null) {
event.preventDefault();
const running = server;
server = null;
stopPromise = stopEmbeddedServer(running).finally(() => app.quit());
}
});
void app.whenReady().then(() =>
(async () => {
// GUI launches on macOS/Linux miss the login shell's exports (model API keys for
// core's env fallback, the PATH the agent shell needs). Import them fill-missing
// before anything reads process.env — boot() resolves PENGUIN_HOME from it, and
// the forked server inherits it (#351).
await applyLoginShellEnv({
platform: process.platform,
env: process.env,
shell: process.env.SHELL,
log: (line) => logLine(`[shell] ${line}`),
});
// The App page may ask for notifications and nothing new; installed before the window
// exists, so the very first request already finds a handler.
allowAppNotifications();
// Standard menu plus native desktop-only actions; the window gets no IPC channel.
// The install item is the release profile's, like the per-launch repair below: the
// `penguin` command has one owner, and a `--dev` instance of the same install would
// rewrite it and record having done so in its own userData.
installAppMenu({
includeCliInstall: profile === "release" && currentCliInstallKind() !== null,
onInstallCli: () => void installCliCommand(win),
});
// Before boot, and whatever the window is doing: the icon is there for as long as the
// app runs. Its menu's navigation entries tolerate an origin that is not resolved yet,
// and the close-to-tray preference has to be in hand before the first window close can
// happen.
const trayPrefs = readTrayPrefs(app.getPath("userData"));
showTrayIcon = trayPrefs.showTrayIcon;
// Nothing has reported a language yet on a first launch, so the device decides — the
// same rule the Web App applies to its own "follow the system" default.
trayLocale = trayPrefs.locale ?? resolveTrayLocale(app.getLocale());
openTray();
// A launch Windows' own login item started waits in the tray instead of popping a window
// over whatever the user just signed in to open — but only where there is a tray icon to
// come back from (see startHidden). The attempt above is what decides that: a platform with
// no tray leaves `tray` null, and this launch then behaves like any other.
startHidden = launchedAtLogin && tray !== null;
if (startHidden) logLine("[shell] started by the sign-in entry; waiting in the tray");
// The pet's preference, read before boot for the same reason: the window it decides about
// is opened by the main window's first load, which boot is what starts.
showPet = readPetPrefs(app.getPath("userData")).showPet;
initUpdater(() => win);
await boot();
// Install or repair the bundled 'penguin' command. Runs every launch: that is what
// carries it across an update and repairs a link a moved app left dangling. Only the
// release profile does it — a `--dev` instance of the same install has nothing of
// its own to link, and one owner keeps the link from being rewritten twice. Skipped
// in smoke mode — the macOS administrator prompt would hang the automated run.
if (profile === "release" && process.env.PENGUIN_DESKTOP_SMOKE !== "1") {
await ensureCliCommand();
}
})().catch((err) => fatal(`${app.name} failed to start.`, err)),
);
}
// --- smoke hook ------------------------------------------------------------
/** Render-settle delay before sampling the page in smoke mode. */
const SMOKE_SETTLE_MS = 2500;
function armSmokeProbe(target: BrowserWindow): void {
if (process.env.PENGUIN_DESKTOP_SMOKE !== "1") return;
target.webContents.once("did-finish-load", () => {
setTimeout(() => {
void (async () => {
try {
const pet = petWin;
const result = {
title: target.webContents.getTitle(),
url: target.webContents.getURL(),
origin: appOrigin,
embedded: server !== null,
// Whether the pet window is up, and what it is showing. Null is the honest answer for
// a run whose preference is off, so the probe reports it rather than only the cases
// where the window exists.
pet:
pet === null || pet.isDestroyed()
? null
: { url: pet.webContents.getURL(), title: pet.webContents.getTitle() },
};
const shot = process.env.PENGUIN_DESKTOP_SMOKE_SHOT;
if (shot) {
const { writeFileSync } = await import("node:fs");
const image = await target.webContents.capturePage();
writeFileSync(shot, image.toPNG());
// The pet is a window of its own, and its pixels are the only way to check that what
// it draws is the penguin and not a blank transparent rectangle: its shot lands beside
// the main window's when a run has one.
if (pet !== null && !pet.isDestroyed()) {
writeFileSync(petShotPath(shot), (await pet.webContents.capturePage()).toPNG());
}
}
process.stdout.write(`DESKTOP-SMOKE-RESULT ${JSON.stringify(result)}\n`);
} catch (err) {
process.stdout.write(`DESKTOP-SMOKE-RESULT ${JSON.stringify({ error: String(err) })}\n`);
} finally {
app.quit();
}
})();
}, SMOKE_SETTLE_MS);
});
}