@jini-ai/agent-plugins 0.4.6 → 0.4.8

package/dist/lifecycle/compatibility-metadata.js

@@ -0,0 +1,45 @@
+/**
+ * Reads the host-namespace compatibility metadata (`extensions.<ns>.requires` / `hostRange`).
+ *
+ * A leaf on purpose: `manifest.ts` calls this while `compatibility.ts` needs manifest-shaped
+ * types, so keeping the reader here (semver only, no lifecycle imports) keeps the lifecycle
+ * import graph acyclic (`__tests__/type-cycles.test.ts`).
+ */
+import * as semver from 'semver';
+/** Stored in place of a present-but-unusable range so the plugin stays listable but never enables. */
+export const INVALID_AGENT_PLUGIN_HOST_RANGE = '<invalid>';
+/** A blank string is a semver wildcard, so blank is rejected here rather than silently allowed.
+ * The same holds for a blank `||` alternative: semver reads '>=99 ||' as '*', i.e. allow-all. */
+export function isValidAgentPluginHostRange({ range }, _optional = {}) {
+    return range.split('||').every(part => part.trim().length > 0) && semver.validRange(range) !== null;
+}
+function isCapabilityId(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function readRequires({ value, warnings }) {
+    if (value === undefined)
+        return undefined;
+    if (Array.isArray(value) && value.every(isCapabilityId))
+        return [...new Set(value.map(id => id.trim()))];
+    warnings.push('requires must be an array of non-empty capability ids');
+    return undefined;
+}
+function readHostRange({ value, warnings }) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string' && isValidAgentPluginHostRange({ range: value }))
+        return value;
+    warnings.push('hostRange is invalid; enabling this plugin is refused');
+    return INVALID_AGENT_PLUGIN_HOST_RANGE;
+}
+/** Reads metadata in the host-selected namespace. A present malformed range stays incompatible;
+ * malformed `requires` is advisory only, so it is dropped with a warning.
+ * @returns Normalized advisory metadata and parse warnings. @complexity O(r).
+ */
+export function readAgentPluginCompatibilityMetadata({ extension }, _optional = {}) {
+    const warnings = [];
+    const requires = readRequires({ value: extension.requires, warnings });
+    const hostRange = readHostRange({ value: extension.hostRange, warnings });
+    return { ...(requires === undefined ? {} : { requires }), ...(hostRange === undefined ? {} : { hostRange }), warnings };
+}
+//# sourceMappingURL=compatibility-metadata.js.map

package/dist/lifecycle/compatibility.d.ts

@@ -0,0 +1,52 @@
+import type { InstalledAgentPlugin } from './types.js';
+import type { AgentPluginActivations, AgentPluginOrigin } from './activation.js';
+export { readAgentPluginCompatibilityMetadata, isValidAgentPluginHostRange, INVALID_AGENT_PLUGIN_HOST_RANGE } from './compatibility-metadata.js';
+/** Host extension contract, independent of product releases and the upstream manifest schema.
+ * `hostRange` is checked against this, never against an app version. */
+export declare const AGENT_PLUGIN_CONTRACT_VERSION = "1.0.0";
+/** Named refusal shared by HTTP and tool adapters. */
+export declare class AgentPluginHostIncompatibleError extends Error {
+    readonly code = "PLUGIN_HOST_INCOMPATIBLE";
+    constructor(required: {
+        pluginId: string;
+    }, _optional?: Record<string, never>);
+}
+export interface AgentPluginCompatibility {
+    readonly hostOk: boolean;
+    readonly missingRequires: readonly string[];
+}
+/** Projects live metadata, excluding disabled providers and the plugin itself.
+ * @returns Origin, host compatibility, and advisory requirements. @complexity O(p + r).
+ */
+export declare function describeAgentPluginCompatibility({ plugin, installed, activations }: {
+    plugin: InstalledAgentPlugin;
+    installed: readonly InstalledAgentPlugin[];
+    activations: AgentPluginActivations;
+}, { hostVersion }?: {
+    hostVersion?: string;
+}): AgentPluginCompatibility & {
+    readonly origin: AgentPluginOrigin;
+};
+/** Names active dependents that would lose a capability after disabling or updating a provider.
+ * Other enabled providers can satisfy the same requirement. Advisory only. @complexity O(p * (p + r)).
+ */
+export declare function agentPluginDependentWarnings({ plugin, installed, activations, nextProvides }: {
+    plugin: InstalledAgentPlugin;
+    installed: readonly InstalledAgentPlugin[];
+    activations: AgentPluginActivations;
+    nextProvides: readonly string[];
+}, _optional?: Record<string, never>): string[];
+/** Checks the declared host contract and advisory capabilities; never throws for a bad range.
+ * Callers supply capabilities from other enabled plugins only (no self-satisfaction).
+ * Uses `semver.satisfies` with default options, the same check site plugins apply to `sdkRange`.
+ * @returns Compatibility plus unmet advisory requirements. @complexity O(r + p).
+ */
+export declare function checkAgentPluginCompatibility({ manifest, hostVersion, activeProvides }: {
+    readonly manifest: {
+        readonly hostRange?: string | undefined;
+        readonly requires?: readonly string[] | undefined;
+    };
+    readonly hostVersion: string;
+    readonly activeProvides: readonly string[];
+}, _optional?: Record<string, never>): AgentPluginCompatibility;
+//# sourceMappingURL=compatibility.d.ts.map

package/dist/lifecycle/compatibility.js

@@ -0,0 +1,60 @@
+import * as semver from 'semver';
+import { isValidAgentPluginHostRange } from './compatibility-metadata.js';
+export { readAgentPluginCompatibilityMetadata, isValidAgentPluginHostRange, INVALID_AGENT_PLUGIN_HOST_RANGE } from './compatibility-metadata.js';
+/** Host extension contract, independent of product releases and the upstream manifest schema.
+ * `hostRange` is checked against this, never against an app version. */
+export const AGENT_PLUGIN_CONTRACT_VERSION = '1.0.0';
+/** Named refusal shared by HTTP and tool adapters. */
+export class AgentPluginHostIncompatibleError extends Error {
+    code = 'PLUGIN_HOST_INCOMPATIBLE';
+    constructor(required, _optional = {}) {
+        super(`Plugin '${required.pluginId}' is not compatible with this host's Agent Plugin contract.`);
+        this.name = 'AgentPluginHostIncompatibleError';
+    }
+}
+/** Same rule as activation.ts `isAgentPluginActive`: an absent activation record means active. */
+function isActive({ activations, pluginId }) {
+    return !Object.hasOwn(activations.plugins, pluginId) || activations.plugins[pluginId].enabled;
+}
+/** Active plugins other than `excludeId`, so a plugin never satisfies its own requirements. */
+function activeOthers({ installed, activations, excludeId }) {
+    return installed.filter(other => other.pluginId !== excludeId && isActive({ activations, pluginId: other.pluginId }));
+}
+function providedBy({ plugins }) {
+    return plugins.flatMap(plugin => plugin.provides ?? []);
+}
+/** Projects live metadata, excluding disabled providers and the plugin itself.
+ * @returns Origin, host compatibility, and advisory requirements. @complexity O(p + r).
+ */
+export function describeAgentPluginCompatibility({ plugin, installed, activations }, { hostVersion = AGENT_PLUGIN_CONTRACT_VERSION } = {}) {
+    const activeProvides = providedBy({ plugins: activeOthers({ installed, activations, excludeId: plugin.pluginId }) });
+    const origin = Object.hasOwn(activations.plugins, plugin.pluginId) ? activations.plugins[plugin.pluginId].origin : 'operator-installed';
+    return { origin, ...checkAgentPluginCompatibility({ manifest: plugin, hostVersion, activeProvides }) };
+}
+/** Requirements of `dependent` that only the removed capabilities satisfied. */
+function lostRequirements({ dependent, providers, removed }) {
+    const available = new Set(providedBy({ plugins: providers.filter(provider => provider.pluginId !== dependent.pluginId) }));
+    return [...new Set(dependent.requires ?? [])].filter(id => removed.has(id) && !available.has(id));
+}
+/** Names active dependents that would lose a capability after disabling or updating a provider.
+ * Other enabled providers can satisfy the same requirement. Advisory only. @complexity O(p * (p + r)).
+ */
+export function agentPluginDependentWarnings({ plugin, installed, activations, nextProvides }, _optional = {}) {
+    const removed = new Set((plugin.provides ?? []).filter(id => !nextProvides.includes(id)));
+    const others = activeOthers({ installed, activations, excludeId: plugin.pluginId });
+    // One dependent id may have several installed digests; report each lost capability once.
+    return [...new Set(others.flatMap(dependent => lostRequirements({ dependent, providers: others, removed })
+            .map(id => `${dependent.pluginId} needs ${id}`)))];
+}
+/** Checks the declared host contract and advisory capabilities; never throws for a bad range.
+ * Callers supply capabilities from other enabled plugins only (no self-satisfaction).
+ * Uses `semver.satisfies` with default options, the same check site plugins apply to `sdkRange`.
+ * @returns Compatibility plus unmet advisory requirements. @complexity O(r + p).
+ */
+export function checkAgentPluginCompatibility({ manifest, hostVersion, activeProvides }, _optional = {}) {
+    const available = new Set(activeProvides);
+    const range = manifest.hostRange;
+    const hostOk = range === undefined || (isValidAgentPluginHostRange({ range }) && semver.satisfies(hostVersion, range));
+    return { hostOk, missingRequires: [...new Set(manifest.requires ?? [])].filter(id => !available.has(id)) };
+}
+//# sourceMappingURL=compatibility.js.map

package/dist/lifecycle/fetch-archive.js

@@ -57,12 +57,28 @@ export async function fetchAgentPluginArchive(required, optional = {}) {
         throw new RangeError("maxBytes must be a positive integer");
     assertAllowedUrl(required.url, "requested");
     const diagnosticUrl = redactArchiveUrl({ value: required.url });
-    let response;
-    let finalRequestedUrl = required.url;
+    const { response, resolvedUrl: finalRequestedUrl } = await requestArchive({ required, diagnosticUrl }, optional);
+    // A server-controlled reason phrase can reflect secrets; use the standard status label.
+    if (!response.ok) {
+        throw new AgentPluginFetchError({ code: "HTTP_ERROR", message: `'${diagnosticUrl}' returned HTTP ${response.status} ${STATUS_CODES[response.status] ?? ''}`.trimEnd() });
+    }
+    const resolvedUrl = response.url || finalRequestedUrl;
+    assertAllowedUrl(resolvedUrl, "redirected-to");
+    assertDeclaredSizeWithinCap(response, maxBytes, diagnosticUrl);
+    const archive = await readArchiveBody({ response, maxBytes, diagnosticUrl });
+    if (archive.byteLength === 0) {
+        throw new AgentPluginFetchError({ code: "EMPTY_BODY", message: `'${diagnosticUrl}' returned an empty body` });
+    }
+    return {
+        archive,
+        sha256: createHash("sha256").update(archive).digest("hex"),
+        resolvedUrl,
+    };
+}
+/** Runs the guarded request; any failure becomes one redacted `REQUEST_FAILED`. */
+async function requestArchive({ required, diagnosticUrl }, optional = {}) {
     try {
-        const downloaded = await fetchWithGuard(required, optional);
-        response = downloaded.response;
-        finalRequestedUrl = downloaded.resolvedUrl;
+        return await fetchWithGuard(required, optional);
     }
     catch {
         // Dependency messages and nested causes can contain signed redirect URLs or bare tokens.
@@ -71,16 +87,11 @@ export async function fetchAgentPluginArchive(required, optional = {}) {
             cause: new Error("archive request failed"),
         });
     }
-    // A server-controlled reason phrase can reflect secrets; use the standard status label.
-    if (!response.ok) {
-        throw new AgentPluginFetchError({ code: "HTTP_ERROR", message: `'${diagnosticUrl}' returned HTTP ${response.status} ${STATUS_CODES[response.status] ?? ''}`.trimEnd() });
-    }
-    const resolvedUrl = response.url || finalRequestedUrl;
-    assertAllowedUrl(resolvedUrl, "redirected-to");
-    assertDeclaredSizeWithinCap(response, maxBytes, diagnosticUrl);
-    let archive;
+}
+/** Reads the body within the cap; an over-cap body stays `ARCHIVE_TOO_LARGE`, anything else one redacted `REQUEST_FAILED`. */
+async function readArchiveBody({ response, maxBytes, diagnosticUrl }) {
     try {
-        archive = await readBodyWithinCap(response, maxBytes, diagnosticUrl);
+        return await readBodyWithinCap(response, maxBytes, diagnosticUrl);
     }
     catch (error) {
         // Preserve our bounded-download error; stream failures must not escape as raw transport text.
@@ -91,14 +102,6 @@ export async function fetchAgentPluginArchive(required, optional = {}) {
             cause: new Error("archive response body failed"),
         });
     }
-    if (archive.byteLength === 0) {
-        throw new AgentPluginFetchError({ code: "EMPTY_BODY", message: `'${diagnosticUrl}' returned an empty body` });
-    }
-    return {
-        archive,
-        sha256: createHash("sha256").update(archive).digest("hex"),
-        resolvedUrl,
-    };
 }
 /**
  * The module's own cap, exported so a caller (or a test pinning it against `install.ts`'s
@@ -150,10 +153,9 @@ async function readBodyWithinCap(response, maxBytes, url) {
     try {
         for (;;) {
             const { done, value } = await reader.read();
+            // A read that is not `done` always carries a chunk (`ReadableStreamReadValueResult`).
             if (done)
                 break;
-            if (value === undefined)
-                continue;
             total += value.byteLength;
             if (total > maxBytes) {
                 throw new AgentPluginFetchError({ code: "ARCHIVE_TOO_LARGE", message: `'${url}' body exceeded the ${maxBytes}-byte cap` });

package/dist/lifecycle/index.d.ts

@@ -1,3 +1,8 @@
+export * from './update-plan.js';
+export { AgentPluginUpdateError } from './update-store.js';
+export type { UpdateAgentPluginRequired, UpdateAgentPluginResult } from './update.js';
+export * from './compatibility.js';
+export * from './automatic-use.js';
 import { maxAgentPluginArchiveBytes } from './fetch-archive.js';
 import type { FetchAgentPluginArchiveOptional } from './fetch-archive.js';
 import type { AgentPluginLifecycleRequired, AgentPluginLifecycleOptional } from './ports.js';
@@ -13,6 +18,7 @@ export * from './manifest.js';
 export * from './fetch-archive.js';
 export * from './mcp-provisioning.js';
 export * from './contribution-loader.js';
+export * from './provider-contribution.js';
 export { createAgentPluginActivations, ACTIVATIONS_FILENAME, ACTIVATIONS_LOCK_FILENAME, AgentPluginActivationsBusyError, AgentPluginActivationsUnreadableError } from './activation.js';
 export { BUNDLED_DIGESTS_FILENAME } from './bundled-digests.js';
 export { AgentPluginInstallError } from './install.js';
@@ -72,7 +78,7 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
     }) => Promise<boolean>;
     installAgentPlugin: (required: import("./install.js").InstallAgentPluginRequired, optional?: import("./install.js").InstallAgentPluginOptional) => Promise<import("./types.js").InstalledAgentPlugin>;
     installAgentPluginFromUrl: (required: import("./install-from-url.js").InstallAgentPluginFromUrlRequired, optional?: import("./install-from-url.js").InstallAgentPluginFromUrlOptional) => Promise<import("./install-from-url.js").InstalledAgentPluginFromUrl>;
-    setAgentPluginEnabled: (input: import("./set-enabled.js").SetAgentPluginEnabledInput) => Promise<import("./set-enabled.js").SetAgentPluginEnabledResult>;
+    setAgentPluginEnabled: (input: import("./set-enabled.js").SetAgentPluginEnabledInput, _optional?: Record<string, never>) => Promise<import("./set-enabled.js").SetAgentPluginEnabledResult>;
     findTrustedPluginPackages: (input: Omit<Parameters<(query: import("./trusted-plugin-files.js").TrustedPluginPackagesQuery) => Promise<readonly import("./trusted-plugin-files.js").TrustedPluginVerdict[]>>[0], "orderByPluginId" | "onInactive">, optional?: Pick<Parameters<(query: import("./trusted-plugin-files.js").TrustedPluginPackagesQuery) => Promise<readonly import("./trusted-plugin-files.js").TrustedPluginVerdict[]>>[0], "orderByPluginId" | "onInactive">) => Promise<readonly import("./trusted-plugin-files.js").TrustedPluginVerdict[]>;
     previewAgentPluginUninstall: (required: import("./uninstall.js").UninstallAgentPluginRequired) => Promise<import("./uninstall.js").AgentPluginUninstallPreview>;
     uninstallAgentPlugin: (required: import("./uninstall.js").UninstallAgentPluginRequired, optional?: import("./uninstall.js").UninstallAgentPluginOptional) => Promise<import("./uninstall.js").UninstallAgentPluginResult>;
@@ -176,8 +182,10 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
     }) => Promise<boolean>;
     rankInstalledAgentPlugins: (input: {
         readonly query: string;
-        readonly candidates: Parameters<(query: string, candidates: readonly import("./search.js").AgentPluginSearchCandidate[], limit: number) => readonly import("./search.js").AgentPluginSearchMatch[]>[1];
+        readonly candidates: Parameters<(query: string, candidates: readonly import("./search.js").AgentPluginSearchCandidate[], limit: number, automatic?: boolean) => readonly import("./search.js").AgentPluginSearchMatch[]>[1];
         readonly limit: number;
+    }, optional?: {
+        readonly automatic?: boolean;
     }) => readonly import("./search.js").AgentPluginSearchMatch[];
     readTrustedPluginFile: (input: {
         readonly plugin: Parameters<(plugin: import("./trusted-plugin-files.js").TrustedPluginPackage, filename: string) => Promise<string>>[0];
@@ -208,5 +216,9 @@ export declare function createAgentPluginLifecycle(required: AgentPluginLifecycl
         readonly plugin: import("./trusted-plugin-files.js").TrustedPluginPackage;
         readonly definition: import("./contribution-loader.js").PluginContributionDefinition<D, T>;
     }, _options?: Record<string, never>) => Promise<import("./contribution-loader.js").PluginContributionResult<T>>;
+    updateAgentPlugin: (required: import("./update.js").UpdateAgentPluginRequired, _optional?: Record<string, never>) => Promise<import("./update.js").UpdateAgentPluginResult>;
+    reconcileAgentPluginUpdates: ({ workspaceId }: {
+        workspaceId: string;
+    }, _optional?: Record<string, never>) => Promise<void>;
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.js

@@ -1,3 +1,8 @@
+export * from './update-plan.js';
+export { AgentPluginUpdateError } from './update-store.js';
+import { createUpdateModule } from './update.js';
+export * from './compatibility.js';
+export * from './automatic-use.js';
 import { createPersistentStateModule } from "./persistent-state.js";
 import { fetchAgentPluginArchive, maxAgentPluginArchiveBytes } from './fetch-archive.js';
 import { createSeedBundledModule } from './seed-bundled.js';
@@ -22,6 +27,7 @@ export * from './manifest.js';
 export * from './fetch-archive.js';
 export * from './mcp-provisioning.js';
 export * from './contribution-loader.js';
+export * from './provider-contribution.js';
 export { createAgentPluginActivations, ACTIVATIONS_FILENAME, ACTIVATIONS_LOCK_FILENAME, AgentPluginActivationsBusyError, AgentPluginActivationsUnreadableError } from './activation.js';
 export { BUNDLED_DIGESTS_FILENAME } from './bundled-digests.js';
 export { AgentPluginInstallError } from './install.js';
@@ -56,6 +62,7 @@ export function createAgentPluginLifecycle(required, optional = {}) {
     });
     const uninstall = createUninstallModule(context);
     return {
+        ...createUpdateModule(context),
         ...contributions,
         fetchAgentPluginArchive: (input, optional = {}) => fetchAgentPluginArchive({ ...input, fetch: context.fetch, outboundGuard: context.outboundGuard }, optional),
         maxAgentPluginArchiveBytes,
@@ -102,7 +109,7 @@ export function createAgentPluginLifecycle(required, optional = {}) {
         }),
         listInstalledPlugins: (input) => refs.listInstalledPlugins(input.workspaceRoot),
         isInstalledDigestPresent: (input) => refs.isInstalledDigestPresent(input.packagesDir, input.archiveDigest),
-        rankInstalledAgentPlugins: (input) => search.rankInstalledAgentPlugins(input.query, input.candidates, input.limit),
+        rankInstalledAgentPlugins: (input, optional = {}) => search.rankInstalledAgentPlugins(input.query, input.candidates, input.limit, optional.automatic),
         readTrustedPluginFile: (input) => trusted.readTrustedPluginFile(input.plugin, input.filename),
         importContainedModule: (input) => trusted.importContainedModule(input.plugin, input.modulePath),
         maxAgentPluginInstallArchiveBytes: (_input) => install.maxAgentPluginInstallArchiveBytes(),

package/dist/lifecycle/install-errors.d.ts

@@ -0,0 +1,14 @@
+/** One extraction/install failure reason. A caller (an admin route, a future marketplace installer)
+ * branches on `code` rather than parsing `message` — this codebase's own convention
+ * (`PluginLoadError.reason` in `plugin-runtime/loader.ts` is the direct precedent). */
+export type AgentPluginInstallErrorCode = "PLUGIN_ID_CONFLICT" | "ARCHIVE_TOO_LARGE" | "DIGEST_MISMATCH" | "TOO_MANY_ENTRIES" | "UNSAFE_ENTRY_PATH" | "SYMLINK_ENTRY_REJECTED" | "UNSUPPORTED_ENTRY_KIND" | "DUPLICATE_ENTRY" | "FILE_TOO_LARGE" | "DECOMPRESSION_BOMB" | "TOTAL_SIZE_EXCEEDED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "PUBLISH_FAILED";
+export declare class AgentPluginInstallError extends Error {
+    readonly code: AgentPluginInstallErrorCode;
+    constructor({ code, message }: {
+        readonly code: AgentPluginInstallErrorCode;
+        readonly message: string;
+    }, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=install-errors.d.ts.map

package/dist/lifecycle/install-errors.js

@@ -0,0 +1,9 @@
+export class AgentPluginInstallError extends Error {
+    code;
+    constructor({ code, message }, options = {}) {
+        super(message, options);
+        this.name = "AgentPluginInstallError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=install-errors.js.map

package/dist/lifecycle/install.d.ts

@@ -2,19 +2,8 @@ import type { AgentPluginLayout } from "./layout.js";
 import type { AgentPluginLifecyclePorts } from "./ports.js";
 import type { InstalledAgentPlugin } from "./types.js";
 export type { InstalledAgentPlugin, InstalledAgentPluginSkill } from "./types.js";
-/** One extraction/install failure reason. A caller (an admin route, a future marketplace installer)
- * branches on `code` rather than parsing `message` — this codebase's own convention
- * (`PluginLoadError.reason` in `plugin-runtime/loader.ts` is the direct precedent). */
-export type AgentPluginInstallErrorCode = "PLUGIN_ID_CONFLICT" | "ARCHIVE_TOO_LARGE" | "DIGEST_MISMATCH" | "TOO_MANY_ENTRIES" | "UNSAFE_ENTRY_PATH" | "SYMLINK_ENTRY_REJECTED" | "UNSUPPORTED_ENTRY_KIND" | "DUPLICATE_ENTRY" | "FILE_TOO_LARGE" | "DECOMPRESSION_BOMB" | "TOTAL_SIZE_EXCEEDED" | "MANIFEST_MISSING" | "MANIFEST_INVALID" | "PUBLISH_FAILED";
-export declare class AgentPluginInstallError extends Error {
-    readonly code: AgentPluginInstallErrorCode;
-    constructor({ code, message }: {
-        readonly code: AgentPluginInstallErrorCode;
-        readonly message: string;
-    }, options?: {
-        cause?: unknown;
-    });
-}
+export { AgentPluginInstallError } from "./install-errors.js";
+export type { AgentPluginInstallErrorCode } from "./install-errors.js";
 /** One archive entry. A symlink is modeled as its OWN kind rather than folded into "file" — the
  * zip-slip research this module's header cites is explicit that the symlink-entry vector is
  * distinct from the lexical-traversal one, and the two need independent tests and independent

package/dist/lifecycle/install.js

@@ -1,5 +1,7 @@
 import { listInstalledPackageRoots } from "./installed-package-roots.js";
 import { createUninstallModule } from "./uninstall.js";
+import { AgentPluginInstallError } from "./install-errors.js";
+import { createInstalledPackageIndex } from "./installed-package-index.js";
 import { readPluginIdentity, assertPluginIdentityAvailable } from "@jini-ai/core/plugin-directory";
 /**
  * @file `installAgentPlugin()` — content-addressed, adversarially-hardened extraction of one Agent
@@ -60,33 +62,15 @@ import { readPluginIdentity, assertPluginIdentityAvailable } from "@jini-ai/core
  * (archive bytes and their expected digest are caller-supplied — see the module header above for why
  * "how does the archive get here" is out of this slice) and no execution of anything extracted.
  */
-/** One trimmed, non-blank string field of the host-supplied extension namespace, capped at `maxLength`, else
- *  `undefined` — a malformed value falls back rather than failing the whole index, since every
- *  field read this way is cosmetic. The cap stops a hostile package flooding the admin row.
- *  @complexity O(maxLength). */
-/** `{ displayName }` when the host namespace's `displayName` is a non-blank string, else `{}` (callers
- *  title-case the id).
- *  @complexity O(1). */
-/** `{ summary }` when the host namespace's `summary` is a non-blank string, else `{}` (the admin shows
- *  the spec `description` instead). Inner newlines are kept: blank lines are the paragraph breaks
- *  the admin renders.
- *  @complexity O(1). */
 import { createPersistentStateModule } from "./persistent-state.js";
+import { createAgentPluginUpdateStore, settleAgentPluginUpdateJournal } from "./update-store.js";
 /** Extracted from the host plugin lifecycle. Effects are supplied per host context. */
 import { createHash } from "node:crypto";
 import { constants } from "node:fs";
 import path from "node:path";
-import { readAgentPluginExtension, parseAgentPluginManifest as parseAgentPluginManifestValue } from "./manifest.js";
 import { PackagePathViolation } from "./package-paths.js";
 import { createPackagePathsModule } from "./package-paths.js";
-export class AgentPluginInstallError extends Error {
-    code;
-    constructor({ code, message }, options = {}) {
-        super(message, options);
-        this.name = "AgentPluginInstallError";
-        this.code = code;
-    }
-}
+export { AgentPluginInstallError } from "./install-errors.js";
 function buildModule(ports) {
     const persistentState = createPersistentStateModule(ports);
     const chmod = ports.filesystem.chmod.bind(ports.filesystem);
@@ -98,7 +82,8 @@ function buildModule(ports) {
     const rename = ports.filesystem.rename.bind(ports.filesystem);
     const rm = ports.filesystem.rm.bind(ports.filesystem);
     const stat = ports.filesystem.stat.bind(ports.filesystem);
-    const parseAgentPluginManifest = (value) => parseAgentPluginManifestValue({ value }, { identityNamespace: ports.extensionNamespace });
+    const index = createInstalledPackageIndex({ ports });
+    const indexInstalledRoot = (packageRoot, archiveDigest) => index.indexInstalledRoot({ packageRoot, archiveDigest });
     const { assertContainedOnDisk, normalizePackageEntryPath } = createPackagePathsModule(ports);
     const LIMITS = {
         maxArchiveBytes: 32 * 1024 * 1024,
@@ -145,7 +130,6 @@ function buildModule(ports) {
      */
     async function pruneSupersededRevisions({ workspaceRoot, installed }, _optional = {}) {
         try {
-            // Resolve lazily: uninstall's read-side index uses this install module for manifest indexing.
             const removal = createUninstallModule(ports);
             for (const root of await listInstalledPackageRoots({ ports, workspaceRoot })) {
                 if (root.localId !== installed.pluginId || root.archiveDigest === installed.archiveDigest)
@@ -213,6 +197,12 @@ function buildModule(ports) {
             return await persistentState.withIdentityLock({ workspaceRoot: workspaceLayout.root, run: async () => {
                     await assertIdentityAvailable(workspaceLayout.root, indexed);
                     const publishWithinPluginLock = () => persistentState.withPluginLock({ workspaceRoot: workspaceLayout.root, pluginId: indexed.pluginId, run: async () => {
+                            // Every install and replacement, not only an update, is a mutation of this plugin: an
+                            // unfinished update journal refuses it here, under the same plugin lock, because boot
+                            // recovery removes only the journal's own candidate digest and would otherwise restore the
+                            // old revision beside whatever this install published.
+                            // The journal lives under the layout this install was given, the one it publishes into.
+                            await settleAgentPluginUpdateJournal({ store: createAgentPluginUpdateStore({ ports: { ...ports, layout }, workspaceId, pluginId: indexed.pluginId }) });
                             // Layout B needs the manifest id before choosing the package destination. Dedup still
                             // skips publication and freezing, after one bounded staging extraction.
                             // Owner decision 2026-10-04: learned facts begin empty for each site; author guidance stays
@@ -400,107 +390,6 @@ function buildModule(ports) {
         }
         return totalBytes;
     }
-    /** Cosmetic fields are trimmed and capped rather than invalidating the package. The cap stops
-     * a hostile package flooding an admin row. Inner newlines remain paragraph breaks in summaries.
-     * @complexity O(n) in the supplied text length; output is capped at maxLength. */
-    function readDisplayText(required, _optional = {}) {
-        const text = readAgentPluginExtension({ manifest: required.manifest, namespace: ports.extensionNamespace,
-            read: ({ value }) => {
-                const field = value[required.key];
-                return typeof field === 'string' ? field.trim() : undefined;
-            } });
-        return text ? { [required.key]: text.slice(0, required.maxLength) } : {};
-    }
-    /**
-   * Reads the (already-extracted-and-trusted, or already-published) `plugin.json` at `packageRoot`
-   * and walks the tree to build the `files`/`skills` index. Shared between a fresh install and the
-   * content-addressed dedup fast path so both return an identically-shaped result.
-   *
-   * Exported (2026-08-21) for a second caller outside this module:
-   * `resolve-agent-plugin-refs.ts`'s run-time resolution of a pinned `pluginRefId` against the
-   * packages already on disk needs the SAME `plugin.json`-parse-plus-tree-walk this function
-   * already does correctly (manifest validation via `parseAgentPluginManifest`, sorted `files`), so
-   * it re-derives an `InstalledAgentPlugin` per installed digest rather than hand-rolling a second,
-   * less-validated reader.
-   */
-    // Conditional spreads, not `field: parsed.manifest.field` directly: an `exactOptionalPropertyTypes`-
-    // style caller (and this codebase's own convention elsewhere — see `buildToolSource`'s identical
-    // `defaultSkillReason` spread in `tool-registrations.ts`) must see an ABSENT key, not a key present
-    // with value `undefined`, when the manifest declared none of these — `deepEqual` fixtures across
-    // this feature's own tests already assert exact object shape.
-    async function indexInstalledRoot(packageRoot, /** SHA-256 of the raw archive bytes — the content-addressing key and the descriptor `revision`
-     * a future capability projection pins invocation to (`capability-projection.ts`). */ archiveDigest) {
-        let manifestRaw;
-        try {
-            manifestRaw = await readFile(path.join(packageRoot, "plugin.json"), "utf8");
-        }
-        catch (error) {
-            if (isErrnoException(error) && error.code === "ENOENT") {
-                throw new AgentPluginInstallError({ code: "MANIFEST_MISSING", message: "the archive does not contain a plugin.json at its root" });
-            }
-            throw error;
-        }
-        let manifestValue;
-        try {
-            manifestValue = JSON.parse(manifestRaw);
-        }
-        catch (error) {
-            throw new AgentPluginInstallError({ code: "MANIFEST_INVALID", message: "plugin.json is not valid JSON" }, { cause: error });
-        }
-        const parsed = parseAgentPluginManifest(manifestValue);
-        if (!parsed.ok) {
-            throw new AgentPluginInstallError({ code: "MANIFEST_INVALID", message: `plugin.json failed validation: ${parsed.errors.join("; ")}` });
-        }
-        const files = [];
-        for (const message of parsed.warnings)
-            ports.onEvent?.({ event: 'agent-plugin-identity-warning', message });
-        const skills = [];
-        async function walk(absolute, prefix) {
-            for (const entry of await readdir(absolute, { withFileTypes: true })) {
-                const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
-                if (entry.isDirectory()) {
-                    await walk(path.join(absolute, entry.name), relative);
-                }
-                else if (entry.isFile()) {
-                    files.push(relative);
-                    const match = relative.match(/^skills\/([^/]+)\/SKILL\.md$/);
-                    if (match)
-                        skills.push({ name: match[1], skillPath: relative });
-                }
-                // Anything that is neither a directory nor a regular file (a symlink somehow already present,
-                // a device node) is skipped rather than indexed — extraction itself never creates one, so
-                // encountering one here would mean the filesystem changed out from under an already-published,
-                // supposedly-frozen package, which this function has no business acting on either way.
-            }
-        }
-        await walk(packageRoot, "");
-        return {
-            pluginId: parsed.manifest.name,
-            id: parsed.manifest.id,
-            provides: parsed.manifest.provides,
-            version: parsed.manifest.version,
-            ...( /**
-         * `plugin.json`'s own `description`/`keywords`/`author`/`license` (`manifest.ts`'s
-         * `AgentPluginManifest`) — parsed at index time but, before 2026-09-09, discarded immediately
-         * after: only `name`/`version` ever reached `InstalledAgentPlugin`. Added for
-         * `search_agent_plugin_local` (`tool-registrations.ts`), which needs the description and the
-         * author-curated keywords to rank installed plugins against a free-text query — the manifest is
-         * already read and parsed here on every call, so carrying these through is zero additional I/O,
-         * not a new read path. All four are optional because the spec itself makes them optional (the real
-         * installed `ui-ux-design` fixture ships `description` but no `keywords`; a bare-minimum manifest
-         * ships neither) — a caller must not assume any of them are present.
-         */parsed.manifest.description !== undefined ? { description: parsed.manifest.description } : {}),
-            ...(parsed.manifest.keywords !== undefined ? { keywords: parsed.manifest.keywords } : {}),
-            ...(parsed.manifest.author !== undefined ? { author: parsed.manifest.author } : {}),
-            ...(parsed.manifest.license !== undefined ? { license: parsed.manifest.license } : {}),
-            ...readDisplayText({ manifest: parsed.manifest, key: "displayName", maxLength: 64 }),
-            ...readDisplayText({ manifest: parsed.manifest, key: "summary", maxLength: 1200 }),
-            archiveDigest,
-            packageRoot,
-            files: files.sort(),
-            skills: skills.sort((a, b) => a.name.localeCompare(b.name)),
-        };
-    }
     /** Makes every file/directory under `root` read-only (executables keep `+x`, per the Agent Plugins
    * spec's own MCP `command` needing to launch a `./`-relative script — not exercised by anything in
    * this slice, since MCP execution is out of scope for v1, but the bit is preserved now rather than

package/dist/lifecycle/installed-package-index.d.ts

@@ -0,0 +1,15 @@
+import type { AgentPluginLifecyclePorts } from "./ports.js";
+import type { InstalledAgentPlugin } from "./types.js";
+/** Indexes manifests and files with the same injected effects used by installation and resolution.
+ * @complexity O(f) reads/walk work for f package files; no mutation or executable imports. */
+export declare function createInstalledPackageIndex(required: {
+    readonly ports: AgentPluginLifecyclePorts;
+}, _optional?: Record<string, never>): {
+    indexInstalledRoot: ({ packageRoot, archiveDigest }: {
+        readonly packageRoot: string;
+        /** SHA-256 of the raw archive bytes — the content-addressing key and the descriptor `revision`
+         * a future capability projection pins invocation to (`capability-projection.ts`). */
+        readonly archiveDigest: string;
+    }, _optional?: Record<string, never>) => Promise<InstalledAgentPlugin>;
+};
+//# sourceMappingURL=installed-package-index.d.ts.map