pi-hodor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# pi-hodor
+
+[![npm version](https://img.shields.io/npm/v/pi-hodor)](https://www.npmjs.com/package/pi-hodor)
+[![npm downloads](https://img.shields.io/npm/dm/pi-hodor)](https://www.npmjs.com/package/pi-hodor)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+`pi-hodor` is a pi extension that automatically sends a follow-up retry message when an assistant response fails because of transient streaming or connection errors.
+
+It is useful when model output is interrupted by provider-side failures such as `ECONNRESET`, `ETIMEDOUT`, premature stream closure, or partial JSON responses. Instead of stopping and waiting for manual intervention, the extension detects the failure and sends a configurable retry message such as `continue`.
+
+## Features
+
+- Watches assistant messages that end with `stopReason === "error"`
+- Matches the error text against configurable substring patterns
+- Automatically sends a retry message when a match is found
+- Prevents runaway loops with a configurable retry limit
+- Optionally shows UI notifications when an auto-retry happens
+- Supports project-level config overrides without modifying the packaged files
+
+## Installation
+
+Install from npm:
+
+```bash
+pi install npm:pi-hodor
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/vurihuang/pi-hodor
+```
+
+Restart pi after installation so the extension is loaded.
+
+### Load it for a single run
+
+```bash
+pi -e npm:pi-hodor
+```
+
+### Install from a local path
+
+```bash
+pi install /absolute/path/to/pi-hodor
+```
+
+### Load from a local path for one session
+
+```bash
+pi -e /absolute/path/to/pi-hodor
+```
+
+## Verify installation
+
+After restarting pi, the extension is active automatically.
+
+You can confirm it is loaded by triggering a transient stream error during normal use, or by checking that the extension has been installed from npm and is available in your pi package list.
+
+## Usage
+
+Once the extension is loaded, there is nothing else to trigger manually.
+
+When pi receives an assistant message that:
+
+1. ends with an error stop reason, and
+2. contains one of the configured error patterns,
+
+`pi-hodor` automatically sends the configured retry message.
+
+The default retry message is:
+
+```json
+"continue"
+```
+
+## Configuration
+
+Configuration is resolved in this order:
+
+1. `./.pi-hodor.json`
+2. `./.pi/pi-hodor.json`
+3. the bundled `config.json` inside this package
+
+This keeps the package defaults intact while allowing per-project overrides.
+
+### Example config
+
+```json
+{
+  "enabled": true,
+  "retryMessage": "continue",
+  "maxConsecutiveAutoRetries": 99,
+  "notifyOnAutoContinue": true,
+  "errorPatterns": [
+    "error decoding response body",
+    "stream disconnected before completion",
+    "ECONNRESET"
+  ]
+}
+```
+
+### Config fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` | Enables or disables the extension logic. |
+| `retryMessage` | `string` | The exact user message sent back to pi after a matched error. |
+| `maxConsecutiveAutoRetries` | `number` | Maximum automatic retries before the extension stops retrying. |
+| `notifyOnAutoContinue` | `boolean` | Shows a UI notification when an automatic retry happens or when the retry limit is reached. |
+| `errorPatterns` | `string[]` | Case-insensitive substrings used to detect transient failures. |
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run the type check:
+
+```bash
+npm run check
+```
+
+Preview the npm package contents:
+
+```bash
+npm run pack:check
+```
+
+## Package structure
+
+```text
+.
+├── config.json
+├── index.ts
+├── LICENSE
+├── package.json
+├── README.md
+└── tsconfig.json
+```
+
+## Updating
+
+Reinstall the package from npm:
+
+```bash
+pi install npm:pi-hodor
+```
+
+Or update from git:
+
+```bash
+pi install git:github.com/vurihuang/pi-hodor
+```
+
+Restart pi after updating.
+
+## Install as a pi package
+
+This project is already structured as a pi package via the `pi` field in `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}
+```
+
+That means pi can install it from a local path, npm, or git using the standard pi package flow.

package/config.json

@@ -0,0 +1,24 @@
+{
+  "enabled": true,
+  "retryMessage": "continue",
+  "maxConsecutiveAutoRetries": 99,
+  "notifyOnAutoContinue": true,
+  "errorPatterns": [
+    "error decoding response body",
+    "stream disconnected before completion",
+    "stream closed before",
+    "stream closed unexpectedly",
+    "stream interrupted",
+    "stream ended unexpectedly",
+    "premature close",
+    "socket hang up",
+    "connection reset by peer",
+    "connection reset",
+    "read ECONNRESET",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "fetch failed",
+    "unexpected end of JSON input",
+    "unexpected end of input"
+  ]
+}

package/index.ts

@@ -0,0 +1,229 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+type NotifyLevel = "info" | "success" | "warning" | "error";
+
+type NotifierContext = {
+	hasUI: boolean;
+	ui: {
+		notify(message: string, level: NotifyLevel): void;
+	};
+};
+
+type QueueAwareContext = NotifierContext & {
+	cwd: string;
+	isIdle(): boolean;
+	hasPendingMessages(): boolean;
+};
+
+interface AutoContinueConfig {
+	enabled: boolean;
+	retryMessage: string;
+	maxConsecutiveAutoRetries: number;
+	notifyOnAutoContinue: boolean;
+	errorPatterns: string[];
+}
+
+const EXTENSION_NAME = "pi-hodor";
+const BUNDLED_CONFIG_PATH = join(__dirname, "config.json");
+const PROJECT_CONFIG_CANDIDATES = [
+	".pi-hodor.json",
+	join(".pi", "pi-hodor.json"),
+] as const;
+const DEFAULT_CONFIG: AutoContinueConfig = {
+	enabled: true,
+	retryMessage: "continue",
+	maxConsecutiveAutoRetries: 99,
+	notifyOnAutoContinue: true,
+	errorPatterns: [
+		"上游流式响应中断",
+		"error decoding response body",
+		"stream disconnected before completion",
+		"stream closed before",
+		"stream closed unexpectedly",
+		"stream interrupted",
+		"stream ended unexpectedly",
+		"premature close",
+		"socket hang up",
+		"connection reset by peer",
+		"connection reset",
+		"read ECONNRESET",
+		"ECONNRESET",
+		"ETIMEDOUT",
+		"fetch failed",
+		"unexpected end of JSON input",
+		"unexpected end of input",
+	],
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function normalizeConfig(raw: unknown): AutoContinueConfig {
+	const config = isRecord(raw) ? raw : {};
+	const errorPatterns = Array.isArray(config.errorPatterns)
+		? config.errorPatterns
+				.filter((pattern): pattern is string => typeof pattern === "string")
+				.map((pattern) => pattern.trim())
+				.filter(Boolean)
+		: DEFAULT_CONFIG.errorPatterns;
+	const retryMessage =
+		typeof config.retryMessage === "string" && config.retryMessage.trim().length > 0
+			? config.retryMessage.trim()
+			: DEFAULT_CONFIG.retryMessage;
+	const maxConsecutiveAutoRetries =
+		typeof config.maxConsecutiveAutoRetries === "number" && Number.isFinite(config.maxConsecutiveAutoRetries)
+			? Math.max(0, Math.floor(config.maxConsecutiveAutoRetries))
+			: DEFAULT_CONFIG.maxConsecutiveAutoRetries;
+
+	return {
+		enabled: typeof config.enabled === "boolean" ? config.enabled : DEFAULT_CONFIG.enabled,
+		retryMessage,
+		maxConsecutiveAutoRetries,
+		notifyOnAutoContinue:
+			typeof config.notifyOnAutoContinue === "boolean"
+				? config.notifyOnAutoContinue
+				: DEFAULT_CONFIG.notifyOnAutoContinue,
+		errorPatterns: errorPatterns.length > 0 ? errorPatterns : DEFAULT_CONFIG.errorPatterns,
+	};
+}
+
+function safeNotify(ctx: NotifierContext, message: string, level: NotifyLevel) {
+	if (!ctx.hasUI) return;
+	ctx.ui.notify(message, level);
+}
+
+async function ensureBundledConfigFile() {
+	try {
+		await access(BUNDLED_CONFIG_PATH);
+	} catch {
+		await writeFile(BUNDLED_CONFIG_PATH, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf8");
+	}
+}
+
+async function resolveConfigPath(cwd: string) {
+	for (const relativePath of PROJECT_CONFIG_CANDIDATES) {
+		const candidatePath = join(cwd, relativePath);
+		try {
+			await access(candidatePath);
+			return candidatePath;
+		} catch {
+			// Keep searching.
+		}
+	}
+
+	return BUNDLED_CONFIG_PATH;
+}
+
+async function loadConfig(ctx: QueueAwareContext, lastConfigError: { value?: string }) {
+	await ensureBundledConfigFile();
+	const configPath = await resolveConfigPath(ctx.cwd);
+
+	try {
+		const config = normalizeConfig(JSON.parse(await readFile(configPath, "utf8")));
+		lastConfigError.value = undefined;
+		return config;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const errorKey = `${configPath}:${message}`;
+		if (lastConfigError.value !== errorKey) {
+			lastConfigError.value = errorKey;
+			safeNotify(
+				ctx,
+				`[${EXTENSION_NAME}] Failed to read config from ${configPath}. Falling back to defaults: ${message}`,
+				"warning",
+			);
+		}
+		return DEFAULT_CONFIG;
+	}
+}
+
+function extractTextBlocks(content: unknown): string {
+	if (!Array.isArray(content)) return "";
+	return content
+		.flatMap((block) => {
+			if (!isRecord(block)) return [];
+			if (block.type !== "text") return [];
+			return typeof block.text === "string" ? [block.text] : [];
+		})
+		.join("\n")
+		.trim();
+}
+
+function extractUserText(content: unknown): string {
+	if (typeof content === "string") return content.trim();
+	return extractTextBlocks(content);
+}
+
+function matchesConfiguredError(errorText: string, patterns: string[]) {
+	const normalizedError = errorText.toLowerCase();
+	return patterns.some((pattern) => normalizedError.includes(pattern.toLowerCase()));
+}
+
+export default function (pi: ExtensionAPI) {
+	let consecutiveAutoRetries = 0;
+	let pendingAutoRetryMessage: string | undefined;
+	const lastConfigError: { value?: string } = {};
+
+	pi.on("session_start", async () => {
+		await ensureBundledConfigFile();
+	});
+
+	pi.on("message_end", async (event, ctx) => {
+		if (event.message.role === "user") {
+			const userText = extractUserText(event.message.content);
+			if (pendingAutoRetryMessage && userText === pendingAutoRetryMessage) {
+				pendingAutoRetryMessage = undefined;
+				return;
+			}
+			consecutiveAutoRetries = 0;
+			pendingAutoRetryMessage = undefined;
+			return;
+		}
+
+		if (event.message.role !== "assistant") return;
+
+		if (event.message.stopReason !== "error") {
+			consecutiveAutoRetries = 0;
+			pendingAutoRetryMessage = undefined;
+			return;
+		}
+
+		const config = await loadConfig(ctx as QueueAwareContext, lastConfigError);
+		if (!config.enabled) return;
+		if (ctx.hasPendingMessages()) return;
+		if (consecutiveAutoRetries >= config.maxConsecutiveAutoRetries) {
+			if (config.notifyOnAutoContinue) {
+				safeNotify(
+					ctx as QueueAwareContext,
+					`[${EXTENSION_NAME}] Reached the consecutive auto-retry limit (${config.maxConsecutiveAutoRetries}). Skipping automatic \"${config.retryMessage}\".`,
+					"warning",
+				);
+			}
+			return;
+		}
+
+		const errorText = [event.message.errorMessage, extractTextBlocks(event.message.content)]
+			.filter((value): value is string => typeof value === "string" && value.trim().length > 0)
+			.join("\n");
+		if (!errorText || !matchesConfiguredError(errorText, config.errorPatterns)) return;
+
+		consecutiveAutoRetries += 1;
+		pendingAutoRetryMessage = config.retryMessage;
+		if (config.notifyOnAutoContinue) {
+			safeNotify(
+				ctx as QueueAwareContext,
+				`[${EXTENSION_NAME}] Matched a configured error. Sending \"${config.retryMessage}\" automatically (${consecutiveAutoRetries}/${config.maxConsecutiveAutoRetries}).`,
+				"info",
+			);
+		}
+
+		if (ctx.isIdle()) {
+			await pi.sendUserMessage(config.retryMessage);
+		} else {
+			await pi.sendUserMessage(config.retryMessage, { deliverAs: "followUp" });
+		}
+	});
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pi-hodor",
+  "version": "0.1.0",
+  "description": "A pi extension that automatically continues after transient stream and connection errors.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "extension",
+    "retry",
+    "error-recovery"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vurihuang/pi-hodor.git"
+  },
+  "homepage": "https://github.com/vurihuang/pi-hodor#readme",
+  "bugs": {
+    "url": "https://github.com/vurihuang/pi-hodor/issues"
+  },
+  "files": [
+    "index.ts",
+    "config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.2"
+  }
+}