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

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/runtime/store.d.ts

@@ -25,6 +25,7 @@ export declare class SQLiteStore implements SessionStore {
     append(id: string, message: Message): void;
     setModel(id: string, model: string): void;
     compact(id: string, replaced: number, summary: Message): void;
+    overwrite(id: string, messages: Message[]): void;
     acquire(id: string): void;
     release(id: string): void;
     beginCall(id: string, call: ToolCall): void;