@lincoln504/pi-research 1.7.1 → 1.7.3

package/docs/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.7.3] - 2026-09-30
+
+### Changed
+
+- **Quick (depth 0) research is now shaped like a quick answer, not a report.** Depth 0 is for a single verifiable fact, but it inherited the deep path's volume and framing: five search queries, eight URLs per scrape batch, and the deep `researcher.md` system prompt with two placeholders blanked — a prompt that asks for an exhaustive, critically-deconstructed report, advertises scrape rounds 2+ and a sibling "Session URL Pool" a single-pass run cannot have, and states that omitting information is a failure. Three changes, all scoped to quick runs (the pi extension tool, the CLI and the SDK's `--depth 0`; the deep path is untouched):
+  - `QUICK_MAX_QUERIES` default `5` → `3` (range unchanged, 1–10).
+  - New `QUICK_MAX_SCRAPE_URLS` (`PI_RESEARCH_QUICK_MAX_SCRAPE_URLS`, default `5`, range 1–20) caps the `scrape` tool's URLs per call for quick runs, plumbed through `createResearcherSession` → `createResearchTools` → `createScrapeTool` the way `maxSearchQueries` already was, so the advertised cap, the per-call slice and the over-cap report stay one number. `PI_RESEARCH_MAX_SCRAPE_URLS` (`8`) remains the deep cap, and `PI_RESEARCH_MAX_SCRAPE_BATCHES` still caps the batch count, so a quick run's scrape ceiling falls from 2×8 to 2×5 URLs.
+  - New `src/prompts/quick-researcher.md`: single-pass, answer-first, "stop once the answer is sourced", with every hard requirement the engine depends on kept intact (grounding, `[N]` citations, the `CITED LINKS` format `parseCitations` parses, the untrusted-content rule, and the `RESEARCHER_AGENT_MARKER` the host hook keys on to skip steering injection). The deep `researcher.md` is unchanged, so its byte-identical-across-researchers prompt-cache property is unaffected.
+- **pi packages verified against 0.99.2; the floor moves `0.87.0` → `0.99.0` and the tested ceiling to 0.99.2.** `@earendil-works/pi-ai`, `pi-coding-agent` and `pi-tui` move `>=0.87.0 <1` → `>=0.99.0 <1`, and the lockfile resolves 0.99.2. (`@earendil-works/pi-server` was bumped to the same floor in the interim and then deleted outright later in this release — see below.) The floor moved because this release starts depending on a 0.99-only surface: tool `exposure` (see below) and `ToolDefinition.execute()`'s context widening to `ExtensionToolContext`. A pre-0.99 host does not fail a type check for either — it ignores an unknown `exposure` value and would declare a withdrawn tool to the model, which is exactly the class of silent breakage the floor exists to prevent. The upgrade's compile-time fallout was three direct `ToolDefinition.execute()` call sites (the `/research` and `/knowledge-store` command handlers, the SDK's `searchKnowledge`), which now view their plain context through `asToolExecContext()` (`src/utils/tool-exec-context.ts`, documented there: pi-research's tools never use `ctx.tools` or `ctx.executeTool()`). One runtime contract test caught a new host loader member (`loadExtensionPaths`, a private helper, added to `HOST_INTERNAL_HELPERS`). Full unit suite (3,176 tests) passes against 0.99.2.
+- **The knowledge-search tool is withdrawn from the model's tool list while Knowledge Mode is `none`, using pi 0.99's `exposure`.** Previously `research_knowledge_search` was registered `direct` unconditionally, so a disabled store still showed the model a tool that could only miss; only its prompt block was gated. It is now re-registered with `exposure: 'hidden'` when the mode is `none` and back to `'direct'` when it is not (`syncKnowledgeSearchExposure` in `src/index.ts`, run at load, on `session_start`, and on each new prompt), so the toggle still applies from the next prompt without a pi restart and the disabled tool is genuinely undeclared. `pi.getAllTools()` reports the exposure; a hidden tool is neither declared to the model nor listed in the prompt.
+- **`npm audit` production tree: the `brace-expansion` advisories are fixed by override, and the one copy no override can reach left the shipped tree.** `brace-expansion` `GHSA-q2hr-2g5m-vwhr` / `GHSA-qhr7-859c-m2p7` / `GHSA-6j4f-fj2g-mc7p` (brace-expansion ≤ 5.0.11, a CPU-DoS in glob brace expansion) is fixed by the new `overrides` entry `brace-expansion: ^5.0.12` everywhere in the tree EXCEPT the copy frozen inside the pi host's own `npm-shrinkwrap.json` (`@earendil-works/pi-coding-agent` → `minimatch@10.2.6` → `brace-expansion@5.0.9`), which no downstream override can reach. That single node was briefly allowlisted with the location-scoped exception shape in `config/tooling/audit-exceptions.json`; the peer-dependency change below removed the host's shrinkwrapped subtree from the shipped tree, so the entry is gone and the allowlist is empty again. A second new override, `fast-uri: ^3.1.8`, fixes `GHSA-hrr3-gc8f-f4qj` (dev-only, via `depngn` → `table` → `ajv`). `node scripts/audit-gate.cjs` is green with zero allowlisted advisories.
+- **In-range dependency refresh:** `undici` 8.11.0 → 8.11.2, `vite` 8.3.0 → 8.3.1, `vitest` / `@vitest/coverage-v8` 5.0.1 → 5.0.3, `dependency-cruiser` 18.3.1 → 18.5.0, `@typescript-eslint/*` 8.70.1 → 8.71.0. The deliberate holds are unchanged and re-verified against the new tree: `apache-arrow` 21.1.0 (21.2.0 breaks LanceDB 0.39.0 IPC reads), `playwright-core` 1.60.0 (camoufox-js 0.12.0 peer cap `<1.61.0`), `typebox` 1.3.27 (lockstep with pi 0.99.2's own pin), `@huggingface/transformers` 4.2.0 (4.3.0 reshuffles the ONNX native stack for no needed gain), `typescript` 6.0.3.
+
+- **CI action pins refreshed to the newest releases.** `actions/setup-node` v6.5.0 → v7.0.0, `actions/upload-artifact` v4.6.2 → v7.0.1, `actions/download-artifact` v6.0.0 → v8.0.1, `github/codeql-action` v4.37.7 → v4.38.2 (`init` and `analyze` kept on the same commit). `actions/checkout` (v7.0.1) and `actions/cache` (v6.1.0) were already the newest release. Every pin stays a full commit SHA with the version in a trailing comment.
+- **The pinned-stack version claims in the docs were stale and are corrected.** `docs/ARCHITECTURE.md` still cited `typebox` `1.3.7` across pi's 0.84/0.85 lines and `@lancedb/lancedb` 0.38. `typebox` is `1.3.27`, the version `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent` 0.99.2 both declare (read from their installed `package.json`), and LanceDB is `0.39.0`. The Arrow hold was re-verified against 0.39.0 on 2026-10-01: `21.2.0` still fails every table open with `Failed to read IPC file: Arrow error: Parser error: Unable to get root as footer: RangeOutOfBounds … UnionVariant { variant: "Type::FixedSizeList" }`. The same three numbers were corrected in the ES/JA/ZH translations.
+
+- **The `@earendil-works/pi-*` host packages are peer dependencies now, the unused `@earendil-works/pi-server` is gone, and the shipped tree audits clean with no allowlist.** pi's extension loader aliases every `@earendil-works/*` and `typebox` specifier to the HOST's own copies, so the copies inside a managed install are never loaded in-host — they existed only for the standalone CLI and SDK, at a cost of roughly 145MB per managed install (`pi-coding-agent` alone is ~440MB unpacked here). pi's own installer passes `--legacy-peer-deps` on purpose so host packages are not installed alongside. `@earendil-works/pi-ai`, `pi-coding-agent` and `pi-tui` therefore move `dependencies` → `peerDependencies` (`>=0.99.0 <1`), with matching `devDependencies` so this repo's own install, tests and CI still resolve them. Three consequences:
+  - The production tree no longer contains `pi-coding-agent`'s `npm-shrinkwrap.json` subtree, so the `brace-expansion` advisories it froze are no longer shipped and `config/tooling/audit-exceptions.json` is empty again (the gate prints a stale-entry warning if the entry is left in place). The full-tree audit still reports it, as the informational dev summary.
+  - `@earendil-works/pi-server` is removed. It was declared as a dependency but imported by nothing in `src/`, `dist/` or the agent skill.
+  - Standalone installs are unaffected on npm ≥ 7, which resolves peers automatically. An install that skips them (`--legacy-peer-deps`, yarn classic) is now caught: the agent-skill launcher's dependency preflight covers the PATH and `~/.pi/bin` engine locations too (it dereferences the bin symlink before deciding, and skips the check when the layout cannot be identified, so a working install is never failed), and the message plus the docs name the one-line fix. `test/unit/cli.test.ts` covers both the fail-closed path and the pass-through.
+
+### Fixed
+
+- **The log-redaction JWT bounds are asserted directly instead of timed.** `redactSecrets` keeps every JWT segment quantifier bounded, because an unbounded `[A-Za-z0-9_-]+` consumed to the end of a dotless base64url run and backtracked one character at a time, and `_`/`-` count as non-alphanumeric left boundaries, so the same run offered a fresh start position every few characters. The guard was a wall-clock scaling ratio, and it failed CI twice: 3.12x against a 3.0 threshold on ubuntu/node 22, 3.47x on node 24 before that. The ratio is not measurable on this input. The bounded pattern costs about 0.004ms per call, so a doubling ratio was reading call overhead and regexp-cache warm-up rather than regex work, and V8's literal prefilter hides the pathology either way: an unbounded variant of the same pattern also scales linearly on `_eyJ` runs. The test now asserts the bound itself (`['{1,1024}', '{1,8192}', '{1,4096}']` on the exported `JWT_PATTERN`), which is deterministic and still fails if a bound is dropped.
+
+- **Research runs no longer fail on models that cannot turn thinking off.** The engine's direct LLM calls (coordinator, lead router, synthesizer, JSON repair, knowledge-search extraction and triage) all go through `buildSafeOptions` (`src/core/llm/llm-utils.ts`), which sends thinking `off` by default (`PI_RESEARCH_LLM_THINKING_LEVEL`). Some models reject that: zai/glm-5.3, whose catalog entry marks `off` as unsupported, answers every such call with 400 "This model always engages in thinking and cannot be disabled; please use low, high, or max", so a depth 1–3 run failed at the coordinator's first plan (quick mode was unaffected: it runs as a pi agent session, which already clamps the level). `off` is now raised to the nearest level the model supports (pi-ai's `clampThinkingLevel`, `low` for glm-5.3) only when the model cannot disable thinking; every other model and every explicit level is sent exactly as before. With the fix, the same depth-1 run on glm-5.3 completes.
+
+## [1.7.2] - 2026-09-27
+
+### Changed
+
+- **Scraped pages keep only the useful part of the converter's front matter.** The native converter turns every `<meta>` tag into a front-matter line: 54 lines on a GitHub page (analytics and error-reporting URLs, verification hashes, nonces, app ids), and on arXiv the abstract three times over. Nothing parses these lines; researchers read them and the knowledge store indexes them. `trimFrontMatter` (`src/web-research/scraper-utils.ts`) now keeps the title, description, author and publication/modification dates (first key present per slot: plain, Open Graph, citation or Dublin Core names) and drops the rest; a page with none of them loses the block. GitHub pages shrink by about 11%, arXiv abstract pages by about a third. Side effect: an empty page shell whose front matter alone used to pass the stub check is now treated as a stub, so the browser fallback gets a chance.
+- **Scraped pages no longer carry empty same-page links.** Documentation generators such as Quarto and nbdev put an empty anchor before every code line (`<a href="#cb2-1"></a>`) and next to headings; the native HTML→Markdown converter turned each into `[](#cb2-1)`, so every code block in a research scrape (and in the knowledge store) started each line with one. Both converters now drop links that have no text and point to the same page (`cleanConvertedMarkdown` in `src/web-research/scraper-utils.ts`, run after the existing image-link stripping so heading anchors that wrap an icon — GitHub's `[![](link.svg)](#title)` — go too). Links with text, and empty links to other pages, are kept. On an nbdev documentation page (fastcore.fast.ai/docments.html) this removes 583 such links, 16% of the scraped text.
+
 ## [1.7.1] - 2026-09-27
 
 ### Changed

package/docs/CONFIGURATION.md

@@ -75,7 +75,8 @@ Research
 | `PI_RESEARCH_MAX_RESEARCHERS` (TUI) | `3` | 1–5 | Parallel researchers. |
 | `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` (TUI) `[project]` | `1` | 0–3 | Depth for `/research` and the CLI when `--depth` is omitted (0=quick single-pass — requires `PI_RESEARCH_QUICK_RESEARCH` —, 1=normal, 2=deep, 3=ultra). The agent-facing `research` tool-usage prompt renders its depth guidance relative to this setting too: when quick is the configured default, depth 0 is the ordinary choice; a user who keeps the default (1) gets byte-identical guidance. |
 | `PI_RESEARCH_QUICK_RESEARCH` (TUI) `[project]` | `false` | `true` · `false` | Opt-in gate for depth-0 (quick) research. When `false` (default), the agent-facing `research` tool keeps its upstream `minimum: 1` schema — agents can neither see nor send depth 0 — and a `DEFAULT_RESEARCH_DEPTH` of 0 resolves to 1. Toggling applies on the next session. |
-| `PI_RESEARCH_QUICK_MAX_QUERIES` | `5` | 1–10 | Max queries per `search` call in quick (depth 0) research. Applies to every quick run — the pi extension tool, the CLI, and the SDK's `--depth 0` — since they share the same researcher session factory. Deliberately below deep research's 30-query cap; the ceiling of 10 keeps quick mode from ever exceeding the old 5–10 prompt guidance. |
+| `PI_RESEARCH_QUICK_MAX_QUERIES` | `3` | 1–10 | Max queries per `search` call in quick (depth 0) research. Applies to every quick run — the pi extension tool, the CLI, and the SDK's `--depth 0` — since they share the same researcher session factory. Deliberately below deep research's 30-query cap; the ceiling of 10 keeps quick mode from ever exceeding the old 5–10 prompt guidance. |
+| `PI_RESEARCH_QUICK_MAX_SCRAPE_URLS` | `5` | 1–20 | Max URLs fetched per scrape batch in quick (depth 0) research. Separate from `PI_RESEARCH_MAX_SCRAPE_URLS` (deep, `8`) because quick mode answers a single-fact question and the deep budget pulls in pages that question does not need; `PI_RESEARCH_MAX_SCRAPE_BATCHES` still caps how many batches a quick run may use. Applies to every quick run (pi extension tool, CLI, SDK `--depth 0`). |
 | `PI_RESEARCH_MAX_SCRAPE_BATCHES` (TUI) | `2` | 0–99 | Scrape batches per researcher (0 = unlimited). When prompt caching is known to be active for the resolved research model (Anthropic API models, or a provider route explicitly configured for Anthropic-style cache control), the effective limit is this value plus one — the cached prompt prefix makes the extra batch cheap. |
 | `PI_RESEARCH_MAX_GATHERING_CALLS` | `12` | 1–100 | Shared web-gathering calls per researcher (`search` + `security_search` + `stackexchange` + `youtube_transcript`). |
 | `PI_RESEARCH_MAX_CONCURRENT_SCRAPES` | `3` | 1–20 | Concurrent URLs fetched per scrape batch. |

package/docs/SDK.md

@@ -13,6 +13,14 @@ run the `pi` extension, which keeps its own private copy your scripts can't impo
 npm install @lincoln504/pi-research
 ```
 
+The `@earendil-works/pi-*` host packages are peer dependencies, so npm ≥7 installs them
+with the command above. If your install skips peers — `--legacy-peer-deps`, yarn
+classic — the SDK cannot import them, so add the one it loads directly:
+
+```bash
+npm install @earendil-works/pi-coding-agent
+```
+
 On npm ≥11.19 (and npm 12), dependency install scripts are skipped by default. Nothing
 here needs them: better-sqlite3 13 carries prebuilt bindings for every supported
 platform and loads them at runtime, and the stealth browser self-provisions on its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
@@ -115,10 +115,6 @@
     "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": ">=0.87.0 <1",
-    "@earendil-works/pi-coding-agent": ">=0.87.0 <1",
-    "@earendil-works/pi-server": ">=0.87.0 <1",
-    "@earendil-works/pi-tui": ">=0.87.0 <1",
     "@kreuzberg/html-to-markdown-node": "^3.7.2",
     "@lancedb/lancedb": "0.39.0",
     "apache-arrow": "21.1.0",
@@ -132,22 +128,29 @@
     "playwright-core": "1.60.0",
     "poolifier": "^5.3.2",
     "typebox": "1.3.27",
-    "undici": "^8.10.2",
+    "undici": "^8.11.2",
     "youtubei.js": "^18.0.0"
   },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.99.0 <1",
+    "@earendil-works/pi-coding-agent": ">=0.99.0 <1",
+    "@earendil-works/pi-tui": ">=0.99.0 <1"
+  },
   "optionalDependencies": {
     "@huggingface/transformers": "4.2.0",
     "webgpu": "^0.6.0"
   },
   "overrides": {
     "lodash.isequal": "npm:fast-deep-equal@^3.1.3",
+    "brace-expansion": "^5.0.12",
+    "fast-uri": "^3.1.8",
     "ip-address": "^10.2.0",
     "apache-arrow": "21.1.0",
     "onnxruntime-web": "1.24.3",
     "node-domexception": "npm:@nolyfill/domexception@^1.0.28",
     "ua-parser-js": "^1.0.41",
     "protobufjs": "7.6.5",
-    "vite": "^8.2.2",
+    "vite": "^8.3.1",
     "adm-zip": "^0.6.1",
     "jsdom": {
       "undici": "^8.10.2"
@@ -155,17 +158,20 @@
     "sharp": "^0.35.0"
   },
   "devDependencies": {
+    "@earendil-works/pi-ai": ">=0.99.0 <1",
+    "@earendil-works/pi-coding-agent": ">=0.99.0 <1",
+    "@earendil-works/pi-tui": ">=0.99.0 <1",
     "@eslint/js": "^10.0.1",
     "@types/jsdom": "^30.0.0",
-    "@typescript-eslint/eslint-plugin": "8.70.1",
-    "@typescript-eslint/parser": "8.70.1",
-    "@vitest/coverage-v8": "^5.0.1",
-    "dependency-cruiser": "^18.2.0",
+    "@typescript-eslint/eslint-plugin": "8.71.0",
+    "@typescript-eslint/parser": "8.71.0",
+    "@vitest/coverage-v8": "^5.0.3",
+    "dependency-cruiser": "^18.5.0",
     "depngn": "^0.6.0",
     "eslint": "10.11.0",
     "npm-check-updates": "^23.1.0",
     "typescript": ">=6.0.3 <6.1.0",
-    "vite": "^8.2.2",
-    "vitest": "^5.0.1"
+    "vite": "^8.3.1",
+    "vitest": "^5.0.3"
   }
 }

package/src/config.ts

@@ -96,12 +96,19 @@ export const ConfigSchema = Type.Object({
    *  (default: 5; 1 = every query). Configured via env/config file; not surfaced
    *  in the config TUI. */
   YOUTUBE_QUERY_EVERY_N: Type.Number({ minimum: 1, maximum: 100, default: 5 }),
-  /** Max queries per `search` call in quick (depth 0) research (default: 5, range: 1-10).
+  /** Max queries per `search` call in quick (depth 0) research (default: 3, range: 1-10).
    *  Applies to every quick run — the pi extension tool, the CLI, and the SDK's
    *  `--depth 0` — since all three share the same researcher session factory. The
    *  ceiling is 10 so quick mode can never exceed the old 5–10 prompt guidance.
    *  Configured via env/config file; not surfaced in the config TUI. */
-  QUICK_MAX_QUERIES: Type.Number({ minimum: 1, maximum: 10, default: 5 }),
+  QUICK_MAX_QUERIES: Type.Number({ minimum: 1, maximum: 10, default: 3 }),
+  /** Max URLs scraped per `scrape` call in quick (depth 0) research (default: 5,
+   *  range: 1-20). Quick mode is for single-fact lookups, where the deep default
+   *  (MAX_SCRAPE_URLS, 8) pulls in pages the question does not need; its per-batch
+   *  budget is therefore separate. Batches are still capped by MAX_SCRAPE_BATCHES.
+   *  Applies to every quick run (pi extension tool, CLI, SDK `--depth 0`).
+   *  Configured via env/config file; not surfaced in the config TUI. */
+  QUICK_MAX_SCRAPE_URLS: Type.Number({ minimum: 1, maximum: 20, default: 5 }),
   /** Health check timeout in milliseconds (default: 10000ms) */
   HEALTH_CHECK_TIMEOUT_MS: Type.Number({ minimum: 2000, maximum: 120000, default: 10000 }),
   /** Default timeout for browser page operations like search (default: 45000ms) */
@@ -282,6 +289,7 @@ const USER_MIGRATION_KEYS = [
   'PI_RESEARCH_YOUTUBE_TRANSCRIPT_LANG',
   'PI_RESEARCH_YOUTUBE_QUERY_EVERY_N',
   'PI_RESEARCH_QUICK_MAX_QUERIES',
+  'PI_RESEARCH_QUICK_MAX_SCRAPE_URLS',
   'PI_RESEARCH_CONSOLE_LOG',
   'PI_RESEARCH_MODEL',
   'PI_RESEARCH_KNOWLEDGE_DIR',
@@ -970,6 +978,7 @@ export function saveConfig(config: Config, scope: 'local' | 'user' = 'local', cw
     PI_RESEARCH_YOUTUBE_TRANSCRIPT_LANG: config.YOUTUBE_TRANSCRIPT_LANG,
     PI_RESEARCH_YOUTUBE_QUERY_EVERY_N: String(config.YOUTUBE_QUERY_EVERY_N),
     PI_RESEARCH_QUICK_MAX_QUERIES: String(config.QUICK_MAX_QUERIES),
+    PI_RESEARCH_QUICK_MAX_SCRAPE_URLS: String(config.QUICK_MAX_SCRAPE_URLS),
     PI_RESEARCH_BROWSER_TASK_TIMEOUT_MS: String(config.BROWSER_TASK_TIMEOUT_MS),
     PI_RESEARCH_LLM_TIMEOUT_MS: String(config.LLM_TIMEOUT_MS),
     PI_RESEARCH_LLM_THINKING_LEVEL: config.LLM_THINKING_LEVEL,
@@ -1202,6 +1211,7 @@ export function createConfig(env: Record<string, string | undefined>, processEnv
     YOUTUBE_TRANSCRIPT_LANG: parseEnvString(e, 'PI_RESEARCH_YOUTUBE_TRANSCRIPT_LANG', DEFAULTS.YOUTUBE_TRANSCRIPT_LANG)!,
     YOUTUBE_QUERY_EVERY_N: parseEnvNumber(e, 'PI_RESEARCH_YOUTUBE_QUERY_EVERY_N', DEFAULTS.YOUTUBE_QUERY_EVERY_N, 1, 100, true),
     QUICK_MAX_QUERIES: parseEnvNumber(e, 'PI_RESEARCH_QUICK_MAX_QUERIES', DEFAULTS.QUICK_MAX_QUERIES, 1, 10, true),
+    QUICK_MAX_SCRAPE_URLS: parseEnvNumber(e, 'PI_RESEARCH_QUICK_MAX_SCRAPE_URLS', DEFAULTS.QUICK_MAX_SCRAPE_URLS, 1, 20, true),
     HEALTH_CHECK_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_HEALTH_CHECK_TIMEOUT_MS', DEFAULTS.HEALTH_CHECK_TIMEOUT_MS, 2000, 120000),
     SEARCH_TIMEOUT_MS: parseEnvNumber(e, 'PI_RESEARCH_SEARCH_TIMEOUT_MS', DEFAULTS.SEARCH_TIMEOUT_MS, 5000, 120000),
     TUI_REFRESH_DEBOUNCE_MS: parseEnvNumber(e, 'PI_RESEARCH_TUI_REFRESH_DEBOUNCE_MS', DEFAULTS.TUI_REFRESH_DEBOUNCE_MS, 0, 1000),

package/src/core/llm/llm-utils.ts

@@ -4,7 +4,7 @@
  * Shared logic for safe and robust LLM interactions.
  */
 
-import { type Model, type AssistantMessage, type SimpleStreamOptions, type ModelThinkingLevel, type Tool, type TSchema, type Context, type ToolCall } from '@earendil-works/pi-ai';
+import { clampThinkingLevel, type Model, type AssistantMessage, type SimpleStreamOptions, type ModelThinkingLevel, type Tool, type TSchema, type Context, type ToolCall } from '@earendil-works/pi-ai';
 import { extractText } from '../../utils/text-utils.ts';
 import { logger } from '../../logger.ts';
 import { completeSimple } from './pi-ai-completion.ts';
@@ -20,6 +20,10 @@ import { completeSimple } from './pi-ai-completion.ts';
  *   'off' is deliberate: these engine calls emit structured JSON / cited reports, so a
  *   thinking block only consumes the output-token budget (often truncating before the
  *   text block is emitted) for at most a marginal quality gain that does not justify the cost.
+ *   Some models cannot turn thinking off (their `thinkingLevelMap` marks `off` as
+ *   unsupported, e.g. zai/glm-5.3, which rejects the request with a 400); for those
+ *   'off' becomes the nearest level the model supports (pi-ai's clampThinkingLevel,
+ *   the same rule pi's own agent sessions apply). Other levels pass through unchanged.
  *
  * Callers should also pass the research `sessionId` in `options`. pi-ai forwards it as the
  * provider's prompt-cache / session-affinity key — OpenAI's `prompt_cache_key`, OpenRouter's
@@ -40,7 +44,8 @@ export function buildSafeOptions(
   defaultCap: number = 4096,
   thinkingLevel: ModelThinkingLevel = 'off'
 ): SimpleStreamOptions {
-  const effective: ModelThinkingLevel = (options.reasoning as ModelThinkingLevel | undefined) ?? thinkingLevel;
+  const requested: ModelThinkingLevel = (options.reasoning as ModelThinkingLevel | undefined) ?? thinkingLevel;
+  const effective: ModelThinkingLevel = requested === 'off' ? clampThinkingLevel(model, 'off') : requested;
   return {
     ...options,
     // Ensure maxTokens is never null/None to avoid provider-side crashes

package/src/core/pi-version.ts

@@ -7,7 +7,7 @@
  *
  *   - As a pi EXTENSION, the host supplies `@earendil-works/*`. Our package.json
  *     range never constrains it, so an in-process check is the only enforcement.
- *   - As a standalone CLI/SDK, the range is `>=0.87.0 <1` and published tarballs
+ *   - As a standalone CLI/SDK, the range is `>=0.99.0 <1` and published tarballs
  *     carry no lockfile, so every fresh install resolves the newest 0.x at that
  *     instant. pi is pre-1.0: a minor bump may break anything under semver, and
  *     already has (0.83.0 extended the ResourceLoader contract).
@@ -83,8 +83,19 @@ export function compareVersions(a: SemverParts, b: SemverParts): number {
  * finishTurn boundary. The SDK paths (session service, model-registry factory)
  * are written against that surface; an older host may resolve but is not a
  * tested or supported target.
+ *
+ * 0.99.0 added tool `exposure` (including `hidden`, which is how a tool is
+ * withdrawn when tools cannot be unregistered) and widened
+ * `ToolDefinition.execute()`'s context from `ExtensionContext` to
+ * `ExtensionToolContext` (adds `tools` and `executeTool()`). pi-research uses
+ * `exposure` to keep an optional tool out of the model's tool list without a
+ * restart, and adapts plain contexts with `asToolExecContext()` at the three
+ * places it invokes its own tools directly (see utils/tool-exec-context.ts).
+ * Relying on either on an older host is a silent misbehaviour rather than a
+ * type error — a pre-0.99 host ignores `exposure: hidden` and would declare a
+ * withdrawn tool to the model — so the floor moved with the adoption.
  */
-export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 87, patch: 0 };
+export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 99, patch: 0 };
 
 /**
  * Newest host line this release was actually exercised against (CI + a real run).
@@ -92,7 +103,7 @@ export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 87, patch: 0 };
  * Compared on MAJOR.MINOR only: a patch bump within a tested line is not a new
  * surface, and warning on it would be noise.
  */
-export const PI_TESTED_MAX_VERSION: SemverParts = { major: 0, minor: 87, patch: 1 };
+export const PI_TESTED_MAX_VERSION: SemverParts = { major: 0, minor: 99, patch: 2 };
 
 export type PiCompatibilityLevel = 'ok' | 'unparseable' | 'too-old' | 'untested';
 

package/src/index.ts

@@ -14,6 +14,7 @@ import { logger } from './logger.ts';
 import { checkPiCompatibility } from './core/pi-version.ts';
 import { randomUUID } from 'node:crypto';
 import { shutdownManager } from './utils/shutdown-manager.ts';
+import { asToolExecContext } from './utils/tool-exec-context.ts';
 import { healthRegistry } from './healthcheck/index.ts';
 import { registerBeforeExitSafetyNet } from './knowledge/embedder-utils.ts';
 import { getConfig, validateConfig } from './config.ts';
@@ -92,11 +93,12 @@ function extractResultText(result: AgentToolResult<unknown>): string {
  * Pi Research Extension
  */
 export default async function (pi: ExtensionAPI) {
-  // Runtime version check — must match the @earendil-works/* dependency minimum (>=0.87.0).
+  // Runtime version check — must match the @earendil-works/* dependency minimum (>=0.99.0).
   // The floor was raised to 0.84.0 because setRuntimeApiKey() lost its `allowNetwork` option
   // there and only 0.84.0+ hardcodes the equivalent guard internally (see pi-version.ts), then
   // to 0.85.0 to track the pi extension package line, and to 0.87.0 for the 0.86
-  // TranscriptContext / 0.87 SessionEntry-union surface (see pi-version.ts). The
+  // TranscriptContext / 0.87 SessionEntry-union surface, and to 0.99.0 for tool `exposure`
+  // and the ExtensionToolContext widening of ToolDefinition.execute() (see pi-version.ts). The
   // APIs it rests on arrived in 0.80.8, which introduced ModelRuntime and removed
   // AuthStorage/ModelRegistry.create(); buildModelRegistry (model-registry-factory.ts)
   // unconditionally calls ModelRuntime.create(), and createAgentSession() is invoked
@@ -127,6 +129,12 @@ export default async function (pi: ExtensionAPI) {
   // 1. REGISTER CRITICAL EVENT LISTENERS IMMEDIATELY
   // This ensures we capture steering even if initialization takes time.
   pi.on('input', async (event: any, ctx: ExtensionContext) => {
+    // A new prompt (not steering typed while the agent runs): re-align the
+    // knowledge-search tool's exposure with live config before pi builds this
+    // turn's prompt, so a /research-config Knowledge Mode change applies without
+    // a pi restart. Registration happens before this closure runs (see
+    // syncKnowledgeSearchExposure below).
+    if (!event.streamingBehavior) syncKnowledgeSearchExposure(ctx);
     // Only intercept genuine interactive keystrokes. Programmatic sends originate
     // from this extension (source 'extension') — e.g. the Alt+P pop handler forwards
     // a popped message as 'steer'. Without this guard that forward would be captured
@@ -344,13 +352,34 @@ export default async function (pi: ExtensionAPI) {
 
   // Create and register the Research Knowledge Search tool. It is native-free at
   // construction (the vector/ML stack loads lazily on first execute) and self-guards when
-  // Knowledge Mode is 'none' (its execute returns a "store disabled" miss). Registering it
-  // unconditionally lets a Knowledge Mode change via /research-config take effect without a
-  // Pi restart — availability to the agent and the /knowledge-store command below both key
-  // off live config, not this startup binding. The pi API has no unregisterTool, so a
-  // startup-gated registration could never be added back after enabling mid-session anyway.
+  // Knowledge Mode is 'none' (its execute returns a "store disabled" miss).
+  //
+  // pi 0.99 exposes tool `exposure`, which is how this tool is keyed to LIVE
+  // Knowledge Mode: while the mode is 'none' it is re-registered as `hidden`, so
+  // it is neither declared to the model nor listed in the prompt, and a mode
+  // change via /research-config takes effect on the next prompt without a pi
+  // restart (pi has no unregisterTool; re-registering with `exposure: 'hidden'`
+  // is the documented withdrawal, and a later re-register back to `direct`
+  // activates the tool like a new one). The tool object itself is kept as the
+  // base so the /knowledge-store command below can still invoke it directly.
   const researchKnowledgeSearchTool: ToolDefinition = createResearchKnowledgeSearchTool('pi');
-  pi.registerTool(researchKnowledgeSearchTool);
+  let knowledgeSearchExposure: 'direct' | 'hidden' | undefined;
+  const syncKnowledgeSearchExposure = (ctx?: ExtensionContext): void => {
+    try {
+      const mode = getConfig(ctx?.cwd ?? (pi as any).cwd, 'pi').KNOWLEDGE_STORE_MODE;
+      const want: 'direct' | 'hidden' = mode === 'none' ? 'hidden' : 'direct';
+      if (want === knowledgeSearchExposure) return;
+      pi.registerTool({ ...researchKnowledgeSearchTool, exposure: want });
+      knowledgeSearchExposure = want;
+      logger.debug(`[pi-research] research_knowledge_search exposure → ${want}`);
+    } catch (err) {
+      logger.debug('[pi-research] could not sync research_knowledge_search exposure:', err);
+    }
+  };
+  syncKnowledgeSearchExposure();
+  pi.on('session_start', async (_event: any, ctx: ExtensionContext) => {
+    syncKnowledgeSearchExposure(ctx);
+  });
 
   // Alt+P — Pop queued steering messages out of the research queue and steer pi with them.
   pi.registerShortcut(Key.alt('p'), {
@@ -435,7 +464,7 @@ export default async function (pi: ExtensionAPI) {
           { query: text, depth: config.DEFAULT_RESEARCH_DEPTH },
           ctx.signal,
           undefined,
-          ctx,
+          asToolExecContext(ctx),
         );
 
         const output = extractResultText(result);
@@ -525,7 +554,7 @@ export default async function (pi: ExtensionAPI) {
           { queries: [text] },
           ctx.signal,
           undefined,
-          ctx,
+          asToolExecContext(ctx),
         );
 
         const output = extractResultText(result);

package/src/infrastructure/browser/thread-worker.mjs

@@ -149,7 +149,7 @@ var init_user_agent = __esm({
 });
 
 // src/web-research/scraper-types.ts
-var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN;
+var MAX_HTML_SIZE, MAX_PDF_SIZE, INTERNAL_NETWORK_PATTERNS, FILTERED_TAGS, BOT_PATTERNS, IMAGE_LINK_PATTERN, MARKDOWN_IMAGE_PATTERN, EMPTY_FRAGMENT_LINK_PATTERN;
 var init_scraper_types = __esm({
   "src/web-research/scraper-types.ts"() {
     "use strict";
@@ -215,6 +215,7 @@ var init_scraper_types = __esm({
     ];
     IMAGE_LINK_PATTERN = /\[([^\]]*)\]\((data:image\/[^)]+|[^)\s]+\.(?:svg|png|jpe?g|gif|webp|bmp|ico)(?:\?[^)]*)?)\)/gi;
     MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((?:data:image\/[^)]+|[^)\s]+)\)/gi;
+    EMPTY_FRAGMENT_LINK_PATTERN = /\[\]\(#[^)\s]*(?:\s+"[^"\n]*")?\)/g;
   }
 });
 
@@ -1559,6 +1560,7 @@ var init_browser_error_utils = __esm({
 // src/web-research/scraper-utils.ts
 var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
+  cleanConvertedMarkdown: () => cleanConvertedMarkdown,
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
@@ -1569,7 +1571,9 @@ __export(scraper_utils_exports, {
   isBenignScrapeFailure: () => isBenignScrapeFailure,
   isSsrfBlockError: () => isSsrfBlockError,
   ssrfSafeLookup: () => ssrfSafeLookup,
+  stripEmptyFragmentLinks: () => stripEmptyFragmentLinks,
   stripImageLinks: () => stripImageLinks,
+  trimFrontMatter: () => trimFrontMatter,
   validateContent: () => validateContent,
   validateUrlForSSRF: () => validateUrlForSSRF,
   validateUrlForSSRFSync: () => validateUrlForSSRFSync
@@ -1785,6 +1789,34 @@ function isMappedLoopback(ip) {
   const mapped = extractMappedIpv4(ip.toLowerCase().replace(/^\[|\]$/g, ""));
   return mapped !== null && /^127\./.test(mapped);
 }
+function stripEmptyFragmentLinks(markdown) {
+  return markdown.replace(EMPTY_FRAGMENT_LINK_PATTERN, "");
+}
+function trimFrontMatter(markdown) {
+  if (!markdown.startsWith("---\n")) return markdown;
+  const close = markdown.indexOf("\n---\n", 3);
+  if (close === -1 || close > MAX_FRONT_MATTER_CHARS) return markdown;
+  const entries = [];
+  for (const line of markdown.slice(4, close).split("\n")) {
+    const m = FRONT_MATTER_KEY.exec(line);
+    if (m) entries.push({ key: m[1].toLowerCase(), lines: [line] });
+    else if (entries.length) entries[entries.length - 1].lines.push(line);
+  }
+  const kept = [];
+  for (const slot of FRONT_MATTER_SLOTS) {
+    const entry = slot.map((key) => entries.find((e) => e.key === key)).find((e) => e !== void 0);
+    if (entry) kept.push(...entry.lines);
+  }
+  const rest = markdown.slice(close + 5).replace(/^\n+/, "");
+  return kept.length ? `---
+${kept.join("\n")}
+---
+
+${rest}` : rest;
+}
+function cleanConvertedMarkdown(markdown) {
+  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+}
 function stripImageLinks(markdown) {
   return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -1798,7 +1830,7 @@ function createNativeMarkdownConverter(nativeModule) {
       codeBlockStyle: nativeModule.CodeBlockStyle.Backticks,
       wrap: false
     });
-    return stripImageLinks(result.content ?? "");
+    return cleanConvertedMarkdown(result.content ?? "");
   };
 }
 function createJsMarkdownConverter() {
@@ -1809,7 +1841,7 @@ function createJsMarkdownConverter() {
   });
   return async (html) => {
     const markdown = converter.translate(html);
-    return stripImageLinks(markdown);
+    return cleanConvertedMarkdown(markdown);
   };
 }
 function validateContent(html, markdown, url) {
@@ -1848,7 +1880,7 @@ function validateContent(html, markdown, url) {
     throw error;
   }
 }
-var cachedSsrfFetcher;
+var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY;
 var init_scraper_utils = __esm({
   "src/web-research/scraper-utils.ts"() {
     "use strict";
@@ -1858,6 +1890,23 @@ var init_scraper_utils = __esm({
     init_scraper_types();
     init_browser_error_utils();
     cachedSsrfFetcher = void 0;
+    FRONT_MATTER_SLOTS = [
+      ["title", "meta-og:title", "meta-citation_title"],
+      ["meta-description", "description", "meta-og:description", "meta-twitter:description"],
+      ["meta-author", "meta-article:author", "meta-citation_author", "meta-dc.creator", "meta-dcterms.creator"],
+      [
+        "meta-article:published_time",
+        "meta-citation_publication_date",
+        "meta-citation_date",
+        "meta-dcterms.date",
+        "meta-dc.date",
+        "meta-date",
+        "meta-dcterms.created"
+      ],
+      ["meta-article:modified_time", "meta-dcterms.modified"]
+    ];
+    MAX_FRONT_MATTER_CHARS = 2e4;
+    FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
   }
 });
 
@@ -2745,12 +2794,19 @@ var ConfigSchema = Type.Object({
    *  (default: 5; 1 = every query). Configured via env/config file; not surfaced
    *  in the config TUI. */
   YOUTUBE_QUERY_EVERY_N: Type.Number({ minimum: 1, maximum: 100, default: 5 }),
-  /** Max queries per `search` call in quick (depth 0) research (default: 5, range: 1-10).
+  /** Max queries per `search` call in quick (depth 0) research (default: 3, range: 1-10).
    *  Applies to every quick run — the pi extension tool, the CLI, and the SDK's
    *  `--depth 0` — since all three share the same researcher session factory. The
    *  ceiling is 10 so quick mode can never exceed the old 5–10 prompt guidance.
    *  Configured via env/config file; not surfaced in the config TUI. */
-  QUICK_MAX_QUERIES: Type.Number({ minimum: 1, maximum: 10, default: 5 }),
+  QUICK_MAX_QUERIES: Type.Number({ minimum: 1, maximum: 10, default: 3 }),
+  /** Max URLs scraped per `scrape` call in quick (depth 0) research (default: 5,
+   *  range: 1-20). Quick mode is for single-fact lookups, where the deep default
+   *  (MAX_SCRAPE_URLS, 8) pulls in pages the question does not need; its per-batch
+   *  budget is therefore separate. Batches are still capped by MAX_SCRAPE_BATCHES.
+   *  Applies to every quick run (pi extension tool, CLI, SDK `--depth 0`).
+   *  Configured via env/config file; not surfaced in the config TUI. */
+  QUICK_MAX_SCRAPE_URLS: Type.Number({ minimum: 1, maximum: 20, default: 5 }),
   /** Health check timeout in milliseconds (default: 10000ms) */
   HEALTH_CHECK_TIMEOUT_MS: Type.Number({ minimum: 2e3, maximum: 12e4, default: 1e4 }),
   /** Default timeout for browser page operations like search (default: 45000ms) */

package/src/orchestration/quick-research-orchestrator.ts

@@ -142,7 +142,14 @@ export class QuickResearchOrchestrator {
         }
         }
 
-        const researcherPromptTemplate = loadPrompt('researcher');
+        // Quick mode has its own, much shorter system prompt. The deep researcher
+        // prompt is written for a multi-round, sibling-coordinated, "exhaustive
+        // detail" report; reusing it here (with two placeholders blanked) fought
+        // every one of quick mode's design goals: it asked for a report where the
+        // deliverable is an answer, it advertised scrape rounds 2+ and a Session URL
+        // Pool quick runs cannot have, and "omitting information is a failure"
+        // pushed volume on a single-fact lookup.
+        const researcherPromptTemplate = loadPrompt('quick-researcher');
         // Resolve the model here (same deterministic inputs createResearcherSession
         // below will resolve again) purely to learn whether prompt caching will be
         // active, so the batch count told to the model in the prompt below matches
@@ -155,6 +162,10 @@ export class QuickResearchOrchestrator {
         const maxScrapeBatchesDisplay = maxScrapeBatches > 99 ? 'unlimited' : maxScrapeBatches.toString();
 
         const maxQueries = this.config.QUICK_MAX_QUERIES;
+        // The quick per-batch URL budget: the same value createResearcherSession
+        // hands the scrape tool below, so the number the model reads is the number
+        // the tool enforces.
+        const maxScrapeUrls = this.config.QUICK_MAX_SCRAPE_URLS;
         const quickEvidenceSection =
             '## Search\n' +
             `You have access to the \`search\` tool. You get EXACTLY ONE search call — make it count.\n` +
@@ -163,8 +174,8 @@ export class QuickResearchOrchestrator {
             `For roughly one in ${this.config.YOUTUBE_QUERY_EVERY_N} of your queries, append the word 'youtube' (e.g. "<topic> explained youtube") — DuckDuckGo rarely surfaces YouTube otherwise, and YouTube links let you read video transcripts.\n` +
             'Your goal is to gather a focused, high-quality pool of initial links.\n\n' +
             '## Scrape\n' +
-            `After searching, scrape the best sources using the \`scrape\` tool (up to ${maxScrapeBatchesDisplay} batches, up to ${this.config.MAX_SCRAPE_URLS} URLs each).\n` +
-            'Prioritize primary sources and authoritative data.';
+            `After searching, scrape the sources that can answer the question using the \`scrape\` tool (up to ${maxScrapeBatchesDisplay} batches, up to ${maxScrapeUrls} URLs each).\n` +
+            'Prioritize primary sources and authoritative data. Stop once the answer is sourced.';
         
         // Consume queued steering messages before starting
         consumeQueuedMessages(this.options.sessionId);
@@ -187,14 +198,11 @@ export class QuickResearchOrchestrator {
         // prefix providers key on, so back-to-back quick runs (and every follow-up
         // turn within this session) reuse it via prompt-cache reads.
         const prompt = injectCurrentDate(researcherPromptTemplate, 'researcher')
-            .replace('{{extra_tool_guidelines}}', '- `search`: Perform broad web searches (Round 1 only).')
+            .replace('{{extra_tool_guidelines}}', '- `search`: one web search call, executed up front.')
             // Config-driven, mirroring researcher-executor: the prompt's per-batch
-            // target can never drift from the cap the scrape tool enforces.
+            // cap can never drift from the cap the scrape tool enforces.
             // replaceAll — the template states the budget more than once.
-            .replaceAll('{{max_scrape_urls}}', String(this.config.MAX_SCRAPE_URLS))
-            // Quick research has no research lead and no next round — see
-            // RESEARCHER_DIGEST_SECTION. Its report IS the deliverable.
-            .replace('{{digest_section}}', '')
+            .replaceAll('{{max_scrape_urls}}', String(maxScrapeUrls))
             .trim();
 
         // `$`-bearing dynamic content (the user query, store descriptions, steering)
@@ -219,6 +227,7 @@ export class QuickResearchOrchestrator {
           excludeTools: resolveExcludedTools(this.options.excludeTools),
           config: this.config,
           maxSearchQueries: this.config.QUICK_MAX_QUERIES,
+          maxScrapeUrls: this.config.QUICK_MAX_SCRAPE_URLS,
           getGlobalState: (): SystemResearchState => ({
             version: 1,
             researchId: this.options.researchId,

package/src/orchestration/researcher.ts

@@ -45,6 +45,8 @@ export interface CreateResearcherSessionOptions {
   config?: Config;
   /** Overrides the search tool's query cap (default 30). Quick research passes QUICK_MAX_QUERIES. */
   maxSearchQueries?: number;
+  /** Overrides the scrape tool's per-call URL cap (default MAX_SCRAPE_URLS). Quick research passes QUICK_MAX_SCRAPE_URLS. */
+  maxScrapeUrls?: number;
 }
 
 export interface ResolvedResearcherSession {
@@ -68,6 +70,7 @@ export async function createResearcherSession(options: CreateResearcherSessionOp
     excludeTools = [],
     config,
     maxSearchQueries,
+    maxScrapeUrls,
   } = options;
 
   if (!systemPrompt || typeof systemPrompt !== 'string') {
@@ -104,6 +107,7 @@ export async function createResearcherSession(options: CreateResearcherSessionOp
       onSearchProgress: onSearchProgress,
       onUrlScrapeResult: onUrlScrapeResult,
       maxSearchQueries,
+      maxScrapeUrls,
       getTokensUsed: () => {
         if (!sessionRef.session) return 0;