@lincoln504/pi-research 1.7.6 → 1.7.8

package/README.md

@@ -92,7 +92,7 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 - Node.js >= 22.22.2
 - An LLM with a 100k+ context window (an API key or a local model)
 - Internet access on a residential IP, since search, scraping, and YouTube transcripts get bot-blocked from datacenter/VPS/cloud IPs
-- pi. The pi extension uses the host's copy while the standalone CLI and agent skill install it as a dependency.
+- pi (`@earendil-works/pi-coding-agent`) 0.99.0 or newer, including the 1.x line. The pi extension uses the host's copy while the standalone CLI and agent skill install it as a dependency. A host newer than the last version this release was tested against still runs, with a one-line notice; the tested ceiling is in `src/core/pi-version.ts`.
 - Local knowledge-store embeddings need `@huggingface/transformers`, an optional dependency. If its native image chain (sharp) cannot install, npm skips it with a warning and the install still succeeds, so everything works except local embeddings. The store tells you how to restore them. Prefer no embedding model at all? Set `PI_RESEARCH_KNOWLEDGE_STORE_RETRIEVAL=bm25` for a pure lexical (BM25) knowledge store — see [KNOWLEDGE-STORE.md](docs/KNOWLEDGE-STORE.md).
 - Cloudflare Turnstile and similar systems block scraping on some sites. A run compensates with a wide pool of search results to scrape.
 

package/agent-skill/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.7.6", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.7.8", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli-bin.mjs

@@ -37,7 +37,13 @@
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
+const REQUIRED_PEERS = [
+  '@earendil-works/pi-ai',
+  '@earendil-works/pi-coding-agent',
+  // dist/cli.mjs imports it directly (TUI width helpers), so an install that skips
+  // peers can lack it even though pi-coding-agent normally brings it in.
+  '@earendil-works/pi-tui',
+];
 
 /**
  * Probe one peer dependency.

package/dist/cli.mjs

@@ -230,7 +230,12 @@ function redactSecrets(message) {
   out = out.replace(BASIC_AUTH_PATTERN, "Basic [REDACTED]");
   out = out.replace(BEARER_AUTH_PATTERN, "Bearer [REDACTED]");
   out = out.replace(COOKIE_HEADER_PATTERN, (_m, key, sep3) => `${key}${sep3}[REDACTED]`);
-  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep3) => `${key}${sep3}[REDACTED]`);
+  out = out.replace(AUTH_SCHEME_PATTERN, (_m, key, sep3, scheme) => `${key}${sep3}${scheme} [REDACTED]`);
+  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep3, val) => {
+    const q = val[0] === '"' || val[0] === "'" ? val[0] : "";
+    const closed = q !== "" && val.length > 1 && val.endsWith(q);
+    return `${key}${sep3}${q}[REDACTED]${closed ? q : ""}`;
+  });
   out = out.replace(KNOWN_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(PROVIDER_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(LONG_HEX_SECRET_PATTERN, "[REDACTED]");
@@ -249,7 +254,7 @@ function redactSecrets(message) {
 function stripTerminalEscapes(message) {
   return message.replace(TERMINAL_ESCAPE_PATTERN, "").replace(CONTROL_CHARS_PATTERN, " ");
 }
-var logContextStorage, MAX_LOG_MESSAGE_LENGTH, ANSI_PATTERN, URL_CREDENTIALS_PATTERN, B_LEFT, B_RIGHT, COOKIE_HEADER_PATTERN, SENSITIVE_KV_PATTERN, KNOWN_TOKEN_PATTERN, JWT_PATTERN, BASIC_AUTH_PATTERN, BEARER_AUTH_PATTERN, PROVIDER_TOKEN_PATTERN, LONG_HEX_SECRET_PATTERN, CONTROL_CHARS_PATTERN, REDACT_SCAN_LENGTH, TOKEN_CHAR_PATTERN, REDACT_SCAN_EXTENSION_MAX, TERMINAL_ESCAPE_PATTERN;
+var logContextStorage, MAX_LOG_MESSAGE_LENGTH, ANSI_PATTERN, URL_CREDENTIALS_PATTERN, B_LEFT, B_RIGHT, COOKIE_HEADER_PATTERN, SENSITIVE_KV_PATTERN, AUTH_SCHEME_PATTERN, KNOWN_TOKEN_PATTERN, JWT_PATTERN, BASIC_AUTH_PATTERN, BEARER_AUTH_PATTERN, PROVIDER_TOKEN_PATTERN, LONG_HEX_SECRET_PATTERN, CONTROL_CHARS_PATTERN, REDACT_SCAN_LENGTH, TOKEN_CHAR_PATTERN, REDACT_SCAN_EXTENSION_MAX, TERMINAL_ESCAPE_PATTERN;
 var init_log_utils = __esm({
   "src/utils/log-utils.ts"() {
     "use strict";
@@ -264,7 +269,11 @@ var init_log_utils = __esm({
       "gi"
     );
     SENSITIVE_KV_PATTERN = new RegExp(
-      `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|key)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([^\\s"',&)]+)`,
+      `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|token|key)${B_RIGHT}(["']?\\s*[:=]\\s*)("[^"\\r\\n]{0,1024}"|'[^'\\r\\n]{0,1024}'|["']?[^\\s"',&)]+)`,
+      "gi"
+    );
+    AUTH_SCHEME_PATTERN = new RegExp(
+      `${B_LEFT}(authorization)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([A-Za-z][A-Za-z0-9_-]{0,31})[ \\t]+[^\\s"',&)]+`,
       "gi"
     );
     KNOWN_TOKEN_PATTERN = new RegExp(
@@ -7959,7 +7968,7 @@ var init_store = __esm({
         if (this.db) return;
         try {
           if (!fs13.existsSync(this.options.dbDir)) {
-            fs13.mkdirSync(this.options.dbDir, { recursive: true });
+            fs13.mkdirSync(this.options.dbDir, { recursive: true, mode: 448 });
           }
           this.db = await (await getLancedb()).connect(this.options.dbDir);
           const tableNames = await this.db.tableNames();
@@ -9928,6 +9937,25 @@ var init_cancellation = __esm({
   }
 });
 
+// src/tools/tool-metadata.ts
+var PI_RESEARCH_TOOL_NAMESPACE, KNOWLEDGE_SEARCH_TOOL_ANNOTATIONS;
+var init_tool_metadata = __esm({
+  "src/tools/tool-metadata.ts"() {
+    "use strict";
+    PI_RESEARCH_TOOL_NAMESPACE = {
+      name: "pi-research",
+      description: "Web research, knowledge-store search, and system health checks.",
+      instructions: "research_knowledge_search is a local lookup and should be tried before research: a complete hit answers the question without any live work. research runs a multi-agent web investigation and takes minutes. health reports local service status and is the cheapest of the three."
+    };
+    KNOWLEDGE_SEARCH_TOOL_ANNOTATIONS = {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true
+    };
+  }
+});
+
 // src/tools/research-knowledge-types.ts
 import { Type as Type9 } from "typebox";
 var AnswerStatusEnum, ResearchKnowledgeSynthesisResponseSchema, ResearchKnowledgeSynthesisResponseSchemaAsTSchema, KnowledgeRelevanceTriageSchema;
@@ -10473,6 +10501,8 @@ function createResearchKnowledgeSearchTool(iface) {
       "Do not call knowledge search and research for the same query in the same turn \u2014 wait for the result."
     ],
     parameters: ResearchKnowledgeSearchParams,
+    annotations: KNOWLEDGE_SEARCH_TOOL_ANNOTATIONS,
+    namespace: PI_RESEARCH_TOOL_NAMESPACE,
     executionMode: "parallel",
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
       const startTime = Date.now();
@@ -10599,6 +10629,7 @@ var init_research_knowledge_search = __esm({
     init_llm_utils();
     init_service_registry();
     init_llm_timeout();
+    init_tool_metadata();
     init_retry_utils();
     init_service_interfaces();
     init_research_knowledge_types();
@@ -18981,10 +19012,29 @@ ${kept.join("\n")}
 ${rest}` : rest;
 }
 function cleanConvertedMarkdown(markdown) {
-  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+  return collapseBlankLines(stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown)))).trim();
+}
+var CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/;
+function collapseBlankLines(markdown) {
+  if (!markdown.includes("\n\n\n")) return markdown;
+  const out = [];
+  let fence = null;
+  for (const line of markdown.split("\n")) {
+    const m = CODE_FENCE.exec(line);
+    if (fence === null) {
+      if (m) fence = m[1];
+    } else if (m && m[1][0] === fence[0] && m[1].length >= fence.length && line.slice(m[0].length).trim() === "") {
+      fence = null;
+    }
+    if (fence === null && line === "" && out.length > 0 && out[out.length - 1] === "") continue;
+    out.push(line);
+  }
+  return out.join("\n");
 }
 function stripImageLinks(markdown) {
-  return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
+  return collapseBlankLines(
+    markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1")
+  ).trim();
 }
 function createNativeMarkdownConverter(nativeModule) {
   return async (html) => {
@@ -27172,7 +27222,7 @@ async function exportResearchReport(query, result, _mode, cwd, explicitDir) {
     const filename = `${baseFilename}-${hash}.md`;
     const filepath = join21(targetDir, filename);
     try {
-      await fs15.writeFile(filepath, result, { flag: "wx" });
+      await fs15.writeFile(filepath, result, { flag: "wx", mode: 384 });
       logger.log(`[export] Research report saved to: ${filepath}`);
       return filepath;
     } catch (error) {
@@ -27501,6 +27551,10 @@ function configBlock(det, extraNote) {
   if (extraNote) lines.push(`  \u2022 note:               ${extraNote}`);
   return lines.join("\n");
 }
+function resolveCliDepth(explicit, cfg) {
+  const d = explicit ?? (cfg.QUICK_RESEARCH ? cfg.DEFAULT_RESEARCH_DEPTH : Math.max(1, cfg.DEFAULT_RESEARCH_DEPTH));
+  return d;
+}
 async function cmdResearch(args) {
   const det = await detectCredentials(args.model);
   if (det.problem) {
@@ -27523,7 +27577,7 @@ Error: ${vmsg}
 `);
     return EXIT.USAGE;
   }
-  const depth = args.depth ?? getConfig(process.cwd(), "cli").DEFAULT_RESEARCH_DEPTH;
+  const depth = resolveCliDepth(args.depth, getConfig(process.cwd(), "cli"));
   const runModel = det.model;
   toStderr(`[pi-research] starting research (depth ${depth})${runModel ? ` with ${runModel}` : ""}\u2026
 `);
@@ -28496,5 +28550,6 @@ export {
   exitCodeForSignal,
   makeProgressObserver,
   parseArgs,
-  reportError
+  reportError,
+  resolveCliDepth
 };

package/dist/pdf-extract-worker.mjs

@@ -213,7 +213,11 @@ var COOKIE_HEADER_PATTERN = new RegExp(
   "gi"
 );
 var SENSITIVE_KV_PATTERN = new RegExp(
-  `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|key)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([^\\s"',&)]+)`,
+  `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|token|key)${B_RIGHT}(["']?\\s*[:=]\\s*)("[^"\\r\\n]{0,1024}"|'[^'\\r\\n]{0,1024}'|["']?[^\\s"',&)]+)`,
+  "gi"
+);
+var AUTH_SCHEME_PATTERN = new RegExp(
+  `${B_LEFT}(authorization)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([A-Za-z][A-Za-z0-9_-]{0,31})[ \\t]+[^\\s"',&)]+`,
   "gi"
 );
 var KNOWN_TOKEN_PATTERN = new RegExp(
@@ -251,7 +255,12 @@ function redactSecrets(message) {
   out = out.replace(BASIC_AUTH_PATTERN, "Basic [REDACTED]");
   out = out.replace(BEARER_AUTH_PATTERN, "Bearer [REDACTED]");
   out = out.replace(COOKIE_HEADER_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
-  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
+  out = out.replace(AUTH_SCHEME_PATTERN, (_m, key, sep, scheme) => `${key}${sep}${scheme} [REDACTED]`);
+  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep, val) => {
+    const q = val[0] === '"' || val[0] === "'" ? val[0] : "";
+    const closed = q !== "" && val.length > 1 && val.endsWith(q);
+    return `${key}${sep}${q}[REDACTED]${closed ? q : ""}`;
+  });
   out = out.replace(KNOWN_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(PROVIDER_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(LONG_HEX_SECRET_PATTERN, "[REDACTED]");

package/dist/thread-worker.mjs

@@ -60,7 +60,12 @@ function redactSecrets(message) {
   out = out.replace(BASIC_AUTH_PATTERN, "Basic [REDACTED]");
   out = out.replace(BEARER_AUTH_PATTERN, "Bearer [REDACTED]");
   out = out.replace(COOKIE_HEADER_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
-  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
+  out = out.replace(AUTH_SCHEME_PATTERN, (_m, key, sep, scheme) => `${key}${sep}${scheme} [REDACTED]`);
+  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep, val) => {
+    const q = val[0] === '"' || val[0] === "'" ? val[0] : "";
+    const closed = q !== "" && val.length > 1 && val.endsWith(q);
+    return `${key}${sep}${q}[REDACTED]${closed ? q : ""}`;
+  });
   out = out.replace(KNOWN_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(PROVIDER_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(LONG_HEX_SECRET_PATTERN, "[REDACTED]");
@@ -79,7 +84,7 @@ function redactSecrets(message) {
 function stripTerminalEscapes(message) {
   return message.replace(TERMINAL_ESCAPE_PATTERN, "").replace(CONTROL_CHARS_PATTERN, " ");
 }
-var logContextStorage, MAX_LOG_MESSAGE_LENGTH, ANSI_PATTERN, URL_CREDENTIALS_PATTERN, B_LEFT, B_RIGHT, COOKIE_HEADER_PATTERN, SENSITIVE_KV_PATTERN, KNOWN_TOKEN_PATTERN, JWT_PATTERN, BASIC_AUTH_PATTERN, BEARER_AUTH_PATTERN, PROVIDER_TOKEN_PATTERN, LONG_HEX_SECRET_PATTERN, CONTROL_CHARS_PATTERN, REDACT_SCAN_LENGTH, TOKEN_CHAR_PATTERN, REDACT_SCAN_EXTENSION_MAX, TERMINAL_ESCAPE_PATTERN;
+var logContextStorage, MAX_LOG_MESSAGE_LENGTH, ANSI_PATTERN, URL_CREDENTIALS_PATTERN, B_LEFT, B_RIGHT, COOKIE_HEADER_PATTERN, SENSITIVE_KV_PATTERN, AUTH_SCHEME_PATTERN, KNOWN_TOKEN_PATTERN, JWT_PATTERN, BASIC_AUTH_PATTERN, BEARER_AUTH_PATTERN, PROVIDER_TOKEN_PATTERN, LONG_HEX_SECRET_PATTERN, CONTROL_CHARS_PATTERN, REDACT_SCAN_LENGTH, TOKEN_CHAR_PATTERN, REDACT_SCAN_EXTENSION_MAX, TERMINAL_ESCAPE_PATTERN;
 var init_log_utils = __esm({
   "src/utils/log-utils.ts"() {
     "use strict";
@@ -94,7 +99,11 @@ var init_log_utils = __esm({
       "gi"
     );
     SENSITIVE_KV_PATTERN = new RegExp(
-      `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|key)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([^\\s"',&)]+)`,
+      `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|token|key)${B_RIGHT}(["']?\\s*[:=]\\s*)("[^"\\r\\n]{0,1024}"|'[^'\\r\\n]{0,1024}'|["']?[^\\s"',&)]+)`,
+      "gi"
+    );
+    AUTH_SCHEME_PATTERN = new RegExp(
+      `${B_LEFT}(authorization)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([A-Za-z][A-Za-z0-9_-]{0,31})[ \\t]+[^\\s"',&)]+`,
       "gi"
     );
     KNOWN_TOKEN_PATTERN = new RegExp(
@@ -1561,6 +1570,7 @@ var init_browser_error_utils = __esm({
 var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
   cleanConvertedMarkdown: () => cleanConvertedMarkdown,
+  collapseBlankLines: () => collapseBlankLines,
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
@@ -1815,10 +1825,28 @@ ${kept.join("\n")}
 ${rest}` : rest;
 }
 function cleanConvertedMarkdown(markdown) {
-  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+  return collapseBlankLines(stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown)))).trim();
+}
+function collapseBlankLines(markdown) {
+  if (!markdown.includes("\n\n\n")) return markdown;
+  const out = [];
+  let fence = null;
+  for (const line of markdown.split("\n")) {
+    const m = CODE_FENCE.exec(line);
+    if (fence === null) {
+      if (m) fence = m[1];
+    } else if (m && m[1][0] === fence[0] && m[1].length >= fence.length && line.slice(m[0].length).trim() === "") {
+      fence = null;
+    }
+    if (fence === null && line === "" && out.length > 0 && out[out.length - 1] === "") continue;
+    out.push(line);
+  }
+  return out.join("\n");
 }
 function stripImageLinks(markdown) {
-  return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
+  return collapseBlankLines(
+    markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1")
+  ).trim();
 }
 function createNativeMarkdownConverter(nativeModule) {
   return async (html) => {
@@ -1880,7 +1908,7 @@ function validateContent(html, markdown, url) {
     throw error;
   }
 }
-var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY;
+var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY, CODE_FENCE;
 var init_scraper_utils = __esm({
   "src/web-research/scraper-utils.ts"() {
     "use strict";
@@ -1907,6 +1935,7 @@ var init_scraper_utils = __esm({
     ];
     MAX_FRONT_MATTER_CHARS = 2e4;
     FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
+    CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/;
   }
 });
 

package/docs/ARCHITECTURE.md

@@ -372,7 +372,8 @@ changes which pairing needs re-validating.
 
 Pinned validation library — `typebox` (TypeBox 1.x, unscoped package name) is pinned to the
 exact version the pi host packages depend on (`@earendil-works/pi-ai` /
-`@earendil-works/pi-coding-agent` 0.99.2 both pin `1.3.27` — verified 2026-10-01, after an
+`@earendil-works/pi-coding-agent` 1.0.0 both pin `1.3.27` — verified 2026-10-01 against 1.0.0 
+(and against 0.99.2 before it), after an
 undocumented drift was caught in the 0.84/0.85 era and realigned; that drift was to `1.3.26`,
 and the version now pinned is `1.3.27`, both re-checked directly in the installed host
 packages' `package.json`). Every

package/docs/CHANGELOG.md

@@ -5,13 +5,34 @@ 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.8] - 2026-10-01
+
+### Fixed
+
+- **Scraped code blocks keep their blank lines.** `cleanConvertedMarkdown` and `stripImageLinks` collapsed every run of blank lines across the whole document, fenced code included, so a PEP 8 two-blank-line gap, a Makefile or preformatted ASCII was altered in what was stored and cited. The collapse now skips fenced blocks (backtick or tilde, closing fence at least as long as the opening one, an unclosed fence running to the end as in CommonMark) and still tidies prose. Empty-anchor removal still applies inside code on purpose: that is where Quarto/nbdev emit them.
+- **`pi-research research` honours the quick-mode gate for a config-derived depth.** `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH=0` with `QUICK_RESEARCH` off ran quick mode from the CLI, while the documented rule, and the pi tool path, resolve it to 1. An explicit `--depth 0` still runs quick mode, as the skill documents. The rule now lives in one tested function, `resolveCliDepth`.
+- **Log redaction covers more credential shapes.** A bare `token` key (`token=…`, `GITHUB_TOKEN=…`, `?token=…`) was not masked, a quoted value was cut at its first space, comma or ampersand (`password="a b"` left ` b"` in the log), and `Authorization: Token <credential>` (any scheme other than Bearer/Basic) masked only the scheme word. Quoted values are now consumed whole under a 1024-character bound, so the scan stays linear (measured on adversarial 40k inputs: single-digit milliseconds). Plural counters such as `max_tokens=4096` are deliberately not matched.
+- **The `pi-research` bin shim also checks `@earendil-works/pi-tui`.** `dist/cli.mjs` imports it directly, but the preflight only listed `pi-ai` and `pi-coding-agent`, so a peer-skipping install lacking only `pi-tui` still died with a raw `ERR_MODULE_NOT_FOUND`.
+- **Local files that hold research content are no longer group/world readable by default.** The knowledge store directory is created `0700` and exported research reports are written `0600` (previously the process umask decided, typically `0775`/`0644`, and exports can fall back to the shared temp directory). An existing directory is not re-chmodded.
+
+## [1.7.7] - 2026-10-01
+
+### Changed
+
+- **pi 1.0.0 support.** The peer ranges said `>=0.99.0 <1`, which excluded the current pi release: a standalone install resolved 0.99.x while the user's pi was 1.0.0, and the extension printed an untested-host notice on every session. The ranges are now `>=0.99.0 <2` and the tested ceiling is 1.0.0. The whole public surface was diffed 0.99.2 -> 1.0.0: `@earendil-works/pi-ai` is identical in its declarations, the extension API (`core/extensions/index.d.ts`, the file every tool, event and context type comes from) is unchanged, and `docs/extensions.md` is unchanged. `pi-coding-agent` adds `ModelRegistry.generateImages()` and widens `quietStartup` to `boolean | "header"`; `pi-tui` adds `isAppleTerminalSession`, `flattenLines()` and `TUI.getScreenLines()`. Nothing was removed or re-signed, so the 0.99.0 floor still describes the oldest host those APIs exist on, and the version number is a milestone rather than a break for this package. Verified by installing 1.0.0 into this repo, type-checking both projects against it, running the unit and integration suites (254 files / 3207 tests, 57 + 103 integration), and calling the `health` tool through a real pi 1.0.0 session. Two 1.0.0 behaviour changes are worth knowing and change nothing here: the TUI now defaults to fullscreen (this extension renders through `ctx.ui.*` widgets, which work in both modes) and built-in extensions and tools are named `builtin:<name>` in errors and diagnostics.
+- **The three tools declare MCP-style `annotations` and one shared `namespace`.** Both fields arrived in pi 0.99 and are surfaced by 1.0.0: `pi.getAllTools()` reports them, the documented permission pattern reads the annotations to decide which calls to confirm, and codemode lists the tools of one namespace under a single heading. `research` and `research_knowledge_search` are declared `openWorldHint: true` because they reach the network and spend provider tokens, `health` is `idempotentHint: true` and closed-world, and all three are `readOnlyHint: false` with `destructiveHint: false`: they append to the knowledge store, and `health` with `probe: true` starts the browser pool. The hints are author-declared and unverified, so they under-claim deliberately, because `readOnlyHint` is the one hint that can suppress a confirmation a user should have been asked for.
+
+### Fixed
+
+- Host-version references in `docs/ARCHITECTURE.md` and the ES/JA/ZH docs said the typebox pin was verified against 0.99.2. It is still `1.3.27` in both host packages, re-verified against 1.0.0, and the docs now say so. The README requirements state the supported host range and that a host newer than the tested ceiling still runs, with a one-line notice.
+
 ## [1.7.6] - 2026-10-01
 
 ### Fixed
 
 - **The missing-peer remedy names the package that is actually missing.** The 1.7.5 shim's bullet list correctly enumerated every absent `@earendil-works/pi-*` package, but the command underneath it was hardcoded to `npm install -g @earendil-works/pi-coding-agent` with the comment "add just the missing host package". When `pi-ai` (and not `pi-coding-agent`) was the absent one, the instruction named a package the user already had and following it changed nothing. The remedy is now built from the detected set, so both peers are named when both are missing and only the absent one is named otherwise. Caught in review; pinned by a test that asserts the present package is never the one the remedy suggests installing.
 - **The bin preflight detects an install whose files are incomplete, not just an absent package.** It resolved each peer and treated a successful resolve as healthy. Resolving is not loading: an interrupted install, a pruned `node_modules` or a bad package-cache restore leaves `package.json` and its `exports` map intact with the file they point at gone, so the preflight passed it through and the bundle died on that import with the raw `ERR_MODULE_NOT_FOUND` the shim exists to replace. The preflight now also checks that the resolved file exists and reports `installed, but its files are incomplete` with the same exit 78. Checked with `existsSync` rather than by importing the module, which would run the host packages' side effects before the CLI has decided to start. Verified by reverting each half in isolation: without the `argv[1]` rewrite the stub engine exits 97, with a resolve-only preflight a deliberately truncated peer produces `ERR_MODULE_NOT_FOUND`, and the fixed shim produces exit 78.
-- **`dist/cli-bin.mjs` ships executable.** It was published at mode 644 against 755 for `dist/cli.mjs`, because the build copies it with `copyFileSync`, which preserves the committed source mode. Every package manager chmods the declared `bin` target itself, so no install was broken, but the shipped artifact should not depend on that. The build now chmods 755 and the source is committed executable.
+- **`dist/cli-bin.mjs` ships executable.** It went out at mode 644 because the build copies it with `copyFileSync`, which preserves the committed source mode. No install was broken by that: npm, pnpm and bun each chmod the declared `bin` target when they link it, which is how 1.7.5 worked. The point is not to depend on it, since the bin is the one file a shell may execute directly. The build now chmods 755 after the copy and the source is committed executable. (Measured correction, 2026-10-01: this entry first said `dist/cli.mjs` shipped at 755 for contrast. It does not. npm publishes every file in this package at 644, `dist/cli.mjs` included, in both the 1.7.5 and 1.7.6 tarballs. That file is never executed directly, only via `node` or a manager-generated shim, so its mode does not matter.)
 
 ## [1.7.5] - 2026-10-01
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.7.6",
+  "version": "1.7.8",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,
@@ -133,9 +133,9 @@
     "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"
+    "@earendil-works/pi-ai": ">=0.99.0 <2",
+    "@earendil-works/pi-coding-agent": ">=0.99.0 <2",
+    "@earendil-works/pi-tui": ">=0.99.0 <2"
   },
   "optionalDependencies": {
     "@huggingface/transformers": "4.3.0",
@@ -159,9 +159,9 @@
     "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",
+    "@earendil-works/pi-ai": ">=0.99.0 <2",
+    "@earendil-works/pi-coding-agent": ">=0.99.0 <2",
+    "@earendil-works/pi-tui": ">=0.99.0 <2",
     "@eslint/js": "^10.0.1",
     "@types/jsdom": "^30.0.0",
     "@typescript-eslint/eslint-plugin": "8.71.0",

package/src/cli-bin.mjs

@@ -37,7 +37,13 @@
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-const REQUIRED_PEERS = ['@earendil-works/pi-ai', '@earendil-works/pi-coding-agent'];
+const REQUIRED_PEERS = [
+  '@earendil-works/pi-ai',
+  '@earendil-works/pi-coding-agent',
+  // dist/cli.mjs imports it directly (TUI width helpers), so an install that skips
+  // peers can lack it even though pi-coding-agent normally brings it in.
+  '@earendil-works/pi-tui',
+];
 
 /**
  * Probe one peer dependency.

package/src/cli.ts

@@ -580,6 +580,20 @@ interface ResearchArgs {
   json?: boolean;
 }
 
+
+/**
+ * Depth for a CLI research run. An explicit --depth 0 always runs quick mode (the
+ * documented CLI/skill entry). A CONFIG-derived default of 0 only does when
+ * QUICK_RESEARCH is on; otherwise it resolves to 1, as on the pi tool path.
+ */
+export function resolveCliDepth(
+  explicit: number | undefined,
+  cfg: { QUICK_RESEARCH: boolean; DEFAULT_RESEARCH_DEPTH: number },
+): 0 | 1 | 2 | 3 {
+  const d = explicit ?? (cfg.QUICK_RESEARCH ? cfg.DEFAULT_RESEARCH_DEPTH : Math.max(1, cfg.DEFAULT_RESEARCH_DEPTH));
+  return d as 0 | 1 | 2 | 3;
+}
+
 /**
  * Research subcommand. Initializes the SDK, runs deep/quick research, prints the
  * markdown report to stdout, and always shuts down (even on failure).
@@ -607,8 +621,7 @@ export async function cmdResearch(args: ResearchArgs): Promise<number> {
     return EXIT.USAGE;
   }
 
-  const depth: 0 | 1 | 2 | 3 =
-    (args.depth ?? getConfig(process.cwd(), 'cli').DEFAULT_RESEARCH_DEPTH) as 0 | 1 | 2 | 3;
+  const depth = resolveCliDepth(args.depth, getConfig(process.cwd(), 'cli'));
   // det.model already reflects --model-first precedence (detectCredentials above).
   const runModel = det.model;
   toStderr(`[pi-research] starting research (depth ${depth})${runModel ? ` with ${runModel}` : ''}…\n`);

package/src/core/pi-version.ts

@@ -7,10 +7,13 @@
  *
  *   - 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.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).
+ *   - As a standalone CLI/SDK, the range is `>=0.99.0 <2` and published tarballs
+ *     carry no lockfile, so every fresh install resolves the newest release in
+ *     that window at that instant. The host is young: a minor bump may break
+ *     anything under semver, and already has (0.83.0 extended the ResourceLoader
+ *     contract). The upper bound is `<2` rather than `<1` because 1.0.0 changed
+ *     no API this package uses — see the 1.0.0 note on the tested ceiling — and
+ *     `<1` would exclude the current release from a fresh install.
  *
  * Hence two thresholds, not one. Below the FLOOR we throw — those APIs are gone
  * and nothing will work. Above the TESTED ceiling we warn once and continue: a
@@ -102,8 +105,25 @@ export const PI_MIN_VERSION: SemverParts = { major: 0, minor: 99, patch: 0 };
  * Bump this — deliberately — when a new pi is verified, not automatically.
  * Compared on MAJOR.MINOR only: a patch bump within a tested line is not a new
  * surface, and warning on it would be noise.
+ *
+ * 1.0.0 is a major version number, not a breaking change for this package. The
+ * full public surface was diffed against 0.99.2 (2026-10-01): `@earendil-works/pi-ai`
+ * is byte-identical in its declarations, and the extension API
+ * (`core/extensions/index.d.ts`, the file every tool, event and context type
+ * comes from) is unchanged, as is `docs/extensions.md`. `pi-coding-agent` adds
+ * one method (`ModelRegistry.generateImages()`), widens `quietStartup` to
+ * `boolean | "header"`, and adds internal fields; `pi-tui` adds
+ * `isAppleTerminalSession`, `flattenLines()` and `TUI.getScreenLines()`.
+ * Nothing was removed or re-signed, so the 0.99.0 floor still describes the
+ * oldest host these APIs exist on.
+ *
+ * The behavioural changes in 1.0.0 that a user can notice are the fullscreen TUI
+ * default (this extension renders through `ctx.ui.*` widgets, which work in both
+ * modes), the `builtin:<name>` naming for built-in extensions and tools, and
+ * `--no-extensions` now also disabling the built-in extensions. None of them
+ * change what this package does.
  */
-export const PI_TESTED_MAX_VERSION: SemverParts = { major: 0, minor: 99, patch: 2 };
+export const PI_TESTED_MAX_VERSION: SemverParts = { major: 1, minor: 0, patch: 0 };
 
 export type PiCompatibilityLevel = 'ok' | 'unparseable' | 'too-old' | 'untested';
 

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

@@ -60,7 +60,12 @@ function redactSecrets(message) {
   out = out.replace(BASIC_AUTH_PATTERN, "Basic [REDACTED]");
   out = out.replace(BEARER_AUTH_PATTERN, "Bearer [REDACTED]");
   out = out.replace(COOKIE_HEADER_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
-  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
+  out = out.replace(AUTH_SCHEME_PATTERN, (_m, key, sep, scheme) => `${key}${sep}${scheme} [REDACTED]`);
+  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep, val) => {
+    const q = val[0] === '"' || val[0] === "'" ? val[0] : "";
+    const closed = q !== "" && val.length > 1 && val.endsWith(q);
+    return `${key}${sep}${q}[REDACTED]${closed ? q : ""}`;
+  });
   out = out.replace(KNOWN_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(PROVIDER_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(LONG_HEX_SECRET_PATTERN, "[REDACTED]");
@@ -79,7 +84,7 @@ function redactSecrets(message) {
 function stripTerminalEscapes(message) {
   return message.replace(TERMINAL_ESCAPE_PATTERN, "").replace(CONTROL_CHARS_PATTERN, " ");
 }
-var logContextStorage, MAX_LOG_MESSAGE_LENGTH, ANSI_PATTERN, URL_CREDENTIALS_PATTERN, B_LEFT, B_RIGHT, COOKIE_HEADER_PATTERN, SENSITIVE_KV_PATTERN, KNOWN_TOKEN_PATTERN, JWT_PATTERN, BASIC_AUTH_PATTERN, BEARER_AUTH_PATTERN, PROVIDER_TOKEN_PATTERN, LONG_HEX_SECRET_PATTERN, CONTROL_CHARS_PATTERN, REDACT_SCAN_LENGTH, TOKEN_CHAR_PATTERN, REDACT_SCAN_EXTENSION_MAX, TERMINAL_ESCAPE_PATTERN;
+var logContextStorage, MAX_LOG_MESSAGE_LENGTH, ANSI_PATTERN, URL_CREDENTIALS_PATTERN, B_LEFT, B_RIGHT, COOKIE_HEADER_PATTERN, SENSITIVE_KV_PATTERN, AUTH_SCHEME_PATTERN, KNOWN_TOKEN_PATTERN, JWT_PATTERN, BASIC_AUTH_PATTERN, BEARER_AUTH_PATTERN, PROVIDER_TOKEN_PATTERN, LONG_HEX_SECRET_PATTERN, CONTROL_CHARS_PATTERN, REDACT_SCAN_LENGTH, TOKEN_CHAR_PATTERN, REDACT_SCAN_EXTENSION_MAX, TERMINAL_ESCAPE_PATTERN;
 var init_log_utils = __esm({
   "src/utils/log-utils.ts"() {
     "use strict";
@@ -94,7 +99,11 @@ var init_log_utils = __esm({
       "gi"
     );
     SENSITIVE_KV_PATTERN = new RegExp(
-      `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|key)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([^\\s"',&)]+)`,
+      `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|token|key)${B_RIGHT}(["']?\\s*[:=]\\s*)("[^"\\r\\n]{0,1024}"|'[^'\\r\\n]{0,1024}'|["']?[^\\s"',&)]+)`,
+      "gi"
+    );
+    AUTH_SCHEME_PATTERN = new RegExp(
+      `${B_LEFT}(authorization)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([A-Za-z][A-Za-z0-9_-]{0,31})[ \\t]+[^\\s"',&)]+`,
       "gi"
     );
     KNOWN_TOKEN_PATTERN = new RegExp(
@@ -1561,6 +1570,7 @@ var init_browser_error_utils = __esm({
 var scraper_utils_exports = {};
 __export(scraper_utils_exports, {
   cleanConvertedMarkdown: () => cleanConvertedMarkdown,
+  collapseBlankLines: () => collapseBlankLines,
   createJsMarkdownConverter: () => createJsMarkdownConverter,
   createNativeMarkdownConverter: () => createNativeMarkdownConverter,
   disposeSsrfSafeFetcher: () => disposeSsrfSafeFetcher,
@@ -1815,10 +1825,28 @@ ${kept.join("\n")}
 ${rest}` : rest;
 }
 function cleanConvertedMarkdown(markdown) {
-  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown))).replace(/\n{3,}/g, "\n\n").trim();
+  return collapseBlankLines(stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown)))).trim();
+}
+function collapseBlankLines(markdown) {
+  if (!markdown.includes("\n\n\n")) return markdown;
+  const out = [];
+  let fence = null;
+  for (const line of markdown.split("\n")) {
+    const m = CODE_FENCE.exec(line);
+    if (fence === null) {
+      if (m) fence = m[1];
+    } else if (m && m[1][0] === fence[0] && m[1].length >= fence.length && line.slice(m[0].length).trim() === "") {
+      fence = null;
+    }
+    if (fence === null && line === "" && out.length > 0 && out[out.length - 1] === "") continue;
+    out.push(line);
+  }
+  return out.join("\n");
 }
 function stripImageLinks(markdown) {
-  return markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1").replace(/\n{3,}/g, "\n\n").trim();
+  return collapseBlankLines(
+    markdown.replace(MARKDOWN_IMAGE_PATTERN, "").replace(IMAGE_LINK_PATTERN, "$1")
+  ).trim();
 }
 function createNativeMarkdownConverter(nativeModule) {
   return async (html) => {
@@ -1880,7 +1908,7 @@ function validateContent(html, markdown, url) {
     throw error;
   }
 }
-var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY;
+var cachedSsrfFetcher, FRONT_MATTER_SLOTS, MAX_FRONT_MATTER_CHARS, FRONT_MATTER_KEY, CODE_FENCE;
 var init_scraper_utils = __esm({
   "src/web-research/scraper-utils.ts"() {
     "use strict";
@@ -1907,6 +1935,7 @@ var init_scraper_utils = __esm({
     ];
     MAX_FRONT_MATTER_CHARS = 2e4;
     FRONT_MATTER_KEY = /^([\w.:-]+):(?:\s|$)/;
+    CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/;
   }
 });
 

package/src/knowledge/store.ts

@@ -279,7 +279,7 @@ export class KnowledgeStore implements IKnowledgeStore {
 
     try {
       if (!fs.existsSync(this.options.dbDir)) {
-        fs.mkdirSync(this.options.dbDir, { recursive: true });
+        fs.mkdirSync(this.options.dbDir, { recursive: true, mode: 0o700 });
       }
       this.db = await (await getLancedb()).connect(this.options.dbDir);
 

package/src/tools/health-tool-definition.ts

@@ -13,6 +13,7 @@ import type {
 import { Type, type Static } from 'typebox';
 import { Value } from 'typebox/value';
 import { healthRegistry } from '../healthcheck/index.ts';
+import { HEALTH_TOOL_ANNOTATIONS, PI_RESEARCH_TOOL_NAMESPACE } from './tool-metadata.ts';
 
 /**
  * Create the health check tool definition
@@ -37,6 +38,8 @@ export function createHealthTool(): ToolDefinition {
     description: 'Verify system status (browser pool, knowledge store, GPU lock).',
     promptSnippet: 'Run system health checks',
     parameters,
+    annotations: HEALTH_TOOL_ANNOTATIONS,
+    namespace: PI_RESEARCH_TOOL_NAMESPACE,
     renderShell: 'self',
     executionMode: 'parallel',
     async execute(

package/src/tools/research-knowledge-search.ts

@@ -37,6 +37,7 @@ import { recordLlmUsage } from '../utils/llm-usage.ts';
 import { buildSafeOptions, validateAndExtractText, buildConstrainedSubmitTool, completeSimpleStructured } from '../core/llm/llm-utils.ts';
 import { getService, tryGetServiceContainerFromCtx } from '../core/service-registry.ts';
 import { withTimeout } from '../core/llm/llm-timeout.ts';
+import { KNOWLEDGE_SEARCH_TOOL_ANNOTATIONS, PI_RESEARCH_TOOL_NAMESPACE } from './tool-metadata.ts';
 import { abortableDelay } from '../web-research/retry-utils.ts';
 import { ServiceNames } from '../core/service-interfaces.ts';
 import type { IKnowledgeStoreService } from '../core/service-interfaces.ts';
@@ -894,6 +895,8 @@ export function createResearchKnowledgeSearchTool(iface?: ConfigInterface): Tool
       'Do not call knowledge search and research for the same query in the same turn — wait for the result.',
     ],
     parameters: ResearchKnowledgeSearchParams,
+    annotations: KNOWLEDGE_SEARCH_TOOL_ANNOTATIONS,
+    namespace: PI_RESEARCH_TOOL_NAMESPACE,
     executionMode: 'parallel',
     async execute(
       _toolCallId: string,

package/src/tools/research-tool-definition.ts

@@ -19,6 +19,7 @@ import type { ResearchDepth, CleanupContext } from '../types/index.ts';
 import { Type, type Static } from 'typebox';
 import { Value } from 'typebox/value';
 import { validateConfig, getConfig, type ConfigInterface } from '../config.ts';
+import { RESEARCH_TOOL_ANNOTATIONS, PI_RESEARCH_TOOL_NAMESPACE } from './tool-metadata.ts';
 import { tryGetServiceContainerFromCtx, getService } from '../core/service-registry.ts';
 
 import { ServiceNames } from '../core/service-interfaces.ts';
@@ -159,6 +160,8 @@ export function createResearchTool(iface?: ConfigInterface): ToolDefinition {
       'Perform multi-source web research using search, scraping, and specialized databases.',
     promptSnippet: 'Execute comprehensive web research',
     parameters,
+    annotations: RESEARCH_TOOL_ANNOTATIONS,
+    namespace: PI_RESEARCH_TOOL_NAMESPACE,
     renderShell: 'self',
     executionMode: 'parallel',
     prepareArguments: (args: unknown) => {

package/src/tools/tool-metadata.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared metadata for the tools this extension registers.
+ *
+ * pi 0.99 added two MCP-shaped fields to `ToolDefinition`: `annotations` and
+ * `namespace`. Neither changes how a tool runs. They are what pi reports and what
+ * other extensions read:
+ *
+ *   - `pi.getAllTools()` reports each tool's `exposure`, `namespace` and
+ *     `annotations`, and the documented permission pattern reads the annotations
+ *     to decide which calls to confirm.
+ *   - codemode lists the tools of one namespace under a single heading with the
+ *     namespace `description`; `instructions` is returned on request by
+ *     `describeNamespace(name)` and is not part of any tool listing.
+ *
+ * The hints come from the tool's author and are NOT verified by pi, so the rule
+ * here is to under-claim. `readOnlyHint` is true only for a tool that cannot
+ * change anything the user would have to undo, and `openWorldHint` is true for
+ * anything that can reach the network. A permission extension that trusts these
+ * hints to skip a confirmation must not be able to skip one for a call that
+ * starts a browser, spends money on a provider, or writes to the knowledge store.
+ *
+ * MCP defaults for absent hints are "not read-only, may be destructive, may reach
+ * an open world", so declaring a hint can only ever narrow what a permission
+ * extension confirms — with one exception: `readOnlyHint: true` on a tool that
+ * does write would silence a confirmation it should have asked for. That is the
+ * claim to be most careful about.
+ */
+
+import type { ToolAnnotations, ToolNamespace } from '@earendil-works/pi-coding-agent';
+
+/**
+ * One namespace for every tool this extension registers, so codemode lists them
+ * together instead of scattering three unrelated entries through its tool list.
+ */
+export const PI_RESEARCH_TOOL_NAMESPACE: ToolNamespace = {
+  name: 'pi-research',
+  description: 'Web research, knowledge-store search, and system health checks.',
+  instructions:
+    'research_knowledge_search is a local lookup and should be tried before research: ' +
+    'a complete hit answers the question without any live work. research runs a ' +
+    'multi-agent web investigation and takes minutes. health reports local service ' +
+    'status and is the cheapest of the three.',
+};
+
+/**
+ * `research`: reaches the open web, spawns sub-agents, spends provider tokens, and
+ * appends to the knowledge store and the session report. Additive, so not
+ * destructive, and every run is a new investigation, so not idempotent.
+ */
+export const RESEARCH_TOOL_ANNOTATIONS: ToolAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true,
+};
+
+/**
+ * `research_knowledge_search`: reads the local store, and on a miss can go live
+ * (network, provider tokens) and write what it learned back. Not read-only for the
+ * same reason as `research`.
+ */
+export const KNOWLEDGE_SEARCH_TOOL_ANNOTATIONS: ToolAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true,
+};
+
+/**
+ * `health`: reports local status. Not read-only because `probe: true` forces
+ * liveness checks that can start the browser pool and load models, and repeating a
+ * probe has no further effect, so it is idempotent. It reaches the local machine,
+ * not the open web.
+ */
+export const HEALTH_TOOL_ANNOTATIONS: ToolAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+};

package/src/utils/log-utils.ts

@@ -126,8 +126,18 @@ const COOKIE_HEADER_PATTERN = new RegExp(
 // sort key, a map key) is the accepted trade-off — same one already made for
 // the equally generic bare `session`/`cookie` entries below.
 const SENSITIVE_KV_PATTERN = new RegExp(
-  `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|key)${B_RIGHT}` +
-    `(["']?\\s*[:=]\\s*["']?)([^\\s"',&)]+)`,
+  `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|token|key)${B_RIGHT}` +
+    // A quoted value is consumed whole (bounded, so no backtracking blow-up): the
+    // old unquoted class stopped at the first space/comma/&, so `password="a b"`
+    // left ` b"` in the clear. An unterminated quote falls through to that class.
+    `(["']?\\s*[:=]\\s*)("[^"\\r\\n]{0,1024}"|'[^'\\r\\n]{0,1024}'|["']?[^\\s"',&)]+)`,
+  'gi',
+);
+// `Authorization: <scheme> <credential>` for schemes the Bearer/Basic patterns do
+// not know (Token, Digest, ApiKey, ...). The KV pass alone would mask only the
+// scheme word and leave the credential after the space.
+const AUTH_SCHEME_PATTERN = new RegExp(
+  `${B_LEFT}(authorization)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([A-Za-z][A-Za-z0-9_-]{0,31})[ \\t]+[^\\s"',&)]+`,
   'gi',
 );
 // Well-known opaque credential formats (OpenAI, GitHub, AWS, Slack, Anthropic).
@@ -237,7 +247,12 @@ export function redactSecrets(message: string): string {
   // Whole-header cookie masking before the KV pass, which would otherwise stop
   // at the first whitespace and leave every subsequent pair in the clear.
   out = out.replace(COOKIE_HEADER_PATTERN, (_m, key: string, sep: string) => `${key}${sep}[REDACTED]`);
-  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key: string, sep: string) => `${key}${sep}[REDACTED]`);
+  out = out.replace(AUTH_SCHEME_PATTERN, (_m, key: string, sep: string, scheme: string) => `${key}${sep}${scheme} [REDACTED]`);
+  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key: string, sep: string, val: string) => {
+    const q = val[0] === '"' || val[0] === "'" ? val[0] : '';
+    const closed = q !== '' && val.length > 1 && val.endsWith(q);
+    return `${key}${sep}${q}[REDACTED]${closed ? q : ''}`;
+  });
   out = out.replace(KNOWN_TOKEN_PATTERN, '[REDACTED]');
   out = out.replace(PROVIDER_TOKEN_PATTERN, '[REDACTED]');
   out = out.replace(LONG_HEX_SECRET_PATTERN, '[REDACTED]');

package/src/utils/research-export.ts

@@ -188,7 +188,7 @@ export async function exportResearchReport(
     const filepath = join(targetDir, filename);
 
     try {
-      await fs.writeFile(filepath, result, { flag: 'wx' });
+      await fs.writeFile(filepath, result, { flag: 'wx', mode: 0o600 });
       logger.log(`[export] Research report saved to: ${filepath}`);
       return filepath;
     } catch (error) {

package/src/web-research/pdf-extract-worker.mjs

@@ -213,7 +213,11 @@ var COOKIE_HEADER_PATTERN = new RegExp(
   "gi"
 );
 var SENSITIVE_KV_PATTERN = new RegExp(
-  `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|key)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([^\\s"',&)]+)`,
+  `${B_LEFT}(api[_-]?key|apikey|access[_-]?token|auth[_-]?token|refresh[_-]?token|secret|client[_-]?secret|password|passwd|pwd|authorization|bearer|set[_-]?cookie|cookie|session[_-]?id|session|csrf[_-]?token|xsrf[_-]?token|private[_-]?key|token|key)${B_RIGHT}(["']?\\s*[:=]\\s*)("[^"\\r\\n]{0,1024}"|'[^'\\r\\n]{0,1024}'|["']?[^\\s"',&)]+)`,
+  "gi"
+);
+var AUTH_SCHEME_PATTERN = new RegExp(
+  `${B_LEFT}(authorization)${B_RIGHT}(["']?\\s*[:=]\\s*["']?)([A-Za-z][A-Za-z0-9_-]{0,31})[ \\t]+[^\\s"',&)]+`,
   "gi"
 );
 var KNOWN_TOKEN_PATTERN = new RegExp(
@@ -251,7 +255,12 @@ function redactSecrets(message) {
   out = out.replace(BASIC_AUTH_PATTERN, "Basic [REDACTED]");
   out = out.replace(BEARER_AUTH_PATTERN, "Bearer [REDACTED]");
   out = out.replace(COOKIE_HEADER_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
-  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep) => `${key}${sep}[REDACTED]`);
+  out = out.replace(AUTH_SCHEME_PATTERN, (_m, key, sep, scheme) => `${key}${sep}${scheme} [REDACTED]`);
+  out = out.replace(SENSITIVE_KV_PATTERN, (_m, key, sep, val) => {
+    const q = val[0] === '"' || val[0] === "'" ? val[0] : "";
+    const closed = q !== "" && val.length > 1 && val.endsWith(q);
+    return `${key}${sep}${q}[REDACTED]${closed ? q : ""}`;
+  });
   out = out.replace(KNOWN_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(PROVIDER_TOKEN_PATTERN, "[REDACTED]");
   out = out.replace(LONG_HEX_SECRET_PATTERN, "[REDACTED]");

package/src/web-research/scraper-utils.ts

@@ -551,20 +551,43 @@ export function trimFrontMatter(markdown: string): string {
  * leaves extra blank lines, so they are collapsed again.
  */
 export function cleanConvertedMarkdown(markdown: string): string {
-  return stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown)))
-    .replace(/\n{3,}/g, '\n\n')
-    .trim();
+  return collapseBlankLines(stripEmptyFragmentLinks(stripImageLinks(trimFrontMatter(markdown)))).trim();
+}
+
+/** Opening/closing fence of a fenced code block (CommonMark: up to 3 spaces, 3+ backticks or tildes). */
+const CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/;
+
+/**
+ * Collapse runs of blank lines to one, EXCEPT inside fenced code blocks, where
+ * blank lines are content (PEP 8 spacing, Makefiles, ASCII art). An unclosed
+ * fence runs to the end of the document, as in CommonMark.
+ */
+export function collapseBlankLines(markdown: string): string {
+  if (!markdown.includes('\n\n\n')) return markdown;
+  const out: string[] = [];
+  let fence: string | null = null;
+  for (const line of markdown.split('\n')) {
+    const m = CODE_FENCE.exec(line);
+    if (fence === null) {
+      if (m) fence = m[1]!;
+    } else if (m && m[1]![0] === fence[0] && m[1]!.length >= fence.length && line.slice(m[0].length).trim() === '') {
+      fence = null;
+    }
+    if (fence === null && line === '' && out.length > 0 && out[out.length - 1] === '') continue;
+    out.push(line);
+  }
+  return out.join('\n');
 }
 
 /**
  * Strip image links from markdown
  */
 export function stripImageLinks(markdown: string): string {
-  return markdown
-    .replace(MARKDOWN_IMAGE_PATTERN, '')
-    .replace(IMAGE_LINK_PATTERN, '$1')
-    .replace(/\n{3,}/g, '\n\n')
-    .trim();
+  return collapseBlankLines(
+    markdown
+      .replace(MARKDOWN_IMAGE_PATTERN, '')
+      .replace(IMAGE_LINK_PATTERN, '$1'),
+  ).trim();
 }
 
 /**