acrylblends 1.0.7 → 1.0.8

package/plugins/agent-panel/client/main.ts

@@ -37,6 +37,77 @@ async function* events(response: Response): AsyncGenerator<PanelEvent> {
   }
 }
 
+/** What a run is read from: its events, and a way to end the run. A socket and a stream give the same events. */
+interface RunSource {
+  readonly events: AsyncIterable<PanelEvent>
+}
+
+/** A WebSocket is not one of the browser's six connections per host, so the panel's Stop and a run still work when two windows stream their own state. */
+let socketBroken = false
+let activeSocket: WebSocket | undefined
+
+/** Open the run socket and send the token and the first action. Rejects when the page cannot upgrade (a proxy, a server without `ws`): the caller falls back to the stream. */
+function openSocket(token: string, action: Record<string, unknown>): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(
+      `${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}${PREFIX}/run/ws`,
+    )
+    const timer = setTimeout(() => {
+      socket.close()
+      reject(new Error('the socket did not open in time'))
+    }, 4000)
+    socket.onopen = () => {
+      clearTimeout(timer)
+      socket.send(JSON.stringify({ t: 'hello', token }))
+      socket.send(JSON.stringify(action))
+      resolve(socket)
+    }
+    socket.onerror = () => {
+      clearTimeout(timer)
+      reject(new Error('the server refused the upgrade'))
+    }
+  })
+}
+
+/** The frames of an open run socket as panel events, until it closes. */
+async function* socketEvents(socket: WebSocket): AsyncGenerator<PanelEvent> {
+  const queue: PanelEvent[] = []
+  let wake: (() => void) | undefined
+  let closed: CloseEvent | undefined
+  socket.onmessage = (message) => {
+    try {
+      const frame = JSON.parse(String(message.data)) as { e?: unknown; d?: unknown }
+      if (typeof frame.e === 'string')
+        queue.push({ event: frame.e, data: (frame.d ?? {}) as Record<string, unknown> })
+    } catch {
+      // Not a frame of ours.
+    }
+    wake?.()
+  }
+  socket.onclose = (event) => {
+    closed = event
+    wake?.()
+  }
+  for (;;) {
+    const next = queue.shift()
+    if (next !== undefined) {
+      yield next
+      continue
+    }
+    if (closed !== undefined) {
+      if (closed.code === 4401)
+        yield {
+          event: 'error',
+          data: { message: 'the panel was not accepted (reload the page and try again)' },
+        }
+      return
+    }
+    await new Promise<void>((resolve) => {
+      wake = resolve
+    })
+  }
+}
+
 const css = `
 :host { all: initial }
 * { box-sizing: border-box; font: 14px system-ui, sans-serif }
@@ -68,6 +139,7 @@ textarea { width: 100%; min-height: 64px; resize: vertical; padding: 8px; border
 .row { display: flex; gap: 8px; align-items: center }
 .row button, header button { padding: 6px 12px; border: 1px solid #d1d5db; border-radius: 6px; background: #fff; cursor: pointer }
 .row button.send { background: #1f2937; color: #fff; border-color: #1f2937 }
+.row button:disabled { opacity: 0.45; cursor: not-allowed }
 `
 
 async function start(): Promise<void> {
@@ -194,12 +266,55 @@ async function start(): Promise<void> {
   // loads next follows it again. Only Stop cancels it.
   const headers = { 'content-type': 'application/json', 'x-agent-panel-token': session.token }
   let following = false
-  stop.addEventListener('click', () => void fetch(`${PREFIX}/stop`, { method: 'POST', headers }))
+  stop.addEventListener('click', () => {
+    // On the run's socket when there is one: a request would wait behind the browser's six connections per host.
+    if (activeSocket?.readyState === WebSocket.OPEN)
+      activeSocket.send(JSON.stringify({ t: 'stop' }))
+    else void fetch(`${PREFIX}/stop`, { method: 'POST', headers })
+  })
+  /** A run over the socket when the server upgrades, else over the stream, with one console warning saying why. */
+  const openRun = async (
+    action: { t: 'ask'; message: string; driver: string } | { t: 'follow' },
+  ): Promise<RunSource | { error: string } | undefined> => {
+    if (!socketBroken && typeof WebSocket !== 'undefined') {
+      try {
+        const socket = await openSocket(session.token, action)
+        activeSocket = socket
+        socket.addEventListener('close', () => {
+          if (activeSocket === socket) activeSocket = undefined
+        })
+        return { events: socketEvents(socket) }
+      } catch (cause) {
+        socketBroken = true
+        console.warn(
+          `agent-panel: the run could not open a WebSocket (${cause instanceof Error ? cause.message : String(cause)}); using server-sent events, which count against the browser's six connections per host`,
+        )
+      }
+    }
+    if (action.t === 'ask') {
+      const response = await fetch(`${PREFIX}/ask`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ message: action.message, driver: action.driver }),
+      })
+      if (!response.ok)
+        return {
+          error:
+            ((await response.json().catch(() => ({}))) as { error?: string }).error ??
+            `The panel answered ${response.status}.`,
+        }
+      return { events: events(response) }
+    }
+    const latest = await fetch(`${PREFIX}/run`, { headers })
+    return latest.ok && (latest.headers.get('content-type') ?? '').includes('text/event-stream')
+      ? { events: events(latest) }
+      : undefined
+  }
   /**
    * Show one run, as its events come, until it ends. `own` is true for a run this page just started (its question is on screen); a run found on load is shown from its question, and
    * a run that had already ended before the page loaded is only shown, never reloads the page.
    */
-  const watch = async (response: Response, own: boolean): Promise<void> => {
+  const watch = async (source: RunSource, own: boolean): Promise<void> => {
     let live = true
     following = true
     send.disabled = true
@@ -218,7 +333,7 @@ async function start(): Promise<void> {
     tick()
     const timer = setInterval(tick, 1000)
     try {
-      for await (const { event, data } of events(response)) {
+      for await (const { event, data } of source.events) {
         if (event === 'run') {
           live = data.ended !== true
           if (!own) {
@@ -270,29 +385,21 @@ async function start(): Promise<void> {
     input.value = ''
     line(message, 'me')
     try {
-      const response = await fetch(`${PREFIX}/ask`, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify({ message, driver: driver.value }),
-      })
-      if (!response.ok) {
-        line(
-          ((await response.json().catch(() => ({}))) as { error?: string }).error ??
-            `The panel answered ${response.status}.`,
-          'err',
-        )
+      const run = await openRun({ t: 'ask', message, driver: driver.value })
+      if (run === undefined) return
+      if ('error' in run) {
+        line(run.error, 'err')
         return
       }
-      await watch(response, true)
+      await watch(run, true)
     } catch (error) {
       line(`The request failed: ${error instanceof Error ? error.message : String(error)}`, 'err')
     }
   })
   // The latest run, if there is one: shown again after a reload (its question, its events), and followed if it is still going.
   try {
-    const latest = await fetch(`${PREFIX}/run`, { headers })
-    if (latest.ok && (latest.headers.get('content-type') ?? '').includes('text/event-stream'))
-      void watch(latest, false)
+    const latest = await openRun({ t: 'follow' })
+    if (latest !== undefined && !('error' in latest)) void watch(latest, false)
   } catch {
     // No run to show.
   }

package/plugins/agent-panel/headless.ts

@@ -195,3 +195,23 @@ export function headlessDriver(name: HeadlessName, root: string): ChatDriver {
     },
   }
 }
+
+/**
+ * Why a driver name cannot be used to ask a question, in a sentence: it is a terminal (picked in the panel, not asked over `/ask`), it is a coding agent that is not installed or not
+ * able to start, or pi without a key to reach its model. Nothing when the name is not one of the headless agents.
+ */
+export function whyNotChat(
+  name: string,
+  kind: 'chat' | 'terminal' | undefined,
+): string | undefined {
+  if (kind === 'terminal')
+    return `"${name}" is a terminal driver: pick it in the panel to open its terminal; /ask runs the chat drivers`
+  if (name !== 'claude' && name !== 'codex' && name !== 'pi') return undefined
+  if (!onPath(name))
+    return `${name} was not found on the PATH of the app, so the panel cannot start it`
+  const launch = resolveLaunch(name, [])
+  if ('error' in launch) return launch.error
+  if (name === 'pi' && !piHasDeepseekKey())
+    return 'pi needs a DeepSeek key: set DEEPSEEK_API_KEY in the environment of the app, or log in with pi once (it keeps the key in ~/.pi/agent/auth.json)'
+  return undefined
+}

package/plugins/agent-panel/index.ts

@@ -9,17 +9,24 @@
  * - Only the app's own page may ask (a same-origin request carrying the token), one run at a time, and every ask is written to `.acryl/audit/agent-panel.jsonl`.
  * - Development only: the plugin does nothing with `NODE_ENV=production` or `ACRYL_DOOR=off`.
  */
-import { randomBytes } from 'node:crypto'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { appendFileSync, mkdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import { clientModules } from '../acryl-node-server/src/client-modules.ts'
-import { streamSSE } from '../acryl-router/src/helpers/index.ts'
-import { Acryl } from '../acryl-router/src/index.ts'
+import { streamSSE, type UpgradeWebSocket } from '../acryl-router/src/helpers/index.ts'
+import { Acryl, type MiddlewareHandler } from '../acryl-router/src/index.ts'
+import { loopbackAuthority } from '../acryl-router/src/middleware/index.ts'
 import type {} from '../agent/index.ts'
 import type {} from '../extensions/index.ts'
 import type { ChatDriver } from './drivers.ts'
-import { agentDriver, availableHeadless, type HeadlessName, headlessDriver } from './headless.ts'
+import {
+  agentDriver,
+  availableHeadless,
+  type HeadlessName,
+  headlessDriver,
+  whyNotChat,
+} from './headless.ts'
 import { provideDrivers } from './registry.ts'
 
 export type {
@@ -117,25 +124,9 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       if (!fromOwnPage(c.req.raw.headers) || c.req.header('x-agent-panel-token') !== token)
         return c.json({ error: "only the app's own page may ask" }, 403)
       const body = (await c.req.json().catch(() => ({}))) as { message?: unknown; driver?: unknown }
-      const message = typeof body.message === 'string' ? body.message.trim() : ''
-      const driverName = typeof body.driver === 'string' ? body.driver : 'agent'
-      if (message === '' || message.length > 8000)
-        return c.json({ error: 'write a message of at most 8000 characters' }, 400)
-      const driver = registry.get(driverName)
-      if (driver?.kind !== 'chat')
-        return c.json(
-          {
-            error: `the driver "${driverName}" is not available here (${registry
-              .list()
-              .filter((d) => d.kind === 'chat')
-              .map((d) => d.name)
-              .join(', ')})`,
-          },
-          400,
-        )
-      if (current !== undefined && !current.ended)
-        return c.json({ error: 'a run is already going; wait for it to end' }, 409)
-      const run = startRun(driverName, message, driver)
+      const checked = checkAsk(body.message, body.driver)
+      if ('error' in checked) return c.json({ error: checked.error }, checked.status)
+      const run = startRun(checked.driverName, checked.message, checked.driver)
       return follow(c, run, false)
     })
     // Stop: the only thing that cancels a run. A page that goes away (a reload, a move to another page, a closed tab) does not: the agent goes on, and the page picks it up again.
@@ -151,6 +142,34 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
         return c.json({ error: "only the app's own page may read the run" }, 403)
       return current === undefined ? c.json({ run: null }) : follow(c, current, true)
     })
+  /** What `/ask` and the socket's `ask` both check: a message of a sensible size, a chat driver that is here, and no run going. */
+  const checkAsk = (
+    rawMessage: unknown,
+    rawDriver: unknown,
+  ):
+    | { message: string; driverName: string; driver: ChatDriver }
+    | { error: string; status: 400 | 409 } => {
+    const message = typeof rawMessage === 'string' ? rawMessage.trim() : ''
+    const driverName = typeof rawDriver === 'string' ? rawDriver : 'agent'
+    if (message === '' || message.length > 8000)
+      return { error: 'write a message of at most 8000 characters', status: 400 }
+    const driver = registry.get(driverName)
+    if (driver?.kind !== 'chat') {
+      const chat = registry
+        .list()
+        .filter((d) => d.kind === 'chat')
+        .map((d) => d.name)
+        .join(', ')
+      const why = whyNotChat(driverName, driver?.kind)
+      return {
+        error: `the driver "${driverName}" is not available here${why === undefined ? '' : `: ${why}`} (chat drivers: ${chat})`,
+        status: 400,
+      }
+    }
+    if (current !== undefined && !current.ended)
+      return { error: 'a run is already going; wait for it to end', status: 409 }
+    return { message, driverName, driver }
+  }
   /** One run of an agent: its events as they came, and who is following. It lives in the app, not in a page. */
   interface Run {
     readonly id: number
@@ -205,33 +224,35 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     })()
     return run
   }
-  /** Follow a run as server-sent events: a `run` event (what it is, whether it already ended), the events so far, then the new ones until it ends. Following does not keep it alive. */
-  const follow = (c: Parameters<typeof streamSSE>[0], run: Run, announce: boolean): Response =>
-    streamSSE(c, async (stream) => {
-      if (announce)
-        await stream.writeSSE({
-          event: 'run',
-          data: JSON.stringify({
-            id: run.id,
-            driver: run.driver,
-            message: run.message,
-            ended: run.ended,
-            endedAt: run.endedAt ?? null,
-          }),
-        })
-      const queue: Array<{ event: string; data: unknown }> = [...run.events]
-      let wake: (() => void) | undefined
-      const follower = (item: { event: string; data: unknown }): void => {
-        queue.push(item)
-        wake?.()
-      }
-      if (!run.ended) run.followers.add(follower)
-      let open = true
-      stream.onAbort(() => {
-        open = false
-        run.followers.delete(follower)
-        wake?.()
+  /**
+   * Follow a run into `write`: a `run` event (what it is, whether it already ended) when `announce`, the events so far, then the new ones until it ends. Following does not keep the
+   * run alive. `detach` stops following (the page went away); `done` settles when the run ended or the following was detached.
+   */
+  const pump = (
+    run: Run,
+    announce: boolean,
+    write: (event: string, data: unknown) => void | Promise<void>,
+  ): { done: Promise<void>; detach(): void } => {
+    const queue: Array<{ event: string; data: unknown }> = [...run.events]
+    if (announce)
+      queue.unshift({
+        event: 'run',
+        data: {
+          id: run.id,
+          driver: run.driver,
+          message: run.message,
+          ended: run.ended,
+          endedAt: run.endedAt ?? null,
+        },
       })
+    let wake: (() => void) | undefined
+    const follower = (item: { event: string; data: unknown }): void => {
+      queue.push(item)
+      wake?.()
+    }
+    if (!run.ended) run.followers.add(follower)
+    let open = true
+    const done = (async () => {
       try {
         while (open) {
           const item = queue.shift()
@@ -244,11 +265,130 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
             continue
           }
           if (item.event === 'end') break
-          await stream.writeSSE({ event: item.event, data: JSON.stringify(item.data) })
+          await write(item.event, item.data)
         }
       } finally {
         run.followers.delete(follower)
       }
+    })()
+    return {
+      done,
+      detach: () => {
+        open = false
+        run.followers.delete(follower)
+        wake?.()
+      },
+    }
+  }
+  /** Follow a run as server-sent events. */
+  const follow = (c: Parameters<typeof streamSSE>[0], run: Run, announce: boolean): Response =>
+    streamSSE(c, async (stream) => {
+      const following = pump(run, announce, (event, data) =>
+        stream.writeSSE({ event, data: JSON.stringify(data) }),
+      )
+      stream.onAbort(following.detach)
+      await following.done
     })
+  // The same runs over a WebSocket, which is not one of the browser's six connections per host: a page that streams its own state in two windows, with a run going, would otherwise
+  // queue the panel's Stop and the door's answers behind them. A WebSocket has no CORS and cannot set a header, so the Origin must be this app's own and the first frame carries the
+  // token. Frames: up `{ t: 'hello', token }`, then `{ t: 'ask', message, driver }`, `{ t: 'follow' }` or `{ t: 'stop' }`; down `{ e: <event>, d: <data> }`, as the stream's events.
+  // The server row comes after this plugin in a blend, so the WebSocket form is mounted when the server appears (and not at all without one that upgrades or without the `ws` package).
+  ctx.inject(['nodeServer'], (inner) => {
+    let upgrade: UpgradeWebSocket
+    try {
+      upgrade = (
+        inner as unknown as { nodeServer: { upgrades(): UpgradeWebSocket } }
+      ).nodeServer.upgrades()
+    } catch {
+      return
+    }
+    const ws = new Acryl()
+    const own: MiddlewareHandler = async (c, next) => {
+      const authority = loopbackAuthority(c)
+      const origin = c.req.header('origin')
+      const site = c.req.header('sec-fetch-site')
+      if (
+        authority === undefined ||
+        origin === undefined ||
+        origin !== authority.origin ||
+        (site !== undefined && site !== 'same-origin')
+      )
+        return c.json({ error: "only the app's own page may use the panel" }, 403)
+      await next()
+    }
+    const sameToken = (presented: unknown): boolean => {
+      if (typeof presented !== 'string') return false
+      const a = Buffer.from(presented)
+      const b = Buffer.from(token)
+      return a.length === b.length && timingSafeEqual(a, b)
+    }
+    ws.get(
+      `${PREFIX}/run/ws`,
+      own,
+      upgrade(
+        () => {
+          let authed = false
+          let following: { detach(): void } | undefined
+          let hello: NodeJS.Timeout | undefined
+          return {
+            onOpen(_event, ws) {
+              hello = setTimeout(() => ws.close(4401, 'no token'), 5000)
+            },
+            onMessage(event, ws) {
+              if (typeof event.data !== 'string') return
+              let message: { t?: unknown; token?: unknown; message?: unknown; driver?: unknown }
+              try {
+                message = JSON.parse(event.data) as typeof message
+              } catch {
+                return
+              }
+              if (!authed) {
+                if (message.t !== 'hello' || !sameToken(message.token)) {
+                  ws.close(4401, 'token')
+                  return
+                }
+                authed = true
+                if (hello !== undefined) clearTimeout(hello)
+                return
+              }
+              const send = (e: string, d: unknown): void => {
+                ws.send(JSON.stringify({ e, d }))
+              }
+              if (message.t === 'stop') {
+                current?.cancel.abort()
+                return
+              }
+              if (following !== undefined) return
+              const watch = (run: Run, announce: boolean): void => {
+                const pumped = pump(run, announce, send)
+                following = pumped
+                void pumped.done.then(() => ws.close(1000, 'run ended'))
+              }
+              if (message.t === 'ask') {
+                const checked = checkAsk(message.message, message.driver)
+                if ('error' in checked) {
+                  send('error', { message: checked.error })
+                  ws.close(1000, 'refused')
+                  return
+                }
+                watch(startRun(checked.driverName, checked.message, checked.driver), false)
+              } else if (message.t === 'follow') {
+                if (current === undefined) {
+                  send('idle', {})
+                  ws.close(1000, 'no run')
+                } else watch(current, true)
+              }
+            },
+            onClose() {
+              if (hello !== undefined) clearTimeout(hello)
+              following?.detach()
+            },
+          }
+        },
+        { textOnly: true },
+      ),
+    )
+    inner.router.route('/', ws)
+  })
   ctx.router.route('/', app)
 }

package/plugins/desktop/main.ts

@@ -9,7 +9,7 @@
 import { mkdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { app, BrowserWindow, Menu, type MenuItem, shell } from 'electron'
+import { app, BrowserWindow, Menu, MenuItem, screen, shell } from 'electron'
 import type { App } from '../../src/app.ts'
 import '../acryl-node-server/src/register.ts'
 import { selectInstance } from '../instance/index.ts'
@@ -20,9 +20,10 @@ import {
   startDoorShell,
   type WindowPort,
 } from './door-shell.ts'
+import { hasSettings, settingsPlacement } from './menu.ts'
 import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
-import { windowOptions } from './window.ts'
+import { cascade, windowOptions } from './window.ts'
 
 const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
 const chosen = selectInstance({ projectRoot, env: process.env })
@@ -91,7 +92,19 @@ if (!app.requestSingleInstanceLock()) {
     const origin = new URL(url).origin
     /** One window on a path of the app. Navigation stays on the app's own server; any other address opens in the system browser. The user agent names the window to the door (`AcrylWindow/<id>`), so an agent can drive it with `--window <id>`. */
     const createWindow = (path: string): BrowserWindow => {
-      const created = new BrowserWindow(windowOptions({ title: chosen.name }))
+      // A window opened while another is open sits a step down and to the right of it, not exactly on top.
+      const beside =
+        BrowserWindow.getFocusedWindow() ??
+        BrowserWindow.getAllWindows().find((other) => !other.isDestroyed())
+      const where = (() => {
+        if (beside === undefined) return {}
+        const bounds = beside.getBounds()
+        return cascade(bounds, screen.getDisplayMatching(bounds).workArea, {
+          width: 1100,
+          height: 760,
+        })
+      })()
+      const created = new BrowserWindow(windowOptions({ title: chosen.name, ...where }))
       created.webContents.setUserAgent(
         `${created.webContents.getUserAgent()} AcrylWindow/${String(created.id)}`,
       )
@@ -147,6 +160,40 @@ if (!app.requestSingleInstanceLock()) {
       open: (path) => port(createWindow(path ?? startPath())),
       menu: () => (Menu.getApplicationMenu()?.items ?? []).map(menuItem),
     }
+    // An app that serves a /settings page gets a Settings item in the menu (Electron's own menu otherwise): it opens that page, in the window that already shows it when there is one.
+    const settingsServed = await fetch(new URL('/settings', url), {
+      headers: { accept: 'text/html' },
+      signal: AbortSignal.timeout(2000),
+    }).then(
+      (answer) => answer.ok,
+      () => false,
+    )
+    const menu = Menu.getApplicationMenu()
+    const placement =
+      menu === null || !settingsServed || hasSettings(menu.items)
+        ? undefined
+        : settingsPlacement(menu.items, process.platform)
+    if (menu !== null && placement !== undefined) {
+      const target = menu.items[placement.menu]?.submenu
+      const openSettings = (): void => {
+        const shown = live().find(
+          (candidate) =>
+            new URL(candidate.webContents.getURL() || 'about:blank', url).pathname === '/settings',
+        )
+        if (shown === undefined) createWindow('/settings')
+        else {
+          if (shown.isMinimized()) shown.restore()
+          shown.focus()
+        }
+      }
+      target?.insert(
+        placement.at,
+        new MenuItem({ label: 'Settings...', accelerator: 'CmdOrCtrl+,', click: openSettings }),
+      )
+      if (placement.separatorAfter)
+        target?.insert(placement.at + 1, new MenuItem({ type: 'separator' }))
+      Menu.setApplicationMenu(menu)
+    }
     stopDoorShell = startDoorShell(projectRoot, { desktop, log: console.log })
   })
 }

package/plugins/desktop/menu.ts

@@ -0,0 +1,60 @@
+/**
+ * The desktop app's Settings menu item. An app that serves a `/settings` page gets a "Settings..." item that opens it in a window (Cmd+, on macOS, Ctrl+, elsewhere); an app without
+ * the page gets nothing. Where the item goes is decided here, from the labels of the application menu Electron built, so it is tested without Electron.
+ */
+
+/** The part of an Electron menu item this file reads. */
+export interface MenuNode {
+  readonly label: string
+  readonly role?: string | undefined
+  readonly type?: string | undefined
+  readonly submenu?: { readonly items: readonly MenuNode[] } | null | undefined
+}
+
+export interface Placement {
+  /** Index of the top-level menu that gets the item. */
+  readonly menu: number
+  /** Index inside that menu to insert at. */
+  readonly at: number
+  /** Whether a separator goes after the item (so it sits in a group of its own). */
+  readonly separatorAfter: boolean
+}
+
+/**
+ * macOS puts Settings in the application menu, under About; elsewhere it is the first item of the File menu. Returns nothing when the menu has neither place (an app that
+ * replaced Electron's menu with its own keeps its own).
+ */
+export function settingsPlacement(
+  items: readonly MenuNode[],
+  platform: NodeJS.Platform,
+): Placement | undefined {
+  if (platform === 'darwin') {
+    const submenu = items[0]?.submenu?.items
+    if (submenu === undefined || submenu === null) return undefined
+    const about = submenu.findIndex(
+      (item) => item.role === 'about' || /^about\b/iu.test(item.label),
+    )
+    // Under About and the separator after it; first when there is no About.
+    const separator =
+      about === -1
+        ? -1
+        : submenu.findIndex((item, index) => index > about && item.type === 'separator')
+    return {
+      menu: 0,
+      at: separator === -1 ? (about === -1 ? 0 : about + 1) : separator + 1,
+      separatorAfter: true,
+    }
+  }
+  const file = items.findIndex((item) => /^&?file$/iu.test(item.label) || item.role === 'fileMenu')
+  if (file === -1 || items[file]?.submenu == null) return undefined
+  return { menu: file, at: 0, separatorAfter: true }
+}
+
+/** Whether a menu already has a Settings item (so a restart that builds the menu twice adds it once). */
+export function hasSettings(items: readonly MenuNode[]): boolean {
+  return items.some(
+    (item) =>
+      /^settings\b|^preferences\b/iu.test(item.label) ||
+      (item.submenu?.items !== undefined && hasSettings(item.submenu.items)),
+  )
+}