# Changelog

## 5.0.0 - 2026-11-03

### Upgrade notes

- Requires Pi 1.5.0+ and Node.js 22.19.0+.
- Codemode callers now receive structured objects instead of Markdown strings. Update scripts to use search `results`, Context7 `text`, read `ok`/`content` (or `savePath`/`preview`), and cowork `content`/`details`. Direct tool text remains available.
- Replaces CloakBrowser with stock Playwright Chromium (`playwright` ^1.64.1). `/reload` every Pi agent and close/reopen cowork or browser-rendered read sessions after upgrading.
- Default cowork profile is a **fresh** directory at `~/.pi/web-cowork/profile`. Screenshots go to `~/.pi/web-cowork/shots`. Explicit `cowork.userDataDir` is honored unchanged. Older CloakBrowser profiles (for example under `~/.cloakbrowser/`) are never inspected, copied, or deleted. Log in again on the new default. To keep a previous explicit path, leave it; to use the new default, change that setting yourself.
- `postinstall` runs `playwright install chromium`. If scripts were skipped: `npx playwright install chromium`. `npx playwright install-deps chromium` is advisory OS-library help only (Debian/Ubuntu); this package does not install system packages.
- Stock Chromium has no stealth or fingerprint-seed guarantees. Challenge and anti-bot results can differ from CloakBrowser.

### Changed

- Typecheck against the actual Pi SDK instead of ambient substitutes. Declare the extension changelog path for Pi's update notices.
- Search/cowork configuration supplies registration defaults without overwriting CLI, resumed-session, or branch tool selections. The active `web_fetch` alias no longer repeats `web_read` prompt guidelines.
- Browser cleanup follows Pi's shutdown lifecycle instead of accumulating process listeners. Owner shutdown/reload/session replacement closes the shared browser; guests only disconnect.
- Validate numeric tool arguments with JSON Schema integer bounds. Search and Context7 advertise read-only permission hints; file saves and browser interactions retain conservative hints.
- `web_read` browser rendering and `web_cowork` persistent sessions use Playwright Chromium instead of CloakBrowser. Runtime imports come from `playwright`.

### Removed

- CloakBrowser dependency/installer, stealth-engine integration, fingerprint-seed persistence, launch update checks, and Cloak-specific console filtering and binary-license notes. Existing browser binaries and profile data are not deleted.

### Added

- Inline PNG screenshots alongside saved paths, with image blocks available to codemode scripts.
- Structured search, read, and Context7 outputs for codemode. Saved-page results contain only metadata and a bounded preview, not the full saved page.
- Compact tool renderers with elapsed time, configured expand-key hints, reusable components, and expanded text.

### Fixed

- Allow `web_cowork` open/navigate to `about:blank` without an SSRF error; other URL protections remain unchanged.
- Show full read/fetch URLs in compact tool rows, including query strings and fragments, while masking credentials and obvious secret parameters.
- Discover project-specific Context7 configuration at session start without repeatedly enabling an already registered tool.
- Serialize read saves through Pi's per-file mutation queue and normalize an optional leading `@` on save paths.

## 4.0.2 - 2026-10-22

### Changed

- Upgrade CloakBrowser to 0.6.3. Node.js now requires `^20.19.0 || >=22.12.0`; older Node 20/22 releases and Node 21 are no longer supported.
- Persistent cowork profiles now keep CloakBrowser's fingerprint seed across launches. Reload Pi and close/reopen cowork after upgrading; no profile reset is needed.
- Bump playwright-core, impit, linkedom, and tsx within existing ranges.

### Security

- Prevent caller-supplied `Authorization`, `Cookie`, and `Proxy-Authorization` headers from returning after an HTTP redirect or meta-refresh crosses origins, including mixed chains and redirects back to the original origin. Same-origin requests retain their headers.
- Upgrade undici to 7.30.1 (high-severity HTTP client issues, including DoS and cookie handling).

### Fixed

- Surface Wayback availability lookup failures, including HTTP 429 rate limits, in read results, saved extracts/summaries, and original network errors instead of silently treating them as archive misses.

## 4.0.1 - 2026-09-28

### Fixed

- Declare host-provided `typebox` in `peerDependencies` (`*`) instead of `dependencies`, matching Pi 0.99 package rules.

### Added

- Cowork JS dialog handling and result reports. Default dismiss; `beforeunload` accepts during `open`/`navigate`/`close`. Per-call `dialog` overrides the policy, and `dialogText` answers accepted prompts.
- Native dropdown selection through `action=select` with a target plus `text` and/or `value`; `pageIndex` still switches tabs. Snapshots include selected label/value and option metadata.
- Automatic iframe refs in interactive snapshots, with indented child controls actionable by ref. Role/name/CSS fallbacks, content snapshots, and `evaluate` remain main-frame only.

## 4.0.0 - 2026-09-27

### Upgrade (required)

- **Reload every Pi agent** (`/reload` or restart) and **close/reopen any cowork browser** started before this version. Older windows have no discovery file and cannot be attached.
- Existing search/read config keeps working. No `web.json` change is required unless you want browser extensions.
- To load extensions, add `cowork.extensionPaths` in **global `~/.pi/agent/web.json` only** (absolute or `~/` paths, Manifest V3 `manifest.json`, max 8). Project `.pi/web.json` and legacy extension configs cannot enable this. Close/reopen cowork after changing it; `/reload` first if you just updated the package.

### Breaking

- Cowork again opens an ephemeral **unauthenticated** loopback CDP port (`127.0.0.1`, port 0) and writes owner-only `.pi-cowork-session.json` in the profile so other agents can attach. **v3.0.0 removed that port.** Use only on a trusted local machine; never forward or expose it.
- `action=close` closes the shared browser for **every** agent on that profile. Guest process cleanup disconnects; it does not close the owner's window. Keep the launching agent running.
- Interactive refs are agent-local (`data-cowork-ref-<uuid>`). Do not pass `@eN` between agents. Run `pages` → `select` → `snapshot` in each agent. Emulation labels are per-agent.

### Added

- Agents sharing `cowork.userDataDir` auto-attach to the live browser (`status`, `pages`, `open`, or any page action). Different profiles stay separate. The launching agent owns lifetime and URL guarding.
- Opt-in cowork loading of trusted local Manifest V3 extensions via global `cowork.extensionPaths`. Loaded extension-worker IDs may fetch their own `chrome-extension:` resources; website workers stay blocked and normal URL checks stay on.

### Changed

- `/web` status reports the shared browser if another agent already launched it.

## 3.3.0 - 2026-09-22

### Added

- `web_read` extracts PDF text (pdf-parse). Scanned/OCR PDFs still placeholder.
- Dead links (404/410 or network failure) retry via Wayback (`archive=auto`, default). Snapshot age is labeled. `archive=never` skips.
- Stable read errors: `[error] <code>` plus `next_action` for `wall.challenge`, `guard.ssrf`, `deadline.hit`.
- CloakBrowser challenge cookies are reused on later HTTP fetches for that host (session jar, cleared on session start).
- `stitch=true` follows same-origin `rel=next` for up to three extra pages.

### Fixed

- Cowork screenshots retain mobile emulation instead of restoring Playwright's stale desktop viewport. Device labels are per-tab; open/emulate include observed CSS viewport dimensions.
- Cowork defaults to headless on Linux without display variables. Explicit headed requests fail early with guidance to use headless or provide a display server.

### Changed

- Footer chips are one line below the editor (not `setStatus` rows). Empty leftover keys are deleted so they cannot become blank footer lines. Reads, cowork, and used services share that single chip.

## 3.2.1 - 2026-09-17

### Added

- `web_cowork` `action=emulate` switches Chrome device mode (`device=mobile` / `device=desktop`). Mobile uses Pixel 7 metrics with `mobile:true`, touch, and a mobile UA/client hints — not a window resize. Optional `device` on `open`. Default remains desktop.

### Fixed

- Compact `web_search` results keep full URLs instead of truncating them at 50 characters.

## 3.2.0 - 2026-09-14

### Added

- `/web` command toggles `web_search` and `web_cowork` on or off for the current session (`/web [search|cowork] [on|off]`, bare target flips, `/web` reports status).
- `search.enabled` and `cowork.enabled` in `web.json` set the per-session default for both tools; both default to enabled.

## 3.1.0 - 2026-08-31

### Changed

- Auto `web_read` keeps a per-host climb floor for the session after a confirmed block (status or `cf-mitigated`), so later reads of that host skip HTTP.
- Residual challenge pages after the top tier are omitted; the tool returns a blocked notice instead of challenge HTML.
- Session start clears host floors so a new Pi session starts from the fast HTTP tier.

## 3.0.0 - 2026-08-30

### Added

- Cowork developer actions for console, network, JavaScript, screenshots, accessibility, tabs, and raw page/browser CDP.
- Configurable headless cowork sessions; external desktop window remains default. Headless applies only when creating a session.
- `allowPrivateHosts` in global `~/.pi/agent/web.json` for trusted loopback/LAN names. Project config cannot widen it.
- Hop-by-hop redirect checks in `web_read` fetch paths and a Playwright request guard for browser navigation.

### Changed

- IPv4-mapped, IPv4-compatible, and NAT64 IPv6 literals are classified as their embedded IPv4 address for SSRF checks.
- Cross-origin redirects drop `Authorization`, `Cookie`, and `Proxy-Authorization`.
- CDP denylist now covers Target attach/close, `Page.crash`, and `Browser.crashGpuProcess`, case-insensitively. Cookie dumps and `Runtime.evaluate` remain available on the persistent profile.

### Removed

- **Breaking:** Herdr pane rendering, `cowork.herdr` config, `verify:herdr`, and the unauthenticated loopback CDP endpoint.

## 2.0.0 - 2026-08-27

### Added

- `web_cowork` now returns bounded, viewport-first refs after browser actions.
- Added narrow `batch` form filling with one optional final click.
- `wait` now returns user notes and cancellation state.

### Changed

- Context7 output is capped at 12k characters.

### Removed

- **Breaking:** Retired the `web_fetch_and_index` alias; use `web_read` or `web_fetch`.

## 1.3.0

### Added

- Optional Herdr rendering for `web_cowork`. The agent controls Chromium with the existing cowork actions while the user watches or takes control in a Herdr pane.
- In-pane tabs, navigation controls, URL entry, page zoom, mouse input, keyboard input, and scrolling.
- `npm run verify:herdr` for graphics, browser, and interaction checks.
- Configuration for split direction, focus, browser zoom, diagnostics, capture scale, frame skipping, fallback behavior, and the CDP port.

### Changed

- `web_cowork` uses the same persistent browser profile in desktop and Herdr modes.
- If Herdr graphics are unavailable, cowork reports the cause and opens a desktop window by default.
- The README now presents Herdr integration near the top and links to the full setup guide.
- Requires Node.js 20.18.1+ (`undici` 7).
- Cowork navigation allows `file://` for user-driven local pages.

### Fixed

- Sanitized page titles and URLs before rendering them in the terminal.
- Added viewer readiness checks, pane cleanup, bounded network waits, and frame backpressure.
- Preserved terminal input order and fixed standalone Escape handling.

## 1.2.1

### Changed

- Published through npm trusted publishing with OIDC.

## 1.2.0

### Added

- Context7 documentation search.
- Query-ranked web extraction and improved search results.

## 1.1.1

### Fixed

- GitHub issues and pull requests now fetch through the REST API.

## 1.1.0

### Added

- `web.env` secret loading, read metadata, and alternate extraction paths.

## 1.0.0

### Added

- Initial `web_search`, `web_read`, and `web_cowork` release.