@lincoln504/pi-research 1.7.6 → 1.7.7

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.7", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli.mjs

@@ -9928,6 +9928,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 +10492,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 +10620,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();

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,24 @@ 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.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.7",
   "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/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/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,
+};