@oddessentials/agent-guild 0.26.0 → 0.28.0

package/src/manager/folder-browser.mjs

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const failure = (status, code, message) => Object.assign(new Error(message), { status, code });
+const byName = (a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base', numeric: true }) || (a.name < b.name ? -1 : 1);
+
+export function folderSegments(dir, paths = path) {
+  const root = paths.parse(dir).root;
+  const segments = [{ name: root, path: root }];
+  let current = root;
+  for (const part of dir.slice(root.length).split(paths.sep).filter(Boolean)) {
+    current = paths.join(current, part);
+    segments.push({ name: part, path: current });
+  }
+  return segments;
+}
+
+export function createFolderBrowser({ platform = process.platform, home = os.homedir(), limit = 2000, driveTimeoutMs = 500, fsp = fs.promises } = {}) {
+  const paths = platform === 'win32' ? path.win32 : path.posix;
+
+  async function roots() {
+    if (platform !== 'win32') return [{ name: '/', path: '/' }];
+    const letters = [...'ABCDEFGHIJKLMNOPQRSTUVWXYZ'];
+    const found = await Promise.all(letters.map((letter) => {
+      let timer;
+      const probe = fsp.stat(`${letter}:\\`).then((stat) => stat.isDirectory(), () => false);
+      const late = new Promise((resolve) => { timer = setTimeout(resolve, driveTimeoutMs, false); });
+      return Promise.race([probe, late]).finally(() => clearTimeout(timer));
+    }));
+    return letters.filter((_, i) => found[i]).map((letter) => ({ name: `${letter}:`, path: `${letter}:\\` }));
+  }
+
+  async function nearestFolder(dir) {
+    for (;;) {
+      try {
+        if ((await fsp.stat(dir)).isDirectory()) return dir;
+      } catch (error) {
+        if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw failure(409, 'folder_unreadable', `Agent Guild cannot read ${dir}.`);
+      }
+      const parent = paths.dirname(dir);
+      if (parent === dir) return home;
+      dir = parent;
+    }
+  }
+
+  async function entries(dir) {
+    let listed;
+    try {
+      listed = await fsp.readdir(dir, { withFileTypes: true });
+    } catch {
+      throw failure(409, 'folder_unreadable', `Agent Guild cannot read ${dir}.`);
+    }
+    const folders = await Promise.all(listed.map(async (entry) => {
+      let folder = entry.isDirectory();
+      if (!folder && entry.isSymbolicLink()) folder = await fsp.stat(paths.join(dir, entry.name)).then((stat) => stat.isDirectory(), () => false);
+      return folder ? { name: entry.name, path: paths.join(dir, entry.name), hidden: entry.name.startsWith('.') } : null;
+    }));
+    return folders.filter(Boolean).sort(byName);
+  }
+
+  return {
+    async list(raw) {
+      if (raw !== undefined && raw !== null && (typeof raw !== 'string' || raw.includes('\0'))) {
+        throw failure(400, 'bad_path', 'The folder must be a path.');
+      }
+      let asked = String(raw ?? '').trim();
+      if (asked === '~' || asked.startsWith('~/') || asked.startsWith('~\\')) asked = paths.join(home, asked.slice(1));
+      const wanted = asked ? paths.resolve(asked) : home;
+      const dir = await nearestFolder(wanted);
+      const [folders, drives] = await Promise.all([entries(dir), roots()]);
+      const parent = paths.dirname(dir);
+      return {
+        path: dir,
+        parent: parent === dir ? null : parent,
+        home,
+        segments: folderSegments(dir, paths),
+        roots: drives,
+        entries: folders.slice(0, limit),
+        truncated: folders.length > limit,
+        note: dir === wanted ? null : wanted,
+      };
+    },
+  };
+}

package/src/manager/main.mjs

@@ -12,7 +12,8 @@ import { ModelStats } from './model-stats.mjs';
 import { NewsFeed } from './news.mjs';
 import { Changelog } from './changelog.mjs';
 import { GitHub } from './github.mjs';
-import { createManagerServer, parseAllowedHosts } from './server.mjs';
+import { createManagerServer } from './server.mjs';
+import { RemoteAccess, loadRemoteAccess } from './remote-access.mjs';
 import { SelfUpdate } from './self-update.mjs';
 import { resolveBaseEnv, pathReader } from './shell-env.mjs';
 import { writeReportShims } from './report-shims.mjs';
@@ -38,12 +39,13 @@ const rootDir = path.resolve(here, '../..');
 const VERSION_REFRESH_MS = 60 * 60 * 1000;
 
 /** `version`, `packageFile` and `github` (GitHub's URLs and client id) stand in for the real ones in tests. */
-export async function startManager({ port = resolvePort(), host = DEFAULT_HOST, sessionDefaults, version = VERSION, packageFile = PACKAGE_FILE, github: githubOptions = {} } = {}) {
+export async function startManager({ port = resolvePort(), host = DEFAULT_HOST, sessionDefaults, version = VERSION, packageFile = PACKAGE_FILE, github: githubOptions = {}, remoteAccess: remoteOptions = {} } = {}) {
   // Validate before creating files, processes or timers, so a typo fails startup cleanly.
-  const extraHosts = parseAllowedHosts(process.env.AGENT_GUILD_ALLOWED_HOSTS);
+  const remoteSettings = loadRemoteAccess(paths.remoteAccess);
   ensureDataDir();
   const token = loadOrCreateToken();
   const baseEnv = resolveBaseEnv();
+  const remoteAccess = new RemoteAccess({ file: paths.remoteAccess, env: baseEnv, loaded: remoteSettings, ...remoteOptions });
   const webDir = path.join(rootDir, 'web');
   // The hooks in examples/ call `agent-guild-report` by name; these shims
   // make that name resolve inside every session. Regenerated at each start
@@ -95,6 +97,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     if (closing) return closing;
     console.log(`[manager] ${restart ? 'restarting' : 'stopping'} (${reason}); ending ${manager.sessions.size} session(s)`);
     clearInterval(versionTimer);
+    remoteAccess.close();
     github.close();
     removeRuntimeFile();
     // Sessions end before the API closes, and the last event says whether
@@ -117,9 +120,6 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     return closing;
   };
 
-  const extraOrigins = (process.env.AGENT_GUILD_ALLOWED_ORIGINS || '')
-    .split(',').map((s) => s.trim()).filter(Boolean);
-
   api = createManagerServer({
     manager,
     registry,
@@ -135,11 +135,13 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     webDir,
     version,
     selfUpdate,
-    extraHosts,
-    extraOrigins,
+    extraHosts: remoteSettings.config.access.hosts,
+    extraOrigins: remoteSettings.config.access.origins,
+    remoteAccess,
     launcher: launcherPath(),
     onShutdownRequest: ({ restart = false } = {}) => shutdown('requested via API', { restart }).then(() => process.exit(0)),
   });
+  remoteAccess.attach({ apply: (access) => api.setAccessPolicy(access), getTarget: () => api.url });
 
   try {
     await api.listen();
@@ -165,7 +167,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   });
   console.log(`[manager] Agent Guild ${version} listening on ${api.url} (pid ${process.pid})`);
   refreshVersions();
-  return { api, manager, registry, token, shutdown };
+  return { api, manager, registry, token, shutdown, remoteAccess };
 }
 
 function isEntryPoint() {

package/src/manager/remote-access.mjs

@@ -0,0 +1,286 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import https from 'node:https';
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { normalizeAccess, parseAllowedHosts, parseAllowedOrigins } from './access-policy.mjs';
+import { Tailscale, chooseRoute, remoteError, routeMatches, routeUrl } from './tailscale.mjs';
+
+const emptyAccess = () => ({ hosts: [], origins: [] });
+
+function validateRoute(route) {
+  if (!route || typeof route.nodeId !== 'string' || !route.nodeId || route.nodeId.length > 256
+    || typeof route.host !== 'string' || !route.host.endsWith('.ts.net') || parseAllowedHosts(route.host)[0] !== route.host
+    || !Number.isInteger(route.port) || route.port < 1 || route.port > 65535
+    || typeof route.target !== 'string' || !/^http:\/\/127\.0\.0\.1:[1-9]\d{0,4}$/.test(route.target)
+    || Number(new URL(route.target).port) > 65535) throw new Error('Invalid saved Tailscale route.');
+  return { nodeId: route.nodeId, host: route.host, port: route.port, target: route.target };
+}
+
+function routeAccess(route) {
+  const url = new URL(routeUrl(route));
+  return { hosts: [url.host], origins: [url.origin] };
+}
+
+function validateSaved(value) {
+  if (!value || value.version !== 1 || typeof value.revision !== 'string' || value.revision.length > 100
+    || !['off', 'custom', 'tailscale'].includes(value.mode)) throw new Error('Unsupported remote-access settings.');
+  const route = value.route ? validateRoute(value.route) : null;
+  if (value.mode === 'tailscale' && !route) throw new Error('Missing saved Tailscale route.');
+  if (value.mode !== 'tailscale' && route) throw new Error('Unexpected saved Tailscale route.');
+  const access = value.mode === 'off' ? emptyAccess() : value.mode === 'tailscale' ? routeAccess(route) : normalizeAccess(value.access);
+  let pending = null;
+  if (value.pending) {
+    if (!['enable', 'disable'].includes(value.pending.type)) throw new Error('Invalid pending remote-access operation.');
+    pending = { type: value.pending.type, route: validateRoute(value.pending.route), ...(value.pending.previous ? { previous: validateRoute(value.pending.previous) } : {}) };
+  }
+  return { version: 1, revision: value.revision, mode: value.mode, access, route, pending };
+}
+
+export function loadRemoteAccess(file, env = process.env) {
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (error) {
+    if (error.code !== 'ENOENT') return { config: disabledConfig(), source: 'saved', error: 'Remote-access settings could not be read. Local access remains available.' };
+  }
+  if (raw !== undefined) {
+    try {
+      if (raw.length > 65536) throw new Error('Settings are too large.');
+      return { config: validateSaved(JSON.parse(raw)), source: 'saved', error: null };
+    } catch {
+      return { config: disabledConfig(), source: 'saved', error: 'Saved remote-access settings are invalid. Set up remote access again to replace them. Local access remains available.' };
+    }
+  }
+  const access = { hosts: parseAllowedHosts(env.AGENT_GUILD_ALLOWED_HOSTS), origins: parseAllowedOrigins(env.AGENT_GUILD_ALLOWED_ORIGINS) };
+  const enabled = access.hosts.length > 0 || access.origins.length > 0;
+  return { config: { ...disabledConfig(), mode: enabled ? 'custom' : 'off', access }, source: enabled ? 'environment' : 'default', error: null };
+}
+
+function disabledConfig() {
+  return { version: 1, revision: randomUUID(), mode: 'off', access: emptyAccess(), route: null, pending: null };
+}
+
+export function saveRemoteAccess(file, config) {
+  const value = validateSaved(config);
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const next = `${file}.${randomUUID()}.tmp`;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(next, 'wx', 0o600);
+    fs.writeFileSync(descriptor, JSON.stringify(value, null, 2) + '\n');
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    fs.renameSync(next, file);
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    try { fs.unlinkSync(next); } catch {}
+  }
+}
+
+export function checkRemoteUrl(url, { signal, pid = process.pid } = {}) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (ok) => { if (!done) { done = true; clearTimeout(timer); resolve({ ok, checkedAt: new Date().toISOString() }); } };
+    const timer = setTimeout(() => { request.destroy(); finish(false); }, 7000);
+    const request = https.get(`${url}/api/v1/health`, { signal, headers: { 'Cache-Control': 'no-store' } }, (response) => {
+      let body = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => {
+        body += chunk;
+        if (body.length > 16384) { request.destroy(); finish(false); }
+      });
+      response.on('end', () => {
+        try {
+          const health = JSON.parse(body);
+          finish(response.statusCode === 200 && health.name === 'agent-guild' && health.pid === pid);
+        } catch { finish(false); }
+      });
+      response.on('error', () => finish(false));
+    });
+    request.on('error', () => finish(false));
+  });
+}
+
+export class RemoteAccess extends EventEmitter {
+  constructor({ file, env = process.env, loaded = loadRemoteAccess(file, env), tailscale = new Tailscale({ env }), save = saveRemoteAccess, probe = checkRemoteUrl } = {}) {
+    super();
+    Object.assign(this, { file, tailscale, save, probe, config: loaded.config, source: loaded.source });
+    this.problem = loaded.error ? { code: 'invalid_settings', message: loaded.error } : null;
+    this.busy = null;
+    this.info = null;
+    this.connection = null;
+    this.closed = false;
+    this.abort = new AbortController();
+    this.apply = () => {};
+    this.getTarget = () => null;
+    this.task = Promise.resolve();
+    this.checkTask = null;
+  }
+
+  attach({ apply, getTarget }) {
+    this.apply = apply;
+    this.getTarget = getTarget;
+  }
+
+  snapshot() {
+    const config = this.config;
+    let candidate = null;
+    if (this.info && !this.busy && this.getTarget()) {
+      try {
+        const route = chooseRoute(this.info, this.getTarget(), config.pending?.type === 'enable' ? config.pending.route : config.route);
+        candidate = { url: routeUrl(route), existing: !config.route && !config.pending && routeMatches(this.info.config, route) };
+      } catch {}
+    }
+    return {
+      available: true, revision: config.revision, source: this.source, mode: config.mode,
+      hosts: [...config.access.hosts], origins: [...config.access.origins],
+      url: config.route ? routeUrl(config.route) : null,
+      busy: this.busy, pending: config.pending?.type || null, problem: this.problem,
+      tailscale: this.info ? { connected: true, version: this.info.version, hostname: this.info.host, httpsReady: this.info.httpsReady } : null,
+      command: config.pending ? `tailscale serve --bg --https=${config.pending.route.port} --set-path=/ ${config.pending.type === 'disable' ? 'off' : config.pending.route.target}` : null,
+      candidate, connection: this.connection,
+    };
+  }
+
+  publish() { if (!this.closed) this.emit('updated'); }
+
+  persist(next) {
+    if (this.closed) throw remoteError('manager_stopping', 'The manager is stopping.');
+    const value = validateSaved({ ...next, version: 1, revision: randomUUID() });
+    this.save(this.file, value);
+    this.config = value;
+    this.source = 'saved';
+    this.apply(value.access);
+    this.publish();
+  }
+
+  async check() {
+    if (this.closed) return this.snapshot();
+    if (this.checkTask) return this.checkTask;
+    if (this.busy) return this.snapshot();
+    this.busy = 'checking';
+    this.publish();
+    this.checkTask = this.inspect().finally(() => {
+      this.busy = null;
+      this.checkTask = null;
+      this.publish();
+    }).then(() => this.snapshot());
+    return this.checkTask;
+  }
+
+  async inspect() {
+    this.connection = null;
+    try {
+      this.info = await this.tailscale.inspect({ signal: this.abort.signal });
+      const config = this.config;
+      if (config.pending) {
+        try { chooseRoute(this.info, config.pending.route.target, config.pending.route); } catch (error) {
+          const previous = config.pending.previous || config.route;
+          if (!previous || !routeMatches(this.info.config, previous)) throw error;
+          chooseRoute(this.info, previous.target, previous);
+        }
+        this.problem = this.problem?.approvalUrl && config.pending.type === 'enable' ? this.problem : { code: 'operation_pending', message: config.pending.type === 'enable'
+          ? 'Setup is unfinished. Continue to check and complete it.'
+          : 'Access through the saved address is blocked. The Tailscale route still needs cleanup.' };
+      } else if (config.route) {
+        chooseRoute(this.info, this.getTarget(), config.route);
+        if (!routeMatches(this.info.config, config.route) || config.route.target !== this.getTarget()) {
+          throw remoteError('repair_required', 'The Tailscale route needs to be updated for this manager.');
+        }
+        this.problem = null;
+        this.connection = await this.probe(routeUrl(config.route), { signal: this.abort.signal });
+      } else if (this.problem?.code !== 'invalid_settings') this.problem = null;
+    } catch (error) {
+      this.info = null;
+      this.problem = { code: error.code || 'tailscale_error', message: error.message, ...(error.approvalUrl ? { approvalUrl: error.approvalUrl } : {}) };
+    }
+  }
+
+  change(body) {
+    if (this.closed) throw remoteError('manager_stopping', 'The manager is stopping.');
+    if (this.busy) throw remoteError('remote_busy', 'A remote-access operation is already in progress.');
+    if (body.revision !== this.config.revision) throw remoteError('stale_settings', 'Remote access changed in another tab. Review the current settings and try again.');
+    if (!['enable', 'disable', 'custom', 'forget'].includes(body.action)) throw remoteError('bad_action', 'Choose a valid remote-access action.', 400);
+    let access;
+    if (body.action === 'custom') {
+      if (this.config.route || this.config.pending) throw remoteError('disable_first', 'Disable the Tailscale connection before changing custom proxy settings.');
+      try { access = normalizeAccess({ hosts: body.hosts, origins: body.origins }); } catch (error) { throw remoteError('bad_settings', error.message, 400); }
+    }
+    if (body.action === 'forget' && (this.config.mode !== 'off' || this.config.pending?.type !== 'disable')) {
+      throw remoteError('bad_action', 'Only an inactive route awaiting cleanup can be left in Tailscale.', 400);
+    }
+    this.busy = body.action === 'enable' ? 'enabling' : body.action === 'disable' ? 'disabling' : 'saving';
+    this.problem = null;
+    this.connection = null;
+    this.publish();
+    this.task = Promise.resolve().then(async () => {
+      if (body.action === 'enable') await this.enable(body.adopt === true);
+      else if (body.action === 'disable') await this.disable();
+      else if (body.action === 'custom') this.persist({ ...this.config, mode: access.hosts.length || access.origins.length ? 'custom' : 'off', access, route: null, pending: null });
+      else this.persist({ ...this.config, pending: null });
+    }).catch((error) => {
+      this.problem = { code: error.code || 'save_failed', message: error.message, ...(error.approvalUrl ? { approvalUrl: error.approvalUrl } : {}) };
+    }).finally(() => {
+      this.busy = null;
+      this.publish();
+    });
+    return this.snapshot();
+  }
+
+  async enable(adopt) {
+    if (this.config.pending?.type === 'disable') throw remoteError('cleanup_required', 'Finish cleanup of the previous route before enabling remote access.');
+    const info = await this.tailscale.inspect({ signal: this.abort.signal });
+    this.info = info;
+    let previous = this.config.pending?.type === 'enable' ? this.config.pending.route : this.config.route;
+    let route;
+    try { route = chooseRoute(info, this.getTarget(), previous); } catch (error) {
+      const fallback = this.config.pending?.previous || this.config.route;
+      if (!fallback || !routeMatches(info.config, fallback)) throw error;
+      previous = fallback;
+      route = chooseRoute(info, this.getTarget(), previous);
+    }
+    if (!previous && routeMatches(info.config, route) && !adopt) {
+      throw remoteError('adoption_required', 'A matching Tailscale route already exists. Choose “Use existing route” to let Agent Guild manage it.');
+    }
+    this.persist({ ...this.config, pending: { type: 'enable', route, ...(previous ? { previous } : {}) } });
+    let approvalUrl = null;
+    await this.tailscale.enable(route, previous, {
+      signal: this.abort.signal,
+      onApproval: (url) => {
+        approvalUrl = url;
+        this.problem = { code: 'approval_required', message: 'Approve HTTPS in Tailscale to continue setup.', approvalUrl: url };
+        this.publish();
+      },
+    }).catch((error) => {
+      if (approvalUrl && error.code === 'setup_incomplete') error.approvalUrl = approvalUrl;
+      throw error;
+    });
+    this.persist({ ...this.config, mode: 'tailscale', access: routeAccess(route), route, pending: null });
+    this.problem = null;
+    this.info = await this.tailscale.inspect({ signal: this.abort.signal });
+    this.connection = await this.probe(routeUrl(route), { signal: this.abort.signal });
+  }
+
+  async disable() {
+    const route = this.config.pending?.route || this.config.route;
+    const previous = this.config.pending?.previous || this.config.route;
+    this.persist({ ...this.config, mode: 'off', access: emptyAccess(), route: null, pending: route ? { type: 'disable', route, ...(previous ? { previous } : {}) } : null });
+    if (route) {
+      try {
+        const info = await this.tailscale.inspect({ signal: this.abort.signal });
+        const cleanup = previous && info.nodeId === previous.nodeId && info.host === previous.host && routeMatches(info.config, previous) ? previous : route;
+        this.info = await this.tailscale.remove(cleanup, { signal: this.abort.signal });
+      } catch (error) {
+        error.message = `Access through the saved address is blocked. ${error.message}`;
+        throw error;
+      }
+      this.persist({ ...this.config, pending: null });
+    }
+    this.problem = null;
+  }
+
+  close() {
+    this.closed = true;
+    this.abort.abort();
+  }
+}

package/src/manager/server.mjs

@@ -4,14 +4,14 @@
 import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
-import { isIP } from 'node:net';
 import { createRequire } from 'node:module';
 import { WebSocketServer } from 'ws';
 import { timingSafeEqualString } from './session-manager.mjs';
 import { folderOrigin } from './github.mjs';
 import { createViews } from './github-views.mjs';
 import { createFolderOpener } from './folder-opener.mjs';
-import { createFolderPicker } from './folder-picker.mjs';
+import { createFolderBrowser } from './folder-browser.mjs';
+import { normalizeAccess } from './access-policy.mjs';
 
 const require = createRequire(import.meta.url);
 const API = '/api/v1';
@@ -41,6 +41,7 @@ function vendorFiles() {
     '/vendor/xterm/xterm.css': path.join(pkgDir('@xterm/xterm'), 'css/xterm.css'),
     '/vendor/xterm/addon-fit.js': path.join(pkgDir('@xterm/addon-fit'), 'lib/addon-fit.js'),
     '/vendor/xterm/addon-web-links.js': path.join(pkgDir('@xterm/addon-web-links'), 'lib/addon-web-links.js'),
+    '/vendor/qrcode.mjs': path.join(path.dirname(require.resolve('qrcode-generator')), 'qrcode.mjs'),
   };
 }
 
@@ -62,21 +63,6 @@ class HttpError extends Error {
   }
 }
 
-/** Exact Host authorities, also safe to include as CSP WebSocket sources. */
-export function parseAllowedHosts(value = '') {
-  const entries = value.split(',').map((entry) => entry.trim().toLowerCase()).filter(Boolean);
-  for (const entry of entries) {
-    const match = /^(\[[0-9a-f:.]+\]|[a-z0-9.-]+)(?::([1-9]\d{0,4}))?$/.exec(entry);
-    const name = match?.[1];
-    const validName = name?.startsWith('[') ? isIP(name.slice(1, -1)) === 6
-      : name && name.length <= 253 && name.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
-    if (!validName || (match[2] && Number(match[2]) > 65535)) {
-      throw new Error(`Invalid AGENT_GUILD_ALLOWED_HOSTS entry ${JSON.stringify(entry)}. Use a hostname with an optional port, such as guild.example.ts.net or guild.example.ts.net:8443; URLs and wildcards are not allowed.`);
-    }
-  }
-  return [...new Set(entries)];
-}
-
 function readJsonBody(req) {
   return new Promise((resolve, reject) => {
     let size = 0;
@@ -126,28 +112,36 @@ export function createManagerServer({
   selfUpdate = null,
   extraHosts = [],
   extraOrigins = [],
+  remoteAccess = null,
   folderOpener = createFolderOpener({ resolveCwd: (cwd) => manager.resolveCwd(cwd) }),
-  folderPicker = createFolderPicker({ resolveCwd: (cwd) => manager.resolveCwd(cwd) }),
+  folderBrowser = createFolderBrowser(),
   /** The double-click launcher file for this platform, or null when the package carries none. */
   launcher = null,
   /** @type {(opts: { restart: boolean }) => void} */
   onShutdownRequest = () => {},
 }) {
-  const proxyHosts = parseAllowedHosts(extraHosts.join(','));
-  const socketSources = proxyHosts.flatMap((authority) => [`ws://${authority}`, `wss://${authority}`]);
-  const securityHeaders = {
+  let access = normalizeAccess({ hosts: extraHosts, origins: extraOrigins });
+  let policyVersion = 0;
+  const headersForAccess = () => ({
     ...SECURITY_HEADERS,
     'Content-Security-Policy': SECURITY_HEADERS['Content-Security-Policy'].replace(
-      "connect-src 'self'", ["connect-src 'self'", ...socketSources].join(' ')),
-  };
+      "connect-src 'self'", ["connect-src 'self'", ...access.hosts.flatMap((authority) => [`ws://${authority}`, `wss://${authority}`])].join(' ')),
+  });
+  let securityHeaders = headersForAccess();
   const upgradeInfo = () => (selfUpdate ? selfUpdate.describe() : null);
   const startedAt = new Date().toISOString();
   const vendor = vendorFiles();
   let boundPort = port;
 
-  const allowedHosts = () => new Set([`127.0.0.1:${boundPort}`, `localhost:${boundPort}`, `[::1]:${boundPort}`, ...proxyHosts]);
+  const localHosts = () => [`127.0.0.1:${boundPort}`, `localhost:${boundPort}`, `[::1]:${boundPort}`];
+  const allowedHosts = () => new Set([...localHosts(), ...access.hosts]);
+  const isLocalClient = (req) => localHosts().includes(String(req.headers.host || '').toLowerCase());
+  const folderOpenerFor = (req) => {
+    const opener = folderOpener.describe();
+    return isLocalClient(req) ? opener : { ...opener, available: false, reason: 'Only available on the computer running Agent Guild.' };
+  };
   const allowedOrigins = () =>
-    new Set([`http://127.0.0.1:${boundPort}`, `http://localhost:${boundPort}`, `http://[::1]:${boundPort}`, ...extraOrigins]);
+    new Set([`http://127.0.0.1:${boundPort}`, `http://localhost:${boundPort}`, `http://[::1]:${boundPort}`, ...access.origins]);
 
   /** Blocks DNS-rebinding (Host) and cross-site browser requests (Origin). */
   function checkRequestSource(req) {
@@ -188,7 +182,7 @@ export function createManagerServer({
     const notFound = () => sendJson(res, 404, { error: { code: 'not_found', message: 'not found' } });
     fs.stat(file, (statErr, stat) => {
       if (statErr || !stat.isFile()) return notFound();
-      const etag = `W/"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`;
+      const etag = `W/"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}-${policyVersion}"`;
       const headers = {
         ...securityHeaders,
         'Content-Type': MIME[path.extname(file).toLowerCase()] || 'application/octet-stream',
@@ -258,6 +252,17 @@ export function createManagerServer({
 
     requireAuth(req, url);
 
+    if (remoteAccess && route === '/remote-access' && method === 'GET') {
+      return sendJson(res, 200, { remoteAccess: remoteAccess.snapshot() });
+    }
+    if (remoteAccess && route === '/remote-access/check' && method === 'POST') {
+      return sendJson(res, 200, { remoteAccess: await remoteAccess.check() });
+    }
+    if (remoteAccess && route === '/remote-access' && method === 'PUT') {
+      const operation = remoteAccess.change(await readJsonBody(req));
+      return sendJson(res, 202, { remoteAccess: operation });
+    }
+
     if (route === '/info' && method === 'GET') {
       selfUpdate?.refresh().catch(() => {});
       return sendJson(res, 200, {
@@ -269,20 +274,18 @@ export function createManagerServer({
         warnings: registry.warnings,
         upgrade: upgradeInfo(),
         launcher,
-        folderOpener: folderOpener.describe(),
-        folderPicker: folderPicker.describe(),
+        folderOpener: folderOpenerFor(req),
+        remoteAccess: remoteAccess ? { available: true } : null,
       });
     }
     if (route === '/open-folder' && method === 'POST') {
       const { cwd } = await readJsonBody(req);
+      if (!isLocalClient(req)) throw new HttpError(403, 'Only available on the computer running Agent Guild.', 'local_only');
       await folderOpener.open(cwd);
       return sendJson(res, 200, { ok: true });
     }
-    if (route === '/pick-folder' && method === 'POST') {
-      const { cwd } = await readJsonBody(req);
-      const gone = new AbortController();
-      res.once('close', () => gone.abort());
-      return sendJson(res, 200, { path: await folderPicker.pick(cwd, { signal: gone.signal }) });
+    if (route === '/folders' && method === 'GET') {
+      return sendJson(res, 200, await folderBrowser.list(url.searchParams.get('path') ?? undefined));
     }
     if (route === '/upgrade' && method === 'POST') {
       const session = await manager.upgrade();
@@ -496,7 +499,7 @@ export function createManagerServer({
   const eventClients = new Set();
 
   const safeSend = (ws, message) => {
-    if (ws.readyState !== ws.OPEN) return;
+    if (ws.revoked || ws.readyState !== ws.OPEN) return;
     if (ws.bufferedAmount > SLOW_CLIENT_BYTES) {
       // The client can reconnect and will receive a fresh snapshot.
       ws.close(4008, 'client too slow');
@@ -528,10 +531,11 @@ export function createManagerServer({
   news?.on('updated', () => broadcast({ type: 'news.updated' }));
   changelog?.on('updated', () => broadcast({ type: 'changelog.updated' }));
   github?.on('updated', () => broadcast({ type: 'github.updated' }));
+  remoteAccess?.on('updated', () => broadcast({ type: 'remote-access.updated' }));
 
-  function handleEvents(ws) {
+  function handleEvents(ws, req) {
     eventClients.add(ws);
-    safeSend(ws, { type: 'hello', version, pid: process.pid, startedAt, launcher, folderOpener: folderOpener.describe(), folderPicker: folderPicker.describe(), upgrade: upgradeInfo(), sessions: manager.list() });
+    safeSend(ws, { type: 'hello', version, pid: process.pid, platform: process.platform, startedAt, launcher, folderOpener: folderOpenerFor(req), remoteAccess: remoteAccess ? { available: true } : null, upgrade: upgradeInfo(), sessions: manager.list() });
     ws.on('close', () => eventClients.delete(ws));
     ws.on('message', () => { /* events socket is server -> client only */ });
   }
@@ -549,9 +553,10 @@ export function createManagerServer({
       safeSend(ws, message);
       if (message.type === 'removed') ws.close(4410, 'session removed');
     });
+    ws.detachTerminal = detach;
     ws.on('close', detach);
     ws.on('message', (raw, isBinary) => {
-      if (isBinary) return;
+      if (isBinary || ws.revoked) return;
       let msg;
       try { msg = JSON.parse(raw.toString('utf8')); } catch { return; }
       if (msg.type === 'input' && typeof msg.data === 'string') session.input(msg.data);
@@ -575,11 +580,12 @@ export function createManagerServer({
     const termMatch = url.pathname.match(/^\/api\/v1\/sessions\/([a-f0-9]+)\/terminal$/);
     if (url.pathname !== `${API}/events` && !termMatch) return reject(404, 'Not Found');
     wss.handleUpgrade(req, socket, head, (ws) => {
+      ws.source = { headers: { host: req.headers.host, origin: req.headers.origin } };
       ws.isAlive = true;
       ws.on('pong', () => { ws.isAlive = true; });
       ws.on('error', () => {});
       if (termMatch) handleTerminal(ws, termMatch[1]);
-      else handleEvents(ws);
+      else handleEvents(ws, req);
     });
   });
 
@@ -594,6 +600,21 @@ export function createManagerServer({
 
   return {
     server,
+    setAccessPolicy(next) {
+      access = normalizeAccess(next);
+      policyVersion++;
+      securityHeaders = headersForAccess();
+      for (const ws of wss.clients) {
+        try { checkRequestSource(ws.source); } catch {
+          ws.revoked = true;
+          ws.detachTerminal?.();
+          ws.close(4403, 'Remote access changed');
+          const timer = setTimeout(() => ws.terminate(), 500);
+          timer.unref();
+          ws.once('close', () => clearTimeout(timer));
+        }
+      }
+    },
     get port() { return boundPort; },
     get url() { return `http://127.0.0.1:${boundPort}`; },
     listen() {