@alisio/core 0.1.0-alpha.5 → 0.1.0-alpha.6

package/dist/application.d.ts

@@ -1,4 +1,4 @@
-import type { AvailableProviderModel, ModelInfo, ModelProvider, Plugin, PluginCategory, ResolvedProviderModel, RunEvent } from "@alisio/sdk";
+import type { AvailableProviderModel, ModelInfo, ModelProvider, Plugin, PluginCategory, ProviderConfigurationValue, ResolvedProviderModel, RunEvent } from "@alisio/sdk";
 import type { ApprovalHandler } from "./core/contracts.ts";
 import { ToolRegistry } from "./core/registry.ts";
 import { AgentRunner } from "./core/runner.ts";
@@ -142,11 +142,25 @@ export declare function createApplication(options?: AppOptions): Promise<{
     mcp: McpConnector;
     /** Current-process MCP grant; deliberately independent from persisted server enablement. */
     mcpRuntimePermission(): "granted" | "not-granted" | "read-only";
+    /** Whether global MCP consent (`mcp.allow`) is persisted for this user right now. */
+    mcpAllowPersisted(): boolean;
+    /**
+     * 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(): string[];
     /** Host-owned interactive consent boundary. Headless callers remain blocked unless flagged. */
     grantMcpRuntimePermission(request: {
         source: "interactive-tui";
         confirmed: boolean;
     }): "granted" | "not-granted" | "read-only";
+    /** Persist global consent atomically, then grant runtime permission for this process. */
+    rememberGlobalMcpConsent(): Promise<void>;
+    /**
+     * 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.
+     */
+    revokeGlobalMcpConsent(): Promise<void>;
     /** Persist an MCP toggle in its defining layer, then safely update this process. */
     setMcpEnabled(id: string, enabled: boolean, connect?: boolean): Promise<import("./index.ts").McpServerInfo>;
     provider: ActiveProvider;
@@ -155,7 +169,7 @@ export declare function createApplication(options?: AppOptions): Promise<{
     readonly providerError: string | undefined;
     readonly providerInfo: {
         id: string;
-        profile: Record<string, import("@alisio/sdk").ProviderConfigurationValue>;
+        profile: Record<string, ProviderConfigurationValue>;
         persisted: boolean;
         profileName: string;
     } | {
@@ -169,8 +183,8 @@ export declare function createApplication(options?: AppOptions): Promise<{
     contextWindow: (model: string) => number | undefined;
     /** Effective context budget + compaction point shared by the runner and the TUI bar. */
     contextBudget: (model: string) => {
-        total: number;
-        basis: "window" | "chars";
+        total?: number;
+        basis: "window" | "unknown";
         compactionAt: number;
     };
     loadModels: (signal: AbortSignal) => Promise<ModelInfo[]>;

package/dist/application.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { configFile, configHome, loadConfigWithProvenance, overridesSavedProviderProfile, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
+import { configFile, configHome, loadConfigWithProvenance, overridesSavedProviderProfile, 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";
@@ -28,6 +28,17 @@ 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, {
@@ -37,16 +48,20 @@ export async function createApplication(options = {}) {
         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 ? "allowed" : "disabled", config.mcpSources);
+    }), 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
+        : options.allowMcp || mcpAllow
             ? "granted"
             : "not-granted";
     const herdr = options.noHerdr
@@ -220,7 +235,9 @@ export async function createApplication(options = {}) {
             config: config.websearch,
             resolveExtension: () => plugins.extensions.resolve("websearch"),
         });
-        if (options.allowMcp && !options.readOnly)
+        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);
@@ -297,9 +314,39 @@ export async function createApplication(options = {}) {
                 throw new Error('websearch.provider is "native" but the active provider does not support native search');
         }
         const models = new Map();
-        // Priority: explicit configuration for the configured model, then GET /models.
-        const contextWindow = (model) => (model === config.provider.model ? config.provider.contextWindow : undefined) ??
-            models.get(model)?.contextWindow;
+        // 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 [];
@@ -431,6 +478,7 @@ export async function createApplication(options = {}) {
             external: !options.readOnly &&
                 (!!options.allowExternal ||
                     !!options.allowMcp ||
+                    mcpAllow ||
                     !!options.allowAgents ||
                     plugins.externalCount > 0 ||
                     registry.list().some((t) => t.name.startsWith("p_"))),
@@ -508,6 +556,24 @@ export async function createApplication(options = {}) {
             }
             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,
@@ -595,6 +661,17 @@ export async function createApplication(options = {}) {
             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)
@@ -610,6 +687,35 @@ export async function createApplication(options = {}) {
                 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)
@@ -688,6 +794,7 @@ export async function createApplication(options = {}) {
                     providerError = undefined;
                     providerInfo = { id, profile, persisted: true, profileName };
                     models.clear();
+                    modelsLoading = undefined;
                     catalogCache = undefined;
                 }
                 catch (error) {

package/dist/config.d.ts

@@ -85,6 +85,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
             enabled: boolean;
             bearerTokenEnv?: string | undefined;
         }>>]>>>;
+        allow: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
         transport: z.ZodLiteral<"stdio">;
@@ -223,6 +224,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
         maxTokens?: number | undefined;
     };
     mcp: {
+        allow?: boolean | undefined;
         servers: {
             [x: string]: {
                 transport: "stdio";
@@ -294,6 +296,7 @@ export declare const configSchema: z.ZodPipe<z.ZodObject<{
             bearerTokenEnv?: string | undefined;
             transport: "http";
         }>;
+        allow?: boolean | undefined;
     };
     mcpServers?: Record<string, {
         transport: "stdio";
@@ -376,7 +379,11 @@ export interface ConfigLoadResult {
     config: LoadedConfig;
     provenance: ConfigProvenance;
 }
-/** Whether legacy provider selection should take priority over a saved plugin profile for this run. */
+/**
+ * Whether legacy provider selection should take priority over a saved plugin profile for this
+ * run: an explicit endpoint override, or a trusted project/explicit layer whose parsed root
+ * `provider.model` is actually usable (non-empty and not the `alisio setup` placeholder).
+ */
 export declare function overridesSavedProviderProfile(provenance: ConfigProvenance, hasEndpointOverride: boolean): boolean;
 export declare const configHome: () => string;
 export declare const stateHome: () => string;
@@ -405,6 +412,10 @@ export declare function setMcpServerEnabled(input: {
     name: string;
     enabled: boolean;
 }): Promise<string>;
+/** Atomically sets or clears the global `mcp.allow` consent preference in the user config file. */
+export declare function setGlobalMcpAllow(input: {
+    allow: boolean;
+}): Promise<string>;
 /** Atomically updates one project plugin override while preserving every unrelated JSON field. */
 export declare function setProjectPluginEnabled(input: {
     workspace: string;

package/dist/config.js

@@ -84,7 +84,14 @@ const configObjectSchema = z
     /** Project-local enable/disable overrides for effective non-plugin skills. */
     skillOverrides: z.record(z.string(), z.object({ enabled: z.boolean() }).strict()).default({}),
     mcp: z
-        .object({ servers: serversSchema(compatibleServerSchema).default({}) })
+        .object({
+        servers: serversSchema(compatibleServerSchema).default({}),
+        /**
+         * Global-only user preference: grants MCP process/network consent across sessions.
+         * Only the user (global) configuration layer is consulted; a project value is ignored.
+         */
+        allow: z.boolean().optional(),
+    })
         .strict()
         .default({ servers: {} }),
     /** Compatibility with the common MCP client configuration shape. */
@@ -172,9 +179,24 @@ const configObjectSchema = z
 });
 export const configSchema = configObjectSchema.transform(({ mcpServers, ...config }) => ({
     ...config,
-    mcp: { servers: { ...config.mcp.servers, ...mcpServers } },
+    mcp: { ...config.mcp, servers: { ...config.mcp.servers, ...mcpServers } },
 }));
-/** Whether legacy provider selection should take priority over a saved plugin profile for this run. */
+/** The `alisio setup` scaffold writes this placeholder; a model matching it is not usable. */
+const LEGACY_PROVIDER_MODEL_PLACEHOLDER = "YOUR_MODEL_ID";
+/**
+ * A legacy root `provider` is usable only when its parsed model is non-empty and not the
+ * `alisio setup` placeholder, so a scaffolded or empty project config never defeats a saved
+ * `/connect` profile.
+ */
+function isUsableLegacyModel(model) {
+    const normalized = model.trim();
+    return normalized !== "" && normalized !== LEGACY_PROVIDER_MODEL_PLACEHOLDER;
+}
+/**
+ * Whether legacy provider selection should take priority over a saved plugin profile for this
+ * run: an explicit endpoint override, or a trusted project/explicit layer whose parsed root
+ * `provider.model` is actually usable (non-empty and not the `alisio setup` placeholder).
+ */
 export function overridesSavedProviderProfile(provenance, hasEndpointOverride) {
     return hasEndpointOverride || !!provenance.selectedLayer?.hasLegacyProvider;
 }
@@ -233,10 +255,12 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
     global.config.skillOverrides = {};
     let config = global.config;
     let mcpSources = global.sources;
-    let selectedKeys;
+    // Parsed `provider.model` of the selected layer itself (before env/CLI overrides), used to
+    // decide whether its legacy root `provider` is usable against a saved `/connect` profile.
+    let selectedLegacyModel = "";
     if (selectedFile && selectedFile !== globalFile) {
         const selected = await parseLayer(selectedFile, options.file ? "explicit" : "project");
-        selectedKeys = selected.keys;
+        selectedLegacyModel = selected.config.provider.model;
         const overlaid = { ...config };
         for (const key of selected.keys) {
             if (key === "mcp" || key === "mcpServers")
@@ -245,14 +269,17 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
                 overlaid[key] = selected.config[key];
         }
         if (selected.keys.has("mcp") || selected.keys.has("mcpServers"))
+            // Only servers merge upward; `mcp.allow` is a global/user preference and is deliberately
+            // dropped from the selected layer so a project can never grant itself network consent.
             overlaid.mcp = {
+                ...config.mcp,
                 servers: { ...config.mcp.servers, ...selected.config.mcp.servers },
             };
         mcpSources = { ...mcpSources, ...selected.sources };
         config = overlaid;
     }
     else if (selectedFile) {
-        selectedKeys = global.keys;
+        selectedLegacyModel = global.config.provider.model;
     }
     config.provider = providerSchema.parse({
         ...config.provider,
@@ -273,7 +300,7 @@ export async function loadConfigWithProvenance(workspace, options = {}) {
                 ? {
                     selectedLayer: {
                         kind: options.file ? "explicit" : "project",
-                        hasLegacyProvider: selectedKeys?.has("provider") ?? false,
+                        hasLegacyProvider: isUsableLegacyModel(selectedLegacyModel),
                     },
                 }
                 : {}),
@@ -326,6 +353,51 @@ export async function setMcpServerEnabled(input) {
     }
     return file;
 }
+/** Atomically sets or clears the global `mcp.allow` consent preference in the user config file. */
+export async function setGlobalMcpAllow(input) {
+    const file = join(configHome(), "config.json");
+    let raw = {};
+    if (await exists(file)) {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("Global Alisio configuration must be a JSON object");
+        raw = parsed;
+    }
+    if (input.allow) {
+        const current = raw.mcp && typeof raw.mcp === "object" && !Array.isArray(raw.mcp)
+            ? raw.mcp
+            : {};
+        raw.mcp = { ...current, allow: true };
+    }
+    else if (raw.mcp && typeof raw.mcp === "object" && !Array.isArray(raw.mcp)) {
+        const mcp = { ...raw.mcp };
+        delete mcp.allow;
+        if (Object.keys(mcp).length)
+            raw.mcp = mcp;
+        else
+            delete raw.mcp;
+    }
+    raw.schemaVersion ??= 1;
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(raw, null, 2)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, file);
+        await chmod(file, 0o600);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => { });
+        throw error;
+    }
+    return file;
+}
 /** Atomically updates one project plugin override while preserving every unrelated JSON field. */
 export async function setProjectPluginEnabled(input) {
     const file = join(input.workspace, ".alisio", "config.json");

package/dist/core/runner.d.ts

@@ -108,14 +108,16 @@ export declare class AgentRunner {
     /** Estimated tokens the next request of a session would send. */
     estimateContext(sessionId: string): Promise<number>;
     /**
-     * The effective context budget a session's auto-compaction and the TUI context bar both use:
-     * the model window when known (and not beyond `MAX_TRUSTED_WINDOW`), otherwise the char budget
-     * converted to estimated tokens. `compactionAt` is the percentage of `total` where auto
-     * compaction triggers, so the bar turns red exactly where the engine compacts.
+     * The effective context budget the TUI context bar displays. The model window is the total
+     * when known (and not beyond `MAX_TRUSTED_WINDOW`); otherwise the bar reports an honest
+     * unknown (`basis: "unknown"`, no fabricated total). `compactionAt` is the percentage of
+     * `total` where auto-compaction triggers, so the bar turns red exactly where the engine
+     * compacts. The engine's own auto-compaction guardrail still falls back to the char budget
+     * internally (see `shouldCompactContext`) — that fallback is never shown as a fake total.
      */
     contextBudget(model: string): {
-        total: number;
-        basis: "window" | "chars";
+        total?: number;
+        basis: "window" | "unknown";
         compactionAt: number;
     };
     /** Change the model used by subsequent turns of a session; recorded in the store. */

package/dist/core/runner.js

@@ -1,5 +1,5 @@
 import { textResult, } from "@alisio/sdk";
-import { checkpointInstructions, effectiveContextBudget, estimateTokens, parseCheckpointOutput, planCompaction, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
 /**
  * Default cumulative token budget for one run: several context windows (each turn re-sends the
  * context), clamped; 1M tokens when the window is unknown.
@@ -112,19 +112,22 @@ export class AgentRunner {
             estimateTokens(this.toolsText(this.availableTools())));
     }
     /**
-     * The effective context budget a session's auto-compaction and the TUI context bar both use:
-     * the model window when known (and not beyond `MAX_TRUSTED_WINDOW`), otherwise the char budget
-     * converted to estimated tokens. `compactionAt` is the percentage of `total` where auto
-     * compaction triggers, so the bar turns red exactly where the engine compacts.
+     * The effective context budget the TUI context bar displays. The model window is the total
+     * when known (and not beyond `MAX_TRUSTED_WINDOW`); otherwise the bar reports an honest
+     * unknown (`basis: "unknown"`, no fabricated total). `compactionAt` is the percentage of
+     * `total` where auto-compaction triggers, so the bar turns red exactly where the engine
+     * compacts. The engine's own auto-compaction guardrail still falls back to the char budget
+     * internally (see `shouldCompactContext`) — that fallback is never shown as a fake total.
      */
     contextBudget(model) {
-        const budget = effectiveContextBudget(this.options.contextWindow?.(model), this.options.maxContextChars ?? 160_000);
-        return {
-            ...budget,
-            compactionAt: budget.basis === "window"
-                ? Math.round((this.options.compaction?.threshold ?? 0.85) * 100)
-                : 100,
-        };
+        const window = this.options.contextWindow?.(model);
+        if (window !== undefined && window > 0 && window <= MAX_TRUSTED_WINDOW)
+            return {
+                total: window,
+                basis: "window",
+                compactionAt: Math.round((this.options.compaction?.threshold ?? 0.85) * 100),
+            };
+        return { total: undefined, basis: "unknown", compactionAt: 100 };
     }
     /** Change the model used by subsequent turns of a session; recorded in the store. */
     setModel(sessionId, model) {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** @alisio/core public API: embed the Alisio agent programmatically. */
 export * from "@alisio/sdk";
 export { type AppOptions, type BuiltinContext, type BuiltinPlugin, createApplication, enabledBuiltins, type PluginCatalogEntry, type PluginCatalogStatus, } from "./application.ts";
-export { type Config, type ConfigLoadResult, type ConfigProvenance, configFile, configHome, configSchema, type LoadedConfig, loadConfig, loadConfigWithProvenance, type McpServerSource, overridesSavedProviderProfile, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.ts";
+export { type Config, type ConfigLoadResult, type ConfigProvenance, configFile, configHome, configSchema, type LoadedConfig, loadConfig, loadConfigWithProvenance, type McpServerSource, overridesSavedProviderProfile, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.ts";
 export { type ContextBudget, checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.ts";
 export type { ApprovalDecision, ApprovalHandler, ApprovalRequest, ContextSource, HookFailure, Policy, RunnerExtensions, Session, SessionStore, } from "./core/contracts.ts";
 export { ToolRegistry } from "./core/registry.ts";
@@ -10,6 +10,7 @@ export { type ExtensionConflict, ExtensionRegistry } from "./extensions/registry
 export { HerdrBridge } from "./integrations/herdr.ts";
 export { McpConnector, type McpServerInfo, type McpStatus, type McpToolInfo, } from "./mcp/connector.ts";
 export { discoverPlugins, PluginHost, type PluginHostOptions, pluginPrefix, } from "./plugins/host.ts";
+export { type CliInstallOptions, cliInstall, INSTALL_TIMEOUT_MS, type InstallPluginInput, type InstallPluginResult, type InstallRunner, installedNpmPlugins, installPlugin, npmInstallTarget, type PluginSpec, parsePluginSpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, } from "./plugins/install.ts";
 export { ActiveProvider, ProviderRegistry, UnconfiguredProvider } from "./providers/registry.ts";
 export { availableProviderModels, type ProviderModelCatalog, resolveProviderModel, } from "./providers/routing.ts";
 export { type ProviderProfile, type ProviderSettings, ProviderSettingsStore, } from "./providers/settings.ts";
@@ -19,7 +20,7 @@ export { type Skill, type SkillCatalogEntry, type SkillRoot, type SkillScope, Sk
 export { exists, fileSize, readHead, readJson, readText, which } from "./runtime/fs.ts";
 export { defaultGlobalRoots, isPathSpec, PLUGIN_KEYWORD, resolvePluginSpec, } from "./runtime/modules.ts";
 export { findWorkspace, safePath } from "./runtime/paths.ts";
-export { type ProcessResult, runProcess } from "./runtime/process.ts";
+export { isMissingCommand, type ProcessResult, RIPGREP_INSTALL_HINT, runProcess, } from "./runtime/process.ts";
 export { isSqliteExperimentalWarning, openDatabase } from "./runtime/sqlite.ts";
 export { SQLiteStore } from "./runtime/store.ts";
 export { ChildSessions, type ChildSessionsOptions } from "./sessions/children.ts";

package/dist/index.js

@@ -1,7 +1,7 @@
 /** @alisio/core public API: embed the Alisio agent programmatically. */
 export * from "@alisio/sdk";
 export { createApplication, enabledBuiltins, } from "./application.js";
-export { configFile, configHome, configSchema, loadConfig, loadConfigWithProvenance, overridesSavedProviderProfile, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
+export { configFile, configHome, configSchema, loadConfig, loadConfigWithProvenance, overridesSavedProviderProfile, setGlobalMcpAllow, setMcpServerEnabled, setProjectPluginEnabled, setProjectSkillEnabled, stateHome, } from "./config.js";
 export { checkpointInstructions, completeText, effectiveContextBudget, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, renderCheckpoint, serializeForSummary, shouldCompact, shouldCompactContext, summarize, } from "./core/compaction.js";
 export { ToolRegistry } from "./core/registry.js";
 export { AgentRunner, defaultTokenBudget, } from "./core/runner.js";
@@ -9,6 +9,7 @@ export { ExtensionRegistry } from "./extensions/registry.js";
 export { HerdrBridge } from "./integrations/herdr.js";
 export { McpConnector, } from "./mcp/connector.js";
 export { discoverPlugins, PluginHost, pluginPrefix, } from "./plugins/host.js";
+export { cliInstall, INSTALL_TIMEOUT_MS, installedNpmPlugins, installPlugin, npmInstallTarget, parsePluginSpec, pluginTrustRemark, printInstallResult, registerPluginInstallTool, sanitizeNpmError, } from "./plugins/install.js";
 export { ActiveProvider, ProviderRegistry, UnconfiguredProvider } from "./providers/registry.js";
 export { availableProviderModels, resolveProviderModel, } from "./providers/routing.js";
 export { ProviderSettingsStore, } from "./providers/settings.js";
@@ -18,7 +19,7 @@ export { Skills, skillRoots, } from "./resources/skills.js";
 export { exists, fileSize, readHead, readJson, readText, which } from "./runtime/fs.js";
 export { defaultGlobalRoots, isPathSpec, PLUGIN_KEYWORD, resolvePluginSpec, } from "./runtime/modules.js";
 export { findWorkspace, safePath } from "./runtime/paths.js";
-export { runProcess } from "./runtime/process.js";
+export { isMissingCommand, RIPGREP_INSTALL_HINT, runProcess, } from "./runtime/process.js";
 export { isSqliteExperimentalWarning, openDatabase } from "./runtime/sqlite.js";
 export { SQLiteStore } from "./runtime/store.js";
 export { ChildSessions } from "./sessions/children.js";

package/dist/mcp/connector.d.ts

@@ -48,6 +48,8 @@ export declare class McpConnector {
     constructor(servers: Record<string, ServerConfig>, registry: ToolRegistry, workspace: string, availability?: "allowed" | "disabled" | "read-only", sources?: Record<string, McpServerSource>);
     register(): void;
     grantRuntimePermission(): void;
+    /** Drop the runtime grant: disconnect every server and unregister the bridge (used on revoke). */
+    revokeRuntimePermission(): Promise<void>;
     runtimePermission(): McpServerInfo["runtimePermission"];
     private assertAvailable;
     private client;

package/dist/mcp/connector.js

@@ -3,6 +3,7 @@ import { textResult } from "@alisio/sdk";
 import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
 import { objectSchema } from "../tools/standard.js";
+import { loadVersion } from "../version.js";
 const TOOL_NAME_LIMIT = 64;
 const semanticSegment = (value, fallback) => value
     .normalize("NFKD")
@@ -138,6 +139,13 @@ export class McpConnector {
         this.availability = "allowed";
         this.register();
     }
+    /** Drop the runtime grant: disconnect every server and unregister the bridge (used on revoke). */
+    async revokeRuntimePermission() {
+        await Promise.all([...this.clients.keys()].map((name) => this.disconnect(name)));
+        for (const undo of this.bridgeUndo.splice(0).reverse())
+            undo();
+        this.availability = "disabled";
+    }
     runtimePermission() {
         return this.availability === "allowed"
             ? "granted"
@@ -212,7 +220,7 @@ export class McpConnector {
         }
         this.statuses.set(name, "connecting");
         this.diagnostics.delete(name);
-        const client = new Client({ name: "alisio", version: "0.1.0-alpha.1" }, { capabilities: {} });
+        const client = new Client({ name: "alisio", version: loadVersion(import.meta.url) }, { capabilities: {} });
         const undo = [];
         const generation = Symbol(name);
         const transport = config.transport === "stdio"

package/dist/plugins/host.js

@@ -566,7 +566,13 @@ export async function discoverPlugins(root) {
         throw e;
     }
     return entries
-        .filter((e) => (e.isFile() && /\.[cm]?[jt]s$/.test(e.name)) || e.isDirectory())
+        .filter(
+    // A root may hold an `npm install --prefix` layout (`node_modules`, package.json/lock);
+    // npm packages there are resolved through the configured `plugins` array instead.
+    (e) => e.name !== "node_modules" &&
+        e.name !== "package.json" &&
+        e.name !== "package-lock.json" &&
+        ((e.isFile() && /\.[cm]?[jt]s$/.test(e.name)) || e.isDirectory()))
         .map((e) => join(root, e.name))
         .sort();
 }

package/dist/plugins/install.d.ts

@@ -0,0 +1,100 @@
+import type { ToolRegistry } from "../core/registry.ts";
+import { type ProcessResult } from "../runtime/process.ts";
+export interface PluginSpec {
+    name: string;
+    version?: string;
+}
+/**
+ * Validates an install spec without touching the network: `npm:<package>[@<version>]` (canonical),
+ * a bare package name (same resolution), and nothing else. Rejects shell metacharacters, `..` /
+ * absolute paths, and unknown prefixes (`registry:`, `git:`, `file:`, URLs) with a clear error.
+ */
+export declare function parsePluginSpec(spec: string): PluginSpec;
+/** The npm argument for a spec: `name`, `name@<version>` or `name@latest` for `--update`. */
+export declare function npmInstallTarget(name: string, version?: string, update?: boolean): string;
+/**
+ * Injectable process runner so tests can substitute a fake `npm` without a network or a PATH shim.
+ * The default runs the real npm with a generous timeout and bounded output.
+ */
+export type InstallRunner = (command: string, args: string[], options: {
+    cwd: string;
+    signal: AbortSignal;
+    env?: Record<string, string>;
+}) => Promise<ProcessResult>;
+export declare const INSTALL_TIMEOUT_MS = 300000;
+export interface InstallPluginInput {
+    /** `npm:<package>[@<version>]` or a bare package name. */
+    spec: string;
+    /** Defaults to `configHome()` (ALISIO_CONFIG_HOME, else ~/.config/alisio). */
+    configHome?: string;
+    /** Refresh an already-installed package to `@latest`, keeping the npm name in the config. */
+    update?: boolean;
+    /** Refuse immediately; loading and installing executable plugins is disabled under --read-only. */
+    readOnly?: boolean;
+    signal?: AbortSignal;
+    /** Injected installer for tests (fake npm); defaults to the real npm. */
+    runner?: InstallRunner;
+}
+export interface InstallPluginResult {
+    packageName: string;
+    /** Version read back from the installed package.json, or "unknown". */
+    installedVersion: string;
+    /** `<configHome>/plugins/node_modules/<name>` (a directory). */
+    path: string;
+    /** The npm name persisted in the global configuration `plugins` array. */
+    configEntry: string;
+    /** The global configuration file that received the entry. */
+    configFile: string;
+    pluginsDir: string;
+    /** Already present in the global plugins directory before this call (no npm run performed). */
+    alreadyInstalled: boolean;
+    /** Refreshed to `@latest` by this call. */
+    updated: boolean;
+    /** Plain-text remark about where the plugin loads and how project trust applies. */
+    trustRemark: string;
+}
+/**
+ * Redacts probable secrets from npm output (auth tokens, JWTs, bearer credentials, userinfo in
+ * URLs) and caps the size, so a failing install never echoes credentials to the user.
+ */
+export declare function sanitizeNpmError(text: string, maxLength?: number): string;
+/** The shared install routine used by both the CLI command and the `plugin_install` tool. */
+export declare function installPlugin(input: InstallPluginInput): Promise<InstallPluginResult>;
+/** Final remark about loading and project trust, printed by the CLI and returned by the tool. */
+export declare function pluginTrustRemark(name: string): string;
+export interface CliInstallOptions {
+    spec: string;
+    configHome?: string;
+    /** `--yes`/`--trust-plugin`: skip the interactive pre-install confirmation. */
+    yes?: boolean;
+    update?: boolean;
+    readOnly?: boolean;
+    /** True when the CLI can prompt (interactive TTY, not --json). */
+    interactive?: boolean;
+    /** Print the result as JSON instead of human lines. */
+    json?: boolean;
+    signal?: AbortSignal;
+    runner?: InstallRunner;
+    /** Injectable confirmation for the interactive path (tests); defaults to a readline prompt. */
+    confirm?: () => Promise<boolean>;
+}
+export declare function cliInstall(options: CliInstallOptions): Promise<InstallPluginResult>;
+export declare function printInstallResult(result: InstallPluginResult, options?: {
+    json?: boolean;
+}): void;
+/**
+ * Registers the host-owned `plugin_install` tool (agent capability). It has process effect so it
+ * goes through the existing write/process/external permission gate (TUI approval or
+ * `--allow-process`; never available under `--read-only`, where it is not registered at all).
+ */
+export declare function registerPluginInstallTool(registry: ToolRegistry, options?: {
+    readOnly?: boolean;
+    configHome?: string;
+    runner?: InstallRunner;
+}): void;
+/**
+ * Lists npm packages installed under `<root>/node_modules` that declare the `alisio-plugin`
+ * keyword — the same packages `plugins`-array entries resolve to. Used by `alisio plugins list`
+ * so an installed package shows up alongside file/directory plugins.
+ */
+export declare function installedNpmPlugins(root: string): Promise<string[]>;

package/dist/plugins/install.js

@@ -0,0 +1,322 @@
+/**
+ * Installer for npm plugin packages: `alisio install npm:<package>[@<version>]`.
+ *
+ * One shared routine (`installPlugin`) backs both the CLI command (`cliInstall`) and the
+ * host-owned `plugin_install` tool for the agent, so the two can never drift apart. The install
+ * target is the GLOBAL plugins directory `<configHome>/plugins` (default `~/.config/alisio/plugins`),
+ * installed with `npm install --prefix`; the package NAME is persisted in the global configuration
+ * `plugins` array (never the resolved filesystem path), keeping entries portable. Loading the plugin
+ * still follows the existing executable-plugin policy: it runs in-process wherever it is loaded and
+ * is disabled entirely under `--read-only`.
+ */
+import { chmod, mkdir, open, readdir, rename, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { textResult } from "@alisio/sdk";
+import { configHome } from "../config.js";
+import { readJson } from "../runtime/fs.js";
+import { PLUGIN_KEYWORD } from "../runtime/modules.js";
+import { runProcess } from "../runtime/process.js";
+/** npm package name: scope (optional) followed by the name; both start with an alphanumeric. */
+const PACKAGE_PART = "[A-Za-z0-9][A-Za-z0-9._-]*";
+const NAME_RE = new RegExp(`^(?:@${PACKAGE_PART}\\/)?${PACKAGE_PART}$`);
+/** Version specifier: npm's `@<version>` part, restricted to the same safe character set. */
+const VERSION_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Validates an install spec without touching the network: `npm:<package>[@<version>]` (canonical),
+ * a bare package name (same resolution), and nothing else. Rejects shell metacharacters, `..` /
+ * absolute paths, and unknown prefixes (`registry:`, `git:`, `file:`, URLs) with a clear error.
+ */
+export function parsePluginSpec(spec) {
+    if (!spec || !spec.trim())
+        throw new Error("Plugin spec is empty: use npm:<package>[@<version>] or a bare package name, for example npm:plugin-openrouter");
+    const trimmed = spec.trim();
+    let rest = trimmed;
+    if (trimmed.startsWith("npm:"))
+        rest = trimmed.slice(4);
+    else {
+        const colon = trimmed.indexOf(":");
+        if (colon >= 0)
+            throw new Error(`Unsupported plugin spec prefix "${trimmed.slice(0, colon)}:": only npm:<package>[@<version>] ` +
+                `or a bare package name is supported (registry:/git:/file:/http: specs are not)` +
+                (trimmed.startsWith("registry:")
+                    ? "; pass the package name directly instead of a registry URL"
+                    : ""));
+    }
+    if (!rest)
+        throw new Error(`Plugin spec "${spec}" has no package name`);
+    const at = rest.lastIndexOf("@");
+    let name = rest;
+    let version;
+    if (at > 0) {
+        name = rest.slice(0, at);
+        version = rest.slice(at + 1);
+    }
+    if (name.length > 214)
+        throw new Error(`Invalid plugin spec "${spec}": package name is too long`);
+    if (!NAME_RE.test(name) || name.includes(".."))
+        throw new Error(`Invalid plugin package name "${name}" in spec "${spec}": allowed characters are letters, ` +
+            `digits, dot, underscore and dash, with "/" only for a scoped name and "@" only for a version; ` +
+            `names may not start with "." or "_" and may not contain ".."`);
+    if (version !== undefined && !VERSION_RE.test(version))
+        throw new Error(`Invalid plugin version "${version}" in spec "${spec}": versions may contain only letters, ` +
+            `digits, dot, underscore and dash (for example 1.2.3, 1.2.3-beta.1 or latest)`);
+    return { name, version };
+}
+/** The npm argument for a spec: `name`, `name@<version>` or `name@latest` for `--update`. */
+export function npmInstallTarget(name, version, update = false) {
+    return update ? `${name}@latest` : version ? `${name}@${version}` : name;
+}
+export const INSTALL_TIMEOUT_MS = 300_000;
+const defaultRunner = (command, args, options) => runProcess(command, args, { ...options, timeoutMs: INSTALL_TIMEOUT_MS, maxBytes: 64_000 });
+/**
+ * Redacts probable secrets from npm output (auth tokens, JWTs, bearer credentials, userinfo in
+ * URLs) and caps the size, so a failing install never echoes credentials to the user.
+ */
+export function sanitizeNpmError(text, maxLength = 4000) {
+    const MAX = Math.max(1, maxLength);
+    let cleaned = text.replace(/(eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]+|\bbearer\s+[A-Za-z0-9._~+/-]{12,}=*\b|\b(?:npm_?authToken|_authToken|NODE_AUTH_TOKEN|NPM_TOKEN|authToken|password|secret)\b\s*(?:=|:)\s*\S+|\b(?:npm_?authToken|_authToken|NODE_AUTH_TOKEN|NPM_TOKEN|authToken|password|secret)\b\s+\S+)/gi, "[redacted]");
+    cleaned = cleaned.replace(/([a-z][a-z0-9+.-]*):\/\/[^@\s/]+@/gi, "$1://[redacted]@");
+    if (cleaned.length > MAX)
+        cleaned = `${cleaned.slice(0, MAX)}\n…[npm output truncated]`;
+    return cleaned;
+}
+function npmInstallError(name, version, update, pluginsDir, result) {
+    const detail = sanitizeNpmError([result.stdout, result.stderr].filter(Boolean).join("\n"));
+    const retry = `npm install --prefix ${pluginsDir} ${npmInstallTarget(name, version, update)}`;
+    return new Error(`npm install failed for plugin "${name}" (exit ${result.exitCode}).\n${detail || "no output"}\n` +
+        `Retry with: ${retry}\n(or: alisio install npm:${npmInstallTarget(name, version)})`);
+}
+/** Atomically adds `packageName` to the global configuration `plugins` array, preserving all other fields. */
+async function persistGlobalPluginEntry(configHomeDir, packageName) {
+    const file = join(configHomeDir, "config.json");
+    const existing = await readJson(file);
+    let raw;
+    if (existing === undefined)
+        raw = {};
+    else if (typeof existing === "object" && !Array.isArray(existing))
+        raw = existing;
+    else
+        throw new Error(`Global Alisio configuration must be a JSON object: ${file}`);
+    const current = Array.isArray(raw.plugins) ? raw.plugins : [];
+    if (!current.includes(packageName))
+        raw.plugins = [...current, packageName];
+    raw.schemaVersion ??= 1;
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(`${JSON.stringify(raw, null, 2)}\n`, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(temporary, file);
+        await chmod(file, 0o600);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => { });
+        throw error;
+    }
+    return file;
+}
+/** The shared install routine used by both the CLI command and the `plugin_install` tool. */
+export async function installPlugin(input) {
+    const parsed = parsePluginSpec(input.spec);
+    if (input.readOnly)
+        throw new Error(`Installing npm plugin "${parsed.name}" is unavailable under --read-only: installation runs npm and writes your global configuration. Run without --read-only.`);
+    const home = resolve(input.configHome ?? configHome());
+    const pluginsDir = join(home, "plugins");
+    // npm creates the prefix directory itself, but the subprocess cwd must already exist for spawn.
+    await mkdir(pluginsDir, { recursive: true, mode: 0o700 });
+    const packageDir = join(pluginsDir, "node_modules", parsed.name);
+    const installedManifest = (await readJson(join(packageDir, "package.json")));
+    const alreadyInstalled = !!installedManifest?.version;
+    let updated = false;
+    if (!alreadyInstalled || input.update) {
+        const signal = input.signal ?? AbortSignal.timeout(INSTALL_TIMEOUT_MS);
+        const run = input.runner ?? defaultRunner;
+        const npmResult = await run("npm", [
+            "install",
+            "--prefix",
+            pluginsDir,
+            npmInstallTarget(parsed.name, parsed.version, input.update),
+        ], { cwd: pluginsDir, signal });
+        if (npmResult.exitCode !== 0)
+            throw npmInstallError(parsed.name, parsed.version, input.update, pluginsDir, npmResult);
+        updated = !!input.update && alreadyInstalled;
+    }
+    const manifest = (await readJson(join(packageDir, "package.json")));
+    const installedVersion = manifest?.version ?? "unknown";
+    const configFile = await persistGlobalPluginEntry(home, parsed.name);
+    return {
+        packageName: parsed.name,
+        installedVersion,
+        path: packageDir,
+        configEntry: parsed.name,
+        configFile,
+        pluginsDir,
+        alreadyInstalled,
+        updated,
+        trustRemark: pluginTrustRemark(parsed.name),
+    };
+}
+/** Final remark about loading and project trust, printed by the CLI and returned by the tool. */
+export function pluginTrustRemark(name) {
+    return (`The plugin "${name}" is installed globally for your user; it loads as trusted personal code ` +
+        `wherever global plugins load — use \`alisio --trust-project\` or accept the one-time trust prompt ` +
+        `in a project so its configuration and project plugins load too. \`--read-only\` keeps the plugin ` +
+        `from loading. Run \`alisio plugins list\` to inspect.`);
+}
+const PREINSTALL_WARNING = `Warning: "npm install" may run the package's lifecycle scripts (preinstall, install, postinstall) ` +
+    `with your user privileges. Alisio does not sandbox plugin installation or plugin code; the plugin ` +
+    `runs in-process if it is loaded. Only install packages you trust.`;
+export async function cliInstall(options) {
+    // Validate the spec before any network operation or prompt.
+    const parsed = parsePluginSpec(options.spec);
+    if (options.readOnly)
+        throw new Error(`Refusing to install npm plugin "${parsed.name}" under --read-only: installing runs npm and writes your global configuration. Run the command without --read-only.`);
+    if (options.yes) {
+        // Explicit opt-in: no warning, no prompt.
+    }
+    else if (options.interactive) {
+        process.stderr.write(`\n${PREINSTALL_WARNING}\n`);
+        const confirmed = await (options.confirm ?? defaultConfirm)();
+        if (!confirmed)
+            throw new Error(`Install of plugin "${parsed.name}" cancelled; nothing was installed or configured.`);
+    }
+    else {
+        // Headless (including --json): never prompt, fail with an actionable error.
+        throw new Error(`Refusing to install npm plugin "${parsed.name}" without confirmation: npm install may run ` +
+            `lifecycle scripts from the package. Re-run with --yes (or --trust-plugin) to confirm, for ` +
+            `example: alisio install npm:${npmInstallTarget(parsed.name, parsed.version)} --yes`);
+    }
+    const result = await installPlugin({
+        spec: options.spec,
+        configHome: options.configHome,
+        update: options.update,
+        signal: options.signal,
+        runner: options.runner,
+    });
+    printInstallResult(result, { json: !!options.json });
+    return result;
+}
+async function defaultConfirm() {
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = (await rl.question("Install this plugin package globally? [y/N] "))
+            .trim()
+            .toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export function printInstallResult(result, options = {}) {
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({
+            packageName: result.packageName,
+            installedVersion: result.installedVersion,
+            path: result.path,
+            configEntry: result.configEntry,
+            configFile: result.configFile,
+            alreadyInstalled: result.alreadyInstalled,
+            updated: result.updated,
+            trustRemark: result.trustRemark,
+        }, null, 2)}\n`);
+        return;
+    }
+    if (result.alreadyInstalled && !result.updated)
+        console.log(`Plugin "${result.packageName}" is already installed (v${result.installedVersion}). Use --update to refresh it to the latest version and keep its name.`);
+    else if (result.updated)
+        console.log(`Updated plugin "${result.packageName}" to v${result.installedVersion}.`);
+    else
+        console.log(`Installed plugin "${result.packageName}" v${result.installedVersion}.`);
+    console.log(`  path: ${result.path}`);
+    console.log(`  config: "plugins" entry "${result.configEntry}" in ${result.configFile}`);
+    console.log(result.trustRemark);
+}
+/**
+ * Registers the host-owned `plugin_install` tool (agent capability). It has process effect so it
+ * goes through the existing write/process/external permission gate (TUI approval or
+ * `--allow-process`; never available under `--read-only`, where it is not registered at all).
+ */
+export function registerPluginInstallTool(registry, options = {}) {
+    if (options.readOnly)
+        return;
+    const tool = {
+        name: "plugin_install",
+        effect: "process",
+        description: "Install an npm plugin package into Alisio's global plugins directory " +
+            "(<configHome>/plugins, for example ~/.config/alisio/plugins) and add its npm name to the " +
+            'global configuration "plugins" array so it can load across projects. Accepts "npm:<package>' +
+            "[@<version>]\" or a bare package name. npm may run the package's lifecycle scripts with your " +
+            "privileges, so this tool goes through the process permission gate like any subprocess; the " +
+            "installed plugin runs in-process wherever it is loaded and is disabled under --read-only.",
+        inputSchema: {
+            type: "object",
+            properties: { spec: { type: "string", minLength: 1 } },
+            required: ["spec"],
+            additionalProperties: false,
+        },
+        async execute(input, context) {
+            const result = await installPlugin({
+                spec: String(input.spec),
+                configHome: options.configHome,
+                runner: options.runner,
+                signal: context.signal,
+            });
+            return textResult(JSON.stringify({
+                packageName: result.packageName,
+                installedVersion: result.installedVersion,
+                path: result.path,
+                configEntry: result.configEntry,
+                configFile: result.configFile,
+                alreadyInstalled: result.alreadyInstalled,
+                updated: result.updated,
+                trustRemark: result.trustRemark,
+            }));
+        },
+    };
+    registry.register(tool);
+}
+/**
+ * Lists npm packages installed under `<root>/node_modules` that declare the `alisio-plugin`
+ * keyword — the same packages `plugins`-array entries resolve to. Used by `alisio plugins list`
+ * so an installed package shows up alongside file/directory plugins.
+ */
+export async function installedNpmPlugins(root) {
+    const packagesDir = join(root, "node_modules");
+    let entries;
+    try {
+        entries = await readdir(packagesDir, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    }
+    const result = [];
+    const consider = async (dir) => {
+        const manifest = (await readJson(join(dir, "package.json")));
+        if (manifest && Array.isArray(manifest.keywords) && manifest.keywords.includes(PLUGIN_KEYWORD))
+            result.push(dir);
+    };
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        if (entry.name.startsWith("@")) {
+            const scoped = await readdir(join(packagesDir, entry.name), { withFileTypes: true }).catch(() => []);
+            for (const scope of scoped)
+                if (scope.isDirectory())
+                    await consider(join(packagesDir, entry.name, scope.name));
+        }
+        else {
+            await consider(join(packagesDir, entry.name));
+        }
+    }
+    return result.sort();
+}

package/dist/resources/context.js

@@ -3,7 +3,7 @@
  *
  * - Global: `<config home>/AGENTS.override.md` or `<config home>/AGENTS.md`.
  * - Project: one file per directory from the workspace root down to cwd, choosing
- *   AGENTS.override.md > AGENTS.md > AGENT.md (legacy alias kept from 0.1.0-alpha.1) >
+ *   AGENTS.override.md > AGENTS.md > AGENT.md (legacy alias from the earliest alphas) >
  *   CLAUDE.md (only with `claudeMdFallback`). Concatenated root-first so the closest is last.
  * - Nested files below other directories are attached lazily when tools touch paths under them,
  *   once per session per file (re-attached if the file changes).

package/dist/runtime/modules.d.ts

@@ -1,7 +1,9 @@
 export declare const PLUGIN_KEYWORD = "alisio-plugin";
 /** Paths start with `.`, are absolute, use `\`, end in a JS/TS extension or contain `/` unscoped. */
 export declare function isPathSpec(spec: string): boolean;
-/** Global package roots: NODE_PATH entries and the prefix of the running Node/npm. */
+/** Global package roots: NODE_PATH entries, the prefix of the running Node/npm, and the
+ * Alisio global plugins directory (`<configHome>/plugins`), where `alisio install` puts npm
+ * plugin packages. */
 export declare function defaultGlobalRoots(): string[];
 /**
  * Returns the file to import (or the directory holding an alisio-plugin.json manifest).

package/dist/runtime/modules.js

@@ -1,5 +1,6 @@
 /** Resolution of explicitly trusted plugins given as a path or an npm package name. */
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { configHome } from "../config.js";
 import { readJson } from "./fs.js";
 export const PLUGIN_KEYWORD = "alisio-plugin";
 /** Paths start with `.`, are absolute, use `\`, end in a JS/TS extension or contain `/` unscoped. */
@@ -11,7 +12,9 @@ export function isPathSpec(spec) {
         /\.(?:[cm]?[jt]s|tsx|jsx)$/.test(spec) ||
         (!spec.startsWith("@") && spec.includes("/")));
 }
-/** Global package roots: NODE_PATH entries and the prefix of the running Node/npm. */
+/** Global package roots: NODE_PATH entries, the prefix of the running Node/npm, and the
+ * Alisio global plugins directory (`<configHome>/plugins`), where `alisio install` puts npm
+ * plugin packages. */
 export function defaultGlobalRoots() {
     const prefix = process.env.npm_config_prefix ?? process.env.PREFIX ?? dirname(dirname(process.execPath));
     return [
@@ -21,6 +24,7 @@ export function defaultGlobalRoots() {
         process.platform === "win32"
             ? join(prefix, "node_modules")
             : join(prefix, "lib", "node_modules"),
+        join(configHome(), "plugins"),
     ];
 }
 function entryOf(manifest) {
@@ -58,8 +62,11 @@ export async function resolvePluginSpec(spec, options) {
         if (dirname(dir) === dir)
             break;
     }
-    for (const rootDir of options.globalRoots ?? defaultGlobalRoots())
+    for (const rootDir of options.globalRoots ?? defaultGlobalRoots()) {
         candidates.push(join(rootDir, spec));
+        // `alisio install` writes npm packages under <root>/node_modules/<spec>.
+        candidates.push(join(rootDir, "node_modules", spec));
+    }
     for (const dir of candidates) {
         searched.push(dir);
         const manifest = (await readJson(join(dir, "package.json")));

package/dist/runtime/process.d.ts

@@ -4,6 +4,15 @@ export interface ProcessResult {
     exitCode: number;
     truncated: boolean;
 }
+/**
+ * Detect a spawn failure caused by a missing executable (`ENOENT`), so tools can explain how to
+ * install the dependency instead of surfacing the raw OS error.
+ */
+export declare function isMissingCommand(error: unknown): boolean;
+/** Per-platform install commands for the ripgrep dependency. */
+export declare const RIPGREP_INSTALL_HINT: string;
+/** Human-readable detection status for `alisio doctor`. */
+export declare function ripgrepDiagnostic(found: boolean): string | undefined;
 export declare function runProcess(command: string, args: string[], options: {
     cwd: string;
     signal: AbortSignal;

package/dist/runtime/process.js

@@ -1,4 +1,22 @@
 import { spawn, spawnSync } from "node:child_process";
+/**
+ * Detect a spawn failure caused by a missing executable (`ENOENT`), so tools can explain how to
+ * install the dependency instead of surfacing the raw OS error.
+ */
+export function isMissingCommand(error) {
+    return (!!error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+/** Per-platform install commands for the ripgrep dependency. */
+export const RIPGREP_INSTALL_HINT = "Install ripgrep (rg): `sudo apt install ripgrep` (Debian/Ubuntu), " +
+    "`brew install ripgrep` (macOS), `winget install BurntSushi.ripgrep.MSVC` or " +
+    "`scoop install ripgrep` (Windows). It powers the search_text and list_files tools.";
+/** Human-readable detection status for `alisio doctor`. */
+export function ripgrepDiagnostic(found) {
+    return found ? undefined : RIPGREP_INSTALL_HINT;
+}
 export async function runProcess(command, args, options) {
     options.signal.throwIfAborted();
     const signal = AbortSignal.any([

package/dist/tools/standard.js

@@ -4,13 +4,24 @@ import { dirname, relative } from "node:path";
 import { textResult, } from "@alisio/sdk";
 import { fileSize, readHead, readText } from "../runtime/fs.js";
 import { safePath } from "../runtime/paths.js";
-import { runProcess } from "../runtime/process.js";
+import { isMissingCommand, RIPGREP_INSTALL_HINT, runProcess } from "../runtime/process.js";
 import { EXECUTE_TIMEOUT_MS, MAX_NESTED_CALLS, runExecute } from "./execute.js";
 import { searchWithFallback } from "./search.js";
 import { DEFAULT_TIMEOUT_SECONDS, MAX_RESPONSE_BYTES, MAX_TIMEOUT_SECONDS, webfetch, } from "./webfetch.js";
 const str = { type: "string" }, integer = { type: "integer", minimum: 0 };
 export const objectSchema = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
 export const hash = (text) => createHash("sha256").update(text).digest("hex");
+/** Runs ripgrep and turns a missing binary into an actionable install message. */
+async function runRipgrep(args, options) {
+    try {
+        return await runProcess("rg", args, options);
+    }
+    catch (error) {
+        if (isMissingCommand(error))
+            throw new Error(RIPGREP_INSTALL_HINT);
+        throw error;
+    }
+}
 async function existing(path) {
     const size = await fileSize(path);
     if (size === undefined)
@@ -120,7 +131,7 @@ execCtx, websearchCtx) {
         paths: filePaths,
         async execute(i, c) {
             const path = await safePath(c.workspace, String(i.path ?? "."));
-            const result = await runProcess("rg", ["--files", "--glob", "!.git", "--glob", "!node_modules", "--", path], { cwd: c.workspace, signal: c.signal, maxBytes: 200_000 });
+            const result = await runRipgrep(["--files", "--glob", "!.git", "--glob", "!node_modules", "--", path], { cwd: c.workspace, signal: c.signal, maxBytes: 200_000 });
             if (result.exitCode > 1 && !result.truncated)
                 throw new Error(result.stderr);
             const all = result.stdout
@@ -146,7 +157,7 @@ execCtx, websearchCtx) {
         paths: filePaths,
         async execute(i, c) {
             const path = await safePath(c.workspace, String(i.path ?? "."));
-            const r = await runProcess("rg", [
+            const r = await runRipgrep([
                 "--json",
                 "--max-count",
                 "100",

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Reads the @alisio/core package version at runtime so the MCP client metadata stays in sync
+ * with the published package. Resolves the manifest relative to the module (`src/version.ts` →
+ * `../package.json` in the source tree; `dist/version.js` → `../package.json` when installed).
+ * Standalone binaries inject ALISIO_PACKAGE_VERSION at build time (scripts/binary-build.ts).
+ */
+export declare function loadVersion(fromHere: string): string;

package/dist/version.js

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Fallback used when neither the build-time injection nor the package manifest is readable.
+ * A development marker, never a publish literal: it cannot silently desync from the package.
+ */
+const FALLBACK = "dev";
+/**
+ * Reads the @alisio/core package version at runtime so the MCP client metadata stays in sync
+ * with the published package. Resolves the manifest relative to the module (`src/version.ts` →
+ * `../package.json` in the source tree; `dist/version.js` → `../package.json` when installed).
+ * Standalone binaries inject ALISIO_PACKAGE_VERSION at build time (scripts/binary-build.ts).
+ */
+export function loadVersion(fromHere) {
+    if (process.env.ALISIO_PACKAGE_VERSION)
+        return process.env.ALISIO_PACKAGE_VERSION;
+    try {
+        const manifest = join(dirname(fileURLToPath(fromHere)), "..", "package.json");
+        const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+        return typeof parsed.version === "string" && parsed.version ? parsed.version : FALLBACK;
+    }
+    catch {
+        return FALLBACK;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",