vera-web-tools

Purpose

Provide network-backed information retrieval tools for Pi: web search, page extraction, documentation lookup, academic search, and document parsing.

Non-goals

• local workspace search (rg / fd)
• owning session UI, banners, or thinking shortcuts; search/read/parse logic stays non-UI, while tool-frame chrome is currently borrowed from vera-theme
• compaction, prompt rules, or system prompt mutation
• provider compatibility shims

Registered tools

• web_search — aggregated multi-engine web search
• web_read — readable page extraction
• docs_search — library documentation lookup via Context7
• academic_search — scholarly search via OpenAlex
• document_parse — document parsing via MinerU (remote URL or local file path); writes Markdown to a required output_path, optionally one file per page (paginate)

Config / auth

This package reads credentials from agent/auth.json and matching environment variables.

Supported keys:

• exa / EXA_API_KEY
• brave / BRAVE_API_KEY
• metaso / METASO_API_KEY
• jina / JINA_API_KEY
• tavily / TAVILY_API_KEY
• context7 / CONTEXT7_API_KEY
• openalex / OPENALEX_API_KEY
• mineru / MINERU_API_KEY

External dependencies

• outbound network access
• upstream service availability and rate limits
• a valid URL for web_read; a URL or readable local file path for document_parse

Internal structure

• src/index.ts — Pi extension entrypoint
• src/tools/ — tool definitions and renderers; renderers currently use vera-theme's kylinFrameForCall / kylinFrameForResult tool-frame chrome helpers from the sibling package
• src/clients/ — upstream client wrappers; search deduplication uses src/shared/render.ts URL normalization
• src/shared/ — package-local auth, error, http, render, and helper utilities
• src/types.ts — shared detail/result types

Boundary notes

• The package owns network search/read/docs/academic/parse behavior, not session UI; tool-frame chrome is a cross-package borrow from vera-theme rather than a local UI framework.
• src/shared/render.ts is also part of client-side normalization: clients/search.ts uses normalizeUrl when de-duplicating provider results.

Smoke

• npm run smoke
• npm run smoke:offline
• npm run smoke:strict-network
• from project root: node scripts/smoke-all.mjs

Debugging

1. Run the package smoke in offline mode first to verify registration and renderer stability.
2. Re-run without --offline to test live upstream calls.
3. If a tool fails, separate missing-key paths from upstream/network failures before changing code.
4. For renderer regressions, inspect document_parse first; it has explicit regression coverage.

Loaded through agent/settings.json as ./packages/vera-web-tools.