@openlines/opl-pi-sht 0.2.12 → 0.3.1

package/extensions/opl-browser/config.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export interface BrowserConfig {
   headless: boolean;
@@ -9,9 +9,12 @@ export interface BrowserConfig {
   navigationTimeoutMs: number;
   previewChars: number;
   getChars: number;
-  /** Allow navigate/new_page to reach private/link-local ranges (loopback is always
-   *  allowed; cloud metadata is always blocked). Default false. */
+  /** Allow navigate/new_page to reach private/link-local ranges (default false).
+   *  Cloud metadata is always blocked. */
   allowPrivateNetwork: boolean;
+  /** Allow loopback hosts — localhost, 127.0.0.0/8, ::1 (default true, for local dev
+   *  servers). Cloud metadata is unaffected. */
+  allowLoopback: boolean;
 }
 
 export const DEFAULT_CONFIG: BrowserConfig = {
@@ -22,14 +25,18 @@ export const DEFAULT_CONFIG: BrowserConfig = {
   previewChars: 4000,
   getChars: 30000,
   allowPrivateNetwork: false,
+  allowLoopback: false,
 };
 
-const CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "configs", "opl-browser.json");
+/** Resolved per call so a custom `PI_AGENT_DIR` (pi's own agent dir) is honoured. */
+export function configPath(): string {
+  return join(getAgentDir(), "configs", "opl-browser.json");
+}
 
-export function loadUserConfig(configPath = CONFIG_PATH): BrowserConfig {
+export function loadUserConfig(file = configPath()): BrowserConfig {
   let user: Partial<BrowserConfig> = {};
   try {
-    user = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    user = JSON.parse(fs.readFileSync(file, "utf8"));
   } catch {
     user = {};
   }
@@ -41,5 +48,6 @@ export function loadUserConfig(configPath = CONFIG_PATH): BrowserConfig {
     previewChars: user.previewChars ?? DEFAULT_CONFIG.previewChars,
     getChars: user.getChars ?? DEFAULT_CONFIG.getChars,
     allowPrivateNetwork: user.allowPrivateNetwork ?? DEFAULT_CONFIG.allowPrivateNetwork,
+    allowLoopback: user.allowLoopback ?? DEFAULT_CONFIG.allowLoopback,
   };
 }

package/extensions/opl-browser/index.ts

@@ -35,7 +35,8 @@ export default function (pi: ExtensionAPI) {
     description:
       `Drive a real Chromium browser (Playwright) for web testing and inspection. One dispatcher tool; pick action: ${ACTIONS}. ` +
       "navigate(url|back|forward|reload); snapshot (accessibility tree); extract (rendered-page markdown, optionally scoped to selector); screenshot (saved to file, not inlined); " +
-      "click/fill/hover/select by CSS selector; press(key); evaluate(script in page); console/network (captured for active page); " +
+      "click/fill/hover/select by CSS selector; press(key); evaluate(script in page); console/network (captured per page); " +
+      "index selects which page a page-scoped action runs on; without it the selected page is used and a stale selection is an error. " +
       "wait_for(selector|text); pages/new_page/select_page/close_page; resize(width,height); get(responseId) to retrieve a stored large result; close to shut the browser. " +
       "Large outputs return a preview + responseId; call action:get with that id for the full text.",
     parameters: Type.Object({
@@ -48,14 +49,14 @@ export default function (pi: ExtensionAPI) {
       script: Type.Optional(Type.String({ description: "evaluate: JS expression run in the page" })),
       path: Type.Optional(Type.String({ description: "screenshot: output file path" })),
       fullPage: Type.Optional(Type.Boolean({ description: "screenshot: capture full scrollable page" })),
-      index: Type.Optional(Type.Number({ description: "select_page/close_page: page index" })),
+      index: Type.Optional(Type.Number({ description: "page-scoped actions: act on this page index instead of the selected one (see pages)" })),
       timeoutMs: Type.Optional(Type.Number({ description: "wait_for: timeout in ms" })),
       width: Type.Optional(Type.Number({ description: "resize: viewport width" })),
       height: Type.Optional(Type.Number({ description: "resize: viewport height" })),
       responseId: Type.Optional(Type.String({ description: "get: id from a previous large result" })),
       offset: Type.Optional(Type.Number({ description: "get: character offset to continue a truncated retrieval" })),
     }),
-    async execute(_toolCallId, params) {
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const p = params as BrowserParams & { responseId?: string; offset?: number };
 
       if (p.action === "get") {
@@ -76,7 +77,7 @@ export default function (pi: ExtensionAPI) {
 
       let result;
       try {
-        result = await runAction(p, cfg);
+        result = await runAction(p, cfg, ctx.cwd);
       } catch (e) {
         return err(`browser ${p.action}: ${e instanceof Error ? e.message : String(e)}`);
       }

package/extensions/opl-browser/package-lock.json

@@ -1,13 +1,13 @@
 {
   "name": "opl-browser",
-  "version": "1.1.0",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "opl-browser",
-      "version": "1.1.0",
-      "license": "ISC",
+      "version": "0.2.0",
+      "license": "MIT",
       "dependencies": {
         "@mozilla/readability": "^0.6.0",
         "linkedom": "^0.18.13",

package/extensions/opl-browser/package.json

@@ -1,9 +1,9 @@
 {
   "name": "opl-browser",
-  "version": "1.1.0",
-  "description": "Chromium browser automation for pi via Playwright. A single dispatcher tool for navigation, snapshots, interaction, console/network capture, and evaluation — replaces the chrome-devtools MCP server.",
-  "main": "index.js",
-  "license": "ISC",
+  "version": "0.2.0",
+  "private": true,
+  "description": "Chromium browser automation for pi via Playwright. A single dispatcher tool for navigation, snapshots, interaction, console/network capture, and evaluation \u2014 replaces the chrome-devtools MCP server.",
+  "license": "MIT",
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",

package/extensions/opl-browser/validate.ts

@@ -1,13 +1,26 @@
 // Pure URL/path guards for the browser tool. No Playwright import so tests load it directly.
 
-import { existsSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { closeSync, mkdirSync, openSync, realpathSync, statSync, unlinkSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { promises as dns } from "node:dns";
 
 export interface HttpUrlOptions {
-  /** Allow private, link-local, and reserved network hosts (default false). Loopback is always allowed; cloud metadata is always blocked. */
+  /** Allow private, link-local, and reserved network hosts (default false). Cloud metadata is always blocked. */
   allowPrivateNetwork?: boolean;
+  /** Allow loopback hosts — localhost, 127.0.0.0/8, ::1 (default false: opt in). */
+  allowLoopback?: boolean;
+  /** Test seam for host resolution; production callers leave it unset and use node:dns. */
+  resolveHost?: (host: string) => Promise<string[]>;
+  /** Caller's abort signal. The lookup itself cannot be cancelled, so this only bounds how long
+   *  the caller waits; without it a stalled getaddrinfo outlives the caller's own timeout. */
+  signal?: AbortSignal;
+  /** Self-bound for the DNS round-trip when the caller passes no signal (ms). */
+  dnsTimeoutMs?: number;
 }
 
+// BEGIN SHARED HOST GUARD — duplicated verbatim in extensions/opl-browser/validate.ts
+// (install.sh installs one extension directory at a time, so this cannot be a shared import;
+//  tests/net-guard-parity.test.mjs fails if the two copies drift)
 /** Well-known cloud metadata hostnames that resolve to instance-credential endpoints. */
 const BLOCKED_METADATA_HOSTS = new Set([
   "metadata",
@@ -17,77 +30,159 @@ const BLOCKED_METADATA_HOSTS = new Set([
 ]);
 
 /** Cloud metadata IPv6 literals (e.g. AWS IMDS over IPv6). Always blocked. */
-const BLOCKED_METADATA_V6 = new Set(["fd00:ec2::254"]);
+const BLOCKED_METADATA_V6 = new Set(["fd00:ec2:0:0:0:0:0:254"]);
 
-type HostClass = "loopback" | "metadata" | "private" | "public";
+type HostClass = "loopback" | "metadata" | "unspecified" | "translation" | "private" | "public";
 
-function ipv4FromInteger(n: number): number[] | null {
+/** The four octets of an IPv4 address. The arity is the whole point of the classifier, so it is a
+ *  tuple rather than a list whose elements TypeScript must assume could be missing. */
+type Ipv4 = readonly [number, number, number, number];
+/** The eight groups of an IPv6 literal, with any `::` already expanded. */
+type Ipv6Groups = readonly [number, number, number, number, number, number, number, number];
+
+/** Build a tuple from a list whose arity a length check established but `split`/`map` cannot show
+ *  to TypeScript. The length test keeps the previous rejection of over-long quads; the per-element
+ *  tests are what the compiler needs. These are the only two widening points in the guard. */
+function asIpv4(values: number[]): Ipv4 | null {
+  const [a, b, c, d] = values;
+  if (values.length !== 4 || a === undefined || b === undefined || c === undefined || d === undefined) return null;
+  return [a, b, c, d];
+}
+function asIpv6Groups(values: number[]): Ipv6Groups | null {
+  const [a, b, c, d, e, f, g, h] = values;
+  if (
+    values.length !== 8 ||
+    a === undefined || b === undefined || c === undefined || d === undefined ||
+    e === undefined || f === undefined || g === undefined || h === undefined
+  ) {
+    return null;
+  }
+  return [a, b, c, d, e, f, g, h];
+}
+
+/** Decode a bare unsigned 32-bit integer hostname (e.g. 2130706433) into octets. */
+function ipv4FromInteger(n: number): Ipv4 | null {
   if (!Number.isInteger(n) || n < 0 || n > 0xffffffff) return null;
   return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
 }
 
-function ipv4Octets(host: string): number[] | null {
+/** Parse a host into IPv4 octets (dotted-quad or integer form), or null when not an IPv4 literal. */
+function ipv4Octets(host: string): Ipv4 | null {
   if (/^\d+$/.test(host)) return ipv4FromInteger(Number(host));
   const octets = host.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : NaN));
-  if (octets.length !== 4 || octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return null;
-  return octets;
+  if (octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return null;
+  return asIpv4(octets);
 }
 
-function isLoopbackIpv4(o: number[]): boolean {
+function isLoopbackIpv4(o: Ipv4): boolean {
   return o[0] === 127;
 }
 
-function isMetadataIpv4(o: number[]): boolean {
+function isMetadataIpv4(o: Ipv4): boolean {
   return (
-    (o[0] === 169 && o[1] === 254 && o[2] === 169 && o[3] === 254) ||
-    (o[0] === 100 && o[1] === 100 && o[2] === 100 && o[3] === 200)
+    (o[0] === 169 && o[1] === 254 && o[2] === 169 && o[3] === 254) || // AWS/Azure/GCP/Oracle
+    (o[0] === 100 && o[1] === 100 && o[2] === 100 && o[3] === 200) // Alibaba
   );
 }
 
-function isPrivateIpv4(o: number[]): boolean {
+/** Non-globally-routable (blocked by default, opt-in via allowPrivateNetwork). */
+function isPrivateIpv4(o: Ipv4): boolean {
   const [a, b, c] = o;
   return (
-    a === 0 || a === 10 ||
-    (a === 100 && b >= 64 && b <= 127) ||
-    (a === 169 && b === 254) ||
-    (a === 172 && b >= 16 && b <= 31) ||
-    (a === 192 && b === 168) ||
-    (a === 192 && b === 0 && (c === 0 || c === 2)) ||
-    (a === 198 && (b === 18 || b === 19)) ||
-    (a === 198 && b === 51 && c === 100) ||
-    (a === 203 && b === 0 && c === 113) ||
-    a >= 224
+    a === 10 || // 10/8
+    (a === 100 && b >= 64 && b <= 127) || // 100.64/10 carrier-grade NAT
+    (a === 169 && b === 254) || // 169.254/16 link-local
+    (a === 172 && b >= 16 && b <= 31) || // 172.16/12
+    (a === 192 && b === 168) || // 192.168/16
+    (a === 192 && b === 0 && (c === 0 || c === 2)) || // 192.0.0/24, 192.0.2/24
+    (a === 198 && (b === 18 || b === 19)) || // 198.18/15 benchmark
+    (a === 198 && b === 51 && c === 100) || // 198.51.100/24
+    (a === 203 && b === 0 && c === 113) || // 203.0.113/24
+    a >= 224 // 224/4 multicast and 240/4 reserved
   );
 }
 
-function ipv4MappedOctets(ip: string): number[] | null {
-  const dotted = ip.match(/^::ffff:(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
-  if (dotted) return dotted.slice(1).map(Number);
-  const hex = ip.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-  if (hex) {
-    const n = (parseInt(hex[1], 16) << 16) | parseInt(hex[2], 16);
-    return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+/** "This host on this network" (0.0.0.0/8, ::) — reaching it means reaching local listeners,
+ * so it is never toggleable the way cloud metadata is not. */
+function isUnspecifiedIpv4(o: Ipv4): boolean {
+  return o[0] === 0;
+}
+
+/** Expand a compressed, dotted-suffix or full IPv6 literal into its eight 16-bit groups. */
+function ipv6Groups(ip: string): Ipv6Groups | null {
+  const sides = ip.split("::");
+  if (sides.length > 2) return null;
+  const parse = (side: string): number[] | null => {
+    if (!side) return [];
+    const out: number[] = [];
+    for (const part of side.split(":")) {
+      const dotted = part.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+      if (dotted) {
+        const o = asIpv4(dotted.slice(1, 5).map(Number));
+        if (!o || o.some((n) => n > 255)) return null;
+        const [q0, q1, q2, q3] = o;
+        out.push((q0 << 8) | q1, (q2 << 8) | q3);
+        continue;
+      }
+      if (!part || !/^[0-9a-f]{1,4}$/.test(part)) return null;
+      out.push(parseInt(part, 16));
+    }
+    return out;
+  };
+  const head = parse(sides[0] ?? "");
+  if (!head) return null;
+  if (sides.length === 1) return asIpv6Groups(head);
+  const tail = parse(sides[1] ?? "");
+  if (!tail) return null;
+  const fill = 8 - head.length - tail.length;
+  if (fill < 1) return null; // `::` must stand for at least one zero group
+  return asIpv6Groups([...head, ...Array(fill).fill(0), ...tail]);
+}
+
+/** IPv4 that an IPv6 literal still routes to: mapped (`::ffff:`), NAT64 (`64:ff9b::/96`),
+ *  6to4 (`2002::/16`) and the deprecated IPv4-compatible form (`::a.b`).
+ *  Wherever those prefixes are still routable they reach the embedded address, so the embedded
+ *  address is what has to be classified — otherwise `http://[64:ff9b::a9fe:a9fe]/` walks past the
+ *  metadata block one literal away from 169.254.169.254, and a DNS64 answer can do the same. */
+function embeddedIpv4Octets(ip: string): Ipv4 | null {
+  const g = ipv6Groups(ip);
+  if (!g) return null;
+  const zeros = (from: number, to: number) => g.slice(from, to).every((x) => x === 0);
+  const low32 = (): Ipv4 => [(g[6] >> 8) & 0xff, g[6] & 0xff, (g[7] >> 8) & 0xff, g[7] & 0xff];
+  if (g[5] === 0xffff && zeros(0, 5)) return low32();
+  if (g[0] === 0x2002) {
+    return [(g[1] >> 8) & 0xff, g[1] & 0xff, (g[2] >> 8) & 0xff, g[2] & 0xff]; // 6to4 carries v4 after the prefix (tuple by return type)
+  }
+  if (g[0] === 0x0064 && g[1] === 0xff9b) {
+    if (zeros(2, 6)) return low32(); // NAT64 well-known prefix
   }
+  if (zeros(0, 6) && (g[6] !== 0 || g[7] !== 0)) return low32(); // IPv4-compatible (deprecated)
   return null;
 }
 
-function classifyIpv4Octets(o: number[]): HostClass {
+function classifyIpv4Octets(o: Ipv4): HostClass {
   if (isLoopbackIpv4(o)) return "loopback";
   if (isMetadataIpv4(o)) return "metadata";
+  if (isUnspecifiedIpv4(o)) return "unspecified";
   if (isPrivateIpv4(o)) return "private";
   return "public";
 }
 
 function classifyIpv6Host(host: string): HostClass {
   const ip = host.replace(/^\[/, "").replace(/\]$/, "").replace(/%.*$/, "").toLowerCase();
-  if (BLOCKED_METADATA_V6.has(ip)) return "metadata";
-  if (ip === "::1") return "loopback";
-  const mapped = ipv4MappedOctets(ip);
-  if (mapped) return classifyIpv4Octets(mapped);
-  if (ip === "::") return "private";
-  if (/^f[cd]/.test(ip)) return "private";
-  if (/^fe[89ab]/.test(ip)) return "private";
-  if (/^ff/.test(ip)) return "private";
+  const groups = ipv6Groups(ip);
+  if (groups) {
+    if (BLOCKED_METADATA_V6.has(groups.map((g) => g.toString(16)).join(":"))) return "metadata";
+    if (groups.every((g) => g === 0)) return "unspecified";
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return "loopback";
+    // Local-use translation layouts vary; no opt-in may bypass this prefix block.
+    if (groups[0] === 0x0064 && groups[1] === 0xff9b && groups[2] === 1) return "translation";
+  }
+  const embedded = embeddedIpv4Octets(ip);
+  if (embedded) return classifyIpv4Octets(embedded);
+  if (/^f[cd]/.test(ip)) return "private"; // fc00::/7 unique-local
+  if (/^fe[89ab]/.test(ip)) return "private"; // fe80::/10 link-local
+  if (/^ff/.test(ip)) return "private"; // ff00::/8 multicast
   return "public";
 }
 
@@ -100,48 +195,206 @@ function classifyHost(host: string): HostClass {
   return octets ? classifyIpv4Octets(octets) : "public";
 }
 
-function isBlockedNetworkHost(host: string, allowPrivateNetwork: boolean): boolean {
+function isBlockedNetworkHost(host: string, allowPrivateNetwork: boolean, allowLoopback: boolean): boolean {
   const cls = classifyHost(host);
-  if (cls === "metadata") return true;
-  if (cls === "loopback" || cls === "public") return false;
-  return !allowPrivateNetwork;
+  if (cls === "metadata" || cls === "unspecified" || cls === "translation") return true; // never toggleable
+  if (cls === "loopback") return !allowLoopback;
+  if (cls === "public") return false;
+  return !allowPrivateNetwork; // private / link-local / reserved
 }
 
 /**
- * Normalize a URL, allowing only http/https, so `file:`/`data:`/`javascript:` URLs and SSRF
- * targets can't be navigated (file:// + evaluate = local file bytes returned into model context).
- * Loopback is allowed by default for local development; private/link-local/reserved ranges are
- * blocked unless allowPrivateNetwork is set; cloud metadata is always blocked.
+ * Normalize a URL, allowing only http/https. Loopback (localhost/127.0.0.0/8/::1) is
+ * opt-in through allowLoopback; private/link-local/reserved ranges are blocked unless
+ * allowPrivateNetwork is set; cloud metadata, unspecified addresses and 64:ff9b:1::/48 are always blocked.
  */
 export function assertHttpUrl(url: string, opts: HttpUrlOptions = {}): string {
   let parsed: URL;
   try {
     parsed = new URL(url);
   } catch {
-    throw new Error(`invalid URL: ${url}`);
+    throw new Error(`Invalid URL: ${url}`);
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new Error(`only http/https URLs are allowed, got ${parsed.protocol}//`);
+    throw new Error(`Only http/https URLs are allowed, "${parsed.protocol}"`);
   }
-  if (isBlockedNetworkHost(parsed.hostname, opts.allowPrivateNetwork === true)) {
-    throw new Error(`blocked network host "${parsed.hostname}" — private, link-local, reserved, and cloud-metadata URLs are not allowed (set allowPrivateNetwork to opt in to private ranges; metadata is always blocked)`);
+  if (isBlockedNetworkHost(parsed.hostname, opts.allowPrivateNetwork === true, opts.allowLoopback === true)) {
+    throw new Error(`Blocked network host "${parsed.hostname}" — private, link-local, and reserved URLs are not allowed (set allowPrivateNetwork to opt in to private ranges, or allowLoopback for localhost and 127.0.0.0/8; cloud-metadata, unspecified addresses such as 0.0.0.0, and the 64:ff9b:1::/48 translation prefix are always blocked)`);
   }
   return parsed.href;
 }
 
-/** Require a screenshot path to stay within the project directory and refuse to overwrite
- *  existing files (guard against overwriting project files or writing outside the repo). */
-export function safeScreenshotPath(file: string, cwd: string = process.cwd()): string {
+export function isIpLiteralHost(host: string): boolean {
+  const lowered = host.toLowerCase().replace(/^\[|\]$/g, "");
+  return lowered.includes(":") || /^\d+$/.test(lowered) || /^\d{1,3}(\.\d{1,3}){3}$/.test(lowered);
+}
+
+/** In-flight lookups by host. A page with hundreds of subresources on one host would otherwise
+ *  serialize hundreds of getaddrinfo calls on libuv's small thread pool. Entries are dropped as
+ *  soon as the lookup settles, so this deduplicates concurrency only: no decision is reused, and
+ *  a hostname that changes between two calls still gets two independent answers. */
+const inflightLookups = new Map<string, Promise<string[]>>();
+
+/** Default resolver. Rethrows the original error so `.code` survives for callers. */
+export function resolveHostAddresses(host: string): Promise<string[]> {
+  const running = inflightLookups.get(host);
+  if (running) return running;
+  const pending = dns
+    .lookup(host, { all: true, verbatim: true })
+    .then((hits) => hits.map((hit) => hit.address));
+  inflightLookups.set(host, pending);
+  const stop = () => {
+    if (inflightLookups.get(host) === pending) inflightLookups.delete(host);
+  };
+  pending.then(stop, stop);
+  return pending;
+}
+
+/** Reject as soon as the caller gives up. `dns.lookup` cannot be cancelled, so without this a
+ *  stalled getaddrinfo would hold the tool past its own timeout. */
+function untilAborted<T>(pending: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return pending;
+  const aborted = new Promise<never>((_, reject) => {
+    const fail = () => reject(Object.assign(new Error("Aborted"), { name: "AbortError" }));
+    if (signal.aborted) fail();
+    else signal.addEventListener("abort", fail, { once: true });
+  });
+  return Promise.race([pending, aborted]);
+}
+
+/** A URL that passed the policy check, together with the addresses that decision used. */
+export interface SafeHttpTarget {
+  /** Normalized absolute URL. */
+  url: string;
+  /** Hostname with any IPv6 brackets stripped. */
+  host: string;
+  /** The classified answers. A literal-IP host contributes that literal. */
+  addresses: string[];
+}
+
+/**
+ * Same policy as assertHttpUrl, plus a DNS round-trip: a hostname that answers with a
+ * loopback, private, link-local, reserved, or metadata address is rejected before any
+ * request is made. Literal-IP hosts skip the lookup. Text-only classification is not enough
+ * on its own — `http://169.254.169.254.nip.io/` reads as a public hostname.
+ *
+ * The answers are returned so a caller can pin its socket to one of them: validating a name
+ * and then letting the transport resolve it again leaves a window where a short-TTL record
+ * answers a public address at check time and an internal one at connect time.
+ */
+export async function resolveSafeHostUrl(url: string, opts: HttpUrlOptions = {}): Promise<SafeHttpTarget> {
+  const normalized = assertHttpUrl(url, opts);
+  const host = new URL(normalized).hostname.replace(/^\[|\]$/g, "");
+  if (isIpLiteralHost(host)) return { url: normalized, host, addresses: [host] }; // already classified; no DNS round-trip
+  // A stalled getaddrinfo must not outlive the caller's own budget, and with no caller signal
+  // (a browser route handler, a frame re-check) the guard bounds itself instead of hanging.
+  const dnsSignal = opts.signal ?? (opts.dnsTimeoutMs ? AbortSignal.timeout(opts.dnsTimeoutMs) : undefined);
+  const answers = opts.resolveHost
+    ? await untilAborted(Promise.resolve(opts.resolveHost(host)), dnsSignal)
+    : await untilAborted(resolveHostAddresses(host), dnsSignal);
+  if (!answers.length) throw new Error(`Could not resolve host "${host}"`);
+  const allowPrivate = opts.allowPrivateNetwork === true;
+  const allowLoopback = opts.allowLoopback === true;
+  for (const answer of answers) {
+    if (isBlockedNetworkHost(answer, allowPrivate, allowLoopback)) {
+      throw new Error(`Blocked network host "${host}" — it resolves to ${answer}, and private, link-local, and reserved addresses are not allowed (set allowPrivateNetwork to opt in to private ranges, or allowLoopback for localhost and 127.0.0.0/8; cloud-metadata, unspecified addresses such as 0.0.0.0, and the 64:ff9b:1::/48 translation prefix are always blocked)`);
+    }
+  }
+  return { url: normalized, host, addresses: answers };
+}
+
+/** `resolveSafeHostUrl` for callers that do not open a socket. */
+export async function assertSafeHttpUrl(url: string, opts: HttpUrlOptions = {}): Promise<string> {
+  return (await resolveSafeHostUrl(url, opts)).url;
+}
+// END SHARED HOST GUARD
+
+const NON_HTTP = /^(data|blob|about|chrome|chrome-extension|devtools|view-source):/i;
+
+/**
+ * Route-level decision for requests a page makes on its own (subresources, scripts,
+ * popups, JS-driven redirects). Only ENOTFOUND fails open: a genuinely missing host
+ * cannot be reached by the page either, while any other resolver failure could be
+ * hiding an internal answer and must abort.
+ */
+export async function decideSubresource(url: string, opts: HttpUrlOptions = {}): Promise<"continue" | "abort"> {
+  if (NON_HTTP.test(url)) return "continue";
+  try {
+    await assertSafeHttpUrl(url, opts);
+    return "continue";
+  } catch (err) {
+    return (err as { code?: string })?.code === "ENOTFOUND" ? "continue" : "abort";
+  }
+}
+
+/** Resolve the deepest existing ancestor of `abs` through symlinks, or null if none exists.
+ *  A path that does not exist yet is contained by the directory that would hold it. */
+function realAncestor(abs: string): string | null {
+  let cur = abs;
+  for (;;) {
+    try {
+      return realpathSync(cur);
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return null;
+      cur = parent;
+    }
+  }
+}
+
+/**
+ * Resolve a screenshot target inside the session directory, and *reserve* it.
+ *
+ * Three things are checked, in this order: the path stays under `cwd` lexically; it stays under
+ * the real session directory once every symlink in the existing part of the path is followed (a
+ * `shots -> ~/.pi` entry inside the project would otherwise carry the write out of it); and the
+ * name is an image. Then the file is created with `wx`, so "refuse to overwrite" and "hand this
+ * path to Playwright" are one atomic operation instead of a check-then-write race, and a symlink
+ * standing at the target is refused like any other existing path rather than followed onto the
+ * file it points at.
+ *
+ * Returns the absolute path - the caller writes there instead of letting Playwright resolve a
+ * relative name against whatever directory the harness happened to start in.
+ */
+export function safeScreenshotPath(file: string, cwd: string): string {
   const root = resolve(cwd);
-  const abs = resolve(cwd, file);
+  const abs = resolve(root, file);
   if (abs !== root && !abs.startsWith(root + sep)) {
     throw new Error(`screenshot path must stay within the project directory: ${file}`);
   }
-  if (!/\.(png|jpe?g)$/i.test(file)) {
+  if (!/\.(png|jpe?g)$/i.test(abs)) {
     throw new Error(`screenshot path must end in .png or .jpg: ${file}`);
   }
-  if (existsSync(abs)) {
-    throw new Error(`screenshot path already exists (refusing to overwrite): ${file}`);
+  let realRoot = root;
+  try {
+    realRoot = realpathSync(root);
+  } catch {
+    // The session directory itself is missing; there is no real root to contain anything.
+  }
+  const real = realAncestor(abs);
+  if (real && real !== realRoot && !real.startsWith(realRoot + sep)) {
+    throw new Error(`screenshot path resolves outside the project directory: ${file}`);
+  }
+  mkdirSync(dirname(abs), { recursive: true });
+  let fd: number;
+  try {
+    fd = openSync(abs, "wx");
+  } catch (err) {
+    if ((err as { code?: string }).code === "EEXIST") {
+      throw new Error(`screenshot path already exists (refusing to overwrite): ${file}`);
+    }
+    throw err;
+  }
+  closeSync(fd);
+  return abs;
+}
+
+/** Drop a reservation that never got written (a failed capture must not leave an empty file
+ *  behind), and leave anything with content - including an earlier screenshot - alone. */
+export function discardEmptyFile(abs: string): void {
+  try {
+    if (statSync(abs).size === 0) unlinkSync(abs);
+  } catch {
+    // Already gone, or never created: nothing to clean up.
   }
-  return file;
 }

package/extensions/opl-configurator/README.md

@@ -0,0 +1,40 @@
+# opl-configurator
+
+A generic, extensible configuration shell for the OPL extension kit. It owns the `/configurator` command and a small tab bar; each instrumented extension publishes one tab, and the user switches between tabs by tapping the tab's hotkey (much like the footer's reorder view is reached with `r`).
+
+The shell itself has no configuration and no tools.
+
+## How an extension opts in
+
+An instrumented extension registers one entry on `globalThis.__oplConfiguratorTabs` at load time:
+
+```ts
+const tab = {
+  id: "opl-footer",
+  hotkey: "f",
+  label: "Footer",
+  create(api) {
+    return {
+      render(width) {},
+      invalidate() {},
+      handleInput(data) {},
+    };
+  },
+};
+```
+
+- `id` is a unique extension id (the hotkey and id must not collide with another tab).
+- `hotkey` is a single lowercase letter the shell uses to focus the tab.
+- `label` is the short text in the tab bar.
+- `create(api)` returns a component with the same contract as `ctx.ui.custom`'s return value. `api` carries `{ ctx, tui, theme, keybindings, done }`.
+
+The shell reads the registry lazily when `/configurator` runs, so extension load order does not matter. Entries are validated rather than trusted: malformed entries and duplicate ids or hotkeys are dropped, and a tab whose `create` throws is skipped without taking the whole configurator down. The footer and input replace their own tab entries on reload, so their factories use the current extension instances. If every tab fails to load, Escape closes the diagnostic screen.
+
+## Keyboard model
+
+The shell reserves two things: `esc` closes the configurator, and each tab's hotkey focuses that tab. Everything else is delegated to the active tab, which keeps its own keys (the footer tab still uses `←`/`→` for its layout tabs and `r` for reorder). `create` is called again on every `/configurator` invocation, so a tab starts in a fresh state each time.
+
+## Extension features
+
+- **`/configurator`** command only; no tools and no config file.
+- Ships a tab for each instrumented extension installed beside it: `f` footer (`opl-footer`), `i` input (`opl-input`). With no instrumented extension present, the command reports that nothing is wired up yet.