@dumbmice/pi-deepseek-websearch 0.1.4 → 0.1.6

package/AGENTS.md

@@ -10,6 +10,7 @@ Instructions for anyone — human or coding agent — changing
 src/index.ts              the extension: two tool registrations, transport, formatting, guards
 test/index.test.ts        node:test suite; global fetch is stubbed, nothing touches the network
 docs/docs-alignment.md    every client-side deviation from DeepSeek's published API contract
+docs/pi-api-alignment.md  which pi release this package is verified against
 README.md                 user-facing documentation
 AGENTS.md                 this file
 CONTRIBUTING.md           four-line pointer to this file (GitHub convention)
@@ -21,8 +22,8 @@ tsconfig.json             the strict / noEmit settings used by typecheck
 
 ## Requirements and commands
 
-Node >= 22.6 (`engines`; the entry point is TypeScript and the test runner uses
-`--experimental-strip-types`). devDependencies stay limited to `typescript` and `@types/node`; the
+Node >= 22.19 (`engines`, the floor pi 1.5.1 itself requires; the entry point is TypeScript and
+the test runner uses `--experimental-strip-types`). devDependencies stay limited to `typescript` and `@types/node`; the
 publish workflow installs with `npm ci`, the test matrix with `npm install`.
 
 ```bash
@@ -45,10 +46,12 @@ README text, the matching `docs/docs-alignment.md` entry (or marking that item s
   no-runtime-dependencies rule. Do not replace them with `Type.Object` imports.
 - **A fitting query is never rewritten.** `fitQuery` returns the caller's text untouched when it fits,
   apart from stripped leading/trailing whitespace. Only an over-long query is tokenised and trimmed.
-- **Trimming is bounded and reported.** Shed filters (recency, language, domains) first, then trailing
-  words, then a code-point tail cut; drop a dangling operator or unmatched quote; record every removal
-  in `dropped`. Whitespace stripped from `query`, `ori_question` and `localization` before use is
-  silent (register item 3).
+- **Filters are constraints; words are expendable.** When the assembled query exceeds 128 characters,
+  keep every filter and remove trailing words; cut one indivisible token by code point only if it
+  alone exceeds the remaining budget. If the filters leave no room for search text, fail before the
+  request. Drop a dangling operator or unmatched quote, and record every removal in `dropped`.
+  Whitespace stripped from `query`, `ori_question` and `localization` before use is silent
+  (register item 3).
 - **Cost follows the raw response.** `estimatedCostUsd` is keyed to `rawResults.length`, not to what
   survives client-side filtering, because DeepSeek bills a non-empty result set.
 - **A malformed 200 is an error.** A body without a `results` array is rejected; an empty array is a
@@ -116,6 +119,9 @@ is enough to check rendering. `npm test` needs neither key nor network.
   and constant and at the top of the register — keep them in step.
 - `CHANGELOG.md` follows Keep a Changelog. Put unreleased work under `[Unreleased]` with
   Added/Changed/Fixed headings; add the version heading when the release is tagged.
+- `docs/pi-api-alignment.md` records the pi release and Node version this package is verified
+  against. `PI_API_SNAPSHOT` in `src/index.ts`, that file and the README *Install* line move together;
+  `test/docs.test.ts` fails when they drift.
 - `AGENTS.md` (this file) holds contributor, architecture and release material.
 
 ## Release process

package/CHANGELOG.md

@@ -6,6 +6,27 @@ All notable changes to this extension are documented in this file. The format fo
 
 ## [Unreleased]
 
+## [0.1.6] - 2026-11-06
+
+### Added
+
+- `docs/pi-api-alignment.md`: a tested-version table recording the pi release (`1.5.1`) and Node
+  version this package is verified against, pinned by `PI_API_SNAPSHOT` and a docs test so the claim
+  cannot drift from the code.
+
+### Changed
+
+- `engines.node` raised to `>=22.19`, matching pi 1.5.1's own floor. The README now states the pi
+  version it was tested with.
+
+## [0.1.5] - 2026-11-06
+
+### Fixed
+
+- Over-length queries no longer lose their filters. Trimming keeps `allowed_domains`, `blocked_domains`,
+  `lang` and `recency` and removes trailing words instead; a filter set that leaves no room for search
+  text fails before the request rather than sending the query with those filters stripped.
+
 ## [0.1.4] - 2026-10-30
 
 ### Added
@@ -72,7 +93,9 @@ results are not billed. Validated against the DeepSeek API documentation as of 2
 - `deepseek_fetch` rejects local and private targets and never unescapes inside code.
 
 
-[Unreleased]: https://github.com/DumbMice/pi-deepseek-websearch/compare/v0.1.4...HEAD
+[Unreleased]: https://github.com/DumbMice/pi-deepseek-websearch/compare/v0.1.6...HEAD
+[0.1.6]: https://github.com/DumbMice/pi-deepseek-websearch/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/DumbMice/pi-deepseek-websearch/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/DumbMice/pi-deepseek-websearch/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/DumbMice/pi-deepseek-websearch/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/DumbMice/pi-deepseek-websearch/compare/v0.1.1...v0.1.2

package/README.md

@@ -46,13 +46,17 @@ pi install git:github.com/DumbMice/pi-deepseek-websearch
 
 Requirements:
 
-- Node >= 22.6.
+- **pi 1.5.1** (tested).
+- Node >= 22.19, the floor pi itself requires.
 - A DeepSeek key, from pi's `deepseek` provider (`/login`) or the `DEEPSEEK_API_KEY` variable. Create
   one at <https://platform.deepseek.com/api_keys>.
 - Optional, for a compatible gateway: set `PI_DEEPSEEK_BASE_URL` or `DEEPSEEK_SEARCH_BASE_URL`. A
   trailing slash or `/v1` suffix is stripped. The bare `DEEPSEEK_BASE_URL` is ignored on purpose,
   because other tools point it at an OpenAI-compatible `/v1` root.
 
+Last verified 2026-11-06; the table and what was checked is in
+[docs/pi-api-alignment.md](https://github.com/DumbMice/pi-deepseek-websearch/blob/main/docs/pi-api-alignment.md).
+
 Confirm registration by starting `pi` and asking *"use deepseek_search to look up the DeepSeek API
 pricing"*; the reply begins with a `DeepSeek search · N result(s)` header.
 
@@ -104,9 +108,11 @@ an error, not as an empty success.
 
 ## Behaviour to expect
 
-- **Long queries are trimmed, not rejected.** The 128-character cap includes operators; when a query
-  is shortened, the reply names what went — filters first, then trailing words, then a truncated tail
-  — and prints the final query.
+- **Long queries are trimmed, not rejected.** The 128-character cap includes operators. When a query
+  is shortened, trailing words are removed and the filters are kept (a single word or quoted
+  phrase longer than the remaining room is cut); the reply names what went and prints the final query. If the filters alone
+  leave no room for search text, the call fails before any request — shorten the domain list or
+  remove a filter to send it.
 - **Transient failures are retried.** `408`, `429`, any `5xx`, network failures and timeouts get up
   to three attempts, honouring `retry-after` (seconds or an HTTP date) capped at 5 seconds. Every
   other `4xx` fails immediately with DeepSeek's own message. Each attempt has its own deadline: 30

package/docs/docs-alignment.md

@@ -11,8 +11,9 @@ extension can emit is always a valid request.
 Client-side deviations and transport details, listed in full. Items that produce no signal in the
 output are marked _(silent)_; everything else is observable in the reply or in `details`.
 
-1. over-length queries are trimmed rather than rejected, and every removal is reported; a single
-   token longer than the whole budget is cut mid-token;
+1. over-length queries are trimmed rather than rejected, and every removal is reported. Filters are
+   kept and trailing words are removed; a single token longer than the remaining budget is cut
+   mid-token. If the filters alone leave no room for search text, the call fails before the request;
 2. query whitespace is normalised only when the query must be rewritten, and that is reported in the
    same line;
 3. leading and trailing whitespace is stripped from `query`, `ori_question` and `localization` before
@@ -63,7 +64,9 @@ output are marked _(silent)_; everything else is observable in the reply or in `
 23. result fields of an unexpected type are ignored rather than passed through, so one malformed
     result degrades instead of failing the call _(silent)_;
 24. `recency` windows are fixed client-side at 1 / 7 / 30 / 365 days for `day` / `week` / `month` /
-    `year`.
+    `year`;
+25. domain list entries that are empty or contain whitespace or a quote are dropped before the query is
+    assembled _(silent)_.
 
 Transport details: requests send `Accept: application/json` alongside the two documented headers;
 retry backoff is 500 ms then 1 s when no `retry-after` is present (two sleeps for three attempts); and

package/docs/pi-api-alignment.md

@@ -0,0 +1,42 @@
+# pi extension API alignment
+
+How this extension's use of pi's extension API relates to the documented contract, and which exact
+versions that was established against.
+
+| Component | Tested version | Recorded in |
+|---|---|---|
+| `@earendil-works/pi-coding-agent` | **1.5.1** | `PI_API_SNAPSHOT` in `src/index.ts` |
+| `@earendil-works/pi-schema` (tool validation) | ships with pi 1.5.1 | this file (notes below) |
+| Node | 22.23.2 (tested); floor 22.19, the floor pi itself requires | `package.json` `engines`, README *Install* |
+| DeepSeek Search & Fetch API | docs snapshot 2026-10-30 | `DOCS_SNAPSHOT`; see `docs/docs-alignment.md` |
+
+Last verified **2026-11-06**. Bump a row here, its constant where one exists, and the README
+*Install* line in the same commit as the change that depends on it.
+
+## What this extension actually uses
+
+The contract is followed where it is documented, and nothing here calls pi internals:
+
+- `pi.registerTool()` with a hand-written JSON Schema `parameters` object. pi validates any JSON
+  Schema; the `typebox` import in the docs is a convenience, and avoiding it keeps the package
+  dependency-free.
+- `execute(toolCallId, params, signal, onUpdate, ctx)` — the five-argument form.
+- `ctx.modelRegistry.getApiKeyForProvider("deepseek")` for credentials, falling back to
+  `DEEPSEEK_API_KEY`.
+- The `pi.extensions` manifest entry in `package.json`.
+
+It registers no commands, hooks, renderers or UI, so a release that only changes those surfaces
+cannot affect this package.
+
+## Notes on the 1.5.x line
+
+1. **Tool validation moved to `@earendil-works/pi-schema` in 1.5.0.** TypeBox features outside JSON
+   Schema no longer apply; plain JSON Schema tools now get the same coercion as TypeBox tools
+   (numeric strings to numbers, `"true"` to `true`, a single value to a one-item array, `null` in an
+   optional property dropped). This package uses only JSON Schema keywords, so nothing was lost, and
+   the coercion is a net improvement: `allowed_domains: "example.com"` now arrives as
+   `["example.com"]` instead of being rejected.
+2. **Package changelogs are read from the package root by 1.5.x.** `CHANGELOG.md` uses the required
+   `## [x.y.z]` headings, so extension updates surface our notes without a `pi.changelogPath` entry.
+3. **Node floor.** pi 1.5.1 declares `>=22.19.0`; this package declares the same floor, because it
+   only runs inside pi.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dumbmice/pi-deepseek-websearch",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "DeepSeek web search and page fetch tools for the pi coding agent: publication dates, authority, rerank scores, ori_question, count 1-50.",
   "type": "module",
   "license": "MIT",
@@ -41,12 +41,12 @@
     ]
   },
   "scripts": {
-    "test": "node --experimental-strip-types --no-warnings --test test/index.test.ts",
+    "test": "node --experimental-strip-types --no-warnings --test test/index.test.ts test/docs.test.ts",
     "typecheck": "tsc -p tsconfig.json",
     "pack:check": "npm pack --dry-run"
   },
   "engines": {
-    "node": ">=22.6"
+    "node": ">=22.19"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",

package/src/index.ts

@@ -21,6 +21,7 @@
 import { isIP } from "node:net";
 
 export const DOCS_SNAPSHOT = "2026-10-30";
+export const PI_API_SNAPSHOT = "2026-11-06";
 export const PRICE_PER_SUCCESSFUL_REQUEST_USD = 0.00075;
 export const MAX_QUERY_CHARS = 128;
 
@@ -242,10 +243,9 @@ async function postDeepSeek<T>(
 /* ------------------------------------------------------------------- query */
 
 /**
- * Trim to the API's hard character budget (docs: 1-128 Unicode characters including
- * operators). Filters are shed first — recency, then language, then domains — and only
- * then trailing free-text words. Every removal is reported so the caller can see that
- * the request differs from what was asked for.
+ * Fit the assembled query into the API's hard limit (docs: 1-128 Unicode characters,
+ * operators included). Filters are explicit constraints, so they are kept and the
+ * free-text part is shortened instead. Every removal is reported.
  */
 export function fitQuery(options: SearchOptions): { query: string; dropped: string[] } {
 	const dropped: string[] = [];
@@ -272,33 +272,36 @@ export function fitQuery(options: SearchOptions): { query: string; dropped: stri
 	const untouched = [raw, ...filters].filter(Boolean).join(" ");
 	if (charLength(untouched) <= MAX_QUERY_CHARS) return { query: untouched, dropped };
 
-	// Only a query that cannot fit is rewritten, token by token, and every change is reported.
+	// The filters occupy the tail of the string, so they set the budget for the words.
+	const filterText = filters.join(" ");
+	const filterCost = filterText ? charLength(filterText) + 1 : 0;
+	const available = MAX_QUERY_CHARS - filterCost;
+	if (available < 1) {
+		const names = [
+			options.allowedDomains.length > 0 ? "allowed_domains" : "",
+			options.blockedDomains.length > 0 ? "blocked_domains" : "",
+			options.lang ? "lang" : "",
+			options.recency ? "recency" : "",
+		].filter(Boolean);
+		const named =
+			names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}` : names[0]!;
+		throw new Error(
+			`The ${named} ${names.length > 1 ? "filters need" : "filter needs"} ${filterCost} characters ` +
+				"of the 128-character query limit, leaving no room for the search text. " +
+				"Shorten the filter values or remove a filter.",
+		);
+	}
+
 	// An unescaped quoted phrase is one token: slicing mid-phrase would change its meaning.
 	// Backslash-escaped quotes are not special-cased (only reachable on over-length queries).
 	const matchedTokens = raw.match(/"[^"]*"|\S+/g);
-	const tokens: string[] = matchedTokens ? [...matchedTokens] : [raw];
+	let words: string[] = matchedTokens ? [...matchedTokens] : [raw];
 	const quotesWereBalanced = ((raw.match(/"/g) ?? []).length % 2) === 0;
-	if (raw !== tokens.join(" ")) dropped.push("query whitespace normalised");
-	let words = tokens;
-	let active = [...filters];
-
-	const overBudget = () => charLength(join(words, active)) > MAX_QUERY_CHARS;
-	const dropFilter = (predicate: (filter: string) => boolean, label: (filter: string) => string): void => {
-		const index = active.findIndex(predicate);
-		if (index < 0 || !overBudget()) return;
-		const [removed] = active.splice(index, 1);
-		dropped.push(label(removed!));
-	};
-
-	dropFilter((f) => f.startsWith("after:"), (f) => `recency (${f})`);
-	dropFilter((f) => f.startsWith("lang:"), (f) => `language (${f})`);
-	while (overBudget() && active.length > 0) {
-		const removed = active.pop()!;
-		dropped.push(`domain filter (${removed.slice(0, 40)})`);
-	}
+	if (raw !== words.join(" ")) dropped.push("query whitespace normalised");
 
 	const wordsBefore = words.join(" ");
-	while (words.length > 1 && overBudget()) words = words.slice(0, -1);
+	while (words.length > 1 && charLength(words.join(" ")) > available) words = words.slice(0, -1);
+
 	// Never leave a dangling operator (`site:`, `-site:`, `after:`, a bare `-`) or an
 	// unbalanced quote behind: DeepSeek would answer 400 and no retry would help.
 	const danglingOperator = /^(?:-|-[A-Za-z]+:|[A-Za-z]+:)$/;
@@ -313,20 +316,37 @@ export function fitQuery(options: SearchOptions): { query: string; dropped: stri
 		dropped.push("trailing query words");
 	}
 
-	let query = join(words, active);
+	let query = join(words, filters);
 	if (charLength(query) > MAX_QUERY_CHARS) {
-		// A single token longer than the whole budget: cutting it is unavoidable, so do it
-		// by code point and report it rather than sending an invalid request.
-		query = Array.from(query).slice(0, MAX_QUERY_CHARS).join("").trim();
-		// A cut can land on a bare operator (`-`, `:`), which the API would reject.
-		while (query.length > 0 && /[-:]$/.test(query)) query = Array.from(query).slice(0, -1).join("").trimEnd();
-		if (quotesWereBalanced && (query.match(/"/g) ?? []).length % 2 === 1) {
-			// The cut left one unmatched quote: remove that quote rather than invent a pair.
-			const balanced = Array.from(query);
-			const lastQuote = balanced.lastIndexOf('"');
-			if (lastQuote >= 0) balanced.splice(lastQuote, 1);
-			query = balanced.join("").trimEnd();
+		// One indivisible token longer than the remaining budget: cutting it is unavoidable,
+		// so do that by code point rather than dropping a filter.
+		let cut = Array.from(words.join(" ")).slice(0, available).join("").trim();
+		// Repeat until stable: splicing an unmatched quote can expose a trailing `-`/`:`.
+		for (let changed = true; changed; ) {
+			changed = false;
+			const stripped = cut.replace(/[-:]+$/, "").trimEnd();
+			if (stripped !== cut) {
+				cut = stripped;
+				changed = true;
+			}
+			if (quotesWereBalanced && (cut.match(/"/g) ?? []).length % 2 === 1) {
+				const balanced = Array.from(cut);
+				const lastQuote = balanced.lastIndexOf('"');
+				if (lastQuote >= 0) balanced.splice(lastQuote, 1);
+				const next = balanced.join("").trimEnd();
+				if (next !== cut) {
+					cut = next;
+					changed = true;
+				}
+			}
+		}
+		if (cut === "" && filters.length === 0) {
+			throw new Error(
+				"The query has no searchable text within the 128-character limit — it consists only of " +
+					"operators or punctuation. Add search terms.",
+			);
 		}
+		query = join([cut], filters);
 		dropped.push("query tail");
 	}
 	return { query, dropped };
@@ -502,7 +522,7 @@ const SEARCH_SCHEMA = {
 			type: "string",
 			minLength: 1,
 			description:
-				'Search query. Supports operators: "exact phrase", -word, -"phrase", site:a.com OR site:b.com, -site:c.com, lang:en,zh, after:2025-01-01, before:2026-06-01. Queries are capped at 128 chars including operators; anything longer is trimmed automatically (filters shed first, then trailing words) and the removals are reported in the output — do not pre-shorten.',
+				'Search query. Supports operators: "exact phrase", -word, -"phrase", site:a.com OR site:b.com, -site:c.com, lang:en,zh, after:2025-01-01, before:2026-06-01. Queries are capped at 128 chars including operators; anything longer is trimmed automatically (trailing words are removed, filters are kept) and the removals are reported in the output — do not pre-shorten.',
 		},
 		count: {
 			type: "integer",
@@ -524,13 +544,13 @@ const SEARCH_SCHEMA = {
 			type: "array",
 			items: { type: "string" },
 			description:
-				"Restrict results to these domains (compiled into site: OR site:). Counts toward the 128-char query cap, so a long domain list can be dropped for very long queries — any drop is reported in the output.",
+				"Restrict results to these domains (compiled into site: OR site:). Counts toward the 128-char query cap and is never dropped by trimming; if the filters leave no room for the query text, the call fails before any request.",
 		},
 		blocked_domains: {
 			type: "array",
 			items: { type: "string" },
 			description:
-				"Exclude these domains (compiled into -site:). Counts toward the 128-char query cap and may be dropped for very long queries; any drop is reported.",
+				"Exclude these domains (compiled into -site:). Counts toward the 128-char query cap and is never dropped by trimming; if the filters leave no room for the query text, the call fails before any request.",
 		},
 		lang: { type: "string", description: 'Language codes, e.g. "zh,en" (becomes lang:).' },
 		recency: {