pi-quiver 3.2.0 → 3.3.1

package/CHANGELOG.md

@@ -8,6 +8,17 @@ 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.1 - 2026-07-19
+
+- **`provider-stall-watchdog`: bounded multi-stall retry via `maxStallRetries`.** Each semantic stall converts to a retryable error until the budget is exhausted; previously only the first stall retried, so a longer provider outage forced manual resubmission (observed stuck streams recover in seconds on a fresh request). Default = layered `retry.maxRetries` (Pi default 3); explicit config wins; positive integer, fails closed. A successful assistant turn resets the counter, mirroring Pi's retry loop.
+- **Watchdog notices moved to the main window.** The silence warning is now a `notify(..., "warning")` transcript line instead of a bottom status-line entry; the status-line integration is removed. Recovery notices report the attempt as `(used/max)`.
+
+## 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 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).
 
@@ -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,39 @@ 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,
+    "maxStallRetries": 3
+  }
+}
+```
+
+`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: each semantic stall is aborted and offered to Pi retry until `maxStallRetries` conversions are used; further stalls stop for manual resubmission. `maxStallRetries` defaults to the layered `retry.maxRetries` (Pi default 3); consecutive stall conversions consume Pi retry attempts without a success reset in between, so keep `maxStallRetries <= retry.maxRetries`. A successful assistant turn resets the stall counter (mirroring Pi's own retry counter). The silence warning and all watchdog notices render as main-window notifications, not the bottom status line. 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.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",
   "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,268 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readSettings, resolveConfig, settingsPaths } 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;
+	maxStallRetries: 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;
+	maxStallRetries?: 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", "maxStallRetries"] 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" };
+	if (!isPositiveInteger(candidate.maxStallRetries)) return { ok: false, error: "maxStallRetries must be a positive integer" };
+	return {
+		ok: true,
+		config: {
+			enabled: candidate.enabled,
+			warningMs: candidate.warningMs,
+			recoveryMs: candidate.recoveryMs,
+			maxStallRetries: candidate.maxStallRetries,
+		},
+	};
+}
+
+function isTimerDelay(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value > 0 && value <= MAX_TIMER_MS;
+}
+
+function isPositiveInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+/** Pi's own resolution is `settings.retry?.maxRetries ?? 3` over the same layered settings.json files. */
+export function resolveRetryMaxRetries(cwd: string): number {
+	let maxRetries = 3;
+	for (const path of settingsPaths(cwd)) {
+		const retry = readSettings(path)?.retry;
+		if (retry === null || typeof retry !== "object" || Array.isArray(retry)) continue;
+		const value = (retry as Record<string, unknown>).maxRetries;
+		if (isPositiveInteger(value)) maxRetries = value;
+	}
+	return maxRetries;
+}
+
+export function resolveWatchdogConfig(cwd: string): ConfigValidation {
+	const candidate = resolveConfig(cwd, "providerStallWatchdog", DEFAULT_CANDIDATE, coerce);
+	if (candidate.blockIsObject === true && candidate.maxStallRetries === undefined) {
+		candidate.maxStallRetries = resolveRetryMaxRetries(cwd);
+	}
+	return validateConfig(candidate);
+}
+
+const defaultRuntime: WatchdogRuntime = {
+	now: () => Date.now(),
+	setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+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 warningNotice(config: WatchdogConfig): string {
+	return `No model progress for ${formatElapsed(config.warningMs)}; aborting and asking Pi to retry in ${formatElapsed(config.recoveryMs - config.warningMs)} (Esc aborts now)`;
+}
+
+function exhaustedNotice(config: WatchdogConfig): string {
+	return `Stall retry budget (${config.maxStallRetries}) exhausted; aborting without another automatic retry. Submit the message again manually.`;
+}
+
+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: { notify(text: string, type?: string): void } | undefined;
+		let watchdogAbortedGeneration: number | undefined;
+		let timeoutConversionPending = false;
+		let stallRetriesUsed = 0;
+		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 clear = () => {
+			clearTimers();
+			removeSignalListener?.();
+			removeSignalListener = undefined;
+			activeGeneration = undefined;
+		};
+		const disarm = () => { clear(); warned = false; };
+		const resetRunState = () => {
+			disarm();
+			activeRun = false;
+			pendingInteractive = false;
+			stallRetriesUsed = 0;
+			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?.notify(warningNotice(config), "warning");
+				}
+				if (kind === "recovery") {
+					clearTimers();
+					warned = false;
+					if (stallRetriesUsed >= config.maxStallRetries) {
+						ui?.notify(exhaustedNotice(config));
+						ctx.abort();
+						return;
+					}
+					watchdogAbortedGeneration = capturedGeneration;
+					timeoutConversionPending = true;
+					stallRetriesUsed += 1;
+					ui?.notify(`No model progress for ${formatElapsed(elapsed)}; aborting now. Pi will retry (${stallRetriesUsed}/${config.maxStallRetries}) 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;
+			clearTimers();
+			schedule(ctx);
+		});
+		pi.on("message_end", (event) => {
+			if (event.message.role !== "assistant") return;
+			const matchesWatchdogAbort = event.message.stopReason === "aborted"
+				&& activeGeneration === watchdogAbortedGeneration
+				&& timeoutConversionPending;
+			disarm();
+			// Mirror Pi's retry loop, which resets its attempt counter on any successful assistant turn.
+			if (event.message.stopReason !== "aborted" && event.message.stopReason !== "error") stallRetriesUsed = 0;
+			if (!matchesWatchdogAbort || !config) return;
+			timeoutConversionPending = false;
+			convertedTimeout = true;
+			continuationStarted = false;
+			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();