Extensions, skills, templates, themes, packages

		promptSections.docs = `Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):- Main documentation: ${getReadmePath()}- Additional docs: ${getDocsPath()}- Examples: ${getExamplesPath()} (extensions, custom tools, SDK)- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md), MCP servers (docs/mcp.md), codemode scripts and non-LLM models such as classifiers and image models (docs/codemode.md)- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;

async resolve(onMissing?: (source: string) => Promise<MissingSourceAction>): Promise<ResolvedPaths> {	const accumulator = this.createAccumulator();	const globalSettings = this.settingsManager.getGlobalSettings();	const projectSettings = this.settingsManager.getProjectSettings();	// Collect all packages with scope (project first so cwd resources win collisions)	const allPackages: Array<{ pkg: PackageSource; scope: SourceScope }> = [];	for (const pkg of projectSettings.packages ?? []) {		allPackages.push({ pkg, scope: "project" });	}	for (const pkg of globalSettings.packages ?? []) {		allPackages.push({ pkg, scope: "user" });	}	// Dedupe: project scope wins over global for same package identity	const packageSources = this.dedupePackages(allPackages);	await this.resolvePackageSources(packageSources, accumulator, onMissing);⋯ lược bớt dòng 943–974	this.addAutoDiscoveredResources(accumulator, globalSettings, projectSettings, globalBaseDir, projectBaseDir);	// Built-in extensions are enabled unless the user `extensions` setting excludes them, for example	// with `-builtin:mcp`. A matching `+`, `-`, or `!` entry in the project setting overrides that.	for (const name of this.builtinExtensions) {		const path = `${BUILTIN_PATH_PREFIX}${name}`;		const projectEnabled = applyAutoloadDisabledPatterns(			[path],			getOverridePatterns(projectSettings.extensions ?? []),			projectBaseDir,		).get(path);		this.addResource(			accumulator.extensions,			path,			{ source: "builtin", scope: projectEnabled === undefined ? "user" : "project", origin: "top-level" },			projectEnabled ?? isEnabledByOverrides(path, globalSettings.extensions ?? [], globalBaseDir),		);	}	return this.toResolvedPaths(accumulator);}

/** * Compute a numeric precedence rank for a resource based on its metadata. * Lower rank = higher precedence. Used to sort resolved resources so that * name-collision resolution ("first wins") produces the correct outcome. * * Precedence (highest to lowest): *   0  project + settings entry (source: "local", scope: "project") *   1  project + auto-discovered (source: "auto", scope: "project") *   2  user + settings entry (source: "local", scope: "user") *   3  user + auto-discovered (source: "auto", scope: "user") *   4  package resource (origin: "package") */function resourcePrecedenceRank(m: PathMetadata): number {	// Built-in extensions load after file and package extensions, whichever scope enables them.	if (m.source === "builtin") return 5;	if (m.origin === "package") return 4;	const scopeBase = m.scope === "project" ? 0 : 2;	return scopeBase + (m.source === "local" ? 0 : 1);}

const isNodeSeaBinary =	("sea" in process.features && process.features.sea === true) ||	process.getBuiltinModule("node:sea")?.isSea() === true;const isTypeScriptSourceRuntime = !isBunBinary && path.extname(fileURLToPath(import.meta.url)) === ".ts";const usesEmbeddedModules = isBunBinary || isNodeSeaBinary || isBundledNode;⋯ lược bớt dòng 46–561async function loadExtensionModule(extensionPath: string, cacheToken?: ExtensionCacheToken) {	if (isCurrentCacheToken(cacheToken)) {		const cachedFactory = extensionCache.get(extensionPath);		if (cachedFactory) {			return cachedFactory;		}	}	const createJitiImpl = await getCreateJiti();	// Compiled binaries and the bundled Node distribution use embedded modules.	// Source TypeScript reuses host modules and root tsconfig paths. Unbundled	// Node builds use dist aliases and do not need the bundled virtual modules.	const resolutionOptions = usesEmbeddedModules		? { virtualModules: await getVirtualModules(), tryNative: false }		: isTypeScriptSourceRuntime			? { virtualModules: await getVirtualModules(), tsconfigPaths: true }			: { alias: getAliases() };	const jiti = createJitiImpl(import.meta.url, {		moduleCache: false,		...resolutionOptions,	});	const module = await jiti.import(extensionPath, { default: true });	const factory = module as ExtensionFactory;	if (typeof factory !== "function") {		return undefined;	}	if (isCurrentCacheToken(cacheToken)) {		extensionCache.set(extensionPath, factory);	}	return factory;}

// This import is safe because loader.ts exports are not re-exported from index.ts.// Extensions can therefore import from @earendil-works/pi-coding-agent.import * as bundledPiCodingAgent from "../../index.ts";/** Modules available to extensions in source and compiled binary runtimes. */export const VIRTUAL_MODULES: Record<string, unknown> = {	typebox: bundledTypebox,	"typebox/compile": bundledTypeboxCompile,	"typebox/value": bundledTypeboxValue,	"@sinclair/typebox": bundledTypebox,	"@sinclair/typebox/compile": bundledTypeboxCompile,	"@sinclair/typebox/value": bundledTypeboxValue,	"@earendil-works/pi-agent-core": bundledPiAgentCore,	"@earendil-works/pi-tui": bundledPiTui,	// Extensions resolve the pi-ai root to the compat entrypoint (a strict	// superset of the core entrypoint): existing extensions using the old	// global API keep working at runtime until compat is removed.	"@earendil-works/pi-ai": bundledPiAiCompat,	"@earendil-works/pi-ai/compat": bundledPiAiCompat,	"@earendil-works/pi-ai/models": bundledPiAiModels,	"@earendil-works/pi-ai/oauth": bundledPiAiOauth,	"@earendil-works/pi-ai/providers/all": bundledPiAiProviders,	"@earendil-works/pi-coding-agent": bundledPiCodingAgent,

async function initializeExtension(	factory: ExtensionFactory,	extensionPath: string,	resolvedPath: string,	cwd: string,	eventBus: EventBus,	runtime: ExtensionRuntime,): Promise<Extension> {	const extension = createExtension(extensionPath, resolvedPath);	const load = createExtensionAPI(extension, runtime, cwd, eventBus);	try {		await factory(load.api);		load.commit();	} catch (error) {		load.discard();		throw error;	}	time(`${extensionPath} factory`, "extensions");	return extension;}⋯ lược bớt dòng 636–645	try {		const factory = await loadExtensionModule(resolvedPath, cacheToken);		time(`${extensionPath} module import`, "extensions");		if (!factory) {			return { extension: null, error: `Extension does not export a valid factory function: ${extensionPath}` };		}		const extension = await initializeExtension(factory, extensionPath, resolvedPath, cwd, eventBus, runtime);		return { extension, error: null };	} catch (err) {		const message = err instanceof Error ? err.message : String(err);		return { extension: null, error: `Failed to load extension: ${message}` };	}

const pendingFlagValues = new Map<string, boolean | string>();const pendingRuntimeChanges: Array<() => void> = [];const loadingUnsubscribers: Array<() => void> = [];let state: "loading" | "active" | "failed" = "loading";const assertActive = () => {	if (state === "failed") {		throw new Error(`Extension "${extension.path}" failed to load and its API is no longer active.`);	}	runtime.assertActive();};const applyRuntimeChange = (change: () => void) => {	if (state === "loading") pendingRuntimeChanges.push(change);	else change();};const clearPending = () => {	pendingFlagValues.clear();	pendingRuntimeChanges.length = 0;	loadingUnsubscribers.length = 0;};⋯ lược bớt dòng 272–532return {	api,	commit: () => {		if (state !== "loading") return;		runtime.assertActive();		for (const [name, value] of pendingFlagValues) {			if (!runtime.flagValues.has(name)) runtime.flagValues.set(name, value);		}		for (const apply of pendingRuntimeChanges) apply();		state = "active";		clearPending();	},	discard: () => {		if (state !== "loading") return;		state = "failed";		for (const unsubscribe of loadingUnsubscribers) unsubscribe();		clearPending();	},};

export function createExtensionRuntime(): ExtensionRuntime {	const notInitialized = () => {		throw new Error("Extension runtime not initialized. Action methods cannot be called during extension loading.");	};	const state: { staleMessage?: string } = {};	const eventBusUnsubscribers = new Set<() => void>();	const assertActive = () => {		if (state.staleMessage) {			throw new Error(state.staleMessage);		}	};	const runtime: ExtensionRuntime = {		sendMessage: notInitialized,		sendUserMessage: notInitialized,		appendEntry: notInitialized,

export const builtInExtensions: InlineExtension[] = [	{ name: "llama.cpp", factory: llamaExtension, builtin: true },	// Replaceable: an extension that registers `codemode`, `tool_search`, or `/mcp` (such as a third-party	// MCP extension) takes over instead of running alongside the built-in one.	{ name: "codemode", factory: codemodeExtension, replaceable: true, builtin: true },	{ name: "tool-search", factory: toolSearchExtension, replaceable: true, builtin: true },	{ name: "mcp", factory: mcpExtension, replaceable: true, builtin: true },];

export type InlineExtension =	| ExtensionFactory	| {			/**			 * Display name shown as `<inline:name>` in the startup Extensions list and errors. With			 * `builtin`, the extension is named `builtin:name` in errors and diagnostics.			 */			name: string;			factory: ExtensionFactory;			/** Omit this extension from the startup Extensions list. */			hidden?: boolean;			/**			 * Leave this extension out when another extension registers a tool, command, or flag with a			 * name it registers during loading, instead of reporting a conflict. The CLI's built-in MCP,			 * codemode, and tool search extensions use it, so for example an MCP extension that registers			 * `/mcp` replaces the built-in MCP support. The factory still runs, so it should only register			 * tools, commands, flags, and event handlers.			 */			replaceable?: boolean;			/**			 * Supply the code of the `builtin:<name>` extension instead of loading as an inline extension.			 * `builtin:<name>` is an extension resource like a file: it loads by default, `pi config` lists			 * it, `-builtin:<name>` in the `extensions` setting and `--no-extensions` disable it, and			 * `-e builtin:<name>` loads it explicitly. It is hidden from the startup Extensions list and			 * loads after project trust is resolved, so it cannot handle `project_trust`. The CLI's built-in			 * extensions use it.			 */			builtin?: boolean;	  };

/** Load extension paths: files from disk and `builtin:<name>` paths from the built-in extensions. */private async loadExtensionPaths(paths: string[], runtime?: ExtensionRuntime): Promise<LoadExtensionsResult> {	const isBuiltinPath = (path: string) => path.startsWith(BUILTIN_PATH_PREFIX);	const result = await loadExtensionsCached(		paths.filter((path) => !isBuiltinPath(path)),		this.cwd,		this.eventBus,		runtime,	);	for (const path of paths.filter(isBuiltinPath)) {		const builtin = this.builtinExtensions.get(path.slice(BUILTIN_PATH_PREFIX.length));		if (!builtin) {			result.errors.push({ path, error: `Unknown built-in extension: ${path}` });			continue;		}		try {			const extension = await loadExtensionFromFactory(				builtin.factory,				this.cwd,				this.eventBus,				result.runtime,				path,			);			extension.hidden = true;			extension.replaceable = builtin.replaceable === true;			result.extensions.push(extension);		} catch (error) {			result.errors.push({ path, error: error instanceof Error ? error.message : "failed to load extension" });		}	}	return result;}

function omitReplacedExtensions(	extensions: Extension[],	warnings?: Array<{ path: string; warning: string }>,): Extension[] {	const names = (extension: Extension) => [		...[...extension.tools.keys()].map((name) => `tool:${name}`),		...[...extension.commands.keys()].map((name) => `command:${name}`),		...[...extension.flags.keys()].map((name) => `flag:${name}`),	];	const taken = new Map(		extensions			.filter((extension) => !extension.replaceable)			.flatMap((extension) => names(extension).map((name) => [name, extension] as const)),	);	return extensions.filter((extension) => {		if (!extension.replaceable) return true;		const replacement = names(extension)			.map((name) => ({ name, extension: taken.get(name) }))			.find((value): value is { name: string; extension: Extension } => value.extension !== undefined);		if (!replacement) return true;		if (extension.path.startsWith(BUILTIN_PATH_PREFIX)) {			const builtinName = extension.path.slice(BUILTIN_PATH_PREFIX.length);			const [kind, rawName] = replacement.name.split(":", 2);			const registeredName = kind === "command" ? `/${rawName}` : kind === "flag" ? `--${rawName}` : rawName;			warnings?.push({				path: extension.path,				warning: `Extension ${replacement.extension.path} registers ${kind} \`${registeredName}\`, so built-in extension \`${builtinName}\` was not loaded. To use \`${builtinName}\`, run \`pi config\` and make sure it is enabled under Built-in extensions, then disable or remove the existing extension. We recommend only having one or the other loaded at a time.`,			});		}		return false;	});}

export function wrapToolDefinition<TDetails = unknown>(	definition: ToolDefinition<any, TDetails>,	ctxFactory?: ToolContextFactory,): AgentTool<any, TDetails> {	return {		name: definition.name,		label: definition.label,		description: definition.description,		parameters: definition.parameters,		outputSchema: definition.outputSchema,		constrainedSampling: definition.constrainedSampling,		prepareArguments: definition.prepareArguments,		executionMode: definition.executionMode,		execute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionToolContext) =>			definition.execute(				toolCallId,				params,				signal,				onUpdate,				ctx ?? (ctxFactory?.(toolCallId, signal) as ExtensionToolContext),			),	};}

async reload(options?: { beforeSessionStart?: () => void | Promise<void> }): Promise<void> {	const oldRunner = this._extensionRunner;	const previousFlagValues = oldRunner.getFlagValues();	await emitSessionShutdownEvent(oldRunner, { type: "session_shutdown", reason: "reload" });	oldRunner.invalidate();⋯ lược bớt dòng 3725–3732	await this.settingsManager.reload();	this.syncQueueModesFromSettings();	resetApiProviders();	await this._resourceLoader.reload();	// Activate tools newly added to defaultTools. Removed ones stay active, and tools disabled	// during the session stay disabled unless the setting newly adds them.	const addedDefaultTools = getDefaultTools().filter((name) => !previousDefaultTools.has(name));	// Tools the new extensions register later, such as MCP tools, are pending until then.	for (const name of this.getActiveToolNames()) this._pendingToolNames.add(name);	this._buildRuntime({		activeToolNames: [...this.getActiveToolNames(), ...addedDefaultTools],		flagValues: previousFlagValues,		includeAllExtensionTools: true,	});⋯ lược bớt dòng 3747–3752	if (hasBindings) {		await options?.beforeSessionStart?.();		await this._extensionRunner.emit({ type: "session_start", reason: "reload" });		this._extensionRunner.reportUnhandledMcpServers();		await this.extendResourcesFromExtensions("reload");	}

const TRUST_REQUIRING_PROJECT_CONFIG_RESOURCES = [	"settings.json",	"mcp.json",	"extensions",	"skills",	"prompts",	"themes",	"SYSTEM.md",	"APPEND_SYSTEM.md",] as const;

async loadProjectTrustExtensions(): Promise<LoadExtensionsResult> {	// Force untrusted project settings for the bootstrap pass. This keeps project-local	// extensions/packages out while still loading user/global and temporary CLI extensions.	this.settingsManager.setProjectTrusted(false);	await this.settingsManager.reload();	return this.loadCurrentExtensionSet({ includeInlineFactories: true });}async reload(options?: ResourceLoaderReloadOptions): Promise<void> {	resetTimings("extensions");	if (this.loaded) {		clearExtensionCache();	}	let preTrustExtensions: LoadExtensionsResult | undefined;	if (options?.resolveProjectTrust) {		preTrustExtensions = await this.loadProjectTrustExtensions();		const projectTrusted = await options.resolveProjectTrust({ extensionsResult: preTrustExtensions });		this.settingsManager.setProjectTrusted(projectTrusted);	}	// reload() preserves SettingsManager.projectTrusted and reloads settings for that trust state.	await this.settingsManager.reload();

private async loadCurrentExtensionSet(options: { includeInlineFactories: boolean }): Promise<LoadExtensionsResult> {	const resolvedPaths = await this.packageManager.resolve();	const cliExtensionPaths = await this.packageManager.resolveExtensionSources(this.additionalExtensionPaths, {		temporary: true,	});	const enabledExtensions = resolvedPaths.extensions.filter((r) => r.enabled).map((r) => r.path);	const cliEnabledExtensions = cliExtensionPaths.extensions.filter((r) => r.enabled).map((r) => r.path);	// Built-in extensions wait for the final pass: project settings can disable them, and a loaded	// extension cannot be unloaded.	const extensionPaths = (		this.noExtensions ? cliEnabledExtensions : this.mergePaths(cliEnabledExtensions, enabledExtensions)	).filter((path) => !path.startsWith(BUILTIN_PATH_PREFIX));⋯ lược bớt dòng 692–698	const extensionsResult = await loadExtensionsCached(extensionPaths, this.cwd, this.eventBus);	mergeExtensionWarnings(extensionsResult, packageWarnings);	if (!options.includeInlineFactories) {		return extensionsResult;	}	const inlineExtensions = await this.loadExtensionFactories(extensionsResult.runtime);	extensionsResult.extensions.push(...inlineExtensions.extensions);	extensionsResult.errors.push(...inlineExtensions.errors);	const replacementWarnings: Array<{ path: string; warning: string }> = [];	extensionsResult.extensions = omitReplacedExtensions(extensionsResult.extensions, replacementWarnings);	mergeExtensionWarnings(extensionsResult, replacementWarnings);	return extensionsResult;

export async function emitProjectTrustEvent(	extensionsResult: LoadExtensionsResult,	event: ProjectTrustEvent,	ctx: ProjectTrustContext,): Promise<{ result?: ProjectTrustEventResult; errors: ExtensionError[] }> {	const errors: ExtensionError[] = [];	for (const { ext, handlers } of snapshotEventHandlers(extensionsResult.extensions, "project_trust")) {		// A single extension may register multiple handlers for the same event.		// The first project_trust handler that returns yes/no wins; undecided falls through.		for (const handler of handlers) {			try {				const handlerResult = (await handler(event, ctx)) as ProjectTrustEventResult;				if (handlerResult.trusted === "undecided") {					continue;				}				return { result: handlerResult, errors };			} catch (error) {				errors.push({					extensionPath: ext.path,					event: event.type,					error: error instanceof Error ? error.message : String(error),					stack: error instanceof Error ? error.stack : undefined,				});			}		}	}	return { errors };}

private async loadFinalExtensionSet(	extensionPaths: string[],	preTrustExtensions: LoadExtensionsResult | undefined,): Promise<LoadExtensionsResult> {	// Without a pre-trust pass nothing is preloaded, and inline extensions load here.	const preloaded = preTrustExtensions?.extensions ?? [];	const preloadedByPath = new Map(		preloaded			.filter((extension) => !extension.path.startsWith("<inline:"))			.map((extension) => [extension.resolvedPath, extension]),	);	const failedPreloadPaths = new Set(		(preTrustExtensions?.errors ?? []).map((error) => this.resolveExtensionLoadPath(error.path)),	);	const remainingPaths = extensionPaths.filter((path) => {		const resolvedPath = this.resolveExtensionLoadPath(path);		return !preloadedByPath.has(resolvedPath) && !failedPreloadPaths.has(resolvedPath);	});	const remainingExtensions = await this.loadExtensionPaths(remainingPaths, preTrustExtensions?.runtime);	const loadedByPath = new Map(preloadedByPath);	for (const extension of remainingExtensions.extensions) {		loadedByPath.set(extension.resolvedPath, extension);	}	const inlineExtensions = preTrustExtensions		? { extensions: preloaded.filter((extension) => extension.path.startsWith("<inline:")), errors: [] }		: await this.loadExtensionFactories(remainingExtensions.runtime);	const orderedExtensions = extensionPaths		.map((path) => loadedByPath.get(this.resolveExtensionLoadPath(path)))		.filter((extension): extension is Extension => extension !== undefined);	orderedExtensions.push(...inlineExtensions.extensions);

/** Extension factory function type. Supports both sync and async initialization. */export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;

/** Handler function type for events */// biome-ignore lint/suspicious/noConfusingVoidType: void allows bare return statementsexport type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;/** * ExtensionAPI passed to extension factory functions. */export interface ExtensionAPI {	// =========================================================================	// Event Subscription	// =========================================================================	on(event: "project_trust", handler: ProjectTrustHandler): () => void;	on(		event: "resources_discover",		handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>,	): () => void;	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): () => void;⋯ lược bớt dòng 1603–1660	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): () => void;	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): () => void;	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): () => void;	on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): () => void;	// =========================================================================	// Tool Registration	// =========================================================================	/** Register a tool that the LLM can call. */	registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(		tool: ToolDefinition<TParams, TDetails, TState>,	): void;

registerTool(tool: ToolDefinition): void {	assertActive();	if (typeof tool.parameters !== "object" || tool.parameters === null || Array.isArray(tool.parameters)) {		throw new Error(			`Tool "${tool.name}" registered by extension "${extension.path}" must define an object parameter schema.`,		);	}	extension.tools.set(tool.name, {		definition: tool,		sourceInfo: extension.sourceInfo,	});	runtime.refreshTools();},registerCommand(name: string, options: Omit<RegisteredCommand, "name" | "sourceInfo">): void {	assertActive();	if (typeof name !== "string" || name.length === 0) {		throw new Error(			`Command registered by extension "${extension.path}" must have a non-empty string name. Use pi.registerCommand("name", { description, handler }).`,		);	}	if (typeof options?.handler !== "function") {		throw new Error(`Command "/${name}" registered by extension "${extension.path}" must define handler().`);	}	extension.commands.set(name, {		name,		sourceInfo: extension.sourceInfo,		...options,	});},

export interface RegisteredCommand {	name: string;	sourceInfo: SourceInfo;	description?: string;	getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>;	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;}export interface ResolvedCommand extends RegisteredCommand {	invocationName: string;}

/** * Create an ExtensionContext for use in event handlers and tool execution. * Context values are resolved at call time, so changes via bindCore/bindUI are reflected. */createContext(): ExtensionContext {	const runner = this;	const getModel = this.getModel;	const getScopedModels = this.getScopedModels;	return {		get ui() {			runner.assertActive();			return runner.uiContext;		},		get mode() {			runner.assertActive();			return runner.mode;		},		get hasUI() {			runner.assertActive();			return runner.hasUI();		},		get cwd() {			runner.assertActive();			return runner.cwd;		},		get sessionManager() {			runner.assertActive();			return runner.sessionManager;		},		get modelRegistry() {			runner.assertActive();			return runner.modelRegistry;		},

runner.bindCore(	{		sendMessage: (message, options) => {			this.sendCustomMessage(message, options).catch((err) => {				runner.emitError({					extensionPath: "<runtime>",					event: "send_message",					error: err instanceof Error ? err.message : String(err),				});			});		},		sendUserMessage: (content, options) => {			this.sendUserMessage(content, options).catch((err) => {				runner.emitError({					extensionPath: "<runtime>",					event: "send_user_message",					error: err instanceof Error ? err.message : String(err),				});			});		},		appendEntry: (customType, data) => {			const entryId = this.sessionManager.appendCustomEntry(customType, data);			const entry = this.sessionManager.getEntry(entryId);			if (entry) {				this._emit({ type: "entry_appended", entry });			}⋯ lược bớt dòng 3472–3481		getActiveTools: () => this.getActiveToolNames(),		getAllTools: () => this.getAllTools(),		getSettings: () => this.settingsManager.getSettings(),		setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),		refreshTools: () => this._refreshToolRegistry(),		getCommands,		setModel: async (model) => {			if (!this._modelRuntime.hasConfiguredAuth(model.provider)) return false;			await this.setModel(model);			return true;		},

async sendCustomMessage<T = unknown>(	message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,	options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },): Promise<void> {⋯ lược bớt dòng 2361–2369	if (options?.deliverAs === "nextTurn") {		this._pendingNextTurnMessages.push(appMessage);	} else if (this.isStreaming && options?.triggerTurn !== false) {		if (options?.deliverAs === "followUp") {			this.agent.followUp(appMessage);		} else {			this.agent.steer(appMessage);		}	} else if (options?.triggerTurn) {		if (this._isEmittingAgentSettled) {			this._deferredSettledActions.push(async () => await this.sendCustomMessage(message, options));			return;		}		await this._startRun({ messageType: "custom", message: appMessage });	} else if (this.isStreaming) {		// Appending now would put the message between an assistant tool call and its		// result, which providers that validate message order reject on replay. Defer		// to the end of the turn. Nothing is emitted yet: message events must not		// describe messages the session tree does not contain.		this._pendingCustomMessages.push(appMessage);	} else {		this._appendCustomMessage(appMessage);	}}

/** * How the model reaches a tool. "Callable" means callable from other tools through * `ctx.executeTool()`, as the `codemode` tool does. * * - `direct`: declared to the model while active, and callable while active. * - `model-only`: declared to the model while active, never callable. Use it for orchestrating or *   interactive tools. * - `codemode`: callable whenever registered. Not declared to the model unless explicitly *   activated. Codemode tools list it in their description. * - `deferred`: like `codemode`, but codemode tools do not list it; tool search can find it. * - `hidden`: registered but unreachable. Activating it has no effect. * * `direct` and `model-only` tools are activated when they are registered; the others are not. * The active tool set (`getActiveTools`/`setActiveTools`) is the set declared to the model. */export type ToolExposure = "direct" | "model-only" | "codemode" | "deferred" | "hidden";

/** * Tools callable through `ctx.executeTool()`: the active `direct` tools and every registered * `codemode` or `deferred` tool. */private _getCallableTools(active: ReadonlySet<string> = new Set(this.getActiveToolNames())): AgentTool[] {	return [...this._toolRegistry.values()].filter((tool) => {		const exposure = this._getToolExposure(tool.name);		return exposure === "codemode" || exposure === "deferred" || (exposure === "direct" && active.has(tool.name));	});}

/** The tools of a session as {@link ToolDefinition.prepareLoadout} sees them. */export interface ToolLoadout {	/** Tools declared to the model (the active tools), in order, with their original descriptions. */	readonly declared: readonly AgentTool[];	/** Tools callable through `ctx.executeTool()`. */	readonly callable: readonly AgentTool[];	/** Every registered tool. */	readonly registered: readonly AgentTool[];	getExposure(name: string): ToolExposure;	getNamespace(name: string): ToolNamespace | undefined;	/** A tool's `promptGuidelines`. Hidden declarations leave them out of the system prompt. */	getPromptGuidelines(name: string): readonly string[];}/** Changes {@link ToolDefinition.prepareLoadout} makes to what the model sees. */export interface ToolLoadoutChanges {	/** Model-facing descriptions of declared tools, by tool name. */	descriptions?: Readonly<Record<string, string>>;	/**	 * Declared tools whose declarations requests leave out. They stay active and callable, and the	 * transcript still declares them, so the active set survives `/tree` and resume.	 */	hiddenDeclarations?: readonly string[];}

function snapshotEventHandlers(extensions: Extension[], event: ExtensionEvent["type"]) {	return extensions.map((ext) => ({ ext, handlers: ext.handlers.get(event)?.slice() ?? [] }));}

async emit<TEvent extends RunnerEmitEvent>(event: TEvent): Promise<RunnerEmitResult<TEvent>> {	const ctx = this.createContext();	let result: SessionBeforeEventResult | undefined;	for (const { ext, handlers } of snapshotEventHandlers(this.extensions, event.type)) {		for (const handler of handlers) {			try {				const handlerResult = await handler(event, ctx);				if (this.isSessionBeforeEvent(event) && handlerResult) {					result = handlerResult as SessionBeforeEventResult;					if (result.cancel) {						return result as RunnerEmitResult<TEvent>;					}				}			} catch (err) {				const message = err instanceof Error ? err.message : String(err);				const stack = err instanceof Error ? err.stack : undefined;				this.emitError({					extensionPath: ext.path,					event: event.type,					error: message,					stack,				});			}		}	}	return result as RunnerEmitResult<TEvent>;}

/** * Run the request-time transforms in two phases. `context` handlers see the conversation * only and Pi restores the prompt and tool state after each; `context_with_system` * handlers then see the full transcript and their output is used as returned. */async emitContext(messages: AgentMessage[]): Promise<AgentMessage[]> {	const ctx = this.createContext();	let currentMessages = structuredClone(messages);	for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "context")) {		for (const handler of handlers) {			try {				const visibleMessages = currentMessages.filter((message) => message.role !== "system");				const visibleSnapshot = visibleMessages.slice();				const event: ContextEvent = { type: "context", messages: visibleMessages };				const handlerResult = (await handler(event, ctx)) as ContextEventResult | undefined;				// Handlers may return a new list or edit event.messages in place.				const returned =					handlerResult?.messages ??					(sameMessages(visibleMessages, visibleSnapshot) ? undefined : visibleMessages);				if (!returned) continue;				currentMessages = restoreSystemMessages(currentMessages, visibleSnapshot, returned);⋯ lược bớt dòng 1323–1335	for (const { ext, handlers } of snapshotEventHandlers(this.extensions, "context_with_system")) {		for (const handler of handlers) {			try {				const hadLeadingSystemMessage = currentMessages[0]?.role === "system";				const event: ContextWithSystemEvent = { type: "context_with_system", messages: currentMessages };				const handlerResult = (await handler(event, ctx)) as ContextEventResult | undefined;				currentMessages = handlerResult?.messages ?? currentMessages;				// Providers read the prompt and initial tools from the leading system message.				// Losing it is never intended; report it but honor the handler's output.				if (hadLeadingSystemMessage && currentMessages[0]?.role !== "system") {					this.emitError({						extensionPath: ext.path,						event: "context_with_system",						error: "Handler removed the leading system message; the request has no prompt or initial tool declarations. Keep it at index 0 or replace a dropped prefix with getCurrentSystemMessage().",					});				}

/** * Re-attach the prompt and tool state after a `context` handler. Handlers only see the * conversation; the system messages belong to Pi. An unchanged conversation keeps every * system message in place, so models with mid-conversation support keep their cached * prefix. A changed one gets the replayed prompt sections and tool declarations as one * leading system message, so pruning, windowing, or slicing from a compaction summary * cannot drop them. */function restoreSystemMessages(	current: AgentMessage[],	visible: AgentMessage[],	returned: AgentMessage[],): AgentMessage[] {	if (sameMessages(returned, visible)) return current;	const head = getCurrentSystemMessage(current);	return head ? [head, ...returned] : returned;}

export default function (pi: ExtensionAPI) {	const dangerousPatterns = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i, /\b(chmod|chown)\b.*777/i];	pi.on("tool_call", async (event, ctx) => {		if (event.toolName !== "bash") return undefined;		const command = event.input.command as string;		const isDangerous = dangerousPatterns.some((p) => p.test(command));		if (isDangerous) {			if (!ctx.hasUI) {				// In non-interactive mode, block by default				return { block: true, reason: "Dangerous command blocked (no UI for confirmation)" };			}			const choice = await ctx.ui.select(`⚠️ Dangerous command:\n\n  ${command}\n\nAllow?`, ["Yes", "No"]);			if (choice !== "Yes") {				return { block: true, reason: "Blocked by user" };			}		}		return undefined;	});}

export function validateToolArguments(tool: Tool, toolCall: ToolCall): any {	if (toolCall.argumentsError) {		throw new Error(`Invalid arguments for tool "${toolCall.name}": ${toolCall.argumentsError}`);	}	const args = structuredClone(toolCall.arguments);	normalizeOptionalNulls(args, tool.parameters as JsonSchemaObject);	Value.Convert(tool.parameters, args);

private _installAgentToolHooks(): void {	this.agent.beforeToolCall = (context) => this._beforeToolCall(context);	this.agent.afterToolCall = (context) => this._afterToolCall(context);}/** `tool_call` handlers. `parentToolCallId` is set for calls another tool made. */private async _beforeToolCall(	{ toolCall, args }: BeforeToolCallContext,	parentToolCallId?: string,): Promise<BeforeToolCallResult | undefined> {	const runner = this._extensionRunner;	if (!runner.hasHandlers("tool_call")) {		return undefined;	}	try {		return await runner.emitToolCall({			type: "tool_call",			toolName: toolCall.name,			toolCallId: toolCall.id,			...(parentToolCallId ? { parentToolCallId } : {}),			input: args as Record<string, unknown>,		});	} catch (err) {		if (err instanceof Error) {			throw err;		}		throw new Error(`Extension failed, blocking execution: ${String(err)}`);	}}

async emitToolCall(event: ToolCallEvent): Promise<ToolCallEventResult | undefined> {	const ctx = this.createContext();	let result: ToolCallEventResult | undefined;	for (const { handlers } of snapshotEventHandlers(this.extensions, "tool_call")) {		for (const handler of handlers) {			const handlerResult = await handler(event, ctx);			if (handlerResult) {				result = handlerResult as ToolCallEventResult;				if (result.block) {					return result;				}			}		}	}	return result;}

private async _afterToolCall(	{ toolCall, args, result, isError }: AfterToolCallContext,	parentToolCallId?: string,): Promise<AfterToolCallResult | undefined> {	const runner = this._extensionRunner;	const hookResult = runner.hasHandlers("tool_result")		? await runner.emitToolResult({				type: "tool_result",				toolName: toolCall.name,				toolCallId: toolCall.id,				...(parentToolCallId ? { parentToolCallId } : {}),				input: args as Record<string, unknown>,				content: result.content,				details: result.details,				...(result.structuredContent === undefined ? {} : { structuredContent: result.structuredContent }),				isError,				usage: result.usage,			})		: undefined;	const content = hookResult?.content ?? result.content ?? [];	// Runs after the extension hook so images injected or replaced by extensions are normalized too.	const resizeOptions = this._limitsModel()?.inputLimits?.images?.resize;	const normalizedContent = await normalizeToolResultImages(content, {		autoResizeImages: this.settingsManager.getImageAutoResize(),		...(resizeOptions ? { resizeOptions } : {}),	});	if (!hookResult && normalizedContent === content) {		return undefined;	}	// The hook result already dropped structured content that replaced content no longer matches.	return {		content: normalizedContent,		details: hookResult?.details,		structuredContent: hookResult ? hookResult.structuredContent : result.structuredContent,		isError: hookResult?.isError ?? isError,		usage: hookResult?.usage,	};

function enablePlanModeTools(): void {	if (toolsBeforePlanMode === undefined) {		toolsBeforePlanMode = pi.getActiveTools();	}	pi.setActiveTools(getPlanModeTools(toolsBeforePlanMode));}function restoreNormalModeTools(): void {	pi.setActiveTools(toolsBeforePlanMode ?? getNormalModeTools(pi.getActiveTools()));	toolsBeforePlanMode = undefined;}function persistState(): void {	pi.appendEntry("plan-mode", {		enabled: planModeEnabled,		todos: todoItems,		executing: executionMode,		toolsBeforePlanMode,	});}

// Block destructive bash commands in plan modepi.on("tool_call", async (event) => {	if (!planModeEnabled || event.toolName !== "bash") return;	const command = event.input.command as string;	if (!isSafeCommand(command)) {		return {			block: true,			reason: `Plan mode: command blocked (not allowlisted). Use /plan to disable plan mode first.\nCommand: ${command}`,		};	}});