pi-quiver 3.4.1 → 4.0.1

package/CHANGELOG.md

@@ -8,6 +8,16 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v4.0.1 - 2026-08-04
+
+- **Trimmed `fetch`/`doc_to_md` system-prompt guidelines that duplicated the tool descriptions** (~200 tokens). The two additive bits (degraded-result fidelity warning, grep-the-spilled-file guidance) moved into the tool descriptions; `promptGuidelines` dropped from both tools.
+
+## v4.0.0 - 2026-08-04
+
+- **BREAKING: extension sources moved out of the package root** into `extensions/`; the shared config helper moved to `lib/extension-config.ts` (#4). If you disabled an extension through `pi config`, the stored filter (e.g. `-fast-mode.ts`) no longer matches any path and the extension will load again - re-disable it, or update the entry to `extensions/fast-mode.ts`. Hand-written `!fast-mode.ts` entries in `settings.json` are unaffected.
+- **Local-checkout invocation changed:** `pi -e <path>/fetch.ts` is now `pi -e <path>/extensions/fetch.ts`.
+- No behaviour change in any extension; `pi.extensions` is now a single directory entry and typecheck flags moved into `tsconfig.json`.
+
 ## v3.4.1 - 2026-08-04
 
 - **`fast-mode` now corrects reported `usage.cost` to true 2x fast pricing for Opus 4.8/5** (statusline, persisted cost, and pi-cohort `Σ$` per load order) (#6).

package/README.md

@@ -62,12 +62,12 @@ A 300 KB changelog page never touches your context window - you get a preview an
 
 | Extension | Tool | What it does |
 | --- | --- | --- |
-| `fetch.ts` | `fetch` | Retrieve URLs over HTTP(S). HTML -> Markdown (Readability extraction, Turndown conversion). Binary saved untouched to a temp file. GitHub issue/PR/repo/actions-run URLs auto-route through `gh` (falls back to HTTP). Same size gate as `doc_to_md`. |
-| `doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX to Markdown. High-fidelity via `pymupdf4llm` (run through `uv`); degraded pure-JS fallback (`unpdf`) when `uv`/Python is unavailable or conversion times out. DOCX/PPTX convert via LibreOffice first. |
-| `session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, with Ghostty tab rename. OFF by default. |
-| `sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
-| `fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 / Opus 5 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
-| `provider-stall-watchdog.ts` | - | Opt-in provider-stall recovery, in two tiers: a pre-first-event deadline (`firstEventMs`, 20s) on every provider request in every mode, and the mid-stream pair (warn at 2 min, recover at 4 min) in TUI runs only. Policy D offers each stall to Pi's retry loop until the stall retry budget (`maxStallRetries`, default = `retry.maxRetries`) is exhausted. OFF by default. |
+| `extensions/fetch.ts` | `fetch` | Retrieve URLs over HTTP(S). HTML -> Markdown (Readability extraction, Turndown conversion). Binary saved untouched to a temp file. GitHub issue/PR/repo/actions-run URLs auto-route through `gh` (falls back to HTTP). Same size gate as `doc_to_md`. |
+| `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX to Markdown. High-fidelity via `pymupdf4llm` (run through `uv`); degraded pure-JS fallback (`unpdf`) when `uv`/Python is unavailable or conversion times out. DOCX/PPTX convert via LibreOffice first. |
+| `extensions/session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, with Ghostty tab rename. OFF by default. |
+| `extensions/sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
+| `extensions/fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 / Opus 5 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
+| `extensions/provider-stall-watchdog.ts` | - | Opt-in provider-stall recovery, in two tiers: a pre-first-event deadline (`firstEventMs`, 20s) on every provider request in every mode, and the mid-stream pair (warn at 2 min, recover at 4 min) in TUI runs only. Policy D offers each stall to Pi's retry loop until the stall retry budget (`maxStallRetries`, default = `retry.maxRetries`) is exhausted. OFF by default. |
 
 Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md), [doc/doc-to-md.md](doc/doc-to-md.md).
 
@@ -120,7 +120,7 @@ pi -e npm:pi-quiver
 
 ```bash
 git clone git@github.com:jjuraszek/pi-quiver.git ~/repos/pi-quiver
-pi -e ~/repos/pi-quiver/fetch.ts
+pi -e ~/repos/pi-quiver/extensions/fetch.ts
 ```
 
 ## Prerequisites
@@ -203,7 +203,7 @@ runtime deps; install them transiently and run the full check:
 
 ```bash
 npm install
-npm run test:all      # node --test *.test.ts  +  tsc --noEmit typecheck
+npm run test:all      # node --test test/*.test.ts  +  tsc --noEmit typecheck
 ```
 
 `npm test` runs the unit tests alone; `npm run typecheck` runs the type pass.

package/{doc_to_md.ts → extensions/doc_to_md.ts}

@@ -250,7 +250,7 @@ let warmPromise: Promise<"warm" | "unavailable"> | null = null;
 let uvAvailable: boolean | null = null;
 
 function scriptPath(): string {
-	return fileURLToPath(new URL("./scripts/pdf_to_md.py", import.meta.url));
+	return fileURLToPath(new URL("../scripts/pdf_to_md.py", import.meta.url));
 }
 
 async function onPath(cmd: string): Promise<boolean> {
@@ -357,15 +357,8 @@ export default function docToMdExtension(pi: ExtensionAPI) {
 		name: "doc_to_md",
 		label: "Convert doc to Markdown",
 		description:
-			"Convert a local PDF/DOCX/PPTX file to Markdown. High-fidelity conversion via pymupdf4llm (run through uv, fetched on first use); falls back to a degraded pure-JS text extractor (unpdf) when uv/Python is unavailable or conversion times out. DOCX/PPTX require LibreOffice (soffice) for the office->PDF step. Output over 32KB or 1000 lines is written to a temp .md file with a preview instead of inlined. Input must be a local file path (use fetch first for URLs).",
+			"Convert a local PDF/DOCX/PPTX file to Markdown. High-fidelity conversion via pymupdf4llm (run through uv, fetched on first use); falls back to a degraded pure-JS text extractor (unpdf) when uv/Python is unavailable or conversion times out. DOCX/PPTX require LibreOffice (soffice) for the office->PDF step. Output over 32KB or 1000 lines is written to a temp .md file with a preview instead of inlined - grep it or read with offset/limit. A degraded result (marked in the output) means the fallback ran: tables and headings are NOT faithfully preserved, treat structure with suspicion. Input must be a local file path (use fetch first for URLs).",
 		promptSnippet: "Convert a local PDF/DOCX/PPTX to Markdown",
-		promptGuidelines: [
-			"Input is a LOCAL file path, not a URL — use the fetch tool first to download remote documents, then pass the saved path here.",
-			"Supported types: .pdf, .docx, .pptx. Spreadsheets and other formats are not supported.",
-			"DOCX/PPTX conversion requires LibreOffice (soffice) on PATH; without it those inputs error.",
-			"A degraded result (marked in the output) means the pure-JS fallback ran — tables and headings are NOT faithfully preserved; treat structure with suspicion.",
-			"When output is written to a file, grep it or read with offset/limit; Markdown is grep-able by heading (^#).",
-		],
 		parameters: Type.Object({
 			path: Type.String({ description: "Local path to a .pdf, .docx, or .pptx file" }),
 		}),

package/{fast-mode.ts → extensions/fast-mode.ts}

@@ -23,7 +23,7 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Usage } from "@earendil-works/pi-ai";
-import { resolveConfig } from "./extension-config.ts";
+import { resolveConfig } from "../lib/extension-config.ts";
 
 export const FAST_MODE_BETA = "fast-mode-2026-02-01";
 export const FAST_SPEED = "fast";

package/{fetch.ts → extensions/fetch.ts}

@@ -458,15 +458,8 @@ export default function fetchExtension(pi: ExtensionAPI) {
 		name: "fetch",
 		label: "Fetch URL",
 		description:
-			"Fetch a URL over HTTP(S). HTML is extracted to Markdown (readability + turndown). Binary content (images, PDFs, archives) is saved untouched to a temp file and only a path is returned. Text/Markdown/JSON over 32KB or 1000 lines is written to a temp file with a 60-line preview; smaller content is returned inline. Parsable downloads are capped at 1MB, binary at 50MB. GitHub issue/PR/repo/actions-run URLs are served via the gh CLI when available (falls back to HTTP otherwise).",
+			"Fetch a URL over HTTP(S). HTML is extracted to Markdown (readability + turndown). Binary content (images, PDFs, archives) is saved untouched to a temp file and only a path is returned. Text/Markdown/JSON over 32KB or 1000 lines is written to a temp file with a 60-line preview; smaller content is returned inline. Parsable downloads are capped at 1MB, binary at 50MB. When the body is written to a file, grep it or read with offset/limit; converted Markdown is grep-able by heading (^#). GitHub issue/PR/repo/actions-run URLs are served via the gh CLI when available (falls back to HTTP otherwise; raw=true forces the rendered HTML page).",
 		promptSnippet: "Fetch the contents of a URL",
-		promptGuidelines: [
-			"Use fetch when the user provides a URL or asks to read web content.",
-			"Binary responses return a file path only — pass that path to a tool that can process the bytes; do not expect inline content.",
-			"When the body is written to a file, grep it or read with offset/limit. Converted Markdown is grep-able by heading (^#).",
-			"Pass raw=true to skip Markdown/JSON conversion and get the decoded body as-is (still subject to the size gate).",
-			"GitHub issue/PR/repo/actions-run links are fetched through the gh CLI automatically; pass raw=true to force the rendered HTML page.",
-		],
 		parameters: Type.Object({
 			url: Type.String({ description: "Absolute http(s) URL" }),
 			method: Type.Optional(

package/{provider-stall-watchdog.ts → extensions/provider-stall-watchdog.ts}

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { readSettings, resolveConfig, settingsPaths } from "./extension-config.ts";
+import { readSettings, resolveConfig, settingsPaths } from "../lib/extension-config.ts";
 
 export const MAX_TIMER_MS = 2_147_483_647;
 export const DEFAULT_CONFIG = {

package/{session-name.ts → extensions/session-name.ts}

@@ -18,7 +18,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resolveConfig } from "./extension-config.ts";
+import { resolveConfig } from "../lib/extension-config.ts";
 
 // `complete` moved between pi-ai layouts: older builds re-export it from the
 // package index, newer ones expose it only via the `/compat` subpath. A static

package/{sword-header.ts → extensions/sword-header.ts}

@@ -14,7 +14,7 @@
  */
 
 import type { ExtensionAPI, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
-import { resolveConfig } from "./extension-config.ts";
+import { resolveConfig } from "../lib/extension-config.ts";
 
 type Config = { enabled: boolean };
 const DEFAULT_CONFIG: Config = { enabled: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "3.4.1",
+  "version": "4.0.1",
   "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, a themed ASCII startup header, Opus 4.8 fast mode, and a provider-stall watchdog.",
   "author": "Jacek Juraszek",
   "license": "MIT",
@@ -28,13 +28,8 @@
     "node": ">=20"
   },
   "files": [
-    "fetch.ts",
-    "doc_to_md.ts",
-    "session-name.ts",
-    "sword-header.ts",
-    "fast-mode.ts",
-    "provider-stall-watchdog.ts",
-    "extension-config.ts",
+    "extensions",
+    "lib",
     "scripts/pdf_to_md.py",
     "types/**/*.d.ts",
     "README.md",
@@ -42,18 +37,13 @@
   ],
   "scripts": {
     "check:agents-core": "node scripts/check-agents-core.mjs",
-    "test": "node --test \"*.test.ts\"",
-    "typecheck": "npx -y tsc --noEmit --allowImportingTsExtensions --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck --esModuleInterop --resolveJsonModule --lib es2022 --types node fetch.ts fetch.test.ts doc_to_md.ts doc_to_md.test.ts session-name.ts session-name.test.ts sword-header.ts sword-header.test.ts fast-mode.ts fast-mode.test.ts provider-stall-watchdog.ts provider-stall-watchdog.test.ts extension-config.ts types/turndown-plugin-gfm.d.ts",
+    "test": "node --test \"test/*.test.ts\"",
+    "typecheck": "npx -y tsc --noEmit",
     "test:all": "npm run check:agents-core && npm run test && npm run typecheck"
   },
   "pi": {
     "extensions": [
-      "./fetch.ts",
-      "./doc_to_md.ts",
-      "./session-name.ts",
-      "./sword-header.ts",
-      "./fast-mode.ts",
-      "./provider-stall-watchdog.ts"
+      "./extensions"
     ],
     "image": "https://raw.githubusercontent.com/jjuraszek/pi-quiver/main/pi-quiver.png"
   },