gsd-pi 2.43.0-next.8 → 2.44.0-dev.0b97ffd

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: {
@@ -683,6 +700,12 @@ function createExtension(extensionPath: string, resolvedPath: string): Extension
 		commands: new Map(),
 		flags: new Map(),
 		shortcuts: new Map(),
+		lifecycleHooks: {
+			beforeInstall: [],
+			afterInstall: [],
+			beforeRemove: [],
+			afterRemove: [],
+		},
 	};
 }
 

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,

package/packages/pi-coding-agent/src/core/fs-utils.test.ts

@@ -1,66 +1,54 @@
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it, afterEach } from "node:test";
 import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { atomicWriteFileSync } from "./fs-utils.js";
 
 describe("atomicWriteFileSync", () => {
-	it("writes file content atomically", () => {
-		const dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
-		try {
-			const filePath = join(dir, "test.txt");
-			atomicWriteFileSync(filePath, "hello world");
-			assert.equal(readFileSync(filePath, "utf-8"), "hello world");
-		} finally {
+	let dir: string;
+
+	afterEach(() => {
+		if (dir) {
 			rmSync(dir, { recursive: true, force: true });
 		}
 	});
 
+	it("writes file content atomically", () => {
+		dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
+		const filePath = join(dir, "test.txt");
+		atomicWriteFileSync(filePath, "hello world");
+		assert.equal(readFileSync(filePath, "utf-8"), "hello world");
+	});
+
 	it("overwrites existing file atomically", () => {
-		const dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
-		try {
-			const filePath = join(dir, "test.txt");
-			atomicWriteFileSync(filePath, "first");
-			atomicWriteFileSync(filePath, "second");
-			assert.equal(readFileSync(filePath, "utf-8"), "second");
-		} finally {
-			rmSync(dir, { recursive: true, force: true });
-		}
+		dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
+		const filePath = join(dir, "test.txt");
+		atomicWriteFileSync(filePath, "first");
+		atomicWriteFileSync(filePath, "second");
+		assert.equal(readFileSync(filePath, "utf-8"), "second");
 	});
 
 	it("does not leave .tmp file after successful write", () => {
-		const dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
-		try {
-			const filePath = join(dir, "test.txt");
-			atomicWriteFileSync(filePath, "content");
-			assert.equal(existsSync(filePath + ".tmp"), false);
-		} finally {
-			rmSync(dir, { recursive: true, force: true });
-		}
+		dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
+		const filePath = join(dir, "test.txt");
+		atomicWriteFileSync(filePath, "content");
+		assert.equal(existsSync(filePath + ".tmp"), false);
 	});
 
 	it("supports Buffer content", () => {
-		const dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
-		try {
-			const filePath = join(dir, "test.bin");
-			const buf = Buffer.from([0x00, 0x01, 0x02, 0xff]);
-			atomicWriteFileSync(filePath, buf);
-			const result = readFileSync(filePath);
-			assert.deepEqual(result, buf);
-		} finally {
-			rmSync(dir, { recursive: true, force: true });
-		}
+		dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
+		const filePath = join(dir, "test.bin");
+		const buf = Buffer.from([0x00, 0x01, 0x02, 0xff]);
+		atomicWriteFileSync(filePath, buf);
+		const result = readFileSync(filePath);
+		assert.deepEqual(result, buf);
 	});
 
 	it("supports encoding parameter", () => {
-		const dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
-		try {
-			const filePath = join(dir, "test.txt");
-			atomicWriteFileSync(filePath, "utf8 content", "utf-8");
-			assert.equal(readFileSync(filePath, "utf-8"), "utf8 content");
-		} finally {
-			rmSync(dir, { recursive: true, force: true });
-		}
+		dir = mkdtempSync(join(tmpdir(), "fs-utils-test-"));
+		const filePath = join(dir, "test.txt");
+		atomicWriteFileSync(filePath, "utf8 content", "utf-8");
+		assert.equal(readFileSync(filePath, "utf-8"), "utf8 content");
 	});
 });

package/packages/pi-coding-agent/src/core/lifecycle-hooks.ts

@@ -0,0 +1,274 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseGitUrl } from "../utils/git.js";
+import {
+	importExtensionModule,
+	loadExtensions,
+	type LifecycleHookContext,
+	type LifecycleHookMap,
+	type LifecycleHookHandler,
+	type LifecycleHookPhase,
+	type LifecycleHookScope,
+} from "./extensions/index.js";
+import type { DefaultPackageManager } from "./package-manager.js";
+
+interface ExtensionManifest {
+	dependencies?: {
+		runtime?: string[];
+	};
+}
+
+export interface PackageLifecycleHooksOptions {
+	source: string;
+	local: boolean;
+	cwd: string;
+	agentDir: string;
+	appName: string;
+	packageManager: DefaultPackageManager;
+	stdout: NodeJS.WriteStream;
+	stderr: NodeJS.WriteStream;
+}
+
+export type LifecycleHooksTarget = "source" | "installed";
+
+export interface PrepareLifecycleHooksOptions {
+	verifyRuntimeDependencies?: boolean;
+}
+
+export interface LifecycleHooksRunResult {
+	phase: LifecycleHookPhase;
+	hooksRun: number;
+	hookErrors: number;
+	legacyHooksRun: number;
+	entryPathCount: number;
+	skipped: boolean;
+}
+
+interface LoadedLifecycleHooks {
+	source: string;
+	scope: LifecycleHookScope;
+	installedPath?: string;
+	cwd: string;
+	stdout: NodeJS.WriteStream;
+	stderr: NodeJS.WriteStream;
+	entryPaths: string[];
+	hooksByPath: Map<string, LifecycleHookMap>;
+}
+
+function toScope(local: boolean): LifecycleHookScope {
+	return local ? "project" : "user";
+}
+
+function readManifestRuntimeDeps(dir: string): string[] {
+	const manifestPath = join(dir, "extension-manifest.json");
+	if (!existsSync(manifestPath)) return [];
+	try {
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf-8")) as ExtensionManifest;
+		return manifest.dependencies?.runtime?.filter((dep): dep is string => typeof dep === "string") ?? [];
+	} catch {
+		return [];
+	}
+}
+
+function collectRuntimeDependencies(installedPath: string, entryPaths: string[]): string[] {
+	const deps = new Set<string>();
+	const candidateDirs = new Set<string>([installedPath, ...entryPaths.map((entryPath) => dirname(entryPath))]);
+	for (const dir of candidateDirs) {
+		for (const dep of readManifestRuntimeDeps(dir)) {
+			deps.add(dep);
+		}
+	}
+	return Array.from(deps);
+}
+
+function verifyRuntimeDependencies(runtimeDeps: string[], source: string, appName: string): void {
+	const missing: string[] = [];
+	for (const dep of runtimeDeps) {
+		const result = spawnSync(dep, ["--version"], { encoding: "utf-8", timeout: 5000 });
+		if (result.error || result.status !== 0) {
+			missing.push(dep);
+		}
+	}
+	if (missing.length === 0) return;
+	throw new Error(
+		`Missing runtime dependencies: ${missing.join(", ")}.\n` +
+			`Install them and retry: ${appName} install ${source}`,
+	);
+}
+
+function resolveLocalSourcePath(source: string, cwd: string): string | undefined {
+	const trimmed = source.trim();
+	if (!trimmed) return undefined;
+	if (trimmed.startsWith("npm:")) return undefined;
+	if (parseGitUrl(trimmed)) return undefined;
+
+	let normalized = trimmed;
+	if (normalized === "~") {
+		normalized = homedir();
+	} else if (normalized.startsWith("~/")) {
+		normalized = join(homedir(), normalized.slice(2));
+	}
+
+	const absolutePath = resolve(cwd, normalized);
+	return existsSync(absolutePath) ? absolutePath : undefined;
+}
+
+async function resolveEntryPathsFromTarget(
+	options: PackageLifecycleHooksOptions,
+	target: LifecycleHooksTarget,
+	scope: LifecycleHookScope,
+): Promise<{ entryPaths: string[]; installedPath?: string }> {
+	if (target === "source") {
+		const localSourcePath = resolveLocalSourcePath(options.source, options.cwd);
+		if (!localSourcePath) return { entryPaths: [] };
+		const resolved = await options.packageManager.resolveExtensionSources([localSourcePath], { local: true });
+		const entryPaths = resolved.extensions.filter((resource) => resource.enabled).map((resource) => resource.path);
+		return { entryPaths, installedPath: localSourcePath };
+	}
+
+	const installedPath = options.packageManager.getInstalledPath(options.source, scope);
+	if (!installedPath) return { entryPaths: [] };
+	const resolved = await options.packageManager.resolveExtensionSources([installedPath], { local: true });
+	const entryPaths = resolved.extensions.filter((resource) => resource.enabled).map((resource) => resource.path);
+	return { entryPaths, installedPath };
+}
+
+export async function prepareLifecycleHooks(
+	options: PackageLifecycleHooksOptions,
+	target: LifecycleHooksTarget,
+	prepareOptions?: PrepareLifecycleHooksOptions,
+): Promise<LoadedLifecycleHooks | null> {
+	const scope = toScope(options.local);
+	const { entryPaths, installedPath } = await resolveEntryPathsFromTarget(options, target, scope);
+	if (entryPaths.length === 0) {
+		return null;
+	}
+
+	if (prepareOptions?.verifyRuntimeDependencies && installedPath) {
+		const runtimeDeps = collectRuntimeDependencies(installedPath, entryPaths);
+		verifyRuntimeDependencies(runtimeDeps, options.source, options.appName);
+	}
+
+	const loaded = await loadExtensions(entryPaths, options.cwd);
+	for (const { path, error } of loaded.errors) {
+		options.stderr.write(`[lifecycle-hooks] Failed to load extension "${path}": ${error}\n`);
+	}
+
+	const hooksByPath = new Map<string, LifecycleHookMap>();
+	for (const extension of loaded.extensions) {
+		hooksByPath.set(extension.path, extension.lifecycleHooks);
+	}
+
+	return {
+		source: options.source,
+		scope,
+		installedPath,
+		cwd: options.cwd,
+		stdout: options.stdout,
+		stderr: options.stderr,
+		entryPaths,
+		hooksByPath,
+	};
+}
+
+async function runHookSafe(
+	hook: LifecycleHookHandler,
+	context: LifecycleHookContext,
+	stderr: NodeJS.WriteStream,
+): Promise<boolean> {
+	try {
+		await hook(context);
+		return true;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		stderr.write(`[lifecycle-hooks:${context.phase}] Hook failed: ${message}\n`);
+		return false;
+	}
+}
+
+function getLegacyExportCandidates(phase: LifecycleHookPhase): string[] {
+	return [phase];
+}
+
+async function runLegacyExportHook(
+	entryPath: string,
+	phase: LifecycleHookPhase,
+	context: LifecycleHookContext,
+): Promise<LifecycleHookHandler | null> {
+	try {
+		const module = await importExtensionModule<Record<string, unknown>>(import.meta.url, pathToFileURL(entryPath).href);
+		for (const exportName of getLegacyExportCandidates(phase)) {
+			const candidate = module[exportName];
+			if (typeof candidate === "function") {
+				return candidate as LifecycleHookHandler;
+			}
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+export async function runLifecycleHooks(
+	loaded: LoadedLifecycleHooks | null,
+	phase: LifecycleHookPhase,
+): Promise<LifecycleHooksRunResult> {
+	if (!loaded) {
+		return {
+			phase,
+			hooksRun: 0,
+			hookErrors: 0,
+			legacyHooksRun: 0,
+			entryPathCount: 0,
+			skipped: true,
+		};
+	}
+
+	const context: LifecycleHookContext = {
+		phase,
+		source: loaded.source,
+		installedPath: loaded.installedPath,
+		scope: loaded.scope,
+		cwd: loaded.cwd,
+		interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+		log: (message) => loaded.stdout.write(`${message}\n`),
+		warn: (message) => loaded.stderr.write(`${message}\n`),
+		error: (message) => loaded.stderr.write(`${message}\n`),
+	};
+
+	let hooksRun = 0;
+	let hookErrors = 0;
+	let legacyHooksRun = 0;
+
+	for (const entryPath of loaded.entryPaths) {
+		const hookMap = loaded.hooksByPath.get(entryPath);
+		const registeredHooks = hookMap?.[phase] ?? [];
+		if (registeredHooks.length > 0) {
+			for (const hook of registeredHooks) {
+				hooksRun += 1;
+				const ok = await runHookSafe(hook, context, loaded.stderr);
+				if (!ok) hookErrors += 1;
+			}
+			continue;
+		}
+
+		const legacyHook = await runLegacyExportHook(entryPath, phase, context);
+		if (!legacyHook) continue;
+
+		legacyHooksRun += 1;
+		const ok = await runHookSafe(legacyHook, context, loaded.stderr);
+		if (!ok) hookErrors += 1;
+	}
+
+	return {
+		phase,
+		hooksRun,
+		hookErrors,
+		legacyHooksRun,
+		entryPathCount: loaded.entryPaths.length,
+		skipped: false,
+	};
+}