gsd-pi 2.43.0 → 2.44.0-dev.0b97ffd

package/packages/pi-coding-agent/src/core/agent-session.ts

@@ -255,6 +255,10 @@ export class AgentSession {
 	private _cumulativeOutputTokens = 0;
 	private _cumulativeToolCalls = 0;
 
+	/** Cost of the most recent assistant response (for per-prompt display). */
+	private _lastTurnCost = 0;
+
+
 	// Bash execution state
 	private _bashAbortController: AbortController | undefined = undefined;
 	private _pendingBashMessages: BashExecutionMessage[] = [];
@@ -454,6 +458,7 @@ export class AgentSession {
 
 				// Accumulate session stats that survive compaction (#1423)
 				const assistantMsg = event.message as AssistantMessage;
+				this._lastTurnCost = assistantMsg.usage?.cost?.total ?? 0;
 				this._cumulativeCost += assistantMsg.usage?.cost?.total ?? 0;
 				this._cumulativeInputTokens += assistantMsg.usage?.input ?? 0;
 				this._cumulativeOutputTokens += assistantMsg.usage?.output ?? 0;
@@ -1049,9 +1054,8 @@ export class AgentSession {
 			});
 		}
 
-		// Validate API key
-		const apiKey = await this._modelRegistry.getApiKey(this.model, this.sessionId);
-		if (!apiKey) {
+		// Validate provider readiness
+		if (!this._modelRegistry.isProviderRequestReady(this.model.provider)) {
 			const isOAuth = this._modelRegistry.isUsingOAuth(this.model);
 			if (isOAuth) {
 				throw new Error(
@@ -1609,12 +1613,11 @@ export class AgentSession {
 
 	/**
 	 * Set model directly.
-	 * Validates API key, saves to session and settings.
-	 * @throws Error if no API key available for the model
+	 * Validates provider readiness, saves to session and settings.
+	 * @throws Error if provider is not ready (missing credentials for apiKey/oauth providers)
 	 */
 	async setModel(model: Model<any>, options?: { persist?: boolean }): Promise<void> {
-		const apiKey = await this._modelRegistry.getApiKey(model, this.sessionId);
-		if (!apiKey) {
+		if (!this._modelRegistry.isProviderRequestReady(model.provider)) {
 			throw new Error(`No API key for ${model.provider}/${model.id}`);
 		}
 
@@ -1635,30 +1638,14 @@ export class AgentSession {
 		return this._cycleAvailableModel(direction, options);
 	}
 
-	private async _getScopedModelsWithApiKey(): Promise<Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }>> {
-		const apiKeysByProvider = new Map<string, string | undefined>();
-		const result: Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }> = [];
-
-		for (const scoped of this._scopedModels) {
-			const provider = scoped.model.provider;
-			let apiKey: string | undefined;
-			if (apiKeysByProvider.has(provider)) {
-				apiKey = apiKeysByProvider.get(provider);
-			} else {
-				apiKey = await this._modelRegistry.getApiKeyForProvider(provider, this.sessionId);
-				apiKeysByProvider.set(provider, apiKey);
-			}
-
-			if (apiKey) {
-				result.push(scoped);
-			}
-		}
-
-		return result;
+	private _getReadyScopedModels(): Array<{ model: Model<any>; thinkingLevel?: ThinkingLevel }> {
+		return this._scopedModels.filter((scoped) =>
+			this._modelRegistry.isProviderRequestReady(scoped.model.provider),
+		);
 	}
 
 	private async _cycleScopedModel(direction: "forward" | "backward", options?: { persist?: boolean }): Promise<ModelCycleResult | undefined> {
-		const scopedModels = await this._getScopedModelsWithApiKey();
+		const scopedModels = this._getReadyScopedModels();
 		if (scopedModels.length <= 1) return undefined;
 
 		const currentModel = this.model;
@@ -1689,11 +1676,6 @@ export class AgentSession {
 		const nextIndex = direction === "forward" ? (currentIndex + 1) % len : (currentIndex - 1 + len) % len;
 		const nextModel = availableModels[nextIndex];
 
-		const apiKey = await this._modelRegistry.getApiKey(nextModel, this.sessionId);
-		if (!apiKey) {
-			throw new Error(`No API key for ${nextModel.provider}/${nextModel.id}`);
-		}
-
 		const thinkingLevel = this._getThinkingLevelForModelSwitch();
 		await this._applyModelChange(nextModel, thinkingLevel, "cycle", options);
 
@@ -2032,8 +2014,7 @@ export class AgentSession {
 				refreshTools: () => this._refreshToolRegistry(),
 				getCommands,
 				setModel: async (model, options) => {
-					const key = await this.modelRegistry.getApiKey(model, this.sessionId);
-					if (!key) return false;
+					if (!this.modelRegistry.isProviderRequestReady(model.provider)) return false;
 					await this.setModel(model, options);
 					return true;
 				},
@@ -2603,10 +2584,10 @@ export class AgentSession {
 		let summaryDetails: unknown;
 		if (options.summarize && entriesToSummarize.length > 0 && !extensionSummary) {
 			const model = this.model!;
-			const apiKey = await this._modelRegistry.getApiKey(model, this.sessionId);
-			if (!apiKey) {
+			if (!this._modelRegistry.isProviderRequestReady(model.provider)) {
 				throw new Error(`No API key for ${model.provider}`);
 			}
+			const apiKey = await this._modelRegistry.getApiKey(model, this.sessionId);
 			const branchSummarySettings = this.settingsManager.getBranchSummarySettings();
 			const result = await generateBranchSummary(entriesToSummarize, {
 				model,
@@ -2780,6 +2761,14 @@ export class AgentSession {
 		};
 	}
 
+	/**
+	 * Get the cost of the most recent assistant response.
+	 * Returns 0 if no assistant message has been received yet.
+	 */
+	getLastTurnCost(): number {
+		return this._lastTurnCost;
+	}
+
 	getContextUsage(): ContextUsage | undefined {
 		const model = this.model;
 		if (!model) return undefined;

package/packages/pi-coding-agent/src/core/auth-storage.test.ts

@@ -287,7 +287,7 @@ describe("AuthStorage — oauth credential for non-OAuth provider (#2083)", () =
 		assert.equal(key, undefined);
 	});
 
-	it("falls through to env var when openrouter has type:oauth credential", async () => {
+	it("falls through to env var when openrouter has type:oauth credential", async (t) => {
 		const storage = inMemory({
 			openrouter: {
 				type: "oauth",
@@ -299,17 +299,17 @@ describe("AuthStorage — oauth credential for non-OAuth provider (#2083)", () =
 
 		// Simulate OPENROUTER_API_KEY being set via env
 		const origEnv = process.env.OPENROUTER_API_KEY;
-		try {
-			process.env.OPENROUTER_API_KEY = "sk-or-v1-env-key";
-			const key = await storage.getApiKey("openrouter");
-			assert.equal(key, "sk-or-v1-env-key");
-		} finally {
+		t.after(() => {
 			if (origEnv === undefined) {
 				delete process.env.OPENROUTER_API_KEY;
 			} else {
 				process.env.OPENROUTER_API_KEY = origEnv;
 			}
-		}
+		});
+
+		process.env.OPENROUTER_API_KEY = "sk-or-v1-env-key";
+		const key = await storage.getApiKey("openrouter");
+		assert.equal(key, "sk-or-v1-env-key");
 	});
 
 	it("falls through to fallback resolver when openrouter has type:oauth credential", async () => {

package/packages/pi-coding-agent/src/core/compaction/branch-summarization.ts

@@ -64,8 +64,8 @@ export interface CollectEntriesResult {
 export interface GenerateBranchSummaryOptions {
 	/** Model to use for summarization */
 	model: Model<any>;
-	/** API key for the model */
-	apiKey: string;
+	/** API key for the model. Undefined for externalCli/none providers. */
+	apiKey: string | undefined;
 	/** Abort signal for cancellation */
 	signal: AbortSignal;
 	/** Optional custom instructions for summarization */

package/packages/pi-coding-agent/src/core/compaction/compaction.ts

@@ -497,7 +497,7 @@ export async function generateSummary(
 	currentMessages: AgentMessage[],
 	model: Model<any>,
 	reserveTokens: number,
-	apiKey: string,
+	apiKey: string | undefined,
 	signal?: AbortSignal,
 	customInstructions?: string,
 	previousSummary?: string,
@@ -660,7 +660,7 @@ Be concise. Focus on what's needed to understand the kept suffix.`;
 export async function compact(
 	preparation: CompactionPreparation,
 	model: Model<any>,
-	apiKey: string,
+	apiKey: string | undefined,
 	customInstructions?: string,
 	signal?: AbortSignal,
 ): Promise<CompactionResult> {
@@ -732,7 +732,7 @@ async function generateTurnPrefixSummary(
 	messages: AgentMessage[],
 	model: Model<any>,
 	reserveTokens: number,
-	apiKey: string,
+	apiKey: string | undefined,
 	signal?: AbortSignal,
 ): Promise<string> {
 	const maxTokens = Math.floor(0.5 * reserveTokens); // Smaller budget for turn prefix

package/packages/pi-coding-agent/src/core/compaction-orchestrator.ts

@@ -94,10 +94,10 @@ export class CompactionOrchestrator {
 				throw new Error("No model selected");
 			}
 
-			const apiKey = await this._deps.modelRegistry.getApiKey(model, this._deps.getSessionId());
-			if (!apiKey) {
+			if (!this._deps.modelRegistry.isProviderRequestReady(model.provider)) {
 				throw new Error(`No API key for ${model.provider}`);
 			}
+			const apiKey = await this._deps.modelRegistry.getApiKey(model, this._deps.getSessionId());
 
 			const pathEntries = this._deps.sessionManager.getBranch();
 			const settings = this._deps.settingsManager.getCompactionSettings();
@@ -299,11 +299,11 @@ export class CompactionOrchestrator {
 				return;
 			}
 
-			const apiKey = await this._deps.modelRegistry.getApiKey(model, this._deps.getSessionId());
-			if (!apiKey) {
+			if (!this._deps.modelRegistry.isProviderRequestReady(model.provider)) {
 				this._deps.emit({ type: "auto_compaction_end", result: undefined, aborted: false, willRetry: false });
 				return;
 			}
+			const apiKey = await this._deps.modelRegistry.getApiKey(model, this._deps.getSessionId());
 
 			const pathEntries = this._deps.sessionManager.getBranch();
 			const preparation = prepareCompaction(pathEntries, settings);

package/packages/pi-coding-agent/src/core/extensions/index.ts

@@ -94,6 +94,11 @@ export type {
 	// Provider Registration
 	ProviderConfig,
 	ProviderModelConfig,
+	LifecycleHookContext,
+	LifecycleHookHandler,
+	LifecycleHookMap,
+	LifecycleHookPhase,
+	LifecycleHookScope,
 	ReadToolCallEvent,
 	ReadToolResultEvent,
 	// Commands

package/packages/pi-coding-agent/src/core/extensions/loader.test.ts

@@ -4,6 +4,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { isProjectTrusted, trustProject, getUntrustedExtensionPaths } from "./project-trust.js";
+import { containsTypeScriptSyntax, loadExtensions } from "./loader.js";
 
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
@@ -139,3 +140,98 @@ describe("getUntrustedExtensionPaths", () => {
 		assert.deepEqual(result, paths);
 	});
 });
+
+// ─── containsTypeScriptSyntax ─────────────────────────────────────────────────
+
+describe("containsTypeScriptSyntax", () => {
+	it("detects parameter type annotations", () => {
+		assert.ok(containsTypeScriptSyntax(`export default function activate(api: ExtensionAPI) {}`));
+	});
+
+	it("detects interface declarations", () => {
+		assert.ok(containsTypeScriptSyntax(`interface Config { name: string; }`));
+	});
+
+	it("detects type alias declarations", () => {
+		assert.ok(containsTypeScriptSyntax(`type Handler = (event: string) => void;`));
+	});
+
+	it("detects enum declarations", () => {
+		assert.ok(containsTypeScriptSyntax(`enum Direction { Up, Down, Left, Right }`));
+	});
+
+	it("detects return type annotations", () => {
+		assert.ok(containsTypeScriptSyntax(`function foo(): Promise<void> {}`));
+	});
+
+	it("detects generic type parameters on functions", () => {
+		assert.ok(containsTypeScriptSyntax(`function identity<T>(arg) { return arg; }`));
+	});
+
+	it("detects variable type annotations", () => {
+		assert.ok(containsTypeScriptSyntax(`const name: string = "hello";`));
+	});
+
+	it("returns false for plain JavaScript", () => {
+		assert.equal(containsTypeScriptSyntax(`export default function activate(api) { api.on("init", () => {}); }`), false);
+	});
+
+	it("returns false for empty string", () => {
+		assert.equal(containsTypeScriptSyntax(""), false);
+	});
+
+	it("returns false for JSDoc comments with type-like syntax", () => {
+		// JSDoc uses different syntax: @param {string} name
+		assert.equal(containsTypeScriptSyntax(`/** @param {string} name */\nexport default function activate(api) {}`), false);
+	});
+});
+
+// ─── loadExtensions: TypeScript syntax in .js files ───────────────────────────
+
+describe("loadExtensions", () => {
+	let tmpDir: string;
+
+	beforeEach(() => {
+		tmpDir = makeTempDir();
+	});
+
+	afterEach(() => {
+		cleanDir(tmpDir);
+	});
+
+	it("reports helpful error when .js file contains TypeScript syntax", async () => {
+		// Create a .js file that uses TypeScript type annotations
+		const extPath = path.join(tmpDir, "my-extension.js");
+		fs.writeFileSync(
+			extPath,
+			`export default function activate(api: ExtensionAPI) {\n  api.on("init", async () => {});\n}\n`,
+		);
+
+		const result = await loadExtensions([extPath], tmpDir);
+
+		assert.equal(result.errors.length, 1);
+		const errorMsg = result.errors[0].error;
+		// The error should mention TypeScript syntax and suggest .ts extension
+		assert.ok(
+			/TypeScript/.test(errorMsg) && /\.ts\b/.test(errorMsg),
+			`Expected error to mention TypeScript syntax and .ts extension, got: ${errorMsg}`,
+		);
+	});
+
+	it("reports helpful error when .js file contains TS interface declaration", async () => {
+		const extPath = path.join(tmpDir, "typed-ext.js");
+		fs.writeFileSync(
+			extPath,
+			`interface Config { name: string; }\nexport default function activate(api) { return; }\n`,
+		);
+
+		const result = await loadExtensions([extPath], tmpDir);
+
+		assert.equal(result.errors.length, 1);
+		const errorMsg = result.errors[0].error;
+		assert.ok(
+			/TypeScript/.test(errorMsg) && /\.ts\b/.test(errorMsg),
+			`Expected error to mention TypeScript syntax and .ts extension, got: ${errorMsg}`,
+		);
+	});
+});

package/packages/pi-coding-agent/src/core/extensions/loader.ts

@@ -42,6 +42,7 @@ import type {
 	Extension,
 	ExtensionAPI,
 	ExtensionFactory,
+	LifecycleHookHandler,
 	ExtensionRuntime,
 	LoadExtensionsResult,
 	MessageRenderer,
@@ -463,6 +464,22 @@ function createExtensionAPI(
 			extension.commands.set(name, { name, ...options });
 		},
 
+		registerBeforeInstall(handler: LifecycleHookHandler): void {
+			extension.lifecycleHooks.beforeInstall.push(handler);
+		},
+
+		registerAfterInstall(handler: LifecycleHookHandler): void {
+			extension.lifecycleHooks.afterInstall.push(handler);
+		},
+
+		registerBeforeRemove(handler: LifecycleHookHandler): void {
+			extension.lifecycleHooks.beforeRemove.push(handler);
+		},
+
+		registerAfterRemove(handler: LifecycleHookHandler): void {
+			extension.lifecycleHooks.afterRemove.push(handler);
+		},
+
 		registerShortcut(
 			shortcut: KeyId,
 			options: {
@@ -568,6 +585,39 @@ function createExtensionAPI(
 	return api;
 }
 
+/**
+ * Heuristic patterns that indicate TypeScript syntax in a source file.
+ * Used to detect when a .js file accidentally contains TypeScript code
+ * and provide a helpful error message instead of a cryptic parse failure.
+ */
+const TS_SYNTAX_PATTERNS: RegExp[] = [
+	// Variable type annotations: const name: string, let count: number
+	/\b(?:const|let|var)\s+\w+\s*:\s*(?:string|number|boolean|any|void|never|unknown|object|bigint|symbol|undefined|null)\b/,
+	// Parameter type annotations: (api: ExtensionAPI)
+	/\(\s*\w+\s*:\s*[A-Z]\w*/,
+	// Return type annotations: ): Promise<void> {  or  ): string =>
+	/\)\s*:\s*(?:Promise|string|number|boolean|void|any|never|unknown)\b/,
+	// Interface declarations
+	/\binterface\s+[A-Z]\w*\s*(?:<[^>]*>)?\s*\{/,
+	// Type alias declarations
+	/\btype\s+[A-Z]\w*\s*(?:<[^>]*>)?\s*=/,
+	// Angle-bracket type assertions: <Type>value
+	/(?:as\s+\w+(?:<[^>]*>)?)\s*[;,)\]}]/,
+	// Generic type parameters on functions: function foo<T>
+	/\bfunction\s+\w+\s*<[^>]+>/,
+	// Enum declarations
+	/\benum\s+[A-Z]\w*\s*\{/,
+];
+
+/**
+ * Check whether a source string likely contains TypeScript syntax.
+ * This is a heuristic — it may produce false positives for unusual JS,
+ * but is tuned to catch the most common TS-in-JS mistakes.
+ */
+export function containsTypeScriptSyntax(source: string): boolean {
+	return TS_SYNTAX_PATTERNS.some((pattern) => pattern.test(source));
+}
+
 async function loadExtensionModule(extensionPath: string) {
 	// Pre-compiled extension loading: if the source is .ts and a sibling .js
 	// file exists with matching or newer mtime, use native import() to skip
@@ -650,6 +700,12 @@ function createExtension(extensionPath: string, resolvedPath: string): Extension
 		commands: new Map(),
 		flags: new Map(),
 		shortcuts: new Map(),
+		lifecycleHooks: {
+			beforeInstall: [],
+			afterInstall: [],
+			beforeRemove: [],
+			afterRemove: [],
+		},
 	};
 }
 
@@ -672,6 +728,22 @@ async function loadExtension(
 				return { extension: null, error: null };
 			}
 			logExtensionTiming(extensionPath, Date.now() - start, "failed");
+
+			// Check if a .js file contains TypeScript syntax
+			if (resolvedPath.endsWith(".js")) {
+				try {
+					const source = fs.readFileSync(resolvedPath, "utf-8");
+					if (containsTypeScriptSyntax(source)) {
+						return {
+							extension: null,
+							error: `Extension file "${extensionPath}" appears to contain TypeScript syntax but has a .js extension. Rename it to .ts so the loader can compile it.`,
+						};
+					}
+				} catch {
+					// Could not read file — fall through to generic error
+				}
+			}
+
 			return { extension: null, error: `Extension does not export a valid factory function: ${extensionPath}` };
 		}
 
@@ -684,6 +756,23 @@ async function loadExtension(
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
 		logExtensionTiming(extensionPath, Date.now() - start, "failed");
+
+		// Check if a .js file contains TypeScript syntax — the parse error from
+		// jiti/Node is often cryptic, so surface a clearer diagnostic.
+		if (resolvedPath.endsWith(".js")) {
+			try {
+				const source = fs.readFileSync(resolvedPath, "utf-8");
+				if (containsTypeScriptSyntax(source)) {
+					return {
+						extension: null,
+						error: `Extension file "${extensionPath}" appears to contain TypeScript syntax but has a .js extension. Rename it to .ts so the loader can compile it.`,
+					};
+				}
+			} catch {
+				// Could not read file — fall through to generic error
+			}
+		}
+
 		return { extension: null, error: `Failed to load extension: ${message}` };
 	}
 }

package/packages/pi-coding-agent/src/core/extensions/runner.test.ts

@@ -48,37 +48,37 @@ function makeThrowingExtension(eventType: string, error: Error): Extension {
 }
 
 describe("ExtensionRunner.emitToolCall", () => {
-	it("catches throwing extension handler and routes to emitError", async () => {
+	it("catches throwing extension handler and routes to emitError", async (t) => {
 		const dir = mkdtempSync(join(tmpdir(), "runner-test-"));
-		try {
-			const sessionManager = SessionManager.create(dir, dir);
-			const authStorage = AuthStorage.create();
-			const modelRegistry = new ModelRegistry(authStorage, join(dir, "models.json"));
+		t.after(() => {
+			rmSync(dir, { recursive: true, force: true });
+		});
 
-			const throwingExt = makeThrowingExtension("tool_call", new Error("handler crashed"));
-			const runtime = makeMinimalRuntime();
-			const runner = new ExtensionRunner([throwingExt], runtime, dir, sessionManager, modelRegistry);
+		const sessionManager = SessionManager.create(dir, dir);
+		const authStorage = AuthStorage.create();
+		const modelRegistry = new ModelRegistry(authStorage, join(dir, "models.json"));
 
-			const errors: any[] = [];
-			runner.onError((err) => errors.push(err));
+		const throwingExt = makeThrowingExtension("tool_call", new Error("handler crashed"));
+		const runtime = makeMinimalRuntime();
+		const runner = new ExtensionRunner([throwingExt], runtime, dir, sessionManager, modelRegistry);
 
-			const event: ToolCallEvent = {
-				type: "tool_call",
-				toolCallId: "test-123",
-				toolName: "test_tool",
-				input: {},
-			} as ToolCallEvent;
+		const errors: any[] = [];
+		runner.onError((err) => errors.push(err));
 
-			const result = await runner.emitToolCall(event);
+		const event: ToolCallEvent = {
+			type: "tool_call",
+			toolCallId: "test-123",
+			toolName: "test_tool",
+			input: {},
+		} as ToolCallEvent;
 
-			// Should not throw — error is caught and routed to emitError
-			assert.equal(result, undefined);
-			assert.equal(errors.length, 1);
-			assert.equal(errors[0].error, "handler crashed");
-			assert.equal(errors[0].event, "tool_call");
-			assert.equal(errors[0].extensionPath, "/test/throwing-ext");
-		} finally {
-			rmSync(dir, { recursive: true, force: true });
-		}
+		const result = await runner.emitToolCall(event);
+
+		// Should not throw — error is caught and routed to emitError
+		assert.equal(result, undefined);
+		assert.equal(errors.length, 1);
+		assert.equal(errors[0].error, "handler crashed");
+		assert.equal(errors[0].event, "tool_call");
+		assert.equal(errors[0].extensionPath, "/test/throwing-ext");
 	});
 });

package/packages/pi-coding-agent/src/core/extensions/types.ts

@@ -949,6 +949,33 @@ export interface RegisteredCommand {
 	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
 }
 
+export type LifecycleHookScope = "user" | "project";
+export type LifecycleHookPhase = "beforeInstall" | "afterInstall" | "beforeRemove" | "afterRemove";
+
+export interface LifecycleHookContext {
+	/** Lifecycle phase currently being executed. */
+	phase: LifecycleHookPhase;
+	/** Package source string passed to install (npm:, git:, https://, local path). */
+	source: string;
+	/** Resolved installed package path (or resolved local path), when available for this phase. */
+	installedPath?: string;
+	/** Where the package was installed. */
+	scope: LifecycleHookScope;
+	/** Current working directory for the install invocation. */
+	cwd: string;
+	/** Whether install is running in an interactive TTY. */
+	interactive: boolean;
+	/** Info-level logging sink for install output. */
+	log(message: string): void;
+	/** Warning-level logging sink for install output. */
+	warn(message: string): void;
+	/** Error-level logging sink for install output. */
+	error(message: string): void;
+}
+
+export type LifecycleHookHandler = (ctx: LifecycleHookContext) => Promise<void> | void;
+export type LifecycleHookMap = Record<LifecycleHookPhase, LifecycleHookHandler[]>;
+
 // ============================================================================
 // Extension API
 // ============================================================================
@@ -1019,6 +1046,18 @@ export interface ExtensionAPI {
 	/** Register a custom command. */
 	registerCommand(name: string, options: Omit<RegisteredCommand, "name">): void;
 
+	/** Register a lifecycle hook run before package installation starts. */
+	registerBeforeInstall(handler: LifecycleHookHandler): void;
+
+	/** Register a lifecycle hook run after package installation completes. */
+	registerAfterInstall(handler: LifecycleHookHandler): void;
+
+	/** Register a lifecycle hook run before package removal starts. */
+	registerBeforeRemove(handler: LifecycleHookHandler): void;
+
+	/** Register a lifecycle hook run after package removal completes. */
+	registerAfterRemove(handler: LifecycleHookHandler): void;
+
 	/** Register a keyboard shortcut. */
 	registerShortcut(
 		shortcut: KeyId,
@@ -1201,6 +1240,10 @@ export interface ExtensionAPI {
 
 /** Configuration for registering a provider via pi.registerProvider(). */
 export interface ProviderConfig {
+	/** Auth behavior for provider availability and request key handling. Defaults to "apiKey". */
+	authMode?: "apiKey" | "oauth" | "externalCli" | "none";
+	/** Optional readiness check. Return false if the provider cannot accept requests (e.g., CLI not authenticated, API key invalid). Called before default auth checks. */
+	isReady?: () => boolean;
 	/** Base URL for the API endpoint. Required when defining models. */
 	baseUrl?: string;
 	/** API key or environment variable name. Required when defining models (unless oauth provided). */
@@ -1382,6 +1425,7 @@ export interface Extension {
 	commands: Map<string, RegisteredCommand>;
 	flags: Map<string, ExtensionFlag>;
 	shortcuts: Map<KeyId, ExtensionShortcut>;
+	lifecycleHooks: LifecycleHookMap;
 }
 
 /** Result of loading extensions. */

package/packages/pi-coding-agent/src/core/fallback-resolver.test.ts

@@ -38,6 +38,7 @@ function createResolver(overrides?: {
 	enabled?: boolean;
 	isProviderAvailable?: (provider: string) => boolean;
 	hasAuth?: (provider: string) => boolean;
+	isProviderRequestReady?: (provider: string) => boolean;
 	find?: (provider: string, modelId: string) => Model<Api> | undefined;
 }) {
 	const settingsManager = {
@@ -60,6 +61,7 @@ function createResolver(overrides?: {
 			if (provider === "openai" && modelId === "gpt-4.1") return openaiModel;
 			return undefined;
 		}),
+		isProviderRequestReady: overrides?.isProviderRequestReady ?? overrides?.hasAuth ?? (() => true),
 	} as unknown as ModelRegistry;
 
 	return { resolver: new FallbackResolver(settingsManager, authStorage, modelRegistry), authStorage };
@@ -122,9 +124,9 @@ describe("FallbackResolver — findFallback", () => {
 		assert.equal(result, null);
 	});
 
-	it("skips providers without auth", async () => {
+	it("skips providers that are not request-ready", async () => {
 		const { resolver } = createResolver({
-			hasAuth: (provider: string) => provider !== "alibaba",
+			isProviderRequestReady: (provider: string) => provider !== "alibaba",
 		});
 
 		const result = await resolver.findFallback(zaiModel, "quota_exhausted");
@@ -133,6 +135,17 @@ describe("FallbackResolver — findFallback", () => {
 		assert.equal(result!.model.provider, "openai");
 	});
 
+	it("allows fallback to external-cli style providers without stored auth", async () => {
+		const { resolver } = createResolver({
+			hasAuth: () => false,
+			isProviderRequestReady: (provider: string) => provider === "alibaba",
+		});
+
+		const result = await resolver.findFallback(zaiModel, "quota_exhausted");
+		assert.notEqual(result, null);
+		assert.equal(result!.model.provider, "alibaba");
+	});
+
 	it("skips providers with no model in registry", async () => {
 		const { resolver } = createResolver({
 			find: (provider: string, modelId: string) => {

package/packages/pi-coding-agent/src/core/fallback-resolver.ts

@@ -149,9 +149,8 @@ export class FallbackResolver {
 			const model = this.modelRegistry.find(entry.provider, entry.model);
 			if (!model) continue;
 
-			// Check if API key is available
-			const hasAuth = this.authStorage.hasAuth(entry.provider);
-			if (!hasAuth) continue;
+			// Check if provider is request-ready for fallback (authMode-aware)
+			if (!this.modelRegistry.isProviderRequestReady(entry.provider)) continue;
 
 			return {
 				model,