pi-quiver 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -8,6 +8,12 @@ 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.
 
+## v3.3.0 - 2026-07-17
+
+- **`provider-stall-watchdog`: opt-in semantic-silence recovery.** Policy D warns after configured silence, aborts the first semantic stall, and offers it once to Pi's existing retry loop; a second stall stops without another watchdog retry. OFF by default.
+- **Human-TUI boundary.** Arms only for confirmed human interactive TUI runs; JSON, RPC, print, and subagent runs are excluded by activation rather than environment or session lineage.
+- **Compatibility and fallback.** Verified against Pi 0.80.10. Automatic continuation requires enabled Pi retry with remaining capacity; disabled, exhausted, or incompatible retry leaves the request stopped for manual resubmission. Pending steering and follow-ups return to the editor and are excluded from automatic continuation; invalid merged watchdog configuration fails closed.
+
 ## v3.2.0 - 2026-07-12
 
 - Add `fast-mode` extension: opt-in Anthropic fast mode for Claude Opus 4.8 (`speed: "fast"` payload + `fast-mode-2026-02-01` beta header), controlled via `fastMode` settings key, `--fast` flag, and `/fast [on|off|status]`. OFF by default. Preserves OAuth identity betas. Requires pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5 (the `before_provider_headers` hook).

package/README.md

@@ -18,7 +18,7 @@ But the moment an agent does that, one `fetch` or PDF read can dump hundreds of
 
 `fetch` and `doc_to_md` bring real web pages, GitHub issues/PRs, and local PDF/DOCX/PPTX files into context - and every result is size-gated by construction: over 32 KB or 1000 lines spills to a temp file with a preview and a grep/read hint, so a single call can never flood the window. Ingestion is what makes data-driven work possible; the gate is what keeps it safe.
 
-`session-name` and `sword-header` are smaller, opt-in ergonomics on top - session labeling and a themed startup header.
+`session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` are opt-in ergonomics and recovery controls: session labeling, a themed startup header, Anthropic fast mode, and semantic-stall recovery.
 
 ## Part of the pi agent toolkit
 
@@ -33,7 +33,7 @@ No code dependency between them. pi-quiver is call-level: it gates the size of w
 
 ## Mental model
 
-Every extension here is context-safe by construction, not by convention: the size check runs on every call, there's no flag to forget. Two tools bring real sources in (`fetch`, `doc_to_md`); two are opt-in ergonomics (`session-name`, `sword-header`).
+Every ingestion extension here is context-safe by construction, not by convention: the size check runs on every call, there's no flag to forget. `fetch` and `doc_to_md` bring real sources in; `session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` are opt-in.
 
 ```mermaid
 flowchart LR
@@ -67,6 +67,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | `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 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
+| `provider-stall-watchdog.ts` | - | Opt-in semantic-silence watchdog for human interactive TUI runs. Warns after 2 minutes and recovers after 4 minutes; policy D offers the first stall once to Pi's retry loop, then stops a second stall. 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).
 
@@ -77,18 +78,21 @@ Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md
 | Size gate | Text/Markdown/JSON output over 32 KB or 1000 lines spills to a temp file with a 60-line preview instead of inlining. |
 | Content routing | HTML -> Markdown, binary -> untouched file, GitHub URLs -> `gh` CLI, everything else -> the size gate. |
 | Graceful degradation | Optional binaries (`gh`, `uv`, LibreOffice) are never hard install-time deps; each has a defined, documented fallback or failure mode. |
-| Opt-in ergonomics | `session-name` and `sword-header` do nothing until explicitly enabled in `settings.json`. |
+| Opt-in extensions | `session-name`, `sword-header`, `fast-mode`, and `provider-stall-watchdog` do nothing until explicitly enabled in `settings.json`. |
+| Provider stall recovery | The watchdog detects missing parsed semantic progress, not network liveness. It is limited to confirmed human interactive TUI runs. |
 
 ## When to use
 
 - An agent needs to reason from a real web page, GitHub issue/PR, or local PDF/DOCX/PPTX instead of memory.
 - You want that ingestion to be safe by default, with no risk of a single call blowing the context budget.
+- A human interactive Pi session needs an opt-in guard against providers that stop making semantic progress.
 
 ## When NOT to use
 
 - You need a general-purpose web scraper (JS-rendered pages, pagination, auth flows) - `fetch` does plain HTTP + Readability extraction, nothing more.
 - You need spreadsheet conversion - `doc_to_md` explicitly excludes spreadsheets (they paginate badly via PDF).
-- You want automatic session naming or a custom header without opting in - both stay off until you flip the config.
+- You want automatic session naming, a custom header, fast mode, or stall recovery without opting in - all stay off until you flip the config.
+- You need watchdog behavior in JSON, RPC, print, or subagent runs - activation excludes them by input origin and mode, not environment or session lineage.
 
 ## Install
 
@@ -133,18 +137,38 @@ None is a hard install-time dependency of the package; they are tools you provid
 
 ### Opt-in extension config
 
-Both are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer):
+These extensions are opt-in via `settings.json` (project `.pi/settings.json` overrides the global agent-dir layer):
 
 ```jsonc
 {
   "sessionAutoName": { "enabled": false, "ghosttyTab": true }, // or boolean shorthand
   "swordHeader": false,                                        // or { "enabled": true }
-  "fastMode": false                                            // or { "enabled": true }
+  "fastMode": false,                                           // or { "enabled": true }
+  "providerStallWatchdog": false                               // or { "enabled": true }
 }
 ```
 
 `sessionAutoName.enabled` makes one extra short LLM call per session (once, after the first turn) to title it; `false` (default) makes no model calls. `fastMode` only affects `claude-opus-4-8` requests on Anthropic's `anthropic-messages` API; enabling it opts into premium fast-mode pricing. `--fast` forces it on for one launch; `/fast on|off` toggles live. Proxy providers (opencode, cloudflare-ai-gateway) are excluded. `fastMode`'s header injection needs the `before_provider_headers` hook (pi bundling `@earendil-works/pi-coding-agent` >= 0.80.5); on older pi the beta header is silently not sent. See [doc/fetch.md](doc/fetch.md) and [doc/doc-to-md.md](doc/doc-to-md.md) for the ingestion tools' full reference; session-name/sword-header behavior above is complete.
 
+Recommended explicit retry and watchdog settings:
+
+```json
+{
+  "retry": {
+    "enabled": true,
+    "maxRetries": 3,
+    "baseDelayMs": 2000
+  },
+  "providerStallWatchdog": {
+    "enabled": true,
+    "warningMs": 120000,
+    "recoveryMs": 240000
+  }
+}
+```
+
+`providerStallWatchdog` is OFF by default and runs only for confirmed human interactive TUI runs. JSON, RPC, print, and subagent runs are excluded by activation, not environment or session lineage. Verified with Pi 0.80.10: the first semantic stall is aborted and offered once to Pi retry; a second stall stops. Automatic continuation needs enabled Pi retry with remaining capacity. Disabled, exhausted, or incompatible retry degrades to manual resubmission. Pending steering or follow-ups return to the editor and are excluded from automatic continuation. Invalid merged watchdog config fails closed.
+
 ## Development
 
 Deps are peers (`@earendil-works/*`, `@sinclair/typebox`) plus the bundled

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-quiver",
-  "version": "3.2.0",
-  "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, and a themed ASCII startup header.",
+  "version": "3.3.0",
+  "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",
   "type": "module",
@@ -33,6 +33,7 @@
     "session-name.ts",
     "sword-header.ts",
     "fast-mode.ts",
+    "provider-stall-watchdog.ts",
     "extension-config.ts",
     "scripts/pdf_to_md.py",
     "types/**/*.d.ts",
@@ -42,7 +43,7 @@
   "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 extension-config.ts types/turndown-plugin-gfm.d.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:all": "npm run check:agents-core && npm run test && npm run typecheck"
   },
   "pi": {
@@ -51,7 +52,8 @@
       "./doc_to_md.ts",
       "./session-name.ts",
       "./sword-header.ts",
-      "./fast-mode.ts"
+      "./fast-mode.ts",
+      "./provider-stall-watchdog.ts"
     ],
     "image": "https://raw.githubusercontent.com/jjuraszek/pi-quiver/main/pi-quiver.png"
   },

package/provider-stall-watchdog.ts

@@ -0,0 +1,245 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveConfig } from "./extension-config.ts";
+
+export const MAX_TIMER_MS = 2_147_483_647;
+export const DEFAULT_CONFIG = {
+	enabled: false,
+	warningMs: 120_000,
+	recoveryMs: 240_000,
+} as const;
+
+export type WatchdogConfig = {
+	enabled: boolean;
+	warningMs: number;
+	recoveryMs: number;
+};
+
+export type WatchdogRuntime = {
+	now(): number;
+	setTimeout(callback: () => void, delayMs: number): unknown;
+	clearTimeout(handle: unknown): void;
+};
+
+export type ConfigCandidate = {
+	blockIsObject?: unknown;
+	enabled?: unknown;
+	warningMs?: unknown;
+	recoveryMs?: unknown;
+};
+
+export type ConfigValidation =
+	| { ok: true; config: WatchdogConfig }
+	| { ok: false; error: string };
+
+const DEFAULT_CANDIDATE: ConfigCandidate = { blockIsObject: true, ...DEFAULT_CONFIG };
+
+export function coerce(raw: unknown): ConfigCandidate | undefined {
+	if (raw === undefined) return undefined;
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { blockIsObject: false };
+
+	const source = raw as Record<string, unknown>;
+	const candidate: ConfigCandidate = { blockIsObject: true };
+	for (const key of ["enabled", "warningMs", "recoveryMs"] as const) {
+		if (Object.hasOwn(source, key)) candidate[key] = source[key];
+	}
+	return candidate;
+}
+
+export function validateConfig(candidate: ConfigCandidate): ConfigValidation {
+	if (candidate.blockIsObject !== true) return { ok: false, error: "providerStallWatchdog must be an object" };
+	if (typeof candidate.enabled !== "boolean") return { ok: false, error: "enabled must be a boolean" };
+	if (!isTimerDelay(candidate.warningMs)) return { ok: false, error: "warningMs must be a positive timer delay" };
+	if (!isTimerDelay(candidate.recoveryMs)) return { ok: false, error: "recoveryMs must be a positive timer delay" };
+	if (candidate.warningMs >= candidate.recoveryMs) return { ok: false, error: "warningMs must be less than recoveryMs" };
+	return {
+		ok: true,
+		config: {
+			enabled: candidate.enabled,
+			warningMs: candidate.warningMs,
+			recoveryMs: candidate.recoveryMs,
+		},
+	};
+}
+
+function isTimerDelay(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value > 0 && value <= MAX_TIMER_MS;
+}
+
+export function resolveWatchdogConfig(cwd: string): ConfigValidation {
+	return validateConfig(resolveConfig(cwd, "providerStallWatchdog", DEFAULT_CANDIDATE, coerce));
+}
+
+const defaultRuntime: WatchdogRuntime = {
+	now: () => Date.now(),
+	setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+const STATUS_KEY = "providerStallWatchdog";
+const SECOND_STALL_NOTICE = "The retry also stopped making progress; aborting without another automatic retry. Submit the message again manually.";
+const DEGRADATION_NOTICE = "The stalled request was stopped, but Pi did not start an automatic retry. Retry may be disabled, exhausted, or incompatible; submit the message again to retry manually.";
+
+type Timer = { warning?: unknown; recovery?: unknown };
+
+function formatElapsed(ms: number): string {
+	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+	if (ms % 1_000 === 0) return `${ms / 1_000}s`;
+	return `${ms}ms`;
+}
+
+function warningStatus(config: WatchdogConfig): string {
+	return `No model progress for ${formatElapsed(config.warningMs)}; aborting and asking Pi to retry once in ${formatElapsed(config.recoveryMs - config.warningMs)} (Esc aborts now)`;
+}
+
+export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRuntime): (pi: ExtensionAPI) => void {
+	return (pi) => {
+		let pendingInteractive = false;
+		let activeRun = false;
+		let disabled = false;
+		let config: WatchdogConfig | undefined;
+		let generation = 0;
+		let activeGeneration: number | undefined;
+		let lastSemanticAt = 0;
+		let warned = false;
+		let epoch = 0;
+		let deadlineEpoch = 0;
+		let timers: Timer = {};
+		let removeSignalListener: (() => void) | undefined;
+		let ui: { setStatus(key: string, text: string | undefined): void; notify(text: string, type?: string): void } | undefined;
+		let watchdogAbortedGeneration: number | undefined;
+		let timeoutConversionPending = false;
+		let stallRetryConsumed = false;
+		let continuationStarted = false;
+		let convertedTimeout = false;
+
+		const clearTimers = () => {
+			if (timers.warning !== undefined) runtime.clearTimeout(timers.warning);
+			if (timers.recovery !== undefined) runtime.clearTimeout(timers.recovery);
+			timers = {};
+		};
+		const clearDeadlines = () => {
+			clearTimers();
+			ui?.setStatus(STATUS_KEY, undefined);
+		};
+		const clear = () => {
+			clearDeadlines();
+			removeSignalListener?.();
+			removeSignalListener = undefined;
+			activeGeneration = undefined;
+		};
+		const disarm = () => { clear(); warned = false; };
+		const resetRunState = () => {
+			disarm();
+			activeRun = false;
+			pendingInteractive = false;
+			stallRetryConsumed = false;
+			continuationStarted = false;
+			convertedTimeout = false;
+			watchdogAbortedGeneration = undefined;
+			timeoutConversionPending = false;
+		};
+		const schedule = (ctx: { ui: typeof ui; abort(): void }) => {
+			if (activeGeneration === undefined || !config) return;
+			const capturedGeneration = activeGeneration;
+			const capturedEpoch = epoch;
+			const capturedDeadlineEpoch = ++deadlineEpoch;
+			const run = (kind: "warning" | "recovery", threshold: number) => () => {
+				if (capturedEpoch !== epoch || capturedGeneration !== activeGeneration || capturedDeadlineEpoch !== deadlineEpoch || !activeRun || !config) return;
+				const elapsed = runtime.now() - lastSemanticAt;
+				if (elapsed < threshold) {
+					timers[kind] = runtime.setTimeout(run(kind, threshold), threshold - elapsed);
+					return;
+				}
+				if (kind === "warning" && !warned) {
+					warned = true;
+					ctx.ui?.setStatus(STATUS_KEY, warningStatus(config));
+				}
+				if (kind === "recovery") {
+					clearDeadlines();
+					warned = false;
+					if (stallRetryConsumed) {
+						ui?.notify(SECOND_STALL_NOTICE);
+						ctx.abort();
+						return;
+					}
+					watchdogAbortedGeneration = capturedGeneration;
+					timeoutConversionPending = true;
+					stallRetryConsumed = true;
+					ui?.notify(`No model progress for ${formatElapsed(elapsed)}; aborting now. Pi will retry once if retry is enabled and capacity remains. Pending follow-ups are returned to the editor.`);
+					ctx.abort();
+				}
+			};
+			timers.warning = runtime.setTimeout(run("warning", config.warningMs), config.warningMs);
+			timers.recovery = runtime.setTimeout(run("recovery", config.recoveryMs), config.recoveryMs);
+		};
+
+		pi.on("input", (event) => {
+			if (!activeRun) pendingInteractive = event.source === "interactive";
+		});
+		pi.on("before_agent_start", (_event, ctx) => {
+			if (!pendingInteractive) return;
+			pendingInteractive = false;
+			if (ctx.mode !== "tui" || disabled) return;
+			const resolved = resolveWatchdogConfig(ctx.cwd);
+			if (!resolved.ok) {
+				disabled = true;
+				console.warn(`providerStallWatchdog disabled: ${resolved.error}`);
+				ctx.ui.notify(`providerStallWatchdog disabled: ${resolved.error}`, "warning");
+				return;
+			}
+			config = resolved.config;
+			activeRun = config.enabled;
+		});
+		pi.on("before_provider_request", (_event, ctx) => {
+			if (!activeRun || ctx.mode !== "tui" || !config) return;
+			disarm();
+			if (convertedTimeout) continuationStarted = true;
+			activeGeneration = ++generation;
+			lastSemanticAt = runtime.now();
+			ui = ctx.ui;
+			const target = ctx.signal;
+			if (target) {
+				const listener = () => {
+					if (watchdogAbortedGeneration !== activeGeneration) disarm();
+				};
+				target.addEventListener("abort", listener, { once: true });
+				removeSignalListener = () => target.removeEventListener("abort", listener);
+			}
+			schedule(ctx);
+		});
+		pi.on("message_update", (event, ctx) => {
+			const update = event.assistantMessageEvent;
+			if (activeGeneration === undefined || !(update.type === "text_delta" || update.type === "thinking_delta" || update.type === "toolcall_delta") || update.delta.length === 0) return;
+			lastSemanticAt = runtime.now();
+			warned = false;
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			clearTimers();
+			schedule(ctx);
+		});
+		pi.on("message_end", (event) => {
+			if (event.message.role !== "assistant") return;
+			const matchesWatchdogAbort = event.message.stopReason === "aborted"
+				&& activeGeneration === watchdogAbortedGeneration
+				&& timeoutConversionPending
+				&& stallRetryConsumed;
+			disarm();
+			if (!matchesWatchdogAbort || !config) return;
+			timeoutConversionPending = false;
+			convertedTimeout = true;
+			return { message: { ...event.message, stopReason: "error", errorMessage: `Provider semantic timeout after ${config.recoveryMs} ms without progress` } };
+		});
+		pi.on("agent_end", () => disarm());
+		pi.on("agent_settled", () => {
+			if (convertedTimeout && !continuationStarted) ui?.notify(DEGRADATION_NOTICE);
+			resetRunState();
+		});
+		pi.on("session_shutdown", () => {
+			epoch += 1;
+			resetRunState();
+			config = undefined;
+			disabled = false;
+		});
+	};
+}
+
+export default createProviderStallWatchdog();