@herbertgao/pi-extensions 2026.8.14 → 2026.8.15

package/node_modules/pi-mcp-adapter/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.31.0] - 2026-08-28
+
+### Highlights
+- MCP Apps-aware servers can now recognize Pi as a UI-capable host and expose interactive resources.
+- UI capability advertising works consistently across legacy and modern MCP protocol negotiation.
+- Manual OAuth callback completion now supports HTTPS redirect URLs for pre-registered clients.
+
+### Added
+
+- Pi now advertises MCP Apps UI support with the `io.modelcontextprotocol/ui` extension capability, so compatible servers can expose UI resources. Thanks to [@VikashLoomba](https://github.com/VikashLoomba) for #465.
+
+### Fixed
+
+- Pre-registered OAuth clients can use HTTPS callback URLs through manual callback completion instead of being rejected as non-local redirects. Thanks to [@jluisrojas](https://github.com/jluisrojas) for PR #464.
+
 ## [2.30.0] - 2026-08-28
 
 ### Highlights

package/node_modules/pi-mcp-adapter/README.md

@@ -272,7 +272,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `oauth.clientId` | Pre-registered OAuth client ID. MCP 2026 prefers pre-registered clients or Client ID Metadata Documents; this adapter falls back to Dynamic Client Registration when the ID is omitted and the server supports it. |
 | `oauth.clientSecret` | OAuth client secret for confidential clients; a value beginning with `!` runs a command when OAuth authenticates, while `!!` escapes a literal leading `!` |
 | `oauth.scope` | Requested OAuth scopes |
-| `oauth.redirectUri` | Exact localhost redirect URI for browser OAuth, including port and path, for providers that pre-register callbacks |
+| `oauth.redirectUri` | Exact redirect URI for browser OAuth. Local `http://` loopback URIs need an explicit port. Pre-registered `https://` callbacks use manual completion by pasting the full callback URL. |
 | `oauth.clientName` | Client display name advertised during Dynamic Client Registration fallback |
 | `oauth.clientUri` | Client homepage URI advertised during Dynamic Client Registration fallback. Defaults to `piConfig.clientUri` from the host's manifest when set, and is omitted rather than guessed under a rebranded host |
 | `oauth.logoUri` | Client logo URL advertised during Dynamic Client Registration fallback (RFC 7591 `logo_uri`). Must be an absolute `http(s)` URL — consent screens fetch it server-side, so local paths render nothing. Omitted from the registration request when unset |
@@ -304,7 +304,7 @@ Use `"2026-07-28"` to pin that revision. Pinning has no legacy or SSE fallback a
 
 The stable SDK handles era-specific request envelopes, result decoding, list-changed subscriptions, cancellation, and multi-round-trip sampling/elicitation. The adapter keeps strict OAuth issuer validation in every mode. Adapter-level roots support, standard MCP logging presentation, and configuration/UI for protocol cache hints are not yet implemented.
 
-For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port.
+For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port. A configured `https://` callback runs in manual mode because the adapter cannot receive a callback on another host. After authorization, copy the full callback URL from the browser address bar and paste it into `/mcp-auth` or `mcp({ action: "auth-complete", ... })`.
 
 If an internal authorization server publishes mismatched OAuth metadata and cannot be fixed immediately, set `oauth.skipIssuerMetadataValidation: true` on that server only. This is security-weakening. It disables the RFC 8414 issuer echo check and should not be used for public or untrusted servers.
 

package/node_modules/pi-mcp-adapter/commands.ts

@@ -297,7 +297,7 @@ export async function authenticateServer(
         return ui.input(
           `Complete ${serverName} OAuth\n\n` +
             `${terminalHyperlink("Open authorization page", authorizationUrl)}\n${authorizationUrl}\n\n` +
-            "Approve access, then paste the full localhost callback URL below.",
+            "Approve access, then paste the full callback URL from the browser address bar below.",
           undefined,
           { signal: inputSignal },
         );

package/node_modules/pi-mcp-adapter/dist/types.d.ts

@@ -228,7 +228,7 @@ export interface OAuthConfig {
     scope?: string;
     /** Extra authorization URL parameters for provider-specific extensions. Flow-owned parameters cannot be overridden. */
     authorizationParams?: Record<string, string>;
-    /** Exact authorization-code redirect URI for pre-registered clients */
+    /** Exact authorization-code redirect URI for pre-registered clients. HTTPS redirects use manual callback URL completion. */
     redirectUri?: string;
     /** Client display name for dynamic registration */
     clientName?: string;

package/node_modules/pi-mcp-adapter/mcp-auth-flow.ts

@@ -75,6 +75,8 @@ type PendingAuth = {
   authProvider: McpOAuthProvider
   serverUrl: string
   authorizationUrl: string
+  manualRedirect: boolean
+  manualCompletionController?: AbortController
   discovery: AuthDiscovery
   authStorageOptions: AuthStorageOptions
 }
@@ -307,7 +309,11 @@ async function probeAuthDiscovery(serverUrl: string, definition?: ServerEntry, s
   }
 }
 
-function parseOAuthRedirectUri(redirectUri: string): { port: number; callbackHost: string; callbackPath: string } {
+type OAuthRedirectTarget =
+  | { mode: "local"; port: number; callbackHost: string; callbackPath: string }
+  | { mode: "manual" }
+
+function parseOAuthRedirectUri(redirectUri: string): OAuthRedirectTarget {
   let url: URL
   try {
     url = new URL(redirectUri)
@@ -315,12 +321,6 @@ function parseOAuthRedirectUri(redirectUri: string): { port: number; callbackHos
     throw new Error(`Invalid OAuth redirectUri: ${redirectUri}`, { cause: error })
   }
 
-  const hostname = url.hostname.toLowerCase()
-  const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1"
-  if (url.protocol !== "http:" || !isLocalhost) {
-    throw new Error("OAuth redirectUri must be an http:// localhost or loopback URI")
-  }
-
   if (url.username || url.password) {
     throw new Error("OAuth redirectUri must not include username or password")
   }
@@ -329,17 +329,32 @@ function parseOAuthRedirectUri(redirectUri: string): { port: number; callbackHos
     throw new Error("OAuth redirectUri must not include a fragment")
   }
 
+  const hostname = url.hostname.toLowerCase()
+  const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1"
+  if (url.port) {
+    const parsedPort = Number.parseInt(url.port, 10)
+    if (!Number.isInteger(parsedPort) || parsedPort <= 0 || parsedPort > 65535) {
+      throw new Error("OAuth redirectUri port must be a positive numeric port")
+    }
+  }
+  if (url.protocol === "https:" && !isLocalhost) {
+    return { mode: "manual" }
+  }
+  if (url.protocol !== "http:" || !isLocalhost) {
+    throw new Error("OAuth redirectUri must be an https:// URI or an http:// localhost or loopback URI")
+  }
+
   if (!url.port) {
-    throw new Error("OAuth redirectUri must include an explicit numeric port")
+    throw new Error("OAuth localhost redirectUri must include an explicit numeric port")
   }
 
   const port = Number.parseInt(url.port, 10)
   if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new Error("OAuth redirectUri must include an explicit numeric port")
+    throw new Error("OAuth localhost redirectUri must include an explicit numeric port")
   }
 
   const callbackHost = hostname === "[::1]" ? "::1" : hostname
-  return { port, callbackHost, callbackPath: url.pathname }
+  return { mode: "local", port, callbackHost, callbackPath: url.pathname }
 }
 
 /**
@@ -393,25 +408,30 @@ export async function startAuth(
     return { authorizationUrl: existingPendingAuth.authorizationUrl }
   }
 
-  const redirectCallback = config.redirectUri !== undefined ? parseOAuthRedirectUri(config.redirectUri) : undefined
+  const redirectTarget = config.redirectUri !== undefined ? parseOAuthRedirectUri(config.redirectUri) : undefined
+  const manualRedirect = redirectTarget?.mode === "manual"
   const oauthState = generateState()
 
-  try {
-    await ensureCallbackServer({
-      strictPort: Boolean(config.clientId) || config.redirectUri !== undefined,
-      oauthState,
-      reserveState: true,
-      ...(redirectCallback ? { port: redirectCallback.port, callbackHost: redirectCallback.callbackHost, callbackPath: redirectCallback.callbackPath } : {}),
-    })
-    throwIfAborted(signal)
-  } catch (error) {
-    releaseCallbackServer(oauthState)
+  if (!manualRedirect) {
     try {
-      await cleanupAndReleaseCallbackServerIfIdle(() => clearOAuthState(serverName, authStorageOptions))
-    } catch (cleanupError) {
-      throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed")
+      await ensureCallbackServer({
+        strictPort: Boolean(config.clientId) || config.redirectUri !== undefined,
+        oauthState,
+        reserveState: true,
+        ...(redirectTarget?.mode === "local"
+          ? { port: redirectTarget.port, callbackHost: redirectTarget.callbackHost, callbackPath: redirectTarget.callbackPath }
+          : {}),
+      })
+      throwIfAborted(signal)
+    } catch (error) {
+      releaseCallbackServer(oauthState)
+      try {
+        await cleanupAndReleaseCallbackServerIfIdle(() => clearOAuthState(serverName, authStorageOptions))
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed")
+      }
+      throw error
     }
-    throw error
   }
 
   let capturedUrl: URL | undefined
@@ -455,7 +475,16 @@ export async function startAuth(
     if (!capturedUrl) {
       throw new UnauthorizedError("OAuth authorization URL was not provided")
     }
-    await setPendingAuth(runtime, serverName, { serverName, authProvider, serverUrl, authorizationUrl: capturedUrl.toString(), discovery, authStorageOptions }, oauthState, signal, generation)
+    await setPendingAuth(runtime, serverName, {
+      serverName,
+      authProvider,
+      serverUrl,
+      authorizationUrl: capturedUrl.toString(),
+      manualRedirect,
+      ...(manualRedirect ? { manualCompletionController: new AbortController() } : {}),
+      discovery,
+      authStorageOptions,
+    }, oauthState, signal, generation)
     return { authorizationUrl: capturedUrl.toString() }
   } catch (error) {
     authProvider.deactivate()
@@ -484,7 +513,13 @@ async function setPendingAuth(
   state.pendingAuths.set(key, pendingAuth)
   state.pendingAuthStates.set(key, oauthState)
   const cleanupTimer = setTimeout(() => {
-    void clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, pendingAuth.authStorageOptions).catch(error => {
+    void clearPendingAuthAndReleaseIfIdle(
+      runtime,
+      serverName,
+      oauthState,
+      pendingAuth.authStorageOptions,
+      new Error("OAuth authorization timeout - authorization took too long"),
+    ).catch(error => {
       console.error(`MCP Auth: Timed-out flow cleanup failed: ${formatTerminalError(error)}`)
     })
   }, MANUAL_AUTH_TIMEOUT_MS)
@@ -492,7 +527,13 @@ async function setPendingAuth(
   state.pendingAuthCleanupTimers.set(key, cleanupTimer)
 }
 
-async function clearPendingAuth(runtime: McpOAuthRuntime, serverName: string, oauthState?: string, fallbackStorageOptions: AuthStorageOptions = {}): Promise<void> {
+async function clearPendingAuth(
+  runtime: McpOAuthRuntime,
+  serverName: string,
+  oauthState?: string,
+  fallbackStorageOptions: AuthStorageOptions = {},
+  reason: Error = new Error("Authorization cancelled"),
+): Promise<void> {
   const state = getRuntimeState(runtime)
   const key = getPendingAuthKey(serverName, fallbackStorageOptions)
   const pendingAuth = state.pendingAuths.get(key)
@@ -506,6 +547,7 @@ async function clearPendingAuth(runtime: McpOAuthRuntime, serverName: string, oa
     state.pendingAuthCleanupTimers.delete(key)
   }
 
+  pendingAuth?.manualCompletionController?.abort(reason)
   pendingAuth?.authProvider.deactivate()
   state.pendingAuths.delete(key)
   state.pendingAuthStates.delete(key)
@@ -524,9 +566,10 @@ async function clearPendingAuthAndReleaseIfIdle(
   serverName: string,
   oauthState: string | undefined,
   fallbackStorageOptions: AuthStorageOptions = {},
+  reason?: Error,
 ): Promise<void> {
   await cleanupAndReleaseCallbackServerIfIdle(
-    () => clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions),
+    () => clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions, reason),
   )
 }
 
@@ -629,6 +672,19 @@ type AuthorizationResponse = {
   source: "callback" | "manual"
 }
 
+function waitForManualCompletionCancellation(signal: AbortSignal): Promise<AuthorizationCodeInput> {
+  return new Promise((_, reject) => {
+    const rejectFromSignal = () => {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("Authorization cancelled"))
+    }
+    if (signal.aborted) {
+      rejectFromSignal()
+      return
+    }
+    signal.addEventListener("abort", rejectFromSignal, { once: true })
+  })
+}
+
 /**
  * Wait for either the localhost callback or a manually pasted redirect URL.
  * The manual input prompt is dismissed as soon as either path finishes.
@@ -686,7 +742,11 @@ export async function completeAuthFromInput(
   throwIfAborted(signal)
   const key = getPendingAuthKey(serverName, fallbackAuthStorageOptions)
   const oauthState = runtimeState.pendingAuthStates.get(key)
+  const pendingAuth = runtimeState.pendingAuths.get(key)
   throwIfAborted(signal)
+  if (pendingAuth?.manualRedirect && !getSearchParamsFromInput(input.trim())) {
+    throw new Error("Paste the full OAuth callback URL, including its code and state parameters")
+  }
   const parsed = parseAuthorizationRedirectInput(input, oauthState)
   return completeAuth(serverName, parsed, options)
 }
@@ -805,15 +865,28 @@ export async function authenticate(
     try {
       // Get the state that was already generated and stored in startAuth().
       // Keep this lookup and its abort check inside the cleanup boundary because
-      // startAuth has already reserved callback state at this point.
+      // startAuth already owns the pending flow at this point.
       oauthState = runtimeState.pendingAuthStates.get(getPendingAuthKey(serverName, authStorageOptions))
       throwIfAborted(signal)
       if (!oauthState) {
         throw new Error("OAuth state not found - this should not happen")
       }
 
-      // Register the callback BEFORE opening the browser.
-      const callbackPromise = waitForCallback(oauthState)
+      const pendingAuth = runtimeState.pendingAuths.get(getPendingAuthKey(serverName, authStorageOptions))
+      if (!pendingAuth) {
+        throw new Error(`No pending OAuth flow for server: ${serverName}`)
+      }
+      if (pendingAuth.manualRedirect && !options.onAuthorizationInput) {
+        throw new Error(
+          `OAuth for ${serverName} uses a remote redirect URI. Complete it with auth-start/auth-complete or /mcp-auth.`,
+        )
+      }
+
+      // Register the localhost callback before opening the browser. Remote
+      // pre-registered callbacks are completed by pasting their full URL.
+      const callbackPromise: Promise<AuthorizationCodeInput> = pendingAuth.manualRedirect
+        ? waitForManualCompletionCancellation(pendingAuth.manualCompletionController!.signal)
+        : waitForCallback(oauthState)
       void callbackPromise.catch(() => {})
 
       // Open browser. Always surface the URL first so remote/headless users can copy it

package/node_modules/pi-mcp-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",

package/node_modules/pi-mcp-adapter/proxy-modes.ts

@@ -143,22 +143,30 @@ function getAuthFailedMessage(state: McpExtensionState, serverName: string, mess
   return `OAuth authentication failed for "${serverName}": ${message}. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`;
 }
 
-function getRedirectPort(authorizationUrl: string): number | undefined {
+function getRedirectDetails(authorizationUrl: string): { port?: number; remote: boolean } {
   try {
     const redirectUri = new URL(authorizationUrl).searchParams.get("redirect_uri");
-    if (!redirectUri) return undefined;
-    const port = Number.parseInt(new URL(redirectUri).port, 10);
-    return Number.isInteger(port) ? port : undefined;
+    if (!redirectUri) return { remote: false };
+    const redirect = new URL(redirectUri);
+    const hostname = redirect.hostname.toLowerCase();
+    const local = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+    const port = Number.parseInt(redirect.port, 10);
+    return {
+      ...(Number.isInteger(port) ? { port } : {}),
+      remote: !local,
+    };
   } catch {
-    return undefined;
+    return { remote: false };
   }
 }
 
 function formatManualAuthInstructions(serverName: string, authorizationUrl: string): string {
-  const port = getRedirectPort(authorizationUrl);
-  const portNote = port
-    ? `\nThe redirect URL will use local port ${port}. On a remote server it is expected for that localhost page to fail locally; copy the address bar URL anyway.`
-    : "";
+  const redirect = getRedirectDetails(authorizationUrl);
+  const redirectNote = redirect.remote
+    ? "The provider uses a pre-registered HTTPS callback. Copy its full URL from the browser address bar, even if the destination page reports an error."
+    : redirect.port
+      ? `The redirect URL will use local port ${redirect.port}. On a remote server it is expected for that localhost page to fail locally; copy the address bar URL anyway.`
+      : "";
 
   return [
     `MCP OAuth required for "${serverName}".`,
@@ -167,11 +175,13 @@ function formatManualAuthInstructions(serverName: string, authorizationUrl: stri
     "",
     authorizationUrl,
     "",
-    "After approving, copy the full redirected localhost URL from your browser address bar and send it back with:",
+    "After approving, copy the full callback URL from your browser address bar and send it back with:",
     `mcp({ action: "auth-complete", server: "${serverName}", args: { redirectUrl: "PASTE_REDIRECT_URL_HERE" } })`,
     "",
-    'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`. JSON-string args remain supported.',
-    portNote.trimEnd(),
+    redirect.remote
+      ? "Remote HTTPS callbacks must include the full callback URL so the OAuth state can be checked. JSON-string args remain supported."
+      : 'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`. JSON-string args remain supported.',
+    redirectNote,
   ].filter(Boolean).join("\n");
 }
 

package/node_modules/pi-mcp-adapter/server-manager.ts

@@ -34,6 +34,7 @@ import {
 import { resolveNpxBinary } from "./npx-resolver.ts";
 import { createJsonSchemaValidator } from "./json-schema-validator.ts";
 import { logger } from "./logger.ts";
+import { RESOURCE_MIME_TYPE } from "./ui-app-bridge-helpers.ts";
 import { McpOAuthProvider } from "./mcp-oauth-provider.ts";
 import { extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import { invalidateAuthEntryCache, type AuthStorageOptions } from "./mcp-auth.ts";
@@ -725,6 +726,11 @@ export class McpServerManager {
 
   private buildClientCapabilities() {
     return {
+      extensions: {
+        "io.modelcontextprotocol/ui": {
+          mimeTypes: [RESOURCE_MIME_TYPE],
+        },
+      },
       ...(this.samplingConfig ? { sampling: {} } : {}),
       ...(this.elicitationConfig
         ? {

package/node_modules/pi-mcp-adapter/types.ts

@@ -378,7 +378,7 @@ export interface OAuthConfig {
   scope?: string;
   /** Extra authorization URL parameters for provider-specific extensions. Flow-owned parameters cannot be overridden. */
   authorizationParams?: Record<string, string>;
-  /** Exact authorization-code redirect URI for pre-registered clients */
+  /** Exact authorization-code redirect URI for pre-registered clients. HTTPS redirects use manual callback URL completion. */
   redirectUri?: string;
   /** Client display name for dynamic registration */
   clientName?: string;

package/node_modules/pi-web-access/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-08-28
+
+### Highlights
+
+- `fetch_content` now lets you tune direct HTTP and Jina Reader timeouts from config.
+- Answer mode can use a configured default model while still allowing per-call overrides.
+- HTML fallback parsing is quieter for pages with relative canonical links.
+- GitHub repository fetching is safer when more than one Pi process is running.
+
+### Added
+
+- Added opt-in `fetch.timeout` configuration in seconds for the direct HTTP and Jina Reader `fetch_content` paths, with per-call timeout overrides taking precedence. Thanks to [@linuxtextadventurer](https://github.com/linuxtextadventurer) for PR #327.
+- Added opt-in `fetch.answerProvider` and `fetch.answerModel` defaults for `fetch_content` answer mode, with per-call `answerModel` overrides taking precedence. Thanks to [@linuxtextadventurer](https://github.com/linuxtextadventurer) for PR #328.
+
+### Fixed
+
+- Set the Defuddle fallback document URL before parsing pages with relative canonical links, preventing `ERR_INVALID_URL` warnings. Thanks to [@bin115885](https://github.com/bin115885) for issue #322.
+- Isolated GitHub clone workdirs per extension runtime so cleanup in one process cannot delete another process's clone. Thanks to [@MDGChamomile](https://github.com/MDGChamomile) for PR #323.
+
+
 ## [0.26.0] - 2026-08-28
 
 ### Highlights

package/node_modules/pi-web-access/README.md

@@ -159,11 +159,15 @@ fetch_content({ url: "https://example.com/diagram.png" })
 | `url` / `urls` | Single URL/path or multiple URLs |
 | `prompt` | Question for video analysis, or the page-local question required by `mode: "answer"` |
 | `mode` | `readable` (default), `raw` for exact textual HTTP bodies, or `answer` for a grounded answer from fetched content |
-| `answerModel` | Optional `provider/model-id` override for answer mode; defaults to the current enabled Pi model |
+| `answerModel` | Optional `provider/model-id` override for answer mode; defaults to the configured `fetch.answerProvider` + `fetch.answerModel` pair, or the current enabled Pi model when no pair is configured |
 | `timestamp` | Extract frame(s) — single (`"23:41"`), range (`"23:41-25:00"`), or seconds (`"85"`) |
 | `frames` | Number of frames to extract (max 12) |
 | `forceClone` | Clone GitHub repos that exceed the 350MB size threshold |
 
+For a standing answer-mode model, set both `fetch.answerProvider` and `fetch.answerModel` in `web-search.json`; a per-call `answerModel` takes precedence. Configured answer defaults are opt-in and can send fetched page text to a different provider/model, which may change privacy and cost behavior.
+
+Thanks to [@linuxtextadventurer](https://github.com/linuxtextadventurer) for PR #328.
+
 ### get_search_content
 
 Retrieve stored content from previous searches or fetches. Fetched URL content is stored in full in a private `web-search-cache` directory under the Pi config directory, not in the session JSONL. This includes `fetch_content` answer mode, which stores the original page content. The cache has a one-hour lifetime and fixed limits of 128 entries and 128 MiB; when either limit is reached, the oldest entries are removed first. On macOS and Linux the cache directory and files are kept at permissions `0700` and `0600`, respectively. Use `findText` to locate bounded matching passages without paging through a large page, or use `offset` and `limit` to retrieve slices intentionally.
@@ -403,6 +407,11 @@ Config defaults to `~/.pi/web-search.json`, or `web-search.json` under `PI_CODIN
     "providers": ["http", "firecrawl", "jina", "tinyfish", "search1api", "querit", "kagi", "ollama", "parallel", "brightdata", "gemini"],
     "allowRemoteHostedProviders": false
   },
+  "fetch": {
+    "timeout": 30,
+    "answerProvider": "openai",
+    "answerModel": "gpt-5.6"
+  },
   "webSearch": {
     "enabled": true
   },
@@ -502,6 +511,10 @@ Set `braveBaseUrl`, `exaBaseUrl`, or `tavilyBaseUrl` to route those providers th
 
 `fetchContent.domainPolicy` is an optional hostname allow/deny policy for `fetch_content` target URLs. It is off when omitted. Each bare hostname matches itself and its subdomains; `deny` wins when a hostname matches both lists. The policy is checked before HTTP(S) target handling and before each redirect followed by this extension's own fetch path. Local file paths and non-HTTP sources are not subject to this policy. It is an additional restriction: the existing SSRF guard still blocks private and internal destinations. Remote extraction services can still perform their own DNS, redirects, and egress after this extension preflights the submitted target URL, so third-party hosted HTTP(S) fallbacks stay disabled unless `fetchRouting.allowRemoteHostedProviders` is enabled for separately isolated provider deployments.
 
+`fetch.timeout` is an optional positive finite number of seconds for direct HTTP fetches and the Jina Reader fallback. When omitted, both use a 30-second budget. Fractional values are supported and rounded up to at least 1 millisecond; values that cannot be converted to a finite safe integer delay from 1 through Node's 2,147,483,647 ms timer maximum are rejected. An invalid declared value fails closed with an error naming `web-search.json`. An internal/per-call `timeoutMs` override takes precedence over this setting. Other remote extraction fallbacks keep their own documented budgets.
+
+`fetch.answerProvider` and `fetch.answerModel` are an optional pair that selects the model used by `fetch_content` answer mode when no per-call `answerModel` is supplied. Both values must be non-empty strings and must identify an enabled text-capable model available in Pi's model registry; invalid or partial configuration fails closed. This is opt-in: answering with the configured provider/model can send fetched page text outside the current session and may incur that provider's costs. A per-call `answerModel` override is resolved first and remains usable even when these configured defaults are malformed.
+
 Set `searxngBaseUrl` or `SEARXNG_BASE_URL` to use a self-hosted SearXNG JSON API. A configured endpoint is preferred first in `auto` mode for local/private search. Its base URL and redirects remain subject to the SSRF guard; add only the narrowest self-hosted range to `ssrf.allowRanges` when it resolves to a private or synthetic range. Optional `searxngHeaders` merges extra HTTP headers into each SearXNG request (string values only; invalid header names are ignored), which is useful for reverse-proxy or Zero Trust auth such as Cloudflare Access service tokens (`CF-Access-Client-Id` / `CF-Access-Client-Secret`). Configured headers override the default `Accept: application/json` when the same name is supplied. Thanks to Marcos A. Núñez (@marnunez) for PR #107 and Avinash Kanaujiya (@avinashkanaujiya) for issue #105.
 
 **DuckDuckGo.** DuckDuckGo HTML search is keyless and explicit-only. Select it with `provider: "duckduckgo"` or place it in `searchRouting`; it is never chosen by `auto` and never participates in `provider: "all"`. Domain filters are enforced locally after DuckDuckGo redirect URLs are decoded. `recencyFilter` is not guaranteed because the HTML endpoint has no documented stable time parameter. A 200 page with no parseable results is reported as an invalid response, so routing can continue when `fallbackOn` includes `"invalid-response"`.
@@ -868,7 +881,7 @@ Values use the same format as pi keybindings (e.g. `ctrl+s`, `ctrl+shift+s`, `al
 
 Set `"enabled": false` under `tools`, `commands`, `image`, or `pdf` to disable that feature. Tool-specific settings override the legacy `webSearch.enabled` shorthand; without an override, it still disables `web_search` and `source_check`. `image.enabled: false` blocks direct image fetches and video frame extraction, and prevents video thumbnails. `pdf.enabled: false` blocks PDF extraction. For GitHub specifically, `githubClone.enabled: false` only skips clone/API specialization, and `githubPrIssue.enabled: false` only skips PR/issue specialization; neither setting unregisters `fetch_content` or blocks generic URL extraction. Pi restart is required for tool and command registration changes.
 
-Rate limits: Perplexity is capped at 10 requests/minute (client-side). Jina Search, TinyFish, Search1API, and Searchinfinity apply the plan limits documented by their APIs. Querit Search and Contents subscriptions are independent. Content fetches run 3 concurrent with a 30s timeout for the direct HTTP fetch of each URL. Remote extraction fallbacks carry their own budgets and are not covered by that number: Jina Reader 30s, Firecrawl 60s, Kagi Extract 60s, Ollama Web Fetch 60s, Bright Data Web Unlocker 60s, TinyFish up to 150s, Gemini 120s, Datalab 120s (capped at 300s, rate-limited to 25 requests/minute on the free tier). `pdf.maxSizeMB` defaults to 20 and is capped at 50. `pdf.maxPages` defaults to 100 and limits every PDF provider to the first N pages.
+Rate limits: Perplexity is capped at 10 requests/minute (client-side). Jina Search, TinyFish, Search1API, and Searchinfinity apply the plan limits documented by their APIs. Querit Search and Contents subscriptions are independent. Content fetches run 3 concurrent; direct HTTP fetches and Jina Reader use a 30s timeout by default, configurable together with `fetch.timeout` in seconds. Remote extraction fallbacks carry their own budgets and are not covered by that setting: Firecrawl 60s, Kagi Extract 60s, Ollama Web Fetch 60s, Bright Data Web Unlocker 60s, TinyFish up to 150s, Gemini 120s, Datalab 120s (capped at 300s, rate-limited to 25 requests/minute on the free tier). `pdf.maxSizeMB` defaults to 20 and is capped at 50. `pdf.maxPages` defaults to 100 and limits every PDF provider to the first N pages.
 
 ## Limitations
 

package/node_modules/pi-web-access/extract.ts

@@ -31,12 +31,45 @@ import { getBrowserCookiesForHosts, getLastBrowserCookieDiagnostic } from "./chr
 import { sanitizeInlineDataUris } from "./data-uri-sanitize.ts";
 
 const DEFAULT_TIMEOUT_MS = 30000;
+const MAX_CONFIGURED_TIMEOUT_MS = 2_147_483_647;
 const CONCURRENT_LIMIT = 3;
+const WEB_SEARCH_CONFIG_PATH = getWebSearchConfigPath();
+
+function loadFetchTimeoutMs(): number {
+	if (!existsSync(WEB_SEARCH_CONFIG_PATH)) return DEFAULT_TIMEOUT_MS;
+
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(WEB_SEARCH_CONFIG_PATH, "utf-8"));
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to parse ${WEB_SEARCH_CONFIG_PATH}: ${message}`);
+	}
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new Error(`Invalid config in ${WEB_SEARCH_CONFIG_PATH}: expected a JSON object`);
+	}
+
+	const fetchConfig = (raw as Record<string, unknown>).fetch;
+	if (fetchConfig === undefined) return DEFAULT_TIMEOUT_MS;
+	if (!fetchConfig || typeof fetchConfig !== "object" || Array.isArray(fetchConfig)) {
+		throw new Error(`fetch in ${WEB_SEARCH_CONFIG_PATH} must be an object`);
+	}
+
+	const value = (fetchConfig as Record<string, unknown>).timeout;
+	if (value === undefined) return DEFAULT_TIMEOUT_MS;
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+		throw new Error(`Invalid fetch.timeout in ${WEB_SEARCH_CONFIG_PATH}: expected a positive finite number of seconds, got ${JSON.stringify(value)}`);
+	}
+	const timeoutMs = Math.ceil(value * 1000);
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_CONFIGURED_TIMEOUT_MS) {
+		throw new Error(`Invalid fetch.timeout in ${WEB_SEARCH_CONFIG_PATH}: converted timeout must be a finite safe integer from 1 through ${MAX_CONFIGURED_TIMEOUT_MS} milliseconds`);
+	}
+	return Math.max(1, timeoutMs);
+}
 
 const NON_RECOVERABLE_ERRORS = ["Unsupported content type", "Response too large", "PDF extraction is disabled", "Image fetching is disabled"];
 const MIN_USEFUL_CONTENT = 500;
 const SUPPORTED_IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
-const WEB_SEARCH_CONFIG_PATH = getWebSearchConfigPath();
 const FETCH_PROVIDERS = ["http", "firecrawl", "jina", "tinyfish", "search1api", "querit", "kagi", "ollama", "parallel", "parallel-mcp", "brightdata", "gemini"] as const;
 type FetchProvider = typeof FETCH_PROVIDERS[number];
 type FetchRouting = { providers: FetchProvider[]; allowRemoteHostedProviders: boolean };
@@ -51,6 +84,10 @@ function isDefuddleConsoleError(args: Parameters<typeof console.error>): boolean
 async function extractWithDefuddle(text: string, url: string): Promise<{ title: string; content: string } | null> {
 	const { Defuddle } = await import("defuddle/node");
 	const { document } = parseHTML(text);
+	Object.defineProperty(document, "location", {
+		value: new URL(url),
+		configurable: true,
+	});
 	let processingError: unknown;
 	const originalConsoleError = console.error;
 	console.error = (...args) => {
@@ -298,11 +335,16 @@ export interface ExtractOptions {
 	lookup?: Lookup;
 }
 
+/** Resolve the direct HTTP/Jina fetch budget, with a per-call override taking precedence. */
+export function resolveFetchTimeoutMs(options?: Pick<ExtractOptions, "timeoutMs">): number {
+	return options?.timeoutMs ?? loadFetchTimeoutMs();
+}
+
 const JINA_READER_BASE = "https://r.jina.ai/";
-const JINA_TIMEOUT_MS = 30000;
 
 async function extractWithJinaReader(
 	url: string,
+	timeoutMs: number,
 	signal?: AbortSignal,
 	lookup?: Lookup,
 ): Promise<ExtractedContent | null> {
@@ -325,7 +367,7 @@ async function extractWithJinaReader(
 				"X-No-Cache": "true",
 			},
 			signal: AbortSignal.any([
-				AbortSignal.timeout(JINA_TIMEOUT_MS),
+				AbortSignal.timeout(timeoutMs),
 				...(signal ? [signal] : []),
 			]),
 		});
@@ -480,18 +522,14 @@ export async function extractContent(
 		}
 	}
 
-	if (options?.authFetchProfile) {
+	if (options?.authFetchProfile || options?.mode === "raw") {
 		try {
-			return await extractViaHttp(url, signal, options);
+			return await extractViaHttp(url, resolveFetchTimeoutMs(options), signal, options);
 		} catch (err) {
 			return { url, title: "", content: "", error: errorMessage(err) };
 		}
 	}
 
-	if (options?.mode === "raw") {
-		return extractViaHttp(url, signal, options);
-	}
-
 	if (options?.frames || options?.timestamp) {
 		const disabled = imageGateError();
 		if (disabled) return { url, title: "", content: "", error: disabled };
@@ -703,6 +741,13 @@ export async function extractContent(
 
 	if (signal?.aborted) return abortedResult(url);
 
+	let fetchTimeoutMs: number;
+	try {
+		fetchTimeoutMs = resolveFetchTimeoutMs(options);
+	} catch (err) {
+		return { url, title: "", content: "", error: errorMessage(err) };
+	}
+
 	let fetchRouting: FetchRouting;
 	try {
 		fetchRouting = loadFetchRouting();
@@ -731,7 +776,7 @@ export async function extractContent(
 		? { ...httpResult, error: message }
 		: { url, title: "", content: "", error: message };
 	const runHttpProvider = async (): Promise<ExtractedContent | null> => {
-		const { declaredLinks: discoveredLinks = [], ...result } = await extractViaHttp(url, signal, options);
+		const { declaredLinks: discoveredLinks = [], ...result } = await extractViaHttp(url, fetchTimeoutMs, signal, options);
 		httpResult = result;
 		declaredLinks = discoveredLinks;
 		if (signal?.aborted) return abortedResult(url);
@@ -786,7 +831,7 @@ export async function extractContent(
 		}
 
 		if (provider === "jina") {
-			const jinaResult = await extractWithJinaReader(url, signal, options?.lookup);
+			const jinaResult = await extractWithJinaReader(url, fetchTimeoutMs, signal, options?.lookup);
 			if (jinaResult) return withDeclaredLinks(jinaResult);
 			continue;
 		}
@@ -1066,10 +1111,10 @@ function responseSizeLimitError(maxBytes: number): Error {
 
 async function extractViaHttp(
 	url: string,
+	timeoutMs: number,
 	signal?: AbortSignal,
 	options?: ExtractOptions,
 ): Promise<HttpExtractedContent> {
-	const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const activityId = activityMonitor.logStart({ type: "fetch", url });
 
 	const controller = new AbortController();