@jini-ai/agent-plugins 0.4.7 → 0.4.8

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.js

@@ -63,6 +63,7 @@ import { readPluginIdentity, assertPluginIdentityAvailable } from "@jini-ai/core
  * "how does the archive get here" is out of this slice) and no execution of anything extracted.
  */
 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";
@@ -196,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

package/dist/lifecycle/installed-package-index.js

@@ -22,24 +22,8 @@ export function createInstalledPackageIndex(required, _optional = {}) {
             } });
         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, archiveDigest }, _optional = {}) {
+    /** Reads and validates `packageRoot`'s `plugin.json`, refusing a missing, unparseable or invalid one. */
+    async function readInstalledManifest({ packageRoot }) {
         let manifestRaw;
         try {
             manifestRaw = await readFile(path.join(packageRoot, "plugin.json"), "utf8");
@@ -61,22 +45,19 @@ export function createInstalledPackageIndex(required, _optional = {}) {
         if (!parsed.ok) {
             throw new AgentPluginInstallError({ code: "MANIFEST_INVALID", message: `plugin.json failed validation: ${parsed.errors.join("; ")}` });
         }
+        return parsed;
+    }
+    /** Every regular file under `packageRoot` (sorted) and every `skills/<name>/SKILL.md` (sorted by name). */
+    async function walkPackageTree({ packageRoot }) {
         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()) {
+                if (entry.isDirectory())
                     await walk(path.join(absolute, entry.name), relative);
-                }
-                else if (entry.isFile()) {
+                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,
@@ -84,10 +65,41 @@ export function createInstalledPackageIndex(required, _optional = {}) {
             }
         }
         await walk(packageRoot, "");
+        for (const relative of files) {
+            const match = relative.match(/^skills\/([^/]+)\/SKILL\.md$/);
+            if (match)
+                skills.push({ name: match[1], skillPath: relative });
+        }
+        return { files: files.sort(), skills: skills.sort((a, b) => a.name.localeCompare(b.name)) };
+    }
+    /**
+   * 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, archiveDigest }, _optional = {}) {
+        const parsed = await readInstalledManifest({ packageRoot });
+        for (const message of parsed.warnings)
+            ports.onEvent?.({ event: 'agent-plugin-identity-warning', message });
+        const { files, skills } = await walkPackageTree({ packageRoot });
         return {
             pluginId: parsed.manifest.name,
             id: parsed.manifest.id,
             provides: parsed.manifest.provides,
+            ...(parsed.manifest.requires === undefined ? {} : { requires: parsed.manifest.requires }),
+            ...(parsed.manifest.hostRange === undefined ? {} : { hostRange: parsed.manifest.hostRange }),
             version: parsed.manifest.version,
             ...( /**
          * `plugin.json`'s own `description`/`keywords`/`author`/`license` (`manifest.ts`'s
@@ -107,8 +119,8 @@ export function createInstalledPackageIndex(required, _optional = {}) {
             ...readDisplayText({ manifest: parsed.manifest, key: "summary", maxLength: 1200 }),
             archiveDigest,
             packageRoot,
-            files: files.sort(),
-            skills: skills.sort((a, b) => a.name.localeCompare(b.name)),
+            files,
+            skills,
         };
     }
     return { indexInstalledRoot };

package/dist/lifecycle/installed-package-roots.js

@@ -9,12 +9,14 @@ export const INSTALLED_PLUGIN_DIGEST_PATTERN = /^[a-f0-9]{64}$/;
  * @complexity O(d) directory/containment operations for d revisions; no executable imports.
  */
 export async function listInstalledPackageRoots({ ports, workspaceRoot }, _optional = {}) {
-    const persistentState = createPersistentStateModule(ports);
-    const { assertContainedOnDisk } = createPackagePathsModule(ports);
-    const readdir = ports.filesystem.readdir.bind(ports.filesystem);
+    const effects = {
+        readdir: ports.filesystem.readdir.bind(ports.filesystem),
+        assertOwnedPath: createPersistentStateModule(ports).assertOwnedPath,
+        assertContainedOnDisk: createPackagePathsModule(ports).assertContainedOnDisk,
+    };
     let folders;
     try {
-        folders = await readdir(workspaceRoot, { withFileTypes: true });
+        folders = await effects.readdir(workspaceRoot, { withFileTypes: true });
     }
     catch (error) {
         if (isEnoent(error))
@@ -25,25 +27,31 @@ export async function listInstalledPackageRoots({ ports, workspaceRoot }, _optio
     for (const folder of folders) {
         if (!folder.isDirectory() || !/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(folder.name) || folder.name.length > 64)
             continue;
-        const packagesDir = path.join(workspaceRoot, folder.name, 'package', 'sha256');
-        let entries;
+        roots.push(...await listFolderRevisions({ effects, workspaceRoot, localId: folder.name }));
+    }
+    return roots;
+}
+/** One plugin folder's contained digest revisions; a folder with no owned package store has none. */
+async function listFolderRevisions({ effects, workspaceRoot, localId }) {
+    const packagesDir = path.join(workspaceRoot, localId, 'package', 'sha256');
+    let entries;
+    try {
+        await effects.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
+        entries = await effects.readdir(packagesDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const roots = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !INSTALLED_PLUGIN_DIGEST_PATTERN.test(entry.name))
+            continue;
         try {
-            await persistentState.assertOwnedPath({ workspaceRoot, entryPath: path.relative(workspaceRoot, packagesDir) });
-            entries = await readdir(packagesDir, { withFileTypes: true });
+            const packageRoot = await effects.assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, path.join(packagesDir, entry.name)));
+            roots.push({ localId, archiveDigest: entry.name, packageRoot });
         }
         catch {
-            continue;
-        }
-        for (const entry of entries) {
-            if (!entry.isDirectory() || !INSTALLED_PLUGIN_DIGEST_PATTERN.test(entry.name))
-                continue;
-            try {
-                const packageRoot = await assertContainedOnDisk(workspaceRoot, path.relative(workspaceRoot, path.join(packagesDir, entry.name)));
-                roots.push({ localId: folder.name, archiveDigest: entry.name, packageRoot });
-            }
-            catch {
-                // One corrupt package never hides another plugin. Memory-only folders are not installs.
-            }
+            // One corrupt package never hides another plugin. Memory-only folders are not installs.
         }
     }
     return roots;

package/dist/lifecycle/manifest.d.ts

@@ -8,6 +8,15 @@ export type AgentPluginServerMetadataReader = (required: {
     readonly value: Readonly<Record<string, unknown>>;
     readonly server: Readonly<Record<string, unknown>>;
 }) => Readonly<Record<string, unknown>>;
+/**
+ * True when `value` is a valid Agent Plugin id: `plugin.json`'s `name` grammar (§5.5, see
+ * `NAME_PATTERN`), 1-64 characters. The one owner of that grammar: a host checks an id taken from a
+ * URL or a tool input here before it names anything on disk, instead of restating the pattern.
+ * @complexity O(n) in the value's length.
+ */
+export declare function isAgentPluginName({ value }: {
+    readonly value: unknown;
+}, _optional?: Record<string, never>): boolean;
 export interface AgentPluginManifest {
     readonly name: string;
     readonly version?: (string) | undefined;
@@ -19,6 +28,10 @@ export interface AgentPluginManifest {
     /** Normalized publisher identity, independent of name/storage key and version. */
     readonly id?: string | undefined;
     readonly provides?: readonly string[] | undefined;
+    /** `extensions.<ns>.requires`: advisory capability ids other active plugins should provide. */
+    readonly requires?: readonly string[] | undefined;
+    /** `extensions.<ns>.hostRange`: semver range over AGENT_PLUGIN_CONTRACT_VERSION; a malformed value is stored as `<invalid>`. */
+    readonly hostRange?: string | undefined;
 }
 export type ParseAgentPluginManifestResult = {
     readonly ok: true;