@selesai/code 0.13.39 → 0.14.0

package/dist/core/release-rpc.js

@@ -0,0 +1,77 @@
+export const RELEASE_READINESS_EVENT = "release:readiness:v1";
+/**
+ * Core blocker kind reported by `release_readiness` once a `release` has been committed (the process is about to exit).
+ * `kind` is `releasing`.
+ */
+export const RELEASING_BLOCKER_KIND = "releasing";
+/**
+ * Whether a readiness answer permits an immediate release. "Nobody answered" (`contributors` empty, e.g. extensions not
+ * loaded) is NOT safe: the process cannot prove that no background work exists.
+ */
+export function decideRelease(readiness) {
+    return readiness.safe === true && readiness.blockers.length === 0 && readiness.contributors.length > 0;
+}
+/**
+ * Listener-side helper: gate on session identity, compute blockers, and fail closed.
+ * The EventBus swallows listener exceptions, so a contributor that throws would otherwise look like "not loaded"
+ * and the host would report safe. Always answer through this helper (or reproduce its try/catch).
+ */
+export function answerReleaseReadiness(raw, name, boundSessionId, compute) {
+    const request = raw;
+    if (!request || request.version !== 1 || typeof request.contribute !== "function" || !boundSessionId || request.sessionId !== boundSessionId)
+        return;
+    let blockers;
+    try {
+        blockers = compute();
+    }
+    catch (error) {
+        blockers = [{ source: name, kind: "contributor_error", detail: (error instanceof Error ? error.message : String(error)).slice(0, 512) || "contributor failed" }];
+    }
+    request.contribute(name, blockers);
+}
+const text = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
+const record = (v) => Boolean(v && typeof v === "object" && !Array.isArray(v));
+/** Bounded shape check for blockers received from trusted-but-fallible extension contributors. */
+export function isReleaseBlocker(v) {
+    return record(v) && Object.keys(v).every(key => ["source", "kind", "id", "detail", "since"].includes(key))
+        && text(v.source, 64) && text(v.kind, 64) && text(v.detail, 512)
+        && (v.id === undefined || text(v.id, 256))
+        && (v.since === undefined || typeof v.since === "number" && Number.isSafeInteger(v.since) && v.since >= 0);
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// stop_all_background: the kill switch behind the desktop's "Quit anyway".
+// ---------------------------------------------------------------------------------------------------------------------
+export const STOP_ALL_BACKGROUND_EVENT = "release:stop-all:v1";
+/** Total budget for one `stop_all_background`: core abort plus every extension's (possibly asynchronous) stop. */
+export const STOP_ALL_BACKGROUND_TIMEOUT_MS = 5_000;
+/**
+ * Listener-side helper: gate on session identity and fail closed. A synchronous throw becomes an `ok:false` item, so one
+ * extension failing never prevents the others from stopping (the bridge also converts a rejected promise).
+ */
+export function answerStopAllBackground(raw, name, boundSessionId, compute) {
+    const request = raw;
+    if (!request || request.version !== 1 || typeof request.contribute !== "function" || !boundSessionId || request.sessionId !== boundSessionId)
+        return;
+    const deadline = typeof request.deadline === "number" && Number.isFinite(request.deadline) ? request.deadline : Date.now() + STOP_ALL_BACKGROUND_TIMEOUT_MS;
+    let items;
+    try {
+        items = compute({ deadline });
+    }
+    catch (error) {
+        items = [stopAllContributorError(name, error)];
+    }
+    request.contribute(name, items);
+}
+/** The item every failure path uses, so a broken contributor is visible instead of silent. */
+export function stopAllContributorError(source, error) {
+    const detail = (error instanceof Error ? error.message : String(error)).slice(0, 400) || "contributor failed";
+    return { source, kind: "contributor", detail: `Stop failed: ${detail}`, ok: false, error: detail.slice(0, 256) };
+}
+/** Bounded shape check for items received from trusted-but-fallible extension contributors. */
+export function isStopAllBackgroundItem(v) {
+    return record(v) && Object.keys(v).every(key => ["source", "kind", "id", "detail", "ok", "error"].includes(key))
+        && text(v.source, 64) && text(v.kind, 64) && text(v.detail, 512)
+        && (v.id === undefined || text(v.id, 256))
+        && typeof v.ok === "boolean"
+        && (v.error === undefined || text(v.error, 256));
+}

package/dist/core/remote-catalog-provider.d.ts

@@ -1,4 +1,11 @@
-import type { Provider } from "@earendil-works/pi-ai";
+import { type ModelType, type Provider } from "@earendil-works/pi-ai";
 export declare const REMOTE_CATALOG_REFRESH_INTERVAL_MS: number;
+/**
+ * Model types this client can consume. Sent as `?types=` so the catalog server
+ * returns the full-type shard instead of the chat-only one served to clients
+ * that predate model types. A server that ignores the parameter still returns
+ * the chat-only shard, which this client handles unchanged.
+ */
+export declare const REMOTE_CATALOG_MODEL_TYPES: readonly ModelType[];
 /** Add a persisted pi.dev catalog overlay to a static built-in provider. */
 export declare function withRemoteCatalog(provider: Provider, catalogBaseUrl?: string, localGeneratedAt?: number): Provider;

package/dist/core/remote-catalog-provider.js

@@ -1,17 +1,26 @@
+import { getModelType, isModelType, } from "@earendil-works/pi-ai";
 import { PI_PLATFORM_VERSION } from "../config.js";
+import { fetchWithRetry } from "../utils/management-http.js";
 import { getPiUserAgent } from "../utils/pi-user-agent.js";
+const REMOTE_CATALOG_ATTEMPT_TIMEOUT_MS = 4_000;
 const DEFAULT_CATALOG_BASE_URL = "https://pi.dev";
 export const REMOTE_CATALOG_REFRESH_INTERVAL_MS = 4 * 60 * 60 * 1000;
+/**
+ * Model types this client can consume. Sent as `?types=` so the catalog server
+ * returns the full-type shard instead of the chat-only one served to clients
+ * that predate model types. A server that ignores the parameter still returns
+ * the chat-only shard, which this client handles unchanged.
+ */
+export const REMOTE_CATALOG_MODEL_TYPES = ["chat", "image", "classifier"];
+function isSupportedModelType(model) {
+    return (model.type === undefined ||
+        (typeof model.type === "string" && REMOTE_CATALOG_MODEL_TYPES.includes(model.type)));
+}
 function mergeModels(baseline, dynamic) {
-    const merged = [...baseline];
-    for (const model of dynamic) {
-        const index = merged.findIndex((entry) => entry.id === model.id);
-        if (index >= 0)
-            merged[index] = model;
-        else
-            merged.push(model);
-    }
-    return merged;
+    const merged = new Map();
+    for (const model of [...baseline, ...dynamic])
+        merged.set(`${getModelType(model)}\0${model.id}`, model);
+    return [...merged.values()];
 }
 function parseCatalog(providerId, value) {
     const entries = Array.isArray(value)
@@ -25,6 +34,7 @@ function parseCatalog(providerId, value) {
         throw new Error(`Invalid model catalog for provider "${providerId}"`);
     return entries
         .filter((entry) => typeof entry === "object" && entry !== null && "id" in entry)
+        .filter(isSupportedModelType)
         .map((model) => ({ ...model, provider: providerId }));
 }
 function remoteModels(entry, localGeneratedAt) {
@@ -44,7 +54,8 @@ export function withRemoteCatalog(provider, catalogBaseUrl = DEFAULT_CATALOG_BAS
     let dynamicModels = [];
     return {
         ...provider,
-        getModels: () => mergeModels(provider.getModels(), dynamicModels),
+        getModels: () => mergeModels(provider.getModels(), dynamicModels.filter((model) => isModelType(model, "chat"))),
+        getAllModels: () => mergeModels(provider.getAllModels?.() ?? provider.getModels(), dynamicModels),
         refreshModels: async (context) => {
             const stored = context.stored;
             const restored = remoteModels(stored, localGeneratedAt).filter((model) => model.provider === provider.id);
@@ -65,16 +76,17 @@ export function withRemoteCatalog(provider, catalogBaseUrl = DEFAULT_CATALOG_BAS
             }
             // Only revalidate when a cached body backs the validator, so a 304 can never
             // leave the overlay empty.
-            const validator = stored?.models.length ? stored.etag : undefined;
+            const validator = stored && stored.models.length > 0 ? stored.etag : undefined;
             const url = new URL(`/api/models/providers/${encodeURIComponent(provider.id)}`, catalogBaseUrl);
-            const response = await fetch(url, {
+            url.searchParams.set("types", REMOTE_CATALOG_MODEL_TYPES.join(","));
+            const response = await fetchWithRetry(url, {
                 headers: {
                     accept: "application/json",
                     "User-Agent": getPiUserAgent(PI_PLATFORM_VERSION),
                     ...(validator ? { "if-none-match": validator } : {}),
                 },
                 signal: context.signal,
-            });
+            }, { attemptTimeoutMs: REMOTE_CATALOG_ATTEMPT_TIMEOUT_MS });
             if (context.signal.aborted)
                 return;
             const checkedAt = Date.now();

package/dist/core/resource-loader.d.ts

@@ -2,7 +2,7 @@ import { type Theme } from "../modes/interactive/theme/theme.ts";
 import type { ResourceDiagnostic } from "./diagnostics.ts";
 export type { ResourceCollision, ResourceDiagnostic } from "./diagnostics.ts";
 import { type EventBus } from "./event-bus.ts";
-import type { InlineExtension, LoadExtensionsResult } from "./extensions/types.ts";
+import type { ExtensionFactory, InlineExtension, LoadExtensionsResult } from "./extensions/types.ts";
 import { type PathMetadata, type ResolvedResource } from "./package-manager.ts";
 import type { PromptTemplate } from "./prompt-templates.ts";
 import { SettingsManager } from "./settings-manager.ts";
@@ -27,7 +27,12 @@ export interface ResourceLoaderReloadOptions {
         extensionsResult: LoadExtensionsResult;
     }) => Promise<boolean>;
 }
+type BuiltinExtension = Exclude<InlineExtension, ExtensionFactory>;
+/** Built-in extensions supply the code of `builtin:<name>` extension paths (see `InlineExtension`). */
+export declare function isBuiltinExtension(input: InlineExtension): input is BuiltinExtension;
 export interface ResourceLoader {
+    /** Same-process extension bridge for host integrations; never exposed as an arbitrary RPC command. */
+    getEventBus?(): EventBus;
     getExtensions(): LoadExtensionsResult;
     getExtensionDiagnostics(): ResourceDiagnostic[];
     getSkills(): {
@@ -97,6 +102,8 @@ export interface DefaultResourceLoaderOptions {
     additionalThemePaths?: string[];
     extensionFactories?: InlineExtension[];
     noExtensions?: boolean;
+    /** Built-in extensions not to load, by name (such as `mcp`), even when settings or `-e` enable them. */
+    disabledBuiltinExtensions?: string[];
     noSkills?: boolean;
     noAgents?: boolean;
     noPromptTemplates?: boolean;
@@ -159,7 +166,9 @@ export declare class DefaultResourceLoader implements ResourceLoader {
     private additionalPromptTemplatePaths;
     private additionalThemePaths;
     private extensionFactories;
+    private builtinExtensions;
     private noExtensions;
+    private disabledBuiltinExtensions;
     private noSkills;
     private noAgents;
     private noPromptTemplates;
@@ -201,6 +210,7 @@ export declare class DefaultResourceLoader implements ResourceLoader {
     private lastThemePaths;
     private loaded;
     constructor(options: DefaultResourceLoaderOptions);
+    getEventBus(): EventBus;
     getExtensions(): LoadExtensionsResult;
     getExtensionDiagnostics(): ResourceDiagnostic[];
     getSkills(): {
@@ -241,6 +251,7 @@ export declare class DefaultResourceLoader implements ResourceLoader {
     reload(options?: ResourceLoaderReloadOptions): Promise<void>;
     private loadCurrentExtensionSet;
     private resolveExtensionLoadPath;
+    private loadExtensionPaths;
     private loadFinalExtensionSet;
     private addExtensionConflictDiagnostics;
     /**

package/dist/core/resource-loader.js

@@ -1,5 +1,7 @@
+import { stripBom } from "../utils/text.js";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
+import { detectCapabilities, getTerminalColorMode } from "@earendil-works/pi-tui";
 import chalk from "chalk";
 import { CONFIG_DIR_NAME } from "../config.js";
 import { loadThemeFromPath } from "../modes/interactive/theme/theme.js";
@@ -13,15 +15,97 @@ import { loadPromptTemplates } from "./prompt-templates.js";
 import { SettingsManager } from "./settings-manager.js";
 import { loadAgents } from "./agents.js";
 import { loadSkills } from "./skills.js";
-import { createSourceInfo } from "./source-info.js";
+import { BUILTIN_PATH_PREFIX, createSourceInfo, getSyntheticPathSource, isSyntheticPath, } from "./source-info.js";
 import { resetTimings } from "./timings.js";
+const HOST_PROVIDED_EXTENSION_PACKAGES = new Set([
+    "@earendil-works/pi-agent-core",
+    "@earendil-works/pi-ai",
+    "@earendil-works/pi-coding-agent",
+    "@earendil-works/pi-tui",
+    "@mariozechner/pi-agent-core",
+    "@mariozechner/pi-ai",
+    "@mariozechner/pi-coding-agent",
+    "@mariozechner/pi-tui",
+    "@sinclair/typebox",
+    "typebox",
+]);
+function collectExtensionPackageWarnings(extensionPaths, metadataByPath) {
+    const warnings = [];
+    const packageRoots = new Set(extensionPaths
+        .map((extensionPath) => metadataByPath.get(extensionPath)?.packageRoot)
+        .filter((packageRoot) => packageRoot !== undefined));
+    for (const packageRoot of packageRoots) {
+        const packageJsonPath = join(packageRoot, "package.json");
+        if (!existsSync(packageJsonPath))
+            continue;
+        const manifest = JSON.parse(stripBom(readFileSync(packageJsonPath, "utf-8")));
+        if (typeof manifest.dependencies !== "object" ||
+            manifest.dependencies === null ||
+            Array.isArray(manifest.dependencies)) {
+            continue;
+        }
+        const hostDependencies = Object.keys(manifest.dependencies)
+            .filter((name) => HOST_PROVIDED_EXTENSION_PACKAGES.has(name))
+            .sort();
+        if (hostDependencies.length === 0)
+            continue;
+        warnings.push({
+            path: packageJsonPath,
+            warning: `Host-provided extension packages must be declared in peerDependencies with a "*" range, not dependencies: ${hostDependencies.join(", ")}. Installed copies can bypass the extension loader and create duplicate runtime modules.`,
+        });
+    }
+    return warnings;
+}
+function mergeExtensionWarnings(result, warnings) {
+    result.warnings = [
+        ...new Map([...(result.warnings ?? []), ...warnings].map((warning) => [warning.path, warning])).values(),
+    ];
+}
+/** Built-in extensions supply the code of `builtin:<name>` extension paths (see `InlineExtension`). */
+export function isBuiltinExtension(input) {
+    return typeof input !== "function" && input.builtin === true;
+}
+/**
+ * Leave out replaceable extensions (see `InlineExtension`) that share a tool, command, or flag name
+ * with another extension. For example, a third-party MCP extension that registers `/mcp` replaces
+ * the built-in MCP extension instead of both connecting the same servers.
+ */
+function omitReplacedExtensions(extensions, warnings) {
+    const names = (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])));
+    return extensions.filter((extension) => {
+        if (!extension.replaceable)
+            return true;
+        const replacement = names(extension)
+            .map((name) => ({ name, extension: taken.get(name) }))
+            .find((value) => 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;
+    });
+}
 function resolvePromptInput(input, description) {
     if (!input) {
         return undefined;
     }
     if (existsSync(input)) {
         try {
-            return readFileSync(input, "utf-8");
+            return stripBom(readFileSync(input, "utf-8"));
         }
         catch (error) {
             console.error(chalk.yellow(`Warning: Could not read ${description} file ${input}: ${error}`));
@@ -31,7 +115,7 @@ function resolvePromptInput(input, description) {
     return input;
 }
 function loadContextFileFromDir(dir) {
-    const candidates = ["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+    const candidates = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
     for (const filename of candidates) {
         const filePath = join(dir, filename);
         if (existsSync(filePath)) {
@@ -41,7 +125,7 @@ function loadContextFileFromDir(dir) {
                 }
                 return {
                     path: filePath,
-                    content: readFileSync(filePath, "utf-8"),
+                    content: stripBom(readFileSync(filePath, "utf-8")),
                 };
             }
             catch (error) {
@@ -53,7 +137,7 @@ function loadContextFileFromDir(dir) {
 }
 /**
  * The main repo's context file that a nested linked worktree's own copy shadows: both
- * are the same tracked AGENTS.md/CLAUDE.md, so loading both loads it twice. Returns
+ * occupy the same logical repository scope, so loading both applies that context twice. Returns
  * undefined when nothing is shadowed, leaving normal ancestor inheritance alone.
  *
  * Returned canonicalized (realpath), because `git worktree add` writes the `.git`
@@ -120,7 +204,9 @@ export class DefaultResourceLoader {
     additionalPromptTemplatePaths;
     additionalThemePaths;
     extensionFactories;
+    builtinExtensions;
     noExtensions;
+    disabledBuiltinExtensions;
     noSkills;
     noAgents;
     noPromptTemplates;
@@ -166,18 +252,22 @@ export class DefaultResourceLoader {
         this.agentDir = resolvePath(options.agentDir);
         this.settingsManager = options.settingsManager ?? SettingsManager.create(this.cwd, this.agentDir);
         this.eventBus = options.eventBus ?? createEventBus();
+        const factories = options.extensionFactories ?? [];
+        this.extensionFactories = factories.filter((input) => !isBuiltinExtension(input));
+        this.builtinExtensions = new Map(factories.filter(isBuiltinExtension).map((input) => [input.name, input]));
         this.packageManager = new DefaultPackageManager({
             cwd: this.cwd,
             agentDir: this.agentDir,
             settingsManager: this.settingsManager,
+            builtinExtensions: [...this.builtinExtensions.keys()],
         });
         this.additionalExtensionPaths = options.additionalExtensionPaths ?? [];
         this.additionalSkillPaths = options.additionalSkillPaths ?? [];
         this.additionalAgentPaths = options.additionalAgentPaths ?? [];
         this.additionalPromptTemplatePaths = options.additionalPromptTemplatePaths ?? [];
         this.additionalThemePaths = options.additionalThemePaths ?? [];
-        this.extensionFactories = options.extensionFactories ?? [];
         this.noExtensions = options.noExtensions ?? false;
+        this.disabledBuiltinExtensions = new Set(options.disabledBuiltinExtensions);
         this.noSkills = options.noSkills ?? false;
         this.noAgents = options.noAgents ?? false;
         this.noPromptTemplates = options.noPromptTemplates ?? false;
@@ -215,6 +305,9 @@ export class DefaultResourceLoader {
         this.lastThemePaths = [];
         this.loaded = false;
     }
+    getEventBus() {
+        return this.eventBus;
+    }
     getExtensions() {
         return this.extensionsResult;
     }
@@ -350,12 +443,13 @@ export class DefaultResourceLoader {
         const cliEnabledSkills = getEnabledPaths(cliExtensionPaths.skills);
         const cliEnabledPrompts = getEnabledPaths(cliExtensionPaths.prompts);
         const cliEnabledThemes = getEnabledPaths(cliExtensionPaths.themes);
-        const extensionPaths = this.noExtensions
-            ? cliEnabledExtensions
-            : this.mergePaths(cliEnabledExtensions, enabledExtensions);
+        const extensionPaths = (this.noExtensions ? cliEnabledExtensions : this.mergePaths(cliEnabledExtensions, enabledExtensions)).filter((path) => !path.startsWith(BUILTIN_PATH_PREFIX) ||
+            !this.disabledBuiltinExtensions.has(path.slice(BUILTIN_PATH_PREFIX.length)));
+        const packageWarnings = collectExtensionPackageWarnings(extensionPaths, metadataByPath);
         const extensionsResult = await this.loadFinalExtensionSet(extensionPaths, preTrustExtensions);
+        mergeExtensionWarnings(extensionsResult, packageWarnings);
         for (const p of this.additionalExtensionPaths) {
-            if (isLocalPath(p)) {
+            if (!isSyntheticPath(p) && isLocalPath(p)) {
                 const resolved = this.resolveResourcePath(p);
                 if (!existsSync(resolved)) {
                     extensionsResult.errors.push({ path: resolved, error: `Extension path does not exist: ${resolved}` });
@@ -455,53 +549,83 @@ export class DefaultResourceLoader {
         });
         const enabledExtensions = resolvedPaths.extensions.filter((r) => r.enabled).map((r) => r.path);
         const cliEnabledExtensions = cliExtensionPaths.extensions.filter((r) => r.enabled).map((r) => r.path);
-        const extensionPaths = this.noExtensions
-            ? cliEnabledExtensions
-            : this.mergePaths(cliEnabledExtensions, enabledExtensions);
+        // 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));
+        const metadataByPath = new Map([...resolvedPaths.extensions, ...cliExtensionPaths.extensions].map((resource) => [
+            resource.path,
+            resource.metadata,
+        ]));
+        const packageWarnings = collectExtensionPackageWarnings(extensionPaths, metadataByPath);
         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 = [];
+        extensionsResult.extensions = omitReplacedExtensions(extensionsResult.extensions, replacementWarnings);
+        mergeExtensionWarnings(extensionsResult, replacementWarnings);
         return extensionsResult;
     }
     resolveExtensionLoadPath(path) {
-        return resolvePath(path, this.cwd, { normalizeUnicodeSpaces: true });
+        return isSyntheticPath(path) ? path : resolvePath(path, this.cwd, { normalizeUnicodeSpaces: true });
     }
-    async loadFinalExtensionSet(extensionPaths, preTrustExtensions) {
-        if (!preTrustExtensions) {
-            const extensionsResult = await loadExtensionsCached(extensionPaths, this.cwd, this.eventBus);
-            const inlineExtensions = await this.loadExtensionFactories(extensionsResult.runtime);
-            extensionsResult.extensions.push(...inlineExtensions.extensions);
-            extensionsResult.errors.push(...inlineExtensions.errors);
-            this.addExtensionConflictDiagnostics(extensionsResult);
-            return extensionsResult;
+    /** Load extension paths: files from disk and `builtin:<name>` paths from the built-in extensions. */
+    async loadExtensionPaths(paths, runtime) {
+        const isBuiltinPath = (path) => 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" });
+            }
         }
-        const preloadedByPath = new Map(preTrustExtensions.extensions
+        return result;
+    }
+    async loadFinalExtensionSet(extensionPaths, preTrustExtensions) {
+        // 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 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 loadExtensionsCached(remainingPaths, this.cwd, this.eventBus, preTrustExtensions.runtime);
+        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.filter((extension) => extension.path.startsWith("<inline:"));
+        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 !== undefined);
-        orderedExtensions.push(...inlineExtensions);
+        orderedExtensions.push(...inlineExtensions.extensions);
+        const replacementWarnings = [];
         const extensionsResult = {
-            extensions: orderedExtensions,
-            errors: [...preTrustExtensions.errors, ...remainingExtensions.errors],
-            runtime: preTrustExtensions.runtime,
+            extensions: omitReplacedExtensions(orderedExtensions, replacementWarnings),
+            errors: [...(preTrustExtensions?.errors ?? []), ...remainingExtensions.errors, ...inlineExtensions.errors],
+            warnings: [...(preTrustExtensions?.warnings ?? []), ...(remainingExtensions.warnings ?? [])],
+            runtime: remainingExtensions.runtime,
         };
+        mergeExtensionWarnings(extensionsResult, replacementWarnings);
         this.addExtensionConflictDiagnostics(extensionsResult);
         return extensionsResult;
     }
@@ -611,13 +735,17 @@ export class DefaultResourceLoader {
             promptsResult = { prompts: [], diagnostics: [] };
         }
         else {
-            const allPrompts = loadPromptTemplates({
+            const loaded = loadPromptTemplates({
                 cwd: this.cwd,
                 agentDir: this.agentDir,
                 promptPaths,
                 includeDefaults: false,
             });
-            promptsResult = this.dedupePrompts(allPrompts);
+            const deduped = this.dedupePrompts(loaded.templates);
+            promptsResult = {
+                prompts: deduped.prompts,
+                diagnostics: [...loaded.diagnostics, ...deduped.diagnostics],
+            };
         }
         const resolvedPrompts = this.promptsOverride ? this.promptsOverride(promptsResult) : promptsResult;
         this.prompts = resolvedPrompts.prompts.map((prompt) => ({
@@ -634,7 +762,12 @@ export class DefaultResourceLoader {
             themesResult = { themes: [], diagnostics: [] };
         }
         else {
-            const loaded = this.loadThemes(themePaths, false);
+            // Theme construction only needs trueColor, so skip the unrelated tmux hyperlink probe.
+            const colorMode = getTerminalColorMode({
+                ...detectCapabilities(() => false),
+                ...this.settingsManager.getTerminalCapabilityOverrides(),
+            });
+            const loaded = this.loadThemes(themePaths, false, colorMode);
             const deduped = this.dedupeThemes(loaded.themes);
             themesResult = { themes: deduped.themes, diagnostics: [...loaded.diagnostics, ...deduped.diagnostics] };
         }
@@ -689,7 +822,7 @@ export class DefaultResourceLoader {
         if (!resourcePath) {
             return undefined;
         }
-        if (resourcePath.startsWith("<")) {
+        if (isSyntheticPath(resourcePath)) {
             return this.getDefaultSourceInfoForPath(resourcePath);
         }
         const normalizedResourcePath = resolve(resourcePath);
@@ -718,10 +851,11 @@ export class DefaultResourceLoader {
         return undefined;
     }
     getDefaultSourceInfoForPath(filePath) {
-        if (filePath.startsWith("<") && filePath.endsWith(">")) {
+        const syntheticSource = getSyntheticPathSource(filePath);
+        if (syntheticSource) {
             return {
                 path: filePath,
-                source: filePath.slice(1, -1).split(":")[0] || "temporary",
+                source: syntheticSource,
                 scope: "temporary",
                 origin: "top-level",
             };
@@ -771,15 +905,15 @@ export class DefaultResourceLoader {
         return merged;
     }
     resolveResourcePath(p) {
-        return resolvePath(p, this.cwd, { trim: true });
+        return isSyntheticPath(p) ? p : resolvePath(p, this.cwd, { trim: true });
     }
-    loadThemes(paths, includeDefaults = true) {
+    loadThemes(paths, includeDefaults, colorMode) {
         const themes = [];
         const diagnostics = [];
         if (includeDefaults) {
             const defaultDirs = [join(this.agentDir, "themes"), join(this.cwd, CONFIG_DIR_NAME, "themes")];
             for (const dir of defaultDirs) {
-                this.loadThemesFromDir(dir, themes, diagnostics);
+                this.loadThemesFromDir(dir, themes, diagnostics, colorMode);
             }
         }
         for (const p of paths) {
@@ -791,10 +925,10 @@ export class DefaultResourceLoader {
             try {
                 const stats = statSync(resolved);
                 if (stats.isDirectory()) {
-                    this.loadThemesFromDir(resolved, themes, diagnostics);
+                    this.loadThemesFromDir(resolved, themes, diagnostics, colorMode);
                 }
                 else if (stats.isFile() && resolved.endsWith(".json")) {
-                    this.loadThemeFromFile(resolved, themes, diagnostics);
+                    this.loadThemeFromFile(resolved, themes, diagnostics, colorMode);
                 }
                 else {
                     diagnostics.push({ type: "warning", message: "theme path is not a json file", path: resolved });
@@ -807,7 +941,7 @@ export class DefaultResourceLoader {
         }
         return { themes, diagnostics };
     }
-    loadThemesFromDir(dir, themes, diagnostics) {
+    loadThemesFromDir(dir, themes, diagnostics, colorMode) {
         if (!existsSync(dir)) {
             return;
         }
@@ -829,7 +963,7 @@ export class DefaultResourceLoader {
                 if (!entry.name.endsWith(".json")) {
                     continue;
                 }
-                this.loadThemeFromFile(join(dir, entry.name), themes, diagnostics);
+                this.loadThemeFromFile(join(dir, entry.name), themes, diagnostics, colorMode);
             }
         }
         catch (error) {
@@ -837,9 +971,9 @@ export class DefaultResourceLoader {
             diagnostics.push({ type: "warning", message, path: dir });
         }
     }
-    loadThemeFromFile(filePath, themes, diagnostics) {
+    loadThemeFromFile(filePath, themes, diagnostics, colorMode) {
         try {
-            themes.push(loadThemeFromPath(filePath));
+            themes.push(loadThemeFromPath(filePath, colorMode));
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "failed to load theme";
@@ -856,6 +990,7 @@ export class DefaultResourceLoader {
             try {
                 const extension = await loadExtensionFromFactory(factory, this.cwd, this.eventBus, runtime, extensionPath);
                 extension.hidden = isNamed && input.hidden;
+                extension.replaceable = isNamed && input.replaceable === true;
                 extensions.push(extension);
             }
             catch (error) {