@openlines/opl-pi-sht 0.2.6 → 0.2.8

package/README.md

@@ -17,7 +17,9 @@ A portable collection of various Pi coding agent extensions. Repository director
 <div align="center">
 
 >
-> ### v0.2.6 (24 Sept 2026) - **Post-compaction context estimate**: `opl-footer` keeps the context bar visible with explicitly approximate values until Pi reports fresh usage. <br/>see [CHANGELOG.md](CHANGELOG.md) for more details.
+> ### v0.2.8 (29 Sept 2026) - **SSRF and tool-safety hardening**: `opl-webaccess` and `opl-browser` block private/link-local hosts by default and cloud metadata always (localhost stays available for dev), fetch redirects are re-checked per hop, screenshots refuse to overwrite existing files, and `evaluate` no longer crashes on `undefined`. <br/>See [CHANGELOG.md](CHANGELOG.md) for details.
+>
+> `Current project state also marked 'SAFE' for pi v0.99.0 release`<br/>*confirmed this because I was literally typing to push the patches when I noticed the release notif*
 >
 
 </div>
@@ -84,7 +86,7 @@ Copy mode overwrites matching destinations. Link mode skips existing destination
 | [`opl-webaccess`](extensions/opl-webaccess/README.md)         | Search plus readable URL/PDF retrieval with session recovery.                                                                                                                                                                | `web_search`, `fetch_content`, `get_search_content`; `opl-webaccess.json`.                                     |
 | [`opl-browser`](extensions/opl-browser/README.md)             | Chromium automation via Playwright with structured extraction of rendered pages; single dispatcher tool replacing the chrome-devtools MCP.                                                                                   | `browser` (action-based); `opl-browser.json`.                                                                  |
 | [`opl-ctxtrim`](extensions/opl-ctxtrim/README.md)             | Trims verbose`ctx_*` tool-schema descriptions on outbound provider requests (~67% smaller schema, ~4,700-6,300 tokens/request). Built specifically for the [context-mode](https://github.com/mksglu/context-mode) extension. | No commands/tools; no config.                                                                                  |
-| [`opl-guardian`](extensions/opl-guardian/README.md)           | Drops malformed assistant tool calls before session persistence or replay, with project-local JSONL evidence. | No commands/tools; no config.                                                                                  |
+| [`opl-guardian`](extensions/opl-guardian/README.md)           | Configurable tool and session safety: dangerous-Bash confirmation, protected paths, destructive-session confirmation, and malformed-call filtering. | No commands/tools; `opl-guardian.json`. |
 | [`opl-todo`](extensions/opl-todo/README.md)                   | Branch-aware task tool, overlay, and task list.                                                                                                                                                                              | `todo`, `/todos`; `opl-todo.json`.                                                                             |
 | [`opl-questionnaire`](extensions/opl-questionnaire/README.md) | Interactive structured-choice tool.                                                                                                                                                                                          | `questionnaire`; no config.                                                                                    |
 | [`opl-input`](extensions/opl-input/README.md)                 | Configurable replacement editor - enhanced [pikit chat-input](https://github.com/adrianapan/pikit) (because pet is life, and configurable). ![pet](images/ss-input-pet.png)                                                                                   | No commands/tools;`opl-input.json`.                                                                            |
@@ -116,15 +118,15 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 - **`opl-modes`** chat and plan modes swap the active toolset for read-only lists and gate Bash to safe inspection patterns **per shell segment**, so `cat f && node -e '...'`, `cat x & rm -rf /tmp/x`, and `echo "$(node -e ...)"` can no longer ride the first command's allowance. Destructive checks still fire inside otherwise-safe commands (anchored to command position, so `du -sh` and `find . -name '*.sh'` stay allowed; `find -delete`, `find -fprint`, `git log --output`, `sort -o`, `npm audit fix`, `git clean`, `sudo`, and quote-obfuscated `r"m"`/`-del"ete"` are blocked; `env`/`printenv` are not safe-listed). The plan to execute lifecycle keeps exploration and mutation cleanly separated. Add custom modes (like below) for your workflow needs. Execute-mode auto-exit needs pi >= 0.87.0 (the `agent_before_settle` boundary).
 ![custom mode sample](images/ss-mode-custom.png)
 - `load_tools` activation is bounded by the current mode, so a read-only mode cannot be tricked into enabling a write-capable tool.
-- **`opl-guardian`** stops a malformed provider tool-call record from poisoning the session: it removes calls missing an ID or name before Pi persists or replays them, while preserving dropped records in `err/guardian.jsonl` for an upstream report.
+- **`opl-guardian`** combines configurable safety checks in one extension: it confirms dangerous Bash commands in the terminal or over RPC, blocks configured protected paths for file tools (including symlink targets), and confirms session clear/switch-with-pending-work/fork actions. Without a UI, configured dangerous commands and session actions block by default. It also removes malformed provider tool calls before persistence or replay and records incidents in `err/guardian.jsonl`. Protected-path Bash matching is literal best-effort, not shell sandboxing.
 
 
 ### Move through work faster
 
 - **`opl-init`** deterministically crawls and refines `AGENTS.md` with a single out-of-band model call (never a synthetic user message), writes it, and reloads context so the session runs on the new guide. A current fingerprint means zero model calls; mid-session invocations wait for the agent to settle instead of interrupting it. Needs pi >= 0.86.0.
 ![init](images/ss-init.png)
-- **`opl-browser`** gives full Chromium automation (navigate, snapshot, extract rendered-page markdown, interact, screenshot, console/network capture, evaluate) through a single tool, with handle+preview output for large results — navigation is http(s)-only and screenshots stay in the project directory.
-- **`opl-webaccess`** adds provider-backed search plus readable URL and PDF extraction, with session recovery of earlier results, an http(s)-only fetch, a 10 MB response cap, and a 30s timeout.
+- **`opl-browser`** gives full Chromium automation (navigate, snapshot, extract rendered-page markdown, interact, screenshot, console/network capture, evaluate) through a single tool, with handle+preview output for large results — navigation is http(s)-only, blocks private/link-local hosts by default and cloud metadata always (SSRF guard; localhost is allowed for dev), and screenshots must use `.png`/`.jpg`, stay in the project directory, and never overwrite an existing file.
+- **`opl-webaccess`** adds provider-backed search plus readable URL and PDF extraction, with session recovery of earlier results, an http(s)-only fetch that blocks private/link-local hosts by default and cloud metadata always, re-checks every redirect hop (SSRF guard; localhost is allowed for dev), a 10 MB response cap, and a 30s timeout.
 - **`opl-simplebench`** benchmarks models on deterministic closed-answer contracts, instruction-following, and tool-call generation so you pick a model on evidence, not vibes.
 ![simplebench](images/ss-simplebench.png)
 - **`opl-todo`** tracks branch-aware tasks that persist across a session and reconstruct from history.
@@ -150,7 +152,7 @@ Cold prompt-cache write, measured /init session (opl-modes lazy tools + MCP adap
 | Run the agent safely on real repos | `opl-modes` (pulls in the `opl-input` + `opl-footer` UI bundle), `opl-guardian` |
 | Research and drive the web         | `opl-webaccess`, `opl-browser`                                  |
 | Choose models with data            | `opl-simplebench`                                               |
-| The full, coordinated experience   | all ten                                                         |
+| The full, coordinated experience   | all eleven                                                      |
 
 Selecting `opl-footer`, `opl-input`, or `opl-modes` installs all three, because they share active-mode state.
 
@@ -171,7 +173,7 @@ Installing extensions adds tool schemas (name + description + JSON parameters) t
 | `opl-init` | command only (no tool) | ~0 |
 | `opl-input` | UI only | ~0 |
 | `opl-footer` | UI only | ~0 |
-| `opl-guardian` | none (session-integrity guard) | ~0 |
+| `opl-guardian` | none (tool/session safety; no added tool schemas) | ~0 |
 | `opl-ctxtrim` | none (payload transformer) | net negative |
 
 Command descriptions add roughly another ~120 tokens collectively, and only if your build surfaces them in the prompt or help block.
@@ -195,9 +197,10 @@ The fixed cost of a full install is small and paid once per session, then cached
 
 Copy applicable files from [`configs/`](configs/) to `~/.pi/agent/configs/`. For a Pi package installation, the source directory is `~/.pi/agent/npm/node_modules/@openlines/opl-pi-sht/configs/` (npm) or `~/.pi/agent/git/github.com/linellazatin/opl-pi-sht/configs/` (Git):
 
-- `opl-footer.json`, `opl-input.json`, `opl-modes.json`, `opl-todo.json`, `opl-webaccess.json`
+- `opl-footer.json`, `opl-input.json`, `opl-modes.json`, `opl-todo.json`, `opl-webaccess.json`, `opl-guardian.json`
 - `opl-browser` has optional configuration (`opl-browser.json`); all fields default, so it works without any config file.
 - `opl-simplebench` has optional `opl-simplebench.json`; copy `configs/opl-simplebench.json.sample` to configure DDGS/SearXNG research and llama metadata endpoints.
+- `opl-guardian` has an optional `opl-guardian.json`; copy `configs/opl-guardian.json.sample` and manually migrate any old permission-gate or protected-path settings. It does not load legacy files. Configured `permissionGate.patterns` replace the defaults, so copied live patterns do not automatically inherit later default-rule updates.
 - `opl-init` and `opl-questionnaire` have no external configuration.
 - Config files must be valid JSON, with no comments or trailing commas beyond deliberate `_comment` keys.
 - `opl-modes` owns active-mode appearance. Each mode's `appearance.prefix`, `prefixColor`, and `borderColor` style `opl-input`; `appearance.modeColor` styles `opl-footer`'s unified mode label. Renderers retain hardcoded fallbacks.

package/configs/opl-browser.json.sample

@@ -1,9 +1,10 @@
 {
-  "_comment": "Optional. Copy to ~/.pi/agent/configs/opl-browser.json. All fields optional; defaults shown.",
+  "_comment": "Optional. Copy to ~/.pi/agent/configs/opl-browser.json. All fields optional; defaults shown. allowPrivateNetwork (default false) blocks navigate/new_page from reaching private/link-local ranges; loopback (localhost) is always allowed for local development, and cloud-metadata endpoints are always blocked.",
   "headless": true,
   "width": 1280,
   "height": 800,
   "navigationTimeoutMs": 30000,
   "previewChars": 4000,
-  "getChars": 30000
+  "getChars": 30000,
+  "allowPrivateNetwork": false
 }

package/configs/opl-guardian.json.sample

@@ -0,0 +1,28 @@
+{
+  "_comment": "Copy to ~/.pi/agent/configs/opl-guardian.json and customize. This replaces standalone permission-gate, protected-paths, and confirm-destructive settings.",
+  "permissionGate": {
+    "patterns": [
+      "\\brm\\s+(?:(?:-[a-z]+|--[a-z-]+)\\s+)*(?:-[a-z]*r[a-z]*|--recursive)(?=\\s|$)",
+      "\\bsudo\\b",
+      "\\b(chmod|chown)\\s+(?:-[a-z]+\\s+)*777(?:\\b|$)",
+      "\\bprintenv\\b",
+      "(^|\\s)env(\\s|$)"
+    ],
+    "blockWithoutUI": true
+  },
+  "protectedPaths": {
+    "paths": [
+      { "path": ".env", "deny": ["read", "write", "edit", "bash"] },
+      { "path": ".git/", "deny": ["read", "write", "edit"] },
+      { "path": "node_modules/", "deny": ["write", "edit"] },
+      { "path": "~/.pi/agent/auth.json", "deny": ["read", "write", "edit", "bash"] }
+    ]
+  },
+  "confirmDestructive": {
+    "clearSession": true,
+    "switchWithUnsavedWork": true,
+    "forkSession": true,
+    "blockWithoutUI": true
+  },
+  "dropMalformedToolCalls": true
+}

package/configs/opl-modes.json.sample

@@ -6,7 +6,7 @@
   },
   "shortcuts": {
     "_comment": "Shortcut that cycles through all enabled, visible modes in registry order. Default: ctrl+alt+m.",
-    "cycleMode": "shift+tab"
+    "cycleMode": "ctrl+alt+m"
   },
   "cleanup": {
     "_comment": "Set to true to delete the plan file automatically after plan_complete is called.",
@@ -17,8 +17,8 @@
   "_comment_lazyTools": "Tool names withheld from the active set at rest and enabled on demand via the load_tools tool. Only affects modes that would otherwise include them (off/execute and custom modes that list them). Core built-ins, plan_complete, and load_tools are protected and ignored. Omit or leave empty to keep all tools always active.",
   "lazyTools": [],
   "bashPatterns": {
-    "_comment_safe": "Replace-only: providing bashPatterns.safePatterns replaces the built-in safe list. This is the default safe allowlist for every mode and it is checked per shell segment (&&, ||, a lone &, |, ;, newline, $(...), backticks, <( and >( each start a segment), so every chained or backgrounded command must be allowed. Quote-aware: grep \\\"a|b\\\" stays one command, but a $(...) or backtick payload still runs inside double quotes, so it is split out and checked too. Interpreters and tools that can write files or exec programs from their own arguments (awk, sed, xargs, perl, python, env) are deliberately not listed. A mode overrides it with its own safePatterns or opts out of Bash gating with unrestrictedBash. Shown here with the built-in list.",
-    "_comment_destructive": "Replace-only: providing bashPatterns.destructivePatterns replaces the built-in destructive list. This is the default destructive blocklist for every mode; a mode overrides it with its own destructivePatterns or opts out of Bash gating with unrestrictedBash. Program-name entries are anchored to command position (match each segment start) so read-only commands that only mention rm/cp/sh in an argument stay allowed, while flag and redirect entries stay unanchored - that is how find -fprint, sort -o in any position, git log --output, npm audit fix, uniq's output operand, and a bare > file are caught even behind a safe command. Descriptor duplication (2>&1, >&2) and redirects into /dev/null are not writes and stay allowed. Shown here with the built-in list.",
+    "_comment_safe": "Replace-only: providing bashPatterns.safePatterns replaces the built-in safe list. This is the default safe allowlist for every mode and it is checked per shell segment (&&, ||, a lone &, |, ;, newline, $(...), backticks, <( and >( each start a segment), so every chained or backgrounded command must be allowed. Quote-aware: grep \\\"a|b\\\" stays one command, but a $(...) or backtick payload still runs inside double quotes, so it is split out and checked too. Interpreters and tools that can write files or exec programs from their own arguments (awk, sed, xargs, perl, python, env) are deliberately not listed. A mode overrides it with its own safePatterns or opts out of Bash gating with unrestrictedBash. An empty top-level safePatterns array falls back to the built-in list (it cannot opt out); set a per-mode safePatterns: [] to opt that mode out. Shown here with the built-in list.",
+    "_comment_destructive": "Replace-only: providing bashPatterns.destructivePatterns replaces the built-in destructive list. This is the default destructive blocklist for every mode; a mode overrides it with its own destructivePatterns or opts out of Bash gating with unrestrictedBash. Program-name entries are anchored to command position (match each segment start) so read-only commands that only mention rm/cp/sh in an argument stay allowed, while flag and redirect entries stay unanchored - that is how find -fprint, sort -o in any position, git log --output, npm audit fix, uniq's output operand, and a bare > file are caught even behind a safe command. Descriptor duplication (2>&1, >&2) and redirects into /dev/null are not writes and stay allowed. An empty top-level destructivePatterns array falls back to the built-in list (it cannot opt out); set a per-mode destructivePatterns: [] to opt that mode out. Shown here with the built-in list.",
     "safePatterns": [
       "^\\s*cat\\b",
       "^\\s*head\\b",

package/configs/opl-webaccess.json.sample

@@ -1,7 +1,11 @@
 {
-  "_comment_limits": "Optional top-level caps: maxContentChars caps the initial web_search/fetch_content body (default 30000); maxRetrievalChars caps one get_search_content page (default 30000). Pass offset=N to get_search_content to continue a truncated retrieval.",
+  "_comment_limits": "Optional top-level caps: maxContentChars caps the initial web_search/fetch_content body (default 30000); maxRetrievalChars caps one get_search_content page (default 30000). Pass offset=N to get_search_content to continue a truncated retrieval. maxSearchQueries caps how many queries one web_search call runs (default 10); maxFetchUrls caps how many URLs one fetch_content call fetches (default 20). Excess inputs are skipped and reported in the tool output.",
+  "_comment_network": "allowPrivateNetwork defaults to false: fetch_content rejects private-range and link-local hosts. Loopback (localhost/127.0.0.1/::1) is always allowed for local development, and cloud-metadata endpoints are always blocked. Set allowPrivateNetwork true to reach private ranges (LAN servers). This does NOT affect provider API endpoints (ddgs.apiUrl / searxng.instanceUrl), which remain configurable.",
+  "allowPrivateNetwork": false,
   "maxContentChars": 30000,
   "maxRetrievalChars": 30000,
+  "maxSearchQueries": 10,
+  "maxFetchUrls": 20,
   "provider": "searxng",
   "providers": {
     "gemini": {

package/extensions/opl-browser/README.md

@@ -45,15 +45,25 @@ Full action set: `navigate` (url, or `back`/`forward`/`reload`), `snapshot`,
   which only sees raw HTTP HTML. Static pages: `fetch_content`; rendered or
   interacted-with pages: `browser:extract`. With a `selector`, the matched element
   is converted verbatim (no article detection): Readability's candidate scoring is
-  a whole-document heuristic and mispicks inside small subtrees.
+  a whole-document heuristic and mispicks inside small subtrees. A selector that
+  matches multiple elements returns a clear error instead of a strict-mode crash,
+  and a selector with no match reports `(no elements match ...)`.
 - **Real Chromium via Playwright.** Navigation with `domcontentloaded` waits,
   CSS-selector interaction, viewport control, multi-page management.
 - **Scheme + path guards.** `navigate`/`new_page` accept http(s) only; `file:`,
-  `data:`, and `javascript:` are rejected. Screenshot paths are confined to the
-  project directory, so a bad `path` cannot overwrite arbitrary files.
+  `data:`, and `javascript:` are rejected, private-range and link-local hosts are
+  blocked by default, and cloud-metadata endpoints are always blocked (SSRF guard).
+  Loopback (`localhost`/`127.0.0.0/8`/`::1`) is allowed by default for local
+  development; set `allowPrivateNetwork: true` for private ranges. Redirect targets
+  are re-checked on the final URL. Screenshot paths must use `.png`/`.jpg`, stay
+  inside the project directory, and are refused when the file already exists, so a
+  bad action cannot overwrite or plant arbitrary files.
 - **Per-page capture.** Console messages and network requests are buffered per
   page as they occur; `console` and `network` actions return the active page's
-  buffer.
+  buffer, capped at the most recent `200` entries per page so an active
+  long-running page cannot grow the buffer without bound. `navigate: back`/
+  `forward` on a fresh session reports `(no history to go back/forward)` instead of
+  silently returning the unchanged page.
 - **One reused browser per session.** Launched on first use, closed automatically
   on `session_shutdown`, or on demand via `action: "close"`.
 
@@ -68,6 +78,7 @@ Optional `~/.pi/agent/configs/opl-browser.json` (see `opl-browser.json.sample`):
 | `navigationTimeoutMs` | `30000` | Default navigation and `wait_for` timeout. |
 | `previewChars` | `4000` | Inline threshold; larger outputs are stored and previewed. |
 | `getChars` | `30000` | Characters returned by one `action: "get"` page. |
+| `allowPrivateNetwork` | `false` | Allow `navigate`/`new_page` to reach private/link-local ranges (loopback is always allowed; cloud metadata is always blocked). |
 
 ### Dependencies
 
@@ -86,7 +97,8 @@ npx playwright install chromium
 index.ts     Pi wiring: registers the single `browser` tool, TTL result store,
              preview/handle logic, and session_shutdown cleanup.
 browser.ts   Playwright driver: browser/context/page lifecycle, per-page console
-             and network buffers, and the action switch.
+             and network buffers, and the action switch. Tool calls are serialized
+             on the single shared context.
 validate.ts  URL/path guards: http/https-only navigation, screenshot path confined
              to the project directory.
 paging.ts    Bounded `get` pagination and continuation metadata.
@@ -98,4 +110,6 @@ config.ts    DEFAULT_CONFIG + loadUserConfig (user overrides win via ??).
 Interaction is CSS-selector based. Snapshot-uid interaction (referencing elements
 by ids returned from `snapshot`) is intentionally not implemented; use CSS
 selectors, which are simpler and robust. The in-memory result store expires
-entries after one hour or when the browser is closed.
+entries after one hour or when the browser is closed; expiry is checked on read,
+not only when another result is stored, so an idle entry past its TTL is never
+served.

package/extensions/opl-browser/browser.ts

@@ -12,22 +12,37 @@ let activeIndex = 0;
 const consoleBuf = new WeakMap<Page, string[]>();
 const networkBuf = new WeakMap<Page, string[]>();
 
+/** Cap on per-page console/network log lines kept in memory. */
+export const MAX_LOG_ENTRIES = 200;
+
+/** Push one log line, trimming the oldest entries past the cap. */
+export function pushLogEntry(entries: string[], entry: string, max = MAX_LOG_ENTRIES): string[] {
+  entries.push(entry);
+  if (entries.length > max) entries.splice(0, entries.length - max);
+  return entries;
+}
+
 function track(page: Page, cfg: BrowserConfig): void {
   consoleBuf.set(page, []);
   networkBuf.set(page, []);
   page.setDefaultNavigationTimeout(cfg.navigationTimeoutMs);
-  page.on("console", (m: ConsoleMessage) => consoleBuf.get(page)?.push(`[${m.type()}] ${m.text()}`));
+  page.on("console", (m: ConsoleMessage) => {
+    const buf = consoleBuf.get(page);
+    if (buf) pushLogEntry(buf, `[${m.type()}] ${m.text()}`);
+  });
   page.on("requestfinished", async (req) => {
     try {
       const res = await req.response();
-      networkBuf.get(page)?.push(`${req.method()} ${res?.status() ?? "?"} ${req.url()}`);
+      const buf = networkBuf.get(page);
+      if (buf) pushLogEntry(buf, `${req.method()} ${res?.status() ?? "?"} ${req.url()}`);
     } catch {
       /* response unavailable */
     }
   });
-  page.on("requestfailed", (req) =>
-    networkBuf.get(page)?.push(`${req.method()} FAILED ${req.url()} (${req.failure()?.errorText ?? "unknown"})`),
-  );
+  page.on("requestfailed", (req) => {
+    const buf = networkBuf.get(page);
+    if (buf) pushLogEntry(buf, `${req.method()} FAILED ${req.url()} (${req.failure()?.errorText ?? "unknown"})`);
+  });
 }
 
 async function ensure(cfg: BrowserConfig): Promise<BrowserContext> {
@@ -46,6 +61,13 @@ function page(): Page {
   return pages[activeIndex] ?? pages[pages.length - 1];
 }
 
+/** Navigate with the host validated both before the request and on the final URL, so a
+ *  public URL that redirects to a private/link-local host is rejected. */
+async function gotoAllowed(target: Page, url: string, cfg: BrowserConfig): Promise<void> {
+  await target.goto(assertHttpUrl(url, { allowPrivateNetwork: cfg.allowPrivateNetwork }), { waitUntil: "domcontentloaded" });
+  assertHttpUrl(target.url(), { allowPrivateNetwork: cfg.allowPrivateNetwork });
+}
+
 export interface BrowserActionResult {
   text: string;
   file?: string;
@@ -67,9 +89,23 @@ export interface BrowserParams {
   height?: number;
 }
 
-export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
+let last: Promise<unknown> = Promise.resolve();
+/** Serialize state-mutating browser work: a single shared context cannot service
+ *  concurrent tool calls safely (activeIndex, page(), ensure() all race). Each new
+ *  action is queued behind the previous one, and failures never break the chain. */
+function serialize<T>(task: () => Promise<T>): Promise<T> {
+  const run = last.then(task, task);
+  last = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+export function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
+  return serialize(() => runActionInternal(p, cfg));
+}
+
+async function runActionInternal(p: BrowserParams, cfg: BrowserConfig): Promise<BrowserActionResult> {
   if (p.action === "close") {
-    await closeBrowser();
+    await closeBrowserInternal();
     return { text: "Browser closed." };
   }
 
@@ -78,10 +114,15 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
   switch (p.action) {
     case "navigate": {
       const url = p.url ?? "";
-      if (url === "back") { await page().goBack(); }
-      else if (url === "forward") { await page().goForward(); }
-      else if (url === "reload") { await page().reload(); }
-      else if (url) { await page().goto(assertHttpUrl(url), { waitUntil: "domcontentloaded" }); }
+      if (url === "back" || url === "forward") {
+        // Playwright returns null (no throw) when history is exhausted; report it
+        // clearly instead of silently returning the unchanged page.
+        const moved = url === "back" ? await page().goBack() : await page().goForward();
+        if (!moved) return { text: `(no history to go ${url})` };
+        return { text: `${page().url()} — ${await page().title()}` };
+      }
+      if (url === "reload") await page().reload();
+      else if (url) await gotoAllowed(page(), url, cfg);
       else throw new Error("navigate requires url (or back|forward|reload)");
       return { text: `${page().url()} — ${await page().title()}` };
     }
@@ -91,9 +132,18 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
     }
     case "extract": {
       const selector = p.selector;
-      const html = selector
-        ? await page().locator(selector).evaluate((el: Element) => el.outerHTML)
-        : await page().content();
+      let html: string;
+      if (selector) {
+        const loc = page().locator(selector);
+        const count = await loc.count();
+        if (count === 0) return { text: `(no elements match "${selector}")` };
+        if (count > 1) {
+          throw new Error(`extract selector "${selector}" matched ${count} elements; use a more specific selector`);
+        }
+        html = await loc.evaluate((el: Element) => el.outerHTML);
+      } else {
+        html = await page().content();
+      }
       const { markdown } = extractMarkdown(html, { raw: Boolean(selector) });
       return { text: markdown || "(empty extraction)" };
     }
@@ -130,15 +180,18 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
     case "evaluate": {
       if (!p.script) throw new Error("evaluate requires script");
       const value = await page().evaluate(p.script);
-      return { text: typeof value === "string" ? value : JSON.stringify(value, null, 2) };
+      if (value === undefined) return { text: "(undefined result)" };
+      return { text: typeof value === "string" ? value : (JSON.stringify(value, null, 2) ?? "(undefined result)") };
     }
     case "console": {
       const msgs = consoleBuf.get(page()) ?? [];
-      return { text: msgs.length ? msgs.join("\n") : "(no console messages)" };
+      const suffix = msgs.length >= MAX_LOG_ENTRIES ? `\n… (showing last ${MAX_LOG_ENTRIES} entries)` : "";
+      return { text: msgs.length ? msgs.join("\n") + suffix : "(no console messages)" };
     }
     case "network": {
       const reqs = networkBuf.get(page()) ?? [];
-      return { text: reqs.length ? reqs.join("\n") : "(no network requests)" };
+      const suffix = reqs.length >= MAX_LOG_ENTRIES ? `\n… (showing last ${MAX_LOG_ENTRIES} requests)` : "";
+      return { text: reqs.length ? reqs.join("\n") + suffix : "(no network requests)" };
     }
     case "wait_for": {
       const timeout = p.timeoutMs ?? cfg.navigationTimeoutMs;
@@ -155,7 +208,7 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
       const pg = await ctx.newPage();
       track(pg, cfg);
       activeIndex = ctx.pages().length - 1;
-      if (p.url) await pg.goto(assertHttpUrl(p.url), { waitUntil: "domcontentloaded" });
+      if (p.url) await gotoAllowed(pg, p.url, cfg);
       return { text: `Opened page [${activeIndex}] ${pg.url()}` };
     }
     case "select_page": {
@@ -182,7 +235,11 @@ export async function runAction(p: BrowserParams, cfg: BrowserConfig): Promise<B
   }
 }
 
-export async function closeBrowser(): Promise<void> {
+export function closeBrowser(): Promise<void> {
+  return serialize(closeBrowserInternal);
+}
+
+async function closeBrowserInternal(): Promise<void> {
   try {
     await context?.close();
     await browser?.close();

package/extensions/opl-browser/config.ts

@@ -9,6 +9,9 @@ export interface BrowserConfig {
   navigationTimeoutMs: number;
   previewChars: number;
   getChars: number;
+  /** Allow navigate/new_page to reach private/link-local ranges (loopback is always
+   *  allowed; cloud metadata is always blocked). Default false. */
+  allowPrivateNetwork: boolean;
 }
 
 export const DEFAULT_CONFIG: BrowserConfig = {
@@ -18,6 +21,7 @@ export const DEFAULT_CONFIG: BrowserConfig = {
   navigationTimeoutMs: 30000,
   previewChars: 4000,
   getChars: 30000,
+  allowPrivateNetwork: false,
 };
 
 const CONFIG_PATH = path.join(os.homedir(), ".pi", "agent", "configs", "opl-browser.json");
@@ -36,5 +40,6 @@ export function loadUserConfig(configPath = CONFIG_PATH): BrowserConfig {
     navigationTimeoutMs: user.navigationTimeoutMs ?? DEFAULT_CONFIG.navigationTimeoutMs,
     previewChars: user.previewChars ?? DEFAULT_CONFIG.previewChars,
     getChars: user.getChars ?? DEFAULT_CONFIG.getChars,
+    allowPrivateNetwork: user.allowPrivateNetwork ?? DEFAULT_CONFIG.allowPrivateNetwork,
   };
 }

package/extensions/opl-browser/index.ts

@@ -62,6 +62,11 @@ export default function (pi: ExtensionAPI) {
         if (!p.responseId) return err("get requires responseId");
         const hit = STORE.get(p.responseId);
         if (!hit) return err(`No stored result for ${p.responseId} (expires after 1h or on browser close).`);
+        // Enforce TTL on read, not just on the next store.
+        if (Date.now() - hit.timestamp > TTL_MS) {
+          STORE.delete(p.responseId);
+          return err(`No stored result for ${p.responseId} (expires after 1h or on browser close).`);
+        }
         const page = paginateStored(hit.text, p.offset ?? 0, cfg.getChars);
         return {
           content: [{ type: "text", text: page.text + continuationNotice(page) }],
@@ -76,15 +81,18 @@ export default function (pi: ExtensionAPI) {
         return err(`browser ${p.action}: ${e instanceof Error ? e.message : String(e)}`);
       }
 
+      // Defensive: never let a missing/invalid action text crash the size gate.
+      const text = String(result.text ?? "");
+
       // Small outputs return inline; large outputs are stored and previewed.
-      if (result.text.length <= cfg.previewChars) {
-        return { content: [{ type: "text", text: result.text }], details: result.file ? { file: result.file } : {} };
+      if (text.length <= cfg.previewChars) {
+        return { content: [{ type: "text", text }], details: result.file ? { file: result.file } : {} };
       }
-      const id = store(p.action, result.text);
-      const preview = result.text.slice(0, cfg.previewChars);
+      const id = store(p.action, text);
+      const preview = text.slice(0, cfg.previewChars);
       return {
         content: [{ type: "text", text: `${preview}\n\n… truncated. Full result via action:get responseId: ${id}` }],
-        details: { responseId: id, action: p.action, chars: result.text.length },
+        details: { responseId: id, action: p.action, chars: text.length },
       };
     },
   });

package/extensions/opl-browser/validate.ts

@@ -1,10 +1,119 @@
 // Pure URL/path guards for the browser tool. No Playwright import so tests load it directly.
 
+import { existsSync } from "node:fs";
 import { resolve, sep } from "node:path";
 
-/** Normalize a URL, allowing only http/https so file:/data:/javascript: URLs can't
- *  be navigated (file:// + evaluate = local file bytes returned into model context). */
-export function assertHttpUrl(url: string): string {
+export interface HttpUrlOptions {
+  /** Allow private, link-local, and reserved network hosts (default false). Loopback is always allowed; cloud metadata is always blocked. */
+  allowPrivateNetwork?: boolean;
+}
+
+/** Well-known cloud metadata hostnames that resolve to instance-credential endpoints. */
+const BLOCKED_METADATA_HOSTS = new Set([
+  "metadata",
+  "metadata.google.internal",
+  "instance-data",
+  "instance-data.ec2.internal",
+]);
+
+/** Cloud metadata IPv6 literals (e.g. AWS IMDS over IPv6). Always blocked. */
+const BLOCKED_METADATA_V6 = new Set(["fd00:ec2::254"]);
+
+type HostClass = "loopback" | "metadata" | "private" | "public";
+
+function ipv4FromInteger(n: number): number[] | null {
+  if (!Number.isInteger(n) || n < 0 || n > 0xffffffff) return null;
+  return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+}
+
+function ipv4Octets(host: string): number[] | null {
+  if (/^\d+$/.test(host)) return ipv4FromInteger(Number(host));
+  const octets = host.split(".").map((part) => (/^\d+$/.test(part) ? Number(part) : NaN));
+  if (octets.length !== 4 || octets.some((o) => !Number.isInteger(o) || o < 0 || o > 255)) return null;
+  return octets;
+}
+
+function isLoopbackIpv4(o: number[]): boolean {
+  return o[0] === 127;
+}
+
+function isMetadataIpv4(o: number[]): boolean {
+  return (
+    (o[0] === 169 && o[1] === 254 && o[2] === 169 && o[3] === 254) ||
+    (o[0] === 100 && o[1] === 100 && o[2] === 100 && o[3] === 200)
+  );
+}
+
+function isPrivateIpv4(o: number[]): boolean {
+  const [a, b, c] = o;
+  return (
+    a === 0 || a === 10 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) ||
+    (a === 192 && b === 0 && (c === 0 || c === 2)) ||
+    (a === 198 && (b === 18 || b === 19)) ||
+    (a === 198 && b === 51 && c === 100) ||
+    (a === 203 && b === 0 && c === 113) ||
+    a >= 224
+  );
+}
+
+function ipv4MappedOctets(ip: string): number[] | null {
+  const dotted = ip.match(/^::ffff:(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
+  if (dotted) return dotted.slice(1).map(Number);
+  const hex = ip.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (hex) {
+    const n = (parseInt(hex[1], 16) << 16) | parseInt(hex[2], 16);
+    return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+  }
+  return null;
+}
+
+function classifyIpv4Octets(o: number[]): HostClass {
+  if (isLoopbackIpv4(o)) return "loopback";
+  if (isMetadataIpv4(o)) return "metadata";
+  if (isPrivateIpv4(o)) return "private";
+  return "public";
+}
+
+function classifyIpv6Host(host: string): HostClass {
+  const ip = host.replace(/^\[/, "").replace(/\]$/, "").replace(/%.*$/, "").toLowerCase();
+  if (BLOCKED_METADATA_V6.has(ip)) return "metadata";
+  if (ip === "::1") return "loopback";
+  const mapped = ipv4MappedOctets(ip);
+  if (mapped) return classifyIpv4Octets(mapped);
+  if (ip === "::") return "private";
+  if (/^f[cd]/.test(ip)) return "private";
+  if (/^fe[89ab]/.test(ip)) return "private";
+  if (/^ff/.test(ip)) return "private";
+  return "public";
+}
+
+function classifyHost(host: string): HostClass {
+  const lowered = host.toLowerCase();
+  if (BLOCKED_METADATA_HOSTS.has(lowered)) return "metadata";
+  if (lowered === "localhost" || lowered.endsWith(".localhost")) return "loopback";
+  if (lowered.includes(":")) return classifyIpv6Host(lowered);
+  const octets = ipv4Octets(lowered);
+  return octets ? classifyIpv4Octets(octets) : "public";
+}
+
+function isBlockedNetworkHost(host: string, allowPrivateNetwork: boolean): boolean {
+  const cls = classifyHost(host);
+  if (cls === "metadata") return true;
+  if (cls === "loopback" || cls === "public") return false;
+  return !allowPrivateNetwork;
+}
+
+/**
+ * Normalize a URL, allowing only http/https, so `file:`/`data:`/`javascript:` URLs and SSRF
+ * targets can't be navigated (file:// + evaluate = local file bytes returned into model context).
+ * Loopback is allowed by default for local development; private/link-local/reserved ranges are
+ * blocked unless allowPrivateNetwork is set; cloud metadata is always blocked.
+ */
+export function assertHttpUrl(url: string, opts: HttpUrlOptions = {}): string {
   let parsed: URL;
   try {
     parsed = new URL(url);
@@ -14,16 +123,25 @@ export function assertHttpUrl(url: string): string {
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
     throw new Error(`only http/https URLs are allowed, got ${parsed.protocol}//`);
   }
+  if (isBlockedNetworkHost(parsed.hostname, opts.allowPrivateNetwork === true)) {
+    throw new Error(`blocked network host "${parsed.hostname}" — private, link-local, reserved, and cloud-metadata URLs are not allowed (set allowPrivateNetwork to opt in to private ranges; metadata is always blocked)`);
+  }
   return parsed.href;
 }
 
-/** Require a screenshot path to stay within the project directory (guard against
- *  overwriting absolute or parent-relative user files with PNG bytes). */
+/** Require a screenshot path to stay within the project directory and refuse to overwrite
+ *  existing files (guard against overwriting project files or writing outside the repo). */
 export function safeScreenshotPath(file: string, cwd: string = process.cwd()): string {
   const root = resolve(cwd);
   const abs = resolve(cwd, file);
   if (abs !== root && !abs.startsWith(root + sep)) {
     throw new Error(`screenshot path must stay within the project directory: ${file}`);
   }
+  if (!/\.(png|jpe?g)$/i.test(file)) {
+    throw new Error(`screenshot path must end in .png or .jpg: ${file}`);
+  }
+  if (existsSync(abs)) {
+    throw new Error(`screenshot path already exists (refusing to overwrite): ${file}`);
+  }
   return file;
 }