@alisio/core 0.1.0-alpha.10

package/dist/application.js

@@ -0,0 +1,950 @@
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { configFile, configHome, loadConfigWithProvenance, overridesSavedProviderProfile, setConfigValue, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
+import { completeText } from "./core/compaction.js";
+import { ToolRegistry } from "./core/registry.js";
+import { AgentRunner } from "./core/runner.js";
+import { HerdrBridge } from "./integrations/herdr.js";
+import { McpConnector } from "./mcp/connector.js";
+import { discoverPlugins, PluginHost } from "./plugins/host.js";
+import { ActiveProvider, ProviderRegistry, UnconfiguredProvider } from "./providers/registry.js";
+import { availableProviderModels, resolveProviderModel as resolveConfiguredModel, } from "./providers/routing.js";
+import { ProviderSettingsStore } from "./providers/settings.js";
+import { ProjectContext } from "./resources/context.js";
+import { expandSlashPrompt, loadPromptTemplates, promptSources } from "./resources/prompts.js";
+import { Skills, skillRoots } from "./resources/skills.js";
+import { isPathSpec } from "./runtime/modules.js";
+import { findWorkspace } from "./runtime/paths.js";
+import { SQLiteStore } from "./runtime/store.js";
+import { ChildSessions } from "./sessions/children.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Cap per teardown stage of `app.close()`: exit must never wait longer than this on a hanging
+ * component (MCP server, provider, plugin). Stages run in parallel where independent and
+ * failures are swallowed, so teardown errors never replace the caller's result.
+ */
+const TEARDOWN_STAGE_TIMEOUT_MS = 2_500;
+/** A built-in runs unless its config sets `enabled: false` or it is disabled by id. */
+export function enabledBuiltins(available, config, disabled = []) {
+    for (const id of [...Object.keys(config), ...disabled])
+        if (!available.some((p) => p.id === id))
+            throw new Error(`Unknown built-in plugin: ${id}`);
+    return available.filter((p) => config[p.id]?.enabled !== false && !disabled.includes(p.id));
+}
+const nonBlank = (value) => {
+    const normalized = value?.trim();
+    return normalized || undefined;
+};
+/**
+ * Per-profile optional context-window override, in tokens (for local OpenAI-compatible servers
+ * like llama.cpp whose `GET /models` omits `context_window`). Numbers are used directly; strings
+ * (for example hand-edited providers.json) are parsed. Absent or unparseable means "no override".
+ */
+const parseProfileContextWindow = (value) => {
+    if (value === undefined)
+        return undefined;
+    const window = typeof value === "number" ? value : Number(String(value).trim());
+    return Number.isFinite(window) && window > 0 ? window : undefined;
+};
+export async function createApplication(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd()), workspace = await findWorkspace(cwd);
+    const { config, provenance: configProvenance } = await loadConfigWithProvenance(workspace, {
+        file: options.config,
+        trustProject: options.trustProject,
+        model: options.model,
+        baseURL: options.baseURL,
+        apiMode: options.apiMode,
+    });
+    // Global-only consent: `mcp.allow` is read from the user layer; the merged config never carries
+    // a project value (see loadConfigWithProvenance), so a project cannot grant itself MCP consent.
+    const mcpAllow = config.mcp.allow === true;
+    let persistedMcpAllow = mcpAllow;
+    const store = new SQLiteStore(options.db ?? join(stateHome(), "sessions.sqlite"));
+    const registry = new ToolRegistry(), skills = new Skills({ overrides: config.skillOverrides }), context = new ProjectContext(workspace, {
+        globalDir: configHome(),
+        cwd,
+        claudeMdFallback: config.context.claudeMdFallback,
+        maxBytes: config.context.maxBytes,
+    }), providers = new ProviderRegistry(), plugins = new PluginHost(registry, store, config.pluginHooks, providers), mcp = new McpConnector(config.mcp.servers, registry, workspace, options.readOnly ? "read-only" : options.allowMcp || mcpAllow ? "allowed" : "disabled", config.mcpSources);
+    let mcpRuntimePermission = options.readOnly
+        ? "read-only"
+        : options.allowMcp || mcpAllow
+            ? "granted"
+            : "not-granted";
+    const herdr = options.noHerdr
+        ? new HerdrBridge({}, async () => "")
+        : HerdrBridge.fromEnvironment(workspace, (error) => process.stderr.write(`${error}\n`));
+    try {
+        // First-party built-ins load through the trusted path, also under --read-only.
+        const builtinContext = {
+            workspace,
+            cwd,
+            stateHome: stateHome(),
+            configHome: configHome(),
+            home: homedir(),
+            trusted: !!options.trustProject || !!options.config,
+            configDir: dirname(configFile(workspace, options.config ? { file: options.config } : { trustProject: options.trustProject })),
+        };
+        const trustedProject = !!options.trustProject || !!options.config;
+        const pluginCatalog = new Map();
+        const runtimePluginEnabled = new Map();
+        const enabledBuiltinList = enabledBuiltins(options.builtins ?? [], config.builtinPlugins, options.disablePlugins);
+        const enabledBuiltinIds = new Set(enabledBuiltinList.map((item) => item.id));
+        for (const builtin of options.builtins ?? []) {
+            const enabled = enabledBuiltinIds.has(builtin.id);
+            let instance;
+            try {
+                instance = builtin.create({
+                    ...(config.builtinPlugins[builtin.id] ?? {}),
+                    ...(options.pluginOptions?.[builtin.id] ?? {}),
+                }, builtinContext);
+                if (enabled)
+                    await plugins.activate(instance, workspace, { builtin: true });
+                pluginCatalog.set(builtin.id, {
+                    id: builtin.id,
+                    name: instance.name ?? builtin.name ?? builtin.id,
+                    description: instance.description ?? builtin.description,
+                    version: instance.version,
+                    categories: instance.categories ?? builtin.categories ?? [],
+                    builtin: true,
+                    source: "built-in",
+                    status: enabled ? "active" : "inactive",
+                    enabled,
+                    manageable: !(options.disablePlugins ?? []).includes(builtin.id),
+                    ...((options.disablePlugins ?? []).includes(builtin.id)
+                        ? { diagnostic: "Disabled by command-line option" }
+                        : {}),
+                });
+                runtimePluginEnabled.set(builtin.id, enabled);
+            }
+            catch {
+                pluginCatalog.set(builtin.id, {
+                    id: builtin.id,
+                    name: instance?.name ?? builtin.name ?? builtin.id,
+                    description: instance?.description ?? builtin.description,
+                    version: instance?.version,
+                    categories: instance?.categories ?? builtin.categories ?? [],
+                    builtin: true,
+                    source: "built-in",
+                    status: "failed",
+                    enabled,
+                    manageable: true,
+                    diagnostic: "Activation failed; registrations were rolled back",
+                });
+            }
+        }
+        if (!options.readOnly) {
+            const external = [
+                ...(options.plugin ?? []).map((p) => ({
+                    spec: isPathSpec(p) ? resolve(cwd, p) : p,
+                    source: "command line",
+                    manageable: false,
+                })),
+                ...config.plugins.map((spec) => ({
+                    spec,
+                    source: options.config
+                        ? "explicit configuration"
+                        : options.trustProject
+                            ? isPathSpec(spec)
+                                ? "project configuration"
+                                : `project package: ${spec}`
+                            : "global configuration",
+                    manageable: !!options.trustProject && !options.config,
+                })),
+                ...(await discoverPlugins(join(configHome(), "plugins"))).map((spec) => ({
+                    spec,
+                    source: "global plugin directory",
+                    manageable: false,
+                })),
+                ...(options.trustProject
+                    ? (await discoverPlugins(join(workspace, ".alisio", "plugins"))).map((spec) => ({
+                        spec,
+                        source: "project plugin directory",
+                        manageable: true,
+                    }))
+                    : []),
+            ];
+            // Import is isolated from setup so configured disabled plugins remain visible in the catalog.
+            for (const entry of external.filter((candidate, index, all) => all.findIndex((x) => x.spec === candidate.spec) === index)) {
+                let candidate;
+                try {
+                    candidate = await plugins.inspect(entry.spec, { from: workspace });
+                    const enabled = config.pluginOverrides[candidate.plugin.id]?.enabled !== false;
+                    if (enabled)
+                        await plugins.activate(candidate.plugin, candidate.base);
+                    pluginCatalog.set(candidate.plugin.id, {
+                        id: candidate.plugin.id,
+                        name: candidate.plugin.name ?? candidate.plugin.id,
+                        description: candidate.plugin.description ?? "No description provided",
+                        version: candidate.plugin.version,
+                        categories: candidate.plugin.categories ??
+                            plugins.metadata().find((metadata) => metadata.id === candidate?.plugin.id)
+                                ?.categories ??
+                            [],
+                        builtin: false,
+                        source: entry.source,
+                        status: enabled ? "active" : "inactive",
+                        enabled,
+                        manageable: entry.manageable,
+                    });
+                    runtimePluginEnabled.set(candidate.plugin.id, enabled);
+                }
+                catch {
+                    if (candidate) {
+                        pluginCatalog.set(candidate.plugin.id, {
+                            id: candidate.plugin.id,
+                            name: candidate.plugin.name ?? candidate.plugin.id,
+                            description: candidate.plugin.description ?? "No description provided",
+                            version: candidate.plugin.version,
+                            categories: candidate.plugin.categories ?? [],
+                            builtin: false,
+                            source: entry.source,
+                            status: "failed",
+                            enabled: true,
+                            manageable: entry.manageable,
+                            diagnostic: "Activation failed; registrations were rolled back",
+                        });
+                        continue;
+                    }
+                    const id = `unavailable-${pluginCatalog.size + 1}`;
+                    pluginCatalog.set(id, {
+                        id,
+                        name: "Unavailable plugin",
+                        description: "Plugin metadata could not be loaded",
+                        categories: [],
+                        builtin: false,
+                        source: entry.source,
+                        status: "failed",
+                        enabled: true,
+                        manageable: false,
+                        diagnostic: "Load failed; no path or credential details are shown here",
+                    });
+                }
+            }
+        }
+        // Project skills follow the config trust model (--trust-project or an explicit --config).
+        await skills.discover(skillRoots({
+            workspace,
+            cwd,
+            home: homedir(),
+            configHome: configHome(),
+            trusted: !!options.trustProject || !!options.config,
+            configSkills: config.skills,
+            pluginRoots: plugins.skillSources,
+        }));
+        context.extras.push(async () => skills.catalog(), ...plugins.contexts);
+        const { registerStandard } = await import("./tools/standard.js");
+        // `runner` is referenced lazily (constructed just below): safe because these accessors only
+        // run once the tool is actually called, well after the runner exists.
+        registerStandard(registry, workspace, skills, context, plugins.ui, {
+            policy: () => runner.policy,
+        }, {
+            config: config.websearch,
+            resolveExtension: () => plugins.extensions.resolve("websearch"),
+        });
+        const { registerPluginInstallTool } = await import("./plugins/install.js");
+        registerPluginInstallTool(registry, { readOnly: !!options.readOnly });
+        if ((options.allowMcp || mcpAllow) && !options.readOnly)
+            mcp.register();
+        if (options.allowAgents && !options.readOnly)
+            herdr.registerTools(registry);
+        const providerSettings = new ProviderSettingsStore();
+        const saved = options.provider ? undefined : await providerSettings.active();
+        const defaultProvider = (options.builtins ?? []).find((item) => item.defaultProvider);
+        const legacyEndpointOverride = overridesSavedProviderProfile(configProvenance, !!options.baseURL ||
+            !!options.apiMode ||
+            !!process.env.OPENAI_BASE_URL ||
+            !!process.env.ALISIO_API_MODE);
+        const selectedSaved = legacyEndpointOverride ? undefined : saved;
+        const supportsNativeSearch = (id, profile) => {
+            const capability = id ? providers.get(id)?.capabilities?.nativeWebSearch : undefined;
+            return (capability === true ||
+                (typeof capability === "object" &&
+                    capability.values.includes(profile[capability.field] ?? "")));
+        };
+        let providerInfo = options.provider
+            ? { id: options.provider.id, profile: {}, persisted: false, profileName: undefined }
+            : selectedSaved
+                ? {
+                    id: selectedSaved.profile.provider,
+                    profile: selectedSaved.profile.values,
+                    persisted: true,
+                    profileName: selectedSaved.name,
+                }
+                : defaultProvider
+                    ? {
+                        id: defaultProvider.id,
+                        profile: config.provider,
+                        persisted: false,
+                        profileName: undefined,
+                    }
+                    : undefined;
+        let providerError;
+        let initial = new UnconfiguredProvider();
+        if (options.provider)
+            initial = options.provider;
+        else if (selectedSaved) {
+            try {
+                initial = await providers.create(selectedSaved.profile.provider, {
+                    profile: {
+                        ...selectedSaved.profile.values,
+                        model: nonBlank(options.model) ??
+                            nonBlank(process.env.ALISIO_MODEL) ??
+                            selectedSaved.profile.model,
+                    },
+                    credentials: selectedSaved.credentials,
+                });
+            }
+            catch (error) {
+                providerError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        else if (defaultProvider && config.provider.model) {
+            try {
+                initial = await providers.create(defaultProvider.id, {
+                    profile: {},
+                    credentials: {},
+                    legacy: config.provider,
+                });
+            }
+            catch (error) {
+                providerError = error instanceof Error ? error.message : String(error);
+            }
+        }
+        const provider = new ActiveProvider(initial);
+        if (config.websearch.provider === "native") {
+            const id = selectedSaved?.profile.provider ?? defaultProvider?.id;
+            const profile = selectedSaved
+                ? selectedSaved.profile.values
+                : config.provider;
+            if (!supportsNativeSearch(id, profile))
+                throw new Error('websearch.provider is "native" but the active provider does not support native search');
+        }
+        const models = new Map();
+        // Lazily (re)loads the active provider's catalog exactly once, so the ACTIVE model's
+        // contextWindow becomes known for the context bar without waiting for an explicit
+        // /model picker or autocomplete call. Failed or absent discovery stays retryable.
+        let modelsLoading;
+        const ensureModels = () => {
+            if (!provider.listModels || modelsLoading)
+                return modelsLoading;
+            modelsLoading = loadModels(AbortSignal.timeout(10_000));
+            modelsLoading.catch(() => {
+                if (modelsLoading)
+                    modelsLoading = undefined;
+            });
+            return modelsLoading;
+        };
+        // Priority: explicit configuration for the configured model, then the active saved profile's
+        // per-model override (user intent for local servers that omit context_window), then GET /models.
+        const contextWindow = (model) => {
+            const explicit = model === config.provider.model ? config.provider.contextWindow : undefined;
+            if (explicit !== undefined)
+                return explicit;
+            const override = providerInfo?.persisted && model === provider.model
+                ? parseProfileContextWindow(providerInfo.profile.contextWindow)
+                : undefined;
+            if (override !== undefined)
+                return override;
+            const known = models.get(model)?.contextWindow;
+            if (known !== undefined)
+                return known;
+            // Background prime: this call stays synchronous (the runner and the bar are sync), and
+            // once the catalog lands the map is populated for every later lookup.
+            void ensureModels();
+            return undefined;
+        };
+        const loadModels = async (signal) => {
+            if (!provider.listModels)
+                return [];
+            const list = await provider.listModels(signal);
+            models.clear();
+            for (const m of list)
+                models.set(m.id, m);
+            return list;
+        };
+        let catalogCache;
+        const configuredCatalogs = async (signal) => {
+            if (catalogCache && Date.now() - catalogCache.at < 15_000)
+                return catalogCache.value;
+            const settings = await providerSettings.load();
+            const value = await Promise.all(Object.entries(settings.profiles).map(async ([name, profile]) => {
+                const registration = providers.get(profile.provider);
+                const base = {
+                    profile: name,
+                    provider: profile.provider,
+                    title: registration?.name ?? profile.provider,
+                    configuredModel: profile.model,
+                };
+                if (!registration)
+                    return { ...base, models: [], unavailable: true };
+                try {
+                    const resolved = await providerSettings.resolve(name);
+                    if (!resolved)
+                        return { ...base, models: [], unavailable: true };
+                    const candidate = await providers.create(profile.provider, {
+                        profile: { ...profile.values, model: profile.model },
+                        credentials: resolved.credentials,
+                    });
+                    try {
+                        return {
+                            ...base,
+                            models: (await candidate.listModels?.(signal)) ?? [],
+                            unavailable: false,
+                        };
+                    }
+                    finally {
+                        await candidate.dispose?.();
+                    }
+                }
+                catch {
+                    return { ...base, models: [], unavailable: true };
+                }
+            })).then((catalogs) => catalogs.sort((a, b) => a.title.localeCompare(b.title)));
+            catalogCache = { at: Date.now(), value };
+            return value;
+        };
+        const listAvailableModels = async (signal = AbortSignal.timeout(20_000)) => availableProviderModels(await configuredCatalogs(signal));
+        const resolveModel = async (reference, signal = AbortSignal.timeout(20_000)) => resolveConfiguredModel(await configuredCatalogs(signal), reference);
+        const sessionProviders = new Map();
+        const targetProviders = new Map();
+        const retainedProviders = new Set();
+        const runtimeFor = (target) => {
+            const key = `${target.profile}\0${target.model.id}`;
+            let pending = targetProviders.get(key);
+            if (!pending) {
+                pending = providerSettings.resolve(target.profile).then(async (saved) => {
+                    if (!saved || saved.profile.provider !== target.provider)
+                        throw new Error(`Configured provider "${target.provider}" is unavailable. Reconnect it with /connect.`);
+                    try {
+                        return await providers.create(target.provider, {
+                            profile: { ...saved.profile.values, model: target.model.id },
+                            credentials: saved.credentials,
+                        });
+                    }
+                    catch {
+                        throw new Error(`Configured provider "${target.provider}" could not be activated. Reconnect it with /connect.`);
+                    }
+                });
+                targetProviders.set(key, pending);
+                pending.catch(() => targetProviders.delete(key));
+            }
+            return pending;
+        };
+        const bindProvider = async (sessionId, target) => {
+            const runtime = await runtimeFor(target);
+            sessionProviders.set(sessionId, runtime);
+            return runtime.id;
+        };
+        const providerFor = async (session) => {
+            const bound = sessionProviders.get(session.id);
+            if (bound)
+                return bound;
+            if (session.parentId) {
+                const parent = sessionProviders.get(session.parentId);
+                if (parent && parent.id === session.provider) {
+                    sessionProviders.set(session.id, parent);
+                    return parent;
+                }
+            }
+            const current = provider.currentProvider;
+            if (current.id === session.provider) {
+                sessionProviders.set(session.id, current);
+                retainedProviders.add(current);
+                return current;
+            }
+            // A persisted routed session may be resumed after another profile became the global default.
+            // Recreate only configured runtimes whose catalog contains the recorded model, then match the
+            // provider's stable public id. Credentials never leave this activation boundary.
+            const candidates = (await listAvailableModels()).filter((entry) => entry.model.id === session.model);
+            for (const target of candidates) {
+                const runtime = await runtimeFor(target).catch(() => undefined);
+                if (!runtime)
+                    continue;
+                if (runtime.id !== session.provider)
+                    continue;
+                sessionProviders.set(session.id, runtime);
+                return runtime;
+            }
+            throw new Error(`Session provider "${session.provider}" is unavailable. Reconnect that provider or start a new session.`);
+        };
+        plugins.setModels({ list: listAvailableModels, resolve: resolveModel });
+        plugins.setCompleter(async (request) => {
+            if (!request.model) {
+                const runtime = request.sessionId
+                    ? await providerFor(store.get(request.sessionId))
+                    : provider.currentProvider;
+                return completeText(runtime, request);
+            }
+            const target = await resolveModel(request.model, request.signal);
+            return completeText(await runtimeFor(target), { ...request, model: target.model.id });
+        });
+        const runtimePolicy = {
+            write: !!options.allowWrite && !options.readOnly,
+            process: !!options.allowProcess && !options.readOnly,
+            external: !options.readOnly &&
+                (!!options.allowExternal ||
+                    !!options.allowMcp ||
+                    mcpAllow ||
+                    !!options.allowAgents ||
+                    plugins.externalCount > 0 ||
+                    registry.list().some((t) => t.name.startsWith("p_"))),
+        };
+        const runner = new AgentRunner({
+            provider,
+            providerFor,
+            registry,
+            store,
+            context,
+            workspace,
+            policy: runtimePolicy,
+            ...config.limits,
+            compaction: config.compaction,
+            extensions: plugins,
+            contextWindow,
+            ...(options.approve && !options.readOnly ? { approve: options.approve } : {}),
+            ...(config.websearch.provider === "native"
+                ? { nativeTools: [{ type: config.websearch.nativeToolType }] }
+                : {}),
+            onEvent: (event) => {
+                herdr.event(event);
+                plugins.emit(event);
+                options.onEvent?.(event);
+            },
+        });
+        // Child sessions (generic delegation service for plugins). Contexts are cached per workspace
+        // so a child in a git worktree reads that worktree's AGENTS.md files.
+        const contexts = new Map([[workspace, context]]);
+        plugins.setSessions(new ChildSessions({
+            store,
+            runner,
+            providerId: () => provider.id,
+            resolveModel,
+            bindProvider,
+            rootPolicy: () => runner.policy,
+            rootApprovals: runner.approvals,
+            readOnly: !!options.readOnly,
+            contextFor: (root) => {
+                let found = contexts.get(root);
+                if (!found) {
+                    found = new ProjectContext(root, {
+                        globalDir: configHome(),
+                        claudeMdFallback: config.context.claudeMdFallback,
+                        maxBytes: config.context.maxBytes,
+                    });
+                    found.extras.push(...context.extras);
+                    contexts.set(root, found);
+                }
+                return found;
+            },
+        }));
+        // Project prompts follow the config trust model: --trust-project or an explicit --config.
+        const prompts = await loadPromptTemplates(promptSources({
+            builtin: options.builtinPrompts ?? [],
+            plugins: plugins.promptSources,
+            userDir: join(configHome(), "prompts"),
+            projectDir: join(workspace, ".alisio", "prompts"),
+            trusted: !!options.trustProject || !!options.config,
+        }), { reserved: [...(options.reservedPromptNames ?? []), ...plugins.commands.keys()] });
+        /**
+         * `/name args` → rendered template text, or undefined when not a template. Throws when the
+         * template requires a capability that is neither allowed nor approvable.
+         */
+        const expandPrompt = (input) => {
+            const expanded = expandSlashPrompt(input, prompts.templates);
+            if (!expanded)
+                return undefined;
+            for (const need of expanded.template.requires) {
+                const flag = need === "write" ? "--allow-write" : "--allow-process";
+                if (options.readOnly)
+                    throw new Error(`/${expanded.name} needs ${need} access, which --read-only disables. Run it without --read-only (and with ${flag}, or approve the calls in the TUI).`);
+                if (!runner.policy[need] && !runner.approvals)
+                    throw new Error(`/${expanded.name} needs ${need} access: rerun with ${flag}.`);
+            }
+            return expanded;
+        };
+        // Startup auto-connect: when runtime permission is granted (--allow-mcp or global mcp.allow),
+        // connect every enabled server exactly like pressing Connect for each. Failures are per-server,
+        // sanitized and never fatal to startup.
+        const mcpStartupFailures = [];
+        if (mcpRuntimePermission === "granted") {
+            for (const [name, server] of Object.entries(config.mcp.servers)) {
+                if (!server.enabled)
+                    continue;
+                try {
+                    await mcp.connect(name, AbortSignal.timeout(15_000));
+                }
+                catch {
+                    const diagnostic = mcp.info(name).diagnostic ??
+                        "Connection failed; inspect the server separately for details";
+                    mcpStartupFailures.push(`MCP server "${name}" did not auto-connect: ${diagnostic}`);
+                }
+            }
+        }
+        return {
+            workspace,
+            config,
+            prompts,
+            expandPrompt,
+            store,
+            registry,
+            context,
+            skills,
+            /** Path- and content-safe metadata for the interactive skills manager. */
+            skillCatalog() {
+                const pluginStatus = new Map([...pluginCatalog.values()].map((entry) => [entry.id, entry]));
+                return skills.catalogEntries().map((skill) => {
+                    const owner = skill.owner ? pluginStatus.get(skill.owner.id) : undefined;
+                    return {
+                        ...skill,
+                        ...(owner?.status === "restart-required"
+                            ? { source: "plugin (restart required)" }
+                            : {}),
+                    };
+                });
+            },
+            /** Persist a project-local override and apply it to model-visible skills immediately. */
+            async setSkillEnabled(id, enabled) {
+                const current = skills.catalogEntries().find((skill) => skill.id === id && skill.effective);
+                if (!current)
+                    throw new Error(`Unknown effective skill: ${id}`);
+                if (!current.manageable || current.locked)
+                    throw new Error("This skill is locked by its plugin; use /plugins to manage the owner");
+                await setProjectSkillEnabled({ workspace, id, enabled, trusted: trustedProject });
+                return skills.setEnabled(id, enabled);
+            },
+            plugins,
+            /** Credential- and path-safe catalog for the current resolved plugin set. */
+            pluginCatalog() {
+                return [...pluginCatalog.values()]
+                    .map((entry) => ({ ...entry, categories: [...entry.categories] }))
+                    .sort((a, b) => a.name.localeCompare(b.name));
+            },
+            /** Persist a project-local override. Runtime registrations intentionally change on restart. */
+            async setPluginEnabled(id, enabled, lifecycle = {}) {
+                const entry = pluginCatalog.get(id);
+                if (!entry)
+                    throw new Error(`Unknown plugin: ${id}`);
+                if (!entry.manageable)
+                    throw new Error(entry.diagnostic ?? "This plugin is managed outside project configuration");
+                if (!entry.builtin && !trustedProject)
+                    throw new Error("Trust this project before enabling or disabling executable plugins");
+                if (!enabled) {
+                    const activeRegistration = providers.get(providerInfo?.id ?? "");
+                    if (activeRegistration?.plugin === id)
+                        throw new Error("Switch to a model from another provider, then start a fresh session before disabling this plugin");
+                    if ([...sessionProviders.values()].some((runtime) => providers.get(runtime.id)?.plugin === id))
+                        throw new Error("A live routed session still uses this provider plugin; close those sessions or restart Alisio before disabling it");
+                    if (lifecycle.liveSession && plugins.ownsSessionResources(id))
+                        throw new Error("This plugin owns resources used by the current session; start a fresh session before disabling it");
+                }
+                if (entry.enabled === enabled && entry.status !== "restart-required")
+                    return { ...entry };
+                await setProjectPluginEnabled({
+                    workspace,
+                    id,
+                    enabled,
+                    builtin: entry.builtin,
+                    trusted: trustedProject,
+                });
+                const matchesRuntime = runtimePluginEnabled.get(id) === enabled;
+                const updated = {
+                    ...entry,
+                    enabled,
+                    status: matchesRuntime ? (enabled ? "active" : "inactive") : "restart-required",
+                    ...(matchesRuntime
+                        ? { diagnostic: undefined }
+                        : {
+                            diagnostic: enabled
+                                ? "Enabled for the next Alisio start"
+                                : "Disabled for the next Alisio start",
+                        }),
+                };
+                pluginCatalog.set(id, updated);
+                return { ...updated, categories: [...updated.categories] };
+            },
+            mcp,
+            /** Current-process MCP grant; deliberately independent from persisted server enablement. */
+            mcpRuntimePermission() {
+                return mcpRuntimePermission;
+            },
+            /** Whether global MCP consent (`mcp.allow`) is persisted for this user right now. */
+            mcpAllowPersisted() {
+                return persistedMcpAllow;
+            },
+            /**
+             * Sanitized per-server failures collected while auto-connecting enabled servers at startup
+             * (only when runtime permission was granted). Never includes credentials or command paths.
+             */
+            mcpStartupFailures() {
+                return [...mcpStartupFailures];
+            },
+            /** Host-owned interactive consent boundary. Headless callers remain blocked unless flagged. */
+            grantMcpRuntimePermission(request) {
+                if (!request.confirmed)
+                    return mcpRuntimePermission;
+                if (request.source !== "interactive-tui")
+                    throw new Error("MCP runtime permission may only be granted by the interactive TUI");
+                if (options.readOnly)
+                    throw new Error("MCP is unavailable under --read-only");
+                if (mcpRuntimePermission === "granted")
+                    return mcpRuntimePermission;
+                mcp.grantRuntimePermission();
+                runtimePolicy.external = true;
+                mcpRuntimePermission = "granted";
+                return mcpRuntimePermission;
+            },
+            /** Persist global consent atomically, then grant runtime permission for this process. */
+            async rememberGlobalMcpConsent() {
+                if (options.readOnly)
+                    throw new Error("MCP is unavailable under --read-only");
+                await setGlobalMcpAllow({ allow: true });
+                persistedMcpAllow = true;
+                this.grantMcpRuntimePermission({ source: "interactive-tui", confirmed: true });
+            },
+            /**
+             * Clear the persisted global consent atomically and drop the runtime permission (disconnecting
+             * servers as cleanup does). An explicit this-run `--allow-mcp` flag keeps the grant alive.
+             */
+            async revokeGlobalMcpConsent() {
+                if (options.readOnly)
+                    throw new Error("MCP is unavailable under --read-only");
+                await setGlobalMcpAllow({ allow: false });
+                persistedMcpAllow = false;
+                if (options.allowMcp)
+                    return;
+                if (mcpRuntimePermission !== "granted")
+                    return;
+                await mcp.revokeRuntimePermission();
+                mcpRuntimePermission = "not-granted";
+                runtimePolicy.external =
+                    !!options.allowExternal ||
+                        !!options.allowAgents ||
+                        plugins.externalCount > 0 ||
+                        registry.list().some((t) => t.name.startsWith("p_"));
+            },
+            /** Persist an MCP toggle in its defining layer, then safely update this process. */
+            async setMcpEnabled(id, enabled, connect = false) {
+                if (options.readOnly)
+                    throw new Error("MCP changes are unavailable under --read-only");
+                const source = config.mcpSources[id];
+                if (!source)
+                    throw new Error(`Unknown MCP server: ${id}`);
+                await setMcpServerEnabled({ source, name: id, enabled });
+                await mcp.setEnabled(id, enabled, connect && enabled && mcpRuntimePermission === "granted"
+                    ? AbortSignal.timeout(15_000)
+                    : undefined);
+                return mcp.info(id);
+            },
+            /**
+             * Persist one user-facing setting to the GLOBAL user config (`<config home>/config.json`)
+             * and apply it to this process where the value can change live. Compaction and limits land
+             * in the runner (honored by the next run/compact), `context.*` lands in the project context
+             * (next instructions load), `websearch.provider` mutates the shared config object the search
+             * chain reads per call, `pluginHooks.timeoutMs` lands in the plugin host (next hook call),
+             * and `tui.*` is persisted for the host to apply. Nothing in this set requires a restart.
+             * `mcp.allow` is deliberately not routed here: it flows through
+             * `rememberGlobalMcpConsent`/`revokeGlobalMcpConsent` instead.
+             * Throws under `--read-only`. Returns the written config file.
+             */
+            async updateSetting(key, value) {
+                if (options.readOnly)
+                    throw new Error("Settings changes are unavailable under --read-only");
+                const file = await setConfigValue({ key, value });
+                const compactionLeaf = (leaf) => ({ [leaf]: value });
+                const limitLeaf = (leaf) => ({ [leaf]: value });
+                switch (key) {
+                    case "compaction.auto":
+                    case "compaction.threshold":
+                    case "compaction.keepTurns":
+                    case "compaction.maxOutputTokens": {
+                        const patch = compactionLeaf(key.slice("compaction.".length));
+                        config.compaction = { ...config.compaction, ...patch };
+                        runner.applySettings({ compaction: patch });
+                        break;
+                    }
+                    case "context.claudeMdFallback":
+                        config.context = { ...config.context, claudeMdFallback: value === true };
+                        context.update({ claudeMdFallback: value === true });
+                        break;
+                    case "context.maxBytes":
+                        config.context = { ...config.context, maxBytes: Number(value) };
+                        context.update({ maxBytes: Number(value) });
+                        break;
+                    case "limits.maxTurns":
+                    case "limits.maxOutputTokens":
+                    case "limits.maxContextChars":
+                    case "limits.timeoutMs": {
+                        const patch = limitLeaf(key.slice("limits.".length));
+                        config.limits = { ...config.limits, ...patch };
+                        runner.applySettings(patch);
+                        break;
+                    }
+                    case "pluginHooks.timeoutMs":
+                        config.pluginHooks = { ...config.pluginHooks, timeoutMs: Number(value) };
+                        plugins.applyTimeoutSettings({ hookTimeoutMs: Number(value) });
+                        break;
+                    case "tui.paddingX":
+                        config.tui = { ...config.tui, paddingX: Number(value) };
+                        break;
+                    case "tui.skillSlashCommands":
+                        config.tui = { ...config.tui, skillSlashCommands: value === true };
+                        break;
+                    case "websearch.provider":
+                        // Mutated in place (same object identity) so the tool chain's per-call
+                        // `websearchCtx.config` sees the new provider on the very next search call.
+                        config.websearch.provider =
+                            value === undefined ? undefined : value;
+                        break;
+                }
+                return file;
+            },
+            provider,
+            providers,
+            providerSettings,
+            get providerError() {
+                return providerError;
+            },
+            get providerInfo() {
+                return providerInfo;
+            },
+            runner,
+            herdr,
+            contextWindow,
+            /** Effective context budget + compaction point shared by the runner and the TUI bar. */
+            contextBudget: (model) => runner.contextBudget(model),
+            loadModels,
+            /** Creates a provider for validation/model discovery without changing the active provider. */
+            async probeProvider(id, profile, credentials, signal) {
+                const candidate = await providers.create(id, { profile, credentials });
+                try {
+                    return (await candidate.listModels?.(signal)) ?? [];
+                }
+                finally {
+                    await candidate.dispose?.();
+                }
+            },
+            /** Lists every plugin-configured profile without returning credentials or provider errors. */
+            async configuredProviderCatalogs(signal) {
+                return configuredCatalogs(signal);
+            },
+            /** Lists credential-free models from globally configured `/connect` profiles. */
+            listAvailableModels,
+            /** Resolves `provider/model` or a unique bare model id without exposing credentials. */
+            resolveModel,
+            /** Creates and binds a fresh session to an optional configured model selector. */
+            async createSession(reference) {
+                if (!reference) {
+                    const session = store.create(workspace, provider.id, provider.model);
+                    sessionProviders.set(session.id, provider.currentProvider);
+                    retainedProviders.add(provider.currentProvider);
+                    return session;
+                }
+                const target = await resolveModel(reference);
+                const runtime = await runtimeFor(target);
+                const session = store.create(workspace, runtime.id, target.model.id);
+                sessionProviders.set(session.id, runtime);
+                return session;
+            },
+            /** Persists and activates only after construction succeeds; programmatic overrides stay fixed. */
+            async activateProvider(id, profile, credentials, model, profileName = id) {
+                if (options.provider)
+                    throw new Error("A programmatic provider override is active");
+                if (config.websearch.provider === "native" && !supportsNativeSearch(id, profile))
+                    throw new Error("The selected provider configuration does not support native web search");
+                const candidate = await providers.create(id, {
+                    profile: { ...profile, model },
+                    credentials,
+                });
+                try {
+                    await providerSettings.saveActive(profileName, { provider: id, values: profile, model }, credentials);
+                    const previous = provider.currentProvider;
+                    const retained = retainedProviders.has(previous);
+                    await provider.replace(candidate, !retained);
+                    providerError = undefined;
+                    providerInfo = { id, profile, persisted: true, profileName };
+                    models.clear();
+                    modelsLoading = undefined;
+                    catalogCache = undefined;
+                }
+                catch (error) {
+                    await Promise.resolve(candidate.dispose?.()).catch(() => { });
+                    throw error;
+                }
+            },
+            /** Activates a stored profile without exposing its credentials. Returns false for a no-op. */
+            async activateProviderProfile(name, model) {
+                const saved = await providerSettings.resolve(name);
+                if (!saved)
+                    throw new Error("Configured provider profile is unavailable");
+                if (providerInfo?.persisted &&
+                    saved.name === providerInfo.profileName &&
+                    saved.profile.provider === providerInfo.id &&
+                    provider.model === model)
+                    return false;
+                await this.activateProvider(saved.profile.provider, saved.profile.values, saved.credentials, model, saved.name);
+                return true;
+            },
+            /** Resolves, globally activates, and creates the fresh session required by a main switch. */
+            async switchModel(reference) {
+                const target = await resolveModel(reference);
+                const changed = await this.activateProviderProfile(target.profile, target.model.id);
+                if (!changed)
+                    return undefined;
+                return this.createSession(target.reference);
+            },
+            /** Runs session-end plugin hooks (bounded by the host timeout). */
+            async endSession(sessionId, reason) {
+                if (!plugins.hasSessionEndHooks)
+                    return { failures: [] };
+                const session = store.get(sessionId);
+                return plugins.sessionEnd({
+                    sessionId,
+                    model: session.model,
+                    workspace,
+                    reason,
+                    messages: store.messages(sessionId),
+                });
+            },
+            async close() {
+                // Exit latency is user-facing: tear down herdr + MCP in parallel, then provider +
+                // plugins (store last). Every stage is raced against a cap so a single hanging
+                // component cannot stall /exit; teardown errors are swallowed for callers.
+                const capped = (work) => Promise.race([work.catch(() => { }), delay(TEARDOWN_STAGE_TIMEOUT_MS)]);
+                try {
+                    await capped(Promise.allSettled([herdr.close(), mcp.close()]));
+                }
+                finally {
+                    try {
+                        await capped((async () => {
+                            const runtimes = new Set([
+                                ...(await Promise.allSettled(targetProviders.values()))
+                                    .filter((x) => x.status === "fulfilled")
+                                    .map((x) => x.value),
+                                ...retainedProviders,
+                            ]);
+                            await Promise.allSettled([
+                                provider.dispose(),
+                                ...[...runtimes]
+                                    .filter((runtime) => runtime !== provider.currentProvider)
+                                    .map((runtime) => Promise.resolve(runtime.dispose?.())),
+                                plugins.close(),
+                            ]);
+                        })());
+                    }
+                    finally {
+                        store.close();
+                    }
+                }
+            },
+        };
+    }
+    catch (e) {
+        await Promise.race([
+            Promise.allSettled([herdr.close(), mcp.close(), plugins.close()]),
+            delay(TEARDOWN_STAGE_TIMEOUT_MS),
+        ]);
+        store.close();
+        throw e;
+    }
+}