pi-web-access

Pi extension for web search and URL content extraction.

Tools

web_search

Search the web for information. Only registered when a search provider is configured with an API key.

Parameter	Type	Required	Description
query	string	yes	The search query
maxResults	number	no	Max results to return (default 5)
topic	"general" | "news"	no	Topic category
timeRange	"day" | "week" | "month" | "year"	no	Recency filter
includeDomains	string[]	no	Only include results from these domains
excludeDomains	string[]	no	Exclude results from these domains

web_fetch

Fetch a URL and process its content with a prompt. Only registered when fetch.provider or fetch.summary is configured.

Parameter	Type	Required	Description
url	string	yes	The URL to fetch
prompt	string	yes	What information to extract or summarize

x_search

Search X (Twitter) for posts and social media content. Only registered when xai provider has an API key.

Parameter	Type	Required	Description
query	string	yes	The search query on X
allowedHandles	string[]	no	Only include posts from these handles (max 20)
excludedHandles	string[]	no	Exclude posts from these handles (max 20)
fromDate	string	no	Start date (YYYY-MM-DD)
toDate	string	no	End date (YYYY-MM-DD)

Providers

Provider	Search	Fetch	X Search	Default Base URL	Env Var	Default Model
tavily	✓	✓	✗	https://api.tavily.com	TAVILY_API_KEY	-
kimi	✓	✗	✗	https://api.moonshot.cn/v1	MOONSHOT_API_KEY	kimi-k2.6
mimo	✓	✗	✗	https://api.xiaomimimo.com/v1	MIMO_API_KEY	mimo-v2.5-pro
zai	✓	✓	✗	https://api.z.ai	ZAI_API_KEY	-
gemini	✓	✗	✗	https://generativelanguage.googleapis.com/v1beta	GEMINI_API_KEY	gemini-2.5-flash
perplexity	✓	✓	✗	https://api.perplexity.ai	PERPLEXITY_API_KEY	openai/gpt-5.5
openrouter	✓	✓	✗	https://openrouter.ai/api/v1	OPENROUTER_API_KEY	openai/gpt-4.1-mini
xai	✓	✗	✓	https://api.x.ai/v1	XAI_API_KEY	grok-4.3
openai	✓	✗	✗	https://api.openai.com/v1	OPENAI_API_KEY	gpt-5.5
anthropic	✓	✓	✗	https://api.anthropic.com/v1	ANTHROPIC_API_KEY	claude-sonnet-4-6

Fetch fallback (when fetch.provider is not set): Jina Reader (r.jina.ai, free, JS-rendered) → local HTTP GET + turndown.

Configuration

Settings key: pi-web-access

{
  "pi-web-access": {
    "search": {
      "provider": "kimi"
    },
    "fetch": {
      "provider": "zai",
      "summary": {
        "provider": "amaster",
        "model": "deepseek-v4-flash"
      }
    },
    "providers": {
      "kimi": {
        "apiKey": "AMASTER_API_KEY",
        "baseUrl": "https://credits.amaster.ai/v1"
      },
      "zai": {
        "apiKey": "${ZAI_API_KEY}"
      },
      "xai": {
        "apiKey": "${XAI_API_KEY}"
      }
    }
  }
}

search

Field	Description
provider	Which provider to use for web search. Not set = auto-select first provider with key. No key at all = tool not registered.

fetch

Field	Description
provider	Which provider to use for URL fetching. Not set = Jina Reader → local fallback.
summary	Model config for summarizing fetched content.
summary.provider	Model provider name (resolved via pi model registry).
summary.model	Model id.

If neither fetch.provider nor fetch.summary is configured, web_fetch is not registered.

providers

Per-provider configuration. Each provider supports:

Field	Description
apiKey	API key. Supports ${ENV_VAR} syntax.
baseUrl	Override the default API endpoint.
model	Override the default model.
headers	Extra headers merged into every request.

Environment variables serve as fallbacks when apiKey is not set in config.

Architecture

Each provider implements the WebProvider interface via BaseProvider:

// providers/base.ts
export interface WebProvider {
  readonly id: BuiltInProviderId;
  search(params: SearchParams, provider: ResolvedProvider): Promise<SearchResponse>;
  fetch(url: string, provider: ResolvedProvider): Promise<FetchResponse>;
}

export abstract class BaseProvider implements WebProvider {
  abstract readonly id: BuiltInProviderId;
  // Default implementations throw "not supported"
  async search(...) { throw new Error(`${this.id} does not support web_search.`); }
  async fetch(...) { throw new Error(`${this.id} does not support web_fetch.`); }
}

Providers only override methods they support. Provider-specific capabilities (like XaiProvider.xsearch) are exposed as additional methods on the class.

Tool Registration Rules

• web_search — registered when a search provider has an API key.
• web_fetch — registered when fetch.provider or fetch.summary is configured.
• x_search — registered when xai provider has an API key.
• If none are configured, the extension loads silently with no tools registered.

Install

pi install npm:@amaster.ai/pi-web-access

Development

pnpm build      # tsc -b
pnpm typecheck  # tsc -b --pretty false
pnpm test       # vitest run src