@openlines/opl-pi-sht 0.2.12 → 0.3.1

package/extensions/opl-simplebench/util/providers.ts

@@ -6,8 +6,8 @@
  * @writtenby VTSTech — https://www.vts-tech.org
  */
 import * as fs from "node:fs";
-import * as path from "node:path";
-import os from "node:os";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "./debug";
 
 /** Minimal shape of Pi's extension context that provider detection reads. Keeps this module
@@ -41,11 +41,23 @@ export const EXTENSION_VERSION = "1.3.4";
  *
  * @example
  * ```typescript
- * console.log(MODELS_JSON_PATH);
+ * Pi reads it from its own agent directory, so `modelsJsonPath()` resolves it per call
+ * and a custom `PI_AGENT_DIR` is honoured.
+ *
+ * @example
+ * ```typescript
+ * console.log(modelsJsonPath());
  * // Output: "/home/user/.pi/agent/models.json"
  * ```
  */
-export const MODELS_JSON_PATH: string = path.join(os.homedir(), ".pi", "agent", "models.json");
+export function modelsJsonPath(): string {
+  return join(getAgentDir(), "models.json");
+}
+
+/** Pi's credential store, resolved the same way as {@link modelsJsonPath}. */
+export function authJsonPath(): string {
+  return join(getAgentDir(), "auth.json");
+}
 
 // ============================================================================
 // Types
@@ -189,8 +201,9 @@ export function getOllamaBaseUrl(): string {
   const now = Date.now();
   if (_ollamaBaseUrlCache && now - _ollamaBaseUrlCache.ts < CACHE_TTL_MS) return _ollamaBaseUrlCache.data;
   try {
-    if (fs.existsSync(MODELS_JSON_PATH)) {
-      const raw = fs.readFileSync(MODELS_JSON_PATH, "utf-8");
+    const file = modelsJsonPath();
+    if (fs.existsSync(file)) {
+      const raw = fs.readFileSync(file, "utf-8");
       const config = JSON.parse(raw) as PiModelsJson;
       const baseUrl = config?.providers?.["ollama"]?.baseUrl;
       if (baseUrl) {
@@ -234,8 +247,9 @@ export function readModelsJson(): PiModelsJson {
   const now = Date.now();
   if (_modelsJsonCache && now - _modelsJsonCache.ts < CACHE_TTL_MS) return _modelsJsonCache.data;
   try {
-    if (fs.existsSync(MODELS_JSON_PATH)) {
-      const raw = fs.readFileSync(MODELS_JSON_PATH, "utf-8");
+    const file = modelsJsonPath();
+    if (fs.existsSync(file)) {
+      const raw = fs.readFileSync(file, "utf-8");
       const data = JSON.parse(raw) as PiModelsJson;
       _modelsJsonCache = { data, ts: now };
       return data;
@@ -246,92 +260,6 @@ export function readModelsJson(): PiModelsJson {
   return empty;
 }
 
-/**
- * Write Pi's models.json configuration back to disk.
- *
- * Uses an atomic write-then-rename pattern: the new content is first written
- * to a `.tmp` sibling file, then renamed over the target. This ensures
- * concurrent readers never see a partially-written file.
- *
- * NOTE: The write-then-rename pattern provides filesystem-level atomicity
- * but does NOT protect against concurrent read-modify-write cycles (e.g.
- * two processes both read the file, mutate in memory, then write back).
- * If that becomes a concern in the future, file-based locking (e.g. `proper-lockfile`)
- * should be added around the read-modify-write sequence.
- *
- * @param data - The configuration object to write
- *
- * @example
- * ```typescript
- * const config = readModelsJson();
- * config.providers["ollama"] = {
- *   baseUrl: "http://localhost:11434/v1",
- *   models: [{ id: "qwen3:0.6b" }]
- * };
- * writeModelsJson(config);
- * ```
- */
-export function writeModelsJson(data: PiModelsJson): void {
-  const dir = path.dirname(MODELS_JSON_PATH);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  const tmpPath = MODELS_JSON_PATH + ".tmp";
-  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
-  fs.renameSync(tmpPath, MODELS_JSON_PATH);
-  // Invalidate cache so next read picks up the written data
-  _modelsJsonCache = null;
-  _ollamaBaseUrlCache = null;
-}
-
-// In-memory mutex for models.json write operations
-let _modelsJsonLock: Promise<void> | null = null;
-
-/**
- * Acquire the models.json write lock.
- * Returns a release function that MUST be called when done.
- * Prevents concurrent read-modify-write cycles from different extensions.
- */
-export async function acquireModelsJsonLock(): Promise<{ release: () => void }> {
-  // Wait for any existing lock to be released
-  while (_modelsJsonLock) {
-    await _modelsJsonLock;
-  }
-  // Create new lock
-  let releaseLock: () => void;
-  _modelsJsonLock = new Promise<void>((resolve) => {
-    releaseLock = resolve;
-  });
-  return {
-    release: () => {
-      releaseLock!();
-      _modelsJsonLock = null;
-    },
-  };
-}
-
-/**
- * Safely read, modify, and write models.json under a lock.
- * Prevents concurrent read-modify-write cycles between extensions.
- *
- * @param modifier - Function that receives the current data and returns modified data (or null to abort)
- * @returns true if the write succeeded, false if aborted
- */
-export async function readModifyWriteModelsJson(
-  modifier: (data: PiModelsJson) => PiModelsJson | null
-): Promise<boolean> {
-  const { release } = await acquireModelsJsonLock();
-  try {
-    const data = readModelsJson();
-    const modified = modifier(data);
-    if (modified === null) return false;
-    writeModelsJson(modified);
-    return true;
-  } finally {
-    release();
-  }
-}
-
 // ============================================================================
 // Ollama API Helpers
 // ============================================================================
@@ -470,86 +398,6 @@ export async function fetchOllamaModels(baseUrl: string): Promise<OllamaModel[]>
   });
 }
 
-/**
- * Fetch detailed model info from Ollama's /api/show endpoint.
- *
- * Returns the model's context window size (`num_ctx`), along with
- * other details like the template and system prompt. Used by
- * ollama-sync to enrich model entries with context length metadata.
- *
- * @param baseUrl - The Ollama base URL (without /v1 suffix)
- * @param modelName - The model tag name (e.g., "qwen3:0.6b")
- * @returns Context length in tokens, or undefined if unavailable
- *
- * @example
- * ```typescript
- * const ctx = await fetchModelContextLength("http://localhost:11434", "qwen3:0.6b");
- * console.log(ctx); // 8192
- * ```
- */
-export async function fetchModelContextLength(
-  baseUrl: string,
-  modelName: string
-): Promise<number | undefined> {
-  return withRetry(async () => {
-    try {
-      const res = await fetch(`${baseUrl}/api/show`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name: modelName }),
-        signal: AbortSignal.timeout(30000),
-      });
-      if (!res.ok) return undefined;
-      const data = (await res.json()) as {
-        model_info?: Record<string, unknown>;
-        template?: string;
-      };
-      const modelInfo = data.model_info ?? {};
-      // Ollama uses architecture-specific keys like "qwen3.context_length"
-      for (const key of Object.keys(modelInfo)) {
-        if (key.endsWith(".context_length")) {
-          const val = modelInfo[key];
-          if (typeof val === "number") return val;
-        }
-      }
-      // Fallback: generic "num_ctx" key
-      const numCtx = data?.model_info?.["num_ctx"];
-      if (typeof numCtx === "number") return numCtx;
-    } catch (err) {
-      debugLog("ollama", `failed to fetch context length for ${modelName}`, err);
-      return undefined;
-    }
-    return undefined;
-  });
-}
-
-/**
- * Fetch context lengths for multiple models, processing them in small batches
- * to avoid overwhelming the connection (especially over tunnels).
- *
- * @param baseUrl - The Ollama base URL (without /v1 suffix)
- * @param modelNames - Array of model tag names
- * @param batchSize - Number of concurrent requests (default: 3)
- * @returns Map of model name to context length (undefined if unavailable)
- */
-export async function fetchContextLengthsBatched(
-  baseUrl: string,
-  modelNames: string[],
-  batchSize = 3
-): Promise<Map<string, number | undefined>> {
-  const result = new Map<string, number | undefined>();
-  for (let i = 0; i < modelNames.length; i += batchSize) {
-    const batch = modelNames.slice(i, i + batchSize);
-    const results = await Promise.allSettled(
-      batch.map((name) => fetchModelContextLength(baseUrl, name))
-    );
-    results.forEach((r, idx) => {
-      result.set(batch[idx], r.status === "fulfilled" ? r.value : undefined);
-    });
-  }
-  return result;
-}
-
 /**
  * Check if an Ollama model name suggests reasoning capability.
  *
@@ -728,7 +576,7 @@ function expandEnvVars(value: string): string {
  */
 function readAuthJsonKey(providerName: string): string {
   try {
-    const p = path.join(os.homedir(), ".pi", "agent", "auth.json");
+    const p = authJsonPath();
     if (!fs.existsSync(p)) return "";
     const entry = JSON.parse(fs.readFileSync(p, "utf-8"))[providerName];
     return typeof entry?.key === "string" ? entry.key : "";
@@ -825,22 +673,3 @@ export function detectProvider(ctx: PiExtensionContext, modelsJson?: PiModelsJso
   // Tier 3: Unknown provider
   return { kind: "unknown", name: providerName };
 }
-
-// ============================================================================
-// Local Provider Detection
-// ============================================================================
-
-/**
- * Check if a provider URL indicates a local (on-machine) provider.
- * Used by api.ts, status.ts, and diag.ts to determine whether
- * system metrics (CPU/RAM/Swap) are meaningful.
- *
- * @param baseUrl - The provider's base URL (e.g. "http://localhost:11434/v1")
- * @param providerName - Optional provider name (e.g. "ollama")
- * @returns `true` if the provider is local, `false` otherwise
- */
-export function isLocalProvider(baseUrl: string, providerName?: string): boolean {
-  if (providerName === "ollama") return true;
-  const url = baseUrl || "";
-  return url.includes("localhost") || url.includes("127.0.0.1") || url.includes("0.0.0.0");
-}

package/extensions/opl-todo/README.md

@@ -7,19 +7,19 @@ Provides branch-aware model-managed tasks with a non-capturing overlay and full-
 - `/todos`: open the current branch's full-screen task list; `Esc` closes it.
 - Tool: `todo` with `list`, `add`, `toggle`, and `clear` actions.
 - `shortcuts.toggleWidget`: show or hide the overlay, default `ctrl+alt+t`.
-- `shortcuts.resetDone`: clear only a fully completed list, default `ctrl+alt+r`.
+- `shortcuts.resetDone`: clear completed todos while keeping unfinished items, default `ctrl+alt+r`.
 
 ## Extension features
 
 - Stores todos in session tool results; switching session branches with `/tree` restores that branch's list.
 - Starts a fresh batch at ID `#1` when adding after every prior task is complete.
-- Displays a top-right overlay without taking editor focus; hides below 80 columns and caps its height to the configured terminal percentage.
+- Displays a top-right overlay without taking editor focus; hides below 80 columns and caps its height to the configured terminal percentage. The row count comes from the overlay renderer - pi-tui reports the dimensions it is about to draw into on every frame - so a redirected stdout or an embedded terminal of a different shape cannot make the widget size itself against the wrong screen. Until the first frame reports a height, a 24-row terminal is assumed.
 - Shows `✓ All done!` and hides after the configured delay; `clear` hides immediately.
 - Reconstructs state on session start, `/reload`, and session-tree changes. A completed restored list is cleared so the next add begins a new batch.
 
 ## Configuration
 
-Copy [`configs/opl-todo.json.sample`](../../configs/opl-todo.json.sample) to `~/.pi/agent/configs/opl-todo.json`, then `/reload` or restart Pi.
+Copy [`configs/opl-todo.json.sample`](../../configs/opl-todo.json.sample) to `~/.pi/agent/configs/opl-todo.json`, then `/reload` or restart Pi. The example below shows **chosen values, not defaults** - the defaults are in the table.
 
 ```json
 {
@@ -33,9 +33,9 @@ Copy [`configs/opl-todo.json.sample`](../../configs/opl-todo.json.sample) to `~/
 |---|---:|---|
 | `allDoneHideMs` | `5000` | Delay before a completed overlay hides; `0` hides immediately. |
 | `shortcuts.toggleWidget` | `ctrl+alt+t` | Toggle overlay visibility. |
-| `shortcuts.resetDone` | `ctrl+alt+r` | Clear only a fully completed list. |
+| `shortcuts.resetDone` | `ctrl+alt+r` | Clear completed todos while keeping unfinished items. |
 | `widget.widthPercent` | `33` | Overlay width, greater than 0 through 100. |
-| `widget.maxHeightPercent` | `50` | Terminal-row percentage used for the item cap. |
+| `widget.maxHeightPercent` | `50` | Percentage of the **renderer-reported** terminal height used for the item cap (minus the box's own chrome, floor of 3 items). |
 | `widget.minWidth` | `32` | Minimum overlay width; values below 20 are rejected. |
 
 ## Architecture

package/extensions/opl-todo/config.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export interface TodoConfig {
 	allDoneHideMs: number;
@@ -28,7 +28,12 @@ const DEFAULT: TodoConfig = {
 	},
 };
 
-function load(path = join(homedir(), ".pi", "agent", "configs", "opl-todo.json")): TodoConfig {
+/** 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-todo.json");
+}
+
+function load(path = configPath()): TodoConfig {
 	try {
 		if (!existsSync(path)) return DEFAULT;
 		const raw = JSON.parse(readFileSync(path, "utf8"));

package/extensions/opl-todo/index.ts

@@ -24,6 +24,13 @@ interface TodoDetails {
 	error?: string;
 }
 
+interface TodoStateSnapshot {
+	todos: Todo[];
+	nextId: number;
+}
+
+const TODO_STATE_ENTRY = "opl-todo-state";
+
 // ── Widget constants ─────────────────────────────────────────────────────────
 
 const TodoParams = Type.Object({
@@ -32,20 +39,34 @@ const TodoParams = Type.Object({
 	id: Type.Optional(Type.Number({ description: "Todo ID (for toggle)" })),
 });
 
+/** Rows per terminal before the overlay has reported one (first frame, or a non-TUI host). */
+const FALLBACK_ROWS = 24;
+
+/** How many todo lines fit in `rows` terminal rows, given the configured height budget and the
+ *  box's own chrome (border, title, progress line, footer). */
+export function widgetMaxItems(rows: number): number {
+	const usable = (rows > 0 ? rows : FALLBACK_ROWS) * CONFIG.widget.maxHeightPercent;
+	return Math.max(3, Math.floor(usable / 100) - 5);
+}
+
 /**
  * Persistent top-right overlay. Non-capturing — never steals editor focus.
  * Reads the shared `todos` array directly so render() always reflects live state.
  */
-class TodoWidgetComponent {
+export class TodoWidgetComponent {
 	constructor(
 		private readonly todos: Todo[],
 		private readonly theme: Theme,
+		// The height comes from the overlay renderer, which reports the terminal it is drawing
+		// into on every frame. The harness terminal size is not that: with stdout redirected, or
+		// an embedded terminal of a different shape, it describes some other screen.
+		private readonly terminalRows: () => number = () => FALLBACK_ROWS,
 	) {}
 
 	render(width: number): string[] {
 		const th = this.theme;
 		const t = this.todos;
-		const maxItems = Math.max(3, Math.floor((process.stdout.rows || 24) * CONFIG.widget.maxHeightPercent / 100) - 5);
+		const maxItems = widgetMaxItems(this.terminalRows());
 		const W = Math.max(width, CONFIG.widget.minWidth);
 
 		const b = (s: string) => th.fg("border", s);
@@ -168,6 +189,8 @@ export default function (pi: ExtensionAPI) {
 	// ── Widget handles ─────────────────────────────────────────────────────
 	let overlayHandle: OverlayHandle | undefined;
 	let tuiRef: TUI | undefined;
+	// Terminal height as the overlay renderer last reported it. 0 until the first frame.
+	let overlayRows = 0;
 	let autoHideTimer: ReturnType<typeof setTimeout> | undefined;
 
 	function showWidget(): void {
@@ -194,6 +217,15 @@ export default function (pi: ExtensionAPI) {
 		nextId = 1;
 
 		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type === "custom" && entry.customType === TODO_STATE_ENTRY) {
+				const state = entry.data as TodoStateSnapshot | undefined;
+				if (state && Array.isArray(state.todos) && typeof state.nextId === "number") {
+					todos.length = 0;
+					todos.push(...state.todos);
+					nextId = state.nextId;
+				}
+				continue;
+			}
 			if (entry.type !== "message") continue;
 			const msg = entry.message;
 			if (msg.role !== "toolResult" || msg.toolName !== "todo") continue;
@@ -226,7 +258,7 @@ export default function (pi: ExtensionAPI) {
 		void ctx.ui.custom<void>(
 			(tui, theme, _kb, _done) => {
 				tuiRef = tui;
-				return new TodoWidgetComponent(todos, theme);
+				return new TodoWidgetComponent(todos, theme, () => overlayRows);
 			},
 			{
 				overlay: true,
@@ -236,7 +268,12 @@ export default function (pi: ExtensionAPI) {
 					offsetY: 0,
 					width: `${CONFIG.widget.widthPercent}%`,
 					nonCapturing: true,
-					visible: (w) => w >= 80,
+					// pi-tui calls this every frame with the dimensions it is about to draw into, so the
+					// widget sizes itself against the screen it is actually on.
+					visible: (w, h) => {
+						overlayRows = h;
+						return w >= 80;
+					},
 				},
 				onHandle: (h) => {
 					overlayHandle = h;
@@ -259,12 +296,16 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.registerShortcut(CONFIG.shortcuts.resetDone as KeyId, {
-		description: "Clear completed todos (only when all are done)",
+		description: "Clear completed todos",
 		handler: (_ctx) => {
-			if (todos.length === 0 || !todos.every((t) => t.done)) return;
-			todos.length = 0;
-			nextId = 1;
-			hideWidget();
+			const remaining = todos.filter((todo) => !todo.done);
+			if (remaining.length === todos.length) return;
+			todos.splice(0, todos.length, ...remaining);
+			if (todos.length === 0) nextId = 1;
+			clearTimeout(autoHideTimer);
+			pi.appendEntry(TODO_STATE_ENTRY, { todos: [...todos], nextId } satisfies TodoStateSnapshot);
+			if (todos.length === 0) hideWidget();
+			else showWidget();
 		},
 	});
 

package/extensions/opl-webaccess/README.md

@@ -13,9 +13,10 @@ Provides configurable web search and readable URL/PDF retrieval with session-bac
 ## Extension features
 
 - Searches through `gemini`, `tavily`, `ddgs`, `searxng`, or `exa`; multiple queries run concurrently and results include citations where available.
-- Extracts HTML with Readability and Markdown conversion, falls back to full-document Turndown conversion, passes PDF responses to the PDF extractor, and returns plain text, Markdown, and JSON directly.
-- Restricts `fetch_content` to http/https and blocks private-range, link-local, and reserved hosts by default, re-checks every redirect hop, and always blocks cloud-metadata endpoints (SSRF guard). Loopback (`localhost`/`127.0.0.0/8`/`::1`) is allowed by default for local development; set `allowPrivateNetwork: true` to reach private ranges. Caps each response at 10 MB and applies a 30s timeout; Gemini keys are sent via the `x-goog-api-key` header rather than the query string.
-- Caps initial tool output at a configurable length (default 30,000 characters), then keeps it for retrieval for one hour (expiry is enforced on read, not just on write) or until the session ends.
+- Extracts HTML with Readability and Markdown conversion, falls back to full-document Turndown conversion, normalizes PDF response buffers to plain `Uint8Array` input for text extraction, and returns plain text, Markdown, and JSON directly.
+- Restricts `fetch_content` to http/https and applies its host policy to **resolved addresses**: a URL is rejected when any DNS answer for its hostname falls in blocked space, not merely when the hostname is written as an internal literal. Private/link-local/reserved answers are blocked by default (`allowPrivateNetwork` to opt in), loopback answers are refused unless `allowLoopback: true` opts in, and cloud-metadata and unspecified addresses (`0.0.0.0/8`, `::`) are always blocked. Every redirect hop is re-validated and re-resolved, so a public first hop cannot bounce into internal space. Caps each response at 10 MB and applies a 30s timeout; the DNS round-trip is bounded by the same signal, and concurrent lookups for one host share a single query. Gemini keys are sent via the `x-goog-api-key` header rather than the query string. The addresses that pass are the ones the socket dials, so a short-TTL record cannot answer one address for the check and another for the connection.
+- Caps initial tool output at a configurable length (default 30,000 characters) and keeps results retrievable for one hour (expiry is enforced on read, not just on write) or until the session ends.
+- Keeps the full body **out of the session transcript**: each result spills to `<agent dir>/web-access-cache/<responseId>.json` (the directory pi itself uses, so a relocated `PI_CODING_AGENT_DIR` moves it) and the session entry stores a bounded preview (512 bytes per answer or URL content, marked `truncated`) plus the file path. Reads rehydrate from disk; if the spill file is gone or expired, the preview is returned with a note to re-fetch rather than a silent stub. The cache is pruned by age, then oldest-first past a 32 MB ceiling.
 - Pages `get_search_content` results (default 30,000 characters per page) with `offset` continuation, so a model never loads the whole stored body in one call.
 - Honors abort signals and returns provider, HTTP, and per-result failures through the tool boundary rather than throwing.
 
@@ -43,7 +44,10 @@ Optional top-level caps control how much content reaches the model:
 | `maxRetrievalChars` | `30000` | Cap on one `get_search_content` page. Pass `offset` to continue. |
 | `maxSearchQueries` | `10` | Cap on how many queries one `web_search` call runs. Excess queries are skipped and reported. |
 | `maxFetchUrls` | `20` | Cap on how many URLs one `fetch_content` call fetches. Excess URLs are skipped and reported. |
-| `allowPrivateNetwork` | `false` | Allow `fetch_content` to reach private/link-local ranges (loopback is always allowed; cloud metadata is always blocked). Provider API endpoints (e.g. `ddgs.apiUrl`, `searxng.instanceUrl`) are excluded from this guard. |
+| `timeoutMs` | `30000` | Deadline for one provider search or URL fetch, composed with the caller's abort signal. A slow provider fails as its own error instead of hanging the tool. |
+| `maxResponseBytes` | `10485760` | Independent ceilings on received and decoded response bytes. Exceeding either stops reading and closes the socket and decoder before output truncation. |
+| `allowPrivateNetwork` | `false` | Allow `fetch_content` to reach private/link-local ranges, literal or resolved (cloud metadata is always blocked). Provider API endpoints (e.g. `ddgs.apiUrl`, `searxng.instanceUrl`) are excluded from this guard. |
+| `allowLoopback` | `false` | Allow `fetch_content` to reach loopback — `localhost`, `127.0.0.0/8`, `::1`, literal or resolved. Set `true` to fetch from a local dev server; metadata and private ranges are unaffected by this key. |
 
 Install extraction dependencies before use:
 
@@ -54,6 +58,28 @@ npm install
 
 `@mozilla/readability`, `linkedom`, `turndown`, and `unpdf` are runtime dependencies. The extension registers without them, but affected calls fail until installed; `unpdf` loads only for PDFs.
 
+### Network policy
+
+`fetch_content` classifies the address it is about to contact, not the text in the URL:
+
+1. Scheme, userinfo and literal-host checks (`assertHttpUrl`).
+2. For a non-literal hostname, `node:dns` `lookup(host, { all: true, verbatim: true })`, then the same classifier over **every** answer. One internal answer among many public ones rejects.
+3. The addresses that passed are handed to the transport, which dials them through a pinned `lookup` (`http.ts`). Nothing in the connection path resolves the name again.
+4. Each redirect hop re-enters at step 2 with the new hostname — re-resolved and re-pinned, with no reuse across hops and no cache between calls.
+5. `Host` and TLS `servername` keep the hostname, so virtual hosting and certificate validation behave as they would unpinned. Sockets are never pooled, so a connection made under one hop's answer cannot carry a later request.
+
+The transport requests `identity` encoding but decodes `gzip`, `deflate` and `br` when a server compresses anyway. `maxResponseBytes` (default 10485760) independently caps received and decoded bytes; malformed, unsupported or chained encodings return an error. Redirects (301/302/303/307/308 with `Location`) return headers immediately and discard their bodies before the next hop is validated. The overall `timeoutMs` budget spans all hops; cancellation, inactivity and byte-limit failures close the request, response and decoder.
+
+Compressed and fully expanded IPv6 forms share the same policy, including DNS answers. NAT64 (`64:ff9b::/96`), 6to4 (`2002::/16`), mapped and IPv4-compatible addresses are classified by their embedded IPv4. The entire local-use translation prefix `64:ff9b:1::/48` is always blocked, regardless of `allowPrivateNetwork` or `allowLoopback`; this also blocks translations of public IPv4 addresses within that prefix.
+
+A resolver failure rejects the fetch (fail closed): unlike a browser's subresources, this URL was named by the model, so a host that does not resolve is an error to report rather than a request to wave through. The lookup honors the caller's abort signal and the 30s fetch budget.
+
+Residuals, deliberately left open:
+
+- **Operator endpoints are not pinned.** Provider API endpoints (`ddgs.apiUrl`, `searxng.instanceUrl`) are chosen by you, not by the model, so they stay reachable on private or loopback hosts and go through the ordinary client.
+- **A response body can describe internal services.** The guard decides where the tool connects, not what the text says.
+- **`opl-browser` cannot pin.** Chromium resolves names internally and no Playwright API exposes a per-connection resolver; see its README. This pin covers `fetch_content`, not page traffic.
+
 ## Architecture
 
-`index.ts` registers the tools and session storage. Provider adapters live under `providers/`; `search.ts` dispatches search, `extract.ts` converts readable content, `pdf.ts` handles PDFs, and stored response data backs `get_search_content`. Smoke tests bundle with these runtime dependencies externalized; they do not exercise credentials, network, extraction, or PDF behavior.
+`index.ts` registers the tools and session storage. Provider adapters live under `providers/`; `search.ts` dispatches search, `http.ts` owns the pinned transport (one request per hop, body cap enforced while reading), `extract.ts` converts readable content, `pdf.ts` handles PDFs, and stored response data backs `get_search_content`. `utils.ts` exports `resolveSafeHostUrl`, the only place a policy decision produces the address set a socket may use; `assertSafeHttpUrl` is the string-only wrapper for callers that never connect. Smoke tests bundle with these runtime dependencies externalized; they do not exercise credentials, network, extraction, or PDF behavior.

package/extensions/opl-webaccess/config.ts

@@ -26,15 +26,28 @@ export interface WebAccessConfig {
   maxSearchQueries?: number;
   /** Cap on the number of URLs a single fetch_content call may fetch. */
   maxFetchUrls?: number;
-  /** Allow fetch_content to reach private/link-local ranges (loopback is always
-   *  allowed; cloud metadata is always blocked). Default false. */
+  /** Allow fetch_content to reach private/link-local ranges (default false). Cloud
+   *  metadata is always blocked. */
   allowPrivateNetwork?: boolean;
+  /** Allow fetch_content to reach loopback hosts — localhost, 127.0.0.0/8, ::1
+   *  (default false: opt in). Cloud metadata is unaffected. */
+  allowLoopback?: boolean;
+  /** Deadline applied to one provider search request or one fetched URL (ms,
+   *  default 30000). The agent's own abort signal is combined with it, so the
+   *  shorter of the two wins. */
+  timeoutMs?: number;
+  /** Ceiling on one fetched response body (bytes, default 10485760). The transport stops
+   *  reading and drops the socket past it, so an oversized page cannot cost memory before
+   *  content truncation gets a say. */
+  maxResponseBytes?: number;
 }
 
 export const DEFAULT_MAX_CONTENT_CHARS = 30_000;
 export const DEFAULT_MAX_RETRIEVAL_CHARS = 30_000;
 export const DEFAULT_MAX_SEARCH_QUERIES = 10;
 export const DEFAULT_MAX_FETCH_URLS = 20;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
 
 /** Coerce an unknown value into a positive integer, else the fallback. */
 function positiveInt(value: unknown, fallback: number): number {
@@ -55,7 +68,20 @@ export function resolveCaps(
   };
 }
 
-const CONFIG_PATH = join(getAgentDir(), "configs", "opl-webaccess.json");
+/** Per-request deadline for provider calls and URL fetches (ms). */
+export function resolveTimeoutMs(cfg: Pick<WebAccessConfig, "timeoutMs">): number {
+  return positiveInt(cfg.timeoutMs, DEFAULT_TIMEOUT_MS);
+}
+
+/** Per-response body ceiling for URL fetches (bytes). */
+export function resolveMaxResponseBytes(cfg: Pick<WebAccessConfig, "maxResponseBytes">): number {
+  return positiveInt(cfg.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES);
+}
+
+/** Resolved per call so a custom `PI_CODING_AGENT_DIR` (pi's own agent dir) is honoured. */
+export function configPath(): string {
+  return join(getAgentDir(), "configs", "opl-webaccess.json");
+}
 
 const DEFAULT_CONFIG: WebAccessConfig = {
   provider: "gemini",
@@ -68,13 +94,13 @@ const DEFAULT_CONFIG: WebAccessConfig = {
   },
 };
 
-export function loadConfig(): WebAccessConfig {
-  if (!existsSync(CONFIG_PATH)) return DEFAULT_CONFIG;
+export function loadConfig(file = configPath()): WebAccessConfig {
+  if (!existsSync(file)) return DEFAULT_CONFIG;
   let parsed: unknown;
   try {
-    parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+    parsed = JSON.parse(readFileSync(file, "utf-8"));
   } catch {
-    console.error(`[opl-webaccess] failed to parse ${CONFIG_PATH}, using defaults`);
+    console.error(`[opl-webaccess] failed to parse ${file}, using defaults`);
     return DEFAULT_CONFIG;
   }
   return normalizeConfig(parsed);
@@ -106,6 +132,9 @@ function normalizeConfig(parsed: unknown): WebAccessConfig {
     maxSearchQueries: record.maxSearchQueries as number | undefined,
     maxFetchUrls: record.maxFetchUrls as number | undefined,
     allowPrivateNetwork: record.allowPrivateNetwork === true,
+    allowLoopback: record.allowLoopback === true,
+    timeoutMs: record.timeoutMs as number | undefined,
+    maxResponseBytes: record.maxResponseBytes as number | undefined,
   };
 }