@openlines/opl-pi-sht 0.2.12 → 0.3.0

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,
   };
 }
 

package/extensions/opl-webaccess/extract.ts

@@ -2,11 +2,16 @@ import { Readability } from "@mozilla/readability";
 import { parseHTML } from "linkedom";
 import TurndownService from "turndown";
 import { extractPdfBuffer } from "./pdf.js";
-import { errorMessage, isAbortError, isPdfUrl, isPdfContentType, assertHttpUrl, type HttpUrlOptions } from "./utils.js";
+import { errorMessage, isAbortError, isPdfUrl, isPdfContentType, resolveSafeHostUrl, type HttpUrlOptions } from "./utils.js";
+import { pinnedFetch, isRedirectStatus, type PinnedResponse } from "./http.js";
 import type { ExtractedContent } from "./types.js";
 
 const CONCURRENT_LIMIT = 3;
-const MAX_FETCH_BYTES = 10 * 1024 * 1024; // 10 MB response cap
+const MAX_FETCH_BYTES = 10 * 1024 * 1024; // default response cap, overridable by maxResponseBytes
+const FETCH_HEADERS = {
+  "User-Agent": "Mozilla/5.0 (compatible; pi-web-access/1.0)",
+  Accept: "text/html,application/xhtml+xml,application/pdf,*/*",
+};
 const FETCH_TIMEOUT_MS = 30_000;
 const MAX_REDIRECTS = 5;
 /** Ceiling on the number of URLs a single fetch_content call may include. */
@@ -17,33 +22,6 @@ const td = new TurndownService({
   codeBlockStyle: "fenced",
 });
 
-/** Read a response body into bytes, aborting past maxBytes (guards memory against huge payloads). */
-async function readBufferCapped(response: Response, maxBytes: number): Promise<ArrayBuffer> {
-  const declared = Number(response.headers.get("content-length") ?? "0");
-  if (declared > maxBytes) throw new Error(`Response too large (${declared} bytes)`);
-  const reader = response.body?.getReader();
-  if (!reader) return await response.arrayBuffer();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-  for (;;) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    total += value.byteLength;
-    if (total > maxBytes) {
-      await reader.cancel().catch(() => {});
-      throw new Error(`Response exceeds ${maxBytes} byte limit`);
-    }
-    chunks.push(value);
-  }
-  const merged = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    merged.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return merged.buffer;
-}
-
 export async function fetchAllContent(
   urls: string[],
   signal?: AbortSignal,
@@ -62,36 +40,47 @@ export async function fetchAllContent(
 }
 
 /**
- * Fetch with redirects followed manually so each hop is re-validated. The native
- * `redirect: "follow"` would let a public URL bounce to a private/link-local host
- * past the `assertHttpUrl` check.
+ * Fetch with redirects followed manually so each hop is re-validated, re-resolved **and
+ * re-pinned**. The native `redirect: "follow"` would let a public URL bounce to a private or
+ * link-local host past the guard; a hostname that merely reads public can answer with an
+ * internal address; and a record with a short TTL can answer one address at check time and
+ * another at connect time. So every hop goes through resolveSafeHostUrl and the socket is
+ * pinned to the addresses that hop approved.
  */
 async function fetchWithRedirectValidation(
   url: string,
   fetchSignal: AbortSignal,
   opts: HttpUrlOptions
-): Promise<Response> {
-  let current = assertHttpUrl(url, opts);
-  const headers = {
-    "User-Agent": "Mozilla/5.0 (compatible; pi-web-access/1.0)",
-    Accept: "text/html,application/xhtml+xml,application/pdf,*/*",
-  };
+): Promise<PinnedResponse> {
+  const maxResponseBytes = opts.maxResponseBytes ?? MAX_FETCH_BYTES;
+  let current = url;
   for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
-    const response = await fetch(current, { signal: fetchSignal, headers, redirect: "manual" });
-    if (response.status < 300 || response.status >= 400) return response;
+    const target = await resolveSafeHostUrl(current, { ...opts, signal: fetchSignal });
+    const request = {
+      signal: fetchSignal,
+      headers: FETCH_HEADERS,
+      maxResponseBytes,
+      timeoutMs: opts.timeoutMs,
+    };
+    const response = await (opts.transport ?? pinnedFetch)(target, request);
+    if (!isRedirectStatus(response.status)) return response;
     const location = response.headers.get("location");
     if (!location) return response; // 3xx without a Location: treat as final
-    await response.body?.cancel().catch(() => {});
-    current = assertHttpUrl(new URL(location, current).href, opts);
+    current = new URL(location, target.url).href;
   }
   throw new Error(`Too many redirects (max ${MAX_REDIRECTS})`);
 }
 
 async function fetchOne(url: string, signal?: AbortSignal, opts: HttpUrlOptions = {}): Promise<ExtractedContent> {
+  const deadline = new AbortController();
+  const budget = opts.timeoutMs ?? FETCH_TIMEOUT_MS;
+  // Own this timer across all hops. Bun cancels AbortSignal.timeout when its last listener
+  // is removed, so transport cleanup between literal-IP hops must not cancel the deadline.
+  const timer = setTimeout(() => deadline.abort(), budget);
   try {
     const fetchSignal = signal
-      ? AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
-      : AbortSignal.timeout(FETCH_TIMEOUT_MS);
+      ? AbortSignal.any([signal, deadline.signal])
+      : deadline.signal;
     const response = await fetchWithRedirectValidation(url, fetchSignal, opts);
 
     if (!response.ok) {
@@ -101,15 +90,14 @@ async function fetchOne(url: string, signal?: AbortSignal, opts: HttpUrlOptions
     const contentType = response.headers.get("content-type") ?? "";
 
     if (isPdfUrl(url) || isPdfContentType(contentType)) {
-      const buffer = await readBufferCapped(response, MAX_FETCH_BYTES);
-      const content = await extractPdfBuffer(buffer);
+      const content = await extractPdfBuffer(response.body);
       return { url, title: url, content, error: null };
     }
 
     const isHtml =
       contentType.includes("text/html") || contentType.includes("application/xhtml");
 
-    const body = new TextDecoder().decode(await readBufferCapped(response, MAX_FETCH_BYTES));
+    const body = response.text();
 
     if (!isHtml) {
       // Plain text, markdown, JSON, etc. — return as-is
@@ -137,5 +125,7 @@ async function fetchOne(url: string, signal?: AbortSignal, opts: HttpUrlOptions
   } catch (err) {
     if (isAbortError(err)) return { url, title: "", content: "", error: "Aborted" };
     return { url, title: "", content: "", error: errorMessage(err) };
+  } finally {
+    clearTimeout(timer);
   }
 }

package/extensions/opl-webaccess/http.ts

@@ -0,0 +1,259 @@
+/**
+ * Pinned HTTP transport for model-supplied URLs.
+ *
+ * The guard in utils.ts classifies every DNS answer for a hostname. Handing only the *name* to a
+ * generic client throws that work away: the client resolves again, and a record with a one-second
+ * TTL can answer a public address at check time and 127.0.0.1 or 169.254.169.254 at connect time.
+ * This module takes the validated set and dials it, so the socket cannot be re-steered.
+ *
+ * Node's global fetch has no resolver hook, so the transport is node:http/node:https with a
+ * `lookup` that never reaches DNS. The hostname still drives TLS (`servername`) and the `Host`
+ * header, so certificate validation and virtual hosting behave as they would without pinning.
+ */
+import http from "node:http";
+import https from "node:https";
+import type { LookupAddress, LookupOptions } from "node:dns";
+import { createGunzip, createInflate, createBrotliDecompress } from "node:zlib";
+import type { Transform } from "node:stream";
+import type { SafeHttpTarget } from "./utils.ts";
+
+/** Keeps site responses identical to the fetch path this replaces. */
+const USER_AGENT = "Mozilla/5.0 (compatible; opl-pi-sht/webaccess)";
+
+export interface PinnedFetchOptions {
+  method?: string;
+  headers?: Record<string, string>;
+  /** Caller's abort signal; aborting destroys the socket and rejects with an AbortError. */
+  signal?: AbortSignal;
+  /** Socket inactivity deadline (ms). 0 or unset means no transport-side deadline. */
+  timeoutMs?: number;
+  /** Hard ceiling on both received and decoded body bytes. 0 or unset means unlimited. */
+  maxResponseBytes?: number;
+}
+
+export interface PinnedResponse {
+  status: number;
+  ok: boolean;
+  headers: { get(name: string): string | null };
+  body: Buffer;
+  text(): string;
+}
+
+function isIpv6(address: string): boolean {
+  return address.includes(":");
+}
+
+function familyOf(address: string): 4 | 6 {
+  return isIpv6(address) ? 6 : 4;
+}
+
+function abortError(): Error & { name: string } {
+  return Object.assign(new Error("The operation was aborted"), { name: "AbortError" });
+}
+
+/**
+ * A resolver that answers only from the addresses the guard approved. It ignores the name it is
+ * asked about - the point is that nothing downstream gets to choose a different answer.
+ */
+export function pinnedLookup(addresses: string[]) {
+  return (
+    hostname: string,
+    options: LookupOptions,
+    callback: (err: Error | null, address?: string | LookupAddress[], family?: number) => void,
+  ): void => {
+    if (options && options.all) {
+      callback(null, addresses.map((address) => ({ address, family: familyOf(address) })));
+      return;
+    }
+    const asked = options && typeof options.family === "string" ? (options.family === "IPv6" ? 6 : 4) : options?.family;
+    const want = asked === 6 ? 6 : asked === 4 ? 4 : 0;
+    const hit = want ? addresses.find((address) => familyOf(address) === want) ?? addresses[0] : addresses[0];
+    if (!hit) {
+      callback(new Error(`No pinned address available for "${hostname}"`));
+      return;
+    }
+    callback(null, hit, familyOf(hit));
+  };
+}
+
+/** The request options for one pinned hop. Exported so the contract is testable without a socket. */
+export function buildRequestOptions(
+  target: SafeHttpTarget,
+  opts: PinnedFetchOptions = {},
+): http.RequestOptions & { servername?: string } {
+  const parsed = new URL(target.url);
+  const tls = parsed.protocol === "https:";
+  const port = parsed.port ? Number(parsed.port) : tls ? 443 : 80;
+  const headers: Record<string, string> = {
+    "user-agent": USER_AGENT,
+    accept: "*/*",
+    // Prefer identity, but decode supported encodings if the server compresses anyway.
+    "accept-encoding": "identity",
+    ...opts.headers,
+  };
+  headers.host = parsed.host; // keeps the port and IPv6 brackets exactly as the URL spells them
+  const options: http.RequestOptions & { servername?: string } = {
+    protocol: parsed.protocol,
+    method: (opts.method ?? "GET").toUpperCase(),
+    host: target.host,
+    hostname: target.host,
+    port,
+    path: `${parsed.pathname}${parsed.search}`,
+    headers,
+    agent: pinnedAgent(target.url),
+    // Node declares this hook as two overloads (`all` or not); the pin answers both, so the widening
+    // happens here instead of pretending it is only one of them.
+    lookup: pinnedLookup(target.addresses) as http.RequestOptions["lookup"],
+  };
+  if (tls) options.servername = target.host; // certificate validation stays bound to the name
+  return options;
+}
+
+/**
+ * A fresh agent per request. Pooling is off (`keepAlive: false`) and, because nothing is shared,
+ * a socket established under one hop's approved address can never be reused by a later request
+ * whose guard approved a different one.
+ */
+export function pinnedAgent(url: string): http.Agent | https.Agent {
+  return url.startsWith("https:") ? new https.Agent({ keepAlive: false }) : new http.Agent({ keepAlive: false });
+}
+
+/** Only these status codes redirect a GET; other 3xx responses are final. */
+export function isRedirectStatus(status: number): boolean {
+  return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
+}
+
+/**
+ * Fetch one already-validated target. Redirects are returned, never followed: the caller re-runs the
+ * guard and re-pins for each hop, which is the only place a new host can appear.
+ */
+export function pinnedFetch(target: SafeHttpTarget, opts: PinnedFetchOptions = {}): Promise<PinnedResponse> {
+  const options = buildRequestOptions(target, opts);
+  const transport = new URL(target.url).protocol === "https:" ? https : http;
+  const limit = opts.maxResponseBytes && opts.maxResponseBytes > 0 ? opts.maxResponseBytes : 0;
+
+  return new Promise<PinnedResponse>((resolve, reject) => {
+    let settled = false;
+    let incoming: http.IncomingMessage | undefined;
+    let decoder: Transform | undefined;
+    let inactivityTimer: ReturnType<typeof setTimeout> | undefined;
+    const abort = () => fail(abortError());
+    const resetTimeout = () => {
+      if (!opts.timeoutMs || opts.timeoutMs <= 0) return;
+      clearTimeout(inactivityTimer);
+      inactivityTimer = setTimeout(() => fail(new Error(`Request to ${target.host} timed out after ${opts.timeoutMs} ms`)), opts.timeoutMs);
+    };
+    const cleanup = () => {
+      opts.signal?.removeEventListener("abort", abort);
+      clearTimeout(inactivityTimer);
+      decoder?.destroy();
+      incoming?.destroy();
+      request.destroy();
+      if (options.agent && typeof options.agent === "object") options.agent.destroy();
+    };
+    const fail = (err: Error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(err);
+    };
+    const request = transport.request(options, (response) => {
+      incoming = response;
+      response.on("error", fail);
+      response.on("aborted", () => fail(new Error(`Response from ${target.host} ended before its body completed`)));
+      const status = response.statusCode ?? 0;
+      const headers = {
+        get(name: string): string | null {
+          const value = response.headers[name.toLowerCase()];
+          if (Array.isArray(value)) return value.join(", ");
+          return value === undefined ? null : String(value);
+        },
+      };
+      const finish = (body: Buffer) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve({ status, ok: status >= 200 && status < 300, headers, body, text: () => body.toString("utf8") });
+      };
+      // A redirect body is irrelevant. Close this socket and let the caller validate the next hop.
+      if (isRedirectStatus(status) && headers.get("location")) {
+        finish(Buffer.alloc(0));
+        return;
+      }
+      // These responses cannot carry a body, even if they advertise its size or encoding.
+      if (options.method === "HEAD" || status === 204 || status === 304) {
+        finish(Buffer.alloc(0));
+        return;
+      }
+      const declared = Number(response.headers["content-length"]);
+      if (limit > 0 && Number.isFinite(declared) && declared > limit) {
+        fail(new Error(`Response from ${target.host} is ${declared} bytes, over the ${limit} byte limit (set maxResponseBytes to raise it)`));
+        return;
+      }
+      const encoding = (headers.get("content-encoding") ?? "identity").trim().toLowerCase();
+      switch (encoding) {
+        case "identity": break;
+        case "gzip": decoder = createGunzip(); break;
+        case "deflate": decoder = createInflate(); break;
+        case "br": decoder = createBrotliDecompress(); break;
+        default:
+          fail(new Error(`Unsupported content encoding "${encoding}" from ${target.host}`));
+          return;
+      }
+      const chunks: Buffer[] = [];
+      let received = 0;
+      let decoded = 0;
+      const collect = (chunk: Buffer) => {
+        if (settled) return;
+        decoded += chunk.length;
+        if (limit > 0 && decoded > limit) {
+          fail(new Error(`Decoded response from ${target.host} exceeds the ${limit} byte limit (set maxResponseBytes to raise it)`));
+          return;
+        }
+        chunks.push(chunk);
+      };
+      response.on("data", (chunk: Buffer) => {
+        if (settled) return;
+        resetTimeout();
+        received += chunk.length;
+        if (limit > 0 && received > limit) {
+          fail(new Error(`Response from ${target.host} exceeds the ${limit} byte limit (set maxResponseBytes to raise it)`));
+        }
+      });
+      const bodyStream = decoder ?? response;
+      bodyStream.on("data", collect);
+      bodyStream.on("end", () => finish(Buffer.concat(chunks)));
+      if (decoder) {
+        decoder.on("error", (err: Error) => fail(new Error(`Cannot decompress ${encoding} response from ${target.host}: ${err.message}`, { cause: err })));
+        response.pipe(decoder);
+      }
+    });
+    request.on("error", (err) => {
+      const failure = err as Error & { code?: string };
+      if (failure.name === "AbortError" || /byte limit|timed out/.test(failure.message)) {
+        fail(failure);
+        return;
+      }
+      // Name the address the guard approved: "connect ECONNREFUSED api.internal:80" on its own hides
+      // which validated answer the socket was pinned to, which is the first thing triage needs.
+      fail(
+        Object.assign(new Error(`${target.host} -> ${target.addresses.join(", ")}: ${failure.message}`), {
+          code: failure.code,
+          cause: failure,
+        }),
+      );
+    });
+    // Both the deadline and the caller's abort own their error objects. Handing destroy() an error
+    // reaches the rejection reliably on Node; on Bun the socket comes back as ECONNRESET or a bare
+    // "Connection closed", which would hide the reason from the model and from these tests.
+    resetTimeout();
+    if (opts.signal) {
+      if (opts.signal.aborted) {
+        fail(abortError());
+        return;
+      }
+      opts.signal.addEventListener("abort", abort, { once: true });
+    }
+    request.end();
+  });
+}

package/extensions/opl-webaccess/index.ts

@@ -10,13 +10,14 @@ import {
   restoreFromSession,
 } from "./storage.js";
 import { truncate, errorMessage, paginateContent, continuationNotice } from "./utils.js";
-import { loadConfig, resolveCaps } from "./config.js";
+import { loadConfig, resolveCaps, resolveTimeoutMs, resolveMaxResponseBytes } from "./config.js";
 import type { StoredData } from "./types.js";
 
 export default function (pi: ExtensionAPI) {
   const config = loadConfig();
   const caps = resolveCaps(config);
   const allowPrivateNetwork = config.allowPrivateNetwork === true;
+  const allowLoopback = config.allowLoopback === true;
 
   // Note shown to the model when the per-call URL/query cap drops some inputs.
   const skippedNote = (dropped: number, limit: number, singular: string, plural: string) =>
@@ -57,11 +58,11 @@ export default function (pi: ExtensionAPI) {
       try {
         // allSettled so one provider's throw (non-JSON body, missing key) cannot
         // discard the sibling queries' results.
-        const settled = await Promise.allSettled(queryList.map((q) => searchWeb(q, signal)));
+        const settled = await Promise.allSettled(queryList.map((q) => searchWeb(q, signal, config)));
         results = settled.map((s, i) =>
           s.status === "fulfilled"
             ? s.value
-            : { query: queryList[i], answer: "", results: [], error: errorMessage(s.reason) }
+            : { query: queryList[i] ?? `query #${i}`, answer: "", results: [], error: errorMessage(s.reason) } // index-aligned by allSettled; the fallback only names a list that cannot happen
         );
       } catch (err) {
         return {
@@ -121,7 +122,7 @@ export default function (pi: ExtensionAPI) {
       let results;
       const dropped = urlList.length > caps.maxFetchUrls ? urlList.length - caps.maxFetchUrls : 0;
       try {
-        results = await fetchAllContent(urlList, signal, { allowPrivateNetwork }, caps.maxFetchUrls);
+        results = await fetchAllContent(urlList, signal, { allowPrivateNetwork, allowLoopback, timeoutMs: resolveTimeoutMs(config), maxResponseBytes: resolveMaxResponseBytes(config) }, caps.maxFetchUrls);
       } catch (err) {
         return {
           content: [{ type: "text", text: `Error: ${errorMessage(err)}` }],
@@ -176,6 +177,11 @@ export default function (pi: ExtensionAPI) {
     }),
     async execute(_toolCallId, params) {
       const data = getResult(params.responseId);
+      // A restored entry is a capped preview until its spilled body is found; say so
+      // instead of handing the model a short answer that looks complete.
+      const staleNote = data?.truncated
+        ? "\n\n*Session copy: the cached full body is no longer on disk, so this excerpt is capped. Re-fetch to retrieve the rest.*"
+        : "";
       if (!data) {
         return {
           content: [
@@ -215,7 +221,7 @@ export default function (pi: ExtensionAPI) {
           caps.maxRetrievalChars,
         );
         return {
-          content: [{ type: "text", text: page.text + continuationNotice(page) }],
+          content: [{ type: "text", text: page.text + continuationNotice(page) + staleNote }],
           details: { responseId: params.responseId },
         };
       }
@@ -252,7 +258,7 @@ export default function (pi: ExtensionAPI) {
           caps.maxRetrievalChars,
         );
         return {
-          content: [{ type: "text", text: page.text + continuationNotice(page) }],
+          content: [{ type: "text", text: page.text + continuationNotice(page) + staleNote }],
           details: { responseId: params.responseId },
         };
       }

package/extensions/opl-webaccess/package.json

@@ -1,14 +1,9 @@
 {
   "name": "opl-webaccess",
-  "version": "1.0.0",
-  "description": "Web search and content extraction for pi. Search the web via Gemini AI, fetch and read web pages, and extract text from PDFs — all from within the agent.",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "version": "0.2.0",
+  "private": true,
+  "description": "Web search and content extraction for pi. Search the web via Gemini AI, fetch and read web pages, and extract text from PDFs \u2014 all from within the agent.",
+  "license": "MIT",
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",

package/extensions/opl-webaccess/pdf.ts

@@ -1,8 +1,8 @@
-import { errorMessage } from "./utils.js";
-
-export async function extractPdfBuffer(buffer: ArrayBuffer): Promise<string> {
+export async function extractPdfBuffer(buffer: ArrayBuffer | Uint8Array): Promise<string> {
   const { getDocumentProxy, extractText } = await import("unpdf");
-  const pdf = await getDocumentProxy(new Uint8Array(buffer));
+  // Buffer extends Uint8Array, but PDF.js rejects it; copy into the accepted type.
+  const bytes = new Uint8Array(buffer);
+  const pdf = await getDocumentProxy(bytes);
   const { text } = await extractText(pdf, { mergePages: true });
   return text ?? "";
 }

package/extensions/opl-webaccess/search.ts

@@ -1,4 +1,4 @@
-import { loadConfig, getApiKey } from "./config.js";
+import { loadConfig, getApiKey, resolveTimeoutMs, type WebAccessConfig } from "./config.js";
 import { searchGemini } from "./providers/gemini.js";
 import { searchTavily } from "./providers/tavily.js";
 import { searchDdgs } from "./providers/ddgs.js";
@@ -6,25 +6,36 @@ import { searchSearxng } from "./providers/searxng.js";
 import { searchExa } from "./providers/exa.js";
 import type { SearchQueryResult } from "./types.js";
 
+/**
+ * Run one search with the configured provider.
+ *
+ * `config` is passed in by callers that fan out over queries, so a multi-query
+ * call reads and parses the config file once instead of once per query. Every
+ * provider request gets a deadline: the agent signal alone can stay pending
+ * forever if a provider accepts the connection and never answers.
+ */
 export async function searchWeb(
   query: string,
-  signal?: AbortSignal
+  signal?: AbortSignal,
+  config: WebAccessConfig = loadConfig(),
 ): Promise<SearchQueryResult> {
-  const config = loadConfig();
   const providerName = config.provider;
   const providerCfg = config.providers?.[providerName] ?? {};
+  const timeoutMs = resolveTimeoutMs(config);
+  const deadline = AbortSignal.timeout(timeoutMs);
+  const tied = signal ? AbortSignal.any([signal, deadline]) : deadline;
 
   switch (providerName) {
     case "gemini":
-      return searchGemini(query, providerCfg, getApiKey(providerCfg), signal);
+      return searchGemini(query, providerCfg, getApiKey(providerCfg), tied);
     case "tavily":
-      return searchTavily(query, providerCfg, getApiKey(providerCfg), signal);
+      return searchTavily(query, providerCfg, getApiKey(providerCfg), tied);
     case "ddgs":
-      return searchDdgs(query, providerCfg, signal);
+      return searchDdgs(query, providerCfg, tied);
     case "searxng":
-      return searchSearxng(query, providerCfg, signal);
+      return searchSearxng(query, providerCfg, tied);
     case "exa":
-      return searchExa(query, providerCfg, getApiKey(providerCfg), signal);
+      return searchExa(query, providerCfg, getApiKey(providerCfg), tied);
     default:
       return {
         query,