# pi-web-agent

[![CI](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/demigodmode/pi-web-agent/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/@demigodmode/pi-web-agent)](https://www.npmjs.com/package/@demigodmode/pi-web-agent)
[![Docs](https://img.shields.io/badge/docs-github%20pages-blue)](https://demigodmode.github.io/pi-web-agent/)

`@demigodmode/pi-web-agent` is a Pi package for web access.

Most agent web tools blur search, fetch, browser rendering, and research into one vague thing. `pi-web-agent` exposes one public research tool, `web_explore`, and keeps search/fetch/headless work inside that bounded workflow.

The point is keeping the model-facing boundary simple: ask `web_explore` to research a question, and it handles direct links, discovery, HTTP reads, targeted browser rendering, source ranking, source-quality checks, and caveats internally.

That sounds obvious, but a lot of agent tooling gets fuzzy right there. This package is meant to be stricter about what it actually did and more willing to say when a read was not good enough to trust. Bot-check pages, narrow source sets, unreadable threads, and cautionary/conflicting evidence should show up as caveats instead of fake confidence.

## Install

Compatibility notice: current `pi-web-agent` requires Pi 0.74+ because Pi packages moved to the `@earendil-works/*` scope. Update Pi before updating this package. If you are on an older Pi version, stay on `@demigodmode/pi-web-agent@0.6.x` until Pi is updated.

```bash
pi install npm:@demigodmode/pi-web-agent
```

After installing, reload or restart Pi. Run `/web-agent` for the action menu, or `/web-agent doctor` to check whether the package loaded cleanly and which web backends are configured.

Headless rendering first tries a detectable Chromium-family browser: Chrome, Chromium, Edge, or Brave. If none is found, it falls back to Playwright-managed Chromium and still launches headless. Firefox/Safari-only systems can still use search and plain HTTP reads; browser-rendered fallback uses Chromium.

Later on, update installed packages with:

```bash
pi update --extensions
```

## Docs

Docs site:

- https://demigodmode.github.io/pi-web-agent/

Work on the docs locally:

```bash
npm run docs:dev
```

Build the docs:

```bash
npm run docs:build
```

## Presentation modes

`pi-web-agent` renders web tool output in one visible mode at a time:

- `compact` — short summary, default everywhere
- `preview` — slightly richer bounded view
- `verbose` — fuller bounded view

See the `v0.3.0` release notes for a before/after of the transcript cleanup:

- https://github.com/demigodmode/pi-web-agent/releases/tag/v0.3.0

## Settings

Primary UI:

```text
/web-agent settings
```

Helper commands:

```text
/web-agent doctor
/web-agent show
/web-agent changelog
/web-agent reset project
/web-agent reset global
/web-agent mode preview
/web-agent mode web_explore verbose
/web-agent mode web_explore inherit
```

Config files:

```text
Global:  ~/.pi/agent/extensions/pi-web-agent/config.json
Project: .pi/extensions/pi-web-agent/config.json
```

Precedence:

- built-in defaults
- global config
- project config

Project config overrides global config.

Example:

```json
{
  "presentation": {
    "defaultMode": "compact",
    "tools": {
      "web_explore": { "mode": "verbose" }
    }
  }
}
```

Backend config is also supported. Defaults remain DuckDuckGo search, plain HTTP fetch, and local-browser headless fallback with managed Chromium fallback configured. If you have a Brave Search or You.com API key, either can be selected as a hosted search backend while `web_explore` still handles page reading, ranking, and caveats itself.

Search backends: DuckDuckGo (default), SearXNG (self-hosted), Brave Search (hosted), You.com (hosted).

Backend settings can be changed from:

```text
/web-agent settings
```

Choose **Backends** to edit search/fetch providers, fallback behavior, and SearXNG or Firecrawl base URLs interactively. Brave Search uses `PI_WEB_AGENT_BRAVE_API_KEY`, You.com uses `YDC_API_KEY`, Exa uses `EXA_API_KEY`, and Tavily uses `TAVILY_API_KEY`. Firecrawl API keys should also stay in environment variables rather than being written into config files.

For the full backend config shape, including SearXNG, Brave, You.com, Firecrawl, and fallback behavior, see:

- https://demigodmode.github.io/pi-web-agent/self-hosted-backends

## Local development

```bash
npm install
npm test
npm run lint
npm run build
```

For local Pi work, this repo includes `.pi/extensions/pi-web-agent.ts`.

If Pi is already running, use `/reload` after changes.

## License

AGPL-3.0-only. See `LICENSE`.