pi-error-advisor 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# pi-error-advisor
+
+Makes provider errors visible to the LLM in [Pi](https://pi.dev) — without writing anything to the session.
+
+Pi's default behavior keeps errors UI-only: assistant error messages carry the error in the `errorMessage` field with empty content (which provider serializers drop entirely), and overflow recovery removes the error message from context before retrying. The model therefore never learns that a request failed, why compaction ran, or that retries were exhausted — it either regenerates blind or gets a dead session.
+
+## What It Does
+
+pi-error-advisor synthesizes a short, clearly-labeled note into the outgoing request context whenever the previous turn failed:
+
+1. **Retry exhaustion** — after Pi's automatic retries give up on a transient provider error (rate limit, overloaded, network), the model is told the failure was infrastructure: *retry the same approach, don't change plans*, and let the user know the provider was unavailable.
+
+2. **Non-retryable provider errors** — 400/401/422-class failures surface the error text so the model can inform the user (e.g. expired auth → suggest `/login`) or recognize that something in the conversation history is being rejected.
+
+3. **Overflow recovery** — when the conversation exceeds the context window and Pi compacts it, the model is told to keep responses concise. If compaction *didn't complete* (failure, auth problem, nothing to compact), the model is told to produce the shortest useful response and suggest `/compact` or a larger-context model.
+
+4. **Silence where it belongs** — user aborts (Ctrl+C during compaction or retry backoff), manual and threshold compaction, and anything after a successful assistant turn produce no notes at all.
+
+## Why Request-Time, Not Persisted
+
+A previous iteration of this idea injected persisted advisory messages into the session. Upstream feedback (rightly) flagged that as detrimental: transient infrastructure noise becomes permanent conversation history, flows into compaction summaries and forks, and steers the model with fabricated context.
+
+This extension takes the opposite approach — **everything happens in the `context` hook at request time**:
+
+- Sessions, exports, compaction summaries, forks, and resumes are byte-identical with or without the extension.
+- Notes are self-limiting: they stop as soon as a successful assistant turn lands.
+- Notes are appended at the end of the message list, keeping the prompt-cache prefix stable.
+- Uninstalling the extension leaves zero trace in any session.
+
+## Installation
+
+```
+# Via GitHub URL
+pi install https://github.com/yeshao/pi-error-advisor
+
+# Or run ad hoc
+pi --extension path/to/pi-error-advisor/src/index.ts
+```
+
+## How It Works
+
+### Trailing-error scan (retry exhaustion, non-retryable errors)
+
+On every request, the `context` hook scans backwards for the last assistant message with `stopReason: "error"` that has no completed assistant message after it. The error is classified with pi-ai's own `isContextOverflow` / `isRetryableAssistantError`, and one matching note is appended:
+
+```
+[error-advisor] The previous request failed with a transient provider error after
+automatic retries were exhausted: "overloaded_error". This was an infrastructure
+problem, not a problem with your approach — do not change your plan because of it. …
+```
+
+The scan stops at successful or aborted assistant messages and at compaction/branch summaries, so stale errors never resurface.
+
+### Overflow compaction tracking
+
+The overflow-recovery path removes the error message from context before retrying, so the scan can't see it. Instead the extension pairs `session_before_compact(reason: "overflow")` with `session_compact`:
+
+- Both fired → compaction succeeded → one-shot "conversation was compacted, keep responses concise" note on the retry request.
+- Only the first fired → by the time the next request is built, the compaction must have failed → one-shot "compaction did not complete" note plus a UI warning.
+- The event's abort signal clears the pending flag, so user-cancelled compactions stay silent.
+
+(`agent_end` can't be used for failure detection — it fires *before* post-run compaction.)
+
+## Project Structure
+
+```
+pi-error-advisor/
+├── package.json          # Pi extension manifest
+├── tsconfig.json
+├── vitest.config.ts
+├── README.md
+├── src/
+│   └── index.ts          # Extension entry
+├── tests/
+│   └── error-advisor.test.ts
+└── types/
+    └── pi-coding-agent.ts  # Type stubs for standalone typecheck/tests
+```
+
+## Development
+
+```
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Run tests
+npm test
+```
+
+Tests exercise the real pi-ai error classification (`@earendil-works/pi-ai` is a dev dependency); only `@earendil-works/pi-coding-agent` is stubbed.
+
+## Dependencies
+
+Runtime: pi-ai's `isContextOverflow` / `isRetryableAssistantError` (provided by Pi as a peer dependency). No other runtime dependencies.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "pi-error-advisor",
+  "version": "0.1.0",
+  "description": "Makes provider errors visible to the LLM in Pi — request-time advisory notes for retry exhaustion, non-retryable errors, and context-overflow compaction, persisting nothing to the session",
+  "type": "module",
+  "main": "./src/index.ts",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.80.6",
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,167 @@
+/**
+ * pi-error-advisor
+ *
+ * Makes provider errors visible to the LLM at request time — without writing
+ * anything to the session.
+ *
+ * Pi's default behavior keeps errors UI-only: assistant error messages carry
+ * the error in the `errorMessage` field with empty content (which provider
+ * serializers drop entirely), and overflow recovery removes the error message
+ * from context before retrying. The model therefore never learns that a
+ * request failed, why compaction ran, or that retries were exhausted.
+ *
+ * This extension synthesizes a short, clearly-labeled note into the outgoing
+ * request context whenever the previous turn failed:
+ *
+ * - Transient provider errors (rate limit / overloaded / network) after retry
+ *   exhaustion: tells the model the failure was infrastructure — retry the
+ *   same approach, don't change plans.
+ * - Non-retryable errors (400/401/422): surfaces the error text so the model
+ *   can inform the user (e.g. expired auth) or adjust (e.g. rejected content).
+ * - Overflow recovery: notes that the conversation was compacted (or that
+ *   compaction did not complete) so the model keeps responses concise.
+ *
+ * Nothing is persisted. The note is added in the `context` hook, which only
+ * affects the outgoing provider request: sessions, exports, compaction
+ * summaries, forks, and resumes are byte-identical with or without this
+ * extension. Notes are self-limiting — they stop as soon as a successful
+ * assistant turn lands.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { isContextOverflow, isRetryableAssistantError } from "@earendil-works/pi-ai/compat";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const NOTE_PREFIX = "[error-advisor]";
+const MAX_ERROR_TEXT = 300;
+const ADVISOR_CUSTOM_TYPE = "error-advisor";
+
+function makeNote(text: string): AgentMessage {
+	return {
+		role: "custom",
+		customType: ADVISOR_CUSTOM_TYPE,
+		content: [{ type: "text", text: `${NOTE_PREFIX} ${text}` }],
+		display: false,
+		timestamp: Date.now(),
+	};
+}
+
+function truncate(text: string): string {
+	return text.length > MAX_ERROR_TEXT ? `${text.slice(0, MAX_ERROR_TEXT)}…` : text;
+}
+
+/**
+ * Find the trailing assistant error message: the last assistant message with
+ * stopReason "error" that has no completed assistant message after it.
+ *
+ * Stops scanning at: a successful/aborted assistant message (advice would be
+ * stale or unwanted — user aborts are not the model's business), or a
+ * compaction/branch summary (errors before a summary are ancient history).
+ */
+function findTrailingError(messages: AgentMessage[]): AssistantMessage | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "compactionSummary" || msg.role === "branchSummary") {
+			return undefined;
+		}
+		if (msg.role !== "assistant") {
+			continue;
+		}
+		const assistant = msg as AssistantMessage;
+		return assistant.stopReason === "error" ? assistant : undefined;
+	}
+	return undefined;
+}
+
+function classifyError(msg: AssistantMessage): string {
+	const errorText = truncate(msg.errorMessage ?? "unknown error");
+	if (isContextOverflow(msg, 0)) {
+		return (
+			"The previous request exceeded the model's context window and could not be completed. " +
+			"Keep your responses concise. If this persists, suggest the user run /compact or switch to a larger-context model."
+		);
+	}
+	if (isRetryableAssistantError(msg)) {
+		return (
+			`The previous request failed with a transient provider error after automatic retries were exhausted: "${errorText}". ` +
+			"This was an infrastructure problem, not a problem with your approach — do not change your plan because of it. " +
+			"Briefly let the user know the provider was unavailable and that retrying later should work."
+		);
+	}
+	return (
+		`The previous request failed with a non-retryable provider error: "${errorText}". ` +
+		"If it indicates an authentication problem, tell the user to check their credentials (e.g. /login). " +
+		"If it indicates a malformed request, part of the conversation history may contain content the provider rejects."
+	);
+}
+
+export default function errorAdvisor(pi: ExtensionAPI) {
+	// One-shot flags set by compaction events, consumed by the next context
+	// transform. These cover the overflow-recovery path, where the error
+	// message is removed from context before the retry — a stateless scan of
+	// the context can't see it, but the compaction events can.
+	//
+	// Failure inference: session_compact fires only on success, and there is
+	// no failure event. Event order matters — agent_end fires BEFORE the
+	// post-run compaction, so it cannot be used to detect failure. Instead:
+	// by the time the next `context` transform runs, an overflow compaction
+	// has either succeeded (session_compact cleared the pending flag before
+	// the retry request) or failed (the run died and this request belongs to
+	// the next prompt). A user abort clears the flag via the event's signal,
+	// so cancellations stay silent (user aborts are not the model's business).
+	let overflowCompacted = false;
+	let overflowCompactionPending = false;
+
+	pi.on("session_before_compact", async (event) => {
+		if (event.reason === "overflow") {
+			overflowCompactionPending = true;
+			event.signal.addEventListener("abort", () => {
+				overflowCompactionPending = false;
+			});
+		}
+		return undefined;
+	});
+
+	pi.on("session_compact", async (event) => {
+		if (event.reason === "overflow") {
+			overflowCompactionPending = false;
+			overflowCompacted = true;
+		}
+	});
+
+	pi.on("context", async (event, ctx) => {
+		const notes: string[] = [];
+
+		if (overflowCompacted) {
+			overflowCompacted = false;
+			notes.push(
+				"The conversation exceeded the model's context window and was automatically compacted. " +
+					"Keep your responses concise to avoid another overflow.",
+			);
+		}
+		if (overflowCompactionPending) {
+			overflowCompactionPending = false;
+			ctx.ui.notify("Overflow compaction did not complete; the request may fail again", "warning");
+			notes.push(
+				"The conversation exceeded the model's context window and automatic compaction did not complete. " +
+					"Produce the shortest useful response, and suggest the user run /compact or switch to a larger-context model.",
+			);
+		}
+
+		// Trailing provider error scan. Covers non-retryable errors (400/401)
+		// and retry exhaustion (the final failed attempt stays in context).
+		// Self-limiting: once a successful assistant message lands, the scan
+		// stops matching, so a note is only added while the failure is fresh.
+		const trailingError = findTrailingError(event.messages);
+		if (trailingError) {
+			notes.push(classifyError(trailingError));
+		}
+
+		if (notes.length === 0) {
+			return undefined;
+		}
+		// Append at the end: keeps the message prefix stable for prompt caching.
+		return { messages: [...event.messages, ...notes.map(makeNote)] };
+	});
+}

package/sso_html.txt

@@ -0,0 +1,16 @@
+{
+  "html": "",
+  "lifecycle": {
+    "effectiveLaunch": {
+      "browserLaunched": true,
+      "engine": "chrome",
+      "launchHash": 6847324482101410000
+    },
+    "launched": false,
+    "relaunchedBrowser": false,
+    "restartedBackground": false,
+    "restoreStatus": "not_configured",
+    "reused": true,
+    "saveStatus": "not_attempted"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@earendil-works/pi-coding-agent": ["./types/pi-coding-agent"]
+    }
+  },
+  "include": ["src", "types", "tests"]
+}

package/types/pi-coding-agent.ts

@@ -0,0 +1,104 @@
+// Minimal type stubs for @earendil-works/pi-coding-agent used by pi-error-advisor.
+// Only the members actually referenced are declared. At runtime under Pi, the
+// real package provides these; the stub exists so `tsc --noEmit` and vitest can
+// run standalone without the full coding-agent as a dev dependency.
+
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+
+/** Mirrors coding-agent's BashExecutionMessage. */
+export interface BashExecutionMessage {
+	role: "bashExecution";
+	command: string;
+	output: string;
+	exitCode: number | undefined;
+	cancelled: boolean;
+	truncated: boolean;
+	fullOutputPath?: string;
+	timestamp: number;
+	excludeFromContext?: boolean;
+}
+
+/** Mirrors coding-agent's CustomMessage. */
+export interface CustomMessage<T = unknown> {
+	role: "custom";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	display: boolean;
+	details?: T;
+	timestamp: number;
+}
+
+/** Mirrors coding-agent's BranchSummaryMessage. */
+export interface BranchSummaryMessage {
+	role: "branchSummary";
+	summary: string;
+	fromId: string;
+	timestamp: number;
+}
+
+/** Mirrors coding-agent's CompactionSummaryMessage. */
+export interface CompactionSummaryMessage {
+	role: "compactionSummary";
+	summary: string;
+	tokensBefore: number;
+	timestamp: number;
+}
+
+// Replicate coding-agent's declaration merging so AgentMessage includes the
+// custom roles — identical to what the real package declares.
+declare module "@earendil-works/pi-agent-core" {
+	interface CustomAgentMessages {
+		bashExecution: BashExecutionMessage;
+		custom: CustomMessage;
+		branchSummary: BranchSummaryMessage;
+		compactionSummary: CompactionSummaryMessage;
+	}
+}
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+export interface ContextEvent {
+	type: "context";
+	messages: AgentMessage[];
+}
+
+export interface ContextEventResult {
+	messages?: AgentMessage[];
+}
+
+export interface SessionBeforeCompactEvent {
+	type: "session_before_compact";
+	reason: "manual" | "threshold" | "overflow";
+	willRetry: boolean;
+	signal: AbortSignal;
+}
+
+export interface SessionCompactEvent {
+	type: "session_compact";
+	reason: "manual" | "threshold" | "overflow";
+	willRetry: boolean;
+}
+
+export interface ExtensionUIContext {
+	notify(message: string, level?: "info" | "warning" | "error"): void;
+}
+
+export interface ExtensionContext {
+	ui: ExtensionUIContext;
+	cwd: string;
+}
+
+export interface ExtensionAPI {
+	on(
+		event: "context",
+		handler: (event: ContextEvent, ctx: ExtensionContext) => Promise<ContextEventResult | undefined>,
+	): void;
+	on(
+		event: "session_before_compact",
+		handler: (event: SessionBeforeCompactEvent, ctx: ExtensionContext) => Promise<unknown>,
+	): void;
+	on(
+		event: "session_compact",
+		handler: (event: SessionCompactEvent, ctx: ExtensionContext) => Promise<unknown>,
+	): void;
+}

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	resolve: {
+		alias: {
+			"@earendil-works/pi-coding-agent": resolve(__dirname, "types/pi-coding-agent.ts"),
+		},
+	},
+	test: {
+		globals: true,
+	},
+});