@oddessentials/agent-guild 0.25.0 → 0.26.0

package/README.md

@@ -60,6 +60,14 @@ and come back to the same screens. Drag a session card by its grip, with a
 mouse or a finger, to put the cards in the order you want; this browser
 remembers it, and new sessions join at the end.
 
+**Two terminals at once.** **Split** in the terminal's header, or Ctrl+click
+(⌘-click on a Mac) on a card's **Open**, shows a second session beside the
+first, or above it on a tall, narrow window. Click a terminal to work in it;
+drag the divider, or focus it and use the arrow keys, to resize them. The
+session name in the header switches the focused terminal to another session.
+On a phone one terminal shows at a time, with a button to switch to the
+other. This browser reopens the terminals you had open after a reload.
+
 On a touchscreen, **Copy…** opens a still copy of the terminal text. Touch and
 hold to select, then use **Copy selection** or the browser's Copy menu. **Done**
 returns to the live terminal; the session keeps running while you copy. The
@@ -145,12 +153,27 @@ vX.Y.Z** switches over when you are ready. The version badge opens
 <img src="docs/images/whats-new.webp" alt="The What's new panel listing the release notes of each version">
 
 **Keep notes at hand.** **Notes** in the top bar opens a notepad for prompts,
-commands and to-dos, even while a terminal is open. It saves up to 100,000
-characters as you type and keeps them in this browser, never on the manager;
-every tab of the page shows the same notes.
-
-**Appearance.** The Appearance menu in the top bar picks a skin and light or
-dark mode, without a reload. **Guild** is the default fantasy look;
+commands and to-dos in the side panel, next to your terminals. It saves up to
+100,000 characters as you type and keeps them in this browser, never on the
+manager; every tab of the page shows the same notes.
+
+**GitHub beside your work.** **GitHub** in the top bar opens the side panel.
+Sign in to one or more GitHub accounts, then search the repositories of all
+of them from the box at its top; it starts on the repository the focused
+terminal's folder is a clone of. **Issues** lists, opens, edits and closes
+issues. **Actions** shows the latest workflow runs and whether one is still
+going, refreshing while it is on screen. **Pull requests** lists the open
+ones. **Repositories** lists and creates repositories and clones them over SSH
+with a key Agent Guild keeps for each account. On a wide window the side panel
+makes room for itself; on a smaller one it lies over the cards, and over the
+terminals when they would get too narrow. Drag its edge to resize it. Escape
+or **Close** puts it away.
+
+<img src="docs/images/workspace.webp" alt="Two terminals side by side with the GitHub panel showing the workflow runs of the focused terminal's repository">
+
+**Settings.** The Settings menu in the top bar picks a skin and light or
+dark mode, without a reload. On a narrow window the top bar's buttons gather
+under its menu button. **Guild** is the default fantasy look;
 **Professional** is a plain business look with no characters; **Orbital**
 puts a crew of little robots in deep space; **Grove** is a calm moss garden
 of gentle nature spirits; **Gnomeland** is a lantern-lit village of gnome
@@ -164,6 +187,12 @@ new version is discovered after the initial version check. Session activity
 and assistant responses have no sounds:
 the providers do not yet offer consistently reliable completion signals.
 
+The browser tab icon adds a rotating green ring whenever any session card says
+**Working**, including Shell and task cards. It mirrors the cards' terminal
+activity, not assistant completion. The ring remains visible with reduced
+motion or when the browser pauses animation. During a connection interruption,
+it reflects the last card state until the page reconnects.
+
 Sounds play in one eligible tab per browser and origin after browser playback
 permission (usually a click or keypress). They require Web Locks and writable
 local storage. Opening or reconnecting a page does not replay old alerts,
@@ -186,8 +215,8 @@ There is no added polling while connected and no additional monitoring process.
 | `agent-guild url` | Print the page URL with its access token. |
 | `agent-guild start` | Run the manager in the foreground, for debugging. |
 
-The page's **Restart manager** and **Stop manager** buttons do the same as
-`restart` and `stop`, but ask first while sessions are running. The page also
+**Restart manager** and **Stop manager** in the page's **Manager** menu do the
+same as `restart` and `stop`, but ask first while sessions are running. The page also
 asks before you close it with sessions running. Sessions end when the manager
 stops or the computer restarts.
 
@@ -227,7 +256,9 @@ Any other tool or script can report agents and its model too. See
 
 ## Security and privacy
 
-* The manager listens on `127.0.0.1` only.
+* The manager listens on `127.0.0.1` only. To use its UI through a reverse
+  proxy such as Tailscale Serve, configure explicit
+  [allowed hosts and origins](docs/configuration.md#reverse-proxies).
 * Every API call needs a random per-user token, stored in the data folder
   with owner-only permissions. Anyone who can run programs as your user can
   read it, as with any local developer tool.
@@ -255,7 +286,7 @@ or prompts:
 | GitHub's releases API | What's new | Hourly |
 | herdr.dev and formulae.brew.sh | Multiplexer version checks | At most hourly, or on Refresh or a requested operation; disabled by `AGENT_GUILD_NO_UPDATE_CHECK=1` |
 | herdr.dev, GitHub release downloads, and the selected package manager's repositories | Multiplexer installation and updates | When you request the operation |
-| GitHub (sign-in, API, avatars and SSH) | Signing in to GitHub, listing your repositories, adding your SSH key and cloning | When you use **Clone from GitHub…** |
+| GitHub (sign-in, API, avatars and SSH) | Signing in to GitHub, listing your repositories, issues, workflow runs and pull requests, editing issues, adding your SSH key and cloning | When you use the GitHub panel; while its Actions tab shows, every few seconds during a run and every 30 seconds otherwise |
 
 ## Other front ends
 
@@ -278,6 +309,9 @@ npm test
   coding tool in `tests/fixtures`. CI runs them on Windows, macOS and Linux
   with Node.js 22, 24 and 26, and installs the packed package on x64 and
   arm64.
+* `node tests/browser/proxy.mjs` checks the real UI and terminal through a
+  local HTTPS proxy with an isolated manager and test certificates. Set
+  `CHROME_PATH` to Chrome or Edge if it is not in a standard location.
 * In a checkout, `launchers/AgentGuild.cmd` (Windows) and
   `launchers/AgentGuild.command` (macOS) start Agent Guild with a
   double-click.

package/bin/agent-guild.mjs

@@ -34,6 +34,8 @@ Commands:
 Environment:
   AGENT_GUILD_PORT             Port for the local API (default 47821)
   AGENT_GUILD_HOME             Data directory (default: per-user app data folder)
+  AGENT_GUILD_ALLOWED_HOSTS    Extra accepted Host values (comma-separated)
+  AGENT_GUILD_ALLOWED_ORIGINS  Extra accepted browser origins (comma-separated)
   AGENT_GUILD_NPM_REGISTRY     npm registry for version checks and installs
   AGENT_GUILD_NO_UPDATE_CHECK  Set to 1 to skip version checks`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddessentials/agent-guild",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Launch and watch AI coding-assistant terminal sessions from one local web page. A bundled session manager owns the terminals so the page can close and reconnect.",
   "license": "MIT",
   "repository": {
@@ -33,7 +33,7 @@
     "status": "node bin/agent-guild.mjs status",
     "demo:build": "node docs/demo/build.mjs",
     "demo:check": "node docs/demo/check.mjs",
-    "test": "node --test --test-concurrency=1"
+    "test": "node --test --test-concurrency=1 \"tests/*.test.mjs\""
   },
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",

package/src/manager/folder-opener.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const failure = (status, code, message) => Object.assign(new Error(message), { status, code });
+const isFile = (file) => { try { return fs.statSync(file).isFile(); } catch { return false; } };
+
+export function folderOpenTarget({ platform = process.platform, env = process.env, release = os.release(), fileExists = isFile } = {}) {
+  const onPath = (name) => (env.PATH || '').split(':').filter((dir) => path.posix.isAbsolute(dir))
+    .map((dir) => path.posix.join(dir, name)).find(fileExists);
+  let command, kind, label, reason;
+  if (platform === 'win32') {
+    kind = 'explorer';
+    label = 'File Explorer';
+    command = path.win32.join(env.SystemRoot || env.WINDIR || 'C:\\Windows', 'explorer.exe');
+  } else if (platform === 'darwin') {
+    kind = 'finder';
+    label = 'Finder';
+    command = '/usr/bin/open';
+  } else if (platform === 'linux' && (env.WSL_DISTRO_NAME || /microsoft|wsl/i.test(release))) {
+    kind = 'explorer';
+    label = 'File Explorer';
+    command = onPath('explorer.exe');
+    reason = 'Windows Explorer is unavailable. Enable Windows interoperability in WSL to open folders.';
+  } else if (platform === 'linux') {
+    kind = 'desktop';
+    label = 'file manager';
+    if (env.DISPLAY || env.WAYLAND_DISPLAY) {
+      command = onPath('xdg-open');
+      reason = 'Install xdg-utils and configure a default file manager to open folders.';
+    } else reason = 'Opening folders requires a desktop session on the computer running Agent Guild.';
+  } else reason = 'Opening folders is unavailable on this operating system.';
+  const available = Boolean(command && fileExists(command));
+  return { command, kind, label: label || 'file manager', available, reason: available ? null : reason || `${label} is unavailable on the computer running Agent Guild.` };
+}
+
+export function createFolderOpener({ resolveCwd, spawnImpl = spawn, cooldownMs = 1000, handoffMs = 1500, ...targetOptions }) {
+  let pending = false, nextOpen = 0;
+  return {
+    describe() {
+      const { available, label, reason } = folderOpenTarget(targetOptions);
+      return { available, label, reason };
+    },
+    async open(cwd) {
+      if (cwd !== undefined && (typeof cwd !== 'string' || /[\0\r\n]/.test(cwd))) {
+        throw failure(400, 'bad_cwd', 'The working folder must be a directory path.');
+      }
+      if (typeof cwd === 'string' && /^[a-z][a-z\d+.-]*:\/\//i.test(cwd.trim()) && !/^[a-z]:[/\\]/i.test(cwd.trim())) {
+        throw failure(400, 'bad_cwd', 'Enter a folder path, not a URL.');
+      }
+      if (pending || Date.now() < nextOpen) throw failure(429, 'folder_open_busy', 'Please wait before opening another folder.');
+      const target = folderOpenTarget(targetOptions);
+      if (!target.available) throw failure(409, 'folder_open_unavailable', target.reason);
+      pending = true;
+      try {
+        const resolved = resolveCwd(cwd);
+        let dir;
+        try {
+          dir = await fs.promises.realpath(resolved);
+          if (!(await fs.promises.stat(dir)).isDirectory()) throw new Error();
+        } catch {
+          throw failure(400, 'bad_cwd', 'The working folder does not exist or cannot be accessed.');
+        }
+        let args;
+        if (target.kind === 'explorer') args = ['.'];
+        else if (target.kind === 'finder') {
+          // Reveal packages instead of asking Finder to open (and potentially execute) them.
+          args = /\.(app|bundle|framework|plugin|kext|prefpane|workflow)$/i.test(dir)
+            ? ['-R', dir] : ['-a', '/System/Library/CoreServices/Finder.app', dir];
+        } else args = [dir];
+        nextOpen = Date.now() + cooldownMs;
+        await new Promise((resolve, reject) => {
+          let child, timer, settled = false;
+          const finish = (error) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            child?.unref();
+            if (error) reject(failure(409, 'folder_open_failed', `Could not open ${target.label}. Check that a desktop session and file manager are available on the computer running Agent Guild.`));
+            else resolve();
+          };
+          try {
+            child = spawnImpl(target.command, args, {
+              cwd: target.kind === 'explorer' ? dir : undefined,
+              shell: false, windowsHide: true, detached: true, stdio: 'ignore',
+            });
+            child.once('error', finish);
+            child.once('spawn', () => { timer = setTimeout(() => finish(), handoffMs); });
+            child.once('exit', (code) => finish(code !== 0 && !(target.kind === 'explorer' && code === 1)));
+          } catch (error) { finish(error); }
+        });
+      } finally { pending = false; }
+    },
+  };
+}

package/src/manager/folder-picker.mjs

@@ -0,0 +1,116 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const TITLE = 'Choose a working folder';
+const failure = (status, code, message) => Object.assign(new Error(message), { status, code });
+const isFile = (file) => { try { return fs.statSync(file).isFile(); } catch { return false; } };
+const isFolder = (dir) => { try { return fs.statSync(dir).isDirectory(); } catch { return false; } };
+
+const APPLESCRIPT = [
+  'on run argv',
+  'activate',
+  'try',
+  `return POSIX path of (choose folder with prompt "${TITLE}" default location (POSIX file (item 1 of argv)))`,
+  'on error number -128',
+  'return ""',
+  'end try',
+  'end run',
+];
+
+let windowsScript;
+function encodedWindowsScript() {
+  windowsScript ??= Buffer.from(fs.readFileSync(new URL('./folder-picker.ps1', import.meta.url), 'utf8'), 'utf16le').toString('base64');
+  return windowsScript;
+}
+
+export function folderPickTarget({ platform = process.platform, env = process.env, release = os.release(), fileExists = isFile } = {}) {
+  const onPath = (name) => (env.PATH || '').split(':').filter((dir) => path.posix.isAbsolute(dir))
+    .map((dir) => path.posix.join(dir, name)).find(fileExists);
+  let command, kind, translate, reason;
+  if (platform === 'win32') {
+    kind = 'windows';
+    command = path.win32.join(env.SystemRoot || env.WINDIR || 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  } else if (platform === 'darwin') {
+    kind = 'mac';
+    command = '/usr/bin/osascript';
+  } else if (platform === 'linux' && (env.WSL_DISTRO_NAME || /microsoft|wsl/i.test(release))) {
+    kind = 'windows';
+    translate = onPath('wslpath');
+    command = translate && onPath('powershell.exe');
+    reason = 'Windows PowerShell is unavailable. Enable Windows interoperability in WSL to choose folders.';
+  } else if (platform === 'linux') {
+    if (env.DISPLAY || env.WAYLAND_DISPLAY) {
+      command = onPath('zenity');
+      kind = command ? 'zenity' : 'kdialog';
+      command ||= onPath('kdialog');
+      reason = 'Install zenity or kdialog to choose folders.';
+    } else reason = 'Choosing folders requires a desktop session on the computer running Agent Guild.';
+  } else reason = 'Choosing folders is unavailable on this operating system.';
+  const available = Boolean(command && fileExists(command));
+  return { command, kind, translate, available, reason: available ? null : reason || 'The folder dialog is unavailable on the computer running Agent Guild.' };
+}
+
+export function createFolderPicker({ resolveCwd, spawnImpl = spawn, env = process.env, ...targetOptions }) {
+  let pending = false;
+
+  const run = (command, args, { signal, env: childEnv = env } = {}) => new Promise((resolve, reject) => {
+    let child, out = '';
+    try {
+      child = spawnImpl(command, args, { env: childEnv, shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch (error) { return reject(error); }
+    const stop = () => child.kill();
+    if (signal?.aborted) stop();
+    else signal?.addEventListener('abort', stop, { once: true });
+    child.stdout.setEncoding('utf8').on('data', (chunk) => { out += chunk; });
+    child.once('error', reject);
+    child.once('close', (code) => {
+      signal?.removeEventListener('abort', stop);
+      resolve({ code, out: out.replace(/[\r\n]+$/, '') });
+    });
+  });
+
+  function dialog(target, start, signal) {
+    if (target.kind === 'windows') {
+      const vars = { AGENT_GUILD_PICK_START: start, AGENT_GUILD_PICK_TITLE: TITLE };
+      if (target.translate) vars.WSLENV = [env.WSLENV, 'AGENT_GUILD_PICK_START/p', 'AGENT_GUILD_PICK_TITLE'].filter(Boolean).join(':');
+      return run(target.command, ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encodedWindowsScript()], { signal, env: { ...env, ...vars } });
+    }
+    if (target.kind === 'mac') return run(target.command, [...APPLESCRIPT.flatMap((line) => ['-e', line]), start], { signal });
+    if (target.kind === 'zenity') return run(target.command, ['--file-selection', '--directory', `--title=${TITLE}`, `--filename=${path.join(start, path.sep)}`], { signal });
+    return run(target.command, ['--title', TITLE, '--getexistingdirectory', start], { signal });
+  }
+
+  return {
+    describe() {
+      const { available, reason } = folderPickTarget({ env, ...targetOptions });
+      return { available, reason };
+    },
+    async pick(cwd, { signal } = {}) {
+      if (cwd !== undefined && (typeof cwd !== 'string' || /[\0\r\n]/.test(cwd))) {
+        throw failure(400, 'bad_cwd', 'The working folder must be a directory path.');
+      }
+      if (pending) throw failure(409, 'folder_pick_busy', 'A folder dialog is already open on the computer running Agent Guild.');
+      const target = folderPickTarget({ env, ...targetOptions });
+      if (!target.available) throw failure(409, 'folder_pick_unavailable', target.reason);
+      let start;
+      try { start = resolveCwd(cwd); } catch { start = os.homedir(); }
+      pending = true;
+      try {
+        const broken = () => failure(409, 'folder_pick_failed', 'Could not show the folder dialog. Check that a desktop session is available on the computer running Agent Guild.');
+        let result = await dialog(target, start, signal).catch(() => { throw broken(); });
+        const cancelled = result.code === 0 || (result.code === 1 && target.kind !== 'windows' && target.kind !== 'mac');
+        if (signal?.aborted || (!result.out && cancelled)) return null;
+        if (result.code !== 0) throw broken();
+        if (target.translate) {
+          result = await run(target.translate, ['-u', result.out], { signal }).catch(() => ({ code: 1 }));
+          if (result.code !== 0) throw failure(409, 'folder_pick_failed', 'The chosen folder cannot be reached from WSL.');
+        }
+        const dir = path.resolve(result.out);
+        if (!isFolder(dir)) throw failure(409, 'folder_pick_failed', 'The chosen folder cannot be used as a working folder.');
+        return dir;
+      } finally { pending = false; }
+    },
+  };
+}

package/src/manager/folder-picker.ps1

@@ -0,0 +1,84 @@
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -ReferencedAssemblies System.Windows.Forms -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+using System.Windows.Forms;
+public static class GuildFolderPicker {
+  [ComImport, Guid("DC1C5A9C-E88A-4dde-A5A1-60F82A20AEF7")] class FileOpenDialog {}
+  [ComImport, Guid("42f85136-db7e-439c-85f1-e4075d135fc8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface IFileDialog {
+    [PreserveSig] int Show(IntPtr owner);
+    void SetFileTypes(uint count, IntPtr specs);
+    void SetFileTypeIndex(uint index);
+    void GetFileTypeIndex(out uint index);
+    void Advise(IntPtr events, out uint cookie);
+    void Unadvise(uint cookie);
+    void SetOptions(uint options);
+    void GetOptions(out uint options);
+    void SetDefaultFolder(IShellItem item);
+    void SetFolder(IShellItem item);
+    void GetFolder(out IShellItem item);
+    void GetCurrentSelection(out IShellItem item);
+    void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string name);
+    void GetFileName([MarshalAs(UnmanagedType.LPWStr)] out string name);
+    void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string title);
+    void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string text);
+    void SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string text);
+    void GetResult(out IShellItem item);
+  }
+  [ComImport, Guid("43826D1E-E718-42EE-BC55-A1E261C37BFE"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface IShellItem {
+    void BindToHandler(IntPtr context, ref Guid handler, ref Guid iid, out IntPtr result);
+    void GetParent(out IShellItem parent);
+    void GetDisplayName(uint form, [MarshalAs(UnmanagedType.LPWStr)] out string name);
+  }
+  [StructLayout(LayoutKind.Sequential)] struct RECT { public int L, T, R, B; }
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+  static extern void SHCreateItemFromParsingName(string path, IntPtr context, ref Guid iid, out IShellItem item);
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr window, out RECT rect);
+  [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr window, IntPtr process);
+  [DllImport("kernel32.dll")] static extern uint GetCurrentThreadId();
+  [DllImport("user32.dll")] static extern bool AttachThreadInput(uint from, uint to, bool attach);
+  [DllImport("user32.dll")] static extern bool SetForegroundWindow(IntPtr window);
+
+  public static string Pick(string start, string title) {
+    var dialog = (IFileDialog)new FileOpenDialog();
+    uint options;
+    dialog.GetOptions(out options);
+    dialog.SetOptions(options | 0x20 | 0x40 | 0x800);
+    dialog.SetTitle(title);
+    if (!string.IsNullOrEmpty(start)) {
+      try {
+        IShellItem folder;
+        Guid iid = typeof(IShellItem).GUID;
+        SHCreateItemFromParsingName(start, IntPtr.Zero, ref iid, out folder);
+        dialog.SetFolder(folder);
+      } catch {}
+    }
+    // A dialog from a background process opens behind the browser. An invisible owner that takes
+    // the foreground brings it to the front, just inside the window that asked.
+    using (var owner = new Form { TopMost = true, ShowInTaskbar = false, FormBorderStyle = FormBorderStyle.None, Opacity = 0, StartPosition = FormStartPosition.Manual }) {
+      IntPtr asking = GetForegroundWindow();
+      RECT r;
+      if (GetWindowRect(asking, out r)) owner.SetBounds(r.L + 48, r.T + 48, 1, 1);
+      else owner.StartPosition = FormStartPosition.CenterScreen;
+      owner.Show();
+      uint front = GetWindowThreadProcessId(asking, IntPtr.Zero), self = GetCurrentThreadId();
+      AttachThreadInput(self, front, true);
+      SetForegroundWindow(owner.Handle);
+      AttachThreadInput(self, front, false);
+      if (dialog.Show(owner.Handle) != 0) return null;
+    }
+    IShellItem picked;
+    dialog.GetResult(out picked);
+    string path;
+    picked.GetDisplayName(0x80058000, out path);
+    return path;
+  }
+}
+'@
+$picked = [GuildFolderPicker]::Pick($env:AGENT_GUILD_PICK_START, $env:AGENT_GUILD_PICK_TITLE)
+if ($picked) { [Console]::Out.Write($picked) }

package/src/manager/github-views.mjs

@@ -0,0 +1,171 @@
+// Issues, Actions runs and open pull requests of one repository, read with a
+// signed-in account. Reading and editing stay shallow: GitHub's page is the full view.
+
+import { nextLink, parseRepo } from './github.mjs';
+
+const PAGE = 30;
+const RUNNING = new Set(['queued', 'in_progress', 'waiting', 'requested', 'pending']);
+const WEB = 'https://github.com';
+const ISSUE_RE = /^[1-9]\d{0,9}$/;
+
+function refusal(status, code, message) {
+  return Object.assign(new Error(message), { status, code });
+}
+
+/** A github.com page, or the fallback built from checked parts. */
+export function githubUrl(value, fallback) {
+  try {
+    const url = new URL(value);
+    if (url.protocol === 'https:' && url.hostname === 'github.com') return url.href;
+  } catch { /* the fallback */ }
+  return fallback;
+}
+
+function text(value, max) {
+  return typeof value === 'string' ? value.slice(0, max) : '';
+}
+
+function time(value) {
+  return Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
+}
+
+function loginOf(user) {
+  return typeof user?.login === 'string' && user.login.trim() ? user.login.trim().slice(0, 80) : 'unknown';
+}
+
+function cleanIssue(raw, fullName) {
+  const number = raw?.number;
+  if (!raw || typeof raw !== 'object' || !Number.isSafeInteger(number) || number < 1) return null;
+  if (typeof raw.title !== 'string' || !raw.title.trim()) return null;
+  return {
+    number,
+    title: raw.title.trim().slice(0, 256),
+    body: text(raw.body, 65536),
+    state: raw.state === 'closed' ? 'closed' : 'open',
+    user: loginOf(raw.user),
+    comments: Number.isSafeInteger(raw.comments) ? raw.comments : 0,
+    updatedAt: time(raw.updated_at),
+    url: githubUrl(raw.html_url, `${WEB}/${fullName}/issues/${number}`),
+  };
+}
+
+function cleanRun(raw, fullName) {
+  const id = raw?.id;
+  if (!raw || typeof raw !== 'object' || !Number.isSafeInteger(id) || id < 1) return null;
+  return {
+    id,
+    name: text(raw.name, 200) || text(raw.display_title, 200) || 'Workflow',
+    title: text(raw.display_title, 300) || text(raw.name, 300) || 'Workflow run',
+    branch: text(raw.head_branch, 200),
+    event: text(raw.event, 40),
+    status: typeof raw.status === 'string' ? raw.status.slice(0, 40) : 'unknown',
+    conclusion: typeof raw.conclusion === 'string' ? raw.conclusion.slice(0, 40) : null,
+    runNumber: Number.isSafeInteger(raw.run_number) ? raw.run_number : null,
+    updatedAt: time(raw.updated_at),
+    url: githubUrl(raw.html_url, `${WEB}/${fullName}/actions/runs/${id}`),
+  };
+}
+
+function cleanPull(raw, fullName) {
+  const number = raw?.number;
+  if (!raw || typeof raw !== 'object' || !Number.isSafeInteger(number) || number < 1) return null;
+  if (typeof raw.title !== 'string' || !raw.title.trim()) return null;
+  return {
+    number,
+    title: raw.title.trim().slice(0, 256),
+    draft: raw.draft === true,
+    user: loginOf(raw.user),
+    head: text(raw.head?.ref, 200),
+    base: text(raw.base?.ref, 200),
+    updatedAt: time(raw.updated_at),
+    url: githubUrl(raw.html_url, `${WEB}/${fullName}/pull/${number}`),
+  };
+}
+
+function checkTitle(title) {
+  if (typeof title !== 'string' || !title.trim()) throw refusal(400, 'bad_title', 'title must be a non-empty string');
+  if (title.trim().length > 256) throw refusal(400, 'bad_title', 'Keep the title to 256 characters or fewer.');
+  return title.trim();
+}
+
+function checkBody(body) {
+  if (body === undefined || body === null) return '';
+  if (typeof body !== 'string') throw refusal(400, 'bad_body', 'body must be a string');
+  if (body.length > 48000) throw refusal(400, 'bad_body', 'Keep the description to 48,000 characters or fewer, or edit it on GitHub.');
+  return body;
+}
+
+export function createViews(github) {
+  /** One request for the repository's account. GitHub's own refusals become answers the page can show as they are. */
+  async function call(accountId, owner, name, route, init) {
+    const account = github.account(accountId);
+    const repo = parseRepo(`${owner ?? ''}/${name ?? ''}`);
+    try {
+      const { body, res } = await github._apiJson(account, `/repos/${repo.owner}/${repo.name}${route}`, init);
+      return { body, res, repo };
+    } catch (err) {
+      if (err.limited) throw refusal(429, 'rate_limited', err.message);
+      if (err.github === 404) throw refusal(404, 'not_found', `GitHub could not find ${repo.fullName} for @${account.login}`);
+      if (err.github === 410) throw refusal(404, 'issues_disabled', `Issues are turned off for ${repo.fullName}`);
+      if (err.github === 403) throw refusal(403, 'forbidden', `GitHub did not let @${account.login} do that in ${repo.fullName}`);
+      if (err.github === 422) throw refusal(400, 'github_rejected', err.message);
+      throw err;
+    }
+  }
+
+  return {
+    async issues(accountId, owner, name, { state = 'open' } = {}) {
+      if (state !== 'open' && state !== 'closed' && state !== 'all') throw refusal(400, 'bad_state', 'state must be open, closed or all');
+      const { body, res, repo } = await call(accountId, owner, name, `/issues?state=${state}&per_page=${PAGE}&sort=updated&direction=desc`);
+      return {
+        issues: (Array.isArray(body) ? body : []).filter((item) => item && !item.pull_request).map((item) => cleanIssue(item, repo.fullName)).filter(Boolean),
+        truncated: Boolean(nextLink(res.headers.get('link'))),
+        url: `${WEB}/${repo.fullName}/issues`,
+      };
+    },
+
+    async createIssue(accountId, owner, name, { title, body } = {}) {
+      const payload = { title: checkTitle(title), body: checkBody(body) };
+      const { body: created, repo } = await call(accountId, owner, name, '/issues', { method: 'POST', body: JSON.stringify(payload) });
+      const issue = cleanIssue(created, repo.fullName);
+      if (!issue) throw refusal(502, 'github_error', 'GitHub did not describe the new issue');
+      return issue;
+    },
+
+    async updateIssue(accountId, owner, name, number, patch = {}) {
+      if (!ISSUE_RE.test(String(number ?? ''))) throw refusal(400, 'bad_issue', 'issue number must be a positive integer');
+      const payload = {};
+      if (patch.title !== undefined) payload.title = checkTitle(patch.title);
+      if (patch.body !== undefined) payload.body = checkBody(patch.body);
+      if (patch.state !== undefined) {
+        if (patch.state !== 'open' && patch.state !== 'closed') throw refusal(400, 'bad_state', 'state must be open or closed');
+        payload.state = patch.state;
+      }
+      if (Object.keys(payload).length === 0) throw refusal(400, 'bad_request', 'nothing to update');
+      const { body, repo } = await call(accountId, owner, name, `/issues/${Number(number)}`, { method: 'PATCH', body: JSON.stringify(payload) });
+      const issue = cleanIssue(body, repo.fullName);
+      if (!issue) throw refusal(502, 'github_error', 'GitHub did not describe the issue');
+      return issue;
+    },
+
+    async actions(accountId, owner, name) {
+      const { body, res, repo } = await call(accountId, owner, name, `/actions/runs?per_page=${PAGE}`);
+      const runs = (Array.isArray(body?.workflow_runs) ? body.workflow_runs : []).map((item) => cleanRun(item, repo.fullName)).filter(Boolean);
+      return {
+        runs,
+        running: runs.some((run) => RUNNING.has(run.status)),
+        truncated: Boolean(nextLink(res.headers.get('link'))),
+        url: `${WEB}/${repo.fullName}/actions`,
+      };
+    },
+
+    async pulls(accountId, owner, name) {
+      const { body, res, repo } = await call(accountId, owner, name, `/pulls?state=open&per_page=${PAGE}&sort=updated&direction=desc`);
+      return {
+        pulls: (Array.isArray(body) ? body : []).map((item) => cleanPull(item, repo.fullName)).filter(Boolean),
+        truncated: Boolean(nextLink(res.headers.get('link'))),
+        url: `${WEB}/${repo.fullName}/pulls`,
+      };
+    },
+  };
+}