@jini-ai/agent-plugins 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.5 — 2026-10-12 — retirement waits for usable successors
+
+- `retireBundledAgentPlugins()` (and so the boot seeder) keeps a retired bundled plugin until EVERY
+  successor is installed at the digest `bundled-digests.json` records for it. Before, a successor
+  whose seed had failed still got an activation record and the predecessor was removed — a switch
+  with no code behind it. The kept plugin's outcome is `failed` with the reason; the next boot retries.
+- `retiredBundledPlugins` (and the `retired` option) may list several successors for a plugin split
+  across them; such outcomes carry `successorIds` and, when retired, per-successor `successors`.
+  Single-successor outcomes are unchanged.
+
 ## 0.4.4 — 2026-10-12 — Agent Plugins 1.1.0
 
 - `parseAgentPluginManifest()` / `parseAgentPluginMcpConfig()` (and so the installer and MCP

package/dist/lifecycle/ports.d.ts

@@ -66,7 +66,8 @@ export interface AgentPluginLifecyclePorts {
         readonly pluginId: string;
     }) => string;
     readonly seededEnabledPluginIds: ReadonlySet<string>;
-    readonly retiredBundledPlugins: ReadonlyMap<string, string>;
+    /** Retired bundled plugin id -> the bundled plugin(s) that absorbed it (`retire-bundled.ts`). */
+    readonly retiredBundledPlugins: ReadonlyMap<string, string | readonly string[]>;
     readonly bundledArchiveMagic: string;
     readonly filesystem: FilesystemPort;
     readonly clock: AgentPluginClockPort;

package/dist/lifecycle/retire-bundled.d.ts

@@ -19,6 +19,14 @@
  * ---------------------------------------------------------------------------
  * 1. Nothing installed and no activation record: nothing to do (the second boot after a migration).
  *    A leftover ledger entry is still dropped.
+ * 1a. Otherwise EVERY successor must be usable first: installed at the digest `bundled-digests.json`
+ *    records for it (the build's own seed — the same trust `trusted-plugin-files.ts` demands before
+ *    core takes a contribution from it), whether it seeded this boot or on an earlier one. If any
+ *    is not, the retired plugin is KEPT and the outcome is `failed` with the reason; the next boot
+ *    retries. Without this a successor whose seed failed (a broken `plugin.json`, a full disk) left
+ *    the retired plugin removed and only an activation record for the successor — a switch with no
+ *    code behind it (R6, 2026-10-12). A plugin split into several (`deploy` -> `fly`, `render`, ...)
+ *    is kept until all of them are usable: one working successor must not cost the others' capability.
  * 2. The retired plugin was ENABLED (explicitly, or by the "absent means active" default while its
  *    package is installed): the successor is switched on — unless an operator explicitly turned the
  *    successor off, which is left exactly as it is and reported in the outcome. No silent override.
@@ -47,13 +55,17 @@ import type { AgentPluginLifecyclePorts } from "./ports.js";
 /** What happened to the successor. `not-needed`: the retired plugin was off, so the successor was
  *  left as it was. The other three are {@link BundledAgentPluginEnableOutcome}. */
 export type RetiredAgentPluginSuccessorOutcome = BundledAgentPluginEnableOutcome | "not-needed";
-export type RetiredAgentPluginOutcome = {
-    readonly pluginId: string;
+/** `successorId` is the (first) successor; `successorIds` is present only when the map entry lists
+ *  several, and then names every one in map order. */
+interface RetiredAgentPluginSuccessors {
     readonly successorId: string;
+    readonly successorIds?: readonly string[] | undefined;
+}
+export type RetiredAgentPluginOutcome = (RetiredAgentPluginSuccessors & {
+    readonly pluginId: string;
     readonly status: "absent";
-} | {
+}) | (RetiredAgentPluginSuccessors & {
     readonly pluginId: string;
-    readonly successorId: string;
     readonly status: "retired";
     /** Every installed archive digest removed; empty when only a record or ledger entry was left. */
     readonly removedDigests: readonly string[];
@@ -62,24 +74,27 @@ export type RetiredAgentPluginOutcome = {
     /** `left-disabled-by-operator` is the one case a caller should surface: the retired plugin was
      *  on, its successor was explicitly turned off, and this step did not override that. */
     readonly successor: RetiredAgentPluginSuccessorOutcome;
-} | {
+    /** Present only with `successorIds`: each successor's own outcome. `successor` is the first's. */
+    readonly successors?: Readonly<Record<string, RetiredAgentPluginSuccessorOutcome>> | undefined;
+}) | (RetiredAgentPluginSuccessors & {
     readonly pluginId: string;
-    readonly successorId: string;
     readonly status: "failed";
     readonly reason: string;
-};
+});
 export interface RetireBundledAgentPluginsRequired {
     /** The INSTANCE-level layout, for the same reason `seed-bundled.ts` takes one. */
     readonly layout: AgentPluginLayout;
     readonly workspaceId: string;
 }
 export interface RetireBundledAgentPluginsOptional {
-    /** Defaults to {@link RETIRED_BUNDLED_AGENT_PLUGINS}; tests pass their own. */
-    readonly retired?: (ReadonlyMap<string, string>) | undefined;
+    /** Defaults to the host's `retiredBundledPlugins` port; tests pass their own. A value lists
+     *  several successors when the retired plugin was split across them. */
+    readonly retired?: (ReadonlyMap<string, string | readonly string[]>) | undefined;
     readonly now?: ((required: Record<string, never>) => Date) | undefined;
 }
 /** Internal composition; one state/queue instance per injected host context. */
 export declare function createRetireBundledModule(ports: AgentPluginLifecyclePorts): {
     retireBundledAgentPlugins: (required: RetireBundledAgentPluginsRequired, optional?: RetireBundledAgentPluginsOptional) => Promise<readonly RetiredAgentPluginOutcome[]>;
 };
+export {};
 //# sourceMappingURL=retire-bundled.d.ts.map

package/dist/lifecycle/retire-bundled.js

@@ -4,7 +4,7 @@ import { createResolveAgentPluginRefsModule } from "./resolve-agent-plugin-refs.
 import { createUninstallModule } from "./uninstall.js";
 function buildModule(ports) {
     const { deleteAgentPluginActivation, enableBundledAgentPluginUnlessOperatorDisabled, readAgentPluginActivations, resolveAgentPluginActivation } = createActivationModule(ports);
-    const { removeBundledAgentPluginDigest } = createBundledDigestsModule(ports);
+    const { readBundledAgentPluginDigests, removeBundledAgentPluginDigest } = createBundledDigestsModule(ports);
     const { listInstalledPlugins } = createResolveAgentPluginRefsModule(ports);
     const { uninstallAgentPlugin } = createUninstallModule(ports);
     /**
@@ -16,41 +16,54 @@ function buildModule(ports) {
    */
     async function retireBundledAgentPlugins(required, optional = {}) {
         const outcomes = [];
-        for (const [pluginId, successorId] of optional.retired ?? ports.retiredBundledPlugins) {
+        for (const [pluginId, successor] of optional.retired ?? ports.retiredBundledPlugins) {
+            const successorIds = typeof successor === "string" ? [successor] : successor;
+            const ids = { successorId: successorIds[0] ?? "", ...(typeof successor === "string" ? {} : { successorIds }) };
             try {
-                outcomes.push(await retireOne(required, optional, pluginId, successorId));
+                outcomes.push(await retireOne(required, optional, pluginId, ids));
             }
             catch (error) {
-                outcomes.push({ pluginId, successorId, status: "failed", reason: error instanceof Error ? error.message : String(error) });
+                outcomes.push({ pluginId, ...ids, status: "failed", reason: error instanceof Error ? error.message : String(error) });
             }
         }
         return outcomes;
     }
     // The successor first: if a later step fails, the operator keeps the capability, and the next boot
     // (which finds this step already done) retries only what is left.
-    async function retireOne(required, optional, pluginId, successorId) {
+    async function retireOne(required, optional, pluginId, ids) {
         const workspaceLayout = required.layout.forWorkspace({ workspaceId: required.workspaceId });
         const workspaceRoot = workspaceLayout.root;
+        const successorIds = ids.successorIds ?? [ids.successorId];
         const verdict = await resolveAgentPluginActivation(workspaceRoot, pluginId);
         if (verdict.verdict === "undetermined") {
-            return { pluginId, successorId, status: "failed", reason: `cannot tell whether '${pluginId}' was enabled: ${verdict.reason}` };
+            return { pluginId, ...ids, status: "failed", reason: `cannot tell whether '${pluginId}' was enabled: ${verdict.reason}` };
         }
-        const installed = (await listInstalledPlugins(workspaceLayout.root)).filter((plugin) => plugin.pluginId === pluginId);
+        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, successorId, status: "absent" };
-            return { pluginId, successorId, status: "retired", removedDigests: [], activationRemoved: false, ledgerEntryRemoved, successor: "not-needed" };
+                return { pluginId, ...ids, status: "absent" };
+            return { pluginId, ...ids, status: "retired", removedDigests: [], activationRemoved: false, ledgerEntryRemoved, successor: "not-needed", ...(ids.successorIds ? { successors: {} } : {}) };
         }
-        const successor = verdict.verdict === "active"
-            ? await enableBundledAgentPluginUnlessOperatorDisabled({
-                workspaceRoot,
-                pluginId: successorId,
-                actor: `system:retire-${pluginId}`,
-                ...(optional.now !== undefined ? { now: optional.now } : {}),
-            })
-            : "not-needed";
+        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 successor = successors[ids.successorId] ?? "not-needed";
         let removedDigests = [];
         if (installed.length > 0) {
             removedDigests = (await uninstallAgentPlugin({ layout: required.layout, workspaceId: required.workspaceId, pluginId }, { retiredBundled: true })).removedDigests;
@@ -59,7 +72,22 @@ function buildModule(ports) {
             await deleteAgentPluginActivation({ workspaceRoot, pluginId });
         }
         const ledgerEntryRemoved = await removeBundledAgentPluginDigest({ workspaceRoot, pluginId });
-        return { pluginId, successorId, status: "retired", removedDigests, activationRemoved: hasRecord, ledgerEntryRemoved, successor };
+        return { pluginId, ...ids, status: "retired", removedDigests, activationRemoved: hasRecord, ledgerEntryRemoved, successor, ...(ids.successorIds ? { 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. */
+    async function unusableSuccessor(workspaceRoot, allInstalled, successorIds) {
+        const ledger = await readBundledAgentPluginDigests(workspaceRoot);
+        for (const successorId of successorIds) {
+            const digest = ledger.get(successorId);
+            if (digest === undefined)
+                return `successor '${successorId}' has never been seeded into this workspace`;
+            if (!allInstalled.some((plugin) => plugin.pluginId === successorId && plugin.archiveDigest === digest)) {
+                return `successor '${successorId}' is not installed at its seeded digest`;
+            }
+        }
+        return undefined;
     }
     return { retireBundledAgentPlugins };
 }

package/dist/lifecycle/seed-bundled.js

@@ -115,6 +115,8 @@ function buildModule(ports) {
     // once its bytes are actually on disk for this workspace.
     // AFTER seeding and the ledger: a retired plugin's successor is itself bundled, so its record and
     // its ledger entry exist by now, and the retirement only has to decide whether to switch it on.
+    // A successor whose seed FAILED has neither; `retire-bundled.ts` then keeps the retired plugin
+    // rather than remove it in favour of a switch with no code behind it (its header, step 1a).
     async function seedBundledAgentPlugins(required) {
         const { layout, workspaceId, sourceRoot } = required;
         const pluginDirNames = await listBundledPluginDirs(sourceRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agent-plugins",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Support for Agent Plugins, the open, vendor-neutral spec (v1.0.0, published 2026-08-06; v1.1.0 and later 1.x manifests are also accepted; Technical Steering Committee with maintainers from Amazon, Cursor, Google, Microsoft, OpenAI, and Vercel) for bundling Agent Skills and MCP servers into one portable directory: PluginManifest/McpManifest types + structural validators on the package root, plus the bundled plugins themselves, each on a subpath named for itself (./ui-ux-design). Extracted 2026-08-18 from @jini-ai/plugins, which now only reserves the unrelated, unimplemented ./host format.",
   "license": "Apache-2.0",
   "repository": {