Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

10.8 KB
Raw Blame
/**
 * Pure helpers for the desktop shell — no Electron imports, so they unit-test under
 * plain vitest.
 */

/** Parses the server's port-announcement file: a decimal port on the first line. */
export function parsePortFile(content: string): number | null {
  const m = /^(\d{1,5})\s*$/.exec(content.trim());
  if (!m) return null;
  const port = Number(m[1]);
  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
}

/**
 * The App origin for a port. Always `localhost`: on loopback the App is canonicalized
 * onto localhost and `127.0.0.1` is reserved as the preview host, which rejects /api.
 */
export function appOriginFor(port: number): string {
  return `http://localhost:${port}`;
}

/** The window's first navigation: redeems the shell's one-shot token for a cookie session. */
export function desktopLoginUrl(origin: string, token: string): string {
  return `${origin}/api/auth/claim?token=${encodeURIComponent(token)}`;
}

/**
 * Whether a navigation target stays inside the app window. Only the app origin itself
 * qualifies; everything else (external sites, and Workspace previews on the 127.0.0.1
 * counterpart host) opens in the system browser.
 */
export function isAppUrl(url: string, origin: string | null): boolean {
  if (origin === null) return false;
  try {
    return new URL(url).origin === origin;
  } catch {
    return false;
  }
}

const LOOPBACK_HOSTS: ReadonlySet<string> = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);

/**
 * The host Workspace previews are served from. On loopback the server always puts the App on
 * `localhost` and previews on this name (loopbackHostRoles in the server's preview-token
 * service), and the desktop always loads the App on `localhost` (appOriginFor, attach mode).
 */
const PREVIEW_HOST = "127.0.0.1";

/**
 * Whether a URL belongs to this instance's local surface: the app origin itself or its
 * loopback counterpart on the same port, which is where Workspace previews are served.
 * Preview windows navigate freely within it; anything else is external and belongs in
 * the system browser.
 */
export function isLocalSurfaceUrl(url: string, origin: string | null): boolean {
  if (origin === null) return false;
  let target: URL;
  let app: URL;
  try {
    target = new URL(url);
    app = new URL(origin);
  } catch {
    return false;
  }
  if (target.protocol !== app.protocol || target.port !== app.port) return false;
  return LOOPBACK_HOSTS.has(target.hostname) && LOOPBACK_HOSTS.has(app.hostname);
}

/** "Open in a new tab" for a Workspace HTML file: mints a preview token, then 302s to the preview host. */
const PREVIEW_REDIRECT_PATH = /^\/api\/sessions\/[^/]+\/files\/preview-redirect$/;

/** A terminal detached from the dock into a window of its own. */
const TERMINAL_PATH = "/terminal";

/**
 * Whether a URL may be handed to the operating system: a web page or a mail link. Never a
 * file, a script or a custom protocol handler — a preview window runs Agent-written HTML, and
 * `shell.openExternal` on such a URL launches whatever the OS has registered for it.
 */
export function isExternalScheme(url: string): boolean {
  let protocol: string;
  try {
    protocol = new URL(url).protocol;
  } catch {
    return false;
  }
  return protocol === "http:" || protocol === "https:" || protocol === "mailto:";
}

/** What a window-open request may do; see classifyWindowOpen. */
export type WindowOpenAction = "window" | "external" | "deny";

/**
 * Routes a request to open a new window — a `target="_blank"` link or a `window.open` call,
 * from the main window or from any window it opened.
 *
 * `window`, a window of this app, is for the three URL shapes that cannot work anywhere else:
 * - the Workspace preview hand-off, `/api/sessions/<id>/files/preview-redirect` on the app
 *   origin. It mints its token with the session cookie, so the system browser would get a 401;
 * - a preview page, `/preview/…` on the preview host, which is where a preview's own links and
 *   `window.open` calls land;
 * - a detached terminal, `/terminal` on the app origin: the page needs the session, and the
 *   opener watches the window it gets back to return the tab to the dock when it closes.
 *
 * `external`, the system browser, is for an http(s) or mailto URL that is not this instance —
 * another site, or another port on this machine, such as a dev server a conversation started.
 *
 * `deny` is everything else. Every other path on the app origin serves the SPA, and the
 * preview host redirects every non-preview path back to it, so a relative link in a chat reply
 * (`/chat/x.html`) would boot a second copy of the App in a new window on a page that does not
 * exist — one more window per click. Other schemes (`file:`, custom protocol handlers) are
 * refused outright rather than handed to the OS (isExternalScheme). With no origin, which no
 * window ever sees, everything is refused.
 *
 * `about:blank` — `window.open()` with no URL — is refused with the other schemes, and that is
 * load-bearing: a blank window inherits its opener's origin, so the opener can script it, and a
 * handler is not told which frame asked. The Files panel previews Agent-written HTML in an
 * iframe that allows popups, so a blank window allowed for any purpose would be a hidden window
 * that HTML could own. The Web App therefore asks for none when it is drawn by this shell's
 * renderer (it reads `Electron/` in the user agent, whatever session it holds): it opens
 * Penguin Go's authorization URL directly, which this rule routes to the system browser.
 */
export function classifyWindowOpen(url: string, origin: string | null): WindowOpenAction {
  if (origin === null || !isExternalScheme(url)) return "deny";
  const target = new URL(url);
  if (!isLocalSurfaceUrl(url, origin)) return "external";
  // Parses: isLocalSurfaceUrl answers false for an origin that does not.
  const appHost = new URL(origin).hostname;
  if (target.hostname === appHost) {
    return PREVIEW_REDIRECT_PATH.test(target.pathname) || target.pathname === TERMINAL_PATH
      ? "window"
      : "deny";
  }
  return target.hostname === PREVIEW_HOST && target.pathname.startsWith("/preview/")
    ? "window"
    : "deny";
}

/**
 * What a window of this app looks like, whatever the page that opened it asked for.
 *
 * Electron builds a new window's options as `{ show: true, width: 800, height: 600,
 * ...featuresFromThePage, ...override }` (lib/browser/guest-window-manager.ts), and the
 * page's `window.open` feature string may set `show`, `skipTaskbar`, `opacity`, `transparent`,
 * `focusable`, a position and size limits (allowedWindowOptions in
 * lib/browser/parse-features-string.ts). A preview page is Agent-written HTML, and a window it
 * is allowed to open must never be one the user cannot see: with `show=no`, `skipTaskbar=yes`
 * or `opacity=0` the "window" a `/preview/` URL earns would be as hidden as the blank one
 * classifyWindowOpen refuses, and same-origin with the preview that opened it. So every key
 * that can hide, dim, or shrink a window to nothing is spelled out here, and the override
 * spreads this last. Position is not an option — `left`/`top` land as `x`/`y` — so the window
 * is centered after creation, and a page's `moveTo`/`resizeTo` is refused (see
 * guardOpenedWindow in main.ts). The size limits are the defaults restated: 0 is Electron's
 * "no maximum".
 */
export const APP_WINDOW_OPTIONS = {
  width: 1100,
  height: 800,
  minWidth: 320,
  minHeight: 240,
  maxWidth: 0,
  maxHeight: 0,
  show: true,
  skipTaskbar: false,
  opacity: 1,
  transparent: false,
  focusable: true,
  hiddenInMissionControl: false,
  enableLargerThanScreen: false,
  autoHideMenuBar: true,
} as const;

/**
 * A URL as a log line may show it: origin and path for a web URL, the scheme alone for any
 * other. A query or a fragment can carry a token, and neither says where the request went.
 */
export function urlForLog(url: string): string {
  let target: URL;
  try {
    target = new URL(url);
  } catch {
    return "an unparsable URL";
  }
  return target.protocol === "http:" || target.protocol === "https:"
    ? `${target.origin}${target.pathname}`
    : `a ${target.protocol} URL`;
}

/** Max automatic server restarts before giving up with an error dialog. */
export const MAX_SERVER_RESTARTS = 3;

/** Restart backoff: 1s, 2s, 4s (attempt is 0-based). */
export function restartDelayMs(attempt: number): number {
  return Math.min(1000 * 2 ** attempt, 8000);
}

/** A window whose page stays up this long after a reload is healthy again: the next crash reloads at once. */
export const RENDERER_HEALTHY_MS = 60_000;

/**
 * How long the main window waits before reloading a page whose renderer died, by how many times
 * it has died in a row (0-based): at once the first time, then 1s, 2s, 4s … up to 30s, so a
 * page that crashes as it loads cannot spin the machine in a reload loop.
 */
export function rendererReloadDelayMs(attempt: number): number {
  return attempt <= 0 ? 0 : Math.min(1000 * 2 ** (attempt - 1), 30_000);
}

/** What died, as the log names it: Electron's render-process-gone details and the page. */
export interface RendererGone {
  /** `webContents.getType()`: the app window's page is a `window`, a browser tab a `webview`. */
  type: string;
  id: number;
  url: string;
  reason: string;
  exitCode: number;
}

/** The log line for a renderer that went away: which page, and why (never the page's query). */
export function rendererGoneLine(gone: RendererGone): string {
  const page = gone.url === "" ? "" : ` ${urlForLog(gone.url)}`;
  return `a renderer is gone: ${gone.type} ${gone.id}${page} (${gone.reason}, exit code ${gone.exitCode})`;
}

/** The log line for another child process that went away (Electron's child-process-gone details). */
export function childGoneLine(gone: {
  type: string;
  reason: string;
  exitCode: number;
  serviceName?: string;
  name?: string;
}): string {
  const names = [gone.serviceName, gone.name].filter(
    (name): name is string => name !== undefined && name !== "",
  );
  const named = names.length > 0 ? ` ${[...new Set(names)].join(" / ")}` : "";
  return `a child process is gone: ${gone.type}${named} (${gone.reason}, exit code ${gone.exitCode})`;
}

/**
 * Whether closing the main window hides it into the tray instead of destroying it.
 *
 * All three conditions are load-bearing. A quit already under way never hides — the close
 * that Electron runs on the way out has to complete. `trayShown` matters because without
 * an icon there is no way back to a hidden window: the close must proceed instead, which
 * leaves the app in the Dock on macOS and quits it on Windows and Linux through
 * window-all-closed. A running app with no window and no tray icon is a state the user
 * cannot escape, so it is one this must never produce.
 */
export function hidesOnClose(state: {
  quitting: boolean;
  trayShown: boolean;
  closeToTray: boolean;
}): boolean {
  return !state.quitting && state.trayShown && state.closeToTray;
}