pi-quiver 6.3.1 → 6.4.0

package/CHANGELOG.md

@@ -8,6 +8,10 @@ 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.
 
+## v6.4.0 - 2026-09-28
+
+- provider-stall-watchdog: per-model threshold overrides via a `models` map on `quiver.providerStallWatchdog` - glob keys like `lmstudio/*` override `firstEventMs`/`warningMs`/`recoveryMs` for matching models, so slow local servers get patience without raising the global defaults (#18).
+
 ## v6.3.1 - 2026-09-25
 
 - `provider-stall-watchdog` recovers again on pi >= 0.86 ([#23](https://github.com/jjuraszek/pi-quiver/issues/23)): pi's session abort now fences the run so its retry loop never runs after a watchdog abort; the watchdog omits the aborted attempt from the model's context at `turn_end` and re-drives the request itself via a hidden custom message after pi's backoff, honoring pi's `retry.enabled` / `retry.baseDelayMs` / `retry.maxAgentDelayMs` live and the existing `maxStallRetries` cap. Print/json await the backoff; TUI/RPC show `Retrying (n/m) in Ns... (Esc to cancel)` in the status bar on the timer path. In TUI, Esc, a new prompt, a tree switch, or compaction cancels the pending retry; RPC cancels on a new prompt, not Esc. Behavior guide: `doc/provider-stall-watchdog.md`. Dev dependencies on `@earendil-works/*` move to `^0.87.1`.

package/README.md

@@ -186,7 +186,7 @@ a new setting is registered there or it warns as unknown.
 ```text
 Warning: pi-quiver settings (/Users/x/.pi/agent/settings.json): unknown or misplaced keys - unknown ones fall back to defaults
   "providerStallWatchdog" at top level - move under "quiver"
-  "quiver.providerStallWatchdog.timeoutMs" - unknown; accepted: enabled, firstEventMs, warningMs, recoveryMs, maxStallRetries
+  "quiver.providerStallWatchdog.timeoutMs" - unknown; accepted: enabled, firstEventMs, warningMs, recoveryMs, maxStallRetries, models
 ```
 
 Worked mixed-shape example: global `settings.json` has flat
@@ -218,7 +218,10 @@ not a pi-quiver setting and is never nested):
       "firstEventMs": 20000,
       "warningMs": 120000,
       "recoveryMs": 240000,
-      "maxStallRetries": 3
+      "maxStallRetries": 3,
+      "models": {
+        "lmstudio/*": { "firstEventMs": 600000, "recoveryMs": 600000 }
+      }
     }
   },
   "retry": {
@@ -236,13 +239,16 @@ not a pi-quiver setting and is never nested):
 | `warningMs` | `120000` | mid-stream, `ctx.mode === "tui"` only | Silence since the last non-empty text/thinking/toolcall delta; notifies. |
 | `recoveryMs` | `240000` | mid-stream, `ctx.mode === "tui"` only | Same clock; aborts and converts. Must be `> warningMs`. |
 | `maxStallRetries` | layered `retry.maxRetries`, else `3` | shared by both tiers | Watchdog aborts that may convert to a retryable error before stopping. |
+| `models` | `{}` | per-model overrides of the three thresholds | Glob keys match `provider/model` (case-insensitive, `*` matches any run of characters, first match wins); each entry may override `firstEventMs`, `warningMs`, and/or `recoveryMs`. |
 
 `providerStallWatchdog` is OFF by default. Once enabled it arms in two tiers per provider request:
 
 - **Pre-first-event (`firstEventMs`).** Armed at every provider request, in every mode and from every origin - including extension-triggered turns that never emit `before_agent_start` - and cleared by the first assistant `message_start`. On expiry the request is aborted and, budget permitting, converted to a retryable error and re-driven after pi's backoff when `retry.enabled` is true, so an unresponsive request recovers in ~22s (20s detection + 2s backoff) instead of the ~240s it took when only the mid-stream tier existed.
 - **Mid-stream (`warningMs` / `recoveryMs`).** Armed from the first assistant `message_start` onward, and only when `ctx.mode === "tui"`. Aborting mid-generation discards billed output tokens and an unattended run has nobody to read the warning, so headless mid-stream silence deliberately falls through to the transport timeout instead.
 
-**Raise `firstEventMs` if your provider is legitimately slow to first event.** Queueing gateways, throttled endpoints, and busy single-slot local model servers can hold the connection for well over 20s before their first stream event; every false abort re-uploads the whole context and spends one stall retry.
+`models` retunes the three thresholds per model. A request's effective thresholds are the base knobs overlaid with the first entry whose glob matches its `provider/model` label - `"lmstudio/*"` covers a whole local server, `"openai/gpt-5.4"` one remote model. An override that would leave the merged `warningMs >= recoveryMs` is invalid and fails closed at startup like any other invalid watchdog config.
+
+**Raise `firstEventMs` if your provider is legitimately slow to first event** - per model via `models` when only one provider is slow. Queueing gateways, throttled endpoints, and busy single-slot local model servers can hold the connection for well over 20s before their first stream event; every false abort re-uploads the whole context and spends one stall retry.
 
 **Leave pi's own `httpIdleTimeoutMs` (default `300000`) at its default.** It is the transport backstop, and a single value drives undici's `headersTimeout` *and* `bodyTimeout` - lowering it to get fast pre-stream failure also truncates legitimate mid-stream gaps. `firstEventMs` is the knob for pre-stream silence.
 

package/extensions/provider-stall-watchdog.ts

@@ -7,14 +7,20 @@ export const DEFAULT_CONFIG = {
 	firstEventMs: 20_000,
 	warningMs: 120_000,
 	recoveryMs: 240_000,
+	models: {},
 } as const;
 
-export type WatchdogConfig = {
-	enabled: boolean;
+export type WatchdogThresholds = {
 	firstEventMs: number;
 	warningMs: number;
 	recoveryMs: number;
+};
+
+export type WatchdogConfig = WatchdogThresholds & {
+	enabled: boolean;
 	maxStallRetries: number;
+	/** Per-model threshold overrides keyed by glob; see thresholdsFor. */
+	models: Record<string, Partial<WatchdogThresholds>>;
 };
 
 export type WatchdogRuntime = {
@@ -30,6 +36,7 @@ export type ConfigCandidate = {
 	warningMs?: unknown;
 	recoveryMs?: unknown;
 	maxStallRetries?: unknown;
+	models?: unknown;
 };
 
 export type ConfigValidation =
@@ -45,12 +52,17 @@ export function coerce(raw: unknown): ConfigCandidate | undefined {
 
 	const source = raw as Record<string, unknown>;
 	const candidate: ConfigCandidate = { blockIsObject: true };
-	for (const key of ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries"] as const) {
+	for (const key of ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries", "models"] as const) {
 		if (Object.hasOwn(source, key)) candidate[key] = source[key];
 	}
 	return candidate;
 }
 
+const THRESHOLD_KEYS = ["firstEventMs", "warningMs", "recoveryMs"] as const;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	value !== null && typeof value === "object" && !Array.isArray(value);
+
 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" };
@@ -59,6 +71,21 @@ export function validateConfig(candidate: ConfigCandidate): ConfigValidation {
 	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 (!isNonNegativeInteger(candidate.maxStallRetries)) return { ok: false, error: "maxStallRetries must be a non-negative integer" };
+	if (!isRecord(candidate.models)) return { ok: false, error: "models must be an object" };
+	for (const [pattern, override] of Object.entries(candidate.models)) {
+		if (!isRecord(override)) return { ok: false, error: `models["${pattern}"] must be an object` };
+		for (const key of Object.keys(override)) {
+			if (!(THRESHOLD_KEYS as readonly string[]).includes(key)) {
+				return { ok: false, error: `models["${pattern}"] has unknown key "${key}"; accepted: ${THRESHOLD_KEYS.join(", ")}` };
+			}
+			if (!isTimerDelay(override[key])) return { ok: false, error: `models["${pattern}"].${key} must be a positive timer delay` };
+		}
+		const mergedWarning = (override.warningMs ?? candidate.warningMs) as number;
+		const mergedRecovery = (override.recoveryMs ?? candidate.recoveryMs) as number;
+		if (mergedWarning >= mergedRecovery) {
+			return { ok: false, error: `models["${pattern}"] leaves warningMs (${mergedWarning}) >= recoveryMs (${mergedRecovery})` };
+		}
+	}
 	return {
 		ok: true,
 		config: {
@@ -67,6 +94,7 @@ export function validateConfig(candidate: ConfigCandidate): ConfigValidation {
 			warningMs: candidate.warningMs,
 			recoveryMs: candidate.recoveryMs,
 			maxStallRetries: candidate.maxStallRetries,
+			models: candidate.models as Record<string, Partial<WatchdogThresholds>>,
 		},
 	};
 }
@@ -144,20 +172,41 @@ function formatElapsed(ms: number): string {
 
 const ABORT_STUCK_NOTICE = `The stalled request did not stop within ${formatElapsed(ABORT_GRACE_MS)} of being aborted; the provider connection is unresponsive. No automatic retry will run - the turn will not end until the HTTP idle timeout expires.`;
 
-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 warningNotice(thresholds: WatchdogThresholds): string {
+	return `No model progress for ${formatElapsed(thresholds.warningMs)}; aborting and asking Pi to retry in ${formatElapsed(thresholds.recoveryMs - thresholds.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.`;
 }
 
-function firstEventRetryNotice(config: WatchdogConfig): string {
-	return `Provider sent no response for ${formatElapsed(config.firstEventMs)}; stopping and retrying the request.`;
+function firstEventRetryNotice(thresholds: WatchdogThresholds): string {
+	return `Provider sent no response for ${formatElapsed(thresholds.firstEventMs)}; stopping and retrying the request.`;
+}
+
+function firstEventExhaustedNotice(thresholds: WatchdogThresholds): string {
+	return `Provider sent no response for ${formatElapsed(thresholds.firstEventMs)} and the stall-retry budget is spent; the request was stopped.`;
 }
 
-function firstEventExhaustedNotice(config: WatchdogConfig): string {
-	return `Provider sent no response for ${formatElapsed(config.firstEventMs)} and the stall-retry budget is spent; the request was stopped.`;
+/** A glob where `*` matches any run of characters; matching is case-insensitive. */
+function modelPattern(pattern: string): RegExp {
+	const source = pattern.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+	return new RegExp(`^${source}$`, "i");
+}
+
+/**
+ * Effective thresholds for one request: the base knobs overlaid with the
+ * first `models` entry whose glob matches the request's `provider/model`
+ * label. First match wins; later entries for the same model are ignored.
+ */
+export function thresholdsFor(config: WatchdogConfig, model: { provider: string; id: string } | undefined): WatchdogThresholds {
+	const base: WatchdogThresholds = { firstEventMs: config.firstEventMs, warningMs: config.warningMs, recoveryMs: config.recoveryMs };
+	if (model === undefined) return base;
+	const label = `${model.provider}/${model.id}`;
+	for (const [pattern, override] of Object.entries(config.models)) {
+		if (modelPattern(pattern).test(label)) return { ...base, ...override };
+	}
+	return base;
 }
 
 export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRuntime): (pi: ExtensionAPI) => void {
@@ -171,6 +220,7 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 		let config: WatchdogConfig | undefined;
 		let generation = 0;
 		let activeGeneration: number | undefined;
+		let activeModel: { provider: string; id: string } | undefined;
 		let lastSemanticAt = 0;
 		let warned = false;
 		let deadlineEpoch = 0;
@@ -281,9 +331,10 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 		const armFirstEvent = (ctx: { abort(): void }) => {
 			if (activeGeneration === undefined || !config) return;
 			const cfg = config;
+			const thresholds = thresholdsFor(cfg, activeModel);
 			const capturedGeneration = activeGeneration;
 			const capturedDeadlineEpoch = ++deadlineEpoch;
-			const threshold = cfg.firstEventMs;
+			const threshold = thresholds.firstEventMs;
 			const run = () => {
 				if (capturedGeneration !== activeGeneration || capturedDeadlineEpoch !== deadlineEpoch || !activeRun || firstEventSeen) return;
 				const elapsed = runtime.now() - lastSemanticAt;
@@ -292,15 +343,16 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 					return;
 				}
 				abortStall(ctx, capturedGeneration, {
-					retry: () => firstEventRetryNotice(cfg),
-					exhausted: () => firstEventExhaustedNotice(cfg),
-				}, `Provider first-event timeout after ${cfg.firstEventMs} ms without a stream event`);
+					retry: () => firstEventRetryNotice(thresholds),
+					exhausted: () => firstEventExhaustedNotice(thresholds),
+				}, `Provider first-event timeout after ${thresholds.firstEventMs} ms without a stream event`);
 			};
 			timers.firstEvent = runtime.setTimeout(run, threshold);
 		};
 		const schedule = (ctx: { abort(): void }) => {
 			if (activeGeneration === undefined || !config) return;
 			const cfg = config;
+			const thresholds = thresholdsFor(cfg, activeModel);
 			const capturedGeneration = activeGeneration;
 			const capturedDeadlineEpoch = ++deadlineEpoch;
 			const run = (kind: "warning" | "recovery", threshold: number) => () => {
@@ -312,17 +364,17 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 				}
 				if (kind === "warning" && !warned) {
 					warned = true;
-					announce(warningNotice(cfg), "warning");
+					announce(warningNotice(thresholds), "warning");
 				}
 				if (kind === "recovery") {
 					abortStall(ctx, capturedGeneration, {
 						retry: () => `No model progress for ${formatElapsed(elapsed)}; aborting now. Pi will retry (${stallRetriesUsed}/${cfg.maxStallRetries}) if retry is enabled and capacity remains. Pending follow-ups are returned to the editor.`,
 						exhausted: () => exhaustedNotice(cfg),
-					}, `Provider semantic timeout after ${cfg.recoveryMs} ms without progress`);
+					}, `Provider semantic timeout after ${thresholds.recoveryMs} ms without progress`);
 				}
 			};
-			timers.warning = runtime.setTimeout(run("warning", cfg.warningMs), cfg.warningMs);
-			timers.recovery = runtime.setTimeout(run("recovery", cfg.recoveryMs), cfg.recoveryMs);
+			timers.warning = runtime.setTimeout(run("warning", thresholds.warningMs), thresholds.warningMs);
+			timers.recovery = runtime.setTimeout(run("recovery", thresholds.recoveryMs), thresholds.recoveryMs);
 		};
 
 		pi.on("before_provider_request", (_event, ctx) => {
@@ -347,6 +399,7 @@ export function createProviderStallWatchdog(runtime: WatchdogRuntime = defaultRu
 			if (!activeRun) return;
 			disarm();
 			activeGeneration = ++generation;
+			activeModel = ctx.model;
 			lastSemanticAt = runtime.now();
 			const target = ctx.signal;
 			if (target) {

package/lib/extension-config.ts

@@ -46,7 +46,7 @@ export const QUIVER_CONFIG_KEYS: Record<string, readonly string[]> = {
 	fastMode: ["enabled"],
 	sessionAutoName: ["enabled", "ghosttyTab", "herdrTab", "rules", "deny", "revisitFirstTurn", "revisitEveryTurns"],
 	swordHeader: ["enabled"],
-	providerStallWatchdog: ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries"],
+	providerStallWatchdog: ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries", "models"],
 	slack: ["enabled", "cachePath", "policyPath", "userTokenEnv", "userTokenCommand", "userTokenCommandTimeoutSeconds", "botTokenEnv", "uploadThresholdChars"],
 	docToMd: DOC_TO_MD_OPTIONS.filter((o) => o.settable).map((o) => o.key),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "6.3.1",
+  "version": "6.4.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",