@jini-ai/agent-plugins 0.4.6 → 0.4.8

package/dist/lifecycle/provider-contribution.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Plugin-contributed providers for `@jini-ai/core`'s `createProviderRegistry` (FROZEN CONTRACT,
+ * 2026-10-21). Lives here rather than in core because core cannot import agent-plugins (agent-plugins
+ * already depends on core). Defined on the one executable loader (`defineExecutablePluginContribution`)
+ * so a provider module passes the same gates as every other seam that runs plugin code: active
+ * plugin, bundled digest, contained `.mjs` path. No second loader.
+ *
+ * Every failure is a refusal line, never a throw: a broken or duplicate plugin provider must not
+ * crash boot (core/built-in registrations keep the registry's throwing policy).
+ */
+import { type ProviderDefinition, type ProviderRegistry } from '@jini-ai/core/provider-registry';
+import { type PluginContributionDefinition, type PluginContributionResult } from './contribution-loader.js';
+/** The minimum a provider manifest entry declares; a seam's parser may add fields. */
+export interface ProviderContributionDescriptor {
+    readonly id: string;
+    /** Plain-JS module inside the plugin root (`.mjs`); containment is checked on disk at import. */
+    readonly module: string;
+    readonly label?: string;
+}
+export interface LoadedProviderContribution<T> {
+    readonly contract: string;
+    readonly pluginId: string;
+    readonly definition: ProviderDefinition<T>;
+}
+/**
+ * Defines the contribution of providers for one contract (e.g. `mail`) from a host-chosen file.
+ * The id is checked before the module is imported, so a malformed entry never runs code.
+ * @param required.contract - Must equal the target registry's `contract`.
+ * @param required.filename - The file a plugin ships at its package root to contribute providers.
+ * @param required.parse - The seam's manifest parser.
+ * @param required.validate - The module export as a provider of this contract, or why not.
+ * @param optional - The loader's read/import recovery policy. Unlike the bare executable loader, absent
+ *   policies default to refusal lines (`could not be read`, `its module failed to load`) instead of
+ *   propagating the fault, so one unreadable manifest or throwing module never discards the healthy
+ *   contributions loaded alongside it. Pass `onReadError: () => []` to tolerate a missing manifest.
+ * @returns A definition for `loadPluginContributions`; executable, so activation is always required.
+ * @complexity O(1); each load is one contained import per declared provider.
+ */
+export declare function defineProviderContribution<D extends ProviderContributionDescriptor, T>(required: {
+    readonly contract: string;
+    readonly filename: string;
+    readonly parse: PluginContributionDefinition<D, LoadedProviderContribution<T>>['parse'];
+    readonly validate: (required: {
+        readonly exported: unknown;
+    }) => T | string;
+}, optional?: {
+    readonly onReadError?: PluginContributionDefinition<D, LoadedProviderContribution<T>>['onReadError'];
+    readonly importRefusalReason?: string;
+    readonly importErrorReason?: string;
+}): PluginContributionDefinition<D, LoadedProviderContribution<T>>;
+/**
+ * Offer loaded plugin providers to a registry and merge every refusal into one host-facing list:
+ * the loader's (gate, manifest, import, validation) first, then the registry's (contract mismatch,
+ * duplicate, invalid provider) in contribution order.
+ * @returns The ids the registry accepted and every refusal line; never throws.
+ * @complexity O(n) contributions.
+ */
+export declare function contributeProviders<T>(required: {
+    readonly registry: ProviderRegistry<T>;
+    readonly loaded: PluginContributionResult<LoadedProviderContribution<T>>;
+}, _optional?: Record<string, never>): {
+    readonly accepted: readonly string[];
+    readonly refusals: readonly string[];
+};
+//# sourceMappingURL=provider-contribution.d.ts.map

package/dist/lifecycle/provider-contribution.js

@@ -0,0 +1,93 @@
+/**
+ * @file Plugin-contributed providers for `@jini-ai/core`'s `createProviderRegistry` (FROZEN CONTRACT,
+ * 2026-10-21). Lives here rather than in core because core cannot import agent-plugins (agent-plugins
+ * already depends on core). Defined on the one executable loader (`defineExecutablePluginContribution`)
+ * so a provider module passes the same gates as every other seam that runs plugin code: active
+ * plugin, bundled digest, contained `.mjs` path. No second loader.
+ *
+ * Every failure is a refusal line, never a throw: a broken or duplicate plugin provider must not
+ * crash boot (core/built-in registrations keep the registry's throwing policy).
+ */
+import { PROVIDER_ID_PATTERN } from '@jini-ai/core/provider-registry';
+import { defineExecutablePluginContribution, } from './contribution-loader.js';
+/**
+ * Defines the contribution of providers for one contract (e.g. `mail`) from a host-chosen file.
+ * The id is checked before the module is imported, so a malformed entry never runs code.
+ * @param required.contract - Must equal the target registry's `contract`.
+ * @param required.filename - The file a plugin ships at its package root to contribute providers.
+ * @param required.parse - The seam's manifest parser.
+ * @param required.validate - The module export as a provider of this contract, or why not.
+ * @param optional - The loader's read/import recovery policy. Unlike the bare executable loader, absent
+ *   policies default to refusal lines (`could not be read`, `its module failed to load`) instead of
+ *   propagating the fault, so one unreadable manifest or throwing module never discards the healthy
+ *   contributions loaded alongside it. Pass `onReadError: () => []` to tolerate a missing manifest.
+ * @returns A definition for `loadPluginContributions`; executable, so activation is always required.
+ * @complexity O(1); each load is one contained import per declared provider.
+ */
+export function defineProviderContribution(required, optional = {}) {
+    const { contract } = required;
+    const refusal = ({ plugin, descriptor, reason }) => `${contract} provider '${String(descriptor.id)}' from '${plugin.pluginId}' was not loaded: ${reason}`;
+    const { filename } = required;
+    const executable = defineExecutablePluginContribution({
+        filename, contribution: `${contract} providers`, parse: guardedParse({ parse: required.parse }),
+        modulePath: ({ descriptor }) => descriptor.module, validate: required.validate, refusal,
+    }, {
+        onReadError: optional.onReadError ?? (({ plugin }) => [`${contract} providers from '${plugin.pluginId}' were not loaded: ${filename} could not be read`]),
+        importErrorReason: optional.importErrorReason ?? 'its module failed to load',
+        ...(optional.importRefusalReason === undefined ? {} : { importRefusalReason: optional.importRefusalReason }),
+    });
+    const loadOne = async (input) => {
+        const { plugin, descriptor } = input;
+        if (typeof descriptor.id !== 'string' || !PROVIDER_ID_PATTERN.test(descriptor.id)) {
+            return refusal({ plugin, descriptor, reason: `its id must match ${PROVIDER_ID_PATTERN.source}` });
+        }
+        const loaded = await executable.load(input);
+        if (typeof loaded === 'string')
+            return loaded;
+        const { id, label } = descriptor;
+        return { contract, pluginId: loaded.pluginId, definition: { id, provider: loaded.module, ...(label === undefined ? {} : { label }) } };
+    };
+    return {
+        ...executable,
+        // Per-descriptor boundary: a hostile descriptor (e.g. a throwing getter) becomes one refusal and
+        // the loader moves on to the next declaration.
+        load: async (input) => {
+            try {
+                return await loadOne(input);
+            }
+            catch {
+                return `${contract} provider from '${input.plugin.pluginId}' was not loaded: its declaration could not be read`;
+            }
+        },
+    };
+}
+/** A throwing seam parser is a refused manifest, not a boot fault. */
+function guardedParse(required, _optional = {}) {
+    return (input) => {
+        try {
+            return required.parse(input);
+        }
+        catch {
+            return { ok: false, reason: 'its parser failed' };
+        }
+    };
+}
+/**
+ * Offer loaded plugin providers to a registry and merge every refusal into one host-facing list:
+ * the loader's (gate, manifest, import, validation) first, then the registry's (contract mismatch,
+ * duplicate, invalid provider) in contribution order.
+ * @returns The ids the registry accepted and every refusal line; never throws.
+ * @complexity O(n) contributions.
+ */
+export function contributeProviders(required, _optional = {}) {
+    const { registry, loaded } = required;
+    const before = registry.refusals().length;
+    const accepted = [];
+    for (const item of loaded.items) {
+        if (registry.contribute({ definition: item.definition, pluginId: item.pluginId, contract: item.contract }))
+            accepted.push(item.definition.id);
+    }
+    const registryRefusals = registry.refusals().slice(before).map(refusal => refusal.message);
+    return { accepted, refusals: [...loaded.refusals, ...registryRefusals] };
+}
+//# sourceMappingURL=provider-contribution.js.map

package/dist/lifecycle/resolve-agent-plugin-refs.js

@@ -22,7 +22,8 @@ import { listInstalledPackageRoots, INSTALLED_PLUGIN_DIGEST_PATTERN } from "./in
  * `packages/sha256/*` and matches on the installed `plugin.json`'s own `name` field, after dropping
  * any digest of a bundled plugin the ledger records as superseded:
  *
- * - Exactly one match: resolves normally.
+ * - Exactly one match: resolves normally, unless the bundled ledger records that id at a different
+ *   digest (a copy the build did not ship never guides under a bundled id).
  * - Zero matches: fails with a "not installed" reason — the operator pinned a chip for a plugin
  *   that is not (or no longer) actually on disk for this workspace.
  * - More than one match: fails with an explicit ambiguity reason naming every matching digest.
@@ -50,7 +51,7 @@ import { listInstalledPackageRoots, INSTALLED_PLUGIN_DIGEST_PATTERN } from "./in
  * and CLI agents — supporting content is deferred to an explicit follow-up read.
  *
  * Architectural role:
- * Server-side only (reads `node:fs/promises`, imports `install.ts`'s `indexInstalledRoot`) — never
+ * Server-side only (reads injected filesystem ports through the installed-package index) — never
  * imported into a browser bundle. Returns a discriminated result rather than throwing, so
  * `agent-daemon-server.ts`'s `onStarted` gets one place to branch on success/failure without a
  * second try/catch layer duplicating this module's own error classification.
@@ -60,7 +61,7 @@ import path from "node:path";
 import { createPackagePathsModule } from "./package-paths.js";
 import { createActivationModule } from "./activation.js";
 import { createBundledDigestsModule } from "./bundled-digests.js";
-import { createInstallModule } from "./install.js";
+import { createInstalledPackageIndex } from "./installed-package-index.js";
 import { createCapabilityProjectionModule } from "./capability-projection.js";
 function buildModule(ports) {
     const persistentState = createPersistentStateModule(ports);
@@ -68,7 +69,7 @@ function buildModule(ports) {
     const stat = ports.filesystem.stat.bind(ports.filesystem);
     const { resolveAgentPluginActivation } = createActivationModule(ports);
     const { preferBundledAgentPluginDigests, readBundledAgentPluginDigests } = createBundledDigestsModule(ports);
-    const { indexInstalledRoot } = createInstallModule(ports);
+    const { indexInstalledRoot } = createInstalledPackageIndex({ ports });
     const { readInstalledSkillFile } = createCapabilityProjectionModule(ports);
     /** Reads the delivery mode for this process. An unset or unrecognised value is `inject` — an A/B
    *  affordance must never be able to change production behaviour by typo. */
@@ -149,7 +150,7 @@ function buildModule(ports) {
         const installed = [];
         for (const root of await listInstalledPackageRoots({ ports, workspaceRoot })) {
             try {
-                const plugin = await indexInstalledRoot(root.packageRoot, root.archiveDigest);
+                const plugin = await indexInstalledRoot({ packageRoot: root.packageRoot, archiveDigest: root.archiveDigest });
                 if (plugin.pluginId === root.localId)
                     installed.push(plugin);
             }
@@ -218,9 +219,21 @@ function buildModule(ports) {
             };
         }
         const plugin = matches[0];
-        const skillPath = `skills/${pluginRefId}/SKILL.md`;
+        // Activation is checked by the caller. A lone copy under an id the bundled ledger records must be
+        // the digest this build shipped; an operator install (no ledger entry) was digest-verified when
+        // installed and its skills may guide once enabled (install-upload's trust warning). Inline, not
+        // trusted-plugin-files' verdict: that module lists installs through this one (import cycle).
+        const shippedDigest = bundledDigests.get(pluginRefId);
+        if (shippedDigest !== undefined && shippedDigest !== plugin.archiveDigest) {
+            return { ok: false, reason: `Agent Plugin '${pluginRefId}' was not loaded: only plugins shipped with ${ports.productName} may add agent guidance under a bundled id (installed digest ${plugin.archiveDigest.slice(0, 12)} is not the one this build shipped)` };
+        }
         if (deliveryMode === "pointer")
             return buildPointerSection(pluginRefId, plugin);
+        return buildInjectedSection({ pluginRefId, packagesDir, plugin });
+    }
+    /** `inject` mode: the eponymous SKILL.md, the plugin's user notes, and its readable-file inventory. */
+    async function buildInjectedSection({ pluginRefId, packagesDir, plugin }) {
+        const skillPath = `skills/${pluginRefId}/SKILL.md`;
         let skillMarkdown;
         let files;
         let fileNote;

package/dist/lifecycle/retire-bundled.js

@@ -41,28 +41,13 @@ function buildModule(ports) {
         const allInstalled = await listInstalledPlugins(workspaceLayout.root);
         const installed = allInstalled.filter((plugin) => plugin.pluginId === pluginId);
         const hasRecord = Object.hasOwn((await readAgentPluginActivations(workspaceRoot)).plugins, pluginId);
-        if (installed.length === 0 && !hasRecord) {
-            const ledgerEntryRemoved = await removeBundledAgentPluginDigest({ workspaceRoot, pluginId });
-            if (!ledgerEntryRemoved)
-                return { pluginId, ...ids, status: "absent" };
-            return { pluginId, ...ids, status: "retired", removedDigests: [], activationRemoved: false, ledgerEntryRemoved, successor: "not-needed", ...(ids.successorIds ? { successors: {} } : {}) };
-        }
+        if (installed.length === 0 && !hasRecord)
+            return dropLeftoverLedgerEntry({ workspaceRoot, pluginId, ids });
         const unusable = await unusableSuccessor(workspaceRoot, allInstalled, successorIds);
         if (unusable !== undefined) {
             return { pluginId, ...ids, status: "failed", reason: `'${pluginId}' is kept until every successor is usable: ${unusable}` };
         }
-        const successors = {};
-        for (const successorId of successorIds) {
-            successors[successorId] =
-                verdict.verdict === "active"
-                    ? await enableBundledAgentPluginUnlessOperatorDisabled({
-                        workspaceRoot,
-                        pluginId: successorId,
-                        actor: `system:retire-${pluginId}`,
-                        ...(optional.now !== undefined ? { now: optional.now } : {}),
-                    })
-                    : "not-needed";
-        }
+        const successors = await switchOnSuccessors({ workspaceRoot, pluginId, successorIds, wasActive: verdict.verdict === "active" }, { now: optional.now });
         const successor = successors[ids.successorId] ?? "not-needed";
         let removedDigests = [];
         if (installed.length > 0) {
@@ -74,6 +59,23 @@ function buildModule(ports) {
         const ledgerEntryRemoved = await removeBundledAgentPluginDigest({ workspaceRoot, pluginId });
         return { pluginId, ...ids, status: "retired", removedDigests, activationRemoved: hasRecord, ledgerEntryRemoved, successor, ...(ids.successorIds ? { successors } : {}) };
     }
+    /** Step 1: nothing installed and no record — only a leftover ledger entry can remain to drop. */
+    async function dropLeftoverLedgerEntry({ workspaceRoot, pluginId, ids }) {
+        const ledgerEntryRemoved = await removeBundledAgentPluginDigest({ workspaceRoot, pluginId });
+        if (!ledgerEntryRemoved)
+            return { pluginId, ...ids, status: "absent" };
+        return { pluginId, ...ids, status: "retired", removedDigests: [], activationRemoved: false, ledgerEntryRemoved, successor: "not-needed", ...(ids.successorIds ? { successors: {} } : {}) };
+    }
+    /** Step 2: each successor's outcome — switched on only when the retired plugin was active. */
+    async function switchOnSuccessors({ workspaceRoot, pluginId, successorIds, wasActive }, { now } = {}) {
+        const successors = {};
+        for (const successorId of successorIds) {
+            successors[successorId] = wasActive
+                ? await enableBundledAgentPluginUnlessOperatorDisabled({ workspaceRoot, pluginId: successorId, actor: `system:retire-${pluginId}`, ...(now !== undefined ? { now } : {}) })
+                : "not-needed";
+        }
+        return successors;
+    }
     /** Why one of `successorIds` cannot take over yet, or `undefined` when every one is installed at the
    *  digest the ledger records for it (this file's header, step 1a).
    *  @complexity O(s * n) for s successors over n installed packages; both are small bundled counts. */

package/dist/lifecycle/search.d.ts

@@ -60,6 +60,11 @@ export interface AgentPluginSearchSkill {
  *  `packageRoot`/`skillPath`/any other host-filesystem detail (see `tool-registrations.ts`'s own
  *  SECURITY note for why: this candidate shape is what actually reaches the model). */
 export interface AgentPluginSearchCandidate {
+    readonly origin?: import("./activation.js").AgentPluginOrigin;
+    readonly hostOk?: boolean;
+    readonly missingRequires?: readonly string[];
+    readonly requiredBy?: readonly string[];
+    readonly archiveDigest?: string;
     readonly pluginId: string;
     readonly version?: (string) | undefined;
     /** Human-facing title from the host extension namespace in `plugin.json`: `displayName`, when the package set one. */
@@ -83,6 +88,6 @@ export interface AgentPluginSearchMatch extends AgentPluginSearchCandidate {
 }
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createSearchModule(ports: AgentPluginLifecyclePorts): {
-    rankInstalledAgentPlugins: (query: string, candidates: readonly AgentPluginSearchCandidate[], limit: number) => readonly AgentPluginSearchMatch[];
+    rankInstalledAgentPlugins: (query: string, candidates: readonly AgentPluginSearchCandidate[], limit: number, automatic?: boolean) => readonly AgentPluginSearchMatch[];
 };
 //# sourceMappingURL=search.d.ts.map

package/dist/lifecycle/search.js

@@ -1,4 +1,39 @@
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+/** These describe the conversation or target, not a plugin's topic. Prose-only hits remain
+ * available to explicit search without silently loading unrelated guidance. */
+const INCIDENTAL_TERMS = new Set('a an and are as at be build can could create do for from get help i in is it make me my new of on or please the this to use want we with you your site sites page pages website websites plugin plugins tell which load just don t anything'.split(' '));
+const DEPLOYMENT_TERMS = new Set('deploy deployment deploying deployed publish publishing published host hosting hosted'.split(' '));
+function automaticTerms(query) {
+    return [...new Set((query.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).filter(term => !INCIDENTAL_TERMS.has(term)))];
+}
+/** A dedicated deployment provider (only `deploy-*` and `credential-scheme:*` capabilities) matches only a
+ * query naming both a deployment action and one of its vendor terms; any other plugin passes. */
+function passesDeploymentGate({ candidate, capabilities, terms }, _options = {}) {
+    const deployment = capabilities.filter(capability => capability.startsWith('deploy-'));
+    const dedicatedDeployment = deployment.length > 0 && capabilities.every(capability => capability.startsWith('deploy-') || capability.startsWith('credential-scheme:'));
+    if (!dedicatedDeployment)
+        return true;
+    const vendors = automaticTerms([candidate.pluginId, candidate.displayName ?? '', ...deployment.map(capability => capability.split(':')[1] ?? '')].join(' '))
+        .filter(term => !DEPLOYMENT_TERMS.has(term));
+    return terms.some(term => DEPLOYMENT_TERMS.has(term)) && terms.some(term => vendors.includes(term));
+}
+/** Score complete authored terms only: long descriptions must not manufacture relevance.
+ * Dedicated deployment providers additionally need both the action and their declared vendor.
+ * Mixed-purpose plugins can still match their other capabilities (for example source control).
+ */
+function automaticScore({ candidate, terms }, _options = {}) {
+    if (!candidate.enabled)
+        return 0;
+    const capabilities = candidate.provides ?? [];
+    if (!passesDeploymentGate({ candidate, capabilities, terms }))
+        return 0;
+    const fields = [
+        { terms: automaticTerms(capabilities.join(' ')), weight: 6 },
+        { terms: automaticTerms(`${candidate.pluginId} ${candidate.id ?? ''} ${candidate.displayName ?? ''}`), weight: 5 },
+        { terms: automaticTerms(candidate.keywords.join(' ')), weight: 4 },
+    ];
+    return terms.reduce((score, term) => score + fields.reduce((sum, field) => sum + (field.terms.includes(term) ? field.weight : 0), 0), 0);
+}
 function buildModule(ports) {
     const ID_FIELD_WEIGHT = 5;
     const KEYWORD_FIELD_WEIGHT = 4;
@@ -18,7 +53,7 @@ function buildModule(ports) {
    *  plain, independently-readable list rather than interleaved with the scoring loop itself. */
     function fieldHaystacks(candidate) {
         return [
-            { text: `${candidate.pluginId} ${candidate.id ?? ""}`.toLowerCase(), weight: ID_FIELD_WEIGHT },
+            { text: `${candidate.pluginId} ${candidate.id ?? ""} ${candidate.displayName ?? ""}`.toLowerCase(), weight: ID_FIELD_WEIGHT },
             { text: [...candidate.keywords, ...(candidate.provides ?? [])].join(" ").toLowerCase(), weight: KEYWORD_FIELD_WEIGHT },
             { text: (candidate.description ?? "").toLowerCase(), weight: DESCRIPTION_FIELD_WEIGHT },
             {
@@ -48,20 +83,23 @@ function buildModule(ports) {
    * @param limit - Max matches to return, already clamped by the caller (mirrors
    * `component-catalog-tool.ts`'s handler, which owns the clamp so this function can stay a pure
    * "given these inputs, rank them" step with no knowledge of the tool's own schema bounds).
-   * @returns Matches with score > 0, sorted by score descending, truncated to `limit`. A candidate
+   * @returns Matches with score > 0, sorted by score descending then plugin id, truncated to `limit`. A candidate
    * that scores 0 (no term matched anything) is dropped, not returned at the bottom — the caller's own
    * "N installed, 0 matched" framing is what tells the model the workspace is not empty even when a
    * query matches nothing.
    * @complexity See this file's header.
    */
-    function rankInstalledAgentPlugins(query, candidates, limit) {
-        const terms = tokenize(query);
+    function rankInstalledAgentPlugins(query, candidates, limit, automatic = false) {
+        const terms = automatic ? automaticTerms(query) : tokenize(query);
         if (terms.length === 0)
             return [];
-        return candidates
-            .map((candidate) => ({ ...candidate, score: scoreCandidate(candidate, terms) }))
+        const ranked = candidates
+            .map((candidate) => ({ ...candidate, score: automatic ? automaticScore({ candidate, terms }) : scoreCandidate(candidate, terms) }))
             .filter((match) => match.score > 0)
-            .sort((a, b) => b.score - a.score)
+            .sort((a, b) => b.score - a.score || a.pluginId.localeCompare(b.pluginId));
+        // A weak shared keyword must not ride alongside a substantially stronger task owner.
+        const threshold = automatic ? Math.max(4, (ranked[0]?.score ?? 0) * 0.6) : 0;
+        return ranked.filter(match => match.score >= threshold)
             .slice(0, Math.max(limit, 0));
     }
     return { rankInstalledAgentPlugins };

package/dist/lifecycle/set-enabled.d.ts

@@ -20,9 +20,10 @@ export interface SetAgentPluginEnabledResult {
     readonly pluginId: string;
     /** As actually written and read back, not as requested. */
     readonly enabled: boolean;
+    readonly warnings?: readonly string[];
 }
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createSetEnabledModule(ports: AgentPluginLifecyclePorts): {
-    setAgentPluginEnabled: (input: SetAgentPluginEnabledInput) => Promise<SetAgentPluginEnabledResult>;
+    setAgentPluginEnabled: (input: SetAgentPluginEnabledInput, _optional?: Record<string, never>) => Promise<SetAgentPluginEnabledResult>;
 };
 //# sourceMappingURL=set-enabled.d.ts.map

package/dist/lifecycle/set-enabled.js

@@ -1,6 +1,9 @@
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
+import { createPersistentStateModule } from './persistent-state.js';
+import { AgentPluginHostIncompatibleError, describeAgentPluginCompatibility, agentPluginDependentWarnings } from './compatibility.js';
 import { createActivationModule } from "./activation.js";
 import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.js";
+import { createAgentPluginUpdateStore, settleAgentPluginUpdateJournal } from "./update-store.js";
 /**
  * The id named is not installed in this workspace. A distinct class rather than a bare `Error` so
  * each caller can map it to its own boundary's vocabulary — 404 `AGENT_PLUGIN_NOT_FOUND` at the
@@ -13,21 +16,62 @@ export class AgentPluginNotInstalledError extends Error {
     }
 }
 function buildModule(ports) {
-    const { setAgentPluginActivation } = createActivationModule(ports);
+    const { setAgentPluginActivation, readAgentPluginActivations } = createActivationModule(ports);
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
-    async function setAgentPluginEnabled(input) {
-        const workspaceLayout = ports.layout.forWorkspace({ workspaceId: input.workspaceId });
-        const installed = await listInstalledPlugins(workspaceLayout.root);
-        if (!installed.some((plugin) => plugin.pluginId === input.pluginId)) {
-            throw new AgentPluginNotInstalledError({ pluginId: input.pluginId });
+    const persistentState = createPersistentStateModule(ports);
+    async function findInstalled({ workspaceRoot, pluginId }) {
+        const installed = await listInstalledPlugins(workspaceRoot);
+        const plugin = installed.find(candidate => candidate.pluginId === pluginId);
+        if (!plugin) {
+            throw new AgentPluginNotInstalledError({ pluginId });
         }
+        return { installed, plugin };
+    }
+    /** Refuses a host-incompatible enable; otherwise returns advisory warnings, never blocking. */
+    async function enablementWarnings({ input, workspaceRoot, installed, plugin }) {
+        const activations = await readAgentPluginActivations(workspaceRoot);
+        if (!input.enabled)
+            return agentPluginDependentWarnings({ plugin, installed, activations, nextProvides: [] });
+        const compatibility = describeAgentPluginCompatibility({ plugin, installed, activations });
+        // Several digests of one id can be installed (a bundled upgrade lands beside the old one), and
+        // the listing order is arbitrary, so every installed revision must be host-compatible.
+        const revisions = installed.filter(candidate => candidate.pluginId === plugin.pluginId);
+        if (revisions.some(revision => !describeAgentPluginCompatibility({ plugin: revision, installed, activations }).hostOk)) {
+            throw new AgentPluginHostIncompatibleError({ pluginId: input.pluginId });
+        }
+        return compatibility.missingRequires.map(id => `Needs ${id}`);
+    }
+    async function setEnabledLocked({ input, workspaceRoot }) {
+        // Re-read under the lock: an uninstall or update may have finished while this call waited.
+        const { installed, plugin } = await findInstalled({ workspaceRoot, pluginId: input.pluginId });
+        // Boot recovery of an unfinished update would overwrite this decision, so it refuses
+        // (PLUGIN_UPDATE_PENDING) until a boot recovers it.
+        await settleAgentPluginUpdateJournal({ store: createAgentPluginUpdateStore({ ports, workspaceId: input.workspaceId, pluginId: input.pluginId }) });
+        const warnings = await enablementWarnings({ input, workspaceRoot, installed, plugin });
         const written = await setAgentPluginActivation({
-            workspaceRoot: workspaceLayout.root,
+            workspaceRoot,
             pluginId: input.pluginId,
             enabled: input.enabled,
             actor: input.actor,
         });
-        return { pluginId: input.pluginId, enabled: written.plugins[input.pluginId]?.enabled ?? input.enabled };
+        // Always present: setAgentPluginActivation asserts the same id grammar its normalizer keeps and
+        // writes a boolean `enabled`, so the record it returns holds this entry (the former
+        // `?? input.enabled` fallback was unreachable).
+        return { pluginId: input.pluginId, enabled: written.plugins[input.pluginId].enabled, ...(warnings.length ? { warnings } : {}) };
+    }
+    /**
+     * Serialized with install/update/uninstall of the same plugin by the per-plugin state lock, so a
+     * toggle never judges compatibility against a package that is mid-swap. The lock is a
+     * non-reentrant file lock: no caller holds it around this function (checked 2026-10-21 in this
+     * package and in Tovu's admin route / `plugins_set_enabled` tool).
+     */
+    async function setAgentPluginEnabled(input, _optional = {}) {
+        const workspaceRoot = ports.layout.forWorkspace({ workspaceId: input.workspaceId }).root;
+        // Checked once before locking so an unknown or ungrammatical id stays a not-installed refusal
+        // and never creates workspace or lock directories (the lock path re-asserts the id grammar).
+        await findInstalled({ workspaceRoot, pluginId: input.pluginId });
+        return persistentState.withPluginLock({ workspaceRoot, pluginId: input.pluginId,
+            run: () => setEnabledLocked({ input, workspaceRoot }) });
     }
     return { setAgentPluginEnabled };
 }