acrylblends 1.0.10 → 1.2.0

package/plugins/agent-panel/visitors.ts

@@ -0,0 +1,231 @@
+/**
+ * Who uses the panel, and what each one may do.
+ *
+ * - In development one person does, the app's owner: every page of the app shares one token and one run, so a run asked in the frame is followed from any tab of the app.
+ * - As the Assistant every visitor of the app is their own: a visitor is known by an HttpOnly cookie that the panel's session sets, and has their own token, their own run and
+ *   their own limits. A visitor never sees, follows or stops another visitor's run, and never waits for one.
+ *
+ * The Assistant spends the owner's model key for anyone who opens the app, so its asks are bounded: per visitor per hour, for all visitors per day, runs at once, and the length of
+ * a question. The agent's own step budget bounds each run.
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto'
+
+/** The cookie that names a visitor of the Assistant. HttpOnly: the page's scripts never read it. */
+export const VISITOR_COOKIE = 'acryl-visitor'
+
+/** The Assistant's limits; each one has a default. */
+export interface AssistantLimits {
+  /** Questions one visitor may ask in an hour. */
+  readonly perVisitorPerHour?: number
+  /** Questions all visitors together may ask in a day: every one of them spends the owner's model key. */
+  readonly perDay?: number
+  /** Runs going at once, across visitors. */
+  readonly concurrent?: number
+  /** Characters in one question. */
+  readonly messageLength?: number
+}
+
+export const DEFAULT_LIMITS: Required<AssistantLimits> = {
+  perVisitorPerHour: 20,
+  perDay: 300,
+  concurrent: 4,
+  messageLength: 1000,
+}
+
+/** The question length the development panel accepts (one person, who owns the key). */
+const OWNER_MESSAGE_LENGTH = 8000
+const HOUR_MS = 60 * 60 * 1000
+const DAY_MS = 24 * HOUR_MS
+/** Visitors kept at most; the one seen longest ago without a run going is let go first. */
+const DEFAULT_CAPACITY = 5000
+
+/** What a visitor's run must say about itself. */
+export interface RunState {
+  readonly ended: boolean
+}
+
+export interface Visitor<R extends RunState> {
+  readonly id: string
+  readonly token: string
+  /** The visitor in the audit: a short hash, never the cookie itself. */
+  readonly tag: string
+  /** The visitor's latest run, going or ended (what a page that loads shows again). */
+  current: R | undefined
+  /** When this visitor's asks of the last hour started. */
+  readonly asks: number[]
+  lastSeen: number
+}
+
+/** Why an ask is refused, with the HTTP status to answer. */
+export interface Refusal {
+  readonly error: string
+  readonly status: 400 | 409 | 429 | 503
+}
+
+export interface VisitorsOptions {
+  /** One visitor for every page (development); otherwise one per cookie (the Assistant). */
+  readonly shared: boolean
+  readonly limits?: AssistantLimits
+  readonly now?: () => number
+  readonly capacity?: number
+}
+
+const newSecret = (): string => randomBytes(24).toString('base64url')
+
+/** The value of one cookie in a `Cookie` header. */
+export function cookieValue(header: string | undefined | null, name: string): string | undefined {
+  if (header === undefined || header === null) return undefined
+  for (const part of header.split(';')) {
+    const at = part.indexOf('=')
+    if (at === -1) continue
+    if (part.slice(0, at).trim() === name) return part.slice(at + 1).trim()
+  }
+  return undefined
+}
+
+/** Whether two secrets are the same, in constant time. */
+export function sameSecret(presented: unknown, expected: string): boolean {
+  if (typeof presented !== 'string') return false
+  const a = Buffer.from(presented)
+  const b = Buffer.from(expected)
+  return a.length === b.length && timingSafeEqual(a, b)
+}
+
+const minutes = (ms: number): string => {
+  const count = Math.max(1, Math.ceil(ms / 60_000))
+  return `${String(count)} minute${count === 1 ? '' : 's'}`
+}
+
+export class Visitors<R extends RunState> {
+  private readonly shared: boolean
+  private readonly limits: Required<AssistantLimits>
+  private readonly now: () => number
+  private readonly capacity: number
+  private readonly byId = new Map<string, Visitor<R>>()
+  /** When every ask of the last day started, across visitors. */
+  private readonly day: number[] = []
+  private readonly owner: Visitor<R> | undefined
+
+  constructor(options: VisitorsOptions) {
+    this.shared = options.shared
+    this.limits = { ...DEFAULT_LIMITS, ...options.limits }
+    this.now = options.now ?? Date.now
+    this.capacity = options.capacity ?? DEFAULT_CAPACITY
+    this.owner = this.shared ? this.make() : undefined
+  }
+
+  /** The visitor a request belongs to: the owner in development, else the one its cookie names; `undefined` when it names none this app knows. */
+  of(cookieHeader: string | undefined | null): Visitor<R> | undefined {
+    if (this.owner !== undefined) return this.owner
+    const id = cookieValue(cookieHeader, VISITOR_COOKIE)
+    const visitor = id === undefined ? undefined : this.byId.get(id)
+    if (visitor !== undefined) visitor.lastSeen = this.now()
+    return visitor
+  }
+
+  /**
+   * The visitor of a session request, made when the request names none. `setCookie` is the header to answer with, only for a new visitor: HttpOnly, SameSite=Strict, the whole
+   * app (`Path=/`), a day long, and Secure when the page came over https.
+   */
+  session(
+    cookieHeader: string | undefined | null,
+    secure: boolean,
+  ): { visitor: Visitor<R>; setCookie?: string } {
+    const known = this.of(cookieHeader)
+    if (known !== undefined) return { visitor: known }
+    const visitor = this.make()
+    this.keep(visitor)
+    const setCookie = `${VISITOR_COOKIE}=${visitor.id}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${String(DAY_MS / 1000)}${secure ? '; Secure' : ''}`
+    return { visitor, setCookie }
+  }
+
+  /** Whether `presented` is this visitor's token. */
+  accepts(visitor: Visitor<R> | undefined, presented: unknown): visitor is Visitor<R> {
+    return visitor !== undefined && sameSecret(presented, visitor.token)
+  }
+
+  /** Whether any visitor holds this token (a terminal driver checks a request with no other context). */
+  knows(cookieHeader: string | undefined | null, presented: unknown): boolean {
+    return this.accepts(this.of(cookieHeader), presented)
+  }
+
+  /** The question's length check, which comes before anything is counted. */
+  checkMessage(message: string): Refusal | undefined {
+    const most = this.shared ? OWNER_MESSAGE_LENGTH : this.limits.messageLength
+    if (message === '' || message.length > most)
+      return { error: `write a message of at most ${String(most)} characters`, status: 400 }
+    return undefined
+  }
+
+  /**
+   * Whether this visitor may start a run now. The visitor's own run going is refused first (409); then, for the Assistant, the visitor's hour, the runs going at once and the
+   * day. An admitted ask is counted.
+   */
+  admit(visitor: Visitor<R>): Refusal | undefined {
+    if (visitor.current !== undefined && !visitor.current.ended)
+      return { error: 'a run is already going; wait for it to end', status: 409 }
+    if (this.shared) return undefined
+    const now = this.now()
+    prune(visitor.asks, now - HOUR_MS)
+    prune(this.day, now - DAY_MS)
+    const hour = visitor.asks[0]
+    if (visitor.asks.length >= this.limits.perVisitorPerHour && hour !== undefined)
+      return {
+        error: `You have asked ${String(this.limits.perVisitorPerHour)} questions this hour. Ask again in ${minutes(hour + HOUR_MS - now)}.`,
+        status: 429,
+      }
+    let going = 0
+    for (const other of this.byId.values())
+      if (other.current !== undefined && !other.current.ended) going += 1
+    if (going >= this.limits.concurrent)
+      return {
+        error: 'The assistant is helping other people right now. Ask again in a moment.',
+        status: 503,
+      }
+    const first = this.day[0]
+    if (this.day.length >= this.limits.perDay && first !== undefined)
+      return {
+        error: `The assistant has answered all the questions it can today. It is back in ${minutes(first + DAY_MS - now)}.`,
+        status: 429,
+      }
+    visitor.asks.push(now)
+    this.day.push(now)
+    return undefined
+  }
+
+  /** How many visitors are kept (for tests and diagnostics). */
+  get size(): number {
+    return this.owner === undefined ? this.byId.size : 1
+  }
+
+  private make(): Visitor<R> {
+    const id = newSecret()
+    return {
+      id,
+      token: newSecret(),
+      tag: createHash('sha256').update(id).digest('hex').slice(0, 12),
+      current: undefined,
+      asks: [],
+      lastSeen: this.now(),
+    }
+  }
+
+  /** Keep a new visitor; past the capacity, let go of the visitors seen longest ago that have no run going. */
+  private keep(visitor: Visitor<R>): void {
+    if (this.byId.size >= this.capacity) {
+      const idle = [...this.byId.values()]
+        .filter((other) => other.current === undefined || other.current.ended)
+        .sort((a, b) => a.lastSeen - b.lastSeen)
+      for (const other of idle.slice(0, this.byId.size - this.capacity + 1))
+        this.byId.delete(other.id)
+    }
+    this.byId.set(visitor.id, visitor)
+  }
+}
+
+/** Drop the times up to `since` from the front of an ascending list: an ask exactly an hour (or a day) old is out of the window. */
+function prune(times: number[], since: number): void {
+  let drop = 0
+  while (drop < times.length && (times[drop] ?? 0) <= since) drop += 1
+  if (drop > 0) times.splice(0, drop)
+}

package/plugins/desktop/frame.ts

@@ -0,0 +1,231 @@
+/**
+ * The desktop window on the ACRYL frame (docs/plans/ide-host-inversion.md, section 27). An app with `scripts/ide-host.mjs` runs inside the frame on `npm run dev`;
+ * `npm run desktop` shows that same frame: it attaches to a host that already runs (the host's address record, `.acrylblends/frame-url.json`), or starts the host
+ * the way `npm run dev` does and loads the address it prints. Nothing here imports electron: `main.ts` decides with these functions and owns the window.
+ */
+import { type ChildProcess, spawn, spawnSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { connect } from 'node:net'
+import { join, resolve } from 'node:path'
+
+/** The launcher every frame app has; without it the app runs on its own server (made before the frame). */
+export const HOST_SCRIPT = join('scripts', 'ide-host.mjs')
+
+/** The line the host prints once it serves the frame, with the launch token in the address. */
+const HOST_LINE = /acrylblends host: (http:\/\/\S+)/u
+
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]'])
+
+/** How long a stopping host gets before its tree is killed. */
+export const HOST_STOP_GRACE_MS = 5_000
+
+export function isFrameApp(root: string, exists: (path: string) => boolean = existsSync): boolean {
+  return exists(join(root, HOST_SCRIPT))
+}
+
+/** The app home the host uses: `ACRYLBLENDS_HOME` when set, else `<app>/.acrylblends` (the launcher's own rule). */
+export function frameHome(root: string, env: Record<string, string | undefined>): string {
+  const pinned = env.ACRYLBLENDS_HOME?.trim()
+  return pinned === undefined || pinned === ''
+    ? join(resolve(root), '.acrylblends')
+    : resolve(pinned)
+}
+
+/** The frame address in the host's output so far, or `undefined` while it has not printed it. */
+export function hostAddress(output: string): string | undefined {
+  return HOST_LINE.exec(output)?.[1]
+}
+
+/** A loopback `http:` address, or `undefined` for anything else: the window only ever opens a frame on this machine. */
+export function loopbackAddress(url: unknown): URL | undefined {
+  if (typeof url !== 'string') return undefined
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === 'http:' && LOOPBACK.has(parsed.hostname) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export interface RecordDeps {
+  readonly read?: (file: string) => string
+  /** Whether something accepts a connection at the address. */
+  readonly listening?: (url: URL) => Promise<boolean>
+}
+
+const tcpListening = (url: URL, timeoutMs = 500): Promise<boolean> =>
+  new Promise((done) => {
+    const socket = connect({
+      host: url.hostname.replace(/^\[|\]$/gu, ''),
+      port: Number(url.port || 80),
+    })
+    const finish = (listening: boolean) => {
+      socket.destroy()
+      done(listening)
+    }
+    socket.setTimeout(timeoutMs)
+    socket.once('connect', () => finish(true))
+    socket.once('timeout', () => finish(false))
+    socket.once('error', () => finish(false))
+  })
+
+/**
+ * The frame that already runs for this app: the host's address record, when it names a loopback address and something listens there. A record a stopped host
+ * left behind is not a running frame.
+ */
+export async function runningFrame(
+  home: string,
+  deps: RecordDeps = {},
+): Promise<string | undefined> {
+  const read = deps.read ?? ((file: string) => readFileSync(file, 'utf8'))
+  let record: { url?: unknown }
+  try {
+    record = JSON.parse(read(join(home, 'frame-url.json'))) as { url?: unknown }
+  } catch {
+    return undefined
+  }
+  const url = loopbackAddress(record.url)
+  if (url === undefined) return undefined
+  return (await (deps.listening ?? tcpListening)(url)) ? url.href : undefined
+}
+
+/** An address as the door may show it: the frame's launch token removed (the token is the way into the frame, so it never goes to a log). */
+export function withoutToken(href: string): string {
+  try {
+    const parsed = new URL(href)
+    if (!parsed.searchParams.has('token')) return href
+    parsed.searchParams.delete('token')
+    return parsed.href
+  } catch {
+    return href
+  }
+}
+
+/**
+ * What the Settings... menu item runs in a frame window: the window event the page's root owner opens its own Settings on (`acryl-blends-frame`'s
+ * `OPEN_SETTINGS_EVENT`, and the IDE's `acryl-workspace`; keep the string in step). The same dialog as the top bar's gear, never a second one.
+ */
+export const openFrameSettings = "window.dispatchEvent(new Event('acryl:open-settings'))"
+
+/** What the window does with a navigation: stay on the frame's origin, hand the address to the system browser, or refuse it. */
+export type Navigation = 'stay' | 'external' | 'block'
+
+/**
+ * ACRYL Desktop's rule (`electron-shell-generation.ts`): only the main frame is checked, so the frame's tiles (the app's page in an iframe) navigate freely;
+ * the frame's own origin stays in the window, an `http(s)` or `mailto` address goes to the system browser, anything else is refused.
+ */
+export function navigation(target: string, origin: string, mainFrame = true): Navigation {
+  if (!mainFrame) return 'stay'
+  let parsed: URL
+  try {
+    parsed = new URL(target)
+  } catch {
+    return 'block'
+  }
+  if (parsed.origin === origin) return 'stay'
+  return parsed.protocol === 'http:' ||
+    parsed.protocol === 'https:' ||
+    parsed.protocol === 'mailto:'
+    ? 'external'
+    : 'block'
+}
+
+/** How the host is started: the npm and Node that ran `npm run desktop`, never Electron's Node (node-pty and DSH's rows are built for Node's ABI). */
+export function hostCommand(
+  env: Record<string, string | undefined>,
+  platform: NodeJS.Platform,
+): { file: string; args: string[]; shell: boolean } {
+  const node = env.npm_node_execpath
+  const npm = env.npm_execpath
+  if (node !== undefined && node !== '' && npm !== undefined && npm !== '')
+    return /\.c?js$/u.test(npm)
+      ? { file: node, args: [npm, 'run', 'dev'], shell: false }
+      : { file: npm, args: ['run', 'dev'], shell: platform === 'win32' }
+  // Started without npm (Electron run by hand): npm from the PATH, `npm.cmd` through the shell on Windows (scripts/lib/platform.mjs, npmSpawn).
+  return platform === 'win32'
+    ? { file: 'npm.cmd', args: ['run', 'dev'], shell: true }
+    : { file: 'npm', args: ['run', 'dev'], shell: false }
+}
+
+export interface FrameHost {
+  /** The frame address the host printed, or a rejection with the host's output when it ended first. */
+  readonly ready: Promise<string>
+  /** Stop the host and what it started; resolves once it has exited. */
+  stop(): Promise<void>
+}
+
+/** Start the app's frame host as `npm run dev` does, in the app folder; its output is passed through to `write`. */
+export function startFrameHost(
+  root: string,
+  env: NodeJS.ProcessEnv,
+  write: (text: string) => void,
+  platform: NodeJS.Platform = process.platform,
+): FrameHost {
+  const command = hostCommand(env, platform)
+  // The host leads its own process group on macOS and Linux, so a stop reaches npm, the host and every terminal it runs; Windows stops the tree with taskkill.
+  const child: ChildProcess = spawn(command.file, command.args, {
+    cwd: root,
+    env: { ...env, ELECTRON_RUN_AS_NODE: undefined },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: command.shell,
+    detached: platform !== 'win32',
+    windowsHide: true,
+  })
+  let output = ''
+  let exited = false
+  const exit = new Promise<void>((done) => {
+    child.once('exit', () => {
+      exited = true
+      done()
+    })
+    child.once('error', () => {
+      exited = true
+      done()
+    })
+  })
+  const ready = new Promise<string>((done, fail) => {
+    const take = (chunk: Buffer) => {
+      const text = chunk.toString()
+      write(text)
+      if (output.length < 200_000) output += text
+      const address = hostAddress(output)
+      if (address !== undefined) done(address)
+    }
+    child.stdout?.on('data', take)
+    child.stderr?.on('data', take)
+    void exit.then(() =>
+      fail(new Error(`the frame host ended before it served the frame:\n${output.slice(-3000)}`)),
+    )
+  })
+  const signal = (name: NodeJS.Signals) => {
+    if (child.pid === undefined) return
+    // Windows has no process groups and no SIGTERM a console process can answer: the whole tree (npm, the host, its terminals) is ended at once.
+    if (platform === 'win32') {
+      spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      })
+      return
+    }
+    try {
+      process.kill(-child.pid, name)
+    } catch {
+      // The group is already gone.
+    }
+  }
+  return {
+    ready,
+    async stop() {
+      if (exited) return
+      signal('SIGTERM')
+      const graceful = await Promise.race([
+        exit.then(() => true),
+        new Promise<boolean>((done) => setTimeout(() => done(false), HOST_STOP_GRACE_MS).unref()),
+      ])
+      if (!graceful) {
+        signal('SIGKILL')
+        await exit
+      }
+    },
+  }
+}

package/plugins/desktop/launch.ts

@@ -3,7 +3,7 @@
  * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
  * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
  */
-import { spawn } from 'node:child_process'
+import { type ChildProcess, spawn } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { join } from 'node:path'
@@ -29,9 +29,45 @@ export const SANDBOX_NOTICE =
   "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
   'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
 
-/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
-export function electronArgs(entry: string, blocked: boolean): string[] {
-  return blocked ? ['--no-sandbox', entry] : [entry]
+/**
+ * The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. Chromium switches given to the script
+ * (`npm run desktop -- --remote-debugging-port=9222`) go before the entry; anything that is not a switch is dropped.
+ */
+export function electronArgs(
+  entry: string,
+  blocked: boolean,
+  extra: readonly string[] = [],
+): string[] {
+  const switches = extra.filter((arg) => /^--[a-z][a-z0-9-]*(=.*)?$/u.test(arg))
+  return [...(blocked ? ['--no-sandbox'] : []), ...switches, entry]
+}
+
+/** The signals the launcher hands to Electron: Ctrl-C, a stop, and the terminal closing. */
+export const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+
+/**
+ * Start Electron and make it end the way it was asked to. On macOS and Linux Electron leads its own process group, so a terminal's Ctrl-C (which goes to the
+ * whole foreground group) reaches only this launcher, which hands Electron exactly one signal. Electron answers a first SIGINT, SIGTERM or SIGHUP with a
+ * graceful quit, the one that stops the frame host the window started; a second signal kills it at once, before any of that runs, and a Ctrl-C that reached
+ * both processes was two, as is one that npm passes on after the terminal sent it. Later signals are not passed on. Windows has no process groups and no such signals; there Electron starts as before. This process ends with Electron's exit code.
+ */
+export function runElectron(
+  file: string,
+  args: readonly string[],
+  platform: NodeJS.Platform = process.platform,
+): ChildProcess {
+  const child = spawn(file, args, { stdio: 'inherit', detached: platform !== 'win32' })
+  // One signal, ever: npm hands a Ctrl-C to this process a second time, and Electron's quit is bounded (DESKTOP_SHUTDOWN_TIMEOUT_MS) without another.
+  let forwarded = false
+  for (const signal of FORWARDED_SIGNALS)
+    if (platform !== 'win32' || signal !== 'SIGHUP')
+      process.on(signal, () => {
+        if (forwarded) return
+        forwarded = true
+        child.kill(signal)
+      })
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  return child
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -40,9 +76,8 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const blocked =
     process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
   if (blocked) console.warn(SANDBOX_NOTICE)
-  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
-    stdio: 'inherit',
-  })
-  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
-  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  runElectron(
+    electron,
+    electronArgs(join(import.meta.dirname, 'main.ts'), blocked, process.argv.slice(2)),
+  )
 }